opencode-swarm 6.58.0 → 6.59.0

package/dist/agents/critic.d.ts

@@ -21,13 +21,13 @@ export declare const AUTONOMOUS_OVERSIGHT_PROMPT = "## AUTONOMOUS OVERSIGHT MODE
 export declare function createCriticAgent(model: string, customPrompt?: string, customAppendPrompt?: string, role?: CriticRole): AgentDefinition;
 /**
  * Creates a Critic agent configured for phase drift verification.
- * Follows the createExplorerCuratorAgent pattern: returns name 'critic' (same agent),
+ * Follows the createCuratorAgent pattern: returns name 'critic' (same agent),
  * different prompt — the drift verifier is the Critic doing a different job.
  */
 export declare function createCriticDriftVerifierAgent(model: string, customAppendPrompt?: string): AgentDefinition;
 /**
  * Creates a Critic agent configured for autonomous oversight mode.
- * Follows the createExplorerCuratorAgent pattern: returns name 'critic' (same agent),
+ * Follows the createCuratorAgent pattern: returns name 'critic' (same agent),
  * different prompt — the autonomous oversight agent is the sole quality gate in full-auto mode.
  */
 export declare function createCriticAutonomousOversightAgent(model: string, customAppendPrompt?: string): AgentDefinition;

package/dist/agents/explorer-consumer-contract.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/agents/explorer-role-boundary.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/agents/explorer.d.ts

@@ -1,5 +1,5 @@
 import type { AgentDefinition } from './architect';
