@platless/axom-cli 0.5.9 → 0.6.52

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

@@ -44,7 +44,7 @@ const MAX_READ_RECORDS = 1024;
 const MAX_READ_BYTES = 1536 * 1024;
 const MAX_GRACE_MS = 10 * 60 * 1000;
 const EXEC_ID = /^[A-Za-z0-9_.:-]{1,128}$/;
-const START_KEYS = ['execId', 'argv', 'cwd', 'env', 'deadlineEpochMs', 'killGraceMs', 'retainHeadBytes', 'maxUncommittedBytes', 'onKeeperLoss', 'label', 'jobId'];
+const START_KEYS = ['execId', 'argv', 'cwd', 'env', 'deadlineEpochMs', 'killGraceMs', 'retainHeadBytes', 'maxUncommittedBytes', 'onKeeperLoss', 'label', 'jobId', 'registrationId'];
 /**
  * Whether a kept record stays in keep.jsonl once the daemon committed through `committed`. The head reserve (kept `out`/`err`
  * records: the first `retainHeadBytes` of each stream) and the spawn record survive every non-final commit: the daemon shapes the
@@ -305,11 +305,14 @@ export class ExecHost {
             bad('Invalid jobId');
         if (this.runningCount() >= (this.options.runningLimit ?? EXEC_RUNNING_LIMIT))
             throw new KeeperMethodError(ExecErrorCode.limit, 'Too many running commands in keeper-terminal');
+        const registrationId = params.registrationId;
+        if (registrationId !== undefined && (typeof registrationId !== 'string' || !registrationId || registrationId.length > 128 || /[\x00-\x1f]/.test(registrationId)))
+            bad('Invalid registrationId');
         const meta = {
             v: 1, execId, label: params.label.slice(0, EXEC_LABEL_CHARS), ...(jobId ? { jobId: jobId } : {}),
             argv: argv, cwd, envKeys: Object.keys(env).sort(),
             deadlineEpochMs: typeof deadline === 'number' ? deadline : null, killGraceMs, retainHeadBytes, maxUncommittedBytes, onKeeperLoss: onKeeperLoss,
-            createdAtMs: this.now(), owner: this.options.owner, spawn: null, exit: null, logReclaimed: null,
+            createdAtMs: this.now(), owner: this.options.owner, ...(typeof registrationId === 'string' ? { registrationId } : {}), spawn: null, exit: null, logReclaimed: null,
         };
         // Synchronously up to the spawn: a concurrent start of the same id finds the entry and waits for it.
         let entry;
@@ -811,7 +814,7 @@ export class ExecHost {
     describe(entry) {
         const { meta } = entry;
         return {
-            execId: meta.execId, label: meta.label, ...(meta.jobId ? { jobId: meta.jobId } : {}), state: this.stateOf(entry),
+            execId: meta.execId, label: meta.label, ...(meta.registrationId ? { registrationId: meta.registrationId } : {}), ...(meta.jobId ? { jobId: meta.jobId } : {}), state: this.stateOf(entry),
             pid: meta.spawn?.pid ?? null, pgid: meta.spawn?.pgid ?? null, startTime: meta.spawn?.startTime ?? null,
             createdAtMs: meta.createdAtMs, deadlineEpochMs: meta.deadlineEpochMs, onKeeperLoss: meta.onKeeperLoss, exit: meta.exit,
             head: this.headOf(entry), committed: entry.committed, dropped: entry.dropped,

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

@@ -0,0 +1,73 @@
+import { KeeperMethodError } from '../kit/protocol.js';
+import { TERMINAL_GRID_LIMITS as limits } from './gridProtocol.js';
+/** Complete immutable snapshots, with deltas computed against any retained base. */
+export class TerminalFrames {
+    cache = [];
+    bytes = 0;
+    /** A failed/oversized capture leaves both the revision and recovery cache untouched. */
+    publish(snapshot, session, geometry) {
+        validate(snapshot, session);
+        const previous = this.cache.at(-1)?.frame;
+        const sameSession = previous?.incarnation === session.incarnation && previous.id === session.id;
+        const nextGeometry = geometry ?? (sameSession ? previous.geometry + Number(previous.cols !== snapshot.cols || previous.rows !== snapshot.rows) : 1);
+        if (!Number.isSafeInteger(nextGeometry) || nextGeometry < 1 || (sameSession && nextGeometry < previous.geometry))
+            throw new Error('Invalid terminal geometry');
+        const next = structuredClone({
+            ...snapshot, schema: 1, id: session.id, incarnation: session.incarnation,
+            revision: sameSession ? previous.revision + 1 : 1, baseRevision: 0,
+            geometry: nextGeometry, full: true, session,
+        });
+        if (sameSession && equalContent(previous, next))
+            return;
+        const bytes = resultBytes(next);
+        if (!sameSession) {
+            this.cache = [];
+            this.bytes = 0;
+        }
+        this.cache.push({ frame: next, bytes });
+        this.bytes += bytes;
+        while (this.cache.length > limits.maxCachedFrames || this.bytes > limits.maxFrameCacheBytes)
+            this.bytes -= this.cache.shift().bytes;
+    }
+    poll(after) {
+        const current = this.cache.at(-1)?.frame;
+        if (!current)
+            throw new Error('Terminal frame has not been captured');
+        if (after === current.revision)
+            return structuredClone({ ...current, full: false, baseRevision: after, styles: [], changedRows: [] });
+        const base = after === 0 ? undefined : this.cache.find(entry => entry.frame.revision === after)?.frame;
+        if (!base || base.geometry !== current.geometry || base.buffer !== current.buffer || base.incarnation !== current.incarnation)
+            return structuredClone(current);
+        const changedRows = current.changedRows.filter((row, index) => semanticRow(row, current) !== semanticRow(base.changedRows[index], base));
+        const delta = { ...current, full: false, baseRevision: after, changedRows };
+        resultBytes(delta);
+        return structuredClone(delta);
+    }
+    cacheStats() { return { frames: this.cache.length, bytes: this.bytes }; }
+}
+function semanticRow(row, frame) {
+    return JSON.stringify([row.wrapped ?? false, row.runs.flatMap(run => run.cells.map(cell => [cell.text, cell.width, frame.styles[run.style]]))]);
+}
+function equalContent(a, b) {
+    const header = (frame) => JSON.stringify([
+        frame.geometry, frame.cols, frame.rows, frame.buffer, frame.viewport, frame.cursor, frame.modes, frame.session,
+    ]);
+    return header(a) === header(b) && a.changedRows.every((row, index) => semanticRow(row, a) === semanticRow(b.changedRows[index], b));
+}
+function resultBytes(frame) {
+    const bytes = Buffer.byteLength(JSON.stringify(frame));
+    // Leave room for the keeper response envelope and the tool response wrapper.
+    if (bytes > limits.maxResultBytes - 1024)
+        throw new KeeperMethodError('pty_snapshot_too_large', 'Terminal frame exceeds result limit; resize to a smaller viewport');
+    return bytes;
+}
+function validate(snapshot, session) {
+    if (snapshot.cols < limits.minCols || snapshot.cols > limits.maxCols || snapshot.rows < limits.minRows || snapshot.rows > limits.maxRows
+        || snapshot.cols !== session.cols || snapshot.rows !== session.rows || snapshot.changedRows.length !== snapshot.rows)
+        throw new Error('Terminal snapshot must contain a complete matching grid');
+    for (const [index, row] of snapshot.changedRows.entries()) {
+        if (row.index !== index || row.runs.reduce((count, run) => count + run.cells.length, 0) !== snapshot.cols
+            || row.runs.some(run => !snapshot.styles[run.style] || run.cells.some(cell => typeof cell.text !== 'string' || ![0, 1, 2].includes(cell.width))))
+            throw new Error('Terminal snapshot must contain complete rows and styles');
+    }
+}

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

