@kontourai/flow-agents 2.1.1 → 2.3.0

package/docs/adr/0018-freeze-local-shell-heuristics.md

@@ -0,0 +1,95 @@
+---
+title: "ADR 0018: Freeze the Local Shell-Parsing Heuristics; Route New Enforcement to the CI Anchor"
+---
+
+# ADR 0018: Freeze the Local Shell-Parsing Heuristics; Route New Enforcement to the CI Anchor
+
+Status: Accepted
+
+## Context
+
+ADR 0017 records the anti-gaming trust model: a **layered** defense whose *authoritative*
+boundary is the external CI anchor (`trust-reconcile.js` + the required anti-gaming suite),
+with the local Stop gate and `config-protection.js` as **Layer 1 bar-raisers** — explicitly
+"a bar-raiser, not a wall." That model was earned by a 7-round adversarial loop (PRs
+#213–#228), and ADR 0017 states the loop is "run to convergence."
+
+The local shell-parsing heuristics have nonetheless kept accreting per-round string-matching
+rules:
+
+- `config-protection.js` — redirect detection (`>`, `>>`, `tee`), interpreter-write
+  detection (`node -e`, `py -c`, `sed -i`, `perl -e`), and `cp`/`mv`/`install` target
+  matching, grown across R5a / R6 / R7.
+- `hasLaunderingOperator` (now in `scripts/lib/command-log-chain.js`) — the exit-code-mask
+  screen, extended in R6a / R7.
+
+Their **own headers already admit the ceiling**: *"An agent with shell access can still
+evade. The real anchor is external."* Each new round adds another regex for another evasion
+shape (runtime-constructed paths, base64, exotic tools, here-docs, …) while the set remains,
+by construction, non-exhaustive. This is **low-ROI churn** that also manufactures *false
+confidence* in a control ADR 0017 already classifies as best-effort.
+
+Worse, the pattern-chasing has a real cost beyond effort: the blanket `||` rule in
+`hasLaunderingOperator` flags **any** `||` in a claimed verification command, which
+**false-positives legitimate commands** that use `||` for control flow rather than exit-code
+laundering — e.g. `test -d node_modules || npm ci`, `command -v shellcheck || npm i -g shellcheck`.
+It errs toward blocking, which is acceptable for a bar-raiser but not something to keep
+extending.
+
+## Decision
+
+**Freeze the local shell-parsing heuristics as feature-complete bar-raisers.** Specifically:
+
+1. **No new evasion-pattern rules** are added to `config-protection.js`'s redirect/
+   interpreter/copy detection or to `hasLaunderingOperator`. The current rule sets are the
+   frozen surface. They stand as documented, intentionally-incomplete local bar-raisers.
+
+2. **New enforcement concerns route to the external anchor**, not to new local regex:
+   - a new way to launder a verification result → strengthen the CI **`trust-reconcile`**
+     reconciliation and add a case to the required **anti-gaming suite**
+     (`evals/ci/antigaming-suite.sh`);
+   - a new self-tamper / kill-switch vector → it is already defended structurally by Layer 2
+     (CI does not trust the agent's files or environment) and Layer 4 (CODEOWNERS + required
+     checks). Encode the *regression test* there, not another local path matcher.
+
+3. **Still allowed** under the freeze: correctness/bug fixes that do **not** expand the
+   pattern surface (e.g. removing a clear false-positive, consolidating duplicated copies as
+   in ops#20), and changes required to keep the existing rules working. The freeze targets
+   *scope growth*, not maintenance.
+
+The decisive line — already the consistent finding of ADR 0017 — is that a local control
+running inside the agent's environment cannot be made airtight by adding rules; effort spent
+making the bar-raiser taller has sharply diminishing returns once the external anchor exists.
+
+## Accepted limitations (documented, not closed)
+
+These are now **accepted properties** of the frozen Layer 1, with the CI anchor as the
+authoritative backstop:
+
+- **`config-protection.js` — incomplete coverage.** Runtime-constructed protected paths
+  (`homedir() + '/.bashrc'`), base64/multi-step path assembly, interpreters outside the
+  listed set (ruby, php, …), `rsync`/`dd`/process-substitution writes, and here-docs are
+  **not** caught. *Backstop:* Layer 2 does not trust those files; Layer 4 + human review.
+- **`hasLaunderingOperator` — blanket `||` over-blocks.** A legitimate verification command
+  that uses `||` for control flow is flagged as laundering. *Backstop / workaround:* split
+  the conditional out of the single claimed-verify command; CI reconciles the real result
+  regardless. We keep the blanket rule (fail-toward-blocking) rather than enumerate "safe"
+  `||` forms — enumeration is exactly the churn this ADR freezes.
+
+## Consequences
+
+- The adversarial-hardening loop is declared **converged at the local layer**: ongoing trust
+  investment goes to the external anchor (re-run freshness, reconciliation breadth, the
+  required suite, activation of `Trust Reconcile` as a no-bypass check — ADR 0017 §Activation,
+  issue #225), not to more local string parsing.
+- Reviewers can decline new "Round N" local-heuristic PRs by pointing here: the bar-raiser is
+  frozen by decision, and the gap belongs in the CI anchor.
+- No behavior change ships with this ADR. The heuristics keep doing exactly what they do; we
+  stop growing them and we write down why.
+
+## Related
+
+ADR 0017 (anti-gaming trust security model — the layered defense this freezes the local
+layer of), ADR 0016 (three-hard-boundary model), ADR 0010 (workflow trust state as a hachure
+bundle). Implements ops#21. Consolidation of the frozen helpers: ops#20
+(`scripts/lib/command-log-chain.js`).

package/docs/repository-structure.md

@@ -10,9 +10,10 @@ This is the canonical developer-facing map for the Flow Agents repository. Use i
 
 - Edit canonical source in the repo root areas listed below, then regenerate derived output with the documented commands.
 - Do not edit `dist/`, `build/`, or `_site/` by hand. They are generated from tracked source.
-- Do not commit local runtime state from `.flow-agents/<slug>/`, `.codex/`, `.claude/`, `.omx/`, `.promptfoo/`, `.telemetry/`, `.surface/`, `.veritas/`, or tool caches.
+- Do not commit local runtime state from `.flow-agents/<slug>/`, `.kontourai/`, `.codex/`, `.claude/`, `.omx/`, `.promptfoo/`, `.telemetry/`, `.surface/`, generated `.veritas/` output, or tool caches; intentionally tracked `.veritas/` governance/config remains durable source.
 - Runtime workflow artifacts stay local and ignored; promote reviewable or durable outcomes to docs, source, schemas, or provider records before merging to `main`.
 - Treat generated exports and installed runtime config as products of `packaging/manifest.json`, `src/tools/build-universal-bundles.ts`, `scripts/install-*.sh`, and the source directories they copy.
+- Use `.kontourai/` for non-durable local or generated Kontour workspace state. Keep durable tracked files in intuitive product-owned paths such as `.veritas/`, `.flow/`, `.agents/`, `.claude/commands`, and `docs/`; existing transition ignores remain during migration.
 
 ## Target Layout
 
@@ -32,7 +33,7 @@ This is the canonical developer-facing map for the Flow Agents repository. Use i
   docs/                        # durable docs and GitHub Pages source
   integrations/                # optional external integration config
   dist/ build/ _site/           # generated output; ignored
-  .flow-agents/ .codex/ .claude/ ... # local runtime state; ignored by default
+  .flow-agents/ .kontourai/ .codex/ .claude/ ... # local runtime state; ignored by default
 ```
 
 ## Top-Level Inventory
@@ -40,11 +41,12 @@ This is the canonical developer-facing map for the Flow Agents repository. Use i
 | Path | Classification | Source of truth | Generated or runtime policy | Safe cleanup rule |
 | --- | --- | --- | --- | --- |
 | `.flow-agents/` | runtime state | Workflow tools write local session artifacts. | Ignored. | Do not commit task runtime roots; promote durable decisions to docs, source, schemas, or providers before merge. |
+| `.kontourai/` | local/generated workspace state | Local Kontour tools and developer workflows. | Ignored. | Safe local cleanup when no active workflow needs it; durable source and decisions stay in product-owned tracked paths. |
 | `.claude/` | installed runtime config | Generated bundle or local runtime install. | Ignored. | Reinstall from `dist/claude-code/` instead of editing as source. |
 | `.codex/` | installed runtime config | Generated bundle or local runtime install. | Ignored. | Reinstall from `dist/codex/` or `scripts/install-codex-home.sh`; do not treat local hooks as canonical. |
 | `.githooks/` | canonical repo tooling | Tracked repository hook scripts. | Source, not runtime agent hooks. | Keep compatible with `npm run setup:repo-hooks` and `npm run validate:repo-hooks --`. |
 | `.github/` | canonical CI config | GitHub workflow files. | Source. | Preserve workflow command names and artifact expectations. |
-| `.ai/`, `.omx/`, `.promptfoo/`, `.surface/`, `.telemetry/`, `.veritas/` | runtime, cache, or integration output | Local tools and optional integrations. | Ignored runtime state. | Clean locally when not needed; promote only stable integration config under `integrations/` or durable docs. |
+| `.ai/`, `.omx/`, `.promptfoo/`, `.surface/`, `.telemetry/`, `.veritas/` | runtime, cache, or integration output | Local tools, optional integrations, and generated Veritas output. | Ignored runtime state, except intentionally tracked Veritas governance/config. | Clean locally when not needed; promote only stable integration config under `integrations/` or durable docs. |
 | `.venv/`, `node_modules/`, `test-results/`, `__pycache__/` | dependency/cache output | Package managers and test tools. | Ignored. | Safe local cleanup; recreate with normal install or test commands. |
 | `_site/` | generated docs output | Built from `docs/`. | Ignored. | Recreate with docs preview/build tooling. |
 | `agent-cards/` | canonical source | Discovery metadata for routable agents. | Exported into runtime bundles. | Do not delete without checking bundle manifests and evals. |
@@ -115,6 +117,8 @@ The package requires Node `>=22`, and GitHub Actions runs CI on Node 22. Keep `@
 
 `.flow-agents/<slug>/` is workflow working memory. Keep plans, sidecars, evidence, and handoffs there while work is active. Promote stable outcomes into `docs/`, schemas, source, or provider records before final acceptance.
 
+Across Kontour repos, `.kontourai/` is the simple ignored home for non-durable local/generated workspace state. It is not a durable source root. Keep durable governance, Flow config, agent source, command source, and documentation in the product-owned tracked paths where developers expect them, including `.veritas/`, `.flow/`, `.agents/`, `.claude/commands`, and `docs/`. Existing transition ignores such as `.flow-agents/`, `.kontour/`, `.surface/`, `.veritas/evidence/`, `.flow/runs/`, and `.telemetry/` remain in place during migration.
+
 `evals/fixtures/` ownership is tracked in [Fixture Ownership](fixture-ownership.md).
 Do not delete or add fixture directories without updating that inventory and the
 owning eval evidence.

package/evals/integration/test_bundle_lifecycle.sh

@@ -630,14 +630,14 @@ fi
 echo ""
 echo "--- opencode Plugin Hook Chain (end-to-end telemetry persistence) ---"
 # Execute the REAL generated plugin module under node, invoke its handlers,
-# and assert telemetry events persist inside the workspace .telemetry/ —
+# and assert telemetry events persist inside the workspace .kontourai/telemetry/ —
 # not the workspace PARENT. Pins three live-smoke findings (2026-06-11):
 #   1. spawning process.execPath fails under non-node hosts (NODE_BIN guard)
 #   2. empty stdin makes the telemetry pipeline silently skip the emit
 #   3. TELEMETRY_DATA_DIR escaping to the workspace parent (../../.. depth bug)
 CHAIN_WS="$TMPDIR_EVAL/plugin-chain-opencode"
 (cd "$ROOT_DIR/dist/opencode" && bash install.sh "$CHAIN_WS" >/dev/null 2>&1) || true
-rm -rf "$CHAIN_WS/.telemetry" "$TMPDIR_EVAL/.telemetry"
+rm -rf "$CHAIN_WS/.kontourai/telemetry" "$CHAIN_WS/.telemetry" "$TMPDIR_EVAL/.kontourai" "$TMPDIR_EVAL/.telemetry"
 
 if (cd "$CHAIN_WS" && node --input-type=module -e "
 const mod = await import('./.opencode/plugins/flow-agents.js');
@@ -653,21 +653,21 @@ fi
 # The telemetry emit is detached (disowned) and can take a few seconds to
 # land; poll rather than fixed-sleep.
 for _i in 1 2 3 4 5 6 7 8 9 10; do
-  [[ -s "$CHAIN_WS/.telemetry/full.jsonl" ]] && break
+  [[ -s "$CHAIN_WS/.kontourai/telemetry/full.jsonl" ]] && break
   sleep 1
 done
-if [[ -s "$CHAIN_WS/.telemetry/full.jsonl" ]] && node -e "
-  require('fs').readFileSync('$CHAIN_WS/.telemetry/full.jsonl','utf8').trim().split('\n').map(JSON.parse);
+if [[ -s "$CHAIN_WS/.kontourai/telemetry/full.jsonl" ]] && node -e "
+  require('fs').readFileSync('$CHAIN_WS/.kontourai/telemetry/full.jsonl','utf8').trim().split('\n').map(JSON.parse);
 " 2>/dev/null; then
-  _pass "opencode plugin: handlers persisted telemetry events in workspace .telemetry/"
+  _pass "opencode plugin: handlers persisted telemetry events in workspace .kontourai/telemetry/"
 else
-  _fail "opencode plugin: no telemetry events persisted in workspace .telemetry/"
+  _fail "opencode plugin: no telemetry events persisted in workspace .kontourai/telemetry/"
 fi
 
-if [[ ! -e "$TMPDIR_EVAL/.telemetry" ]]; then
+if [[ ! -e "$TMPDIR_EVAL/.kontourai/telemetry" && ! -e "$TMPDIR_EVAL/.telemetry" ]]; then
   _pass "opencode plugin: telemetry did not leak into the workspace parent directory"
 else
-  _fail "opencode plugin: telemetry leaked into workspace parent (.telemetry escape)"
+  _fail "opencode plugin: telemetry leaked into workspace parent"
 fi
 
 echo ""

package/evals/integration/test_gate_lockdown.sh

@@ -802,7 +802,9 @@ cp "$ROOT/scripts/lib/command-log-chain.js" "$ISO_LIBDIR/"
 # Create isolated node context that can't find @kontourai/surface
 ISO_DIR="$TMP/surface-iso"
 mkdir -p "$ISO_DIR/repo/.flow-agents/surftest"
+mkdir -p "$ISO_DIR/lib"
 cp "$GATE" "$ISO_DIR/stop-goal-fit.js"
+cp "$ROOT/scripts/hooks/lib/local-artifact-paths.js" "$ISO_DIR/lib/"
 printf '# Repo\n' > "$ISO_DIR/repo/AGENTS.md"
 # Non-terminal session (execution phase, in_progress status)
 printf '%s' '{"schema_version":"1.0","task_slug":"surftest","status":"in_progress","phase":"execution","updated_at":"2026-06-27T00:00:00Z","next_action":{"status":"in_progress","summary":"running"}}' \
@@ -846,7 +848,9 @@ echo "--- AC3.1b: Low-impact-only bundle with unavailable surface → NOT blocke
 
 ISO2_DIR="$TMP/surface-iso2"
 mkdir -p "$ISO2_DIR/repo/.flow-agents/lowtest"
+mkdir -p "$ISO2_DIR/lib"
 cp "$GATE" "$ISO2_DIR/stop-goal-fit.js"
+cp "$ROOT/scripts/hooks/lib/local-artifact-paths.js" "$ISO2_DIR/lib/"
 printf '# Repo\n' > "$ISO2_DIR/repo/AGENTS.md"
 printf '%s' '{"schema_version":"1.0","task_slug":"lowtest","status":"in_progress","phase":"execution","updated_at":"2026-06-27T00:00:00Z","next_action":{"status":"in_progress","summary":"running"}}' \
   > "$ISO2_DIR/repo/.flow-agents/lowtest/state.json"

package/evals/integration/test_migrate_local_artifacts.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+TMPDIR_EVAL="$(mktemp -d)"
+errors=0
+
+cleanup() { rm -rf "$TMPDIR_EVAL"; }
+trap cleanup EXIT
+
+_pass() { echo "  ✓ $1"; }
+_fail() { echo "  ✗ $1"; errors=$((errors + 1)); }
+
+REPO="$TMPDIR_EVAL/repo"
+mkdir -p \
+  "$REPO/.telemetry" \
+  "$REPO/.flow/runs/run-1" \
+  "$REPO/.surface/runs/run-2" \
+  "$REPO/.veritas/evidence" \
+  "$REPO/.veritas/repo-standards" \
+  "$REPO/.flow/definitions" \
+  "$REPO/.flow-agents/task"
+
+printf '%s\n' '{"event":1}' > "$REPO/.telemetry/full.jsonl"
+printf '%s\n' '{"run":1}' > "$REPO/.flow/runs/run-1/state.json"
+printf '%s\n' '{"surface":1}' > "$REPO/.surface/runs/run-2/latest.json"
+printf '%s\n' '{"evidence":1}' > "$REPO/.veritas/evidence/e.json"
+printf '%s\n' '{"durable":1}' > "$REPO/.veritas/repo-map.json"
+printf '%s\n' '{"standard":1}' > "$REPO/.veritas/repo-standards/std.json"
+printf '%s\n' '{"definition":1}' > "$REPO/.flow/definitions/main.json"
+printf '%s\n' '{"state":1}' > "$REPO/.flow-agents/task/state.json"
+ln -s "$REPO/.telemetry/full.jsonl" "$REPO/.telemetry/link.jsonl"
+
+if node "$ROOT/scripts/migrate-local-artifacts.mjs" --repo "$REPO" --json > "$TMPDIR_EVAL/dry.json"; then
+  if [[ ! -e "$REPO/.kontourai/telemetry/full.jsonl" ]] \
+    && node - "$TMPDIR_EVAL/dry.json" <<'NODE'
+const fs = require("node:fs");
+const data = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
+if (!data.summary.dry_run || data.summary.applied) throw new Error("expected dry-run");
+const text = JSON.stringify(data);
+for (const needle of [".telemetry/full.jsonl", ".flow/runs/run-1/state.json", ".surface/runs/run-2/latest.json", ".veritas/evidence/e.json"]) {
+  if (!text.includes(needle)) throw new Error(`missing copy plan ${needle}`);
+}
+for (const needle of [".veritas/repo-map.json", ".veritas/repo-standards", ".flow/definitions", ".flow-agents"]) {
+  if (!text.includes(needle)) throw new Error(`missing durable skip ${needle}`);
+}
+if (!text.includes("source-is-symlink")) throw new Error("missing symlink skip");
+NODE
+  then
+    _pass "migration script defaults to dry-run and reports generated copies plus durable skips"
+  else
+    _fail "migration dry-run output was wrong"
+  fi
+else
+  _fail "migration dry-run command failed"
+fi
+
+if node "$ROOT/scripts/migrate-local-artifacts.mjs" --repo "$REPO" --apply --include-flow-agents > "$TMPDIR_EVAL/apply.out"; then
+  if [[ -f "$REPO/.kontourai/telemetry/full.jsonl" ]] \
+    && [[ -f "$REPO/.kontourai/flow/runs/run-1/state.json" ]] \
+    && [[ -f "$REPO/.kontourai/surface/runs/run-2/latest.json" ]] \
+    && [[ -f "$REPO/.kontourai/veritas/evidence/e.json" ]] \
+    && [[ -f "$REPO/.kontourai/flow-agents/task/state.json" ]] \
+    && [[ -f "$REPO/.telemetry/full.jsonl" ]] \
+    && [[ -f "$REPO/.flow-agents/task/state.json" ]] \
+    && [[ ! -e "$REPO/.kontourai/veritas/repo-map.json" ]] \
+    && [[ ! -e "$REPO/.kontourai/flow/definitions/main.json" ]]; then
+    _pass "migration apply copies only generated allowlisted paths without deleting old files"
+  else
+    _fail "migration apply copied wrong files or deleted old files"
+  fi
+else
+  _fail "migration apply command failed"
+fi
+
+TARGET_SYMLINK_WORKSPACE="$TMPDIR_EVAL/target-symlink-workspace"
+TARGET_SYMLINK_REPO="$TARGET_SYMLINK_WORKSPACE/repo"
+OUTSIDE="$TMPDIR_EVAL/outside.txt"
+mkdir -p "$TARGET_SYMLINK_REPO/.telemetry" "$TARGET_SYMLINK_REPO/.kontourai/telemetry"
+printf '%s\n' '{"safe":true}' > "$TARGET_SYMLINK_REPO/.telemetry/full.jsonl"
+printf '%s\n' 'outside-original' > "$OUTSIDE"
+ln -s "$OUTSIDE" "$TARGET_SYMLINK_REPO/.kontourai/telemetry/full.jsonl"
+
+if node "$ROOT/scripts/migrate-local-artifacts.mjs" --repo "$TARGET_SYMLINK_REPO" --apply --force --json > "$TMPDIR_EVAL/target-symlink.json"; then
+  if [[ "$(cat "$OUTSIDE")" == "outside-original" ]] \
+    && node - "$TMPDIR_EVAL/target-symlink.json" <<'NODE'
+const fs = require("node:fs");
+const data = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
+const text = JSON.stringify(data);
+if (!text.includes("target-is-symlink")) throw new Error("missing target symlink skip");
+if (data.summary.copies !== 0) throw new Error(`expected no copies, got ${data.summary.copies}`);
+NODE
+  then
+    _pass "migration apply --force refuses target symlinks"
+  else
+    _fail "migration apply --force followed or failed to report target symlink"
+  fi
+else
+  _fail "migration apply --force target symlink command failed"
+fi
+
+exit "$errors"

package/evals/integration/test_workflow_sidecar_writer.sh

@@ -37,6 +37,40 @@ VALIDATOR="validate-workflow-artifacts"
 ARTIFACT_DIR="$TMPDIR_EVAL/repo/.flow-agents/auto-sidecars"
 mkdir -p "$ARTIFACT_DIR"
 
+DEFAULT_ROOT_REPO="$TMPDIR_EVAL/default-root-repo"
+mkdir -p "$DEFAULT_ROOT_REPO"
+if (cd "$DEFAULT_ROOT_REPO" && flow_agents_node "$WRITER" ensure-session \
+  --task-slug default-root \
+  --title "Default Root" \
+  --summary "Default root should use the Kontour runtime artifact home." \
+  --criterion "Default root exists" \
+  --timestamp "2026-05-09T00:00:00Z" >"$TMPDIR_EVAL/default-root.out" 2>"$TMPDIR_EVAL/default-root.err"); then
+  if [[ -f "$DEFAULT_ROOT_REPO/.kontourai/flow-agents/default-root/state.json" ]] \
+    && [[ -f "$DEFAULT_ROOT_REPO/.kontourai/flow-agents/current.json" ]] \
+    && [[ ! -e "$DEFAULT_ROOT_REPO/.flow-agents/default-root/state.json" ]]; then
+    _pass "sidecar writer defaults new sessions to .kontourai/flow-agents"
+  else
+    _fail "sidecar writer default root did not use .kontourai/flow-agents"
+  fi
+else
+  _fail "sidecar writer default-root ensure-session failed: $(cat "$TMPDIR_EVAL/default-root.out" "$TMPDIR_EVAL/default-root.err")"
+fi
+
+OLD_ROOT_REPO="$TMPDIR_EVAL/old-root-repo"
+mkdir -p "$OLD_ROOT_REPO/.flow-agents/old-session"
+cat > "$OLD_ROOT_REPO/.flow-agents/current.json" <<'JSON'
+{"schema_version":"1.0","active_slug":"old-session","artifact_dir":"old-session"}
+JSON
+cat > "$OLD_ROOT_REPO/.flow-agents/old-session/state.json" <<'JSON'
+{"schema_version":"1.0","task_slug":"old-session","status":"planned","phase":"planning","next_action":{"status":"continue","summary":"continue"}}
+JSON
+if (cd "$OLD_ROOT_REPO" && flow_agents_node "$WRITER" current --format slug >"$TMPDIR_EVAL/old-current.out" 2>"$TMPDIR_EVAL/old-current.err") \
+  && [[ "$(cat "$TMPDIR_EVAL/old-current.out")" == "old-session" ]]; then
+  _pass "sidecar writer reads legacy .flow-agents current session when no new root exists"
+else
+  _fail "sidecar writer did not read legacy current session: $(cat "$TMPDIR_EVAL/old-current.out" "$TMPDIR_EVAL/old-current.err")"
+fi
+
 SESSION_ROOT="$TMPDIR_EVAL/repo/.flow-agents"
 if flow_agents_node "$WRITER" ensure-session \
   --artifact-root "$SESSION_ROOT" \

package/evals/run.sh

@@ -140,6 +140,8 @@ run_static() {
   bash "$EVAL_DIR/static/test_console_presets.sh" || result=1
   echo ""
   bash "$EVAL_DIR/static/test_repo_hooks.sh" || result=1
+  echo ""
+  bash "$EVAL_DIR/static/test_unit_helpers.sh" || result=1
   return $result
 }
 

package/evals/static/test_unit_helpers.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# test_unit_helpers.sh — Layer 1: TypeScript-layer unit tests for the PURE
+# workflow-sidecar helpers (ops#22).
+#
+# Historically every assertion covering workflow-sidecar was black-box bash driving
+# the CLI. These node:test units exercise the pure projection/validation helpers
+# directly against the built JS — fast, deterministic, isolated — and complement
+# (do not replace) the bash evals.
+set -uo pipefail
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "$ROOT_DIR"
+
+echo "── TS pure-helper unit tests (node --test) ──"
+
+# The units import the build output. CI builds before evals; build here too when run
+# standalone so the test is self-sufficient.
+if [[ ! -f build/src/cli/workflow-sidecar.js ]]; then
+  npm run build --silent
+fi
+
+if node --test src/cli/*.test.mjs; then
+  echo "  PASS: workflow-sidecar pure-helper unit tests"
+else
+  echo "  FAIL: workflow-sidecar pure-helper unit tests"
+  exit 1
+fi

package/integrations/strands-ts/package.json

@@ -41,6 +41,9 @@
     "conformance:self": "node ../../packaging/conformance/run-conformance.js --self",
     "conformance": "node ../../packaging/conformance/run-conformance.js --adapter-cmd \"node bin/conformance-shim.mjs\" --level L2"
   },
+  "dependencies": {
+    "@kontourai/console-telemetry": "^0.1.0"
+  },
   "peerDependencies": {
     "@strands-agents/sdk": ">=1.0.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.1",
+  "version": "2.3.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/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;
@@ -197,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) {