@andorra-labs/code 0.0.0-stage → 0.1.4

package/dist/src/remote/engine-pool.js

@@ -0,0 +1,1160 @@
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { loadConfig } from '../config.js';
+import { reconcileInterruptedRuns } from '../run-records.js';
+import { configuredSurface, reportInterruptedRuns } from '../telemetry/surface.js';
+import { authorizedRoots } from './roots.js';
+/**
+ * The engine relay: the host side of full-owner remote access.
+ *
+ * A paired window is a full client of this machine's engine surface, so someone has to stand between
+ * the pairing listener and the engine pool the product describes (ADR 0017): a browsing engine that
+ * answers sessions, run records, workspace reads and terminals, plus one child engine per concurrent
+ * task. That coordinator is this module, and it lives in the process that owns the listener — the
+ * desktop's primary engine, or a standalone `andorra remote serve`. It spawns its own children with
+ * the same `app-server --stdio` wire every other client speaks, so a headless host and a desktop host
+ * serve the identical surface.
+ *
+ * Nothing here decides authority: the endpoints in `server.ts` admit a request only for a full-grant
+ * device over TLS, and this module assumes that check has run. Revocation is still enforced live — a
+ * poller re-reads the device table and cuts a revoked device's event stream and terminals, because a
+ * long-lived stream is exactly the resource a per-request authentication check cannot see.
+ *
+ * Client-lifetime resources are namespaced per connection: terminal ids are prefixed with the
+ * connection that opened them, their output is delivered only to that connection, and a closeAll from
+ * one connection sweeps only its own shells. Run ownership is host-wide (the runs belong to this
+ * machine), so run and prompt routing is by runId and engine id across all children.
+ */
+/** The engine a paired client addresses for everything that is not one task's run. */
+export const REMOTE_PRIMARY_ENGINE = 'remote-primary';
+/**
+ * The capability that says this relay understands a capability requirement.
+ *
+ * It lives here, with the implementation that honours it, and not in the app-server's shared
+ * capability list: the server loads that list lazily, so a build whose files were replaced under
+ * a running relay would advertise a capability the relay in memory does not have — and a client
+ * that trusted it would send a requirement the old relay forwards to a child that ignores it.
+ */
+export const RELAY_CAPABILITY_REQUIREMENT = 'remote.engine.relay.capability';
+const TASK_PREFIX = 'remote-task-';
+/** How many task engines the relay will run at once, besides the browsing engine. */
+const MAX_RELAY_ENGINES = 9;
+/** How many of a child's newest stderr lines are kept, for the message when it dies. */
+const CHILD_STDERR_LINES = 50;
+/** A child that never completes its handshake is not an engine; the start fails after this. */
+const CHILD_READY_TIMEOUT_MS = 60_000;
+/** How long a graceful child stop may take before the kill backstop fires. */
+const CHILD_STOP_GRACE_MS = 20_000;
+/**
+ * The wall-clock a relayed request gives the child, over what the viewer asked for.
+ *
+ * The viewer's own client times out at exactly the deadline it sent; this slack is what keeps the
+ * relay from racing that timer, so the failure the desktop reports is its own timeout with its own
+ * pending-entry cleanup, not a second, earlier one from under the link.
+ */
+const CHILD_DEADLINE_SLACK_MS = 5_000;
+const MAX_CHILD_DEADLINE_MS = 300_000;
+/**
+ * The ceiling for methods whose own work is allowed to be slow. The browser installer is bounded by
+ * its own twenty-minute timer and the viewer grants it 21 minutes; the short ceiling would cut that
+ * budget off under the link and fail a call the peer was still completing.
+ */
+const LONG_DEADLINE_METHODS = new Set(['browser.runtime.install']);
+const MAX_LONG_CHILD_DEADLINE_MS = 1_260_000;
+/** How often a live connection's device is re-checked against the configuration. */
+const REVOCATION_POLL_MS = 5_000;
+/**
+ * How long a connection may exist with no event stream before the relay retires it.
+ *
+ * `remote.engine.connect` answers before its SSE GET lands, and a viewer can unload in between: a
+ * connection created only by requests would otherwise keep its terminals and never be swept, since
+ * the response-close callback that ends it exists only on the stream. The same TTL now also bounds
+ * a retryable stream loss: the shells survive the seconds a reconnect takes, and only an abandoned
+ * connection reaches the poller's sweep.
+ */
+const SINKLESS_CONNECTION_TTL_MS = 30_000;
+/**
+ * How long a run's completion is kept for a reconnecting viewer.
+ *
+ * A run that finished while its viewer's stream was down is not active any more — replaying its
+ * start would show it working forever — so the completion itself is what the replacement stream
+ * receives, for as long as a viewer that saw the start could still be reconnecting.
+ */
+const FINISHED_RUN_TTL_MS = 5 * 60_000;
+/** How many recent completions are kept, per the TTL above. */
+const FINISHED_RUNS_REMEMBERED = 8;
+/**
+ * What a relayed response may weigh. The viewer's transport caps at 2 MiB by default; the methods a
+ * local window displays in megabytes — a journal tail, a diff — get the larger bound the product
+ * contract asks for, and anything past its bound is an error the window can name.
+ */
+const MAX_RESPONSE_BYTES = 2 * 1024 * 1024;
+const MAX_LARGE_RESPONSE_BYTES = 12 * 1024 * 1024;
+const LARGE_RESPONSE_METHODS = new Set(['runs.get', 'workspace.diff', 'workspace.git', 'sessions.trajectory', 'browser.view.selection', 'attachments.read']);
+/** Methods a paired client may ask the browsing engine (and only the browsing engine). */
+const PRIMARY_METHODS = new Set([
+    'sessions.list', 'sessions.get', 'sessions.create', 'sessions.rename', 'sessions.setArchived', 'sessions.delete',
+    'sessions.trajectory',
+    'runs.list', 'runs.get', 'timers.list',
+    'workspace.tree', 'workspace.read', 'workspace.git', 'workspace.branches', 'workspace.checkout', 'workspace.diff',
+    'graphs.list', 'graphs.get', 'graphs.select',
+    // The attachment chips of a browsed session name files spooled on the machine that owns the
+    // session, so the preview asks that machine's engine for the bytes.
+    'attachments.read',
+    'config.get', 'projects.list', 'projects.add', 'projects.remove',
+    // Composer suggestions read the paired machine's installed skills; management stays local.
+    'extensions.list',
+    // The session browser panel lives on the machine that owns the session, so a
+    // paired window's pane asks that machine's browsing engine for both the
+    // runtime and the pages. Without these entries a full-grant link refuses
+    // every panel call as unknown-method.
+    'browser.runtime.status', 'browser.runtime.install',
+    'browser.view.status', 'browser.view.open', 'browser.view.navigate', 'browser.view.go', 'browser.view.activate',
+    'browser.view.closeTab', 'browser.view.stream', 'browser.view.input', 'browser.view.selection',
+    'browser.view.release', 'browser.view.cursor',
+    // The agent's panel tool on a task engine relays through the viewer: the
+    // operation runs on the browsing engine, and a run cancellation travels back
+    // so a stopped call cannot act on the shared browser afterwards.
+    'browser.panel.op', 'browser.panel.cancel',
+]);
+/** Methods that start a run, on an engine of the pool's choosing. */
+const RUN_START_METHODS = new Set(['run.start', 'run.resume']);
+/** Methods that answer for one run, addressed to the child that owns it. */
+const RUN_TARGET_METHODS = new Set(['run.setModel', 'run.cancel', 'run.steer', 'run.approve', 'run.answer', 'browser.panel.result']);
+/** Methods handled by the namespacing layer rather than forwarded verbatim. */
+const TERMINAL_METHODS = new Set(['terminal.open', 'terminal.write', 'terminal.resize', 'terminal.close', 'terminal.closeAll']);
+const ALLOWED_METHODS = new Set([...PRIMARY_METHODS, ...RUN_START_METHODS, ...RUN_TARGET_METHODS, ...TERMINAL_METHODS]);
+/** A session-mutating call goes to the engine whose run owns the session's record. */
+const SESSION_MUTATION_METHODS = new Set(['sessions.rename', 'sessions.setArchived', 'sessions.delete']);
+/** Calls whose effect must land inside the caller's own deadline, not past it. */
+const MUTATING_METHODS = new Set([
+    ...RUN_START_METHODS, ...RUN_TARGET_METHODS, ...SESSION_MUTATION_METHODS,
+    'terminal.open', 'terminal.write', 'terminal.close', 'terminal.closeAll', 'workspace.checkout', 'projects.add', 'projects.remove',
+    // Panel calls act on the peer's browser immediately; an install outlives the
+    // relay's default child deadline, so it keeps the caller's own budget.
+    'browser.runtime.install', 'browser.view.open', 'browser.view.navigate', 'browser.view.go', 'browser.view.activate',
+    'browser.view.closeTab', 'browser.view.stream', 'browser.view.input',
+    'browser.panel.op', 'browser.panel.cancel',
+]);
+/** A child's failure, with the wire code it answered with — `engine-busy` decides pool selection. */
+class ChildError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+/**
+ * The only refusal type the relay raises on its own. A code from the engine's vocabulary survives
+ * the trip (the desktop branches on `engine-busy`, `nothing-to-continue`); an unrecognized peer
+ * string is never rethrown as a code.
+ */
+class RelayRefusal extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+const KNOWN_CODES = new Set(['invalid-request', 'unknown-method', 'invalid-params', 'busy', 'engine-busy', 'not-found',
+    'login-required', 'auth', 'storage', 'network', 'cancelled', 'internal', 'remote', 'nothing-to-continue']);
+function relayError(error) {
+    if (error instanceof RelayRefusal || error instanceof ChildError) {
+        return { code: KNOWN_CODES.has(error.code) ? error.code : 'remote', message: error.message };
+    }
+    return { code: 'remote', message: error instanceof Error ? error.message : String(error) };
+}
+/** One spawned `app-server`, speaking the newline JSON wire. */
+class ChildEngine {
+    id;
+    onEvent;
+    onExit;
+    child;
+    nextId = 1;
+    pending = new Map();
+    ready;
+    resolveReady;
+    rejectReady;
+    stopped = false;
+    /** Whether a run owns this child; learned from its own run lifecycle events. */
+    busy = false;
+    /** The capabilities the child advertised in its handshake. */
+    advertised = [];
+    /** The child's newest stderr lines: an engine that dies should say what it last said. */
+    stderrTail = [];
+    constructor(id, command, home, onEvent, onExit) {
+        this.id = id;
+        this.onEvent = onEvent;
+        this.onExit = onExit;
+        this.child = spawn(command[0], command.slice(1), {
+            windowsHide: true,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            // The relayed child cannot see the window that drives it, so it is told which surface it is.
+            env: { ...process.env, ANDORRACODE_HOME: home, ANDORRA_SURFACE: 'remote' },
+        });
+        this.ready = new Promise((resolve, reject) => {
+            this.resolveReady = resolve;
+            this.rejectReady = reject;
+            setTimeout(() => reject(new Error(`Engine ${id} did not report ready`)), CHILD_READY_TIMEOUT_MS).unref?.();
+        });
+        this.child.on('error', error => this.fail(new Error(`Engine ${id} could not start: ${error.message}`)));
+        this.child.on('exit', () => {
+            const last = this.stderrTail[this.stderrTail.length - 1];
+            this.fail(new Error(`Engine ${id} exited.${last !== undefined ? ` Last output: ${last.slice(0, 300)}` : ''}`));
+        });
+        // A child's stderr must be drained even though nothing forwards it yet: an unread pipe fills,
+        // and a task that writes enough diagnostics would then block on its own logging and hang.
+        if (this.child.stderr) {
+            createInterface({ input: this.child.stderr }).on('line', line => {
+                if (!line.trim())
+                    return;
+                this.stderrTail.push(line);
+                if (this.stderrTail.length > CHILD_STDERR_LINES)
+                    this.stderrTail.shift();
+            });
+        }
+        const stdout = this.child.stdout;
+        const stdin = this.child.stdin;
+        if (!stdout || !stdin) {
+            this.fail(new Error(`Engine ${id} started without a usable pipe.`));
+            return;
+        }
+        // A write that fails asynchronously — EPIPE after the child died between the liveness check and
+        // the write — is emitted as an 'error' event on stdin, not thrown; unhandled it would terminate
+        // the whole relay process instead of failing this engine.
+        stdin.on('error', error => this.fail(new Error(`Engine ${id} lost its input: ${error.message}`)));
+        createInterface({ input: stdout }).on('line', line => {
+            if (!line.trim())
+                return;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                return;
+            }
+            if (typeof parsed.event === 'string') {
+                if (parsed.event === 'ready') {
+                    // The handshake is what says what this child can do, and the pool routes by it: a child
+                    // that predates a feature answers the request and silently ignores the parameter.
+                    const capabilities = parsed.data?.capabilities;
+                    this.advertised = Array.isArray(capabilities) ? capabilities.filter((entry) => typeof entry === 'string') : [];
+                    this.resolveReady?.();
+                    return;
+                }
+                this.onEvent(this.id, parsed.event, (parsed.data ?? {}));
+                return;
+            }
+            if (typeof parsed.id !== 'number')
+                return;
+            const entry = this.pending.get(parsed.id);
+            if (!entry)
+                return;
+            this.pending.delete(parsed.id);
+            clearTimeout(entry.timer);
+            const failure = parsed.error;
+            if (failure && typeof failure.message === 'string')
+                entry.reject(new ChildError(typeof failure.code === 'string' ? failure.code : 'internal', failure.message));
+            else
+                entry.resolve(parsed.result ?? null);
+        });
+    }
+    fail(error) {
+        for (const [, entry] of [...this.pending]) {
+            clearTimeout(entry.timer);
+            entry.reject(error);
+        }
+        this.pending.clear();
+        this.rejectReady?.(error);
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        this.child.kill();
+        this.onExit(this.id);
+    }
+    /** Whether this child advertised a capability in its handshake. */
+    supports(capability) {
+        return this.advertised.includes(capability);
+    }
+    request(method, params, timeoutMs) {
+        const stdin = this.child.stdin;
+        if (this.stopped || !stdin || stdin.destroyed)
+            return Promise.reject(new ChildError('closed', `Engine ${this.id} is not running.`));
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new ChildError('timeout', `${method} on engine ${this.id} did not answer in time.`));
+            }, timeoutMs);
+            timer.unref?.();
+            this.pending.set(id, { resolve, reject, timer });
+            try {
+                stdin.write(`${JSON.stringify({ id, method, params })}\n`, error => {
+                    // The same failure surfacing on the write's own callback: the request cannot be answered,
+                    // so it is rejected now rather than left to its deadline.
+                    if (!error)
+                        return;
+                    const entry = this.pending.get(id);
+                    if (!entry)
+                        return;
+                    this.pending.delete(id);
+                    clearTimeout(entry.timer);
+                    entry.reject(new ChildError('closed', `Engine ${this.id} is not running.`));
+                });
+            }
+            catch (error) {
+                this.pending.delete(id);
+                clearTimeout(timer);
+                reject(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
+    }
+    /** Close stdin (the engine's graceful shutdown signal) with a kill backstop. */
+    stop() {
+        if (this.stopped)
+            return Promise.resolve();
+        this.stopped = true;
+        return new Promise(resolve => {
+            const settled = () => { clearTimeout(killTimer); resolve(); };
+            const killTimer = setTimeout(() => { this.child.kill(); settled(); }, CHILD_STOP_GRACE_MS);
+            killTimer.unref?.();
+            this.child.once('exit', settled);
+            const stdin = this.child.stdin;
+            if (!stdin || stdin.destroyed) {
+                this.child.kill();
+                settled();
+                return;
+            }
+            stdin.on('error', () => undefined);
+            stdin.end(() => undefined);
+        });
+    }
+}
+/** How this process spawns another engine of its own CLI. */
+export function relayEngineCommand() {
+    const override = process.env.ANDORRA_REMOTE_ENGINE_COMMAND;
+    if (override) {
+        try {
+            const parsed = JSON.parse(override);
+            if (Array.isArray(parsed) && parsed.length)
+                return parsed.map(String);
+        }
+        catch { /* A single path is the plain spelling of the override. */ }
+        return [override];
+    }
+    // This process is the CLI (`node …/cli.js app-server|remote …`), so its own entry is the engine
+    // entry: the relay's children are the same `app-server --stdio` wire the desktop's shell spawns.
+    const entry = process.argv[1];
+    if (!entry)
+        throw new RelayRefusal('remote', 'The engine relay cannot locate its own CLI entry.');
+    return [process.execPath, entry, 'app-server', '--stdio'];
+}
+const REMOTE_PROJECT_PREFIX = 'rw:';
+function isRemoteProjectSpelling(value) {
+    return value.startsWith(REMOTE_PROJECT_PREFIX);
+}
+/** The root id part of an `rw:` spelling: everything after the viewer workspace segment. */
+function rootPartOf(value) {
+    const rest = value.slice(REMOTE_PROJECT_PREFIX.length);
+    const colon = rest.indexOf(':');
+    if (colon < 0)
+        return undefined;
+    return rest.slice(colon + 1);
+}
+/**
+ * The coordinator. One instance per listener, created by the server alongside it.
+ */
+export class RemoteEngineRelay {
+    directory;
+    children = new Map();
+    /**
+     * The children this relay is stopping, so no start takes one that is on its way out.
+     *
+     * It belongs to the relay: two relays in one process allocate the same child ids, and one
+     * relay's reservation would hide another's idle child.
+     */
+    retiringChildren = new Set();
+    taskSeq = 0;
+    connections = new Map();
+    /** Real (child-side) terminal id → the connection that opened it. */
+    terminalOwner = new Map();
+    /** Session id → the connections whose panels are watching it (a stream they share). */
+    browserViewers = new Map();
+    /** runId / sessionId → the child that owns it, learned from run lifecycle events. */
+    runEngine = new Map();
+    sessionEngine = new Map();
+    /** The `run.started` payload of each live run, keyed by its child — replayed to new connections. */
+    activeRuns = new Map();
+    /** The completions that landed with no stream attached, kept briefly for the reconnect replay. */
+    finishedRuns = new Map();
+    /** Translations by viewer workspace id, each cached briefly (a rebuild realpath-walks the roots). */
+    translations = new Map();
+    revocationTimer;
+    /** Event delivery is queued: a stream's frames must land in the order the children emitted them. */
+    delivery = Promise.resolve();
+    closed = false;
+    constructor(directory) {
+        this.directory = directory;
+    }
+    /**
+     * One relayed request. Throws nothing: every failure is the answer's `error`, because the caller is
+     * an HTTP handler whose status code cannot say what went wrong inside the engine pool.
+     */
+    async request(deviceId, body) {
+        try {
+            const { method, params } = this.validate(body);
+            const result = await this.dispatch(deviceId, body, method, params);
+            const translation = await this.translation(body.viewerWorkspaceId);
+            const rewritten = OPAQUE_RESPONSE_METHODS.has(method) ? (result ?? null) : translation.rewrite(result ?? null);
+            const serialized = JSON.stringify(rewritten) ?? 'null';
+            const cap = LARGE_RESPONSE_METHODS.has(method) ? MAX_LARGE_RESPONSE_BYTES : MAX_RESPONSE_BYTES;
+            if (Buffer.byteLength(serialized) > cap) {
+                return { error: { code: 'remote', message: `${method} answered larger than the remote link allows (${Math.round(cap / 1024 / 1024)} MiB).` } };
+            }
+            return { result: rewritten };
+        }
+        catch (error) {
+            return { error: relayError(error) };
+        }
+    }
+    validate(body) {
+        if (!body.connectionId || typeof body.connectionId !== 'string')
+            throw new RelayRefusal('invalid-params', 'connectionId is required.');
+        if (!body.engine || typeof body.engine !== 'string')
+            throw new RelayRefusal('invalid-params', 'engine is required.');
+        if (!body.method || typeof body.method !== 'string' || !ALLOWED_METHODS.has(body.method)) {
+            throw new RelayRefusal('unknown-method', 'That method is not part of the remote engine surface.');
+        }
+        const params = body.params === undefined ? {} : body.params;
+        if (!params || typeof params !== 'object' || Array.isArray(params))
+            throw new RelayRefusal('invalid-params', 'params must be an object.');
+        return { method: body.method, params };
+    }
+    childDeadline(body) {
+        const asked = typeof body.deadlineMs === 'number' && body.deadlineMs > 0 ? body.deadlineMs : 120_000;
+        const ceiling = LONG_DEADLINE_METHODS.has(body.method) ? MAX_LONG_CHILD_DEADLINE_MS : MAX_CHILD_DEADLINE_MS;
+        const bounded = Math.min(Math.max(asked, 5_000), ceiling);
+        // A mutation runs inside the caller's own budget: the viewer's client fails the call at the
+        // deadline it sent, and a start, prompt answer, session change, or shell open that committed
+        // after that would surprise a user who already retried or moved on. Reads keep the small slack
+        // that lets the engine decide its own timeout rather than racing the viewer's.
+        if (MUTATING_METHODS.has(body.method))
+            return bounded;
+        return bounded + CHILD_DEADLINE_SLACK_MS;
+    }
+    async dispatch(deviceId, body, method, params) {
+        const connection = this.connection(deviceId, body.connectionId, body.viewerWorkspaceId);
+        const deadline = this.childDeadline(body);
+        if (TERMINAL_METHODS.has(method))
+            return this.terminalRequest(connection, method, params, deadline);
+        if (RUN_START_METHODS.has(method))
+            return this.startRequest(body, method, params, deadline);
+        if (RUN_TARGET_METHODS.has(method))
+            return this.runTargetRequest(body, method, params, deadline);
+        // A run owns its session's record while it executes, so a mutation belongs to the engine running
+        // it — the same refusal-and-perform rule a local window's routing follows.
+        if (SESSION_MUTATION_METHODS.has(method) && typeof params.id === 'string') {
+            const owner = this.sessionEngine.get(params.id);
+            if (owner)
+                return (await this.engine(owner)).request(method, params, deadline);
+        }
+        const target = body.engine === '' ? REMOTE_PRIMARY_ENGINE : body.engine;
+        if (target !== REMOTE_PRIMARY_ENGINE && !this.children.has(target)) {
+            throw new RelayRefusal('not-found', `No engine ${target} is serving this machine's remote surface.`);
+        }
+        // A session's panel stream is one switch on the hosting engine, so several paired viewers
+        // watching the same session share it: it is turned off only when the last of them leaves, and
+        // the other viewers' panes keep receiving frames until then.
+        if (method === 'browser.view.stream' && typeof params.sessionId === 'string') {
+            const sessionId = params.sessionId;
+            if (params.enabled === false) {
+                const viewers = this.browserViewers.get(sessionId);
+                viewers?.delete(connection.id);
+                connection.browserStreams.delete(sessionId);
+                if ((viewers?.size ?? 0) > 0)
+                    return { ok: true };
+                this.browserViewers.delete(sessionId);
+            }
+            else {
+                const viewers = this.browserViewers.get(sessionId) ?? new Set();
+                viewers.add(connection.id);
+                this.browserViewers.set(sessionId, viewers);
+                connection.browserStreams.add(sessionId);
+            }
+        }
+        const engine = await this.engine(target);
+        const answer = await engine.request(method, await this.translateParams(body.viewerWorkspaceId, params), deadline);
+        // The session listing echoes each requested spelling back; the viewer files its groups by its
+        // own, so the echo is restored here rather than left in this machine's terms.
+        if (method === 'sessions.list' && Array.isArray(params.workspaces)) {
+            return this.restoreRequestedEcho(answer, params.workspaces, body.viewerWorkspaceId);
+        }
+        // A trajectory page names the log it is showing, and that name is a path on this machine: the
+        // viewer's own home is not this one, and it cannot use the name anyway. It is left out rather
+        // than sent, so the host's layout is not handed to a paired client.
+        if (method === 'sessions.trajectory' && answer !== null && typeof answer === 'object' && !Array.isArray(answer)) {
+            const { path: _hostPath, ...page } = answer;
+            return page;
+        }
+        return answer;
+    }
+    /**
+     * run.start / run.resume: pick a free task engine, spawning one when every child is busy.
+     *
+     * The browsing engine never takes a run (ADR 0017), the busy refusal is the engine's own, and the
+     * answer names the engine that took the run so the viewer can address its prompts directly.
+     */
+    async startRequest(body, method, params, deadline) {
+        // The capability the answering child must advertise, asked for by the viewer: the browsing
+        // engine's handshake says what the machine can do, not what every task engine on it can, and a
+        // child that predates a feature answers the request and ignores the parameter. The requirement
+        // travels with the request so the pool picks a child that honours it — and it is stripped here,
+        // because it is the pool's own routing rule and not the engine's parameter.
+        const { requireCapability, ...rest } = params;
+        const required = typeof requireCapability === 'string' && requireCapability.length > 0 ? requireCapability : undefined;
+        const translated = await this.translateParams(body.viewerWorkspaceId, rest);
+        // A resume may address the engine that owns the session's scheduled wake (the desktop learned
+        // the id from the wake's own events): routing it by pool selection could wake the session in a
+        // second process while the first still holds the timer, and the two would overwrite each
+        // other's persisted turns. The addressed engine decides; its own busy refusal is the answer.
+        if (body.engine !== '' && body.engine !== REMOTE_PRIMARY_ENGINE) {
+            const addressed = this.children.get(body.engine);
+            if (addressed !== undefined) {
+                // A child this relay is stopping is on its way out: a request addressed to it would be
+                // accepted and then lose the engine under it.
+                if (this.retiringChildren.has(addressed.id)) {
+                    throw new RelayRefusal('busy', 'That engine is being stopped; try again.');
+                }
+                // The addressed engine owns the session's wake, so it is the one that has to answer. A child
+                // that cannot honour the requirement is refused rather than rerouted: another engine would
+                // wake the session in a second process.
+                if (required !== undefined && !addressed.supports(required)) {
+                    throw new RelayRefusal('invalid-params', `The engine that would answer does not support ${required}.`);
+                }
+                const result = await addressed.request(method, translated, deadline);
+                return { ...result, engine: addressed.id };
+            }
+        }
+        // A child that does not advertise the capability is not asked at all: it would answer and
+        // ignore the parameter, which is exactly the silence the requirement exists to prevent. An idle
+        // one is retired rather than merely skipped: the pool's cap counts every child, and a pool full
+        // of children that cannot answer would refuse the run as busy while nothing was running.
+        const incompatible = [];
+        for (const [id, engine] of [...this.children]) {
+            if (id === REMOTE_PRIMARY_ENGINE)
+                continue;
+            if (required !== undefined && !engine.supports(required)) {
+                // A child another request is already retiring is not a candidate: two scans would pick the
+                // same one, and only one slot would be freed.
+                if (!engine.busy && !this.retiringChildren.has(id))
+                    incompatible.push(engine);
+                continue;
+            }
+            // A child this relay is stopping is on its way out: a start must not take it.
+            if (this.retiringChildren.has(id))
+                continue;
+            try {
+                const result = await engine.request(method, translated, deadline);
+                return { ...result, engine: id };
+            }
+            catch (error) {
+                if (error instanceof ChildError && (error.code === 'engine-busy' || error.code === 'busy'))
+                    continue;
+                throw error;
+            }
+        }
+        // A child that finished its run but still owns a self-wake timer is not idle in the sense that
+        // matters: stopping it would destroy the pending wake, which is the session's own work. The
+        // scan looks for a child that can be stopped — one may hold a wake while the next cannot.
+        for (const child of incompatible) {
+            // Reserved before the first check, and only if another request has not claimed this child
+            // already: two claims would retire one child and free one slot, and the second request
+            // would be refused as busy while another incompatible idle child remained.
+            if (this.retiringChildren.has(child.id))
+                continue;
+            this.retiringChildren.add(child.id);
+            try {
+                if (await this.childHoldsWake(child))
+                    continue;
+                // The child's own answer is the authority on whether it is free: the busy flag is set when
+                // a run starts, which is after the child has accepted the request, so a child that is still
+                // preparing one looks idle here and must not be stopped under it.
+                if (!await this.childIsIdle(child))
+                    continue;
+                await this.retireChild(child.id);
+                break;
+            }
+            finally {
+                this.retiringChildren.delete(child.id);
+            }
+        }
+        const spawned = await this.spawnChild(`${TASK_PREFIX}${++this.taskSeq}`);
+        try {
+            // A fresh child comes from the machine's current install, so it advertises what the browsing
+            // engine advertised; a machine whose install cannot honour the requirement says so instead.
+            if (required !== undefined && !spawned.supports(required)) {
+                throw new RelayRefusal('invalid-params', `This machine's engine does not support ${required}.`);
+            }
+            const result = await spawned.request(method, translated, deadline);
+            return { ...result, engine: spawned.id };
+        }
+        catch (error) {
+            // A child that took no run is an idle process the pool does not need; retiring it keeps a
+            // refused start from spending a slot. A child whose run began keeps the slot — its events are
+            // still owed to the streams.
+            if (!spawned.busy && !this.engineOwnsRun(spawned.id))
+                await this.retireChild(spawned.id);
+            throw error;
+        }
+    }
+    /**
+     * run.cancel / run.approve / run.answer: a prompt belongs to the child that raised it.
+     *
+     * The viewer addresses these by the engine id it learned from `run.started`, which is authoritative
+     * here as well; a cancel names its run id, and the ownership map answers that on its own.
+     */
+    async runTargetRequest(body, method, params, deadline) {
+        let owner;
+        if (typeof params.runId === 'string')
+            owner = this.runEngine.get(params.runId);
+        if (owner === undefined && body.engine !== '' && body.engine !== REMOTE_PRIMARY_ENGINE && this.children.has(body.engine))
+            owner = body.engine;
+        if (owner === undefined && typeof params.runId === 'string') {
+            throw new RelayRefusal('not-found', 'That run is not executing on this machine.');
+        }
+        if (owner === undefined) {
+            throw new RelayRefusal('not-found', 'That interaction is not waiting on this machine.');
+        }
+        return (await this.engine(owner)).request(method, params, deadline);
+    }
+    /**
+     * Terminal calls: ids are prefixed with the connection, output goes only to that connection, and a
+     * closeAll sweeps only the shells that connection opened. The browsing engine hosts the PTYs — a
+     * shell outlives any one task and belongs to no run.
+     */
+    async terminalRequest(connection, method, params, deadline) {
+        const primary = await this.engine(REMOTE_PRIMARY_ENGINE);
+        const real = (prefixed) => {
+            return typeof prefixed === 'string' ? connection.terminals.get(prefixed) : undefined;
+        };
+        if (method === 'terminal.open') {
+            const result = await primary.request('terminal.open', await this.translateParams(connection.viewerWorkspaceId, params), deadline);
+            const id = result?.terminal?.id;
+            if (typeof id !== 'string')
+                throw new RelayRefusal('remote', 'The engine opened a terminal without an id.');
+            const prefixed = `${connection.id}:${id}`;
+            connection.terminals.set(prefixed, id);
+            this.terminalOwner.set(id, connection.id);
+            return { terminal: { ...result.terminal, id: prefixed } };
+        }
+        if (method === 'terminal.write' || method === 'terminal.resize' || method === 'terminal.close') {
+            const id = real(params.id);
+            if (id === undefined)
+                throw new RelayRefusal('not-found', 'That terminal was not opened on this connection.');
+            // `cwd` on these calls is the VIEWER's routing hint (which machine owns the shell); the
+            // engine's own write/resize/close take no folder, so it is not forwarded.
+            const { cwd: _routing, ...forwarded } = params;
+            const answer = await primary.request(method, { ...forwarded, id }, deadline);
+            if (method === 'terminal.close') {
+                connection.terminals.delete(params.id);
+                this.terminalOwner.delete(id);
+            }
+            return answer;
+        }
+        // terminal.closeAll: only the shells this connection opened — the desktop's own closeAll from a
+        // reattach is the one call that cannot name ids, and here it stays scoped to the issuer.
+        const opened = [...connection.terminals.entries()];
+        connection.terminals.clear();
+        for (const [, id] of opened)
+            this.terminalOwner.delete(id);
+        let closed = 0;
+        for (const [, id] of opened) {
+            try {
+                await primary.request('terminal.close', { id }, 5_000);
+                closed += 1;
+            }
+            catch { /* A dead shell is closed. */ }
+        }
+        return { closed };
+    }
+    /**
+     * Translate the viewer's project spellings inside request params. Only the fields that NAME a
+     * workspace folder carry one, so the walk is over those fields, not the whole payload — a task
+     * prompt may legitimately contain the literal text "rw:".
+     */
+    async translateParams(viewerWorkspaceId, params) {
+        const workspaces = Array.isArray(params.workspaces) ? params.workspaces : undefined;
+        const needs = (typeof params.workspace === 'string' && isRemoteProjectSpelling(params.workspace))
+            || (typeof params.cwd === 'string' && isRemoteProjectSpelling(params.cwd))
+            || (workspaces !== undefined && workspaces.some(value => typeof value === 'string' && isRemoteProjectSpelling(value)));
+        if (!needs)
+            return params;
+        const translation = await this.translation(viewerWorkspaceId);
+        const next = { ...params };
+        if (typeof next.workspace === 'string' && isRemoteProjectSpelling(next.workspace))
+            next.workspace = translation.toHost(next.workspace);
+        if (typeof next.cwd === 'string' && isRemoteProjectSpelling(next.cwd))
+            next.cwd = translation.toHost(next.cwd);
+        if (workspaces !== undefined) {
+            // A listing tolerates one untranslatable spelling: a hashed pick (a folder chosen inside a
+            // root) has no host path, but refusing the WHOLE listing for it would blank every registered
+            // row beside it. It passes through verbatim; the host answers that group empty.
+            next.workspaces = workspaces.map(value => {
+                if (typeof value !== 'string' || !isRemoteProjectSpelling(value))
+                    return value;
+                try {
+                    return translation.toHost(value);
+                }
+                catch {
+                    return value;
+                }
+            });
+        }
+        return next;
+    }
+    /** Put each listing group back under the spelling the viewer asked with. */
+    async restoreRequestedEcho(answer, original, viewerWorkspaceId) {
+        const groups = answer?.groups;
+        if (!Array.isArray(groups))
+            return answer;
+        const translation = await this.translation(viewerWorkspaceId);
+        groups.forEach((group, index) => {
+            const asked = original[index];
+            if (typeof asked === 'string' && isRemoteProjectSpelling(asked))
+                group.requested = asked;
+            else if (typeof group.requested === 'string')
+                group.requested = translation.toViewer(group.requested);
+        });
+        return answer;
+    }
+    /** The connection record, created on first sight. */
+    connection(deviceId, connectionId, viewerWorkspaceId) {
+        let found = this.connections.get(connectionId);
+        if (!found) {
+            found = { id: connectionId, deviceId, terminals: new Map(), browserStreams: new Set(), sinks: new Set(), cuts: new Set(), sinklessSince: Date.now() };
+            this.connections.set(connectionId, found);
+            this.startRevocationPoll();
+        }
+        found.deviceId = deviceId;
+        if (viewerWorkspaceId !== undefined)
+            found.viewerWorkspaceId = viewerWorkspaceId;
+        return found;
+    }
+    /**
+     * End one connection outright: its streams are closed (not merely starved), its terminals swept.
+     *
+     * Revocation and shutdown both go through here, so a connection never survives either — the
+     * viewer observes the stream end and the host keeps no orphaned shells or half-dead sockets.
+     */
+    sever(connection) {
+        for (const cut of [...connection.cuts]) {
+            try {
+                cut();
+            }
+            catch { /* The response is already gone. */ }
+        }
+        connection.sinks.clear();
+        connection.cuts.clear();
+        for (const [, real] of connection.terminals) {
+            this.terminalOwner.delete(real);
+            void this.engine(REMOTE_PRIMARY_ENGINE).then(primary => primary.request('terminal.close', { id: real }, 5_000)).catch(() => undefined);
+        }
+        connection.terminals.clear();
+        // Turning the stream off hands the browser back to the idle reaper, which
+        // closes it a while later; the viewer that owned it is gone either way — but
+        // only when no other connection is still watching that session's panel.
+        for (const sessionId of connection.browserStreams) {
+            const viewers = this.browserViewers.get(sessionId);
+            viewers?.delete(connection.id);
+            if ((viewers?.size ?? 0) > 0)
+                continue;
+            this.browserViewers.delete(sessionId);
+            void this.engine(REMOTE_PRIMARY_ENGINE)
+                .then(primary => primary.request('browser.view.stream', { sessionId, enabled: false }, 5_000))
+                .catch(() => undefined);
+        }
+        connection.browserStreams.clear();
+        this.connections.delete(connection.id);
+    }
+    /**
+     * Register one connection's event stream. The returned stop function ends delivery; the server
+     * calls it when the HTTP response closes, and it sweeps that connection's terminals with it — a
+     * window that is gone cannot name its shells any more, and the host's slots are not a graveyard.
+     */
+    events(deviceId, connectionId, viewerWorkspaceId, sink, cut) {
+        const connection = this.connection(deviceId, connectionId, viewerWorkspaceId);
+        connection.sinks.add(sink);
+        connection.cuts.add(cut);
+        connection.sinklessSince = 0;
+        // A window that reconnects while work is still live has never seen what happened since its last
+        // stream ended: the active run's `run.started`, the completions that landed in the gap, and the
+        // timers an idle engine still holds. These are delivered TO THIS SINK alone — the other, healthy
+        // viewers already saw them, and replaying start frames at them would reset live tracking.
+        this.replayTo(connection, viewerWorkspaceId, sink);
+        return () => {
+            connection.sinks.delete(sink);
+            connection.cuts.delete(cut);
+            if (connection.sinks.size > 0)
+                return;
+            // A stream that closed may be a retryable one (a network blip, backpressure): its viewer
+            // reconnects with the same connection id within seconds. The shells stay — they are the
+            // connection's until either an explicit stream returns (sinklessSince resets) or the poller's
+            // abandonment TTL ends the connection for good.
+            connection.sinklessSince = Date.now();
+        };
+    }
+    /**
+     * Deliver the reconnect snapshot to one stream, in emission order with everything else.
+     *
+     * Active runs first (the replacement client must register them), then the completions that landed
+     * while no stream was attached (so a run that finished in a reconnect gap is not shown as working
+     * forever), then each idle engine's outstanding timers (so a scheduled wake is adopted by the new
+     * client rather than firing unseen).
+     */
+    replayTo(connection, viewerWorkspaceId, sink) {
+        void (async () => {
+            const now = Date.now();
+            for (const [engineId, record] of [...this.finishedRuns]) {
+                if (now - record.at > FINISHED_RUN_TTL_MS) {
+                    this.finishedRuns.delete(engineId);
+                    continue;
+                }
+            }
+            const translation = await this.translation(viewerWorkspaceId);
+            for (const [engineId, data] of this.activeRuns) {
+                this.enqueueTo(sink, translation, engineId, 'run.started', data);
+            }
+            for (const [engineId, record] of this.finishedRuns) {
+                this.enqueueTo(sink, translation, engineId, record.event, record.data);
+            }
+            for (const [engineId, child] of this.children) {
+                if (engineId === REMOTE_PRIMARY_ENGINE)
+                    continue;
+                let listed;
+                try {
+                    listed = await child.request('timers.list', {}, 5_000);
+                }
+                catch {
+                    continue;
+                }
+                for (const entry of listed.sessions ?? []) {
+                    if (typeof entry.sessionId !== 'string')
+                        continue;
+                    this.enqueueTo(sink, translation, engineId, 'timers.updated', { sessionId: entry.sessionId, timers: entry.timers ?? [] });
+                }
+            }
+        })().catch(() => undefined);
+    }
+    /** One queued frame for one sink: the reconnect replay shares the queue, not the broadcast. */
+    enqueueTo(sink, translation, engineId, event, data) {
+        this.delivery = this.delivery.then(() => {
+            if (this.closed)
+                return;
+            try {
+                sink({ engine: engineId, event, data: translation.rewrite(data) });
+            }
+            catch { /* The stream's own handler closes it. */ }
+        }).catch(() => undefined);
+    }
+    /**
+     * One child event, in emission order.
+     *
+     * The queue is the ordering guarantee a stream needs — `run.started` must reach the viewer before
+     * the run's first events whatever the translation cache is doing between them.
+     */
+    enqueue(engineId, event, data) {
+        this.delivery = this.delivery.then(() => this.deliverEvent(engineId, event, data)).catch(() => undefined);
+    }
+    async deliverEvent(engineId, event, data) {
+        if (this.closed)
+            return;
+        const runId = typeof data.runId === 'string' ? data.runId : undefined;
+        if (event === 'run.started') {
+            if (engineId !== REMOTE_PRIMARY_ENGINE) {
+                const child = this.children.get(engineId);
+                if (child)
+                    child.busy = true;
+            }
+            if (runId !== undefined)
+                this.runEngine.set(runId, engineId);
+            if (typeof data.sessionId === 'string')
+                this.sessionEngine.set(data.sessionId, engineId);
+            // A task engine runs one task at a time: this frame is the run a reconnecting window adopts.
+            if (engineId !== REMOTE_PRIMARY_ENGINE)
+                this.activeRuns.set(engineId, data);
+        }
+        if (event === 'run.completed' || event === 'run.failed') {
+            if (runId !== undefined)
+                this.runEngine.delete(runId);
+            if (typeof data.sessionId === 'string' && this.sessionEngine.get(data.sessionId) === engineId)
+                this.sessionEngine.delete(data.sessionId);
+            const child = this.children.get(engineId);
+            if (child && engineId !== REMOTE_PRIMARY_ENGINE)
+                child.busy = false;
+            if (engineId !== REMOTE_PRIMARY_ENGINE) {
+                this.activeRuns.delete(engineId);
+                // A viewer whose stream is down saw the start but will miss this: the completion is kept
+                // for the reconnect replay, so the run does not stay on screen as working forever.
+                this.finishedRuns.set(engineId, { event, data, at: Date.now() });
+                if (this.finishedRuns.size > FINISHED_RUNS_REMEMBERED) {
+                    const oldest = this.finishedRuns.keys().next().value;
+                    if (oldest !== undefined)
+                        this.finishedRuns.delete(oldest);
+                }
+            }
+        }
+        if ((event === 'terminal.data' || event === 'terminal.exit') && typeof data.id === 'string') {
+            // Terminal output belongs to the connection that opened the shell; every other stream — and
+            // every other device — never sees it.
+            const ownerId = this.terminalOwner.get(data.id);
+            if (ownerId === undefined)
+                return;
+            const connection = this.connections.get(ownerId);
+            if (!connection)
+                return;
+            const translation = await this.translation(connection.viewerWorkspaceId);
+            const frame = { engine: engineId, event, data: translation.rewrite({ ...data, id: `${ownerId}:${data.id}` }) };
+            for (const sink of [...connection.sinks]) {
+                try {
+                    sink(frame);
+                }
+                catch { /* The stream's own handler closes it. */ }
+            }
+            return;
+        }
+        for (const connection of [...this.connections.values()]) {
+            if (connection.sinks.size === 0)
+                continue;
+            const translation = await this.translation(connection.viewerWorkspaceId);
+            const frame = { engine: engineId, event, data: this.rewriteEventData(translation, event, data) };
+            for (const sink of [...connection.sinks]) {
+                try {
+                    sink(frame);
+                }
+                catch { /* The stream's own handler closes it. */ }
+            }
+        }
+    }
+    /**
+     * One event's data for one viewer, with its project paths translated.
+     *
+     * A panel operation's arguments are the browser's own input, not paths: a `fill` value that
+     * happens to equal a shared root is a form value the page must receive verbatim, and rewriting it
+     * into the viewer's project id would type that id into the page instead. Only the routing fields
+     * around them are translated.
+     */
+    rewriteEventData(translation, event, data) {
+        if (event !== 'browser.panel.request' || data.arguments === undefined)
+            return translation.rewrite(data);
+        const { arguments: verbatim, ...rest } = data;
+        return { ...translation.rewrite(rest), arguments: verbatim };
+    }
+    onChildExit(engineId) {
+        // A child that dies mid-run leaves the persisted session claiming the run is still live (the
+        // reconciliation a healthy engine performs at startup never runs for it): mark it interrupted
+        // here, so listings and reloads do not show a working task that no process is driving.
+        const interrupted = this.activeRuns.get(engineId);
+        if (interrupted !== undefined && typeof interrupted.runId === 'string') {
+            // The child queued a start for this run, so the reconciliation owes the matching finish;
+            // dropping the returned records would leave that start unmatched, because a replacement
+            // app-server skips records no longer marked running.
+            void reconcileInterruptedRuns(this.directory, new Set([interrupted.runId]), { includePending: true })
+                .then(recovered => reportInterruptedRuns({ home: this.directory, surface: configuredSurface('remote') }, recovered.interrupted))
+                .catch(() => undefined);
+        }
+        this.children.delete(engineId);
+        this.activeRuns.delete(engineId);
+        for (const [runId, owner] of [...this.runEngine])
+            if (owner === engineId)
+                this.runEngine.delete(runId);
+        for (const [sessionId, owner] of [...this.sessionEngine])
+            if (owner === engineId)
+                this.sessionEngine.delete(sessionId);
+        // The viewer learns the engine is gone as an event, so its remote client for it can be retired
+        // the way a dead process's client is.
+        this.enqueue(engineId, 'engine.exited', { engine: engineId });
+    }
+    engineOwnsRun(engineId) {
+        for (const owner of this.runEngine.values())
+            if (owner === engineId)
+                return true;
+        return false;
+    }
+    async engine(id) {
+        const existing = this.children.get(id);
+        if (existing)
+            return existing;
+        if (id !== REMOTE_PRIMARY_ENGINE)
+            throw new RelayRefusal('not-found', `No engine ${id} is serving this machine's remote surface.`);
+        return this.spawnChild(REMOTE_PRIMARY_ENGINE);
+    }
+    async spawnChild(id) {
+        const existing = this.children.get(id);
+        if (existing)
+            return existing;
+        if (this.closed)
+            throw new RelayRefusal('remote', 'The remote engine relay is shutting down.');
+        // The cap counts task engines, and the browsing engine is exempt from it — its slot is the one
+        // the cap exists to protect, so nine busy tasks never leave the primary surface (sessions,
+        // workspace reads, terminals) unspawnable.
+        if (id !== REMOTE_PRIMARY_ENGINE) {
+            const taskEngines = [...this.children.keys()].filter(childId => childId !== REMOTE_PRIMARY_ENGINE).length;
+            if (taskEngines >= MAX_RELAY_ENGINES) {
+                throw new RelayRefusal('busy', 'This machine is already running the most concurrent remote tasks it allows. Wait for one to finish.');
+            }
+        }
+        const created = new ChildEngine(id, relayEngineCommand(), this.directory, (engineId, event, data) => this.enqueue(engineId, event, data), engineId => this.onChildExit(engineId));
+        this.children.set(id, created);
+        try {
+            await created.ready;
+        }
+        catch (error) {
+            this.children.delete(id);
+            await created.stop().catch(() => undefined);
+            throw new RelayRefusal('remote', `Starting engine ${id} failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return created;
+    }
+    /**
+     * Whether a child still owns a scheduled wake.
+     *
+     * A child that cannot answer is treated as holding one: stopping it could destroy a wake that
+     * is still owed, and a refused start is a visible failure while a lost wake is not.
+     */
+    /**
+     * Whether a child is free of a run.
+     *
+     * A child that cannot answer is not known to be free, and stopping one that is preparing a run
+     * would abort the task it accepted.
+     */
+    async childIsIdle(child) {
+        try {
+            const info = await child.request('host.info', {}, 5_000);
+            return info?.running !== true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async childHoldsWake(child) {
+        try {
+            const listed = await child.request('timers.list', {}, 5_000);
+            return (listed?.sessions ?? []).some(entry => Array.isArray(entry.timers) && entry.timers.length > 0);
+        }
+        catch {
+            return true;
+        }
+    }
+    async retireChild(id) {
+        const child = this.children.get(id);
+        if (!child)
+            return;
+        this.children.delete(id);
+        await child.stop().catch(() => undefined);
+    }
+    /**
+     * The bidirectional project-spelling translation for one viewer.
+     *
+     * Cached briefly per viewer workspace id: building it realpath-walks every authorized root, and a
+     * sessions listing or an event burst would otherwise pay that per call. The cache never outlives a
+     * pairing change by long — five seconds — so a newly registered project is executable almost
+     * immediately.
+     */
+    async translation(viewerWorkspaceId) {
+        const cached = this.translations.get(viewerWorkspaceId);
+        const now = Date.now();
+        if (cached && now - cached.at < 5_000)
+            return cached.translation;
+        const config = await loadConfig(this.directory);
+        const roots = await authorizedRoots(config);
+        const toHostMap = new Map();
+        const toViewerMap = new Map();
+        for (const root of roots) {
+            const spelling = viewerWorkspaceId !== undefined ? `${REMOTE_PROJECT_PREFIX}${viewerWorkspaceId}:${root.id}` : `${REMOTE_PROJECT_PREFIX}:${root.id}`;
+            toHostMap.set(spelling, root.path);
+            if (!toViewerMap.has(root.path))
+                toViewerMap.set(root.path, spelling);
+        }
+        const translation = {
+            toHost: value => {
+                if (!isRemoteProjectSpelling(value))
+                    return value;
+                const mapped = toHostMap.get(value);
+                if (mapped !== undefined)
+                    return mapped;
+                // A folder picked inside a root was hashed with a relative path only the viewer knows, so no
+                // host-side table can reverse it. Refusing with the fix is the answer that can be acted on.
+                throw new RelayRefusal('not-found', 'That folder was picked inside a shared root. Register the folder itself on this machine (Add on the rail, or a project on this host) to run tasks in it.');
+            },
+            toViewer: value => toViewerMap.get(value) ?? value,
+            rewrite: value => rewritePaths(value, toViewerMap),
+        };
+        this.translations.set(viewerWorkspaceId, { at: now, translation });
+        return translation;
+    }
+    /**
+     * Cut every live stream and terminal of devices that no longer hold full authority.
+     *
+     * Per-request authentication already refuses a revoked device's next call; this poller is for the
+     * resource a request never re-checks — the open event stream, and the shells its connection owns.
+     */
+    startRevocationPoll() {
+        if (this.revocationTimer !== undefined)
+            return;
+        const sweep = () => {
+            void (async () => {
+                const config = await loadConfig(this.directory);
+                const valid = new Set((config.remote?.hosting?.devices ?? []).filter(device => device.grant === 'full').map(device => device.id));
+                for (const [, connection] of [...this.connections]) {
+                    if (valid.has(connection.deviceId)) {
+                        // A connection made by requests whose stream never arrived (the viewer unloaded between
+                        // `remote.engine.connect` and its SSE GET) has no response-close callback to end it:
+                        // the poller retires it, sweeping the terminals it opened.
+                        if (connection.sinks.size === 0 && connection.sinklessSince !== 0 && Date.now() - connection.sinklessSince > SINKLESS_CONNECTION_TTL_MS) {
+                            this.sever(connection);
+                        }
+                        continue;
+                    }
+                    this.sever(connection);
+                }
+            })().catch(() => undefined);
+        };
+        this.revocationTimer = setInterval(sweep, REVOCATION_POLL_MS);
+        this.revocationTimer.unref?.();
+    }
+    /** Stop the pool: every child gets the graceful close, and no stream outlives the listener. */
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        if (this.revocationTimer !== undefined)
+            clearInterval(this.revocationTimer);
+        for (const connection of [...this.connections.values()])
+            this.sever(connection);
+        const children = [...this.children.values()];
+        this.children.clear();
+        await Promise.all(children.map(child => child.stop().catch(() => undefined)));
+    }
+}
+/** Rewrite every known host path inside an arbitrary payload, structurally. */
+function rewritePaths(value, paths) {
+    if (typeof value === 'string')
+        return paths.get(value) ?? value;
+    if (Array.isArray(value))
+        return value.map(entry => rewritePaths(entry, paths));
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [key, entry] of Object.entries(value))
+            out[key] = rewritePaths(entry, paths);
+        return out;
+    }
+    return value;
+}
+/**
+ * Answers that are the page's own data, not file-system answers. A selection that happens to read
+ * exactly like one of the host's shared-root paths is the user's text — rewriting it would put an
+ * `rw:` project identifier on the viewer's clipboard and, for a cut, delete the original from the
+ * page with only the identifier surviving.
+ */
+const OPAQUE_RESPONSE_METHODS = new Set(['browser.view.selection', 'browser.view.cursor']);
+export { REMOTE_PROJECT_PREFIX, isRemoteProjectSpelling, rootPartOf };