@felan-ai/daemon 0.0.0-stage → 0.1.0

package/dist/daemon/processes.js

@@ -0,0 +1,691 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { createHash, randomUUID } from 'node:crypto';
+import { join, resolve } from 'node:path';
+import { setImmediate as yieldTurn } from 'node:timers/promises';
+import { stripVTControlCharacters } from 'node:util';
+import { DEFAULT_MAX_BYTES, getShellConfig, truncateTail } from '@earendil-works/pi-coding-agent';
+import { LIMITS, canonicalRequestPayload } from '@felan-ai/session-protocol';
+import { boundedText } from './projection.js';
+import { readOwnedOutputRange } from './session-files.js';
+import { pathInside } from './target.js';
+export class RegistryProcesses {
+    options;
+    live = new Map();
+    views = new Map();
+    lifetimes = new Set();
+    starting = new Set();
+    operations = new Map();
+    foregroundId = new AsyncLocalStorage();
+    foregroundStarts = new Map();
+    cleanup = new AsyncLocalStorage();
+    now;
+    constructor(options) {
+        this.options = options;
+        this.now = options.now ?? Date.now;
+    }
+    wrap(runtime, scope) {
+        const storage = new Map();
+        const lifetime = { scope, runtime, draining: false, revoked: false };
+        const current = () => this.assertLifetime(lifetime);
+        const checked = (operation) => this.track((async () => {
+            current();
+            const value = await operation();
+            this.options.assertCurrent();
+            return value;
+        })(), scope);
+        const wrapped = {
+            kind: runtime.kind, cwd: runtime.cwd, logger: runtime.logger, ...(runtime.classifier ? { classifier: runtime.classifier } : {}),
+            storage: (kind = 'session') => {
+                let result = storage.get(kind);
+                if (!result) {
+                    const original = runtime.storage(kind);
+                    result = {
+                        root: original.root,
+                        readFile: (path, opts) => checked(() => original.readFile(path, opts)),
+                        writeFile: (path, content) => checked(async () => {
+                            if (kind === 'session')
+                                this.observeJob(path, content, runtime, scope);
+                            await original.writeFile(path, content);
+                        }),
+                        appendFile: (path, content) => checked(() => original.appendFile(path, content)),
+                        listFiles: (path, opts) => checked(() => original.listFiles(path, opts)),
+                        mkdir: (path, opts) => checked(() => original.mkdir(path, opts)),
+                        remove: (path, opts) => checked(() => original.remove(path, opts)),
+                    };
+                    storage.set(kind, result);
+                }
+                return result;
+            },
+            exec: (command, args, opts) => checked(() => runtime.exec(command, args, opts)),
+            shell: (command, opts) => checked(() => runtime.shell(command, opts)),
+            readFile: (path, opts) => checked(() => runtime.readFile(path, opts)),
+            writeFile: (path, content, opts) => checked(() => runtime.writeFile(path, content, opts)),
+            listFiles: (path, opts) => checked(() => runtime.listFiles(path, opts)),
+            mkdir: (path, opts) => checked(() => runtime.mkdir(path, opts)),
+            remove: (path, opts) => checked(() => runtime.remove(path, opts)),
+            ...(runtime.files ? { files: {
+                    inspect: path => checked(() => runtime.files.inspect(path)),
+                    canonicalPath: path => checked(() => runtime.files.canonicalPath(path)),
+                    move: (source, target) => checked(() => runtime.files.move(source, target)),
+                    removeEmptyDirectory: path => checked(() => runtime.files.removeEmptyDirectory(path)),
+                    touch: (path, modifiedAt) => checked(() => runtime.files.touch(path, modifiedAt)),
+                    ensurePrivateDirectory: (path, options) => checked(() => runtime.files.ensurePrivateDirectory(path, options)),
+                    snapshot: (path, maxBytes) => checked(() => runtime.files.snapshot(path, maxBytes)),
+                    append: (path, content, expected) => checked(() => runtime.files.append(path, content, expected)),
+                } } : {}),
+            ...(runtime.readAgentFile ? { readAgentFile: (path) => checked(() => runtime.readAgentFile(path)) } : {}),
+            ...(runtime.privateRuntime ? { privateRuntime: { ensureDirectory: (name) => checked(() => runtime.privateRuntime.ensureDirectory(name)) } } : {}),
+            ...(runtime.processes ? { processes: {
+                    startShell: (command, opts) => this.start(lifetime, 'foreground', command, () => runtime.processes.startShell(command, opts), this.foregroundId.getStore()),
+                    ...(runtime.processes.startStdio ? { startStdio: (command, args, opts) => this.start(lifetime, 'foreground', command, () => runtime.processes.startStdio(command, args, opts), undefined, true) } : {}),
+                } } : {}),
+            ...(runtime.terminals ? { terminals: {
+                    startShell: async (command, opts) => {
+                        const id = opts?.id ?? randomUUID();
+                        await this.start(lifetime, 'pty', command, () => runtime.terminals.startShell(command, opts), id);
+                        return this.terminalHandle(lifetime, id);
+                    },
+                    attach: id => this.terminalHandle(lifetime, id),
+                } } : {}),
+        };
+        lifetime.runtime = wrapped;
+        this.lifetimes.add(lifetime);
+        return wrapped;
+    }
+    seal(session) { for (const lifetime of this.lifetimes)
+        if (lifetime.scope.session === session)
+            lifetime.draining = true; }
+    revoke(session) { for (const lifetime of this.lifetimes)
+        if (lifetime.scope.session === session) {
+            lifetime.revoked = true;
+            this.lifetimes.delete(lifetime);
+        } }
+    revokeRuntime(runtime) { for (const lifetime of this.lifetimes)
+        if (lifetime.runtime === runtime) {
+            lifetime.revoked = true;
+            this.lifetimes.delete(lifetime);
+        } }
+    sealAll() { for (const lifetime of this.lifetimes)
+        lifetime.draining = true; }
+    withCleanup(session, operation) {
+        return this.cleanup.run(new Set([...(this.cleanup.getStore() ?? []), ...(typeof session === 'string' ? [session] : session)]), operation);
+    }
+    assertLifetime(lifetime, starting = false) {
+        this.options.assertCurrent();
+        if (!lifetime.scope.session)
+            throw new Error('Session runtime is not bound yet.');
+        if (lifetime.revoked || lifetime.draining && (starting || !this.cleanup.getStore()?.has(lifetime.scope.session)))
+            throw new Error('Session runtime is closed to new work.');
+    }
+    runtime(session, root) {
+        return [...this.lifetimes].reverse().find(item => !item.revoked && item.scope.session === session && item.scope.root === root)?.runtime;
+    }
+    terminalHandle(lifetime, id) {
+        this.assertLifetime(lifetime);
+        const live = this.live.get(id);
+        if (!live || live.view.root !== lifetime.scope.root || live.view.kind !== 'pty')
+            return undefined;
+        const checked = (operation) => {
+            this.assertLifetime(lifetime);
+            return this.track(operation(), lifetime.scope);
+        };
+        return {
+            pid: live.raw.pid,
+            read: (offset, options) => checked(() => live.process.read(offset, options)),
+            write: content => checked(() => live.process.write(content)),
+            terminate: signal => checked(() => live.process.terminate(signal)),
+            ...(live.process.interrupt ? { interrupt: () => checked(() => live.process.interrupt()) } : {}),
+            dispose: async () => { },
+        };
+    }
+    list(root) {
+        return this.options.store.resources().filter(row => row.root === root).map(row => {
+            const known = this.views.get(row.id);
+            return known ?? { id: row.id, session: row.session, root, kind: row.kind,
+                state: row.state === 'reconciling' ? 'interrupted' : row.state, command: '', startedAt: row.updatedAt, controllable: false, outputOffset: 0 };
+        });
+    }
+    prepareForeground(session, settings = {}) {
+        const lifetime = this.currentLifetime(session);
+        this.assertLifetime(lifetime, true);
+        if (!lifetime.runtime.processes)
+            throw processFault('unavailable', 'Foreground processes are unavailable.');
+        const shell = getShellConfig(settings.shell).shell;
+        return { shell, prefix: settings.prefix, assertCurrent: () => this.assertLifetime(lifetime, true) };
+    }
+    async startForeground(requestId, session, params, prepared = this.prepareForeground(session)) {
+        const lifetime = this.currentLifetime(session);
+        this.assertLifetime(lifetime, true);
+        const request = this.options.store.request(requestId);
+        if (request?.session !== session || request.op !== 'shell.execute' || request.phase !== 'dispatch_intent')
+            throw new Error('Foreground start requires its committed shell dispatch.');
+        const payload = canonicalRequestPayload({ v: 1, id: requestId, op: 'shell.execute', session, params });
+        if (request.identity.bytes !== Buffer.byteLength(payload) || request.identity.sha256 !== createHash('sha256').update(payload).digest('hex'))
+            throw new Error('Shell command differs from its admitted payload.');
+        if (!lifetime.runtime.processes)
+            throw new Error('Foreground processes are unavailable.');
+        if (this.foregroundStarts.has(requestId))
+            throw new Error('Foreground dispatch cannot be repeated.');
+        const resourceId = `foreground:${requestId}`;
+        if (this.options.store.resource(resourceId))
+            throw processFault('already_resolved', 'Foreground dispatch already has a durable resource intent.');
+        this.foregroundStarts.set(requestId, resourceId);
+        return this.track((async () => {
+            prepared.assertCurrent();
+            const command = prepared.prefix ? `${prepared.prefix}\n${params.command}` : params.command;
+            const process = await this.foregroundId.run(resourceId, () => lifetime.runtime.processes.startShell(command, { shellFlavor: 'posix', shell: prepared.shell }));
+            this.assertLifetime(lifetime, true);
+            const live = this.live.get(resourceId);
+            if (!live || live.process !== process || live.view.session !== session)
+                throw new Error('Foreground process identity changed.');
+            return { resourceId };
+        })().catch(error => { this.foregroundStarts.delete(requestId); throw error; }), lifetime.scope);
+    }
+    async waitForeground(requester, id, onOutput) {
+        const row = this.authorizeResource(requester, id);
+        const live = this.live.get(id);
+        if (row.kind !== 'foreground' || !live)
+            throw new Error('Foreground process is unavailable.');
+        const lifetime = this.currentLifetime(row.session);
+        this.assertLifetime(lifetime);
+        return this.track((async () => {
+            let offset = 0;
+            let retained = 0;
+            let total = 0;
+            let discarded = false;
+            const chunks = [];
+            const decoder = new TextDecoder();
+            let pending = '';
+            let fullOutputPath;
+            const storage = lifetime.runtime.storage('session');
+            const append = async (raw) => {
+                const text = stripVTControlCharacters(raw).replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\uFFF9-\uFFFB\r]/gu, '');
+                if (!text)
+                    return;
+                total += Buffer.byteLength(text);
+                if (!fullOutputPath && total > DEFAULT_MAX_BYTES) {
+                    const directory = join(storage.root, 'shell-output');
+                    await storage.mkdir(directory, { recursive: true });
+                    fullOutputPath = join(directory, `${id}.log`);
+                    await storage.writeFile(fullOutputPath, Buffer.from(chunks.join('')));
+                }
+                if (fullOutputPath)
+                    await storage.appendFile(fullOutputPath, Buffer.from(text));
+                chunks.push(text);
+                retained += Buffer.byteLength(text);
+                while (retained > DEFAULT_MAX_BYTES * 2 && chunks.length > 1) {
+                    retained -= Buffer.byteLength(chunks.shift());
+                    discarded = true;
+                }
+                onOutput?.(truncateTail(chunks.join('')).content);
+            };
+            try {
+                for (;;) {
+                    const result = await live.process.read(offset, { waitMs: 1000, maxBytes: LIMITS.processReadBytes });
+                    this.assertLifetime(lifetime);
+                    this.assertLiveIdentity(this.authorizeResource(requester, id), live);
+                    if (!Number.isSafeInteger(result.nextOffset) || result.nextOffset !== offset + result.output.byteLength || result.output.byteLength > LIMITS.processReadBytes)
+                        throw new Error('Foreground output range is unavailable.');
+                    const decoded = pending + decoder.decode(result.output, { stream: true });
+                    const split = splitShellOutput(decoded);
+                    pending = split.pending;
+                    await append(split.complete);
+                    offset = result.nextOffset;
+                    if (!result.running && result.output.byteLength === 0) {
+                        await append(pending + decoder.decode());
+                        const resultText = truncateTail(chunks.join(''));
+                        return { output: resultText.content, exitCode: result.exitCode, cancelled: result.exitCode === undefined,
+                            truncated: discarded || resultText.truncated, ...(fullOutputPath ? { fullOutputPath } : {}) };
+                    }
+                    if (!result.output.byteLength)
+                        await yieldTurn();
+                }
+            }
+            finally {
+                for (const [request, resource] of this.foregroundStarts)
+                    if (resource === id)
+                        this.foregroundStarts.delete(request);
+            }
+        })(), lifetime.scope);
+    }
+    async cancelForeground(session) {
+        const rows = this.options.store.resources().filter(row => row.session === session && row.kind === 'foreground' && row.state === 'running');
+        for (const row of rows)
+            await this.stop(row.root, row.id);
+    }
+    async read(requester, id, offset, limit) {
+        if (!Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(limit) || limit < 1 || limit > LIMITS.processReadBytes)
+            throw new Error('Invalid process read range.');
+        const row = this.authorizeResource(requester, id);
+        if (row.kind === 'detached') {
+            const lifetime = this.currentLifetime(requester);
+            this.assertLifetime(lifetime);
+            if (!row.reference || !row.startIdentity)
+                throw new Error('Detached output identity is unavailable.');
+            const root = this.currentLifetime(row.root);
+            this.assertLifetime(root);
+            const storage = root.runtime.storage('session');
+            const reference = row.reference;
+            const directory = this.options.processAdapter?.storageDirectory(root.runtime);
+            if (!directory || !pathInside(directory, reference))
+                throw new Error('Detached output is outside its root storage.');
+            return this.track((async () => {
+                const info = this.describeJob(root.runtime, reference, await storage.readFile(reference, { maxBytes: 65536 }));
+                this.assertLifetime(lifetime);
+                this.assertLifetime(root);
+                const current = this.authorizeResource(requester, id);
+                if (current.reference !== reference || current.startIdentity !== row.startIdentity || current.kind !== 'detached'
+                    || !info || info.id !== id || info.startIdentity !== row.startIdentity || info.kind !== 'detached')
+                    throw new Error('Detached output identity changed.');
+                const data = readOwnedOutputRange(this.options.store.owner, info.outputPath, offset, limit);
+                this.assertLifetime(lifetime);
+                this.assertLifetime(root);
+                this.authorizeResource(requester, id);
+                const state = current.state === 'reconciling' ? 'interrupted' : info.status === 'unknown' ? 'missing'
+                    : info.status !== 'running' ? 'exited' : current.state;
+                return { data, offset, nextOffset: offset + data.byteLength, state,
+                    ...(state === 'exited' && typeof info.exitCode === 'number' && Number.isInteger(info.exitCode) ? { exitCode: info.exitCode } : {}) };
+            })(), lifetime.scope);
+        }
+        const live = this.live.get(id);
+        if (!live)
+            return { data: new Uint8Array(), offset, nextOffset: offset, state: row.state === 'interrupted' ? 'interrupted' : 'missing' };
+        const lifetime = this.creatorLifetime(row);
+        this.assertLifetime(lifetime);
+        this.assertLiveIdentity(row, live);
+        return this.track((async () => {
+            const snapshot = await live.process.read(offset, { maxBytes: limit });
+            this.assertLifetime(lifetime);
+            this.assertLiveIdentity(this.authorizeResource(requester, id), live);
+            if (!(snapshot.output instanceof Uint8Array) || snapshot.output.byteLength > limit
+                || !Number.isSafeInteger(snapshot.nextOffset) || snapshot.nextOffset !== offset + snapshot.output.byteLength) {
+                throw Object.assign(new Error('Process output range is no longer retained.'), { code: 'resync_required' });
+            }
+            return { data: new Uint8Array(snapshot.output), offset, nextOffset: snapshot.nextOffset,
+                state: snapshot.running ? 'running' : 'exited', ...(snapshot.exitCode === undefined ? {} : { exitCode: snapshot.exitCode }) };
+        })(), lifetime.scope);
+    }
+    async write(requester, id, data) {
+        if (!(data instanceof Uint8Array) || data.byteLength > LIMITS.processWriteBytes)
+            throw new Error('Invalid process input size.');
+        const bytes = new Uint8Array(data);
+        const row = this.authorizeResource(requester, id);
+        const live = this.live.get(id);
+        if (!live || live.disposed || live.settled || !live.view.controllable)
+            throw new Error('Process stdin is unavailable.');
+        const lifetime = this.creatorLifetime(row);
+        this.assertLifetime(lifetime);
+        this.assertLiveIdentity(row, live);
+        return this.track((async () => {
+            await live.process.write(bytes);
+            this.assertLifetime(lifetime);
+            this.assertLiveIdentity(this.authorizeResource(requester, id), live);
+            return bytes.byteLength;
+        })(), lifetime.scope);
+    }
+    assertWritable(requester, id) {
+        const row = this.authorizeResource(requester, id);
+        const live = this.live.get(id);
+        if (!live || live.disposed || live.settled || !live.view.controllable)
+            throw processFault('unavailable', 'Process stdin is unavailable.');
+        this.assertLifetime(this.creatorLifetime(row));
+        this.assertLiveIdentity(row, live);
+    }
+    async prepareStop(requester, id) {
+        let row = this.authorizeResource(requester, id);
+        this.assertLifetime(this.creatorLifetime(row));
+        if (this.live.has(id))
+            return;
+        await this.refresh(row.root);
+        row = this.authorizeResource(requester, id);
+        this.assertLifetime(this.creatorLifetime(row));
+        if (row.kind !== 'detached' || !this.views.get(id)?.controllable)
+            throw processFault('unavailable', 'Process identity is missing or unverified.');
+    }
+    async stopForSession(requester, id, signal) {
+        if (signal !== 'SIGTERM' && signal !== 'SIGKILL')
+            throw new Error('Unsupported process termination signal.');
+        const row = this.authorizeResource(requester, id);
+        const lifetime = this.creatorLifetime(row);
+        this.assertLifetime(lifetime);
+        return this.track((async () => {
+            await this.stop(row.root, id, signal);
+            this.assertLifetime(lifetime);
+            this.authorizeResource(requester, id);
+        })(), lifetime.scope);
+    }
+    currentLifetime(session) {
+        const lifetime = this.openLifetime(session);
+        if (!lifetime)
+            throw new Error('Process creator runtime is unavailable.');
+        return lifetime;
+    }
+    openLifetime(session) {
+        const stored = this.options.store.sessionMetadata(session);
+        return stored.state === 'open' ? [...this.lifetimes].reverse().find(item => !item.revoked && item.scope.session === session && item.scope.root === stored.root) : undefined;
+    }
+    /** A PTY kept across reload may outlive its child creator's runtime; its root then controls it. */
+    creatorLifetime(row) {
+        return this.openLifetime(row.session) ?? this.currentLifetime(row.root);
+    }
+    authorizeResource(requester, id) {
+        this.options.assertCurrent();
+        const sessions = this.options.store.sessionMetadatas();
+        const session = sessions.find(item => item.id === requester);
+        const row = this.options.store.resource(id);
+        if (!session || session.state !== 'open' || !row || row.root !== session.root)
+            throw new Error('Process not found in the authorized session scope.');
+        const creator = sessions.find(item => item.id === row.session);
+        if (!creator || creator.root !== row.root)
+            throw new Error('Process creator identity is invalid.');
+        let ancestor = creator;
+        const seen = new Set();
+        while (ancestor.id !== requester && ancestor.parent && !seen.has(ancestor.id)) {
+            seen.add(ancestor.id);
+            const parent = sessions.find(item => item.id === ancestor.parent && item.root === row.root);
+            if (!parent)
+                break;
+            ancestor = parent;
+        }
+        if (ancestor.id !== requester)
+            throw new Error('Process belongs to another session lineage.');
+        return row;
+    }
+    assertLiveIdentity(row, live) {
+        if (this.live.get(row.id) !== live || live.view.session !== row.session || live.view.root !== row.root || live.view.kind !== row.kind)
+            throw new Error('Retained process identity changed.');
+    }
+    blocksEviction(root) { return this.activeCount(root) > 0; }
+    /** In-flight runtime operations plus running or unverified processes of a root; stdio service transports are excluded. */
+    activeCount(root) {
+        return [...this.operations.values()].filter(({ scope, passive }) => scope.root === root && !passive).length
+            + this.options.store.resources().filter(row => row.root === root && !this.live.get(row.id)?.transport && (row.state === 'running' || row.state === 'reconciling')).length;
+    }
+    /** Work a daemon stop would interrupt: in-flight runtime operations and live non-transport processes. Detached jobs survive the daemon. */
+    async interruptibleCount() {
+        await this.observeLive();
+        return [...this.operations.values()].filter(({ passive }) => !passive).length
+            + [...this.live.values()].filter(item => !item.transport && !item.settled && !item.disposed).length;
+    }
+    async observeLive() {
+        await Promise.all([...this.live.values()].filter(item => !item.transport).map(item => this.observe(item)));
+    }
+    /** Roots that still hold undisposed live handles, including PTYs kept by a reload that never reopened its root. */
+    liveRoots() { return new Set([...this.live.values()].filter(item => !item.disposed).map(item => item.view.root)); }
+    /** Reconciles a root's processes; a failed per-process probe leaves that row unchanged, while store and ownership failures propagate. */
+    async refresh(root) {
+        for (const row of this.options.store.resources().filter(row => row.root === root)) {
+            const live = this.live.get(row.id);
+            if (live) {
+                await this.observe(live);
+                continue;
+            }
+            // Live handles end with the daemon that started them.
+            if (row.kind !== 'detached' && row.state === 'running' && !this.starting.has(row.id)) {
+                this.update(row, 'interrupted');
+                continue;
+            }
+            if (row.kind !== 'detached' || !row.reference || !row.startIdentity)
+                continue;
+            const runtime = this.runtime(row.session, root) ?? this.runtime(root, root);
+            if (!runtime)
+                continue;
+            const bytes = await runtime.storage('session').readFile(row.reference, { maxBytes: 64 * 1024 }).catch(() => undefined);
+            this.options.assertCurrent();
+            if (!bytes) {
+                this.update(row, 'missing');
+                continue;
+            }
+            const adapter = this.options.processAdapter;
+            if (!adapter)
+                continue;
+            let info;
+            try {
+                info = this.describeJob(runtime, row.reference, bytes);
+            }
+            catch {
+                this.update(row, 'missing');
+                continue;
+            }
+            if (!info || info.id !== row.id || info.startIdentity !== row.startIdentity || info.kind !== 'detached') {
+                this.update(row, 'missing');
+                continue;
+            }
+            const job = await Promise.resolve().then(() => adapter.inspectDetached(runtime, row.id)).catch(() => undefined);
+            this.options.assertCurrent();
+            if (!job)
+                continue;
+            if (job.status !== 'running') {
+                this.update(row, job.status === 'unknown' ? 'missing' : 'exited');
+                continue;
+            }
+            const pid = job.pid;
+            const inspection = pid ? await runtime.exec('ps', ['-o', 'command=', '-p', String(pid)]).catch(() => null) : undefined;
+            this.options.assertCurrent();
+            if (inspection === null)
+                continue;
+            const verified = inspection?.code === 0 && info.commandIdentity.every(value => inspection.stdout.includes(value)) && inspection.stdout.includes(row.startIdentity);
+            this.update(row, verified ? 'running' : 'reconciling', {
+                id: row.id, session: row.session, root, kind: 'detached', state: verified ? 'running' : 'interrupted',
+                command: boundedText(info.command, 16384), startedAt: info.startedAt, controllable: verified, outputOffset: 0,
+            });
+        }
+    }
+    async stop(root, id, signal = 'SIGTERM') {
+        this.options.assertCurrent();
+        const row = this.options.store.resource(id);
+        if (!row || row.root !== root)
+            throw new Error('Process not found in this root session.');
+        const live = this.live.get(id);
+        if (live) {
+            await live.process.terminate(signal);
+            await live.process.read(0, { maxBytes: 0 });
+            return;
+        }
+        await this.refresh(root);
+        this.options.assertCurrent();
+        const runtime = this.runtime(row.session, root) ?? this.runtime(root, root);
+        if (!runtime || !this.views.get(id)?.controllable || row.kind !== 'detached')
+            throw new Error('Process identity is missing or unverified.');
+        const adapter = this.options.processAdapter;
+        if (!adapter)
+            throw processFault('unavailable', 'Detached process control is unavailable.');
+        await adapter.stopDetached(runtime, id, signal);
+        await this.refresh(root);
+    }
+    /** Settles a root's live handles and operations; `keepTerminals` leaves PTYs running for the root's next runtime. */
+    async settle(root, fenced = false, sessions, keepTerminals = false) {
+        const owns = (scope) => scope.root === root && (!sessions || sessions.has(scope.session));
+        const settles = (item) => owns(item.view) && !item.disposed && !(keepTerminals && item.view.kind === 'pty');
+        for (const lifetime of this.lifetimes)
+            if (owns(lifetime.scope))
+                lifetime.draining = true;
+        const failures = [];
+        const join = async (operations) => {
+            const results = await Promise.allSettled(operations);
+            for (const result of results)
+                if (result.status === 'rejected')
+                    failures.push(result.reason);
+        };
+        for (;;) {
+            // Terminate first: a pending foreground read may need process exit to unblock.
+            const handles = [...this.live.values()].filter(settles);
+            await join(handles.map(async (item) => {
+                if (!item.settled)
+                    await item.raw.terminate('SIGTERM');
+            }));
+            const pending = [...this.operations].filter(([, { scope }]) => owns(scope)).map(([operation]) => operation);
+            await join(pending);
+            await join(handles.map(async (item) => {
+                const snapshot = await item.raw.read(0, { maxBytes: 0 });
+                if (snapshot.running)
+                    throw new Error('A live process did not settle.');
+                item.settled = true;
+                if (!fenced) {
+                    item.view = { ...item.view, state: 'exited', controllable: false, outputOffset: snapshot.nextOffset, ...(snapshot.exitCode === undefined ? {} : { exitCode: snapshot.exitCode }) };
+                    const row = this.options.store.resource(item.view.id);
+                    this.update(row, 'exited', item.view);
+                }
+                await item.raw.dispose();
+                item.disposed = true;
+            }));
+            if (failures.length)
+                throw new AggregateError(failures, 'Owned processes did not settle.');
+            if (![...this.operations.values()].some(({ scope }) => owns(scope)) && ![...this.live.values()].some(settles))
+                break;
+        }
+    }
+    start(lifetime, kind, command, create, requestedId, transport = false) {
+        const scope = lifetime.scope;
+        return this.track((async () => {
+            this.assertLifetime(lifetime, true);
+            const id = requestedId ?? randomUUID();
+            const previous = this.options.store.resource(id);
+            if (this.live.has(id) || this.starting.has(id) || previous && (previous.session !== scope.session || previous.root !== scope.root || previous.kind !== kind))
+                throw new Error('Process identity is already registered.');
+            this.starting.add(id);
+            const row = previous ?? { id, ...scope, kind, state: 'running', updatedAt: this.now() };
+            this.update(row, 'running', { id, ...scope, kind, state: 'running', command: boundedText(command, 16384), startedAt: this.now(), controllable: false, outputOffset: 0 });
+            let process;
+            try {
+                process = await create();
+            }
+            catch (error) {
+                this.update(row, 'missing');
+                throw error;
+            }
+            finally {
+                this.starting.delete(id);
+            }
+            try {
+                this.options.assertCurrent();
+            }
+            catch (error) {
+                await process.terminate('SIGTERM');
+                await process.dispose();
+                throw error;
+            }
+            const view = { id, ...scope, kind, state: 'running', command: boundedText(command, 16384), startedAt: this.now(), controllable: true, outputOffset: 0 };
+            const live = { raw: process, process, view, transport, settled: false, disposed: false };
+            const wrapped = new Proxy(process, { get: (target, key) => {
+                    const current = () => { this.options.assertCurrent(); if (live.disposed)
+                        throw new Error('Process handle is disposed.'); };
+                    if (key === 'read' || transport && (key === 'readStdout' || key === 'readStderr'))
+                        return (...args) => {
+                            if (live.disposed)
+                                return Promise.resolve({ output: new Uint8Array(), nextOffset: live.view.outputOffset, running: false,
+                                    ...(live.view.exitCode === undefined ? {} : { exitCode: live.view.exitCode }), ...(live.signal ? { signal: live.signal } : {}) });
+                            return this.track((async () => {
+                                current();
+                                const read = Reflect.get(target, key, target);
+                                const snapshot = await read.apply(target, args);
+                                this.options.assertCurrent();
+                                this.record(live, row, snapshot, key === 'read');
+                                return { ...snapshot, running: !live.settled, ...(live.view.exitCode === undefined ? {} : { exitCode: live.view.exitCode }), ...(!snapshot.running && live.signal ? { signal: live.signal } : {}) };
+                            })(), scope, transport);
+                        };
+                    if (key === 'terminate')
+                        return (signal = 'SIGTERM') => {
+                            if (live.disposed)
+                                return Promise.resolve();
+                            current();
+                            live.signal = signal;
+                            return this.track(target.terminate(signal).catch(error => { delete live.signal; throw error; }), scope);
+                        };
+                    const value = Reflect.get(target, key, target);
+                    if (typeof value !== 'function')
+                        return value;
+                    return (...args) => {
+                        if (live.disposed && (key === 'dispose' || key === 'terminate' || key === 'closeInput'))
+                            return Promise.resolve();
+                        current();
+                        // A PTY outlives its starting runtime across reload; its callers check their own current lifetime.
+                        if ((key === 'write' || key === 'resize') && kind !== 'pty')
+                            this.assertLifetime(lifetime);
+                        return this.track(Promise.resolve(Reflect.apply(value, target, args)).then(result => {
+                            this.options.assertCurrent();
+                            if (key === 'dispose')
+                                live.disposed = true;
+                            return result;
+                        }), scope);
+                    };
+                } });
+            live.process = wrapped;
+            this.live.set(id, live);
+            this.update(row, 'running', view);
+            return wrapped;
+        })(), scope);
+    }
+    describeJob(runtime, path, bytes) {
+        const adapter = this.options.processAdapter;
+        if (!adapter || !pathInside(adapter.storageDirectory(runtime), path))
+            return undefined;
+        const info = adapter.describeJob(runtime, path, bytes);
+        if (info && !pathInside(adapter.storageDirectory(runtime), info.outputPath))
+            throw new Error('Process output is outside its root storage.');
+        return info;
+    }
+    observeJob(path, bytes, runtime, scope) {
+        const absolute = resolve(runtime.storage('session').root, path);
+        const directory = this.options.processAdapter?.storageDirectory(runtime);
+        if (!directory || !pathInside(directory, absolute))
+            return;
+        const info = this.describeJob(runtime, absolute, bytes);
+        if (!info)
+            return;
+        const previous = this.options.store.resource(info.id);
+        const row = previous ?? { id: info.id, ...scope, kind: info.kind, state: 'running', reference: absolute,
+            ...(info.startIdentity ? { startIdentity: info.startIdentity } : {}), updatedAt: this.now() };
+        if (previous && (previous.root !== scope.root || previous.reference !== absolute || previous.startIdentity !== info.startIdentity))
+            throw new Error('Background job identity changed.');
+        this.update(row, info.status === 'running' ? 'running' : info.status === 'unknown' ? 'missing' : 'exited', {
+            id: info.id, session: row.session, root: row.root, kind: row.kind, state: info.status === 'running' ? 'running' : info.status === 'unknown' ? 'missing' : 'exited',
+            command: boundedText(info.command, 16384), startedAt: info.startedAt, controllable: this.live.has(info.id), outputOffset: 0,
+        });
+    }
+    record(live, row, snapshot, advance) {
+        live.settled ||= !snapshot.running;
+        live.view = { ...live.view, state: live.settled ? 'exited' : 'running', controllable: !live.settled, outputOffset: advance ? Math.max(live.view.outputOffset, snapshot.nextOffset) : live.view.outputOffset, ...(snapshot.exitCode === undefined ? {} : { exitCode: snapshot.exitCode }) };
+        this.update(row, live.view.state, live.view);
+    }
+    /** Records an exit nobody has read yet, e.g. a PTY kept across reload; a failed probe leaves the handle as it was. */
+    async observe(live) {
+        if (live.settled || live.disposed)
+            return;
+        const snapshot = await this.track(live.raw.read(live.view.outputOffset, { maxBytes: 0 }), live.view, true).catch(() => undefined);
+        this.options.assertCurrent();
+        const row = this.options.store.resource(live.view.id);
+        if (!snapshot || !row || this.live.get(live.view.id) !== live || live.disposed)
+            return;
+        this.record(live, row, snapshot, false);
+    }
+    update(row, state, view) {
+        this.options.assertCurrent();
+        const old = this.options.store.resource(row.id);
+        const known = view ?? this.views.get(row.id);
+        const next = known ? { ...known, state: state === 'reconciling' ? 'interrupted' : state, controllable: state === 'running' && known.controllable }
+            : { id: row.id, session: row.session, root: row.root, kind: row.kind, state: state === 'reconciling' ? 'interrupted' : state,
+                command: '', startedAt: row.updatedAt, controllable: false, outputOffset: 0 };
+        if (!old || old.state !== state || JSON.stringify(this.views.get(row.id)) !== JSON.stringify(next)) {
+            const commit = this.options.store.putResource({ ...row, state });
+            this.views.set(row.id, next);
+            this.options.changed(row.session, next, commit.revisions[row.session]);
+        }
+    }
+    track(operation, scope, passive = false) {
+        this.operations.set(operation, { scope, passive });
+        void operation.then(() => this.operations.delete(operation), () => this.operations.delete(operation));
+        return operation;
+    }
+}
+function processFault(code, message) { return Object.assign(new Error(message), { code }); }
+function splitShellOutput(value) {
+    const start = Math.max(0, value.length - 256);
+    const tail = value.slice(start);
+    const osc = tail.lastIndexOf('\x1b]');
+    if (osc >= 0 && !/[\x07\x9c]|\x1b\\/u.test(tail.slice(osc + 2)))
+        return { complete: value.slice(0, start + osc), pending: tail.slice(osc) };
+    const incomplete = /(?:\x1b(?:\[[0-?]*[ -/]*|[()][ -/]*)?|\x9b[0-?]*[ -/]*)$/u.exec(tail);
+    return incomplete ? { complete: value.slice(0, start + incomplete.index), pending: incomplete[0] } : { complete: value, pending: '' };
+}
+//# sourceMappingURL=processes.js.map