cclaw-cli 0.51.26 → 0.51.27

package/dist/delegation.js

@@ -10,6 +10,35 @@ import { readFlowState } from "./runs.js";
 import { stageSchema } from "./content/stage-schema.js";
 const execFileAsync = promisify(execFile);
 const TERMINAL_DELEGATION_STATUSES = new Set(["completed", "failed", "waived", "stale"]);
+export const DELEGATION_DISPATCH_SURFACES = [
+    "claude-task",
+    "cursor-task",
+    "opencode-agent",
+    "codex-agent",
+    "generic-task",
+    "role-switch",
+    "manual"
+];
+/**
+ * Per-surface allowed agent-definition path prefixes. Used by the generated
+ * `.cclaw/hooks/delegation-record.mjs` helper to reject mismatched
+ * `--agent-definition-path` values without inspecting any harness state.
+ *
+ * The list is intentionally structural: each surface maps to one or more
+ * repo-relative path prefixes that must be a parent of the supplied path.
+ * `role-switch` and `manual` accept any path because the agent-definition
+ * is intentionally not a generated artifact for those surfaces.
+ */
+export const DELEGATION_DISPATCH_SURFACE_PATH_PREFIXES = {
+    "claude-task": [".claude/agents/", ".cclaw/agents/"],
+    "cursor-task": [".cursor/agents/", ".cclaw/agents/"],
+    "opencode-agent": [".opencode/agents/", ".cclaw/agents/"],
+    "codex-agent": [".codex/agents/", ".cclaw/agents/"],
+    "generic-task": [".cclaw/agents/"],
+    "role-switch": [],
+    "manual": []
+};
+export const DELEGATION_LEDGER_SCHEMA_VERSION = 3;
 function delegationLogPath(projectRoot) {
     return path.join(projectRoot, RUNTIME_ROOT, "state", "delegation-log.json");
 }
@@ -175,7 +204,8 @@ function isDelegationEntry(value) {
             o.fulfillmentMode === "isolated" ||
             o.fulfillmentMode === "generic-dispatch" ||
             o.fulfillmentMode === "role-switch" ||
-            o.fulfillmentMode === "harness-waiver") &&
+            o.fulfillmentMode === "harness-waiver" ||
+            o.fulfillmentMode === "legacy-inferred") &&
         (o.conditionTrigger === undefined || typeof o.conditionTrigger === "string") &&
         (o.dispatchId === undefined || typeof o.dispatchId === "string") &&
         (o.workerRunId === undefined || typeof o.workerRunId === "string") &&
@@ -188,16 +218,10 @@ function isDelegationEntry(value) {
         retryOk &&
         (o.evidenceRefs === undefined || (Array.isArray(o.evidenceRefs) && o.evidenceRefs.every((item) => typeof item === "string"))) &&
         (o.skill === undefined || typeof o.skill === "string") &&
-        (o.schemaVersion === undefined || o.schemaVersion === 1));
+        (o.schemaVersion === undefined || o.schemaVersion === 1 || o.schemaVersion === 2 || o.schemaVersion === 3));
 }
 function isDelegationDispatchSurface(value) {
-    return (value === "claude-task" ||
-        value === "cursor-task" ||
-        value === "opencode-agent" ||
-        value === "codex-agent" ||
-        value === "generic-task" ||
-        value === "role-switch" ||
-        value === "manual");
+    return typeof value === "string" && DELEGATION_DISPATCH_SURFACES.includes(value);
 }
 function statusTimestampPatch(entry, ts) {
     const patch = { ...entry };
@@ -215,30 +239,50 @@ function eventFromEntry(entry) {
         ...entry,
         event: entry.status,
         eventTs,
-        schemaVersion: 1
+        schemaVersion: DELEGATION_LEDGER_SCHEMA_VERSION
     };
 }
 function isDelegationEvent(value) {
     if (!isDelegationEntry(value))
         return false;
     const o = value;
-    return o.event === o.status && typeof o.eventTs === "string";
+    if (o.event !== o.status || typeof o.eventTs !== "string")
+        return false;
+    return true;
 }
 function parseLedger(raw, runId) {
     if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
-        return { runId, entries: [] };
+        return { runId, entries: [], schemaVersion: DELEGATION_LEDGER_SCHEMA_VERSION };
     }
     const o = raw;
