@interf/compiler 0.13.0 → 0.16.0

package/README.md

@@ -152,6 +152,43 @@ When the first compile run still misses readiness checks, Interf edits the Metho
 
 Interf saves every readiness-check run inside the preparation's portable context under `.interf/tests/`. You can inspect what changed and why a later compile run did better.
 
+## How Interf Compiles
+
+You don't need to think about roles. By default Interf uses your active agent for every stage of every compile run, the same way 0.14 did. Roles are available for advanced users who want different agents per stage; defaults are good and stable.
+
+Interf treats connected agents as a first-class primitive and uses a small role taxonomy internally to route stages between them. The default behavior is single-active-agent — one installed agent runs everything — but you can opt into per-role specialization without changing any Method.
+
+```text
+Connected agents             Role map (per-instance)
+  claude-code (active)         extractor   → claude-code
+  codex                        summarizer  → claude-code
+  pdf-extract (custom)         structurer  → claude-code
+                               verifier    → claude-code
+                               general     → claude-code
+
+A Method compile run
+  for each stage in the Method
+    look up the stage's role in the role map
+    invoke the mapped agent on the prepared shell
+    record which agent ran which stage
+```
+
+Methods declare an optional `role` per stage — one of `extractor`, `summarizer`, `structurer`, `verifier`, or `general`. Custom role names are allowed; unknown roles fall through to `general`.
+
+The role map lives in `~/.interf/agents.json`. On a fresh install with one agent installed, every role maps to that agent and you get the same single-active-agent behavior 0.14 had. To change which agent runs which role:
+
+```bash
+interf agents ls
+interf agents register opencode --command "opencode --prompt"
+interf agents map structurer codex
+interf agents use claude-code   # set the active agent
+interf agents unmap structurer  # fall back to active
+```
+
+Or use the **Agents** tab in Interf Compiler UI. Either surface mutates the same `~/.interf/agents.json` through the local service.
+
+Verify runs always resolve to the `verifier` role. Method-authoring runs ask the authoring agent to propose a `role` per stage based on the prompt content; missing roles default to `general`.
+
 ## How the Pieces Fit
 
 The instance owns preparation state. A preparation declares a source binding (`{ kind: "local-folder", locator: <path> }`) and a method id; the instance stores its config at `~/.interf/preparations/<prep-id>/config.json` and writes portable context to `~/.interf/preparations/<prep-id>/portable-context/`. A compile run processes the selected source files and produces the artifact locator the API returns. `interf test` checks Source Folder files and portable context against the same readiness checks.
@@ -160,6 +197,8 @@ Readiness is one `ready` / `not ready` status, not a separate score. Interf buil
 
 `interf web` runs the local Interf instance and serves Interf Compiler UI. The UI reads local-service resources: Source Files, Methods, runs, stages, proof, artifacts, readiness checks, and whether portable context is `ready` or `not ready`. It renders local instance state; it does not own compiler, Method, or readiness semantics.
 
+Everywhere Interf shows a resource — Source Folder, portable context, Method files, run artifacts — the API returns a single locator shape: `{ kind, value }`. `local-path` means the engine has filesystem access to the same host as the user; `remote-url` is a signed URL the UI opens in a browser tab; `api-served` is a relative API route the UI fetches and renders inline. Local engines today return `local-path`; the same shape carries forward unchanged when a remote instance fronts the API.
+
 ## CLI Connection
 
 The CLI is a thin authorized client of one connected instance. It carries one piece of state — `~/.interf/connection.json`:
@@ -247,6 +286,7 @@ A maintained public test example uses this preparation:
 - `interf compile <prep-id>` — build portable context, returns the artifact locator
 - `interf test <prep-id>` — run readiness checks against source files and/or portable context
 - `interf method ls / install / draft / improve` — manage Method packages
+- `interf agents ls / use / register / unregister / map / unmap` — manage connected agents and the role map
 - `interf runs ls / status / watch / cancel / fetch` — inspect runs
 - `interf login / logout` — manage `~/.interf/connection.json` (remote backend ships in a future release)
 - `interf status` — show the active connection and a preparation summary

package/agent-skills/interf-actions/SKILL.md