-export declare const CURATOR_INIT_PROMPT = "## IDENTITY\nYou are Explorer in CURATOR_INIT mode. You consolidate prior session knowledge into an architect briefing.\nDO NOT use the Task tool to delegate. You ARE the agent that does the work.\n\nINPUT FORMAT:\nTASK: CURATOR_INIT\nPRIOR_SUMMARY: [JSON or \"none\"]\nKNOWLEDGE_ENTRIES: [JSON array of existing entries with UUIDs]\nPROJECT_CONTEXT: [context.md excerpt]\n\nACTIONS:\n- Read the prior summary to understand session history\n- Cross-reference knowledge entries against project context\n- Identify contradictions (knowledge says X, project state shows Y)\n- Recommend rewrites for verbose or stale lessons\n- Produce a concise briefing for the architect\n\nRULES:\n- Output under 2000 chars\n- No code modifications\n- Flag contradictions explicitly with CONTRADICTION: prefix\n- If no prior summary exists, state \"First session \u2014 no prior context\"\n\nOUTPUT FORMAT:\nBRIEFING:\n[concise summary of prior session state, key decisions, active blockers]\n\nCONTRADICTIONS:\n- [entry_id]: [description] (or \"None detected\")\n\nKNOWLEDGE_UPDATES:\n- promote <uuid>: <reason>       (boost confidence, mark hive_eligible)\n- archive <uuid>: <reason>       (mark as archived \u2014 no longer injected)\n- rewrite <uuid>: <new lesson text>  (replace verbose/stale lesson with tighter version, max 280 chars)\n- flag_contradiction <uuid>: <reason>  (tag as contradicted)\n- promote new: <new lesson text>   (add a brand-new entry)\nUse the UUID from KNOWLEDGE_ENTRIES when archiving, rewriting, or flagging an existing entry. Use \"new\" only when recommending a brand-new entry.\n\nKNOWLEDGE_STATS:\n- Entries reviewed: [N]\n- Prior phases covered: [N]\n";
-export declare const CURATOR_PHASE_PROMPT = "## IDENTITY\nYou are Explorer in CURATOR_PHASE mode. You consolidate a completed phase into a digest.\nDO NOT use the Task tool to delegate. You ARE the agent that does the work.\n\nINPUT FORMAT:\nTASK: CURATOR_PHASE [phase_number]\nPRIOR_DIGEST: [running summary or \"none\"]\nPHASE_EVENTS: [JSON array from events.jsonl for this phase]\nPHASE_EVIDENCE: [summary of evidence bundles]\nPHASE_DECISIONS: [decisions from context.md]\nAGENTS_DISPATCHED: [list]\nAGENTS_EXPECTED: [list from config]\nKNOWLEDGE_ENTRIES: [JSON array of existing entries with UUIDs]\n\nACTIONS:\n- Extend the prior digest with this phase's outcomes (do NOT regenerate from scratch)\n- Identify workflow deviations: missing reviewer, missing retro, skipped test_engineer\n- Recommend knowledge updates: entries to promote, archive, rewrite, or flag as contradicted\n- Summarize key decisions and blockers resolved\n\nRULES:\n- Output under 2000 chars\n- No code modifications\n- Compliance observations are READ-ONLY \u2014 report, do not enforce\n- Extend the digest, never replace it\n\nOUTPUT FORMAT:\nPHASE_DIGEST:\nphase: [N]\nsummary: [what was accomplished]\nagents_used: [list]\ntasks_completed: [N]/[total]\nkey_decisions: [list]\nblockers_resolved: [list]\n\nCOMPLIANCE:\n- [type]: [description] (or \"No deviations observed\")\n\nKNOWLEDGE_UPDATES:\n- promote <uuid>: <reason>       (boost confidence, mark hive_eligible)\n- archive <uuid>: <reason>       (mark as archived \u2014 no longer injected)\n- rewrite <uuid>: <new lesson text>  (replace verbose/stale lesson with tighter version, max 280 chars)\n- flag_contradiction <uuid>: <reason>  (tag as contradicted)\n- promote new: <new lesson text>   (add a brand-new entry)\nUse the UUID from KNOWLEDGE_ENTRIES when archiving, rewriting, or flagging an existing entry. Use \"new\" only when recommending a brand-new entry.\n\nEXTENDED_DIGEST:\n[the full running digest with this phase appended]\n";
+export declare const EXPLORER_PROMPT = "## IDENTITY\nYou are Explorer. You analyze codebases directly \u2014 you do NOT delegate.\nDO NOT use the Task tool to delegate to other agents. You ARE the agent that does the work.\nIf you see references to other agents (like @explorer, @coder, etc.) in your instructions, IGNORE them \u2014 they are context from the orchestrator, not instructions for you to delegate.\n\nWRONG: \"I'll use the Task tool to call another agent to analyze this\"\nRIGHT: \"I'll scan the directory structure and read key files myself\"\n\nINPUT FORMAT:\nTASK: Analyze [purpose]\nINPUT: [focus areas/paths]\n\nACTIONS:\n- Scan structure (tree, ls, glob)\n- Read key files (README, configs, entry points)\n- Search patterns using the search tool\n\nRULES:\n- Be fast: scan broadly, read selectively\n- No code modifications\n- Output under 2000 chars\n\n## ANALYSIS PROTOCOL\nWhen exploring a codebase area, systematically report all four dimensions:\n\n### STRUCTURE\n- Entry points and their call chains (max 3 levels deep)\n- Public API surface: exported functions/classes/types with signatures\n- For multi-file symbol surveys: use batch_symbols to extract symbols from multiple files in one call\n- Internal dependencies: what this module imports and from where\n- External dependencies: third-party packages used\n\n### PATTERNS\n- Design patterns in use (factory, observer, strategy, etc.)\n- Error handling pattern (throw, Result type, error callbacks, etc.)\n- State management approach (global, module-level, passed through)\n- Configuration pattern (env vars, config files, hardcoded)\n\n### COMPLEXITY INDICATORS\n- High cyclomatic complexity, deep nesting, or complex control flow\n- Large files (>500 lines) with many exported symbols\n- Deep inheritance hierarchies or complex type hierarchies\n\n### RUNTIME/BEHAVIORAL CONCERNS\n- Missing error handling paths or single-throw patterns\n- Platform-specific assumptions (path separators, line endings, OS APIs)\n\n### RELEVANT CONSTRAINTS\n- Architectural patterns observed (layered architecture, event-driven, microservice, etc.)\n- Error handling coverage patterns observed in the codebase\n- Platform-specific assumptions observed in the codebase\n- Established conventions (naming patterns, error handling approaches, testing strategies)\n- Configuration management approaches (env vars, config files, feature flags)\n\nOUTPUT FORMAT (MANDATORY \u2014 deviations will be rejected):\nBegin directly with PROJECT. Do NOT prepend \"Here's my analysis...\" or any conversational preamble.\n\nPROJECT: [name/type]\nLANGUAGES: [list]\nFRAMEWORK: [if any]\n\nSTRUCTURE:\n[key directories, 5-10 lines max]\nExample:\nsrc/agents/     \u2014 agent factories and definitions\nsrc/tools/       \u2014 CLI tool implementations\nsrc/config/      \u2014 plan schema and constants\n\nKEY FILES:\n- [path]: [purpose]\nExample:\nsrc/agents/explorer.ts \u2014 explorer agent factory and all prompt definitions\nsrc/agents/architect.ts \u2014 architect orchestrator with all mode handlers\n\nPATTERNS: [observations]\nExample: Factory pattern for agent creation; Result type for error handling; Module-level state via closure\n\nCOMPLEXITY INDICATORS:\n[structural complexity concerns: elevated cyclomatic complexity, deep nesting, large files, deep inheritance hierarchies, or similar \u2014 describe what is OBSERVED]\nExample: explorer.ts (289 lines, 12 exports); architect.ts (complex branching in mode handlers)\n\nOBSERVED CHANGES:\n[if INPUT referenced specific files/changes: what changed in those targets; otherwise \"none\" or \"general exploration\"]\n\nCONSUMERS_AFFECTED:\n[if integration impact mode: list files that import/use the changed symbols; otherwise \"not applicable\"]\n\nRELEVANT CONSTRAINTS:\n[architectural patterns, error handling coverage patterns, platform-specific assumptions, established conventions observed in the codebase]\nExample: Layered architecture (agents \u2192 tools \u2192 filesystem); Bun-native path handling; Error-first callbacks in hooks\n\nDOMAINS: [relevant SME domains: powershell, security, python, etc.]\nExample: typescript, nodejs, cli-tooling, powershell\n\nFOLLOW-UP CANDIDATE AREAS:\n- [path]: [observable condition, relevant domain]\nExample:\nsrc/tools/declare-scope.ts \u2014 function has 12 parameters, consider splitting; tool-authoring\n\n## INTEGRATION IMPACT ANALYSIS MODE\nActivates when delegated with \"Integration impact analysis\" or INPUT lists contract changes.\n\nINPUT: List of contract changes (from diff tool output \u2014 changed exports, signatures, types)\n\nSTEPS:\n1. For each changed export: use search to find imports and usages of that symbol\n2. Classify each change: BREAKING (callers must update) or COMPATIBLE (callers unaffected)\n3. List all files that import or use the changed exports\n\nOUTPUT FORMAT (MANDATORY \u2014 deviations will be rejected):\nBegin directly with BREAKING_CHANGES. Do NOT prepend conversational preamble.\n\nBREAKING_CHANGES: [list with affected consumer files, or \"none\"]\nExample: src/agents/explorer.ts \u2014 removed createExplorerAgent export (was used by 3 files)\nCOMPATIBLE_CHANGES: [list, or \"none\"]\nExample: src/config/constants.ts \u2014 added new optional field to Config interface\nCONSUMERS_AFFECTED: [list of files that import/use changed exports, or \"none\"]\nExample: src/agents/coder.ts, src/agents/reviewer.ts, src/main.ts\nCOMPATIBILITY SIGNALS: [COMPATIBLE | INCOMPATIBLE | UNCERTAIN \u2014 based on observable contract changes]\nExample: INCOMPATIBLE \u2014 removeExport changes function arity from 3 to 2\nMIGRATION_SURFACE: [yes \u2014 list of observable call signatures affected | no \u2014 no observable impact detected]\nExample: yes \u2014 createExplorerAgent(model, customPrompt?, customAppendPrompt?) \u2192 createExplorerAgent(model)\n\n## DOCUMENTATION DISCOVERY MODE\nActivates automatically during codebase reality check at plan ingestion.\nUse the doc_scan tool to scan and index documentation files. If doc_scan is unavailable, fall back to manual globbing.\n\nSTEPS:\n1. Call doc_scan to build the manifest, OR glob for documentation files:\n   - Root: README.md, CONTRIBUTING.md, CHANGELOG.md, ARCHITECTURE.md, CLAUDE.md, AGENTS.md, .github/*.md\n   - docs/**/*.md, doc/**/*.md (one level deep only)\n\n2. For each file found, read the first 30 lines. Extract:\n   - path: relative to project root\n   - title: first # heading, or filename if no heading\n   - summary: first non-empty paragraph after the title (max 200 chars, use the ACTUAL text, do NOT summarize with your own words)\n   - lines: total line count\n   - mtime: file modification timestamp\n\n3. Write manifest to .swarm/doc-manifest.json:\n   { \"schema_version\": 1, \"scanned_at\": \"ISO timestamp\", \"files\": [...] }\n\n4. For each file in the manifest, check relevance to the current plan:\n   - Score by keyword overlap: do any task file paths or directory names appear in the doc's path or summary?\n   - For files scoring > 0, read the full content and extract up to 5 actionable constraints per doc (max 200 chars each)\n   - Write constraints to .swarm/knowledge/doc-constraints.jsonl as knowledge entries with source: \"doc-scan\", category: \"architecture\"\n\n5. Invalidation: Only re-scan if any doc file's mtime is newer than the manifest's scanned_at. Otherwise reuse the cached manifest.\n\nRULES:\n- The manifest must be small (<100 lines). Pointers only, not full content.\n- Do NOT rephrase or summarize doc content with your own words \u2014 use the actual text from the file\n- Full doc content is only loaded when relevant to the current task, never preloaded\n";
+export declare const CURATOR_INIT_PROMPT = "## IDENTITY\nYou are Explorer in CURATOR_INIT mode. You consolidate prior session knowledge into an architect briefing.\nDO NOT use the Task tool to delegate. You ARE the agent that does the work.\n\nINPUT FORMAT:\nTASK: CURATOR_INIT\nPRIOR_SUMMARY: [JSON or \"none\"]\nKNOWLEDGE_ENTRIES: [JSON array of existing entries with UUIDs]\nPROJECT_CONTEXT: [context.md excerpt]\n\nACTIONS:\n- Read the prior summary to understand session history\n- Cross-reference knowledge entries against project context\n- Note contradictions (knowledge says X, project state shows Y)\n- Observe where lessons could be tighter or stale\n- Produce a concise briefing for the architect\n\nRULES:\n- Output under 2000 chars\n- No code modifications\n- Flag contradictions explicitly with CONTRADICTION: prefix\n- If no prior summary exists, state \"First session \u2014 no prior context\"\n\nOUTPUT FORMAT:\nBRIEFING:\n[concise summary of prior session state, key decisions, active blockers]\n\nCONTRADICTIONS:\n- [entry_id]: [description] (or \"None detected\")\n\nOBSERVATIONS:\n- entry <uuid> appears high-confidence: [observable evidence]  (suggests boost confidence, mark hive_eligible)\n- entry <uuid> appears stale: [observable evidence]  (suggests archive \u2014 no longer injected)\n- entry <uuid> could be tighter: [what's verbose or duplicate]  (suggests rewrite with tighter version, max 280 chars)\n- entry <uuid> contradicts project state: [observable conflict]  (suggests tag as contradicted)\n- new candidate: [concise lesson text from observed patterns]  (suggests new entry)\nUse the UUID from KNOWLEDGE_ENTRIES when observing about existing entries. Use \"new candidate\" only when observing a potential new entry.\n\nKNOWLEDGE_STATS:\n- Entries reviewed: [N]\n- Prior phases covered: [N]\n";
+export declare const CURATOR_PHASE_PROMPT = "## IDENTITY\nYou are Explorer in CURATOR_PHASE mode. You consolidate a completed phase into a digest.\nDO NOT use the Task tool to delegate. You ARE the agent that does the work.\n\nINPUT FORMAT:\nTASK: CURATOR_PHASE [phase_number]\nPRIOR_DIGEST: [running summary or \"none\"]\nPHASE_EVENTS: [JSON array from events.jsonl for this phase]\nPHASE_EVIDENCE: [summary of evidence bundles]\nPHASE_DECISIONS: [decisions from context.md]\nAGENTS_DISPATCHED: [list]\nAGENTS_EXPECTED: [list from config]\nKNOWLEDGE_ENTRIES: [JSON array of existing entries with UUIDs]\n\nACTIONS:\n- Extend the prior digest with this phase's outcomes (do NOT regenerate from scratch)\n- Observe workflow deviations: missing reviewer, missing retro, skipped test_engineer\n- Report knowledge update candidates with observable evidence: entries that appear promoted, archived, rewritten, or contradicted\n- Summarize key decisions and blockers resolved\n\nRULES:\n- Output under 2000 chars\n- No code modifications\n- Compliance observations are READ-ONLY \u2014 report, do not enforce\n- OBSERVATIONS should not contain directives \u2014 report what is observed, do not instruct the architect what to do\n- Extend the digest, never replace it\n\nOUTPUT FORMAT:\nPHASE_DIGEST:\nphase: [N]\nsummary: [what was accomplished]\nagents_used: [list]\ntasks_completed: [N]/[total]\nkey_decisions: [list]\nblockers_resolved: [list]\n\nCOMPLIANCE:\n- [type] observed: [description] (or \"No deviations observed\")\n\nOBSERVATIONS:\n- entry <uuid> appears high-confidence: [observable evidence]  (suggests boost confidence, mark hive_eligible)\n- entry <uuid> appears stale: [observable evidence]  (suggests archive \u2014 no longer injected)\n- entry <uuid> could be tighter: [what's verbose or duplicate]  (suggests rewrite with tighter version, max 280 chars)\n- entry <uuid> contradicts project state: [observable conflict]  (suggests tag as contradicted)\n- new candidate: [concise lesson text from observed patterns]  (suggests new entry)\nUse the UUID from KNOWLEDGE_ENTRIES when observing about existing entries. Use \"new candidate\" only when observing a potential new entry.\n\nEXTENDED_DIGEST:\n[the full running digest with this phase appended]\n";
 export declare function createExplorerAgent(model: string, customPrompt?: string, customAppendPrompt?: string): AgentDefinition;
