@indigoai-us/hq-cli 5.117.0 → 5.117.1

package/dist/lib/agent-kit/fallback.d.ts

@@ -0,0 +1,63 @@
+/**
+ * No-service-manager fallback for `hq agent kit install`.
+ *
+ * When systemd --user cannot be reached (no user session bus, permission
+ * refused) or launchd is unavailable, the kit is started as ONE detached
+ * `hq agent kit run all` supervisor with output appended to
+ * ~/.hq-agent/logs/kit.log and its pid recorded in ~/.hq-agent/kit.pid.
+ * `kit status` reads the pidfile; `kit uninstall` kills it and removes it.
+ */
+import type { ServiceHostPaths, ServiceSetResult } from "../service-manager/index.js";
+import type { AgentKitPaths } from "./paths.js";
+export declare const KIT_PID_NAME = "kit.pid";
+export declare const KIT_FALLBACK_LOG_NAME = "kit.log";
+export declare function kitPidPath(paths: Pick<AgentKitPaths, "agentDir">): string;
+export declare function kitFallbackLogPath(paths: Pick<AgentKitPaths, "logsDir">): string;
+/** True when an activation error means the service manager itself is unusable. */
+export declare function isServiceManagerUnavailable(error: string | undefined): boolean;
+/**
+ * Pick the fallback when activation was requested and the host has no service
+ * manager integration, or every failure is a service-manager-unavailable error.
+ */
+export declare function shouldUseFallback(result: ServiceSetResult, activate: boolean): boolean;
+export declare function readKitPid(paths: Pick<AgentKitPaths, "agentDir">): number | null;
+export type KillFn = (pid: number, signal?: NodeJS.Signals | 0) => boolean;
+export declare function isPidAlive(pid: number, kill?: KillFn): boolean;
+export interface FallbackStatus {
+    pidFile: string;
+    pid: number | null;
+    running: boolean;
+}
+export declare function fallbackStatus(paths: Pick<AgentKitPaths, "agentDir">, kill?: KillFn): FallbackStatus | null;
+/** Kill a recorded supervisor (if alive) and remove the pidfile. */
+export declare function stopFallback(paths: Pick<AgentKitPaths, "agentDir">, kill?: KillFn): {
+    pid: number | null;
+    killed: boolean;
+};
+export interface DetachedSpawn {
+    (cmd: string, args: string[], opts: {
+        detached: true;
+        stdio: ["ignore", number, number];
+        env: NodeJS.ProcessEnv;
+        cwd: string;
+    }): {
+        pid?: number;
+        unref(): void;
+    };
+}
+export declare function fallbackCommand(host: ServiceHostPaths): {
+    cmd: string;
+    args: string[];
+};
+/** crontab line that restarts the fallback supervisor after a reboot. */
+export declare function rebootCrontabLine(paths: Pick<AgentKitPaths, "agentDir" | "logsDir">, host: ServiceHostPaths): string;
+export declare function startFallback(paths: AgentKitPaths, host: ServiceHostPaths, deps?: {
+    spawn?: DetachedSpawn;
+    kill?: KillFn;
+    env?: NodeJS.ProcessEnv;
+}): {
+    pid: number;
+    logPath: string;
+    pidFile: string;
+};
+//# sourceMappingURL=fallback.d.ts.map

package/dist/lib/agent-kit/fallback.js

