@kontourai/flow-agents 2.1.0 → 2.2.0

package/integrations/strands-ts/src/telemetry.ts

@@ -14,6 +14,11 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { randomUUID } from "node:crypto";
+import {
+  costForModel as pkgCostForModel,
+  currentPricingVersion as pkgPricingVersion,
+  setRegistry as setPkgRegistry
+} from "@kontourai/console-telemetry";
 
 // ESM has no __dirname; derive it (this package is "type":"module").
 const __filename = fileURLToPath(import.meta.url);
@@ -308,7 +313,12 @@ export class TelemetrySink {
 }
 
 // ---------------------------------------------------------------------------
-// Usage / cost — mirror of scripts/telemetry/pricing.json (per 1M tokens, USD)
+// Usage / cost — pricing math + registry shape come from the shared contract
+// package @kontourai/console-telemetry (single source). This sink only loads
+// the flow-agents authored registry (scripts/telemetry/pricing.json) and feeds
+// it to the package so cost prices against pricing.json rather than the
+// package's bundled fallback. Tokens are exact regardless; the console
+// recomputes cost authoritatively.
 // ---------------------------------------------------------------------------
 
 export interface TokenCounts {
@@ -331,37 +341,15 @@ interface NormalizedTokens {
   cacheRead: number;
 }
 
-// Pricing is read from the single-source registry (scripts/telemetry/pricing.json),
-// never hand-maintained here. Resolution: TELEMETRY_PRICING_FILE /
-// FLOW_AGENTS_PRICING_FILE env path, else the repo-relative registry, else a
-// minimal fallback. Tokens are exact regardless; the console recomputes cost
-// authoritatively, so a missing file only degrades the sink's stamped estimate.
-interface PricingVersionBlock {
-  cache_multipliers: { write_5m: number; write_1h: number; read: number };
-  models: Record<string, { input: number; output: number }>;
-  default: { input: number; output: number };
-  zero_cost_models: string[];
-}
-interface PricingRegistry {
-  current_version: string;
-  versions: Record<string, PricingVersionBlock>;
-}
-
-const FALLBACK_REGISTRY: PricingRegistry = {
-  current_version: "fallback",
-  versions: {
-    fallback: {
-      cache_multipliers: { write_5m: 1.25, write_1h: 2.0, read: 0.1 },
-      models: {},
-      default: { input: 5.0, output: 25.0 },
-      zero_cost_models: ["<synthetic>", "synthetic", "unknown", ""]
-    }
-  }
-};
-
-let cachedRegistry: PricingRegistry | null = null;
-function loadRegistry(): PricingRegistry {
-  if (cachedRegistry) return cachedRegistry;
+// Feed the package the flow-agents authored registry when present (its single
+// source of truth). Resolution: TELEMETRY_PRICING_FILE / FLOW_AGENTS_PRICING_FILE
+// env path, else the repo-relative registry. Runs once; on failure the package
+// keeps its bundled fallback. The console recomputes cost authoritatively, so a
+// missing file only degrades the sink's stamped estimate.
+let registryLoaded = false;
+function ensureRegistry(): void {
+  if (registryLoaded) return;
+  registryLoaded = true;
   const candidates = [
     process.env.TELEMETRY_PRICING_FILE,
     process.env.FLOW_AGENTS_PRICING_FILE,
@@ -372,19 +360,18 @@ function loadRegistry(): PricingRegistry {
     try {
       const parsed = JSON.parse(fs.readFileSync(candidate, "utf8"));
       if (parsed && typeof parsed.current_version === "string" && parsed.versions) {
-        cachedRegistry = parsed as PricingRegistry;
-        return cachedRegistry;
+        setPkgRegistry(parsed);
+        return;
       }
     } catch {
       // try next candidate
     }
   }
-  cachedRegistry = FALLBACK_REGISTRY;
-  return cachedRegistry;
 }
 
 function pricingVersion(): string {
-  return loadRegistry().current_version;
+  ensureRegistry();
+  return pkgPricingVersion();
 }
 
 function num(value: number | undefined): number {
@@ -405,17 +392,11 @@ function normalizeTokens(tokens: TokenCounts): NormalizedTokens {
 }
 
 function costForModel(model: string | undefined, tokens: NormalizedTokens): number {
-  const registry = loadRegistry();
-  const block = registry.versions[registry.current_version] ?? FALLBACK_REGISTRY.versions.fallback;
-  const key = (model ?? "").trim();
-  if (block.zero_cost_models.includes(key)) return 0;
-  const rate = block.models[key] ?? block.default;
-  const cm = block.cache_multipliers;
-  return round6(
-    (tokens.input * rate.input +
-      tokens.output * rate.output +
-      tokens.cacheCreation * rate.input * cm.write_5m +
-      tokens.cacheRead * rate.input * cm.read) /
-      1_000_000
-  );
+  ensureRegistry();
+  return pkgCostForModel(model, {
+    inputTokens: tokens.input,
+    outputTokens: tokens.output,
+    cacheCreationInputTokens: tokens.cacheCreation,
+    cacheReadInputTokens: tokens.cacheRead
+  });
 }

package/kits/knowledge/adapters/flow-runner/index.js

@@ -17,7 +17,7 @@
  *   - defaultSimilarityDetector         — pluggable similarity interface default (R3)
  *
  * Telemetry:
- *   Gate events are emitted to <workspace>/.telemetry/full.jsonl using
+ *   Gate events are emitted to <workspace>/.kontourai/telemetry/full.jsonl using
  *   canonical schema v0.3.0 events (preToolUse at gate entry, postToolUse at gate exit).
  *
  * Similarity Interface (R3):

package/kits/knowledge/adapters/flow-runner/telemetry.js

@@ -8,7 +8,7 @@
  * Zero runtime dependencies beyond Node.js built-ins.
  * Fails open: telemetry errors never block kit operations.
  *
- * Sink path: <workspace>/.telemetry/full.jsonl
+ * Sink path: <workspace>/.kontourai/telemetry/full.jsonl
  * The workspace is resolved from FLOW_AGENTS_WORKSPACE env var, falling back
  * to process.cwd().
  *
@@ -47,7 +47,7 @@ function schemaEventType(canonical) {
 
 function resolveSinkPath(workspace) {
   const ws = workspace || process.env.FLOW_AGENTS_WORKSPACE || process.cwd();
-  return path.join(ws, ".telemetry", "full.jsonl");
+  return path.join(ws, ".kontourai", "telemetry", "full.jsonl");
 }
 
 // ---------------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "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",
@@ -99,6 +99,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test:unit": "npm run build --silent && node --test src/cli/*.test.mjs",
     "validate:source": "npm run build --silent && node build/src/cli.js validate-source",
     "validate:artifacts": "npm run build --silent && node build/src/cli/validate-workflow-artifacts.js",
     "context-map": "npm run build --silent && node build/src/cli.js context-map",

package/scripts/README.md

@@ -70,6 +70,7 @@ renamed, or changes category, update the table and the validator together.
 | `lib/audit-transport.sh` | shared hook library | `evals/integration/test_hook_category_behaviors.sh`, `evals/integration/test_telemetry.sh` | Shared audit event transport functions. |
 | `lib/hook-flags.js` | shared hook library | `evals/integration/test_hook_category_behaviors.sh` | Shared profile/disable flag parsing. |
 | `lib/liveness-read.js` | shared hook library | `evals/integration/test_session_resume_roundtrip.sh` | Shared liveness event reader + freshness check (`readLivenessEvents`, `freshHolders`); consumed by the reground hook and `workflow-sidecar liveness status`. |
+| `lib/local-artifact-paths.js` | shared hook library | `evals/integration/test_migrate_local_artifacts.sh`, `evals/integration/test_workflow_sidecar_writer.sh` | Shared `.kontourai/flow-agents` artifact-root helpers with legacy `.flow-agents` read compatibility for CJS hooks. |
 | `lib/patterns.sh` | shared hook library | `evals/integration/test_hook_category_behaviors.sh`, `evals/integration/test_telemetry.sh` | Shared shell pattern constants. |
 | `lib/resolve-formatter.js` | shared hook library | `evals/integration/test_hook_category_behaviors.sh` | Shared formatter resolution helper. |
 

package/scripts/ci/trust-reconcile.js

@@ -61,6 +61,10 @@ const { spawnSync } = require('child_process');
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+// One normative definition shared with scripts/hooks/stop-goal-fit.js — the local
+// copy here had drifted (it was missing the trailing `/bin/true` check), which is
+// exactly why this is now imported rather than duplicated.
+const { hasLaunderingOperator } = require('../lib/command-log-chain.js');
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -80,29 +84,9 @@ function isPassingValue(v) {
   return v === true || v === 1 || v === 'true' || v === 'pass';
 }
 
-/**
- * Returns true when a command string contains an exit-code-laundering operator.
- * These operators mask real exit codes so the real sub-command may have failed silently.
- *
- * Rules (applied to claimed verification commands only):
- *   - ANY || operator — verify commands must not contain ||. This catches:
- *     || exit 0, || echo ok, || /bin/true, || true, || :, etc.
- *   - ; or newline followed by true / : / exit 0 — trailing success injection
- *
- * NOTE: Logic must stay identical to scripts/hooks/stop-goal-fit.js hasLaunderingOperator.
- * Centralize into a shared module as a follow-up (coordinate-free duplication for now).
- */
-function hasLaunderingOperator(cmd) {
-  // Flag ANY || operator — masks the exit code of the left-hand command.
-  if (/\|\|/.test(cmd)) return true;
-  // Flag ; or newline followed by true / : / exit 0
-  if (/[;\n]\s*true\b/.test(cmd)) return true;
-  if (/[;\n]\s*:\s*(?:$|\s|;|\n)/.test(cmd)) return true;
-  if (/[;\n]\s*exit\s+0\b/.test(cmd)) return true;
-  // Flag pipe to true (pipeline absorbs exit code)
-  if (/\|\s*true\b/.test(cmd)) return true;
-  return false;
-}
+// hasLaunderingOperator is imported from ../lib/command-log-chain.js (above) so this
+// CI reconciler and the stop-goal-fit verifier apply the identical exit-code-mask
+// heuristic — see that module for the rules.
 
 /**
  * Run a single shell command under bash, capturing exit code.

package/scripts/hooks/config-protection.js

@@ -40,6 +40,12 @@
  * any interpreter not in the list (ruby, php, etc.), and multiline here-docs.
  * The real anchor remains external (clean CI env + human review).
  *
+ * FROZEN bar-raiser (ADR 0018). The redirect / interpreter-write / cp-target detection
+ * is intentionally non-exhaustive and is NOT to be grown with new evasion-pattern rules.
+ * A newly-discovered self-tamper vector belongs in the external CI anchor (trust-reconcile
+ * does not trust agent-written files) and the required anti-gaming suite — not another
+ * local string matcher. Bug fixes that don't expand the pattern surface are still welcome.
+ *
  * Exit codes: 0 = allow, 2 = block
  */
 

package/scripts/hooks/evidence-capture.js

@@ -48,6 +48,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { flowAgentsArtifactRootsForRead } = require('./lib/local-artifact-paths');
 const crypto = require('crypto');
 
 const MAX_STDIN = 1024 * 1024;
@@ -62,43 +63,16 @@ const COMMAND_TOOL_NAME = /(^|[^a-z])(bash|shell|sh|exec|run|command|terminal|cm
 
 // ─── Hash-chain integrity (tamper-EVIDENCE) ───────────────────────────────────
 //
-// Genesis prevHash: a fixed arbitrary sentinel used when the log is empty or
-// the last entry has no _chain field (legacy record). This is NOT the SHA256 of
-// any specific input string — it is a fixed constant chosen for the original
-// implementation. (A previous comment incorrectly claimed it was
-// sha256("flow-agents:command-log:genesis"); that is wrong.)
-//
-// Writer (this file, CHAIN_GENESIS) and verifier (stop-goal-fit.js,
-// CHAIN_GENESIS_VERIFY) MUST use the same value. Do not change one without
-// changing the other — existing chained logs depend on this constant.
-//
-// HONEST FRAMING: this makes alteration DETECTABLE, not impossible. An agent
-// that rewrites all hashes can still forge the chain. The real tamper-proof
-// boundary is the signed checkpoint (B1). We do not oversell this boundary.
-const CHAIN_GENESIS = 'a3f9e2b7d5c84f1e6a0d2c3b9f7e1a4d8c6b5f2e9a0d3c7b1f4e8a2d6c0b9f3';
-
-/**
- * Stable canonical JSON for the chain input: the record WITHOUT the `_chain`
- * field, keys sorted alphabetically. This ensures the hash is independent of
- * key insertion order and that `_chain` itself does not contribute to its own
- * hash (circular dependency).
- */
-function canonicalJsonForChain(record) {
-  // Strip _chain if present (should not be, but defensive).
-  const keys = Object.keys(record).filter(k => k !== '_chain').sort();
-  const obj = {};
-  for (const k of keys) obj[k] = record[k];
-  return JSON.stringify(obj);
-}
-
-/**
- * Compute the sha256 hex hash for this chain link.
- * hash = sha256(prevHash + canonicalJson(record))
- */
-function computeChainHash(prevHash, record) {
-  const input = prevHash + canonicalJsonForChain(record);
-  return crypto.createHash('sha256').update(input, 'utf8').digest('hex');
-}
+// CHAIN_GENESIS is a fixed arbitrary sentinel — NOT the SHA256 of any specific
+// input string (a previous comment incorrectly claimed sha256("…:genesis")). The
+// writer here and the verifier in stop-goal-fit.js MUST canonicalize and seed
+// identically, so the genesis constant and the canonicalJson/hash helpers live in
+// ONE shared module that both import — divergence is structurally impossible.
+const {
+  CHAIN_GENESIS,
+  canonicalJsonForChain,
+  computeChainHash,
+} = require('../lib/command-log-chain.js');
 
 /**
  * Read the last entry from command-log.jsonl that has a `_chain` block.
@@ -224,18 +198,23 @@ function latestStateDir(flowAgentsDir) {
  * to the newest-mtime state.json directory.
  */
 function resolveArtifactDir(root) {
-  const flowAgentsDir = path.join(root, '.flow-agents');
-  const current = readJsonFile(path.join(flowAgentsDir, 'current.json'));
-  if (current) {
-    const slug = current.artifact_dir || current.active_slug;
-    if (typeof slug === 'string' && slug.trim()) {
-      // Guard against path traversal in the slug.
-      const safe = slug.replace(/\.\.+/g, '').replace(/^[/\\]+/, '');
-      const dir = path.join(flowAgentsDir, safe);
-      if (dir.startsWith(flowAgentsDir + path.sep) && fs.existsSync(dir)) return dir;
+  for (const flowAgentsDir of flowAgentsArtifactRootsForRead(root)) {
+    const current = readJsonFile(path.join(flowAgentsDir, 'current.json'));
+    if (current) {
+      const slug = current.artifact_dir || current.active_slug;
+      if (typeof slug === 'string' && slug.trim()) {
+        // Guard against path traversal in the slug.
+        const safe = slug.replace(/\.\.+/g, '').replace(/^[/\\]+/, '');
+        const dir = path.join(flowAgentsDir, safe);
+        if (dir.startsWith(flowAgentsDir + path.sep) && fs.existsSync(dir)) return dir;
+      }
     }
   }
-  return latestStateDir(flowAgentsDir);
+  for (const flowAgentsDir of flowAgentsArtifactRootsForRead(root)) {
+    const latest = latestStateDir(flowAgentsDir);
+    if (latest) return latest;
+  }
+  return null;
 }
 
 function isCommandTool(toolName, command) {

package/scripts/hooks/lib/local-artifact-paths.js

@@ -0,0 +1,32 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const KONTOURAI_DIR = '.kontourai';
+const LEGACY_FLOW_AGENTS_DIR = '.flow-agents';
+
+function flowAgentsArtifactRoot(cwd = process.cwd()) {
+  return path.resolve(cwd, KONTOURAI_DIR, 'flow-agents');
+}
+
+function legacyFlowAgentsArtifactRoot(cwd = process.cwd()) {
+  return path.resolve(cwd, LEGACY_FLOW_AGENTS_DIR);
+}
+
+function flowAgentsArtifactRootsForRead(cwd = process.cwd()) {
+  const roots = [flowAgentsArtifactRoot(cwd), legacyFlowAgentsArtifactRoot(cwd)];
+  return roots.filter((root, index) => roots.indexOf(root) === index && fs.existsSync(root));
+}
+
+function defaultArtifactRootForRead(cwd = process.cwd()) {
+  const roots = flowAgentsArtifactRootsForRead(cwd);
+  return roots[0] || flowAgentsArtifactRoot(cwd);
+}
+
+module.exports = {
+  flowAgentsArtifactRoot,
+  legacyFlowAgentsArtifactRoot,
+  flowAgentsArtifactRootsForRead,
+  defaultArtifactRootForRead,
+};

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

@@ -29,6 +29,20 @@ const path = require('path');
 const { spawnSync } = require('child_process');
 const crypto = require('crypto');
 
+// Hash-chain primitives + the exit-code-laundering heuristic come from ONE shared
+// module, so this verifier can never drift from the writer (evidence-capture.js).
+// CHAIN_GENESIS is re-aliased to CHAIN_GENESIS_VERIFY to preserve the long-standing
+// export name consumed by repair-command-log.js and the fork-classification eval.
+const {
+  CHAIN_GENESIS: CHAIN_GENESIS_VERIFY,
+  canonicalJsonForChain,
+  hasLaunderingOperator,
+} = require('../lib/command-log-chain.js');
+const {
+  flowAgentsArtifactRoot,
+  flowAgentsArtifactRootsForRead,
+} = require('./lib/local-artifact-paths');
+
 const MAX_STDIN = 1024 * 1024;
 const ACTIVE_STATUSES = new Set([
   'planning',
@@ -733,36 +747,10 @@ function claimAcknowledgesFailure(status, value) {
     || v === 'fail' || v === 'failed' || v === 'not_verified' || v === 'failing';
 }
 
-/**
- * Returns true when a command string contains an exit-code-neutralizing operator.
- * A claimed-pass check whose captured command uses one of these cannot be accepted as a
- * deterministic pass — the real sub-command may have failed silently.
- *
- * R6 extended logic (identical patterns used by scripts/ci/trust-reconcile.js — centralize
- * as a follow-up if drift becomes a maintenance concern):
- *   - ANY || operator is flagged. A legitimate verification command never needs || — its
- *     only purpose in a verification command is to mask the real exit code (e.g.
- *     `npm test || exit 0`, `npm test || echo ok`, `npm test || /bin/true`, `npm test || (exit 0)`).
- *   - | true  (single pipe into true — always exits 0)
- *   - Trailing ; or newline followed by: true  :  exit 0  /bin/true
- *
- * Fix D: applied in captureCrossReference's satisfied path and capturedFailReconciliation.
- */
-function hasLaunderingOperator(cmd) {
-  // ANY || in a claimed verification command is an exit-code mask.
-  // Legitimate verification commands never need || — its only purpose there is to
-  // suppress the real exit code (|| exit 0, || echo ok, || /bin/true, || (exit 0), etc.).
-  if (/\|\|/.test(cmd)) return true;
-  // | true  — single-pipe into true: `cmd | true` always exits 0 regardless of left-side exit code.
-  if (/\|\s*true\b/.test(cmd)) return true;
-  // Trailing ; or \n followed by exit-neutralizing commands (same threat, appended after the real cmd):
-  //   ; true    ; :    ; exit 0    ; /bin/true    (and \n variants)
-  if (/[;\n]\s*true\b/.test(cmd)) return true;
-  if (/[;\n]\s*:\s*(?:$|\s|;)/.test(cmd)) return true;
-  if (/[;\n]\s*exit\s+0\b/.test(cmd)) return true;
-  if (/[;\n]\s*\/bin\/true\b/.test(cmd)) return true;
-  return false;
-}
+// hasLaunderingOperator (the exit-code-mask heuristic) is imported from
+// ../lib/command-log-chain.js so this verifier and scripts/ci/trust-reconcile.js
+// share one normative definition. Applied in captureCrossReference's satisfied
+// path and capturedFailReconciliation.
 
 // ─── Hash-chain integrity verification (Increment B2, tamper-EVIDENCE) ────────
 //
@@ -786,20 +774,9 @@ function hasLaunderingOperator(cmd) {
 // The genesis prevHash is a fixed arbitrary sentinel — NOT the SHA256 of any
 // specific input string. The comment in evidence-capture.js previously (and
 // incorrectly) claimed it was sha256("flow-agents:command-log:genesis"); it is not.
-// Writer (evidence-capture.js CHAIN_GENESIS) and verifier (CHAIN_GENESIS_VERIFY here)
-// MUST use the same value. Do not change one without changing the other.
-const CHAIN_GENESIS_VERIFY = 'a3f9e2b7d5c84f1e6a0d2c3b9f7e1a4d8c6b5f2e9a0d3c7b1f4e8a2d6c0b9f3';
-
-/**
- * Canonical JSON for chain verification: record WITHOUT `_chain`, keys sorted.
- * Must be byte-identical to canonicalJsonForChain() in evidence-capture.js.
- */
-function canonicalJsonForVerify(record) {
-  const keys = Object.keys(record).filter(k => k !== '_chain').sort();
-  const obj = {};
-  for (const k of keys) obj[k] = record[k];
-  return JSON.stringify(obj);
-}
+// Both the genesis (CHAIN_GENESIS_VERIFY, imported above) and the canonical-JSON
+// helper (canonicalJsonForChain) come from ../lib/command-log-chain.js, the single
+// source the writer in evidence-capture.js imports too — so they cannot diverge.
 
 /**
  * Verify the hash chain of command-log.jsonl.
@@ -870,7 +847,7 @@ function verifyCommandLogChain(artifactDir) {
     // (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')
+      .update(chain.prevHash + canonicalJsonForChain(entry), 'utf8')
       .digest('hex');
     if (chain.hash !== selfHash) return { status: 'broken', brokenAt: i, forkAt: null };
 
@@ -1602,11 +1579,11 @@ const HARD_BLOCK = /contradicts evidence\.json|caught false-completion|evidence
 const FULL_BLOCK = /status:|Definition Of Done|Goal Fit|sidecar validation:|contradicts evidence\.json|workflow state|evidence verdict|evidence check|NOT_VERIFIED gap|critique status|critique open|next action|caught false-completion|NOT_VERIFIED —|command-log integrity check FAILED|gate misconfiguration:|surface unavailable —|expected capture log is missing|exit-code-laundered/;
 
 async function analyze(root, now = Date.now()) {
-  const flowAgentsDir = path.join(root, '.flow-agents');
+  const flowAgentsDirs = flowAgentsArtifactRootsForRead(root);
   // Scope to the session's current task when current.json names one, so an
   // unrelated active workflow elsewhere in the repo does not gate this stop.
-  const scoped = preferredArtifactDir(flowAgentsDir);
-  const searchDirs = scoped ? [scoped] : [flowAgentsDir];
+  const scoped = flowAgentsDirs.map(preferredArtifactDir).find(Boolean);
+  const searchDirs = scoped ? [scoped] : flowAgentsDirs;
   const artifacts = searchDirs
     .flatMap(dir => walkMarkdown(dir))
     .map(readArtifact)
@@ -1616,6 +1593,7 @@ async function analyze(root, now = Date.now()) {
   if (artifacts.length === 0) return { warnings: [], blocking: false };
 
   const latest = artifacts[0];
+  const latestArtifactDir = path.dirname(latest.file);
   const warnings = [];
   const relPath = relative(root, latest.file);
   const status = latest.status || 'unknown';
@@ -1631,11 +1609,11 @@ async function analyze(root, now = Date.now()) {
 
   // ADR 0016 P-c: load the active FlowDefinition gate (fail-open: null when absent).
   // Null → existing workflow.* fallback path unchanged. Non-null → expects[]-driven claim selection.
-  const activeFlowStep = loadActiveFlowStep(flowAgentsDir);
+  const activeFlowStep = loadActiveFlowStep(path.dirname(latestArtifactDir));
 
-  warnings.push(...sidecarValidation(root, path.dirname(latest.file)));
-  warnings.push(...sidecarGuidance(root, path.dirname(latest.file), activeFlowStep));
-  const captureWarnings = captureCrossReference(root, path.dirname(latest.file), activeFlowStep);
+  warnings.push(...sidecarValidation(root, latestArtifactDir));
+  warnings.push(...sidecarGuidance(root, latestArtifactDir, activeFlowStep));
+  const captureWarnings = captureCrossReference(root, latestArtifactDir, activeFlowStep);
   warnings.push(...captureWarnings);
   // Dedup: bundleEnforcement and captureCrossReference can both fire "caught false-completion"
   // for the same disputed claim. Suppress the bundleEnforcement warning ONLY when
@@ -1649,7 +1627,7 @@ async function analyze(root, now = Date.now()) {
     const m = /evidence check ([^\s:]+):/.exec(w);
     if (m) captureHardBlockIds.add(m[1]);
   }
-  const bundleWarnings = (await bundleEnforcement(path.dirname(latest.file), activeFlowStep)).filter(w => {
+  const bundleWarnings = (await bundleEnforcement(latestArtifactDir, activeFlowStep)).filter(w => {
     if (!captureHardBlockIds.size) return true;
     // bundleEnforcement warns: "trust.bundle claim disputed: <subjectId> ..."
     const m = /trust\.bundle claim (?:disputed|tampered): ([^\s(]+)/.exec(w);
@@ -1661,21 +1639,21 @@ async function analyze(root, now = Date.now()) {
     return !captureHardBlockIds.has(checkId);
   });
   warnings.push(...bundleWarnings);
-  warnings.push(...missingBundleOrStateSignal(path.dirname(latest.file), activeFlowStep));
+  warnings.push(...missingBundleOrStateSignal(latestArtifactDir, activeFlowStep));
 
   // A pre-execution task (not started) OR a terminal task (which is itself a
   // completion *claim*) must not block on mere incompleteness — but a FALSE claim
   // (capture/evidence contradiction) still blocks at any phase. This is the whole
   // point of the capture cross-reference: catch a task that falsely claims done.
-  const gateState = readJsonFile(path.join(path.dirname(latest.file), 'state.json'));
+  const gateState = readJsonFile(path.join(latestArtifactDir, 'state.json'));
   const taskStatus = gateState ? normalizedStatus(gateState.status) : normalizedStatus(status);
-  const preExecution = isPreExecution(path.dirname(latest.file), status);
+  const preExecution = isPreExecution(latestArtifactDir, status);
   const terminal = TERMINAL_STATUSES.has(taskStatus);
 
   // Namespace-agnostic captured-FAIL reconciliation (AC1 — closes the allowlist bypass).
   // Fix A: status-independent — runs on EVERY stop. A claim contradicting the capture
   // is a false-completion whether or not the agent says the task is 'done'.
-  warnings.push(...capturedFailReconciliation(root, path.dirname(latest.file), taskStatus));
+  warnings.push(...capturedFailReconciliation(root, latestArtifactDir, taskStatus));
 
   // Use module-scope HARD_BLOCK / FULL_BLOCK (defined above analyze()).
   // pre-execution/terminal tasks: only HARD_BLOCK signals cause a block.
@@ -1713,7 +1691,8 @@ function resolveMaxBlocks() {
 }
 
 function blockStreakFile(root) {
-  return path.join(root, '.flow-agents', '.goal-fit-block-streak.json');
+  const artifactRoot = flowAgentsArtifactRoot(root);
+  return path.join(artifactRoot, '.goal-fit-block-streak.json');
 }
 
 function reasonsHash(warnings) {

package/scripts/hooks/workflow-steering.js

@@ -17,6 +17,7 @@
 const fs = require('fs');
 const path = require('path');
 const { readLivenessEvents, freshHolders } = require('./lib/liveness-read');
+const { flowAgentsArtifactRootsForRead } = require('./lib/local-artifact-paths');
 
 const STEERING = {
   'tool-planner': [
@@ -101,7 +102,8 @@ function readJson(file) {
 }
 
 function latestWorkflowState(root) {
-  const states = walkStateFiles(path.join(root, '.flow-agents'))
+  const states = flowAgentsArtifactRootsForRead(root)
+    .flatMap(artifactRoot => walkStateFiles(artifactRoot))
     .map(file => {
       let stat;
       try { stat = fs.statSync(file); } catch { return null; }
@@ -295,8 +297,8 @@ function resumeSteering(root, current) {
 
     // Liveness advisory
     try {
-      const livenessFile = path.join(root, '.flow-agents', 'liveness', 'events.jsonl');
-      const events = readLivenessEvents(livenessFile);
+      const events = flowAgentsArtifactRootsForRead(root)
+        .flatMap(artifactRoot => readLivenessEvents(path.join(artifactRoot, 'liveness', 'events.jsonl')));
       if (events.length > 0) {
         const selfActor = (process.env.FLOW_AGENTS_ACTOR || '').trim() || 'local';
         const holders = freshHolders(events, slug, selfActor, Date.now());

package/scripts/lib/command-log-chain.js

@@ -0,0 +1,78 @@
+'use strict';
+//
+// Single normative source for the command-log hash-chain primitives and the
+// exit-code-laundering heuristic.
+//
+// These were previously copy-pasted across the writer (hooks/evidence-capture.js),
+// the verifier (hooks/stop-goal-fit.js), the repair tool (repair-command-log.js),
+// and CI reconcile (ci/trust-reconcile.js) under "keep byte-identical" comments —
+// the most security-sensitive path in the bundle, since the chain's integrity
+// claim rests on writer and verifier canonicalizing identically. The copies had
+// ALREADY drifted (ci/trust-reconcile's hasLaunderingOperator was missing the
+// trailing `/bin/true` check), which is exactly the failure mode duplication
+// invites. Importing from one module makes that divergence structurally impossible.
+//
+const crypto = require('crypto');
+
+// The genesis prevHash is a FIXED ARBITRARY SENTINEL — NOT the SHA256 of any
+// specific input string. (An earlier comment incorrectly claimed it was
+// sha256("flow-agents:command-log:genesis"); that is wrong.) Writer and verifier
+// MUST share this exact value — existing chained logs depend on it.
+//
+// HONEST FRAMING: this makes alteration DETECTABLE, not impossible. An agent that
+// rewrites all hashes can still forge the chain. The real tamper-proof boundary is
+// the signed checkpoint (B1). We do not oversell this boundary.
+const CHAIN_GENESIS = 'a3f9e2b7d5c84f1e6a0d2c3b9f7e1a4d8c6b5f2e9a0d3c7b1f4e8a2d6c0b9f3';
+
+/**
+ * Stable canonical JSON for a chain link: the record WITHOUT its `_chain` field,
+ * keys sorted alphabetically. This makes the hash independent of key insertion
+ * order and keeps `_chain` from contributing to its own hash.
+ */
+function canonicalJsonForChain(record) {
+  const keys = Object.keys(record).filter((k) => k !== '_chain').sort();
+  const obj = {};
+  for (const k of keys) obj[k] = record[k];
+  return JSON.stringify(obj);
+}
+
+/** Chain link hash: sha256(prevHash + canonicalJsonForChain(record)), hex. */
+function computeChainHash(prevHash, record) {
+  return crypto
+    .createHash('sha256')
+    .update(prevHash + canonicalJsonForChain(record), 'utf8')
+    .digest('hex');
+}
+
+/**
+ * True when a claimed verification command contains an exit-code-laundering
+ * operator. Legitimate verification commands never need these — their only
+ * purpose is to suppress a real non-zero exit:
+ *   - ANY `||`             (e.g. `npm test || exit 0`, `|| echo ok`, `|| /bin/true`)
+ *   - `| true`             (pipe into true — the pipeline absorbs the exit code)
+ *   - trailing `; true` / `; :` / `; exit 0` / `; /bin/true` (and `\n` variants)
+ *
+ * FROZEN bar-raiser (ADR 0018). Do NOT add new evasion-pattern rules here; route new
+ * laundering shapes to the external CI anchor (trust-reconcile + the anti-gaming suite).
+ * Accepted limitation: the blanket `||` rule over-blocks legitimate control-flow `||`
+ * (e.g. `test -d node_modules || npm ci`) — it fails toward blocking by design.
+ */
+function hasLaunderingOperator(cmd) {
+  // ANY || in a claimed verification command is an exit-code mask.
+  if (/\|\|/.test(cmd)) return true;
+  // | true — single-pipe into true always exits 0 regardless of the left side.
+  if (/\|\s*true\b/.test(cmd)) return true;
+  // Trailing ; or \n followed by an exit-neutralizing command:
+  if (/[;\n]\s*true\b/.test(cmd)) return true;
+  if (/[;\n]\s*:\s*(?:$|\s|;)/.test(cmd)) return true;
+  if (/[;\n]\s*exit\s+0\b/.test(cmd)) return true;
+  if (/[;\n]\s*\/bin\/true\b/.test(cmd)) return true;
+  return false;
+}
+
+module.exports = {
+  CHAIN_GENESIS,
+  canonicalJsonForChain,
+  computeChainHash,
+  hasLaunderingOperator,
+};