graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
//! Goal lifecycle FLOW (#318): the pure helpers a /goal transition needs, plus
//! the scenario tests that walk a whole sequence (set -> work -> clear -> set)
//! instead of one function in isolation. Split out of goal_state.zig, which is
//! at this repo's 600-line file cap. Reached through the `test { _ = ... }`
//! hook in main.zig - without that line these tests silently compile to
//! nothing and the suite still reports green.
const std = @import("std");
const Allocator = std.mem.Allocator;
const agent_mod = @import("agent.zig");
const goal_state = @import("goal_state.zig");
const repl_glue = @import("repl_glue.zig");
const presence = @import("presence.zig");
const task_outcome = @import("task_outcome.zig");
const utf8Prefix = @import("util.zig").utf8Prefix;
const Agent = agent_mod.Agent;
const TodoItem = agent_mod.TodoItem;
/// The Goal `--goal <text>` seeds: a STANDING objective (the flag's documented
/// contract is "every turn, incl. --json/-p/SDK"), stamped above `old` (the
/// goal it displaces, if any) and every epoch already present in `todos`, so a
/// resumed session's parked checklist can never become its work and it never
/// aliases the epoch-0 no-goal bucket (#318).
/// `objective` must already be owned by the session arena. Re-application over
/// a loadSession goes through reapplyFlagGoal, which keeps the same objective's
/// goal instead of re-minting it.
pub fn standingGoalFromFlag(objective: []const u8, old: ?agent_mod.Goal, todos: []const TodoItem, now_ms: i64) agent_mod.Goal {
return .{
.objective = objective,
.status = .active,
.standing = true,
.epoch = goal_state.nextEpoch(old, todos),
.created_ms = now_ms,
.updated_ms = now_ms,
};
}
/// Re-apply the --goal flag over whatever loadSession restored (#318). The flag
/// wins, but idempotently: resuming the SAME standing objective keeps the
/// restored goal - epoch, checklist and timestamps - instead of minting a new
/// epoch and parking the objective's own work on every restart. A different
/// restored goal is displaced like any supersession; when it was live with open
/// items the returned note must be queued (pending_goal_note, always null right
/// after a load) so neither the model nor the user loses the boundary silently.
pub fn reapplyFlagGoal(arena: Allocator, root: *Agent, objective: []const u8, now_ms: i64) !?[]const u8 {
if (root.goal) |*g| {
if (g.standing and std.mem.eql(u8, g.objective, objective)) {
// Same policy, same goal - but the flag passed TODAY outranks a saved
// pause: --goal on the command line means steer. Without this, a
// paused standing goal came back paused and the flag produced no
// steering and no completion gate at all, silently (#318).
g.status = .active;
g.updated_ms = now_ms;
root.goal_note_fp = 0; // a revived goal re-states its note, not by caller-ordering luck
return null;
}
}
const displaced: ?agent_mod.Goal = if (root.goal) |old| (if (old.status == .complete) null else old) else null;
root.goal = standingGoalFromFlag(objective, root.goal, root.todos.items, now_ms);
task_outcome.noteGoalSet(root);
presence.noteGoal(root.io, root.gpa, root.arena, objective); // #469: co-resident sessions read our goal off the presence record
root.goal_note_fp = 0; // re-state the (now standing) note on the next turn
goal_state.resetCompletionGate(root); // a new objective is fresh evidence for the double-check
if (displaced) |old| {
const parked = goal_state.parkedOpenCount(root.todos.items, root.goal.?.epoch);
if (parked > 0) return try goal_state.supersededNote(arena, old.objective, parked);
}
return null;
}
/// The checklist render carried into a compaction handoff is capped here: a
/// pathological 200-item list must never eat the very context the compaction
/// was run to reclaim. Over the cap the render is cut at a line boundary and
/// the model is pointed at todo_read for the rest.
pub const snapshot_render_cap: usize = 2_000;
/// The standing state a compaction handoff has to carry across the summary
/// boundary (#318). compact() rebuilds history as [handoff summary] + an ~8k
/// suffix, so the last todo_write result - the ONLY place the live checklist
/// ever reaches the model - is usually gone, and the summarizer may not have
/// seen the item statuses either (trimOldestToolOutputs blanks old outputs
/// before the summary request). The model then rewrote the list from prose,
/// todo_write REPLACED the epoch, three already-completed items came back as
/// pending, allDone flipped false, and the goal could never finish - durably,
/// because the autosave persisted the damaged list. So the harness restates
/// the list itself, once, as part of the new history.
/// Restates any saved goal or current checklist, including inactive goals with
/// their lifecycle authority. Excludes subagents and /review turns. Allocates
/// from `arena`, which MUST outlive compact()'s temporary
/// compaction arena - the text goes into the history that survives it.
pub fn compactionSnapshot(arena: Allocator, root: *Agent) !?[]const u8 {
// The gate is the CHECKLIST, not the goal. Gating on goalActive left every
// todo_write user who never types /goal - most of them - with no
// restatement, which is the #318 failure this exists to stop; a paused goal
// needs it too, since it emits no steering note either. Subagents and
// review turns share the Agent but not the goal, so they still never do.
if (root.sub or root.review_mode) return null;
const rendered = goal_state.renderCurrent(root);
const objective: ?[]const u8 = if (root.goal) |g|
try std.fmt.allocPrint(arena, "{s} (status: {s}; kind: {s})", .{ g.objective, @tagName(g.status), if (g.standing) "standing" else "task" })
else
null;
// A summary is not permission to revive paused or completed work. Keep
// lifecycle authority beside the objective even when there is no checklist.
const inactive = if (root.goal) |g| g.status != .active else false;
if (inactive) return try std.fmt.allocPrint(arena, "[standing state (harness-kept, survives context rewrites): goal: {s}. Do not resume this objective unless the user explicitly asks. Its checklist is retained for reference; read it with todo_read. This snapshot does not reactivate the goal.\n{s}]", .{ objective.?, try capRender(arena, rendered) });
if (rendered.len == 0) {
const obj = objective orelse return null; // no goal AND no checklist: nothing to restate
return try std.fmt.allocPrint(arena, "[standing state (harness-kept, survives context rewrites): goal: {s}. No checklist has been written for it yet - plan the work with todo_write, and read the list back with todo_read at any time.]", .{obj});
}
const open = goal_state.openCount(root.todos.items, goal_state.currentEpoch(root.goal));
const head = if (objective) |obj|
try std.fmt.allocPrint(arena, "goal: {s}. Checklist ({d} open)", .{ obj, open })
else
try std.fmt.allocPrint(arena, "Checklist ({d} open)", .{open});
return try std.fmt.allocPrint(arena, "[standing state (harness-kept, survives context rewrites): {s}:\n{s}\nThis list is live harness state, read it back with todo_read at any time. todo_write REPLACES the whole list; completed items you omit are kept automatically, open items you omit are dropped.]", .{ head, try capRender(arena, rendered) });
}
/// Cut an oversized checklist render at a line boundary and say so, rather
/// than pasting it whole. Cuts from the FRONT: preserved completed items keep
/// their original positions while new work appends, so cutting the tail threw
/// away the live plan and kept a wall of finished history.
fn capRender(arena: Allocator, rendered: []const u8) ![]const u8 {
if (rendered.len <= snapshot_render_cap) return rendered;
const start = rendered.len - snapshot_render_cap;
const tail = rendered[start..];
const cut = if (std.mem.indexOfScalar(u8, tail, '\n')) |i| i + 1 else 0;
return std.fmt.allocPrint(arena, "[earlier completed items truncated for the handoff - call todo_read for the full list]\n{s}", .{tail[cut..]});
}
pub const GoalSetResult = struct {
/// The live goal this one replaced, or null when there was nothing to
/// supersede (no goal, or one already retired). The caller prints it and
/// queues the supersession note.
superseded: ?agent_mod.Goal,
/// Open items that do NOT belong to the new epoch, i.e. the work that
/// stopped steering. Retained, never deleted (#318).
parked_open: usize,
};
/// The pure state transition behind `/goal <objective>` (set and replace are
/// the same transition): the new epoch, the adopt-or-supersede choice, the
/// goal assignment, and the gate/fingerprint resets. Printing, tracing and the
/// session save stay with the caller, which is what makes the rules here
/// unit-testable - the two riskiest of them had no test at all before, since
/// they only existed inside a slash-command handler.
/// `objective` must already be owned by the session arena. `standing` is left
/// at its default false: a typed /goal is a task the model may complete, only
/// the --goal flag makes an objective standing (goal_flow.standingGoalFromFlag).
pub fn applyGoalSet(root: *Agent, objective: []const u8, now_ms: i64) GoalSetResult {
const epoch = goal_state.nextEpoch(root.goal, root.todos.items);
// A COMPLETE goal is already retired and its checklist already parked
// (#318 D1), so the next /goal is not superseding live work: it takes the
// adoption branch, exactly like a first /goal.
const superseded: ?agent_mod.Goal = if (root.goal) |old| (if (old.status == .complete) null else old) else null;
// Formalizing an in-flight plan keeps its checklist; work parked by a
// finished or superseded goal stays parked and is never resurrected.
if (superseded == null)
goal_state.adoptTodos(root.todos.items, goal_state.currentEpoch(root.goal), epoch);
const parked_open = goal_state.parkedOpenCount(root.todos.items, epoch);
root.goal = .{ .objective = objective, .status = .active, .epoch = epoch, .created_ms = now_ms, .updated_ms = now_ms };
task_outcome.noteGoalSet(root);
presence.noteGoal(root.io, root.gpa, root.arena, objective); // #469: keep the presence record's goal current for peers
root.goal_note_fp = 0; // re-state the note on the next turn, not a stale-suppressed repeat
goal_state.resetCompletionGate(root); // a new objective is new evidence for the completion double-check
return .{ .superseded = superseded, .parked_open = parked_open };
}
/// The autonomous run controller's per-turn decision, assembled from root state. Split
/// out of mainloop (#318) so the composition itself is testable: which turns
/// count as work, which count as silence, and which goal status is read.
/// work_done is the only evidence that may complete the goal and the only
/// thing that earns `accepted` - a checklist restored from disk is not it
/// (checklistFinished gates on this-process freshness). A zero-tool turn ends
/// the LOOP as `idle` (codex RegularTask semantics: no run burns 25
/// continuations on a one-turn prompt), but a REFUSED attempt_completion is
/// work, not silence. A session with no goal reads as .active, so a goal-less run
/// is governed by its work and its iteration bound alone.
pub fn loopTurnDecision(root: *Agent, iters_left: u32, now_ms: i64) repl_glue.ContinuationDecision {
if (root.yielded != null) return .{ .stop = .blocked }; // wait for the next user prompt, not completion
if (@import("subagent_interactive.zig").enabled.load(.acquire) and @import("subagent_interactive.zig").yielded) return .{ .stop = .idle };
const work_done = root.completed != null or goal_state.checklistFinished(root);
const model_stopped = repl_glue.turnStopped(root.tool_calls_this_turn, root.completion_refused);
const gstatus: agent_mod.GoalStatus = if (root.goal) |g| g.status else .active;
const d = repl_glue.continuationDecision(gstatus, work_done, model_stopped, iters_left);
// A deadline is the run's ONLY hard effect (#224 dropped goal budget
// enforcement): it stops the run and names the outcome, flipping no goal
// status. accepted (real evidence) and cancelled/blocked (the USER is
// needed) outrank the clock; expired renames only uninformative stops.
if (root.loop_deadline_ms) |dl| if (now_ms >= dl) {
return switch (d) {
.continue_turn => .{ .stop = .expired },
.stop => |o| if (o == .idle or o == .exhausted) .{ .stop = .expired } else d,
};
};
return d;
}
/// The steering appended to each autonomous run's continuation turn (the
/// continuation_steering_item analog): keep working the checklist, verify, and
/// stop only when done or blocked - not a per-turn user note. Moved here from
/// repl_glue.zig, which is at the 600-line cap.
/// `paste_list` is the diff-gate's verdict (goal_state.steeringGate over the
/// render). It used to be unconditional, so a 25-iteration run wrote up to 25
/// near-identical checklist copies into root.messages - autosaved, and fed
/// verbatim into the next compaction's summary input. That is the exact
/// re-pasting this branch removed from the goal note, left behind in its one
/// remaining every-turn paster (#318). When the list has not changed the model
/// is still pointed at it, just not handed another copy; the harness restates
/// the full list on the first continuation after a compaction, where the old
/// copies died with the old history.
pub fn continuationSteeringNote(arena: Allocator, todos_render: []const u8, paste_list: bool) ![]const u8 {
if (todos_render.len == 0)
return "[continuing autonomously: make the next concrete step toward the goal, then verify it. Do not ask for confirmation between routine steps. Stop only when the work is complete or you hit a blocker that needs the user.]";
if (!paste_list)
return "[continuing autonomously: keep working the current checklist (unchanged, see your latest todo_write result, or call todo_read) - do the next incomplete item, mark it in_progress then completed, and verify. Do not ask for confirmation between routine steps. Stop only when every item is done or you are blocked.]";
return std.fmt.allocPrint(arena, "[continuing autonomously: keep working the checklist below — do the next incomplete item, mark it in_progress then completed, and verify. Do not ask for confirmation between routine steps. Stop only when every item is done or you are blocked.\n\nChecklist so far:\n{s}]", .{todos_render});
}
/// Run-LOCAL diff-gate state for the checklist copy in the run's continuation
/// prompt (#318). Deliberately not an Agent field and never persisted: it
/// describes what THIS run has already handed the model, so a fresh run, a
/// user steer, a stop and a compaction all reset it.
pub const LoopListGate = struct {
fp: u64 = 0,
age: u32 = 0,
rewrites_seen: u32 = 0,
pub fn reset(self: *LoopListGate) void {
self.* = .{};
}
/// This continuation turn's steering note, pasting the render only when the
/// model has not just been handed the same list. A history rewrite
/// (root.history_rewrites: compaction or emergency trim) kills every copy
/// already pasted - including MID-turn, where mainloop's post-turn hook
/// never fires because the meter is already back under the window - so the
/// first continuation after one re-carries the list in full.
pub fn note(self: *LoopListGate, arena: Allocator, root: *Agent) ![]const u8 {
if (root.history_rewrites != self.rewrites_seen) {
self.reset();
self.rewrites_seen = root.history_rewrites;
}
const rendered = goal_state.renderCurrent(root);
const gate = goal_state.steeringGate(rendered, self.fp, self.age, goal_state.refresh_turns);
self.fp = gate.fp;
self.age = gate.age;
return continuationSteeringNote(arena, rendered, gate.inject);
}
};
/// The goal-side effect of a run that stopped as `accepted`: the run
/// drove the objective to done, so it retires. Returns true when it flipped.
/// A standing --goal is the user's policy for the whole session and outlives
/// any single completion (#318); a paused or already-complete goal is not the
/// loop's to change either.
pub fn acceptLoopOutcome(root: *Agent) bool {
if (root.goal) |*g| {
if (g.status == .active and !g.standing) {
g.status = .complete;
return true;
}
}
return false;
}
/// A root agent in the shape the goal helpers read; no live turn behind it.
fn flowRoot(arena: Allocator) Agent {
var root: Agent = undefined;
root.arena = arena;
root.sub = false;
root.review_mode = false;
root.todos = .empty;
root.goal = null;
root.todos_dirty = false;
root.completion_gate_armed = false;
root.completion_refused = false;
root.completed = null;
root.yielded = null;
root.goal_note_fp = 0;
root.pending_goal_note = null;
root.history_rewrites = 0;
root.tool_calls_this_turn = 0;
root.loop_deadline_ms = null;
return root;
}
test "a --goal standing objective outlives the model's own completion (#318)" {
var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena_state.deinit();
const ar = arena_state.allocator();
var root = flowRoot(ar);
root.goal = standingGoalFromFlag("keep the tree green", null, root.todos.items, 7);
try std.testing.expect(root.goal.?.standing);
try std.testing.expectEqual(@as(u64, 1), root.goal.?.epoch); // never epoch 0: that bucket is the no-goal one
// The completion CLAIM is double-checked exactly like a /goal objective:
// an unearned "done" is worst in the flag's own headless sessions, where it
// ended a run as accepted with open work. Only RETIREMENT is exempt.
const r1 = try goal_state.completionGate(ar, &root);
try std.testing.expect(r1 != null and std.mem.indexOf(u8, r1.?, "no checklist") != null);
try std.testing.expect(std.mem.indexOf(u8, r1.?, "keeps steering") != null); // the refusal never promises a close
goal_state.noteCompletionRefused(&root);
try std.testing.expect((try goal_state.completionGate(ar, &root)) == null); // the promised second call is accepted...
// ...and the accepted claim is recorded, but the objective stays active and
// keeps steering. Before this, one attempt_completion left every later turn
// of a headless/SDK session unsteered.
root.completed = "shipped the first task";
try std.testing.expect(!goal_state.retireOnCompletion(&root, 99));
try std.testing.expectEqual(agent_mod.GoalStatus.active, root.goal.?.status);
try std.testing.expect(root.completed != null);
try std.testing.expect(goal_state.goalActive(&root));
// The accepted claim CONSUMED the arm: a goal that never retires must not
// ride one refusal forever, or every later claim passes unchecked.
try std.testing.expect(!root.completion_gate_armed);
// So the NEXT claim starts a fresh double-check cycle, no reset needed:
// open work refuses with the standing consequence (the items stay active).
try root.todos.append(ar, .{ .content = "an open item", .status = "pending", .epoch = 1 });
const r2 = try goal_state.completionGate(ar, &root);
try std.testing.expect(r2 != null and std.mem.indexOf(u8, r2.?, "stay active") != null);
// A /goal-typed objective is unchanged: it still retires on completion.
root.goal = .{ .objective = "ship phase 2", .epoch = 1 };
try std.testing.expect(goal_state.retireOnCompletion(&root, 99));
try std.testing.expectEqual(agent_mod.GoalStatus.complete, root.goal.?.status);
try std.testing.expectEqual(@as(i64, 99), root.goal.?.updated_ms);
}
test "resume never auto-retires a standing goal over a finished checklist (#318)" {
var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena_state.deinit();
const ar = arena_state.allocator();
var root = flowRoot(ar);
// A restored session whose --goal checklist is all done. reconcileRestored
// retires a /goal objective here (the model finished and quit), but a
// standing one is the user's policy for the session, not a task that ended.
root.goal = standingGoalFromFlag("keep the tree green", null, root.todos.items, 7);
try root.todos.append(ar, .{ .content = "done", .status = "completed", .epoch = 1 });
try std.testing.expect(goal_state.allDone(root.todos.items, 1));
try std.testing.expect(!goal_state.reconcileRestored(&root));
try std.testing.expectEqual(agent_mod.GoalStatus.active, root.goal.?.status);
try std.testing.expectEqualStrings("[x] done", goal_state.renderCurrent(&root)); // still current, still steering
// The same list under a /goal objective does retire it.
root.goal.?.standing = false;
try std.testing.expect(goal_state.reconcileRestored(&root));
}
test "--goal seeded onto a resumed session lands above every restored epoch (#318)" {
var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena_state.deinit();
const ar = arena_state.allocator();
var root = flowRoot(ar);
// What `graff -r <session> --goal X` finds after loadSession: an unscoped
// finished list plus a parked epoch. Seeding the flag goal at the default
// epoch 0 aliased the no-goal bucket, so the restored all-[x] items were
// instantly its "finished checklist" and completion was free.
try root.todos.append(ar, .{ .content = "old unscoped work", .status = "completed", .epoch = 0 });
try root.todos.append(ar, .{ .content = "parked", .status = "pending", .epoch = 3 });
root.goal = standingGoalFromFlag("keep the tree green", null, root.todos.items, 7);
try std.testing.expectEqual(@as(u64, 4), root.goal.?.epoch);
try std.testing.expectEqual(@as(u64, 4), goal_state.currentEpoch(root.goal));
try std.testing.expect(!goal_state.hasCurrent(root.todos.items, 4));
try std.testing.expectEqual(@as(usize, 0), goal_state.openCount(root.todos.items, 4));
try std.testing.expect(!goal_state.allDone(root.todos.items, 4)); // nothing of its own is "done"
try std.testing.expectEqual(@as(usize, 2), root.todos.items.len); // and nothing was deleted
}
test "a leftover complete goal cannot end a fresh run at iteration 1 (#318)" {
// After a resume reconciliation - or any earlier run that retired the goal -
// root.goal is .complete while a NEW run starts. The controller read the
// status before the work and stopped at its first decision as `accepted`, so
// a run that had done nothing reported success.
const zero_tools = repl_glue.turnStopped(0, false);
try std.testing.expect(zero_tools);
try std.testing.expectEqual(repl_glue.ContinuationOutcome.idle, repl_glue.continuationDecision(.complete, false, zero_tools, 25).stop);
// Real work under the same leftover goal still earns accepted, and an
// ongoing run keeps its iterations - the status decides nothing either way.
try std.testing.expectEqual(repl_glue.ContinuationOutcome.accepted, repl_glue.continuationDecision(.complete, true, zero_tools, 25).stop);
try std.testing.expect(std.meta.activeTag(repl_glue.continuationDecision(.complete, false, false, 25)) == .continue_turn);
try std.testing.expectEqual(repl_glue.ContinuationOutcome.exhausted, repl_glue.continuationDecision(.complete, false, false, 0).stop);
// paused/blocked are the user's business and are untouched.
try std.testing.expectEqual(repl_glue.ContinuationOutcome.cancelled, repl_glue.continuationDecision(.paused, false, false, 25).stop);
try std.testing.expectEqual(repl_glue.ContinuationOutcome.blocked, repl_glue.continuationDecision(.blocked, false, false, 25).stop);
}
test "a cleared goal's finished checklist cannot be reborn as the next goal's list (#318)" {
var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena_state.deinit();
const ar = arena_state.allocator();
var root = flowRoot(ar);
// /goal A, a checklist, and the model finishes every item.
const epoch_a = goal_state.nextEpoch(root.goal, root.todos.items);
root.goal = .{ .objective = "phase A", .epoch = epoch_a };
try root.todos.append(ar, .{ .content = "A1", .status = "completed", .epoch = epoch_a });
goal_state.noteTodoWrite(&root); // todos_dirty is now true and NOTHING in /goal clear or set resets it
try std.testing.expect(goal_state.checklistFinished(&root));
// /goal clear: the goal goes, its items park at epoch 1 (retention, #318).
root.goal = null;
goal_state.resetCompletionGate(&root);
// /goal B. nextEpoch used to read the live goal only, so this was epoch 1
// again and B inherited A's finished list: born done, the first
// attempt_completion accepted with zero work, and a run under B stopped
// at iteration 1 as `accepted` while flipping B to complete.
const epoch_b = goal_state.nextEpoch(root.goal, root.todos.items);
try std.testing.expectEqual(@as(u64, 2), epoch_b);
goal_state.adoptTodos(root.todos.items, goal_state.currentEpoch(root.goal), epoch_b); // the /goal set branch
root.goal = .{ .objective = "phase B", .epoch = epoch_b };
try std.testing.expect(!goal_state.hasCurrent(root.todos.items, epoch_b)); // B starts with no plan
const refusal = try goal_state.completionGate(ar, &root);
try std.testing.expect(refusal != null and std.mem.indexOf(u8, refusal.?, "no checklist") != null);
try std.testing.expect(!goal_state.checklistFinished(&root)); // and no all-done list for the run to read
// A's work is retained and parked, exactly where it was left.
try std.testing.expectEqual(@as(usize, 1), root.todos.items.len);
try std.testing.expectEqual(@as(u64, 1), root.todos.items[0].epoch);
}
test "a cleared goal's OPEN items never become the next goal's work (#318)" {
var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena_state.deinit();
const ar = arena_state.allocator();
var root = flowRoot(ar);
root.goal = .{ .objective = "phase A", .epoch = 1 };
try root.todos.append(ar, .{ .content = "audit the old phase", .status = "pending", .epoch = 1 });
root.goal = null; // /goal clear parks the unfinished item
const epoch_b = goal_state.nextEpoch(root.goal, root.todos.items);
goal_state.adoptTodos(root.todos.items, goal_state.currentEpoch(root.goal), epoch_b);
root.goal = .{ .objective = "phase B", .epoch = epoch_b };
// The colliding epoch made A's leftover item read as B's open work - #318's
// literal reattachment complaint, reborn one /goal clear later.
try std.testing.expectEqual(@as(usize, 0), goal_state.openCount(root.todos.items, epoch_b));
try std.testing.expectEqual(@as(usize, 1), goal_state.parkedOpenCount(root.todos.items, epoch_b));
const refusal = try goal_state.completionGate(ar, &root);
try std.testing.expect(refusal != null and std.mem.indexOf(u8, refusal.?, "no checklist") != null);
try std.testing.expect(std.mem.indexOf(u8, refusal.?, "open checklist item") == null);
try std.testing.expectEqualStrings("", goal_state.renderCurrent(&root)); // B never renders A's list
}
test "a compaction does not move the goal note's diff-gate fingerprint (#318)" {
var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena_state.deinit();
const ar = arena_state.allocator();
var root = flowRoot(ar);
root.goal = .{ .objective = "ship phase 2", .epoch = 1 };
try root.todos.append(ar, .{ .content = "write the test", .status = "pending", .epoch = 1 });
// The restatement is HISTORY (compact() appends it to the handoff message),
// never steering. Routing it through goalSteeringNote would change that
// note's text on the turn after every compaction, re-fingerprinting the
// diff-gate whose entire job is to stop the checklist being re-pasted.
const before = try repl_glue.goalSteeringNote(ar, root.goal);
const snap = (try compactionSnapshot(ar, &root)).?;
root.goal_note_fp = 0; // the reset compact()/emergencyTrim really do perform
const after = try repl_glue.goalSteeringNote(ar, root.goal);
try std.testing.expectEqualStrings(before, after);
try std.testing.expect(std.mem.indexOf(u8, after, "write the test") == null); // the note still embeds no checklist
try std.testing.expect(std.mem.indexOf(u8, snap, "[ ] write the test") != null); // the snapshot is where it lives
// Both note variants now point at todo_read and warn that a todo_write
// REPLACES the list: rewriting it from a summary is exactly how the three
// completed items were lost after every compaction (#318).
const standing = try repl_glue.goalSteeringNote(ar, .{ .objective = "keep the tree green", .standing = true });
for ([_][]const u8{ after, standing }) |n| {
try std.testing.expect(std.mem.indexOf(u8, n, "todo_read") != null);
try std.testing.expect(std.mem.indexOf(u8, n, "REPLACES") != null);
}
}
test "continuationSteeringNote: checklist, generic, and the suppressed variant (#226/#318)" {
var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena_state.deinit();
const ar = arena_state.allocator();
const empty = try continuationSteeringNote(ar, "", true);
try std.testing.expect(std.mem.indexOf(u8, empty, "Checklist so far") == null);
try std.testing.expect(std.mem.indexOf(u8, empty, "continuing autonomously") != null);
const withlist = try continuationSteeringNote(ar, "[ ] add test", true);
try std.testing.expect(std.mem.indexOf(u8, withlist, "Checklist so far:\n[ ] add test") != null);
// Suppressed: the model is still told to work the checklist and where to
// find it, but gets no second copy of a list it has not changed.
const quiet = try continuationSteeringNote(ar, "[ ] add test", false);
try std.testing.expect(std.mem.indexOf(u8, quiet, "add test") == null);
try std.testing.expect(std.mem.indexOf(u8, quiet, "Checklist so far") == null);
try std.testing.expect(std.mem.indexOf(u8, quiet, "keep working the current checklist (unchanged") != null);
try std.testing.expect(std.mem.indexOf(u8, quiet, "todo_read") != null);
}
test "LoopListGate pastes the checklist once per change, not once per turn (#318)" {
var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena_state.deinit();
const ar = arena_state.allocator();
var root = flowRoot(ar);
root.goal = .{ .objective = "ship", .epoch = 1 };
try root.todos.append(ar, .{ .content = "a", .status = "pending", .epoch = 1 });
try root.todos.append(ar, .{ .content = "b", .status = "pending", .epoch = 1 });
var gate: LoopListGate = .{};
// Turn 1 of a run carries the list; the next turns do not, so a 25-turn
// run no longer writes 25 near-identical copies into root.messages (all
// autosaved, and all fed verbatim into the next compaction's summary).
try std.testing.expect(std.mem.indexOf(u8, try gate.note(ar, &root), "[ ] a") != null);
var i: usize = 0;
while (i < 3) : (i += 1)
try std.testing.expect(std.mem.indexOf(u8, try gate.note(ar, &root), "[ ] a") == null);
// A real change to the list is carried immediately.
root.todos.items[0].status = "completed";
try std.testing.expect(std.mem.indexOf(u8, try gate.note(ar, &root), "[x] a") != null);
// An unchanged list is re-stated after the refresh interval, in case it
// aged out of the model's effective attention.
i = 0;
var restated = false;
while (i < goal_state.refresh_turns) : (i += 1)
restated = restated or std.mem.indexOf(u8, try gate.note(ar, &root), "[x] a") != null;
try std.testing.expect(restated);
// A history rewrite (compaction or emergency trim, possibly MID-turn where
// no post-turn hook fires) destroyed every pasted copy: the next
// continuation re-carries the list in full, then gates again.
_ = try gate.note(ar, &root); // settle into suppression
root.history_rewrites += 1;
try std.testing.expect(std.mem.indexOf(u8, try gate.note(ar, &root), "[x] a") != null);
try std.testing.expect(std.mem.indexOf(u8, try gate.note(ar, &root), "[x] a") == null);
// reset() is what a fresh run, a user steer and a stop do: the very next
// continuation carries the list in full again.
gate.reset();
try std.testing.expect(std.mem.indexOf(u8, try gate.note(ar, &root), "[x] a") != null);
}
test "re-applying --goal on resume keeps the same objective's own checklist (#318)" {
var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
defer arena_state.deinit();
const ar = arena_state.allocator();
var root = flowRoot(ar);
// Run 1 of `graff -r sess --goal X` wrote a checklist under the standing
// goal. Run 2 of the IDENTICAL command must find that work, not park it:
// re-minting an epoch on every restart orphaned the objective's own list.
root.goal = standingGoalFromFlag("keep the tree green", null, root.todos.items, 7);
try root.todos.append(ar, .{ .content = "a", .status = "completed", .epoch = 1 });
try root.todos.append(ar, .{ .content = "b", .status = "pending", .epoch = 1 });
try std.testing.expect((try reapplyFlagGoal(ar, &root, "keep the tree green", 9)) == null);
try std.testing.expectEqual(@as(u64, 1), root.goal.?.epoch);
try std.testing.expectEqual(@as(i64, 7), root.goal.?.created_ms); // the restored goal, not a re-mint
try std.testing.expectEqualStrings("[x] a\n[ ] b", goal_state.renderCurrent(&root));
// A saved pause does not survive the flag: --goal typed TODAY means steer.
// Restored verbatim, a paused standing goal produced no steering and no
// completion gate at all, silently, in exactly the flag's headless flows.
root.goal.?.status = .paused;
try std.testing.expect((try reapplyFlagGoal(ar, &root, "keep the tree green", 10)) == null);
try std.testing.expectEqual(agent_mod.GoalStatus.active, root.goal.?.status);
try std.testing.expectEqual(@as(u64, 1), root.goal.?.epoch); // still the same goal, not a re-mint
try std.testing.expect(goal_state.goalActive(&root));
// A DIFFERENT flag objective displaces a live restored /goal like any
// supersession: new standing goal above every epoch, and the note reports
// the parked work so the model does not silently continue it.
root.goal = .{ .objective = "ship phase 2", .epoch = 1, .status = .active };
root.completion_gate_armed = true; // a stale arm must not survive the boundary
const note = try reapplyFlagGoal(ar, &root, "keep master green", 11);
try std.testing.expect(note != null and std.mem.indexOf(u8, note.?, "ship phase 2") != null);
try std.testing.expect(root.goal.?.standing);
try std.testing.expectEqual(@as(u64, 2), root.goal.?.epoch);
try std.testing.expect(!root.completion_gate_armed);
try std.testing.expectEqual(@as(usize, 1), goal_state.parkedOpenCount(root.todos.items, 2)); // b parked, never adopted
// Displacing an already-complete goal queues nothing: its work already
// parked when it retired, so there is no live boundary to announce.
root.goal.?.standing = false;
root.goal.?.status = .complete;
try std.testing.expect((try reapplyFlagGoal(ar, &root, "keep the tree green", 12)) == null);
try std.testing.expect(root.goal.?.standing and root.goal.?.status == .active);
}