@kontourai/flow-agents 3.3.0 → 3.4.1

package/scripts/hooks/lib/codex-exit-code.js

@@ -0,0 +1,316 @@
+'use strict';
+/**
+ * codex-exit-code.js — codex-only host-banner exit-code extraction (#470).
+ *
+ * The codex PostToolUse payload carries no structured exit code (no
+ * `tool_response.exitCode`/`exit_code`, no `error`, no `stderr`). The only
+ * deterministic host signal is a fixed-format banner the codex CLI itself
+ * writes into the session rollout's `function_call_output`:
+ *
+ *   Process exited with code N
+ *
+ * This is HOST-authored prose (observed on codex-cli 0.142.5), not model
+ * narration — regex-matching exactly this banner is a deterministic host
+ * signal, distinct from scanning stdout/narration for "error"/"fail" words
+ * (which docs/spec/runtime-hook-surface.md §2.5 forbids and this module does
+ * not do).
+ *
+ * SECURITY (iteration 2 / #470 review). The banner lives in the HOST-authored
+ * PREAMBLE of a `function_call_output.output` string, BEFORE the model's own
+ * stdout, which is appended after a literal `Output:` delimiter:
+ *
+ *   Process exited with code 1
+ *   Original token count: 25
+ *   Output:
+ *   <arbitrary model-produced stdout, which may itself contain the string
+ *    "Process exited with code 0" — this is NOT a host signal and must never
+ *    be matched>
+ *
+ * Both exports are therefore PREAMBLE-ANCHORED: extraction only ever looks
+ * BEFORE the first `Output:` delimiter and takes the FIRST banner match there
+ * (the host writes it once). The post-delimiter model stdout is never
+ * scanned, at any size — this is what makes the extraction fail-safe against
+ * a command that deliberately prints a forged banner to stdout.
+ *
+ * Both exports are pure/fail-open: malformed input, a missing/unreadable file,
+ * an oversized/inaccessible rollout, or an ambiguous cross-call correlation
+ * all degrade to `null` ("no signal"), never a throw. Callers must treat
+ * `null` as "extraction unavailable", not as exit code 0.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// The two forms the `Output:` delimiter can take depending on how far the
+// caller has decoded the surrounding JSON:
+//   - a JSON.parse'd `output` string carries the delimiter as a REAL newline
+//     pair: "...\nOutput:\n...".
+//   - a raw (still JSON-escaped) slice of the rollout file — used only by the
+//     head-only fallback below, when a line is too large to fully parse —
+//     carries it literally escaped: "...\\nOutput:\\n...".
+// extractExitCodeFromBanner accepts either input flavor and anchors on
+// whichever form is present (real callers only ever hand it one flavor at a
+// time; this is not an ambiguity, just support for both call sites).
+const ANCHOR_REAL = '\nOutput:\n';
+const ANCHOR_ESCAPED = '\\nOutput:\\n';
+
+const BANNER_RE = /Process exited with code (\d+)/;
+
+function splitPreamble(text) {
+  const iReal = text.indexOf(ANCHOR_REAL);
+  const iEsc = text.indexOf(ANCHOR_ESCAPED);
+  let idx = -1;
+  if (iReal !== -1 && iEsc !== -1) idx = Math.min(iReal, iEsc);
+  else if (iReal !== -1) idx = iReal;
+  else if (iEsc !== -1) idx = iEsc;
+  // No anchor found at all: fall back to treating the whole text as the
+  // preamble (documented residual — the observed codex format always
+  // includes the `Output:` delimiter; see docs/spec + plan risk log).
+  return idx === -1 ? text : text.slice(0, idx);
+}
+
+/**
+ * extractExitCodeFromBanner(text) → integer | null
+ *
+ * Pure regex extraction — no I/O, cannot throw on well-formed string input.
+ * PREAMBLE-ANCHORED (#470 iteration 2, CRITICAL finding #1): splits `text` on
+ * the FIRST `Output:` delimiter (real or JSON-escaped form) and matches the
+ * banner ONLY in the portion before it, returning the FIRST match. The
+ * model's stdout after the delimiter is never scanned, so a command that
+ * prints a forged `Process exited with code 0` to its own stdout cannot
+ * override the real host-reported code in the preamble.
+ */
+function extractExitCodeFromBanner(text) {
+  if (typeof text !== 'string' || !text) return null;
+  const preamble = splitPreamble(text);
+  const match = BANNER_RE.exec(preamble);
+  if (!match) return null;
+  const n = Number(match[1]);
+  return Number.isInteger(n) ? n : null;
+}
+
+function normalizeCommandText(value) {
+  if (typeof value === 'string') return value.trim() || null;
+  if (Array.isArray(value)) {
+    const joined = value.map(v => String(v)).join(' ').trim();
+    return joined || null;
+  }
+  return null;
+}
+
+// Best-effort parse of a rollout `function_call`'s `arguments` field into a
+// normalized command string, used only for the command cross-check
+// correlation (Decision B #2). Any shape mismatch degrades to `null`
+// (unresolvable pairing), never a throw.
+function normalizeCallArguments(argumentsField) {
+  let parsed = argumentsField;
+  if (typeof argumentsField === 'string') {
+    try {
+      parsed = JSON.parse(argumentsField);
+    } catch {
+      return null;
+    }
+  }
+  if (!parsed || typeof parsed !== 'object') return null;
+  return normalizeCommandText(parsed.command);
+}
+
+const OUTPUT_FIELD_NEEDLE = '"output":"';
+
+/**
+ * parseCandidateLine(line, maxLineHeadBytes) → candidate | null
+ *
+ * Interprets one JSONL rollout line as either a `function_call_output` or a
+ * `function_call` response_item, HEAD-ANCHORED (#470 iteration 2, MEDIUM
+ * finding #5): a line that fits within `maxLineHeadBytes` is fully
+ * `JSON.parse`d (cheap, and correct for the real-newline anchor form); a line
+ * that exceeds the head window is NEVER fully parsed (that would mean holding
+ * arbitrarily large flooded stdout in memory and risks the preamble/banner —
+ * which lives at the line HEAD — being reasoned about incorrectly). Instead
+ * only the first `maxLineHeadBytes` raw bytes are inspected: the banner and
+ * `Output:` delimiter live within the first few hundred bytes of the `output`
+ * field regardless of how much stdout follows, so the raw head slice is
+ * sufficient for `extractExitCodeFromBanner` (escaped-anchor form).
+ */
+function parseCandidateLine(line, maxLineHeadBytes) {
+  const byteLen = Buffer.byteLength(line, 'utf8');
+  if (byteLen <= maxLineHeadBytes) {
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      return null; // malformed/partial line — skip, keep scanning
+    }
+    const payload = entry && typeof entry === 'object' ? entry.payload : null;
+    if (!payload || typeof payload !== 'object') return null;
+    const callId = typeof payload.call_id === 'string' ? payload.call_id : null;
+    if (payload.type === 'function_call_output' && typeof payload.output === 'string') {
+      return { type: 'function_call_output', callId, output: payload.output };
+    }
+    if (payload.type === 'function_call') {
+      return { type: 'function_call', callId, command: normalizeCallArguments(payload.arguments) };
+    }
+    return null;
+  }
+
+  // Line exceeds the head window: raw, head-only, best-effort extraction.
+  // `function_call` entries carry only a short command string in practice and
+  // are not expected to exceed the head window; only `function_call_output`
+  // (whose stdout can flood) is handled here.
+  const head = line.slice(0, maxLineHeadBytes);
+  if (head.indexOf('"type":"function_call_output"') === -1) return null;
+  const callIdMatch = /"call_id":"([^"]*)"/.exec(head);
+  const outputIdx = head.indexOf(OUTPUT_FIELD_NEEDLE);
+  if (outputIdx === -1) return null; // output field itself starts beyond the head window
+  const rawOutputHead = head.slice(outputIdx + OUTPUT_FIELD_NEEDLE.length);
+  return {
+    type: 'function_call_output',
+    callId: callIdMatch ? callIdMatch[1] : null,
+    output: rawOutputHead, // still JSON-escaped; extractExitCodeFromBanner handles both anchor forms
+  };
+}
+
+// Best-effort containment (#470 iteration 2, LOW finding #8): realpath the
+// transcript path and require it to be a regular file; when the codex
+// sessions root itself resolves on this host, additionally reject a realpath
+// that escapes it (defends against a symlinked transcript_path pointing
+// somewhere unexpected). Fail-open: any resolution error propagates to the
+// caller's try/catch as "unusable" (null); a non-resolvable sessions root
+// (e.g. custom CODEX_HOME, test fixtures) simply skips the containment check.
+function resolveContainedRealPath(transcriptPath) {
+  const realPath = fs.realpathSync(transcriptPath);
+  const stat = fs.statSync(realPath);
+  if (!stat.isFile()) return null;
+  try {
+    const codexHome = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+    const sessionsRoot = path.join(codexHome, 'sessions');
+    const realRoot = fs.realpathSync(sessionsRoot);
+    const rel = path.relative(realRoot, realPath);
+    if (rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) return null;
+  } catch {
+    // Sessions root doesn't exist/resolve on this host — best-effort only.
+  }
+  return realPath;
+}
+
+/**
+ * readExitCodeFromRollout(transcriptPath, options) → integer | null
+ *
+ * options:
+ *   - maxScanBytes (default 1MB): bounded backward-scan window from EOF used
+ *     to locate candidate `response_item` lines. Beyond this cap, an
+ *     unresolvable line start (and thus that candidate) is dropped — never
+ *     read further back, and never a crash.
+ *   - maxLineHeadBytes (default 64KB): per-line head window; see
+ *     `parseCandidateLine`. This is what makes extraction survive a flooded
+ *     `output` field (#470 iteration 2, MEDIUM finding #5) — the preamble
+ *     banner sits at the line HEAD, so bounding reads to the head can never
+ *     have the banner pushed out of the window by TAIL stdout volume.
+ *   - callId: correlate to a specific `function_call_output.call_id`.
+ *   - command: the claimed command (e.g. `tool_input.command`), used only for
+ *     the command cross-check correlation below.
+ *
+ * Correlation policy (Decision B, #470 iteration 2, HIGH finding #4), in
+ * priority order:
+ *   1. call_id match wins — authoritative.
+ *   2. Absent a call_id match: take the newest `function_call_output` in the
+ *      scanned window, resolve its paired `function_call` (same call_id), and
+ *      compare that call's `arguments` command (normalized) to `command`. A
+ *      resolved MATCH uses the newest output; a resolved MISMATCH DECLINES
+ *      (`null`) rather than knowingly attribute a different call's exit code.
+ *   3. If no pairing is resolvable at all (the common single-call case): fall
+ *      back to the newest `function_call_output` banner.
+ *
+ * Any failure (missing/unreadable/non-regular file, containment violation,
+ * malformed JSON lines, no candidate found) yields `null` — never throws.
+ */
+function readExitCodeFromRollout(transcriptPath, options) {
+  const opts = options || {};
+  const maxScanBytes = Number.isInteger(opts.maxScanBytes) && opts.maxScanBytes > 0
+    ? opts.maxScanBytes
+    : 1024 * 1024;
+  const maxLineHeadBytes = Number.isInteger(opts.maxLineHeadBytes) && opts.maxLineHeadBytes > 0
+    ? opts.maxLineHeadBytes
+    : 64 * 1024;
+  const callId = typeof opts.callId === 'string' && opts.callId ? opts.callId : null;
+  const command = normalizeCommandText(opts.command);
+
+  if (typeof transcriptPath !== 'string' || !transcriptPath) return null;
+
+  let text;
+  let truncated;
+  try {
+    const realPath = resolveContainedRealPath(transcriptPath);
+    if (realPath === null) return null; // containment violation
+
+    const stat = fs.statSync(realPath);
+    const fd = fs.openSync(realPath, 'r');
+    try {
+      const readLen = Math.min(maxScanBytes, stat.size);
+      const start = stat.size - readLen;
+      const buf = Buffer.alloc(readLen);
+      fs.readSync(fd, buf, 0, readLen, start);
+      text = buf.toString('utf8');
+      // A read starting after byte 0 means the file is larger than the scan
+      // window and the first captured line may be a truncated fragment of a
+      // longer line that started before `start` — only then is it dropped.
+      truncated = start > 0;
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    return null;
+  }
+
+  let lines;
+  try {
+    lines = text.split('\n');
+  } catch {
+    return null;
+  }
+  if (truncated && lines.length > 1) lines.shift();
+
+  let matchedByCallId = null;
+  let newestOutputEntry = null;
+  let pairedCommand = null;
+
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i].trim();
+    if (!line) continue;
+    const candidate = parseCandidateLine(line, maxLineHeadBytes);
+    if (!candidate) continue; // malformed/partial/unrecognized line — skip, keep scanning
+
+    if (candidate.type === 'function_call_output') {
+      if (newestOutputEntry === null) newestOutputEntry = candidate; // first seen scanning backward = newest
+      if (callId && candidate.callId === callId) {
+        matchedByCallId = candidate;
+        break; // call_id match is authoritative — stop scanning
+      }
+    } else if (candidate.type === 'function_call') {
+      if (newestOutputEntry && pairedCommand === null && candidate.callId === newestOutputEntry.callId) {
+        pairedCommand = candidate.command;
+      }
+    }
+  }
+
+  let chosenOutput = null;
+  if (matchedByCallId) {
+    chosenOutput = matchedByCallId.output;
+  } else if (newestOutputEntry) {
+    if (pairedCommand !== null && command) {
+      if (pairedCommand === command) {
+        chosenOutput = newestOutputEntry.output;
+      } else {
+        return null; // positive command mismatch — decline rather than mis-attribute
+      }
+    } else {
+      chosenOutput = newestOutputEntry.output; // single-call fallback — no pairing resolvable
+    }
+  }
+
+  if (chosenOutput === null) return null;
+  return extractExitCodeFromBanner(chosenOutput);
+}
+
+module.exports = { extractExitCodeFromBanner, readExitCodeFromRollout };

