@kendoo.agentdesk/agentdesk 0.31.1 → 0.32.1

package/CHANGELOG.md

@@ -8,6 +8,21 @@ All user-facing changes to AgentDesk. Each entry is tagged:
 
 Internal refactors, infrastructure changes, and architectural notes are not listed here.
 
+## [0.32.1] — 2026-09-21
+
+### Fixed
+- `[CLI]` The publish and history gates now understand the command they are looking at. `git -C . push`, `env git push`, a `git push` on a second line, `sh -c 'git push'`, `/usr/bin/git push` and similar spellings used to slip past both Sam's audit gate and the verification; the engine now parses the shell command and classifies what it actually runs, and refuses anything it cannot model when the text hints at publishing.
+- `[CLI]` A cached verification pass is only reused for the exact tree it ran on — same commit *and* a clean working tree, then and now. Uncommitted edits left `HEAD` unchanged, so later publish attempts and the review could reuse stale evidence; they now run the checks again. An approval is also invalidated by uncommitted changes appearing after it in a session worktree.
+- `[CLI]` Sam finishing his audit no longer counts as approving it. Sam ends his report with `AUDIT: APPROVED` or `AUDIT: REJECTED — <why>`; the engine reads that line, ties an approval to the commit he audited, and refuses to publish after a rejection, without the line, or once a newer commit exists — until he audits again. The verdict shows in the feed and in the handoff ledger.
+
+## [0.32.0] — 2026-09-21
+
+### Changed
+- `[CLI]` Publishing is verified on the spot. When the team runs `git push` or `gh pr create`, the engine runs the project's `test`/`build`/`lint` at the commit being published and refuses with the failing output until a new commit passes; the review that follows reuses a passing run instead of running everything twice. Reviewers can no longer push or change history either.
+- `[CLI]` A phase that ends without its structured handoff is run again once; if it misses again the session ends for human review instead of letting the next phase start from nothing.
+- `[UI]` A Delivery strip above the conversation shows the engine's verification results (each command, pass/fail, failing output), the open items carried between phases, and the phase-by-phase handoff timeline with commit changes — live, and after a restart.
+- `[UI]` The conversation defaults to a product view: the lead's narrative stays inline, the team's reports fold into one expandable row, and tool calls and status notes are hidden. Switch to Full in the session row to see everything; the choice is remembered.
+
 ## [0.31.1] — 2026-09-21
 
 ### Fixed

package/README.md

@@ -265,7 +265,7 @@ Valid values: `"default"`, `"opus"`, `"sonnet"`, `"haiku"`. `"default"` resolves
 
 The `REVIEW` phase is a read-only completeness check (no code changes) — it verifies the implementation meets requirements, flags missed documentation updates or silently-deferred scope. If gaps are found, the orchestrator loops back to `EXECUTION` once before moving on. The `SUMMARY` phase writes the final tracker comments and session protocol.
 
-Before the reviewers are asked, the engine runs the project's own checks itself — `commands.test`, `commands.build` and `commands.lint` from project settings, or the `test`/`build`/`lint` scripts in `package.json` when those are unset — inside the session sandbox, at the current commit. A failing check goes straight back to `EXECUTION` with the real output as findings; the reviewers are only asked once the checks pass. An approval is pinned to that commit: if the code changes afterwards, the approval no longer counts and the session ends for human review instead of reporting success. In a session worktree, uncommitted changes block review too — an approval refers to a committed revision. `SUMMARY` cannot commit, move `HEAD`, or push; it writes messages only.
+Before the reviewers are asked, the engine runs the project's own checks itself — `commands.test`, `commands.build` and `commands.lint` from project settings, or the `test`/`build`/`lint` scripts in `package.json` when those are unset — inside the session sandbox, at the current commit. A failing check goes straight back to `EXECUTION` with the real output as findings; the reviewers are only asked once the checks pass. An approval is pinned to that commit: if the code changes afterwards, the approval no longer counts and the session ends for human review instead of reporting success. In a session worktree, uncommitted changes block review too — an approval refers to a committed revision. Publishing is verified the same way, on the spot: when the team runs `git push` or `gh pr create` — however the command is spelled (`git -C . push`, `env git push`, on a later line, inside `sh -c`) — the engine runs the checks at the revision being published and refuses with the failing output until a new commit passes. A passing run is evidence for one tree only: the same commit with a clean working tree, then and now. It is reused by the review that follows only while that still holds; uncommitted changes force a fresh run. Publishing also needs Sam's explicit verdict: he ends his audit with `AUDIT: APPROVED` or `AUDIT: REJECTED`, the engine reads that line and ties an approval to the commit he read — a rejection, a report without the line, or a commit made after his approval keeps publishing closed until he audits again. `REVIEW` and `SUMMARY` cannot commit, move `HEAD`, or push; they read and write messages only.
 
 The team follows the task. `INTAKE` assesses the scope — `small` or `standard`, and which areas the change touches (`ui`, `copy`, `docs`, `api`, `data`). A small task skips `PLAN` (Dennis states the approach at the start of `EXECUTION`) and is reviewed by Bart and Vera; Sam's architecture audit still gates the PR inside `EXECUTION`. Luna, Mark and Nora join only when the task touches UI, user-facing copy or docs respectively. Set `"teamProfile": "small"` or `"standard"` in `.agentdesk.json` to force it (`"auto"`, the default, lets `INTAKE` decide).
 

package/cli/engine/agents/index.mjs

@@ -12,6 +12,7 @@
 // belt to these braces.
 
 import { BUILT_IN_AGENTS } from "../../agents.mjs";
+import { AUDITOR, AUDIT_INSTRUCTION } from "../hooks.mjs";
 
 export const LEAD = "Jane";
 export const READ_ONLY = Object.freeze(["Read", "Grep", "Glob"]);
