Skip to content

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

Python

/loop holds for its own background work instead of ending idle (#1278)

justrach1328a9d576cc
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index fa1aaf88..59bc6a31 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -217,6 +217,9 @@ jobs:
- name: PTY /goal autonomous collapse wiring test
run: python3 scripts/test-pty-goal-loop.py zig-out/bin/graff
+ - name: PTY /loop holds for its own background work (#1278)
+ run: python3 scripts/test-pty-loop-hold.py zig-out/bin/graff
+
- name: PTY peer-channel delivery smoke test (#469)
run: python3 scripts/test-pty-peer-channel.py zig-out/bin/graff
diff --git a/scripts/test-pty-loop-hold.py b/scripts/test-pty-loop-hold.py
new file mode 100755
index 00000000..c8276076
--- /dev/null
+++ b/scripts/test-pty-loop-hold.py
@@ -0,0 +1,115 @@
+#!/usr/bin/env python3
+"""Real-PTY regression for #1278: /loop holds for its own background work.
+
+A /loop turn that starts a background shell job yields the prompt at once
+(subagent_interactive), so the turn makes no further model call and the
+controller used to read it as `idle` and end the run. The job's completion
+wake then ran as an ordinary turn, outside the loop's credits and steering.
+
+Mock script (by request ordinal):
+ 1 "/loop wait for the build" -> one shell call with run_in_background.
+ The turn yields; the job (a short sleep) is still running, so the run
+ must HOLD instead of stopping.
+ 2 the job's completion wake -> a final message with no tool call. It must
+ arrive as a /loop continuation: the wake text plus the continuation
+ steering and pacing note. With the job gone, the run then stops idle.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tempfile
+
+from codex_ws_mock import CodexMock, RecordedRequest, turn_events
+from pty_harness import PtySession
+
+
+_arg = sys.argv[1] if len(sys.argv) > 1 else "graff"
+GRAFF = os.path.abspath(_arg) if os.sep in _arg else _arg
+
+
+def events(request: RecordedRequest) -> list[dict]:
+ if request.ordinal == 1:
+ return [
+ {
+ "type": "response.output_item.done",
+ "item": {
+ "type": "function_call",
+ "id": "fc_hold_1",
+ "call_id": "call_hold_1",
+ "name": "shell",
+ "arguments": json.dumps({"action": "run", "command": "sleep 2; echo HOLD_BUILD_DONE", "run_in_background": True}),
+ "status": "completed",
+ },
+ },
+ turn_events("resp_hold_tool")[1],
+ ]
+ done = turn_events(f"resp_hold_{request.ordinal}")
+ done[0]["item"]["content"][0]["text"] = f"HOLD_TURN_{request.ordinal}_DONE"
+ return done
+
+
+def main() -> None:
+ mock = CodexMock(events_for_request=events)
+ port = mock.start()
+ try:
+ with tempfile.TemporaryDirectory(prefix="graff-loop-hold-") as tmp:
+ codex_home = os.path.join(tmp, "codex-home")
+ os.makedirs(codex_home)
+ with open(os.path.join(codex_home, "auth.json"), "w", encoding="utf-8") as fh:
+ json.dump({"tokens": {"access_token": "loop-hold-mock", "account_id": "acct-loop-hold"}}, fh)
+ harness_dir = os.path.join(tmp, ".harness")
+ os.makedirs(harness_dir)
+ with open(os.path.join(harness_dir, "settings.json"), "w", encoding="utf-8") as fh:
+ # Title/recap calls would shift the scripted request ordinals.
+ json.dump({"ai_title": False, "session_recap": False, "skills": {"codedbpro": False}}, fh)
+ env = {
+ "HOME": tmp,
+ "CODEX_HOME": codex_home,
+ "GRAFF_CODEX_URL": f"http://127.0.0.1:{port}/backend-api/codex/responses",
+ "GRAFF_CODEX_WS": "off",
+ "GRAFF_FLEET": "off",
+ "GRAFF_NO_TELEMETRY": "1",
+ }
+ ambient = tuple(
+ name
+ for name in os.environ
+ if (name.startswith("GRAFF_") or name.startswith("CODEX_") or name == "NO_COLOR")
+ and name not in env
+ )
+ with PtySession(
+ GRAFF,
+ ["--model", "codex", "--no-telemetry", "--yolo"],
+ cwd=tmp,
+ env=env,
+ unset_env=ambient,
+ timeout=15.0,
+ ) as session:
+ session.wait_for_prompt()
+ cursor = len(session.raw)
+ session.send_line("/loop wait for the build")
+ session.wait_for_literal("run waiting", start=cursor, timeout=15.0)
+ # The job's wake continues the run; with the job gone it stops idle.
+ session.wait_for_literal("run stopped — idle", start=cursor, timeout=20.0)
+ session.wait_for_prompt(start=cursor)
+ session.send_key("ctrl-d")
+ result = session.read_until_exit(5.0)
+ if result.timed_out or result.exit_code != 0:
+ raise AssertionError(f"session did not exit cleanly: exit={result.exit_code} timed_out={result.timed_out}")
+ finally:
+ mock.stop()
+
+ requests = mock.recorded_requests()
+ if len(requests) != 2:
+ raise AssertionError(f"expected exactly 2 model requests, got {len(requests)}")
+ wake_turn = json.dumps(requests[1].body)
+ for needle in ("HOLD_BUILD_DONE", "continuing autonomously (/loop)", "[pace: continuation"):
+ if needle not in wake_turn:
+ raise AssertionError(f"the wake turn did not continue the /loop run ({needle!r} missing): {wake_turn[-600:]!r}")
+ print("ok /loop holds for its background job, and the job's wake continues the run with its steering")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/src/loop_run.zig b/src/loop_run.zig
new file mode 100644
index 00000000..d5e2b7ee
--- /dev/null
+++ b/src/loop_run.zig
@@ -0,0 +1,161 @@
+//! One line-REPL /loop run (#226): its iteration credits, the queued
+//! continuation, the checklist gate and the wall clock. Moved out of
+//! mainloop.zig (600-line cap) when #1278 added the hold.
+//!
+//! #1278: a loop turn that only started or waited on background work makes no
+//! tool calls, so the controller read it as `idle` and ended the run. The
+//! work's completion wake then ran as an ordinary turn, outside the loop's
+//! credits and steering. Now, while the root still owns a running shell job or
+//! background subagent that will report, the run holds instead: the next idle
+//! wake continues it as a loop turn. A typed line ends the hold like a steer.
+
+const std = @import("std");
+const Io = std.Io;
+const Allocator = std.mem.Allocator;
+
+const Agent = @import("agent.zig").Agent;
+const goal_flow = @import("goal_flow.zig");
+const goal_pacing = @import("goal_pacing.zig");
+const repl_glue = @import("repl_glue.zig");
+const util = @import("util.zig");
+const style = &@import("ansi.zig").style;
+
+/// Hard per-run iteration bound (the never-completing-model guard).
+pub const iter_cap: u32 = 25;
+
+pub const LoopRun = struct {
+ iters_left: u32 = 0, // continuation turns still authorized this run
+ armed: bool = false, // a continuation turn is queued for the next read
+ holding: bool = false, // #1278: waiting for the root's background work to report
+ list: goal_flow.LoopListGate = .{}, // diff-gate for the checklist copy (#318)
+ clock: goal_pacing.LoopClock = .{}, // `/loop 30m <prompt>` deadline + pacing
+
+ /// A user steer or typed line, or the run's end: nothing continues.
+ pub fn cancel(self: *LoopRun, root: *Agent) void {
+ self.iters_left = 0;
+ self.armed = false;
+ self.holding = false;
+ self.list.reset();
+ self.clock.clear(root); // and its deadline stops reaching subagents
+ }
+
+ /// The queued continuation turn's line, consumed here so an interrupted
+ /// or errored turn does not resume the run. `wake` prefixes it when the
+ /// continuation comes out of a hold.
+ pub fn continuation(self: *LoopRun, arena: Allocator, root: *Agent, now_ms: i64, wake: []const u8) ![]const u8 {
+ self.armed = false;
+ // Gated: these prompts persist in root.messages, autosave, and are
+ // compaction input, so the current epoch's list is pasted only when
+ // it changed or a history rewrite destroyed the pasted copies (#318).
+ const note = try self.list.note(arena, root);
+ const pace = try goal_pacing.pacingNote(arena, now_ms, self.clock, iter_cap - self.iters_left, iter_cap);
+ if (wake.len == 0) return std.fmt.allocPrint(arena, "/loop {s}\n{s}", .{ note, pace });
+ return std.fmt.allocPrint(arena, "/loop {s}\n\n{s}\n{s}", .{ wake, note, pace });
+ }
+
+ /// A line read while holding. An idle wake (the work reporting) continues
+ /// the run when a credit and the clock allow; anything typed ends it.
+ /// Returns the continuation line, or null to handle `line` as read.
+ pub fn afterRead(self: *LoopRun, arena: Allocator, root: *Agent, now_ms: i64, line: []const u8, from_wake: bool) !?[]const u8 {
+ if (!self.holding) return null;
+ self.holding = false;
+ const expired = if (root.loop_deadline_ms) |deadline| now_ms >= deadline else false;
+ if (!from_wake or expired or self.iters_left == 0) {
+ self.cancel(root);
+ return null;
+ }
+ self.iters_left -= 1;
+ return try self.continuation(arena, root, now_ms, line);
+ }
+
+ /// After a clean /loop turn the CONTROLLER decides whether another runs,
+ /// not the model merely stopping (goal_flow.loopTurnDecision).
+ pub fn afterTurn(self: *LoopRun, root: *Agent, io: Io, out: *Io.Writer, is_continuation: bool) !void {
+ if (!is_continuation) {
+ self.iters_left = iter_cap; // fresh run: arm the bound
+ self.list.reset(); // and a clean gate: its first continuation carries the list in full
+ }
+ switch (goal_flow.loopTurnDecision(root, self.iters_left, util.unixMs(io))) {
+ .continue_turn => {
+ self.iters_left -= 1; // one credit for the queued continuation
+ self.armed = true;
+ },
+ .stop => |outcome| {
+ if (holds(outcome, self.iters_left, liveBackgroundWork(io))) {
+ self.holding = true;
+ try out.print("{s}↻ run waiting — background work is still running; the run continues when it reports (type to take over){s}\n", .{ style.accent, style.reset });
+ try out.flush();
+ if (root.tracer) |t| t.note("loop", "holding");
+ return;
+ }
+ self.cancel(root);
+ // Only work_done reaches `accepted`, so the loop drove the
+ // goal to done; a --goal standing objective outlives it (#318).
+ if (outcome == .accepted) _ = goal_flow.acceptLoopOutcome(root);
+ const tone = if (outcome == .accepted) style.green else style.yellow; // success must not look like the four failures
+ try out.print("{s}↩ run stopped — {s}{s}\n", .{ tone, if (@import("subagent_interactive.zig").yielded) "waiting for delegated work; prompt available" else repl_glue.outcomeText(outcome, iter_cap), style.reset });
+ try out.flush();
+ if (root.tracer) |t| t.note("loop", @tagName(outcome)); // every /goal transition is traced; the run's end was not
+ },
+ }
+ }
+};
+
+/// Only a turn that stopped for want of work holds, and only while there is
+/// work that will wake the run and a credit to spend when it does.
+pub fn holds(outcome: repl_glue.ContinuationOutcome, iters_left: u32, live_work: bool) bool {
+ return outcome == .idle and iters_left > 0 and live_work;
+}
+
+/// A running shell job that will post a completion notice, or a background
+/// subagent owned by this session (its completion is an idle wake).
+fn liveBackgroundWork(io: Io) bool {
+ const jobs = &@import("jobs.zig").g_jobs;
+ {
+ jobs.mutex.lockUncancelable(io);
+ defer jobs.mutex.unlock(io);
+ for (jobs.list.items) |job| if (!job.done and !job.quiet and !job.detach) return true;
+ }
+ 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 and job.owner != null) return true;
+ return false;
+}
+
+test "#1278: only an idle stop with live work and a credit left holds" {
+ try std.testing.expect(holds(.idle, 5, true));
+ try std.testing.expect(!holds(.idle, 5, false)); // nothing will wake it
+ try std.testing.expect(!holds(.idle, 0, true)); // no credit to continue with
+ for ([_]repl_glue.ContinuationOutcome{ .accepted, .exhausted, .expired, .blocked, .cancelled }) |outcome|
+ try std.testing.expect(!holds(outcome, 5, true));
+}
+
+test "#1278: a wake during a hold continues the run; a typed line or a spent run ends it" {
+ var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+ defer arena_state.deinit();
+ const arena = arena_state.allocator();
+ var root: Agent = undefined;
+ root.loop_deadline_ms = null;
+ root.history_rewrites = 0;
+ root.todos = .empty;
+ root.goal = null;
+ const wake = "[job 7 exited 0: zig build test]";
+
+ var run: LoopRun = .{ .iters_left = 3, .holding = true };
+ const line = (try run.afterRead(arena, &root, 1_000, wake, true)).?;
+ try std.testing.expect(std.mem.startsWith(u8, line, "/loop " ++ wake ++ "\n\n[continuing autonomously (/loop)"));
+ try std.testing.expect(!run.holding and run.iters_left == 2);
+
+ var typed: LoopRun = .{ .iters_left = 3, .holding = true };
+ try std.testing.expect(try typed.afterRead(arena, &root, 1_000, "do something else", false) == null);
+ try std.testing.expect(!typed.holding and typed.iters_left == 0);
+
+ root.loop_deadline_ms = 500;
+ var late: LoopRun = .{ .iters_left = 3, .holding = true };
+ try std.testing.expect(try late.afterRead(arena, &root, 1_000, wake, true) == null); // out of time
+ try std.testing.expect(late.iters_left == 0);
+
+ var idle: LoopRun = .{};
+ try std.testing.expect(try idle.afterRead(arena, &root, 1_000, wake, true) == null); // no hold: an ordinary wake
+}
diff --git a/src/mainloop.zig b/src/mainloop.zig
index 4b68cfc7..28a0f3c3 100644
--- a/src/mainloop.zig
+++ b/src/mainloop.zig
@@ -75,11 +75,7 @@ pub fn run(ctx: *Ctx) !void {
var prev_turn_id: u64 = 0;
var prev_prompt_fp: [16]u8 = scoring.promptFingerprint(ctx.root.systemPrompt());
// Armed only after a clean /loop turn and consumed by the next read (#226).
- const loop_iter_cap: u32 = 25; // hard per-/loop iteration bound (never-completing-model guard)
- var loop_iters_left: u32 = 0; // continuation turns still authorized this /loop run
- var loop_continue_armed = false; // a continuation turn is queued for the next readline
- var loop_list: goal_flow.LoopListGate = .{}; // diff-gate for the checklist copy in continuation prompts (#318)
- var loop_clock: goal_pacing.LoopClock = .{}; // this run's wall clock: `/loop 30m <prompt>` arms a deadline, and every continuation is told where it stands
+ var loop_run: @import("loop_run.zig").LoopRun = .{};
while (true) {
@import("subagent_interactive.zig").line_notice = false;
@@ -91,10 +87,7 @@ pub fn run(ctx: *Ctx) !void {
defer if (steer_entry) |e| std.heap.page_allocator.free(e.text);
var is_loop_continuation = false; // #226: this iteration is an autonomous /loop continuation turn
const raw_line: []const u8 = if (steer_entry) |e| blk: {
- loop_iters_left = 0; // #226: a user steer/force cancels the autonomous /loop run
- loop_continue_armed = false;
- loop_list.reset();
- loop_clock.clear(ctx.root); // and its deadline stops reaching subagents
+ loop_run.cancel(ctx.root); // #226: a user steer/force cancels the autonomous /loop run
if (e.force) {
try ctx.out.print("{s}↳ force ›{s} {s}\n", .{ style.yellow, style.reset, e.text });
} else {
@@ -102,21 +95,20 @@ pub fn run(ctx: *Ctx) !void {
}
try ctx.out.flush();
break :blk e.text;
- } else if (loop_continue_armed) blk: {
+ } else if (loop_run.armed) blk: {
// #226: autonomous /loop continuation — synthesize the next turn from the
- // continuation steering note instead of reading a new user line. Consumed
- // here, so an interrupted/errored turn does not resume the loop.
- loop_continue_armed = false;
+ // continuation steering note instead of reading a new user line.
is_loop_continuation = true;
- // Gated: these prompts persist in root.messages, autosave, and are
- // compaction input, so the current epoch's list is pasted only when
- // it changed or a history rewrite destroyed the pasted copies (#318).
- const note = try loop_list.note(ctx.arena, ctx.root);
- const pace = try goal_pacing.pacingNote(ctx.arena, util.unixMs(ctx.io), loop_clock, loop_iter_cap - loop_iters_left, loop_iter_cap);
- break :blk try std.fmt.allocPrint(ctx.arena, "/loop {s}\n{s}", .{ note, pace });
+ break :blk try loop_run.continuation(ctx.arena, ctx.root, util.unixMs(ctx.io), "");
} else if (ctx.interactive) blk: {
try ctx.root.prompt();
- break :blk (try readline.readLine(ctx.root, ctx.in, ctx.out, ctx.gpa, ctx.history, ctx.linebuf, null)) orelse break;
+ const read = (try readline.readLine(ctx.root, ctx.in, ctx.out, ctx.gpa, ctx.history, ctx.linebuf, null)) orelse break;
+ // #1278: the wake of the work a held run waits on continues that run.
+ if (try loop_run.afterRead(ctx.arena, ctx.root, util.unixMs(ctx.io), read, @import("subagent_interactive.zig").line_notice)) |resumed| {
+ is_loop_continuation = true;
+ break :blk resumed;
+ }
+ break :blk read;
} else (try json_inbox.request(ctx.arena, ctx.in)) orelse break;
title_jobs.poll(ctx);
recap_jobs.poll(ctx);
@@ -130,7 +122,7 @@ pub fn run(ctx: *Ctx) !void {
const loop_prompt: ?[]const u8 = if (auto) |a| a.prompt else null;
// A fresh line starts (or ends) a run: wall clock begins here; stale todos_dirty is
// dropped, and an armed budget is echoed — a silently-eaten "5m" reads like a truncated prompt.
- if (!is_loop_continuation) try goal_pacing.armAndAnnounce(&loop_clock, ctx.root, ctx.out, ctx.arena, util.unixMs(ctx.io), if (auto) |a| a.budget() else null);
+ if (!is_loop_continuation) try goal_pacing.armAndAnnounce(&loop_run.clock, ctx.root, ctx.out, ctx.arena, util.unixMs(ctx.io), if (auto) |a| a.budget() else null);
var review_prompt: ?[]const u8 = if (!main_mod.json_mode) review.promptFromLine(line) else null;
const issue_report: ?[]const u8 = if (!main_mod.json_mode) @import("issue_cmd.zig").promptFromLine(line) else null;
if (!main_mod.json_mode) {
@@ -557,40 +549,16 @@ pub fn run(ctx: *Ctx) !void {
if (session_context_tokens >= ctx.root.provider.compactAt()) {
// Trim on failure only when we're genuinely against the window — at
// 80–95% a transient compaction failure can recover next turn.
- ctx.root.autocompact(session_context_tokens); // loop_list re-carries via root.history_rewrites, incl. MID-turn rewrites this block never sees (#318)
+ ctx.root.autocompact(session_context_tokens); // loop_run.list re-carries via root.history_rewrites, incl. MID-turn rewrites this block never sees (#318)
}
// #226: /loop controller-authorized continuation. After a cleanly-
// completed autonomous /loop turn the CONTROLLER decides whether to run
- // another turn — not the model merely stopping; the rule itself is
- // goal_flow.loopTurnDecision. `loop_continue_armed` is consumed at the
- // next readline, so an interrupted/errored turn (which `continue`s past
- // here) never resumes the loop.
- if (loop_prompt != null and !main_mod.json_mode) {
- if (!is_loop_continuation) {
- loop_iters_left = loop_iter_cap; // fresh /loop run: arm the bound
- loop_list.reset(); // and a clean gate: its first continuation carries the list in full
- }
- switch (goal_flow.loopTurnDecision(ctx.root, loop_iters_left, util.unixMs(ctx.io))) {
- .continue_turn => {
- loop_iters_left -= 1; // consume one credit for the queued continuation
- loop_continue_armed = true;
- },
- .stop => |outcome| {
- loop_iters_left = 0;
- loop_continue_armed = false;
- loop_list.reset();
- loop_clock.clear(ctx.root);
- // Only work_done reaches `accepted`, so the loop drove the
- // goal to done; a --goal standing objective outlives it (#318).
- if (outcome == .accepted) _ = goal_flow.acceptLoopOutcome(ctx.root);
- const tone = if (outcome == .accepted) style.green else style.yellow; // success must not look like the four failures
- try ctx.out.print("{s}↩ run stopped — {s}{s}\n", .{ tone, if (@import("subagent_interactive.zig").yielded) "waiting for delegated work; prompt available" else repl_glue.outcomeText(outcome, loop_iter_cap), style.reset });
- try ctx.out.flush();
- if (ctx.root.tracer) |t| t.note("loop", @tagName(outcome)); // every /goal transition is traced; the run's end was not
- },
- }
- }
+ // another turn — not the model merely stopping (loop_run.zig). The armed
+ // continuation is consumed at the next read, so an interrupted/errored
+ // turn (which `continue`s past here) never resumes the loop; a run with
+ // background work still running holds for its wake instead (#1278).
+ if (loop_prompt != null and !main_mod.json_mode) try loop_run.afterTurn(ctx.root, ctx.io, ctx.out, is_loop_continuation);
session.saveSessionAsync(ctx.root, ctx.arena, ctx.root.session_name) catch {};
// --worktree checkpoint: commit this turn's edits to the scratch branch so the work is durable
@@ -598,3 +566,7 @@ pub fn run(ctx: *Ctx) !void {
jobs.worktreeAutoCommit(ctx.gpa, ctx.io, std.fmt.allocPrint(ctx.arena, "wip: {s}", .{title_mod.titleFromPrompt(base_msg)}) catch "wip: graff checkpoint");
}
}
+
+test {
+ _ = @import("loop_run.zig");
+}