@sjawhar/claude-envoy 0.0.0 → 1.1.0

package/src/replay-state.ts

@@ -0,0 +1,97 @@
+// One session's delivery record, in one file per session id under `CLAUDE_PLUGIN_DATA`: the
+// replay engine's (`@legion/envoy-client/replay`: its cursors, the subjects it follows and the
+// frames it was shown in the last 72 hours), and consumer delivery's
+// (`@legion/envoy-client/consumer-delivery`: the resume point and when each topic was first
+// followed). Claude Code can resume a session at any later time, so no sweep prunes these files;
+// each holds only cursors, followed subjects, a resume point and at most 72 hours of ledger,
+// since the engine drops older ledger entries before every write.
+import { readFile } from "node:fs/promises"
+import { join } from "node:path"
+import {
+  type ConsumerDeliverySnapshot,
+  ConsumerDeliverySnapshotSchema,
+} from "@legion/envoy-client/consumer-delivery"
+import { hasErrnoCode } from "@legion/envoy-client/errors"
+import { type ReplaySnapshot, ReplaySnapshotSchema } from "@legion/envoy-client/replay"
+import type { z } from "zod"
+import { writeAtomicStateFile } from "./session-state"
+
+/**
+ * A session's file: the replay snapshot, and the consumer delivery snapshot once the session had
+ * one. `consumer` is optional, so a file a release before consumer delivery wrote still reads, and
+ * such a release reading a newer file passes over it.
+ */
+export const ReplayStateFileSchema = ReplaySnapshotSchema.extend({
+  consumer: ConsumerDeliverySnapshotSchema.optional(),
+})
+
+export type ReplayStateFile = z.infer<typeof ReplayStateFileSchema>
+
+/** The `.json` suffix is what keeps a session id of `.` or `..` a file of the directory itself,
+ *  since `encodeURIComponent` leaves a dot alone. */
+export function replayStateFile(stateDirectory: string, sessionId: string): string {
+  return join(stateDirectory, `replay-${encodeURIComponent(sessionId)}.json`)
+}
+
+/**
+ * The record a session's file holds; an empty one when there is no file, which is a session that
+ * never ran this plugin, or a new id (a `/clear`, a fresh start). A file that cannot be read or
+ * holds no replay snapshot throws.
+ */
+export async function readReplayState(file: string): Promise<ReplayStateFile> {
+  let text: string
+  try {
+    text = await readFile(file, "utf8")
+  } catch (error) {
+    if (hasErrnoCode(error, "ENOENT")) return { ledger: [] }
+    throw error
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(text)
+  } catch {
+    throw new Error(`${file} is not JSON`)
+  }
+  const snapshot = ReplayStateFileSchema.safeParse(parsed)
+  if (!snapshot.success) throw new Error(`${file} holds no replay state`)
+  return snapshot.data
+}
+
+/** Replaces the session's file by rename, mode 0600, as every other state file is written. */
+export async function writeReplayState(file: string, state: ReplayStateFile): Promise<void> {
+  await writeAtomicStateFile(file, `${JSON.stringify(state)}\n`)
+}
+
+/** Writes one session's file from its two parts, each written whenever its owner changes it. */
+export interface ReplayStateWriter {
+  /** The replay engine's snapshot changed; resolves once a file holding it is in place. */
+  replay(snapshot: ReplaySnapshot): Promise<void>
+  /** The consumer delivery snapshot changed; resolves once a file holding it is in place. */
+  consumer(snapshot: ConsumerDeliverySnapshot): Promise<void>
+  /** Resolves once every write asked for so far has finished, failed ones included. */
+  idle(): Promise<void>
+}
+
+/**
+ * The writer of `file`, starting from what it held (`restored`). Every write replaces the whole
+ * file with both parts as they stand when it runs, one write at a time, so a write that finishes
+ * last never puts back an older part the other owner has replaced since.
+ */
+export function replayStateWriter(file: string, restored: ReplayStateFile): ReplayStateWriter {
+  let current: ReplayStateFile = restored
+  let writing: Promise<void> = Promise.resolve()
+  const write = (next: ReplayStateFile): Promise<void> => {
+    current = next
+    const run = writing.then(() => writeReplayState(file, current))
+    writing = run.catch(() => undefined)
+    return run
+  }
+  return {
+    replay: (snapshot) =>
+      write(
+        current.consumer === undefined ? snapshot : { ...snapshot, consumer: current.consumer },
+      ),
+    consumer: (snapshot) => write({ ...current, consumer: snapshot }),
+    idle: () => writing,
+  }
+}

