@openparachute/agent 0.1.2 → 0.2.2

package/src/_parked/interactive-spawn.ts

@@ -0,0 +1,701 @@
+/**
+ * PARKED — the interactive (tmux) agent SPAWNER + tmux session admin.
+ *
+ * This is NOT a live agent backend. The `interactive` backend was retired
+ * 2026-06-19 (design `design/2026-06-19-retire-interactive-backend.md`): the
+ * `channel` backend supersedes the human-driven-Claude-Code need it hedged,
+ * without the tmux/send-keys/idle-wake fragility. The daemon no longer imports
+ * or routes to any of this code.
+ *
+ * Per Aaron's note in the channel-backend design ("Retiring interactive"), the
+ * PTY/terminal-spawning machinery is PARKED, not deleted: it gets repurposed
+ * later (lower priority) into proper TERMINAL / PROCESS MANAGEMENT in the
+ * Parachute interface — a general capability (spin up a Claude Code session, or
+ * anything), decoupled from the agent backend.
+ *
+ * What's here:
+ *   - the tmux SPAWNER: `spawnAgent` + its argv/launch-script/dev-channels-prompt
+ *     helpers + the `TmuxLauncher`/`realTmuxLauncher` seam + the deps/result types;
+ *   - the tmux SESSION ADMIN: `AgentOps`/`TmuxAdmin`/`createRealAgentOps` +
+ *     `parseTmuxSessions`/`agentInfoFromSessions`/`realTmuxAdmin` + `AgentInfo`.
+ *
+ * What it still SHARES from the live tree (imported, not copied) — the sandbox/
+ * filesystem/env helpers that the PROGRAMMATIC backend also uses, which stayed in
+ * `src/spawn-agent.ts`: `wrapArgvInSandbox`, `seedAgentHome`, `buildAgentChildEnv`,
+ * `resolveAgentCwd`, `sessionWorkspace`, `persistSpec`, `readPersistedSpec`,
+ * `shellJoin`. Parking the spawner did NOT fork those.
+ *
+ * If/when this is revived as terminal-mgmt, it should be lifted out of the agent
+ * module entirely (a `process`/`terminal` capability), not re-wired as a backend.
+ */
+
+import { existsSync, statSync, writeFileSync, chmodSync } from "node:fs";
+import { join } from "node:path";
+import type {
+  AgentSpec,
+  AgentChannel,
+  AgentVaultSpec,
+  AgentMount,
+} from "../sandbox/types.ts";
+import { normalizeChannel } from "../sandbox/types.ts";
+import type { SandboxEngine, WrappedCommand } from "../sandbox/index.ts";
+import {
+  buildAgentChildEnv,
+  mergeSandboxLaunchEnv,
+  resolveAgentCwd,
+  seedAgentHome,
+  sessionWorkspace,
+  persistSpec,
+  readPersistedSpec,
+  shellJoin,
+  wrapArgvInSandbox,
+  type SpawnAgentBaseDeps,
+} from "../spawn-agent.ts";
+import {
+  buildAgentMcpConfigJson,
+  channelEntryKey,
+  type ChannelMcpEntry,
+  type VaultMcpEntry,
+  type OtherMcpEntry,
+} from "../agent-mcp-config.ts";
+import {
+  mintScopedToken,
+  agentScope,
+  vaultScope,
+  type MintTokenDeps,
+  type MintResult,
+} from "../mint-token.ts";
+import {
+  resolveClaudeCredential,
+  resolveChannelEnv,
+} from "../credentials.ts";
+
+/** Same slug shape spawnAgent enforces. */
+const AGENT_NAME_SLUG = /^[a-z0-9_-]+$/i;
+
+/** The `-agent` suffix tmux sessions launched by `spawnAgent` carry. */
+const AGENT_SESSION_SUFFIX = "-agent";
+
+/** A malformed spawn request body — the caller maps `.message` to a 400. */
+export class SpawnRequestError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "SpawnRequestError";
+  }
+}
+
+// ===========================================================================
+// The tmux SPAWNER (was spawn-agent.ts).
+// ===========================================================================
+
+/** A tmux launcher seam — real impl spawns tmux; tests inject a recorder. */
+export interface TmuxLauncher {
+  newSession(opts: {
+    name: string;
+    argv: string[];
+    env: Record<string, string | undefined>;
+    cwd: string;
+    scriptDir?: string;
+  }): Promise<void>;
+  hasSession(name: string): Promise<boolean>;
+  confirmDevChannelsPrompt(session: string): Promise<"confirmed" | "already-running" | "timeout">;
+}
+
+/** Deps for the interactive {@link spawnAgent} — the shared base + the tmux launcher. */
+export interface SpawnAgentDeps extends SpawnAgentBaseDeps {
+  /** tmux launcher (tests inject a recorder). */
+  tmux: TmuxLauncher;
+}
+
+export interface SpawnAgentResult {
+  session: string;
+  workspace: string;
+  tokens: Record<string, MintResult>;
+  mcpConfigJson: string;
+  wrapped: WrappedCommand;
+  alreadyRunning: boolean;
+  devChannelsPrompt?: "confirmed" | "already-running" | "timeout";
+}
+
+/** tmux session name for a spec — matches launch-session.sh's `<name>-agent`. */
+export function sessionName(specName: string): string {
+  return `${specName}-agent`;
+}
+
+/**
+ * Build the `claude` invocation argv (pre-sandbox-wrap). Interactive `claude`
+ * (NOT `claude -p`) with the strict, multi-entry MCP config + the dev-channels
+ * flag for the first channel. `--strict-mcp-config` closes the MCP surface.
+ */
+export function buildAgentClaudeArgs(opts: {
+  mcpConfigPath: string;
+  firstChannelEntryKey: string;
+  claudeBin?: string;
+  systemPromptFile?: string;
+  systemPromptMode?: "append" | "replace";
+}): string[] {
+  const bin = opts.claudeBin ?? "claude";
+  const argv = [
+    bin,
+    "--dangerously-skip-permissions",
+    "--strict-mcp-config",
+    "--mcp-config",
+    opts.mcpConfigPath,
+    `--dangerously-load-development-channels=server:${opts.firstChannelEntryKey}`,
+  ];
+  if (opts.systemPromptFile) {
+    const flag = opts.systemPromptMode === "replace" ? "--system-prompt-file" : "--append-system-prompt-file";
+    argv.push(flag, opts.systemPromptFile);
+  }
+  return argv;
+}
+
+/**
+ * Spawn a sandboxed interactive agent session from a spec. Idempotent: an
+ * existing tmux session is a no-op (returns `alreadyRunning: true`).
+ */
+export async function spawnAgent(
+  spec: AgentSpec,
+  deps: SpawnAgentDeps,
+): Promise<SpawnAgentResult> {
+  if (!AGENT_NAME_SLUG.test(spec.name)) {
+    throw new Error(
+      `spawnAgent: spec name "${spec.name}" must be a slug (alphanumeric, dash, underscore only)`,
+    );
+  }
+
+  const session = sessionName(spec.name);
+  const workspace = sessionWorkspace(deps.sessionsDir, spec.name);
+
+  if (await deps.tmux.hasSession(session)) {
+    return {
+      session,
+      workspace,
+      tokens: {},
+      mcpConfigJson: "",
+      wrapped: { argv: [], env: {}, config: { network: { allowedDomains: [], deniedDomains: [] }, filesystem: { denyRead: [], allowWrite: [], denyWrite: [] } } },
+      alreadyRunning: true,
+    };
+  }
+
+  if (spec.channels.length === 0) {
+    throw new Error(`spawnAgent: spec "${spec.name}" declares no channels`);
+  }
+
+  const wakeChannel = normalizeChannel(spec.channels[0]!).name;
+  const resolveToken = deps.resolveClaudeToken ?? ((ch: string) => resolveClaudeCredential(ch));
+  const claudeOauthToken = resolveToken(wakeChannel);
+
+  const resolveEnv = deps.resolveChannelEnv ?? ((ch: string) => resolveChannelEnv(ch));
+  const channelEnv = resolveEnv(wakeChannel);
+
+  const mintDeps: MintTokenDeps = {
+    hubOrigin: deps.hubOrigin,
+    managerBearer: deps.managerBearer,
+    ...(deps.fetchFn ? { fetchFn: deps.fetchFn } : {}),
+  };
+
+  const tokens: Record<string, MintResult> = {};
+  const channelEntries: ChannelMcpEntry[] = [];
+  for (const rawChannel of spec.channels) {
+    const { name: channel, access } = normalizeChannel(rawChannel);
+    const minted = await mintScopedToken(
+      { scope: agentScope({ write: access === "write" }), audience: "agent" },
+      mintDeps,
+    );
+    tokens[channel] = minted;
+    channelEntries.push({ channel, token: minted.token });
+  }
+
+  let vaultArg: { url: string; entry: VaultMcpEntry } | undefined;
+  if (spec.vault) {
+    const v = spec.vault;
+    const minted = await mintScopedToken(
+      {
+        scope: vaultScope(v.name, v.access),
+        audience: `vault.${v.name}`,
+        ...(v.tags && v.tags.length > 0 ? { permissions: { scoped_tags: v.tags } } : {}),
+      },
+      mintDeps,
+    );
+    tokens[`vault:${v.name}`] = minted;
+    vaultArg = {
+      url: deps.vaultUrl ?? deps.hubOrigin,
+      entry: { name: v.name, token: minted.token },
+    };
+  }
+
+  const otherEntries: OtherMcpEntry[] = [];
+  for (const o of spec.otherMcps ?? []) {
+    let token: string | undefined;
+    if (o.scope) {
+      const minted = await mintScopedToken(
+        { scope: o.scope, ...(o.audience ? { audience: o.audience } : {}) },
+        mintDeps,
+      );
+      tokens[o.name] = minted;
+      token = minted.token;
+    }
+    otherEntries.push({ name: o.name, url: o.url, ...(token ? { token } : {}) });
+  }
+
+  const mcpConfigJson = buildAgentMcpConfigJson({
+    channelUrl: deps.channelUrl,
+    channels: channelEntries,
+    ...(vaultArg ? { vault: vaultArg } : {}),
+    ...(otherEntries.length > 0 ? { otherMcps: otherEntries } : {}),
+  });
+  persistSpec(workspace, spec);
+  const mcpConfigPath = join(workspace, ".mcp.json");
+  writeFileSync(mcpConfigPath, mcpConfigJson, { mode: 0o600 });
+
+  let systemPromptFile: string | undefined;
+  if (typeof spec.systemPrompt === "string" && spec.systemPrompt.length > 0) {
+    systemPromptFile = join(workspace, "system-prompt.txt");
+    writeFileSync(systemPromptFile, spec.systemPrompt, { mode: 0o600 });
+  }
+
+  const claudeArgs = buildAgentClaudeArgs({
+    mcpConfigPath,
+    firstChannelEntryKey: channelEntryKey(wakeChannel),
+    ...(deps.claudeBin ? { claudeBin: deps.claudeBin } : {}),
+    ...(systemPromptFile
+      ? { systemPromptFile, systemPromptMode: spec.systemPromptMode ?? "append" }
+      : {}),
+  });
+
+  const wrapped = await wrapArgvInSandbox({
+    spec,
+    workspace,
+    runtimeReadOnly: deps.runtimeReadOnly,
+    hubOrigin: deps.hubOrigin,
+    ...(deps.vaultUrl ? { vaultUrl: deps.vaultUrl } : {}),
+    argv: claudeArgs,
+    ...(deps.sandboxEngine ? { sandboxEngine: deps.sandboxEngine } : {}),
+    ...(deps.ripgrep ? { ripgrep: deps.ripgrep } : {}),
+  });
+
+  const cwd = resolveAgentCwd(spec, workspace);
+
+  const mcpServerNames = Object.keys(
+    (JSON.parse(mcpConfigJson) as { mcpServers?: Record<string, unknown> }).mcpServers ?? {},
+  );
+  const homeEnv = seedAgentHome(workspace, { mcpServers: mcpServerNames, projectRoot: cwd });
+
+  const childEnv = buildAgentChildEnv(deps.parentEnv ?? process.env, claudeOauthToken, channelEnv);
+  // Scrub WINS: only allowlisted sandbox/proxy keys from `wrapped.env` (not the whole
+  // daemon `process.env` the engine returns) layer on top. See mergeSandboxLaunchEnv.
+  // (This file is the PARKED/retired interactive backend — kept in sync with the live
+  // programmatic backend's shared seam, not a live spawn path.)
+  const launchEnv = mergeSandboxLaunchEnv(childEnv, wrapped.env, homeEnv);
+
+  await deps.tmux.newSession({
+    name: session,
+    argv: wrapped.argv,
+    env: launchEnv,
+    cwd,
+    scriptDir: workspace,
+  });
+
+  const devChannelsPrompt = await deps.tmux.confirmDevChannelsPrompt(session);
+
+  return {
+    session,
+    workspace,
+    tokens,
+    mcpConfigJson,
+    wrapped,
+    alreadyRunning: false,
+    devChannelsPrompt,
+  };
+}
+
+/** Per-session launch-script path under the session workspace (`cwd`). */
+function launchScriptPath(cwd: string): string {
+  return join(cwd, ".launch.sh");
+}
+
+/**
+ * Build the per-session **launch script** body for an already-sandbox-wrapped argv.
+ * On macOS `wrapWithSandboxArgv` returns `["/bin/bash","-c","<~84KB profile inline>"]`
+ * — too large for a tmux argument, so we write it to a file tmux runs via a short argv.
+ */
+export function buildLaunchScript(argv: string[]): string {
+  const header = "#!/bin/bash\nset -euo pipefail\n";
+  if (argv.length === 3 && argv[0] === "/bin/bash" && argv[1] === "-c") {
+    return `${header}${argv[2]}\n`;
+  }
+  return `${header}exec ${shellJoin(argv)}\n`;
+}
+
+/** The prompt marker for the dev-channels consent gate (agent#70). */
+export const DEV_CHANNELS_PROMPT_MARKER = "I am using this for local development";
+/** The ready marker shown once claude is running interactively. */
+export const DEV_CHANNELS_READY_MARKER = "bypass permissions on";
+
+/**
+ * Auto-confirm claude's `--dangerously-load-development-channels` consent gate in a
+ * detached tmux session (agent#70). NEVER throws.
+ */
+export async function confirmDevChannelsPrompt(
+  session: string,
+  opts: {
+    spawnFn?: typeof Bun.spawn;
+    timeoutMs?: number;
+    intervalMs?: number;
+    sleepFn?: (ms: number) => Promise<void>;
+  } = {},
+): Promise<"confirmed" | "already-running" | "timeout"> {
+  const spawnFn = opts.spawnFn ?? Bun.spawn;
+  const timeoutMs = opts.timeoutMs ?? 15_000;
+  const intervalMs = opts.intervalMs ?? 400;
+  const sleep = opts.sleepFn ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
+
+  async function capture(): Promise<string> {
+    try {
+      const proc = spawnFn(["tmux", "capture-pane", "-t", session, "-p"], {
+        stdout: "pipe",
+        stderr: "ignore",
+      });
+      const text = await new Response(proc.stdout as ReadableStream<Uint8Array>).text();
+      await proc.exited;
+      return text;
+    } catch {
+      return "";
+    }
+  }
+
+  const deadline = Date.now() + timeoutMs;
+  do {
+    const pane = await capture();
+    if (pane.includes(DEV_CHANNELS_PROMPT_MARKER)) {
+      try {
+        const proc = spawnFn(["tmux", "send-keys", "-t", session, "Enter"], {
+          stdout: "ignore",
+          stderr: "ignore",
+        });
+        await proc.exited;
+        return "confirmed";
+      } catch {
+        break;
+      }
+    }
+    if (pane.includes(DEV_CHANNELS_READY_MARKER)) {
+      return "already-running";
+    }
+    if (Date.now() >= deadline) break;
+    await sleep(intervalMs);
+  } while (Date.now() < deadline);
+
+  console.warn(
+    `parachute-agent: dev-channels consent prompt for tmux session "${session}" did not ` +
+      `appear within ${timeoutMs}ms (agent#70). If \`mcp_sessions\` stays 0, attach to the ` +
+      `session and press Enter in its terminal to clear the gate.`,
+  );
+  return "timeout";
+}
+
+/** The real tmux launcher — `tmux new-session -d` running the sandboxed argv via a launch script. */
+export function realTmuxLauncher(spawnFn: typeof Bun.spawn = Bun.spawn): TmuxLauncher {
+  return {
+    async hasSession(name: string): Promise<boolean> {
+      const proc = spawnFn(["tmux", "has-session", "-t", name], {
+        stdout: "ignore",
+        stderr: "ignore",
+      });
+      const code = await proc.exited;
+      return code === 0;
+    },
+    async newSession(opts): Promise<void> {
+      const scriptPath = launchScriptPath(opts.scriptDir ?? opts.cwd);
+      writeFileSync(scriptPath, buildLaunchScript(opts.argv), { mode: 0o600 });
+      chmodSync(scriptPath, 0o600);
+
+      const envArgs: string[] = [];
+      for (const [k, v] of Object.entries(opts.env)) {
+        if (typeof v === "string") envArgs.push("-e", `${k}=${v}`);
+      }
+      const argv = [
+        "tmux",
+        "new-session",
+        "-d",
+        "-s",
+        opts.name,
+        "-c",
+        opts.cwd,
+        "-x",
+        "220",
+        "-y",
+        "50",
+        ...envArgs,
+        "--",
+        "/bin/bash",
+        scriptPath,
+      ];
+      const proc = spawnFn(argv, { stdout: "pipe", stderr: "pipe" });
+      const code = await proc.exited;
+      if (code !== 0) {
+        const err = await new Response(proc.stderr as ReadableStream<Uint8Array>).text();
+        throw new Error(`tmux new-session failed (exit ${code}): ${err.trim()}`);
+      }
+    },
+    async confirmDevChannelsPrompt(session) {
+      return confirmDevChannelsPrompt(session, { spawnFn });
+    },
+  };
+}
+
+// ===========================================================================
+// The tmux SESSION ADMIN (was agents.ts).
+// ===========================================================================
+
+/** One running (or recently-launched) interactive agent session, as the page listed them. */
+export interface AgentInfo {
+  name: string;
+  session: string;
+  attached: boolean;
+  workspace: string;
+  hasWorkspace: boolean;
+  backend: "interactive";
+  status?: string;
+  channel?: string;
+  vault?: string;
+  systemPromptMode?: "append" | "replace";
+  workingDir?: string;
+}
+
+/** A redacted mint summary — scope + audience + expiry, NEVER the token value. */
+export interface RedactedToken {
+  resource: string;
+  scope: string;
+  expiresAt: string;
+}
+
+/** The redacted spawn result the web endpoint returned (no token values). */
+export interface RedactedSpawnResult {
+  session: string;
+  workspace: string;
+  alreadyRunning: boolean;
+  tokens: RedactedToken[];
+  mcpServers: string[];
+  filesystem: "workspace" | "full";
+  network: "open" | "restricted";
+  egress: string[];
+}
+
+export interface RedactedRestartResult extends RedactedSpawnResult {
+  killed: boolean;
+}
+
+/** The spawn/list/kill/restart operations the daemon routes called. Injectable for tests. */
+export interface AgentOps {
+  spawn(spec: AgentSpec): Promise<SpawnAgentResult>;
+  list(): Promise<AgentInfo[]>;
+  kill(name: string): Promise<{ killed: boolean }>;
+  restart(name: string): Promise<RedactedRestartResult>;
+}
+
+/** A tmux admin seam — real impl shells out to tmux; tests inject a recorder. */
+export interface TmuxAdmin {
+  listSessions(): Promise<{ name: string; attached: boolean }[]>;
+  killSession(name: string): Promise<boolean>;
+}
+
+/** Parse `tmux list-sessions -F '#{session_name} #{session_attached}'` stdout. */
+export function parseTmuxSessions(stdout: string): { name: string; attached: boolean }[] {
+  const out: { name: string; attached: boolean }[] = [];
+  for (const line of stdout.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const idx = trimmed.lastIndexOf(" ");
+    if (idx < 0) {
+      out.push({ name: trimmed, attached: false });
+      continue;
+    }
+    const name = trimmed.slice(0, idx);
+    const attachedRaw = trimmed.slice(idx + 1);
+    out.push({ name, attached: parseInt(attachedRaw, 10) > 0 });
+  }
+  return out;
+}
+
+/** Map raw tmux sessions to {@link AgentInfo}, keeping only `*-agent` sessions. */
+export function agentInfoFromSessions(
+  sessions: { name: string; attached: boolean }[],
+  sessionsDirPath: string,
+): AgentInfo[] {
+  const agents: AgentInfo[] = [];
+  for (const s of sessions) {
+    if (!s.name.endsWith(AGENT_SESSION_SUFFIX)) continue;
+    const name = s.name.slice(0, -AGENT_SESSION_SUFFIX.length);
+    if (name.length === 0) continue;
+    const workspace = sessionWorkspace(sessionsDirPath, name);
+    const persisted = readPersistedSpec(workspace);
+    const hasPrompt = typeof persisted?.systemPrompt === "string" && persisted.systemPrompt.length > 0;
+    const hasWorkingDir =
+      typeof persisted?.workspace === "string" &&
+      persisted.workspace.length > 0 &&
+      existsSync(persisted.workspace);
+    agents.push({
+      name,
+      session: s.name,
+      attached: s.attached,
+      workspace,
+      hasWorkspace: existsSync(join(workspace, ".mcp.json")),
+      backend: "interactive",
+      ...(hasPrompt ? { systemPromptMode: persisted!.systemPromptMode ?? "append" } : {}),
+      ...(hasWorkingDir ? { workingDir: persisted!.workspace } : {}),
+    });
+  }
+  agents.sort((a, b) => a.name.localeCompare(b.name));
+  return agents;
+}
+
+/** The real tmux admin — shells out via Bun.spawn. */
+export function realTmuxAdmin(spawnFn: typeof Bun.spawn = Bun.spawn): TmuxAdmin {
+  return {
+    async listSessions() {
+      const proc = spawnFn(
+        ["tmux", "list-sessions", "-F", "#{session_name} #{session_attached}"],
+        { stdout: "pipe", stderr: "pipe" },
+      );
+      const code = await proc.exited;
+      if (code !== 0) return [];
+      const stdout = await new Response(proc.stdout as ReadableStream<Uint8Array>).text();
+      return parseTmuxSessions(stdout);
+    },
+    async killSession(name: string) {
+      const proc = spawnFn(["tmux", "kill-session", "-t", name], {
+        stdout: "ignore",
+        stderr: "ignore",
+      });
+      const code = await proc.exited;
+      return code === 0;
+    },
+  };
+}
+
+/** Redact a {@link SpawnAgentResult} for the wire — never the token values. */
+export function redactSpawnResult(result: SpawnAgentResult): RedactedSpawnResult {
+  const tokens: RedactedToken[] = Object.entries(result.tokens).map(([resource, minted]) => ({
+    resource,
+    scope: minted.scope,
+    expiresAt: minted.expiresAt,
+  }));
+  let mcpServers: string[] = [];
+  try {
+    const parsed = JSON.parse(result.mcpConfigJson || "{}") as { mcpServers?: Record<string, unknown> };
+    mcpServers = Object.keys(parsed.mcpServers ?? {});
+  } catch {
+    mcpServers = [];
+  }
+  const allowed = result.wrapped.config.network.allowedDomains as string[] | undefined;
+  const scopedReads = (result.wrapped.config.filesystem.denyRead ?? []).length > 0;
+  return {
+    session: result.session,
+    workspace: result.workspace,
+    alreadyRunning: result.alreadyRunning,
+    tokens,
+    mcpServers,
+    filesystem: scopedReads ? "workspace" : "full",
+    network: allowed === undefined ? "open" : "restricted",
+    egress: allowed ?? [],
+  };
+}
+
+/**
+ * The PARKED interactive {@link AgentOps} — spawn/list/kill/restart over tmux
+ * sessions. The live daemon no longer constructs or routes to this (the
+ * interactive backend retired); kept buildable for the future revival + its tests.
+ * `depsFactory` resolves the shared base deps; the caller supplies the tmux launcher.
+ */
+export function createRealAgentOps(opts?: {
+  depsFactory?: () => SpawnAgentDeps;
+  tmux?: TmuxAdmin;
+  sessionsDirPath?: string;
+}): AgentOps {
+  const depsFactory =
+    opts?.depsFactory ?? (() => {
+      throw new SpawnRequestError(
+        "createRealAgentOps: no depsFactory — the interactive backend is parked; wire " +
+          "resolveSpawnDeps + realTmuxLauncher explicitly if reviving it.",
+      );
+    });
+  const tmux = opts?.tmux ?? realTmuxAdmin();
+  const dir = opts?.sessionsDirPath ?? "";
+  return {
+    async spawn(spec) {
+      return spawnAgent(spec, depsFactory());
+    },
+    async list() {
+      return agentInfoFromSessions(await tmux.listSessions(), dir);
+    },
+    async kill(name) {
+      if (!AGENT_NAME_SLUG.test(name)) {
+        throw new SpawnRequestError(
+          `agent name "${name}" must be a slug (alphanumeric, dash, underscore only)`,
+        );
+      }
+      const killed = await tmux.killSession(sessionName(name));
+      return { killed };
+    },
+    async restart(name) {
+      if (!AGENT_NAME_SLUG.test(name)) {
+        throw new SpawnRequestError(
+          `agent name "${name}" must be a slug (alphanumeric, dash, underscore only)`,
+        );
+      }
+      const workspace = sessionWorkspace(dir, name);
+      const spec = readPersistedSpec(workspace);
+      if (!spec) {
+        throw new SpawnRequestError(
+          `cannot restart agent "${name}": no persisted spec at ${workspace}/spec.json ` +
+            `(it predates spawn-spec persistence, or was never spawned through this daemon). ` +
+            `Kill it and spawn a fresh session from the Agents page.`,
+        );
+      }
+      const killed = await tmux.killSession(sessionName(name));
+      const result = await spawnAgent(spec, depsFactory());
+      return { ...redactSpawnResult(result), killed };
+    },
+  };
+}
+
+/** Parse a mount entry from an untrusted body (parked). */
+export function parseMountEntry(raw: unknown, i: number): AgentMount {
+  if (!raw || typeof raw !== "object") {
+    throw new SpawnRequestError(`body.mounts[${i}] must be { hostPath, mountPath, mode, shared? }`);
+  }
+  const m = raw as Record<string, unknown>;
+  if (typeof m.hostPath !== "string" || m.hostPath.length === 0) {
+    throw new SpawnRequestError(`body.mounts[${i}].hostPath (non-empty string) is required`);
+  }
+  if (typeof m.mountPath !== "string" || m.mountPath.length === 0) {
+    throw new SpawnRequestError(`body.mounts[${i}].mountPath (non-empty string) is required`);
+  }
+  if (!m.hostPath.startsWith("/")) {
+    throw new SpawnRequestError(`body.mounts[${i}].hostPath must be an absolute path (start with "/")`);
+  }
+  if (!m.mountPath.startsWith("/")) {
+    throw new SpawnRequestError(`body.mounts[${i}].mountPath must be an absolute path (start with "/")`);
+  }
+  if (m.mode !== "ro" && m.mode !== "rw") {
+    throw new SpawnRequestError(`body.mounts[${i}].mode must be "ro" or "rw"`);
+  }
+  const mount: AgentMount = {
+    hostPath: m.hostPath,
+    mountPath: m.mountPath,
+    mode: m.mode as "ro" | "rw",
+  };
+  if (m.shared !== undefined && m.shared !== null) {
+    if (typeof m.shared !== "string" || m.shared.length === 0) {
+      throw new SpawnRequestError(`body.mounts[${i}].shared must be a non-empty string`);
+    }
+    mount.shared = m.shared;
+  }
+  return mount;
+}
+
+// Re-exported so the parked unit references resolve without reaching into the live tree.
+export type { AgentSpec, AgentChannel, AgentVaultSpec, AgentMount };
+export { statSync };