@indigoai-us/hq-cli 5.117.0 → 5.117.2

package/dist/commands/agent-probe.js

@@ -4,9 +4,14 @@
  *
  *   whoami       mint as the machine identity; token names this agent
  *   team-sync    `hq sync pull --all` succeeds and the company folder exists
- *   work-mesh    realtime credentials vend for this agent and the roster row
- *                shows presence online/stale (heartbeat landed)
- *   dm           send a DM to self via the notify surface and read it back
+ *   work-mesh    the personal (contract-2) realtime vend names this agent, the
+ *                agent-authorized inbox route answers 200, and this host's own
+ *                presence is live: a fresh last-heartbeat.json plus an ok
+ *                component-mesh stamp from the doorbell listener. (The company
+ *                roster route is owner/admin-only and 404s for agt_ callers.)
+ *   dm           send a DM to self via POST /v1/notify/dm (accepted) and read the agent inbox (200)
+ *                through GET /v1/agents/{uid}/inbox (the agent read surface;
+ *                /v1/notify/thread is intentionally closed to agents)
  *   secrets      `GET /secrets/{companyUid}` answers 200
  *
  * Output is the exact shape the console recipes promise: one
@@ -26,15 +31,18 @@ import { CLI_VERSION } from "../cli-version.js";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { peekIdToken } from "../utils/id-token.js";
 import { getCompanyUid, vaultApiFetch } from "../utils/vault-api.js";
-import { listAgents, readAgentThread, sendAgentDm } from "./agents.js";
-import { createContract3Fetcher } from "../lib/mesh/live/daemon/credentials.js";
+import { sendAgentDm } from "./agents.js";
+import { createPersonalRealtimeFetcher } from "../lib/mesh/live/daemon/credentials.js";
+import { readComponentStatus } from "../lib/agent-kit/creds.js";
+import { COMPONENT_STALE_AFTER_MS } from "../lib/agent-kit/run/heartbeat.js";
+import { defaultFetchInbox } from "../lib/agent-kit/run/inbox.js";
 import { agentKitPaths } from "../lib/agent-kit/paths.js";
 import { readKitConfig } from "../lib/agent-kit/kit-config.js";
 import { readLastHeartbeat } from "../lib/agent-kit/run/heartbeat.js";
 import { defaultRunPull, syncPullArgs } from "../lib/agent-kit/run/sync.js";
 import { requireExternalCreds } from "./agent-kit.js";
-export const DM_ROUNDTRIP_TIMEOUT_MS = 20_000;
-export const DM_ROUNDTRIP_POLL_MS = 2_000;
+/** A heartbeat older than this does not count as live presence (3 missed 60 s beats). */
+export const PRESENCE_FRESH_SECONDS = 180;
 function errText(err) {
     return err instanceof Error ? err.message : String(err);
 }
@@ -49,7 +57,6 @@ export function heartbeatAgeSeconds(paths, now = () => new Date()) {
 }
 export async function runProbe(deps) {
     const now = deps.now ?? (() => new Date());
-    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
     const nonce = (deps.nonce ?? (() => randomBytes(6).toString("hex")))();
     const self = deps.creds.entityUid;
     const checks = [];
@@ -108,7 +115,7 @@ export async function runProbe(deps) {
     else {
         checks.push({ name: "team-sync", ok: false, detail: "skipped: no token" });
     }
-    // 3. mesh-presence
+    // 3. work-mesh: vend + agent-authorized reachability + self presence
     if (token && companyUid) {
         try {
             const vend = await deps.vendRealtime(token);
@@ -116,17 +123,23 @@ export async function runProbe(deps) {
                 checks.push({ name: "work-mesh", ok: false, detail: `realtime vend is for ${vend.actorUid}` });
             }
             else {
-                const roster = await deps.listRoster(token, companyUid);
-                const row = roster.find((r) => r.uid === self);
-                const presence = typeof row?.presence === "string" ? row.presence : "unknown";
-                const last = typeof row?.lastHeartbeatAt === "string" ? row.lastHeartbeatAt : "never";
-                const ok = presence === "online" || presence === "stale";
+                const inbox = await deps.readInbox(token);
+                const age = heartbeatAgeSeconds(deps.paths, now);
+                const mesh = readComponentStatus(deps.paths, "mesh", COMPONENT_STALE_AFTER_MS.mesh, now);
+                const reachable = inbox.status === 200;
+                const fresh = age !== null && age <= PRESENCE_FRESH_SECONDS;
+                const meshOk = mesh.status === "ok";
+                const ok = reachable && fresh && meshOk;
+                const parts = [
+                    "realtime vend ok",
+                    `inbox GET → ${inbox.status}`,
+                    `heartbeat ${age === null ? "never" : `${age}s ago`}`,
+                    `mesh listener ${mesh.status}${mesh.at ? ` @${mesh.at.toISOString()}` : ""}`,
+                ];
                 checks.push({
                     name: "work-mesh",
                     ok,
-                    detail: row
-                        ? `realtime vend ok; presence=${presence} lastHeartbeatAt=${last}${ok ? "" : " — is `hq agent kit` installed and running?"}`
-                        : "realtime vend ok but this agent is not on the company roster",
+                    detail: `${parts.join("; ")}${ok ? "" : " — is `hq agent kit` installed and running? see ~/.hq-agent/logs/mesh.log"}`,
                 });
             }
         }
@@ -137,27 +150,22 @@ export async function runProbe(deps) {
     else {
         checks.push({ name: "work-mesh", ok: false, detail: "skipped: no token/company" });
     }
-    // 4. dm-roundtrip
+    // 4. dm: the send is accepted and the agent inbox is readable.
+    // The server never delivers a self-DM into the sender's own inbox
+    // (hq-pro-core notify-dm skips inbox delivery when recipient === sender),
+    // so a self round-trip can never succeed. Inbound delivery is proven by a
+    // teammate's DM, which the kit's inbox poller mirrors to inbox.jsonl.
     if (token) {
         try {
             const body = `hq agent probe ${nonce}`;
             await deps.sendDm(token, self, body);
-            const deadline = now().getTime() + (deps.dmTimeoutMs ?? DM_ROUNDTRIP_TIMEOUT_MS);
-            let found = false;
-            for (;;) {
-                const msgs = await deps.readThread(token, self);
-                if (msgs.some((m) => typeof m.body === "string" && m.body.includes(nonce))) {
-                    found = true;
-                    break;
-                }
-                if (now().getTime() >= deadline)
-                    break;
-                await sleep(DM_ROUNDTRIP_POLL_MS);
-            }
+            const res = await deps.readInbox(token);
             checks.push({
                 name: "dm",
-                ok: found,
-                detail: found ? "sent to self via /v1/notify/dm and read back" : `sent but not visible in thread after ${Math.round((deps.dmTimeoutMs ?? DM_ROUNDTRIP_TIMEOUT_MS) / 1000)}s`,
+                ok: res.status === 200,
+                detail: res.status === 200
+                    ? "send accepted by /v1/notify/dm; /v1/agents/{uid}/inbox → 200 (self-DMs are not delivered to the inbox; a DM from a teammate confirms inbound)"
+                    : `send accepted but /v1/agents/{uid}/inbox answered ${res.status}`,
             });
         }
         catch (err) {
@@ -205,6 +213,19 @@ export async function runProbe(deps) {
     }
     return result;
 }
+/** True when any inbox item (whatever its channel shape) carries the nonce. */
+export function inboxContainsNonce(body, nonce) {
+    const rec = body && typeof body === "object" ? body : {};
+    const messages = Array.isArray(rec.messages) ? rec.messages : [];
+    return messages.some((m) => {
+        try {
+            return JSON.stringify(m).includes(nonce);
+        }
+        catch {
+            return false;
+        }
+    });
+}
 export function formatHeartbeatAge(age) {
     if (age === null)
         return "never (kit heartbeat has not posted yet)";
@@ -241,12 +262,11 @@ export function defaultProbeDeps(paths, creds) {
         resolveCompanyUid: (token, slug) => getCompanyUid(token, slug),
         runPull: defaultRunPull(process.execPath, process.argv[1], process.env),
         vendRealtime: async (token) => {
-            const bundle = await createContract3Fetcher({ token, baseUrl: base })();
+            const bundle = await createPersonalRealtimeFetcher({ token, baseUrl: base })();
             return { actorUid: bundle.actorUid };
         },
-        listRoster: async (token, companyUid) => (await listAgents(token, companyUid)),
+        readInbox: (token) => defaultFetchInbox(creds.entityUid, base)(token),
         sendDm: (token, to, body) => sendAgentDm(token, to, body),
-        readThread: async (token, withUid) => readAgentThread(token, withUid, 20),
         listSecrets: async (token, companyUid) => {
             const res = await vaultApiFetch({
                 token,

package/dist/commands/billing.js

@@ -110,7 +110,7 @@ export function registerBillingCommand(program) {
     });
     billing
         .command("upgrade")
-        .description("Open Stripe Checkout to upgrade this company to HQ Team ($500/mo)")
+        .description("Open Stripe Checkout to upgrade this company to HQ Workforce ($500/mo)")
         .option("--company <slug>", "Company slug (resolves to companyUid)")
         .option("--no-browser", "Print the Stripe Checkout URL instead of opening it")
         .option("--json", "Emit the Checkout URL as JSON")

package/dist/commands/db-provision.js

@@ -28,7 +28,7 @@ const defaultDeps = () => ({
 });
 export function registerDbProvisionCommand(db, depsFactory = defaultDeps) {
     db.command("provision")
-        .description("Provision (or re-bind) the company remote vault DB via HQ control plane (Team plan)")
+        .description("Provision (or re-bind) the company remote vault DB via HQ control plane (HQ Workforce plan)")
         .requiredOption("--company <slug>", "Company slug")
         .option("--region <region>", "AWS region", "us-east-1")
         .action(async (opts) => {
@@ -65,9 +65,9 @@ export function registerDbProvisionCommand(db, depsFactory = defaultDeps) {
                 throw error;
             const msg = error instanceof Error ? error.message : "Unknown error";
             const status = error.status;
-            if (status === 402 || /PLAN_REQUIRED|Team plan|\$500/i.test(msg)) {
-                console.error(chalk.red("Error:"), "Remote vault DB requires the HQ Team plan ($500/mo).");
-                console.error(chalk.dim("Local databases still work: hq db status|sql|migrate — no Team plan required."));
+            if (status === 402 || /PLAN_REQUIRED|Team plan|Workforce|\$500/i.test(msg)) {
+                console.error(chalk.red("Error:"), "Remote vault DB requires the HQ Workforce plan ($500/mo).");
+                console.error(chalk.dim("Local databases still work: hq db status|sql|migrate — no HQ Workforce plan required."));
             }
             else if (status === 404 || /Unknown route|Not Found/i.test(msg)) {
                 console.error(chalk.red("Error:"), "Remote DB control plane is not available yet (routes not deployed).");

package/dist/commands/dm.d.ts

@@ -259,5 +259,15 @@ export declare function formatInboxEvent(e: DmInboxEvent, nowMs: number): string
 export declare function formatThreadMessage(m: DmThreadMessage, nowMs: number): string;
 /** Render one channel/group message line. */
 export declare function formatChannelMessage(m: ChannelMessageItem, nowMs: number): string;
+/**
+ * The agent uid when the caller is an agent (machine) identity, else null.
+ * Agents may not read /v1/notify/inbox or /v1/notify/thread (the server
+ * allow-list is intentionally human-only); their read surface is
+ * GET /v1/agents/{uid}/inbox.
+ */
+export declare function agentCallerUid(token: string, machine?: () => boolean): string | null;
+export declare const AGENT_THREAD_UNAVAILABLE: string;
+/** One-line summary of an agent inbox item (DM, email, … — shapes vary by channel). Pure. */
+export declare function formatAgentInboxItem(item: Record<string, unknown>): string;
 export declare function registerDmCommand(program: Command): void;
 //# sourceMappingURL=dm.d.ts.map

package/dist/commands/dm.js

@@ -2,6 +2,8 @@ import chalk from "chalk";
 import { readFileSync } from "node:fs";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch } from "../utils/vault-api.js";
+import { isMachineIdentity } from "@indigoai-us/hq-cloud";
+import { peekIdToken } from "../utils/id-token.js";
 const EMAIL_PATTERN = /^[^\s]+@[^\s]+$/;
 // People (prs_) and agents (agt_) are both first-class DM participants; the
 // server applies the same membership-overlap gate to either and delivers
@@ -789,9 +791,83 @@ async function ackEvents(token, eventIds) {
         throw new Error(friendlyDmError(res.status, err.code, err.error ?? err.message ?? res.statusText));
     }
 }
+/**
+ * The agent uid when the caller is an agent (machine) identity, else null.
+ * Agents may not read /v1/notify/inbox or /v1/notify/thread (the server
+ * allow-list is intentionally human-only); their read surface is
+ * GET /v1/agents/{uid}/inbox.
+ */
+export function agentCallerUid(token, machine = isMachineIdentity) {
+    const claims = peekIdToken(token);
+    const uid = claims["custom:entityUid"];
+    if (typeof uid !== "string" || !uid.startsWith("agt_"))
+        return null;
+    if (claims["custom:entityType"] === "agent")
+        return uid;
+    try {
+        return machine() ? uid : null;
+    }
+    catch {
+        return null;
+    }
+}
+export const AGENT_THREAD_UNAVAILABLE = "`hq dm thread` reads /v1/notify/thread, which is not available to agent identities. " +
+    "Use `hq dm inbox` — for agents it reads GET /v1/agents/{uid}/inbox.";
+/** One-line summary of an agent inbox item (DM, email, … — shapes vary by channel). Pure. */
+export function formatAgentInboxItem(item) {
+    const str = (k) => (typeof item[k] === "string" ? item[k] : "");
+    const id = str("messageId") || str("id") || "?";
+    const channel = str("channel") || "inbox";
+    const from = str("fromDisplayName") || str("fromEmail") || str("from") || str("fromPersonUid") || "unknown";
+    const when = str("createdAt") || str("receivedAt");
+    const text = str("text") || str("body") || str("subject");
+    return `${chalk.bold(from)} ${chalk.dim(`[${channel}] ${id}${when ? ` ${when}` : ""}`)}\n  ${firstLine(text)}`;
+}
+async function runAgentInbox(token, agentUid, opts) {
+    const route = `/v1/agents/${encodeURIComponent(agentUid)}/inbox`;
+    const res = await vaultApiFetch({ token, path: route });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        console.error(chalk.red(`GET ${route} → ${res.status}${text ? `: ${text.slice(0, 300)}` : ""}`));
+        process.exit(1);
+    }
+    const data = (await res.json().catch(() => ({})));
+    let items = Array.isArray(data.messages) ? data.messages : [];
+    if (opts.limit && Number(opts.limit) > 0)
+        items = items.slice(0, Number(opts.limit));
+    if (opts.json) {
+        console.log(JSON.stringify(items, null, 2));
+    }
+    else if (items.length === 0) {
+        console.log(chalk.dim("No pending inbox items."));
+    }
+    else {
+        console.log(chalk.green(`${items.length} pending inbox item${items.length === 1 ? "" : "s"}:`));
+        for (const item of items)
+            console.log(`\n${formatAgentInboxItem(item)}`);
+    }
+    if (opts.markRead) {
+        let acked = 0;
+        for (const item of items) {
+            const id = typeof item.messageId === "string" ? item.messageId : typeof item.id === "string" ? item.id : null;
+            if (!id)
+                continue;
+            const ack = await vaultApiFetch({ token, path: `${route}/${encodeURIComponent(id)}/ack`, method: "POST" });
+            if (ack.ok)
+                acked += 1;
+        }
+        if (!opts.json && acked > 0)
+            console.log(chalk.dim(`\nAcked ${acked}.`));
+    }
+}
 async function runDmInbox(opts) {
     try {
         const token = await ensureCognitoToken();
+        const agentUid = agentCallerUid(token);
+        if (agentUid) {
+            await runAgentInbox(token, agentUid, opts);
+            return;
+        }
         const query = {};
         if (opts.limit)
             query.limit = opts.limit;
@@ -841,6 +917,10 @@ async function runDmThread(identifier, opts) {
         if (opts.limit)
             query.limit = opts.limit;
         const token = await ensureCognitoToken();
+        if (agentCallerUid(token)) {
+            console.error(chalk.yellow(AGENT_THREAD_UNAVAILABLE));
+            process.exit(1);
+        }
         const res = await vaultApiFetch({
             token,
             path: "/v1/notify/thread",

package/dist/commands/meetings.js

@@ -111,8 +111,8 @@ async function handleApiError(res, json = false) {
         console.error(chalk.red(body.error ?? "Not found"));
     }
     else if (res.status === 402) {
-        console.error(chalk.red("Meeting notetaker bots require the $500/mo HQ Team plan."));
-        console.error(chalk.dim(body.message ?? body.error ?? "Upgrade your company to HQ Team to record meetings."));
+        console.error(chalk.red("Meeting notetaker bots require the $500/mo HQ Workforce plan."));
+        console.error(chalk.dim(body.message ?? body.error ?? "Upgrade your company to HQ Workforce to record meetings."));
     }
     else {
         console.error(chalk.red(`API error (${res.status}): ${body.error ?? res.statusText}`));

package/dist/commands/whoami.d.ts

@@ -2,6 +2,7 @@
  * hq whoami — displays current user or 'not logged in'
  */
 import { Command } from 'commander';
+import { type PlanLockStatus } from "../lib/billing/plan-lock.js";
 export interface WhoamiTokenIdentity {
     email?: string;
     sub?: string;
@@ -19,5 +20,11 @@ export interface WhoamiDisplayIdentity {
  * email with the token subject of the delegating machine.
  */
 export declare function resolveWhoamiIdentity(identity: WhoamiTokenIdentity): WhoamiDisplayIdentity;
+/**
+ * Human rendering of the plan state: the full WORKSPACE LOCKED block when the
+ * workspace is locked, the one-line `Plan: Starter — …` orientation when it is
+ * Starter and healthy, and nothing at all otherwise.
+ */
+export declare function renderWhoamiPlanBlock(status: PlanLockStatus): string | null;
 export declare function registerWhoamiCommand(program: Command): void;
 //# sourceMappingURL=whoami.d.ts.map

package/dist/commands/whoami.js

@@ -4,7 +4,8 @@
 import chalk from 'chalk';
 import { loadCachedTokens, isExpiring, loadMachineCreds, } from '@indigoai-us/hq-cloud';
 import { peekIdToken as decodeIdToken } from "../utils/id-token.js";
-import { loadMachineCachedTokens, resolveCognitoTokenSource } from "../utils/cognito-session.js";
+import { ensureCognitoToken, loadMachineCachedTokens, resolveCognitoTokenSource, } from "../utils/cognito-session.js";
+import { colorizePlanLockNotice, fetchPlanLockStatus, renderPlanLine, renderPlanLockNotice, } from "../lib/billing/plan-lock.js";
 /**
  * Resolves the person represented by an ID token without pairing a delegated
  * email with the token subject of the delegating machine.
@@ -40,11 +41,58 @@ function peekIdToken(idToken) {
             : undefined,
     };
 }
+/**
+ * starter-plan-hard-limits / US-011 — read the workspace plan lock for
+ * `--company <slug>`.
+ *
+ * hq-pro owns the decision (`planLock` on GET /membership/me); this only reads
+ * it. Best-effort by construction: no session, a network failure, an older
+ * backend that sends no `planLock`, or a company the caller is not a member of
+ * all resolve to null — reported as UNKNOWN and rendered as nothing, never as
+ * a guessed lock or a guessed all-clear, and never as a command failure. The
+ * command exists to answer "who am I"; the plan line is decoration on top.
+ */
+async function readPlanLock(company) {
+    const slug = company?.trim();
+    if (!slug)
+        return null;
+    try {
+        // NEVER interactive: this runs inside `--json` (before the authenticated
+        // check) and inside hq-core's per-turn plan-lock refresh hook. With the
+        // default `interactive: true`, a box with no cached session would launch a
+        // browser sign-in and block the caller instead of resolving to UNKNOWN.
+        const token = await ensureCognitoToken({ interactive: false });
+        return await fetchPlanLockStatus(token, slug);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Human rendering of the plan state: the full WORKSPACE LOCKED block when the
+ * workspace is locked, the one-line `Plan: Starter — …` orientation when it is
+ * Starter and healthy, and nothing at all otherwise.
+ */
+export function renderWhoamiPlanBlock(status) {
+    if (status.lock.locked) {
+        return colorizePlanLockNotice(renderPlanLockNotice(status));
+    }
+    return renderPlanLine(status);
+}
+async function printPlanBlock(company) {
+    const status = await readPlanLock(company);
+    if (!status)
+        return;
+    const block = renderWhoamiPlanBlock(status);
+    if (block)
+        console.log(block);
+}
 export function registerWhoamiCommand(program) {
     program
         .command('whoami')
         .description('Show the currently authenticated user')
         .option('--json', 'Output identity metadata as JSON (never tokens)')
+        .option('--company <slug>', 'Also report this company\'s workspace plan state (Starter lock)')
         .action(async (opts) => {
         try {
             // Effective source (same as auth status / ensureCognitoToken): env
@@ -67,6 +115,9 @@ export function registerWhoamiCommand(program) {
                 const agentUid = machineCreds?.entityUid !== undefined
                     ? (machineCreds.entityUid.startsWith('agt_') ? machineCreds.entityUid : null)
                     : boundLegacyAgent;
+                // planLock is additive: absent-or-null means UNKNOWN, which is what
+                // every consumer already sees from a backend that predates it.
+                const planLock = await readPlanLock(opts.company);
                 console.log(JSON.stringify({
                     schemaVersion: 1,
                     authenticated: machine ? Boolean(machineCreds) : Boolean(cached && !isExpiring(cached, 0)),
@@ -75,6 +126,7 @@ export function registerWhoamiCommand(program) {
                     personUid: !machine && identity.entityType === 'person' ? identity.entityUid ?? null : null,
                     agentUid,
                     username: machineCreds?.username ?? null,
+                    planLock,
                 }, null, 2));
                 return;
             }
@@ -88,6 +140,7 @@ export function registerWhoamiCommand(program) {
                     : undefined;
                 console.log(`Machine identity ${username}${entityUid ? ` (agent ${entityUid})` : ''} — sessions mint automatically`);
                 console.log(`token source: machine`);
+                await printPlanBlock(opts.company);
                 return;
             }
             if (!cached) {
@@ -101,6 +154,7 @@ export function registerWhoamiCommand(program) {
             }
             const { email, sub } = resolveWhoamiIdentity(peekIdToken(cached.idToken));
             console.log(`Logged in as ${email ?? 'unknown'}${sub ? ` (${sub})` : ''}`);
+            await printPlanBlock(opts.company);
         }
         catch (error) {
             console.error(chalk.red('Error:'), error instanceof Error ? error.message : 'Unknown error');

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