@excitedjs/tm 1.1.0

package/src/engines/git-worktree.ts

@@ -0,0 +1,137 @@
+/**
+ * Self-managed git worktree helpers — used by engines (currently
+ * Codex) that do not have a native worktree concept.
+ *
+ * The Claude engine relies on `claude --worktree <slug>` and does not
+ * call into this module. Codex has no equivalent flag, so claudemux
+ * drives `git worktree add` / `git worktree remove` itself; the
+ * resulting worktree layout matches Claude's:
+ *
+ *     <repo>/.claude/worktrees/<slug>     ← runtime cwd
+ *     branch: worktree-<slug>             ← matches `claude --worktree`
+ *
+ * Decisions:
+ *
+ *   - `baseRef = HEAD`. The user's pinned default for both engines;
+ *     Claude's side configures this through its `--settings` worktree
+ *     block, ours is just `git worktree add -b worktree-<slug> <path>
+ *     HEAD`.
+ *
+ *   - `--no-worktree` does not call these helpers; the daemon's cwd
+ *     stays at the repo root.
+ */
+
+import { existsSync } from 'node:fs'
+
+import { spawnCapture } from '../proc'
+import { worktreeBranchFor, worktreePathFor } from '../persistence/paths'
+
+/**
+ * Create the worktree for a Codex teammate. Returns `null` on
+ * success, or a human-readable error message describing why the
+ * `git worktree add` invocation failed.
+ *
+ * Idempotent: a worktree-path that already exists is accepted —
+ * either the previous spawn left a clean directory or the user
+ * pre-created it via `claude --worktree <slug>` from the same repo.
+ */
+export async function provisionCodexWorktree(
+  repo: string,
+  slug: string,
+): Promise<string | null> {
+  const path = worktreePathFor(repo, slug)
+  if (existsSync(path)) return null
+  const branch = worktreeBranchFor(slug)
+  const args = ['git', '-C', repo, 'worktree', 'add', '-b', branch, path, 'HEAD']
+  const result = await spawnCapture(args)
+  if (result.code === 0) return null
+  return (
+    `git worktree add failed (code ${result.code}): ` +
+    (result.stderr.trim() || result.stdout.trim() || `unknown failure running ${args.join(' ')}`)
+  )
+}
+
+/**
+ * Tear down the worktree for a Codex teammate. Returns the
+ * resolution:
+ *
+ *  - `removed` — the worktree was cleanly cleared AND the
+ *    `worktree-<slug>` branch was removable (either fully merged
+ *    into the parent HEAD or already gone elsewhere).
+ *  - `preserved-dirty` — `git status --porcelain` reported uncommitted
+ *    changes; the worktree and the branch are both kept.
+ *  - `preserved-unmerged` — the worktree itself had no uncommitted
+ *    changes, but its branch carries commits that are not merged
+ *    into the parent HEAD. The worktree was removed (its content
+ *    is reachable via the surviving branch ref); the branch is
+ *    preserved so the user's committed work does not become a
+ *    dangling object.
+ *  - `not-present` — nothing to remove.
+ *  - `failed` — some `git` invocation failed.
+ */
+export type CodexWorktreeReap =
+  | { kind: 'removed' }
+  | { kind: 'preserved-dirty'; path: string }
+  | { kind: 'preserved-unmerged'; path: string; branch: string }
+  | { kind: 'not-present' }
+  | { kind: 'failed'; message: string }
+
+export async function reapCodexWorktree(
+  repo: string,
+  slug: string,
+): Promise<CodexWorktreeReap> {
+  const path = worktreePathFor(repo, slug)
+  if (!existsSync(path)) return { kind: 'not-present' }
+  const status = await spawnCapture(['git', '-C', path, 'status', '--porcelain'])
+  if (status.code !== 0) {
+    return {
+      kind: 'failed',
+      message:
+        `git status failed (code ${status.code}): ${status.stderr.trim() || status.stdout.trim()}`,
+    }
+  }
+  if (status.stdout.trim().length > 0) {
+    return { kind: 'preserved-dirty', path }
+  }
+  const remove = await spawnCapture(['git', '-C', repo, 'worktree', 'remove', '--force', path])
+  if (remove.code !== 0) {
+    return {
+      kind: 'failed',
+      message:
+        `git worktree remove failed (code ${remove.code}): ${remove.stderr.trim() || remove.stdout.trim()}`,
+    }
+  }
+  // `provisionCodexWorktree` created the branch with `worktree add
+  // -b worktree-<slug>`; `git worktree remove` does NOT delete the
+  // branch ref. Use `git branch -d` (safe) — it refuses to delete a
+  // branch carrying commits not yet merged into HEAD, which is
+  // exactly the case where a force-delete would orphan committed
+  // user work into a dangling commit. On `-d` refusal, restore the
+  // worktree path (so the user can resume the conversation /
+  // recover from the branch) and report `preserved-unmerged`. If
+  // `-d` succeeds (branch was merged or already gone), the slug
+  // is now fully free for a subsequent same-name `tm spawn`.
+  const branch = worktreeBranchFor(slug)
+  const branchDelete = await spawnCapture(['git', '-C', repo, 'branch', '-d', branch])
+  if (branchDelete.code === 0) return { kind: 'removed' }
+  const stderr = branchDelete.stderr.trim()
+  // `not fully merged` is what `git branch -d` prints when refusing
+  // because of unmerged commits. If git failed for any *other*
+  // reason (e.g. the branch was already gone), the slug is still
+  // free, so treat it the same as `removed`.
+  if (!/not fully merged/i.test(stderr)) return { kind: 'removed' }
+  // The branch ref carries unmerged work. Recreate the worktree
+  // pointing back at it so the user can recover. If even this
+  // restore fails, the data is still safe at the branch ref — but
+  // we surface a `failed` so the user can intervene.
+  const restore = await spawnCapture(['git', '-C', repo, 'worktree', 'add', path, branch])
+  if (restore.code !== 0) {
+    return {
+      kind: 'failed',
+      message:
+        `branch '${branch}' has unmerged commits and the recovery worktree-restore failed: ` +
+        (restore.stderr.trim() || restore.stdout.trim()),
+    }
+  }
+  return { kind: 'preserved-unmerged', path, branch }
+}

