@kontourai/flow-agents 4.1.0 → 4.2.1

package/dist/kiro/evals/integration/test_liveness_console_relay.sh

@@ -18,6 +18,13 @@ source "$ROOT/evals/lib/node.sh"
 
 TMPDIR_EVAL="$(mktemp -d)"
 trap 'rm -rf "$TMPDIR_EVAL"; [[ -n "${STUB_PID:-}" ]] && kill "$STUB_PID" 2>/dev/null' EXIT
+
+# Hermetic HOME: the conf-driven relay resolver (#567) reads __KIRO_PACKAGE_ROOT__/telemetry-console.conf
+# as a resolution slot. Point HOME at an empty dir so these tests never read the running machine's
+# real console conf — enablement here is controlled only by the env flag / an explicit
+# TELEMETRY_CONFIG_FILE, exactly as each case sets up.
+export HOME="$TMPDIR_EVAL/clean-home"
+mkdir -p "$HOME"
 PORT=38795
 RECV="$TMPDIR_EVAL/recv.jsonl"
 
@@ -29,6 +36,12 @@ fail() { echo "  [FAIL] $1"; errors=$((errors + 1)); }
 # controls the response — "ok" (200) or "fail" (500) — to exercise the relay-failure path.
 start_stub() {
   local mode="$1"
+  # Fresh port per stub: the relay POST is detached/async, so a late POST from a PRIOR "on" case
+  # could otherwise race into the next case's freshly-cleared RECV on a reused port and cause a
+  # spurious "a POST happened" failure in a "no POST" assertion. A new port each time sends any
+  # stray prior-case POST to a now-dead port (connection refused), never into this case's RECV.
+  PORT=$((PORT + 1))
+  ENDPOINT="http://127.0.0.1:${PORT}/records"
   STUB_MODE="$mode" node -e '
 const http=require("http"),fs=require("fs");
 const out=process.argv[1], mode=process.env.STUB_MODE||"ok";
@@ -67,7 +80,7 @@ echo "=== console liveness relay (#295) ==="
 echo "--- 1. relay on+configured: liveness emit mirrors to the Console with Bearer + tenant ---"
 : > "$RECV"; start_stub ok || { fail "stub server did not start"; }
 ROOT_A="$TMPDIR_EVAL/a"
-EVT1='{"type":"claim","subjectId":"relay-subj-1","actor":"claude-code:sessA:host","actor_key":"claude-code:sessA:host","at":"2026-07-05T00:00:00Z","ttlSeconds":1800,"host":"host","branch":"agent/a/relay-subj-1","artifact_dir":"relay-subj-1"}'
+EVT1='{"type":"claim","subjectId":"relay-subj-1","actor":"claude-code:sessA:host","actor_key":"claude-code:sessA:host","at":"2026-07-05T00:00:00Z","ttlSeconds":1800,"host":"host","branch":"agent/a/relay-subj-1","artifact_dir":"relay-subj-1","source":"tool-activity","activity":{"tool":"Bash"}}'
 (
   export FLOW_AGENTS_CONSOLE_LIVENESS_RELAY=1
   export FLOW_AGENTS_CONSOLE_LIVENESS_ENDPOINT_URL="$ENDPOINT"
@@ -92,6 +105,8 @@ const checks=[
   ["subjectId", b.subjectId==="relay-subj-1"],
   ["actor", b.actor==="claude-code:sessA:host"],
   ["branch", b.branch==="agent/a/relay-subj-1"],
+  ["source tool-activity", b.source==="tool-activity"],
+  ["activity.tool Bash (richer real-liveness rides to the Console)", !!b.activity && b.activity.tool==="Bash"],
 ];
 for(const [name,ok] of checks) console.log((ok?"OK ":"BAD ")+name);
 ' "$RECV" > "$TMPDIR_EVAL/checks.txt" 2>&1
@@ -156,6 +171,81 @@ console.log(hasRawCtl?"RAW":"ESCAPED");
 if grep -q ESCAPED "$TMPDIR_EVAL/inj.txt"; then pass "hostile actor/branch control bytes are JSON-escaped, never raw in the POST body (injection discipline)"; else fail "raw control bytes reached the POST body: $(cat "$TMPDIR_EVAL/inj.txt")"; fi
 stop_stub
 
+# ─── 6. CONF-DRIVEN enablement (#567): NO env flag, `console_liveness_relay=1` in the conf → POST ─
+echo "--- 6. conf-driven (#567): console_liveness_relay=1 in the conf relays with NO env var ---"
+: > "$RECV"; start_stub ok
+ROOT_F="$TMPDIR_EVAL/f"
+CONF6="$TMPDIR_EVAL/conf6.conf"
+printf 'console_telemetry_url=https://example.invalid\nconsole_liveness_relay=1\n' > "$CONF6"
+(
+  unset FLOW_AGENTS_CONSOLE_LIVENESS_RELAY   # the whole point: no env var
+  export TELEMETRY_CONFIG_FILE="$CONF6"
+  export FLOW_AGENTS_CONSOLE_LIVENESS_ENDPOINT_URL="$ENDPOINT"   # POST target (stub)
+  emit_event "$ROOT_F" '{"type":"claim","subjectId":"conf-on-1","actor":"a","at":"t"}'
+)
+[[ -s "$ROOT_F/liveness/events.jsonl" ]] && pass "local write happened (conf-driven case)" || fail "local write missing (conf-driven)"
+if wait_for_post; then pass "conf-driven relay POSTed with NO env var (console_liveness_relay=1)"; else fail "conf-driven relay did NOT POST (env-var-free enablement broken)"; fi
+stop_stub
+
+# ─── 7. CONF-DRIVEN auto-on parity (#469): a console url with no explicit key defaults ON ────────
+echo "--- 7. conf-driven auto-on: a console url with no explicit key relays; explicit =0 suppresses ---"
+: > "$RECV"; start_stub ok
+ROOT_G="$TMPDIR_EVAL/g"
+CONF7="$TMPDIR_EVAL/conf7.conf"
+printf 'console_telemetry_url=https://example.invalid\n' > "$CONF7"   # url only, no explicit key
+(
+  unset FLOW_AGENTS_CONSOLE_LIVENESS_RELAY
+  export TELEMETRY_CONFIG_FILE="$CONF7"
+  export FLOW_AGENTS_CONSOLE_LIVENESS_ENDPOINT_URL="$ENDPOINT"
+  emit_event "$ROOT_G" '{"type":"claim","subjectId":"auto-on-1","actor":"a","at":"t"}'
+)
+if wait_for_post; then pass "auto-on: a configured console url defaults the relay ON (#469 parity)"; else fail "auto-on did NOT POST (console-url default-on broken)"; fi
+stop_stub
+
+: > "$RECV"; start_stub ok
+ROOT_H="$TMPDIR_EVAL/h"
+CONF8="$TMPDIR_EVAL/conf8.conf"
+printf 'console_telemetry_url=https://example.invalid\nconsole_liveness_relay=0\n' > "$CONF8"   # explicit off wins
+(
+  unset FLOW_AGENTS_CONSOLE_LIVENESS_RELAY
+  export TELEMETRY_CONFIG_FILE="$CONF8"
+  export FLOW_AGENTS_CONSOLE_LIVENESS_ENDPOINT_URL="$ENDPOINT"
+  emit_event "$ROOT_H" '{"type":"claim","subjectId":"conf-off-1","actor":"a","at":"t"}'
+)
+sleep 1
+[[ -s "$ROOT_H/liveness/events.jsonl" ]] && pass "local write happened (explicit conf off)" || fail "local write missing (explicit conf off)"
+[[ ! -s "$RECV" ]] && pass "explicit console_liveness_relay=0 suppresses the relay even with a url (opt-out wins)" || fail "a POST happened despite console_liveness_relay=0"
+stop_stub
+
+# ─── 8. EXFIL DEFENSE: an UNTRUSTED (mode 644) default-path conf must NOT relay (trust gate) ─────
+# The cases above drive enablement through TELEMETRY_CONFIG_FILE, which is trusted BY DESIGN (an
+# explicit env override bypasses the mode-600 gate). This case exercises the actual supply-chain
+# defense end-to-end: a conf planted at the user-global default slot (__KIRO_PACKAGE_ROOT__/…, reached via
+# the hermetic HOME set at the top) pointing at an attacker stub with console_liveness_relay=1, but
+# mode 644 — exactly what a non-operator drop (clone/tarball/local tool) can produce, since git can
+# only ship 644/755, never 600. relay.sh re-sources config.sh, whose telemetry_conf_trusted gate
+# (mode 600 + owner + not-a-symlink) rejects it, so no URL resolves and nothing is POSTed — while
+# the durable local write still happens. NO env flag, NO TELEMETRY_CONFIG_FILE, NO endpoint env:
+# the untrusted conf is the ONLY possible signal, so a POST here would be a real exfil regression.
+echo "--- 8. exfil defense: an untrusted (mode 644) __KIRO_PACKAGE_ROOT__ conf with an attacker url never relays ---"
+: > "$RECV"; start_stub ok
+ROOT_X="$TMPDIR_EVAL/x"
+mkdir -p "__KIRO_PACKAGE_ROOT__"
+UNTRUSTED_CONF="__KIRO_PACKAGE_ROOT__/telemetry-console.conf"
+printf 'console_telemetry_url=http://127.0.0.1:%s\nconsole_liveness_relay=1\n' "$PORT" > "$UNTRUSTED_CONF"
+chmod 644 "$UNTRUSTED_CONF"
+(
+  unset FLOW_AGENTS_CONSOLE_LIVENESS_RELAY
+  unset TELEMETRY_CONFIG_FILE
+  unset FLOW_AGENTS_CONSOLE_LIVENESS_ENDPOINT_URL
+  emit_event "$ROOT_X" '{"type":"claim","subjectId":"exfil-x","actor":"a","at":"t"}'
+)
+sleep 1
+[[ -s "$ROOT_X/liveness/events.jsonl" ]] && pass "local write happened (untrusted-conf case, local-first intact)" || fail "local write missing (untrusted conf)"
+[[ ! -s "$RECV" ]] && pass "an untrusted (644) default-path conf naming an attacker url NEVER relays (trust gate holds, no exfil)" || fail "EXFIL: a POST reached the attacker stub from an untrusted 644 conf"
+rm -f "$UNTRUSTED_CONF"
+stop_stub
+
 echo ""
 if [[ "$errors" -eq 0 ]]; then
   echo "test_liveness_console_relay: all checks passed."

package/dist/kiro/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/kiro/install.sh

@@ -73,7 +73,7 @@ fi
 export DEST
 find "$DEST" \( -path "$DEST/AGENTS.md" -o -path "$DEST/CLAUDE.md" \) -prune -o -type f \( -name '*.json' -o -name '*.md' -o -name '*.sh' -o -name '*.js' -o -name '*.ts' -o -name '*.yaml' -o -name '*.yml' \) -print0 | xargs -0 perl -0pi -e 's#__KIRO_PACKAGE_ROOT__#$ENV{DEST}#g'
 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 "kiro" || true
+  node "$DEST/scripts/install-merge.js" --stamp-only --version "4.2.1" --install-record "$DEST/.flow-agents/install.json" --runtime "kiro" || 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/kiro/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/kiro/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/kiro/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/kiro/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: __KIRO_PACKAGE_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 };