@kontourai/flow-agents 4.1.0 → 4.2.1

package/evals/integration/test_effective_backlog_settings.sh

@@ -2,13 +2,18 @@
 set -uo pipefail
 
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
-SCRIPT="$ROOT/scripts/effective-backlog-settings.js"
-PROJECT="$ROOT/context/settings/backlog-provider-settings.json"
-GLOBAL="$ROOT/evals/fixtures/backlog-provider-settings/global-default.json"
-OVERRIDE="$ROOT/evals/fixtures/backlog-provider-settings/project-override.json"
-EMPTY="$(mktemp)"
-trap 'rm -f "$EMPTY"' EXIT
-printf '{"schema_version":"1.0","projects":[]}\n' > "$EMPTY"
+CLI="$ROOT/build/src/cli.js"
+BACKLOG_SETTINGS="$ROOT/context/settings/backlog-provider-settings.json"
+ASSIGNMENT_SETTINGS="$ROOT/context/settings/assignment-provider-settings.json"
+BACKLOG_GLOBAL="$ROOT/evals/fixtures/backlog-provider-settings/global-default.json"
+BACKLOG_OVERRIDE="$ROOT/evals/fixtures/backlog-provider-settings/project-override.json"
+TMPDIR_EVAL="$(mktemp -d)"
+EMPTY_BACKLOG="$TMPDIR_EVAL/empty-backlog-settings.json"
+EMPTY_ASSIGNMENT="$TMPDIR_EVAL/empty-assignment-settings.json"
+trap 'rm -rf "$TMPDIR_EVAL"' EXIT
+
+printf '{"schema_version":"1.0","projects":[]}\n' > "$EMPTY_BACKLOG"
+printf '{"schema_version":"1.0","projects":[]}\n' > "$EMPTY_ASSIGNMENT"
 
 errors=0
 pass() { echo "  ✓ $1"; }
@@ -18,17 +23,32 @@ json_value() {
   NO_COLOR=1 FORCE_COLOR=0 node -e 'const fs=require("fs"); let cur=JSON.parse(fs.readFileSync(0,"utf8")); for (const part of process.argv[1].split(".")) cur=Array.isArray(cur) ? cur[Number(part)] : cur[part]; console.log(cur);' "$1"
 }
 
-echo "=== Effective Backlog Settings ==="
+echo "=== Effective provider settings ==="
+
+# Build exactly once before calling the actual compiled CLI commands below.
+if (cd "$ROOT" && npm run build --silent); then
+  pass "compiled CLI build succeeds"
+else
+  fail "compiled CLI build succeeds"
+fi
 
-default_result="$(cd "$ROOT" && npm run --silent effective-backlog-settings -- --repo-path . --json)"
-[[ "$(printf '%s' "$default_result" | json_value status)" == "configured" ]] && pass "default project settings resolve through npm command" || fail "default project settings resolve through npm command"
+if [[ ! -f "$CLI" ]]; then
+  fail "compiled CLI is available"
+else
+  pass "compiled CLI is available"
+fi
+
+echo "--- existing backlog precedence and ask-user behavior ---"
+
+default_result="$(node "$CLI" effective-backlog-settings --repo-path "$ROOT" --json 2>/dev/null)"
+[[ "$(printf '%s' "$default_result" | json_value status)" == "configured" ]] && pass "default project settings resolve through compiled CLI" || fail "default project settings resolve through compiled CLI"
 [[ "$(printf '%s' "$default_result" | json_value settings.work_item_provider.kind)" == "github" ]] && pass "default provider kind is github" || fail "default provider kind is github"
 [[ "$(printf '%s' "$default_result" | json_value settings.work_item_provider.repo.owner)" == "kontourai" ]] && pass "default repo owner is kontourai" || fail "default repo owner is kontourai"
 [[ "$(printf '%s' "$default_result" | json_value settings.work_item_provider.repo.name)" == "flow-agents" ]] && pass "default repo name is flow-agents" || fail "default repo name is flow-agents"
 [[ "$(printf '%s' "$default_result" | json_value settings.board_provider.board.number)" == "1" ]] && pass "default project number is 1" || fail "default project number is 1"
 ! printf '%s' "$default_result" | rg -q '/build/context/settings/backlog-provider-settings.json' && pass "default settings path is not build-relative" || fail "default settings path is not build-relative"
 
-configured="$(node "$SCRIPT" --repo-path "$ROOT" --project-settings "$PROJECT" --global-settings "$EMPTY" --json)"
+configured="$(node "$CLI" effective-backlog-settings --repo-path "$ROOT" --project-settings "$BACKLOG_SETTINGS" --global-settings "$EMPTY_BACKLOG" --json)"
 [[ "$(printf '%s' "$configured" | json_value status)" == "configured" ]] && pass "configured repo resolves" || fail "configured repo resolves"
 [[ "$(printf '%s' "$configured" | json_value settings.work_item_provider.kind)" == "github" ]] && pass "provider kind is github" || fail "provider kind is github"
 [[ "$(printf '%s' "$configured" | json_value settings.work_item_provider.repo.owner)" == "kontourai" ]] && pass "repo owner is kontourai" || fail "repo owner is kontourai"
