@kontourai/flow-agents 3.12.1 → 4.1.0

package/src/cli/narrative-resolver.test.mjs

@@ -0,0 +1,114 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import test from "node:test";
+import { parseSourceId, formatSourceId } from "../../build/src/narrative/source-ids.js";
+import { snapshotNarrative, validateNarrativeSourceManifest } from "../../build/src/narrative/snapshot.js";
+import { resolveSource, verifyManifest } from "../../build/src/narrative/resolver.js";
+
+const NOW = "2026-07-14T12:00:00Z";
+
+function setup() {
+  const scope = fs.mkdtempSync(path.join(os.tmpdir(), "narrative-resolver-"));
+  const repo = path.join(scope, "repo");
+  const narrativeDir = path.join(scope, "artifacts", "narrative", "n1");
+  fs.mkdirSync(repo, { recursive: true });
+  const raw = Buffer.from(JSON.stringify({ event: "kept", tool: { input: "remove" } }));
+  fs.writeFileSync(path.join(repo, "source.json"), raw);
+  const hash = createHash("sha256").update(raw).digest("hex");
+  const source = parseSourceId(`fa1:file:source.json:${hash}`);
+  const result = snapshotNarrative({
+    narrativeDir, narrativeId: "n1", requests: [{ source, roots: { repoRoot: repo } }], redactionFields: ["tool.input"],
+    compiler: { name: "test", version: "1", policy_hash: "policy" }, captureCompleteness: { channels: {}, known_gaps: [] },
+  }, { now: () => NOW });
+  return { scope, narrativeDir, sourceId: formatSourceId(source), entry: result.manifest.sources[0] };
+}
+
+test("resolve returns the exact hash-verified snapshot bytes", () => {
+  const { narrativeDir, sourceId, entry } = setup();
+  const result = resolveSource(narrativeDir, sourceId);
+  assert.equal(result.status, "resolved");
+  assert.equal(createHash("sha256").update(result.content).digest("hex"), result.sha256);
+  assert.equal(result.sha256, entry.sha256);
+  assert.deepEqual(result.lineage, [{ at: NOW, event: "source_snapshotted" }]);
+});
+
+test("byte flip and same-size replacement are corrupt", () => {
+  const { narrativeDir, sourceId, entry } = setup();
+  const blob = path.join(narrativeDir, "sources", entry.sha256);
+  const bytes = fs.readFileSync(blob);
+  bytes[0] ^= 1;
+  fs.writeFileSync(blob, bytes);
+  assert.deepEqual(resolveSource(narrativeDir, sourceId).reason, "corrupt");
+});
+
+test("symlinked blob is corrupt", { skip: process.platform === "win32" }, () => {
+  const { narrativeDir, sourceId, entry } = setup();
+  const blob = path.join(narrativeDir, "sources", entry.sha256);
+  const target = path.join(narrativeDir, "replacement");
+  fs.writeFileSync(target, "replacement");
+  fs.rmSync(blob);
+  fs.symlinkSync(target, blob);
+  assert.deepEqual(resolveSource(narrativeDir, sourceId).reason, "corrupt");
+});
+
+test("manifest traversal-shaped sha is rejected and resolves corrupt", () => {
+  const { narrativeDir, sourceId } = setup();
+  const manifestFile = path.join(narrativeDir, "source-manifest.json");
+  const manifest = JSON.parse(fs.readFileSync(manifestFile, "utf8"));
+  manifest.sources[0].sha256 = "../x";
+  assert.ok(validateNarrativeSourceManifest(manifest).length > 0);
+  fs.writeFileSync(manifestFile, JSON.stringify(manifest));
+  assert.deepEqual(resolveSource(narrativeDir, sourceId).reason, "corrupt");
+});
+
+test("unknown source id is not_captured", () => {
+  const { narrativeDir } = setup();
+  assert.deepEqual(resolveSource(narrativeDir, `fa1:file:missing:${"0".repeat(64)}`).reason, "not_captured");
+});
+
+test("scope mismatch is unauthorized", () => {
+  const { narrativeDir, sourceId } = setup();
+  const otherScope = fs.mkdtempSync(path.join(os.tmpdir(), "narrative-other-scope-"));
+  assert.deepEqual(resolveSource(narrativeDir, sourceId, { scope: otherScope }).reason, "unauthorized");
+});
+
+test("verifyManifest reports every source and fails after corruption", () => {
+  const { narrativeDir, entry } = setup();
+  assert.deepEqual(verifyManifest(narrativeDir), { ok: true, perSource: [{ sourceId: entry.source_id, status: "resolved" }] });
+  fs.appendFileSync(path.join(narrativeDir, "sources", entry.sha256), "x");
+  const report = verifyManifest(narrativeDir);
+  assert.equal(report.ok, false);
+  assert.deepEqual(report.perSource, [{ sourceId: entry.source_id, status: "unavailable", reason: "corrupt" }]);
+});
+
+test("a symlinked sources directory is rejected as corrupt, never followed", (t) => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "narrative-resolver-symdir-"));
+  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+  const narrativeDir = path.join(root, "narrative", "n1");
+  const elsewhere = path.join(root, "elsewhere");
+  const { repo } = { repo: path.join(root, "repo") };
+  fs.mkdirSync(repo, { recursive: true });
+  const content = Buffer.from(JSON.stringify({ ok: true }));
+  fs.writeFileSync(path.join(repo, "f.json"), content);
+  const hash = createHash("sha256").update(content).digest("hex");
+  const request = { source: parseSourceId(`fa1:file:f.json:${hash}`), roots: { repoRoot: repo } };
+  const { manifest } = snapshotNarrative({
+    narrativeDir, narrativeId: "n1", requests: [request], redactionFields: [],
+    compiler: { name: "test", version: "1", policy_hash: "p" },
+    captureCompleteness: { channels: {}, known_gaps: [] },
+  }, { now: () => "2026-07-14T12:00:00Z" });
+  const entry = manifest.sources[0];
+  assert.equal(entry.status, "snapshotted");
+  // Replace the sources directory (the blob's intermediate ancestor) with a
+  // symlink pointing elsewhere carrying an identical blob.
+  fs.mkdirSync(elsewhere, { recursive: true });
+  fs.copyFileSync(path.join(narrativeDir, "sources", entry.sha256), path.join(elsewhere, entry.sha256));
+  fs.rmSync(path.join(narrativeDir, "sources"), { recursive: true });
+  fs.symlinkSync(elsewhere, path.join(narrativeDir, "sources"));
+  const result = resolveSource(narrativeDir, entry.source_id);
+  assert.equal(result.status, "unavailable");
+  assert.equal(result.reason, "corrupt");
+});