package/src/engines/production.ts

@@ -0,0 +1,19 @@
+/**
+ * Production engine wiring for one `tm` process.
+ *
+ * Phase 2a registers the Claude engine; Phase 2b registers the Codex
+ * engine. Keep both registrations in this one invocation-scoped helper so
+ * verb defaults see the full fleet.
+ */
+
+import type { NativeEnv } from '../env'
+import { ClaudeEngine } from './claude/claude-engine'
+import { CodexEngine } from './codex/engine'
+import { EngineRegistry } from './registry'
+
+export function productionRegistry(env: NativeEnv): EngineRegistry {
+  const registry = new EngineRegistry()
+  registry.register(new ClaudeEngine(env))
+  registry.register(new CodexEngine())
+  return registry
+}

package/src/engines/registry.ts

@@ -0,0 +1,70 @@
+/**
+ * The engine registry — one place where every concrete engine
+ * registers itself, and every verb-layer default implementation pulls
+ * the engines it needs to fan out over.
+ *
+ * Decision multi-engine-tui-architecture §"Verb is the abstraction" leans on this seam: `tm ls`
+ * iterates `registered()` and concatenates `Engine.list()` rows; the
+ * status / kill verbs resolve a teammate's engine through the identity
+ * router (decision multi-engine-tui-architecture §"Engine identity is the JSON's `engine` field")
+ * and the registry hands back the implementation. Phase 1 ships the
+ * empty registry; Phase 2a registers the Claude engine, Phase 2b
+ * registers the Codex engine.
+ *
+ * The registry is invocation-scoped: each `tm` process creates one,
+ * the production wiring populates it, tests inject their own. There is
+ * no module-level singleton.
+ */
+
+import type { Engine } from './engine'
+import type { EngineKind } from './types'
+
+/**
+ * A read-only view of registered engines. Verb-layer default impls
+ * accept this view (not the mutable registry), so a verb cannot
+ * accidentally re-register an engine mid-dispatch.
+ */
+export interface EngineRegistryView {
+  /** Look up by kind; `undefined` when no engine of that kind is registered. */
+  get(kind: EngineKind): Engine | undefined
+  /** Every registered engine, in deterministic order (insertion order). */
+  registered(): readonly Engine[]
+  /** Every kind currently registered. */
+  kinds(): readonly EngineKind[]
+}
+
+/**
+ * The mutable registry. The production wiring constructs one of these,
+ * registers each engine implementation, then hands the view to the
+ * verb dispatcher.
+ */
+export class EngineRegistry implements EngineRegistryView {
+  private readonly engines: Map<EngineKind, Engine> = new Map()
+
+  /** Add an engine; throws if a kind is registered twice in one process. */
+  register(engine: Engine): void {
+    if (this.engines.has(engine.kind)) {
+      throw new Error(
+        `EngineRegistry.register: engine '${engine.kind}' is already registered in this process`,
+      )
+    }
+    this.engines.set(engine.kind, engine)
+  }
+
+  get(kind: EngineKind): Engine | undefined {
+    return this.engines.get(kind)
+  }
+
+  registered(): readonly Engine[] {
+    return Array.from(this.engines.values())
+  }
+
+  kinds(): readonly EngineKind[] {
+    return Array.from(this.engines.keys())
+  }
+}
+
+/** Convenience constructor for tests / empty production wiring. */
+export function emptyRegistry(): EngineRegistry {
+  return new EngineRegistry()
+}

