@indigoai-us/hq-cli 5.77.12 → 5.77.13

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

@@ -0,0 +1,195 @@
+/**
+ * Payload bounding for the Outpost session heartbeat.
+ *
+ * ## Why this exists
+ *
+ * The heartbeat enumerates every Claude transcript and Codex rollout on the
+ * box. On a long-lived Outpost that is an archive, not a status: the box this
+ * was first run against had **8,258 Claude transcripts and 1,082 Codex
+ * rollouts — 9,340 sessions — of which 15 had any activity in the last 15
+ * minutes.** Publishing all of them produced a payload of roughly 1.9 MB.
+ *
+ * AWS IoT Core rejects anything over 128 KB, so the very first real publish
+ * failed with `payload larger than 131072 bytes`. Every subsequent one would
+ * have too. The heartbeat is a liveness signal; it must carry what is live.
+ *
+ * Two rules, both tested here:
+ *   1. `ended` sessions are not published — they are history, and re-sending
+ *      thousands of them every five seconds is the bug.
+ *   2. Whatever survives that filter is still bounded by BYTES, because a busy
+ *      box could exceed the limit on live sessions alone. When the bound bites
+ *      it is reported, never silent — a truncated payload that looks complete
+ *      is how you get a wrong dashboard instead of a missing one.
+ */
+
+import { describe, expect, it } from "vitest";
+import {
+  DEFAULT_LIVENESS_THRESHOLDS,
+  IOT_PAYLOAD_BUDGET_BYTES,
+  collectSessions,
+  type DirEntry,
+  type FileStat,
+  type FileSystemPort,
+} from "./session-heartbeat.js";
+
+const NOW = new Date("2026-07-29T12:00:00.000Z");
+const NOW_MS = NOW.getTime();
+
+/**
+ * A fake Claude tree with `count` transcripts, each aged `ageSecondsFor(i)`.
+ * Codex enumeration sees an empty tree.
+ */
+function claudeTreeFs(
+  count: number,
+  ageSecondsFor: (i: number) => number,
+): FileSystemPort {
+  const names = Array.from(
+    { length: count },
+    (_, i) =>
+      `${i.toString(16).padStart(8, "0")}-aaaa-bbbb-cccc-dddddddddddd.jsonl`,
+  );
+  const ageOf = new Map<string, number>();
+  names.forEach((n, i) => ageOf.set(n, ageSecondsFor(i)));
+
+  return {
+    async readDir(path: string): Promise<DirEntry[]> {
+      if (path.endsWith("/.claude/projects")) {
+        return [{ name: "-home-ec2-user-hq", isDirectory: true, isFile: false }];
+      }
+      if (path.endsWith("/.claude/projects/-home-ec2-user-hq")) {
+        return names.map((name) => ({
+          name,
+          isDirectory: false,
+          isFile: true,
+        }));
+      }
+      return [];
+    },
+    async stat(path: string): Promise<FileStat> {
+      const name = path.split("/").pop() ?? "";
+      const age = ageOf.get(name) ?? 0;
+      const mtimeMs = NOW_MS - age * 1000;
+      return { mtimeMs, birthtimeMs: mtimeMs, size: 1024 };
+    },
+    async readTextFile() {
+      return "";
+    },
+    async readBounded() {
+      // A realistic cwd/model sniff, so each record is a realistic size.
+      return JSON.stringify({
+        cwd: "/home/ec2-user/hq/repos/private/some-longish-repo-name",
+        model: "claude-opus-4-8",
+      });
+    },
+  };
+}
+
+const config = { personUid: "prs_01TEST", home: "/home/ec2-user", now: () => NOW };
+
+describe("payload bounding", () => {
+  it("publishes live sessions and drops the ended archive", async () => {
+    // 500 sessions: the first 5 active, the rest ancient — the real shape of
+    // a box that has been running for weeks.
+    const fs = claudeTreeFs(500, (i) => (i < 5 ? 2 : 60 * 60 * 24 * 30));
+
+    const payload = await collectSessions(config, { fs });
+
+    expect(payload.sessions).toHaveLength(5);
+    expect(payload.sessions.every((s) => s.status !== "ended")).toBe(true);
+  });
+
+  it("reports how many sessions exist, not just how many it sent", async () => {
+    const fs = claudeTreeFs(500, (i) => (i < 5 ? 2 : 60 * 60 * 24 * 30));
+
+    const payload = await collectSessions(config, { fs });
+
+    // Silent filtering reads as "this box has 5 sessions". It has 500.
+    expect(payload.totalSessions).toBe(500);
+    expect(payload.sessions.length).toBeLessThan(payload.totalSessions);
+  });
+
+  it("keeps idle sessions — only `ended` is archive", async () => {
+    // 2s → running, 5min → idle, 30d → ended.
+    const fs = claudeTreeFs(3, (i) => [2, 300, 60 * 60 * 24 * 30][i]!);
+
+    const payload = await collectSessions(config, { fs });
+
+    const statuses = payload.sessions.map((s) => s.status).sort();
+    expect(statuses).toEqual(["idle", "running"]);
+  });
+
+  it("stays under the IoT limit even when every session is live", async () => {
+    // 5,000 sessions all active — the size bound, not the status filter, is
+    // what has to hold here.
+    const fs = claudeTreeFs(5000, () => 2);
+
+    const payload = await collectSessions(config, { fs });
+    const bytes = Buffer.byteLength(JSON.stringify(payload), "utf8");
+
+    expect(bytes).toBeLessThanOrEqual(IOT_PAYLOAD_BUDGET_BYTES);
+    // The real AWS IoT Core ceiling. The budget must leave headroom under it.
+    expect(bytes).toBeLessThan(131072);
+  });
+
+  it("flags truncation rather than quietly shortening the list", async () => {
+    const fs = claudeTreeFs(5000, () => 2);
+
+    const payload = await collectSessions(config, { fs });
+
+    expect(payload.truncated).toBe(true);
+    expect(payload.totalSessions).toBe(5000);
+    expect(payload.sessions.length).toBeLessThan(5000);
+  });
+
+  it("does not flag truncation when everything fits", async () => {
+    const fs = claudeTreeFs(3, () => 2);
+
+    const payload = await collectSessions(config, { fs });
+
+    expect(payload.truncated).toBe(false);
+    expect(payload.sessions).toHaveLength(3);
+    expect(payload.totalSessions).toBe(3);
+  });
+
+  it("reads transcript bodies ONLY for sessions it will publish", async () => {
+    // The enumerator statted every file AND did a 16 KiB bounded read on each,
+    // before anything was filtered. On the first real box that was 9,340 reads
+    // per tick, every 5 seconds — ~150 MB of disk for 15 useful records, on
+    // the exact resource that had already taken the machine down once.
+    const reads: string[] = [];
+    const base = claudeTreeFs(500, (i) => (i < 5 ? 2 : 60 * 60 * 24 * 30));
+    const fs: FileSystemPort = {
+      ...base,
+      async readBounded(path, maxBytes, from) {
+        reads.push(path);
+        return base.readBounded(path, maxBytes, from);
+      },
+    };
+
+    const payload = await collectSessions(config, { fs });
+
+    expect(payload.sessions).toHaveLength(5);
+    // Five live sessions ⇒ five reads, not five hundred.
+    expect(reads).toHaveLength(5);
+  });
+
+  it("keeps the MOST RECENTLY ACTIVE sessions when it has to choose", async () => {
+    // Index 0 is freshest, index N oldest — all still within `idle`.
+    const fs = claudeTreeFs(5000, (i) => 1 + i * (1 / 10));
+
+    const payload = await collectSessions(config, { fs });
+
+    expect(payload.truncated).toBe(true);
+    // Dropping the newest and keeping stale ones would make the live view
+    // wrong in the one way that matters.
+    const kept = payload.sessions
+      .map((s) => Date.parse(s.lastActivityAt!))
+      .sort((a, b) => a - b);
+    const oldestKept = kept[0]!;
+    const cutoff =
+      NOW_MS - DEFAULT_LIVENESS_THRESHOLDS.idleWithinSeconds * 1000;
+    expect(oldestKept).toBeGreaterThan(cutoff);
+    // The single freshest session must always survive.
+    expect(Math.max(...kept)).toBe(NOW_MS - 1000);
+  });
+});

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

