graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
repl: name parked background work and say the session continues
justrach97666b77e54b
diff --git a/docs/adr/0247-parked-work-is-named-above-the-prompt.md b/docs/adr/0247-parked-work-is-named-above-the-prompt.mdnew file mode 100644index 00000000..5db44b62--- /dev/null+++ b/docs/adr/0247-parked-work-is-named-above-the-prompt.md@@ -0,0 +1,37 @@+# 0247. Parked work is named above the prompt++Status: accepted 2026-10-03++## Context++ADR 0154 parks a shell command that outlives the interactive foreground wait+and hands the prompt back; the command's exit wakes the session, which then+continues on its own. The yield printed one generic line ("Background work+continues separately…") and returned to `›`. It never said what was running+or that the session would resume by itself, so a parked turn read as graff+stopping mid-task, with an unfinished checklist still drawn above the prompt.++## Decision++- `background_wait` names the live work whose exit wakes the session: running+ shell jobs that will post an exit notice and this session's unfinished+ agents. A command is shown as its first line, clipped; finite work leads and+ the rest are counted ("zig build and 2 more"). Job ids stay out: they are+ session handles the model already has from the tool result.+- The standing block above `›` draws `↻ waiting on <work> — graff continues+ when it finishes` whenever such work is running, below the checklist or on+ its own, on every prompt redraw.+- The yield itself prints only what that line will not say: a persistent+ server never exits to wake the session, so it is named as running in the+ background with no promise to continue. The recorded turn result names the+ work either way.+- A wake that resumes the session prints `↻ <command> exited 0 — continuing`+ (or killed / stopped idle / `agent N completed`) before the turn runs.++ACP sessions are unattended and never yield (ADR 0154), so nothing changes+there.++## Consequences++One extra line above `›` while parked work runs, and one when it resumes. The+model-facing tool results and wake notices are unchanged.diff --git a/docs/adr/README.md b/docs/adr/README.mdindex 2e0095a7..4f9d59e8 100644--- a/docs/adr/README.md+++ b/docs/adr/README.md@@ -273,6 +273,7 @@ record only when you need the evidence or the edge cases.| [0244](0244-saved-workspaces-have-durable-discovery.md) | Remember saved workspace roots locally; remote picker targets are workspace-qualified, and resume must enter the selected tree before restoring it. || [0245](0245-fullscreen-tui-is-an-external-client.md) | The fullscreen UI is maintained separately; `graff tui` launches installed `graff-tui` before engine startup, sibling first then PATH, without downloading. TTY `graff repl` uses the line REPL. Supersedes 0041, 0042 and the fullscreen portion of 0142. || [0246](0246-jev-picks-each-turns-effort-alongside-the-first-request.md) | On an eligible model at the default effort, graff asks Jev for the turn's effort alongside the first request; the pick applies from the next request, holds for that turn, is never saved, and never overrides a user's effort. `chatgpt-new` GPT-6 models are eligible. |+| [0247](0247-parked-work-is-named-above-the-prompt.md) | A parked turn names the work it waits on: the standing block draws `↻ waiting on <work> — graff continues when it finishes` while a job or agent that will wake the session runs, the yield prints only for a server, and a wake prints what finished before continuing. |## When to write onediff --git a/src/agent_prompt.zig b/src/agent_prompt.zigindex 9d38e849..4cbc9f8d 100644--- a/src/agent_prompt.zig+++ b/src/agent_prompt.zig@@ -99,6 +99,11 @@ fn standing(self: *const Agent) engine_events.StandingWork {}out.todos = items.items;out.image = self.pending_image != null;+ // ADR 0247: a parked turn resumes when this work exits; say so above `›`.+ if (self.arena.alloc(u8, 160)) |buf| {+ const w = @import("background_wait.zig").describe(self.io, buf);+ if (w.wakes) out.waiting = w.text;+ } else |_| {}return out;}diff --git a/src/agent_working.zig b/src/agent_working.zigindex d32b358a..4f3f1e74 100644--- a/src/agent_working.zig+++ b/src/agent_working.zig@@ -44,6 +44,8 @@ pub fn write(w: *Io.Writer, title: []const u8, items: []const Item) void {}pub fn writeFromStanding(w: *Io.Writer, st: engine_events.StandingWork) void {+ // Below the checklist, or alone: a parked turn is still working (ADR 0247).+ defer writeWaiting(w, st.waiting);// Keep completed history, but do not redraw a finished checklist as WORKING.// Use the full counts: an open item may be beyond the displayed slice.if (st.todos_total > 0 and st.todos_done == st.todos_total) return;@@ -55,6 +57,13 @@ pub fn writeFromStanding(w: *Io.Writer, st: engine_events.StandingWork) void {write(w, st.goal, buf[0..n]);}+/// ADR 0247: the prompt is back but the task is not over. Names the work the+/// session waits on so the `›` below it does not read as graff having stopped.+fn writeWaiting(w: *Io.Writer, waiting: []const u8) void {+ if (waiting.len == 0) return;+ w.print("↻ waiting on {s} — graff continues when it finishes\n", .{waiting}) catch return;+}+/// Parse the model's todo_write dump (`[x]` / `[~]` / `[ ]` lines) into the/// same block. Unknown lines are ignored so a stray sentence cannot appear.pub fn writeFromTodoText(w: *Io.Writer, title: []const u8, text: []const u8) void {@@ -139,3 +148,28 @@ test "writeFromStanding uses the goal title and active/done marks" {aw.writer.buffered(),);}++test "ADR 0247: a parked turn says what it waits on, with or without a checklist" {+ var aw: Io.Writer.Allocating = .init(std.testing.allocator);+ defer aw.deinit();+ const items = [_]engine_events.StandingTodo{+ .{ .content = "inspect", .done = true },+ .{ .content = "configure inbound replies", .active = true },+ };+ writeFromStanding(&aw.writer, .{ .todos = &items, .todos_done = 1, .todos_total = 2, .waiting = "terraform plan" });+ try std.testing.expectEqualStrings(+ "WORKING work 1/2\n" +++ "├ ✓ inspect\n" +++ "└ ◌ configure inbound replies\n" +++ "↻ waiting on terraform plan — graff continues when it finishes\n",+ aw.written(),+ );+ aw.clearRetainingCapacity();+ // A finished checklist stays hidden, but the wait does not.+ const finished = [_]engine_events.StandingTodo{.{ .content = "inspect", .done = true }};+ writeFromStanding(&aw.writer, .{ .todos = &finished, .todos_done = 1, .todos_total = 1, .waiting = "zig build" });+ try std.testing.expectEqualStrings("↻ waiting on zig build — graff continues when it finishes\n", aw.written());+ aw.clearRetainingCapacity();+ writeFromStanding(&aw.writer, .{ .waiting = "agent 4" });+ try std.testing.expectEqualStrings("↻ waiting on agent 4 — graff continues when it finishes\n", aw.written());+}diff --git a/src/background_wait.zig b/src/background_wait.zignew file mode 100644index 00000000..0bf7d202--- /dev/null+++ b/src/background_wait.zig@@ -0,0 +1,196 @@+//! What a parked turn is waiting on (ADR 0247): the running shell jobs and+//! background agents whose exit wakes the session (ADR 0154), named for the+//! yield notice and for the standing block above `›`. Without a name the+//! yield read as graff stopping mid-task. A persistent server never exits to+//! wake anything, so it is named only when nothing finite is left, and never+//! with a promise to continue.++const std = @import("std");+const Io = std.Io;++const util = @import("util.zig");++pub const Waiting = struct {+ /// "zig build test", "zig build and 2 more", "agent 2". Empty when+ /// nothing is running. Job ids stay out: they are session handles the+ /// model reads off the tool result, noise on a line meant for people.+ text: []const u8 = "",+ /// Something finite is running: its exit resumes the session on its own.+ wakes: bool = false,+};++pub const Shell = struct { id: u64, cmd: []const u8, persistent: bool = false };++const cmd_clip: usize = 48;++/// The command as one short line: its first non-blank line, clipped.+fn shortCmd(cmd: []const u8) []const u8 {+ var lines = std.mem.splitScalar(u8, cmd, '\n');+ while (lines.next()) |raw| {+ const line = std.mem.trim(u8, raw, " \t\r");+ if (line.len > 0) return util.utf8Prefix(line, cmd_clip);+ }+ return "command";+}++/// True when shortCmd dropped anything: the rest of a long line, or more lines.+fn clipped(cmd: []const u8) bool {+ return shortCmd(cmd).len < std.mem.trim(u8, cmd, " \t\r\n").len;+}++/// Pure: name these live jobs and agents. Finite work leads; a persistent+/// server is named only when it is all there is.+pub fn label(buf: []u8, shells: []const Shell, agents: []const u32) Waiting {+ var finite: usize = 0;+ var first: ?Shell = null;+ var server: ?Shell = null;+ for (shells) |s| {+ if (s.persistent) {+ if (server == null) server = s;+ continue;+ }+ if (first == null) first = s;+ finite += 1;+ }+ var w: Io.Writer = .fixed(buf);+ const total = finite + agents.len;+ if (total == 0) {+ const s = server orelse return .{};+ w.print("{s}{s}", .{ shortCmd(s.cmd), if (clipped(s.cmd)) "…" else "" }) catch return .{ .text = "a background server" };+ return .{ .text = w.buffered() };+ }+ if (first) |s| {+ w.print("{s}{s}", .{ shortCmd(s.cmd), if (clipped(s.cmd)) "…" else "" }) catch return .{ .text = "background work", .wakes = true };+ } else {+ w.print("agent {d}", .{agents[0]}) catch return .{ .text = "a background agent", .wakes = true };+ }+ if (total > 1) w.print(" and {d} more", .{total - 1}) catch {};+ return .{ .text = w.buffered(), .wakes = true };+}++/// The live registries, read under their own locks one at a time: shell jobs+/// that will post an exit notice (not the foreground wait, not a job a+/// finished session detached) and this session's unfinished agents.+pub fn describe(io: Io, buf: []u8) Waiting {+ var agent_ids: [8]u32 = undefined;+ var n_agents: usize = 0;+ {+ const agents = &@import("subagent.zig").g_agent_jobs;+ agents.mutex.lockUncancelable(io);+ defer agents.mutex.unlock(io);+ for (agents.list.items) |job| {+ if (job.done or job.owner == null) continue;+ if (n_agents < agent_ids.len) {+ agent_ids[n_agents] = job.id;+ n_agents += 1;+ }+ }+ }+ var shells: [8]Shell = undefined;+ var n_shells: usize = 0;+ const jobs = &@import("jobs.zig").g_jobs;+ jobs.mutex.lockUncancelable(io);+ defer jobs.mutex.unlock(io);+ for (jobs.list.items) |job| {+ if (job.done or job.quiet or job.detach) continue;+ if (n_shells < shells.len) {+ shells[n_shells] = .{ .id = job.id, .cmd = job.cmd, .persistent = job.persistent };+ n_shells += 1;+ }+ }+ // Formatted under the jobs lock: the command bytes belong to the job.+ return label(buf, shells[0..n_shells], agent_ids[0..n_agents]);+}++/// The line that ends a parked turn (ADR 0154), plain text: it is also the+/// turn's recorded result.+pub fn yieldNotice(a: std.mem.Allocator, w: Waiting) ![]const u8 {+ if (w.wakes) return std.fmt.allocPrint(a, "Still running: {s}. graff continues when it finishes; the prompt is free meanwhile.", .{w.text});+ if (w.text.len > 0) return std.fmt.allocPrint(a, "{s} keeps running in the background. graff is waiting for your next message.", .{w.text});+ return a.dupe(u8, "Background work is running; graff continues when it reports. The prompt is free meanwhile.");+}++/// The line printed when a wake resumes a parked session: what finished, from+/// the wake's first line, without the job's session handle.+/// "[job 12 exited 0: zig build test]" reads "zig build test exited 0".+pub fn resumeLine(buf: []u8, wake: []const u8) []const u8 {+ const text = std.mem.trim(u8, wake, " \t\r\n");+ const first = std.mem.trim(u8, std.mem.sliceTo(text, '\n'), " \t\r");+ if (std.mem.startsWith(u8, text, "[job ")) {+ // "[job ID STATUS: CMD]", where a multi-line command spans lines.+ var close: ?usize = std.mem.indexOf(u8, text, "]\n");+ if (close == null and std.mem.endsWith(u8, text, "]")) close = text.len - 1;+ if (close) |c| {+ const body = text["[job ".len..c];+ if (std.mem.indexOfScalar(u8, body, ' ')) |after_id| {+ const rest = body[after_id + 1 ..];+ if (std.mem.indexOf(u8, rest, ": ")) |colon| {+ const cmd = rest[colon + 2 ..];+ return std.fmt.bufPrint(buf, "{s}{s} {s}", .{ shortCmd(cmd), if (clipped(cmd)) "…" else "", rest[0..colon] }) catch util.utf8Prefix(first, 72);+ }+ }+ }+ }+ if (std.mem.startsWith(u8, first, "[agent ")) {+ if (std.mem.indexOfScalar(u8, first, ']')) |close| return first[1..close];+ }+ return util.utf8Prefix(first, 72);+}++test "ADR 0247: a resumed session names what finished, not its handle" {+ var buf: [160]u8 = undefined;+ try std.testing.expectEqualStrings("zig build test exited 0", resumeLine(&buf, "[job 4294978433 exited 0: zig build test]\nAll 2 tests passed."));+ try std.testing.expectEqualStrings("next dev killed", resumeLine(&buf, "[job 7 killed: next dev]"));+ try std.testing.expectEqualStrings("python3 - <<'PY'… stopped idle", resumeLine(&buf, "[job 8 stopped idle: python3 - <<'PY'\nprint(1)\nPY]"));+ try std.testing.expectEqualStrings("agent 2 completed", resumeLine(&buf, "[agent 2 completed] Read its report with agent_output (no wait)."));+ try std.testing.expectEqualStrings("a scheduled check is due", resumeLine(&buf, "a scheduled check is due\nmore"));+}++test "ADR 0247: a parked command is named by its command line" {+ var buf: [128]u8 = undefined;+ const w = label(&buf, &.{.{ .id = 3, .cmd = "terraform plan -out=tf.plan" }}, &.{});+ try std.testing.expectEqualStrings("terraform plan -out=tf.plan", w.text);+ try std.testing.expect(w.wakes);+}++test "ADR 0247: more work is counted, agents too, and finite work leads" {+ var buf: [128]u8 = undefined;+ const shells = [_]Shell{+ .{ .id = 4, .cmd = "next dev", .persistent = true },+ .{ .id = 5, .cmd = "zig build test" },+ .{ .id = 6, .cmd = "gh run watch 123" },+ };+ const w = label(&buf, &shells, &.{2});+ try std.testing.expectEqualStrings("zig build test and 2 more", w.text);+ try std.testing.expect(w.wakes);+ const only_agents = label(&buf, &.{}, &.{ 7, 8 });+ try std.testing.expectEqualStrings("agent 7 and 1 more", only_agents.text);+ try std.testing.expect(only_agents.wakes);+}++test "ADR 0247: a server alone is named but never promised to wake the session" {+ var buf: [128]u8 = undefined;+ const w = label(&buf, &.{.{ .id = 4, .cmd = "next dev --port 3777", .persistent = true }}, &.{});+ try std.testing.expectEqualStrings("next dev --port 3777", w.text);+ try std.testing.expect(!w.wakes);+ const notice = try yieldNotice(std.testing.allocator, w);+ defer std.testing.allocator.free(notice);+ try std.testing.expect(std.mem.indexOf(u8, notice, "continues") == null);+ try std.testing.expect(std.mem.indexOf(u8, notice, "waiting for your next message") != null);+}++test "ADR 0247: long and multi-line commands shrink to one clipped line" {+ var buf: [128]u8 = undefined;+ const script = "python3 - <<'PY'\nimport json\nprint(1)\nPY";+ try std.testing.expectEqualStrings("python3 - <<'PY'…", label(&buf, &.{.{ .id = 9, .cmd = script }}, &.{}).text);+ const long = "bun run scripts/migrate-every-table-in-the-database.ts --all --verbose";+ const w = label(&buf, &.{.{ .id = 1, .cmd = long }}, &.{});+ try std.testing.expect(std.mem.endsWith(u8, w.text, "…"));+ try std.testing.expectEqual(@as(usize, 0), label(&buf, &.{}, &.{}).text.len);+}++test "ADR 0247: the yield notice says graff continues on its own" {+ const notice = try yieldNotice(std.testing.allocator, .{ .text = "zig build", .wakes = true });+ defer std.testing.allocator.free(notice);+ try std.testing.expectEqualStrings("Still running: zig build. graff continues when it finishes; the prompt is free meanwhile.", notice);+}diff --git a/src/engine_events.zig b/src/engine_events.zigindex be46836d..b714d8e7 100644--- a/src/engine_events.zig+++ b/src/engine_events.zig@@ -235,6 +235,7 @@ pub const StandingWork = struct {todos: []const StandingTodo = &.{},/// `/image` or Ctrl-V staged a picture for the next send.image: bool = false,+ waiting: []const u8 = "", // ADR 0247: live work whose exit resumes the session};/// Everything the status line printed before a human turn actually says.diff --git a/src/main.zig b/src/main.zigindex 6600cb72..799d6a5d 100644--- a/src/main.zig+++ b/src/main.zig@@ -593,7 +593,7 @@ test { // ── Unit tests (`zig build test`): pull in tests from imported modu_ = .{ @import("acp_agents.zig"), @import("repo_context_tests.zig") };_ = .{ @import("subagent_activity.zig"), @import("subagent_interactive.zig"), @import("subagent_recovery.zig"), @import("subagent_retained.zig"), @import("subagent_run_tests.zig") };_ = .{ @import("acp_agent_activity.zig"), @import("acp_subagent_live.zig"), @import("acp_line_writer.zig") };- _ = .{ @import("acp_replay.zig"), @import("python_version.zig"), @import("jev_auto.zig") };+ _ = .{ @import("acp_replay.zig"), @import("python_version.zig"), @import("jev_auto.zig"), @import("background_wait.zig") };_ = @import("read_image.zig");_ = .{ @import("pr_local_checks.zig"), @import("mcp_names.zig"), @import("workspace_history.zig"), @import("file_worktree.zig"), @import("mcp_turn_context.zig"), @import("review_deadline.zig"), @import("issue_cmd.zig"), @import("shell_tool.zig"), @import("acp_ask.zig"), @import("side_steer.zig"), @import("task_workspace_tests.zig"), @import("workspace_prepare_tests.zig"), @import("worktree_reap.zig") };}diff --git a/src/subagent_interactive.zig b/src/subagent_interactive.zigindex 282fd05f..c13b6f28 100644--- a/src/subagent_interactive.zig+++ b/src/subagent_interactive.zig@@ -9,6 +9,9 @@ pub var enabled = std.atomic.Value(bool).init(false);var requested = std.atomic.Value(bool).init(false);pub var line_notice = false; // legacy line REPL provenancepub var yielded = false; // root thread only+/// ADR 0247: the last yield's work resumes the session, so the standing+/// block above `›` names it and the yield itself need not print.+pub var yield_wakes = false;pub fn stealIdleLine(io: std.Io, owner: []const u8, gpa: std.mem.Allocator, buf: anytype, idle: bool) !?[]u8 {if (!idle or !enabled.load(.acquire) or buf.items.len != 0) return null;@@ -48,8 +51,13 @@ pub fn beforeRequest(root: anytype) !?[]const u8 {if (root.sub or !enabled.load(.acquire)) return null;yielded = requested.swap(false, .acq_rel);if (!yielded) return null;- const text = "Background work continues separately. You can keep using the prompt; completed shell jobs and subagents will be surfaced automatically.";- return try root.arena.dupe(u8, text);+ // ADR 0247: name what the session waits on and say it resumes on its own;+ // a bare "keep using the prompt" read as graff stopping mid-task.+ const bw = @import("background_wait.zig");+ var buf: [160]u8 = undefined;+ const waiting = bw.describe(root.io, &buf);+ yield_wakes = waiting.wakes;+ return try bw.yieldNotice(root.arena, waiting);}/// Consume only complete, previously unread jobs owned by this session. Full@@ -137,8 +145,8 @@ test "beforeRequest yields so parked shell jobs free the prompt" {requested.store(true, .release);var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);defer arena_state.deinit();- const Fake = struct { sub: bool = false, arena: std.mem.Allocator };+ const Fake = struct { sub: bool = false, arena: std.mem.Allocator, io: std.Io = std.testing.io };const text = (try beforeRequest(Fake{ .arena = arena_state.allocator() })) orelse return error.TestUnexpectedResult;- try std.testing.expect(std.mem.indexOf(u8, text, "keep using the prompt") != null);- try std.testing.expect(std.mem.indexOf(u8, text, "shell jobs") != null);+ try std.testing.expect(std.mem.indexOf(u8, text, "graff continues") != null);+ try std.testing.expect(std.mem.indexOf(u8, text, "prompt is free") != null);}diff --git a/src/subagent_tests.zig b/src/subagent_tests.zigindex 76c03e9a..f76ed134 100644--- a/src/subagent_tests.zig+++ b/src/subagent_tests.zig@@ -343,7 +343,7 @@ test "interactive children yield once without cancellation or a model request" {defer interactive.configure(false);var arena = std.heap.ArenaAllocator.init(std.testing.allocator);defer arena.deinit();- var root = .{ .sub = false, .arena = arena.allocator() };+ var root = .{ .sub = false, .arena = arena.allocator(), .io = std.testing.io };var ctx: @import("tools.zig").ToolCtx = .{ .gpa = std.testing.allocator, .io = std.testing.io, .client = undefined, .provider = undefined, .registry = null, .from_sub = false, .approvals = null, .tracer = null };interactive.request(ctx); // headless callers retain wait-until-exit behaviortry std.testing.expect((try interactive.beforeRequest(&root)) == null);@@ -356,7 +356,7 @@ test "interactive children yield once without cancellation or a model request" {main_mod.unattended = saved_unattended;interactive.request(ctx);const text = (try interactive.beforeRequest(&root)).?;- try std.testing.expect(std.mem.indexOf(u8, text, "keep using the prompt") != null);+ try std.testing.expect(std.mem.indexOf(u8, text, "graff") != null);try std.testing.expect(interactive.yielded);try std.testing.expect(!@import("agent.zig").Agent.esc_cancel.load(.acquire));try std.testing.expect((try interactive.beforeRequest(&root)) == null);diff --git a/src/turn_chrome.zig b/src/turn_chrome.zigindex 916269d8..b2993c2c 100644--- a/src/turn_chrome.zig+++ b/src/turn_chrome.zig@@ -10,6 +10,7 @@ const Io = std.Io;const Agent = @import("agent.zig").Agent;const tool_pulse = @import("tool_pulse.zig");+const style = &@import("ansi.zig").style;/// Per-turn inner-loop cap. 0 = unlimited (the production default).pub var max_turn_model_calls: u64 = 0;@@ -54,7 +55,10 @@ pub fn shouldPulseTurn(unattended: bool, json_mode: bool, sub: bool, call_n: u64/// Call 2+ used to print an inner-loop counter; that line is gone (ADR 0021).pub fn beforeRequest(self: *Agent) !?[]const u8 {if (try @import("subagent_interactive.zig").beforeRequest(self)) |text| {- try self.say("{s}\n", .{text});+ // ADR 0247: work that resumes the session is named above `›` by the+ // standing block on every redraw; print only what that will not say.+ if (!@import("subagent_interactive.zig").yield_wakes)+ try self.say("{s}↻ {s}{s}\n", .{ style.accent, text, style.reset });return text;}self.model_calls_this_turn += 1;diff --git a/src/turn_dedup.zig b/src/turn_dedup.zigindex b6eabf12..8f40401c 100644--- a/src/turn_dedup.zig+++ b/src/turn_dedup.zig@@ -33,6 +33,12 @@ pub const Outcome = enum { started, skipped, stuck };/// (learn-auto sends one prompt per model call).pub fn enqueue(root: *Agent, arena: Allocator, out: ?*Io.Writer, text: []const u8) !Outcome {if (@import("subagent_interactive.zig").line_notice) {+ // ADR 0247: a parked session resuming on its own says what woke it.+ if (out) |w| {+ var buf: [160]u8 = undefined;+ w.print("{s}↻ {s} — continuing{s}\n", .{ style.dim, @import("background_wait.zig").resumeLine(&buf, text), style.reset }) catch {};+ w.flush() catch {};+ }try root.messages.append(try @import("session_wake.zig").message(arena, text));return .started;}