cclaw-cli 6.5.0 → 6.7.0

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";

package/dist/runtime/run-hook.mjs

@@ -7573,12 +7573,14 @@ function nodeHookRuntimeScript(options = {}) {
   const defaultDisabledHooks = [];
   const cliRuntime = resolveCliRuntimeForGeneratedHook();
   return `#!/usr/bin/env node
+import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import process from "node:process";
 import { spawn } from "node:child_process";
 
 const RUNTIME_ROOT = ${JSON.stringify(RUNTIME_ROOT)};
+const FLOW_STATE_GUARD_REL_PATH = RUNTIME_ROOT + "/.flow-state.guard.json";
 // Single strictness default, derived from config.strictness at install time.
 // \`CCLAW_STRICTNESS\` env var overrides for the current process. All guards
 // (prompt, workflow, TDD, iron-laws) route through \`resolveStrictness()\`.
@@ -8541,6 +8543,40 @@ function extractCodePathsFromText(value) {
   return out;
 }
 
+async function verifyFlowStateGuardInline(root, hookName) {
+  const statePath = path.join(root, RUNTIME_ROOT, "state", "flow-state.json");
+  const guardPath = path.join(root, FLOW_STATE_GUARD_REL_PATH);
+  let raw;
+  try {
+    raw = await fs.readFile(statePath, "utf8");
+  } catch {
+    return true;
+  }
+  let guard;
+  try {
+    const guardRaw = await fs.readFile(guardPath, "utf8");
+    guard = JSON.parse(guardRaw);
+  } catch {
+    return true;
+  }
+  if (!guard || typeof guard !== "object" || typeof guard.sha256 !== "string") {
+    return true;
+  }
+  const actual = createHash("sha256").update(raw, "utf8").digest("hex");
+  if (actual === guard.sha256) return true;
+  const hookLabel = typeof hookName === "string" && hookName.length > 0 ? hookName : "hook";
+  process.stderr.write(
+    "[cclaw] " + hookLabel + ": flow-state guard mismatch: " + (guard.runId || "unknown-run") + "\\n" +
+      "expected sha: " + guard.sha256 + "\\n" +
+      "actual sha:   " + actual + "\\n" +
+      "last writer:  " + (guard.writerSubsystem || "unknown") + "@" + (guard.writtenAt || "unknown") + "\\n" +
+      "do not edit flow-state.json by hand. To recover, run:\\n" +
+      "  cclaw-cli internal flow-state-repair --reason \\"manual_edit_recovery\\"\\n"
+  );
+  await recordHookError(root, hookLabel, "flow-state guard mismatch actual=" + actual + " expected=" + guard.sha256).catch(() => undefined);
+  return false;
+}
+
 async function readFlowState(root) {
   const statePath = path.join(root, RUNTIME_ROOT, "state", "flow-state.json");
   // Loud-on-corrupt: if flow-state.json exists but fails JSON.parse, log
@@ -9634,6 +9670,13 @@ async function main() {
   };
 
   try {
+    if (hookName === "session-start" || hookName === "stop-handoff") {
+      const guardOk = await verifyFlowStateGuardInline(runtime.root, hookName);
+      if (!guardOk) {
+        process.exitCode = 2;
+        return;
+      }
+    }
     if (hookName === "session-start") {
       process.exitCode = await handleSessionStart(runtime);
       return;

package/package.json

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