@brimveyn/aimux 1.16.3 → 1.18.2

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`)
@@ -51,9 +60,78 @@ if (command === 'terminal-manager') {
   await runTerminalManager()
 }
 
-if (command === '--help' || command === '-h') {
+if (command === '--help' || command === '-h' || command === 'help') {
   process.stdout.write(
-    'aimux -- terminal multiplexer for AI CLIs\n\nUsage:\n  aimux                           Start aimux\n  aimux update                    Update to latest version\n  aimux doctor                    Diagnose setup issues\n  aimux restart-daemon            Restart IPC daemon\n  aimux restart-terminal-manager  Restart terminal-manager (kills live workspaces)\n\n'
+    [
+      'aimux — terminal multiplexer for AI CLIs',
+      '',
+      'Two surfaces:',
+      '  • Interactive TUI (no args): drive assistants side-by-side in one window.',
+      '  • CLI control plane (`aimux <group> <verb>`): script-friendly, JSON output,',
+      '    designed to be driven by another agent or a shell pipeline.',
+      '',
+      'Interactive',
+      '  aimux                             Start the TUI in the current profile',
+      '',
+      'CLI control plane (JSON on stdout, human-readable errors on stderr)',
+      '  aimux tab       list | create | send | focus | close | snapshot | tail | wait',
+      '  aimux workspace list | show | create | switch | close',
+      '  aimux worktree  list | create | remove',
+      '',
+      '  aimux <group> --help              List verbs in that group',
+      '  aimux <group> <verb> --help       Show flags, args, and exit codes',
+      '',
+      'Common CLI verbs at a glance',
+      '  aimux tab list                                     Enumerate tabs (+ activeTabId)',
+      '  aimux tab create --assistant <id> [--title …]      Spawn claude / codex / opencode / terminal / …',
+      '  aimux tab send <tabId> [text] [--enter|--keys|--stdin]  Type, chord, or paste into a tab',
+      '  aimux tab focus <tabId>                            Bring a tab to the foreground',
+      '  aimux tab close <tabId>                            Terminate a tab',
+      '  aimux tab snapshot <tabId> [--tail N] [--format …] Capture the screen (json | text)',
+      '  aimux tab tail <tabId> [--follow-status] […]       NDJSON stream of renders / status',
+      '  aimux tab wait <tabId> --status <idle|working|waiting-input>  Block on an activity state',
+      '  aimux workspace show                               Dump the active workspace + worktrees',
+      '  aimux workspace create <name> [--project P] [--switch [--wait]]',
+      '  aimux workspace switch <ws> [--wait --timeout N]   Move the running UI to another workspace',
+      '  aimux worktree create --name <n> [--branch B --base R]',
+      '  aimux worktree remove <id|path> [--force]',
+      '',
+      'Shared flags (accepted by every CLI verb)',
+      '  --workspace <id|name>             Target a specific workspace (default: active)',
+      '  --profile <name>                  Runtime profile (also settable via AIMUX_PROFILE)',
+      '  --json                            Reserved; JSON is always on',
+      '',
+      'Maintenance',
+      '  aimux update                      Update aimux to the latest published version',
+      '  aimux doctor                      Diagnose setup (paths, sockets, PTY, integrations)',
+      '  aimux restart-daemon              Restart the IPC daemon (keeps live workspaces)',
+      '  aimux restart-terminal-manager    Restart terminal-manager (kills live workspaces)',
+      '  aimux --version                   Print the installed version',
+      '',
+      'Exit codes',
+      '  0    success',
+      '  2    usage error (bad flags, unknown command, missing argument)',
+      '  3    runtime error (server replied with error, command failed)',
+      '  4    daemon unreachable (socket missing and autostart failed)',
+      '  124  timeout (tab wait, tab tail --timeout, workspace switch --wait)',
+      '',
+      'Env',
+      '  AIMUX_PROFILE                     Runtime profile (state dir, socket paths)',
+      '',
+      'Recipes for agents',
+      '  # spawn Claude, wait for idle, dump the last 40 non-blank lines',
+      '  TAB=$(aimux tab create --assistant claude --title fixup | jq -r .tabId)',
+      '  aimux tab send "$TAB" "explain this repo" --enter',
+      '  aimux tab wait "$TAB" --status idle --timeout 60000',
+      '  aimux tab snapshot "$TAB" --tail 40 --format text',
+      '',
+      '  # send a control chord (Ctrl-C then Esc) using vim-style notation',
+      '  aimux tab send "$TAB" "<C-c><Esc>" --keys',
+      '',
+      '  # follow a tab as NDJSON, one render (or tabStatus) per line',
+      '  aimux tab tail "$TAB" --rate-limit-ms 100 --follow-status',
+      '',
+    ].join('\n')
   )
   process.exit(0)
 }

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.