@ultimat3/cli 23.0.0 → 25.0.0

package/src/cmd-jobs-spec.ts

@@ -15,17 +15,14 @@ export const JOBS_SUBCOMMANDS = [
   'drain',
 ] as const;
 
-/**
- * The drivers a drain may move work ONTO — every one of them durable, and that is the whole rule.
- * Closed, and read three ways: the flag summary, the refusal, and the `memory` case below.
- */
-export const DRAIN_TARGETS = ['redis', 'nats'] as const;
-
 export const jobsSpec: CommandSpec = {
   name: 'jobs',
-  summary: 'list, show, retry, cancel, remove and promote jobs; pause and resume a queue; drain',
+  // Never ENDING in "(planned)": that suffix is how `x help` and the planned-table tests tell a
+  // planned COMMAND from a shipped one, and `x jobs` ships — only its `drain` does not.
+  summary:
+    'list, show, retry, cancel, remove and promote jobs; pause and resume a queue (drain is planned)',
   usage:
-    'x jobs [ls|show <id>|retry <id>|cancel <id>|rm <id>|promote <id>|pause <queue>|resume <queue>|drain --to <driver>] [--queue q] [--state s] [--name n] [--limit n] [--after cursor] [--from-step name] [--reason text] [--to driver] [--dry-run] [--json]',
+    'x jobs [ls|show <id>|retry <id>|cancel <id>|rm <id>|promote <id>|pause <queue>|resume <queue>|drain] [--queue q] [--state s] [--name n] [--limit n] [--after cursor] [--from-step name] [--reason text] [--json]',
   requiresApp: true,
   subcommands: JOBS_SUBCOMMANDS,
   // The bare `x jobs` lists; it never retries, cancels or drains anything.
@@ -41,8 +38,8 @@ export const jobsSpec: CommandSpec = {
       summary: 'ls: the next page — the cursor the previous page printed',
       subcommands: ['ls'],
     },
-    // Each of these is read by ONE subcommand — `retryJob`, `cancelJob`, `runDrain` — and says
-    // so in its own summary. The scope is what makes the parser refuse it anywhere else instead
+    // Each of these is read by ONE subcommand — `retryJob`, `cancelJob` — and says so in its own
+    // summary. The scope is what makes the parser refuse it anywhere else instead
     // of accepting it and ignoring it: `x db gen --dry-run` parsed and wrote the migration.
     {
       name: 'from-step',
@@ -56,17 +53,5 @@ export const jobsSpec: CommandSpec = {
       summary: 'cancel: why, recorded on the job',
       subcommands: ['cancel'],
     },
-    {
-      name: 'to',
-      type: 'string',
-      summary: `drain: target driver — ${DRAIN_TARGETS.join(', ')}`,
-      subcommands: ['drain'],
-    },
-    {
-      name: 'dry-run',
-      type: 'boolean',
-      summary: 'drain: report the plan, move nothing',
-      subcommands: ['drain'],
-    },
   ],
 };

package/src/cmd-jobs.ts

@@ -1,6 +1,6 @@
-// `x jobs ls|show|retry|cancel|rm|promote|pause|resume|drain` — introspect and recover the job queue, bound to
-// `@ultimat3/jobs`'s
-// own introspection so the CLI, `/_x` and MCP report identically. This file is CLI wiring only:
+// `x jobs ls|show|retry|cancel|rm|promote|pause|resume` — introspect and recover the job queue,
+// bound to `@ultimat3/jobs`'s own introspection so the CLI, `/_x` and MCP report identically;
+// `drain` is planned (`cmd-planned.ts`): Postgres is the one durable driver. CLI wiring only:
 // the driver-injected logic is `jobs-report.ts`, the `--json` shapes `jobs-json.ts`, the table
 // `jobs-table.ts`, and getting hold of the queue at all is `jobs-driver.ts` — shared with `x db`.
 
