@indigoai-us/hq-cli 5.77.11 → 5.77.13

package/CHANGELOG.md

@@ -2,6 +2,52 @@
 
 ## [Unreleased]
 
+## [5.77.13]
+
+### Added
+
+- `hq outposts heartbeat` — the Outpost session-heartbeat runner. The unit on
+  every box invoked `outpost-session-heartbeat-runner`, a command that was
+  never written in any package, so each tick logged `command not found` behind
+  a `|| echo … continuing` while systemd and the box audit both reported
+  healthy. The enumeration and publisher modules existed in hq-pro (a server
+  repo) with no entrypoint; they move here and the cadence runs in-process —
+  no bash loop, no per-tick `npx …@latest`, no per-tick `hq auth refresh`.
+  That removes ~35k process launches per box per day. (#274)
+
+### Fixed
+
+- Heartbeat payloads no longer exceed the AWS IoT 128 KiB limit. A box with
+  9,340 transcripts produced ~1.9 MB and was rejected outright; `ended`
+  sessions are no longer published and the remainder is bounded by serialized
+  bytes, newest first, with `totalSessions`/`truncated` on the envelope so a
+  filtered list cannot read as a complete one. (#274)
+- Transcript bodies are read only for sessions that will be published — the
+  enumerator previously did a 16 KiB bounded read on every file before
+  filtering (~150 MB of disk per tick on a large box). (#274)
+- The no-secrets guard no longer matches ordinary paths. `sk-` and `asia` were
+  bare substrings, so a directory named `task-runner` or `flask-app` made the
+  guard throw and silently stopped the box reporting; markers are now
+  credential-shaped. (#274)
+- `nodeFileSystem.readDir` propagates operational errors instead of treating
+  every failure as an empty directory — an EACCES previously published an
+  empty session list and refreshed the liveness marker as if collection had
+  succeeded. (#274)
+- The realtime-credentials request is bounded, and the cadence sleep races the
+  abort signal so SIGTERM stops the loop cooperatively. (#274)
+- `vaultApiFetch` accepts an optional `baseUrl` so identity resolves against
+  the same control plane as the credentials fetch on non-default
+  deployments. (#274)
+
+## [5.77.12]
+
+### Added
+
+- `HQ_API_KEY` fail-closed consume path: `hqk_…` keys route `hq secrets get`
+  / `exec` / `env` through vault key fetch; Cognito-only commands hard-error.
+- `hq api-keys create --deploy-app` (repeatable) and deploy-app column in list
+  output for identity-bound deploy keys. (#270)
+
 ## [5.77.11]
 
 ### Fixed

package/dist/commands/api-keys.js

@@ -1,6 +1,11 @@
 import chalk from "chalk";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { assertCognitoOnlyCommand } from "../utils/resolve-vault-credential.js";
 import { getCompanyUid, vaultApiFetch } from "./secrets.js";
+async function requireCognitoForApiKeys(label) {
+    assertCognitoOnlyCommand(label);
+    return ensureCognitoToken();
+}
 function collectRepeatedOption(value, previous) {
     return [...previous, value];
 }
@@ -10,6 +15,11 @@ function formatMaybe(value) {
 function formatPrefixes(prefixes) {
     return prefixes.length > 0 ? prefixes.join(", ") : "-";
 }
+function formatDeployApps(deploy) {
+    if (!deploy?.apps?.length)
+        return "-";
+    return deploy.apps.join(", ");
+}
 function parsePermission(value) {
     if (value === "read" || value === "write" || value === "admin") {
         return value;
@@ -51,6 +61,7 @@ function renderApiKeysTable(apiKeys) {
         name: apiKey.name,
         permission: apiKey.scope.permission,
         prefixes: formatPrefixes(apiKey.scope.allowedPrefixes),
+        deployApps: formatDeployApps(apiKey.scope.deploy),
         status: apiKey.status,
         lastUsedAt: formatMaybe(apiKey.lastUsedAt),
         expiresAt: formatMaybe(apiKey.expiresAt),
@@ -59,6 +70,7 @@ function renderApiKeysTable(apiKeys) {
     const nameWidth = Math.max(4, ...rows.map((row) => row.name.length));
     const permissionWidth = Math.max(10, ...rows.map((row) => row.permission.length));
     const prefixesWidth = Math.max(8, ...rows.map((row) => row.prefixes.length));
+    const deployWidth = Math.max(6, ...rows.map((row) => row.deployApps.length));
     const statusWidth = Math.max(6, ...rows.map((row) => row.status.length));
     const lastUsedWidth = Math.max(11, ...rows.map((row) => row.lastUsedAt.length));
     const expiresWidth = Math.max(10, ...rows.map((row) => row.expiresAt.length));
@@ -67,6 +79,7 @@ function renderApiKeysTable(apiKeys) {
         "NAME".padEnd(nameWidth),
         "PERMISSION".padEnd(permissionWidth),
         "PREFIXES".padEnd(prefixesWidth),
+        "DEPLOY".padEnd(deployWidth),
         "STATUS".padEnd(statusWidth),
         "LAST USED".padEnd(lastUsedWidth),
         "EXPIRES".padEnd(expiresWidth),
@@ -78,6 +91,7 @@ function renderApiKeysTable(apiKeys) {
             row.name.padEnd(nameWidth),
             row.permission.padEnd(permissionWidth),
             row.prefixes.padEnd(prefixesWidth),
+            row.deployApps.padEnd(deployWidth),
             row.status.padEnd(statusWidth),
             row.lastUsedAt.padEnd(lastUsedWidth),
             row.expiresAt.padEnd(expiresWidth),
@@ -91,20 +105,21 @@ export function registerApiKeysCommand(program) {
         .option("--company <slug>", "Company slug (resolves to companyUid)");
     apiKeys
         .command("create")
-        .description("Create a new API key")
+        .description("Create a new API key (vault secrets and/or scoped deploy via --deploy-app)")
         .requiredOption("--name <label>", "Human-readable label for the API key")
-        .option("--scope <prefix>", "Allowed prefix (repeatable)", collectRepeatedOption, [])
-        .option("--permission <level>", "Permission level: read | write | admin", "read")
+        .option("--scope <prefix>", "Allowed secret prefix (repeatable)", collectRepeatedOption, [])
+        .option("--deploy-app <id>", "Deploy app id/slug allowed for publish (repeatable)", collectRepeatedOption, [])
+        .option("--permission <level>", "Secret permission level: read | write | admin (required when --scope is set)", "read")
         .option("--expires <ISO8601>", "Optional ISO-8601 expiry timestamp")
         .action(async (opts) => {
         try {
-            if (opts.scope.length === 0) {
-                console.error(chalk.red("Error: at least one --scope <prefix> is required."));
+            if (opts.scope.length === 0 && opts.deployApp.length === 0) {
+                console.error(chalk.red("Error: provide at least one --scope <prefix> and/or --deploy-app <id>."));
                 process.exit(1);
             }
             const permission = parsePermission(opts.permission);
             const expiresAt = parseExpires(opts.expires);
-            const token = await ensureCognitoToken();
+            const token = await requireCognitoForApiKeys("api-keys create");
             const companyUid = await getCompanyUid(token, apiKeys.opts().company);
             const res = await vaultApiFetch({
                 token,
@@ -113,8 +128,20 @@ export function registerApiKeysCommand(program) {
                 body: {
                     companyUid,
                     name: opts.name,
-                    allowedPrefixes: opts.scope,
-                    permission,
+                    ...(opts.scope.length > 0
+                        ? { allowedPrefixes: opts.scope, permission }
+                        : {}),
+                    ...(opts.deployApp.length > 0
+                        ? {
+                            deploy: {
+                                apps: opts.deployApp,
+                                capabilities: ["deploy:write"],
+                            },
+                        }
+                        : {}),
+                    ...(opts.scope.length === 0 && opts.deployApp.length > 0
+                        ? { permission }
+                        : {}),
                     ...(expiresAt ? { expiresAt } : {}),
                 },
             });
@@ -131,10 +158,26 @@ export function registerApiKeysCommand(program) {
             console.log(`  Company: ${data.apiKey.companyUid}`);
             console.log(`  Permission: ${data.apiKey.scope.permission}`);
             console.log(`  Prefixes: ${formatPrefixes(data.apiKey.scope.allowedPrefixes)}`);
+            console.log(`  Deploy apps: ${formatDeployApps(data.apiKey.scope.deploy)}`);
             console.log(`  Status: ${data.apiKey.status}`);
             console.log(`  Created: ${data.apiKey.createdAt}`);
             console.log(`  Last used: ${formatMaybe(data.apiKey.lastUsedAt)}`);
             console.log(`  Expires: ${formatMaybe(data.apiKey.expiresAt)}`);
+            console.log("");
+            console.log(chalk.bold("Usage"));
+            console.log("  This key acts as you (Cognito identity), limited to the scopes above.");
+            console.log("  Export it for automation (never falls back to a session):");
+            console.log(`\n  export HQ_API_KEY='${data.key.value}'\n`);
+            console.log("  Vault secrets:");
+            console.log("    hq secrets get <NAME> --reveal");
+            console.log("    hq secrets exec --only <NAME> -- <command>");
+            console.log("    Or HTTP: POST /v1/keys/secrets/fetch with Authorization: Bearer <key>");
+            if (data.apiKey.scope.deploy?.apps?.length) {
+                console.log("  Deploy (scoped apps only):");
+                console.log("    Authorization: Bearer <key> against the hq-deploy API");
+                console.log(chalk.dim("    Cannot change access-mode, password, or mint hqd_ keys."));
+            }
+            console.log(chalk.dim("  Unsupported under HQ_API_KEY: secrets list/set/share/acl (use a Cognito session)."));
         }
         catch (err) {
             console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
@@ -146,7 +189,7 @@ export function registerApiKeysCommand(program) {
         .description("List API keys for a company")
         .action(async () => {
         try {
-            const token = await ensureCognitoToken();
+            const token = await requireCognitoForApiKeys("api-keys list");
             const companyUid = await getCompanyUid(token, apiKeys.opts().company);
             const res = await vaultApiFetch({
                 token,
@@ -173,7 +216,7 @@ export function registerApiKeysCommand(program) {
         .description("Revoke an API key")
         .action(async (keyId) => {
         try {
-            const token = await ensureCognitoToken();
+            const token = await requireCognitoForApiKeys("api-keys revoke");
             const res = await vaultApiFetch({
                 token,
                 path: `/v1/api-keys/${encodeURIComponent(keyId)}/revoke`,

package/dist/commands/outposts-heartbeat.d.ts

@@ -0,0 +1,96 @@
+/**
+ * `hq outposts heartbeat` — publish this box's agent-session summary to the
+ * realtime fabric.
+ *
+ * Runs ON an Outpost, under systemd. It enumerates the box's local Claude Code
+ * and Codex sessions with cheap scandir + stat + bounded reads, projects them
+ * down to the compact secret-free `AgentSession[]` payload, and publishes to
+ * `hq/{personUid}/sessions` so Mission Control can see what the box is doing.
+ *
+ * ## Why the cadence lives in here
+ *
+ * The original box-side design was a bash `while` loop that, every 5 seconds,
+ * ran `hq auth refresh` and then `npx -y --package=@indigoai-us/hq-cloud@latest
+ * outpost-session-heartbeat-runner`. That is ~35k process launches a day, and
+ * every `npx` re-resolves the package and re-reads it off disk — on a t3 box
+ * whose EBS budget is the scarce resource, that is a meaningful, permanent tax
+ * for a job that should be nearly free.
+ *
+ * So the loop lives in-process instead:
+ *   - identity is resolved ONCE per process, not once per tick;
+ *   - the Cognito session refreshes itself on demand (`ensureCognitoToken`
+ *     returns the cached token until it is close to expiry), so there is no
+ *     separate per-tick `hq auth refresh`;
+ *   - the IoT client is cached across ticks by the publisher and only rebuilt
+ *     when its credentials near expiry.
+ *
+ * The loop is deliberately unkillable-by-transients: a failed publish, a failed
+ * enumeration, or a not-yet-warm session are all logged and retried on the next
+ * tick. Nothing here should ever take the service down, because a service that
+ * exits looks identical to a service that is quietly failing.
+ */
+import type { Command } from "commander";
+import { type FileSystemPort, type PublishPort, type SessionsHeartbeatPayload } from "../outpost/session-heartbeat.js";
+/** Everything the loop touches, injected so it is testable without a box. */
+export interface HeartbeatLoopDeps {
+    fs: FileSystemPort;
+    publish: PublishPort;
+    /** Resolve the caller's canonical `prs_*` id. Called once per process. */
+    getPersonUid: () => Promise<string>;
+    /**
+     * Wait between ticks. MUST return early when `signal` aborts — otherwise a
+     * SIGTERM arriving mid-sleep is not noticed until the full interval elapses,
+     * and systemd force-kills the process instead of it stopping cooperatively.
+     */
+    sleep: (ms: number, signal?: AbortSignal) => Promise<void>;
+    now: () => Date;
+    log: (line: string) => void;
+    /**
+     * Record that a heartbeat actually LANDED. Called only after a successful
+     * publish — never on failure, or the freshness signal it feeds would always
+     * read fresh and be worth nothing.
+     */
+    onPublished?: (payload: SessionsHeartbeatPayload) => Promise<void>;
+}
+export interface HeartbeatLoopOptions {
+    /** Emit a single heartbeat and return. */
+    once?: boolean;
+    /** Cadence between ticks. Defaults to {@link DEFAULT_HEARTBEAT_INTERVAL_SECONDS}. */
+    intervalSeconds?: number;
+    /** Home directory to scan (defaults to the process HOME). */
+    home?: string;
+    /** Print each published payload as JSON. */
+    json?: boolean;
+    /** Stop the loop cooperatively. */
+    signal?: AbortSignal;
+    /** Bound the loop — used by tests; production runs until aborted. */
+    maxTicks?: number;
+}
+/**
+ * Resolve the cadence from the flag, then the environment, then the default.
+ * Floored at 1s: a sub-second cadence hammers the fabric for no benefit, and a
+ * zero/negative value would spin the loop hot.
+ */
+export declare function resolveIntervalSeconds(flag: string | undefined, env?: NodeJS.ProcessEnv): number;
+/**
+ * Where the box records its last LANDED heartbeat. The post-provision audit
+ * reads this file's freshness, because "systemd says the unit is active" is not
+ * evidence that anything was published — that gap is what let a heartbeat fail
+ * every five seconds for nine days while every dashboard stayed green.
+ *
+ * Lives under the service user's home so the unit (User=ec2-user) can write it
+ * without extra tmpfiles.d wiring; the SSM collector reads it as root.
+ */
+export declare const DEFAULT_HEARTBEAT_STATE_FILE: string;
+/** Persist the liveness marker the box audit reads. */
+export declare function writeHeartbeatState(path: string, payload: SessionsHeartbeatPayload): Promise<void>;
+/**
+ * Run the heartbeat loop. Returns the number of ticks performed.
+ *
+ * A "tick" is one attempt, whether or not it published — the count is the
+ * loop's liveness, not its success rate.
+ */
+export declare function runHeartbeatLoop(options: HeartbeatLoopOptions, deps: HeartbeatLoopDeps): Promise<number>;
+/** Wire the production dependencies and register the subcommand. */
+export declare function registerHeartbeatCommand(outposts: Command): void;
+//# sourceMappingURL=outposts-heartbeat.d.ts.map

package/dist/commands/outposts-heartbeat.js

@@ -0,0 +1,188 @@
+/**
+ * `hq outposts heartbeat` — publish this box's agent-session summary to the
+ * realtime fabric.
+ *
+ * Runs ON an Outpost, under systemd. It enumerates the box's local Claude Code
+ * and Codex sessions with cheap scandir + stat + bounded reads, projects them
+ * down to the compact secret-free `AgentSession[]` payload, and publishes to
+ * `hq/{personUid}/sessions` so Mission Control can see what the box is doing.
+ *
+ * ## Why the cadence lives in here
+ *
+ * The original box-side design was a bash `while` loop that, every 5 seconds,
+ * ran `hq auth refresh` and then `npx -y --package=@indigoai-us/hq-cloud@latest
+ * outpost-session-heartbeat-runner`. That is ~35k process launches a day, and
+ * every `npx` re-resolves the package and re-reads it off disk — on a t3 box
+ * whose EBS budget is the scarce resource, that is a meaningful, permanent tax
+ * for a job that should be nearly free.
+ *
+ * So the loop lives in-process instead:
+ *   - identity is resolved ONCE per process, not once per tick;
+ *   - the Cognito session refreshes itself on demand (`ensureCognitoToken`
+ *     returns the cached token until it is close to expiry), so there is no
+ *     separate per-tick `hq auth refresh`;
+ *   - the IoT client is cached across ticks by the publisher and only rebuilt
+ *     when its credentials near expiry.
+ *
+ * The loop is deliberately unkillable-by-transients: a failed publish, a failed
+ * enumeration, or a not-yet-warm session are all logged and retried on the next
+ * tick. Nothing here should ever take the service down, because a service that
+ * exits looks identical to a service that is quietly failing.
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { DEFAULT_VAULT_API_URL } from "../utils/cognito-session.js";
+import { resolveCallerPersonUid } from "../utils/vault-api.js";
+import { DEFAULT_HEARTBEAT_INTERVAL_SECONDS, collectSessions, nodeFileSystem, sessionsTopicForPerson, } from "../outpost/session-heartbeat.js";
+import { createIotPublishPort, defaultRealtimeCredentialsFetcher, } from "../outpost/session-heartbeat-publisher.js";
+/**
+ * Resolve the cadence from the flag, then the environment, then the default.
+ * Floored at 1s: a sub-second cadence hammers the fabric for no benefit, and a
+ * zero/negative value would spin the loop hot.
+ */
+export function resolveIntervalSeconds(flag, env = process.env) {
+    for (const raw of [flag, env.OUTPOST_SESSIONS_HEARTBEAT_INTERVAL_SECONDS]) {
+        if (raw === undefined || raw === null || raw === "")
+            continue;
+        const parsed = Number.parseInt(raw, 10);
+        if (!Number.isFinite(parsed))
+            return DEFAULT_HEARTBEAT_INTERVAL_SECONDS;
+        return Math.max(1, parsed);
+    }
+    return DEFAULT_HEARTBEAT_INTERVAL_SECONDS;
+}
+/**
+ * Where the box records its last LANDED heartbeat. The post-provision audit
+ * reads this file's freshness, because "systemd says the unit is active" is not
+ * evidence that anything was published — that gap is what let a heartbeat fail
+ * every five seconds for nine days while every dashboard stayed green.
+ *
+ * Lives under the service user's home so the unit (User=ec2-user) can write it
+ * without extra tmpfiles.d wiring; the SSM collector reads it as root.
+ */
+export const DEFAULT_HEARTBEAT_STATE_FILE = join(homedir(), ".hq", "outpost-session-heartbeat.json");
+/** Persist the liveness marker the box audit reads. */
+export async function writeHeartbeatState(path, payload) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify({
+        lastPublishAt: payload.emittedAt,
+        sessions: payload.sessions.length,
+    })}\n`, "utf8");
+}
+/** Structured one-line log — journald gets JSON, not prose. */
+function logLine(step, outcome, extra, now) {
+    return JSON.stringify({
+        service: "outpost-session-heartbeat",
+        step,
+        outcome,
+        ...extra,
+        timestamp: now().toISOString(),
+    });
+}
+/**
+ * Run the heartbeat loop. Returns the number of ticks performed.
+ *
+ * A "tick" is one attempt, whether or not it published — the count is the
+ * loop's liveness, not its success rate.
+ */
+export async function runHeartbeatLoop(options, deps) {
+    const intervalMs = (options.intervalSeconds ?? DEFAULT_HEARTBEAT_INTERVAL_SECONDS) * 1000;
+    const maxTicks = options.once ? 1 : options.maxTicks;
+    // Resolved once and reused. Re-resolving per tick was the original sin.
+    let personUid = null;
+    let ticks = 0;
+    for (;;) {
+        ticks += 1;
+        try {
+            if (!personUid)
+                personUid = await deps.getPersonUid();
+            const payload = await collectSessions({ personUid, home: options.home, now: deps.now }, { fs: deps.fs });
+            const topic = sessionsTopicForPerson(personUid);
+            await deps.publish(topic, payload);
+            // Ordering matters: the marker is written only once the publish has
+            // resolved, so a stale marker means "nothing landed", not "nothing ran".
+            await deps.onPublished?.(payload);
+            if (options.json)
+                deps.log(JSON.stringify(payload));
+            deps.log(logLine("publish", "ok", { topic, sessions: payload.sessions.length }, deps.now));
+        }
+        catch (err) {
+            // Every failure mode lands here on purpose: a transient must never take
+            // the service down, because systemd restarting a hot-failing loop looks
+            // exactly like a healthy one.
+            deps.log(logLine("tick", "error", { message: err instanceof Error ? err.message : String(err) }, deps.now));
+        }
+        if (options.once)
+            break;
+        if (maxTicks !== undefined && ticks >= maxTicks)
+            break;
+        if (options.signal?.aborted)
+            break;
+        await deps.sleep(intervalMs, options.signal);
+        if (options.signal?.aborted)
+            break;
+    }
+    return ticks;
+}
+/** Wire the production dependencies and register the subcommand. */
+export function registerHeartbeatCommand(outposts) {
+    outposts
+        .command("heartbeat", { hidden: true })
+        .description("Publish this box's agent-session summary to the realtime fabric (runs on the Outpost, under systemd)")
+        .option("--once", "Emit a single heartbeat and exit")
+        .option("--interval <seconds>", "Cadence in seconds (default 5; env OUTPOST_SESSIONS_HEARTBEAT_INTERVAL_SECONDS)")
+        .option("--home <path>", "Home directory to scan for sessions")
+        .option("--api-base-url <url>", "HQ API base URL")
+        .option("--state-file <path>", `Liveness marker read by the box audit (default ${DEFAULT_HEARTBEAT_STATE_FILE})`)
+        .option("--json", "Print each published payload as JSON")
+        .action(async (opts) => {
+        const apiBaseUrl = opts.apiBaseUrl ??
+            process.env.HQAPI_BASE_URL ??
+            DEFAULT_VAULT_API_URL;
+        const getJwt = () => ensureCognitoToken({ interactive: false });
+        const deps = {
+            fs: nodeFileSystem,
+            publish: createIotPublishPort({
+                fetchCredentials: defaultRealtimeCredentialsFetcher({
+                    apiBaseUrl,
+                    getJwt,
+                }),
+            }),
+            // Same base as the credentials fetch. Resolving identity against the
+            // default plane while vending credentials from another sends a
+            // deployment-specific token to the wrong control plane, which is
+            // rejected — and the loop then retries forever without publishing.
+            getPersonUid: async () => resolveCallerPersonUid(await getJwt(), apiBaseUrl),
+            sleep: (ms, signal) => new Promise((resolve) => {
+                if (signal?.aborted)
+                    return resolve();
+                const t = setTimeout(done, ms);
+                function done() {
+                    clearTimeout(t);
+                    signal?.removeEventListener("abort", done);
+                    resolve();
+                }
+                signal?.addEventListener("abort", done, { once: true });
+            }),
+            now: () => new Date(),
+            log: (line) => console.error(line),
+            onPublished: (payload) => writeHeartbeatState(opts.stateFile ?? DEFAULT_HEARTBEAT_STATE_FILE, payload),
+        };
+        // systemd sends SIGTERM on stop/restart — finish the in-flight tick,
+        // then exit cleanly rather than being killed mid-publish.
+        const controller = new AbortController();
+        const stop = () => controller.abort();
+        process.once("SIGTERM", stop);
+        process.once("SIGINT", stop);
+        await runHeartbeatLoop({
+            once: opts.once,
+            intervalSeconds: resolveIntervalSeconds(opts.interval),
+            home: opts.home,
+            json: opts.json,
+            signal: controller.signal,
+        }, deps);
+    });
+}
+//# sourceMappingURL=outposts-heartbeat.js.map

package/dist/commands/outposts.js

@@ -31,6 +31,7 @@ import * as yaml from "js-yaml";
 import { loadCachedTokens } from "@indigoai-us/hq-cloud";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch } from "../utils/vault-api.js";
+import { registerHeartbeatCommand } from "./outposts-heartbeat.js";
 import { OUTPOST_PRICE_CENTS, confirmChargeOrExit, parseBillingPayload, surfaceBillingBlocked, } from "../utils/billing-gate.js";
 /** Decode hq-pro's `{ capped, limit, outposts }` cap envelope, if present. */
 export function parseCappedPayload(body) {
@@ -738,6 +739,8 @@ export function registerOutpostsCommand(program, selfDeployOverrides = {}) {
     const outposts = program
         .command("outposts")
         .description("Manage your personal HQ Outposts (EC2 boxes)");
+    // On-box session heartbeat (systemd). Hidden — operators never run it.
+    registerHeartbeatCommand(outposts);
     outposts
         .command("self-deploy", { hidden: true })
         .description("Configure this EC2 host as a locally self-hosted HQ outpost")