@kendoo.agentdesk/agentdesk 0.32.1 → 0.34.0

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);
+  const projectNotes = loadProjectMemory(sourceCwd);
+  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,22 @@ 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 handoff failure the engine can try to repair — in
+      // every phase but SOLO, which has no repair path and must fail closed:
+      // a solo run with no summary is a handoff, never "complete".
+      const outputFailure = !sourceDenied && summary.subtype === "error_max_structured_output_retries";
+      const repairable = outputFailure && phase !== "SOLO";
+      if (!repairable && 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 });
@@ -519,6 +594,61 @@ async function executeSession({
         break;
       }
 
+      // The structured output IS the handoff. Without it the next phase would
+      // start from nothing: repair from saved evidence with no tools, then fail
+      // closed. Solo mode keeps its single-run behaviour. A REVIEW that simply
+      // returned no verdict is "not approved" and goes back to EXECUTION
+      // (settleReview); only a REVIEW whose verdict the SDK gave up on gets the
+      // repair — a transport error is not a reason to re-implement anything.
+      if (!summary.structuredOutput && phase !== "SOLO" && (phase !== "REVIEW" || repairable)) {
+        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: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 verdictRule = phase === "REVIEW" ? " For REVIEW, report NEEDS_MORE_WORK with every finding and unverified claim the evidence supports; a recovered verdict cannot grant approval — the reviewers approve again on the next run." : "";
+            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.${verdictRule}\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)) {
+              // The repaired handoff stands in for the failed result from here on.
+              summary.structuredOutput = repaired.structuredOutput;
+              summary.isError = false;
+              summary.subtype = repaired.subtype;
+              // A recovered verdict is the engine's reconstruction, not a
+              // reviewer's word: it carries the findings forward so the retry
+              // is informed, but it can never grant the approval itself.
+              if (phase === "REVIEW" && summary.structuredOutput.verdict === "APPROVED") {
+                summary.structuredOutput = { ...summary.structuredOutput, verdict: "NEEDS_MORE_WORK",
+                  unverifiedClaims: [...(summary.structuredOutput.unverifiedClaims || []), "Approval was reconstructed after the SDK gave up on the verdict; the reviewers must approve this revision again."] };
+              }
+            } else if (repaired.isError) repairError = repaired.errors.join("\n") || repaired.resultText || repaired.subtype;
+            else repairError = "repair produced no valid handoff";
+          } catch (error) { repairError = error.message; }
+          checkpoint([phase, ...queue]);
+          emit({ type: "session:usage", inputTokens: totals.inputTokens, outputTokens: totals.outputTokens });
+        }
+        if (abortController.signal.aborted) { aborted = true; break; }
+        if (!summary.structuredOutput) {
+          // Both failures are reported: what the repair said, and what the
+          // SDK threw or returned in the first place.
+          const original = thrown?.message || (summary.isError ? summary.errors?.join("\n") || summary.subtype : null);
+          const cause = [repairError, original].filter(Boolean).join("; ") || "missing structured handoff";
+          block(cause, "HANDOFF_INVALID", phase);
+          emit({ type: "session:error", code: "HANDOFF_INVALID", message: `${phase} handoff recovery failed (${cause}) — 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 (phase === "REVIEW") {
         const verdict = verdictFromResult({ is_error: summary.isError, subtype: summary.subtype, structured_output: summary.structuredOutput });
         const now = treeNow();
@@ -529,27 +659,13 @@ async function executeSession({
         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.
-      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.` });
       }
       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 +688,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 +703,33 @@ 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) {
+    try {
+      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" && !solo });
+      const { activated, proposed, confirmed, retired, dropped } = recorded;
+      lessonCounts = { activated, proposed, confirmed, retired, dropped };
+      if (recorded.changed) {
+        emit({ type: "session:lessons", ...lessonCounts });
+        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(", ")}.` });
+      }
+    } catch (err) {
+      lessonCounts = null;
+      emit({ type: "session:error", code: "LESSONS_NOT_RECORDED", message: `Project lessons were not recorded: ${err.message}` });
+    }
+  }
+
   const resumePath = join(cwd, ".agentdesk-resume.md");
   const endFields = { duration, steps: totals.steps, inputTokens: totals.inputTokens, outputTokens: totals.outputTokens };
 
@@ -606,5 +750,6 @@ async function executeSession({
     approvedRevision: reviewResolved ? approvedRevision : null,
     openItems,
     profile,
+    lessons: lessonCounts,
   };
 }

package/cli/engine/tracker/github.md

@@ -5,7 +5,7 @@
 {{/COMMON}}
 {{#INTAKE}}
 - Fetch: `gh issue view {{TASK_ID}} --json title,body,state,comments,labels`
-- Session start: post "Team session started. Session: {{SESSION_URL}}" and add the "in progress" label.
+- Session start: post "Team session started. Session: {{SESSION_URL}}" and add the "in progress" label — best-effort: `gh issue edit {{TASK_ID}} --add-label "in progress" 2>/dev/null || true` (a label that does not exist in the repository is not a failed write).
 {{/INTAKE}}
 {{#EXECUTION}}
 - PR created (Bart): reference the issue in the PR body ("Closes #{{TASK_ID}}") and post a comment with the PR link.
@@ -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" 2>/dev/null || true`. Otherwise leave them unchanged. Labels are best-effort — a label that does not exist in the repository is not a failed write. A denied comment or edit is; report it 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" } },
   },
 });

package/cli/prompt.mjs

@@ -42,16 +42,9 @@ export function loadProjectMemory(cwd) {
   return "";
 }
 