package/src/send-arguments.ts

@@ -0,0 +1,13 @@
+import { z } from "zod"
+
+const SendArgumentsSchema = z.tuple([z.string().min(1), z.string().min(1)]).rest(z.string().min(1))
+
+export type SendArguments = {
+  readonly targetSession: string
+  readonly message: string
+}
+
+export function parseSendArguments(arguments_: readonly string[]): SendArguments {
+  const [targetSession, ...words] = SendArgumentsSchema.parse(arguments_)
+  return { targetSession, message: words.join(" ") }
+}

package/src/session-identity.ts

@@ -0,0 +1,165 @@
+import { readFile } from "node:fs/promises"
+import { basename, join } from "node:path"
+import { hasErrnoCode, messageFor } from "@legion/envoy-client/errors"
+import { z } from "zod"
+import { pruneStateDirectory, writeAtomicStateFile, writtenLongAgo } from "./session-state"
+
+const PersistedRole = z.object({ session_id: z.string().min(1), role: z.string().min(1) })
+
+/**
+ * The session id the channel server acts as, held once and passed by reference.
+ *
+ * Claude Code mints a new session id on `/clear` but a stdio MCP server keeps the
+ * `CLAUDE_CODE_SESSION_ID` it was spawned with, so the server learns the current id
+ * from the SessionStart hook's handoff file and rebinds. Every registration, tool
+ * call, role claim, and deregistration reads `id` at the moment it runs.
+ */
+export class SessionIdentity {
+  #id: string
+
+  constructor(
+    id: string,
+    /** The Claude project directory Dispatch operations are scoped to. */
+    readonly directory: string,
+  ) {
+    this.#id = id
+  }
+
+  get id(): string {
+    return this.#id
+  }
+
+  set(next: string): void {
+    this.#id = next
+  }
+}
+
+/**
+ * Per-Claude-process handoff: `${CLAUDE_PLUGIN_DATA}/sessions/<pid>/session-id`, where
+ * `<pid>` is the `claude` process both the SessionStart hook and the stdio MCP server are
+ * spawned by. Two concurrent Claude sessions therefore never share a file.
+ */
+export function sessionHandoffDirectory(stateDirectory: string, claudePid: number): string {
+  return join(stateDirectory, "sessions", String(claudePid))
+}
+
+export function sessionHandoffFile(stateDirectory: string, claudePid: number): string {
+  return join(sessionHandoffDirectory(stateDirectory, claudePid), "session-id")
+}
+
+/** The directory the role records live in, named once for the writer and the sweep. */
+const ROLES_DIRECTORY = "roles"
+
+/** Role state is keyed by session id so `claude --resume <id>` finds the role it held. The
+ *  `.json` suffix keeps the name a path segment: `encodeURIComponent` leaves a dot alone, so a
+ *  session id of `.` or `..` would otherwise name the directory itself or its parent. */
+export function roleStateFile(stateDirectory: string, sessionId: string): string {
+  return join(stateDirectory, ROLES_DIRECTORY, `${encodeURIComponent(sessionId)}.json`)
+}
+
+/**
+ * A role record whose bytes cannot be parsed — truncated, hand-edited, written by a later format.
+ * Thrown only by `readPersistedRole`, the one place that knows the bytes came from the file and
+ * not from a listener answering a claim: no later read of the same bytes succeeds, so unlike every
+ * other failure to restore a role it is not worth retrying.
+ */
+export class UnparseableRoleRecordError extends Error {
+  readonly name = "UnparseableRoleRecordError"
+
+  constructor(roleFile: string, cause: unknown) {
+    super(`the role record ${roleFile} cannot be parsed (${messageFor(cause)})`, { cause })
+  }
+}
+
+/**
+ * The role a session held, from its role file; undefined when it has none. Bytes that do not
+ * parse throw `UnparseableRoleRecordError`; every other failure to read them (`EACCES`, `EISDIR`,
+ * any I/O error) propagates unchanged.
+ */
+export async function readPersistedRole(
+  roleFile: string,
+): Promise<z.infer<typeof PersistedRole> | undefined> {
+  let bytes: string
+  try {
+    bytes = await readFile(roleFile, "utf8")
+  } catch (error) {
+    if (hasErrnoCode(error, "ENOENT")) return undefined
+    throw error
+  }
+  try {
+    return PersistedRole.parse(JSON.parse(bytes))
+  } catch (error) {
+    throw new UnparseableRoleRecordError(roleFile, error)
+  }
+}
+
+export async function writePersistedRole(
+  roleFile: string,
+  state: z.infer<typeof PersistedRole>,
+): Promise<void> {
+  await writeAtomicStateFile(roleFile, `${JSON.stringify(state)}\n`)
+}
+
+export async function writeSessionHandoff(file: string, sessionId: string): Promise<void> {
+  await writeAtomicStateFile(file, `${sessionId.trim()}\n`)
+}
+
+export async function readSessionHandoff(file: string): Promise<string | undefined> {
+  try {
+    const id = (await readFile(file, "utf8")).trim()
+    return id.length === 0 ? undefined : id
+  } catch (error) {
+    if (hasErrnoCode(error, "ENOENT")) return undefined
+    throw error
+  }
+}
+
+function processExists(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    return hasErrnoCode(error, "EPERM")
+  }
+}
+
+/** Drop `sessions/<pid>` directories whose Claude process has exited. Anything else under
+ *  `sessions/` is left alone: it was never this sweep's to name. */
+export async function pruneStaleSessionHandoffs(stateDirectory: string): Promise<void> {
+  await pruneStateDirectory(join(stateDirectory, "sessions"), (file) => {
+    const pid = basename(file)
+    return /^\d+$/.test(pid) && !processExists(Number(pid))
+  })
+}
+
+/**
+ * Drop `roles/` records nothing has touched in `STATE_FILE_MAX_AGE_MS`, by the age rule the
+ * title records follow, except the record of `currentSessionId` — the session running the sweep.
+ *
+ * A record's mtime is when its session was last seen holding the role: every heartbeat on which
+ * the listener still names the session as holder touches the record (`refreshRoleRecord` in the
+ * channel server), so this age reaches only a record whose session has not confirmed its role for
+ * that long — in practice one that stopped running. Only one path removes a role file by hand —
+ * a soft `setRole` another live session holds off (`claimed: false`, the listener's 409), never
+ * any answer of the publish route — so a session that holds its role to the end leaves its file
+ * behind, and the handoff sweep cannot reach it: that one walks `sessions/<pid>/` and asks
+ * the operating system about a pid, while a role file is keyed by session id and has no process
+ * left to ask about.
+ *
+ * The sweep runs at startup, before any heartbeat has touched anything, and a session whose claim
+ * the listener refused there has not touched its own record either: age alone would expire the
+ * record of the very session that is running, and the retry queued for its next heartbeat would
+ * find nothing left to restore. Expiring an abandoned record is this sweep's whole point, and the
+ * running session's own record is by construction not abandoned, so it is the one record age does
+ * not decide.
+ */
+export async function pruneStaleSessionRoles(
+  stateDirectory: string,
+  currentSessionId: string,
+): Promise<void> {
+  const own = roleStateFile(stateDirectory, currentSessionId)
+  await pruneStateDirectory(
+    join(stateDirectory, ROLES_DIRECTORY),
+    async (file) => file !== own && (await writtenLongAgo(file)),
+  )
+}

