@excitedjs/tm 1.1.0

package/src/engines/claude/keys.ts

@@ -0,0 +1,163 @@
+/**
+ * `tm`'s `_send_keys`: push a prompt into a teammate's tmux pane.
+ *
+ * The hot-path verbs (`spawn` atomic-prompt tail, `send`, `compact`)
+ * share the same delivery shape — two modes by size, both clear the
+ * idle/last/busy baseline first and touch `<name>.send-at`. Centralised
+ * here so a future fix lands across every verb that composes them.
+ */
+
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { randomBytes } from 'node:crypto'
+import { dirname } from 'node:path'
+
+import { clearIdle, resolveSid } from './idle'
+import { sendAtFile, tmuxSessionName } from '../../persistence/paths'
+import { die, requireSession, resolvePaneTarget } from './tmux'
+import { sleepMs } from './clock'
+import type { TeammateName } from '../types'
+import type { TmResult } from '../../tm'
+import type { TmuxRunner } from '../../tmux'
+
+/** Runtime knobs `_send_keys` reads from the environment. */
+export interface SendKeysConfig {
+  /** Max prompt size (chars) to take the inline `send-keys -l + Enter` path. */
+  inlineMax: number
+  /** Optional override (seconds) for the post-paste settle gap. */
+  gapOverride: string | null
+}
+
+/**
+ * Parse the env knobs for `_send_keys` once per call — a malformed value
+ * dies up front rather than crashing the script mid-flow.
+ */
+export function readSendKeysConfig(env: NodeJS.ProcessEnv): SendKeysConfig | TmResult {
+  const inlineRaw = env.TM_SEND_INLINE_MAX ?? ''
+  const inlineMax = inlineRaw === '' ? 200 : Number(inlineRaw)
+  if (inlineRaw !== '' && !/^[0-9]+$/.test(inlineRaw)) {
+    return die(`TM_SEND_INLINE_MAX must be a non-negative integer (got: '${inlineRaw}')`)
+  }
+  const gapRaw = env.TM_SEND_GAP ?? ''
+  if (gapRaw !== '' && !/^[0-9]+(\.[0-9]+)?$/.test(gapRaw)) {
+    return die(`TM_SEND_GAP must be a non-negative number of seconds (got: '${gapRaw}')`)
+  }
+  return { inlineMax, gapOverride: gapRaw === '' ? null : gapRaw }
+}
+
+/** `tm`'s size-based default paste-buffer settle gap, in seconds. */
+export function defaultPasteGapSec(promptLength: number): number {
+  if (promptLength <= 256) return 0.2
+  if (promptLength <= 1024) return 0.5
+  if (promptLength <= 4096) return 1.0
+  if (promptLength <= 16384) return 2.0
+  return 4.0
+}
+
+/**
+ * `tm`'s `_send_keys`. Two delivery modes by size:
+ *
+ *  - short single-line prompts take the inline `send-keys -l + Enter`
+ *    fast path
+ *  - larger or multi-line prompts stage the bytes in a named tmux
+ *    buffer and `paste-buffer -p -r` them in a single bracketed-paste
+ *    sequence, then send Enter after the trailing `\e[201~` marker
+ *
+ * Both modes clear the idle baseline first and touch `<name>.send-at`.
+ *
+ * Returns the `TmResult` whose stderr carries the `sent to ... ` /
+ * `sid=...` lines `cmd_send`'s preamble emits.
+ */
+export async function sendKeys(
+  name: TeammateName,
+  prompt: string,
+  runTmux: TmuxRunner,
+  processEnv: NodeJS.ProcessEnv,
+): Promise<TmResult> {
+  const sessionMissing = await requireSession(name, runTmux)
+  if (sessionMissing !== null) return sessionMissing
+
+  const pane = await resolvePaneTarget(name, runTmux)
+  if (pane === '') return die(`could not resolve pane target for ${name}`)
+
+  const cfg = readSendKeysConfig(processEnv)
+  if ('code' in cfg) return cfg
+
+  // Clear the idle baseline before sending so the subsequent wait reflects
+  // THIS turn, not a prior one. A no-sid case is the fresh-spawn path where
+  // there is no prior turn to clear.
+  const sid = resolveSid(name)
+  if (sid !== null) clearIdle(sid)
+
+  // `tm`'s `: > "$(send_at_file "$repo")"` — touch the marker.
+  const sa = sendAtFile(name)
+  mkdirSync(dirname(sa), { recursive: true })
+  writeFileSync(sa, '')
+
+  const n = prompt.length
+  const inlinePath = n <= cfg.inlineMax && !prompt.includes('\n')
+
+  const session = tmuxSessionName(name)
+  let stderr = `sent to ${name} (tmux=${session})\n`
+  if (sid !== null) stderr += `sid=${sid}\n`
+
+  // `bin/tm` runs under `set -euo pipefail`, so a failed `tmux send-keys` /
+  // `load-buffer` / `paste-buffer` aborts the script before the verb claims
+  // success. Mirror that: any non-zero tmux exit fails the verb so the
+  // dispatcher does not later block on a Stop hook that will never fire.
+  const tmuxOk = (
+    result: { code: number; stderr: string },
+    what: string,
+  ): TmResult | null =>
+    result.code === 0
+      ? null
+      : die(`tmux ${what} failed: ${result.stderr.trim() || 'non-zero exit'}`)
+
+  if (inlinePath) {
+    const sent = await runTmux(['send-keys', '-t', pane, '-l', prompt])
+    const sentErr = tmuxOk(sent, 'send-keys')
+    if (sentErr !== null) return sentErr
+    const enter = await runTmux(['send-keys', '-t', pane, 'Enter'])
+    const enterErr = tmuxOk(enter, 'send-keys Enter')
+    if (enterErr !== null) return enterErr
+    return { code: 0, stdout: '', stderr }
+  }
+
+  const gap = cfg.gapOverride !== null ? Number(cfg.gapOverride) : defaultPasteGapSec(n)
+  const buf = `tm-send-${process.pid}-${randomBytes(2).toString('hex')}`
+  let loaded = false
+  try {
+    const loadResult = await runTmux(['load-buffer', '-b', buf, '-'], { stdin: prompt })
+    const loadErr = tmuxOk(loadResult, 'load-buffer')
+    if (loadErr !== null) return loadErr
+    loaded = true
+    const pasteResult = await runTmux([
+      'paste-buffer',
+      '-p',
+      '-r',
+      '-d',
+      '-b',
+      buf,
+      '-t',
+      pane,
+    ])
+    const pasteErr = tmuxOk(pasteResult, 'paste-buffer')
+    if (pasteErr !== null) return pasteErr
+    // `paste-buffer -d` deletes the buffer on success.
+    loaded = false
+    await sleepMs(Math.round(gap * 1000))
+    const enter = await runTmux(['send-keys', '-t', pane, 'Enter'])
+    const enterErr = tmuxOk(enter, 'send-keys Enter')
+    if (enterErr !== null) return enterErr
+  } finally {
+    // Mirror `tm`'s RETURN trap: a `paste-buffer` that failed after
+    // `load-buffer` succeeded would otherwise leak a named buffer entry.
+    if (loaded) {
+      try {
+        await runTmux(['delete-buffer', '-b', buf])
+      } catch {
+        // Best effort — `tm` swallows this too (`2>/dev/null || true`).
+      }
+    }
+  }
+  return { code: 0, stdout: '', stderr }
+}

