pi-maestro-teammate 2.1.0 → 2.3.0

package/README.md

@@ -187,7 +187,17 @@ project .pi/agents > project .agents > ~/.agents > legacy user directory > bundl
 
 ## Model Routing Profiles
 
-Configure task-type defaults with `Alt+M` or `/teammate-models`. The Control Center's **Profiles** tab manages named routing Profiles shared by every project. Its **Routing** tab edits the active global Profile and combines built-in task types, discovered agent types, and types already present in that Profile.
+Configure task-type defaults with `Alt+M` or `/teammate-models`. The Control Center's **Profiles** tab is the saved-template system: it manages multiple named routing Profiles shared by every project. Its **Routing** tab edits the active global Profile and combines built-in task types, discovered agent types, and types already present in that Profile.
+
+Switch the current project's template directly by stable Profile ID or display name. With no argument, the command opens the Control Center on **Profiles**:
+
+```text
+/teammate-model fast-lane
+/teammate-model Fast Lane
+/teammate-model
+```
+
+Command completion lists every saved template and marks the project-active and global-default entries. If display names are duplicated, use the stable ID. Direct switching disables but preserves project overrides, matching the Profiles UI.
 
 The **Roles** tab lists discovered roles and their effective durable route. Role-scoped settings can be edited through the unified Settings surface as `role.<role-name>.model`, `role.<role-name>.fallbacks`, and `role.<role-name>.thinking`. These settings are stored in the same global Profile or project override file; package updates never rewrite role definitions or user routing data.
 

