@synap-core/cli 1.11.0 → 1.13.0

package/dist/lib/installed.d.ts

@@ -12,9 +12,18 @@
  * build, this degrades to an empty set (no markers) rather than failing the
  * discovery command — you can always browse the catalog offline.
  */
+import { type HubConfig } from "./hub-client.js";
+import { type LifecycleInfo, type OverlayInfo, type PendingDataChanges } from "./template-lifecycle.js";
 /** An installed workspace's package identity — slug plus (when the pod stamped one) its content version. */
 export interface InstalledTemplateInfo {
     slug: string;
+    /**
+     * Which install ledger this row came from — `"workspace"` for the historical
+     * shape, and one of the other five kinds once the pod serves
+     * `GET /api/hub/installed`. Optional so every existing constructor (and every
+     * test that builds one by hand) stays valid; absent reads as `"workspace"`.
+     */
+    kind?: InstalledKind;
     /**
      * `settings.packageVersion`, when the pod stamped one — `GET /api/hub/workspaces`
      * (`hub-protocol/rest/workspaces.ts`) projects it off `workspace.settings`.
@@ -25,27 +34,217 @@ export interface InstalledTemplateInfo {
      * "can't check" rather than "outdated" — see `market.ts`'s `computeUpdates`.
      */
     version?: string;
-    workspaceId: string;
+    /**
+     * The workspace this row lives in — `null` for a POD-GLOBAL install (a
+     * capability, cell or skill installed with `workspace_id IS NULL`). Widened
+     * from `string` when `GET /installed` brought the other five kinds in: a
+     * pod-wide row has no workspace, and inventing one would be a fabrication.
+     */
+    workspaceId: string | null;
     workspaceName: string;
+    /**
+     * Server-computed latest catalog version for this slug (Hub `/workspaces`
+     * TemplateHealth projection). Present when the pod runs the server-side drift
+     * code; `undefined` on an older pod, where the CLI falls back to deriving
+     * drift itself. Only set for the `packageSlug` entry, never `installedPacks`.
+     */
+    latestVersion?: string | null;
+    /**
+     * Server-computed drift (Hub `/workspaces` TemplateHealth) — the single
+     * truthful "an update is available" signal, so the CLI stops re-deriving it.
+     * `undefined` on an older pod → client fallback.
+     */
+    drifted?: boolean;
 }
+/** Every kind the door can report. Mirrors the pod's `INSTALLED_KINDS`. */
+export declare const INSTALLED_KINDS: readonly ["workspace", "capability", "view", "skill", "automation", "cell"];
+export type InstalledKind = (typeof INSTALLED_KINDS)[number];
+/**
+ * One row of `GET /api/hub/installed`, plus the locally-joined `workspaceName`.
+ *
+ * Read the pod's `hub-protocol/rest/installed.ts` docblock for the field
+ * contract. The three that bite:
+ *
+ *  - `drift: null` means **NOT COMPUTED**, never "no drift". Capabilities and
+ *    cells have no local comparator, so `null` is the honest answer for them.
+ *  - `packageSlug: null` means **not source-linked to a package** — every
+ *    capability row (its link is a `templateKey`, not a catalog slug) and any
+ *    cell minted with the `"unknown"` sentinel. Never print it as a name.
+ *  - `installedVersion` is a semver for workspace/view/skill/automation and a
+ *    CONTENT HASH for capability/cell. Never diff the two shapes.
+ */
+export interface InstalledRow {
+    kind: InstalledKind;
+    id: string;
+    name: string;
+    packageSlug: string | null;
+    templateKey: string | null;
+    installedVersion: string | null;
+    latestVersion: string | null;
+    drift: boolean | null;
+    installedAt: string | null;
+    workspaceId: string | null;
+    /** Joined LOCALLY from `GET /workspaces`; the door itself carries only the id. */
+    workspaceName: string | null;
+    provisioningStatus: string | null;
+    failedStep: string | null;
+    note?: string;
+}
+export interface InstalledInventory {
+    rows: InstalledRow[];
+    /** Echoes whether the pod ran its expensive drift pass. The CLI never asks for it. */
+    driftComputed: boolean;
+    /**
+     * TRUE when the pod does not serve `GET /installed` (404) and this inventory
+     * was rebuilt from `GET /workspaces` alone — i.e. workspace packages only.
+     * Callers must SAY so; an older pod is not an empty pod.
+     */
+    degraded: boolean;
+}
+/**
+ * STRICT inventory — THROWS on any pod failure except the older-pod 404, which
+ * degrades to the historical `/workspaces` behaviour with `degraded: true`.
+ * Absence of the route is not absence of installs.
+ */
+export declare function fetchInstalledInventoryStrict(cfg?: HubConfig): Promise<InstalledInventory>;
+/** Non-fatal inventory — empty (and NOT degraded) on any failure, for markers that must never block discovery. */
+export declare function fetchInstalledInventory(cfg?: HubConfig): Promise<InstalledInventory>;
 /**
- * Every installed workspace's `{slug, version, workspaceId, workspaceName}` —
- * the raw material for "what's installed" (`fetchInstalledSlugs`) and "what's
- * out of date" (`market update`'s `computeUpdates`). One Hub call, derived
- * views. Unions TWO install shapes, mirroring the browser's
- * `useInstalledPackageSlugs` (see that hook's doc for the full rationale):
+ * The UPDATABLE subset of an inventory, in the shape `computeUpdates` /
+ * `market update` / the composition renderers already speak.
  *
- *  1. `workspace.packageSlug` — a workspace-creating install (template).
- *  2. `workspace.settings.installedPacks[]` — additive packs (profile/view/
- *     bento) that create no workspace of their own, so never set `packageSlug`.
+ * Rows with `packageSlug: null` are dropped ON PURPOSE — they are inventory,
+ * not update targets: `market update` takes a catalog SLUG, and a capability's
+ * `templateKey` is not one. Feeding them through would hand the user a slug
+ * that misses the catalog. `market installed` renders them separately.
  *
- * A workspace carrying BOTH contributes one row per shape — they're different
- * package identities layered onto the same workspace.
+ * `drift: null` maps to `drifted: undefined`, which is `computeUpdates`'
+ * long-standing "the server didn't answer — derive it client-side, and report
+ * an unstampable install as noVersionInfo rather than outdated" path. It is
+ * NEVER mapped to `drifted: false`.
  */
