@excitedjs/tm 1.1.0

package/src/proc.ts

@@ -0,0 +1,66 @@
+/**
+ * The process spawn primitive.
+ *
+ * Every shell-out backend — `tm.ts`, `tmux.ts`, `column.ts`, `grep.ts` —
+ * spawns a child, optionally feeds it stdin, and captures its exit code,
+ * stdout, and stderr in full. `spawnCapture` is that one primitive, over Node's
+ * `child_process`. Output is collected with no size cap, so a large pane
+ * capture or `tm history` listing is never truncated.
+ */
+
+import { spawn } from 'node:child_process'
+
+/** A child process's faithful exit-code + stream capture. */
+export interface ProcResult {
+  /** Process exit code; `1` when the process was terminated by a signal. */
+  code: number
+  /** Captured standard output. */
+  stdout: string
+  /** Captured standard error. */
+  stderr: string
+}
+
+/**
+ * Spawn `argv[0]` with the rest as its arguments, optionally feeding `stdin`,
+ * and resolve with its exit code and captured streams. `env` and `cwd`
+ * override the inherited process environment and working directory. Rejects
+ * if the child fails to spawn (a missing or non-executable binary); a
+ * non-zero exit is a resolved result, since `tm` verbs exit non-zero as
+ * ordinary behavior.
+ */
+export function spawnCapture(
+  argv: readonly string[],
+  options?: { stdin?: string; env?: NodeJS.ProcessEnv; cwd?: string },
+): Promise<ProcResult> {
+  return new Promise((resolve, reject) => {
+    const [command, ...args] = argv
+    if (command === undefined) {
+      reject(new Error('spawnCapture: empty argument vector'))
+      return
+    }
+    const child = spawn(command, args, {
+      // `pipe` on all three streams, so `child.stdin/stdout/stderr` are the
+      // non-null streams the capture below relies on.
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: options?.env ?? process.env,
+      cwd: options?.cwd,
+    })
+    const stdout: Buffer[] = []
+    const stderr: Buffer[] = []
+    child.stdout!.on('data', (chunk: Buffer) => stdout.push(chunk))
+    child.stderr!.on('data', (chunk: Buffer) => stderr.push(chunk))
+    child.on('error', reject)
+    child.on('close', (code) => {
+      resolve({
+        code: code ?? 1,
+        stdout: Buffer.concat(stdout).toString('utf8'),
+        stderr: Buffer.concat(stderr).toString('utf8'),
+      })
+    })
+    // The child may exit before consuming all of stdin (`grep -q` stops at the
+    // first match); the resulting broken-pipe write error is expected — the
+    // exit code and captured output are what matter — so swallow it.
+    child.stdin!.on('error', () => {})
+    child.stdin!.end(options?.stdin ?? '')
+  })
+}

package/src/shared/verb-args.ts