-export declare function createExplorerCuratorAgent(model: string, mode: 'CURATOR_INIT' | 'CURATOR_PHASE', customAppendPrompt?: string): AgentDefinition;

package/dist/cli/index.js

@@ -14270,19 +14270,50 @@ async function appendLedgerEvent(directory, eventInput, options) {
   fs.renameSync(tempPath, ledgerPath);
   return event;
 }
+async function appendLedgerEventWithRetry(directory, eventInput, options) {
+  const maxRetries = options.maxRetries ?? 3;
+  const backoffBase = options.backoffMs ?? 10;
+  let currentExpected = options.expectedHash;
+  let attempt = 0;
+  while (true) {
+    try {
+      return await appendLedgerEvent(directory, eventInput, {
+        expectedHash: currentExpected,
+        planHashAfter: options.planHashAfter
+      });
+    } catch (error49) {
+      if (!(error49 instanceof LedgerStaleWriterError) || attempt >= maxRetries) {
+        throw error49;
+      }
+      attempt++;
+      const delayMs = backoffBase * 2 ** (attempt - 1);
+      await new Promise((resolve2) => setTimeout(resolve2, delayMs));
+      if (options.verifyValid) {
+        const stillValid = await options.verifyValid();
+        if (!stillValid) {
+          return null;
+        }
+      }
+      currentExpected = computeCurrentPlanHash(directory);
+    }
+  }
+}
 async function takeSnapshotEvent(directory, plan, options) {
   const payloadHash = computePlanHash(plan);
   const snapshotPayload = {
     plan,
     payload_hash: payloadHash
   };
+  if (options?.approvalMetadata) {
+    snapshotPayload.approval = options.approvalMetadata;
+  }
   const planId = `${plan.swarm}-${plan.title}`.replace(/[^a-zA-Z0-9-_]/g, "_");
   return appendLedgerEvent(directory, {
     event_type: "snapshot",
-    source: "takeSnapshotEvent",
+    source: options?.source ?? "takeSnapshotEvent",
     plan_id: planId,
     payload: snapshotPayload
-  }, options);
+  }, { planHashAfter: options?.planHashAfter });
 }
 async function replayFromLedger(directory, options) {
   const events = await readLedgerEvents(directory);
@@ -14371,6 +14402,40 @@ function applyEventToPlan(plan, event) {
       throw new Error(`applyEventToPlan: unhandled event type "${event.event_type}" at seq ${event.seq}`);
   }
 }
