@kontourai/flow-agents 4.1.0 → 4.2.1

package/dist/base/evals/integration/test_liveness_heartbeat.sh

@@ -704,6 +704,72 @@ else
   _fail "maybeEmitHeartbeat did not neutralize an orphan heartbeat as expected: $J1_OUT"
 fi
 
+# ─── K. Richer "real liveness": activity descriptor on the emitted heartbeat ────────────────
+echo "--- K. Activity enrichment (tool name on the pulse) ---"
+
+# call_heartbeat_activity <scratch_root> <env_json> <now_iso> <activity_json>
+# Like call_heartbeat, but passes an `activity` descriptor through opts so we can prove the emitted
+# heartbeat carries a sanitized activity field (the "what is this agent doing right now" signal).
+call_heartbeat_activity() {
+  local root="$1" env_json="$2" now="$3" activity_json="$4"
+  MODULE_ARG="$HEARTBEAT_MODULE" ROOT_ARG="$root" ENV_JSON_ARG="$env_json" NOW_ARG="$now" ACTIVITY_ARG="$activity_json" \
+    node - <<'NODE'
+const { maybeEmitHeartbeat } = require(process.env.MODULE_ARG);
+const env = JSON.parse(process.env.ENV_JSON_ARG);
+const opts = { cwd: process.env.ROOT_ARG, env, now: process.env.NOW_ARG, activity: JSON.parse(process.env.ACTIVITY_ARG) };
+process.stdout.write(JSON.stringify(maybeEmitHeartbeat(opts)));
+NODE
+}
+
+# K1: a clean tool name rides through onto the emitted heartbeat as activity.tool.
+K1_ROOT="$(new_scratch)"
+seed_claim "$K1_ROOT" "k1-subj" "agent-k1" "2026-06-25T12:00:00.000Z" 1800
+K1_RESULT="$(call_heartbeat_activity "$K1_ROOT" '{"FLOW_AGENTS_ACTOR":"agent-k1"}' "2026-06-25T12:01:00.000Z" '{"tool":"Bash"}')"
+K1_LINE="$(tail -n 1 "$(stream_file "$K1_ROOT")" 2>/dev/null)"
+if [[ "$K1_RESULT" == '{"emitted":true}' ]] \
+  && grep -q '"type":"heartbeat"' <<<"$K1_LINE" \
+  && grep -q '"activity":{"tool":"Bash"}' <<<"$K1_LINE"; then
+  _pass "the emitted heartbeat carries a sanitized activity.tool (what the agent is doing right now)"
+else
+  _fail "the heartbeat did not carry the expected activity.tool: result=$K1_RESULT line=$K1_LINE"
+fi
+
+# K2: an MCP-style tool name (double underscores + hyphens) survives sanitizeSegment intact.
+K2_ROOT="$(new_scratch)"
+seed_claim "$K2_ROOT" "k2-subj" "agent-k2" "2026-06-25T12:00:00.000Z" 1800
+call_heartbeat_activity "$K2_ROOT" '{"FLOW_AGENTS_ACTOR":"agent-k2"}' "2026-06-25T12:01:00.000Z" '{"tool":"mcp__claude-in-chrome__navigate"}' >/dev/null
+K2_LINE="$(tail -n 1 "$(stream_file "$K2_ROOT")" 2>/dev/null)"
+if grep -q '"activity":{"tool":"mcp__claude-in-chrome__navigate"}' <<<"$K2_LINE"; then
+  _pass "an MCP tool name (double underscores + hyphens) rides through the allowlist sanitizer intact"
+else
+  _fail "the MCP tool name was not preserved on the activity descriptor: line=$K2_LINE"
+fi
+
+# K3: a hostile tool name (control bytes / injection payload) is stripped to the allowlist charset —
+# never emitted raw into the append-only stream.
+K3_ROOT="$(new_scratch)"
+seed_claim "$K3_ROOT" "k3-subj" "agent-k3" "2026-06-25T12:00:00.000Z" 1800
+call_heartbeat_activity "$K3_ROOT" '{"FLOW_AGENTS_ACTOR":"agent-k3"}' "2026-06-25T12:01:00.000Z" '{"tool":"Ba\"sh\n{\"x\":1}"}' >/dev/null
+K3_LINE="$(tail -n 1 "$(stream_file "$K3_ROOT")" 2>/dev/null)"
+# The allowlist keeps only [A-Za-z0-9_.-], so the payload collapses to "Bashx1".
+if grep -q '"activity":{"tool":"Bashx1"}' <<<"$K3_LINE" && ! grep -q 'Ba"sh' <<<"$K3_LINE"; then
+  _pass "a hostile tool name is stripped to the allowlist charset, never emitted raw (injection discipline)"
+else
+  _fail "the hostile tool name was not sanitized as expected: line=$K3_LINE"
+fi
+
+# K4: no activity supplied → the heartbeat is a plain aliveness pulse with NO activity key (the field
+# is omitted, not emitted empty).
+K4_ROOT="$(new_scratch)"
+seed_claim "$K4_ROOT" "k4-subj" "agent-k4" "2026-06-25T12:00:00.000Z" 1800
+call_heartbeat "$K4_ROOT" '{"FLOW_AGENTS_ACTOR":"agent-k4"}' "2026-06-25T12:01:00.000Z" >/dev/null
+K4_LINE="$(tail -n 1 "$(stream_file "$K4_ROOT")" 2>/dev/null)"
+if grep -q '"type":"heartbeat"' <<<"$K4_LINE" && ! grep -q '"activity"' <<<"$K4_LINE"; then
+  _pass "with no activity supplied the heartbeat omits the activity field entirely (no empty-object noise)"
+else
+  _fail "the no-activity heartbeat unexpectedly carried an activity field: line=$K4_LINE"
+fi
+
 echo ""
 if [[ "$errors" -eq 0 ]]; then
   echo "Liveness heartbeat integration passed."

