cclaw-cli 0.51.25 → 0.51.27

package/dist/delegation.js

@@ -9,13 +9,48 @@ import { HARNESS_ADAPTERS } from "./harness-adapters.js";
 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"]);
+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");
 }
 function delegationLockPath(projectRoot) {
     return path.join(projectRoot, RUNTIME_ROOT, "state", ".delegation.lock");
 }
+function delegationEventsPath(projectRoot) {
+    return path.join(projectRoot, RUNTIME_ROOT, "state", "delegation-events.jsonl");
+}
+function subagentsStatePath(projectRoot) {
+    return path.join(projectRoot, RUNTIME_ROOT, "state", "subagents.json");
+}
 function createSpanId() {
     return `dspan-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
 }
@@ -131,13 +166,16 @@ function isDelegationEntry(value) {
     const o = value;
     const modeOk = o.mode === "mandatory" || o.mode === "proactive";
     const statusOk = o.status === "scheduled" ||
+        o.status === "launched" ||
+        o.status === "acknowledged" ||
         o.status === "completed" ||
         o.status === "failed" ||
-        o.status === "waived";
+        o.status === "waived" ||
+        o.status === "stale";
     const timestampOk = typeof o.ts === "string" ||
         typeof o.startTs === "string";
-    const terminalStatus = o.status === "completed" || o.status === "failed" || o.status === "waived";
-    const lifecycleOk = o.status !== "scheduled" || o.endTs === undefined;
+    const terminalStatus = o.status === "completed" || o.status === "failed" || o.status === "waived" || o.status === "stale";
+    const lifecycleOk = (o.status !== "scheduled" && o.status !== "launched" && o.status !== "acknowledged") || o.endTs === undefined;
     const terminalLifecycleOk = !terminalStatus ||
         o.endTs === undefined ||
         typeof o.endTs === "string";
@@ -166,46 +204,105 @@ 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") &&
+        (o.dispatchSurface === undefined || isDelegationDispatchSurface(o.dispatchSurface)) &&
+        (o.agentDefinitionPath === undefined || typeof o.agentDefinitionPath === "string") &&
+        (o.ackTs === undefined || typeof o.ackTs === "string") &&
+        (o.launchedTs === undefined || typeof o.launchedTs === "string") &&
+        (o.completedTs === undefined || typeof o.completedTs === "string") &&
         (o.tokens === undefined || isDelegationTokenUsage(o.tokens)) &&
         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 typeof value === "string" && DELEGATION_DISPATCH_SURFACES.includes(value);
+}
+function statusTimestampPatch(entry, ts) {
+    const patch = { ...entry };
+    if (patch.status === "launched")
+        patch.launchedTs = patch.launchedTs ?? ts;
+    if (patch.status === "acknowledged")
+        patch.ackTs = patch.ackTs ?? ts;
+    if (patch.status === "completed")
+        patch.completedTs = patch.completedTs ?? patch.endTs ?? ts;
+    return patch;
+}
+function eventFromEntry(entry) {
+    const eventTs = entry.completedTs ?? entry.ackTs ?? entry.launchedTs ?? entry.endTs ?? entry.startTs ?? entry.ts ?? new Date().toISOString();
+    return {
+        ...entry,
+        event: entry.status,
+        eventTs,
+        schemaVersion: DELEGATION_LEDGER_SCHEMA_VERSION
+    };
+}
+function isDelegationEvent(value) {
+    if (!isDelegationEntry(value))
+        return false;
+    const o = value;
+    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(),
                     startTs: ts,
                     endTs: TERMINAL_DELEGATION_STATUSES.has(item.status) ? (item.endTs ?? ts) : undefined,
                     ts,
+                    launchedTs: item.launchedTs ?? (item.status === "launched" ? ts : undefined),
+                    ackTs: item.ackTs ?? (item.status === "acknowledged" ? ts : undefined),
+                    completedTs: item.completedTs ?? (item.status === "completed" ? (item.endTs ?? ts) : undefined),
                     retryCount: typeof item.retryCount === "number" && Number.isInteger(item.retryCount) && item.retryCount >= 0
                         ? item.retryCount
                         : 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);
@@ -222,6 +319,57 @@ export async function readDelegationLedger(projectRoot) {
         return { runId: activeRunId, entries: [] };
     }
 }
+export async function readDelegationEvents(projectRoot) {
+    const filePath = delegationEventsPath(projectRoot);
+    if (!(await exists(filePath))) {
+        return { events: [], corruptLines: [] };
+    }
+    const events = [];
+    const corruptLines = [];
+    const text = await fs.readFile(filePath, "utf8").catch(() => "");
+    const lines = text.split(/\r?\n/gu);
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index]?.trim() ?? "";
+        if (line.length === 0)
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (isDelegationEvent(parsed)) {
+                events.push(parsed);
+            }
+            else {
+                corruptLines.push(index + 1);
+            }
+        }
+        catch {
+            corruptLines.push(index + 1);
+        }
+    }
+    return { events, corruptLines };
+}
+async function appendDelegationEvent(projectRoot, event) {
+    const filePath = delegationEventsPath(projectRoot);
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.appendFile(filePath, `${JSON.stringify(event)}\n`, { encoding: "utf8", mode: 0o600 });
+}
+async function writeSubagentTracker(projectRoot, entries) {
+    const active = entries
+        .filter((entry) => entry.status === "scheduled" || entry.status === "launched" || entry.status === "acknowledged")
+        .map((entry) => ({
+        spanId: entry.spanId,
+        dispatchId: entry.dispatchId,
+        workerRunId: entry.workerRunId,
+        stage: entry.stage,
+        agent: entry.agent,
+        status: entry.status,
+        dispatchSurface: entry.dispatchSurface,
+        agentDefinitionPath: entry.agentDefinitionPath,
+        startedAt: entry.startTs,
+        launchedAt: entry.launchedTs,
+        acknowledgedAt: entry.ackTs
+    }));
+    await writeFileSafe(subagentsStatePath(projectRoot), `${JSON.stringify({ active, updatedAt: new Date().toISOString() }, null, 2)}\n`, { mode: 0o600 });
+}
 export async function appendDelegation(projectRoot, entry) {
     const { activeRunId } = await readFlowState(projectRoot);
     await withDirectoryLock(delegationLockPath(projectRoot), async () => {
@@ -231,17 +379,20 @@ export async function appendDelegation(projectRoot, entry) {
         if (entry.status === "waived" && !hasValidWaiverReason(entry.waiverReason)) {
             throw new Error("waived delegation entries require a non-empty waiverReason");
         }
-        const stamped = { ...entry, runId: entry.runId ?? activeRunId };
+        const stamped = statusTimestampPatch({ ...entry, runId: entry.runId ?? activeRunId }, startTs);
         stamped.spanId = entry.spanId ?? createSpanId();
         stamped.startTs = startTs;
         stamped.ts = startTs;
         if (TERMINAL_DELEGATION_STATUSES.has(stamped.status) && !stamped.endTs) {
             stamped.endTs = new Date().toISOString();
         }
+        if (stamped.status === "completed") {
+            stamped.completedTs = stamped.completedTs ?? stamped.endTs ?? new Date().toISOString();
+        }
         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) {
@@ -268,11 +419,14 @@ export async function appendDelegation(projectRoot, entry) {
         if (prior.entries.some((existing) => existing.spanId === stamped.spanId && existing.status === stamped.status)) {
             return;
         }
+        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);
     });
 }
 /**
@@ -299,6 +453,7 @@ export async function checkMandatoryDelegations(projectRoot, stage, options = {}
     const mandatory = stageSchema(stage, flowState.track).mandatoryDelegations;
     const { activeRunId } = flowState;
     const ledger = await readDelegationLedger(projectRoot);
+    const events = await readDelegationEvents(projectRoot);
     const forStage = ledger.entries.filter((e) => e.stage === stage);
     const forRun = forStage.filter((e) => e.runId === activeRunId);
     const staleIgnored = forStage
@@ -307,6 +462,9 @@ export async function checkMandatoryDelegations(projectRoot, stage, options = {}
     const missing = [];
     const waived = [];
     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));
@@ -342,13 +500,57 @@ 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 &&
+                    event.agent === agent &&
+                    event.spanId === row.spanId);
+                const dispatchId = row.dispatchId ?? row.workerRunId ?? spanEvents.find((event) => event.dispatchId || event.workerRunId)?.dispatchId ?? spanEvents.find((event) => event.workerRunId)?.workerRunId;
+                const dispatchSurface = row.dispatchSurface ?? spanEvents.find((event) => event.dispatchSurface)?.dispatchSurface;
+                const agentDefinitionPath = row.agentDefinitionPath ?? spanEvents.find((event) => event.agentDefinitionPath)?.agentDefinitionPath;
+                const hasAck = Boolean(row.ackTs || spanEvents.some((event) => event.event === "acknowledged" && event.ackTs));
+                const hasCompleted = Boolean(row.completedTs || spanEvents.some((event) => event.event === "completed" && event.completedTs));
+                const hasDispatchProof = Boolean(row.spanId && dispatchId && dispatchSurface && agentDefinitionPath && hasAck && hasCompleted);
+                if (!hasDispatchProof) {
+                    const proofEraSignal = Boolean(row.dispatchId || row.workerRunId || row.dispatchSurface || row.agentDefinitionPath || spanEvents.some((event) => event.dispatchId || event.workerRunId || event.dispatchSurface || event.agentDefinitionPath || event.event === "acknowledged" || event.event === "launched"));
+                    if (proofEraSignal) {
+                        missingDispatchProof.push(agent);
+                    }
+                    else {
+                        legacyInferredCompletions.push(`${agent}(spanId=${row.spanId ?? "unknown"})`);
+                    }
+                }
+            }
+        }
     }
     return {
-        satisfied: missing.length === 0 && missingEvidence.length === 0 && staleWorkers.length === 0,
+        satisfied: missing.length === 0 &&
+            missingEvidence.length === 0 &&
+            missingDispatchProof.length === 0 &&
+            !legacyRequiresRerecord &&
+            staleWorkers.length === 0 &&
+            events.corruptLines.length === 0,
         missing,
         waived,
         staleIgnored,
         missingEvidence,
+        missingDispatchProof,
+        legacyInferredCompletions,
+        corruptEventLines: events.corruptLines,
         staleWorkers,
         expectedMode
     };

package/dist/doctor-registry.js

@@ -107,6 +107,15 @@ const RULES = [
             docRef: ref("harnesses.md")
         }
     },
+    {
+        test: /^harness:reality:/,
+        metadata: {
+            severity: "info",
+            summary: "Harness reality label for dispatch/proof support.",
+            fix: "No action required; use this label to interpret native/generic/role-switch proof requirements.",
+            docRef: ref("harnesses.md")
+        }
+    },
     {
         test: /^delegation:/,
         metadata: {

package/dist/doctor.js

@@ -13,7 +13,7 @@ import { policyChecks } from "./policy.js";
 import { CorruptFlowStateError, readFlowState } from "./runs.js";
 import { createInitialFlowState, skippedStagesForTrack } from "./flow-state.js";
 import { FLOW_STAGES, TRACK_STAGES } from "./types.js";
-import { checkMandatoryDelegations } from "./delegation.js";
+import { checkMandatoryDelegations, readDelegationEvents } from "./delegation.js";
 import { buildTraceMatrix } from "./trace-matrix.js";
 import { classifyReconciliationNotices, reconcileAndWriteCurrentStageGateCatalog, readReconciliationNotices, RECONCILIATION_NOTICES_REL_PATH, verifyCompletedStagesGateClosure, verifyCurrentStageGateEvidence } from "./gate-evidence.js";
 import { parseTddCycleLog, validateTddCycleOrder } from "./tdd-cycle.js";
@@ -305,6 +305,20 @@ function normalizeOpenCodePluginEntry(entry) {
     }
     return null;
 }
+function generatedAgentShape(content, kind, agentName) {
+    if (kind === "opencode") {
+        return content.includes("mode: subagent") && content.includes(`# ${agentName}`) && content.includes("STRICT_RETURN_SCHEMA");
+    }
+    return content.includes(`name = "${agentName}"`) && content.includes("developer_instructions") && content.includes("STRICT_RETURN_SCHEMA");
+}
+function harnessRealityLabel(harness) {
+    const adapter = HARNESS_ADAPTERS[harness];
+    const declaredSupport = adapter.capabilities.nativeSubagentDispatch;
+    const runtimeLaunch = harness === "opencode" || harness === "codex" ? "prompt-level launch" : declaredSupport === "generic" ? "generic Task launch" : "native tool launch";
+    const proofRequired = adapter.capabilities.subagentFallback === "native" ? "dispatchId+spanId+ack" : "evidenceRefs";
+    const proofSource = harness === "opencode" ? ".opencode/agents + delegation-events.jsonl" : harness === "codex" ? ".codex/agents + delegation-events.jsonl" : ".cclaw/state/delegation-log.json";
+    return `declaredSupport=${declaredSupport}; runtimeLaunch=${runtimeLaunch}; proofRequired=${proofRequired}; proofSource=${proofSource}`;
+}
 const OPENCODE_PLUGIN_REL_PATH = ".opencode/plugins/cclaw-plugin.mjs";
 function opencodeConfigCandidates(projectRoot) {
     return [
@@ -780,6 +794,14 @@ export async function doctorChecks(projectRoot, options = {}) {
             }
         }
     }