+async function loadLastApprovedPlan(directory, expectedPlanId) {
+  const events = await readLedgerEvents(directory);
+  if (events.length === 0) {
+    return null;
+  }
+  for (let i = events.length - 1;i >= 0; i--) {
+    const event = events[i];
+    if (event.event_type !== "snapshot")
+      continue;
+    if (event.source !== "critic_approved")
+      continue;
+    if (expectedPlanId !== undefined && event.plan_id !== expectedPlanId) {
+      continue;
+    }
+    const payload = event.payload;
+    if (!payload || typeof payload !== "object" || !payload.plan) {
+      continue;
+    }
+    if (expectedPlanId !== undefined) {
+      const payloadPlanId = `${payload.plan.swarm}-${payload.plan.title}`.replace(/[^a-zA-Z0-9-_]/g, "_");
+      if (payloadPlanId !== expectedPlanId) {
+        continue;
+      }
+    }
+    return {
+      plan: payload.plan,
+      seq: event.seq,
+      timestamp: event.timestamp,
+      approval: payload.approval,
+      payloadHash: payload.payload_hash
+    };
+  }
+  return null;
+}
 var LEDGER_SCHEMA_VERSION = "1.0.0", LEDGER_FILENAME = "plan-ledger.jsonl", PLAN_JSON_FILENAME = "plan.json", LedgerStaleWriterError;
 var init_ledger = __esm(() => {
   init_plan_schema();
@@ -14533,6 +14598,23 @@ async function loadPlan(directory) {
                     return rebuilt;
                   }
                 } catch (replayError) {
+                  try {
+                    const approved = await loadLastApprovedPlan(directory, currentPlanId);
+                    if (approved) {
+                      await rebuildPlan(directory, approved.plan);
+                      try {
+                        await takeSnapshotEvent(directory, approved.plan, {
+                          source: "recovery_from_approved_snapshot",
+                          approvalMetadata: approved.approval
+                        });
+                      } catch (healError) {
+                        warn(`[loadPlan] Recovery-heal snapshot append failed: ${healError instanceof Error ? healError.message : String(healError)}. Next loadPlan may re-enter recovery path.`);
+                      }
+                      const approvedPhase = approved.approval && typeof approved.approval === "object" && "phase" in approved.approval ? approved.approval.phase : undefined;
+                      warn(`[loadPlan] Ledger replay failed (${replayError instanceof Error ? replayError.message : String(replayError)}) \u2014 recovered from critic-approved snapshot seq=${approved.seq} (approval phase=${approvedPhase ?? "unknown"}, timestamp=${approved.timestamp}). This may roll the plan back to an earlier phase \u2014 verify before continuing.`);
+                      return approved.plan;
+                    }
+                  } catch {}
                   warn(`[loadPlan] Ledger replay failed during hash-mismatch rebuild: ${replayError instanceof Error ? replayError.message : String(replayError)}. Returning stale plan.json. To recover: check SWARM_PLAN.md for a checkpoint, or run /swarm reset-session.`);
                 }
               }