@@ -0,0 +1,331 @@
+/**
+ * Shared CLI argument parsers for teammate verbs.
+ *
+ * These parsers sit outside any concrete engine because `tm spawn` and
+ * `tm resume` carry cross-engine flags (`--engine`) even when the eventual
+ * request is routed to Claude or Codex. Keeping them here prevents the CLI
+ * layer from importing parser helpers out of `engines/claude/`.
+ */
+
+import type { TmResult } from '../tm'
+
+type EngineFlag = 'claude' | 'codex'
+
+function die(message: string): TmResult {
+  return { code: 1, stdout: '', stderr: `tm: ${message}\n` }
+}
+
+/** Parsed arg vector for `tm compact`. */
+export interface CompactArgs {
+  name: string
+  timeout: string
+}
+
+/** Parsed arg vector for `tm resume`. */
+export interface ResumeArgs {
+  name: string
+  sid: string
+  prompt: string
+  hasPrompt: boolean
+  engine: EngineFlag | null
+}
+
+/** Parsed arg vector for `tm send`. */
+export interface SendArgs {
+  name: string
+  prompt: string
+  hasPrompt: boolean
+  paneQuiet: boolean
+  timeout: string | null
+}
+
+/** Parsed arg vector for `tm spawn`. */
+export interface SpawnArgs {
+  engine: EngineFlag | null
+  /** Explicit teammate name from `--name`; empty when the caller wants auto-gen. */
+  name: string
+  resumeSid: string
+  prompt: string
+  hasPrompt: boolean
+  timeout: string | null
+  noWorktree: boolean
+}
+
+/** Parsed arg vector for `tm wait`. */
+export interface WaitArgs {
+  name: string
+  timeout: string | null
+  fresh: boolean
+  paneQuiet: boolean
+}
+
+/**
+ * `tm compact`'s arg loop: same positional-then-flag rule as `wait`.
+ * `--timeout` with no value is the bash silent-exit-1 case; mirror it.
+ */
+export function parseCompactArgs(args: readonly string[]): CompactArgs | { error: TmResult } {
+  const SILENT: TmResult = { code: 1, stdout: '', stderr: '' }
+  let name = ''
+  let timeout = '1800'
+  let i = 0
+  while (i < args.length) {
+    const arg = args[i]!
+    if (arg === '--timeout') {
+      if (i + 1 >= args.length) return { error: SILENT }
+      timeout = args[i + 1]!
+      i += 2
+    } else if (arg.startsWith('--timeout=')) {
+      timeout = arg.slice('--timeout='.length)
+      i++
+    } else if (arg.startsWith('-')) {
+      return { error: die(`tm compact: unknown flag: ${arg}`) }
+    } else if (name === '') {
+      name = arg
+      i++
+    } else {
+      timeout = arg
+      i++
+    }
+  }
+  return { name, timeout }
+}
+
+/**
+ * `tm resume`'s arg loop; two positionals (`<name> [<sid>]`) plus
+ * flags. `--prompt` and `--engine` carry required values; missing
+ * values surface as explicit errors.
+ */
+export function parseResumeArgs(args: readonly string[]): ResumeArgs | { error: TmResult } {
+  let name = ''
+  let sid = ''
+  let prompt = ''
+  let hasPrompt = false
+  let engine: EngineFlag | null = null
+  let i = 0
+  while (i < args.length) {
+    const arg = args[i]!
+    if (arg === '--prompt') {
+      if (i + 1 >= args.length) return { error: die('tm resume: --prompt requires a value') }
+      prompt = args[i + 1]!
+      hasPrompt = true
+      i += 2
+    } else if (arg.startsWith('--prompt=')) {
+      prompt = arg.slice('--prompt='.length)
+      hasPrompt = true
+      i++
+    } else if (arg === '--engine') {
+      if (i + 1 >= args.length) return { error: die('tm resume: --engine requires a value') }
+      const value = args[i + 1]!
+      if (value !== 'claude' && value !== 'codex') {
+        return { error: die(`tm resume: --engine must be 'claude' or 'codex' (got: '${value}')`) }
+      }
+      engine = value
+      i += 2
+    } else if (arg.startsWith('--engine=')) {
+      const value = arg.slice('--engine='.length)
+      if (value !== 'claude' && value !== 'codex') {
+        return { error: die(`tm resume: --engine must be 'claude' or 'codex' (got: '${value}')`) }
+      }
+      engine = value
+      i++
+    } else if (arg === '--') {
+      i++
+      break
+    } else if (arg.startsWith('-')) {
+      return { error: die(`unknown flag: ${arg}`) }
+    } else if (name === '') {
+      name = arg
+      i++
+    } else if (sid === '') {
+      sid = arg
+      i++
+    } else {
+      return {
+        error: die(
+          `tm resume: too many positional args (got '${arg}' after ` +
+            `name='${name}' sid='${sid}')`,
+        ),
+      }
+    }
+  }
+  return { name, sid, prompt, hasPrompt, engine }
+}
+
+/**
+ * Single-quote-escape a string for safe embedding in a bash command
+ * line — used by the legacy-form error suggestion below.
+ */
+function shellSingleQuote(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`
+}
+
+/**
+ * `tm send`'s arg loop. Catches the legacy `tm send <name> <free
+ * text>` form with a dedicated error — pre-0.3.0 callers passed
+ * prompts as positional args, and this catches that habit explicitly
+ * rather than swallowing the trailing positionals as a confusing
+ * "unknown arg".
+ */
+export function parseSendArgs(args: readonly string[]): SendArgs | { error: TmResult } {
+  let paneQuiet = false
+  let timeout: string | null = null
+  let name = ''
+  let prompt = ''
+  let hasPrompt = false
+  let i = 0
+  while (i < args.length) {
+    const arg = args[i]!
+    if (arg === '--pane-quiet') {
+      paneQuiet = true
+      i++
+    } else if (arg === '--timeout') {
+      if (i + 1 >= args.length) return { error: die('tm send: --timeout requires a value') }
+      timeout = args[i + 1]!
+      i += 2
+    } else if (arg.startsWith('--timeout=')) {
+      timeout = arg.slice('--timeout='.length)
+      i++
+    } else if (arg === '--prompt') {
+      if (i + 1 >= args.length) return { error: die('tm send: --prompt requires a value') }
+      prompt = args[i + 1]!
+      hasPrompt = true
+      i += 2
+    } else if (arg.startsWith('--prompt=')) {
+      prompt = arg.slice('--prompt='.length)
+      hasPrompt = true
+      i++
+    } else if (arg === '--') {
+      i++
+      name = args[i] ?? ''
+      i++
+      break
+    } else if (arg.startsWith('-')) {
+      return { error: die(`tm send: unknown flag: ${arg}`) }
+    } else if (name === '') {
+      name = arg
+      i++
+    } else {
+      const tail = args.slice(i).join(' ')
+      return {
+        error: die(
+          'tm send: prompt is now a --prompt flag, not a positional arg. ' +
+            `Did you mean: tm send ${name} --prompt ${shellSingleQuote(tail)} ?`,
+        ),
+      }
+    }
+  }
+  return { name, prompt, hasPrompt, paneQuiet, timeout }
+}
+
+/**
+ * `tm spawn`'s arg loop. `--prompt` and `--name` carry required
+ * values; `--resume <sid>` and `--timeout` accept either a separate
+ * value or `--flag=value` form. `--no-worktree` is a boolean.
+ *
+ * `--task` was removed in the schema-2 cut — pass `--name` instead.
+ */
+export function parseSpawnArgs(rest: readonly string[]): SpawnArgs | { error: TmResult } {
+  const SILENT: TmResult = { code: 1, stdout: '', stderr: '' }
+  let name = ''
+  let resumeSid = ''
+  let prompt = ''
+  let hasPrompt = false
+  let timeout: string | null = null
+  let engine: EngineFlag | null = null
+  let noWorktree = false
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i]!
+    if (arg === '--resume') {
+      if (i + 1 >= rest.length) return { error: SILENT }
+      resumeSid = rest[i + 1]!
+      i++
+    } else if (arg === '--engine') {
+      if (i + 1 >= rest.length) return { error: die('tm spawn: --engine requires a value') }
+      const value = rest[i + 1]!
+      if (value !== 'claude' && value !== 'codex') {
+        return { error: die(`tm spawn: --engine must be 'claude' or 'codex' (got: '${value}')`) }
+      }
+      engine = value
+      i++
+    } else if (arg.startsWith('--engine=')) {
+      const value = arg.slice('--engine='.length)
+      if (value !== 'claude' && value !== 'codex') {
+        return { error: die(`tm spawn: --engine must be 'claude' or 'codex' (got: '${value}')`) }
+      }
+      engine = value
+    } else if (arg === '--name') {
+      if (i + 1 >= rest.length) return { error: die('tm spawn: --name requires a value') }
+      name = rest[i + 1]!
+      i++
+    } else if (arg.startsWith('--name=')) {
+      name = arg.slice('--name='.length)
+    } else if (arg === '--task' || arg.startsWith('--task=')) {
+      return {
+        error: die(
+          "tm spawn: --task was removed in the name/repo decoupling cut. " +
+            "Pass --name <id> to set an explicit teammate name, or omit it " +
+            'to auto-generate (`<path-leaf>-<rand4>`).',
+        ),
+      }
+    } else if (arg === '--timeout') {
+      if (i + 1 >= rest.length) return { error: die('tm spawn: --timeout requires a value') }
+      timeout = rest[i + 1]!
+      i++
+    } else if (arg.startsWith('--timeout=')) {
+      timeout = arg.slice('--timeout='.length)
+    } else if (arg === '--prompt') {
+      if (i + 1 >= rest.length) return { error: die('tm spawn: --prompt requires a value') }
+      prompt = rest[i + 1]!
+      hasPrompt = true
+      i++
+    } else if (arg.startsWith('--prompt=')) {
+      prompt = arg.slice('--prompt='.length)
+      hasPrompt = true
+    } else if (arg === '--no-worktree') {
+      noWorktree = true
+    } else {
+      return { error: die(`unknown flag: ${arg}`) }
+    }
+  }
+  return { engine, name, resumeSid, prompt, hasPrompt, timeout, noWorktree }
+}
+
+/**
+ * `tm wait`'s arg loop; positional after `<name>` is a positional
+ * timeout. `--timeout` with no value is the bash silent-exit-1 case;
+ * mirror it so the conformance differential stays clean.
+ */
+export function parseWaitArgs(args: readonly string[]): WaitArgs | { error: TmResult } {
+  const SILENT: TmResult = { code: 1, stdout: '', stderr: '' }
+  let name = ''
+  let timeout: string | null = null
+  let fresh = false
+  let paneQuiet = false
+  let i = 0
+  while (i < args.length) {
+    const arg = args[i]!
+    if (arg === '--fresh') {
+      fresh = true
+      i++
+    } else if (arg === '--pane-quiet') {
+      paneQuiet = true
+      i++
+    } else if (arg === '--timeout') {
+      if (i + 1 >= args.length) return { error: SILENT }
+      timeout = args[i + 1]!
+      i += 2
+    } else if (arg.startsWith('--timeout=')) {
+      timeout = arg.slice('--timeout='.length)
+      i++
+    } else if (arg.startsWith('-')) {
+      return { error: die(`tm wait: unknown flag: ${arg}`) }
+    } else if (name === '') {
+      name = arg
+      i++
+    } else {
+      timeout = arg
+      i++
+    }
+  }
+  return { name, timeout, fresh, paneQuiet }
+}

package/src/tm.ts

@@ -0,0 +1,54 @@
+/**
+ * The `TmResult` shape — what every `tm` verb returns — and `resolveTmBinary`,
+ * which locates the user-installed `tm` PATH entry.
+ *
+ * Stage 3c retired the Bash `bin/tm`; the orchestrator is now a pure Node CLI
+ * and no verb shells out to `tm`. The runtime shell-out functions that used to
+ * live here (`runTm` / `runTmRaw`) are gone with it.
+ *
+ * Two seams remain useful and keep their home in this module:
+ *
+ *  - `TmResult` — the call shape every verb produces. Module-public so the
+ *    CLI front end and the conformance harness see the same contract.
+ *  - `resolveTmBinary` — used by the live-teammate integration harness to
+ *    locate the PATH entry it drives. It honors `CLAUDEMUX_TM`, so the same
+ *    harness can be re-aimed at any custom `tm` binary without code change.
+ */
+
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/** The outcome of one `tm` verb: a faithful exit-code + stream capture. */
+export interface TmResult {
+  /** Process exit code. */
+  code: number
+  /** Captured standard output. */
+  stdout: string
+  /** Captured standard error. */
+  stderr: string
+}
+
+/**
+ * Exit code for "sync wait expired but the teammate is still running" —
+ * the verb wanted a reply within `--timeout`, the timer elapsed, but the
+ * underlying teammate (Claude REPL, codex daemon) was not declared dead.
+ *
+ * The value (124) is the GNU `timeout(1)` convention: callers that already
+ * branch on `124` for `timeout` behave the same on `tm`. The dispatcher's
+ * bg-task wrapper uses it to distinguish "TM is gone, retry from spawn"
+ * (exit 1) from "TM is still working, keep watching with `tm wait`" (exit
+ * 124). Exit 0 still means "got the reply within the window".
+ */
+export const EXIT_SYNC_WAIT_EXPIRED = 124
+
+/**
+ * Resolve the `tm` executable. `CLAUDEMUX_TM` overrides it (the live-teammate
+ * suite points it at any custom launcher this way); otherwise it is the
+ * `bin/tm` shipped alongside this core in the claudemux plugin.
+ */
+export function resolveTmBinary(): string {
+  const override = process.env.CLAUDEMUX_TM
+  if (override && override.length > 0) return override
+  // src/tm.ts → plugins/claudemux/bin/tm
+  return join(dirname(fileURLToPath(import.meta.url)), '..', 'bin', 'tm')
+}

package/src/tmux.ts

@@ -0,0 +1,57 @@
+/**
+ * The `tmux` shell-out layer.
+ *
+ * Phase B of the strangler migration (`.agents/domains/mcp-native-orchestrator.md`
+ * §12) reimplements `tm` verbs in native core code instead of shelling out to
+ * `tm`. Some of those verbs still need tmux itself: migrating `tm ls` means
+ * the core runs `tmux ls` and filters the output in TypeScript — it does not
+ * mean tmux stops being the session backend. This module is that tmux seam,
+ * the counterpart of `tm.ts` for verbs that have left the `tm` shell-out.
+ *
+ * The caller, not this module, decides what a non-zero exit means: `tmux ls`
+ * exits non-zero merely because no server is running, which the `ls` verb
+ * treats as the ordinary "no sessions" case.
+ */
+
+import { spawnCapture } from './proc'
+
+/** The outcome of one `tmux` invocation: a faithful exit-code + stream capture. */
+export interface TmuxResult {
+  /** Process exit code. */
+  code: number
+  /** Captured standard output. */
+  stdout: string
+  /** Captured standard error. */
+  stderr: string
+}
+
+/**
+ * Runs one `tmux` invocation. Injectable: native verbs depend on this type,
+ * not on the concrete function, so a conformance fixture can supply a fake
+ * tmux without touching the verb logic.
+ *
+ * The optional `stdin` is the bytes piped to tmux's standard input — what
+ * `tmux load-buffer -b <name> -` reads to stage a paste buffer.
+ */
+export type TmuxRunner = (
+  args: readonly string[],
+  options?: { stdin?: string },
+) => Promise<TmuxResult>
+
+/**
+ * Resolve the `tmux` executable. `CLAUDEMUX_TMUX` overrides it (the tests
+ * point it at a fake); otherwise it is plain `tmux`, found on `PATH` — the
+ * same way `bin/tm` invokes tmux.
+ */
+export function resolveTmuxBinary(): string {
+  const override = process.env.CLAUDEMUX_TMUX
+  if (override && override.length > 0) return override
+  return 'tmux'
+}
+
+/**
+ * The production `TmuxRunner`: spawn `tmux`, forward the argument vector
+ * verbatim, and capture exit code, stdout, and stderr without interpretation.
+ */
+export const runTmux: TmuxRunner = (args, options) =>
+  spawnCapture([resolveTmuxBinary(), ...args], options)