@brimveyn/aimux 1.16.2 → 1.18.1

package/src/daemon/reexec-client.ts

@@ -0,0 +1,147 @@
+import { existsSync } from 'node:fs'
+import { connect } from 'node:net'
+
+import { MANAGER_PROTOCOL_MIN_VERSION } from '../ipc/manager-protocol'
+import {
+  encodeMessage,
+  IPC_CAPABILITY_HOT_REEXEC,
+  IPC_PROTOCOL_MIN_VERSION,
+  IPC_PROTOCOL_VERSION,
+  MessageDecoder,
+  parseServerMessage,
+} from '../ipc/protocol'
+
+export interface NegotiateReexecOptions {
+  /**
+   * Free-form label sent as `prepareReexec.reason`. Shows up in daemon
+   * debug logs so post-mortems can distinguish bootstrap-driven from
+   * CLI-driven reexecs.
+   */
+  reason: string
+  /**
+   * Overall deadline for the round-trip (connect → hello → prepareReexec
+   * → ack). Defaults to 5s, matching the pre-consolidation ad-hoc value.
+   */
+  timeoutMs?: number
+}
+
+export type NegotiateReexecResult =
+  | { handoffPath: string; ok: true; renamedSocketPath: string }
+  | { ok: false; reason: string }
+
+/**
+ * Negotiate a hot-reexec with the daemon at `socketPath`. Resolves once
+ * the daemon has acked the drain (it will then exit ~250ms later on its
+ * own and free the canonical socket for a successor binary) or a failure
+ * mode is detected — the caller falls back to a full restart.
+ *
+ * Consolidates the previously-duplicated negotiation in bootstrap.ts,
+ * restart-daemon.ts, and the manual-reexec-test harness.
+ */
+export async function negotiateDaemonReexec(
+  socketPath: string,
+  opts: NegotiateReexecOptions
+): Promise<NegotiateReexecResult> {
+  const { reason, timeoutMs = 5_000 } = opts
+  return new Promise<NegotiateReexecResult>((resolve) => {
+    const socket = connect(socketPath)
+    const decoder = new MessageDecoder(parseServerMessage)
+    const helloId = crypto.randomUUID()
+    const reexecId = crypto.randomUUID()
+    let settled = false
+
+    const finish = (result: NegotiateReexecResult) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      socket.removeAllListeners()
+      socket.destroy()
+      resolve(result)
+    }
+
+    const timer = setTimeout(() => finish({ ok: false, reason: 'timeout' }), timeoutMs)
+
+    socket.once('error', (error: NodeJS.ErrnoException) => {
+      // Once we've observed the ack we've already resolved; ECONNRESET /
+      // EPIPE during the daemon's drain is expected. Guard on `settled`.
+      if (!settled) finish({ ok: false, reason: error.message })
+    })
+    socket.once('connect', () => {
+      socket.write(
+        encodeMessage({
+          id: helloId,
+          payload: { maxVersion: IPC_PROTOCOL_VERSION, minVersion: IPC_PROTOCOL_MIN_VERSION },
+          type: 'hello',
+        })
+      )
+    })
+    socket.on('data', (chunk) => {
+      try {
+        for (const message of decoder.push(chunk)) {
+          if (!('id' in message)) continue
+          if (message.id === helloId) {
+            if (message.type !== 'helloResult') {
+              finish({ ok: false, reason: `hello: ${message.type}` })
+              return
+            }
+            if (!message.payload.capabilities.includes(IPC_CAPABILITY_HOT_REEXEC)) {
+              finish({ ok: false, reason: 'daemon does not advertise hotReexec' })
+              return
+            }
+            // Successor would fail to speak to the running TM if it needs a
+            // newer manager protocol than the TM negotiated. Legacy daemons
+            // that predate managerSelectedVersion omit the field — treat
+            // that as unknown-and-bail so we don't drain into a doomed
+            // reexec.
+            const managerSelected = message.payload.managerSelectedVersion
+            if (managerSelected === undefined || managerSelected < MANAGER_PROTOCOL_MIN_VERSION) {
+              finish({ ok: false, reason: 'manager-protocol mismatch' })
+              return
+            }
+            socket.write(
+              encodeMessage({
+                id: reexecId,
+                payload: { reason },
+                type: 'prepareReexec',
+              })
+            )
+            continue
+          }
+          if (message.id === reexecId) {
+            if (message.type === 'reexecAck') {
+              finish({
+                handoffPath: message.payload.handoffPath,
+                ok: true,
+                renamedSocketPath: message.payload.renamedSocketPath,
+              })
+              return
+            }
+            finish({ ok: false, reason: `prepareReexec: ${message.type}` })
+            return
+          }
+        }
+      } catch (error) {
+        finish({ ok: false, reason: error instanceof Error ? error.message : String(error) })
+      }
+    })
+  })
+}
+
+/**
+ * Poll until the canonical daemon socket path no longer exists (the
+ * predecessor renamed it away as part of its drain). Returns true once
+ * the dirent is gone, false if `deadlineMs` elapses first. Consolidates
+ * the poll loop that bootstrap.ts, restart-daemon.ts, and the manual
+ * harness each carried a copy of.
+ */
+export async function waitForSocketRemoval(
+  socketPath: string,
+  deadlineMs = 2_000
+): Promise<boolean> {
+  const stop = Date.now() + deadlineMs
+  while (Date.now() < stop) {
+    if (!existsSync(socketPath)) return true
+    await new Promise((r) => setTimeout(r, 25))
+  }
+  return false
+}

