@volter/sdk 0.0.0-stage → 0.5.203

package/src/session/collaboration-types.ts

@@ -0,0 +1,262 @@
+import type { ShareRole } from '../share';
+
+export type CollaborationCapability =
+  | 'view'
+  | 'comment'
+  | 'test'
+  | 'edit'
+  | 'terminal'
+  | 'maintain';
+/**
+ * A collaboration role is a {@link ShareRole} PLUS the local-only `maintainer`,
+ * and it is spelled that way so the relationship is CHECKED. Written as its own
+ * six-member union — which is what it was — the two lists drift with no
+ * compiler signal: a role added to the share wire is simply a role this session
+ * cannot hold, and the only symptom is a participant the UI refuses to promote.
+ */
+export type CollaborationRole = ShareRole | 'maintainer';
+/**
+ * Least authority first; `maintainer` is local-only and has no share role.
+ *
+ * Declared as a `satisfies Record<CollaborationRole, …>` rather than an array
+ * annotated `readonly CollaborationRole[]`, because the array form accepts an
+ * INCOMPLETE list: adding a role to `CollaborationRole` and forgetting it here
+ * compiles, and the only symptom is that `assignableCollaborationRoles` quietly
+ * offers a participant one fewer role than they can hold. A missing key here is
+ * a compile error.
+ */
+const COLLABORATION_ROLE_RANK = {
+  viewer: 0,
+  commenter: 1,
+  tester: 2,
+  editor: 3,
+  terminal: 4,
+  maintainer: 5,
+} as const satisfies Record<CollaborationRole, number>;
+
+export const COLLABORATION_ROLE_ORDER: readonly CollaborationRole[] = (
+  Object.keys(COLLABORATION_ROLE_RANK) as CollaborationRole[]
+).sort((a, b) => COLLABORATION_ROLE_RANK[a] - COLLABORATION_ROLE_RANK[b]);
+
+/**
+ * Which roles a UI may OFFER for one participant. Enforcement is the server's,
+ * always; this only keeps the editor from presenting an option the session
+ * would refuse. A participant that entered through the share gateway carries a
+ * verified `account` and can never reach `maintainer`, nor exceed the ceiling
+ * its invitation set.
+ */
+export function assignableCollaborationRoles(
+  participant: { account: { id: string } | null },
+  ceiling?: CollaborationRole,
+): CollaborationRole[] {
+  if (!participant.account) return [...COLLABORATION_ROLE_ORDER];
+  const remoteLimit = COLLABORATION_ROLE_ORDER.indexOf('terminal');
+  const ceilingIndex = ceiling ? COLLABORATION_ROLE_ORDER.indexOf(ceiling) : remoteLimit;
+  const limit = Math.min(remoteLimit, ceilingIndex < 0 ? remoteLimit : ceilingIndex);
+  return COLLABORATION_ROLE_ORDER.slice(0, limit + 1);
+}
+
+export type ParticipantKind = 'human' | 'agent';
+export type ParticipantStatus = 'active' | 'idle' | 'needs-input' | 'done';
+
+export interface CollaborationParticipantLocation {
+  repositoryId: string;
+  worktreeId: string;
+  sessionId: string;
+}
+
+export interface CollaborationAgentIdentity {
+  harness: string;
+  conversationId: string;
+}
+
+export interface CollaborationCameraPose {
+  x: number;
+  y: number;
+  z: number;
+  targetX: number;
+  targetY: number;
+  targetZ: number;
+  fov: number;
+}
+
+export function isCollaborationCameraPose(value: unknown): value is CollaborationCameraPose {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const camera = value as Record<string, unknown>;
+  const keys = ['x', 'y', 'z', 'targetX', 'targetY', 'targetZ', 'fov'] as const;
+  return (
+    Object.keys(camera).length === keys.length &&
+    keys.every((key) => typeof camera[key] === 'number' && Number.isFinite(camera[key])) &&
+    (camera['fov'] as number) > 0 &&
+    (camera['fov'] as number) < 180
+  );
+}
+
+/**
+ * THE owner of team-message size limits, read by the HTTP route guard and by
+ * `CollaborationSession`'s own methods alike.
+ *
+ * The two used to carry separate numbers and disagree in both directions — the
+ * route accepted 20k of text the session then refused, and refused 50
+ * references the session would have taken — so which error a caller saw
+ * depended on which layer happened to see the message first. Each value here is
+ * the tighter of the pair that split produced.
+ */
+export const TEAM_MESSAGE_LIMITS = {
+  text: 10_000,
+  mentions: 16,
+  mentionLength: 80,
+  references: 32,
+} as const;
+
+export const COLLABORATION_AGENT_MENTIONS = ['agent', 'claude', 'codex'] as const;
+
+export function isCollaborationAgentMention(value: string): boolean {
+  return (COLLABORATION_AGENT_MENTIONS as readonly string[]).includes(value.toLowerCase());
+}
+
+export interface CollaborationPresence {
+  document: string | null;
+  file: string | null;
+  oid: string | null;
+  selection: readonly string[];
+  camera: Readonly<CollaborationCameraPose> | null;
+  gesture: Readonly<Record<string, unknown>> | null;
+  playtest?: {
+    id: string;
+    play: 'starting' | 'ready' | 'error';
+    networking: 'not-declared' | 'connecting' | 'ready' | 'error';
+    roomName: string | null;
+    problem: string | null;
+  } | null;
+}
+
+export interface CollaborationParticipant {
+  participantId: string;
+  /** Verified Volter account authority. Null only for local-only host/agent
+   * participants that did not enter through a public share gateway. */
+  account: { id: string; email: string; name?: string } | null;
+  displayName: string;
+  kind: ParticipantKind;
+  color: string;
+  status: ParticipantStatus;
+  location: CollaborationParticipantLocation | null;
+  agent: CollaborationAgentIdentity | null;
+  role: CollaborationRole;
+  capabilities: readonly CollaborationCapability[];
+  connectedAt: string;
+  lastSeenAt: string;
+  presence: CollaborationPresence;
+}
+
+export interface CollaborationAuthorProjection {
+  participantId: string;
+  account: { id: string; email: string; name?: string } | null;
+  displayName: string;
+  kind: ParticipantKind;
+  color: string;
+  location: CollaborationParticipantLocation | null;
+}
+
+const PARTICIPANT_COLORS = [
+  '#4f8cff',
+  '#e45c9d',
+  '#20a87a',
+  '#a46de8',
+  '#d9782d',
+  '#2f9eb8',
+  '#ca4f55',
+  '#6f9f32',
+] as const;
+
+export function collaborationParticipantColor(identity: string): string {
+  let hash = 2_166_136_261;
+  for (const codePoint of identity) {
+    hash ^= codePoint.codePointAt(0) ?? 0;
+    hash = Math.imul(hash, 16_777_619);
+  }
+  return PARTICIPANT_COLORS[(hash >>> 0) % PARTICIPANT_COLORS.length]!;
+}
+
+export type TeamMessageReference =
+  | { type: 'worktree'; worktreeId: string }
+  | { type: 'revision'; revision: number }
+  | { type: 'file'; path: string; revision: number }
+  | { type: 'oid'; oid: string; revision: number }
+  | { type: 'asset'; path: string; revision: number }
+  | { type: 'screenshot'; id: string; revision: number }
+  | { type: 'playtest'; id: string; revision: number }
+  | { type: 'diff'; fromRevision: number; toRevision: number };
+
+export interface TeamMessage {
+  id: string;
+  authorId: string;
+  author: CollaborationAuthorProjection;
+  text: string;
+  mentions: readonly string[];
+  references: readonly TeamMessageReference[];
+  threadId: string | null;
+  editedAt: string | null;
+  deletedAt: string | null;
+  reactions: Readonly<Record<string, readonly string[]>>;
+  revision: number;
+  createdAt: string;
+}
+
+export interface SourceRevision {
+  revision: number;
+  authorId: string;
+  author: CollaborationAuthorProjection;
+  source: 'editor' | 'filesystem';
+  resources: readonly { path: string; sha: string | null }[];
+  createdAt: string;
+}
+
+export interface CollaborationAuditEvent {
+  id: string;
+  type: 'join' | 'leave' | 'role' | 'revision' | 'message' | 'agent' | 'playtest' | 'git';
+  participantId: string;
+  createdAt: string;
+  detail: Readonly<Record<string, unknown>>;
+}
+
+export interface TeamPlaytest {
+  id: string;
+  revision: number;
+  seed: number;
+  roomKey: string;
+  startedBy: string;
+  startedAt: string;
+}
+
+export interface CollaborationSnapshot {
+  sequence: number;
+  revision: number;
+  activePlaytest: TeamPlaytest | null;
+  participants: readonly CollaborationParticipant[];
+  messages: readonly TeamMessage[];
+  revisions: readonly SourceRevision[];
+  audit: readonly CollaborationAuditEvent[];
+}
+
+export type CollaborationEventChannel =
+  | 'participants'
+  | 'presence'
+  | 'messages'
+  | 'revisions'
+  | 'audit'
+  | 'team-test';
+
+export interface CollaborationEvent {
+  sequence: number;
+  channel: CollaborationEventChannel;
+  createdAt: string;
+  payload: unknown;
+}
+
+export interface CollaborationResume {
+  cursor: number;
+  reset: boolean;
+  events: readonly CollaborationEvent[];
+  snapshot?: CollaborationSnapshot;
+}

