@kontourai/flow-agents 1.2.0 → 1.3.0

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

@@ -14,12 +14,12 @@
       "expects": [
         {
           "id": "similar-sources-found",
-          "kind": "surface.claim",
+          "kind": "trust.bundle",
           "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",
+          "bundle_claim": {
+            "claimType": "knowledge.synthesize.cluster",
+            "subjectType": "artifact",
             "accepted_statuses": ["trusted", "accepted"]
           }
         }
@@ -30,12 +30,12 @@
       "expects": [
         {
           "id": "proposal-recorded",
-          "kind": "surface.claim",
+          "kind": "trust.bundle",
           "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",
+          "bundle_claim": {
+            "claimType": "knowledge.synthesize.proposal",
+            "subjectType": "artifact",
             "accepted_statuses": ["trusted", "accepted"]
           }
         }
@@ -46,12 +46,12 @@
       "expects": [
         {
           "id": "proposal-carries-source-refs",
-          "kind": "surface.claim",
+          "kind": "trust.bundle",
           "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",
+          "bundle_claim": {
+            "claimType": "knowledge.synthesize.evidence",
+            "subjectType": "artifact",
             "accepted_statuses": ["trusted", "accepted"]
           }
         }
@@ -62,12 +62,12 @@
       "expects": [
         {
           "id": "mutation-gate-decision",
-          "kind": "surface.claim",
+          "kind": "trust.bundle",
           "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",
+          "bundle_claim": {
+            "claimType": "knowledge.synthesize.gate-decision",
+            "subjectType": "artifact",
             "accepted_statuses": ["trusted", "accepted"]
           }
         }

package/kits/release-evidence/flows/release-evidence.flow.json

@@ -13,12 +13,12 @@
       "expects": [
         {
           "id": "release-claim-present",
-          "kind": "surface.claim",
+          "kind": "trust.bundle",
           "required": true,
           "description": "A trusted release.evidence claim must be attached before this gate can pass.",
           "explore_hint": "Attach a trust-report JSON file with claim type release.evidence and status trusted.",
-          "claim": {
-            "type": "release.evidence",
+          "bundle_claim": {
+            "claimType": "release.evidence",
             "accepted_statuses": [
               "trusted"
             ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "1.2.0",
+  "version": "1.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",
@@ -133,6 +133,9 @@
     "typescript": "^6.0.3"
   },
   "dependencies": {
-    "@kontourai/flow": "^1.2.0"
+    "@kontourai/flow": "~1.3.0"
+  },
+  "optionalDependencies": {
+    "hachure": "^0.4.0"
   }
 }

package/schemas/workflow-evidence.schema.json

@@ -239,7 +239,8 @@
               "properties": {
                 "artifact_kind": {
                   "type": "string",
-                  "enum": ["TrustReport", "Trust Snapshot"]
+                  "description": "Hachure-aligned artifact kind. trust.bundle is the canonical value; TrustReport and Trust Snapshot are legacy aliases.",
+                  "enum": ["trust.bundle", "TrustReport", "Trust Snapshot"]
                 },
                 "artifact_ref": {
                   "type": "string",

package/scripts/hooks/stop-goal-fit.js

@@ -80,6 +80,15 @@ function hasSidecars(dir) {
   }
 }
 
+/**
+ * Returns true if a line of validator output looks like a validator-environment
+ * error (shell/npm error, tsc missing, spawn failure) rather than a real
+ * artifact validation message. Environment errors must never block goal-fit.
+ */
+function isEnvironmentError(line) {
+  return /tsc[:\s]|command not found|npm ERR!|npm error|ENOENT|EACCES|Cannot find module|node_modules\/.bin|TypeScript version|version conflict|error TS[0-9]/i.test(line);
+}
+
 function sidecarValidation(root, artifactDir) {
   const requireSidecars = String(process.env.FLOW_AGENTS_REQUIRE_SIDECARS || '').toLowerCase() === 'true';
   const requireCritique = String(process.env.FLOW_AGENTS_REQUIRE_CRITIQUE || '').toLowerCase() === 'true';
@@ -88,8 +97,6 @@ function sidecarValidation(root, artifactDir) {
   const packageRoot = fs.existsSync(path.join(root, 'package.json'))
     ? root
     : path.resolve(__dirname, '..', '..');
-  const packageJson = path.join(packageRoot, 'package.json');
-  if (!fs.existsSync(packageJson)) return [`${relative(root, artifactDir)} sidecar validation: package.json is missing; cannot run TypeScript workflow validator.`];
 
   let sidecarFiles = [];
   try {
@@ -112,26 +119,67 @@ function sidecarValidation(root, artifactDir) {
 
   if (sidecarFiles.length === 0) return [];
 
-  const args = ['run', 'workflow:validate-artifacts', '--silent', '--'];
-  args.push('--skip-markdown-validation');
-  if (requireSidecars) args.push('--require-sidecars');
-  if (requireCritique) args.push('--require-critique');
-  args.push(artifactDir);
+  // Part 1 fix: invoke the already-built validator directly via `node`, bypassing
+  // `npm run build` (tsc). npm-installed packages ship build/ in the package files,
+  // so the compiled JS is always available. Only fall back to npm run if build/ is
+  // absent (a raw dev checkout that hasn't been built yet).
+  const builtValidator = path.join(packageRoot, 'build', 'src', 'cli', 'validate-workflow-artifacts.js');
+  const hasBuild = fs.existsSync(builtValidator);
+
+  const validatorArgs = ['--skip-markdown-validation'];
+  if (requireSidecars) validatorArgs.push('--require-sidecars');
+  if (requireCritique) validatorArgs.push('--require-critique');
+  validatorArgs.push(artifactDir);
+
+  let result;
+  if (hasBuild) {
+    // Direct node invocation: no tsc, no npm build step, works from any npm install.
+    result = spawnSync(process.execPath, [builtValidator, ...validatorArgs], {
+      cwd: packageRoot,
+      encoding: 'utf8',
+      timeout: 30000,
+    });
+  } else {
+    // Dev checkout without build/: fall back to npm run (may trigger tsc).
+    // If this also fails due to environment issues, Part 2 handles it below.
+    const npmArgs = ['run', 'workflow:validate-artifacts', '--silent', '--', ...validatorArgs];
+    result = spawnSync('npm', npmArgs, {
+      cwd: packageRoot,
+      encoding: 'utf8',
+      timeout: 30000,
+    });
+  }
 
-  const result = spawnSync('npm', args, {
-    cwd: packageRoot,
-    encoding: 'utf8',
-    timeout: 30000,
-  });
+  // Part 2 fix: treat validator-environment failures as SKIP, never as blocking.
+  // A spawn error (ENOENT, timeout) means the validator couldn't run at all.
+  if (result.error) {
+    // Validator couldn't be launched — environment issue, not a goal-fit failure.
+    return [`${relative(root, artifactDir)} sidecar validation skipped: validator could not run (${result.error.code || result.error.message})`];
+  }
 
   if (result.status === 0) return [];
-  const output = `${result.stdout || ''}\n${result.stderr || ''}`
+
+  // Validator ran and exited non-zero. Separate real validation errors from
+  // environment errors (tsc missing, npm ERR!, shell errors) so that a broken
+  // validator environment never blocks goal-fit.
+  const allLines = `${result.stdout || ''}\n${result.stderr || ''}`
     .split('\n')
     .map(line => line.trim())
-    .filter(Boolean)
-    .slice(0, 12);
-  if (output.length === 0) output.push(`validator exited with status ${result.status ?? 'unknown'}`);
-  return output.map(line => `${relative(root, artifactDir)} sidecar validation: ${line}`);
+    .filter(Boolean);
+
+  const envLines = allLines.filter(isEnvironmentError);
+  const validationLines = allLines.filter(line => !isEnvironmentError(line));
+
+  if (envLines.length > 0 && validationLines.length === 0) {
+    // Pure environment failure — skip, do not block.
+    return [`${relative(root, artifactDir)} sidecar validation skipped: validator environment error (${envLines[0].slice(0, 120)})`];
+  }
+
+  // Real validation errors (possibly mixed with a few env noise lines).
+  const output = validationLines.length > 0 ? validationLines : allLines;
+  const trimmed = output.slice(0, 12);
+  if (trimmed.length === 0) trimmed.push(`validator exited with status ${result.status ?? 'unknown'}`);
+  return trimmed.map(line => `${relative(root, artifactDir)} sidecar validation: ${line}`);
 }
 
 function isWorkflowArtifact(artifact) {
@@ -295,7 +343,7 @@ function analyze(root, now = Date.now()) {
   }
   warnings.push(...sidecarGuidance(root, path.dirname(latest.file)));
 
-  const blocking = warnings.some(w => /status:|Definition Of Done|Goal Fit|sidecar validation|contradicts evidence\.json|workflow state|evidence verdict|evidence check|NOT_VERIFIED gap|critique status|critique open|next action/.test(w));
+  const blocking = warnings.some(w => /status:|Definition Of Done|Goal Fit|sidecar validation:|contradicts evidence\.json|workflow state|evidence verdict|evidence check|NOT_VERIFIED gap|critique status|critique open|next action/.test(w));
   return { warnings, blocking };
 }
 

package/src/cli/workflow-sidecar.ts

@@ -2,6 +2,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { execFileSync } from "node:child_process";
+import { createRequire } from "node:module";
 
 type AnyObj = Record<string, any>;
 
@@ -24,6 +25,46 @@ function appendJsonl(file: string, payload: AnyObj): void {
 function die(message: string): never { throw new Error(message); }
 function slugify(value: string, fallback: string): string { return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || fallback; }
 
+// Optional Hachure trust-bundle validation. No-ops gracefully when hachure is not installed.
+// Install hachure (^0.4.0) as an optional dependency to enable schema validation.
+function tryLoadHachureValidator(): ((bundle: unknown) => { valid: boolean; errors: string[] }) | null {
+  try {
+    const _require = createRequire(import.meta.url);
+    const hachureDir = path.dirname(_require.resolve("hachure"));
+    const schemasDir = path.join(hachureDir, "schemas");
+    const Ajv = _require("ajv/dist/2020");
+    const schemas: Record<string, any> = {};
+    for (const file of fs.readdirSync(schemasDir)) {
+      if (!file.endsWith(".schema.json")) continue;
+      schemas[file] = JSON.parse(fs.readFileSync(path.join(schemasDir, file), "utf8"));
+    }
+    const ajv = new Ajv({ strict: false, allErrors: true });
+    for (const [filename, schema] of Object.entries(schemas)) {
+      if (filename === "trust-bundle.schema.json") continue;
+      ajv.addSchema(schema, filename);
+    }
+    const trustBundleSchema = schemas["trust-bundle.schema.json"];
+    if (!trustBundleSchema) return null;
+    const validate = ajv.compile(trustBundleSchema);
+    return (bundle: unknown) => {
+      const valid = validate(bundle);
+      if (valid) return { valid: true, errors: [] };
+      const errors = ((validate as any).errors ?? []).map((err: any) => {
+        const loc = err.instancePath || err.schemaPath || "";
+        return `${loc} ${err.message ?? "invalid"}`.trim();
+      });
+      return { valid: false, errors };
+    };
+  } catch {
+    return null;
+  }
+}
+let _hachureValidator: ReturnType<typeof tryLoadHachureValidator> | undefined;
+function getHachureValidator(): ReturnType<typeof tryLoadHachureValidator> {
+  if (_hachureValidator === undefined) _hachureValidator = tryLoadHachureValidator();
+  return _hachureValidator;
+}
+
 function safeRepoIdentifier(value: string): string {
   const trimmed = value.trim().replace(/\.git$/, "");
   if (!trimmed || trimmed.length > 120) return "";
@@ -372,11 +413,27 @@ function normalizeCheck(raw: AnyObj): AnyObj {
 }
 function normalizeSurfaceRefs(refs: any): AnyObj[] {
   if (!Array.isArray(refs)) die("surface_trust_refs must be an array");
+  const hachureValidate = getHachureValidator();
   return refs.map((ref) => {
     const keys = JSON.stringify(ref).match(/"([^"]+)":/g) ?? [];
     for (const key of keys.map((k) => k.slice(1, -2))) if (key.toLowerCase().includes("veritas")) die(`unsupported field in Surface trust ref: ${key}`);
     const out = { ...ref };
-    if (!["TrustReport", "Trust Snapshot"].includes(out.artifact_kind)) die("artifact_kind must be one of");
+    // trust.bundle is the canonical Hachure-aligned artifact kind; TrustReport/Trust Snapshot are legacy aliases
+    if (!["trust.bundle", "TrustReport", "Trust Snapshot"].includes(out.artifact_kind)) die("artifact_kind must be one of: trust.bundle, TrustReport, Trust Snapshot");
+    // When hachure is installed, validate the referenced trust artifact if it is a local file
+    if (hachureValidate && out.artifact_ref && typeof out.artifact_ref === "string" && fs.existsSync(out.artifact_ref)) {
+      try {
+        const bundle = JSON.parse(fs.readFileSync(out.artifact_ref, "utf8"));
+        const result = hachureValidate(bundle);
+        if (!result.valid) {
+          const errorSummary = result.errors.slice(0, 3).join("; ");
+          die(`trust.bundle artifact at ${out.artifact_ref} failed Hachure schema validation: ${errorSummary}`);
+        }
+      } catch (err) {
+        if (err instanceof Error && err.message.includes("failed Hachure schema validation")) throw err;
+        // File read or parse errors are not re-thrown: the artifact_ref validation path is advisory
+      }
+    }
     const status = deriveSurfaceStatus(out);
     if (out.status === "pass" && status !== "pass") die("surface_trust_refs contradicts Surface trust facts");
     return out;
@@ -394,15 +451,16 @@ function surfaceCheckFromArtifact(file: string, index: number): AnyObj {
   const lower = JSON.stringify(raw).toLowerCase();
   let ref: AnyObj;
   if (lower.includes("provider") && lower.includes("absent")) {
-    ref = { artifact_kind: "TrustReport", artifact_ref: file, gate_id: "provider.unavailable", claim_type: "surface.claim", claim_status: "unknown", subject: "builder-kit", freshness: { status: "unknown", summary: "No trust provider is configured" }, authority: { producer: "unknown", summary: "No trust provider is configured" }, integrity: { status: "unknown", summary: "Unknown" }, status: "not_verified", summary: "No trust provider is configured" };
+    ref = { artifact_kind: "trust.bundle", artifact_ref: file, gate_id: "provider.unavailable", claim_type: "builder.trust.bundle", claim_status: "unknown", subject: "builder-kit", freshness: { status: "unknown", summary: "No trust provider is configured" }, authority: { producer: "unknown", summary: "No trust provider is configured" }, integrity: { status: "unknown", summary: "Unknown" }, status: "not_verified", summary: "No trust provider is configured" };
   } else if (lower.includes("artifact") && lower.includes("absent")) {
-    ref = { artifact_kind: "TrustReport", artifact_ref: file, gate_id: "artifact.unavailable", claim_type: "surface.claim", claim_status: "unknown", subject: "builder-kit", freshness: { status: "unknown", summary: "Artifact not readable" }, authority: { producer: "unknown", summary: "Artifact not readable" }, integrity: { status: "unknown", summary: "Artifact not readable" }, status: "not_verified", summary: "artifact not readable" };
+    ref = { artifact_kind: "trust.bundle", artifact_ref: file, gate_id: "artifact.unavailable", claim_type: "builder.trust.bundle", claim_status: "unknown", subject: "builder-kit", freshness: { status: "unknown", summary: "Artifact not readable" }, authority: { producer: "unknown", summary: "Artifact not readable" }, integrity: { status: "unknown", summary: "Artifact not readable" }, status: "not_verified", summary: "artifact not readable" };
   } else {
     const claimStatus = lower.includes("rejected") ? "rejected" : "accepted";
     const freshness = lower.includes("stale") ? "stale" : "fresh";
     const producer = lower.includes("missing-authority") ? "unknown" : "surface-local";
     const integrity = lower.includes("mismatch") ? "mismatch" : "matched";
-    ref = { artifact_kind: file.includes("snapshot") ? "Trust Snapshot" : "TrustReport", artifact_ref: file, gate_id: "builder.surface.claim", claim_type: "surface.claim", claim_status: claimStatus, subject: "builder-kit", freshness: { status: freshness, summary: freshness === "fresh" ? "fresh" : "not currently verifiable" }, authority: { producer, summary: producer === "unknown" ? "missing authority" : "Local Surface trust producer." }, integrity: { status: integrity, summary: integrity === "matched" ? "matched" : "integrity mismatch" } };
+    // Use trust.bundle as the canonical Hachure-aligned artifact_kind for all trust-backed evidence refs
+    ref = { artifact_kind: "trust.bundle", artifact_ref: file, gate_id: "builder.trust.bundle", claim_type: "builder.trust.bundle", claim_status: claimStatus, subject: "builder-kit", freshness: { status: freshness, summary: freshness === "fresh" ? "fresh" : "not currently verifiable" }, authority: { producer, summary: producer === "unknown" ? "missing authority" : "Local Surface trust producer." }, integrity: { status: integrity, summary: integrity === "matched" ? "matched" : "integrity mismatch" } };
     ref.status = deriveSurfaceStatus(ref);
     ref.summary = ref.status === "pass" ? "accepted" : ref.status === "not_verified" ? "not currently verifiable" : (claimStatus === "rejected" ? "rejected" : producer === "unknown" ? "missing authority" : "integrity mismatch");
   }

package/src/flow-kit/validate.ts

@@ -24,6 +24,47 @@ export interface KitConformanceLevel {
   k2: boolean;
 }
 
+/**
+ * Kit trust level — WHO vouches for a kit, orthogonal to the K-level capability axis.
+ *
+ * - "first-party": the kit is authored and published by Kontour (kontourai); its id is in the
+ *   FIRST_PARTY_KIT_IDS allowlist maintained in this repository. These kits are built, tested,
+ *   and distributed with the flow-agents package.
+ * - "verified": reserved for a future third-party verification process (e.g. self-certification
+ *   via the conformance kit + cryptographic attestation / Veritas claims). Not yet implemented.
+ * - "unverified": default for all kits not in the first-party allowlist. This says nothing about
+ *   the kit's quality — it only means Kontour has not vouched for it.
+ *
+ * The v2 path for "verified": cryptographic signing / attestation against the conformance kit
+ * and Veritas claims substrate is the natural next step and is intentionally deferred.
+ */
+export type KitTrustLevel = "first-party" | "verified" | "unverified";
+
+/**
+ * Allowlist of kit IDs that Kontour authors, tests, and ships with the flow-agents package.
+ *
+ * Criteria for inclusion:
+ *   1. The kit directory lives under kits/ in the kontourai/flow-agents repository.
+ *   2. The kit is published by @kontourai (npm package @kontourai/flow-agents).
+ *   3. Kontour owns and maintains the kit's content and release lifecycle.
+ *
+ * To add a new first-party kit: add its id here AND ensure it lives under kits/ in this repo.
+ * Third-party forks or community kits published elsewhere are NOT first-party, even if they
+ * share a similar id — first-party is tied to provenance in this specific repository.
+ */
+export const FIRST_PARTY_KIT_IDS: ReadonlySet<string> = new Set(["builder", "knowledge"]);
+
+/**
+ * Derive the trust level for a kit id.
+ *
+ * v1 determination: allowlist check against FIRST_PARTY_KIT_IDS.
+ * "verified" is reserved for future third-party verification (not yet granted to any kit).
+ */
+export function deriveKitTrust(kitId: string): KitTrustLevel {
+  if (FIRST_PARTY_KIT_IDS.has(kitId)) return "first-party";
+  return "unverified";
+}
+
 export interface KitTargetsResult {
   kit_id: string;
   kit_name: string;
@@ -32,6 +73,11 @@ export interface KitTargetsResult {
   targets: KitTargetConsumer[];
   /** Extension field namespaces that are not Flow or Flow Agents-owned. */
   third_party_extensions: string[];
+  /**
+   * Trust level: who vouches for this kit. Orthogonal to the K-level capability axis.
+   * "first-party" = Kontour-published; "verified" = reserved (future); "unverified" = default.
+   */
+  trust: KitTrustLevel;
 }
 
 // Lazy-loaded cache for validateKitContainer from @kontourai/flow.
@@ -83,7 +129,7 @@ async function delegateCoreContainerValidation(kitDir: string, manifest: Record<
 }
 
 /**
- * Derives the consumer-target level (K0/K1/K2) and target audience list from
+ * Derives the consumer-target level (K0/K1/K2), target audience list, and trust level from
  * observable asset classes in the kit manifest. Does not require file I/O.
  *
  * Derivation rules (from kontourai/flow-agents#52 and Brian's layering review):
@@ -94,6 +140,10 @@ async function delegateCoreContainerValidation(kitDir: string, manifest: Record<
  *  - targets.flow-agents: present when K1 (agent extension assets activate in >=1 harness).
  *  - third-party: any top-level keys that are not core fields and not Flow Agents extension classes.
  *
+ * Trust derivation (from kontourai/flow-agents#79):
+ *  - "first-party": kit id is in FIRST_PARTY_KIT_IDS (Kontour-authored kits in this repo).
+ *  - "unverified": all other kits (default; "verified" is reserved for a future process).
+ *
  * @param manifest  The kit.json manifest object.
  * @param kitDir    Kit directory for flow file-existence checks. Defaults to "" (structural-only).
  *                  Pass the real kit directory from `inspect` to get authoritative K0 validation.
@@ -125,12 +175,16 @@ export async function deriveKitTargets(manifest: Record<string, unknown>, kitDir
   if (k1) targets.push("flow-agents");
   for (const ns of thirdPartyExtensions) targets.push(ns);
 
+  // Derive trust level orthogonally to the K-level capability axis.
+  const trust = deriveKitTrust(kitId);
+
   return {
     kit_id: kitId,
     kit_name: kitName,
     conformance: { k0, k1, k2 },
     targets,
     third_party_extensions: thirdPartyExtensions,
+    trust,
   };
 }
 

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

@@ -439,6 +439,7 @@ function exportOpencodePlugin(): string {
 
 import { spawnSync } from 'node:child_process';
 import { join, basename } from 'node:path';
+import { mkdirSync, writeFileSync } from 'node:fs';
 
 // opencode runs plugins inside its own compiled (Bun-based) binary, so
 // process.execPath points at opencode itself — spawning it with a script
@@ -449,6 +450,19 @@ const NODE_BIN = basename(process.execPath).startsWith('node') ? process.execPat
 export const FlowAgentsPlugin = async ({ project, client, $, directory, worktree }) => {
   const root = directory || process.cwd();
 
+  // Deterministic load marker. opencode invokes this factory at startup but
+  // does not reliably surface plugin console output to its log file, and its
+  // internal "loading plugin" message was dropped in opencode 1.17.x. Write a
+  // marker into the workspace telemetry dir so acceptance tests can confirm the
+  // plugin loaded without depending on opencode internals. Best-effort only.
+  try {
+    const telemetryDir = join(root, '.telemetry');
+    mkdirSync(telemetryDir, { recursive: true });
+    writeFileSync(join(telemetryDir, 'opencode-plugin.loaded'), 'flow-agents');
+  } catch (_err) {
+    // Marker is diagnostic only; never block plugin load on a write failure.
+  }
+
   // The hook scripts read the event payload from stdin; an empty stdin makes
   // the telemetry pipeline silently skip the emit (fail-open), so every spawn
   // must pass a payload (caught by live acceptance smoke 2026-06-11).