npm - agent-relay-server - Versions diffs - 0.32.4 → 0.33.1 - Mend

agent-relay-server 0.32.4 → 0.33.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (125) hide show

package/package.json +2 -2
package/public/assets/{activity-DT1JGHnp.js → activity-B0_uE6Yh.js} +2 -2
package/public/assets/{activity-DT1JGHnp.js.map → activity-B0_uE6Yh.js.map} +1 -1
package/public/assets/{agent-profiles-CrMemMkZ.js → agent-profiles-Rwxrcf9F.js} +2 -2
package/public/assets/{agent-profiles-CrMemMkZ.js.map → agent-profiles-Rwxrcf9F.js.map} +1 -1
package/public/assets/{agents-Bl-rrgOy.js → agents-Dp1EXJc8.js} +2 -2
package/public/assets/{agents-Bl-rrgOy.js.map → agents-Dp1EXJc8.js.map} +1 -1
package/public/assets/{analytics-a663ak56.js → analytics-D5OT5ajj.js} +2 -2
package/public/assets/{analytics-a663ak56.js.map → analytics-D5OT5ajj.js.map} +1 -1
package/public/assets/automation-Dm6rXNxK.js +2 -0
package/public/assets/{automation-CiaLThdO.js.map → automation-Dm6rXNxK.js.map} +1 -1
package/public/assets/{branch-state-badge-D4ur3m3_.js → branch-state-badge-FX5Yww2s.js} +2 -2
package/public/assets/{branch-state-badge-D4ur3m3_.js.map → branch-state-badge-FX5Yww2s.js.map} +1 -1
package/public/assets/{channels-o9KLTHoK.js → channels--rdAiX17.js} +2 -2
package/public/assets/{channels-o9KLTHoK.js.map → channels--rdAiX17.js.map} +1 -1
package/public/assets/chat-JZAEDGfX.js +2 -0
package/public/assets/chat-JZAEDGfX.js.map +1 -0
package/public/assets/{connectors-CdC806mA.js → connectors-Bx4gzvNf.js} +2 -2
package/public/assets/{connectors-CdC806mA.js.map → connectors-Bx4gzvNf.js.map} +1 -1
package/public/assets/display-Bebqs1qu.js +3 -0
package/public/assets/display-Bebqs1qu.js.map +1 -0
package/public/assets/{formatted-body-impl-Ca74OAEH.js → formatted-body-impl-CVq4qHix.js} +2 -2
package/public/assets/{formatted-body-impl-Ca74OAEH.js.map → formatted-body-impl-CVq4qHix.js.map} +1 -1
package/public/assets/{index-C_33ymaw.js → index-BHRtR4q7.js} +8 -8
package/public/assets/{index-C_33ymaw.js.map → index-BHRtR4q7.js.map} +1 -1
package/public/assets/{insights-ClI68s39.js → insights-yJFgCa3o.js} +2 -2
package/public/assets/{insights-ClI68s39.js.map → insights-yJFgCa3o.js.map} +1 -1
package/public/assets/{integrations-1nxMizDY.js → integrations-k1HIONjo.js} +2 -2
package/public/assets/{integrations-1nxMizDY.js.map → integrations-k1HIONjo.js.map} +1 -1
package/public/assets/maintenance-CsoOFBXx.js +2 -0
package/public/assets/{maintenance-DiFNzNPN.js.map → maintenance-CsoOFBXx.js.map} +1 -1
package/public/assets/{managed-agents-Do3dKvfj.js → managed-agents-Q3HuVjGg.js} +2 -2
package/public/assets/{managed-agents-Do3dKvfj.js.map → managed-agents-Q3HuVjGg.js.map} +1 -1
package/public/assets/{markdown-preview-impl-CLA0J255.js → markdown-preview-impl-CnsMjrnu.js} +2 -2
package/public/assets/{markdown-preview-impl-CLA0J255.js.map → markdown-preview-impl-CnsMjrnu.js.map} +1 -1
package/public/assets/{memory-IjwqFzBd.js → memory-D3-K5eJS.js} +2 -2
package/public/assets/{memory-IjwqFzBd.js.map → memory-D3-K5eJS.js.map} +1 -1
package/public/assets/{messages-DjvWqHyn.js → messages-B4lCP5rS.js} +2 -2
package/public/assets/{messages-DjvWqHyn.js.map → messages-B4lCP5rS.js.map} +1 -1
package/public/assets/{orchestrators-D2IqDxDT.js → orchestrators-CRoZtLeQ.js} +2 -2
package/public/assets/{orchestrators-D2IqDxDT.js.map → orchestrators-CRoZtLeQ.js.map} +1 -1
package/public/assets/{overview-DKC3TbAh.js → overview-CxCU2fOF.js} +2 -2
package/public/assets/{overview-DKC3TbAh.js.map → overview-CxCU2fOF.js.map} +1 -1
package/public/assets/pairs-unqjPlmq.js +2 -0
package/public/assets/{pairs-WpKCPE1n.js.map → pairs-unqjPlmq.js.map} +1 -1
package/public/assets/{security-BF7ZtPQe.js → security-B7HhSYNy.js} +2 -2
package/public/assets/{security-BF7ZtPQe.js.map → security-B7HhSYNy.js.map} +1 -1
package/public/assets/{settings-CQnjrTa-.js → settings-B9NDhsAb.js} +2 -2
package/public/assets/{settings-CQnjrTa-.js.map → settings-B9NDhsAb.js.map} +1 -1
package/public/assets/store-DiSzYHj9.js +9 -0
package/public/assets/{store-C9VcSo05.js.map → store-DiSzYHj9.js.map} +1 -1
package/public/assets/{tasks-CbN_GSSb.js → tasks-CIQolvNm.js} +2 -2
package/public/assets/{tasks-CbN_GSSb.js.map → tasks-CIQolvNm.js.map} +1 -1
package/public/assets/{terminal-viewer-impl-BJRohThT.js → terminal-viewer-impl-DCifVqFR.js} +2 -2
package/public/assets/{terminal-viewer-impl-BJRohThT.js.map → terminal-viewer-impl-DCifVqFR.js.map} +1 -1
package/public/assets/{work-queue-C5xLBLmm.js → work-queue-Dr3c1V6O.js} +2 -2
package/public/assets/{work-queue-C5xLBLmm.js.map → work-queue-Dr3c1V6O.js.map} +1 -1
package/public/assets/{workspaces-D91H3wDX.js → workspaces-B1Jxop7h.js} +3 -3
package/public/assets/{workspaces-D91H3wDX.js.map → workspaces-B1Jxop7h.js.map} +1 -1
package/public/index.html +3 -3
package/runner/src/adapter.ts +1 -1
package/src/agent-lifecycle-events.ts +137 -0
package/src/artifact-storage.ts +3 -5
package/src/channel-target.ts +24 -0
package/src/cli/_shared.ts +80 -0
package/src/cli/agent-detect.ts +188 -0
package/src/cli/agent-meta.ts +95 -0
package/src/cli/context-probe.ts +88 -0
package/src/cli/daemon.ts +111 -0
package/src/cli/dev.ts +173 -0
package/src/cli/index.ts +361 -0
package/src/cli/introspect.ts +73 -0
package/src/cli/memory.ts +37 -0
package/src/cli/message.ts +201 -0
package/src/cli/orchestrator.ts +227 -0
package/src/cli/pair.ts +125 -0
package/src/cli/provider.ts +209 -0
package/src/cli/recipe.ts +110 -0
package/src/cli/reply.ts +141 -0
package/src/cli/setup.ts +57 -0
package/src/cli/steward.ts +59 -0
package/src/cli/token.ts +81 -0
package/src/cli/upgrade.ts +193 -0
package/src/cli/workspace.ts +215 -0
package/src/cli.ts +4 -2718
package/src/config-store.ts +10 -6
package/src/db/activity.ts +194 -0
package/src/db/agent-search.ts +174 -0
package/src/db/agents.ts +551 -0
package/src/db/artifacts.ts +342 -0
package/src/db/channels.ts +576 -0
package/src/db/connection.ts +71 -0
package/src/db/delivery.ts +395 -0
package/src/db/inbox.ts +249 -0
package/src/db/index.ts +23 -0
package/src/db/integrations.ts +339 -0
package/src/db/mappers.ts +397 -0
package/src/db/merge-lease.ts +160 -0
package/src/db/message-reads.ts +304 -0
package/src/db/messages.ts +434 -0
package/src/db/migrations.ts +431 -0
package/src/db/orchestrators.ts +358 -0
package/src/db/pairs.ts +324 -0
package/src/db/schema.ts +758 -0
package/src/db/stats.ts +337 -0
package/src/db/tasks.ts +407 -0
package/src/db/workspaces.ts +440 -0
package/src/db.ts +4 -5721
package/src/maintenance.ts +4 -0
package/src/mcp-errors.ts +7 -0
package/src/mcp.ts +32 -34
package/src/routes/agents-spawn.ts +9 -1
package/src/routes/agents.ts +5 -0
package/src/routes/commands.ts +15 -0
package/src/routes/integrations.ts +6 -8
package/src/spawn-targets.ts +159 -0
package/src/utils.ts +16 -1
package/public/assets/automation-CiaLThdO.js +0 -2
package/public/assets/chat-5hvHZcAe.js +0 -2
package/public/assets/chat-5hvHZcAe.js.map +0 -1
package/public/assets/display-JI19Vc7L.js +0 -3
package/public/assets/display-JI19Vc7L.js.map +0 -1
package/public/assets/maintenance-DiFNzNPN.js +0 -2
package/public/assets/pairs-WpKCPE1n.js +0 -2
package/public/assets/store-C9VcSo05.js +0 -9

package/src/cli.ts CHANGED Viewed