+    const ledgerSchemaVersion = (o.schemaVersion === 1 || o.schemaVersion === 2 || o.schemaVersion === 3
+        ? o.schemaVersion
+        : undefined);
     const entriesRaw = o.entries;
     const entries = [];
     if (Array.isArray(entriesRaw)) {
         for (const item of entriesRaw) {
             if (isDelegationEntry(item)) {
                 const ts = item.startTs ?? item.ts ?? new Date().toISOString();
-                const isLegacyCompletion = item.fulfillmentMode === undefined &&
-                    item.schemaVersion === undefined &&
+                // A row is "pre-v3 legacy" when the file format predates the
+                // dispatch-proof contract: schemaVersion is missing on both ledger
+                // and entry, the entry has no fulfillmentMode, and there is no
+                // dispatch-surface or dispatch-id evidence on the row. We honor
+                // that by tagging fulfillmentMode = "legacy-inferred" so callers
+                // (stage-complete, doctor) can require an explicit `--rerecord`
+                // before the row counts as proof-era.
+                const ledgerHasNoVersion = ledgerSchemaVersion === undefined || ledgerSchemaVersion === 1;
+                const entryHasNoVersion = item.schemaVersion === undefined || item.schemaVersion === 1;
+                const looksLegacy = ledgerHasNoVersion &&
+                    entryHasNoVersion &&
+                    item.fulfillmentMode === undefined &&
+                    item.dispatchSurface === undefined &&
+                    item.dispatchId === undefined &&
+                    item.workerRunId === undefined &&
+                    item.agentDefinitionPath === undefined &&
                     item.status === "completed";
-                const inferredFulfillmentMode = item.fulfillmentMode ?? (isLegacyCompletion ? "isolated" : undefined);
+                const inferredFulfillmentMode = item.fulfillmentMode
+                    ?? (looksLegacy ? "legacy-inferred" : (item.status === "completed" && item.schemaVersion === undefined ? "isolated" : undefined));
                 entries.push({
                     ...item,
                     spanId: item.spanId ?? createSpanId(),
@@ -253,12 +297,12 @@ function parseLedger(raw, runId) {
                         : 0,
                     evidenceRefs: Array.isArray(item.evidenceRefs) ? item.evidenceRefs : [],
                     fulfillmentMode: inferredFulfillmentMode,
-                    schemaVersion: 1
+                    schemaVersion: item.schemaVersion ?? DELEGATION_LEDGER_SCHEMA_VERSION
                 });
             }
         }
     }
-    return { runId, entries };
+    return { runId, entries, schemaVersion: ledgerSchemaVersion ?? DELEGATION_LEDGER_SCHEMA_VERSION };
 }
 export async function readDelegationLedger(projectRoot) {
     const { activeRunId } = await readFlowState(projectRoot);
@@ -348,7 +392,7 @@ export async function appendDelegation(projectRoot, entry) {
         if (stamped.status === "scheduled") {
             delete stamped.endTs;
         }
-        stamped.schemaVersion = 1;
+        stamped.schemaVersion = DELEGATION_LEDGER_SCHEMA_VERSION;
         if (stamped.retryCount === undefined ||
             !Number.isInteger(stamped.retryCount) ||
             stamped.retryCount < 0) {
@@ -378,7 +422,8 @@ export async function appendDelegation(projectRoot, entry) {
         await appendDelegationEvent(projectRoot, eventFromEntry(stamped));
         const ledger = {
             runId: activeRunId,
-            entries: [...prior.entries, stamped]
+            entries: [...prior.entries, stamped],
+            schemaVersion: DELEGATION_LEDGER_SCHEMA_VERSION
         };
         await writeFileSafe(filePath, `${JSON.stringify(ledger, null, 2)}\n`, { mode: 0o600 });
         await writeSubagentTracker(projectRoot, ledger.entries);
@@ -419,6 +464,7 @@ export async function checkMandatoryDelegations(projectRoot, stage, options = {}
     const missingEvidence = [];
     const missingDispatchProof = [];
     const legacyInferredCompletions = [];
+    let legacyRequiresRerecord = false;
     const terminalSpanIds = new Set(forRun
         .filter((entry) => TERMINAL_DELEGATION_STATUSES.has(entry.status) && entry.spanId)
         .map((entry) => entry.spanId));
@@ -454,8 +500,20 @@ export async function checkMandatoryDelegations(projectRoot, stage, options = {}
             !completedRows.some((e) => Array.isArray(e.evidenceRefs) && e.evidenceRefs.length > 0)) {
             missingEvidence.push(agent);
         }
+        // legacyInferredCompletions has two sources, split by `legacyTagged`:
+        //   - legacyTagged === true : the row was *parsed* as legacy-inferred
+        //     from a pre-v3 ledger file. Requires `delegation-record.mjs
+        //     --rerecord` and BLOCKS satisfied.
+        //   - legacyTagged === false: in-check inference for minimally-spec'd
+        //     isolated rows that lack proof-era signals. Advisory only —
+        //     preserves backward-compatible behavior for existing API callers.
         for (const row of completedRows) {
             const mode = row.fulfillmentMode ?? "isolated";
+            if (mode === "legacy-inferred") {
+                legacyInferredCompletions.push(`${agent}(spanId=${row.spanId ?? "unknown"})`);
+                legacyRequiresRerecord = true;
+                continue;
+            }
             if (mode === "isolated") {
                 const spanEvents = events.events.filter((event) => event.runId === activeRunId &&
                     event.stage === stage &&
@@ -480,7 +538,12 @@ export async function checkMandatoryDelegations(projectRoot, stage, options = {}
         }
     }
     return {
-        satisfied: missing.length === 0 && missingEvidence.length === 0 && missingDispatchProof.length === 0 && staleWorkers.length === 0 && events.corruptLines.length === 0,
+        satisfied: missing.length === 0 &&
+            missingEvidence.length === 0 &&
+            missingDispatchProof.length === 0 &&
+            !legacyRequiresRerecord &&
+            staleWorkers.length === 0 &&
+            events.corruptLines.length === 0,
         missing,
         waived,
         staleIgnored,

package/dist/harness-adapters.d.ts

@@ -95,6 +95,48 @@ export declare function harnessShimFileNames(): string[];
 export declare function harnessShimSkillNames(): string[];
 export declare const HARNESS_ADAPTERS: Record<HarnessId, HarnessAdapter>;
 export declare function harnessDispatchSurface(harnessId: HarnessId): string;
+export interface HarnessDelegationRecipe {
+    harnessId: HarnessId;
+    dispatchSurface: "claude-task" | "cursor-task" | "opencode-agent" | "codex-agent";
+    agentDefinitionDirectory: string;
+    agentDefinitionExample: string;
+    invocationLine: string;
+    fulfillmentMode: "isolated" | "generic-dispatch";
+    /**
+     * Step-by-step lifecycle commands rendered with structural placeholders only:
+     *  `<agent-name>`, `<stage>`, `<run-id>`, `<span-id>`, `<dispatch-id>`,
+     *  `<agent-def-path>`, `<iso-ts>`. No domain/example values.
+     */
+    lifecycleCommands: string[];
+}
+/**
+ * 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 declare function harnessDelegationRecipe(harnessId: HarnessId): HarnessDelegationRecipe;
+/** All four harness recipes in tier-stable order. */
+export declare function harnessDelegationRecipes(): HarnessDelegationRecipe[];
 export declare function harnessDispatchFallback(harnessId: HarnessId): string;
 export type HarnessTier = "tier1" | "tier2" | "tier3";
 export declare function harnessTier(harnessId: HarnessId): HarnessTier;

package/dist/harness-adapters.js

@@ -184,6 +184,101 @@ export function harnessDispatchSurface(harnessId) {
             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") {

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.26",
+  "version": "0.51.27",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {