golem-kit 0.1.0 → 0.2.0

package/src/runtime/harness/fake.js

@@ -0,0 +1,430 @@
+// Vendored from bridge-commander 5bf87e4b harness/fake.js (zero-dependency). Local patches are marked 'golem:'.
+'use strict';
+// fake — in-memory harness implementing the same seven verbs, for unit tests
+// of server code. No tmux, no claude, no filesystem.
+//
+// Refs look like the real thing: { harness: 'fake', session: 'bc-<id>', window?, cwd, resumeId }.
+// A window-granular ref (opts.window at spawn — workers as windows in their
+// lieutenant's session) is keyed as `session:window` everywhere the plain
+// session name would be: the in-memory map, marker files, sends log, and the
+// emitted turn-end event's `session` field.
+//
+// Behavior model:
+//   spawn   — creates a live session, records the prompt as transcript[0],
+//             emits one turn-end event asynchronously (the "reply" turn).
+//   send    — throws on a dead session; records the text; emits a turn-end.
+//   alive   — session exists and is not killed.
+//   resumable — would resume restore memory? true iff this process holds the
+//             session's transcript under a matching resumeId.
+//   resume  — revives a dead session; transcript (memory) survives iff the
+//             resumeId matches the recorded one.
+//   kill    — ends a session for good (idempotent); in file-backed mode also
+//             removes the marker, so cross-process alive() flips false.
+//   onTurnEnd — hooks fire once per emitted turn, in registration order,
+//             only for events after registration. Returns unsubscribe().
+//
+// Test helpers (not part of the port contract): transcript(ref), reset().
+//
+// File-backed mode (cross-process observability): when BC_FAKE_STATE names a
+// directory, spawn/send also persist there —
+//   <session>.json         spawn record { cwd, resumeId, prompt, stateDir }
+//   <session>.sends.jsonl  one JSON line per send { ts, session, text }
+// and a session unknown to THIS process counts as alive (and accepts sends)
+// iff its <session>.json marker exists AND does not say `exited: true` — the
+// window whose agent ended by itself, still standing until something kills it.
+// That lets a test process watch what a server process sent, and pre-register
+// "live" (or exited) fake sessions by dropping a marker file. A marker saying
+// `unreadable: true` is the third state: alive() THROWS, the way a harness
+// answers a question it could not ask. Without BC_FAKE_STATE the fake stays
+// purely in-memory.
+//
+// spawn also writes opts.stateDir/<key>.prompt (the SAME source-of-truth file
+// the real tmux adapters persist) whenever opts.stateDir is given — distinct
+// from BC_FAKE_STATE, and honored even without it, mirroring the real
+// harnesses closely enough for callers (card.start's brief-artifact
+// auto-attach) to be exercised under test without tmux.
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+const { SLASH_COMMANDS, helpText, formatStatus } = require('./agent-status.js');
+const { validatePaneInput } = require('./port.js');
+
+const sessions = new Map(); // key (session or session:window) -> { alive, cwd, resumeId, transcript, hooks, turns }
+
+function keyOf(session, window) {
+  return window ? session + ':' + window : session;
+}
+function refKey(ref) {
+  return keyOf(ref.session, ref.window);
+}
+
+function fakeStateDir() {
+  const dir = process.env.BC_FAKE_STATE;
+  if (!dir) return null;
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+function markerFile(session) {
+  const dir = fakeStateDir();
+  return dir ? path.join(dir, session + '.json') : null;
+}
+function logSend(session, text) {
+  const dir = fakeStateDir();
+  if (!dir) return;
+  fs.appendFileSync(path.join(dir, session + '.sends.jsonl'),
+    JSON.stringify({ ts: new Date().toISOString(), session, text }) + '\n');
+}
+
+function get(ref) {
+  const s = sessions.get(refKey(ref));
+  if (!s) throw new Error(`fake: unknown session ${refKey(ref)}`);
+  return s;
+}
+
+// live(key) — known to THIS process, else the file-backed marker.
+//
+// A marker carrying `exited: true` is the state both tmux harnesses read as NOT
+// alive while the WINDOW is still standing: the agent process ended by itself
+// and its pane fell back to a shell. The marker is that window, so only kill()
+// takes it away — which is why alive() answering false never means there is
+// nothing left to kill.
+function live(key) {
+  const s = sessions.get(key);
+  if (s) return s.alive;
+  const marker = markerFile(key);
+  if (!marker || !fs.existsSync(marker)) return false;
+  try { return !JSON.parse(fs.readFileSync(marker, 'utf8')).exited; }
+  catch (e) { return true; } // unreadable marker: the window is there, that is all we know
+}
+
+// siblings(session) — every key living in that tmux session: the session
+// itself plus its `session:window` windows (in-process and marker-backed).
+// The two verbs below need it because a SESSION-granular ref addresses a whole
+// tmux session, windows and all — the fidelity that makes the lieutenant's
+// window-granular ref testable without tmux.
+function siblings(session) {
+  const keys = new Set();
+  const mine = (k) => k === session || k.startsWith(session + ':');
+  for (const k of sessions.keys()) if (mine(k)) keys.add(k);
+  const dir = fakeStateDir();
+  if (dir) {
+    for (const f of fs.readdirSync(dir)) {
+      if (!f.endsWith('.json')) continue;
+      const k = f.slice(0, -5);
+      if (mine(k)) keys.add(k);
+    }
+  }
+  return [...keys];
+}
+
+function emitTurnEnd(name) {
+  const s = sessions.get(name);
+  if (!s || !s.alive) return;
+  s.turns += 1;
+  const event = {
+    ts: new Date().toISOString(),
+    session: name,
+    event: 'Stop',
+    session_id: s.resumeId,
+    cwd: s.cwd,
+    turn: s.turns,
+  };
+  const hooks = [...s.hooks];
+  setImmediate(() => {
+    for (const h of hooks) {
+      try {
+        h.fn(event, h.ref);
+      } catch {
+        // hooks must not break the fake
+      }
+    }
+  });
+}
+
+// BC_FAKE_SPAWN_MS holds spawn open for that long before it returns. A real
+// spawn is seconds — createPane, then launch-settle blocking until the composer
+// is up — and everything racing that window (supervision landing on a session
+// that is legitimately down mid-restart) is invisible against a fake that
+// returns instantly.
+const SPAWN_MS = parseInt(process.env.BC_FAKE_SPAWN_MS, 10) > 0
+  ? parseInt(process.env.BC_FAKE_SPAWN_MS, 10) : 0;
+
+// BC_FAKE_ALIVE_MS does the same for alive(). A real liveness read is two tmux
+// subprocess round-trips, and what a caller does with the answer can be decided
+// while the registry moves underneath it — invisible against a fake that
+// answers in the same tick.
+const ALIVE_MS = parseInt(process.env.BC_FAKE_ALIVE_MS, 10) > 0
+  ? parseInt(process.env.BC_FAKE_ALIVE_MS, 10) : 0;
+
+async function spawn(cwd, prompt, opts = {}) {
+  const session = opts.session || 'bc-' + crypto.randomBytes(3).toString('hex');
+  const window = opts.window === undefined || opts.window === null ? undefined : String(opts.window);
+  const key = keyOf(session, window);
+  if (sessions.has(key) && sessions.get(key).alive) {
+    throw new Error(`fake: session ${key} already exists`);
+  }
+  // tmux refuses a window whose name is already taken, and a window whose agent
+  // EXITED is still a window. The marker is that window in file-backed mode, so
+  // a spawn over one nobody killed fails here exactly as the real harness does.
+  if (markerFile(key) && fs.existsSync(markerFile(key))) {
+    throw new Error(`fake: session ${key} already exists`);
+  }
+  if (SPAWN_MS) await new Promise((r) => setTimeout(r, SPAWN_MS));
+  const resumeId = crypto.randomUUID();
+  sessions.set(key, {
+    alive: true,
+    cwd,
+    resumeId,
+    transcript: [prompt],
+    hooks: [],
+    turns: 0,
+  });
+  const marker = markerFile(key);
+  if (marker) {
+    // stateDir rides along so a watching test can verify what dir the caller
+    // plumbed through the port (the fake itself never writes state there).
+    fs.writeFileSync(marker,
+      JSON.stringify({ cwd, resumeId, prompt, stateDir: opts.stateDir || null }, null, 2) + '\n');
+  }
+  if (opts.stateDir) {
+    fs.mkdirSync(opts.stateDir, { recursive: true });
+    fs.writeFileSync(path.join(opts.stateDir, `${key}.prompt`), prompt);
+  }
+  emitTurnEnd(key);
+  const ref = { harness: 'fake', session, cwd, resumeId };
+  if (window) ref.window = window;
+  return ref;
+}
+
+async function send(ref, text) {
+  const key = refKey(ref);
+  const s = sessions.get(key);
+  if (!s) {
+    // Cross-process fake session: alive iff its marker file exists.
+    const marker = markerFile(key);
+    if (marker && fs.existsSync(marker)) return logSend(key, text);
+    throw new Error(`fake: unknown session ${key}`);
+  }
+  if (!s.alive) throw new Error(`session ${key} is not alive`);
+  s.transcript.push(text);
+  logSend(key, text);
+  emitTurnEnd(key);
+}
+
+// alive(ref) — window-granular refs answer for their own window only.
+// A session-granular ref is read the way tmux reads `=session:`: off whichever
+// window has FOCUS, so ANY live window in the session makes it read alive —
+// including a busy worker masking a dead lieutenant beside it.
+// A marker carrying `unreadable: true` is the tmux nobody could READ — the verb
+// cannot be honored, so it throws with the reason instead of answering "gone".
+// Absence and an unanswered question are different facts, and the board drops
+// worker records on the difference.
+function assertReadable(key) {
+  const marker = markerFile(key);
+  if (!marker || !fs.existsSync(marker)) return;
+  let doc = null;
+  try { doc = JSON.parse(fs.readFileSync(marker, 'utf8')); } catch (e) { return; }
+  if (doc && doc.unreadable) throw new Error(`fake: cannot read session ${key}`);
+}
+
+async function alive(ref) {
+  if (ALIVE_MS) await new Promise((r) => setTimeout(r, ALIVE_MS));
+  if (ref.window) { assertReadable(refKey(ref)); return live(refKey(ref)); }
+  const keys = siblings(ref.session);
+  for (const k of keys) assertReadable(k);
+  return keys.some(live);
+}
+
+// resumable — introspection only: memory survives a resume iff this process
+// still holds the session's transcript under the same resumeId.
+async function resumable(ref) {
+  const s = sessions.get(refKey(ref));
+  return !!(s && ref.resumeId && ref.resumeId === s.resumeId);
+}
+
+async function resume(ref) {
+  const key = refKey(ref);
+  const s = sessions.get(key);
+  if (s && s.alive) return { ...ref };
+  const out = { harness: 'fake', session: ref.session, cwd: ref.cwd, resumeId: ref.resumeId };
+  if (ref.window) out.window = ref.window;
+  if (s && ref.resumeId === s.resumeId) {
+    s.alive = true; // memory (transcript) preserved
+    return { ...out, cwd: s.cwd };
+  }
+  // No matching memory: fresh session under the same name (transcript lost).
+  // golem: `claude --resume <id>` keeps that id even when its transcript is gone, so a ref's id survives.
+  out.resumeId = ref.resumeId || crypto.randomUUID();
+  sessions.set(key, {
+    alive: true,
+    cwd: ref.cwd,
+    resumeId: out.resumeId,
+    transcript: [],
+    hooks: s ? s.hooks : [],
+    turns: 0,
+  });
+  return out;
+}
+
+function onTurnEnd(ref, hook) {
+  const s = get(ref);
+  const entry = { fn: hook, ref };
+  s.hooks.push(entry);
+  return function unsubscribe() {
+    const i = s.hooks.indexOf(entry);
+    if (i !== -1) s.hooks.splice(i, 1);
+  };
+}
+
+// kill(ref) — port verb: end the session for good. Idempotent (unknown or
+// already-dead sessions are a no-op). File-backed mode also removes the
+// marker so a WATCHING process sees alive() flip false.
+// tmux semantics: a window-granular ref takes ONLY its window; a
+// session-granular one takes the whole session — every sibling window with it.
+function kill(ref) {
+  for (const key of (ref.window ? [refKey(ref)] : siblings(ref.session))) {
+    const s = sessions.get(key);
+    if (s) s.alive = false;
+    const marker = markerFile(key);
+    if (marker) { try { fs.unlinkSync(marker); } catch { /* already gone */ } }
+  }
+}
+
+// adoptWindow(ref, window, taken?) -> ref — OPTIONAL capability verb; the real
+// contract is in tmux-session.js. The fake has one pane per key, so there is
+// no window to mis-adopt (`taken` never applies): the live session is simply
+// re-keyed, and the SAME agent (transcript, hooks, marker) answers to
+// `session:window` from now on.
+async function adoptWindow(ref, window) {
+  if (ref.window) return ref;
+  const key = keyOf(ref.session, window);
+  const s = sessions.get(ref.session);
+  if (s) {
+    sessions.delete(ref.session);
+    sessions.set(key, s);
+  }
+  const from = markerFile(ref.session);
+  const to = markerFile(key);
+  if (from && to && fs.existsSync(from)) fs.renameSync(from, to);
+  return { ...ref, window };
+}
+
+// ---------- pane viewing (OPTIONAL capability verbs — see port.js) ----------
+// openPane emits deterministic counter frames on the interval — each frame
+// differs from the last, so change-detecting consumers always deliver — letting
+// server tests assert subscribe → frames → teardown without tmux. In
+// file-backed mode every open/close also appends to <key>.pane.jsonl, so a
+// WATCHING test process can assert refcounting (one open, one close) across
+// the process boundary.
+//   BC_FAKE_PANE_MS   default frame interval (callers' intervalMs still wins)
+//   BC_FAKE_NO_PANE   hides both verbs — the "harness without pane support"
+function logPane(session, event, extra) {
+  const dir = fakeStateDir();
+  if (!dir) return;
+  fs.appendFileSync(path.join(dir, session + '.pane.jsonl'),
+    JSON.stringify({ ts: new Date().toISOString(), session, event, ...extra }) + '\n');
+}
+
+function openPane(ref, opts = {}) {
+  const key = refKey(ref);
+  const onFrame = typeof opts.onFrame === 'function' ? opts.onFrame : () => {};
+  const intervalMs = opts.intervalMs > 0 ? opts.intervalMs
+    : (parseInt(process.env.BC_FAKE_PANE_MS, 10) > 0 ? parseInt(process.env.BC_FAKE_PANE_MS, 10) : 1000);
+  let n = 0;
+  let closed = false;
+  const emit = () => {
+    if (closed) return;
+    n += 1;
+    try { onFrame('fake pane ' + key + ' — frame ' + n + '\n'); } catch { /* subscriber's problem */ }
+  };
+  logPane(key, 'open');
+  const timer = setInterval(emit, intervalMs);
+  timer.unref?.();
+  emit(); // immediate first frame
+  return {
+    close() {
+      if (closed) return;
+      closed = true;
+      clearInterval(timer);
+      logPane(key, 'close');
+    },
+  };
+}
+
+async function paneSnapshot(ref) {
+  return 'fake pane ' + refKey(ref) + ' — snapshot\n';
+}
+
+// paneInput records the keystroke into the same <key>.pane.jsonl the open/close
+// events land in, so a watching test process can assert what the server
+// forwarded. Validation is the SHARED one from port.js, not a copy: a fake that
+// is laxer than the real harness turns route tests green against payloads tmux
+// would choke on, and two copies of a regex are two regexes that drift.
+async function paneInput(ref, input = {}) {
+  const { key, text } = validatePaneInput(input);
+  logPane(refKey(ref), 'input', key ? { key } : { text });
+}
+
+// ---------- slash commands + status (OPTIONAL capability verbs — see port.js) ----------
+// Canned, deterministic, filesystem-free — the whole slash/status stack (server
+// routing, /api/commands, the composer autocomplete, context bars) tests
+// without tmux. A session counts for status the same way alive() counts it:
+// known to this process OR marked live via a BC_FAKE_STATE marker file.
+//   BC_FAKE_NO_COMMANDS   hides all three verbs — the "harness without slash
+//                         commands" (capability-absent degradation under test)
+const FAKE_STATUS = { model: 'fake-model', contextUsed: 50000, contextWindow: 200000 };
+
+function commands() {
+  return SLASH_COMMANDS.map((c) => ({ ...c }));
+}
+
+async function status(ref) {
+  const s = sessions.get(refKey(ref));
+  if (s) return s.alive ? { ...FAKE_STATUS } : null;
+  const marker = markerFile(refKey(ref));
+  return marker && fs.existsSync(marker) ? { ...FAKE_STATUS } : null;
+}
+
+async function runCommand(ref, command) {
+  const line = String(command || '').trim();
+  const name = line.split(/\s+/)[0];
+  if (name === '/help') return helpText(commands());
+  if (name === '/status') {
+    const st = await status(ref);
+    if (!st) throw new Error('fake: no status for ' + refKey(ref));
+    return formatStatus(st);
+  }
+  if (name === '/compact') {
+    await send(ref, line); // same path a real adapter uses: the send machinery
+    return '"' + line + '" submitted to ' + refKey(ref) + ' — the session runs it in-place';
+  }
+  throw new Error('fake: unknown command ' + name + ' (see /help)');
+}
+
+// --- test helpers ---
+
+function transcript(ref) {
+  return [...get(ref).transcript];
+}
+
+function reset() {
+  sessions.clear();
+}
+
+const impl = { spawn, send, alive, resumable, resume, onTurnEnd, kill, adoptWindow, transcript, reset };
+// Pane verbs are OPTIONAL by contract; BC_FAKE_NO_PANE simulates a harness
+// that never implemented them (capability-absent degradation under test).
+if (!process.env.BC_FAKE_NO_PANE) {
+  impl.openPane = openPane;
+  impl.paneSnapshot = paneSnapshot;
+  impl.paneInput = paneInput;
+}
+// Slash commands + status are OPTIONAL too; BC_FAKE_NO_COMMANDS simulates a
+// harness that never implemented them.
+if (!process.env.BC_FAKE_NO_COMMANDS) {
+  impl.commands = commands;
+  impl.runCommand = runCommand;
+  impl.status = status;
+}
+module.exports = impl;

package/src/runtime/harness/package.json

@@ -0,0 +1 @@
+{ "type": "commonjs" }

package/src/runtime/harness/port.js

@@ -0,0 +1,208 @@
+// Vendored from bridge-commander 5bf87e4b harness/port.js (zero-dependency). Local patches are marked 'golem:'.
+'use strict';
+// harness port — the multi-harness contract (docs/api/overview.md, "harness port").
+//
+// The server speaks ONLY this port. An implementation is a module exposing
+// exactly these seven verbs (all may be async):
+//
+//   spawn(cwd, prompt, opts?) -> HarnessRef   birth an agent session
+//   send(ref, text)                           type a message into a session (verified submit)
+//   alive(ref) -> bool                        liveness
+//   resumable(ref, opts?) -> bool             would resume(ref) restore memory? (introspection only)
+//   resume(ref) -> HarnessRef                 reincarnate a dead session with memory when possible
+//   kill(ref)                                 end a session for good (idempotent; dead ref is a no-op)
+//   onTurnEnd(ref, hook) -> unsubscribe()     turn-boundary detection
+//
+// A HarnessRef is a plain, JSON-serializable object; `harness` names the
+// implementation and the rest is that implementation's opaque address:
+//   { harness: 'claude', session: 'bc-<id>', window?: 'w-<id>', cwd: '/abs/path', resumeId?: '<uuid>' }
+// `window` marks a window-granular ref: the agent lives in a named window of
+// a shared session (workers inside their lieutenant's session) instead of
+// owning the whole session.
+//
+// Adding a harness = implementing the seven verbs and registering it here
+// (or shipping it as a builtin module). Nothing else.
+//
+// All seven must EXIST; one that cannot be honored must THROW with the reason
+// rather than pretend — a caller that learns why beats one watching text vanish
+// into a verb that quietly did nothing.
+//
+// OPTIONAL capability verbs: beyond the seven REQUIRED verbs a harness MAY
+// expose extra verbs for features not every harness can honor. They are
+// deliberately NOT validated here — adding one to VERBS would force every
+// harness (the fake included) to implement it and break validation. The
+// server capability-checks at the call site (`typeof impl.openPane ===
+// 'function'`) and degrades gracefully when the verb is absent. Current
+// optional verbs — pane viewing (the UI's 👁 peek):
+//   openPane(ref, { onFrame, intervalMs?, lines? }) -> { close() }
+//       deliver the pane's CURRENT RENDERED SCREEN as successive frames:
+//       onFrame(frameString) fires whenever the content changes (identical
+//       frames are skipped); a frame MAY carry ANSI SGR escapes. close()
+//       stops delivery and releases resources. All async-safe.
+//   paneSnapshot(ref, { lines? }) -> Promise<string>
+//       one-shot capture — the initial paint / non-streaming fallback.
+//   paneInput(ref, { text? | key? }) -> Promise<void>
+//       forward RAW input to the pane: `text` typed literally (multi-line
+//       rides a bracketed paste), `key` ONE tmux key name ('Enter', 'BSpace',
+//       'Up', 'BTab', 'C-c', …). Exactly one of the two; anything else throws,
+//       as does an unusable key name, a pane that is gone, or text past
+//       PANE_INPUT_MAX. Validate with the SHARED validatePaneInput() below —
+//       a harness with its own copy of the rules is a harness that drifts from
+//       them. Deliberately NOT
+//       send(): that one types, settles, Enters and retries until the composer
+//       verifies empty — right for delivering a brief, wrong for a keystroke.
+//       A harness MAY offer paneInput while send() throws: "no composer for a
+//       brief" and "no way to press a key" are different claims.
+//       Implementations that also stream SHOULD speed their feed up briefly
+//       after input, so the echo is not stuck behind the poll.
+// — migration of a session-granular ref to window granularity (the lieutenant
+// whose session it turned out to cohabit with its worker windows):
+//   adoptWindow(ref, window, taken?) -> Promise<HarnessRef|null>
+//       make the SAME running agent addressable as `session:window` without
+//       restarting it. `taken` names windows that belong to someone else and
+//       must never be adopted. null = the agent's window cannot be identified;
+//       the caller keeps the old ref. Idempotent: a ref that already carries a
+//       window comes back unchanged.
+// — and slash commands + session status (the UI composer's "/" and the
+// context bars; agent-status.js holds the shared machinery):
+//   commands(ref?) -> [{ name, description, args? }]
+//       the slash commands this harness answers (/status /compact /help
+//       where applicable; claude adds /autocompact and /output-style — verified
+//       against the binary, the public docs lag behind).
+//       `ref`, when given, scopes the answer to that session — claude's style
+//       list includes the ones installed in the session's own cwd.
+//       `args` is OPTIONAL metadata: [{ value, description }], the values this
+//       command accepts as its single argument, for a composer that wants to
+//       keep completing AFTER the command name (ui/js/slash.js). A harness that
+//       does not send it behaves exactly as before — the picker closes on the
+//       space, as it always did — so this is additive for every existing
+//       implementation. Everything a caller types after the command name is ONE
+//       argument: a `value` may contain spaces, and runCommand must not tokenize
+//       it. The server passes the field through untouched.
+//   runCommand(ref, command, opts?) -> Promise<string>
+//       execute one command line against the session (first token names the
+//       command; arguments ride along); resolves to the reply text. opts is
+//       the same bag spawn/resume take — `stateDir` is the one field that
+//       matters here, since /status reads from it.
+//       Pass-through commands (/compact, claude's /autocompact) type the
+//       LITERAL line through the verified-submit send path — the harness's
+//       own implementation runs in-session; /status formats status(); /help
+//       renders commands(). Unknown names throw — and so does a command whose
+//       argument is missing or unrecognised, BEFORE it does anything: claude's
+//       /output-style writes a setting to disk, and a typo must not sit there
+//       waiting to surprise the next conversation. A command that changes
+//       something the session only reads at STARTUP says WHEN it applies in
+//       its reply (/output-style: the next time this session starts) without
+//       naming a command to get there, which a harness cannot know exists —
+//       no verb here restarts a session on the caller's behalf.
+//   status(ref, opts?) -> Promise<{ model, contextUsed, contextWindow, rateLimits? } | null>
+//       model + context usage read from the files the harness already
+//       writes (transcript / rollout log); null — never a throw — when
+//       nothing is readable. opts.stateDir points at the board's harness
+//       state (codex resolves its thread-id from the session-id file there);
+//       omitting it falls back to whatever the ref alone can answer. rateLimits only where the harness persists
+//       them (codex); claude omits the field.
+
+const VERBS = ['spawn', 'send', 'alive', 'resumable', 'resume', 'kill', 'onTurnEnd'];
+
+// ---------- paneInput payload validation (the port contract, in one place) ----------
+// Lives HERE, not in an implementation, because every harness that offers
+// paneInput must enforce the SAME contract: a fake that is laxer than the real
+// thing turns route tests green against payloads tmux would choke on. port.js
+// has no dependencies, so both the tmux adapters and the fake can require it.
+//
+// KEY_RE — tmux's key-name grammar. Anchored, and no branch can begin with '-':
+// tmux is spawned via execFile (an argv array, so no shell) and sendKey passes
+// `--`, but a name that looks like a flag has no business reaching argv at all.
+// The punctuation branch is the five control keys that are not letters — C-[
+// (Escape on a lot of muscle memory), C-\, C-], C-^, C-_ — every one verified
+// accepted by tmux 3.4. The client emits them, so the grammar must too.
+const KEY_RE = /^(C-|M-|S-)*([A-Za-z0-9]+|[[\\\]^_])$/;
+// One POST must not be able to shove a whole file into a live agent's pane —
+// and, more sharply, must not hand tmux more than tmux can take. Single-line
+// text rides `send-keys -l -- <text>` in ARGV, and a tmux client packs one
+// command into a single imsg: MAX_IMSGSIZE 16384 minus the 16-byte header, so
+// the whole NUL-packed argv must fit in 16368 bytes. Measured against tmux 3.4:
+// `send-keys -t <target> -l -- <text>` succeeds while
+// target.length + text.length <= 16343 and fails at 16344 with "failed to send
+// command" — the same total for an 8-char target and a 49-char one, which is
+// how we know the budget is the command, not the payload. Multi-line text is
+// unconstrained (it rides load-buffer's STDIN), but one cap is honest and does
+// not drift; 16 KB less 512 bytes leaves room for the longest pane target plus
+// the fixed argv words.
+const PANE_INPUT_MAX = 16 * 1024 - 512;
+
+// validatePaneInput(input) -> { key, text } — exactly one of the two is
+// non-empty. Throws with the reason otherwise; callers let it propagate.
+function validatePaneInput(input) {
+  const key = input && input.key != null ? String(input.key) : '';
+  const text = input && input.text != null ? String(input.text) : '';
+  if (key && text) throw new Error('paneInput: pass key or text, not both');
+  if (!key && !text) throw new Error('paneInput: nothing to send (pass key or text)');
+  if (key && !KEY_RE.test(key)) throw new Error(`paneInput: invalid tmux key name "${key}"`);
+  // BYTES, not String.length: argv is UTF-8, so 16384 emoji is 65536 bytes and
+  // would sail past a UTF-16-unit check to die as `spawn E2BIG`.
+  const bytes = Buffer.byteLength(text, 'utf8');
+  if (bytes > PANE_INPUT_MAX) {
+    throw new Error(`paneInput: text too long (${bytes} > ${PANE_INPUT_MAX} bytes)`);
+  }
+  return { key, text };
+}
+
+// Builtins are lazy-required so requiring port.js never drags in tmux/claude
+// machinery for callers that only use the fake.
+const BUILTINS = {
+  claude: './claude-tmux.js',
+  codex: './codex-tmux.js',
+  fake: './fake.js',
+};
+
+const registry = new Map();
+
+function validateImpl(name, impl) {
+  if (!impl || typeof impl !== 'object') {
+    throw new TypeError(`harness "${name}": implementation must be an object`);
+  }
+  for (const verb of VERBS) {
+    if (typeof impl[verb] !== 'function') {
+      throw new TypeError(`harness "${name}": missing verb ${verb}()`);
+    }
+  }
+  return impl;
+}
+
+function registerHarness(name, impl) {
+  if (!name || typeof name !== 'string') throw new TypeError('harness name must be a non-empty string');
+  registry.set(name, validateImpl(name, impl));
+  return impl;
+}
+
+function getHarness(name) {
+  if (registry.has(name)) return registry.get(name);
+  if (Object.prototype.hasOwnProperty.call(BUILTINS, name)) {
+    const impl = validateImpl(name, require(BUILTINS[name]));
+    registry.set(name, impl);
+    return impl;
+  }
+  throw new Error(`unknown harness "${name}" (known: ${[...new Set([...registry.keys(), ...Object.keys(BUILTINS)])].join(', ')})`);
+}
+
+// isHarnessRef — structural check for a persisted/deserialized ref.
+function isHarnessRef(ref) {
+  return !!ref
+    && typeof ref === 'object'
+    && typeof ref.harness === 'string' && ref.harness.length > 0
+    && typeof ref.session === 'string' && ref.session.length > 0
+    && (ref.window === undefined || (typeof ref.window === 'string' && ref.window.length > 0))
+    && typeof ref.cwd === 'string' && ref.cwd.length > 0
+    && (ref.resumeId === undefined || typeof ref.resumeId === 'string');
+}
+
+// harnessFor(ref) — dispatch helper: the implementation a ref belongs to.
+function harnessFor(ref) {
+  if (!isHarnessRef(ref)) throw new TypeError('not a HarnessRef: ' + JSON.stringify(ref));
+  return getHarness(ref.harness);
+}
+
+module.exports = { VERBS, registerHarness, getHarness, isHarnessRef, harnessFor,
+  validatePaneInput, KEY_RE, PANE_INPUT_MAX };