@vellumai/assistant 0.12.2 → 0.12.3-dev.202609220419.f870d95

package/src/cli/__tests__/roadmap-cli.test.ts

@@ -219,15 +219,15 @@ describe("roadmap writes", () => {
     });
   });
 
-  test("update sends only the fields that were passed", async () => {
+  test("update forwards only the title and description it was given", async () => {
     nextResult = ITEM;
 
     await runAssistantCommandFull(
       "roadmap",
       "update",
       "dark-mode",
-      "--status",
-      "planned",
+      "--description",
+      "Follow the OS setting",
     );
 
     expect(calls[0]).toEqual({
@@ -236,49 +236,12 @@ describe("roadmap writes", () => {
         pathParams: { slug: "dark-mode" },
         body: {
           title: undefined,
-          description: undefined,
-          status: "planned",
-          tags: undefined,
+          description: "Follow the OS setting",
         },
       },
     });
   });
 
-  test("--clear-tags sends the empty set that --tag cannot express", async () => {
-    nextResult = ITEM;
-
-    await runAssistantCommandFull(
-      "roadmap",
-      "update",
-      "dark-mode",
-      "--clear-tags",
-    );
-
-    expect((calls[0].params as { body: { tags: string[] } }).body.tags).toEqual(
-      [],
-    );
-  });
-
-  test("--clear-tags with --tag is refused rather than silently picking one", async () => {
-    nextResult = ITEM;
-    process.exitCode = 0;
-
-    // The complaint itself goes straight to stderr, which this harness does
-    // not capture; what matters is that no update was forwarded.
-    await runAssistantCommandFull(
-      "roadmap",
-      "update",
-      "dark-mode",
-      "--clear-tags",
-      "--tag",
-      "ui",
-    );
-
-    expect(calls).toHaveLength(0);
-    expect(process.exitCode).toBe(1);
-    process.exitCode = 0;
-  });
-
   test("delete names the item it removed", async () => {
     nextResult = { slug: "dark-mode", deleted: true };
 

package/src/cli/commands/__tests__/cli-test-harness.ts

@@ -6,7 +6,10 @@
  * `process.stdout.write`, `process.stderr.write`, `console.log`, and
  * `console.error` are captured for the duration of the run, so command output
  * lands in the result regardless of which sink the command writes to;
- * `process.exitCode` is reset afterwards.
+ * `process.exitCode` is reset afterwards. A write callback is honoured the
+ * way the real stream honours it, and `process.exit` records its code as the
+ * run's exit code instead of ending the test process, so a command that exits
+ * itself once its output has drained is observed rather than fatal.
  * The caller passes its own (possibly mock-backed) registration function, so
  * this helper imports nothing from `src/` beyond what any test file may
  * import itself (see the test-machinery isolation rules in assistant/CLAUDE.md).
@@ -34,18 +37,32 @@ export async function runCliCommand(
   const stderrChunks: string[] = [];
   const events: string[] = [];
 
-  process.stdout.write = ((chunk: unknown) => {
+  const originalExit = process.exit;
+  const invokeCallback = (rest: unknown[]): void => {
+    const callback = rest.find((arg) => typeof arg === "function");
+    if (callback) {
+      (callback as () => void)();
+    }
+  };
+  process.stdout.write = ((chunk: unknown, ...rest: unknown[]) => {
     const text = typeof chunk === "string" ? chunk : String(chunk);
     stdoutChunks.push(text);
     events.push(text);
+    invokeCallback(rest);
     return true;
   }) as typeof process.stdout.write;
-  process.stderr.write = ((chunk: unknown) => {
+  process.stderr.write = ((chunk: unknown, ...rest: unknown[]) => {
     const text = typeof chunk === "string" ? chunk : String(chunk);
     stderrChunks.push(text);
     events.push(text);
+    invokeCallback(rest);
     return true;
   }) as typeof process.stderr.write;
+  process.exit = ((code?: number) => {
+    if (code !== undefined) {
+      process.exitCode = code;
+    }
+  }) as typeof process.exit;
   console.log = (...logArgs: unknown[]) => {
     const text = logArgs.map(String).join(" ") + "\n";
     stdoutChunks.push(text);
@@ -75,6 +92,7 @@ export async function runCliCommand(
   } finally {
     process.stdout.write = originalStdoutWrite;
     process.stderr.write = originalStderrWrite;
+    process.exit = originalExit;
     console.log = originalConsoleLog;
     console.error = originalConsoleError;
   }

package/src/cli/commands/__tests__/notifications.test.ts

@@ -175,7 +175,7 @@ describe("notifications send", () => {
       "--source-channel",
       "assistant_tool",
       "--source-event-name",
-      "user.send_notification",
+      "schedule.notify",
       "--message",
       "Hello",
     ]);
@@ -186,7 +186,7 @@ describe("notifications send", () => {
 
     const body = lastSendBody();
     expect(body.sourceChannel).toBe("assistant_tool");
-    expect(body.sourceEventName).toBe("user.send_notification");
+    expect(body.sourceEventName).toBe("schedule.notify");
     const payload = body.contextPayload as Record<string, unknown>;
     expect(payload.requestedMessage).toBe("Hello");
   });
@@ -221,7 +221,7 @@ describe("notifications send", () => {
       "--source-channel",
       "assistant_tool",
       "--source-event-name",
-      "user.send_notification",
+      "schedule.notify",
       "--message",
       "Hello",
       "--preferred-channels",
@@ -235,7 +235,7 @@ describe("notifications send", () => {
     expect(payload.preferredChannels).toEqual(["telegram", "slack"]);
   });
 
-  test("send rejects invalid urgency", async () => {
+  test("send passes exclusive channel allowlist", async () => {
     const { parsed, exitCode } = await runCommand([
       "send",
       "--source-channel",
@@ -243,6 +243,31 @@ describe("notifications send", () => {
       "--source-event-name",
       "user.send_notification",
       "--message",
+      "Alarm",
+      "--channels",
+      "telegram",
+      "--urgent",
+    ]);
+
+    expect(exitCode).toBe(0);
+    expect(parsed.ok).toBe(true);
+    expect(parsed.selectedChannels).toEqual([]);
+    expect(parsed.deliveryResults).toEqual([]);
+    expect(parsed.receiptClass).toBe("unknown");
+
+    const payload = lastSendBody().contextPayload as Record<string, unknown>;
+    expect(payload.channelAllowlist).toEqual(["telegram"]);
+    expect(payload.preferredChannels).toBeUndefined();
+  });
+
+  test("send rejects invalid urgency", async () => {
+    const { parsed, exitCode } = await runCommand([
+      "send",
+      "--source-channel",
+      "assistant_tool",
+      "--source-event-name",
+      "schedule.notify",
+      "--message",
       "Hello",
       "--urgency",
       "invalid",
@@ -265,7 +290,7 @@ describe("notifications send", () => {
       "--source-channel",
       "water_reminder",
       "--source-event-name",
-      "user.send_notification",
+      "schedule.notify",
       "--message",
       "Hello",
     ]);
@@ -300,7 +325,7 @@ describe("notifications send", () => {
       "--source-channel",
       "assistant_tool",
       "--source-event-name",
-      "user.send_notification",
+      "schedule.notify",
       "--message",
       "Hi",
       "--conversation-id",
@@ -320,7 +345,7 @@ describe("notifications send", () => {
       "--source-channel",
       "assistant_tool",
       "--source-event-name",
-      "user.send_notification",
+      "schedule.notify",
       "--message",
       "Hi",
     ]);
@@ -335,7 +360,7 @@ describe("notifications send", () => {
       "--source-channel",
       "assistant_tool",
       "--source-event-name",
-      "user.send_notification",
+      "schedule.notify",
       "--message",
       "Hi",
       "--conversation-id",
@@ -359,7 +384,7 @@ describe("notifications send", () => {
       "--source-channel",
       "assistant_tool",
       "--source-event-name",
-      "user.send_notification",
+      "schedule.notify",
       "--message",
       "Hello",
     ]);
@@ -384,7 +409,7 @@ describe("notifications send", () => {
       "--source-channel",
       "assistant_tool",
       "--source-event-name",
-      "user.send_notification",
+      "schedule.notify",
       "--message",
       "Hello",
     ]);

package/src/cli/commands/__tests__/plugins.test.ts

@@ -65,6 +65,7 @@ let installPluginCalls: InstallPluginOptions[] = [];
 let platformInstallCalls: Array<{ name: string; force?: boolean }> = [];
 let upgradePluginCalls: UpgradePluginOptions[] = [];
 let catalogMatches: PluginSearchMatch[] = [];
+let catalogError: Error | null = null;
 
 /**
  * Queued daemon IPC responses. The default (empty queue) is a transport
@@ -162,7 +163,12 @@ mock.module("../../lib/install-from-platform.js", () => ({
 }));
 
 mock.module("../../lib/plugin-catalog-cache.js", () => ({
-  getPluginCatalog: async () => ({ ref: "main", matches: catalogMatches }),
+  getPluginCatalog: async () => {
+    if (catalogError) {
+      throw catalogError;
+    }
+    return { ref: "main", matches: catalogMatches };
+  },
 }));
 
 mock.module("../../lib/inspect-plugin.js", () => ({
@@ -264,6 +270,7 @@ beforeEach(() => {
   platformInstallCalls = [];
   upgradePluginCalls = [];
   catalogMatches = [];
+  catalogError = null;
   ipcResults = [];
   inspectResult = null;
   installTarget = null;
@@ -466,6 +473,18 @@ describe("plugins install - declared-schedules consent", () => {
     });
     expect(r.exitCode).toBe(0);
   });
+
+  test("falls back to the platform installer when catalog discovery fails", async () => {
+    catalogError = new Error("catalog unavailable");
+
+    const r = await runCommand(["plugins", "install", "example"]);
+
+    expect(installPluginCalls).toHaveLength(0);
+    expect(platformInstallCalls).toEqual([
+      { name: "example", force: undefined },
+    ]);
+    expect(r.exitCode).toBe(0);
+  });
 });
 
 describe("plugins upgrade - declared-schedules consent (local fallback)", () => {

package/src/cli/commands/__tests__/schedules.test.ts

@@ -380,6 +380,7 @@ describe("schedules get", () => {
     mode: "execute",
     status: "active",
     routingIntent: "all_channels",
+    quiet: false,
     reuseConversation: false,
     wakeConversationId: null,
     isOneShot: false,
@@ -436,9 +437,22 @@ describe("schedules get", () => {
     expect(output).toContain("Every 30 minutes (UTC)");
     expect(output).toContain("run heartbeat");
     expect(output).toContain("all_channels");
+    expect(output).toMatch(/Quiet:\s+no/);
     expect(output).toContain("conv-abc");
   });
 
+  test("prints Quiet: yes when the schedule suppresses completion notifications", async () => {
+    mockIpcResult = {
+      ok: true,
+      result: { schedule: { ...scheduleFixture, quiet: true } },
+    };
+
+    const { exitCode } = await runCommand(["schedules", "get", "schedule-1"]);
+
+    expect(exitCode).toBe(0);
+    expect(logLines.join("\n")).toMatch(/Quiet:\s+yes/);
+  });
+
   test("emits JSON result when --json is set", async () => {
     mockIpcResult = { ok: true, result: { schedule: scheduleFixture } };
 

package/src/cli/commands/bash.help.ts

@@ -16,9 +16,10 @@ export const bashHelp: CliCommandHelp = {
   ],
   helpText: `
 Spawns the command with the same sanitized environment, working directory,
-and platform shell the bash tool uses for tool-call subprocesses. Vault
-bearers such as CES_SERVICE_TOKEN are stripped; CES_LOCAL_SOCKET and workspace
-paths are forwarded. The command does not go through the assistant HTTP or IPC
+and platform shell the bash tool uses for tool-call subprocesses. CES
+bootstrap and workspace paths are forwarded so children can reach CES over
+IPC. CES HTTP credentials are also forwarded. The command does not go through
+the assistant HTTP or IPC
 API, and does not require a running assistant process.
 
 Arguments:

package/src/cli/commands/browser.help.ts

@@ -17,6 +17,7 @@ import type {
   BrowserOperationMeta,
   OperationField,
 } from "../../browser/types.js";
+import { DESKTOP_HELP_GUIDANCE } from "../../util/browser-human-verification.js";
 import type {
   CliCommandHelp,
   CliOptionHelp,
@@ -137,11 +138,10 @@ Existing sessions and explicit backend/client choices take priority.
 not the user's Chrome. --desktop remains an alias for --virtual-desktop.
 Use --virtual-desktop for Chrome in the Desktop panel.
 Run navigate --url <url> directly to open a page.
-The assistant-desktop feature flag and completed installation are required.
-The first browser command installs missing components, starts Chrome, and completes
-the requested action in one call. Allow up to 600 seconds for this command when
-using bash (timeout_seconds: 600). Opening the Desktop panel also starts
-the same installation and shows progress. No separate setup command is needed.
+The assistant-desktop feature flag and a desktop-enabled assistant image are required.
+Chrome and desktop components are included in the image. The first browser command
+starts Chrome and completes the requested action without downloading or installing
+anything. Missing components require an assistant image update.
 Report other availability errors without switching to a personal computer.
 The assistant manages Chrome startup. Do not launch a separate desktop stack,
 install desktop packages, or drive webpages with shell-level xdotool.
@@ -158,7 +158,10 @@ or --use-active-tab. Download waiting is unavailable on this target.
 Users can interact directly with the expanded desktop. If they ask you to pause,
 stop and wait. Take a fresh snapshot before resuming. Closing the viewer does not
 end automation. Run assistant browser --virtual-desktop detach when finished or
-blocked, including before asking a question. Chrome stays running.
+blocked. Chrome stays running.
+For logins, use saved credentials first. Securely collect missing credentials
+with assistant credentials prompt, then fill the login form yourself.
+${DESKTOP_HELP_GUIDANCE}
 Each subcommand maps to a browser operation and communicates
 with the assistant process.
 

package/src/cli/commands/browser.ts

@@ -168,7 +168,6 @@ function attachOperationAction(
       }
     }
 
-    // First use can include virtual desktop installation and Chrome startup.
     const ipcResult = await cliIpcCall<BrowserExecuteResult>(
       "browser_execute",
       {

package/src/cli/commands/channel-verification-sessions.help.ts

@@ -44,7 +44,11 @@ Examples:
           description:
             "Destination address for outbound verification (handle, phone number, user ID, or email address)",
         },
-        { flags: "--rebind", description: "Replace existing guardian binding" },
+        {
+          flags: "--rebind",
+          description:
+            "Create a code although the channel already has a guardian (see below)",
+        },
         {
           flags: "--conversation-id <conversationId>",
           description: "Conversation ID for inbound challenges",
@@ -74,7 +78,13 @@ Routes between three creation modes based on the provided options:
   2. Outbound: --channel <ch> --destination <dest>
      Sends a verification code to the given destination. Supports telegram
      (handle or chat ID), phone (E.164 number), slack and discord (user ID),
-     and email. Use --rebind to replace an existing guardian binding.
+     and email.
+
+--rebind creates a code although the channel already has a guardian. On
+telegram, slack, discord and email, only the account already bound can redeem
+that code, which is how the same guardian verifies again. A code never moves
+the guardian to a different account there: run "revoke" first, then create
+without --rebind. On phone, an outbound code replaces the bound number.
 
   3. Inbound: --channel <ch> (no --destination)
      Generates a challenge secret for the guardian to send back on the

package/src/cli/commands/clients.help.ts

@@ -58,6 +58,7 @@ Examples:
   $ assistant clients list                             List all connected clients
   $ assistant clients list --json                      Machine-readable JSON output
   $ assistant clients list --capability host_bash      Show only clients that can run host commands
+  $ assistant clients history                          Recent connection sessions and flaps
   $ assistant clients disconnect <clientId>            Force-disconnect a client`,
   subcommands: [
     {
@@ -87,6 +88,51 @@ Examples:
   $ assistant clients list
   $ assistant clients list --capability host_bash
   $ assistant clients list --json | jq '.clients[0].capabilities'`,
+    },
+    {
+      name: "history",
+      description: "Show persisted client connection sessions",
+      options: [
+        {
+          flags: "--json",
+          description: "Machine-readable compact JSON output",
+        },
+        {
+          flags: "--client-id <id>",
+          description: "Restrict history to one client UUID",
+        },
+        {
+          flags: "--interface-id <id>",
+          description:
+            "Restrict history to one interface (e.g. chrome-extension)",
+        },
+        {
+          flags: "--since <when>",
+          description:
+            "ISO-8601 or epoch-ms lower bound. Sessions already open at this time are included.",
+        },
+        {
+          flags: "--limit <n>",
+          description: "Max coalesced sessions to return (1-500, default 50)",
+        },
+      ],
+      helpText: `
+Options:
+  --json                 Output as compact JSON instead of a table.
+  --client-id <id>       Only show history for this client UUID.
+  --interface-id <id>    Only show history for this interface.
+  --since <when>         Lower bound as ISO-8601 or epoch milliseconds.
+                         Sessions already open at this time are included.
+  --limit <n>            Max sessions after flap coalescing. Default 50.
+
+Reconnects shorter than 60 seconds are flaps on the same session, not
+separate outages. History starts when this assistant version first
+records connections. It does not backfill earlier uptime.
+
+Examples:
+  $ assistant clients history
+  $ assistant clients history --interface-id chrome-extension
+  $ assistant clients history --client-id client-123 --since 2026-09-01 --json`,
     },
     {
       name: "disconnect",

package/src/cli/commands/clients.ts

@@ -26,6 +26,23 @@ interface DisconnectClientResponse {
   disconnected: number;
 }
 
+interface ClientHistorySessionJSON {
+  clientId: string;
+  interfaceId: string;
+  startedAt: string;
+  endedAt: string | null;
+  durationMs: number | null;
+  flapCount: number;
+  closeReason: string | null;
+  clientVersion: string | null;
+  sseWatchdog: boolean | null;
+}
+
+interface ListClientHistoryResponse {
+  sessions: ClientHistorySessionJSON[];
+  events: unknown[];
+}
+
 export function registerClientsCommand(program: Command): void {
   registerCommand(program, {
     name: clientsHelp.name,
@@ -108,6 +125,85 @@ export function registerClientsCommand(program: Command): void {
         },
       );
 
+      subcommand(clients, "history").action(
+        async (
+          opts: {
+            json?: boolean;
+            clientId?: string;
+            interfaceId?: string;
+            since?: string;
+            limit?: string;
+          },
+          cmd: Command,
+        ) => {
+          const result = await cliIpcCall<ListClientHistoryResponse>(
+            "list_client_history",
+            optsToQueryParams(opts),
+          );
+
+          if (!result.ok) {
+            log.error(result.error ?? "Failed to load client history");
+            process.exitCode = 1;
+            return;
+          }
+
+          const response = result.result!;
+          if (opts.json) {
+            writeOutput(cmd, response);
+            return;
+          }
+
+          const sessions = response.sessions;
+          if (sessions.length === 0) {
+            log.info("No client connection history.");
+            return;
+          }
+
+          const header = [
+            "CLIENT ID",
+            "INTERFACE",
+            "STARTED",
+            "ENDED",
+            "DURATION",
+            "FLAPS",
+            "CLOSE",
+            "VERSION",
+            "WATCHDOG",
+          ];
+          const rows: string[][] = sessions.map((session) => [
+            session.clientId,
+            session.interfaceId,
+            formatRelativeTime(session.startedAt),
+            session.endedAt ? formatRelativeTime(session.endedAt) : "connected",
+            formatDuration(session.durationMs),
+            String(session.flapCount),
+            session.closeReason ?? "-",
+            session.clientVersion ?? "-",
+            session.sseWatchdog == null
+              ? "-"
+              : session.sseWatchdog
+                ? "yes"
+                : "no",
+          ]);
+
+          const colWidths = header.map((h: string, i: number) =>
+            Math.max(h.length, ...rows.map((r: string[]) => r[i].length)),
+          );
+          const pad = (s: string, w: number) => s.padEnd(w);
+          log.info(
+            header.map((h: string, i: number) => pad(h, colWidths[i])).join("  "),
+          );
+          log.info(colWidths.map((w: number) => "─".repeat(w)).join("  "));
+          for (const row of rows) {
+            log.info(
+              row
+                .map((c: string, i: number) => pad(c, colWidths[i]))
+                .join("  "),
+            );
+          }
+        },
+      );
+
       subcommand(clients, "disconnect").action(
         async (clientId: string, opts: { json?: boolean }, cmd: Command) => {
           const result = await cliIpcCall<DisconnectClientResponse>(
@@ -155,3 +251,23 @@ function formatRelativeTime(iso: string): string {
   const days = Math.floor(hr / 24);
   return `${days}d ago`;
 }
+
+function formatDuration(ms: number | null): string {
+  if (ms == null || ms < 0) {
+    return "-";
+  }
+  const sec = Math.floor(ms / 1000);
+  if (sec < 60) {
+    return `${sec}s`;
+  }
+  const min = Math.floor(sec / 60);
+  if (min < 60) {
+    return `${min}m`;
+  }
+  const hr = Math.floor(min / 60);
+  if (hr < 24) {
+    return `${hr}h ${min % 60}m`;
+  }
+  const days = Math.floor(hr / 24);
+  return `${days}d ${hr % 24}h`;
+}

package/src/cli/commands/credentials.help.ts

@@ -74,9 +74,9 @@ path or connection details. Run this to diagnose credential lookup mismatches
 for example, when the CLI and the daemon are reading from different stores.
 
 Backend types:
-  encrypted-store   Direct file read from keys.enc (standalone CLI, no daemon)
-  ces-rpc           Delegates to the running CES process via stdio RPC (daemon)
-  ces-http          Delegates to CES sidecar over HTTP (containerized/Docker mode)
+  encrypted-store   Direct file read from keys.enc (standalone CLI, no assistant)
+  ces-rpc           Delegates to the running CES process via socket RPC
+  ces-http          Managed failover when the CES socket is unavailable
 
 Also shows the CREDENTIAL_SECURITY_DIR, GATEWAY_SECURITY_DIR, and
 VELLUM_WORKSPACE_DIR env vars so you can confirm which instance directory this
@@ -294,7 +294,12 @@ web, etc.). The user enters the secret through the UI — it never passes throug
 the conversation or CLI output. On success the credential is stored in the
 encrypted vault with the specified metadata.
 
-Requires the assistant to be running with at least one connected client.
+Requires the assistant to be running. The prompt renders in the conversation
+this command runs from (the bash tool sets __CONVERSATION_ID). With no
+conversation attached (a headless shell, Doctor's run_assistant_cli), no client
+can show the card, so the command returns at once with a one-time collection
+link (exit 75) to relay to the user, or an error when no link can be minted.
+Never fall back to asking the user for the value in chat.
 
 This command BLOCKS until the user answers the prompt, so it returns only once
 the prompt has already closed. Tell the user what to paste BEFORE running it.

package/src/cli/commands/notifications.help.ts

@@ -127,7 +127,12 @@ Examples:
         {
           flags: "--preferred-channels <channels>",
           description:
-            "Comma-separated channel hints (e.g. vellum,telegram,slack)",
+            "Comma-separated channel hints (e.g. vellum,telegram,slack). Additive: vellum stays selected.",
+        },
+        {
+          flags: "--channels <channels>",
+          description:
+            "Exclusive channel allowlist (e.g. telegram). Replaces the default set. Urgent delivery does not add vellum or platform. Wins over --preferred-channels.",
         },
         {
           flags: "--session-id <id>",
@@ -162,7 +167,15 @@ Behavioral notes:
     is treated as critical and requires user action. Explicit --urgency /
     --requires-action flags still win for back-compat.
   - Without --urgent, --urgency defaults to low and --requires-action to false.
-  - --preferred-channels are hints only; the decision engine may override them.
+  - --preferred-channels are additive hints; vellum stays in the selected set.
+  - --channels is an exclusive allowlist. Only those connected channels are
+    selected. Urgent delivery does not force vellum or platform, and Home
+    does not mirror unless vellum is in the list. When both flags are set,
+    --channels wins.
+  - --json includes selectedChannels, deliveryResults, and receiptClass.
+    receiptClass is the strongest delivery proof (provider_accepted,
+    gateway_accepted, client_os_posted, or unknown), not a promise the
+    user saw a banner.
   - --dedupe-key suppresses duplicate signals with the same key.
   - --conversation-id pins delivery to an existing vellum conversation
     deterministically. Other channels (telegram, slack) continue to use
@@ -171,6 +184,7 @@ Behavioral notes:
 Examples:
   $ assistant notifications send --message "Task complete"
   $ assistant notifications send --message "Pager: prod is down" --urgent
+  $ assistant notifications send --message "Alarm" --channels telegram --urgent
   $ assistant notifications send --message "Build green" --conversation-id 649c4645-3a6f-4ded-a713-504f02ca806b`,
     },
     {