package/src/session-state.ts

@@ -0,0 +1,142 @@
+// The plugin's state files under `CLAUDE_PLUGIN_DATA`: how one is written, how a directory of
+// them is swept, and the chosen-title file itself.
+//
+// This module is the title hook's whole dependency graph beyond `node:` builtins, and it must
+// stay that way: `hooks/session-title-hook.ts` runs before every user prompt, with Claude Code
+// blocking the prompt on it, so anything this file pulls in (zod, the Dispatch client, the
+// session-settings reader — all of which `src/session-identity.ts` reaches through its role
+// schema) is parsed and evaluated on every prompt. The role helpers import from here, never the
+// other way round.
+import { readFileSync } from "node:fs"
+import { mkdir, readdir, rename, rm, stat, utimes, writeFile } from "node:fs/promises"
+import { dirname, join } from "node:path"
+import { hasErrnoCode } from "@legion/envoy-client/errors"
+import { configuredValue } from "./claude-session"
+
+/**
+ * Write a private state file atomically: a 0700 directory, a 0600 temporary file
+ * unique to this process, then a rename onto `file`.
+ */
+export async function writeAtomicStateFile(file: string, contents: string): Promise<void> {
+  await mkdir(dirname(file), { recursive: true, mode: 0o700 })
+  const temporary = `${file}.${process.pid}.${crypto.randomUUID()}.tmp`
+  await writeFile(temporary, contents, { mode: 0o600 })
+  await rename(temporary, file)
+}
+
+/**
+ * Mark `file` as current without touching what it holds: the sweeps below read an mtime for
+ * "last seen", and a holder that is still holding has nothing new to write. A touch also leaves
+ * no temporary file beside it, which an atomic rewrite on every heartbeat would.
+ */
+export async function touchStateFile(file: string): Promise<void> {
+  const now = new Date()
+  await utimes(file, now, now)
+}
+
+/** Whether an entry of a state directory may go, given its path. */
+export type StaleStateEntry = (file: string) => boolean | Promise<boolean>
+
+/**
+ * Remove every entry of `directory` that `isStale` gives up, directories and all. A directory
+ * that does not exist holds nothing stale: nothing here has run yet, or the sweep before this one
+ * emptied it.
+ *
+ * The one sweep behind all three state directories, each of which differs only in what it calls
+ * stale: a handoff whose Claude process is gone, a title or a role nothing has touched in
+ * `STATE_FILE_MAX_AGE_MS`.
+ */
+export async function pruneStateDirectory(
+  directory: string,
+  isStale: StaleStateEntry,
+): Promise<void> {
+  const entries = await readdir(directory).catch((error: unknown) => {
+    if (hasErrnoCode(error, "ENOENT")) return []
+    throw error
+  })
+  for (const entry of entries) {
+    const file = join(directory, entry)
+    if (!(await isStale(file))) continue
+    await rm(file, { recursive: true, force: true })
+  }
+}
+
+/** Thirty days: long enough that a session resumed weeks later still finds the name and the role
+ *  it held. */
+export const STATE_FILE_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1_000
+
+/**
+ * Stale by age: last written more than `STATE_FILE_MAX_AGE_MS` ago. A file whose age cannot be
+ * read is kept, since a sweep that cannot tell must not delete.
+ *
+ * Both the title and the role file are keyed by session id, and a session's id dies with it,
+ * unmourned, so nothing else ever deletes one: without this each directory grows by a file per
+ * session for ever.
+ */
+export async function writtenLongAgo(file: string): Promise<boolean> {
+  const modified = await stat(file).then(
+    (stats) => stats.mtimeMs,
+    () => undefined,
+  )
+  return modified !== undefined && Date.now() - modified > STATE_FILE_MAX_AGE_MS
+}
+
+/** The directory the title records live in, named once for the writer, the reader and the
+ *  sweep. */
+const TITLES_DIRECTORY = "titles"
+
+/** Title state is keyed by session id, like role state, so `claude --resume <id>` finds the name
+ *  the user gave that session and a `/clear`'s new id starts without one. The `.txt` suffix is
+ *  what keeps the name a path segment: `encodeURIComponent` leaves a dot alone, so a session id
+ *  of `.` or `..` would otherwise name the directory itself or its parent. */
+export function sessionTitleFile(stateDirectory: string, sessionId: string): string {
+  return join(stateDirectory, TITLES_DIRECTORY, `${encodeURIComponent(sessionId)}.txt`)
+}
+
+export async function writeChosenTitle(file: string, title: string): Promise<void> {
+  await writeAtomicStateFile(file, `${title}\n`)
+}
+
+/** The session has no custom title any more: a rename can be undone, and the fallback returns. */
+export async function removeChosenTitle(file: string): Promise<void> {
+  await rm(file, { force: true })
+}
+
+/**
+ * The name a user gave the session, as recorded; undefined when the file cannot be read.
+ *
+ * Synchronous and never throwing, because the registration path reads it inside a
+ * `(sessionId: string) => string`: the title is cosmetic, so a failed read must leave the session
+ * on its fallback name rather than fail the registration that carries it.
+ */
+export function readChosenTitleSync(file: string): string | undefined {
+  try {
+    return readFileSync(file, "utf8")
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Records the session's custom title under its session id, or removes the record when the session
+ * has none: an absent or blank `session_title` is how Claude Code says a rename was undone. The
+ * title is written as Claude Code gave it; `src/session-title.ts` cleans and judges it when it
+ * reads the record. A session with no `CLAUDE_PLUGIN_DATA` records nothing, since there is
+ * nowhere the channel server would read it from.
+ */
+export async function recordChosenTitle(
+  sessionId: string,
+  title: string | undefined,
+): Promise<void> {
+  const pluginData = configuredValue(process.env["CLAUDE_PLUGIN_DATA"])
+  if (pluginData === undefined) return
+  const file = sessionTitleFile(pluginData, sessionId)
+  const chosen = configuredValue(title)
+  if (chosen === undefined) await removeChosenTitle(file)
+  else await writeChosenTitle(file, chosen)
+}
+
+/** Drop `titles/` records nothing has touched in `STATE_FILE_MAX_AGE_MS`. */
+export async function pruneStaleSessionTitles(stateDirectory: string): Promise<void> {
+  await pruneStateDirectory(join(stateDirectory, TITLES_DIRECTORY), writtenLongAgo)
+}

package/src/session-title.ts

@@ -0,0 +1,251 @@
+import { execFileSync } from "node:child_process"
+import { readFileSync } from "node:fs"
+import { basename } from "node:path"
+import { configuredValue } from "./claude-session"
+
+export interface SessionTitleEnvironment {
+  readonly ENVOY_SESSION_TITLE?: string | undefined
+  readonly TMUX?: string | undefined
+  readonly TMUX_PANE?: string | undefined
+}
+
+/**
+ * The title registered for the session's current id. Every registration calls it, so the short
+ * id in it follows a `/clear` handoff.
+ */
+export type SessionTitle = (sessionId: string) => string
+
+/** What `tmux -u -S <socket> display-message -p` prints for `pane` and `format`; undefined when
+ *  tmux cannot say. */
+export type TmuxQuery = (
+  socket: string,
+  pane: string,
+  format: string,
+) => Promise<string | undefined>
+
+// `automatic-rename` is the window option, which tmux expands as a format variable (1 or 0). A
+// window left on it is named after the running command, `claude` in every pane, which tells
+// sessions apart no better than nothing, so only a window with it off lends its name. A window
+// index is never used: with `renumber-windows` on, tmux moves it after the title is worked out.
+// A pane of grouped sessions answers with whichever session of the group tmux picks, so the
+// group's name stands in for it, which tmux keeps even after the sessions are renamed or end.
+// `pid` is the server's: a pane id names a pane only on the server that gave it out, and a server
+// started again on the same socket gives out the same ids. `pane_pid` is the pane's first process:
+// tmux hands a popup, `run-shell` job or hook a `TMUX_PANE` left over from wherever the server was
+// started, so a pane is this session's only when its process is one of this session's ancestors.
+const TMUX_PANE_FORMAT = [
+  "#{session_name}",
+  "#{window_name}",
+  "#{automatic-rename}",
+  "#{session_group}",
+  "#{pid}",
+  "#{pane_pid}",
+].join("\t")
+
+/** Bounds the one tmux call the server makes as it starts. A timer bounds it, not a synchronous
+ *  spawn's `timeout`: Bun 1.3.14's `spawnSync` and `execFileSync` can let a child that outlives the
+ *  timeout run to its end, holding the server's start as long as tmux hangs. */
+const TMUX_TIMEOUT_MS = 1_000
+const SHORT_ID_LENGTH = 8
+
+/** How many parents `isAncestor` follows before it stops. */
+const MAX_ANCESTORS = 64
+
+/** A terminal control sequence (a colour code: ESC [ parameters final byte). Built from the ESC
+ *  code, since a control character in a regular expression literal is a lint error. */
+const CSI_SEQUENCE = new RegExp(`${String.fromCharCode(0x1b)}\\[[0-?]*[ -/]*[@-~]`, "gu")
+
+// Bidirectional overrides and isolates would reorder the short id after the name on the Agents
+// page. Other format characters stay: a zero-width joiner holds an emoji sequence together.
+function oneLine(value: string): string {
+  return (
+    value
+      // A colour code goes whole; any other escape loses only its ESC, below.
+      .replace(CSI_SEQUENCE, "")
+      .replace(/[\u202a-\u202e\u2066-\u2069]/gu, "")
+      .replace(/[\s\p{Cc}]+/gu, " ")
+      .trim()
+  )
+}
+
+/** Whether `value` holds a character that shows: not whitespace, a control, format, surrogate or
+ *  unassigned code point, a combining mark with nothing to sit on, an ignorable code point, or
+ *  the blank braille pattern. A private-use glyph (a patched font's icon) counts. */
+function visible(value: string): boolean {
+  return (
+    value.replace(
+      /[\s\p{Cc}\p{Cf}\p{Cs}\p{Cn}\p{M}\p{Default_Ignorable_Code_Point}\u2800]/gu,
+      "",
+    ) !== ""
+  )
+}
+
+/** The parent of process `pid`, or undefined when it cannot be read. */
+function parentPid(pid: number): number | undefined {
+  try {
+    if (process.platform === "linux") {
+      // The command name, in parentheses, may hold spaces; the parent is the second field after it.
+      const stat = readFileSync(`/proc/${pid}/stat`, "utf8")
+      const parent = Number(stat.slice(stat.lastIndexOf(")") + 2).split(" ")[1])
+      return Number.isInteger(parent) ? parent : undefined
+    }
+    const parent = Number(
+      execFileSync("ps", ["-o", "ppid=", "-p", String(pid)], {
+        encoding: "utf8",
+        timeout: TMUX_TIMEOUT_MS,
+        killSignal: "SIGKILL",
+      }).trim(),
+    )
+    return Number.isInteger(parent) ? parent : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** Whether process `candidate` is `pid` or one of its ancestors, walking up from `pid` and
+ *  stopping at the first match, at init, or after `MAX_ANCESTORS` steps. */
+export function isAncestor(candidate: string, pid: number = process.pid): boolean {
+  let current: number | undefined = pid
+  for (let step = 0; current !== undefined && current > 1 && step < MAX_ANCESTORS; step++) {
+    if (String(current) === candidate) return true
+    current = parentPid(current)
+  }
+  return false
+}
+
+/**
+ * `tmux -u -S <socket> display-message -p -t <pane> <format>`; undefined when tmux is missing, slow
+ * or refuses, or prints nothing: a running tmux server answers a pane it does not have with an
+ * empty line and exit status 0 (tmux 3.7b), not an error. `-u`, because the format's fields are
+ * tab-separated, and tmux prints a tab as `_` to a client that has neither `TMUX` nor a UTF-8
+ * locale in its environment; the daemon's `utf8Argv` passes it for the same reason.
+ */
+export async function queryTmux(
+  socket: string,
+  pane: string,
+  format: string,
+): Promise<string | undefined> {
+  let child: Bun.Subprocess<"ignore", "pipe", "ignore">
+  try {
+    child = Bun.spawn(["tmux", "-u", "-S", socket, "display-message", "-p", "-t", pane, format], {
+      stdin: "ignore",
+      stdout: "pipe",
+      stderr: "ignore",
+    })
+  } catch {
+    // No `tmux` on the PATH.
+    return undefined
+  }
+  const reader = child.stdout.getReader()
+  const expired = Promise.withResolvers<undefined>()
+  const timer = setTimeout(() => {
+    // A `tmux` that ignores SIGTERM (a wrapper script) would hold the server's start past the
+    // bound; SIGKILL cannot be ignored. A grandchild it leaves behind (the wrapper's own command)
+    // can still hold the pipe open, so the pipe is not waited for, and the read is cancelled: a
+    // read left pending would keep this process alive until that grandchild ends.
+    child.kill("SIGKILL")
+    reader.cancel().catch(() => undefined)
+    expired.resolve(undefined)
+  }, TMUX_TIMEOUT_MS)
+  const answered = (async () => {
+    const decoder = new TextDecoder()
+    let answer = ""
+    for (let chunk = await reader.read(); !chunk.done; chunk = await reader.read()) {
+      answer += decoder.decode(chunk.value, { stream: true })
+    }
+    answer += decoder.decode()
+    return (await child.exited) === 0 && answer.trim() !== "" ? answer : undefined
+  })().catch(() => undefined)
+  try {
+    return await Promise.race([answered, expired.promise])
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/**
+ * The tmux name of `pane` on the server at `socket` whose process is `serverPid`: `session:window`
+ * for a window whose `automatic-rename` is off, else the tmux session's name. Undefined when tmux
+ * cannot say, when another server now answers on that socket, when `ownPane` refuses the pane's
+ * first process (the pane is not this session's), and for a session named only by digits (plain
+ * `tmux` names its first one `0`) in a window nobody named, since that says nothing on any machine.
+ */
+export async function tmuxPaneTitle(
+  socket: string,
+  serverPid: string,
+  pane: string,
+  ownPane: (panePid: string) => boolean,
+  query: TmuxQuery = queryTmux,
+): Promise<string | undefined> {
+  const fields = (await query(socket, pane, TMUX_PANE_FORMAT))?.replace(/\r?\n$/, "").split("\t")
+  if (fields === undefined || fields.length < 6) return undefined
+  const [name = "", window = "", automaticRename, group = "", pid, panePid = ""] =
+    fields.map(oneLine)
+  if (pid !== serverPid || !ownPane(panePid)) return undefined
+  const session = group === "" ? name : group
+  // A tmux too old to expand a format prints it as it was sent; a name with nothing that shows
+  // would be a blank label.
+  if (!visible(session) || session.startsWith("#{")) return undefined
+  if (visible(window) && (automaticRename === "0" || automaticRename === "off")) {
+    return `${session}:${window}`
+  }
+  return /^[0-9]+$/.test(session) ? undefined : session
+}
+
+/** A name the user gave the session (`claude -n`, `--name`, `/rename`), as recorded for
+ *  `sessionId`; undefined when that session has none. */
+export type ChosenTitle = (sessionId: string) => string | undefined
+
+/** The seams a caller may inject; each defaults to what the running session uses. */
+export interface SessionTitleSources {
+  /** How a tmux server is asked for a pane's fields; by default a bounded `tmux` run. */
+  readonly query?: TmuxQuery
+  /** Whether a pane's first process is ours; by default one of this process's ancestors. */
+  readonly ownPane?: (panePid: string) => boolean
+  /** The name the user gave a session; by default none is recorded. */
+  readonly chosen?: ChosenTitle
+}
+
+/**
+ * The title this session registers with the Envoy listener, which Dispatch's Agents page shows in
+ * place of the session id: `ENVOY_SESSION_TITLE`; else the name the user gave the session, alone,
+ * since a name a person chose needs nothing to tell it apart; else a name and the current id's
+ * first eight characters, the name being the pane's tmux name inside tmux (`TMUX` and
+ * `TMUX_PANE`, asked of the server `TMUX` names, for a pane whose first process `ownPane`
+ * accepts, by default one of this process's ancestors) and the project directory's name
+ * otherwise. The short id keeps two sessions that share a tmux window or session apart. The tmux
+ * name is worked out once, as the server starts, which is the one thing the returned promise waits
+ * for: a tmux rename after that shows on the next start. `chosen` is asked on every call instead,
+ * so a name the user chose after the server started reaches the listener on the next registration.
+ */
+export async function sessionTitle(
+  environment: SessionTitleEnvironment,
+  directory: string,
+  sources: SessionTitleSources = {},
+): Promise<SessionTitle> {
+  const {
+    query = queryTmux,
+    ownPane = (panePid: string) => isAncestor(panePid),
+    chosen = () => undefined,
+  } = sources
+  const explicit = oneLine(configuredValue(environment.ENVOY_SESSION_TITLE) ?? "")
+  // A title with nothing that shows once cleaned (a zero-width space, a colour code alone) would
+  // be a blank row.
+  if (visible(explicit)) return () => explicit
+  // `TMUX` is `<socket>,<server pid>,<session>`, and a socket path may hold a comma.
+  const parts = configuredValue(environment.TMUX)?.split(",") ?? []
+  const socket = parts.slice(0, -2).join(",")
+  const serverPid = parts.at(-2) ?? ""
+  const pane = configuredValue(environment.TMUX_PANE)?.trim()
+  // A directory name holds whatever the filesystem allows, newlines and overrides among them.
+  const directoryName = oneLine(basename(directory) || directory)
+  const name =
+    (socket === "" || serverPid === "" || pane === undefined
+      ? undefined
+      : await tmuxPaneTitle(socket, serverPid, pane, ownPane, query)) ??
+    (visible(directoryName) ? directoryName : "session")
+  return (sessionId) => {
+    const own = oneLine(chosen(sessionId) ?? "")
+    return visible(own) ? own : `${name} ${sessionId.slice(0, SHORT_ID_LENGTH)}`
+  }
+}