@platless/axom-cli 0.5.9 → 0.6.52

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

@@ -97,23 +97,27 @@ export async function gcBundles(options) {
     const keep = new Set(options.keep ?? []);
     const removed = [];
     for (const kind of KEEPER_KINDS) {
-        const root = path.join(path.resolve(options.configDir), 'keepers', kind);
-        const referenced = new Set(keep);
-        for (const gen of await fs.readdir(path.join(root, 'run')).catch(() => [])) {
-            const manifest = await readPidManifest(path.join(root, 'run', gen, 'keeper.pid.json')).catch(() => null);
-            if (manifest && await manifestProcessLive(manifest))
-                referenced.add(manifest.buildVersion);
-        }
-        const bundles = path.join(root, 'bundles');
-        for (const name of await fs.readdir(bundles).catch(() => [])) {
-            if (referenced.has(name))
-                continue;
-            const dir = path.join(bundles, name);
-            const stat = await fs.lstat(dir).catch(() => null);
-            if (!stat || (minAge > 0 && now - Math.max(stat.mtimeMs, stat.ctimeMs) < minAge))
-                continue;
-            await fs.rm(dir, { recursive: true, force: true });
-            removed.push(dir);
+        const kindRoot = path.join(path.resolve(options.configDir), 'keepers', kind);
+        const entries = await fs.readdir(kindRoot, { withFileTypes: true }).catch(() => []);
+        const roots = [kindRoot, ...entries.filter(entry => entry.isDirectory() && /^[0-9a-f]{32}$/.test(entry.name)).map(entry => path.join(kindRoot, entry.name))];
+        for (const root of roots) {
+            const referenced = new Set(keep);
+            for (const gen of await fs.readdir(path.join(root, 'run')).catch(() => [])) {
+                const manifest = await readPidManifest(path.join(root, 'run', gen, 'keeper.pid.json')).catch(() => null);
+                if (manifest && await manifestProcessLive(manifest))
+                    referenced.add(manifest.buildVersion);
+            }
+            const bundles = path.join(root, 'bundles');
+            for (const name of await fs.readdir(bundles).catch(() => [])) {
+                if (referenced.has(name))
+                    continue;
+                const dir = path.join(bundles, name);
+                const stat = await fs.lstat(dir).catch(() => null);
+                if (!stat || (minAge > 0 && now - Math.max(stat.mtimeMs, stat.ctimeMs) < minAge))
+                    continue;
+                await fs.rm(dir, { recursive: true, force: true });
+                removed.push(dir);
+            }
         }
     }
     return removed;

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

@@ -24,7 +24,7 @@ export class KeeperRequestTimeoutError extends Error {
 }
 export class KeeperNotConnectedError extends Error {
     code = 'not_connected';
-    constructor(message = 'Keeper is not connected') { super(message); this.name = 'KeeperNotConnectedError'; }
+    constructor(message = 'Keeper is not connected', options) { super(message, options); this.name = 'KeeperNotConnectedError'; }
 }
 export class KeeperClosedError extends Error {
     code = 'closed';
@@ -154,7 +154,7 @@ function connectLink(socketPath, limits, timeoutMs, onEvt, onClose) {
         const timer = setTimeout(() => fail(new KeeperNotConnectedError('Timed out connecting to the keeper')), timeoutMs);
         const fail = (error) => { if (settled)
             return; settled = true; clearTimeout(timer); socket.destroy(); reject(error); };
-        socket.once('error', (error) => fail(new KeeperNotConnectedError(error.message)));
+        socket.once('error', (error) => fail(new KeeperNotConnectedError(error.message, { cause: error })));
         socket.once('connect', () => {
             if (settled)
                 return;

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

@@ -1,6 +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, mkdirSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { keeperOneShot, readKeeperToken } from './client.js';
@@ -9,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) {
@@ -46,20 +48,122 @@ 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) { return keeperPaths(this.options, kind, gen); }
+    pathsFor(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;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        const legacy = keeperPaths(this.options, kind, gen, { legacyLayout: true });
+        let descriptor;
+        try {
+            descriptor = openSync(legacy.pidFile, constants.O_RDONLY | constants.O_NOFOLLOW);
+            const stat = fstatSync(descriptor);
+            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) {
+                assertOwnedDirectory(legacy.root, this.ownership, kind);
+                return legacy;
+            }
+        }
+        catch (error) {
+            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)
+                closeSync(descriptor);
+        }
+        return scoped;
+    }
     /** The generation the current build of `kind` runs as (`dist/keepers/<kind>/manifest.json`); starts nothing. */
     async currentGen(kind) {
         return keeperGen((await readKeeperManifest(path.join(this.distDir, kind))).buildVersion);
     }
     /** Generations of `kind` whose pid manifest names a live keeper of that generation (`<root>/run/<gen>`); starts nothing. */
     async liveGenerations(kind) {
-        const runRoot = path.join(this.pathsFor(kind, 'probe').root, 'run');
-        const gens = await fs.readdir(runRoot).catch(() => []);
+        const scoped = keeperPaths(this.options, kind, 'probe');
+        const legacy = keeperPaths(this.options, kind, 'probe', { legacyLayout: true });
+        const roots = [scoped.root, legacy.root];
+        const gens = new Set();
+        for (const root of roots)
+            for (const gen of await fs.readdir(path.join(root, 'run')).catch(() => [])) {
+                const manifest = await readPidManifest(path.join(root, 'run', gen, 'keeper.pid.json')).catch(() => null);
+                if (manifest?.identity === scoped.identity && manifest.kind === kind && manifest.gen === gen)
+                    gens.add(gen);
+            }
         const live = [];
-        for (const gen of gens.sort())
+        for (const gen of [...gens].sort())
             if (await liveManifest(this.pathsFor(kind, gen)).catch(() => false))
                 live.push(gen);
         return live;
@@ -76,7 +180,7 @@ export class KeeperLauncher {
     async start(kind) {
         const deadline = Date.now() + (this.options.startTimeoutMs ?? 7500);
         const manifest = await readKeeperManifest(path.join(this.distDir, kind));
-        const paths = keeperPaths(this.options, kind, keeperGen(manifest.buildVersion));
+        const paths = this.pathsFor(kind, keeperGen(manifest.buildVersion));
         await ensureKeeperDirectories(paths);
         // A keeper that already answers needs no snapshot check: it runs from the snapshot it was started with.
         const alive = await this.probe(paths);
@@ -157,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
@@ -165,9 +272,10 @@ export class KeeperLauncher {
      * socket. Sockets under configDir are left alone. Returns how many were touched; never throws.
      */
     async touchSockets(kind) {
-        const runRoot = path.join(this.pathsFor(kind, 'probe').root, 'run');
+        const root = keeperPaths(this.options, kind, 'probe').root;
+        const gens = new Set([...await fs.readdir(path.join(root, 'run')).catch(() => []), ...await this.liveGenerations(kind)]);
         let touched = 0;
-        for (const gen of await fs.readdir(runRoot).catch(() => [])) {
+        for (const gen of gens) {
             const paths = this.pathsFor(kind, gen);
             if (paths.socketFallback && await touchSocket(paths).catch(() => false))
                 touched += 1;
@@ -204,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/kit/paths.js

@@ -16,7 +16,8 @@ export function keeperLockPort(identity, gen) {
 }
 export function keeperPaths(input, kind, gen, options = {}) {
     const identity = keeperIdentity(input, kind);
-    const root = path.join(path.resolve(input.configDir), 'keepers', kind);
+    const kindRoot = path.join(path.resolve(input.configDir), 'keepers', kind);
+    const root = options.legacyLayout ? kindRoot : path.join(kindRoot, identity);
     const runDir = path.join(root, 'run', gen);
     let socket = path.join(runDir, 'keeper.sock');
     let socketDir = runDir;

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; }