@kontourai/flow-agents 1.4.0 → 2.0.1

package/scripts/hooks/workflow-steering.js

@@ -3,7 +3,11 @@
  * Workflow Steering Hook
  *
  * Injects phase-transition reminders after use_subagent calls complete and
- * ambient workflow-state reminders at the start of the next user turn.
+ * re-grounds the active workflow state at the start of every user turn and on
+ * SessionStart. SessionStart fires after context compaction and on resume, so
+ * re-injecting the goal/phase/next-step there is what makes an in-flight goal
+ * survive context loss instead of relying on the model voluntarily re-reading
+ * the sidecar.
  *
  * Non-blocking — always exits 0.
  */
@@ -12,6 +16,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { readLivenessEvents, freshHolders } = require('./lib/liveness-read');
 
 const STEERING = {
   'tool-planner': [
@@ -198,6 +203,118 @@ function contextMapSteering(root) {
   ].join(' ');
 }
 
+/**
+ * Compose the RESUME block for SessionStart.
+ *
+ * Reads trust.bundle, handoff.json, and the liveness stream beside state.json;
+ * all reads are fail-open (errors → skip that section, never throw).
+ *
+ * Returns a multi-line string starting with "RESUME: <slug> status:<s> phase:<p>"
+ * or '' if the current state has status 'done', 'archived', or 'accepted'.
+ *
+ * @param {string} root     Repository root
+ * @param {{ file: string, payload: object }} current  Latest active state entry
+ * @returns {string}
+ */
+function resumeSteering(root, current) {
+  try {
+    const state = current.payload;
+    const workflowDir = path.dirname(current.file);
+    const slug = state.task_slug || path.basename(workflowDir);
+    const next = state.next_action || {};
+
+    if (next.status === 'done' || state.status === 'archived' || state.status === 'accepted') return '';
+
+    const lines = [];
+
+    // Header line
+    lines.push(`RESUME: ${slug} status:${safeStateText(state.status, 60)} phase:${safeStateText(state.phase, 60)}`);
+
+    // Full next action (240-char display path, not the 80-char normalization)
+    const nextSummary = next.summary ? safeStateText(next.summary, 240) : 'none';
+    lines.push(`Next action: ${nextSummary}`);
+
+    // Plan artifact path
+    let planPath = 'not found';
+    try {
+      const artifactPaths = Array.isArray(state.artifact_paths) ? state.artifact_paths : [];
+      const planEntry = artifactPaths.find(p => typeof p === 'string' && p.endsWith('--plan-work.md'));
+      if (planEntry) {
+        planPath = planEntry;
+      } else {
+        const candidate = path.join(workflowDir, `${slug}--plan-work.md`);
+        if (fs.existsSync(candidate)) planPath = candidate;
+      }
+    } catch { /* skip */ }
+    lines.push(`Plan: ${planPath}`);
+
+    // Handoff: next_steps[0] and blockers
+    let nextStep = 'none';
+    let blockers = 'none';
+    try {
+      const handoff = readJson(path.join(workflowDir, 'handoff.json'));
+      if (handoff) {
+        const steps = Array.isArray(handoff.next_steps) ? handoff.next_steps : [];
+        if (steps.length > 0) nextStep = safeStateText(String(steps[0]), 240);
+        const bArr = Array.isArray(handoff.blockers) ? handoff.blockers : [];
+        if (bArr.length > 0) blockers = bArr.map(b => safeStateText(String(b), 120)).join(', ');
+      }
+    } catch { /* skip */ }
+    lines.push(`Next step: ${nextStep}`);
+    lines.push(`Blockers: ${blockers}`);
+
+    // Trust bundle
+    try {
+      const bundle = readJson(path.join(workflowDir, 'trust.bundle'));
+      if (bundle) {
+        const claims = Array.isArray(bundle.claims) ? bundle.claims : [];
+        let verified = 0;
+        let disputed = 0;
+        const unresolved = [];
+        for (const claim of claims) {
+          if (!claim || typeof claim !== 'object') continue;
+          const status = String(claim.status || '');
+          if (status === 'verified') {
+            verified++;
+          } else if (status === 'disputed' || status === 'unknown') {
+            disputed++;
+            unresolved.push(claim);
+          }
+        }
+        const total = claims.length;
+        lines.push(`Trust: ${verified} verified / ${disputed} disputed / ${total} total`);
+        for (const claim of unresolved) {
+          const id = safeStateText(String(claim.id || ''), 120);
+          const st = safeStateText(String(claim.status || ''), 30);
+          lines.push(`  - ${id} (${st}) → npm run workflow:sidecar -- claim ${id} ${workflowDir}`);
+        }
+      } else {
+        lines.push('Trust: no trust data available');
+      }
+    } catch { /* skip */ }
+
+    // Liveness advisory
+    try {
+      const livenessFile = path.join(root, '.flow-agents', 'liveness', 'events.jsonl');
+      const events = readLivenessEvents(livenessFile);
+      if (events.length > 0) {
+        const selfActor = (process.env.FLOW_AGENTS_ACTOR || '').trim() || 'local';
+        const holders = freshHolders(events, slug, selfActor, Date.now());
+        for (const h of holders) {
+          lines.push(`[LIVENESS WARNING: another agent appears live on this work: actor ${h.actor}, last seen ${h.lastAt}]`);
+        }
+      }
+    } catch { /* skip */ }
+
+    // Pull-work route hint
+    lines.push('To continue: resume this work. Or run pull-work to assess WIP and start new/parallel work.');
+
+    return lines.join('\n');
+  } catch {
+    return '';
+  }
+}
+
 function run(rawInput) {
   try {
     const input = JSON.parse(rawInput);
@@ -217,9 +334,22 @@ function run(rawInput) {
       shouldAppendWorkflowContext = hints.length > 0;
     }
 
-    if (event === 'UserPromptSubmit' && current && stateNeedsAmbientSteering(current.payload)) {
-      hints.push('WORKFLOW STATE ATTENTION: current sidecars show unresolved workflow state at turn start.');
-      shouldAppendWorkflowContext = true;
+    if ((event === 'UserPromptSubmit' || event === 'SessionStart') && current) {
+      const stateHint = stateSteering(root);
+      if (stateHint) {
+        hints.push(stateNeedsAmbientSteering(current.payload)
+          ? 'WORKFLOW STATE ATTENTION: current sidecars show unresolved workflow state at turn start.'
+          : 'WORKFLOW STATE: an active task is in progress — re-ground the recorded goal and resume the next step before doing anything else.');
+        hints.push(stateHint);
+        const contextHint = contextMapSteering(root);
+        if (contextHint) hints.push(contextHint);
+      }
+    }
+
+    // SessionStart only: append the RESUME block for richer situational awareness
+    if (event === 'SessionStart' && current) {
+      const resumeBlock = resumeSteering(root, current);
+      if (resumeBlock) hints.push(resumeBlock);
     }
 
     if (shouldAppendWorkflowContext) {
@@ -247,4 +377,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { run, stateSteering, critiqueSteering, contextMapSteering, latestWorkflowState, findRepoRoot, safeStateText, stateNeedsAmbientSteering };
+module.exports = { run, stateSteering, critiqueSteering, contextMapSteering, latestWorkflowState, findRepoRoot, safeStateText, stateNeedsAmbientSteering, resumeSteering };

package/scripts/install-codex-home.sh

@@ -60,6 +60,14 @@ fi
 
 mkdir -p "$DEST"
 
+# Stash the user's existing hooks.json (if any) BEFORE cleaning, so the merge
+# step below can preserve user hooks across re-installs.
+FA_USER_HOOKS_STASH=""
+if [[ -f "$DEST/hooks.json" ]]; then
+  FA_USER_HOOKS_STASH="$(mktemp /tmp/fa-user-hooks.XXXXXX.json)"
+  cp "$DEST/hooks.json" "$FA_USER_HOOKS_STASH"
+fi
+
 # This is an isolated generated Codex home. Clean generated bundle content before
 # overlaying so renamed/deleted source files do not survive across installs.
 rm -rf \
@@ -98,6 +106,37 @@ done
 
 chmod 700 "$DEST" 2>/dev/null || true
 [[ -f "$DEST/auth.json" ]] && chmod 600 "$DEST/auth.json" 2>/dev/null || true
+
+# Merge FA hooks into the flattened hooks.json, preserving any user hooks already present.
+# The managed-hooks source is the bundle's .codex/hooks.json (pre-flatten, always present in dist/codex/).
+# The rsync above wrote the FA hooks.json directly to $DEST/hooks.json.
+# If the user had a hooks.json before this install, use the stash as the "existing" config so
+# user-owned hook groups survive. Otherwise, $DEST/hooks.json is already correct (FA only).
+FA_VERSION="$(node -p "require('$ROOT_DIR/package.json').version" 2>/dev/null || echo unknown)"
+FA_MANAGED_HOOKS="$ROOT_DIR/dist/codex/.codex/hooks.json"
+if command -v node >/dev/null 2>&1 && [[ -f "$FA_MANAGED_HOOKS" ]]; then
+  if [[ -n "$FA_USER_HOOKS_STASH" && -f "$FA_USER_HOOKS_STASH" ]]; then
+    # Merge user's prior hooks (stash) with the current FA managed hooks.
+    node "$ROOT_DIR/scripts/install-merge.js" \
+      --config "$FA_USER_HOOKS_STASH" \
+      --managed-hooks "$FA_MANAGED_HOOKS" \
+      --version "$FA_VERSION" \
+      --install-record "$DEST/.flow-agents/install.json" \
+      --runtime "codex" || true
+    # Move the merged result into the destination.
+    cp "$FA_USER_HOOKS_STASH" "$DEST/hooks.json"
+    rm -f "$FA_USER_HOOKS_STASH"
+  else
+    # No prior user hooks: just write the version stamp (FA hooks are already correct from rsync).
+    node "$ROOT_DIR/scripts/install-merge.js" \
+      --config "$DEST/hooks.json" \
+      --managed-hooks "$FA_MANAGED_HOOKS" \
+      --version "$FA_VERSION" \
+      --install-record "$DEST/.flow-agents/install.json" \
+      --runtime "codex" || true
+  fi
+fi
+
 if [[ ${#CONSOLE_CONFIG_ARGS[@]} -gt 0 || -n "${FLOW_AGENTS_TELEMETRY_SINK:-}" || -n "${FLOW_AGENTS_TELEMETRY_SINKS:-}" || -n "${FLOW_AGENTS_CONSOLE_URL:-}" || -n "${CONSOLE_TELEMETRY_URL:-}" || -n "${CONSOLE_URL:-}" || -n "${FLOW_AGENTS_CONSOLE_TOKEN_FILE:-}" || -n "${CONSOLE_TELEMETRY_TOKEN_FILE:-}" ]]; then
   bash "$DEST/scripts/telemetry/install-console-config.sh" "$DEST/scripts/telemetry/telemetry.conf" "${CONSOLE_CONFIG_ARGS[@]}"
 fi

package/scripts/install-merge.js

@@ -0,0 +1,330 @@
+#!/usr/bin/env node
+/**
+ * install-merge.js — Merge-aware installer for flow-agents config files.
+ *
+ * Usage (CLI — full merge):
+ *   node scripts/install-merge.js \
+ *     --config <path-to-settings.json-or-hooks.json> \
+ *     --managed-hooks <path-to-flow-agents-hooks-snippet.json> \
+ *     --version <version-string> \
+ *     --install-record <path-to-install.json> \
+ *     --runtime <claude-code|codex|opencode|pi|kiro|base>
+ *
+ * Usage (CLI — stamp only, no config merge):
+ *   node scripts/install-merge.js \
+ *     --stamp-only \
+ *     --version <version-string> \
+ *     --install-record <path-to-install.json> \
+ *     --runtime <pi|kiro|base|opencode>
+ *
+ * Design (per install-merge-aware--plan-work.md):
+ *   (a) Read dest JSON (or {} if absent).
+ *   (b) STRIP any hook entry whose inner hooks' statusMessage matches a
+ *       flow-agents marker (the COLLISION_MARKER strings from init.ts).
+ *   (c) APPEND the current managed hook groups from the bundle.
+ *   (d) Preserve ALL other keys (permissions, statusLine, user hooks, auth).
+ *   (e) Atomic write (write tmp + rename).
+ *   (f) Write/update .flow-agents/install.json version stamp.
+ *
+ * Export: mergeSettings(existing, managed) — pure, testable.
+ * The managed ownership region is identified purely by statusMessage markers
+ * (cross-runtime, no top-level key needed in settings.json).
+ */
+
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+
+// ─── Marker strings ───────────────────────────────────────────────────────────
+// These three statusMessage strings identify every flow-agents managed hook.
+// They are the same strings used by COLLISION_MARKER in src/cli/init.ts and
+// by exportClaudeSettings() / exportCodexHooks() in build-universal-bundles.ts.
+const FA_MARKERS = [
+  "Recording Flow Agents telemetry",
+  "Running Flow Agents hook policy",
+  "Capturing Flow Agents command evidence",
+];
+
+/**
+ * Returns true if a hook-group entry is owned by flow-agents.
+ * A hook-group in Claude Code settings looks like:
+ *   { hooks: [ { type, command, timeout, statusMessage } ] }
+ * A hook-group in Codex hooks.json looks like:
+ *   { hooks: [ { type, command, timeout, statusMessage } ] }
+ *
+ * We identify a managed group by checking whether ANY inner hook's
+ * statusMessage contains one of the FA_MARKERS strings.
+ *
+ * @param {Record<string, unknown>} hookGroup
+ * @returns {boolean}
+ */
+function isManagedHookGroup(hookGroup) {
+  if (typeof hookGroup !== "object" || hookGroup === null) return false;
+  const innerHooks = Array.isArray(hookGroup.hooks) ? hookGroup.hooks : [];
+  return innerHooks.some((innerHook) => {
+    if (typeof innerHook !== "object" || innerHook === null) return false;
+    const sm = typeof innerHook.statusMessage === "string" ? innerHook.statusMessage : "";
+    return FA_MARKERS.some((marker) => sm.includes(marker));
+  });
+}
+
+/**
+ * mergeArrayUnion — union two arrays preserving order, de-duped (string or JSON key).
+ * @param {unknown} a @param {unknown} b @returns {unknown[]}
+ */
+function mergeArrayUnion(a, b) {
+  const out = [];
+  const seen = new Set();
+  for (const item of [...(Array.isArray(a) ? a : []), ...(Array.isArray(b) ? b : [])]) {
+    const key = typeof item === "string" ? item : JSON.stringify(item);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(item);
+  }
+  return out;
+}
+
+/**
+ * mergePermissions — deep-merge the `permissions` block so flow-agents only ADDS
+ * its required entries and never clobbers the user's customizations (#117):
+ *   - union the user's + managed `allow`/`deny`/`ask` rule lists (de-duped),
+ *   - preserve the user's `defaultMode` when set (only adopt managed's if unset),
+ *   - keep user-only sub-keys; overlay other managed scalar sub-keys.
+ * @param {unknown} existingPerms @param {unknown} managedPerms
+ * @returns {Record<string, unknown>}
+ */
+function mergePermissions(existingPerms, managedPerms) {
+  const e = existingPerms && typeof existingPerms === "object" ? existingPerms : {};
+  const m = managedPerms && typeof managedPerms === "object" ? managedPerms : {};
+  const out = Object.assign({}, e, m);
+  for (const listKey of ["allow", "deny", "ask"]) {
+    if (Array.isArray(e[listKey]) || Array.isArray(m[listKey])) {
+      out[listKey] = mergeArrayUnion(e[listKey], m[listKey]);
+    }
+  }
+  if (e.defaultMode !== undefined) out.defaultMode = e.defaultMode;
+  return out;
+}
+
+/**
+ * mergeSettings — pure merge function (no I/O).
+ *
+ * Given:
+ *   existing  — the current dest settings object (e.g. from settings.json)
+ *   managed   — the flow-agents generated settings (e.g. from bundle .claude/settings.json)
+ *
+ * Returns a new object with:
+ *   - All keys from `existing` preserved (permissions, statusLine, auth, etc.)
+ *   - All keys from `managed` merged in (flow-agents owned keys like statusLine, hooks)
+ *   - For the `hooks` key: user-owned hook groups (non-FA) survive; FA groups are
+ *     replaced with the current managed set from `managed`.
+ *
+ * Strategy:
+ *   1. Start with a shallow copy of `existing` (preserves all user keys).
+ *   2. Overlay all scalar/non-hooks keys from `managed` (statusLine, permissions
+ *      from the bundle, skipDangerousModePermissionPrompt, etc.).
+ *   3. For `hooks`: iterate each event key from both existing and managed;
+ *      keep user (non-FA) groups from existing, append the current FA groups
+ *      from managed.
+ *
+ * @param {Record<string, unknown>} existing
+ * @param {Record<string, unknown>} managed
+ * @returns {Record<string, unknown>}
+ */
+function mergeSettings(existing, managed) {
+  // 1. Start with all existing keys (preserves user-owned data).
+  const result = Object.assign({}, existing);
+
+  // 2. Overlay non-hooks keys from managed. `permissions` is DEEP-merged so the
+  //    user's allow/deny/ask lists + defaultMode survive — flow-agents only adds
+  //    its required entries (#117: never clobber user customizations).
+  for (const [key, value] of Object.entries(managed)) {
+    if (key === "hooks") continue;
+    if (key === "permissions") {
+      result.permissions = mergePermissions(existing.permissions, value);
+    } else {
+      result[key] = value;
+    }
+  }
+
+  // 3. Merge hooks: strip FA groups from existing, append current FA groups.
+  const existingHooks =
+    typeof existing.hooks === "object" && existing.hooks !== null
+      ? (existing.hooks)
+      : {};
+  const managedHooks =
+    typeof managed.hooks === "object" && managed.hooks !== null
+      ? (managed.hooks)
+      : {};
+
+  // Collect all event keys from both sides.
+  const allEventKeys = new Set([
+    ...Object.keys(existingHooks),
+    ...Object.keys(managedHooks),
+  ]);
+
+  const mergedHooks = {};
+  for (const eventKey of allEventKeys) {
+    const existingGroups = Array.isArray(existingHooks[eventKey])
+      ? existingHooks[eventKey]
+      : [];
+    const managedGroups = Array.isArray(managedHooks[eventKey])
+      ? managedHooks[eventKey]
+      : [];
+
+    // Keep user-owned (non-FA) groups from existing.
+    const userGroups = existingGroups.filter(
+      (group) => !isManagedHookGroup(group)
+    );
+
+    // Append the new FA groups from managed (may be empty if event not in managed).
+    mergedHooks[eventKey] = [...userGroups, ...managedGroups];
+
+    // Drop empty event keys (only user groups existed and were zero — unlikely
+    // but defensive: remove keys with empty arrays to keep JSON clean).
+    if (mergedHooks[eventKey].length === 0) {
+      delete mergedHooks[eventKey];
+    }
+  }
+
+  // Only write the hooks key if at least one side actually had a hooks key,
+  // OR if the merged result is non-empty. This prevents injecting a spurious
+  // empty "hooks": {} into configs that have no hooks (e.g. opencode.json).
+  const eitherHadHooks = "hooks" in existing || "hooks" in managed;
+  if (eitherHadHooks || Object.keys(mergedHooks).length > 0) {
+    result.hooks = mergedHooks;
+  }
+  return result;
+}
+
+/**
+ * atomicWriteJson — write JSON to a file atomically (tmp + rename).
+ *
+ * @param {string} filePath
+ * @param {unknown} data
+ */
+function atomicWriteJson(filePath, data) {
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = `${filePath}.tmp.${process.pid}`;
+  fs.writeFileSync(tmp, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+  fs.renameSync(tmp, filePath);
+}
+
+/**
+ * writeInstallRecord — write/update .flow-agents/install.json.
+ *
+ * @param {string} installRecordPath
+ * @param {string} version
+ * @param {string} runtime
+ */
+function writeInstallRecord(installRecordPath, version, runtime) {
+  const record = {
+    version,
+    installedAt: new Date().toISOString(),
+    runtime,
+  };
+  atomicWriteJson(installRecordPath, record);
+}
+
+/**
+ * runMerge — perform the full merge (read, merge, write, stamp).
+ *
+ * @param {{
+ *   configPath: string,
+ *   managedHooksPath: string,
+ *   version: string,
+ *   installRecordPath: string,
+ *   runtime: string,
+ * }} opts
+ */
+function runMerge({ configPath, managedHooksPath, version, installRecordPath, runtime }) {
+  // (a) Read dest JSON (or {} if absent).
+  let existing = {};
+  if (fs.existsSync(configPath)) {
+    try {
+      existing = JSON.parse(fs.readFileSync(configPath, "utf8"));
+    } catch (err) {
+      process.stderr.write(
+        `install-merge: warning: could not parse existing ${configPath} (${err.message}); treating as empty\n`
+      );
+      existing = {};
+    }
+  }
+
+  // Read the managed (bundle-generated) config.
+  let managed = {};
+  try {
+    managed = JSON.parse(fs.readFileSync(managedHooksPath, "utf8"));
+  } catch (err) {
+    process.stderr.write(
+      `install-merge: error: could not read managed config ${managedHooksPath}: ${err.message}\n`
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  // (b) + (c) + (d) Merge.
+  const merged = mergeSettings(existing, managed);
+
+  // (e) Atomic write.
+  atomicWriteJson(configPath, merged);
+
+  // (f) Write version stamp.
+  writeInstallRecord(installRecordPath, version, runtime);
+}
+
+// ─── CLI wrapper ──────────────────────────────────────────────────────────────
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--stamp-only") {
+      flags["stamp-only"] = "1";
+    } else if (args[i].startsWith("--") && i + 1 < args.length) {
+      flags[args[i].slice(2)] = args[i + 1];
+      i++;
+    }
+  }
+
+  const stampOnly = flags["stamp-only"] === "1";
+  const configPath = flags["config"];
+  const managedHooksPath = flags["managed-hooks"];
+  const version = flags["version"] || "unknown";
+  const installRecordPath = flags["install-record"];
+  const runtime = flags["runtime"] || "claude-code";
+
+  if (stampOnly) {
+    // Stamp-only mode: write install.json without merging any config file.
+    // Used by runtimes (pi, kiro, base) that do not have a shared config to merge.
+    if (!installRecordPath) {
+      process.stderr.write(
+        "usage: node install-merge.js --stamp-only --version <ver> --install-record <path> --runtime <runtime>\n"
+      );
+      process.exitCode = 2;
+    } else {
+      try {
+        writeInstallRecord(installRecordPath, version, runtime);
+      } catch (err) {
+        process.stderr.write(`install-merge: error: ${err.message}\n`);
+        process.exitCode = 1;
+      }
+    }
+  } else if (!configPath || !managedHooksPath || !installRecordPath) {
+    process.stderr.write(
+      "usage: node install-merge.js --config <path> --managed-hooks <path> --version <ver> --install-record <path> --runtime <runtime>\n"
+    );
+    process.exitCode = 2;
+  } else {
+    try {
+      runMerge({ configPath, managedHooksPath, version, installRecordPath, runtime });
+    } catch (err) {
+      process.stderr.write(`install-merge: error: ${err.message}\n`);
+      process.exitCode = 1;
+    }
+  }
+}
+
+module.exports = { mergeSettings, isManagedHookGroup, FA_MARKERS };

package/scripts/repair-command-log.js

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * repair-command-log.js — deterministic re-linearization of a concurrent-fork
+ * command-log.jsonl.
+ *
+ * A "fork" happens when two PostToolUse captures append off the same parent tip
+ * (parallel writers before the writer lock, flow-agents#232). The records are
+ * all genuine and self-consistent; only their linear order is ambiguous. This
+ * tool produces THE canonical order — sort chained entries by (capturedAt, then
+ * hash) — and re-chains them, so any party re-running it gets the identical
+ * result. It is therefore a verifiable repair, not a judgement call.
+ *
+ * SAFETY: it refuses to run unless verifyCommandLogChain() reports "forked".
+ *   - "broken" (real tamper: edited content, reorder, deletion) → REFUSE. The
+ *     repair must never be usable to launder tampering.
+ *   - "ok" / "legacy" → nothing to do.
+ * No record content is altered — only the _chain wrappers and line order. The
+ * original is backed up, and an in-chain `chain-repair` marker records that the
+ * re-linearization happened (so the repair is itself auditable).
+ *
+ * Usage: node scripts/repair-command-log.js <artifact-dir> [--reason "..."]
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const gate = require(path.join(__dirname, 'hooks', 'stop-goal-fit.js'));
+const GENESIS = gate.CHAIN_GENESIS_VERIFY;
+
+function canon(rec) {
+  const keys = Object.keys(rec).filter((k) => k !== '_chain').sort();
+  const obj = {};
+  for (const k of keys) obj[k] = rec[k];
+  return JSON.stringify(obj);
+}
+function hashLink(prev, rec) {
+  return crypto.createHash('sha256').update(prev + canon(rec), 'utf8').digest('hex');
+}
+
+function main() {
+  const dir = process.argv[2];
+  if (!dir) { console.error('usage: repair-command-log.js <artifact-dir> [--reason "..."]'); process.exit(2); }
+  const reasonIdx = process.argv.indexOf('--reason');
+  const reason = reasonIdx !== -1 ? (process.argv[reasonIdx + 1] || '') : 'deterministic concurrent-fork re-linearization';
+
+  const verdict = gate.verifyCommandLogChain(dir);
+  if (verdict.status === 'ok' || verdict.status === 'legacy') {
+    console.log(`nothing to repair: chain status is "${verdict.status}"`);
+    return;
+  }
+  if (verdict.status !== 'forked') {
+    console.error(`REFUSING to repair: chain status is "${verdict.status}" (entry ${verdict.brokenAt}). ` +
+      'This tool only re-linearizes benign concurrent forks; it will not touch a tampered chain.');
+    process.exit(1);
+  }
+
+  const file = path.join(dir, 'command-log.jsonl');
+  const lines = fs.readFileSync(file, 'utf8').split('\n').filter((l) => l.trim());
+
+  // Preserve legacy prefix verbatim; collect the chained records (content only).
+  const legacyPrefix = [];
+  const records = [];
+  let started = false;
+  for (const line of lines) {
+    let e;
+    try { e = JSON.parse(line); } catch { if (!started) { legacyPrefix.push(line); } continue; }
+    const isChained = e._chain && typeof e._chain.hash === 'string';
+    if (!started && !isChained) { legacyPrefix.push(line); continue; }
+    started = true;
+    const rec = { ...e };
+    delete rec._chain;
+    records.push(rec);
+  }
+
+  // Canonical deterministic order: capturedAt asc, then a stable content hash.
+  records.sort((a, b) => {
+    const ta = String(a.capturedAt || ''), tb = String(b.capturedAt || '');
+    if (ta !== tb) return ta < tb ? -1 : 1;
+    const ha = crypto.createHash('sha256').update(canon(a)).digest('hex');
+    const hb = crypto.createHash('sha256').update(canon(b)).digest('hex');
+    return ha < hb ? -1 : ha > hb ? 1 : 0;
+  });
+
+  // Re-chain from genesis.
+  const out = [...legacyPrefix];
+  let prev = GENESIS;
+  let seq = 0;
+  for (const rec of records) {
+    const h = hashLink(prev, rec);
+    out.push(JSON.stringify({ ...rec, _chain: { seq, prevHash: prev, hash: h } }));
+    prev = h; seq += 1;
+  }
+  // Append an in-chain repair marker so the re-linearization is itself auditable.
+  const marker = {
+    command: '(chain-repair marker)',
+    observedResult: `re-linearized ${records.length} entries from concurrent fork`,
+    exitCode: 0,
+    capturedAt: new Date().toISOString(),
+    source: 'chain-repair',
+    repair: { reason, entries: records.length, forkAt: verdict.forkAt },
+  };
+  const mh = hashLink(prev, marker);
+  out.push(JSON.stringify({ ...marker, _chain: { seq, prevHash: prev, hash: mh } }));
+
+  fs.copyFileSync(file, file + '.prebackup-repair');
+  fs.writeFileSync(file, out.join('\n') + '\n');
+
+  const after = gate.verifyCommandLogChain(dir);
+  console.log(`repaired: re-linearized ${records.length} entries (legacy prefix: ${legacyPrefix.length}); ` +
+    `chain status now "${after.status}". backup: command-log.jsonl.prebackup-repair`);
+  if (after.status !== 'ok') { console.error('repair did not produce a clean chain'); process.exit(1); }
+}
+
+main();