cclaw-cli 6.5.0 → 6.7.0

package/dist/internal/advance-stage.js

@@ -11,13 +11,33 @@ import { runRewind } from "./advance-stage/rewind.js";
 import { runVerifyFlowStateDiff, runVerifyCurrentState } from "./advance-stage/verify.js";
 import { runHookCommand } from "./advance-stage/hook.js";
 import { parseAdvanceStageArgs, parseCancelRunArgs, parseHookArgs, parseRewindArgs, parseStartFlowArgs, parseVerifyCurrentStateArgs, parseVerifyFlowStateDiffArgs } from "./advance-stage/parsers.js";
+import { parseFlowStateRepairArgs, runFlowStateRepair } from "./flow-state-repair.js";
+import { parseWaiverGrantArgs, runWaiverGrant } from "./waiver-grant.js";
+import { FlowStateGuardMismatchError, verifyFlowStateGuard } from "../run-persistence.js";
+/**
+ * Subcommands that mutate or consult flow-state.json via the CLI runtime.
+ * They all require the sha256 sidecar to match before continuing so a
+ * manual edit hard-blocks with exit code 2 (same contract as the inline
+ * hook checks).
+ */
+const GUARD_ENFORCED_SUBCOMMANDS = new Set([
+    "advance-stage",
+    "start-flow",
+    "cancel-run",
+    "rewind",
+    "verify-flow-state-diff",
+    "verify-current-state"
+]);
 export async function runInternalCommand(projectRoot, argv, io) {
     const [subcommand, ...tokens] = argv;
     if (!subcommand) {
-        io.stderr.write("cclaw internal requires a subcommand: advance-stage | start-flow | cancel-run | rewind | verify-flow-state-diff | verify-current-state | envelope-validate | tdd-red-evidence | tdd-loop-status | early-loop-status | compound-readiness | runtime-integrity | hook\n");
+        io.stderr.write("cclaw internal requires a subcommand: advance-stage | start-flow | cancel-run | rewind | verify-flow-state-diff | verify-current-state | envelope-validate | tdd-red-evidence | tdd-loop-status | early-loop-status | compound-readiness | runtime-integrity | hook | flow-state-repair | waiver-grant\n");
         return 1;
     }
     try {
+        if (GUARD_ENFORCED_SUBCOMMANDS.has(subcommand)) {
+            await verifyFlowStateGuard(projectRoot);
+        }
         if (subcommand === "advance-stage") {
             return await runAdvanceStage(projectRoot, parseAdvanceStageArgs(tokens), io);
         }
@@ -57,10 +77,20 @@ export async function runInternalCommand(projectRoot, argv, io) {
         if (subcommand === "hook") {
             return await runHookCommand(projectRoot, parseHookArgs(tokens), io);
         }
-        io.stderr.write(`Unknown internal subcommand: ${subcommand}. Expected advance-stage | start-flow | cancel-run | rewind | verify-flow-state-diff | verify-current-state | envelope-validate | tdd-red-evidence | tdd-loop-status | early-loop-status | compound-readiness | runtime-integrity | hook\n`);
+        if (subcommand === "flow-state-repair") {
+            return await runFlowStateRepair(projectRoot, parseFlowStateRepairArgs(tokens), io);
+        }
+        if (subcommand === "waiver-grant") {
+            return await runWaiverGrant(projectRoot, parseWaiverGrantArgs(tokens), io);
+        }
+        io.stderr.write(`Unknown internal subcommand: ${subcommand}. Expected advance-stage | start-flow | cancel-run | rewind | verify-flow-state-diff | verify-current-state | envelope-validate | tdd-red-evidence | tdd-loop-status | early-loop-status | compound-readiness | runtime-integrity | hook | flow-state-repair | waiver-grant\n`);
         return 1;
     }
     catch (err) {
+        if (err instanceof FlowStateGuardMismatchError) {
+            io.stderr.write(`cclaw internal ${subcommand}: ${err.message}\n`);
+            return 2;
+        }
         io.stderr.write(`cclaw internal ${subcommand} failed: ${err instanceof Error ? err.message : String(err)}\n`);
         return 1;
     }

package/dist/internal/flow-state-repair.d.ts

@@ -0,0 +1,13 @@
+import type { Writable } from "node:stream";
+interface InternalIo {
+    stdout: Writable;
+    stderr: Writable;
+}
+export interface FlowStateRepairArgs {
+    reason: string;
+    json: boolean;
+    quiet: boolean;
+}
+export declare function parseFlowStateRepairArgs(tokens: string[]): FlowStateRepairArgs;
+export declare function runFlowStateRepair(projectRoot: string, args: FlowStateRepairArgs, io: InternalIo): Promise<number>;
+export {};

package/dist/internal/flow-state-repair.js

@@ -0,0 +1,65 @@
+import path from "node:path";
+import { RUNTIME_ROOT } from "../constants.js";
+import { repairFlowStateGuard } from "../run-persistence.js";
+export function parseFlowStateRepairArgs(tokens) {
+    let reason;
+    let json = false;
+    let quiet = false;
+    for (let i = 0; i < tokens.length; i += 1) {
+        const token = tokens[i];
+        const nextToken = tokens[i + 1];
+        if (token === "--json") {
+            json = true;
+            continue;
+        }
+        if (token === "--quiet") {
+            quiet = true;
+            continue;
+        }
+        if (token === "--reason") {
+            if (!nextToken || nextToken.startsWith("--")) {
+                throw new Error("--reason requires a short slug value.");
+            }
+            reason = nextToken.trim();
+            i += 1;
+            continue;
+        }
+        if (token.startsWith("--reason=")) {
+            reason = token.slice("--reason=".length).trim();
+            continue;
+        }
+        throw new Error(`Unknown flag for internal flow-state-repair: ${token}`);
+    }
+    if (!reason || reason.length === 0) {
+        throw new Error("internal flow-state-repair requires --reason=<slug> (e.g. --reason=manual_edit_recovery).");
+    }
+    return { reason, json, quiet };
+}
+export async function runFlowStateRepair(projectRoot, args, io) {
+    const result = await repairFlowStateGuard(projectRoot, args.reason);
+    const logRel = path.relative(projectRoot, result.repairLogPath).replace(/\\/gu, "/");
+    const guardRel = path.relative(projectRoot, result.guardPath).replace(/\\/gu, "/");
+    if (args.json) {
+        io.stdout.write(`${JSON.stringify({
+            ok: true,
+            command: "flow-state-repair",
+            reason: args.reason,
+            sidecar: result.sidecar,
+            guardPath: guardRel,
+            repairLogPath: logRel,
+            runtimeRoot: RUNTIME_ROOT
+        })}\n`);
+        return 0;
+    }
+    if (!args.quiet) {
+        io.stdout.write(`${JSON.stringify({
+            ok: true,
+            command: "flow-state-repair",
+            reason: args.reason,
+            sidecar: result.sidecar,
+            guardPath: guardRel,
+            repairLogPath: logRel
+        }, null, 2)}\n`);
+    }
+    return 0;
+}

package/dist/internal/waiver-grant.d.ts

@@ -0,0 +1,62 @@
+import { type FlowStage } from "../types.js";
+import type { Writable } from "node:stream";
+interface InternalIo {
+    stdout: Writable;
+    stderr: Writable;
+}
+export declare const WAIVER_TOKEN_DEFAULT_TTL_MINUTES = 30;
+export declare const WAIVER_TOKEN_MAX_TTL_MINUTES = 120;
+export declare const WAIVER_REASON_PATTERN: RegExp;
+export interface WaiverRecord {
+    token: string;
+    stage: FlowStage;
+    reason: string;
+    issuedAt: string;
+    expiresAt: string;
+    consumedAt: string | null;
+    issuerSubsystem: string;
+    consumedBy?: string;
+}
+export interface WaiverLedger {
+    schemaVersion: number;
+    pending: WaiverRecord[];
+    consumed: WaiverRecord[];
+}
+export interface IssueWaiverTokenOptions {
+    stage: FlowStage;
+    reason: string;
+    expiresInMinutes?: number;
+    issuerSubsystem?: string;
+    now?: Date;
+}
+export interface ConsumeWaiverOptions {
+    stage: FlowStage;
+    token: string;
+    consumedBy?: string;
+    now?: Date;
+}
+export declare function formatWaiverToken(stage: FlowStage, fingerprint: string, expiresAt: Date): string;
+export declare function issueWaiverToken(projectRoot: string, options: IssueWaiverTokenOptions): Promise<WaiverRecord>;
+export type ConsumeWaiverFailureReason = "not-found" | "wrong-stage" | "expired" | "already-consumed";
+export interface ConsumeWaiverSuccess {
+    ok: true;
+    record: WaiverRecord;
+}
+export interface ConsumeWaiverFailure {
+    ok: false;
+    reason: ConsumeWaiverFailureReason;
+    record?: WaiverRecord;
+    detail: string;
+}
+export type ConsumeWaiverResult = ConsumeWaiverSuccess | ConsumeWaiverFailure;
+export declare function consumeWaiverToken(projectRoot: string, options: ConsumeWaiverOptions): Promise<ConsumeWaiverResult>;
+export interface WaiverGrantArgs {
+    stage: FlowStage;
+    reason: string;
+    ttlMinutes: number;
+    json: boolean;
+    quiet: boolean;
+}
+export declare function parseWaiverGrantArgs(tokens: string[]): WaiverGrantArgs;
+export declare function runWaiverGrant(projectRoot: string, args: WaiverGrantArgs, io: InternalIo): Promise<number>;
+export {};

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