@kontourai/flow-agents 2.0.0 → 2.0.1

package/evals/integration/test_kit_identity_trust.sh

@@ -0,0 +1,393 @@
+#!/usr/bin/env bash
+# test_kit_identity_trust.sh — Regression eval for kit identity end-to-end in the trust chain.
+#
+# Proves Fix 1 and Fix 2 from the kit-identity task:
+#
+#  Fix 1 (surfaceCheckFromArtifact reads kit from bundle, never hardcodes "builder"):
+#   1a. KNOWLEDGE-TYPED bundle → kitIdentityFromBundle derives kitId="knowledge", subject="knowledge-kit"
+#   1b. BUILDER-TYPED bundle  → kitIdentityFromBundle derives kitId="builder", subject="builder-kit"
+#   1c. WORKFLOW-ONLY bundle (no kit-typed claim, no current.json) → kitId="unknown", subject="unknown-kit"
+#   1d. record-evidence --surface-trust-json <knowledge-fixture> completes without crash
+#
+#  Fix 2 (route-back guard is FlowDefinition-driven, not hardcoded to builder.build):
+#   2a. builder.build: verification→execution still enforced (identical behavior preserved)
+#   2b. Custom non-builder flow WITH route_back_policy: verification→execution ENFORCED
+#   2c. Custom flow WITHOUT route_back_policy: verification→execution NOT ENFORCED
+#
+# Deterministic, no model spend, self-cleaning.
+# Usage: bash evals/integration/test_kit_identity_trust.sh
+
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+source "$ROOT/evals/lib/node.sh"
+
+TMP="$(mktemp -d)"
+errors=0
+
+_pass() { echo "  ✓ $1"; }
+_fail() { echo "  ✗ $1"; errors=$((errors + 1)); }
+
+cleanup() { rm -rf "$TMP"; }
+trap cleanup EXIT
+
+SIDECAR_JS="${ROOT}/build/src/cli/workflow-sidecar.js"
+SIDECAR_BUNDLE_WRITER="workflow-sidecar"
+
+echo ""
+echo "=== Fix 1: kitIdentityFromBundle reads kit from bundle claims (not hardcoded 'builder') ==="
+
+# ─── Write fixture bundle files (note: argv[2] = file path since argv[1] = "-" for stdin) ─────────
+
+node - "$TMP/knowledge.bundle" << 'NODE'
+const fs = require('fs');
+// argv[0]=node, argv[1]="-", argv[2]=file path
+const bundlePath = process.argv[2];
+const bundle = {
+  schemaVersion: 3, source: "test-fixture",
+  claims: [{
+    id: "c-knowledge-1", claimType: "knowledge.verify.tests",
+    subjectType: "flow-step", subjectId: "test-slug/knowledge-ev",
+    surface: "flow-agents.workflow", fieldOrBehavior: "knowledge verification",
+    value: "pass", status: "verified",
+    createdAt: "2026-06-27T00:00:00Z", updatedAt: "2026-06-27T00:00:00Z",
+    impactLevel: "high", verificationPolicyId: "policy:knowledge.verify.tests"
+  }],
+  evidence: [], policies: [], events: []
+};
+fs.writeFileSync(bundlePath, JSON.stringify(bundle, null, 2));
+NODE
+
+node - "$TMP/builder.bundle" << 'NODE'
+const fs = require('fs');
+const bundlePath = process.argv[2];
+const bundle = {
+  schemaVersion: 3, source: "test-fixture",
+  claims: [{
+    id: "c-builder-1", claimType: "builder.verify.tests",
+    subjectType: "flow-step", subjectId: "test-slug/builder-ev",
+    surface: "flow-agents.workflow", fieldOrBehavior: "builder verification",
+    value: "pass", status: "verified",
+    createdAt: "2026-06-27T00:00:00Z", updatedAt: "2026-06-27T00:00:00Z",
+    impactLevel: "high", verificationPolicyId: "policy:builder.verify.tests"
+  }],
+  evidence: [], policies: [], events: []
+};
+fs.writeFileSync(bundlePath, JSON.stringify(bundle, null, 2));
+NODE
+
+node - "$TMP/workflow-only.bundle" << 'NODE'
+const fs = require('fs');
+const bundlePath = process.argv[2];
+const bundle = {
+  schemaVersion: 3, source: "test-fixture",
+  claims: [{
+    id: "c-wf-1", claimType: "workflow.check.build",
+    subjectType: "workflow-check", subjectId: "test-slug/build",
+    surface: "flow-agents.workflow", fieldOrBehavior: "build check",
+    value: "pass", status: "verified",
+    createdAt: "2026-06-27T00:00:00Z", updatedAt: "2026-06-27T00:00:00Z",
+    impactLevel: "high", verificationPolicyId: "policy:workflow.check.build"
+  }],
+  evidence: [], policies: [], events: []
+};
+fs.writeFileSync(bundlePath, JSON.stringify(bundle, null, 2));
+NODE
+
+echo ""
+echo "=== 1a. KNOWLEDGE-TYPED bundle → kitIdentityFromBundle derives knowledge kit ==="
+KNOWLEDGE_BUNDLE="$TMP/knowledge.bundle"
+SIDECAR_JS_PATH="$SIDECAR_JS"
+node --input-type=module << JSEOF
+import { kitIdentityFromBundle } from '${SIDECAR_JS_PATH}';
+import { readFileSync } from 'node:fs';
+const raw = JSON.parse(readFileSync('${KNOWLEDGE_BUNDLE}', 'utf8'));
+const result = kitIdentityFromBundle(raw, '${KNOWLEDGE_BUNDLE}');
+if (result.kitId !== 'knowledge') throw new Error('Expected kitId=knowledge, got: ' + result.kitId);
+if (result.subject !== 'knowledge-kit') throw new Error('Expected subject=knowledge-kit, got: ' + result.subject);
+if (!result.claimType.startsWith('knowledge.')) throw new Error('Expected claimType to start with knowledge., got: ' + result.claimType);
+if (result.claimType === 'knowledge.trust.bundle') throw new Error('Should use the specific claim type, not the generic fallback, got: ' + result.claimType);
+JSEOF
+if [ $? -eq 0 ]; then
+  _pass "KNOWLEDGE bundle: kitId=knowledge, subject=knowledge-kit, claimType=knowledge.verify.tests (not builder)"
+else
+  _fail "KNOWLEDGE bundle: expected kitId=knowledge and subject=knowledge-kit, not builder hardcode"
+fi
+
+echo ""
+echo "=== 1b. BUILDER-TYPED bundle → kitIdentityFromBundle derives builder kit ==="
+BUILDER_BUNDLE="$TMP/builder.bundle"
+node --input-type=module << JSEOF
+import { kitIdentityFromBundle } from '${SIDECAR_JS_PATH}';
+import { readFileSync } from 'node:fs';
+const raw = JSON.parse(readFileSync('${BUILDER_BUNDLE}', 'utf8'));
+const result = kitIdentityFromBundle(raw, '${BUILDER_BUNDLE}');
+if (result.kitId !== 'builder') throw new Error('Expected kitId=builder, got: ' + result.kitId);
+if (result.subject !== 'builder-kit') throw new Error('Expected subject=builder-kit, got: ' + result.subject);
+if (!result.claimType.startsWith('builder.')) throw new Error('Expected claimType to start with builder., got: ' + result.claimType);
+JSEOF
+if [ $? -eq 0 ]; then
+  _pass "BUILDER bundle: kitId=builder, subject=builder-kit (correctly derived from claims, not hardcoded)"
+else
+  _fail "BUILDER bundle: expected kitId=builder and subject=builder-kit"
+fi
+
+echo ""
+echo "=== 1c. WORKFLOW-ONLY bundle (no kit-typed claim, no current.json) → unknown identity ==="
+ISOLATED_DIR="$TMP/isolated-session"
+mkdir -p "$ISOLATED_DIR"
+cp "$TMP/workflow-only.bundle" "$ISOLATED_DIR/workflow-only.bundle"
+WORKFLOW_BUNDLE="$ISOLATED_DIR/workflow-only.bundle"
+node --input-type=module << JSEOF
+import { kitIdentityFromBundle } from '${SIDECAR_JS_PATH}';
+import { readFileSync } from 'node:fs';
+const raw = JSON.parse(readFileSync('${WORKFLOW_BUNDLE}', 'utf8'));
+const result = kitIdentityFromBundle(raw, '${WORKFLOW_BUNDLE}');
+if (result.kitId !== 'unknown') throw new Error('Expected kitId=unknown (no kit-typed claim, no active flow), got: ' + result.kitId);
+if (result.subject !== 'unknown-kit') throw new Error('Expected subject=unknown-kit, got: ' + result.subject);
+if (result.claimType !== 'unknown.trust.bundle') throw new Error('Expected claimType=unknown.trust.bundle, got: ' + result.claimType);
+JSEOF
+if [ $? -eq 0 ]; then
+  _pass "WORKFLOW-ONLY bundle: kitId=unknown, subject=unknown-kit (never falls back to builder)"
+else
+  _fail "WORKFLOW-ONLY bundle: expected kitId=unknown (no hardcoded builder fallback)"
+fi
+
+echo ""
+echo "=== 1d. Full pipeline: record-evidence --surface-trust-json with knowledge fixture ==="
+PIPELINE_AROOT="$TMP/pipeline-test/.flow-agents"
+PIPELINE_SLUG="pipeline-kit-identity"
+PIPELINE_DIR="$PIPELINE_AROOT/$PIPELINE_SLUG"
+mkdir -p "$PIPELINE_AROOT"
+
+flow_agents_node "$SIDECAR_BUNDLE_WRITER" ensure-session \
+  --artifact-root "$PIPELINE_AROOT" \
+  --task-slug "$PIPELINE_SLUG" \
+  --title "Pipeline kit identity test" \
+  --summary "Proves record-evidence processes knowledge bundle without crashing." \
+  --criterion "Kit identity preserved" \
+  --timestamp "2026-06-27T10:00:00Z" > "$TMP/pipeline-ensure.out" 2>&1
+
+KNOWLEDGE_BUNDLE_PATH="$TMP/knowledge.bundle"
+if flow_agents_node "$SIDECAR_BUNDLE_WRITER" record-evidence "$PIPELINE_DIR" \
+  --verdict not_verified \
+  --surface-trust-json "$KNOWLEDGE_BUNDLE_PATH" \
+  --timestamp "2026-06-27T10:01:00Z" > "$TMP/pipeline-evidence.out" 2>&1; then
+  if [[ -f "$PIPELINE_DIR/trust.bundle" ]]; then
+    _pass "record-evidence --surface-trust-json with knowledge bundle completes (pipeline proof: fix is in production code path)"
+  else
+    _fail "record-evidence --surface-trust-json with knowledge bundle did not write trust.bundle"
+  fi
+else
+  _fail "record-evidence --surface-trust-json with knowledge bundle failed: $(cat "$TMP/pipeline-evidence.out")"
+fi
+
+echo ""
+echo "=== Fix 2: FlowDefinition-driven route-back guard ==="
+
+# ─── 2a. builder.build: verification→execution still enforced ─────────────────
+echo ""
+echo "=== 2a. builder.build route-back guard: still enforces verification→execution ==="
+BUILDER_DIR="$TMP/fix2-builder/.flow-agents/builder-fix2"
+mkdir -p "$TMP/fix2-builder/.flow-agents"
+
+flow_agents_node "$SIDECAR_BUNDLE_WRITER" ensure-session \
+  --artifact-root "$TMP/fix2-builder/.flow-agents" \
+  --task-slug "builder-fix2" \
+  --title "Fix2 builder route-back test" \
+  --summary "Verify builder.build route-back still enforced." \
+  --timestamp "2026-06-27T10:00:00Z" > "$TMP/fix2-builder-ensure.out" 2>&1
+
+flow_agents_node "$SIDECAR_BUNDLE_WRITER" advance-state "$BUILDER_DIR" \
+  --status verifying --phase verification \
+  --summary "Moving to verification." \
+  --flow-definition builder.build \
+  --timestamp "2026-06-27T10:01:00Z" > "$TMP/fix2-builder-verify.out" 2>&1
+
+if flow_agents_node "$SIDECAR_BUNDLE_WRITER" advance-state "$BUILDER_DIR" \
+  --status in_progress --phase execution \
+  --summary "Route back without reason." \
+  --flow-definition builder.build \
+  --timestamp "2026-06-27T10:02:00Z" > "$TMP/fix2-builder-noReason.out" 2>&1; then
+  _fail "builder.build route-back should require --route-back-reason"
+elif grep -q 'route_back_reason_required' "$TMP/fix2-builder-noReason.out"; then
+  _pass "builder.build: verification→execution requires --route-back-reason (identical behavior preserved)"
+else
+  _fail "builder.build route-back lacked expected diagnostic (got: $(cat "$TMP/fix2-builder-noReason.out"))"
+fi
+
+if flow_agents_node "$SIDECAR_BUNDLE_WRITER" advance-state "$BUILDER_DIR" \
+  --status in_progress --phase execution \
+  --summary "Route back with reason." \
+  --flow-definition builder.build \
+  --route-back-reason implementation_defect \
+  --timestamp "2026-06-27T10:03:00Z" > "$TMP/fix2-builder-withReason.out" 2>&1; then
+  _pass "builder.build: verification→execution with reason succeeds (identical behavior preserved)"
+else
+  _fail "builder.build route-back with reason should succeed (got: $(cat "$TMP/fix2-builder-withReason.out"))"
+fi
+
+# ─── 2b. Custom non-builder flow WITH route_back_policy: enforced ─────────────
+echo ""
+echo "=== 2b. Custom non-builder flow WITH route_back_policy: enforced ==="
+
+CUSTOM_FLOWS_DIR="$TMP/custom-flows"
+mkdir -p "$CUSTOM_FLOWS_DIR"
+
+# Write acme.deliver flow with route_back_policy (using argv[2] correctly)
+node - "$CUSTOM_FLOWS_DIR/acme.deliver.flow.json" << 'NODE'
+const fs = require('fs');
+const flowPath = process.argv[2];
+const flow = {
+  id: "acme.deliver", version: "1.0",
+  phase_map: { execution: "execute", verification: "verify" },
+  steps: [{ id: "execute", next: "verify" }, { id: "verify", next: "done" }, { id: "done", next: null }],
+  gates: {
+    "execute-gate": {
+      step: "execute",
+      expects: [{ id: "execution-scope", kind: "trust.bundle", required: true,
+        bundle_claim: { claimType: "acme.execute.scope", subjectType: "change", accepted_statuses: ["trusted","accepted"] } }]
+    },
+    "verify-gate": {
+      step: "verify",
+      on_route_back: { implementation_defect: "execute", missing_evidence: "verify", default: "verify" },
+      route_back_policy: { max_attempts: 2, on_exceeded: "block" },
+      expects: [{ id: "verify-evidence", kind: "trust.bundle", required: true,
+        bundle_claim: { claimType: "acme.verify.tests", subjectType: "flow-step", accepted_statuses: ["trusted","accepted"] } }]
+    }
+  }
+};
+fs.writeFileSync(flowPath, JSON.stringify(flow, null, 2));
+NODE
+
+ACME_DIR="$TMP/fix2-acme/.flow-agents/acme-fix2"
+mkdir -p "$TMP/fix2-acme/.flow-agents"
+
+flow_agents_node "$SIDECAR_BUNDLE_WRITER" ensure-session \
+  --artifact-root "$TMP/fix2-acme/.flow-agents" \
+  --task-slug "acme-fix2" \
+  --title "Fix2 acme route-back test" \
+  --summary "Verify non-builder flow with route_back_policy is enforced." \
+  --timestamp "2026-06-27T10:00:00Z" > "$TMP/fix2-acme-ensure.out" 2>&1
+
+# Set FLOW_AGENTS_FLOW_DEFS_DIR and export it for the duration of this block
+export FLOW_AGENTS_FLOW_DEFS_DIR="$CUSTOM_FLOWS_DIR"
+
+flow_agents_node "$SIDECAR_BUNDLE_WRITER" advance-state "$ACME_DIR" \
+  --status verifying --phase verification \
+  --summary "Moving acme to verification." \
+  --flow-definition acme.deliver \
+  --timestamp "2026-06-27T10:01:00Z" > "$TMP/fix2-acme-verify.out" 2>&1
+
+if flow_agents_node "$SIDECAR_BUNDLE_WRITER" advance-state "$ACME_DIR" \
+  --status in_progress --phase execution \
+  --summary "Acme route back without reason." \
+  --flow-definition acme.deliver \
+  --timestamp "2026-06-27T10:02:00Z" > "$TMP/fix2-acme-noReason.out" 2>&1; then
+  _fail "acme.deliver route-back should require --route-back-reason when route_back_policy is declared"
+elif grep -q 'route_back_reason_required' "$TMP/fix2-acme-noReason.out"; then
+  _pass "acme.deliver (non-builder): verification→execution requires reason when route_back_policy declared"
+else
+  _fail "acme.deliver route-back lacked expected diagnostic (got: $(cat "$TMP/fix2-acme-noReason.out"))"
+fi
+
+# Do 2 successful route-backs
+flow_agents_node "$SIDECAR_BUNDLE_WRITER" advance-state "$ACME_DIR" \
+  --status in_progress --phase execution \
+  --summary "Acme route back 1." --flow-definition acme.deliver \
+  --route-back-reason implementation_defect \
+  --timestamp "2026-06-27T10:03:00Z" > "$TMP/fix2-acme-rb1.out" 2>&1
+flow_agents_node "$SIDECAR_BUNDLE_WRITER" advance-state "$ACME_DIR" \
+  --status verifying --phase verification \
+  --summary "Back to verify." --flow-definition acme.deliver \
+  --timestamp "2026-06-27T10:04:00Z" > "$TMP/fix2-acme-fwd1.out" 2>&1
+flow_agents_node "$SIDECAR_BUNDLE_WRITER" advance-state "$ACME_DIR" \
+  --status in_progress --phase execution \
+  --summary "Acme route back 2." --flow-definition acme.deliver \
+  --route-back-reason implementation_defect \
+  --timestamp "2026-06-27T10:05:00Z" > "$TMP/fix2-acme-rb2.out" 2>&1
+flow_agents_node "$SIDECAR_BUNDLE_WRITER" advance-state "$ACME_DIR" \
+  --status verifying --phase verification \
+  --summary "Back to verify again." --flow-definition acme.deliver \
+  --timestamp "2026-06-27T10:06:00Z" > "$TMP/fix2-acme-fwd2.out" 2>&1
+
+# Third attempt should exceed max_attempts=2 (flow declares max 2, not hardcoded 3)
+if flow_agents_node "$SIDECAR_BUNDLE_WRITER" advance-state "$ACME_DIR" \
+  --status in_progress --phase execution \
+  --summary "Acme exceeds route-back limit." --flow-definition acme.deliver \
+  --route-back-reason implementation_defect \
+  --timestamp "2026-06-27T10:07:00Z" > "$TMP/fix2-acme-exceeded.out" 2>&1; then
+  _fail "acme.deliver should block after flow-declared max_attempts=2 route-backs"
+elif grep -q 'route_back_attempts_exceeded' "$TMP/fix2-acme-exceeded.out"; then
+  _pass "acme.deliver: blocks after flow-declared max_attempts=2 (not the hardcoded 3 from old builder code)"
+else
+  _fail "acme.deliver exceeded max_attempts but wrong diagnostic (got: $(cat "$TMP/fix2-acme-exceeded.out"))"
+fi
+
+unset FLOW_AGENTS_FLOW_DEFS_DIR
+
+# ─── 2c. Custom flow WITHOUT route_back_policy: NOT enforced ──────────────────
+echo ""
+echo "=== 2c. Custom flow WITHOUT route_back_policy: verification→execution NOT enforced ==="
+
+CUSTOM_FLOWS_DIR_2="$TMP/custom-flows-2"
+mkdir -p "$CUSTOM_FLOWS_DIR_2"
+
+node - "$CUSTOM_FLOWS_DIR_2/acme.nodecl.flow.json" << 'NODE'
+const fs = require('fs');
+const flowPath = process.argv[2];
+const flow = {
+  id: "acme.nodecl", version: "1.0",
+  phase_map: { execution: "execute", verification: "verify" },
+  steps: [{ id: "execute", next: "verify" }, { id: "verify", next: "done" }, { id: "done", next: null }],
+  gates: {
+    "verify-gate": {
+      step: "verify",
+      expects: [{ id: "verify-evidence", kind: "trust.bundle", required: true,
+        bundle_claim: { claimType: "acme.verify.tests", subjectType: "flow-step", accepted_statuses: ["trusted","accepted"] } }]
+    }
+  }
+};
+fs.writeFileSync(flowPath, JSON.stringify(flow, null, 2));
+NODE
+
+NODECL_DIR="$TMP/fix2-nodecl/.flow-agents/nodecl-fix2"
+mkdir -p "$TMP/fix2-nodecl/.flow-agents"
+
+flow_agents_node "$SIDECAR_BUNDLE_WRITER" ensure-session \
+  --artifact-root "$TMP/fix2-nodecl/.flow-agents" \
+  --task-slug "nodecl-fix2" \
+  --title "Fix2 nodecl route-back test" \
+  --summary "Verify flow without route_back_policy is not guarded." \
+  --timestamp "2026-06-27T10:00:00Z" > "$TMP/fix2-nodecl-ensure.out" 2>&1
+
+export FLOW_AGENTS_FLOW_DEFS_DIR="$CUSTOM_FLOWS_DIR_2"
+
+flow_agents_node "$SIDECAR_BUNDLE_WRITER" advance-state "$NODECL_DIR" \
+  --status verifying --phase verification \
+  --summary "Moving nodecl to verification." \
+  --flow-definition acme.nodecl \
+  --timestamp "2026-06-27T10:01:00Z" > "$TMP/fix2-nodecl-verify.out" 2>&1
+
+if flow_agents_node "$SIDECAR_BUNDLE_WRITER" advance-state "$NODECL_DIR" \
+  --status in_progress --phase execution \
+  --summary "Nodecl route back — should be free without reason." \
+  --flow-definition acme.nodecl \
+  --timestamp "2026-06-27T10:02:00Z" > "$TMP/fix2-nodecl-rb.out" 2>&1 \
+  && [[ ! -f "$NODECL_DIR/transition-attempts.json" ]]; then
+  _pass "acme.nodecl (no route_back_policy): verification→execution freely allowed, no attempts file"
+else
+  _fail "acme.nodecl without route_back_policy should allow route-back freely (got: $(cat "$TMP/fix2-nodecl-rb.out"))"
+fi
+
+unset FLOW_AGENTS_FLOW_DEFS_DIR
+
+echo ""
+echo "────────────────────────────────────────────"
+if [[ "$errors" -eq 0 ]]; then
+  echo "test_kit_identity_trust: all checks passed."
+  exit 0
+else
+  echo "test_kit_identity_trust: $errors check(s) FAILED."
+  exit 1
+fi

