cclaw-cli 7.7.1 → 8.1.0

package/dist/run-persistence.js

@@ -1,856 +1,40 @@
-import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { RUNTIME_ROOT } from "./constants.js";
-import { nextStage, createInitialCloseoutState, createInitialFlowState, FLOW_STATE_SCHEMA_VERSION, isDiscoveryMode, isFlowTrack, skippedStagesForTrack, SHIP_SUBSTATES } from "./flow-state.js";
-import { ensureDir, exists, withDirectoryLock, writeFileSafe } from "./fs-utils.js";
-import { FLOW_STAGES } from "./types.js";
-export class InvalidStageTransitionError extends Error {
-    from;
-    to;
-    constructor(from, to, message) {
-        super(message);
-        this.from = from;
-        this.to = to;
-        this.name = "InvalidStageTransitionError";
-    }
-}
-const FLOW_STATE_REL_PATH = `${RUNTIME_ROOT}/state/flow-state.json`;
-const FLOW_STATE_GUARD_REL_PATH = `${RUNTIME_ROOT}/.flow-state.guard.json`;
-const FLOW_STATE_REPAIR_LOG_REL_PATH = `${RUNTIME_ROOT}/.flow-state-repair.log`;
-const ARCHIVE_DIR_REL_PATH = `${RUNTIME_ROOT}/archive`;
-const ACTIVE_ARTIFACTS_REL_PATH = `${RUNTIME_ROOT}/artifacts`;
-const FLOW_STAGE_SET = new Set(FLOW_STAGES);
-const DEFAULT_WRITER_SUBSYSTEM = "cclaw-cli";
-const DEFAULT_REPAIR_REASON_PATTERN = /^[a-z][a-z0-9_-]{2,}$/u;
-export class FlowStateGuardMismatchError extends Error {
-    expectedSha;
-    actualSha;
-    lastWriter;
-    writtenAt;
-    runId;
-    statePath;
-    guardPath;
-    repairCommand;
-    constructor(details) {
-        super(`flow-state guard mismatch: ${details.runId}\n` +
-            `expected sha: ${details.expectedSha}\n` +
-            `actual sha:   ${details.actualSha}\n` +
-            `last writer:  ${details.lastWriter}@${details.writtenAt}\n` +
-            `do not edit flow-state.json by hand. To recover, run:\n` +
-            `  ${details.repairCommand}`);
-        this.name = "FlowStateGuardMismatchError";
-        this.expectedSha = details.expectedSha;
-        this.actualSha = details.actualSha;
-        this.lastWriter = details.lastWriter;
-        this.writtenAt = details.writtenAt;
-        this.runId = details.runId;
-        this.statePath = details.statePath;
-        this.guardPath = details.guardPath;
-        this.repairCommand = details.repairCommand;
-    }
-}
-function canonicalFlowStateShaFromRaw(raw) {
-    return createHash("sha256").update(raw, "utf8").digest("hex");
-}
-function guardSidecarPath(projectRoot) {
-    return path.join(projectRoot, FLOW_STATE_GUARD_REL_PATH);
-}
-function repairLogPath(projectRoot) {
-    return path.join(projectRoot, FLOW_STATE_REPAIR_LOG_REL_PATH);
-}
-function validateFlowTransition(prev, next) {
-    if (prev.activeRunId !== next.activeRunId) {
-        // 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.`);
-    }
-    if (prev.discoveryMode !== next.discoveryMode) {
-        throw new InvalidStageTransitionError(prev.currentStage, next.currentStage, `cannot change discoveryMode from "${prev.discoveryMode}" to "${next.discoveryMode}" mid-run (activeRunId="${prev.activeRunId}"). Reclassify through start-flow or start a new run.`);
-    }
-    const newRewind = next.rewinds.length === prev.rewinds.length + 1
-        ? next.rewinds[next.rewinds.length - 1]
-        : undefined;
-    const isManagedRewind = newRewind !== undefined
-        && newRewind.fromStage === prev.currentStage
-        && newRewind.toStage === next.currentStage
-        && newRewind.invalidatedStages.includes(next.currentStage);
-    const removedCompletedStages = prev.completedStages.filter((stage) => !next.completedStages.includes(stage));
-    if (removedCompletedStages.length > 0 && !isManagedRewind) {
-        throw new InvalidStageTransitionError(prev.currentStage, next.currentStage, `completedStages must be monotonic: stage(s) ${removedCompletedStages.map((stage) => `"${stage}"`).join(", ")} were previously completed but are missing from the new state.`);
-    }
-    if (isManagedRewind) {
-        const invalidated = new Set(newRewind.invalidatedStages);
-        const unexpectedRemoved = removedCompletedStages.filter((stage) => !invalidated.has(stage));
-        const missingMarkers = newRewind.invalidatedStages.filter((stage) => {
-            const marker = next.staleStages[stage];
-            return !marker || marker.rewindId !== newRewind.id;
-        });
-        if (unexpectedRemoved.length > 0 || missingMarkers.length > 0) {
-            throw new InvalidStageTransitionError(prev.currentStage, next.currentStage, `managed rewind state is inconsistent: unexpectedRemoved=${unexpectedRemoved.join(",") || "none"}; missingMarkers=${missingMarkers.join(",") || "none"}.`);
-        }
-        return;
-    }
-    if (prev.currentStage === next.currentStage) {
-        return;
-    }
-    const naturalForward = nextStage(prev.currentStage, prev.track);
-    const isNaturalForward = naturalForward === next.currentStage;
-    const isReviewRewind = prev.currentStage === "review" && next.currentStage === "tdd";
-    if (!isNaturalForward && !isReviewRewind) {
-        throw new InvalidStageTransitionError(prev.currentStage, next.currentStage, `no transition rule allows "${prev.currentStage}" -> "${next.currentStage}" for track "${prev.track}". Use /cc to advance stages or archive the run to reset.`);
-    }
-}
-function flowStatePath(projectRoot) {
+import { FLOW_STATE_REL_PATH, RUNTIME_ROOT } from "./constants.js";
+import { assertFlowStateV8, createInitialFlowStateV8 } from "./flow-state.js";
+import { ensureDir, exists, writeFileSafe } from "./fs-utils.js";
+export function flowStatePath(projectRoot) {
     return path.join(projectRoot, FLOW_STATE_REL_PATH);
 }
-function flowStateLockPath(projectRoot) {
-    return path.join(projectRoot, RUNTIME_ROOT, "state", ".flow-state.lock");
-}
-function archiveRoot(projectRoot) {
-    return path.join(projectRoot, ARCHIVE_DIR_REL_PATH);
-}
-function activeArtifactsPath(projectRoot) {
-    return path.join(projectRoot, ACTIVE_ARTIFACTS_REL_PATH);
-}
-function isFlowStage(value) {
-    return typeof value === "string" && FLOW_STAGE_SET.has(value);
-}
-function sanitizeStringArray(value) {
-    if (!Array.isArray(value)) {
-        return [];
-    }
-    return value.filter((item) => typeof item === "string" && item.trim().length > 0);
-}
-function sanitizeCompletedStages(value) {
-    if (!Array.isArray(value)) {
-        return [];
-    }
-    const unique = new Set();
-    const stages = [];
-    for (const item of value) {
-        if (isFlowStage(item) && !unique.has(item)) {
-            unique.add(item);
-            stages.push(item);
-        }
-    }
-    return stages;
-}
-function sanitizeGuardEvidence(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
-        return {};
-    }
-    const next = {};
-    for (const [key, raw] of Object.entries(value)) {
-        if (typeof raw === "string") {
-            next[key] = raw;
-        }
-    }
-    return next;
-}
-function sanitizeStageGateCatalog(value, fallback) {
-    const uniqueStrings = (items) => [...new Set(items)];
-    const next = {};
-    for (const stage of FLOW_STAGES) {
-        const base = fallback[stage];
-        next[stage] = {
-            required: [...base.required],
-            recommended: [...base.recommended],
-            conditional: [...base.conditional],
-            triggered: [...base.triggered],
-            passed: [...base.passed],
-            blocked: [...base.blocked]
-        };
-    }
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
-        return next;
-    }
-    const rawCatalog = value;
-    for (const stage of FLOW_STAGES) {
-        const rawStage = rawCatalog[stage];
-        if (!rawStage || typeof rawStage !== "object" || Array.isArray(rawStage)) {
-            continue;
-        }
-        const typed = rawStage;
-        const stageState = next[stage];
-        const allowedGateIds = new Set([
-            ...stageState.required,
-            ...stageState.recommended,
-            ...stageState.conditional
-        ]);
-        const conditionalGateIds = new Set(stageState.conditional);
-        const passed = sanitizeStringArray(typed.passed).filter((gate) => allowedGateIds.has(gate));
-        const blocked = sanitizeStringArray(typed.blocked).filter((gate) => allowedGateIds.has(gate));
-        const triggeredFromState = sanitizeStringArray(typed.triggered).filter((gate) => conditionalGateIds.has(gate));
-        const touchedConditionals = [...passed, ...blocked].filter((gate) => conditionalGateIds.has(gate));
-        next[stage] = {
-            required: [...stageState.required],
-            recommended: [...stageState.recommended],
-            conditional: [...stageState.conditional],
-            triggered: uniqueStrings([...triggeredFromState, ...touchedConditionals]),
-            passed,
-            blocked
-        };
-    }
-    return next;
-}
-function coerceTrack(value) {
-    return isFlowTrack(value) ? value : "standard";
-}
-function coerceDiscoveryMode(value) {
-    if (typeof value === "string") {
-        const normalized = value.trim().toLowerCase();
-        if (isDiscoveryMode(normalized))
-            return normalized;
-    }
-    return "guided";
-}
-function coerceRepoSignals(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
-        return undefined;
-    }
-    const typed = value;
-    const fileCountRaw = typed.fileCount;
-    const fileCount = typeof fileCountRaw === "number" && Number.isFinite(fileCountRaw) && fileCountRaw >= 0
-        ? Math.min(Math.floor(fileCountRaw), 1_000_000)
-        : undefined;
-    const capturedAt = typeof typed.capturedAt === "string" ? typed.capturedAt.trim() : "";
-    if (fileCount === undefined || !capturedAt) {
-        return undefined;
-    }
-    return {
-        fileCount,
-        hasReadme: typed.hasReadme === true,
-        hasPackageManifest: typed.hasPackageManifest === true,
-        capturedAt
-    };
-}
-/**
- * preserve `flow-state.json#taskClass`
- * across read/write round-trips. Before this audit fix the persistence
- * layer silently dropped the field, which made the bugfix-skip
- * (`mandatoryAgentsFor` short-circuit) and the artifact-validation
- * demotion both dead in practice: the only entry point that classified
- * a run was the unit-test harness passing `options.taskClass` directly
- * to `checkMandatoryDelegations`. The accepted union mirrors
- * `MandatoryDelegationTaskClass` plus `null` so callers can explicitly
- * clear the classification without dropping the property.
- */
-function coerceTaskClass(value) {
-    if (value === undefined)
-        return undefined;
-    if (value === null)
-        return null;
-    if (value === "software-standard" ||
-        value === "software-trivial" ||
-        value === "software-bugfix") {
-        return value;
-    }
-    return undefined;
-}
-function sanitizeSkippedStages(value, track) {
-    const trackDefault = skippedStagesForTrack(track);
-    if (!Array.isArray(value)) {
-        return trackDefault;
-    }
-    const seen = new Set();
-    const out = [];
-    for (const raw of value) {
-        if (isFlowStage(raw) && !seen.has(raw)) {
-            seen.add(raw);
-            out.push(raw);
-        }
-    }
-    return out.length > 0 ? out : trackDefault;
-}
-function sanitizeStaleStages(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
-        return {};
-    }
-    const out = {};
-    for (const [stage, raw] of Object.entries(value)) {
-        if (!isFlowStage(stage))
-            continue;
-        if (!raw || typeof raw !== "object" || Array.isArray(raw))
-            continue;
-        const typed = raw;
-        const rewindId = typeof typed.rewindId === "string" ? typed.rewindId : "";
-        const reason = typeof typed.reason === "string" ? typed.reason : "";
-        const markedAt = typeof typed.markedAt === "string" ? typed.markedAt : "";
-        const acknowledgedAt = typeof typed.acknowledgedAt === "string" ? typed.acknowledgedAt : undefined;
-        if (!rewindId || !reason || !markedAt) {
-            continue;
-        }
-        out[stage] = {
-            rewindId,
-            reason,
-            markedAt,
-            acknowledgedAt
-        };
-    }
-    return out;
-}
-function sanitizeCompletedStageMeta(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
-        return undefined;
-    }
-    const out = {};
-    for (const [key, raw] of Object.entries(value)) {
-        if (!isFlowStage(key))
-            continue;
-        if (!raw || typeof raw !== "object" || Array.isArray(raw))
-            continue;
-        const record = raw;
-        const ca = typeof record.completedAt === "string" ? record.completedAt.trim() : "";
-        if (ca.length > 0) {
-            out[key] = { completedAt: ca };
-        }
-    }
-    return Object.keys(out).length > 0 ? out : undefined;
-}
-function sanitizeRewinds(value) {
-    if (!Array.isArray(value)) {
-        return [];
-    }
-    const out = [];
-    for (const raw of value) {
-        if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
-            continue;
-        }
-        const typed = raw;
-        if (typeof typed.id !== "string" ||
-            !isFlowStage(typed.fromStage) ||
-            !isFlowStage(typed.toStage) ||
-            typeof typed.reason !== "string" ||
-            typeof typed.timestamp !== "string") {
-            continue;
-        }
-        const invalidatedStages = Array.isArray(typed.invalidatedStages)
-            ? typed.invalidatedStages.filter((stage) => isFlowStage(stage))
-            : [];
-        out.push({
-            id: typed.id,
-            fromStage: typed.fromStage,
-            toStage: typed.toStage,
-            reason: typed.reason,
-            timestamp: typed.timestamp,
-            invalidatedStages
-        });
-    }
-    return out;
-}
-function sanitizeInteractionHints(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
-        return {};
-    }
-    const out = {};
-    for (const [stage, raw] of Object.entries(value)) {
-        if (!isFlowStage(stage))
-            continue;
-        if (!raw || typeof raw !== "object" || Array.isArray(raw))
-            continue;
-        const typed = raw;
-        const skipQuestions = typed.skipQuestions === true ? true : undefined;
-        const sourceStage = isFlowStage(typed.sourceStage) ? typed.sourceStage : undefined;
-        const recordedAt = typeof typed.recordedAt === "string" ? typed.recordedAt : undefined;
-        const fromIdeaArtifact = typeof typed.fromIdeaArtifact === "string" && typed.fromIdeaArtifact.trim().length > 0
-            ? typed.fromIdeaArtifact.trim()
-            : undefined;
-        const fromIdeaCandidateId = typeof typed.fromIdeaCandidateId === "string" && typed.fromIdeaCandidateId.trim().length > 0
-            ? typed.fromIdeaCandidateId.trim()
-            : undefined;
-        if (skipQuestions !== true &&
-            !sourceStage &&
-            !recordedAt &&
-            !fromIdeaArtifact &&
-            !fromIdeaCandidateId) {
-            continue;
-        }
-        out[stage] = {
-            ...(skipQuestions ? { skipQuestions } : {}),
-            ...(sourceStage ? { sourceStage } : {}),
-            ...(recordedAt ? { recordedAt } : {}),
-            ...(fromIdeaArtifact ? { fromIdeaArtifact } : {}),
-            ...(fromIdeaCandidateId ? { fromIdeaCandidateId } : {})
-        };
-    }
-    return out;
-}
-function sanitizeRetroState(value) {
-    const fallback = {
-        required: false,
-        completedAt: undefined,
-        compoundEntries: 0
-    };
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
-        return fallback;
-    }
-    const typed = value;
-    const required = typeof typed.required === "boolean" ? typed.required : false;
-    const completedAt = typeof typed.completedAt === "string" ? typed.completedAt : undefined;
-    const compoundEntriesRaw = typed.compoundEntries;
-    const compoundEntries = typeof compoundEntriesRaw === "number" && Number.isFinite(compoundEntriesRaw) && compoundEntriesRaw >= 0
-        ? Math.floor(compoundEntriesRaw)
-        : 0;
-    return {
-        required,
-        completedAt,
-        compoundEntries
-    };
-}
-function isShipSubstate(value) {
-    return typeof value === "string" && SHIP_SUBSTATES.includes(value);
-}
-function sanitizeCloseoutState(value) {
-    const fallback = createInitialCloseoutState();
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
-        return fallback;
-    }
-    const typed = value;
-    const rawShipSubstate = typeof typed.shipSubstate === "string" ? typed.shipSubstate : undefined;
-    let shipSubstate;
-    if (rawShipSubstate === "retro_review" || rawShipSubstate === "compound_review") {
-        shipSubstate = "post_ship_review";
-    }
-    else {
-        shipSubstate = isShipSubstate(rawShipSubstate) ? rawShipSubstate : fallback.shipSubstate;
-    }
-    const retroDraftedAt = typeof typed.retroDraftedAt === "string" ? typed.retroDraftedAt : undefined;
-    const retroAcceptedAt = typeof typed.retroAcceptedAt === "string" ? typed.retroAcceptedAt : undefined;
-    const retroSkipReason = typeof typed.retroSkipReason === "string"
-        ? typed.retroSkipReason.trim() || undefined
-        : undefined;
-    const retroSkipped = typed.retroSkipped === true && retroSkipReason !== undefined
-        ? true
-        : undefined;
-    const compoundCompletedAt = typeof typed.compoundCompletedAt === "string" ? typed.compoundCompletedAt : undefined;
-    const compoundSkipReason = typeof typed.compoundSkipReason === "string"
-        ? typed.compoundSkipReason.trim() || undefined
-        : undefined;
-    const compoundSkipped = typed.compoundSkipped === true && compoundSkipReason !== undefined
-        ? true
-        : undefined;
-    const promotedRaw = typed.compoundPromoted;
-    const compoundPromoted = typeof promotedRaw === "number" && Number.isFinite(promotedRaw) && promotedRaw >= 0
-        ? Math.floor(promotedRaw)
-        : 0;
-    // Demote shipSubstate when its closeout invariants are violated on disk. A
-    // hand-edited flow-state could claim `ready_to_archive` without completing
-    // the compound leg, which would let `archive` skip durable closeout proof.
-    const retroDone = retroAcceptedAt !== undefined || retroSkipped === true;
-    const compoundDone = compoundCompletedAt !== undefined || compoundPromoted > 0 || compoundSkipped === true;
-    if (shipSubstate === "ready_to_archive" && (!retroDone || !compoundDone)) {
-        shipSubstate = "post_ship_review";
-    }
-    return {
-        shipSubstate,
-        retroDraftedAt,
-        retroAcceptedAt,
-        retroSkipped,
-        retroSkipReason,
-        compoundCompletedAt,
-        compoundSkipped,
-        compoundSkipReason,
-        compoundPromoted
-    };
-}
-function coerceFlowState(parsed) {
-    const track = coerceTrack(parsed.track);
-    const discoveryMode = coerceDiscoveryMode(parsed.discoveryMode);
-    const next = createInitialFlowState({ track, discoveryMode });
-    const activeRunIdRaw = parsed.activeRunId;
-    const activeRunId = typeof activeRunIdRaw === "string" && activeRunIdRaw.trim().length > 0
-        ? activeRunIdRaw.trim()
-        : next.activeRunId;
-    const taskClass = coerceTaskClass(parsed.taskClass);
-    const repoSignals = coerceRepoSignals(parsed.repoSignals);
-    const completedStageMeta = sanitizeCompletedStageMeta(parsed.completedStageMeta);
-    const tddGreenMinElapsedMs = coerceTddGreenMinElapsedMs(parsed.tddGreenMinElapsedMs);
-    const packageVersion = typeof parsed.packageVersion === "string" && parsed.packageVersion.trim().length > 0
-        ? parsed.packageVersion.trim()
-        : undefined;
-    const state = {
-        schemaVersion: FLOW_STATE_SCHEMA_VERSION,
-        activeRunId,
-        currentStage: isFlowStage(parsed.currentStage) ? parsed.currentStage : next.currentStage,
-        completedStages: sanitizeCompletedStages(parsed.completedStages),
-        guardEvidence: sanitizeGuardEvidence(parsed.guardEvidence),
-        stageGateCatalog: sanitizeStageGateCatalog(parsed.stageGateCatalog, next.stageGateCatalog),
-        track,
-        discoveryMode,
-        ...(taskClass !== undefined ? { taskClass } : {}),
-        ...(repoSignals ? { repoSignals } : {}),
-        ...(completedStageMeta ? { completedStageMeta } : {}),
-        ...(tddGreenMinElapsedMs !== undefined ? { tddGreenMinElapsedMs } : {}),
-        ...(packageVersion ? { packageVersion } : {}),
-        skippedStages: sanitizeSkippedStages(parsed.skippedStages, track),
-        staleStages: sanitizeStaleStages(parsed.staleStages),
-        rewinds: sanitizeRewinds(parsed.rewinds),
-        interactionHints: sanitizeInteractionHints(parsed.interactionHints),
-        retro: sanitizeRetroState(parsed.retro),
-        closeout: sanitizeCloseoutState(parsed.closeout)
-    };
-    return { state };
-}
-/**
- * coerce `tddGreenMinElapsedMs` from disk. Mirrors the
- * defensive read in `effectiveTddGreenMinElapsedMs`: numbers ≥ 0 round
- * down to integers; everything else (NaN, strings, negatives) returns
- * undefined so the field is omitted from the rehydrated state and the
- * effective getter falls back to the documented 4000ms default.
- */
-function coerceTddGreenMinElapsedMs(value) {
-    if (typeof value !== "number")
-        return undefined;
-    if (!Number.isFinite(value))
-        return undefined;
-    if (value < 0)
-        return undefined;
-    return Math.floor(value);
-}
-export class CorruptFlowStateError extends Error {
-    statePath;
-    quarantinedPath;
-    constructor(statePath, quarantinedPath, cause) {
-        super(`Corrupt flow-state.json detected at ${statePath}. ` +
-            `Quarantined to ${quarantinedPath}. ` +
-            `Inspect the quarantined file, reconcile by hand, then re-run your command ` +
-            `or delete ${statePath} to start over. ` +
-            `Underlying error: ${cause instanceof Error ? cause.message : String(cause)}`);
-        this.name = "CorruptFlowStateError";
-        this.statePath = statePath;
-        this.quarantinedPath = quarantinedPath;
-        if (cause instanceof Error) {
-            this.cause = cause;
-        }
-    }
-}
-function quarantineTimestamp(date = new Date()) {
-    return date.toISOString().replace(/[:.]/gu, "-");
-}
-async function quarantineCorruptState(statePath, cause) {
-    const quarantinedPath = `${statePath}.corrupt-${quarantineTimestamp()}.json`;
-    try {
-        await fs.rename(statePath, quarantinedPath);
-    }
-    catch (renameErr) {
-        try {
-            const raw = await fs.readFile(statePath, "utf8");
-            await fs.writeFile(quarantinedPath, raw, "utf8");
-            await fs.unlink(statePath).catch(() => undefined);
-        }
-        catch {
-            throw new CorruptFlowStateError(statePath, quarantinedPath, renameErr);
-        }
-    }
-    throw new CorruptFlowStateError(statePath, quarantinedPath, cause);
-}
-function buildRepairCommand(reason = "<manual_edit_recovery>") {
-    return `cclaw-cli internal flow-state-repair --reason "${reason}"`;
-}
-async function readGuardSidecar(projectRoot) {
-    const guardPath = guardSidecarPath(projectRoot);
-    try {
-        const raw = await fs.readFile(guardPath, "utf8");
-        const parsed = JSON.parse(raw);
-        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-            return null;
-        }
-        const sha256 = typeof parsed.sha256 === "string" ? parsed.sha256 : "";
-        const writtenAt = typeof parsed.writtenAt === "string" ? parsed.writtenAt : "";
-        const writerSubsystem = typeof parsed.writerSubsystem === "string" ? parsed.writerSubsystem : "";
-        const runId = typeof parsed.runId === "string" ? parsed.runId : "";
-        if (!sha256 || !writtenAt || !writerSubsystem || !runId) {
-            return null;
-        }
-        return { sha256, writtenAt, writerSubsystem, runId };
-    }
-    catch {
-        return null;
-    }
-}
-async function verifyFlowStateGuardFromRaw(projectRoot, statePath, rawContents) {
-    const sidecar = await readGuardSidecar(projectRoot);
-    if (!sidecar) {
-        // Legacy: flow-state.json was written by a pre-guard runtime, or sidecar
-        // was intentionally reset. Permit the read so existing projects keep
-        // working; the next legitimate stage-complete writes a fresh sidecar.
-        return;
-    }
-    const actualSha = canonicalFlowStateShaFromRaw(rawContents);
-    if (actualSha === sidecar.sha256) {
-        return;
-    }
-    throw new FlowStateGuardMismatchError({
-        expectedSha: sidecar.sha256,
-        actualSha,
-        lastWriter: sidecar.writerSubsystem,
-        writtenAt: sidecar.writtenAt,
-        runId: sidecar.runId,
-        statePath,
-        guardPath: guardSidecarPath(projectRoot),
-        repairCommand: buildRepairCommand("manual_edit_recovery")
-    });
-}
-/**
- * Verify the on-disk flow-state against the sha256 sidecar. Throws
- * `FlowStateGuardMismatchError` when manual editing is detected. Safe to
- * call on projects that have never written a sidecar: a missing sidecar is
- * treated as "legacy runtime" and the check silently succeeds.
- */
-export async function verifyFlowStateGuard(projectRoot) {
-    const statePath = flowStatePath(projectRoot);
-    if (!(await exists(statePath)))
-        return;
-    let raw;
-    try {
-        raw = await fs.readFile(statePath, "utf8");
-    }
-    catch {
-        return;
-    }
-    await verifyFlowStateGuardFromRaw(projectRoot, statePath, raw);
-}
-export async function readFlowState(projectRoot, options = {}) {
-    void options;
+export async function ensureRunSystem(projectRoot) {
+    await ensureDir(path.join(projectRoot, RUNTIME_ROOT, "state"));
     const statePath = flowStatePath(projectRoot);
     if (!(await exists(statePath))) {
-        return createInitialFlowState();
-    }
-    let raw;
-    try {
-        raw = await fs.readFile(statePath, "utf8");
-    }
-    catch (readErr) {
-        throw new CorruptFlowStateError(statePath, statePath, readErr);
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch (parseErr) {
-        await quarantineCorruptState(statePath, parseErr);
-    }
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-        await quarantineCorruptState(statePath, new Error("flow-state.json did not deserialize to a JSON object"));
-    }
-    return coerceFlowState(parsed).state;
-}
-/**
- * Guarded read wrapper used by runtime hook scripts and the repair CLI.
- * Unlike `readFlowState`, it enforces the sha256 sidecar before returning:
- * a manual edit to flow-state.json fails fast with
- * `FlowStateGuardMismatchError`.
- */
-export async function readFlowStateGuarded(projectRoot, options = {}) {
-    void options;
-    const statePath = flowStatePath(projectRoot);
-    if (!(await exists(statePath))) {
-        return createInitialFlowState();
-    }
-    let raw;
-    try {
-        raw = await fs.readFile(statePath, "utf8");
-    }
-    catch (readErr) {
-        throw new CorruptFlowStateError(statePath, statePath, readErr);
-    }
-    await verifyFlowStateGuardFromRaw(projectRoot, statePath, raw);
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch (parseErr) {
-        await quarantineCorruptState(statePath, parseErr);
-    }
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-        await quarantineCorruptState(statePath, new Error("flow-state.json did not deserialize to a JSON object"));
-    }
-    return coerceFlowState(parsed).state;
-}
-export async function writeFlowState(projectRoot, state, options = {}) {
-    const writerSubsystem = options.writerSubsystem?.trim() || DEFAULT_WRITER_SUBSYSTEM;
-    const doWrite = async () => {
-        const statePath = flowStatePath(projectRoot);
-        if (!options.allowReset && (await exists(statePath))) {
-            try {
-                const rawExisting = await fs.readFile(statePath, "utf8");
-                const parsed = JSON.parse(rawExisting);
-                if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-                    const prev = coerceFlowState(parsed).state;
-                    validateFlowTransition(prev, state);
-                }
-            }
-            catch (err) {
-                if (err instanceof InvalidStageTransitionError) {
-                    throw err;
-                }
-                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 \`npx cclaw-cli sync\` and reconcile the state before retrying.`);
-            }
-        }
-        const safe = coerceFlowState({ ...state }).state;
-        const canonicalPayload = `${JSON.stringify(safe, null, 2)}\n`;
-        const sha256 = canonicalFlowStateShaFromRaw(canonicalPayload);
-        await writeFileSafe(statePath, canonicalPayload, { mode: 0o600 });
-        const sidecar = {
-            sha256,
-            writtenAt: new Date().toISOString(),
-            writerSubsystem,
-            runId: safe.activeRunId
-        };
-        await writeFileSafe(guardSidecarPath(projectRoot), `${JSON.stringify(sidecar, null, 2)}\n`, { mode: 0o600 });
-    };
-    if (options.skipLock) {
-        await doWrite();
-    }
-    else {
-        await withDirectoryLock(flowStateLockPath(projectRoot), doWrite);
+        await writeFlowState(projectRoot, createInitialFlowStateV8());
     }
 }