-export const MEMORY_INSTRUCTIONS = `
-## Project Memory
+// Notes earlier teams wrote by hand into .agentdesk/memory.md. Still shown,
+// no longer written: lessons are recorded by the engine from the SUMMARY
+// handoff (cli/engine/lessons.mjs), each with its source and a status.
+export const LEGACY_NOTES_HEADER = `## LEGACY PROJECT NOTES (read-only)
 
-The team has a shared memory file at \`.agentdesk/memory.md\` for storing learnings that should persist across sessions. This is LOCAL and gitignored — it never leaves this machine.
-
-**When to save**: After discovering something non-obvious that cost time (test setup steps, required seed data, login credentials for test env, workarounds, environment quirks, deployment steps). If you had to figure it out, save it so you don't have to next time.
-
-**When NOT to save**: Code patterns, architecture, or anything derivable from the codebase. Don't duplicate what's already in README or CLAUDE.md.
-
-**Format**: Use clear markdown sections. Update existing sections rather than appending duplicates. Never store real secrets — reference env vars instead (e.g. \`$TEST_ADMIN_PASSWORD\`).
-
-**How**: Use the Edit or Write tool on \`.agentdesk/memory.md\`. Create the file if it doesn't exist.
-`.trim();
+Notes earlier teams left by hand in \`.agentdesk/memory.md\`. Treat them as hints to verify, not as facts. Do not edit that file — lessons are now recorded by the engine from the SUMMARY handoff (\`lessons\` / \`retireLessons\`).`;

package/cli/session-queue.mjs

@@ -7,7 +7,7 @@ export function sessionLimit(value = process.env.AGENTDESK_MAX_SESSIONS) {
 
 // Capacity belongs to the daemon, not the network connection or UI status.
 // Hold reservations through confirmation, cancellation and engine teardown.
-export function createSessionQueue({ limit = sessionLimit(), run, onQueued = () => {}, onError = () => {} }) {
+export function createSessionQueue({ limit = sessionLimit(), run, onQueued = () => {}, onError = () => {}, onSettled = () => {} }) {
   const active = new Map();
   const waiting = [];
   let closed = false;
@@ -20,6 +20,7 @@ export function createSessionQueue({ limit = sessionLimit(), run, onQueued = ()
       active.set(job.sessionId, job);
       Promise.resolve().then(() => run(job)).catch(error => onError(job, error)).finally(() => {
         active.delete(job.sessionId);
+        onSettled(job);
         drain();
       });
     }
@@ -39,6 +40,7 @@ export function createSessionQueue({ limit = sessionLimit(), run, onQueued = ()
       waiting.splice(index, 1);
       return true;
     },
+    get(sessionId) { return active.get(sessionId) || waiting.find(job => job.sessionId === sessionId); },
     get activeIds() { return [...active.keys()]; },
     get queuedIds() { return waiting.map(job => job.sessionId); },
     close() { closed = true; waiting.length = 0; },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kendoo.agentdesk/agentdesk",
-  "version": "0.32.1",
+  "version": "0.34.0",
   "description": "AI team orchestrator for Claude Code — run collaborative agent sessions from your terminal",
   "type": "module",
   "bin": {
@@ -22,7 +22,9 @@
     "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-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:sdk-handoff": "node --test --test-concurrency=1 --test-reporter=spec tests/engine-sdk-handoff.smoke.mjs",
+    "test:sdk-leadership": "node --test --test-concurrency=1 --test-reporter=spec tests/engine-sdk-leadership.smoke.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 tests/recovery.test.mjs tests/session-recovery-api.test.mjs tests/engine-lessons.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/recovery.mjs

@@ -0,0 +1,28 @@
+// Public recovery state contains no credentials or raw tool responses.
+export const RECOVERY_STATES = new Set(["running", "recovering", "pausing", "paused", "waiting_access", "waiting_input"]);
+
+export function classifyFailure(text = "", code = "") {
+  const detail = `${code} ${text}`;
+  if (/401|oauth.*revoked|failed to authenticate|not.logged.in|authentication|invalid.api.key/i.test(detail)) {
+    return { state: "waiting_access", kind: "authentication", message: "The model connection needs attention. Work has been preserved. Reconnect on the daemon machine, then verify and resume." };
+  }
+  if (/permission|not.allowed|denied|403/i.test(detail)) {
+    return { state: "waiting_access", kind: "permission", message: "A required operation was denied. Check project access or correct the instructions, then retry." };
+  }
+  if (/handoff|structured/i.test(detail)) {
+    return { state: "waiting_input", kind: "handoff", message: "The phase handoff could not be recovered. Review the preserved findings before retrying." };
+  }
+  return { state: "waiting_input", kind: "execution", message: "Work paused after an execution failure. Review the details, correct instructions or the environment, then retry." };
+}
+
+export function normalizeRecovery(value) {
+  if (!value || !RECOVERY_STATES.has(value.state)) return null;
+  return {
+    state: value.state,
+    kind: String(value.kind || "execution").slice(0, 60),
+    message: String(value.message || "").slice(0, 1500),
+    phase: String(value.phase || "").slice(0, 30),
+    ready: value.ready === true,
+    updatedAt: Date.now(),
+  };
+}

package/shared/session-status.mjs

@@ -1,6 +1,6 @@
 // Running consumes execution capacity. Open also includes queued work and a
 // human handoff: neither may disappear through generic inactive cleanup.
 export const RUNNING_SESSION_STATUSES = new Set(["active", "stale"]);
-export const OPEN_SESSION_STATUSES = new Set(["queued", "active", "stale", "handoff"]);
+export const OPEN_SESSION_STATUSES = new Set(["queued", "active", "stale", "handoff", "paused"]);
 export const isRunningSession = status => RUNNING_SESSION_STATUSES.has(status);
 export const isOpenSession = status => OPEN_SESSION_STATUSES.has(status);