package/src/daemon/runtime-paths.ts

@@ -1,4 +1,13 @@
-import { chmodSync, constants, existsSync, lstatSync, mkdirSync, unlinkSync } from 'node:fs'
+import {
+  chmodSync,
+  constants,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs'
 import { dirname, join } from 'node:path'
 
 import { getProfileName } from '../profile-paths'
@@ -108,3 +117,154 @@ export function removeSocketIfExists(socketPath: string): void {
 export function removeTerminalManagerSocketIfExists(): void {
   removeSocketIfExists(getTerminalManagerSocketPath())
 }
+
+// --- Hot-reexec sidecars ---
+//
+// Three small files coordinate the daemon-hot-reexec handoff (see
+// docs/developer/hot-reexec.md):
+//
+//   daemon.pid          // current daemon's pid, written on bind
+//   daemon.version      // current daemon's process version (Bun version)
+//   daemon.handoff.json // present iff the running daemon was spawned as a
+//                       // reexec successor. Consumed (deleted) on read so
+//                       // a subsequent fresh boot doesn't trip the path.
+//
+// The renamed-away socket lives at daemon.old.sock until the predecessor
+// daemon exits and the dirent is unlinked.
+
+export function getDaemonPidFilePath(): string {
+  return join(ensureRuntimeDir(), 'daemon.pid')
+}
+
+export function getDaemonVersionFilePath(): string {
+  return join(ensureRuntimeDir(), 'daemon.version')
+}
+
+export function getDaemonHandoffFilePath(): string {
+  return join(ensureRuntimeDir(), 'daemon.handoff.json')
+}
+
+export function getDaemonOldSocketPath(): string {
+  return join(ensureRuntimeDir(), 'daemon.old.sock')
+}
+
+export interface DaemonHandoffV1 {
+  version: 1
+  fromPid: number
+  fromProcessVersion: string
+  /** Epoch ms when the handoff was written. Diagnostic only. */
+  writtenAt: number
+  /** The renamed-away socket the predecessor is about to release. */
+  renamedSocketPath: string
+}
+
+export function writeDaemonHandoff(data: DaemonHandoffV1): string {
+  const path = getDaemonHandoffFilePath()
+  writeFileSync(path, JSON.stringify(data), { mode: 0o600 })
+  return path
+}
+
+/**
+ * Reads the handoff file if present and deletes it in the same call. The
+ * file is single-use: a daemon that finds it knows it was spawned to take
+ * over from a predecessor.
+ */
+export function consumeDaemonHandoff(): DaemonHandoffV1 | null {
+  const path = getDaemonHandoffFilePath()
+  if (!existsSync(path)) {
+    return null
+  }
+  let raw: string
+  try {
+    raw = readFileSync(path, 'utf8')
+  } catch {
+    return null
+  }
+  try {
+    unlinkSync(path)
+  } catch {
+    // best-effort — the next fresh boot would re-consume it, which is fine.
+  }
+  try {
+    const parsed = JSON.parse(raw) as Partial<DaemonHandoffV1>
+    if (
+      parsed.version === 1 &&
+      typeof parsed.fromPid === 'number' &&
+      typeof parsed.fromProcessVersion === 'string' &&
+      typeof parsed.writtenAt === 'number' &&
+      typeof parsed.renamedSocketPath === 'string'
+    ) {
+      return parsed as DaemonHandoffV1
+    }
+    return null
+  } catch {
+    return null
+  }
+}
+
+export function writeDaemonPidFile(pid: number): void {
+  writeFileSync(getDaemonPidFilePath(), `${pid}\n`, { mode: 0o600 })
+}
+
+export function writeDaemonVersionFile(version: string): void {
+  writeFileSync(getDaemonVersionFilePath(), `${version}\n`, { mode: 0o600 })
+}
+
+export function readDaemonPidFile(): number | null {
+  const path = getDaemonPidFilePath()
+  if (!existsSync(path)) return null
+  try {
+    const pid = Number.parseInt(readFileSync(path, 'utf8').trim(), 10)
+    return Number.isFinite(pid) && pid > 0 ? pid : null
+  } catch {
+    return null
+  }
+}
+
+export function readDaemonVersionFile(): string | null {
+  const path = getDaemonVersionFilePath()
+  if (!existsSync(path)) return null
+  try {
+    const v = readFileSync(path, 'utf8').trim()
+    return v.length > 0 ? v : null
+  } catch {
+    return null
+  }
+}
+
+export function removeDaemonSidecars(): void {
+  for (const path of [
+    getDaemonPidFilePath(),
+    getDaemonVersionFilePath(),
+    getDaemonHandoffFilePath(),
+    getDaemonOldSocketPath(),
+  ]) {
+    if (existsSync(path)) {
+      try {
+        unlinkSync(path)
+      } catch {
+        // best-effort cleanup
+      }
+    }
+  }
+}
+
+/**
+ * Reexec-only variant: strip pid/version so no bystander (harness, CLI,
+ * anything that prefers the pidfile over `lsof`) reads a dead PID during
+ * the swap window. The handoff file is intentionally preserved — the
+ * successor consumes it on boot to log that it took over from the
+ * predecessor. The renamed socket dirent is handled by the shutdown path
+ * (which unlinks it after `server.close()` releases the inode).
+ */
+export function removeDaemonSidecarsForReexec(): void {
+  for (const path of [getDaemonPidFilePath(), getDaemonVersionFilePath()]) {
+    if (existsSync(path)) {
+      try {
+        unlinkSync(path)
+      } catch {
+        // best-effort cleanup
+      }
+    }
+  }
+}

package/src/daemon/session-registry.ts

@@ -131,6 +131,12 @@ export class SessionRegistry extends EventEmitter<SessionRegistryEvents> {
     cwd?: string
     /** Extra env injected into the spawned shell. Passed through to the PTY. */
     env?: Record<string, string>
+    /**
+     * Worktree this tab belongs to (for UI grouping). Stored on the
+     * TabSession so an attach-time replay surfaces it inside the right
+     * worktree column. Optional — tabs not bound to a worktree are valid.
+     */
+    worktreeId?: string
   }): void {
     logDebug('daemon.registry.createSession', {
       args: options.args ?? [],
@@ -150,6 +156,7 @@ export class SessionRegistry extends EventEmitter<SessionRegistryEvents> {
         status: 'starting',
         terminalModes: createDefaultTerminalModes(),
         title: options.title,
+        worktreeId: options.worktreeId,
       })
     } else {
       existing.status = 'starting'
@@ -161,12 +168,22 @@ export class SessionRegistry extends EventEmitter<SessionRegistryEvents> {
       existing.assistant = options.assistant
       existing.title = options.title
       existing.command = [options.command, ...(options.args ?? [])].join(' ')
+      if (options.worktreeId !== undefined) existing.worktreeId = options.worktreeId
     }
 
     this.activeTabId = options.tabId
     this.ptyManager.createSession(options)
   }
 
+  /**
+   * Read the in-memory TabSession for a tab. Returned by reference — used by
+   * the daemon's `tabAdded` broadcast path to publish the same shape the UI
+   * already knows how to ingest from `attachResult.tabs[]`.
+   */
+  getTab(tabId: string): TabSession | undefined {
+    return this.tabs.get(tabId)
+  }
+
   write(tabId: string, data: string): void {
     this.ptyManager.write(tabId, data)
   }

package/src/index.tsx

@@ -19,6 +19,15 @@ import { runUpdate } from './update'
 const command = process.argv[2]
 const runtimeProfile = getRuntimeProfile()
 
+// CLI control plane (docs/reference/cli.md). Branch BEFORE the UI bootstrap so
+// `aimux tab list` from a non-TTY shell never spins up the React renderer.
+// Dynamic import keeps the CLI code out of the UI's cold-start cost.
+const CLI_GROUPS = new Set(['tab', 'workspace', 'worktree'])
+if (typeof command === 'string' && CLI_GROUPS.has(command)) {
+  const { runCli } = await import('./cli')
+  process.exit(await runCli(process.argv.slice(2)))
+}
+
 if (command === '--version' || command === '-v' || command === 'version') {
   const { version } = await import('../package.json')
   process.stdout.write(`aimux ${version}\n`)

package/src/input/modes/bridge.ts

@@ -45,6 +45,12 @@ export function deriveModeId(state: AppState): ModeId {
     return 'modal.worktree-move'
   }
 
+  // Flash-jump overlay: same pattern — renders on top of navigation, all
+  // letter keys are passthrough'd to update-command-edit for buffer matching.
+  if (state.modal.type === 'flash-jump') {
+    return 'modal.flash-jump'
+  }
+
   const directMode = DIRECT_FOCUS_MODE_IDS[state.focusMode]
   if (directMode) {
     return directMode

package/src/input/modes/transitions.ts

@@ -4,6 +4,7 @@ const TRANSITIONS: Record<ModeId, readonly ModeId[]> = {
   'git-mode': ['navigation', 'modal.git-commit', 'modal.worktree-move'],
   'modal.ai-usage': ['navigation', 'terminal-input'],
   'modal.create-session': ['navigation', 'modal.session-picker.filtering'],
+  'modal.flash-jump': ['navigation'],
   'modal.git-commit': ['git-mode', 'modal.git-commit.confirm', 'modal.git-commit.generating'],
   'modal.git-commit.confirm': ['modal.git-commit', 'git-mode'],
   'modal.git-commit.generating': ['modal.git-commit', 'modal.git-commit.confirm', 'git-mode'],
@@ -41,6 +42,7 @@ const TRANSITIONS: Record<ModeId, readonly ModeId[]> = {
     'modal.ai-usage',
     'modal.worktree-delete-confirm',
     'modal.worktree-move-confirm',
+    'modal.flash-jump',
     'git-mode',
   ],
   'terminal-input': ['navigation', 'modal.split-picker', 'modal.ai-usage'],

package/src/input/modes/types.ts

@@ -28,6 +28,7 @@ export type ModeId =
   | 'modal.worktree-move'
   | 'modal.worktree-move-confirm'
   | 'modal.ai-usage'
+  | 'modal.flash-jump'
 
 export type SideEffect =
   | { type: 'quit'; state: AppState }

package/src/ipc/README.md

@@ -0,0 +1,112 @@
+# IPC protocols — additive contract
+
+Two wire protocols live in this directory:
+
+| Link                      | File                  | Negotiated by                     | Breaking it kills...                                                                |
+| ------------------------- | --------------------- | --------------------------------- | ----------------------------------------------------------------------------------- |
+| UI / CLI ↔ daemon         | `protocol.ts`         | `DaemonClient.hello()`            | Client connections. PTYs survive (they live in the TM).                             |
+| daemon ↔ terminal-manager | `manager-protocol.ts` | `TerminalManagerClient.connect()` | **Every PTY.** A fresh TM is spawned, the old one dies, every session dies with it. |
+
+The cost asymmetry is the whole reason this document exists. **Touch
+`manager-protocol.ts` and you are about to drop every running Claude/Codex
+session.** Make sure that's what you want.
+
+## The rule
+
+> A wire change is **additive** by default. `MIN_VERSION` only rises when the
+> new daemon literally cannot parse a message a pre-bump peer would send.
+
+`MAX_VERSION` advertises "I know about new things." `MIN_VERSION` declares
+"old peers are now unrunnable." These are different operations. The old
+`bump-protocol.ts` script bumps both in lockstep — that's correct only for
+true semantic breaks, and most wire changes aren't that.
+
+### Decision tree before bumping MIN
+
+```
+            Are you adding a field / event / request type?
+                              │
+              ┌───────────────┴───────────────┐
+            yes                              no (removing / repurposing)
+              │                              │
+   Is the new field required for             │
+   correctness on the OLD peer?              Can the old peer still
+              │                              decode the bytes the new
+       ┌──────┴──────┐                       peer puts on the wire?
+      yes           no                       │
+       │             │                ┌──────┴──────┐
+   bump MIN     keep MIN.            yes           no
+                Advertise as a       │             │
+                capability.          keep MIN.    bump MIN.
+                Gate the new         Deprecate    Write
+                wire on              the old      `BREAKING:` in
+                `capabilities.       behaviour    the commit body.
+                includes(...)`.      and stop
+                                     reading it
+                                     long before
+                                     raising MIN.
+```
+
+If the answer to "are you certain old peers cannot decode this?" is "I
+think so", treat it as additive. The cost of being wrong (PTYs die) is
+much higher than the cost of one stale capability flag.
+
+## Capabilities
+
+Both `helloResult` payloads carry a `capabilities: string[]`. A client
+checks `capabilities.includes("featureName")` before sending a request or
+relying on an event that the peer might not understand. New features are
+introduced as new capability strings, **not** as a MIN bump.
+
+Current capability registries live next to each protocol:
+
+- `src/ipc/protocol.ts` → `IPC_PROTOCOL_CAPABILITIES`
+- `src/ipc/manager-protocol.ts` → `MANAGER_PROTOCOL_CAPABILITIES`
+
+To add a new capability:
+
+1. Pick a stable string (kebab/camel — pick one and stay consistent per
+   protocol; `manager-protocol` uses camelCase).
+2. Add it to the capabilities constant the producing side advertises.
+3. On the consuming side, gate calls / event handlers behind
+   `helloResult.capabilities.includes("yourCap")`.
+4. **Do not** bump MIN. Old peers without the capability will simply not
+   see the new behaviour, which is the entire point of the gate.
+
+For unknown request types received by an old peer: the peer replies
+`error: "unknown request"`. New clients must treat that as the gate having
+been wrong (capability advertised but no handler) and surface a clear
+error, not retry forever.
+
+## When MIN must bump anyway
+
+Examples of genuine semantic breaks where MIN must rise in lockstep with
+MAX (and `BREAKING:` belongs in the commit body):
+
+- A field changed type (e.g. `cols: number` → `cols: { value: number; cells: number }`).
+- A request was removed and its absence is load-bearing (the peer would
+  hang waiting for a response).
+- Per-line wire framing changed.
+
+The previous lockstep bumps in `protocol.ts` (v9 dropped scroll intent
+from resize messages) and `manager-protocol.ts` (v7 added palette indices
+to TerminalSpan) qualify because they change the meaning of existing
+fields. Most other changes don't.
+
+## TM bumps that aren't really TM bumps
+
+A historical bad pattern: a UI-only feature lands, `manager-protocol.ts`
+gets bumped "to force a fresh TM and clear caches." This kills PTYs for
+zero benefit. Don't do this. If the TM behaviour didn't change,
+`manager-protocol.ts` doesn't get touched.
+
+The lint check in `scripts/check-protocol-discipline.ts` enforces both
+rules: MIN bumps require an explicit `BREAKING:` marker, and new callers
+of `stopTerminalManager` need explicit approval.
+
+## See also
+
+- `docs/developer/hot-reexec.md` — the additive-contract discipline and the
+  daemon hot-reexec swap that keeps PTYs alive across upgrades.
+- `docs/reference/cli.md` — the headless control-plane surface that the
+  capability mechanism was originally introduced to serve.

package/src/ipc/manager-protocol.ts

@@ -34,10 +34,32 @@ import {
 // is raised in lockstep to force matching binaries.
 export const MANAGER_PROTOCOL_MIN_VERSION = 8
 export const MANAGER_PROTOCOL_VERSION = 8
+
+/**
+ * Capability strings advertised by *this* process in its `helloResult`. New
+ * additive TM features should be introduced here rather than via a MIN bump
+ * — bumping MIN forces a fresh TM and kills every PTY. See
+ * `src/ipc/README.md`.
+ */
+export const MANAGER_PROTOCOL_CAPABILITIES: readonly string[] = [
+  'setBroadcastEnabled',
+  'createTabWorktreeId',
+]
+
+/**
+ * Capability name a daemon must observe on the TM's helloResult before
+ * sending `setBroadcastEnabled`.
+ */
+export const MANAGER_CAPABILITY_SET_BROADCAST_ENABLED = 'setBroadcastEnabled'
+
 /**
- * Minimum version required to send `setBroadcastEnabled`. Older TMs (v3) will
- * not understand the message; the daemon must check the negotiated version
- * before sending and fall back to always-on broadcast.
+ * Version-based fallback for `setBroadcastEnabled`. TM binaries that predate
+ * the capability field (built before the additive-contract migration) don't
+ * advertise capabilities, but any TM at v4+ speaks the request. Callers gate
+ * on `capabilities.has('setBroadcastEnabled') || selectedVersion >= this`.
+ *
+ * Rolling-upgrade window: new daemon + old TM (still v4+) would otherwise
+ * silently regress to always-broadcasting, spiking CPU and IPC traffic.
  */
 export const MANAGER_PROTOCOL_BROADCAST_GATE_VERSION = 4
 
@@ -51,6 +73,11 @@ export interface ManagerHelloResult {
   maxVersion: number
   processVersion: string
   selectedVersion: number
+  /**
+   * Feature flags. Always present on the typed shape; older peers that did
+   * not yet advertise capabilities are normalised to `[]` at parse time.
+   */
+  capabilities: string[]
 }
 
 export interface ManagerAttachRequest {
@@ -85,6 +112,13 @@ export type ManagerRequest =
         cwd?: string
         /** Extra env vars merged into the spawned PTY's environment. */
         env?: Record<string, string>
+        /**
+         * Worktree this tab belongs to (UI grouping). Capability-gated on
+         * `createTabWorktreeId`. Pre-cap TMs silently drop the field, which
+         * matches the previous behaviour where every new tab had
+         * `worktreeId = undefined`.
+         */
+        worktreeId?: string
       }
     }
   | { id: string; type: 'write'; payload: { sessionId: string; tabId: string; data: string } }
@@ -240,7 +274,10 @@ function isHelloResult(value: unknown): value is ManagerHelloResult {
     isFiniteNumber(value.minVersion) &&
     isFiniteNumber(value.maxVersion) &&
     isFiniteNumber(value.selectedVersion) &&
-    isString(value.processVersion)
+    isString(value.processVersion) &&
+    // Wire-back-compat: legacy peers omit capabilities entirely. The parser
+    // normalises that to `[]` before returning the typed shape.
+    (value.capabilities === undefined || isStringArray(value.capabilities))
   )
 }
 
@@ -250,6 +287,12 @@ function assert(condition: boolean, message: string): asserts condition {
   }
 }
 
+function normaliseManagerCapabilities(payload: Record<string, unknown>): void {
+  if (!Array.isArray(payload.capabilities)) {
+    payload.capabilities = []
+  }
+}
+
 export function selectManagerProtocolVersion(payload: ManagerHelloRequest): number | null {
   return negotiateProtocolVersion(
     payload.minVersion,
@@ -261,6 +304,7 @@ export function selectManagerProtocolVersion(payload: ManagerHelloRequest): numb
 
 export function createManagerHelloResult(selectedVersion: number): ManagerHelloResult {
   return {
+    capabilities: [...MANAGER_PROTOCOL_CAPABILITIES],
     maxVersion: MANAGER_PROTOCOL_VERSION,
     minVersion: MANAGER_PROTOCOL_MIN_VERSION,
     processVersion: getProcessVersion(),
@@ -316,6 +360,10 @@ export function parseManagerRequest(value: unknown): ManagerRequest {
         value.payload.env === undefined || isStringRecord(value.payload.env),
         'createTab.env must be a string-keyed string record'
       )
+      assert(
+        value.payload.worktreeId === undefined || isString(value.payload.worktreeId),
+        'createTab.worktreeId must be a string when present'
+      )
       return value as ManagerRequest
     case 'write':
       assert(isString(value.payload.sessionId), 'write.sessionId must be a string')
@@ -375,6 +423,8 @@ export function parseManagerMessage(value: unknown): ManagerResponse | ManagerEv
     case 'helloResult':
       assert(isString(value.id), 'helloResult.id must be a string')
       assert(isHelloResult(value.payload), 'helloResult.payload is invalid')
+      // Normalise wire-back-compat: pre-capability TMs omit the field.
+      normaliseManagerCapabilities(value.payload)
       return value as ManagerResponse
     case 'ok':
       assert(isString(value.id), 'ok.id must be a string')