package/bin/pi-teammate-outbox.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { createJiti } from "jiti";
+
+const jiti = createJiti(import.meta.url, { interopDefault: true });
+const { main } = await jiti.import("../src/completion-outbox/cli.ts");
+
+try {
+  process.exitCode = await main(process.argv.slice(2));
+} catch (error) {
+  process.stderr.write(`pi-teammate-outbox: ${error instanceof Error ? error.message : String(error)}\n`);
+  process.exitCode = 1;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-maestro-teammate",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "Pi extension — teammate agent dispatch with DAG task graphs, RPC messaging, and compact TUI",
   "type": "module",
   "engines": {
@@ -9,6 +9,7 @@
   "bin": {
     "pi-teammate-broker": "./bin/pi-teammate-broker.mjs",
     "pi-teammate-models": "./bin/pi-teammate-models.mjs",
+    "pi-teammate-outbox": "./bin/pi-teammate-outbox.mjs",
     "pi-teammate-remote": "./bin/pi-teammate-remote.mjs"
   },
   "keywords": [
@@ -19,7 +20,7 @@
     "agents"
   ],
   "scripts": {
-    "test": "node --experimental-transform-types --import ./test/setup.ts --test --test-concurrency=4 \"test/*.test.ts\"",
+    "test": "node --experimental-transform-types --import ./test/setup.ts --test --test-concurrency=2 \"test/*.test.ts\"",
     "typecheck": "tsc -p tsconfig.build.json",
     "build:declarations": "tsc -p tsconfig.declarations.json",
     "check:declarations": "node scripts/check-declarations.mjs",
@@ -72,6 +73,10 @@
       "types": "./types/public/v1/model-routing.d.ts",
       "default": "./src/public/v1/model-routing.ts"
     },
+    "./v1/monitor-window-state": {
+      "types": "./types/public/v1/monitor-window-state.d.ts",
+      "default": "./src/public/v1/monitor-window-state.ts"
+    },
     "./v1/cli-tools": {
       "types": "./types/public/v1/cli-tools.d.ts",
       "default": "./src/public/v1/cli-tools.ts"
@@ -100,6 +105,10 @@
       "types": "./types/public/v1/retry.d.ts",
       "default": "./src/public/v1/retry.ts"
     },
+    "./v1/session-history": {
+      "types": "./types/public/v1/session-history.d.ts",
+      "default": "./src/public/v1/session-history.ts"
+    },
     "./v1/scheduler": {
       "types": "./types/public/v1/scheduler.d.ts",
       "default": "./src/public/v1/scheduler.ts"
@@ -112,6 +121,10 @@
       "types": "./types/public/v1/supervision.d.ts",
       "default": "./src/public/v1/supervision.ts"
     },
+    "./v1/ssh-hosts": {
+      "types": "./types/public/v1/ssh-hosts.d.ts",
+      "default": "./src/public/v1/ssh-hosts.ts"
+    },
     "./v1/workspace-projections": {
       "types": "./types/public/v1/workspace-projections.d.ts",
       "default": "./src/public/v1/workspace-projections.ts"
@@ -192,11 +205,11 @@
     "pi-maestro-settings-core"
   ],
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "0.83.0",
+    "@earendil-works/pi-agent-core": "0.84.4",
     "@types/cross-spawn": "6.0.6",
-    "@earendil-works/pi-ai": "0.83.0",
-    "@earendil-works/pi-coding-agent": "0.83.0",
-    "@earendil-works/pi-tui": "0.83.0",
+    "@earendil-works/pi-ai": "0.84.4",
+    "@earendil-works/pi-coding-agent": "0.84.4",
+    "@earendil-works/pi-tui": "0.84.4",
     "@types/ssh2": "1.15.5",
     "typebox": "1.3.7"
   },

package/src/backends/acp-cli-catalog.ts

@@ -43,6 +43,9 @@ export const ACP_CLI_SETTINGS_CATALOGS: TranslationCatalogs = {
     "acpCli.mode": "Launch mode",
     "acpCli.mode.local": "Local process",
     "acpCli.mode.ssh": "Remote over SSH",
+    "acpCli.sshHostRef": "/ssh host reference",
+    "acpCli.sshHostRef.description":
+      "Host id from the unlocked encrypted /ssh manager. Use it instead of every embedded SSH connection field; the host is resolved again for each run.",
     "acpCli.host": "SSH host",
     "acpCli.user": "SSH user",
     "acpCli.port": "SSH port",
@@ -92,6 +95,9 @@ export const ACP_CLI_SETTINGS_CATALOGS: TranslationCatalogs = {
     "acpCli.mode": "启动方式",
     "acpCli.mode.local": "本地进程",
     "acpCli.mode.ssh": "经 SSH 远程",
+    "acpCli.sshHostRef": "/ssh 主机引用",
+    "acpCli.sshHostRef.description":
+      "已解锁加密 /ssh 管理器中的主机 id。它必须替代全部内嵌 SSH 连接字段，并在每次运行时重新解析。",
     "acpCli.host": "SSH 主机",
     "acpCli.user": "SSH 用户",
     "acpCli.port": "SSH 端口",

package/src/backends/acp-cli.ts

@@ -52,6 +52,7 @@ import type {
 import {
   cliToolArgv,
   probeCliToolCommand,
+  sshHostConfigIssue,
   type CliToolConfig,
 } from "../cli-tools/cli-tools-config.ts";
 import {
@@ -282,9 +283,18 @@ export const ACP_CLI_CONFIG_FIELDS: readonly BackendConfigField[] = [
     labelKey: "acpCli.mode",
     default: "local",
   },
+  {
+    key: "sshHostRef",
+    kind: "text",
+    labelKey: "acpCli.sshHostRef",
+    descriptionKey: "acpCli.sshHostRef.description",
+  },
   { key: "host", kind: "text", labelKey: "acpCli.host" },
   { key: "user", kind: "text", labelKey: "acpCli.user" },
-  { key: "port", kind: "integer", labelKey: "acpCli.port", default: 22 },
+  // Applied only to embedded SSH below. Leaving this declaration without a
+  // generic default lets validation distinguish an explicit override from a
+  // reference that must take its port exclusively from `/ssh`.
+  { key: "port", kind: "integer", labelKey: "acpCli.port" },
   { key: "hostKeySha256", kind: "text", labelKey: "acpCli.hostKeySha256" },
   { key: "identityFile", kind: "path", labelKey: "acpCli.identityFile" },
   {
@@ -420,6 +430,7 @@ async function installedLaunchConfig(
 function launchConfigOf(config: Record<string, ConfigValue>): CliToolConfig {
   const command = text(config, "command");
   const cwd = text(config, "cwd");
+  const sshHostRef = text(config, "sshHostRef");
   const host = text(config, "host");
   const user = text(config, "user");
   const port = count(config, "port");
@@ -432,6 +443,7 @@ function launchConfigOf(config: Record<string, ConfigValue>): CliToolConfig {
     args: list(config, "args"),
     ...(cwd === undefined ? {} : { cwd }),
     env: list(config, "env"),
+    ...(sshHostRef === undefined ? {} : { sshHostRef }),
     ...(host === undefined ? {} : { host }),
     ...(user === undefined ? {} : { user }),
     ...(port === undefined ? {} : { port }),
@@ -605,14 +617,18 @@ export function createAcpCliBackend(
           + "parent process forwards by name; a name=value entry puts the value in the registration document",
         );
       }
-      // Checked at load rather than at launch: the runner's ssh path already
-      // fails closed on an incomplete host, but it does so per run, long after
-      // the operator stopped looking at the file that caused it.
+      // Checked at load rather than at launch: one SSH source must be complete
+      // and authoritative. A reference cannot be paired with even a seemingly
+      // harmless port override, because that would recreate two sources of
+      // truth for the connection.
       if (mode === "ssh") {
-        for (const key of ["host", "user", "hostKeySha256"]) {
-          if ((text(config, key) ?? "").trim().length > 0) continue;
-          errors.push(`"${key}" is required when "mode" is "ssh"`);
+        const issue = sshHostConfigIssue(launchConfigOf(values));
+        if (issue !== undefined) errors.push(issue);
+        else if ((text(values, "sshHostRef") ?? "").trim().length === 0 && count(values, "port") === undefined) {
+          values.port = 22;
         }
+      } else if ((text(values, "sshHostRef") ?? "").trim().length > 0) {
+        errors.push('"sshHostRef" requires "mode" to be "ssh"');
       }
       return { values, errors };
     },
@@ -638,7 +654,7 @@ export function createAcpCliBackend(
         // beats returning the local machine's answer for a remote target.
         throw new Error(
           `teammate backend "acp-cli" cannot list "${field}" for an "ssh" registration: `
-          + "the probe launches the agent locally, so the target host's catalogue is not reachable here",
+          + "whether embedded or selected by sshHostRef, the target host's catalogue is not reachable by the local probe",
         );
       }
       const route = routeOf(config);
@@ -796,6 +812,7 @@ export function createAcpCliBackend(
  * registration ship fields whose keys have no text.
  */
 export { ACP_CLI_SETTINGS_CATALOGS } from "./acp-cli-catalog.ts";
+export { probeSshCliExecutable } from "../remote/ssh-exec.ts";
 
 /**
  * The registered instance.

package/src/cli-tools/cli-tools-config.ts

@@ -6,8 +6,8 @@
  * models and executed over the Agent Client Protocol:
  *
  * - mode "local": the CLI is spawned on this machine (which/where reachability);
- * - mode "ssh": the CLI runs on a remote host over a direct ssh2 exec, with the
- *   ssh connection fields embedded per tool (host/user/port/hostKeySha256/identityFile).
+ * - mode "ssh": the CLI runs on a remote host over a direct ssh2 exec, using
+ *   either an `/ssh` manager reference or embedded connection fields.
  *
  * Discovery follows the same convention as teammate-models.json / teammate-remotes.json:
  * the global file is ~/.pi/agent/teammate-cli-tools.json and the project file is
@@ -17,13 +17,16 @@
  * ~/.maestro/cli-tools.json for pi-maestro-flow's original provider registration.
  */
 
-import { execFileSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import type { AvailableModelEntry } from "../models/model-catalog.ts";
 import type { RemoteHostConfig } from "../remote/types.ts";
-import { probeSshCliExecutable } from "../remote/ssh-exec.ts";
+import { resolveSshHostRef } from "../public/v1/ssh-hosts.ts";
+import {
+  probeSshCliExecutable,
+  remoteHostConfigFromSshProfile,
+} from "../remote/ssh-exec.ts";
 
 /** Launch configuration for a teammate-managed CLI tool. */
 export interface CliToolConfig {
@@ -38,7 +41,8 @@ export interface CliToolConfig {
   cwd?: string;
   /** Trusted environment-variable names forwarded from the parent process. */
   env?: readonly string[];
-  // SSH connection fields (mode "ssh" only):
+  // SSH source (mode "ssh" only): a manager reference OR embedded fields.
+  sshHostRef?: string;
   host?: string;
   user?: string;
   port?: number;
@@ -82,7 +86,6 @@ export interface MaestroDelegateConfig {
 
 const GLOBAL_CONFIG_FILE = "teammate-cli-tools.json";
 const LEGACY_CONFIG_PATH = path.join(os.homedir(), ".maestro", "cli-tools.json");
-const PROBE_TIMEOUT_MS = 2_000;
 const PROBE_CACHE_TTL_MS = 30_000;
 
 export function getGlobalCliToolsConfigPath(): string {
@@ -237,24 +240,73 @@ export function cliToolArgv(name: string, config: CliToolConfig): [string, ...st
   return [cliToolCommand(name, config), ...(config.args ?? [])];
 }
 
-/** SSH connection fields lifted from a tool config; null if incomplete. */
-export function sshHostConfigOf(config: CliToolConfig): RemoteHostConfig | null {
-  if ((config.mode ?? "local") !== "ssh") return null;
+const SSH_INLINE_FIELDS: readonly (keyof CliToolConfig)[] = [
+  "host",
+  "user",
+  "port",
+  "hostKeySha256",
+  "identityFile",
+];
+
+function hasInlineSshField(config: CliToolConfig): boolean {
+  return SSH_INLINE_FIELDS.some((key) => {
+    const value = config[key];
+    return typeof value === "number" || (typeof value === "string" && value.trim().length > 0);
+  });
+}
+
+/** Safe configuration diagnostic for one ssh-mode tool, or undefined when complete. */
+export function sshHostConfigIssue(config: CliToolConfig): string | undefined {
+  if ((config.mode ?? "local") !== "ssh") return undefined;
+  const rawRef = config.sshHostRef;
+  const hostRef = rawRef?.trim() ?? "";
+  if (rawRef !== undefined && hostRef.length === 0) {
+    return "sshHostRef must be a non-empty /ssh host id";
+  }
+  if (hostRef && hasInlineSshField(config)) {
+    return "sshHostRef cannot be combined with host, user, port, hostKeySha256 or identityFile";
+  }
+  if (hostRef) return undefined;
+
   const host = config.host?.trim() ?? "";
   const user = config.user?.trim() ?? "";
-  const port = config.port ?? 22;
   const hostKeySha256 = config.hostKeySha256?.trim() ?? "";
-  if (!host || !user || !hostKeySha256) return null;
-  if (!Number.isInteger(port) || port < 1 || port > 65_535) return null;
+  if (!host || !user || !hostKeySha256) {
+    return "ssh mode requires sshHostRef or host, user and hostKeySha256";
+  }
+  const port = config.port ?? 22;
+  if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+    return "ssh port must be an integer between 1 and 65535";
+  }
+  return undefined;
+}
+
+/** Embedded SSH connection fields lifted from a tool config; null for references or invalid input. */
+export function sshHostConfigOf(config: CliToolConfig): RemoteHostConfig | null {
+  if (sshHostConfigIssue(config) !== undefined || (config.sshHostRef?.trim() ?? "")) return null;
+  if ((config.mode ?? "local") !== "ssh") return null;
   return {
-    host,
-    user,
-    port,
-    hostKeySha256,
+    host: config.host!.trim(),
+    user: config.user!.trim(),
+    port: config.port ?? 22,
+    hostKeySha256: config.hostKeySha256!.trim(),
     ...(config.identityFile?.trim() ? { identityFile: config.identityFile.trim() } : {}),
   };
 }
 
+/** Resolve either host source immediately before a new direct-SSH connection. */
+export async function resolveSshHostConfigOf(config: CliToolConfig): Promise<RemoteHostConfig> {
+  const issue = sshHostConfigIssue(config);
+  if (issue !== undefined) throw new Error(issue);
+  const hostRef = config.sshHostRef?.trim();
+  if (hostRef) {
+    return remoteHostConfigFromSshProfile(await resolveSshHostRef(hostRef));
+  }
+  const inline = sshHostConfigOf(config);
+  if (!inline) throw new Error("ssh mode requires sshHostRef or complete embedded SSH fields");
+  return inline;
+}
+
 export interface CliToolProbeResult {
   ok: boolean;
   command: string;
@@ -280,6 +332,10 @@ const sshProbeInflight = new Map<string, Promise<void>>();
  */
 function probeCacheKey(command: string, config: CliToolConfig): string {
   if ((config.mode ?? "local") !== "ssh") return JSON.stringify(["local", command]);
+  const hostRef = config.sshHostRef?.trim();
+  if (hostRef && sshHostConfigIssue(config) === undefined) {
+    return JSON.stringify(["ssh-ref", hostRef, command]);
+  }
   const hostConfig = sshHostConfigOf(config);
   // An incomplete ssh config has no target to name; the verdict is the same
   // refusal for every such registration, so they share one entry.
@@ -326,6 +382,34 @@ function adapterInstallHint(command: string): string {
   return pkg === undefined ? "" : `; install it with: npm i -g ${pkg}`;
 }
 
+function localExecutableCandidates(command: string): string[] {
+  const hasPathSeparator = command.includes("/") || command.includes("\\");
+  const directories = hasPathSeparator
+    ? [process.cwd()]
+    : (process.env.PATH ?? "").split(path.delimiter).map((entry) => {
+      const trimmed = entry.trim();
+      return trimmed.replace(/^"|"$/g, "") || process.cwd();
+    });
+  const extensions = process.platform === "win32" && path.extname(command) === ""
+    ? ["", ...(process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";")]
+    : [""];
+  return [...new Set(directories.flatMap((directory) =>
+    extensions.map((extension) => path.resolve(directory, `${command}${extension.toLowerCase()}`)),
+  ))];
+}
+
+function localExecutableExists(command: string): boolean {
+  return localExecutableCandidates(command).some((candidate) => {
+    try {
+      if (!fs.statSync(candidate).isFile()) return false;
+      fs.accessSync(candidate, process.platform === "win32" ? fs.constants.F_OK : fs.constants.X_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+}
+
 function probeLocalExecutable(key: string, command: string): CliToolProbeResult {
   const quotedCommand = JSON.stringify(command);
   let result: CliToolProbeResult;
@@ -351,40 +435,29 @@ function probeLocalExecutable(key: string, command: string): CliToolProbeResult
       };
     }
   } else {
-    try {
-      const lookup = process.platform === "win32" ? "where" : "which";
-      execFileSync(lookup, [command], {
-        encoding: "utf8",
-        timeout: PROBE_TIMEOUT_MS,
-        stdio: ["ignore", "ignore", "pipe"],
-        windowsHide: true,
-      });
-      result = { ok: true, command };
-    } catch {
-      result = { ok: false, command, error: `executable ${quotedCommand} not found on PATH${adapterInstallHint(command)}` };
-    }
+    result = localExecutableExists(command)
+      ? { ok: true, command }
+      : { ok: false, command, error: `executable ${quotedCommand} not found on PATH${adapterInstallHint(command)}` };
   }
   probeCache.set(key, { result, at: Date.now() });
   return result;
 }
 
 function probeSshTool(key: string, command: string, config: CliToolConfig): CliToolProbeResult {
-  const hostConfig = sshHostConfigOf(config);
-  if (!hostConfig) {
-    const result: CliToolProbeResult = {
-      ok: false,
-      command,
-      error: "ssh mode requires host, user and hostKeySha256 in teammate-cli-tools.json",
-    };
+  const issue = sshHostConfigIssue(config);
+  if (issue !== undefined) {
+    const result: CliToolProbeResult = { ok: false, command, error: issue };
     probeCache.set(key, { result, at: Date.now() });
     return result;
   }
-  // Optimistically list a complete configuration; warm the cache asynchronously
-  // so the next refresh filters unreachable hosts. Deduplicate concurrent probes.
+  // Optimistically list a complete source while an actual provider-resolution
+  // and remote executable probe warms the cache. This is the same bounded
+  // discovery behavior as embedded SSH, not a local catalogue result.
   const result: CliToolProbeResult = { ok: true, command };
   probeCache.set(key, { result, at: Date.now() });
   if (!sshProbeInflight.has(key)) {
-    const probe = probeSshCliExecutable(hostConfig, command)
+    const probe = resolveSshHostConfigOf(config)
+      .then((hostConfig) => probeSshCliExecutable(hostConfig, command))
       .then((outcome) => {
         probeCache.set(key, {
           result: outcome.ok
@@ -393,9 +466,13 @@ function probeSshTool(key: string, command: string, config: CliToolConfig): CliT
           at: Date.now(),
         });
       })
-      .catch(() => {
+      .catch((error: unknown) => {
         probeCache.set(key, {
-          result: { ok: false, command, error: `remote executable "${command}" probe failed` },
+          result: {
+            ok: false,
+            command,
+            error: error instanceof Error ? error.message : `remote executable "${command}" probe failed`,
+          },
           at: Date.now(),
         });
       })

package/src/cli-tools/local-acp.ts

@@ -34,7 +34,7 @@ import type {
 import {
   cliToolArgv,
   probeCliToolCommand,
-  sshHostConfigOf,
+  resolveSshHostConfigOf,
   type CliToolConfig,
 } from "./cli-tools-config.ts";
 
@@ -174,11 +174,15 @@ export async function runSshCliTool(
   params: RunLocalCliToolParams,
 ): Promise<CliToolRunResult> {
   const startedAt = Date.now();
-  const hostConfig = sshHostConfigOf(params.config);
-  if (!hostConfig) {
+  let hostConfig: Awaited<ReturnType<typeof resolveSshHostConfigOf>>;
+  try {
+    // Resolve for every new run: locking, deleting, or editing an `/ssh` host
+    // therefore affects new connections without disturbing an active channel.
+    hostConfig = await resolveSshHostConfigOf(params.config);
+  } catch (error) {
     return failedResult(
       startedAt,
-      `CLI tool "${params.tool}" ssh mode requires host, user and hostKeySha256 in teammate-cli-tools.json`,
+      `CLI tool "${params.tool}" SSH host could not be resolved: ${error instanceof Error ? error.message : "unknown SSH host error"}`,
     );
   }
 

package/src/completion-outbox/cli.ts

@@ -0,0 +1,123 @@
+import * as path from "node:path";
+import { CompletionOutboxFileStore } from "./file-store.ts";
+import { getRuntimeWorkspaceIdentity } from "../runtime-broker/private-state.ts";
+
+interface ParsedOptions {
+  command?: "cleanup";
+  workspace: string;
+  rootDir?: string;
+  apply: boolean;
+  json: boolean;
+  maxEntries?: number;
+  help: boolean;
+}
+
+function usage(): string {
+  return [
+    "Usage: pi-teammate-outbox cleanup [options]",
+    "",
+    "Safely removes obsolete atomic-replacement remnants while preserving the",
+    "latest recoverable transaction for every canonical outbox file.",
+    "",
+    "Options:",
+    "  --workspace <path>   Workspace whose outbox is cleaned (default: cwd)",
+    "  --root <path>        Completion outbox root directory",
+    "  --apply              Delete candidates; without this flag cleanup is dry-run",
+    "  --max-entries <n>    Refuse scans larger than n entries (default: 100000)",
+    "  --json               Emit one JSON result",
+    "  --help               Show this help",
+    "",
+    "Exit codes: 0 success, 2 usage error, 3 workspace outbox is busy.",
+  ].join("\n");
+}
+
+function parsePositiveInteger(value: string | undefined, option: string): number {
+  if (!value || !/^\d+$/.test(value)) throw new Error(`${option} requires a positive integer`);
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < 1 || parsed > 1_000_000) {
+    throw new Error(`${option} must be between 1 and 1000000`);
+  }
+  return parsed;
+}
+
+function parseOptions(args: readonly string[]): ParsedOptions {
+  const first = args[0];
+  const command = first === "cleanup" ? first : undefined;
+  const help = args.includes("--help") || args.includes("-h");
+  const options: ParsedOptions = {
+    command,
+    workspace: process.cwd(),
+    apply: false,
+    json: false,
+    help,
+  };
+  for (let index = command ? 1 : (help ? 1 : 0); index < args.length; index += 1) {
+    const argument = args[index];
+    if (argument === "--help" || argument === "-h") continue;
+    if (argument === "--apply") {
+      options.apply = true;
+      continue;
+    }
+    if (argument === "--json") {
+      options.json = true;
+      continue;
+    }
+    const value = args[++index];
+    if (argument === "--workspace") {
+      if (!value) throw new Error("--workspace requires a path");
+      options.workspace = path.resolve(value);
+    } else if (argument === "--root") {
+      if (!value) throw new Error("--root requires a path");
+      options.rootDir = path.resolve(value);
+    } else if (argument === "--max-entries") {
+      options.maxEntries = parsePositiveInteger(value, argument);
+    } else {
+      throw new Error(`Unknown option: ${argument}`);
+    }
+  }
+  return options;
+}
+
+export async function main(args = process.argv.slice(2)): Promise<number> {
+  const options = parseOptions(args);
+  if (options.help || !options.command) {
+    process.stdout.write(`${usage()}\n`);
+    return options.help ? 0 : 2;
+  }
+
+  const identity = getRuntimeWorkspaceIdentity(options.workspace);
+  const store = new CompletionOutboxFileStore({
+    ...(options.rootDir === undefined ? {} : { rootDir: options.rootDir }),
+  });
+  const result = await store.cleanupRemnants(identity.workspaceId, {
+    apply: options.apply,
+    ...(options.maxEntries === undefined ? {} : { maxEntries: options.maxEntries }),
+  });
+  const output = {
+    workspace: identity.canonicalPath,
+    workspaceId: identity.workspaceId,
+    rootDir: store.rootDir,
+    ...result,
+  };
+
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(output)}\n`);
+  } else if (result.busy) {
+    process.stderr.write(`Completion outbox is busy for ${identity.canonicalPath}; nothing was removed.\n`);
+  } else {
+    process.stdout.write([
+      `Completion outbox cleanup: ${result.apply ? "applied" : "dry-run"}`,
+      `Workspace: ${identity.canonicalPath}`,
+      `Scanned: ${result.scannedEntries} entries (${result.replacementFiles} replacement remnants)`,
+      `Preserved: ${result.preservedFiles}`,
+      `Candidates: ${result.candidateFiles} files, ${result.candidateBytes} bytes`,
+      `Removed: ${result.removedFiles} files, ${result.removedBytes} bytes`,
+      ...(result.candidateSample.length === 0 ? [] : [
+        "Candidate sample:",
+        ...result.candidateSample.map((candidate) => `  ${candidate}`),
+      ]),
+      ...(!result.apply && result.candidateFiles > 0 ? ["Re-run with --apply to remove these candidates."] : []),
+    ].join("\n") + "\n");
+  }
+  return result.busy ? 3 : 0;
+}

package/src/completion-outbox/coordinator.ts

@@ -151,15 +151,10 @@ export class CompletionDeliveryCoordinator {
   #binding: CompletionSessionBinding | undefined;
   #unsubscribe: (() => void) | undefined;
   #disposed = false;
-  // Throttle store.gc() inside reconcile(): a full workspace GC under the lock
-  // competes with reserve()/importIntent() writers and is the main source of the
-  // "Timed out acquiring completion outbox lock" warnings. Expired records are
-  // inert (deliverDue/acquireClaim already reject expired entries), so skipping
-  // a sweep between two reconciles is safe; the next reconcile past this gap
-  // reclaims them. This is the only place store.gc() is called — bindSession()
-  // relies on this reconcile path for the initial sweep on a fresh binding.
-  // Seeded lazily on the first reconcile so the first sweep always runs (a zero
-  // seed under a small mocked clock would otherwise skip the first sweep).
+  // Throttle GC attempts inside reconcile(). tryGc() also persists a cross-process
+  // page/expiry fence, but this local guard prevents one coordinator from
+  // immediately reacquiring the maintenance lock while a backlog remains.
+  // Seeded lazily so the first reconcile still attempts one non-blocking page.
   #lastReconcileGcAt: number | undefined;
 
   constructor(options: CompletionCoordinatorOptions = {}) {
@@ -331,12 +326,12 @@ export class CompletionDeliveryCoordinator {
       // failed" warning. Canonical and legacy roots remain isolated and are
       // swept independently; no alias root is merged or deleted.
       if (this.#lastReconcileGcAt === undefined || now - this.#lastReconcileGcAt >= RECONCILE_GC_MIN_INTERVAL_MS) {
-        let swept = false;
+        let attempted = false;
         for (const target of targets) {
           const result = await this.store.tryGc(target.workspaceId);
-          if (!result.busy && !result.skipped && !result.hasMore) swept = true;
+          if (!result.busy && !result.skipped) attempted = true;
         }
-        if (swept) this.#lastReconcileGcAt = now;
+        if (attempted) this.#lastReconcileGcAt = now;
       }
       const providers = new Set<CompletionDurabilityProvider>();
       const currentProvider = this.registry.current();