package/src/engines/teammate-record.ts

@@ -0,0 +1,113 @@
+/**
+ * The single source of truth for a teammate's identity. Decision multi-engine-tui-architecture
+ * §"TeammateRecord — one base JSON, engine-private extensions, hooks-
+ * managed files left alone" collapses what `tm` itself writes and reads
+ * (engine, repo, cwd, worktreeSlug, createdAt, …) into one JSON at
+ * `/tmp/teammate-<name>.json`; engine-private state lives under the
+ * engine's persistence module; hooks-managed marker files (`.busy`,
+ * `.last`, `.sid`, `.ready`, idle marker) stay separate because Bash
+ * hooks cannot atomically rewrite JSON.
+ *
+ * `TeammateRecord` is the abstract base every per-engine record extends.
+ * It owns the JSON-serialised base fields plus the `markerPath(name)`
+ * builder (one named function, so the file shape is changed in one
+ * place — decision cross-process-cross-platform-invariants's path-builder discipline). A subclass declares
+ * its engine-private extension files via `engineExtensionFiles()`, which
+ * `tm doctor` consumes to enumerate everything to reap for a given
+ * teammate.
+ *
+ * Schema 2 — the name/repo decoupling cut. The teammate `name` is a
+ * flat opaque identifier; `repo` is the physical path of the source
+ * repository (recorded once at spawn); `cwd` is the runtime working
+ * directory (= `repo/.claude/worktrees/<worktreeSlug>` when a worktree
+ * is in use, `= repo` otherwise); `worktreeSlug` is the short name of
+ * the worktree under `.claude/worktrees/`, or `null` for
+ * `--no-worktree`.
+ */
+
+import type { EngineKind, TeammateName } from './types'
+
+/** Current on-disk schema for `/tmp/teammate-<name>.json`. */
+export const TEAMMATE_RECORD_SCHEMA = 2 as const
+
+/** The JSON shape `tm` writes at spawn and reads on every verb. */
+export interface TeammateRecordJson {
+  readonly schema: typeof TEAMMATE_RECORD_SCHEMA
+  readonly name: TeammateName
+  readonly engine: EngineKind
+  /** Physical path of the source repository (parent of any worktree). */
+  readonly repo: string
+  /**
+   * Runtime working directory the teammate process is launched in.
+   * Equal to `<repo>/.claude/worktrees/<worktreeSlug>` when a worktree
+   * is in use; equal to `repo` otherwise.
+   */
+  readonly cwd: string
+  /** Short name of the worktree under `.claude/worktrees/`; `null` for `--no-worktree`. */
+  readonly worktreeSlug: string | null
+  readonly createdAt: number
+  readonly displayName: string | null
+}
+
+/**
+ * Base carrier for a teammate identity. Subclasses live under
+ * `engines/<kind>/persistence.ts` and add engine-private file builders
+ * (e.g., `.cwd`, `.sid`, `/tmp/teammate-codex/<name>/socket`); the base
+ * fields are written once by the registry layer and never mutated.
+ */
+export abstract class TeammateRecord {
+  readonly schema: typeof TEAMMATE_RECORD_SCHEMA = TEAMMATE_RECORD_SCHEMA
+  readonly name: TeammateName
+  abstract readonly engine: EngineKind
+  readonly repo: string
+  readonly cwd: string
+  readonly worktreeSlug: string | null
+  readonly createdAt: number
+  readonly displayName: string | null
+
+  protected constructor(args: {
+    name: TeammateName
+    repo: string
+    cwd: string
+    worktreeSlug: string | null
+    createdAt: number
+    displayName: string | null
+  }) {
+    this.name = args.name
+    this.repo = args.repo
+    this.cwd = args.cwd
+    this.worktreeSlug = args.worktreeSlug
+    this.createdAt = args.createdAt
+    this.displayName = args.displayName
+  }
+
+  /**
+   * Absolute path of the base JSON file for this teammate. The single
+   * builder so the file shape changes in one place.
+   */
+  static markerPath(name: TeammateName): string {
+    return `/tmp/teammate-${name}.json`
+  }
+
+  /** Serialise this record's base fields to the on-disk JSON shape. */
+  toJson(): TeammateRecordJson {
+    return {
+      schema: this.schema,
+      name: this.name,
+      engine: this.engine,
+      repo: this.repo,
+      cwd: this.cwd,
+      worktreeSlug: this.worktreeSlug,
+      createdAt: this.createdAt,
+      displayName: this.displayName,
+    }
+  }
+
+  /**
+   * The engine-private files that belong to this teammate. `tm doctor`
+   * walks this list when reaping an orphaned identity. The base file
+   * (`/tmp/teammate-<name>.json`) is not part of the list — the
+   * registry layer owns it.
+   */
+  abstract engineExtensionFiles(): readonly string[]
+}

