@openscout/protocol 0.2.64 → 0.2.82

package/dist/terminal-sessions.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Terminal session registry.
+ *
+ * The durable noun is a HARNESS SESSION — a stable agent session identified by
+ * its harness-native source id and resumable via a resume command. A harness
+ * session is *materialized* through one or more disposable TERMINAL SURFACES
+ * (tmux, zellij, future ssh/host-control). Backends are interchangeable: the
+ * source session id is the stable key; the surface is the throwaway shell.
+ *
+ * This module defines the shared contract used by `scout session intake`
+ * (which writes the record), the runtime store (which persists it), the
+ * web/runtime APIs (which list it + materialize surfaces), and the app
+ * terminal UI (which reads it to attach/observe/take over).
+ *
+ * Terminal scrollback is never imported as Scout messages — a surface is a
+ * relay target, not a message source.
+ */
+import type { TerminalHostId, TerminalSurfaceId } from "./terminal-surface-id.js";
+/** Lifecycle of a single materialized surface. */
+export type TerminalSurfaceState = "live" | "detached" | "exited";
+/**
+ * Relay descriptor for one surface.
+ *
+ * The per-backend optional fields are legacy: they are what a relay built
+ * before host adapters expects to find, and they are only populated for the
+ * hosts that predate the registry. A new host adds an adapter, not a field —
+ * `backend` plus `sessionName` is the whole contract.
+ */
+export type TerminalSurfaceRelay = {
+    backend: TerminalHostId;
+    sessionName: string;
+    tmuxSession?: string;
+    zellijSession?: string;
+    zellijPaneId?: string;
+};
+/** One disposable terminal surface a harness session has been materialized through. */
+export type TerminalSurface = {
+    /**
+     * Opaque durable handle for this surface. Absent on records written before
+     * surface ids existed; derive one with `terminalSurfaceIdForSurface`.
+     */
+    surfaceId?: TerminalSurfaceId;
+    /** Host that owns the surface. Registered adapters may add hosts the union does not name. */
+    backend: TerminalHostId;
+    /** Backend session name (e.g. tmux target, zellij session). Secondary metadata. */
+    sessionName: string;
+    paneId: string | null;
+    attachCommand: string[];
+    observeCommand: string[] | null;
+    relay: TerminalSurfaceRelay;
+    /** Lifecycle state; absent means unknown / not yet observed. */
+    state?: TerminalSurfaceState;
+    /**
+     * Zellij requires a short socket dir on macOS (the default $TMPDIR exceeds the
+     * Unix socket-path length limit). Any relay attaching to a Scout-created zellij
+     * surface must preserve this, or it lands in a different server namespace.
+     */
+    socketDir?: string;
+};
+/**
+ * Durable registry record: a stable harness session plus the disposable
+ * terminal surfaces it owns. Re-materializing in another backend appends a
+ * surface; it never changes the record identity.
+ */
+export type TerminalSessionRecord = {
+    /** Stable Scout record id (derived from harness + sourceSessionId by default). */
+    id: string;
+    harness: string;
+    /** Harness-native session id — the stable identity across backends. */
+    sourceSessionId: string;
+    cwd: string;
+    resumeCommand: string;
+    /**
+     * Where the record came from. `registry` records are Scout-owned harness
+     * sessions with a real harness and resume command; `discovered` records are
+     * live multiplexer sessions observed on the host, for which both are unknown
+     * and must be left empty rather than filled with the backend and attach argv.
+     * Absent means `registry`.
+     */
+    origin?: "registry" | "discovered";
+    surfaces: TerminalSurface[];
+    createdAt: number;
+    updatedAt: number;
+    metadata?: Record<string, unknown>;
+};
+/** Upsert input for a registry record. Timestamps + id are assigned by the store. */
+export type TerminalSessionRecordInput = {
+    /** Optional explicit id; defaults to a deterministic id from harness + sourceSessionId. */
+    id?: string;
+    harness: string;
+    sourceSessionId: string;
+    cwd: string;
+    resumeCommand: string;
+    surfaces?: TerminalSurface[];
+    metadata?: Record<string, unknown>;
+};
+/**
+ * The durable handle for a surface. Prefers the stored id and derives the same
+ * value from the surface's address otherwise, so a record written before
+ * surface ids existed resolves to the id it would be issued today.
+ */
+export declare function terminalSurfaceIdForSurface(surface: Pick<TerminalSurface, "surfaceId" | "backend" | "sessionName" | "paneId">, options?: {
+    nodeId?: string | null;
+}): TerminalSurfaceId;
+/** Where a match is being evaluated, for the parts of matching that are node-scoped. */
+export type TerminalSurfaceMatchScope = {
+    /**
+     * This host's own Scout node id, when the caller knows it. A surface observed
+     * with no node in its id was observed HERE, so this is the only node whose
+     * handles may claim it.
+     */
+    localNodeId?: string | null;
+};
+/**
+ * Whether a handle scoped to `handleNodeId` may address a surface scoped to
+ * `surfaceNodeId`.
+ *
+ * Three cases, and the third is the one a review reproduced:
+ *
+ * - Both sides name a node: they must name the same one. Without this a handle
+ *   for one node matched an identically named session on another.
+ * - The handle names none: it is a legacy key, which names no machine and must
+ *   keep matching whatever it finds.
+ * - The handle names a node and the OBSERVATION does not. A node-less
+ *   observation is by definition local — it is a session this host just listed
+ *   — so only the local node's handle can be the one it belongs to. Letting any
+ *   node-scoped handle match it meant handles for `node-a` and `node-b` both
+ *   bound to one discovered local session, and both workspaces reported it
+ *   Running: one session proving two machines live. A foreign handle never
+ *   matches, and when this host does not know its own node id it cannot prove
+ *   the handle is local either, so it does not claim it.
+ */
+export declare function terminalSurfaceNodeScopeMatches(input: {
+    handleNodeId: string | null;
+    surfaceNodeId: string | null;
+    localNodeId?: string | null;
+}): boolean;
+/** The node a surface belongs to, which lives inside its own opaque id. */
+export declare function terminalSurfaceNodeId(surface: Pick<TerminalSurface, "surfaceId">): string | null;
+/** True when a handle addresses this surface, in either the opaque or legacy form. */
+export declare function terminalSurfaceMatchesId(surface: Pick<TerminalSurface, "surfaceId" | "backend" | "sessionName" | "paneId">, handle: string | null | undefined, scope?: TerminalSurfaceMatchScope): boolean;
+//# sourceMappingURL=terminal-sessions.d.ts.map

