cclaw-cli 0.51.28 → 0.51.29

package/dist/doctor.js

@@ -3,10 +3,11 @@ import path from "node:path";
 import { execFile } from "node:child_process";
 import { pathToFileURL } from "node:url";
 import { promisify } from "node:util";
-import { REQUIRED_DIRS, RUNTIME_ROOT } from "./constants.js";
+import { CCLAW_VERSION, REQUIRED_DIRS, RUNTIME_ROOT } from "./constants.js";
 import { CCLAW_AGENTS } from "./content/core-agents.js";
 import { detectAdvancedKeys, InvalidConfigError, readConfig } from "./config.js";
 import { exists } from "./fs-utils.js";
+import { hashManagedResourceContent, isManagedGeneratedPath, MANAGED_RESOURCE_MANIFEST_REL_PATH, readManagedResourceManifest, validateManagedResourceManifest } from "./managed-resources.js";
 import { gitignoreHasRequiredPatterns } from "./gitignore.js";
 import { HARNESS_ADAPTERS, CCLAW_MARKER_START, CCLAW_MARKER_END, harnessShimFileNames, harnessShimSkillNames } from "./harness-adapters.js";
 import { policyChecks } from "./policy.js";
@@ -21,6 +22,7 @@ import { stageSkillFolder } from "./content/skills.js";
 import { stageCommandShimMarkdown } from "./content/stage-command.js";
 import { doctorCheckMetadata } from "./doctor-registry.js";
 import { resolveTrackFromPrompt } from "./track-heuristics.js";
+import { detectHarnesses } from "./init-detect.js";
 import { classifyCodexHooksFlag, codexConfigPath, readCodexConfig } from "./codex-feature-flag.js";
 import { LANGUAGE_RULE_PACK_DIR, LANGUAGE_RULE_PACK_FILES, LEGACY_LANGUAGE_RULE_PACK_FOLDERS } from "./content/utility-skills.js";
 import { validateHookDocument } from "./hook-schema.js";
@@ -92,8 +94,48 @@ function extractGeneratedCliEntrypoints(scriptContent) {
             // malformed generated constant; treat below as missing/unusable
         }
     }
+    for (const match of scriptContent.matchAll(/const\s+CCLAW_CLI_ARGS_PREFIX\s*=\s*(\[(?:\\.|[^\]])*\]);/gu)) {
+        try {
+            const parsed = JSON.parse(match[1] ?? "[]");
+            if (Array.isArray(parsed)) {
+                for (const item of parsed) {
+                    if (typeof item === "string" && item.trim().length > 0 && !item.startsWith("-")) {
+                        paths.push(item);
+                    }
+                }
+            }
+        }
+        catch {
+            // malformed generated constant; treat below as missing/unusable
+        }
+    }
     return paths;
 }
