cclaw-cli 6.6.0 → 6.7.0

package/dist/internal/waiver-grant.js

@@ -0,0 +1,294 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { RUNTIME_ROOT } from "../constants.js";
+import { ensureDir, exists, withDirectoryLock, writeFileSafe } from "../fs-utils.js";
+import { FLOW_STAGES } from "../types.js";
+/**
+ * Tokens issued by `cclaw internal waiver-grant` live under the runtime
+ * root. The ledger also tracks `consumed[]` entries so consumption is
+ * traceable and one-shot.
+ */
+const WAIVER_LEDGER_REL_PATH = `${RUNTIME_ROOT}/.waivers.json`;
+const WAIVER_LEDGER_LOCK_REL_PATH = `${RUNTIME_ROOT}/.waivers.json.lock`;
+export const WAIVER_TOKEN_DEFAULT_TTL_MINUTES = 30;
+export const WAIVER_TOKEN_MAX_TTL_MINUTES = 120;
+export const WAIVER_REASON_PATTERN = /^[a-z][a-z0-9_-]{2,}$/u;
+const WAIVER_TOKEN_PREFIX = "WV";
+const WAIVER_LEDGER_SCHEMA_VERSION = 1;
+function waiverLedgerPath(projectRoot) {
+    return path.join(projectRoot, WAIVER_LEDGER_REL_PATH);
+}
+function waiverLedgerLockPath(projectRoot) {
+    return path.join(projectRoot, WAIVER_LEDGER_LOCK_REL_PATH);
+}
+function sanitizeWaiverRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const row = value;
+    const token = typeof row.token === "string" ? row.token : "";
+    const stage = row.stage;
+    const reason = typeof row.reason === "string" ? row.reason : "";
+    const issuedAt = typeof row.issuedAt === "string" ? row.issuedAt : "";
+    const expiresAt = typeof row.expiresAt === "string" ? row.expiresAt : "";
+    const consumedAt = typeof row.consumedAt === "string" ? row.consumedAt : null;
+    const issuerSubsystem = typeof row.issuerSubsystem === "string" ? row.issuerSubsystem : "";
+    const consumedBy = typeof row.consumedBy === "string" ? row.consumedBy : undefined;
+    if (token.length === 0 ||
+        typeof stage !== "string" ||
+        !FLOW_STAGES.includes(stage) ||
+        reason.length === 0 ||
+        issuedAt.length === 0 ||
+        expiresAt.length === 0 ||
+        issuerSubsystem.length === 0) {
+        return null;
+    }
+    return {
+        token,
+        stage: stage,
+        reason,
+        issuedAt,
+        expiresAt,
+        consumedAt,
+        issuerSubsystem,
+        ...(consumedBy ? { consumedBy } : {})
+    };
+}
+async function readWaiverLedger(projectRoot) {
+    const statePath = waiverLedgerPath(projectRoot);
+    if (!(await exists(statePath))) {
+        return { schemaVersion: WAIVER_LEDGER_SCHEMA_VERSION, pending: [], consumed: [] };
+    }
+    let raw;
+    try {
+        raw = await fs.readFile(statePath, "utf8");
+    }
+    catch {
+        return { schemaVersion: WAIVER_LEDGER_SCHEMA_VERSION, pending: [], consumed: [] };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { schemaVersion: WAIVER_LEDGER_SCHEMA_VERSION, pending: [], consumed: [] };
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return { schemaVersion: WAIVER_LEDGER_SCHEMA_VERSION, pending: [], consumed: [] };
+    }
+    const typed = parsed;
+    const pending = Array.isArray(typed.pending)
+        ? typed.pending
+            .map((item) => sanitizeWaiverRecord(item))
+            .filter((item) => item !== null)
+        : [];
+    const consumed = Array.isArray(typed.consumed)
+        ? typed.consumed
+            .map((item) => sanitizeWaiverRecord(item))
+            .filter((item) => item !== null)
+        : [];
+    return { schemaVersion: WAIVER_LEDGER_SCHEMA_VERSION, pending, consumed };
+}
+async function writeWaiverLedger(projectRoot, ledger) {
+    const next = {
+        schemaVersion: WAIVER_LEDGER_SCHEMA_VERSION,
+        pending: ledger.pending,
+        consumed: ledger.consumed
+    };
+    await writeFileSafe(waiverLedgerPath(projectRoot), `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+}
+function formatExpiresSlug(expiresAt) {
+    // Minute-precision slug for the token: e.g. `20260502T220500Z`
+    return expiresAt.toISOString().replace(/[-:]/gu, "").replace(/\..+$/u, "").concat("Z");
+}
+function minuteFingerprint(stage, reason, issuedAt) {
+    const payload = `${stage}|${reason}|${issuedAt.toISOString()}|${Math.random().toString(16).slice(2, 12)}`;
+    return createHash("sha256").update(payload, "utf8").digest("hex").slice(0, 8);
+}
+export function formatWaiverToken(stage, fingerprint, expiresAt) {
+    return `${WAIVER_TOKEN_PREFIX}-${stage}-${fingerprint}-${formatExpiresSlug(expiresAt)}`;
+}
+export async function issueWaiverToken(projectRoot, options) {
+    if (!FLOW_STAGES.includes(options.stage)) {
+        throw new Error(`waiver-grant: --stage must be one of ${FLOW_STAGES.join(", ")}.`);
+    }
+    const reason = options.reason.trim();
+    if (reason.length === 0) {
+        throw new Error("waiver-grant: --reason is required.");
+    }
+    if (!WAIVER_REASON_PATTERN.test(reason)) {
+        throw new Error("waiver-grant: --reason must match /^[a-z][a-z0-9_-]{2,}$/ (short lowercase slug, e.g. architect_unavailable).");
+    }
+    const ttlRaw = typeof options.expiresInMinutes === "number" && Number.isFinite(options.expiresInMinutes)
+        ? Math.floor(options.expiresInMinutes)
+        : WAIVER_TOKEN_DEFAULT_TTL_MINUTES;
+    if (ttlRaw < 1) {
+        throw new Error("waiver-grant: --ttl must be >= 1 minute.");
+    }
+    if (ttlRaw > WAIVER_TOKEN_MAX_TTL_MINUTES) {
+        throw new Error(`waiver-grant: --ttl must be <= ${WAIVER_TOKEN_MAX_TTL_MINUTES} minutes.`);
+    }
+    const issuedAtDate = options.now ?? new Date();
+    const expiresAtDate = new Date(issuedAtDate.getTime() + ttlRaw * 60 * 1000);
+    const fingerprint = minuteFingerprint(options.stage, reason, issuedAtDate);
+    const token = formatWaiverToken(options.stage, fingerprint, expiresAtDate);
+    const record = {
+        token,
+        stage: options.stage,
+        reason,
+        issuedAt: issuedAtDate.toISOString(),
+        expiresAt: expiresAtDate.toISOString(),
+        consumedAt: null,
+        issuerSubsystem: options.issuerSubsystem?.trim() || "cli"
+    };
+    await ensureDir(path.dirname(waiverLedgerPath(projectRoot)));
+    await withDirectoryLock(waiverLedgerLockPath(projectRoot), async () => {
+        const ledger = await readWaiverLedger(projectRoot);
+        ledger.pending.push(record);
+        await writeWaiverLedger(projectRoot, ledger);
+    });
+    return record;
+}
+export async function consumeWaiverToken(projectRoot, options) {
+    const token = options.token.trim();
+    if (token.length === 0) {
+        return {
+            ok: false,
+            reason: "not-found",
+            detail: "waiver token is required"
+        };
+    }
+    const now = (options.now ?? new Date()).getTime();
+    return withDirectoryLock(waiverLedgerLockPath(projectRoot), async () => {
+        const ledger = await readWaiverLedger(projectRoot);
+        const pendingIdx = ledger.pending.findIndex((entry) => entry.token === token);
+        const consumedMatch = ledger.consumed.find((entry) => entry.token === token);
+        if (pendingIdx < 0) {
+            if (consumedMatch) {
+                return {
+                    ok: false,
+                    reason: "already-consumed",
+                    record: consumedMatch,
+                    detail: `waiver token ${token} was already consumed at ${consumedMatch.consumedAt ?? "unknown time"}`
+                };
+            }
+            return {
+                ok: false,
+                reason: "not-found",
+                detail: `no pending waiver token "${token}" found in ${WAIVER_LEDGER_REL_PATH}`
+            };
+        }
+        const record = ledger.pending[pendingIdx];
+        if (record.stage !== options.stage) {
+            return {
+                ok: false,
+                reason: "wrong-stage",
+                record,
+                detail: `waiver token ${token} was issued for stage "${record.stage}", not "${options.stage}"`
+            };
+        }
+        const expiresAt = Date.parse(record.expiresAt);
+        if (Number.isFinite(expiresAt) && expiresAt < now) {
+            return {
+                ok: false,
+                reason: "expired",
+                record,
+                detail: `waiver token ${token} expired at ${record.expiresAt}`
+            };
+        }
+        const consumedAtIso = (options.now ?? new Date()).toISOString();
+        const consumedRecord = {
+            ...record,
+            consumedAt: consumedAtIso,
+            ...(options.consumedBy ? { consumedBy: options.consumedBy } : {})
+        };
+        ledger.pending.splice(pendingIdx, 1);
+        ledger.consumed.push(consumedRecord);
+        await writeWaiverLedger(projectRoot, ledger);
+        return { ok: true, record: consumedRecord };
+    });
+}
+export function parseWaiverGrantArgs(tokens) {
+    let stage;
+    let reason;
+    let ttlMinutes = WAIVER_TOKEN_DEFAULT_TTL_MINUTES;
+    let json = false;
+    let quiet = false;
+    for (let i = 0; i < tokens.length; i += 1) {
+        const token = tokens[i];
+        const nextToken = tokens[i + 1];
+        const readValue = (flag) => {
+            if (token.startsWith(`${flag}=`))
+                return token.slice(flag.length + 1);
+            if (token === flag && nextToken && !nextToken.startsWith("--")) {
+                i += 1;
+                return nextToken;
+            }
+            throw new Error(`${flag} requires a value.`);
+        };
+        if (token === "--json") {
+            json = true;
+            continue;
+        }
+        if (token === "--quiet") {
+            quiet = true;
+            continue;
+        }
+        if (token === "--stage" || token.startsWith("--stage=")) {
+            const raw = readValue("--stage").trim();
+            if (!FLOW_STAGES.includes(raw)) {
+                throw new Error(`waiver-grant: --stage must be one of ${FLOW_STAGES.join(", ")}.`);
+            }
+            stage = raw;
+            continue;
+        }
+        if (token === "--reason" || token.startsWith("--reason=")) {
+            reason = readValue("--reason").trim();
+            continue;
+        }
+        if (token === "--ttl" || token.startsWith("--ttl=")) {
+            const raw = readValue("--ttl").trim();
+            if (!/^[0-9]+$/u.test(raw)) {
+                throw new Error("waiver-grant: --ttl must be an integer number of minutes.");
+            }
+            ttlMinutes = Number(raw);
+            continue;
+        }
+        throw new Error(`Unknown flag for internal waiver-grant: ${token}`);
+    }
+    if (!stage) {
+        throw new Error(`internal waiver-grant requires --stage=<${FLOW_STAGES.join("|")}>.`);
+    }
+    if (!reason) {
+        throw new Error(`internal waiver-grant requires --reason=<short-slug> (e.g. architect_unavailable).`);
+    }
+    return { stage, reason, ttlMinutes, json, quiet };
+}
+export async function runWaiverGrant(projectRoot, args, io) {
+    const record = await issueWaiverToken(projectRoot, {
+        stage: args.stage,
+        reason: args.reason,
+        expiresInMinutes: args.ttlMinutes,
+        issuerSubsystem: "cli"
+    });
+    if (args.json) {
+        io.stdout.write(`${JSON.stringify({
+            ok: true,
+            command: "waiver-grant",
+            token: record.token,
+            stage: record.stage,
+            reason: record.reason,
+            issuedAt: record.issuedAt,
+            expiresAt: record.expiresAt,
+            ttlMinutes: args.ttlMinutes,
+            consumption: `cclaw-cli internal advance-stage ${record.stage} --accept-proactive-waiver=${record.token} --accept-proactive-waiver-reason="${record.reason}"`
+        })}\n`);
+        return 0;
+    }
+    io.stdout.write(`${record.token}\n`);
+    if (!args.quiet) {
+        io.stdout.write(`Waiver token issued for stage="${record.stage}" reason="${record.reason}" expires=${record.expiresAt}.\n`);
+        io.stdout.write(`Consume with: node ${RUNTIME_ROOT}/hooks/stage-complete.mjs ${record.stage} --accept-proactive-waiver=${record.token} --accept-proactive-waiver-reason="${record.reason}"\n`);
+    }
+    return 0;
+}

package/dist/run-persistence.d.ts

@@ -18,6 +18,13 @@ export interface WriteFlowStateOptions {
      * flow-state reset inside one atomic lock window.
      */
     skipLock?: boolean;
+    /**
+     * Free-form writer identifier persisted in the `.flow-state.guard.json`
+     * sidecar. Helps operators trace which subsystem wrote a given state
+     * (e.g. `advance-stage`, `start-flow`, `run-archive`). Defaults to
+     * `cclaw-cli` when omitted.
+     */
+    writerSubsystem?: string;
 }
 export interface ReadFlowStateOptions {
     /**
@@ -26,13 +33,76 @@ export interface ReadFlowStateOptions {
      */
     repairFeatureSystem?: boolean;
 }
+export interface FlowStateGuardSidecar {
+    sha256: string;
+    writtenAt: string;
+    writerSubsystem: string;
+    runId: string;
+}
+export interface FlowStateGuardMismatchDetails {
+    expectedSha: string;
+    actualSha: string;
+    lastWriter: string;
+    writtenAt: string;
+    runId: string;
+    statePath: string;
+    guardPath: string;
+    repairCommand: string;
+}
+export declare class FlowStateGuardMismatchError extends Error {
+    readonly expectedSha: string;
+    readonly actualSha: string;
+    readonly lastWriter: string;
+    readonly writtenAt: string;
+    readonly runId: string;
+    readonly statePath: string;
+    readonly guardPath: string;
+    readonly repairCommand: string;
+    constructor(details: FlowStateGuardMismatchDetails);
+}
 export declare class CorruptFlowStateError extends Error {
     readonly statePath: string;
     readonly quarantinedPath: string;
     constructor(statePath: string, quarantinedPath: string, cause: unknown);
 }
+/**
+ * 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 declare function verifyFlowStateGuard(projectRoot: string): Promise<void>;
 export declare function readFlowState(projectRoot: string, options?: ReadFlowStateOptions): Promise<FlowState>;
+/**
+ * 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 declare function readFlowStateGuarded(projectRoot: string, options?: ReadFlowStateOptions): Promise<FlowState>;
 export declare function writeFlowState(projectRoot: string, state: FlowState, options?: WriteFlowStateOptions): Promise<void>;
+/**
+ * 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 declare function writeFlowStateGuarded(projectRoot: string, state: FlowState, options?: WriteFlowStateOptions): Promise<void>;
+export interface FlowStateRepairResult {
+    sidecar: FlowStateGuardSidecar;
+    repairLogPath: string;
+    guardPath: string;
+}
+/**
+ * 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 declare function repairFlowStateGuard(projectRoot: string, reason: string): Promise<FlowStateRepairResult>;
+export declare function flowStateGuardSidecarPathFor(projectRoot: string): string;
+export declare function flowStateRepairLogPathFor(projectRoot: string): string;
 /**
  * Exposed path helper so callers that need to serialize a multi-step
  * state operation with flow-state writes (e.g. run archival) can

package/dist/run-persistence.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { RUNTIME_ROOT } from "./constants.js";
@@ -15,9 +16,49 @@ export class InvalidStageTransitionError extends Error {
     }
 }
 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.
@@ -488,6 +529,72 @@ async function quarantineCorruptState(statePath, cause) {
     }
     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;
     const statePath = flowStatePath(projectRoot);
@@ -513,13 +620,46 @@ export async function readFlowState(projectRoot, options = {}) {
     }
     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 raw = await fs.readFile(statePath, "utf8");
-                const parsed = JSON.parse(raw);
+                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);
@@ -533,7 +673,16 @@ export async function writeFlowState(projectRoot, state, options = {}) {
             }
         }
         const safe = coerceFlowState({ ...state }).state;
-        await writeFileSafe(statePath, `${JSON.stringify(safe, null, 2)}\n`, { mode: 0o600 });
+        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();
@@ -542,6 +691,69 @@ export async function writeFlowState(projectRoot, state, options = {}) {
         await withDirectoryLock(flowStateLockPath(projectRoot), doWrite);
     }
 }
+/**
+ * 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);
+}
+/**
+ * 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).");
+    }
+    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 () => {
+        const raw = await fs.readFile(statePath, "utf8");
+        let runId = "unknown-run";
+        try {
+            const parsed = JSON.parse(raw);
+            const coerced = coerceFlowState(parsed).state;
+            runId = coerced.activeRunId;
+        }
+        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 logLine = `${sidecar.writtenAt} reason=${trimmed} runId=${sidecar.runId} sha256=${sidecar.sha256}\n`;
+        await fs.appendFile(logPath, logLine, "utf8");
+        return { sidecar, repairLogPath: logPath, guardPath };
+    });
+}
+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

package/dist/runs.d.ts

@@ -1,2 +1,2 @@
-export { CorruptFlowStateError, InvalidStageTransitionError, type WriteFlowStateOptions, ensureRunSystem, readFlowState, writeFlowState } from "./run-persistence.js";
+export { CorruptFlowStateError, FlowStateGuardMismatchError, InvalidStageTransitionError, type FlowStateGuardSidecar, type FlowStateRepairResult, type WriteFlowStateOptions, ensureRunSystem, flowStateGuardSidecarPathFor, flowStateRepairLogPathFor, readFlowState, readFlowStateGuarded, repairFlowStateGuard, verifyFlowStateGuard, writeFlowState, writeFlowStateGuarded } from "./run-persistence.js";
 export { ARCHIVE_DISPOSITIONS, archiveRun, countActiveKnowledgeEntries, listRuns, type ArchiveDisposition, type ArchiveManifest, type ArchiveRunOptions, type ArchiveRunResult, type CclawRunMeta } from "./run-archive.js";

package/dist/runs.js

@@ -1,2 +1,2 @@
-export { CorruptFlowStateError, InvalidStageTransitionError, ensureRunSystem, readFlowState, writeFlowState } from "./run-persistence.js";
+export { CorruptFlowStateError, FlowStateGuardMismatchError, InvalidStageTransitionError, ensureRunSystem, flowStateGuardSidecarPathFor, flowStateRepairLogPathFor, readFlowState, readFlowStateGuarded, repairFlowStateGuard, verifyFlowStateGuard, writeFlowState, writeFlowStateGuarded } from "./run-persistence.js";
 export { ARCHIVE_DISPOSITIONS, archiveRun, countActiveKnowledgeEntries, listRuns } from "./run-archive.js";