A self-improving RLM agent for coding workflows and long-running autonomous tasks.
Rust
standardize cli commands and discovery (#423)
ktebb240e5a8dc
diff --git a/README.md b/README.mdindex 93cf99b1f6..fc4f7f438d 100644--- a/README.md+++ b/README.md@@ -68,3 +68,14 @@ Authenticate in the TUI with:```text/login```++## Common Commands++```bash+prime-agent # Start a new session+prime-agent agents # Open the agents view+prime-agent --resume [path|id] # Browse or resume a previous session+prime-agent doctor [--fix] # Inspect or repair background services+prime-agent update [--force] # Update Prime Agent+prime-agent shutdown [--force] # Stop every agent, worker, and background service+```diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.mdindex dacf2e36c4..d4aedf8b9e 100644--- a/packages/coding-agent/CHANGELOG.md+++ b/packages/coding-agent/CHANGELOG.md@@ -2,6 +2,7 @@## [Unreleased]+- Changed shell commands to use discoverable agent, schedule, package, model, session, update, doctor, and full-shutdown verbs without exposing the background daemon hierarchy ([ENG-4538](https://linear.app/primeintellect/issue/ENG-4538/standardize-bash-command-conventions-and-improve-command-discovery)).- Fixed unsupported Node versions crashing before startup by requiring Node 22.8.0 or newer and showing upgrade guidance before loading the CLI ([ENG-4260](https://linear.app/primeintellect/issue/ENG-4260/incorrect-node-version-breaks-first-launch)).- Added `@` file-path autocomplete to new-agent and reply prompts in the Agents View.- Added a combined heartbeat indicator and manager for pausing, resuming, or stopping user and agent heartbeats ([ENG-4536](https://linear.app/primeintellect/issue/ENG-4536/add-heartbeat-observability-and-management-ui)).diff --git a/packages/coding-agent/README.md b/packages/coding-agent/README.mdindex d96966466d..84ab805b9c 100644--- a/packages/coding-agent/README.md+++ b/packages/coding-agent/README.md@@ -400,28 +400,23 @@ Bundle and share extensions, skills, prompts, and themes via npm or git.> **Security:** Prime Agent packages run with full system access. Extensions execute arbitrary code, and skills can instruct the model to perform any action including running executables. Review source code before installing third-party packages.```bash-prime-agent install npm:@foo/prime-agent-tools-prime-agent install npm:@foo/[email protected] # pinned version-prime-agent install git:github.com/user/repo-prime-agent install git:github.com/user/repo@v1 # tag or commit-prime-agent install git:[email protected]:user/repo-prime-agent install git:[email protected]:user/repo@v1 # tag or commit-prime-agent install https://github.com/user/repo-prime-agent install https://github.com/user/repo@v1 # tag or commit-prime-agent install ssh://[email protected]/user/repo-prime-agent install ssh://[email protected]/user/repo@v1 # tag or commit-prime-agent remove npm:@foo/prime-agent-tools-prime-agent uninstall npm:@foo/prime-agent-tools # alias for remove-prime-agent list-prime-agent update # update Prime Agent and packages (skips pinned packages)-prime-agent update --extensions # update packages only-prime-agent update --self # update Prime Agent only-prime-agent update --self --force # reinstall Prime Agent even if current-prime-agent update npm:@foo/prime-agent-tools # update one package-prime-agent config # enable/disable extensions, skills, prompts, themes+prime-agent package install npm:@foo/prime-agent-tools+prime-agent package install npm:@foo/[email protected] # pinned version+prime-agent package install git:github.com/user/repo+prime-agent package install git:github.com/user/repo@v1 # tag or commit+prime-agent package install git:[email protected]:user/repo+prime-agent package install https://github.com/user/repo+prime-agent package install ssh://[email protected]/user/repo+prime-agent package remove npm:@foo/prime-agent-tools+prime-agent package list+prime-agent package update # update packages, except pinned versions+prime-agent package update npm:@foo/prime-agent-tools # update one package+prime-agent update # update Prime Agent+prime-agent update --force # reinstall Prime Agent even if current+prime-agent config # enable/disable package resources```-Packages install to `~/.prime/agent/git/` (git) or global npm. Use `-l` for project-local installs (`.prime/agent/git/`, `.prime/agent/npm/`). Git packages install dependencies with `npm install --omit=dev` by default, so runtime deps must be listed under `dependencies`; when `npmCommand` is configured, git packages use plain `install` for compatibility with wrappers. If you use a Node version manager and want package installs to reuse a stable npm context, set `npmCommand` in `settings.json`, for example `["mise", "exec", "node@20", "--", "npm"]`.+Packages install to `~/.prime/agent/git/` (git) or global npm. Use `--local` for project-local installs (`.prime/agent/git/`, `.prime/agent/npm/`). Git packages install dependencies with `npm install --omit=dev` by default, so runtime deps must be listed under `dependencies`; when `npmCommand` is configured, git packages use plain `install` for compatibility with wrappers. If you use a Node version manager and want package installs to reuse a stable npm context, set `npmCommand` in `settings.json`, for example `["mise", "exec", "node@20", "--", "npm"]`.Create a package by adding the inherited `pi` manifest key to `package.json`:@@ -488,19 +483,45 @@ The package architecture, extension model, and source package names still reflecprime-agent [options] [@files...] [messages...]```-### Package Commands+Run `prime-agent help` for the command list and `prime-agent help <command>` for details.++### Agent Commands++```bash+prime-agent agents # Open the agents view+prime-agent list [--all] # List active or saved agents+prime-agent attach <agent> # Attach the interactive UI+prime-agent stop <agent> # Stop one agent+prime-agent rename <agent> <name> # Rename an agent+prime-agent send <agent> <message> # Send an agent-to-agent message+prime-agent status # Show background service status+prime-agent doctor [--fix] # Inspect or safely clean up background services+prime-agent shutdown [--force] # Stop every agent, worker, and background service+```++`shutdown` asks for confirmation. `shutdown --force` skips confirmation and kills unresponsive workers and their tracked child processes.++### Scheduled Prompts++```bash+prime-agent schedule list [--all] [agent]+prime-agent schedule add <agent> <schedule> -- <message>+prime-agent schedule cancel <job-id>+```++Schedules run prompts later or repeatedly. A schedule can be a supported one-time expression such as `in 5m` or a cron expression.++### Package and Update Commands++Packages bundle capabilities such as extensions, skills, prompts, and themes.```bash-prime-agent install <source> [-l] # Install package, -l for project-local-prime-agent remove <source> [-l] # Remove package-prime-agent uninstall <source> [-l] # Alias for remove-prime-agent update [source|self|prime-agent] # Update Prime Agent and packages (skips pinned packages)-prime-agent update --extensions # Update packages only-prime-agent update --self # Update Prime Agent only-prime-agent update --self --force # Reinstall Prime Agent even if current-prime-agent update --extension <src> # Update one package-prime-agent list # List installed packages-prime-agent config # Enable/disable package resources+prime-agent package install <source> [--local]+prime-agent package remove <source> [--local]+prime-agent package list+prime-agent package update [source]+prime-agent update [--force] # Update Prime Agent itself+prime-agent config # Enable/disable package resources```### Modes@@ -511,7 +532,6 @@ prime-agent config # Enable/disable package resources| `-p`, `--print` | Print response and exit || `--mode json` | Output all events as JSON lines (see [docs/json.md](docs/json.md)) || `--mode rpc` | RPC mode for process integration (see [docs/rpc.md](docs/rpc.md)) |-| `--export <in> [out]` | Export session to HTML |In print mode, Prime Agent also reads piped stdin and merges it into the initial prompt:@@ -528,7 +548,8 @@ cat README.md | prime-agent -p "Summarize this text"| `--api-key <key>` | API key (overrides env vars) || `--thinking <level>` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh` || `--models <patterns>` | Comma-separated patterns for Ctrl+P cycling |-| `--list-models [search]` | List available models |++Use `prime-agent model list [search]` to list available models.### Session Options@@ -540,6 +561,8 @@ cat README.md | prime-agent -p "Summarize this text"| `--session-dir <dir>` | Custom session storage directory || `--no-session` | Ephemeral mode (don't save) |+Use `prime-agent session export <file> [output]` to export a saved session to HTML.+### Tool Options| Option | Description |diff --git a/packages/coding-agent/docs/agent-connection-readme.md b/packages/coding-agent/docs/agent-connection-readme.mdindex 7ac1c9e5b6..b377e4f177 100644--- a/packages/coding-agent/docs/agent-connection-readme.md+++ b/packages/coding-agent/docs/agent-connection-readme.md@@ -140,7 +140,7 @@ This matters because the in-process path still exists for explicit fallbacks:- startup benchmark- `--no-session`- `--help`-- `--list-models`+- `prime-agent model list`- other non-interactive modes that are not daemon-backed TUI clientsThe adapter preserves local behavior without preserving the old TUI ownership model.@@ -328,7 +328,7 @@ Current explicit fallbacks include:- `PI_STARTUP_BENCHMARK`- `--no-session`- `--help`-- `--list-models`+- `prime-agent model list`In this path, startup creates the runtime and wraps it:@@ -352,30 +352,11 @@ PR #79 also supports rich TUI attach to existing active daemon sessions.The user-facing shape is:```bash-./prime-agent.sh --resume <selector>+./prime-agent.sh attach <selector>```If `<selector>` names a live active daemon session, startup attaches the rich TUI to that active session instead of opening the session file locally.-There is also a convenience shortcut:--```bash-./prime-agent.sh daemon <selector>-```--That shorthand becomes rich TUI attach only when `<selector>` names a live active session. Explicit daemon CLI commands keep their line-oriented behavior:--```bash-./prime-agent.sh daemon list-./prime-agent.sh daemon attach <selector>-./prime-agent.sh daemon create scratch-```--The difference is intentional:--- `daemon attach` is the line-oriented daemon client.-- `daemon <active-id>` is a convenience shorthand for rich TUI attach when the id is live.-## Execution Surface### Prompt@@ -1063,8 +1044,7 @@ These verify:- normal interactive startup uses daemon-backed mode- explicit fallback paths remain in-process-- rich TUI daemon attach shorthand parsing works-- explicit daemon line-oriented commands are preserved+- `prime-agent attach` resolves active agents through the rich TUI path### Daemon Extension Binding Tests@@ -1091,28 +1071,20 @@ Expected behavior:- interactive mode is backed by `DaemonAgentConnection`- user-visible behavior should match normal interactive use-### Active Daemon Session List+### Active Agent ListRun:```bash-./prime-agent.sh daemon list+./prime-agent.sh list```-This uses the line-oriented daemon CLI, not rich TUI attach.-### Rich TUI AttachStart or find an active daemon session id, then run:```bash-./prime-agent.sh --resume <active-session-id>-```--or:--```bash-./prime-agent.sh daemon <active-session-id>+./prime-agent.sh attach <active-session-id>```Expected behavior:@@ -1121,21 +1093,6 @@ Expected behavior:- it attaches to the existing active daemon session- it does not create a new local in-process runtime for the TUI-### Explicit Line-Oriented Attach--Run:--```bash-./prime-agent.sh daemon attach <active-session-id>-```--Expected behavior:--- line-oriented daemon attach behavior-- not the rich TUI--This distinction is intentional.-## Common Misunderstandings### "Does AgentConnection mean the remote protocol is done?"diff --git a/packages/coding-agent/docs/custom-provider.md b/packages/coding-agent/docs/custom-provider.mdindex 095bc1ca3e..a21e92eeff 100644--- a/packages/coding-agent/docs/custom-provider.md+++ b/packages/coding-agent/docs/custom-provider.md@@ -59,7 +59,7 @@ export default function (pi: ExtensionAPI) {}```-The extension factory can also be `async`. For dynamic model discovery, fetch and register models in the factory instead of `session_start`. pi waits for the factory before startup continues, so the provider is available during interactive startup and to `pi --list-models`.+The extension factory can also be `async`. For dynamic model discovery, fetch and register models in the factory instead of `session_start`. pi waits for the factory before startup continues, so the provider is available during interactive startup and to `prime-agent model list`.## Override Existing Providerdiff --git a/packages/coding-agent/docs/daemon-implementation-summary.md b/packages/coding-agent/docs/daemon-implementation-summary.mdindex 7c12f8f071..b889b0bb60 100644--- a/packages/coding-agent/docs/daemon-implementation-summary.md+++ b/packages/coding-agent/docs/daemon-implementation-summary.md@@ -35,9 +35,9 @@ Normal interactive sessions use resident workers:- Workers monitor the public supervisor socket. If it disappears, one worker acquires an atomic launch lease and starts a replacement supervisor.- A replacement supervisor adopts the existing worker PIDs and active-session IDs.- A worker crash affects only its root tree. Recovery retries after 250 ms, 1 second, and 5 seconds; three failed attempts mark that root failed.-- `prime-agent daemon retry <session>` retries a failed root.-- `prime-agent daemon restart` replaces only the supervisor and adopts workers.-- `prime-agent daemon shutdown` stops workers before the supervisor; `--force` sends `SIGKILL` to workers that do not stop gracefully.+- The agents view can retry a failed root through the internal supervisor protocol.+- Supervisor replacement adopts workers automatically.+- `prime-agent shutdown` stops every worker and supervisor; `--force` also sends `SIGKILL` to unresponsive workers and their tracked child processes.There are no session, worker, client, or workload caps in this layer.diff --git a/packages/coding-agent/docs/extensions.md b/packages/coding-agent/docs/extensions.mdindex 4470a69b84..bf482e969d 100644--- a/packages/coding-agent/docs/extensions.md+++ b/packages/coding-agent/docs/extensions.md@@ -214,7 +214,7 @@ export default async function (pi: ExtensionAPI) {}```-This pattern makes the fetched models available during normal startup and to `pi --list-models`.+This pattern makes the fetched models available during normal startup and to `prime-agent model list`.### Extension Styles@@ -1545,7 +1545,7 @@ Register or override a model provider dynamically. Useful for proxies, custom enCalls made during the extension factory function are queued and applied once the runner initialises. Calls made after that — for example from a command handler following a user setup flow — take effect immediately without requiring a `/reload`.-If you need to discover models from a remote endpoint, prefer an async extension factory over deferring the fetch to `session_start`. pi waits for the factory before startup continues, so the registered models are available immediately, including to `pi --list-models`.+If you need to discover models from a remote endpoint, prefer an async extension factory over deferring the fetch to `session_start`. pi waits for the factory before startup continues, so the registered models are available immediately, including to `prime-agent model list`.```typescript// Register a new provider with custom modelsdiff --git a/packages/coding-agent/docs/models.md b/packages/coding-agent/docs/models.mdindex 0bc4164315..cb35340ffd 100644--- a/packages/coding-agent/docs/models.md+++ b/packages/coding-agent/docs/models.md@@ -200,7 +200,7 @@ If your command is slow, expensive, rate-limited, or should keep using a previou| `compat` | No | provider `compat` | Provider compatibility overrides. Merged with provider-level `compat` when both are set. |Current behavior:-- `/model` and `--list-models` list entries by model `id`.+- `/model` and `prime-agent model list` list entries by model `id`.- The configured `name` is used for model matching and detail/status text.### Thinking Level Mapdiff --git a/packages/coding-agent/docs/packages.md b/packages/coding-agent/docs/packages.mdindex 81da7201e6..93bca7f72d 100644--- a/packages/coding-agent/docs/packages.md+++ b/packages/coding-agent/docs/packages.md@@ -20,23 +20,21 @@ Pi packages bundle extensions, skills, prompt templates, and themes so you can s> **Security:** Pi packages run with full system access. Extensions execute arbitrary code, and skills can instruct the model to perform any action including running executables. Review source code before installing third-party packages.```bash-pi install npm:@foo/[email protected]-pi install git:github.com/user/repo@v1-pi install https://github.com/user/repo # raw URLs work too-pi install /absolute/path/to/package-pi install ./relative/path/to/package--pi remove npm:@foo/bar-pi list # show installed packages from settings-prime-agent update # update Prime Agent and all non-pinned packages-prime-agent update --extensions # update all non-pinned packages only-prime-agent update --self # update Prime Agent only-prime-agent update --self --force # reinstall Prime Agent even if current-prime-agent update npm:@foo/bar # update one package-prime-agent update --extension npm:@foo/bar+prime-agent package install npm:@foo/[email protected]+prime-agent package install git:github.com/user/repo@v1+prime-agent package install https://github.com/user/repo # raw URLs work too+prime-agent package install /absolute/path/to/package+prime-agent package install ./relative/path/to/package++prime-agent package remove npm:@foo/bar+prime-agent package list # show installed packages from settings+prime-agent package update # update all non-pinned packages+prime-agent package update npm:@foo/bar # update one package+prime-agent update # update Prime Agent+prime-agent update --force # reinstall Prime Agent even if current```-By default, `install` and `remove` write to global settings (`~/.pi/agent/settings.json`). Use `-l` to write to project settings (`.pi/settings.json`) instead. Project settings can be shared with your team, and pi installs any missing packages automatically on startup.+By default, `package install` and `package remove` write to global settings (`~/.pi/agent/settings.json`). Use `--local` to write to project settings (`.pi/settings.json`) instead. Project settings can be shared with your team, and Prime Agent installs any missing packages automatically on startup.To try a package without installing it, use `--extension` or `-e`. This installs to a temporary directory for the current run only:@@ -47,7 +45,7 @@ pi -e git:github.com/user/repo## Package Sources-Pi accepts three source types in settings and `pi install`.+Prime Agent accepts three source types in settings and `prime-agent package install`.### npm@@ -56,7 +54,7 @@ npm:@scope/[email protected]npm:pkg```-- Versioned specs are pinned and skipped by package updates (`prime-agent update`, `prime-agent update --extensions`).+- Versioned specs are pinned and skipped by `prime-agent package update`.- Global installs use `npm install -g`.- Project installs go under `.pi/npm/`.- Set `npmCommand` in `settings.json` to pin npm package lookup and install operations to a specific wrapper command such as `mise` or `asdf`.@@ -83,20 +81,20 @@ ssh://[email protected]/user/repo@v1- HTTPS and SSH URLs are both supported.- SSH URLs use your configured SSH keys automatically (respects `~/.ssh/config`).- For non-interactive runs (for example CI), you can set `GIT_TERMINAL_PROMPT=0` to disable credential prompts and set `GIT_SSH_COMMAND` (for example `ssh -o BatchMode=yes -o ConnectTimeout=5`) to fail fast.-- Refs pin the package and skip package updates (`prime-agent update`, `prime-agent update --extensions`).+- Refs pin the package and skip `prime-agent package update`.- Cloned to `~/.pi/agent/git/<host>/<path>` (global) or `.pi/git/<host>/<path>` (project).- Runs `npm install` after clone or pull if `package.json` exists.**SSH examples:**```bash# git@host:path shorthand (requires git: prefix)-pi install git:[email protected]:user/repo+prime-agent package install git:[email protected]:user/repo# ssh:// protocol format-pi install ssh://[email protected]/user/repo+prime-agent package install ssh://[email protected]/user/repo# With version ref-pi install git:[email protected]:user/[email protected]+prime-agent package install git:[email protected]:user/[email protected]```### Local Paths@@ -161,7 +159,7 @@ If no `pi` manifest is present, pi auto-discovers resources from these directori## Dependencies-Third party runtime dependencies belong in `dependencies` in `package.json`. Dependencies that do not register extensions, skills, prompt templates, or themes also belong in `dependencies`. When pi installs a package from npm or git, it runs `npm install`, so those dependencies are installed automatically.+Third party runtime dependencies belong in `dependencies` in `package.json`. Dependencies that do not register extensions, skills, prompt templates, or themes also belong in `dependencies`. When Prime Agent installs a package from npm or git, it runs `npm install`, so those dependencies are installed automatically.Pi bundles core packages for extensions and skills. If you import any of these, list them in `peerDependencies` with a `"*"` range and do not bundle them: `@earendil-works/pi-ai`, `@earendil-works/pi-agent-core`, `@earendil-works/pi-coding-agent`, `@earendil-works/pi-tui`, `typebox`.@@ -212,7 +210,7 @@ Filter what a package loads using the object form in settings:## Enable and Disable Resources-Use `pi config` to enable or disable extensions, skills, prompt templates, and themes from installed packages and local directories. Works for both global (`~/.pi/agent`) and project (`.pi/`) scopes.+Use `prime-agent config` to enable or disable extensions, skills, prompt templates, and themes from installed packages and local directories. Works for both global (`~/.pi/agent`) and project (`.pi/`) scopes.## Scope and Deduplicationdiff --git a/packages/coding-agent/docs/usage.md b/packages/coding-agent/docs/usage.mdindex 27bb949e46..b7b577eb3b 100644--- a/packages/coding-agent/docs/usage.md+++ b/packages/coding-agent/docs/usage.md@@ -127,18 +127,26 @@ If you use pi for open source work and want to publish sessions for model, promppi [options] [@files...] [messages...]```-### Package Commands+### Shell Commands```bash-pi install <source> [-l] # Install package, -l for project-local-pi remove <source> [-l] # Remove package-pi uninstall <source> [-l] # Alias for remove-prime-agent update [source|self|prime-agent] # Update Prime Agent and packages; skips pinned packages-prime-agent update --extensions # Update packages only-prime-agent update --self # Update Prime Agent only-prime-agent update --extension <src> # Update one package-pi list # List installed packages-pi config # Enable/disable package resources+prime-agent agents+prime-agent list [--all]+prime-agent attach <agent>+prime-agent stop <agent>+prime-agent rename <agent> <name>+prime-agent send <agent> <message>+prime-agent schedule <list|add|cancel>+prime-agent status+prime-agent doctor [--fix]+prime-agent shutdown [--force]++prime-agent package install <source> [--local]+prime-agent package remove <source> [--local]+prime-agent package list+prime-agent package update [source]+prime-agent update [--force]+prime-agent config```See [Pi Packages](packages.md) for package sources and security notes.@@ -151,7 +159,6 @@ See [Pi Packages](packages.md) for package sources and security notes.| `-p`, `--print` | Print response and exit || `--mode json` | Output all events as JSON lines; see [JSON mode](json.md) || `--mode rpc` | RPC mode over stdin/stdout; see [RPC mode](rpc.md) |-| `--export <in> [out]` | Export a session to HTML |In print mode, pi also reads piped stdin and merges it into the initial prompt:@@ -168,7 +175,8 @@ cat README.md | pi -p "Summarize this text"| `--api-key <key>` | API key, overriding environment variables || `--thinking <level>` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh` || `--models <patterns>` | Comma-separated patterns for Ctrl+P cycling |-| `--list-models [search]` | List available models |++Use `prime-agent model list [search]` to list available models.### Session Options@@ -180,6 +188,8 @@ cat README.md | pi -p "Summarize this text"| `--session-dir <dir>` | Custom session storage directory || `--no-session` | Ephemeral mode; do not save |+Use `prime-agent session export <file> [output]` to export a session to HTML.+### Tool Options| Option | Description |diff --git a/packages/coding-agent/src/cli/args.ts b/packages/coding-agent/src/cli/args.tsindex 2f115d411f..05583c5d75 100644--- a/packages/coding-agent/src/cli/args.ts+++ b/packages/coding-agent/src/cli/args.ts@@ -6,6 +6,7 @@ import type { ThinkingLevel } from "@earendil-works/pi-agent-core";import chalk from "chalk";import { APP_NAME, CONFIG_DIR_NAME, ENV_AGENT_DIR, ENV_SESSION_DIR } from "../config.js";import type { ExtensionFlag } from "../core/extensions/types.js";+import { formatTopLevelHelp } from "./command-registry.js";export type Mode = "text" | "json" | "rpc" | "daemon";@@ -64,6 +65,8 @@ const VALID_THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhighconst REMOVED_BUILTIN_TOOL_NAMES = new Set(["read", "write", "grep", "find", "ls"]);const BUILTIN_TOOL_NAMES = ["ipython"];+export const INTERNAL_RUNTIME_COMMAND_MARKER = "\0prime-agent-runtime-command";+export function isValidThinkingLevel(level: string): level is ThinkingLevel {return VALID_THINKING_LEVELS.includes(level as ThinkingLevel);}@@ -77,8 +80,10 @@ export function parseArgs(args: string[]): Args {};let endOfOptions = false;+ const internalRuntimeCommand = args[0] === INTERNAL_RUNTIME_COMMAND_MARKER;+ const firstArgIndex = internalRuntimeCommand ? 1 : 0;- for (let i = 0; i < args.length; i++) {+ for (let i = firstArgIndex; i < args.length; i++) {const arg = args[i];// POSIX end-of-options: everything after a standalone "--" is a positional@@ -181,8 +186,23 @@ export function parseArgs(args: string[]): Args {result.messages.push(next);i++;}- } else if (arg === "--export" && i + 1 < args.length) {- result.export = args[++i];+ } else if (arg === "--export") {+ if (!internalRuntimeCommand) {+ result.diagnostics.push({+ type: "error",+ message: `--export was removed. Use "${APP_NAME} session export <file> [output]".`,+ });+ if (i + 1 < args.length && !args[i + 1].startsWith("-")) i++;+ } else if (i + 1 < args.length) {+ result.export = args[++i];+ } else {+ result.diagnostics.push({ type: "error", message: "--export requires a value" });+ }+ } else if (arg.startsWith("--export=")) {+ result.diagnostics.push({+ type: "error",+ message: `--export was removed. Use "${APP_NAME} session export <file> [output]".`,+ });} else if ((arg === "--extension" || arg === "-e") && i + 1 < args.length) {result.extensions = result.extensions ?? [];result.extensions.push(args[++i]);@@ -244,12 +264,23 @@ export function parseArgs(args: string[]): Args {result.autonomousTimeoutMs = parsePositiveInt(args[++i], "--autonomous-timeout-ms", result);}} else if (arg === "--list-models") {- // Check if next arg is a search pattern (not a flag or file arg)- if (i + 1 < args.length && !args[i + 1].startsWith("-") && !args[i + 1].startsWith("@")) {+ const hasSearch = i + 1 < args.length && !args[i + 1].startsWith("-") && !args[i + 1].startsWith("@");+ if (!internalRuntimeCommand) {+ result.diagnostics.push({+ type: "error",+ message: `--list-models was removed. Use "${APP_NAME} model list [search]".`,+ });+ if (hasSearch) i++;+ } else if (hasSearch) {result.listModels = args[++i];} else {result.listModels = true;}+ } else if (arg.startsWith("--list-models=")) {+ result.diagnostics.push({+ type: "error",+ message: `--list-models was removed. Use "${APP_NAME} model list [search]".`,+ });} else if (arg === "--verbose") {result.verbose = true;} else if (arg === "--offline") {@@ -291,21 +322,7 @@ export function printHelp(extensionFlags?: ExtensionFlag[]): void {}).join("\n")}\n`: "";- console.log(`${chalk.bold(APP_NAME)} - AI coding assistant with an ipython tool--${chalk.bold("Usage:")}- ${APP_NAME} [options] [@files...] [messages...] Open a new chat (press left to reach the agents view)--${chalk.bold("Commands:")}- ${APP_NAME} agents Open the agents view (alias: manage)- ${APP_NAME} install <source> [-l] Install extension source and add to settings- ${APP_NAME} remove <source> [-l] Remove extension source from settings- ${APP_NAME} uninstall <source> [-l] Alias for remove- ${APP_NAME} update [source|self|${APP_NAME}] Update ${APP_NAME} and installed extensions- ${APP_NAME} list List installed extensions from settings- ${APP_NAME} config Open TUI to enable/disable package resources- ${APP_NAME} daemon [name] Start daemon if needed, create a session, and attach- ${APP_NAME} <command> --help Show help for install/remove/uninstall/update/list/daemon+ console.log(`${formatTopLevelHelp()}${chalk.bold("Options:")}--provider <name> Provider name (default: google)@@ -314,8 +331,7 @@ ${chalk.bold("Options:")}--cwd <dir> Working directory for the session--system-prompt <text> System prompt (default: coding assistant prompt)--append-system-prompt <text> Append text or file contents to the system prompt (can be used multiple times)- --mode <mode> Output mode: text (default), json, rpc, or daemon- --daemon-socket <path> Socket path for daemon mode+ --mode <mode> Output mode: text (default), json, or rpc--print, -p Non-interactive mode: process prompt and exit--continue, -c Continue previous session--resume, -r [path|id] Resume specific session, or browse when omitted@@ -346,8 +362,6 @@ ${chalk.bold("Options:")}--autonomous-max-turns <n> Max assistant turns while autonomous mode is active (default: 12)--autonomous-max-tokens <n> Max tokens while autonomous mode is active (default: 80000)--autonomous-timeout-ms <n> Max autonomous wall-clock time in milliseconds (default: 1800000)- --export <file> Export session file to HTML and exit- --list-models [search] List available models (with optional fuzzy search)--verbose Force verbose startup (overrides quietStartup setting)--offline Disable startup network operations (same as PI_OFFLINE=1)--help, -h Show this help@@ -400,13 +414,13 @@ ${chalk.bold("Examples:")}${APP_NAME} --thinking high "Solve this complex problem"# Export a session file to HTML- ${APP_NAME} --export ~/${CONFIG_DIR_NAME}/sessions/session.jsonl- ${APP_NAME} --export session.jsonl output.html+ ${APP_NAME} session export ~/${CONFIG_DIR_NAME}/sessions/session.jsonl+ ${APP_NAME} session export session.jsonl output.html- # Start and control active sessions- ${APP_NAME} daemon --socket /tmp/prime-agent.sock --model openai/gpt-4o-mini scratch- ${APP_NAME} daemon --socket /tmp/prime-agent.sock list- ${APP_NAME} daemon --socket /tmp/prime-agent.sock prompt <session> "Say hello"+ # Work with agents+ ${APP_NAME} list+ ${APP_NAME} attach <agent>+ ${APP_NAME} send <agent> "Use this context"${chalk.bold("Environment Variables:")}ANTHROPIC_API_KEY - Anthropic Claude API keydiff --git a/packages/coding-agent/src/cli/command-registry.ts b/packages/coding-agent/src/cli/command-registry.tsnew file mode 100644index 0000000000..0ca01665c5--- /dev/null+++ b/packages/coding-agent/src/cli/command-registry.ts@@ -0,0 +1,260 @@+import { APP_NAME } from "../config.js";++export interface CommandSpec {+ path: readonly string[];+ usage: string;+ summary: string;+ description?: string;+ options?: readonly string[];+ examples?: readonly string[];+}++export const COMMAND_SPECS: readonly CommandSpec[] = [+ {+ path: ["help"],+ usage: "help [command]",+ summary: "Show command help",+ },+ {+ path: ["agents"],+ usage: "agents",+ summary: "Open the agents view",+ },+ {+ path: ["list"],+ usage: "list [--all] [--json]",+ summary: "List agents",+ options: ["-a, --all Include saved agents", "--json Print JSON"],+ },+ {+ path: ["attach"],+ usage: "attach <agent>",+ summary: "Attach the interactive UI to an agent",+ },+ {+ path: ["stop"],+ usage: "stop <agent> [--json]",+ summary: "Stop an agent",+ },+ {+ path: ["rename"],+ usage: "rename <agent> <name> [--json]",+ summary: "Rename an agent",+ },+ {+ path: ["send"],+ usage: "send [--from <agent>] [--steer|--follow-up] <agent> <message>",+ summary: "Send a message to an agent",+ options: [+ "--from <agent> Identify the sending agent",+ "--steer Deliver as steering when the agent is busy",+ "--follow-up Queue the message after the current turn",+ "--json Print JSON",+ ],+ },+ {+ path: ["schedule"],+ usage: "schedule <list|add|cancel>",+ summary: "Manage prompts that run later or on a recurring schedule",+ },+ {+ path: ["schedule", "list"],+ usage: "schedule list [--all] [agent] [--json]",+ summary: "List scheduled prompts",+ },+ {+ path: ["schedule", "add"],+ usage: "schedule add <agent> <schedule> -- <message>",+ summary: "Schedule a prompt",+ description: "The schedule may be a cron expression or a supported one-time schedule.",+ examples: [`schedule add worker "0 9 * * 1-5" -- "Check open work"`],+ },+ {+ path: ["schedule", "cancel"],+ usage: "schedule cancel <job-id>",+ summary: "Cancel a scheduled prompt",+ },+ {+ path: ["status"],+ usage: "status [--json]",+ summary: "Show background service status",+ },+ {+ path: ["doctor"],+ usage: "doctor [--fix] [--json]",+ summary: "Inspect and safely clean up background services",+ options: ["--fix Remove stale sockets and stop idle orphaned services", "--json Print JSON"],+ },+ {+ path: ["shutdown"],+ usage: "shutdown [--force] [--json]",+ summary: "Stop every agent and background service",+ description: "Without --force, an interactive confirmation is required. --force also kills unresponsive workers.",+ options: ["--force Skip confirmation and kill unresponsive processes", "--json Print JSON"],+ },+ {+ path: ["package"],+ usage: "package <install|remove|list|update>",+ summary: "Manage capability packages",+ description: "Packages can provide extensions, skills, prompts, and themes.",+ },+ {+ path: ["package", "install"],+ usage: "package install <source> [--local]",+ summary: "Install a capability package",+ options: ["--local Install into the current project instead of the user configuration"],+ },+ {+ path: ["package", "remove"],+ usage: "package remove <source> [--local]",+ summary: "Remove a capability package",+ options: ["--local Remove from the current project configuration"],+ },+ {+ path: ["package", "list"],+ usage: "package list",+ summary: "List installed capability packages",+ },+ {+ path: ["package", "update"],+ usage: "package update [source]",+ summary: "Update capability packages",+ },+ {+ path: ["update"],+ usage: "update [--force]",+ summary: "Update Prime Agent",+ },+ {+ path: ["model"],+ usage: "model list [search]",+ summary: "Inspect available models",+ },+ {+ path: ["model", "list"],+ usage: "model list [search]",+ summary: "List available models",+ },+ {+ path: ["session"],+ usage: "session export <file> [output]",+ summary: "Manage saved sessions",+ },+ {+ path: ["session", "export"],+ usage: "session export <file> [output]",+ summary: "Export a saved session to HTML",+ },+ {+ path: ["config"],+ usage: "config",+ summary: "Configure package resources",+ },+];++export const PUBLIC_COMMAND_NAMES = new Set(+ COMMAND_SPECS.filter((spec) => spec.path.length === 1).map((spec) => spec.path[0]!),+);++export const REMOVED_COMMAND_NAMES = new Set(["app", "daemon", "install", "manage", "remove", "uninstall"]);++export function getCommandSpec(path: readonly string[]): CommandSpec | undefined {+ return COMMAND_SPECS.find(+ (spec) => spec.path.length === path.length && spec.path.every((segment, index) => segment === path[index]),+ );+}++export function getChildCommandSpecs(path: readonly string[]): CommandSpec[] {+ return COMMAND_SPECS.filter(+ (spec) => spec.path.length === path.length + 1 && path.every((segment, index) => segment === spec.path[index]),+ );+}++export function isHelpCommandRequest(path: readonly string[]): boolean {+ if (path.length === 0 || getCommandSpec(path)) {+ return true;+ }+ if (REMOVED_COMMAND_NAMES.has(path[0]!)) {+ return true;+ }+ if (getCommandSpec(path.slice(0, 1))) {+ return true;+ }+ const parent = path.slice(0, -1);+ const candidates = getChildCommandSpecs(parent).map((spec) => spec.path.at(-1)!);+ return findCommandSuggestion(path.at(-1)!, candidates) !== undefined;+}++export function findCommandSuggestion(input: string, candidates: readonly string[]): string | undefined {+ let closest: { candidate: string; distance: number } | undefined;+ for (const candidate of candidates) {+ const distance = editDistance(input, candidate);+ if (!closest || distance < closest.distance) {+ closest = { candidate, distance };+ }+ }+ if (!closest || closest.distance > Math.max(2, Math.floor(input.length / 3))) {+ return undefined;+ }+ return closest.candidate;+}++export function formatTopLevelHelp(): string {+ const commands = COMMAND_SPECS.filter((spec) => spec.path.length === 1);+ const width = Math.max(...commands.map((spec) => spec.path[0]!.length));+ return `${APP_NAME} - AI coding assistant with an IPython tool++Usage:+ ${APP_NAME} [options] [@files...] [message...]+ ${APP_NAME} <command> [args...]++Commands:+${commands.map((spec) => ` ${spec.path[0]!.padEnd(width)} ${spec.summary}`).join("\n")}++Run "${APP_NAME} help <command>" for command details.`;+}++export function formatCommandHelp(path: readonly string[]): string | undefined {+ const spec = getCommandSpec(path);+ if (!spec) {+ return undefined;+ }+ const children = getChildCommandSpecs(path);+ const sections = [`Usage:\n ${APP_NAME} ${spec.usage}`, "", `${spec.summary}.`];+ if (spec.description) {+ sections.push("", spec.description);+ }+ if (children.length > 0) {+ const width = Math.max(...children.map((child) => child.path.at(-1)!.length));+ sections.push(+ "",+ "Commands:",+ ...children.map((child) => ` ${child.path.at(-1)!.padEnd(width)} ${child.summary}`),+ );+ }+ if (spec.options && spec.options.length > 0) {+ sections.push("", "Options:", ...spec.options.map((option) => ` ${option}`));+ }+ if (spec.examples && spec.examples.length > 0) {+ sections.push("", "Examples:", ...spec.examples.map((example) => ` ${APP_NAME} ${example}`));+ }+ return sections.join("\n");+}++function editDistance(left: string, right: string): number {+ const previous = Array.from({ length: right.length + 1 }, (_, index) => index);+ for (let leftIndex = 1; leftIndex <= left.length; leftIndex++) {+ let diagonal = previous[0]!;+ previous[0] = leftIndex;+ for (let rightIndex = 1; rightIndex <= right.length; rightIndex++) {+ const above = previous[rightIndex]!;+ previous[rightIndex] = Math.min(+ previous[rightIndex]! + 1,+ previous[rightIndex - 1]! + 1,+ diagonal + (left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1),+ );+ diagonal = above;+ }+ }+ return previous[right.length]!;+}diff --git a/packages/coding-agent/src/cli/daemon-command.ts b/packages/coding-agent/src/cli/daemon-command.tsindex 082899e568..357bddf50c 100644--- a/packages/coding-agent/src/cli/daemon-command.ts+++ b/packages/coding-agent/src/cli/daemon-command.ts@@ -4,18 +4,19 @@ import { setTimeout as delay } from "node:timers/promises";import type { AgentMessage } from "@earendil-works/pi-agent-core";import chalk from "chalk";import { spawn } from "child_process";-import { APP_NAME, expandTildePath } from "../config.js";+import { expandTildePath } from "../config.js";import type { AgentSessionEvent } from "../core/agent-session.js";import type { AgentSessionRuntimeConfig } from "../core/agent-session-config.js";import { type AgentCronJob, formatAgentCronJob } from "../core/cron-jobs.js";import { DaemonClient, type DaemonClientMessageListener } from "../modes/daemon/daemon-client.js";import type { DaemonOutbound, DaemonResponse } from "../modes/daemon/daemon-protocol.js";+import { matchesSessionIdSuffix } from "../modes/daemon/daemon-session-id.js";import type { SessionSummary } from "../modes/daemon/daemon-session-list.js";import { defaultDaemonSocketPath } from "../modes/daemon/daemon-socket.js";import { isLocalPath } from "../utils/paths.js";import { isValidThinkingLevel } from "./args.js";import { formatSessionListTable } from "./daemon-list-format.js";-import { runPs, runReap, runShutdownAll } from "./daemon-ps.js";+import { runPs, runReap } from "./daemon-ps.js";interface ParsedDaemonClientCommand {command: string;@@ -25,7 +26,6 @@ interface ParsedDaemonClientCommand {}const DAEMON_CLIENT_COMMANDS = new Set([- "help","start","ps","list",@@ -49,25 +49,6 @@ const DAEMON_CLIENT_COMMANDS = new Set(["shutdown",]);-export function normalizeDaemonStartArgs(args: string[]): string[] | undefined {- if (args[0] !== "daemon" || args[1] !== "start") {- return undefined;- }- if (!args.slice(2).some((arg) => arg === "--foreground" || arg === "--no-detach")) {- return undefined;- }-- const normalized = ["--mode", "daemon"];- for (let index = 2; index < args.length; index++) {- const arg = args[index];- if (arg === "--foreground" || arg === "--no-detach" || arg === "--background" || arg === "-d") {- continue;- }- normalized.push(arg === "--socket" ? "--daemon-socket" : arg);- }- return normalized;-}-export async function handleDaemonCommand(args: string[]): Promise<boolean> {if (args[0] !== "daemon") {return false;@@ -75,17 +56,13 @@ export async function handleDaemonCommand(args: string[]): Promise<boolean> {try {const parsed = parseDaemonClientCommand(args.slice(1));- if (parsed.command === "help") {- printDaemonHelp();- return true;- }-await runDaemonClientCommand(parsed);return true;} catch (error) {const message = error instanceof Error ? error.message : String(error);console.error(chalk.red(`Error: ${message}`));- process.exit(1);+ process.exitCode = 1;+ return true;}}@@ -168,11 +145,6 @@ async function runDaemonClientCommand(parsed: ParsedDaemonClientCommand): Promisreturn;}- if (parsed.command === "shutdown" && parsed.positionals.some((arg) => arg === "--all" || arg === "-a")) {- await runShutdownAll(parsed.json);- return;- }-const client = new DaemonClient(parsed.socketPath);await client.connect();@@ -654,11 +626,6 @@ function nextDefaultSessionName(sessions: SessionSummary[]): string {}async function runStart(parsed: ParsedDaemonClientCommand): Promise<void> {- if (parsed.positionals.length === 1 && parsed.positionals[0] === "help") {- printDaemonHelp();- return;- }-if (await canConnectToDaemon(parsed.socketPath, 250)) {console.log(`Daemon already running on ${parsed.socketPath}`);return;@@ -746,7 +713,7 @@ async function runList(client: DaemonClient, args: string[], json: boolean): Pro}if (sessions.length === 0) {- console.log(all ? "No sessions." : "No active sessions.");+ console.log(all ? "No agents." : "No active agents.");return;}@@ -810,7 +777,7 @@ async function runRename(client: DaemonClient, args: string[], json: boolean): Pconst activeSessionId = requireActiveSessionId(args);const name = args.slice(1).join(" ").trim();if (!name) {- throw new Error("Usage: daemon rename <session> <name>");+ throw new Error("Usage: prime-agent rename <agent> <name>");}const response = await client.request({ type: "rename", activeSessionId, name });const data = requireSuccess(response);@@ -934,14 +901,23 @@ function parseSendArgs(args: string[]): ParsedSendArgs {continue;}if (parseOptions && arg === "--steer") {+ if (deliveryMode !== undefined) {+ throw new Error("Only one send delivery mode may be specified: --steer or --follow-up");+ }deliveryMode = "steer";continue;}if (parseOptions && arg === "--follow-up") {+ if (deliveryMode !== undefined) {+ throw new Error("Only one send delivery mode may be specified: --steer or --follow-up");+ }deliveryMode = "follow_up";continue;}if (parseOptions && arg === "--auto") {+ if (deliveryMode !== undefined) {+ throw new Error("Only one send delivery mode may be specified: --steer or --follow-up");+ }deliveryMode = "auto";continue;}@@ -959,7 +935,7 @@ function parseSendArgs(args: string[]): ParsedSendArgs {continue;}if (parseOptions && arg.startsWith("--")) {- throw new Error(`Unknown option for daemon send: ${arg} (use -- before message text starting with --)`);+ throw new Error(`Unknown option for send: ${arg} (use -- before message text starting with --)`);}if (!targetActiveSessionId) {targetActiveSessionId = arg;@@ -970,13 +946,13 @@ function parseSendArgs(args: string[]): ParsedSendArgs {if (explicitMessage !== undefined && messageParts.length > 0) {throw new Error(- "Usage: daemon send [--from <session>] [--steer|--follow-up] <target-session> [--message <message>|<message>]",+ "Usage: prime-agent send [--from <agent>] [--steer|--follow-up] <agent> [--message <message>|<message>]",);}const message = (explicitMessage ?? messageParts.join(" ")).trim();if (!targetActiveSessionId || !message) {throw new Error(- "Usage: daemon send [--from <session>] [--steer|--follow-up] <target-session> [--message <message>|<message>]",+ "Usage: prime-agent send [--from <agent>] [--steer|--follow-up] <agent> [--message <message>|<message>]",);}return {@@ -1006,7 +982,8 @@ async function runCron(client: DaemonClient, args: string[], json: boolean): Proconst subcommand = args[0] ?? "list";if (subcommand === "list") {const includeInactive = args.includes("--all") || args.includes("-a");- const activeSessionId = args.find((arg) => !arg.startsWith("-") && arg !== "list");+ const selector = args.find((arg) => !arg.startsWith("-") && arg !== "list");+ const activeSessionId = selector ? await resolveLiveSessionSelector(client, selector) : undefined;const response = await client.request({ type: "cron_list", activeSessionId, includeInactive });const data = requireSuccess(response);if (json) {@@ -1019,7 +996,7 @@ async function runCron(client: DaemonClient, args: string[], json: boolean): Proreturn;}if (jobs.length === 0) {- console.log("No cron jobs.");+ console.log("No scheduled prompts.");return;}for (const job of jobs) {@@ -1031,11 +1008,11 @@ async function runCron(client: DaemonClient, args: string[], json: boolean): Proif (subcommand === "add" || subcommand === "schedule") {const separator = args.indexOf("--");if (separator < 0) {- throw new Error("Usage: daemon cron add <session> <schedule> -- <message>");+ throw new Error("Usage: prime-agent schedule add <agent> <schedule> -- <message>");}const activeSessionId = args[1];if (!activeSessionId) {- throw new Error("Usage: daemon cron add <session> <schedule> -- <message>");+ throw new Error("Usage: prime-agent schedule add <agent> <schedule> -- <message>");}const schedule = args.slice(2, separator).join(" ").trim();const message = args@@ -1043,7 +1020,7 @@ async function runCron(client: DaemonClient, args: string[], json: boolean): Pro.join(" ").trim();if (!schedule || !message) {- throw new Error("Usage: daemon cron add <session> <schedule> -- <message>");+ throw new Error("Usage: prime-agent schedule add <agent> <schedule> -- <message>");}const response = await client.request({ type: "cron_add", activeSessionId, schedule, prompt: message });const data = requireSuccess(response);@@ -1052,14 +1029,14 @@ async function runCron(client: DaemonClient, args: string[], json: boolean): Proreturn;}const job = getCronJob(data);- console.log(job ? `Scheduled ${job.id} next=${job.nextRunAt ?? "-"}` : "Scheduled cron job.");+ console.log(job ? `Scheduled ${job.id} next=${job.nextRunAt ?? "-"}` : "Scheduled prompt.");return;}if (subcommand === "cancel" || subcommand === "delete" || subcommand === "remove") {const jobId = args[1];if (!jobId) {- throw new Error("Usage: daemon cron cancel <job-id>");+ throw new Error("Usage: prime-agent schedule cancel <job-id>");}const response = await client.request({ type: "cron_cancel", jobId });const data = requireSuccess(response);@@ -1072,7 +1049,30 @@ async function runCron(client: DaemonClient, args: string[], json: boolean): Proreturn;}- throw new Error(`Unknown cron command: ${subcommand}`);+ throw new Error(`Unknown schedule command: ${subcommand}`);+}++async function resolveLiveSessionSelector(client: DaemonClient, selector: string): Promise<string> {+ const sessions = (await getLiveSessions(client)).filter(+ (session): session is SessionSummary & { activeSessionId: string } => typeof session.activeSessionId === "string",+ );+ const exact = sessions.filter(+ (session) =>+ session.activeSessionId === selector || session.sessionId === selector || session.sessionName === selector,+ );+ const suffix = sessions.filter(+ (session) =>+ matchesSessionIdSuffix(session.activeSessionId, selector) ||+ matchesSessionIdSuffix(session.sessionId, selector),+ );+ const matches = exact.length > 0 ? exact : suffix;+ if (matches.length === 1) {+ return matches[0]!.activeSessionId;+ }+ if (matches.length > 1) {+ throw new Error(`Ambiguous active session "${selector}"`);+ }+ throw new Error(`Unknown active session: ${selector}`);}async function printResponseData(@@ -1092,7 +1092,7 @@ async function printResponseData(function requireActiveSessionId(args: string[]): string {const activeSessionId = args[0];if (!activeSessionId) {- throw new Error("Missing active session id");+ throw new Error("Missing agent id or name");}return activeSessionId;}@@ -1658,72 +1658,3 @@ function isAgentMessageReceipt(typeof (target as { activeSessionId?: unknown }).activeSessionId === "string");}--function printDaemonHelp(): void {- console.log(`${chalk.bold("Usage:")}- ${APP_NAME} daemon [options] [session name]- ${APP_NAME} daemon --name <name> [agent options]- ${APP_NAME} daemon [--socket <path>] <command> [args...]- ${APP_NAME} daemon help--${chalk.bold("Commands:")}- help Show daemon help- start Start the background daemon and return- ps [--reap [--force]] List all daemons on this machine; --reap stops idle/orphaned ones- list [-a|--all] List active sessions; include inactive sessions with -a- create [name] Create a new active session- attach <session> Attach an interactive terminal to a live session- detach [session] Detach this client from one session or all sessions- prompt <session> <message> Send a prompt, stream events, and exit when idle- send [options] <target> <msg> Send an agent-to-agent message to another live session- agent-messages <cmd> Safety controls: status, pause, resume, clear <session>- steer <session> <message> Queue a steering message- follow-up <session> <message> Queue a follow-up message- rename <session> <name> Rename a live session- kill <session> Kill a live session- state <session> Print session state as JSON- messages <session> Print messages as JSON- stats <session> Print session stats as JSON- commands <session> Print available commands as JSON- cron list [-a|--all] [session] List scheduled cron jobs- cron add <session> <schedule> -- <message>- Schedule a prompt for a session- cron cancel <job-id> Cancel a scheduled cron job- retry <session> Retry a root worker marked failed- restart Restart only the supervisor and adopt existing workers- shutdown [--force|--all] Stop workers and the daemon; --force kills unresponsive workers--${chalk.bold("Options:")}- --socket <path> Socket path (default: ${defaultDaemonSocketPath()})- --name <name> Name for the new session created by bare daemon- --cwd <dir> Working directory for the created session- --resume <selector> Resume a saved session file or partial UUID- --foreground, --no-detach Keep daemon attached to this terminal for debugging- --json Print raw JSON for commands with formatted output; attach streams raw protocol JSON- send options: --from <session>, --steer, --follow-up, --message <message>- agent-messages clear only clears one explicitly named session- Agent options such as --model, --provider, --tools, and --thinking apply to created sessions.--${chalk.bold("Examples:")}- ${APP_NAME} daemon --socket /tmp/prime-agent.sock --model openai/gpt-4o-mini- ${APP_NAME} daemon --socket /tmp/prime-agent.sock create scratch --model openai/gpt-4o-mini- ${APP_NAME} daemon --socket /tmp/prime-agent.sock create audit --model anthropic/claude-sonnet-4-5 --cwd ../other-repo- ${APP_NAME} daemon --socket /tmp/prime-agent.sock --name scratch --model openai/gpt-4o-mini- ${APP_NAME} daemon --socket /tmp/prime-agent.sock scratch- ${APP_NAME} daemon start --socket /tmp/prime-agent.sock --model openai/gpt-4o-mini- ${APP_NAME} daemon start --foreground --socket /tmp/prime-agent.sock --offline- ${APP_NAME} daemon ps- ${APP_NAME} daemon ps --reap- ${APP_NAME} daemon --socket /tmp/prime-agent.sock list- ${APP_NAME} daemon --socket /tmp/prime-agent.sock list -a- ${APP_NAME} daemon --socket /tmp/prime-agent.sock create scratch- ${APP_NAME} daemon --socket /tmp/prime-agent.sock create --resume <session>- ${APP_NAME} daemon --socket /tmp/prime-agent.sock cron add <session> "*/30 * * * *" -- "Check progress"- ${APP_NAME} daemon --socket /tmp/prime-agent.sock cron list- ${APP_NAME} daemon --socket /tmp/prime-agent.sock prompt <session> "Say hello"- ${APP_NAME} daemon --socket /tmp/prime-agent.sock send --from planner worker --message "Use this context..."- ${APP_NAME} daemon --socket /tmp/prime-agent.sock attach <session>- ${APP_NAME} daemon --socket /tmp/prime-agent.sock shutdown- ${APP_NAME} daemon shutdown --all-`);-}diff --git a/packages/coding-agent/src/cli/daemon-launch.ts b/packages/coding-agent/src/cli/daemon-launch.tsindex 6f605fcde2..6df80083d0 100644--- a/packages/coding-agent/src/cli/daemon-launch.ts+++ b/packages/coding-agent/src/cli/daemon-launch.ts@@ -15,6 +15,7 @@ import { DaemonClient } from "../modes/daemon/daemon-client.js";import { DAEMON_PROTOCOL_VERSION } from "../modes/daemon/daemon-protocol.js";import type { SessionSummary } from "../modes/daemon/daemon-session-list.js";import { defaultDaemonSocketPath } from "../modes/daemon/daemon-socket.js";+import { isHelpCommandRequest, PUBLIC_COMMAND_NAMES, REMOVED_COMMAND_NAMES } from "./command-registry.js";export function isDaemonSessionSummary(value: unknown): value is SessionSummary {if (!value || typeof value !== "object") {@@ -104,8 +105,8 @@ export async function listActiveDaemonSessionSummaries(client: DaemonClient): Prexport class StaleDaemonError extends Error {constructor(readonly socketPath: string) {super(- `A background daemon from a different prime-agent version is running on ${socketPath} and can't be driven by ` +- `this version. Run "prime-agent daemon shutdown" to stop it, then retry.`,+ `A background service from a different Prime Agent version is running on ${socketPath} and can't be driven by ` ++ `this version. Run "prime-agent shutdown" to stop it, then retry.`,);this.name = "StaleDaemonError";}@@ -297,8 +298,6 @@ const EARLY_LAUNCH_EXCLUDED_FLAGS = new Set(["--export",]);-const EARLY_LAUNCH_EXCLUDED_COMMANDS = new Set(["daemon", "install", "remove", "update", "list", "config"]);-/** Conservative pre-parse of argv: true only when startup clearly heads into daemon-backed interactive mode. */export function shouldStartInteractiveDaemonEarly(args: readonly string[],@@ -308,8 +307,16 @@ export function shouldStartInteractiveDaemonEarly(if (startupBenchmark || !stdinIsTTY) {return false;}- const firstPositional = args.find((arg) => arg.length > 0 && !arg.startsWith("-"));- if (firstPositional && EARLY_LAUNCH_EXCLUDED_COMMANDS.has(firstPositional)) {+ const firstPositionalIndex = args.findIndex((arg) => arg.length > 0 && !arg.startsWith("-"));+ const firstPositional = args[firstPositionalIndex];+ const isHelpCommand = firstPositional === "help" && isHelpCommandRequest(args.slice(firstPositionalIndex + 1));+ if (+ firstPositional &&+ (REMOVED_COMMAND_NAMES.has(firstPositional) ||+ (PUBLIC_COMMAND_NAMES.has(firstPositional) &&+ firstPositional !== "agents" &&+ (firstPositional !== "help" || isHelpCommand)))+ ) {return false;}return !args.some((arg) => EARLY_LAUNCH_EXCLUDED_FLAGS.has(arg));diff --git a/packages/coding-agent/src/cli/daemon-ps-format.ts b/packages/coding-agent/src/cli/daemon-ps-format.tsindex b50b3decea..a2277841d6 100644--- a/packages/coding-agent/src/cli/daemon-ps-format.ts+++ b/packages/coding-agent/src/cli/daemon-ps-format.ts@@ -20,7 +20,9 @@ export function formatDaemonListTable(daemons: readonly DaemonInfo[]): string {uptime: formatUptime(daemon.uptimeSeconds),}));const table = formatTable(["socket", "pid", "version", "status", "sessions", "uptime"], rows, formatDaemonCell);- return daemons.some((daemon) => daemon.isDefault) ? `${table}\n\n${chalk.dim("* default daemon")}` : table;+ return daemons.some((daemon) => daemon.isDefault)+ ? `${table}\n\n${chalk.dim("* default background service")}`+ : table;}function formatDaemonCell(_row: DaemonRow, column: keyof DaemonRow, value: string): string {diff --git a/packages/coding-agent/src/cli/daemon-ps.ts b/packages/coding-agent/src/cli/daemon-ps.tsindex 1b25850aab..1d3dd86193 100644--- a/packages/coding-agent/src/cli/daemon-ps.ts+++ b/packages/coding-agent/src/cli/daemon-ps.ts@@ -1,14 +1,18 @@import { spawnSync } from "node:child_process";-import { existsSync, lstatSync, readdirSync, unlinkSync } from "node:fs";+import { existsSync, lstatSync, readdirSync, readFileSync, rmSync, unlinkSync } from "node:fs";import { basename, dirname, join, resolve } from "node:path";import chalk from "chalk";-import { APP_NAME, VERSION } from "../config.js";+import { APP_NAME, getAgentDir, VERSION } from "../config.js";+import { isOrphanProcessIdentityCurrent, readActiveOrphanProcesses } from "../core/orphan-process-journal.js";import { getProcessStartId } from "../core/session-lease.js";import { DaemonClient } from "../modes/daemon/daemon-client.js";import { DAEMON_PROTOCOL_VERSION } from "../modes/daemon/daemon-protocol.js";import { defaultDaemonSocketDir, defaultDaemonSocketPath } from "../modes/daemon/daemon-socket.js";import { acquireDaemonShutdownAdmission } from "../modes/daemon/daemon-supervisor-ownership.js";+import type { DaemonWorkerDescriptor } from "../modes/daemon/daemon-worker-protocol.js";+import { signalProcessGroupOrProcess } from "../utils/child-process.js";import { formatDaemonListTable } from "./daemon-ps-format.js";+import { promptYesNo } from "./daemon-stop-confirm.js";/*** `daemon ps` discovers every prime-agent daemon on the machine, not just the@@ -45,6 +49,7 @@ export interface DaemonInfo {sessionCount?: number;status: DaemonStatus;isDefault: boolean;+ hasTrackedWorkers?: boolean;}const STATUS_ORDER: Record<DaemonStatus, number> = {@@ -239,17 +244,32 @@ function classifyReachable(probe: ProbeResult): DaemonStatus {export async function discoverDaemons(): Promise<DaemonInfo[]> {const processBySocket = new Map<string, DiscoveredDaemonProcess>();for (const daemon of scanListeningDaemons()) {+ if (isWorkerSocketPath(daemon.socketPath)) {+ continue;+ }processBySocket.set(daemon.socketPath, daemon);}- const sockets = new Set<string>([...processBySocket.keys(), ...scanSocketDir()]);+ const workerSockets = new Set(+ findAllTrackedWorkers().map((worker) => normalizeSocketPath(worker.descriptor.supervisorSocketPath)),+ );+ const sockets = new Set<string>([+ ...processBySocket.keys(),+ ...scanSocketDir().filter((socketPath) => !isWorkerSocketPath(socketPath)),+ ...workerSockets,+ ]);const defaultSocket = normalizeSocketPath(defaultDaemonSocketPath());const infos = await Promise.all([...sockets].map(async (socketPath): Promise<DaemonInfo> => {const proc = processBySocket.get(socketPath);const probe = await probeDaemon(socketPath);- const status: DaemonStatus = probe.reachable ? classifyReachable(probe) : proc ? "unreachable" : "orphan-file";+ const hasTrackedWorkers = workerSockets.has(socketPath);+ const status: DaemonStatus = probe.reachable+ ? classifyReachable(probe)+ : proc || hasTrackedWorkers+ ? "unreachable"+ : "orphan-file";return {socketPath,pid: proc?.pid,@@ -259,6 +279,7 @@ export async function discoverDaemons(): Promise<DaemonInfo[]> {sessionCount: probe.sessionCount,status,isDefault: socketPath === defaultSocket,+ ...(hasTrackedWorkers ? { hasTrackedWorkers: true } : {}),};}),);@@ -283,7 +304,7 @@ export async function runPs(json: boolean): Promise<void> {return;}if (daemons.length === 0) {- console.log("No daemons found.");+ console.log("No background services found.");return;}console.log(formatDaemonListTable(daemons));@@ -326,11 +347,11 @@ export function planReap(daemons: readonly DaemonInfo[], force: boolean): ReapAcreturn { kind: "remove-file", daemon };}if (daemon.isDefault) {- return { kind: "skip", daemon, reason: "default daemon" };+ return { kind: "skip", daemon, reason: "default background service" };}if (daemon.status === "unreachable") {if (!force || daemon.pid === undefined) {- return { kind: "skip", daemon, reason: "unreachable; pass --force to kill" };+ return { kind: "skip", daemon, reason: 'unreachable; use "prime-agent shutdown --force" to stop it' };}if ((pidCounts.get(daemon.pid) ?? 0) > 1) {return {@@ -348,13 +369,18 @@ export function planReap(daemons: readonly DaemonInfo[], force: boolean): ReapAc});}-export function planShutdownAll(daemons: readonly DaemonInfo[]): ReapAction[] {+export function planShutdownAll(daemons: readonly DaemonInfo[], force: boolean): ReapAction[] {return daemons.map((daemon): ReapAction => {if (daemon.status === "orphan-file") {return { kind: "remove-file", daemon };}if (daemon.status === "unreachable") {- return daemon.pid === undefined ? { kind: "remove-file", daemon } : { kind: "kill", daemon };+ if (daemon.pid === undefined) {+ return force || !daemon.hasTrackedWorkers+ ? { kind: "remove-file", daemon }+ : { kind: "skip", daemon, reason: "has unreachable workers; use --force to kill" };+ }+ return force ? { kind: "kill", daemon } : { kind: "skip", daemon, reason: "unreachable; use --force to kill" };}return { kind: "shutdown", daemon };});@@ -367,25 +393,79 @@ const SHUTDOWN_ALL_ACTION_ORDER: Record<ReapAction["kind"], number> = {skip: 3,};-export async function runShutdownAll(json: boolean): Promise<void> {+export type ShutdownConfirmationPlan = "none" | "prompt" | "json-error" | "tty-error";++export function planShutdownConfirmation(+ daemonCount: number,+ json: boolean,+ force: boolean,+ stdinIsTTY: boolean | undefined,+): ShutdownConfirmationPlan {+ if (daemonCount === 0 || force) return "none";+ if (json) return "json-error";+ return stdinIsTTY ? "prompt" : "tty-error";+}++export async function runShutdownAll(json: boolean, force: boolean): Promise<void> {+ const daemons = await discoverDaemons();+ switch (planShutdownConfirmation(daemons.length, json, force, process.stdin.isTTY)) {+ case "json-error":+ process.exitCode = 1;+ console.log(+ JSON.stringify(+ {+ stopped: [],+ failed: daemons.map(({ socketPath }) => ({+ socketPath,+ reason: 'confirmation required; use "prime-agent shutdown --force --json"',+ })),+ },+ null,+ 2,+ ),+ );+ return;+ case "tty-error":+ throw new Error(+ 'Shutdown requires confirmation in an interactive terminal. Use "prime-agent shutdown --force".',+ );+ case "prompt": {+ const confirmed = await promptYesNo(+ "Stop every agent and background service? Active work will be interrupted.",+ );+ if (!confirmed) {+ console.log(chalk.dim("Shutdown cancelled."));+ return;+ }+ break;+ }+ case "none":+ break;+ }const admission = await acquireDaemonShutdownAdmission();try {- await runShutdownAllConverging(json, () => admission.assertOrRenew());+ await runShutdownAllConverging(json, force, () => admission.assertOrRenew());} finally {await admission.release();}}-async function runShutdownAllConverging(json: boolean, assertAdmission: () => Promise<void>): Promise<void> {+async function runShutdownAllConverging(+ json: boolean,+ force: boolean,+ assertAdmission: () => Promise<void>,+): Promise<void> {const stopped: Array<{ socketPath: string; action: string }> = [];const failed: Array<{ socketPath: string; reason: string }> = [];const handledPids = new Set<number>();const reportedFailures = new Set<string>();- await stopHiddenSupervisors(stopped, failed, handledPids, reportedFailures, assertAdmission);+ if (force) {+ await stopHiddenSupervisors(stopped, failed, handledPids, reportedFailures, assertAdmission);+ }const daemons = (await discoverDaemons()).filter((daemon) => !isWorkerSocketPath(daemon.socketPath));- const actions = [...planShutdownAll(daemons)].sort(+ const actions = [...planShutdownAll(daemons, force)].sort((left, right) => SHUTDOWN_ALL_ACTION_ORDER[left.kind] - SHUTDOWN_ALL_ACTION_ORDER[right.kind],);@@ -394,14 +474,22 @@ async function runShutdownAllConverging(json: boolean, assertAdmission: () => Prif (pid !== undefined && handledPids.has(pid)) {await assertAdmission();removeSocketFile(socketPath);- stopped.push({ socketPath, action: `already stopped (pid ${pid})` });+ stopped.push({ socketPath, action: `background service already stopped (pid ${pid})` });+ if (force) {+ failed.push(+ ...(await forceStopTrackedWorkers(socketPath, assertAdmission)).map((reason) => ({+ socketPath,+ reason,+ })),+ );+ }continue;}switch (action.kind) {case "remove-file": {if ((await probeDaemon(socketPath)).reachable) {apply(- await stopDaemonForcefully(socketPath, pid, handledPids, assertAdmission),+ await stopBackgroundService(socketPath, pid, handledPids, force, assertAdmission),socketPath,stopped,failed,@@ -419,7 +507,7 @@ async function runShutdownAllConverging(json: boolean, assertAdmission: () => Prcase "kill": {if ((await probeDaemon(socketPath)).reachable) {apply(- await stopDaemonForcefully(socketPath, pid, handledPids, assertAdmission),+ await stopBackgroundService(socketPath, pid, handledPids, force, assertAdmission),socketPath,stopped,failed,@@ -430,35 +518,46 @@ async function runShutdownAllConverging(json: boolean, assertAdmission: () => PrhandledPids.add(pid!);await assertAdmission();removeSocketFile(socketPath);- stopped.push({ socketPath, action: `killed unreachable daemon (pid ${pid})` });+ stopped.push({ socketPath, action: `killed unreachable background service (pid ${pid})` });} else {await assertAdmission();removeSocketFile(socketPath);- stopped.push({ socketPath, action: "daemon already stopped" });+ stopped.push({ socketPath, action: "background service already stopped" });}break;}case "shutdown":apply(- await stopDaemonForcefully(socketPath, pid, handledPids, assertAdmission),+ await stopBackgroundService(socketPath, pid, handledPids, force, assertAdmission),socketPath,stopped,failed,);break;case "skip":+ failed.push({ socketPath, reason: action.reason });break;}+ if (force && action.kind !== "skip") {+ failed.push(+ ...(await forceStopTrackedWorkers(socketPath, assertAdmission)).map((reason) => ({ socketPath, reason })),+ );+ }}- await terminateVerifiedResiduals(stopped, failed, handledPids, reportedFailures, assertAdmission);+ if (force) {+ await terminateVerifiedResiduals(stopped, failed, handledPids, reportedFailures, assertAdmission);+ }if (json) {+ if (failed.length > 0) {+ process.exitCode = 1;+ }console.log(JSON.stringify({ stopped, failed }, null, 2));return;}if (stopped.length === 0 && failed.length === 0) {- console.log("No daemons found.");+ console.log("No background services found.");return;}for (const entry of stopped) {@@ -467,6 +566,9 @@ async function runShutdownAllConverging(json: boolean, assertAdmission: () => Prfor (const entry of failed) {console.log(chalk.red(`failed ${entry.socketPath}: ${entry.reason}`));}+ if (failed.length > 0) {+ process.exitCode = 1;+ }}async function stopHiddenSupervisors(@@ -634,7 +736,7 @@ function recordShutdownFailure(failed.push({ socketPath, reason });}-function isWorkerSocketPath(socketPath: string): boolean {+export function isWorkerSocketPath(socketPath: string): boolean {return (process.platform !== "win32" &&resolve(dirname(socketPath)) === resolve(defaultDaemonSocketDir()) &&@@ -643,33 +745,190 @@ function isWorkerSocketPath(socketPath: string): boolean {);}-async function stopDaemonForcefully(+async function stopBackgroundService(socketPath: string,pid: number | undefined,handledPids: Set<number>,+ force: boolean,assertAdmission: () => Promise<void>,): Promise<ReapOutcome> {await assertAdmission();- if (await shutdownDaemon(socketPath)) {+ if (await shutdownDaemon(socketPath, force)) {if (pid !== undefined) {handledPids.add(pid);}- return { reaped: `stopped daemon${pid ? ` (pid ${pid})` : ""}` };+ return { reaped: `stopped background service${pid ? ` (pid ${pid})` : ""}` };}if (!(await canConnectToSocket(socketPath, 250))) {await assertAdmission();removeSocketFile(socketPath);- return { reaped: "daemon already stopped" };+ return { reaped: "background service already stopped" };}if (pid === undefined) {return { skipped: "still listening but no pid to kill" };}+ if (!force) {+ return { skipped: "did not stop gracefully; retry with --force" };+ }await assertAdmission();await forceKillDaemon(pid);handledPids.add(pid);await assertAdmission();removeSocketFile(socketPath);- return { reaped: `force-killed unresponsive daemon (pid ${pid})` };+ return { reaped: `force-killed unresponsive background service (pid ${pid})` };+}++interface TrackedWorker {+ descriptor: DaemonWorkerDescriptor;+ descriptorPath: string;+}++async function forceStopTrackedWorkers(+ supervisorSocketPath: string,+ assertAdmission: () => Promise<void>,+): Promise<string[]> {+ const failures: string[] = [];+ for (const worker of findTrackedWorkers(supervisorSocketPath)) {+ const { descriptor } = worker;+ let cleanupWorkerRecords = await stopTrackedProcess(descriptor.pid, descriptor.processStartId, assertAdmission);+ if (!cleanupWorkerRecords) {+ failures.push(`could not safely stop worker ${descriptor.workerId} (pid ${descriptor.pid})`);+ }+ if (descriptor.orphanProcessJournalPath) {+ let orphans: ReturnType<typeof readActiveOrphanProcesses> = [];+ try {+ orphans = readActiveOrphanProcesses(descriptor.orphanProcessJournalPath, descriptor.pid);+ } catch (error) {+ failures.push(`could not read child process records for worker ${descriptor.workerId}: ${String(error)}`);+ }+ for (const orphan of orphans) {+ if (!isOrphanProcessIdentityCurrent(orphan)) {+ continue;+ }+ if (!(await stopTrackedProcess(orphan.pid, orphan.processStartId, assertAdmission))) {+ cleanupWorkerRecords = false;+ failures.push(`could not stop child process ${orphan.pid} for worker ${descriptor.workerId}`);+ }+ }+ }+ if (cleanupWorkerRecords) {+ try {+ removeSocketFile(descriptor.socketPath);+ rmSync(worker.descriptorPath, { force: true });+ rmSync(descriptor.recoveryJournalPath, { force: true });+ if (descriptor.orphanProcessJournalPath) {+ rmSync(descriptor.orphanProcessJournalPath, { force: true });+ }+ } catch (error) {+ failures.push(`could not clean up worker ${descriptor.workerId}: ${String(error)}`);+ }+ }+ }+ return failures;+}++function findTrackedWorkers(supervisorSocketPath: string): TrackedWorker[] {+ return findAllTrackedWorkers().filter(+ (worker) =>+ normalizeSocketPath(worker.descriptor.supervisorSocketPath) === normalizeSocketPath(supervisorSocketPath),+ );+}++function findAllTrackedWorkers(): TrackedWorker[] {+ const root = join(getAgentDir(), "daemon-workers");+ if (!existsSync(root)) {+ return [];+ }+ const workers: TrackedWorker[] = [];+ let directoryNames: string[];+ try {+ directoryNames = readdirSync(root);+ } catch {+ return [];+ }+ for (const directoryName of directoryNames) {+ const directory = join(root, directoryName);+ try {+ if (!lstatSync(directory).isDirectory()) {+ continue;+ }+ } catch {+ continue;+ }+ let fileNames: string[];+ try {+ fileNames = readdirSync(directory);+ } catch {+ continue;+ }+ for (const fileName of fileNames) {+ if (!fileName.endsWith(".json")) {+ continue;+ }+ const descriptorPath = join(directory, fileName);+ try {+ const value: unknown = JSON.parse(readFileSync(descriptorPath, "utf8"));+ if (isTrackedWorkerDescriptor(value)) {+ workers.push({ descriptor: value, descriptorPath });+ }+ } catch {+ // Invalid or concurrently removed descriptors are not safe shutdown targets.+ }+ }+ }+ return workers;+}++function isTrackedWorkerDescriptor(value: unknown): value is DaemonWorkerDescriptor {+ if (!value || typeof value !== "object") {+ return false;+ }+ const descriptor = value as Partial<DaemonWorkerDescriptor>;+ return (+ descriptor.version === 1 &&+ typeof descriptor.supervisorSocketPath === "string" &&+ typeof descriptor.workerId === "string" &&+ Number.isInteger(descriptor.pid) &&+ (descriptor.pid ?? 0) > 0 &&+ (descriptor.processStartId === undefined || typeof descriptor.processStartId === "string") &&+ typeof descriptor.socketPath === "string" &&+ typeof descriptor.recoveryJournalPath === "string"+ );+}++async function stopTrackedProcess(+ pid: number,+ expectedStartId: string | undefined,+ assertAdmission: () => Promise<void>,+): Promise<boolean> {+ if (!isProcessAlive(pid)) {+ return true;+ }+ if (!expectedStartId || getProcessStartId(pid) !== expectedStartId) {+ return false;+ }+ await assertAdmission();+ if (getProcessStartId(pid) !== expectedStartId) {+ return false;+ }+ signalProcessGroupOrProcess(pid, "SIGTERM");+ let deadline = Date.now() + 500;+ while (isProcessAlive(pid) && Date.now() < deadline) {+ await delay(25);+ }+ if (!isProcessAlive(pid)) {+ return true;+ }+ await assertAdmission();+ if (getProcessStartId(pid) !== expectedStartId) {+ return false;+ }+ signalProcessGroupOrProcess(pid, "SIGKILL");+ deadline = Date.now() + 1000;+ while (isProcessAlive(pid) && Date.now() < deadline) {+ await delay(25);+ }+ return !isProcessAlive(pid);}export async function runReap(json: boolean, force: boolean): Promise<void> {@@ -722,7 +981,7 @@ export async function runReap(json: boolean, force: boolean): Promise<void> {return;}if (reaped.length === 0 && skipped.length === 0) {- console.log("No daemons found.");+ console.log("No background services found.");return;}for (const entry of reaped) {@@ -761,8 +1020,8 @@ async function reapReachableDaemon(socketPath: string, pid: number | undefined):if (probe.sessionCount !== 0) {return { skipped: `now has ${probe.sessionCount ?? "unknown"} session(s)` };}- return (await shutdownDaemon(socketPath))- ? { reaped: `stopped idle daemon${pid ? ` (pid ${pid})` : ""}` }+ return (await shutdownDaemon(socketPath, false))+ ? { reaped: `stopped idle background service${pid ? ` (pid ${pid})` : ""}` }: { skipped: "shutdown request failed" };}@@ -805,8 +1064,8 @@ function isProcessAlive(pid: number): boolean {try {process.kill(pid, 0);return true;- } catch {- return false;+ } catch (error) {+ return (error as NodeJS.ErrnoException).code === "EPERM";}}@@ -831,7 +1090,7 @@ async function canConnectToSocket(socketPath: string, timeoutMs: number): Promis* shutdown ack alone is not proof, so success is reported only once the socket* stops accepting connections.*/-async function shutdownDaemon(socketPath: string): Promise<boolean> {+async function shutdownDaemon(socketPath: string, force: boolean): Promise<boolean> {const client = new DaemonClient(socketPath);try {await client.connect(1000);@@ -840,7 +1099,7 @@ async function shutdownDaemon(socketPath: string): Promise<boolean> {return false;}try {- await client.request({ type: "shutdown" }, 1500);+ await client.request({ type: "shutdown", force }, 1500);} catch {// The daemon may still stop; the connectivity check below is the source of truth.} finally {diff --git a/packages/coding-agent/src/cli/owned-session-worker.ts b/packages/coding-agent/src/cli/owned-session-worker.tsindex b35a5505d6..c7447862e5 100644--- a/packages/coding-agent/src/cli/owned-session-worker.ts+++ b/packages/coding-agent/src/cli/owned-session-worker.ts@@ -13,6 +13,7 @@ import {} from "../core/orphan-process-journal.js";import { SESSION_LEASE_OWNER_ID_ENV, SESSION_LEASES_ENABLED_ENV } from "../core/session-lease.js";import { attachJsonlLineReader, serializeJsonLine } from "../modes/rpc/jsonl.js";+import { isHelpCommandRequest, PUBLIC_COMMAND_NAMES, REMOVED_COMMAND_NAMES } from "./command-registry.js";import { type CliSubprocessLaunchSpec, createCliSubprocessLaunchSpec } from "./subprocess-launch.js";const OWNED_WORKER_ENV = "PRIME_AGENT_INTERNAL_OWNED_WORKER";@@ -34,17 +35,7 @@ interface OwnedSessionRecoveryDescriptor {const NON_SESSION_FLAGS = new Set(["--help", "-h", "--version", "-v", "--list-models", "--export"]);-const NON_SESSION_COMMANDS = new Set([- "agents",- "manage",- "daemon",- "install",- "remove",- "uninstall",- "update",- "list",- "config",-]);+const NON_SESSION_COMMANDS = new Set([...PUBLIC_COMMAND_NAMES, ...REMOVED_COMMAND_NAMES]);function valueAfter(args: readonly string[], flag: string): string | undefined {const index = args.indexOf(flag);@@ -56,6 +47,9 @@ function hasNonSessionOperation(args: readonly string[]): boolean {return true;}const first = args[0];+ if (first === "help") {+ return isHelpCommandRequest(args.slice(1));+ }return first !== undefined && NON_SESSION_COMMANDS.has(first);}diff --git a/packages/coding-agent/src/cli/public-command.ts b/packages/coding-agent/src/cli/public-command.tsnew file mode 100644index 0000000000..2f561af720--- /dev/null+++ b/packages/coding-agent/src/cli/public-command.ts@@ -0,0 +1,401 @@+import chalk from "chalk";+import { APP_NAME } from "../config.js";+import { handlePackageCommand, isSelfUpdateSource } from "../package-manager-cli.js";+import { INTERNAL_RUNTIME_COMMAND_MARKER, parseArgs } from "./args.js";+import {+ findCommandSuggestion,+ formatCommandHelp,+ formatTopLevelHelp,+ getChildCommandSpecs,+ getCommandSpec,+ isHelpCommandRequest,+ PUBLIC_COMMAND_NAMES,+ REMOVED_COMMAND_NAMES,+} from "./command-registry.js";+import { handleDaemonCommand } from "./daemon-command.js";+import { runPs, runReap, runShutdownAll } from "./daemon-ps.js";++export interface PublicCommandResult {+ handled: boolean;+ args: string[];+ explicitAgentsView: boolean;+ attachAgent?: string;+}++const HANDLED: PublicCommandResult = { handled: true, args: [], explicitAgentsView: false };++export async function handlePublicCommand(args: string[]): Promise<PublicCommandResult> {+ try {+ return await runPublicCommand(args);+ } catch (error) {+ return fail(error instanceof Error ? error.message : String(error));+ }+}++async function runPublicCommand(args: string[]): Promise<PublicCommandResult> {+ if (args[0] === "help" && isHelpCommandRequest(args.slice(1))) {+ return printRequestedHelp(args.slice(1));+ }++ const command = args[0];+ if (!command) {+ return continueWith(args);+ }++ if (REMOVED_COMMAND_NAMES.has(command)) {+ return rejectRemovedCommand(args);+ }++ if (!PUBLIC_COMMAND_NAMES.has(command)) {+ return continueWith(args);+ }++ const separatorIndex = args.indexOf("--");+ const helpIndex = args.findIndex(+ (arg, index) =>+ index > 0 && (separatorIndex === -1 || index < separatorIndex) && (arg === "--help" || arg === "-h"),+ );+ if (helpIndex !== -1) {+ return printRequestedHelp(getCommandPath(args.slice(0, helpIndex)));+ }++ switch (command) {+ case "agents":+ return { handled: false, args: args.slice(1), explicitAgentsView: true };+ case "list":+ return runInternalAgentCommand("list", args.slice(1));+ case "attach": {+ const rest = args.slice(1);+ const agent = rest[0];+ const options = rest.slice(1);+ if (!agent || agent.startsWith("-") || hasPositionalArguments(options)) {+ return fail(`Usage: ${APP_NAME} ${getCommandSpec(["attach"])!.usage}`);+ }+ if (hasConflictingAttachOption(options)) {+ return fail("attach cannot be combined with --resume, --continue, or --fork.");+ }+ return {+ handled: false,+ args: ["--resume", agent, ...options],+ explicitAgentsView: false,+ attachAgent: agent,+ };+ }+ case "stop":+ if (!requireOperandCount(args.slice(1), 1, 1, "stop")) return HANDLED;+ return runInternalAgentCommand("kill", args.slice(1));+ case "rename":+ if (!requireOperandCount(args.slice(1), 2, undefined, "rename")) return HANDLED;+ return runInternalAgentCommand("rename", args.slice(1));+ case "send":+ return runInternalAgentCommand("send", args.slice(1));+ case "schedule":+ return runNestedAgentCommand("schedule", "cron", args.slice(1));+ case "status":+ return runStatus(args.slice(1));+ case "doctor":+ return runDoctor(args.slice(1));+ case "shutdown":+ return runShutdown(args.slice(1));+ case "package":+ return runPackage(args.slice(1));+ case "update": {+ const rest = args.slice(1);+ const hasLegacySelfTarget = rest.some((arg) => arg === "--self" || isSelfUpdateSource(arg));+ const hasLegacyPackageTarget = rest.some(+ (arg) =>+ arg === "--extensions" || arg === "--extension" || (!arg.startsWith("-") && !isSelfUpdateSource(arg)),+ );+ if (hasLegacySelfTarget && hasLegacyPackageTarget) {+ return fail(+ "Prime Agent and package updates are now separate.",+ `Run "${APP_NAME} update [--force]" and "${APP_NAME} package update [source]" separately.`,+ );+ }+ if (hasLegacySelfTarget) {+ return fail("An update target is no longer needed.", `Use "${APP_NAME} update [--force]".`);+ }+ if (hasLegacyPackageTarget) {+ return fail("Package updates moved to the package command.", `Use "${APP_NAME} package update [source]".`);+ }+ const options = parseBooleanOptions(rest, new Set(["--force"]), "update");+ if (!options) return HANDLED;+ await handlePackageCommand(["update", "--self", ...options]);+ return HANDLED;+ }+ case "model":+ return rewriteNestedCommand("model", "list", "--list-models", args.slice(1));+ case "session":+ return rewriteNestedCommand("session", "export", "--export", args.slice(1));+ case "config":+ if (!requireArgumentCount(args.slice(1), 0, "config")) return HANDLED;+ return continueWith(args);+ default:+ return continueWith(args);+ }+}++function continueWith(args: string[]): PublicCommandResult {+ return { handled: false, args, explicitAgentsView: false };+}++function printRequestedHelp(path: string[]): PublicCommandResult {+ if (path.length === 0) {+ console.log(formatTopLevelHelp());+ return HANDLED;+ }+ if (REMOVED_COMMAND_NAMES.has(path[0]!)) {+ return rejectRemovedCommand(path);+ }+ const help = formatCommandHelp(path);+ if (help) {+ console.log(help);+ return HANDLED;+ }+ const parent = path.slice(0, -1);+ const candidates = getChildCommandSpecs(parent).map((spec) => spec.path.at(-1)!);+ const suggestion = findCommandSuggestion(path.at(-1)!, candidates);+ return fail(+ `Unknown command: ${path.join(" ")}`,+ suggestion ? `Did you mean "${APP_NAME} help ${[...parent, suggestion].join(" ")}"?` : undefined,+ );+}++function getCommandPath(args: string[]): string[] {+ const path: string[] = [];+ for (const arg of args) {+ if (!getCommandSpec([...path, arg])) {+ break;+ }+ path.push(arg);+ }+ return path;+}++function rejectRemovedCommand(args: string[]): PublicCommandResult {+ const [command, subcommand] = args;+ let replacement: string | undefined;+ if (command === "daemon") {+ replacement = 'Run "prime-agent help" to see the agent commands.';+ } else if (command === "app" && subcommand === "update") {+ replacement = 'Use "prime-agent update".';+ } else if (command === "install") {+ replacement = 'Use "prime-agent package install".';+ } else if (command === "remove" || command === "uninstall") {+ replacement = 'Use "prime-agent package remove".';+ } else if (command === "manage") {+ replacement = 'Use "prime-agent agents".';+ }+ return fail(`Unknown command: ${args.slice(0, 2).join(" ")}`, replacement);+}++async function runInternalAgentCommand(command: string, args: string[]): Promise<PublicCommandResult> {+ await handleDaemonCommand(["daemon", command, ...args]);+ return HANDLED;+}++async function runNestedAgentCommand(+ parent: string,+ internalCommand: string,+ args: string[],+): Promise<PublicCommandResult> {+ const subcommand = args[0];+ const children = getChildCommandSpecs([parent]).map((spec) => spec.path.at(-1)!);+ if (!subcommand || !children.includes(subcommand)) {+ const suggestion = subcommand ? findCommandSuggestion(subcommand, children) : undefined;+ return fail(+ subcommand ? `Unknown ${parent} command: ${subcommand}` : `Missing ${parent} command.`,+ suggestion+ ? `Did you mean "${APP_NAME} ${parent} ${suggestion}"?`+ : `Run "${APP_NAME} help ${parent}" for usage.`,+ );+ }+ if (parent === "schedule" && !validateScheduleArgs(args)) {+ return HANDLED;+ }+ await handleDaemonCommand(["daemon", internalCommand, ...args]);+ return HANDLED;+}++async function runStatus(args: string[]): Promise<PublicCommandResult> {+ const options = parseBooleanOptions(args, new Set(["--json"]), "status");+ if (!options) return HANDLED;+ await runPs(options.has("--json"));+ return HANDLED;+}++async function runDoctor(args: string[]): Promise<PublicCommandResult> {+ const options = parseBooleanOptions(args, new Set(["--fix", "--json"]), "doctor");+ if (!options) return HANDLED;+ if (options.has("--fix")) {+ await runReap(options.has("--json"), false);+ } else {+ await runPs(options.has("--json"));+ }+ return HANDLED;+}++async function runShutdown(args: string[]): Promise<PublicCommandResult> {+ const options = parseBooleanOptions(args, new Set(["--force", "--json"]), "shutdown");+ if (!options) return HANDLED;+ await runShutdownAll(options.has("--json"), options.has("--force"));+ return HANDLED;+}++async function runPackage(args: string[]): Promise<PublicCommandResult> {+ const subcommand = args[0];+ if (subcommand === "uninstall") {+ return fail("Unknown package command: uninstall", `Use "${APP_NAME} package remove".`);+ }+ const children = getChildCommandSpecs(["package"]).map((spec) => spec.path.at(-1)!);+ if (!subcommand || !children.includes(subcommand)) {+ const suggestion = subcommand ? findCommandSuggestion(subcommand, children) : undefined;+ return fail(+ subcommand ? `Unknown package command: ${subcommand}` : "Missing package command.",+ suggestion ? `Did you mean "${APP_NAME} package ${suggestion}"?` : `Run "${APP_NAME} help package" for usage.`,+ );+ }+ const rest = args.slice(1);+ if (subcommand === "list" && rest.length > 0) {+ return fail(`Usage: ${APP_NAME} package list`);+ }+ if (subcommand === "update") {+ if (+ rest.some((arg) => arg === "--self" || arg === "--extensions" || arg === "--extension" || arg === "--force")+ ) {+ return fail(+ 'Package updates accept only an optional source. Use "prime-agent update --force" to update Prime Agent.',+ );+ }+ if (rest.length > 1) {+ return fail(`Usage: ${APP_NAME} package update [source]`);+ }+ if (rest[0] && isSelfUpdateSource(rest[0])) {+ return fail('Use "prime-agent update" to update Prime Agent.');+ }+ await handlePackageCommand(["update", ...(rest.length === 0 ? ["--extensions"] : rest)]);+ return HANDLED;+ }+ await handlePackageCommand([subcommand, ...rest]);+ return HANDLED;+}++function rewriteNestedCommand(parent: string, subcommand: string, flag: string, args: string[]): PublicCommandResult {+ if (args[0] !== subcommand) {+ const candidate = args[0];+ const suggestion = candidate ? findCommandSuggestion(candidate, [subcommand]) : undefined;+ return fail(+ candidate ? `Unknown ${parent} command: ${candidate}` : `Missing ${parent} command.`,+ suggestion+ ? `Did you mean "${APP_NAME} ${parent} ${suggestion}"?`+ : `Run "${APP_NAME} help ${parent}" for usage.`,+ );+ }+ const splitArgs = splitOperandsAndOptions(args.slice(1));+ if (!splitArgs) {+ return fail(`Usage: ${APP_NAME} ${getCommandSpec([parent, subcommand])?.usage ?? `${parent} ${subcommand}`}`);+ }+ const { operands, options } = splitArgs;+ const validCount = parent === "model" ? operands.length <= 1 : operands.length >= 1 && operands.length <= 2;+ if (!validCount) {+ return fail(`Usage: ${APP_NAME} ${getCommandSpec([parent, subcommand])?.usage ?? `${parent} ${subcommand}`}`);+ }+ return continueWith([INTERNAL_RUNTIME_COMMAND_MARKER, flag, ...operands, ...options]);+}++function parseBooleanOptions(args: string[], allowed: ReadonlySet<string>, command: string): Set<string> | undefined {+ const options = new Set<string>();+ for (const arg of args) {+ if (!allowed.has(arg)) {+ fail(`Unknown option for ${command}: ${arg}`, `Run "${APP_NAME} help ${command}" for usage.`);+ return undefined;+ }+ options.add(arg);+ }+ return options;+}++function requireArgumentCount(args: string[], count: number, command: string): boolean {+ if (args.length === count) {+ return true;+ }+ fail(`Usage: ${APP_NAME} ${getCommandSpec([command])?.usage ?? command}`);+ return false;+}++function hasPositionalArguments(args: string[]): boolean {+ const parsed = parseArgs(args);+ return parsed.messages.length > 0 || parsed.fileArgs.length > 0;+}++function hasConflictingAttachOption(args: string[]): boolean {+ return args.some(+ (arg) =>+ arg === "--resume" ||+ arg === "-r" ||+ arg.startsWith("--resume=") ||+ arg === "--continue" ||+ arg === "-c" ||+ arg === "--fork",+ );+}++function splitOperandsAndOptions(args: string[]): { operands: string[]; options: string[] } | undefined {+ const optionsStart = args.findIndex((arg) => arg.startsWith("-"));+ if (optionsStart === -1) {+ return { operands: args, options: [] };+ }+ const options = args.slice(optionsStart);+ if (hasPositionalArguments(options)) {+ return undefined;+ }+ return { operands: args.slice(0, optionsStart), options };+}++function requireOperandCount(args: string[], minimum: number, maximum: number | undefined, command: string): boolean {+ if (args.some((arg) => arg.startsWith("-") && arg !== "--json")) {+ fail(`Usage: ${APP_NAME} ${getCommandSpec([command])?.usage ?? command}`);+ return false;+ }+ const operands = args.filter((arg) => arg !== "--json");+ if (operands.length >= minimum && (maximum === undefined || operands.length <= maximum)) {+ return true;+ }+ fail(`Usage: ${APP_NAME} ${getCommandSpec([command])?.usage ?? command}`);+ return false;+}++function validateScheduleArgs(args: string[]): boolean {+ const subcommand = args[0];+ if (subcommand === "list") {+ let agentCount = 0;+ for (const arg of args.slice(1)) {+ if (arg === "--all" || arg === "-a" || arg === "--json") {+ continue;+ }+ if (arg.startsWith("-") || ++agentCount > 1) {+ fail(`Usage: ${APP_NAME} schedule list [--all] [agent] [--json]`);+ return false;+ }+ }+ return true;+ }+ if (subcommand === "cancel") {+ const operands = args.slice(1).filter((arg) => arg !== "--json");+ if (operands.length === 1 && !operands[0]!.startsWith("-")) {+ return true;+ }+ fail(`Usage: ${APP_NAME} ${getCommandSpec(["schedule", "cancel"])!.usage}`);+ return false;+ }+ return true;+}++function fail(message: string, hint?: string): PublicCommandResult {+ console.error(chalk.red(`Error: ${message}`));+ if (hint) {+ console.error(chalk.dim(hint));+ }+ process.exitCode = 1;+ return HANDLED;+}diff --git a/packages/coding-agent/src/core/model-resolver.ts b/packages/coding-agent/src/core/model-resolver.tsindex 78bdafb6ee..51724206b6 100644--- a/packages/coding-agent/src/core/model-resolver.ts+++ b/packages/coding-agent/src/core/model-resolver.ts@@ -7,6 +7,7 @@ import { type Api, getLogger, type KnownProvider, type Model, modelsAreEqual } fimport chalk from "chalk";import { minimatch } from "minimatch";import { isValidThinkingLevel } from "../cli/args.js";+import { APP_NAME } from "../config.js";import { DEFAULT_THINKING_LEVEL } from "./defaults.js";import type { ModelRegistry } from "./model-registry.js";import { isPrivatePrimeInferenceModel } from "./prime-inference-models.js";@@ -398,7 +399,7 @@ export function resolveCliModel(options: {return {model: undefined,warning: undefined,- error: `Unknown provider "${cliProvider}". Use --list-models to see available providers/models.`,+ error: `Unknown provider "${cliProvider}". Use "${APP_NAME} model list" to see available providers/models.`,};}@@ -493,7 +494,7 @@ export function resolveCliModel(options: {model: undefined,thinkingLevel: undefined,warning,- error: `Model "${display}" not found. Use --list-models to see available models.`,+ error: `Model "${display}" not found. Use "${APP_NAME} model list" to see available models.`,};}diff --git a/packages/coding-agent/src/main.ts b/packages/coding-agent/src/main.tsindex 80ebffd07e..5c5c3cb213 100644--- a/packages/coding-agent/src/main.ts+++ b/packages/coding-agent/src/main.ts@@ -12,7 +12,6 @@ import { registerBuiltinMcpOAuthProviders } from "@earendil-works/pi-ai/mcp";import { ProcessTerminal, setKeybindings, TUI } from "@earendil-works/pi-tui";import chalk from "chalk";import { type Args, type Mode, parseArgs, printHelp } from "./cli/args.js";-import { handleDaemonCommand, normalizeDaemonStartArgs } from "./cli/daemon-command.js";import {ensureInteractiveDaemonRunning,isDaemonSessionSummary,@@ -26,6 +25,7 @@ import { processFileArguments } from "./cli/file-processor.js";import { buildInitialMessage } from "./cli/initial-message.js";import { listModels } from "./cli/list-models.js";import { installOwnedSessionRecoveryTracking } from "./cli/owned-session-worker.js";+import { handlePublicCommand } from "./cli/public-command.js";import { selectSession } from "./cli/session-picker.js";import { expandTildePath, getAgentDir, getSessionDirEnvOverride, VERSION } from "./config.js";import {@@ -93,7 +93,7 @@ import {import { ExtensionSelectorComponent } from "./modes/interactive/components/extension-selector.js";import { shouldRunOnboarding } from "./modes/interactive/onboarding.js";import { initTheme, preloadCodeHighlighter, stopThemeWatcher } from "./modes/interactive/theme/theme.js";-import { handleConfigCommand, handlePackageCommand } from "./package-manager-cli.js";+import { handleConfigCommand } from "./package-manager-cli.js";import { isLocalPath } from "./utils/paths.js";/**@@ -144,6 +144,10 @@ function isTruthyEnvFlag(value: string | undefined): boolean {export type AppMode = "interactive" | "print" | "json" | "rpc" | "daemon";+export function shouldRejectNonInteractiveAttach(attachAgent: string | undefined, appMode: AppMode): boolean {+ return attachAgent !== undefined && appMode !== "interactive";+}+function resolveAppMode(parsed: Args, stdinIsTTY: boolean): AppMode {if (parsed.mode === "daemon") {return "daemon";@@ -164,10 +168,9 @@ function toPrintOutputMode(appMode: AppMode): Exclude<Mode, "rpc" | "daemon"> {return appMode === "json" ? "json" : "text";}-// `prime-agent agents` / `prime-agent manage` open the agents view directly; the-// leading verb is stripped so the remaining args parse as usual.+// `prime-agent agents` opens the agents view directly.export function parseAgentsViewCommand(args: string[]): { explicitAgentsView: boolean; args: string[] } {- if (args[0] === "agents" || args[0] === "manage") {+ if (args[0] === "agents") {return { explicitAgentsView: true, args: args.slice(1) };}return { explicitAgentsView: false, args };@@ -191,6 +194,13 @@ export function shouldUseDaemonInteractive(options: InteractiveDaemonStartupDeci);}+export function shouldEnsureInteractiveDaemonForStartup(+ useDaemonInteractive: boolean,+ attachAgent: string | undefined,+): boolean {+ return useDaemonInteractive && attachAgent === undefined;+}+export interface AgentsViewStartupDecision {useDaemonInteractive: boolean;needsOnboarding: boolean;@@ -204,7 +214,7 @@ export function shouldOpenAgentsViewForDaemonInteractive(options: AgentsViewStarreturn (options.useDaemonInteractive &&// `prime-agent` opens a new chat by default; the agents view is reached via- // left-arrow from a session or requested explicitly (`agents`/`manage`).+ // left-arrow from a session or requested explicitly (`agents`).!!options.explicitAgentsView &&// Onboarding lives in InteractiveMode, so a first run must take the// direct session path; the agents view would otherwise require creating@@ -232,82 +242,37 @@ export function shouldUseEphemeralSessionManagerForDaemonInteractive(export interface DaemonActiveSessionLookupDecision {useDaemonInteractive: boolean;resumeSelector?: string;+ explicitAttach?: boolean;}export function shouldEnsureDaemonBeforeActiveSessionLookup(options: DaemonActiveSessionLookupDecision): boolean {return (options.useDaemonInteractive &&options.resumeSelector !== undefined &&- !looksLikeSessionPath(options.resumeSelector)+ (options.explicitAttach || !looksLikeSessionPath(options.resumeSelector)));}type ActiveDaemonSessionSummaryLookup = (socketPath: string, selector: string) => Promise<SessionSummary | undefined>;+interface ActiveDaemonSessionSummaryLookupOptions {+ fallbackOnError?: boolean;+ lookup?: ActiveDaemonSessionSummaryLookup;+}+export async function findActiveDaemonSessionSummaryForInteractiveStartup(socketPath: string,selector: string,- lookup: ActiveDaemonSessionSummaryLookup = findActiveDaemonSessionSummary,+ options: ActiveDaemonSessionSummaryLookupOptions = {},): Promise<SessionSummary | undefined> {try {- return await lookup(socketPath, selector);- } catch {- return undefined;- }-}--const DAEMON_RICH_TUI_SHORTCUT_COMMANDS = new Set([- "help",- "start",- "list",- "create",- "attach",- "detach",- "kill",- "rename",- "prompt",- "steer",- "follow-up",- "state",- "messages",- "stats",- "commands",- "shutdown",-]);--export interface DaemonRichTuiAttachShortcut {- socketPath: string;- selector: string;-}--export function parseDaemonRichTuiAttachShortcut(args: string[]): DaemonRichTuiAttachShortcut | undefined {- if (args[0] !== "daemon") {- return undefined;- }-- let socketPath = defaultDaemonSocketPath();- let selector: string | undefined;- for (let index = 1; index < args.length; index++) {- const arg = args[index];- if (arg === "--socket" || arg === "--daemon-socket") {- const value = args[index + 1];- if (!value) {- return undefined;- }- socketPath = value;- index++;- continue;- }- if (arg === "--json" || arg.startsWith("-") || DAEMON_RICH_TUI_SHORTCUT_COMMANDS.has(arg)) {- return undefined;- }- if (selector) {- return undefined;+ return await (options.lookup ?? findActiveDaemonSessionSummary)(socketPath, selector);+ } catch (error) {+ if (options.fallbackOnError === false) {+ throw error;}- selector = arg;+ return undefined;}-- return selector ? { socketPath, selector } : undefined;}function looksLikeSessionPath(sessionArg: string): boolean {@@ -392,12 +357,12 @@ async function promptConfirm(message: string): Promise<boolean> {const STARTUP_SESSION_LOSS_COPY: DaemonSessionLossCopy = {busyDetail(count) {const { noun, pronoun } = pluralizeSessions(count);- return `A background daemon from a different prime-agent version is running with ${count} busy ${noun}. Stopping it will terminate ${pronoun}.`;+ return `A background service from a different Prime Agent version is running with ${count} busy ${noun}. Stopping it will terminate ${pronoun}.`;},unlistableDetail:- "A background daemon from a different prime-agent version is running and its sessions could not be listed. Stopping it may terminate active sessions.",+ "A background service from a different Prime Agent version is running and its sessions could not be listed. Stopping it may terminate active sessions.",question: "Stop it and continue?",- nonTtyHint: 'Run "prime-agent daemon shutdown" to stop it, then retry.',+ nonTtyHint: 'Run "prime-agent shutdown" to stop it, then retry.',};// The promise to keep after awaiting readiness. Wrapped in an object so it@@ -419,7 +384,7 @@ async function takeOverStaleDaemonOrExit(socketPath: string): Promise<DaemonRead}if (!(await shutdownDaemonAndWait(socketPath))) {console.error(- chalk.red(`Could not stop the daemon on ${socketPath}. Run "prime-agent daemon shutdown" and retry.`),+ chalk.red(`Could not stop the background service on ${socketPath}. Run "prime-agent shutdown" and retry.`),);process.exit(1);}@@ -428,7 +393,7 @@ async function takeOverStaleDaemonOrExit(socketPath: string): Promise<DaemonReadawait ready;} catch (error) {const message = error instanceof Error ? error.message : String(error);- console.error(chalk.red(`Could not start the daemon: ${message}`));+ console.error(chalk.red(`Could not start the background service: ${message}`));process.exit(1);}return { ready };@@ -947,11 +912,7 @@ async function findActiveDaemonSessionSummary(selector: string,): Promise<SessionSummary | undefined> {const client = new DaemonClient(socketPath);- try {- await client.connect(250);- } catch {- return undefined;- }+ await client.connect(250);try {const response = await client.request({ type: "get_state", activeSessionId: selector }, 3000);@@ -970,20 +931,6 @@ async function findActiveDaemonSessionSummary(}}-async function normalizeDaemonRichTuiAttachArgs(args: string[]): Promise<string[] | undefined> {- const shortcut = parseDaemonRichTuiAttachShortcut(args);- if (!shortcut) {- return undefined;- }-- const summary = await findActiveDaemonSessionSummary(shortcut.socketPath, shortcut.selector);- if (!summary) {- return undefined;- }-- return ["--daemon-socket", shortcut.socketPath, "--resume", getDaemonSummaryActiveSessionId(summary)];-}-function createSessionManagerForActiveDaemonSummary(summary: SessionSummary, fallbackCwd: string): SessionManager {const cwd = summary.cwd || fallbackCwd;if (summary.sessionFile) {@@ -1103,37 +1050,23 @@ export async function main(args: string[], options?: MainOptions) {}// Client and daemon are separate processes; both need these in their registry.registerBuiltinMcpOAuthProviders();- args = normalizeDaemonStartArgs(args) ?? args;const offlineMode = args.includes("--offline") || isTruthyEnvFlag(process.env.PI_OFFLINE);if (offlineMode) {process.env.PI_OFFLINE = "1";process.env.PI_SKIP_VERSION_CHECK = "1";}- if (await handlePackageCommand(args)) {+ const publicCommand = await handlePublicCommand(args);+ if (publicCommand.handled) {return;}+ args = publicCommand.args;if (await handleConfigCommand(args)) {return;}- try {- args = (await normalizeDaemonRichTuiAttachArgs(args)) ?? args;- } catch (error) {- const message = error instanceof Error ? error.message : String(error);- console.error(chalk.red(`Error: ${message}`));- process.exit(1);- }-- if (await handleDaemonCommand(args)) {- return;- }-- // `prime-agent agents` / `prime-agent manage` open the agents view directly.- const agentsViewCommand = parseAgentsViewCommand(args);- const explicitAgentsView = agentsViewCommand.explicitAgentsView;- args = agentsViewCommand.args;+ const explicitAgentsView = publicCommand.explicitAgentsView;const parsed = parseArgs(args);if (parsed.diagnostics.length > 0) {@@ -1147,6 +1080,10 @@ export async function main(args: string[], options?: MainOptions) {}time("parseArgs");let appMode = resolveAppMode(parsed, process.stdin.isTTY);+ if (shouldRejectNonInteractiveAttach(publicCommand.attachAgent, appMode)) {+ console.error(chalk.red("Error: attach requires an interactive terminal"));+ process.exit(1);+ }setLogContext({ mode: appMode });const shouldTakeOverStdout = appMode !== "interactive";if (shouldTakeOverStdout) {@@ -1221,8 +1158,10 @@ export async function main(args: string[], options?: MainOptions) {startupSettingsManager.getSessionDir();const daemonSocketPath = parsed.daemonSocket ?? defaultDaemonSocketPath();// Kick off daemon spawn/readiness immediately so it overlaps session-manager- // and runtime-services preparation; awaited wherever the daemon is first used.- let daemonReady = useDaemonInteractive ? ensureInteractiveDaemonRunning(daemonSocketPath) : undefined;+ // and runtime-services preparation; attach only connects to an existing daemon.+ let daemonReady = shouldEnsureInteractiveDaemonForStartup(useDaemonInteractive, publicCommand.attachAgent)+ ? ensureInteractiveDaemonRunning(daemonSocketPath)+ : undefined;// Errors are rethrown at the await sites below; this only avoids an unhandled// rejection if startup exits before reaching them.daemonReady?.catch(() => {});@@ -1230,14 +1169,29 @@ export async function main(args: string[], options?: MainOptions) {const shouldLookupDaemonActiveSession = shouldEnsureDaemonBeforeActiveSessionLookup({useDaemonInteractive,resumeSelector,+ explicitAttach: publicCommand.attachAgent !== undefined,});if (shouldLookupDaemonActiveSession && daemonReady) {daemonReady = (await awaitDaemonReady(daemonReady)).ready;}- const activeDaemonSessionSummary =- shouldLookupDaemonActiveSession && resumeSelector- ? await findActiveDaemonSessionSummaryForInteractiveStartup(daemonSocketPath, resumeSelector)- : undefined;+ let activeDaemonSessionSummary: SessionSummary | undefined;+ if (shouldLookupDaemonActiveSession && resumeSelector) {+ try {+ activeDaemonSessionSummary = await findActiveDaemonSessionSummaryForInteractiveStartup(+ daemonSocketPath,+ resumeSelector,+ { fallbackOnError: !publicCommand.attachAgent },+ );+ } catch (error) {+ const message = error instanceof Error ? error.message : String(error);+ console.error(chalk.red(`Error: Could not look up active agent '${resumeSelector}': ${message}`));+ process.exit(1);+ }+ }+ if (publicCommand.attachAgent && !activeDaemonSessionSummary) {+ console.error(chalk.red(`Error: No active agent found matching '${publicCommand.attachAgent}'`));+ process.exit(1);+ }let sessionManager: SessionManager;if (activeDaemonSessionSummary) {sessionManager = createSessionManagerForActiveDaemonSummary(activeDaemonSessionSummary, cwd);diff --git a/packages/coding-agent/src/modes/daemon/daemon-supervisor.ts b/packages/coding-agent/src/modes/daemon/daemon-supervisor.tsindex 793e1f73de..b33454def4 100644--- a/packages/coding-agent/src/modes/daemon/daemon-supervisor.ts+++ b/packages/coding-agent/src/modes/daemon/daemon-supervisor.ts@@ -29,6 +29,7 @@ import {} from "../../core/orphan-process-journal.js";import { getProcessStartId } from "../../core/session-lease.js";import type { SessionInfo } from "../../core/session-manager.js";+import { signalProcessGroupOrProcess } from "../../utils/child-process.js";import type { AgentConnectionHeartbeat } from "../agent-connection/types.js";import { attachJsonlLineReader, serializeJsonLine } from "../rpc/jsonl.js";import type { PrivateFrame } from "../session-worker/private-framing.js";@@ -439,20 +440,6 @@ function isProcessAlive(pid: number): boolean {}}-function signalProcessGroupOrProcess(pid: number, signal: NodeJS.Signals): void {- try {- process.kill(-pid, signal);- return;- } catch {- // Fall back when process groups are unavailable or the group already exited.- }- try {- process.kill(pid, signal);- } catch {- // The process may already be fully reaped.- }-}-function isFinalizedTranscriptEvent(eventType: string | undefined): boolean {return (eventType === "message_end" ||diff --git a/packages/coding-agent/src/package-manager-cli.ts b/packages/coding-agent/src/package-manager-cli.tsindex 4d25a702d3..3e133230df 100644--- a/packages/coding-agent/src/package-manager-cli.ts+++ b/packages/coding-agent/src/package-manager-cli.ts@@ -46,6 +46,10 @@ export type PackageCommand = "install" | "remove" | "update" | "list";type UpdateTarget = { type: "all" } | { type: "self" } | { type: "extensions"; source?: string };+export function isSelfUpdateSource(source: string): boolean {+ return source === "self" || source === "pi" || source === APP_NAME;+}+interface PackageCommandOptions {command: PackageCommand;source?: string;@@ -72,13 +76,13 @@ function reportSettingsErrors(settingsManager: SettingsManager, context: string)function getPackageCommandUsage(command: PackageCommand): string {switch (command) {case "install":- return `${APP_NAME} install <source> [-l]`;+ return `${APP_NAME} package install <source> [--local]`;case "remove":- return `${APP_NAME} remove <source> [-l]`;+ return `${APP_NAME} package remove <source> [--local]`;case "update":- return `${APP_NAME} update [source|self|${APP_NAME}] [--self] [--extensions] [--extension <source>] [--force]`;+ return `${APP_NAME} update [--force] or ${APP_NAME} package update [source]`;case "list":- return `${APP_NAME} list`;+ return `${APP_NAME} package list`;}}@@ -91,15 +95,15 @@ function printPackageCommandHelp(command: PackageCommand): void {Install a package and add it to settings.Options:- -l, --local Install project-locally (${CONFIG_DIR_NAME}/settings.json)+ --local Install project-locally (${CONFIG_DIR_NAME}/settings.json)Examples:- ${APP_NAME} install npm:@foo/bar- ${APP_NAME} install git:github.com/user/repo- ${APP_NAME} install git:[email protected]:user/repo- ${APP_NAME} install https://github.com/user/repo- ${APP_NAME} install ssh://[email protected]/user/repo- ${APP_NAME} install ./local/path+ ${APP_NAME} package install npm:@foo/bar+ ${APP_NAME} package install git:github.com/user/repo+ ${APP_NAME} package install git:[email protected]:user/repo+ ${APP_NAME} package install https://github.com/user/repo+ ${APP_NAME} package install ssh://[email protected]/user/repo+ ${APP_NAME} package install ./local/path`);return;@@ -108,14 +112,12 @@ Examples:${getPackageCommandUsage("remove")}Remove a package and its source from settings.-Alias: ${APP_NAME} uninstall <source> [-l]Options:- -l, --local Remove from project settings (${CONFIG_DIR_NAME}/settings.json)+ --local Remove from project settings (${CONFIG_DIR_NAME}/settings.json)Examples:- ${APP_NAME} remove npm:@foo/bar- ${APP_NAME} uninstall npm:@foo/bar+ ${APP_NAME} package remove npm:@foo/bar`);return;@@ -123,7 +125,7 @@ Examples:console.log(`${chalk.bold("Usage:")}${getPackageCommandUsage("update")}-Update ${APP_NAME} and installed packages.+Update ${APP_NAME} or installed packages.Options:--self Update ${APP_NAME} only@@ -131,10 +133,10 @@ Options:--extension <source> Update one package only--force Reinstall ${APP_NAME} even if the current version is latest-Short forms:- ${APP_NAME} update Update ${APP_NAME} and all extensions- ${APP_NAME} update <source> Update one package- ${APP_NAME} update ${APP_NAME} Update ${APP_NAME} only (self works as an alias)+Commands:+ ${APP_NAME} update Update ${APP_NAME}+ ${APP_NAME} package update Update installed packages+ ${APP_NAME} package update <source> Update one package`);return;@@ -179,7 +181,7 @@ function parsePackageCommand(args: string[]): PackageCommandOptions | undefinedcontinue;}- if (arg === "-l" || arg === "--local") {+ if (arg === "--local") {if (command === "install" || command === "remove") {local = true;} else {@@ -257,7 +259,7 @@ function parsePackageCommand(args: string[]): PackageCommandOptions | undefined}updateTarget = { type: "extensions", source: extensionFlagSource };} else if (source) {- const sourceIsSelf = source === "self" || source === "pi" || source === APP_NAME;+ const sourceIsSelf = isSelfUpdateSource(source);if (sourceIsSelf) {updateTarget = extensionsFlag ? { type: "all" } : { type: "self" };} else {@@ -383,10 +385,10 @@ const UPDATE_RESTART_CONTINUATION_PROMPT =const UPDATE_SESSION_LOSS_COPY: DaemonSessionLossCopy = {busyDetail(count) {const { noun, pronoun } = pluralizeSessions(count);- return `The running daemon has ${count} busy ${noun}. After the update installs, Prime Agent will stop ${pronoun}, restart the daemon, and resume interrupted work.`;+ return `Prime Agent has ${count} busy ${noun}. After the update installs, it will stop ${pronoun}, restart its background service, and resume interrupted work.`;},unlistableDetail:- "A running daemon's sessions could not be listed. After the update installs, Prime Agent will stop resident sessions, restart the daemon, and resume interrupted work where possible.",+ "Running agents could not be listed. After the update installs, Prime Agent will stop resident agents, restart its background service, and resume interrupted work where possible.",question: "Continue?",nonTtyHint: "Re-run with --force to proceed.",};@@ -1010,7 +1012,7 @@ async function restoreDaemonUpdateRestart(socketPath: string, manifest: DaemonUp} finally {client.close();}- console.log(chalk.green(`Restored ${restored} daemon session${restored === 1 ? "" : "s"}`));+ console.log(chalk.green(`Restored ${restored} agent session${restored === 1 ? "" : "s"}`));if (resumed > 0) {console.log(chalk.green(`Resumed ${resumed} interrupted session${resumed === 1 ? "" : "s"}`));}@@ -1035,7 +1037,7 @@ async function tryRestoreDaemonUpdateRestart(return true;} catch (error: unknown) {console.error(- chalk.yellow(`Warning: could not restore daemon sessions ${failureContext}: ${formatUnknownError(error)}`),+ chalk.yellow(`Warning: could not restore agent sessions ${failureContext}: ${formatUnknownError(error)}`),);return false;}@@ -1054,14 +1056,14 @@ async function restartDaemonAfterSelfUpdate(socketPath: string, agentDir: stringif (daemonProbeMayHaveBusySessions(daemonProbe) || !daemonLacksPrepareCommand) {console.error(chalk.yellow(- `Warning: updated, but could not prepare daemon sessions for automatic resume (${message}); leaving the running daemon on the previous version.`,+ `Warning: updated, but could not prepare agent sessions for automatic resume (${message}); leaving the background service on the previous version.`,),);return;}console.error(chalk.yellow(- `Warning: the old daemon cannot prepare idle sessions for automatic resume (${message}); restarting the daemon without restored sessions.`,+ `Warning: the old background service cannot prepare idle sessions for automatic resume (${message}); restarting without restored sessions.`,),);}@@ -1075,7 +1077,9 @@ async function restartDaemonAfterSelfUpdate(socketPath: string, agentDir: stringconst stopped = oldDaemonAlreadyStopped || (await shutdownDaemonAndWait(socketPath));if (!stopped) {console.error(- chalk.yellow(`Warning: could not stop the old daemon on ${socketPath}; it will be replaced on next launch.`),+ chalk.yellow(+ `Warning: could not stop the old background service on ${socketPath}; it will be replaced on next launch.`,+ ),);await tryRestoreDaemonUpdateRestart(socketPath, agentDir, manifest, "after daemon stop failed");return;@@ -1086,7 +1090,7 @@ async function restartDaemonAfterSelfUpdate(socketPath: string, agentDir: stringconst message = formatUnknownError(error);console.error(chalk.yellow(- `Warning: updated, but could not relaunch the daemon (${message}); it will start on next launch.`,+ `Warning: updated, but could not relaunch the background service (${message}); it will start on next launch.`,),);await tryRestoreDaemonUpdateRestart(socketPath, agentDir, manifest, "after relaunch failed");@@ -1131,6 +1135,11 @@ export async function handlePackageCommand(args: string[]): Promise<boolean> {}if (options.invalidOption) {+ if (options.invalidOption === "-l" && (options.command === "install" || options.command === "remove")) {+ console.error(chalk.red('Option -l was removed. Use "--local".'));+ process.exitCode = 1;+ return true;+ }console.error(chalk.red(`Unknown option ${options.invalidOption} for "${options.command}".`));console.error(chalk.dim(`Use "${APP_NAME} --help" or "${getPackageCommandUsage(options.command)}".`));process.exitCode = 1;diff --git a/packages/coding-agent/src/utils/child-process.ts b/packages/coding-agent/src/utils/child-process.tsindex 7e91bc3718..dd2d021343 100644--- a/packages/coding-agent/src/utils/child-process.ts+++ b/packages/coding-agent/src/utils/child-process.ts@@ -12,6 +12,20 @@ export function shouldUseWindowsShell(command: string): boolean {return commandName.endsWith(".cmd") || commandName.endsWith(".bat") || WINDOWS_SHELL_COMMANDS.has(commandName);}+export function signalProcessGroupOrProcess(pid: number, signal: NodeJS.Signals): void {+ try {+ process.kill(-pid, signal);+ return;+ } catch {+ // Fall back when process groups are unavailable or the group already exited.+ }+ try {+ process.kill(pid, signal);+ } catch {+ // The process may already be fully reaped.+ }+}+/*** Wait for a child process to terminate without hanging on inherited stdio handles.*diff --git a/packages/coding-agent/test/args.test.ts b/packages/coding-agent/test/args.test.tsindex 0c13740e2b..2be760a8d0 100644--- a/packages/coding-agent/test/args.test.ts+++ b/packages/coding-agent/test/args.test.ts@@ -1,5 +1,5 @@import { describe, expect, test } from "vitest";-import { parseArgs } from "../src/cli/args.js";+import { INTERNAL_RUNTIME_COMMAND_MARKER, parseArgs } from "../src/cli/args.js";describe("parseArgs", () => {describe("--version flag", () => {@@ -194,11 +194,36 @@ describe("parseArgs", () => {expect(result.messages).toEqual([]);});- test("parses --export", () => {+ test("rejects removed --export syntax", () => {const result = parseArgs(["--export", "session.jsonl"]);+ expect(result.export).toBeUndefined();+ expect(result.messages).toEqual([]);+ expect(result.diagnostics).toContainEqual({+ type: "error",+ message: '--export was removed. Use "prime-agent session export <file> [output]".',+ });+ });++ test("parses session export only through the internal command marker", () => {+ const result = parseArgs([INTERNAL_RUNTIME_COMMAND_MARKER, "--export", "session.jsonl"]);expect(result.export).toBe("session.jsonl");});+ test("rejects removed --list-models syntax", () => {+ const result = parseArgs(["--list-models", "sonnet"]);+ expect(result.listModels).toBeUndefined();+ expect(result.messages).toEqual([]);+ expect(result.diagnostics).toContainEqual({+ type: "error",+ message: '--list-models was removed. Use "prime-agent model list [search]".',+ });+ });++ test("parses model list only through the internal command marker", () => {+ const result = parseArgs([INTERNAL_RUNTIME_COMMAND_MARKER, "--list-models", "sonnet"]);+ expect(result.listModels).toBe("sonnet");+ });+test("parses --thinking", () => {const result = parseArgs(["--thinking", "high"]);expect(result.thinking).toBe("high");diff --git a/packages/coding-agent/test/daemon-command.test.ts b/packages/coding-agent/test/daemon-command.test.tsindex 5bd23068ae..cd298873bd 100644--- a/packages/coding-agent/test/daemon-command.test.ts+++ b/packages/coding-agent/test/daemon-command.test.ts@@ -13,17 +13,19 @@ const daemonClientMock = vi.hoisted(() => {message?: string;schedule?: string;prompt?: string;+ includeInactive?: boolean;sessionPath?: string;config?: { extensionFlagValues?: Record<string, boolean | string> };};type Response =- | { type: "response"; command: string; success: true }+ | { type: "response"; command: string; success: true; data?: unknown }| { type: "response"; command: string; success: false; error: string };const instances: MockDaemonClient[] = [];const behavior = {promptSucceeds: false,emitStaleAgentEndOnAttach: false,+ sessions: [] as Array<Record<string, unknown>>,};class MockDaemonClient {@@ -41,6 +43,9 @@ const daemonClientMock = vi.hoisted(() => {async request(command: Command): Promise<Response> {this.requests.push(command);+ if (command.type === "list") {+ return { type: "response", command: command.type, success: true, data: { sessions: behavior.sessions } };+ }if (command.type === "attach" && behavior.emitStaleAgentEndOnAttach) {this.emitMessage({ type: "session_event", activeSessionId: "active-1", event: { type: "agent_end" } });}@@ -95,9 +100,11 @@ describe("daemon command", () => {let consoleErrorMessages: unknown[];beforeEach(() => {+ process.exitCode = undefined;daemonClientMock.instances.length = 0;daemonClientMock.behavior.promptSucceeds = false;daemonClientMock.behavior.emitStaleAgentEndOnAttach = false;+ daemonClientMock.behavior.sessions = [];consoleErrorMessages = [];vi.spyOn(process, "exit").mockImplementation(((code?: string | number | null | undefined) => {throw new Error(`exit ${code}`);@@ -109,13 +116,14 @@ describe("daemon command", () => {});afterEach(() => {+ process.exitCode = undefined;vi.restoreAllMocks();});it("cleans prompt listeners when the prompt request fails", async () => {await expect(handleDaemonCommand(["daemon", "--socket", "/tmp/prime-agent.sock", "prompt", "active-1", "hello"]),- ).rejects.toThrow("exit 1");+ ).resolves.toBe(true);const client = daemonClientMock.instances[0];expect(client?.messageListenerCountAtClose).toBe(0);@@ -257,12 +265,12 @@ describe("daemon command", () => {it("rejects unknown send options instead of folding them into the message", async () => {await expect(handleDaemonCommand(["daemon", "--socket", "/tmp/prime-agent.sock", "send", "worker", "--bogus", "hello"]),- ).rejects.toThrow("exit 1");+ ).resolves.toBe(true);expect(daemonClientMock.instances[0]?.requests).toEqual([]);expect(consoleErrorMessages.some(- (message) => typeof message === "string" && message.includes("Unknown option for daemon send: --bogus"),+ (message) => typeof message === "string" && message.includes("Unknown option for send: --bogus"),),).toBe(true);});@@ -315,10 +323,32 @@ describe("daemon command", () => {});});+ it("rejects conflicting send delivery modes", async () => {+ await expect(+ handleDaemonCommand([+ "daemon",+ "--socket",+ "/tmp/prime-agent.sock",+ "send",+ "--steer",+ "--follow-up",+ "worker",+ "hello",+ ]),+ ).resolves.toBe(true);++ expect(daemonClientMock.instances[0]?.requests).toEqual([]);+ expect(+ consoleErrorMessages.some(+ (message) => typeof message === "string" && message.includes("Only one send delivery mode"),+ ),+ ).toBe(true);+ });+it("rejects extra agent-messages status arguments", async () => {await expect(handleDaemonCommand(["daemon", "--socket", "/tmp/prime-agent.sock", "agent-messages", "pause", "active-1"]),- ).rejects.toThrow("exit 1");+ ).resolves.toBe(true);expect(daemonClientMock.instances[0]?.requests).toEqual([]);expect(@@ -376,8 +406,38 @@ describe("daemon command", () => {prompt: "check status",});});++ it("resolves agent names before filtering scheduled prompts", async () => {+ daemonClientMock.behavior.sessions = [makeSessionSummary("active-1", "session-1", "alpha")];++ await expect(+ handleDaemonCommand(["daemon", "--socket", "/tmp/prime-agent.sock", "--json", "cron", "list", "alpha"]),+ ).resolves.toBe(true);++ expect(daemonClientMock.instances[0]?.requests).toEqual([+ { type: "list" },+ { type: "cron_list", activeSessionId: "active-1", includeInactive: false },+ ]);+ });});+function makeSessionSummary(activeSessionId: string, sessionId: string, sessionName: string): Record<string, unknown> {+ return {+ id: activeSessionId,+ activeSessionId,+ sessionId,+ sessionName,+ cwd: "/tmp/project",+ lifecycle: "ready",+ activity: "idle",+ isStreaming: false,+ isCompacting: false,+ attachedClients: 0,+ messageCount: 0,+ pendingMessageCount: 0,+ };+}+async function flushPromises(): Promise<void> {await Promise.resolve();await Promise.resolve();diff --git a/packages/coding-agent/test/daemon-launch.test.ts b/packages/coding-agent/test/daemon-launch.test.tsindex 9b448d8fa0..af3b063e1f 100644--- a/packages/coding-agent/test/daemon-launch.test.ts+++ b/packages/coding-agent/test/daemon-launch.test.ts@@ -4,7 +4,11 @@ import { createServer, type Server, type Socket } from "node:net";import { tmpdir } from "node:os";import { join } from "node:path";import { afterEach, describe, expect, it } from "vitest";-import { probeRunningDaemonSessions, shutdownDaemonAndWait } from "../src/cli/daemon-launch.js";+import {+ probeRunningDaemonSessions,+ shouldStartInteractiveDaemonEarly,+ shutdownDaemonAndWait,+} from "../src/cli/daemon-launch.js";interface FakeDaemonOptions {/** Sessions returned for a `list` command. */@@ -158,6 +162,36 @@ describe("probeRunningDaemonSessions", () => {});});+describe("shouldStartInteractiveDaemonEarly", () => {+ it("starts early for default interactive use and the agents view", () => {+ expect(shouldStartInteractiveDaemonEarly([], true, false)).toBe(true);+ expect(shouldStartInteractiveDaemonEarly(["agents"], true, false)).toBe(true);+ expect(shouldStartInteractiveDaemonEarly(["review this change"], true, false)).toBe(true);+ expect(shouldStartInteractiveDaemonEarly(["help", "me", "fix", "this"], true, false)).toBe(true);+ });++ it("does not start a service for standalone management commands", () => {+ for (const command of [+ "list",+ "attach",+ "status",+ "doctor",+ "shutdown",+ "package",+ "update",+ "model",+ "session",+ ]) {+ expect(shouldStartInteractiveDaemonEarly([command], true, false)).toBe(false);+ }+ });++ it("does not start a service for help or removed command forms", () => {+ expect(shouldStartInteractiveDaemonEarly(["help"], true, false)).toBe(false);+ expect(shouldStartInteractiveDaemonEarly(["daemon", "list"], true, false)).toBe(false);+ });+});+describe("shutdownDaemonAndWait", () => {const cleanups: Array<() => Promise<void>> = [];afterEach(async () => {diff --git a/packages/coding-agent/test/daemon-ps-format.test.ts b/packages/coding-agent/test/daemon-ps-format.test.tsindex ccd60ad607..1b3108b6ff 100644--- a/packages/coding-agent/test/daemon-ps-format.test.ts+++ b/packages/coding-agent/test/daemon-ps-format.test.ts@@ -42,7 +42,7 @@ describe("formatDaemonListTable", () => {const lines = table.split("\n");expect(lines[0]!.trim().split(/\s+/)).toEqual(["socket", "pid", "version", "status", "sessions", "uptime"]);expect(table).toContain("/tmp/prime-agent-1000/daemon.sock *");- expect(table).toContain("* default daemon");+ expect(table).toContain("* default background service");expect(table).toContain("current");expect(table).toContain("orphan-file");expect(table).toContain("2h");diff --git a/packages/coding-agent/test/daemon-ps.test.ts b/packages/coding-agent/test/daemon-ps.test.tsindex 43dcd609d8..ca20129d12 100644--- a/packages/coding-agent/test/daemon-ps.test.ts+++ b/packages/coding-agent/test/daemon-ps.test.ts@@ -1,13 +1,25 @@+import { join } from "node:path";import { describe, expect, it } from "vitest";import {type DaemonInfo,+ isWorkerSocketPath,parseLsofListeners,parsePsEtimes,parseSsListeners,planReap,planShutdownAll,+ planShutdownConfirmation,sortDaemons,} from "../src/cli/daemon-ps.js";+import { defaultDaemonSocketDir } from "../src/modes/daemon/daemon-socket.js";++describe("worker socket classification", () => {+ it.runIf(process.platform !== "win32")("recognizes only worker sockets in the default service directory", () => {+ expect(isWorkerSocketPath(join(defaultDaemonSocketDir(), "worker-abc.sock"))).toBe(true);+ expect(isWorkerSocketPath(join(defaultDaemonSocketDir(), "daemon.sock"))).toBe(false);+ expect(isWorkerSocketPath("/tmp/worker-abc.sock")).toBe(false);+ });+});describe("parseSsListeners", () => {const stdout = [@@ -113,7 +125,9 @@ describe("planReap", () => {it("only kills unreachable daemons with --force", () => {const daemon = makeDaemon({ socketPath: "/tmp/hung.sock", status: "unreachable", pid: 7 });- expect(planReap([daemon], false)[0]!.kind).toBe("skip");+ const skipped = planReap([daemon], false)[0]!;+ expect(skipped.kind).toBe("skip");+ expect(skipped.kind === "skip" ? skipped.reason : "").toContain("prime-agent shutdown --force");expect(planReap([daemon], true)[0]!.kind).toBe("kill");});@@ -132,28 +146,63 @@ describe("planReap", () => {});describe("planShutdownAll", () => {- it("targets every daemon reap would skip", () => {- const plan = planShutdownAll([- makeDaemon({ socketPath: "/tmp/default.sock", status: "current", isDefault: true, sessionCount: 0, pid: 1 }),- makeDaemon({ socketPath: "/tmp/busy.sock", status: "current", sessionCount: 3, pid: 2 }),- makeDaemon({ socketPath: "/tmp/hung.sock", status: "unreachable", pid: 7 }),- makeDaemon({ socketPath: "/tmp/orphan.sock", status: "orphan-file" }),- ]);+ it("targets every service when forced", () => {+ const plan = planShutdownAll(+ [+ makeDaemon({+ socketPath: "/tmp/default.sock",+ status: "current",+ isDefault: true,+ sessionCount: 0,+ pid: 1,+ }),+ makeDaemon({ socketPath: "/tmp/busy.sock", status: "current", sessionCount: 3, pid: 2 }),+ makeDaemon({ socketPath: "/tmp/hung.sock", status: "unreachable", pid: 7 }),+ makeDaemon({ socketPath: "/tmp/orphan.sock", status: "orphan-file" }),+ ],+ true,+ );expect(plan.map((action) => action.kind)).toEqual(["shutdown", "shutdown", "kill", "remove-file"]);});- it("never skips a daemon", () => {- const plan = planShutdownAll([- makeDaemon({ socketPath: "/tmp/a.sock", status: "stale", pid: 9 }),- makeDaemon({ socketPath: "/tmp/b.sock", status: "unreachable", pid: 10 }),- ]);+ it("never skips a service when forced", () => {+ const plan = planShutdownAll(+ [+ makeDaemon({ socketPath: "/tmp/a.sock", status: "stale", pid: 9 }),+ makeDaemon({ socketPath: "/tmp/b.sock", status: "unreachable", pid: 10 }),+ ],+ true,+ );expect(plan.some((action) => action.kind === "skip")).toBe(false);});it("removes the socket file for an unreachable daemon with no pid", () => {- const plan = planShutdownAll([makeDaemon({ socketPath: "/tmp/c.sock", status: "unreachable" })]);+ const plan = planShutdownAll([makeDaemon({ socketPath: "/tmp/c.sock", status: "unreachable" })], false);expect(plan[0]!.kind).toBe("remove-file");});++ it("requires force for unreachable tracked workers", () => {+ const daemon = makeDaemon({+ socketPath: "/tmp/worker-only.sock",+ status: "unreachable",+ hasTrackedWorkers: true,+ });+ expect(planShutdownAll([daemon], false)[0]!.kind).toBe("skip");+ expect(planShutdownAll([daemon], true)[0]!.kind).toBe("remove-file");+ });+});++describe("planShutdownConfirmation", () => {+ it("never prompts when JSON output was requested", () => {+ expect(planShutdownConfirmation(1, true, false, true)).toBe("json-error");+ });++ it("prompts only for non-JSON shutdown at a TTY", () => {+ expect(planShutdownConfirmation(1, false, false, true)).toBe("prompt");+ expect(planShutdownConfirmation(1, false, false, false)).toBe("tty-error");+ expect(planShutdownConfirmation(1, true, true, true)).toBe("none");+ expect(planShutdownConfirmation(0, false, false, true)).toBe("none");+ });});function makeDaemon(options: Partial<DaemonInfo> & { socketPath: string; status: DaemonInfo["status"] }): DaemonInfo {diff --git a/packages/coding-agent/test/main-interactive-routing.test.ts b/packages/coding-agent/test/main-interactive-routing.test.tsindex ae83d27c11..129dce791d 100644--- a/packages/coding-agent/test/main-interactive-routing.test.ts+++ b/packages/coding-agent/test/main-interactive-routing.test.ts@@ -7,11 +7,12 @@ import {findActiveDaemonSessionSummaryForSessionFile,type InteractiveDaemonStartupDecision,parseAgentsViewCommand,- parseDaemonRichTuiAttachShortcut,resolveRuntimeSessionOptions,restoreResumeSelectorFallback,shouldEnsureDaemonBeforeActiveSessionLookup,+ shouldEnsureInteractiveDaemonForStartup,shouldOpenAgentsViewForDaemonInteractive,+ shouldRejectNonInteractiveAttach,shouldUseDaemonInteractive,shouldUseEphemeralSessionManagerForDaemonInteractive,} from "../src/main.js";@@ -64,6 +65,18 @@ describe("interactive startup routing", () => {}),).toBe(false);});++ test("rejects attach before non-interactive startup", () => {+ expect(shouldRejectNonInteractiveAttach("worker", "print")).toBe(true);+ expect(shouldRejectNonInteractiveAttach("worker", "interactive")).toBe(false);+ expect(shouldRejectNonInteractiveAttach(undefined, "print")).toBe(false);+ });++ test("does not start the daemon for attach", () => {+ expect(shouldEnsureInteractiveDaemonForStartup(true, undefined)).toBe(true);+ expect(shouldEnsureInteractiveDaemonForStartup(true, "worker")).toBe(false);+ expect(shouldEnsureInteractiveDaemonForStartup(false, undefined)).toBe(false);+ });});describe("daemon-backed interactive session manager routing", () => {@@ -76,7 +89,7 @@ describe("daemon-backed interactive session manager routing", () => {).toBe(false);});- test("opens the agents view when explicitly requested via the agents/manage command", () => {+ test("opens the agents view when explicitly requested", () => {expect(shouldOpenAgentsViewForDaemonInteractive({useDaemonInteractive: true,@@ -124,6 +137,13 @@ describe("daemon-backed interactive session manager routing", () => {resumeSelector: "/tmp/session.jsonl",}),).toBe(false);+ expect(+ shouldEnsureDaemonBeforeActiveSessionLookup({+ useDaemonInteractive: true,+ resumeSelector: "/tmp/session.jsonl",+ explicitAttach: true,+ }),+ ).toBe(true);expect(shouldEnsureDaemonBeforeActiveSessionLookup({useDaemonInteractive: false,@@ -134,27 +154,42 @@ describe("daemon-backed interactive session manager routing", () => {test("falls back to local session lookup when daemon active-session probing fails", async () => {await expect(- findActiveDaemonSessionSummaryForInteractiveStartup("/tmp/prime.sock", "saved-session-id", async () => {- throw new Error("Daemon returned an invalid active session summary");+ findActiveDaemonSessionSummaryForInteractiveStartup("/tmp/prime.sock", "saved-session-id", {+ lookup: async () => {+ throw new Error("Daemon returned an invalid active session summary");+ },}),).resolves.toBeUndefined();});+ test("propagates active-session lookup failures for explicit attach", async () => {+ await expect(+ findActiveDaemonSessionSummaryForInteractiveStartup("/tmp/prime.sock", "active-1", {+ fallbackOnError: false,+ lookup: async () => {+ throw new Error("protocol mismatch");+ },+ }),+ ).rejects.toThrow("protocol mismatch");+ });+test("uses daemon active-session summary when probing succeeds", async () => {await expect(- findActiveDaemonSessionSummaryForInteractiveStartup("/tmp/prime.sock", "active-1", async () => ({- id: "active-1",- activeSessionId: "active-1",- lifecycle: "draft",- activity: "idle",- sessionId: "session-1",- cwd: "/tmp/project",- isStreaming: false,- isCompacting: false,- attachedClients: 0,- messageCount: 0,- pendingMessageCount: 0,- })),+ findActiveDaemonSessionSummaryForInteractiveStartup("/tmp/prime.sock", "active-1", {+ lookup: async () => ({+ id: "active-1",+ activeSessionId: "active-1",+ lifecycle: "draft",+ activity: "idle",+ sessionId: "session-1",+ cwd: "/tmp/project",+ isStreaming: false,+ isCompacting: false,+ attachedClients: 0,+ messageCount: 0,+ pendingMessageCount: 0,+ }),+ }),).resolves.toMatchObject({ activeSessionId: "active-1" });});@@ -216,10 +251,10 @@ describe("agents view command parsing", () => {expect(parseAgentsViewCommand(["agents"])).toEqual({ explicitAgentsView: true, args: [] });});- test("treats manage as an alias for agents", () => {+ test("does not treat manage as an alias", () => {expect(parseAgentsViewCommand(["manage", "--verbose"])).toEqual({- explicitAgentsView: true,- args: ["--verbose"],+ explicitAgentsView: false,+ args: ["manage", "--verbose"],});});@@ -238,27 +273,6 @@ describe("agents view command parsing", () => {});});-describe("daemon rich TUI attach shortcut parsing", () => {- test("recognizes daemon active-session shorthand", () => {- expect(parseDaemonRichTuiAttachShortcut(["daemon", "d5c1e83e2182"])).toMatchObject({- selector: "d5c1e83e2182",- });- });-- test("preserves explicit daemon client commands", () => {- expect(parseDaemonRichTuiAttachShortcut(["daemon", "attach", "d5c1e83e2182"])).toBeUndefined();- expect(parseDaemonRichTuiAttachShortcut(["daemon", "list"])).toBeUndefined();- expect(parseDaemonRichTuiAttachShortcut(["daemon", "create", "scratch"])).toBeUndefined();- });-- test("carries daemon socket option into shorthand attach", () => {- expect(parseDaemonRichTuiAttachShortcut(["daemon", "--socket", "/tmp/prime.sock", "d5c1e83e2182"])).toEqual({- socketPath: "/tmp/prime.sock",- selector: "d5c1e83e2182",- });- });-});-describe("runtime session option resolution", () => {test("preserves daemon-provided RLM heartbeat controller when creating sessions", () => {const preparedModel = { id: "prepared-model" } as unknown as CreateAgentSessionOptions["model"];diff --git a/packages/coding-agent/test/owned-session-worker.test.ts b/packages/coding-agent/test/owned-session-worker.test.tsindex 68318a17a3..11d8777c8e 100644--- a/packages/coding-agent/test/owned-session-worker.test.ts+++ b/packages/coding-agent/test/owned-session-worker.test.ts@@ -1,4 +1,5 @@import { describe, expect, it } from "vitest";+import { PUBLIC_COMMAND_NAMES } from "../src/cli/command-registry.js";import {classifyOwnedSessionWorkerInvocation,createOwnedWorkerLaunchSpec,@@ -21,7 +22,12 @@ describe("owned session worker CLI routing", () => {expect(classifyOwnedSessionWorkerInvocation(["--version"], false, {})).toBeUndefined();expect(classifyOwnedSessionWorkerInvocation(["--list-models"], false, {})).toBeUndefined();expect(classifyOwnedSessionWorkerInvocation(["--export", "session.jsonl"], false, {})).toBeUndefined();+ expect(classifyOwnedSessionWorkerInvocation(["help"], false, {})).toBeUndefined();+ expect(classifyOwnedSessionWorkerInvocation(["help", "me", "fix", "this"], false, {})).toBe("print");expect(classifyOwnedSessionWorkerInvocation(["daemon", "list"], false, {})).toBeUndefined();+ for (const command of PUBLIC_COMMAND_NAMES) {+ expect(classifyOwnedSessionWorkerInvocation([command], false, {})).toBeUndefined();+ }});it("does not recursively route an owned worker", () => {diff --git a/packages/coding-agent/test/package-command-paths.test.ts b/packages/coding-agent/test/package-command-paths.test.tsindex 2f6a5e3547..594946a3e0 100644--- a/packages/coding-agent/test/package-command-paths.test.ts+++ b/packages/coding-agent/test/package-command-paths.test.ts@@ -22,6 +22,7 @@ describe("package commands", () => {let originalAgentDir: string | undefined;let originalPiPackageDir: string | undefined;let originalPrimeAgentDownloadBaseUrl: string | undefined;+ let originalTmpDir: string | undefined;let originalExitCode: typeof process.exitCode;let originalExecPath: string;@@ -43,10 +44,12 @@ describe("package commands", () => {originalAgentDir = process.env[ENV_AGENT_DIR];originalPiPackageDir = process.env.PI_PACKAGE_DIR;originalPrimeAgentDownloadBaseUrl = process.env.PRIME_AGENT_DOWNLOAD_BASE_URL;+ originalTmpDir = process.env.TMPDIR;originalExitCode = process.exitCode;originalExecPath = process.execPath;process.exitCode = undefined;process.env[ENV_AGENT_DIR] = agentDir;+ process.env.TMPDIR = tempDir;process.chdir(projectDir);});@@ -57,6 +60,7 @@ describe("package commands", () => {restoreEnv(ENV_AGENT_DIR, originalAgentDir);restoreEnv("PI_PACKAGE_DIR", originalPiPackageDir);restoreEnv("PRIME_AGENT_DOWNLOAD_BASE_URL", originalPrimeAgentDownloadBaseUrl);+ restoreEnv("TMPDIR", originalTmpDir);Object.defineProperty(process, "execPath", { value: originalExecPath, configurable: true });rmSync(tempDir, { recursive: true, force: true });});@@ -65,7 +69,7 @@ describe("package commands", () => {const relativePkgDir = join(projectDir, "packages", "local-package");mkdirSync(relativePkgDir, { recursive: true });- await main(["install", "./packages/local-package"]);+ await main(["package", "install", "./packages/local-package"]);const settingsPath = join(agentDir, "settings.json");const settings = JSON.parse(readFileSync(settingsPath, "utf-8")) as { packages?: string[] };@@ -76,13 +80,13 @@ describe("package commands", () => {});it("should remove local packages using a path with a trailing slash", async () => {- await main(["install", `${packageDir}/`]);+ await main(["package", "install", `${packageDir}/`]);const settingsPath = join(agentDir, "settings.json");const installedSettings = JSON.parse(readFileSync(settingsPath, "utf-8")) as { packages?: string[] };expect(installedSettings.packages?.length).toBe(1);- await main(["remove", `${packageDir}/`]);+ await main(["package", "remove", `${packageDir}/`]);const removedSettings = JSON.parse(readFileSync(settingsPath, "utf-8")) as { packages?: string[] };expect(removedSettings.packages ?? []).toHaveLength(0);@@ -93,11 +97,11 @@ describe("package commands", () => {const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});try {- await expect(main(["install", "--help"])).resolves.toBeUndefined();+ await expect(main(["package", "install", "--help"])).resolves.toBeUndefined();const stdout = logSpy.mock.calls.map(([message]) => String(message)).join("\n");expect(stdout).toContain("Usage:");- expect(stdout).toContain(`${APP_NAME} install <source> [-l]`);+ expect(stdout).toContain(`${APP_NAME} package install <source> [--local]`);expect(errorSpy).not.toHaveBeenCalled();expect(process.exitCode).toBeUndefined();} finally {@@ -110,11 +114,41 @@ describe("package commands", () => {const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});try {- await expect(main(["install", "--unknown"])).resolves.toBeUndefined();+ await expect(main(["package", "install", "--unknown"])).resolves.toBeUndefined();const stderr = errorSpy.mock.calls.map(([message]) => String(message)).join("\n");expect(stderr).toContain('Unknown option --unknown for "install".');- expect(stderr).toContain(`Use "${APP_NAME} --help" or "${APP_NAME} install <source> [-l]".`);+ expect(stderr).toContain(`Use "${APP_NAME} --help" or "${APP_NAME} package install <source> [--local]".`);+ expect(process.exitCode).toBe(1);+ } finally {+ errorSpy.mockRestore();+ }+ });++ it("directs the removed -l package option to --local", async () => {+ const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});++ try {+ await expect(main(["package", "install", packageDir, "-l"])).resolves.toBeUndefined();++ const stderr = errorSpy.mock.calls.map(([message]) => String(message)).join("\n");+ expect(stderr).toContain('Option -l was removed. Use "--local".');+ expect(process.exitCode).toBe(1);+ expect(existsSync(join(agentDir, "settings.json"))).toBe(false);+ } finally {+ errorSpy.mockRestore();+ }+ });++ it("treats -l as an unknown option for package update", async () => {+ const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});++ try {+ await expect(main(["package", "update", "-l"])).resolves.toBeUndefined();++ const stderr = errorSpy.mock.calls.map(([message]) => String(message)).join("\n");+ expect(stderr).toContain('Unknown option -l for "update".');+ expect(stderr).not.toContain('Use "--local".');expect(process.exitCode).toBe(1);} finally {errorSpy.mockRestore();@@ -125,11 +159,11 @@ describe("package commands", () => {const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});try {- await expect(main(["install"])).resolves.toBeUndefined();+ await expect(main(["package", "install"])).resolves.toBeUndefined();const stderr = errorSpy.mock.calls.map(([message]) => String(message)).join("\n");expect(stderr).toContain("Missing install source.");- expect(stderr).toContain(`Usage: ${APP_NAME} install <source> [-l]`);+ expect(stderr).toContain(`Usage: ${APP_NAME} package install <source> [--local]`);expect(stderr).not.toContain("at ");expect(process.exitCode).toBe(1);} finally {@@ -173,7 +207,7 @@ else fs.writeFileSync(${JSON.stringify(recordPath)},JSON.stringify(args));const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});try {- await expect(main(["update", "--self", "--force"])).resolves.toBeUndefined();+ await expect(main(["update", "--force"])).resolves.toBeUndefined();expect(process.exitCode).toBeUndefined();expect(errorSpy).not.toHaveBeenCalled();@@ -217,7 +251,7 @@ else fs.writeFileSync(${JSON.stringify(recordPath)},JSON.stringify(args));const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});try {- await expect(main(["update", "--self"])).resolves.toBeUndefined();+ await expect(main(["update"])).resolves.toBeUndefined();expect(process.exitCode).toBeUndefined();expect(errorSpy).not.toHaveBeenCalled();@@ -266,7 +300,7 @@ else {const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});try {- await expect(main(["update", "--self"])).resolves.toBeUndefined();+ await expect(main(["update"])).resolves.toBeUndefined();expect(process.exitCode).toBeUndefined();expect(errorSpy).not.toHaveBeenCalled();@@ -319,7 +353,7 @@ else {const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});try {- await expect(main(["update", "--self"])).resolves.toBeUndefined();+ await expect(main(["update"])).resolves.toBeUndefined();expect(process.exitCode).toBeUndefined();expect(errorSpy).not.toHaveBeenCalled();@@ -373,7 +407,7 @@ else fs.writeFileSync(${JSON.stringify(recordPath)},JSON.stringify(args));const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});try {- await expect(main(["update", "--self"])).resolves.toBeUndefined();+ await expect(main(["update"])).resolves.toBeUndefined();expect(process.exitCode).toBeUndefined();expect(errorSpy).not.toHaveBeenCalled();@@ -423,7 +457,7 @@ if(args.includes("install")) process.exit(23);const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});try {- await expect(main(["update", "--self"])).resolves.toBeUndefined();+ await expect(main(["update"])).resolves.toBeUndefined();expect(process.exitCode).toBe(1);const stdout = logSpy.mock.calls.map(([message]) => String(message)).join("\n");@@ -449,7 +483,7 @@ if(args.includes("install")) process.exit(23);const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});try {- await expect(main(["update", "pi-formatter"])).resolves.toBeUndefined();+ await expect(main(["package", "update", "pi-formatter"])).resolves.toBeUndefined();const stderr = errorSpy.mock.calls.map(([message]) => String(message)).join("\n");const stdout = logSpy.mock.calls.map(([message]) => String(message)).join("\n");diff --git a/packages/coding-agent/test/public-command.test.ts b/packages/coding-agent/test/public-command.test.tsnew file mode 100644index 0000000000..a28a67b407--- /dev/null+++ b/packages/coding-agent/test/public-command.test.ts@@ -0,0 +1,283 @@+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";++const mocks = vi.hoisted(() => ({+ daemonCommands: [] as string[][],+ packageCommands: [] as string[][],+ psCalls: [] as boolean[],+ reapCalls: [] as Array<[boolean, boolean]>,+ shutdownCalls: [] as Array<[boolean, boolean]>,+}));++vi.mock("../src/cli/daemon-command.js", () => ({+ handleDaemonCommand: async (args: string[]) => {+ mocks.daemonCommands.push(args);+ return true;+ },+}));++vi.mock("../src/package-manager-cli.js", () => ({+ handlePackageCommand: async (args: string[]) => {+ mocks.packageCommands.push(args);+ return true;+ },+ isSelfUpdateSource: (source: string) => source === "self" || source === "pi" || source === "prime-agent",+}));++vi.mock("../src/cli/daemon-ps.js", () => ({+ runPs: async (json: boolean) => {+ mocks.psCalls.push(json);+ },+ runReap: async (json: boolean, force: boolean) => {+ mocks.reapCalls.push([json, force]);+ },+ runShutdownAll: async (json: boolean, force: boolean) => {+ mocks.shutdownCalls.push([json, force]);+ },+}));++import { INTERNAL_RUNTIME_COMMAND_MARKER } from "../src/cli/args.js";+import { formatTopLevelHelp } from "../src/cli/command-registry.js";+import { handlePublicCommand } from "../src/cli/public-command.js";++describe("public command routing", () => {+ beforeEach(() => {+ mocks.daemonCommands.length = 0;+ mocks.packageCommands.length = 0;+ mocks.psCalls.length = 0;+ mocks.reapCalls.length = 0;+ mocks.shutdownCalls.length = 0;+ process.exitCode = undefined;+ vi.spyOn(console, "log").mockImplementation(() => {});+ vi.spyOn(console, "error").mockImplementation(() => {});+ });++ afterEach(() => {+ process.exitCode = undefined;+ vi.restoreAllMocks();+ });++ it("rewrites attach into the normal interactive resume path", async () => {+ await expect(handlePublicCommand(["attach", "worker"])).resolves.toEqual({+ handled: false,+ args: ["--resume", "worker"],+ explicitAgentsView: false,+ attachAgent: "worker",+ });+ });++ it("forwards global options when attaching", async () => {+ await expect(handlePublicCommand(["attach", "worker", "--verbose", "--provider", "anthropic"])).resolves.toEqual({+ handled: false,+ args: ["--resume", "worker", "--verbose", "--provider", "anthropic"],+ explicitAgentsView: false,+ attachAgent: "worker",+ });+ });++ it("rejects extra attach operands", async () => {+ await expect(handlePublicCommand(["attach", "worker", "extra"])).resolves.toMatchObject({ handled: true });+ expect(process.exitCode).toBe(1);+ expect(console.error).toHaveBeenCalledWith(expect.stringContaining("prime-agent attach <agent>"));+ });++ it("rejects conflicting session selectors when attaching", async () => {+ for (const selector of [["--resume", "other"], ["-r", "other"], ["--continue"], ["--fork", "session.jsonl"]]) {+ await expect(handlePublicCommand(["attach", "worker", ...selector])).resolves.toMatchObject({ handled: true });+ }+ expect(process.exitCode).toBe(1);+ expect(console.error).toHaveBeenCalledWith(expect.stringContaining("cannot be combined"));+ });++ it("forwards global options when opening the agents view", async () => {+ await expect(handlePublicCommand(["agents", "--verbose", "--provider", "anthropic"])).resolves.toEqual({+ handled: false,+ args: ["--verbose", "--provider", "anthropic"],+ explicitAgentsView: true,+ });+ });++ it("routes agent operations through the internal protocol adapter", async () => {+ await expect(handlePublicCommand(["list", "--all", "--json"])).resolves.toMatchObject({ handled: true });+ expect(mocks.daemonCommands).toEqual([["daemon", "list", "--all", "--json"]]);+ });++ it("separates Prime Agent updates from package updates", async () => {+ await handlePublicCommand(["update", "--force"]);+ await handlePublicCommand(["package", "update"]);+ await handlePublicCommand(["package", "update", "npm:@example/tools"]);++ expect(mocks.packageCommands).toEqual([+ ["update", "--self", "--force"],+ ["update", "--extensions"],+ ["update", "npm:@example/tools"],+ ]);+ });++ it("gives legacy update targets explicit migration guidance", async () => {+ for (const target of ["self", "--self", "prime-agent"]) {+ await handlePublicCommand(["update", target]);+ }++ expect(mocks.packageCommands).toEqual([]);+ expect(console.error).toHaveBeenCalledWith(expect.stringContaining('Use "prime-agent update [--force]"'));+ });++ it("directs legacy package-update forms to the package command", async () => {+ await handlePublicCommand(["update", "npm:@example/tools"]);+ await handlePublicCommand(["update", "--extensions"]);+ await handlePublicCommand(["update", "--extension", "npm:@example/tools"]);++ expect(mocks.packageCommands).toEqual([]);+ expect(console.error).toHaveBeenCalledWith(expect.stringContaining('Use "prime-agent package update [source]"'));+ });++ it("explains that combined legacy updates are now separate", async () => {+ await handlePublicCommand(["update", "--self", "--extensions"]);++ expect(mocks.packageCommands).toEqual([]);+ expect(console.error).toHaveBeenCalledWith(expect.stringContaining("separately"));+ });++ it("rejects self-update aliases on the package update path", async () => {+ for (const source of ["self", "pi", "prime-agent"]) {+ await handlePublicCommand(["package", "update", source]);+ }++ expect(mocks.packageCommands).toEqual([]);+ expect(console.error).toHaveBeenCalledWith(expect.stringContaining('Use "prime-agent update"'));+ });++ it("directs package uninstall to package remove", async () => {+ await handlePublicCommand(["package", "uninstall", "npm:@example/tools"]);++ expect(mocks.packageCommands).toEqual([]);+ expect(console.error).toHaveBeenCalledWith(expect.stringContaining('Use "prime-agent package remove"'));+ expect(console.error).not.toHaveBeenCalledWith(expect.stringContaining("package install"));+ });++ it("maps model listing and session export to the existing runtime flags", async () => {+ await expect(handlePublicCommand(["model", "list", "sonnet"])).resolves.toMatchObject({+ handled: false,+ args: [INTERNAL_RUNTIME_COMMAND_MARKER, "--list-models", "sonnet"],+ });+ await expect(handlePublicCommand(["session", "export", "session.jsonl", "session.html"])).resolves.toMatchObject({+ handled: false,+ args: [INTERNAL_RUNTIME_COMMAND_MARKER, "--export", "session.jsonl", "session.html"],+ });+ });++ it("preserves trailing global options for model listing and session export", async () => {+ await expect(handlePublicCommand(["model", "list", "sonnet", "--offline"])).resolves.toMatchObject({+ handled: false,+ args: [INTERNAL_RUNTIME_COMMAND_MARKER, "--list-models", "sonnet", "--offline"],+ });+ await expect(+ handlePublicCommand(["session", "export", "session.jsonl", "session.html", "--verbose"]),+ ).resolves.toMatchObject({+ handled: false,+ args: [INTERNAL_RUNTIME_COMMAND_MARKER, "--export", "session.jsonl", "session.html", "--verbose"],+ });+ });++ it("rejects operands for package list", async () => {+ await handlePublicCommand(["package", "list", "ignored-source"]);++ expect(mocks.packageCommands).toEqual([]);+ expect(console.error).toHaveBeenCalledWith(expect.stringContaining("prime-agent package list"));+ });++ it("uses force only when explicitly requested for full shutdown", async () => {+ await handlePublicCommand(["shutdown", "--json"]);+ await handlePublicCommand(["shutdown", "--force"]);+ expect(mocks.shutdownCalls).toEqual([+ [true, false],+ [false, true],+ ]);+ });++ it("routes doctor fixes through the safe cleanup path", async () => {+ await handlePublicCommand(["doctor", "--fix", "--json"]);+ expect(mocks.reapCalls).toEqual([[true, false]]);+ });++ it("rejects the old daemon hierarchy with migration guidance", async () => {+ await expect(handlePublicCommand(["daemon", "list"])).resolves.toMatchObject({ handled: true });+ expect(process.exitCode).toBe(1);+ expect(console.error).toHaveBeenCalledWith(expect.stringContaining('Run "prime-agent help"'));+ });++ it("shows migration guidance when help targets removed commands", async () => {+ const cases: Array<[path: string[], hint: string]> = [+ [["daemon"], 'Run "prime-agent help"'],+ [["install"], 'Use "prime-agent package install"'],+ [["remove"], 'Use "prime-agent package remove"'],+ [["uninstall"], 'Use "prime-agent package remove"'],+ [["manage"], 'Use "prime-agent agents"'],+ [["app", "update"], 'Use "prime-agent update"'],+ ];++ for (const [path, hint] of cases) {+ await expect(handlePublicCommand(["help", ...path])).resolves.toMatchObject({ handled: true });+ expect(console.error).toHaveBeenCalledWith(expect.stringContaining(hint));+ }+ expect(process.exitCode).toBe(1);+ expect(console.log).not.toHaveBeenCalled();+ });++ it("suggests close nested commands without executing them", async () => {+ await handlePublicCommand(["schedule", "cancell", "job-1"]);+ expect(mocks.daemonCommands).toEqual([]);+ expect(console.error).toHaveBeenCalledWith(expect.stringContaining("schedule cancel"));+ });++ it("treats help-like message text after the separator literally", async () => {+ await handlePublicCommand(["send", "worker", "--", "--help"]);+ expect(mocks.daemonCommands).toEqual([["daemon", "send", "worker", "--", "--help"]]);+ });++ it("leaves natural-language prompts beginning with help on the prompt path", async () => {+ const args = ["help", "me", "fix", "this"];+ await expect(handlePublicCommand(args)).resolves.toEqual({+ handled: false,+ args,+ explicitAgentsView: false,+ });+ });++ it("rejects invalid paths below a known help command", async () => {+ await handlePublicCommand(["help", "schedule", "nonsense"]);++ expect(process.exitCode).toBe(1);+ expect(console.error).toHaveBeenCalledWith(expect.stringContaining("Unknown command: schedule nonsense"));+ });++ it("shows command help when options precede the help flag", async () => {+ await handlePublicCommand(["list", "--all", "--help"]);+ await handlePublicCommand(["doctor", "--fix", "--help"]);+ await handlePublicCommand(["package", "install", "--local", "--help"]);++ expect(console.log).toHaveBeenNthCalledWith(1, expect.stringContaining("prime-agent list [--all] [--json]"));+ expect(console.log).toHaveBeenNthCalledWith(2, expect.stringContaining("prime-agent doctor [--fix] [--json]"));+ expect(console.log).toHaveBeenNthCalledWith(3, expect.stringContaining("prime-agent package install <source>"));+ expect(console.error).not.toHaveBeenCalled();+ });++ it("leaves top-level help flags on the full CLI help path", async () => {+ await expect(handlePublicCommand(["--help"])).resolves.toEqual({+ handled: false,+ args: ["--help"],+ explicitAgentsView: false,+ });+ await expect(handlePublicCommand(["-h"])).resolves.toEqual({+ handled: false,+ args: ["-h"],+ explicitAgentsView: false,+ });+ });++ it("keeps daemon terminology out of public help", () => {+ const help = formatTopLevelHelp();+ expect(help).toContain("shutdown");+ expect(help).not.toContain("daemon");+ });+});diff --git a/packages/coding-agent/test/suite/regressions/4603-worker-recovery.test.ts b/packages/coding-agent/test/suite/regressions/4603-worker-recovery.test.tsindex c7d824ab61..48e99e71fc 100644--- a/packages/coding-agent/test/suite/regressions/4603-worker-recovery.test.ts+++ b/packages/coding-agent/test/suite/regressions/4603-worker-recovery.test.ts@@ -986,7 +986,7 @@ describe("ENG-4603 worker recovery convergence", () => {}}, 15_000);- it("shutdown --all removes hidden supervisors and workers without changing CLI contracts", async () => {+ it("shutdown --force removes hidden supervisors and workers through the public CLI", async () => {if (process.platform === "win32") return;const paths = await createPaths();const predecessor = spawnSupervisor(paths);@@ -1026,7 +1026,7 @@ describe("ENG-4603 worker recovery convergence", () => {expect(listenersBeforeShutdown).toContain(`p${predecessor.child.pid}`);expect(listenersBeforeShutdown).toContain(`p${successor.child.pid}`);- const shutdown = await runCli(paths, ["daemon", "shutdown", "--all", "--json"], 60_000, lsofEnvironment);+ const shutdown = await runCli(paths, ["shutdown", "--force", "--json"], 60_000, lsofEnvironment);expect(shutdown.code).toBe(0);const shutdownResult = JSON.parse(shutdown.stdout) as { stopped: unknown[]; failed: unknown[] };const survivingIdentities = [@@ -1047,9 +1047,9 @@ describe("ENG-4603 worker recovery convergence", () => {expect(exactProcessIsAlive(workerPid, workerStartId)).toBe(false);const contracts = [- { args: ["daemon", "ps", "--json"], json: [] },- { args: ["daemon", "ps", "--reap", "--json"], json: { reaped: [], skipped: [] } },- { args: ["daemon", "shutdown", "--all", "--json"], json: { stopped: [], failed: [] } },+ { args: ["status", "--json"], json: [] },+ { args: ["doctor", "--fix", "--json"], json: { reaped: [], skipped: [] } },+ { args: ["shutdown", "--force", "--json"], json: { stopped: [], failed: [] } },];for (const contract of contracts) {const result = await runCli(paths, contract.args, 60_000, lsofEnvironment);@@ -1058,14 +1058,10 @@ describe("ENG-4603 worker recovery convergence", () => {}expect(JSON.parse(result.stdout)).toEqual(contract.json);}- for (const args of [- ["daemon", "ps"],- ["daemon", "ps", "--reap"],- ["daemon", "shutdown", "--all"],- ]) {+ for (const args of [["status"], ["doctor", "--fix"], ["shutdown", "--force"]]) {const result = await runCli(paths, args, 60_000, lsofEnvironment);expect(result.code).toBe(0);- expect(result.stdout).toBe("No daemons found.\n");+ expect(result.stdout).toBe("No background services found.\n");}}, 150_000);});