@openparachute/agent 0.1.2 → 0.2.0

package/scripts/spawn-agent.ts

@@ -0,0 +1,371 @@
+#!/usr/bin/env bun
+/**
+ * `spawn-agent` — the operator CLI for launching a sandboxed Claude Code agent
+ * session, wired to one or more channels (and optionally a vault). This is the
+ * "graduate `scripts/launch-session.sh` into a real command" step (design §4,
+ * PLAN.md "Session lifecycle/supervision"): launch-session.sh hand-rolled the
+ * token mint + .mcp.json + tmux launch in bash with NO sandbox; this thin CLI
+ * parses args into an {@link AgentSpec} and calls {@link spawnAgent} with the
+ * REAL deps — the real hub mint client, the real sandbox engine, the real tmux
+ * launcher, and the real per-channel Claude-credential resolver.
+ *
+ * It does NOT re-implement scoping or sandboxing — every least-privilege decision
+ * lives in `spawnAgent`/`sandbox/*`. The CLI's only jobs are: parse flags → build
+ * the spec → resolve the real deps → call `spawnAgent` → print the result (or a
+ * clean, actionable error).
+ *
+ * Usage:
+ *   bun scripts/spawn-agent.ts <name> [flags]
+ *
+ * Flags (mirroring launch-session.sh's ergonomics, generalized to the spec):
+ *   --channel <name>[:read|write]   repeatable; default write. First = wake channel.
+ *   --vault <name>:<read|write>[:tag1,tag2]   optional vault MCP scope (+ tag-scope).
+ *   --egress <host,host,...>        optional additive egress allowlist.
+ *   --mount <hostPath:mountPath:ro|rw[:sharedName]>   repeatable; optional.
+ *   --help                          usage.
+ *
+ * Environment:
+ *   PARACHUTE_HOME              base for operator.token (default ~/.parachute).
+ *   PARACHUTE_HUB_ORIGIN       hub public origin (else expose-state self-heal → loopback).
+ *   PARACHUTE_AGENT_URL      daemon base URL (default http://127.0.0.1:<port>).
+ *   PARACHUTE_AGENT_PORT     daemon port for the default channel URL (default 1941).
+ *   PARACHUTE_AGENT_STATE_DIR  state dir (sessions, credentials.json) — default ~/.parachute/agent.
+ *   PARACHUTE_VAULT_URL        vault base URL when a --vault is bound (default http://127.0.0.1:1940).
+ *   CLAUDE_CONFIG_DIR          claude config dir bound read-only into the sandbox (default ~/.claude).
+ */
+
+// PARKED: the interactive (tmux) backend was retired 2026-06-19 (design
+// 2026-06-19-retire-interactive-backend.md). This CLI launches a tmux session and is
+// therefore part of the parked interactive spawner — it imports the spawner from
+// `src/_parked/interactive-spawn.ts`, not the live tree. Kept buildable for the
+// future terminal/process-mgmt revival, but not a live agent-launch path.
+import {
+  spawnAgent,
+  realTmuxLauncher,
+  type SpawnAgentDeps,
+} from "../src/_parked/interactive-spawn.ts";
+import { CredentialNotConfiguredError } from "../src/credentials.ts";
+import { resolveSpawnDeps } from "../src/spawn-deps.ts";
+import { channelEntryKey, vaultEntryKey } from "../src/agent-mcp-config.ts";
+import { MintError } from "../src/mint-token.ts";
+import type {
+  AgentSpec,
+  AgentChannelSpec,
+  AgentVaultSpec,
+  AgentMount,
+} from "../src/sandbox/types.ts";
+
+const USAGE = `spawn-agent — launch a sandboxed Claude Code agent session
+
+Usage:
+  bun scripts/spawn-agent.ts <name> [flags]
+
+Arguments:
+  <name>                          agent/session slug (alphanumeric, dash, underscore).
+
+Flags:
+  --channel <name>[:read|write]   channel to scope to (repeatable; default write).
+                                  The FIRST channel is the wake channel.
+  --vault <name>:<read|write>[:tag1,tag2]
+                                  optional vault MCP scope (+ optional tag-scope).
+  --full-read                     give the agent FULL read access to your disk.
+                                  Default: reads are sandboxed to the workspace
+                                  (your home tree, incl. operator.token, is unreadable).
+  --restricted                    restrict network egress to the base + --egress hosts
+                                  (for UNTRUSTED input). Default: open (full internet).
+  --egress <host,host,...>        additive egress allowlist (only used with --restricted).
+  --mount <hostPath:mountPath:ro|rw[:shared]>
+                                  filesystem mount (repeatable; optional).
+  --help                          show this help.
+
+Example:
+  bun scripts/spawn-agent.ts aaron --channel aaron --vault default:read:#agent-message
+`;
+
+/** Parsed CLI request: the spec plus the `--help` short-circuit flag. */
+export interface ParsedArgs {
+  /** True when --help/-h was passed — print usage and exit 0, build no spec. */
+  help: boolean;
+  /** The agent spec assembled from the flags (undefined when help). */
+  spec?: AgentSpec;
+}
+
+/** A user-facing argument error — the CLI prints `.message` and exits non-zero. */
+export class ArgError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ArgError";
+  }
+}
+
+/**
+ * Parse one channel token `name[:read|write]` into an {@link AgentChannelSpec}.
+ * A bare name defaults to `write` (mirrors the spec's back-compat: a resident
+ * session reads + replies). `:read` scopes a watcher channel read-only.
+ */
+function parseChannel(value: string): AgentChannelSpec {
+  const [name, access, extra] = value.split(":");
+  if (!name) throw new ArgError(`--channel: empty channel name in "${value}"`);
+  if (extra !== undefined) {
+    throw new ArgError(`--channel "${value}": expected <name>[:read|write], got extra ":"`);
+  }
+  if (access !== undefined && access !== "read" && access !== "write") {
+    throw new ArgError(`--channel "${value}": access must be "read" or "write", got "${access}"`);
+  }
+  return access === undefined ? { name } : { name, access };
+}
+
+/**
+ * Parse `--vault <name>:<read|write>[:tag1,tag2]` into an {@link AgentVaultSpec}.
+ * (The spec also supports `admin`, but the CLI surface mirrors launch's
+ * read/write ergonomics; admin is an explicit, rare grant left to the API path.)
+ */
+function parseVault(value: string): AgentVaultSpec {
+  const parts = value.split(":");
+  const name = parts[0];
+  const access = parts[1];
+  const tagPart = parts[2];
+  if (parts.length < 2 || parts.length > 3) {
+    throw new ArgError(`--vault "${value}": expected <name>:<read|write>[:tag1,tag2]`);
+  }
+  if (!name) throw new ArgError(`--vault "${value}": empty vault name`);
+  if (access !== "read" && access !== "write") {
+    throw new ArgError(`--vault "${value}": access must be "read" or "write", got "${access}"`);
+  }
+  const spec: AgentVaultSpec = { name, access };
+  if (tagPart !== undefined) {
+    const tags = tagPart.split(",").map((t) => t.trim()).filter((t) => t.length > 0);
+    if (tags.length === 0) {
+      throw new ArgError(`--vault "${value}": tag list after the access is empty`);
+    }
+    spec.tags = tags;
+  }
+  return spec;
+}
+
+/**
+ * Parse `--mount <hostPath:mountPath:ro|rw[:shared]>` into an {@link AgentMount}.
+ * hostPath/mountPath are absolute paths; the mode is `ro`|`rw`; an optional 4th
+ * segment names a cross-session share.
+ */
+function parseMount(value: string): AgentMount {
+  const parts = value.split(":");
+  if (parts.length < 3 || parts.length > 4) {
+    throw new ArgError(`--mount "${value}": expected <hostPath:mountPath:ro|rw[:shared]>`);
+  }
+  const [hostPath, mountPath, mode, shared] = parts;
+  if (!hostPath || !mountPath) {
+    throw new ArgError(`--mount "${value}": hostPath and mountPath are required`);
+  }
+  if (mode !== "ro" && mode !== "rw") {
+    throw new ArgError(`--mount "${value}": mode must be "ro" or "rw", got "${mode}"`);
+  }
+  const mount: AgentMount = { hostPath, mountPath, mode };
+  if (shared !== undefined) {
+    if (shared.length === 0) throw new ArgError(`--mount "${value}": empty shared name`);
+    mount.shared = shared;
+  }
+  return mount;
+}
+
+/** Read the value that must follow a flag, or throw a clean ArgError. */
+function takeValue(argv: string[], i: number, flag: string): string {
+  const v = argv[i + 1];
+  if (v === undefined || v.startsWith("--")) {
+    throw new ArgError(`${flag}: expected a value`);
+  }
+  return v;
+}
+
+/**
+ * Parse argv (everything AFTER `bun scripts/spawn-agent.ts`) into a spec. Pure +
+ * exported so the unit test exercises it without any fs/tmux/mint side effect.
+ * Throws {@link ArgError} on any malformed input.
+ */
+export function parseArgs(argv: string[]): ParsedArgs {
+  let name: string | undefined;
+  const channels: AgentChannelSpec[] = [];
+  let vault: AgentVaultSpec | undefined;
+  const egress: string[] = [];
+  let fullRead = false;
+  let restricted = false;
+  const mounts: AgentMount[] = [];
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]!;
+    switch (arg) {
+      case "--help":
+      case "-h":
+        return { help: true };
+      case "--channel": {
+        channels.push(parseChannel(takeValue(argv, i, "--channel")));
+        i++;
+        break;
+      }
+      case "--vault": {
+        if (vault) throw new ArgError("--vault may only be given once");
+        vault = parseVault(takeValue(argv, i, "--vault"));
+        i++;
+        break;
+      }
+      case "--egress": {
+        const raw = takeValue(argv, i, "--egress");
+        for (const h of raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0)) {
+          egress.push(h);
+        }
+        i++;
+        break;
+      }
+      case "--full-read": {
+        fullRead = true;
+        break;
+      }
+      case "--restricted": {
+        restricted = true;
+        break;
+      }
+      case "--mount": {
+        mounts.push(parseMount(takeValue(argv, i, "--mount")));
+        i++;
+        break;
+      }
+      default: {
+        if (arg.startsWith("-")) throw new ArgError(`unknown flag "${arg}" (try --help)`);
+        if (name !== undefined) {
+          throw new ArgError(`unexpected positional "${arg}" — only one <name> is accepted`);
+        }
+        name = arg;
+      }
+    }
+  }
+
+  if (name === undefined) throw new ArgError("missing required <name> (try --help)");
+  if (channels.length === 0) {
+    throw new ArgError("at least one --channel is required (the first is the wake channel)");
+  }
+
+  const spec: AgentSpec = { name, channels };
+  if (vault) spec.vault = vault;
+  if (fullRead) spec.filesystem = "full";
+  if (restricted) spec.network = "restricted";
+  if (egress.length > 0) spec.egress = egress;
+  if (mounts.length > 0) spec.mounts = mounts;
+  return { help: false, spec };
+}
+
+// ---------------------------------------------------------------------------
+// Run-time helpers (only reached on the actual run, not in unit tests).
+// ---------------------------------------------------------------------------
+
+/** Format a per-aud scope summary line for each minted token. */
+function scopeLines(result: Awaited<ReturnType<typeof spawnAgent>>): string[] {
+  const lines: string[] = [];
+  for (const [resource, minted] of Object.entries(result.tokens)) {
+    lines.push(`    ${resource.padEnd(20)} ${minted.scope}`);
+  }
+  return lines;
+}
+
+async function main(): Promise<number> {
+  let parsed: ParsedArgs;
+  try {
+    parsed = parseArgs(process.argv.slice(2));
+  } catch (err) {
+    if (err instanceof ArgError) {
+      process.stderr.write(`error: ${err.message}\n\n${USAGE}`);
+      return 2;
+    }
+    throw err;
+  }
+
+  if (parsed.help || !parsed.spec) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  const spec = parsed.spec;
+
+  let deps: SpawnAgentDeps;
+  try {
+    // The shared base deps + the (parked) real tmux launcher — the live
+    // `resolveSpawnDeps` no longer carries a tmux launcher (interactive retired).
+    deps = { ...resolveSpawnDeps(), tmux: realTmuxLauncher() };
+  } catch (err) {
+    process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}\n`);
+    return 1;
+  }
+
+  const wakeChannel =
+    typeof spec.channels[0] === "string" ? spec.channels[0] : spec.channels[0]!.name;
+
+  let result: Awaited<ReturnType<typeof spawnAgent>>;
+  try {
+    result = await spawnAgent(spec, deps);
+  } catch (err) {
+    // A missing Claude credential is the most common operator error — surface the
+    // exact creds-API curl to set it, and exit non-zero (no session launched).
+    if (err instanceof CredentialNotConfiguredError) {
+      process.stderr.write(
+        `error: ${err.message}\n\n` +
+          `Set the operator Claude credential (get a token with \`claude setup-token\`), then re-run:\n` +
+          `  curl -X POST ${deps.channelUrl}/api/credentials/claude \\\n` +
+          `    -H 'authorization: Bearer <agent:admin JWT>' \\\n` +
+          `    -H 'content-type: application/json' \\\n` +
+          `    -d '{"token":"<oat_… from claude setup-token>"}'\n\n` +
+          `Or scope it to just the wake channel "${wakeChannel}":\n` +
+          `  curl -X POST ${deps.channelUrl}/api/credentials/claude/${encodeURIComponent(wakeChannel)} \\\n` +
+          `    -H 'authorization: Bearer <agent:admin JWT>' \\\n` +
+          `    -H 'content-type: application/json' \\\n` +
+          `    -d '{"token":"<oat_…>"}'\n`,
+      );
+      return 1;
+    }
+    // A bad slug name (spawnAgent's guard) or a refused/over-broad mint — surface
+    // the message cleanly; no session was created in either case.
+    if (err instanceof MintError) {
+      process.stderr.write(`error: token mint failed — ${err.message}\n`);
+      return 1;
+    }
+    process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}\n`);
+    return 1;
+  }
+
+  if (result.alreadyRunning) {
+    process.stdout.write(
+      `session "${result.session}" is already running (no-op).\n` +
+        `  attach:   tmux attach -t ${result.session}\n` +
+        `  terminal: ${deps.channelUrl.replace(/\/$/, "")}/terminal?session=${encodeURIComponent(result.session)}\n`,
+    );
+    return 0;
+  }
+
+  // Success — print the session, the resolved scopes (per aud), and how to watch it.
+  const out: string[] = [];
+  out.push(`launched session "${result.session}" on channel "${wakeChannel}".`);
+  out.push(`  workspace: ${result.workspace}`);
+  out.push(`  scopes (one token per aud):`);
+  out.push(...scopeLines(result));
+  out.push(`  MCP servers: ${Object.keys(JSON.parse(result.mcpConfigJson).mcpServers).join(", ")}`);
+  out.push("");
+  out.push(`  watch (tmux):   tmux attach -t ${result.session}   (detach: Ctrl-b then d)`);
+  out.push(
+    `  watch (web):    ${deps.channelUrl.replace(/\/$/, "")}/terminal?session=${encodeURIComponent(result.session)}`,
+  );
+  out.push(`  chat:           open the channel UI and pick channel "${wakeChannel}"`);
+  // Note the entry keys so the operator can map scopes → MCP entries at a glance.
+  const entryHints = [
+    ...spec.channels.map((c) => channelEntryKey(typeof c === "string" ? c : c.name)),
+    ...(spec.vault ? [vaultEntryKey(spec.vault.name)] : []),
+  ];
+  out.push(`  mcp entries:    ${entryHints.join(", ")}`);
+  process.stdout.write(out.join("\n") + "\n");
+  return 0;
+}
+
+if (import.meta.main) {
+  main()
+    .then((code) => process.exit(code))
+    .catch((err) => {
+      process.stderr.write(`error: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+      process.exit(1);
+    });
+}