package/src/engines/claude/last.ts

@@ -0,0 +1,52 @@
+/**
+ * Claude-engine `tm last` body — reprint a teammate's last-turn reply.
+ *
+ * The verb resolves the teammate's sid via the on-disk marker, then
+ * returns the verbatim content of `<sid>.last`. Two empty states are
+ * both "no reply yet": the file missing, or present but zero bytes.
+ *
+ * Returns a structured result so `ClaudeEngine.last` can pass it through
+ * unchanged and the verb-layer formatter renders the right
+ * `TmResult`. The `message` field carries the bare diagnostic text
+ * without a `tm:` prefix — the formatter adds that.
+ */
+
+import { readFileSync, statSync } from 'node:fs'
+
+import { lastFileFor, sidFile } from '../../persistence/paths'
+import { readSid } from './state'
+import type { TeammateName, TextResult } from '../types'
+
+/** Read a file only if it exists and is non-empty (`tm`'s `[[ -s file ]]`). */
+function readIfNonEmpty(file: string): string | null {
+  try {
+    if (statSync(file).size === 0) return null
+    return readFileSync(file, 'utf8')
+  } catch {
+    return null
+  }
+}
+
+export function claudeLast(name: TeammateName): TextResult {
+  const sid = readSid(name)
+  if (sid === null) {
+    return {
+      kind: 'failed',
+      message:
+        `no sid file for ${name} at ${sidFile(name)} — was this teammate ` +
+        "spawned via 'tm spawn'? (raw 'tmux new-session' won't seed the sid)",
+    }
+  }
+  const file = lastFileFor(sid)
+  const reply = readIfNonEmpty(file)
+  if (reply === null) {
+    return {
+      kind: 'failed',
+      message:
+        `no reply yet for ${name} (sid=${sid}) — file is missing or empty at ` +
+        `${file}. Try 'tm wait ${name}' to block for the next Stop, or ` +
+        `'tm send ${name} --prompt "..."' to drive a turn.`,
+    }
+  }
+  return { kind: 'text', text: reply }
+}

