@platless/axom-cli 0.6.36 → 0.6.52

package/dist/workstation/keepers/kit/launcher.js

@@ -1,7 +1,7 @@
 // Daemon-side: starts, probes and stops keepers. Exempt from the keeper-side import guard.
 import { spawn } from 'node:child_process';
 import { promises as fs } from 'node:fs';
-import { constants, openSync, fstatSync, readFileSync, closeSync, lstatSync } from 'node:fs';
+import { constants, openSync, fstatSync, readFileSync, closeSync, lstatSync, mkdirSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { keeperOneShot, readKeeperToken } from './client.js';
@@ -10,6 +10,7 @@ import { keeperGen } from './identity.js';
 import { encodeLaunchConfig, launchConfigOf } from './launchConfig.js';
 import { acquireStartupLock, liveManifest, manifestProcessLive, pidAlive, processCommand, readPidManifest, releaseStartupLock } from './lock.js';
 import { bundleDirFor, ensureKeeperDirectories, keeperPaths, touchSocket } from './paths.js';
+import { assertOwnedDirectory, assertRegistrationOwner, legacyOwnershipAllowed, legacySourcesOf, readOwnerFile, RegistrationOwnershipError } from '../../runtime/ownership.js';
 const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /** `keeper.ping` on a fresh connection. Null unless the answer is from this exact keeper generation. */
 export async function pingKeeper(paths, timeoutMs = 250) {
@@ -47,11 +48,70 @@ export class KeeperLauncher {
     constructor(options) {
         this.options = options;
     }
+    get ownership() { return this.options.ownership; }
+    assertOwnership(kind, gen = 'ownership') { this.pathsFor(kind, gen); }
+    allowsLegacyOwnership(kind, gen) {
+        const sources = legacySourcesOf(this.ownership);
+        return !!sources && this.options.server === sources.keeperServer && path.resolve(this.options.configDir) === path.resolve(sources.adapterCacheDirectory) && legacyOwnershipAllowed(this.ownership, this.pathsFor(kind, gen).root, kind);
+    }
+    assertSessionOwnership(label, gen) {
+        assertRegistrationOwner(label, this.ownership, this.allowsLegacyOwnership('acp', gen) ? { directory: this.pathsFor('acp', gen).root, kind: 'acp' } : undefined);
+    }
+    assertResourceOwnership(kind, gen, resource, id, create = false) {
+        if (!this.ownership)
+            return;
+        const paths = this.pathsFor(kind, gen);
+        const directory = path.join(paths.dataDir, 'registration-owners', resource);
+        const file = path.join(directory, `${encodeURIComponent(id)}.json`);
+        try {
+            assertRegistrationOwner(readOwnerFile(file), this.ownership);
+            return;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (!create && !this.allowsLegacyOwnership(kind, gen))
+            throw new RegistrationOwnershipError('Registration resource owner is unknown; state quarantined');
+        mkdirSync(directory, { recursive: true, mode: 0o700 });
+        try {
+            writeFileSync(file, JSON.stringify({ schemaVersion: 1, registrationId: this.ownership.registrationId }), { mode: 0o600, flag: 'wx' });
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+        }
+        assertRegistrationOwner(readOwnerFile(file), this.ownership);
+    }
+    async assertKeeperResources(kind, gen, timeoutMs = 1000) {
+        if (!this.ownership)
+            return;
+        const paths = this.pathsFor(kind, gen);
+        const token = await readKeeperToken(paths.tokenFile);
+        if (kind === 'acp') {
+            const listed = await keeperOneShot(paths.socket, 'acp.list', {}, timeoutMs, { kind, token });
+            if (!Array.isArray(listed.sessions))
+                throw new RegistrationOwnershipError('Registration session ownership needs verification');
+            for (const session of listed.sessions)
+                this.assertSessionOwnership(session.label, gen);
+        }
+        else {
+            const ptys = await keeperOneShot(paths.socket, 'pty.list', {}, timeoutMs, { kind, token });
+            const execs = await keeperOneShot(paths.socket, 'exec.list', {}, timeoutMs, { kind, token });
+            if (!Array.isArray(ptys.sessions) || !Array.isArray(execs.execs))
+                throw new RegistrationOwnershipError('Registration shell ownership needs verification');
+            for (const session of ptys.sessions)
+                this.assertResourceOwnership(kind, gen, 'pty', session.id);
+            for (const exec of execs.execs)
+                this.assertResourceOwnership(kind, gen, 'exec', exec.execId);
+        }
+    }
     get distDir() { return this.options.distDir ?? defaultDistDir(); }
     probe(paths, timeoutMs) { return this.options.probe ? this.options.probe(paths) : pingKeeper(paths, timeoutMs); }
     /** Paths of generation `gen` of `kind` (no build needed). */
     pathsFor(kind, gen) {
-        const scoped = keeperPaths(this.options, kind, gen);
+        const scoped = keeperPaths(this.options, kind, gen, { fallbackRoot: this.options.fallbackRoot });
+        assertOwnedDirectory(scoped.root, this.ownership, kind);
         try {
             lstatSync(scoped.pidFile);
             return scoped;
@@ -68,12 +128,17 @@ export class KeeperLauncher {
             if (!stat.isFile() || stat.size > 4096 || process.getuid && stat.uid !== process.getuid())
                 throw new Error('Unsafe keeper PID manifest');
             const manifest = JSON.parse(readFileSync(descriptor, 'utf8'));
-            if (manifest.identity === scoped.identity && manifest.kind === kind && manifest.gen === gen)
+            if (manifest.identity === scoped.identity && manifest.kind === kind && manifest.gen === gen) {
+                assertOwnedDirectory(legacy.root, this.ownership, kind);
                 return legacy;
+            }
         }
         catch (error) {
-            if (error.code !== 'ENOENT')
+            if (error.code !== 'ENOENT') {
+                if (this.ownership && !(error instanceof RegistrationOwnershipError))
+                    throw new RegistrationOwnershipError('Keeper registration ownership could not be verified; state quarantined', error);
                 throw error;
+            }
         }
         finally {
             if (descriptor !== undefined)
@@ -196,7 +261,10 @@ export class KeeperLauncher {
         // `detached` is what makes it survive; do not add launchd keys or drop it.
         const child = spawn(nodePath, [script, config], { detached: true, stdio: 'ignore' });
         child.on('error', () => { });
+        this.options.onNativeAcquired?.(child, paths);
         child.unref();
+        if (child.pid)
+            await this.options.onNativeSpawn?.(child.pid, paths, child);
     }
     /**
      * Spec §3.1: a socket that fell back to `/tmp` (its configDir path is too long for sockaddr_un) is touched for every generation
@@ -244,6 +312,14 @@ export class KeeperLauncher {
             }
             return true;
         };
+        if (this.ownership) {
+            try {
+                await this.assertKeeperResources(kind, gen);
+            }
+            catch {
+                return { stopped: false, pid, reason: 'Registration resource ownership needs verification' };
+            }
+        }
         // keeper.stop needs the connection token (the daemon owns the run directory it lives in). Without a usable token
         // the keeper cannot be asked, so after the same identity check the force path uses, SIGTERM it (its handler is the graceful stop).
         let reason;

package/dist/workstation/keepers/legacy.js

@@ -9,8 +9,19 @@
 import { execFile, spawn } from 'node:child_process';
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
-import { keeperPaths, keeperRpc } from '../tools/client.js';
+import os from 'node:os';
+import { createHash } from 'node:crypto';
+import { keeperRpc } from '../tools/client.js';
 import { pidAlive } from './kit/lock.js';
+import { legacySourcesOf } from '../runtime/ownership.js';
+export function legacyKeeperPaths(options) {
+    const identity = createHash('sha256').update(JSON.stringify([path.resolve(options.configDir), options.workstationId, options.server])).digest('hex').slice(0, 32);
+    const namespace = `axom-tools-${process.getuid?.() ?? 'user'}`;
+    let dir = path.join(process.platform === 'darwin' ? '/tmp' : os.tmpdir(), namespace, identity);
+    if (Buffer.byteLength(path.join(dir, 'keeper.sock')) > 100)
+        dir = path.join('/tmp', namespace, identity);
+    return { dir, socket: path.join(dir, 'keeper.sock'), lock: path.join(dir, 'startup.lock'), pidFile: path.join(dir, 'keeper.pid.json'), lockPort: 20000 + Number.parseInt(identity.slice(0, 8), 16) % 40000, unit: `axom-tools-keeper-${identity}` };
+}
 /** A legacy keeper with no open PTY is stopped once nothing was routed to it for this long (the user may still read an exited one). */
 export const LEGACY_IDLE_MS = 10 * 60_000;
 /**
@@ -57,9 +68,12 @@ export class LegacyToolsKeeper {
     rpc;
     constructor(options) {
         this.options = options;
-        this.paths = options.paths ?? keeperPaths({ ...options.tools }, undefined, undefined, 'terminal');
+        this.paths = options.paths ?? legacyKeeperPaths(options.tools);
         this.now = options.now ?? Date.now;
         this.rpc = options.rpc ?? keeperRpc;
+        const sources = legacySourcesOf(options.ownership);
+        if (options.ownership && (!sources || path.resolve(options.tools.configDir) !== path.resolve(sources.adapterCacheDirectory) || options.tools.server !== sources.keeperServer))
+            this.current = 'absent';
     }
     get state() { return this.current; }
     /** Present or busy: it may hold sessions, so the router asks it. */

package/dist/workstation/keepers/policy.js

@@ -19,8 +19,6 @@
 //              older one gets a persistent intent to move there when idle (`moveOffOlderKeeperGenerations`, Task 24); an older
 //              generation that hosts no adapter any more is stopped (`retireIdleGenerations`). Never for `available` unless asked.
 //              replace-now stops the older generations at once (their in-flight turns end; the sessions reopen through session/load).
-//   legacy     the legacy tools keeper (spec §9) retires by itself (keepers/legacy.ts); it is reported `required`/`when-idle`, and
-//              replace-now stops it at once.
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { keeperOneShot, readKeeperToken } from './kit/client.js';
@@ -268,24 +266,8 @@ export class KeeperPolicy {
                 this.log(`[keepers] keeper-terminal could not be described: ${error instanceof Error ? error.message : String(error)}`);
             }
         }
-        const legacy = this.options.legacy;
-        if (legacy?.live)
-            out.push({ live: true, current: false, status: this.legacyStatus(legacy) });
         return out;
     }
-    legacyStatus(legacy) {
-        const { state, open } = legacy.status();
-        const shell = nameLabel(this.options.legacyShell?.(), 'shell');
-        const sessions = legacy.lastSessions();
-        return {
-            kind: 'terminal', gen: 'legacy', legacy: true, state: state === 'present' || state === 'stopping' ? 'running' : 'unavailable', // busy = not answering
-            protocolVersion: 0, buildVersion: 'legacy', replacement: 'required', pending: 'when-idle',
-            metrics: { ptyOpen: open ?? sessions.filter((session) => !session.exited).length, ptyActive: 0, execRunning: 0 },
-            items: sessions.slice(0, KEEPER_STATUS_MAX_ITEMS).map((session) => ({
-                type: 'pty', id: clip(session.id, 256), label: shell, state: session.exited ? 'exited' : 'idle', sinceEpochMs: 0,
-            })),
-        };
-    }
     async collectAcp() {
         const acp = this.options.acp;
         if (!acp)
@@ -351,7 +333,7 @@ export class KeeperPolicy {
     /** required/mandatory, never decided before (a cancel or a restart never brings an automatic decision back): queue it. */
     async automatic(sampled) {
         for (const { status, live, current } of sampled) {
-            if (status.legacy || current || !live || !replacesByItself(status.replacement))
+            if (current || !live || !replacesByItself(status.replacement))
                 continue;
             if (this.decisions.has(decisionKey(status.kind, status.gen)))
                 continue;
@@ -375,7 +357,7 @@ export class KeeperPolicy {
     async runQueued(sampled) {
         const acpPending = [];
         for (const { status, live, current } of sampled) {
-            if (status.legacy || current || this.pendingOf(status.kind, status.gen) !== 'when-idle')
+            if (current || this.pendingOf(status.kind, status.gen) !== 'when-idle')
                 continue;
             if (status.kind === 'acp') {
                 if (live)
@@ -465,8 +447,7 @@ export class KeeperPolicy {
     }
     async apply(frame) {
         const sampled = await this.sampled(true);
-        const older = sampled.filter((entry) => entry.status.kind === frame.kind && !entry.current && entry.live && !entry.status.legacy);
-        const legacy = frame.kind === 'terminal' ? sampled.find((entry) => entry.status.legacy) : undefined;
+        const older = sampled.filter((entry) => entry.status.kind === frame.kind && !entry.current && entry.live);
         const affected = [];
         let ok = true;
         let incomplete = false;
@@ -502,15 +483,6 @@ export class KeeperPolicy {
                         error = `generation ${status.gen} could not be stopped`;
                     }
                 }
-                if (legacy && this.options.legacy) {
-                    const shell = nameLabel(this.options.legacyShell?.(), 'shell');
-                    for (const session of await this.options.legacy.replaceNow())
-                        affected.push({ type: 'pty', id: session.id, label: shell, gen: 'legacy' });
-                    if (this.options.legacy.live) {
-                        ok = false;
-                        error = 'the legacy tools keeper could not be stopped';
-                    }
-                }
                 break;
             }
             case 'cancel': {
@@ -525,9 +497,8 @@ export class KeeperPolicy {
             }
         }
         this.sample = undefined;
-        // From the decisions themselves (a sample in flight may predate them); the legacy keeper is always queued while it lives.
-        const queued = [...this.decisions].some(([key, decision]) => key.startsWith(`${frame.kind}:`) && decision.mode === 'when-idle')
-            || (frame.kind === 'terminal' && this.options.legacy?.live === true);
+        // Read decisions directly: an in-flight sample may predate them.
+        const queued = [...this.decisions].some(([key, decision]) => key.startsWith(`${frame.kind}:`) && decision.mode === 'when-idle');
         if (affected.length > KEEPER_AFFECTED_MAX_ITEMS)
             incomplete = true;
         return {

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

@@ -3,11 +3,14 @@
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { readKeeperManifest } from '../kit/bundle.js';
-import { KeeperClient } from '../kit/client.js';
+import { KeeperClient, KeeperNotConnectedError, KeeperRequestError } from '../kit/client.js';
+import { liveManifest } from '../kit/lock.js';
 import { keeperGen } from '../kit/identity.js';
 import { defaultDistDir } from '../kit/launcher.js';
 import { protocolWindow } from '../kit/protocol.js';
+import { RegistrationOwnershipError } from '../../runtime/ownership.js';
 import { PTY_CAPABILITY, PTY_UNAVAILABLE_ERROR, TERMINAL_PROTOCOL_VERSION, execStream, } from './protocol.js';
+import { TERMINAL_GRID_LIMITS } from './gridProtocol.js';
 /** keeper-terminal could not be reached (launch, connect or hello failed): the request was never sent. */
 export class KeeperLaunchError extends Error {
     cause;
@@ -27,7 +30,12 @@ export function terminalStatusOf(hello) {
 const NOT_RUNNING_TTL_MS = 5000;
 /** The default bound of {@link TerminalKeeperClient.probe}: a real connect and hello, not a quick peek. */
 export const KEEPER_PROBE_TIMEOUT_MS = 3000;
-const errnoOf = (error) => typeof error === 'object' && error !== null && typeof error.code === 'string' ? error.code : undefined;
+const errnoOf = (error) => {
+    // The kit keeps its public not_connected code; classify only the underlying socket errno.
+    const source = error instanceof KeeperNotConnectedError ? error.cause : error;
+    return typeof source === 'object' && source !== null && typeof source.code === 'string'
+        ? source.code : undefined;
+};
 /** Connect errors that prove nothing listens: the socket file is gone, or a stale one with no listener behind it. */
 const ABSENT_ERRNOS = new Set(['ENOENT', 'ECONNREFUSED']);
 const messageOf = (error) => (error instanceof Error ? error.message : String(error));
@@ -48,7 +56,7 @@ export class TerminalKeeperClient {
     }
     get daemonProtocol() { return this.options.daemonProtocol ?? protocolWindow(TERMINAL_PROTOCOL_VERSION); }
     clientFor(paths) {
-        if (this.client && this.clientGen === paths.gen)
+        if (this.client && this.client.state !== 'closed' && this.clientGen === paths.gen)
             return this.client;
         this.client?.close();
         this.client = new KeeperClient({
@@ -70,6 +78,7 @@ export class TerminalKeeperClient {
      * most one keeper per kind at a time. A `gen`-bound client only connects to its generation.
      */
     async ensure() {
+        this.options.launcher.assertOwnership?.('terminal', this.clientGen ?? this.options.gen);
         const current = this.client;
         if (this.options.gen !== undefined) {
             if (current && current.state === 'ready')
@@ -123,24 +132,41 @@ export class TerminalKeeperClient {
         return probing;
     }
     async probeOnce(timeoutMs) {
+        try {
+            this.options.launcher.assertOwnership?.('terminal', this.clientGen ?? this.options.gen);
+        }
+        catch {
+            return { state: 'unknown', reason: 'Registration owner needs verification' };
+        }
         const absent = () => { this.notRunningUntil = Date.now() + NOT_RUNNING_TTL_MS; return { state: 'absent' }; };
         let gen;
         try {
-            gen = this.options.gen
+            gen = this.options.gen ?? this.currentGen
                 ?? keeperGen((await readKeeperManifest(path.join(this.options.distDir ?? defaultDistDir(), 'terminal'))).buildVersion);
         }
-        catch {
-            return absent();
-        } // no build of the current generation: nothing of it can run
+        catch (error) {
+            return errnoOf(error) === 'ENOENT' ? absent() : { state: 'unknown', reason: messageOf(error) };
+        } // A missing build is absent; unreadable or invalid metadata is inconclusive.
         const paths = this.options.launcher.pathsFor('terminal', gen);
         if (this.options.gen === undefined)
             this.currentGen = paths.gen;
+        // A live owner may be initializing, busy, or have lost its socket. None proves its sessions are gone.
+        const unreachable = async () => {
+            try {
+                if (await liveManifest(paths))
+                    return { state: 'unknown', reason: 'live keeper owner is unreachable' };
+                return absent();
+            }
+            catch (error) {
+                return { state: 'unknown', reason: messageOf(error) };
+            }
+        };
         try {
             await fs.access(paths.tokenFile);
             await fs.access(paths.socket);
         }
         catch (error) {
-            return ABSENT_ERRNOS.has(errnoOf(error) ?? '') ? absent() : { state: 'unknown', reason: messageOf(error) };
+            return ABSENT_ERRNOS.has(errnoOf(error) ?? '') ? unreachable() : { state: 'unknown', reason: messageOf(error) };
         }
         const client = this.clientFor(paths);
         let timer;
@@ -159,41 +185,105 @@ export class TerminalKeeperClient {
             return { state: 'unknown', reason: `protocol ${result.hello.protocolVersion} is outside the daemon's window` };
         }
         catch (error) {
-            // The token or the socket went away meanwhile, or nothing listens behind a stale socket file: the keeper is gone.
-            return ABSENT_ERRNOS.has(errnoOf(error) ?? '') ? absent() : { state: 'unknown', reason: messageOf(error) };
+            // Missing endpoints prove absence only when there is no verified live owner.
+            return ABSENT_ERRNOS.has(errnoOf(error) ?? '') ? unreachable() : { state: 'unknown', reason: messageOf(error) };
         }
         finally {
             clearTimeout(timer);
         }
     }
-    /** `tools.info` terminal fields from a running keeper's hello, else from `fallback` (a cached node-pty check). Starts nothing. */
+    /** `tools.info` terminal fields from a running keeper's hello, else from the caller's unavailable status. Starts nothing. */
     async terminalStatus(fallback) {
         const hello = await this.runningHello();
         return hello ? terminalStatusOf(hello) : fallback();
     }
     /** A failure to reach the keeper (launch, connect, hello) surfaces as {@link KeeperLaunchError}: nothing was sent. */
     async call(method, params, options = {}) {
+        this.options.launcher.assertOwnership?.('terminal', this.clientGen ?? this.options.gen);
         let client;
         try {
             client = await this.ensure();
         }
         catch (error) {
+            if (error instanceof RegistrationOwnershipError)
+                throw error;
             throw new KeeperLaunchError(error);
         }
-        return client.request(method, params, options);
+        const input = params;
+        const resource = method.startsWith('pty.') ? 'pty' : 'exec';
+        const id = resource === 'pty' ? input.id : input.execId;
+        if (this.options.launcher.ownership && typeof id === 'string' && method !== 'exec.status') {
+            let create = false;
+            if (method === 'pty.create')
+                create = !(await client.request('pty.list', {})).sessions.some(session => session.id === id);
+            if (method === 'exec.start')
+                create = !(await client.request('exec.list', {})).execs.some(exec => exec.execId === id);
+            this.options.launcher.assertResourceOwnership?.('terminal', this.clientGen, resource, id, create);
+        }
+        const result = await client.request(method, input, options);
+        if (this.options.launcher.ownership && typeof id === 'string' && method === 'exec.status') {
+            this.options.launcher.assertResourceOwnership?.('terminal', this.clientGen, resource, id);
+        }
+        if (this.options.launcher.ownership && (method === 'pty.list' || method === 'exec.list')) {
+            const registrationId = this.options.launcher.ownership.registrationId;
+            if (method === 'pty.list')
+                result.sessions = result.sessions.filter(session => !session.registrationId || session.registrationId === registrationId);
+            else
+                result.execs = result.execs.filter(exec => !exec.registrationId || exec.registrationId === registrationId);
+            const ids = method === 'pty.list' ? result.sessions.map(session => session.id) : result.execs.map(exec => exec.execId);
+            for (const current of ids)
+                this.options.launcher.assertResourceOwnership?.('terminal', this.clientGen, resource, current);
+        }
+        return result;
+    }
+    /** Connect only to existing terminal work. Never launch or retry a possibly delivered event. */
+    async callNative(method, params, absentResult) {
+        this.options.launcher.assertOwnership?.('terminal', this.clientGen ?? this.options.gen);
+        // A cached absence may predate another client's create; cleanup needs a fresh absence check.
+        const presence = this.hello ? { state: 'running' } : await this.probeOnce(KEEPER_PROBE_TIMEOUT_MS);
+        if (presence.state === 'absent') {
+            if (absentResult !== undefined)
+                return absentResult;
+            throw new KeeperRequestError('pty_not_found', 'Terminal session not found; keeper restart loses live PTYs');
+        }
+        if (presence.state === 'unknown')
+            throw new KeeperRequestError('pty_unavailable', `Terminal keeper unavailable: ${presence.reason}`);
+        const client = this.client;
+        if (!client)
+            throw new KeeperRequestError('pty_unavailable', 'Terminal keeper disconnected');
+        const input = params;
+        if (typeof input.id === 'string')
+            this.options.launcher.assertResourceOwnership?.('terminal', this.clientGen, 'pty', input.id);
+        return client.request(method, input);
+    }
+    create(params) { return this.call('pty.create', { ...params, ...(this.options.launcher.ownership ? { registrationId: this.options.launcher.ownership.registrationId } : {}) }); }
+    attach(params) { return this.callNative('pty.attach', params); }
+    poll(params) { return this.callNative('pty.poll', params); }
+    input(params) { return this.callNative('pty.input', params); }
+    resize(params) { return this.callNative('pty.resize', params); }
+    scroll(params) { return this.callNative('pty.scroll', params); }
+    detach(params) { return this.callNative('pty.detach', params, { ok: true }); }
+    close(params) { return this.callNative('pty.close', params, { ok: true }); }
+    /** Listing is a probe even if the ready socket disappears: reconnect, never launch. */
+    async list() {
+        const presence = await this.probe();
+        if (presence.state === 'absent')
+            return { schema: 1, limits: { ...TERMINAL_GRID_LIMITS }, sessions: [] };
+        if (presence.state === 'unknown')
+            throw new KeeperLaunchError(new Error(presence.reason));
+        const result = await this.client.request('pty.list', {});
+        const registrationId = this.options.launcher.ownership?.registrationId;
+        if (registrationId)
+            result.sessions = result.sessions.filter(session => !session.registrationId || session.registrationId === registrationId);
+        for (const session of result.sessions)
+            this.options.launcher.assertResourceOwnership?.('terminal', this.clientGen, 'pty', session.id);
+        return result;
     }
-    create(params) { return this.call('pty.create', params); }
-    attach(params) { return this.call('pty.attach', params); }
-    poll(params) { return this.call('pty.poll', params); }
-    write(params) { return this.call('pty.write', params); }
-    resize(params) { return this.call('pty.resize', params); }
-    takeover(params) { return this.call('pty.takeover', params); }
-    detach(params) { return this.call('pty.detach', params); }
-    close(params) { return this.call('pty.close', params); }
-    list() { return this.call('pty.list', {}); }
     activity() { return this.call('keeper.activity', {}); }
     // exec.* (spec §4.2). The daemon decides argv/env/deadline/quotas; the keeper only executes them.
-    execStart(params, options = {}) { return this.call('exec.start', params, options); }
+    execStart(params, options = {}) {
+        return this.call('exec.start', { ...params, ...(this.options.launcher.ownership ? { registrationId: this.options.launcher.ownership.registrationId } : {}) }, options);
+    }
     execList() { return this.call('exec.list', {}); }
     /** Descriptor plus the latest checkpoint (blob as given to `execCheckpoint`). */
     execStatus(execId, options = {}) { return this.call('exec.status', { execId }, options); }
@@ -206,7 +296,9 @@ export class TerminalKeeperClient {
      * resumes after the last record delivered.
      */
     async execSubscribe(execId, handler, options) {
-        return (await this.ensure()).subscribe(execStream(execId), handler, options);
+        const client = await this.ensure();
+        this.options.launcher.assertResourceOwnership?.('terminal', this.clientGen, 'exec', execId);
+        return client.subscribe(execStream(execId), handler, options);
     }
     /** Drops the connection (the keeper and its PTYs keep running). */
     disconnect() { this.client?.close(); this.client = undefined; this.clientGen = undefined; }

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;