@kendoo.agentdesk/agentdesk 0.32.1 → 0.33.0

package/cli/engine/prompts.mjs

@@ -10,11 +10,12 @@
 import { readFileSync } from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
-import { wrapUntrusted, PROMPT_SECURITY_HEADER, MEMORY_INSTRUCTIONS, loadProjectMemory } from "../prompt.mjs";
+import { wrapUntrusted, PROMPT_SECURITY_HEADER, LEGACY_NOTES_HEADER } from "../prompt.mjs";
 import { generateContext } from "../detect.mjs";
 import { formatFindingsForRetry } from "./verdict.mjs";
 import { formatEvidenceForPrompt } from "./evidence.mjs";
 import { renderOpenItems } from "./handoff.mjs";
+import { renderLessonsSection } from "./lessons.mjs";
 
 const here = dirname(fileURLToPath(import.meta.url));
 
@@ -40,6 +41,16 @@ export function renderTemplate(text, { flags = new Set(), vars = {} } = {}) {
   return out;
 }
 
+// Engine-provided project knowledge: active lessons in scope, then the
+// hand-written notes from before the ledger existed (read-only).
+function projectKnowledge({ lessons = [], projectNotes = "" }) {
+  let out = "";
+  const block = renderLessonsSection(lessons);
+  if (block) out += `\n\n${block}`;
+  if (projectNotes) out += `\n\n${LEGACY_NOTES_HEADER}\n\n${projectNotes}`;
+  return out;
+}
+
 function trackerSection(tracker, phases, vars) {
   if (!tracker) return "";
   let text;
@@ -67,7 +78,7 @@ function soloSearchAndCreate({ tracker, config }) {
 // tools, no lead and no review gate. Ported from the legacy buildSoloPrompt.
 export function renderSoloPrompt({
   agent, taskId, taskLink, description, tracker, config = {}, project = {},
-  sessionUrl, cwd, childStrategy,
+  sessionUrl, childStrategy, lessons = [], projectNotes = "",
 }) {
   const hasRealTaskId = !!taskId && !String(taskId).startsWith("new-") && !String(taskId).startsWith("task-");
   const vars = {
@@ -104,9 +115,7 @@ export function renderSoloPrompt({
   }
   if (config.instructions) body += `\n\n## ADDITIONAL INSTRUCTIONS\n\n${config.instructions}`;
 
-  body += `\n\n${MEMORY_INSTRUCTIONS}`;
-  const memory = loadProjectMemory(cwd);
-  if (memory) body += `\n\n### Current memory\n\n${memory}`;
+  body += projectKnowledge({ lessons, projectNotes });
 
   const context = generateContext(project);
   const now = new Date();
@@ -135,8 +144,8 @@ function createTaskSection({ tracker, config, description }) {
 // Returns the full user prompt for one phase's query().
 export function renderPhasePrompt({
   phase, taskId, taskLink, description, createTask, tracker, config = {}, project = {},
-  sessionUrl, cwd, sessionMemory = "", retryVerdict = null, evidence = null, openItems = [],
-  roster = null, profile = null, handoffRetry = false,
+  sessionUrl, sessionMemory = "", retryVerdict = null, evidence = null, openItems = [],
+  roster = null, profile = null, handoffRetry = false, lessons = [], projectNotes = "",
 }) {
   const vars = {
     TASK_ID: taskId,
@@ -187,9 +196,7 @@ export function renderPhasePrompt({
     body += `\n\n## SESSION MEMORY (previous phases)\n\n${sessionMemory}`;
   }
 
-  body += `\n\n${MEMORY_INSTRUCTIONS}`;
-  const memory = loadProjectMemory(cwd);
-  if (memory) body += `\n\n### Current memory\n\n${memory}`;
+  body += projectKnowledge({ lessons, projectNotes });
 
   if (config.projectAgents?.length) {
     project.configAgents = config.projectAgents.map(a => ({ ...a, type: a.type || "declared", source: ".agentdesk.json" }));

package/cli/engine/recovery.mjs

@@ -0,0 +1,101 @@
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import { PHASE_OUTPUT_SCHEMAS } from "./schemas.mjs";
+
+export function checkpointStore(directory, sessionId, { resume = false } = {}) {
+  mkdirSync(directory, { recursive: true });
+  const path = join(directory, `recovery-${createHash("sha256").update(sessionId).digest("hex").slice(0, 24)}.json`);
+  let data = { version: 1, sessionId, queue: null, receipts: {}, outcomes: [], instructions: [], transcript: [], totals: null };
+  if (resume) {
+    if (!existsSync(path)) throw new Error("No recovery checkpoint exists for this session. Start a separately reviewed continuation instead.");
+    data = JSON.parse(readFileSync(path, "utf8"));
+    if (data.version !== 1 || data.sessionId !== sessionId) throw new Error("Recovery checkpoint does not match this session.");
+  }
+  const save = patch => {
+    data = { ...data, ...patch };
+    writeFileSync(`${path}.tmp`, JSON.stringify(data), { mode: 0o600 });
+    renameSync(`${path}.tmp`, path);
+  };
+  return { get data() { return data; }, save, path };
+}
+
+export function validHandoff(phase, value) {
+  const matches = (schema, v) => {
+    if (schema.type === "object") return !!v && typeof v === "object" && !Array.isArray(v)
+      && (schema.required || []).every(k => k in v)
+      && Object.entries(v).every(([k, item]) => schema.properties?.[k] ? matches(schema.properties[k], item) : schema.additionalProperties !== false);
+    if (schema.type === "array") return Array.isArray(v) && v.every(item => matches(schema.items, item));
+    if (schema.type === "string") return typeof v === "string" && (!schema.enum || schema.enum.includes(v));
+    if (schema.type === "integer") return Number.isInteger(v);
+    return true;
+  };
+  return !!PHASE_OUTPUT_SCHEMAS[phase] && matches(PHASE_OUTPUT_SCHEMAS[phase], value);
+}
+
+// Conservative journal for externally visible commands. Exact repeats are
+// refused; uncertain responses require reconciliation, never automatic replay.
+export function externalActionKey(tool, input = {}) {
+  const command = String(input.command || "");
+  const external = tool.startsWith("mcp__") && /create|update|delete|transition|comment|post|send/i.test(tool) || (tool === "Bash" && (
+    /\bgh\s+(?:pr|issue)\s+(?:create|comment|edit|merge|close|reopen)\b/.test(command)
+    || /\bcurl\b/.test(command) && /(?:--data|-d\b|-X\s*(?:POST|PUT|PATCH|DELETE)|--request\s+(?:POST|PUT|PATCH|DELETE))/.test(command)
+  ));
+  if (!external) return null;
+  const canonical = value => Array.isArray(value) ? value.map(canonical)
+    : value && typeof value === "object" ? Object.fromEntries(Object.keys(value).sort().map(k => [k, canonical(value[k])])) : value;
+  // Bash descriptions/timeouts are presentation, not the external action.
+  return createHash("sha256").update(JSON.stringify([tool, tool === "Bash" ? command.trim() : canonical(input)])).digest("hex");
+}
+
+export function journalExternalActions(options, recovery) {
+  const previousPre = options.hooks.PreToolUse[0].hooks[0];
+  options.hooks.PreToolUse[0].hooks[0] = async input => {
+    const decision = await previousPre(input);
+    if (decision.hookSpecificOutput?.permissionDecision === "deny") return decision;
+    const key = externalActionKey(input.tool_name, input.tool_input);
+    if (!key) return decision;
+    const receipt = recovery.data.receipts[key];
+    if (receipt) return { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny",
+      permissionDecisionReason: `This external action is recorded as ${receipt.state}. Do not repeat or reword it to bypass this guard. Inspect the provider to reconcile its result; preserve the existing PR/comment.` } };
+    recovery.save({ receipts: { ...recovery.data.receipts, [key]: { state: "pending", tool: input.tool_name, at: Date.now() } } });
+    return decision;
+  };
+  const previousPost = options.hooks.PostToolUse[0].hooks[0];
+  options.hooks.PostToolUse[0].hooks[0] = async input => {
+    const result = await previousPost(input);
+    const key = externalActionKey(input.tool_name, input.tool_input);
+    if (key && recovery.data.receipts[key]) {
+      // A tool returning is not proof of an external write succeeding. Only
+      // the provider-specific outcome parser can produce a confirmed receipt.
+      recovery.save({ receipts: { ...recovery.data.receipts, [key]: { ...recovery.data.receipts[key], state: "response-received" } } });
+    }
+    return result;
+  };
+}
+
+export function repairQueryOptions(options) {
+  return { ...options, agents: {}, agent: undefined, allowedTools: ["StructuredOutput"], tools: ["StructuredOutput"], mcpServers: {},
+    hooks: { PreToolUse: [{ hooks: [async input => input.tool_name === "StructuredOutput" ? {} : {
+      hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: "Handoff repair cannot execute tools." },
+    }] }] }, maxTurns: 2 };
+}
+
+export function trackerAccessDenied(denials) {
+  return denials.some(d => /mcp__.*(?:jira|atlassian|linear|github)/i.test(d.tool_name || "")
+    || d.tool_name === "Bash" && /\bcurl\b|\bgh\s+(?:issue|pr)\s+(?:view|list)\b/.test(d.tool_input?.command || ""));
+}
+
+export function recoveryBrief(data, tree) {
+  return [
+    "## Authoritative task and user instructions",
+    `Original task: ${data.taskId || ""}\n${data.description || ""}`,
+    "Stay within this objective. Propose unrelated discoveries separately; do not expand scope to repair lost context.",
+    ...data.instructions.map((i, n) => `${n + 1}. ${i.text}`),
+    "Latest user corrections override earlier plans. Acknowledge their effect before working.",
+    `Current revision: ${tree.revision || "unknown"}; working tree clean: ${tree.clean}. Preserve unfinished edits. Inspect the diff and existing PR before continuing. Prior verification must be re-established.`,
+    `Recorded external actions: ${JSON.stringify(data.receipts)}`,
+    `Confirmed provider outcomes: ${JSON.stringify(data.outcomes || [])}`,
+    "Do not repeat confirmed actions. A pending or response-received entry is uncertain: reconcile it against the provider first. Never reword commands to bypass the replay guard. Never claim an action failed merely because this phase cannot access the provider.",
+  ].join("\n\n");
+}

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

@@ -41,6 +41,10 @@ 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;
@@ -299,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,
@@ -363,18 +395,34 @@ async function executeSession({
 
   // --- 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,
@@ -382,6 +430,7 @@ async function executeSession({
           ...(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);
@@ -419,11 +468,11 @@ async function executeSession({
         ? 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,
@@ -432,10 +481,15 @@ 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`;
@@ -477,6 +531,7 @@ async function executeSession({
               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 });
             }
           },
@@ -494,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;
       }
@@ -506,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 });
@@ -530,26 +602,46 @@ async function executeSession({
       }
 
       // 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 });
@@ -572,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);
@@ -586,6 +679,27 @@ async function executeSession({
 
   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 };
 
@@ -606,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" } },
   },
 });