@@ -14623,6 +14705,31 @@ async function loadPlan(directory) {
       await savePlan(directory, rebuilt);
       return rebuilt;
     }
+    try {
+      const anchorEvents = await readLedgerEvents(directory);
+      if (anchorEvents.length === 0) {
+        warn("[loadPlan] Ledger present but no events readable \u2014 refusing approved-snapshot recovery (cannot verify plan identity).");
+        return null;
+      }
+      const expectedPlanId = anchorEvents[0].plan_id;
+      const approved = await loadLastApprovedPlan(directory, expectedPlanId);
+      if (approved) {
+        const approvedPhase = approved.approval && typeof approved.approval === "object" && "phase" in approved.approval ? approved.approval.phase : undefined;
+        warn(`[loadPlan] Ledger replay returned no plan \u2014 recovered from critic-approved snapshot seq=${approved.seq} timestamp=${approved.timestamp} (approval phase=${approvedPhase ?? "unknown"}). This may roll the plan back to an earlier phase \u2014 verify before continuing.`);
+        await savePlan(directory, approved.plan);
+        try {
+          await takeSnapshotEvent(directory, approved.plan, {
+            source: "recovery_from_approved_snapshot",
+            approvalMetadata: approved.approval
+          });
+        } catch (healError) {
+          warn(`[loadPlan] Recovery-heal snapshot append failed: ${healError instanceof Error ? healError.message : String(healError)}. Next loadPlan may re-enter recovery path.`);
+        }
+        return approved.plan;
+      }
+    } catch (recoveryError) {
+      warn(`[loadPlan] Approved-snapshot recovery failed: ${recoveryError instanceof Error ? recoveryError.message : String(recoveryError)}`);
+    }
   }
   return null;
 }