package/evals/run.sh

@@ -242,6 +242,8 @@ run_integration() {
   echo ""
   bash "$EVAL_DIR/integration/test_verify_cli.sh" || result=1
   echo ""
+  bash "$EVAL_DIR/integration/test_kit_identity_trust.sh" || result=1
+  echo ""
   bash "$EVAL_DIR/acceptance/prove-capture-teeth-declared.sh" || result=1
   return $result
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Flow Agents — a Kontour product that applies Flow and Veritas discipline as a portable process layer inside the agent tools you already use: Claude Code, Codex, Kiro, opencode, pi, and GitHub Actions — with framework adapters (AWS Strands preview) on the same policy-engine contract.",
   "keywords": [
     "agents",
@@ -136,15 +136,15 @@
     "kit": "npm run build --silent && node build/src/cli.js kit"
   },
   "devDependencies": {
-    "@types/node": "^22.19.19",
-    "promptfoo": "^0.121.15",
+    "@types/node": "^26.0.1",
+    "promptfoo": "^0.121.17",
     "typescript": "^6.0.3"
   },
   "dependencies": {
     "@kontourai/flow": "~1.3.0"
   },
   "optionalDependencies": {
-    "hachure": "^0.4.0",
+    "hachure": "^0.5.1",
     "@kontourai/surface": "^1.2.0"
   }
 }