@@ -8,10 +8,6 @@ import { renderFixShellArg } from '@ultimat3/core';
 import type { JobDriver } from '@ultimat3/jobs';
 import {
   cancelJob,
-  createNatsDriver,
-  createRedisDriver,
-  DEFAULT_JOB_PAGE,
-  jobCursor,
   MAX_JOB_PAGE,
   pauseQueue,
   promoteJob,
@@ -20,18 +16,15 @@ import {
 } from '@ultimat3/jobs';
 import { loadApp } from './app-load';
 import { requireAppRoot } from './app-root';
-import { DRAIN_TARGETS, jobsSpec } from './cmd-jobs-spec';
+import { jobsSpec } from './cmd-jobs-spec';
+import { plannedSubcommand } from './cmd-planned';
 import type { CliCommand, CommandContext } from './command';
 import { BadFlagError, JobUnknownError, MissingPositionalError } from './errors';
-import type { DrainOutcome } from './jobs-drain';
-import { drainJobs } from './jobs-drain';
 import { withJobDriver } from './jobs-driver';
 import {
   backfillToJson,
   deadLetterToJson,
   depthToJson,
-  drainFailureToJson,
-  drainSkipToJson,
   jobRecordToJson,
   jobTraceToJson,
   pausedToJson,
@@ -41,32 +34,22 @@ import { listJobs, retryJob, showJob } from './jobs-report';
 import { renderJobTable } from './jobs-table';
 import { msg } from './messages';
 import type { CommandResult } from './output';
-import { flagBool, flagString } from './parse';
+import { flagString } from './parse';
 
-export { DRAIN_TARGETS, JOBS_SUBCOMMANDS } from './cmd-jobs-spec';
+export { JOBS_SUBCOMMANDS } from './cmd-jobs-spec';
 
 /**
- * `memory` was on that list until 2026-09 and could not be: `createMemoryDriver()` is a `Map` in
- * THIS process, so `x jobs drain --to memory` enqueued each job into it and then `ack`ed the
- * durable row off the source. Reproduced against two real drivers — source ready 1 -> 0, target
- * ready 1, `ok: true` — and the target dies with the command. `wiki/CLI-Reference.md` said the
- * crash window "duplicates a job … instead of losing it"; this target lost every one of them.
- *
- * Refused by NAME rather than folded into the unknown-value message, for `cmd-deploy.ts`'s
- * `readMethod` reason: `--to memory` is a spelling that used to work, so a reader who types it is
- * owed the fact that it moved work into a process that is about to exit, not a list of words.
+ * A uuid in any spelling Postgres' `uuid` input accepts: canonical, upper-case, unhyphenated,
+ * braced. Every driver mints its ids with core's `uuid()`, and `x_jobs.id` is a `uuid` column.
  */
-function refuseMemoryTarget(): never {
-  throw new BadFlagError({
-    flag: 'to',
-    command: 'jobs',
-    reason:
-      'memory is a Map inside this process — the drain would ack every durable row and lose the copy when the command exits',
-    fix: 'x jobs drain --to redis --json   # or --to nats; --dry-run reports the plan and moves nothing',
-  });
-}
+const JOB_ID = /^\{?[0-9a-f]{8}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{12}\}?$/i;
 
-function requireIdPositional(ctx: CommandContext, sub: string): string {
+/**
+ * The id, parsed at the door — admin's `readableId` rule: an id no driver could hold is a job that
+ * does not exist, answered before a statement is sent. `x jobs show nosuch` reached Postgres and
+ * came back a raw `X_DB_STATEMENT_FAILED [22P02]` whose fix was a psql session.
+ */
+function requireIdPositional(ctx: CommandContext, sub: string, driver: JobDriver): string {
   const id = ctx.args.positionals[0];
   if (id === undefined) {
     // `--id on "x jobs"` is a flag `x jobs` does not declare; the id is a positional and says so.
@@ -76,6 +59,7 @@ function requireIdPositional(ctx: CommandContext, sub: string): string {
       example: 'x jobs ls --json',
     });
   }
+  if (!JOB_ID.test(id)) throw new JobUnknownError({ id, driver: driver.name });
   return id;
 }
 
@@ -102,42 +86,10 @@ function refuseOversizedPage(limit: string | undefined): void {
     command: 'jobs',
     reason: `one page holds at most ${MAX_JOB_PAGE} jobs`,
     // The bound is the queue's own constant, screened like any value spliced into a command.
-    fix: `x jobs ls --limit ${renderFixShellArg(String(MAX_JOB_PAGE), '200')} --json   # then pass its data.next as --after for the page that follows`,
+    fix: `x jobs ls --limit ${renderFixShellArg(String(MAX_JOB_PAGE), '200')} --json   # then pass its data.nextCursor as --after while data.hasMore is true`,
   });
 }
 
