@excitedjs/tm 1.1.0

package/src/engines/claude/tmux.ts

@@ -0,0 +1,99 @@
+/**
+ * Claude-engine tmux helpers — the session-probe and pane-target lookups
+ * the hot-path verbs share. Decision multi-engine-tui-architecture §"Verb is the abstraction" pins
+ * the session-name encoding to `persistence/paths.ts`; this
+ * module is the thin runtime layer on top of that, so a verb that needs
+ * to ask "is this teammate's tmux session alive?" or "what pane should I
+ * send keys to?" calls one helper instead of repeating the same
+ * `has-session -t '=…'` / `list-sessions -F '#{session_id} #{session_name}'`
+ * argv at every site.
+ */
+
+import { TMUX_SESSION_PREFIX, tmuxSessionName } from '../../persistence/paths'
+import type { TeammateName } from '../types'
+import type { TmResult } from '../../tm'
+import type { TmuxRunner } from '../../tmux'
+
+/** `tm`'s `die`: one `tm: <message>` line on stderr, exit 1. */
+export function die(message: string): TmResult {
+  return { code: 1, stdout: '', stderr: `tm: ${message}\n` }
+}
+
+/** Whether a session of this name is currently up — `has-session -t '=NAME'`. */
+export async function sessionExists(
+  session: string,
+  runTmux: TmuxRunner,
+): Promise<boolean> {
+  try {
+    return (await runTmux(['has-session', '-t', `=${session}`])).code === 0
+  } catch {
+    return false
+  }
+}
+
+/**
+ * `tm`'s `require_session`: a `die` `TmResult` when the teammate's tmux
+ * session does not exist, or `null` when it does. The `=` modifier in
+ * `has-session -t '=NAME'` is tmux's exact-match qualifier — without it
+ * a teammate named `teammate-foo` would also match `teammate-foo-bar`.
+ */
+export async function requireSession(
+  name: TeammateName,
+  runTmux: TmuxRunner,
+): Promise<TmResult | null> {
+  const session = tmuxSessionName(name)
+  if (await sessionExists(session, runTmux)) return null
+  return die(`no such teammate session: ${name} (tmux=${session}; try 'tm ls')`)
+}
+
+/**
+ * `tm`'s `resolve_pane_target`: the tmux internal session id of a
+ * teammate's session, or `''` when none matches. tmux pane targets cannot
+ * take the `=NAME` exact-match modifier, so the id is resolved instead.
+ */
+export async function resolvePaneTarget(
+  name: TeammateName,
+  runTmux: TmuxRunner,
+): Promise<string> {
+  const session = tmuxSessionName(name)
+  let listing = ''
+  try {
+    listing = (await runTmux(['list-sessions', '-F', '#{session_id} #{session_name}'])).stdout
+  } catch {
+    listing = ''
+  }
+  for (const line of listing.split('\n')) {
+    const space = line.indexOf(' ')
+    if (space >= 0 && line.slice(space + 1) === session) return line.slice(0, space)
+  }
+  return ''
+}
+
+/** The session field of one `tmux ls` line — `awk -F:` `$1`. */
+export function sessionField(line: string): string {
+  const colon = line.indexOf(':')
+  return colon >= 0 ? line.slice(0, colon) : line
+}
+
+/** The running teammate names from a `tmux ls` stdout listing. */
+export function teammateNamesFromTmuxLs(listing: string): string[] {
+  const out: string[] = []
+  for (const line of listing.split('\n')) {
+    const field = sessionField(line)
+    if (field.startsWith(TMUX_SESSION_PREFIX)) {
+      out.push(field.slice(TMUX_SESSION_PREFIX.length))
+    }
+  }
+  return out
+}
+
+/** `tm`'s `iter_repos` — the running teammate repo names from a tmux runner. */
+export async function iterTeammates(runTmux: TmuxRunner): Promise<string[]> {
+  let listing = ''
+  try {
+    listing = (await runTmux(['ls'])).stdout
+  } catch {
+    listing = ''
+  }
+  return teammateNamesFromTmuxLs(listing)
+}

package/src/engines/claude/wait-signals.ts

