Gate agent completion on commits, pushes, and tests; capture real checkpoints

Agents could be marked done while leaving work uncommitted or unpushed:
the Stop gate only ran the test suite, and the headless supervisor's
fallback marked any still-working agent done on a clean process exit
even when the Stop gate never recorded a verdict. Checkmarks also only
ever carried hook-written boilerplate, so the webui had no real
checkpoint to show.

The Stop gate now blocks the turn on any of: failing tests, uncommitted
changes, or commits no origin/* ref contains (rev-list --not
--remotes=origin, so it works for the --no-track worktree branches).
All blockers are reported at once; status 'done' only ever accompanies
a fully passing gate. Working dirs that aren't git checkouts, and repos
without an origin remote, skip the git half so local-only projects
can't deadlock. The supervisor's clean-exit fallback now reconciles a
still-working agent to blocked instead of done — done is a gate
verdict, not an exit code (operator cancels still settle as done).

The agent's final message is captured deterministically from the
session transcript onto the checkmark's where_it_stopped, so the
dashboard always shows a real checkpoint regardless of whether the
agent thought to leave one; a blocked checkmark shows the blockers.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01V7mF6qeryi9nJthaxYkfPm

tests/test_headless_run.py

@@ -81,7 +81,9 @@ def test_spawn_run_streams_events_and_completes(headless_env, tmp_path):
     assert [e["seq"] for e in events] == [1, 2, 3]
     # last_output is now derived from assistant text — the log the UI shows is real.
     assert updated["last_output"] == "working on: build the thing"
-    assert updated["status"] == "done"
+    # done is a gate outcome, not an exit code: the fake claude never ran the Stop
+    # hook, so nothing verified tests/commits/pushes and the agent must not be done.
+    assert updated["status"] == "blocked"
     assert updated["session_id"] == run["session_id"]
     assert updated["worker_id"] == "w1"
     # The session archive was uploaded at exit for cross-worker resume.

tests/test_hook_checkpoint.py

@@ -20,13 +20,22 @@ def _fake_mise_state(monkeypatch, *, has_test, clean, ahead):
     monkeypatch.setattr(gitops, "ahead_count", lambda cwd: ahead)
 
 
+def _fake_git_state(monkeypatch, *, is_repo=True, clean=True, unpushed=0, has_origin=True):
+    monkeypatch.setattr(gitops, "head_sha", lambda cwd: "abc123" if is_repo else None)
+    monkeypatch.setattr(gitops, "is_clean", lambda cwd: clean)
+    monkeypatch.setattr(gitops, "has_origin", lambda cwd: has_origin)
+    monkeypatch.setattr(gitops, "unpushed_count", lambda cwd: unpushed)
+
+
 def test_stop_blocks_on_failing_tests(conn, monkeypatch):
     ident = _seed(conn)
     monkeypatch.setattr(verify, "run_test", lambda cwd: (False, "1 failed"))
+    _fake_git_state(monkeypatch)
 
     result = checkpoint.handle_stop(conn, ident, HookInput({"session_id": "s1"}, "stop"))
     assert result["decision"] == "block"
-    assert "test gate failed" in result["reason"]
+    assert "test suite is failing" in result["reason"]
+    assert "1 failed" in result["reason"]
 
     cm = repo.get_checkmark(conn, ident.agent_id)
     assert cm["tests_status"] == "fail"
@@ -35,9 +44,59 @@ def test_stop_blocks_on_failing_tests(conn, monkeypatch):
     assert repo.get_agent_by_name(conn, "p", "a")["status"] == "blocked"
 
 
-def test_stop_allows_done_on_passing_tests(conn, monkeypatch):
+def test_stop_blocks_on_uncommitted_changes_even_with_green_tests(conn, monkeypatch):
     ident = _seed(conn)
     monkeypatch.setattr(verify, "run_test", lambda cwd: (True, "ok"))
+    _fake_git_state(monkeypatch, clean=False)
+
+    result = checkpoint.handle_stop(conn, ident, HookInput({"session_id": "s1"}, "stop"))
+    assert result["decision"] == "block"
+    assert "uncommitted" in result["reason"]
+
+    cm = repo.get_checkmark(conn, ident.agent_id)
+    assert cm["tests_status"] == "pass"  # tests still recorded honestly
+    assert cm["status"] == "blocked"
+    assert repo.get_agent_by_name(conn, "p", "a")["status"] == "blocked"
+
+
+def test_stop_blocks_on_unpushed_commits(conn, monkeypatch):
+    ident = _seed(conn)
+    monkeypatch.setattr(verify, "run_test", lambda cwd: (True, "ok"))
+    _fake_git_state(monkeypatch, unpushed=3)
+
+    result = checkpoint.handle_stop(conn, ident, HookInput({"session_id": "s1"}, "stop"))
+    assert result["decision"] == "block"
+    assert "3 commit(s) exist only locally" in result["reason"]
+    assert repo.get_agent_by_name(conn, "p", "a")["status"] == "blocked"
+
+
+def test_stop_reports_every_blocker_at_once(conn, monkeypatch):
+    ident = _seed(conn)
+    monkeypatch.setattr(verify, "run_test", lambda cwd: (False, "boom"))
+    _fake_git_state(monkeypatch, clean=False, unpushed=1)
+
+    result = checkpoint.handle_stop(conn, ident, HookInput({"session_id": "s1"}, "stop"))
+    assert "test suite is failing" in result["reason"]
+    assert "uncommitted" in result["reason"]
+    assert "exist only locally" in result["reason"]
+
+
+def test_stop_skips_push_gate_without_an_origin_remote(conn, monkeypatch):
+    ident = _seed(conn)
+    monkeypatch.setattr(verify, "run_test", lambda cwd: (True, "ok"))
+    # Local-only project: commits exist that no remote has, but there is no origin
+    # to push them to — the push gate must not deadlock the agent.
+    _fake_git_state(monkeypatch, unpushed=5, has_origin=False)
+
+    result = checkpoint.handle_stop(conn, ident, HookInput({"session_id": "s1"}, "stop"))
+    assert result == {}
+    assert repo.get_checkmark(conn, ident.agent_id)["status"] == "done"
+
+
+def test_stop_allows_done_when_tests_pass_and_tree_is_settled(conn, monkeypatch):
+    ident = _seed(conn)
+    monkeypatch.setattr(verify, "run_test", lambda cwd: (True, "ok"))
+    _fake_git_state(monkeypatch)
 
     result = checkpoint.handle_stop(conn, ident, HookInput({"session_id": "s1"}, "stop"))
     assert result == {}  # no block
@@ -48,9 +107,60 @@ def test_stop_allows_done_on_passing_tests(conn, monkeypatch):
     assert cm["log_entry_id"] is not None
 
 
+def test_stop_allows_done_when_working_dir_is_not_a_repo(conn, monkeypatch):
+    # A manually managed root has nothing to gate beyond its tests.
+    ident = _seed(conn)
+    monkeypatch.setattr(verify, "run_test", lambda cwd: (True, "ok"))
+    _fake_git_state(monkeypatch, is_repo=False, clean=False, unpushed=9)
+
+    result = checkpoint.handle_stop(conn, ident, HookInput({"session_id": "s1"}, "stop"))
+    assert result == {}
+    assert repo.get_checkmark(conn, ident.agent_id)["status"] == "done"
+
+
+def test_stop_captures_final_message_as_checkpoint(conn, monkeypatch, tmp_path):
+    ident = _seed(conn)
+    monkeypatch.setattr(verify, "run_test", lambda cwd: (True, "ok"))
+    _fake_git_state(monkeypatch)
+    transcript = tmp_path / "session.jsonl"
+    transcript.write_text(
+        '{"type": "user", "message": {"content": "do the thing"}}\n'
+        "this line is not json\n"
+        '{"type": "assistant", "message": {"content": [{"type": "text", '
+        '"text": "Working on it."}]}}\n'
+        '{"type": "assistant", "message": {"content": [{"type": "tool_use", "id": "x"},'
+        ' {"type": "text", "text": "Shipped the fix in abc123; tests green."}]}}\n'
+    )
+
+    hi = HookInput({"session_id": "s1", "transcript_path": str(transcript)}, "stop")
+    result = checkpoint.handle_stop(conn, ident, hi)
+    assert result == {}
+    cm = repo.get_checkmark(conn, ident.agent_id)
+    # The webui checkpoint carries the agent's own closing message, captured
+    # deterministically from the transcript — not left to the agent's discretion.
+    assert cm["where_it_stopped"] == "Shipped the fix in abc123; tests green."
+
+
+def test_blocked_stop_shows_blockers_not_narrative(conn, monkeypatch, tmp_path):
+    ident = _seed(conn)
+    monkeypatch.setattr(verify, "run_test", lambda cwd: (True, "ok"))
+    _fake_git_state(monkeypatch, clean=False)
+    transcript = tmp_path / "session.jsonl"
+    transcript.write_text(
+        '{"type": "assistant", "message": {"content": [{"type": "text", '
+        '"text": "All done!"}]}}\n'
+    )
+
+    hi = HookInput({"session_id": "s1", "transcript_path": str(transcript)}, "stop")
+    checkpoint.handle_stop(conn, ident, hi)
+    cm = repo.get_checkmark(conn, ident.agent_id)
+    assert "uncommitted" in cm["where_it_stopped"]
+
+
 def test_stop_does_not_reblock_when_already_active(conn, monkeypatch):
     ident = _seed(conn)
     monkeypatch.setattr(verify, "run_test", lambda cwd: (False, "still failing"))
+    _fake_git_state(monkeypatch)
     hi = HookInput({"session_id": "s1", "stop_hook_active": True}, "stop")
     result = checkpoint.handle_stop(conn, ident, hi)
     assert result == {}  # recorded, but not an infinite block

tests/test_integration_web_spawn.py

@@ -71,13 +71,15 @@ def test_spawn_via_api_then_worker_runs_headless_claude(client, auth, headless_e
     assert got["result"]["name"] == "api"
 
     # ...and the run's whole life shows up via the API: events stream in, the agent
-    # reconciles to done, last_output is the assistant's text.
+    # reconciles, last_output is the assistant's text. The fake claude never runs the
+    # Stop gate, so the clean exit reconciles to blocked, not done — done is only ever
+    # a gate verdict (tests pass, work committed and pushed).
     def finished():
         agents = client.get("/projects/proj/agents", headers=auth).json()
-        return agents if agents and agents[0]["status"] == "done" else None
+        return agents if agents and agents[0]["status"] == "blocked" else None
 
     agents = _wait(finished)
-    assert agents is not None, "run never reconciled to done"
+    assert agents is not None, "run never reconciled"
     agent = agents[0]
     assert agent["name"] == "api"
     assert agent["session_id"]