@vellumai/assistant 0.10.8 → 0.10.9-dev.202607152225.ec6fdbf

package/src/channels/gateway-guardian-requests.ts

@@ -0,0 +1,410 @@
+/**
+ * Gateway-backed guardian-request client.
+ *
+ * Typed async wrappers over the gateway's `guardian_requests_*` IPC routes.
+ * The gateway owns the `guardian_requests` and `guardian_request_deliveries`
+ * tables and applies decision ACL outcomes in the same transaction as the
+ * status CAS; the daemon relays lifecycle operations here and keeps
+ * notifications, card withdrawal, and other daemon-domain side effects.
+ * Responses are validated against the shared contract schemas in
+ * `@vellumai/gateway-client` — the same schemas the gateway routes are
+ * pinned to.
+ *
+ * Error posture (fail-closed — there is no local fallback):
+ * - Lifecycle writes (create, update, decide, expire, sweep, delivery
+ *   writes) THROW on any transport failure or malformed response. A guardian
+ *   decision that cannot persist must fail loudly, never fake success.
+ * - Reads used for hints/dedup/scope THROW by default; ones whose only
+ *   callers are deny paths that must degrade to "no data" instead of
+ *   blocking are exported solely as a degrading variant (`...OrNull` /
+ *   `...OrEmpty` / `...OrFalse`) that logs the failure and returns the
+ *   empty value.
+ */
+
+import {
+  type CreateGuardianRequestDeliveryIpcParams,
+  CreateGuardianRequestDeliveryIpcResponseSchema,
+  type CreateGuardianRequestIpcParams,
+  CreateGuardianRequestIpcResponseSchema,
+  type DecideGuardianRequestIpcParams,
+  type DecideGuardianRequestIpcResponse,
+  DecideGuardianRequestIpcResponseSchema,
+  ExpireInteractionBoundIpcResponseSchema,
+  GUARDIAN_REQUESTS_IPC_METHODS,
+  GuardianRequestDeliveryListIpcResponseSchema,
+  type GuardianRequestDeliveryWire,
+  GuardianRequestInScopeIpcResponseSchema,
+  GuardianRequestListIpcResponseSchema,
+  GuardianRequestLookupIpcResponseSchema,
+  GuardianRequestMutationIpcResponseSchema,
+  type GuardianRequestPatch,
+  type GuardianRequestsIpcMethod,
+  type GuardianRequestWire,
+  type ListGuardianRequestsIpcParams,
+  type ListPendingGuardianRequestsByDestinationIpcParams,
+  SweepExpiredGuardianRequestsIpcResponseSchema,
+  type UpdateGuardianRequestDeliveryIpcParams,
+} from "@vellumai/gateway-client";
+import type { ZodType } from "zod";
+
+import { ipcCallPersistentValidated } from "../ipc/gateway-validated-call.js";
+import { getLogger } from "../util/logger.js";
+
+export type {
+  CreateGuardianRequestIpcParams,
+  DecideGuardianRequestIpcParams,
+  DecideGuardianRequestIpcResponse,
+  GuardianRequestAclOutcome,
+  GuardianRequestDeliveryWire,
+  GuardianRequestPatch,
+  GuardianRequestStatus,
+  GuardianRequestWire,
+} from "@vellumai/gateway-client";
+
+const log = getLogger("gateway-guardian-requests");
+
+/**
+ * Call a gateway guardian-request route and validate the response against
+ * its contract schema. Throws on transport failure or a malformed response
+ * (shared helper; typed to the guardian-request method union).
+ */
+async function callGateway<T>(
+  method: GuardianRequestsIpcMethod,
+  params: Record<string, unknown>,
+  responseSchema: ZodType<T>,
+): Promise<T> {
+  return ipcCallPersistentValidated(method, params, responseSchema);
+}
+
+/** Call a mutation route; throws unless the gateway acks `{ ok: true }`. */
+async function callMutation(
+  method: GuardianRequestsIpcMethod,
+  params: Record<string, unknown>,
+): Promise<void> {
+  await callGateway(method, params, GuardianRequestMutationIpcResponseSchema);
+}
+
+/**
+ * Wrap a read so any failure — transport included — degrades to `fallback`
+ * (logged) instead of throwing, for deny-path callers.
+ */
+function degradeOnFailure<Args extends unknown[], T>(
+  read: (...args: Args) => Promise<T>,
+  fallback: T,
+): (...args: Args) => Promise<T> {
+  return async (...args: Args): Promise<T> => {
+    try {
+      return await read(...args);
+    } catch (err) {
+      log.warn(
+        { err, read: read.name },
+        "gateway guardian-request read degraded to fallback",
+      );
+      return fallback;
+    }
+  };
+}
+
+/**
+ * Create a guardian request. `id` and `guardianPrincipalId` are required —
+ * request ids are caller-supplied and load-bearing. Throws on any failure
+ * (fail-closed).
+ */
+export async function createGuardianRequest(
+  params: CreateGuardianRequestIpcParams,
+): Promise<GuardianRequestWire> {
+  return callGateway(
+    GUARDIAN_REQUESTS_IPC_METHODS.create,
+    params as unknown as Record<string, unknown>,
+    CreateGuardianRequestIpcResponseSchema,
+  );
+}
+
+/** Look up a guardian request by id. Throws on transport failure. */
+export async function getGuardianRequest(
+  id: string,
+): Promise<GuardianRequestWire | null> {
+  return callGateway(
+    GUARDIAN_REQUESTS_IPC_METHODS.get,
+    { id },
+    GuardianRequestLookupIpcResponseSchema,
+  );
+}
+
+/** `getGuardianRequest` for deny-path callers: failures degrade to null. */
+export const getGuardianRequestOrNull = degradeOnFailure(
+  getGuardianRequest,
+  null,
+);
+
+/**
+ * Look up a PENDING guardian request by its short request code. Throws on
+ * transport failure.
+ */
+async function getGuardianRequestByCode(
+  code: string,
+): Promise<GuardianRequestWire | null> {
+  return callGateway(
+    GUARDIAN_REQUESTS_IPC_METHODS.getByCode,
+    { code },
+    GuardianRequestLookupIpcResponseSchema,
+  );
+}
+
+/** `getGuardianRequestByCode` for deny-path callers: degrades to null. */
+export const getGuardianRequestByCodeOrNull = degradeOnFailure(
+  getGuardianRequestByCode,
+  null,
+);
+
+/** List guardian requests matching the filters. Throws on transport failure. */
+async function listGuardianRequests(
+  filters: ListGuardianRequestsIpcParams = {},
+): Promise<GuardianRequestWire[]> {
+  return callGateway(
+    GUARDIAN_REQUESTS_IPC_METHODS.list,
+    filters as unknown as Record<string, unknown>,
+    GuardianRequestListIpcResponseSchema,
+  );
+}
+
+/** `listGuardianRequests` for deny-path callers: degrades to []. */
+export const listGuardianRequestsOrEmpty = degradeOnFailure(
+  listGuardianRequests,
+  [],
+);
+
+/** Apply a partial patch to a guardian request. Throws on any failure. */
+export async function updateGuardianRequest(
+  id: string,
+  patch: GuardianRequestPatch,
+): Promise<void> {
+  await callMutation(GUARDIAN_REQUESTS_IPC_METHODS.update, { id, patch });
+}
+
+/**
+ * Decide a pending guardian request: status CAS plus the optional ACL
+ * outcome, committed in one gateway transaction. A CAS miss returns
+ * `{ applied: false, reason: "status_conflict" }` with zero side effects;
+ * on success `mintedSession` carries the raw outbound-session secret when
+ * the outcome minted one. Throws on any transport failure or malformed
+ * response (fail-closed — a decision that cannot persist fails loudly).
+ */
+export async function decideGuardianRequest(
+  params: DecideGuardianRequestIpcParams,
+): Promise<DecideGuardianRequestIpcResponse> {
+  return callGateway(
+    GUARDIAN_REQUESTS_IPC_METHODS.decide,
+    params as unknown as Record<string, unknown>,
+    DecideGuardianRequestIpcResponseSchema,
+  );
+}
+
+/**
+ * Expire a pending request (CAS pending → expired; the gateway also expires
+ * its deliveries). Throws on any failure (fail-closed).
+ */
+export async function expireGuardianRequest(id: string): Promise<void> {
+  await callMutation(GUARDIAN_REQUESTS_IPC_METHODS.expire, { id });
+}
+
+/**
+ * Daemon-boot expiry: interaction-bound kinds die with the daemon's
+ * in-memory pendingInteractions map, plus persistent kinds already past
+ * `expiresAt`. Returns the expired count. Throws on any failure
+ * (fail-closed).
+ */
+export async function expireInteractionBoundGuardianRequests(): Promise<number> {
+  const response = await callGateway(
+    GUARDIAN_REQUESTS_IPC_METHODS.expireInteractionBound,
+    {},
+    ExpireInteractionBoundIpcResponseSchema,
+  );
+  return response.expired;
+}
+
+/**
+ * Sweep persistent requests past their `expiresAt` (gateway CAS-expires;
+ * `now` defaults gateway-side). Returns the expired rows so the daemon fan-out
+ * needs no follow-up read. Throws on any failure (fail-closed).
+ */
+export async function sweepExpiredGuardianRequests(
+  now?: number,
+): Promise<GuardianRequestWire[]> {
+  const response = await callGateway(
+    GUARDIAN_REQUESTS_IPC_METHODS.sweepExpired,
+    { now },
+    SweepExpiredGuardianRequestsIpcResponseSchema,
+  );
+  return response.expired;
+}
+
+/**
+ * Record a delivery of a guardian-request card to a destination. Throws on
+ * any failure (fail-closed).
+ */
+export async function createGuardianRequestDelivery(
+  params: CreateGuardianRequestDeliveryIpcParams,
+): Promise<GuardianRequestDeliveryWire> {
+  return callGateway(
+    GUARDIAN_REQUESTS_IPC_METHODS.createDelivery,
+    params as unknown as Record<string, unknown>,
+    CreateGuardianRequestDeliveryIpcResponseSchema,
+  );
+}
+
+/** Patch a delivery record. Throws on any failure (fail-closed). */
+export async function updateGuardianRequestDelivery(
+  id: string,
+  patch: UpdateGuardianRequestDeliveryIpcParams["patch"],
+): Promise<void> {
+  await callMutation(GUARDIAN_REQUESTS_IPC_METHODS.updateDelivery, {
+    id,
+    patch,
+  });
+}
+
+/** List a request's delivery records. Throws on transport failure. */
+export async function listGuardianRequestDeliveries(
+  requestId: string,
+): Promise<GuardianRequestDeliveryWire[]> {
+  return callGateway(
+    GUARDIAN_REQUESTS_IPC_METHODS.listDeliveries,
+    { requestId },
+    GuardianRequestDeliveryListIpcResponseSchema,
+  );
+}
+
+/** `listGuardianRequestDeliveries` for deny-path callers: degrades to []. */
+export const listGuardianRequestDeliveriesOrEmpty = degradeOnFailure(
+  listGuardianRequestDeliveries,
+  [],
+);
+
+/**
+ * Reaction routing: the pending request whose delivered card is the
+ * reacted-to message. Throws on transport failure.
+ */
+async function getPendingRequestByDestinationMessage(
+  channel: string,
+  chatId: string,
+  messageId: string,
+): Promise<GuardianRequestWire | null> {
+  return callGateway(
+    GUARDIAN_REQUESTS_IPC_METHODS.getByDestinationMessage,
+    { channel, chatId, messageId },
+    GuardianRequestLookupIpcResponseSchema,
+  );
+}
+
+/** `getPendingRequestByDestinationMessage` deny-path variant: degrades to null. */
+export const getPendingRequestByDestinationMessageOrNull = degradeOnFailure(
+  getPendingRequestByDestinationMessage,
+  null,
+);
+
+/**
+ * Reply routing: pending requests delivered to a destination conversation
+ * (`conversationId`, optionally narrowed by `channel`) or chat
+ * (`channel` + `chatId`). Throws on transport failure.
+ */
+async function listPendingRequestsByDestination(
+  params: ListPendingGuardianRequestsByDestinationIpcParams,
+): Promise<GuardianRequestWire[]> {
+  return callGateway(
+    GUARDIAN_REQUESTS_IPC_METHODS.listPendingByDestination,
+    params as unknown as Record<string, unknown>,
+    GuardianRequestListIpcResponseSchema,
+  );
+}
+
+/** `listPendingRequestsByDestination` deny-path variant: degrades to []. */
+export const listPendingRequestsByDestinationOrEmpty = degradeOnFailure(
+  listPendingRequestsByDestination,
+  [],
+);
+
+/**
+ * Pending requests sourced from OR delivered to the conversation,
+ * deduplicated, non-expired. Throws on transport failure.
+ */
+export async function listPendingRequestsByScope(
+  conversationId: string,
+  channel?: string,
+): Promise<GuardianRequestWire[]> {
+  return callGateway(
+    GUARDIAN_REQUESTS_IPC_METHODS.listPendingByScope,
+    { conversationId, channel },
+    GuardianRequestListIpcResponseSchema,
+  );
+}
+
+/** `listPendingRequestsByScope` deny-path variant: degrades to []. */
+export const listPendingRequestsByScopeOrEmpty = degradeOnFailure(
+  listPendingRequestsByScope,
+  [],
+);
+
+/**
+ * Is a decision from this conversation allowed for the request (source
+ * match, or delivery match optionally narrowed by `channel`)? Throws on
+ * transport failure.
+ */
+async function isGuardianRequestInScope(
+  requestId: string,
+  conversationId: string,
+  channel?: string,
+): Promise<boolean> {
+  const response = await callGateway(
+    GUARDIAN_REQUESTS_IPC_METHODS.inScope,
+    { requestId, conversationId, channel },
+    GuardianRequestInScopeIpcResponseSchema,
+  );
+  return response.inScope;
+}
+
+/** `isGuardianRequestInScope` deny-path variant: degrades to false (not in scope). */
+export const isGuardianRequestInScopeOrFalse = degradeOnFailure(
+  isGuardianRequestInScope,
+  false,
+);
+
+/**
+ * Latest pending request for a live voice call session (mid-call guardian
+ * wait polling). Throws on transport failure.
+ */
+export async function getPendingRequestByCallSession(
+  callSessionId: string,
+): Promise<GuardianRequestWire | null> {
+  return callGateway(
+    GUARDIAN_REQUESTS_IPC_METHODS.getByCallSession,
+    { callSessionId },
+    GuardianRequestLookupIpcResponseSchema,
+  );
+}
+
+/** `getPendingRequestByCallSession` deny-path variant: degrades to null. */
+export const getPendingRequestByCallSessionOrNull = degradeOnFailure(
+  getPendingRequestByCallSession,
+  null,
+);
+
+/**
+ * The request carrying a specific voice pending-question id. Throws on
+ * transport failure.
+ */
+async function getRequestByPendingQuestion(
+  pendingQuestionId: string,
+): Promise<GuardianRequestWire | null> {
+  return callGateway(
+    GUARDIAN_REQUESTS_IPC_METHODS.getByPendingQuestion,
+    { pendingQuestionId },
+    GuardianRequestLookupIpcResponseSchema,
+  );
+}
+
+/** `getRequestByPendingQuestion` deny-path variant: degrades to null. */
+export const getRequestByPendingQuestionOrNull = degradeOnFailure(
+  getRequestByPendingQuestion,
+  null,
+);

