@excitedjs/tm 1.1.0 → 1.3.2

package/package.json

@@ -1,9 +1,14 @@
 {
   "name": "@excitedjs/tm",
-  "version": "1.1.0",
+  "version": "1.3.2",
   "description": "Multi-repo AI orchestrator CLI — spawn, message, and wait on Claude/Codex teammates across sibling repos.",
   "type": "module",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/excitedjs/claudemux.git",
+    "directory": "plugins/claudemux"
+  },
   "engines": {
     "node": ">=22.7.0"
   },

package/src/cli/dispatch.ts

@@ -88,6 +88,24 @@ async function combineResults(results: readonly Promise<TmResult>[]): Promise<Tm
   return { code, stdout, stderr }
 }
 
+/**
+ * Parse the flag set `tm ls` / `tm states` accept. Both take only the
+ * optional `--all` (also list killed teammates from the kill-time
+ * identity archive); any positional or other flag is a usage error so
+ * a typo'd name does not silently behave like a bare fleet listing.
+ */
+function parseFleetListFlags(
+  verb: 'ls' | 'states',
+  rest: readonly string[],
+): { all: boolean } | { error: TmResult } {
+  let all = false
+  for (const arg of rest) {
+    if (arg === '--all') all = true
+    else return { error: die(`tm ${verb}: unexpected argument '${arg}'. Usage: tm ${verb} [--all]`) }
+  }
+  return { all }
+}
+
 // ─── Engine-routed teammate verbs ─────────────────────────────────────────
 
 const ENGINE_VERBS: ReadonlySet<string> = new Set([
@@ -114,10 +132,16 @@ async function dispatchEngineVerb(
   env: NativeEnv,
 ): Promise<TmResult> {
   switch (verb) {
-    case 'ls':
-      return lsVerb(ctx)
-    case 'states':
-      return statesVerb(ctx)
+    case 'ls': {
+      const parsed = parseFleetListFlags('ls', rest)
+      if ('error' in parsed) return parsed.error
+      return lsVerb(ctx, { all: parsed.all })
+    }
+    case 'states': {
+      const parsed = parseFleetListFlags('states', rest)
+      if ('error' in parsed) return parsed.error
+      return statesVerb(ctx, { all: parsed.all })
+    }
     case 'status': {
       if (rest.length === 0) {
         return { code: 1, stdout: '', stderr: 'tm: usage: tm status <name> [lines=80]\n' }

package/src/engines/claude/base-ref.ts

@@ -0,0 +1,83 @@
+/**
+ * `tm spawn`'s base-ref note. A fresh worktree teammate branches from
+ * the source repo's current HEAD (`claude --worktree` pins
+ * `worktree.baseRef = "head"`). When the repo happens to be parked on a
+ * branch other than the trunk, the teammate silently starts from the
+ * wrong baseline — so spawn prints a one-line summary of that ref:
+ * the current branch + short sha, plus a best-effort ahead/behind
+ * against the remote default branch.
+ *
+ * Everything here is best-effort and read-only: a repo that is not a
+ * git checkout, a missing `git`, or any failing probe yields `null`,
+ * and the caller simply omits the line. The base-ref note must never
+ * throw and must never fail a spawn — surfacing the baseline is a
+ * convenience, not a gate.
+ */
+
+import { spawnCapture } from '../../proc'
+
+/** The `git` shell-out the note runs through; injectable so unit tests stay hermetic. */
+export type GitRunner = (
+  args: readonly string[],
+) => Promise<{ code: number; stdout: string; stderr: string }>
+
+const defaultRunner: GitRunner = (args) => spawnCapture(args)
+
+/**
+ * Ahead/behind of HEAD relative to the repo's remote default branch
+ * (`origin/HEAD`, e.g. `origin/main`). Returns `null` when no trunk
+ * resolves — `origin/HEAD` is frequently unset on a local clone — so
+ * the caller drops the comparison rather than guessing a trunk.
+ */
+async function aheadBehind(repo: string, run: GitRunner): Promise<string | null> {
+  try {
+    const trunkRes = await run(['git', '-C', repo, 'rev-parse', '--abbrev-ref', 'origin/HEAD'])
+    if (trunkRes.code !== 0) return null
+    const trunk = trunkRes.stdout.trim()
+    if (trunk.length === 0) return null
+    const countRes = await run([
+      'git', '-C', repo, 'rev-list', '--left-right', '--count', `HEAD...${trunk}`,
+    ])
+    if (countRes.code !== 0) return null
+    const parts = countRes.stdout.trim().split(/\s+/)
+    const ahead = Number(parts[0])
+    const behind = Number(parts[1])
+    if (!Number.isFinite(ahead) || !Number.isFinite(behind)) return null
+    if (ahead === 0 && behind === 0) return `in sync with ${trunk}`
+    const bits: string[] = []
+    if (ahead > 0) bits.push(`${ahead} ahead`)
+    if (behind > 0) bits.push(`${behind} behind`)
+    return `${bits.join(' / ')} ${trunk}`
+  } catch {
+    return null
+  }
+}
+
+/**
+ * A one-line summary of the ref a fresh spawn branches from, e.g.
+ * `main (a1b2c3d), in sync with origin/main` or
+ * `feat/x (a1b2c3d), 2 ahead / 5 behind origin/main`, or
+ * `detached @ a1b2c3d` for a detached HEAD. Returns `null` when the
+ * repo is not a git checkout or any required probe fails.
+ */
+export async function gitBaseRefNote(
+  repo: string,
+  run: GitRunner = defaultRunner,
+): Promise<string | null> {
+  let branch: string
+  let sha: string
+  try {
+    const branchRes = await run(['git', '-C', repo, 'rev-parse', '--abbrev-ref', 'HEAD'])
+    if (branchRes.code !== 0) return null
+    branch = branchRes.stdout.trim()
+    const shaRes = await run(['git', '-C', repo, 'rev-parse', '--short', 'HEAD'])
+    if (shaRes.code !== 0) return null
+    sha = shaRes.stdout.trim()
+  } catch {
+    return null
+  }
+  if (branch.length === 0 || sha.length === 0) return null
+  const head = branch === 'HEAD' ? `detached @ ${sha}` : `${branch} (${sha})`
+  const divergence = await aheadBehind(repo, run)
+  return divergence === null ? head : `${head}, ${divergence}`
+}

package/src/engines/claude/send.ts

@@ -13,9 +13,15 @@
  *     (which fans out by calling `claudeSend` directly).
  */
 
+import { writeFileSync } from 'node:fs'
+
 import { sendKeys } from './keys'
-import { probeStillAlive, waitIdleSignal, waitPaneQuiet } from './wait-signals'
+import { confirmSubmit, probeStillAlive, waitForTurnEnd, waitPaneQuiet } from './wait-signals'
 import { echoCtxToStderr, printLastOrEmpty } from './post-turn'
+import { transcriptFile } from './ctx'
+import { lastAssistantTextAfter, transcriptSizeBytes } from './turn-jsonl'
+import { readIfNonEmpty, resolveSid, rstrip } from './idle'
+import { cwdFile, lastFileFor } from '../../persistence/paths'
 import { die } from './tmux'
 import { isNonNegativeInteger } from './clock'
 import { parseSendArgs } from '../../shared/verb-args'
@@ -46,14 +52,35 @@ export async function claudeSend(args: readonly string[], env: ClaudeVerbEnv): P
     return die(`tm send: --timeout must be a non-negative integer (got: '${timeout}')`)
   }
 
+  // Snapshot the transcript offset BEFORE sending so submit-confirmation
+  // and the JSONL wait fallback only read what THIS turn appends — never
+  // a prior turn's settled entry. `null` when the transcript path cannot
+  // be resolved (no recorded cwd/sid); the JSONL-side checks then no-op
+  // and the marker-based behavior stands alone.
+  const sid0 = resolveSid(name)
+  const cwdRaw = readIfNonEmpty(cwdFile(name))
+  const cwd0 = cwdRaw === null ? null : rstrip(cwdRaw)
+  const jsonl = sid0 !== null && cwd0 !== null ? transcriptFile(env.projectsDir, cwd0, sid0) : null
+  const anchor = { jsonl, sinceBytes: jsonl !== null ? transcriptSizeBytes(jsonl) : 0 }
+
   const sentResult = await sendKeys(name, prompt, env.runTmux, process.env)
   if (sentResult.code !== 0) return sentResult
 
+  // Confirm the prompt was accepted as a turn (not swallowed by a modal).
+  // Warn-and-proceed only — never converts a slow-but-live send into a
+  // failure; the wait below still expires to 124 if the turn never runs.
+  // Pane-quiet covers TUI commands with no turn to confirm, so skip it.
+  let confirmStderr = ''
+  if (!paneQuiet) {
+    const confirmed = await confirmSubmit(name, anchor, env.runTmux)
+    if (!confirmed.ok) confirmStderr = confirmed.warn
+  }
+
   const timeoutSec = timeout === null ? 1800 : Number(timeout)
   const verdict = paneQuiet
     ? await waitPaneQuiet(name, timeoutSec, env.runTmux)
-    : await waitIdleSignal(name, timeoutSec, false, env.runTmux)
-  if ('code' in verdict) return verdict
+    : await waitForTurnEnd(name, timeoutSec, false, env.runTmux, anchor)
+  if ('code' in verdict) return { ...verdict, stderr: confirmStderr + verdict.stderr }
   if (!verdict.ok) {
     // Re-probe at the timeout moment: a teammate that died mid-wait must
     // NOT be reported as "still running" with code 124, or the dispatcher's
@@ -62,7 +89,7 @@ export async function claudeSend(args: readonly string[], env: ClaudeVerbEnv): P
     // promise 124 ("still running") when the session + sid are still there.
     const dead = await probeStillAlive(name, env.runTmux)
     if (dead !== null) {
-      return { ...dead, stderr: sentResult.stderr + dead.stderr }
+      return { ...dead, stderr: sentResult.stderr + confirmStderr + dead.stderr }
     }
     const kind = paneQuiet ? 'pane-quiet' : 'Stop hook'
     return {
@@ -70,17 +97,37 @@ export async function claudeSend(args: readonly string[], env: ClaudeVerbEnv): P
       stdout: printLastOrEmpty(name),
       stderr:
         sentResult.stderr +
+        confirmStderr +
         `tm send: sync wait expired after ${timeoutSec}s on ${name} ` +
         `(no ${kind} fired; the teammate is still running — tail with ` +
         `'tm wait ${name}' or check 'tm status ${name}'). exit ${EXIT_SYNC_WAIT_EXPIRED}.\n`,
     }
   }
 
+  // No-hook JSONL fallback: the turn settled in the transcript but the
+  // Stop hook never wrote `<sid>.last` (sendKeys' clearIdle wiped it at
+  // send time and no hook repopulated it). Recover the reply from THIS
+  // turn's appended region — scoped to the send offset, so a prior turn's
+  // text is never surfaced — and persist it exactly as `tm spawn --resume`
+  // seeds `.last`, so stdout AND `tm last` / `tm states` all surface the
+  // reply instead of the "(no text reply...)" sentinel. A textless turn
+  // (tool-only) writes an empty `.last`, clearing any stale value. The
+  // marker path is left untouched: on-stop writes `.last` before touching
+  // the idle marker, so `via: 'marker'` means `.last` is already current.
+  if (!paneQuiet && 'via' in verdict && verdict.via === 'jsonl' && jsonl !== null && sid0 !== null) {
+    const recovered = lastAssistantTextAfter(jsonl, anchor.sinceBytes)
+    try {
+      writeFileSync(lastFileFor(sid0), recovered !== null && recovered.length > 0 ? `${recovered}\n` : '')
+    } catch {
+      // Best-effort: printLastOrEmpty falls back to the sentinel if unwritten.
+    }
+  }
+
   let trailingStderr = ''
   if (!paneQuiet) trailingStderr = echoCtxToStderr(name, env)
   return {
     code: 0,
     stdout: printLastOrEmpty(name),
-    stderr: sentResult.stderr + trailingStderr,
+    stderr: sentResult.stderr + confirmStderr + trailingStderr,
   }
 }

package/src/engines/claude/spawn.ts

@@ -29,6 +29,7 @@ import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
 import { dirname } from 'node:path'
 
 import { claudeSend } from './send'
+import { gitBaseRefNote } from './base-ref'
 import { readLastAssistantText, transcriptFile } from './ctx'
 import { clearIdle, isDirectory } from './idle'
 import { newSid } from './identifiers'
@@ -47,6 +48,25 @@ import {
 import type { ClaudeVerbEnv } from './env'
 import { EXIT_SYNC_WAIT_EXPIRED, type TmResult } from '../../tm'
 
+/**
+ * Value for `CLAUDE_CODE_RESUME_TOKEN_THRESHOLD`, injected into every
+ * teammate tmux session. Claude Code raises a "Resume from summary
+ * (recommended) / Resume full session as-is" startup prompt when a
+ * resumed session is older than `CLAUDE_CODE_RESUME_THRESHOLD_MINUTES`
+ * (default 70) AND larger than `CLAUDE_CODE_RESUME_TOKEN_THRESHOLD`
+ * (default 100_000) tokens. A teammate has no human to answer that
+ * modal, and the next `tm send`'s Enter lands on it — picking the
+ * default "summary" option, which runs `/compact` and discards the
+ * full context the resume was meant to restore. Setting the token
+ * threshold far above any real context window keeps that condition
+ * permanently false, so the prompt never renders and a resumed
+ * teammate always loads its full session silently. Degrades safely:
+ * a Claude Code build that drops this knob simply re-exposes the
+ * prompt, falling back to the documented "confirm with tm status"
+ * guidance.
+ */
+const RESUME_TOKEN_THRESHOLD_SUPPRESS = 100_000_000
+
 interface ClaudeLaunchArgs {
   /** Physical repo path (the parent of the worktree, or the cwd itself). */
   readonly repo: string
@@ -84,9 +104,15 @@ function shellSingleQuote(value: string): string {
  * `claude --session-id|--resume <sid>` and the optional `-n '<name>'`
  * / `--worktree <slug>` extras. A bare tool name in
  * `--disallowedTools` drops it from the model's context entirely.
+ *
+ * `EnterPlanMode` / `ExitPlanMode` join `AskUserQuestion` on the
+ * disallow list for the same reason: plan mode opens an approval modal
+ * that holds the turn open waiting for a human, and a teammate has no
+ * human at its terminal. A teammate proposes a plan by ending its turn
+ * with text, which `tm send` relays to the dispatcher.
  */
 function teammateLaunchFlags(mdExcludes: string): string {
-  return `--settings ${shellSingleQuote(mdExcludes)} --disallowedTools AskUserQuestion`
+  return `--settings ${shellSingleQuote(mdExcludes)} --disallowedTools AskUserQuestion,EnterPlanMode,ExitPlanMode`
 }
 
 /**
@@ -318,7 +344,12 @@ async function claudeLaunch(
   // cannot wrong-route. `-e CLAUDEMUX_TEAMMATE_NAME=...` is the
   // positive identity gate the on-session-start hook reads to
   // discriminate "this teammate" from "the dispatcher happens to
-  // share the cwd".
+  // share the cwd". `-e CLAUDE_CODE_RESUME_TOKEN_THRESHOLD=...`
+  // suppresses Claude Code's "resume from summary vs full session"
+  // startup prompt (see RESUME_TOKEN_THRESHOLD_SUPPRESS): a teammate
+  // is headless and cannot answer that modal, and the prompt's
+  // Enter-default picks the compacted summary — silently dropping the
+  // very context a resume is meant to restore.
   let paneId = ''
   try {
     const newSession = await env.runTmux([
@@ -330,6 +361,8 @@ async function claudeLaunch(
       paneCwd,
       '-e',
       `CLAUDEMUX_TEAMMATE_NAME=${name}`,
+      '-e',
+      `CLAUDE_CODE_RESUME_TOKEN_THRESHOLD=${RESUME_TOKEN_THRESHOLD_SUPPRESS}`,
       '-P',
       '-F',
       '#{session_id}',
@@ -367,6 +400,23 @@ async function claudeLaunch(
     stderr += `spawned: ${name} (tmux=${session}, cwd=${cwd}${worktreeNote}, sid=${sid})\n`
   }
 
+  // Surface the baseline a fresh spawn starts from. A worktree teammate
+  // branches `worktree-<slug>` off the repo's current HEAD; a
+  // `--no-worktree` teammate runs on it directly. Printing the branch +
+  // short sha (plus best-effort ahead/behind vs the remote default)
+  // makes a repo parked on the wrong branch obvious instead of silent.
+  // Only on the genuine fresh-launch path — resume / continue reuse an
+  // existing session, and an already-present worktree is not re-created
+  // from HEAD, so the note would mislead in those cases.
+  if (resumeSid.length === 0 && !continueLatest) {
+    const worktreeAlreadyThere =
+      worktreeSlug !== null && existsSync(worktreePathFor(repo, worktreeSlug))
+    if (!worktreeAlreadyThere) {
+      const baseNote = await gitBaseRefNote(repo)
+      if (baseNote !== null) stderr += `base: ${baseNote}\n`
+    }
+  }
+
   if (!continueLatest) {
     const sf = sidFile(name)
     mkdirSync(dirname(sf), { recursive: true })

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

@@ -0,0 +1,165 @@
+/**
+ * JSONL turn-state reads for the Claude engine — the transcript-side
+ * signals that back `tm send`'s submit confirmation and the no-hook wait
+ * fallback. These mirror what `hooks/on-stop.sh` decides in bash
+ * (terminal stop_reason + a text/tool_use block = a settled turn), but
+ * run inside `tm` so a session whose Stop hook never fired still gets
+ * JSONL-grade turn detection instead of a pane-quiet heuristic.
+ *
+ * Every read is anchored to a byte offset snapshotted at send time, so a
+ * settled assistant entry from a PRIOR turn (which lives before the
+ * offset) can never be mistaken for this turn's completion. Reads of the
+ * appended region only; a file that shrank (compaction rewrote it) is
+ * treated as "nothing new yet" rather than risking a false positive.
+ */
+
+import { closeSync, openSync, readSync, statSync } from 'node:fs'
+
+/** Terminal `stop_reason` values — the API call ended without expecting the agent loop to continue. */
+const TERMINAL_STOP_REASONS = new Set(['end_turn', 'stop_sequence', 'max_tokens', 'refusal'])
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** Byte size of the transcript, or 0 when it does not exist yet. */
+export function transcriptSizeBytes(path: string): number {
+  try {
+    return statSync(path).size
+  } catch {
+    return 0
+  }
+}
+
+/**
+ * Read the bytes appended after `sinceBytes`. Returns `''` when the file
+ * is missing, unreadable, or no larger than `sinceBytes` (including the
+ * shrink-after-compaction case). Reading only the tail keeps every poll
+ * O(one turn) rather than O(whole transcript).
+ */
+function readAppended(path: string, sinceBytes: number): string {
+  let fd: number
+  try {
+    const size = statSync(path).size
+    if (size <= sinceBytes) return ''
+    fd = openSync(path, 'r')
+    try {
+      const len = size - sinceBytes
+      const buf = Buffer.allocUnsafe(len)
+      const read = readSync(fd, buf, 0, len, sinceBytes)
+      return buf.toString('utf8', 0, read)
+    } finally {
+      closeSync(fd)
+    }
+  } catch {
+    return ''
+  }
+}
+
+/** Parse the complete JSONL lines in `text`; a trailing partial line (mid-write) is dropped. */
+function parsedLines(text: string): Record<string, unknown>[] {
+  const out: Record<string, unknown>[] = []
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim()
+    if (trimmed === '') continue
+    let value: unknown
+    try {
+      value = JSON.parse(trimmed)
+    } catch {
+      // A half-written final line, or a non-JSON line — skip it. A real
+      // entry reappears intact on the next poll.
+      continue
+    }
+    if (isPlainObject(value)) out.push(value)
+  }
+  return out
+}
+
+/**
+ * Whether any `type: "user"` entry appears in the region appended after
+ * `sinceBytes`. Claude Code writes the submitted prompt as a user entry,
+ * so a new user entry after the send offset is positive evidence the
+ * input was accepted as a turn — the signal `tm send` uses to tell
+ * "submitted" from "the Enter was swallowed by a modal". Slash-command
+ * and tool_result entries are also `type: "user"`; counting them is
+ * correct here — any of them proves the REPL took the input, which is
+ * exactly the question submit-confirmation answers.
+ */
+export function userEntryAppearedAfter(path: string, sinceBytes: number): boolean {
+  for (const entry of parsedLines(readAppended(path, sinceBytes))) {
+    if (entry['type'] === 'user') return true
+  }
+  return false
+}
+
+/**
+ * Whether the most recent assistant entry in the region appended after
+ * `sinceBytes` is SETTLED — terminal `stop_reason` AND at least one
+ * `text` or `tool_use` content block. This is `on-stop.sh`'s
+ * `is_assistant_settled` predicate, scoped to this turn's appended
+ * region:
+ *
+ *  - mid tool-loop → the last assistant entry's stop_reason is
+ *    `tool_use` (non-terminal) → not settled → keep waiting;
+ *  - a thinking-only response that ended with `end_turn` before the
+ *    text response landed → no text/tool_use block → not settled →
+ *    keep waiting (the split-turn case `on-stop.sh` guards against);
+ *  - the final text/tool_use response with a terminal stop_reason →
+ *    settled → the turn is over.
+ */
+export function terminalAssistantAfter(path: string, sinceBytes: number): boolean {
+  let lastAssistantSettled = false
+  let sawAssistant = false
+  for (const entry of parsedLines(readAppended(path, sinceBytes))) {
+    if (entry['type'] !== 'assistant') continue
+    sawAssistant = true
+    const message = entry['message']
+    if (!isPlainObject(message)) {
+      lastAssistantSettled = false
+      continue
+    }
+    const reason = message['stop_reason']
+    const content = Array.isArray(message['content']) ? message['content'] : []
+    const types = new Set(
+      content.filter(isPlainObject).map((block) => block['type']),
+    )
+    lastAssistantSettled =
+      typeof reason === 'string' &&
+      TERMINAL_STOP_REASONS.has(reason) &&
+      (types.has('text') || types.has('tool_use'))
+  }
+  return sawAssistant && lastAssistantSettled
+}
+
+/**
+ * The joined text of the most recent text-bearing assistant entry in the
+ * region appended after `sinceBytes`, or `null` when none exists (no
+ * assistant entry, or a tool-only / thinking-only turn with no `text`
+ * block). Mirrors `readLastAssistantText` — the on-stop hook's
+ * `extract_last_turn` shape — but scoped to THIS turn's appended region,
+ * so a prior turn's reply can never be recovered as this turn's.
+ *
+ * `tm send` uses this on the no-hook JSONL wait-fallback path: the Stop
+ * hook never wrote `<sid>.last`, so the deliverable lives only in the
+ * transcript, and this recovers it to repopulate `.last` and stdout.
+ */
+export function lastAssistantTextAfter(path: string, sinceBytes: number): string | null {
+  const entries = parsedLines(readAppended(path, sinceBytes))
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i]!
+    if (entry['type'] !== 'assistant') continue
+    const message = entry['message']
+    if (!isPlainObject(message)) continue
+    const content = Array.isArray(message['content']) ? message['content'] : []
+    const texts: string[] = []
+    for (const block of content) {
+      if (!isPlainObject(block)) continue
+      if (block['type'] !== 'text') continue
+      const t = block['text']
+      if (typeof t === 'string') texts.push(t)
+    }
+    const joined = texts.join('')
+    if (joined.length > 0) return joined
+  }
+  return null
+}

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

@@ -9,12 +9,151 @@ 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 { requireSession, resolvePaneTarget } from './tmux'
 import { nowSec, sleepMs } from './clock'
+import { terminalAssistantAfter, userEntryAppearedAfter } from './turn-jsonl'
 import type { TeammateName } from '../types'
 import type { TmResult } from '../../tm'
 import type { TmuxRunner } from '../../tmux'
 
+/**
+ * A turn's JSONL anchor — the transcript path and the byte offset
+ * snapshotted at send time. `tm send` passes this so the submit
+ * confirmation and the wait can read only the region appended by THIS
+ * turn (never a prior turn's settled entry). `jsonl` is `null` when the
+ * transcript path could not be resolved (no recorded cwd / sid), in
+ * which case the JSONL-side checks are skipped and the marker-based
+ * behavior stands alone.
+ */
+export interface TurnAnchor {
+  readonly jsonl: string | null
+  readonly sinceBytes: number
+}
+
+/**
+ * Total budget (ms) for `confirmSubmit`. Override via
+ * `CLAUDEMUX_CONFIRM_SUBMIT_MS`; `0` disables confirmation entirely
+ * (the conformance harness and the sync-wait tests set it so a synthetic
+ * "send succeeded, wait expires" scenario is not held up — or reshaped —
+ * by submit confirmation). Default 4s: a real submission's turn-start
+ * signal (the on-busy marker, or the prompt's user entry in the jsonl)
+ * lands well under a second, so the budget is a ceiling for the
+ * not-submitted case, not a cost every send pays.
+ */
+function confirmSubmitBudgetMs(): number {
+  const raw = process.env['CLAUDEMUX_CONFIRM_SUBMIT_MS']
+  if (raw !== undefined && raw !== '') {
+    const parsed = Number(raw)
+    if (Number.isFinite(parsed) && parsed >= 0) return parsed
+  }
+  return 4000
+}
+
+/**
+ * After `tm send` injects a prompt + Enter, verify the REPL actually
+ * accepted it as a turn — rather than the Enter being swallowed by a
+ * modal (the bug #2 class) and the prompt text discarded. "Accepted" is
+ * any of: the on-busy hook set the `.busy` marker, the idle marker
+ * reappeared (a fast turn already ended), or a new user entry landed in
+ * the transcript past the send offset (hook-independent). When none of
+ * those appears within an attempt's slice, re-send Enter (the common
+ * "the first Enter did not register" case) and recheck, up to 3
+ * attempts. Returns `{ ok: true }` on confirmation; otherwise a warning
+ * the caller prepends to stderr — `tm send` then PROCEEDS to the wait
+ * (which expires to 124 if the turn truly never runs), so confirmation
+ * never converts a working-but-slow send into a hard failure.
+ */
+export async function confirmSubmit(
+  name: TeammateName,
+  anchor: TurnAnchor,
+  runTmux: TmuxRunner,
+): Promise<{ ok: true } | { ok: false; warn: string }> {
+  const totalMs = confirmSubmitBudgetMs()
+  if (totalMs <= 0) return { ok: true }
+
+  const submitted = (): boolean => {
+    const sid = resolveSid(name)
+    if (sid !== null && (isRegularFile(busyMarkerFor(sid)) || existsSync(idleMarkerFor(sid)))) {
+      return true
+    }
+    return anchor.jsonl !== null && userEntryAppearedAfter(anchor.jsonl, anchor.sinceBytes)
+  }
+
+  const attempts = 3
+  const tickMs = 200
+  const ticksPerAttempt = Math.max(1, Math.round(totalMs / attempts / tickMs))
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    for (let tick = 0; tick < ticksPerAttempt; tick++) {
+      if (submitted()) return { ok: true }
+      await sleepMs(tickMs)
+    }
+    if (attempt < attempts) {
+      // Re-send Enter best-effort. Targets the resolved pane so a
+      // prefix-match cannot wrong-route; a failure here is swallowed —
+      // the next attempt's poll (or the final warning) covers it.
+      try {
+        const pane = await resolvePaneTarget(name, runTmux)
+        if (pane !== '') await runTmux(['send-keys', '-t', pane, 'Enter'])
+      } catch {
+        // ignore — best-effort retry.
+      }
+    }
+  }
+  if (submitted()) return { ok: true }
+  return {
+    ok: false,
+    warn:
+      `tm send: ${name}: no turn-start signal after re-sending Enter ` +
+      `${attempts - 1}x in ~${Math.round(totalMs / 1000)}s — the prompt may not have ` +
+      `landed (the REPL may be at a modal, or the turn is very slow to start). ` +
+      `Proceeding to wait; if no reply arrives, check 'tm status ${name}'.\n`,
+  }
+}
+
+/** Which signal ended the turn — the Stop-hook idle marker, or the transcript. */
+export type TurnEndSignal = 'marker' | 'jsonl'
+
+/**
+ * Block until the teammate's turn ends, by either signal: the Stop-hook
+ * idle marker `/tmp/claude-idle/<sid>` (the primary path), OR — when the
+ * transcript path resolved — a settled assistant entry appended past the
+ * send offset (`terminalAssistantAfter`). The JSONL branch is the
+ * no-hook fallback: a session whose Stop hook never fired still unblocks
+ * here once its turn reaches a terminal stop_reason on disk, instead of
+ * burning the full timeout to a 124. When `jsonl` is `null` the JSONL
+ * branch never trips, so this is byte-for-byte `waitIdleSignal`.
+ *
+ * On success it reports WHICH signal ended the turn (`via`). The caller
+ * needs this: on `via: 'marker'` the Stop hook already wrote `<sid>.last`
+ * (it writes `.last` before touching the idle marker), but on
+ * `via: 'jsonl'` no hook ran, so `.last` is absent and the reply must be
+ * recovered from the transcript. This function itself stays read-only.
+ */
+export async function waitForTurnEnd(
+  name: TeammateName,
+  timeoutSec: number,
+  fresh: boolean,
+  runTmux: TmuxRunner,
+  anchor: TurnAnchor,
+): Promise<TmResult | { ok: true; via: TurnEndSignal } | { ok: false }> {
+  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, via: 'marker' }
+    if (anchor.jsonl !== null && terminalAssistantAfter(anchor.jsonl, anchor.sinceBytes)) {
+      return { ok: true, via: 'jsonl' }
+    }
+    await sleepMs(3000)
+  }
+  return { ok: false }
+}
+
 /**
  * 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

package/src/engines/types.ts

@@ -277,7 +277,13 @@ export type TextResult =
 export interface TeammateListing {
   readonly name: TeammateName
   readonly engine: EngineKind
-  readonly state: 'idle' | 'busy' | 'unknown'
+  /**
+   * Live turn state from the hook markers, or `killed` for an archived
+   * record surfaced by `tm ls --all` / `tm states --all` — that
+   * teammate has no live process; its identity snapshot survives kill
+   * so it stays resumable by name.
+   */
+  readonly state: 'idle' | 'busy' | 'unknown' | 'killed'
   /** Physical repo path the teammate is bound to. */
   readonly repo: string
   /** Runtime working directory (worktree path or `repo`). */

package/src/help.ts

@@ -39,8 +39,9 @@ USAGE  (most common first)
   tm kill <name>                         graceful /exit (clean worktree auto-removed);
                                          dirty worktree preserved with stderr note
   tm reload <name>... | --all            fan out /reload-plugins
-  tm ls                                  list teammates (NAME REPO WORKTREE ENGINE STATE)
-  tm states                              rich fleet snapshot
+  tm ls [--all]                          list teammates (NAME REPO WORKTREE ENGINE STATE);
+                                         --all also lists killed teammates (resumable by name)
+  tm states [--all]                      rich fleet snapshot; --all includes killed teammates
   tm ctx <name>... | --all               real ctx-window usage from jsonl
   tm history <name> [<sid/thread-prefix>] inspect past sessions for this teammate
   tm mem <name>                          cat the parent repo's auto-memory index
@@ -70,20 +71,34 @@ ENVIRONMENT
 
 /** Per-verb help text — `tm <verb> --help` and `tm help <verb>` both print this. */
 export const HELP_TEXTS: Readonly<Record<string, string>> = {
-  ls: `tm ls
-
-      List running teammate-<name> sessions. Shows tmux's raw session
-      row (name, window count, attached state). For a richer "who's
-      doing what" view, prefer \`tm states\`.
+  ls: `tm ls [--all]
+
+      List teammates, one row each: NAME, REPO (last path segment),
+      WORKTREE (slug or '-'), ENGINE (claude / codex), STATE (idle /
+      busy / unknown). The live fleet comes from each engine's session
+      listing. For a richer "who's doing what" view, prefer
+      \`tm states\`.
+
+      --all also lists killed teammates — the identity snapshots
+      \`tm kill\` archives under /tmp/teammate-archive/<name>.json —
+      with STATE 'killed'. Their NAME / REPO / WORKTREE are enough to
+      re-launch with \`tm resume <name>\`, so you recover a killed
+      session without scraping /tmp by hand. A name that is live again
+      shows its live row, not the stale killed one.
 `,
-  states: `tm states
+  states: `tm states [--all]
 
-      One-line fleet snapshot: REPO, SID / thread id (first 8
-      chars), BUSY, LAST (size + age of the last assistant reply),
-      PREVIEW (first 50 chars of that reply). Claude reads
+      Rich fleet snapshot, one row each: NAME, REPO, WORKTREE, ENGINE,
+      STATE, LAST (size + age of the last assistant reply), PREVIEW
+      (first chars of that reply). Claude reads
       /tmp/claude-idle/<sid>.last; Codex reads the current thread's
       rollout JSONL. Use to see what every teammate is doing at a
       glance.
+
+      --all also lists killed teammates (STATE 'killed') from the
+      kill-time identity archive, same as \`tm ls --all\`; their LAST /
+      PREVIEW render as '-' because the live markers are gone. Recover
+      one with \`tm resume <name>\`.
 `,
   spawn: `tm spawn <path> [--name <id>] [--engine claude|codex] [--prompt "..."] [--no-worktree] [--timeout N]
 
@@ -112,6 +127,12 @@ export const HELP_TEXTS: Readonly<Record<string, string>> = {
       useful for repo-wide work where a worktree would be a
       negative-value isolation.
 
+      On a fresh launch the verb prints a \`base:\` line to stderr —
+      the branch + short sha the teammate starts from, plus a
+      best-effort ahead/behind vs the remote default branch. The base
+      is the repo's current HEAD, so a repo parked on a non-trunk
+      branch is visible at a glance rather than a silent surprise.
+
       Without --prompt, the verb returns once the REPL signals
       SessionStart (typically 2-4s on a warm Mac). With
       \`--prompt "..."\`, the verb sleeps 3s after ready, sends the
@@ -126,11 +147,13 @@ export const HELP_TEXTS: Readonly<Record<string, string>> = {
       \`.claude/worktrees/<name>/\` layout; they are not tmux sessions,
       and \`--resume\` / \`--task\` are rejected on that path.
 
-      Every teammate launches with the \`AskUserQuestion\` tool
-      disabled — a teammate runs with no human at its terminal, and
-      that modal would hold the turn open. A teammate raises
-      questions by ending its turn with text, which \`tm send\` /
-      \`tm spawn --prompt\` relays straight back to the dispatcher.
+      Every teammate launches with the \`AskUserQuestion\`,
+      \`EnterPlanMode\`, and \`ExitPlanMode\` tools disabled — a
+      teammate runs with no human at its terminal, and each of those
+      opens a modal that holds the turn open waiting for a person. A
+      teammate raises questions or proposes a plan by ending its turn
+      with text, which \`tm send\` / \`tm spawn --prompt\` relays
+      straight back to the dispatcher.
 
       Exit codes on the \`--prompt\` sync path:
         0   first-turn reply
@@ -157,6 +180,15 @@ export const HELP_TEXTS: Readonly<Record<string, string>> = {
         need it — the Stop hook now covers them via PostCompact /
         SessionEnd.
       --timeout N overrides the 1800s default wait.
+      After sending, confirms the REPL accepted the prompt as a turn
+      (the on-busy marker, or a new user entry in the transcript) and
+      re-sends Enter up to 3x if not — so an Enter swallowed by a modal
+      surfaces a stderr warning instead of a silent wait. The wait then
+      unblocks on either the Stop-hook idle marker OR a settled turn in
+      the transcript jsonl, so a session whose Stop hook never loaded
+      still ends its wait on disk evidence instead of timing out. On
+      that no-hook path the reply is recovered from the transcript (and
+      written back to <sid>.last), so stdout still carries it.
       Empty stdout never silently means success: a turn with no text
       (tool-only, /compact, /clear) prints the sentinel line "(no
       text reply this turn — tool-only, /compact, /clear, or fresh
@@ -259,6 +291,18 @@ export const HELP_TEXTS: Readonly<Record<string, string>> = {
       AskUserQuestion tool disabled (see 'tm help spawn' for why): a
       resumed teammate raises questions by ending its turn with
       text, not by opening a modal.
+
+      Large-session startup prompt: resuming a big, hours-old Claude
+      session can make Claude Code raise a "Resume from summary
+      (recommended) / Resume full session as-is" startup selection
+      that waits for a choice — and a teammate has no human to answer
+      it. Teammates suppress it: 'tm spawn' / 'tm resume' launch with
+      CLAUDE_CODE_RESUME_TOKEN_THRESHOLD set far above any real window,
+      so the prompt never renders and the full session loads silently.
+      Fallback only — if a future Claude Code build ignores that knob
+      and the prompt reappears, confirm the REPL is at a normal input
+      box with 'tm status <name>' before the next 'tm send' (a blind
+      send's Enter would pick the summary and discard context).
 `,
   last: `tm last <name> [--verbose]
 

package/src/persistence/identity-store.ts

@@ -91,6 +91,9 @@ export function archivedIdentityFile(name: TeammateName): string {
 /** Regex pinning the top-level identity-file name shape; capture group 1 is the name. */
 const TOP_LEVEL_FILENAME = /^teammate-(.+)\.json$/
 
+/** Regex pinning the archived identity-file name shape (`<name>.json`, no prefix). */
+const ARCHIVE_FILENAME = /^(.+)\.json$/
+
 export type ReserveResult =
   | { kind: 'reserved' }
   | { kind: 'taken'; existing: TeammateRecordJson }
@@ -232,6 +235,49 @@ export function list(): readonly TeammateRecordJson[] {
   return out
 }
 
+/**
+ * Enumerate every archived teammate record — the snapshots `tm kill`
+ * leaves behind under `<identityRoot>/teammate-archive/<name>.json`.
+ * `tm ls --all` / `tm states --all` use this to surface killed
+ * teammates that no live tmux session or Codex daemon would report,
+ * so the agent can recover a resumable name without scraping `/tmp`.
+ *
+ * The archive holds the LAST snapshot per name: re-spawning then
+ * re-killing a name overwrites its archive entry, and a name that is
+ * currently live also keeps its prior kill's snapshot here. Callers
+ * that merge this with the live fleet must dedupe by name, preferring
+ * the live row.
+ *
+ * Unparseable or schema-mismatched files are skipped, mirroring
+ * `list()`. The directory not existing yet (no teammate ever killed)
+ * returns an empty list, not an error.
+ */
+export function listArchived(): readonly TeammateRecordJson[] {
+  const out: TeammateRecordJson[] = []
+  const dir = archiveDir()
+  let entries: string[]
+  try {
+    entries = readdirSync(dir)
+  } catch {
+    return []
+  }
+  for (const entry of entries) {
+    if (ARCHIVE_FILENAME.exec(entry) === null) continue
+    let info: ReturnType<typeof statSync>
+    try {
+      info = statSync(join(dir, entry))
+    } catch {
+      continue
+    }
+    if (!info.isFile()) continue
+    const raw = readIfPresent(join(dir, entry))
+    if (raw === null) continue
+    const parsed = parse(raw)
+    if (parsed !== null) out.push(parsed)
+  }
+  return out
+}
+
 /**
  * Parse a raw JSON file into a `TeammateRecordJson`. Returns `null` if
  * the shape doesn't match the current schema. Schema 2 is the

package/src/verbs/format.ts

@@ -24,6 +24,7 @@ import type {
   TeammateStatus,
   TurnResult,
 } from '../engines/types'
+import { listArchived } from '../persistence/identity-store'
 import { EXIT_SYNC_WAIT_EXPIRED, type TmResult } from '../tm'
 
 function rawTmResult(result: RawTmResult): TmResult | null {
@@ -60,6 +61,33 @@ function repoLeaf(path: string): string {
   return leaf.length === 0 ? '-' : leaf
 }
 
+/**
+ * Build the `killed` listing rows for `tm ls --all` / `tm states --all`:
+ * every archived identity record whose name is not already present in
+ * the live fleet. A killed teammate has no live markers, so the runtime
+ * `extras` (last / preview) are empty — the formatters render them as
+ * `-`. The name / repo / worktree / engine come straight from the
+ * archived record, which is enough to drive `tm resume <name>`.
+ *
+ * `liveNames` is the set of names the live `engine.list()` fan-out
+ * already returned; archived entries for those names are dropped so a
+ * re-spawned teammate shows its live row, not a stale killed one.
+ */
+export function archivedListingRows(liveNames: ReadonlySet<string>): TeammateListing[] {
+  return listArchived()
+    .filter((record) => !liveNames.has(record.name))
+    .map((record) => ({
+      name: record.name,
+      engine: record.engine,
+      state: 'killed' as const,
+      repo: record.repo,
+      cwd: record.cwd,
+      worktreeSlug: record.worktreeSlug,
+      displayName: record.displayName,
+      extras: {},
+    }))
+}
+
 export function formatListing(rows: readonly TeammateListing[]): TmResult {
   if (rows.length === 0) {
     return {

package/src/verbs/ls.ts

@@ -11,17 +11,24 @@
  * the row shape, not the verb.
  */
 
-import { formatListing, noEngineRegistered } from './format'
+import { archivedListingRows, formatListing, noEngineRegistered } from './format'
 import type { VerbContext } from './context'
 import type { TmResult } from '../tm'
 
-export async function lsVerb(ctx: VerbContext): Promise<TmResult> {
+export interface LsOptions {
+  /** `--all`: also list killed teammates from the kill-time identity archive. */
+  readonly all: boolean
+}
+
+export async function lsVerb(ctx: VerbContext, opts: LsOptions): Promise<TmResult> {
   // An empty registry means production wiring is incomplete — the verb must
   // surface that loudly, not silently report "no teammates". A zero-engine
   // process is a misconfiguration, not a fleet state.
   const engines = ctx.engines.registered()
   if (engines.length === 0) return noEngineRegistered()
 
-  const listings = await Promise.all(engines.map((engine) => engine.list(ctx.engineContext)))
-  return formatListing(listings.flat())
+  const live = (await Promise.all(engines.map((engine) => engine.list(ctx.engineContext)))).flat()
+  if (!opts.all) return formatListing(live)
+  const liveNames = new Set(live.map((row) => row.name))
+  return formatListing([...live, ...archivedListingRows(liveNames)])
 }

package/src/verbs/states.ts

@@ -14,9 +14,14 @@
  */
 
 import type { TmResult } from '../tm'
-import { noEngineRegistered } from './format'
+import { archivedListingRows, noEngineRegistered } from './format'
 import type { VerbContext } from './context'
 
+export interface StatesOptions {
+  /** `--all`: also list killed teammates from the kill-time identity archive. */
+  readonly all: boolean
+}
+
 type StatesRow = readonly [
   string, string, string, string,
   string, string, string,
@@ -47,13 +52,16 @@ function repoLeaf(path: string): string {
   return leaf.length === 0 ? '-' : leaf
 }
 
-export async function statesVerb(ctx: VerbContext): Promise<TmResult> {
+export async function statesVerb(ctx: VerbContext, opts: StatesOptions): Promise<TmResult> {
   const engines = ctx.engines.registered()
   if (engines.length === 0) return noEngineRegistered()
 
-  const listings = (
+  const live = (
     await Promise.all(engines.map((engine) => engine.list(ctx.engineContext)))
   ).flat()
+  const listings = opts.all
+    ? [...live, ...archivedListingRows(new Set(live.map((row) => row.name)))]
+    : live
 
   if (listings.length === 0) return { code: 0, stdout: '(no teammate sessions)\n', stderr: '' }