@platless/axom-cli 0.3.13 → 0.5.9

package/dist/workstation/keepers/terminal/generations.js

@@ -0,0 +1,129 @@
+// Daemon-side: keeper-terminal generations (Task 26, spec §3.1, §8.3). One keeper-terminal per build ("generation") may run; after a
+// CLI upgrade an OLDER generation can still host PTYs and execs while a newer one takes new work. Nothing here starts an older
+// generation: only the current build's client launches keeper-terminal. Exempt from the keeper-side import guard (daemon module).
+//
+// - New work (a `terminal.create`, an exec start) goes to the SERVING generation: the current build's, unless the replacement policy
+//   (keepers/policy.ts) keeps an older, still compatible generation serving (`replacement: 'available'` and nobody asked to replace
+//   it — spec §8.3: an available update never does anything by itself).
+// - Everything else is routed by OWNER: a PTY id or an exec id is served by the generation that runs it, through a client bound to
+//   that generation (tools/terminalRouter.ts, exec/policy.ts).
+import path from 'node:path';
+import { readKeeperManifest } from '../kit/bundle.js';
+import { TerminalKeeperClient } from './client.js';
+import { defaultDistDir } from '../kit/launcher.js';
+/** How long one listing of the live generations is reused (each costs a pid-manifest read and a process lookup per generation). */
+export const LIVE_GENERATIONS_TTL_MS = 2000;
+export class TerminalGenerations {
+    options;
+    /** The current build's client: the only one that launches keeper-terminal. */
+    primary;
+    bound = new Map();
+    currentGenValue;
+    manifestValue;
+    liveCache;
+    now;
+    /** Set by the replacement policy; absent = the current build always serves. */
+    picker;
+    constructor(options) {
+        this.options = options;
+        this.now = options.now ?? Date.now;
+        this.primary = options.primary ?? new TerminalKeeperClient({
+            launcher: options.launcher, distDir: options.distDir, daemonProtocol: options.daemonProtocol,
+            requestTimeoutMs: options.requestTimeoutMs, connectTimeoutMs: options.connectTimeoutMs,
+        });
+    }
+    /** The current build's manifest (`dist/keepers/terminal/manifest.json`), read once. */
+    manifest() {
+        this.manifestValue ??= readKeeperManifest(path.join(this.options.distDir ?? defaultDistDir(), 'terminal'))
+            .catch((error) => { this.manifestValue = undefined; throw error; });
+        return this.manifestValue;
+    }
+    /** The generation the current build runs as. */
+    currentGen() {
+        this.currentGenValue ??= this.options.launcher.currentGen('terminal')
+            .catch((error) => { this.currentGenValue = undefined; throw error; });
+        return this.currentGenValue;
+    }
+    /** Generations with a live keeper-terminal (pid manifest), the current one included when it runs. Starts nothing. Briefly cached. */
+    live() {
+        const cached = this.liveCache;
+        if (cached && this.now() - cached.at < LIVE_GENERATIONS_TTL_MS)
+            return cached.gens;
+        const gens = this.options.launcher.liveGenerations('terminal');
+        this.liveCache = { at: this.now(), gens };
+        gens.catch(() => { if (this.liveCache?.gens === gens)
+            this.liveCache = undefined; });
+        return gens;
+    }
+    /** Forget the cached listing (a generation was started or stopped). */
+    invalidate() { this.liveCache = undefined; }
+    /** The client of `gen`: the current build's own, or one bound to `gen` that only connects. */
+    async client(gen) {
+        if (gen === await this.currentGen().catch(() => undefined))
+            return this.primary;
+        let client = this.bound.get(gen);
+        if (!client) {
+            client = new TerminalKeeperClient({
+                launcher: this.options.launcher, distDir: this.options.distDir, daemonProtocol: this.options.daemonProtocol,
+                requestTimeoutMs: this.options.requestTimeoutMs, connectTimeoutMs: this.options.connectTimeoutMs, gen,
+            });
+            this.bound.set(gen, client);
+        }
+        return client;
+    }
+    /** The serving generation (see the file comment). Never starts anything itself; its client's `ensure()` may (current build only). */
+    async servingGeneration() {
+        let current;
+        try {
+            current = await this.currentGen();
+        }
+        catch {
+            return { gen: 'current', client: this.primary };
+        } // no build: as before
+        let older;
+        if (this.picker) {
+            try {
+                const candidates = (await this.live()).filter((gen) => gen !== current);
+                if (candidates.length > 0)
+                    older = await this.picker(current, candidates);
+            }
+            catch {
+                older = undefined;
+            }
+        }
+        return older !== undefined && older !== current ? { gen: older, client: await this.client(older) } : { gen: current, client: this.primary };
+    }
+    /** `ExecKeeperGenerations.serving` / the router's create target. */
+    async serving() { return (await this.servingGeneration()).client; }
+    /** Every live generation with its client (the current build's only when it runs). Starts nothing. */
+    async running() {
+        const gens = [...await this.live()];
+        // The current build's client launched keeper-terminal since the (cached) listing: it runs.
+        const current = await this.currentGen().catch(() => undefined);
+        if (current !== undefined && this.primary.hello && !gens.includes(current))
+            gens.push(current);
+        return Promise.all(gens.map(async (gen) => ({ gen, client: await this.client(gen) })));
+    }
+    /** `ExecKeeperGenerations.others`: the clients of every live generation except the serving one. */
+    async others() {
+        const serving = await this.serving();
+        return (await this.running()).map((generation) => generation.client).filter((client) => client !== serving);
+    }
+    /** `tools.info` terminal fields from the serving generation when it already runs, else `fallback`. Starts nothing. */
+    async terminalStatus(fallback) {
+        return (await this.serving()).terminalStatus(fallback);
+    }
+    /** Drops the connection to `gen` (it was stopped). */
+    forget(gen) {
+        this.bound.get(gen)?.disconnect();
+        this.bound.delete(gen);
+        this.invalidate();
+    }
+    /** Drops every connection (the keepers and their PTYs keep running). */
+    disconnect() {
+        this.primary.disconnect();
+        for (const client of this.bound.values())
+            client.disconnect();
+        this.bound.clear();
+    }
+}