@@ -1,2718 +1,4 @@
-import { createInterface } from "node:readline/promises";
-import { stdin as input, stdout as output } from "node:process";
-import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
-import { hostname as osHostname, homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
-import {
-  createDaemonPlan,
-  detectDaemonEnvironment,
-  executeDaemonPlan,
-  formatDaemonPlan,
-  type DaemonAction,
-  type DaemonScope,
-} from "./daemon";
-import {
-  createSetupPlan,
-  executeSetupPlan,
-  formatSetupPlan,
-  pathExists,
-  renderEnvFile,
-} from "./setup";
-import { defaultRuntimePrefix, runtimeBinPath } from "./runtime-prefix";
-import {
-  createDevInstallPlan,
-  createDevPackPlan,
-  createDevServicePlan,
-  defaultDevRoot,
-  executeDevInstallPlan,
-  executeDevPackPlan,
-  executeDevServicePlan,
-  executeDevSmoke,
-  formatDevInstallPlan,
-  formatDevPackPlan,
-  formatDevServicePlan,
-  parseDevPackages,
-  type DevServiceAction,
-} from "./dev";
-import {
-  createUpgradePlan,
-  detectUpgradeSnapshot,
-  executeUpgradePlan,
-  formatUpgradePlan,
-  resolveLocalOrchestratorId,
-  type UpgradeProvider,
-} from "./upgrade";
-import { formatMemoryBrokerSmokeResult, runMemoryBrokerSmoke } from "./memory-broker-smoke";
-import { MAX_BODY_BYTES, VERSION } from "./config";
-import { runContextProbe } from "agent-relay-sdk/context-probe";
-import { shellQuote } from "agent-relay-sdk/shell-utils";
-import { errMessage, RELAY_TOKEN_HEADER } from "agent-relay-sdk";
-import type { WorkspaceDepsRefreshResult } from "agent-relay-sdk";
-import { describeWorkspacePhase, readyContract, type WorkspacePhaseView } from "./workspace-phase";
-export const WORKSPACE_USAGE = "Usage: agent-relay workspace <status|diagnostics|ready|land|claim|release|list|cleanup-stale|deps> [--id ID] [--strategy ...] [--purpose TEXT] [--repo PATH] [--wait] [--timeout SECONDS] [--check] [--execute] [--json]";
-const HELP = `
-agent-relay ${VERSION}
-Usage:
-  agent-relay [start]
-  agent-relay setup [--yes] [--dry-run] [--force] [--env-file PATH] [--runtime-prefix DIR] [--host HOST] [--port PORT] [--db-path PATH] [--token TOKEN|--no-token]
-  agent-relay upgrade [--dry-run] [--version VERSION] [--runtime-prefix DIR] [--providers auto|all|codex|claude|orchestrator] [--no-restart] [--yes]
-  agent-relay upgrade --host ID [--host ID2 ...] [--version VERSION] [--providers ...]   (upgrade remote orchestrator hosts over the relay)
-  agent-relay upgrade --all-hosts [...]                                                  (upgrade this host, then every behind remote host)
-  agent-relay setup upgrade [same options as upgrade]
-  agent-relay daemon <install|uninstall|start|stop|restart|enable|disable|status|logs> [options]
-  agent-relay orchestrator install [options]
-  agent-relay dev <pack|install|service|smoke> [options]
-  agent-relay memory broker smoke [options]
-  agent-relay recipe <list|show|start|stop|status> [options]
-  agent-relay provider <wrap|unwrap> <claude|codex>
-  agent-relay context-probe [print-status-line] [--wrap COMMAND] [--agent-id ID] [--state-dir DIR] [--standalone]
-  agent-relay token <create|list|revoke|verify> [options]
-  agent-relay pair <target|create|status|accept|reject|hangup|send> [options]
-  agent-relay workspace <status|diagnostics|ready|land|claim|release|list|cleanup-stale|deps> [--id ID] [--strategy ...] [--purpose TEXT] [--repo PATH] [--wait] [--timeout SECONDS] [--check] [--execute] [--json]
-  agent-relay steward <queue|inspect|checks> [WORKSPACE_ID] [--repo PATH] [--json]
-  agent-relay message <target> <body> [options]
-  agent-relay get-message <messageId> [--json|--body]
-  agent-relay /pair <target|accept|reject|send|status> [...]
-  agent-relay /message <target> <body>
-  agent-relay /reply <messageId> <body|--stdin|--body-file PATH> [--format text|markdown|markdownv2]
-  agent-relay /react <messageId> <emoji> [--remove]
-  agent-relay /send-claimable <target> <body>
-  agent-relay /disconnect [PAIR_ID]
-  agent-relay /status
-  agent-relay /guide
-  agent-relay /label [LABEL]
-  agent-relay /tags [TAG ...]
-  agent-relay /introspect [--thin TEXT] [--worked-around TEXT] [--would-have-helped TEXT] [--stdin]
-  agent-relay --help
-Pair examples:
-  agent-relay pair codex --objective "Debug flaky tests"
-  agent-relay /pair codex "Debug flaky tests"
-  agent-relay pair status
-  agent-relay pair accept PAIR_ID --agent AGENT_ID
-  agent-relay pair send PAIR_ID --from AGENT_ID --body "What do you see?"
-  agent-relay /message codex "Can you look at that failing action?"
-  agent-relay /reply 206 "Sounds good, I'll take a look"
-  agent-relay /react 206 👍
-  agent-relay /reply 206 --stdin < result.md
-  agent-relay get-message 206 --json
-  agent-relay /reply 206 --format markdown "Here is **formatted** text"
-  agent-relay /send-claimable tag:backend "Please claim and fix the failing API test"
-  agent-relay /disconnect
-  agent-relay /status
-  agent-relay /guide
-  agent-relay /label backend-fixer
-  agent-relay /tags backend tests urgent
-Daemon options:
-  --env-file PATH   Env file sourced by the daemon (default: platform user config dir)
-  --runtime-prefix DIR  Isolated Agent Relay npm prefix (default: ~/.agent-relay/runtime)
-  --binary PATH     Stable agent-relay binary/script path for the service
-  --path-prefix DIR Prepend a directory to daemon PATH; repeatable
-  --name NAME       Service name (default: agent-relay)
-  --host HOST       Display/listen host for generated plan (default: 127.0.0.1)
-  --port PORT       Display/listen port for generated plan (default: 4850)
-  --user|--system   User service by default, system service when explicitly requested
-  --enable          Enable service at login/boot during install
-  --start           Start service after install
-  --dry-run         Print the plan without writing files or running service commands
-  --yes             Skip confirmation prompts
-  --force           Overwrite/remove managed-file guardrails
-  --json            Print structured output
-Orchestrator install options:
-  --relay-url URL   Agent Relay server URL reachable from this host
-  --token TOKEN     Scoped runtime orchestrator token
-  --bootstrap-token TOKEN Short-lived dashboard bootstrap token to exchange during install
-  --id ID           Orchestrator id (default: sanitized hostname)
-  --base-dir PATH   Base directory for agent working directories (default: ~/projects)
-  --providers LIST  Providers to probe/enable (default: claude,codex)
-  --api-port PORT   Orchestrator local API port (default: 4860)
-  --runtime-prefix DIR  Isolated npm prefix (default: ~/.agent-relay/runtime)
-  --path-prefix DIR Prepend a directory to daemon PATH; repeatable
-  --version VERSION Package version to install (default: this CLI version)
-  --dry-run         Print the plan without writing files, installing, or starting
-  --yes             Skip confirmation prompts
-Upgrade options:
-  --version VERSION Target version (default: latest published server version)
-  --runtime-prefix DIR  Isolated Agent Relay npm prefix (default: ~/.agent-relay/runtime)
-  --providers LIST  Provider integrations to upgrade: auto, all, codex, claude, orchestrator
-  --host ID         Upgrade a remote orchestrator host over the relay (repeatable). Skips the local upgrade
-  --all-hosts       Upgrade this host, then fan out to every connected remote host that is behind
-  --no-restart      Do not restart agent-relay.service (warns you to restart it manually)
-  --restart-deferred  Like --no-restart, but the caller restarts the services itself; suppresses the manual-restart warning (used by the release script)
-  --dry-run         Print detected state and planned commands
-  --yes             Skip confirmation prompts
-Dev options:
-  agent-relay dev pack [--packages LIST] [--out DIR]
-  agent-relay dev install [--packages LIST] [--prefix DIR] [--out DIR] [--dry-run] [--json]
-  agent-relay dev service <install|uninstall|start|stop|restart|status|logs> [--prefix DIR] [--root DIR] [--port PORT] [--api-port PORT] [--base-dir DIR] [--enable] [--start] [--dry-run] [--yes] [--force] [--json]
-  agent-relay dev smoke [--root DIR] [--providers LIST] [--cwd DIR] [--timeout MS]
-Memory options:
-  agent-relay memory broker smoke [--relay-url URL] [--token TOKEN] [--agent-id ID] [--scope SCOPE] [--tag TAG] [--no-cleanup] [--json]
-Recipe examples:
-  agent-relay recipe list
-  agent-relay recipe start code-review --cwd /repo --orchestrator local
-  agent-relay recipe status
-  agent-relay recipe stop INSTANCE_ID
-Token examples:
-  agent-relay token create --role orchestrator --sub macmini --ttl 86400
-  agent-relay token list
-  agent-relay token revoke JTI
-Context probe examples:
-  agent-relay context-probe print-status-line --wrap 'ccstatusline'
-  agent-relay context-probe --wrap 'ccstatusline'
-  agent-relay context-probe --standalone
-`.trim();
-const AGENT_GUIDE = `
-Agent Relay guide for coding agents
-Agent Relay is a message bus between local or managed agents. Use the
-agent-relay CLI for relay communication.
-Current session
-  agent-relay /status --json
-    Shows your relay agent id, label, tags, health, and active pair state.
-Replying
-  agent-relay /reply <messageId> "<response>"
-  agent-relay /reply <messageId> --stdin < response.md
-  agent-relay /reply <messageId> --body-file response.md
-    Reply to the sender of a relay message. Prefer this over /message when
-    handling an incoming relay message because the server keeps the routing
-    and channel context. Large replies are uploaded as an artifact
-    automatically and sent as a concise attached reply.
-Reactions
-  agent-relay /react <messageId> <emoji>
-  agent-relay /react <messageId> <emoji> --remove
-    Use reactions for lightweight acknowledgement, approval, thanks, or
-    "good job" when no text response is needed. Do not use reactions when the
-    sender asked a question, gave a new task, or needs a result in text.
-Reading full messages
-  agent-relay get-message <messageId>
-  agent-relay read-message <messageId> --json
-  agent-relay get-message <messageId> --body
-    Fetch the full message body, attachments, metadata, and thread context.
-Sending messages
-  agent-relay /message <target> "<message>"
-    Send a direct one-off relay message.
-  agent-relay /send-claimable <target> "<work item>"
-    Queue work that one matching agent can claim and handle.
-Targets
-  <agent-id>       A specific live agent id.
-  <label>          A registered agent label.
-  tag:<tag>        Any agent with that tag.
-  cap:<capability> Any agent with that capability.
-  policy:<name>    A managed policy target that can survive restarts.
-  broadcast        All reachable agents.
-Pair sessions
-  agent-relay /pair <target> "<objective>"
-  agent-relay /pair status
-  agent-relay /pair accept <pairId>
-  agent-relay /pair reject <pairId>
-  agent-relay /pair send <pairId> "<message>"
-  agent-relay /disconnect [pairId]
-Labels and tags
-  agent-relay /label [LABEL]
-  agent-relay /tags [TAG ...]
-Isolated workspaces
-  If you are working in an isolated workspace (a git worktree on an agent
-  branch, not the main checkout), you do NOT rebase, merge, or push yourself —
-  Relay does. Just commit your work in the worktree, then:
-    agent-relay workspace ready    Hand off: Relay rebases onto the latest base,
-                                   lands your work, and pushes.
-    agent-relay workspace status   Show your workspace's state + what to do next.
-    agent-relay workspace status --wait
-                                   Block until your branch lands (returns the
-                                   moment the auto-merge completes).
-  After "ready", status is "review_requested" — this is NORMAL, not an
-  escalation. Relay auto-merges clean rebases ~every 2 min; a steward agent is
-  spawned only if it can't land deterministically, so no steward = healthy. On
-  landing you move onto a fresh rebased branch (name gains a "--N" suffix).
-  The base branch will move as other agents land in parallel — that is normal,
-  let the merge handle it. Never push, merge, resolve conflicts, or touch the
-  main checkout yourself; it is local-only and Relay (and the steward) own that.
-  If typecheck/build fails on a missing module (a dep added to the base after
-  your worktree was created), do NOT run a clean install — it mutates the shared
-  node_modules. Instead refresh your worktree's deps in isolation:
-    agent-relay workspace deps     Re-provision deps that have gone stale.
-    agent-relay workspace deps --check   Report staleness without installing.
-Rules of thumb
-  If you are handling relay message #123, reply with:
-    agent-relay /reply 123 "<response>"
-  If the delivered preview says it was truncated, fetch the full message with:
-    agent-relay get-message 123
-  If your reply is long, avoid shell quoting and use:
-    agent-relay /reply 123 --stdin < response.md
-  If you need to know who you are in Relay, run:
-    agent-relay /status --json
-Recording session friction (optional, helps improve your standing context)
-  agent-relay /introspect --thin "..." --worked-around "..." --would-have-helped "..."
-    When a session involved real work, you can record a short 3-field note about
-    where context was thin, what tooling/instruction gaps you routed around, and
-    what would have saved the read-up. Keep each field to a sentence or two. This
-    feeds the relay's self-improvement signal so the operator can close the gaps —
-    it is not a reply and needs no message id. Skip it for trivial sessions.
-  Use the HTTP API for integrations and debugging. For normal agent-to-agent
-  communication, use the CLI commands above.
-`.trim();
-const DAEMON_ACTIONS = new Set<DaemonAction>([
-  "install",
-  "uninstall",
-  "start",
-  "stop",
-  "restart",
-  "enable",
-  "disable",
-  "status",
-  "logs",
-]);
-export async function handleCli(args: string[]): Promise<"start" | "handled"> {
-  const command = args[0];
-  if (!command || command === "start") return "start";
-  if (command === "--help" || command === "-h" || command === "help") {
-    console.log(HELP);
-    return "handled";
-  }
-  if (command === "--version" || command === "-v") {
-    console.log(VERSION);
-    return "handled";
-  }
-  if (command === "guide" || command === "/guide" || command === "agent-guide" || command === "/agent-guide") {
-    console.log(AGENT_GUIDE);
-    return "handled";
-  }
-  if (command === "upgrade" || (command === "setup" && args[1] === "upgrade")) {
-    await handleUpgradeCommand(command === "setup" ? args.slice(2) : args.slice(1));
-    return "handled";
-  }
-  if (command === "setup" || command === "init") {
-    await handleSetupCommand(args.slice(1));
-    return "handled";
-  }
-  if (command === "daemon") {
-    await handleDaemonCommand(args.slice(1));
-    return "handled";
-  }
-  if (command === "orchestrator" || command === "orchestrators") {
-    await handleOrchestratorCommand(args.slice(1));
-    return "handled";
-  }
-  if (command === "dev") {
-    await handleDevCommand(args.slice(1));
-    return "handled";
-  }
-  if (command === "memory") {
-    await handleMemoryCommand(args.slice(1));
-    return "handled";
-  }
-  if (command === "recipe" || command === "recipes") {
-    await handleRecipeCommand(args.slice(1));
-    return "handled";
-  }
-  if (command === "provider" || command === "providers") {
-    await handleProviderCommand(args.slice(1));
-    return "handled";
-  }
-  if (command === "context-probe") {
-    await handleContextProbeCommand(args.slice(1));
-    return "handled";
-  }
-  if (command === "token" || command === "tokens") {
-    await handleTokenCommand(args.slice(1));
-    return "handled";
-  }
-  if (command === "pair" || command === "/pair" || command === "/disconnect") {
-    await handleSlashOrPairCommand(command, args.slice(1));
-    return "handled";
-  }
-  if (command === "message" || command === "send" || command === "/message" || command === "/send" || command === "/send-claimable") {
-    await handleMessageCommand(args.slice(1), { claimable: command === "/send-claimable" });
-    return "handled";
-  }
-  if (command === "get-message" || command === "read-message" || command === "/get-message" || command === "/read-message") {
-    await handleGetMessageCommand(args.slice(1));
-    return "handled";
-  }
-  if (command === "reply" || command === "/reply") {
-    await handleReplyCommand(args.slice(1));
-    return "handled";
-  }
-  if (command === "react" || command === "/react" || command === "reaction" || command === "/reaction") {
-    await handleReactCommand(args.slice(1));
-    return "handled";
-  }
-  if (command === "introspect" || command === "/introspect") {
-    await handleIntrospectCommand(args.slice(1));
-    return "handled";
-  }
-  if (command === "/status" || command === "status") {
-    await handleStatusCommand(args.slice(1));
-    return "handled";
-  }
-  if (command === "/label" || command === "label") {
-    await handleLabelCommand(args.slice(1));
-    return "handled";
-  }
-  if (command === "/tags" || command === "tags") {
-    await handleTagsCommand(args.slice(1));
-    return "handled";
-  }
-  if (command === "workspace" || command === "workspaces") {
-    await handleWorkspaceCommand(args.slice(1));
-    return "handled";
-  }
-  if (command === "steward" || command === "stewards") {
-    await handleStewardCommand(args.slice(1));
-    return "handled";
-  }
-  if (command === "/reconnect") {
-    console.log("Reconnect is handled automatically by provider runners; use `agent-relay pair status` to inspect current pair state.");
-    return "handled";
-  }
-  throw new Error(`Unknown command "${command}". Run agent-relay --help.`);
-}
-async function handleUpgradeCommand(args: string[]): Promise<void> {
-  let targetVersion: string | undefined;
-  let dryRun = false;
-  let noRestart = false;
-  let restartDeferred = false;
-  let yes = false;
-  let json = false;
-  let runtimePrefix: string | undefined;
-  const pathPrefix: string[] = [];
-  const providers: UpgradeProvider[] = [];
-  const hosts: string[] = [];
-  let allHosts = false;
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === "--version" && i + 1 < args.length) targetVersion = args[++i];
-    else if (arg === "--runtime-prefix" && i + 1 < args.length) runtimePrefix = args[++i];
-    else if (arg === "--providers" && i + 1 < args.length) {
-      for (const provider of args[++i]!.split(",")) providers.push(parseUpgradeProvider(provider));
-    } else if (arg === "--provider" && i + 1 < args.length) providers.push(parseUpgradeProvider(args[++i]!));
-    else if (arg === "--host" && i + 1 < args.length) hosts.push(args[++i]!);
-    else if (arg === "--all-hosts") allHosts = true;
-    else if (arg === "--codex") providers.push("codex");
-    else if (arg === "--claude") providers.push("claude");
-    else if (arg === "--orchestrator") providers.push("orchestrator");
-    else if (arg === "--all") providers.push("all");
-    else if (arg === "--dry-run") dryRun = true;
-    else if (arg === "--no-restart") noRestart = true;
-    else if (arg === "--restart-deferred") restartDeferred = true;
-    else if (arg === "--yes" || arg === "-y") yes = true;
-    else if (arg === "--json") json = true;
-    else throw new Error(`Unknown upgrade option "${arg}"`);
-  }
-  // Remote-only: drive named hosts' self-upgrade over the relay command bus and
-  // skip the local upgrade entirely (#210). `--all-hosts` instead upgrades this
-  // host first, then fans out to every behind remote (handled after the local run).
-  if (hosts.length && !allHosts) {
-    await runRemoteOrchestratorUpgrades({ hosts, targetVersion, providers, json, dryRun, yes });
-    return;
-  }
-  const snapshot = await detectUpgradeSnapshot({
-    ...(targetVersion ? { targetVersion } : {}),
-    ...(runtimePrefix ? { runtimePrefix } : {}),
-    providers,
-    noRestart,
-  });
-  const plan = createUpgradePlan(snapshot, {
-    ...(targetVersion ? { targetVersion } : {}),
-    ...(runtimePrefix ? { runtimePrefix } : {}),
-    providers,
-    noRestart,
-    restartDeferred,
-  });
-  if (json) {
-    console.log(JSON.stringify({ plan }, null, 2));
-    if (allHosts) await runRemoteOrchestratorUpgrades({ allBehind: true, targetVersion: plan.targetVersion, providers, json, dryRun: true });
-    return;
-  }
-  if (dryRun) {
-    console.log(formatUpgradePlan(plan, { dryRun: true }));
-    if (allHosts) await runRemoteOrchestratorUpgrades({ allBehind: true, targetVersion: plan.targetVersion, providers, dryRun: true });
-    return;
-  }
-  if (!yes) {
-    console.log(formatUpgradePlan(plan));
-    const ok = await confirm("Run this upgrade plan?");
-    if (!ok) {
-      console.log("Upgrade cancelled.");
-      return;
-    }
-  }
-  console.log(await executeUpgradePlan(plan));
-  if (allHosts) {
-    await runRemoteOrchestratorUpgrades({ allBehind: true, targetVersion: plan.targetVersion, providers, json, yes: true });
-  }
-}
-/**
- * Trigger orchestrator self-upgrade on remote hosts via the relay command bus
- * (#210). Each host installs its own runtime + self-restarts; the relay settles
- * the version when it re-registers. Replaces the manual ssh + npm install dance.
- */
-async function runRemoteOrchestratorUpgrades(opts: {
-  hosts?: string[];
-  allBehind?: boolean;
-  targetVersion?: string;
-  providers: UpgradeProvider[];
-  json?: boolean;
-  dryRun?: boolean;
-  yes?: boolean;
-}): Promise<void> {
-  const targetVersion = opts.targetVersion ?? VERSION;
-  const orchestrators = (await apiRequest("GET", "/api/orchestrators")) as Array<{
-    id: string;
-    version?: string;
-  }>;
-  const byId = new Map(orchestrators.map((orch) => [orch.id, orch]));
-  const localId = resolveLocalOrchestratorId();
-  // Default to "all" so a remote host's provider runner is upgraded too, not just
-  // the orchestrator package (matters for hosts running claude/codex agents).
-  const remoteProviders: UpgradeProvider[] = opts.providers.length ? opts.providers : ["all"];
-  let targets: string[];
-  if (opts.allBehind) {
-    targets = orchestrators
-      .filter((orch) => orch.id !== localId && orch.version && orch.version !== targetVersion)
-      .map((orch) => orch.id);
-    if (!targets.length) {
-      if (opts.json) console.log(JSON.stringify({ remoteUpgrades: [] }, null, 2));
-      else console.log(`No remote orchestrators behind ${targetVersion}.`);
-      return;
-    }
-  } else {
-    targets = opts.hosts ?? [];
-  }
-  if (opts.dryRun) {
-    const lines = targets.map((id) => {
-      const orch = byId.get(id);
-      const from = orch ? orch.version ?? "unknown" : "(not connected)";
-      return `  ${id}: ${from} → ${targetVersion} (providers: ${remoteProviders.join(",")})`;
-    });
-    if (opts.json) console.log(JSON.stringify({ remoteUpgrades: targets.map((id) => ({ id, targetVersion, providers: remoteProviders, dryRun: true })) }, null, 2));
-    else console.log(`Remote orchestrator upgrade plan → ${targetVersion}:\n${lines.join("\n")}`);
-    return;
-  }
-  if (!opts.yes && !opts.json) {
-    console.log(`Trigger remote orchestrator upgrade → ${targetVersion} for: ${targets.join(", ")}`);
-    const ok = await confirm("Send remote upgrade command(s)?");
-    if (!ok) {
-      console.log("Remote upgrade cancelled.");
-      return;
-    }
-  }
-  const results: Array<{ id: string; ok: boolean; message: string }> = [];
-  for (const id of targets) {
-    if (!byId.has(id)) {
-      results.push({ id, ok: false, message: "not connected to the relay" });
-      continue;
-    }
-    try {
-      const res = (await apiRequest("POST", `/api/orchestrators/${encodeURIComponent(id)}/actions`, {
-        action: "upgrade",
-        targetVersion,
-        providers: remoteProviders,
-      })) as { command?: { id?: string } };
-      const from = byId.get(id)?.version;
-      results.push({ id, ok: true, message: `queued ${from ?? "?"} → ${targetVersion} (command ${res?.command?.id ?? "?"})` });
-    } catch (err) {
-      results.push({ id, ok: false, message: errMessage(err) });
-    }
-  }
-  if (opts.json) {
-    console.log(JSON.stringify({ remoteUpgrades: results }, null, 2));
-    return;
-  }
-  console.log(`\nRemote orchestrator upgrades → ${targetVersion}:`);
-  for (const result of results) console.log(`  ${result.ok ? "✓" : "✗"} ${result.id}: ${result.message}`);
-  console.log("\nEach host installs and self-restarts; the relay reconciles the version when it re-registers.");
-  console.log("Track progress in the dashboard Orchestrators view or via GET /api/orchestrators.");
-  if (results.some((result) => !result.ok)) {
-    process.exitCode = 1;
-  }
-}
-function parseUpgradeProvider(value: string): UpgradeProvider {
-  if (value === "auto" || value === "all" || value === "codex" || value === "claude" || value === "orchestrator") return value;
-  throw new Error(`Unknown upgrade provider "${value}". Expected auto, all, codex, claude, or orchestrator.`);
-}
-async function handleProviderCommand(args: string[]): Promise<void> {
-  const action = args[0];
-  const provider = args[1];
-  if ((action !== "wrap" && action !== "unwrap") || (provider !== "claude" && provider !== "codex")) {
-    throw new Error("Usage: agent-relay provider <wrap|unwrap> <claude|codex>");
-  }
-  const dir = join(process.env.HOME || homedir(), ".agent-relay", "bin");
-  const shims = providerShimPaths(provider);
-  if (provider === "codex") cleanLegacyCodexSessionStartHook();
-  if (action === "wrap") {
-    for (const shim of shims) {
-      mkdirSync(dirname(shim), { recursive: true });
-      writeFileSync(shim, providerShimContent(provider), "utf8");
-      chmodSync(shim, 0o755);
-      console.log(`Wrapped ${provider}: ${shim}`);
-    }
-    console.log(`Ensure ${dir} is before the provider binary on PATH.`);
-    return;
-  }
-  for (const shim of shims) {
-    if (existsSync(shim)) unlinkSync(shim);
-    console.log(`Unwrapped ${provider}: ${shim}`);
-  }
-}
-function cleanLegacyCodexSessionStartHook(): void {
-  const configPath = join(process.env.HOME || homedir(), ".codex", "config.toml");
-  if (!existsSync(configPath)) return;
-  const before = readFileSync(configPath, "utf8");
-  const after = removeLegacyCodexSessionStartHookToml(before);
-  if (after === before) return;
-  writeFileSync(configPath, after, "utf8");
-  console.log(`Removed legacy Agent Relay Codex hook entries from ${configPath}`);
-}
-export function removeLegacyCodexSessionStartHookToml(input: string): string {
-  const blocks = tomlHookBlocks(input);
-  let output = "";
-  for (let index = 0; index < blocks.length;) {
-    const block = blocks[index];
-    if (isCodexHookGroupHeader(block?.header)) {
-      const group = block!;
-      const hooks: typeof blocks = [];
-      const hookHeader = codexHookHandlerHeader(group.header!);
-      index += 1;
-      while (index < blocks.length && blocks[index]?.header?.trim() === hookHeader) {
-        hooks.push(blocks[index]!);
-        index += 1;
-      }
-      const keptHooks = hooks.filter((hook) => !isLegacyCodexSessionStartHook(hook.text));
-      const groupIsLegacyOnly = isLegacyCodexSessionStartHook(group.text) || (hooks.length > 0 && keptHooks.length === 0);
-      if (!groupIsLegacyOnly || keptHooks.length > 0) {
-        output += `${group.text}\n`;
-        for (const hook of keptHooks) output += `${hook.text}\n`;
-      }
-      continue;
-    }
-    if (isCodexHookHandlerHeader(block?.header) && isLegacyCodexSessionStartHook(block?.text ?? "")) {
-      index += 1;
-      continue;
-    }
-    if (block) output += `${block.text}\n`;
-    index += 1;
-  }
-  return output.trimEnd() + "\n";
-}
-function tomlHookBlocks(input: string): Array<{ header: string | null; text: string }> {
-  const lines = input.split(/\r?\n/);
-  const blocks: Array<{ header: string | null; text: string }> = [];
-  let current: { header: string | null; lines: string[] } = { header: null, lines: [] };
-  for (const line of lines) {
-    const header = line.match(/^\s*\[\[hooks\.[^\]]+\]\]\s*$/)?.[0] ?? null;
-    if (header) {
-      if (current.lines.length > 0) blocks.push({ header: current.header, text: current.lines.join("\n").trimEnd() });
-      current = { header, lines: [line] };
-    } else {
-      current.lines.push(line);
-    }
-  }
-  if (current.lines.length > 0) blocks.push({ header: current.header, text: current.lines.join("\n").trimEnd() });
-  return blocks.filter((block) => block.text.trim().length > 0);
-}
-function isCodexHookGroupHeader(header: string | null | undefined): boolean {
-  return /^\[\[hooks\.[^.]+\]\]$/.test(header?.trim() ?? "");
-}
-function isCodexHookHandlerHeader(header: string | null | undefined): boolean {
-  return /^\[\[hooks\.[^.]+\.hooks\]\]$/.test(header?.trim() ?? "");
-}
-function codexHookHandlerHeader(groupHeader: string): string {
-  return groupHeader.trim().replace(/\]\]$/, ".hooks]]");
-}
-function isLegacyCodexSessionStartHook(text: string): boolean {
-  return /\.agent-relay\/codex\/package\/hooks\//.test(text) ||
-    /agent-relay-codex.*hook/i.test(text) ||
-    /agent-relay.*(SessionStart|UserPromptSubmit|Stop).*hook/i.test(text);
-}
-async function handleContextProbeCommand(args: string[]): Promise<void> {
-  const printStatusLine = args[0] === "print-status-line";
-  const inputArgs = printStatusLine ? args.slice(1) : args;
-  let wrapCommand: string | undefined;
-  let wrapRequested = false;
-  let agentId: string | undefined;
-  let stateDir: string | undefined;
-  let standalone = false;
-  for (let i = 0; i < inputArgs.length; i++) {
-    const arg = inputArgs[i];
-    if (arg === "--wrap") {
-      wrapRequested = true;
-      const next = inputArgs[i + 1];
-      if (next && !next.startsWith("--")) {
-        wrapCommand = next;
-        i++;
-      }
-    } else if (arg === "--agent-id") {
-      agentId = inputArgs[++i];
-    } else if (arg === "--state-dir") {
-      stateDir = inputArgs[++i] ?? stateDir;
-    } else if (arg === "--standalone") {
-      standalone = true;
-    } else if (arg === "--help" || arg === "-h") {
-      console.log("Usage: agent-relay context-probe [print-status-line] [--wrap COMMAND] [--agent-id ID] [--state-dir DIR] [--standalone]");
-      return;
-    } else {
-      throw new Error(`Unknown context-probe option "${arg}"`);
-    }
-  }
-  if (printStatusLine) {
-    const command = [
-      "agent-relay",
-      "context-probe",
-      ...(wrapRequested ? ["--wrap", ...(wrapCommand ? [shellQuote(wrapCommand)] : [])] : ["--standalone"]),
-      ...(agentId ? ["--agent-id", shellQuote(agentId)] : []),
-      ...(stateDir ? ["--state-dir", shellQuote(stateDir)] : []),
-    ].join(" ");
-    console.log(command);
-    return;
-  }
-  if (wrapRequested && !wrapCommand) wrapCommand = currentClaudeStatusLineCommand();
-  if (wrapCommand && commandLooksLikeContextProbe(wrapCommand)) {
-    wrapCommand = undefined;
-    standalone = true;
-  }
-  if (!wrapRequested && !standalone) {
-    throw new Error("Usage: agent-relay context-probe [--wrap COMMAND|--standalone] [--agent-id ID] [--state-dir DIR]");
-  }
-  const input = await readStdin();
-  const result = runContextProbe(input, { wrapCommand, agentId, stateDir, standalone });
-  if (result.wrappedStderr) process.stderr.write(result.wrappedStderr);
-  if (result.output) process.stdout.write(result.output);
-  if (result.output && !result.output.endsWith("\n")) process.stdout.write("\n");
-  if (typeof result.wrappedExitCode === "number" && result.wrappedExitCode !== 0) process.exit(result.wrappedExitCode);
-}
-function providerShimPaths(provider: "claude" | "codex"): string[] {
-  const root = join(process.env.HOME || homedir(), ".agent-relay");
-  const paths = [join(root, "bin", provider)];
-  if (provider === "codex") paths.push(join(root, "codex", "bin", "codex"));
-  return paths;
-}
-async function readStdin(): Promise<string> {
-  if (typeof Bun !== "undefined" && Bun.stdin && typeof Bun.stdin.text === "function") {
-    return Bun.stdin.text();
-  }
-  let value = "";
-  for await (const chunk of process.stdin) value += String(chunk);
-  return value;
-}
-function currentClaudeStatusLineCommand(): string | undefined {
-  const settingsPath = join(process.env.HOME || homedir(), ".claude", "settings.json");
-  try {
-    const settings = JSON.parse(readFileSync(settingsPath, "utf8")) as unknown;
-    if (!settings || typeof settings !== "object" || Array.isArray(settings)) return undefined;
-    const statusLine = (settings as Record<string, unknown>).statusLine;
-    if (!statusLine || typeof statusLine !== "object" || Array.isArray(statusLine)) return undefined;
-    const command = (statusLine as Record<string, unknown>).command;
-    return typeof command === "string" && command.trim() ? command : undefined;
-  } catch {
-    return undefined;
-  }
-}
-function commandLooksLikeContextProbe(command: string): boolean {
-  return /\bagent-relay\s+context-probe\b/.test(command);
-}
-function providerShimContent(provider: "claude" | "codex"): string {
-  if (provider === "claude") {
-    return `#!/usr/bin/env bash\nexec claude-relay claude -- "$@"\n`;
-  }
-  return `#!/usr/bin/env bash
-set -e
-resolve_path() {
-  if command -v realpath >/dev/null 2>&1; then
-    realpath "$1" 2>/dev/null || printf '%s\\n' "$1"
-  elif command -v readlink >/dev/null 2>&1; then
-    readlink -f "$1" 2>/dev/null || printf '%s\\n' "$1"
-  else
-    printf '%s\\n' "$1"
-  fi
-}
-find_real_codex() {
-  local self resolved candidate
-  self="$(resolve_path "$0")"
-  IFS=: read -r -a path_parts <<< "$PATH"
-  for dir in "\${path_parts[@]}"; do
-    candidate="$dir/codex"
-    [ -x "$candidate" ] || continue
-    resolved="$(resolve_path "$candidate")"
-    [ "$resolved" = "$self" ] && continue
-    printf '%s\\n' "$candidate"
-    return 0
-  done
-  return 1
-}
-first_command() {
-  local skip_next=0
-  for arg in "$@"; do
-    if [ "$skip_next" = 1 ]; then
-      skip_next=0
-      continue
-    fi
-    case "$arg" in
-      --) break ;;
-      -c|--config|--enable|--disable|-i|--image|-m|--model|--local-provider|-p|--profile|-s|--sandbox|-C|--cd|--add-dir|-a|--ask-for-approval|--remote|--remote-auth-token-env)
-        skip_next=1
-        ;;
-      --config=*|--enable=*|--disable=*|--image=*|--model=*|--local-provider=*|--profile=*|--sandbox=*|--cd=*|--add-dir=*|--ask-for-approval=*|--remote=*|--remote-auth-token-env=*)
-        ;;
-      -*)
-        ;;
-      *)
-        printf '%s\\n' "$arg"
-        return 0
-        ;;
-    esac
-  done
-  return 0
-}
-has_passthrough_option() {
-  for arg in "$@"; do
-    case "$arg" in
-      -h|--help|-V|--version)
-        return 0
-        ;;
-    esac
-  done
-  return 1
-}
-exec_real_codex() {
-  real_codex="$(find_real_codex)" || {
-    echo "agent-relay codex shim could not find the real codex binary on PATH" >&2
-    exit 127
-  }
-  exec "$real_codex" "$@"
-}
-if has_passthrough_option "$@"; then
-  exec_real_codex "$@"
-fi
-case "$(first_command "$@")" in
-  exec|e|review|login|logout|mcp|plugin|mcp-server|app-server|remote-control|completion|update|sandbox|debug|apply|a|cloud|exec-server|features|help)
-    exec_real_codex "$@"
-    ;;
-esac
-exec codex-relay codex -- "$@"
-`;
-}
-async function handleSlashOrPairCommand(command: string, args: string[]): Promise<void> {
-  if (command === "/disconnect") {
-    await handlePairCommand(["hangup", ...args]);
-    return;
-  }
-  if (command === "/pair") {
-    await handlePairCommand(args);
-    return;
-  }
-  await handlePairCommand(args);
-}
-async function handleSetupCommand(args: string[]): Promise<void> {
-  let envFile: string | undefined;
-  let host: string | undefined;
-  let port: number | undefined;
-  let dbPath: string | undefined;
-  let runtimePrefix: string | undefined;
-  let token: string | undefined;
-  let generateToken = true;
-  let dryRun = false;
-  let force = false;
-  let yes = false;
-  let json = false;
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === "--env-file" && i + 1 < args.length) envFile = args[++i];
-    else if (arg === "--host" && i + 1 < args.length) host = args[++i];
-    else if (arg === "--port" && i + 1 < args.length) port = parseInt(args[++i]!, 10);
-    else if (arg === "--db-path" && i + 1 < args.length) dbPath = args[++i];
-    else if (arg === "--runtime-prefix" && i + 1 < args.length) runtimePrefix = args[++i];
-    else if (arg === "--token" && i + 1 < args.length) token = args[++i];
-    else if (arg === "--generate-token") generateToken = true;
-    else if (arg === "--no-token") generateToken = false;
-    else if (arg === "--dry-run") dryRun = true;
-    else if (arg === "--force") force = true;
-    else if (arg === "--yes") yes = true;
-    else if (arg === "--json") json = true;
-    else throw new Error(`Unknown setup option "${arg}"`);
-  }
-  const plan = createSetupPlan({
-    ...(envFile ? { envFile } : {}),
-    ...(host ? { host } : {}),
-    ...(port !== undefined ? { port } : {}),
-    ...(dbPath ? { dbPath } : {}),
-    ...(runtimePrefix ? { runtimePrefix } : {}),
-    ...(token ? { token } : {}),
-    generateToken,
-    force,
-  });
-  if (!dryRun && !yes && await pathExists(plan.envFile)) {
-    const ok = await confirm(`Overwrite ${plan.envFile}?`);
-    if (!ok) {
-      console.log("Setup cancelled.");
-      return;
-    }
-  }
-  const result = await executeSetupPlan(plan, { dryRun, force });
-  if (json) console.log(JSON.stringify({ plan, output: result }, null, 2));
-  else console.log(dryRun ? formatSetupPlan(plan) : result);
-}
-async function handleDaemonCommand(args: string[]): Promise<void> {
-  const action = parseDaemonAction(args[0]);
-  let name: string | undefined;
-  let envFile: string | undefined;
-  let port: number | undefined;
-  let host: string | undefined;
-  let scope: DaemonScope | undefined;
-  let binaryPath: string | undefined;
-  let runtimePrefix: string | undefined;
-  const pathPrefix: string[] = [];
-  let start = false;
-  let enable = false;
-  let dryRun = false;
-  let force = false;
-  let yes = false;
-  let json = false;
-  for (let i = 1; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === "--name" && i + 1 < args.length) name = args[++i];
-    else if (arg === "--env-file" && i + 1 < args.length) envFile = args[++i];
-    else if (arg === "--port" && i + 1 < args.length) port = parseInt(args[++i]!, 10);
-    else if (arg === "--host" && i + 1 < args.length) host = args[++i];
-    else if (arg === "--user") scope = "user";
-    else if (arg === "--system") scope = "system";
-    else if (arg === "--binary" && i + 1 < args.length) binaryPath = args[++i];
-    else if (arg === "--runtime-prefix" && i + 1 < args.length) runtimePrefix = args[++i];
-    else if (arg === "--path-prefix" && i + 1 < args.length) pathPrefix.push(args[++i]!);
-    else if (arg === "--start") start = true;
-    else if (arg === "--enable") enable = true;
-    else if (arg === "--dry-run") dryRun = true;
-    else if (arg === "--force") force = true;
-    else if (arg === "--yes") yes = true;
-    else if (arg === "--json") json = true;
-    else throw new Error(`Unknown daemon option "${arg}"`);
-  }
-  if (action === "install" && !dryRun && !envFile && !(await pathExists(createSetupPlan().envFile))) {
-    const setupPlan = createSetupPlan({
-      ...(host ? { host } : {}),
-      ...(port !== undefined ? { port } : {}),
-      ...(runtimePrefix ? { runtimePrefix } : {}),
-    });
-    const ok = yes || await confirm(`Create daemon env file at ${setupPlan.envFile}?`);
-    if (!ok) throw new Error("Daemon install needs an env file. Run `agent-relay setup` first.");
-    console.log(await executeSetupPlan(setupPlan, { force }));
-  }
-  const env = await detectDaemonEnvironment();
-  const plan = createDaemonPlan({
-    action,
-    ...(name ? { name } : {}),
-    ...(envFile ? { envFile } : {}),
-    ...(port !== undefined ? { port } : {}),
-    ...(host ? { host } : {}),
-    ...(scope ? { scope } : {}),
-    ...(binaryPath ? { binaryPath } : {}),
-    ...(runtimePrefix ? { runtimePrefix } : {}),
-    ...(pathPrefix.length ? { pathPrefix } : {}),
-    start,
-    enable,
-  }, env);
-  if (!dryRun && !json && (action === "install" || action === "uninstall") && !yes) {
-    const ok = await confirm(
-      action === "install"
-        ? `Install ${plan.kind} ${plan.scope} daemon "${plan.name}"?`
-        : `Uninstall daemon "${plan.name}"?`,
-    );
-    if (!ok) {
-      console.log("Daemon command cancelled.");
-      return;
-    }
-  }
-  const result = await executeDaemonPlan(plan, { dryRun, force });
-  if (json) console.log(JSON.stringify({ plan: result.plan, output: result.output }, null, 2));
-  else console.log(dryRun ? formatDaemonPlan(plan) : result.output);
-}
-async function handleOrchestratorCommand(args: string[]): Promise<void> {
-  const subcommand = args[0];
-  if (subcommand !== "install") {
-    throw new Error("Usage: agent-relay orchestrator install --relay-url URL --token TOKEN|--bootstrap-token TOKEN [options]");
-  }
-  let relayUrl = "";
-  let token = "";
-  let bootstrapToken = "";
-  let id = sanitizeOrchestratorId(osHostname());
-  let baseDir = join(homedir(), "projects");
-  let providers = "claude,codex";
-  let apiPort = 4860;
-  let runtimePrefix = defaultRuntimePrefix();
-  let serviceName = "agent-relay-orchestrator";
-  let version = VERSION;
-  const pathPrefix: string[] = [];
-  let dryRun = false;
-  let yes = false;
-  let force = false;
-  let json = false;
-  for (let i = 1; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === "--relay-url" && i + 1 < args.length) relayUrl = args[++i]!;
-    else if (arg === "--token" && i + 1 < args.length) token = args[++i]!;
-    else if (arg === "--bootstrap-token" && i + 1 < args.length) bootstrapToken = args[++i]!;
-    else if (arg === "--id" && i + 1 < args.length) id = sanitizeOrchestratorId(args[++i]!);
-    else if (arg === "--base-dir" && i + 1 < args.length) baseDir = resolve(expandHomePath(args[++i]!));
-    else if (arg === "--providers" && i + 1 < args.length) providers = args[++i]!;
-    else if (arg === "--api-port" && i + 1 < args.length) apiPort = parseInt(args[++i]!, 10);
-    else if (arg === "--runtime-prefix" && i + 1 < args.length) runtimePrefix = resolve(expandHomePath(args[++i]!));
-    else if (arg === "--service-name" && i + 1 < args.length) serviceName = args[++i]!;
-    else if (arg === "--version" && i + 1 < args.length) version = args[++i]!;
-    else if (arg === "--path-prefix" && i + 1 < args.length) pathPrefix.push(resolve(expandHomePath(args[++i]!)));
-    else if (arg === "--dry-run") dryRun = true;
-    else if (arg === "--yes" || arg === "-y") yes = true;
-    else if (arg === "--force") force = true;
-    else if (arg === "--json") json = true;
-    else throw new Error(`Unknown orchestrator install option "${arg}"`);
-  }
-  if (!relayUrl) throw new Error("--relay-url is required");
-  if (!token && !bootstrapToken) throw new Error("--token or --bootstrap-token is required");
-  if (!Number.isInteger(apiPort) || apiPort < 1 || apiPort > 65535) throw new Error("--api-port must be an integer from 1 to 65535");
-  const providerList = providers.split(",").map((p) => p.trim()).filter(Boolean);
-  for (const provider of providerList) {
-    if (provider !== "claude" && provider !== "codex") throw new Error(`Unknown provider "${provider}". Expected claude or codex.`);
-  }
-  const detectedPathPrefix = [...pathPrefix, ...detectProviderPathPrefixes(providerList as Array<"claude" | "codex">)];
-  const uniquePathPrefix = [...new Set(detectedPathPrefix)];
-  const envToken = token || (dryRun || json ? "<runtime-token-from-bootstrap>" : await exchangeOrchestratorBootstrapToken(relayUrl, bootstrapToken, id, baseDir));
-  const envFile = defaultOrchestratorEnvFile();
-  const binaryPath = runtimeBinPath("agent-relay-orchestrator", runtimePrefix);
-  const envValues: Record<string, string> = {
-    AGENT_RELAY_URL: relayUrl,
-    AGENT_RELAY_TOKEN: envToken,
-    AGENT_RELAY_ORCHESTRATOR_ID: id,
-    AGENT_RELAY_ORCHESTRATOR_HOSTNAME: osHostname(),
-    AGENT_RELAY_ORCHESTRATOR_BASE_DIR: baseDir,
-    AGENT_RELAY_ORCHESTRATOR_PROVIDERS: providerList.join(","),
-    AGENT_RELAY_ORCHESTRATOR_API_PORT: String(apiPort),
-  };
-  if (uniquePathPrefix.length) envValues.AGENT_RELAY_ORCHESTRATOR_PATH_PREFIX = uniquePathPrefix.join(":");
-  const daemonEnv = await detectDaemonEnvironment();
-  const daemonPlan = createDaemonPlan({
-    action: "install",
-    name: serviceName,
-    envFile,
-    binaryPath,
-    runtimePrefix,
-    pathPrefix: uniquePathPrefix,
-    enable: true,
-    start: true,
-  }, daemonEnv);
-  const packageCommand = ["npm", "install", "--prefix", runtimePrefix, `agent-relay-runner@${version}`, `agent-relay-orchestrator@${version}`];
-  if (json || dryRun) {
-    const plan = {
-      id,
-      relayUrl,
-      baseDir,
-      providers: providerList,
-      apiPort,
-      runtimePrefix,
-      envFile,
-      binaryPath,
-      serviceName,
-      version,
-      pathPrefix: uniquePathPrefix,
-      packageCommand,
-      daemon: daemonPlan,
-    };
-    if (json) console.log(JSON.stringify({ plan }, null, 2));
-    else console.log(formatOrchestratorInstallPlan(plan));
-    return;
-  }
-  if (!yes) {
-    const ok = await confirm(`Install orchestrator "${id}" as daemon "${serviceName}"?`);
-    if (!ok) {
-      console.log("Orchestrator install cancelled.");
-      return;
-    }
-  }
-  mkdirSync(dirname(envFile), { recursive: true });
-  mkdirSync(baseDir, { recursive: true });
-  writeFileSync(envFile, renderEnvFile(envValues), { mode: 0o600 });
-  chmodSync(envFile, 0o600);
-  console.log(`Wrote ${envFile}`);
-  runChecked(packageCommand);
-  const result = await executeDaemonPlan(daemonPlan, { force });
-  console.log(result.output);
-  console.log(`Orchestrator install complete. Verify in Relay: ${relayUrl}`);
-}
-function defaultOrchestratorEnvFile(): string {
-  const platform = process.platform;
-  if (platform === "darwin") return join(homedir(), "Library", "Application Support", "agent-relay", "orchestrator.env");
-  return join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "agent-relay", "orchestrator.env");
-}
-async function exchangeOrchestratorBootstrapToken(relayUrl: string, bootstrapToken: string, id: string, baseDir: string): Promise<string> {
-  const response = await fetch(new URL("/api/orchestrators/bootstrap/exchange", relayUrl), {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      [RELAY_TOKEN_HEADER]: bootstrapToken,
-    },
-    body: JSON.stringify({ id, baseDir }),
-  });
-  const payload = await response.json().catch(() => null) as { token?: string; error?: string } | null;
-  if (!response.ok || !payload?.token) {
-    throw new Error(`bootstrap token exchange failed (${response.status}): ${payload?.error ?? response.statusText}`);
-  }
-  return payload.token;
-}
-function sanitizeOrchestratorId(value: string): string {
-  const clean = value.trim().replace(/\./g, "-").replace(/[^A-Za-z0-9_.-]+/g, "-").replace(/^-+|-+$/g, "");
-  if (!clean) throw new Error("--id must contain at least one letter or number");
-  return clean.slice(0, 120);
-}
-function expandHomePath(value: string): string {
-  if (value === "~") return homedir();
-  if (value.startsWith("~/")) return join(homedir(), value.slice(2));
-  return value;
-}
-function detectProviderPathPrefixes(providers: Array<"claude" | "codex">): string[] {
-  const prefixes: string[] = [];
-  for (const provider of providers) {
-    const path = resolveExecutableOnPath(provider);
-    if (path) prefixes.push(dirname(path));
-  }
-  return prefixes;
-}
-function resolveExecutableOnPath(command: string): string | undefined {
-  if (command.includes("/")) return existsSync(command) ? command : undefined;
-  for (const entry of (process.env.PATH ?? "").split(":")) {
-    if (!entry) continue;
-    const candidate = join(entry, command);
-    try {
-      if (existsSync(candidate) && statSync(candidate).isFile()) return candidate;
-    } catch {}
-  }
-  return undefined;
-}
-function runChecked(command: string[]): void {
-  console.log(`$ ${command.map(shellQuote).join(" ")}`);
-  const result = Bun.spawnSync(command, { stdin: "ignore", stdout: "inherit", stderr: "inherit" });
-  if (result.exitCode !== 0) throw new Error(`${command[0]} exited with code ${result.exitCode}`);
-}
-function formatOrchestratorInstallPlan(plan: {
-  id: string;
-  relayUrl: string;
-  baseDir: string;
-  providers: string[];
-  apiPort: number;
-  runtimePrefix: string;
-  envFile: string;
-  binaryPath: string;
-  serviceName: string;
-  version: string;
-  pathPrefix: string[];
-  packageCommand: string[];
-  daemon: ReturnType<typeof createDaemonPlan>;
-}): string {
-  const lines = [
-    "Orchestrator install plan",
-    `ID: ${plan.id}`,
-    `Relay: ${plan.relayUrl}`,
-    `Base dir: ${plan.baseDir}`,
-    `Providers: ${plan.providers.join(", ") || "(none)"}`,
-    `API port: ${plan.apiPort}`,
-    `Runtime prefix: ${plan.runtimePrefix}`,
-    `Env file: ${plan.envFile}`,
-    `Binary: ${plan.binaryPath}`,
-    `Service: ${plan.serviceName}`,
-    `Package version: ${plan.version}`,
-  ];
-  if (plan.pathPrefix.length) lines.push(`PATH prefix: ${plan.pathPrefix.join(":")}`);
-  lines.push("", "Package command:", `  ${plan.packageCommand.join(" ")}`);
-  lines.push("", formatDaemonPlan(plan.daemon));
-  return lines.join("\n");
-}
-function parseDaemonAction(value: string | undefined): DaemonAction {
-  if (!value || !DAEMON_ACTIONS.has(value as DaemonAction)) {
-    throw new Error("Usage: agent-relay daemon <install|uninstall|start|stop|restart|enable|disable|status|logs> [options]");
-  }
-  return value as DaemonAction;
-}
-async function handleDevCommand(args: string[]): Promise<void> {
-  const action = args[0];
-  if (!action) throw new Error("Usage: agent-relay dev <pack|install|service|smoke> [options]");
-  if (action === "pack") {
-    let packages: string | undefined;
-    let outDir: string | undefined;
-    let dryRun = false;
-    let json = false;
-    for (let i = 1; i < args.length; i++) {
-      const arg = args[i];
-      if (arg === "--packages" && i + 1 < args.length) packages = args[++i];
-      else if (arg === "--out" && i + 1 < args.length) outDir = args[++i];
-      else if (arg === "--dry-run") dryRun = true;
-      else if (arg === "--json") json = true;
-      else throw new Error(`Unknown dev pack option "${arg}"`);
-    }
-    const plan = createDevPackPlan({
-      ...(packages ? { packages: parseDevPackages(packages) } : {}),
-      ...(outDir ? { outDir } : {}),
-    });
-    const result = await executeDevPackPlan(plan, { dryRun });
-    if (json) console.log(JSON.stringify(result, null, 2));
-    else console.log(dryRun ? formatDevPackPlan(plan) : result.output);
-    return;
-  }
-  if (action === "install") {
-    let packages: string | undefined;
-    let outDir: string | undefined;
-    let prefix: string | undefined;
-    let dryRun = false;
-    let json = false;
-    for (let i = 1; i < args.length; i++) {
-      const arg = args[i];
-      if (arg === "--packages" && i + 1 < args.length) packages = args[++i];
-      else if (arg === "--out" && i + 1 < args.length) outDir = args[++i];
-      else if (arg === "--prefix" && i + 1 < args.length) prefix = args[++i];
-      else if (arg === "--dry-run") dryRun = true;
-      else if (arg === "--json") json = true;
-      else throw new Error(`Unknown dev install option "${arg}"`);
-    }
-    const plan = createDevInstallPlan({
-      ...(packages ? { packages: parseDevPackages(packages) } : {}),
-      ...(outDir ? { outDir } : {}),
-      ...(prefix ? { prefix } : {}),
-    });
-    const result = await executeDevInstallPlan(plan, { dryRun });
-    if (json) console.log(JSON.stringify(result, null, 2));
-    else console.log(dryRun ? formatDevInstallPlan(plan) : result.output);
-    return;
-  }
-  if (action === "service") {
-    await handleDevServiceCommand(args.slice(1));
-    return;
-  }
-  if (action === "smoke") {
-    let rootDir: string | undefined;
-    let providers: string | undefined;
-    let cwd: string | undefined;
-    let orchestratorId: string | undefined;
-    let timeoutMs: number | undefined;
-    for (let i = 1; i < args.length; i++) {
-      const arg = args[i];
-      if (arg === "--root" && i + 1 < args.length) rootDir = args[++i];
-      else if (arg === "--providers" && i + 1 < args.length) providers = args[++i];
-      else if (arg === "--cwd" && i + 1 < args.length) cwd = args[++i];
-      else if (arg === "--orchestrator" && i + 1 < args.length) orchestratorId = args[++i];
-      else if (arg === "--timeout" && i + 1 < args.length) timeoutMs = parseInt(args[++i]!, 10);
-      else throw new Error(`Unknown dev smoke option "${arg}"`);
-    }
-    const result = await executeDevSmoke({
-      ...(rootDir ? { rootDir } : {}),
-      ...(providers ? { providers } : {}),
-      ...(cwd ? { cwd } : {}),
-      ...(orchestratorId ? { orchestratorId } : {}),
-      ...(timeoutMs !== undefined ? { timeoutMs } : {}),
-    });
-    console.log(result.output);
-    return;
-  }
-  throw new Error("Usage: agent-relay dev <pack|install|service|smoke> [options]");
-}
-async function handleMemoryCommand(args: string[]): Promise<void> {
-  const section = args[0];
-  const action = args[1];
-  if (section !== "broker" || action !== "smoke") {
-    throw new Error("Usage: agent-relay memory broker smoke [--relay-url URL] [--token TOKEN] [--agent-id ID] [--scope SCOPE] [--tag TAG] [--no-cleanup] [--json]");
-  }
-  let baseUrl: string | undefined;
-  let token: string | undefined;
-  let agentId: string | undefined;
-  let scope: string | undefined;
-  let tag: string | undefined;
-  let cleanup = true;
-  let json = false;
-  for (let i = 2; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === "--relay-url" && i + 1 < args.length) baseUrl = args[++i];
-    else if (arg === "--token" && i + 1 < args.length) token = args[++i];
-    else if (arg === "--agent-id" && i + 1 < args.length) agentId = args[++i];
-    else if (arg === "--scope" && i + 1 < args.length) scope = args[++i];
-    else if (arg === "--tag" && i + 1 < args.length) tag = args[++i];
-    else if (arg === "--no-cleanup") cleanup = false;
-    else if (arg === "--json") json = true;
-    else throw new Error(`Unknown memory broker smoke option "${arg}"`);
-  }
-  const result = await runMemoryBrokerSmoke({
-    ...(baseUrl ? { baseUrl } : {}),
-    ...(token ? { token } : {}),
-    ...(agentId ? { agentId } : {}),
-    ...(scope ? { scope } : {}),
-    ...(tag ? { tag } : {}),
-    cleanup,
-  });
-  console.log(json ? JSON.stringify(result, null, 2) : formatMemoryBrokerSmokeResult(result));
-}
-async function handleDevServiceCommand(args: string[]): Promise<void> {
-  const action = parseDevServiceAction(args[0]);
-  let prefix: string | undefined;
-  let rootDir: string | undefined;
-  let port: number | undefined;
-  let apiPort: number | undefined;
-  let baseDir: string | undefined;
-  let orchestratorId: string | undefined;
-  let token: string | undefined;
-  let start = false;
-  let enable = false;
-  let dryRun = false;
-  let force = false;
-  let yes = false;
-  let json = false;
-  for (let i = 1; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === "--prefix" && i + 1 < args.length) prefix = args[++i];
-    else if (arg === "--root" && i + 1 < args.length) rootDir = args[++i];
-    else if (arg === "--port" && i + 1 < args.length) port = parseInt(args[++i]!, 10);
-    else if (arg === "--api-port" && i + 1 < args.length) apiPort = parseInt(args[++i]!, 10);
-    else if (arg === "--base-dir" && i + 1 < args.length) baseDir = args[++i];
-    else if (arg === "--orchestrator-id" && i + 1 < args.length) orchestratorId = args[++i];
-    else if (arg === "--token" && i + 1 < args.length) token = args[++i];
-    else if (arg === "--start") start = true;
-    else if (arg === "--enable") enable = true;
-    else if (arg === "--dry-run") dryRun = true;
-    else if (arg === "--force") force = true;
-    else if (arg === "--yes") yes = true;
-    else if (arg === "--json") json = true;
-    else throw new Error(`Unknown dev service option "${arg}"`);
-  }
-  const root = rootDir ?? defaultDevRoot();
-  const plan = createDevServicePlan({
-    action,
-    ...(prefix ? { prefix } : {}),
-    rootDir: root,
-    ...(port !== undefined ? { port } : {}),
-    ...(apiPort !== undefined ? { apiPort } : {}),
-    ...(baseDir ? { baseDir } : {}),
-    ...(orchestratorId ? { orchestratorId } : {}),
-    ...(token ? { token } : {}),
-    start,
-    enable,
-  });
-  if (!dryRun && !json && (action === "install" || action === "uninstall") && !yes) {
-    const ok = await confirm(action === "install" ? `Install dev service profile under ${root}?` : `Uninstall dev service profile under ${root}?`);
-    if (!ok) {
-      console.log("Dev service command cancelled.");
-      return;
-    }
-  }
-  const result = await executeDevServicePlan(plan, { dryRun, force });
-  if (json) console.log(JSON.stringify({ plan: result.plan, output: result.output }, null, 2));
-  else console.log(dryRun ? formatDevServicePlan(plan) : result.output);
-}
-function parseDevServiceAction(value: string | undefined): DevServiceAction {
-  const allowed = new Set<DevServiceAction>(["install", "uninstall", "start", "stop", "restart", "status", "logs"]);
-  if (!value || !allowed.has(value as DevServiceAction)) {
-    throw new Error("Usage: agent-relay dev service <install|uninstall|start|stop|restart|status|logs> [options]");
-  }
-  return value as DevServiceAction;
-}
-async function handlePairCommand(args: string[]): Promise<void> {
-  if (!args.length) throw new Error("Usage: agent-relay pair <target|create|status|accept|reject|hangup|send> [options]");
-  const knownActions = new Set(["create", "status", "list", "accept", "reject", "hangup", "disconnect", "send"]);
-  const action = knownActions.has(args[0]!) ? args[0]! : "create";
-  const rest = action === "create" && args[0] !== "create" ? args : args.slice(1);
-  if (action === "status" || action === "list") {
-    let agent: string | undefined = await detectAgentId();
-    let status: string | undefined;
-    let json = false;
-    for (let i = 0; i < rest.length; i++) {
-      const arg = rest[i];
-      if (arg === "--agent" && i + 1 < rest.length) agent = rest[++i];
-      else if (arg === "--status" && i + 1 < rest.length) status = rest[++i];
-      else if (arg === "--json") json = true;
-      else throw new Error(`Unknown pair status option "${arg}"`);
-    }
-    const query = new URLSearchParams();
-    if (agent) query.set("agent", agent);
-    if (status) query.set("status", status);
-    const pairs = await apiRequest("GET", `/api/pairs${query.size ? `?${query}` : ""}`);
-    if (json) console.log(JSON.stringify(pairs, null, 2));
-    else console.log(formatPairs(pairs as any[]));
-    return;
-  }
-  if (action === "create") {
-    const target = rest[0];
-    if (!target || target.startsWith("--")) throw new Error("Usage: agent-relay pair <target> [--from AGENT_ID] [--objective TEXT]");
-    let from = await detectAgentId();
-    let objective: string | undefined;
-    let ttlMs: number | undefined;
-    let json = false;
-    const objectiveParts: string[] = [];
-    for (let i = 1; i < rest.length; i++) {
-      const arg = rest[i];
-      if (arg === "--from" && i + 1 < rest.length) from = rest[++i];
-      else if (arg === "--objective" && i + 1 < rest.length) objective = rest[++i];
-      else if (arg === "--ttl-ms" && i + 1 < rest.length) ttlMs = parseInt(rest[++i]!, 10);
-      else if (arg === "--json") json = true;
-      else objectiveParts.push(arg!);
-    }
-    objective ??= objectiveParts.length ? objectiveParts.join(" ") : undefined;
-    if (!from) throw new Error("Could not detect current Agent Relay ID. Pass --from AGENT_ID or set AGENT_RELAY_ID.");
-    const result = await apiRequest("POST", "/api/pairs", { from, target, objective, ttlMs });
-    if (json) console.log(JSON.stringify(result, null, 2));
-    else {
-      const pair = (result as any).pair;
-      console.log(`Pair invite ${pair.id} sent: ${pair.requesterId} -> ${pair.targetId}`);
-    }
-    return;
-  }
-  if (action === "accept" || action === "reject" || action === "hangup" || action === "disconnect") {
-    const pairId = rest[0];
-    let agentId = await detectAgentId();
-    let reason: string | undefined;
-    let json = false;
-    let startIndex = 0;
-    if (pairId && !pairId.startsWith("--")) startIndex = 1;
-    for (let i = startIndex; i < rest.length; i++) {
-      const arg = rest[i];
-      if (arg === "--agent" && i + 1 < rest.length) agentId = rest[++i];
-      else if (arg === "--reason" && i + 1 < rest.length) reason = rest[++i];
-      else if (arg === "--json") json = true;
-      else throw new Error(`Unknown pair ${action} option "${arg}"`);
-    }
-    if (!agentId) throw new Error("Could not detect current Agent Relay ID. Pass --agent AGENT_ID or set AGENT_RELAY_ID.");
-    const resolvedPairId = pairId && !pairId.startsWith("--") ? pairId : await detectActivePairId(agentId);
-    if (!resolvedPairId) throw new Error(`Usage: agent-relay pair ${action} PAIR_ID --agent AGENT_ID`);
-    const endpoint = action === "disconnect" ? "hangup" : action;
-    const pair = await apiRequest("POST", `/api/pairs/${encodeURIComponent(resolvedPairId)}/${endpoint}`, { agentId, reason });
-    if (json) console.log(JSON.stringify(pair, null, 2));
-    else console.log(`Pair ${resolvedPairId}: ${(pair as any).status}`);
-    return;
-  }
-  if (action === "send") {
-    const pairId = rest[0];
-    if (!pairId || pairId.startsWith("--")) throw new Error("Usage: agent-relay pair send PAIR_ID --from AGENT_ID --body TEXT");
-    let from = await detectAgentId();
-    let body: string | undefined;
-    let subject: string | undefined;
-    let json = false;
-    for (let i = 1; i < rest.length; i++) {
-      const arg = rest[i];
-      if (arg === "--from" && i + 1 < rest.length) from = rest[++i];
-      else if (arg === "--body" && i + 1 < rest.length) body = rest[++i];
-      else if (arg === "--subject" && i + 1 < rest.length) subject = rest[++i];
-      else if (arg === "--json") json = true;
-      else throw new Error(`Unknown pair send option "${arg}"`);
-    }
-    if (!from) throw new Error("Could not detect current Agent Relay ID. Pass --from AGENT_ID or set AGENT_RELAY_ID.");
-    if (!body) throw new Error("--body TEXT required");
-    const result = await apiRequest("POST", `/api/pairs/${encodeURIComponent(pairId)}/messages`, { from, body, subject });
-    if (json) console.log(JSON.stringify(result, null, 2));
-    else console.log(`Pair message sent: ${(result as any).message.id}`);
-    return;
-  }
-}
-// The agent's own isolated-workspace id, published in AGENT_RELAY_WORKSPACE_JSON
-// by the orchestrator at spawn. Undefined for shared-workspace / non-managed agents.
-function currentWorkspaceId(): string | undefined {
-  const json = process.env.AGENT_RELAY_WORKSPACE_JSON;
-  if (!json) return undefined;
-  try {
-    const parsed = JSON.parse(json) as { id?: string };
-    return typeof parsed.id === "string" && parsed.id ? parsed.id : undefined;
-  } catch {
-    return undefined;
-  }
-}
-function formatWorkspaceStatus(ws: any, extra?: { guidance?: WorkspacePhaseView; landed?: string | null }): string {
-  // Render the directive projection so the agent gets "what does this mean / what
-  // do I do next" inline, not a bare enum it has to decode (#235). Computed
-  // client-side from the record (the projection is pure) unless the wait response
-  // already carried it.
-  const guidance = extra?.guidance ?? describeWorkspacePhase(ws);
-  const lines = [
-    `Workspace ${ws.id}`,
-    `  status:   ${ws.status}  (${guidance.phase}${guidance.actionNeeded ? "" : " — no action needed"})`,
-    `  branch:   ${ws.branch ?? "(none)"}`,
-    `  base:     ${ws.baseRef ?? "(none)"}`,
-    `  worktree: ${ws.worktreePath ?? "(none)"}`,
-    "",
-    `  ${guidance.headline}`,
-    `  ${guidance.hint}`,
-  ];
-  if (guidance.blockers.length) {
-    lines.push("", "  Blockers:");
-    for (const b of guidance.blockers) lines.push(`    - ${b}`);
-  }
-  if (guidance.nextActions.length) {
-    lines.push("", "  Next:");
-    for (const a of guidance.nextActions) lines.push(`    - ${a.cli ?? a.tool} — ${a.when}`);
-  }
-  if (extra?.landed) lines.push("", `  ${extra.landed}`);
-  return lines.join("\n");
-}
-// Poll a command to a terminal state (succeeded/failed). Returns undefined on
-// timeout so the caller can degrade to "dispatched, check later".
-async function pollCommand(id: string, timeoutMs: number): Promise<{ status?: string; result?: unknown; error?: string } | undefined> {
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
-    const cmd = await apiRequest("GET", `/api/commands/${encodeURIComponent(id)}`) as { status?: string; result?: unknown; error?: string };
-    if (cmd.status === "succeeded" || cmd.status === "failed") return cmd;
-    await new Promise((r) => setTimeout(r, 1000));
-  }
-  return undefined;
-}
-function formatDepsRefresh(result: WorkspaceDepsRefreshResult, checkOnly: boolean): string {
-  if (result.error && (!result.dirs || result.dirs.length === 0)) return `Deps ${checkOnly ? "check" : "refresh"}: ${result.error}`;
-  const lines: string[] = [];
-  for (const d of result.dirs) {
-    const icon = d.status === "installed" ? "↻" : d.status === "stale" ? "✗" : d.status === "failed" ? "!" : "✓";
-    const detail = d.status === "ok" ? "up to date"
-      : d.status === "installed" ? `reinstalled${d.wasSymlink ? " (was symlinked)" : ""}`
-      : d.status === "stale" ? `stale — missing ${d.missing?.join(", ") ?? "?"}`
-      : `failed — ${d.error ?? "unknown"}`;
-    lines.push(`  ${icon} ${d.dir}: ${detail}`);
-  }
-  const header = checkOnly
-    ? (result.stale ? "Deps check: stale dirs found — run `agent-relay workspace deps` to refresh" : "Deps check: all dirs up to date")
-    : (result.refreshed ? "Deps refreshed" : result.error ? "Deps refresh hit errors" : "Deps already up to date");
-  return [header, ...lines].join("\n");
-}
-// Self-service workspace lifecycle for agents in isolated worktrees (#205) plus
-// steward coordination (#208).
-//   status — read your workspace row     ready — hand off for review/landing
-//   land   — request a base merge (operator)   list — all workspaces
-//   diagnostics — joined briefing + recommended action
-//   claim/release — TTL'd steward lease auto-merge yields to
-//   cleanup-stale — guarded batch cleanup of stale worktrees (dry-run by default)
-async function handleWorkspaceCommand(args: string[]): Promise<void> {
-  const action = args[0];
-  const valid = new Set(["status", "ready", "land", "list", "diagnostics", "diag", "claim", "release", "cleanup-stale", "deps"]);
-  if (action === "--help" || action === "-h" || action === "help") {
-    console.log(WORKSPACE_USAGE);
-    return;
-  }
-  if (!action || !valid.has(action)) {
-    throw new Error(WORKSPACE_USAGE);
-  }
-  let id = currentWorkspaceId(), idExplicit = false; // idExplicit: --id was passed, not the ambient default (#307)
-  let strategy: string | undefined;
-  let purpose: string | undefined;
-  let repo: string | undefined;
-  let execute = false;
-  let check = false;
-  let json = false;
-  let wait = false;
-  let timeoutSeconds: number | undefined;
-  for (let i = 1; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === "--id" && i + 1 < args.length) { id = args[++i]; idExplicit = true; }
-    else if (arg === "--strategy" && i + 1 < args.length) strategy = args[++i];
-    else if (arg === "--purpose" && i + 1 < args.length) purpose = args[++i];
-    else if (arg === "--repo" && i + 1 < args.length) repo = args[++i];
-    else if (arg === "--execute") execute = true;
-    else if (arg === "--check") check = true;
-    else if (arg === "--refresh") check = false; // explicit no-op default for clarity
-    else if (arg === "--wait") wait = true;
-    else if (arg === "--timeout" && i + 1 < args.length) {
-      const parsed = Number.parseInt(args[++i]!, 10);
-      if (!Number.isFinite(parsed) || parsed <= 0) throw new Error("--timeout must be a positive number of seconds");
-      timeoutSeconds = parsed;
-    }
-    else if (arg === "--json") json = true;
-    else throw new Error(`Unknown workspace option "${arg}".`);
-  }
-  if (action === "list") {
-    console.log(JSON.stringify(await apiRequest("GET", "/api/workspaces"), null, 2));
-    return;
-  }
-  if (action === "cleanup-stale") {
-    const result = await apiRequest("POST", "/api/workspaces/actions/cleanup-stale", { repoRoot: repo, dryRun: !execute, ...(idExplicit && id ? { workspaceId: id } : {}) });
-    console.log(JSON.stringify(result, null, 2));
-    return;
-  }
-  if (!id) throw new Error("No current workspace detected (AGENT_RELAY_WORKSPACE_JSON unset). Pass --id WORKSPACE_ID — only isolated-workspace agents have one.");
-  if (action === "status") {
-    // --wait long-polls via the action endpoint (server blocks until the status
-    // changes — the blessed way to wait for an auto-merge to land, #235), and the
-    // response carries the directive projection + land receipt. Plain status is a
-    // bare GET; the projection is computed client-side for rendering.
-    if (wait) {
-      const res = await apiRequest("POST", `/api/workspaces/${encodeURIComponent(id)}/actions`, {
-        action: "status",
-        wait: true,
-        ...(timeoutSeconds ? { timeoutSeconds } : {}),
-      }) as { workspace?: any; guidance?: WorkspacePhaseView; landed?: string | null };
-      if (json) { console.log(JSON.stringify(res, null, 2)); return; }
-      console.log(formatWorkspaceStatus(res.workspace ?? res, { guidance: res.guidance, landed: res.landed }));
-      return;
-    }
-    const ws = await apiRequest("GET", `/api/workspaces/${encodeURIComponent(id)}`);
-    if (json) console.log(JSON.stringify(ws, null, 2));
-    else console.log(formatWorkspaceStatus(ws));
-    return;
-  }
-  if (action === "diagnostics" || action === "diag") {
-    console.log(JSON.stringify(await apiRequest("GET", `/api/workspaces/${encodeURIComponent(id)}/diagnostics`), null, 2));
-    return;
-  }
-  // Refresh (or --check) deps the shared symlinked node_modules has gone stale on
-  // (#51). Emits a host command; poll it to a terminal state so the agent gets a
-  // synchronous result and knows when to re-run typecheck.
-  if (action === "deps") {
-    const from = await detectAgentId();
-    const res = await apiRequest("POST", `/api/workspaces/${encodeURIComponent(id)}/actions`, { action: "deps-refresh", agentId: from, checkOnly: check }) as { command?: { id?: string } };
-    const commandId = res.command?.id;
-    const settled = commandId ? await pollCommand(commandId, 180_000) : undefined;
-    const result = (settled?.result ?? null) as WorkspaceDepsRefreshResult | null;
-    if (json) {
-      console.log(JSON.stringify(settled ?? res, null, 2));
-      return;
-    }
-    if (settled?.status === "failed") {
-      console.error(`Deps ${check ? "check" : "refresh"} failed: ${settled.error ?? "unknown error"}`);
-      process.exitCode = 1;
-      return;
-    }
-    if (!result) {
-      console.log(`Deps ${check ? "check" : "refresh"} dispatched (command ${commandId ?? "?"}) — host did not report back in time. Check \`agent-relay workspace deps --json\`.`);
-      return;
-    }
-    console.log(formatDepsRefresh(result, check));
-    return;
-  }
-  const from = await detectAgentId();
-  const actionBody: Record<string, unknown> =
-    action === "ready" ? { action: "request-review", agentId: from }
-    : action === "claim" ? { action: "claim", agentId: from, purpose }
-    : action === "release" ? { action: "release-claim", agentId: from }
-    : { action: "merge", agentId: from, ...(strategy ? { strategy } : {}) };
-  const result = await apiRequest("POST", `/api/workspaces/${encodeURIComponent(id)}/actions`, actionBody);
-  if (json) {
-    console.log(JSON.stringify(result, null, 2));
-    return;
-  }
-  if (action === "ready") {
-    // Print the whole contract up front so the agent isn't left decoding status
-    // enums over the next minutes (#235). `result.workspace` is the post-ready row.
-    const ws = (result as { workspace?: any }).workspace ?? { status: "review_requested" };
-    console.log(`Workspace ${id} marked ready.\n\n${readyContract(ws)}`);
-    return;
-  }
-  console.log(
-    action === "claim" ? `Workspace ${id} claimed${purpose ? ` (${purpose})` : ""} — auto-merge will yield until released or the claim expires.`
-    : action === "release" ? `Workspace ${id} claim released.`
-    : `Workspace ${id} merge requested (${strategy ?? "auto"}).`,
-  );
-}
-// Steward briefing commands (#208): queue of workspaces needing attention, a
-// per-workspace diagnostics inspection, and a check-command suggestion.
-async function handleStewardCommand(args: string[]): Promise<void> {
-  const action = args[0];
-  if (!action || !["queue", "inspect", "checks"].includes(action)) {
-    throw new Error("Usage: agent-relay steward <queue|inspect|checks> [WORKSPACE_ID] [--repo PATH] [--json]");
-  }
-  let repo: string | undefined;
-  let json = false;
-  const positional: string[] = [];
-  for (let i = 1; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === "--repo" && i + 1 < args.length) repo = args[++i];
-    else if (arg === "--json") json = true;
-    else if (!arg!.startsWith("--")) positional.push(arg!);
-    else throw new Error(`Unknown steward option "${arg}".`);
-  }
-  if (action === "queue") {
-    const all = await apiRequest("GET", "/api/workspaces") as any[];
-    const attention = new Set(["conflict", "review_requested", "merge_planned"]);
-    const queue = all.filter((ws) => attention.has(ws.status) && (!repo || ws.repoRoot === repo));
-    if (json) { console.log(JSON.stringify(queue, null, 2)); return; }
-    if (!queue.length) { console.log("Steward queue empty — no workspaces awaiting review, merge, or conflict resolution."); return; }
-    for (const ws of queue) console.log(`${ws.status.padEnd(16)} ${ws.branch ?? ws.id}  (${ws.repoRoot})`);
-    return;
-  }
-  const id = positional[0];
-  if (!id) throw new Error(`Usage: agent-relay steward ${action} WORKSPACE_ID [--json]`);
-  if (action === "inspect") {
-    console.log(JSON.stringify(await apiRequest("GET", `/api/workspaces/${encodeURIComponent(id)}/diagnostics`), null, 2));
-    return;
-  }
-  // checks: suggest validation commands from the workspace's changed files.
-  const diff = await apiRequest("GET", `/api/workspaces/${encodeURIComponent(id)}/diff?patch=0`) as any;
-  const files: string[] = Array.isArray(diff?.files) ? diff.files.map((f: any) => f.path) : [];
-  const checks = suggestStewardChecks(files);
-  console.log(JSON.stringify({ workspaceId: id, changedFiles: files.length, checks }, null, 2));
-}
-// Heuristic check suggestions from changed file paths. Repo-agnostic defaults a
-// steward can refine; cheaper than re-deriving from project docs every run.
-function suggestStewardChecks(files: string[]): Array<{ command: string; reason: string }> {
-  const checks: Array<{ command: string; reason: string }> = [];
-  const has = (re: RegExp) => files.some((f) => re.test(f));
-  if (has(/\.(ts|tsx|mts|cts)$/)) checks.push({ command: "bun run typecheck", reason: "TypeScript files changed" });
-  if (has(/\.test\.|(^|\/)tests?\//)) checks.push({ command: "bun test", reason: "test files changed" });
-  else if (files.length) checks.push({ command: "bun test", reason: "repo default" });
-  if (has(/(^|\/)dashboard\//)) checks.push({ command: "bun run build:dashboard", reason: "dashboard sources changed" });
-  return checks;
-}
-async function handleMessageCommand(args: string[], defaults: { claimable?: boolean } = {}): Promise<void> {
-  const target = args[0];
-  if (!target || target.startsWith("--")) {
-    throw new Error("Usage: agent-relay message <target> <body> [--from AGENT_ID] [--subject TEXT] [--channel NAME] [--reply-to ID] [--claimable]");
-  }
-  let from = await detectAgentId();
-  let subject: string | undefined;
-  let channel: string | undefined;
-  let replyTo: number | undefined;
-  let idempotencyKey: string | undefined;
-  let json = false;
-  let claimable = defaults.claimable ?? false;
-  const bodyParts: string[] = [];
-  for (let i = 1; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === "--from" && i + 1 < args.length) from = args[++i];
-    else if (arg === "--subject" && i + 1 < args.length) subject = args[++i];
-    else if (arg === "--channel" && i + 1 < args.length) channel = args[++i];
-    else if (arg === "--reply-to" && i + 1 < args.length) {
-      const parsed = Number.parseInt(args[++i]!, 10);
-      if (!Number.isFinite(parsed) || parsed <= 0) throw new Error("--reply-to must be a positive message id");
-      replyTo = parsed;
-    } else if (arg === "--idempotency-key" && i + 1 < args.length) idempotencyKey = args[++i];
-    else if (arg === "--claimable") claimable = true;
-    else if (arg === "--json") json = true;
-    else bodyParts.push(arg!);
-  }
-  const body = bodyParts.join(" ").trim();
-  if (!from) throw new Error("Could not detect current Agent Relay ID. Pass --from AGENT_ID or set AGENT_RELAY_ID.");
-  if (!body) throw new Error("Message body required.");
-  const message = await apiRequest("POST", "/api/messages", {
-    from,
-    to: target,
-    kind: claimable ? "task" : "chat",
-    subject,
-    channel,
-    body,
-    replyTo,
-    claimable,
-    payload: claimable ? { title: subject || "Claimable task" } : undefined,
-    idempotencyKey,
-  });
-  if (json) console.log(JSON.stringify(message, null, 2));
-  else console.log(`${claimable ? "Claimable message" : "Message"} sent: ${(message as any).id} -> ${target}`);
-}
-async function handleGetMessageCommand(args: string[]): Promise<void> {
-  const msgIdRaw = args[0];
-  if (!msgIdRaw || msgIdRaw.startsWith("--")) {
-    throw new Error("Usage: agent-relay get-message <messageId> [--json] [--body]");
-  }
-  const messageId = Number.parseInt(msgIdRaw, 10);
-  if (!Number.isFinite(messageId) || messageId <= 0) throw new Error("messageId must be a positive integer");
-  let json = false;
-  let bodyOnly = false;
-  for (let i = 1; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === "--json") json = true;
-    else if (arg === "--body") bodyOnly = true;
-    else throw new Error(`Unknown get-message option "${arg}".`);
-  }
-  const [message, artifacts, thread] = await Promise.all([
-    apiRequest("GET", `/api/messages/${messageId}`),
-    apiRequest("GET", `/api/messages/${messageId}/artifacts`).catch(() => []),
-    apiRequest("GET", `/api/messages/${messageId}/thread`).catch(() => []),
-  ]);
-  if (bodyOnly) {
-    console.log(String((message as any).body ?? ""));
-    return;
-  }
-  const msg = message as any;
-  const attachments = Array.isArray(msg.payload?.attachments)
-    ? msg.payload.attachments
-    : Array.isArray(msg.attachments)
-    ? msg.attachments
-    : [];
-  const payload = {
-    id: msg.id,
-    from: msg.from,
-    to: msg.to,
-    kind: msg.kind,
-    body: msg.body,
-    subject: msg.subject,
-    channel: msg.channel,
-    replyToId: msg.replyTo,
-    threadId: msg.threadId,
-    createdAt: msg.createdAt,
-    payload: msg.payload,
-    meta: msg.meta,
-    attachments,
-    message,
-    artifacts,
-    thread,
-    replyTo: msg.replyTo ? (thread as any[]).find((item) => item.id === msg.replyTo) ?? null : null,
-  };
-  if (json) {
-    console.log(JSON.stringify(payload, null, 2));
-    return;
-  }
-  console.log(formatMessageDetails(payload));
-}
-async function handleReplyCommand(args: string[]): Promise<void> {
-  const msgIdRaw = args[0];
-  if (!msgIdRaw || msgIdRaw.startsWith("--")) {
-    throw new Error("Usage: agent-relay /reply <messageId> <body|--stdin|--body-file PATH> [--from AGENT_ID] [--subject TEXT] [--format text|markdown|markdownv2] [--json]");
-  }
-  const replyTo = Number.parseInt(msgIdRaw, 10);
-  if (!Number.isFinite(replyTo) || replyTo <= 0) throw new Error("messageId must be a positive integer");
-  let from = await detectAgentId();
-  let subject: string | undefined;
-  let format: string | undefined;
-  let json = false;
-  let stdinBody = false;
-  let bodyFile: string | undefined;
-  const bodyParts: string[] = [];
-  for (let i = 1; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === "--from" && i + 1 < args.length) from = args[++i];
-    else if (arg === "--subject" && i + 1 < args.length) subject = args[++i];
-    else if (arg === "--stdin") stdinBody = true;
-    else if ((arg === "--body-file" || arg === "--file") && i + 1 < args.length) bodyFile = args[++i];
-    else if (arg === "--format" && i + 1 < args.length) {
-      const parsed = parseReplyFormat(args[++i]!);
-      if (!parsed) throw new Error("--format must be text, markdown, or markdownv2");
-      format = parsed;
-    }
-    else if (arg === "--json") json = true;
-    else bodyParts.push(arg!);
-  }
-  const body = (await resolveBodyInput({ bodyParts, stdinBody, bodyFile })).trim();
-  if (!from) throw new Error("Could not detect current Agent Relay ID. Pass --from AGENT_ID or set AGENT_RELAY_ID.");
-  if (!body) throw new Error("Reply body required.");
-  const prepared = await prepareReplyBody({ body, from, replyTo, format, subject });
-  const message = await apiRequest("POST", "/api/messages", {
-    from,
-    body: prepared.body,
-    subject: prepared.subject,
-    replyTo,
-    attachments: prepared.attachments,
-    payload: prepared.payload,
-  });
-  const msg = message as any;
-  if (json) console.log(JSON.stringify(msg, null, 2));
-  else console.log(`Reply sent: ${msg.id} -> ${msg.to} (reply to #${replyTo})`);
-}
-async function handleReactCommand(args: string[]): Promise<void> {
-  const msgIdRaw = args[0];
-  const emoji = args[1];
-  if (!msgIdRaw || msgIdRaw.startsWith("--") || !emoji || emoji.startsWith("--")) {
-    throw new Error("Usage: agent-relay /react <messageId> <emoji> [--from AGENT_ID] [--remove] [--json]");
-  }
-  const messageId = Number.parseInt(msgIdRaw, 10);
-  if (!Number.isFinite(messageId) || messageId <= 0) throw new Error("messageId must be a positive integer");
-  let actorId = await detectAgentId();
-  let action: "add" | "remove" = "add";
-  let json = false;
-  for (let i = 2; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === "--from" && i + 1 < args.length) actorId = args[++i];
-    else if (arg === "--remove") action = "remove";
-    else if (arg === "--json") json = true;
-    else throw new Error(`Unknown react option "${arg}"`);
-  }
-  if (!actorId) throw new Error("Could not detect current Agent Relay ID. Pass --from AGENT_ID or set AGENT_RELAY_ID.");
-  const message = await apiRequest("POST", `/api/messages/${messageId}/reactions`, {
-    actorId,
-    emoji,
-    action,
-  });
-  if (json) console.log(JSON.stringify(message, null, 2));
-  else console.log(`${action === "remove" ? "Reaction removed" : "Reaction sent"}: ${emoji} on #${messageId}`);
-}
-// Insights #185: capture the agent's end-of-session self-view as a bounded, structured
-// artifact (epic #183, docs/self-improvement.md). Manual rail in v0 — the agent or
-// operator runs this; the auto-trigger is chosen later on real data. The relay drops it
-// (409) if Insights or the introspection feature is toggled off.
-const INTROSPECT_FIELD_MAX = 600;
-async function handleIntrospectCommand(args: string[]): Promise<void> {
-  let from = await detectAgentId();
-  let project: string | undefined;
-  let sessionId: string | undefined;
-  let thin: string | undefined;
-  let workedAround: string | undefined;
-  let wouldHaveHelped: string | undefined;
-  let stdin = false;
-  let json = false;
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === "--from" && i + 1 < args.length) from = args[++i];
-    else if (arg === "--project" && i + 1 < args.length) project = args[++i];
-    else if (arg === "--session" && i + 1 < args.length) sessionId = args[++i];
-    else if (arg === "--thin" && i + 1 < args.length) thin = args[++i];
-    else if (arg === "--worked-around" && i + 1 < args.length) workedAround = args[++i];
-    else if (arg === "--would-have-helped" && i + 1 < args.length) wouldHaveHelped = args[++i];
-    else if (arg === "--stdin") stdin = true;
-    else if (arg === "--json") json = true;
-    else throw new Error(`Unknown introspect option "${arg}"`);
-  }
-  // --stdin reads a JSON object { thin, workedAround, wouldHaveHelped } — lets agents
-  // pipe a file without shell-quoting three multi-line fields.
-  if (stdin) {
-    const raw = (await readStdin()).trim();
-    if (!raw) throw new Error("--stdin given but no input received.");
-    let parsed: unknown;
-    try {
-      parsed = JSON.parse(raw);
-    } catch {
-      throw new Error('--stdin must be JSON: { "thin": "...", "workedAround": "...", "wouldHaveHelped": "..." }');
-    }
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("--stdin JSON must be an object");
-    const obj = parsed as Record<string, unknown>;
-    if (typeof obj.thin === "string") thin = obj.thin;
-    if (typeof obj.workedAround === "string") workedAround = obj.workedAround;
-    if (typeof obj.wouldHaveHelped === "string") wouldHaveHelped = obj.wouldHaveHelped;
-  }
-  const clip = (v: string | undefined): string => (v ?? "").trim().slice(0, INTROSPECT_FIELD_MAX);
-  const value = { thin: clip(thin), workedAround: clip(workedAround), wouldHaveHelped: clip(wouldHaveHelped) };
-  if (!value.thin && !value.workedAround && !value.wouldHaveHelped) {
-    throw new Error(
-      "Usage: agent-relay /introspect [--thin TEXT] [--worked-around TEXT] [--would-have-helped TEXT] [--stdin] [--from AGENT_ID]\n" +
-        "At least one field is required. The three fields: what context was thin, what you worked around, what would've helped.",
-    );
-  }
-  if (!from) throw new Error("Could not detect current Agent Relay ID. Pass --from AGENT_ID or set AGENT_RELAY_ID.");
-  const observation = await apiRequest("POST", "/api/insights/observations", {
-    sessionId: sessionId || process.env.AGENT_RELAY_PROVIDER_SESSION_ID || `manual-${from}`,
-    project: project || process.env.AGENT_RELAY_PROJECT || process.cwd().split("/").filter(Boolean).at(-1) || process.cwd(),
-    agentId: from,
-    signal: "introspection",
-    source: "agent",
-    value,
-  });
-  if (json) console.log(JSON.stringify(observation, null, 2));
-  else console.log("Introspection recorded.");
-}
-function parseReplyFormat(value: string): "text" | "markdown" | "markdownv2" | undefined {
-  const normalized = value.trim().toLowerCase();
-  if (normalized === "text" || normalized === "markdown" || normalized === "markdownv2") return normalized;
-  return undefined;
-}
-const MAX_DIRECT_REPLY_BODY_BYTES = Math.floor(MAX_BODY_BYTES * 0.75);
-async function resolveBodyInput(options: {
-  bodyParts: string[];
-  stdinBody: boolean;
-  bodyFile?: string;
-}): Promise<string> {
-  const sources = [
-    options.bodyParts.length > 0 ? "argv" : "",
-    options.stdinBody ? "stdin" : "",
-    options.bodyFile ? "body file" : "",
-  ].filter(Boolean);
-  if (sources.length > 1) throw new Error("Reply body must come from exactly one source: arguments, --stdin, or --body-file.");
-  if (options.stdinBody) return readStdin();
-  if (options.bodyFile) return readFileSync(resolve(options.bodyFile), "utf8");
-  return options.bodyParts.join(" ");
-}
-async function prepareReplyBody(options: {
-  body: string;
-  from: string;
-  replyTo: number;
-  format?: string;
-  subject?: string;
-}): Promise<{
-  body: string;
-  subject?: string;
-  attachments?: Array<Record<string, unknown>>;
-  payload?: Record<string, unknown>;
-}> {
-  const payload: Record<string, unknown> = options.format ? { message: { format: options.format } } : {};
-  if (encodedLength(options.body) <= MAX_DIRECT_REPLY_BODY_BYTES) {
-    return {
-      body: options.body,
-      subject: options.subject,
-      payload: Object.keys(payload).length ? payload : undefined,
-    };
-  }
-  const filename = `relay-reply-${options.replyTo}-${Date.now()}.${options.format === "markdown" ? "md" : "txt"}`;
-  const artifact = await apiRawRequest("POST", "/api/artifacts", options.body, {
-    "Content-Type": options.format === "markdown" ? "text/markdown; charset=utf-8" : "text/plain; charset=utf-8",
-    "X-Artifact-Filename": filename,
-    "X-Artifact-Kind": "document",
-    "X-Artifact-Sensitivity": "normal",
-  }) as { id: string; size?: number };
-  const preview = truncateText(options.body, 1800);
-  const body = [
-    `Full reply attached as Agent Relay artifact ${artifact.id} (${filename}).`,
-    "",
-    "Preview:",
-    preview,
-  ].join("\n");
-  return {
-    body,
-    subject: options.subject ?? "Long reply attached",
-    attachments: [{
-      artifactId: artifact.id,
-      kind: "document",
-      role: "report",
-      title: "Full reply",
-      metadata: {
-        source: "agent-relay-cli",
-        replyTo: options.replyTo,
-        originalBytes: encodedLength(options.body),
-      },
-    }],
-    payload: {
-      ...payload,
-      relay: {
-        longReply: true,
-        artifactId: artifact.id,
-        originalBytes: encodedLength(options.body),
-      },
-    },
-  };
-}
-function encodedLength(value: string): number {
-  return new TextEncoder().encode(value).byteLength;
-}
-function truncateText(value: string, maxChars: number): string {
-  if (value.length <= maxChars) return value;
-  return `${value.slice(0, maxChars)}\n\n[truncated preview; full content is attached]`;
-}
-function formatMessageDetails(payload: {
-  message: any;
-  artifacts: any;
-  thread: any;
-  replyTo: any;
-}): string {
-  const message = payload.message;
-  const lines = [
-    `Message #${message.id}`,
-    `From: ${message.from}`,
-    `To: ${message.to}`,
-    `Kind: ${message.kind}`,
-  ];
-  if (message.subject) lines.push(`Subject: ${message.subject}`);
-  if (message.channel) lines.push(`Channel: ${message.channel}`);
-  if (message.replyTo) lines.push(`Reply-to: #${message.replyTo}`);
-  if (message.threadId) lines.push(`Thread: #${message.threadId}`);
-  if (message.createdAt) lines.push(`Created: ${new Date(message.createdAt).toISOString()}`);
-  if (message.deliveryStatus) lines.push(`Delivery: ${message.deliveryStatus}`);
-  if (message.resolvedToAgent) lines.push(`Resolved-to: ${message.resolvedToAgent}`);
-  lines.push("", "Body:", String(message.body ?? ""));
-  if (message.payload && Object.keys(message.payload).length) {
-    lines.push("", "Payload:", JSON.stringify(message.payload, null, 2));
-  }
-  if (message.meta && Object.keys(message.meta).length) {
-    lines.push("", "Meta:", JSON.stringify(message.meta, null, 2));
-  }
-  const artifacts = Array.isArray(payload.artifacts) ? payload.artifacts : [];
-  if (artifacts.length) {
-    lines.push("", "Attachments:");
-    for (const artifact of artifacts) {
-      lines.push(`- ${artifact.id ?? artifact.artifactId} ${artifact.filename ? `(${artifact.filename}) ` : ""}${artifact.mediaType ?? artifact.kind ?? ""}`.trim());
-    }
-  } else if (Array.isArray(message.payload?.attachments) && message.payload.attachments.length) {
-    lines.push("", "Attachments:");
-    for (const attachment of message.payload.attachments) {
-      lines.push(`- ${attachment.artifactId}${attachment.title ? ` (${attachment.title})` : ""}`);
-    }
-  }
-  if (payload.replyTo) {
-    lines.push("", "Reply Context:", `Parent: #${payload.replyTo.id} from ${payload.replyTo.from} to ${payload.replyTo.to}`);
-  }
-  const thread = Array.isArray(payload.thread) ? payload.thread : [];
-  if (thread.length) {
-    lines.push("", "Thread:");
-    for (const item of thread) {
-      const subject = item.subject ? ` ${item.subject}` : "";
-      lines.push(`- #${item.id} ${item.from} -> ${item.to}${subject}`);
-    }
-  }
-  return lines.join("\n");
-}
-async function handleStatusCommand(args: string[]): Promise<void> {
-  let agentId = await detectAgentId();
-  let json = false;
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === "--agent" && i + 1 < args.length) agentId = args[++i];
-    else if (arg === "--json") json = true;
-    else throw new Error(`Unknown status option "${arg}"`);
-  }
-  const [stats, health, pairs, agent] = await Promise.all([
-    apiRequest("GET", "/api/stats"),
-    apiRequest("GET", "/api/health"),
-    agentId ? apiRequest("GET", `/api/pairs?agent=${encodeURIComponent(agentId)}`) : Promise.resolve([]),
-    agentId ? apiRequest("GET", `/api/agents/${encodeURIComponent(agentId)}`).catch(() => null) : Promise.resolve(null),
-  ]);
-  const payload = { agent, stats, health, pairs };
-  if (json) console.log(JSON.stringify(payload, null, 2));
-  else console.log(formatStatus(payload));
-}
-async function handleLabelCommand(args: string[]): Promise<void> {
-  let agentId = await detectAgentId();
-  let label: string | null | undefined;
-  let json = false;
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === "--agent" && i + 1 < args.length) agentId = args[++i];
-    else if (arg === "--clear") label = null;
-    else if (arg === "--json") json = true;
-    else if (label === undefined) label = args.slice(i).join(" ");
-  }
-  if (!agentId) throw new Error("Could not detect current Agent Relay ID. Pass --agent AGENT_ID or set AGENT_RELAY_ID.");
-  if (label === undefined) {
-    const agent = await apiRequest("GET", `/api/agents/${encodeURIComponent(agentId)}`) as { label?: string };
-    console.log(agent.label ?? "(no label)");
-    return;
-  }
-  const result = await apiRequest("PATCH", `/api/agents/${encodeURIComponent(agentId)}/label`, { label });
-  if (json) console.log(JSON.stringify(result, null, 2));
-  else console.log(label ? `Label set: ${label}` : "Label cleared.");
-}
-async function handleTagsCommand(args: string[]): Promise<void> {
-  let agentId = await detectAgentId();
-  let json = false;
-  let listOnly = false;
-  let add: string[] = [];
-  let remove: string[] = [];
-  const positional: string[] = [];
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === "--agent" && i + 1 < args.length) agentId = args[++i];
-    else if (arg === "--json") json = true;
-    else if (arg === "--list") listOnly = true;
-    else if (arg === "--add" && i + 1 < args.length) add = add.concat(splitTagArgs(args[++i]!));
-    else if (arg === "--remove" && i + 1 < args.length) remove = remove.concat(splitTagArgs(args[++i]!));
-    else positional.push(...splitTagArgs(arg!));
-  }
-  if (!agentId) throw new Error("Could not detect current Agent Relay ID. Pass --agent AGENT_ID or set AGENT_RELAY_ID.");
-  const current = await apiRequest("GET", `/api/agents/${encodeURIComponent(agentId)}`) as { tags?: string[] };
-  if (listOnly || (positional.length === 0 && add.length === 0 && remove.length === 0)) {
-    console.log((current.tags ?? []).join(", ") || "(no tags)");
-    return;
-  }
-  const next = positional.length > 0
-    ? uniqueStrings(positional)
-    : uniqueStrings([...(current.tags ?? []), ...add]).filter((tag) => !remove.includes(tag));
-  const updated = await apiRequest("PATCH", `/api/agents/${encodeURIComponent(agentId)}/tags`, { tags: next });
-  if (json) console.log(JSON.stringify(updated, null, 2));
-  else console.log(`Tags: ${next.join(", ") || "(none)"}`);
-}
-async function handleRecipeCommand(args: string[]): Promise<void> {
-  const action = args[0] ?? "list";
-  const rest = args.slice(1);
-  if (action === "list") {
-    const json = rest.includes("--json");
-    const recipes = await apiRequest("GET", "/api/recipes");
-    if (json) console.log(JSON.stringify(recipes, null, 2));
-    else console.log(formatRecipes(recipes as any[]));
-    return;
-  }
-  if (action === "show") {
-    const name = rest.find((arg) => !arg.startsWith("--"));
-    const json = rest.includes("--json");
-    if (!name) throw new Error("Usage: agent-relay recipe show NAME [--json]");
-    const recipe = await apiRequest("GET", `/api/recipes/${encodeURIComponent(name)}`);
-    if (json) console.log(JSON.stringify(recipe, null, 2));
-    else console.log(formatRecipe(recipe as any));
-    return;
-  }
-  if (action === "start") {
-    const name = rest[0];
-    if (!name || name.startsWith("--")) throw new Error("Usage: agent-relay recipe start NAME [--cwd PATH] [--orchestrator ID] [--by NAME] [--json]");
-    let cwd: string | undefined;
-    let orchestratorId: string | undefined;
-    let startedBy: string | undefined;
-    let json = false;
-    for (let i = 1; i < rest.length; i++) {
-      const arg = rest[i];
-      if (arg === "--cwd" && i + 1 < rest.length) cwd = rest[++i];
-      else if ((arg === "--orchestrator" || arg === "--orchestrator-id") && i + 1 < rest.length) orchestratorId = rest[++i];
-      else if (arg === "--by" && i + 1 < rest.length) startedBy = rest[++i];
-      else if (arg === "--json") json = true;
-      else throw new Error(`Unknown recipe start option "${arg}"`);
-    }
-    const result = await apiRequest("POST", "/api/recipes/start", { name, cwd, orchestratorId, startedBy });
-    if (json) console.log(JSON.stringify(result, null, 2));
-    else {
-      const payload = result as any;
-      console.log(`Recipe ${payload.instance.recipeName} started: ${payload.instance.id} (${payload.commands.length} command(s))`);
-    }
-    return;
-  }
-  if (action === "stop") {
-    const id = rest[0];
-    if (!id || id.startsWith("--")) throw new Error("Usage: agent-relay recipe stop INSTANCE_ID [--by NAME] [--json]");
-    let stoppedBy: string | undefined;
-    let json = false;
-    for (let i = 1; i < rest.length; i++) {
-      const arg = rest[i];
-      if (arg === "--by" && i + 1 < rest.length) stoppedBy = rest[++i];
-      else if (arg === "--json") json = true;
-      else throw new Error(`Unknown recipe stop option "${arg}"`);
-    }
-    const result = await apiRequest("POST", `/api/recipes/instances/${encodeURIComponent(id)}/stop`, { stoppedBy });
-    if (json) console.log(JSON.stringify(result, null, 2));
-    else {
-      const payload = result as any;
-      console.log(`Recipe ${payload.instance.recipeName} stopped: ${payload.instance.id} (${payload.commands.length} command(s))`);
-    }
-    return;
-  }
-  if (action === "status" || action === "instances") {
-    const json = rest.includes("--json");
-    const instances = await apiRequest("GET", "/api/recipes/instances");
-    if (json) console.log(JSON.stringify(instances, null, 2));
-    else console.log(formatRecipeInstances(instances as any[]));
-    return;
-  }
-  throw new Error("Usage: agent-relay recipe <list|show|start|stop|status> [options]");
-}
-async function handleTokenCommand(args: string[]): Promise<void> {
-  const action = args[0] ?? "list";
-  const rest = args.slice(1);
-  if (action === "list") {
-    const json = rest.includes("--json");
-    const tokens = await apiRequest("GET", "/api/tokens");
-    if (json) console.log(JSON.stringify(tokens, null, 2));
-    else console.log(formatTokens(tokens as any[]));
-    return;
-  }
-  if (action === "create") {
-    let role: string | undefined;
-    let sub: string | undefined;
-    let ttlSeconds: number | undefined;
-    let json = false;
-    let scope: string[] | undefined;
-    for (let i = 0; i < rest.length; i++) {
-      const arg = rest[i];
-      if (arg === "--role" && i + 1 < rest.length) role = rest[++i];
-      else if (arg === "--sub" && i + 1 < rest.length) sub = rest[++i];
-      else if ((arg === "--scope" || arg === "--scopes") && i + 1 < rest.length) scope = splitTagArgs(rest[++i]!);
-      else if ((arg === "--ttl" || arg === "--ttl-seconds") && i + 1 < rest.length) ttlSeconds = parseInt(rest[++i]!, 10);
-      else if (arg === "--json") json = true;
-      else throw new Error(`Unknown token create option "${arg}"`);
-    }
-    if (!role) throw new Error("Usage: agent-relay token create --role ROLE [--sub SUBJECT] [--scope a,b] [--ttl SECONDS]");
-    const result = await apiRequest("POST", "/api/tokens", { role, sub, scope, ttlSeconds, createdBy: "cli" });
-    if (json) console.log(JSON.stringify(result, null, 2));
-    else {
-      const payload = result as any;
-      console.log(payload.token);
-      console.error(`Issued ${payload.record.role} token ${payload.record.jti} for ${payload.record.sub}`);
-    }
-    return;
-  }
-  if (action === "revoke") {
-    const jti = rest.find((arg) => !arg.startsWith("--"));
-    if (!jti) throw new Error("Usage: agent-relay token revoke JTI");
-    await apiRequest("POST", `/api/tokens/${encodeURIComponent(jti)}/revoke`, {});
-    console.log(`Token revoked: ${jti}`);
-    return;
-  }
-  if (action === "verify") {
-    const token = rest.find((arg) => !arg.startsWith("--")) ?? process.env.AGENT_RELAY_TOKEN;
-    if (!token) throw new Error("Usage: agent-relay token verify TOKEN");
-    const payload = decodeJwtPayload(token);
-    if (!payload) throw new Error("not a component JWT");
-    let record: unknown = null;
-    if (typeof payload.jti === "string") {
-      record = await apiRequest("GET", `/api/tokens/${encodeURIComponent(payload.jti)}`).catch(() => null);
-    }
-    console.log(JSON.stringify({ payload, record }, null, 2));
-    return;
-  }
-  throw new Error("Usage: agent-relay token <create|list|revoke|verify> [options]");
-}
-async function apiRequest(method: string, path: string, body?: unknown): Promise<unknown> {
-  const baseUrl = process.env.AGENT_RELAY_URL || "http://127.0.0.1:4850";
-  const headers: Record<string, string> = {};
-  const token = process.env.AGENT_RELAY_TOKEN;
-  if (token) headers[RELAY_TOKEN_HEADER] = token;
-  if (body !== undefined) headers["Content-Type"] = "application/json";
-  const response = await fetch(new URL(path, baseUrl), {
-    method,
-    headers,
-    body: body === undefined ? undefined : JSON.stringify(body),
-  });
-  const text = await response.text();
-  const payload = text ? JSON.parse(text) : null;
-  if (!response.ok) {
-    const message = payload && typeof payload === "object" && "error" in payload ? String((payload as any).error) : text;
-    throw new Error(`agent-relay ${method} ${path} failed (${response.status}): ${message}`);
-  }
-  return payload;
-}
-async function apiRawRequest(method: string, path: string, body: BodyInit, extraHeaders: Record<string, string> = {}): Promise<unknown> {
-  const baseUrl = process.env.AGENT_RELAY_URL || "http://127.0.0.1:4850";
-  const headers: Record<string, string> = { ...extraHeaders };
-  const token = process.env.AGENT_RELAY_TOKEN;
-  if (token) headers[RELAY_TOKEN_HEADER] = token;
-  const response = await fetch(new URL(path, baseUrl), { method, headers, body });
-  const text = await response.text();
-  const payload = text ? JSON.parse(text) : null;
-  if (!response.ok) {
-    const message = payload && typeof payload === "object" && "error" in payload ? String((payload as any).error) : text;
-    throw new Error(`agent-relay ${method} ${path} failed (${response.status}): ${message}`);
-  }
-  return payload;
-}
-function splitTagArgs(raw: string): string[] {
-  return raw.split(",").map((tag) => tag.trim()).filter(Boolean);
-}
-function uniqueStrings(values: string[]): string[] {
-  return [...new Set(values.map((value) => value.trim()).filter(Boolean))];
-}
-async function detectActivePairId(agentId: string): Promise<string | undefined> {
-  const pairs = await apiRequest("GET", `/api/pairs?agent=${encodeURIComponent(agentId)}&status=active`) as Array<{ id?: string }>;
-  return Array.isArray(pairs) && typeof pairs[0]?.id === "string" ? pairs[0].id : undefined;
-}
-async function detectAgentId(): Promise<string | undefined> {
-  const explicit = process.env.AGENT_RELAY_ID;
-  if (explicit) return explicit;
-  const contextMatch = currentAgentContextId();
-  if (contextMatch) return contextMatch;
-  const cwd = process.cwd();
-  const explicitCodexState = process.env.AGENT_RELAY_CODEX_STATE_PATH
-    ? readCodexState(process.env.AGENT_RELAY_CODEX_STATE_PATH)
-    : null;
-  if (explicitCodexState?.agentId) return explicitCodexState.agentId;
-  const stateCandidates = [
-    resolve(cwd, "codex/runtime/live-state.json"),
-    ...collectCodexStateFiles(),
-  ].filter((path): path is string => Boolean(path));
-  const codexMatch = newestCodexAgentId(stateCandidates, cwd);
-  if (codexMatch) return codexMatch;
-  const claudeMatch = currentClaudeAgentId();
-  if (claudeMatch) return claudeMatch;
-  try {
-    const agents = await apiRequest("GET", "/api/agents") as Array<{ id?: string; status?: string; ready?: boolean; meta?: { cwd?: unknown }; lastSeen?: number }>;
-    const cwdAgents = agents
-      .filter((agent) => agent.status !== "offline" && agent.ready !== false && agent.meta?.cwd === cwd && typeof agent.id === "string")
-      .sort((a, b) => (b.lastSeen ?? 0) - (a.lastSeen ?? 0));
-    const uniqueAgentIds = uniqueStrings(cwdAgents.map((agent) => agent.id!));
-    return uniqueAgentIds.length === 1 ? uniqueAgentIds[0] : undefined;
-  } catch {
-    return undefined;
-  }
-}
-function currentAgentContextId(): string | undefined {
-  const explicitPath = process.env.AGENT_RELAY_CONTEXT_PATH;
-  if (explicitPath) {
-    const explicit = readAgentContext(explicitPath);
-    if (explicit?.agentId && contextMatchesCurrentProcess(explicit)) return explicit.agentId;
-  }
-  const candidates = collectAgentContextFiles();
-  const matches = candidates
-    .map((path) => readAgentContext(path))
-    .filter((context): context is AgentContextState => Boolean(context))
-    .filter((context) => contextMatchesCurrentProcess(context))
-    .filter((context) => context.matchEnv.some((match) => process.env[match.name] === match.value))
-    .sort((a, b) => b.updatedAtMs - a.updatedAtMs);
-  const uniqueAgentIds = uniqueStrings(matches.map((context) => context.agentId));
-  return uniqueAgentIds.length === 1 ? uniqueAgentIds[0] : undefined;
-}
-interface AgentContextState {
-  agentId: string;
-  cwd?: string;
-  updatedAtMs: number;
-  matchEnv: Array<{ name: string; value: string }>;
-}
-function contextMatchesCurrentProcess(context: AgentContextState): boolean {
-  return !context.cwd || context.cwd === process.cwd();
-}
-function readAgentContext(path: string): AgentContextState | null {
-  if (!existsSync(path)) return null;
-  try {
-    const parsed = JSON.parse(readFileSync(path, "utf8")) as {
-      agentId?: unknown;
-      cwd?: unknown;
-      updatedAt?: unknown;
-      matchEnv?: unknown;
-    };
-    if (typeof parsed.agentId !== "string" || !parsed.agentId) return null;
-    const matchEnv = Array.isArray(parsed.matchEnv)
-      ? parsed.matchEnv.flatMap((item) => {
-        if (!item || typeof item !== "object") return [];
-        const record = item as { name?: unknown; value?: unknown };
-        return typeof record.name === "string" && typeof record.value === "string"
-          ? [{ name: record.name, value: record.value }]
-          : [];
-      })
-      : [];
-    const stat = statSync(path);
-    const updatedAt = typeof parsed.updatedAt === "string" ? Date.parse(parsed.updatedAt) : Number.NaN;
-    return {
-      agentId: parsed.agentId,
-      cwd: typeof parsed.cwd === "string" ? parsed.cwd : undefined,
-      matchEnv,
-      updatedAtMs: Number.isFinite(updatedAt) ? updatedAt : stat.mtimeMs,
-    };
-  } catch {
-    return null;
-  }
-}
-function collectAgentContextFiles(): string[] {
-  const roots = [
-    join(process.env.HOME || "", ".agent-relay", "contexts"),
-  ].filter((root) => root && existsSync(root));
-  const files: string[] = [];
-  for (const root of roots) collectFiles(root, ".json", files, 2);
-  return files;
-}
-function newestCodexAgentId(paths: string[], cwd: string): string | undefined {
-  const states = paths
-    .map((path) => readCodexState(path))
-    .filter((state): state is { agentId: string; cwd?: string; updatedAtMs: number } => Boolean(state))
-    .sort((a, b) => b.updatedAtMs - a.updatedAtMs);
-  const cwdAgentIds = uniqueStrings(states.filter((state) => state.cwd === cwd).map((state) => state.agentId));
-  return cwdAgentIds.length === 1 ? cwdAgentIds[0] : undefined;
-}
-function readCodexState(path: string): { agentId: string; cwd?: string; updatedAtMs: number } | null {
-  if (!existsSync(path)) return null;
-  try {
-    const parsed = JSON.parse(readFileSync(path, "utf8")) as { agentId?: unknown; cwd?: unknown; updatedAt?: unknown };
-    if (typeof parsed.agentId !== "string" || !parsed.agentId) return null;
-    const stat = statSync(path);
-    const updatedAt = typeof parsed.updatedAt === "string" ? Date.parse(parsed.updatedAt) : Number.NaN;
-    return {
-      agentId: parsed.agentId,
-      cwd: typeof parsed.cwd === "string" ? parsed.cwd : undefined,
-      updatedAtMs: Number.isFinite(updatedAt) ? updatedAt : stat.mtimeMs,
-    };
-  } catch {
-    return null;
-  }
-}
-function collectCodexStateFiles(): string[] {
-  const roots = [
-    join(process.env.HOME || "", ".agent-relay", "codex", "runtime"),
-    resolve(process.cwd(), "codex", "runtime"),
-  ].filter((root) => root && existsSync(root));
-  const files: string[] = [];
-  for (const root of roots) collectFiles(root, "live-state.json", files, 4);
-  return files;
-}
-function collectFiles(dir: string, name: string, output: string[], depth: number): void {
-  if (depth < 0) return;
-  let entries: string[];
-  try {
-    entries = readdirSync(dir);
-  } catch {
-    return;
-  }
-  for (const entry of entries) {
-    const path = join(dir, entry);
-    try {
-      const stat = statSync(path);
-      if (stat.isDirectory()) collectFiles(path, name, output, depth - 1);
-      else if (name.startsWith(".") ? entry.endsWith(name) : entry === name) output.push(path);
-    } catch {
-      // Ignore state files that disappear while scanning.
-    }
-  }
-}
-function currentClaudeAgentId(): string | undefined {
-  const sessionKey = process.env.CLAUDE_CODE_SESSION_ID || String(process.ppid || "");
-  if (!sessionKey) return undefined;
-  const safeSessionKey = sessionKey.replace(/[^A-Za-z0-9_.:-]/g, "_");
-  const statePath = join("/tmp", `agent-relay-instance-${safeSessionKey}.state`);
-  if (!existsSync(statePath)) return undefined;
-  try {
-    return readFileSync(statePath, "utf8").split(/\r?\n/)[0]?.trim() || undefined;
-  } catch {
-    return undefined;
-  }
-}
-function formatPairs(pairs: any[]): string {
-  if (!pairs.length) return "No pair sessions.";
-  return pairs
-    .map((pair) => `${pair.id}  ${pair.status}  ${pair.requesterId} <-> ${pair.targetId}${pair.objective ? `  ${pair.objective}` : ""}`)
-    .join("\n");
-}
-function formatStatus(payload: any): string {
-  const agent = payload.agent;
-  const stats = payload.stats ?? {};
-  const health = payload.health ?? {};
-  const pairs = Array.isArray(payload.pairs) ? payload.pairs : [];
-  const activePair = pairs.find((pair: any) => pair.status === "active") ?? pairs.find((pair: any) => pair.status === "pending");
-  return [
-    `Relay: ${health.status ?? "unknown"}  version=${stats.version ?? "unknown"}`,
-    `Agents: ${stats.online ?? "?"}/${stats.agents ?? "?"} online  Messages: ${stats.messages ?? "?"}  Tasks: ${stats.openTasks ?? "?"}/${stats.tasks ?? "?"} open`,
-    agent
-      ? `Current: ${agent.id}  status=${agent.status}  ready=${agent.ready ? "yes" : "no"}  label=${agent.label ?? "(none)"}  tags=${(agent.tags ?? []).join(", ") || "(none)"}`
-      : "Current: unknown",
-    activePair
-      ? `Pair: ${activePair.id}  ${activePair.status}  ${activePair.requesterId} <-> ${activePair.targetId}`
-      : "Pair: none active",
-  ].join("\n");
-}
-function formatRecipes(recipes: any[]): string {
-  if (!recipes.length) return "No recipes.";
-  return recipes
-    .map((entry) => {
-      const recipe = entry.recipe ?? {};
-      const agents = Array.isArray(recipe.agents)
-        ? recipe.agents.map((agent: any) => `${agent.count ?? 1}x ${agent.provider}:${agent.role}`).join(", ")
-        : "no agents";
-      return `${entry.name}  ${entry.source}  ${agents}  ${recipe.description ?? ""}`.trim();
-    })
-    .join("\n");
-}
-function formatRecipe(entry: any): string {
-  const recipe = entry.recipe ?? {};
-  const agents = Array.isArray(recipe.agents)
-    ? recipe.agents.map((agent: any) => `  - ${agent.count ?? 1}x ${agent.provider}:${agent.role}`).join("\n")
-    : "  (none)";
-  return [
-    `${entry.name} (${entry.source})`,
-    recipe.description,
-    "Agents:",
-    agents,
-  ].filter(Boolean).join("\n");
-}
-function formatRecipeInstances(instances: any[]): string {
-  if (!instances.length) return "No recipe instances.";
-  return instances
-    .map((instance) => {
-      const agents = Array.isArray(instance.agents) ? instance.agents.length : 0;
-      return `${instance.id}  ${instance.status}  ${instance.recipeName}  agents=${agents}  cwd=${instance.cwd}`;
-    })
-    .join("\n");
-}
-function formatTokens(tokens: any[]): string {
-  if (!tokens.length) return "No component tokens.";
-  return tokens
-    .map((token) => {
-      const state = token.revokedAt ? "revoked" : token.expiresAt && token.expiresAt <= Math.floor(Date.now() / 1000) ? "expired" : "active";
-      return `${token.jti}  ${state}  ${token.role}  ${token.sub}  ${(token.scope ?? []).join(",")}`;
-    })
-    .join("\n");
-}
-function decodeJwtPayload(token: string): Record<string, unknown> | null {
-  const payload = token.split(".")[1];
-  if (!payload) return null;
-  try {
-    const parsed = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
-    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
-  } catch {
-    return null;
-  }
-}
-async function confirm(message: string): Promise<boolean> {
-  if (!input.isTTY) return false;
-  const rl = createInterface({ input, output });
-  try {
-    const answer = await rl.question(`${message} [y/N] `);
-    return answer.trim().toLowerCase() === "y" || answer.trim().toLowerCase() === "yes";
-  } finally {
-    rl.close();
-  }
-}
+// Barrel shim — cli.ts split into src/cli/ per-domain command modules (#294, epic
+// #291). Keeps the import sites (src/index.ts + cli.test.ts importing handleCli /
+// WORKSPACE_USAGE / removeLegacyCodexSessionStartHookToml) untouched.
+export * from "./cli/index";