@@ -0,0 +1,129 @@
+/**
+ * No-service-manager fallback for `hq agent kit install`.
+ *
+ * When systemd --user cannot be reached (no user session bus, permission
+ * refused) or launchd is unavailable, the kit is started as ONE detached
+ * `hq agent kit run all` supervisor with output appended to
+ * ~/.hq-agent/logs/kit.log and its pid recorded in ~/.hq-agent/kit.pid.
+ * `kit status` reads the pidfile; `kit uninstall` kills it and removes it.
+ */
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { kitServiceEnv } from "./services.js";
+export const KIT_PID_NAME = "kit.pid";
+export const KIT_FALLBACK_LOG_NAME = "kit.log";
+export function kitPidPath(paths) {
+    return path.join(paths.agentDir, KIT_PID_NAME);
+}
+export function kitFallbackLogPath(paths) {
+    return path.join(paths.logsDir, KIT_FALLBACK_LOG_NAME);
+}
+const UNAVAILABLE_PATTERNS = [
+    /no user session bus/i,
+    /failed to connect to (?:user )?bus/i,
+    /DBUS_SESSION_BUS_ADDRESS/i,
+    /XDG_RUNTIME_DIR/i,
+    /permission denied/i,
+    /operation not permitted/i,
+    /access denied/i,
+    /\bENOENT\b/i,
+    /command not found|spawnSync \S+ ENOENT/i,
+    /launchctl bootstrap failed/i,
+    /System has not been booted with systemd/i,
+];
+/** True when an activation error means the service manager itself is unusable. */
+export function isServiceManagerUnavailable(error) {
+    if (!error)
+        return false;
+    return UNAVAILABLE_PATTERNS.some((re) => re.test(error));
+}
+/**
+ * Pick the fallback when activation was requested and the host has no service
+ * manager integration, or every failure is a service-manager-unavailable error.
+ */
+export function shouldUseFallback(result, activate) {
+    if (!activate)
+        return false;
+    if (result.platform === "other")
+        return true;
+    const failed = result.units.filter((u) => u.running === false);
+    return failed.length > 0 && failed.some((u) => isServiceManagerUnavailable(u.error));
+}
+export function readKitPid(paths) {
+    try {
+        const n = Number.parseInt(fs.readFileSync(kitPidPath(paths), "utf8").trim(), 10);
+        return Number.isInteger(n) && n > 0 ? n : null;
+    }
+    catch {
+        return null;
+    }
+}
+const defaultKill = (pid, signal) => process.kill(pid, signal);
+export function isPidAlive(pid, kill = defaultKill) {
+    try {
+        kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM: exists but owned by someone else — still alive.
+        return err?.code === "EPERM";
+    }
+}
+export function fallbackStatus(paths, kill) {
+    if (!fs.existsSync(kitPidPath(paths)))
+        return null;
+    const pid = readKitPid(paths);
+    return { pidFile: kitPidPath(paths), pid, running: pid !== null && isPidAlive(pid, kill) };
+}
+/** Kill a recorded supervisor (if alive) and remove the pidfile. */
+export function stopFallback(paths, kill = defaultKill) {
+    const pid = readKitPid(paths);
+    let killed = false;
+    if (pid !== null && isPidAlive(pid, kill)) {
+        try {
+            kill(pid, "SIGTERM");
+            killed = true;
+        }
+        catch {
+            killed = false;
+        }
+    }
+    fs.rmSync(kitPidPath(paths), { force: true });
+    return { pid, killed };
+}
+export function fallbackCommand(host) {
+    return { cmd: host.nodeBinary, args: [host.hqBinary, "agent", "kit", "run", "all"] };
+}
+/** crontab line that restarts the fallback supervisor after a reboot. */
+export function rebootCrontabLine(paths, host) {
+    const q = (v) => `'${v.replace(/'/g, `'\\''`)}'`;
+    const { cmd, args } = fallbackCommand(host);
+    return `@reboot HQ_AGENT_DIR=${q(paths.agentDir)} ${[cmd, ...args].map(q).join(" ")} >> ${q(kitFallbackLogPath(paths))} 2>&1`;
+}
+export function startFallback(paths, host, deps = {}) {
+    // Re-install replaces a running supervisor, like a unit restart.
+    stopFallback(paths, deps.kill);
+    fs.mkdirSync(paths.logsDir, { recursive: true, mode: 0o700 });
+    const logPath = kitFallbackLogPath(paths);
+    const fd = fs.openSync(logPath, "a", 0o600);
+    const doSpawn = deps.spawn ?? ((cmd, args, opts) => spawn(cmd, args, opts));
+    const { cmd, args } = fallbackCommand(host);
+    try {
+        const child = doSpawn(cmd, args, {
+            detached: true,
+            stdio: ["ignore", fd, fd],
+            env: { ...(deps.env ?? process.env), HOME: host.home, ...kitServiceEnv(paths) },
+            cwd: paths.agentDir,
+        });
+        if (!child.pid)
+            throw new Error(`could not start ${cmd} ${args.join(" ")}`);
+        child.unref();
+        fs.writeFileSync(kitPidPath(paths), `${child.pid}\n`, { mode: 0o600 });
+        return { pid: child.pid, logPath, pidFile: kitPidPath(paths) };
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+//# sourceMappingURL=fallback.js.map

package/dist/lib/agent-kit/run/inbox.d.ts

@@ -37,19 +37,31 @@ export interface InboxDeps {
     ack: boolean;
     getToken: () => Promise<string>;
     log: KitLogger;
-    fetchInbox?: (token: string) => Promise<{
-        status: number;
-        body: unknown;
-    }>;
+    fetchInbox?: (token: string) => Promise<InboxFetchResult>;
     ackItem?: (token: string, id: string) => Promise<number>;
     warmCache?: (token: string, agentUid: string) => Promise<unknown>;
     sleep?: (ms: number) => Promise<void>;
     maxPolls?: number;
 }
-export declare function defaultFetchInbox(agentUid: string, apiBaseUrl: string): (token: string) => Promise<{
+export declare const INBOX_ERROR_BODY_MAX = 300;
+export interface InboxFetchResult {
     status: number;
     body: unknown;
-}>;
+    /** Full request URL (never carries credentials). */
+    url?: string;
+    /** Raw response text, truncated to INBOX_ERROR_BODY_MAX chars. */
+    bodyText?: string;
+}
+/**
+ * Join apiBaseUrl (from machine-creds.json) with the agent inbox route.
+ * `new URL("/v1/…", base)` would silently drop a base path such as an API
+ * Gateway stage (`…/prod`), and a base that already ends in `/v1` must not
+ * become `/v1/v1`. Trailing slashes are tolerated.
+ */
+export declare function agentApiUrl(apiBaseUrl: string, route: string): string;
+export declare function agentInboxUrl(apiBaseUrl: string, agentUid: string): string;
+export declare function truncateBody(text: string, max?: number): string;
+export declare function defaultFetchInbox(agentUid: string, apiBaseUrl: string): (token: string) => Promise<InboxFetchResult>;
 export declare function defaultAckItem(agentUid: string, apiBaseUrl: string): (token: string, id: string) => Promise<number>;
 export declare function pollInboxOnce(deps: InboxDeps): Promise<{
     ok: boolean;

package/dist/lib/agent-kit/run/inbox.js

@@ -60,15 +60,45 @@ export function mirrorInboxItem(paths, item) {
     fs.appendFileSync(path.join(paths.inboxDir, INBOX_JSONL_NAME), `${JSON.stringify({ id: item.id, mirroredAt: new Date().toISOString(), ...item.raw })}\n`, { mode: 0o600 });
     return dest;
 }
+export const INBOX_ERROR_BODY_MAX = 300;
+/**
+ * Join apiBaseUrl (from machine-creds.json) with the agent inbox route.
+ * `new URL("/v1/…", base)` would silently drop a base path such as an API
+ * Gateway stage (`…/prod`), and a base that already ends in `/v1` must not
+ * become `/v1/v1`. Trailing slashes are tolerated.
+ */
+export function agentApiUrl(apiBaseUrl, route) {
+    const base = new URL(apiBaseUrl);
+    let prefix = base.pathname.replace(/\/+$/, "");
+    const suffix = route.startsWith("/") ? route : `/${route}`;
+    if (prefix.endsWith("/v1") && suffix.startsWith("/v1/"))
+        prefix = prefix.slice(0, -3);
+    return `${base.origin}${prefix}${suffix}`;
+}
+export function agentInboxUrl(apiBaseUrl, agentUid) {
+    return agentApiUrl(apiBaseUrl, `/v1/agents/${encodeURIComponent(agentUid)}/inbox`);
+}
+export function truncateBody(text, max = INBOX_ERROR_BODY_MAX) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
 export function defaultFetchInbox(agentUid, apiBaseUrl) {
     return async (token) => {
+        const url = new URL(agentInboxUrl(apiBaseUrl, agentUid));
         const res = await vaultApiFetch({
             token,
-            baseUrl: apiBaseUrl,
-            path: `/v1/agents/${encodeURIComponent(agentUid)}/inbox`,
+            baseUrl: url.origin,
+            path: url.pathname,
         });
-        const body = await res.json().catch(() => ({}));
-        return { status: res.status, body };
+        const text = await res.text().catch(() => "");
+        let body;
+        try {
+            body = text ? JSON.parse(text) : {};
+        }
+        catch {
+            body = {};
+        }
+        return { status: res.status, body, url: url.toString(), bodyText: truncateBody(text) };
     };
 }
 export function defaultAckItem(agentUid, apiBaseUrl) {
@@ -101,12 +131,14 @@ export async function pollInboxOnce(deps) {
     }
     catch (err) {
         writeComponentStatus(deps.paths, "inbox", "error");
-        deps.log("error", `inbox fetch failed: ${err instanceof Error ? err.message : String(err)}`);
+        deps.log("error", `inbox fetch failed: GET ${agentInboxUrl(deps.apiBaseUrl, deps.agentUid)}: ${err instanceof Error ? err.message : String(err)}`);
         return { ok: false, mirrored: 0 };
     }
     if (res.status !== 200) {
         writeComponentStatus(deps.paths, "inbox", "error");
-        deps.log("warn", `inbox poll ${res.status}`);
+        const url = res.url ?? agentInboxUrl(deps.apiBaseUrl, deps.agentUid);
+        const bodyText = truncateBody(res.bodyText ?? (res.body === undefined ? "" : JSON.stringify(res.body)));
+        deps.log("warn", `inbox poll GET ${url} → ${res.status}${bodyText ? ` body=${bodyText}` : ""}`);
         return { ok: false, mirrored: 0 };
     }
     writeComponentStatus(deps.paths, "inbox", "ok");

package/dist/lib/agent-kit/run/mesh-listener.d.ts

@@ -3,25 +3,39 @@
  *
  * Policy hq-work-mesh-source-of-truth: the work mesh (REST) is the source of
  * truth; MQTT carries IDS-ONLY doorbells on the agent's personal topics
- * `hq/{agt_*}/{dm,work,sessions,notifications}`. This listener is the cache
+ * `hq/{agt_*}/{dm,work,sessions,notifications,inbox}`. This listener is the cache
  * writer: on any doorbell it refetches through the REST API into
  * ~/.hq/work-mesh/cache (warmMeshConversationCache) — message bodies are
  * never taken from MQTT. A periodic refresh covers missed doorbells.
  *
- * Credentials come from the same contract-3 vend the mesh daemon uses
- * (POST /v1/realtime/credentials); the WSS URL is SigV4-presigned. The
+ * Credentials come from the contract-2 (personal) vend
+ * (POST /v1/realtime/credentials {contractVersion: 2}), whose STS policy grants
+ * the caller's own `hq/{uid}/*` topics. The contract-3 vend the presence daemon
+ * uses only grants company presence + thread-directory topics, so subscribing
+ * to personal doorbells with it made AWS IoT drop the connection before SUBACK.
+ * Only doorbell topics the vend advertises are subscribed (one ungranted topic
+ * in a SUBSCRIBE disconnects the whole client). An `inbox` doorbell triggers
+ * an immediate inbox poll via `onInboxDoorbell`. The WSS URL is SigV4-presigned. The
  * connection is rebuilt before the vended credentials expire. `component-mesh`
  * is stamped ok while subscribed and refreshing, error otherwise.
  */
 import { type IClientOptions } from "mqtt";
-import { type CredentialsFetcher } from "../../mesh/live/daemon/credentials.js";
+import { type PersonalCredentialsFetcher, type PersonalRealtimeBundle } from "../../mesh/live/daemon/credentials.js";
 import type { KitLogger } from "../log.js";
 import type { AgentKitPaths } from "../paths.js";
-export declare const DOORBELL_KINDS: readonly ["dm", "work", "sessions", "notifications"];
+export declare const DOORBELL_KINDS: readonly ["dm", "work", "sessions", "notifications", "inbox"];
 export declare const DOORBELL_DEBOUNCE_MS = 2000;
 export declare const RECONNECT_BASE_MS = 1000;
 export declare const RECONNECT_MAX_MS = 60000;
 export declare function doorbellTopics(actorUid: string): string[];
+/**
+ * Doorbell topics this session may subscribe to: the intersection of
+ * DOORBELL_KINDS with the personal topics the vend advertises. AWS IoT
+ * disconnects the client on any unauthorized topic in a SUBSCRIBE, so a kind
+ * the server does not (yet) grant is skipped rather than risked.
+ */
+export declare function grantedDoorbellTopics(bundle: Pick<PersonalRealtimeBundle, "actorUid" | "topics">): string[];
+export declare function isInboxDoorbell(topic: string): boolean;
 /** Minimal mqtt client surface the listener needs (test seam). */
 export interface DoorbellMqttClient {
     on(event: string, handler: (...args: any[]) => void): unknown;
@@ -38,7 +52,9 @@ export interface MeshListenerDeps {
     refreshMs: number;
     getToken: () => Promise<string>;
     log: KitLogger;
-    fetchCredentials?: CredentialsFetcher;
+    fetchCredentials?: PersonalCredentialsFetcher;
+    /** Called immediately (not debounced) when an `hq/{uid}/inbox` doorbell rings. */
+    onInboxDoorbell?: () => Promise<unknown> | void;
     connect?: DoorbellConnectFn;
     refetch?: (token: string, actorUid: string) => Promise<unknown>;
     now?: () => Date;

package/dist/lib/agent-kit/run/mesh-listener.js

@@ -3,28 +3,47 @@
  *
  * Policy hq-work-mesh-source-of-truth: the work mesh (REST) is the source of
  * truth; MQTT carries IDS-ONLY doorbells on the agent's personal topics
- * `hq/{agt_*}/{dm,work,sessions,notifications}`. This listener is the cache
+ * `hq/{agt_*}/{dm,work,sessions,notifications,inbox}`. This listener is the cache
  * writer: on any doorbell it refetches through the REST API into
  * ~/.hq/work-mesh/cache (warmMeshConversationCache) — message bodies are
  * never taken from MQTT. A periodic refresh covers missed doorbells.
  *
- * Credentials come from the same contract-3 vend the mesh daemon uses
- * (POST /v1/realtime/credentials); the WSS URL is SigV4-presigned. The
+ * Credentials come from the contract-2 (personal) vend
+ * (POST /v1/realtime/credentials {contractVersion: 2}), whose STS policy grants
+ * the caller's own `hq/{uid}/*` topics. The contract-3 vend the presence daemon
+ * uses only grants company presence + thread-directory topics, so subscribing
+ * to personal doorbells with it made AWS IoT drop the connection before SUBACK.
+ * Only doorbell topics the vend advertises are subscribed (one ungranted topic
+ * in a SUBSCRIBE disconnects the whole client). An `inbox` doorbell triggers
+ * an immediate inbox poll via `onInboxDoorbell`. The WSS URL is SigV4-presigned. The
  * connection is rebuilt before the vended credentials expire. `component-mesh`
  * is stamped ok while subscribed and refreshing, error otherwise.
  */
 import mqtt from "mqtt";
 import { warmMeshConversationCache } from "../../mesh/api.js";
-import { createContract3Fetcher, MQTT_KEEPALIVE_SECONDS, renewalDelayMs, } from "../../mesh/live/daemon/credentials.js";
+import { createPersonalRealtimeFetcher, MQTT_KEEPALIVE_SECONDS, renewalDelayMs, } from "../../mesh/live/daemon/credentials.js";
 import { presignIotWssUrl } from "../../mesh/live/daemon/presign.js";
 import { writeComponentStatus } from "../creds.js";
-export const DOORBELL_KINDS = ["dm", "work", "sessions", "notifications"];
+export const DOORBELL_KINDS = ["dm", "work", "sessions", "notifications", "inbox"];
 export const DOORBELL_DEBOUNCE_MS = 2_000;
 export const RECONNECT_BASE_MS = 1_000;
 export const RECONNECT_MAX_MS = 60_000;
 export function doorbellTopics(actorUid) {
     return DOORBELL_KINDS.map((k) => `hq/${actorUid}/${k}`);
 }
+/**
+ * Doorbell topics this session may subscribe to: the intersection of
+ * DOORBELL_KINDS with the personal topics the vend advertises. AWS IoT
+ * disconnects the client on any unauthorized topic in a SUBSCRIBE, so a kind
+ * the server does not (yet) grant is skipped rather than risked.
+ */
+export function grantedDoorbellTopics(bundle) {
+    const advertised = new Set(Object.values(bundle.topics));
+    return doorbellTopics(bundle.actorUid).filter((t) => advertised.has(t));
+}
+export function isInboxDoorbell(topic) {
+    return /^hq\/[^/]+\/inbox$/.test(topic);
+}
 function backoff(attempt, random) {
     const cap = Math.min(RECONNECT_MAX_MS, RECONNECT_BASE_MS * 2 ** attempt);
     return Math.max(RECONNECT_BASE_MS, Math.floor(random() * cap));
@@ -39,7 +58,7 @@ export async function startMeshListener(deps) {
     const fetchCredentials = deps.fetchCredentials ??
         (async () => {
             const token = await deps.getToken();
-            return createContract3Fetcher({ token, baseUrl: deps.apiBaseUrl })();
+            return createPersonalRealtimeFetcher({ token, baseUrl: deps.apiBaseUrl })();
         });
     let state = "idle";
     let client = null;
@@ -78,6 +97,14 @@ export async function startMeshListener(deps) {
         return refetching;
     };
     const ring = (topic) => {
+        if (isInboxDoorbell(topic) && deps.onInboxDoorbell) {
+            try {
+                void Promise.resolve(deps.onInboxDoorbell()).catch((err) => deps.log("warn", `inbox poll on doorbell failed: ${err instanceof Error ? err.message : String(err)}`));
+            }
+            catch (err) {
+                deps.log("warn", `inbox poll on doorbell failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
         if (debounce)
             clearT(debounce);
         debounce = setT(() => {
@@ -128,8 +155,17 @@ export async function startMeshListener(deps) {
         });
         client = c;
         let settled = false;
+        const topics = grantedDoorbellTopics(bundle);
+        const skipped = doorbellTopics(bundle.actorUid).filter((t) => !topics.includes(t));
+        if (skipped.length > 0)
+            deps.log("info", `vend does not grant ${skipped.join(", ")}; not subscribing`);
         c.on("connect", () => {
-            c.subscribe(doorbellTopics(bundle.actorUid), { qos: 1 }, (err) => {
+            if (topics.length === 0) {
+                deps.log("error", "realtime vend advertises no doorbell topics");
+                c.end(true);
+                return;
+            }
+            c.subscribe(topics, { qos: 1 }, (err) => {
                 if (err) {
                     deps.log("error", `subscribe failed: ${err.message}`);
                     c.end(true);
@@ -139,7 +175,7 @@ export async function startMeshListener(deps) {
                 attempt = 0;
                 state = "subscribed";
                 writeComponentStatus(deps.paths, "mesh", "ok");
-                deps.log("info", `subscribed to ${doorbellTopics(bundle.actorUid).length} doorbell topics`);
+                deps.log("info", `subscribed to ${topics.length} doorbell topics`);
                 void doRefetch("connect");
                 if (renewal)
                     clearT(renewal);

package/dist/lib/agent-kit/run/supervisor.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `hq agent kit run all` — supervise the four kit services in ONE process.
+ *
+ * The fallback for hosts with no usable service manager (a Linux box with no
+ * systemd user session bus, a container, launchd unavailable): each service
+ * runs as a child `node hq agent kit run <service>` whose output is appended
+ * to its own ~/.hq-agent/logs/<service>.log, and a child that exits is
+ * restarted with per-service exponential backoff (1 s doubling to 60 s,
+ * reset once a child has stayed up for a minute).
+ */
+import type { KitService } from "../services.js";
+export declare const SUPERVISOR_BACKOFF_BASE_MS = 1000;
+export declare const SUPERVISOR_BACKOFF_MAX_MS = 60000;
+/** A child that ran at least this long resets its backoff. */
+export declare const SUPERVISOR_HEALTHY_RUN_MS = 60000;
+export interface SupervisedChild {
+    on(event: "exit", handler: (code: number | null, signal: string | null) => void): unknown;
+    kill(signal?: NodeJS.Signals | number): boolean;
+}
+export interface SupervisorDeps {
+    services: readonly KitService[];
+    spawnService: (service: KitService) => SupervisedChild;
+    log: (level: "info" | "warn" | "error", msg: string) => void;
+    now?: () => number;
+    setTimeout?: (fn: () => void, ms: number) => unknown;
+    clearTimeout?: (handle: unknown) => void;
+}
+export interface SupervisorHandle {
+    stop: (signal?: NodeJS.Signals) => void;
+    restarts: () => Record<string, number>;
+    running: () => KitService[];
+}
+export declare function supervisorBackoffMs(attempt: number): number;
+export declare function superviseKitServices(deps: SupervisorDeps): SupervisorHandle;
+//# sourceMappingURL=supervisor.d.ts.map

package/dist/lib/agent-kit/run/supervisor.js

@@ -0,0 +1,85 @@
+/**
+ * `hq agent kit run all` — supervise the four kit services in ONE process.
+ *
+ * The fallback for hosts with no usable service manager (a Linux box with no
+ * systemd user session bus, a container, launchd unavailable): each service
+ * runs as a child `node hq agent kit run <service>` whose output is appended
+ * to its own ~/.hq-agent/logs/<service>.log, and a child that exits is
+ * restarted with per-service exponential backoff (1 s doubling to 60 s,
+ * reset once a child has stayed up for a minute).
+ */
+export const SUPERVISOR_BACKOFF_BASE_MS = 1_000;
+export const SUPERVISOR_BACKOFF_MAX_MS = 60_000;
+/** A child that ran at least this long resets its backoff. */
+export const SUPERVISOR_HEALTHY_RUN_MS = 60_000;
+export function supervisorBackoffMs(attempt) {
+    return Math.min(SUPERVISOR_BACKOFF_MAX_MS, SUPERVISOR_BACKOFF_BASE_MS * 2 ** Math.max(0, attempt));
+}
+export function superviseKitServices(deps) {
+    const now = deps.now ?? Date.now;
+    const setT = deps.setTimeout ?? ((fn, ms) => setTimeout(fn, ms));
+    const clearT = deps.clearTimeout ?? ((h) => clearTimeout(h));
+    const children = new Map();
+    const attempts = new Map();
+    const restarts = {};
+    const timers = new Map();
+    let stopped = false;
+    const start = (service) => {
+        if (stopped)
+            return;
+        timers.delete(service);
+        let child;
+        const startedAt = now();
+        try {
+            child = deps.spawnService(service);
+        }
+        catch (err) {
+            deps.log("error", `${service} failed to start: ${err instanceof Error ? err.message : String(err)}`);
+            scheduleRestart(service);
+            return;
+        }
+        children.set(service, child);
+        child.on("exit", (code, signal) => {
+            if (children.get(service) === child)
+                children.delete(service);
+            if (stopped)
+                return;
+            if (now() - startedAt >= SUPERVISOR_HEALTHY_RUN_MS)
+                attempts.set(service, 0);
+            deps.log("warn", `${service} exited (code=${code ?? "null"} signal=${signal ?? "none"})`);
+            scheduleRestart(service);
+        });
+    };
+    const scheduleRestart = (service) => {
+        if (stopped)
+            return;
+        const attempt = attempts.get(service) ?? 0;
+        attempts.set(service, attempt + 1);
+        const delay = supervisorBackoffMs(attempt);
+        restarts[service] = (restarts[service] ?? 0) + 1;
+        deps.log("info", `restarting ${service} in ${delay}ms (restart ${restarts[service]})`);
+        timers.set(service, setT(() => start(service), delay));
+    };
+    for (const s of deps.services)
+        start(s);
+    return {
+        stop: (signal = "SIGTERM") => {
+            stopped = true;
+            for (const h of timers.values())
+                clearT(h);
+            timers.clear();
+            for (const child of children.values()) {
+                try {
+                    child.kill(signal);
+                }
+                catch {
+                    /* already gone */
+                }
+            }
+            children.clear();
+        },
+        restarts: () => ({ ...restarts }),
+        running: () => [...children.keys()],
+    };
+}
+//# sourceMappingURL=supervisor.js.map

package/dist/lib/mesh/live/daemon/credentials.d.ts

@@ -131,4 +131,31 @@ export declare class CredentialRenewalManager {
     stop(): void;
     private clear;
 }
+/**
+ * Contract-2 (personal) realtime vend. Backed server-side by the personal
+ * session policy, which grants Subscribe/Receive on the caller's own
+ * `hq/{principalUid}/{dm,sessions,work,notifications,meeting,sync}` topics —
+ * unlike contract 3, whose policy only covers company presence and the thread
+ * directory. Doorbell listeners on personal topics MUST use this contract;
+ * subscribing to personal topics with a contract-3 session makes AWS IoT drop
+ * the connection before SUBACK.
+ */
+export interface PersonalRealtimeBundle {
+    contractVersion: 2;
+    credentials: IotCredentials;
+    iotEndpoint: string;
+    region: string;
+    clientId: string;
+    actorUid: string;
+    /** Advertised personal topics keyed by kind (dm, sessions, work, notifications, …). */
+    topics: Record<string, string>;
+    expiresAt: string;
+}
+export type PersonalCredentialsFetcher = () => Promise<PersonalRealtimeBundle>;
+export declare function normalizePersonalRealtimeBundle(raw: unknown): PersonalRealtimeBundle;
+export declare function createPersonalRealtimeFetcher(opts: {
+    token: string;
+    baseUrl?: string;
+    post?: (path: string, body: unknown) => Promise<CredentialVendPostResult>;
+}): PersonalCredentialsFetcher;
 //# sourceMappingURL=credentials.d.ts.map