@@ -61,6 +61,21 @@ interf login --url <…>  # remote: writes connection.json
    interf method improve <prep-id>
    ```
 
+## Connected agents and the role map
+
+Interf treats the agents it can shell out to (Claude Code, Codex, custom CLIs) as a first-class primitive. `GET /v1/instance` reports `agent_count` and `default_agent`; if `agent_count` is `0`, **`interf compile` and `interf verify` will hard-error** — install one or register a custom CLI before retrying.
+
+```sh
+interf agents ls                                       # list registered + detected agents
+interf agents use <name>                               # set the active agent (sweeps role map)
+interf agents register <name> --command "<cmd>"        # register a custom CLI
+interf agents unregister <name>                        # remove a custom CLI
+interf agents map <role> <agent>                       # pin a role to an agent
+interf agents unmap <role>                             # fall back to the active agent
+```
+
+Roles are: `extractor`, `summarizer`, `structurer`, `verifier`, `general` (Methods may declare custom names; the engine treats unknown roles as `general`). Default behavior is single-active-agent — every role maps to the same agent — so existing agent flows do not change unless the user opts into per-role specialization.
+
 ## Agent contract — flags every CLI run uses
 
 | Flag | What it controls | When the agent passes it |
@@ -82,6 +97,41 @@ interf login --url <…>  # remote: writes connection.json
 - Propose the command first and wait for approval before running commands that write files, start runs, create Method packages, build portable context, or run readiness checks.
 - If the request is ambiguous, ask one concise clarification instead of guessing.
 
+## Show your work — always print the run URL
+
+Interf Compiler UI is the user's verification surface. The agent does
+the work; the user clicks a URL to see live trace, events, readiness,
+and proof. **Whenever you kick off a run, print a deep-link to the run
+page in the same message as the run id.** The user should never have
+to navigate the UI manually to find what you just started.
+
+The base URL is whatever `interf status` reports as the connected
+instance (e.g. `http://127.0.0.1:4873` for a local engine,
+`https://api.interf.cloud/...` for cloud). Append query params:
+
+| Param | Value |
+|---|---|
+| `preparation` | the preparation id |
+| `run` | the run id returned by the CLI |
+| `runTab` | optional: `trace` (default), `events`, or `readiness` |
+
+**Example output after `interf compile serge`:**
+
+```text
+Started compile run compile_8x2abc...
+Watch live: http://127.0.0.1:4873/?preparation=serge&run=compile_8x2abc...
+
+I'll check status in a moment with `interf runs status compile_8x2abc...`.
+```
+
+The same pattern applies to verify, method-improvement, and method-authoring
+runs. When a run finishes, print the same URL with `runTab=readiness` so the
+user can click through to the readiness summary.
+
+The agent stays the executor; the URL is the user's "I can see what's
+happening" handle. It also makes failures self-explanatory — when a run
+errors, the user clicks through to the same trace the agent is reading.
+
 ## Reading the artifact locator
 
 `interf compile <prep-id>` prints a short multi-line block by default. The portable-context locator looks like one of:
@@ -111,11 +161,7 @@ Use these action types:
 
 Use `compile` when the user asks to prepare, build, or refresh portable context. Set `method` to the Method id and, if the request named one, `preparation` to the preparation id. CLI equivalent: `interf compile --method`.
 
-For a readiness-check proposal, set `values.mode` to:
-
-- `source-files` for source files only
-- `compiled` for portable context only
-- `both` for source files and portable context
+Readiness-check proposals always run against the compiled portable context in 0.15+. The legacy `values.mode` field is gone — omit it from `test` proposals.
 
 Return this shape:
 

package/agent-skills/interf-actions/references/cli.md