+    for (const harness of configuredHarnesses) {
+        checks.push({
+            name: `harness:reality:${harness}`,
+            ok: true,
+            severity: "info",
+            details: harnessRealityLabel(harness)
+        });
+    }
     const agentsFile = path.join(projectRoot, "AGENTS.md");
     let agentsBlockOk = false;
     if (await exists(agentsFile)) {
@@ -884,12 +906,39 @@ export async function doctorChecks(projectRoot, options = {}) {
             details: agentPath
         });
     }
+    for (const agent of CCLAW_AGENTS) {
+        if (configuredHarnesses.includes("opencode")) {
+            const agentPath = path.join(projectRoot, ".opencode", "agents", `${agent.name}.md`);
+            let ok = false;
+            if (await exists(agentPath)) {
+                ok = generatedAgentShape(await fs.readFile(agentPath, "utf8"), "opencode", agent.name);
+            }
+            checks.push({
+                name: `agent:opencode:${agent.name}:shape`,
+                ok,
+                details: `${agentPath} must be a generated OpenCode subagent with mode: subagent and strict return schema`
+            });
+        }
+        if (configuredHarnesses.includes("codex")) {
+            const agentPath = path.join(projectRoot, ".codex", "agents", `${agent.name}.toml`);
+            let ok = false;
+            if (await exists(agentPath)) {
+                ok = generatedAgentShape(await fs.readFile(agentPath, "utf8"), "codex", agent.name);
+            }
+            checks.push({
+                name: `agent:codex:${agent.name}:shape`,
+                ok,
+                details: `${agentPath} must be a generated Codex custom agent TOML with developer_instructions and strict return schema`
+            });
+        }
+    }
     // Hook scripts
     for (const script of [
         "run-hook.mjs",
         "run-hook.cmd",
         "stage-complete.mjs",
         "start-flow.mjs",
+        "delegation-record.mjs",
         "opencode-plugin.mjs"
     ]) {
         const scriptPath = path.join(projectRoot, RUNTIME_ROOT, "hooks", script);
@@ -1774,6 +1823,7 @@ export async function doctorChecks(projectRoot, options = {}) {
     const delegation = await checkMandatoryDelegations(projectRoot, flowState.currentStage, {
         repairFeatureSystem: false
     });
+    const delegationEvents = await readDelegationEvents(projectRoot);
     const delegationSatisfiedForDoctor = currentStageUntouched || delegation.satisfied;
     const missingEvidenceNote = delegation.missingEvidence && delegation.missingEvidence.length > 0
         ? ` (role-switch rows without evidenceRefs: ${delegation.missingEvidence.join(", ")})`
@@ -1785,7 +1835,30 @@ export async function doctorChecks(projectRoot, options = {}) {
             ? `mandatory delegation check deferred for untouched stage "${flowState.currentStage}"; stage-complete enforces it when work begins`
             : delegation.satisfied
                 ? `All mandatory delegations satisfied for stage "${flowState.currentStage}" (mode: ${delegation.expectedMode})`
-                : `Missing mandatory delegations for stage "${flowState.currentStage}": ${delegation.missing.join(", ")}${missingEvidenceNote}`
+                : `Missing mandatory delegations for stage "${flowState.currentStage}": ${delegation.missing.join(", ")}${missingEvidenceNote}; missingDispatchProof=${delegation.missingDispatchProof.join(", ")}; staleWorkers=${delegation.staleWorkers.join(", ")}; corruptEventLines=${delegation.corruptEventLines.join(", ")}`
+    });
+    checks.push({
+        name: "delegation:events:parse",
+        ok: delegationEvents.corruptLines.length === 0,
+        details: delegationEvents.corruptLines.length === 0
+            ? `${RUNTIME_ROOT}/state/delegation-events.jsonl parsed successfully (${delegationEvents.events.length} event(s))`
+            : `corrupt delegation event line(s): ${delegationEvents.corruptLines.join(", ")}`
+    });
+    checks.push({
+        name: "delegation:proof:current_stage",
+        ok: currentStageUntouched || delegation.missingDispatchProof.length === 0,
+        details: currentStageUntouched
+            ? `dispatch proof check deferred for untouched stage "${flowState.currentStage}"`
+            : delegation.missingDispatchProof.length === 0
+                ? `no dispatch proof gaps for current stage "${flowState.currentStage}"`
+                : `isolated completions missing dispatchId/dispatchSurface/agentDefinitionPath/ackTs/completedTs: ${delegation.missingDispatchProof.join(", ")}`
+    });
+    checks.push({
+        name: "warning:delegation:legacy_inferred_completions",
+        ok: true,
+        details: delegation.legacyInferredCompletions.length > 0
+            ? `warning: legacy inferred isolated completion rows lack event-log proof: ${delegation.legacyInferredCompletions.join(", ")}`
+            : "no legacy inferred isolated completions for current stage"
     });
     checks.push({
         name: "warning:delegation:waived",

package/dist/harness-adapters.d.ts

@@ -37,6 +37,12 @@ export type SubagentFallback =
 export type ShimKind = "command" | "skill";
 export interface HarnessAdapter {
     id: HarnessId;
+    reality: {
+        declaredSupport: "full" | "generic" | "partial" | "none";
+        runtimeLaunch: string;
+        proofRequired: string;
+        proofSource: string;
+    };
     /**
      * Root directory where cclaw writes `/cc*` entry points.
      *
@@ -89,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;