@@ -38,21 +58,104 @@ printf '%s' "$configured" | rg -F -q '"ready_statuses": [' && pass "filters incl
 printf '%s' "$configured" | rg -F -q '"include_labels": []' && pass "filters do not require labels by default" || fail "filters do not require labels by default"
 printf '%s' "$configured" | rg -q '"prefer_finishing_active_work": true' && pass "WIP policy prefers finishing active work" || fail "WIP policy prefers finishing active work"
 
-override_result="$(node "$SCRIPT" --repo-path "$ROOT" --project-settings "$OVERRIDE" --global-settings "$GLOBAL" --json)"
+override_result="$(node "$CLI" effective-backlog-settings --repo-path "$ROOT" --project-settings "$BACKLOG_OVERRIDE" --global-settings "$BACKLOG_GLOBAL" --json)"
 [[ "$(printf '%s' "$override_result" | json_value source)" == "project" ]] && pass "project settings override global defaults" || fail "project settings override global defaults"
 [[ "$(printf '%s' "$override_result" | json_value settings.board_provider.board.number)" == "1" ]] && pass "project override keeps Project 1" || fail "project override keeps Project 1"
 ! printf '%s' "$override_result" | rg -q 'global-ready' && pass "project override replaces global filters" || fail "project override replaces global filters"
 
-missing_output="$(node "$SCRIPT" --repo-path "$ROOT" --project-settings "$EMPTY" --global-settings "$EMPTY" --json 2>/dev/null)"
+missing_output="$(node "$CLI" effective-backlog-settings --repo-path "$ROOT" --project-settings "$EMPTY_BACKLOG" --global-settings "$EMPTY_BACKLOG" --json 2>/dev/null)"
 missing_status=$?
 [[ "$missing_status" -eq 2 ]] && pass "missing settings exits with ask-user status" || fail "missing settings exits with ask-user status"
 [[ "$(printf '%s' "$missing_output" | json_value status)" == "ask_user" ]] && pass "missing settings reports ask_user" || fail "missing settings reports ask_user"
 printf '%s' "$missing_output" | rg -q 'WorkItemProvider and BoardProvider' && pass "missing settings names provider roles" || fail "missing settings names provider roles"
 