-function requireEnvUrl(env: CommandContext['env'], name: string, target: string): string {
-  const value = env[name];
-  if (value === undefined || value.trim().length === 0) {
-    throw new BadFlagError({
-      flag: 'to',
-      command: 'jobs',
-      reason: `--to ${target} needs ${name} set in the environment`,
-    });
-  }
-  return value;
-}
-
-/**
- * `redis`/`nats` are honest `X_NOT_IMPLEMENTED` stubs in `@ultimat3/jobs` — building one here is
- * fine even though every `enqueue` on it will fail; `drainJobs` reports that per record. What is
- * NOT fine is a target that accepts every enqueue and then vanishes, which is why `memory` is
- * refused first and by name rather than falling into the closed-set message below.
- * Exported so a test can drive the `--to`/env-var validation without a driver or a boot.
- */
-export function buildDrainTarget(to: string | undefined, env: CommandContext['env']): JobDriver {
-  if (to === 'memory') refuseMemoryTarget();
-  if (to === undefined || !(DRAIN_TARGETS as readonly string[]).includes(to)) {
-    throw new BadFlagError({
-      flag: 'to',
-      command: 'jobs',
-      reason: `expects one of: ${DRAIN_TARGETS.join(', ')}`,
-    });
-  }
-  if (to === 'redis') return createRedisDriver({ url: requireEnvUrl(env, 'REDIS_URL', 'redis') });
-  return createNatsDriver({ servers: [requireEnvUrl(env, 'NATS_URL', 'nats')] });
-}
-
 async function runLs(driver: JobDriver, ctx: CommandContext): Promise<CommandResult> {
   const limit = flagString(ctx.args, 'limit');
   refuseOversizedPage(limit);
@@ -148,11 +100,9 @@ async function runLs(driver: JobDriver, ctx: CommandContext): Promise<CommandRes
     limit,
     after: flagString(ctx.args, 'after'),
   });