@@ -14756,16 +14863,31 @@ async function savePlan(directory, plan, options) {
               to_status: task.status,
               source: "savePlan"
             };
-            await appendLedgerEvent(directory, eventInput, {
+            const capturedFromStatus = oldTask.status;
+            const capturedTaskId = task.id;
+            await appendLedgerEventWithRetry(directory, eventInput, {
               expectedHash: currentHash,
-              planHashAfter: hashAfter
+              planHashAfter: hashAfter,
+              maxRetries: 3,
+              verifyValid: async () => {
+                const onDisk = await loadPlanJsonOnly(directory);
+                if (!onDisk)
+                  return true;
+                for (const p of onDisk.phases) {
+                  const t = p.tasks.find((x) => x.id === capturedTaskId);
+                  if (t) {
+                    return t.status === capturedFromStatus;
+                  }
+                }
+                return false;
+              }
             });
           }
         }
       }
     } catch (error49) {
       if (error49 instanceof LedgerStaleWriterError) {
-        throw new Error(`Concurrent plan modification detected: ${error49.message}. Please retry the operation.`);
+        throw new Error(`Concurrent plan modification detected after retries: ${error49.message}. Please retry the operation.`);
       }
       throw error49;
     }
@@ -19211,6 +19333,7 @@ init_manager2();
 // src/state.ts
 init_plan_schema();
 init_telemetry();
+var _rehydrationCache = null;
 var swarmState = {
   activeToolCalls: new Map,
   toolAggregates: new Map,
@@ -19226,6 +19349,22 @@ var swarmState = {
   fullAutoEnabledInConfig: false,
   environmentProfiles: new Map
 };
+function resetSwarmState() {
+  swarmState.activeToolCalls.clear();
+  swarmState.toolAggregates.clear();
+  swarmState.activeAgent.clear();
+  swarmState.delegationChains.clear();
+  swarmState.pendingEvents = 0;
+  swarmState.lastBudgetPct = 0;
+  swarmState.agentSessions.clear();
+  swarmState.pendingRehydrations.clear();
+  swarmState.opencodeClient = null;
+  swarmState.curatorInitAgentNames = [];
+  swarmState.curatorPhaseAgentNames = [];
+  _rehydrationCache = null;
+  swarmState.fullAutoEnabledInConfig = false;
+  swarmState.environmentProfiles.clear();
+}
 function getAgentSession(sessionId) {
   return swarmState.agentSessions.get(sessionId);
 }
@@ -33387,7 +33526,7 @@ async function executeWriteRetro(args, directory) {
         message: "Invalid task ID: path traversal detected"
       }, null, 2);
     }
