@osdlc/agent-seat 0.0.0-stage → 0.7.1

package/dist/hosts/orca.js

@@ -0,0 +1,292 @@
+/**
+ * Orca (com.stablyai.orca): a terminal tab on `cwd` running a command.
+ *
+ * Orca knows a worktree by path once its repository is registered, so an
+ * unknown-worktree failure is retried after `orca repo add --path <repoRoot>`; any
+ * other failure, and a second one, is reported verbatim.
+ *
+ * `terminal create --json` returns the new terminal's handle, which is
+ * remembered against the caller's session id (`./session-panes.ts`); a later
+ * request for that session targets that terminal among the worktree's, so two
+ * sessions in one worktree reach two terminals. A request without a remembered
+ * handle (no id, or a terminal opened before handles were remembered) targets the
+ * worktree's one live, writable agent terminal, and none when there are several.
+ */
+import { existsSync } from 'node:fs';
+import { commandString, failureText, ran, resolveRunner, } from '@osdlc/command-seam';
+import { isRecord, parseJsonOrNull } from "../util.js";
+import { onPath, supportsPlatform, } from "../contract.js";
+import { harnessOrNull, sessionViaTerminal } from "../harness.js";
+import { boundPane, rememberSessionPane } from "./session-panes.js";
+import { registryDirOf } from "./registry.js";
+/** The CLI the app bundle ships when `orca` is not on PATH. */
+export const ORCA_BUNDLED_CLI = '/Applications/Orca.app/Contents/Resources/bin/orca';
+export function orcaBinary() {
+    if (onPath('orca'))
+        return 'orca';
+    return existsSync(ORCA_BUNDLED_CLI) ? ORCA_BUNDLED_CLI : null;
+}
+/** Argv for `orca terminal create` — pure, so a test can pin it. */
+export function orcaCreateArgv(req) {
+    return [
+        'terminal',
+        'create',
+        '--worktree',
+        `path:${req.cwd}`,
+        '--title',
+        req.title,
+        '--command',
+        commandString(req.argv),
+        '--focus',
+        '--json',
+    ];
+}
+/** The new terminal's handle in `orca terminal create --json`: `result.terminal.handle`. */
+export function parseOrcaCreatedHandle(stdout) {
+    const handle = field(field(field(parseJsonOrNull(stdout), 'result'), 'terminal'), 'handle');
+    return typeof handle === 'string' && handle !== '' ? handle : null;
+}
+/** Seconds `orca terminal send` waits for `turn_started`; Orca's own request timeout is this plus 10s. */
+const ORCA_SEND_WAIT_SUBMIT_SECS = 10;
+export function orcaSendArgv(handle, text) {
+    return [
+        'terminal',
+        'send',
+        '--terminal',
+        handle,
+        '--text',
+        text,
+        '--enter',
+        '--wait-submit',
+        String(ORCA_SEND_WAIT_SUBMIT_SECS),
+        '--json',
+    ];
+}
+export function orcaSwitchArgv(handle) {
+    return ['terminal', 'switch', '--terminal', handle, '--json'];
+}
+/** `orca terminal close --terminal <handle>`: closes that terminal and kills what runs in it. */
+export function orcaCloseArgv(handle) {
+    return ['terminal', 'close', '--terminal', handle, '--json'];
+}
+/**
+ * Parses `orca terminal send --json`, which wraps its receipt as
+ * `{ok, result: {send: {accepted, prompt: {stages}}}}`. `accepted` alone only
+ * means the input reached the terminal; a `turn_started` stage confirms the
+ * agent took it. Unparseable output is `{accepted: false, ack: false}`.
+ */
+export function parseOrcaSendResponse(stdout) {
+    const send = field(field(parseJsonOrNull(stdout), 'result'), 'send');
+    const accepted = field(send, 'accepted') === true;
+    const stages = field(field(send, 'prompt'), 'stages');
+    const ack = accepted && Array.isArray(stages) && stages.includes('turn_started');
+    // Input accepted but no `turn_started`: Orca itself warns "inspect the terminal before
+    // retrying" (`docs/planning/research/orca.md`, "send"), so the text may be in the session.
+    return accepted && !ack ? { accepted, ack, uncertain: true } : { accepted, ack };
+}
+/** True when Orca rejected a handle issued before its last restart. */
+export function isOrcaHandleStale(stdout) {
+    return field(field(parseJsonOrNull(stdout), 'error'), 'code') === 'terminal_handle_stale';
+}
+function field(value, key) {
+    return isRecord(value) ? value[key] : undefined;
+}
+/** Argv for `orca terminal list --worktree path:<cwd> --json` — pure, so a test can pin it. */
+export function orcaFindArgv(query) {
+    return ['terminal', 'list', '--worktree', `path:${query.cwd}`, '--json'];
+}
+/** The terminal entries of `orca terminal list --json`: `result.terminals`, `terminals`, or a bare array. */
+function orcaFindResponseArray(parsed) {
+    if (Array.isArray(parsed))
+        return parsed;
+    const terminals = field(parsed, 'terminals') ?? field(field(parsed, 'result'), 'terminals');
+    return Array.isArray(terminals) ? terminals : null;
+}
+/**
+ * Parses `orca terminal list --json` into {@link FoundSession}s. An entry's
+ * `agentIdentity` is absent or null for a plain shell and a harness name
+ * otherwise, so `alive` means "an agent runs there". `lastOutputAt` is epoch
+ * milliseconds. Every entry gets the query's `cwd`, since `--worktree`
+ * already scoped the list. Unparseable output is `[]`.
+ */
+export function parseOrcaFindResponse(stdout, cwd) {
+    return parseOrcaTerminals(stdout, cwd).map(toFoundSession);
+}
+function toFoundSession(terminal) {
+    const { writable, ...session } = terminal;
+    void writable; // a found session does not report whether it accepts input
+    return session;
+}
+function parseOrcaTerminals(stdout, cwd) {
+    const entries = orcaFindResponseArray(parseJsonOrNull(stdout));
+    if (entries === null)
+        return [];
+    const found = [];
+    for (const entry of entries) {
+        if (!isRecord(entry))
+            continue;
+        const agentIdentity = entry['agentIdentity'];
+        const harness = harnessOrNull(agentIdentity);
+        const alive = agentIdentity !== null && agentIdentity !== undefined;
+        found.push({
+            cwd,
+            harness,
+            alive,
+            lastOutputAt: isoTimestamp(entry['lastOutputAt']),
+            handle: typeof entry['handle'] === 'string' ? entry['handle'] : null,
+            writable: entry['writable'] === true,
+        });
+    }
+    return found;
+}
+function isoTimestamp(value) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return new Date(value).toISOString();
+    return null;
+}
+function listOrcaTerminals(runner, cwd) {
+    const res = runner.run(orcaFindArgv({ cwd }), { cwd, timeoutMs: 30_000 });
+    return ran(res) ? parseOrcaTerminals(res.stdout, cwd) : [];
+}
+/**
+ * The handle of the terminal for `cwd` to act on, or null. With a remembered handle
+ * (`bound`) that is that terminal if Orca still lists it live and writable, and nothing
+ * otherwise: another session's terminal at the same worktree is not this one's. Without
+ * one it is the one live, writable agent terminal on `cwd` (of `harness` when given), or
+ * null when there are none or several: delivering into the wrong session is worse than no
+ * delivery. Handles change when Orca restarts, so resolve one right before using it.
+ */
+export function resolveOrcaHandle(runner, cwd, bound = null, harness) {
+    const terminals = listOrcaTerminals(runner, cwd);
+    if (bound !== null) {
+        return terminals.some((t) => t.handle === bound && t.writable) ? bound : null;
+    }
+    const matches = terminals.filter((t) => t.alive && t.writable && t.handle && (harness === undefined || t.harness === harness));
+    return matches.length === 1 ? (matches[0]?.handle ?? null) : null;
+}
+/**
+ * Whether a failed `terminal create` says Orca does not know the worktree. The exact
+ * wording is not recorded (`docs/planning/research/orca.md`), so this matches any
+ * mention of a worktree in its output.
+ */
+function isOrcaUnknownWorktree(res) {
+    return /worktree/i.test(res.stderr) || /worktree/i.test(res.stdout);
+}
+/**
+ * The Orca host: opens terminal tabs in Orca through its CLI, found as `orca` on PATH or the app's bundled CLI.
+ * darwin only. Remembers the terminal handle of each session under `runtimeDir`/`registryDir` ({@link HostStateOptions}).
+ */
+export function makeOrcaHost(opts) {
+    const binary = () => (opts.binary === undefined ? orcaBinary() : opts.binary);
+    const registryDir = registryDirOf('orca', opts);
+    const boundHandle = (target) => boundPane(registryDir, target);
+    return {
+        name: 'orca',
+        acksSend: true,
+        // Observed on macOS only; a platform that was not run is left out.
+        platforms: ['darwin'],
+        available() {
+            if (opts.binary === undefined && !supportsPlatform(this))
+                return false;
+            return binary() !== null;
+        },
+        terminal(req) {
+            const bin = binary();
+            if (bin === null)
+                throw new Error(`orca is not on PATH and ${ORCA_BUNDLED_CLI} is absent`);
+            const runner = resolveRunner(bin, opts.runner);
+            const argv = orcaCreateArgv(req);
+            let res = runner.run(argv, { cwd: req.cwd, timeoutMs: 60_000 });
+            // Only an unknown worktree is retried. Any other failure, or a create that never exited
+            // (timed out, killed), may have opened the terminal already: a second create would start
+            // the agent twice.
+            if (!ran(res) &&
+                res.neverExited !== true &&
+                opts.repoRoot !== undefined &&
+                isOrcaUnknownWorktree(res)) {
+                runner.run(['repo', 'add', '--path', opts.repoRoot], { cwd: req.cwd, timeoutMs: 60_000 });
+                res = runner.run(argv, { cwd: req.cwd, timeoutMs: 60_000 });
+            }
+            if (!ran(res)) {
+                throw new Error(`orca terminal create failed: ${failureText(res)}\n` +
+                    `If Orca does not know this worktree, open it there first: orca worktree list`);
+            }
+            const handle = parseOrcaCreatedHandle(res.stdout);
+            if (handle !== null && req.sessionId !== undefined) {
+                rememberSessionPane(registryDir, req.sessionId, handle, req.cwd);
+            }
+            return 0;
+        },
+        // Orca's own `terminal create` call carries no session identity of its
+        // own to hand back, but `wrapperSession` (`../harness.ts`) can still
+        // resolve one independently of Orca, when the harness itself exposes a
+        // way to (codex's own rollout-file scan) — see its doc for why
+        // claude/cursor/pi currently always come back null regardless of host.
+        session: sessionViaTerminal,
+        send(req) {
+            const bin = binary();
+            if (bin === null)
+                return { accepted: false, ack: false };
+            const runner = resolveRunner(bin, opts.runner);
+            const trySend = () => {
+                const handle = resolveOrcaHandle(runner, req.cwd, boundHandle(req), req.harness);
+                if (handle === null)
+                    return null;
+                try {
+                    return runner.run(orcaSendArgv(handle, req.text), { cwd: req.cwd, timeoutMs: 30_000 });
+                }
+                catch {
+                    // The runner throws on text it cannot pass at all (a NUL byte); `send` never throws.
+                    return null;
+                }
+            };
+            let res = trySend();
+            if (res !== null && isOrcaHandleStale(res.stdout))
+                res = trySend();
+            if (res === null || !ran(res))
+                return { accepted: false, ack: false };
+            return parseOrcaSendResponse(res.stdout);
+        },
+        find(query) {
+            const bin = binary();
+            if (bin === null)
+                return [];
+            // A find failure means "nothing found", not an exception.
+            const found = listOrcaTerminals(resolveRunner(bin, opts.runner), query.cwd);
+            const bound = boundHandle(query);
+            return (bound === null ? found : found.filter((t) => t.handle === bound)).map(toFoundSession);
+        },
+        focus(query) {
+            const bin = binary();
+            if (bin === null)
+                return false;
+            const runner = resolveRunner(bin, opts.runner);
+            const handle = resolveOrcaHandle(runner, query.cwd, boundHandle(query));
+            if (handle === null)
+                return false;
+            return ran(runner.run(orcaSwitchArgv(handle), { cwd: query.cwd, timeoutMs: 30_000 }));
+        },
+        close(query) {
+            const bin = binary();
+            if (bin === null)
+                return false;
+            try {
+                // Closing is destructive: a session whose terminal was never remembered (opened before
+                // handles were) is left open rather than closing whichever agent terminal is first there.
+                const bound = boundHandle(query);
+                if (query.sessionId !== undefined && bound === null)
+                    return false;
+                const runner = resolveRunner(bin, opts.runner);
+                const handle = resolveOrcaHandle(runner, query.cwd, bound);
+                if (handle === null)
+                    return false;
+                return (runner.run(orcaCloseArgv(handle), { cwd: query.cwd, timeoutMs: 30_000 }).exitCode === 0);
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}

package/dist/hosts/otty.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Otty (darwin only): a tab on `cwd` running a command, found again by a tag
+ * in its title: derived from the caller's session id when the launch has one, else
+ * from `cwd`. Research: `docs/planning/research/otty.md`
+ * (otty 1.5.4; the app was not running, so every JSON shape here is DOCS-ONLY:
+ * `--help` names the flags but `pane list --json` output was never observed).
+ *
+ * Otty's control CLI needs the running app; without it every command exits
+ * nonzero with "Cannot connect to Otty ... Is Otty running?" (observed). So
+ * send/find/focus/capture treat any nonzero exit as "no session" and never throw.
+ *
+ * `--help` does not show whether `pane list` carries a cwd, so a pane matches when a
+ * cwd-like field equals `cwd` OR any string field contains {@link ottyTag}, which
+ * `terminal()` appends to the tab title. A request with a session id matches by the
+ * id's tag alone (or, for a tab opened before ids were tagged, the cwd's tag), never by
+ * a bare cwd field: that would reach another session's pane in the same directory. Whether `pane list` exposes the title is also
+ * unverified (`docs/planning/research/otty.md`). `send` goes only to a pane carrying the tag (one this host
+ * opened) AND showing an agent in the foreground: the tag stays in the tab title
+ * after the agent exits, and the tab then holds a plain shell, where the pointer
+ * would run as a command. A pane that does not name its foreground process is
+ * therefore never sent to and `find` reports it not alive, so a caller falls
+ * back to another route.
+ */
+import { type CommandRunner } from '@osdlc/command-seam';
+import { type CommandRequest, type Host } from '../contract.ts';
+/**
+ * A tag appended to the tab title so a later `find` can match it: stable for the
+ * caller's session id when there is one (`[sd-i-<slug>]`, {@link sessionIdSlug}: the id's first
+ * 12 characters, rewritten to `[A-Za-z0-9_-]`, and 8 hex digits of a hash of the whole id, so
+ * ids sharing a prefix get different tags), else for `cwd` (`[sd-<hash>]`).
+ */
+export declare function ottyTag(cwd: string, sessionId?: string): string;
+/** Argv for `otty tab new` — pure, so a test can pin it. */
+export declare function ottyCreateArgv(req: CommandRequest): string[];
+export declare function ottyListArgv(): string[];
+/**
+ * Argv for `otty pane send-keys`: the text pasted bracketed (so embedded
+ * newlines are not Enters), then a separate `key:Enter` part. `--` keeps a
+ * `-`-prefixed text from being read as a flag.
+ */
+export declare function ottySendArgv(paneId: string, text: string): string[];
+export declare function ottyFocusArgv(paneId: string): string[];
+export declare function ottyCaptureArgv(paneId: string): string[];
+/**
+ * Argv for `otty pane close`; `--yes` skips the destructive-action prompt (the global
+ * flag of `otty pane close --help`). Closing a tab's last pane closes the tab.
+ */
+export declare function ottyCloseArgv(paneId: string): string[];
+/**
+ * The pane ids in `otty pane list --json` that belong to `cwd`: a bare array
+ * or `{panes: [...]}` of objects with an `id` (or `pane_id`). Unparseable
+ * output is `[]`. Field names are DOCS-ONLY guesses; see the module doc.
+ * `taggedOnly` drops the panes matched by a cwd field alone; `agentOnly` keeps
+ * only panes whose foreground process is a known agent.
+ */
+export declare function parseOttyPanes(stdout: string, cwd: string, opts?: {
+    taggedOnly?: boolean;
+    agentOnly?: boolean;
+    sessionId?: string | undefined;
+    /** With a session id, only its own tab: never the cwd-tagged fallback. */
+    idOnly?: boolean;
+}): string[];
+/**
+ * The Otty host: opens tabs in the Otty app through the `otty` binary, which must be on PATH; the app must be running.
+ * darwin only. Keeps no state of its own; tabs are found again by a tag in their title.
+ */
+export declare function makeOttyHost(opts?: {
+    runner?: CommandRunner | undefined;
+    available?: (() => boolean) | undefined;
+}): Host;

package/dist/hosts/otty.js

@@ -0,0 +1,233 @@
+/**
+ * Otty (darwin only): a tab on `cwd` running a command, found again by a tag
+ * in its title: derived from the caller's session id when the launch has one, else
+ * from `cwd`. Research: `docs/planning/research/otty.md`
+ * (otty 1.5.4; the app was not running, so every JSON shape here is DOCS-ONLY:
+ * `--help` names the flags but `pane list --json` output was never observed).
+ *
+ * Otty's control CLI needs the running app; without it every command exits
+ * nonzero with "Cannot connect to Otty ... Is Otty running?" (observed). So
+ * send/find/focus/capture treat any nonzero exit as "no session" and never throw.
+ *
+ * `--help` does not show whether `pane list` carries a cwd, so a pane matches when a
+ * cwd-like field equals `cwd` OR any string field contains {@link ottyTag}, which
+ * `terminal()` appends to the tab title. A request with a session id matches by the
+ * id's tag alone (or, for a tab opened before ids were tagged, the cwd's tag), never by
+ * a bare cwd field: that would reach another session's pane in the same directory. Whether `pane list` exposes the title is also
+ * unverified (`docs/planning/research/otty.md`). `send` goes only to a pane carrying the tag (one this host
+ * opened) AND showing an agent in the foreground: the tag stays in the tab title
+ * after the agent exits, and the tab then holds a plain shell, where the pointer
+ * would run as a command. A pane that does not name its foreground process is
+ * therefore never sent to and `find` reports it not alive, so a caller falls
+ * back to another route.
+ */
+import { commandString, failureText, ran, resolveRunner, } from '@osdlc/command-seam';
+import { BUILTIN_HARNESSES, HARNESS_ALIASES } from '@osdlc/detect-harness';
+import { isRecord, parseJsonOrNull, sessionIdSlug, shortHash } from "../util.js";
+import { onPath, quietRun, supportsPlatform, } from "../contract.js";
+import { sessionViaTerminal } from "../harness.js";
+/**
+ * A tag appended to the tab title so a later `find` can match it: stable for the
+ * caller's session id when there is one (`[sd-i-<slug>]`, {@link sessionIdSlug}: the id's first
+ * 12 characters, rewritten to `[A-Za-z0-9_-]`, and 8 hex digits of a hash of the whole id, so
+ * ids sharing a prefix get different tags), else for `cwd` (`[sd-<hash>]`).
+ */
+export function ottyTag(cwd, sessionId) {
+    if (sessionId !== undefined)
+        return `[sd-i-${sessionIdSlug(sessionId)}]`;
+    return `[sd-${shortHash(cwd, 12)}]`;
+}
+/** Argv for `otty tab new` — pure, so a test can pin it. */
+export function ottyCreateArgv(req) {
+    return [
+        'tab',
+        'new',
+        '--cwd',
+        req.cwd,
+        '--command',
+        commandString(req.argv),
+        '--title',
+        `${req.title} ${ottyTag(req.cwd, req.sessionId)}`,
+        '--no-focus',
+        '--json',
+    ];
+}
+export function ottyListArgv() {
+    return ['pane', 'list', '--json'];
+}
+/**
+ * Argv for `otty pane send-keys`: the text pasted bracketed (so embedded
+ * newlines are not Enters), then a separate `key:Enter` part. `--` keeps a
+ * `-`-prefixed text from being read as a flag.
+ */
+export function ottySendArgv(paneId, text) {
+    return ['pane', 'send-keys', '--pane', paneId, '--bracketed-paste', '--', text, 'key:Enter'];
+}
+export function ottyFocusArgv(paneId) {
+    return ['pane', 'focus', paneId];
+}
+export function ottyCaptureArgv(paneId) {
+    return ['pane', 'capture', '--pane', paneId];
+}
+/**
+ * Argv for `otty pane close`; `--yes` skips the destructive-action prompt (the global
+ * flag of `otty pane close --help`). Closing a tab's last pane closes the tab.
+ */
+export function ottyCloseArgv(paneId) {
+    return ['pane', 'close', '--pane', paneId, '--yes'];
+}
+const CWD_KEYS = ['cwd', 'working_directory', 'current_directory'];
+/** Pane fields that may name the foreground process (DOCS-ONLY guesses, like the rest). */
+const PROCESS_KEYS = ['foreground_process', 'process', 'running_command', 'command', 'agent'];
+/** Executable names that mean an agent is running: each built-in harness id and alias (`cursor-agent`, `agy`). */
+const AGENT_BINS = new Set([
+    ...BUILTIN_HARNESSES,
+    ...Object.keys(HARNESS_ALIASES),
+]);
+/** Whether the pane entry names a known agent as its foreground process. */
+function showsAgent(entry) {
+    return PROCESS_KEYS.some((k) => {
+        const v = entry[k];
+        if (typeof v !== 'string')
+            return false;
+        const bin = v.trim().split(/\s+/)[0]?.split(/[\\/]/).pop() ?? '';
+        return AGENT_BINS.has(bin);
+    });
+}
+/**
+ * The pane ids in `otty pane list --json` that belong to `cwd`: a bare array
+ * or `{panes: [...]}` of objects with an `id` (or `pane_id`). Unparseable
+ * output is `[]`. Field names are DOCS-ONLY guesses; see the module doc.
+ * `taggedOnly` drops the panes matched by a cwd field alone; `agentOnly` keeps
+ * only panes whose foreground process is a known agent.
+ */
+export function parseOttyPanes(stdout, cwd, opts = {}) {
+    const parsed = parseJsonOrNull(stdout);
+    const entries = Array.isArray(parsed) ? parsed : isRecord(parsed) ? parsed['panes'] : null;
+    if (!Array.isArray(entries))
+        return [];
+    const cwdTag = ottyTag(cwd);
+    const idTag = opts.sessionId === undefined ? null : ottyTag(cwd, opts.sessionId);
+    const byIdTag = [];
+    const byCwdTag = [];
+    const byBareCwd = [];
+    for (const entry of entries) {
+        if (!isRecord(entry))
+            continue;
+        const id = entry['id'] ?? entry['pane_id'];
+        if (typeof id !== 'string' && typeof id !== 'number')
+            continue;
+        if (opts.agentOnly === true && !showsAgent(entry))
+            continue;
+        const tagged = (tag) => Object.values(entry).some((v) => typeof v === 'string' && v.includes(tag));
+        if (idTag !== null && tagged(idTag))
+            byIdTag.push(String(id));
+        else if (tagged(cwdTag))
+            byCwdTag.push(String(id));
+        else if (CWD_KEYS.some((k) => entry[k] === cwd))
+            byBareCwd.push(String(id));
+    }
+    // With a session id: its own tab, else (a tab opened before ids were tagged) the cwd's tag.
+    // A bare cwd field never counts there: it could be another session's tab or a plain shell.
+    if (idTag !== null)
+        return byIdTag.length > 0 || opts.idOnly === true ? byIdTag : byCwdTag;
+    return opts.taggedOnly === true ? byCwdTag : [...byCwdTag, ...byBareCwd];
+}
+/**
+ * The Otty host: opens tabs in the Otty app through the `otty` binary, which must be on PATH; the app must be running.
+ * darwin only. Keeps no state of its own; tabs are found again by a tag in their title.
+ */
+export function makeOttyHost(opts = {}) {
+    const runner = () => resolveRunner('otty', opts.runner);
+    /** `pane list --json` output for `cwd`, or null (also when the app is not running). */
+    const listOutput = (cwd) => quietRun(runner(), ottyListArgv(), { cwd, timeoutMs: 10_000 });
+    /** The first pane for the request (tagged ones only when `taggedOnly`), or null. */
+    const resolvePane = (target, pick = {}) => {
+        const out = listOutput(target.cwd);
+        return out === null
+            ? null
+            : (parseOttyPanes(out, target.cwd, { ...pick, sessionId: target.sessionId })[0] ?? null);
+    };
+    return {
+        name: 'otty',
+        platforms: ['darwin'],
+        available() {
+            if (opts.available !== undefined)
+                return opts.available();
+            return supportsPlatform(this) && onPath('otty');
+        },
+        terminal(req) {
+            const res = runner().run(ottyCreateArgv(req), { cwd: req.cwd, timeoutMs: 60_000 });
+            if (!ran(res))
+                throw new Error(`otty tab new failed: ${failureText(res)}`);
+            return 0;
+        },
+        session: sessionViaTerminal,
+        send(req) {
+            // Otty has no delivery confirmation, so ack is always false.
+            try {
+                const pane = resolvePane(req, { taggedOnly: true, agentOnly: true });
+                if (pane === null)
+                    return { accepted: false, ack: false };
+                const res = runner().run(ottySendArgv(pane, req.text), { cwd: req.cwd, timeoutMs: 15_000 });
+                return { accepted: ran(res), ack: false };
+            }
+            catch {
+                return { accepted: false, ack: false };
+            }
+        },
+        find(query) {
+            const out = listOutput(query.cwd);
+            if (out === null)
+                return [];
+            const pick = { sessionId: query.sessionId };
+            // No harness identity and no output-recency signal are documented. A pane
+            // is alive only while it shows an agent in the foreground: the tab outlives
+            // the agent, as a shell. The agent pane is returned when there is one, so
+            // `alive` describes the pane whose handle is returned.
+            const agentPane = parseOttyPanes(out, query.cwd, { ...pick, agentOnly: true })[0];
+            const pane = agentPane ?? parseOttyPanes(out, query.cwd, pick)[0];
+            if (pane === undefined)
+                return [];
+            return [
+                {
+                    cwd: query.cwd,
+                    harness: null,
+                    alive: agentPane !== undefined,
+                    lastOutputAt: null,
+                    handle: pane,
+                },
+            ];
+        },
+        focus(query) {
+            const pane = resolvePane(query);
+            if (pane === null)
+                return false;
+            return quietRun(runner(), ottyFocusArgv(pane), { cwd: query.cwd, timeoutMs: 10_000 }) !== null;
+        },
+        capture(query) {
+            const pane = resolvePane(query);
+            if (pane === null)
+                return null;
+            return quietRun(runner(), ottyCaptureArgv(pane), { cwd: query.cwd, timeoutMs: 10_000 });
+        },
+        close(query) {
+            // Closing is destructive: with a session id only that session's own tab closes. The
+            // cwd-tagged tab may belong to another launch at the same cwd that carried no id.
+            // Without an id, every id-less launch at the cwd carries the same tag, so close only
+            // when exactly one tab does: any pick among several could close another session's.
+            const out = listOutput(query.cwd);
+            if (out === null)
+                return false;
+            const panes = parseOttyPanes(out, query.cwd, {
+                taggedOnly: true,
+                idOnly: true,
+                sessionId: query.sessionId,
+            });
+            const pane = query.sessionId !== undefined || panes.length === 1 ? panes[0] : undefined;
+            if (pane === undefined)
+                return false;
+            return quietRun(runner(), ottyCloseArgv(pane), { cwd: query.cwd, timeoutMs: 10_000 }) !== null;
+        },
+    };
+}

package/dist/hosts/registry.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The shared reader for a host's registry: `<runtime>/hosts/<name>/*.json`,
+ * one file per running IDE or window, written by the extension or plugin that
+ * owns it. `<runtime>` is the caller's runtime directory (`runtimeDir`); the
+ * package picks none of its own, because the IDE companions must write to the
+ * same place.
+ */
+/** Where host `name` keeps its state under `runtimeDir`: `<runtimeDir>/hosts/<name>`. */
+export declare function hostRegistryDir(runtimeDir: string, name: string): string;
+/**
+ * Where a stateful host keeps its files. Give one of the two: `registryDir` is
+ * used as is; otherwise the host uses `<runtimeDir>/hosts/<name>`.
+ */
+export type HostStateOptions = {
+    /** The caller's runtime directory; the host uses `<runtimeDir>/hosts/<name>`. */
+    runtimeDir: string;
+    /** The host's own directory, used as is. Wins over `runtimeDir`. */
+    registryDir?: string | undefined;
+} | {
+    runtimeDir?: string | undefined;
+    /** The host's own directory, used as is. */
+    registryDir: string;
+};
+/** Host `name`'s state directory under `opts`. */
+export declare function registryDirOf(name: string, opts: HostStateOptions): string;
+/** How {@link readHostRegistry} decides whom to trust; injectable for tests. */
+export interface RegistryTrustOptions {
+    /** The uid entries must belong to; null skips the check (Windows). Default `process.getuid()`. */
+    uid?: number | null | undefined;
+    /** Told why an entry or the whole directory was skipped as untrusted. */
+    onSkip?: ((reason: string) => void) | undefined;
+}
+/**
+ * Entries in `dir` that `parse` accepts and whose process is alive. A missing
+ * directory, an unreadable or malformed file, and a dead pid are all skipped.
+ *
+ * An entry carries an endpoint and a token, so a planted one would receive
+ * every session's argv and sent text. On POSIX the whole directory is skipped
+ * unless it belongs to the current user and is not group- or world-writable,
+ * and so is each file; `opts.onSkip` hears why. Windows has no uid to check.
+ */
+export declare function readHostRegistry<T extends {
+    pid: number;
+}>(dir: string, parse: (raw: unknown) => T | null, alive: (pid: number) => boolean, opts?: RegistryTrustOptions): T[];
+/**
+ * The candidate with the deepest folder containing `cwd` (depth = length of the
+ * real path), the newest `startedAt` winning a tie, then the earliest in list
+ * order. Null when no folder contains `cwd`. How both IDE hosts pick a window.
+ */
+export declare function deepestContaining<T>(cwd: string, candidates: readonly T[], folders: (c: T) => readonly string[], startedAt: (c: T) => string): T | null;