-/**
- * Named entry point for the write-guard workstream. Equivalent to
- * `writeFlowState`: the write always produces the sha256 sidecar via
- * the internal implementation so every existing writer inherits the
- * guard without rewriting callsites.
- */
-export async function writeFlowStateGuarded(projectRoot, state, options = {}) {
-    await writeFlowState(projectRoot, state, options);
-}
-/**
- * backfill missing `completedStageMeta` rows for any stage that
- * already lives in `completedStages` but has no audit timestamp. Uses the
- * stage's artifact mtime when available, otherwise the current time. This
- * runs as part of `flow-state-repair` so older flow-state.json files
- * get their meta carried forward without a destructive rewrite.
- */
-async function backfillCompletedStageMeta(projectRoot, state) {
-    const meta = { ...(state.completedStageMeta ?? {}) };
-    const backfilled = [];
-    for (const stage of state.completedStages) {
-        if (meta[stage] && typeof meta[stage].completedAt === "string" && meta[stage].completedAt.length > 0) {
-            continue;
-        }
-        let completedAt = new Date().toISOString();
-        try {
-            const { resolveArtifactPath } = await import("./artifact-paths.js");
-            const resolved = await resolveArtifactPath(stage, {
-                projectRoot,
-                track: state.track,
-                intent: "read"
-            });
-            const stat = await fs.stat(resolved.absPath);
-            completedAt = new Date(stat.mtimeMs).toISOString();
-        }
-        catch {
-            // artifact missing or unreadable — fall back to "now" so the meta row
-            // is at least consistently populated; operators can re-edit if needed.
-        }
-        meta[stage] = { completedAt };
-        backfilled.push(stage);
-    }
-    if (backfilled.length === 0) {
-        return { state, backfilled };
-    }
-    return { state: { ...state, completedStageMeta: meta }, backfilled };
-}
-/**
- * Recompute the write-guard sidecar from the current on-disk flow-state
- * contents and append an audit entry to `.cclaw/.flow-state-repair.log`.
- * The reason is required so no repair happens without an operator-visible
- * rationale. Intended to be called only from the explicit
- * `cclaw-cli internal flow-state-repair` subcommand.
- */
-export async function repairFlowStateGuard(projectRoot, reason) {
-    const trimmed = reason.trim();
-    if (trimmed.length === 0) {
-        throw new Error("flow-state-repair requires --reason=<slug> (e.g. --reason=\"manual_edit_recovery\").");
-    }
-    if (!DEFAULT_REPAIR_REASON_PATTERN.test(trimmed)) {
-        throw new Error("flow-state-repair --reason must match /^[a-z][a-z0-9_-]{2,}$/ (short lowercase slug).");
-    }
+export async function readFlowState(projectRoot) {
     const statePath = flowStatePath(projectRoot);
     if (!(await exists(statePath))) {
-        throw new Error(`flow-state-repair: ${FLOW_STATE_REL_PATH} does not exist; nothing to repair.`);
-    }
-    return withDirectoryLock(flowStateLockPath(projectRoot), async () => {
-        let raw = await fs.readFile(statePath, "utf8");
-        let runId = "unknown-run";
-        let backfilledStages = [];
-        try {
-            const parsed = JSON.parse(raw);
-            const coerced = coerceFlowState(parsed).state;
-            runId = coerced.activeRunId;
-            const { state: nextState, backfilled } = await backfillCompletedStageMeta(projectRoot, coerced);
-            backfilledStages = backfilled;
-            if (backfilled.length > 0) {
-                // Persist the migrated state inside the same lock window so the
-                // sha sidecar below covers the post-migration bytes, not the
-                // pre-migration ones.
-                await writeFlowState(projectRoot, nextState, {
-                    allowReset: true,
-                    skipLock: true,
-                    writerSubsystem: "flow-state-repair-backfill"
-                });
-                raw = await fs.readFile(statePath, "utf8");
-            }
-        }
-        catch {
-            // parsing failure falls back to "unknown-run"; repair intentionally
-            // accepts the contents as-is so operators can recover even from
-            // borderline JSON after manual edits.
-        }
-        const sha256 = canonicalFlowStateShaFromRaw(raw);
-        const sidecar = {
-            sha256,
-            writtenAt: new Date().toISOString(),
-            writerSubsystem: "flow-state-repair",
-            runId
-        };
-        const guardPath = guardSidecarPath(projectRoot);
-        await writeFileSafe(guardPath, `${JSON.stringify(sidecar, null, 2)}\n`, { mode: 0o600 });
-        const logPath = repairLogPath(projectRoot);
-        await ensureDir(path.dirname(logPath));
-        const backfillNote = backfilledStages.length > 0
-            ? ` backfilledCompletedStageMeta=${backfilledStages.join(",")}`
-            : "";
-        const logLine = `${sidecar.writtenAt} reason=${trimmed} runId=${sidecar.runId} sha256=${sidecar.sha256}${backfillNote}\n`;
-        await fs.appendFile(logPath, logLine, "utf8");
-        return {
-            sidecar,
-            repairLogPath: logPath,
-            guardPath,
-            completedStageMetaBackfilled: backfilledStages
-        };
-    });
-}
-export function flowStateGuardSidecarPathFor(projectRoot) {
-    return guardSidecarPath(projectRoot);
-}
-export function flowStateRepairLogPathFor(projectRoot) {
-    return repairLogPath(projectRoot);
-}
-/**
- * Exposed path helper so callers that need to serialize a multi-step
- * state operation with flow-state writes (e.g. run archival) can
- * acquire the SAME lock directory used internally by `writeFlowState`.
- */
-export function flowStateLockPathFor(projectRoot) {
-    return flowStateLockPath(projectRoot);
-}
-export async function ensureRunSystem(projectRoot, options = {}) {
-    await ensureDir(archiveRoot(projectRoot));
-    await ensureDir(activeArtifactsPath(projectRoot));
-    const statePath = flowStatePath(projectRoot);
-    const state = await readFlowState(projectRoot);
-    const createIfMissing = options.createIfMissing !== false;
-    if (createIfMissing && !(await exists(statePath))) {
-        await writeFlowState(projectRoot, state, { allowReset: true });
-    }
-    return state;
+        const initial = createInitialFlowStateV8();
+        await writeFlowState(projectRoot, initial);
+        return initial;
+    }
+    const raw = await fs.readFile(statePath, "utf8");
+    const parsed = JSON.parse(raw);
+    assertFlowStateV8(parsed);
+    return parsed;
+}
+export async function writeFlowState(projectRoot, state) {
+    assertFlowStateV8(state);
+    await writeFileSafe(flowStatePath(projectRoot), `${JSON.stringify(state, null, 2)}\n`);
+}
+export async function resetFlowState(projectRoot) {
+    await writeFlowState(projectRoot, createInitialFlowStateV8());
+}
+export async function patchFlowState(projectRoot, patch) {
+    const current = await readFlowState(projectRoot);
+    const next = { ...current, ...patch };
+    await writeFlowState(projectRoot, next);
+    return next;
 }