@@ -0,0 +1,128 @@
+/**
+ * `tm`'s `_wait_idle_signal` and `_wait_pane_quiet` — the two block-
+ * until-the-turn-ends primitives `tm send` and `tm wait` compose. The
+ * idle-marker path is the primary signal; pane-quiet is a fallback for
+ * sessions whose Stop hook is not loaded.
+ */
+
+import { existsSync, statSync } from 'node:fs'
+
+import { clearIdle, resolveSidOrDie, resolveSid, isRegularFile } from './idle'
+import { busyMarkerFor, idleMarkerFor, sendAtFile } from '../../persistence/paths'
+import { requireSession } from './tmux'
+import { nowSec, sleepMs } from './clock'
+import type { TeammateName } from '../types'
+import type { TmResult } from '../../tm'
+import type { TmuxRunner } from '../../tmux'
+
+/**
+ * Re-probe a teammate's liveness at the moment a sync wait is about to
+ * declare 124 ("expired, still running"). Two failure modes count as DEAD
+ * here — the dispatcher MUST distinguish "TM dropped during the wait" from
+ * "TM is alive and slow":
+ *
+ *  - The tmux session is gone (manual `tm kill`, crash, terminal closed).
+ *  - The `.sid` file is gone (a fresh `tm spawn` would have rewritten it;
+ *    its absence proves the teammate's bookkeeping was torn down).
+ *
+ * Returns `null` when the teammate looks alive (the caller proceeds to its
+ * 124 path), or a `TmResult` with exit 1 + a death-flavored stderr line
+ * the caller can prepend to its own context. The 124 contract is "still
+ * running, re-collect with `tm wait`"; promising that on a dead teammate
+ * is exactly the bg-classifier failure mode this whole PR exists to fix,
+ * just from the opposite direction — so every wait-expiry path runs this
+ * probe before the 124 branch.
+ */
+export async function probeStillAlive(
+  name: TeammateName,
+  runTmux: TmuxRunner,
+): Promise<TmResult | null> {
+  const sessionMissing = await requireSession(name, runTmux)
+  if (sessionMissing !== null) {
+    return {
+      code: 1,
+      stdout: '',
+      stderr:
+        `tm: teammate '${name}' died during the wait — tmux session is gone. ` +
+        `Respawn with 'tm spawn ${name}' (or 'tm resume') once you have a ` +
+        `target. Original wait-expiry: ` +
+        sessionMissing.stderr.replace(/^tm: /, '').trimEnd() +
+        '\n',
+    }
+  }
+  const sidR = resolveSidOrDie(name)
+  if ('error' in sidR) {
+    return {
+      code: 1,
+      stdout: '',
+      stderr:
+        `tm: teammate '${name}' died during the wait — sid marker disappeared ` +
+        `(typically 'tm kill' run mid-wait). Respawn with 'tm spawn ${name}'. ` +
+        `Original wait-expiry: ` +
+        sidR.error.stderr.replace(/^tm: /, '').trimEnd() +
+        '\n',
+    }
+  }
+  return null
+}
+
+/**
+ * `tm`'s `_wait_idle_signal`: block until `/tmp/claude-idle/<sid>`
+ * exists, or `timeoutSec` elapses. Returns the resolved `TmResult` on
+ * early-out (no-such-session / no-sid), or `{ ok }` once the loop has
+ * its verdict.
+ */
+export async function waitIdleSignal(
+  name: TeammateName,
+  timeoutSec: number,
+  fresh: boolean,
+  runTmux: TmuxRunner,
+): Promise<TmResult | { ok: boolean }> {
+  const sessionMissing = await requireSession(name, runTmux)
+  if (sessionMissing !== null) return sessionMissing
+  const sidR = resolveSidOrDie(name)
+  if ('error' in sidR) return sidR.error
+  if (fresh) clearIdle(sidR.sid)
+
+  const end = nowSec() + timeoutSec
+  const marker = idleMarkerFor(sidR.sid)
+  while (nowSec() < end) {
+    if (existsSync(marker)) return { ok: true }
+    await sleepMs(3000)
+  }
+  return { ok: false }
+}
+
+/**
+ * `tm`'s `_wait_pane_quiet`: block until the teammate's pane has shown
+ * no busy marker for ~4s AND at least 3s have passed since the last
+ * send. Returns the resolved `TmResult` on early-out or `{ ok }` once
+ * decided.
+ */
+export async function waitPaneQuiet(
+  name: TeammateName,
+  timeoutSec: number,
+  runTmux: TmuxRunner,
+): Promise<TmResult | { ok: boolean }> {
+  const sessionMissing = await requireSession(name, runTmux)
+  if (sessionMissing !== null) return sessionMissing
+
+  let sendAt = 0
+  try {
+    sendAt = Math.floor(statSync(sendAtFile(name)).mtimeMs / 1000)
+  } catch {
+    sendAt = 0
+  }
+
+  const end = nowSec() + timeoutSec
+  let quietStreak = 0
+  while (nowSec() < end) {
+    const sid = resolveSid(name)
+    const isBusy = sid !== null && isRegularFile(busyMarkerFor(sid))
+    if (isBusy) quietStreak = 0
+    else quietStreak += 1
+    if (quietStreak >= 2 && nowSec() - sendAt >= 3) return { ok: true }
+    await sleepMs(2000)
+  }
+  return { ok: false }
+}

package/src/engines/claude/wait.ts

