@vellumai/assistant 0.9.0 → 0.10.0-staging.2

package/src/calls/media-stream-server.ts

@@ -50,6 +50,7 @@ import {
   recordCallEvent,
   updateCallSession,
 } from "./call-store.js";
+import { getChannelAdmissionPolicy } from "./channel-admission-reader.js";
 import { finalizeCall } from "./finalize-call.js";
 import { MediaStreamOutput } from "./media-stream-output.js";
 import { parseMediaStreamFrame } from "./media-stream-parser.js";
@@ -90,6 +91,18 @@ export class MediaStreamCallSession {
   private streamSid: string | null = null;
   private callSid: string | null = null;
   private disposed = false;
+  // True from the synchronous start of handleStart until setup routing
+  // completes. Resolving the admission floor yields the event loop, so
+  // transcripts/barge-in arriving in this window are ignored — a denied or
+  // not-yet-authorized caller's speech is never persisted before the floor
+  // and trust ACL are applied. The controller-existence checks below also
+  // gate persistence, but this guard makes the intent explicit and covers
+  // the brief async window before the controller is created.
+  private setupRouting = false;
+  // Resolves when the async setup routing kicked off by the `start` frame
+  // settles. Exposed via whenSetupSettled() for deterministic test awaiting,
+  // since handleStart now yields on the admission-policy read.
+  private setupSettled: Promise<void> = Promise.resolve();
 
   // ── Operational diagnostics counters ──────────────────────────────
   /** Number of barge-in attempts that were accepted (assistant was speaking). */
@@ -141,6 +154,14 @@ export class MediaStreamCallSession {
     return this.controller;
   }
 
+  /**
+   * Resolves once the async setup routing started by the `start` frame has
+   * settled. Test-only convenience — production code does not await this.
+   */
+  whenSetupSettled(): Promise<void> {
+    return this.setupSettled;
+  }
+
   /**
    * Feed a raw WebSocket message into the session.
    *
@@ -154,7 +175,16 @@ export class MediaStreamCallSession {
     // Intercept `start` to bootstrap the session before forwarding.
     const parseResult = parseMediaStreamFrame(raw);
     if (parseResult.ok && parseResult.event.event === "start") {
-      this.handleStart(parseResult.event);
+      // handleStart resolves the admission floor asynchronously; the
+      // setupRouting guard set synchronously at its top ensures inbound
+      // frames forwarded below are ignored until routing completes.
+      this.setupSettled = this.handleStart(parseResult.event).catch((err) => {
+        log.error(
+          { err, callSessionId: this.callSessionId },
+          "Media-stream setup routing failed",
+        );
+        this.setupRouting = false;
+      });
     }
 
     // Always forward to the STT session (it handles all event types).
@@ -296,7 +326,12 @@ export class MediaStreamCallSession {
 
   // ── Internal: media-stream event handlers ─────────────────────────
 
-  private handleStart(event: MediaStreamStartEvent): void {
+  private async handleStart(event: MediaStreamStartEvent): Promise<void> {
+    // Enter the setup-pending window synchronously, before any await. The
+    // admission-policy read below yields the event loop, so frames forwarded
+    // to the STT session can produce transcripts/barge-in before routing
+    // completes — those are dropped while setupRouting is true.
+    this.setupRouting = true;
     this.streamSid = event.streamSid;
     this.callSid = event.start.callSid;
 
@@ -337,12 +372,32 @@ export class MediaStreamCallSession {
     const from = session?.fromNumber ?? "";
     const to = session?.toNumber ?? "";
 
+    // Resolve the phone channel's inbound admission floor so the trust floor
+    // (e.g. guardian_only) is enforced on this transport too — not just the
+    // gateway webhook's no_one kill switch. The reader fails open to `null`
+    // by contract, so a transport hiccup admits the caller.
+    const admissionPolicy = await getChannelAdmissionPolicy("phone");
+
+    // The admission-policy read above yields the event loop; if Twilio closed
+    // the WebSocket meanwhile, the close handler will have called destroy().
+    // Abort setup so we don't create a controller or speak on a disposed
+    // session.
+    if (this.disposed) {
+      log.info(
+        { callSessionId: this.callSessionId },
+        "Media-stream session disposed during admission read — aborting setup",
+      );
+      this.setupRouting = false;
+      return;
+    }
+
     const { outcome, resolved } = routeSetup({
       callSessionId: this.callSessionId,
       session: session ?? null,
       from,
       to,
       customParameters: event.start.customParameters,
+      admissionPolicy,
     });
 
     log.info(
@@ -377,6 +432,10 @@ export class MediaStreamCallSession {
         );
         registerCallController(this.callSessionId, this.controller);
 
+        // Routing/ACL cleared — leave the setup-pending window so subsequent
+        // transcripts and barge-in are handled normally.
+        this.setupRouting = false;
+
         // Fire the initial greeting.
         this.controller.startInitialGreeting().catch((err) => {
           log.error(
@@ -525,6 +584,18 @@ export class MediaStreamCallSession {
 
   private handleTranscriptFinal(text: string, _durationMs: number): void {
     if (!text.trim()) return;
+
+    // Drop transcripts arriving while setup routing is still pending so a
+    // not-yet-authorized / floor-denied caller's speech is never persisted
+    // before the admission floor and trust ACL are applied.
+    if (this.setupRouting) {
+      log.debug(
+        { callSessionId: this.callSessionId },
+        "Transcript received during setup routing — dropping",
+      );
+      return;
+    }
+
     this.transcriptFinalsProduced++;
 
     if (!this.controller) {
@@ -560,6 +631,17 @@ export class MediaStreamCallSession {
   }
 
   private handleDtmf(digit: string): void {
+    // Drop DTMF arriving while setup routing is still pending so a
+    // not-yet-authorized / floor-denied caller's digit is never persisted
+    // before the admission floor and trust ACL are applied.
+    if (this.setupRouting) {
+      log.debug(
+        { callSessionId: this.callSessionId, digit },
+        "DTMF received during setup routing — dropping",
+      );
+      return;
+    }
+
     log.info(
       { callSessionId: this.callSessionId, digit },
       "DTMF digit received on media-stream",

package/src/calls/relay-access-wait.ts

@@ -249,7 +249,7 @@ export function emitAccessRequestCallbackHandoff(
     try {
       const contactResult = findContactChannel({
         channelType: "phone",
-        externalUserId: fromNumber,
+        address: fromNumber,
         externalChatId: fromNumber,
       });
       if (

package/src/calls/relay-server.ts

@@ -8,6 +8,7 @@
 
 import { randomInt } from "node:crypto";
 
+import type { AdmissionPolicy } from "@vellumai/gateway-client";
 import type { ServerWebSocket } from "bun";
 
 import {
@@ -47,6 +48,7 @@ import {
   updateCallSession,
 } from "./call-store.js";
 import { ConversationRelayTransport } from "./call-transport.js";
+import { getChannelAdmissionPolicy } from "./channel-admission-reader.js";
 import { finalizeCall } from "./finalize-call.js";
 import {
   classifyWaitUtterance,
@@ -170,6 +172,11 @@ export function setRelayBroadcast(fn: (msg: ServerMessage) => void): void {
  */
 type RelayConnectionState =
   | "connected"
+  // Transient state held synchronously from the start of handleSetup until
+  // routing/ACL completes. Prompts arriving in this window are dropped so a
+  // not-yet-authorized caller's speech is never persisted/emitted before the
+  // admission floor and trust ACL are applied.
+  | "setting_up"
   | "verification_pending"
   | "awaiting_name"
   | "awaiting_guardian_decision"
@@ -550,15 +557,58 @@ export class RelayConnection {
       "ConversationRelay setup received",
     );
 
+    // Enter the setup-pending state synchronously, before any await. The
+    // admission-policy read below yields the event loop, and inbound frames are
+    // dispatched fire-and-forget, so a `prompt` frame can arrive before routing
+    // completes. handlePrompt drops prompts while in "setting_up" so a blocked
+    // or admission-denied caller's speech is never stored before the ACL runs.
+    this.connectionState = "setting_up";
+
     const session = getCallSession(this.callSessionId);
     this.recordSetupBookkeeping(session, msg);
 
+    // Resolve the phone channel's inbound admission floor. The reader fails
+    // open to `null` by contract, so a transport hiccup admits the caller.
+    const admissionPolicy = await getChannelAdmissionPolicy("phone");
+
+    try {
+      await this.routeSetupOutcome(msg, session, admissionPolicy);
+    } catch (err) {
+      // Never leave the connection stranded in "setting_up": a setup that
+      // throws before reaching a terminal outcome would otherwise drop every
+      // prompt forever. Tear the call down instead.
+      log.error(
+        { err, callSessionId: this.callSessionId },
+        "Setup routing failed — disconnecting",
+      );
+      this.connectionState = "disconnecting";
+      updateCallSession(this.callSessionId, {
+        status: "failed",
+        endedAt: Date.now(),
+        lastError: "Setup routing failed",
+      });
+      this.endSession("Setup routing failed");
+    }
+  }
+
+  /**
+   * Apply the routing/ACL outcome for a setup frame. Synchronous helpers that
+   * fire-and-forget (greeting, verification, name capture) are awaited here only
+   * when they themselves are async. Each reachable outcome transitions the
+   * connection out of "setting_up" into its terminal state.
+   */
+  private async routeSetupOutcome(
+    msg: RelaySetupMessage,
+    session: ReturnType<typeof getCallSession>,
+    admissionPolicy: AdmissionPolicy | null,
+  ): Promise<void> {
     const { outcome, resolved } = routeSetup({
       callSessionId: this.callSessionId,
       session,
       from: msg.from,
       to: msg.to,
       customParameters: msg.customParameters,
+      admissionPolicy,
     });
 
     const initialTrustContext = toTrustContext(
@@ -634,6 +684,9 @@ export class RelayConnection {
             );
           }
         }