package/src/session/command-table.ts

@@ -0,0 +1,327 @@
+import { MAX_DOCUMENT_KEY_HOLD_MS } from '../document-probe';
+
+/**
+ * THE RELAY COMMAND VOCABULARY, in one typed table.
+ *
+ * A relay command's type string used to be answered by two independent
+ * switches that had to agree and were never checked against each other:
+ * `command-listener.ts`'s dispatch (what the command DOES) and
+ * `server/server-utils.ts`'s `relayCommandTimeoutMs` (how long the server
+ * waits for it). A command missing from the second one did not fail — it
+ * silently took the generic 5s default, which undercut a client's 60s hold, so
+ * the uninformative timer won every race and sent a real investigation looking
+ * for a dead editor.
+ *
+ * This table is the single source. Adding a command means adding a ROW here:
+ * the dispatch switch keys off `RelayCommandType`, so a case with no row does
+ * not compile, and a row with no case fails the exhaustiveness check in that
+ * switch's `default`. The server imports the timeout column rather than
+ * restating it.
+ *
+ * `timeoutMs` is the budget for the WORK. Delivery has its own, much shorter
+ * budget (`RELAY_DELIVERY_ACK_MS`, clamped by `RELAY_DELIVERY_MAX_WAIT_MS`) —
+ * see `server/server-utils.ts`, which explains why the two are separate.
+ */
+
+/**
+ * The generic budget. Most commands are a synchronous edit against the live
+ * editor and answer in milliseconds; the rows that override this are the ones
+ * that boot a game, rasterize something, or hand control to a game's own code.
+ */
+export const DEFAULT_RELAY_COMMAND_TIMEOUT_MS = 5_000;
+
+interface RelayCommandSpec {
+  /** How long the relay waits for this command to FINISH. */
+  readonly timeoutMs: number;
+  /** Whether command completion owes a tree-scale status derivation. */
+  readonly derivedRefresh: RelayCommandDerivedRefresh;
+}
+
+export type RelayCommandDerivedRefresh = 'none' | 'if-content-changed' | 'always';
+
+const noDerivedRefresh = (timeoutMs = DEFAULT_RELAY_COMMAND_TIMEOUT_MS): RelayCommandSpec => ({
+  timeoutMs,
+  derivedRefresh: 'none',
+});
+
+const refreshIfContentChanged = (
+  timeoutMs = DEFAULT_RELAY_COMMAND_TIMEOUT_MS,
+): RelayCommandSpec => ({ timeoutMs, derivedRefresh: 'if-content-changed' });
+
+const alwaysRefresh = (timeoutMs = DEFAULT_RELAY_COMMAND_TIMEOUT_MS): RelayCommandSpec => ({
+  timeoutMs,
+  derivedRefresh: 'always',
+});
+
+/**
+ * Every command the editor's relay accepts, and how long it waits for each one
+ * to answer. Pure and exported so the table is testable without booting a
+ * server and standing through a real 5-second expiry.
+ *
+ * The rule the table encodes: the budget belongs to whoever the ack is
+ * actually gated on. An ordinary editor interaction ("select this entity") is
+ * gated on the editor and must fail fast — 5s. Everything with its own entry
+ * is gated on something slower and outside the editor's control:
+ *
+ * - `capture-asset-preview` loads a model, renders four views and encodes
+ *   five PNGs before acknowledging.
+ * - `capture-active-document` can wait for an ingested canvas's next render,
+ *   composite its canvas and DOM layers, sample flatness, and encode the PNG.
+ *   It is not an ordinary editor read. Measured in Doctor on racing-game under
+ *   SwiftShader: the 5s default expired while the page kept rasterizing; the
+ *   walk retried, parked more captures behind it, and `stop` then 504ed behind
+ *   work the relay had already told its caller was over.
+ * - `active-tab` may synchronously mount a component board before its result can
+ *   be serialized. The Unity FPS import has 178 stories: the page RECEIVED the
+ *   command in 0.9s but its first board activation answered after the generic
+ *   5s budget, while heartbeats continued throughout. This is editor work, but
+ *   it is not a millisecond chrome toggle when the destination mounts a board.
+ * - `select` and `inspect` may synchronously publish the selected subject and
+ *   compose its inspector after a cold remount. The translated Unity FPS scene
+ *   has 4,458 authored objects: Doctor measured both commands received by a
+ *   beating tab yet still working past 5s, which filed seven false `play-stall`
+ *   errors and made a source value that had survived the remount look unreadable.
+ * - `set-inspection-field`, `remove-inspection-field`, and
+ *   `run-inspection-action` are authored WRITES —
+ *   the same dialect writer, the same pipe, the same budget; removing an
+ *   attribute re-parses and rewrites the module exactly as setting one does.
+ *   For a source-backed root
+ *   that write is server work the tab waits on: the planner re-parses the
+ *   game's own module, the writer rewrites the literal, and a vendored game's
+ *   lock is re-hashed and recorded in the same gesture. Measured on the
+ *   racing-game ingest, where the tab is also servicing a game that logs every
+ *   frame: EVERY transform write came back 504 at the 5s default while the
+ *   same tab answered `select`/`inspect`/`hierarchy` in the same second — so
+ *   the caller was told "no editor answered" about a write that was merely
+ *   slow, which is the failure mode this whole table exists to stop.
+ * The PLAY verbs and the whole page-bridge family carry their budgets in
+ * `@volter/editor-game`'s own contributed rows now, for the same reasons and with the
+ * same numbers: `play` waits on the project's entire async `setup()`; `stop`
+ * waits on a teardown chain; `bridge-recording-export` steps a paused game
+ * frame by frame and encodes a video; `bridge-call` runs GAME code;
+ * `page-script` and `game-eval` run a step the CALLER wrote; and
+ * `bridge-screenshot` rasterizes the whole game stack.
+ *
+ * That family is the reason this table exists as a named thing. Their
+ * client (`@volter/game-live`'s `RelayTransport`) already applies its own per-leg
+ * `AbortSignal.timeout` — 60s for invoke/page-script, 15s for screenshot —
+ * and the server's generic 5s was UNDERCUTTING it, so the server's timer won
+ * every race. That mattered for the message, not just the duration: the
+ * client's own expiry produces `RELAY_UNREACHABLE` plus a "split the hold into
+ * shorter calls" hint, while the server's produces "Command timed out —
+ * editor connected but did not respond", which names nothing and sent a real
+ * investigation looking for a dead editor. Keep each entry >= its client-side
+ * counterpart so the informative timer is always the one that fires.
+ *
+ * Rows without an explicit budget take {@link DEFAULT_RELAY_COMMAND_TIMEOUT_MS}.
+ */
+export const RELAY_COMMANDS = {
+  'session-prepare-close': noDerivedRefresh(120_000),
+  // ---- Selection ---------------------------------------------------------
+  select: noDerivedRefresh(30_000),
+  'select-multiple': noDerivedRefresh(),
+  'select-all': noDerivedRefresh(),
+
+  // ---- Editor chrome ------------------------------------------------------
+  'viewport-tab': noDerivedRefresh(),
+  // Focusing a panel is dock work, but its ack WAITS for the dock to report
+  // the panel focused (`revealStaticPanel`), so keep the relay past that wait.
+  'show-panel': noDerivedRefresh(15_000),
+  'active-tab': alwaysRefresh(30_000),
+  // Opening and presenting can await the inspector and a fresh source build.
+  // Keep their relay budget aligned with capture-active-document below.
+  'open-asset-tab': alwaysRefresh(30_000),
+  // The selection half: it changes what the Inspector shows, so the derived
+  // state a caller reads next must be refreshed like the open half's.
+  'select-asset': alwaysRefresh(),
+  'close-asset-tab': alwaysRefresh(),
+  'toggle-command-palette': noDerivedRefresh(),
+  'toggle-console': noDerivedRefresh(),
+  // RELOAD THE EDITOR PAGE — `@volter/game-live`'s `page.reload()`, the one page verb
+  // no step can express. It is the HOST's, not a package's: reloading the tab
+  // is what the tab is, and until walk 5 it was a `@volter/editor-game` command
+  // contribution, so a project without that package — every model project —
+  // answered `unknown command type "page-reload"` for a door `@volter/game-live`
+  // documents as general (measured on a `cyclotron create` scaffold,
+  // 2026-09-21). The handler schedules the navigation for the next task so
+  // this ack can travel before the channel is torn down; the client waits for
+  // the new page load on the server's own tab table.
+  'page-reload': alwaysRefresh(),
+  // Acks the ARRANGEMENT, not the intent: the dock clears and rebuilds on the
+  // next paint, so the handler waits for that rebuild (see
+  // `workspace-presets.ts`'s applied signal). Still ordinary editor work.
+  'set-workspace': noDerivedRefresh(),
+  // A style bundle is chrome appearance; the document is untouched.
+  'set-style': noDerivedRefresh(),
+  'set-appearance': noDerivedRefresh(),
+  // A view's viewport presentation (lighting, backdrop, overlays); the document is untouched.
+  'viewport-presentation': noDerivedRefresh(),
+  'present-view': alwaysRefresh(30_000),
+  'current-view': refreshIfContentChanged(),
+  // A read of the resolved document table; changes nothing.
+  'document-table': noDerivedRefresh(),
+
+  // ---- Inspection and authoring ------------------------------------------
+  // The inspection writes go through the project mutation path, which touches
+  // the filesystem and may wait on a collaboration revision.
+  inspect: refreshIfContentChanged(30_000),
+  hierarchy: refreshIfContentChanged(),
+  'expand-hierarchy-all': refreshIfContentChanged(),
+  'collapse-hierarchy-all': refreshIfContentChanged(),
+  'document-probe': refreshIfContentChanged(),
+  // A step against the open document's session can edit it (`ctx.ops.mesh.*`).
+  // Project-owned document code can rebuild an entire Model, just as a
+  // page-script can rebuild a game. Give both the same execution budget.
+  'document-script': refreshIfContentChanged(60_000),
+  'set-inspection-field': alwaysRefresh(30_000),
+  'remove-inspection-field': alwaysRefresh(30_000),
+  // `extract-component` and `fork-component` left this table with their menus
+  // (`@volter/editor-game/contributions/component-verbs.command.ts`), which carries
+  // both budgets forward row for row.
+  // The hierarchy context menu's structure verbs, over the control door. Every
+  // one of them rewrites the game's own source, so they refresh like a write.
+  'structure-op': alwaysRefresh(30_000),
+  'run-inspection-action': alwaysRefresh(30_000),
+  // `editor.command(id, args)` — ONE workbench/view command by id. What it
+  // does is the command's, so nothing here can know whether the document
+  // changed: `alwaysRefresh` is the honest budget, the same one every other
+  // "run something the editor does not model" verb takes.
+  'run-command': alwaysRefresh(30_000),
+  undo: alwaysRefresh(),
+  redo: alwaysRefresh(),
+  // `open` WAITS FOR THE PROJECT ADAPTER, for the same reason `play` waits on
+  // the project's async `setup()`: on a cold session the adapter's scene table
+  // is not there yet, and the door's whole job is to put a document on screen
+  // once it is. MEASURED on three cold the editor's `edit` command sessions over a
+  // `--template models` probe — 6025 / 6831 / 6474 ms from tab-connected to
+  // the entry being listed, every one of them first refusing with
+  // `SCENE_TABLE_UNAVAILABLE`. At the 5 s default the relay's timer won that
+  // race and the caller was told "the tab did not respond" about a door that
+  // was merely waiting, which is the exact failure this table exists to stop.
+  // 30 s sits above `openSceneTableEntryWhenListed`'s own 15 s bound so the
+  // INFORMATIVE refusal (the scene table's, naming the known ids) is always
+  // the one that fires.
+  open: alwaysRefresh(30_000),
+
+  // ---- Rasterizing --------------------------------------------------------
+  // Everything here renders something and reads pixels back.
+  'capture-active-document': refreshIfContentChanged(30_000),
+  // The whole editor page through the same compositor; the foreignObject leg
+  // over a full dock takes seconds, not milliseconds.
+  'capture-editor-chrome': refreshIfContentChanged(30_000),
+
+  // The ONE door onto a view's verbs (`@volter/sdk/views`, U8 ruling 1).
+  // A verb either READS the view or moves its own transform; neither touches
+  // a document, so nothing derived refreshes.
+
+  // The THREE VIEWPORT'S verbs — framing, the camera, view presets, the open
+  // Object3D document's orbit/turntable/frame, the viewport photograph and the
+  // display and transform toggles — are its own command contribution
+  // (`viewport-commands.ts`), each budget on its contributed row.
+
+  // The BLENDER lane's ten verbs are `@volter/editor-blender`'s
+  // `contributions/blender.command.ts` (WORK.md §The workbench, item D) —
+  // each row's budget travelled with it, onto the contributed spec the page
+  // reports to the server. `capture-story-variants` made the same move, to the
+  // kit's own `stories/story-capture-command.ts`: it
+  // mounts each CSF export, waits for the DOM to settle, rasterizes it through
+  // the `foreignObject` leg and tiles the sheet, so its budget scales with the
+  // file's export count rather than with any single render — 120 s, measured
+  // on a real 10-story HUD file that expired the default outright, and stated
+  // now on the contributed row instead of here.
+} as const satisfies Record<string, RelayCommandSpec>;
+
+/** Every command type the relay accepts. The dispatch switch keys off this. */
+export type RelayCommandType = keyof typeof RELAY_COMMANDS;
+
+/** The vocabulary as data — what a guard or a tool enumerates. */
+export const RELAY_COMMAND_TYPES = Object.keys(RELAY_COMMANDS) as readonly RelayCommandType[];
+
+export function isRelayCommandType(value: unknown): value is RelayCommandType {
+  return typeof value === 'string' && Object.hasOwn(RELAY_COMMANDS, value);
+}
+
+/**
+ * How long the relay waits for a command to finish. An unrecognized type gets
+ * the generic budget rather than an error: the relay's job is to hand the
+ * string to the tab and let the TAB say it does not know it.
+ */
+export function relayCommandTimeoutMs(type: unknown, command?: Record<string, unknown>): number {
+  const base = isRelayCommandType(type)
+    ? RELAY_COMMANDS[type].timeoutMs
+    : DEFAULT_RELAY_COMMAND_TIMEOUT_MS;
+  // A held key answers after release. Its requested duration is work, not a
+  // stalled tab; ordinary probes retain their short completion budget.
+  if (type === 'document-probe' && command?.['step'] && typeof command['step'] === 'object') {
+    const step = command['step'] as Record<string, unknown>;
+    const hold = step['holdMs'];
+    if (step['action'] === 'key' && typeof hold === 'number' && Number.isFinite(hold) &&
+        hold >= 0 && hold <= MAX_DOCUMENT_KEY_HOLD_MS) return base + Math.ceil(hold);
+  }
+  return base;
+}
+
+/** The status-derivation policy owned by the same command row as its timeout. */
+export function relayCommandDerivedRefresh(type: unknown): RelayCommandDerivedRefresh {
+  return isRelayCommandType(type) ? RELAY_COMMANDS[type].derivedRefresh : 'always';
+}
+
+/**
+ * The subset an INGEST session answers itself (`ingest/ingest-play-commands.ts`).
+ * A captured ingest is not a host-mounted root, so first-party play would tear
+ * its mount down; these five are dispatched against the ingest surface instead.
+ *
+ * Plain strings, not `RelayCommandType`: the five verbs left this table for
+ * `@volter/editor-game`'s `play.command.ts` when Play left the host (WORK.md §The
+ * workbench, P3b), and the ingest latch runs in `handleCommand`'s PROLOGUE —
+ * before any contributed handler is looked up — so a captured ingest still
+ * answers them first. The latch moves with ingest in P4.
+ */
+export const INGEST_PLAY_COMMAND_TYPES = [
+  'play',
+  'stop',
+  'pause',
+  'resume',
+  'step',
+] as const satisfies readonly string[];
+
+export type IngestPlayCommandType = (typeof INGEST_PLAY_COMMAND_TYPES)[number];
+
+export function isIngestPlayCommandType(value: unknown): value is IngestPlayCommandType {
+  return (INGEST_PLAY_COMMAND_TYPES as readonly string[]).includes(value as string);
+}
+
+/**
+ * THE ANSWER SHAPE, the other column of the same vocabulary — what a tab posts
+ * back to `/__editor/command-result` for a command it just ran.
+ *
+ * Same rule as the timeout column above, for the same reason: the relay has two
+ * ends in two compilation units — the browser that PRODUCES this
+ * (`command-listener.ts`) and the server that settles and re-serves it
+ * (`server/server-utils.ts`, `server/routes/control-plane.ts`) — and each used
+ * to declare its own copy. They had already drifted on the field that matters
+ * most: the browser's said `ok: boolean` and the server's said `ok?: boolean`,
+ * so server code could read a result that never says whether it worked. Both
+ * files already import this module (so does `ingest/ingest-play-commands.ts`,
+ * which restated the shape a third time), so there is no new dependency here.
+ *
+ * `ok` is REQUIRED because the producer always writes it: every browser exit
+ * (`structuredErrorResult`, `commandThrewResult`, every handler's return) and
+ * every server-side settle (`settlePendingCommand`'s callers, all of which pair
+ * `timedOut: true` with `ok: false`) sets it. A payload arriving from off the
+ * wire is narrowed where it enters — `handleCommandResult` — not by weakening
+ * this type.
+ *
+ * `timedOut` is deliberately NOT here: no tab produces it. It is the SERVER's
+ * own verdict for a command no tab answered, so it lives on the server's
+ * `RelayedCommandResult` extension beside the code that sets it.
+ */
+export interface CommandResult {
+  ok: boolean;
+  error?: string;
+  /** Payload for commands that answer with data (`capture-viewport`'s base64
+   *  PNG, the debug-seam reads). On the failure path it carries structured
+   *  markers (`{ code: 'UNKNOWN_COMMAND_TYPE' }`, registered-name lists) the
+   *  SDK matches on — never message prose. */
+  data?: Record<string, unknown>;
+}