package/src/cli/narrative-snapshot.test.mjs

@@ -0,0 +1,149 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import test from "node:test";
+import { parseSourceId } from "../../build/src/narrative/source-ids.js";
+import { snapshotNarrative } from "../../build/src/narrative/snapshot.js";
+
+const NOW = "2026-07-14T12:00:00Z";
+const compiler = { name: "test", version: "1", policy_hash: "policy" };
+const captureCompleteness = { channels: { full: "active" }, known_gaps: [] };
+
+function fixture() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "narrative-snapshot-"));
+  const repo = path.join(root, "repo");
+  const narrativeDir = path.join(root, "artifacts", "narrative", "n1");
+  fs.mkdirSync(repo, { recursive: true });
+  return { root, repo, narrativeDir };
+}
+
+function fileRequest(repo, relative, content) {
+  fs.mkdirSync(path.dirname(path.join(repo, relative)), { recursive: true });
+  fs.writeFileSync(path.join(repo, relative), content);
+  const hash = createHash("sha256").update(content).digest("hex");
+  return { source: parseSourceId(`fa1:file:${encodeURIComponent(relative)}:${hash}`), roots: { repoRoot: repo } };
+}
+
+function input(narrativeDir, requests) {
+  return { narrativeDir, narrativeId: "n1", requests, redactionFields: ["tool.input"], compiler, captureCompleteness };
+}
+
+test("snapshot stores identical filtered content once and references it twice", () => {
+  const { repo, narrativeDir } = fixture();
+  const content = Buffer.from(JSON.stringify({ event: "same", tool: { input: "secret" } }));
+  const result = snapshotNarrative(input(narrativeDir, [fileRequest(repo, "a.json", content), fileRequest(repo, "b.json", content)]), { now: () => NOW });
+  assert.equal(result.manifest.sources.length, 2);
+  assert.equal(result.manifest.sources[0].sha256, result.manifest.sources[1].sha256);
+  assert.equal(fs.readdirSync(path.join(narrativeDir, "sources")).length, 1);
+  assert.equal(fs.readFileSync(path.join(narrativeDir, "sources", result.manifest.sources[0].sha256), "utf8").includes("secret"), false);
+});
+
+test("a blob write failure leaves no manifest", () => {
+  const { repo, narrativeDir } = fixture();
+  const request = fileRequest(repo, "a.json", Buffer.from(JSON.stringify({ ok: true })));
+  assert.throws(() => snapshotNarrative(input(narrativeDir, [request]), {
+    now: () => NOW,
+    writeBlob: () => { throw new Error("simulated blob write failure"); },
+  }), /simulated blob write failure/);
+  assert.equal(fs.existsSync(path.join(narrativeDir, "source-manifest.json")), false);
+});
+
+test("filter failure records unavailable redacted without leaking source values", () => {
+  const { repo, narrativeDir } = fixture();
+  const secret = "TOP_SECRET_617";
+  const request = fileRequest(repo, "bad.json", Buffer.from(JSON.stringify({ tool: secret })));
+  const result = snapshotNarrative(input(narrativeDir, [request]), { now: () => NOW });
+  assert.equal(result.manifest.sources[0].status, "unavailable");
+  assert.equal(result.manifest.sources[0].unavailable_reason, "redacted");
+  const allNarrativeText = fs.readdirSync(narrativeDir, { recursive: true })
+    .map(String).filter((name) => fs.statSync(path.join(narrativeDir, name)).isFile())
+    .map((name) => fs.readFileSync(path.join(narrativeDir, name), "utf8")).join("\n");
+  assert.equal(allNarrativeText.includes(secret), false);
+  assert.deepEqual(fs.readdirSync(path.join(narrativeDir, "sources")), []);
+});
+
+test("manifest publication is creation-only: a concurrent racer cannot replace the winner", () => {
+  const { repo, narrativeDir } = fixture();
+  const request = fileRequest(repo, "good.json", Buffer.from(JSON.stringify({ ok: true })));
+  const first = snapshotNarrative(input(narrativeDir, [request]), { now: () => NOW });
+  assert.equal(first.manifest.sources[0].status, "snapshotted");
+  const before = fs.readFileSync(path.join(narrativeDir, "source-manifest.json"), "utf8");
+  // A second snapshot into the same narrative dir must fail without replacing
+  // the frozen manifest, even when it skips the advisory exists pre-check by
+  // racing straight to publication.
+  assert.throws(() => snapshotNarrative(input(narrativeDir, [request]), { now: () => NOW }), /already exists/);
+  assert.equal(fs.readFileSync(path.join(narrativeDir, "source-manifest.json"), "utf8"), before);
+});
+
+test("schema rejects malformed fa1 ids and entries without lineage", () => {
+  const { repo, narrativeDir } = fixture();
+  const request = fileRequest(repo, "s.json", Buffer.from(JSON.stringify({ ok: 1 })));
+  const { manifest } = snapshotNarrative(input(narrativeDir, [request]), { now: () => NOW });
+  const validate = (mutate) => {
+    const clone = JSON.parse(JSON.stringify(manifest));
+    mutate(clone);
+    return clone;
+  };
+  // Malformed fa1 id: right prefix, structurally invalid remainder.
+  const badId = validate((m) => { m.sources[0].source_id = "fa1:file:not a valid component:zz"; });
+  // Missing lineage on a snapshotted entry.
+  const noLineage = validate((m) => { delete m.sources[0].lineage; });
+  return import("../../build/src/narrative/snapshot.js").then(({ validateNarrativeSourceManifest }) => {
+    assert.equal(validateNarrativeSourceManifest(manifest).length, 0);
+    assert.notEqual(validateNarrativeSourceManifest(badId).length, 0);
+    assert.notEqual(validateNarrativeSourceManifest(noLineage).length, 0);
+  });
+});
+
+test("session-scoped IDs are refused when the session root does not carry the ID's slug", () => {
+  const { root, narrativeDir } = fixture();
+  const wrongSession = path.join(root, "some-other-session");
+  fs.mkdirSync(wrongSession, { recursive: true });
+  fs.writeFileSync(path.join(wrongSession, "command-log.jsonl"), "");
+  const request = {
+    source: parseSourceId("fa1:cmdlog:expected-slug:0/01234567"),
+    roots: { sessionDir: wrongSession },
+  };
+  const { manifest } = snapshotNarrative(input(narrativeDir, [request]), { now: () => NOW });
+  assert.equal(manifest.sources[0].status, "unavailable");
+  assert.equal(manifest.sources[0].unavailable_reason, "unauthorized");
+});
+
+test("creation-only publication rejects a racer that lands between the pre-check and the link", () => {
+  const { repo, narrativeDir } = fixture();
+  const request = fileRequest(repo, "raced.json", Buffer.from(JSON.stringify({ ok: true })));
+  const manifestPath = path.join(narrativeDir, "source-manifest.json");
+  const racerContent = '{"racer":"winner"}\n';
+  let raced = false;
+  // The racer publishes AFTER snapshotNarrative's advisory exists pre-check has
+  // passed (we publish from inside the blob write), so only the link(2)
+  // creation-only path can refuse the replacement.
+  assert.throws(() => snapshotNarrative(input(narrativeDir, [request]), {
+    now: () => NOW,
+    writeBlob: (rootDir, file, data) => {
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      fs.writeFileSync(file, data);
+      if (!raced) {
+        raced = true;
+        fs.writeFileSync(manifestPath, racerContent);
+      }
+    },
+  }), /already exists/);
+  assert.equal(fs.readFileSync(manifestPath, "utf8"), racerContent);
+});
+
+test("schema requires lineage on unavailable entries too", () => {
+  const { narrativeDir } = fixture();
+  const wrongSession = path.join(path.dirname(narrativeDir), "not-the-slug");
+  fs.mkdirSync(wrongSession, { recursive: true });
+  const request = { source: parseSourceId("fa1:cmdlog:someslug:0/01234567"), roots: { sessionDir: wrongSession } };
+  const { manifest } = snapshotNarrative(input(narrativeDir, [request]), { now: () => NOW });
+  assert.equal(manifest.sources[0].status, "unavailable");
+  const clone = JSON.parse(JSON.stringify(manifest));
+  delete clone.sources[0].lineage;
+  return import("../../build/src/narrative/snapshot.js").then(({ validateNarrativeSourceManifest }) => {
+    assert.notEqual(validateNarrativeSourceManifest(clone).length, 0);
+  });
+});