+echo "--- public self-configuration and external multi-repository settings ---"
+
+# Product-specific fleet routing belongs in consumer-owned settings. The public package proves
+# that an external settings file can configure multiple repositories without embedding those
+# consumer mappings in Flow Agents source.
+if node --input-type=module - "$ROOT" "$CLI" "$TMPDIR_EVAL/repos" "$BACKLOG_SETTINGS" "$ASSIGNMENT_SETTINGS" "$EMPTY_BACKLOG" "$EMPTY_ASSIGNMENT" <<'NODE'
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import Ajv2020 from "ajv/dist/2020.js";
+
+const [root, cli, reposRoot, publicBacklogPath, publicAssignmentPath, emptyBacklog, emptyAssignment] = process.argv.slice(2);
+const readJson = (file) => JSON.parse(fs.readFileSync(file, "utf8"));
+const assert = (condition, message) => {
+  if (!condition) throw new Error(message);
+};
+
+const backlogSchema = readJson(path.join(root, "schemas/backlog-provider-settings.schema.json"));
+const assignmentSchema = readJson(path.join(root, "schemas/assignment-provider-settings.schema.json"));
+const ajv = new Ajv2020({ allErrors: true });
+const validateBacklog = ajv.compile(backlogSchema);
+const validateAssignment = ajv.compile(assignmentSchema);
+
+const publicBacklog = readJson(publicBacklogPath);
+const publicAssignment = readJson(publicAssignmentPath);
+assert(validateBacklog(publicBacklog), `public backlog settings schema validation failed: ${ajv.errorsText(validateBacklog.errors)}`);
+assert(validateAssignment(publicAssignment), `public assignment settings schema validation failed: ${ajv.errorsText(validateAssignment.errors)}`);
+assert(publicBacklog.projects.length === 1 && publicBacklog.projects[0]?.project?.repo?.name === "flow-agents", "public backlog settings must remain self-only");
+assert(publicAssignment.projects.length === 1 && publicAssignment.projects[0]?.project?.repo?.name === "flow-agents", "public assignment settings must remain self-only");
+
+const owner = "example-org";
+const targets = ["alpha", "beta"];
+const projectNumber = 42;
+const repoRef = (name) => ({ owner, name, url: `https://github.com/${owner}/${name}` });
+const externalBacklog = {
+  schema_version: "1.0",
+  projects: targets.map((name) => ({
+    project: { repo: repoRef(name) },
+    work_item_provider: { role: "WorkItemProvider", kind: "github", repo: repoRef(name), capabilities: ["issues", "labels", "assignees", "pr_links", "comments"] },
+    board_provider: { role: "BoardProvider", kind: "github", repo: repoRef(name), board: { type: "github_project", owner, number: projectNumber, url: `https://github.com/orgs/${owner}/projects/${projectNumber}` }, capabilities: ["projects_boards", "status_fields", "custom_fields"] },
+    selection: { filters: { issue_state: "open", include_labels: [], ready_statuses: ["ready"], exclude_statuses: ["triage", "in_progress", "blocked", "review", "verification", "done"] }, wip_policy: { prefer_finishing_active_work: true, active_statuses: ["in_progress", "review", "verification"], block_new_work_when_active_count_exceeds: 0 } },
+  })),
+};
+const externalAssignment = {
+  schema_version: "1.0",
+  projects: targets.map((name) => ({
+    project: { repo: repoRef(name) },
+    provider: { kind: "github", repo: repoRef(name), capabilities: ["assignees", "labels", "comments"] },
+    policy: { label_name: "agent:claimed", claim_comment_marker: "<!-- flow-agents:assignment-claim -->", human_assignee_policy: { behavior: "ask_first", idle_threshold_days: 3 }, comment_refresh_on_phase_transition: false },
+  })),
+};
+assert(validateBacklog(externalBacklog), `external backlog settings schema validation failed: ${ajv.errorsText(validateBacklog.errors)}`);
+assert(validateAssignment(externalAssignment), `external assignment settings schema validation failed: ${ajv.errorsText(validateAssignment.errors)}`);
+
+fs.mkdirSync(reposRoot, { recursive: true });
+const externalBacklogPath = path.join(reposRoot, "backlog-provider-settings.json");
+const externalAssignmentPath = path.join(reposRoot, "assignment-provider-settings.json");
+fs.writeFileSync(externalBacklogPath, JSON.stringify(externalBacklog, null, 2));
+fs.writeFileSync(externalAssignmentPath, JSON.stringify(externalAssignment, null, 2));
+
+for (const name of targets) {
+  const repoPath = path.join(reposRoot, name);
+  fs.mkdirSync(repoPath, { recursive: true });
+  fs.writeFileSync(path.join(repoPath, "package.json"), JSON.stringify({ name: `fixture-${name}`, repository: { type: "git", url: `https://github.com/${owner}/${name}.git` } }, null, 2));
+  const resolve = (command, globalPath, emptyProject) => JSON.parse(execFileSync(process.execPath, [cli, command, "--repo-path", repoPath, "--project-settings", emptyProject, "--global-settings", globalPath, "--json"], { encoding: "utf8" }));
+  const backlogResult = resolve("effective-backlog-settings", externalBacklogPath, emptyBacklog);
+  const assignmentResult = resolve("effective-assignment-provider-settings", externalAssignmentPath, emptyAssignment);
+
+  assert(backlogResult.status === "configured" && backlogResult.source === "global", `${name} backlog settings must resolve from the external file`);
+  assert(backlogResult.settings.work_item_provider?.repo?.name === name, `${name} must select its own work item repository`);
+  assert(backlogResult.settings.board_provider?.board?.number === projectNumber, `${name} must select the external board`);
+  assert(assignmentResult.status === "configured" && assignmentResult.source === "global", `${name} assignment settings must resolve from the external file`);
+  assert(assignmentResult.settings.provider?.repo?.name === name, `${name} must select its own assignment repository`);
+}
+
+console.log("Public settings remain self-only and external multi-repository settings resolve through the supported global precedence layer.");
+NODE
+then
+  pass "public settings stay self-only and external multi-repository settings resolve"
+else
+  fail "public settings stay self-only and external multi-repository settings resolve"
+fi
+
 if [[ "$errors" -eq 0 ]]; then
-  echo "Effective backlog settings checks passed"
+  echo "Effective provider settings checks passed"
 else
-  echo "Effective backlog settings checks failed: $errors"
+  echo "Effective provider settings checks failed: $errors"
 fi
 
 exit "$errors"

package/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 ~/.flow-agents/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 (~/.flow-agents/…, 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) ~/.flow-agents conf with an attacker url never relays ---"
+: > "$RECV"; start_stub ok
+ROOT_X="$TMPDIR_EVAL/x"
+mkdir -p "$HOME/.flow-agents"
+UNTRUSTED_CONF="$HOME/.flow-agents/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "4.1.0",
+  "version": "4.2.1",
   "description": "Flow Agents — a Kontour product that applies Flow and Veritas discipline as a portable process layer inside the agent tools you already use: Claude Code, Codex, Kiro, opencode, pi, and GitHub Actions — with framework adapters (AWS Strands preview) on the same policy-engine contract.",
   "keywords": [
     "agents",
@@ -152,6 +152,7 @@
   },
   "devDependencies": {
     "@types/node": "^26.1.1",
+    "gcp-metadata": "7.0.1",
     "promptfoo": "^0.121.18",
     "typescript": "^7.0.2"
   },

package/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/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/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) {