cclaw-cli 0.48.1 → 0.48.2

package/dist/artifact-linter.js

@@ -1,6 +1,6 @@
 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 { exists } from "./fs-utils.js";
 import { stageSchema } from "./content/stage-schema.js";
 import { FLOW_STAGES } from "./types.js";
@@ -137,13 +137,7 @@ function tokensFromRule(rule) {
         return [...new Set(allCaps)];
     }
     if (/finalization enum token/iu.test(rule)) {
-        return [
-            "FINALIZE_MERGE_LOCAL",
-            "FINALIZE_OPEN_PR",
-            "FINALIZE_KEEP_BRANCH",
-            "FINALIZE_DISCARD_BRANCH",
-            "FINALIZE_NO_VCS"
-        ];
+        return [...SHIP_FINALIZATION_MODES];
     }
     if (/final verdict/iu.test(rule)) {
         return ["APPROVED", "APPROVED_WITH_CONCERNS", "BLOCKED"];

package/dist/constants.d.ts

@@ -3,6 +3,12 @@ import type { FlowStage, HarnessId } from "./types.js";
 export declare const RUNTIME_ROOT = ".cclaw";
 export declare const CCLAW_VERSION: string;
 export declare const FLOW_VERSION = "1.0.0";
+/**
+ * Canonical ship finalization enums used across stage schema, linting, and
+ * runtime gate evidence checks.
+ */
+export declare const SHIP_FINALIZATION_MODES: readonly ["FINALIZE_MERGE_LOCAL", "FINALIZE_OPEN_PR", "FINALIZE_KEEP_BRANCH", "FINALIZE_DISCARD_BRANCH", "FINALIZE_NO_VCS"];
+export type ShipFinalizationMode = (typeof SHIP_FINALIZATION_MODES)[number];
 export declare const DEFAULT_HARNESSES: HarnessId[];
 /**
  * Evals subtree. Scaffolds the directory layout and a default config.yaml; the

package/dist/constants.js

@@ -35,6 +35,17 @@ function readPackageVersion() {
 }
 export const CCLAW_VERSION = readPackageVersion();
 export const FLOW_VERSION = "1.0.0";
+/**
+ * Canonical ship finalization enums used across stage schema, linting, and
+ * runtime gate evidence checks.
+ */
+export const SHIP_FINALIZATION_MODES = [
+    "FINALIZE_MERGE_LOCAL",
+    "FINALIZE_OPEN_PR",
+    "FINALIZE_KEEP_BRANCH",
+    "FINALIZE_DISCARD_BRANCH",
+    "FINALIZE_NO_VCS"
+];
 export const DEFAULT_HARNESSES = [
     "claude",
     "cursor",

package/dist/content/stages/ship.js

@@ -1,3 +1,4 @@
+import { SHIP_FINALIZATION_MODES } from "../../constants.js";
 // ---------------------------------------------------------------------------
 // SHIP — reference: superpowers finishing-a-development-branch + gstack /ship
 // ---------------------------------------------------------------------------
@@ -93,11 +94,7 @@ export const SHIP = {
         "Pre-Ship Checks",
         "Release Notes",
         "Rollback Plan",
-        "FINALIZE_MERGE_LOCAL",
-        "FINALIZE_OPEN_PR",
-        "FINALIZE_KEEP_BRANCH",
-        "FINALIZE_DISCARD_BRANCH",
-        "FINALIZE_NO_VCS"
+        ...SHIP_FINALIZATION_MODES
     ],
     artifactFile: "08-ship.md",
     // `done` exits the stage pipeline. Archive semantics are handled by the

package/dist/content/templates.js

@@ -1,6 +1,7 @@
-import { CCLAW_VERSION } from "../constants.js";
+import { CCLAW_VERSION, SHIP_FINALIZATION_MODES } from "../constants.js";
 import { orderedStageSchemas } from "./stage-schema.js";
 import { FLOW_STAGES } from "../types.js";
+const SHIP_FINALIZATION_ENUM_LINES = SHIP_FINALIZATION_MODES.map((mode) => `  - ${mode}`).join("\n");
 export const ARTIFACT_TEMPLATES = {
     "01-brainstorm.md": `---
 stage: brainstorm
@@ -645,11 +646,7 @@ inputs_hash: sha256:pending
 
 ## Finalization
 - Selected enum (exactly one):
-  - FINALIZE_MERGE_LOCAL
-  - FINALIZE_OPEN_PR
-  - FINALIZE_KEEP_BRANCH
-  - FINALIZE_DISCARD_BRANCH
-  - FINALIZE_NO_VCS
+${SHIP_FINALIZATION_ENUM_LINES}
 - Selected label (A/B/C/D/E):
 - Execution result:
 - PR URL / merge commit / kept branch / discard confirmation:

package/dist/delegation.d.ts

@@ -53,6 +53,8 @@ export type DelegationEntry = {
     retryCount?: number;
     /** Optional references to evidence anchors in artifacts. */
     evidenceRefs?: string[];
+    /** Optional skill marker used for role-specific mandatory checks. */
+    skill?: string;
     /**
      * Fulfillment mode this entry was executed under. Omitted on legacy rows
      * (treated as `"isolated"` for Claude, otherwise inferred from the active
@@ -85,7 +87,9 @@ export declare function appendDelegation(projectRoot: string, entry: DelegationE
  * strongest guarantee.
  */
 export declare function expectedFulfillmentMode(fallbacks: SubagentFallback[]): DelegationFulfillmentMode;
-export declare function checkMandatoryDelegations(projectRoot: string, stage: FlowStage): Promise<{
+export declare function checkMandatoryDelegations(projectRoot: string, stage: FlowStage, options?: {
+    repairFeatureSystem?: boolean;
+}): Promise<{
     satisfied: boolean;
     missing: string[];
     waived: string[];

package/dist/delegation.js

@@ -154,6 +154,7 @@ function isDelegationEntry(value) {
         (o.tokens === undefined || isDelegationTokenUsage(o.tokens)) &&
         retryOk &&
         (o.evidenceRefs === undefined || (Array.isArray(o.evidenceRefs) && o.evidenceRefs.every((item) => typeof item === "string"))) &&
+        (o.skill === undefined || typeof o.skill === "string") &&
         (o.schemaVersion === undefined || o.schemaVersion === 1));
 }
 function parseLedger(raw, runId) {
@@ -257,9 +258,11 @@ export function expectedFulfillmentMode(fallbacks) {
         return "role-switch";
     return "harness-waiver";
 }
-export async function checkMandatoryDelegations(projectRoot, stage) {
+export async function checkMandatoryDelegations(projectRoot, stage, options = {}) {
     const mandatory = stageSchema(stage).mandatoryDelegations;
-    const { activeRunId } = await readFlowState(projectRoot);
+    const { activeRunId } = await readFlowState(projectRoot, {
+        repairFeatureSystem: options.repairFeatureSystem
+    });
     const ledger = await readDelegationLedger(projectRoot);
     const forStage = ledger.entries.filter((e) => e.stage === stage);
     const forRun = forStage.filter((e) => e.runId === activeRunId);
@@ -279,14 +282,15 @@ export async function checkMandatoryDelegations(projectRoot, stage) {
         const rows = forRun.filter((e) => e.agent === agent);
         const completedRows = rows.filter((e) => e.status === "completed");
         const waivedRows = rows.filter((e) => e.status === "waived");
-        const requiredCompletedCount = stage === "review" &&
+        const adversarialReviewerRequired = stage === "review" &&
             agent === "reviewer" &&
-            reviewTriggers?.requireAdversarialReviewer
-            ? 2
-            : 1;
+            reviewTriggers?.requireAdversarialReviewer === true;
+        const requiredCompletedCount = adversarialReviewerRequired ? 2 : 1;
         const hasCompleted = completedRows.length >= requiredCompletedCount;
         const hasWaived = waivedRows.length > 0;
-        const ok = hasCompleted || hasWaived;
+        const hasAdversarialSkill = !adversarialReviewerRequired ||
+            completedRows.some((row) => row.skill === "adversarial-review");
+        const ok = hasWaived || (hasCompleted && hasAdversarialSkill);
         if (!ok) {
             missing.push(agent);
             continue;

package/dist/doctor.js

@@ -10,11 +10,11 @@ import { exists } from "./fs-utils.js";
 import { gitignoreHasRequiredPatterns } from "./gitignore.js";
 import { HARNESS_ADAPTERS, CCLAW_MARKER_START, CCLAW_MARKER_END, harnessShimFileNames, harnessShimSkillNames } from "./harness-adapters.js";
 import { policyChecks } from "./policy.js";
-import { readFlowState } from "./runs.js";
-import { skippedStagesForTrack } from "./flow-state.js";
+import { CorruptFlowStateError, readFlowState } from "./runs.js";
+import { createInitialFlowState, skippedStagesForTrack } from "./flow-state.js";
 import { FLOW_STAGES, TRACK_STAGES } from "./types.js";
 import { checkMandatoryDelegations } from "./delegation.js";
-import { ensureFeatureSystem, listFeatures, readActiveFeature, readFeatureWorktreeRegistry, resolveFeatureWorkspacePath, worktreeRegistryPath } from "./feature-system.js";
+import { activeFeatureMetaPath, ensureFeatureSystem, listFeatures, readActiveFeature, readFeatureWorktreeRegistry, resolveFeatureWorkspacePath, worktreeRegistryPath } from "./feature-system.js";
 import { buildTraceMatrix } from "./trace-matrix.js";
 import { classifyReconciliationNotices, reconcileAndWriteCurrentStageGateCatalog, readReconciliationNotices, RECONCILIATION_NOTICES_REL_PATH, verifyCompletedStagesGateClosure, verifyCurrentStageGateEvidence } from "./gate-evidence.js";
 import { parseTddCycleLog, validateTddCycleOrder } from "./tdd-cycle.js";
@@ -190,6 +190,25 @@ async function readHookDocument(filePath) {
         return null;
     }
 }
+async function readJsonObjectStatus(filePath) {
+    if (!(await exists(filePath))) {
+        return { exists: false, ok: false, error: "file is missing" };
+    }
+    try {
+        const parsed = JSON.parse(await fs.readFile(filePath, "utf8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return { exists: true, ok: false, error: "JSON root must be an object" };
+        }
+        return { exists: true, ok: true };
+    }
+    catch (error) {
+        return {
+            exists: true,
+            ok: false,
+            error: error instanceof Error ? error.message : String(error)
+        };
+    }
+}
 function normalizeOpenCodePluginEntry(entry) {
     if (typeof entry === "string" && entry.trim().length > 0)
         return entry.trim();
@@ -212,12 +231,16 @@ async function opencodeRegistrationCheck(projectRoot) {
         path.join(projectRoot, ".opencode/opencode.json"),
         path.join(projectRoot, ".opencode/opencode.jsonc")
     ];
+    const mismatches = [];
+    let foundAnyConfig = false;
     for (const configPath of candidates) {
         if (!(await exists(configPath))) {
             continue;
         }
+        foundAnyConfig = true;
         const parsed = await readHookDocument(configPath);
         if (!parsed) {
+            mismatches.push(`${path.relative(projectRoot, configPath)} is unreadable or invalid JSON`);
             continue;
         }
         const plugins = Array.isArray(parsed.plugin) ? parsed.plugin : [];
@@ -225,7 +248,10 @@ async function opencodeRegistrationCheck(projectRoot) {
         if (registered) {
             return { ok: true, details: `${path.relative(projectRoot, configPath)} registers ${expected}` };
         }
-        return { ok: false, details: `${path.relative(projectRoot, configPath)} missing plugin ${expected}` };
+        mismatches.push(`${path.relative(projectRoot, configPath)} missing plugin ${expected}`);
+    }
+    if (foundAnyConfig) {
+        return { ok: false, details: mismatches.join(" | ") };
     }
     return { ok: false, details: `No opencode.json/opencode.jsonc found with plugin ${expected}` };
 }
@@ -244,6 +270,12 @@ async function opencodePluginRuntimeShapeCheck(projectRoot) {
             };
         }
         const plugin = imported.default({ directory: projectRoot });
+        if (!plugin || typeof plugin !== "object" || Array.isArray(plugin)) {
+            return {
+                ok: false,
+                details: `${path.relative(projectRoot, pluginPath)} factory must return a plugin object`
+            };
+        }
         const requiredHandlers = [
             "event",
             "tool.execute.before",
@@ -257,7 +289,6 @@ async function opencodePluginRuntimeShapeCheck(projectRoot) {
                 details: `${path.relative(projectRoot, pluginPath)} missing runtime handlers: ${missing.join(", ")}`
             };
         }
-        await plugin.event({ event: { type: "session.updated", data: {} } });
         return {
             ok: true,
             details: `${path.relative(projectRoot, pluginPath)} exports compatible runtime handler shape`
@@ -1289,10 +1320,28 @@ export async function doctorChecks(projectRoot, options = {}) {
             details: modePath
         });
     }
-    await ensureFeatureSystem(projectRoot);
-    const activeFeature = await readActiveFeature(projectRoot);
-    let flowState = await readFlowState(projectRoot);
-    if (options.reconcileCurrentStageGates === true) {
+    await ensureFeatureSystem(projectRoot, { repair: false });
+    const activeFeature = await readActiveFeature(projectRoot, { repair: false });
+    let flowState = createInitialFlowState();
+    let flowStateCorruptError = null;
+    try {
+        flowState = await readFlowState(projectRoot, { repairFeatureSystem: false });
+    }
+    catch (error) {
+        if (error instanceof CorruptFlowStateError) {
+            flowStateCorruptError = error;
+            checks.push({
+                name: "flow_state:readable",
+                ok: false,
+                severity: "error",
+                details: error.message
+            });
+        }
+        else {
+            throw error;
+        }
+    }
+    if (options.reconcileCurrentStageGates === true && !flowStateCorruptError) {
         const reconciliation = await reconcileAndWriteCurrentStageGateCatalog(projectRoot);
         if (reconciliation.wrote) {
             flowState = {
@@ -1311,6 +1360,13 @@ export async function doctorChecks(projectRoot, options = {}) {
                 : `no gate reconciliation changes needed for stage "${reconciliation.stage}"`
         });
     }
+    else if (options.reconcileCurrentStageGates === true && flowStateCorruptError) {
+        checks.push({
+            name: "gates:reconcile:writeback",
+            ok: false,
+            details: "skipped gate reconciliation because flow-state.json is corrupt"
+        });
+    }
     const activeRunId = typeof flowState.activeRunId === "string" ? flowState.activeRunId.trim() : "";
     checks.push({
         name: "flow_state:active_run_id",
@@ -1318,6 +1374,15 @@ export async function doctorChecks(projectRoot, options = {}) {
         details: `${RUNTIME_ROOT}/state/flow-state.json must include activeRunId`
     });
     const reconciliationNotices = await readReconciliationNotices(projectRoot);
+    checks.push({
+        name: "state:reconciliation_notices_parse",
+        ok: reconciliationNotices.parseOk && reconciliationNotices.schemaOk,
+        details: !reconciliationNotices.parseOk
+            ? `unable to parse ${RECONCILIATION_NOTICES_REL_PATH}; reset with \`cclaw sync\` or repair JSON by hand`
+            : !reconciliationNotices.schemaOk
+                ? `${RECONCILIATION_NOTICES_REL_PATH} schemaVersion mismatch; expected ${reconciliationNotices.schemaVersion}`
+                : `${RECONCILIATION_NOTICES_REL_PATH} parsed successfully`
+    });
     const noticeBuckets = classifyReconciliationNotices(flowState, reconciliationNotices.notices);
     const formatNoticeList = (items) => items
         .slice(0, 8)
@@ -1425,22 +1490,38 @@ export async function doctorChecks(projectRoot, options = {}) {
             ? "no TODO/TBD/FIXME placeholder markers found in active artifacts"
             : `warning: placeholder markers detected in active artifacts (${artifactPlaceholderHits.join(", ")}). Clear before marking completion.`
     });