@@ -2,11 +2,8 @@
 // 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).
+// Durable exec work uses the serving picker and retains owner routing across generations.
+// Native terminal tools bypass this selection and always use `primary` (tools/terminalRouter.ts).
 import path from 'node:path';
 import { readKeeperManifest } from '../kit/bundle.js';
 import { TerminalKeeperClient } from './client.js';
@@ -93,7 +90,7 @@ export class TerminalGenerations {
         }
         return older !== undefined && older !== current ? { gen: older, client: await this.client(older) } : { gen: current, client: this.primary };
     }
-    /** `ExecKeeperGenerations.serving` / the router's create target. */
+    /** Durable exec creation target. Native terminal creation uses primary directly. */
     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() {
@@ -109,9 +106,9 @@ export class TerminalGenerations {
         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. */
+    /** Native terminal status belongs only to the current build. Starts nothing. */
     async terminalStatus(fallback) {
-        return (await this.serving()).terminalStatus(fallback);
+        return this.primary.terminalStatus(fallback);
     }
     /** Drops the connection to `gen` (it was stopped). */
     forget(gen) {

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

@@ -0,0 +1,16 @@
+/** Native terminal wire contract. No runtime/platform dependencies. */
+export const TERMINAL_GRID_SCHEMA = 1;
+export const TERMINAL_KEEPER_PROTOCOL = 2;
+export const TERMINAL_GRID_CAPABILITY = 'pty-grid-v1';
+export const TERMINAL_GRID_LIMITS = {
+    minCols: 20, maxCols: 300, minRows: 5, maxRows: 100,
+    maxSessions: 8, maxAttachments: 16, leaseMs: 15_000, scrollbackLines: 10_000,
+    maxInputBytes: 64 * 1024, maxRequestBytes: 128 * 1024, maxResultBytes: 2 * 1024 * 1024,
+    maxCachedFrames: 8, maxFrameCacheBytes: 8 * 1024 * 1024,
+};
+export const TERMINAL_MODIFIERS = { shift: 1, alt: 2, ctrl: 4, meta: 8 };
+export const TERMINAL_STYLE_FLAGS = {
+    bold: 1, dim: 2, italic: 4, underline: 8, blink: 16, inverse: 32, invisible: 64, strike: 128,
+};
+export const TERMINAL_DEFAULT_COLOR = -1;
+export const TERMINAL_RGB_COLOR_BASE = 0x1000000;

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

@@ -0,0 +1,146 @@
+import { KeeperMethodError } from '../kit/protocol.js';
+import { TERMINAL_GRID_LIMITS } from './gridProtocol.js';
+const esc = '\x1b';
+const modifiers = (mask) => 1 + (mask & 1) + (mask & 2) + (mask & 4) + (mask & 8);
+const arrows = { 79: 'C', 80: 'D', 81: 'B', 82: 'A', 74: 'H', 77: 'F' };
+const tilde = { 73: 2, 76: 3, 75: 5, 78: 6, 62: 15, 63: 17, 64: 18, 65: 19, 66: 20, 67: 21, 68: 23, 69: 24 };
+const keypad = {
+    84: ['/', 'o'], 85: ['*', 'j'], 86: ['-', 'm'], 87: ['+', 'k'], 88: ['\r', 'M'],
+    89: ['1', 'q'], 90: ['2', 'r'], 91: ['3', 's'], 92: ['4', 't'], 93: ['5', 'u'], 94: ['6', 'v'],
+    95: ['7', 'w'], 96: ['8', 'x'], 97: ['9', 'y'], 98: ['0', 'p'], 99: ['.', 'n'], 103: ['=', 'X'],
+};
+/** One attachment's only held input is its mouse buttons; modifiers are explicit per event. */
+export class TerminalInputEncoder {
+    buttons = new Set();
+    release() { this.buttons.clear(); }
+    encode(event, screen) {
+        switch (event.kind) {
+            case 'release':
+                this.release();
+                return '';
+            case 'text': return event.text;
+            case 'paste': return screen.modes.bracketedPaste ? `${esc}[200~${event.text}${esc}[201~` : event.text;
+            case 'key': return event.down ? encodeKey(event.usage, event.modifiers, screen.modes) : '';
+            case 'button': {
+                if (event.down)
+                    this.buttons.add(event.button);
+                else
+                    this.buttons.delete(event.button);
+                if (screen.modes.mouseTracking === 'none' || (!event.down && screen.modes.mouseTracking === 'x10'))
+                    return '';
+                return mouse(event.button, event.x, event.y, event.modifiers, screen.modes, !event.down);
+            }
+            case 'pointer': {
+                const tracking = screen.modes.mouseTracking;
+                if (tracking !== 'any' && !(tracking === 'drag' && this.buttons.size))
+                    return '';
+                return mouse(32 + (this.buttons.values().next().value ?? 3), event.x, event.y, event.modifiers, screen.modes);
+            }
+        }
+    }
+}
+export function createTerminalInput(screen) {
+    const clients = new Map();
+    const encoder = (id) => { let value = clients.get(id); if (!value) {
+        value = new TerminalInputEncoder();
+        clients.set(id, value);
+    } return value; };
+    return {
+        input(event, clientId, context) { return encoder(clientId).encode(event, context); },
+        scroll(gesture, _clientId, context) {
+            if (!gesture.lines)
+                return '';
+            const state = screen.state();
+            if (context.modes.mouseTracking === 'x10')
+                return '';
+            if (context.modes.mouseTracking !== 'none')
+                return repeat(mouse(gesture.lines < 0 ? 64 : 65, gesture.x, gesture.y, gesture.modifiers, context.modes), Math.abs(gesture.lines));
+            if (state.buffer === 'normal')
+                return undefined;
+            if (!context.modes.alternateScroll)
+                return '';
+            return repeat(encodeKey(gesture.lines < 0 ? 82 : 81, gesture.modifiers, context.modes), Math.abs(gesture.lines));
+        },
+        release(clientId) { clients.get(clientId)?.release(); clients.delete(clientId); },
+        dispose() { clients.clear(); },
+    };
+}
+function repeat(bytes, count) {
+    if (!bytes)
+        return '';
+    if (count > Math.floor(TERMINAL_GRID_LIMITS.maxInputBytes / Buffer.byteLength(bytes)))
+        throw new KeeperMethodError('bad_request', 'Terminal input exceeds limit');
+    if (typeof bytes === 'string')
+        return bytes.repeat(count);
+    return Buffer.concat(Array.from({ length: count }, () => bytes));
+}
+function mouse(button, x, y, mask, modes, release = false) {
+    // The wire carries cells, so pixel encoding cannot be represented faithfully.
+    if (modes.mouseEncoding === 'sgr-pixels')
+        return '';
+    const mods = modes.mouseTracking === 'x10' ? 0 : (mask & 1 ? 4 : 0) + (mask & 2 ? 8 : 0) + (mask & 4 ? 16 : 0);
+    if (modes.mouseEncoding === 'sgr')
+        return `${esc}[<${button + mods};${x + 1};${y + 1}${release ? 'm' : 'M'}`;
+    const code = (release ? 3 : button) + mods + 32;
+    if (modes.mouseEncoding === 'urxvt')
+        return `${esc}[${code};${x + 1};${y + 1}M`;
+    if (modes.mouseEncoding === 'default' && (x > 222 || y > 222))
+        return '';
+    if (modes.mouseEncoding === 'default')
+        return Buffer.from([27, 91, 77, code, x + 33, y + 33]);
+    return `${esc}[M${String.fromCharCode(code, x + 33, y + 33)}`;
+}
+function encodeKey(usage, mask, modes) {
+    const mod = modifiers(mask);
+    if (arrows[usage])
+        return mod > 1 ? `${esc}[1;${mod}${arrows[usage]}` : `${esc}${modes.applicationCursor ? 'O' : '['}${arrows[usage]}`;
+    if (tilde[usage])
+        return `${esc}[${tilde[usage]}${mod > 1 ? `;${mod}` : ''}~`;
+    if (usage >= 58 && usage <= 61)
+        return mod > 1 ? `${esc}[1;${mod}${String.fromCharCode(80 + usage - 58)}` : `${esc}O${String.fromCharCode(80 + usage - 58)}`;
+    if (keypad[usage]) {
+        if (mask & 8 && usage !== 88)
+            return '';
+        return modes.applicationKeypad ? mod > 1 ? `${esc}[1;${mod}${keypad[usage][1]}` : `${esc}O${keypad[usage][1]}` : prefixed(keypad[usage][0], mask);
+    }
+    if (usage === 40)
+        return prefixed('\r', mask);
+    if (usage === 41)
+        return esc;
+    if (usage === 42)
+        return prefixed(mask & 4 ? '\b' : '\x7f', mask);
+    if (usage === 43)
+        return mask & 1 ? `${esc}[Z` : prefixed('\t', mask);
+    if (mask & 8)
+        return ''; // Native clients handle local Meta shortcuts.
+    let text = '';
+    if (usage >= 4 && usage <= 29)
+        text = String.fromCharCode((mask & 1 ? 65 : 97) + usage - 4);
+    else if (usage >= 30 && usage <= 39)
+        text = (mask & 1 ? '!@#$%^&*()' : '1234567890')[usage - 30];
+    else {
+        const punctuation = { 44: [' ', ' '], 45: ['-', '_'], 46: ['=', '+'], 47: ['[', '{'], 48: [']', '}'], 49: ['\\', '|'], 50: ['#', '~'], 51: [';', ':'], 52: ["'", '"'], 53: ['`', '~'], 54: [',', '<'], 55: ['.', '>'], 56: ['/', '?'] };
+        text = punctuation[usage]?.[mask & 1 ? 1 : 0] ?? '';
+    }
+    if (mask & 4) {
+        const upper = text.toUpperCase();
+        if (upper >= '@' && upper <= '_')
+            text = String.fromCharCode(upper.charCodeAt(0) - 64);
+        else if (text === ' ' || text === '2' || text === '`')
+            text = '\0';
+        else if (text === '3')
+            text = esc;
+        else if (text === '4')
+            text = '\x1c';
+        else if (text === '5')
+            text = '\x1d';
+        else if (text === '6')
+            text = '\x1e';
+        else if (text === '7' || text === '/')
+            text = '\x1f';
+        else if (text === '8' || text === '?')
+            text = '\x7f';
+    }
+    return prefixed(text, mask);
+}
+function prefixed(text, mask) { return text && mask & 2 ? esc + text : text; }

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

@@ -1,8 +1,9 @@
-// keeper-terminal's methods on the kit server: `pty.*` over PtySessions, `exec.*` over ExecHost, plus their activity samplers.
+// keeper-terminal's methods on the kit server: `pty.*` over NativePtySessions, `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 { createRequire } from 'node:module';
+import { NativePtySessions, NATIVE_PTY_OPERATIONS } from './sessions.js';
 import { KeeperMethodError } from '../kit/protocol.js';
 import { EXEC_CAPABILITY, ExecErrorCode, PTY_CAPABILITY, execStream } from './protocol.js';
 /**
@@ -21,18 +22,31 @@ async function launchOf(p) {
         bad('Terminal shell is not an executable file');
     return { cwd, shell, env };
 }
-export const KEEPER_CREATE_KEYS = [...CREATE_KEYS, 'shell', 'env'];
+export const KEEPER_CREATE_KEYS = ['id', 'cwd', 'shell', 'env', 'registrationId'];
 export function createTerminalKeeper(options = {}) {
-    const sessions = new PtySessions(options);
+    let available = false;
+    const sessions = new NativePtySessions({ ...options, loadPty: () => {
+            const module = (options.loadPty ?? (() => createRequire(import.meta.url)('node-pty')))();
+            available = true;
+            return module;
+        } });
     const exec = options.exec;
     return {
         sessions,
         exec,
-        capabilities: [...(sessions.available ? [PTY_CAPABILITY] : []), ...(exec ? [EXEC_CAPABILITY] : [])],
+        capabilities: [...(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.create', (params) => {
+                if (Object.keys(params).some(key => !KEEPER_CREATE_KEYS.includes(key)))
+                    bad('Unexpected tool parameter');
+                return sessions.create({ id: params.id, ...(params.cwd !== undefined ? { cwd: params.cwd } : {}), ...(params.registrationId !== undefined ? { registrationId: params.registrationId } : {}) }, () => launchOf(params));
+            }, { startsWork: true });
+            server.register('pty.list', (params) => {
+                if (Object.keys(params).length)
+                    bad('Unexpected tool parameter');
+                return sessions.list();
+            });
+            for (const op of NATIVE_PTY_OPERATIONS)
                 server.register(`pty.${op}`, (params) => sessions.operate(op, params));
             server.addActivitySampler(() => sessions.activity());
             if (!exec)

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

@@ -8,7 +8,7 @@ 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;
+export const protocolVersion = 2;
 /**
  * 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).

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

@@ -0,0 +1,138 @@
+import { execFile } from 'node:child_process';
+import { readlink } from 'node:fs/promises';
+import { hostname as localHostname } from 'node:os';
+import path from 'node:path';
+const clean = (value) => [...value.replace(/[\x00-\x1f\x7f-\x9f]/g, '').trim()].slice(0, 256).join('');
+const validCwd = (value) => value.startsWith('/') && !/[\x00-\x1f\x7f-\x9f]/.test(value);
+/** Resolved display metadata; native xterm hooks are the only OSC parser. */
+export class TerminalMetadata {
+    options;
+    cwd;
+    cwdSource = 'launch';
+    explicitTitle = '';
+    listeners;
+    now;
+    hostname;
+    lastLookup = -Infinity;
+    oscRevision = 0;
+    closed = false;
+    pending;
+    cancelLookup;
+    timer;
+    constructor(options) {
+        this.options = options;
+        this.cwd = options.cwd;
+        this.now = options.now ?? Date.now;
+        this.hostname = (options.hostname ?? localHostname()).toLowerCase();
+        this.listeners = [options.screen.onTitleChange(title => {
+                if (this.closed)
+                    return;
+                const previous = this.title;
+                this.explicitTitle = clean(title);
+                if (this.title !== previous)
+                    options.changed();
+            }), options.screen.onCwdChange(uri => this.osc7(uri))];
+    }
+    get title() { return this.explicitTitle || clean(path.posix.basename(this.cwd) || this.cwd) || 'Terminal'; }
+    read() { return { title: this.title, cwd: this.cwd, cwdSource: this.cwdSource }; }
+    /** Called once by the host factory, independently of output and attachments. */
+    start() {
+        if (this.closed || this.timer)
+            return;
+        void this.refresh();
+        this.timer = setInterval(() => { void this.refresh(); }, 2000);
+        this.timer.unref();
+    }
+    refresh() {
+        if (this.closed || this.options.live?.() === false)
+            return Promise.resolve();
+        if (this.pending)
+            return this.pending;
+        if (this.now() - this.lastLookup < 2000)
+            return Promise.resolve();
+        this.lastLookup = this.now();
+        const revision = this.oscRevision;
+        let timeout;
+        const bounded = new Promise(resolve => {
+            timeout = setTimeout(() => resolve(null), 1000);
+            this.cancelLookup = () => resolve(null);
+            // Normalize synchronous failures too; no failed lookup invalidates the last cwd.
+            try {
+                void (this.options.lookup ?? lookupProcessCwd)(this.options.pid).then(resolve, () => resolve(null));
+            }
+            catch {
+                resolve(null);
+            }
+        });
+        this.pending = bounded.then(cwd => {
+            if (!this.closed && this.options.live?.() !== false && revision === this.oscRevision && cwd && validCwd(cwd))
+                this.updateCwd(cwd, 'process');
+        }).finally(() => { clearTimeout(timeout); this.cancelLookup = undefined; this.pending = undefined; });
+        return this.pending;
+    }
+    dispose() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        clearInterval(this.timer);
+        this.timer = undefined;
+        this.cancelLookup?.();
+        for (const listener of this.listeners)
+            listener.dispose();
+    }
+    osc7(uri) {
+        if (this.closed)
+            return;
+        try {
+            if (/[\x00-\x1f\x7f-\x9f]/.test(uri))
+                return;
+            const url = new URL(uri);
+            if (url.protocol !== 'file:' || url.username || url.password || url.port || uri.includes('?') || uri.includes('#'))
+                return;
+            const host = url.hostname.toLowerCase();
+            if (host && host !== 'localhost' && host !== this.hostname)
+                return;
+            const cwd = decodeURIComponent(url.pathname);
+            if (!validCwd(cwd))
+                return;
+            this.oscRevision++;
+            this.updateCwd(cwd, 'osc7');
+        }
+        catch { /* malformed/untrusted OSC payload is data, never executable */ }
+    }
+    updateCwd(cwd, source) {
+        if (cwd === this.cwd && source === this.cwdSource)
+            return;
+        this.cwd = cwd;
+        this.cwdSource = source;
+        this.options.changed();
+    }
+}
+/** No shell interpolation: lsof receives the shell pid only as an argv element. */
+export async function lookupProcessCwd(pid, platform = process.platform) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return null;
+    if (platform === 'linux') {
+        try {
+            return await readlink(`/proc/${pid}/cwd`);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (platform !== 'darwin')
+        return null;
+    return new Promise(resolve => {
+        execFile('lsof', ['-a', '-p', String(pid), '-d', 'cwd', '-Fn'], { timeout: 1000, maxBuffer: 64 * 1024 }, (error, stdout) => {
+            resolve(error ? null : stdout.split('\n').find(line => line.startsWith('n/'))?.slice(1) ?? null);
+        });
+    });
+}
+export function createTerminalMetadata(context) {
+    // Capture initial values before installing metadata; read() must never call session().
+    const initial = context.session();
+    const metadata = new TerminalMetadata({ screen: context.screen, cwd: initial.cwd, pid: context.pty.pid,
+        changed: context.changed, live: () => !context.session().exited });
+    metadata.start();
+    return metadata;
+}

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

@@ -1,32 +1,8 @@
-// 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. */
+// Terminal transport is a direct native-grid protocol replacement. Durable exec vocabulary follows.
+export const TERMINAL_PROTOCOL_VERSION = 2;
+export const PTY_CAPABILITY = 'pty-grid-v1';
 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',
-};
+export const PTY_METHODS = ['pty.list', 'pty.create', 'pty.attach', 'pty.poll', 'pty.resize', 'pty.input', 'pty.scroll', 'pty.detach', 'pty.close'];
 // ---- exec (spec §4.2): non-interactive commands with durable per-exec output logs ----------------------------------
 /** `keeper.hello` capability: `exec.*` is served. */
 export const EXEC_CAPABILITY = 'exec';