@indigoai-us/hq-cli 5.77.11 → 5.77.13

package/dist/outpost/session-heartbeat.js

@@ -0,0 +1,657 @@
+/**
+ * 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";
+/**
+ * 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 = {
+    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 = 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 = [
+    // 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 },
+];
+/**
+ * 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;
+// ---------------------------------------------------------------------------
+// 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) {
+    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 = process.env) {
+    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, nowMs, thresholds = DEFAULT_LIVENESS_THRESHOLDS) {
+    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) {
+    // 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) {
+    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) {
+    let model = null;
+    let cwd = 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;
+        try {
+            obj = JSON.parse(trimmed);
+        }
+        catch {
+            continue; // partial last line from a tail read — skip
+        }
+        if (obj && typeof obj === "object") {
+            const rec = obj;
+            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.model;
+                if (typeof m === "string")
+                    model = m;
+            }
+        }
+        if (model && cwd)
+            break;
+    }
+    return { model, cwd };
+}
+async function enumerateClaude(fsp, home, nowMs, thresholds, resolveCompany) {
+    const root = join(home, ".claude", "projects");
+    const projectDirs = await fsp.readDir(root);
+    const out = [];
+    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;
+            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 = 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;
+/** Parse the small newline-delimited Codex index into records. */
+export function parseCodexIndex(text) {
+    const out = [];
+    for (const line of text.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith("{"))
+            continue;
+        let obj;
+        try {
+            obj = JSON.parse(trimmed);
+        }
+        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, home, nowMs, thresholds, resolveCompany) {
+    const codexRoot = join(home, ".codex");
+    const out = [];
+    const seen = new Set();
+    // 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();
+    // 1. Read the small index (whole-file read is safe — one line per session).
+    let indexRecords = [];
+    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;
+            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, baseRoot) {
+    const found = [];
+    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() {
+    // 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) {
+    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) {
+    for (const session of payload.sessions) {
+        const keys = Object.keys(session);
+        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, deps) {
+    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 = {
+        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, emittedAt) {
+    const sizeOf = (n) => 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, deps) {
+    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 = {
+    async readDir(path) {
+        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?.code;
+            if (code === "ENOENT" || code === "ENOTDIR")
+                return [];
+            throw err;
+        }
+    },
+    async stat(path) {
+        const st = await fs.stat(path);
+        return {
+            mtimeMs: st.mtimeMs,
+            birthtimeMs: st.birthtimeMs,
+            size: st.size,
+        };
+    },
+    async readTextFile(path) {
+        return fs.readFile(path, "utf8");
+    },
+    async readBounded(path, maxBytes, from) {
+        let handle = 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);
+        }
+    },
+};
+//# sourceMappingURL=session-heartbeat.js.map

package/dist/utils/resolve-vault-credential.d.ts

@@ -0,0 +1,30 @@
+/** Vault API keys issued by `hq api-keys create` (hq-pro). */
+export declare const HQ_API_KEY_PREFIX = "hqk_";
+export type VaultCredential = {
+    kind: "api-key";
+    token: string;
+} | {
+    kind: "cognito";
+    token: string;
+};
+/**
+ * Raw HQ_API_KEY from the environment, trimmed. Undefined when unset/empty.
+ * Does not validate prefix — use {@link resolveVaultCredential} for that.
+ */
+export declare function peekHqApiKey(): string | undefined;
+/**
+ * Resolve vault auth for CLI commands.
+ *
+ * When `HQ_API_KEY` is set it is authoritative: must be a vault key (`hqk_…`)
+ * and Cognito is never used as a fallback (fail-closed). When unset, uses the
+ * cached Cognito session (interactive login if needed).
+ */
+export declare function resolveVaultCredential(options?: {
+    interactive?: boolean;
+}): Promise<VaultCredential>;
+/**
+ * Throw when HQ_API_KEY is set but the command only supports Cognito sessions
+ * (list, set, ACL, api-keys admin, etc.).
+ */
+export declare function assertCognitoOnlyCommand(commandLabel: string): void;
+//# sourceMappingURL=resolve-vault-credential.d.ts.map