package/dist/workstation/keepers/terminal/keeper.js

@@ -0,0 +1,62 @@
+// keeper-terminal's methods on the kit server: `pty.*` over PtySessions, `exec.*` over ExecHost, plus their activity samplers.
+// Keeper-side module: node builtins and kit siblings only (the import guard enforces it).
+import { constants, promises as fs } from 'node:fs';
+import { absolutePath, badRequest as bad, environment } from './params.js';
+import { CREATE_KEYS, PtySessions } from './pty.js';
+import { KeeperMethodError } from '../kit/protocol.js';
+import { EXEC_CAPABILITY, ExecErrorCode, PTY_CAPABILITY, execStream } from './protocol.js';
+/**
+ * `pty.create`'s launch: the daemon's absolute cwd (must be a directory now), absolute shell (an executable file now: a bad path
+ * would otherwise spawn, exit at once and still hold one of the 8 session slots) and complete env. Never this process's own env.
+ */
+async function launchOf(p) {
+    const cwd = absolutePath(p.cwd, 'cwd');
+    const shell = absolutePath(p.shell, 'shell');
+    const env = environment(p.env);
+    const stat = await fs.stat(cwd).catch(() => null);
+    if (!stat?.isDirectory())
+        bad('Terminal working directory is not a directory');
+    const executable = await fs.stat(shell).then((s) => s.isFile(), () => false) && await fs.access(shell, constants.X_OK).then(() => true, () => false);
+    if (!executable)
+        bad('Terminal shell is not an executable file');
+    return { cwd, shell, env };
+}
+export const KEEPER_CREATE_KEYS = [...CREATE_KEYS, 'shell', 'env'];
+export function createTerminalKeeper(options = {}) {
+    const sessions = new PtySessions(options);
+    const exec = options.exec;
+    return {
+        sessions,
+        exec,
+        capabilities: [...(sessions.available ? [PTY_CAPABILITY] : []), ...(exec ? [EXEC_CAPABILITY] : [])],
+        install(server) {
+            server.register('pty.create', (params) => sessions.create(params, KEEPER_CREATE_KEYS, () => launchOf(params)), { startsWork: true });
+            server.register('pty.list', (params) => sessions.list(params));
+            for (const op of ['attach', 'poll', 'write', 'resize', 'takeover', 'detach', 'close'])
+                server.register(`pty.${op}`, (params) => sessions.operate(op, params));
+            server.addActivitySampler(() => sessions.activity());
+            if (!exec)
+                return;
+            server.register('exec.start', (params) => exec.start(params), { startsWork: true });
+            server.register('exec.list', () => exec.list());
+            server.register('exec.status', (params) => exec.status(params));
+            server.register('exec.read', (params) => exec.read(params));
+            server.register('exec.kill', (params) => exec.kill(params));
+            server.register('exec.commit', (params) => exec.commit(params));
+            server.register('exec.checkpoint', (params) => exec.checkpoint(params));
+            server.register('exec.subscribe', (params, context) => {
+                const { execId, from = 0, credit = 0 } = params;
+                if (typeof execId !== 'string' || !Number.isSafeInteger(from) || from < 0 || !Number.isSafeInteger(credit) || credit < 0)
+                    bad('exec.subscribe needs execId, from >= 0 and credit >= 0');
+                const source = exec.source(execId);
+                if (!source)
+                    throw new KeeperMethodError(ExecErrorCode.notFound, 'Exec not found');
+                context.subscribe(execStream(execId), source, from, credit);
+                return { stream: execStream(execId), from };
+            });
+            server.setStreamResolver((stream) => (stream.startsWith('exec/') ? exec.source(stream.slice('exec/'.length)) : undefined));
+            server.addActivitySampler(exec.activity);
+        },
+        shutdown: async () => { await Promise.all([sessions.dispose(), exec?.dispose()]); },
+    };
+}