+        // Routing/ACL cleared — leave the setup-pending state so subsequent
+        // prompts are handled normally.
+        this.connectionState = "connected";
         this.startNormalCallFlow(controller, outcome.isInbound);
         return;
     }
@@ -1822,6 +1875,13 @@ export class RelayConnection {
       return;
     }
 
+    // Prompts arriving before setup routing/ACL completes are dropped — never
+    // persisted or emitted — so a not-yet-authorized caller's speech can't be
+    // stored ahead of the admission floor / trust ACL decision.
+    if (this.connectionState === "setting_up") {
+      return;
+    }
+
     if (!msg.last) {
       // Partial transcript, wait for final
       return;
@@ -2024,6 +2084,12 @@ export class RelayConnection {
       return;
     }
 
+    // Drop DTMF arriving before setup routing/ACL completes (same reasoning as
+    // handlePrompt): don't record input from a not-yet-authorized caller.
+    if (this.connectionState === "setting_up") {
+      return;
+    }
+
     // Ignore DTMF during name capture and guardian decision wait
     if (
       this.connectionState === "awaiting_name" ||

package/src/calls/relay-setup-router.ts

@@ -6,6 +6,8 @@
  * next — without performing any side effects itself.
  */
 
+import type { AdmissionPolicy } from "@vellumai/gateway-client";
+
 import { getConfig } from "../config/loader.js";
 import { findActiveVoiceInvites } from "../memory/invite-store.js";
 import {
@@ -14,6 +16,10 @@ import {
 } from "../runtime/actor-trust-resolver.js";
 import { DAEMON_INTERNAL_ASSISTANT_ID } from "../runtime/assistant-scope.js";
 import { getPendingSession } from "../runtime/channel-verification-service.js";
+import {
+  type AdmissionPolicyResult,
+  enforceAdmissionPolicy,
+} from "../runtime/routes/inbound-stages/admission-policy.js";
 import { getLogger } from "../util/logger.js";
 import type { CallSession } from "./types.js";
 
@@ -27,6 +33,12 @@ interface SetupContext {
   from: string;
   to: string;
   customParameters?: Record<string, string>;
+  /**
+   * Per-channel inbound admission floor for the `phone` channel, supplied by
+   * the caller. When absent/`null`, the floor check is skipped entirely —
+   * preserving all pre-admission behavior.
+   */
+  admissionPolicy?: AdmissionPolicy | null;
 }
 
 // ── Setup outcomes ───────────────────────────────────────────────────
@@ -184,7 +196,55 @@ export function routeSetup(ctx: SetupContext): {
   // ── Inbound call ACL evaluation ─────────────────────────────────
   const pendingChallenge = getPendingSession("phone");
 
-  if (actorTrust.trustClass === "unknown" && !pendingChallenge) {
+  // An admission floor is "active" only when a policy applies and no pending
+  // verification challenge is in flight. While active, the floor IS the access
+  // decision: an admitted caller bypasses the legacy identity flows
+  // (unverified_caller / name_capture) and connects directly. When inactive
+  // (null policy, flag off, exempt channel, reader failed open, or a pending
+  // challenge), those legacy flows are preserved unchanged.
+  const floorActive = ctx.admissionPolicy != null && !pendingChallenge;
+
+  // Inbound admission floor verdict; defaults to admitted when inactive.
+  const floorVerdict = floorActive
+    ? enforceAdmissionPolicy({
+        sourceChannel: "phone",
+        trustClass: actorTrust.trustClass,
+        memberStatus: actorTrust.memberRecord?.channel.status,
+        policy: ctx.admissionPolicy!,
+      })
+    : ({ admitted: true } as const);
+
+  // Floor-deny outcome shared by the unknown-caller and member-caller branches.
+  // Live calls cannot await async re-verification, so the floor's
+  // `shouldChallenge` upgrade UX is not surfaced — same rationale as `escalate`.
+  const floorDeny = (
+    denyVerdict: Extract<AdmissionPolicyResult, { admitted: false }>,
+  ) => {
+    log.info(
+      {
+        callSessionId: ctx.callSessionId,
+        from: ctx.from,
+        trustClass: actorTrust.trustClass,
+        effectivePolicy: denyVerdict.effectivePolicy,
+      },
+      "Inbound voice ACL: admission floor denied caller",
+    );
+    return {
+      outcome: {
+        action: "deny" as const,
+        message:
+          "This number is not authorized to reach the assistant right now.",
+        logReason: `Inbound voice admission floor: ${denyVerdict.effectivePolicy}`,
+      },
+      resolved,
+    };
+  };
+
+  if (
+    (actorTrust.trustClass === "unknown" ||
+      actorTrust.trustClass === "unverified_contact") &&
+    !pendingChallenge
+  ) {
     // Check for blocked caller
     if (actorTrust.memberRecord?.channel.status === "blocked") {
       log.info(
@@ -241,6 +301,21 @@ export function routeSetup(ctx: SetupContext): {
       };
     }
 
+    // When a floor is active it is the access decision: an admitted caller
+    // connects directly (skipping unverified_caller / name_capture), and a
+    // below-floor caller is denied. Invites (handled above) bypass the floor
+    // as an explicit grant. When the floor is inactive (null policy), fall
+    // through to the legacy identity flows below.
+    if (floorActive) {
+      if (!floorVerdict.admitted) {
+        return floorDeny(floorVerdict);
+      }
+      return {
+        outcome: { action: "normal_call" as const, isInbound: true },
+        resolved,
+      };
+    }
+
     // Known caller whose channel hasn't passed verification yet —
     // mirrors the gateway's pre-intercept (twilio-voice-webhook.ts) so
     // calls slipping past it (e.g. canonicalization mismatch between
@@ -345,6 +420,12 @@ export function routeSetup(ctx: SetupContext): {
     };
   }
 
+  // Admission floor: deny member/guardian callers below the floor (e.g.
+  // `guardian_only` denies a trusted_contact).
+  if (!floorVerdict.admitted) {
+    return floorDeny(floorVerdict);
+  }
+
   // Guardian and trusted-contact callers proceed normally
   return {
     outcome: { action: "normal_call", isInbound: true },

package/src/calls/twilio-routes.ts

@@ -54,6 +54,7 @@ import {
   releaseCallbackClaim,
   updateCallSession,
 } from "./call-store.js";
+import { getChannelAdmissionPolicy } from "./channel-admission-reader.js";
 import { routeSetup } from "./relay-setup-router.js";
 import { resolveCallHints } from "./stt-hints.js";
 import { resolveTelephonySttRouting } from "./telephony-stt-routing.js";
@@ -277,10 +278,10 @@ const TWIML_HEADERS = { "Content-Type": "text/xml" } as const;
  * query for outbound calls). Returns a TwiML string. Throws RouteError
  * subclasses on failure.
  */
-function processVoiceWebhook(
+async function processVoiceWebhook(
   params: Record<string, string>,
   callSessionId: string | null,
-): string {
+): Promise<string> {
   const callSid = params.CallSid ?? null;
   const callerFrom = params.From ?? "";
   const callerTo = params.To ?? "";
@@ -371,7 +372,7 @@ export async function handleVoiceWebhook(req: Request): Promise<Response> {
   const params = Object.fromEntries(formBody.entries());
 
   try {
-    return twimlResponse(processVoiceWebhook(params, callSessionId));
+    return twimlResponse(await processVoiceWebhook(params, callSessionId));
   } catch (err) {
     if (err instanceof RouteError) {
       return new Response(err.message, { status: err.statusCode });
@@ -399,7 +400,7 @@ export async function handleVoiceWebhook(req: Request): Promise<Response> {
  * the Twilio setup payload. The persisted call session mode is the
  * primary signal for deterministic flow selection in the relay server.
  */
-function buildVoiceWebhookTwiml(
+async function buildVoiceWebhookTwiml(
   callSessionId: string,
   sessionContext: {
     task: string | null;
@@ -410,7 +411,7 @@ function buildVoiceWebhookTwiml(
     inviteGuardianName: string | null;
   } | null,
   verificationSessionId?: string | null,
-): string {
+): Promise<string> {
   const cfg = loadConfig();
   const profile = resolveVoiceQualityProfile(cfg);
 
@@ -476,11 +477,19 @@ function buildVoiceWebhookTwiml(
   const from = sessionContext?.fromNumber ?? "";
   const to = sessionContext?.toNumber ?? "";
 
+  // Resolve the phone channel's inbound admission floor so this preflight
+  // classification matches the real enforcement at stream start — a
+  // floor-denied caller is recognized as `deny` here, not `normal_call`.
+  // The reader fails open to `null` by contract, so a transport hiccup
+  // admits the caller.
+  const admissionPolicy = await getChannelAdmissionPolicy("phone");
+
   const { outcome } = routeSetup({
     callSessionId,
     session: session ?? null,
     from,
     to,
+    admissionPolicy,
   });
 
   // The media-stream transport supports normal_call and deny (which speaks
@@ -780,9 +789,9 @@ const EMPTY_TWIML = '<?xml version="1.0" encoding="UTF-8"?><Response/>';
  * Internal voice-webhook handler for gateway→runtime forwarding.
  * Accepts JSON body `{ params, originalUrl? }` from the gateway.
  */
-export function handleInternalVoiceWebhook({
+export async function handleInternalVoiceWebhook({
   body = {},
-}: RouteHandlerArgs): RouteResponse {
+}: RouteHandlerArgs): Promise<RouteResponse> {
   const { params = {}, originalUrl } = body as {
     params?: Record<string, string>;
     originalUrl?: string;
@@ -798,7 +807,7 @@ export function handleInternalVoiceWebhook({
     }
   }
 
-  const twiml = processVoiceWebhook(params, callSessionId);
+  const twiml = await processVoiceWebhook(params, callSessionId);
   return new RouteResponse(twiml, TWIML_HEADERS);
 }
 

package/src/calls/voice-session-bridge.ts

@@ -553,8 +553,8 @@ export async function startVoiceTurn(
     } else if (msg.type === "secret_request") {
       if (usesLocalInteractiveApprovals) {
         // Local live voice runs alongside the desktop client, which has a
-        // secret-entry UI (SecretPromptManager). Forward the broadcast and
-        // let the prompter's existing registration handle the response.
+        // secret-entry UI. Forward the broadcast and let the prompter's
+        // existing registration handle the response.
         broadcastMessage(msg);
         return;
       }

package/src/cli/commands/clients.ts

@@ -13,6 +13,7 @@ interface ClientEntryJSON {
   machineName?: string;
   connectedAt: string;
   lastActiveAt: string;
+  degraded?: boolean;
 }
 
 interface ListClientsResponse {
@@ -111,6 +112,7 @@ Examples:
           "LABEL",
           "CONNECTED",
           "LAST ACTIVE",
+          "STATUS",
         ];
         const rows: string[][] = entries.map((e: ClientEntryJSON) => [
           e.clientId,
@@ -119,6 +121,7 @@ Examples:
           e.machineName ?? "—",
           formatRelativeTime(e.connectedAt),
           formatRelativeTime(e.lastActiveAt),
+          e.degraded ? "degraded" : "—",
         ]);
 
         // Calculate column widths

package/src/cli/commands/{__tests__ → memory/__tests__}/memory-v2-compare-render.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 
-import type { ComparisonReport } from "../../../memory/v2/harness/runner.js";
+import type { ComparisonReport } from "../../../../memory/v2/harness/runner.js";
 import {
   renderComparisonReport,
   renderTurnTrace,

package/src/cli/commands/{__tests__ → memory/__tests__}/memory-v2.test.ts

@@ -3,8 +3,8 @@
  *
  * Validates:
  *   - Subcommand registration (reembed, reembed-skills, activation, validate,
- *     ema, simulate) under `memory v2`. The `memory` parent is created by the
- *     v2 registrar itself; v1 had its own subcommands but those were retired.
+ *     ema, simulate) under `memory v2`. v1 had its own subcommands but those
+ *     were retired.
  *   - Each mutating subcommand maps to the right `memory_v2_backfill` op.
  *   - `validate` calls `memory_v2_validate` and pretty-prints the report.
  *   - `reembed-skills` calls `memory_v2_reembed_skills` synchronously.
@@ -40,7 +40,7 @@ let logOutput: string[] = [];
 // Mocks
 // ---------------------------------------------------------------------------
 
-mock.module("../../../ipc/cli-client.js", () => ({
+mock.module("../../../../ipc/cli-client.js", () => ({
   cliIpcCall: async (method: string, params?: any) => {
     lastIpcCall = { method, params };
     return mockIpcResult;
@@ -56,7 +56,7 @@ const fakeLogger = {
   error: capture,
   debug: () => {},
 };
-mock.module("../../../util/logger.js", () => ({
+mock.module("../../../../util/logger.js", () => ({
   getLogger: () => fakeLogger,
   getCliLogger: () => fakeLogger,
 }));
@@ -72,8 +72,8 @@ const { registerMemoryV2Command } = await import("../memory-v2.js");
 // ---------------------------------------------------------------------------
 
 /**
- * Build a fresh program and register the v2 subgroup. The registrar creates
- * the `memory` parent itself, so callers don't need to stub one.
+ * Build a fresh program with a `memory` parent and register the v2 subgroup
+ * under it — mirroring how `registerMemoryCommand` wires the namespace.
  */
 function buildProgram(): Command {
   const program = new Command();
@@ -82,7 +82,8 @@ function buildProgram(): Command {
     writeErr: () => {},
     writeOut: () => {},
   });
-  registerMemoryV2Command(program);
+  const memory = program.command("memory");
+  registerMemoryV2Command(memory);
   return program;
 }
 

package/src/cli/commands/{__tests__ → memory/__tests__}/memory-v3.test.ts

@@ -40,7 +40,7 @@ let logOutput: string[] = [];
 // Mocks
 // ---------------------------------------------------------------------------
 
-mock.module("../../../ipc/cli-client.js", () => ({
+mock.module("../../../../ipc/cli-client.js", () => ({
   cliIpcCall: async (
     method: string,
     params?: any,
@@ -60,7 +60,7 @@ const fakeLogger = {
   error: capture,
   debug: () => {},
 };
-mock.module("../../../util/logger.js", () => ({
+mock.module("../../../../util/logger.js", () => ({
   getLogger: () => fakeLogger,
   getCliLogger: () => fakeLogger,
 }));
@@ -82,7 +82,8 @@ function buildProgram(): Command {
     writeErr: () => {},
     writeOut: () => {},
   });
-  registerMemoryV3Command(program);
+  const memory = program.command("memory");
+  registerMemoryV3Command(memory);
   return program;
 }
 
@@ -144,7 +145,7 @@ describe("subcommand registration", () => {
     const v3 = memory!.commands.find((c) => c.name() === "v3");
     expect(v3).toBeDefined();
     const subcommandNames = v3!.commands.map((c) => c.name()).sort();
-    expect(subcommandNames).toEqual(["backfill-sections", "rebuild-index"]);
+    expect(subcommandNames).toEqual(["backfill-sections", "eval", "rebuild-index"]);
   });
 });
 

package/src/cli/commands/memory/index.ts

@@ -0,0 +1,30 @@
+import type { Command } from "commander";
+
+import { registerCommand } from "../../lib/register-command.js";
+import { registerMemoryV2Command } from "./memory-v2.js";
+import { registerMemoryV3Command } from "./memory-v3.js";
+
+export function registerMemoryCommand(program: Command): void {
+  registerCommand(program, {
+    name: "memory",
+    transport: "ipc",
+    description: "Inspect and maintain the assistant memory subsystem",
+    build: (memory) => {
+      memory.addHelpText(
+        "after",
+        `
+The memory subsystem retrieves concept pages two ways: the v2 concept-page
+activation model (prose pages with directed edges) and the v3 section-lane
+model (section-grain lanes cached as live shadow state). Each subgroup exposes
+operator-facing maintenance verbs — reindexing, backfills, validation, and evals.
+
+Examples:
+  $ assistant memory v2 validate
+  $ assistant memory v3 rebuild-index`,
+      );
+
+      registerMemoryV2Command(memory);
+      registerMemoryV3Command(memory);
+    },
+  });
+}

package/src/cli/commands/{memory-v2-compare-render.ts → memory/memory-v2-compare-render.ts}

@@ -9,7 +9,7 @@
  * type-only imports but forbids pulling in daemon runtime modules.
  */
 
-import type { ComparisonReport } from "../../memory/v2/harness/runner.js";
+import type { ComparisonReport } from "../../../memory/v2/harness/runner.js";
 
 function sortedKs(report: ComparisonReport): number[] {
   return [...report.ks].sort((a, b) => a - b);