-  // A FULL page may have another behind it: `next` is the cursor that asks for it, and `null`
-  // says this was the last one — so a walk never has to guess from a row count.
-  const size = limit === undefined ? DEFAULT_JOB_PAGE : Number(limit);
-  const last = result.rows[result.rows.length - 1];
-  const next = last === undefined || result.rows.length < size ? null : jobCursor(last);
+  // `nextCursor` exists exactly when a row past this page does (`listJobs` asks the queue), so a
+  // full last page prints no "next page" a caller would follow to an empty one.
+  const next = result.nextCursor;
   const [paused, workers] = await Promise.all([
     driver.introspect?.pausedQueues() ?? [],
     driver.introspect?.workers() ?? [],
@@ -203,7 +153,8 @@ async function runLs(driver: JobDriver, ctx: CommandContext): Promise<CommandRes
       rows: result.rows.map(jobRecordToJson),
       deadLetters: result.deadLetters.map(deadLetterToJson),
       backfills: result.backfills.map(backfillToJson),
-      next,
+      nextCursor: result.nextCursor,
+      hasMore: result.hasMore,
       pausedQueues: paused.map(pausedToJson),
       workers: workers.map(workerToJson),
     },
@@ -211,7 +162,7 @@ async function runLs(driver: JobDriver, ctx: CommandContext): Promise<CommandRes
 }
 
 async function runShow(driver: JobDriver, ctx: CommandContext): Promise<CommandResult> {
-  const trace = await showJob(driver, requireIdPositional(ctx, 'show'));
+  const trace = await showJob(driver, requireIdPositional(ctx, 'show', driver));
   return {
     ok: true,
     command: 'jobs',
@@ -226,7 +177,7 @@ async function runShow(driver: JobDriver, ctx: CommandContext): Promise<CommandR
 }
 
 async function runRetry(driver: JobDriver, ctx: CommandContext): Promise<CommandResult> {
-  const id = requireIdPositional(ctx, 'retry');
+  const id = requireIdPositional(ctx, 'retry', driver);
   const trace = await retryJob(driver, id, flagString(ctx.args, 'from-step'));
   return {
     ok: true,
@@ -243,7 +194,7 @@ async function runRetry(driver: JobDriver, ctx: CommandContext): Promise<Command
  * The trace is rendered by the same projection `show` and `retry` use — one shape for one job.
  */
 async function runCancel(driver: JobDriver, ctx: CommandContext): Promise<CommandResult> {
-  const id = requireIdPositional(ctx, 'cancel');
+  const id = requireIdPositional(ctx, 'cancel', driver);
   const trace = await cancelJob(driver, id, flagString(ctx.args, 'reason'));
   // `cancelJob` re-reads the job after cancelling, so `undefined` would mean the row vanished
   // between the two — reported as the same refusal rather than rendered as a success with no job.
@@ -258,7 +209,7 @@ async function runCancel(driver: JobDriver, ctx: CommandContext): Promise<Comman
 
 /** Exit 0 means the row is gone. An id nobody queued is `X_JOB_UNKNOWN`; a running one refuses. */
 async function runRm(driver: JobDriver, ctx: CommandContext): Promise<CommandResult> {
-  const id = requireIdPositional(ctx, 'rm');
+  const id = requireIdPositional(ctx, 'rm', driver);
   const removed = await removeJob(driver, id);
   if (removed === undefined) throw new JobUnknownError({ id, driver: driver.name });
   return {
@@ -270,7 +221,7 @@ async function runRm(driver: JobDriver, ctx: CommandContext): Promise<CommandRes
 }
 
 async function runPromote(driver: JobDriver, ctx: CommandContext): Promise<CommandResult> {
-  const promoted = await promoteJob(driver, requireIdPositional(ctx, 'promote'));
+  const promoted = await promoteJob(driver, requireIdPositional(ctx, 'promote', driver));
   return {
     ok: true,
     command: 'jobs',
@@ -298,59 +249,6 @@ async function runPause(
   };
 }
 
-/**
- * A skipped candidate is not an error — a job whose `runAt` has not arrived is unclaimable by
- * design — so it carries no `X_*` finding. It still fails the command: `x jobs drain` is run to
- * empty a driver, and a partial move that exited 0 would read as "the queue is clear".
- *
- * Exported, and separate from the flag reading above it, because every target the flag now accepts
- * needs a server: a test can produce a real outcome from two drivers and render THAT, where
- * driving the whole command would need a redis or a nats to move anything at all.
- */
-export function drainResult(outcome: DrainOutcome): CommandResult {
-  const dryRun = outcome.dryRun;
-  const findings = outcome.failures.map((failure) => failure.finding);
-  const lines: string[] = [];
-  if (outcome.skipped.length > 0) {
-    const count = outcome.skipped.length;
-    lines.push(`  ${msg('cli.jobs.skipped', { count, from: outcome.from })}`);
-    for (const skip of outcome.skipped) {
-      lines.push(`    ${skip.id}  ${skip.name}  (${skip.queue})  ${skip.state}  ${skip.reason}`);
-    }
-  }
-  const partial = outcome.skipped.length > 0;
-  return {
-    ok: findings.length === 0 && !partial,
-    command: 'jobs',
-    summary: msg(partial ? 'cli.jobs.drainedPartial' : 'cli.jobs.drained', {
-      count: dryRun ? outcome.candidates.length : outcome.moved.length,
-      from: outcome.from,
-      to: outcome.to,
-      skipped: outcome.skipped.length,
-    }),
-    lines,
-    findings,
-    data: {
-      from: outcome.from,
-      to: outcome.to,
-      dryRun: outcome.dryRun,
-      candidates: outcome.candidates.map(jobRecordToJson),
-      moved: outcome.moved.map(jobRecordToJson),
-      skipped: outcome.skipped.map(drainSkipToJson),
-      failures: outcome.failures.map(drainFailureToJson),
-    },
-  };
-}
-
-/** The move, then the render. The target is built ABOVE `withJobDriver` — see `run` below. */
-async function runDrain(
-  driver: JobDriver,
-  target: JobDriver,
-  ctx: CommandContext,
-): Promise<CommandResult> {
-  return drainResult(await drainJobs(driver, target, flagBool(ctx.args, 'dry-run')));
-}
-
 /** The subcommands that answer a `JobTrace`. `ls`, `rm`, `promote` and the rest read rows only. */
 const TRACE_SUBCOMMANDS: ReadonlySet<string> = new Set(['show', 'retry', 'cancel']);
 
@@ -359,13 +257,11 @@ export const jobsCommand: CliCommand = {
   async run(ctx: CommandContext): Promise<CommandResult> {
     const root = requireAppRoot('jobs', ctx.cwd).dir;
     const sub = ctx.args.subcommand ?? 'ls';
-    // BEFORE `withJobDriver`, which boots the SOURCE queue and pings it. `--to` is a flag, so
-    // whether it names a durable driver is answerable with no server at all — and reading it
-    // inside meant `x jobs drain --to memory` on a box whose database is down reported the boot
-    // failure instead of `X_CLI_BAD_FLAG`, i.e. the operator repaired Postgres to be told the
-    // word they typed was refused by name. It also opens a connection to a target the command
-    // then refuses, which is a socket nothing closes.
-    const target = sub === 'drain' ? buildDrainTarget(flagString(ctx.args, 'to'), ctx.env) : null;
+    // BEFORE `withJobDriver`, which boots the source queue: the answer needs no server, so a box
+    // whose database is down gets it rather than the boot failure of a queue never to be used —
+    // and nothing is leased. 24.x's `--to`/`--dry-run` are deleted, so the parser refuses them
+    // (`X_CLI_BAD_FLAG`); only a bare `x jobs drain` reaches this answer.
+    if (sub === 'drain') throw plannedSubcommand('jobs', 'drain');
     // A TRACE is the queue row projected through the job's own declaration — its concurrency key,
     // its retry schedule — and a declaration exists in this process only once the app is loaded.
     // Unloaded, `show` answered `concurrencyKey: null` and `retryDelaysMs: []` for every job of
@@ -379,13 +275,10 @@ export const jobsCommand: CliCommand = {
       if (sub === 'rm') return runRm(driver, ctx);
       if (sub === 'promote') return runPromote(driver, ctx);
       if (sub === 'pause' || sub === 'resume') return runPause(driver, ctx, sub);
-      if (target !== null) return runDrain(driver, target, ctx);
       return runLs(driver, ctx);
     });
   },
 };
 
-export type { DrainFailure, DrainOutcome, DrainSkip } from './jobs-drain';
-export { drainJobs } from './jobs-drain';
 export type { JobsListFilter, JobsListResult } from './jobs-report';
 export { listJobs, retryJob, showJob } from './jobs-report';

package/src/cmd-manifest-spec.ts

@@ -6,7 +6,7 @@ import type { CommandSpec } from './parse';
 export const manifestSpec: CommandSpec = {
   name: 'manifest',
   summary: 'regenerate x.manifest.json and openapi.json from the code',
-  usage: 'x manifest [--check] [--json]',
+  usage: 'x manifest [--check] [--no-openapi] [--json]',
   requiresApp: true,
   flags: [
     { name: 'check', type: 'boolean', summary: 'fail if the committed files are stale' },

package/src/cmd-manifest.ts

@@ -4,16 +4,15 @@
 
 import { join } from 'node:path';
 import type { Manifest } from '@ultimat3/manifest';
-import { assertNoDrift, MANIFEST_FILENAME } from '@ultimat3/manifest';
+import { MANIFEST_FILENAME } from '@ultimat3/manifest';
 import { writeAppArtifacts } from './app-artifacts';
 import { appManifest } from './app-manifest';
-import { openApiStaleness } from './app-openapi';
 import { requireAppRoot } from './app-root';
 import { manifestSpec } from './cmd-manifest-spec';
 import type { CliCommand, CommandContext } from './command';
+import { manifestStaleness } from './manifest-staleness';
 import { msg } from './messages';
-import type { CommandResult, Finding, JsonValue } from './output';
-import { findingFrom } from './output';
+import type { CommandResult, JsonValue } from './output';
 import { flagBool } from './parse';
 
 const countsOf = (manifest: Manifest): JsonValue => ({
@@ -27,21 +26,6 @@ const countsOf = (manifest: Manifest): JsonValue => ({
   policies: manifest.policies.length,
 });
 
-/**
- * The identical comparison `x verify`'s `manifest` step makes, through the identical function.
- * A buildId equality test here would answer "fresh" for a hand-edited file whose body no longer
- * hashes to the id it carries — and two commands giving two answers about one file is itself the
- * drift the manifest exists to prevent.
- */
-async function staleness(root: string, manifest: Manifest): Promise<Finding | undefined> {
-  try {
-    await assertNoDrift({ manifest, path: join(root, MANIFEST_FILENAME) });
-    return undefined;
-  } catch (error) {
-    return { ...findingFrom(error), at: MANIFEST_FILENAME };
-  }
-}
-
 export const manifestCommand: CliCommand = {
   spec: manifestSpec,
   async run(ctx: CommandContext): Promise<CommandResult> {
@@ -50,12 +34,9 @@ export const manifestCommand: CliCommand = {
     const counts = countsOf(manifest);
 
     if (flagBool(ctx.args, 'check')) {
-      // BOTH files the command writes: `--check` compared only `x.manifest.json`, so a stale
-      // `openapi.json` — the one the typed client is generated from — read as fresh.
-      const stale = [
-        ...[await staleness(root, manifest)].filter((one) => one !== undefined),
-        ...(await openApiStaleness(root, manifest)),
-      ];
+      // The gate's own check, through its function (`manifest-staleness.ts`): both files this
+      // command writes, and the same code for each condition `x verify`'s `manifest` step gives.
+      const stale = await manifestStaleness(root, manifest);
       return {
         ok: stale.length === 0 && findings.length === 0,
         command: 'manifest',

package/src/cmd-mcp.ts

@@ -3,17 +3,24 @@
 // supplies only the app, the caller and the socket. A tool answered here would be a second answer
 // to a question the framework already answers.
 
-import { markListening, nanoid, timingSafeEqual } from '@ultimat3/core';
-import { mcpHttpRoute, serveStdio } from '@ultimat3/mcp';
+import {
+  markListening,
+  nanoid,
+  renderFixShellArg,
+  timingSafeEqual,
+  UltimateError,
+} from '@ultimat3/core';
+import { mcpHttpRoute, type StdioTransportInput, serveStdio } from '@ultimat3/mcp';
 import { requireAppRoot } from './app-root';
 import { DEFAULT_PORT, mcpSpec } from './cmd-mcp-spec';
 import type { CliCommand, CommandContext } from './command';
 import { BadFlagError } from './errors';
-import { intFlagOr, PORT_RANGE } from './flag-number';
+import { intFlagOr, neighbouringPort, PORT_RANGE } from './flag-number';
 import { holdUntilShutdown } from './hold';
 import type { CliMcpServer } from './mcp-host';
 import { createDevMcpServer, DEV_TOOL_SCOPES } from './mcp-host';
 import { msg } from './messages';
+import { isAddressInUse } from './metrics-endpoint';
 import type { CommandResult } from './output';
 import { flagString } from './parse';
 
@@ -30,8 +37,12 @@ const isTransport = (value: string): value is Transport =>
 
 /** The catalog, from the server's own registry — never a list kept here. */
 async function catalog(host: CliMcpServer): Promise<CommandResult> {
-  const tools = host.server.list(host.caller);
-  await host.close();
+  let tools: ReturnType<CliMcpServer['server']['list']>;
+  try {
+    tools = host.server.list(host.caller);
+  } finally {
+    await host.close();
+  }
   return {
     ok: true,
     command: 'mcp',
@@ -56,6 +67,21 @@ const notFound = (path: string): Response =>
     { status: 404, headers: { 'content-type': 'application/json' } },
   );
 
+/**
+ * The MCP port is bound already — by another `x mcp serve`, or by the inspector, whose default
+ * 9229 this one shares. `metrics-endpoint.ts`'s pattern: an `EADDRINUSE` throw becomes the
+ * framework's `X_PORT_IN_USE`, with the invocation one port over.
+ */
+export class McpPortInUseError extends UltimateError {
+  constructor(input: { port: number }) {
+    super({
+      code: 'X_PORT_IN_USE',
+      cause: `port ${String(input.port)} is already bound, so x mcp serve could not open its HTTP transport`,
+      fix: `x mcp serve --transport http --port ${renderFixShellArg(String(neighbouringPort(input.port)), '9230')}`,
+    });
+  }
+}
+
 /** A running HTTP transport. `stop()` releases the socket AND the host's lazily booted services. */
 export interface McpHttpServer {
   readonly result: CommandResult;
@@ -70,7 +96,7 @@ export interface McpHttpServer {
  * directory outlive `run()` otherwise, and nothing — a test, an embedding caller, or a signal —
  * could ever release them.
  */
-export function startMcpHttp(host: CliMcpServer, port: number): McpHttpServer {
+export async function startMcpHttp(host: CliMcpServer, port: number): Promise<McpHttpServer> {
   const token = nanoid(32);
   const route = mcpHttpRoute({
     server: host.server,
@@ -83,17 +109,26 @@ export function startMcpHttp(host: CliMcpServer, port: number): McpHttpServer {
         ? { actor: host.caller.actor, scopes: DEV_TOOL_SCOPES }
         : null,
   });
-  const handle = Bun.serve({
-    port,
-    hostname: 'localhost',
-    fetch: (request: Request): Response | Promise<Response> => {
-      const url = new URL(request.url);
-      if (request.method !== route.method || url.pathname !== route.path) {
-        return notFound(route.path);
-      }
-      return route.handle(request);
-    },
-  });
+  let handle: ReturnType<typeof Bun.serve>;
+  try {
+    handle = Bun.serve({
+      port,
+      hostname: 'localhost',
+      fetch: (request: Request, server): Response | Promise<Response> => {
+        const url = new URL(request.url);
+        if (request.method !== route.method || url.pathname !== route.path) {
+          return notFound(route.path);
+        }
+        // The socket's peer: failed tokens are metered per address, and only the server knows it.
+        return route.handle(request, { address: server.requestIP(request)?.address });
+      },
+    });
+  } catch (error) {
+    // The host booted before the bind; a refusal that left it open would leak its database.
+    await host.close();
+    if (isAddressInUse(error)) throw new McpPortInUseError({ port });
+    throw error;
+  }
   // Announces the socket as this process's own, so a caller on it is never mistaken for egress.
   const stopListening = markListening(handle.url.origin);
   const url = `${handle.url.origin}${route.path}`;
@@ -131,10 +166,24 @@ export const stdioResult = (tools: number): CommandResult => ({
   stream: 'stderr',
 });
 
-/** stdout is the WIRE: `serveStdio` owns fd 1 for as long as the peer holds stdin open. */
-async function serveOverStdio(host: CliMcpServer): Promise<CommandResult> {
-  await serveStdio({ server: host.server, caller: host.caller });
-  await host.close();
+/** The pipe a session reads, when it is not this process's own stdin — a test's script. */
+export type StdioPipe = Pick<StdioTransportInput, 'input' | 'write'>;
+
+/**
+ * stdout is the WIRE: `serveStdio` owns fd 1 for as long as the peer holds stdin open. Exported
+ * with `pipe` so a test can end the session with a throw instead of a closed stdin.
+ */
+export async function serveOverStdio(
+  host: CliMcpServer,
+  pipe: StdioPipe = {},
+): Promise<CommandResult> {
+  // `finally`, as `startMcpHttp`'s refused bind does: a session that throws must not leave the
+  // host's PGlite data directory held by a process about to report the failure.
+  try {
+    await serveStdio({ server: host.server, caller: host.caller, ...pipe });
+  } finally {
+    await host.close();
+  }
   return stdioResult(host.tools.length);
 }
 
@@ -179,7 +228,7 @@ export const mcpCommand: CliCommand = {
     // starts is what releases the socket and the database. Registering a shutdown hook and
     // returning was the older shape — nothing installed a signal handler, so the hook was never
     // reached and the exit code closed the socket the line above had just announced.
-    const served = startMcpHttp(host, port);
+    const served = await startMcpHttp(host, port);
     return { ...served.result, hold: holdUntilShutdown('mcp', () => served.stop()) };
   },
 };