typeclaw 0.1.0

package/src/config/reloadable.ts

@@ -0,0 +1,47 @@
+import type { Reloadable, ReloadResult } from '@/reload'
+
+import { type ConfigReloadDiff, reloadConfig, validateConfig } from './config'
+
+export type CreateConfigReloadableOptions = {
+  cwd: string
+}
+
+export function createConfigReloadable({ cwd }: CreateConfigReloadableOptions): Reloadable {
+  return {
+    scope: 'config',
+    description: 'typeclaw.json runtime config',
+    reload: async () => doReload(cwd),
+  }
+}
+
+async function doReload(cwd: string): Promise<ReloadResult> {
+  // Mount accessibility belongs to the validation surface, not loadConfigSync —
+  // validateConfig is the single gate that every host-side caller goes through.
+  // Run it before swapping the live config pointer so a mount that vanished
+  // between starts surfaces as a reload failure (`mounts` is restart-required
+  // anyway, so the user has to restart to pick up changes; better to flag the
+  // problem now than to let restart fail later).
+  const validated = validateConfig(cwd)
+  if (!validated.ok) {
+    return { scope: 'config', ok: false, reason: validated.reason }
+  }
+
+  let diff: ConfigReloadDiff
+  try {
+    diff = reloadConfig(cwd)
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    return { scope: 'config', ok: false, reason: message }
+  }
+
+  return {
+    scope: 'config',
+    ok: true,
+    summary: formatSummary(diff),
+    details: diff,
+  }
+}
+
+function formatSummary(diff: ConfigReloadDiff): string {
+  return `${diff.applied.length} applied, ${diff.restartRequired.length} restart-required, ${diff.ignored.length} ignored`
+}

package/src/container/index.ts

@@ -0,0 +1,27 @@
+export { logs, planLogs, type LogsPlan, type LogsResult } from './logs'
+export { CONTAINER_PORT, findFreePort, resolveHostPort } from './port'
+export { planShell, shell, type ShellPlan, type ShellResult } from './shell'
+export { status, type ContainerStatus, type StatusOptions } from './status'
+export {
+  checkDockerAvailable,
+  containerExists,
+  containerNameFromCwd,
+  defaultDockerExec,
+  DOCKER_NOT_FOUND_STDERR,
+  imageTagFromCwd,
+  inspectContainer,
+  type ContainerState,
+  type DockerAvailability,
+  type DockerExec,
+  type DockerExecResult,
+} from './shared'
+export {
+  planStart,
+  start,
+  type HostDaemonStatus,
+  type PlanStartOptions,
+  type StartOptions,
+  type StartPlan,
+  type StartResult,
+} from './start'
+export { planStop, stop, type StopOptions, type StopPlan, type StopResult } from './stop'

package/src/container/logs.ts

@@ -0,0 +1,37 @@
+import { containerExists, containerNameFromCwd, getBun } from './shared'
+
+export type LogsPlan = {
+  containerName: string
+  follow: boolean
+}
+
+export type LogsResult = { ok: true; containerName: string; exitCode: number } | { ok: false; reason: string }
+
+export async function logs({ cwd, follow }: { cwd: string; follow: boolean }): Promise<LogsResult> {
+  const bun = getBun()
+  if (!bun) return { ok: false, reason: 'bun runtime not available' }
+
+  const { containerName } = planLogs(cwd, { follow })
+
+  try {
+    if (!(await containerExists(containerName))) {
+      return { ok: false, reason: `Container ${containerName} not found. Run \`typeclaw start\` first.` }
+    }
+
+    const cmd = ['docker', 'logs']
+    if (follow) cmd.push('-f')
+    cmd.push(containerName)
+
+    // Inherit stdio so logs stream live and Ctrl+C reaches `docker logs`,
+    // which exits cleanly on SIGINT in follow mode.
+    const proc = bun.spawn({ cmd, cwd, stdout: 'inherit', stderr: 'inherit' })
+    const exitCode = await proc.exited
+    return { ok: true, containerName, exitCode }
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? error.message : String(error) }
+  }
+}
+
+export function planLogs(cwd: string, { follow }: { follow: boolean }): LogsPlan {
+  return { containerName: containerNameFromCwd(cwd), follow }
+}

