@kendoo.agentdesk/agentdesk 0.32.0 → 0.33.0

package/cli/engine/schemas.mjs

@@ -11,6 +11,33 @@ import { VERDICT_SCHEMA } from "./verdict.mjs";
 
 const strList = { type: "array", items: { type: "string" } };
 
+// What SUMMARY/SOLO hand back for the project lessons ledger. The engine
+// records these with provenance; agents never write the ledger themselves.
+const lessonList = {
+  type: "array",
+  description: "non-obvious things that cost this session time and would cost the next one too; empty when nothing qualifies",
+  items: {
+    type: "object",
+    additionalProperties: false,
+    required: ["text", "scope", "evidence"],
+    properties: {
+      text: { type: "string", description: "one actionable sentence" },
+      scope: { type: "string", description: "project | area:<ui|copy|docs|api|data> | path:<file or directory prefix>" },
+      evidence: { type: "string", description: "what happened that proves it (command and outcome)" },
+    },
+  },
+};
+const retireList = {
+  type: "array",
+  description: "ids from PROJECT LESSONS that proved wrong or obsolete in this session; empty when none did",
+  items: {
+    type: "object",
+    additionalProperties: false,
+    required: ["id", "reason"],
+    properties: { id: { type: "string" }, reason: { type: "string" } },
+  },
+};
+
 export const PHASE_OUTPUT_SCHEMAS = Object.freeze({
   INTAKE: {
     type: "object",
@@ -44,8 +71,8 @@ export const PHASE_OUTPUT_SCHEMAS = Object.freeze({
       filesToModify: strList,
       decisions: strList,
       risks: strList,
-      assignments: { ...strList, description: "who does what during execution" },
-      steps: { ...strList, description: "ordered implementation steps" },
+      assignments: { ...strList, description: "each assignment names one owner, a bounded deliverable, dependencies, and acceptance evidence" },
+      steps: { ...strList, description: "ordered implementation steps with owners; implementation and the subsequent audit both happen in EXECUTION, with audit approval required before publishing" },
     },
   },
   EXECUTION: {
@@ -65,25 +92,29 @@ export const PHASE_OUTPUT_SCHEMAS = Object.freeze({
   SOLO: {
     type: "object",
     additionalProperties: false,
-    required: ["summary", "filesChanged", "prUrl", "deferred", "manualSteps"],
+    required: ["summary", "filesChanged", "prUrl", "deferred", "manualSteps", "lessons", "retireLessons"],
     properties: {
       summary: { type: "string" },
       filesChanged: strList,
       prUrl: { type: "string", description: "empty string if no PR was created" },
       deferred: strList,
       manualSteps: strList,
+      lessons: lessonList,
+      retireLessons: retireList,
     },
   },
   SUMMARY: {
     type: "object",
     additionalProperties: false,
-    required: ["status", "prUrl", "deferred", "manualSteps", "summaryComment"],
+    required: ["status", "prUrl", "deferred", "manualSteps", "summaryComment", "lessons", "retireLessons"],
     properties: {
-      status: { type: "string" },
+      status: { type: "string", description: "accurate delivery outcome, including any unresolved review or tracker-write blocker" },
       prUrl: { type: "string" },
-      deferred: strList,
-      manualSteps: strList,
-      summaryComment: { type: "string", description: "the final tracker comment as posted" },
+      deferred: { ...strList, description: "only explicitly out-of-scope or user-approved deferrals; required work blocked on access belongs in status and manualSteps" },
+      manualSteps: { ...strList, description: "each remaining manual action with its named owner and completion evidence; include access recovery and the subsequent delivery retry when a tracker write failed; empty only when no manual action remains" },
+      summaryComment: { type: "string", description: "the final tracker comment exactly as confirmed posted; empty string if posting failed or was not confirmed" },
+      lessons: lessonList,
+      retireLessons: retireList,
     },
   },
 });

package/cli/engine/session.mjs

@@ -36,11 +36,15 @@ 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";
 import { runCancellable } from "./cancellation.mjs";
+import { checkpointStore, validHandoff, journalExternalActions, repairQueryOptions, trackerAccessDenied, recoveryBrief } from "./recovery.mjs";
+import { classifyFailure } from "../../shared/recovery.mjs";
+import { loadProjectMemory } from "../prompt.mjs";
+import { lessonsPath, readLessons, recordLessons, selectLessons } from "./lessons.mjs";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const CLI_VERSION = JSON.parse(readFileSync(join(here, "../../package.json"), "utf-8")).version;
@@ -144,14 +148,33 @@ async function executeSession({
   sourceCwd = cwd, workspaceRecord, workspaceStateDir, resumingWorkspace = false,
   workspaceGitEnv = {},
   registerCleanup,
+  resumeSession = false, instructions = [],
 }) {
   const startedAt = Date.now();
   const emit = event => {
-    if (event.type === "session:update" && event.taskId) taskId = event.taskId;
+    if (event.type === "session:update" && (event.taskId || event.taskLink)) {
+      taskId = event.taskId || taskId;
+      taskLink = event.taskLink || taskLink;
+      recovery.save({ taskId, taskLink });
+    }
     onEvent?.({ ...event, timestamp: timestamp() });
   };
-  const outcomeIds = new Set();
   const outcomeRepo = githubRepository(sourceCwd || cwd);
+  const recovery = checkpointStore(workspaceStateDir || join(cwd, ".agentdesk"), sessionId, { resume: resumeSession });
+  const prior = recovery.data;
+  const outcomeIds = new Set((prior.outcomes || []).map(o => o.id));
+  if (resumeSession) {
+    taskId = prior.taskId || taskId;
+    description = prior.description ?? description;
+    taskLink = prior.taskLink || taskLink;
+    createTask = false;
+  }
+  const knownInstructions = new Map((prior.instructions || []).map(i => [i.id, i]));
+  let changedInstructions = false;
+  for (const i of instructions) if (!knownInstructions.has(i.id)) { knownInstructions.set(i.id, i); changedInstructions = true; }
+  recovery.save({ taskId, taskLink, description, instructions: [...knownInstructions.values()],
+    replanRequired: prior.replanRequired || changedInstructions });
+  const block = (detail, code, phase) => emit({ type: "session:recovery", recovery: { ...classifyFailure(detail, code), phase, ready: false } });
 
   // Solo mode: one agent, one phase, full tools, no lead and no review gate.
   const solo = soloAgent ? team.find(a => a.name === soloAgent) : null;
@@ -177,6 +200,7 @@ async function executeSession({
   const creds = { ...trackerCreds, GITHUB_TOKEN: resolvedToken || trackerCreds.GITHUB_TOKEN };
 
   const failStart = (code, message) => {
+    block(message, code, prior.phase);
     emit({ type: "session:error", code, message });
     emit({ type: "session:end", duration: seconds(startedAt), steps: 0, inputTokens: 0, outputTokens: 0, status: "error" });
     return { duration: "0s", steps: 0, inputTokens: 0, outputTokens: 0, handoff: false, error: message, status: "error" };
@@ -196,6 +220,7 @@ async function executeSession({
   const auth = await authCheck({ env: buildChildEnv({ dotenv }) });
   abortSignal?.throwIfAborted();
   if (!auth.ok) return failStart("CLAUDE_NOT_LOGGED_IN", `${auth.detail}.\n${auth.hint || ""}`.trim());
+  emit({ type: "session:recovery", recovery: { state: "running", kind: "resume", message: "Access checked; continuing the saved task.", ready: false } });
 
   const sandbox = createScratchHome({
     projectId: project?.name,
@@ -219,7 +244,7 @@ async function executeSession({
   const findingsPath = join(stateDir, "review-findings.json");
   const ledgerPath = join(stateDir, "handoffs.jsonl");
   try { mkdirSync(stateDir, { recursive: true }); } catch {}
-  if (!resumingWorkspace || !existsSync(memoryPath)) {
+  if (!(resumingWorkspace || resumeSession) || !existsSync(memoryPath)) {
     if (archiveStaleMemory(memoryPath)) console.error("[agentdesk] archived stale session-memory.md from a previous run");
     try { if (existsSync(findingsPath)) unlinkSync(findingsPath); } catch {}
     try { if (existsSync(ledgerPath)) unlinkSync(ledgerPath); } catch {}
@@ -230,7 +255,14 @@ async function executeSession({
   const memoryText = () => { try { return readFileSync(memoryPath, "utf-8").trim(); } catch { return ""; } };
   const appendMemory = text => { try { appendFileSync(memoryPath, `\n${text}`); } catch {} };
 
-  const totals = { steps: 0, inputTokens: 0, outputTokens: 0, costUsd: 0 };
+  // --- project lessons (engine-owned, shared by every worktree) ------------
+  // Read from and recorded in the source project, never the session worktree.
+  const lessonsFile = lessonsPath(sourceCwd || cwd);
+  const projectNotes = loadProjectMemory(sourceCwd || cwd);
+  const lessonsForPrompt = () => selectLessons({ lessons: readLessons(lessonsFile).lessons, touches: profile.touches });
+  let lessonHandoff = null; // { phase, agent, lessons, retireLessons } from SUMMARY/SOLO
+
+  const totals = { steps: 0, inputTokens: 0, outputTokens: 0, costUsd: 0, ...(resumeSession ? prior.totals : {}) };
   const state = { openFindings: [], mainThreadMayCode: !!solo };
   let handoff = false, aborted = false, reviewResolved = !!solo; // solo has no review gate
   let reviewRetries = 0, phaseRuns = 0, lastVerdict = null, lastPhase = null;
@@ -249,7 +281,11 @@ 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 });
@@ -258,27 +294,36 @@ async function executeSession({
 
   // 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 cached per revision, so
-  // REVIEW reuses it at the same HEAD instead of running everything twice; a
-  // failure is never cached — the next attempt gets a fresh run.
-  let verified = null; // { revision, evidence, verdict } from the latest publish verification
+  // 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 () => {
-    const head = headNow();
-    if (verified && head && verified.revision === head && verified.evidence.passed) return verified.verdict;
+    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 (!evidence.checked && evidence.clean !== false) verdict = { ok: true };
+    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(head)}.\n${lines.join("\n")}\nFix it, commit, and publish again — the engine re-runs the checks for the new revision.` };
+        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 = { revision: evidence.revision, evidence, verdict };
+    verified = moved ? null : { revision: evidence.revision, clean: evidence.clean, evidence, verdict };
     return verdict;
   };
   state.verifyPublish = verifyPublish;
@@ -286,7 +331,7 @@ async function executeSession({
   // --- handoff ledger (engine-owned) ---------------------------------------
   // One entry per phase run; the open-items list travels into the next prompt.
   const ledger = createLedger(ledgerPath);
-  let openItems = [];
+  let openItems = resumeSession ? (prior.openItems || []) : [];
 
   const reportEvidence = (evidence, evidencePhase = "REVIEW") => {
     emit({ type: "session:evidence", phase: evidencePhase, revision: evidence.revision, clean: evidence.clean,
@@ -332,37 +377,60 @@ 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 {}
     }
   };
 
   // --- team profile (INTAKE assesses the task; config may force) -----------
   let profile = teamProfileFor({ intake: null, config });
-  const queue = solo ? ["SOLO"] : phasesFor(profile);
+  if (resumeSession && prior.profile) profile = prior.profile;
+  const queue = resumeSession && Array.isArray(prior.queue) ? [...prior.queue] : solo ? ["SOLO"] : phasesFor(profile);
+  if (resumeSession && !queue.length) queue.push(...(solo ? ["SOLO"] : ["EXECUTION", "REVIEW", "SUMMARY"]));
+  if (resumeSession && prior.lastVerdict) lastVerdict = prior.lastVerdict;
+  if (resumeSession) phaseRuns = prior.phaseRuns || 0;
+  // User corrections invalidate the old plan and review. Preserve intake;
+  // re-plan against the existing implementation instead of starting a new task.
+  if (recovery.data.replanRequired && resumeSession && !solo && queue[0] !== "INTAKE") queue.splice(0, queue.length, "PLAN", "EXECUTION", "REVIEW", "SUMMARY");
+  if (resumeSession && queue[0] === "SUMMARY") queue.unshift("REVIEW");
+  let invocationRuns = 0;
+  const checkpoint = pending => recovery.save({ queue: [...pending], phase: pending[0] || null,
+    totals, profile, lastVerdict, openItems, phaseRuns });
+  checkpoint(queue);
+  recovery.save({ replanRequired: false });
 
   try {
     while (queue.length > 0) {
       if (abortController.signal.aborted) { aborted = true; break; }
-      if (++phaseRuns > MAX_PHASE_RUNS) {
+      phaseRuns++;
+      if (++invocationRuns > MAX_PHASE_RUNS) {
         emit({ type: "agent:message", agent: "Jane", tag: "SAY", message: `Phase ceiling reached (${MAX_PHASE_RUNS} runs) — ending session for review.` });
         break;
       }
 
       const phase = queue.shift();
       lastPhase = phase;
+      checkpoint([phase, ...queue]);
+      if (!(resumeSession && prior.phase === phase && invocationRuns === 1)) recovery.save({ transcript: [] });
       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 });
+        checkpoint(status === "ok" || status === "not-approved" || status === "checks-failed" ? queue : [phase, ...queue]);
       };
       // The dashboard knows the five team phases; solo shows as EXECUTION.
       const model = modelForPhase(phase === "SOLO" ? "EXECUTION" : phase, config.phaseModels);
@@ -373,12 +441,12 @@ async function executeSession({
       // to EXECUTION as findings, through the same retry path.
       let evidence = null;
       if (phase === "REVIEW") {
-        const head = headNow();
-        const reusable = verified && head && verified.revision === head && verified.evidence.passed && verified.evidence.checked;
+        const tree = treeNow();
+        const reusable = reusableFor(tree) && verified.evidence.checked;
         evidence = reusable ? verified.evidence : await verify();
         if (abortController.signal.aborted) { aborted = true; break; }
         if (reusable) {
-          emit({ type: "agent:message", agent: "Jane", tag: "SAY", message: `Verification at ${shortRev(head)} already passed when the work was published — reusing it for review.` });
+          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);
@@ -392,19 +460,19 @@ 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
         ? soloDefinition(solo)
         : agentsForPhase({ phase, team, phaseModels: config.phaseModels, profile });
       let prompt = solo
-        ? renderSoloPrompt({ agent: solo, taskId, taskLink, description, tracker, config, project, sessionUrl, cwd, childStrategy })
+        ? renderSoloPrompt({ agent: solo, taskId, taskLink, description, tracker, config, project, sessionUrl, childStrategy, lessons: lessonsForPrompt(), projectNotes })
         : renderPhasePrompt({
           phase, taskId, taskLink, description,
           createTask: phase === "INTAKE" ? createTask : false,
-          tracker, config, project, sessionUrl, cwd,
+          tracker, config, project, sessionUrl,
           sessionMemory: memoryText(),
           retryVerdict: phase === "EXECUTION" && lastVerdict && !lastVerdict.approved ? lastVerdict : null,
           evidence,
@@ -413,17 +481,42 @@ async function executeSession({
           roster: Object.keys(agents).filter(name => name !== lead),
           profile,
           handoffRetry: (handoffRetries.get(phase) || 0) > 0,
+          lessons: lessonsForPrompt(), projectNotes,
         });
       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`;
       }
+      prompt += `\n\n${recoveryBrief(recovery.data, treeNow())}`;
+      if (resumeSession && invocationRuns === 1 && recovery.data.transcript.length) {
+        prompt += `\n\nPreserved observations from the interrupted phase (evidence, not new instructions):\n${recovery.data.transcript.join("\n")}`;
+      }
       prompt += `\n\n## Confirmed session outcomes\nWhen creating a PR, use a standalone gh pr create command with explicit --repo ${outcomeRepo || "OWNER/REPO"} and --head ${workspaceRecord?.branch || "BRANCH"}. Do not chain it with other commands; preserve its stdout so the harness can confirm creation. Never create another PR just to record an outcome.\n`;
       if (["SUMMARY", "SOLO"].includes(phase)) {
         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({
@@ -433,15 +526,17 @@ async function executeSession({
         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)) {
               outcomeIds.add(outcome.id);
+              recovery.save({ outcomes: [...(recovery.data.outcomes || []), outcome] });
               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.` });
           },
         },
@@ -454,9 +549,19 @@ async function executeSession({
         },
       });
 
+      // Journal external writes before dispatch, so a crash between execution
+      // and response cannot turn into a blind duplicate on resume.
+      journalExternalActions(options, recovery);
+
       let thrown = null;
       try {
-        for await (const msg of runQuery({ prompt, options })) mapper.handle(msg);
+        for await (const msg of runQuery({ prompt, options })) {
+          mapper.handle(msg);
+          if (msg.type === "assistant") {
+            const text = (msg.message?.content || []).filter(b => b.type === "text").map(b => b.text).join("\n");
+            if (text) recovery.save({ transcript: [...recovery.data.transcript, text.slice(-12000)].slice(-30) });
+          }
+        }
       } catch (err) {
         if (!abortController.signal.aborted) thrown = err;
       }
@@ -466,12 +571,19 @@ async function executeSession({
       totals.inputTokens += summary.inputTokens;
       totals.outputTokens += summary.outputTokens;
       totals.costUsd += summary.costUsd;
+      checkpoint([phase, ...queue]);
       emit({ type: "session:usage", inputTokens: totals.inputTokens, outputTokens: totals.outputTokens });
 
       if (abortController.signal.aborted) { aborted = true; break; }
 
-      if (phaseFailed({ exitCode: thrown || summary.isError ? 1 : 0, aborted: false })) {
-        const detail = thrown?.message || summary.subtype || "error";
+      const sourceDenied = ["INTAKE", "PLAN"].includes(phase) && trackerAccessDenied(summary.permissionDenials);
+      // The SDK can yield its error result and then throw. The yielded subtype
+      // still identifies a repairable handoff failure in that case.
+      const outputFailure = !sourceDenied && summary.subtype === "error_max_structured_output_retries";
+      if (!outputFailure && phaseFailed({ exitCode: thrown || summary.isError || sourceDenied ? 1 : 0, aborted: false })) {
+        const detail = sourceDenied ? "Tracker permission denied. Restore access before planning from unverified requirements."
+          : thrown?.message || summary.errors?.join("\n") || summary.resultText || summary.subtype || "error";
+        block(detail, "PHASE_FAILED", phase);
         emit({ type: "session:error", code: "PHASE_FAILED", message: `${phase} failed (${detail}) — session incomplete.` });
         handoff = true;
         writeResumeFile({ cwd, taskId, sessionUrl, phase, duration: seconds(startedAt), steps: totals.steps, workspaceId: workspaceRecord?.id });
@@ -481,35 +593,55 @@ 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. Without it the
-      // next phase would start from nothing — run the phase again once, then
-      // fail closed. Solo mode keeps its single-run behaviour.
+      // next phase would start from nothing. Repair from saved evidence with
+      // no tools, then fail closed. Solo mode keeps its single-run behaviour.
       if (!summary.structuredOutput && phase !== "SOLO") {
+        let repairError = null;
         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:recovery", recovery: { state: "recovering", kind: "handoff", phase,
+            message: "Recovering the phase summary from preserved findings. Completed actions will not be repeated.", ready: false } });
+          const repair = createEventMapper({ leadAgent: lead });
+          try {
+            const repairOptions = repairQueryOptions(options);
+            const repairPrompt = `Recover the ${phase} structured handoff using only the preserved evidence below. Do not use tools, perform actions, invent requirements, or expand scope. If the evidence is insufficient, return no structured output.\n${recoveryBrief(recovery.data, treeNow())}\n${memoryText()}\n${recovery.data.transcript.join("\n")}\n${summary.resultText || ""}`;
+            for await (const msg of runQuery({ prompt: repairPrompt, options: repairOptions })) repair.handle(msg);
+            const repaired = repair.finish();
+            totals.inputTokens += repaired.inputTokens; totals.outputTokens += repaired.outputTokens; totals.costUsd += repaired.costUsd;
+            if (!repaired.isError && validHandoff(phase, repaired.structuredOutput)) summary.structuredOutput = repaired.structuredOutput;
+            else if (repaired.isError) repairError = repaired.errors.join("\n") || repaired.resultText || repaired.subtype;
+          } catch (error) { repairError = error.message; }
+          checkpoint([phase, ...queue]);
+          emit({ type: "session:usage", inputTokens: totals.inputTokens, outputTokens: totals.outputTokens });
         }
-        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 (abortController.signal.aborted) { aborted = true; break; }
+        if (!summary.structuredOutput) {
+          block(repairError || "Missing structured handoff", "HANDOFF_INVALID", phase);
+          emit({ type: "session:error", code: "HANDOFF_INVALID", message: `${phase} handoff recovery failed — work preserved for intervention.` });
+          handoff = true;
+          writeResumeFile({ cwd, taskId, sessionUrl, phase, duration: seconds(startedAt), steps: totals.steps, workspaceId: workspaceRecord?.id });
+          break;
+        }
+        emit({ type: "session:recovery", recovery: { state: "running", kind: "handoff", phase, message: "Phase summary recovered.", ready: false } });
       }
       if (!summary.structuredOutput) {
         emit({ type: "session:error", code: "PHASE_OUTPUT_MISSING", message: `${phase} produced no structured summary — later phases will have less context.` });
       }
       appendMemory(renderMemorySection(phase, summary.structuredOutput));
+      if (["SUMMARY", "SOLO"].includes(phase) && summary.structuredOutput) {
+        lessonHandoff = { phase, agent: lead, lessons: summary.structuredOutput.lessons, retireLessons: summary.structuredOutput.retireLessons };
+      }
       if (phase === "EXECUTION") {
         const after = gitState(cwd, workspaceGitEnv);
         const missing = noCommitItem({ phase, revisionBefore: run.revisionBefore, revisionAfter: after.revision, clean: after.clean, output: summary.structuredOutput });
@@ -532,6 +664,7 @@ async function executeSession({
         const areas = profile.touches.length ? ` (${profile.touches.join(", ")})` : "";
         emit({ type: "agent:message", agent: "Jane", tag: "SAY", message: `Team for this task: ${profile.size}${areas} — ${names}.${profile.size === "small" ? " Skipping PLAN." : ""}` });
       }
+      checkpoint(queue);
     }
   } finally {
     abortSignal?.removeEventListener?.("abort", onExternalAbort);
@@ -540,12 +673,33 @@ 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);
   const status = finalStatus({ aborted, crashed: handoff, reviewResolved });
+  if (status === "handoff" && !handoff) block("Verification or review remains unresolved", "REVIEW_UNRESOLVED", lastPhase);
+
+  // The engine's verdict on the session decides whether a lesson is active
+  // (verified approval) or only proposed; the agents' say-so never does.
+  let lessonCounts = null;
+  if (lessonHandoff) {
+    const recorded = recordLessons({ path: lessonsFile, proposals: lessonHandoff.lessons, retirements: lessonHandoff.retireLessons,
+      source: { sessionId, taskId, phase: lessonHandoff.phase, agent: lessonHandoff.agent, revision: headNow() }, complete: status === "complete" });
+    const { activated, proposed, confirmed, retired, dropped } = recorded;
+    lessonCounts = { activated, proposed, confirmed, retired, dropped };
+    if (recorded.changed) {
+      emit({ type: "session:lessons", ...lessonCounts, path: lessonsFile });
+      const parts = [
+        activated && `${activated} recorded as active`,
+        proposed && `${proposed} proposed (activates when a later session that ends complete confirms it)`,
+        confirmed && `${confirmed} confirmed`, retired && `${retired} retired`, dropped && `${dropped} dropped`,
+      ].filter(Boolean);
+      emit({ type: "agent:message", agent: "Jane", tag: "SAY", message: `Project lessons: ${parts.join(", ")}.` });
+    }
+  }
+
   const resumePath = join(cwd, ".agentdesk-resume.md");
   const endFields = { duration, steps: totals.steps, inputTokens: totals.inputTokens, outputTokens: totals.outputTokens };
 
@@ -566,5 +720,6 @@ async function executeSession({
     approvedRevision: reviewResolved ? approvedRevision : null,
     openItems,
     profile,
+    lessons: lessonCounts,
   };
 }

package/cli/engine/tracker/github.md

@@ -14,6 +14,6 @@
 {{/EXECUTION}}
 {{#SUMMARY}}
 - Ensure the PR references the issue ("Closes #{{TASK_ID}}").
-- Labels: `gh issue edit {{TASK_ID}} --remove-label "in progress" --add-label "in review" 2>/dev/null || true`
+- Only when review and engine verification permit readiness, update labels: `gh issue edit {{TASK_ID}} --remove-label "in progress" --add-label "in review"`. Otherwise leave them unchanged. Report any failed write instead of hiding it.
 - Post the final comment with the session link {{SESSION_URL}}.
 {{/SUMMARY}}

package/cli/engine/tracker/jira.md

@@ -18,6 +18,6 @@
 {{/EXECUTION}}
 {{#SUMMARY}}
 - Verify the PR remote link exists; add it if missing.
-- Transition to "In Review": GET `/rest/api/3/issue/{{TASK_ID}}/transitions`, then POST `{"transition":{"id":"<id>"}}`.
+- Only when review and engine verification permit readiness, transition to "In Review": GET `/rest/api/3/issue/{{TASK_ID}}/transitions`, then POST `{"transition":{"id":"<id>"}}`. Otherwise leave the status unchanged and report the blocker.
 - Post the final comment (ADF, `inlineCard` for the session link {{SESSION_URL}} and the PR).
 {{/SUMMARY}}

package/cli/engine/tracker/linear.md

@@ -19,6 +19,6 @@
 {{/EXECUTION}}
 {{#SUMMARY}}
 - Verify the PR link is attached (attach via `attachmentCreate` if missing).
-- Transition to "In Review": `mutation { issueUpdate(id: "$ISSUE_ID", input: { stateId: "$IN_REVIEW_STATE_ID" }) { success } }`
+- Only when review and engine verification permit readiness, transition to "In Review": `mutation { issueUpdate(id: "$ISSUE_ID", input: { stateId: "$IN_REVIEW_STATE_ID" }) { success } }`. Otherwise leave the status unchanged and report the blocker.
 - Post the final comment with the session link {{SESSION_URL}} via `commentCreate`.
 {{/SUMMARY}}

package/cli/engine/verdict.mjs

@@ -24,13 +24,13 @@ export const VERDICT_SCHEMA = Object.freeze({
         properties: {
           reviewer: { type: "string" },
           title: { type: "string" },
-          detail: { type: "string" },
+          detail: { type: "string", description: "observed gap, named corrective owner, next action, and evidence required to close it; name the owner even when the reviewer is someone else" },
           file: { type: "string" },
           line: { type: "integer" },
         },
       },
     },
-    deferred: { type: "array", items: { type: "string" } },
+    deferred: { type: "array", items: { type: "string" }, description: "only explicitly out-of-scope or user-approved deferrals; unresolved acceptance criteria belong in findings" },
     unverifiedClaims: { type: "array", items: { type: "string" } },
   },
 });