@excitedjs/tm 1.1.0

package/src/identity/uuid-prefix.ts

@@ -0,0 +1,40 @@
+/**
+ * Detect whether a user-supplied checkpoint argument looks like a partial
+ * canonical UUID — i.e. a string that, if extended, would form a valid
+ * `XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX` (8-4-4-4-12) id. Used by Claude
+ * and Codex resume to attach an actionable hint to the "no transcript" /
+ * "not a valid uuid" error instead of letting the caller chase the
+ * misleading "wrong repo" line.
+ *
+ * "Looks like a canonical prefix" means: not empty, every position is
+ * either lowercase hex or a `-` exactly where canonical UUIDs put one
+ * (positions 8, 13, 18, 23), and the input is strictly shorter than the
+ * 36-char canonical form. That matches the inputs `tm history`'s detail
+ * mode actually accepts (it does `startsWith` against canonical dashed
+ * ids), so the hint we emit — "Run 'tm history <repo> <input>'" — is
+ * always actionable.
+ *
+ * Notably rejected: the no-dash 32-hex form (history's startsWith would
+ * miss a dashed candidate), uppercase hex, dashes at non-canonical
+ * positions, and the full 36-char UUID (which the strict regex would
+ * have accepted upstream and never reached this helper).
+ */
+const DASH_POSITIONS: ReadonlySet<number> = new Set([8, 13, 18, 23])
+
+function isLowerHexChar(ch: string): boolean {
+  const code = ch.charCodeAt(0)
+  return (code >= 48 && code <= 57) || (code >= 97 && code <= 102)
+}
+
+export function looksLikeUuidPrefix(input: string): boolean {
+  if (input.length === 0 || input.length >= 36) return false
+  for (let i = 0; i < input.length; i++) {
+    const ch = input[i]!
+    if (DASH_POSITIONS.has(i)) {
+      if (ch !== '-') return false
+    } else {
+      if (!isLowerHexChar(ch)) return false
+    }
+  }
+  return true
+}

package/src/main.ts

@@ -0,0 +1,39 @@
+/**
+ * The process entrypoint — `tm`'s `argv` → `runCli` → `process` streams + exit code.
+ *
+ * Kept separate from [`cli.ts`](./cli.ts) so the library (`runCli`,
+ * `productionEnv`) imports cleanly into tests and harnesses without a side
+ * effect at module-load time. The `bin/tm` launcher execs Node against this
+ * file under `--experimental-transform-types`, so there is no build step
+ * between source and runtime.
+ */
+
+import { productionEnv, runCli, triggersHelp } from './cli'
+
+/** Read all of stdin; `undefined` on an interactive TTY so we never block on a never-arriving EOF. */
+async function readStdin(): Promise<string | undefined> {
+  if (process.stdin.isTTY) return undefined
+  const chunks: Buffer[] = []
+  for await (const chunk of process.stdin) chunks.push(chunk as Buffer)
+  return Buffer.concat(chunks).toString('utf8')
+}
+
+async function main(): Promise<void> {
+  const argv = process.argv.slice(2)
+  // `archive` is the only verb that reads stdin. Slurp it only when the
+  // invocation will actually reach the verb handler — `tm archive --help` /
+  // `tm archive -h` route to the help branch and read no stdin in bash, so
+  // we must skip the slurp there too or the launcher blocks indefinitely on
+  // any caller whose stdin is a pipe an upstream producer holds open.
+  const needsStdin = argv[0] === 'archive' && !triggersHelp(argv.slice(1))
+  const stdin = needsStdin ? await readStdin() : undefined
+  const result = await runCli(argv, productionEnv(), stdin)
+  if (result.stdout) process.stdout.write(result.stdout)
+  if (result.stderr) process.stderr.write(result.stderr)
+  process.exitCode = result.code
+}
+
+main().catch((err) => {
+  process.stderr.write(`[tm] ${err instanceof Error ? err.message : String(err)}\n`)
+  process.exitCode = 1
+})

package/src/persistence/atomic-file.ts

