cclaw-cli 0.51.25 → 0.51.27

package/dist/harness-adapters.js

@@ -71,6 +71,12 @@ export function harnessShimSkillNames() {
 export const HARNESS_ADAPTERS = {
     claude: {
         id: "claude",
+        reality: {
+            declaredSupport: "full",
+            runtimeLaunch: "native Task launch",
+            proofRequired: "spanId+dispatchId or workerRunId+ACK for isolated completion",
+            proofSource: ".cclaw/state/delegation-events.jsonl plus delegation-log.json"
+        },
         commandDir: ".claude/commands",
         shimKind: "command",
         capabilities: {
@@ -82,6 +88,12 @@ export const HARNESS_ADAPTERS = {
     },
     cursor: {
         id: "cursor",
+        reality: {
+            declaredSupport: "generic",
+            runtimeLaunch: "generic Task/Subagent launch with cclaw role prompt",
+            proofRequired: "spanId+dispatchId/evidenceRefs for generic-dispatch completion",
+            proofSource: ".cclaw/state/delegation-events.jsonl plus artifact evidenceRefs"
+        },
         commandDir: ".cursor/commands",
         shimKind: "command",
         capabilities: {
@@ -97,6 +109,12 @@ export const HARNESS_ADAPTERS = {
     },
     opencode: {
         id: "opencode",
+        reality: {
+            declaredSupport: "full",
+            runtimeLaunch: "prompt-level launch via Task or @agent against generated .opencode/agents",
+            proofRequired: "spanId+dispatchId+ackTs+completedTs before isolated completion",
+            proofSource: ".opencode/agents/<agent>.md and .cclaw/state/delegation-events.jsonl"
+        },
         commandDir: ".opencode/commands",
         shimKind: "command",
         capabilities: {
@@ -119,6 +137,12 @@ export const HARNESS_ADAPTERS = {
     },
     codex: {
         id: "codex",
+        reality: {
+            declaredSupport: "full",
+            runtimeLaunch: "prompt-level launch by asking Codex to spawn generated custom agents",
+            proofRequired: "spanId+dispatchId+ackTs+completedTs before isolated completion",
+            proofSource: ".codex/agents/<agent>.toml and .cclaw/state/delegation-events.jsonl"
+        },
         // Codex CLI reads skills from the universal `.agents/skills/` path
         // (OpenAI Codex 0.89, Jan 2026). It does NOT have a native
         // `.codex/commands/*` slash-command discovery — cclaw installs
@@ -155,11 +179,106 @@ export function harnessDispatchSurface(harnessId) {
         case "cursor":
             return "Use Cursor Subagent/Task with a generic subagent_type (explore for read-only mapping, generalPurpose for broader work, shell/browser-use when specifically needed) and paste the cclaw role prompt; record fulfillmentMode: \"generic-dispatch\" with evidenceRefs.";
         case "opencode":
-            return "Use OpenCode subagents: invoke the generated .opencode/agents/<agent>.md agent via Task or @<agent>, run independent agents in parallel when safe, then record fulfillmentMode: \"isolated\".";
+            return "Use OpenCode subagents: invoke the generated .opencode/agents/<agent>.md agent via Task or @<agent>; record scheduled/launched/acknowledged/completed events with spanId+dispatchId before claiming fulfillmentMode: \"isolated\".";
         case "codex":
-            return "Use Codex native subagents: ask Codex to spawn the generated .codex/agents/<agent>.toml agent(s) by name, wait for all results, then record fulfillmentMode: \"isolated\".";
+            return "Use Codex native subagents: ask Codex to spawn the generated .codex/agents/<agent>.toml agent(s) by name; record scheduled/launched/acknowledged/completed events with spanId+dispatchId before claiming fulfillmentMode: \"isolated\".";
     }
 }
+/**
+ * Per-harness lifecycle recipe used by skills and harness docs to render the
+ * canonical scheduled -> launched -> acknowledged -> completed sequence in
+ * structural form. The recipe never embeds task-specific or domain-specific
+ * placeholders — only neutral angle-bracket tokens (`<agent-name>`, `<stage>`,
+ * `<span-id>`, `<dispatch-id>`, `<agent-def-path>`, `<iso-ts>`).
+ *
+ * This function returns the **canonical primary recipe** for each shipped
+ * harness — the dispatch surface that maps 1:1 onto the harness's vendor-
+ * native subagent surface:
+ *
+ * - `claude` -> `claude-task` (isolated)
+ * - `cursor` -> `cursor-task` (generic-dispatch)
+ * - `opencode` -> `opencode-agent` (isolated)
+ * - `codex` -> `codex-agent` (isolated)
+ *
+ * The remaining `--dispatch-surface` enum values (`generic-task`,
+ * `role-switch`, `manual`) are universal fallback paths available to any
+ * harness when the canonical surface is unavailable; they are documented in
+ * the dispatch-surface table in `docs/harnesses.md` rather than per-harness
+ * here, because their lifecycle commands are structurally identical except
+ * for the surface token. No shipped harness has a non-canonical *primary*
+ * surface, so this function only needs to enumerate the four canonical
+ * recipes above.
+ */
+export function harnessDelegationRecipe(harnessId) {
+    const helper = "node .cclaw/hooks/delegation-record.mjs";
+    const common = "--stage=<stage> --agent=<agent-name> --mode=mandatory --span-id=<span-id> --dispatch-id=<dispatch-id>";
+    switch (harnessId) {
+        case "claude":
+            return {
+                harnessId,
+                dispatchSurface: "claude-task",
+                agentDefinitionDirectory: ".claude/agents/",
+                agentDefinitionExample: ".claude/agents/<agent-name>.md",
+                invocationLine: "Call Task with subagent_type=<agent-name> and prompt body that paraphrases the stage skill role.",
+                fulfillmentMode: "isolated",
+                lifecycleCommands: [
+                    `${helper} ${common} --status=scheduled --dispatch-surface=claude-task --agent-definition-path=.claude/agents/<agent-name>.md --json`,
+                    `${helper} ${common} --status=launched --dispatch-surface=claude-task --agent-definition-path=.claude/agents/<agent-name>.md --launched-ts=<iso-ts> --json`,
+                    `${helper} ${common} --status=acknowledged --dispatch-surface=claude-task --agent-definition-path=.claude/agents/<agent-name>.md --ack-ts=<iso-ts> --json`,
+                    `${helper} ${common} --status=completed --dispatch-surface=claude-task --agent-definition-path=.claude/agents/<agent-name>.md --completed-ts=<iso-ts> --json`
+                ]
+            };
+        case "cursor":
+            return {
+                harnessId,
+                dispatchSurface: "cursor-task",
+                agentDefinitionDirectory: ".cclaw/agents/",
+                agentDefinitionExample: ".cclaw/agents/<agent-name>.md",
+                invocationLine: "Call Task with a generic subagent_type and paste the cclaw role prompt; capture worker output as evidenceRefs in the artifact.",
+                fulfillmentMode: "generic-dispatch",
+                lifecycleCommands: [
+                    `${helper} ${common} --status=scheduled --dispatch-surface=cursor-task --agent-definition-path=.cclaw/agents/<agent-name>.md --json`,
+                    `${helper} ${common} --status=launched --dispatch-surface=cursor-task --agent-definition-path=.cclaw/agents/<agent-name>.md --launched-ts=<iso-ts> --json`,
+                    `${helper} ${common} --status=acknowledged --dispatch-surface=cursor-task --agent-definition-path=.cclaw/agents/<agent-name>.md --ack-ts=<iso-ts> --json`,
+                    `${helper} ${common} --status=completed --dispatch-surface=cursor-task --agent-definition-path=.cclaw/agents/<agent-name>.md --completed-ts=<iso-ts> --evidence-ref=<artifact-anchor> --json`
+                ]
+            };
+        case "opencode":
+            return {
+                harnessId,
+                dispatchSurface: "opencode-agent",
+                agentDefinitionDirectory: ".opencode/agents/",
+                agentDefinitionExample: ".opencode/agents/<agent-name>.md",
+                invocationLine: "Invoke the generated agent via Task or `@<agent-name>`; the agent body lives in `.opencode/agents/<agent-name>.md`.",
+                fulfillmentMode: "isolated",
+                lifecycleCommands: [
+                    `${helper} ${common} --status=scheduled --dispatch-surface=opencode-agent --agent-definition-path=.opencode/agents/<agent-name>.md --json`,
+                    `${helper} ${common} --status=launched --dispatch-surface=opencode-agent --agent-definition-path=.opencode/agents/<agent-name>.md --launched-ts=<iso-ts> --json`,
+                    `${helper} ${common} --status=acknowledged --dispatch-surface=opencode-agent --agent-definition-path=.opencode/agents/<agent-name>.md --ack-ts=<iso-ts> --json`,
+                    `${helper} ${common} --status=completed --dispatch-surface=opencode-agent --agent-definition-path=.opencode/agents/<agent-name>.md --completed-ts=<iso-ts> --json`
+                ]
+            };
+        case "codex":
+            return {
+                harnessId,
+                dispatchSurface: "codex-agent",
+                agentDefinitionDirectory: ".codex/agents/",
+                agentDefinitionExample: ".codex/agents/<agent-name>.toml",
+                invocationLine: "Ask Codex to spawn the named custom agent; the agent definition lives in `.codex/agents/<agent-name>.toml`.",
+                fulfillmentMode: "isolated",
+                lifecycleCommands: [
+                    `${helper} ${common} --status=scheduled --dispatch-surface=codex-agent --agent-definition-path=.codex/agents/<agent-name>.toml --json`,
+                    `${helper} ${common} --status=launched --dispatch-surface=codex-agent --agent-definition-path=.codex/agents/<agent-name>.toml --launched-ts=<iso-ts> --json`,
+                    `${helper} ${common} --status=acknowledged --dispatch-surface=codex-agent --agent-definition-path=.codex/agents/<agent-name>.toml --ack-ts=<iso-ts> --json`,
+                    `${helper} ${common} --status=completed --dispatch-surface=codex-agent --agent-definition-path=.codex/agents/<agent-name>.toml --completed-ts=<iso-ts> --json`
+                ]
+            };
+    }
+}
+/** All four harness recipes in tier-stable order. */
+export function harnessDelegationRecipes() {
+    return harnessesByTier().map((id) => harnessDelegationRecipe(id));
+}
 export function harnessDispatchFallback(harnessId) {
     const adapter = HARNESS_ADAPTERS[harnessId];
     if (adapter.capabilities.subagentFallback !== "role-switch") {
@@ -597,7 +716,7 @@ async function cleanupLegacyCodexSurfaces(projectRoot) {
     }
 }
 function codexAgentToml(agent) {
-    const instructions = `${agent.body}\n\n${enhancedAgentInstruction(agent.name)}`.trim();
+    const instructions = `${agentMarkdown(agent)}\n\n${enhancedAgentInstruction(agent.name)}`.trim();
     const sandboxMode = agent.tools.some((tool) => ["Write", "Edit", "Bash"].includes(tool))
         ? "workspace-write"
         : "read-only";
@@ -625,7 +744,7 @@ permission:
 ${agentMarkdown(agent)}`;
 }
 function enhancedAgentInstruction(agentName) {
-    return `You are the cclaw ${agentName} subagent. Follow the parent prompt as the task boundary, produce evidence suitable for .cclaw/state/delegation-log.json, and do not recursively orchestrate other agents unless the parent explicitly asks.`;
+    return `## Worker ACK Contract\n\nYou are the cclaw ${agentName} subagent. Follow the parent prompt as the task boundary. ACK first with JSON containing spanId, dispatchId or workerRunId, dispatchSurface, agentDefinitionPath, ackTs, and status: "ACK". Finish with the strict return schema plus the same spanId+dispatchId proof so the parent can append .cclaw/state/delegation-events.jsonl and .cclaw/state/delegation-log.json. Do not let the parent claim isolated completion without matching ACK/result proof. Do not recursively orchestrate other agents unless the parent explicitly asks.`;
 }
 async function syncAgentFiles(projectRoot, harnesses) {
     const agentsDir = path.join(projectRoot, RUNTIME_ROOT, "agents");

package/dist/install.js

@@ -13,7 +13,7 @@ import { viewCommandContract, viewCommandSkillMarkdown } from "./content/view-co
 import { subagentDrivenDevSkill, parallelAgentsSkill } from "./content/subagents.js";
 import { sessionHooksSkillMarkdown } from "./content/session-hooks.js";
 import { ironLawRuntimeDocument, ironLawsSkillMarkdown } from "./content/iron-laws.js";
-import { stageCompleteScript, startFlowScript, runHookCmdScript, opencodePluginJs, claudeHooksJson, codexHooksJson, cursorHooksJson } from "./content/hooks.js";
+import { stageCompleteScript, startFlowScript, runHookCmdScript, delegationRecordScript, opencodePluginJs, claudeHooksJson, codexHooksJson, cursorHooksJson } from "./content/hooks.js";
 import { nodeHookRuntimeScript } from "./content/node-hooks.js";
 import { META_SKILL_NAME, usingCclawSkillMarkdown } from "./content/meta-skill.js";
 import { ARTIFACT_TEMPLATES, CURSOR_WORKFLOW_RULE_MDC, RULEBOOK_MARKDOWN, buildRulesJson } from "./content/templates.js";
@@ -884,6 +884,7 @@ async function writeHooks(projectRoot, config) {
         compoundRecurrenceThreshold: config.compound?.recurrenceThreshold
     }));
     await writeFileSafe(path.join(hooksDir, "run-hook.cmd"), runHookCmdScript());
+    await writeFileSafe(path.join(hooksDir, "delegation-record.mjs"), delegationRecordScript());
     const opencodePluginSource = opencodePluginJs();
     await writeFileSafe(path.join(hooksDir, "opencode-plugin.mjs"), opencodePluginSource);
     try {
@@ -892,6 +893,7 @@ async function writeHooks(projectRoot, config) {
             "start-flow.mjs",
             "run-hook.mjs",
             "run-hook.cmd",
+            "delegation-record.mjs",
             "opencode-plugin.mjs"
         ]) {
             await fs.chmod(path.join(hooksDir, script), 0o755);

package/dist/internal/advance-stage.js

@@ -6,7 +6,7 @@ import { resolveArtifactPath } from "../artifact-paths.js";
 import { RUNTIME_ROOT, SHIP_FINALIZATION_MODES } from "../constants.js";
 import { ensureDir } from "../fs-utils.js";
 import { stageAutoSubagentDispatch, stageSchema } from "../content/stage-schema.js";
-import { appendDelegation, checkMandatoryDelegations, readDelegationLedger } from "../delegation.js";
+import { appendDelegation, checkMandatoryDelegations, readDelegationEvents, readDelegationLedger } from "../delegation.js";
 import { verifyCompletedStagesGateClosure, verifyCurrentStageGateEvidence } from "../gate-evidence.js";
 import { extractMarkdownSectionBody, parseLearningsSection } from "../artifact-linter.js";
 import { getAvailableTransitions, getTransitionGuards, isFlowTrack, createInitialFlowState } from "../flow-state.js";
@@ -669,6 +669,9 @@ async function buildValidationReport(projectRoot, flowState, options = {}) {
             missing: delegation.missing,
             waived: delegation.waived,
             missingEvidence: delegation.missingEvidence,
+            missingDispatchProof: delegation.missingDispatchProof,
+            legacyInferredCompletions: delegation.legacyInferredCompletions,
+            corruptEventLines: delegation.corruptEventLines,
             staleWorkers: delegation.staleWorkers,
             expectedMode: delegation.expectedMode
         },
@@ -897,6 +900,48 @@ async function runAdvanceStage(projectRoot, args, io) {
         allowBlockedReviewRoute: blockedReviewRoute
     });
     if (!validation.ok) {
+        const ledgerForDiag = await readDelegationLedger(projectRoot).catch(() => ({ entries: [] }));
+        const eventsForDiag = await readDelegationEvents(projectRoot).catch(() => ({ events: [], corruptLines: [] }));
+        const ledgerEntriesText = await fs.readFile(path.join(projectRoot, ".cclaw/state/delegation-events.jsonl"), "utf8").catch(() => "");
+        const corruptSnippets = (() => {
+            if (validation.delegation.corruptEventLines.length === 0)
+                return [];
+            const lines = ledgerEntriesText.split(/\r?\n/u);
+            return validation.delegation.corruptEventLines.slice(0, 3).map((lineNo) => {
+                const line = lines[lineNo - 1] ?? "";
+                const sample = line.length > 120 ? `${line.slice(0, 117)}...` : line;
+                return `line ${lineNo}: ${sample}`;
+            });
+        })();
+        const dispatchProofDetails = validation.delegation.missingDispatchProof.flatMap((agent) => {
+            const rows = ledgerForDiag.entries.filter((entry) => entry.agent === agent && entry.status === "completed");
+            return rows.map((row) => `${agent}(spanId=${row.spanId ?? "unknown"})`);
+        });
+        const nextActions = [];
+        if (validation.delegation.missing.length > 0) {
+            nextActions.push(`Complete or waive mandatory delegation(s): ${validation.delegation.missing.join(", ")}. Helper: \`node .cclaw/hooks/stage-complete.mjs ${args.stage} --waive-delegation=${validation.delegation.missing.join(",")} --waiver-reason="<why safe>"\`.`);
+        }
+        if (validation.delegation.missingEvidence.length > 0) {
+            nextActions.push(`Role-switch fallback completion needs --evidence-ref or escalate to a real isolated dispatch surface.`);
+        }
+        if (validation.delegation.missingDispatchProof.length > 0) {
+            nextActions.push(`Isolated completion(s) ${dispatchProofDetails.join(", ") || validation.delegation.missingDispatchProof.join(", ")} lack matching dispatch proof; run the helper lifecycle scheduled -> launched -> acknowledged -> completed with --span-id, --dispatch-id, --dispatch-surface and --agent-definition-path before advancing.`);
+        }
+        if (validation.delegation.legacyInferredCompletions.length > 0) {
+            nextActions.push(`Pre-v3 ledger entries found: ${validation.delegation.legacyInferredCompletions.join(", ")}. Run \`node .cclaw/hooks/delegation-record.mjs --rerecord --span-id=<id> --dispatch-id=<id> --dispatch-surface=<surface> --agent-definition-path=<path>\` to upgrade the row to dispatch-proof shape.`);
+        }
+        if (validation.delegation.corruptEventLines.length > 0) {
+            nextActions.push(`delegation-events.jsonl has ${validation.delegation.corruptEventLines.length} corrupt line(s) at ${validation.delegation.corruptEventLines.slice(0, 3).join(", ")}${validation.delegation.corruptEventLines.length > 3 ? ", ..." : ""}; remove or fix them before advancing.`);
+        }
+        if (validation.delegation.staleWorkers.length > 0) {
+            nextActions.push(`Stale scheduled delegations ${validation.delegation.staleWorkers.join(", ")} have no terminal row sharing the same spanId; emit launched/acknowledged/completed (or failed/stale) before advancing.`);
+        }
+        if (validation.gates.issues.length > 0) {
+            nextActions.push("Fix the artifact/gate issue shown in gates.issues, then rerun stage-complete.");
+        }
+        if (validation.completedStages.issues.length > 0) {
+            nextActions.push("Repair previously completed stage gate closure before advancing.");
+        }
         if (args.json) {
             io.stdout.write(`${JSON.stringify({
                 ok: false,
@@ -906,23 +951,12 @@ async function runAdvanceStage(projectRoot, args, io) {
                 delegation: validation.delegation,
                 gates: validation.gates,
                 completedStages: validation.completedStages,
-                nextActions: [
-                    ...(validation.delegation.missing.length > 0
-                        ? [`Complete or waive mandatory delegation(s): ${validation.delegation.missing.join(", ")}.`]
-                        : []),
-                    ...(validation.delegation.missingEvidence.length > 0
-                        ? ["Add evidenceRefs for role-switch delegation completion or use an explicit waiver reason."]
-                        : []),
-                    ...(validation.delegation.staleWorkers.length > 0
-                        ? ["Resolve scheduled delegation span(s) without terminal lifecycle evidence before advancing."]
-                        : []),
-                    ...(validation.gates.issues.length > 0
-                        ? ["Fix the artifact/gate issue shown in gates.issues, then rerun stage-complete."]
-                        : []),
-                    ...(validation.completedStages.issues.length > 0
-                        ? ["Repair previously completed stage gate closure before advancing."]
-                        : [])
-                ]
+                diagnostics: {
+                    dispatchProofRows: dispatchProofDetails,
+                    corruptEventSamples: corruptSnippets,
+                    unawareEvents: eventsForDiag.corruptLines.length
+                },
+                nextActions
             })}\n`);
         }
         io.stderr.write(`cclaw internal advance-stage: validation failed for stage "${args.stage}".\n`);
@@ -932,9 +966,25 @@ async function runAdvanceStage(projectRoot, args, io) {
         }
         if (validation.delegation.missingEvidence.length > 0) {
             io.stderr.write(`- role-switch evidence missing: ${validation.delegation.missingEvidence.join(", ")}\n`);
+            io.stderr.write(`  next action: include --evidence-ref=<artifact#anchor> when emitting the completed event, or escalate to a true isolated dispatch surface.\n`);
+        }
+        if (validation.delegation.missingDispatchProof.length > 0) {
+            io.stderr.write(`- isolated completion lacks dispatch proof: ${dispatchProofDetails.join(", ") || validation.delegation.missingDispatchProof.join(", ")}\n`);
+            io.stderr.write(`  next action: emit scheduled -> launched -> acknowledged -> completed with --span-id, --dispatch-id, --dispatch-surface, --agent-definition-path before advancing.\n`);
+        }
+        if (validation.delegation.legacyInferredCompletions.length > 0) {
+            io.stderr.write(`- legacy-inferred completions need rerecord: ${validation.delegation.legacyInferredCompletions.join(", ")}\n`);
+            io.stderr.write(`  next action: \`node .cclaw/hooks/delegation-record.mjs --rerecord --span-id=<id> --dispatch-id=<id> --dispatch-surface=<surface> --agent-definition-path=<path>\`.\n`);
+        }
+        if (validation.delegation.corruptEventLines.length > 0) {
+            io.stderr.write(`- corrupt delegation-events.jsonl line(s): ${validation.delegation.corruptEventLines.slice(0, 3).join(", ")}${validation.delegation.corruptEventLines.length > 3 ? `, ... (+${validation.delegation.corruptEventLines.length - 3})` : ""}\n`);
+            for (const snippet of corruptSnippets) {
+                io.stderr.write(`    sample: ${snippet}\n`);
+            }
         }
         if (validation.delegation.staleWorkers.length > 0) {
             io.stderr.write(`- stale scheduled delegations: ${validation.delegation.staleWorkers.join(", ")}\n`);
+            io.stderr.write(`  next action: emit a terminal row (completed/failed/stale) for the same span before advancing.\n`);
         }
         if (validation.gates.issues.length > 0) {
             io.stderr.write(`- gate issues: ${validation.gates.issues.join(" | ")}\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "0.51.25",
+  "version": "0.51.27",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {