cclaw-cli 0.51.28 → 0.51.29

package/dist/cli.d.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import type { FlowTrack, HarnessId } from "./types.js";
+import type { ArchiveDisposition } from "./runs.js";
 type CommandName = "init" | "sync" | "doctor" | "upgrade" | "uninstall" | "archive" | "internal";
 interface ParsedArgs {
     command?: CommandName;
@@ -15,6 +16,8 @@ interface ParsedArgs {
     archiveName?: string;
     archiveSkipRetro?: boolean;
     archiveSkipRetroReason?: string;
+    archiveDisposition?: ArchiveDisposition;
+    archiveDispositionReason?: string;
     /** Hidden plumbing command (`cclaw internal ...`) arguments. */
     internalArgs?: string[];
     showHelp?: boolean;
@@ -23,5 +26,18 @@ interface ParsedArgs {
 export declare function usage(): string;
 declare function parseHarnesses(raw: string): HarnessId[];
 declare function parseTrack(raw: string): FlowTrack;
+declare function parseArchiveDisposition(raw: string): ArchiveDisposition;
+export type HarnessSelectionAnswer = {
+    kind: "accept";
+} | {
+    kind: "all";
+} | {
+    kind: "toggle";
+    indexes: number[];
+} | {
+    kind: "invalid";
+    message: string;
+};
+export declare function parseHarnessSelectionAnswer(raw: string): HarnessSelectionAnswer;
 declare function parseArgs(argv: string[]): ParsedArgs;
-export { parseArgs, parseHarnesses, parseTrack };
+export { parseArgs, parseArchiveDisposition, parseHarnesses, parseTrack };

package/dist/cli.js

@@ -8,9 +8,9 @@ import { doctorChecks, doctorSucceeded } from "./doctor.js";
 import { initCclaw, syncCclaw, uninstallCclaw, upgradeCclaw } from "./install.js";
 import { error, info } from "./logger.js";
 import { FLOW_TRACKS, HARNESS_IDS } from "./types.js";
-import { archiveRun } from "./runs.js";
+import { ARCHIVE_DISPOSITIONS, archiveRun } from "./runs.js";
 import { CCLAW_VERSION, RUNTIME_ROOT } from "./constants.js";
-import { createDefaultConfig } from "./config.js";
+import { createDefaultConfig, readConfig } from "./config.js";
 import { detectHarnesses } from "./init-detect.js";
 import { HARNESS_ADAPTERS } from "./harness-adapters.js";
 import { classifyCodexHooksFlag, codexConfigPath, patchCodexHooksFlag, readCodexConfig, writeCodexConfig } from "./codex-feature-flag.js";
@@ -38,17 +38,21 @@ Commands:
              Flags: --harnesses=<list>  Comma list of harnesses (claude,cursor,opencode,codex).
                     --no-interactive    Skip interactive prompts even on TTY (for CI/scripts).
   sync       Reconcile generated runtime files with the current config.
+             Flags: --harnesses=<list>  Update configured harnesses before syncing.
+                    --interactive      Pick harnesses from a numbered TTY menu.
   doctor     Check install/runtime wiring and print concrete fixes for failures.
              Flags: --explain           Include docs pointers for every check.
                     --json              Emit machine-readable check results.
                     --quiet             Show only failing checks.
                     --only=<filter>     Limit displayed checks (error,warning,hook:,state:,...).
-                    --reconcile-gates   Refresh derived gate status before checking.
+                    --reconcile-gates   Refresh derived gate status before checking; does not repair missing artifacts/tests.
   upgrade    Refresh generated files in .cclaw. Preserves your config.yaml.
   archive    Archive the active run and reset flow state for the next run.
              Flags: --name=<slug>        Override archive folder suffix.
                     --skip-retro         Skip retro gate only when runtime allows it.
                     --retro-reason=<txt> Required rationale with --skip-retro.
+                    --disposition=<completed|cancelled|abandoned>
+                    --reason=<txt>      Required for cancelled/abandoned archives.
   uninstall  Remove .cclaw runtime and the generated harness shim files.
 
 Global flags:
@@ -58,17 +62,18 @@ Global flags:
 Examples:
   npx cclaw-cli
   npx cclaw-cli init --harnesses=claude,cursor --no-interactive
-  npx cclaw-cli sync
+  npx cclaw-cli sync --interactive
   npx cclaw-cli archive --name=my-run
+  npx cclaw-cli archive --disposition=cancelled --reason="deprioritized"
   npx cclaw-cli upgrade
 
 Happy-path work happens inside your harness via /cc, /cc-next,
-/cc-ideate, and /cc-view. Doctor is an operator/support surface:
+/cc-ideate, /cc-view, /cc-finish, and /cc-cancel. Doctor is an operator/support surface:
 it verifies install/runtime wiring, but a real harness smoke test is
 still needed to prove provider auth and model execution.
 
 Docs:   https://github.com/zuevrs/cclaw
-Local:  docs/config.md and docs/harnesses.md
+Local:  README.md and generated .cclaw/skills/*.md
 Issues: https://github.com/zuevrs/cclaw/issues
 `;
 }
@@ -77,6 +82,9 @@ function parseHarnesses(raw) {
         .split(",")
         .map((item) => item.trim())
         .filter(Boolean);
+    if (requested.length === 0) {
+        throw new Error("Select at least one harness.");
+    }
     const invalid = requested.filter((item) => !HARNESS_IDS.includes(item));
     if (invalid.length > 0) {
         throw new Error(`Unknown harnesses: ${invalid.join(", ")}`);
@@ -90,6 +98,13 @@ function parseTrack(raw) {
     }
     return trimmed;
 }
+function parseArchiveDisposition(raw) {
+    const trimmed = raw.trim();
+    if (!ARCHIVE_DISPOSITIONS.includes(trimmed)) {
+        throw new Error(`Unknown archive disposition: ${trimmed}. Supported: ${ARCHIVE_DISPOSITIONS.join(", ")}`);
+    }
+    return trimmed;
+}
 function isInitPromptAllowed(ctx) {
     return Boolean(process.stdin.isTTY && ctx.stdout.isTTY);
 }
@@ -156,39 +171,95 @@ function buildInitSurfacePreview(harnesses) {
     }
     return lines;
 }
-async function promptInitConfig(defaults, ctx) {
+function harnessLabel(harness) {
+    const adapter = HARNESS_ADAPTERS[harness];
+    const tier = adapter ? `${adapter.reality.declaredSupport}, ${adapter.capabilities.hookSurface} hooks` : "supported";
+    return `${harness} (${tier})`;
+}
+function selectedHarnessPreview(harnesses) {
+    return harnesses.length > 0 ? harnesses.join(", ") : "none";
+}
+export function parseHarnessSelectionAnswer(raw) {
+    const answer = raw.trim().toLowerCase();
+    if (answer.length === 0)
+        return { kind: "accept" };
+    if (answer === "all")
+        return { kind: "all" };
+    if (answer === "none") {
+        return { kind: "invalid", message: "Zero harnesses is not supported. Select at least one harness." };
+    }
+    const parts = answer.split(",").map((part) => part.trim()).filter(Boolean);
+    const indexes = parts.map((part) => Number.parseInt(part, 10));
+    if (indexes.some((value) => !Number.isInteger(value) || value < 1 || value > HARNESS_IDS.length)) {
+        return { kind: "invalid", message: `Invalid selection. Use numbers 1-${HARNESS_IDS.length}, comma-separated.` };
+    }
+    return { kind: "toggle", indexes };
+}
+async function promptHarnessSelection(defaults, ctx, label = "Harness selection") {
     const rl = createInterface({
         input: process.stdin,
         output: ctx.stdout
     });
-    const pickHarnesses = async (fallback) => {
-        const fallbackText = fallback.join(",");
+    const defaultSet = new Set(defaults.harnesses);
+    const selected = new Set(defaults.harnesses.length > 0 ? defaults.harnesses : HARNESS_IDS);
+    const detected = new Set(defaults.detectedHarnesses ?? []);
+    const current = new Set(defaults.currentHarnesses ?? []);
+    const printMenu = () => {
+        ctx.stdout.write(`\n${label}\n`);
+        ctx.stdout.write(`Detected: ${selectedHarnessPreview(defaults.detectedHarnesses ?? [])}\n`);
+        ctx.stdout.write(`Current: ${selectedHarnessPreview(defaults.currentHarnesses ?? [])}\n`);
+        ctx.stdout.write(`Supported harnesses and target paths:\n`);
+        HARNESS_IDS.forEach((harness, index) => {
+            const adapter = HARNESS_ADAPTERS[harness];
+            const markers = [
+                detected.has(harness) ? "detected" : "",
+                current.has(harness) ? "current" : "",
+                defaultSet.has(harness) ? "default" : ""
+            ].filter(Boolean).join(", ");
+            const checked = selected.has(harness) ? "x" : " ";
+            ctx.stdout.write(`  ${index + 1}. [${checked}] ${harnessLabel(harness)} -> ${adapter.commandDir}${markers ? ` (${markers})` : ""}\n`);
+        });
+        ctx.stdout.write("Enter numbers to toggle (for example 1,3), 'all', or press Enter to accept.\n");
+    };
+    try {
         while (true) {
-            const answer = (await rl.question(`\nHarnesses (comma list from ${HARNESS_IDS.join(", ")}) [${fallbackText}]: `)).trim();
-            if (answer.length === 0) {
-                return fallback;
-            }
-            try {
-                const parsed = parseHarnesses(answer);
-                if (parsed.length === 0) {
+            printMenu();
+            const answer = await rl.question(`Selected [${[...selected].join(",") || "select at least one"}]: `);
+            const parsedAnswer = parseHarnessSelectionAnswer(answer);
+            if (parsedAnswer.kind === "accept") {
+                if (selected.size === 0) {
                     ctx.stdout.write("Select at least one harness.\n");
                     continue;
                 }
-                return parsed;
+                return HARNESS_IDS.filter((harness) => selected.has(harness));
+            }
+            if (parsedAnswer.kind === "all") {
+                HARNESS_IDS.forEach((harness) => selected.add(harness));
+                continue;
+            }
+            if (parsedAnswer.kind === "invalid") {
+                ctx.stdout.write(`${parsedAnswer.message}\n`);
+                continue;
             }
-            catch (err) {
-                ctx.stdout.write(`${err instanceof Error ? err.message : "Invalid harness list"}\n`);
+            for (const index of parsedAnswer.indexes) {
+                const harness = HARNESS_IDS[index - 1];
+                if (!harness)
+                    continue;
+                if (selected.has(harness))
+                    selected.delete(harness);
+                else
+                    selected.add(harness);
             }
         }
-    };
-    try {
-        const harnesses = await pickHarnesses(defaults.harnesses);
-        return { harnesses };
     }
     finally {
         rl.close();
     }
 }
+async function promptInitConfig(defaults, ctx) {
+    const harnesses = await promptHarnessSelection(defaults, ctx, "Initial cclaw harnesses");
+    return { harnesses };
+}
 /**
  * When Codex is one of the installed harnesses, check the Codex CLI
  * config file for the `codex_hooks` feature flag. If it is missing or
@@ -293,13 +364,41 @@ async function resolveInitInputs(parsed, ctx) {
     const defaults = {
         harnesses: autoHarnesses ?? HARNESS_IDS.slice()
     };
-    const prompted = await promptInitConfig(defaults, ctx);
+    const prompted = await promptInitConfig({ ...defaults, detectedHarnesses }, ctx);
     return {
         track: parsed.track,
         harnesses: prompted.harnesses,
         detectedHarnesses
     };
 }
+async function resolveSyncInputs(parsed, ctx) {
+    const explicitHarnesses = parsed.harnesses;
+    if (explicitHarnesses && explicitHarnesses.length > 0) {
+        return { harnesses: explicitHarnesses };
+    }
+    if (parsed.interactive !== true) {
+        return {};
+    }
+    if (!isInitPromptAllowed(ctx)) {
+        throw new Error("Interactive sync requires a TTY. Remove --interactive or run in a terminal.");
+    }
+    let currentHarnesses = [];
+    try {
+        currentHarnesses = (await readConfig(ctx.cwd)).harnesses;
+    }
+    catch {
+        currentHarnesses = [];
+    }
+    const detectedHarnesses = await detectHarnesses(ctx.cwd);
+    const defaults = detectedHarnesses.length > 0 ? detectedHarnesses : currentHarnesses.length > 0 ? currentHarnesses : HARNESS_IDS.slice();
+    return {
+        harnesses: await promptHarnessSelection({
+            harnesses: defaults,
+            detectedHarnesses,
+            currentHarnesses
+        }, ctx, "Sync harness reconfiguration")
+    };
+}
 function parseDoctorOnly(raw) {
     return raw
         .split(",")
@@ -335,24 +434,47 @@ function doctorCountsBySeverity(checks) {
     }
     return result;
 }
+const DOCTOR_ACTION_GROUP_LABELS = {
+    sync: "Can fix with cclaw sync",
+    "user-action": "Requires user action",
+    "stage-work": "Requires stage work",
+    informational: "Informational warning"
+};
+function doctorActionGroupOrder(group) {
+    return group === "sync" ? 0 : group === "user-action" ? 1 : group === "stage-work" ? 2 : 3;
+}
 function printDoctorText(ctx, checks, options) {
     const orderedSeverities = ["error", "warning", "info"];
     const view = options.quiet ? checks.filter((check) => !check.ok) : checks;
-    for (const severity of orderedSeverities) {
-        const inBucket = view.filter((check) => check.severity === severity);
-        if (inBucket.length === 0)
-            continue;
-        ctx.stdout.write(`\n[${severity.toUpperCase()}]\n`);
-        for (const check of inBucket) {
-            const status = check.ok ? "PASS" : "FAIL";
-            ctx.stdout.write(`${status} ${check.name} :: ${check.summary}\n`);
-            if (!options.quiet) {
-                ctx.stdout.write(`  details: ${check.details}\n`);
-            }
-            if (!check.ok || options.explain) {
-                ctx.stdout.write(`  fix: ${check.fix}\n`);
-                if (check.docRef) {
-                    ctx.stdout.write(`  docs: ${check.docRef}\n`);
+    const actionGroups = [...new Set(view.map((check) => check.actionGroup))]
+        .sort((left, right) => doctorActionGroupOrder(left) - doctorActionGroupOrder(right));
+    for (const actionGroup of actionGroups) {
+        const groupChecks = view.filter((check) => check.actionGroup === actionGroup);
+        const failingInGroup = groupChecks.filter((check) => !check.ok).length;
+        ctx.stdout.write(`
+[${DOCTOR_ACTION_GROUP_LABELS[actionGroup]}] ${failingInGroup}/${groupChecks.length} failing
+`);
+        for (const severity of orderedSeverities) {
+            const inBucket = groupChecks.filter((check) => check.severity === severity);
+            if (inBucket.length === 0)
+                continue;
+            ctx.stdout.write(`  ${severity.toUpperCase()}
+`);
+            for (const check of inBucket) {
+                const status = check.ok ? "PASS" : "FAIL";
+                ctx.stdout.write(`  ${status} ${check.name} :: ${check.summary}
+`);
+                if (!options.quiet) {
+                    ctx.stdout.write(`    details: ${check.details}
+`);
+                }
+                if (!check.ok || options.explain) {
+                    ctx.stdout.write(`    next action: ${check.fix}
+`);
+                    if (check.docRef) {
+                        ctx.stdout.write(`    reference: ${check.docRef}
+`);
+                    }
                 }
             }
         }
@@ -392,13 +514,13 @@ function parseArgs(argv) {
     }
     const flags = rest;
     const isAllowedForCommand = (flag) => {
-        if (parsed.command === "init") {
+        if (parsed.command === "init" || parsed.command === "sync") {
             return flag.startsWith("--harnesses=") ||
-                flag.startsWith("--track=") ||
-                flag.startsWith("--profile=") ||
+                (parsed.command === "init" && flag.startsWith("--track=")) ||
+                (parsed.command === "init" && flag.startsWith("--profile=")) ||
                 flag === "--interactive" ||
                 flag === "--no-interactive" ||
-                flag === "--dry-run";
+                (parsed.command === "init" && flag === "--dry-run");
         }
         if (parsed.command === "doctor") {
             return flag === "--reconcile-gates" ||
@@ -410,7 +532,9 @@ function parseArgs(argv) {
         if (parsed.command === "archive") {
             return flag.startsWith("--name=") ||
                 flag === "--skip-retro" ||
-                flag.startsWith("--retro-reason=");
+                flag.startsWith("--retro-reason=") ||
+                flag.startsWith("--disposition=") ||
+                flag.startsWith("--reason=");
         }
         return false;
     };
@@ -473,6 +597,14 @@ function parseArgs(argv) {
             parsed.archiveSkipRetroReason = flag.replace("--retro-reason=", "").trim();
             continue;
         }
+        if (flag.startsWith("--disposition=")) {
+            parsed.archiveDisposition = parseArchiveDisposition(flag.replace("--disposition=", ""));
+            continue;
+        }
+        if (flag.startsWith("--reason=")) {
+            parsed.archiveDispositionReason = flag.replace("--reason=", "").trim();
+            continue;
+        }
     }
     return parsed;
 }
@@ -532,8 +664,10 @@ async function runCommand(parsed, ctx) {
         return 0;
     }
     if (command === "sync") {
-        await syncCclaw(ctx.cwd);
-        info(ctx, "Synchronized harness shims from current .cclaw config");
+        const resolved = await resolveSyncInputs(parsed, ctx);
+        await syncCclaw(ctx.cwd, { harnesses: resolved.harnesses });
+        const harnessNote = resolved.harnesses ? ` (${resolved.harnesses.join(", ")})` : "";
+        info(ctx, `Synchronized harness shims from current .cclaw config${harnessNote}`);
         return 0;
     }
     if (command === "doctor") {
@@ -571,12 +705,14 @@ async function runCommand(parsed, ctx) {
     if (command === "archive") {
         const archived = await archiveRun(ctx.cwd, parsed.archiveName, {
             skipRetro: parsed.archiveSkipRetro === true,
-            skipRetroReason: parsed.archiveSkipRetroReason
+            skipRetroReason: parsed.archiveSkipRetroReason,
+            disposition: parsed.archiveDisposition,
+            dispositionReason: parsed.archiveDispositionReason
         });
         const snapshotSummary = archived.snapshottedStateFiles.length > 0
             ? ` Snapshotted ${archived.snapshottedStateFiles.length} state file(s) under ${archived.archivePath}/state and wrote archive-manifest.json.`
             : "";
-        info(ctx, `Archived active artifacts to ${archived.archivePath}. Flow state reset to brainstorm.${snapshotSummary}`);
+        info(ctx, `Archived active artifacts to ${archived.archivePath} (${archived.disposition}). Flow state reset to brainstorm.${snapshotSummary}`);
         const k = archived.knowledge;
         if (k.overThreshold) {
             info(ctx, `Knowledge curation recommended: ${k.knowledgePath} now has ${k.activeEntryCount} active entries (soft threshold ${k.softThreshold}). Ask your harness to curate cclaw knowledge and plan a soft-archive of stale/duplicate entries to ${RUNTIME_ROOT}/knowledge.archive.jsonl.`);
@@ -624,4 +760,4 @@ function isDirectExecution() {
 if (isDirectExecution()) {
     void main();
 }
-export { parseArgs, parseHarnesses, parseTrack };
+export { parseArgs, parseArchiveDisposition, parseHarnesses, parseTrack };

package/dist/codex-feature-flag.d.ts

@@ -11,7 +11,7 @@
  * ```
  *
  * in `$CODEX_HOME/config.toml` (default: `~/.codex/config.toml`).
- * cclaw's `init --codex` prompts the user to flip this flag for them;
+ * cclaw init/sync can prompt the user to flip this flag for them; `cclaw doctor --explain` reports the concrete repair when it is missing;
  * this module owns the detection / mutation code so the prompt logic in
  * `cli.ts` stays small and testable.
  *

package/dist/codex-feature-flag.js

@@ -11,7 +11,7 @@
  * ```
  *
  * in `$CODEX_HOME/config.toml` (default: `~/.codex/config.toml`).
- * cclaw's `init --codex` prompts the user to flip this flag for them;
+ * cclaw init/sync can prompt the user to flip this flag for them; `cclaw doctor --explain` reports the concrete repair when it is missing;
  * this module owns the detection / mutation code so the prompt logic in
  * `cli.ts` stays small and testable.
  *

package/dist/config.js

@@ -245,6 +245,9 @@ export async function readConfig(projectRoot, options = {}) {
         throw configValidationError(fullPath, `unknown harness id(s): ${formatted}`);
     }
     const validatedHarnesses = configuredHarnesses;
+    if (hasHarnessesField && validatedHarnesses.length === 0) {
+        throw configValidationError(fullPath, `"harnesses" must include at least one harness`);
+    }
     const harnesses = hasHarnessesField
         ? [...new Set(validatedHarnesses)]
         : DEFAULT_HARNESSES;

package/dist/content/cancel-command.d.ts

@@ -0,0 +1,2 @@
+export declare function cancelCommandContract(): string;
+export declare function cancelCommandSkillMarkdown(): string;

package/dist/content/cancel-command.js

@@ -0,0 +1,25 @@
+export function cancelCommandContract() {
+    return `# /cc-cancel command contract
+
+Use this command when the user wants to stop the active run without claiming completion.
+
+## Protocol
+
+1. Ask for a concise cancellation reason if the user has not already provided one.
+2. Run \`cclaw archive --disposition=cancelled --reason=<reason>\` from the project root. Use \`--disposition=abandoned\` only when the user explicitly frames the run as abandoned rather than cancelled.
+3. Report the archive path and reset run id. Make clear that the archived run is not a completed ship.
+
+Cancelled and abandoned archives are allowed from any stage, but they require a required reason so future readers know why the run ended.
+`;
+}
+export function cancelCommandSkillMarkdown() {
+    return `---
+name: flow-cancel
+description: Cancel or abandon the active cclaw run with a required reason. Use when the user types /cc-cancel or asks to cancel, abandon, stop, discard, or reset an unfinished run.
+---
+
+# Cancel cclaw Run
+
+Load and follow \`.cclaw/commands/cancel.md\`. This is a non-completion path: require a reason and archive with cancelled or abandoned disposition.
+`;
+}

package/dist/content/finish-command.d.ts

@@ -0,0 +1,2 @@
+export declare function finishCommandContract(): string;
+export declare function finishCommandSkillMarkdown(): string;

package/dist/content/finish-command.js

@@ -0,0 +1,26 @@
+export function finishCommandContract() {
+    return `# /cc-finish command contract
+
+Use this command when the user says the active run is complete and wants to close it out.
+
+## Protocol
+
+1. Read \`.cclaw/state/flow-state.json\` and \`.cclaw/commands/next.md\`.
+2. Confirm ship closeout is \`ready_to_archive\`. If not, route to \`/cc-next\` until retro and compound closeout are complete or explicitly skipped there.
+3. Run \`cclaw archive --disposition=completed\` from the project root.
+4. Report the archive path, reset run id, and any knowledge curation hint printed by the CLI.
+
+Completed archives keep strict closeout gates: do not bypass retro or compound review from this command.
+`;
+}
+export function finishCommandSkillMarkdown() {
+    return `---
+name: flow-finish
+description: Finish a completed cclaw run by archiving with completed disposition. Use when the user types /cc-finish or asks to finish, close, complete, or archive a successful run.
+---
+
+# Finish cclaw Run
+
+Load and follow \`.cclaw/commands/finish.md\`. This is the successful closeout path and must preserve the normal ship closeout gates before archive.
+`;
+}

package/dist/content/harness-doc.js

@@ -35,7 +35,7 @@ function perHarnessRecipeMarkdown() {
     const examples = recipes
         .map((recipe) => `**${recipe.harnessId}**:\n\n` + recipe.lifecycleCommands.map((cmd) => `    ${cmd}`).join("\n"))
         .join("\n\n");
-    return `\n\n## Per-Harness Lifecycle Recipe\n\n| Harness | Surface | Agent definition path | fulfillmentMode | Lifecycle |\n|---|---|---|---|---|\n${rows}\n\nNeutral placeholder tokens only: \`<agent-name>\`, \`<stage>\`, \`<run-id>\`, \`<span-id>\`, \`<dispatch-id>\`, \`<agent-def-path>\`, \`<iso-ts>\`, \`<artifact-anchor>\`. See \`docs/quality-gates.md\` for stage-by-stage gate mapping.\n\nThe four shipped harnesses (\`claude\`, \`cursor\`, \`opencode\`, \`codex\`) each ship with a canonical primary surface in the table above. The remaining enum values \`generic-task\`, \`role-switch\`, and \`manual\` are documented in the dispatch-surface table below and are available to any harness as fallback paths when the primary surface is unavailable.\n\n${examples}\n\n${dispatchSurfaceTableMarkdown()}\n\n### Legacy ledger upgrade\n\nPre-v3 ledger entries that lack a recorded \`dispatchSurface\` are tagged \`fulfillmentMode: "legacy-inferred"\` on read. Stage-complete blocks completion until those rows are re-recorded with the v3 helper:\n\n    node .cclaw/hooks/delegation-record.mjs \\\n      --rerecord \\\n      --span-id=<span-id> \\\n      --dispatch-id=<dispatch-id> \\\n      --dispatch-surface=<surface> \\\n      --agent-definition-path=<agent-def-path> \\\n      --ack-ts=<iso-ts> \\\n      --completed-ts=<iso-ts> \\\n      --json\n\n\`--dispatch-surface\` must be one of the values listed in the dispatch-surface table above (the enum is generated verbatim from \`src/delegation.ts::DELEGATION_DISPATCH_SURFACES\`). Surfaces must align with the allowed agent-definition-path prefixes shown alongside each surface; \`role-switch\` and \`manual\` accept any path. The deprecated \`task\` surface is rejected.\n\n`;
+    return `\n\n## Per-Harness Lifecycle Recipe\n\n| Harness | Surface | Agent definition path | fulfillmentMode | Lifecycle |\n|---|---|---|---|---|\n${rows}\n\nNeutral placeholder tokens only: \`<agent-name>\`, \`<stage>\`, \`<run-id>\`, \`<span-id>\`, \`<dispatch-id>\`, \`<agent-def-path>\`, \`<iso-ts>\`, \`<artifact-anchor>\`. See \`docs/quality-gates.md\` for stage-by-stage gate mapping.\n\nThe four shipped harnesses (\`claude\`, \`cursor\`, \`opencode\`, \`codex\`) each ship with a canonical primary surface in the table above. Repair hints: \`cclaw sync\` safely regenerates shims/plugins/agents; Codex also needs \`[features] codex_hooks = true\`; OpenCode needs \`opencode.json(.c)\` plugin registration; role-switch completions require evidenceRefs. The remaining enum values \`generic-task\`, \`role-switch\`, and \`manual\` are documented in the dispatch-surface table below and are available to any harness as fallback paths when the primary surface is unavailable.\n\n${examples}\n\n${dispatchSurfaceTableMarkdown()}\n\n### Legacy ledger upgrade\n\nPre-v3 ledger entries that lack a recorded \`dispatchSurface\` are tagged \`fulfillmentMode: "legacy-inferred"\` on read. Stage-complete blocks completion until those rows are re-recorded with the v3 helper:\n\n    node .cclaw/hooks/delegation-record.mjs \\\n      --rerecord \\\n      --span-id=<span-id> \\\n      --dispatch-id=<dispatch-id> \\\n      --dispatch-surface=<surface> \\\n      --agent-definition-path=<agent-def-path> \\\n      --ack-ts=<iso-ts> \\\n      --completed-ts=<iso-ts> \\\n      --json\n\n\`--dispatch-surface\` must be one of the values listed in the dispatch-surface table above (the enum is generated verbatim from \`src/delegation.ts::DELEGATION_DISPATCH_SURFACES\`). Surfaces must align with the allowed agent-definition-path prefixes shown alongside each surface; \`role-switch\` and \`manual\` accept any path. The deprecated \`task\` surface is rejected.\n\n`;
 }
 export function harnessIntegrationDocMarkdown() {
     const head = "# Harness Integration Matrix\n\nGenerated from `src/harness-adapters.ts` capabilities and hook event mappings.";

package/dist/content/hooks.js

@@ -3,7 +3,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { RUNTIME_ROOT } from "../constants.js";
 import { DELEGATION_DISPATCH_SURFACES, DELEGATION_DISPATCH_SURFACE_PATH_PREFIXES } from "../delegation.js";
-function resolveCliEntrypointForGeneratedHook() {
+function resolveCliRuntimeForGeneratedHook() {
     const here = fileURLToPath(import.meta.url);
     const candidates = [
         path.resolve(path.dirname(here), "..", "cli.js"),
@@ -13,12 +13,21 @@ function resolveCliEntrypointForGeneratedHook() {
         // Synchronous probe runs only during cclaw-cli init/sync generation.
         // The generated hook receives a concrete path and does not need a global bin.
         if (existsSync(candidate))
-            return candidate;
+            return { entrypoint: candidate, argsPrefix: [] };
     }
-    return null;
+    // Vitest exercises init/sync directly from src/ without a compiled dist/.
+    // Route that dev-only shape through vite-node so hooks still prove a local runtime.
+    if (process.env.VITEST === "true") {
+        const sourceCli = path.resolve(path.dirname(here), "..", "cli.ts");
+        const viteNode = path.resolve(path.dirname(here), "..", "..", "node_modules", "vite-node", "vite-node.mjs");
+        if (existsSync(sourceCli) && existsSync(viteNode)) {
+            return { entrypoint: viteNode, argsPrefix: ["--script", sourceCli] };
+        }
+    }
+    return { entrypoint: null, argsPrefix: [] };
 }
 function internalHelperScript(helperName, internalSubcommand, usage) {
-    const cliEntrypoint = resolveCliEntrypointForGeneratedHook();
+    const cliRuntime = resolveCliRuntimeForGeneratedHook();
     return `#!/usr/bin/env node
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -26,7 +35,8 @@ import process from "node:process";
 import { spawn } from "node:child_process";
 
 const RUNTIME_ROOT = ${JSON.stringify(RUNTIME_ROOT)};
-const CCLAW_CLI_ENTRYPOINT = ${JSON.stringify(cliEntrypoint)};
+const CCLAW_CLI_ENTRYPOINT = ${JSON.stringify(cliRuntime.entrypoint)};
+const CCLAW_CLI_ARGS_PREFIX = ${JSON.stringify(cliRuntime.argsPrefix)};
 const HELPER_NAME = ${JSON.stringify(helperName)};
 const INTERNAL_SUBCOMMAND = ${JSON.stringify(internalSubcommand)};
 const USAGE = ${JSON.stringify(usage)};
@@ -77,6 +87,7 @@ async function main() {
   }
 
   const cliEntrypoint = process.env.CCLAW_CLI_JS || CCLAW_CLI_ENTRYPOINT;
+  const cliArgsPrefix = process.env.CCLAW_CLI_JS ? [] : CCLAW_CLI_ARGS_PREFIX;
   if (!cliEntrypoint || cliEntrypoint.trim().length === 0) {
     process.stderr.write(
       "[cclaw] " + HELPER_NAME + ": local Node runtime entrypoint is missing. Re-run npx cclaw-cli sync, or set CCLAW_CLI_JS=/absolute/path/to/dist/cli.js for this session.\\n"
@@ -88,6 +99,11 @@ async function main() {
   try {
     const stat = await fs.stat(cliEntrypoint);
     if (!stat.isFile()) throw new Error("not-file");
+    for (const argPath of cliArgsPrefix) {
+      if (typeof argPath !== "string" || argPath.startsWith("-")) continue;
+      const argStat = await fs.stat(argPath);
+      if (!argStat.isFile()) throw new Error("arg-not-file");
+    }
   } catch {
     process.stderr.write(
       "[cclaw] " + HELPER_NAME + ": local Node runtime entrypoint not found at " + cliEntrypoint + ". Re-run npx cclaw-cli sync, or set CCLAW_CLI_JS=/absolute/path/to/dist/cli.js for this session.\\n"
@@ -96,7 +112,7 @@ async function main() {
     return;
   }
 
-  const child = spawn(process.execPath, [cliEntrypoint, "internal", INTERNAL_SUBCOMMAND, ...flags], {
+  const child = spawn(process.execPath, [cliEntrypoint, ...cliArgsPrefix, "internal", INTERNAL_SUBCOMMAND, ...flags], {
     cwd: root,
     env: process.env,
     stdio: "inherit"
@@ -140,7 +156,7 @@ export function startFlowScript() {
     return internalHelperScript("start-flow", "start-flow", "Usage: node " + RUNTIME_ROOT + "/hooks/start-flow.mjs --track=<standard|medium|quick> [--class=...] [--prompt=...] [--stack=...] [--reason=...] [--reclassify] [--force-reset]");
 }
 export function stageCompleteScript() {
-    const cliEntrypoint = resolveCliEntrypointForGeneratedHook();
+    const cliRuntime = resolveCliRuntimeForGeneratedHook();
     return `#!/usr/bin/env node
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -148,7 +164,8 @@ import process from "node:process";
 import { spawn } from "node:child_process";
 
 const RUNTIME_ROOT = ${JSON.stringify(RUNTIME_ROOT)};
-const CCLAW_CLI_ENTRYPOINT = ${JSON.stringify(cliEntrypoint)};
+const CCLAW_CLI_ENTRYPOINT = ${JSON.stringify(cliRuntime.entrypoint)};
+const CCLAW_CLI_ARGS_PREFIX = ${JSON.stringify(cliRuntime.argsPrefix)};
 
 async function detectRoot() {
   const candidates = [
@@ -201,6 +218,7 @@ async function main() {
   }
 
   const cliEntrypoint = process.env.CCLAW_CLI_JS || CCLAW_CLI_ENTRYPOINT;
+  const cliArgsPrefix = process.env.CCLAW_CLI_JS ? [] : CCLAW_CLI_ARGS_PREFIX;
   if (!cliEntrypoint || cliEntrypoint.trim().length === 0) {
     process.stderr.write(
       "[cclaw] stage-complete: local Node runtime entrypoint is missing. Re-run npx cclaw-cli sync, or set CCLAW_CLI_JS=/absolute/path/to/dist/cli.js for this session.\\n"
@@ -212,6 +230,11 @@ async function main() {
   try {
     const stat = await fs.stat(cliEntrypoint);
     if (!stat.isFile()) throw new Error("not-file");
+    for (const argPath of cliArgsPrefix) {
+      if (typeof argPath !== "string" || argPath.startsWith("-")) continue;
+      const argStat = await fs.stat(argPath);
+      if (!argStat.isFile()) throw new Error("arg-not-file");
+    }
   } catch {
     process.stderr.write(
       "[cclaw] stage-complete: local Node runtime entrypoint not found at " + cliEntrypoint + ". Re-run npx cclaw-cli sync, or set CCLAW_CLI_JS=/absolute/path/to/dist/cli.js for this session.\\n"
@@ -222,7 +245,7 @@ async function main() {
 
   const child = spawn(
     process.execPath,
-    [cliEntrypoint, "internal", "advance-stage", stage, ...flags],
+    [cliEntrypoint, ...cliArgsPrefix, "internal", "advance-stage", stage, ...flags],
     {
     cwd: root,
     env: process.env,