-    const features = await listFeatures(projectRoot);
-    const worktreeRegistry = await readFeatureWorktreeRegistry(projectRoot);
+    const activeMetaStatus = await readJsonObjectStatus(activeFeatureMetaPath(projectRoot));
+    const worktreeRegistryStatus = await readJsonObjectStatus(worktreeRegistryPath(projectRoot));
+    const features = await listFeatures(projectRoot, { repair: false });
+    const worktreeRegistry = await readFeatureWorktreeRegistry(projectRoot, { repair: false });
     const activeFeatureEntry = worktreeRegistry.entries.find((entry) => entry.featureId === activeFeature);
     const activeFeatureWorkspacePath = activeFeatureEntry
         ? resolveFeatureWorkspacePath(projectRoot, activeFeatureEntry)
         : "";
     checks.push({
         name: "state:active_feature_meta",
-        ok: await exists(path.join(projectRoot, RUNTIME_ROOT, "state", "active-feature.json")),
+        ok: activeMetaStatus.exists,
         details: `${RUNTIME_ROOT}/state/active-feature.json must exist`
     });
+    checks.push({
+        name: "state:active_feature_meta_valid_json",
+        ok: activeMetaStatus.ok,
+        details: activeMetaStatus.ok
+            ? `${RUNTIME_ROOT}/state/active-feature.json parsed successfully`
+            : `${RUNTIME_ROOT}/state/active-feature.json is invalid: ${activeMetaStatus.error ?? "unknown error"}`
+    });
     checks.push({
         name: "state:worktree_registry_exists",
-        ok: await exists(worktreeRegistryPath(projectRoot)),
+        ok: worktreeRegistryStatus.exists,
         details: `${RUNTIME_ROOT}/state/worktrees.json must exist and track feature->worktree mapping`
     });