package/src/container/port.ts

@@ -0,0 +1,137 @@
+import { createServer } from 'node:net'
+
+import { loadConfigSync } from '@/config'
+
+import { containerNameFromCwd, defaultDockerExec, type DockerExec } from './shared'
+
+// The port the agent's WebSocket server binds to *inside* the container. Host
+// publishing maps a host-side port (chosen at `typeclaw start` time) to this
+// fixed internal port. Decoupling the two lets multiple agents coexist on a
+// single host without colliding on 8973 — see issue #1.
+//
+// Kept identical to the legacy DEFAULT_PORT so a containerful upgrade path
+// works: containers started before this change used `-p 8973:8973`, and after
+// the upgrade `docker port <name> 8973/tcp` still resolves correctly.
+export const CONTAINER_PORT = 8973
+
+// Asks the kernel for a free TCP port. When `preferred` is supplied, tries
+// that port first; if it's already bound, falls back to a kernel-assigned
+// ephemeral port via `listen(0)`. The returned port is *not* held — the test
+// server is closed before resolving, so a different process could grab it
+// before we hand it to Docker. Callers that pipe the result into `docker run`
+// should treat docker's bind error as authoritative and retry on conflict.
+export async function findFreePort(preferred?: number): Promise<number> {
+  if (preferred !== undefined && preferred > 0) {
+    if (await isPortFree(preferred)) return preferred
+  }
+  return listenEphemeral()
+}
+
+async function isPortFree(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const server = createServer()
+    server.unref()
+    server.once('error', () => resolve(false))
+    server.listen({ port, host: '0.0.0.0', exclusive: true }, () => {
+      server.close(() => resolve(true))
+    })
+  })
+}
+
+async function listenEphemeral(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const server = createServer()
+    server.unref()
+    server.once('error', reject)
+    server.listen({ port: 0, host: '0.0.0.0', exclusive: true }, () => {
+      const address = server.address()
+      if (typeof address !== 'object' || address === null) {
+        server.close()
+        reject(new Error('failed to obtain ephemeral port'))
+        return
+      }
+      const port = address.port
+      server.close((err) => {
+        if (err) reject(err)
+        else resolve(port)
+      })
+    })
+  })
+}
+
+// Docker's bind-conflict error from `docker run -p`. Used by `start` to decide
+// whether to retry with a fresh ephemeral port or surface the failure as-is.
+export function isPortAllocatedError(stderr: string): boolean {
+  const lower = stderr.toLowerCase()
+  return (
+    lower.includes('port is already allocated') ||
+    lower.includes('address already in use') ||
+    lower.includes('bind for') // catches "Bind for :::8973 failed: port is already allocated"
+  )
+}
+
+export type ResolveHostPortOptions = {
+  cwd: string
+  exec?: DockerExec
+  retryMs?: number
+  intervalMs?: number
+  fallbackPort?: number
+}
+
+// Returns the host port that `typeclaw tui` / `typeclaw reload` should connect
+// to. Docker is the source of truth for a running container; we ask
+// `docker port <name> ${CONTAINER_PORT}/tcp` and parse the host-side port out
+// of the mapping. If the container isn't running (or we're on an old
+// pre-fix container that doesn't expose CONTAINER_PORT internally), we fall
+// back to the config's `port` field as a best-effort guess.
+export async function resolveHostPort(options: ResolveHostPortOptions): Promise<number> {
+  const exec = options.exec ?? defaultDockerExec
+  const containerName = containerNameFromCwd(options.cwd)
+  const retryMs = options.retryMs ?? 1500
+  const intervalMs = options.intervalMs ?? 100
+
+  const deadline = Date.now() + retryMs
+  while (true) {
+    const port = await queryDockerHostPort(exec, containerName)
+    if (port !== null) return port
+    if (Date.now() >= deadline) break
+    await sleep(intervalMs)
+  }
+
+  if (options.fallbackPort !== undefined) return options.fallbackPort
+  return loadConfigSync(options.cwd).port
+}
+
+async function queryDockerHostPort(exec: DockerExec, containerName: string): Promise<number | null> {
+  const result = await exec(['port', containerName, `${CONTAINER_PORT}/tcp`])
+  if (result.exitCode !== 0) return null
+  return parseDockerPortOutput(result.stdout)
+}
+
+// `docker port` prints one mapping per line, e.g.:
+//   0.0.0.0:49160
+//   :::49160
+//   [::]:49160
+// We pick the last numeric segment after the final colon. If multiple lines
+// are present we prefer an IPv4 mapping (most localhost connects resolve to
+// IPv4 first on macOS/Linux), falling back to whatever parses cleanly.
+export function parseDockerPortOutput(stdout: string): number | null {
+  const lines = stdout
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)
+  if (lines.length === 0) return null
+
+  const ipv4 = lines.find((line) => /^\d{1,3}(\.\d{1,3}){3}:\d+$/.test(line))
+  const candidate = ipv4 ?? lines[0]!
+  const lastColon = candidate.lastIndexOf(':')
+  if (lastColon < 0) return null
+  const portStr = candidate.slice(lastColon + 1)
+  const port = Number(portStr)
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) return null
+  return port
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}

