@kontourai/flow-agents 0.2.0 → 0.3.0

package/kits/knowledge/flows/compile.flow.json

@@ -0,0 +1,60 @@
+{
+  "id": "knowledge.compile",
+  "version": "1.0",
+  "steps": [
+    { "id": "select-raws", "next": "compile" },
+    { "id": "compile", "next": "link" },
+    { "id": "link", "next": "done" },
+    { "id": "done", "next": null }
+  ],
+  "gates": {
+    "select-raws-gate": {
+      "step": "select-raws",
+      "expects": [
+        {
+          "id": "raw-ids-selected",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "One or more raw record IDs have been selected for compilation. Each ID must resolve to an existing raw record in the store.",
+          "claim": {
+            "type": "knowledge.compile.selection",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    },
+    "compile-gate": {
+      "step": "compile",
+      "expects": [
+        {
+          "id": "compiled-record-provenance",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "The compiled record has been created with provenance.source_ids listing every consumed raw ID, and source links (kind='source') from the compiled record to each raw record — satisfying the store contract's compiled record requirements.",
+          "claim": {
+            "type": "knowledge.compile.provenance",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    },
+    "link-gate": {
+      "step": "link",
+      "expects": [
+        {
+          "id": "provenance-refs-resolve",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "Every provenance ref in the compiled record resolves to a retrievable raw record via the store's get() operation. The graph index reflects all source links.",
+          "claim": {
+            "type": "knowledge.compile.link-integrity",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    }
+  }
+}

package/kits/knowledge/flows/consolidate.flow.json

@@ -0,0 +1,77 @@
+{
+  "id": "knowledge.consolidate",
+  "version": "1.0",
+  "steps": [
+    { "id": "related-event", "next": "propose" },
+    { "id": "propose", "next": "evidence-gate" },
+    { "id": "evidence-gate", "next": "apply-or-reject" },
+    { "id": "apply-or-reject", "next": "done" },
+    { "id": "done", "next": null }
+  ],
+  "gates": {
+    "related-event-gate": {
+      "step": "related-event",
+      "expects": [
+        {
+          "id": "related-compiled-records-found",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "One or more compiled records linked to the snapshot's topic have been identified. The trigger fires when new compiled records matching the snapshot topic (by category or explicit topic tag) are present. The result is a cluster of compiled record IDs that form the consolidation input.",
+          "claim": {
+            "type": "knowledge.consolidate.trigger",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    },
+    "propose-gate": {
+      "step": "propose",
+      "expects": [
+        {
+          "id": "consolidation-proposal-recorded",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "A consolidation proposal has been recorded. The proposal carries: the updated snapshot body (latest decisions), source_ids referencing every compiled record that contributed, and supersedes_ids referencing any prior snapshot(s) for the same topic. The snapshot record is NOT mutated at this step — only a consolidation proposal record and proposes link are created.",
+          "claim": {
+            "type": "knowledge.consolidate.proposal",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    },
+    "evidence-gate": {
+      "step": "evidence-gate",
+      "expects": [
+        {
+          "id": "proposal-carries-source-refs",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "The consolidation proposal evidence includes source_ids referencing every compiled record that contributed to the proposed snapshot body. Gate rejects if source_ids is empty or any referenced record does not exist. Also verifies that the proposer record has a 'proposes' link to the snapshot target.",
+          "claim": {
+            "type": "knowledge.consolidate.evidence",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    },
+    "apply-gate": {
+      "step": "apply-or-reject",
+      "expects": [
+        {
+          "id": "consolidation-gate-decision",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "A gate decision (apply or reject) has been recorded. If applied: snapshot body is updated via the store update op with the proposed body; supersede op links the new snapshot to any prior snapshots for the same topic; all superseded snapshots remain queryable with provenance intact. If rejected: the snapshot body is byte-identical to its pre-proposal state.",
+          "claim": {
+            "type": "knowledge.consolidate.gate-decision",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    }
+  }
+}

package/kits/knowledge/flows/ingest.flow.json

@@ -0,0 +1,60 @@
+{
+  "id": "knowledge.ingest",
+  "version": "1.0",
+  "steps": [
+    { "id": "capture", "next": "classify" },
+    { "id": "classify", "next": "route" },
+    { "id": "route", "next": "done" },
+    { "id": "done", "next": null }
+  ],
+  "gates": {
+    "capture-gate": {
+      "step": "capture",
+      "expects": [
+        {
+          "id": "raw-text-received",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "Raw text and metadata have been received and are non-empty.",
+          "claim": {
+            "type": "knowledge.ingest.capture",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    },
+    "classify-gate": {
+      "step": "classify",
+      "expects": [
+        {
+          "id": "classification-recorded",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "The raw record has been classified and stored with a non-empty category and type='raw', satisfying the store contract's create op provenance requirements.",
+          "claim": {
+            "type": "knowledge.ingest.classification",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    },
+    "route-gate": {
+      "step": "route",
+      "expects": [
+        {
+          "id": "routing-decision",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "A routing decision has been recorded for the classified raw record (e.g. queue for compile, discard, or hold).",
+          "claim": {
+            "type": "knowledge.ingest.routing",
+            "subject": "decision",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    }
+  }
+}

package/kits/knowledge/flows/store-contract.flow.json

@@ -0,0 +1,48 @@
+{
+  "id": "knowledge.store-contract",
+  "version": "1.0",
+  "steps": [
+    { "id": "verify-contract", "next": "done" },
+    { "id": "done", "next": null }
+  ],
+  "gates": {
+    "verify-contract-gate": {
+      "step": "verify-contract",
+      "expects": [
+        {
+          "id": "contract-suite-passed",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "The contract test suite has passed 100% against the target adapter, verifying round-trip integrity, required-evidence enforcement, and graph-index consistency.",
+          "claim": {
+            "type": "knowledge.store-contract.suite-result",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        },
+        {
+          "id": "mutation-provenance-enforced",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "Every mutation operation (create, update, link, propose, apply, reject) rejects requests missing required provenance fields, as verified by the contract suite.",
+          "claim": {
+            "type": "knowledge.store-contract.provenance-enforcement",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        },
+        {
+          "id": "round-trip-integrity",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "Records round-trip raw to stored to queried with category and links intact, as verified by the contract suite.",
+          "claim": {
+            "type": "knowledge.store-contract.round-trip",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    }
+  }
+}

package/kits/knowledge/flows/synthesize.flow.json

@@ -0,0 +1,77 @@
+{
+  "id": "knowledge.synthesize",
+  "version": "1.0",
+  "steps": [
+    { "id": "detect-cluster", "next": "propose" },
+    { "id": "propose", "next": "evidence-gate" },
+    { "id": "evidence-gate", "next": "apply-or-reject" },
+    { "id": "apply-or-reject", "next": "done" },
+    { "id": "done", "next": null }
+  ],
+  "gates": {
+    "detect-cluster-gate": {
+      "step": "detect-cluster",
+      "expects": [
+        {
+          "id": "similar-sources-found",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "At least one compiled record similar to the target concept has been identified via the similarity detector. Similarity v1 uses category match + link-overlap heuristic. The result is a cluster of source record IDs to synthesize from.",
+          "claim": {
+            "type": "knowledge.synthesize.cluster",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    },
+    "propose-gate": {
+      "step": "propose",
+      "expects": [
+        {
+          "id": "proposal-recorded",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "A proposal carrying source refs (proposer_id + source_ids in evidence) has been recorded via the store propose op. The concept body is NOT modified at this step — only a proposes link and mutation log entry are created.",
+          "claim": {
+            "type": "knowledge.synthesize.proposal",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    },
+    "evidence-gate": {
+      "step": "evidence-gate",
+      "expects": [
+        {
+          "id": "proposal-carries-source-refs",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "The proposal evidence includes source_ids referencing every compiled record that contributed to the proposed summary. Gate rejects if source_ids is empty or any referenced record does not exist.",
+          "claim": {
+            "type": "knowledge.synthesize.evidence",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    },
+    "apply-gate": {
+      "step": "apply-or-reject",
+      "expects": [
+        {
+          "id": "mutation-gate-decision",
+          "kind": "surface.claim",
+          "required": true,
+          "description": "A gate decision (apply or reject) has been recorded. If applied: concept body is updated via the store apply op with rationale and all contributing source_ids in provenance. If rejected: the store reject op is called, the concept body is byte-identical to its pre-proposal state, and only a rejection log entry is appended.",
+          "claim": {
+            "type": "knowledge.synthesize.gate-decision",
+            "subject": "artifact",
+            "accepted_statuses": ["trusted", "accepted"]
+          }
+        }
+      ]
+    }
+  }
+}

package/kits/knowledge/kit.json

@@ -0,0 +1,78 @@
+{
+  "schema_version": "1.0",
+  "id": "knowledge",
+  "name": "Knowledge Kit",
+  "product_name": "Knowledge Kit",
+  "description": "A Flow Kit for durable, gated knowledge storage. Provides a store contract with defined record types, mutation operations, and provenance rules \u2014 plus a default adapter backed by markdown files, YAML frontmatter, wikilinks, and a graph index.",
+  "flows": [
+    {
+      "id": "knowledge.store-contract",
+      "path": "flows/store-contract.flow.json",
+      "description": "Gate that requires contract-suite evidence before a store implementation is accepted."
+    },
+    {
+      "id": "knowledge.ingest",
+      "path": "flows/ingest.flow.json",
+      "description": "Ingest raw captures: capture \u2192 classify \u2192 route. Gate on classify requires category + type='raw' classification evidence per the store contract create op."
+    },
+    {
+      "id": "knowledge.compile",
+      "path": "flows/compile.flow.json",
+      "description": "Compile classified raws into durable notes: select-raws \u2192 compile \u2192 link. Gate on compile requires provenance refs to every consumed raw record."
+    },
+    {
+      "id": "knowledge.synthesize",
+      "path": "flows/synthesize.flow.json",
+      "description": "Synthesize compiled sources into concept summaries: detect-cluster \u2192 propose \u2192 evidence-gate \u2192 apply-or-reject. Mutation-gate policy: no summary mutates without an approved proposal carrying source refs; rejection leaves store untouched."
+    },
+    {
+      "id": "knowledge.consolidate",
+      "path": "flows/consolidate.flow.json",
+      "description": "Consolidate related compiled records into a living decision snapshot: related-event trigger -> consolidation proposal -> evidence gate -> apply-or-reject. Creates or updates a snapshot record; supersedes prior snapshots via supersede op (never deletes). Reuses S3 mutation-gate machinery."
+    }
+  ],
+  "docs": [
+    {
+      "id": "knowledge.readme",
+      "path": "docs/README.md"
+    },
+    {
+      "id": "knowledge.store-contract-doc",
+      "path": "docs/store-contract.md"
+    }
+  ],
+  "adapters": [
+    {
+      "id": "knowledge.default-store",
+      "path": "adapters/default-store/index.js",
+      "description": "Default store adapter: markdown files + YAML frontmatter + wikilinks + JSON graph index."
+    },
+    {
+      "id": "knowledge.flow-runner",
+      "path": "adapters/flow-runner/index.js",
+      "description": "Executable flow logic: capture(rawText, meta) \u2192 classified raw record; compile(rawIds[]) \u2192 compiled record with provenance links; synthesize(conceptId | topicSelector, options) \u2192 concept summary proposal with mutation gate; consolidate(snapshotId | topicSelector, options) \u2192 decision snapshot consolidation with supersede-not-delete. Emits canonical telemetry events at gate points."
+    }
+  ],
+  "evals": [
+    {
+      "id": "knowledge.contract-suite",
+      "path": "evals/contract-suite/suite.test.js",
+      "description": "Parameterized contract test suite for any Knowledge Kit store adapter."
+    },
+    {
+      "id": "knowledge.ingest-compile-suite",
+      "path": "evals/ingest-compile/suite.test.js",
+      "description": "Eval cases for ingest (AC-mapped), compile provenance gate, telemetry emission, and ref resolution."
+    },
+    {
+      "id": "knowledge.synthesis-suite",
+      "path": "evals/synthesis/suite.test.js",
+      "description": "Eval cases for synthesize: AC1 (similar source \u2192 proposal not mutation), AC2 (rejection leaves concept byte-identical), AC3 (apply updates with provenance to all contributing sources), pluggable-similarity interface test, gate telemetry."
+    },
+    {
+      "id": "knowledge.consolidation-suite",
+      "path": "evals/consolidation/suite.test.js",
+      "description": "Eval cases for consolidate: AC1 (related event -> proposal, not mutation); AC2 (apply updates exactly ONE snapshot, links supersedes refs, superseded sources still queryable); AC3 fixture (decision changed across 3 events -> snapshot reflects ONLY latest decision, provenance to all 3); supersede-not-delete invariant; gate telemetry; contract suite extensions for snapshot semantics."
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Flow Agents — a Kontour product that applies Flow and Veritas discipline as a portable process layer inside the agent tools you already use: Claude Code, Codex, Kiro, opencode, pi, and GitHub Actions — with framework adapters (AWS Strands preview) on the same policy-engine contract.",
   "keywords": [
     "agents",

package/src/cli/flow-kit.ts

@@ -4,7 +4,7 @@ import * as path from "node:path";
 import { parseArgs, flagBool, flagString } from "../lib/args.js";
 import { assertPathContained, copyDir, isoNow, readJson, walkFiles, writeJson } from "../lib/fs.js";
 import { assertKitRepository } from "../flow-kit/validate.js";
-import { activateCodexLocal } from "../runtime-adapters.js";
+import { activateCodexLocal, activateStrandsLocal } from "../runtime-adapters.js";
 
 const REGISTRY_REL = path.join("kits", "local", "installed-kits.json");
 const REPOSITORIES_REL = path.join("kits", "local", "repositories");
@@ -112,16 +112,22 @@ function status(argv: string[]): number {
   return 0;
 }
 
+// Available adapters for the activate subcommand (Issue #32: added strands-local).
+const AVAILABLE_ADAPTERS = ["codex-local", "strands-local"];
+
 function activate(argv: string[]): number {
   const args = parseArgs(argv);
   const dest = path.resolve(flagString(args.flags, "dest", ".") ?? ".");
   const sourceRoot = path.resolve(flagString(args.flags, "source-root", path.resolve(path.dirname(process.argv[1]), "..")) ?? ".");
   const adapter = flagString(args.flags, "adapter");
-  if (adapter && adapter !== "codex-local") {
-    console.log(JSON.stringify({ selected_adapter: null, available_adapters: ["codex-local"], supported_asset_classes: [], generated_runtime_files: [], skipped_assets: [], warnings: [], errors: [`unknown runtime adapter '${adapter}'; available adapters: codex-local`] }, null, 2));
+  if (adapter && !AVAILABLE_ADAPTERS.includes(adapter)) {
+    console.log(JSON.stringify({ selected_adapter: null, available_adapters: AVAILABLE_ADAPTERS, supported_asset_classes: [], generated_runtime_files: [], skipped_assets: [], warnings: [], errors: [`unknown runtime adapter '${adapter}'; available adapters: ${AVAILABLE_ADAPTERS.join(", ")}`] }, null, 2));
     return 2;
   }
-  const result = activateCodexLocal(sourceRoot, dest);
+  // Default to codex-local for backward compatibility; strands-local is opt-in via --adapter.
+  const result = adapter === "strands-local"
+    ? activateStrandsLocal(sourceRoot, dest)
+    : activateCodexLocal(sourceRoot, dest);
   console.log(JSON.stringify(result, null, 2));
   return Array.isArray(result.errors) && result.errors.length ? 1 : 0;
 }

package/src/cli/runtime-adapter.ts

@@ -1,22 +1,27 @@
 import * as path from "node:path";
 import { parseArgs, flagString } from "../lib/args.js";
-import { activateCodexLocal } from "../runtime-adapters.js";
+import { activateCodexLocal, activateStrandsLocal } from "../runtime-adapters.js";
+
+const AVAILABLE_ADAPTERS = ["codex-local", "strands-local"];
 
 export function main(argv = process.argv.slice(2)): number {
   const [command, ...rest] = argv;
   if (command !== "activate") {
-    console.error("usage: runtime-adapter activate [--dest DIR] [--source-root DIR] [--adapter codex-local]");
+    console.error("usage: runtime-adapter activate [--dest DIR] [--source-root DIR] [--adapter codex-local|strands-local]");
     return 2;
   }
   const args = parseArgs(rest);
   const dest = path.resolve(flagString(args.flags, "dest", ".") ?? ".");
   const sourceRoot = path.resolve(flagString(args.flags, "source-root", path.resolve(path.dirname(process.argv[1]), "..")) ?? ".");
   const adapter = flagString(args.flags, "adapter");
-  if (adapter && adapter !== "codex-local") {
-    console.log(JSON.stringify({ selected_adapter: null, available_adapters: ["codex-local"], supported_asset_classes: [], generated_runtime_files: [], skipped_assets: [], warnings: [], errors: [`unknown runtime adapter '${adapter}'; available adapters: codex-local`] }, null, 2));
+  if (adapter && !AVAILABLE_ADAPTERS.includes(adapter)) {
+    console.log(JSON.stringify({ selected_adapter: null, available_adapters: AVAILABLE_ADAPTERS, supported_asset_classes: [], generated_runtime_files: [], skipped_assets: [], warnings: [], errors: [`unknown runtime adapter '${adapter}'; available adapters: ${AVAILABLE_ADAPTERS.join(", ")}`] }, null, 2));
     return 2;
   }
-  const result = activateCodexLocal(sourceRoot, dest);
+  // Default to codex-local for backward compatibility; strands-local is opt-in via --adapter.
+  const result = adapter === "strands-local"
+    ? activateStrandsLocal(sourceRoot, dest)
+    : activateCodexLocal(sourceRoot, dest);
   console.log(JSON.stringify(result, null, 2));
   return Array.isArray(result.errors) && result.errors.length ? 1 : 0;
 }

package/src/cli/telemetry-doctor.ts

@@ -82,7 +82,10 @@ function channelConfigValue(config: Config, channel: string, key: string, fallba
 
 function telemetryDataDir(dest: string): string {
   const configured = process.env.TELEMETRY_DATA_DIR;
-  return configured ? path.resolve(dest, configured) : path.resolve(dest, "..", ".telemetry");
+  // 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");
 }
 
 function deriveConsoleEndpoint(consoleUrl: string, explicitEndpoint: string): string {

package/src/runtime-adapters.ts

@@ -152,3 +152,38 @@ export function activateCodexLocal(sourceRoot: string, dest: string): Record<str
   generated.push({ asset_class: "activation-manifest", path: relPath(dest, manifestPath), kit_id: "runtime", asset_id: "codex-local.activation", source_path: manifestPath.split(path.sep).join("/") });
   return { selected_adapter: "codex-local", supported_asset_classes: ["flows"], generated_runtime_files: generated, skipped_assets: skipped, warnings: inventory.warnings, errors: inventory.errors };
 }
+
+// Decision Q3 (Issue #32): Option (a) — new adapter id "strands-local" rather than
+// loading kit flows inside FlowAgentsHooks. Rationale: activation is a workspace-prep
+// concern (reads catalog + installed kits, writes runtime files, produces diagnostics).
+// Keeping it in the CLI adapter layer maximises reuse of readKitInventory and safeSegment,
+// mirrors the codex-local pattern exactly, and keeps framework adapters free of catalog-
+// layout knowledge. The Strands steering layer then reads the written runtime files.
+export function activateStrandsLocal(sourceRoot: string, dest: string): Record<string, unknown> {
+  const inventory = readKitInventory(sourceRoot, dest);
+  // Runtime flows land at .flow-agents/runtime/strands/flows/<kit-id>/<asset-id>.flow.json
+  // so the Strands steering context can glob for *.flow.json under this path.
+  const runtimeDir = path.join(dest, ".flow-agents", "runtime", "strands");
+  const generated: Record<string, string>[] = [];
+  const skipped: Record<string, string | null>[] = [];
+  for (const asset of inventory.assets) {
+    if (asset.asset_class !== "flows") {
+      skipped.push({ asset_class: asset.asset_class, path: asset.relative_path, kit_id: asset.kit_id, asset_id: asset.asset_id, reason: "asset class is diagnostic-only for strands-local" });
+      continue;
+    }
+    if (!asset.asset_id) {
+      skipped.push({ asset_class: asset.asset_class, path: asset.relative_path, kit_id: asset.kit_id, asset_id: null, reason: "flow asset is missing an id" });
+      continue;
+    }
+    const output = path.join(runtimeDir, "flows", safeSegment(asset.kit_id), `${safeSegment(asset.asset_id)}.flow.json`);
+    fs.mkdirSync(path.dirname(output), { recursive: true });
+    fs.copyFileSync(asset.source_path, output);
+    generated.push({ asset_class: asset.asset_class, path: relPath(dest, output), kit_id: asset.kit_id, asset_id: asset.asset_id, source_path: asset.source_path.split(path.sep).join("/") });
+  }
+  fs.mkdirSync(runtimeDir, { recursive: true });
+  const manifest = { schema_version: "1.0", adapter: "strands-local", supported_asset_classes: ["flows"], generated_runtime_files: generated, skipped_assets: skipped, warnings: inventory.warnings, errors: inventory.errors };
+  const manifestPath = path.join(runtimeDir, "activation.json");
+  writeJson(manifestPath, manifest);
+  generated.push({ asset_class: "activation-manifest", path: relPath(dest, manifestPath), kit_id: "runtime", asset_id: "strands-local.activation", source_path: manifestPath.split(path.sep).join("/") });
+  return { selected_adapter: "strands-local", supported_asset_classes: ["flows"], generated_runtime_files: generated, skipped_assets: skipped, warnings: inventory.warnings, errors: inventory.errors };
+}

package/src/tools/build-universal-bundles.ts

@@ -355,6 +355,15 @@ function exportOpencodePlugin(): string {
   // (for session-start steering context) and tool.execute.before (for
   // policy). This is the closest reasonable approximation — documented here
   // as an honest gap matching the codex live-hook-influence caveat pattern.
+  //
+  // KNOWN GAP (verified 2026-06-11, opencode v1.16.2): session.created is NOT
+  // delivered to plugin event handlers in opencode  (non-interactive) mode.
+  // The session IS created server-side but the event fires before the plugin
+  // hook dispatch loop is active. As a result, agentSpawn telemetry (session.start)
+  // is never emitted in run-mode sessions — only tool.invoke/tool.result appear.
+  // This is an opencode runtime limitation, not a bug in this plugin.
+  // Session.start telemetry carries L1 conformance but is unavailable in run mode.
+  // See docs/spec/runtime-hook-surface.md opencode mapping row for the full gap note.
   return `/**
  * Flow Agents opencode plugin.
  *
@@ -369,6 +378,13 @@ function exportOpencodePlugin(): string {
  * cannot intercept mid-session user messages before they are processed.
  * This is an accepted gap documented here analogously to the codex
  * live-hook-influence caveat.
+ *
+ * KNOWN GAP: session.created is NOT delivered to plugin handlers in opencode
+ * run (non-interactive) mode (verified v1.16.2, 2026-06-11). agentSpawn
+ * telemetry (session.start) is therefore absent from run-mode sessions.
+ * tool.invoke and tool.result events (L1) are still recorded normally.
+ * This is an opencode runtime limitation; no workaround is available without
+ * a different hook surface. See docs/spec/runtime-hook-surface.md for details.
  */
 
 import { spawnSync } from 'node:child_process';
@@ -547,7 +563,8 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.on("before_agent_start", async (event, _ctx) => {
-    runTelemetry("before_agent_start");
+    // Telemetry for agentSpawn is emitted by session_start above; do not repeat it here
+    // to avoid duplicate session.start events in the telemetry log.
     // Inject workflow steering context at agent start
     const result = runAdapter("pi-hook-adapter.js", "before_agent_start", "workflow-steering", "workflow-steering.js");
     if (result.context) {