+export declare function installedRowsToTemplates(rows: InstalledRow[]): InstalledTemplateInfo[];
+/**
+ * STRICT variant — THROWS on any pod failure instead of degrading to empty.
+ * Use when the caller must tell "pod unreachable" apart from "genuinely
+ * nothing installed": `market update` otherwise reports a transient Hub error
+ * as "No installed packages found," which reads as data loss and is why the
+ * command felt random (empty on one call, full on the next).
+ *
+ * Sources from `fetchInstalledInventoryStrict` — so every consumer of this
+ * function (`market update`, `launch --list`, the picker, `fetchInstalledSlugs`)
+ * now sees ALL SIX kinds on a current pod, and exactly the old workspace-only
+ * set on an older one.
+ */
+export declare function fetchInstalledTemplatesStrict(): Promise<InstalledTemplateInfo[]>;
 export declare function fetchInstalledTemplates(): Promise<InstalledTemplateInfo[]>;
+/**
+ * Ground-truth stamp verification — re-reads ONE workspace's stored
+ * `packageVersion` after an apply to confirm a version stamp actually landed,
+ * instead of INFERRING it from the apply response's `outcome` (a proxy that
+ * false-positives whenever content was already identical, so `outcome` comes
+ * back `"unchanged"` even though the stamp was written). Returns:
+ *   - `true`  — the workspace now carries the expected version (stamp landed).
+ *   - `false` — reached the pod, but the stamp is missing/different (old pod
+ *               that doesn't stamp on reconcile, or a real failure).
+ *   - `null`  — couldn't reach/find the workspace; don't cry wolf on a verify
+ *               failure — the apply itself already succeeded.
+ */
+export declare function verifyStampLanded(workspaceId: string, expectedVersion: string, cfg?: HubConfig): Promise<boolean | null>;
+/**
+ * A workspace's template-attachment status — every workspace on the pod, NOT
+ * just the ones with a package identity (which is `fetchInstalledTemplates`'s
+ * job). This is the raw material for the workspace-centric discovery surface
+ * (`market workspaces`): it deliberately KEEPS workspaces with no `packageSlug`
+ * so the user can find the pre-market / hand-built one that still needs
+ * attaching.
+ */
+export interface WorkspaceAttachment {
+    workspaceId: string;
+    workspaceName: string;
+    /** Operational-domain label — `settings.workspaceSubtype ?? workspaceType`, mirroring the `discover()` service's `domain` field. */
+    domain: string | null;
+    /** `settings.packageSlug` — null means this workspace was never provisioned from a template (pre-market or hand-built): a candidate to attach. */
+    packageSlug: string | null;
+    /** `settings.packageVersion` — set only when the pod version-stamped the install. `packageSlug` set + this null = "attached, no version stamp — reattach to enable updates". */
+    packageVersion: string | null;
+    /** Server-computed latest catalog version (Hub TemplateHealth); `undefined` on an older pod. */
+    latestVersion?: string | null;
+    /** Server-computed drift (Hub TemplateHealth) — the truthful "update available"; `undefined` on an older pod → client fallback. */
+    drifted?: boolean;
+    /** Template lifecycle (Hub TemplateHealth): current / retired / unlisted / unknown. `undefined` on an older pod — show what was shown before. */
+    lifecycle?: LifecycleInfo;
+    /** Overlays composed onto this space, each with its own standing. `undefined` on an older pod — show what was shown before. */
+    overlays?: OverlayInfo[];
+    /**
+     * The proposals this space's last template update is still waiting on — the
+     * pod reads them LIVE (Hub `awaitingApproval`), so a decided proposal is
+     * gone from here. `[]`/absent = nothing waiting (or an older pod).
+     */
+    awaitingApproval?: string[];
+    /**
+     * The pod's ONE sentence for why this space's last template update did not
+     * finish (Hub `applyWarning`, synap-backend `templateApplyWarning`) — print
+     * it verbatim, never re-word it. `null`/absent = nothing to say.
+     */
+    applyWarning?: string | null;
+    /** The pod's reading of the last apply (`healthApplyState`): building / active / awaiting-approval / partial / layer-2-not-run / failed. `null`/absent on an older pod. */
+    state?: string | null;
+    /** Data changes the update is held for until a person agrees. `undefined` on an older pod; `null` = nothing held. */
+    pendingDataChanges?: PendingDataChanges | null;
+    /** An agent's pending "update this space" proposal. `null`/absent = none (or an older pod). */
+    updateProposal?: {
+        id: string;
+    } | null;
+    /** Row warnings about the step (a read the pod could not check). Empty on an older pod. */
+    stepWarnings?: string[];
+}
+/**
+ * Every workspace on the pod with its template-attachment status, sourced from
+ * the SAME Hub `GET /workspaces` call `fetchInstalledTemplates` uses (which
+ * already projects `packageSlug`/`packageVersion`/`workspaceType`/
+ * `workspaceSubtype`). Unlike `fetchInstalledTemplates`, it does NOT drop rows
+ * without a `packageSlug` — those unattached workspaces are exactly what the
+ * discovery surface exists to surface. Non-fatal: empty on ANY failure.
+ *
+ * Only the workspace's OWN `packageSlug` is considered here — additive
+ * `installedPacks` (profile/view/bento packs) don't constitute a workspace's
+ * template attachment, so they're intentionally ignored for this view.
+ */
+type HubWorkspaceAttachmentRow = {
+    id: string;
+    name: string;
+    workspaceType?: string | null;
+    workspaceSubtype?: string | null;
+    packageSlug?: string | null;
+    packageVersion?: string | null;
+    latestVersion?: string | null;
+    drifted?: boolean;
+    lifecycle?: string | null;
+    replacedBy?: string | null;
+    retiredReason?: string | null;
+    overlays?: unknown;
+    awaitingApproval?: unknown;
+    applyWarning?: unknown;
+    state?: unknown;
+    pendingDataChanges?: unknown;
+    updateProposal?: unknown;
+    stepWarnings?: unknown;
+};
+export declare function mapWorkspaceAttachments(rows: HubWorkspaceAttachmentRow[]): WorkspaceAttachment[];
+/**
+ * STRICT variant — THROWS on any pod failure instead of degrading to empty.
+ * Use where an empty result would be a LIE about the user's pod (e.g. `synap
+ * templates`, the consolidated home): "pod unreachable" must not read as "no
+ * workspaces / stand one up" — the same false-empty trap `fetchInstalledTemplatesStrict`
+ * exists to prevent.
+ */
+export declare function fetchWorkspaceAttachmentsStrict(cfg?: HubConfig): Promise<WorkspaceAttachment[]>;
+export declare function fetchWorkspaceAttachments(cfg?: HubConfig): Promise<WorkspaceAttachment[]>;
 /**
  * The set of `packageSlug`s installed on the active pod. Empty on ANY failure
  * (no pod configured, unreachable, older build without the field) — the caller
  * simply shows no "installed" markers.
  */
 export declare function fetchInstalledSlugs(): Promise<Set<string>>;
