cclaw-cli 0.48.0 → 0.48.2

package/dist/install.js

@@ -44,7 +44,8 @@ import { ensureDir, exists, writeFileSafe } from "./fs-utils.js";
 import { ensureGitignore, removeGitignorePatterns } from "./gitignore.js";
 import { HARNESS_ADAPTERS, harnessShimFileNames, harnessTier, syncHarnessShims, removeCclawFromAgentsMd } from "./harness-adapters.js";
 import { validateHookDocument } from "./hook-schema.js";
-import { ensureRunSystem, readFlowState } from "./runs.js";
+import { detectHarnesses } from "./init-detect.js";
+import { CorruptFlowStateError, ensureRunSystem, readFlowState } from "./runs.js";
 import { FLOW_STAGES } from "./types.js";
 const OPENCODE_PLUGIN_REL_PATH = ".opencode/plugins/cclaw-plugin.mjs";
 const CURSOR_RULE_REL_PATH = ".cursor/rules/cclaw-workflow.mdc";
@@ -853,7 +854,24 @@ Drop this section if no hard rule applies. Keep it crisp:
 async function ensureSessionStateFiles(projectRoot) {
     const stateDir = runtimePath(projectRoot, "state");
     await ensureDir(stateDir);
-    const flow = await readFlowState(projectRoot);
+    // If flow-state.json is corrupt, `readFlowState` quarantines the bad
+    // file and throws. During install we'd rather continue than abort:
+    // the user just asked to set up cclaw, and the corrupt file is already
+    // preserved next to the original path. Fall back to a fresh initial
+    // state so the rest of install completes and the user can inspect the
+    // `.corrupt-<timestamp>.json` quarantine afterwards.
+    let flow;
+    try {
+        flow = await readFlowState(projectRoot);
+    }
+    catch (err) {
+        if (err instanceof CorruptFlowStateError) {
+            flow = createInitialFlowState();
+        }
+        else {
+            throw err;
+        }
+    }
     const activityPath = path.join(stateDir, "stage-activity.jsonl");
     if (!(await exists(activityPath))) {
         await writeFileSafe(activityPath, "");
@@ -959,7 +977,7 @@ async function writeState(projectRoot, config, forceReset = false) {
     if (!forceReset && (await exists(statePath))) {
         return;
     }
-    const state = createInitialFlowState("active", config.defaultTrack ?? "standard");
+    const state = createInitialFlowState({ track: config.defaultTrack ?? "standard" });
     await writeFileSafe(statePath, `${JSON.stringify(state, null, 2)}\n`);
 }
 async function writeAdapterManifest(projectRoot, harnesses) {
@@ -1021,6 +1039,14 @@ async function writeHarnessGapsState(projectRoot, harnesses) {
                 break;
         }
         for (const event of missingHookEvents) {
+            if (harness === "codex" && event === "precompact_digest") {
+                // Codex CLI has no PreCompact event. Generic "schedule the script
+                // manually" copy doesn't help; instead, point the agent at the
+                // in-thread substitute that already exists in cclaw content
+                // (`/cc-ops retro` reads the same digest the hook would emit).
+                remediation.push("hook event precompact_digest → Codex has no PreCompact event; run `/cc-ops retro` in-thread before compaction instead of relying on a hook");
+                continue;
+            }
             remediation.push(`hook event ${event} → schedule the corresponding script manually or accept reduced observability`);
         }
         return {
@@ -1210,9 +1236,19 @@ export async function initCclaw(options) {
 }
 export async function syncCclaw(projectRoot) {
     const configExists = await exists(configPath(projectRoot));
-    const config = await readConfig(projectRoot);
+    let config = await readConfig(projectRoot);
     if (!configExists) {
-        await writeConfig(projectRoot, createDefaultConfig(config.harnesses));
+        // Prefer detected harness markers over the hardcoded default list.
+        // Without this, a user running `cclaw sync` in a `.claude`-only
+        // project ends up with a config that also enables cursor/opencode/
+        // codex, which then fails doctor checks for missing shim folders.
+        // 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 defaultConfig = createDefaultConfig(harnesses);
+        await writeConfig(projectRoot, defaultConfig);
+        config = defaultConfig;
     }
     await materializeRuntime(projectRoot, config, false);
 }

package/dist/internal/advance-stage.js

@@ -1,22 +1,51 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { RUNTIME_ROOT } from "../constants.js";
+import { RUNTIME_ROOT, SHIP_FINALIZATION_MODES } from "../constants.js";
 import { stageSchema } from "../content/stage-schema.js";
 import { appendDelegation, checkMandatoryDelegations } from "../delegation.js";
 import { readActiveFeature } from "../feature-system.js";
 import { verifyCompletedStagesGateClosure, verifyCurrentStageGateEvidence } from "../gate-evidence.js";
 import { extractMarkdownSectionBody, parseLearningsSection } from "../artifact-linter.js";
-import { isFlowTrack, nextStage } from "../flow-state.js";
+import { getAvailableTransitions, getTransitionGuards, isFlowTrack } from "../flow-state.js";
 import { appendKnowledge } from "../knowledge-store.js";
 import { readFlowState, writeFlowState } from "../runs.js";
 import { FLOW_STAGES } from "../types.js";
 function unique(values) {
     return [...new Set(values)];
 }
+function resolveSuccessorTransition(stage, track, transitionTargets, satisfiedGuards, selectedTransitionGuards) {
+    const natural = transitionTargets[0] ?? null;
+    const specialTargets = transitionTargets.filter((target) => target !== natural);
+    for (const target of specialTargets) {
+        const guards = getTransitionGuards(stage, target, track);
+        if (guards.length === 0)
+            continue;
+        const selectedSpecial = guards.some((guard) => selectedTransitionGuards.has(guard));
+        if (!selectedSpecial)
+            continue;
+        if (guards.every((guard) => satisfiedGuards.has(guard))) {
+            return target;
+        }
+    }
+    if (natural) {
+        const guards = getTransitionGuards(stage, natural, track);
+        if (guards.every((guard) => satisfiedGuards.has(guard))) {
+            return natural;
+        }
+    }
+    for (const target of specialTargets) {
+        const guards = getTransitionGuards(stage, target, track);
+        if (guards.every((guard) => satisfiedGuards.has(guard))) {
+            return target;
+        }
+    }
+    return natural;
+}
 const TEST_COMMAND_HINT_PATTERN = /\b(?:npm test|pnpm test|yarn test|bun test|vitest|jest|pytest|go test|cargo test|mvn test|gradle test|dotnet test)\b/iu;
 const SHA_WITH_LABEL_PATTERN = /\b(?:sha|commit)(?:\s*[:=]|\s+)\s*[0-9a-f]{7,40}\b/iu;
 const PASS_STATUS_PATTERN = /\b(?:pass|passed|green|ok)\b/iu;
-const SHIP_FINALIZATION_MODE_PATTERN = /\bFINALIZE_(?:MERGE_LOCAL|OPEN_PR|QUEUE|HANDOFF|SKIP)\b/u;
+const SHIP_FINALIZATION_MODE_PATTERN = new RegExp(`\\b(?:${SHIP_FINALIZATION_MODES.join("|")})\\b`, "u");
+const SHIP_FINALIZATION_MODE_HINT = SHIP_FINALIZATION_MODES.join(", ");
 // Per-gate validators keyed by `${stage}:${gateId}`. Returning a non-null
 // string surfaces the reason as an `advance-stage` failure so evidence is
 // guaranteed to carry the structural breadcrumbs downstream tooling
@@ -36,7 +65,7 @@ const GATE_EVIDENCE_VALIDATORS = {
     },
     "ship:ship_finalization_executed": (evidence) => {
         if (!SHIP_FINALIZATION_MODE_PATTERN.test(evidence)) {
-            return "must name the finalization mode that ran (for example `FINALIZE_MERGE_LOCAL`, `FINALIZE_OPEN_PR`, `FINALIZE_HANDOFF`, `FINALIZE_QUEUE`, or `FINALIZE_SKIP`).";
+            return `must name the finalization mode that ran (for example ${SHIP_FINALIZATION_MODE_HINT}).`;
         }
         return null;
     }
@@ -395,10 +424,16 @@ async function runAdvanceStage(projectRoot, args, io) {
     const requiredGateIds = schema.requiredGates
         .filter((gate) => gate.tier === "required")
         .map((gate) => gate.id);
+    const transitionTargets = getAvailableTransitions(args.stage, flowState.track).map((rule) => rule.to);
     const allowedGateIds = new Set(schema.requiredGates.map((gate) => gate.id));
+    const transitionGuardIds = new Set(transitionTargets
+        .flatMap((target) => getTransitionGuards(args.stage, target, flowState.track))
+        .filter((guardId) => !allowedGateIds.has(guardId)));
+    const selectableGateIds = new Set([...allowedGateIds, ...transitionGuardIds]);
     const selectedGateIds = args.passedGateIds.length > 0
-        ? args.passedGateIds.filter((gateId) => allowedGateIds.has(gateId))
+        ? args.passedGateIds.filter((gateId) => selectableGateIds.has(gateId))
         : requiredGateIds;
+    const selectedTransitionGuards = selectedGateIds.filter((gateId) => transitionGuardIds.has(gateId));
     const missingRequired = requiredGateIds.filter((gateId) => !selectedGateIds.includes(gateId));
     if (missingRequired.length > 0) {
         io.stderr.write(`cclaw internal advance-stage: required gates not selected as passed: ${missingRequired.join(", ")}.\n`);
@@ -436,7 +471,8 @@ async function runAdvanceStage(projectRoot, args, io) {
         ...nextPassed.filter((gateId) => conditional.has(gateId)),
         ...nextBlocked.filter((gateId) => conditional.has(gateId))
     ]);
-    const missingGuardEvidence = nextPassed.filter((gateId) => {
+    const guardEvidenceGateIds = unique([...nextPassed, ...selectedTransitionGuards]);
+    const missingGuardEvidence = guardEvidenceGateIds.filter((gateId) => {
         const existing = flowState.guardEvidence[gateId];
         if (typeof existing === "string" && existing.trim().length > 0) {
             return false;
@@ -464,7 +500,7 @@ async function runAdvanceStage(projectRoot, args, io) {
         return 1;
     }
     const nextGuardEvidence = { ...flowState.guardEvidence };
-    for (const gateId of nextPassed) {
+    for (const gateId of guardEvidenceGateIds) {
         const provided = args.evidenceByGate[gateId];
         if (typeof provided === "string" && provided.trim().length > 0) {
             nextGuardEvidence[gateId] = provided.trim();
@@ -508,7 +544,8 @@ async function runAdvanceStage(projectRoot, args, io) {
         io.stderr.write(`cclaw internal advance-stage: learnings harvest failed for "${schema.artifactFile}". ${learningsHarvest.details}\n`);
         return 1;
     }
-    const successor = nextStage(args.stage, flowState.track);
+    const satisfiedGuards = new Set([...nextPassed, ...selectedTransitionGuards]);
+    const successor = resolveSuccessorTransition(args.stage, flowState.track, transitionTargets, satisfiedGuards, new Set(selectedTransitionGuards));
     const completedStages = flowState.completedStages.includes(args.stage)
         ? [...flowState.completedStages]
         : [...flowState.completedStages, args.stage];

package/dist/knowledge-store.js

@@ -1,7 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { RUNTIME_ROOT } from "./constants.js";
-import { withDirectoryLock } from "./fs-utils.js";
+import { stripBom, withDirectoryLock } from "./fs-utils.js";
 import { FLOW_STAGES } from "./types.js";
 const KNOWLEDGE_TYPE_SET = new Set(["rule", "pattern", "lesson", "compound"]);
 const KNOWLEDGE_CONFIDENCE_SET = new Set(["high", "medium", "low"]);
@@ -179,7 +179,7 @@ export function materializeKnowledgeEntry(seed, defaults = {}) {
 async function readExistingKnowledgeKeys(filePath) {
     const keys = new Set();
     try {
-        const raw = await fs.readFile(filePath, "utf8");
+        const raw = stripBom(await fs.readFile(filePath, "utf8"));
         const lines = raw.split(/\r?\n/u).map((line) => line.trim()).filter((line) => line.length > 0);
         for (const line of lines) {
             try {

package/dist/retro-gate.js

@@ -1,14 +1,20 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { RUNTIME_ROOT } from "./constants.js";
-import { exists } from "./fs-utils.js";
+import { exists, stripBom } from "./fs-utils.js";
 function activeArtifactsPath(projectRoot) {
     return path.join(projectRoot, RUNTIME_ROOT, "artifacts");
 }
 function retroArtifactPath(projectRoot) {
     return path.join(activeArtifactsPath(projectRoot), "09-retro.md");
 }
-const RETRO_ARTIFACT_MTIME_FALLBACK_WINDOW_MS = 24 * 60 * 60 * 1000;
+// Fallback window for compound-entry scanning when `retroDraftedAt` /
+// `retroAcceptedAt` are not set (legacy runs or imports): use the retro
+// artifact's mtime ± 7 days. 24h was too narrow for long-running retros
+// that are edited over several days or runs imported from another
+// machine with slightly different clocks; 7 days is still tight enough
+// that entries from an unrelated future run are excluded.
+const RETRO_ARTIFACT_MTIME_FALLBACK_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
 function parseIsoTimestamp(value) {
     if (!value || value.trim().length === 0)
         return null;
@@ -58,7 +64,7 @@ export async function evaluateRetroGate(projectRoot, state) {
     const knowledgeFile = path.join(projectRoot, RUNTIME_ROOT, "knowledge.jsonl");
     if (shouldFallbackScan && (await exists(knowledgeFile))) {
         try {
-            const raw = await fs.readFile(knowledgeFile, "utf8");
+            const raw = stripBom(await fs.readFile(knowledgeFile, "utf8"));
             compoundEntries = 0;
             for (const line of raw.split(/\r?\n/)) {
                 const trimmed = line.trim();
@@ -90,17 +96,20 @@ export async function evaluateRetroGate(projectRoot, state) {
             compoundEntries = 0;
         }
     }
-    // A retro is considered complete when either:
-    //   - at least one compound learning was promoted during the retro window, or
-    //   - the operator explicitly skipped retro or compound (`retroSkipped` /
-    //     `compoundSkipped` recorded in the closeout substate) after reviewing
-    //     the draft. Previously the gate required `compoundEntries > 0`
-    //     unconditionally, which dead-locked ship closeout whenever the retro
-    //     yielded no new patterns worth promoting.
-    const explicitSkip = Boolean(state.closeout.retroSkipped || state.closeout.compoundSkipped);
-    const completed = required
-        ? hasRetroArtifact && (compoundEntries > 0 || explicitSkip)
-        : true;
+    // A retro is considered complete when any of:
+    //   - the retro artifact exists AND (at least one compound learning was
+    //     promoted during the retro window OR compound was explicitly skipped
+    //     after reviewing the draft), or
+    //   - the operator explicitly skipped the retro step itself
+    //     (`retroSkipped === true` with a reason). `retroSkipped` is an
+    //     operator-level override of the artifact requirement, so it must
+    //     bypass `hasRetroArtifact` — otherwise a run that legitimately had
+    //     nothing worth retro-ing dead-locks at closeout waiting for a
+    //     file that will never exist.
+    const retroSkipped = state.closeout.retroSkipped === true;
+    const compoundSkipped = state.closeout.compoundSkipped === true;
+    const artifactPathComplete = hasRetroArtifact && (compoundEntries > 0 || compoundSkipped);
+    const completed = required ? retroSkipped || artifactPathComplete : true;
     return {
         required,
         completed,

package/dist/run-archive.js

@@ -3,7 +3,7 @@ import path from "node:path";
 import { RUNTIME_ROOT } from "./constants.js";
 import { createInitialFlowState } from "./flow-state.js";
 import { readActiveFeature, syncActiveFeatureSnapshot } from "./feature-system.js";
-import { ensureDir, exists, writeFileSafe } from "./fs-utils.js";
+import { ensureDir, exists, withDirectoryLock, writeFileSafe } from "./fs-utils.js";
 import { evaluateRetroGate } from "./retro-gate.js";
 import { ensureRunSystem, readFlowState, writeFlowState } from "./run-persistence.js";
 const RUNS_DIR_REL_PATH = `${RUNTIME_ROOT}/runs`;
@@ -17,6 +17,12 @@ const STATE_SNAPSHOT_EXCLUDE = new Set([
 const DELEGATION_LOG_FILE = "delegation-log.json";
 const TDD_CYCLE_LOG_FILE = "tdd-cycle-log.jsonl";
 const RECONCILIATION_NOTICES_FILE = "reconciliation-notices.json";
+const CRITICAL_STATE_SNAPSHOT_FILES = new Set([
+    "flow-state.json",
+    DELEGATION_LOG_FILE,
+    TDD_CYCLE_LOG_FILE,
+    RECONCILIATION_NOTICES_FILE
+]);
 function runsRoot(projectRoot) {
     return path.join(projectRoot, RUNS_DIR_REL_PATH);
 }
@@ -26,6 +32,9 @@ function activeArtifactsPath(projectRoot) {
 function stateDirPath(projectRoot) {
     return path.join(projectRoot, STATE_DIR_REL_PATH);
 }
+function archiveLockPath(projectRoot) {
+    return path.join(projectRoot, RUNTIME_ROOT, "state", ".archive.lock");
+}
 async function snapshotStateDirectory(projectRoot, destinationRoot) {
     const sourceDir = stateDirPath(projectRoot);
     if (!(await exists(sourceDir))) {
@@ -57,8 +66,12 @@ async function snapshotStateDirectory(projectRoot, destinationRoot) {
                 copied.push(entry.name);
             }
         }
-        catch {
-            // best-effort snapshot; continue on individual failures
+        catch (error) {
+            if (CRITICAL_STATE_SNAPSHOT_FILES.has(entry.name)) {
+                const details = error instanceof Error ? error.message : String(error);
+                throw new Error(`Archive snapshot failed for critical state file "${entry.name}" (${details}).`);
+            }
+            // Non-critical snapshot files are best-effort and may be skipped.
         }
     }
     return copied.sort((a, b) => a.localeCompare(b));
@@ -147,97 +160,155 @@ export async function listRuns(projectRoot) {
 }
 export async function archiveRun(projectRoot, featureName, options = {}) {
     await ensureRunSystem(projectRoot);
-    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";
-    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
-            }
+    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 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);
-    await fs.rename(artifactsDir, archiveArtifactsPath);
-    await ensureDir(artifactsDir);
-    const archiveStatePath = path.join(archivePath, "state");
-    const snapshottedStateFiles = await snapshotStateDirectory(projectRoot, archiveStatePath);
-    const resetState = createInitialFlowState();
-    await writeFlowState(projectRoot, resetState, { allowReset: true });
-    await resetCarryoverStateFiles(projectRoot, resetState.activeRunId);
-    const archivedAt = new Date().toISOString();
-    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`);
-    const knowledgeStats = await readKnowledgeStats(projectRoot);
-    await syncActiveFeatureSnapshot(projectRoot);
-    return {
-        archiveId,
-        archivePath,
-        archivedAt,
-        featureName: feature,
-        activeFeature,
-        resetState,
-        snapshottedStateFiles,
-        knowledge: knowledgeStats,
-        retro: retroSummary
-    };
+        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 });
+            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
+            };
+        }
+        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.
+                }
+            }
+            if (stateReset) {
+                try {
+                    await writeFlowState(projectRoot, stateBeforeReset, { allowReset: true });
+                    await resetCarryoverStateFiles(projectRoot, stateBeforeReset.activeRunId);
+                }
+                catch {
+                    // If rollback of state fails, keep sentinel + archive remnants for
+                    // manual reconciliation.
+                }
+            }
+            throw err;
+        }
+    }, {
+        retries: 400,
+        retryDelayMs: 25,
+        staleAfterMs: 120_000
+    });
 }
 const KNOWLEDGE_SOFT_THRESHOLD = 50;
 async function readKnowledgeStats(projectRoot) {

package/dist/run-persistence.d.ts

@@ -12,12 +12,19 @@ export interface WriteFlowStateOptions {
      */
     allowReset?: boolean;
 }
+export interface ReadFlowStateOptions {
+    /**
+     * When false, skip feature-system auto-repair writes and read flow-state in
+     * pure diagnostic mode.
+     */
+    repairFeatureSystem?: boolean;
+}
 export declare class CorruptFlowStateError extends Error {
     readonly statePath: string;
     readonly quarantinedPath: string;
     constructor(statePath: string, quarantinedPath: string, cause: unknown);
 }
-export declare function readFlowState(projectRoot: string): Promise<FlowState>;
+export declare function readFlowState(projectRoot: string, options?: ReadFlowStateOptions): Promise<FlowState>;
 export declare function writeFlowState(projectRoot: string, state: FlowState, options?: WriteFlowStateOptions): Promise<void>;
 interface EnsureRunSystemOptions {
     createIfMissing?: boolean;

package/dist/run-persistence.js

@@ -24,6 +24,13 @@ function validateFlowTransition(prev, next) {
         // New run — only reset paths may change the runId, but those set allowReset.
         throw new InvalidStageTransitionError(prev.currentStage, next.currentStage, `cannot change activeRunId from "${prev.activeRunId}" to "${next.activeRunId}" without allowReset.`);
     }
+    // Track is immutable within a single run: stage schemas, gate sets, and
+    // cross-stage reads all branch on track. Silently flipping the track
+    // mid-run would let completed stages satisfy one gate tier and the
+    // current stage re-read the catalog under a different tier.
+    if (prev.track !== next.track) {
+        throw new InvalidStageTransitionError(prev.currentStage, next.currentStage, `cannot change track from "${prev.track}" to "${next.track}" mid-run (activeRunId="${prev.activeRunId}"). Archive the run and start a new one to switch tracks.`);
+    }
     for (const completed of prev.completedStages) {
         if (!next.completedStages.includes(completed)) {
             throw new InvalidStageTransitionError(prev.currentStage, next.currentStage, `completedStages must be monotonic: stage "${completed}" was previously completed but is missing from the new state.`);
@@ -270,7 +277,7 @@ function sanitizeCloseoutState(value) {
 }
 function coerceFlowState(parsed) {
     const track = coerceTrack(parsed.track);
-    const next = createInitialFlowState("active", track);
+    const next = createInitialFlowState({ track });
     const activeRunIdRaw = parsed.activeRunId;
     const activeRunId = typeof activeRunIdRaw === "string" && activeRunIdRaw.trim().length > 0
         ? activeRunIdRaw.trim()
@@ -326,8 +333,10 @@ async function quarantineCorruptState(statePath, cause) {
     }
     throw new CorruptFlowStateError(statePath, quarantinedPath, cause);
 }
-export async function readFlowState(projectRoot) {
-    await ensureFeatureSystem(projectRoot);
+export async function readFlowState(projectRoot, options = {}) {
+    if (options.repairFeatureSystem !== false) {
+        await ensureFeatureSystem(projectRoot);
+    }
     const statePath = flowStatePath(projectRoot);
     if (!(await exists(statePath))) {
         return createInitialFlowState();
@@ -368,8 +377,7 @@ export async function writeFlowState(projectRoot, state, options = {}) {
                 if (err instanceof InvalidStageTransitionError) {
                     throw err;
                 }
-                // A corrupt prior file is surfaced by readFlowState elsewhere; don't
-                // block a legitimate write attempt on parse errors here.
+                throw new Error(`cannot validate flow-state transition because ${FLOW_STATE_REL_PATH} is unreadable or corrupt (${err instanceof Error ? err.message : String(err)}). Run \`cclaw doctor\` and reconcile the state before retrying.`);
             }
         }
         const safe = coerceFlowState({ ...state });