+    checks.push({
+        name: "state:worktree_registry_valid_json",
+        ok: worktreeRegistryStatus.ok,
+        details: worktreeRegistryStatus.ok
+            ? `${RUNTIME_ROOT}/state/worktrees.json parsed successfully`
+            : `${RUNTIME_ROOT}/state/worktrees.json is invalid: ${worktreeRegistryStatus.error ?? "unknown error"}`
+    });
     checks.push({
         name: "state:active_feature_exists",
         ok: features.includes(activeFeature),
@@ -1590,7 +1671,9 @@ export async function doctorChecks(projectRoot, options = {}) {
         ok: await exists(path.join(projectRoot, RUNTIME_ROOT, "runs")),
         details: `${RUNTIME_ROOT}/runs must exist for archived feature snapshots`
     });
-    const delegation = await checkMandatoryDelegations(projectRoot, flowState.currentStage);
+    const delegation = await checkMandatoryDelegations(projectRoot, flowState.currentStage, {
+        repairFeatureSystem: false
+    });
     const missingEvidenceNote = delegation.missingEvidence && delegation.missingEvidence.length > 0
         ? ` (role-switch rows without evidenceRefs: ${delegation.missingEvidence.join(", ")})`
         : "";

package/dist/feature-system.d.ts

@@ -19,16 +19,23 @@ export interface CreateFeatureOptions {
     cloneActive?: boolean;
     switchTo?: boolean;
 }
+export interface FeatureSystemAccessOptions {
+    /**
+     * When false, read metadata without auto-repair writes. Useful for pure
+     * diagnostics (doctor) that should not mutate state as a side effect.
+     */
+    repair?: boolean;
+}
 export declare function activeFeatureMetaPath(projectRoot: string): string;
 export declare function worktreeRegistryPath(projectRoot: string): string;
 export declare function featureRootPath(projectRoot: string, featureId: string): string;
 export declare function featureArtifactsPath(projectRoot: string, featureId: string): string;
 export declare function featureStatePath(projectRoot: string, featureId: string): string;
 export declare function resolveFeatureWorkspacePath(projectRoot: string, entry: FeatureWorkspaceEntry): string;
-export declare function ensureFeatureSystem(projectRoot: string): Promise<ActiveFeatureMeta>;
-export declare function readFeatureWorktreeRegistry(projectRoot: string): Promise<FeatureWorktreeRegistry>;
-export declare function readActiveFeature(projectRoot: string): Promise<string>;
-export declare function listFeatures(projectRoot: string): Promise<string[]>;
+export declare function ensureFeatureSystem(projectRoot: string, options?: FeatureSystemAccessOptions): Promise<ActiveFeatureMeta>;
+export declare function readFeatureWorktreeRegistry(projectRoot: string, options?: FeatureSystemAccessOptions): Promise<FeatureWorktreeRegistry>;
+export declare function readActiveFeature(projectRoot: string, options?: FeatureSystemAccessOptions): Promise<string>;
+export declare function listFeatures(projectRoot: string, options?: FeatureSystemAccessOptions): Promise<string[]>;
 export declare function syncActiveFeatureSnapshot(projectRoot: string): Promise<void>;
 export declare function switchActiveFeature(projectRoot: string, featureId: string): Promise<ActiveFeatureMeta>;
 export declare function createFeature(projectRoot: string, rawFeatureId: string, options?: CreateFeatureOptions): Promise<string>;

package/dist/feature-system.js

@@ -278,20 +278,64 @@ async function ensureRegistryState(projectRoot) {
     await writeActiveFeatureMeta(projectRoot, activeMeta);
     return { registry, activeMeta };
 }
-export async function ensureFeatureSystem(projectRoot) {
-    const { activeMeta } = await ensureRegistryState(projectRoot);
+async function readRegistryStateReadonly(projectRoot) {
+    const currentRegistry = await readRegistry(projectRoot);
+    const entries = [...currentRegistry.entries];
+    const gitRepo = await isGitRepository(projectRoot);
+    const source = gitRepo ? "git-worktree" : "workspace";
+    const branch = gitRepo ? await currentBranch(projectRoot) : "workspace/default";
+    if (!entries.some((entry) => entry.featureId === DEFAULT_FEATURE_ID)) {
+        entries.push(buildDefaultEntry(source, branch));
+    }
+    const legacyFeatureIds = await listLegacySnapshotIds(projectRoot);
+    for (const legacyId of legacyFeatureIds) {
+        if (entries.some((entry) => entry.featureId === legacyId)) {
+            continue;
+        }
+        entries.push({
+            featureId: legacyId,
+            branch: `legacy/${legacyId}`,
+            path: `${LEGACY_FEATURES_DIR_REL_PATH}/${legacyId}`,
+            source: "legacy-snapshot",
+            createdAt: new Date().toISOString()
+        });
+    }
+    const registry = {
+        schemaVersion: WORKTREE_REGISTRY_SCHEMA_VERSION,
+        updatedAt: currentRegistry.updatedAt,
+        entries: dedupeEntries(entries)
+    };
+    const active = await readActiveFeatureMetaInternal(projectRoot);
+    return {
+        registry,
+        activeMeta: {
+            activeFeature: registryHasFeature(registry, active.activeFeature)
+                ? active.activeFeature
+                : DEFAULT_FEATURE_ID,
+            updatedAt: active.updatedAt
+        }
+    };
+}
+async function resolveFeatureSystemState(projectRoot, options = {}) {
+    if (options.repair === false) {
+        return readRegistryStateReadonly(projectRoot);
+    }
+    return ensureRegistryState(projectRoot);
+}
+export async function ensureFeatureSystem(projectRoot, options = {}) {
+    const { activeMeta } = await resolveFeatureSystemState(projectRoot, options);
     return activeMeta;
 }
-export async function readFeatureWorktreeRegistry(projectRoot) {
-    const { registry } = await ensureRegistryState(projectRoot);
+export async function readFeatureWorktreeRegistry(projectRoot, options = {}) {
+    const { registry } = await resolveFeatureSystemState(projectRoot, options);
     return registry;
 }
-export async function readActiveFeature(projectRoot) {
-    const meta = await ensureFeatureSystem(projectRoot);
+export async function readActiveFeature(projectRoot, options = {}) {
+    const meta = await ensureFeatureSystem(projectRoot, options);
     return normalizedFeatureId(meta.activeFeature);
 }
-export async function listFeatures(projectRoot) {
-    const registry = await readFeatureWorktreeRegistry(projectRoot);
+export async function listFeatures(projectRoot, options = {}) {
+    const registry = await readFeatureWorktreeRegistry(projectRoot, options);
     return registry.entries.map((entry) => entry.featureId).sort((a, b) => a.localeCompare(b));
 }
 export async function syncActiveFeatureSnapshot(projectRoot) {

package/dist/flow-state.d.ts

@@ -92,8 +92,10 @@ export declare function isFlowTrack(value: unknown): value is FlowTrack;
 export declare function trackStages(track: FlowTrack): FlowStage[];
 export declare function skippedStagesForTrack(track: FlowTrack): FlowStage[];
 export declare function firstStageForTrack(track: FlowTrack): FlowStage;
+export declare function createRunId(date?: Date): string;
 export declare function createInitialFlowState(activeRunIdOrOptions?: string | InitialFlowStateOptions, maybeTrack?: FlowTrack): FlowState;
 export declare function canTransition(from: FlowStage, to: FlowStage): boolean;
+export declare function getAvailableTransitions(from: FlowStage, track?: FlowTrack): TransitionRule[];
 export declare function getTransitionGuards(from: FlowStage, to: FlowStage, track?: FlowTrack): string[];
 export declare function nextStage(stage: FlowStage, track?: FlowTrack): FlowStage | null;
 export declare function previousStage(stage: FlowStage, track?: FlowTrack): FlowStage | null;

package/dist/flow-state.js

@@ -58,11 +58,14 @@ export function firstStageForTrack(track) {
     const stages = TRACK_STAGES[track];
     return stages[0] ?? "brainstorm";
 }
-export function createInitialFlowState(activeRunIdOrOptions = "active", maybeTrack) {
+export function createRunId(date = new Date()) {
+    return `run-${date.getTime().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+export function createInitialFlowState(activeRunIdOrOptions = {}, maybeTrack) {
     const options = typeof activeRunIdOrOptions === "string"
         ? { activeRunId: activeRunIdOrOptions, track: maybeTrack }
         : activeRunIdOrOptions;
-    const activeRunId = options.activeRunId ?? "active";
+    const activeRunId = options.activeRunId ?? createRunId();
     const track = options.track ?? "standard";
     const skippedStages = skippedStagesForTrack(track);
     const stageGateCatalog = {};
@@ -97,6 +100,20 @@ export function createInitialFlowState(activeRunIdOrOptions = "active", maybeTra
 export function canTransition(from, to) {
     return TRANSITION_RULES.some((rule) => rule.from === from && rule.to === to);
 }
+export function getAvailableTransitions(from, track = "standard") {
+    const natural = nextStage(from, track);
+    const fromRules = TRANSITION_RULES.filter((rule) => rule.from === from);
+    if (!natural) {
+        return fromRules;
+    }
+    return fromRules.sort((a, b) => {
+        if (a.to === natural && b.to !== natural)
+            return -1;
+        if (b.to === natural && a.to !== natural)
+            return 1;
+        return a.to.localeCompare(b.to);
+    });
+}
 export function getTransitionGuards(from, to, track = "standard") {
     // Natural forward edge on this track: derive guards fresh from the
     // track-specific gate schema. `TRANSITION_RULES` collapses shared edges

package/dist/fs-utils.js

@@ -27,6 +27,7 @@ export async function withDirectoryLock(lockPath, fn, options = {}) {
     const staleAfterMs = options.staleAfterMs ?? 60_000;
     await ensureDir(path.dirname(lockPath));
     let acquired = false;
+    let lastError = null;
     for (let attempt = 0; attempt < retries; attempt += 1) {
         try {
             await fs.mkdir(lockPath);
@@ -34,6 +35,7 @@ export async function withDirectoryLock(lockPath, fn, options = {}) {
             break;
         }
         catch (error) {
+            lastError = error;
             const code = error?.code;
             if (code !== "EEXIST") {
                 throw error;
@@ -52,13 +54,20 @@ export async function withDirectoryLock(lockPath, fn, options = {}) {
         }
     }
     if (!acquired) {
-        throw new Error(`Failed to acquire lock: ${lockPath}`);
+        const details = lastError instanceof Error ? lastError.message : String(lastError);
+        throw new Error(`Failed to acquire lock: ${lockPath} (attempts=${retries}, retryDelayMs=${retryDelayMs}, staleAfterMs=${staleAfterMs}, lastError=${details})`);
     }
     try {
         return await fn();
     }
     finally {
-        await fs.rm(lockPath, { recursive: true, force: true }).catch(() => { });
+        await fs.rm(lockPath, { recursive: true, force: true }).catch((cleanupError) => {
+            // Lock cleanup failure should not shadow the original operation result,
+            // but keep a diagnostic breadcrumb for flaky FS environments.
+            const details = cleanupError instanceof Error ? cleanupError.message : String(cleanupError);
+            // eslint-disable-next-line no-console
+            console.warn(`cclaw lock cleanup failed for ${lockPath}: ${details}`);
+        });
     }
 }
 export async function writeFileSafe(filePath, content) {

package/dist/gate-evidence.d.ts

@@ -41,6 +41,8 @@ export interface ReconciliationNotice {
 export interface ReconciliationNoticesPayload {
     schemaVersion: number;
     notices: ReconciliationNotice[];
+    parseOk: boolean;
+    schemaOk: boolean;
 }
 export interface ReconciliationNoticeBuckets {
     activeBlocked: ReconciliationNotice[];

package/dist/gate-evidence.js

@@ -72,7 +72,9 @@ function reconciliationNoticesPath(projectRoot) {
 function defaultReconciliationNoticesPayload() {
     return {
         schemaVersion: RECONCILIATION_NOTICES_SCHEMA_VERSION,
-        notices: []
+        notices: [],
+        parseOk: true,
+        schemaOk: true
     };
 }
 function sanitizeReconciliationNotice(raw) {
@@ -104,6 +106,7 @@ export async function readReconciliationNotices(projectRoot) {
     }
     try {
         const raw = JSON.parse(await fs.readFile(filePath, "utf8"));
+        const schemaOk = raw.schemaVersion === RECONCILIATION_NOTICES_SCHEMA_VERSION;
         const notices = Array.isArray(raw.notices)
             ? raw.notices
                 .map((value) => sanitizeReconciliationNotice(value))
@@ -111,11 +114,17 @@ export async function readReconciliationNotices(projectRoot) {
             : [];
         return {
             schemaVersion: RECONCILIATION_NOTICES_SCHEMA_VERSION,
-            notices
+            notices,
+            parseOk: true,
+            schemaOk
         };
     }
     catch {
-        return defaultReconciliationNoticesPayload();
+        return {
+            ...defaultReconciliationNoticesPayload(),
+            parseOk: false,
+            schemaOk: false
+        };
     }
 }
 async function writeReconciliationNotices(projectRoot, payload) {

package/dist/install.js

@@ -977,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) {

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/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,127 +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
-            }
-        };
-        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`);
-    let artifactsMoved = false;
-    try {
-        await fs.rename(artifactsDir, archiveArtifactsPath);
-        artifactsMoved = true;
+    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 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 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 });
+        }
+        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);
+        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.
+                }
             }
-            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;
         }
-        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

@@ -277,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()
@@ -333,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();
@@ -375,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 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "0.48.1",
+  "version": "0.48.2",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {