@indigoai-us/hq-cli 5.117.0 → 5.117.2

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

@@ -18,7 +18,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { vaultApiFetch } from "../../../utils/vault-api.js";
-import { warmMeshConversationCache } from "../../mesh/api.js";
 import { writeComponentStatus } from "../creds.js";
 export const SEEN_IDS_NAME = "seen-ids.json";
 export const INBOX_JSONL_NAME = "inbox.jsonl";
@@ -60,15 +59,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) {
@@ -85,7 +114,8 @@ export function defaultAckItem(agentUid, apiBaseUrl) {
 export async function pollInboxOnce(deps) {
     const fetchInbox = deps.fetchInbox ?? defaultFetchInbox(deps.agentUid, deps.apiBaseUrl);
     const ackItem = deps.ackItem ?? defaultAckItem(deps.agentUid, deps.apiBaseUrl);
-    const warmCache = deps.warmCache ?? ((token, uid) => warmMeshConversationCache(token, uid));
+    // No default cache warm: the human conversation routes 403 for agent callers.
+    const warmCache = deps.warmCache ?? (async () => { });
     let token;
     try {
         token = await deps.getToken();
@@ -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 { defaultFetchInbox } from "./inbox.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));
@@ -35,11 +54,20 @@ export async function startMeshListener(deps) {
     const setT = deps.setTimeout ?? ((fn, ms) => setTimeout(fn, ms));
     const clearT = deps.clearTimeout ?? ((h) => clearTimeout(h));
     const connect = deps.connect ?? ((url, opts) => mqtt.connect(url, opts));
-    const refetch = deps.refetch ?? ((token, uid) => warmMeshConversationCache(token, uid));
+    // Agent callers are refused by the human conversation routes
+    // (/v1/notify/inbox|contacts|thread → 403 AGENT_ROUTE_NOT_SUPPORTED), so the
+    // default refetch reads the agent's own inbox, the agent-authorized source.
+    const refetch = deps.refetch ??
+        (async (token, uid) => {
+            const res = await defaultFetchInbox(uid, deps.apiBaseUrl)(token);
+            if (res.status !== 200) {
+                throw new Error(`GET ${res.url ?? "agent inbox"} → ${res.status}${res.bodyText ? ` body=${res.bodyText}` : ""}`);
+            }
+        });
     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 +106,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 +164,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 +184,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/agent-kit/skills.js

@@ -114,8 +114,8 @@ Rules:
         body: `# Work mesh status
 
 The work mesh is HQ's live board of who is working on what. It is the source
-of truth for project stories and active sessions; the kit's listener keeps a
-local cache under \`~/.hq/work-mesh/cache/\`.
+of truth for project stories and active sessions. The kit's listener re-polls
+this agent's inbox whenever a doorbell rings.
 
 \`\`\`bash
 hq mesh session status --company <slug>          # who is working on what right now

package/dist/lib/billing/plan-lock.d.ts

@@ -0,0 +1,99 @@
+/**
+ * `plan-lock` (starter-plan-hard-limits / US-011) — the CLI-side read + render
+ * of the workspace plan lock.
+ *
+ * Starter (free) workspaces are capped at 5 members and 0 integrations. Going
+ * over locks the workspace immediately: it becomes read-only until the owner
+ * trims back under the caps or upgrades to HQ Workforce. The lock decision is
+ * NOT made here — hq-pro's `src/billing/plan-lock.ts` is the single source of
+ * truth and ships the answer on `GET /membership/me` as a per-company
+ * `planLock` object. This module only reads that field and renders it.
+ *
+ * Member counts are decoration, never a second opinion: the count comes from
+ * `GET /v1/billing/usage-limits` on a best-effort basis and its absence only
+ * removes the "n of 5" detail from the notice. An absent field is UNKNOWN, so
+ * nothing here ever infers a lock (or an unlock) from missing data
+ * (hq-absent-field-never-means-constraining-value).
+ */
+/** Mirror of hq-pro's `PlanLockReason`. */
+export type PlanLockReason = "users" | "integrations";
+/** Mirror of hq-pro's `PlanLock` wire shape (see src/billing/plan-lock.ts). */
+export interface PlanLock {
+    locked: boolean;
+    reasons: PlanLockReason[];
+    upgradeUrl: string;
+    fixOptions: {
+        removeMembersTo: number;
+        disconnectIntegrations: boolean;
+    };
+}
+/** Optional member decoration for the notice ("7 of 5 members"). */
+export interface PlanLockMembers {
+    used: number;
+    limit: number;
+}
+export interface PlanLockStatus {
+    companySlug: string;
+    companyUid?: string;
+    lock: PlanLock;
+    members?: PlanLockMembers;
+    /**
+     * Resolved plan id, when the usage endpoint answered. UNKNOWN (absent) when
+     * it did not — surfaces that gate on "is this Starter?" must then stay
+     * silent rather than assume either way.
+     */
+    plan?: "free" | "paid" | "enterprise";
+    checkedAt: string;
+}
+/** Starter member cap quoted when the server did not send `removeMembersTo`. */
+export declare const STARTER_MEMBER_TARGET = 5;
+/** Upgrade destination quoted when the server did not send one. */
+export declare const DEFAULT_UPGRADE_URL = "https://hq.computer/billing";
+/** The paid plan the lock wall sends owners to. Copy lives in ONE place. */
+export declare const WORKFORCE_PLAN_LABEL = "HQ Workforce ($500/mo)";
+/**
+ * Defensively parse a `planLock` payload. Anything malformed returns null —
+ * the caller then behaves exactly as if the server had sent nothing, which is
+ * "unknown", not "locked".
+ */
+export declare function parsePlanLock(value: unknown): PlanLock | null;
+/**
+ * Pick the membership row for `companySlug` (or `cmp_…` uid) out of a decoded
+ * `/membership/me` body and return its parsed lock. No matching row — or no
+ * `planLock` on it — is UNKNOWN, so this returns null rather than guessing.
+ */
+export declare function selectPlanLock(body: unknown, companyRef: string): {
+    lock: PlanLock;
+    companyUid?: string;
+} | null;
+/** Parse the resolved plan id out of a usage-limits body. Absent → null. */
+export declare function selectPlan(body: unknown): "free" | "paid" | "enterprise" | null;
+/** Parse the `users` dimension out of a usage-limits body. Absent → null. */
+export declare function selectMemberUsage(body: unknown): PlanLockMembers | null;
+/**
+ * Read the live lock for one company: `planLock` from `/membership/me`, plus a
+ * best-effort member count for the notice. Returns null when the server did not
+ * answer with a lock for this company — callers must then say nothing.
+ */
+export declare function fetchPlanLockStatus(token: string, companyRef: string, opts?: {
+    timeoutMs?: number;
+}): Promise<PlanLockStatus | null>;
+/**
+ * The full WORKSPACE LOCKED block: why it locked, where the workspace stands
+ * against the cap, and the two fixes. Plain text — colour is applied by the
+ * caller so scripts capturing stdout get a clean block.
+ */
+export declare function renderPlanLockNotice(status: PlanLockStatus): string;
+/**
+ * The one-line form injected on every turn while the workspace stays locked.
+ * Kept to a single line on purpose — it repeats each turn.
+ */
+export declare function renderPlanLockLine(status: PlanLockStatus): string;
+/**
+ * The `Plan: …` orientation line. Starter only: a paid or enterprise
+ * workspace — and an UNKNOWN plan — gets no line at all.
+ */
+export declare function renderPlanLine(status: PlanLockStatus): string | null;
+/** Colourised block for interactive output. */
+export declare function colorizePlanLockNotice(notice: string): string;
+//# sourceMappingURL=plan-lock.d.ts.map