@kontourai/flow-agents 2.0.0 → 2.0.1

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();

package/src/cli/workflow-sidecar.ts

@@ -6,7 +6,7 @@ import { createHash } from "node:crypto";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 // ADR 0016 Abstraction A: shared FlowDefinition resolver (P-a)
-import { resolveActiveFlowStep, resolveFlowFilePath, resolvePhaseMap, type ActiveFlowStep } from "../lib/flow-resolver.js";
+import { resolveActiveFlowStep, resolveFlowFilePath, resolvePhaseMap, resolveRouteBackPolicy, type ActiveFlowStep } from "../lib/flow-resolver.js";
 
 type AnyObj = Record<string, any>;
 
@@ -1026,21 +1026,71 @@ function deriveSurfaceStatus(ref: AnyObj): string {
   if (ref.integrity?.status !== "matched") return "fail";
   return "pass";
 }
+/**
+ * Derive kit identity from a parsed trust.bundle by structurally reading the
+ * DECLARED primary claim (kit-typed) rather than hardcoding "builder".
+ *
+ * Resolution order (no fallbacks to "builder"):
+ *   1. First non-workflow.* claim in bundle.claims[] → claimType drives kitId + subject.
+ *   2. No kit-typed claim: try current.json active_flow_id adjacent to the bundle file
+ *      (bundle lives at <session-dir>/trust.bundle → flowAgentsDir = grandparent).
+ *   3. Genuinely unknown: mark as "unknown" — never hardcode a kit identity.
+ */
+export function kitIdentityFromBundle(
+  raw: AnyObj,
+  bundleFile: string,
+): { claimType: string; kitId: string; subject: string; gateId: string } {
+  // 1. Structurally read the bundle's declared kit-typed claim.
+  const claims: AnyObj[] = Array.isArray(raw.claims) ? raw.claims : [];
+  for (const claim of claims) {
+    const ct = typeof claim?.claimType === "string" ? claim.claimType : "";
+    if (ct && !ct.startsWith("workflow.")) {
+      const kitId = ct.split(".")[0] ?? "unknown";
+      if (kitId && kitId !== "unknown") {
+        return { claimType: ct, kitId, subject: `${kitId}-kit`, gateId: ct };
+      }
+    }
+  }
+  // 2. No kit-typed claim in bundle — try to derive kit from current.json active_flow_id.
+  //    The bundle lives at <session-dir>/trust.bundle, so:
+  //      sessionDir = path.dirname(bundleFile)
+  //      flowAgentsDir = path.dirname(sessionDir)
+  try {
+    const sessionDir = path.dirname(bundleFile);
+    const flowAgentsDir = path.dirname(sessionDir);
+    const currentFile = path.join(flowAgentsDir, "current.json");
+    const current = JSON.parse(fs.readFileSync(currentFile, "utf8")) as Record<string, unknown>;
+    const flowId = typeof current["active_flow_id"] === "string" ? current["active_flow_id"] : null;
+    if (flowId && flowId.includes(".")) {
+      const kitId = flowId.split(".")[0]!;
+      if (kitId) {
+        const derivedClaimType = `${kitId}.trust.bundle`;
+        return { claimType: derivedClaimType, kitId, subject: `${kitId}-kit`, gateId: derivedClaimType };
+      }
+    }
+  } catch {
+    // Ignore — fall through to unknown
+  }
+  // 3. Genuinely unknown — never fallback to "builder".
+  return { claimType: "unknown.trust.bundle", kitId: "unknown", subject: "unknown-kit", gateId: "unknown.trust.bundle" };
+}
 function surfaceCheckFromArtifact(file: string, index: number): AnyObj {
   const raw = JSON.parse(read(file));
   const lower = JSON.stringify(raw).toLowerCase();
+  // Structurally read kit identity from the bundle — never hardcode "builder".
+  const { claimType: bundleClaimType, subject: bundleSubject, gateId: bundleGateId } = kitIdentityFromBundle(raw, file);
   let ref: AnyObj;
   if (lower.includes("provider") && lower.includes("absent")) {
-    ref = { artifact_kind: "trust.bundle", artifact_ref: file, gate_id: "provider.unavailable", claim_type: "builder.trust.bundle", claim_status: "unknown", subject: "builder-kit", freshness: { status: "unknown", summary: "No trust provider is configured" }, authority: { producer: "unknown", summary: "No trust provider is configured" }, integrity: { status: "unknown", summary: "Unknown" }, status: "not_verified", summary: "No trust provider is configured" };
+    ref = { artifact_kind: "trust.bundle", artifact_ref: file, gate_id: "provider.unavailable", claim_type: bundleClaimType, claim_status: "unknown", subject: bundleSubject, freshness: { status: "unknown", summary: "No trust provider is configured" }, authority: { producer: "unknown", summary: "No trust provider is configured" }, integrity: { status: "unknown", summary: "Unknown" }, status: "not_verified", summary: "No trust provider is configured" };
   } else if (lower.includes("artifact") && lower.includes("absent")) {
-    ref = { artifact_kind: "trust.bundle", artifact_ref: file, gate_id: "artifact.unavailable", claim_type: "builder.trust.bundle", claim_status: "unknown", subject: "builder-kit", freshness: { status: "unknown", summary: "Artifact not readable" }, authority: { producer: "unknown", summary: "Artifact not readable" }, integrity: { status: "unknown", summary: "Artifact not readable" }, status: "not_verified", summary: "artifact not readable" };
+    ref = { artifact_kind: "trust.bundle", artifact_ref: file, gate_id: "artifact.unavailable", claim_type: bundleClaimType, claim_status: "unknown", subject: bundleSubject, freshness: { status: "unknown", summary: "Artifact not readable" }, authority: { producer: "unknown", summary: "Artifact not readable" }, integrity: { status: "unknown", summary: "Artifact not readable" }, status: "not_verified", summary: "artifact not readable" };
   } else {
     const claimStatus = lower.includes("rejected") ? "rejected" : "accepted";
     const freshness = lower.includes("stale") ? "stale" : "fresh";
     const producer = lower.includes("missing-authority") ? "unknown" : "surface-local";
     const integrity = lower.includes("mismatch") ? "mismatch" : "matched";
     // Use trust.bundle as the canonical Hachure-aligned artifact_kind for all trust-backed evidence refs
-    ref = { artifact_kind: "trust.bundle", artifact_ref: file, gate_id: "builder.trust.bundle", claim_type: "builder.trust.bundle", claim_status: claimStatus, subject: "builder-kit", freshness: { status: freshness, summary: freshness === "fresh" ? "fresh" : "not currently verifiable" }, authority: { producer, summary: producer === "unknown" ? "missing authority" : "Local Surface trust producer." }, integrity: { status: integrity, summary: integrity === "matched" ? "matched" : "integrity mismatch" } };
+    ref = { artifact_kind: "trust.bundle", artifact_ref: file, gate_id: bundleGateId, claim_type: bundleClaimType, claim_status: claimStatus, subject: bundleSubject, freshness: { status: freshness, summary: freshness === "fresh" ? "fresh" : "not currently verifiable" }, authority: { producer, summary: producer === "unknown" ? "missing authority" : "Local Surface trust producer." }, integrity: { status: integrity, summary: integrity === "matched" ? "matched" : "integrity mismatch" } };
     ref.status = deriveSurfaceStatus(ref);
     ref.summary = ref.status === "pass" ? "accepted" : ref.status === "not_verified" ? "not currently verifiable" : (claimStatus === "rejected" ? "rejected" : producer === "unknown" ? "missing authority" : "integrity mismatch");
   }
@@ -1279,14 +1329,20 @@ async function advanceState(p: ReturnType<typeof parseArgs>): Promise<number> {
   const prev = loadJson(path.join(dir, "state.json"));
   if ((status === "archived" || status === "accepted") && prev.phase !== "learning") diagnostic(dir, "terminal_jump_rejected", "Terminal workflow states require release and learning gates.");
   const flow = opt(p, "flow-definition");
-  if (flow === "builder.build" && prev.phase === "verification" && phase === "execution") {
+  // Route-back guard: FlowDefinition-driven (not hardcoded to builder.build).
+  // Fires when the active flow's gate for prev.phase declares a route_back_policy
+  // AND the target phase maps to a step listed in on_route_back values.
+  // builder.build verify-gate already carries this declaration — behavior preserved.
+  const repoRoot = flow ? findRepoRootFromDir(dir) : "";
+  const routeBack = flow ? resolveRouteBackPolicy(flow, prev.phase, phase, repoRoot) : null;
+  if (routeBack) {
     const reason = opt(p, "route-back-reason");
-    if (!reason) diagnostic(dir, "route_back_reason_required", "Builder Kit route-back requires implementation_defect or equivalent reason.");
+    if (!reason) diagnostic(dir, "route_back_reason_required", `Route-back from ${prev.phase} to ${phase} requires a --route-back-reason (e.g. implementation_defect).`);
     const file = path.join(dir, "transition-attempts.json");
     const attempts = loadJson(file);
-    const key = `verification->execution:${reason}`;
+    const key = `${prev.phase}->${phase}:${reason}`;
     const count = attempts[key]?.count ?? 0;
-    if (count >= 3) diagnostic(dir, "route_back_attempts_exceeded", "Builder Kit route-back attempts exceeded.");
+    if (count >= routeBack.maxAttempts) diagnostic(dir, "route_back_attempts_exceeded", `Route-back attempt limit (${routeBack.maxAttempts}) exceeded for ${prev.phase}→${phase}.`);
     attempts[key] = { count: count + 1, reason, updated_at: opt(p, "timestamp", now()) };
     writeJson(file, attempts);
   }
@@ -1300,7 +1356,7 @@ async function advanceState(p: ReturnType<typeof parseArgs>): Promise<number> {
   // --step-id individually. The repoRoot is derived by walking up from dir to find kits/.
   if (flow) {
     const root = path.resolve(opt(p, "artifact-root", path.dirname(dir)));
-    const repoRoot = findRepoRootFromDir(dir);
+    // repoRoot already computed above when flow is present
     const phaseMap = resolvePhaseMap(flow, repoRoot);
     const stepId = phaseMap?.[phase] ?? undefined;
     if (stepId) {

package/src/lib/flow-resolver.ts

@@ -124,6 +124,10 @@ export type ActiveFlowStep = {
 type FlowGate = {
   step: string;
   expects?: GateExpectation[];
+  /** Reason-to-step mapping for route-back transitions (e.g. {"implementation_defect": "execute"}). */
+  on_route_back?: Record<string, string>;
+  /** Policy governing route-back attempt limits. */
+  route_back_policy?: { max_attempts: number; on_exceeded: string };
 };
 
 /** Shape of a FlowDefinition JSON file. */
@@ -282,3 +286,84 @@ export function resolveActiveFlowStep(flowAgentsDir: string): ActiveFlowStep | n
   const repoRoot = findRepoRoot(path.dirname(flowAgentsDir));
   return resolveFlowStep(flowId, stepId, repoRoot);
 }
+
+/** The resolved route-back policy for a phase transition. */
+export type RouteBackPolicy = {
+  /** Maximum allowed route-back attempts for this transition key. */
+  maxAttempts: number;
+  /** Action when attempts are exceeded (e.g. "block"). */
+  onExceeded: string;
+  /** The step id whose gate declared this policy (e.g. "verify"). */
+  fromStepId: string;
+};
+
+/**
+ * Resolve the route-back policy for a phase transition, if the active FlowDefinition
+ * declares one on the source phase's gate.
+ *
+ * A route-back is a transition where the source phase's gate declares both
+ * `route_back_policy` and `on_route_back`, and the target phase maps to a step
+ * listed as a route-back target in `on_route_back` values.
+ *
+ * This is the FlowDefinition-driven replacement for the hardcoded
+ * `flow === "builder.build" && prev.phase === "verification" && phase === "execution"`
+ * guard in advance-state. Any flow that declares `route_back_policy` on a gate
+ * automatically gets route-back enforcement without code changes.
+ *
+ * @param flowId    e.g. "builder.build" — kitId is the prefix before the first ".".
+ * @param fromPhase Lifecycle phase leaving (e.g. "verification").
+ * @param toPhase   Lifecycle phase entering (e.g. "execution").
+ * @param repoRoot  Absolute path to the repository root (kits/ lives here).
+ * @returns RouteBackPolicy when the transition is a declared route-back, null otherwise.
+ */
+export function resolveRouteBackPolicy(
+  flowId: string,
+  fromPhase: string,
+  toPhase: string,
+  repoRoot: string,
+): RouteBackPolicy | null {
+  if (!flowId || !fromPhase || !toPhase) return null;
+  const dotIdx = flowId.indexOf(".");
+  if (dotIdx < 1) return null;
+  const kitId = flowId.slice(0, dotIdx);
+  const flowName = flowId.slice(dotIdx + 1);
+  if (!kitId || !flowName) return null;
+
+  const flowFilePath = resolveFlowFilePath(kitId, flowName, flowId, repoRoot);
+  if (!flowFilePath) return null;
+
+  let flowDef: FlowDefinition;
+  try {
+    const raw = fs.readFileSync(flowFilePath, "utf8");
+    flowDef = JSON.parse(raw) as FlowDefinition;
+  } catch {
+    return null; // ENOENT, permission error, or parse error — fail-open
+  }
+
+  if (!flowDef || typeof flowDef !== "object") return null;
+  const phaseMap = flowDef.phase_map;
+  if (!phaseMap || typeof phaseMap !== "object" || Array.isArray(phaseMap)) return null;
+
+  const fromStep = phaseMap[fromPhase];
+  const toStep = phaseMap[toPhase];
+  if (!fromStep || !toStep) return null; // phases not in this flow
+
+  if (!flowDef.gates) return null;
+  for (const gate of Object.values(flowDef.gates)) {
+    if (!gate || gate.step !== fromStep) continue;
+    if (!gate.route_back_policy || !gate.on_route_back) return null;
+    // Check if toStep is a valid route-back target declared in on_route_back
+    const routeBackTargets = Object.values(gate.on_route_back);
+    if (!routeBackTargets.includes(toStep)) return null;
+    const maxAttempts =
+      typeof gate.route_back_policy.max_attempts === "number"
+        ? gate.route_back_policy.max_attempts
+        : 3;
+    return {
+      maxAttempts,
+      onExceeded: gate.route_back_policy.on_exceeded ?? "block",
+      fromStepId: fromStep,
+    };
+  }
+  return null;
+}