@kontourai/flow-agents 2.1.0 → 2.2.0

package/build/src/index.js

@@ -15,6 +15,7 @@
  */
 import * as path from "node:path";
 import { loadJson as _loadJson, writeJson as _writeJson } from "./cli/workflow-sidecar.js";
+export { defaultArtifactRootForRead, defaultTelemetryDirForRead, defaultTelemetryDirsForRead, firstExistingPath, flowAgentsArtifactRoot, KONTOURAI_DIR, legacyFlowAgentsArtifactRoot, LEGACY_FLOW_AGENTS_DIR, legacyTelemetryDataDir, LEGACY_TELEMETRY_DIR, telemetryDataDir, } from "./lib/local-artifact-root.js";
 export { 
 // Trust-bundle (Hachure) validation — the same validator the writer uses.
 validateTrustBundle, 

package/build/src/lib/local-artifact-root.d.ts

@@ -0,0 +1,11 @@
+export declare const KONTOURAI_DIR = ".kontourai";
+export declare const LEGACY_FLOW_AGENTS_DIR = ".flow-agents";
+export declare const LEGACY_TELEMETRY_DIR = ".telemetry";
+export declare function flowAgentsArtifactRoot(cwd?: string): string;
+export declare function legacyFlowAgentsArtifactRoot(cwd?: string): string;
+export declare function telemetryDataDir(cwd?: string): string;
+export declare function legacyTelemetryDataDir(cwd?: string): string;
+export declare function firstExistingPath(candidates: string[]): string;
+export declare function defaultArtifactRootForRead(cwd?: string): string;
+export declare function defaultTelemetryDirForRead(cwd?: string): string;
+export declare function defaultTelemetryDirsForRead(cwd?: string): string[];

package/build/src/lib/local-artifact-root.js

@@ -0,0 +1,30 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+export const KONTOURAI_DIR = ".kontourai";
+export const LEGACY_FLOW_AGENTS_DIR = ".flow-agents";
+export const LEGACY_TELEMETRY_DIR = ".telemetry";
+export function flowAgentsArtifactRoot(cwd = process.cwd()) {
+    return path.resolve(cwd, KONTOURAI_DIR, "flow-agents");
+}
+export function legacyFlowAgentsArtifactRoot(cwd = process.cwd()) {
+    return path.resolve(cwd, LEGACY_FLOW_AGENTS_DIR);
+}
+export function telemetryDataDir(cwd = process.cwd()) {
+    return path.resolve(cwd, KONTOURAI_DIR, "telemetry");
+}
+export function legacyTelemetryDataDir(cwd = process.cwd()) {
+    return path.resolve(cwd, LEGACY_TELEMETRY_DIR);
+}
+export function firstExistingPath(candidates) {
+    return candidates.find((candidate) => fs.existsSync(candidate)) ?? candidates[0];
+}
+export function defaultArtifactRootForRead(cwd = process.cwd()) {
+    return firstExistingPath([flowAgentsArtifactRoot(cwd), legacyFlowAgentsArtifactRoot(cwd)]);
+}
+export function defaultTelemetryDirForRead(cwd = process.cwd()) {
+    return firstExistingPath([telemetryDataDir(cwd), legacyTelemetryDataDir(cwd)]);
+}
+export function defaultTelemetryDirsForRead(cwd = process.cwd()) {
+    const dirs = [telemetryDataDir(cwd), legacyTelemetryDataDir(cwd)];
+    return dirs.filter((dir, index) => dirs.indexOf(dir) === index && fs.existsSync(dir));
+}

package/build/src/tools/validate-source-tree.js

@@ -74,6 +74,7 @@ const hookFilePolicies = new Map([
     ["scripts/hooks/lib/audit-transport.sh", { category: "shared hook library", requiredNeedles: ["audit_emit"] }],
     ["scripts/hooks/lib/hook-flags.js", { category: "shared hook library", requiredNeedles: ["isHookEnabled"] }],
     ["scripts/hooks/lib/liveness-read.js", { category: "shared hook library", requiredNeedles: ["freshHolders", "readLivenessEvents"] }],
+    ["scripts/hooks/lib/local-artifact-paths.js", { category: "shared hook library", requiredNeedles: ["flowAgentsArtifactRoot", "defaultArtifactRootForRead"] }],
     ["scripts/hooks/lib/patterns.sh", { category: "shared hook library", requiredNeedles: ["_detect_secrets"] }],
     ["scripts/hooks/lib/resolve-formatter.js", { category: "shared hook library", requiredNeedles: ["resolveFormatter"] }],
 ]);

package/context/scripts/telemetry/lib/config.sh

@@ -7,10 +7,9 @@ TELEMETRY_CONFIG_FILE="${TELEMETRY_CONFIG_FILE:-${TELEMETRY_DIR}/telemetry.conf}
 # Defaults
 TELEMETRY_ENABLED="${TELEMETRY_ENABLED:-true}"
 # TELEMETRY_DIR is <workspace>/scripts/telemetry, so the workspace root is
-# two levels up. Three levels escaped into the workspace's PARENT directory
-# (caught by live acceptance smoke 2026-06-11: events landed in /tmp/.telemetry
-# instead of the installed workspace).
-TELEMETRY_DATA_DIR="${TELEMETRY_DATA_DIR:-$(cd "${TELEMETRY_DIR}/../.." && pwd)/.telemetry}"
+# two levels up. Local runtime telemetry defaults under .kontourai/telemetry;
+# explicit TELEMETRY_DATA_DIR still wins.
+TELEMETRY_DATA_DIR="${TELEMETRY_DATA_DIR:-$(cd "${TELEMETRY_DIR}/../.." && pwd)/.kontourai/telemetry}"
 TELEMETRY_SESSION_DIR="${TELEMETRY_SESSION_DIR:-${TELEMETRY_DATA_DIR}/sessions}"
 TELEMETRY_ENRICH_SYSTEM="${TELEMETRY_ENRICH_SYSTEM:-true}"
 TELEMETRY_ENRICH_WORKSPACE="${TELEMETRY_ENRICH_WORKSPACE:-true}"

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

@@ -790,10 +790,21 @@ echo "=== AC3.1 — Surface unavailable fail-closed ==="
 echo ""
 echo "--- AC3.1a: Isolated (no @kontourai/surface) with high-impact claim → BLOCKS ---"
 
+# The gate imports the shared scripts/lib/command-log-chain.js helpers. A real
+# install rsyncs the whole tree, so the lib always sits beside the hooks. Mirror that:
+# the isolated gates live at "$TMP/surface-iso*/stop-goal-fit.js", so "../lib" resolves
+# to "$TMP/lib" for both. This keeps the test exercising surface-unavailable fail-closed
+# (not a spurious module-not-found crash).
+ISO_LIBDIR="$TMP/lib"
+mkdir -p "$ISO_LIBDIR"
+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"}}' \
@@ -837,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"
@@ -1014,13 +1027,19 @@ else
 fi
 
 echo ""
-echo "--- AC3.3c: Both files use the SAME genesis constant value ---"
-genesis_ec=$(grep "const CHAIN_GENESIS = " "$ROOT/scripts/hooks/evidence-capture.js" | sed "s/.*= '//;s/'.*//")
-genesis_sg=$(grep "const CHAIN_GENESIS_VERIFY = " "$ROOT/scripts/hooks/stop-goal-fit.js" | sed "s/.*= '//;s/'.*//")
-if [ "$genesis_ec" = "$genesis_sg" ] && [ -n "$genesis_ec" ]; then
-  _pass "AC3.3: Both files use the same genesis constant ($genesis_ec)"
+echo "--- AC3.3c: genesis is single-sourced and imported by writer + verifier (cannot diverge) ---"
+# Stronger than the old "two literals match" check: the genesis literal now lives in
+# exactly ONE module, and both the writer and verifier import it — so divergence is
+# structurally impossible rather than merely currently-equal.
+genesis_lib=$(grep "const CHAIN_GENESIS = " "$ROOT/scripts/lib/command-log-chain.js" | sed "s/.*= '//;s/'.*//")
+if [ -n "$genesis_lib" ] \
+   && grep -q "require.*command-log-chain" "$ROOT/scripts/hooks/evidence-capture.js" \
+   && grep -q "require.*command-log-chain" "$ROOT/scripts/hooks/stop-goal-fit.js" \
+   && ! grep -qE "const CHAIN_GENESIS = '" "$ROOT/scripts/hooks/evidence-capture.js" \
+   && ! grep -qE "const CHAIN_GENESIS_VERIFY = '" "$ROOT/scripts/hooks/stop-goal-fit.js"; then
+  _pass "AC3.3: genesis single-sourced in scripts/lib/command-log-chain.js ($genesis_lib); writer + verifier import it, no divergent literal"
 else
-  _fail "AC3.3: Genesis constant mismatch: evidence-capture=$genesis_ec stop-goal-fit=$genesis_sg"
+  _fail "AC3.3: genesis not single-sourced (lib='$genesis_lib') or a divergent literal remains in a consumer"
 fi
 
 

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"
   },