@@ -0,0 +1,74 @@
+/**
+ * Atomic file primitives.
+ *
+ * Decision multi-engine-tui-architecture §"TeammateRecord" gives the registry layer one rule: writes
+ * to `/tmp/teammate-<name>.json` are atomic, so a verb that reads the file
+ * mid-write never sees a half-written record. Atomic on POSIX is
+ * write-tmp-then-rename(2): a rename onto an existing path is a single
+ * dentry swap and another reader observes either the old contents or the
+ * new contents, never a torn write.
+ *
+ * `reserveExclusive` is the matching primitive for the spawn path: create
+ * the marker with `O_CREAT | O_EXCL` so a second concurrent `tm spawn` of
+ * the same name fails immediately. The registry layer uses this to enforce
+ * the "cross-engine name reuse is forbidden" rule (decision codex-engine-flag §4 carried
+ * forward by multi-engine-tui-architecture).
+ *
+ * Both functions go through this module rather than scattering
+ * `writeFileSync` calls at the use sites — the next refactor that wants to
+ * swap in `fs/promises` or add fsync semantics changes one file.
+ */
+
+import {
+  closeSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs'
+import { dirname } from 'node:path'
+
+/**
+ * Write `content` to `path` atomically. The path's directory is created if
+ * it doesn't exist. Concurrent readers see either the old contents (if any)
+ * or the new contents — never a partial write.
+ */
+export function atomicWrite(path: string, content: string): void {
+  mkdirSync(dirname(path), { recursive: true })
+  const tmp = `${path}.tmp.${process.pid}.${Date.now()}`
+  writeFileSync(tmp, content)
+  renameSync(tmp, path)
+}
+
+/** Read a file; return `null` if it does not exist. Any other error throws. */
+export function readIfPresent(path: string): string | null {
+  try {
+    return readFileSync(path, 'utf8')
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return null
+    throw err
+  }
+}
+
+/**
+ * Create the file with content using `O_CREAT | O_EXCL` — fails with `EEXIST`
+ * if the file already exists. The single-step exclusive create is the
+ * registry layer's "reserve this name" primitive: a second concurrent spawn
+ * of the same teammate cannot race past this point.
+ */
+export function reserveExclusive(path: string, content: string): void {
+  mkdirSync(dirname(path), { recursive: true })
+  const fd = openSync(path, 'wx')
+  try {
+    writeFileSync(fd, content)
+  } finally {
+    closeSync(fd)
+  }
+}
+
+/** Remove the file if it exists; no error if it doesn't. */
+export function removeIfPresent(path: string): void {
+  rmSync(path, { force: true })
+}

package/src/persistence/identity-store.ts

@@ -0,0 +1,294 @@
+/**
+ * The identity store — the one place that writes and reads
+ * `/tmp/teammate-<name>.json`. Decision multi-engine-tui-architecture §"TeammateRecord" anchors this
+ * file as the single source of truth for the base `TeammateRecord`, and
+ * §"Enforcement against silent regression" pins the constraint: no other
+ * file in `plugins/claudemux/src/` may touch the JSON marker.
+ *
+ * Three surfaces matter:
+ *
+ *  - `reserve(record)` is the spawn-time write. It uses `O_CREAT | O_EXCL`
+ *    against `/tmp/teammate-<name>.json`; a second concurrent `tm spawn`
+ *    of the same name fails with `EEXIST`, which the verb formats as a
+ *    "name already taken" error. Decision multi-engine-tui-architecture §"Engine identity is the
+ *    JSON's `engine` field" makes this the authoritative race winner —
+ *    whichever engine reserves first owns the name, the loser sees
+ *    `already-exists`. The reservation is atomic enough on POSIX rename
+ *    semantics that a `tm spawn ... --engine claude` on one terminal
+ *    and a `tm spawn ... --engine codex` on another in the same
+ *    millisecond never both succeed.
+ *
+ *  - `read(name)` is the per-verb identity lookup. The router calls it
+ *    once per CLI invocation to map a teammate name to its engine kind.
+ *    Returns `null` for "no such teammate" (the data outcome, not an
+ *    error).
+ *
+ *  - `list()` enumerates every reserved teammate by reading
+ *    `/tmp/teammate-*.json`. Decision multi-engine-tui-architecture §"Verb is the abstraction"
+ *    relies on this for `tm ls`'s engine-agnostic listing — the verb
+ *    asks for "every teammate identity" without knowing per-engine
+ *    persistence shapes.
+ *
+ *  - `remove(name)` is `tm kill`'s identity bookkeeping. The verb calls
+ *    it after a successful kill so a later `tm spawn` of the same name
+ *    is not blocked by a stale identity file.
+ */
+
+import { readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+import {
+  atomicWrite,
+  readIfPresent,
+  removeIfPresent,
+  reserveExclusive,
+} from './atomic-file'
+import {
+  TEAMMATE_RECORD_SCHEMA,
+  type TeammateRecordJson,
+} from '../engines/teammate-record'
+import type { EngineKind, TeammateName } from '../engines/types'
+
+/**
+ * The directory the identity files live in. Defaults to `/tmp` (the
+ * cross-process protocol root); tests point this at a fresh temp
+ * directory via `CLAUDEMUX_IDENTITY_ROOT` so a unit test can drive
+ * `reserve` / `read` / `list` without colliding with real dispatcher
+ * state. Resolved per call so a test that sets the env var inside
+ * `beforeEach` is honoured by code paths that captured the module
+ * earlier.
+ */
+function identityRoot(): string {
+  return process.env['CLAUDEMUX_IDENTITY_ROOT'] || '/tmp'
+}
+
+/** Absolute path of the identity JSON for a teammate. */
+export function identityFile(name: TeammateName): string {
+  return `${identityRoot()}/teammate-${name}.json`
+}
+
+/**
+ * Directory holding archived identity records — written when `tm kill`
+ * tears down a teammate, so a later `tm resume <name> <sid>` or
+ * `tm history <name>` can look up the killed teammate's cwd / repo /
+ * worktreeSlug / displayName without the agent reading `/tmp` files
+ * by hand.
+ *
+ * Lives under `identityRoot()` so `CLAUDEMUX_IDENTITY_ROOT` covers
+ * both the live and archived sides for tests. The directory name has
+ * no `.json` suffix, so `TOP_LEVEL_FILENAME` skips it and `list()`
+ * never enumerates archived records as live teammates.
+ */
+function archiveDir(): string {
+  return join(identityRoot(), 'teammate-archive')
+}
+
+/** Absolute path of the archived identity JSON for a teammate. */
+export function archivedIdentityFile(name: TeammateName): string {
+  return join(archiveDir(), `${name}.json`)
+}
+
+/** Regex pinning the top-level identity-file name shape; capture group 1 is the name. */
+const TOP_LEVEL_FILENAME = /^teammate-(.+)\.json$/
+
+export type ReserveResult =
+  | { kind: 'reserved' }
+  | { kind: 'taken'; existing: TeammateRecordJson }
+  | { kind: 'failed'; message: string }
+
+function sleepSync(ms: number): void {
+  const signal = new Int32Array(new SharedArrayBuffer(4))
+  Atomics.wait(signal, 0, 0, ms)
+}
+
+function readReservedRecord(name: TeammateName): TeammateRecordJson | null {
+  const deadline = Date.now() + 50
+  let existing = read(name)
+  while (existing === null && Date.now() < deadline) {
+    sleepSync(1)
+    existing = read(name)
+  }
+  return existing
+}
+
+/**
+ * Atomically reserve a teammate name. The exclusive create fails with
+ * `EEXIST` if the file already exists — that case is mapped to `taken` and
+ * the existing record is read so the verb can format an "already-exists"
+ * error that names which engine owns the slot.
+ */
+export function reserve(record: TeammateRecordJson): ReserveResult {
+  const path = identityFile(record.name)
+  try {
+    reserveExclusive(path, `${JSON.stringify(record, null, 2)}\n`)
+    return { kind: 'reserved' }
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'EEXIST') {
+      const existing = readReservedRecord(record.name)
+      if (existing === null) {
+        return { kind: 'failed', message: 'EEXIST on identity file but record could not be read back' }
+      }
+      return { kind: 'taken', existing }
+    }
+    return { kind: 'failed', message: err instanceof Error ? err.message : String(err) }
+  }
+}
+
+/**
+ * Rewrite an existing teammate identity record atomically — used by
+ * `commit` after a `reserve` when the engine wants to persist data computed
+ * after the reservation (Phase 2a does not need this; reserved here for the
+ * hook on `/clear` flow where the recorded fields stabilise post-spawn).
+ */
+export function write(record: TeammateRecordJson): void {
+  atomicWrite(identityFile(record.name), `${JSON.stringify(record, null, 2)}\n`)
+}
+
+/** Read an identity record; `null` for "no such teammate". */
+export function read(name: TeammateName): TeammateRecordJson | null {
+  const raw = readIfPresent(identityFile(name))
+  if (raw === null) return null
+  return parse(raw)
+}
+
+/** Remove the identity file; idempotent. */
+export function remove(name: TeammateName): void {
+  removeIfPresent(identityFile(name))
+}
+
+/**
+ * Snapshot the live identity record to the archive directory. Called
+ * by `tm kill` immediately before the live record is removed; after
+ * this call `readArchived(name)` returns the same record that
+ * `read(name)` returned just before the kill.
+ *
+ * No-op when there is no live record — `tm kill` running on a name
+ * with only a stale tmux session leaves nothing to archive, and the
+ * archive directory stays as it was (carrying the previous kill's
+ * snapshot if any). Returns whether anything was archived, so the
+ * verb layer can tell apart "archived a real identity" from
+ * "nothing to archive".
+ */
+export function archive(name: TeammateName): boolean {
+  const raw = readIfPresent(identityFile(name))
+  if (raw === null) return false
+  atomicWrite(archivedIdentityFile(name), raw)
+  return true
+}
+
+/**
+ * Read a teammate's archived record — what was on disk the last time
+ * `tm kill` archived this name. Returns `null` for "no such archive"
+ * (never killed under this scheme, or removed by `removeArchived`).
+ */
+export function readArchived(name: TeammateName): TeammateRecordJson | null {
+  const raw = readIfPresent(archivedIdentityFile(name))
+  if (raw === null) return null
+  return parse(raw)
+}
+
+/** Remove the archived identity file; idempotent. */
+export function removeArchived(name: TeammateName): void {
+  removeIfPresent(archivedIdentityFile(name))
+}
+
+/**
+ * Enumerate every reserved teammate. Schema 2 made names flat (no `/`),
+ * so only the top-level `/tmp/teammate-*.json` files need scanning.
+ *
+ * The Codex engine's per-teammate registry directory
+ * (`/tmp/teammate-codex/<name>/`) is a directory, not a `*.json` file,
+ * so it does not match `TOP_LEVEL_FILENAME` and is skipped silently.
+ *
+ * Unparseable files are skipped (the caller does not get a partial
+ * record). A schema=1 record on disk parses as `null` (no
+ * back-compat read in schema 2's one-step cut) and is treated the
+ * same as a missing teammate — the verb that reads it will surface
+ * the migration error.
+ */
+export function list(): readonly TeammateRecordJson[] {
+  const out: TeammateRecordJson[] = []
+  let entries: string[]
+  try {
+    entries = readdirSync(identityRoot())
+  } catch {
+    return []
+  }
+  for (const entry of entries) {
+    const top = entry.match(TOP_LEVEL_FILENAME)
+    if (top === null) continue
+    let info: ReturnType<typeof statSync>
+    try {
+      info = statSync(join(identityRoot(), entry))
+    } catch {
+      continue
+    }
+    if (!info.isFile()) continue
+    const raw = readIfPresent(join(identityRoot(), 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
+ * name/repo decoupling cut — a schema=1 record parses as `null` (no
+ * silent back-compat read; the user is expected to `tm kill` legacy
+ * teammates before upgrading).
+ */
+function parse(raw: string): TeammateRecordJson | null {
+  let value: unknown
+  try {
+    value = JSON.parse(raw)
+  } catch {
+    return null
+  }
+  if (typeof value !== 'object' || value === null) return null
+  const obj = value as Record<string, unknown>
+  if (obj['schema'] !== TEAMMATE_RECORD_SCHEMA) return null
+  if (typeof obj['name'] !== 'string') return null
+  if (typeof obj['engine'] !== 'string') return null
+  if (typeof obj['repo'] !== 'string') return null
+  if (typeof obj['cwd'] !== 'string') return null
+  if (typeof obj['createdAt'] !== 'number') return null
+  const worktreeSlug = obj['worktreeSlug']
+  if (worktreeSlug !== null && typeof worktreeSlug !== 'string') return null
+  const displayName = obj['displayName']
+  if (displayName !== null && typeof displayName !== 'string') return null
+  // The engine union is not validated against EngineKind here — an unknown
+  // engine kind on disk is "no such teammate from this build's view"
+  // (the router maps it through the registry, which will return undefined
+  // and the verb formats it as not-found).
+  return {
+    schema: TEAMMATE_RECORD_SCHEMA,
+    name: obj['name'],
+    engine: obj['engine'] as EngineKind,
+    repo: obj['repo'],
+    cwd: obj['cwd'],
+    worktreeSlug: worktreeSlug as string | null,
+    createdAt: obj['createdAt'],
+    displayName: displayName as string | null,
+  }
+}
+
+/**
+ * Read the on-disk JSON for a teammate without enforcing schema
+ * version. Returns the `schema` field as a number when present —
+ * used by the dispatch layer to detect a legacy schema=1 record and
+ * print a migration hint instead of silently treating it as missing.
+ */
+export function readRawSchema(name: TeammateName): number | null {
+  const raw = readIfPresent(identityFile(name))
+  if (raw === null) return null
+  try {
+    const value = JSON.parse(raw) as unknown
+    if (typeof value !== 'object' || value === null) return null
+    const schema = (value as Record<string, unknown>)['schema']
+    return typeof schema === 'number' ? schema : null
+  } catch {
+    return null
+  }
+}

package/src/persistence/identity-writer.ts

@@ -0,0 +1,28 @@
+/**
+ * `IdentityStoreWriter` — the verb-layer-facing seam for the identity
+ * file. Decision multi-engine-tui-architecture §"Verb is the abstraction" pulls `VerbContext`'s
+ * `identity` field out as an interface so the verb code does not import
+ * the persistence module directly; the Phase 1 `NoopIdentityStore` lives
+ * in `verbs/context.ts`, and Phase 2a's production implementation lives
+ * here.
+ *
+ * The only mutation verbs trigger is `remove(name)` — `killVerb` calls it
+ * after a successful kill so a later `tm spawn` of the same name is not
+ * blocked by a stale record. Spawn-time `reserve` and per-verb reads go
+ * through `persistence/identity-store.ts` directly (the verb file owns
+ * the rest of the spawn flow).
+ */
+
+import { archive as archiveIdentity, remove as removeIdentity } from './identity-store'
+import type { IdentityStore } from '../verbs/context'
+import type { TeammateName } from '../engines/types'
+
+/** Production `IdentityStore` — archives + deletes the JSON file. Idempotent. */
+export class ProductionIdentityStore implements IdentityStore {
+  async archive(name: TeammateName): Promise<void> {
+    archiveIdentity(name)
+  }
+  async remove(name: TeammateName): Promise<void> {
+    removeIdentity(name)
+  }
+}

package/src/persistence/paths.ts

@@ -0,0 +1,138 @@
+/**
+ * Path builders for every cross-process file the core touches.
+ *
+ * Path-builder discipline (repo CLAUDE.md, decision cross-process-cross-platform-invariants): every path under
+ * `/tmp/teammate-*`, `/tmp/claude-idle/*`, and Claude Code's project-dir root
+ * is constructed by a named function here — never by string concatenation at
+ * a use site. The `/tmp` protocol is the coupling layer between `tm`, the
+ * Bash hooks, and this core; spreading its shape across literals turns the
+ * next schema change into a non-atomic multi-file sweep.
+ *
+ * The hooks are Bash and cannot import this module, so they re-declare the
+ * same builders inline (`hooks/on-stop.sh`, `hooks/on-busy.sh`). The shapes
+ * here must stay byte-for-byte identical to those — see
+ * `.agents/domains/cross-process-protocol.md` for the contract.
+ */
+
+import { join } from 'node:path'
+import type { TeammateName } from '../engines/types'
+
+/** The root directory the Claude engine's extension files live in. */
+const TEAMMATE_ROOT = '/tmp'
+
+/** Root of the per-sid idle/busy/last markers the Claude Code hooks maintain. */
+export function idleDir(): string {
+  return '/tmp/claude-idle'
+}
+
+/** The bare `<sid>` marker — touched by `on-stop.sh` when a turn ends. */
+export function idleMarkerFor(sid: string): string {
+  return join(idleDir(), sid)
+}
+
+/** The `<sid>.busy` marker — present while a session is mid-turn. */
+export function busyMarkerFor(sid: string): string {
+  return join(idleDir(), `${sid}.busy`)
+}
+
+/** The `<sid>.last` file — text of the session's last assistant turn. */
+export function lastFileFor(sid: string): string {
+  return join(idleDir(), `${sid}.last`)
+}
+
+/** `/tmp/teammate-<name>.cwd` — written at spawn; read by SessionStart hook. */
+export function cwdFile(name: TeammateName): string {
+  return join(TEAMMATE_ROOT, `teammate-${name}.cwd`)
+}
+
+/** `/tmp/teammate-<name>.sid` — current session id; updated by SessionStart on `/clear`. */
+export function sidFile(name: TeammateName): string {
+  return join(TEAMMATE_ROOT, `teammate-${name}.sid`)
+}
+
+/** `/tmp/teammate-<name>.ready` — touched by SessionStart; cleared before spawn. */
+export function readyFile(name: TeammateName): string {
+  return join(TEAMMATE_ROOT, `teammate-${name}.ready`)
+}
+
+/** `/tmp/teammate-<name>.send-at` — touched per send; read by the pane-quiet wait fallback. */
+export function sendAtFile(name: TeammateName): string {
+  return join(TEAMMATE_ROOT, `teammate-${name}.send-at`)
+}
+
+/** The session-name prefix every tmux teammate session carries. */
+export const TMUX_SESSION_PREFIX = 'teammate-'
+
+/**
+ * Compose a teammate name into its tmux session name. Schema 2 made
+ * names flat, so the prefix is the only transformation.
+ *
+ * Example: `flow-auth-7d3a` → `teammate-flow-auth-7d3a`.
+ */
+export function tmuxSessionName(name: TeammateName): string {
+  return `${TMUX_SESSION_PREFIX}${name}`
+}
+
+/**
+ * Recover the teammate name from a tmux session string, or `null` if
+ * the session does not carry the teammate prefix. Schema 2's flat
+ * names make this an exact round-trip.
+ */
+export function decodeTmuxSessionName(session: string): string | null {
+  if (!session.startsWith(TMUX_SESSION_PREFIX)) return null
+  return session.slice(TMUX_SESSION_PREFIX.length)
+}
+
+/**
+ * The on-disk worktree path for a teammate. Mirrors Claude Code's
+ * `claude --worktree <slug>` layout — `<repo>/.claude/worktrees/<slug>`
+ * — so the Claude engine's pre-spawn `.cwd` write and the Codex
+ * engine's self-managed `git worktree add` use the same builder.
+ */
+export function worktreePathFor(repo: string, slug: string): string {
+  return `${repo}/.claude/worktrees/${slug}`
+}
+
+/**
+ * The git branch name `claude --worktree <slug>` creates. Codex's
+ * self-managed `git worktree add -b` uses the same branch name so a
+ * teammate's worktree layout looks identical whichever engine owns it.
+ */
+export function worktreeBranchFor(slug: string): string {
+  return `worktree-${slug}`
+}
+
+/** Per-teammate file fan-out for the Claude engine. */
+export interface ClaudeTeammateExtension {
+  readonly cwd: string
+  readonly sid: string
+  readonly ready: string
+  readonly sendAt: string
+}
+
+/** Materialise the Claude engine's extension paths for one teammate name. */
+export function claudeExtensionFor(name: TeammateName): ClaudeTeammateExtension {
+  return {
+    cwd: cwdFile(name),
+    sid: sidFile(name),
+    ready: readyFile(name),
+    sendAt: sendAtFile(name),
+  }
+}
+
+/**
+ * Encode a filesystem path into Claude Code's project-dir segment — the name
+ * of the directory under `~/.claude/projects/` that holds a cwd's transcripts.
+ *
+ * Claude Code derives that name by replacing every character that is not
+ * ASCII-alphanumeric or `-` with `-`. The rule was probed empirically: cwds
+ * containing `_`, `+`, `.`, `,`, `:`, `!`, `@`, `;`, or a literal space all
+ * land at the same `-bar` directory; only `A-Z`, `a-z`, `0-9`, and `-` survive
+ * verbatim. This is an Anthropic-controlled contract, and this is its one
+ * source of truth on the TypeScript side (decision cross-process-cross-platform-invariants): every site that
+ * locates a project dir routes through here, or the same repo ends up
+ * addressed by two different strings.
+ */
+export function encodeProjectDir(cwd: string): string {
+  return cwd.replace(/[^A-Za-z0-9-]/g, '-')
+}

package/src/plugin-root.ts

@@ -0,0 +1,26 @@
+/**
+ * `<plugin-root>/bin/tm` and `<plugin-root>/.claude-plugin/plugin.json`
+ * path computation, in one place.
+ *
+ * This file lives at `src/plugin-root.ts`; the single-`..` walk from its
+ * `import.meta.url` lands at `plugins/claudemux/` regardless of how the
+ * launcher invoked Node, so callers do not have to think about it.
+ */
+
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/** Absolute path to `<plugin-root>/bin/tm`, the user-facing launcher. */
+export function tmWrapperPath(): string {
+  return join(pluginRoot(), 'bin', 'tm')
+}
+
+/** Absolute path to `<plugin-root>/.claude-plugin/plugin.json`. */
+export function pluginJsonPath(): string {
+  return join(pluginRoot(), '.claude-plugin', 'plugin.json')
+}
+
+function pluginRoot(): string {
+  const moduleDir = dirname(fileURLToPath(import.meta.url))
+  return join(moduleDir, '..')
+}