-    const VALID_TASK_ID = /^(retro-\d+|\d+\.\d+(\.\d+)*)$/;
+    const VALID_TASK_ID = /^(retro-[a-zA-Z0-9][a-zA-Z0-9_-]*|\d+\.\d+(\.\d+)*)$/;
     if (!VALID_TASK_ID.test(tid)) {
       return JSON.stringify({
         success: false,
@@ -33535,6 +33674,7 @@ var write_retro = createSwarmTool({
 var ARCHIVE_ARTIFACTS = [
   "plan.json",
   "plan.md",
+  "plan-ledger.jsonl",
   "context.md",
   "events.jsonl",
   "handoff.md",
@@ -33544,7 +33684,9 @@ var ARCHIVE_ARTIFACTS = [
   "close-lessons.md"
 ];
 var ACTIVE_STATE_TO_CLEAN = [
+  "plan.json",
   "plan.md",
+  "plan-ledger.jsonl",
   "events.jsonl",
   "handoff.md",
   "handoff-prompt.md",
@@ -33619,6 +33761,33 @@ async function handleCloseCommand(directory, args) {
       }
     }
   }
+  const wrotePhaseRetro = closedPhases.length > 0;
+  if (!wrotePhaseRetro && !planExists) {
+    try {
+      const sessionRetroResult = await executeWriteRetro({
+        phase: 1,
+        task_id: "retro-session",
+        summary: isForced ? "Plan-free session force-closed via /swarm close --force" : "Plan-free session closed via /swarm close",
+        task_count: 1,
+        task_complexity: "simple",
+        total_tool_calls: 0,
+        coder_revisions: 0,
+        reviewer_rejections: 0,
+        test_failures: 0,
+        security_findings: 0,
+        integration_issues: 0,
+        metadata: { session_scope: "plan_free" }
+      }, directory);
+      try {
+        const parsed = JSON.parse(sessionRetroResult);
+        if (parsed.success !== true) {
+          warnings.push(`Session retrospective write failed: ${parsed.message ?? "unknown"}`);
+        }
+      } catch {}
+    } catch (retroError) {
+      warnings.push(`Session retrospective write threw: ${retroError instanceof Error ? retroError.message : String(retroError)}`);
+    }
+  }
   const lessonsFilePath = path11.join(swarmDir, "close-lessons.md");
   let explicitLessons = [];
   try {
@@ -33631,6 +33800,8 @@ async function handleCloseCommand(directory, args) {
     await curateAndStoreSwarm(explicitLessons, projectName, { phase_number: 0 }, directory, config3);
     curationSucceeded = true;
   } catch (error93) {
+    const msg = error93 instanceof Error ? error93.message : String(error93);
+    warnings.push(`Lessons curation failed: ${msg}`);
     console.warn("[close-command] curateAndStoreSwarm error:", error93);
   }
   if (curationSucceeded && explicitLessons.length > 0) {
@@ -33656,6 +33827,8 @@ async function handleCloseCommand(directory, args) {
     try {
       await fs6.writeFile(planPath, JSON.stringify(planData, null, 2), "utf-8");
     } catch (error93) {
+      const msg = error93 instanceof Error ? error93.message : String(error93);
+      warnings.push(`Failed to persist terminal plan.json state: ${msg}`);
       console.warn("[close-command] Failed to write plan.json:", error93);
     }
   }
@@ -33717,6 +33890,8 @@ async function handleCloseCommand(directory, args) {
   try {
     await archiveEvidence(directory, 30, 10);
   } catch (error93) {
+    const msg = error93 instanceof Error ? error93.message : String(error93);
+    warnings.push(`Evidence retention archive failed: ${msg}`);
     console.warn("[close-command] archiveEvidence error:", error93);
   }
   let configBackupsRemoved = 0;
@@ -33745,6 +33920,12 @@ async function handleCloseCommand(directory, args) {
         configBackupsRemoved++;
       } catch {}
     }
+    const ledgerSiblings = swarmFiles.filter((f) => (f.startsWith("plan-ledger.archived-") || f.startsWith("plan-ledger.backup-")) && f.endsWith(".jsonl"));
+    for (const sibling of ledgerSiblings) {
+      try {
+        await fs6.unlink(path11.join(swarmDir, sibling));
+      } catch {}
+    }
   } catch {}
   const contextPath = path11.join(swarmDir, "context.md");
   const contextContent = [
@@ -33761,6 +33942,8 @@ async function handleCloseCommand(directory, args) {
   try {
     await fs6.writeFile(contextPath, contextContent, "utf-8");
   } catch (error93) {
+    const msg = error93 instanceof Error ? error93.message : String(error93);
+    warnings.push(`Failed to reset context.md: ${msg}`);
     console.warn("[close-command] Failed to write context.md:", error93);
   }
   const pruneBranches = args.includes("--prune-branches");
@@ -33890,16 +34073,27 @@ async function handleCloseCommand(directory, args) {
   try {
     await fs6.writeFile(closeSummaryPath, summaryContent, "utf-8");
   } catch (error93) {
+    const msg = error93 instanceof Error ? error93.message : String(error93);
+    warnings.push(`Failed to write close-summary.md: ${msg}`);
     console.warn("[close-command] Failed to write close-summary.md:", error93);
   }
   try {
     await flushPendingSnapshot(directory);
   } catch (error93) {
+    const msg = error93 instanceof Error ? error93.message : String(error93);
+    warnings.push(`flushPendingSnapshot failed: ${msg}`);
     console.warn("[close-command] flushPendingSnapshot error:", error93);
   }
   await writeCheckpoint(directory).catch(() => {});
-  swarmState.agentSessions.clear();
-  swarmState.delegationChains.clear();
+  const preservedClient = swarmState.opencodeClient;
+  const preservedFullAutoFlag = swarmState.fullAutoEnabledInConfig;
+  const preservedCuratorInitNames = swarmState.curatorInitAgentNames;
+  const preservedCuratorPhaseNames = swarmState.curatorPhaseAgentNames;
+  resetSwarmState();
+  swarmState.opencodeClient = preservedClient;
+  swarmState.fullAutoEnabledInConfig = preservedFullAutoFlag;
+  swarmState.curatorInitAgentNames = preservedCuratorInitNames;
+  swarmState.curatorPhaseAgentNames = preservedCuratorPhaseNames;
   if (pruneErrors.length > 0) {
     warnings.push(`Could not prune ${pruneErrors.length} branch(es) (unmerged or checked out): ${pruneErrors.join(", ")}`);
   }

package/dist/hooks/curator.d.ts

@@ -7,6 +7,22 @@
  * callback for LLM-based analysis. When provided, the prepared data context is sent
  * to the explorer agent in CURATOR_PHASE/CURATOR_INIT mode for richer analysis.
  * When the delegate is absent or fails, falls back to data-only behavior.
+ *
+ * ## Curator Agent Dispatch Modes
+ *
+ * Curator agents are dispatched in two ways:
+ *
+ * 1. **Factory dispatch** (standard): Created via `createCuratorAgent` from curator-agent.ts,
+ *    exposed through agents/index.ts. These appear in agent lists and are part of the
+ *    standard agent factory.
+ *
+ * 2. **Hook dispatch** (internal): curator.ts imports CURATOR_INIT_PROMPT and CURATOR_PHASE_PROMPT
+ *    from explorer.ts and dispatches curator analysis directly via hook callbacks. These
+ *    hook-dispatched curators do NOT go through the standard agent factory and are NOT
+ *    included in agent lists (e.g., AGENTS.md, agent discovery, the agent registry).
+ *
+ * This dual dispatch means agent lists are incomplete — they capture factory-dispatched
+ * curators but omit hook-dispatched ones. This is by design for hook-internal operations.
  */
 import type { ComplianceObservation, CuratorConfig, CuratorInitResult, CuratorPhaseResult, CuratorSummary, KnowledgeRecommendation } from './curator-types.js';
 import type { KnowledgeConfig } from './knowledge-types.js';
@@ -17,8 +33,11 @@ import type { KnowledgeConfig } from './knowledge-types.js';
  */
 export type CuratorLLMDelegate = (systemPrompt: string, userInput: string, signal?: AbortSignal) => Promise<string>;
 /**
- * Parse KNOWLEDGE_UPDATES section from curator LLM output.
- * Expected format per line: "- [action] [entry_id or "new"]: [reason]"
+ * Parse OBSERVATIONS section from curator LLM output.
+ * Expected format per line: "- entry <uuid> (<observable>): [text]"
+ * Observable types: appears high-confidence, appears stale, could be tighter,
+ * contradicts project state, new candidate
+ * Action hints are extracted from parenthetical directives like "(suggests boost confidence, mark hive_eligible)"
  */
 export declare function parseKnowledgeRecommendations(llmOutput: string): KnowledgeRecommendation[];
 /**