cclaw-cli 0.48.15 → 0.48.17

package/dist/content/observe.js

@@ -1,4 +1,5 @@
 import { RUNTIME_ROOT } from "../constants.js";
+import { HOOK_MANIFEST, groupBindingsByEvent } from "./hook-manifest.js";
 function hookDispatcherCommand(hookName) {
     // RUNTIME_ROOT is a relative path (".cclaw") that currently contains no
     // whitespace, so quoting is unnecessary inside the JSON-encoded command
@@ -6,139 +7,83 @@ function hookDispatcherCommand(hookName) {
     // JSON.stringify to survive spaces.
     return `node ${RUNTIME_ROOT}/hooks/run-hook.mjs ${hookName}`;
 }
+/**
+ * Claude / Codex share the same outer envelope: each event is an
+ * array of `{matcher?, hooks: [{type: "command", command, timeout?}]}`
+ * objects. Entries with the same `matcher` are merged into a single
+ * outer entry so we emit one `{matcher: "..."}` block with multiple
+ * inner hook commands.
+ */
+function buildClaudeLikeEvents(harness) {
+    const out = {};
+    for (const group of groupBindingsByEvent(harness)) {
+        const mergedByMatcher = new Map();
+        const order = [];
+        for (const entry of group.entries) {
+            const matcherKey = entry.matcher ?? "__no_matcher__";
+            let bucket = mergedByMatcher.get(matcherKey);
+            if (!bucket) {
+                bucket = {
+                    ...(entry.matcher !== undefined ? { matcher: entry.matcher } : {}),
+                    hooks: []
+                };
+                mergedByMatcher.set(matcherKey, bucket);
+                order.push(matcherKey);
+            }
+            const hookEntry = {
+                type: "command",
+                command: hookDispatcherCommand(entry.handler),
+                ...(entry.timeout !== undefined ? { timeout: entry.timeout } : {})
+            };
+            bucket.hooks.push(hookEntry);
+        }
+        out[group.event] = order.map((key) => mergedByMatcher.get(key));
+    }
+    return out;
+}
+/**
+ * Cursor uses a flat shape: each event maps directly to an array of
+ * `{command, matcher?, timeout?}` entries — no inner `hooks` array.
+ */
+function buildCursorEvents() {
+    const out = {};
+    for (const group of groupBindingsByEvent("cursor")) {
+        out[group.event] = group.entries.map((entry) => ({
+            command: hookDispatcherCommand(entry.handler),
+            ...(entry.matcher !== undefined ? { matcher: entry.matcher } : {}),
+            ...(entry.timeout !== undefined ? { timeout: entry.timeout } : {})
+        }));
+    }
+    return out;
+}
 export function claudeHooksJsonWithObservation() {
     return JSON.stringify({
         cclawHookSchemaVersion: 1,
-        hooks: {
-            SessionStart: [{
-                    matcher: "startup|resume|clear|compact",
-                    hooks: [{
-                            type: "command",
-                            command: hookDispatcherCommand("session-start")
-                        }]
-                }],
-            PreToolUse: [{
-                    matcher: "*",
-                    hooks: [{
-                            type: "command",
-                            command: hookDispatcherCommand("prompt-guard")
-                        }]
-                }, {
-                    matcher: "Write|Edit|MultiEdit|NotebookEdit|Bash",
-                    hooks: [{
-                            type: "command",
-                            command: hookDispatcherCommand("workflow-guard")
-                        }]
-                }],
-            PostToolUse: [{
-                    matcher: "*",
-                    hooks: [{
-                            type: "command",
-                            command: hookDispatcherCommand("context-monitor")
-                        }]
-                }],
-            Stop: [{
-                    hooks: [{
-                            type: "command",
-                            command: hookDispatcherCommand("stop-checkpoint"),
-                            timeout: 10
-                        }]
-                }],
-            PreCompact: [{
-                    matcher: "manual|auto",
-                    hooks: [{
-                            type: "command",
-                            command: hookDispatcherCommand("pre-compact"),
-                            timeout: 10
-                        }]
-                }]
-        }
+        hooks: buildClaudeLikeEvents("claude")
     }, null, 2);
 }
 export function cursorHooksJsonWithObservation() {
     return JSON.stringify({
         cclawHookSchemaVersion: 1,
         version: 1,
-        hooks: {
-            sessionStart: [{
-                    command: hookDispatcherCommand("session-start")
-                }],
-            sessionResume: [{
-                    command: hookDispatcherCommand("session-start")
-                }],
-            sessionClear: [{
-                    command: hookDispatcherCommand("session-start")
-                }],
-            sessionCompact: [{
-                    command: hookDispatcherCommand("pre-compact")
-                }, {
-                    command: hookDispatcherCommand("session-start")
-                }],
-            preToolUse: [{
-                    matcher: "*",
-                    command: hookDispatcherCommand("prompt-guard")
-                }, {
-                    matcher: "*",
-                    command: hookDispatcherCommand("workflow-guard")
-                }],
-            postToolUse: [{
-                    matcher: "*",
-                    command: hookDispatcherCommand("context-monitor")
-                }],
-            stop: [{
-                    command: hookDispatcherCommand("stop-checkpoint"),
-                    timeout: 10
-                }]
-        }
+        hooks: buildCursorEvents()
     }, null, 2);
 }
 export function codexHooksJsonWithObservation() {
     return JSON.stringify({
         cclawHookSchemaVersion: 1,
-        hooks: {
-            SessionStart: [{
-                    matcher: "startup|resume",
-                    hooks: [{
-                            type: "command",
-                            command: hookDispatcherCommand("session-start")
-                        }]
-                }],
-            UserPromptSubmit: [{
-                    hooks: [{
-                            type: "command",
-                            command: hookDispatcherCommand("prompt-guard")
-                        }, {
-                            type: "command",
-                            command: hookDispatcherCommand("workflow-guard")
-                        }, {
-                            type: "command",
-                            command: hookDispatcherCommand("verify-current-state")
-                        }]
-                }],
-            PreToolUse: [{
-                    matcher: "Bash|bash",
-                    hooks: [{
-                            type: "command",
-                            command: hookDispatcherCommand("prompt-guard")
-                        }, {
-                            type: "command",
-                            command: hookDispatcherCommand("workflow-guard")
-                        }]
-                }],
-            PostToolUse: [{
-                    matcher: "Bash|bash",
-                    hooks: [{
-                            type: "command",
-                            command: hookDispatcherCommand("context-monitor")
-                        }]
-                }],
-            Stop: [{
-                    hooks: [{
-                            type: "command",
-                            command: hookDispatcherCommand("stop-checkpoint"),
-                            timeout: 10
-                        }]
-                }]
-        }
+        hooks: buildClaudeLikeEvents("codex")
     }, null, 2);
 }
+/**
+ * Public accessor so diagnostic CLIs and tests can inspect the
+ * manifest without importing the private generator helpers.
+ */
+export function hookManifestSnapshot() {
+    return (HOOK_MANIFEST.length === 0
+        ? ["claude", "cursor", "codex"]
+        : ["claude", "cursor", "codex"]).map((harness) => ({
+        harness,
+        events: groupBindingsByEvent(harness)
+    }));
+}

package/dist/internal/advance-stage.js

@@ -13,6 +13,7 @@ import { appendKnowledge } from "../knowledge-store.js";
 import { readFlowState, writeFlowState } from "../runs.js";
 import { FLOW_STAGES } from "../types.js";
 import { runCompoundReadinessCommand } from "./compound-readiness.js";
+import { runHookManifestCommand } from "./hook-manifest.js";
 import { runEnvelopeValidateCommand } from "./envelope-validate.js";
 import { runKnowledgeDigestCommand } from "./knowledge-digest.js";
 import { runTddLoopStatusCommand } from "./tdd-loop-status.js";
@@ -674,7 +675,7 @@ async function runHookCommand(projectRoot, args, io) {
 export async function runInternalCommand(projectRoot, argv, io) {
     const [subcommand, ...tokens] = argv;
     if (!subcommand) {
-        io.stderr.write("cclaw internal requires a subcommand: advance-stage | verify-flow-state-diff | verify-current-state | knowledge-digest | envelope-validate | tdd-red-evidence | tdd-loop-status | compound-readiness | hook\n");
+        io.stderr.write("cclaw internal requires a subcommand: advance-stage | verify-flow-state-diff | verify-current-state | knowledge-digest | envelope-validate | tdd-red-evidence | tdd-loop-status | compound-readiness | hook-manifest | hook\n");
         return 1;
     }
     try {
@@ -702,10 +703,13 @@ export async function runInternalCommand(projectRoot, argv, io) {
         if (subcommand === "compound-readiness") {
             return await runCompoundReadinessCommand(projectRoot, tokens, io);
         }
+        if (subcommand === "hook-manifest") {
+            return await runHookManifestCommand(projectRoot, tokens, io);
+        }
         if (subcommand === "hook") {
             return await runHookCommand(projectRoot, parseHookArgs(tokens), io);
         }
-        io.stderr.write(`Unknown internal subcommand: ${subcommand}. Expected advance-stage | verify-flow-state-diff | verify-current-state | knowledge-digest | envelope-validate | tdd-red-evidence | tdd-loop-status | compound-readiness | hook\n`);
+        io.stderr.write(`Unknown internal subcommand: ${subcommand}. Expected advance-stage | verify-flow-state-diff | verify-current-state | knowledge-digest | envelope-validate | tdd-red-evidence | tdd-loop-status | compound-readiness | hook-manifest | hook\n`);
         return 1;
     }
     catch (err) {

package/dist/internal/hook-manifest.d.ts

@@ -0,0 +1,16 @@
+import type { Writable } from "node:stream";
+interface InternalIo {
+    stdout: Writable;
+    stderr: Writable;
+}
+/**
+ * `cclaw internal hook-manifest` — diagnostic command that prints
+ * the resolved manifest. Primary use cases:
+ *
+ *  - debugging "which handler fires for event X on harness Y",
+ *  - migration tooling that needs a machine-readable view,
+ *  - parity verification between the source-of-truth manifest and
+ *    per-harness generated documents.
+ */
+export declare function runHookManifestCommand(_projectRoot: string, argv: string[], io: InternalIo): Promise<number>;
+export {};

package/dist/internal/hook-manifest.js

@@ -0,0 +1,77 @@
+import { HOOK_MANIFEST, HOOK_MANIFEST_HARNESSES, groupBindingsByEvent, requiredEventsFor } from "../content/hook-manifest.js";
+function parseArgs(tokens) {
+    const args = { json: false };
+    for (let i = 0; i < tokens.length; i += 1) {
+        const token = tokens[i];
+        if (token === "--json")
+            args.json = true;
+        else if (token === "--harness") {
+            const value = tokens[i + 1];
+            if (value !== "claude" && value !== "cursor" && value !== "codex") {
+                throw new Error(`--harness must be one of claude|cursor|codex, got ${String(value)}`);
+            }
+            args.harness = value;
+            i += 1;
+        }
+        else {
+            throw new Error(`Unknown hook-manifest flag: ${token}`);
+        }
+    }
+    return args;
+}
+/**
+ * `cclaw internal hook-manifest` — diagnostic command that prints
+ * the resolved manifest. Primary use cases:
+ *
+ *  - debugging "which handler fires for event X on harness Y",
+ *  - migration tooling that needs a machine-readable view,
+ *  - parity verification between the source-of-truth manifest and
+ *    per-harness generated documents.
+ */
+export async function runHookManifestCommand(_projectRoot, argv, io) {
+    const args = parseArgs(argv);
+    const harnesses = args.harness ? [args.harness] : [...HOOK_MANIFEST_HARNESSES];
+    if (args.json) {
+        const payload = {
+            handlers: HOOK_MANIFEST.map((spec) => ({
+                handler: spec.handler,
+                description: spec.description,
+                semantic: spec.semantic,
+                bindings: spec.bindings
+            })),
+            byHarness: Object.fromEntries(harnesses.map((harness) => [
+                harness,
+                {
+                    requiredEvents: requiredEventsFor(harness),
+                    events: groupBindingsByEvent(harness)
+                }
+            ]))
+        };
+        io.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+        return 0;
+    }
+    const lines = [];
+    lines.push("cclaw hook manifest");
+    for (const harness of harnesses) {
+        lines.push("");
+        lines.push(`## ${harness}`);
+        const groups = groupBindingsByEvent(harness);
+        if (groups.length === 0) {
+            lines.push("  (no bindings)");
+            continue;
+        }
+        for (const group of groups) {
+            lines.push(`  ${group.event}:`);
+            for (const entry of group.entries) {
+                const parts = [entry.handler];
+                if (entry.matcher)
+                    parts.push(`matcher=${entry.matcher}`);
+                if (entry.timeout)
+                    parts.push(`timeout=${entry.timeout}s`);
+                lines.push(`    - ${parts.join(" ")}`);
+            }
+        }
+    }
+    io.stdout.write(`${lines.join("\n")}\n`);
+    return 0;
+}

package/dist/run-archive.js

@@ -6,7 +6,7 @@ import { readActiveFeature, syncActiveFeatureSnapshot } from "./feature-system.j
 import { ensureDir, exists, withDirectoryLock, writeFileSafe } from "./fs-utils.js";
 import { readKnowledgeSafely } from "./knowledge-store.js";
 import { evaluateRetroGate } from "./retro-gate.js";
-import { ensureRunSystem, readFlowState, writeFlowState } from "./run-persistence.js";
+import { ensureRunSystem, flowStateLockPathFor, readFlowState, writeFlowState } from "./run-persistence.js";
 const RUNS_DIR_REL_PATH = `${RUNTIME_ROOT}/runs`;
 const ACTIVE_ARTIFACTS_REL_PATH = `${RUNTIME_ROOT}/artifacts`;
 const STATE_DIR_REL_PATH = `${RUNTIME_ROOT}/state`;
@@ -161,150 +161,157 @@ export async function listRuns(projectRoot) {
 }
 export async function archiveRun(projectRoot, featureName, options = {}) {
     await ensureRunSystem(projectRoot);
+    // Hold BOTH archive.lock and flow-state.lock for the entire archive:
+    // the outer archive lock serializes two concurrent archives; the
+    // inner flow-state lock prevents CLI / hook paths from mutating
+    // flow-state between the archive snapshot and the subsequent reset,
+    // which used to cause lost-update races.
     return withDirectoryLock(archiveLockPath(projectRoot), async () => {
-        const activeFeature = await readActiveFeature(projectRoot);
-        const artifactsDir = activeArtifactsPath(projectRoot);
-        const runsDir = runsRoot(projectRoot);
-        await ensureDir(runsDir);
-        await ensureDir(artifactsDir);
-        const feature = (featureName?.trim() && featureName.trim().length > 0)
-            ? featureName.trim()
-            : await inferFeatureNameFromArtifacts(projectRoot);
-        const archiveBaseId = `${toArchiveDate()}-${slugifyFeatureName(feature)}`;
-        const archiveId = await uniqueArchiveId(projectRoot, archiveBaseId);
-        const archivePath = path.join(runsDir, archiveId);
-        const archiveArtifactsPath = path.join(archivePath, "artifacts");
-        let sourceState = await readFlowState(projectRoot);
-        const retroGate = await evaluateRetroGate(projectRoot, sourceState);
-        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>.");
-        }
-        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 (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) {
-            throw new Error("Archive blocked: closeout is not ready_to_archive. " +
-                "Resume /cc-next until closeout reaches ready_to_archive.");
-        }
-        if (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) {
-            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>`.");
-        }
-        if (retroGate.completed) {
-            const completedAt = sourceState.retro.completedAt ?? new Date().toISOString();
-            sourceState = {
-                ...sourceState,
-                retro: {
-                    required: retroGate.required,
-                    completedAt,
-                    compoundEntries: retroGate.compoundEntries
-                }
-            };
-            await writeFlowState(projectRoot, sourceState, { allowReset: true });
-        }
-        const retroSummary = {
-            required: retroGate.required,
-            completed: retroGate.completed,
-            skipped: skipRetro || retroSkippedInCloseout,
-            skipReason: skipRetro
-                ? skipRetroReason
-                : retroSkippedInCloseout
-                    ? sourceState.closeout.retroSkipReason
-                    : undefined,
-            compoundEntries: retroGate.compoundEntries
-        };
-        await ensureDir(archivePath);
-        // Drop an `.archive-in-progress` sentinel immediately so that a crash
-        // between the artifact rename and the final manifest write leaves a
-        // recoverable marker (doctor surfaces these; re-running archive on an
-        // orphan attempts to complete or roll back). The sentinel is removed
-        // only after the manifest lands successfully.
-        const sentinelPath = path.join(archivePath, ".archive-in-progress");
-        const archivedAt = new Date().toISOString();
-        await writeFileSafe(sentinelPath, `${JSON.stringify({ archiveId, startedAt: archivedAt, sourceRunId: sourceState.activeRunId }, null, 2)}\n`);
-        const stateBeforeReset = sourceState;
-        let artifactsMoved = false;
-        let stateReset = false;
-        try {
-            await fs.rename(artifactsDir, archiveArtifactsPath);
-            artifactsMoved = true;
+        return withDirectoryLock(flowStateLockPathFor(projectRoot), async () => {
+            const activeFeature = await readActiveFeature(projectRoot);
+            const artifactsDir = activeArtifactsPath(projectRoot);
+            const runsDir = runsRoot(projectRoot);
+            await ensureDir(runsDir);
             await ensureDir(artifactsDir);
-            const archiveStatePath = path.join(archivePath, "state");
-            const snapshottedStateFiles = await snapshotStateDirectory(projectRoot, archiveStatePath);
-            const resetState = createInitialFlowState();
-            await writeFlowState(projectRoot, resetState, { allowReset: true });
-            stateReset = true;
-            await resetCarryoverStateFiles(projectRoot, resetState.activeRunId);
-            const manifest = {
-                version: 1,
-                archiveId,
-                archivedAt,
-                featureName: feature,
-                activeFeature,
-                sourceRunId: sourceState.activeRunId,
-                sourceCurrentStage: sourceState.currentStage,
-                sourceCompletedStages: sourceState.completedStages,
-                snapshottedStateFiles,
-                retro: retroSummary
-            };
-            await writeFileSafe(path.join(archivePath, "archive-manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
-            // Manifest landed — sentinel is no longer needed.
-            await fs.unlink(sentinelPath).catch(() => undefined);
-            const knowledgeStats = await readKnowledgeStats(projectRoot);
-            await syncActiveFeatureSnapshot(projectRoot);
-            return {
-                archiveId,
-                archivePath,
-                archivedAt,
-                featureName: feature,
-                activeFeature,
-                resetState,
-                snapshottedStateFiles,
-                knowledge: knowledgeStats,
-                retro: retroSummary
+            const feature = (featureName?.trim() && featureName.trim().length > 0)
+                ? featureName.trim()
+                : await inferFeatureNameFromArtifacts(projectRoot);
+            const archiveBaseId = `${toArchiveDate()}-${slugifyFeatureName(feature)}`;
+            const archiveId = await uniqueArchiveId(projectRoot, archiveBaseId);
+            const archivePath = path.join(runsDir, archiveId);
+            const archiveArtifactsPath = path.join(archivePath, "artifacts");
+            let sourceState = await readFlowState(projectRoot);
+            const retroGate = await evaluateRetroGate(projectRoot, sourceState);
+            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>.");
+            }
+            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 (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) {
+                throw new Error("Archive blocked: closeout is not ready_to_archive. " +
+                    "Resume /cc-next until closeout reaches ready_to_archive.");
+            }
+            if (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) {
+                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>`.");
+            }
+            if (retroGate.completed) {
+                const completedAt = sourceState.retro.completedAt ?? new Date().toISOString();
+                sourceState = {
+                    ...sourceState,
+                    retro: {
+                        required: retroGate.required,
+                        completedAt,
+                        compoundEntries: retroGate.compoundEntries
+                    }
+                };
+                await writeFlowState(projectRoot, sourceState, { allowReset: true, skipLock: true });
+            }
+            const retroSummary = {
+                required: retroGate.required,
+                completed: retroGate.completed,
+                skipped: skipRetro || retroSkippedInCloseout,
+                skipReason: skipRetro
+                    ? skipRetroReason
+                    : retroSkippedInCloseout
+                        ? sourceState.closeout.retroSkipReason
+                        : undefined,
+                compoundEntries: retroGate.compoundEntries
             };
-        }
-        catch (err) {
-            // Best-effort rollback: if artifacts were moved but the subsequent
-            // steps failed, put artifacts back so the user is not left without
-            // a working run. The sentinel is intentionally left behind for
-            // inspection; doctor surfaces it.
-            if (artifactsMoved) {
-                try {
-                    await fs.rm(artifactsDir, { recursive: true, force: true });
-                    await fs.rename(archiveArtifactsPath, artifactsDir);
-                }
-                catch {
-                    // Rollback failed — sentinel + orphaned archive dir will be
-                    // surfaced by doctor and can be reconciled manually.
-                }
+            await ensureDir(archivePath);
+            // Drop an `.archive-in-progress` sentinel immediately so that a crash
+            // between the artifact rename and the final manifest write leaves a
+            // recoverable marker (doctor surfaces these; re-running archive on an
+            // orphan attempts to complete or roll back). The sentinel is removed
+            // only after the manifest lands successfully.
+            const sentinelPath = path.join(archivePath, ".archive-in-progress");
+            const archivedAt = new Date().toISOString();
+            await writeFileSafe(sentinelPath, `${JSON.stringify({ archiveId, startedAt: archivedAt, sourceRunId: sourceState.activeRunId }, null, 2)}\n`);
+            const stateBeforeReset = sourceState;
+            let artifactsMoved = false;
+            let stateReset = false;
+            try {
+                await fs.rename(artifactsDir, archiveArtifactsPath);
+                artifactsMoved = true;
+                await ensureDir(artifactsDir);
+                const archiveStatePath = path.join(archivePath, "state");
+                const snapshottedStateFiles = await snapshotStateDirectory(projectRoot, archiveStatePath);
+                const resetState = createInitialFlowState();
+                await writeFlowState(projectRoot, resetState, { allowReset: true, skipLock: true });
+                stateReset = true;
+                await resetCarryoverStateFiles(projectRoot, resetState.activeRunId);
+                const manifest = {
+                    version: 1,
+                    archiveId,
+                    archivedAt,
+                    featureName: feature,
+                    activeFeature,
+                    sourceRunId: sourceState.activeRunId,
+                    sourceCurrentStage: sourceState.currentStage,
+                    sourceCompletedStages: sourceState.completedStages,
+                    snapshottedStateFiles,
+                    retro: retroSummary
+                };
+                await writeFileSafe(path.join(archivePath, "archive-manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+                // Manifest landed — sentinel is no longer needed.
+                await fs.unlink(sentinelPath).catch(() => undefined);
+                const knowledgeStats = await readKnowledgeStats(projectRoot);
+                await syncActiveFeatureSnapshot(projectRoot);
+                return {
+                    archiveId,
+                    archivePath,
+                    archivedAt,
+                    featureName: feature,
+                    activeFeature,
+                    resetState,
+                    snapshottedStateFiles,
+                    knowledge: knowledgeStats,
+                    retro: retroSummary
+                };
             }
-            if (stateReset) {
-                try {
-                    await writeFlowState(projectRoot, stateBeforeReset, { allowReset: true });
-                    await resetCarryoverStateFiles(projectRoot, stateBeforeReset.activeRunId);
+            catch (err) {
+                // Best-effort rollback: if artifacts were moved but the subsequent
+                // steps failed, put artifacts back so the user is not left without
+                // a working run. The sentinel is intentionally left behind for
+                // inspection; doctor surfaces it.
+                if (artifactsMoved) {
+                    try {
+                        await fs.rm(artifactsDir, { recursive: true, force: true });
+                        await fs.rename(archiveArtifactsPath, artifactsDir);
+                    }
+                    catch {
+                        // Rollback failed — sentinel + orphaned archive dir will be
+                        // surfaced by doctor and can be reconciled manually.
+                    }
                 }
-                catch {
-                    // If rollback of state fails, keep sentinel + archive remnants for
-                    // manual reconciliation.
+                if (stateReset) {
+                    try {
+                        await writeFlowState(projectRoot, stateBeforeReset, { allowReset: true, skipLock: true });
+                        await resetCarryoverStateFiles(projectRoot, stateBeforeReset.activeRunId);
+                    }
+                    catch {
+                        // If rollback of state fails, keep sentinel + archive remnants for
+                        // manual reconciliation.
+                    }
                 }
+                throw err;
             }
-            throw err;
-        }
+        });
     }, {
         retries: 400,
         retryDelayMs: 25,