package/src/engines/types.ts

@@ -0,0 +1,334 @@
+/**
+ * The shared request / result / value types that the `Engine` interface
+ * and every verb-layer default implementation speak in.
+ *
+ * Decision multi-engine-tui-architecture §"Engine interface" and §"Capabilities are structured,
+ * not stringly-typed" anchor this file. Three rules carry through:
+ *
+ *  - Every operation result is a discriminated union keyed by `kind`, so
+ *    the verb formatter can `switch` exhaustively and TypeScript will
+ *    reject a missing case at compile time. There is no `string`
+ *    fallback on a capability slot; a future engine adding a mode bumps
+ *    the union here in one place.
+ *  - Every result includes a `not-supported` variant carrying a short
+ *    `reason` string. An engine that genuinely cannot perform a verb
+ *    still implements the method and returns this variant — the CLI
+ *    surface gives the agent a one-line "why", not a stack trace.
+ *  - Teammate names may contain `/` (decision multi-engine-tui-architecture §"Nested teammate
+ *    names"). Path builders treat the name as opaque; engine-specific
+ *    encoding (e.g., the Claude engine's tmux session name) lives behind
+ *    named path builders.
+ *
+ * Phase 1 lands this file as a contract. The engine implementations
+ * (Phase 2a for Claude, Phase 2b for Codex) consume it without
+ * touching it.
+ */
+
+import type { TmResult } from '../tm'
+
+/** The closed set of engine kinds. New kinds extend this union here. */
+export type EngineKind = 'claude' | 'codex'
+
+/**
+ * A teammate name as it appears on the CLI. Single-segment is the
+ * common case; nested segments (e.g., `flow/flow-1`) are allowed.
+ * Validation lives in `identity/name.ts` once it lands; this alias
+ * documents intent at the call sites.
+ */
+export type TeammateName = string
+
+/**
+ * Shared environment passed to every Engine method. Phase 2 will widen
+ * this with the production runtime (file system, process runner, clock,
+ * tmux adapter); Phase 1 keeps the surface minimal so engine stubs can
+ * already match the contract.
+ */
+export interface EngineContext {
+  /** Wall-clock reader — engines must not call `Date.now()` directly. */
+  now(): number
+  /** Process environment, scoped per invocation so tests can inject. */
+  env: NodeJS.ProcessEnv
+}
+
+/**
+ * Capabilities reported by an engine. Every slot is a discriminated
+ * literal union or a boolean — no `string` fallback. A verb that
+ * branches on a capability gets exhaustive `switch` checking.
+ *
+ * `atomicSend` is the literal `true`, not `boolean`: the verb contract
+ * demands atomic round-trips, and an engine that cannot do that does
+ * not qualify as a `tm` engine.
+ */
+export interface EngineCapabilities {
+  readonly atomicSend: true
+  readonly atomicSpawnPrompt: boolean
+  readonly compaction: 'manual' | 'auto' | 'unsupported'
+  readonly contextUsage: 'transcript-jsonl' | 'rpc-token-usage' | 'unsupported'
+  readonly history: 'transcript-files' | 'rpc-thread-list' | 'unsupported'
+  readonly memory: 'claude-project-memory' | 'engine-native' | 'unsupported'
+  readonly reload: 'prompt-command' | 'native-command' | 'unsupported'
+  readonly resume: 'transcript-id' | 'thread-id' | 'unsupported'
+  readonly detachedTurn: 'unsupported' | 'replayable' | 'best-effort-push'
+  readonly events: 'push' | 'synthesized' | 'none'
+}
+
+/** One typed item emitted within a turn (assistant text, tool call, …). */
+export type InteractionItem =
+  | { kind: 'assistant-text'; text: string }
+  | { kind: 'tool-call'; tool: string; argsJson: string }
+  | { kind: 'tool-result'; tool: string; ok: boolean; textOrJson: string }
+  | { kind: 'system-note'; text: string }
+
+// ─── Spawn ──────────────────────────────────────────────────────────────
+
+export interface SpawnRequest {
+  readonly name: TeammateName
+  /**
+   * Physical path of the source repository. Equal to `cwd` when
+   * `worktreeSlug` is `null` (`--no-worktree`); otherwise the parent
+   * of the worktree path.
+   */
+  readonly repo: string
+  /**
+   * Runtime working directory the engine launches the teammate in.
+   * `repo/.claude/worktrees/<worktreeSlug>` when a worktree is in use,
+   * `repo` otherwise.
+   */
+  readonly cwd: string
+  /** Short name of the worktree under `.claude/worktrees/`; `null` for `--no-worktree`. */
+  readonly worktreeSlug: string | null
+  /** Optional engine-specific resume checkpoint. */
+  readonly resumeCheckpoint: string | null
+  /** Optional first-turn prompt — when present, spawn is an atomic round-trip. */
+  readonly prompt: string | null
+  /** Optional caller-supplied wall-clock cap; `null` means unbounded. */
+  readonly timeoutMs: number | null
+  /** Human-readable display name for fleet listing; null falls back to `name`. */
+  readonly displayName: string | null
+}
+
+/**
+ * Temporary compatibility carrier for migrated Claude verbs whose public
+ * stdout/stderr contract is already pinned by conformance goldens. The
+ * structured fields stay authoritative for engine-neutral verbs; CLI
+ * formatters can return `tmResult` verbatim when it is present.
+ */
+export interface RawTmResult {
+  readonly tmResult?: TmResult
+}
+
+export type SpawnResult =
+  | ({ kind: 'spawned'; name: TeammateName; firstTurn: TurnResult | null } & RawTmResult)
+  | ({ kind: 'already-exists'; existingEngine: EngineKind } & RawTmResult)
+  | ({ kind: 'failed'; message: string } & RawTmResult)
+
+// ─── Send / Wait ────────────────────────────────────────────────────────
+
+export interface SendRequest {
+  readonly name: TeammateName
+  readonly prompt: string
+  readonly timeoutMs: number | null
+  readonly paneQuiet: boolean
+}
+
+export interface WaitRequest {
+  readonly name: TeammateName
+  /** A previous turn-id to recover from, when send/spawn aborted before reading. */
+  readonly recoverFor: string | null
+  readonly timeoutMs: number | null
+  readonly fresh: boolean
+  readonly paneQuiet: boolean
+}
+
+export type TurnResult =
+  | ({
+      kind: 'completed'
+      text: string
+      items: readonly InteractionItem[]
+      context: ContextResult | null
+    } & RawTmResult)
+  | ({ kind: 'failed'; message: string; recoverable: boolean } & RawTmResult)
+  | ({ kind: 'timed-out'; elapsedMs: number } & RawTmResult)
+  | ({ kind: 'not-supported'; reason: string } & RawTmResult)
+  | ({ kind: 'no-op'; reason: string } & RawTmResult)
+
+// ─── Kill ───────────────────────────────────────────────────────────────
+
+export interface KillRequest {
+  readonly name: TeammateName
+}
+
+export type KillResult =
+  | { kind: 'killed'; note?: string }
+  | { kind: 'not-found' }
+  | { kind: 'failed'; message: string }
+
+// ─── Compact / Resume / Reload ──────────────────────────────────────────
+
+export interface CompactRequest {
+  readonly name: TeammateName
+  readonly timeoutMs: number | null
+}
+
+export type CompactResult =
+  | ({ kind: 'compacted' } & RawTmResult)
+  | ({ kind: 'not-needed'; reason: string } & RawTmResult)
+  | ({ kind: 'not-supported'; reason: string } & RawTmResult)
+  | ({ kind: 'failed'; message: string } & RawTmResult)
+
+export interface ResumeRequest {
+  readonly name: TeammateName
+  /** Physical repo path the teammate is bound to; `null` when unknown. */
+  readonly repo: string | null
+  /** Absolute working directory used by engines that relaunch a process. */
+  readonly cwd: string | null
+  /** Worktree slug under `.claude/worktrees/`; `null` for `--no-worktree`. */
+  readonly worktreeSlug: string | null
+  /** Engine-specific identifier (Claude sid / Codex thread id); null lets the engine auto-pick when supported. */
+  readonly checkpoint: string | null
+  /** Optional first-turn prompt after the resumed teammate is relaunched. */
+  readonly prompt: string | null
+  /** Optional display relabel for engines that expose one. */
+  readonly displayName: string | null
+}
+
+export type ResumeResult =
+  | ({ kind: 'resumed'; checkpoint: string | null } & RawTmResult)
+  | ({ kind: 'not-found'; reason: string } & RawTmResult)
+  | ({ kind: 'not-supported'; reason: string } & RawTmResult)
+  | ({ kind: 'failed'; message: string } & RawTmResult)
+
+export interface ReloadRequest {
+  readonly name: TeammateName
+}
+
+export type ReloadResult =
+  | ({ kind: 'reloaded' } & RawTmResult)
+  | ({ kind: 'not-supported'; reason: string } & RawTmResult)
+  | ({ kind: 'failed'; message: string } & RawTmResult)
+
+// ─── Last / Ctx / History / Mem ────────────────────────────────────────
+
+export interface LastRequest {
+  readonly name: TeammateName
+  readonly verbose: boolean
+}
+
+export interface ContextRequest {
+  readonly name: TeammateName
+  readonly windowOverride: '' | '200k' | '1m'
+}
+
+export type ContextResult =
+  | ({ kind: 'usage'; tokensUsed: number; tokensTotal: number; pct: number } & RawTmResult)
+  | ({ kind: 'not-supported'; reason: string } & RawTmResult)
+  | ({ kind: 'failed'; message: string } & RawTmResult)
+
+export interface HistoryRequest {
+  readonly name: TeammateName
+  /** Absolute working directory used by engines whose history is keyed by cwd. */
+  readonly cwd: string | null
+  /** `null` = list view; non-null = engine-specific detail selector. */
+  readonly index: string | null
+}
+
+export type HistoryResult =
+  | ({ kind: 'list'; turns: readonly HistoryTurn[]; entries?: readonly HistoryListEntry[] } & RawTmResult)
+  | ({ kind: 'detail'; turn: HistoryTurn; items: readonly InteractionItem[] } & RawTmResult)
+  | ({ kind: 'not-supported'; reason: string } & RawTmResult)
+  | ({ kind: 'failed'; message: string } & RawTmResult)
+
+export interface HistoryListEntry {
+  readonly engine: EngineKind
+  readonly id: string
+  readonly mtimeMs: number
+  readonly size: number
+  readonly topic: string
+  readonly active: boolean
+}
+
+export interface HistoryTurn {
+  readonly index: number
+  readonly startedAt: number
+  readonly summary: string
+}
+
+export interface MemoryRequest {
+  readonly name: TeammateName
+}
+
+/**
+ * Plain-text payload — used for `mem`, `last`, and any other verb whose
+ * engine result is "here are some bytes, render them as-is".
+ */
+export type TextResult =
+  | ({ kind: 'text'; text: string } & RawTmResult)
+  | ({ kind: 'not-found'; reason: string } & RawTmResult)
+  | ({ kind: 'not-supported'; reason: string } & RawTmResult)
+  | ({ kind: 'failed'; message: string } & RawTmResult)
+
+// ─── Fleet visibility (list / status) ──────────────────────────────────
+
+/**
+ * One row of `tm ls` — the cross-engine listing default impl concatenates
+ * what every engine returns. Engines stay free to add engine-private
+ * fields by extending `extras`; the verb formatter ignores unknown keys.
+ */
+export interface TeammateListing {
+  readonly name: TeammateName
+  readonly engine: EngineKind
+  readonly state: 'idle' | 'busy' | 'unknown'
+  /** Physical repo path the teammate is bound to. */
+  readonly repo: string
+  /** Runtime working directory (worktree path or `repo`). */
+  readonly cwd: string
+  /** Worktree slug, or `null` for `--no-worktree`. */
+  readonly worktreeSlug: string | null
+  readonly displayName: string | null
+  readonly extras: Readonly<Record<string, string>>
+}
+
+export interface StatusRequest {
+  readonly name: TeammateName
+  /** Verb-layer hint for scrollback depth (status pane capture). */
+  readonly lines: number | null
+}
+
+export type TeammateStatus =
+  | {
+      kind: 'present'
+      name: TeammateName
+      engine: EngineKind
+      state: 'idle' | 'busy' | 'unknown'
+      cwd: string
+      pane: string | null
+      diagnostics: Readonly<Record<string, string>>
+    }
+  | { kind: 'not-found' }
+  | { kind: 'failed'; message: string }
+
+// ─── Doctor / Inspect ───────────────────────────────────────────────────
+
+export interface InspectRequest {
+  readonly name: TeammateName
+}
+
+export interface EngineSnapshot {
+  readonly engine: EngineKind
+  readonly name: TeammateName
+  /** Free-form key/value diagnostic dump. */
+  readonly fields: Readonly<Record<string, string>>
+}
+
+/** One section of the `tm doctor` output, contributed by one engine. */
+export interface DoctorSection {
+  readonly engine: EngineKind
+  readonly findings: readonly DoctorFinding[]
+}
+
+export interface DoctorFinding {
+  readonly severity: 'ok' | 'warn' | 'error'
+  readonly summary: string
+  /** Optional remediation hint shown after the summary line. */
+  readonly fix: string | null
+}