Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python

Keep auto-parked finite shell jobs awaitable

justrach7342d464393d
diff --git a/docs/adr/0152-persistent-shells-snapshot-once.md b/docs/adr/0152-persistent-shells-snapshot-once.md
index e458e310..82afa1dc 100644
--- a/docs/adr/0152-persistent-shells-snapshot-once.md
+++ b/docs/adr/0152-persistent-shells-snapshot-once.md
@@ -30,3 +30,13 @@ A `wait_ms: 30000` call on a server returns now, not in 30s, so the 15s
pulse cannot fire. A model that wanted "sleep 1s then snapshot startup
logs" no longer can through `wait_ms`; it snapshots now and reads again
later if needed. Finite CI watches are unchanged.
+
+## Amendment (#1324, 2026-09-27)
+
+Auto-parking a command no longer makes it persistent by itself. Finite
+commands that outlive the foreground wait (`cargo test`, `sleep 45`, a CI
+watch) were snapshotting on `action=output wait_ms>0`, contradicting the
+tool contract. `job_class.looksPersistent` now decides: dev servers,
+watchers, followed logs, foreground `compose up` and tunnels park as
+persistent; every other auto-parked command stays finite and keeps the
+ADR 0010 wait. `run_in_background` jobs remain persistent.
diff --git a/src/exec_bash.zig b/src/exec_bash.zig
index 3832104c..bf6eaefc 100644
--- a/src/exec_bash.zig
+++ b/src/exec_bash.zig
@@ -75,15 +75,21 @@ fn spawnFailText(gpa: Allocator, err: anyerror) ![]u8 {
try std.fmt.allocPrint(gpa, "could not start background job ({t}) — run it in the foreground instead", .{err});
}
-fn startedText(gpa: Allocator, id: u64, cmd: []const u8, ssh: bool, auto_bg: bool, wait_s: u64, partial: []const u8) ![]u8 {
+/// How a job got to the background: started there, or parked after the
+/// foreground wait as a server-like or a finite command (#1324).
+const Started = enum { background, server, finite };
+
+fn startedText(gpa: Allocator, id: u64, cmd: []const u8, ssh: bool, how: Started, wait_s: u64, partial: []const u8) ![]u8 {
var aw: Io.Writer.Allocating = .init(gpa);
errdefer aw.deinit();
const w = &aw.writer;
try w.print("[job {d} started: {s}]\n", .{ id, cmd });
if (@import("job_wait.zig").followup_pending.load(.acquire)) {
try w.print("Follow-up received while this was running; it was moved to the background so you can talk. Process is still running as job {d}. You are notified on exit — do not poll. action=output is a snapshot; action=kill stops it.", .{id});
- } else if (auto_bg) {
+ } else if (how == .server) {
try w.print("Command exceeded the {d}s foreground wait and was automatically moved to the background. Process is still running as job {d}. You are notified on exit with the status and output — do not poll. action=output is a snapshot; leave it on /jobs or action=kill it.", .{ wait_s, id });
+ } else if (how == .finite) {
+ try w.print("Command exceeded the {d}s foreground wait and was automatically moved to the background. Process is still running as job {d}. You are notified on exit with the status and output. To block until it finishes instead, call action=output id {d} with wait_ms>0 once; action=kill stops it.", .{ wait_s, id, id });
} else {
try w.print("This is a persistent server. It runs in the background across turns. You are notified on exit — do not poll. action=output id {d} reads unread output. action=kill stops it.", .{id});
}
@@ -239,19 +245,28 @@ test "cancel hint tells the model to restart with run_in_background" {
try std.testing.expect(std.mem.indexOf(u8, cancel_hint, "run_in_background") != null);
}
-test "auto-promoted jobs snapshot instead of inheriting wait-until-exit" {
+test "an auto-parked server snapshots instead of inheriting wait-until-exit" {
const gpa = std.testing.allocator;
- const text = try startedText(gpa, 7, "find /", false, true, 15, "partial");
+ const text = try startedText(gpa, 7, "npm run dev", false, .server, 15, "partial");
defer gpa.free(text);
try std.testing.expect(std.mem.indexOf(u8, text, "do not poll") != null);
try std.testing.expect(std.mem.indexOf(u8, text, "snapshot") != null);
- try std.testing.expect(std.mem.indexOf(u8, text, "waits until it exits") == null);
+ try std.testing.expect(std.mem.indexOf(u8, text, "wait_ms>0") == null);
try std.testing.expect(std.mem.indexOf(u8, text, "job 7") != null);
}
+test "an auto-parked finite command offers the wait-until-exit read (#1324)" {
+ const gpa = std.testing.allocator;
+ const text = try startedText(gpa, 8, "cargo test", false, .finite, 15, "");
+ defer gpa.free(text);
+ try std.testing.expect(std.mem.indexOf(u8, text, "action=output id 8 with wait_ms>0") != null);
+ try std.testing.expect(std.mem.indexOf(u8, text, "snapshot") == null);
+ try std.testing.expect(std.mem.indexOf(u8, text, "persistent server") == null);
+}
+
test "persistent start text parks the server and forbids polling" {
const gpa = std.testing.allocator;
- const text = try startedText(gpa, 446, "npm run dev", false, false, 0, "");
+ const text = try startedText(gpa, 446, "npm run dev", false, .background, 0, "");
defer gpa.free(text);
try std.testing.expect(std.mem.indexOf(u8, text, "[job 446 started: npm run dev]") != null);
try std.testing.expect(std.mem.indexOf(u8, text, "persistent server") != null);
@@ -356,7 +371,7 @@ fn execUnchecked(ctx: ToolCtx, call: tools.ToolCall) !ToolOutput {
}) catch |err| return .{ .text = try spawnFailText(gpa, err), .is_error = true };
if (bg) {
@import("subagent_interactive.zig").request(ctx);
- return .{ .text = try startedText(gpa, job.id, job.cmd, ssh, false, 0, ""), .pending = true };
+ return .{ .text = try startedText(gpa, job.id, job.cmd, ssh, .background, 0, ""), .pending = true };
}
const wait_ms = rootWaitMsFor(input, ctx.interactive_children);
const waited = jobs.waitForeground(gpa, io, job.id, wait_ms) catch |err| return .{
@@ -370,9 +385,12 @@ fn execUnchecked(ctx: ToolCtx, call: tools.ToolCall) !ToolOutput {
},
.running => |r| blk: {
defer gpa.free(r.output);
- jobs.markPersistent(io, r.id);
+ // #1324: only a server-like command parks as persistent; a
+ // finite one keeps the wait-until-exit `action=output`.
+ const server = @import("job_class.zig").looksPersistent(cmd);
+ if (server) jobs.markPersistent(io, r.id);
@import("subagent_interactive.zig").request(ctx);
- break :blk .{ .text = try startedText(gpa, r.id, cmd, ssh, true, wait_ms / 1000, r.output), .pending = true };
+ break :blk .{ .text = try startedText(gpa, r.id, cmd, ssh, if (server) .server else .finite, wait_ms / 1000, r.output), .pending = true };
},
.cancelled => |c| blk: {
defer jobs.reapFinished(gpa, io, c.id);
diff --git a/src/job_class.zig b/src/job_class.zig
new file mode 100644
index 00000000..3d065579
--- /dev/null
+++ b/src/job_class.zig
@@ -0,0 +1,158 @@
+//! Whether a foreground command that outlived its wait is a server (#1324).
+//!
+//! A command auto-parked after the foreground wait used to become a
+//! persistent job unconditionally, so `action=output wait_ms>0` on a
+//! `cargo test` or `sleep 45` snapshotted at once instead of waiting for
+//! exit. Only commands that look like they keep running on purpose (dev
+//! servers, watchers, followed logs, foreground containers, tunnels) park as
+//! persistent now; everything else stays a finite job (ADR 0010 waits).
+//! `run_in_background` jobs are persistent by the caller's choice, not here.
+
+const std = @import("std");
+
+/// Programs that serve until stopped whatever their arguments.
+const server_programs = [_][]const u8{
+ "uvicorn", "gunicorn", "hypercorn", "daphne", "nodemon",
+ "live-server", "http-server", "browser-sync", "ngrok", "cloudflared",
+ "caddy", "nginx", "redis-server", "mongod", "postgres",
+ "ollama", "mailhog", "localstack", "json-server", "air",
+};
+
+/// Subcommands that run a server or watcher for tools that also do finite work.
+const server_verbs = [_][2][]const u8{
+ .{ "npm", "start" }, .{ "npm", "dev" }, .{ "npm", "serve" },
+ .{ "yarn", "start" }, .{ "yarn", "dev" }, .{ "yarn", "serve" },
+ .{ "pnpm", "start" }, .{ "pnpm", "dev" }, .{ "pnpm", "serve" },
+ .{ "bun", "dev" }, .{ "bun", "start" }, .{ "next", "dev" },
+ .{ "next", "start" }, .{ "vite", "dev" }, .{ "vite", "preview" },
+ .{ "astro", "dev" }, .{ "nuxt", "dev" }, .{ "remix", "dev" },
+ .{ "wrangler", "dev" }, .{ "vercel", "dev" }, .{ "netlify", "dev" },
+ .{ "hugo", "server" }, .{ "jekyll", "serve" }, .{ "mkdocs", "serve" },
+ .{ "flask", "run" }, .{ "rails", "s" }, .{ "rails", "server" },
+ .{ "manage.py", "runserver" }, .{ "cargo", "watch" }, .{ "webpack", "serve" },
+ .{ "storybook", "dev" }, .{ "firebase", "serve" }, .{ "supabase", "start" },
+ .{ "kubectl", "port-forward" }, .{ "minikube", "tunnel" }, .{ "graff", "serve" },
+ .{ "tailscale", "serve" }, .{ "deno", "serve" },
+};
+
+const ws = " \t\r\n";
+
+/// True when `cmd` looks like it keeps running until stopped.
+pub fn looksPersistent(cmd: []const u8) bool {
+ var segments = std.mem.tokenizeAny(u8, cmd, ";&|\n");
+ while (segments.next()) |segment| if (segmentPersistent(segment)) return true;
+ return false;
+}
+
+fn segmentPersistent(segment: []const u8) bool {
+ var words: [32][]const u8 = undefined;
+ var n: usize = 0;
+ var it = std.mem.tokenizeAny(u8, segment, ws);
+ while (it.next()) |word| {
+ if (n == words.len) break;
+ words[n] = std.mem.trim(u8, word, "\"'()");
+ n += 1;
+ }
+ const w = words[0..n];
+ var command_pos = true;
+ for (w, 0..) |word, i| {
+ const at_command = command_pos;
+ command_pos = std.mem.indexOfScalar(u8, word, '=') != null and at_command or isWrapper(word);
+ if (std.mem.eql(u8, word, "--watch") or std.mem.eql(u8, word, "--serve")) return true;
+ if (std.mem.eql(u8, word, "-f") or std.mem.eql(u8, word, "-F") or std.mem.eql(u8, word, "--follow")) {
+ if (hasProgram(w[0..i], "tail") or hasProgram(w[0..i], "journalctl") or hasWord(w[0..i], "logs")) return true;
+ }
+ const base = std.fs.path.basename(word);
+ if (at_command) for (server_programs) |p| if (std.mem.eql(u8, base, p)) return true;
+ if (i > 0 and std.mem.eql(u8, w[i - 1], "-m")) for (server_programs) |p| if (std.mem.eql(u8, word, p)) return true;
+ for (server_verbs) |v| if (std.mem.eql(u8, base, v[0]) and followedBy(w[i + 1 ..], v[1])) return true;
+ if (std.mem.eql(u8, base, "vite") and (i + 1 == w.len or std.mem.startsWith(u8, w[i + 1], "-"))) return true;
+ if (std.mem.eql(u8, word, "http.server")) return true;
+ if (std.mem.eql(u8, base, "php") and i + 1 < w.len and std.mem.eql(u8, w[i + 1], "-S")) return true;
+ if (std.mem.eql(u8, word, "up") and (hasProgram(w[0..i], "docker-compose") or hasWord(w[0..i], "compose")) and !hasWord(w[i + 1 ..], "-d") and !hasWord(w[i + 1 ..], "--detach")) return true;
+ }
+ return false;
+}
+
+/// `verb` appears among the next few words, skipping `run` and flags
+/// (`npm run dev`, `pnpm --filter web dev`, `python manage.py runserver`).
+fn followedBy(rest: []const []const u8, verb: []const u8) bool {
+ for (rest[0..@min(rest.len, 4)]) |word| {
+ if (std.mem.eql(u8, word, verb)) return true;
+ }
+ return false;
+}
+
+/// Words after which the next word is still the program being run.
+fn isWrapper(word: []const u8) bool {
+ for ([_][]const u8{ "sudo", "exec", "nohup", "time", "env", "npx", "bunx", "uvx", "command", "nice" }) |w|
+ if (std.mem.eql(u8, word, w)) return true;
+ return false;
+}
+
+fn hasWord(words: []const []const u8, word: []const u8) bool {
+ for (words) |w| if (std.mem.eql(u8, w, word)) return true;
+ return false;
+}
+
+fn hasProgram(words: []const []const u8, program: []const u8) bool {
+ for (words) |w| if (std.mem.eql(u8, std.fs.path.basename(w), program)) return true;
+ return false;
+}
+
+test "finite commands from the reports stay finite (#1324, #1325, #1331)" {
+ for ([_][]const u8{
+ "sleep 45",
+ "cargo test --workspace 2>&1 | tee /tmp/t.log; status=${PIPESTATUS[0]}; tail -n 40 /tmp/t.log; exit $status",
+ "zig build test",
+ "npm test",
+ "npm run build",
+ "pnpm install",
+ "gh run watch 123 --exit-status",
+ "vite build",
+ "docker compose up -d",
+ "docker compose logs web",
+ "make -j8",
+ "python -m pytest -x",
+ "git log --follow src/main.zig | head",
+ "tail -n 20 build.log",
+ "grep -rn nginx deploy/",
+ "echo postgres is up",
+ }) |cmd| {
+ if (looksPersistent(cmd)) {
+ std.debug.print("classified as persistent: {s}\n", .{cmd});
+ return error.TestUnexpectedResult;
+ }
+ }
+}
+
+test "servers, watchers and followed logs park as persistent" {
+ for ([_][]const u8{
+ "npm run dev",
+ "cd web && pnpm dev",
+ "yarn start",
+ "next dev --port 3777",
+ "vite",
+ "npx vite --host",
+ "python -m http.server 8000",
+ "python manage.py runserver",
+ "uvicorn app:app --reload",
+ "tail -f /var/log/app.log",
+ "docker compose up",
+ "docker compose logs -f web",
+ "cargo watch -x test",
+ "tsc --watch",
+ "php -S localhost:8000",
+ "flask run",
+ "kubectl port-forward svc/api 8080:80",
+ "graff serve",
+ "PORT=3000 nohup uvicorn app:app",
+ "python -m uvicorn app:app",
+ "journalctl -u api -f",
+ }) |cmd| {
+ if (!looksPersistent(cmd)) {
+ std.debug.print("classified as finite: {s}\n", .{cmd});
+ return error.TestUnexpectedResult;
+ }
+ }
+}
diff --git a/src/main.zig b/src/main.zig
index 448a6f04..0d72c972 100644
--- a/src/main.zig
+++ b/src/main.zig
@@ -579,7 +579,7 @@ test { // ── Unit tests (`zig build test`): pull in tests from imported modu
_ = .{ @import("http2_pool.zig"), @import("agent_stream_h2.zig"), @import("agent_stream_h2_transport_test.zig") }; // h2 stream path, and graff's request/response contract over the pinned http-zig
_ = @import("tui_acp_updates.zig");
_ = @import("acp_preauth.zig"); // credential-free ACP loop must stay in the test root
- _ = .{ @import("acp_protocol.zig"), @import("acp_v2.zig"), @import("acp_v2_prompt.zig"), @import("acp_elicit.zig"), @import("ask_user_args.zig"), @import("acp_engine_test.zig"), @import("subagent_mimo_tests.zig"), @import("mimo_effort_tests.zig"), @import("gateway_picker_catalog.zig") };
+ _ = .{ @import("acp_protocol.zig"), @import("acp_v2.zig"), @import("acp_v2_prompt.zig"), @import("acp_elicit.zig"), @import("ask_user_args.zig"), @import("job_class.zig"), @import("acp_engine_test.zig"), @import("subagent_mimo_tests.zig"), @import("mimo_effort_tests.zig"), @import("gateway_picker_catalog.zig") };
_ = @import("task_outcome.zig"); // goal-outcome telemetry events
_ = @import("learn_delete.zig"); // #303: its tests were dead until listed here
_ = .{ @import("additional_tests.zig"), @import("req_stats.zig"), @import("exact_reply.zig"), @import("rlm_order_tests.zig"), @import("async_tool_policy.zig"), @import("agent_async_tools.zig"), @import("request_usage_attempts.zig"), @import("learn_formal.zig") };