package/scripts/hooks/lib/kit-catalog.js

@@ -0,0 +1,235 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const KIT_ID_RE = /^[a-z][a-z0-9-]*$/;
+const WORKFLOW_TRIGGER_IDENTIFIER_RE = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
+const MAX_STEERING_VALUE_LENGTH = 240;
+
+function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+function containedPath(root, rel) {
+  if (typeof rel !== 'string' || path.isAbsolute(rel)) return null;
+  const resolved = path.resolve(root, rel);
+  const absRoot = path.resolve(root);
+  if (resolved === absRoot || resolved.startsWith(`${absRoot}${path.sep}`)) return resolved;
+  return null;
+}
+
+function loadKitManifest(kitRoot, sourceKind, warnings) {
+  const manifestPath = path.join(kitRoot, 'kit.json');
+  try {
+    if (!fs.existsSync(manifestPath)) return null;
+    const manifest = readJson(manifestPath);
+    const kitId = typeof manifest.id === 'string' ? manifest.id : '';
+    if (!KIT_ID_RE.test(kitId)) {
+      warnings.push(`${manifestPath}: kit id must be a kebab-case id (^[a-z][a-z0-9-]*$); skipping kit`);
+      return null;
+    }
+    return { kit_id: kitId, source_kind: sourceKind, manifest };
+  } catch (error) {
+    warnings.push(`${manifestPath}: ${String(error && error.message ? error.message : error)}`);
+    return null;
+  }
+}
+
+function readKitManifests(root) {
+  const warnings = [];
+  const kits = [];
+  const catalogPath = path.join(root, 'kits', 'catalog.json');
+  if (fs.existsSync(catalogPath)) {
+    try {
+      const catalog = readJson(catalogPath);
+      if (Array.isArray(catalog.kits)) {
+        for (const entry of catalog.kits) {
+          const rel = entry && typeof entry === 'object' ? entry.path : undefined;
+          const kitRoot = containedPath(root, rel);
+          if (!kitRoot || !fs.existsSync(kitRoot)) continue;
+          const loaded = loadKitManifest(kitRoot, 'builtin', warnings);
+          if (loaded) kits.push(loaded);
+        }
+      }
+    } catch (error) {
+      warnings.push(String(error && error.message ? error.message : error));
+    }
+  }
+
+  const registryPath = path.join(root, 'kits', 'local', 'installed-kits.json');
+  if (fs.existsSync(registryPath)) {
+    try {
+      const registry = readJson(registryPath);
+      if (Array.isArray(registry.kits)) {
+        for (const entry of registry.kits) {
+          const id = entry && typeof entry === 'object' ? entry.id : undefined;
+          if (typeof id !== 'string') continue;
+          const kitRoot = path.join(root, 'kits', 'local', 'repositories', id);
+          if (!fs.existsSync(kitRoot)) continue;
+          const loaded = loadKitManifest(kitRoot, 'local', warnings);
+          if (loaded) kits.push(loaded);
+        }
+      }
+    } catch (error) {
+      warnings.push(String(error && error.message ? error.message : error));
+    }
+  }
+  return { kits, warnings };
+}
+
+function isWorkflowTriggerIdentifier(value) {
+  return typeof value === 'string' && WORKFLOW_TRIGGER_IDENTIFIER_RE.test(value);
+}
+
+function optionalWorkflowTriggerIdentifier(value) {
+  return value === undefined || isWorkflowTriggerIdentifier(value);
+}
+
+function optionalWorkflowTriggerIdentifierList(value) {
+  return value === undefined ||
+    (Array.isArray(value) && value.length > 0 && value.every(isWorkflowTriggerIdentifier));
+}
+
+function optionalConditionalSkills(value) {
+  return value === undefined ||
+    (Array.isArray(value) && value.every(item =>
+      item && typeof item === 'object' &&
+      isWorkflowTriggerIdentifier(item.when) &&
+      isWorkflowTriggerIdentifier(item.skill)
+    ));
+}
+
+function renderKitSteering(trigger) {
+  const kitId = isWorkflowTriggerIdentifier(trigger.kit_id) ? trigger.kit_id : '';
+  const category = isWorkflowTriggerIdentifier(trigger.when) ? trigger.when : 'matching';
+  const targetFlowId = isWorkflowTriggerIdentifier(trigger.target_flow_id) ? trigger.target_flow_id : '';
+  const defaultSkill = isWorkflowTriggerIdentifier(trigger.default_skill) ? trigger.default_skill : '';
+  const conditionalSkills = Array.isArray(trigger.conditional_skills) ? trigger.conditional_skills
+    .map(item => ({
+      when: isWorkflowTriggerIdentifier(item && item.when) ? item.when : '',
+      skill: isWorkflowTriggerIdentifier(item && item.skill) ? item.skill : '',
+    }))
+    .filter(item => item.when && item.skill) : [];
+  const requiredSequence = Array.isArray(trigger.required_sequence)
+    ? trigger.required_sequence.filter(isWorkflowTriggerIdentifier)
+    : [];
+  const postVerifyTargets = Array.isArray(trigger.post_verify_targets)
+    ? trigger.post_verify_targets.filter(isWorkflowTriggerIdentifier)
+    : [];
+
+  const lines = [
+    `KIT WORKFLOW ROUTE: this user prompt matches ${category}.`,
+  ];
+  if (kitId && targetFlowId) {
+    lines.push(`Before source edits or implementation commands, use the \`${kitId}\` kit's \`${targetFlowId}\` workflow.`);
+  } else if (kitId) {
+    lines.push(`Before source edits or implementation commands, use the \`${kitId}\` kit workflow.`);
+  } else {
+    lines.push('Before source edits or implementation commands, use the matching kit workflow.');
+  }
+  if (conditionalSkills.length || defaultSkill) {
+    const conditionalText = conditionalSkills
+      .map(item => `If ${item.when}, activate \`${item.skill}\``)
+      .join('; ');
+    if (conditionalText && defaultSkill) lines.push(`${conditionalText}; otherwise activate \`${defaultSkill}\`.`);
+    else if (conditionalText) lines.push(`${conditionalText}.`);
+    else lines.push(`Activate \`${defaultSkill}\`.`);
+  }
+  if (targetFlowId) {
+    lines.push(`Keep the session on \`${targetFlowId}\` and use \`npm run workflow:sidecar -- ensure-session --flow-id ${targetFlowId} ...\` when the repo provides the sidecar writer.`);
+  }
+  if (requiredSequence.length) {
+    lines.push(`Do not bypass ${requiredSequence.join(' -> ')} for matching work.`);
+  }
+  if (postVerifyTargets.length) {
+    lines.push(`After local verification, continue to ${postVerifyTargets.join(' and ')}; do not treat local verification as terminal delivery.`);
+  }
+  return lines.join(' ');
+}
+
+function workflowTriggerValidationErrors(manifest, manifestPath) {
+  const errors = [];
+  const raw = manifest.workflow_triggers;
+  if (raw === undefined) return errors;
+  if (!Array.isArray(raw)) {
+    errors.push(`${manifestPath}: .workflow_triggers must be a list`);
+    return errors;
+  }
+  const seenIds = new Set();
+  raw.forEach((trigger, index) => {
+    if (!trigger || typeof trigger !== 'object') {
+      errors.push(`${manifestPath}: workflow_triggers[${index}] must be an object`);
+      return;
+    }
+    if (!isWorkflowTriggerIdentifier(trigger.id)) {
+      errors.push(`${manifestPath}: workflow_triggers[${index}].id must match ^[a-z0-9]+(?:[.-][a-z0-9]+)*$`);
+      return;
+    }
+    if (seenIds.has(trigger.id)) errors.push(`${manifestPath}: workflow_triggers[${index}].id duplicates '${trigger.id}'`);
+    seenIds.add(trigger.id);
+    if (!isWorkflowTriggerIdentifier(trigger.when)) {
+      errors.push(`${manifestPath}: workflow_triggers[${index}].when must match ^[a-z0-9]+(?:[.-][a-z0-9]+)*$`);
+      return;
+    }
+    if (trigger.hint !== undefined) {
+      errors.push(`${manifestPath}: workflow_triggers[${index}].hint is retired; use structured steering fields`);
+      return;
+    }
+    if (trigger.display_name !== undefined) {
+      errors.push(`${manifestPath}: workflow_triggers[${index}].display_name is not supported in workflow_triggers; use catalog/listing metadata for human-readable names`);
+      return;
+    }
+    if (!optionalWorkflowTriggerIdentifier(trigger.target_flow_id)) {
+      errors.push(`${manifestPath}: workflow_triggers[${index}].target_flow_id must match ^[a-z0-9]+(?:[.-][a-z0-9]+)*$ when present`);
+      return;
+    }
+    if (!optionalWorkflowTriggerIdentifier(trigger.default_skill)) {
+      errors.push(`${manifestPath}: workflow_triggers[${index}].default_skill must match ^[a-z0-9]+(?:[.-][a-z0-9]+)*$ when present`);
+      return;
+    }
+    if (!optionalConditionalSkills(trigger.conditional_skills)) {
+      errors.push(`${manifestPath}: workflow_triggers[${index}].conditional_skills must be a list of { when, skill } identifiers matching ^[a-z0-9]+(?:[.-][a-z0-9]+)*$ when present`);
+      return;
+    }
+    if (!optionalWorkflowTriggerIdentifierList(trigger.required_sequence)) {
+      errors.push(`${manifestPath}: workflow_triggers[${index}].required_sequence must be a non-empty identifier list matching ^[a-z0-9]+(?:[.-][a-z0-9]+)*$ when present`);
+      return;
+    }
+    if (!optionalWorkflowTriggerIdentifierList(trigger.post_verify_targets)) {
+      errors.push(`${manifestPath}: workflow_triggers[${index}].post_verify_targets must be a non-empty identifier list matching ^[a-z0-9]+(?:[.-][a-z0-9]+)*$ when present`);
+    }
+  });
+  return errors;
+}
+
+function workflowTriggersFor(root, when) {
+  const result = [];
+  const inventory = readKitManifests(root);
+  for (const kit of inventory.kits) {
+    const triggers = kit.manifest.workflow_triggers;
+    if (!Array.isArray(triggers)) continue;
+    const manifestPath = path.join(root, kit.source_kind === 'local' ? 'kits/local/repositories' : 'kits', kit.kit_id, 'kit.json');
+    const parseErrors = workflowTriggerValidationErrors(kit.manifest, manifestPath);
+    if (parseErrors.length) {
+      const warning = `${kit.kit_id}: invalid workflow_triggers metadata; skipping workflow_triggers: ${parseErrors.join('; ')}`;
+      inventory.warnings.push(warning);
+      process.stderr.write(`[flow-agents] ${warning}\n`);
+      continue;
+    }
+    for (const trigger of triggers) {
+      if (trigger.when !== when) continue;
+      const steering = renderKitSteering({ ...trigger, kit_id: kit.kit_id });
+      if (!steering) continue;
+      result.push({ kit_id: kit.kit_id, id: trigger.id, when, steering });
+    }
+  }
+  return result;
+}
+
+module.exports = {
+  MAX_STEERING_VALUE_LENGTH,
+  renderKitSteering,
+  readKitManifests,
+  workflowTriggersFor,
+};