@@ -0,0 +1,105 @@
+/**
+ * The no-secrets guard must catch credentials WITHOUT catching ordinary paths.
+ *
+ * Both halves matter equally, and the second is easy to get wrong. The guard
+ * throws, and a throw fails the whole tick — so a pattern that matches a
+ * legitimate directory name silently disables reporting for the entire box
+ * until that session ages out.
+ *
+ * The original marker list held `sk-` and `asia` as bare substrings. `sk-`
+ * matches `task-runner`, `flask-app`, `disk-usage`, `risk-model`. Anyone who
+ * created a repo with one of those names would have taken the heartbeat down
+ * across the box, with the service still reporting active — the exact failure
+ * shape this whole change exists to remove.
+ */
+
+import { describe, expect, it } from "vitest";
+import {
+  assertNoSecretsInPayload,
+  type AgentSession,
+  type SessionsHeartbeatPayload,
+} from "./session-heartbeat.js";
+
+function payloadWith(over: Partial<AgentSession>): SessionsHeartbeatPayload {
+  const session: AgentSession = {
+    id: "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
+    tool: "claude",
+    origin: "outpost",
+    cwd: "/home/ec2-user/hq",
+    project: "hq",
+    company: null,
+    model: "claude-opus-4-8",
+    status: "running",
+    startedAt: "2026-07-29T12:00:00.000Z",
+    lastActivityAt: "2026-07-29T12:00:00.000Z",
+    source: "/home/ec2-user/.claude/projects/-home-ec2-user-hq/x.jsonl",
+    ...over,
+  };
+  return {
+    type: "sessions",
+    origin: "outpost",
+    emittedAt: "2026-07-29T12:00:00.000Z",
+    sessions: [session],
+  };
+}
+
+describe("ordinary paths must never trip the guard", () => {
+  // Every one of these contains `sk-` or `asia` and would have thrown before.
+  const innocentPaths = [
+    "/home/ec2-user/hq/repos/private/task-runner",
+    "/home/ec2-user/hq/repos/public/flask-app",
+    "/home/ec2-user/hq/tools/disk-usage",
+    "/home/ec2-user/hq/models/risk-model",
+    "/home/ec2-user/hq/regions/asia-pacific",
+    "/home/ec2-user/hq/repos/private/password-manager",
+    "/home/ec2-user/hq/kiosk-display",
+  ];
+
+  for (const cwd of innocentPaths) {
+    it(`allows ${cwd.split("/").pop()}`, () => {
+      const project = cwd.split("/").pop()!;
+      expect(() =>
+        assertNoSecretsInPayload(payloadWith({ cwd, project, source: `${cwd}/s.jsonl` })),
+      ).not.toThrow();
+    });
+  }
+
+  it("allows a model id that merely starts with the letters sk", () => {
+    expect(() =>
+      assertNoSecretsInPayload(payloadWith({ model: "sk-lite-preview" })),
+    ).not.toThrow();
+  });
+});
+
+describe("real credentials must still be caught", () => {
+  const leaks: [string, Partial<AgentSession>][] = [
+    ["an Anthropic key", { model: "sk-ant-api03-AbCdEfGhIjKlMnOpQrStUv" }],
+    ["an OpenAI-style key", { model: "sk-AbCdEfGhIjKlMnOpQrStUvWxYz012345" }],
+    ["a long-lived AWS key id", { project: "AKIAIOSFODNN7EXAMPLE" }],
+    ["an STS temp key id", { project: "ASIAIOSFODNN7EXAMPLE" }],
+    ["a PEM private key", { cwd: "-----BEGIN RSA PRIVATE KEY-----" }],
+    ["an authorization header", { model: "authorization: xyz" }],
+    ["a bearer token", { model: "Bearer abcdefghijklmnop0123" }],
+    ["an instance token header", { project: "x-outpost-instance-token" }],
+    ["a refresh token field", { model: 'refresh_token="abc"' }],
+    ["a password field", { model: "password=hunter2" }],
+    ["a secret access key", { project: "secretaccesskey" }],
+    ["a session token", { project: "sessiontoken" }],
+  ];
+
+  for (const [what, over] of leaks) {
+    it(`rejects ${what}`, () => {
+      expect(() => assertNoSecretsInPayload(payloadWith(over))).toThrow(
+        /refusing to publish/,
+      );
+    });
+  }
+});
+
+describe("non-whitelisted fields are still rejected", () => {
+  it("refuses a payload carrying an extra field", () => {
+    const p = payloadWith({});
+    (p.sessions[0] as unknown as Record<string, unknown>).transcript = "secret";
+    expect(() => assertNoSecretsInPayload(p)).toThrow(/non-whitelisted/);
+  });
+});

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