+export {};

package/dist/lib/installed.js

@@ -12,51 +12,249 @@
  * build, this degrades to an empty set (no markers) rather than failing the
  * discovery command — you can always browse the catalog offline.
  */
-import { resolveHubConfig, hubGet } from "./hub-client.js";
+import { resolveHubConfig, hubGet, HubError } from "./hub-client.js";
+import { parseLifecycle, parseOverlays, parsePendingDataChanges, parseUpdateProposal, } from "./template-lifecycle.js";
+// ── THE ONE READ DOOR — `GET /api/hub/installed` ────────────────────────────
+//
+// The pod projects all FOUR install ledgers it already maintains (workspaces,
+// capability containers, marketSource-linked view/skill/automation rows, and
+// package cells) through one kind-agnostic route. Before it existed this file
+// asked `GET /workspaces` and nothing else, so `market installed` /
+// `market update` / every drift marker structurally reported ONE of six kinds
+// while their names claimed all of them.
+//
+// Two calls, deliberately, both cheap and local to the pod:
+//   • `/installed` — the six kinds. Absent on an older pod (404).
+//   • `/workspaces` — for TWO things `/installed` does not carry:
+//       1. the workspace id→name join (`/installed` reports each ROW's own
+//          name — a view's title, not its workspace's), and
+//       2. `settings.installedPacks[]`, an additive-pack ledger `/installed`
+//          reads only to decide whether a workspace counts as installed, and
+//          never emits rows for. Dropping it would un-list (and make
+//          un-updatable) every additive pack — a coverage regression in the
+//          exact command this consolidation exists to widen.
+/** Every kind the door can report. Mirrors the pod's `INSTALLED_KINDS`. */
+export const INSTALLED_KINDS = [
+    "workspace",
+    "capability",
+    "view",
+    "skill",
+    "automation",
+    "cell",
+];
+/** `GET /installed`, or `null` when this pod is too old to serve it. Any other failure throws. */
+async function getInstalledOrNull(cfg) {
+    try {
+        return (await hubGet("/installed", {}, cfg));
+    }
+    catch (e) {
+        if (e instanceof HubError && e.status === 404)
+            return null;
+        throw e;
+    }
+}
 /**
- * Every installed workspace's `{slug, version, workspaceId, workspaceName}` —
- * the raw material for "what's installed" (`fetchInstalledSlugs`) and "what's
- * out of date" (`market update`'s `computeUpdates`). One Hub call, derived
- * views. Unions TWO install shapes, mirroring the browser's
- * `useInstalledPackageSlugs` (see that hook's doc for the full rationale):
+ * STRICT inventory — THROWS on any pod failure except the older-pod 404, which
+ * degrades to the historical `/workspaces` behaviour with `degraded: true`.
+ * Absence of the route is not absence of installs.
+ */
+export async function fetchInstalledInventoryStrict(cfg) {
+    const resolved = cfg ?? (await resolveHubConfig());
+    const [wsRes, installedRes] = await Promise.all([
+        hubGet("/workspaces", {}, resolved),
+        getInstalledOrNull(resolved),
+    ]);
+    const wsRows = wsRes.workspaces ?? [];
+    const nameById = new Map(wsRows.map((w) => [w.id, w.name]));
+    // Additive packs — the ledger `/installed` never emits rows for (see above).
+    const packRows = [];
+    for (const ws of wsRows) {
+        for (const pack of ws.installedPacks ?? []) {
+            if (!pack?.slug)
+                continue;
+            packRows.push({
+                kind: "workspace",
+                id: `${ws.id}:${pack.slug}`,
+                name: pack.slug,
+                packageSlug: pack.slug,
+                templateKey: null,
+                installedVersion: pack.version ?? null,
+                latestVersion: null,
+                // The pod never version-stamped or health-checked an additive pack, so
+                // it cannot be computed here either. `null`, not a defaulted `false`.
+                drift: null,
+                installedAt: null,
+                workspaceId: ws.id,
+                workspaceName: ws.name,
+                provisioningStatus: null,
+                failedStep: null,
+            });
+        }
+    }
+    if (!installedRes) {
+        // Older pod: rebuild the workspace rows exactly as this file always did.
+        const wsOnly = wsRows
+            .filter((ws) => !!ws.packageSlug)
+            .map((ws) => ({
+            kind: "workspace",
+            id: ws.id,
+            name: ws.name,
+            packageSlug: ws.packageSlug,
+            templateKey: null,
+            installedVersion: ws.packageVersion ?? null,
+            latestVersion: ws.latestVersion ?? null,
+            drift: ws.drifted ?? null,
+            installedAt: null,
+            workspaceId: ws.id,
+            workspaceName: ws.name,
+            provisioningStatus: null,
+            failedStep: null,
+        }));
+        return { rows: [...wsOnly, ...packRows], driftComputed: false, degraded: true };
+    }
+    const rows = (installedRes.installed ?? []).map((r) => ({
+        ...r,
+        workspaceName: r.workspaceId ? (nameById.get(r.workspaceId) ?? null) : null,
+    }));
+    return {
+        rows: [...rows, ...packRows],
+        driftComputed: installedRes.driftComputed === true,
+        degraded: false,
+    };
+}
+/** Non-fatal inventory — empty (and NOT degraded) on any failure, for markers that must never block discovery. */
+export async function fetchInstalledInventory(cfg) {
+    try {
+        return await fetchInstalledInventoryStrict(cfg);
+    }
+    catch {
+        return { rows: [], driftComputed: false, degraded: false };
+    }
+}
+/**
+ * The UPDATABLE subset of an inventory, in the shape `computeUpdates` /
+ * `market update` / the composition renderers already speak.
  *
- *  1. `workspace.packageSlug` — a workspace-creating install (template).
- *  2. `workspace.settings.installedPacks[]` — additive packs (profile/view/
- *     bento) that create no workspace of their own, so never set `packageSlug`.
+ * Rows with `packageSlug: null` are dropped ON PURPOSE — they are inventory,
+ * not update targets: `market update` takes a catalog SLUG, and a capability's
+ * `templateKey` is not one. Feeding them through would hand the user a slug
+ * that misses the catalog. `market installed` renders them separately.
  *
- * A workspace carrying BOTH contributes one row per shape — they're different
- * package identities layered onto the same workspace.
+ * `drift: null` maps to `drifted: undefined`, which is `computeUpdates`'
+ * long-standing "the server didn't answer — derive it client-side, and report
+ * an unstampable install as noVersionInfo rather than outdated" path. It is
+ * NEVER mapped to `drifted: false`.
  */