@@ -9,19 +9,21 @@ This snapshot is bundled with the `interf-actions` skill. The installed `interf`
 ```text
 interf
 
+Open the interactive wizard (default when no subcommand is given)
+
 Commands:
-  interf init                 Set up Interf or open the Preparation wizard
-  interf compile              Prepare files and write Portable Context agents can use
-  interf test                 Run readiness checks against source files and Portable Context
-  interf create [type]        Create a Preparation or reusable Method
+  interf                      Open the interactive wizard (default when no subcommand is given)                                                        [default]
+  interf init                 Open the interactive wizard
+  interf compile <prep-id>    Start a compile run for a preparation
+  interf verify <prep-id>     Verify a preparation's claim-checks against its portable context
+  interf agents <subcommand>  Manage connected agents and role mapping
   interf doctor               Check local executor configuration before a real local run
-  interf list                 List saved Preparations in this Source Folder
-  interf list-methods         List Methods available in this Source Folder (built-in + local drafts)
-  interf method <subcommand>  Manage Methods in your user library (install, publish, remove, list)
-  interf runs <subcommand>    Inspect, fetch, or cancel compile runs (status, watch, list, fetch, cancel)
-  interf status               Show deterministic health for the Portable Context agents use
-  interf web [subcommand]     Open Interf Compiler UI; manage the engine instance for this Workspace
-  interf reset <scope>        Reset generated Portable Context state while keeping source files and the local Method package
+  interf method <subcommand>  Manage methods on the connected instance
+  interf mcp                  Run the Interf Model Context Protocol server (stdio by default).
+  interf runs <subcommand>    Inspect runs on the connected instance
+  interf status               Show connection + preparation summary
+  interf web [subcommand]     Start / stop / inspect the Interf engine
+  interf reset <prep-id>      Reset a preparation's compile output
   interf prep <subcommand>    Manage preparations on the connected instance
   interf login                Set the active Interf instance connection (URL + optional bearer token)
   interf logout               Clear the active Interf instance connection
@@ -29,6 +31,8 @@ Commands:
 Options:
   --help     Show help                                                                                                                                 [boolean]
   --version  Show version number                                                                                                                       [boolean]
+  --url      Override the active connection URL                                                                                                         [string]
+  --token    Override the active bearer token                                                                                                           [string]
 ```
 
 ## interf web
@@ -36,23 +40,18 @@ Options:
 ```text
 interf web [subcommand]
 
-Open Interf Compiler UI; manage the engine instance for this Workspace
+Start / stop / inspect the Interf engine
 
 Commands:
-  interf web stop    Deregister this workspace from the engine instance (and shut it down if last)
-  interf web status  Show engine-instance status: registered workspaces, active runs, idle time
-  interf web         Start (or attach to) the engine instance for this Workspace and open Interf Compiler UI. Other CLI commands auto-start this in the backgrou
-                     nd — running it explicitly is only needed for the UI.                                                                             [default]
+  interf web stop    Stop the connected engine
+  interf web status  Show engine status via the connected URL
+  interf web         Start the engine in the foreground (default)                                                                                      [default]
 
 Options:
-  --help           Show help                                                                                                                           [boolean]
-  --version        Show version number                                                                                                                 [boolean]
-  --host           Host for the local Interf service (only when starting a fresh instance)                                                              [string]
-  --port           Port for the local Interf service (only when starting a fresh instance)                                                              [number]
-  --control-path   Folder where Interf stores local config, Methods, runs, and portable context                                                         [string]
-  --source-folder  Source Folder to prepare when initializing a new Interf Workspace                                                                    [string]
-  --background     Run as the detached background instance the auto-bootstrap path uses; suppresses interactive hints. Set INTERF_WEB_NO_AUTOSTART=1 to disable
-                   auto-start.                                                                                                        [boolean] [default: false]
+  --help     Show help                                                                                                                                 [boolean]
+  --version  Show version number                                                                                                                       [boolean]
+  --host     Host to bind                                                                                                        [string] [default: "127.0.0.1"]
+  --port     Port to bind                                                                                                               [number] [default: 4873]
 ```
 
 ## interf prep
@@ -63,10 +62,11 @@ interf prep <subcommand>
 Manage preparations on the connected instance
 
 Commands:
-  interf prep ls                List preparations
-  interf prep create <prep-id>  Create a preparation
-  interf prep show <prep-id>    Show a preparation's full record
-  interf prep rm <prep-id>      Delete a preparation
+  interf prep ls                                List preparations
+  interf prep create <prep-id>                  Create a preparation (method binding optional — set later if you don't have one yet)
+  interf prep set-method <prep-id> <method-id>  Bind a method to a preparation (or change which method it uses)
+  interf prep show <prep-id>                    Show a preparation's full record
+  interf prep rm <prep-id>                      Delete a preparation
 
 Options:
   --help     Show help                                                                                                                                 [boolean]
@@ -78,45 +78,38 @@ Options:
 ## interf compile
 
 ```text
-interf compile
+interf compile <prep-id>
+
+Start a compile run for a preparation
 
-Prepare files and write Portable Context agents can use
+Positionals:
+  prep-id  Preparation id                                                                                                                    [string] [required]
 
 Options:
-  --help               Show help                                                                                                                       [boolean]
-  --version            Show version number                                                                                                             [boolean]
-  --method             Method id to compile against this Source Folder. Resolves to the saved Preparation that uses this Method, or asks if more than one bindin
-                       g exists.                                                                                                                        [string]
-  --preparation        Saved Preparation id to compile (advanced; use --method for the Method-first form).                                              [string]
-  --max-attempts       Retry the compile run and run saved readiness checks with the same Method until the Preparation is ready or reaches this total attempt li
-                       mit                                                                                                                              [number]
-  --max-loops          After retries fail, let Interf edit the Method and run saved readiness checks on new Method variations for this Preparation up to this lo
-                       op limit                                                                                                                         [number]
-  --keep-stage-shells  Keep every executed stage shell under .interf/runtime/execution-shells for review instead of pruning successful shells
-                                                                                                                                      [boolean] [default: false]
-  --auto-create        When --method has no matching saved Preparation: --auto-create creates one without prompting; --no-auto-create refuses to create. Default
-                       : prompt on TTY, auto-create otherwise.                                                                                         [boolean]
-  --source             Source Folder path the auto-created Preparation should bind to. Relative paths resolve against --workspace. Default: '.'.        [string]
-  --as                 Name to use when auto-creating a Preparation. The portable context lands at <workspace>/<as>/. Default: derived from --method id.[string]
-  --watch              Block until the compile run finishes; tail stage status. Default is async return-with-id (use `interf runs status <id>` to check later).
-                                                                                                                                      [boolean] [default: false]
-  --idempotency-key    Opaque key sent as X-Interf-Idempotency-Key. The local service caches the key for an hour and returns the original run id on retries inst
-                       ead of starting a fresh run.                                                                                                     [string]
+  --help             Show help                                                                                                                         [boolean]
+  --version          Show version number                                                                                                               [boolean]
+  --watch            Stream run events                                                                                                [boolean] [default: false]
+  --quiet            Print only the portable-context locator on success                                                               [boolean] [default: false]
+  --idempotency-key  Client-supplied dedupe key                                                                                                         [string]
+  --url              Override the active connection URL                                                                                                 [string]
+  --token            Override the active bearer token                                                                                                   [string]
 ```
 
-## interf test
+## interf verify
 
 ```text
-interf test
+interf verify <prep-id>
 
-Run readiness checks against source files and Portable Context
+Verify a preparation's claim-checks against its portable context
+
+Positionals:
+  prep-id  Preparation id                                                                                                                    [string] [required]
 
 Options:
-  --help         Show help                                                                                                                             [boolean]
-  --version      Show version number                                                                                                                   [boolean]
-  --preparation  Preparation id to check when this Source Folder has more than one Preparation                                                          [string]
-  --target       Check source files, Portable Context, or both. Default: both when Portable Context exists, otherwise source files.
-                                                                                                           [choices: "both", "source-files", "portable-context"]
+  --help     Show help                                                                                                                                 [boolean]
+  --version  Show version number                                                                                                                       [boolean]
+  --url      Override the active connection URL                                                                                                         [string]
+  --token    Override the active bearer token                                                                                                           [string]
 ```
 
 ## interf method
@@ -124,17 +117,19 @@ Options:
 ```text
 interf method <subcommand>
 
-Manage Methods in your user library (install, publish, remove, list)
+Manage methods on the connected instance
 
 Commands:
-  interf method install <path>  Copy a Method package from a path into your user library at ~/.interf/methods/<id>/
-  interf method publish <id>    Promote a workspace draft Method to your user library at ~/.interf/methods/<id>/
-  interf method remove <id>     Remove a Method from your user library at ~/.interf/methods/<id>/
-  interf method list            List Methods installed in your user library at ~/.interf/methods/
+  interf method ls                 List methods on the instance
+  interf method install <path>     Install a method package from a local folder
+  interf method draft <prep-id>    Start a method-authoring run for a preparation
+  interf method improve <prep-id>  Start a method-improvement run for a preparation
 
 Options:
   --help     Show help                                                                                                                                 [boolean]
   --version  Show version number                                                                                                                       [boolean]
+  --url      Override the active connection URL                                                                                                         [string]
+  --token    Override the active bearer token                                                                                                           [string]
 ```
 
 ## interf runs
@@ -142,18 +137,19 @@ Options:
 ```text
 interf runs <subcommand>
 
-Inspect, fetch, or cancel compile runs (status, watch, list, fetch, cancel)
+Inspect runs on the connected instance
 
 Commands:
-  interf runs status <run-id>  Show the current state of a compile run by id
-  interf runs watch <run-id>   Block until the named compile run finishes; tail stage status
-  interf runs list             List recent compile runs in this Workspace
-  interf runs fetch <run-id>   Copy the portable context produced by a compile run to <abs-path>
-  interf runs cancel <run-id>  Cancel an in-flight compile run
+  interf runs ls               List runs (optionally filtered by preparation)
+  interf runs status <run-id>  Show full record for a run
+  interf runs cancel <run-id>  Cancel a running run
+  interf runs fetch <run-id>   Download a run's portable context
 
 Options:
   --help     Show help                                                                                                                                 [boolean]
   --version  Show version number                                                                                                                       [boolean]
+  --url      Override the active connection URL                                                                                                         [string]
+  --token    Override the active bearer token                                                                                                           [string]
 ```
 
 ## interf runs fetch
@@ -161,16 +157,17 @@ Options:
 ```text
 interf runs fetch <run-id>
 
-Copy the portable context produced by a compile run to <abs-path>
+Download a run's portable context
 
 Positionals:
-  run-id  Compile run id to fetch                                                                                                            [string] [required]
+  run-id  Run id                                                                                                                             [string] [required]
 
 Options:
-  --help       Show help                                                                                                                               [boolean]
-  --version    Show version number                                                                                                                     [boolean]
-  --to         Absolute destination path. Must be empty or non-existent unless --overwrite is set.                                           [string] [required]
-  --overwrite  Allow copying into a destination that already has files.                                                               [boolean] [default: false]
+  --help     Show help                                                                                                                                 [boolean]
+  --version  Show version number                                                                                                                       [boolean]
+  --url      Override the active connection URL                                                                                                         [string]
+  --token    Override the active bearer token                                                                                                           [string]
+  --to       Target path                                                                                                                     [string] [required]
 ```
 
 ## interf status
@@ -178,13 +175,13 @@ Options:
 ```text
 interf status
 
-Show deterministic health for the Portable Context agents use
+Show connection + preparation summary
 
 Options:
-  --help      Show help                                                                                                                                [boolean]
-  --version   Show version number                                                                                                                      [boolean]
-  --watch     Poll the local Interf service for live run status                                                                       [boolean] [default: false]
-  --instance  Show only engine-instance status (workspaces, runs, idle); skip workspace details                                       [boolean] [default: false]
+  --help     Show help                                                                                                                                 [boolean]
+  --version  Show version number                                                                                                                       [boolean]
+  --url      Override the active connection URL                                                                                                         [string]
+  --token    Override the active bearer token                                                                                                           [string]
 ```
 
 ## interf login
@@ -216,16 +213,19 @@ Options:
 ## interf reset
 
 ```text
-interf reset <scope>
+interf reset <prep-id>
 
-Reset generated Portable Context state while keeping source files and the local Method package
+Reset a preparation's compile output
 
 Positionals:
-  scope                                                                                                          [string] [required] [choices: "compile", "all"]
+  prep-id  Preparation id                                                                                                                    [string] [required]
 
 Options:
   --help     Show help                                                                                                                                 [boolean]
   --version  Show version number                                                                                                                       [boolean]
+  --mode     Scope of the reset                                                                        [string] [choices: "compile", "all"] [default: "compile"]
+  --url      Override the active connection URL                                                                                                         [string]
+  --token    Override the active bearer token                                                                                                           [string]
 ```
 
 ## interf doctor

package/dist/cli/commands/agents.d.ts

@@ -0,0 +1,2 @@
+import type { CommandModule } from "yargs";
+export declare const agentsCommand: CommandModule;

package/dist/cli/commands/agents.js

@@ -0,0 +1,213 @@
+/**
+ * `interf agents` — manage connected agents + role mapping.
+ *
+ *   interf agents ls                                # list registered + detected
+ *   interf agents use <name>                        # set active agent
+ *   interf agents register <name> --command <cmd> [--display-name <s>]
+ *   interf agents unregister <name>                 # custom CLIs only
+ *   interf agents map <role> <agent>                # pin a role to an agent
+ *   interf agents unmap <role>                      # clear a role
+ *
+ * All subcommands hit the connected local service. They never touch
+ * `~/.interf/agents.json` directly — the service is the source of truth.
+ */
+import chalk from "chalk";
+import { CONNECT_OR_ERROR_HINT, readActiveConnection, } from "../../packages/engine/connection-config.js";
+function resolveConnection(args) {
+    const conn = readActiveConnection({
+        urlOverride: args.url,
+        authTokenOverride: args.token,
+    });
+    if (!conn) {
+        console.error(CONNECT_OR_ERROR_HINT);
+        process.exit(1);
+    }
+    return { url: conn.url.replace(/\/+$/, ""), token: conn.auth_token };
+}
+async function callJson(url, token, init = {}) {
+    const headers = new Headers(init.headers ?? {});
+    if (token)
+        headers.set("authorization", `Bearer ${token}`);
+    if (init.body && !headers.has("content-type")) {
+        headers.set("content-type", "application/json");
+    }
+    const response = await fetch(url, { ...init, headers });
+    const raw = await response.text();
+    let body = null;
+    if (raw.length > 0) {
+        try {
+            body = JSON.parse(raw);
+        }
+        catch {
+            body = null;
+        }
+    }
+    return { status: response.status, body, raw };
+}
+function formatAgentLine(agent, registry) {
+    const isActive = agent.name === registry.active_agent?.name;
+    const sourceLabel = agent.source === "builtin" ? "builtin" : "user";
+    const activeMarker = isActive ? chalk.green(" (active)") : "";
+    const availabilityMarker = agent.available === false ? chalk.yellow(" (not installed)") : "";
+    return `  ${chalk.bold(agent.name)} ${chalk.dim(`[${sourceLabel}]`)} ${chalk.dim(agent.display_name)} — ${chalk.dim(agent.command)}${activeMarker}${availabilityMarker}`;
+}
+function printRegistry(registry) {
+    if (registry.agents.length === 0) {
+        console.log();
+        console.log(chalk.yellow("  No agents available."));
+        console.log();
+        console.log("  Install Claude Code, Codex, Gemini, or another agent CLI,");
+        console.log("  or register a custom CLI: `interf agents register <name> --command <cmd>`.");
+        console.log();
+        return;
+    }
+    console.log();
+    console.log(chalk.bold("  Connected agents"));
+    for (const agent of registry.agents) {
+        console.log(formatAgentLine(agent, registry));
+    }
+    if (Object.keys(registry.role_map).length > 0) {
+        console.log();
+        console.log(chalk.bold("  Role mapping"));
+        for (const [role, agentName] of Object.entries(registry.role_map)) {
+            console.log(`  ${chalk.bold(role.padEnd(11))} → ${agentName}`);
+        }
+    }
+    console.log();
+}
+export const agentsCommand = {
+    command: "agents <subcommand>",
+    describe: "Manage connected agents and role mapping",
+    builder: (yargs) => yargs
+        .option("url", { type: "string", describe: "Override the active connection URL" })
+        .option("token", { type: "string", describe: "Override the active bearer token" })
+        .command("ls", "List registered + detected agents", (y) => y, async (args) => {
+        const { url, token } = resolveConnection(args);
+        const { status, body, raw } = await callJson(`${url}/v1/agents`, token);
+        if (status !== 200 || !body) {
+            console.error(chalk.red(`Failed to list agents (HTTP ${status}).`));
+            if (raw)
+                console.error(raw);
+            process.exit(1);
+        }
+        printRegistry(body);
+    })
+        .command("use <name>", "Set the active agent (mirrors to role_map.general + sweeps roles still on the prior active)", (y) => y.positional("name", {
+        type: "string",
+        demandOption: true,
+        describe: "Agent name (e.g. claude-code, codex, opencode)",
+    }), async (args) => {
+        const { url, token } = resolveConnection(args);
+        const { status, body, raw } = await callJson(`${url}/v1/executor`, token, {
+            method: "POST",
+            body: JSON.stringify({ agent: args.name }),
+        });
+        if (status !== 200 && status !== 202) {
+            console.error(chalk.red(`Failed to set active agent (HTTP ${status}).`));
+            if (raw)
+                console.error(raw);
+            process.exit(1);
+        }
+        const display = body?.executor?.display_name ?? args.name;
+        console.log(chalk.green(`  Active agent: ${chalk.bold(display)}.`));
+    })
+        .command("register <name>", "Register a custom agent CLI", (y) => y
+        .positional("name", {
+        type: "string",
+        demandOption: true,
+        describe: "Agent name (lowercase identifier, e.g. opencode)",
+    })
+        .option("command", {
+        type: "string",
+        demandOption: true,
+        describe: "Command to invoke (e.g. \"opencode --prompt\")",
+    })
+        .option("display-name", {
+        type: "string",
+        describe: "Human-readable name (defaults to the agent name)",
+    }), async (args) => {
+        const { url, token } = resolveConnection(args);
+        const displayName = args.displayName ?? args.name;
+        const { status, body, raw } = await callJson(`${url}/v1/agents`, token, {
+            method: "POST",
+            body: JSON.stringify({
+                name: args.name,
+                display_name: displayName,
+                command: args.command,
+            }),
+        });
+        if (status !== 201 || !body) {
+            console.error(chalk.red(`Failed to register agent (HTTP ${status}).`));
+            if (raw)
+                console.error(raw);
+            process.exit(1);
+        }
+        console.log(chalk.green(`  Registered ${chalk.bold(args.name)} → ${args.command}.`));
+        printRegistry(body);
+    })
+        .command("unregister <name>", "Unregister a custom agent (built-ins cannot be unregistered)", (y) => y.positional("name", {
+        type: "string",
+        demandOption: true,
+        describe: "Agent name to remove",
+    }), async (args) => {
+        const { url, token } = resolveConnection(args);
+        const { status, body, raw } = await callJson(`${url}/v1/agents/${encodeURIComponent(args.name)}`, token, { method: "DELETE" });
+        if (status !== 200 || !body) {
+            console.error(chalk.red(`Failed to unregister agent (HTTP ${status}).`));
+            if (raw)
+                console.error(raw);
+            process.exit(1);
+        }
+        console.log(chalk.green(`  Unregistered ${chalk.bold(args.name)}.`));
+        printRegistry(body);
+    })
+        .command("map <role> <agent>", "Map a role to an agent", (y) => y
+        .positional("role", {
+        type: "string",
+        demandOption: true,
+        describe: "Role name (e.g. extractor, summarizer, verifier, general)",
+    })
+        .positional("agent", {
+        type: "string",
+        demandOption: true,
+        describe: "Agent name to bind to the role",
+    }), async (args) => {
+        const { url, token } = resolveConnection(args);
+        const patch = { [args.role]: args.agent };
+        const { status, body, raw } = await callJson(`${url}/v1/agents/role-map`, token, {
+            method: "PATCH",
+            body: JSON.stringify(patch),
+        });
+        if (status !== 200 || !body) {
+            console.error(chalk.red(`Failed to update role map (HTTP ${status}).`));
+            if (raw)
+                console.error(raw);
+            process.exit(1);
+        }
+        console.log(chalk.green(`  Mapped ${chalk.bold(args.role)} → ${args.agent}.`));
+    })
+        .command("unmap <role>", "Clear a role mapping (falls back to active agent)", (y) => y.positional("role", {
+        type: "string",
+        demandOption: true,
+        describe: "Role name to clear",
+    }), async (args) => {
+        const { url, token } = resolveConnection(args);
+        const patch = { [args.role]: "" };
+        const { status, raw } = await callJson(`${url}/v1/agents/role-map`, token, {
+            method: "PATCH",
+            body: JSON.stringify(patch),
+        });
+        if (status !== 200) {
+            console.error(chalk.red(`Failed to clear role mapping (HTTP ${status}).`));
+            if (raw)
+                console.error(raw);
+            process.exit(1);
+        }
+        console.log(chalk.green(`  Cleared role ${chalk.bold(args.role)}.`));
+    })
+        .demandCommand(1)
+        .strict(),
+    handler: () => {
+        /* yargs subcommand handlers do the work */
+    },
+};