package/src/engines/claude/mem.ts

@@ -0,0 +1,124 @@
+/**
+ * Claude-engine `tm mem` body — print a teammate's Claude Code
+ * project memory index (`MEMORY.md` under
+ * `~/.claude/projects/<dir>/memory/`).
+ *
+ * Schema 2 lookup: the AutoMemory directory is shared across a repo
+ * and its `.claude/worktrees/<slug>` children — Claude Code keys it
+ * by the **parent repo path**, not the runtime cwd. The verb resolves
+ * `identity.repo` (the recorded source repo) and encodes that path,
+ * so a teammate launched inside a worktree still surfaces the
+ * sibling repo's memory.
+ *
+ * Three outcomes carry into the verb-layer formatter:
+ *
+ *  - `kind: 'text'` — file present (possibly empty); content verbatim.
+ *  - `kind: 'not-supported'` — file absent; the formatter renders the
+ *    diagnostic on stderr with exit 0.
+ *  - `kind: 'failed'` — the teammate has no identity record (kill +
+ *    respawn migration message) or the recorded repo path is gone.
+ */
+
+import { readFileSync, realpathSync, statSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+import { encodeProjectDir } from '../../persistence/paths'
+import { read as readIdentity } from '../../persistence/identity-store'
+import type { TeammateName, TextResult } from '../types'
+
+/** Whether a path exists and is a regular file. */
+export function isRegularFile(path: string): boolean {
+  try {
+    return statSync(path).isFile()
+  } catch {
+    return false
+  }
+}
+
+/** Whether a path exists and is a directory. */
+export function isDirectory(path: string): boolean {
+  try {
+    return statSync(path).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+export interface ClaudeMemEnv {
+  readonly dispatcherDir: string
+  readonly projectsDir: string
+}
+
+/**
+ * The `~/.claude/projects/<dir>` directory for a teammate. Resolved
+ * from `identity.repo` (not `identity.cwd`) — worktrees share their
+ * parent repo's AutoMemory.
+ */
+export function projectDirForName(name: TeammateName, env: ClaudeMemEnv): string | null {
+  const identity = readIdentity(name)
+  const target = identity === null ? join(env.dispatcherDir, name) : identity.repo
+  if (!isDirectory(target)) return null
+  const phys = realpathSync(target)
+  return join(env.projectsDir, encodeProjectDir(phys))
+}
+
+/**
+ * The "repo not under dispatcher dir" diagnostic, byte-identical to
+ * the legacy `dieRepoNotFound`. Two branches: dispatcher dir itself
+ * is a git working tree (steer the user to `cd ..`), or the generic
+ * miss (instruction to set `TM_DISPATCHER_DIR`).
+ */
+export function repoNotFoundMessage(
+  verb: string,
+  name: TeammateName,
+  expected: string,
+  dispatcherDir: string,
+): string {
+  if (isDirectory(join(dispatcherDir, '.git'))) {
+    return (
+      `${dispatcherDir} looks like a git working tree (.git exists), not a dispatcher root.\n` +
+      '    The dispatcher dir should be the PARENT of your sibling repos.\n' +
+      `    Try:  cd "${dirname(dispatcherDir)}" && tm ${verb} ${name}\n` +
+      "    (Or set TM_DISPATCHER_DIR in your dispatcher's .claude/settings.json\n" +
+      '    — run /claudemux:setup to wire it up automatically.)'
+    )
+  }
+  return (
+    `repo not found at ${expected} — the teammate's identity record points at ` +
+    `a directory that no longer exists. Re-spawn with 'tm spawn <path> --name ${name}' ` +
+    `(or fix the path) to recover.`
+  )
+}
+
+export function claudeMem(name: TeammateName, env: ClaudeMemEnv): TextResult {
+  const identity = readIdentity(name)
+  if (identity === null) {
+    return {
+      kind: 'failed',
+      message:
+        `tm mem: no identity record for '${name}'. Spawn it with ` +
+        `'tm spawn <path> --name ${name}' first, or check 'tm ls'.`,
+    }
+  }
+  if (!isDirectory(identity.repo)) {
+    return {
+      kind: 'failed',
+      message: repoNotFoundMessage('mem', name, identity.repo, env.dispatcherDir),
+    }
+  }
+  const projectDir = projectDirForName(name, env)
+  if (projectDir === null) {
+    return {
+      kind: 'failed',
+      message: repoNotFoundMessage('mem', name, identity.repo, env.dispatcherDir),
+    }
+  }
+  const mfile = join(projectDir, 'memory', 'MEMORY.md')
+  if (!isRegularFile(mfile)) {
+    return {
+      kind: 'not-supported',
+      reason: `tm mem: no auto-memory recorded for ${name} (looked at ${mfile})`,
+    }
+  }
+  return { kind: 'text', text: readFileSync(mfile, 'utf8') }
+}

package/src/engines/claude/persistence.ts

@@ -0,0 +1,41 @@
+/**
+ * ClaudeTeammateRecord.
+ *
+ * The base `/tmp/teammate-<name>.json` is owned by
+ * `persistence/identity-store.ts`; the Claude extension path builders and
+ * tmux session-name encoding live in `persistence/paths.ts`.
+ */
+
+import { TeammateRecord } from '../teammate-record'
+import type { EngineKind, TeammateName } from '../types'
+import { claudeExtensionFor, tmuxSessionName, type ClaudeTeammateExtension } from '../../persistence/paths'
+
+export class ClaudeTeammateRecord extends TeammateRecord {
+  readonly engine: EngineKind = 'claude'
+
+  constructor(args: {
+    name: TeammateName
+    repo: string
+    cwd: string
+    worktreeSlug: string | null
+    createdAt: number
+    displayName: string | null
+  }) {
+    super(args)
+  }
+
+  /** The tmux session name this teammate is launched as. */
+  tmuxSession(): string {
+    return tmuxSessionName(this.name)
+  }
+
+  /** The Claude-engine extension paths for this teammate. */
+  extension(): ClaudeTeammateExtension {
+    return claudeExtensionFor(this.name)
+  }
+
+  override engineExtensionFiles(): readonly string[] {
+    const ext = this.extension()
+    return [ext.cwd, ext.sid, ext.ready, ext.sendAt]
+  }
+}

package/src/engines/claude/post-turn.ts

@@ -0,0 +1,45 @@
+/**
+ * Post-turn output helpers — what `tm send` and `tm wait` print after a
+ * Stop fires (or a timeout decides). The reply text goes to stdout via
+ * `printLastOrEmpty`; the post-turn ctx echo goes to stderr via
+ * `echoCtxToStderr`. Centralised so the two verbs render identically.
+ */
+
+import { readIfNonEmpty, resolveSid } from './idle'
+import { lastFileFor } from '../../persistence/paths'
+import { claudeCtxLine } from './ctx'
+import type { ClaudeCtxEnv } from './ctx'
+import type { TeammateName } from '../types'
+
+/**
+ * `tm`'s `_print_last_or_empty`: the teammate's `<sid>.last` content,
+ * or the documented sentinel line when the file is missing or zero
+ * bytes. Always exit 0; the verb wrapper decides what code to ship.
+ */
+export function printLastOrEmpty(name: TeammateName): string {
+  const sid = resolveSid(name)
+  if (sid === null) return `(no sid for ${name})\n`
+  const reply = readIfNonEmpty(lastFileFor(sid))
+  if (reply === null) {
+    return '(no text reply this turn — tool-only, /compact, /clear, or fresh spawn)\n'
+  }
+  // `cat` does not append a newline; the file's own trailing newline is
+  // what shapes the printed line. Reproduce that verbatim.
+  return reply
+}
+
+/**
+ * `tm`'s `_echo_ctx_to_stderr`: the teammate's post-turn ctx line,
+ * prefixed with `ctx: `, on stderr. Soft-fails: an unreadable transcript
+ * or a sid that cannot be resolved drops the line silently.
+ */
+export function echoCtxToStderr(name: TeammateName, env: ClaudeCtxEnv): string {
+  // Reuse `claudeCtxLine` — its `?` diagnostic shape would also be a
+  // soft-fail, so any `name:` prefix indicates an unreadable transcript;
+  // only the formatted success line is echoed (the part after `<name>: `).
+  const body = claudeCtxLine(name, '', env)
+  if (body.includes(': ? (')) return ''
+  const prefix = `${name}: `
+  const data = body.startsWith(prefix) ? body.slice(prefix.length) : body
+  return `ctx: ${data}\n`
+}

package/src/engines/claude/reload.ts

@@ -0,0 +1,53 @@
+/**
+ * `tm reload` — fan `/reload-plugins` out to one, many, or all
+ * teammates.
+ *
+ * Fire-and-forget per teammate: each `/reload-plugins` is pushed into
+ * the pane via `sendKeys` directly, without waiting for the Stop hook
+ * (the user only cares that the slash command was queued; the
+ * underlying claude session takes seconds to reload its plugin set,
+ * and a 1-by-1 wait would serialize a 10-teammate fleet for minutes).
+ *
+ * `cmd_reload`'s `(failed — ...)` line and keep-iterating `rc` are
+ * dead code in bash: `_send_keys` `die`s (`exit 1`) for a non-running
+ * teammate rather than returning non-zero, which terminates `tm
+ * reload` outright. This reproduces what `tm reload` *does* — stop at
+ * the first send that exits non-zero, and propagate that exit code —
+ * not the unreachable intent.
+ */
+
+import { sendKeys } from './keys'
+import { die, iterTeammates } from './tmux'
+import type { ClaudeVerbEnv } from './env'
+import type { TmResult } from '../../tm'
+
+export async function claudeReload(args: readonly string[], env: ClaudeVerbEnv): Promise<TmResult> {
+  let all = false
+  const names: string[] = []
+  for (const arg of args) {
+    if (arg === '--all') all = true
+    else if (arg === '-h' || arg === '--help') return die('usage: tm reload <name>... | --all')
+    else if (arg.startsWith('-')) return die(`tm reload: unknown flag: ${arg}`)
+    else names.push(arg)
+  }
+
+  if (all) {
+    if (names.length > 0) return die('tm reload: --all conflicts with explicit names')
+    names.push(...(await iterTeammates(env.runTmux)))
+    if (names.length === 0) {
+      return { code: 0, stdout: '(no teammate sessions to reload)\n', stderr: '' }
+    }
+  } else if (names.length === 0) {
+    return die('usage: tm reload <name>... | --all')
+  }
+
+  let stdout = ''
+  for (const name of names) {
+    stdout += `→ ${name}: /reload-plugins\n`
+    const sent = await sendKeys(name, '/reload-plugins', env.runTmux, process.env)
+    // A non-zero `sendKeys` is the `die` that ends `tm reload`; its
+    // own stderr went to `cmd_reload`'s `>/dev/null`, so it is dropped.
+    if (sent.code !== 0) return { code: sent.code, stdout, stderr: '' }
+  }
+  return { code: 0, stdout, stderr: '' }
+}

package/src/engines/claude/repo-fs.ts

@@ -0,0 +1,63 @@
+/**
+ * Repo-resolution helpers — the dispatcher-tree → physical-path →
+ * `~/.claude/projects/<dir>` mapping `tm history`, `tm mem`, and
+ * `tm resume` all reach for.
+ */
+
+import { realpathSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+import { encodeProjectDir } from '../../persistence/paths'
+import { isDirectory } from './idle'
+import { die } from './tmux'
+import type { TeammateName } from '../types'
+import type { TmResult } from '../../tm'
+
+export interface RepoFsEnv {
+  readonly dispatcherDir: string
+  readonly projectsDir: string
+}
+
+/**
+ * The Claude Code project directory for a teammate, keyed on its
+ * runtime cwd. The cwd's *physical* path (symlinks resolved, as
+ * `cd && pwd -P` does) is encoded — Claude Code writes transcripts
+ * under that exact encoding. Worktree teammates therefore land at
+ * `~/.claude/projects/<repo-with-worktree-suffix>/`; `--no-worktree`
+ * teammates land at the repo's bare encoded path.
+ *
+ * The caller must have already confirmed `cwd` exists —
+ * `realpathSync` needs a real path.
+ */
+export function projectDirForCwd(cwd: string, env: RepoFsEnv): string {
+  const phys = realpathSync(cwd)
+  return join(env.projectsDir, encodeProjectDir(phys))
+}
+
+/**
+ * `tm`'s `die_repo_not_found`. Two branches: dispatcher dir itself is
+ * a git working tree (steer the user to `cd ..`), or the generic miss
+ * (instruction to set `TM_DISPATCHER_DIR`).
+ */
+export function dieRepoNotFound(
+  verb: string,
+  name: TeammateName,
+  expected: string,
+  dispatcherDir: string,
+): TmResult {
+  if (isDirectory(join(dispatcherDir, '.git'))) {
+    return die(
+      `${dispatcherDir} looks like a git working tree (.git exists), not a dispatcher root.\n` +
+        '    The dispatcher dir should be the PARENT of your sibling repos.\n' +
+        `    Try:  cd "${dirname(dispatcherDir)}" && tm ${verb} ${name}\n` +
+        "    (Or set TM_DISPATCHER_DIR in your dispatcher's .claude/settings.json\n" +
+        '    — run /claudemux:setup to wire it up automatically.)',
+    )
+  }
+  return die(
+    `repo not found at ${expected} — <repo> must be a direct subdirectory of the ` +
+      `dispatcher dir (${dispatcherDir}). Dispatcher dir is read from ` +
+      "TM_DISPATCHER_DIR (env) or $PWD; if it's wrong, set TM_DISPATCHER_DIR or " +
+      'run tm from the right place.',
+  )
+}

package/src/engines/claude/resume.ts

@@ -0,0 +1,145 @@
+/**
+ * `tm resume` (Claude) — relaunch a prior conversation. With no sid
+ * the verb delegates session choice to the Claude CLI's native
+ * `--continue`. With a sid it proves the transcript exists at the
+ * recorded cwd's project-dir, then delegates to `spawn --resume`.
+ *
+ * Schema 2 changes:
+ *  - The repo / worktree / cwd are passed in explicitly from the
+ *    engine-router argv (`--repo`, `--cwd`, `--worktree-slug`); the
+ *    legacy `<repo> sid` two-positional form is gone.
+ *  - The teammate identity is the flat `<name>` (not a repo path);
+ *    the tmux-session existence guard reads off `tmuxSessionName(name)`.
+ */
+
+import { join } from 'node:path'
+
+import { claudeContinue, claudeSpawn } from './spawn'
+import { isRegularFile } from './idle'
+import { UUID_RE } from './identifiers'
+import { encodeProjectDir, tmuxSessionName } from '../../persistence/paths'
+import { die, sessionExists } from './tmux'
+import { looksLikeUuidPrefix } from '../../identity/uuid-prefix'
+import type { ClaudeVerbEnv } from './env'
+import type { TmResult } from '../../tm'
+
+interface ParsedClaudeResume {
+  name: string
+  repo: string
+  cwd: string
+  worktreeSlug: string | null
+  displayName: string
+  sid: string
+  prompt: string
+  hasPrompt: boolean
+}
+
+function parseResumeRouterArgs(
+  args: readonly string[],
+): ParsedClaudeResume | { error: TmResult } {
+  const name = args[0] ?? ''
+  if (name.length === 0) return { error: die('claude resume: <name> required') }
+  let repo = ''
+  let cwd = ''
+  let worktreeSlug: string | null = null
+  let displayName = ''
+  let sid = ''
+  let prompt = ''
+  let hasPrompt = false
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i]!
+    const next = (): string | null => {
+      const value = args[i + 1]
+      if (value === undefined) return null
+      i++
+      return value
+    }
+    if (arg === '--repo') {
+      const v = next()
+      if (v === null) return { error: die('claude resume: --repo requires a value') }
+      repo = v
+    } else if (arg === '--cwd') {
+      const v = next()
+      if (v === null) return { error: die('claude resume: --cwd requires a value') }
+      cwd = v
+    } else if (arg === '--worktree-slug') {
+      const v = next()
+      if (v === null) return { error: die('claude resume: --worktree-slug requires a value') }
+      worktreeSlug = v
+    } else if (arg === '--display-name') {
+      const v = next()
+      if (v === null) return { error: die('claude resume: --display-name requires a value') }
+      displayName = v
+    } else if (arg === '--prompt') {
+      const v = next()
+      if (v === null) return { error: die('claude resume: --prompt requires a value') }
+      prompt = v
+      hasPrompt = true
+    } else if (arg.startsWith('-')) {
+      return { error: die(`claude resume: unknown flag: ${arg}`) }
+    } else if (sid === '') {
+      sid = arg
+    } else {
+      return { error: die(`claude resume: unexpected positional '${arg}'`) }
+    }
+  }
+  if (repo.length === 0) return { error: die('claude resume: missing --repo') }
+  if (cwd.length === 0) cwd = repo
+  return { name, repo, cwd, worktreeSlug, displayName, sid, prompt, hasPrompt }
+}
+
+export async function claudeResume(args: readonly string[], env: ClaudeVerbEnv): Promise<TmResult> {
+  const parsed = parseResumeRouterArgs(args)
+  if ('error' in parsed) return parsed.error
+  const { name, repo, cwd, worktreeSlug, displayName, prompt, hasPrompt } = parsed
+  let { sid } = parsed
+
+  const session = tmuxSessionName(name)
+  if (await sessionExists(session, env.runTmux)) {
+    return die(
+      `${name} already running (tmux=${session}) — 'tm kill ${name}' first ` +
+        'if you really want to start over',
+    )
+  }
+
+  const spawnArgs: string[] = [name, '--repo', repo, '--cwd', cwd]
+  if (worktreeSlug !== null) spawnArgs.push('--worktree-slug', worktreeSlug)
+  if (displayName.length > 0) spawnArgs.push('--display-name', displayName)
+  if (hasPrompt) spawnArgs.push('--prompt', prompt)
+
+  if (sid === '') {
+    return claudeContinue(name, spawnArgs.slice(1), env)
+  }
+
+  // The transcript directory Claude uses is keyed by the runtime
+  // cwd (the worktree path when `--worktree-slug` is set). Probe
+  // there for the sid.
+  const projectDir = join(env.projectsDir, encodeProjectDir(cwd))
+  const target = join(projectDir, `${sid}.jsonl`)
+  if (!isRegularFile(target)) {
+    if (looksLikeUuidPrefix(sid)) {
+      return die(
+        `received '${sid}', looks like a sid prefix; resume requires the ` +
+          `full sid. Run 'tm history ${name} ${sid}' to expand it, or ` +
+          `'tm history ${name}' to list past sessions with full ids.`,
+      )
+    }
+    return die(
+      `no transcript at ${target} — wrong name/worktree for this sid, or sid does not ` +
+        `exist. Check 'ls ${projectDir}/'.`,
+    )
+  }
+  if (!UUID_RE.test(sid)) {
+    if (looksLikeUuidPrefix(sid)) {
+      return die(
+        `received '${sid}', looks like a sid prefix; resume requires the ` +
+          `full sid. Run 'tm history ${name} ${sid}' to expand it.`,
+      )
+    }
+    return die(`sid is not a valid uuid: ${sid}`)
+  }
+
+  spawnArgs.splice(1, 0, '--resume', sid)
+  // After splice: [name, --resume, sid, --repo, ..., --cwd, ..., ...]
+  return claudeSpawn(spawnArgs, env)
+}