+async function walkGeneratedCandidates(projectRoot, relDir, candidates) {
+    const fullDir = path.join(projectRoot, relDir);
+    if (!(await exists(fullDir)))
+        return;
+    let entries = [];
+    try {
+        entries = await fs.readdir(fullDir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const rel = path.join(relDir, entry.name).replace(/\\/gu, "/");
+        if (entry.isDirectory()) {
+            await walkGeneratedCandidates(projectRoot, rel, candidates);
+        }
+        else if (entry.isFile() && isManagedGeneratedPath(rel)) {
+            candidates.push(rel);
+        }
+    }
+}
+function formatManagedValidationIssue(issue) {
+    const subject = issue.path ?? (issue.index !== undefined ? `resources[${issue.index}]` : "manifest");
+    return `${subject} ${issue.field}: ${issue.message}`;
+}
 async function generatedCliEntrypointsOk(projectRoot) {
     const hookScripts = ["stage-complete.mjs", "start-flow.mjs", "run-hook.mjs"];
     const problems = [];
@@ -690,8 +732,140 @@ export async function doctorChecks(projectRoot, options = {}) {
         ok: await gitignoreHasRequiredPatterns(projectRoot),
         details: ".gitignore must include cclaw ignore block"
     });
+    const managedManifestPath = path.join(projectRoot, MANAGED_RESOURCE_MANIFEST_REL_PATH);
+    let rawManagedManifest = null;
+    let managedManifestParseError = null;
+    if (await exists(managedManifestPath)) {
+        try {
+            rawManagedManifest = JSON.parse(await fs.readFile(managedManifestPath, "utf8"));
+        }
+        catch (error) {
+            managedManifestParseError = error instanceof Error ? error.message : String(error);
+        }
+    }
+    const managedManifestValidationIssues = rawManagedManifest === null
+        ? []
+        : validateManagedResourceManifest(rawManagedManifest);
+    const managedManifest = await readManagedResourceManifest(projectRoot).catch(() => null);
+    checks.push({
+        name: "managed_resources:manifest_exists",
+        ok: managedManifest !== null,
+        details: managedManifest
+            ? `${MANAGED_RESOURCE_MANIFEST_REL_PATH} tracks ${managedManifest.resources.length} managed generated file(s)`
+            : `${MANAGED_RESOURCE_MANIFEST_REL_PATH} missing; run cclaw sync to establish generated file ownership`
+    });
+    checks.push({
+        name: "managed_resources:manifest_valid",
+        ok: managedManifestParseError === null && managedManifestValidationIssues.length === 0,
+        details: managedManifestParseError
+            ? `${MANAGED_RESOURCE_MANIFEST_REL_PATH} is unreadable JSON (${managedManifestParseError})`
+            : managedManifestValidationIssues.length === 0
+                ? `${MANAGED_RESOURCE_MANIFEST_REL_PATH} metadata is structurally valid`
+                : `malformed managed resource metadata: ${managedManifestValidationIssues.slice(0, 12).map(formatManagedValidationIssue).join("; ")}`
+    });
+    if (managedManifest) {
+        checks.push({
+            name: "managed_resources:manifest_package_version",
+            ok: managedManifest.packageVersion === CCLAW_VERSION,
+            details: managedManifest.packageVersion === CCLAW_VERSION
+                ? `${MANAGED_RESOURCE_MANIFEST_REL_PATH} packageVersion matches cclaw ${CCLAW_VERSION}`
+                : `${MANAGED_RESOURCE_MANIFEST_REL_PATH} packageVersion ${managedManifest.packageVersion} is stale; current cclaw is ${CCLAW_VERSION}. Run cclaw upgrade.`
+        });
+        const rawResources = toObject(rawManagedManifest)?.resources;
+        const stalePackageEntries = Array.isArray(rawResources)
+            ? rawResources.flatMap((entry, index) => {
+                const obj = toObject(entry);
+                if (!obj)
+                    return [];
+                const entryPath = typeof obj.path === "string" ? obj.path : `resources[${index}]`;
+                return typeof obj.packageVersion === "string" && obj.packageVersion !== CCLAW_VERSION
+                    ? [`${entryPath} (${obj.packageVersion})`]
+                    : [];
+            })
+            : [];
+        const stale = [];
+        const missing = [];
+        for (const entry of managedManifest.resources) {
+            const filePath = path.join(projectRoot, entry.path);
+            if (!(await exists(filePath))) {
+                missing.push(entry.path);
+                continue;
+            }
+            const currentHash = hashManagedResourceContent(await fs.readFile(filePath));
+            if (currentHash !== entry.sha256) {
+                stale.push(entry.path);
+            }
+        }
+        checks.push({
+            name: "managed_resources:entry_package_versions",
+            ok: stalePackageEntries.length === 0,
+            details: stalePackageEntries.length === 0
+                ? `all manifest entries match cclaw ${CCLAW_VERSION}`
+                : `manifest entries have stale packageVersion; run cclaw upgrade: ${stalePackageEntries.slice(0, 12).join(", ")}`
+        });
+        checks.push({
+            name: "managed_resources:user_modified",
+            ok: stale.length === 0,
+            details: stale.length === 0
+                ? "all manifest-tracked managed files match recorded hashes"
+                : `manifest-tracked managed files have user modifications: ${stale.slice(0, 12).join(", ")}`
+        });
+        checks.push({
+            name: "managed_resources:stale_entries",
+            ok: missing.length === 0,
+            details: missing.length === 0
+                ? "all manifest entries still exist"
+                : `manifest entries point to missing files: ${missing.slice(0, 12).join(", ")}`
+        });
+        const manifestPaths = new Set(managedManifest.resources.map((entry) => entry.path));
+        const candidates = [];
+        for (const relDir of [
+            `${RUNTIME_ROOT}/commands`,
+            `${RUNTIME_ROOT}/skills`,
+            `${RUNTIME_ROOT}/templates`,
+            `${RUNTIME_ROOT}/rules`,
+            `${RUNTIME_ROOT}/agents`,
+            `${RUNTIME_ROOT}/hooks`,
+            ".claude/commands",
+            ".cursor/commands",
+            ".opencode/commands",
+            ".opencode/agents",
+            ".codex/agents",
+            ".agents/skills",
+            ".claude/hooks",
+            ".cursor",
+            ".codex",
+            ".opencode/plugins"
+        ]) {
+            await walkGeneratedCandidates(projectRoot, relDir, candidates);
+        }
+        for (const rel of ["AGENTS.md", "CLAUDE.md"]) {
+            if ((await exists(path.join(projectRoot, rel))) && isManagedGeneratedPath(rel)) {
+                candidates.push(rel);
+            }
+        }
+        const orphaned = [...new Set(candidates)].filter((rel) => !manifestPaths.has(rel)).sort();
+        checks.push({
+            name: "managed_resources:orphaned_generated_files",
+            ok: orphaned.length === 0,
+            details: orphaned.length === 0
+                ? "no orphaned generated files detected across known cclaw surfaces"
+                : `warning: generated-looking files are not tracked in manifest: ${orphaned.slice(0, 12).join(", ")}`
+        });
+    }
     let configuredHarnesses = [];
     let parsedConfig = null;
+    const configFileExists = await exists(path.join(projectRoot, RUNTIME_ROOT, "config.yaml"));
+    if (!configFileExists) {
+        const detectedHarnesses = await detectHarnesses(projectRoot).catch(() => []);
+        checks.push({
+            name: "config:present",
+            ok: detectedHarnesses.length === 0,
+            details: detectedHarnesses.length > 0
+                ? `${RUNTIME_ROOT}/config.yaml is missing but harness markers were detected (${detectedHarnesses.join(", ")}). Run cclaw sync --harnesses=${detectedHarnesses.join(",")} or cclaw sync --interactive.`
+                : `${RUNTIME_ROOT}/config.yaml missing and no harness markers were detected; run cclaw init or cclaw sync when ready.`
+        });
+    }
     try {
         const config = await readConfig(projectRoot);
         parsedConfig = config;
@@ -811,6 +985,8 @@ export async function doctorChecks(projectRoot, options = {}) {
         const hasCcNext = content.includes("/cc-next");
         const hasCcIdeate = content.includes("/cc-ideate");
         const hasCcView = content.includes("/cc-view");
+        const hasCcFinish = content.includes("/cc-finish");
+        const hasCcCancel = content.includes("/cc-cancel");
         const hasVerification = content.includes("Verification Discipline");
         const hasMinimalMarker = content.includes("intentionally minimal for cross-project use");
         const hasMetaSkillPointer = content.includes(".cclaw/skills/using-cclaw/SKILL.md");
@@ -819,6 +995,8 @@ export async function doctorChecks(projectRoot, options = {}) {
             && hasCcNext
             && hasCcIdeate
             && hasCcView
+            && hasCcFinish
+            && hasCcCancel
             && hasVerification
             && hasMinimalMarker
             && hasMetaSkillPointer;
@@ -828,7 +1006,7 @@ export async function doctorChecks(projectRoot, options = {}) {
         ok: agentsBlockOk,
         details: `${agentsFile} must contain the managed cclaw marker block with routing, verification, and minimal detail pointer`
     });
-    for (const cmd of ["start", "next", "ideate", "view"]) {
+    for (const cmd of ["start", "next", "ideate", "view", "finish", "cancel"]) {
         const cmdPath = path.join(projectRoot, RUNTIME_ROOT, "commands", `${cmd}.md`);
         checks.push({
             name: `utility_command:${cmd}`,
@@ -854,6 +1032,8 @@ export async function doctorChecks(projectRoot, options = {}) {
         ["learnings", "learnings"],
         ["flow-ideate", "flow-ideate"],
         ["flow-view", "flow-view"],
+        ["flow-finish", "flow-finish"],
+        ["flow-cancel", "flow-cancel"],
         ["subagent-dev", "sdd"],
         ["parallel-dispatch", "parallel-agents"],
         ["session", "session"],
@@ -2016,6 +2196,7 @@ export async function doctorChecks(projectRoot, options = {}) {
             severity: check.severity ?? metadata.severity,
             summary: check.summary ?? metadata.summary,
             fix: check.fix ?? metadata.fix,
+            actionGroup: check.actionGroup ?? metadata.actionGroup,
             docRef: check.docRef ?? metadata.docRef
         };
     });

package/dist/fs-utils.js

@@ -1,5 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { getActiveManagedResourceSession } from "./managed-resources.js";
 export async function ensureDir(dirPath) {
     await fs.mkdir(dirPath, { recursive: true });
 }
@@ -83,6 +84,11 @@ export async function withDirectoryLock(lockPath, fn, options = {}) {
     }
 }
 export async function writeFileSafe(filePath, content, options = {}) {
+    const managedSession = getActiveManagedResourceSession();
+    if (managedSession?.shouldManage(filePath)) {
+        await managedSession.writeFileSafe(filePath, content, options);
+        return;
+    }
     await ensureDir(path.dirname(filePath));
     const tempPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
     const targetMode = options.mode;

package/dist/harness-adapters.js

@@ -35,6 +35,20 @@ const UTILITY_SHIMS = [
         command: "view",
         skillFolder: "flow-view",
         commandFile: "view.md"
+    },
+    {
+        fileName: "cc-finish.md",
+        skillName: "cc-finish",
+        command: "finish",
+        skillFolder: "flow-finish",
+        commandFile: "finish.md"
+    },
+    {
+        fileName: "cc-cancel.md",
+        skillName: "cc-cancel",
+        command: "cancel",
+        skillFolder: "flow-cancel",
+        commandFile: "cancel.md"
     }
 ];
 /** Skill-kind shim name for the root `/cc` entry point. */
@@ -179,9 +193,9 @@ export function harnessDispatchSurface(harnessId) {
         case "cursor":
             return "Use Cursor Subagent/Task with a generic subagent_type (explore for read-only mapping, generalPurpose for broader work, shell/browser-use when specifically needed) and paste the cclaw role prompt; record fulfillmentMode: \"generic-dispatch\" with evidenceRefs.";
         case "opencode":
-            return "Use OpenCode subagents: invoke the generated .opencode/agents/<agent>.md agent via Task or @<agent>; record scheduled/launched/acknowledged/completed events with spanId+dispatchId before claiming fulfillmentMode: \"isolated\".";
+            return "Use OpenCode subagents: invoke the generated .opencode/agents/<agent>.md agent via Task or @<agent>; if agents or plugin registration are missing, run `cclaw sync` and check opencode.json(.c) plugin registration with `cclaw doctor --explain`; record scheduled/launched/acknowledged/completed events with spanId+dispatchId before claiming fulfillmentMode: \"isolated\".";
         case "codex":
-            return "Use Codex native subagents: ask Codex to spawn the generated .codex/agents/<agent>.toml agent(s) by name; record scheduled/launched/acknowledged/completed events with spanId+dispatchId before claiming fulfillmentMode: \"isolated\".";
+            return "Use Codex native subagents: ask Codex to spawn the generated .codex/agents/<agent>.toml agent(s) by name; if hooks are inert, set `[features] codex_hooks = true` in ~/.codex/config.toml or rerun init/sync repair, then `cclaw doctor --explain`; record scheduled/launched/acknowledged/completed events with spanId+dispatchId before claiming fulfillmentMode: \"isolated\".";
     }
 }
 /**
@@ -362,13 +376,15 @@ When in doubt, prefer **non-trivial** — the quick track is opt-in and only saf
 | \`/cc-next\` | **Progression.** Advances to the next stage when current is complete. |
 | \`/cc-ideate\` | **Ideate mode.** Generates a ranked repo-improvement backlog before implementation. |
 | \`/cc-view\` | **Read-only router.** Unified entry for status/tree/diff views. |
+| \`/cc-finish\` | **Successful closeout.** Archives a completed run after strict ship closeout gates. |
+| \`/cc-cancel\` | **Non-completion closeout.** Archives a cancelled/abandoned run with a required reason. |
 
 Knowledge capture and curation run automatically as part of stage completion
 protocols via the internal \`learnings\` skill — no user-facing command.
 Reusable entries land in \`.cclaw/knowledge.jsonl\` as strict JSONL with
 \`type\`, \`trigger\`, \`action\`, and \`origin_run\` metadata.
 
-**Stage order:** brainstorm > scope > design > spec > plan > tdd > review > ship, then closeout: retro > compound > archive.
+**Stage order:** brainstorm > scope > design > spec > plan > tdd > review > ship, then closeout: retro > compound > archive. Use \`/cc-finish\` for completed runs and \`/cc-cancel\` for cancelled/abandoned runs.
 \`/cc-next\` loads the right stage skill automatically and also drives post-ship closeout. Gates must pass before handoff.
 
 ### Verification Discipline
@@ -391,8 +407,8 @@ If the same approach fails three times in a row (same command, same finding, sam
 
 OpenAI Codex CLI has **no native \`/cc\` slash command** (custom prompts
 were deprecated in v0.89, Jan 2026). The \`/cc\`, \`/cc-next\`,
-\`/cc-ideate\`, \`/cc-view\` tokens above describe intent — in
-Codex they map onto skills cclaw installs at
+\`/cc-ideate\`, \`/cc-view\`, \`/cc-finish\`, and \`/cc-cancel\`
+tokens above describe intent — in Codex they map onto skills cclaw installs at
 \`.agents/skills/cc*/SKILL.md\`. Activate one of two ways:
 
 - Type \`/use cc\` (or \`cc-next\`, etc.) at Codex's prompt.
@@ -474,6 +490,10 @@ function utilityShimBehavior(command) {
             return "This is an ideation command, not a flow stage. It may write ideation artifacts/seeds but does not advance flow state.";
         case "view":
             return "This is a read-only view command, not a flow stage. It never mutates flow state.";
+        case "finish":
+            return "This is a successful closeout utility, not a flow stage. It archives a completed run after ship closeout gates pass and records completed disposition semantics.";
+        case "cancel":
+            return "This is a non-completion closeout utility, not a flow stage. It requires a reason and archives cancelled or abandoned work without presenting it as completed.";
         default:
             return "This is a utility command, not a flow stage.";
     }
@@ -555,6 +575,10 @@ function codexSkillDescription(command) {
             return `Read-only repo-improvement ideate mode for cclaw. Use when the user types \`/cc-ideate\` or asks to "ideate", "scan the repo for TODOs/tech debt", "generate a backlog", or wants a ranked list of candidate ideas before committing to a single flow. Does not mutate \`.cclaw/state/flow-state.json\`.`;
         case "view":
             return `Read-only router for cclaw flow views. Use when the user types \`/cc-view\`, \`/cc-view status\`, \`/cc-view tree\`, \`/cc-view diff\`, or asks to "show cclaw status", "show the flow tree", "diff flow state", or wants a snapshot without mutation.`;
+        case "finish":
+            return `Finish a completed cclaw run. Use when the user types \`/cc-finish\` or asks to finish, complete, close out, or archive a successful run. Runs cclaw archive with completed disposition after strict ship closeout gates.`;
+        case "cancel":
+            return `Cancel or abandon the active cclaw run. Use when the user types \`/cc-cancel\` or asks to cancel, abandon, stop, discard, or reset an unfinished run. Requires a reason and archives with cancelled/abandoned disposition.`;
         default:
             return `Generated cclaw skill for ${command}.`;
     }

package/dist/install.d.ts

@@ -4,8 +4,11 @@ export interface InitOptions {
     harnesses?: HarnessId[];
     track?: FlowTrack;
 }
+export interface SyncOptions {
+    harnesses?: HarnessId[];
+}
 export declare function initCclaw(options: InitOptions): Promise<void>;
-export declare function syncCclaw(projectRoot: string): Promise<void>;
+export declare function syncCclaw(projectRoot: string, options?: SyncOptions): Promise<void>;
 /**
  * Refresh generated files in `.cclaw/` without touching user-authored
  * artifacts, state, or custom config keys. Only the `version` + `flowVersion`

package/dist/install.js

@@ -10,6 +10,8 @@ import { stageCommandShimMarkdown } from "./content/stage-command.js";
 import { ideateCommandContract, ideateCommandSkillMarkdown } from "./content/ideate-command.js";
 import { startCommandContract, startCommandSkillMarkdown } from "./content/start-command.js";
 import { viewCommandContract, viewCommandSkillMarkdown } from "./content/view-command.js";
+import { finishCommandContract, finishCommandSkillMarkdown } from "./content/finish-command.js";
+import { cancelCommandContract, cancelCommandSkillMarkdown } from "./content/cancel-command.js";
 import { subagentDrivenDevSkill, parallelAgentsSkill } from "./content/subagents.js";
 import { sessionHooksSkillMarkdown } from "./content/session-hooks.js";
 import { ironLawRuntimeDocument, ironLawsSkillMarkdown } from "./content/iron-laws.js";
@@ -26,6 +28,7 @@ import { SUBAGENT_CONTEXT_SKILLS } from "./content/subagent-context-skills.js";
 import { CCLAW_AGENTS } from "./content/core-agents.js";
 import { createInitialFlowState } from "./flow-state.js";
 import { ensureDir, exists, writeFileSafe } from "./fs-utils.js";
+import { ManagedResourceSession, setActiveManagedResourceSession } from "./managed-resources.js";
 import { ensureGitignore, removeGitignorePatterns } from "./gitignore.js";
 import { HARNESS_ADAPTERS, harnessShimFileNames, syncHarnessShims, removeCclawFromAgentsMd } from "./harness-adapters.js";
 import { validateHookDocument } from "./hook-schema.js";
@@ -451,6 +454,8 @@ async function writeSkills(projectRoot, config) {
     await writeFileSafe(runtimePath(projectRoot, "skills", "flow-ideate", "SKILL.md"), ideateCommandSkillMarkdown());
     await writeFileSafe(runtimePath(projectRoot, "skills", "flow-start", "SKILL.md"), startCommandSkillMarkdown());
     await writeFileSafe(runtimePath(projectRoot, "skills", "flow-view", "SKILL.md"), viewCommandSkillMarkdown());
+    await writeFileSafe(runtimePath(projectRoot, "skills", "flow-finish", "SKILL.md"), finishCommandSkillMarkdown());
+    await writeFileSafe(runtimePath(projectRoot, "skills", "flow-cancel", "SKILL.md"), cancelCommandSkillMarkdown());
     await writeFileSafe(runtimePath(projectRoot, "skills", "subagent-dev", "SKILL.md"), subagentDrivenDevSkill());
     await writeFileSafe(runtimePath(projectRoot, "skills", "parallel-dispatch", "SKILL.md"), parallelAgentsSkill());
     await writeFileSafe(runtimePath(projectRoot, "skills", "session", "SKILL.md"), sessionHooksSkillMarkdown());
@@ -514,6 +519,8 @@ async function writeEntryCommands(projectRoot) {
     await writeFileSafe(runtimePath(projectRoot, "commands", "next.md"), nextCommandContract());
     await writeFileSafe(runtimePath(projectRoot, "commands", "ideate.md"), ideateCommandContract());
     await writeFileSafe(runtimePath(projectRoot, "commands", "view.md"), viewCommandContract());
+    await writeFileSafe(runtimePath(projectRoot, "commands", "finish.md"), finishCommandContract());
+    await writeFileSafe(runtimePath(projectRoot, "commands", "cancel.md"), cancelCommandContract());
     for (const stage of FLOW_STAGES) {
         await writeFileSafe(runtimePath(projectRoot, "commands", `${stage}.md`), stageCommandShimMarkdown(stage));
     }
@@ -1085,6 +1092,8 @@ async function cleanStaleFiles(projectRoot) {
 }
 async function materializeRuntime(projectRoot, config, forceStateReset, operation = "sync") {
     const sentinelPath = await writeInitSentinel(projectRoot, operation);
+    const managedSession = await ManagedResourceSession.create({ projectRoot, operation });
+    setActiveManagedResourceSession(managedSession);
     try {
         const harnesses = config.harnesses;
         await ensureStructure(projectRoot);
@@ -1105,14 +1114,21 @@ async function materializeRuntime(projectRoot, config, forceStateReset, operatio
         await syncHarnessShims(projectRoot, harnesses);
         await writeCursorWorkflowRule(projectRoot, harnesses);
         await ensureGitignore(projectRoot);
+        await managedSession.commit();
         await fs.unlink(sentinelPath).catch(() => undefined);
     }
     catch (error) {
         // Leave the sentinel in place so doctor can surface the interrupted run.
         throw error;
     }
+    finally {
+        setActiveManagedResourceSession(null);
+    }
 }
 export async function initCclaw(options) {
+    if (options.harnesses !== undefined && options.harnesses.length === 0) {
+        throw new Error("Select at least one harness.");
+    }
     const baseConfig = createDefaultConfig(options.harnesses, options.track);
     // Best-effort auto-detect: a Node project gets `typescript`, a Go module
     // gets `go`, etc. Skipped entirely when the project root has no manifests.
@@ -1127,7 +1143,10 @@ export async function initCclaw(options) {
     await writeConfig(options.projectRoot, config, { mode: "minimal" });
     await materializeRuntime(options.projectRoot, config, true, "init");
 }
-export async function syncCclaw(projectRoot) {
+export async function syncCclaw(projectRoot, options = {}) {
+    if (options.harnesses !== undefined && options.harnesses.length === 0) {
+        throw new Error("Select at least one harness.");
+    }
     const configExists = await exists(configPath(projectRoot));
     let config = await readConfig(projectRoot);
     if (!configExists) {
@@ -1138,11 +1157,21 @@ export async function syncCclaw(projectRoot) {
         // Fall back to the previous default (config.harnesses) if no markers
         // are found so brand-new projects still bootstrap cleanly.
         const detected = await detectHarnesses(projectRoot);
-        const harnesses = detected.length > 0 ? detected : config.harnesses;
+        const harnesses = options.harnesses ?? (detected.length > 0 ? detected : config.harnesses);
         const defaultConfig = createDefaultConfig(harnesses);
         await writeConfig(projectRoot, defaultConfig);
         config = defaultConfig;
     }
+    else if (options.harnesses !== undefined) {
+        config = {
+            ...config,
+            harnesses: options.harnesses
+        };
+        await writeConfig(projectRoot, config, {
+            mode: "minimal",
+            advancedKeysPresent: await detectAdvancedKeys(projectRoot)
+        });
+    }
     await materializeRuntime(projectRoot, config, false, "sync");
 }
 /**
@@ -1156,8 +1185,12 @@ export async function syncCclaw(projectRoot) {
  * minimal — advanced knobs are never silently added.
  */
 export async function upgradeCclaw(projectRoot) {
+    const configExists = await exists(configPath(projectRoot));
     const advancedKeysPresent = await detectAdvancedKeys(projectRoot);
-    const existing = await readConfig(projectRoot);
+    const detectedHarnesses = configExists ? [] : await detectHarnesses(projectRoot);
+    const existing = configExists
+        ? await readConfig(projectRoot)
+        : createDefaultConfig(detectedHarnesses.length > 0 ? detectedHarnesses : undefined);
     const upgraded = {
         ...existing,
         version: CCLAW_VERSION,
@@ -1332,7 +1365,7 @@ export async function uninstallCclaw(projectRoot) {
     try {
         const entries = await fs.readdir(codexSkillsRoot);
         for (const entry of entries) {
-            if (/^(?:cclaw-)?cc(?:-(?:next|view|ops|ideate|brainstorm|scope|design|spec|plan|tdd|review|ship))?$/u.test(entry)) {
+            if (/^(?:cclaw-)?cc(?:-(?:next|view|finish|cancel|ops|ideate|brainstorm|scope|design|spec|plan|tdd|review|ship))?$/u.test(entry)) {
                 await fs.rm(path.join(codexSkillsRoot, entry), { recursive: true, force: true });
             }
         }

package/dist/internal/advance-stage.js

@@ -919,13 +919,13 @@ async function runAdvanceStage(projectRoot, args, io) {
         });
         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>"\`.`);
+            nextActions.push(`Run mandatory delegation(s) for stage "${args.stage}": ${validation.delegation.missing.join(", ")}. These roles are required by the stage schema before advance. If dispatch is impossible, use the waiver fallback only with a user-visible reason: \`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.`);
+            nextActions.push(`Role-switch fallback completion needs artifact evidenceRefs naming what the role proved; rerun completion with --evidence-ref=<artifact#anchor> 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.`);
+            nextActions.push(`Isolated completion(s) ${dispatchProofDetails.join(", ") || validation.delegation.missingDispatchProof.join(", ")} lack event-log dispatch proof. The ledger says completed, but .cclaw/state/delegation-events.jsonl must show scheduled -> launched -> acknowledged -> completed with --span-id, --dispatch-id, --dispatch-surface, --agent-definition-path, ackTs, and completedTs 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.`);
@@ -962,15 +962,15 @@ async function runAdvanceStage(projectRoot, args, io) {
         io.stderr.write(`cclaw internal advance-stage: validation failed for stage "${args.stage}".\n`);
         if (validation.delegation.missing.length > 0) {
             io.stderr.write(`- missing delegations: ${validation.delegation.missing.join(", ")}\n`);
-            io.stderr.write(`  next action: complete the delegation, or rerun with --waive-delegation=${validation.delegation.missing.join(",")} --waiver-reason="<why safe>".\n`);
+            io.stderr.write(`  next action: run the named agent(s) for this stage, or rerun with --waive-delegation=${validation.delegation.missing.join(",")} --waiver-reason="<why safe>" only when the user accepts the safety trade-off.\n`);
         }
         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`);
+            io.stderr.write(`  next action: include --evidence-ref=<artifact#anchor> when emitting the completed event so the artifact shows what was reviewed/proved, 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`);
+            io.stderr.write(`  next action: repair the event log proof by emitting scheduled -> launched -> acknowledged -> completed with --span-id, --dispatch-id, --dispatch-surface, --agent-definition-path, ackTs, and completedTs before advancing.\n`);
         }
         if (validation.delegation.legacyInferredCompletions.length > 0) {
             io.stderr.write(`- legacy-inferred completions need rerecord: ${validation.delegation.legacyInferredCompletions.join(", ")}\n`);

package/dist/managed-resources.d.ts

@@ -0,0 +1,53 @@
+import { type HarnessId } from "./types.js";
+import type { WriteFileSafeOptions } from "./fs-utils.js";
+export declare const MANAGED_RESOURCE_MANIFEST_REL_PATH = ".cclaw/state/managed-resources.json";
+export interface ManagedResourceEntry {
+    path: string;
+    sha256: string;
+    owner: "cclaw";
+    harness?: HarnessId | "core";
+    packageVersion: string;
+    prunable: boolean;
+    safeToOverwrite: boolean;
+    updatedAt: string;
+    lastBackupPath?: string;
+    previousSha256?: string;
+}
+export interface ManagedResourceManifest {
+    version: 1;
+    generatedAt: string;
+    packageVersion: string;
+    resources: ManagedResourceEntry[];
+}
+interface ManagedResourceSessionOptions {
+    projectRoot: string;
+    operation: string;
+}
+export interface ManagedResourceValidationIssue {
+    index?: number;
+    path?: string;
+    field: string;
+    message: string;
+}
+export declare function isManagedGeneratedPath(relPath: string): boolean;
+export declare function validateManagedResourceEntry(value: unknown, index?: number): ManagedResourceValidationIssue[];
+export declare function validateManagedResourceManifest(value: unknown): ManagedResourceValidationIssue[];
+export declare function isValidManagedResourceEntry(value: unknown): value is ManagedResourceEntry;
+export declare function readManagedResourceManifest(projectRoot: string): Promise<ManagedResourceManifest | null>;
+export declare class ManagedResourceSession {
+    private readonly projectRoot;
+    private readonly operation;
+    private readonly timestamp;
+    private readonly previous;
+    private readonly touched;
+    private constructor();
+    static create(options: ManagedResourceSessionOptions): Promise<ManagedResourceSession>;
+    shouldManage(filePath: string): boolean;
+    writeFileSafe(filePath: string, content: string, options?: WriteFileSafeOptions): Promise<void>;
+    commit(): Promise<ManagedResourceManifest>;
+}
+export declare function getActiveManagedResourceSession(): ManagedResourceSession | null;
+export declare function setActiveManagedResourceSession(session: ManagedResourceSession | null): void;
+export declare function isManagedResourcePath(projectRoot: string, filePath: string): boolean;
+export declare function hashManagedResourceContent(content: string | Buffer): string;
+export {};