package/dist/terminal-sessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-sessions.d.ts","sourceRoot":"","sources":["../src/terminal-sessions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAElF,kDAAkD;AAClD,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,UAAU,GAAG,QAAQ,CAAC;AAElE;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,EAAE,cAAc,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,uFAAuF;AACvF,MAAM,MAAM,eAAe,GAAG;IAC5B;;;OAGG;IACH,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAC9B,6FAA6F;IAC7F,OAAO,EAAE,cAAc,CAAC;IACxB,mFAAmF;IACnF,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,cAAc,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAChC,KAAK,EAAE,oBAAoB,CAAC;IAC5B,gEAAgE;IAChE,KAAK,CAAC,EAAE,oBAAoB,CAAC;IAC7B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,kFAAkF;IAClF,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,eAAe,EAAE,MAAM,CAAC;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,UAAU,GAAG,YAAY,CAAC;IACnC,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CAAC;AAEF,qFAAqF;AACrF,MAAM,MAAM,0BAA0B,GAAG;IACvC,2FAA2F;IAC3F,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAC;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,IAAI,CAAC,eAAe,EAAE,WAAW,GAAG,SAAS,GAAG,aAAa,GAAG,QAAQ,CAAC,EAClF,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAO,GACvC,iBAAiB,CAQnB;AAED,wFAAwF;AACxF,MAAM,MAAM,yBAAyB,GAAG;IACtC;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,+BAA+B,CAAC,KAAK,EAAE;IACrD,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B,GAAG,OAAO,CAKV;AAED,2EAA2E;AAC3E,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,IAAI,CAAC,eAAe,EAAE,WAAW,CAAC,GAC1C,MAAM,GAAG,IAAI,CAEf;AAED,sFAAsF;AACtF,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,IAAI,CAAC,eAAe,EAAE,WAAW,GAAG,SAAS,GAAG,aAAa,GAAG,QAAQ,CAAC,EAClF,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACjC,KAAK,GAAE,yBAA8B,GACpC,OAAO,CAYT"}