package/scripts/hooks/stop-goal-fit.js

@@ -803,17 +803,30 @@ function canonicalJsonForVerify(record) {
 
 /**
  * Verify the hash chain of command-log.jsonl.
- * Returns { status, brokenAt } where:
- *   status  = "ok" | "legacy" | "broken"
+ * Returns { status, brokenAt, forkAt } where:
+ *   status  = "ok" | "legacy" | "broken" | "forked"
  *   brokenAt = index (0-based) of the first broken entry, or null
+ *   forkAt   = index (0-based) of the first concurrent-fork sibling, or null
+ *
+ * "forked" is a BENIGN concurrent-append race, not tampering: two PostToolUse
+ * captures appended off the same parent tip (e.g. parallel agents sharing one
+ * log) before the writer lock (flow-agents#232) serialized them. It is
+ * distinguished from "broken" because:
+ *   - every entry's hash is still self-consistent (no content was edited), and
+ *   - every entry's parent is reachable (nothing was reordered or removed);
+ *   - the only anomaly is a parent claimed by >1 capture-sourced sibling.
+ * Tamper — a content edit (self-hash mismatch), a reorder, or a deletion
+ * (unreachable parent) — still returns "broken". A fork cannot be used to
+ * launder a content edit: editing a record breaks its self-hash, which is
+ * checked before fork classification.
  */
 function verifyCommandLogChain(artifactDir) {
   const file = path.join(artifactDir, 'command-log.jsonl');
   let raw = '';
-  try { raw = fs.readFileSync(file, 'utf8'); } catch { return { status: 'legacy', brokenAt: null }; }
+  try { raw = fs.readFileSync(file, 'utf8'); } catch { return { status: 'legacy', brokenAt: null, forkAt: null }; }
 
   const lines = raw.split('\n').filter(l => l.trim());
-  if (lines.length === 0) return { status: 'legacy', brokenAt: null };
+  if (lines.length === 0) return { status: 'legacy', brokenAt: null, forkAt: null };
 
   // Parse all entries, tolerating unparseable lines (they count as legacy/unchained).
   const entries = [];
@@ -823,18 +836,25 @@ function verifyCommandLogChain(artifactDir) {
       if (entry && typeof entry === 'object') entries.push(entry);
     } catch { /* skip malformed lines */ }
   }
-  if (entries.length === 0) return { status: 'legacy', brokenAt: null };
+  if (entries.length === 0) return { status: 'legacy', brokenAt: null, forkAt: null };
 
   // Classify: are there any chained entries?
   const hasAnyChain = entries.some(e => e._chain && typeof e._chain.hash === 'string');
-  if (!hasAnyChain) return { status: 'legacy', brokenAt: null };
-
-  // Verify chain linkage. Legacy entries (no _chain) that precede the first
-  // chained entry are tolerated (mixed log during the upgrade transition).
-  // However, a chain entry following another chain entry must link correctly.
-  let prevHash = CHAIN_GENESIS_VERIFY;
+  if (!hasAnyChain) return { status: 'legacy', brokenAt: null, forkAt: null };
+
+  // Walk in file order. A chained entry is ACCEPTED when both:
+  //   (a) self-consistent: hash === sha256(prevHash + canonicalJson(record)),
+  //       so a content edit (e.g. flipping exitCode) without rehashing fails; and
+  //   (b) reachable: prevHash is genesis or the hash of any prior accepted entry.
+  // We track the SET of reachable hashes (not just the latest tip) so that
+  // concurrent-fork siblings — which share a still-reachable parent — are
+  // tolerated, while a reorder/deletion (parent not reachable) is caught.
+  const reachable = new Set([CHAIN_GENESIS_VERIFY]);
+  const parentSources = new Map(); // prevHash -> [source, ...] (fork detection)
   let prevWasChained = false;
-  let chainedCount = 0;
+  let forked = false;
+  let firstForkAt = null;
+
   for (let i = 0; i < entries.length; i++) {
     const entry = entries[i];
     const chain = entry._chain;
@@ -842,26 +862,43 @@ function verifyCommandLogChain(artifactDir) {
       // Legacy entry without _chain. If we have already seen a chained entry,
       // a gap in the chain (a legacy entry in the middle) counts as broken
       // (it could indicate a removed chained entry was replaced by a legacy one).
-      if (prevWasChained) return { status: 'broken', brokenAt: i };
+      if (prevWasChained) return { status: 'broken', brokenAt: i, forkAt: null };
       // Before any chained entry: tolerate (legacy prefix).
       continue;
     }
 
-    // This is a chained entry. Verify hash.
-    const expectedHash = crypto.createHash('sha256')
-      .update(prevHash + canonicalJsonForVerify(entry), 'utf8')
+    // (a) Self-consistency. A content edit without rehashing fails here.
+    if (typeof chain.prevHash !== 'string') return { status: 'broken', brokenAt: i, forkAt: null };
+    const selfHash = crypto.createHash('sha256')
+      .update(chain.prevHash + canonicalJsonForVerify(entry), 'utf8')
       .digest('hex');
-    if (chain.hash !== expectedHash) return { status: 'broken', brokenAt: i };
-
-    // Verify linkage: prevHash must match what this entry claims.
-    if (chain.prevHash !== prevHash) return { status: 'broken', brokenAt: i };
+    if (chain.hash !== selfHash) return { status: 'broken', brokenAt: i, forkAt: null };
+
+    // (b) Reachability. An unreachable parent means a reorder or a removed
+    // predecessor — structural tamper, not a benign concurrent append.
+    if (!reachable.has(chain.prevHash)) return { status: 'broken', brokenAt: i, forkAt: null };
+
+    // Fork detection: a parent claimed by more than one entry is a fork. It is
+    // benign only when EVERY sibling on that parent is a PostToolUse capture
+    // (two captures racing on the same tip). Any non-capture sibling on a
+    // shared parent is treated as tamper (conservative).
+    const sources = parentSources.get(chain.prevHash) || [];
+    sources.push(entry.source);
+    parentSources.set(chain.prevHash, sources);
+    if (sources.length > 1) {
+      if (!sources.every(s => s === 'postToolUse-capture')) {
+        return { status: 'broken', brokenAt: i, forkAt: null };
+      }
+      if (firstForkAt === null) firstForkAt = i;
+      forked = true;
+    }
 
-    prevHash = chain.hash;
+    reachable.add(chain.hash);
     prevWasChained = true;
-    chainedCount += 1;
   }
 
-  return { status: 'ok', brokenAt: null };
+  if (forked) return { status: 'forked', brokenAt: null, forkAt: firstForkAt };
+  return { status: 'ok', brokenAt: null, forkAt: null };
 }
 // ─────────────────────────────────────────────────────────────────────────────
 