package/src/cli/narrative-source-ids.test.mjs

@@ -0,0 +1,84 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  SourceIdParseError,
+  buildCaptureCompleteness,
+  compareSourceIds,
+  formatSourceId,
+  integrityClassForSource,
+  parseSourceId,
+} from "../../build/src/index.js";
+
+const ids = [
+  "fa1:telemetry:full/session%2Fone:event%3Aone/0123abcd#1",
+  "fa1:cmdlog:task-617:7/0123abcd",
+  "fa1:cmdlog:task-617:line-2/89abcdef",
+  "fa1:agent-event:task-617/agent%3A1:0/0123abcd",
+  "fa1:delegation:task-617/agent-1:3/89abcdef",
+  "fa1:trust-claim:task-617/0123abcd:claim%3Aone",
+  "fa1:trust-evidence:task-617/89abcdef:evidence%2Fone",
+  "fa1:flow-state:run%2Fone:state/0123abcd",
+  "fa1:flow-transition:run-1:4/89abcdef",
+  "fa1:transcript:0123abcd:10-25",
+  `fa1:file:src%2Fnarrative%2Fsource-ids.ts:${"a".repeat(64)}`,
+  `fa1:file:src%2Findex.ts:${"b".repeat(40)}`,
+];
+
+test("source IDs round-trip every stream with canonical component encoding", () => {
+  for (const id of ids) assert.equal(formatSourceId(parseSourceId(id)), id, id);
+});
+
+test("telemetry ordinal is a stable duplicate disambiguator", () => {
+  const first = parseSourceId("fa1:telemetry:full/s:event/0123abcd#0");
+  const second = parseSourceId("fa1:telemetry:full/s:event/0123abcd#1");
+  assert.equal(first.stream, "telemetry");
+  assert.equal(first.locator.sha8, "0123abcd");
+  assert.equal(first.ordinal, 0);
+  assert.equal(second.ordinal, 1);
+  assert.equal(compareSourceIds(first, second), -1);
+});
+
+test("telemetry locator requires a content pin", () => {
+  for (const id of ["fa1:telemetry:full/s:event", "fa1:telemetry:full/s:event/XYZ", "fa1:telemetry:full/s:event/0123abcd/extra"]) {
+    assert.throws(() => parseSourceId(id), (error) => error instanceof SourceIdParseError, id);
+  }
+});
+
+test("parser rejects malformed, noncanonical, and misplaced components with typed errors", () => {
+  for (const id of [
+    "fa2:telemetry:full/s:e/0123abcd",
+    "fa1:unknown:a:b",
+    "fa1:telemetry:full/s:e/0123abcd#01",
+    "fa1:cmdlog:slug:1/ABCDEF12",
+    "fa1:flow-state:run:other/0123abcd",
+    "fa1:transcript:0123abcd:9-2",
+    "fa1:file:src/raw:path",
+    "fa1:agent-event:slug/agent:one/0123abcd",
+  ]) {
+    assert.throws(() => parseSourceId(id), (error) => error instanceof SourceIdParseError && typeof error.code === "string", id);
+  }
+});
+
+test("compareSourceIds canonicalizes string inputs", () => {
+  assert.equal(compareSourceIds(ids[0], ids[0]), 0);
+  assert.equal(compareSourceIds(ids[0], ids[1]), ids[0] < ids[1] ? -1 : 1);
+});
+
+test("integrity defaults distinguish legacy command logs and file locator kinds", () => {
+  assert.equal(integrityClassForSource(parseSourceId(ids[0])), "rotatable");
+  assert.equal(integrityClassForSource(parseSourceId(ids[1])), "hash_chained");
+  assert.equal(integrityClassForSource(parseSourceId(ids[2])), "append_only_unhashed");
+  assert.equal(integrityClassForSource(parseSourceId(ids[10])), "overwritten_in_place");
+  assert.equal(integrityClassForSource(parseSourceId(ids[11])), "hash_chained");
+});
+
+test("capture completeness detects configured channel presence and always discloses known gaps", () => {
+  const completeness = buildCaptureCompleteness({ full: {}, analytics: false, custom: { enabled: true } }, ["full", "analytics", "custom", "missing"]);
+  assert.deepEqual(completeness.channels, { full: "active", analytics: "inactive", custom: "active", missing: "unknown" });
+  assert.deepEqual(completeness.known_gaps.map((gap) => [gap.class, gap.ref]), [
+    ["mcp_non_native_tools", "flow-agents#492"],
+    ["actor_attribution_conflation", "flow-agents#423"],
+    ["cross_session_event_contamination", "flow-agents#271"],
+  ]);
+});