@@ -0,0 +1,178 @@
+/**
+ * Tests for the on-box realtime publisher (mission-control US-009):
+ *   - defaultRealtimeCredentialsFetcher POSTs the box's JWT to
+ *     /v1/realtime/credentials and parses the response
+ *   - createIotPublishPort vends scoped creds, builds an IoT client, publishes
+ *     to the caller's topic, caches the client until near-expiry, and re-guards
+ *     the no-secrets contract at the transport boundary
+ */
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { mockClient } from "aws-sdk-client-mock";
+import {
+  IoTDataPlaneClient,
+  PublishCommand,
+} from "@aws-sdk/client-iot-data-plane";
+import {
+  createIotPublishPort,
+  defaultRealtimeCredentialsFetcher,
+  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-06-15T18:55:00.000Z");
+
+function credsResponse(
+  expiresInMs: number,
+): RealtimeCredentialsResponse {
+  return {
+    credentials: {
+      accessKeyId: "ASIAEXAMPLE",
+      secretAccessKey: "secret",
+      sessionToken: "token",
+      expiration: new Date(NOW.getTime() + expiresInMs).toISOString(),
+    },
+    iotEndpoint: "abc123-ats.iot.us-east-1.amazonaws.com",
+    region: "us-east-1",
+    topic: TOPIC,
+    expiresAt: new Date(NOW.getTime() + expiresInMs).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("defaultRealtimeCredentialsFetcher", () => {
+  it("POSTs the JWT to /v1/realtime/credentials and returns the parsed body", async () => {
+    const body = credsResponse(3_600_000);
+    const fetchImpl = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      statusText: "OK",
+      json: async () => body,
+    } as Response);
+    const fetcher = defaultRealtimeCredentialsFetcher({
+      apiBaseUrl: "https://hqapi.hq.computer",
+      getJwt: async () => "JWT123",
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+    const out = await fetcher();
+    expect(out).toEqual(body);
+    const [url, init] = fetchImpl.mock.calls[0];
+    expect(url).toBe("https://hqapi.hq.computer/v1/realtime/credentials");
+    expect(init.method).toBe("POST");
+    expect(init.headers.authorization).toBe("Bearer JWT123");
+  });
+
+  it("throws on a non-ok response", async () => {
+    const fetchImpl = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 403,
+      statusText: "Forbidden",
+      json: async () => ({}),
+    } as Response);
+    const fetcher = defaultRealtimeCredentialsFetcher({
+      apiBaseUrl: "https://hqapi.hq.computer",
+      getJwt: async () => "JWT",
+      fetchImpl: fetchImpl as unknown as typeof fetch,
+    });
+    await expect(fetcher()).rejects.toThrow(/403/);
+  });
+});
+
+describe("createIotPublishPort", () => {
+  const iotMock = mockClient(IoTDataPlaneClient);
+  beforeEach(() => iotMock.reset());
+
+  it("publishes the payload to the caller's topic via IoT", async () => {
+    iotMock.on(PublishCommand).resolves({});
+    const fetchCredentials = vi.fn().mockResolvedValue(credsResponse(3_600_000));
+    const publish = createIotPublishPort({
+      fetchCredentials,
+      makeClient: () => iotMock as unknown as IoTDataPlaneClient,
+      now: () => NOW,
+    });
+
+    const payload = cleanPayload();
+    await publish(TOPIC, payload);
+
+    const call = iotMock.commandCalls(PublishCommand)[0];
+    expect(call.args[0].input.topic).toBe(TOPIC);
+    const sent = JSON.parse(
+      Buffer.from(call.args[0].input.payload as Uint8Array).toString("utf8"),
+    );
+    expect(sent.type).toBe("sessions");
+    expect(sent.sessions[0].id).toBe("x");
+  });
+
+  it("caches the vended creds/client until near expiry, then re-vends", async () => {
+    iotMock.on(PublishCommand).resolves({});
+    const fetchCredentials = vi
+      .fn()
+      .mockResolvedValueOnce(credsResponse(3_600_000))
+      .mockResolvedValueOnce(credsResponse(3_600_000));
+    const publish = createIotPublishPort({
+      fetchCredentials,
+      makeClient: () => iotMock as unknown as IoTDataPlaneClient,
+      now: () => NOW,
+    });
+
+    await publish(TOPIC, cleanPayload());
+    await publish(TOPIC, cleanPayload());
+    // Second publish reuses the cached client — creds vended once.
+    expect(fetchCredentials).toHaveBeenCalledTimes(1);
+  });
+
+  it("re-vends when the cached creds are within the refresh skew of expiry", async () => {
+    iotMock.on(PublishCommand).resolves({});
+    const fetchCredentials = vi
+      .fn()
+      // expires in 30s — inside the 60s refresh skew, so every call re-vends
+      .mockResolvedValue(credsResponse(30_000));
+    const publish = createIotPublishPort({
+      fetchCredentials,
+      makeClient: () => iotMock as unknown as IoTDataPlaneClient,
+      now: () => NOW,
+    });
+    await publish(TOPIC, cleanPayload());
+    await publish(TOPIC, cleanPayload());
+    expect(fetchCredentials).toHaveBeenCalledTimes(2);
+  });
+
+  it("re-guards the no-secrets contract at the transport boundary", async () => {
+    iotMock.on(PublishCommand).resolves({});
+    const fetchCredentials = vi.fn().mockResolvedValue(credsResponse(3_600_000));
+    const publish = createIotPublishPort({
+      fetchCredentials,
+      makeClient: () => iotMock as unknown as IoTDataPlaneClient,
+      now: () => NOW,
+    });
+    const dirty = cleanPayload();
+    // Smuggle a secret into a whitelisted field — the publisher must refuse.
+    dirty.sessions[0].model = "sk-ant-leaked-key";
+    await expect(publish(TOPIC, dirty)).rejects.toThrow(/secret marker/);
+    expect(iotMock.commandCalls(PublishCommand)).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,186 @@
+/**
+ * Outpost on-box realtime publisher — mission-control US-009.
+ *
+ * The box already holds a Cognito session (seeded from the caller's refresh
+ * token in user-data, kept fresh by the box's auth timers — see provision.ts).
+ * This module turns that session into a `PublishPort` for the session-heartbeat
+ * emitter using the EXACT on-box credential pattern the rest of the realtime
+ * fabric uses (docs/realtime-fabric.md):
+ *
+ *   1. POST {HQAPI}/v1/realtime/credentials with the box's Cognito JWT.
+ *      The Lambda resolves the caller's `personUid` from the verified JWT
+ *      (never request input) and vends short-lived STS creds whose session
+ *      policy scopes `iot:Connect/Publish/...` to `hq/{personUid}/*` only.
+ *   2. SigV4-sign an IoT Data-plane publish with those creds to
+ *      `hq/{personUid}/sessions`.
+ *
+ * No new auth surface, no embedded long-lived key, no per-device cert — the
+ * per-identity STS session policy is the isolation boundary (US-010).
+ *
+ * The HTTP fetch + IoT client are injected so this is unit-testable without a
+ * live endpoint; `defaultRealtimeCredentialsFetcher` and the IoT publish are
+ * the production wiring.
+ */
+
+import {
+  IoTDataPlaneClient,
+  PublishCommand,
+} from "@aws-sdk/client-iot-data-plane";
+import type {
+  PublishPort,
+  SessionsHeartbeatPayload,
+} from "./session-heartbeat.js";
+import {
+  assertNoSecretsInPayload,
+  sessionsTopicForPerson,
+} from "./session-heartbeat.js";
+
+/** Shape returned by `POST /v1/realtime/credentials` (mirrors the handler). */
+export interface RealtimeCredentialsResponse {
+  credentials: {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken: string;
+    expiration: string;
+  };
+  iotEndpoint: string;
+  region: string;
+  /** The caller's own topic — `hq/{personUid}/...`. */
+  topic: string;
+  expiresAt: string;
+}
+
+/** Fetches scoped realtime credentials for the box. Injected for tests. */
+export type RealtimeCredentialsFetcher = () => Promise<RealtimeCredentialsResponse>;
+
+/** Ceiling on a single credentials request. */
+export const DEFAULT_CREDENTIALS_TIMEOUT_MS = 10_000;
+
+/**
+ * Build the production credentials fetcher. Reads the box's current Cognito
+ * id/access token via the injected `getJwt` and POSTs it to the
+ * realtime-credentials endpoint.
+ */
+export function defaultRealtimeCredentialsFetcher(opts: {
+  apiBaseUrl: string;
+  getJwt: () => Promise<string>;
+  fetchImpl?: typeof fetch;
+  /** Bound the request. Defaults to {@link DEFAULT_CREDENTIALS_TIMEOUT_MS}. */
+  timeoutMs?: number;
+}): RealtimeCredentialsFetcher {
+  const doFetch = opts.fetchImpl ?? fetch;
+  return async () => {
+    const jwt = await opts.getJwt();
+    const res = await doFetch(`${opts.apiBaseUrl}/v1/realtime/credentials`, {
+      method: "POST",
+      // Bounded. An endpoint that accepts the connection but never answers
+      // would otherwise park the tick forever: the loop stops beating, the
+      // liveness marker goes stale, and SIGTERM cannot finish the in-flight
+      // tick — a hang that reads exactly like a healthy quiet box.
+      signal: AbortSignal.timeout(
+        opts.timeoutMs ?? DEFAULT_CREDENTIALS_TIMEOUT_MS,
+      ),
+      headers: {
+        authorization: `Bearer ${jwt}`,
+        "content-type": "application/json",
+      },
+    });
+    if (!res.ok) {
+      throw new Error(
+        `realtime/credentials returned ${res.status} ${res.statusText}`,
+      );
+    }
+    return (await res.json()) as RealtimeCredentialsResponse;
+  };
+}
+
+/** A cached IoT client keyed by endpoint+creds so we don't rebuild per tick. */
+interface CachedClient {
+  client: IoTDataPlaneClient;
+  endpoint: string;
+  accessKeyId: string;
+  expiresAtMs: number;
+}
+
+/**
+ * Create a `PublishPort` that vends scoped creds (refreshing before expiry) and
+ * publishes the compact payload to the box's own sessions topic over MQTT/IoT.
+ *
+ * @param fetchCredentials  vends per-identity-scoped STS creds + IoT endpoint
+ * @param makeClient        builds an IoT client from creds (injected for tests)
+ * @param now               clock injection
+ */
+export function createIotPublishPort(opts: {
+  fetchCredentials: RealtimeCredentialsFetcher;
+  makeClient?: (args: {
+    endpoint: string;
+    region: string;
+    credentials: RealtimeCredentialsResponse["credentials"];
+  }) => IoTDataPlaneClient;
+  now?: () => Date;
+}): PublishPort {
+  const now = opts.now ?? (() => new Date());
+  const makeClient =
+    opts.makeClient ??
+    (({ endpoint, region, credentials }) => {
+      const url = endpoint.startsWith("http")
+        ? endpoint
+        : `https://${endpoint}`;
+      return new IoTDataPlaneClient({
+        endpoint: url,
+        region,
+        credentials: {
+          accessKeyId: credentials.accessKeyId,
+          secretAccessKey: credentials.secretAccessKey,
+          sessionToken: credentials.sessionToken,
+        },
+      });
+    });
+
+  let cached: CachedClient | null = null;
+  // Refresh creds this many ms before they actually expire so a publish never
+  // races expiry mid-flight.
+  const REFRESH_SKEW_MS = 60_000;
+
+  async function clientFor(): Promise<{
+    client: IoTDataPlaneClient;
+  }> {
+    const nowMs = now().getTime();
+    if (cached && cached.expiresAtMs - REFRESH_SKEW_MS > nowMs) {
+      return { client: cached.client };
+    }
+    const vended = await opts.fetchCredentials();
+    const client = makeClient({
+      endpoint: vended.iotEndpoint,
+      region: vended.region,
+      credentials: vended.credentials,
+    });
+    cached = {
+      client,
+      endpoint: vended.iotEndpoint,
+      accessKeyId: vended.credentials.accessKeyId,
+      expiresAtMs: Date.parse(vended.credentials.expiration),
+    };
+    return { client };
+  }
+
+  return async (
+    topic: string,
+    payload: SessionsHeartbeatPayload,
+  ): Promise<void> => {
+    // Re-guard at the transport boundary — a publisher must never ship a
+    // payload that fails the no-secrets contract, regardless of caller.
+    assertNoSecretsInPayload(payload);
+    const { client } = await clientFor();
+    await client.send(
+      new PublishCommand({
+        topic,
+        qos: 0,
+        payload: Buffer.from(JSON.stringify(payload)),
+      }),
+    );
+  };
+}
+
+/** Re-export for the runner so it imports one module. */
+export { sessionsTopicForPerson };