cclaw-cli 0.51.27 → 0.51.29

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 {};

package/dist/managed-resources.js

@@ -0,0 +1,289 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { CCLAW_VERSION, RUNTIME_ROOT } from "./constants.js";
+import { HARNESS_IDS } from "./types.js";
+export const MANAGED_RESOURCE_MANIFEST_REL_PATH = `${RUNTIME_ROOT}/state/managed-resources.json`;
+const MANAGED_RESOURCE_HARNESSES = new Set(["core", ...HARNESS_IDS]);
+const SHA256_HEX_PATTERN = /^[a-f0-9]{64}$/iu;
+let activeSession = null;
+function sha256(content) {
+    return crypto.createHash("sha256").update(content).digest("hex");
+}
+function normalizeRelPath(projectRoot, filePath) {
+    const rel = path.relative(projectRoot, filePath).replace(/\\/gu, "/");
+    if (rel.startsWith("../") || rel === ".." || path.isAbsolute(rel))
+        return null;
+    return rel;
+}
+async function exists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function ensureDir(dirPath) {
+    await fs.mkdir(dirPath, { recursive: true });
+}
+async function atomicWrite(filePath, content, options = {}) {
+    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)}`);
+    await fs.writeFile(tempPath, content, {
+        encoding: "utf8",
+        ...(options.mode !== undefined ? { mode: options.mode } : {})
+    });
+    await fs.rename(tempPath, filePath);
+    if (options.mode !== undefined) {
+        await fs.chmod(filePath, options.mode).catch(() => undefined);
+    }
+}
+function inferHarness(relPath) {
+    if (relPath.startsWith(".claude/"))
+        return "claude";
+    if (relPath.startsWith(".cursor/"))
+        return "cursor";
+    if (relPath.startsWith(".opencode/"))
+        return "opencode";
+    if (relPath.startsWith(".codex/") || relPath.startsWith(".agents/skills/"))
+        return "codex";
+    return "core";
+}
+export function isManagedGeneratedPath(relPath) {
+    if (relPath === MANAGED_RESOURCE_MANIFEST_REL_PATH)
+        return false;
+    if (relPath === `${RUNTIME_ROOT}/config.yaml`)
+        return false;
+    if (relPath === `${RUNTIME_ROOT}/knowledge.jsonl`)
+        return false;
+    if (relPath.startsWith(`${RUNTIME_ROOT}/artifacts/`))
+        return false;
+    if (relPath.startsWith(`${RUNTIME_ROOT}/runs/`))
+        return false;
+    if (relPath === `${RUNTIME_ROOT}/state/flow-state.json`)
+        return false;
+    if (relPath === `${RUNTIME_ROOT}/state/.init-in-progress`)
+        return false;
+    if (relPath.startsWith(`${RUNTIME_ROOT}/state/upgrade-backups/`))
+        return false;
+    if (relPath.startsWith(`${RUNTIME_ROOT}/state/sync-backups/`))
+        return false;
+    if (relPath === "AGENTS.md" || relPath === "CLAUDE.md")
+        return true;
+    if (relPath === `${RUNTIME_ROOT}/state/iron-laws.json`)
+        return true;
+    for (const prefix 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/"
+    ]) {
+        if (relPath.startsWith(prefix))
+            return true;
+    }
+    return relPath === ".claude/hooks/hooks.json" ||
+        relPath === ".cursor/hooks.json" ||
+        relPath === ".cursor/rules/cclaw-workflow.mdc" ||
+        relPath === ".codex/hooks.json" ||
+        relPath === ".opencode/plugins/cclaw-plugin.mjs";
+}
+function validationIssue(index, field, message, pathValue) {
+    return {
+        ...(index !== undefined ? { index } : {}),
+        ...(typeof pathValue === "string" ? { path: pathValue } : {}),
+        field,
+        message
+    };
+}
+function validateSha256(value) {
+    return typeof value === "string" && SHA256_HEX_PATTERN.test(value);
+}
+export function validateManagedResourceEntry(value, index) {
+    const issues = [];
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return [validationIssue(index, "entry", "entry must be an object")];
+    }
+    const entry = value;
+    if (typeof entry.path !== "string" || entry.path.trim().length === 0) {
+        issues.push(validationIssue(index, "path", "path must be a non-empty string", entry.path));
+    }
+    else if (entry.path.startsWith("../") || entry.path === ".." || path.isAbsolute(entry.path)) {
+        issues.push(validationIssue(index, "path", "path must be project-relative", entry.path));
+    }
+    else if (!isManagedGeneratedPath(entry.path)) {
+        issues.push(validationIssue(index, "path", "path must be a known generated cclaw surface", entry.path));
+    }
+    if (!validateSha256(entry.sha256)) {
+        issues.push(validationIssue(index, "sha256", "sha256 must be a 64-character hex digest", entry.path));
+    }
+    if (entry.owner !== "cclaw") {
+        issues.push(validationIssue(index, "owner", 'owner must be "cclaw"', entry.path));
+    }
+    if (typeof entry.harness !== "string" || !MANAGED_RESOURCE_HARNESSES.has(entry.harness)) {
+        issues.push(validationIssue(index, "harness", `harness must be one of: core, ${HARNESS_IDS.join(", ")}`, entry.path));
+    }
+    if (typeof entry.packageVersion !== "string" || entry.packageVersion.trim().length === 0) {
+        issues.push(validationIssue(index, "packageVersion", "packageVersion must be a non-empty string", entry.path));
+    }
+    if (typeof entry.prunable !== "boolean") {
+        issues.push(validationIssue(index, "prunable", "prunable must be a boolean", entry.path));
+    }
+    if (typeof entry.safeToOverwrite !== "boolean") {
+        issues.push(validationIssue(index, "safeToOverwrite", "safeToOverwrite must be a boolean", entry.path));
+    }
+    if (typeof entry.updatedAt !== "string" || entry.updatedAt.trim().length === 0) {
+        issues.push(validationIssue(index, "updatedAt", "updatedAt must be a non-empty string", entry.path));
+    }
+    if (entry.lastBackupPath !== undefined && (typeof entry.lastBackupPath !== "string" || entry.lastBackupPath.trim().length === 0)) {
+        issues.push(validationIssue(index, "lastBackupPath", "lastBackupPath must be a non-empty string when present", entry.path));
+    }
+    if (entry.previousSha256 !== undefined && !validateSha256(entry.previousSha256)) {
+        issues.push(validationIssue(index, "previousSha256", "previousSha256 must be a 64-character hex digest when present", entry.path));
+    }
+    return issues;
+}
+export function validateManagedResourceManifest(value) {
+    const issues = [];
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return [validationIssue(undefined, "manifest", "manifest must be an object")];
+    }
+    const manifest = value;
+    if (manifest.version !== 1) {
+        issues.push(validationIssue(undefined, "version", "version must be 1"));
+    }
+    if (typeof manifest.generatedAt !== "string" || manifest.generatedAt.trim().length === 0) {
+        issues.push(validationIssue(undefined, "generatedAt", "generatedAt must be a non-empty string"));
+    }
+    if (typeof manifest.packageVersion !== "string" || manifest.packageVersion.trim().length === 0) {
+        issues.push(validationIssue(undefined, "packageVersion", "packageVersion must be a non-empty string"));
+    }
+    if (!Array.isArray(manifest.resources)) {
+        issues.push(validationIssue(undefined, "resources", "resources must be an array"));
+        return issues;
+    }
+    manifest.resources.forEach((entry, index) => {
+        issues.push(...validateManagedResourceEntry(entry, index));
+    });
+    return issues;
+}
+export function isValidManagedResourceEntry(value) {
+    return validateManagedResourceEntry(value).length === 0;
+}
+export async function readManagedResourceManifest(projectRoot) {
+    const manifestPath = path.join(projectRoot, MANAGED_RESOURCE_MANIFEST_REL_PATH);
+    if (!(await exists(manifestPath)))
+        return null;
+    const parsed = JSON.parse(await fs.readFile(manifestPath, "utf8"));
+    if (parsed.version !== 1 || !Array.isArray(parsed.resources))
+        return null;
+    const resources = parsed.resources.filter(isValidManagedResourceEntry);
+    return {
+        version: 1,
+        generatedAt: typeof parsed.generatedAt === "string" ? parsed.generatedAt : new Date(0).toISOString(),
+        packageVersion: typeof parsed.packageVersion === "string" ? parsed.packageVersion : "unknown",
+        resources
+    };
+}
+export class ManagedResourceSession {
+    projectRoot;
+    operation;
+    timestamp;
+    previous = new Map();
+    touched = new Map();
+    constructor(options, previous) {
+        this.projectRoot = options.projectRoot;
+        this.operation = options.operation;
+        this.timestamp = new Date().toISOString().replace(/[:.]/gu, "-");
+        for (const entry of previous?.resources ?? []) {
+            this.previous.set(entry.path, entry);
+        }
+    }
+    static async create(options) {
+        const previous = await readManagedResourceManifest(options.projectRoot).catch(() => null);
+        return new ManagedResourceSession(options, previous);
+    }
+    shouldManage(filePath) {
+        const rel = normalizeRelPath(this.projectRoot, filePath);
+        return rel !== null && isManagedGeneratedPath(rel);
+    }
+    async writeFileSafe(filePath, content, options = {}) {
+        const rel = normalizeRelPath(this.projectRoot, filePath);
+        if (rel === null || !isManagedGeneratedPath(rel)) {
+            await atomicWrite(filePath, content, options);
+            return;
+        }
+        const nextHash = sha256(content);
+        const previous = this.previous.get(rel);
+        let previousSha256;
+        let lastBackupPath;
+        if (await exists(filePath)) {
+            const current = await fs.readFile(filePath);
+            const currentHash = sha256(current);
+            previousSha256 = currentHash;
+            const knownPrevious = previous?.sha256;
+            if (currentHash !== nextHash && (knownPrevious === undefined || currentHash !== knownPrevious)) {
+                const backupRoot = path.join(this.projectRoot, RUNTIME_ROOT, "state", this.operation === "upgrade" ? "upgrade-backups" : "sync-backups", this.timestamp);
+                const backupPath = path.join(backupRoot, rel);
+                await ensureDir(path.dirname(backupPath));
+                await fs.copyFile(filePath, backupPath);
+                lastBackupPath = normalizeRelPath(this.projectRoot, backupPath) ?? undefined;
+            }
+        }
+        await atomicWrite(filePath, content, options);
+        this.touched.set(rel, {
+            path: rel,
+            sha256: nextHash,
+            owner: "cclaw",
+            harness: inferHarness(rel),
+            packageVersion: CCLAW_VERSION,
+            prunable: true,
+            safeToOverwrite: true,
+            updatedAt: new Date().toISOString(),
+            ...(lastBackupPath ? { lastBackupPath } : {}),
+            ...(previousSha256 && previousSha256 !== nextHash ? { previousSha256 } : {})
+        });
+    }
+    async commit() {
+        const resourcesByPath = new Map(this.previous);
+        for (const [rel, entry] of this.touched) {
+            resourcesByPath.set(rel, entry);
+        }
+        const resources = [];
+        for (const entry of resourcesByPath.values()) {
+            if (await exists(path.join(this.projectRoot, entry.path))) {
+                resources.push(entry);
+            }
+        }
+        const manifest = {
+            version: 1,
+            generatedAt: new Date().toISOString(),
+            packageVersion: CCLAW_VERSION,
+            resources: resources.sort((a, b) => a.path.localeCompare(b.path))
+        };
+        await atomicWrite(path.join(this.projectRoot, MANAGED_RESOURCE_MANIFEST_REL_PATH), `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
+        return manifest;
+    }
+}
+export function getActiveManagedResourceSession() {
+    return activeSession;
+}
+export function setActiveManagedResourceSession(session) {
+    activeSession = session;
+}
+export function isManagedResourcePath(projectRoot, filePath) {
+    const rel = normalizeRelPath(projectRoot, filePath);
+    return rel !== null && isManagedGeneratedPath(rel);
+}
+export function hashManagedResourceContent(content) {
+    return sha256(content);
+}

