@kontourai/flow-agents 2.1.1 → 2.3.0

package/.github/CODEOWNERS

@@ -27,3 +27,5 @@
 # FlowDefinition resolution + the trust producer/checkpoint/signing the gate depends on
 /src/lib/flow-resolver.ts       @briananderson1222
 /src/cli/workflow-sidecar.ts    @briananderson1222
+# Modules decomposed out of workflow-sidecar.ts (ops#22) keep the same ownership.
+/src/cli/sidecar-*.ts           @briananderson1222

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## [2.3.0](https://github.com/kontourai/flow-agents/compare/v2.2.0...v2.3.0) (2026-07-01)
+
+
+### Features
+
+* **strands-ts:** consume @kontourai/console-telemetry for pricing/cost ([eb878b0](https://github.com/kontourai/flow-agents/commit/eb878b024a166b68d5cef00cd659311de9c7b49b))
+
+## [2.2.0](https://github.com/kontourai/flow-agents/compare/v2.1.1...v2.2.0) (2026-06-30)
+
+
+### Features
+
+* **strands-ts:** consume @kontourai/console-telemetry for pricing/cost ([#243](https://github.com/kontourai/flow-agents/issues/243)) ([eba7ff3](https://github.com/kontourai/flow-agents/commit/eba7ff39433f602e7e17b17164a84fa187aa3dc8))
+
+
+### Fixes
+
+* **flow-agents:** expose kontourai artifact roots ([#258](https://github.com/kontourai/flow-agents/issues/258)) ([82db131](https://github.com/kontourai/flow-agents/commit/82db1319e9115820c606c71c40087c05b1278fce))
+
+
+### Documentation
+
+* **flow-agents:** ADR 0018 — freeze local shell-parsing heuristics (ops[#21](https://github.com/kontourai/flow-agents/issues/21)) ([#255](https://github.com/kontourai/flow-agents/issues/255)) ([777fc50](https://github.com/kontourai/flow-agents/commit/777fc5029409f85bb3097da7f3141e3b4783a789))
+
+
+### Refactoring
+
+* **flow-agents:** extract a pure seam from workflow-sidecar + add TS unit layer (ops[#22](https://github.com/kontourai/flow-agents/issues/22)) ([#257](https://github.com/kontourai/flow-agents/issues/257)) ([7af3f44](https://github.com/kontourai/flow-agents/commit/7af3f44fb1d4c05e155da9e4f6090f1a99b534ef))
+
 ## [2.1.1](https://github.com/kontourai/flow-agents/compare/v2.1.0...v2.1.1) (2026-06-29)
 
 

package/build/src/cli/sidecar-claim-explain.d.ts

@@ -0,0 +1,45 @@
+type AnyObj = Record<string, any>;
+export interface ClaimEvidenceItem {
+    evidenceType: string;
+    label: string;
+    execution: {
+        runner: string;
+        label: string;
+        isError: boolean;
+        exitCode: number | null;
+    } | null;
+    passing: boolean;
+    summary: string;
+}
+export interface ClaimExplanation {
+    found: boolean;
+    status: string;
+    value: string;
+    claimType: string;
+    evidence: ClaimEvidenceItem[];
+    policy: {
+        id: string;
+        requiredEvidence: string[];
+        requiredMethods?: string[];
+        acceptanceCriteria: string[];
+        reviewAuthority: string;
+    } | null;
+    why: {
+        directInputs: AnyObj[];
+        leafClaims: AnyObj[];
+        diagnostics: AnyObj[];
+        transparencyGaps: AnyObj[];
+        changeRecords: AnyObj[];
+    };
+}
+/**
+ * Build a structured explanation for a specific claim.
+ * PURE: report + bundle + id in, structured explanation out.
+ * No fs, no CLI, no .flow-agents paths. Promotable to Surface #171.
+ *
+ * @param report   TrustReport from buildTrustReport(bundle) — required for derived status
+ * @param bundle   Raw parsed trust.bundle (BundleFile shape)
+ * @param claimId  The claim id to explain
+ */
+export declare function buildClaimExplanation(report: Record<string, unknown>, bundle: Record<string, unknown>, claimId: string): ClaimExplanation;
+export {};

package/build/src/cli/sidecar-claim-explain.js

@@ -0,0 +1,87 @@
+// Claim explanation — a PURE projection extracted from workflow-sidecar.ts (ops#22).
+//
+// buildClaimExplanation is a pure function: report + bundle + id in, structured
+// explanation out. No fs, no CLI, no .flow-agents paths, no shared module state —
+// zero flow-agents specifics inside it, so it is unit-testable in isolation and can
+// be lifted to Surface unchanged (issue #171). The IO command handler `claimLookup`
+// that consumes it stays in workflow-sidecar.ts.
+/**
+ * Build a structured explanation for a specific claim.
+ * PURE: report + bundle + id in, structured explanation out.
+ * No fs, no CLI, no .flow-agents paths. Promotable to Surface #171.
+ *
+ * @param report   TrustReport from buildTrustReport(bundle) — required for derived status
+ * @param bundle   Raw parsed trust.bundle (BundleFile shape)
+ * @param claimId  The claim id to explain
+ */
+export function buildClaimExplanation(report, bundle, claimId) {
+    const reportClaims = Array.isArray(report.claims) ? report.claims : [];
+    const reportClaim = reportClaims.find((c) => c.id === claimId);
+    if (!reportClaim) {
+        return {
+            found: false,
+            status: "unknown",
+            value: "",
+            claimType: "",
+            evidence: [],
+            policy: null,
+            why: { directInputs: [], leafClaims: [], diagnostics: [], transparencyGaps: [], changeRecords: [] },
+        };
+    }
+    const bundleClaims = Array.isArray(bundle.claims) ? bundle.claims : [];
+    const bundleClaim = bundleClaims.find((c) => c.id === claimId) ?? reportClaim;
+    const bundlePolicies = Array.isArray(bundle.policies) ? bundle.policies : [];
+    const bundleEvidence = Array.isArray(bundle.evidence) ? bundle.evidence : [];
+    // Governing policy — follow verificationPolicyId into bundle.policies[]
+    const verificationPolicyId = typeof bundleClaim.verificationPolicyId === "string" ? bundleClaim.verificationPolicyId : undefined;
+    const rawPolicy = verificationPolicyId ? bundlePolicies.find((p) => p.id === verificationPolicyId) : undefined;
+    const policy = rawPolicy
+        ? {
+            id: String(rawPolicy.id ?? ""),
+            requiredEvidence: Array.isArray(rawPolicy.requiredEvidence) ? rawPolicy.requiredEvidence : [],
+            requiredMethods: Array.isArray(rawPolicy.requiredMethods) ? rawPolicy.requiredMethods : undefined,
+            acceptanceCriteria: Array.isArray(rawPolicy.acceptanceCriteria) ? rawPolicy.acceptanceCriteria : [],
+            reviewAuthority: String(rawPolicy.reviewAuthority ?? ""),
+        }
+        : null;
+    // Evidence enhancement: pull evidence items for this claim, surface the execution block
+    const claimEvidenceItems = bundleEvidence.filter((ev) => ev && ev.claimId === claimId);
+    const evidence = claimEvidenceItems.map((ev) => {
+        const exec = ev.execution && typeof ev.execution === "object" ? ev.execution : null;
+        const execution = exec
+            ? {
+                runner: String(exec.runner ?? exec.label ?? ""),
+                label: String(exec.label ?? exec.runner ?? ""),
+                isError: Boolean(exec.isError ?? (typeof exec.exitCode === "number" && exec.exitCode !== 0)),
+                exitCode: typeof exec.exitCode === "number" ? exec.exitCode : null,
+            }
+            : null;
+        return {
+            evidenceType: String(ev.evidenceType ?? ev.type ?? "unknown"),
+            label: String(ev.label ?? ev.excerptOrSummary ?? ev.sourceRef ?? ev.id ?? ""),
+            execution,
+            passing: execution ? !execution.isError : String(ev.status ?? "") !== "disputed",
+            summary: String(ev.excerptOrSummary ?? ev.summary ?? ev.label ?? ""),
+        };
+    });
+    // Drilldown: extract from report structure (report.transparencyGaps, report.changeRecords)
+    const allGaps = Array.isArray(report.transparencyGaps) ? report.transparencyGaps : [];
+    const allChanges = Array.isArray(report.changeRecords) ? report.changeRecords : [];
+    const transparencyGaps = allGaps.filter((g) => g && g.claimId === claimId);
+    const changeRecords = allChanges.filter((c) => c && c.claimId === claimId);
+    return {
+        found: true,
+        status: String(reportClaim.status ?? "unknown"),
+        value: String(bundleClaim.value ?? reportClaim.value ?? ""),
+        claimType: String(bundleClaim.claimType ?? reportClaim.claimType ?? ""),
+        evidence,
+        policy,
+        why: {
+            directInputs: [], // populated by buildDerivationDrilldown if non-leaf
+            leafClaims: [],
+            diagnostics: [],
+            transparencyGaps,
+            changeRecords,
+        },
+    };
+}

package/build/src/cli/telemetry-doctor.js

@@ -3,6 +3,7 @@ import * as http from "node:http";
 import * as https from "node:https";
 import * as path from "node:path";
 import { parseArgs, flagBool, flagString } from "../lib/args.js";
+import { telemetryDataDir as defaultTelemetryDataDir } from "../lib/local-artifact-root.js";
 const defaultChannels = "full";
 const sensitiveQueryKeys = new Set(["token", "api_key", "apikey", "key", "secret", "password", "auth", "authorization", "access_token"]);
 function usage() {
@@ -46,10 +47,7 @@ function channelConfigValue(config, channel, key, fallback = "") {
 }
 function telemetryDataDir(dest) {
     const configured = process.env.TELEMETRY_DATA_DIR;
-    // Must mirror scripts/telemetry/lib/config.sh: the sink lives INSIDE the
-    // workspace at <dest>/.telemetry. The previous "../.telemetry" duplicated
-    // the parent-escape bug fixed in config.sh on 2026-06-11.
-    return configured ? path.resolve(dest, configured) : path.resolve(dest, ".telemetry");
+    return configured ? path.resolve(dest, configured) : defaultTelemetryDataDir(dest);
 }
 function deriveConsoleEndpoint(consoleUrl, explicitEndpoint) {
     if (explicitEndpoint)

package/build/src/cli/usage-feedback.js

@@ -3,9 +3,11 @@ import { fileURLToPath } from "node:url";
 import * as os from "node:os";
 import * as path from "node:path";
 import { parseArgs, flagBool, flagList, flagString } from "../lib/args.js";
+import { defaultArtifactRootForRead, defaultTelemetryDirForRead, defaultTelemetryDirsForRead, telemetryDataDir, flowAgentsArtifactRoot, legacyFlowAgentsArtifactRoot } from "../lib/local-artifact-root.js";
 const VALID_RESULTS = new Set(["success", "partial", "failure", "not_verified"]);
 function telemetryDir(flags) {
-    return path.resolve(flagString(flags, "telemetry-dir", process.env.TELEMETRY_DATA_DIR ?? ".telemetry") ?? ".telemetry");
+    const explicit = flagString(flags, "telemetry-dir") ?? process.env.TELEMETRY_DATA_DIR;
+    return explicit ? path.resolve(explicit) : telemetryDataDir();
 }
 function ensureSafeDir(dir) {
     let current = path.resolve(dir);
@@ -112,7 +114,8 @@ function normalize(input, runtime, flags, fallbackSource = "flow-agents") {
 function importTelemetry(argv, defaultRuntime) {
     const { flags } = parseArgs(argv);
     const runtime = defaultRuntime ?? flagString(flags, "runtime", "codex") ?? "codex";
-    const input = flagString(flags, "input-full-jsonl") ?? path.join(flagString(flags, "input-telemetry-dir") ?? "", "full.jsonl");
+    const explicitInputDir = flagString(flags, "input-telemetry-dir");
+    const input = flagString(flags, "input-full-jsonl") ?? path.join(explicitInputDir ? path.resolve(explicitInputDir) : defaultTelemetryDirForRead(), "full.jsonl");
     if (!input || !fs.existsSync(input))
         throw new Error(`input telemetry file does not exist: ${input}`);
     const dir = telemetryDir(flags);
@@ -149,7 +152,7 @@ function syncArtifacts(argv) {
     const dir = telemetryDir(flags);
     ensureSafeDir(dir);
     const artifacts = flagList(flags, "artifact-dir");
-    const records = (artifacts.length ? artifacts : [".flow-agents"]).flatMap((item) => fs.existsSync(item) ? artifactOutcomes(item, flags) : []);
+    const records = (artifacts.length ? artifacts : [flowAgentsArtifactRoot(), legacyFlowAgentsArtifactRoot()]).flatMap((item) => fs.existsSync(item) ? artifactOutcomes(item, flags) : []);
     writeJsonlUpsert(path.join(dir, "outcomes.jsonl"), records, "outcome_id");
     if (!flagBool(flags, "quiet"))
         console.log(`synced ${records.length} artifact outcome(s) to ${path.join(dir, "outcomes.jsonl")}`);
@@ -296,7 +299,10 @@ function markdownReport(data, groupBy) {
 }
 function report(argv) {
     const { flags } = parseArgs(argv);
-    const dirs = flagList(flags, "telemetry-dir").map((dir) => path.resolve(dir));
+    const requestedDirs = flagList(flags, "telemetry-dir");
+    const dirs = (requestedDirs.length ? requestedDirs.map((dir) => path.resolve(dir)) : defaultTelemetryDirsForRead()).filter(Boolean);
+    if (dirs.length === 0)
+        dirs.push(telemetryDataDir());
     dirs.forEach(ensureSafeDir);
     const data = reportData(dirs, flagString(flags, "group-by"));
     const format = flagString(flags, "format", "markdown");
@@ -331,7 +337,7 @@ function registerProject(argv) {
     ensureSafeDir(globalDir);
     const repoRoot = path.resolve(flagString(flags, "repo-root", ".") ?? ".");
     const name = flagString(flags, "name", path.basename(repoRoot)) ?? path.basename(repoRoot);
-    const record = { name, repo_root: repoRoot, artifact_dir: path.join(repoRoot, ".flow-agents"), input_telemetry_dir: path.join(repoRoot, ".telemetry"), runtime: flagString(flags, "runtime", "codex"), repo: flagString(flags, "repo", name), agent: flagString(flags, "agent"), profile_id: flagString(flags, "profile-id"), prompt_id: flagString(flags, "prompt-id"), prompt_variant: flagString(flags, "prompt-variant"), skill_ids: flagList(flags, "skill-id"), skill_variant: flagString(flags, "skill-variant") };
+    const record = { name, repo_root: repoRoot, artifact_dir: defaultArtifactRootForRead(repoRoot), input_telemetry_dir: defaultTelemetryDirForRead(repoRoot), runtime: flagString(flags, "runtime", "codex"), repo: flagString(flags, "repo", name), agent: flagString(flags, "agent"), profile_id: flagString(flags, "profile-id"), prompt_id: flagString(flags, "prompt-id"), prompt_variant: flagString(flags, "prompt-variant"), skill_ids: flagList(flags, "skill-id"), skill_variant: flagString(flags, "skill-variant") };
     const registryFile = path.join(globalDir, "projects.json");
     const existing = fs.existsSync(registryFile) ? JSON.parse(fs.readFileSync(registryFile, "utf8")) : { projects: [] };
     const projects = Array.isArray(existing) ? existing : Array.isArray(existing.projects) ? existing.projects : [];
@@ -355,7 +361,9 @@ function syncProject(project, globalDir) {
     const name = String(project.name ?? project.repo ?? "project").replace(/[^a-zA-Z0-9_.-]+/g, "-") || "project";
     const store = path.join(globalDir, "projects", name);
     ensureSafeDir(store);
-    const artifactDir = String(project.artifact_dir ?? path.join(String(project.repo_root), ".flow-agents"));
+    const repoRoot = String(project.repo_root ?? process.cwd());
+    const configuredArtifactDir = typeof project.artifact_dir === "string" ? project.artifact_dir : "";
+    const artifactDir = configuredArtifactDir && fs.existsSync(configuredArtifactDir) ? configuredArtifactDir : defaultArtifactRootForRead(repoRoot);
     const flags = {
         "repo": String(project.repo ?? name),
         "runtime": String(project.runtime ?? "codex"),
@@ -374,9 +382,9 @@ function discoverProjects(root) {
     if (!fs.existsSync(root))
         return [];
     const candidates = [root, ...fs.readdirSync(root).map((name) => path.join(root, name))];
-    return candidates.filter((candidate) => fs.existsSync(path.join(candidate, ".flow-agents"))).map((repoRoot) => {
+    return candidates.filter((candidate) => fs.existsSync(flowAgentsArtifactRoot(candidate)) || fs.existsSync(legacyFlowAgentsArtifactRoot(candidate))).map((repoRoot) => {
         const name = path.basename(repoRoot);
-        return { name, repo: name, repo_root: repoRoot, artifact_dir: path.join(repoRoot, ".flow-agents"), input_telemetry_dir: path.join(repoRoot, ".telemetry"), runtime: "codex", skill_ids: [] };
+        return { name, repo: name, repo_root: repoRoot, artifact_dir: defaultArtifactRootForRead(repoRoot), input_telemetry_dir: defaultTelemetryDirForRead(repoRoot), runtime: "codex", skill_ids: [] };
     });
 }
 function syncProjects(argv) {

package/build/src/cli/workflow-artifact-cleanup-audit.js

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import { fileURLToPath } from "node:url";
 import * as path from "node:path";
 import { flagBool, flagString, parseArgs } from "../lib/args.js";
+import { defaultArtifactRootForRead } from "../lib/local-artifact-root.js";
 const ACTIVE_STATUSES = new Set([
     "planning",
     "planned",
@@ -23,7 +24,7 @@ function printHelp() {
     console.log("Read-only dry-run audit for local workflow artifact directories.");
     console.log("");
     console.log("Options:");
-    console.log("  --artifact-root <path>  Local artifact root to scan (default: .flow-agents)");
+    console.log("  --artifact-root <path>  Local artifact root to scan (default: .kontourai/flow-agents, with .flow-agents read fallback)");
     console.log("  --json                  Print stable JSON buckets instead of text");
     console.log("  --help                  Show this help");
     console.log("");
@@ -257,7 +258,8 @@ export function main(argv = process.argv.slice(2)) {
     }
     let result;
     try {
-        result = audit(flagString(args.flags, "artifact-root", ".flow-agents") ?? ".flow-agents");
+        const root = flagString(args.flags, "artifact-root") ? path.resolve(flagString(args.flags, "artifact-root")) : defaultArtifactRootForRead();
+        result = audit(root);
     }
     catch (error) {
         console.error(`workflow-artifact-cleanup-audit: ${error instanceof Error ? error.message : String(error)}`);

package/build/src/cli/workflow-sidecar.d.ts

@@ -294,47 +294,5 @@ export declare function gateAdvisoryFix(calibration: GateCalibration, claimId: s
  * @param now                 Optional timestamp override for deterministic tests
  */
 export declare function buildGateInquiryRecords(bundle: BundleFile, blockSignal: GateBlockSignal, slug: string, expectedCriterionIds: string[], surface: SurfaceModule, now?: Date): AnyObj[];
-export interface ClaimEvidenceItem {
-    evidenceType: string;
-    label: string;
-    execution: {
-        runner: string;
-        label: string;
-        isError: boolean;
-        exitCode: number | null;
-    } | null;
-    passing: boolean;
-    summary: string;
-}
-export interface ClaimExplanation {
-    found: boolean;
-    status: string;
-    value: string;
-    claimType: string;
-    evidence: ClaimEvidenceItem[];
-    policy: {
-        id: string;
-        requiredEvidence: string[];
-        requiredMethods?: string[];
-        acceptanceCriteria: string[];
-        reviewAuthority: string;
-    } | null;
-    why: {
-        directInputs: AnyObj[];
-        leafClaims: AnyObj[];
-        diagnostics: AnyObj[];
-        transparencyGaps: AnyObj[];
-        changeRecords: AnyObj[];
-    };
-}
-/**
- * Build a structured explanation for a specific claim.
- * PURE: report + bundle + id in, structured explanation out.
- * No fs, no CLI, no .flow-agents paths. Promotable to Surface #171.
- *
- * @param report   TrustReport from buildTrustReport(bundle) — required for derived status
- * @param bundle   Raw parsed trust.bundle (BundleFile shape)
- * @param claimId  The claim id to explain
- */
-export declare function buildClaimExplanation(report: Record<string, unknown>, bundle: Record<string, unknown>, claimId: string): ClaimExplanation;
-export {};
+export { buildClaimExplanation } from "./sidecar-claim-explain.js";
+export type { ClaimEvidenceItem, ClaimExplanation } from "./sidecar-claim-explain.js";

package/build/src/cli/workflow-sidecar.js

@@ -7,6 +7,7 @@ import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 // ADR 0016 Abstraction A: shared FlowDefinition resolver (P-a)
 import { resolveActiveFlowStep, resolveFlowFilePath, resolvePhaseMap, resolveRouteBackPolicy } from "../lib/flow-resolver.js";
+import { defaultArtifactRootForRead, flowAgentsArtifactRoot } from "../lib/local-artifact-root.js";
 export const statuses = new Set(["new", "planning", "planned", "in_progress", "blocked", "verifying", "verified", "needs_decision", "not_verified", "failed", "delivered", "accepted", "archived"]);
 export const phases = ["idea", "backlog", "pickup", "planning", "execution", "verification", "goal_fit", "evidence", "release", "learning", "done"];
 export const checkKinds = new Set(["build", "types", "lint", "test", "security", "diff", "browser", "runtime", "policy", "external"]);
@@ -618,7 +619,7 @@ function explicitArtifactRoot(p) {
     const explicit = opt(p, "artifact-dir");
     const configuredRoot = opt(p, "artifact-root");
     if (!explicit)
-        return path.resolve(configuredRoot || ".flow-agents");
+        return configuredRoot ? path.resolve(configuredRoot) : flowAgentsArtifactRoot();
     const dir = path.resolve(explicit);
     if (!fs.existsSync(dir))
         die(`artifact directory does not exist: ${dir}`);
@@ -880,7 +881,7 @@ function initSidecars(dir, slug, sourceRequest, summary, nextAction, timestamp,
     });
 }
 function ensureSession(p) {
-    const root = path.resolve(opt(p, "artifact-root", ".flow-agents"));
+    const root = opt(p, "artifact-root") ? path.resolve(opt(p, "artifact-root")) : flowAgentsArtifactRoot();
     const slug = opt(p, "task-slug") || (opt(p, "work-item") ? workItemSlug(opt(p, "work-item")) : die("--task-slug is required (or pass --work-item to derive it)"));
     const dir = sessionDirFor(root, slug);
     fs.mkdirSync(dir, { recursive: true });
@@ -913,7 +914,7 @@ function ensureSession(p) {
     return 0;
 }
 function current(p) {
-    const root = path.resolve(opt(p, "artifact-root", ".flow-agents"));
+    const root = opt(p, "artifact-root") ? path.resolve(opt(p, "artifact-root")) : defaultArtifactRootForRead();
     const dir = currentDir(root);
     if (!dir)
         die("no current workflow session is recorded");
@@ -1908,7 +1909,7 @@ function assertExistingLearningValid(dir) {
     }
 }
 async function dogfoodPass(p) {
-    const root = path.resolve(opt(p, "artifact-root", ".flow-agents"));
+    const root = opt(p, "artifact-root") ? path.resolve(opt(p, "artifact-root")) : defaultArtifactRootForRead();
     const dir = path.resolve(opt(p, "artifact-dir") || currentDir(root) || "");
     requireArtifactDirUnderRoot(dir, root);
     assertExistingLearningValid(dir);
@@ -2283,7 +2284,7 @@ function loadSurfacePanelJs() {
     return "";
 }
 async function renderTrustPanel(p) {
-    const root = path.resolve(opt(p, "artifact-root", ".flow-agents"));
+    const root = opt(p, "artifact-root") ? path.resolve(opt(p, "artifact-root")) : defaultArtifactRootForRead();
     const dir = p.positional[0] ? artifactDirFrom(p.positional[0]) : currentDir(root);
     if (!dir)
         die("render-trust-panel requires a workflow dir or a recorded current session");
@@ -2482,7 +2483,7 @@ function livenessLifecycle(taskDir, slug, kind, timestamp) {
     catch { /* best-effort; liveness is advisory and must never break the workflow */ }
 }
 async function liveness(p) {
-    const root = path.resolve(opt(p, "artifact-root", ".flow-agents"));
+    const root = opt(p, "artifact-root") ? path.resolve(opt(p, "artifact-root")) : flowAgentsArtifactRoot();
     const action = p.positional[0] || "";
     const subjectId = p.positional[1] || "";
     const actor = opt(p, "actor", process.env.FLOW_AGENTS_ACTOR || "unknown");
@@ -2545,86 +2546,14 @@ async function liveness(p) {
     die("liveness action must be one of: claim | heartbeat | release | status");
     return 1;
 }
-/**
- * Build a structured explanation for a specific claim.
- * PURE: report + bundle + id in, structured explanation out.
- * No fs, no CLI, no .flow-agents paths. Promotable to Surface #171.
- *
- * @param report   TrustReport from buildTrustReport(bundle) — required for derived status
- * @param bundle   Raw parsed trust.bundle (BundleFile shape)
- * @param claimId  The claim id to explain
- */
-export function buildClaimExplanation(report, bundle, claimId) {
-    const reportClaims = Array.isArray(report.claims) ? report.claims : [];
-    const reportClaim = reportClaims.find((c) => c.id === claimId);
-    if (!reportClaim) {
-        return {
-            found: false,
-            status: "unknown",
-            value: "",
-            claimType: "",
-            evidence: [],
-            policy: null,
-            why: { directInputs: [], leafClaims: [], diagnostics: [], transparencyGaps: [], changeRecords: [] },
-        };
-    }
-    const bundleClaims = Array.isArray(bundle.claims) ? bundle.claims : [];
-    const bundleClaim = bundleClaims.find((c) => c.id === claimId) ?? reportClaim;
-    const bundlePolicies = Array.isArray(bundle.policies) ? bundle.policies : [];
-    const bundleEvidence = Array.isArray(bundle.evidence) ? bundle.evidence : [];
-    // Governing policy — follow verificationPolicyId into bundle.policies[]
-    const verificationPolicyId = typeof bundleClaim.verificationPolicyId === "string" ? bundleClaim.verificationPolicyId : undefined;
-    const rawPolicy = verificationPolicyId ? bundlePolicies.find((p) => p.id === verificationPolicyId) : undefined;
-    const policy = rawPolicy
-        ? {
-            id: String(rawPolicy.id ?? ""),
-            requiredEvidence: Array.isArray(rawPolicy.requiredEvidence) ? rawPolicy.requiredEvidence : [],
-            requiredMethods: Array.isArray(rawPolicy.requiredMethods) ? rawPolicy.requiredMethods : undefined,
-            acceptanceCriteria: Array.isArray(rawPolicy.acceptanceCriteria) ? rawPolicy.acceptanceCriteria : [],
-            reviewAuthority: String(rawPolicy.reviewAuthority ?? ""),
-        }
-        : null;
-    // Evidence enhancement: pull evidence items for this claim, surface the execution block
-    const claimEvidenceItems = bundleEvidence.filter((ev) => ev && ev.claimId === claimId);
-    const evidence = claimEvidenceItems.map((ev) => {
-        const exec = ev.execution && typeof ev.execution === "object" ? ev.execution : null;
-        const execution = exec
-            ? {
-                runner: String(exec.runner ?? exec.label ?? ""),
-                label: String(exec.label ?? exec.runner ?? ""),
-                isError: Boolean(exec.isError ?? (typeof exec.exitCode === "number" && exec.exitCode !== 0)),
-                exitCode: typeof exec.exitCode === "number" ? exec.exitCode : null,
-            }
-            : null;
-        return {
-            evidenceType: String(ev.evidenceType ?? ev.type ?? "unknown"),
-            label: String(ev.label ?? ev.excerptOrSummary ?? ev.sourceRef ?? ev.id ?? ""),
-            execution,
-            passing: execution ? !execution.isError : String(ev.status ?? "") !== "disputed",
-            summary: String(ev.excerptOrSummary ?? ev.summary ?? ev.label ?? ""),
-        };
-    });
-    // Drilldown: extract from report structure (report.transparencyGaps, report.changeRecords)
-    const allGaps = Array.isArray(report.transparencyGaps) ? report.transparencyGaps : [];
-    const allChanges = Array.isArray(report.changeRecords) ? report.changeRecords : [];
-    const transparencyGaps = allGaps.filter((g) => g && g.claimId === claimId);
-    const changeRecords = allChanges.filter((c) => c && c.claimId === claimId);
-    return {
-        found: true,
-        status: String(reportClaim.status ?? "unknown"),
-        value: String(bundleClaim.value ?? reportClaim.value ?? ""),
-        claimType: String(bundleClaim.claimType ?? reportClaim.claimType ?? ""),
-        evidence,
-        policy,
-        why: {
-            directInputs: [], // populated by buildDerivationDrilldown if non-leaf
-            leafClaims: [],
-            diagnostics: [],
-            transparencyGaps,
-            changeRecords,
-        },
-    };
-}
+// ─────────────────────────────────────────────────────────────────────────────
+// ─── Claim Lookup — pure helper (promotable to Surface #171) ─────────────────
+// buildClaimExplanation + its types are extracted to ./sidecar-claim-explain.ts
+// (ops#22): a PURE projection (report + bundle + id in, structured explanation out)
+// with no fs/CLI/shared state, unit-tested in isolation. Re-exported here so the
+// library facade (src/index.ts) and the IO `claimLookup` handler below are unchanged.
+export { buildClaimExplanation } from "./sidecar-claim-explain.js";
+import { buildClaimExplanation } from "./sidecar-claim-explain.js";
 /**
  * claim <id> <dir>
  *
@@ -2778,7 +2707,9 @@ async function main() {
     const p = parseArgs(process.argv.slice(2));
     if (!p.command)
         die("workflow-sidecar command is required");
-    const lockRoot = ["ensure-session", "current", "dogfood-pass", "liveness"].includes(p.command) ? path.resolve(opt(p, "artifact-root", ".flow-agents")) : p.command === "record-agent-event" ? explicitArtifactRoot(p) : p.command === "claim" ? (p.positional[1] ? path.resolve(p.positional[1]) : "") : p.positional[0] ? artifactDirFrom(p.positional[0]) : "";
+    const lockRoot = ["ensure-session", "current", "dogfood-pass", "liveness"].includes(p.command)
+        ? (opt(p, "artifact-root") ? path.resolve(opt(p, "artifact-root")) : (p.command === "ensure-session" ? flowAgentsArtifactRoot() : defaultArtifactRootForRead()))
+        : p.command === "record-agent-event" ? explicitArtifactRoot(p) : p.command === "claim" ? (p.positional[1] ? path.resolve(p.positional[1]) : "") : p.positional[0] ? artifactDirFrom(p.positional[0]) : "";
     return withLock(lockRoot, ["ensure-session", "record-agent-event", "dogfood-pass"].includes(p.command), p.command, () => {
         switch (p.command) {
             case "ensure-session": return ensureSession(p);

package/build/src/index.d.ts

@@ -1,3 +1,4 @@
+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 { validateTrustBundle, normalizeCheck, normalizeFinding, normalizeLearning, normalizeEvidenceRefs, validateEvidenceRef, validateLearningCorrection, loadJson, writeJson, appendJsonl, sidecarBase, writeState, statuses, phases, checkKinds, checkStatuses, verdicts, } from "./cli/workflow-sidecar.js";
 /** Read a sidecar JSON file from a workflow artifact directory; returns `{}` if absent. */
 export declare function readSidecar(dir: string, name: string): Record<string, any>;

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