@indigoai-us/hq-cli 5.77.13 → 5.78.0

package/src/outpost/session-heartbeat.ts

@@ -1,877 +0,0 @@
-/**
- * Outpost on-box session heartbeat emitter — mission-control US-009.
- *
- * Runs ON the Outpost VM (not in a Lambda). On a fixed cadence it:
- *   1. enumerates the box's local Claude Code (`~/.claude/projects/**\/<uuid>.jsonl`)
- *      and Codex (`~/.codex/session_index.jsonl` + `sessions/YYYY/MM/DD/rollout-*.jsonl`)
- *      sessions using cheap scandir + stat + BOUNDED tail/head reads only —
- *      it NEVER full-parses a multi-MB transcript;
- *   2. summarizes them into a compact `AgentSession[]` payload with
- *      `origin="outpost"`, mirroring the local reader logic from US-002/US-003;
- *   3. publishes that payload to the realtime fabric topic `hq/{personUid}/sessions`
- *      using the same on-box credential pattern the rest of the box uses
- *      (a server-minted, per-identity-scoped STS session vended by
- *      `POST /v1/realtime/credentials`, then an MQTT-over-WSS publish).
- *
- * Security (US-009 acceptance): the payload carries ONLY the AgentSession
- * fields below — never a transcript body, prompt, token, API key, env var, or
- * credential. `assertNoSecretsInPayload` is the runtime guard, and the unit
- * tests assert the no-secrets-in-payload guarantee against adversarial
- * fixtures.
- *
- * This module is intentionally dependency-light and pure-logic where it can be:
- * the filesystem, clock, and publish transport are all injected so the
- * enumeration → payload mapping and the no-secrets guarantee are unit-testable
- * without a real VM, real MQTT, or real STS.
- */
-
-import { promises as fs } from "node:fs";
-import { join } from "node:path";
-import { homedir } from "node:os";
-
-// ---------------------------------------------------------------------------
-// AgentSession contract (US-001) — the canonical shape the desktop subscriber
-// (US-011) deserializes. Field names MUST match design.md exactly:
-//   id, tool, origin, cwd, project, company, model, status, startedAt,
-//   lastActivityAt, source.
-// ---------------------------------------------------------------------------
-
-/** Which agent tool produced the session. */
-export type AgentTool = "claude" | "codex";
-
-/** Where the session physically lives. The outpost emitter always emits `outpost`. */
-export type AgentOrigin = "local" | "outpost";
-
-/**
- * Session liveness taxonomy (US-001). Derived best-effort from a last-activity
- * mtime window. `awaiting_input` is not inferable from on-disk artifacts alone
- * on the box, so the emitter only ever produces `running | idle | ended`; the
- * desktop merges/cross-checks and may surface `awaiting_input` for local PIDs.
- */
-export type AgentStatus = "running" | "awaiting_input" | "idle" | "ended";
-
-/**
- * Unified, compact agent session summary. This is the ONLY shape that crosses
- * the wire — no transcript bodies, no secrets. Matches the Rust struct +
- * TS type defined in the hq-sync repo (US-001).
- */
-export interface AgentSession {
-  /** Stable session id (the `<uuid>` for Claude, the rollout/index id for Codex). */
-  id: string;
-  tool: AgentTool;
-  origin: AgentOrigin;
-  /** Working directory the session is running in, if known. */
-  cwd: string | null;
-  /** Project slug/name (last path segment of cwd, or decoded Claude project dir). */
-  project: string | null;
-  /** Owning company slug, if resolvable from HQ workspace metadata. */
-  company: string | null;
-  /** Model id last seen for the session, if observed in a bounded read. */
-  model: string | null;
-  status: AgentStatus;
-  /** ISO-8601 first-seen / creation time, if known. */
-  startedAt: string | null;
-  /** ISO-8601 last-activity time (file mtime is the liveness signal). */
-  lastActivityAt: string | null;
-  /** Provenance of this record — the on-box file we summarized. Path only, never content. */
-  source: string;
-}
-
-/** Liveness thresholds (seconds). Mirrors the desktop liveness engine (US-004). */
-export interface LivenessThresholds {
-  /** ≤ this since last activity ⇒ `running`. */
-  runningWithinSeconds: number;
-  /** ≤ this (and > running) ⇒ `idle`; beyond ⇒ `ended`. */
-  idleWithinSeconds: number;
-}
-
-/**
- * Default cadence matches the desktop polling interval (~5s). Configurable via
- * the `OUTPOST_SESSIONS_HEARTBEAT_INTERVAL_SECONDS` env var so dev/staging can
- * dial it without a rebuild — read by `resolveCadenceSeconds`.
- */
-export const DEFAULT_HEARTBEAT_INTERVAL_SECONDS = 5;
-
-/**
- * Default liveness windows. `running` ⇐ activity within the last 2 cadence
- * ticks (10s); `idle` out to 15m; older ⇒ `ended`. Kept generous so a session
- * mid-think between writes isn't flapped to `ended`.
- */
-export const DEFAULT_LIVENESS_THRESHOLDS: LivenessThresholds = {
-  runningWithinSeconds: 10,
-  idleWithinSeconds: 15 * 60,
-};
-
-/**
- * Bytes to read from the tail/head of a transcript when sniffing model/cwd.
- * A hard cap — we open, seek, read this many bytes, and close. A multi-MB
- * transcript is NEVER read in full (performance requirement, US-002/US-003).
- */
-const BOUNDED_READ_BYTES = 16 * 1024;
-
-/** Whitelist of AgentSession keys allowed on the wire. Any other key ⇒ reject. */
-const ALLOWED_PAYLOAD_KEYS: ReadonlySet<keyof AgentSession> = new Set([
-  "id",
-  "tool",
-  "origin",
-  "cwd",
-  "project",
-  "company",
-  "model",
-  "status",
-  "startedAt",
-  "lastActivityAt",
-  "source",
-]);
-
-/**
- * Patterns that, if seen in a VALUE, indicate a secret leaked into the payload.
- * Defense in depth — the real protection is that only whitelisted fields are
- * ever copied. Matched case-insensitively.
- *
- * These MUST be shaped, not bare substrings. The guard throws, and a throw
- * fails the whole tick, so a marker that matches an ordinary path silently
- * disables reporting for the entire box until that session ages out.
- *
- * The original list contained `sk-` and `asia` as plain substrings. `sk-`
- * matches `task-runner`, `flask-app`, `disk-usage`, `risk-model`; `asia`
- * matches any path with that string in it. One badly-named directory would
- * have taken the heartbeat down — in a change whose entire subject is failures
- * that report healthy. Every credential-shaped pattern below therefore
- * requires the key's actual body, not just its prefix.
- */
-const SECRET_VALUE_PATTERNS: readonly { label: string; re: RegExp }[] = [
-  // Anthropic: the `sk-ant-` prefix is distinctive enough on its own — no
-  // English word or path segment contains it — so match it bare. A length
-  // floor here would only create a way to miss a short or truncated key.
-  { label: "anthropic-key", re: /sk-ant-/i },
-  // OpenAI-style: sk- plus a long token body. `task-runner` cannot match:
-  // it needs 20+ token chars after the dash, and a word boundary before.
-  { label: "openai-key", re: /\bsk-[a-z0-9]{20,}\b/i },
-  // AWS key IDs are exactly AKIA/ASIA + 16 uppercase alphanumerics.
-  { label: "aws-access-key-id", re: /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/ },
-  { label: "aws-secret-access-key", re: /aws_secret_access_key/i },
-  { label: "aws-access-key-id-name", re: /aws_access_key_id/i },
-  { label: "pem-private-key", re: /-----begin[a-z ]*private key/i },
-  { label: "authorization-header", re: /authorization:\s*\S/i },
-  { label: "bearer-token", re: /\bbearer\s+[a-z0-9._-]{16,}/i },
-  { label: "instance-token", re: /x-outpost-instance-token/i },
-  { label: "refresh-token", re: /refresh[_-]?token["'\s:=]/i },
-  { label: "password", re: /password["'\s:=]/i },
-  { label: "secret-access-key", re: /secretaccesskey/i },
-  { label: "session-token", re: /sessiontoken/i },
-];
-
-// ---------------------------------------------------------------------------
-// Injected ports — keep the module pure + testable.
-// ---------------------------------------------------------------------------
-
-/** A directory entry as returned by the filesystem port. */
-export interface DirEntry {
-  name: string;
-  isDirectory: boolean;
-  isFile: boolean;
-}
-
-/** Minimal stat surface used by the enumerator. */
-export interface FileStat {
-  /** Last-modification time, ms since epoch. */
-  mtimeMs: number;
-  /** Birth/creation time, ms since epoch (may equal mtime on filesystems w/o btime). */
-  birthtimeMs: number;
-  size: number;
-}
-
-/**
- * Filesystem port — abstracts node:fs so tests drive an in-memory tree and the
- * real emitter uses `nodeFileSystem`. Every read here is bounded.
- */
-export interface FileSystemPort {
-  /** Returns [] when the dir is missing — enumeration must not throw on absence. */
-  readDir(path: string): Promise<DirEntry[]>;
-  stat(path: string): Promise<FileStat>;
-  /** Whole-file read — used ONLY for the tiny Codex index, never for transcripts. */
-  readTextFile(path: string): Promise<string>;
-  /**
-   * Bounded read: at most `maxBytes` from the END of the file (tail) or the
-   * START (head). Implementations MUST NOT load the whole file. Returns "" on
-   * any error (missing/locked) — enumeration is best-effort.
-   */
-  readBounded(
-    path: string,
-    maxBytes: number,
-    from: "head" | "tail",
-  ): Promise<string>;
-}
-
-/** Publishes the compact payload to the realtime topic. Injected for tests. */
-export type PublishPort = (
-  topic: string,
-  payload: SessionsHeartbeatPayload,
-) => Promise<void>;
-
-/** The full envelope published to `hq/{personUid}/sessions`. */
-export interface SessionsHeartbeatPayload {
-  /** Schema discriminator for the desktop subscriber. */
-  type: "sessions";
-  /** Always `outpost` from this emitter. */
-  origin: "outpost";
-  /** ISO-8601 emit time. */
-  emittedAt: string;
-  /** The compact session summaries — live only, newest first, size-bounded. */
-  sessions: AgentSession[];
-  /**
-   * How many sessions the box actually has on disk, including the `ended`
-   * archive that is deliberately not published. Present so a consumer can tell
-   * "this box has 15 sessions" from "this box has 9,340 and we sent the live
-   * 15" — a filtered list that looks complete is worse than no list.
-   */
-  totalSessions?: number;
-  /** True when the byte budget forced sessions to be dropped. */
-  truncated?: boolean;
-}
-
-/**
- * Serialized-payload ceiling, in bytes.
- *
- * AWS IoT Core hard-rejects publishes over 128 KiB (131,072) — the box's first
- * real heartbeat died on exactly that. This budget sits under it with headroom
- * for the envelope and for any field a future schema adds.
- */
-export const IOT_PAYLOAD_BUDGET_BYTES = 96 * 1024;
-
-export interface HeartbeatConfig {
-  /** Caller's canonical HQ person id (`prs_*`). Topic = `hq/{personUid}/sessions`. */
-  personUid: string;
-  /** Home directory to scan (defaults to the process HOME). */
-  home?: string;
-  /** Liveness thresholds (defaults to {@link DEFAULT_LIVENESS_THRESHOLDS}). */
-  thresholds?: LivenessThresholds;
-  /** Clock injection for deterministic tests. */
-  now?: () => Date;
-}
-
-export interface HeartbeatDeps {
-  fs: FileSystemPort;
-  publish: PublishPort;
-}
-
-// ---------------------------------------------------------------------------
-// Topic taxonomy — single source of truth (mirrors session-policy.ts's
-// dmTopicForPerson). Documented in docs/realtime-fabric.md.
-// ---------------------------------------------------------------------------
-
-/** The sessions topic for a person. `hq/{personUid}/sessions`. */
-export function sessionsTopicForPerson(personUid: string): string {
-  if (!personUid) {
-    throw new Error("sessionsTopicForPerson: personUid is required");
-  }
-  return `hq/${personUid}/sessions`;
-}
-
-/** Resolve the heartbeat cadence (seconds) from env, clamped to a sane floor. */
-export function resolveCadenceSeconds(
-  env: NodeJS.ProcessEnv = process.env,
-): number {
-  const raw = env.OUTPOST_SESSIONS_HEARTBEAT_INTERVAL_SECONDS;
-  const parsed = raw ? Number.parseInt(raw, 10) : NaN;
-  if (!Number.isFinite(parsed) || parsed <= 0) {
-    return DEFAULT_HEARTBEAT_INTERVAL_SECONDS;
-  }
-  // Floor at 1s — a sub-second cadence would hammer IoT with no benefit.
-  return Math.max(1, parsed);
-}
-
-// ---------------------------------------------------------------------------
-// Status derivation (US-004 parity).
-// ---------------------------------------------------------------------------
-
-/**
- * Map an mtime to a status given the thresholds and `now`. On the box we have
- * no per-session PID cross-check (that's the desktop's job), so we only emit
- * `running | idle | ended` — the desktop refines from there.
- */
-export function deriveStatus(
-  lastActivityMs: number,
-  nowMs: number,
-  thresholds: LivenessThresholds = DEFAULT_LIVENESS_THRESHOLDS,
-): AgentStatus {
-  const ageSeconds = (nowMs - lastActivityMs) / 1000;
-  if (ageSeconds <= thresholds.runningWithinSeconds) return "running";
-  if (ageSeconds <= thresholds.idleWithinSeconds) return "idle";
-  return "ended";
-}
-
-// ---------------------------------------------------------------------------
-// Claude Code enumeration.
-//   ~/.claude/projects/<encoded-cwd>/<uuid>.jsonl
-// The project dir name is the cwd with `/` → `-` (Claude's on-disk encoding).
-// We stat each .jsonl for mtime (liveness) and do ONE bounded tail read to
-// sniff the model — never a full parse.
-// ---------------------------------------------------------------------------
-
-const UUID_JSONL = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.jsonl$/i;
-
-/** Decode Claude's `-`-joined project dir back to a best-effort cwd. */
-export function decodeClaudeProjectDir(dirName: string): string {
-  // Claude encodes the abs cwd by replacing path separators with `-`, e.g.
-  // `/home/ec2-user/hq` → `-home-ec2-user-hq`. The transform is lossy (a real
-  // `-` in a path collides), so this is best-effort: restore leading slash and
-  // separators. The authoritative cwd, when present, comes from the transcript
-  // line itself (sniffed below).
-  const trimmed = dirName.replace(/^-/, "");
-  return "/" + trimmed.split("-").join("/");
-}
-
-/** Last path segment as a project name. */
-function projectFromCwd(cwd: string | null): string | null {
-  if (!cwd) return null;
-  const segs = cwd.split("/").filter(Boolean);
-  return segs.length ? segs[segs.length - 1] : null;
-}
-
-/** Pull the first `model` and `cwd` string from a small chunk of JSONL. */
-function sniffClaudeFields(chunk: string): {
-  model: string | null;
-  cwd: string | null;
-} {
-  let model: string | null = null;
-  let cwd: string | null = null;
-  // Bounded line walk — chunk is already capped at BOUNDED_READ_BYTES.
-  for (const line of chunk.split("\n")) {
-    const trimmed = line.trim();
-    if (!trimmed.startsWith("{")) continue;
-    let obj: unknown;
-    try {
-      obj = JSON.parse(trimmed);
-    } catch {
-      continue; // partial last line from a tail read — skip
-    }
-    if (obj && typeof obj === "object") {
-      const rec = obj as Record<string, unknown>;
-      if (!cwd && typeof rec.cwd === "string") cwd = rec.cwd;
-      if (!model && typeof rec.model === "string") model = rec.model;
-      const message = rec.message;
-      if (!model && message && typeof message === "object") {
-        const m = (message as Record<string, unknown>).model;
-        if (typeof m === "string") model = m;
-      }
-    }
-    if (model && cwd) break;
-  }
-  return { model, cwd };
-}
-
-async function enumerateClaude(
-  fsp: FileSystemPort,
-  home: string,
-  nowMs: number,
-  thresholds: LivenessThresholds,
-  resolveCompany: (cwd: string | null) => Promise<string | null>,
-): Promise<AgentSession[]> {
-  const root = join(home, ".claude", "projects");
-  const projectDirs = await fsp.readDir(root);
-  const out: AgentSession[] = [];
-
-  for (const projDir of projectDirs) {
-    if (!projDir.isDirectory) continue;
-    const projPath = join(root, projDir.name);
-    const decodedCwd = decodeClaudeProjectDir(projDir.name);
-    const files = await fsp.readDir(projPath);
-
-    for (const f of files) {
-      if (!f.isFile || !UUID_JSONL.test(f.name)) continue;
-      const filePath = join(projPath, f.name);
-      let stat: FileStat;
-      try {
-        stat = await fsp.stat(filePath);
-      } catch {
-        continue; // raced unlink — skip
-      }
-      const id = f.name.replace(/\.jsonl$/, "");
-      const status = deriveStatus(stat.mtimeMs, nowMs, thresholds);
-
-      // Sniff ONLY what we will publish. `ended` sessions are dropped from the
-      // payload downstream, so reading them is pure waste — and on a real box
-      // it is a LOT of waste: 9,340 transcripts × a 16 KiB bounded read is
-      // ~150 MB of disk per tick, every 5 seconds, on a machine whose disk
-      // throughput budget is the scarce resource. Statting is cheap; reading
-      // is not. This keeps the read count at the number of live sessions
-      // (~15) rather than the size of the archive.
-      let cwd = decodedCwd;
-      let model: string | null = null;
-      if (status !== "ended") {
-        // ONE bounded tail read to sniff model + authoritative cwd. Never a
-        // full parse — `readBounded` reads at most BOUNDED_READ_BYTES.
-        const tail = await fsp.readBounded(filePath, BOUNDED_READ_BYTES, "tail");
-        const sniffed = sniffClaudeFields(tail);
-        cwd = sniffed.cwd ?? decodedCwd;
-        model = sniffed.model;
-      }
-
-      out.push({
-        id,
-        tool: "claude",
-        origin: "outpost",
-        cwd,
-        project: projectFromCwd(cwd),
-        company: await resolveCompany(cwd),
-        model,
-        status,
-        startedAt: new Date(stat.birthtimeMs).toISOString(),
-        lastActivityAt: new Date(stat.mtimeMs).toISOString(),
-        source: filePath,
-      });
-    }
-  }
-  return out;
-}
-
-// ---------------------------------------------------------------------------
-// Codex enumeration.
-//   ~/.codex/session_index.jsonl   — newline-delimited index records
-//   ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl — per-session rollouts
-// The index is small (one line per session) so it's safe to read whole; the
-// rollouts are NOT — we only stat them for mtime and, when the index is
-// absent, scan the dated dirs by name + stat (never reading rollout bodies).
-//
-// Observed shapes (documented per the US-003 ask):
-//   index line:  { "id": "<uuid>", "cwd": "/abs/path", "model": "gpt-5-codex",
-//                  "timestamp": "2026-06-15T18:00:00Z", "path": "sessions/..." }
-//   rollout file name: rollout-<ISO-or-epoch>-<uuid>.jsonl
-// Field names vary across Codex versions; we read defensively and fall back to
-// the filename/dir structure when a field is missing.
-// ---------------------------------------------------------------------------
-
-const ROLLOUT_FILE = /^rollout-.*\.jsonl$/i;
-const UUID_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
-
-interface CodexIndexRecord {
-  id: string;
-  cwd: string | null;
-  model: string | null;
-  timestamp: string | null;
-  /** Relative path under ~/.codex, when the index records it. */
-  path: string | null;
-}
-
-/** Parse the small newline-delimited Codex index into records. */
-export function parseCodexIndex(text: string): CodexIndexRecord[] {
-  const out: CodexIndexRecord[] = [];
-  for (const line of text.split("\n")) {
-    const trimmed = line.trim();
-    if (!trimmed.startsWith("{")) continue;
-    let obj: Record<string, unknown>;
-    try {
-      obj = JSON.parse(trimmed) as Record<string, unknown>;
-    } catch {
-      continue;
-    }
-    const id =
-      (typeof obj.id === "string" && obj.id) ||
-      (typeof obj.session_id === "string" && obj.session_id) ||
-      (typeof obj.sessionId === "string" && obj.sessionId) ||
-      "";
-    if (!id) continue;
-    const cwd =
-      (typeof obj.cwd === "string" && obj.cwd) ||
-      (typeof obj.cwd_path === "string" && obj.cwd_path) ||
-      null;
-    const model =
-      (typeof obj.model === "string" && obj.model) ||
-      (typeof obj.model_slug === "string" && obj.model_slug) ||
-      null;
-    const timestamp =
-      (typeof obj.timestamp === "string" && obj.timestamp) ||
-      (typeof obj.updated_at === "string" && obj.updated_at) ||
-      (typeof obj.created_at === "string" && obj.created_at) ||
-      null;
-    const path = typeof obj.path === "string" ? obj.path : null;
-    out.push({ id, cwd, model, timestamp, path });
-  }
-  return out;
-}
-
-async function enumerateCodex(
-  fsp: FileSystemPort,
-  home: string,
-  nowMs: number,
-  thresholds: LivenessThresholds,
-  resolveCompany: (cwd: string | null) => Promise<string | null>,
-): Promise<AgentSession[]> {
-  const codexRoot = join(home, ".codex");
-  const out: AgentSession[] = [];
-  const seen = new Set<string>();
-  // Rollout file paths already covered by an index record — excluded from the
-  // dir walk so an indexed session isn't double-counted when its rollout
-  // filename carries no extractable UUID (e.g. `rollout-x.jsonl`).
-  const seenRolloutPaths = new Set<string>();
-
-  // 1. Read the small index (whole-file read is safe — one line per session).
-  let indexRecords: CodexIndexRecord[] = [];
-  try {
-    const indexText = await fsp.readTextFile(
-      join(codexRoot, "session_index.jsonl"),
-    );
-    indexRecords = parseCodexIndex(indexText);
-  } catch {
-    indexRecords = []; // no index — fall through to dir scan
-  }
-
-  for (const rec of indexRecords) {
-    // Liveness from the rollout file's mtime when we can locate it; else the
-    // index timestamp. We only ever STAT the rollout — never read its body.
-    let lastActivityMs = rec.timestamp ? Date.parse(rec.timestamp) : NaN;
-    let startedMs = lastActivityMs;
-    let source = join(codexRoot, "session_index.jsonl");
-    if (rec.path) {
-      const rolloutPath = join(codexRoot, rec.path);
-      // Mark covered regardless of stat success so the dir walk never
-      // re-emits this rollout as a separate session.
-      seenRolloutPaths.add(rolloutPath);
-      try {
-        const st = await fsp.stat(rolloutPath);
-        lastActivityMs = st.mtimeMs;
-        startedMs = st.birthtimeMs;
-        source = rolloutPath;
-      } catch {
-        // rollout missing — keep the index timestamp
-      }
-    }
-    if (!Number.isFinite(lastActivityMs)) lastActivityMs = nowMs;
-    if (!Number.isFinite(startedMs)) startedMs = lastActivityMs;
-    seen.add(rec.id);
-    out.push({
-      id: rec.id,
-      tool: "codex",
-      origin: "outpost",
-      cwd: rec.cwd,
-      project: projectFromCwd(rec.cwd),
-      company: await resolveCompany(rec.cwd),
-      model: rec.model,
-      status: deriveStatus(lastActivityMs, nowMs, thresholds),
-      startedAt: new Date(startedMs).toISOString(),
-      lastActivityAt: new Date(lastActivityMs).toISOString(),
-      source,
-    });
-  }
-
-  // 2. Walk sessions/YYYY/MM/DD/rollout-*.jsonl by NAME + STAT for any sessions
-  //    not covered by the index (and archived_sessions likewise). Never reads
-  //    rollout bodies — this is scandir + stat only.
-  for (const base of ["sessions", "archived_sessions"]) {
-    const baseRoot = join(codexRoot, base);
-    for (const rolloutPath of await walkRolloutFiles(fsp, baseRoot)) {
-      if (seenRolloutPaths.has(rolloutPath)) continue;
-      const idMatch = rolloutPath.match(UUID_RE);
-      const id = idMatch ? idMatch[0] : rolloutPath;
-      if (seen.has(id)) continue;
-      seen.add(id);
-      let st: FileStat;
-      try {
-        st = await fsp.stat(rolloutPath);
-      } catch {
-        continue;
-      }
-      out.push({
-        id,
-        tool: "codex",
-        origin: "outpost",
-        cwd: null,
-        project: null,
-        company: null,
-        model: null,
-        status: deriveStatus(st.mtimeMs, nowMs, thresholds),
-        startedAt: new Date(st.birthtimeMs).toISOString(),
-        lastActivityAt: new Date(st.mtimeMs).toISOString(),
-        source: rolloutPath,
-      });
-    }
-  }
-  return out;
-}
-
-/** Enumerate rollout-*.jsonl under sessions/YYYY/MM/DD (scandir only). */
-async function walkRolloutFiles(
-  fsp: FileSystemPort,
-  baseRoot: string,
-): Promise<string[]> {
-  const found: string[] = [];
-  const years = await fsp.readDir(baseRoot);
-  for (const y of years) {
-    if (!y.isDirectory) continue;
-    const months = await fsp.readDir(join(baseRoot, y.name));
-    for (const mo of months) {
-      if (!mo.isDirectory) continue;
-      const days = await fsp.readDir(join(baseRoot, y.name, mo.name));
-      for (const d of days) {
-        if (!d.isDirectory) continue;
-        const dayPath = join(baseRoot, y.name, mo.name, d.name);
-        const files = await fsp.readDir(dayPath);
-        for (const f of files) {
-          if (f.isFile && ROLLOUT_FILE.test(f.name)) {
-            found.push(join(dayPath, f.name));
-          }
-        }
-      }
-    }
-  }
-  return found;
-}
-
-// ---------------------------------------------------------------------------
-// Company resolution — best-effort from HQ workspace metadata. Mirrors the
-// local reader (US-002): a session whose HQ thread carries a company gets it
-// tagged. We read ONLY the small meta.yaml (bounded) — never session content.
-// On the box the workspace lives at ~/hq/workspace/sessions/<id>/meta.yaml, but
-// the cwd→company mapping isn't reliably derivable, so v1 returns null unless a
-// future enrichment hook is wired. Kept as an injectable seam.
-// ---------------------------------------------------------------------------
-
-function makeCompanyResolver(): (cwd: string | null) => Promise<string | null> {
-  // v1: no on-box cwd→company map. Returns null; the desktop enriches from its
-  // own HQ workspace metadata after merge. Isolated here so US-004/enrichment
-  // can swap it without touching the enumerators.
-  return async () => null;
-}
-
-// ---------------------------------------------------------------------------
-// Payload assembly + the no-secrets guarantee.
-// ---------------------------------------------------------------------------
-
-/**
- * Project an arbitrary session-like object down to EXACTLY the whitelisted
- * AgentSession fields. Any extra key (e.g. a transcript snippet, token, env
- * var) is dropped here — this is the structural half of the no-secrets
- * guarantee.
- */
-export function toCompactSession(s: AgentSession): AgentSession {
-  return {
-    id: s.id,
-    tool: s.tool,
-    origin: s.origin,
-    cwd: s.cwd ?? null,
-    project: s.project ?? null,
-    company: s.company ?? null,
-    model: s.model ?? null,
-    status: s.status,
-    startedAt: s.startedAt ?? null,
-    lastActivityAt: s.lastActivityAt ?? null,
-    source: s.source,
-  };
-}
-
-/**
- * Runtime guard: throw if the payload carries any non-whitelisted key OR any
- * value that looks like a secret. The behavioral half of the no-secrets
- * guarantee — defense in depth on top of `toCompactSession`. Called before
- * every publish.
- */
-export function assertNoSecretsInPayload(
-  payload: SessionsHeartbeatPayload,
-): void {
-  for (const session of payload.sessions) {
-    const keys = Object.keys(session) as (keyof AgentSession)[];
-    for (const key of keys) {
-      if (!ALLOWED_PAYLOAD_KEYS.has(key)) {
-        throw new Error(
-          `heartbeat payload contains non-whitelisted field "${String(key)}" — refusing to publish`,
-        );
-      }
-    }
-    for (const key of keys) {
-      const value = session[key];
-      if (typeof value !== "string") continue;
-      // The `source` field is a path and may legitimately contain a `-` etc.;
-      // still scan it — a path should never contain credential-shaped text.
-      for (const { label, re } of SECRET_VALUE_PATTERNS) {
-        if (re.test(value)) {
-          throw new Error(
-            `heartbeat payload field "${String(key)}" matched secret marker "${label}" — refusing to publish`,
-          );
-        }
-      }
-    }
-  }
-}
-
-/**
- * Enumerate the box's Claude + Codex sessions and build the compact,
- * secret-free payload. Pure w.r.t. the injected fs/clock — does NOT publish.
- */
-export async function collectSessions(
-  config: HeartbeatConfig,
-  deps: Pick<HeartbeatDeps, "fs">,
-): Promise<SessionsHeartbeatPayload> {
-  const now = config.now ?? (() => new Date());
-  const nowDate = now();
-  const nowMs = nowDate.getTime();
-  const home = config.home ?? homedir();
-  const thresholds = config.thresholds ?? DEFAULT_LIVENESS_THRESHOLDS;
-  const resolveCompany = makeCompanyResolver();
-
-  const [claude, codex] = await Promise.all([
-    enumerateClaude(deps.fs, home, nowMs, thresholds, resolveCompany),
-    enumerateCodex(deps.fs, home, nowMs, thresholds, resolveCompany),
-  ]);
-
-  // Project EVERY session through toCompactSession so nothing but the
-  // whitelisted fields can survive into the payload.
-  const all = [...claude, ...codex].map(toCompactSession);
-
-  // A long-lived box accumulates an ARCHIVE, not a status. The first box this
-  // ran against held 9,340 transcripts, 15 of them active — publishing the lot
-  // produced ~1.9 MB and AWS IoT rejected it outright. The heartbeat carries
-  // what is live; history is the vault's job, not a 5-second broadcast's.
-  const live = all
-    .filter((s) => s.status !== "ended")
-    .sort(
-      (a, b) =>
-        Date.parse(b.lastActivityAt ?? "") - Date.parse(a.lastActivityAt ?? ""),
-    );
-
-  const sessions = fitWithinBudget(live, nowDate.toISOString());
-
-  const payload: SessionsHeartbeatPayload = {
-    type: "sessions",
-    origin: "outpost",
-    emittedAt: nowDate.toISOString(),
-    sessions,
-    totalSessions: all.length,
-    truncated: sessions.length < live.length,
-  };
-  // Belt-and-suspenders: guard before the payload ever leaves the box.
-  assertNoSecretsInPayload(payload);
-  return payload;
-}
-
-/**
- * Trim a recency-sorted list until the serialized envelope fits the budget.
- *
- * Binary search rather than a per-item loop: a box with thousands of live
- * sessions would otherwise re-serialize the whole array on every step, and
- * this runs every 5 seconds on a machine whose CPU is not free.
- */
-function fitWithinBudget(
-  sorted: readonly AgentSession[],
-  emittedAt: string,
-): AgentSession[] {
-  const sizeOf = (n: number): number =>
-    Buffer.byteLength(
-      JSON.stringify({
-        type: "sessions",
-        origin: "outpost",
-        emittedAt,
-        sessions: sorted.slice(0, n),
-        totalSessions: sorted.length,
-        truncated: true,
-      }),
-      "utf8",
-    );
-
-  if (sizeOf(sorted.length) <= IOT_PAYLOAD_BUDGET_BYTES) {
-    return [...sorted];
-  }
-
-  let lo = 0;
-  let hi = sorted.length;
-  while (lo < hi) {
-    const mid = Math.ceil((lo + hi) / 2);
-    if (sizeOf(mid) <= IOT_PAYLOAD_BUDGET_BYTES) lo = mid;
-    else hi = mid - 1;
-  }
-  return sorted.slice(0, lo);
-}
-
-/**
- * One heartbeat tick: collect → guard → publish to `hq/{personUid}/sessions`.
- * Best-effort and non-fatal by contract — a publish failure must not crash the
- * box's heartbeat loop (the desktop falls back to the S3-vault heartbeat /
- * stale-timeout, US-011). Returns the payload that was published (or attempted)
- * so callers/tests can assert on it; re-throws nothing.
- */
-export async function emitHeartbeatOnce(
-  config: HeartbeatConfig,
-  deps: HeartbeatDeps,
-): Promise<SessionsHeartbeatPayload> {
-  const payload = await collectSessions(config, deps);
-  const topic = sessionsTopicForPerson(config.personUid);
-  try {
-    await deps.publish(topic, payload);
-  } catch (err) {
-    // Non-fatal: log + continue. The loop keeps the box reporting on the next
-    // tick; the desktop already handles a missed beat via its stale timeout.
-    console.error(
-      JSON.stringify({
-        service: "outpost-session-heartbeat",
-        step: "publish",
-        outcome: "error",
-        topic,
-        message: err instanceof Error ? err.message : String(err),
-        timestamp: new Date().toISOString(),
-      }),
-    );
-  }
-  return payload;
-}
-
-// ---------------------------------------------------------------------------
-// Real node:fs port — bounded reads use a positioned read, never a full slurp.
-// ---------------------------------------------------------------------------
-
-/** Production FileSystemPort backed by node:fs with bounded positioned reads. */
-export const nodeFileSystem: FileSystemPort = {
-  async readDir(path: string): Promise<DirEntry[]> {
-    try {
-      const entries = await fs.readdir(path, { withFileTypes: true });
-      return entries.map((e) => ({
-        name: e.name,
-        isDirectory: e.isDirectory(),
-        isFile: e.isFile(),
-      }));
-    } catch (err) {
-      // A MISSING directory is expected — a box with no Codex sessions has no
-      // ~/.codex — so that degrades to empty. Anything else (EACCES, EIO, a
-      // full disk) must propagate: swallowing it publishes an empty session
-      // list, logs success, and refreshes the liveness marker while collection
-      // has actually failed. That is the silent-success shape the audit check
-      // in this same change exists to catch, so it must not be reintroduced
-      // one layer down.
-      const code = (err as NodeJS.ErrnoException)?.code;
-      if (code === "ENOENT" || code === "ENOTDIR") return [];
-      throw err;
-    }
-  },
-  async stat(path: string): Promise<FileStat> {
-    const st = await fs.stat(path);
-    return {
-      mtimeMs: st.mtimeMs,
-      birthtimeMs: st.birthtimeMs,
-      size: st.size,
-    };
-  },
-  async readTextFile(path: string): Promise<string> {
-    return fs.readFile(path, "utf8");
-  },
-  async readBounded(
-    path: string,
-    maxBytes: number,
-    from: "head" | "tail",
-  ): Promise<string> {
-    let handle: Awaited<ReturnType<typeof fs.open>> | null = null;
-    try {
-      handle = await fs.open(path, "r");
-      const st = await handle.stat();
-      const size = st.size;
-      const length = Math.min(maxBytes, size);
-      const position = from === "tail" ? Math.max(0, size - length) : 0;
-      const buf = Buffer.allocUnsafe(length);
-      const { bytesRead } = await handle.read(buf, 0, length, position);
-      return buf.subarray(0, bytesRead).toString("utf8");
-    } catch {
-      return ""; // locked/missing ⇒ no sniff (best-effort)
-    } finally {
-      if (handle) await handle.close().catch(() => undefined);
-    }
-  },
-};