@@ -1065,6 +1102,11 @@ function captureCrossReference(root, artifactDir, activeFlowStep) {
   //
   // ok     → proceed normally (chain is valid, log is trustworthy).
   // legacy → proceed normally (pre-B2 log, no chain to verify, existing behavior).
+  // forked → benign concurrent-append race (not tampering): emit a loud but
+  //          NON-blocking advisory and keep trusting the records. The capture
+  //          contradiction teeth still run (the records are genuine, just not
+  //          linearly ordered); the operator can re-linearize with the repair
+  //          tool. This is what stops honest parallel work from being trapped.
   // broken → emit a loud warning and treat ALL claimed-pass commands relying on
   //          this log as NOT_VERIFIED/blocking — do not let them sail through.
   let chainBroken = false;
@@ -1079,6 +1121,17 @@ function captureCrossReference(root, artifactDir, activeFlowStep) {
         'This is tamper-EVIDENCE (hash-chain broken); alteration, removal, or reordering detected. ' +
         'NOT_VERIFIED: cannot confirm or deny claimed passes.'
       );
+    } else if (chainResult.status === 'forked') {
+      // NOT a hard block: this string must not match HARD_BLOCK/FULL_BLOCK. A
+      // concurrent fork is benign — no content was edited and nothing was
+      // removed — so honest parallel work proceeds. We surface it loudly and
+      // point at the deterministic repair.
+      const forkIdx = chainResult.forkAt !== null ? ` (entry ${chainResult.forkAt})` : '';
+      warnings.push(
+        `${base} command-log shows a concurrent-capture fork${forkIdx} — two PostToolUse captures appended off the same parent ` +
+        '(parallel writers before the writer lock). This is NOT tampering: every record is self-consistent and reachable. ' +
+        'Records remain trusted; re-linearize with: node scripts/repair-command-log.js <artifact-dir>'
+      );
     }
   }