package/dist/workstation/keepers/terminal/main.js

@@ -0,0 +1,43 @@
+// keeper-terminal: hosts persistent PTY sessions (spec §4.1) and durable non-interactive execs (spec §4.2). Started by the daemon's
+// KeeperLauncher as `node <bundleDir>/keeper.mjs <launch config>` and outlives daemon restarts and CLI upgrades.
+// `scripts/bundle-keepers.mjs` reads `protocolVersion` below (the line must keep this exact shape) and
+// `../daemonProtocol.json` for the daemon protocol range. It must equal TERMINAL_PROTOCOL_VERSION (protocol.ts).
+import { realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path, { sep } from 'node:path';
+import { runKeeperMain } from '../kit/bootstrap.js';
+import { ExecHost } from './exec.js';
+import { createTerminalKeeper } from './keeper.js';
+export const protocolVersion = 1;
+/**
+ * node-pty from the bundle snapshot's own `node_modules` (copied next to keeper.mjs), never one found further up the
+ * directory tree: the snapshot is what the build hashed. Missing or foreign → PTYs unavailable (`pty` capability absent).
+ */
+function loadBundledPty(bundleDir) {
+    const load = createRequire(import.meta.url);
+    const resolved = realpathSync(load.resolve('node-pty'));
+    if (!resolved.startsWith(realpathSync(bundleDir) + sep))
+        throw new Error(`node-pty resolves outside the keeper bundle (${resolved})`);
+    return load('node-pty');
+}
+await runKeeperMain({
+    kind: 'terminal',
+    protocolVersion,
+    create: async (config, { log }) => {
+        // Execs live under the kind's data dir (shared by its generations; each exec belongs to the keeper process that spawned it).
+        const exec = new ExecHost({ root: path.join(config.dataDir, 'exec'), owner: { pid: process.pid, gen: config.gen, bundleDir: config.bundleDir }, log });
+        await exec.open(); // startup sweep: execs whose keeper died get keeper_lost before anyone can ask
+        return createTerminalKeeper({
+            exec,
+            loadPty: () => {
+                try {
+                    return loadBundledPty(config.bundleDir);
+                }
+                catch (error) {
+                    log(`node-pty unavailable: ${error instanceof Error ? error.message : String(error)}`);
+                    throw error;
+                }
+            },
+        });
+    },
+});

package/dist/workstation/keepers/terminal/orphanSweep.js

@@ -0,0 +1,3 @@
+// The PID-reuse-safe process identity moved to the kit (keeper-acp settles its adapters' groups the same way).
+// Keeper-side module: node builtins and kit siblings only (the import guard enforces it).
+export * from '../kit/orphanSweep.js';

package/dist/workstation/keepers/terminal/params.js

@@ -0,0 +1,27 @@
+// Parameter checks shared by `pty.create` and `exec.start` (the daemon decides cwd/env; the keeper only refuses malformed input).
+// Keeper-side module: node builtins and kit siblings only (the import guard enforces it).
+import path from 'node:path';
+import { KeeperMethodError } from '../kit/protocol.js';
+export const MAX_PATH = 4096;
+export const MAX_ENV_ENTRIES = 4096;
+export const badRequest = (message) => { throw new KeeperMethodError('bad_request', message); };
+export function absolutePath(value, name) {
+    if (typeof value !== 'string' || !value.length || value.length > MAX_PATH || value.includes('\0') || !path.isAbsolute(value))
+        badRequest(`Invalid ${name}`);
+    return value;
+}
+/** The environment exactly as the daemon sent it: string values only, no `=` or NUL in names, no NUL in values. */
+export function environment(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return badRequest('Invalid env');
+    const entries = Object.entries(value);
+    if (entries.length > MAX_ENV_ENTRIES)
+        badRequest('Invalid env');
+    const env = {};
+    for (const [name, entry] of entries) {
+        if (!name || name.includes('=') || name.includes('\0') || typeof entry !== 'string' || entry.includes('\0'))
+            badRequest('Invalid env');
+        env[name] = entry;
+    }
+    return env;
+}

package/dist/workstation/keepers/terminal/protocol.js

@@ -0,0 +1,56 @@
+// keeper-terminal's wire vocabulary, shared by the keeper (`main.ts`, `pty.ts`) and the daemon (`client.ts`).
+// Keeper-side module: node builtins and kit siblings only (the import guard enforces it). Spec §4.1.
+/** The keeper protocol this code speaks. `main.ts` declares the same number for the bundler (a test keeps them equal). */
+export const TERMINAL_PROTOCOL_VERSION = 1;
+/** `keeper.hello` capability: node-pty loaded from the bundle snapshot, so `pty.*` works. Absent = PTYs unavailable. */
+export const PTY_CAPABILITY = 'pty';
+/** The legacy keeper's wording (tools/terminal.ts at the merge-base) when node-pty does not load; every `pty.*` call but `pty.list` answers it. */
+export const PTY_UNAVAILABLE_ERROR = 'Terminal native dependency unavailable; reinstall CLI with optional node-pty support';
+/** Ring of rendered output kept per session, the largest poll delta, the scrollback serialised into a snapshot. */
+export const PTY_HISTORY_BYTES = 1024 * 1024;
+export const PTY_MAX_POLL_BYTES = 64 * 1024;
+export const PTY_SCROLLBACK = 1000;
+/** A snapshot must fit one tool result (2 MiB, the same as keeper-terminal's outbound frame cap). */
+export const PTY_RESULT_BYTES = 2 * 1024 * 1024;
+export const PTY_SESSION_LIMIT = 8;
+export const PTY_INPUT_BYTES = 64 * 1024;
+/** Longest activity label (the foreground process basename; never its arguments). */
+export const PTY_LABEL_CHARS = 64;
+export const PTY_METHODS = ['pty.create', 'pty.attach', 'pty.poll', 'pty.write', 'pty.resize', 'pty.takeover', 'pty.detach', 'pty.close', 'pty.list'];
+/** Typed error codes of `pty.*` (the message keeps today's `terminal.*` wording). */
+export const PtyErrorCode = {
+    unavailable: 'pty_unavailable',
+    badRequest: 'bad_request',
+    notFound: 'pty_not_found',
+    notController: 'pty_not_controller',
+    limit: 'pty_limit',
+    exited: 'pty_exited',
+    snapshotTooLarge: 'pty_snapshot_too_large',
+};
+// ---- exec (spec §4.2): non-interactive commands with durable per-exec output logs ----------------------------------
+/** `keeper.hello` capability: `exec.*` is served. */
+export const EXEC_CAPABILITY = 'exec';
+export const EXEC_METHODS = ['exec.start', 'exec.list', 'exec.status', 'exec.read', 'exec.subscribe', 'exec.kill', 'exec.commit', 'exec.checkpoint'];
+/** The kit stream (`keeper.subscribe`) carrying one exec's records. */
+export const execStream = (execId) => `exec/${execId}`;
+/** Spec §14. The daemon passes the per-exec values with `exec.start`; these are the keeper's own bounds and defaults. */
+export const EXEC_RUNNING_LIMIT = 128;
+export const EXEC_TOTAL_BYTES = 512 * 1024 * 1024;
+export const EXEC_TERMINAL_TTL_MS = 24 * 60 * 60 * 1000;
+/** Largest payload of one out/err record (a pipe read is at most 64 KiB; anything bigger is split). */
+export const EXEC_CHUNK_BYTES = 64 * 1024;
+/** Exec streams use a relaxed fsync policy (spawn/exit/commit/checkpoint still fsync at once); lost output on a power cut reads as keeper_lost. */
+export const EXEC_FSYNC_INTERVAL_MS = 1000;
+export const EXEC_FSYNC_BYTES = 4 * 1024 * 1024;
+/** The kit's segment size (spec §14). Sealing a segment fsyncs it, so smaller segments would slow a flood down measurably. */
+export const EXEC_SEGMENT_BYTES = 8 * 1024 * 1024;
+export const EXEC_LABEL_CHARS = 256;
+export const EXEC_SIGNALS = ['SIGTERM', 'SIGKILL', 'SIGINT', 'SIGHUP', 'SIGQUIT', 'SIGUSR1', 'SIGUSR2'];
+export const ExecErrorCode = {
+    badRequest: 'bad_request',
+    notFound: 'exec_not_found',
+    limit: 'exec_limit',
+    /** The exec directory belongs to another live keeper-terminal generation; this one never touches it. */
+    foreign: 'exec_foreign',
+    notExited: 'exec_not_exited',
+};

package/dist/workstation/keepers/terminal/pty.js

@@ -0,0 +1,330 @@
+// Persistent PTY sessions (tmux-like): each session keeps a headless xterm screen and a bounded ring of rendered output;
+// clients `attach` (snapshot) and `poll(after)` (delta, or a snapshot reset when they fell behind). Control is explicit
+// (controller / takeover / detach), at most 8 sessions, exited sessions stay listed until closed. Spec §4.1.
+//
+// This is the one implementation: keeper-terminal serves it as `pty.*` (main.ts); the daemon's `terminal.*` reaches it through
+// tools/terminalRouter.ts.
+//
+// Keeper-side module: node builtins, kit siblings and the bundled @xterm packages only (the import guard enforces it).
+// Sessions are independent: there is no queue across sessions (a slow operation on one never delays another).
+import { execFile } from 'node:child_process';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import xtermHeadless from '@xterm/headless';
+import xtermSerialize from '@xterm/addon-serialize';
+import { KeeperMethodError } from '../kit/protocol.js';
+import { PTY_HISTORY_BYTES, PTY_INPUT_BYTES, PTY_LABEL_CHARS, PTY_MAX_POLL_BYTES, PTY_RESULT_BYTES, PTY_SCROLLBACK, PTY_SESSION_LIMIT, PTY_UNAVAILABLE_ERROR, PtyErrorCode, } from './protocol.js';
+// CommonJS packages: their default export is `module.exports` both under Node and once esbuild bundles them.
+const { Terminal } = xtermHeadless;
+const { SerializeAddon } = xtermSerialize;
+const darwinShellName = (pid) => new Promise((resolve) => {
+    execFile('ps', ['-o', 'ucomm=', '-p', String(pid)], { timeout: 1000 }, (error, stdout) => resolve(error ? null : stdout.trim() || null));
+});
+const defaultShellProcessName = (pid) => (process.platform === 'darwin' ? darwinShellName(pid) : Promise.resolve(null));
+// Parameter checks (today's tools/validation.ts rules; kept here so the keeper bundle depends on no daemon module).
+const bad = (message) => { throw new KeeperMethodError(PtyErrorCode.badRequest, message); };
+function keys(params, allowed) {
+    if (Object.keys(params).some((key) => !allowed.includes(key)))
+        bad('Unexpected tool parameter');
+}
+function identifier(params, name) {
+    const value = params[name];
+    if (typeof value !== 'string' || !value.length || value.includes('\0') || value.length > 128 || !/^[A-Za-z0-9_.:-]+$/.test(value))
+        bad(`Invalid ${name}`);
+    return value;
+}
+function integer(params, name, min, max, fallback) {
+    const value = params[name] === undefined ? fallback : params[name];
+    if (!Number.isSafeInteger(value) || value < min || value > max)
+        bad(`Invalid ${name}`);
+    return value;
+}
+/** The basename of a foreground process name, without the leading '-' a login shell may carry. */
+export const processBasename = (name) => path.basename(name.trim()).replace(/^-/, '');
+export const CREATE_KEYS = ['id', 'clientId', 'name', 'cwd', 'cols', 'rows'];
+export const PTY_OPERATIONS = new Set(['attach', 'poll', 'write', 'resize', 'takeover', 'detach', 'close']);
+export class PtySessions {
+    options;
+    sessions = new Map();
+    ptyModule;
+    error;
+    now;
+    constructor(options = {}) {
+        this.options = options;
+        this.now = options.now ?? Date.now;
+        try {
+            this.ptyModule = (options.loadPty ?? (() => createRequire(import.meta.url)('node-pty')))();
+        }
+        catch {
+            this.error = PTY_UNAVAILABLE_ERROR;
+        }
+    }
+    get available() { return !!this.ptyModule; }
+    descriptor(s) {
+        return { id: s.id, name: s.name, cwd: s.cwd, cols: s.cols, rows: s.rows, exited: s.exited, exitCode: s.exitCode, controllerId: s.controllerId };
+    }
+    control(s, clientId) {
+        if (s.controllerId !== clientId)
+            throw new KeeperMethodError(PtyErrorCode.notController, 'Terminal is controlled by another client; take control explicitly');
+    }
+    resize(s, p) {
+        const cols = integer(p, 'cols', 20, 300, s.cols);
+        const rows = integer(p, 'rows', 5, 100, s.rows);
+        if (cols !== s.cols || rows !== s.rows) {
+            if (!s.exited)
+                s.pty.resize(cols, rows);
+            s.terminal.resize(cols, rows);
+            s.cols = cols;
+            s.rows = rows;
+        }
+    }
+    snapshot(s) {
+        // Scroll position belongs to the viewer, never the keeper. Serialization includes normal and
+        // alternate buffers, SGR attributes, cursor and modes; it starts from a clean emulator.
+        for (let scrollback = PTY_SCROLLBACK;; scrollback = Math.floor(scrollback / 2)) {
+            const snapshot = '\x1bc' + s.serializer.serialize({ scrollback });
+            if (Buffer.byteLength(JSON.stringify({ snapshot })) < PTY_RESULT_BYTES - 8192)
+                return snapshot;
+            if (!scrollback)
+                throw new KeeperMethodError(PtyErrorCode.snapshotTooLarge, 'Terminal screen exceeds snapshot limit; resize to a smaller viewport');
+        }
+    }
+    output(s, data) {
+        if (!data || s.closed)
+            return;
+        const bytes = Buffer.byteLength(data);
+        s.pendingBytes += bytes;
+        if (s.pendingBytes > 256 * 1024)
+            s.pty.pause();
+        // Written to xterm at once, not chained behind the previous write's callback: xterm parses writes and runs their
+        // callbacks strictly in order, so sequence numbers stay per event and `rendered` (the newest write's promise) still
+        // means "everything received so far is rendered". Chaining cost one timer tick per event, and node-pty on macOS
+        // delivers line-by-line output as one ~10-byte event per line (~9 KB/s rendered, a paused shell behind it).
+        s.rendered = new Promise((resolve) => {
+            s.terminal.write(data, () => {
+                // Each PTY event is a sequence boundary. A single large event can exceed the history budget;
+                // dropping it is safe because poll then returns a fully rendered snapshot.
+                s.seq += 1;
+                s.ring.push({ seq: s.seq, data, bytes });
+                s.ringBytes += bytes;
+                const limit = this.options.historyBytes ?? PTY_HISTORY_BYTES;
+                while (s.ringBytes > limit && s.ring.length)
+                    s.ringBytes -= s.ring.shift().bytes;
+                s.pendingBytes -= bytes;
+                if (s.pendingBytes < 64 * 1024 && !s.exited)
+                    s.pty.resume();
+                resolve();
+            });
+        });
+    }
+    unavailable() { throw new KeeperMethodError(PtyErrorCode.unavailable, this.error ?? 'Terminal unavailable'); }
+    list(p) {
+        keys(p, []);
+        return { sessions: [...this.sessions.values()].map((s) => this.descriptor(s)) };
+    }
+    /**
+     * Creates session `id`, or returns the existing one (idempotent). `allowedKeys` is the caller's parameter set; `launch`
+     * supplies cwd, shell and env and runs only when a session is really started (after the duplicate and limit checks,
+     * which are re-checked afterwards because `launch` may be asynchronous).
+     */
+    async create(p, allowedKeys, launch) {
+        if (!this.ptyModule)
+            this.unavailable();
+        const id = identifier(p, 'id');
+        const clientId = identifier(p, 'clientId');
+        keys(p, allowedKeys);
+        const cols = integer(p, 'cols', 20, 300, 100);
+        const rows = integer(p, 'rows', 5, 100, 30);
+        if (p.name !== undefined && (typeof p.name !== 'string' || !p.name.length || p.name.length > 128 || /[\x00-\x1f]/.test(p.name)))
+            bad('Invalid terminal name');
+        const existing = () => { const old = this.sessions.get(id); return old && this.descriptor(old); };
+        const limit = () => { if (this.sessions.size >= PTY_SESSION_LIMIT)
+            throw new KeeperMethodError(PtyErrorCode.limit, 'Terminal session limit exceeded'); };
+        let old = existing();
+        if (old)
+            return old;
+        limit();
+        const { cwd, shell, env } = await launch();
+        old = existing();
+        if (old)
+            return old; // a concurrent create of the same id won
+        limit();
+        const terminal = new Terminal({ cols, rows, scrollback: PTY_SCROLLBACK, allowProposedApi: true });
+        const serializer = new SerializeAddon();
+        // Headless and browser xterm share the addon contract, but their declaration packages differ.
+        terminal.loadAddon(serializer);
+        let pty;
+        try {
+            pty = this.ptyModule.spawn(shell, ['-l'], { name: 'xterm-256color', cwd, cols, rows, env: { ...env, TERM: 'xterm-256color', COLORTERM: 'truecolor' } });
+        }
+        catch (error) {
+            terminal.dispose();
+            throw error;
+        }
+        const created = this.now();
+        const shellName = processBasename(shell);
+        const session = {
+            id, name: p.name ?? 'Terminal', cwd, cols, rows, exited: false, exitCode: null, controllerId: clientId,
+            pty, closed: false, terminal, serializer, seq: 0, ring: [], ringBytes: 0, pendingBytes: 0, rendered: Promise.resolve(),
+            shellName, exitedAt: 0, shellNames: new Set([shellName]), observed: { label: shellName, state: 'idle', since: created },
+        };
+        pty.onData((data) => this.output(session, data));
+        pty.onExit((event) => { session.exited = true; session.exitCode = event.exitCode; session.exitedAt = this.now(); });
+        // Answering terminal queries (DA/DSR, etc.) is keeper-owned and does not require a web client.
+        terminal.onData((data) => { if (!session.exited)
+            pty.write(data); });
+        this.sessions.set(id, session);
+        const learn = setTimeout(() => { void this.learnShellName(session); }, this.options.shellNameDelayMs ?? 250);
+        learn.unref();
+        return this.descriptor(session);
+    }
+    /** attach / poll / write / resize / takeover / detach / close on an existing session. */
+    async operate(op, p) {
+        if (!this.ptyModule)
+            this.unavailable();
+        const id = identifier(p, 'id');
+        const clientId = identifier(p, 'clientId');
+        const s = this.sessions.get(id);
+        if (!s)
+            throw new KeeperMethodError(PtyErrorCode.notFound, 'Terminal session not found; keeper restart loses live PTYs');
+        switch (op) {
+            case 'attach': {
+                keys(p, ['id', 'clientId', 'cols', 'rows']);
+                // Validate dimensions even for a viewer, but only the controller's dimensions affect PTY.
+                integer(p, 'cols', 20, 300, s.cols);
+                integer(p, 'rows', 5, 100, s.rows);
+                await s.rendered;
+                if (s.controllerId === null)
+                    s.controllerId = clientId;
+                if (s.controllerId === clientId)
+                    this.resize(s, p);
+                return { session: this.descriptor(s), seq: s.seq, snapshot: this.snapshot(s), control: s.controllerId === clientId };
+            }
+            case 'poll': {
+                keys(p, ['id', 'clientId', 'after']);
+                const after = integer(p, 'after', 0, Number.MAX_SAFE_INTEGER);
+                await s.rendered;
+                const common = { exited: s.exited, exitCode: s.exitCode, control: s.controllerId === clientId };
+                if (after > s.seq || after < (s.ring[0]?.seq ?? s.seq + 1) - 1)
+                    return { ...common, seq: s.seq, data: '', reset: true, snapshot: this.snapshot(s) };
+                let data = '';
+                let bytes = 0;
+                let seq = after;
+                for (const output of s.ring) {
+                    if (output.seq <= after)
+                        continue;
+                    if (bytes + output.bytes > PTY_MAX_POLL_BYTES) {
+                        if (!bytes)
+                            return { ...common, seq: s.seq, data: '', reset: true, snapshot: this.snapshot(s) };
+                        break;
+                    }
+                    data += output.data;
+                    bytes += output.bytes;
+                    seq = output.seq;
+                }
+                return { ...common, seq, data, reset: false };
+            }
+            case 'takeover':
+                keys(p, ['id', 'clientId']);
+                s.controllerId = clientId;
+                return { ok: true };
+            case 'detach':
+                keys(p, ['id', 'clientId']);
+                if (s.controllerId === clientId)
+                    s.controllerId = null;
+                return { ok: true };
+            case 'write':
+                keys(p, ['id', 'clientId', 'data']);
+                this.control(s, clientId);
+                if (s.exited)
+                    throw new KeeperMethodError(PtyErrorCode.exited, 'Terminal has exited');
+                if (typeof p.data !== 'string' || Buffer.byteLength(p.data) > PTY_INPUT_BYTES)
+                    bad('Invalid terminal input');
+                s.pty.write(p.data);
+                return { ok: true };
+            case 'resize':
+                keys(p, ['id', 'clientId', 'cols', 'rows']);
+                this.control(s, clientId);
+                integer(p, 'cols', 20, 300);
+                integer(p, 'rows', 5, 100);
+                await s.rendered;
+                this.resize(s, p);
+                return { ok: true };
+            case 'close':
+                keys(p, ['id', 'clientId']);
+                this.control(s, clientId);
+                this.sessions.delete(id);
+                s.closed = true;
+                if (!s.exited)
+                    s.pty.kill();
+                await s.rendered;
+                s.terminal.dispose();
+                return { ok: true };
+            default: return bad('Unsupported terminal tool');
+        }
+    }
+    /** The tty's foreground process basename, '' when it cannot be read (node-pty falls back to the shell path itself). */
+    foreground(s) {
+        try {
+            return processBasename(String(s.pty.process ?? ''));
+        }
+        catch {
+            return '';
+        }
+    }
+    /**
+     * Learns once per session, in the background shortly after spawn, what the tty calls the shell itself (macOS `p_comm`).
+     * Until it resolves (or when it fails) the configured basename is the only shell name: activity never waits on a subprocess.
+     */
+    async learnShellName(s) {
+        if (s.closed || s.exited)
+            return;
+        try {
+            const name = await (this.options.shellProcessName ?? defaultShellProcessName)(s.pty.pid);
+            if (name)
+                s.shellNames.add(processBasename(name));
+        }
+        catch { /* keep the configured basename */ }
+    }
+    /**
+     * A live sample for `keeper.activity` (spec §3.5/§4.1): `ptyOpen` live sessions, `ptyActive` live sessions whose foreground
+     * process is not their shell, `ptyExited` exited sessions still listed. One item per session, labelled with the foreground
+     * process basename (never its arguments), `sinceEpochMs` = when this label/state was first observed.
+     */
+    activity() {
+        const now = this.now();
+        let open = 0;
+        let active = 0;
+        let exited = 0;
+        const items = [];
+        for (const s of this.sessions.values()) {
+            if (s.exited) {
+                exited += 1;
+                items.push({ type: 'pty', id: s.id, label: s.shellName.slice(0, PTY_LABEL_CHARS), state: 'exited', sinceEpochMs: s.exitedAt });
+                continue;
+            }
+            open += 1;
+            const fg = this.foreground(s);
+            const busy = fg !== '' && !s.shellNames.has(fg);
+            const label = (busy ? fg : s.shellName).slice(0, PTY_LABEL_CHARS);
+            const state = busy ? 'active' : 'idle';
+            if (s.observed.label !== label || s.observed.state !== state)
+                s.observed = { label, state, since: now };
+            if (busy)
+                active += 1;
+            items.push({ type: 'pty', id: s.id, label, state, sinceEpochMs: s.observed.since });
+        }
+        return { metrics: { ptyOpen: open, ptyActive: active, ptyExited: exited }, items };
+    }
+    /** Kills every session (the keeper is stopping). */
+    async dispose() {
+        for (const session of this.sessions.values()) {
+            session.closed = true;
+            if (!session.exited)
+                session.pty.kill();
+            await session.rendered;
+            session.terminal.dispose();
+        }
+        this.sessions.clear();
+    }
+}