package/dist/terminal-sessions.js

@@ -0,0 +1,81 @@
+/**
+ * Terminal session registry.
+ *
+ * The durable noun is a HARNESS SESSION — a stable agent session identified by
+ * its harness-native source id and resumable via a resume command. A harness
+ * session is *materialized* through one or more disposable TERMINAL SURFACES
+ * (tmux, zellij, future ssh/host-control). Backends are interchangeable: the
+ * source session id is the stable key; the surface is the throwaway shell.
+ *
+ * This module defines the shared contract used by `scout session intake`
+ * (which writes the record), the runtime store (which persists it), the
+ * web/runtime APIs (which list it + materialize surfaces), and the app
+ * terminal UI (which reads it to attach/observe/take over).
+ *
+ * Terminal scrollback is never imported as Scout messages — a surface is a
+ * relay target, not a message source.
+ */
+import { formatTerminalSurfaceId, parseTerminalSurfaceId } from "./terminal-surface-id.js";
+/**
+ * The durable handle for a surface. Prefers the stored id and derives the same
+ * value from the surface's address otherwise, so a record written before
+ * surface ids existed resolves to the id it would be issued today.
+ */
+export function terminalSurfaceIdForSurface(surface, options = {}) {
+    if (surface.surfaceId)
+        return surface.surfaceId;
+    return formatTerminalSurfaceId({
+        backend: surface.backend,
+        hostSession: surface.sessionName,
+        paneId: surface.paneId,
+        nodeId: options.nodeId ?? null,
+    });
+}
+/**
+ * Whether a handle scoped to `handleNodeId` may address a surface scoped to
+ * `surfaceNodeId`.
+ *
+ * Three cases, and the third is the one a review reproduced:
+ *
+ * - Both sides name a node: they must name the same one. Without this a handle
+ *   for one node matched an identically named session on another.
+ * - The handle names none: it is a legacy key, which names no machine and must
+ *   keep matching whatever it finds.
+ * - The handle names a node and the OBSERVATION does not. A node-less
+ *   observation is by definition local — it is a session this host just listed
+ *   — so only the local node's handle can be the one it belongs to. Letting any
+ *   node-scoped handle match it meant handles for `node-a` and `node-b` both
+ *   bound to one discovered local session, and both workspaces reported it
+ *   Running: one session proving two machines live. A foreign handle never
+ *   matches, and when this host does not know its own node id it cannot prove
+ *   the handle is local either, so it does not claim it.
+ */
+export function terminalSurfaceNodeScopeMatches(input) {
+    if (input.handleNodeId === null)
+        return true;
+    if (input.surfaceNodeId !== null)
+        return input.handleNodeId === input.surfaceNodeId;
+    const localNodeId = input.localNodeId?.trim() || null;
+    return localNodeId !== null && input.handleNodeId === localNodeId;
+}
+/** The node a surface belongs to, which lives inside its own opaque id. */
+export function terminalSurfaceNodeId(surface) {
+    return parseTerminalSurfaceId(surface.surfaceId)?.nodeId ?? null;
+}
+/** True when a handle addresses this surface, in either the opaque or legacy form. */
+export function terminalSurfaceMatchesId(surface, handle, scope = {}) {
+    const address = parseTerminalSurfaceId(handle);
+    if (!address)
+        return false;
+    if (address.backend !== surface.backend || address.hostSession !== surface.sessionName)
+        return false;
+    // A legacy key carries no pane, so it matches any pane on the session; an
+    // opaque id that names a pane must match it exactly.
+    if (address.paneId !== null && address.paneId !== (surface.paneId ?? null))
+        return false;
+    return terminalSurfaceNodeScopeMatches({
+        handleNodeId: address.nodeId ?? null,
+        surfaceNodeId: terminalSurfaceNodeId(surface),
+        localNodeId: scope.localNodeId,
+    });
+}