package/dist/base/install.sh

@@ -72,7 +72,7 @@ if [[ ! -e "$DEST/AGENTS.md" && ! -L "$DEST/AGENTS.md" ]]; then
   rm -f "$instruction_tmp"
 fi
 if command -v node >/dev/null 2>&1; then
-  node "$DEST/scripts/install-merge.js" --stamp-only --version "4.1.0" --install-record "$DEST/.flow-agents/install.json" --runtime "base" || true
+  node "$DEST/scripts/install-merge.js" --stamp-only --version "4.2.1" --install-record "$DEST/.flow-agents/install.json" --runtime "base" || true
 fi
 if [[ ${#CONSOLE_CONFIG_ARGS[@]} -gt 0 || -n "${FLOW_AGENTS_TELEMETRY_SINK:-}" || -n "${FLOW_AGENTS_TELEMETRY_SINKS:-}" || -n "${FLOW_AGENTS_CONSOLE_URL:-}" || -n "${CONSOLE_TELEMETRY_URL:-}" || -n "${CONSOLE_URL:-}" || -n "${FLOW_AGENTS_CONSOLE_TOKEN_FILE:-}" || -n "${CONSOLE_TELEMETRY_TOKEN_FILE:-}" ]]; then
   bash "$DEST/scripts/telemetry/install-console-config.sh" "$DEST/scripts/telemetry/telemetry.conf" "${CONSOLE_CONFIG_ARGS[@]}"

package/dist/base/scripts/hooks/claude-telemetry-hook.js

@@ -105,9 +105,15 @@ async function main() {
   let conflict;
   if (canonical === 'postToolUse') {
     try {
+      // Richer "real liveness": name the tool this pulse rode in on so the heartbeat says WHAT the
+      // agent is doing, not just that it is alive. Claude Code's PostToolUse payload carries the
+      // tool name as `tool_name` (fall back to `toolName`); the heartbeat sanitizes it, so a
+      // missing/odd value degrades to a plain aliveness pulse rather than an error.
+      const toolName = payload.tool_name || payload.toolName;
       const heartbeatResult = require('./lib/liveness-heartbeat').maybeEmitHeartbeat({
         cwd: process.cwd(),
         env: process.env,
+        activity: toolName ? { tool: toolName } : undefined,
       });
       conflict = heartbeatResult && heartbeatResult.conflict;
     } catch (err) {

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

@@ -113,10 +113,13 @@ function normalizeCallArguments(argumentsField) {
     }
   }
   if (!parsed || typeof parsed !== 'object') return null;
-  return normalizeCommandText(parsed.command);
+  // Codex records exec_command arguments under `cmd`; older shell fixtures
+  // and some adapters use `command`.
+  return normalizeCommandText(parsed.cmd) || normalizeCommandText(parsed.command);
 }
 
 const OUTPUT_FIELD_NEEDLE = '"output":"';
+const COMMAND_FUNCTION_NAMES = new Set(['exec_command', 'shell']);
 
 /**
  * parseCandidateLine(line, maxLineHeadBytes) → candidate | null
@@ -149,7 +152,15 @@ function parseCandidateLine(line, maxLineHeadBytes) {
       return { type: 'function_call_output', callId, output: payload.output };
     }
     if (payload.type === 'function_call') {
-      return { type: 'function_call', callId, command: normalizeCallArguments(payload.arguments) };
+      const name = typeof payload.name === 'string' && payload.name.trim() ? payload.name.trim() : null;
+      const command = normalizeCallArguments(payload.arguments);
+      const commandCapable = name === null || COMMAND_FUNCTION_NAMES.has(name) || command !== null;
+      return {
+        type: 'function_call',
+        callId,
+        commandCapable,
+        command,
+      };
     }
     return null;
   }
@@ -214,13 +225,12 @@ function resolveContainedRealPath(transcriptPath) {
  * 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.
+ *   2. Absent a call_id match: pair outputs with calls by rollout call_id and
+ *      select the only pair whose normalized arguments match `command`. Zero
+ *      matches or multiple matches DECLINE (`null`) rather than attribute a
+ *      neighboring or repeated command's exit code.
+ *   3. If no pairing is resolvable at all and the rollout contains exactly one
+ *      output with no function call, use that genuinely unpaired legacy output.
  *
  * Any failure (missing/unreadable/non-regular file, containment violation,
  * malformed JSON lines, no candidate found) yields `null` — never throws.
@@ -271,41 +281,83 @@ function readExitCodeFromRollout(transcriptPath, options) {
   }
   if (truncated && lines.length > 1) lines.shift();
 
-  let matchedByCallId = null;
+  const outputsByRequestedCallId = [];
   let newestOutputEntry = null;
-  let pairedCommand = null;
+  const outputEntries = [];
+  const commandByCallId = new Map();
+  const seenFunctionCallIds = new Set();
+  const ambiguousCallIds = new Set();
+  let functionCallCount = 0;
+  let sawUnclassifiableLine = false;
+  let sawUnresolvableFunctionCall = false;
 
   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) {
+      if (Buffer.byteLength(line, 'utf8') > maxLineHeadBytes) {
+        sawUnclassifiableLine = true;
+      } else {
+        try {
+          JSON.parse(line); // valid non-candidate events do not poison correlation
+        } catch {
+          sawUnclassifiableLine = true;
+        }
+      }
+      continue; // malformed/partial/unrecognized line — skip, keep scanning
+    }
 
     if (candidate.type === 'function_call_output') {
+      outputEntries.push(candidate); // scan order is newest to oldest
       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
+        outputsByRequestedCallId.push(candidate);
       }
     } else if (candidate.type === 'function_call') {
-      if (newestOutputEntry && pairedCommand === null && candidate.callId === newestOutputEntry.callId) {
-        pairedCommand = candidate.command;
+      functionCallCount += 1;
+      if (candidate.callId) {
+        if (seenFunctionCallIds.has(candidate.callId)) ambiguousCallIds.add(candidate.callId);
+        else seenFunctionCallIds.add(candidate.callId);
+      }
+      if (candidate.commandCapable && candidate.callId && candidate.command !== null) {
+        if (!commandByCallId.has(candidate.callId)) commandByCallId.set(candidate.callId, candidate.command);
+      } else if (candidate.commandCapable) {
+        sawUnresolvableFunctionCall = true;
       }
     }
   }
 
   let chosenOutput = null;
-  if (matchedByCallId) {
-    chosenOutput = matchedByCallId.output;
+  if ((callId || command) && sawUnclassifiableLine) return null;
+  if (callId) {
+    if (outputsByRequestedCallId.length === 1 && !ambiguousCallIds.has(callId)) {
+      chosenOutput = outputsByRequestedCallId[0].output;
+    } else {
+      return null; // explicit call ID is unresolved, reused, or has duplicate outputs
+    }
   } else if (newestOutputEntry) {
-    if (pairedCommand !== null && command) {
-      if (pairedCommand === command) {
-        chosenOutput = newestOutputEntry.output;
+    if (command) {
+      if (sawUnresolvableFunctionCall) return null;
+      const matchingCallIds = [...commandByCallId.entries()]
+        .filter(([, candidateCommand]) => candidateCommand === command)
+        .map(([candidateCallId]) => candidateCallId);
+      const matches = outputEntries.filter((entry) => commandByCallId.get(entry.callId) === command);
+      if (matchingCallIds.length === 1
+        && !ambiguousCallIds.has(matchingCallIds[0])
+        && matches.length === 1) {
+        chosenOutput = matches[0].output;
+      } else if (matchingCallIds.length > 0 || matches.length > 0 || commandByCallId.size > 0) {
+        return null; // no unique command correlation
+      } else if (!truncated && outputEntries.length === 1 && functionCallCount === 0) {
+        chosenOutput = newestOutputEntry.output; // genuinely unpaired legacy fallback
       } else {
-        return null; // positive command mismatch — decline rather than mis-attribute
+        return null; // multi-call or partially paired tail
       }
+    } else if (!truncated && outputEntries.length === 1 && functionCallCount === 0) {
+      chosenOutput = newestOutputEntry.output; // genuinely unpaired legacy fallback
     } else {
-      chosenOutput = newestOutputEntry.output; // single-call fallback — no pairing resolvable
+      return null; // no correlation signal for a paired or multi-call tail
     }
   }
 

package/dist/base/scripts/hooks/lib/liveness-heartbeat.js

@@ -164,6 +164,39 @@ function readActiveSlug(root, actorKey) {
   return sanitized === 'unknown' ? '' : sanitized;
 }
 
+/**
+ * Sanitize an optional caller-supplied `activity` descriptor into a clean, bounded shape suitable
+ * for embedding in the emitted heartbeat event (issue: richer "real liveness" signals). The point
+ * is to make each pulse say WHAT the agent is doing right now — the tool it just ran — not merely
+ * that it is alive. Every field flows both into the local append-only JSONL and (via relay.sh) into
+ * the hosted Console record, so each value is passed through the same allowlist+64-cap
+ * `sanitizeSegment` the write side already applies to actors/slugs: a hostile or oversized tool
+ * name (a custom MCP tool string, a hand-edited hook payload) can never inject control bytes or
+ * unbounded text downstream. Returns `undefined` when there is no usable activity, so the caller
+ * omits the field entirely rather than emitting `activity: {}` noise.
+ *
+ * @param {{tool?: string}|undefined} activity
+ * @returns {{tool: string}|undefined}
+ */
+function sanitizeActivity(activity) {
+  // Fully self-contained fail-safe: this runs on the hot path just BEFORE the durable local append
+  // in maybeEmitHeartbeat, and local-first is sacred (ADR 0012 §5) — enriching the pulse must never
+  // be able to prevent the write. `String(activity.tool)` could in principle throw for an exotic
+  // caller value (a throwing toString/valueOf); swallow it here and degrade to a plain aliveness
+  // pulse rather than letting the durable write be skipped.
+  try {
+    if (!activity || typeof activity !== 'object') return undefined;
+    const out = {};
+    if (activity.tool != null && String(activity.tool).trim()) {
+      const tool = sanitizeSegment(activity.tool);
+      if (tool && tool !== 'unknown') out.tool = tool;
+    }
+    return Object.keys(out).length ? out : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Filter a list of parsed liveness events down to the ones matching a given
  * (subjectId, actor) pair. Shared by the bounded tail read and the full-read
@@ -270,7 +303,11 @@ function attachConflictField(result, conflict) {
  *     wall-clock timer), so it fires once per genuinely new conflicting event, independent of
  *     whether our own heartbeat emits or throttles this call.
  *
- * @param {{cwd?: string, env?: NodeJS.ProcessEnv, now?: Date|string}} [opts]
+ * @param {{cwd?: string, env?: NodeJS.ProcessEnv, now?: Date|string, activity?: {tool?: string}}} [opts]
+ *   `activity` is an optional descriptor of what the agent is doing right now (e.g. the tool this
+ *   postToolUse pulse rode in on); when present + usable it is sanitized and embedded in the emitted
+ *   heartbeat so the fleet view shows WHAT, not just aliveness. Purely additive — never affects the
+ *   throttle/emit/conflict decisions.
  * @returns {{emitted: boolean, reason?: string, conflict?: {actor: string, lastAt: string, ttlSeconds: number}}}
  */
 function maybeEmitHeartbeat(opts = {}) {
@@ -383,12 +420,16 @@ function maybeEmitHeartbeat(opts = {}) {
     const conflict = computeConflict(holderEvents, slug, actor, nowMs, last.at);
 
     const nowIso = new Date(nowMs).toISOString();
+    const activity = sanitizeActivity(opts.activity);
     appendLivenessEvent(root, {
       type: 'heartbeat',
       subjectId: slug,
       actor,
       at: nowIso,
       source: 'tool-activity',
+      // Richer "real liveness": name the tool this pulse rode in on, so the fleet view shows WHAT
+      // each agent is doing, not just that it is alive. Omitted entirely when no usable activity.
+      ...(activity ? { activity } : {}),
     });
     return attachConflictField({ emitted: true }, conflict);
   } catch (err) {

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

@@ -18,27 +18,127 @@
  */
 
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
 const { spawn } = require('child_process');
 
+const TRUTHY = new Set(['1', 'true', 'yes', 'on']);
+const FALSY = new Set(['0', 'false', 'no', 'off']);
+// Cheap per-process memo keyed by the exact env inputs, so a throttled hot path does at most one
+// conf read per (env flag, conf path) signature. Keyed inputs make unit tests that vary
+// TELEMETRY_CONFIG_FILE independent.
+const relayEnabledCache = new Map();
+
+/**
+ * The console-conf resolution chain, mirroring scripts/telemetry/lib/config.sh's slot order:
+ *   1. TELEMETRY_CONFIG_FILE (env) if set + readable
+ *   2. per-workspace override: <workspace-root>/.kontourai/telemetry-console.conf
+ *   3. user-global durable override: <bundle-root>/telemetry-console.conf
+ *   4. the shipped default: scripts/telemetry/telemetry.conf (relative to this file)
+ * Slot 4's path is <this file>/../../telemetry/telemetry.conf; the workspace root for slot 2 is
+ * three levels up from scripts/hooks/lib. This resolver is only the SPAWN pre-gate — it is
+ * intentionally lenient (no mode-600 trust gate). relay.sh re-sources config.sh, which applies the
+ * trust gate and is the authoritative decision for both enablement and the POST endpoint, so a
+ * lenient "enabled" here at worst spawns a relay.sh that then trust-gates itself to a no-op.
+ *
+ * ACCEPTED, BY DESIGN (security review LOW, A04): because this pre-gate does NOT re-apply
+ * config.sh's mode-600/owner gate, it can read an explicit key from an UNtrusted default-path conf
+ * (a mode-644 .kontourai/telemetry-console.conf a local tool dropped) that config.sh would skip.
+ * This is fail-toward-no-op, never fail-toward-exfil: the only divergence is (a) we spawn a
+ * relay.sh that config.sh then no-ops (harmless), or (b) an untrusted `=0` here suppresses a spawn
+ * that a trusted conf would have enabled (a missed pulse — availability only, requiring local FS
+ * write access). The pre-gate deliberately does not guarantee relay AVAILABILITY — only that we
+ * avoid spawning when nothing plausibly enables it. It NEVER weakens the exfil defense, which lives
+ * entirely in relay.sh's authoritative, trust-gated re-resolution.
+ * @returns {string|null}  first readable conf path, or null
+ */
+function resolveConsoleConfPath(env) {
+  const candidates = [
+    env.TELEMETRY_CONFIG_FILE,
+    path.join(__dirname, '..', '..', '..', '.kontourai', 'telemetry-console.conf'),
+    path.join(os.homedir(), '.flow-agents', 'telemetry-console.conf'),
+    path.join(__dirname, '..', '..', 'telemetry', 'telemetry.conf'),
+  ];
+  for (const c of candidates) {
+    try {
+      if (c && fs.existsSync(c) && fs.statSync(c).isFile()) return c;
+    } catch {
+      /* keep scanning */
+    }
+  }
+  return null;
+}
+
+/**
+ * Conf-driven liveness relay enablement (#567 — parity with the economics relay #469, so an
+ * operator enables via `console_liveness_relay=1` in the console conf, NOT an env var/.profile).
+ * Precedence mirrors config.sh's economics rule EXACTLY (config.sh:182-204): an explicit
+ * `console_liveness_relay` conf key wins over the env var; absent a key, a pre-set env var is
+ * honored; absent both, default ON once a console sink is configured (any console_*url key present)
+ * — opt-out, not silent-off. Best-effort and cheap: any FS/parse failure falls back to the env-only
+ * decision; never throws. This is the spawn pre-gate; relay.sh+config.sh is authoritative.
+ */
+function resolveLivenessRelayEnabled(env) {
+  const envFlag = String(env.FLOW_AGENTS_CONSOLE_LIVENESS_RELAY || '').toLowerCase();
+  const envDecision = TRUTHY.has(envFlag) ? true : FALSY.has(envFlag) ? false : null;
+  const cacheKey = `${envFlag}|${env.TELEMETRY_CONFIG_FILE || ''}`;
+  if (relayEnabledCache.has(cacheKey)) return relayEnabledCache.get(cacheKey);
+  let enabled;
+  try {
+    let explicit = null;
+    let hasConsoleUrl = false;
+    const confPath = resolveConsoleConfPath(env);
+    if (confPath) {
+      for (const raw of fs.readFileSync(confPath, 'utf8').split('\n')) {
+        const line = raw.trim();
+        if (!line || line.startsWith('#')) continue;
+        const eq = line.indexOf('=');
+        if (eq < 0) continue;
+        const key = line.slice(0, eq).trim();
+        const value = line.slice(eq + 1).trim().toLowerCase();
+        if (key === 'console_liveness_relay') {
+          if (TRUTHY.has(value)) explicit = true;
+          else if (FALSY.has(value)) explicit = false;
+        } else if (key === 'console_telemetry_url' || key === 'console_url' || key === 'console_telemetry_endpoint_url') {
+          if (value) hasConsoleUrl = true;
+        }
+      }
+    }
+    // config.sh precedence: explicit conf key > pre-set env var > default-on when a console url resolves.
+    enabled = explicit !== null ? explicit : envDecision !== null ? envDecision : hasConsoleUrl;
+  } catch {
+    enabled = envDecision === true; // best-effort: honor only an explicit env-on if the conf read failed
+  }
+  relayEnabledCache.set(cacheKey, enabled);
+  return enabled;
+}
+
 /**
- * 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).
+ * OPTIONAL console liveness relay (#295, ADR 0021 §4/§7; conf-driven per #567). 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 `resolveLivenessRelayEnabled`, the whole thing wrapped so any failure
+ * (missing script, spawn error) is swallowed. Not enabled ⇒ a cheap resolve 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;
+    if (!resolveLivenessRelayEnabled(process.env)) 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' });
+    // Pass the environment through UNCHANGED — do not force the enable flag. relay.sh re-sources
+    // config.sh, which is the authoritative, trust-gated decision for both enablement (conf key >
+    // env > default-on) and the POST endpoint. Our resolve above is only a lenient spawn pre-gate:
+    // if we enabled from an untrusted default-path conf, config.sh trust-gates relay.sh to a no-op
+    // rather than us bypassing it by forcing the flag on.
+    const child = spawn('bash', [relay, JSON.stringify(evt)], {
+      detached: true,
+      stdio: 'ignore',
+      env: process.env,
+    });
     child.on('error', () => {}); // never surface a spawn failure
     child.unref(); // fully detach — the parent never waits on the relay
   } catch {
@@ -70,4 +170,4 @@ function appendLivenessEvent(root, evt) {
   relayLivenessEvent(evt); // then optionally mirror to the Console — best-effort, detached, off by default
 }
 
-module.exports = { livenessStreamFile, appendLivenessEvent };
+module.exports = { livenessStreamFile, appendLivenessEvent, resolveLivenessRelayEnabled };

package/dist/base/scripts/liveness/relay.sh

@@ -7,26 +7,36 @@
 # never forked). The Console side ingests this record type and projects the fleet view + runs the
 # janitor (console repo #125); this script is only the flow-agents EMIT half.
 #
-# STRICTLY OPTIONAL and local-first (ADR 0012 §5): a no-op unless FLOW_AGENTS_CONSOLE_LIVENESS_RELAY
-# is enabled AND a console endpoint is configured. Best-effort throughout — it must NEVER block, slow,
-# or fail the local liveness write that already happened before this was invoked. Every failure path
-# is a quiet `exit 0`.
+# STRICTLY OPTIONAL and local-first (ADR 0012 §5): a no-op unless the liveness relay is enabled AND a
+# console endpoint is configured. Enablement is conf-driven (#567, parity with economics #469): an
+# operator sets `console_liveness_relay=1` in the console conf (or it defaults on once a console url
+# resolves) — NOT an env var. config.sh (sourced below) is the authoritative, trust-gated decision
+# and also supplies the endpoint/token/tenant from the conf. Best-effort throughout — it must NEVER
+# block, slow, or fail the local liveness write that already happened before this was invoked. Every
+# failure path is a quiet `exit 0`.
 #
 # Invoked (fully detached, best-effort) from scripts/hooks/lib/liveness-write.js after the durable
 # local append. Usage: relay.sh '<liveness-event-json>'
 set -uo pipefail
 
-# Opt-in gate — off by default.
-case "${FLOW_AGENTS_CONSOLE_LIVENESS_RELAY:-}" in
-  1 | true | TRUE | yes | on) ;;
-  *) exit 0 ;;
-esac
-
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" || exit 0
 
 # transport.sh sources ${TELEMETRY_DIR}/lib/redact.sh at load — point it at the telemetry lib dir,
 # then reuse the SAME console POST core the telemetry mirror uses.
 export TELEMETRY_DIR="${TELEMETRY_DIR:-$SCRIPT_DIR/../telemetry}"
+
+# Source config.sh FIRST (best-effort, like economics-record.sh) so the conf resolves enablement
+# (FLOW_AGENTS_CONSOLE_LIVENESS_RELAY) and the endpoint/token/tenant — trust-gated for default-path
+# confs. This is what makes conf-only operation work with NO env var set.
+# shellcheck source=/dev/null
+[[ -f "$TELEMETRY_DIR/lib/config.sh" ]] && source "$TELEMETRY_DIR/lib/config.sh" 2>/dev/null || true
+
+# Opt-in gate — off by default, now honoring the conf-derived value config.sh just resolved.
+case "${FLOW_AGENTS_CONSOLE_LIVENESS_RELAY:-}" in
+  1 | true | TRUE | yes | on) ;;
+  *) exit 0 ;;
+esac
+
 [[ -f "$TELEMETRY_DIR/lib/transport.sh" ]] || exit 0
 # shellcheck source=/dev/null
 source "$TELEMETRY_DIR/lib/transport.sh" 2>/dev/null || exit 0
@@ -73,7 +83,9 @@ record="$(printf '%s' "$event_json" | jq -c '{
   ttlSeconds: (.ttlSeconds // null),
   host: (.host // null),
   branch: (.branch // null),
-  artifact_dir: (.artifact_dir // .artifactDir // null)
+  artifact_dir: (.artifact_dir // .artifactDir // null),
+  source: (.source // null),
+  activity: (.activity // null)
 }' 2>/dev/null)" || exit 0
 [[ -z "$record" || "$record" == "null" ]] && exit 0
 

package/dist/base/scripts/telemetry/lib/config.sh

@@ -109,6 +109,13 @@ FLOW_AGENTS_CONSOLE_ECONOMICS_ENDPOINT_URL="${FLOW_AGENTS_CONSOLE_ECONOMICS_ENDP
 # Set (non-empty) only when the config file carries an explicit console_economics_relay key —
 # distinguishes "operator said 0/1" from "key absent" for the default-on rule below.
 console_economics_relay_raw=""
+# Liveness relay (#567): same conf-driven, opt-out-not-silent-off shape as economics (#469) so an
+# operator enables the hosted liveness mirror via console_liveness_relay=1 in the conf, NOT an env
+# var/.profile. A caller-pre-set env var is the starting point; the config key overrides it; absent
+# any key the default-on rule below turns it on once a console telemetry sink resolves.
+FLOW_AGENTS_CONSOLE_LIVENESS_RELAY="${FLOW_AGENTS_CONSOLE_LIVENESS_RELAY:-}"
+FLOW_AGENTS_CONSOLE_LIVENESS_ENDPOINT_URL="${FLOW_AGENTS_CONSOLE_LIVENESS_ENDPOINT_URL:-}"
+console_liveness_relay_raw=""
 # Pricing registry source (consumed by lib/pricing.sh). Explicit file/URL win;
 # otherwise lib/pricing.sh uses the bundled pricing.json offline.
 TELEMETRY_PRICING_FILE="${TELEMETRY_PRICING_FILE:-${FLOW_AGENTS_PRICING_FILE:-}}"
@@ -164,6 +171,17 @@ if [[ -f "$TELEMETRY_CONFIG_FILE" ]]; then
           esac
           ;;
         console_economics_endpoint_url) FLOW_AGENTS_CONSOLE_ECONOMICS_ENDPOINT_URL="$value" ;;
+        console_liveness_relay)
+          case "$(echo "$value" | tr '[:upper:]' '[:lower:]')" in
+            1|true|yes|on) console_liveness_relay_raw="1" ;;
+            0|false|no|off) console_liveness_relay_raw="0" ;;
+            *)
+              printf 'warning: config.sh: unrecognized console_liveness_relay value %q; treating as off\n' "$value" >&2
+              console_liveness_relay_raw="$value"
+              ;;
+          esac
+          ;;
+        console_liveness_endpoint_url) FLOW_AGENTS_CONSOLE_LIVENESS_ENDPOINT_URL="$value" ;;
         console_pricing_url) TELEMETRY_PRICING_URL="$value" ;;
         pricing_url) TELEMETRY_PRICING_URL="$value" ;;
         pricing_file) TELEMETRY_PRICING_FILE="$value" ;;
@@ -186,6 +204,17 @@ elif [[ -z "$FLOW_AGENTS_CONSOLE_ECONOMICS_RELAY" \
   FLOW_AGENTS_CONSOLE_ECONOMICS_RELAY=1
 fi
 
+# Liveness relay default-on rule (#567), identical shape to economics above: an explicit
+# console_liveness_relay config key always wins; otherwise, once a console telemetry sink resolves,
+# the relay defaults ON unless a caller already pre-set FLOW_AGENTS_CONSOLE_LIVENESS_RELAY in the
+# environment. relay.sh's own opt-in gate reads this exact variable.
+if [[ -n "$console_liveness_relay_raw" ]]; then
+  FLOW_AGENTS_CONSOLE_LIVENESS_RELAY="$console_liveness_relay_raw"
+elif [[ -z "$FLOW_AGENTS_CONSOLE_LIVENESS_RELAY" \
+      && ( -n "${CONSOLE_TELEMETRY_URL:-}" || -n "${CONSOLE_TELEMETRY_ENDPOINT_URL:-}" ) ]]; then
+  FLOW_AGENTS_CONSOLE_LIVENESS_RELAY=1
+fi
+
 # Pricing URL is explicit-only (env or config). Do not derive the console
 # pricing endpoint by default; the bundled registry is the reliable offline floor.
 

package/dist/claude-code/build/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "4.1.0",
+  "version": "4.2.1",
   "type": "module"
 }

package/dist/claude-code/build/src/builder-flow-runtime.js

@@ -572,7 +572,7 @@ async function bundleGateEvidence(bundle, gate, state, subject, projectRoot, man
         throw new BuilderBuildRunInputError("evidence.claims.metadata.gate_claim.route_reason", `is not declared by gate ${String(gate.id ?? "<unknown>")}`);
     }
     if (String(gate.id) === "verify-gate" && relevant.some((claim) => claim.claimType === "builder.verify.tests" && claim.value === "pass")) {
-        await assertVerifiedTestsTrust(bundle.claims, projectRoot);
+        await assertVerifiedTestsTrust(relevant, projectRoot);
     }
     return { failed, routeReason, expectationIds, visitEnteredAt: enteredAt };
 }
@@ -602,8 +602,8 @@ function timestampAtOrAfter(value, boundary) {
     const parsed = parseTimestamp(value);
     return parsed !== null && parsed >= boundary;
 }
-async function assertVerifiedTestsTrust(claims, projectRoot) {
-    const testClaims = claims.filter((claim) => isRecord(claim)
+async function assertVerifiedTestsTrust(currentGateClaims, projectRoot) {
+    const testClaims = currentGateClaims.filter((claim) => isRecord(claim)
         && claim.claimType === "builder.verify.tests"
         && claim.value === "pass"
         && isRecord(claim.metadata)
@@ -611,7 +611,12 @@ async function assertVerifiedTestsTrust(claims, projectRoot) {
         && claim.metadata.gate_claim.expectation_id === "tests-evidence");
     if (testClaims.length === 0)
         throw new BuilderBuildRunInputError("evidence.tests", "is missing a passing tests-evidence claim");
-    const liveCritiques = claims.filter((claim) => isRecord(claim)
+    // A route-back starts a new gate visit and therefore a new critique generation. Historical
+    // reviewer slices remain in the bundle and manifest for audit, but only critiques acquired
+    // during this visit describe the implementation snapshot currently being verified. Within a
+    // visit every live reviewer slice still participates, so changing reviewers cannot bury a
+    // disputed finding.
+    const liveCritiques = currentGateClaims.filter((claim) => isRecord(claim)
         && isRecord(claim.metadata)
         && claim.metadata.origin === "critique"
         && typeof claim.metadata.superseded_by !== "string");
@@ -627,7 +632,7 @@ async function assertVerifiedTestsTrust(claims, projectRoot) {
         await Promise.all(artifacts.map((artifact) => assertReviewedArtifactDigest(artifact, projectRoot)));
         assertReviewedWorkspaceSnapshot(claim, artifacts, projectRoot);
     }));
-    const criteria = claims.filter((claim) => isRecord(claim) && isRecord(claim.metadata) && claim.metadata.origin === "acceptance");
+    const criteria = currentGateClaims.filter((claim) => isRecord(claim) && isRecord(claim.metadata) && claim.metadata.origin === "acceptance");
     if (criteria.length === 0 || criteria.some((claim) => {
         const criterion = isRecord(claim.metadata.criterion) ? claim.metadata.criterion : null;
         return claim.value !== "pass" || !criterion || !Array.isArray(criterion.evidence_refs) || criterion.evidence_refs.length === 0;

package/dist/claude-code/context/contracts/verification-contract.md

@@ -20,6 +20,12 @@ Verifiers and reviewers do not modify source code. They may run commands, inspec
 
 Verifiers write evidence and acceptance status **through** `record-evidence` (directly, or via the orchestrating skill), never by hand-authoring `evidence.json`, `acceptance.json`, or `trust.bundle`. Those bespoke sidecars were retired as the source of truth by ADR 0010 Phase 4c; the `trust.bundle` is the sole verification artifact, and only the sidecar writer performs the evidence classification (`evidenceType`/`method` derivation and manifest reconciliation) the CI trust anchor depends on (ADR 0020). `config-protection.js` blocks direct tool writes to these gate files by design. If the sidecar writer is unavailable, record the exact gap instead of writing the files by hand.
 
+### Critique Generations Across Route-Backs
+
+Each visit to a verification gate establishes a critique generation. Critiques acquired during that visit must target the current implementation snapshot, and every live reviewer slice in the generation participates in the gate decision. A disputed finding therefore cannot be hidden by adding a different reviewer.
+
+When Flow routes back and later re-enters verification, a fresh critique generation is required. Older reviewer slices remain immutable audit history in the trust bundle and evidence manifest, but their prior snapshot hashes are not reinterpreted as reviews of the new implementation. A reviewer handoff must use the public critique writer; it must never require actor impersonation or direct trust-bundle edits.
+
 ## Mutation Testing Runs In A Scratch Copy
 
 Mutation-testing tools (Stryker or equivalent) **must** run against a scratch/throwaway copy of the working tree, never the live working tree. They deliberately introduce defects to measure test-suite sensitivity; running them in place risks leaving mutated source, corrupting the checkout, or tripping the gate/anchor on injected failures. Copy the tree to a temporary directory (or a git worktree/clone) and run the mutation tool there; discard it afterward.