@indigoai-us/hq-cli 5.77.12 → 5.77.13

package/src/outpost/session-heartbeat-retain-guard.test.ts

@@ -0,0 +1,126 @@
+/**
+ * company-work-corpus US-006 AC7 — no retained MQTT publishes for transcript
+ * objects.
+ *
+ * Session transcripts are pulled on demand via the presign GET path (structural
+ * owner+creator gate); they are NEVER pushed as message bodies over the realtime
+ * fabric. The on-box sessions publisher emits only a COMPACT liveness heartbeat
+ * (`SessionsHeartbeatPayload` — path-only session summaries, guarded by
+ * `assertNoSecretsInPayload`), and it must publish NON-RETAINED so a stale
+ * summary is never re-delivered from the broker to a late subscriber.
+ *
+ * This is a GUARD suite: it asserts the current (correct) behavior so a future
+ * change that (a) turns on `retain` for the sessions topic, or (b) starts
+ * shipping transcript/vault-file bytes over MQTT, fails loudly. No product code
+ * change is expected from US-006 here.
+ */
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { readFileSync } from "node:fs";
+import { mockClient } from "aws-sdk-client-mock";
+import {
+  IoTDataPlaneClient,
+  PublishCommand,
+} from "@aws-sdk/client-iot-data-plane";
+import {
+  createIotPublishPort,
+  type RealtimeCredentialsResponse,
+} from "./session-heartbeat-publisher";
+import type { SessionsHeartbeatPayload } from "./session-heartbeat";
+
+const PERSON = "prs_alice";
+const TOPIC = `hq/${PERSON}/sessions`;
+const NOW = new Date("2026-07-11T18:55:00.000Z");
+
+function credsResponse(): RealtimeCredentialsResponse {
+  return {
+    credentials: {
+      accessKeyId: "ASIAEXAMPLE",
+      secretAccessKey: "secret",
+      sessionToken: "token",
+      expiration: new Date(NOW.getTime() + 3_600_000).toISOString(),
+    },
+    iotEndpoint: "abc123-ats.iot.us-east-1.amazonaws.com",
+    region: "us-east-1",
+    topic: TOPIC,
+    expiresAt: new Date(NOW.getTime() + 3_600_000).toISOString(),
+  };
+}
+
+function cleanPayload(): SessionsHeartbeatPayload {
+  return {
+    type: "sessions",
+    origin: "outpost",
+    emittedAt: NOW.toISOString(),
+    sessions: [
+      {
+        id: "x",
+        tool: "claude",
+        origin: "outpost",
+        cwd: "/home/ec2-user/hq",
+        project: "hq",
+        company: null,
+        model: "claude-opus-4",
+        status: "running",
+        startedAt: null,
+        lastActivityAt: NOW.toISOString(),
+        source: "/home/ec2-user/.claude/projects/p/x.jsonl",
+      },
+    ],
+  };
+}
+
+describe("US-006 AC7 — sessions heartbeat is published NON-RETAINED", () => {
+  const iotMock = mockClient(IoTDataPlaneClient);
+  beforeEach(() => iotMock.reset());
+
+  it("the PublishCommand never sets retain=true", async () => {
+    iotMock.on(PublishCommand).resolves({});
+    const publish = createIotPublishPort({
+      fetchCredentials: vi.fn().mockResolvedValue(credsResponse()),
+      makeClient: () => iotMock as unknown as IoTDataPlaneClient,
+      now: () => NOW,
+    });
+
+    await publish(TOPIC, cleanPayload());
+
+    const call = iotMock.commandCalls(PublishCommand)[0];
+    // retain must be absent or explicitly false — never true (no broker
+    // re-delivery of a stale session summary; transcripts are pull-only).
+    expect(call.args[0].input.retain).not.toBe(true);
+    // The wire body is the compact summary envelope — no transcript body field.
+    const sent = JSON.parse(
+      Buffer.from(call.args[0].input.payload as Uint8Array).toString("utf8"),
+    ) as Record<string, unknown> & {
+      sessions: Array<Record<string, unknown>>;
+    };
+    expect(sent.type).toBe("sessions");
+    // The session summary carries a `source` PATH only, never file/transcript
+    // content — assert no body/content/transcript key ever rides the wire.
+    for (const s of sent.sessions) {
+      expect(s).not.toHaveProperty("body");
+      expect(s).not.toHaveProperty("content");
+      expect(s).not.toHaveProperty("transcript");
+    }
+  });
+});
+
+describe("US-006 AC7 — static guard: sessions/realtime publishers never retain", () => {
+  // The sessions publisher is the ONLY realtime path in this package that
+  // touches session data, and it may never set retain=true — a retained
+  // message would leave the last session summary sitting on the broker after
+  // the box goes away. (The server-side DM-wake publisher is guarded by the
+  // matching test in hq-pro, which is where that file lives.)
+  const guardedSources = [
+    new URL("./session-heartbeat-publisher.ts", import.meta.url),
+    new URL("./session-heartbeat.ts", import.meta.url),
+  ];
+
+  it("no guarded publisher sets retain: true", () => {
+    for (const url of guardedSources) {
+      const src = readFileSync(url, "utf8");
+      // Tolerate any whitespace between `retain` and `true`.
+      expect(src).not.toMatch(/retain\s*:\s*true/);
+    }
+  });
+});