@@ -0,0 +1,59 @@
+/**
+ * `tm wait` — block on the Stop-hook idle marker (default) or pane-
+ * quiet fallback, then print the teammate's reply. Same output contract
+ * as `tm send`. `--fresh` clears the baseline up front so it is the
+ * *next* Stop that wakes the wait, not a prior one.
+ */
+
+import { probeStillAlive, waitIdleSignal, waitPaneQuiet } from './wait-signals'
+import { echoCtxToStderr, printLastOrEmpty } from './post-turn'
+import { die } from './tmux'
+import { isNonNegativeInteger } from './clock'
+import { parseWaitArgs } from '../../shared/verb-args'
+import type { ClaudeVerbEnv } from './env'
+import { EXIT_SYNC_WAIT_EXPIRED, type TmResult } from '../../tm'
+
+export async function claudeWait(args: readonly string[], env: ClaudeVerbEnv): Promise<TmResult> {
+  const parsed = parseWaitArgs(args)
+  if ('error' in parsed) return parsed.error
+  const { name, timeout, fresh, paneQuiet } = parsed
+  if (name === '') {
+    return die(
+      'usage: tm wait <name> [timeout=1800] [--fresh] [--pane-quiet] [--timeout N]',
+    )
+  }
+  if (timeout !== null && !isNonNegativeInteger(timeout)) {
+    return die(`tm wait: --timeout must be a non-negative integer (got: '${timeout}')`)
+  }
+
+  const timeoutSec = timeout === null ? 1800 : Number(timeout)
+  const verdict = paneQuiet
+    ? await waitPaneQuiet(name, timeoutSec, env.runTmux)
+    : await waitIdleSignal(name, timeoutSec, fresh, env.runTmux)
+  if ('code' in verdict) return verdict
+  if (!verdict.ok) {
+    // See `send.ts` for the rationale — re-probe before promising "still
+    // running" (124) so a teammate that died mid-wait surfaces as a real
+    // failure (exit 1) instead of being kept on the dispatcher's "keep
+    // tailing" list forever.
+    const dead = await probeStillAlive(name, env.runTmux)
+    if (dead !== null) return dead
+    const kind = paneQuiet ? 'pane-quiet' : 'Stop hook'
+    return {
+      code: EXIT_SYNC_WAIT_EXPIRED,
+      stdout: printLastOrEmpty(name),
+      stderr:
+        `tm wait: sync wait expired after ${timeoutSec}s on ${name} ` +
+        `(no ${kind} fired; the teammate is still running — re-run ` +
+        `'tm wait ${name}' or check 'tm status ${name}'). exit ${EXIT_SYNC_WAIT_EXPIRED}.\n`,
+    }
+  }
+
+  let trailingStderr = ''
+  if (!paneQuiet) trailingStderr = echoCtxToStderr(name, env)
+  return {
+    code: 0,
+    stdout: printLastOrEmpty(name),
+    stderr: trailingStderr,
+  }
+}

package/src/engines/codex/ask.ts

@@ -0,0 +1,69 @@
+import type { ThreadStartResponse } from '../../codex-protocol/v2/ThreadStartResponse.js'
+import type { TmResult } from '../../tm'
+import { openInitializedCodexClient } from './engine.js'
+import { runTurn } from './events.js'
+import {
+  daemonAlive,
+  listDaemons,
+  releaseDaemonBorrow,
+  touchLastSeen,
+  tryBorrowDaemon,
+} from './supervisor.js'
+import { die } from './verb-common.js'
+
+/**
+ * `tm ask "<prompt>"` — borrow one live codex teammate from the pool, run an
+ * ephemeral thread, and release the teammate.
+ */
+export async function codexAsk(prompt: string): Promise<TmResult> {
+  if (prompt.length === 0) return die('usage: tm ask "<prompt>"')
+
+  const candidates = listDaemons()
+  if (candidates.length === 0) {
+    return die("no codex teammates available — run 'tm spawn <name> --engine codex' first")
+  }
+
+  let borrowed: string | null = null
+  let aliveCount = 0
+  for (const name of candidates) {
+    if (!daemonAlive(name)) continue
+    aliveCount += 1
+    if (tryBorrowDaemon(name)) {
+      borrowed = name
+      break
+    }
+  }
+
+  if (borrowed === null) {
+    if (aliveCount === 0) {
+      return die(`all ${candidates.length} codex teammate(s) are dead — 'tm doctor' will reap them`)
+    }
+    return die(`all ${aliveCount} alive codex teammate(s) are busy — retry, or spawn another`)
+  }
+
+  const borrowedName = borrowed
+  let client: Awaited<ReturnType<typeof openInitializedCodexClient>> | null = null
+  try {
+    client = await openInitializedCodexClient(borrowedName)
+    const resp = await client.request<'thread/start', ThreadStartResponse>('thread/start', {
+      ephemeral: true,
+      experimentalRawEvents: false,
+      persistExtendedHistory: false,
+    })
+    const outcome = await runTurn(client, resp.thread.id, prompt, { wait: true, cwd: null })
+    if (outcome === null) return die(`codex ask on '${borrowedName}' did not return a turn`)
+    touchLastSeen(borrowedName)
+    return {
+      code: 0,
+      stdout: JSON.stringify(outcome.completed, null, 2) + '\n',
+      stderr: '',
+    }
+  } catch (e) {
+    return die(
+      `codex ask on '${borrowedName}' failed: ${e instanceof Error ? e.message : String(e)}`,
+    )
+  } finally {
+    if (client !== null) client.close()
+    releaseDaemonBorrow(borrowedName)
+  }
+}