package/src/container/shared.ts

@@ -0,0 +1,290 @@
+import { basename, resolve } from 'node:path'
+
+export type DockerExecResult = { exitCode: number; stdout: string; stderr: string }
+
+export type DockerExec = (
+  args: string[],
+  options?: { cwd?: string; inheritStdio?: boolean; signal?: AbortSignal },
+) => Promise<DockerExecResult>
+
+export const defaultDockerExec: DockerExec = async (args, options) => {
+  const bun = getBun()
+  if (!bun) return { exitCode: -1, stdout: '', stderr: 'bun runtime not available' }
+  // Bun.spawn throws synchronously with code 'ENOENT' when docker isn't on
+  // $PATH (rather than returning a non-zero exit). Two overloads (pipe vs
+  // inherit) so each spawn call site has the literal stdout/stderr type
+  // attached — that's what lets `new Response(proc.stdout)` typecheck on
+  // the piped path. `signal` is forwarded to Bun.spawn so callers can bound
+  // long-running docker subcommands (e.g. `docker logs` on a stuck daemon).
+  if (options?.inheritStdio) {
+    try {
+      const proc = bun.spawn({
+        cmd: ['docker', ...args],
+        cwd: options.cwd,
+        stdout: 'inherit',
+        stderr: 'inherit',
+        signal: options.signal,
+      })
+      return { exitCode: await proc.exited, stdout: '', stderr: '' }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException)?.code === 'ENOENT') {
+        return { exitCode: -1, stdout: '', stderr: DOCKER_NOT_FOUND_STDERR }
+      }
+      throw error
+    }
+  }
+  try {
+    const proc = bun.spawn({
+      cmd: ['docker', ...args],
+      cwd: options?.cwd,
+      stdout: 'pipe',
+      stderr: 'pipe',
+      signal: options?.signal,
+    })
+    const exitCode = await proc.exited
+    const stdout = await new Response(proc.stdout).text()
+    const stderr = await new Response(proc.stderr).text()
+    return { exitCode, stdout, stderr }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException)?.code === 'ENOENT') {
+      return { exitCode: -1, stdout: '', stderr: DOCKER_NOT_FOUND_STDERR }
+    }
+    throw error
+  }
+}
+
+// Sentinel stderr from defaultDockerExec when Bun.spawn throws ENOENT.
+// checkDockerAvailable matches on this exact string to distinguish
+// "binary missing" from "daemon down".
+export const DOCKER_NOT_FOUND_STDERR = 'docker: command not found in $PATH'
+
+// Collapse a multi-line `docker` CLI stderr into a single readable clause
+// suitable for inline `reason:` strings. The motivating case is `compose
+// restart`, which prints one row per agent — raw stderr from a failed
+// `docker run` is 3-5 lines (leading `docker: ` prefix, daemon error body,
+// blank line, "Run 'docker run --help' for more information" tail) and
+// turns each failing row into an ASCII wall. Strip the boilerplate, drop
+// the help-pointer tail (it's noise in a programmatic context — users who
+// hit it can run `docker run --help` themselves), and join any remaining
+// detail lines with "; " so the result fits on the same row as the
+// `✖ [name] failed:` prefix that wraps it.
+export function sanitizeDockerStderr(stderr: string): string {
+  const withoutHelpTail = stderr.replace(/\n*\s*Run '[^']+--help' for more information\s*\n?/g, '')
+  const lines = withoutHelpTail
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)
+    .map((line) => line.replace(/^docker:\s*/, '').replace(/^Error response from daemon:\s*/, ''))
+    .filter((line) => line.length > 0)
+  return lines.join('; ')
+}
+
+export type DockerAvailability = { ok: true } | { ok: false; reason: 'binary-missing' | 'daemon-down'; detail: string }
+
+// `docker info --format {{.ServerVersion}}` is the probe of choice because it
+// requires both the client AND a reachable daemon. `docker --version` would
+// miss the "Docker Desktop installed but not running" case, which is the
+// common failure mode on macOS.
+export async function checkDockerAvailable(exec: DockerExec = defaultDockerExec): Promise<DockerAvailability> {
+  const result = await exec(['info', '--format', '{{.ServerVersion}}'])
+  if (result.exitCode === 0) return { ok: true }
+  if (result.stderr === DOCKER_NOT_FOUND_STDERR) {
+    return { ok: false, reason: 'binary-missing', detail: result.stderr }
+  }
+  return {
+    ok: false,
+    reason: 'daemon-down',
+    detail: result.stderr.trim() || `docker info exited with code ${result.exitCode}`,
+  }
+}
+
+export function containerNameFromCwd(cwd: string): string {
+  return sanitizeContainerName(basename(resolve(cwd)))
+}
+
+// `docker rm` failures we treat as recoverable. The kind matters for the
+// caller's next step:
+//   - 'gone'        — "No such container". The container is already removed
+//                     (peer `typeclaw stop`, manual `docker rm`, or async
+//                     post-stop cleanup that finished first). The name is
+//                     free to reuse immediately.
+//   - 'in-progress' — "removal of container … is already in progress". Docker
+//                     accepted a prior remove and is still draining it. The
+//                     container is STILL PRESENT in `docker inspect` until
+//                     the drain completes, so a `docker run --name <same>`
+//                     fired right now would collide. Callers that follow
+//                     `rm` with `run` MUST wait for the container to
+//                     actually disappear — see waitForRemoval.
+//   - null          — non-benign failure; surface as an error.
+export type BenignRmKind = 'gone' | 'in-progress' | null
+
+export function classifyRmStderr(stderr: string): BenignRmKind {
+  const lower = stderr.toLowerCase()
+  if (lower.includes('no such container')) return 'gone'
+  if (lower.includes('removal of container')) return 'in-progress'
+  return null
+}
+
+// Detects Docker's name-conflict response from `docker run --name <X>`:
+//   docker: Error response from daemon: Conflict. The container name
+//   "/<X>" is already in use by container "<id>". You have to remove
+//   (or rename) that container to be able to reuse that name.
+//
+// The dominant cause of this error in `typeclaw compose restart` is NOT a
+// transient name-reservation drain (PR #121's hypothesis) but a concrete
+// corpse left behind by an earlier `docker run` in the same start() call
+// that failed AFTER Docker created the container record. The canonical
+// path: compose restart fires N agents in parallel via Promise.all; they
+// race for the preferred host port; the loser's `docker run -p <busy>:...`
+// fails with "port is already allocated", and depending on the daemon
+// version Docker may have already created the container record before the
+// port bind failed. start()'s port-TOCTOU retry then re-runs `docker run`
+// with a fresh ephemeral port but the SAME --name, and hits this conflict
+// against the corpse from the previous attempt. The corpse is stable —
+// sleep-only retries cannot make it go away.
+//
+// The fix is destructive: when this error fires for a non-running same-name
+// container, force-remove it before retrying. See cleanupRunCorpse for the
+// safety contract (only force-remove containers that are NOT running, so a
+// concurrent legitimate start of the same name is never killed).
+//
+// Matches case-insensitively on the canonical phrasing across Docker
+// Engine, Docker Desktop, and OrbStack. The (or rename) clause is the
+// most stable substring across vendor message variants.
+export function isContainerNameConflict(stderr: string): boolean {
+  const lower = stderr.toLowerCase()
+  return lower.includes('container name') && lower.includes('is already in use')
+}
+
+// Result of probing whether a previous `docker run --name <X>` left a corpse
+// blocking the next run:
+//   - 'gone'     — no container with that name. Safe to `docker run --name`.
+//   - 'removed'  — corpse existed and was force-removed (and waitForRemoval
+//                  confirmed it disappeared). Safe to `docker run --name`.
+//   - 'running'  — a container with that name is currently RUNNING. We did
+//                  NOT remove it. Caller must NOT proceed with `docker run
+//                  --name <same>`: that would either fail again or imply a
+//                  concurrent legitimate start that we should not kill.
+//   - 'stuck'    — corpse existed but did not disappear within waitForRemoval
+//                  budget. Caller should surface a clear error rather than
+//                  loop forever.
+export type CorpseCleanupOutcome = 'gone' | 'removed' | 'running' | 'stuck'
+
+// Inspects the named container; if a non-running corpse is holding the
+// name (the failure mode behind `typeclaw compose restart`'s persistent
+// Conflict errors), force-removes it and waits for the removal to drain.
+// Explicitly refuses to touch a RUNNING container so that a concurrent
+// legitimate start of the same name (or a foreign-but-named container the
+// user wants kept alive) is never killed by this cleanup path. Errors from
+// the rm itself are folded into 'stuck' so the caller can surface a single
+// "still here" reason rather than chase docker stderr variants.
+//
+// The rm is keyed on the container ID we read from the same inspect call,
+// NOT on the name. This closes the TOCTOU window where another process
+// could create a live container with the same name between our inspect
+// (saw a non-running corpse with ID A) and our rm: removing by name would
+// kill the new live container with ID B, but removing by ID A targets the
+// specific corpse we measured. If ID A is already gone by the time rm
+// fires (e.g. a concurrent cleanup beat us), the rm returns "No such
+// container" which classifyRmStderr folds into 'gone'. waitForRemoval
+// is still keyed on name because that's what the caller's next
+// `docker run --name <name>` will actually collide on.
+export async function cleanupRunCorpse(exec: DockerExec, name: string): Promise<CorpseCleanupOutcome> {
+  const probe = await exec(['inspect', '--format', '{{.Id}}|{{.State.Running}}', name])
+  if (probe.exitCode !== 0) return 'gone'
+  const [id = '', running = ''] = probe.stdout.trim().split('|')
+  if (running === 'true') return 'running'
+  if (id === '') return 'stuck'
+  const rm = await exec(['rm', '-f', id])
+  if (rm.exitCode !== 0) {
+    const kind = classifyRmStderr(rm.stderr)
+    if (kind === 'gone') return 'gone'
+    if (kind === null) return 'stuck'
+  }
+  return (await waitForRemoval(exec, name)) ? 'removed' : 'stuck'
+}
+
+// Polls `docker inspect` until the named container is gone or the deadline
+// elapses. Required after a `docker rm` that returned "removal of container
+// … is already in progress": Docker has committed to removal but has not
+// finished, so the name is briefly still taken. Without this wait, the
+// caller's subsequent `docker run --name <same>` races the daemon's
+// removal-drain and intermittently fails with a name conflict (the
+// user-visible symptom under `typeclaw compose restart` and any restart of
+// a container that hostd's GC tick raced ahead on). Returns true if the
+// container disappeared before the deadline, false on timeout.
+//
+// NOTE: `inspect` reporting "gone" is necessary but NOT sufficient for
+// `docker run --name <same>` to succeed — Docker's name-reservation table
+// drains independently. waitForRemoval is the fast path; the retry on
+// `docker run` (see isContainerNameConflict) is the safety net.
+export async function waitForRemoval(
+  exec: DockerExec,
+  name: string,
+  options: { timeoutMs?: number; intervalMs?: number } = {},
+): Promise<boolean> {
+  const timeoutMs = options.timeoutMs ?? 10_000
+  const intervalMs = options.intervalMs ?? 100
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    const result = await exec(['inspect', '--format', '{{.State.Running}}', name])
+    if (result.exitCode !== 0) return true
+    await new Promise((resolve) => setTimeout(resolve, intervalMs))
+  }
+  const final = await exec(['inspect', '--format', '{{.State.Running}}', name])
+  return final.exitCode !== 0
+}
+
+export function imageTagFromCwd(cwd: string): string {
+  return `typeclaw-${containerNameFromCwd(cwd)}`
+}
+
+// Docker container names must match [a-zA-Z0-9][a-zA-Z0-9_.-]*.
+function sanitizeContainerName(name: string): string {
+  const cleaned = name.replace(/[^a-zA-Z0-9_.-]/g, '-')
+  if (cleaned === '' || !/^[a-zA-Z0-9]/.test(cleaned)) {
+    return `tc-${cleaned || 'agent'}`
+  }
+  return cleaned
+}
+
+export async function imageExists(tag: string): Promise<boolean> {
+  const bun = getBun()
+  if (!bun) return false
+  const proc = bun.spawn({
+    cmd: ['docker', 'image', 'inspect', tag],
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  return (await proc.exited) === 0
+}
+
+export async function containerExists(name: string): Promise<boolean> {
+  return (await inspectContainer(name)).exists
+}
+
+export type ContainerState = { exists: false } | { exists: true; running: boolean }
+
+// `docker inspect` is the canonical way to ask Docker about a single container
+// by name. It returns exit 0 with `true`/`false` when the container exists (in
+// any state: running, exited, dead, or being removed) and exit 1 otherwise.
+// We deliberately do NOT use `docker ps` / `docker ps -a` here because the
+// State.Running boolean — not mere presence in `ps -a` — is what callers need
+// to distinguish a live agent from a corpse left over after a crash (which,
+// since we run without `--rm`, sticks around in `ps -a` until the next start).
+export async function inspectContainer(name: string): Promise<ContainerState> {
+  const bun = getBun()
+  if (!bun) return { exists: false }
+  const proc = bun.spawn({
+    cmd: ['docker', 'inspect', '--format', '{{.State.Running}}', name],
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  if ((await proc.exited) !== 0) return { exists: false }
+  const out = (await new Response(proc.stdout).text()).trim()
+  return { exists: true, running: out === 'true' }
+}
+
+export function getBun(): { spawn: typeof Bun.spawn } | undefined {
+  return (globalThis as { Bun?: { spawn: typeof Bun.spawn } }).Bun
+}

package/src/container/shell.ts

@@ -0,0 +1,58 @@
+import { containerNameFromCwd, getBun, inspectContainer, type ContainerState } from './shared'
+
+export type ShellPlan = {
+  containerName: string
+  shell: string
+}
+
+export type ShellResult = { ok: true; containerName: string; exitCode: number } | { ok: false; reason: string }
+
+type ShellDeps = {
+  inspect?: (name: string) => Promise<ContainerState>
+  spawn?: InteractiveSpawn
+}
+
+type InteractiveSpawn = (options: {
+  cmd: string[]
+  cwd: string
+  stdin: 'inherit'
+  stdout: 'inherit'
+  stderr: 'inherit'
+}) => { exited: Promise<number> }
+
+export async function shell(
+  { cwd, shell: shellPath = '/bin/bash' }: { cwd: string; shell?: string },
+  deps: ShellDeps = {},
+): Promise<ShellResult> {
+  const bun = getBun()
+  const spawn = deps.spawn ?? bun?.spawn
+  if (!spawn) return { ok: false, reason: 'bun runtime not available' }
+
+  const { containerName, shell: plannedShell } = planShell(cwd, { shell: shellPath })
+
+  try {
+    const state = await (deps.inspect ?? inspectContainer)(containerName)
+    if (!state.exists) {
+      return { ok: false, reason: `Container ${containerName} not found. Run \`typeclaw start\` first.` }
+    }
+    if (!state.running) {
+      return { ok: false, reason: `Container ${containerName} is not running. Run \`typeclaw start\` first.` }
+    }
+
+    const proc = spawn({
+      cmd: ['docker', 'exec', '-it', containerName, plannedShell],
+      cwd,
+      stdin: 'inherit',
+      stdout: 'inherit',
+      stderr: 'inherit',
+    })
+    const exitCode = await proc.exited
+    return { ok: true, containerName, exitCode }
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? error.message : String(error) }
+  }
+}
+
+export function planShell(cwd: string, { shell: shellPath = '/bin/bash' }: { shell?: string } = {}): ShellPlan {
+  return { containerName: containerNameFromCwd(cwd), shell: shellPath }
+}