package/src/_parked/interactive-spawn.test.ts

@@ -0,0 +1,324 @@
+/**
+ * PARKED unit tests for the interactive (tmux) spawner + session admin
+ * (`src/_parked/interactive-spawn.ts`). The interactive backend retired 2026-06-19
+ * (design 2026-06-19-retire-interactive-backend.md); these tests keep the parked
+ * code provably buildable for the future terminal/process-mgmt revival. They are
+ * pure over their inputs (an injected `TmuxAdmin` / `TmuxLauncher` recorder) — no
+ * hub, no sandbox, no real tmux server.
+ *
+ * Spawner-internals coverage (buildAgentClaudeArgs, buildLaunchScript,
+ * realTmuxLauncher, confirmDevChannelsPrompt, spawnAgent) lives in
+ * `src/spawn-agent.test.ts`, which imports the spawner from the parked module too.
+ */
+import { describe, test, expect } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  parseTmuxSessions,
+  agentInfoFromSessions,
+  redactSpawnResult,
+  createRealAgentOps,
+  SpawnRequestError,
+  type TmuxAdmin,
+  type TmuxLauncher,
+  type SpawnAgentDeps,
+  type SpawnAgentResult,
+} from "./interactive-spawn.ts";
+import { persistSpec, sessionWorkspace } from "../spawn-agent.ts";
+import type { SandboxEngine } from "../sandbox/index.ts";
+import type { AgentSpec } from "../sandbox/types.ts";
+
+describe("parseTmuxSessions", () => {
+  test("parses `<name> <attachedCount>` lines; attached>0 → true", () => {
+    const out = parseTmuxSessions("aaron-agent 1\nweaver-agent 0\nmisc 2\n");
+    expect(out).toEqual([
+      { name: "aaron-agent", attached: true },
+      { name: "weaver-agent", attached: false },
+      { name: "misc", attached: true },
+    ]);
+  });
+  test("empty / blank input → empty list", () => {
+    expect(parseTmuxSessions("")).toEqual([]);
+    expect(parseTmuxSessions("\n  \n")).toEqual([]);
+  });
+});
+
+describe("agentInfoFromSessions", () => {
+  test("keeps only *-agent sessions, strips the suffix, sorts by name", () => {
+    const infos = agentInfoFromSessions(
+      [
+        { name: "weaver-agent", attached: false },
+        { name: "scratch", attached: true }, // not an agent session — dropped
+        { name: "aaron-agent", attached: true },
+      ],
+      "/tmp/sessions",
+    );
+    expect(infos.map((i) => i.name)).toEqual(["aaron", "weaver"]);
+    expect(infos[0]).toMatchObject({ name: "aaron", session: "aaron-agent", attached: true });
+    expect(infos[0]!.workspace).toBe("/tmp/sessions/aaron");
+    expect(infos[0]!.hasWorkspace).toBe(false);
+  });
+  test("a bare `-agent` (empty slug) is dropped", () => {
+    expect(agentInfoFromSessions([{ name: "-agent", attached: false }], "/tmp/s")).toEqual([]);
+  });
+  test("surfaces systemPromptMode from the persisted spec when a prompt is set; absent otherwise", () => {
+    const dir = mkdtempSync(join(tmpdir(), "agent-info-sysprompt-"));
+    try {
+      persistSpec(sessionWorkspace(dir, "withprompt"), {
+        name: "withprompt",
+        channels: ["withprompt"],
+        systemPrompt: "You are a focused bot.",
+        systemPromptMode: "replace",
+      } as AgentSpec);
+      persistSpec(sessionWorkspace(dir, "noprompt"), { name: "noprompt", channels: ["noprompt"] } as AgentSpec);
+      const infos = agentInfoFromSessions(
+        [
+          { name: "withprompt-agent", attached: false },
+          { name: "noprompt-agent", attached: false },
+        ],
+        dir,
+      );
+      const byName = Object.fromEntries(infos.map((i) => [i.name, i]));
+      expect(byName.withprompt!.systemPromptMode).toBe("replace");
+      expect(byName.noprompt!.systemPromptMode).toBeUndefined();
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+  test("surfaces workingDir from the persisted spec when the workspace is set AND exists; absent otherwise", () => {
+    const dir = mkdtempSync(join(tmpdir(), "agent-info-workdir-"));
+    const workdir = mkdtempSync(join(tmpdir(), "agent-info-real-workdir-"));
+    try {
+      persistSpec(sessionWorkspace(dir, "withdir"), {
+        name: "withdir",
+        channels: ["withdir"],
+        workspace: workdir,
+      } as AgentSpec);
+      persistSpec(sessionWorkspace(dir, "nodir"), { name: "nodir", channels: ["nodir"] } as AgentSpec);
+      persistSpec(sessionWorkspace(dir, "gonedir"), {
+        name: "gonedir",
+        channels: ["gonedir"],
+        workspace: "/Users/op/Code/deleted-repo",
+      } as AgentSpec);
+      const infos = agentInfoFromSessions(
+        [
+          { name: "withdir-agent", attached: false },
+          { name: "nodir-agent", attached: false },
+          { name: "gonedir-agent", attached: false },
+        ],
+        dir,
+      );
+      const byName = Object.fromEntries(infos.map((i) => [i.name, i]));
+      expect(byName.withdir!.workingDir).toBe(workdir);
+      expect(byName.nodir!.workingDir).toBeUndefined();
+      expect(byName.gonedir!.workingDir).toBeUndefined();
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+      rmSync(workdir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("redactSpawnResult", () => {
+  const result: SpawnAgentResult = {
+    session: "aaron-agent",
+    workspace: "/s/aaron",
+    alreadyRunning: false,
+    tokens: {
+      aaron: { jti: "j1", token: "SECRET-AGENT-TOKEN", expiresAt: "2026-07-01T00:00:00Z", scope: "agent:read agent:write" },
+      "vault:default": { jti: "j2", token: "SECRET-VAULT-TOKEN", expiresAt: "2026-07-01T00:00:00Z", scope: "vault:default:read" },
+    },
+    mcpConfigJson: JSON.stringify({ mcpServers: { "agent-aaron": {}, "vault-default": {} } }),
+    wrapped: {
+      argv: ["/bin/bash", "-c", "..."],
+      env: {},
+      config: { network: { allowedDomains: ["api.anthropic.com:443"], deniedDomains: [] }, filesystem: { denyRead: ["/Users"], allowWrite: [], denyWrite: [] } },
+    },
+  };
+  test("surfaces scopes + mcp servers + posture + egress, NEVER the token values", () => {
+    const red = redactSpawnResult(result);
+    expect(red.session).toBe("aaron-agent");
+    expect(red.tokens).toEqual([
+      { resource: "aaron", scope: "agent:read agent:write", expiresAt: "2026-07-01T00:00:00Z" },
+      { resource: "vault:default", scope: "vault:default:read", expiresAt: "2026-07-01T00:00:00Z" },
+    ]);
+    expect(red.mcpServers).toEqual(["agent-aaron", "vault-default"]);
+    expect(red.egress).toEqual(["api.anthropic.com:443"]);
+    expect(red.network).toBe("restricted");
+    expect(red.filesystem).toBe("workspace");
+    const wire = JSON.stringify(red);
+    expect(wire).not.toContain("SECRET-AGENT-TOKEN");
+    expect(wire).not.toContain("SECRET-VAULT-TOKEN");
+  });
+  test("an open result (no allowedDomains, no denyRead) → network 'open' + filesystem 'full', egress []", () => {
+    const open: SpawnAgentResult = {
+      ...result,
+      wrapped: {
+        ...result.wrapped,
+        config: { network: { deniedDomains: [] }, filesystem: { denyRead: [], allowWrite: [], denyWrite: [] } } as unknown as SpawnAgentResult["wrapped"]["config"],
+      },
+    };
+    const red = redactSpawnResult(open);
+    expect(red.network).toBe("open");
+    expect(red.filesystem).toBe("full");
+    expect(red.egress).toEqual([]);
+  });
+});
+
+describe("createRealAgentOps — list + kill", () => {
+  function recorder(sessions: { name: string; attached: boolean }[]): { tmux: TmuxAdmin; killed: string[] } {
+    const killed: string[] = [];
+    const tmux: TmuxAdmin = {
+      async listSessions() {
+        return sessions;
+      },
+      async killSession(name: string) {
+        killed.push(name);
+        return sessions.some((s) => s.name === name);
+      },
+    };
+    return { tmux, killed };
+  }
+
+  test("list maps tmux sessions to agent infos under the sessions dir", async () => {
+    const { tmux } = recorder([{ name: "aaron-agent", attached: true }, { name: "other", attached: false }]);
+    const ops = createRealAgentOps({ tmux, sessionsDirPath: "/tmp/s" });
+    const list = await ops.list();
+    expect(list.map((a) => a.name)).toEqual(["aaron"]);
+  });
+
+  test("kill targets `<name>-agent` and reports whether it existed", async () => {
+    const { tmux, killed } = recorder([{ name: "aaron-agent", attached: false }]);
+    const ops = createRealAgentOps({ tmux, sessionsDirPath: "/tmp/s" });
+    expect(await ops.kill("aaron")).toEqual({ killed: true });
+    expect(killed).toEqual(["aaron-agent"]);
+    expect(await ops.kill("ghost")).toEqual({ killed: false });
+  });
+
+  test("kill rejects a non-slug name before touching tmux", async () => {
+    const { tmux, killed } = recorder([]);
+    const ops = createRealAgentOps({ tmux, sessionsDirPath: "/tmp/s" });
+    await expect(ops.kill("../escape")).rejects.toThrow(SpawnRequestError);
+    expect(killed).toEqual([]);
+  });
+});
+
+describe("createRealAgentOps — restart (param recovery via persisted spec)", () => {
+  function spawnDeps(sessionsDirPath: string): {
+    deps: SpawnAgentDeps;
+    launched: Array<{ name: string }>;
+  } {
+    const launched: Array<{ name: string }> = [];
+    const launcher: TmuxLauncher = {
+      async hasSession() {
+        return false;
+      },
+      async newSession(opts) {
+        launched.push({ name: opts.name });
+      },
+      async confirmDevChannelsPrompt() {
+        return "already-running";
+      },
+    };
+    const engine: SandboxEngine = {
+      isSupportedPlatform: () => true,
+      isSandboxingEnabled: () => true,
+      async initialize() {},
+      async wrapWithSandboxArgv(command: string) {
+        return { argv: ["/bin/bash", "-c", command], env: {} };
+      },
+      async reset() {},
+    };
+    const fetchFn = (async (_u: string | URL | Request, init?: RequestInit) => {
+      const body = JSON.parse(String(init?.body ?? "{}")) as { scope: string };
+      return new Response(
+        JSON.stringify({ jti: "j", token: "TOK", expires_at: "2026-09-01T00:00:00Z", scope: body.scope }),
+        { status: 200, headers: { "content-type": "application/json" } },
+      );
+    }) as unknown as typeof fetch;
+    const deps: SpawnAgentDeps = {
+      hubOrigin: "https://hub.example.com",
+      managerBearer: "MANAGER",
+      channelUrl: "http://127.0.0.1:1941",
+      vaultUrl: "http://127.0.0.1:1940",
+      sessionsDir: sessionsDirPath,
+      runtimeReadOnly: [],
+      resolveClaudeToken: () => "OAUTH-PLACEHOLDER",
+      resolveChannelEnv: () => ({ GH_TOKEN: "ghp_FROM-STORE" }),
+      sandboxEngine: engine,
+      tmux: launcher,
+      fetchFn,
+      parentEnv: { PATH: "/usr/bin" },
+      claudeBin: "claude",
+    };
+    return { deps, launched };
+  }
+
+  test("recovers the persisted spec, kills the old session, re-spawns it", async () => {
+    const sessionsDirPath = mkdtempSync(join(tmpdir(), "restart-ops-"));
+    try {
+      const spec: AgentSpec = { name: "aaron", channels: ["aaron"], network: "open" };
+      persistSpec(sessionWorkspace(sessionsDirPath, "aaron"), spec);
+
+      const killed: string[] = [];
+      const tmux: TmuxAdmin = {
+        async listSessions() {
+          return [{ name: "aaron-agent", attached: false }];
+        },
+        async killSession(name) {
+          killed.push(name);
+          return true;
+        },
+      };
+      const { deps, launched } = spawnDeps(sessionsDirPath);
+      const ops = createRealAgentOps({ tmux, sessionsDirPath, depsFactory: () => deps });
+
+      const result = await ops.restart("aaron");
+      expect(killed).toEqual(["aaron-agent"]);
+      expect(launched).toEqual([{ name: "aaron-agent" }]);
+      expect(result.killed).toBe(true);
+      expect(result.session).toBe("aaron-agent");
+      expect(JSON.stringify(result)).not.toContain("TOK");
+    } finally {
+      rmSync(sessionsDirPath, { recursive: true, force: true });
+    }
+  });
+
+  test("a missing persisted spec → SpawnRequestError (kill not attempted)", async () => {
+    const sessionsDirPath = mkdtempSync(join(tmpdir(), "restart-nospec-"));
+    try {
+      const killed: string[] = [];
+      const tmux: TmuxAdmin = {
+        async listSessions() {
+          return [];
+        },
+        async killSession(name) {
+          killed.push(name);
+          return true;
+        },
+      };
+      const { deps } = spawnDeps(sessionsDirPath);
+      const ops = createRealAgentOps({ tmux, sessionsDirPath, depsFactory: () => deps });
+      await expect(ops.restart("ghost")).rejects.toThrow(SpawnRequestError);
+      await expect(ops.restart("ghost")).rejects.toThrow(/no persisted spec/);
+      expect(killed).toEqual([]);
+    } finally {
+      rmSync(sessionsDirPath, { recursive: true, force: true });
+    }
+  });
+
+  test("restart rejects a non-slug name before touching anything", async () => {
+    const tmux: TmuxAdmin = {
+      async listSessions() {
+        return [];
+      },
+      async killSession() {
+        return false;
+      },
+    };
+    const { deps } = spawnDeps("/tmp/s");
+    const ops = createRealAgentOps({ tmux, sessionsDirPath: "/tmp/s", depsFactory: () => deps });
+    await expect(ops.restart("../escape")).rejects.toThrow(SpawnRequestError);
+  });
+});