package/dist/terminal-surface-id.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Terminal surface identity.
+ *
+ * A surface id is an opaque token that names one materialized terminal surface:
+ * a host session (and optionally a pane) on a host backend, on a node. It is
+ * the durable handle a saved workspace cell, a deep link, or a route alias
+ * holds onto.
+ *
+ * Two rules make it durable, and both are the point of this module:
+ *
+ * 1. Identity comes from (node, backend, host session, pane) — never from the
+ *    display name. Renaming a session used to change its Scout id, because ids
+ *    were `sha1(name)`.
+ * 2. There is exactly ONE constructor ({@link formatTerminalSurfaceId}) and ONE
+ *    parser ({@link parseTerminalSurfaceId}). Nothing else may split a surface
+ *    id on a separator. Four different separator conventions had grown across
+ *    the server, the web client, and the macOS app, each with its own
+ *    assumptions about which characters could appear in a session name; the
+ *    only reason they worked was an unrelated validator that happened to
+ *    exclude `:`.
+ *
+ * The token is opaque to consumers but not to this module: it encodes its parts
+ * so a server can resolve one without a lookup table, and so a client that
+ * receives an id it has never seen can still be routed. Legacy `backend:name`
+ * keys parse too, so persisted workspaces and in-flight URLs keep working.
+ */
+/** Backends with first-class protocol support. */
+export type TerminalBackend = "tmux" | "zellij";
+/**
+ * Any terminal host Scout can address. {@link TerminalBackend} is the subset the
+ * protocol types name explicitly; adapters may register further hosts (herdr,
+ * ssh, host-control) without a protocol change.
+ */
+export type TerminalHostId = TerminalBackend | (string & {});
+/** The parts a surface id is built from. */
+export type TerminalSurfaceAddress = {
+    /** Host adapter that owns the surface. */
+    backend: TerminalHostId;
+    /** Backend-native session name. Mutable display metadata, not identity on its own. */
+    hostSession: string;
+    /** Pane or tab within the host session, when the host addresses one. */
+    paneId?: string | null;
+    /** Scout node the surface lives on. Null/absent means the local node. */
+    nodeId?: string | null;
+};
+/** Opaque surface handle. Never split, slice, or interpolate into a pattern. */
+export type TerminalSurfaceId = string;
+export declare function isTerminalSurfaceId(value: string | null | undefined): boolean;
+/**
+ * Build the surface id for an address. Deterministic: the same address always
+ * yields the same id, on any node, in any process, so two writers converge on
+ * one row instead of forking one.
+ */
+export declare function formatTerminalSurfaceId(address: TerminalSurfaceAddress): TerminalSurfaceId;
+/**
+ * Resolve a surface id back to its address. Accepts the opaque form and the
+ * legacy `backend:sessionName` key. Returns null for anything else rather than
+ * guessing — a caller holding an unparseable handle must say so, not fabricate
+ * a target.
+ */
+export declare function parseTerminalSurfaceId(value: string | null | undefined): TerminalSurfaceAddress | null;
+/**
+ * Compare two handles by what they address, not by how they were written, so a
+ * legacy key and its opaque replacement resolve to the same tile.
+ */
+export declare function terminalSurfaceIdsEqual(left: string | null | undefined, right: string | null | undefined): boolean;
+/**
+ * The legacy `backend:sessionName` key for an address. Kept so ids issued by
+ * this build stay readable by clients that have not adopted the opaque form
+ * (macOS, iOS). Delete once every surface reads {@link TerminalSurfaceId}.
+ */
+export declare function legacyTerminalSurfaceKey(address: TerminalSurfaceAddress): string;
+//# sourceMappingURL=terminal-surface-id.d.ts.map