package/src/outpost/session-heartbeat.test.ts

@@ -0,0 +1,459 @@
+/**
+ * Tests for the Outpost on-box session heartbeat (mission-control US-009):
+ *   - enumeration → AgentSession[] mapping for Claude + Codex against an
+ *     in-memory fixture tree (origin=outpost, status derivation, field mapping)
+ *   - the no-secrets-in-payload guarantee (structural whitelist + value markers)
+ *   - bounded-read discipline (transcripts are never read in full)
+ *   - topic taxonomy + cadence resolution
+ *   - emitHeartbeatOnce publishes to hq/{personUid}/sessions and is non-fatal
+ */
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  assertNoSecretsInPayload,
+  collectSessions,
+  decodeClaudeProjectDir,
+  deriveStatus,
+  emitHeartbeatOnce,
+  parseCodexIndex,
+  resolveCadenceSeconds,
+  sessionsTopicForPerson,
+  toCompactSession,
+  type AgentSession,
+  type DirEntry,
+  type FileStat,
+  type FileSystemPort,
+  type HeartbeatConfig,
+  type SessionsHeartbeatPayload,
+} from "./session-heartbeat";
+
+// ---------------------------------------------------------------------------
+// In-memory filesystem fixture. Keys are absolute paths. Directories are
+// modeled implicitly by their children; files carry { content, stat }.
+// `readBounded` slices the content so we can assert the bounded-read contract.
+// ---------------------------------------------------------------------------
+
+interface MemFile {
+  content: string;
+  mtimeMs: number;
+  birthtimeMs: number;
+}
+
+class MemFs implements FileSystemPort {
+  files = new Map<string, MemFile>();
+  /** Records (path, maxBytes, from) of every readBounded call. */
+  boundedReads: Array<{ path: string; maxBytes: number; from: string }> = [];
+
+  addFile(path: string, content: string, mtimeMs: number, birthtimeMs?: number) {
+    this.files.set(path, {
+      content,
+      mtimeMs,
+      birthtimeMs: birthtimeMs ?? mtimeMs,
+    });
+  }
+
+  private childrenOf(dir: string): DirEntry[] {
+    const prefix = dir.endsWith("/") ? dir : dir + "/";
+    const names = new Map<string, { isFile: boolean; isDirectory: boolean }>();
+    for (const path of this.files.keys()) {
+      if (!path.startsWith(prefix)) continue;
+      const rest = path.slice(prefix.length);
+      const slash = rest.indexOf("/");
+      if (slash === -1) {
+        names.set(rest, { isFile: true, isDirectory: false });
+      } else {
+        const seg = rest.slice(0, slash);
+        if (!names.has(seg)) names.set(seg, { isFile: false, isDirectory: true });
+      }
+    }
+    return [...names.entries()].map(([name, kind]) => ({ name, ...kind }));
+  }
+
+  async readDir(path: string): Promise<DirEntry[]> {
+    return this.childrenOf(path);
+  }
+
+  async stat(path: string): Promise<FileStat> {
+    const f = this.files.get(path);
+    if (!f) throw new Error(`ENOENT: ${path}`);
+    return { mtimeMs: f.mtimeMs, birthtimeMs: f.birthtimeMs, size: f.content.length };
+  }
+
+  async readTextFile(path: string): Promise<string> {
+    const f = this.files.get(path);
+    if (!f) throw new Error(`ENOENT: ${path}`);
+    return f.content;
+  }
+
+  async readBounded(
+    path: string,
+    maxBytes: number,
+    from: "head" | "tail",
+  ): Promise<string> {
+    this.boundedReads.push({ path, maxBytes, from });
+    const f = this.files.get(path);
+    if (!f) return "";
+    if (f.content.length <= maxBytes) return f.content;
+    return from === "tail"
+      ? f.content.slice(f.content.length - maxBytes)
+      : f.content.slice(0, maxBytes);
+  }
+}
+
+const HOME = "/home/ec2-user";
+const PERSON = "prs_alice";
+const NOW = new Date("2026-06-15T18:55:00.000Z");
+const NOW_MS = NOW.getTime();
+
+function baseConfig(overrides: Partial<HeartbeatConfig> = {}): HeartbeatConfig {
+  return { personUid: PERSON, home: HOME, now: () => NOW, ...overrides };
+}
+
+describe("sessionsTopicForPerson", () => {
+  it("is the documented hq/{personUid}/sessions shape", () => {
+    expect(sessionsTopicForPerson(PERSON)).toBe(`hq/${PERSON}/sessions`);
+  });
+  it("throws on empty personUid", () => {
+    expect(() => sessionsTopicForPerson("")).toThrow();
+  });
+});
+
+describe("resolveCadenceSeconds", () => {
+  it("defaults to ~5s (matches desktop poll)", () => {
+    expect(resolveCadenceSeconds({})).toBe(5);
+  });
+  it("honors the env override", () => {
+    expect(
+      resolveCadenceSeconds({ OUTPOST_SESSIONS_HEARTBEAT_INTERVAL_SECONDS: "10" }),
+    ).toBe(10);
+  });
+  it("floors at 1s and ignores garbage", () => {
+    expect(
+      resolveCadenceSeconds({ OUTPOST_SESSIONS_HEARTBEAT_INTERVAL_SECONDS: "0" }),
+    ).toBe(5);
+    expect(
+      resolveCadenceSeconds({ OUTPOST_SESSIONS_HEARTBEAT_INTERVAL_SECONDS: "nope" }),
+    ).toBe(5);
+  });
+});
+
+describe("deriveStatus", () => {
+  it("running within the running window", () => {
+    expect(deriveStatus(NOW_MS - 5_000, NOW_MS)).toBe("running");
+  });
+  it("idle between running and idle windows", () => {
+    expect(deriveStatus(NOW_MS - 60_000, NOW_MS)).toBe("idle");
+  });
+  it("ended beyond the idle window", () => {
+    expect(deriveStatus(NOW_MS - 60 * 60_000, NOW_MS)).toBe("ended");
+  });
+});
+
+describe("decodeClaudeProjectDir", () => {
+  it("restores an abs cwd from Claude's dash encoding (no internal dashes)", () => {
+    expect(decodeClaudeProjectDir("-Users-corey-hq")).toBe("/Users/corey/hq");
+  });
+  it("is lossy when a real path segment itself contains a dash", () => {
+    // `ec2-user` is one segment but encodes the same as `ec2/user`; the decode
+    // cannot recover it. This is why the authoritative cwd comes from the
+    // sniffed transcript line, not the dir name — see the Claude enumeration
+    // test, where the sniffed cwd overrides this best-effort decode.
+    expect(decodeClaudeProjectDir("-home-ec2-user-hq")).toBe("/home/ec2/user/hq");
+  });
+});
+
+describe("parseCodexIndex", () => {
+  it("parses newline-delimited index records with field fallbacks", () => {
+    const text = [
+      JSON.stringify({
+        id: "11111111-1111-1111-1111-111111111111",
+        cwd: "/home/ec2-user/hq",
+        model: "gpt-5-codex",
+        timestamp: "2026-06-15T18:54:00.000Z",
+        path: "sessions/2026/06/15/rollout-x.jsonl",
+      }),
+      "garbage-not-json",
+      JSON.stringify({
+        session_id: "22222222-2222-2222-2222-222222222222",
+        cwd_path: "/tmp/proj",
+        model_slug: "o4-mini",
+        created_at: "2026-06-15T17:00:00.000Z",
+      }),
+    ].join("\n");
+    const recs = parseCodexIndex(text);
+    expect(recs).toHaveLength(2);
+    expect(recs[0].id).toBe("11111111-1111-1111-1111-111111111111");
+    expect(recs[0].model).toBe("gpt-5-codex");
+    expect(recs[1].id).toBe("22222222-2222-2222-2222-222222222222");
+    expect(recs[1].cwd).toBe("/tmp/proj");
+    expect(recs[1].model).toBe("o4-mini");
+  });
+});
+
+describe("collectSessions — Claude enumeration", () => {
+  it("maps a Claude transcript to an origin=outpost AgentSession with sniffed model+cwd", async () => {
+    const fs = new MemFs();
+    const uuid = "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee";
+    const dir = `${HOME}/.claude/projects/-home-ec2-user-hq`;
+    const content =
+      JSON.stringify({ cwd: "/home/ec2-user/hq", message: { model: "claude-opus-4" } }) +
+      "\n";
+    fs.addFile(`${dir}/${uuid}.jsonl`, content, NOW_MS - 3_000, NOW_MS - 120_000);
+
+    const payload = await collectSessions(baseConfig(), { fs });
+    expect(payload.origin).toBe("outpost");
+    expect(payload.type).toBe("sessions");
+    expect(payload.sessions).toHaveLength(1);
+    const s = payload.sessions[0];
+    expect(s).toMatchObject<Partial<AgentSession>>({
+      id: uuid,
+      tool: "claude",
+      origin: "outpost",
+      cwd: "/home/ec2-user/hq",
+      project: "hq",
+      model: "claude-opus-4",
+      status: "running",
+    });
+    expect(s.lastActivityAt).toBe(new Date(NOW_MS - 3_000).toISOString());
+    expect(s.startedAt).toBe(new Date(NOW_MS - 120_000).toISOString());
+    expect(s.source).toBe(`${dir}/${uuid}.jsonl`);
+  });
+
+  it("ignores non-uuid .jsonl files in a project dir", async () => {
+    const fs = new MemFs();
+    const dir = `${HOME}/.claude/projects/-home-ec2-user-hq`;
+    fs.addFile(`${dir}/not-a-session.jsonl`, "{}\n", NOW_MS);
+    fs.addFile(`${dir}/README.md`, "x", NOW_MS);
+    const payload = await collectSessions(baseConfig(), { fs });
+    expect(payload.sessions).toHaveLength(0);
+  });
+
+  it("only ever does a bounded TAIL read of a transcript (never a full slurp)", async () => {
+    const fs = new MemFs();
+    const uuid = "ffffffff-ffff-ffff-ffff-ffffffffffff";
+    const dir = `${HOME}/.claude/projects/-home-ec2-user-hq`;
+    // A "large" transcript — assert we never readTextFile it and the bounded
+    // read is capped + from the tail.
+    const big = "x".repeat(5_000_000);
+    fs.addFile(`${dir}/${uuid}.jsonl`, big, NOW_MS - 1000);
+    const readTextSpy = vi.spyOn(fs, "readTextFile");
+    await collectSessions(baseConfig(), { fs });
+    // readTextFile is reserved for the tiny Codex index — never a Claude transcript.
+    for (const call of readTextSpy.mock.calls) {
+      expect(call[0]).not.toContain(`${uuid}.jsonl`);
+    }
+    const boundedForBig = fs.boundedReads.filter((r) => r.path.includes(uuid));
+    expect(boundedForBig).toHaveLength(1);
+    expect(boundedForBig[0].from).toBe("tail");
+    expect(boundedForBig[0].maxBytes).toBeLessThanOrEqual(64 * 1024);
+  });
+});
+
+describe("collectSessions — Codex enumeration", () => {
+  it("maps an indexed Codex session, stat-ing the rollout for liveness", async () => {
+    const fs = new MemFs();
+    const id = "33333333-3333-3333-3333-333333333333";
+    fs.addFile(
+      `${HOME}/.codex/session_index.jsonl`,
+      JSON.stringify({
+        id,
+        cwd: "/tmp/proj",
+        model: "gpt-5-codex",
+        timestamp: "2026-06-15T10:00:00.000Z",
+        path: "sessions/2026/06/15/rollout-x.jsonl",
+      }) + "\n",
+      NOW_MS,
+    );
+    // The rollout's mtime — fresher than the index timestamp — wins for liveness.
+    fs.addFile(
+      `${HOME}/.codex/sessions/2026/06/15/rollout-x.jsonl`,
+      "rollout body that must NOT be read",
+      NOW_MS - 2_000,
+      NOW_MS - 200_000,
+    );
+    const payload = await collectSessions(baseConfig(), { fs });
+    const codex = payload.sessions.filter((s) => s.tool === "codex");
+    expect(codex).toHaveLength(1);
+    expect(codex[0]).toMatchObject<Partial<AgentSession>>({
+      id,
+      tool: "codex",
+      origin: "outpost",
+      cwd: "/tmp/proj",
+      project: "proj",
+      model: "gpt-5-codex",
+      status: "running",
+    });
+    expect(codex[0].lastActivityAt).toBe(new Date(NOW_MS - 2_000).toISOString());
+    expect(codex[0].source).toBe(
+      `${HOME}/.codex/sessions/2026/06/15/rollout-x.jsonl`,
+    );
+  });
+
+  it("discovers un-indexed rollouts by scandir+stat under sessions/YYYY/MM/DD", async () => {
+    const fs = new MemFs();
+    const id = "44444444-4444-4444-4444-444444444444";
+    fs.addFile(
+      `${HOME}/.codex/sessions/2026/06/15/rollout-2026-06-15-${id}.jsonl`,
+      "body",
+      NOW_MS - 30_000,
+    );
+    const payload = await collectSessions(baseConfig(), { fs });
+    const codex = payload.sessions.filter((s) => s.tool === "codex");
+    expect(codex).toHaveLength(1);
+    expect(codex[0].id).toBe(id);
+    expect(codex[0].status).toBe("idle");
+  });
+
+  it("never readTextFiles a rollout (only the tiny index)", async () => {
+    const fs = new MemFs();
+    fs.addFile(
+      `${HOME}/.codex/sessions/2026/06/15/rollout-x.jsonl`,
+      "huge body",
+      NOW_MS,
+    );
+    const spy = vi.spyOn(fs, "readTextFile");
+    await collectSessions(baseConfig(), { fs });
+    for (const call of spy.mock.calls) {
+      expect(call[0]).not.toContain("rollout-");
+    }
+  });
+});
+
+describe("no-secrets-in-payload guarantee", () => {
+  it("toCompactSession drops any non-whitelisted field (e.g. a leaked token)", () => {
+    const dirty = {
+      id: "x",
+      tool: "claude",
+      origin: "outpost",
+      cwd: "/p",
+      project: "p",
+      company: null,
+      model: "m",
+      status: "running",
+      startedAt: null,
+      lastActivityAt: null,
+      source: "/p/x.jsonl",
+      // adversarial extras that must NOT survive:
+      apiKey: "sk-ant-superSecret",
+      transcript: "user said the password is hunter2",
+      env: { AWS_SECRET_ACCESS_KEY: "abc" },
+    } as unknown as AgentSession;
+    const clean = toCompactSession(dirty);
+    expect(Object.keys(clean).sort()).toEqual(
+      [
+        "company",
+        "cwd",
+        "id",
+        "lastActivityAt",
+        "model",
+        "origin",
+        "project",
+        "source",
+        "startedAt",
+        "status",
+        "tool",
+      ].sort(),
+    );
+    expect(JSON.stringify(clean)).not.toContain("sk-ant-");
+    expect(JSON.stringify(clean)).not.toContain("hunter2");
+  });
+
+  it("assertNoSecretsInPayload throws on a non-whitelisted key", () => {
+    const payload = {
+      type: "sessions",
+      origin: "outpost",
+      emittedAt: NOW.toISOString(),
+      sessions: [
+        {
+          id: "x",
+          tool: "claude",
+          origin: "outpost",
+          cwd: "/p",
+          project: "p",
+          company: null,
+          model: "m",
+          status: "running",
+          startedAt: null,
+          lastActivityAt: null,
+          source: "/p/x.jsonl",
+          leaked: "sk-ant-nope",
+        },
+      ],
+    } as unknown as SessionsHeartbeatPayload;
+    expect(() => assertNoSecretsInPayload(payload)).toThrow(/non-whitelisted/);
+  });
+
+  it("assertNoSecretsInPayload throws when a whitelisted value looks like a secret", () => {
+    const payload: SessionsHeartbeatPayload = {
+      type: "sessions",
+      origin: "outpost",
+      emittedAt: NOW.toISOString(),
+      sessions: [
+        {
+          id: "x",
+          tool: "claude",
+          origin: "outpost",
+          cwd: "/p",
+          project: "p",
+          company: null,
+          // a model field that somehow carries a key — must be rejected
+          model: "sk-ant-api03-leak",
+          status: "running",
+          startedAt: null,
+          lastActivityAt: null,
+          source: "/p/x.jsonl",
+        },
+      ],
+    };
+    expect(() => assertNoSecretsInPayload(payload)).toThrow(/secret marker/);
+  });
+
+  it("a clean enumerated payload passes the guard end-to-end", async () => {
+    const fs = new MemFs();
+    const uuid = "aaaaaaaa-1111-2222-3333-444444444444";
+    const dir = `${HOME}/.claude/projects/-home-ec2-user-hq`;
+    // Even if the transcript tail carries a secret, it must NOT reach the payload
+    // because we only copy whitelisted fields (cwd/model are sniffed, not bodies).
+    fs.addFile(
+      `${dir}/${uuid}.jsonl`,
+      JSON.stringify({
+        cwd: "/home/ec2-user/hq",
+        message: { model: "claude-opus-4" },
+        apiKey: "sk-ant-this-should-never-leak",
+      }) + "\n",
+      NOW_MS - 1000,
+    );
+    const payload = await collectSessions(baseConfig(), { fs });
+    expect(() => assertNoSecretsInPayload(payload)).not.toThrow();
+    expect(JSON.stringify(payload)).not.toContain("sk-ant-");
+  });
+});
+
+describe("emitHeartbeatOnce", () => {
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+  beforeEach(() => {
+    warnSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+  });
+
+  it("publishes the payload to hq/{personUid}/sessions", async () => {
+    const fs = new MemFs();
+    const uuid = "55555555-5555-5555-5555-555555555555";
+    fs.addFile(
+      `${HOME}/.claude/projects/-home-ec2-user-hq/${uuid}.jsonl`,
+      "{}\n",
+      NOW_MS,
+    );
+    const publish = vi.fn().mockResolvedValue(undefined);
+    const payload = await emitHeartbeatOnce(baseConfig(), { fs, publish });
+    expect(publish).toHaveBeenCalledTimes(1);
+    expect(publish).toHaveBeenCalledWith(`hq/${PERSON}/sessions`, payload);
+    expect(payload.sessions[0].id).toBe(uuid);
+  });
+
+  it("is non-fatal: a publish failure is swallowed + logged, not thrown", async () => {
+    const fs = new MemFs();
+    const publish = vi.fn().mockRejectedValue(new Error("mqtt down"));
+    await expect(emitHeartbeatOnce(baseConfig(), { fs, publish })).resolves.toBeDefined();
+    expect(warnSpy).toHaveBeenCalled();
+  });
+});