package/src/channels/types.ts

@@ -150,6 +150,10 @@ export const INTERFACE_IDS = [
   "email",
   "chrome-extension",
   "a2a",
+  // Turns injected by workspace custom routes (webhook receivers, cron jobs,
+  // device/service callbacks). Non-interactive — permission prompts route
+  // through the guardian system, not an interactive client — and non-host-proxy.
+  "route",
 ] as const;
 
 export type InterfaceId = (typeof INTERFACE_IDS)[number];
@@ -227,7 +231,7 @@ export function isInteractiveInterface(id: InterfaceId): boolean {
 
 /**
  * Host proxy capabilities that an interface can support. The macOS client
- * supports all five; the chrome-extension interface only supports
+ * supports all of them; the chrome-extension interface only supports
  * host_browser (via the Chrome DevTools Protocol proxy).
  */
 export type HostProxyCapability =
@@ -235,11 +239,12 @@ export type HostProxyCapability =
   | "host_file"
   | "host_cu"
   | "host_browser"
-  | "host_app_control";
+  | "host_app_control"
+  | "host_ui_snapshot";
 
 /**
- * Interfaces that support the full desktop host-proxy set (all five
- * `HostProxyCapability` values). This is the capability-level identity used
+ * Interfaces that support the full desktop host-proxy set (every
+ * `HostProxyCapability` value). This is the capability-level identity used
  * by the discriminated transport metadata union and by the
  * `supportsHostProxy(id)` type predicate.
  *
@@ -272,7 +277,7 @@ export function supportsHostProxy(
   id: InterfaceId,
   capability?: HostProxyCapability,
 ): boolean {
-  // macOS supports all five host proxy capabilities including host_browser
+  // macOS supports every host proxy capability including host_browser
   // and host_app_control. The host_browser proxy is provisioned via the
   // assistant event hub. When no extension is connected, browser tools fall
   // through to cdp-inspect/local via the CDP factory's candidate chain.

package/src/cli/AGENTS.md

@@ -30,7 +30,7 @@ Every namespace that manages a resource (schedules, contacts, tasks, …) must e
 
 CLI commands use one of two transport patterns depending on whether they need a running daemon:
 
-- **`ipc`-tagged commands** call `cliIpcCall` from `../../ipc/cli-client.js`. They are thin wrappers that forward requests to the daemon over the IPC socket and never import daemon-internal modules.
+- **`ipc`-tagged commands** call `cliIpcCall` from `../../ipc/cli-client.js`. They forward requests to the daemon over the IPC socket for state the daemon owns.
 - **`local`-tagged commands** read or write workspace files directly (config, autonomy, completions, etc.) using the same config/store helpers the daemon uses internally. They do not require the daemon to be running.
 
 Both transport classes avoid proxying through the gateway HTTP API. `ipc` commands reach the daemon directly via the socket; `local` commands bypass the daemon entirely. The transport tag is declared via `registerCommand({ transport, ... })` — see the "Transport tagging" section below.
@@ -40,19 +40,22 @@ Both transport classes avoid proxying through the gateway HTTP API. `ipc` comman
 Every command file declares its transport class via `registerCommand({ transport, ... })`
 from `../lib/register-command.ts`. The three transport classes are:
 
-| Class | Rule | When to use |
-|---|---|---|
-| `ipc` | Wraps exactly one IPC method per subcommand. No daemon-internal imports. | Commands that call the daemon |
-| `local` | Touches only static workspace files / shell artifacts. | Commands that work without a running daemon |
-| `bootstrap` | Runs before the daemon is up (e.g. `assistant config init`). | Pre-daemon setup |
+| Class       | Rule                                                            | When to use                                 |
+| ----------- | --------------------------------------------------------------- | ------------------------------------------- |
+| `ipc`       | Reaches the daemon (over IPC, or in-process via a lazy import). | Commands that call the daemon               |
+| `local`     | Touches only static workspace files / shell artifacts.          | Commands that work without a running daemon |
+| `bootstrap` | Runs before the daemon is up (e.g. `assistant config init`).    | Pre-daemon setup                            |
 
-The ESLint rule `cli/no-daemon-internals` enforces import allowlists per class.
+The tag is descriptive metadata; keep it accurate so readers can tell at a
+glance whether a command needs a running daemon.
 
 ## Anatomy of an `ipc` command
 
-The thin-wrapper pattern. Every `ipc`-tagged subcommand action does three
-things: parse argv → call one IPC method → format output. The business
-logic lives in the daemon route, not the CLI.
+An `ipc`-tagged subcommand action parses argv, reaches the daemon — over
+IPC for daemon-owned state, or by running a lazily-imported helper
+in-process — and formats output. Prefer in-process where it saves an IPC
+round-trip; prefer IPC when the daemon owns the state or a running
+instance must do the work.
 
 ### Required shape
 
@@ -100,63 +103,85 @@ registerFooCommand(program);
 
 ### Rules
 
-1. **One `registerCommand` call per file.** The options object MUST be
-   passed inline as an object literal; `name` and `transport` MUST be
-   string literals. Hoisted variables and `as const` casts break the
-   static analysis tools rely on.
-
-2. **No daemon-internal imports.** An `ipc` command file can import:
-
-   - the IPC client (`../../ipc/cli-client`)
-   - the Commander framework + Node stdlib (`commander`, `node:*`)
-   - shared CLI helpers (`../logger`, `../output`, `../lib/*`,
-     `../../utils/*`)
-   - sibling subcommand modules (`./connect`, etc. — for namespace
-     parents like `oauth/index.ts`)
-
-   It **cannot** import anything under `runtime/`, `services/`,
-   `agents/`, `llm/`, `skills/`, or any other daemon-internal namespace.
-   The `cli/no-daemon-internals` ESLint rule enforces this at `"error"`
-   severity. See `assistant/eslint-rules/cli-no-daemon-internals.js` for
-   the per-transport allowlist (including per-command escape hatches for
-   things like the `keys` security helpers and `credential-execution`
-   bridge).
-
-3. **One IPC call per subcommand action.** A thin wrapper does not
-   compose multiple IPC methods, does not validate beyond Commander's
-   argument parsing, and does not reshape the daemon response.
-   Composition belongs on the daemon side, in a route.
-
-4. **Always check `r.ok` before reading `r.result`.** `cliIpcCall`
+1. **Keep hoisted imports inside the CLI.** A command module's top-level
+   (hoisted) imports are loaded on every `assistant …` invocation, so
+   they must stay light. You may hoist Node/npm packages, modules within
+   `assistant/src/cli`, and the shared non-daemon leaf zones `util/`,
+   `ipc/` (the IPC client + socket path), `types/`, and `version`.
+   Type-only imports (`import type …`) are always fine — they are erased
+   and cost nothing at runtime.
+
+   **Do not hoist imports of daemon functionality** — anything else
+   outside `assistant/src/cli` (`runtime/`, `daemon/`, `persistence/`,
+   `providers/`, `platform/`, `security/`, …). Hoisting it pulls the
+   daemon's module graph into every CLI process and inflates its memory
+   footprint. This is enforced by the `cli/no-daemon-internals` ESLint
+   rule (`error`): a hoisted import that resolves outside the CLI tree and
+   the leaf zones above fails lint. Lazy-import it instead (rule 2).
+
+   Rare exception: an execution-free data leaf that is needed
+   _synchronously_ at command registration (so it can't be a lazy
+   `import()`) may stay hoisted behind a scoped
+   `// eslint-disable-next-line cli/no-daemon-internals` with a comment
+   explaining why. The only current case is `browser/operation-meta`, in
+   `commands/browser.ts` (it drives synchronous subcommand generation and
+   deliberately pulls no Playwright graph) and `commands/browser.help.ts`
+   (which derives the declarative help from the same contract).
+
+2. **Lazy-import daemon functionality inside the action.** Running daemon
+   logic in-process is encouraged where it avoids an IPC round-trip (which
+   otherwise adds main-process event-loop congestion). Reach that code
+   with a dynamic import inside the action, so it loads only when the
+   command actually runs:
+
+   ```ts
+   .action(async (opts) => {
+     const { doTheThing } = await import("../../runtime/foo.js");
+     await doTheThing(opts);
+   });
+   ```
+
+3. **Always check `r.ok` before reading `r.result`.** `cliIpcCall`
    returns `CliIpcCallResult<T>` — either `{ ok: true, result }` or
    `{ ok: false, error, statusCode?, errorCode?, errorDetails? }`. Use
    `exitFromIpcResult(r)` to surface failure: it writes the error to
    stderr and exits with a code derived from the daemon-side
    `statusCode` (10 connect failure, 3 5xx, 2 4xx, 1 other).
 
-5. **Output via `writeOutput(cmd, payload)`.** The shared helper writes
+4. **Output via `writeOutput(cmd, payload)`.** The shared helper writes
    JSON to stdout — compact with `--json`, pretty otherwise — and
    respects `--json` inherited from parent commands. Don't
    `console.log` results directly; that bypasses the convention and
    breaks downstream scripting.
 
+   **`--json` is global.** `registerGlobalJsonOption` (called once in
+   `program.ts` after every command is registered) attaches `--json` to
+   every **leaf** command in the tree, so a caller can append `--json` to
+   any command it actually invokes without hitting "unknown option". Only
+   leaves get it: Commander consumes a recognized option at the outermost
+   command that declares it, even when the flag appears after the
+   subcommand name, so a group-level `--json` would swallow
+   `clients list --json` before the `list` action reads `opts.json`. You
+   therefore do **not** need to declare `--json` yourself — but a command
+   only _honors_ it when its action routes output through
+   `writeOutput`/`shouldOutputJson` (or reads `opts.json`). When a command
+   emits bespoke human-readable text, branch on `shouldOutputJson(cmd)` and
+   emit a JSON object in the `--json` case (see `commands/status.ts`).
+   Declare `--json` explicitly in the command's `.help` module only when
+   you want a more specific description than the generic one; the global
+   registration skips any leaf that already declares it.
+
 ### Anti-patterns
 
-- ❌ `import { something } from "../../runtime/foo.js"` from an
-  `ipc`-tagged command. The ESLint rule rejects this at `"error"`.
-- ❌ `registerCommand(program, opts)` where `opts` is a hoisted
-  variable. Inline the literal so the transport tag is statically
-  visible.
-- ❌ Multiple `registerCommand` calls in one file.
-- ❌ Reshaping `r.result` to differ from what the route returns. If the
-  CLI shape needs to diverge from the daemon response, change the
-  route — the CLI is just a transport.
+- ❌ Hoisting a daemon import — `import { x } from "../../runtime/foo.js"`
+  at module top (caught by `cli/no-daemon-internals`). Lazy-import it
+  inside the action instead so it loads only when the command runs.
 - ❌ Bypassing `exitFromIpcResult` to format your own error output.
   The shared helper gives consistent exit codes across the surface so
   scripts can branch on them.
 - ❌ Calling the gateway HTTP API (`fetch`, `axios`) from a CLI
-  command. All daemon work goes through IPC; the gateway is for
-  external clients.
+  command. Reach the daemon over IPC or via a lazily-imported in-process
+  helper; the gateway is for external clients.
 
 ## IPC operation IDs and routes
 
@@ -174,7 +199,7 @@ served by the daemon's IPC server. Two route surfaces exist:
   shouldn't be exposed over HTTP — when in doubt, default to the
   shared surface.
 
-Operation IDs are snake_case. The conventional shape is
+Operation IDs are `snake_case`. The conventional shape is
 `<command>_<subcommand>` (`pending_list`, `oauth_connect`,
 `cache_get`), but verb-first names are also used where they read more
 naturally (`upsert_contact`, `wake_conversation`, `conversations_import`).
@@ -189,6 +214,7 @@ response. When you add a new CLI verb you're almost always also adding
 
 `commands/pending.ts` is the reference implementation. Read it first
 when migrating a legacy command or unsure about a pattern.
+
 - Clean error handling via `exitFromIpcResult`
 - No daemon-internal imports
 

package/src/cli/__tests__/cli-command-help-coverage.test.ts

@@ -0,0 +1,29 @@
+/**
+ * Coverage guard: every top-level `assistant` CLI command must declare its
+ * help as pure data in `CLI_COMMAND_HELP` (via a `<command>.help.ts` module).
+ *
+ * The memory capability indexer seeds CLI commands purely from
+ * `CLI_COMMAND_HELP` — it does NOT walk the Commander tree — so a command that
+ * registers without a declarative help entry would be silently invisible to
+ * semantic discovery. This test fails loudly in that case, standing in for the
+ * old `buildCliProgramTree()` fallback that used to catch such gaps at runtime.
+ */
+import { describe, expect, test } from "bun:test";
+
+import { CLI_COMMAND_HELP } from "../index.help.js";
+import { buildCliProgramTree } from "../program.js";
+
+describe("CLI declarative help coverage", () => {
+  test("every registered command has a CLI_COMMAND_HELP entry", () => {
+    const declared = new Set(CLI_COMMAND_HELP.map((h) => h.name));
+    const program = buildCliProgramTree();
+
+    // Commander auto-injects a `help` builtin that carries no capability of its
+    // own; every other top-level command must be declared.
+    const missing = program.commands
+      .map((command) => command.name())
+      .filter((name) => name !== "help" && !declared.has(name));
+
+    expect(missing).toEqual([]);
+  });
+});