package/src/cli/narrative-sources.ts

@@ -0,0 +1,276 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { atomicWriteFile, ensureSafeDirectory } from "../lib/fs.js";
+import { parseArgs, flagBool, flagList, flagString } from "../lib/args.js";
+import { flowAgentsArtifactRoot } from "../lib/local-artifact-root.js";
+import { queryCapability, type CapabilityStatus } from "../lib/capability-declarations.js";
+import {
+  composeGroundedNarrative,
+  validateGroundedNarrative,
+  writeEnvelope,
+} from "../narrative/envelope.js";
+import { bindIntentAnnotation, captureIntent } from "../narrative/intent.js";
+import {
+  appendIntentEconomics,
+  readIntentEconomics,
+  reduceIntentEconomics,
+  type IntentAnnotationMode,
+} from "../narrative/intent-economics.js";
+import {
+  NarrativeGroundingError,
+  validateNarrativeGrounding,
+} from "../narrative/grounding-validator.js";
+import type { CaptureCompleteness } from "../narrative/integrity.js";
+import { effectiveNarrativeRedactionFields } from "../narrative/policy-filter.js";
+import { projectRuntimeNarrative, stableStringify, validateNarrativeRuntimeProjection } from "../narrative/projection.js";
+import { resolveManifestEntry, resolveSource, verifyManifest } from "../narrative/resolver.js";
+import { snapshotNarrative, type NarrativeSourceRoots } from "../narrative/snapshot.js";
+import { parseSourceId } from "../narrative/source-ids.js";
+
+export const NARRATIVE_NAMESPACE_ROOT = path.join(".kontourai", "narrative");
+
+function packageVersion(): string {
+  try {
+    const packageFile = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../package.json");
+    return String((JSON.parse(fs.readFileSync(packageFile, "utf8")) as { version?: unknown }).version ?? "unknown");
+  } catch { return "unknown"; }
+}
+
+function usage(): void {
+  console.error(`usage: flow-agents narrative-sources <snapshot|resolve|verify|project|compose> [options]
+
+snapshot:
+  (--session-slug SLUG | --artifact-root PATH) --narrative-id ID --source FA1 [--source FA1 ...]
+  [--telemetry-root PATH] [--session-root PATH] [--flow-root PATH]
+  [--transcript-path FILE] [--repo-root PATH] [--redact-fields FIELD,...]
+  [--allow-transcript-content]  (transcript content is default-deny: without
+                                 this grant transcript sources are recorded
+                                 path_only as unavailable/redacted)
+  [--capture-completeness FILE]
+resolve:
+  --narrative-dir PATH --source-id FA1 (--out FILE | --json)
+project:
+  --narrative-dir PATH (--out FILE | --json) [--projected-at DATE-TIME]
+compose:
+  --narrative-dir PATH --compiled-at DATE-TIME (--out-dir DIR | --json) [--render]
+verify:
+  --narrative-dir PATH --json
+capture-intent:
+  --narrative-dir PATH --runtime ID --actor ID --action-ref FA1 --active-gate-ref FA1
+  [--purpose TEXT] [--objective-ref FA1] [--redact-fields FIELD,...]
+  [--capability-fixture supported|unsupported]  (fixture-only: inject a resolved
+                                 CapabilityStatus; default resolves via the
+                                 runtime's intent_annotation declaration)
+intent-economics:
+  --narrative-dir PATH
+  (--record --mode annotation_on|annotation_off --input-tokens N --output-tokens N
+     --wall-clock-ms N [--attempted-at DATE-TIME]
+   | --report)`);
+}
+
+function required(flags: ReturnType<typeof parseArgs>["flags"], name: string): string {
+  const value = flagString(flags, name);
+  if (!value) throw new Error(`--${name} is required`);
+  return value;
+}
+
+function readCaptureCompleteness(file: string | undefined): CaptureCompleteness {
+  if (!file) return { channels: {}, known_gaps: [] };
+  const parsed: unknown = JSON.parse(fs.readFileSync(file, "utf8"));
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("capture completeness must be a JSON object");
+  return parsed as CaptureCompleteness;
+}
+
+function snapshot(flags: ReturnType<typeof parseArgs>["flags"]): number {
+  const sessionSlug = flagString(flags, "session-slug");
+  const explicitArtifactRoot = flagString(flags, "artifact-root");
+  if (Boolean(sessionSlug) === Boolean(explicitArtifactRoot)) throw new Error("exactly one of --session-slug or --artifact-root is required");
+  if (sessionSlug && (sessionSlug.includes("/") || sessionSlug.includes("\\") || sessionSlug === "." || sessionSlug === "..")) throw new Error("--session-slug must be a single path component");
+  const narrativeId = required(flags, "narrative-id");
+  if (narrativeId.includes("/") || narrativeId.includes("\\") || narrativeId === "." || narrativeId === "..") throw new Error("--narrative-id must be a single path component");
+  const sourceTexts = flagList(flags, "source");
+  if (!sourceTexts.length) throw new Error("at least one --source is required");
+  if (new Set(sourceTexts).size !== sourceTexts.length) throw new Error("--source values must be unique");
+
+  const artifactRoot = explicitArtifactRoot ? path.resolve(explicitArtifactRoot) : flowAgentsArtifactRoot();
+  const sessionDir = sessionSlug ? path.join(artifactRoot, sessionSlug) : flagString(flags, "session-root");
+  const projectRoot = sessionSlug ? path.dirname(path.dirname(artifactRoot)) : artifactRoot;
+  const narrativeDir = sessionSlug
+    ? path.join(projectRoot, NARRATIVE_NAMESPACE_ROOT, sessionSlug, narrativeId)
+    : path.join(projectRoot, NARRATIVE_NAMESPACE_ROOT, narrativeId);
+  const roots: NarrativeSourceRoots = {
+    telemetryDir: flagString(flags, "telemetry-root"), sessionDir,
+    flowRoot: flagString(flags, "flow-root"), transcriptPath: flagString(flags, "transcript-path"),
+    repoRoot: flagString(flags, "repo-root"),
+  };
+  const narrativeFields = (flagString(flags, "redact-fields") ?? "").split(",").map((field) => field.trim()).filter(Boolean);
+  const redactionFields = effectiveNarrativeRedactionFields(narrativeFields);
+  const result = snapshotNarrative({
+    narrativeDir, narrativeId, requests: sourceTexts.map((source) => ({ source: parseSourceId(source), roots })), redactionFields,
+    compiler: {
+      name: "@kontourai/flow-agents", version: packageVersion(),
+      policy_hash: createHash("sha256").update(JSON.stringify(redactionFields)).digest("hex"),
+    },
+    captureCompleteness: readCaptureCompleteness(flagString(flags, "capture-completeness")),
+    allowTranscriptContent: flagBool(flags, "allow-transcript-content"),
+  });
+  console.log(JSON.stringify(result));
+  return 0;
+}
+
+function resolve(flags: ReturnType<typeof parseArgs>["flags"]): number {
+  const narrativeDir = required(flags, "narrative-dir");
+  const sourceId = required(flags, "source-id");
+  const out = flagString(flags, "out");
+  const json = flagBool(flags, "json");
+  if (Boolean(out) === json) throw new Error("exactly one of --out or --json is required");
+  const result = resolveSource(narrativeDir, sourceId);
+  if (result.status === "unavailable") {
+    console.log(JSON.stringify(result));
+    return 2;
+  }
+  if (out) atomicWriteFile(path.dirname(path.resolve(out)), path.resolve(out), Buffer.from(result.content));
+  const { content: _content, ...metadata } = result;
+  console.log(JSON.stringify(metadata));
+  return 0;
+}
+
+function verify(flags: ReturnType<typeof parseArgs>["flags"]): number {
+  const narrativeDir = required(flags, "narrative-dir");
+  if (!flagBool(flags, "json")) throw new Error("--json is required");
+  const report = verifyManifest(narrativeDir);
+  console.log(JSON.stringify(report));
+  return report.ok ? 0 : 2;
+}
+
+function projectNarrative(flags: ReturnType<typeof parseArgs>["flags"]): number {
+  const narrativeDir = required(flags, "narrative-dir");
+  const out = flagString(flags, "out");
+  const json = flagBool(flags, "json");
+  if (Boolean(out) === json) throw new Error("exactly one of --out or --json is required");
+  const projectedAt = flagString(flags, "projected-at") ?? new Date().toISOString();
+  const projection = projectRuntimeNarrative(narrativeDir, { projectedAt });
+  const issues = validateNarrativeRuntimeProjection(projection);
+  if (issues.length > 0) {
+    throw new Error(`narrative runtime projection validation failed: ${issues.map((issue) => `${issue.path} ${issue.message}`).join("; ")}`);
+  }
+  const serialized = `${stableStringify(projection)}\n`;
+  if (out) atomicWriteFile(path.dirname(path.resolve(out)), path.resolve(out), Buffer.from(serialized));
+  else process.stdout.write(serialized);
+  return 0;
+}
+
+function composeNarrative(flags: ReturnType<typeof parseArgs>["flags"]): number {
+  const narrativeDir = required(flags, "narrative-dir");
+  const compiledAt = required(flags, "compiled-at");
+  const outDir = flagString(flags, "out-dir");
+  const json = flagBool(flags, "json");
+  const render = flagBool(flags, "render");
+  if (Boolean(outDir) === json) throw new Error("exactly one of --out-dir or --json is required");
+  if (render && !outDir) throw new Error("--render requires --out-dir");
+
+  const envelope = composeGroundedNarrative(narrativeDir, { compiledAt });
+  const issues = validateGroundedNarrative(envelope);
+  if (issues.length > 0) {
+    throw new Error(`grounded execution narrative validation failed: ${issues.map((issue) => `${issue.path} ${issue.message}`).join("; ")}`);
+  }
+  const grounding = validateNarrativeGrounding(envelope, narrativeDir);
+  if (!grounding.ok) throw new NarrativeGroundingError(grounding.violations);
+  if (outDir) {
+    const written = writeEnvelope(narrativeDir, envelope, { outDir, render });
+    process.stdout.write(`${stableStringify(written)}\n`);
+  } else {
+    process.stdout.write(`${stableStringify(envelope)}\n`);
+  }
+  return 0;
+}
+
+function captureIntentVerb(flags: ReturnType<typeof parseArgs>["flags"]): number {
+  const narrativeDir = path.resolve(required(flags, "narrative-dir"));
+  const runtime = required(flags, "runtime");
+  const actor = required(flags, "actor");
+  const actionRef = required(flags, "action-ref");
+  const activeGateRef = required(flags, "active-gate-ref");
+  const purpose = flagString(flags, "purpose");
+  const objectiveRef = flagString(flags, "objective-ref");
+  const narrativeFields = (flagString(flags, "redact-fields") ?? "").split(",").map((field) => field.trim()).filter(Boolean);
+  const redactionFields = effectiveNarrativeRedactionFields(narrativeFields);
+
+  // The capability is caller-resolved. By default it comes from the runtime's
+  // programmatic declaration (queryCapability, #620); --capability-fixture lets a
+  // FIXTURE inject a resolved status directly (D2) — no real runtime feeds
+  // at-action annotations yet, so the supported path is exercised via a fixture.
+  const fixture = flagString(flags, "capability-fixture");
+  let capability: CapabilityStatus;
+  if (fixture === "supported") capability = { status: "supported" };
+  else if (fixture === "unsupported") capability = { status: "unsupported", reason: "fixture-injected unsupported status" };
+  else if (fixture !== undefined) throw new Error("--capability-fixture must be 'supported' or 'unsupported'");
+  else capability = queryCapability(runtime, "intent_annotation");
+
+  ensureSafeDirectory(narrativeDir, narrativeDir);
+  // R1 (review HIGH): the action ref is co-bound to the frozen narrative manifest.
+  // captureIntent resolves it to its frozen manifest entry (existence + the action's
+  // own captured_at); a fabricated/nonexistent action ref is rejected (throws) before
+  // any annotation is written, and the annotation's captured_at derives from the
+  // resolved action entry rather than bind-time wall-clock.
+  const captured = captureIntent({
+    capability, actor, runtimeId: runtime, actionRef, activeGateRef, redactionFields,
+    ...(purpose !== undefined ? { purpose } : {}),
+    ...(objectiveRef !== undefined ? { objectiveRef } : {}),
+  }, { resolveAction: (ref) => resolveManifestEntry(narrativeDir, ref) });
+  const { path: annotationPath, annotation } = bindIntentAnnotation(narrativeDir, captured);
+  console.error(`captured ${annotation.mode} intent annotation at ${annotationPath}`);
+  console.log(JSON.stringify(annotation));
+  return 0;
+}
+
+function intentEconomicsVerb(flags: ReturnType<typeof parseArgs>["flags"]): number {
+  const narrativeDir = path.resolve(required(flags, "narrative-dir"));
+  const report = flagBool(flags, "report");
+  const record = flagBool(flags, "record");
+  if (report === record) throw new Error("exactly one of --record or --report is required");
+  if (report) {
+    const summary = reduceIntentEconomics(readIntentEconomics(narrativeDir));
+    console.log(JSON.stringify(summary));
+    return 0;
+  }
+  const mode = flagString(flags, "mode");
+  if (mode !== "annotation_on" && mode !== "annotation_off") throw new Error("--mode must be annotation_on or annotation_off");
+  const number = (name: string): number => {
+    const raw = required(flags, name);
+    const value = Number(raw);
+    if (!Number.isFinite(value)) throw new Error(`--${name} must be a number`);
+    return value;
+  };
+  ensureSafeDirectory(narrativeDir, narrativeDir);
+  appendIntentEconomics(narrativeDir, {
+    mode: mode as IntentAnnotationMode,
+    input_tokens: number("input-tokens"),
+    output_tokens: number("output-tokens"),
+    wall_clock_ms: number("wall-clock-ms"),
+    attempted_at: flagString(flags, "attempted-at") ?? new Date().toISOString(),
+  });
+  console.error(`recorded ${mode} intent-economics sample`);
+  return 0;
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+  const args = parseArgs(argv);
+  const verb = args.positionals[0];
+  try {
+    if (verb === "snapshot") return snapshot(args.flags);
+    if (verb === "resolve") return resolve(args.flags);
+    if (verb === "project") return projectNarrative(args.flags);
+    if (verb === "compose") return composeNarrative(args.flags);
+    if (verb === "verify") return verify(args.flags);
+    if (verb === "capture-intent") return captureIntentVerb(args.flags);
+    if (verb === "intent-economics") return intentEconomicsVerb(args.flags);
+    usage();
+    return 64;
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : "narrative source command failed");
+    return 64;
+  }
+}