@@ -85,6 +86,9 @@ export function agentSystemPrompt(a, phase) {
     "",
     PHASE_GUIDANCE[phase] || "",
     phase === "EXECUTION" ? executionTasks(a) : "",
+    // The audit verdict is read by the engine, so the instruction lives here,
+    // not in a customisable task list.
+    phase === "EXECUTION" && a.name === AUDITOR ? `\n${AUDIT_INSTRUCTION}\n` : "",
     "",
     "No announcement without observation: never claim something is done, passes, or works unless you ran the check and read its output. If the observation is out of reach, say so plainly.",
     `Report back to ${LEAD} concisely. You may prefix a message with [THINK], [ACT], [ARGUE] or [AGREE] to make your stance clear.`,

package/cli/engine/commands.mjs

@@ -0,0 +1,162 @@
+// Shell command classification for the publish and history gates.
+//
+// A regex over the raw text is not enforcement: `git -C . push`, `env git
+// push`, a newline before `git push`, `sh -c 'git push'`, `/usr/bin/git
+// push` all publish. This tokenizes the command the way a POSIX shell
+// would, splits it into simple commands, unwraps environment prefixes and
+// wrapper programs, and classifies each simple command by its effective
+// program and subcommand. Constructs it does not model (command
+// substitution, backticks, heredocs, process substitution) are marked
+// unparseable and fail closed whenever the text hints at publishing.
+
+const OPERATORS = ["&&", "||", ";;", "|&", ";", "|", "&", "\n", "(", ")", "{", "}"];
+const WRAPPERS_NO_ARGS = new Set(["command", "exec", "nohup", "time", "builtin", "caffeinate", "chronic", "nocorrect", "noglob"]);
+const PUBLISH_GIT = new Set(["push", "send-pack"]);
+const HISTORY_GIT = new Set(["commit", "merge", "rebase", "reset", "checkout", "switch", "cherry-pick", "revert", "am", "apply", "stash", "restore", "clean"]);
+const PUBLISH_GH_PR = new Set(["create", "merge", "ready", "reopen", "edit"]);
+const GIT_GLOBAL_WITH_ARG = new Set(["-C", "-c", "--git-dir", "--work-tree", "--namespace", "--exec-path", "--super-prefix", "--config-env", "--list-cmds", "--attr-source"]);
+const PUBLISH_HINT = /\b(push|send-pack|pr\s+(create|merge|ready|reopen|edit)|release\s+create|repo\s+sync|gh\s+api)\b/i;
+
+// POSIX-ish tokenizer: words with quote/escape handling, operators, and a
+// flag for constructs we do not model.
+export function tokenize(command) {
+  const text = String(command || "");
+  const tokens = [];
+  let word = "", inWord = false, quote = null, unparseable = false;
+  const push = () => { if (inWord) { tokens.push({ word }); word = ""; inWord = false; } };
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (quote === "'") { if (ch === "'") quote = null; else word += ch; continue; }
+    if (quote === '"') {
+      if (ch === '"') { quote = null; continue; }
+      if (ch === "\\" && i + 1 < text.length && /["\\$`\n]/.test(text[i + 1])) { word += text[++i]; continue; }
+      if (ch === "`" || (ch === "$" && text[i + 1] === "(")) unparseable = true;
+      word += ch; continue;
+    }
+    if (ch === "\\") { if (i + 1 < text.length) { word += text[++i]; inWord = true; } continue; }
+    if (ch === "'" || ch === '"') { quote = ch; inWord = true; continue; }
+    if (ch === "`" || (ch === "$" && text[i + 1] === "(") || (ch === "<" && text[i + 1] === "(") || (ch === ">" && text[i + 1] === "(")) { unparseable = true; word += ch; inWord = true; continue; }
+    if (ch === "<" && text[i + 1] === "<") { unparseable = true; word += ch; inWord = true; continue; }
+    if (/\s/.test(ch) && ch !== "\n") { push(); continue; }
+    const op = OPERATORS.find(o => text.startsWith(o, i));
+    if (op) { push(); tokens.push({ op }); i += op.length - 1; continue; }
+    word += ch; inWord = true;
+  }
+  if (quote) unparseable = true;
+  push();
+  return { tokens, unparseable };
+}
+
+// Splits tokens into simple commands (lists of words); operators and
+// grouping punctuation only separate.
+export function splitCommands(tokens) {
+  const commands = [];
+  let current = [];
+  for (const t of tokens) {
+    if (t.op !== undefined) { if (current.length) commands.push(current); current = []; }
+    else current.push(t.word);
+  }
+  if (current.length) commands.push(current);
+  return commands;
+}
+
+const basename = word => String(word).split("/").pop();
+const isAssignment = word => /^[A-Za-z_][A-Za-z0-9_]*=/.test(word);
+
+// Returns the effective simple command with prefixes and wrappers removed,
+// or a list of nested commands when a wrapper carries a shell string.
+export function unwrap(words, depth = 0) {
+  const rest = [...words];
+  for (let guard = 0; guard < 16 && rest.length; guard++) {
+    while (rest.length && isAssignment(rest[0])) rest.shift();
+    if (!rest.length) return { words: [] };
+    const prog = basename(rest[0]);
+    if (WRAPPERS_NO_ARGS.has(prog)) { rest.shift(); continue; }
+    if (prog === "env") {
+      rest.shift();
+      while (rest.length) {
+        if (rest[0] === "-S" || rest[0] === "--split-string") return { unparseable: true, words: rest };
+        if (rest[0] === "-u" || rest[0] === "-C" || rest[0] === "--unset" || rest[0] === "--chdir") { rest.splice(0, 2); continue; }
+        if (rest[0].startsWith("-") && rest[0] !== "--") { rest.shift(); continue; }
+        if (rest[0] === "--") { rest.shift(); break; }
+        if (isAssignment(rest[0])) { rest.shift(); continue; }
+        break;
+      }
+      continue;
+    }
+    if (prog === "sudo" || prog === "doas") {
+      rest.shift();
+      while (rest.length && rest[0].startsWith("-")) { const flag = rest.shift(); if (["-u", "-g", "-p", "-C", "-D", "-h", "-r", "-t", "-U", "-T"].includes(flag)) rest.shift(); }
+      continue;
+    }
+    if (prog === "timeout") { rest.shift(); while (rest.length && rest[0].startsWith("-")) { const f = rest.shift(); if (["-k", "-s", "--kill-after", "--signal"].includes(f)) rest.shift(); } rest.shift(); continue; }
+    if (prog === "nice" || prog === "ionice" || prog === "stdbuf") { rest.shift(); while (rest.length && rest[0].startsWith("-")) { const f = rest.shift(); if (/^-[nc]$|^-[oei]$/.test(f)) rest.shift(); } continue; }
+    if (prog === "xargs") { rest.shift(); while (rest.length && rest[0].startsWith("-")) { const f = rest.shift(); if (/^-[nILPsdEa]$|^--max-args$|^--replace$|^--max-procs$|^--delimiter$|^--arg-file$/.test(f)) rest.shift(); } continue; }
+    if (["sh", "bash", "zsh", "dash", "ksh", "fish"].includes(prog)) {
+      // `-c` may be combined with other single-letter flags (`bash -lc '…'`).
+      for (let i = 1; i < rest.length; i++) {
+        const w = rest[i];
+        if (/^-[A-Za-z]*c[A-Za-z]*$/.test(w) || w === "--command") { if (rest[i + 1] !== undefined) return { nested: classify(rest[i + 1], depth + 1) }; break; }
+        if (w === "-o" || w === "+o") { i++; continue; }
+        if (!w.startsWith("-") && !w.startsWith("+")) break; // a script file: its contents are not visible here
+      }
+      return { words: rest };
+    }
+    if (prog === "eval") return { nested: classify(rest.slice(1).join(" "), depth + 1) };
+    return { words: [prog, ...rest.slice(1)] };
+  }
+  return { words: rest };
+}
+
+function classifyGit(args) {
+  let i = 0, configOverride = false;
+  while (i < args.length) {
+    const a = args[i];
+    if (GIT_GLOBAL_WITH_ARG.has(a)) { if (a === "-c" && /hooksPath|receive\.|push\./i.test(args[i + 1] || "")) configOverride = true; i += 2; continue; }
+    if (a.startsWith("--") && a.includes("=")) { if (/^--config-env=|^-c=/.test(a)) configOverride = true; i++; continue; }
+    if (a.startsWith("-")) { i++; continue; }
+    break;
+  }
+  const sub = args[i];
+  return { publishes: PUBLISH_GIT.has(sub) || configOverride, history: HISTORY_GIT.has(sub), sub };
+}
+
+function classifyGh(args) {
+  const [a, b] = args;
+  if (a === "pr" && PUBLISH_GH_PR.has(b)) return { publishes: true };
+  if (a === "release" && b === "create") return { publishes: true };
+  if (a === "repo" && (b === "sync" || b === "create")) return { publishes: true };
+  if (a === "api") {
+    const mutating = args.some((w, i) => (["-X", "--method"].includes(w) && /^(POST|PUT|PATCH|DELETE)$/i.test(args[i + 1] || "")) ||
+      /^--method=(POST|PUT|PATCH|DELETE)$/i.test(w) || ["-f", "-F", "--field", "--raw-field", "--input"].includes(w) || /^--(raw-)?field=/.test(w));
+    return { publishes: mutating };
+  }
+  return { publishes: false };
+}
+
+// classify(command) → { publishes, history, unparseable }
+//   publishes  — pushes commits or creates/changes a PR (or cannot be
+//                ruled out because the syntax is not modelled and the text
+//                hints at it)
+//   history    — commits, moves HEAD, or rewrites the tree
+//   unparseable — contains constructs this parser does not model
+export function classify(command, depth = 0) {
+  const result = { publishes: false, history: false, unparseable: false };
+  if (depth > 4) return { ...result, publishes: true, unparseable: true };
+  const { tokens, unparseable } = tokenize(command);
+  if (unparseable) result.unparseable = true;
+  for (const words of splitCommands(tokens)) {
+    const u = unwrap(words, depth);
+    if (u.unparseable) { result.unparseable = true; continue; }
+    if (u.nested) {
+      result.publishes ||= u.nested.publishes; result.history ||= u.nested.history; result.unparseable ||= u.nested.unparseable;
+      continue;
+    }
+    const [prog, ...args] = u.words;
+    if (!prog) continue;
+    if (prog === "git") { const g = classifyGit(args); result.publishes ||= g.publishes; result.history ||= g.history; }
+    else if (prog === "gh") { result.publishes ||= classifyGh(args).publishes; }
+  }
+  if (result.unparseable && PUBLISH_HINT.test(String(command || ""))) result.publishes = true;
+  return result;
+}

package/cli/engine/evidence.mjs

@@ -132,13 +132,15 @@ export async function runChecks({ checks = [], cwd, env = {}, gitEnv: extraGitEn
 }
 
 // An approval stands only on: an explicit APPROVED, passing checks, and the
-// same revision the checks and reviewers saw.
-export function evaluateApproval({ verdict, evidence, headNow }) {
+// same tree the checks and reviewers saw — same revision, and (where a clean
+// tree is required) still clean.
+export function evaluateApproval({ verdict, evidence, headNow, cleanNow }) {
   if (!verdict || verdict.outcome !== "APPROVED") return { approved: false, reason: "review did not approve" };
   if (evidence && !evidence.passed) return { approved: false, reason: evidence.aborted ? "verification was cancelled" : "engine checks did not pass" };
   if (evidence?.revision && headNow && evidence.revision !== headNow) {
     return { approved: false, reason: `code changed after verification (${shortRev(evidence.revision)} → ${shortRev(headNow)})` };
   }
+  if (evidence?.requireClean && cleanNow === false) return { approved: false, reason: "uncommitted changes appeared during review" };
   return { approved: true, reason: null };
 }
 

package/cli/engine/hooks.mjs

@@ -8,49 +8,117 @@
 //
 // decidePreToolUse() is pure so the policy is unit-tested without the SDK.
 
+import { classify } from "./commands.mjs";
+
 export const MUTATING_TOOLS = Object.freeze(new Set(["Edit", "Write", "MultiEdit", "NotebookEdit"]));
 export const CODE_TOOLS = Object.freeze(new Set([...MUTATING_TOOLS, "Bash"]));
 
-// Commands that publish work. Matched loosely on purpose: `gh pr create`,
-// `git push`, `git push --force-with-lease origin HEAD`, chained after `&&`.
-const PUBLISH_RE = /(^|[;&|]\s*)(gh\s+pr\s+create|git\s+push)\b/;
-
+// Commands that publish work: `git push`, `gh pr create` and their relatives,
+// however they are spelled — `git -C . push`, `env git push`, on a later
+// line, inside `sh -c`, behind `sudo`. commands.mjs parses the shell text;
+// anything it cannot model fails closed when the text hints at publishing.
 export function isPublishCommand(command) {
-  return PUBLISH_RE.test(String(command || ""));
+  return classify(command).publishes;
 }
 
 // Commands that move HEAD or rewrite the tree. SUMMARY reports on an approved
 // revision; it must not be able to change which revision that is.
-const HISTORY_RE = /(^|[;&|]\s*)git\s+(commit|merge|rebase|reset|checkout|switch|cherry-pick|revert|am|apply|stash|restore|clean)\b/;
-
 export function isHistoryCommand(command) {
-  return HISTORY_RE.test(String(command || ""));
+  return classify(command).history;
 }
 
 // The auditor whose sign-off gates publishing. "Sam's audit is a blocking
-// gate — not advisory" used to be prose; now it is the observable fact that a
-// Sam subagent finished in this EXECUTION phase (SubagentStop).
+// gate — not advisory" used to be prose; now it is an explicit verdict the
+// engine reads from his report and ties to the revision he audited.
 export const AUDITOR = "Sam";
 
+// The last line of the auditor's report. Bold or plain, any case; an
+// optional commit after the verdict is checked against the real HEAD.
+const AUDIT_LINE_RE = /^[ \t]*(?:\*\*)?AUDIT:?(?:\*\*)?[ \t]*(?:\*\*)?(APPROVED|REJECTED)(?:\*\*)?\b(?:[ \t]*(?:at|@)?[ \t]*`?([0-9a-f]{7,40})`?)?/gim;
+
+export const AUDIT_INSTRUCTION = `End your report with exactly one line, on its own: \`AUDIT: APPROVED\` when the committed revision has no violations left, or \`AUDIT: REJECTED — <one line why>\` when it does. The engine reads that line: without it, or after REJECTED, nothing can be published. Audit committed code — a commit made after your approval needs a new audit.`;
+
+export function parseAuditVerdict(text) {
+  const s = String(text || "");
+  let m, last = null;
+  AUDIT_LINE_RE.lastIndex = 0;
+  while ((m = AUDIT_LINE_RE.exec(s))) last = m;
+  if (!last) return { verdict: "MISSING", statedRevision: null };
+  return { verdict: last[1].toUpperCase(), statedRevision: last[2] || null };
+}
+
+// The text of a tool result, whatever shape the harness hands it in.
+export function responseText(response) {
+  if (response == null) return "";
+  if (typeof response === "string") return response;
+  if (Array.isArray(response)) return response.map(responseText).filter(Boolean).join("\n");
+  if (typeof response === "object") {
+    if (typeof response.text === "string") return response.text;
+    if (response.content !== undefined) return responseText(response.content);
+    if (typeof response.result === "string") return response.result;
+    if (typeof response.output === "string") return response.output;
+  }
+  return "";
+}
+
 // Called at the start of every EXECUTION: nothing may be published until the
-// auditor has run in this phase. `openFindings` (from a rejected REVIEW) is
-// carried for the denial message so the team sees what is outstanding.
+// auditor has approved in this phase. `openFindings` (from a rejected REVIEW)
+// is carried for the denial message so the team sees what is outstanding.
 export function armPublishGate(state, openFindings = []) {
   state.awaitingAudit = true;
+  state.audit = null;
   state.openFindings = Array.isArray(openFindings) ? openFindings : [];
 }
 
-export function onSubagentStopped(state, { phase, agentType }) {
-  if (phase === "EXECUTION" && agentType === AUDITOR) {
-    state.awaitingAudit = false;
-    state.openFindings = [];
+// Records the auditor's verdict for the tree as it is right now.
+//   tree — { revision, clean } observed by the engine when the report arrived
+// Returns the audit record, or null when the report is not the auditor's in
+// EXECUTION. The latest report wins: a re-audit after fixes replaces the old.
+export function recordAudit(state, { phase, agentType, text, tree }) {
+  if (phase !== "EXECUTION" || agentType !== AUDITOR) return null;
+  const { verdict, statedRevision } = parseAuditVerdict(text);
+  const revision = tree?.revision ?? null;
+  const stale = !!(statedRevision && revision && !revision.startsWith(statedRevision));
+  const audit = { verdict: stale ? "STALE" : verdict, revision, clean: tree?.clean ?? null, statedRevision, at: new Date().toISOString() };
+  state.audit = audit;
+  state.awaitingAudit = audit.verdict !== "APPROVED";
+  if (audit.verdict === "APPROVED") state.openFindings = [];
+  return audit;
+}
+
+const short = rev => (rev ? String(rev).slice(0, 7) : "?");
+
+function auditDenial(state, treeNow) {
+  const open = Array.isArray(state.openFindings) ? state.openFindings : [];
+  const audit = state.audit;
+  const fixThenAudit = `have ${AUDITOR} audit the committed revision, fix what he flags, commit, have him re-audit, then publish`;
+  if (state.awaitingAudit || open.length > 0) {
+    const list = open.slice(0, 5).map(f => `- ${f.title || f}`).join("\n");
+    const findings = open.length > 0 ? `${open.length} review finding(s) are unresolved:\n${list}\n` : "";
+    let why;
+    if (audit?.verdict === "REJECTED") why = `${AUDITOR}'s audit REJECTED the change`;
+    else if (audit?.verdict === "STALE") why = `${AUDITOR} approved ${short(audit.statedRevision)} but the code is at ${short(audit.revision)}`;
+    else if (audit?.verdict === "MISSING") why = `${AUDITOR}'s report did not end with an AUDIT line`;
+    else why = `${AUDITOR} has not audited in this phase`;
+    return `Cannot publish yet — ${findings}${why}; ${fixThenAudit}.`;
   }
+  if (audit?.verdict === "APPROVED") {
+    const tree = typeof treeNow === "function" ? treeNow() : null;
+    if (tree?.revision && audit.revision && tree.revision !== audit.revision) {
+      return `Cannot publish: ${AUDITOR} approved ${short(audit.revision)} but HEAD is now ${short(tree.revision)} — the approval covers only the revision he read. Have ${AUDITOR} audit the new commits, then publish.`;
+    }
+    if (state.requireClean && audit.clean === false) {
+      return `Cannot publish: ${AUDITOR} audited while the tree had uncommitted changes, so his approval is not tied to a commit. Commit, have ${AUDITOR} audit the commit, then publish.`;
+    }
+  }
+  return null;
 }
 
-// input — the SDK PreToolUseHookInput ({ tool_name, tool_input, agent_id?, agent_type? }).
-//         `agent_id` is present only inside a subagent (BaseHookInput docs).
-// state — mutable session state; reads `awaitingAudit` and `openFindings`.
-export function decidePreToolUse({ phase, input, state = {} }) {
+// input   — the SDK PreToolUseHookInput ({ tool_name, tool_input, agent_id?, agent_type? }).
+//           `agent_id` is present only inside a subagent (BaseHookInput docs).
+// state   — mutable session state; reads `awaitingAudit`, `audit`, `openFindings`, `requireClean`.
+// treeNow — () => { revision, clean }; consulted only for a publish command.
+export function decidePreToolUse({ phase, input, state = {}, treeNow = state.treeNow }) {
   const tool = input?.tool_name;
   const isMainThread = !input?.agent_id;
 
@@ -69,6 +137,9 @@ export function decidePreToolUse({ phase, input, state = {} }) {
   if (phase === "REVIEW" && MUTATING_TOOLS.has(tool)) {
     return { decision: "deny", reason: "REVIEW is read-only: report findings; fixes happen back in EXECUTION." };
   }
+  if (phase === "REVIEW" && tool === "Bash" && (isPublishCommand(input?.tool_input?.command) || isHistoryCommand(input?.tool_input?.command))) {
+    return { decision: "deny", reason: "REVIEW is read-only: it cannot commit, move HEAD, or publish — the verdict refers to the revision as it is." };
+  }
 
   // The approval refers to one revision. SUMMARY may read it and talk about
   // it; it may not edit, commit, move HEAD, or publish.
@@ -81,17 +152,8 @@ export function decidePreToolUse({ phase, input, state = {} }) {
   }
 
   if (phase === "EXECUTION" && tool === "Bash" && isPublishCommand(input?.tool_input?.command)) {
-    const open = Array.isArray(state.openFindings) ? state.openFindings : [];
-    if (state.awaitingAudit || open.length > 0) {
-      const list = open.slice(0, 5).map(f => `- ${f.title || f}`).join("\n");
-      const why = open.length > 0
-        ? `${open.length} review finding(s) are unresolved:\n${list}\n`
-        : "";
-      return {
-        decision: "deny",
-        reason: `Cannot publish yet — ${why}${AUDITOR} must audit the changed files in this phase first (have the lead delegate the audit to ${AUDITOR}, fix what he flags, then publish).`,
-      };
-    }
+    const reason = auditDenial(state, treeNow);
+    if (reason) return { decision: "deny", reason };
   }
 
   return { decision: "allow" };
@@ -108,17 +170,28 @@ function denyOutput(reason) {
 }
 
 // Build the SDK `hooks` option for one phase.
-//   state         — shared session state (openFindings, ...)
+//   state         — shared session state (openFindings, audit, verifyPublish, treeNow, ...)
 //   onToolUse     — ({ agentType, tool, input }) for the dashboard
-//   onToolResult  — ({ agentType, tool, response }) for the dashboard
-//   onSubagentStop — ({ agentType }) when a subagent finishes
-export function hooksForPhase({ phase, state, onToolUse, onToolResult, onSubagentStop } = {}) {
+//   onToolResult  — ({ agentType, tool, input, actionId, response }) for the dashboard and the audit
+//   onSubagentStop — ({ agentType, text }) when a subagent finishes; `text` is its last message when the harness provides it
+//   verifyTimeoutSec — hook timeout for PreToolUse; publishing may run the
+//                      project's checks inside the hook (state.verifyPublish)
+export function hooksForPhase({ phase, state, onToolUse, onToolResult, onSubagentStop, verifyTimeoutSec } = {}) {
   return {
     PreToolUse: [{
+      ...(verifyTimeoutSec > 0 ? { timeout: verifyTimeoutSec } : {}),
       hooks: [async (input) => {
         onToolUse?.({ agentType: input.agent_type || null, tool: input.tool_name, input: input.tool_input });
         const d = decidePreToolUse({ phase, input, state });
-        return d.decision === "deny" ? denyOutput(d.reason) : {};
+        if (d.decision === "deny") return denyOutput(d.reason);
+        // Publishing is the one action the policy cannot judge from state
+        // alone: the engine verifies the revision being published, on the
+        // spot. state.verifyPublish is set by the session loop for EXECUTION.
+        if (phase === "EXECUTION" && input.tool_name === "Bash" && isPublishCommand(input.tool_input?.command) && typeof state?.verifyPublish === "function") {
+          const verdict = await state.verifyPublish();
+          if (!verdict?.ok) return denyOutput(verdict?.reason || "Cannot publish: verification did not pass.");
+        }
+        return {};
       }],
     }],
     PostToolUse: [{
@@ -130,7 +203,7 @@ export function hooksForPhase({ phase, state, onToolUse, onToolResult, onSubagen
     }],
     SubagentStop: [{
       hooks: [async (input) => {
-        onSubagentStop?.({ agentType: input.agent_type || null });
+        onSubagentStop?.({ agentType: input.agent_type || null, text: typeof input.last_assistant_message === "string" ? input.last_assistant_message : null });
         return {};
       }],
     }],

package/cli/engine/phases/EXECUTION.md

@@ -14,7 +14,7 @@ The reviewers returned the following. Work from this list; do not re-derive it.
 ## Rules
 
 - Follow CLAUDE.md conventions (if present). Do not modify files unrelated to the task.
-- **Sam's audit is a blocking gate.** After Dennis implements, Sam must read every changed file and run his full checklist, citing file:line for every finding — "looks clean" without evidence is invalid. Dennis fixes every violation before Bart creates the PR. Publishing is refused while findings are open.
+- **Sam's audit is a blocking gate.** After Dennis implements and commits, Sam must read every changed file and run his full checklist, citing file:line for every finding — "looks clean" without evidence is invalid. Sam ends his report with `AUDIT: APPROVED` or `AUDIT: REJECTED — <why>`; the engine reads that line and ties an approval to the commit he audited. Publishing is refused without an approval for the current commit: after REJECTED, Dennis fixes and commits and Sam re-audits; any commit made after an approval needs a new audit too.
 {{#HAS_NORA}}- Nora's sign-off is a gate too: Bart cannot create the PR until Nora reports either "No doc impact — skipped" or "Docs updated: [files]".{{/HAS_NORA}}
 - Do NOT post the final tracker summary or transition the task here — SUMMARY owns all final tracker writes.
 
@@ -36,10 +36,10 @@ Screenshots are **disabled** for this project. Do not capture any unless the use
 {{#NO_PLAN}}This task was assessed as small, so there was no PLAN phase. First have Dennis state the approach in two or three lines — files to change, the risk, how it will be verified — and confirm it; that is the plan. Then drive it step by step.{{/NO_PLAN}}{{#HAS_PLAN}}Drive the plan from session memory step by step.{{/HAS_PLAN}} Delegate each step with the Agent tool, give the agent the exact step and the relevant decisions, and require an observation for every claim ("tests pass" means the test output, "endpoint works" means the response). In order:
 
 1. **Dennis implements** — create the branch, implement per the plan, run linter and build, commit. Report files changed and technical decisions.
-2. **Sam audits** — every changed file, full checklist (feature envy, separation of concerns, clear interfaces, layering, god files), file:line for each finding. If there are violations, send Dennis back to fix them, then have Sam re-audit.
+2. **Sam audits the commit** — every changed file, full checklist (feature envy, separation of concerns, clear interfaces, layering, god files), file:line for each finding, closing with his `AUDIT:` line. If there are violations, send Dennis back to fix and commit them, then have Sam re-audit.
 3. **Vera tests** — unit/regression tests for the changed code, run and verified, committed.
 {{#HAS_SPECIALISTS}}4. **{{SPECIALISTS}}** — only where applicable (UI, user-facing copy, user-facing behaviour). Each proposes exact changes; Dennis applies them.{{/HAS_SPECIALISTS}}
-5. **Bart reviews and publishes** — reads all changed files, checks edge cases and error handling, runs linter and build, captures screenshots if applicable, pushes and creates the PR, posts the PR link on the tracker, posts screenshots as a separate comment.
+5. **Bart reviews and publishes** — reads all changed files, checks edge cases and error handling, runs linter and build, captures screenshots if applicable, pushes and creates the PR, posts the PR link on the tracker, posts screenshots as a separate comment. Sam's approval must cover the commit being published: if anyone committed after his audit (Vera's tests, a specialist's change), have Sam audit the new commits first — a short re-audit is enough.
 6. Ask Dennis, Sam and Bart to post their brief tracker comments (files changed & decisions; architecture findings or clean audit with evidence; PR link, test results, screenshots).
 
 The structured output required by the schema is captured automatically — what was implemented, files changed, the PR URL (empty string if none), QA results, issues fixed, and what the reviewers should look at. Do not repeat the JSON object in chat; keep any closing chat message brief and human-readable.

package/cli/engine/prompts.mjs

@@ -136,7 +136,7 @@ function createTaskSection({ tracker, config, description }) {
 export function renderPhasePrompt({
   phase, taskId, taskLink, description, createTask, tracker, config = {}, project = {},
   sessionUrl, cwd, sessionMemory = "", retryVerdict = null, evidence = null, openItems = [],
-  roster = null, profile = null,
+  roster = null, profile = null, handoffRetry = false,
 }) {
   const vars = {
     TASK_ID: taskId,
@@ -180,6 +180,9 @@ export function renderPhasePrompt({
     body += `\n\n## ENGINE VERIFICATION\n\nThe engine ran the project's own checks before this phase. Build on these observations; do not re-run the whole suite blind.\n\n${formatEvidenceForPrompt(evidence)}`;
   }
   if (openItems.length) body += `\n\n${renderOpenItems(openItems)}`;
+  if (handoffRetry) {
+    body += "\n\n## PREVIOUS RUN ENDED WITHOUT ITS HANDOFF\n\nThe last run of this phase did not produce the structured output the schema requires, so nothing was handed forward. Keep this run focused and shorter, and finish while turns remain so the structured summary is captured.";
+  }
   if (sessionMemory) {
     body += `\n\n## SESSION MEMORY (previous phases)\n\n${sessionMemory}`;
   }

package/cli/engine/query.mjs

@@ -35,6 +35,7 @@ export function buildQueryOptions({
   phase, cwd, env, model, agents, allowedTools, lead, state, config = {},
   abortController, sandbox, onChild, onIsolation, hookCallbacks = {},
   extraWritePaths = [],
+  verifyTimeoutSec,
   claudePath = process.env.AGENTDESK_CLAUDE_PATH,
 }) {
   const options = {
@@ -50,7 +51,7 @@ export function buildQueryOptions({
     abortController,
     forwardSubagentText: true,
     outputFormat: { type: "json_schema", schema: PHASE_OUTPUT_SCHEMAS[phase] },
-    hooks: hooksForPhase({ phase, state, ...hookCallbacks }),
+    hooks: hooksForPhase({ phase, state, verifyTimeoutSec, ...hookCallbacks }),
     spawnClaudeCodeProcess: createSandboxedSpawn({ sandbox, onChild, onIsolation, extraWritePaths }),
   };
   if (model) options.model = model;

package/cli/engine/session.mjs

@@ -17,7 +17,7 @@ import { fileURLToPath } from "url";
 import { createScratchHome } from "../session-sandbox.mjs";
 import { resolveGitHubCreds, assertPushable, PreflightError } from "../session-preflight.mjs";
 import {
-  MAX_REVIEW_RETRIES, MAX_PHASE_RUNS, phaseFailed, finalStatus, archiveStaleMemory,
+  MAX_REVIEW_RETRIES, MAX_HANDOFF_RETRIES, MAX_PHASE_RUNS, phaseFailed, finalStatus, archiveStaleMemory,
 } from "../phase-loop.mjs";
 import { buildChildEnv } from "./env.mjs";
 import { loadDotEnv } from "../dotenv.mjs";
@@ -36,7 +36,7 @@ import { spawnSandboxedCommand } from "./spawn.mjs";
 import { createLedger, openItemsFrom, noCommitItem } from "./handoff.mjs";
 import { teamProfileFor, phasesFor } from "./team-profile.mjs";
 import { buildQueryOptions, defaultRunQuery } from "./query.mjs";
-import { armPublishGate, onSubagentStopped } from "./hooks.mjs";
+import { armPublishGate, recordAudit, responseText, AUDITOR } from "./hooks.mjs";
 import { prepareWorkspace } from "../worktrees.mjs";
 import { detectProject } from "../detect.mjs";
 import { preparePrivateGit } from "../worktree-git.mjs";
@@ -235,6 +235,7 @@ async function executeSession({
   let handoff = false, aborted = false, reviewResolved = !!solo; // solo has no review gate
   let reviewRetries = 0, phaseRuns = 0, lastVerdict = null, lastPhase = null;
   let isolationLogged = false;
+  const handoffRetries = new Map(); // phase → runs that ended without a structured handoff
 
   // --- evidence (engine-owned) ---------------------------------------------
   // The engine runs the project's checks itself before every REVIEW and pins
@@ -248,16 +249,60 @@ async function executeSession({
       extraWritePaths: workspaceStateDir ? [workspaceStateDir, workspaceRecord.tree || cwd] : [],
     }),
   });
-  const headNow = () => gitState(cwd, workspaceGitEnv).revision;
+  const treeNow = () => gitState(cwd, workspaceGitEnv);
+  const headNow = () => treeNow().revision;
+  const describeTree = t => `${shortRev(t.revision)}${t.clean === false ? " + uncommitted changes" : ""}`;
+  state.treeNow = treeNow;
+  state.requireClean = requireClean;
   let approvedRevision = null;
+  const verify = () => runChecks({ checks, cwd, env: buildChildEnv({ dotenv, sandboxEnv: sandbox.env, extra: workspaceGitEnv }),
+    gitEnv: workspaceGitEnv, runCheck: runOneCheck, timeoutMs: checkTimeoutMs(config), signal: abortController.signal, requireClean });
+  // Generous: every configured check may run to its own timeout inside the hook.
+  const verifyTimeoutSec = Math.ceil((checkTimeoutMs(config) * Math.max(1, checks.length)) / 1000) + 60;
+
+  // Publishing (git push / gh pr create) is verified on the spot: the engine
+  // runs the checks at the revision being published and refuses with the
+  // failing output when they do not pass. A pass is evidence for the exact
+  // tree it ran on — same commit and a clean tree, then and now — and only
+  // that is reused (by a later publish attempt and by the REVIEW that
+  // follows). Uncommitted edits leave HEAD unchanged, so HEAD alone would let
+  // stale evidence outlive the code it checked. A failure is never cached.
+  let verified = null; // { revision, clean, evidence, verdict } from the latest verification
+  const reusableFor = tree => !!(verified && verified.evidence.passed && verified.clean === true
+    && tree.revision && tree.revision === verified.revision && tree.clean === true);
+  const verifyPublish = async () => {
+    if (reusableFor(treeNow())) return verified.verdict;
+    const evidence = await verify();
+    if (abortController.signal.aborted) return { ok: false, reason: "Session is being cancelled." };
+    // The tree is read again after the checks: evidence for a tree that no
+    // longer exists is not evidence.
+    const after = treeNow();
+    const moved = after.revision !== evidence.revision || after.clean !== evidence.clean;
+    let verdict;
+    if (moved) {
+      verdict = { ok: false, reason: `Cannot publish: the working tree changed while verification ran (${describeTree(evidence)} → ${describeTree(after)}). Commit, then publish again — the engine re-runs the checks.` };
+    } else if (!evidence.checked && evidence.clean !== false) verdict = { ok: true };
+    else {
+      reportEvidence(evidence, "EXECUTION");
+      appendMemory(renderEvidenceSection(evidence));
+      if (evidence.passed) verdict = { ok: true };
+      else {
+        const lines = evidenceFindings(evidence).map(f => `- ${f.title}\n  ${String(f.detail || "").split("\n").slice(-8).join("\n  ")}`);
+        verdict = { ok: false, reason: `Cannot publish: verification did not pass at ${shortRev(evidence.revision)}.\n${lines.join("\n")}\nFix it, commit, and publish again — the engine re-runs the checks for the new revision.` };
+      }
+    }
+    verified = moved ? null : { revision: evidence.revision, clean: evidence.clean, evidence, verdict };
+    return verdict;
+  };
+  state.verifyPublish = verifyPublish;
 
   // --- handoff ledger (engine-owned) ---------------------------------------
   // One entry per phase run; the open-items list travels into the next prompt.
   const ledger = createLedger(ledgerPath);
   let openItems = [];
 
-  const reportEvidence = evidence => {
-    emit({ type: "session:evidence", phase: "REVIEW", revision: evidence.revision, clean: evidence.clean,
+  const reportEvidence = (evidence, evidencePhase = "REVIEW") => {
+    emit({ type: "session:evidence", phase: evidencePhase, revision: evidence.revision, clean: evidence.clean,
       passed: evidence.passed, checked: evidence.checked, results: evidence.results });
     const at = evidence.revision ? ` at ${shortRev(evidence.revision)}` : "";
     if (!evidence.checked) {
@@ -300,13 +345,18 @@ async function executeSession({
     }
   }
 
-  // An approval is void the moment the code moves past the reviewed revision.
-  const invalidateApproval = now => {
+  // An approval is void the moment the code moves past the reviewed revision
+  // — a new commit, or (in a session worktree) uncommitted changes on top.
+  const drifted = tree => tree.revision !== approvedRevision || (requireClean && tree.clean === false);
+  const invalidateApproval = tree => {
     reviewResolved = false;
-    emit({ type: "session:error", code: "REVIEW_STALE", message: `Code changed after approval (${shortRev(approvedRevision)} → ${shortRev(now)}) — the approval no longer applies; ending for human review.` });
-    openItems = [...openItems, { source: "engine", title: "Approval invalidated", detail: `Code changed after approval (${shortRev(approvedRevision)} → ${shortRev(now)}).` }];
+    const what = tree.revision !== approvedRevision
+      ? `Code changed after approval (${shortRev(approvedRevision)} → ${shortRev(tree.revision)})`
+      : `Uncommitted changes appeared after approval of ${shortRev(approvedRevision)}`;
+    emit({ type: "session:error", code: "REVIEW_STALE", message: `${what} — the approval no longer applies; ending for human review.` });
+    openItems = [...openItems, { source: "engine", title: "Approval invalidated", detail: `${what}.` }];
     if (lastVerdict) {
-      lastVerdict = { ...lastVerdict, approved: false, approvalReason: "code changed after approval", headNow: now };
+      lastVerdict = { ...lastVerdict, approved: false, approvalReason: tree.revision !== approvedRevision ? "code changed after approval" : "uncommitted changes after approval", headNow: tree.revision };
       try { writeFileSync(findingsPath, JSON.stringify(lastVerdict, null, 2)); } catch {}
     }
   };
@@ -328,7 +378,8 @@ async function executeSession({
       const run = { index: phaseRuns, startedAt: Date.now(), revisionBefore: headNow() };
       const finishRun = ({ output = null, evidence: runEvidence = null, status }) => {
         const entry = { phase, run: run.index, startedAt: run.startedAt, durationMs: Date.now() - run.startedAt,
-          revisionBefore: run.revisionBefore, revisionAfter: headNow(), output, evidence: runEvidence, openItems: [...openItems], status };
+          revisionBefore: run.revisionBefore, revisionAfter: headNow(), output, evidence: runEvidence, openItems: [...openItems], status,
+          ...(run.audit ? { audit: run.audit } : {}) };
         ledger.record(entry);
         emit({ type: "session:handoff", ...entry });
       };
@@ -341,11 +392,17 @@ async function executeSession({
       // to EXECUTION as findings, through the same retry path.
       let evidence = null;
       if (phase === "REVIEW") {
-        evidence = await runChecks({ checks, cwd, env: buildChildEnv({ dotenv, sandboxEnv: sandbox.env, extra: workspaceGitEnv }),
-          gitEnv: workspaceGitEnv, runCheck: runOneCheck, timeoutMs: checkTimeoutMs(config), signal: abortController.signal, requireClean });
+        const tree = treeNow();
+        const reusable = reusableFor(tree) && verified.evidence.checked;
+        evidence = reusable ? verified.evidence : await verify();
         if (abortController.signal.aborted) { aborted = true; break; }
-        reportEvidence(evidence);
-        appendMemory(renderEvidenceSection(evidence));
+        if (reusable) {
+          emit({ type: "agent:message", agent: "Jane", tag: "SAY", message: `Verification at ${shortRev(tree.revision)} already passed when the work was published (same commit, clean tree) — reusing it for review.` });
+          emit({ type: "session:evidence", phase: "REVIEW", revision: evidence.revision, clean: evidence.clean, passed: evidence.passed, checked: evidence.checked, results: evidence.results });
+        } else {
+          reportEvidence(evidence);
+          appendMemory(renderEvidenceSection(evidence));
+        }
         if (!evidence.passed) {
           settleReview({ outcome: "NEEDS_MORE_WORK", findings: evidenceFindings(evidence), deferred: [], unverifiedClaims: [], reason: null,
             revision: evidence.revision, headNow: evidence.revision, evidence, approved: false, approvalReason: "engine checks did not pass", engineOnly: true });
@@ -354,8 +411,8 @@ async function executeSession({
         }
       }
       if (phase === "SUMMARY" && reviewResolved && approvedRevision) {
-        const now = headNow();
-        if (now !== approvedRevision) invalidateApproval(now);
+        const now = treeNow();
+        if (drifted(now)) invalidateApproval(now);
       }
 
       const { agents, allowedTools, lead } = solo
@@ -374,6 +431,7 @@ async function executeSession({
           openItems: phase === "EXECUTION" && lastVerdict && !lastVerdict.approved ? [] : openItems,
           roster: Object.keys(agents).filter(name => name !== lead),
           profile,
+          handoffRetry: (handoffRetries.get(phase) || 0) > 0,
         });
       if (workspaceRecord) {
         prompt += `\n\n## SESSION WORKSPACE\nAll file reads, writes, shell commands and Git operations must use ${cwd}.\nThe session branch ${workspaceRecord.branch} is already checked out; use it instead of creating or switching branches. The starting branch is ${workspaceRecord.baseRef}. Keep this branch until the session ends. Runtime session memory lives at ${memoryPath}.\n`;
@@ -383,16 +441,38 @@ async function executeSession({
         prompt += `For the final substantive tracker reply only, include the literal marker ${replyMarker(sessionId)} in the posted comment. Never mark startup/progress comments. Keep the successful provider response intact (no jq, redirects or pipelines). For GitHub use standalone gh issue comment ${taskId} --repo ${outcomeRepo || "OWNER/REPO"} --body with a literal body. For Jira use standalone curl with a literal JSON --data-raw payload and the task's comment endpoint. For Linear use standalone curl with a literal JSON --data-raw payload and a commentCreate mutation selecting success and comment { id url body issue { identifier } }. Do not post an extra reply just to record an outcome.\n`;
       }
 
-      // Publishing is gated until Sam has audited in this EXECUTION phase.
+      // Publishing is gated until Sam has approved, in this EXECUTION phase,
+      // the revision being published. His verdict is read from his report —
+      // the harness hands it over when he stops and again as the lead's tool
+      // result — and tied to the tree as the engine sees it at that moment.
       if (phase === "EXECUTION") armPublishGate(state, lastVerdict?.outcome === "APPROVED" ? [] : (lastVerdict?.findings || []));
+      const noteAudit = text => {
+        if (phase !== "EXECUTION") return;
+        const previous = state.audit;
+        const audit = recordAudit(state, { phase, agentType: AUDITOR, text, tree: treeNow() });
+        if (!audit) return;
+        run.audit = audit;
+        const same = previous && ["verdict", "revision", "clean", "statedRevision"].every(k => previous[k] === audit[k]);
+        if (same) return; // the same report, seen twice
+        emit({ type: "session:audit", phase, ...audit });
+        const messages = {
+          APPROVED: `${AUDITOR}'s audit: APPROVED at ${shortRev(audit.revision)}${audit.clean === false ? " (tree has uncommitted changes)" : ""} — publishing is open for that revision.`,
+          REJECTED: `${AUDITOR}'s audit: REJECTED — publishing stays closed until the fixes are committed and ${AUDITOR} re-audits.`,
+          STALE: `${AUDITOR} approved ${shortRev(audit.statedRevision)} but the code is at ${shortRev(audit.revision)} — publishing stays closed until he audits the current revision.`,
+          MISSING: `${AUDITOR}'s report has no AUDIT line — publishing stays closed until he ends his audit with AUDIT: APPROVED or AUDIT: REJECTED.`,
+        };
+        emit({ type: "agent:message", agent: "Jane", tag: "SAY", message: messages[audit.verdict] });
+      };
 
       const mapper = createEventMapper({ leadAgent: lead, onEvent: emit });
       const options = buildQueryOptions({
         phase, cwd, env: buildChildEnv({ dotenv, sandboxEnv: sandbox.env, extra: workspaceGitEnv }), model,
         agents, allowedTools, lead, state, config, abortController, sandbox, onChild,
         extraWritePaths: workspaceStateDir ? [workspaceStateDir, workspaceRecord.tree || cwd] : [],
+        verifyTimeoutSec,
         hookCallbacks: {
           onToolResult: result => {
+            if (result.tool === "Agent" && result.input?.subagent_type === AUDITOR) noteAudit(responseText(result.response));
             const outcome = captureOutcome({ ...result, phase, sessionId, taskId, repo: outcomeRepo,
               branch: workspaceRecord?.branch || (result.tool === "Bash" && /^gh\s+pr\s+create\b/.test(result.input?.command || "") ? currentBranch(cwd) : null), tracker, config });
             if (outcome && !outcomeIds.has(outcome.id)) {
@@ -400,8 +480,8 @@ async function executeSession({
               emit({ type: "session:outcome", project: project?.name || null, outcome });
             }
           },
-          onSubagentStop: ({ agentType }) => {
-            onSubagentStopped(state, { phase, agentType });
+          onSubagentStop: ({ agentType, text }) => {
+            if (agentType === AUDITOR && typeof text === "string") noteAudit(text);
             if (agentType) emit({ type: "agent:message", agent: agentType, tag: "SAY", message: `${agentType} finished and reported back.` });
           },
         },
@@ -441,15 +521,31 @@ async function executeSession({
 
       if (phase === "REVIEW") {
         const verdict = verdictFromResult({ is_error: summary.isError, subtype: summary.subtype, structured_output: summary.structuredOutput });
-        const now = headNow();
-        const approval = evaluateApproval({ verdict, evidence, headNow: now });
+        const now = treeNow();
+        const approval = evaluateApproval({ verdict, evidence, headNow: now.revision, cleanNow: now.clean });
         appendMemory(renderMemorySection("REVIEW", summary.structuredOutput));
-        settleReview({ ...verdict, revision: evidence?.revision ?? null, headNow: now, evidence, approved: approval.approved, approvalReason: approval.reason });
+        settleReview({ ...verdict, revision: evidence?.revision ?? null, headNow: now.revision, evidence, approved: approval.approved, approvalReason: approval.reason });
         finishRun({ output: summary.structuredOutput ?? null, evidence, status: lastVerdict.approved ? "ok" : "not-approved" });
         continue;
       }
 
-      // Other phases: the structured output is the handoff.
+      // Other phases: the structured output IS the handoff. Without it the
+      // next phase would start from nothing — run the phase again once, then
+      // fail closed. Solo mode keeps its single-run behaviour.
+      if (!summary.structuredOutput && phase !== "SOLO") {
+        const attempt = (handoffRetries.get(phase) || 0) + 1;
+        handoffRetries.set(phase, attempt);
+        finishRun({ status: "missing-output" });
+        if (attempt <= MAX_HANDOFF_RETRIES) {
+          emit({ type: "session:error", code: "PHASE_OUTPUT_MISSING", message: `${phase} ended without its structured handoff — running it again (retry ${attempt}/${MAX_HANDOFF_RETRIES}).` });
+          queue.unshift(phase);
+          continue;
+        }
+        emit({ type: "session:error", code: "HANDOFF_INVALID", message: `${phase} ended without its structured handoff again — ending session for human review.` });
+        handoff = true;
+        writeResumeFile({ cwd, taskId, sessionUrl, phase, duration: seconds(startedAt), steps: totals.steps, workspaceId: workspaceRecord?.id });
+        break;
+      }
       if (!summary.structuredOutput) {
         emit({ type: "session:error", code: "PHASE_OUTPUT_MISSING", message: `${phase} produced no structured summary — later phases will have less context.` });
       }
@@ -484,8 +580,8 @@ async function executeSession({
 
   // Belt to SUMMARY's braces: nothing may have moved the approved revision.
   if (!aborted && reviewResolved && approvedRevision) {
-    const now = headNow();
-    if (now !== approvedRevision) invalidateApproval(now);
+    const now = treeNow();
+    if (drifted(now)) invalidateApproval(now);
   }
 
   const duration = seconds(startedAt);

package/cli/phase-loop.mjs

@@ -12,10 +12,17 @@ export const PHASES = ["INTAKE", "PLAN", "EXECUTION", "REVIEW", "SUMMARY"];
 // One execution redo after a failed review, then the session ends unresolved.
 export const MAX_REVIEW_RETRIES = 1;
 
-// Absolute ceiling on phase runs. The review loop re-enqueues phases, so a bug
-// in verdict parsing must not be able to spin forever burning tokens. With
-// MAX_REVIEW_RETRIES=1 a legitimate run tops out at 7 (5 + EXECUTION + REVIEW).
-export const MAX_PHASE_RUNS = 10;
+// A phase that ends without its structured handoff is run again once; a
+// second miss ends the session for human review rather than letting the next
+// phase start from nothing.
+export const MAX_HANDOFF_RETRIES = 1;
+
+// Absolute ceiling on phase runs. The review and handoff loops re-enqueue
+// phases, so a bug in verdict or output parsing must not be able to spin
+// forever burning tokens. With MAX_REVIEW_RETRIES=1 and MAX_HANDOFF_RETRIES=1
+// a legitimate run tops out at 12 (5 + EXECUTION + REVIEW + one handoff
+// retry for each of the five non-review runs).
+export const MAX_PHASE_RUNS = 14;
 
 // Classify the first line of `.agentdesk/review-verdict.md`.
 //

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kendoo.agentdesk/agentdesk",
-  "version": "0.31.1",
+  "version": "0.32.1",
   "description": "AI team orchestrator for Claude Code — run collaborative agent sessions from your terminal",
   "type": "module",
   "bin": {
@@ -22,7 +22,7 @@
     "server": "node server/index.mjs",
     "build": "vite build",
     "preview": "vite preview",
-    "test": "node --test tests/server.test.mjs tests/agents.test.mjs tests/homepage.test.mjs tests/sessionUtils.test.mjs tests/tracker-url.test.mjs tests/session-preflight.test.mjs tests/access.test.mjs tests/project-ownership.test.mjs tests/random-hex.test.mjs tests/projects-registry.test.mjs tests/phase-loop.test.mjs tests/proc.test.mjs tests/crypto.test.mjs tests/dotenv.test.mjs tests/update-check.test.mjs tests/setup-helpers.test.mjs tests/project-key.test.mjs tests/tracker-project.test.mjs tests/tracker-check.test.mjs tests/config.test.mjs tests/engine-env.test.mjs tests/engine-events.test.mjs tests/engine-verdict.test.mjs tests/engine-hooks.test.mjs tests/engine-agents.test.mjs tests/session-isolation.test.mjs tests/engine-session.test.mjs tests/engine-prompts.test.mjs tests/engine-schemas.test.mjs tests/engine-claude-auth.test.mjs tests/worktrees.test.mjs tests/workspaces-api.test.mjs tests/engine-outcome.test.mjs tests/session-outcomes.test.mjs tests/outcome-hydration.test.mjs tests/mobile-outcomes.test.mjs tests/session-queue.test.mjs tests/useFollowScroll.test.mjs tests/session-usage.test.mjs tests/task-lookup.test.mjs tests/engine-evidence.test.mjs tests/engine-handoff.test.mjs tests/engine-team-profile.test.mjs tests/project-settings.test.mjs",
+    "test": "node --test tests/server.test.mjs tests/agents.test.mjs tests/homepage.test.mjs tests/sessionUtils.test.mjs tests/tracker-url.test.mjs tests/session-preflight.test.mjs tests/access.test.mjs tests/project-ownership.test.mjs tests/random-hex.test.mjs tests/projects-registry.test.mjs tests/phase-loop.test.mjs tests/proc.test.mjs tests/crypto.test.mjs tests/dotenv.test.mjs tests/update-check.test.mjs tests/setup-helpers.test.mjs tests/project-key.test.mjs tests/tracker-project.test.mjs tests/tracker-check.test.mjs tests/config.test.mjs tests/engine-env.test.mjs tests/engine-events.test.mjs tests/engine-verdict.test.mjs tests/engine-hooks.test.mjs tests/engine-commands.test.mjs tests/engine-agents.test.mjs tests/session-isolation.test.mjs tests/engine-session.test.mjs tests/engine-prompts.test.mjs tests/engine-schemas.test.mjs tests/engine-claude-auth.test.mjs tests/worktrees.test.mjs tests/workspaces-api.test.mjs tests/engine-outcome.test.mjs tests/session-outcomes.test.mjs tests/outcome-hydration.test.mjs tests/mobile-outcomes.test.mjs tests/session-queue.test.mjs tests/useFollowScroll.test.mjs tests/session-usage.test.mjs tests/task-lookup.test.mjs tests/engine-evidence.test.mjs tests/engine-handoff.test.mjs tests/engine-team-profile.test.mjs tests/project-settings.test.mjs tests/delivery.test.mjs tests/feed-view.test.mjs",
     "test:coverage": "node --test --experimental-test-coverage --test-coverage-include='cli/**' --test-coverage-include='server/**' --test-coverage-lines=60 --test-coverage-branches=62 tests/*.test.mjs",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",

package/shared/delivery.mjs

@@ -0,0 +1,70 @@
+// Delivery record shared by server and dashboard: the engine's verification
+// evidence, the open items carried between phases, and the handoff ledger.
+// Events arrive from the daemon (untrusted shape); everything is validated
+// and bounded here, once, before it is stored or rendered.
+
+const PHASES = new Set(["INTAKE", "PLAN", "EXECUTION", "REVIEW", "SUMMARY", "SOLO"]);
+const STATUSES = new Set(["ok", "not-approved", "checks-failed", "failed", "missing-output"]);
+const SOURCES = new Set(["review", "engine", "deferred"]);
+const MAX_RESULTS = 10, MAX_OUTPUT = 1000, MAX_ITEMS = 50, MAX_TEXT = 300, MAX_DETAIL = 1000, MAX_HANDOFFS = 20;
+
+const str = (v, max) => (typeof v === "string" ? v.slice(0, max) : "");
+const revision = v => (typeof v === "string" && /^[a-f0-9]{7,64}$/.test(v) ? v : null);
+
+export function emptyDelivery() {
+  return { evidence: null, openItems: [], handoffs: [] };
+}
+
+export function normalizeEvidence(event) {
+  if (!event || typeof event !== "object" || !Array.isArray(event.results)) return null;
+  const results = event.results.slice(0, MAX_RESULTS).flatMap(r => {
+    if (!r || typeof r !== "object" || typeof r.command !== "string") return [];
+    return [{
+      name: str(r.name, 40), command: str(r.command, MAX_TEXT),
+      exitCode: Number.isInteger(r.exitCode) ? r.exitCode : null,
+      durationMs: Number.isFinite(r.durationMs) && r.durationMs >= 0 ? Math.round(r.durationMs) : 0,
+      timedOut: r.timedOut === true, output: str(r.output, MAX_OUTPUT).slice(-MAX_OUTPUT),
+    }];
+  });
+  return {
+    revision: revision(event.revision), clean: typeof event.clean === "boolean" ? event.clean : null,
+    passed: event.passed === true, checked: event.checked === true, results,
+  };
+}
+
+export function normalizeOpenItems(items) {
+  if (!Array.isArray(items)) return [];
+  return items.slice(0, MAX_ITEMS).flatMap(i => {
+    if (!i || typeof i !== "object" || !SOURCES.has(i.source) || typeof i.title !== "string" || !i.title) return [];
+    return [{ source: i.source, title: str(i.title, MAX_TEXT), detail: str(i.detail, MAX_DETAIL) }];
+  });
+}
+
+export function normalizeHandoff(event) {
+  if (!event || typeof event !== "object" || !PHASES.has(event.phase) || !Number.isInteger(event.run) || event.run < 1) return null;
+  return {
+    phase: event.phase, run: event.run,
+    status: STATUSES.has(event.status) ? event.status : "ok",
+    durationMs: Number.isFinite(event.durationMs) && event.durationMs >= 0 ? Math.round(event.durationMs) : 0,
+    revisionBefore: revision(event.revisionBefore), revisionAfter: revision(event.revisionAfter),
+    openItems: normalizeOpenItems(event.openItems),
+  };
+}
+
+// Applies one session:evidence or session:handoff event to a delivery record.
+// Returns the same object when the event is not one of ours or is malformed.
+export function mergeDelivery(delivery, event) {
+  const base = delivery && typeof delivery === "object" ? delivery : emptyDelivery();
+  if (event?.type === "session:evidence") {
+    const evidence = normalizeEvidence(event);
+    return evidence ? { ...base, evidence } : base;
+  }
+  if (event?.type === "session:handoff") {
+    const handoff = normalizeHandoff(event);
+    if (!handoff) return base;
+    const handoffs = [...(base.handoffs || []).filter(h => h.run !== handoff.run), handoff]
+      .sort((a, b) => a.run - b.run).slice(-MAX_HANDOFFS);
+    return { ...base, openItems: handoff.openItems, handoffs };
+  }
+  return base;
+}