@excitedjs/tm 1.1.0

package/src/engines/claude/clock.ts

@@ -0,0 +1,48 @@
+/**
+ * Wall-clock + timing utilities shared by the hot-path verbs. Pulled
+ * out so a future `EngineContext.now()` plumb-through has a single
+ * adapter point (Phase 2a-2 keeps the direct `Date.now()`).
+ */
+
+/** Resolve after `ms` milliseconds — `tm`'s `sleep` analog. */
+export function sleepMs(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+/** Epoch seconds, sampled once — `tm`'s `$(date +%s)`. */
+export function nowSec(): number {
+  return Math.floor(Date.now() / 1000)
+}
+
+/**
+ * Whether `value` is a valid non-negative integer string (the shape
+ * `tm`'s `[[ "$timeout" =~ ^[0-9]+$ ]]` accepts). The native verbs guard
+ * `--timeout` with this so a malformed value does not become a NaN loop.
+ */
+export function isNonNegativeInteger(value: string): boolean {
+  return /^[0-9]+$/.test(value)
+}
+
+/**
+ * Format an epoch-seconds value as `YYYY-MM-DD HH:MM:SS` in local time
+ * — the `tm` `history_detail` `last_seen` field. `tm` does this with
+ * BSD `date -r`, so this rendering matches `tm` on macOS; `date -r
+ * <epoch>` is not portable to GNU, which is why `history`'s detail-
+ * mode conformance is macOS-gated.
+ */
+export function fmtLocalDateTime(epochSec: number): string {
+  const d = new Date(epochSec * 1000)
+  const p = (n: number): string => String(n).padStart(2, '0')
+  return (
+    `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ` +
+    `${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`
+  )
+}
+
+/** Format a second-count as a short relative age — `tm`'s `fmt_age`. */
+export function fmtAge(age: number): string {
+  if (age < 60) return `${age}s`
+  if (age < 3600) return `${Math.floor(age / 60)}m`
+  if (age < 86400) return `${Math.floor(age / 3600)}h`
+  return `${Math.floor(age / 86400)}d`
+}

package/src/engines/claude/compact.ts

@@ -0,0 +1,107 @@
+/**
+ * `tm compact` — send `/compact` and verify PostCompact fired. Reports
+ * the one-line `compacted` on stdout when it did. Two non-success modes
+ * with different exit codes:
+ *
+ *   - Claude Code refuses with the "Not enough messages to compact"
+ *     tool-result block. That path fires no Stop/PostCompact hook, so
+ *     the visible pane is scanned alongside the idle-marker poll to
+ *     detect it. Exit 1 — `/compact` rejected and won't proceed.
+ *   - PostCompact never fires within `--timeout` — compaction may still
+ *     be running. Exit `EXIT_SYNC_WAIT_EXPIRED` (124) to mark this as
+ *     "sync wait expired, teammate still running", distinct from a true
+ *     failure (no session, sid missing) which keeps exit 1.
+ */
+
+import { existsSync } from 'node:fs'
+
+import { sendKeys } from './keys'
+import { resolveSidOrDie } from './idle'
+import { idleMarkerFor } from '../../persistence/paths'
+import { die, requireSession, resolvePaneTarget } from './tmux'
+import { isNonNegativeInteger, nowSec, sleepMs } from './clock'
+import { probeStillAlive } from './wait-signals'
+import { parseCompactArgs } from '../../shared/verb-args'
+import type { ClaudeVerbEnv } from './env'
+import { EXIT_SYNC_WAIT_EXPIRED, type TmResult } from '../../tm'
+
+/** The bracketed-paste refusal `Claude Code` emits for a too-short transcript. */
+export const COMPACT_REFUSAL_MARK = '⎿  Error: Not enough messages to compact'
+
+export async function claudeCompact(args: readonly string[], env: ClaudeVerbEnv): Promise<TmResult> {
+  const parsed = parseCompactArgs(args)
+  if ('error' in parsed) return parsed.error
+  const { name, timeout } = parsed
+  if (name === '') return die('usage: tm compact <name> [timeout=1800] [--timeout N]')
+  if (!isNonNegativeInteger(timeout)) {
+    return die(`tm compact: --timeout must be a non-negative integer (got: '${timeout}')`)
+  }
+
+  const sessionMissing = await requireSession(name, env.runTmux)
+  if (sessionMissing !== null) return sessionMissing
+  const sidR = resolveSidOrDie(name)
+  if ('error' in sidR) return sidR.error
+  const sid = sidR.sid
+  const pane = await resolvePaneTarget(name, env.runTmux)
+  if (pane === '') return die(`could not resolve pane target for ${name}`)
+
+  let stderr = `tm compact: sending /compact to ${name} (sid=${sid}, timeout=${timeout}s)\n`
+
+  const sent = await sendKeys(name, '/compact', env.runTmux, process.env)
+  // `bin/tm:1139` runs `_send_keys >/dev/null`, redirecting *stdout* only;
+  // the `sent to ...` / `sid=...` lines `_send_keys` writes to stderr reach
+  // the user. Preserve them by carrying `sent.stderr` on every return path.
+  stderr += sent.stderr
+  if (sent.code !== 0) {
+    return { code: sent.code, stdout: sent.stdout, stderr }
+  }
+
+  const timeoutSec = Number(timeout)
+  const end = nowSec() + timeoutSec
+  const marker = idleMarkerFor(sid)
+  while (nowSec() < end) {
+    if (existsSync(marker)) {
+      return { code: 0, stdout: 'compacted\n', stderr }
+    }
+    // `bin/tm`'s refusal scan is `[[ -n "$pane" ]] && tmux capture-pane ...`
+    // — if the pane is gone the verb silently disables refusal detection
+    // and keeps polling the idle marker. Mirror that.
+    if (pane.length > 0) {
+      try {
+        const captured = await env.runTmux(['capture-pane', '-t', pane, '-p'])
+        if (captured.code === 0 && captured.stdout.includes(COMPACT_REFUSAL_MARK)) {
+          return {
+            code: 1,
+            stdout: '',
+            stderr:
+              stderr +
+              `tm compact: ${name} refused /compact — Claude Code reported ` +
+              "'Not enough messages to compact' (transcript too short).\n",
+          }
+        }
+      } catch {
+        // A capture failure is a transient tmux error; the idle marker is
+        // the primary signal — keep polling.
+      }
+    }
+    await sleepMs(3000)
+  }
+  // Same re-probe pattern as `send.ts` / `wait.ts`: 124 means "still
+  // running, compact may yet finish — re-collect with `tm wait`." If the
+  // tmux session or sid file vanished mid-wait, that promise is false and
+  // returning 124 would deadlock the dispatcher into never respawning.
+  const dead = await probeStillAlive(name, env.runTmux)
+  if (dead !== null) {
+    return { ...dead, stderr: stderr + dead.stderr }
+  }
+  return {
+    code: EXIT_SYNC_WAIT_EXPIRED,
+    stdout: '',
+    stderr:
+      stderr +
+      `tm compact: sync wait expired after ${timeout}s on ${name} ` +
+      '(PostCompact never fired; compaction may still be running, or the ' +
+      `Stop hook is misconfigured). Check 'tm status ${name}' and ${marker}. ` +
+      `exit ${EXIT_SYNC_WAIT_EXPIRED}.\n`,
+  }
+}

package/src/engines/claude/ctx.ts

@@ -0,0 +1,239 @@
+/**
+ * Claude-engine `tm ctx` body — report a teammate's transcript context
+ * window usage.
+ *
+ * Two entry points keep the strangler clean:
+ *
+ *  - `claudeCtxLine(name, windowOverride, env)` is the byte-exact text
+ *    the legacy `tm ctx` printed per teammate (including the
+ *    `? (no sid / no transcript / no usage)` soft-fails so a `--all`
+ *    fan-out keeps going across teammates with no readable transcript).
+ *    The CLI fan-out wrapper still emits this verbatim.
+ *  - `claudeCtxUsage(name, env)` is the structured `ContextResult` the
+ *    Engine interface speaks in — same numbers, no formatting.
+ */
+
+import { readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { encodeProjectDir } from '../../persistence/paths'
+import { cwdFile } from '../../persistence/paths'
+import { readSid } from './state'
+import type { ContextResult, TeammateName } from '../types'
+
+export interface ClaudeCtxEnv {
+  readonly dispatcherDir: string
+  readonly projectsDir: string
+}
+
+/** A teammate's context-window usage, summed from its transcript. */
+export interface CtxUsage {
+  /** Tokens in the last assistant turn — input plus both cache reads. */
+  used: number
+  /** Output tokens of the last assistant turn. */
+  out: number
+  /** The largest `used`-style total across every assistant turn. */
+  peak: number
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** Sum the cache-inclusive input tokens of one `message.usage` object. */
+function usageInput(usage: Record<string, unknown>): number {
+  const num = (v: unknown): number => (typeof v === 'number' ? v : 0)
+  return (
+    num(usage['input_tokens']) +
+    num(usage['cache_creation_input_tokens']) +
+    num(usage['cache_read_input_tokens'])
+  )
+}
+
+function readIfNonEmpty(file: string): string | null {
+  try {
+    if (statSync(file).size === 0) return null
+    return readFileSync(file, 'utf8')
+  } catch {
+    return null
+  }
+}
+
+function isRegularFile(path: string): boolean {
+  try {
+    return statSync(path).isFile()
+  } catch {
+    return false
+  }
+}
+
+/** The Claude Code transcript file for a teammate session under `projectsDir`. */
+export function transcriptFile(projectsDir: string, cwd: string, sid: string): string {
+  return join(projectsDir, encodeProjectDir(cwd), `${sid}.jsonl`)
+}
+
+/**
+ * The most recent assistant turn's joined text from a Claude Code
+ * transcript jsonl, or `''` when no text-bearing assistant entry exists
+ * (unreadable file, malformed entries, tool-only/thinking-only turns).
+ *
+ * Walks the parsed entries from end to start, picks the first assistant
+ * entry whose `message.content` carries at least one non-empty `text`
+ * block, and returns those text blocks joined with `''` — the on-stop
+ * hook's `extract_last_turn` shape for a single assistant entry.
+ *
+ * Used by `tm spawn --resume` to seed `<sid>.last` with the prior turn's
+ * deliverable so the dispatcher has something to re-read after the
+ * relaunch, even before the next turn fires.
+ */
+export function readLastAssistantText(jsonlPath: string): string {
+  let content: string
+  try {
+    content = readFileSync(jsonlPath, 'utf8')
+  } catch {
+    return ''
+  }
+  const lines = content.split('\n')
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i]!
+    if (line.trim() === '') continue
+    let entry: unknown
+    try {
+      entry = JSON.parse(line)
+    } catch {
+      continue
+    }
+    if (!isPlainObject(entry)) continue
+    if (entry['type'] !== 'assistant') continue
+    const message = entry['message']
+    if (!isPlainObject(message)) continue
+    const arr = message['content']
+    if (!Array.isArray(arr)) continue
+    const texts: string[] = []
+    for (const item of arr) {
+      if (!isPlainObject(item)) continue
+      if (item['type'] !== 'text') continue
+      const t = item['text']
+      if (typeof t === 'string') texts.push(t)
+    }
+    const joined = texts.join('')
+    if (joined.length > 0) return joined
+  }
+  return ''
+}
+
+/**
+ * Read a teammate's ctx usage from its transcript jsonl — the native
+ * form of the `jq -s` pass `tm`'s `_ctx_format_line` ran. Collects
+ * every assistant entry's `message.usage`: `used` / `out` come from the
+ * last one, `peak` is the max input across all. Returns `null` when
+ * there is no usable usage; that includes the cases where `jq -s`
+ * itself would have failed (a non-object entry, a non-object
+ * `.message` / `.message.usage`).
+ */
+export function readCtxUsage(jsonl: string): CtxUsage | null {
+  let content: string
+  try {
+    content = readFileSync(jsonl, 'utf8')
+  } catch {
+    return null
+  }
+  const inputs: number[] = []
+  let lastOut = 0
+  for (const line of content.split('\n')) {
+    if (line.trim() === '') continue
+    let entry: unknown
+    try {
+      entry = JSON.parse(line)
+    } catch {
+      return null
+    }
+    if (entry === null) continue
+    if (!isPlainObject(entry)) return null
+    if (entry['type'] !== 'assistant') continue
+    const message = entry['message']
+    if (message === null || message === undefined) continue
+    if (!isPlainObject(message)) return null
+    const usage = message['usage']
+    if (usage === null || usage === undefined) continue
+    if (!isPlainObject(usage)) return null
+    inputs.push(usageInput(usage))
+    lastOut = typeof usage['output_tokens'] === 'number' ? usage['output_tokens'] : 0
+  }
+  if (inputs.length === 0) return null
+  let peak = inputs[0]!
+  for (const value of inputs) if (value > peak) peak = value
+  return { used: inputs[inputs.length - 1]!, out: lastOut, peak }
+}
+
+/**
+ * The byte-exact per-teammate `tm ctx` line. `windowOverride` is `''`,
+ * `'200k'`, or `'1m'`. Soft-fails to a `? (...)` diagnostic so a
+ * `--all` fan-out keeps going.
+ */
+export function claudeCtxLine(
+  name: TeammateName,
+  windowOverride: string,
+  env: ClaudeCtxEnv,
+): string {
+  const sid = readSid(name)
+  if (sid === null) return `${name}: ? (no sid file)`
+
+  const recordedCwd = readIfNonEmpty(cwdFile(name))
+  const cwd =
+    recordedCwd !== null ? recordedCwd.replace(/\n+$/, '') : `${env.dispatcherDir}/${name}`
+  const jsonl = transcriptFile(env.projectsDir, cwd, sid)
+  if (!isRegularFile(jsonl)) return `${name}: ? (no transcript at ${jsonl})`
+
+  const usage = readCtxUsage(jsonl)
+  if (usage === null) return `${name}: ? (no assistant usage in transcript)`
+
+  const next = usage.used + usage.out
+  let window: number
+  let note: string
+  if (windowOverride === '1m') {
+    window = 1000000
+    note = 'flag'
+  } else if (windowOverride === '200k') {
+    window = 200000
+    note = 'flag'
+  } else if (usage.peak > 210000) {
+    window = 1000000
+    note = 'detected 1M'
+  } else {
+    window = 200000
+    note = 'assumed 200k'
+  }
+  const pct = Math.floor((usage.used * 100) / window)
+  const wlabel = window >= 1000000 ? '1M' : '200k'
+  return `${name}: ${usage.used} tokens · ~${next} next turn · ${pct}% of ${wlabel} (${note})`
+}
+
+/**
+ * Structured `ContextResult` for `ClaudeEngine.ctx`. Returns `kind:
+ * 'not-supported'` when the transcript or usage is unreadable — the
+ * verb-layer formatter renders the same `? (...)` line a future
+ * EngineRegistry dispatch would emit.
+ */
+export function claudeCtxUsage(name: TeammateName, env: ClaudeCtxEnv): ContextResult {
+  const sid = readSid(name)
+  if (sid === null) return { kind: 'not-supported', reason: `no sid file for ${name}` }
+  const recordedCwd = readIfNonEmpty(cwdFile(name))
+  const cwd =
+    recordedCwd !== null ? recordedCwd.replace(/\n+$/, '') : `${env.dispatcherDir}/${name}`
+  const jsonl = transcriptFile(env.projectsDir, cwd, sid)
+  if (!isRegularFile(jsonl)) {
+    return { kind: 'not-supported', reason: `no transcript at ${jsonl}` }
+  }
+  const usage = readCtxUsage(jsonl)
+  if (usage === null) {
+    return { kind: 'not-supported', reason: `no assistant usage in transcript for ${name}` }
+  }
+  const window = usage.peak > 210000 ? 1000000 : 200000
+  return {
+    kind: 'usage',
+    tokensUsed: usage.used,
+    tokensTotal: window,
+    pct: Math.floor((usage.used * 100) / window),
+  }
+}

package/src/engines/claude/doctor.ts

@@ -0,0 +1,202 @@
+/**
+ * `tm doctor` — a read-only environment self-check. Sections fire
+ * top-down: the `tm` executable, the dispatcher dir, tmux, the idle
+ * dir, the active teammate list, and the codex teammates. Soft-fails
+ * throughout (every probe is guarded) and always exits 0; output is
+ * meant to be eyeballed, not parsed.
+ *
+ * The path the "tm executable" section reports is the
+ * `<plugin-root>/bin/tm` launcher. The caller passes the resolved
+ * paths in (`tmWrapper`, `pluginJson`) because the relative-`../..`
+ * computation has to be done from a `src/*.ts` file at depth one
+ * inside the plugin root — engines/claude/doctor.ts sits three
+ * directories deeper, so the math does not work from here.
+ */
+
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+
+import { isDirectory } from './idle'
+import { iterTeammates } from './tmux'
+import { die } from './tmux'
+import { fmtLocalDateTime } from './clock'
+import { idleDir, TMUX_SESSION_PREFIX } from '../../persistence/paths'
+import {
+  isProcessAlive as codexProcessAlive,
+  listDaemons as listCodexDaemons,
+  readDaemonState as readCodexState,
+  reapDaemon as reapCodexDaemon,
+} from '../codex/supervisor'
+import { removeBaseRecord as removeCodexBaseRecord } from '../codex/persistence'
+import type { ClaudeVerbEnv } from './env'
+import type { TmResult } from '../../tm'
+
+export interface DoctorPaths {
+  /** Absolute path to the `<plugin-root>/bin/tm` launcher. */
+  tmWrapper: string
+  /** Absolute path to `<plugin-root>/.claude-plugin/plugin.json`. */
+  pluginJson: string
+}
+
+export async function claudeDoctor(
+  args: readonly string[],
+  env: ClaudeVerbEnv,
+  paths: DoctorPaths,
+): Promise<TmResult> {
+  if (args.length > 0) {
+    return die(`tm doctor: takes no arguments (got: ${args.join(' ')})`)
+  }
+
+  // The kv row: a 20-character padded label, then the value — matches
+  // `cmd_doctor`'s `printf '  %-20s%s\n'`. One source of truth here
+  // keeps alignment immune to label renames.
+  const kv = (label: string, value: string): string => {
+    const padded = `${label}:`.padEnd(20, ' ')
+    return `  ${padded}${value}\n`
+  }
+
+  let out = ''
+
+  // --- tm executable ---
+  const { tmWrapper, pluginJson } = paths
+  let version = 'unknown'
+  let pluginJsonPresent = false
+  try {
+    if (statSync(pluginJson).isFile()) {
+      pluginJsonPresent = true
+      const parsed = JSON.parse(readFileSync(pluginJson, 'utf8')) as { version?: unknown }
+      if (typeof parsed.version === 'string' && parsed.version.length > 0) {
+        version = parsed.version
+      }
+    }
+  } catch {
+    pluginJsonPresent = false
+  }
+  out += 'tm executable:\n'
+  out += kv('path', tmWrapper)
+  out += kv('version', version)
+  if (!pluginJsonPresent) out += kv('note', `plugin.json not found at ${pluginJson}`)
+  out += '\n'
+
+  // --- dispatcher dir ---
+  out += 'dispatcher dir:\n'
+  out += kv('resolved', env.dispatcherDir)
+  const envSet = process.env.TM_DISPATCHER_DIR
+  if (envSet !== undefined && envSet.length > 0) {
+    out += kv('TM_DISPATCHER_DIR', `set (= ${envSet})`)
+  } else {
+    out += kv(
+      'TM_DISPATCHER_DIR',
+      'unset — falling back to $PWD (run /claudemux:setup to inoculate against cwd drift)',
+    )
+  }
+  const pwd = process.cwd()
+  out += kv('$PWD', pwd)
+  if (env.dispatcherDir !== pwd) {
+    out += kv(
+      'status',
+      'DIVERGED — dispatcher dir != $PWD; env override is currently keeping tm correct despite the drifted PWD',
+    )
+  } else {
+    out += kv('status', 'matched')
+  }
+  if (!isDirectory(env.dispatcherDir)) {
+    out += kv('warning', `${env.dispatcherDir} does not exist as a directory`)
+  }
+  out += '\n'
+
+  // --- tmux ---
+  out += 'tmux:\n'
+  let tmuxVersionOk = false
+  let tmuxVersionLine = ''
+  try {
+    const versionResult = await env.runTmux(['-V'])
+    if (versionResult.code === 0) {
+      tmuxVersionOk = true
+      tmuxVersionLine = versionResult.stdout.split('\n')[0] ?? '?'
+    }
+  } catch {
+    tmuxVersionOk = false
+  }
+  if (!tmuxVersionOk) {
+    out += kv('installed', 'no (tmux not on PATH — claudemux teammate workflow needs it)')
+  } else {
+    out += kv('installed', `yes (${tmuxVersionLine})`)
+    let serverRunning = false
+    try {
+      serverRunning = (await env.runTmux(['info'])).code === 0
+    } catch {
+      serverRunning = false
+    }
+    if (serverRunning) out += kv('server', 'running')
+    else out += kv('server', "not running (no sessions exist yet — that's fine pre-spawn)")
+    const insideTmux = process.env.TMUX ?? ''
+    if (insideTmux.length > 0) out += kv('in tmux', `yes (TMUX=${insideTmux})`)
+    else out += kv('in tmux', 'no — tm is being run from outside a tmux session')
+  }
+  out += '\n'
+
+  // --- idle dir ---
+  out += `idle dir (${idleDir()}):\n`
+  if (isDirectory(idleDir())) {
+    let count = 0
+    try {
+      count = readdirSync(idleDir()).length
+    } catch {
+      count = 0
+    }
+    out += kv('exists', `yes (${count} file(s))`)
+  } else {
+    out += kv('exists', 'no — gets created on first tm spawn / scripts/setup.sh')
+  }
+  out += '\n'
+
+  // --- active teammates ---
+  // `cmd_doctor` projects each `tmux ls` row to its session field and
+  // prints it with a two-space indent — bare session name, not the
+  // full row.
+  out += 'active teammates:\n'
+  const sessionRows = (await iterTeammates(env.runTmux)).map(
+    (name) => `${TMUX_SESSION_PREFIX}${name}`,
+  )
+  if (sessionRows.length === 0) {
+    out += "  (none — use 'tm spawn <repo>' to launch one)\n"
+  } else {
+    out += kv('count', String(sessionRows.length))
+    for (const name of sessionRows) out += `  ${name}\n`
+  }
+  out += '\n'
+
+  // --- codex teammates ---
+  out += 'codex teammates:\n'
+  const codexNames = listCodexDaemons()
+  if (codexNames.length === 0) {
+    out += "  (none — use 'tm spawn <name> --engine codex' to launch one)\n"
+  } else {
+    const reaped: string[] = []
+    const live: { name: string; pid: number; startedAt: number }[] = []
+    for (const name of codexNames) {
+      const state = readCodexState(name)
+      if (state === null) {
+        reaped.push(name)
+        await reapCodexDaemon(name)
+        removeCodexBaseRecord(name)
+      } else if (!codexProcessAlive(state.pid)) {
+        reaped.push(name)
+        await reapCodexDaemon(name)
+        removeCodexBaseRecord(name)
+      } else {
+        live.push({ name, pid: state.pid, startedAt: state.startedAt })
+      }
+    }
+    out += kv('count', String(live.length))
+    for (const t of live) {
+      out += `  ${t.name} (pid=${t.pid}, started ${fmtLocalDateTime(t.startedAt)})\n`
+    }
+    if (reaped.length > 0) {
+      out += kv('reaped orphans', String(reaped.length))
+      for (const name of reaped) out += `  ${name}\n`
+    }
+  }
+
+  return { code: 0, stdout: out, stderr: '' }
+}

package/src/engines/claude/env.ts

@@ -0,0 +1,16 @@
+/**
+ * The environment a Claude-engine verb body needs at runtime. A subset
+ * of `NativeEnv` — only the fields the Claude bodies touch — so a
+ * future codex teammate registry change does not ripple through every
+ * verb module.
+ */
+
+import type { ColumnRunner } from '../../column'
+import type { TmuxRunner } from '../../tmux'
+
+export interface ClaudeVerbEnv {
+  readonly runTmux: TmuxRunner
+  readonly runColumn: ColumnRunner
+  readonly dispatcherDir: string
+  readonly projectsDir: string
+}