package/dist/terminal-surface-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-surface-id.d.ts","sourceRoot":"","sources":["../src/terminal-surface-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,kDAAkD;AAClD,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEhD;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,eAAe,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAE7D,4CAA4C;AAC5C,MAAM,MAAM,sBAAsB,GAAG;IACnC,0CAA0C;IAC1C,OAAO,EAAE,cAAc,CAAC;IACxB,sFAAsF;IACtF,WAAW,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB,CAAC;AAEF,gFAAgF;AAChF,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC;AAOvC,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAE7E;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,sBAAsB,GAAG,iBAAiB,CAS1F;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,sBAAsB,GAAG,IAAI,CAmC/B;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC/B,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,OAAO,CAQT;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,sBAAsB,GAAG,MAAM,CAEhF"}

package/dist/terminal-surface-id.js

@@ -0,0 +1,162 @@
+/**
+ * Terminal surface identity.
+ *
+ * A surface id is an opaque token that names one materialized terminal surface:
+ * a host session (and optionally a pane) on a host backend, on a node. It is
+ * the durable handle a saved workspace cell, a deep link, or a route alias
+ * holds onto.
+ *
+ * Two rules make it durable, and both are the point of this module:
+ *
+ * 1. Identity comes from (node, backend, host session, pane) — never from the
+ *    display name. Renaming a session used to change its Scout id, because ids
+ *    were `sha1(name)`.
+ * 2. There is exactly ONE constructor ({@link formatTerminalSurfaceId}) and ONE
+ *    parser ({@link parseTerminalSurfaceId}). Nothing else may split a surface
+ *    id on a separator. Four different separator conventions had grown across
+ *    the server, the web client, and the macOS app, each with its own
+ *    assumptions about which characters could appear in a session name; the
+ *    only reason they worked was an unrelated validator that happened to
+ *    exclude `:`.
+ *
+ * The token is opaque to consumers but not to this module: it encodes its parts
+ * so a server can resolve one without a lookup table, and so a client that
+ * receives an id it has never seen can still be routed. Legacy `backend:name`
+ * keys parse too, so persisted workspaces and in-flight URLs keep working.
+ */
+const SURFACE_ID_PREFIX = "srf1.";
+/** Legacy `backend:sessionName` keys, still written by older clients and links. */
+const LEGACY_SURFACE_KEY = /^(?<backend>[A-Za-z][A-Za-z0-9_-]*):(?<hostSession>.+)$/u;
+const BASE64URL_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+export function isTerminalSurfaceId(value) {
+    return typeof value === "string" && value.startsWith(SURFACE_ID_PREFIX);
+}
+/**
+ * Build the surface id for an address. Deterministic: the same address always
+ * yields the same id, on any node, in any process, so two writers converge on
+ * one row instead of forking one.
+ */
+export function formatTerminalSurfaceId(address) {
+    const backend = address.backend.trim();
+    const hostSession = address.hostSession.trim();
+    if (!backend || !hostSession) {
+        throw new Error("a terminal surface id needs a backend and a host session");
+    }
+    const paneId = address.paneId?.trim() || null;
+    const nodeId = address.nodeId?.trim() || null;
+    return `${SURFACE_ID_PREFIX}${encodeBase64Url(JSON.stringify([nodeId, backend, hostSession, paneId]))}`;
+}
+/**
+ * Resolve a surface id back to its address. Accepts the opaque form and the
+ * legacy `backend:sessionName` key. Returns null for anything else rather than
+ * guessing — a caller holding an unparseable handle must say so, not fabricate
+ * a target.
+ */
+export function parseTerminalSurfaceId(value) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return null;
+    if (trimmed.startsWith(SURFACE_ID_PREFIX)) {
+        const decoded = decodeBase64Url(trimmed.slice(SURFACE_ID_PREFIX.length));
+        if (decoded === null)
+            return null;
+        let parsed;
+        try {
+            parsed = JSON.parse(decoded);
+        }
+        catch {
+            return null;
+        }
+        if (!Array.isArray(parsed) || parsed.length < 3)
+            return null;
+        const [nodeId, backend, hostSession, paneId] = parsed;
+        if (typeof backend !== "string" || !backend.trim())
+            return null;
+        if (typeof hostSession !== "string" || !hostSession.trim())
+            return null;
+        return {
+            backend: backend.trim(),
+            hostSession: hostSession.trim(),
+            paneId: typeof paneId === "string" && paneId.trim() ? paneId.trim() : null,
+            nodeId: typeof nodeId === "string" && nodeId.trim() ? nodeId.trim() : null,
+        };
+    }
+    const legacy = LEGACY_SURFACE_KEY.exec(trimmed);
+    if (!legacy?.groups)
+        return null;
+    const hostSession = legacy.groups.hostSession.trim();
+    if (!hostSession)
+        return null;
+    return {
+        backend: legacy.groups.backend,
+        hostSession,
+        paneId: null,
+        nodeId: null,
+    };
+}
+/**
+ * Compare two handles by what they address, not by how they were written, so a
+ * legacy key and its opaque replacement resolve to the same tile.
+ */
+export function terminalSurfaceIdsEqual(left, right) {
+    const leftAddress = parseTerminalSurfaceId(left);
+    const rightAddress = parseTerminalSurfaceId(right);
+    if (!leftAddress || !rightAddress)
+        return false;
+    return leftAddress.backend === rightAddress.backend
+        && leftAddress.hostSession === rightAddress.hostSession
+        && (leftAddress.paneId ?? null) === (rightAddress.paneId ?? null)
+        && (leftAddress.nodeId ?? null) === (rightAddress.nodeId ?? null);
+}
+/**
+ * The legacy `backend:sessionName` key for an address. Kept so ids issued by
+ * this build stay readable by clients that have not adopted the opaque form
+ * (macOS, iOS). Delete once every surface reads {@link TerminalSurfaceId}.
+ */
+export function legacyTerminalSurfaceKey(address) {
+    return `${address.backend}:${address.hostSession}`;
+}
+// Base64url over UTF-8, hand-rolled so this module runs unchanged in a browser
+// bundle, a Bun server, and a Node relay without Buffer or atob/btoa.
+function encodeBase64Url(value) {
+    const bytes = new TextEncoder().encode(value);
+    let out = "";
+    for (let index = 0; index < bytes.length; index += 3) {
+        const byte0 = bytes[index];
+        const byte1 = bytes[index + 1];
+        const byte2 = bytes[index + 2];
+        out += BASE64URL_ALPHABET[byte0 >> 2];
+        out += BASE64URL_ALPHABET[((byte0 & 0b11) << 4) | ((byte1 ?? 0) >> 4)];
+        if (byte1 === undefined)
+            break;
+        out += BASE64URL_ALPHABET[((byte1 & 0b1111) << 2) | ((byte2 ?? 0) >> 6)];
+        if (byte2 === undefined)
+            break;
+        out += BASE64URL_ALPHABET[byte2 & 0b111111];
+    }
+    return out;
+}
+function decodeBase64Url(value) {
+    if (!value)
+        return null;
+    const bytes = [];
+    let buffer = 0;
+    let bits = 0;
+    for (const character of value) {
+        const index = BASE64URL_ALPHABET.indexOf(character);
+        if (index < 0)
+            return null;
+        buffer = (buffer << 6) | index;
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            bytes.push((buffer >> bits) & 0xff);
+        }
+    }
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(new Uint8Array(bytes));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/terminal-workspaces.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Durable terminal workspaces.
+ *
+ * A workspace is a named, server-owned arrangement of agent-CLI tiles. It is
+ * the Scout object the three clients had each invented privately —
+ * `openscout.terminal.workspaces.v1` in localStorage,
+ * `scout.terminals.workspaces.v1` in UserDefaults, and nothing at all on iOS —
+ * with the same version number, the same idea, and no synchronization.
+ *
+ * Where this stands TODAY, so nobody reads more into it than is built: the web
+ * client treats the record as its source of truth, seeding its deck from it and
+ * writing changes back. macOS still keeps its own UserDefaults store and has no
+ * reference to `/api/terminal-workspaces`, and iOS has nothing. "One workspace
+ * on all three clients" is the direction this type exists to make possible, not
+ * something it has delivered; the other two clients follow.
+ *
+ * The load-bearing design decision is that a cell stores INTENT, not just a
+ * binding. A saved cell that only remembers "tmux session scout-tmux-cell-7"
+ * is worth nothing after a reboot: tmux is empty and the name resolves to
+ * nothing. A cell that also remembers which host to use, what directory, and
+ * how to resume the harness can be rebuilt. This is the same conclusion
+ * tmux-resurrect/continuum reached — persist intent and replay it, never
+ * process state — and what macOS's `restoreCommandLine` already does in a
+ * cruder form.
+ */
+import type { TerminalSessionRecord, TerminalSurface } from "./terminal-sessions.js";
+import type { TerminalHostId, TerminalSurfaceId } from "./terminal-surface-id.js";
+/**
+ * Everything needed to re-materialize a cell when nothing live matches it.
+ * Every field is optional because a workspace authored before a given field
+ * existed must still resolve; what a cell cannot say, reconciliation refuses to
+ * invent.
+ */
+export type TerminalWorkspaceCellIntent = {
+    /** Host to materialize on. Absent means "whatever the operator's default is". */
+    hostId?: TerminalHostId | null;
+    /** Durable per-cell host session name. This is what makes a tile reattach. */
+    sessionName?: string | null;
+    /** Working directory to open in. */
+    cwd?: string | null;
+    /** Harness to resume, when the cell is an agent rather than a shell. */
+    harness?: string | null;
+    /** Harness-native resume command, e.g. `claude --resume <id>`. */
+    resumeCommand?: string | null;
+};
+export type TerminalWorkspaceCell = {
+    /** Stable cell id. Minted once, at authoring; never derived from a name. */
+    id: string;
+    /** Durable handle for the surface this cell last bound to. */
+    surfaceId?: TerminalSurfaceId | null;
+    /** Registry record that surface belonged to, when it had one. */
+    terminalSessionId?: string | null;
+    intent: TerminalWorkspaceCellIntent;
+};
+/**
+ * How a workspace arranges its tiles.
+ *
+ * Three shapes, not a list of named presets: one tile, N side-by-side lanes, or
+ * a 2D grid. The old SOLO/SPLIT/TRIO/QUAD taxonomy conflated the shape with a
+ * particular tile count, which is why authoring was capped at four and a
+ * nine-tile workspace silently truncated — "Quad" was both a layout and a size.
+ * Size is now just how many cells exist.
+ */
+export type TerminalWorkspaceLayoutMode = "solo" | "lanes" | "grid";
+/**
+ * `"dynamic"` fits the column count to the number of tiles instead of pinning
+ * it, so adding a tile re-flows the workspace rather than leaving a hole.
+ */
+export type TerminalWorkspaceColumnCount = number | "dynamic";
+export type TerminalWorkspaceLayout = {
+    mode: TerminalWorkspaceLayoutMode;
+    columns?: TerminalWorkspaceColumnCount;
+};
+export type TerminalWorkspaceRecord = {
+    id: string;
+    name: string;
+    purpose: string;
+    /**
+     * Resolved column count at the time of writing. Kept for records and clients
+     * that predate {@link layout}; `layout` wins when both are present.
+     */
+    columns: number;
+    layout?: TerminalWorkspaceLayout;
+    cells: TerminalWorkspaceCell[];
+    createdAt: number;
+    updatedAt: number;
+    metadata?: Record<string, unknown>;
+};
+export type TerminalWorkspaceRecordInput = {
+    id?: string;
+    name: string;
+    purpose?: string;
+    columns?: number;
+    layout?: TerminalWorkspaceLayout;
+    cells?: TerminalWorkspaceCell[];
+    metadata?: Record<string, unknown>;
+};
+/** Highest column count a workspace may reopen with. */
+export declare const TERMINAL_WORKSPACE_MAX_COLUMNS = 6;
+export declare const TERMINAL_WORKSPACE_DEFAULT_COLUMNS = 2;
+/**
+ * The layout a workspace should open with, folding a pre-layout record forward.
+ *
+ * A record written before layouts existed carries only a column count, so the
+ * mode is inferred from how that count relates to the cells: one cell is solo,
+ * a count that fits every cell on one row is lanes, anything else was a grid.
+ */
+export declare function terminalWorkspaceLayoutOf(input: {
+    layout?: TerminalWorkspaceLayout | null;
+    columns?: number | null;
+    cellCount?: number;
+}): TerminalWorkspaceLayout;
+/**
+ * Column count to render with.
+ *
+ * Solo is always one. A dynamic lane count is the tile count, so every tile
+ * gets its own lane; a dynamic grid is the squarest arrangement that holds
+ * them. Both clamp, because past a handful of columns a terminal is too narrow
+ * to read.
+ */
+export declare function resolveTerminalWorkspaceColumns(layout: TerminalWorkspaceLayout, input: {
+    tileCount: number;
+}): number;
+export declare function normalizeTerminalWorkspaceColumnCount(value: unknown): TerminalWorkspaceColumnCount;
+/**
+ * Read a stored `layout_json` column back, or null when there is nothing
+ * trustworthy in it.
+ *
+ * Every store that persists a workspace decodes the layout through this, and
+ * that is the point: `layout_json` was added to the schema and then read by one
+ * handle and ignored by the other, so a layout written through the web server
+ * came back as `null` through the runtime store. One decoder means one answer.
+ *
+ * The mode is validated rather than trusted. It flows straight into the
+ * client's grid resolver, so a value that is not one of the three shapes must
+ * become "no stored layout" — which folds forward from the column count — and
+ * not a mode nothing can render.
+ */
+export declare function parseTerminalWorkspaceLayoutJson(value: string | null | undefined): TerminalWorkspaceLayout | null;
+export declare function terminalWorkspaceLayoutLabel(layout: TerminalWorkspaceLayout): string;
+export type TerminalWorkspaceCellStatus = "live" | "revivable" | "unavailable";
+/** What reconciliation needs to know about a host, with no host access. */
+export type TerminalWorkspaceHostState = {
+    id: TerminalHostId;
+    installed: boolean;
+    /** Whether Scout can materialize a session on this host headlessly. */
+    canCreate: boolean;
+};
+export type TerminalWorkspaceRevivePlan = {
+    hostId: TerminalHostId;
+    sessionName: string;
+    cwd: string | null;
+    /** Harness resume command to run inside the revived surface, when known. */
+    resumeCommand: string | null;
+};
+export type TerminalWorkspaceCellResolution = {
+    cellId: string;
+    status: TerminalWorkspaceCellStatus;
+    surfaceId: TerminalSurfaceId | null;
+    terminalSessionId: string | null;
+    surface: TerminalSurface | null;
+    /** Operator-facing reason, in product language. */
+    detail: string;
+    /** Present exactly when the status is `revivable`. */
+    revive: TerminalWorkspaceRevivePlan | null;
+};
+export type TerminalWorkspaceResolution = {
+    workspaceId: string;
+    cells: TerminalWorkspaceCellResolution[];
+    liveCount: number;
+    revivableCount: number;
+    unavailableCount: number;
+};
+/**
+ * Map every saved cell to a live surface, a restorable-but-dead one, or an
+ * unavailable one.
+ *
+ * This is the only honest answer to a reboot. tmux and zellij sessions do not
+ * survive a restart; a workspace that stored intent can rebuild itself, and one
+ * that stored only a session name cannot. Judgement lives here, on the server
+ * side of the wire, so all three clients inherit the same answer instead of
+ * each re-deriving it — and it never fabricates a record: a cell with nothing
+ * to rebuild from reports `unavailable` and says why.
+ */
+export declare function reconcileTerminalWorkspace(workspace: TerminalWorkspaceRecord, input: {
+    sessions: readonly TerminalSessionRecord[];
+    hosts: readonly TerminalWorkspaceHostState[];
+    /** Host used when a cell's intent names none. */
+    defaultHostId?: TerminalHostId | null;
+    /**
+     * This host's own Scout node id. The observations passed in were made HERE,
+     * so this is the node whose cells they can prove live; a cell scoped to any
+     * other node is not answered by them. Absent means the caller cannot say,
+     * and then no node-scoped cell is claimed by a node-less observation.
+     */
+    localNodeId?: string | null;
+}): TerminalWorkspaceResolution;
+export declare function normalizeTerminalWorkspaceColumns(value: unknown): number;
+//# sourceMappingURL=terminal-workspaces.d.ts.map