-export async function fetchInstalledTemplates() {
+export function installedRowsToTemplates(rows) {
     const out = [];
+    for (const r of rows) {
+        if (!r.packageSlug)
+            continue;
+        out.push({
+            kind: r.kind,
+            slug: r.packageSlug,
+            version: r.installedVersion ?? undefined,
+            workspaceId: r.workspaceId,
+            workspaceName: r.workspaceName ?? (r.workspaceId ? r.workspaceId : "pod-wide"),
+            latestVersion: r.latestVersion ?? undefined,
+            drifted: r.drift ?? undefined,
+        });
+    }
+    return out;
+}
+/**
+ * STRICT variant — THROWS on any pod failure instead of degrading to empty.
+ * Use when the caller must tell "pod unreachable" apart from "genuinely
+ * nothing installed": `market update` otherwise reports a transient Hub error
+ * as "No installed packages found," which reads as data loss and is why the
+ * command felt random (empty on one call, full on the next).
+ *
+ * Sources from `fetchInstalledInventoryStrict` — so every consumer of this
+ * function (`market update`, `launch --list`, the picker, `fetchInstalledSlugs`)
+ * now sees ALL SIX kinds on a current pod, and exactly the old workspace-only
+ * set on an older one.
+ */
+export async function fetchInstalledTemplatesStrict() {
+    const inv = await fetchInstalledInventoryStrict();
+    return installedRowsToTemplates(inv.rows);
+}
+export async function fetchInstalledTemplates() {
     try {
-        const cfg = await resolveHubConfig();
-        const res = (await hubGet("/workspaces", {}, cfg));
-        for (const ws of res.workspaces ?? []) {
-            if (ws.packageSlug) {
-                out.push({
-                    slug: ws.packageSlug,
-                    version: ws.packageVersion ?? undefined,
-                    workspaceId: ws.id,
-                    workspaceName: ws.name,
-                });
-            }
-            for (const pack of ws.installedPacks ?? []) {
-                if (pack?.slug) {
-                    out.push({
-                        slug: pack.slug,
-                        version: pack.version,
-                        workspaceId: ws.id,
-                        workspaceName: ws.name,
-                    });
-                }
-            }
-        }
+        return await fetchInstalledTemplatesStrict();
     }
     catch {
-        // Non-fatal: degrade to empty. Discovery never depends on the pod.
+        // Non-fatal: degrade to empty. Discovery/markers never depend on the pod.
+        return [];
+    }
+}
+/**
+ * Ground-truth stamp verification — re-reads ONE workspace's stored
+ * `packageVersion` after an apply to confirm a version stamp actually landed,
+ * instead of INFERRING it from the apply response's `outcome` (a proxy that
+ * false-positives whenever content was already identical, so `outcome` comes
+ * back `"unchanged"` even though the stamp was written). Returns:
+ *   - `true`  — the workspace now carries the expected version (stamp landed).
+ *   - `false` — reached the pod, but the stamp is missing/different (old pod
+ *               that doesn't stamp on reconcile, or a real failure).
+ *   - `null`  — couldn't reach/find the workspace; don't cry wolf on a verify
+ *               failure — the apply itself already succeeded.
+ */
+export async function verifyStampLanded(workspaceId, expectedVersion, cfg) {
+    try {
+        const resolved = cfg ?? (await resolveHubConfig());
+        const res = (await hubGet("/workspaces", {}, resolved));
+        const ws = (res.workspaces ?? []).find((w) => w.id === workspaceId);
+        if (!ws)
+            return null;
+        return (ws.packageVersion ?? null) === expectedVersion;
+    }
+    catch {
+        return null;
+    }
+}
+export function mapWorkspaceAttachments(rows) {
+    return rows.map((ws) => ({
+        workspaceId: ws.id,
+        workspaceName: ws.name,
+        domain: ws.workspaceSubtype ?? ws.workspaceType ?? null,
+        packageSlug: ws.packageSlug ?? null,
+        packageVersion: ws.packageVersion ?? null,
+        latestVersion: ws.latestVersion ?? undefined,
+        drifted: ws.drifted,
+        lifecycle: parseLifecycle(ws),
+        overlays: parseOverlays(ws),
+        awaitingApproval: Array.isArray(ws.awaitingApproval)
+            ? ws.awaitingApproval.filter((p) => typeof p === "string")
+            : undefined,
+        applyWarning: typeof ws.applyWarning === "string" ? ws.applyWarning : null,
+        state: typeof ws.state === "string" ? ws.state : null,
+        pendingDataChanges: parsePendingDataChanges(ws),
+        updateProposal: parseUpdateProposal(ws),
+        stepWarnings: Array.isArray(ws.stepWarnings)
+            ? ws.stepWarnings.filter((w) => typeof w === "string" && w.trim() !== "")
+            : [],
+    }));
+}
+/**
+ * STRICT variant — THROWS on any pod failure instead of degrading to empty.
+ * Use where an empty result would be a LIE about the user's pod (e.g. `synap
+ * templates`, the consolidated home): "pod unreachable" must not read as "no
+ * workspaces / stand one up" — the same false-empty trap `fetchInstalledTemplatesStrict`
+ * exists to prevent.
+ */
+export async function fetchWorkspaceAttachmentsStrict(cfg) {
+    const resolved = cfg ?? (await resolveHubConfig());
+    const res = (await hubGet("/workspaces", {}, resolved));
+    return mapWorkspaceAttachments(res.workspaces ?? []);
+}
+export async function fetchWorkspaceAttachments(cfg) {
+    try {
+        return await fetchWorkspaceAttachmentsStrict(cfg);
+    }
+    catch {
+        // Non-fatal: degrade to empty. Discovery/markers never hard-depend on the pod.
+        return [];
     }
-    return out;
 }
 /**
  * The set of `packageSlug`s installed on the active pod. Empty on ANY failure

package/dist/lib/installed.js.map

@@ -1 +1 @@
-{"version":3,"file":"installed.js","sourceRoot":"","sources":["../../src/lib/installed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAmB3D;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB;IAC3C,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,gBAAgB,EAAE,CAAC;QACrC,MAAM,GAAG,GAAG,CAAC,MAAM,MAAM,CAAC,aAAa,EAAE,EAAE,EAAE,GAAG,CAAC,CAQhD,CAAC;QACF,KAAK,MAAM,EAAE,IAAI,GAAG,CAAC,UAAU,IAAI,EAAE,EAAE,CAAC;YACtC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;gBACnB,GAAG,CAAC,IAAI,CAAC;oBACP,IAAI,EAAE,EAAE,CAAC,WAAW;oBACpB,OAAO,EAAE,EAAE,CAAC,cAAc,IAAI,SAAS;oBACvC,WAAW,EAAE,EAAE,CAAC,EAAE;oBAClB,aAAa,EAAE,EAAE,CAAC,IAAI;iBACvB,CAAC,CAAC;YACL,CAAC;YACD,KAAK,MAAM,IAAI,IAAI,EAAE,CAAC,cAAc,IAAI,EAAE,EAAE,CAAC;gBAC3C,IAAI,IAAI,EAAE,IAAI,EAAE,CAAC;oBACf,GAAG,CAAC,IAAI,CAAC;wBACP,IAAI,EAAE,IAAI,CAAC,IAAI;wBACf,OAAO,EAAE,IAAI,CAAC,OAAO;wBACrB,WAAW,EAAE,EAAE,CAAC,EAAE;wBAClB,aAAa,EAAE,EAAE,CAAC,IAAI;qBACvB,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,mEAAmE;IACrE,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB;IACvC,MAAM,SAAS,GAAG,MAAM,uBAAuB,EAAE,CAAC;IAClD,OAAO,IAAI,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AAC/C,CAAC"}
+{"version":3,"file":"installed.js","sourceRoot":"","sources":["../../src/lib/installed.ts"],"names":[],"mappings":"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"}

package/dist/lib/key-approval.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Waiting for a pending agent key to be approved — and resuming that wait.
+ *
+ * Two rules, both learnt from the 2026-10-12 incident:
+ *
+ *  1. The wait asks about the PENDING key, presenting the pending key itself
+ *     (`/auth/key-state`). The old poll authenticated with the person's own
+ *     key — which, mid-incident, was the very key the approval had just
+ *     revoked, so the poll could never see the approval land.
+ *  2. A request is never filed twice. A minted-but-unapproved key is recorded
+ *     (`pendingAgentKeys`); the next connect / `doctor --fix` resumes it. Three
+ *     orphaned requests accumulated in one evening before this.
+ */
+import { type FetchLike, type KeyState } from "./key-state.js";
+import type { PendingAgentKey } from "./pod.js";
+/** The approval did not land in time. The request stays filed and resumable. */
+export declare class AgentKeyAwaitingApprovalError extends Error {
+    readonly agentType: string;
+    readonly approvalUrl: string;
+    constructor(agentType: string, approvalUrl: string);
+}
+export type KeyWaitOutcome = "approved" | "rejected" | "timeout";
+export interface WaitForKeyLiveOpts {
+    podUrl: string;
+    /** The pending key's own plaintext — the bearer for `/auth/key-state`. */
+    pendingKey: string;
+    /** Older pods: its id, polled on `/setup/agent/pending/:id` with the human key. */
+    pendingToken?: string;
+    humanApiKey?: string;
+    timeoutMs?: number;
+    intervalMs?: number;
+    fetch?: FetchLike;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Wait until the pod says the key is live (`approved`), refused
+ * (`rejected`: revoked / expired / unknown), or the deadline passes.
+ * Transient failures never end the wait early.
+ */
+export declare function waitForKeyLive(opts: WaitForKeyLiveOpts): Promise<KeyWaitOutcome>;
+/**
+ * What a recorded pending key is now: still waiting (resume it), live
+ * (approved while we were away — promote it), or dead (forget it, file anew).
+ * An unreachable pod keeps it recorded and says so (`unknown`).
+ */
+export declare function classifyRecordedPending(pending: PendingAgentKey, deps?: {
+    fetch?: FetchLike;
+}): Promise<{
+    kind: "pending" | "active" | "dead" | "unknown";
+    state: KeyState;
+}>;
+/**
+ * Print the approval link, open it, and wait — the one interactive wait.
+ * The link came from the pod: it is opened only when it is on that pod's own
+ * origin or its pod-admin origin (`openPodPage`), never anywhere else.
+ */
+export declare function openAndWait(agentType: string, approvalUrl: string, podUrl: string, wait: () => Promise<KeyWaitOutcome>, openUrl: (url: string) => void): Promise<KeyWaitOutcome>;