tokenmaxxing 1.7.0 → 1.8.0

package/DESIGN.md

@@ -111,7 +111,9 @@ The decision engages at `five_hour >= 50%` (policy.greedySessionFloor): from the
 
 **Shipped since (0.13.0):** Codex as a second pool, parallel state (`codex-accounts.json`, `codex-creds/`, own flock), same pace-pressure policy. Codex differences that shaped it: restart IS the switch (a running codex refuses another account's credential), usage is a free direct GET with epoch resets and a duration-classified window set (the weekly window is primary on current plans), the refresh token rotates with reuse punished (harvest-by-true-owner, persist every rotation), and codex's new Stop-hook system drives the auto-swap through a codex supervisor shim that respawns `codex resume <session-id>` (hooks must be trusted once via `/hooks`). Sibling sessions left on ANY non-live account are reconciled cross-session (owner decisions 2026-07-20; a non-live session cannot refresh cross-account and would wedge at token expiry, healthy or not): the deciding actor drops a reconcile marker addressed to the sibling's supervisor, and the sibling's own Stop hook promotes it into a respawn onto the live account at its next turn boundary - the only safe respawn point - while a blocked live seat never receives a signal.
 
-**Non-goals:** an API/MITM proxy; reimplementing OAuth beyond the single refresh-grant call in the swap.
+**Shipped since (relay companion):** `tokenmaxxing relay` hosts durable tmux workers for cheap host subagents. Claude `--permission-mode` vocabulary (default `auto`), Codex sandbox mapping, per-session flock + registry under `relay/`, additive turn-done markers (never `respawn/`), and `permission-needed` stdout pings decided by main. Host finish hooks still run on every return including pings. Skill + agents live under `agent-plugin/` (`relay-session`, `tokenmaxxing-claude`, `tokenmaxxing-codex`). Docs: `docs/content/docs/commands.mdx`, `state-directory.mdx`, `agent-plugin.mdx`.
+
+**Non-goals:** an API/MITM proxy; reimplementing OAuth beyond the single refresh-grant call in the swap; Slack serve as the relay bus; soft concurrency caps; Cloud Agents without local tmux.
 
 ---
 

package/agent-plugin/agents/tokenmaxxing-claude.md

@@ -0,0 +1,43 @@
+---
+name: tokenmaxxing-claude
+description: Cheap shell-only relay to a durable Claude Code worker via tokenmaxxing relay. Use for long-running Claude sessions with permission pings back to main.
+model: inherit
+readonly: false
+is_background: false
+---
+
+# Tokenmaxxing Claude relay
+
+You are a thin shell. Do not edit files yourself. Do not spawn nested Task/Agent children. Only call `tokenmaxxing relay` (alias `xx relay`).
+
+## Commands
+
+```bash
+tokenmaxxing relay turn --worker claude --permission-mode auto --cwd <dir> --session <uuid-or-omit> "<prompt>"
+tokenmaxxing relay decide --session <uuid> --approve
+tokenmaxxing relay decide --session <uuid> --deny
+tokenmaxxing relay set-permission-mode --session <uuid> --permission-mode <mode>
+tokenmaxxing relay status --session <uuid>
+tokenmaxxing relay destroy --session <uuid>
+```
+
+Default permission mode is `auto`. Modes: `default` (alias `manual`), `acceptEdits`, `plan`, `auto`, `dontAsk`, `bypassPermissions`.
+
+## Stdout protocol
+
+```
+session: <id>
+permission-mode: <mode>
+# turn output OR:
+permission-needed: <requestId>
+summary: <one line>
+detail: <flagged action>
+session: <id>
+permission-mode: auto
+```
+
+On `permission-needed`, return that block to main and stop. Main decides (or auto-approves when Cursor Run Mode is Run Everything, or when Claude main is `bypassPermissions`). Then you run `relay decide` and wait.
+
+## Finish hooks
+
+Your host finish hook (`subagentStop` / `SubagentStop`) must run on every return, including permission-needed. A permission park is not a worker Stop.

package/agent-plugin/agents/tokenmaxxing-codex.md

@@ -0,0 +1,40 @@
+---
+name: tokenmaxxing-codex
+description: Cheap shell-only relay to a durable Codex worker via tokenmaxxing relay. Claude permission-mode names map to Codex sandbox flags.
+model: inherit
+readonly: false
+is_background: false
+---
+
+# Tokenmaxxing Codex relay
+
+You are a thin shell. Do not edit files yourself. Do not spawn nested Task/Agent children. Only call `tokenmaxxing relay` (alias `xx relay`).
+
+## Commands
+
+```bash
+tokenmaxxing relay turn --worker codex --permission-mode auto --cwd <dir> --session <uuid-or-omit> "<prompt>"
+tokenmaxxing relay decide --session <uuid> --approve
+tokenmaxxing relay decide --session <uuid> --deny
+tokenmaxxing relay set-permission-mode --session <uuid> --permission-mode <mode>
+tokenmaxxing relay status --session <uuid>
+tokenmaxxing relay destroy --session <uuid>
+```
+
+CLI still speaks Claude permission-mode names. Codex mapping:
+
+| Mode | Codex flags |
+|---|---|
+| `plan` / `default` | `--sandbox read-only` + ask-for-approval on |
+| `acceptEdits` | `--sandbox workspace-write` |
+| `auto` | workspace-write + ask-for-approval |
+| `dontAsk` | read-only + approval never |
+| `bypassPermissions` | `--sandbox danger-full-access` + approval off |
+
+## Stdout protocol
+
+Same as the Claude relay agent. On `permission-needed`, return the block to main; then `relay decide`.
+
+## Finish hooks
+
+Host finish hooks run on every return including permission-needed. Worker Stop still runs only on real turn finish.

package/agent-plugin/hooks/cursor-relay.json

@@ -0,0 +1,14 @@
+{
+  "version": 1,
+  "hooks": {
+    "tokenmaxxingRelay": {
+      "description": "tokenmaxxing-owned Cursor hook group for relay finish behavior. Host finish hooks must still run on every subagent return including permission-needed.",
+      "subagentStop": [
+        {
+          "type": "command",
+          "command": "/usr/bin/true"
+        }
+      ]
+    }
+  }
+}

package/agent-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "tokenmaxxing",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Pool Claude Code and Codex logins, switch on pace pressure, and expose safe ops tools to agent clients.",
   "author": {
     "name": "anaclumos",
@@ -10,5 +10,11 @@
   "homepage": "https://github.com/anaclumos/tokenmaxxing",
   "repository": "https://github.com/anaclumos/tokenmaxxing",
   "license": "MIT",
-  "keywords": ["claude", "codex", "quota", "account-switching", "mcp"]
+  "keywords": [
+    "claude",
+    "codex",
+    "quota",
+    "account-switching",
+    "mcp"
+  ]
 }

package/agent-plugin/skills/relay-session/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: relay-session
+description: Run durable Claude Code or Codex workers through tokenmaxxing relay (tmux). Use when a host agent needs a long-lived pooled worker, permission pings to main, or tokenmaxxing-claude / tokenmaxxing-codex agents.
+---
+
+# Relay session
+
+Host agents stay cheap. They shell into `tokenmaxxing relay`, which owns a durable tmux worker (Claude Code or Codex via tokenmaxxing). High-churn concurrent sessions are expected.
+
+Install templates: `tokenmaxxing relay install --target cursor|claude|all`.
+
+## Claude worker permission modes
+
+CLI: `claude --permission-mode <mode>` / `relay set-permission-mode --permission-mode <mode>`.
+
+| Mode | What runs without asking |
+|---|---|
+| `default` (alias `manual`) | Reads only |
+| `acceptEdits` | Reads, file edits, common filesystem cmds in cwd |
+| `plan` | Reads (+ classifier-approved cmds when auto available) |
+| `auto` | Everything with background safety classifier (**relay default**) |
+| `dontAsk` | Only pre-approved tools; else deny |
+| `bypassPermissions` | Everything (needs allow-dangerously flags) |
+
+Claude `auto` is classifier-assisted autonomy, not "defer to main". Relay pings main only when the worker would still prompt.
+
+## Cursor Run Modes (main only)
+
+| Run Mode | Role for relay |
+|---|---|
+| Auto-review | Main decides each ping or escalates to the user |
+| Allowlist | Main decides / escalates |
+| Run Everything | Main auto-`relay decide --approve` on worker pings |
+
+Do not probe undocumented APIs for main's Run Mode. Main states or infers it.
+
+If Claude main is itself in `bypassPermissions`, auto-approve worker pings the same way.
+
+## Codex mapping
+
+| Claude mode | Codex flags |
+|---|---|
+| `plan` / `default` | `--sandbox read-only` + ask-for-approval on |
+| `acceptEdits` | `--sandbox workspace-write` |
+| `auto` | workspace-write + ask-for-approval |
+| `dontAsk` | read-only + approval never |
+| `bypassPermissions` | `--sandbox danger-full-access` + approval off |
+
+## Shared stdout protocol
+
+```
+session: <id>
+permission-mode: <mode>
+# turn output OR:
+permission-needed: <requestId>
+summary: <one line>
+detail: <flagged action>
+session: <id>
+permission-mode: auto
+```
+
+## Commands
+
+| Command | Job |
+|---|---|
+| `relay turn` | Ensure session, send prompt, wait until turn-done or permission-needed |
+| `relay decide` | Approve/deny pending ping; resume worker |
+| `relay set-permission-mode` | Change live worker mode |
+| `relay status` / `destroy` / `gc` | Inspect, tear down, reap |
+| `relay install` / `relay config` | Host templates + relay.json |
+
+Flags: `--worker claude|codex`, `--session`, `--cwd`, `--permission-mode`, prompt via argv/stdin.
+
+## Finish hooks
+
+1. Cheap relay host finish hooks (`subagentStop` / `SubagentStop`) fire on every return, including `permission-needed`.
+2. Worker Stop / Codex Stop still run on real turn finish (pool logic unchanged).
+3. Relay turn-done markers are additive under `$TOKENMAXXING_HOME/relay/turn-done/`. Permission park is not a fake worker Stop. Never write into `respawn/`.
+
+## Cursor IPC matrix
+
+| Contract | Relay support |
+|---|---|
+| Task / custom agent prompt | Primary in |
+| Task final message | Primary out (delta or permission-needed) |
+| Task resume / interrupt | Continue with decide / set-permission-mode / next turn |
+| Foreground / background + completion notify | Prefer foreground under modes that still prompt |
+| Frontmatter model / readonly / is_background / tools | Shell-only templates; configurable cheap model |
+| `/name` delegate | Same agents |
+| subagentStart / subagentStop (+ followup_message) | Optional hooks; finish hooks always run |
+| Task preToolUse / postToolUse | Optional |
+| UpdateCurrentStep | UI phases only, not permission channel |
+| Nesting | Relay must not spawn Task children |
+
+## Claude IPC matrix
+
+| Contract | Relay support |
+|---|---|
+| Agent tool prompt / final result | Primary |
+| SendMessage resume / mid-run | Primary continue path |
+| Background + completion notify | Supported |
+| Fork / `/subtask` | Supported if host uses it |
+| Permission UI bubble | Orthogonal; do not suppress |
+| PermissionRequest / Notification | Optional hooks; worker pings stay stdout protocol |
+| SubagentStart / SubagentStop | Finish hooks always run on every return including pings |
+| Pre/PostToolUse (incl. on Agent) | Optional |
+| Agent teams mailbox / task list | Same stdout contract over team delivery |
+| Cross-session SendMessage | Supported; peer messages never carry user authority |
+| subagentStatusLine | UI only |
+
+## Hard stops
+
+- Never pattern-kill tmux. Destroy by exact session name only.
+- Never print credentials or OAuth tokens.
+- Never spawn nested Task/Agent from the cheap relay agent.
+- Prefer `tokenmaxxing-claude` / `tokenmaxxing-codex` agents over ad-hoc shells.
+
+See [references/ipc.md](references/ipc.md).

package/agent-plugin/skills/relay-session/references/ipc.md

@@ -0,0 +1,23 @@
+# Relay IPC checklist
+
+## Cursor
+
+- In: Task prompt, `/tokenmaxxing-claude`, `/tokenmaxxing-codex`
+- Out: final message with stdout protocol
+- Continue: Task resume after `relay decide` or `relay set-permission-mode`
+- Finish: `subagentStop` always (including permission-needed returns)
+- Optional: `subagentStart`, Task `preToolUse` / `postToolUse`
+- Not a permission channel: `UpdateCurrentStep`, transcripts
+
+## Claude Code
+
+- In: Agent tool prompt
+- Out: Agent final result with stdout protocol
+- Continue: SendMessage / next Agent turn after decide
+- Finish: `SubagentStop` always (including permission-needed returns)
+- Optional: `PermissionRequest` / `Notification` on main; worker pings still use relay stdout
+- UI only: `subagentStatusLine`
+
+## Finish-hook rule
+
+Permission park returns to main without faking a worker Stop. Worker Stop hooks still run when the worker actually finishes a turn and write additive `relay/turn-done/<session>` markers only.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Automatic Claude Code account switching: pool multiple accounts and hot-swap when quota fills, resuming your session on the fresh account.",
   "type": "module",
   "license": "MIT",

package/src/cli/codexinit.ts

@@ -11,7 +11,7 @@ import { codexIdentityOf, readLiveCodexAuth, writeParkedCodexAuth } from "../lib
 import { CodexUsageReadError, fetchCodexUsage } from "../lib/codexusage.ts";
 import { loadCodexAccounts, saveCodexAccounts } from "../lib/codexstate.ts";
 import { loadConfig, pinBinOverride } from "../lib/state.ts";
-import { installCodexSupervisor, codexSupervisorLink, ensurePathInRc, shellRcPath } from "../lib/install.ts";
+import { installCodexSupervisor, codexSupervisorLink, ensurePathInRc, managedShellRcSkipLines, shellRcPath } from "../lib/install.ts";
 import { withLock } from "../lib/lock.ts";
 import { presentCodexAccountIds } from "../lib/codexpresence.ts";
 import { codexCredItemFor, codexPaths } from "../lib/paths.ts";
@@ -137,7 +137,16 @@ export async function cmdCodexInit(): Promise<number> {
 
   installCodexSupervisor();
   const rc = shellRcPath();
-  if (rc) ensurePathInRc(rc);
+  if (rc) {
+    const pathOutcome = ensurePathInRc(rc);
+    if (pathOutcome === "skipped") {
+      const hint = managedShellRcSkipLines();
+      console.log();
+      console.log(c.yellow(`⚠ ${hint.headline}`));
+      console.log(c.yellow(`  ${hint.detail}`));
+      console.log(c.yellow(`  ${hint.exportLine}`));
+    }
+  }
 
   console.log();
   console.log(`${c.green("✓")} imported codex account ${c.bold(account.label)} (${account.planType ?? "?"})`);

package/src/cli/init.ts

@@ -8,14 +8,15 @@ import { refreshCredential, isAccessTokenExpiring, fetchTokenOrg } from "../lib/
 import { withClaudeRefreshLock } from "../lib/claudelock.ts";
 import { loadAccounts, saveAccounts, loadConfig, pinBinOverride } from "../lib/state.ts";
 import { withLock } from "../lib/lock.ts";
-import { installSupervisor, shellRcPath, ensurePathInRc, timerActivationHint, type InstallOutcome } from "../lib/install.ts";
+import { installSupervisor, shellRcPath, ensurePathInRc, managedShellRcSkipLines, timerActivationHint, type InstallOutcome } from "../lib/install.ts";
 import { resolveVerifiedClaude } from "../lib/claudebin.ts";
 import { credItemFor, paths } from "../lib/paths.ts";
 import { CredentialBlobSchema, type Account } from "../lib/types.ts";
 import { c, claudeTierLabel } from "./render.ts";
 
 /** Put the supervisor bin dir on PATH via the user's shell rc (idempotent).
- *  Falls back to the manual instruction when the shell is unknown. */
+ *  Falls back to the manual instruction when the shell is unknown or the rc
+ *  target is immutable (Home Manager / nix-store). */
 function ensurePathAhead(): void {
   const rc = shellRcPath();
   if (!rc) {
@@ -24,7 +25,12 @@ function ensurePathAhead(): void {
   }
   const outcome = ensurePathInRc(rc);
   if (outcome === "added") console.log(`${c.green("✓")} added ${paths.binDir} to PATH in ${rc} - restart your shell (or \`source ${rc}\`)`);
-  else console.log(c.yellow(`⚠ PATH line already in ${rc} - restart your shell to pick it up`));
+  else if (outcome === "skipped") {
+    const hint = managedShellRcSkipLines();
+    console.log(c.yellow(`⚠ ${hint.headline}`));
+    console.log(c.yellow(`  ${hint.detail}`));
+    console.log(c.yellow(`  ${hint.exportLine}`));
+  } else console.log(c.yellow(`⚠ PATH line already in ${rc} - restart your shell to pick it up`));
 }
 
 function reportTimer(out: InstallOutcome): void {

package/src/cli/relay.ts

@@ -0,0 +1,323 @@
+// `tokenmaxxing relay` - host-agnostic durable tmux relay companion.
+
+import { cwd } from "node:process";
+import { z } from "zod";
+import { c } from "./render.ts";
+import {
+  DEFAULT_RELAY_CONFIG,
+  loadRelayConfig,
+  mergeRelayConfigFile,
+  writeRelayConfig,
+  type RelayConfigFile,
+} from "../lib/relay/config.ts";
+import { runDecide } from "../lib/relay/decide.ts";
+import { destroySession, gcSessions, statusRows } from "../lib/relay/gc.ts";
+import { installRelayHosts, type InstallTarget } from "../lib/relay/install.ts";
+import { parsePermissionMode, tryParsePermissionMode } from "../lib/relay/modes.ts";
+import { runTurn } from "../lib/relay/turn.ts";
+import { setLivePermissionMode } from "../lib/relay/worker.ts";
+import { existsSync, readFileSync } from "node:fs";
+import { paths } from "../lib/paths.ts";
+
+function printHelp(): void {
+  console.log(`${c.bold("tokenmaxxing relay")} - durable tmux workers for host agents
+
+  ${c.cyan("relay turn")} [--worker claude|codex] [--session <uuid>] [--cwd <dir>]
+              [--permission-mode <mode>] [prompt...]
+              Ensure session, send prompt (argv or stdin), wait for turn-done or permission-needed
+  ${c.cyan("relay decide")} --session <uuid> [--request <id>] --approve|--deny [--no-wait]
+              Approve or deny a pending permission ping; by default wait for the next marker
+  ${c.cyan("relay set-permission-mode")} --session <uuid> --permission-mode <mode>
+              Change the live worker permission mode
+  ${c.cyan("relay status")} [--session <uuid>]
+              Inspect relay sessions
+  ${c.cyan("relay destroy")} --session <uuid>
+              Tear down one session (exact tmux name)
+  ${c.cyan("relay gc")}
+              Reap dead or idle sessions (idleTtlMs)
+  ${c.cyan("relay install")} [--target cursor|claude|all]
+              Write agent templates and merge tokenmaxxing-owned hook keys
+  ${c.cyan("relay config")} [get|set|show]
+              Inspect or edit $TOKENMAXXING_HOME/relay.json
+
+  Permission modes (Claude worker): default|acceptEdits|plan|auto|dontAsk|bypassPermissions
+  Alias: manual → default. Default in relay.json: auto.
+  Codex maps those names onto --sandbox / --ask-for-approval.`);
+}
+
+type FlagMap = {
+  worker?: "claude" | "codex";
+  session?: string;
+  cwd?: string;
+  permissionMode?: string;
+  request?: string;
+  approve?: boolean;
+  deny?: boolean;
+  noWait?: boolean;
+  target?: string;
+  positionals: string[];
+};
+
+function parseFlags(args: string[]): FlagMap {
+  const out: FlagMap = { positionals: [] };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!;
+    if (a === "--worker") {
+      const v = z.enum(["claude", "codex"]).parse(args[++i]);
+      out.worker = v;
+    } else if (a.startsWith("--worker=")) {
+      out.worker = z.enum(["claude", "codex"]).parse(a.slice("--worker=".length));
+    } else if (a === "--session") {
+      out.session = z.string().min(1).parse(args[++i]);
+    } else if (a.startsWith("--session=")) {
+      out.session = a.slice("--session=".length);
+    } else if (a === "--cwd") {
+      out.cwd = z.string().min(1).parse(args[++i]);
+    } else if (a.startsWith("--cwd=")) {
+      out.cwd = a.slice("--cwd=".length);
+    } else if (a === "--permission-mode") {
+      out.permissionMode = z.string().min(1).parse(args[++i]);
+    } else if (a.startsWith("--permission-mode=")) {
+      out.permissionMode = a.slice("--permission-mode=".length);
+    } else if (a === "--request") {
+      out.request = z.string().min(1).parse(args[++i]);
+    } else if (a.startsWith("--request=")) {
+      out.request = a.slice("--request=".length);
+    } else if (a === "--approve") {
+      out.approve = true;
+    } else if (a === "--deny") {
+      out.deny = true;
+    } else if (a === "--no-wait") {
+      out.noWait = true;
+    } else if (a === "--target") {
+      out.target = z.string().min(1).parse(args[++i]);
+    } else if (a.startsWith("--target=")) {
+      out.target = a.slice("--target=".length);
+    } else if (a === "--help" || a === "-h") {
+      out.positionals.push(a);
+    } else if (a.startsWith("-")) {
+      throw new Error(`unknown flag: ${a}`);
+    } else {
+      out.positionals.push(a);
+    }
+  }
+  return out;
+}
+
+async function readPrompt(flags: FlagMap): Promise<string> {
+  if (flags.positionals.length > 0) return flags.positionals.join(" ");
+  if (process.stdin.isTTY) return "";
+  const chunks: Uint8Array[] = [];
+  for await (const chunk of Bun.stdin.stream()) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+async function cmdTurn(args: string[]): Promise<number> {
+  const flags = parseFlags(args);
+  if (flags.positionals.includes("--help") || flags.positionals.includes("-h")) {
+    printHelp();
+    return 0;
+  }
+  const mode = flags.permissionMode != null
+    ? parsePermissionMode({ raw: flags.permissionMode })
+    : undefined;
+  const prompt = await readPrompt(flags);
+  const result = await runTurn({
+    sessionId: flags.session,
+    worker: flags.worker,
+    permissionMode: mode,
+    cwd: flags.cwd ?? cwd(),
+    prompt,
+  });
+  process.stdout.write(result.stdout);
+  return result.exitCode;
+}
+
+async function cmdDecide(args: string[]): Promise<number> {
+  const flags = parseFlags(args);
+  if (flags.session == null) {
+    console.error(c.red("relay decide requires --session <uuid>"));
+    return 1;
+  }
+  if (flags.approve === true && flags.deny === true) {
+    console.error(c.red("pass only one of --approve or --deny"));
+    return 1;
+  }
+  if (flags.approve !== true && flags.deny !== true) {
+    console.error(c.red("relay decide requires --approve or --deny"));
+    return 1;
+  }
+  const result = await runDecide({
+    sessionId: flags.session,
+    requestId: flags.request,
+    approve: flags.approve === true,
+    wait: flags.noWait !== true,
+    cwd: flags.cwd ?? cwd(),
+  });
+  if (result.turn != null) {
+    process.stdout.write(result.turn.stdout);
+    return result.turn.exitCode;
+  }
+  console.log(`decision written: ${result.requestId} (${flags.approve ? "approve" : "deny"})`);
+  return 0;
+}
+
+async function cmdSetPermissionMode(args: string[]): Promise<number> {
+  const flags = parseFlags(args);
+  if (flags.session == null || flags.permissionMode == null) {
+    console.error(c.red("relay set-permission-mode requires --session and --permission-mode"));
+    return 1;
+  }
+  const mode = parsePermissionMode({ raw: flags.permissionMode });
+  const entry = await setLivePermissionMode({ sessionId: flags.session, permissionMode: mode });
+  console.log(`session: ${entry.sessionId}`);
+  console.log(`permission-mode: ${entry.permissionMode}`);
+  return 0;
+}
+
+function cmdStatus(args: string[]): number {
+  const flags = parseFlags(args);
+  const rows = statusRows();
+  const filtered = flags.session != null
+    ? rows.filter((r) => r.sessionId === flags.session)
+    : rows;
+  if (filtered.length === 0) {
+    console.log(c.dim("(no relay sessions)"));
+    return 0;
+  }
+  for (const row of filtered) {
+    const alive = row.tmuxAlive ? c.green("up") : c.red("down");
+    console.log(
+      `${row.sessionId}  ${row.worker}  ${row.permissionMode}  ${row.state}  tmux=${alive}  ${row.tmuxName}`,
+    );
+  }
+  return 0;
+}
+
+async function cmdDestroy(args: string[]): Promise<number> {
+  const flags = parseFlags(args);
+  if (flags.session == null) {
+    console.error(c.red("relay destroy requires --session <uuid>"));
+    return 1;
+  }
+  const ok = await destroySession({ sessionId: flags.session });
+  if (!ok) {
+    console.error(c.red(`relay session not found: ${flags.session}`));
+    return 1;
+  }
+  console.log(`destroyed ${flags.session}`);
+  return 0;
+}
+
+async function cmdGc(): Promise<number> {
+  const result = await gcSessions();
+  console.log(`reaped ${result.reaped.length}; kept ${result.kept.length}`);
+  for (const id of result.reaped) console.log(`  reaped ${id}`);
+  return 0;
+}
+
+function cmdInstall(args: string[]): number {
+  const flags = parseFlags(args);
+  const target = z.enum(["cursor", "claude", "all"]).catch("all").parse(flags.target ?? "all") as InstallTarget;
+  const result = installRelayHosts({ target });
+  console.log(`agents: ${result.agentsWritten.length}`);
+  for (const p of result.agentsWritten) console.log(`  ${p}`);
+  console.log(`skill: ${result.skillWritten ? "written" : "skipped"}`);
+  console.log(`hooks: ${result.hooksMerged.length}`);
+  for (const p of result.hooksMerged) console.log(`  ${p}`);
+  return 0;
+}
+
+function cmdConfig(args: string[]): number {
+  const sub = args[0] ?? "show";
+  if (sub === "show" || sub === "get" && args[1] == null) {
+    const cfg = loadRelayConfig();
+    console.log(c.dim(`relay.json: ${paths.relayJson}`));
+    console.log(JSON.stringify(cfg, null, 2));
+    return 0;
+  }
+  if (sub === "get") {
+    const key = args[1];
+    if (key == null) {
+      console.error(c.red("relay config get <key>"));
+      return 1;
+    }
+    const cfg = loadRelayConfig() as Record<string, unknown>;
+    if (!(key in cfg)) {
+      console.error(c.red(`unknown key: ${key}`));
+      return 1;
+    }
+    console.log(JSON.stringify(cfg[key]));
+    return 0;
+  }
+  if (sub === "set") {
+    const key = args[1];
+    const valueText = args[2];
+    if (key == null || valueText == null) {
+      console.error(c.red("relay config set <key> <value>"));
+      return 1;
+    }
+    let value: unknown;
+    try {
+      value = JSON.parse(valueText);
+    } catch {
+      value = valueText;
+    }
+    if (key === "defaultPermissionMode") {
+      const mode = tryParsePermissionMode({ raw: String(value) });
+      if (mode == null) {
+        console.error(c.red(`invalid permission mode: ${value}`));
+        return 1;
+      }
+      value = mode;
+    }
+    const patch = { [key]: value } as RelayConfigFile;
+    const next = mergeRelayConfigFile({ patch });
+    console.log(`${key}: ${JSON.stringify((next as Record<string, unknown>)[key])}`);
+    return 0;
+  }
+  if (sub === "init") {
+    if (!existsSync(paths.relayJson)) {
+      writeRelayConfig({ file: {} });
+      console.log(`wrote defaults-capable ${paths.relayJson}`);
+    } else {
+      console.log(`already exists: ${paths.relayJson}`);
+      console.log(readFileSync(paths.relayJson, "utf8"));
+    }
+    console.log(c.dim(`effective defaultPermissionMode=${DEFAULT_RELAY_CONFIG.defaultPermissionMode}`));
+    return 0;
+  }
+  console.error(c.red(`unknown relay config subcommand: ${sub}`));
+  return 1;
+}
+
+export async function cmdRelay(args: string[]): Promise<number> {
+  const sub = args[0];
+  if (sub == null || sub === "--help" || sub === "-h" || sub === "help") {
+    printHelp();
+    return 0;
+  }
+  const rest = args.slice(1);
+  switch (sub) {
+    case "turn":
+      return cmdTurn(rest);
+    case "decide":
+      return cmdDecide(rest);
+    case "set-permission-mode":
+      return cmdSetPermissionMode(rest);
+    case "status":
+      return cmdStatus(rest);
+    case "destroy":
+      return cmdDestroy(rest);
+    case "gc":
+      return cmdGc();
+    case "install":
+      return cmdInstall(rest);
+    case "config":
+      return cmdConfig(rest);
+    default:
+      console.error(c.red(`unknown relay command: ${sub}`));
+      printHelp();
+      return 2;
+  }
+}