package/dist/run-archive.d.ts

@@ -1,5 +1,7 @@
 import { type FlowState } from "./flow-state.js";
 import type { FlowStage } from "./types.js";
+export declare const ARCHIVE_DISPOSITIONS: readonly ["completed", "cancelled", "abandoned"];
+export type ArchiveDisposition = (typeof ARCHIVE_DISPOSITIONS)[number];
 export interface CclawRunMeta {
     id: string;
     title: string;
@@ -12,6 +14,8 @@ export interface ArchiveRunResult {
     runName: string;
     resetState: FlowState;
     snapshottedStateFiles: string[];
+    disposition: ArchiveDisposition;
+    dispositionReason?: string;
     /** Knowledge curation hint: total active entries + soft threshold (50). */
     knowledge: {
         activeEntryCount: number;
@@ -36,11 +40,15 @@ export interface ArchiveManifest {
     sourceCurrentStage: FlowStage;
     sourceCompletedStages: FlowStage[];
     snapshottedStateFiles: string[];
+    disposition: ArchiveDisposition;
+    dispositionReason?: string;
     retro: ArchiveRunResult["retro"];
 }
 export interface ArchiveRunOptions {
     skipRetro?: boolean;
     skipRetroReason?: string;
+    disposition?: ArchiveDisposition;
+    dispositionReason?: string;
 }
 export declare function listRuns(projectRoot: string): Promise<CclawRunMeta[]>;
 export declare function archiveRun(projectRoot: string, runName?: string, options?: ArchiveRunOptions): Promise<ArchiveRunResult>;

package/dist/run-archive.js

@@ -6,6 +6,7 @@ import { ensureDir, exists, withDirectoryLock, writeFileSafe } from "./fs-utils.
 import { readKnowledgeSafely } from "./knowledge-store.js";
 import { evaluateRetroGate } from "./retro-gate.js";
 import { ensureRunSystem, flowStateLockPathFor, readFlowState, writeFlowState } from "./run-persistence.js";
+export const ARCHIVE_DISPOSITIONS = ["completed", "cancelled", "abandoned"];
 const RUNS_DIR_REL_PATH = `${RUNTIME_ROOT}/runs`;
 const ACTIVE_ARTIFACTS_REL_PATH = `${RUNTIME_ROOT}/artifacts`;
 const STATE_DIR_REL_PATH = `${RUNTIME_ROOT}/state`;
@@ -205,35 +206,44 @@ export async function archiveRun(projectRoot, runName, options = {}) {
             const archiveArtifactsPath = path.join(archivePath, "artifacts");
             let sourceState = await readFlowState(projectRoot);
             const retroGate = await evaluateRetroGate(projectRoot, sourceState);
+            const disposition = options.disposition ?? "completed";
+            const dispositionReason = options.dispositionReason?.trim();
+            const nonCompletedDisposition = disposition !== "completed";
+            if (nonCompletedDisposition && (!dispositionReason || dispositionReason.length === 0)) {
+                throw new Error("archive --disposition=cancelled|abandoned requires --reason=<text>.");
+            }
             const shipCompleted = sourceState.completedStages.includes("ship");
             const skipRetro = options.skipRetro === true;
             const skipRetroReason = options.skipRetroReason?.trim();
             if (skipRetro && (!skipRetroReason || skipRetroReason.length === 0)) {
                 throw new Error("archive --skip-retro requires --retro-reason=<text>.");
             }
+            if (nonCompletedDisposition && skipRetro) {
+                throw new Error("archive --skip-retro is only valid for completed archives; use --reason with cancelled/abandoned.");
+            }
             const retroSkippedInCloseout = sourceState.closeout.retroSkipped === true &&
                 typeof sourceState.closeout.retroSkipReason === "string" &&
                 sourceState.closeout.retroSkipReason.trim().length > 0;
             const readyForArchive = sourceState.closeout.shipSubstate === "ready_to_archive";
             const inShipCloseout = sourceState.currentStage === "ship";
-            if (readyForArchive && !compoundCloseoutComplete(sourceState)) {
+            if (!nonCompletedDisposition && readyForArchive && !compoundCloseoutComplete(sourceState)) {
                 throw new Error("Archive blocked: compound closeout is incomplete. " +
                     "Promote compound guidance or skip compound review with an explicit reason before archiving.");
             }
-            if (inShipCloseout && skipRetro) {
+            if (!nonCompletedDisposition && inShipCloseout && skipRetro) {
                 throw new Error("Archive blocked: --skip-retro is not allowed while current stage is ship. " +
                     "Complete closeout to ready_to_archive via /cc-next.");
             }
-            if (inShipCloseout && !readyForArchive) {
+            if (!nonCompletedDisposition && inShipCloseout && !readyForArchive) {
                 throw new Error("Archive blocked: closeout is not ready_to_archive. " +
                     "Resume /cc-next until closeout reaches ready_to_archive.");
             }
-            if (shipCompleted && !readyForArchive && !skipRetro) {
+            if (!nonCompletedDisposition && shipCompleted && !readyForArchive && !skipRetro) {
                 throw new Error("Archive blocked: closeout is not ready_to_archive. " +
                     "Resume /cc-next until closeout reaches ready_to_archive, " +
                     "or run `cclaw archive --skip-retro --retro-reason=<text>` for CLI-only flows.");
             }
-            if (retroGate.required && !retroGate.completed && !skipRetro && !retroSkippedInCloseout) {
+            if (!nonCompletedDisposition && retroGate.required && !retroGate.completed && !skipRetro && !retroSkippedInCloseout) {
                 throw new Error("Archive blocked: retro gate is required after ship completion. " +
                     "Run /cc-next (auto-runs retro) or, for CLI-only flows, re-run `cclaw archive --skip-retro --retro-reason=<text>`.");
             }
@@ -291,6 +301,8 @@ export async function archiveRun(projectRoot, runName, options = {}) {
                     sourceCurrentStage: sourceState.currentStage,
                     sourceCompletedStages: sourceState.completedStages,
                     snapshottedStateFiles,
+                    disposition,
+                    ...(dispositionReason ? { dispositionReason } : {}),
                     retro: retroSummary
                 };
                 await writeFileSafe(path.join(archivePath, "archive-manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
@@ -304,6 +316,8 @@ export async function archiveRun(projectRoot, runName, options = {}) {
                     runName: archiveRunName,
                     resetState,
                     snapshottedStateFiles,
+                    disposition,
+                    ...(dispositionReason ? { dispositionReason } : {}),
                     knowledge: knowledgeStats,
                     retro: retroSummary
                 };

package/dist/runs.d.ts

@@ -1,2 +1,2 @@
 export { CorruptFlowStateError, InvalidStageTransitionError, type WriteFlowStateOptions, ensureRunSystem, readFlowState, writeFlowState } from "./run-persistence.js";
-export { archiveRun, countActiveKnowledgeEntries, listRuns, type ArchiveManifest, type ArchiveRunOptions, type ArchiveRunResult, type CclawRunMeta } from "./run-archive.js";
+export { ARCHIVE_DISPOSITIONS, archiveRun, countActiveKnowledgeEntries, listRuns, type ArchiveDisposition, type ArchiveManifest, type ArchiveRunOptions, type ArchiveRunResult, type CclawRunMeta } from "./run-archive.js";

package/dist/runs.js

@@ -1,2 +1,2 @@
 export { CorruptFlowStateError, InvalidStageTransitionError, ensureRunSystem, readFlowState, writeFlowState } from "./run-persistence.js";
-export { archiveRun, countActiveKnowledgeEntries, listRuns } from "./run-archive.js";
+export { ARCHIVE_DISPOSITIONS, archiveRun, countActiveKnowledgeEntries, listRuns } from "./run-archive.js";