package/scripts/hooks/lib/liveness-write.js

@@ -19,6 +19,32 @@
 
 const fs = require('fs');
 const path = require('path');
+const { spawn } = require('child_process');
+
+/**
+ * OPTIONAL console liveness relay (#295, ADR 0021 §4/§7). Best-effort, FULLY detached mirror of a
+ * liveness event to the hosted Console via `scripts/liveness/relay.sh`. Local-first is sacred: this
+ * runs AFTER the durable local append and can never block, throw, or affect it — gated on
+ * `FLOW_AGENTS_CONSOLE_LIVENESS_RELAY`, the whole thing wrapped so any failure (missing script,
+ * spawn error) is swallowed. No flag ⇒ a single cheap env read and return (true no-op).
+ *
+ * @param {object} evt  The liveness event just written locally.
+ * @returns {void}
+ */
+function relayLivenessEvent(evt) {
+  try {
+    const flag = String(process.env.FLOW_AGENTS_CONSOLE_LIVENESS_RELAY || '').toLowerCase();
+    if (flag !== '1' && flag !== 'true' && flag !== 'yes' && flag !== 'on') return;
+    // scripts/hooks/lib/ -> scripts/liveness/relay.sh (same relative layout in dist/* bundles).
+    const relay = path.join(__dirname, '..', '..', 'liveness', 'relay.sh');
+    if (!fs.existsSync(relay)) return;
+    const child = spawn('bash', [relay, JSON.stringify(evt)], { detached: true, stdio: 'ignore' });
+    child.on('error', () => {}); // never surface a spawn failure
+    child.unref(); // fully detach — the parent never waits on the relay
+  } catch {
+    // Best-effort only: the durable local write already succeeded above.
+  }
+}
 
 /**
  * Resolve the path to the shared liveness event stream for a given artifact root.
@@ -40,7 +66,8 @@ function livenessStreamFile(root) {
 function appendLivenessEvent(root, evt) {
   const file = livenessStreamFile(root);
   fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.appendFileSync(file, `${JSON.stringify(evt)}\n`);
+  fs.appendFileSync(file, `${JSON.stringify(evt)}\n`); // local-first: the durable write happens first
+  relayLivenessEvent(evt); // then optionally mirror to the Console — best-effort, detached, off by default
 }
 
 module.exports = { livenessStreamFile, appendLivenessEvent };