package/src/session/discovery.ts

@@ -0,0 +1,100 @@
+/** Registered-session discovery; never selects another project's session. */
+import { readLiveRegisteredSessions, servedProjectAnswer } from './registry-format.js';
+export { servedProjectAnswer } from './registry-format.js';
+
+export const EDITOR_SESSION_DISCOVERY_TIMEOUT_MS = 2000;
+
+export const EDITOR_PROBE_TIMEOUT_MS = 1500;
+
+export class EditorTimeoutError extends Error {
+  constructor(label: string, ms: number) {
+    super(`${label} timed out after ${ms}ms`);
+    this.name = 'EditorTimeoutError';
+  }
+}
+
+export function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T> {
+  return new Promise<T>((resolvePromise, reject) => {
+    const timer = setTimeout(() => reject(new EditorTimeoutError(label, ms)), ms);
+    promise.then(
+      (v) => {
+        clearTimeout(timer);
+        resolvePromise(v);
+      },
+      (err) => {
+        clearTimeout(timer);
+        reject(err instanceof Error ? err : new Error(String(err)));
+      },
+    );
+  });
+}
+
+export interface EditorSessionInfo {
+  /** The port this session's dev server is bound to. */
+  port: number;
+  /** Canonical project root path currently open, or null when none. */
+  project: string | null;
+  /** Dev-server process id, when known from the local session registry (null for an unregistered/legacy server the caller only probed by port). */
+  pid: number | null;
+  /** Exact explicitly targeted editor origin/base URL, including protocol and host. */
+  url?: string;
+  /**
+   * Why this server cannot DESCRIBE the `project` it is serving — its
+   * manifest's own parse/validation failure, naming the failing key. `null`
+   * when the project reads fine, and `undefined` from a probe that did not ask
+   * (or a server too old to say). See {@link servedProjectAnswer}: a session in
+   * this state is still THIS project's session, and callers must report the
+   * reason rather than treat it as no session at all.
+   */
+  manifestError?: string | null;
+}
+
+async function fetchJson(url: string, timeoutMs: number): Promise<unknown> {
+  const res = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+  if (!res.ok) throw new Error(`GET /__editor/project returned HTTP ${res.status}`);
+  return await res.json();
+}
+
+function baseUrl(session: EditorSessionInfo): string {
+  return session.url ?? `http://127.0.0.1:${session.port}`;
+}
+
+export interface SessionListingTransport { listSessions(timeoutMs: number): Promise<EditorSessionInfo[]>; }
+export class HttpSessionDiscovery implements SessionListingTransport {
+  async listSessions(timeoutMs: number): Promise<EditorSessionInfo[]> {
+    const registered = readLiveRegisteredSessions();
+    const perProbeTimeout = Math.min(EDITOR_PROBE_TIMEOUT_MS, Math.max(200, timeoutMs));
+    const failures: string[] = [];
+    const probes = await Promise.all(
+      registered.map(async (s) => {
+        try {
+          const body = await fetchJson(
+            `${baseUrl({ port: s.port, project: null, pid: s.pid })}/__editor/project`,
+            perProbeTimeout,
+          );
+          const served = servedProjectAnswer(body);
+          const info: EditorSessionInfo = {
+            port: s.port,
+            project: served.path,
+            pid: s.pid,
+            manifestError: served.manifestError,
+          };
+          return info;
+        } catch (error) {
+          const detail = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+          failures.push(`port ${s.port}: ${detail}`);
+          return undefined;
+        }
+      }),
+    );
+    const sessions = probes.filter((p): p is EditorSessionInfo => p !== undefined);
+    // A readable registry with registered live processes is not an empty
+    // registry just because every HTTP discovery request failed. Keep any
+    // verified sessions usable, but refuse an entirely unanswered inventory
+    // rather than telling the caller to launch a second editor.
+    if (registered.length > 0 && sessions.length === 0) {
+      throw new Error(`Registered editor sessions could not be inspected: ${failures.join('; ')}`);
+    }
+    return sessions;
+  }
+}