@excitedjs/tm 1.1.0

package/src/verbs/archive.ts

@@ -0,0 +1,211 @@
+/**
+ * `tm archive <id>` — move a finished task from the dispatcher's active
+ * ledger to its archive. Decision multi-engine-tui-architecture §"Target shape" puts `archive`
+ * in `verbs/` because it touches no teammate process; it edits two
+ * dispatcher-local markdown files under
+ * `~/.claude/projects/<encoded-dispatcher-dir>/memory/`. No engine is
+ * consulted.
+ *
+ * The verb cuts the `### <id>` block out of `active-dispatcher-tasks.md`,
+ * carries `repo / branch / intent` lines from the cut block, stamps the
+ * close date and the outcome read from stdin, and prepends a compressed
+ * entry to `dispatcher-tasks-archive.md` (seeded from `ARCHIVE_TEMPLATE`
+ * when absent). The behavior is byte-identical to the legacy
+ * `NATIVE_VERBS.archive` it replaces.
+ */
+
+import { readFileSync, statSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { encodeProjectDir } from '../persistence/paths'
+import type { TmResult } from '../tm'
+
+/** The seed `dispatcher-tasks-archive.md` written when the archive file does not exist yet. */
+const ARCHIVE_TEMPLATE = `${[
+  '---',
+  'name: dispatcher-tasks-archive',
+  'description: "On-demand archive of closed dispatcher tasks, compressed to outcome + artifacts. NOT a boot read — only consult when looking up past task history. Live in-flight tasks live in active-dispatcher-tasks.md."',
+  'metadata:',
+  '  node_type: memory',
+  '  type: project',
+  '---',
+  '',
+  '# Dispatcher task archive',
+  '',
+  'Closed tasks moved here from `active-dispatcher-tasks.md`, compressed to a',
+  'pointer + conclusion (not a knowledge base). Newest on top. Reusable analysis',
+  'that outlives a task should be promoted to its own memory file, not kept here.',
+  '',
+  '<!-- split by month (dispatcher-tasks-archive-YYYY-MM.md) if this file grows past a few hundred entries -->',
+].join('\n')}\n`
+
+/** `tm`'s `die`: one `tm: <message>` line on stderr, exit 1. */
+function die(message: string): TmResult {
+  return { code: 1, stdout: '', stderr: `tm: ${message}\n` }
+}
+
+/** Whether a path exists and is a regular file. */
+function isRegularFile(path: string): boolean {
+  try {
+    return statSync(path).isFile()
+  } catch {
+    return false
+  }
+}
+
+/** The current date as `YYYY-MM-DD` in local time. */
+function fmtLocalDate(): string {
+  const d = new Date()
+  const p = (n: number): string => String(n).padStart(2, '0')
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`
+}
+
+/** Split a ledger file into lines; a trailing newline does not add an empty final line. */
+function ledgerLines(content: string): string[] {
+  const lines = content.split('\n')
+  if (lines.length > 0 && lines[lines.length - 1] === '') lines.pop()
+  return lines
+}
+
+type ArchiveArgs = { id: string; status: string } | { error: TmResult }
+
+function parseArchiveArgs(args: readonly string[]): ArchiveArgs {
+  let id = ''
+  let status = ''
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!
+    if (arg === '--status') {
+      if (i + 1 >= args.length) return { error: { code: 1, stdout: '', stderr: '' } }
+      status = args[i + 1]!
+      i++
+    } else if (arg.startsWith('--status=')) {
+      status = arg.slice('--status='.length)
+    } else if (arg.startsWith('-')) {
+      return { error: die(`tm archive: unknown flag: ${arg}`) }
+    } else if (id === '') {
+      id = arg
+    } else {
+      return { error: die(`tm archive: unexpected arg: ${arg}`) }
+    }
+  }
+  return { id, status }
+}
+
+export interface ArchiveEnv {
+  /** The dispatcher directory — `~/.claude/projects/<encoded(this)>` holds the ledger. */
+  readonly dispatcherDir: string
+  /** The Claude Code projects root. */
+  readonly projectsDir: string
+}
+
+/** `tm archive` body. The stdin outcome is required; see the usage line for the form. */
+export async function archiveVerb(
+  args: readonly string[],
+  stdin: string | undefined,
+  env: ArchiveEnv,
+): Promise<TmResult> {
+  const parsed = parseArchiveArgs(args)
+  if ('error' in parsed) return parsed.error
+  const { id } = parsed
+  if (id === '') {
+    return die("usage: tm archive <id> [--status '<tag>']   (outcome text on stdin)")
+  }
+
+  const memoryDir = join(env.projectsDir, encodeProjectDir(env.dispatcherDir), 'memory')
+  const activePath = join(memoryDir, 'active-dispatcher-tasks.md')
+  const archivePath = join(memoryDir, 'dispatcher-tasks-archive.md')
+  if (!isRegularFile(activePath)) return die(`no active ledger at ${activePath}`)
+
+  const outcome = (stdin ?? '').replace(/\n+$/, '')
+  if (outcome.replace(/\s/g, '') === '') {
+    return die(`outcome text required on stdin, e.g.:  echo '...' | tm archive ${id}`)
+  }
+
+  const activeContent = readFileSync(activePath, 'utf8')
+  const activeLines = ledgerLines(activeContent)
+
+  let headerRe: RegExp
+  try {
+    headerRe = new RegExp(`^### ${id}(\\s|$)`)
+  } catch {
+    headerRe = /(?!)/
+  }
+  const headerLines = activeLines
+    .map((line, index) => (headerRe.test(line) ? index + 1 : 0))
+    .filter((lineNo) => lineNo > 0)
+  if (headerLines.length === 0) {
+    const available = activeLines
+      .map((line) => /^### [^ ]+/.exec(line)?.[0])
+      .filter((match): match is string => match != null)
+      .map((match) => match.slice('### '.length))
+      .join(' ')
+    return die(`id not found in active ledger: ${id}\n  available: ${available}`)
+  }
+  if (headerLines.length !== 1) {
+    return die(`id matches ${headerLines.length} entries in active ledger: ${id}`)
+  }
+
+  const start = headerLines[0]!
+  const total = (activeContent.match(/\n/g) ?? []).length
+  let end = total
+  for (let index = start; index < activeLines.length; index++) {
+    if (/^(### |## )/.test(activeLines[index]!)) {
+      end = index
+      break
+    }
+  }
+  const blockLines = activeLines.slice(start - 1, end)
+
+  let status = parsed.status
+  if (status === '') {
+    const tag = /\[(.+)\]\s*$/.exec(blockLines[0] ?? '')
+    status = tag ? tag[1]! : 'done'
+  }
+
+  const field = (name: string): string => {
+    const line = blockLines.find((candidate) => candidate.startsWith(`- ${name}:`))
+    if (line === undefined) return '(unknown)'
+    const value = line.slice(`- ${name}:`.length).replace(/^\s*/, '')
+    return value === '' ? '(unknown)' : value
+  }
+  const entry =
+    `### ${id}  [${status}]\n` +
+    `- repo/branch: ${field('repo')} / ${field('branch')}\n` +
+    `- intent: ${field('intent')}\n` +
+    `- outcome: ${outcome}\n` +
+    `- closed: ${fmtLocalDate()}`
+
+  const archiveContent = isRegularFile(archivePath)
+    ? readFileSync(archivePath, 'utf8')
+    : ARCHIVE_TEMPLATE
+  const archiveLines = ledgerLines(archiveContent)
+  let firstEntry = 0
+  for (let index = 0; index < archiveLines.length; index++) {
+    if (archiveLines[index]!.startsWith('### ')) {
+      firstEntry = index + 1
+      break
+    }
+  }
+  let newArchive: string
+  if (firstEntry > 0) {
+    const head =
+      firstEntry > 1 ? `${archiveLines.slice(0, firstEntry - 1).join('\n')}\n` : ''
+    const tail = `${archiveLines.slice(firstEntry - 1).join('\n')}\n`
+    newArchive = `${head}${entry}\n\n${tail}`
+  } else {
+    newArchive = `${archiveContent}\n${entry}\n`
+  }
+
+  const remaining = [...activeLines.slice(0, start - 1), ...activeLines.slice(end)]
+  const newActive = remaining.length > 0 ? `${remaining.join('\n')}\n` : ''
+
+  writeFileSync(archivePath, newArchive)
+  writeFileSync(activePath, newActive)
+  return {
+    code: 0,
+    stdout:
+      `archived ${id}  [${status}] -> dispatcher-tasks-archive.md  ` +
+      '(removed from active ledger)\n',
+    stderr: '',
+  }
+}

package/src/verbs/ask.ts

@@ -0,0 +1,29 @@
+/**
+ * `tm ask "<prompt>"` — borrow an idle named codex teammate, run one
+ * turn on a fresh thread, return the teammate. The "pool" is the
+ * spawned Codex-engine set; this verb does not name a teammate. Always
+ * routes into the codex driver, never into the tmux path.
+ *
+ * Codex-only by definition (decision multi-engine-tui-architecture): a claude teammate is named,
+ * so a "borrow from the pool" verb belongs to the engine whose
+ * teammates are pool-shaped.
+ */
+
+import { codexAsk } from '../engines/codex/verbs'
+import type { TmResult } from '../tm'
+
+export async function askVerb(args: readonly string[]): Promise<TmResult> {
+  if (args.length === 0) {
+    return { code: 1, stdout: '', stderr: 'tm: usage: tm ask "<prompt>"\n' }
+  }
+  if (args.length > 1) {
+    return {
+      code: 1,
+      stdout: '',
+      stderr:
+        `tm: tm ask: takes exactly one positional argument (the prompt) — ` +
+        `got ${args.length}\n`,
+    }
+  }
+  return codexAsk(args[0] ?? '')
+}

package/src/verbs/compact.ts

@@ -0,0 +1,25 @@
+/**
+ * `tm compact <name>` — manual context compaction. Decision multi-engine-tui-architecture
+ * §"Engine interface" uses this verb as the load-bearing example for
+ * the discriminated-result design: the Codex engine returns
+ * `{ kind: 'not-supported', reason: ... }` and the verb formatter
+ * prints the one-line reason at exit 0.
+ */
+
+import { formatCompact } from './format'
+import type { CompactRequest, TeammateName } from '../engines/types'
+import type { TmResult } from '../tm'
+import type { VerbContext } from './context'
+import { resolveTargetEngine } from './resolve'
+
+export async function compactVerb(
+  name: TeammateName,
+  ctx: VerbContext,
+  opts: { readonly timeoutMs: number | null } = { timeoutMs: null },
+): Promise<TmResult> {
+  const engine = await resolveTargetEngine(name, ctx)
+  if ('code' in engine) return engine
+
+  const req: CompactRequest = { name, timeoutMs: opts.timeoutMs }
+  return formatCompact(await engine.compact(req, ctx.engineContext))
+}

package/src/verbs/context.ts

@@ -0,0 +1,68 @@
+/**
+ * `VerbContext` — the dependency bundle every verb-layer default impl
+ * takes. Decision multi-engine-tui-architecture §"Verb is the abstraction" calls out the four
+ * verb-side primitives:
+ *
+ *  - `engines` — the read-only registry view; `lsVerb` / `statesVerb`
+ *    fan out over `registered()`.
+ *  - `router` — name → engine resolution; `statusVerb` / `killVerb` /
+ *    every single-teammate verb consults this. `null` is the
+ *    "no such teammate" case.
+ *  - `engineContext` — the shared environment every Engine method
+ *    receives; verbs pass it through unmodified.
+ *  - `identity` — the writer for the base `/tmp/teammate-<name>.json`
+ *    file; `killVerb` calls `remove()` after a successful kill so a
+ *    later `tm spawn` of the same name is not blocked by a stale
+ *    identity record.
+ *
+ * Phase 1 has no concrete engines and no real identity store; the
+ * verbs still type-check against this bundle, and the empty / no-op
+ * Phase 1 implementations land them on the "not found" branch.
+ */
+
+import type { ColumnRunner } from '../column'
+import type { EngineRegistryView } from '../engines/registry'
+import type { EngineContext, TeammateName } from '../engines/types'
+import type { TeammateRouter } from '../identity/router'
+
+/**
+ * Writer for the base TeammateRecord JSON. Decision multi-engine-tui-architecture's "identity-
+ * by-JSON" enforcement rule pins this as the only place that mutates
+ * `/tmp/teammate-<name>.json`; Phase 2 lands the production
+ * implementation under `persistence/identity-store.ts`.
+ */
+export interface IdentityStore {
+  /**
+   * Snapshot the live identity JSON into the archive directory. Called by
+   * `tm kill` before `remove(name)` so a later `tm resume <name> <sid>`
+   * or `tm history <name>` can recover cwd / repo / worktreeSlug /
+   * displayName for the killed teammate without the agent shelling into
+   * `/tmp`. No-op when there is no live record to archive.
+   */
+  archive(name: TeammateName): Promise<void>
+  /** Remove the identity JSON for `name`. Idempotent — missing file is OK. */
+  remove(name: TeammateName): Promise<void>
+}
+
+export interface VerbContext {
+  readonly engines: EngineRegistryView
+  readonly router: TeammateRouter
+  readonly engineContext: EngineContext
+  readonly identity: IdentityStore
+  /**
+   * Column-aligner. `tm states` owns the table layout, so the verb layer
+   * — not the engine — holds the `column -t` runner. Engines stay in
+   * the structured-row business.
+   */
+  readonly runColumn: ColumnRunner
+}
+
+/** Phase 1 no-op identity store — Phase 2 ships the real writer. */
+export class NoopIdentityStore implements IdentityStore {
+  async archive(_name: TeammateName): Promise<void> {
+    return
+  }
+  async remove(_name: TeammateName): Promise<void> {
+    return
+  }
+}

package/src/verbs/ctx.ts

@@ -0,0 +1,21 @@
+/**
+ * `tm ctx <name>` — report a teammate's context-window usage.
+ */
+
+import { formatContext } from './format'
+import type { ContextRequest, TeammateName } from '../engines/types'
+import type { TmResult } from '../tm'
+import type { VerbContext } from './context'
+import { resolveTargetEngine } from './resolve'
+
+export async function ctxVerb(
+  name: TeammateName,
+  ctx: VerbContext,
+  opts: { readonly windowOverride: '' | '200k' | '1m' },
+): Promise<TmResult> {
+  const engine = await resolveTargetEngine(name, ctx)
+  if ('code' in engine) return engine
+
+  const req: ContextRequest = { name, windowOverride: opts.windowOverride }
+  return formatContext(await engine.ctx(req, ctx.engineContext))
+}

package/src/verbs/format.ts

@@ -0,0 +1,213 @@
+/**
+ * Verb-layer formatting helpers — turn structured engine results into
+ * the `TmResult` (`{code, stdout, stderr}`) shape the CLI dispatcher
+ * emits. Decision multi-engine-tui-architecture §"Verb is the abstraction" makes the verb own
+ * exit codes and formatting; engines never decide either.
+ *
+ * Phase 1 lands minimal formatters good enough for the verb skeletons
+ * to compile and produce a sensible CLI surface for the
+ * "no engine registered" / "teammate not found" / "not supported"
+ * cases. Phase 2's `presentation/format-*.ts` modules will replace
+ * these as the rich formatting layer.
+ */
+
+import type {
+  CompactResult,
+  ContextResult,
+  HistoryResult,
+  KillResult,
+  RawTmResult,
+  ReloadResult,
+  ResumeResult,
+  TeammateListing,
+  TeammateName,
+  TeammateStatus,
+  TurnResult,
+} from '../engines/types'
+import { EXIT_SYNC_WAIT_EXPIRED, type TmResult } from '../tm'
+
+function rawTmResult(result: RawTmResult): TmResult | null {
+  return result.tmResult ?? null
+}
+
+/**
+ * The "no teammate by this name" verb outcome. Exit code 1 follows the
+ * convention every existing `die`-shaped verb uses today.
+ */
+export function teammateNotFound(name: TeammateName): TmResult {
+  return { code: 1, stdout: '', stderr: `tm: no such teammate: ${name}\n` }
+}
+
+/**
+ * The "no engine for this kind is registered in this process" verb
+ * outcome. Surfaces a missing Phase 2 wiring loudly rather than
+ * silently dispatching to nothing.
+ */
+export function noEngineRegistered(): TmResult {
+  return {
+    code: 1,
+    stdout: '',
+    stderr: 'tm: no engine registered in this process (Phase 2 wiring pending)\n',
+  }
+}
+
+/** Last path segment, or `-` when the path is empty / "/". */
+function repoLeaf(path: string): string {
+  if (path.length === 0) return '-'
+  const trimmed = path.replace(/\/+$/, '')
+  const slash = trimmed.lastIndexOf('/')
+  const leaf = slash >= 0 ? trimmed.slice(slash + 1) : trimmed
+  return leaf.length === 0 ? '-' : leaf
+}
+
+export function formatListing(rows: readonly TeammateListing[]): TmResult {
+  if (rows.length === 0) {
+    return {
+      code: 0,
+      stdout: "(no teammate sessions; use 'tm spawn <path>')\n",
+      stderr: '',
+    }
+  }
+  const lines = rows.map((r) =>
+    [
+      r.name,
+      repoLeaf(r.repo),
+      r.worktreeSlug ?? '-',
+      r.engine,
+      r.state,
+    ].join('\t'),
+  )
+  return { code: 0, stdout: `${lines.join('\n')}\n`, stderr: '' }
+}
+
+export function formatStatus(status: TeammateStatus): TmResult {
+  switch (status.kind) {
+    case 'present': {
+      // Phase 2a-1: the verb prints the captured pane text — same as the
+      // legacy `tm status` did via `tmux capture-pane`. Phase 2a-2 may
+      // prepend a structured header once the dispatcher consumers are
+      // aware of the format change.
+      return { code: 0, stdout: status.pane ?? '', stderr: '' }
+    }
+    case 'not-found':
+      return { code: 1, stdout: '', stderr: 'tm: status: not found\n' }
+    case 'failed':
+      return { code: 1, stdout: '', stderr: `tm: status: ${status.message}\n` }
+  }
+}
+
+export function formatKill(name: TeammateName, result: KillResult): TmResult {
+  switch (result.kind) {
+    case 'killed':
+      return {
+        code: 0,
+        stdout: `killed: ${name}\n`,
+        stderr: result.note ?? '',
+      }
+    case 'not-found':
+      return { code: 0, stdout: `not running: ${name}\n`, stderr: '' }
+    case 'failed':
+      return { code: 1, stdout: '', stderr: `tm: kill: ${result.message}\n` }
+  }
+}
+
+export function formatTurn(turn: TurnResult): TmResult {
+  const raw = rawTmResult(turn)
+  if (raw !== null) return raw
+  switch (turn.kind) {
+    case 'completed':
+      return { code: 0, stdout: turn.text.endsWith('\n') ? turn.text : `${turn.text}\n`, stderr: '' }
+    case 'failed':
+      return { code: 1, stdout: '', stderr: `tm: turn failed: ${turn.message}\n` }
+    case 'timed-out':
+      return {
+        code: EXIT_SYNC_WAIT_EXPIRED,
+        stdout: '',
+        stderr:
+          `tm: sync wait expired after ${turn.elapsedMs}ms (the teammate did ` +
+          `not return a Turn within the window; it is still running). ` +
+          `exit ${EXIT_SYNC_WAIT_EXPIRED}.\n`,
+      }
+    case 'not-supported':
+      return { code: 0, stdout: '', stderr: `  not supported: ${turn.reason}\n` }
+    case 'no-op':
+      return { code: 0, stdout: '', stderr: `  no-op: ${turn.reason}\n` }
+  }
+}
+
+export function formatCompact(result: CompactResult): TmResult {
+  const raw = rawTmResult(result)
+  if (raw !== null) return raw
+  switch (result.kind) {
+    case 'compacted':
+      return { code: 0, stdout: 'compacted\n', stderr: '' }
+    case 'not-needed':
+      return { code: 0, stdout: '', stderr: `  not needed: ${result.reason}\n` }
+    case 'not-supported':
+      return { code: 0, stdout: '', stderr: `  not supported: ${result.reason}\n` }
+    case 'failed':
+      return { code: 1, stdout: '', stderr: `tm: compact: ${result.message}\n` }
+  }
+}
+
+export function formatHistory(result: HistoryResult): TmResult {
+  const raw = rawTmResult(result)
+  if (raw !== null) return raw
+  switch (result.kind) {
+    case 'list': {
+      const lines = result.turns.map((t) => `#${t.index}\t${t.summary}`)
+      return { code: 0, stdout: `${lines.join('\n')}\n`, stderr: '' }
+    }
+    case 'detail':
+      return { code: 0, stdout: `#${result.turn.index}\t${result.turn.summary}\n`, stderr: '' }
+    case 'not-supported':
+      return { code: 0, stdout: '', stderr: `  not supported: ${result.reason}\n` }
+    case 'failed':
+      return { code: 1, stdout: '', stderr: `tm: history: ${result.message}\n` }
+  }
+}
+
+export function formatContext(result: ContextResult): TmResult {
+  const raw = rawTmResult(result)
+  if (raw !== null) return raw
+  switch (result.kind) {
+    case 'usage':
+      return {
+        code: 0,
+        stdout: `${result.tokensUsed} tokens · ${result.pct}% of ${result.tokensTotal}\n`,
+        stderr: '',
+      }
+    case 'not-supported':
+      return { code: 0, stdout: '', stderr: `  not supported: ${result.reason}\n` }
+    case 'failed':
+      return { code: 1, stdout: '', stderr: `tm: ctx: ${result.message}\n` }
+  }
+}
+
+export function formatResume(result: ResumeResult): TmResult {
+  const raw = rawTmResult(result)
+  if (raw !== null) return raw
+  switch (result.kind) {
+    case 'resumed':
+      return { code: 0, stdout: `resumed: ${result.checkpoint ?? ''}\n`, stderr: '' }
+    case 'not-found':
+      return { code: 1, stdout: '', stderr: `tm: resume: ${result.reason}\n` }
+    case 'not-supported':
+      return { code: 0, stdout: '', stderr: `  not supported: ${result.reason}\n` }
+    case 'failed':
+      return { code: 1, stdout: '', stderr: `tm: resume: ${result.message}\n` }
+  }
+}
+
+export function formatReload(result: ReloadResult): TmResult {
+  const raw = rawTmResult(result)
+  if (raw !== null) return raw
+  switch (result.kind) {
+    case 'reloaded':
+      return { code: 0, stdout: 'reloaded\n', stderr: '' }
+    case 'not-supported':
+      return { code: 0, stdout: '', stderr: `  not supported: ${result.reason}\n` }
+    case 'failed':
+      return { code: 1, stdout: '', stderr: `tm: reload: ${result.message}\n` }
+  }
+}