@felan-ai/daemon 0.0.0-stage → 0.0.0

package/dist/daemon/registry.js

@@ -0,0 +1,1591 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { closeSync, constants, existsSync, fsyncSync, openSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { canonicalRequestPayload, parseInteraction, parseSchema } from '@felan-ai/session-protocol';
+import { RegistryExecutions, ExecutionHost } from './executions.js';
+import { SessionProfileSchema } from './control-state.js';
+import { LegacySessionIndex, readTranscriptPreview, transcriptHasConversation, transcriptPreview } from './legacy-sessions.js';
+import { profilePolicy, SessionProjection } from './projection.js';
+import { RegistryProcesses } from './processes.js';
+import { guardOwnedPaths, sha256 } from './persistence.js';
+import { isConversationEntry, prepareTranscriptDeletion } from './session-files.js';
+import { assertTargetIdentity, canonicalProspectivePath, pathInside } from './target.js';
+import { sessionTip } from './session-cursor.js';
+import { shutdownStep } from './shutdown-error.js';
+const nonRunMutations = new Set(['set_model', 'set_thinking', 'session.rename', 'session.entry.label', 'session.branch.select', 'session.export', 'command.invoke', 'shell.execute', 'processes.write', 'processes.stop', 'steer', 'follow_up', 'executions.steer', 'executions.cancel', 'ui.action']);
+class RegistryOpeningCancelled extends Error {
+}
+export class SessionRegistry {
+    options;
+    processes;
+    recovery;
+    entries = new Map();
+    executionManagers = new Map();
+    runtimeOpening = new AsyncLocalStorage();
+    bindingActivation = new AsyncLocalStorage();
+    opening = new Map();
+    pathClaims = new Set();
+    copyClaims = new Set();
+    reservations = new Map();
+    lifecycleWriters = new Set();
+    reloadAttachments = new Map();
+    invalidationListeners = new Set();
+    observers = new Map();
+    listeners = new Map();
+    interactionListeners = new Set();
+    retainedServices = new Map();
+    shutdownInterruptions = new Map();
+    closing = new Set();
+    closes = new Map();
+    now;
+    startedAt;
+    legacy;
+    legacyListing;
+    previews = new Map();
+    stopping = false;
+    draining = false;
+    failure;
+    failureSettlement;
+    cancellationFailures = new Set();
+    lossUnsubscribe;
+    commandDispatcher;
+    constructor(options) {
+        this.options = options;
+        options.owner.assertCurrent();
+        if (options.store.owner !== options.owner)
+            throw new Error('Registry and store require the same held ownership.');
+        this.now = options.now ?? Date.now;
+        this.startedAt = this.now();
+        this.legacy = new LegacySessionIndex(options.owner);
+        this.recovery = options.store.needsRecovery ? options.store.recover().value : undefined;
+        this.processes = new RegistryProcesses({ ...(options.processAdapter ? { processAdapter: options.processAdapter } : {}), store: options.store, now: this.now, assertCurrent: () => options.owner.assertCurrent(),
+            changed: (id, process, rev) => this.publish({ v: 1, session: id, rev, change: { type: 'process.updated', process } }) });
+        this.lossUnsubscribe = options.owner.onLost(error => { this.fence(error); });
+    }
+    wrapOpeningRuntime(runtime, root) {
+        const opening = this.runtimeOpening.getStore();
+        if (!opening)
+            throw new Error('Runtime factories must run inside lifecycle.openSession.');
+        const scope = { session: '', root };
+        opening.scope = scope;
+        return this.processes.wrap(runtime, scope);
+    }
+    assertAdmission() {
+        this.options.owner.assertCurrent();
+        this.options.store.assertCurrent();
+        if (this.failure)
+            throw new Error('Registry is not admitting work.');
+        if (this.stopping)
+            throw new RegistryOpeningCancelled('Registry is not admitting work.');
+    }
+    assertDispatch(id) {
+        this.assertSessionAccess(id, false);
+    }
+    /** A binding's own services run while its open or reload still holds the session reservation. */
+    assertServiceAccess(id) {
+        this.assertSessionAccess(id, this.opening.has(id));
+    }
+    assertSessionAccess(id, activatingBinding) {
+        this.assertAdmission();
+        const session = this.options.store.sessionMetadata(id);
+        if (session.deletedAt !== undefined)
+            throw registryError('not_found', 'Session was deleted.');
+        if (this.reservations.has(session.piPath) && !activatingBinding)
+            throw registryError('busy', 'Session has a lifecycle operation in progress.');
+        if (session.state !== 'open' || this.entries.get(id)?.disposing || this.entries.get(id)?.cancelling || this.closing.has(id) || this.closing.has(session.root) || this.copyClaims.has(session.piPath))
+            throw new Error('Session is closing, cancelling or has a pinned copy in progress.');
+    }
+    assertNewWork() {
+        this.assertAdmission();
+        if (this.draining)
+            throw registryError('busy', 'Daemon is draining.');
+    }
+    failExecution(error) { this.fence(error); }
+    get fenced() { return this.failure !== undefined; }
+    beginDrain() {
+        if (this.draining && this.stopping && !this.failure) {
+            this.options.owner.assertCurrent();
+            this.options.store.assertCurrent();
+            return;
+        }
+        this.assertAdmission();
+        this.draining = true;
+    }
+    /** Reopens admission after an abandoned drain; a registry that started shutting down cannot resume. */
+    endDrain() {
+        this.assertAdmission();
+        this.draining = false;
+    }
+    async waitForDrain() {
+        this.assertAdmission();
+        if (!this.draining)
+            throw new Error('Drain must be started before waiting.');
+        await this.join([...this.entries.keys()].map(id => this.cancelViews(id)));
+        await this.join([...this.opening.values(), ...this.closes.values(), ...this.lifecycleWriters], undefined, true);
+        for (const entry of this.entries.values()) {
+            await entry.host?.settle();
+            await entry.cancelling;
+            await this.join([...entry.writers]);
+            for (const service of entry.services)
+                await service.settle('drain');
+        }
+        this.assertAdmission();
+        if (await this.activeWork())
+            throw registryError('busy', 'Daemon still owns active processes or work. Explicit force is required to interrupt it.');
+    }
+    /** Units of work a drain waits for and a forced stop interrupts: busy resident sessions (including child executions) and live processes. Detached jobs survive a restart and are excluded. */
+    async activeWork() {
+        this.options.owner.assertCurrent();
+        const interruptible = await this.processes.interruptibleCount();
+        const busy = [...this.entries.values()].filter(entry => !entry.binding.runtime.session.isIdle || entry.dispatches.size || entry.writers.size
+            || entry.host?.hasPendingWork() || entry.host?.hasActiveJobs() || [...entry.services].some(service => service.busy())).length;
+        return busy + interruptible;
+    }
+    create(request) {
+        this.assertNewWork();
+        if (request.parentSessionId && (this.closing.has(request.parentSessionId) || this.closing.has(request.rootSessionId)))
+            throw new Error('Parent session is closing.');
+        if (request.target.kind === 'resume')
+            throw new Error('Restore registered sessions by ID.');
+        if (request.parentSessionId && request.rootSessionId && request.extensionConfigOverrides === undefined) {
+            const overrides = this.options.store.sessionMetadata(request.rootSessionId).profile?.extensionConfigOverrides;
+            if (overrides)
+                request = { ...request, extensionConfigOverrides: overrides };
+        }
+        const key = randomUUID();
+        const opening = this.open(request);
+        this.opening.set(key, opening);
+        void opening.then(() => this.opening.delete(key), () => this.opening.delete(key));
+        return opening;
+    }
+    async openWorker(parent, worker) {
+        this.assertNewWork();
+        this.assertDispatch(parent);
+        const owner = this.options.store.sessionMetadata(parent);
+        const root = this.require(owner.root).binding;
+        const manager = worker.sessionManager;
+        const file = manager.getSessionFile();
+        if (!file || this.list().some(row => row.id === manager.getSessionId()))
+            throw registryError('invalid_request', 'Worker transcript must have a fresh identity.');
+        const path = this.options.owner.assertOwnsPath(file);
+        if (!pathInside(root.resources.sessionDir, path))
+            throw registryError('forbidden', 'Worker transcript is outside the root session directory.');
+        const workspace = this.options.owner.assertOwnsPath(worker.runtime.cwd);
+        if (!(root.resources.workerRoots ?? []).some(directory => pathInside(directory, workspace))) {
+            throw registryError('forbidden', 'Worker workspace is outside managed staging storage.');
+        }
+        const tools = new Set(['read', 'ls', 'grep', 'edit', 'write', ...(worker.customTools ?? []).map(tool => tool.name)]);
+        if (!worker.allowedTools.length || worker.allowedTools.some(name => !tools.has(name) || name === 'bash')) {
+            throw registryError('forbidden', 'Worker tools exceed the staged-artifact policy.');
+        }
+        const key = randomUUID();
+        const opening = this.open({ cwd: manager.getCwd(), sessionDir: dirname(path), target: { kind: 'resume', sessionFile: path },
+            parentSessionId: parent, rootSessionId: owner.root, policy: this.getPolicy(parent),
+            extensionPaths: this.options.store.sessionMetadata(owner.root).profile?.extensionPaths ?? [], allowedTools: worker.allowedTools, worker });
+        this.opening.set(key, opening);
+        try {
+            return await opening;
+        }
+        finally {
+            this.opening.delete(key);
+        }
+    }
+    async runWorker(id, operation) {
+        this.assertNewWork();
+        this.assertDispatch(id);
+        const entry = this.require(id);
+        if (!entry.binding.runtime.session.isIdle || entry.writers.size)
+            throw registryError('busy', 'Worker is already running.');
+        const work = Promise.resolve().then(() => { this.assertDispatch(id); return operation(); });
+        const settled = work.then(() => { }, () => { });
+        entry.writers.add(settled);
+        try {
+            return await work;
+        }
+        finally {
+            entry.writers.delete(settled);
+            entry.projection.refresh();
+        }
+    }
+    async validateConfiguration(request, resources) {
+        if (!request.extensionConfigOverrides?.length)
+            return;
+        this.assertAdmission();
+        if (!this.options.lifecycle.validateConfiguration)
+            throw registryError('unavailable', 'The lifecycle cannot validate session configuration before execution.');
+        const resolved = resources ?? await this.options.lifecycle.resolveResources({ cwd: request.cwd, ...(request.sessionDir ? { sessionDir: request.sessionDir } : {}) });
+        const services = this.options.services({ request, getExecutionPolicy: () => request.policy ?? { mode: 'host-default', generation: 0 } });
+        await this.options.lifecycle.validateConfiguration(resolved, request.extensionConfigOverrides, packages => services.extensions.configuration(packages));
+        this.assertAdmission();
+    }
+    /** A custom session directory becomes an owned, remembered store root only once a request using it has been validated. */
+    async ownSessionDirectory(resources) {
+        await this.options.owner.ownRoot(resources.sessionDir);
+        this.assertAdmission();
+    }
+    assertClientSessionDirectory(resources) {
+        this.assertAdmission();
+        const path = canonicalProspectivePath(resources.sessionDir);
+        const reserved = [this.options.store.directory, this.options.owner.target.runtimeDirectory,
+            resources.sessionStorageBase, resources.agentStorageRoot,
+            ...resources.writableRoots.filter(root => root !== resources.sessionDir)];
+        if (path === resources.agentDir || reserved.some(root => pathInside(root, path)))
+            throw registryError('forbidden', 'Client session directory is reserved for daemon state.');
+    }
+    restore(id, context = {}) {
+        this.assertAdmission();
+        const stored = this.options.store.findSessionMetadata(id);
+        if (!stored)
+            throw registryError('not_found', 'Session is not registered.');
+        if (stored.deletedAt !== undefined)
+            throw registryError('not_found', 'Session was deleted.');
+        if (this.reloadAttachments.has(id) && this.opening.has(id))
+            return this.opening.get(id);
+        if (this.closing.has(id))
+            throw new Error('Session is closing.');
+        const entry = this.entries.get(id);
+        if (entry?.disposing)
+            return entry.disposing.then(() => this.restore(id, context));
+        if (entry)
+            return Promise.resolve(entry.binding);
+        const pending = this.opening.get(id);
+        if (pending)
+            return pending;
+        const reopening = stored.state === 'closed';
+        if (reopening)
+            this.options.store.updateSession(id, { state: 'open' });
+        const operation = this.open({ cwd: stored.cwd, sessionDir: directoryOf(stored.piPath), target: { kind: 'resume', sessionFile: stored.piPath },
+            rootSessionId: stored.root, ...(stored.parent ? { parentSessionId: stored.parent } : {}), policy: profilePolicy(stored), ...profileOptions(stored.profile), ...context }, stored)
+            .catch(error => {
+            // A failed reopen leaves the session closed, as it was before.
+            if (reopening && !this.failure && !this.entries.has(id) && this.options.store.sessionMetadata(id).state === 'open')
+                this.options.store.transitionSessionForSafety(id, 'closed');
+            throw error;
+        });
+        this.opening.set(id, operation);
+        void operation.then(() => this.opening.delete(id), () => this.opening.delete(id));
+        return operation;
+    }
+    /** Unregistered pre-daemon transcripts that `adopt` can register in place. */
+    async legacySessions(cwd, fresh = false) {
+        this.assertAdmission();
+        const now = Date.now();
+        // Paged listings share one short-lived index pass. A scan cannot narrow by cwd, so the filter applies after it.
+        if (fresh || !this.legacyListing || this.legacyListing.expires <= now) {
+            this.legacyListing = { expires: now + 2_000, value: this.legacy.discover(this.options.store.sessionMetadatas()) };
+        }
+        const rows = await this.legacyListing.value;
+        const current = this.options.store.sessionMetadatas();
+        const ids = new Set(current.map(session => session.id));
+        const paths = new Set(current.map(session => session.piPath));
+        return rows.filter(row => !ids.has(row.id) && !paths.has(row.path) && (cwd === undefined || row.cwd === cwd));
+    }
+    legacySummary(row) { return this.legacy.summary(row); }
+    /** Reads the titles of listed pre-daemon transcripts, newest first, so the first listing rarely waits for them. */
+    async warmLegacySessions(signal) {
+        this.assertAdmission();
+        await this.legacy.warm(await this.legacySessions(), signal);
+    }
+    /** Registers a discovered pre-daemon transcript under its existing ID and file; later turns append to that file. */
+    adopt(id, profile) {
+        this.assertNewWork();
+        if (this.options.store.findSessionMetadata(id))
+            return this.restore(id);
+        const pending = this.opening.get(id);
+        if (pending)
+            return pending;
+        const operation = (async () => {
+            const legacy = (await this.legacySessions(undefined, true)).find(row => row.id === id);
+            if (!legacy)
+                throw registryError('not_found', 'Session is not registered.');
+            this.assertNewWork();
+            return this.open({ cwd: legacy.cwd, sessionDir: dirname(legacy.path), target: { kind: 'resume', sessionFile: legacy.path }, clientRoot: true, ...profile });
+        })();
+        this.opening.set(id, operation);
+        void operation.then(() => this.opening.delete(id), () => this.opening.delete(id));
+        return operation;
+    }
+    /** First user message for session listings. Transcripts only grow, so a found preview is cached for the daemon's lifetime. */
+    async preview(session) {
+        const cached = this.previews.get(session.id);
+        if (cached)
+            return cached;
+        const live = this.entries.get(session.id)?.binding.runtime.session.sessionManager;
+        const preview = live ? transcriptPreview(live.getEntries()) : await readTranscriptPreview(session.piPath);
+        if (preview)
+            this.previews.set(session.id, preview);
+        return preview;
+    }
+    list() { return this.options.store.sessionMetadatas().filter(session => session.deletedAt === undefined); }
+    /** Sessions clients list and count. A draft appears with its first message. */
+    listed() { return this.list().filter(session => !session.draft); }
+    binding(id) { return this.entries.get(id)?.binding; }
+    projection(id) { return this.require(id).projection; }
+    async refreshModelAvailability(signal) {
+        this.assertAdmission();
+        signal.throwIfAborted();
+        const work = [...this.entries].filter(([id, entry]) => !this.closing.has(id) && !entry.disposing).map(async ([, entry]) => {
+            const refresh = entry.binding.runtime.session.modelRuntime.getAvailable(undefined, { signal });
+            const settled = refresh.then(() => { }, () => { });
+            entry.writers.add(settled);
+            try {
+                await refresh;
+                signal.throwIfAborted();
+                this.options.owner.assertCurrent();
+                entry.projection.refresh();
+            }
+            finally {
+                entry.writers.delete(settled);
+            }
+        });
+        const results = await Promise.allSettled(work);
+        const failure = results.find(result => result.status === 'rejected');
+        if (failure?.status === 'rejected')
+            throw failure.reason;
+    }
+    recordResource(resource, change) {
+        const commit = this.options.store.putResource(resource);
+        if (change)
+            this.publish({ v: 1, session: commit.value.session, rev: commit.revisions[commit.value.session], change });
+    }
+    getPolicy(id) { return profilePolicy(this.options.store.sessionMetadata(id)); }
+    bindCommandDispatcher(available) {
+        if (this.commandDispatcher)
+            throw new Error('A command dispatcher is already bound.');
+        this.commandDispatcher = available;
+        try {
+            for (const entry of this.entries.values())
+                entry.projection.refresh();
+        }
+        catch (error) {
+            this.commandDispatcher = undefined;
+            throw error;
+        }
+        return () => { if (this.commandDispatcher === available)
+            this.commandDispatcher = undefined; };
+    }
+    async attach(id, metadata) {
+        await this.restore(id);
+        this.assertAdmission();
+        const entry = this.require(id);
+        const attachment = randomUUID();
+        const snapshot = entry.projection.snapshot();
+        entry.attachments.set(attachment, { ...metadata });
+        return { attachment, snapshot };
+    }
+    detach(id, attachment) {
+        const entry = this.entries.get(id);
+        if (!entry) {
+            this.reloadAttachments.get(id)?.delete(attachment);
+            return;
+        }
+        const kind = entry.attachments.get(attachment)?.kind;
+        if (entry.attachments.delete(attachment) && !entry.attachments.size)
+            entry.lastDetached = this.now();
+        if (kind === 'acp' && !this.stopping && !this.failure)
+            this.relaxPolicy(this.options.store.sessionMetadata(id).root);
+    }
+    attachmentCount(id) { return this.entries.get(id)?.attachments.size ?? this.reloadAttachments.get(id)?.size ?? 0; }
+    subscribe(id, listener) {
+        this.require(id).projection.refresh();
+        const listeners = this.listeners.get(id) ?? new Set();
+        listeners.add(listener);
+        this.listeners.set(id, listeners);
+        return () => { listeners.delete(listener); if (!listeners.size)
+            this.listeners.delete(id); };
+    }
+    observe(listener, lifecycle) {
+        this.observers.set(listener, lifecycle);
+        return () => { this.observers.delete(listener); };
+    }
+    registerService(id, service) {
+        const entry = this.require(id);
+        entry.services.add(service);
+        return () => entry.services.delete(service);
+    }
+    registerUiActions(id, prepare) {
+        const entry = this.require(id);
+        if (entry.prepareUiAction)
+            throw new Error('Session UI actions are already bound.');
+        entry.prepareUiAction = prepare;
+        return () => { if (entry.prepareUiAction === prepare)
+            delete entry.prepareUiAction; };
+    }
+    prepareUiAction(id, request) {
+        const entry = this.require(id);
+        const prepare = entry.prepareUiAction;
+        if (!prepare)
+            throw registryError('unavailable', 'Session UI actions are unavailable.');
+        const execute = prepare(request);
+        if (request.outcome !== 'cancel')
+            return execute;
+        return async (context) => {
+            const controller = new AbortController();
+            const signal = AbortSignal.any([context.signal, controller.signal]);
+            const actions = entry.viewActions ??= new Set();
+            actions.add(controller);
+            let onAbort;
+            const aborted = new Promise((_resolve, reject) => {
+                onAbort = () => reject(signal.reason);
+                signal.addEventListener('abort', onAbort, { once: true });
+            });
+            try {
+                signal.throwIfAborted();
+                await Promise.race([execute({ ...context, signal }), aborted]);
+            }
+            finally {
+                signal.removeEventListener('abort', onAbort);
+                actions.delete(controller);
+            }
+        };
+    }
+    executionHost(id) {
+        const existing = this.entries.get(id)?.host;
+        if (existing instanceof ExecutionHost)
+            return existing;
+        const root = this.options.store.sessionMetadata(id).root;
+        let manager = this.executionManagers.get(root);
+        if (!manager) {
+            manager = new RegistryExecutions(this, root);
+            this.executionManagers.set(root, manager);
+        }
+        return manager.host(id);
+    }
+    async runAdmitted(requestId, id, origin, effect) {
+        this.assertNewWork();
+        this.assertDispatch(id);
+        const entry = this.require(id);
+        const stored = this.options.store.sessionMetadata(id);
+        if (stored.state !== 'open' || stored.execution && !stored.execution.completedAt || this.closing.has(id) || this.copyClaims.has(stored.piPath) || this.running(id))
+            throw registryError('busy', 'Wait for the current run to finish.');
+        const request = this.options.store.request(requestId);
+        if (request?.session !== id)
+            throw new Error('Admitted request belongs to another session.');
+        const run = { state: 'running', id: randomUUID(), origin };
+        let finish;
+        const writer = new Promise(resolve => { finish = resolve; });
+        entry.writers.add(writer);
+        entry.dispatches.add(requestId);
+        entry.projection.setOrigin(origin);
+        if (request.op === 'command.invoke')
+            entry.command = { runId: run.id, views: new Set() };
+        try {
+            entry.projection.syncCursor();
+            this.commitDispatch(requestId, id);
+            entry.projection.publish({ type: 'run.updated', run }, { run });
+            this.assertDispatch(id);
+            return await effect(entry.binding.runtime.session);
+        }
+        finally {
+            try {
+                entry.dispatches.delete(requestId);
+                if (entry.command?.runId === run.id)
+                    delete entry.command;
+                if (!this.failure) {
+                    if (!entry.cancelling)
+                        entry.projection.settleRun(run.id);
+                    entry.projection.refresh();
+                }
+            }
+            catch (error) {
+                this.fence(error);
+                throw error;
+            }
+            finally {
+                entry.writers.delete(writer);
+                finish();
+            }
+        }
+    }
+    async resumeInteraction(id, answer, continuationId, dispatch) {
+        await this.restore(id);
+        this.assertDispatch(id);
+        const entry = this.require(id);
+        const stored = this.options.store.sessionMetadata(id);
+        if (this.closing.has(id) || this.copyClaims.has(stored.piPath) || this.running(id))
+            throw registryError('busy', 'Session is busy.');
+        const continuation = this.options.store.snapshot().continuations.find(item => item.id === continuationId);
+        if (!continuation || continuation.session !== id || continuation.phase !== 'ready')
+            throw registryError('already_resolved', 'Continuation is no longer ready.');
+        const origin = { kind: 'automation', source: `interaction:${continuation.interaction}` };
+        const run = { state: 'running', id: continuationId, origin };
+        let finish;
+        const writer = new Promise(resolve => { finish = resolve; });
+        entry.writers.add(writer);
+        entry.dispatches.add(continuationId);
+        entry.projection.setOrigin(origin);
+        try {
+            entry.projection.syncCursor();
+            dispatch();
+            entry.projection.publish({ type: 'run.updated', run }, { run });
+            this.assertDispatch(id);
+            await entry.binding.runtime.session.prompt(`A previously deferred question was answered:\n${JSON.stringify(answer)}`);
+        }
+        finally {
+            try {
+                entry.dispatches.delete(continuationId);
+                if (!this.failure) {
+                    if (!entry.cancelling)
+                        entry.projection.settleRun(run.id);
+                    entry.projection.refresh();
+                }
+            }
+            catch (error) {
+                this.fence(error);
+                throw error;
+            }
+            finally {
+                entry.writers.delete(writer);
+                finish();
+            }
+        }
+    }
+    async mutateAdmitted(requestId, id, effect) {
+        const entry = this.require(id);
+        const request = this.options.store.request(requestId);
+        if (request?.session !== id || !nonRunMutations.has(request.op))
+            throw new Error('Request is not a supported non-run mutation for this session.');
+        let active = true;
+        const assertCurrent = () => {
+            if (!active)
+                throw new Error('Mutation dispatch has settled.');
+            this.assertDispatch(id);
+            if (this.entries.get(id) !== entry)
+                throw new Error('Session runtime changed.');
+        };
+        assertCurrent();
+        if (entry.dispatches.has(requestId))
+            throw new Error('Request is already executing.');
+        let finish;
+        const writer = new Promise(resolve => { finish = resolve; });
+        entry.writers.add(writer);
+        entry.dispatches.add(requestId);
+        try {
+            this.commitDispatch(requestId, id);
+            assertCurrent();
+            return await effect({ session: entry.binding.runtime.session, assertCurrent });
+        }
+        finally {
+            active = false;
+            entry.dispatches.delete(requestId);
+            try {
+                if (!this.failure) {
+                    if (!entry.cancelling)
+                        entry.projection.settleRun(this.options.store.sessionMetadata(id).run.id);
+                    entry.projection.refresh();
+                }
+            }
+            catch (error) {
+                this.fence(error);
+                throw error;
+            }
+            finally {
+                entry.writers.delete(writer);
+                finish();
+            }
+        }
+    }
+    commitDispatch(requestId, id) {
+        const commit = this.options.store.markDispatched(requestId);
+        const stored = this.options.store.sessionMetadata(id);
+        if (commit.revisions[id] !== stored.revision || Object.keys(commit.revisions).some(session => session !== id)) {
+            throw new Error('Dispatch checkpoint does not match the committed session revision.');
+        }
+        // Dispatch intent advances the revision before execution changes the run state.
+        this.publish({ v: 1, session: id, rev: stored.revision, change: { type: 'run.updated', run: stored.run } });
+    }
+    publishCommitted(revisions) {
+        for (const [id, revision] of Object.entries(revisions)) {
+            const stored = this.options.store.sessionMetadata(id);
+            if (stored.revision !== revision)
+                throw new Error('Checkpoint differs from the committed revision.');
+            if (this.entries.has(id))
+                this.publish({ v: 1, session: id, rev: revision, change: { type: 'run.updated', run: stored.run } });
+        }
+    }
+    subscribeInteractions(listener) {
+        this.interactionListeners.add(listener);
+        return () => this.interactionListeners.delete(listener);
+    }
+    publishInteraction(interaction, revisions) {
+        if (interaction.scope.kind === 'host') {
+            for (const listener of this.interactionListeners)
+                listener(structuredClone(interaction));
+            return;
+        }
+        const id = interaction.scope.session;
+        const revision = revisions[id];
+        if (revision !== this.options.store.sessionMetadata(id).revision)
+            throw new Error('Interaction differs from its committed revision.');
+        this.publish({ v: 1, session: id, rev: revision, change: {
+                type: interaction.state === 'waiting' || interaction.state === 'deferred' ? 'interaction.requested' : 'interaction.resolved', interaction,
+            } });
+    }
+    subscribeInvalidation(listener) {
+        this.invalidationListeners.add(listener);
+        return () => { this.invalidationListeners.delete(listener); };
+    }
+    /** Closes the session tree if needed, then deletes every transcript in it and records tombstones for request retries. */
+    deleteAdmitted(requestId, id) {
+        this.assertAdmission();
+        const tree = this.descendants(id).map(session => this.options.store.sessionMetadata(session));
+        const paths = tree.map(session => session.piPath);
+        if (paths.some(path => this.reservations.has(path)))
+            throw registryError('busy', 'Session has a lifecycle operation in progress.');
+        const token = Symbol('deletion');
+        for (const path of paths)
+            this.reservations.set(path, { token, id });
+        const work = (async () => {
+            await this.close(id);
+            this.assertAdmission();
+            const removals = paths.map(path => prepareTranscriptDeletion(this.options.owner, path));
+            const commit = this.options.store.markSessionDeleted(requestId);
+            for (const session of tree)
+                this.previews.delete(session.id);
+            this.publishCommitted(commit.revisions);
+            for (const session of tree)
+                for (const lifecycle of this.observers.values()) {
+                    try {
+                        lifecycle?.(session.id);
+                    }
+                    catch { }
+                }
+            for (const remove of removals)
+                remove();
+        })().finally(() => { for (const path of paths)
+            if (this.reservations.get(path)?.token === token)
+                this.reservations.delete(path); });
+        return this.trackLifecycle(work);
+    }
+    /** The session and every registered descendant, parents before children. */
+    descendants(id) {
+        const rows = this.list();
+        const tree = [id];
+        for (let index = 0; index < tree.length; index++)
+            for (const row of rows)
+                if (row.parent === tree[index] && !tree.includes(row.id))
+                    tree.push(row.id);
+        return tree;
+    }
+    /** Applies session configuration now when the root can reload; otherwise persists it for the next reload or resume. */
+    configureAdmitted(requestId, id, configuration) {
+        try {
+            return this.reloadAdmitted(requestId, id, configuration).then(() => undefined);
+        }
+        catch (error) {
+            if (!['busy', 'unavailable'].includes(error.code))
+                throw error;
+        }
+        this.assertAdmission();
+        const commit = this.options.store.configureSession(requestId, configuration.values, configuration.overrides);
+        this.publishCommitted(commit.revisions);
+        return Promise.resolve();
+    }
+    reloadAdmitted(requestId, id, configuration) {
+        this.assertDispatch(id);
+        const stored = this.options.store.sessionMetadata(id);
+        const entry = this.entries.get(id);
+        const request = this.options.store.request(requestId);
+        if (request?.op !== (configuration ? 'config.set' : 'session.reload') || request.session !== id || request.phase !== 'intent')
+            throw registryError('request_conflict', 'Reload request differs.');
+        if (stored.parent)
+            throw registryError('unavailable', 'Only root sessions can reload.');
+        if (!['idle', 'interrupted'].includes(stored.run.state) || entry && this.running(id))
+            throw registryError('busy', 'Wait for the current run to finish before reloading.');
+        if (this.opening.has(id) || entry?.disposing || entry?.cancelling || entry?.writers.size)
+            throw registryError('busy', 'Session has a lifecycle operation in progress.');
+        const token = Symbol('reload');
+        this.reservations.set(stored.piPath, { token, id });
+        const attachments = entry?.attachments ?? new Map();
+        this.reloadAttachments.set(id, attachments);
+        const work = (async () => {
+            try {
+                if (configuration)
+                    this.options.store.configureSession(requestId, configuration.values, configuration.overrides);
+                else
+                    this.commitDispatch(requestId, id);
+                this.settleInteractions(id, 'cancel');
+                // Like Pi's /reload, only the root runtime reloads: busy children and queued executions keep running and deliver to the next root runtime.
+                for (const [child, value] of [...this.entries]) {
+                    if (child !== id && value.binding.rootSessionId === id && !value.disposing && !this.childBusy(child, value))
+                        await this.disposeEntry(child, false, { keepTerminals: true });
+                }
+                if (entry)
+                    await this.disposeEntry(id, false, { preserveView: true, keepTerminals: true, keepExecutions: true });
+                this.assertAdmission();
+                if (this.closing.has(id) || this.options.store.sessionMetadata(id).state !== 'open')
+                    throw new RegistryOpeningCancelled('Session closed during reload.');
+                this.pathClaims.add(stored.piPath);
+                const current = this.options.store.sessionMetadata(id);
+                const binding = await this.open({ cwd: current.cwd, sessionDir: dirname(current.piPath), target: { kind: 'resume', sessionFile: current.piPath },
+                    rootSessionId: current.root, policy: profilePolicy(current), ...profileOptions(current.profile) }, current, undefined, token);
+                const reloaded = this.require(id);
+                reloaded.attachments = attachments;
+                reloaded.host?.resumeQueued();
+                const revisions = { [id]: this.options.store.sessionMetadata(id).revision };
+                for (const listener of this.invalidationListeners)
+                    listener(revisions);
+                return binding;
+            }
+            catch (error) {
+                if (!this.entries.has(id) && !this.failure) {
+                    try {
+                        const current = this.options.store.sessionMetadata(id);
+                        if (current.state === 'open' && current.residency !== 'evicted')
+                            this.options.store.transitionSessionForSafety(id, 'evicted');
+                    }
+                    catch (cleanup) {
+                        this.fence(cleanup);
+                        throw new AggregateError([error, cleanup], 'Reload failed while restoring evicted state.');
+                    }
+                }
+                throw error;
+            }
+            finally {
+                this.reloadAttachments.delete(id);
+                this.reservations.delete(stored.piPath);
+                if (!this.entries.has(id))
+                    this.pathClaims.delete(stored.piPath);
+            }
+        })();
+        this.opening.set(id, work);
+        void work.then(() => this.opening.delete(id), () => this.opening.delete(id));
+        return this.trackLifecycle(work);
+    }
+    trackLifecycle(work) {
+        this.lifecycleWriters.add(work);
+        void work.then(() => this.lifecycleWriters.delete(work), () => this.lifecycleWriters.delete(work));
+        return work;
+    }
+    cancelAdmitted(requestId, id, runId) {
+        this.assertAdmission();
+        if (!this.entries.has(id))
+            throw registryError('not_found', 'Cancel session is not resident.');
+        const request = this.options.store.request(requestId);
+        if (request?.session !== id || request.op !== 'cancel')
+            throw registryError('request_conflict', 'Cancel request belongs to another operation or session.');
+        if (runId && this.options.store.sessionMetadata(id).run.id !== runId)
+            throw registryError('not_found', 'Run not found.');
+        this.commitDispatch(requestId, id);
+        return this.cancel(id, runId);
+    }
+    closeAdmitted(requestId, id) {
+        this.assertAdmission();
+        const request = this.options.store.request(requestId);
+        if (request?.session !== id || request.op !== 'close')
+            throw new Error('Close request belongs to another operation or session.');
+        this.commitDispatch(requestId, id);
+        return this.close(id);
+    }
+    async forkAdmitted(requestId, id, from) {
+        return this.copyAdmitted(requestId, id, from);
+    }
+    async cloneAdmitted(requestId, id) {
+        return this.copyAdmitted(requestId, id);
+    }
+    async copyAdmitted(requestId, id, from) {
+        await this.restore(id);
+        this.assertDispatch(id);
+        const source = this.require(id);
+        const stored = this.options.store.sessionMetadata(id);
+        const request = this.options.store.request(requestId);
+        if (request?.session !== id || request.op !== (from ? 'fork' : 'session.clone'))
+            throw new Error('Copy request belongs to another operation or session.');
+        const path = this.options.owner.assertOwnsPath(stored.piPath);
+        this.copyClaims.add(path);
+        let finish;
+        const writer = new Promise(resolve => { finish = resolve; });
+        source.writers.add(writer);
+        source.dispatches.add(requestId);
+        try {
+            let target = { kind: 'clone', sourceSessionFile: path };
+            if (from) {
+                const choices = source.binding.runtime.session.getUserMessagesForForking();
+                const choice = from.kind === 'entry' ? choices.find(item => item.entryId === from.entryId)
+                    : Number.isSafeInteger(from.position) && from.position >= 0 ? choices[from.position] : undefined;
+                if (!choice)
+                    throw new Error('Fork selector does not identify a stored user message.');
+                target = { kind: 'fork', sourceSessionFile: path, entryId: choice.entryId, position: 'before' };
+            }
+            this.commitDispatch(requestId, id);
+            this.assertAdmission();
+            if (this.closing.has(id) || this.closing.has(stored.root))
+                throw new Error('Source session is closing.');
+            const key = randomUUID();
+            const opening = this.open({ cwd: stored.cwd, sessionDir: directoryOf(path), ...profileOptions(stored.profile),
+                target }, undefined, path);
+            this.opening.set(key, opening);
+            try {
+                return await opening;
+            }
+            finally {
+                this.opening.delete(key);
+            }
+        }
+        finally {
+            this.copyClaims.delete(path);
+            source.dispatches.delete(requestId);
+            source.writers.delete(writer);
+            finish();
+        }
+    }
+    async cancel(id, runId) {
+        this.assertAdmission();
+        const entry = this.require(id);
+        if (entry.disposing)
+            throw new Error('Session runtime is being evicted.');
+        const stored = this.options.store.sessionMetadata(id);
+        if (runId && stored.run.id !== runId)
+            throw registryError('not_found', 'Run not found.');
+        if (entry.cancelling)
+            return entry.cancelling;
+        if (['idle', 'interrupted'].includes(stored.run.state) && entry.binding.runtime.session.isIdle)
+            return;
+        const operation = Promise.resolve().then(async () => {
+            entry.projection.transitionForSafety('cancelling', stored.run.id);
+            this.settleInteractions(id, 'cancel');
+            await this.cancelViews(id);
+            await entry.binding.runtime.session.abort();
+            await this.processes.cancelForeground(id);
+            await this.join([...entry.writers]);
+            this.options.owner.assertCurrent();
+            if (!entry.binding.runtime.session.isIdle)
+                throw new Error('Cancelled session has not settled.');
+            entry.projection.transitionForSafety('idle', stored.run.id);
+            entry.projection.refresh();
+        });
+        entry.cancelling = operation;
+        try {
+            await operation;
+        }
+        catch (error) {
+            this.cancellationFailures.add(error);
+            throw error;
+        }
+        finally {
+            delete entry.cancelling;
+            if (!this.draining && !this.stopping && !this.closing.has(id))
+                delete entry.viewCancellation;
+        }
+        if (!this.stopping && !this.failure && !this.closing.has(id) && !this.closing.has(stored.root))
+            this.entries.get(stored.root)?.host?.resumeQueued();
+    }
+    /** Applies ACP approval policy to the open session tree; running tool calls keep the approvals they already had. */
+    tightenPolicy(root) { this.setPolicy(root, 'acp-strict'); }
+    /** Returns the session tree to host defaults once no ACP client is attached to it. */
+    relaxPolicy(root) {
+        const tree = this.list().filter(item => item.root === root);
+        if (tree.some(item => [...this.entries.get(item.id)?.attachments.values() ?? []].some(attachment => attachment.kind === 'acp')))
+            return;
+        this.setPolicy(root, 'host-default');
+    }
+    setPolicy(root, effective) {
+        this.assertAdmission();
+        for (const stored of this.list().filter(item => item.root === root && item.state === 'open')) {
+            if (stored.policy.effective !== effective)
+                this.policyUpdate(stored.id, { effective, generation: stored.policy.generation + 1 });
+        }
+    }
+    async evictIdle() {
+        this.assertAdmission();
+        const evicted = [];
+        const idle = this.options.idleMs ?? 60_000;
+        for (const [id, entry] of this.entries) {
+            if (this.closing.has(id) || entry.disposing || entry.attachments.size || this.hasWarmChildren(id) || this.now() - entry.lastDetached < idle || this.busy(id))
+                continue;
+            if (this.options.store.sessionMetadata(id).draft && await this.discardDraft(id)) {
+                evicted.push(id);
+                continue;
+            }
+            await this.disposeEntry(id, false);
+            evicted.push(id);
+        }
+        // A draft that was not resident at startup gets its idle window from startup, so a reconnecting client keeps it.
+        for (const row of this.list()) {
+            if (!row.draft || this.entries.has(row.id) || this.opening.has(row.id) || this.closing.has(row.id) || this.now() - Math.max(row.updatedAt, this.startedAt) < idle)
+                continue;
+            if (await this.discardDraft(row.id))
+                evicted.push(row.id);
+        }
+        return evicted;
+    }
+    /**
+     * Removes a draft with no conversation, children, pending interaction or running process. Any other draft becomes a normal session.
+     * A draft that changed during the check is left for a later pass.
+     */
+    async discardDraft(id) {
+        const entry = this.entries.get(id);
+        const conversation = entry ? entry.binding.runtime.session.sessionManager.getEntries().some(isConversationEntry) : await transcriptHasConversation(this.options.store.sessionMetadata(id).piPath);
+        // The transcript read yields, so an attach, deletion or other lifecycle operation may have started meanwhile.
+        const stored = this.options.store.findSessionMetadata(id);
+        if (!stored?.draft || stored.deletedAt !== undefined || this.entries.get(id) !== entry || this.opening.has(id) || this.closing.has(id)
+            || this.reservations.has(stored.piPath) || this.copyClaims.has(stored.piPath))
+            return false;
+        const engaged = this.list().some(row => row.parent === id)
+            || this.options.store.interactions().some(item => item.scope.kind === 'session' && item.scope.session === id && (item.state === 'waiting' || item.state === 'deferred'))
+            || this.processes.blocksEviction(stored.root);
+        if (conversation || engaged) {
+            if (entry)
+                entry.projection.materialize();
+            else
+                this.options.store.updateSession(id, { draft: false });
+            return false;
+        }
+        this.closing.add(id);
+        try {
+            if (entry)
+                await this.disposeEntry(id, false);
+            const remove = prepareTranscriptDeletion(this.options.owner, stored.piPath);
+            const commit = this.options.store.discardDraft(id);
+            this.previews.delete(id);
+            this.publishCommitted(commit.revisions);
+            remove();
+            return true;
+        }
+        finally {
+            this.closing.delete(id);
+        }
+    }
+    close(id) {
+        this.options.owner.assertCurrent();
+        const stored = this.options.store.sessionMetadata(id);
+        const pending = this.closes.get(id);
+        if (pending)
+            return pending;
+        if (stored.state === 'closed')
+            return Promise.resolve();
+        this.closing.add(id);
+        const rows = this.list();
+        const descendants = new Set([id]);
+        for (let changed = true; changed;) {
+            changed = false;
+            for (const row of rows)
+                if (row.parent && descendants.has(row.parent) && !descendants.has(row.id)) {
+                    descendants.add(row.id);
+                    changed = true;
+                }
+        }
+        for (const descendant of descendants)
+            this.processes.seal(descendant);
+        const operation = this.processes.withCleanup([...descendants], () => this.performClose(id));
+        this.closes.set(id, operation);
+        void operation.then(() => { this.closes.delete(id); this.closing.delete(id); }, () => { });
+        return operation;
+    }
+    async performClose(id) {
+        await this.join([...this.opening.values()], undefined, true);
+        await this.entries.get(id)?.disposing;
+        const stored = this.options.store.sessionMetadata(id);
+        if (stored.state === 'closed')
+            return;
+        const descendants = this.list().filter(item => item.parent === id && item.state === 'open');
+        // Host shutdown cancels its full descendant tree and waits beyond terminal status records.
+        const entry = this.entries.get(id);
+        this.settleInteractions(id, 'close');
+        if (entry)
+            await this.cancelViews(id);
+        await entry?.host?.shutdown();
+        for (const child of descendants)
+            await this.close(child.id);
+        if (entry) {
+            await entry.cancelling;
+            await entry.binding.runtime.session.abort();
+            await this.processes.cancelForeground(id);
+            await Promise.all(entry.writers);
+            entry.projection.settleRun(this.options.store.sessionMetadata(id).run.id);
+            await this.processes.settle(stored.root, false, id === stored.root ? undefined : new Set([id]));
+            for (const service of entry.services)
+                await this.processes.withCleanup(id, () => service.settle());
+            await this.disposeEntry(id, true);
+        }
+        else {
+            this.options.store.transitionSessionForSafety(id, 'closed');
+        }
+    }
+    async shutdown(options = {}) {
+        if (options.interrupt)
+            for (const row of this.list()) {
+                if (row.state === 'open' && ['running', 'waiting', 'cancelling'].includes(row.run.state) && row.run.id)
+                    this.shutdownInterruptions.set(row.id, row.run.id);
+            }
+        this.stopping = true;
+        if (this.failure) {
+            await shutdownStep('registry-fenced', async () => { await this.failureSettlement; throw new Error('Registry is fenced; verify settlement before releasing ownership.'); });
+        }
+        const cancellations = [...this.entries].map(([id, entry]) => {
+            if (!options.interrupt)
+                return shutdownStep('session-cancel-views', () => this.cancelViews(id), id);
+            this.closing.add(id);
+            return (async () => {
+                await shutdownStep('session-interactions', () => this.settleInteractions(id, 'shutdown'), id);
+                await this.join([shutdownStep('session-cancel-views', () => this.cancelViews(id), id),
+                    shutdownStep('session-host-shutdown', () => entry.host?.shutdown(), id),
+                    shutdownStep('session-abort', () => entry.runtimeDisposed ? undefined : entry.binding.runtime.session.abort(), id)]);
+            })();
+        });
+        const closing = this.join([...this.closes.values()], undefined, true).catch(error => {
+            // Failed closes retain their intent; force retries them after in-flight closes finish.
+            if (!options.interrupt || this.failure)
+                throw error;
+        });
+        await this.join([...cancellations, shutdownStep('registry-pending', () => this.join([...this.opening.values(), closing, ...this.lifecycleWriters], undefined, true))]);
+        if (this.failure)
+            await shutdownStep('registry-fenced', async () => { await this.failureSettlement; throw this.failure; });
+        if (options.interrupt) {
+            const retry = [...this.closes.keys()];
+            this.closes.clear();
+            await this.join(retry.map(id => shutdownStep('session-close', () => this.close(id), id)));
+        }
+        for (const [id, entry] of this.entries) {
+            this.closing.add(id);
+            await shutdownStep('session-interactions', () => this.settleInteractions(id, 'shutdown'), id);
+            if (!options.interrupt) {
+                await shutdownStep('session-cancel-views', () => this.cancelViews(id), id);
+                await shutdownStep('session-host-shutdown', () => entry.host?.shutdown(), id);
+                await shutdownStep('session-abort', async () => { await entry.cancelling; if (!entry.runtimeDisposed)
+                    await entry.binding.runtime.session.abort(); }, id);
+            }
+            await shutdownStep('session-cancel-foreground', () => this.processes.cancelForeground(id), id);
+            if (!options.interrupt)
+                await shutdownStep('session-writers', () => this.join([...entry.writers]), id);
+            await shutdownStep('session-processes', () => this.processes.settle(entry.binding.rootSessionId), id);
+            for (const service of entry.services) {
+                await shutdownStep('session-services', () => this.processes.withCleanup(id, async () => { await service.settle(); await service.dispose(); }), id);
+                entry.services.delete(service);
+            }
+            if (options.interrupt) {
+                if (!entry.runtimeDisposed) {
+                    await shutdownStep('session-runtime', () => this.processes.withCleanup(id, () => entry.binding.runtime.dispose()), id);
+                    entry.runtimeDisposed = true;
+                }
+                await shutdownStep('session-writers', async () => { await entry.cancelling; await this.join([...entry.writers]); }, id);
+            }
+            await shutdownStep('session-run', () => entry.projection.settleRun(this.options.store.sessionMetadata(id).run.id), id);
+            await shutdownStep('session-dispose', () => this.disposeEntry(id, false), id);
+        }
+        // A failed reload leaves its kept PTYs without a resident root.
+        await shutdownStep('live-roots', async () => { for (const root of this.processes.liveRoots())
+            await this.processes.settle(root); });
+        for (const [id, services] of this.retainedServices)
+            for (const service of services) {
+                await shutdownStep('retained-services', async () => { await service.settle(); await service.dispose(); }, id);
+                services.delete(service);
+            }
+        for (const [id, run] of this.shutdownInterruptions) {
+            await shutdownStep('session-run', () => { if (this.options.store.sessionMetadata(id).state === 'open')
+                this.options.store.interruptSessionRun(id, run); }, id);
+            this.shutdownInterruptions.delete(id);
+        }
+        this.retainedServices.clear();
+        this.lossUnsubscribe();
+        this.listeners.clear();
+        // The caller closes the store/profile and releases ownership only after this resolves.
+    }
+    busy(id) {
+        const entry = this.require(id);
+        const stored = this.options.store.sessionMetadata(id);
+        return this.copyClaims.has(stored.piPath) || this.reservations.has(stored.piPath) || !entry.binding.runtime.session.isIdle || entry.binding.runtime.session.pendingMessageCount > 0 || entry.dispatches.size > 0
+            || ['running', 'waiting', 'cancelling'].includes(stored.run.state) || !!entry.host?.hasPendingWork() || !!entry.host?.hasActiveJobs() || !!entry.host?.hasExecutingJobs()
+            || [...entry.services].some(service => !service.disposeWhenIdle || service.busy()) || this.processes.blocksEviction(stored.root)
+            || this.options.store.interactions().some(item => item.scope.kind === 'session' && item.scope.root === stored.root && item.state === 'waiting');
+    }
+    /** Whether a turn or admitted run is in progress, the condition Pi itself uses to defer conflicting work. */
+    running(id) {
+        const entry = this.entries.get(id);
+        return !!entry && (!entry.binding.runtime.session.isIdle || entry.dispatches.size > 0);
+    }
+    childBusy(id, entry) {
+        return this.running(id) || entry.writers.size > 0 || !!entry.host?.hasPendingWork() || !!entry.host?.hasActiveJobs()
+            || !['idle', 'interrupted'].includes(this.options.store.sessionMetadata(id).run.state);
+    }
+    hasWarmChildren(id) { return [...this.entries].some(([child, value]) => child !== id && value.binding.rootSessionId === id); }
+    async open(request, restored, copySource, reservation) {
+        const resources = await this.options.lifecycle.resolveResources({ cwd: request.cwd, ...(request.sessionDir ? { sessionDir: request.sessionDir } : {}) });
+        this.assertAdmission();
+        if (request.clientRoot)
+            this.assertClientSessionDirectory(resources);
+        await this.ownSessionDirectory(resources);
+        for (const path of resources.writableRoots)
+            this.options.owner.assertOwnsPath(path);
+        const sourcePath = request.target.kind === 'clone' || request.target.kind === 'fork' ? this.options.owner.assertOwnsPath(request.target.sourceSessionFile) : undefined;
+        const source = sourcePath ? this.list().find(item => item.piPath === sourcePath) : undefined;
+        const initialPolicy = request.parentSessionId ? this.getPolicy(request.rootSessionId) : source ? profilePolicy(source) : request.policy ?? { mode: 'host-default', generation: 0 };
+        let binding;
+        let claim;
+        let borrowed;
+        const openingPolicy = () => request.parentSessionId ? this.getPolicy(request.rootSessionId) : source ? this.getPolicy(source.id) : initialPolicy;
+        const externalServices = this.options.services({ request, getExecutionPolicy: () => binding && this.entries.has(binding.sessionId) ? this.getPolicy(binding.sessionId) : openingPolicy() });
+        const services = { ...externalServices, extensions: {
+                configuration: packages => externalServices.extensions.configuration(packages),
+                ...(externalServices.extensions.executionPort ? { executionPort: externalServices.extensions.executionPort } : {}),
+                bind: async (context, port) => {
+                    const scope = this.runtimeOpening.getStore()?.scope;
+                    if (scope) {
+                        scope.session = context.sessionManager.getSessionId();
+                        scope.root = context.rootSessionId;
+                    }
+                    const bindings = await externalServices.extensions.bind(context, port);
+                    return { ...bindings, inlineExtensions: [...(bindings.inlineExtensions ?? []), ...(request.systemPromptAppend ? [{
+                                    name: '@felan-ai/daemon/child-instructions',
+                                    factory: (pi) => { pi.on('before_agent_start', event => ({ systemPrompt: `${event.systemPrompt}\n\n${request.systemPromptAppend}` })); },
+                                }] : [])] };
+                },
+            } };
+        const ownership = { assertOwned: (resolved, target) => {
+                this.assertAdmission();
+                if (request.clientRoot)
+                    this.assertClientSessionDirectory({ ...resolved, sessionDir: target.destinationDirectory });
+                for (const path of resolved.writableRoots)
+                    this.options.owner.assertOwnsPath(path);
+                this.options.owner.assertOwnsPath(target.destinationDirectory);
+                if (target.sourceSessionFile) {
+                    const source = this.options.owner.assertOwnsPath(target.sourceSessionFile);
+                    if (claim === source || borrowed === source)
+                        return;
+                    const held = this.reservations.get(source);
+                    if (held) {
+                        if (held.token !== reservation)
+                            throw registryError('busy', 'Source has a lifecycle reservation.');
+                        claim = source;
+                        this.pathClaims.add(source);
+                        return;
+                    }
+                    if (source === copySource && this.copyClaims.has(source) && (target.kind === 'fork' || target.kind === 'clone')) {
+                        borrowed = source;
+                        return;
+                    }
+                    if (this.pathClaims.has(source))
+                        throw new Error('Session transcript already has a live writer.');
+                    this.pathClaims.add(source);
+                    claim = source;
+                }
+            } };
+        try {
+            binding = await this.runtimeOpening.run({}, () => this.options.lifecycle.openSession({ ...request, resources, ownership, policy: initialPolicy, services }));
+            this.assertAdmission();
+            if (restored && this.closing.has(restored.id) || request.parentSessionId && (this.closing.has(request.parentSessionId) || this.closing.has(request.rootSessionId)))
+                throw new RegistryOpeningCancelled('Session is closing.');
+            const manager = binding.runtime.session.sessionManager;
+            const initialPath = manager.getSessionFile();
+            if (initialPath && !existsSync(this.options.owner.assertOwnsPath(initialPath))) {
+                const path = this.options.owner.assertOwnsPath(initialPath);
+                const header = manager.getHeader();
+                if (!header || header.id !== binding.sessionId)
+                    throw new Error('Missing Pi session header.');
+                this.assertAdmission();
+                if (!existsSync(this.options.owner.assertOwnsPath(path))) {
+                    const rows = [header, ...manager.getEntries()];
+                    if (manager.getEntries().some(row => row.type === 'message' && ['user', 'assistant'].includes(row.message.role)))
+                        throw new Error('Conversation transcript was not persisted.');
+                    const bytes = rows.map(row => JSON.stringify(row)).join('\n') + '\n';
+                    const fd = openSync(this.options.owner.assertOwnsPath(path), constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+                    try {
+                        this.options.owner.assertCurrent();
+                        writeFileSync(fd, bytes);
+                        fsyncSync(fd);
+                    }
+                    finally {
+                        closeSync(fd);
+                    }
+                    const directory = openSync(dirname(path), constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+                    try {
+                        fsyncSync(directory);
+                    }
+                    finally {
+                        closeSync(directory);
+                    }
+                }
+                if (claim && claim !== path)
+                    this.pathClaims.delete(claim);
+                claim = path;
+                this.pathClaims.add(path);
+                // Reload the same manager so Pi appends to the header instead of creating it again on the first message.
+                manager.setSessionFile(this.options.owner.assertOwnsPath(path));
+            }
+            const actualPath = manager.getSessionFile();
+            if (!actualPath || manager.getSessionId() !== binding.sessionId || manager.getCwd() !== resources.cwd)
+                throw new Error('Lifecycle returned inconsistent session identity.');
+            const path = this.options.owner.assertOwnsPath(actualPath);
+            if (restored && (binding.sessionId !== restored.id || path !== restored.piPath || binding.rootSessionId !== restored.root))
+                throw new Error('Restored session identity changed.');
+            if (this.entries.has(binding.sessionId) || (this.pathClaims.has(path) && claim !== path))
+                throw new Error('Session already has a live writer.');
+            if (claim && claim !== path)
+                this.pathClaims.delete(claim);
+            claim = path;
+            this.pathClaims.add(path);
+            const effectivePolicy = openingPolicy();
+            if (!restored)
+                this.options.store.createSession({ id: binding.sessionId, root: binding.rootSessionId, ...(binding.parentSessionId ? { parent: binding.parentSessionId } : {}),
+                    ...(request.execution ? { execution: request.execution } : {}),
+                    cwd: resources.cwd, piPath: path, title: manager.getSessionName() ?? '', state: 'open', residency: 'warm', run: { state: 'idle' },
+                    ...(request.clientRoot === true && request.target.kind === 'new' ? { draft: true } : {}),
+                    policy: { effective: effectivePolicy.mode, generation: effectivePolicy.generation },
+                    branch: manager.getLeafId() ?? binding.sessionId, observedTip: sessionTip(manager),
+                    ...(binding.runtime.session.model ? { model: { provider: binding.runtime.session.model.provider, id: binding.runtime.session.model.id } } : {}), thinking: binding.runtime.session.thinkingLevel,
+                    ...(request.extensionPaths?.length || request.allowedTools?.length || request.extensionConfigOverrides?.length ? { profile: parseSchema(SessionProfileSchema, {
+                            ...(request.extensionPaths?.length ? { extensionPaths: request.extensionPaths } : {}),
+                            ...(request.allowedTools ? { allowedTools: request.allowedTools } : {}),
+                            ...(request.extensionConfigOverrides?.length ? { extensionConfigOverrides: request.extensionConfigOverrides } : {}),
+                        }) } : {}),
+                });
+            else
+                this.options.store.updateSession(binding.sessionId, { residency: 'warm' });
+            const projection = new SessionProjection({ binding, store: this.options.store, extras: () => this.extras(binding.sessionId), publish: event => this.publish(event), onError: error => { this.fence(error); },
+                commandAvailable: name => this.options.commandAvailable?.(binding.sessionId, name) === false ? false
+                    : this.commandDispatcher?.(binding.sessionId, name) ?? this.options.commandAvailable?.(binding.sessionId, name) ?? false,
+                canSettle: () => { const current = this.entries.get(binding.sessionId); return !current?.dispatches.size && !current?.cancelling; },
+                onRefresh: () => {
+                    const current = this.entries.get(binding.sessionId);
+                    if (current)
+                        this.updateCommandState(current);
+                },
+            });
+            const entry = { binding, projection, attachments: new Map(), dispatches: new Set(), writers: new Set(), services: this.retainedServices.get(binding.sessionId) ?? new Set(), lastDetached: this.now() };
+            this.retainedServices.delete(binding.sessionId);
+            this.entries.set(binding.sessionId, entry);
+            const host = this.executionHost(binding.sessionId);
+            host.activate();
+            entry.host = host;
+            const activation = { binding, active: true };
+            try {
+                await this.bindingActivation.run(activation, () => binding.activate?.());
+            }
+            finally {
+                activation.active = false;
+            }
+            this.assertAdmission();
+            if (this.closing.has(binding.sessionId) || request.parentSessionId && this.closing.has(request.parentSessionId))
+                throw new RegistryOpeningCancelled('Session closed during activation.');
+            // A restored root rediscovers jobs that outlived its previous runtime or daemon.
+            if (restored && !binding.parentSessionId)
+                await this.processes.refresh(binding.rootSessionId).catch(error => { this.fence(error); throw error; });
+            projection.refresh();
+            for (const resident of this.observers.values()) {
+                try {
+                    resident?.(binding.sessionId);
+                }
+                catch { }
+            }
+            if (borrowed)
+                this.copyClaims.delete(borrowed);
+            return binding;
+        }
+        catch (error) {
+            if (binding) {
+                const installed = this.entries.get(binding.sessionId);
+                if (installed && installed.binding === binding) {
+                    this.closing.add(binding.sessionId);
+                    installed.projection.dispose();
+                }
+                try {
+                    await this.processes.withCleanup(binding.sessionId, async () => {
+                        if (installed && installed.binding === binding) {
+                            this.settleInteractions(binding.sessionId, 'cancel');
+                            await installed.host?.shutdown();
+                            await installed.cancelling;
+                        }
+                        await binding.runtime.session.abort();
+                        if (installed && installed.binding === binding) {
+                            await this.join([...installed.writers]);
+                            await this.processes.settle(binding.rootSessionId, false, new Set([binding.sessionId]));
+                            for (const service of installed.services) {
+                                await service.settle();
+                                await service.dispose();
+                            }
+                        }
+                        await binding.runtime.dispose();
+                    });
+                    this.processes.revokeRuntime(binding.agentRuntime);
+                    if (installed && installed.binding === binding) {
+                        this.options.store.transitionSessionForSafety(binding.sessionId, 'idle');
+                        this.options.store.transitionSessionForSafety(binding.sessionId, 'evicted');
+                        this.entries.delete(binding.sessionId);
+                        this.closing.delete(binding.sessionId);
+                    }
+                }
+                catch (cleanup) {
+                    this.fence(cleanup);
+                    throw new AggregateError([error, cleanup], 'Registry opening cleanup failed; ownership remains held.');
+                }
+            }
+            if (claim)
+                this.pathClaims.delete(claim);
+            if (borrowed)
+                this.copyClaims.delete(borrowed);
+            throw error;
+        }
+    }
+    settleInteractions(id, reason) {
+        for (const interaction of this.options.store.interactions()) {
+            if (interaction.scope.kind !== 'session' || interaction.scope.session !== id || !['waiting', 'deferred'].includes(interaction.state))
+                continue;
+            const commit = reason === 'shutdown' && interaction.deferrable
+                ? this.options.store.deferInteraction(interaction.id)
+                : this.options.store.cancelInteraction(interaction.id, reason === 'shutdown' ? 'drain' : 'abort');
+            this.publish({ v: 1, session: id, rev: commit.revisions[id], change: { type: commit.value.state === 'deferred' ? 'interaction.requested' : 'interaction.resolved', interaction: commit.value } });
+        }
+    }
+    cancelViews(id) {
+        const entry = this.require(id);
+        if (entry.cancellingViews)
+            return entry.cancellingViews;
+        for (const controller of entry.viewActions ?? [])
+            controller.abort();
+        const cancellation = entry.viewCancellation ??= { attempted: new Set(), rounds: 0 };
+        const work = Promise.resolve().then(async () => {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), 250);
+            let aborted;
+            const deadline = new Promise(resolve => { aborted = resolve; });
+            controller.signal.addEventListener('abort', aborted, { once: true });
+            try {
+                for (;;) {
+                    const actions = entry.projection.presentations().flatMap(element => {
+                        if (element.kind !== 'view' && element.kind !== 'document' && element.kind !== 'progress')
+                            return [];
+                        const action = element.actions.find(action => action.target === 'element' && action.outcome === 'cancel');
+                        const key = JSON.stringify([element.id, element.revision]);
+                        if (!action || cancellation.attempted.has(key))
+                            return [];
+                        cancellation.attempted.add(key);
+                        return [{ elementId: element.id, revision: element.revision, actionId: action.id, outcome: action.outcome, values: {} }];
+                    });
+                    if (!actions.length)
+                        return;
+                    if (cancellation.rounds++ >= 8 || controller.signal.aborted) {
+                        for (const action of actions)
+                            this.viewCancellationDiagnostic(id, action.elementId, controller.signal.aborted ? 'timeout' : 'limit');
+                        return;
+                    }
+                    await Promise.all(actions.map(async (action) => {
+                        try {
+                            const execute = this.prepareUiAction(id, action);
+                            await Promise.race([execute({ requestId: randomUUID(), signal: controller.signal }), deadline]);
+                            if (controller.signal.aborted)
+                                this.viewCancellationDiagnostic(id, action.elementId, 'timeout');
+                        }
+                        catch (error) {
+                            if (error?.code !== 'stale_request')
+                                this.viewCancellationDiagnostic(id, action.elementId, controller.signal.aborted ? 'timeout' : 'failed');
+                        }
+                    }));
+                }
+            }
+            finally {
+                clearTimeout(timer);
+                controller.signal.removeEventListener('abort', aborted);
+                controller.abort();
+                delete entry.cancellingViews;
+                entry.writers.delete(work);
+            }
+        });
+        entry.cancellingViews = work;
+        entry.writers.add(work);
+        return work;
+    }
+    viewCancellationDiagnostic(session, elementId, reason) {
+        try {
+            this.options.onViewCancellationDiagnostic?.({ session, elementId, reason });
+        }
+        catch { /* Diagnostics cannot block best-effort cancellation. */ }
+    }
+    updateCommandState(entry) {
+        if (!entry.command)
+            return;
+        const run = this.options.store.sessionMetadata(entry.binding.sessionId).run;
+        if (run.id !== entry.command.runId || run.state !== 'running' && run.state !== 'waiting')
+            return;
+        const state = entry.command.views.size && entry.binding.runtime.session.isIdle ? 'waiting' : 'running';
+        if (state !== run.state)
+            entry.projection.publish({ type: 'run.updated', run: { ...run, state } }, { run: { ...run, state } });
+    }
+    extras(id) {
+        const sessions = this.options.store.sessionMetadatas();
+        const session = this.options.store.sessionMetadata(id);
+        return { children: sessions.filter(item => item.parent === id && item.deletedAt === undefined).map(item => ({ session: item.id, parent: id, root: item.root, title: item.title, state: item.state, run: item.run })),
+            processes: this.processes.list(session.root), interactions: this.options.store.interactions().filter(item => item.scope.kind === 'session' && item.scope.session === id && (item.state === 'waiting' || item.state === 'deferred')) };
+    }
+    publish(event) {
+        if ('change' in event && 'interaction' in event.change && (event.change.type === 'interaction.requested' || event.change.type === 'interaction.resolved')) {
+            const interaction = parseInteraction(event.change.interaction);
+            for (const listener of this.interactionListeners)
+                listener(structuredClone(interaction));
+        }
+        const listeners = this.listeners.get(event.session);
+        if (listeners?.size || this.observers.size) {
+            const shared = structuredClone(event);
+            for (const listener of listeners ?? []) {
+                try {
+                    listener(shared);
+                }
+                catch { /* A client observer does not own runtime lifetime. */ }
+            }
+            for (const observer of this.observers.keys()) {
+                try {
+                    observer(shared);
+                }
+                catch { }
+            }
+        }
+        const entry = this.entries.get(event.session);
+        if (!entry || !('change' in event))
+            return;
+        const change = event.change;
+        if (change.type === 'run.updated') {
+            this.updateCommandState(entry);
+            return;
+        }
+        if (change.type !== 'presentation.updated' && change.type !== 'presentation.removed')
+            return;
+        if (entry.command) {
+            if (change.type === 'presentation.removed' && 'id' in change)
+                entry.command.views.delete(change.id);
+            else if ('presentation' in change) {
+                const element = change.presentation;
+                if ((element.kind === 'view' || element.kind === 'document') && element.actions.some(action => action.target === 'element' && action.outcome === 'cancel'))
+                    entry.command.views.add(element.id);
+                else
+                    entry.command.views.delete(element.id);
+            }
+            this.updateCommandState(entry);
+        }
+        if (change.type === 'presentation.updated' && 'presentation' in change && (this.draining || this.stopping || this.closing.has(event.session) || entry.cancelling)) {
+            void Promise.resolve().then(() => {
+                if (this.entries.get(event.session) === entry)
+                    return this.cancelViews(event.session);
+            }).catch(() => this.viewCancellationDiagnostic(event.session, change.presentation.id, 'failed'));
+        }
+    }
+    policyUpdate(id, policy) {
+        const projection = this.entries.get(id)?.projection;
+        if (projection)
+            projection.publish({ type: 'policy.updated', policy }, { policy });
+        else
+            this.options.store.updateSession(id, { policy });
+    }
+    require(id) { const entry = this.entries.get(id); if (!entry)
+        throw new Error('Session runtime is not resident.'); return entry; }
+    /** Reload keeps the root's PTYs running (its next runtime reattaches them by ID) and keeps the root's executions running. */
+    async disposeEntry(id, close, { preserveView = false, keepTerminals = false, keepExecutions = false } = {}) {
+        const entry = this.require(id);
+        if (entry.disposing)
+            return entry.disposing;
+        entry.disposing = (async () => {
+            entry.projection.refresh();
+            if (close)
+                this.processes.seal(id);
+            for (const service of [...entry.services])
+                if (service.disposeWhenIdle) {
+                    await this.processes.withCleanup(id, async () => { await service.settle(close ? 'force' : 'drain'); await service.dispose(); });
+                    entry.services.delete(service);
+                }
+            if (!close)
+                this.processes.seal(id);
+            if (close)
+                for (const service of entry.services)
+                    await this.processes.withCleanup(id, () => service.dispose());
+            if (!keepExecutions)
+                await entry.host?.shutdown();
+            await this.processes.settle(entry.binding.rootSessionId, false, new Set([id]), keepTerminals);
+            if (!entry.runtimeDisposed)
+                await this.processes.withCleanup(id, () => entry.binding.runtime.dispose());
+            this.processes.revoke(id);
+            this.options.owner.assertCurrent();
+            const stored = this.options.store.sessionMetadata(id);
+            const closed = close || this.closes.has(id);
+            entry.projection.transitionForSafety(closed ? 'closed' : 'evicted');
+            entry.projection.dispose();
+            this.entries.delete(id);
+            if (!preserveView)
+                this.listeners.delete(id);
+            this.pathClaims.delete(stored.piPath);
+            if (!close && entry.services.size)
+                this.retainedServices.set(id, entry.services);
+        })();
+        try {
+            await entry.disposing;
+        }
+        catch (error) {
+            delete entry.disposing;
+            this.fence(error);
+            throw error;
+        }
+    }
+    fence(error) {
+        this.failure = error;
+        this.processes.sealAll();
+        for (const entry of this.entries.values())
+            entry.projection.dispose();
+        this.failureSettlement ??= Promise.resolve().then(() => this.settleAfterLoss());
+        void this.failureSettlement.catch(() => { });
+    }
+    async settleWriters() {
+        if (this.failureSettlement)
+            await this.failureSettlement;
+        else {
+            const failures = [];
+            do {
+                await this.join(this.pendingWriters(), failures);
+            } while (this.hasPendingWriters());
+            for (const error of this.cancellationFailures)
+                if (!failures.includes(error))
+                    failures.push(error);
+            if (failures.length)
+                throw new AggregateError(failures, 'Registry writers did not settle cleanly; ownership must remain held.');
+        }
+    }
+    async settleAfterLoss() {
+        const failures = [];
+        const roots = new Set([...this.entries.values()].map(entry => entry.binding.rootSessionId).concat([...this.processes.liveRoots()]));
+        const pending = [...this.opening.values(), ...this.closes.values(), ...[...roots].map(root => this.processes.settle(root, true))];
+        for (const entry of this.entries.values()) {
+            pending.push(entry.binding.runtime.session.abort(), ...(entry.disposing ? [entry.disposing] : []), ...(entry.cancelling ? [entry.cancelling] : []));
+            if (entry.host)
+                pending.push((async () => {
+                    try {
+                        await entry.host.shutdown();
+                    }
+                    finally {
+                        await entry.host.settle();
+                    }
+                })());
+            for (const service of entry.services)
+                pending.push(service.settle());
+        }
+        for (const services of this.retainedServices.values())
+            for (const service of services)
+                pending.push(service.settle());
+        await this.join(pending, failures);
+        do {
+            await this.join(this.pendingWriters(), failures);
+        } while (this.hasPendingWriters());
+        for (const error of this.cancellationFailures)
+            if (!failures.includes(error))
+                failures.push(error);
+        if (failures.length)
+            throw new AggregateError(failures, 'Registry writers did not settle cleanly; ownership must remain held.');
+    }
+    pendingWriters() {
+        return [...this.opening.values(), ...this.lifecycleWriters, ...[...this.entries.values()].flatMap(entry => [...entry.writers, ...(entry.cancelling ? [entry.cancelling] : [])])];
+    }
+    hasPendingWriters() {
+        return this.opening.size > 0 || this.lifecycleWriters.size > 0 || [...this.entries.values()].some(entry => entry.writers.size > 0 || entry.cancelling !== undefined);
+    }
+    async join(operations, failures, allowCancelled = false) {
+        const errors = failures ?? [];
+        for (const result of await Promise.allSettled(operations))
+            if (result.status === 'rejected' && !(allowCancelled && result.reason instanceof RegistryOpeningCancelled))
+                errors.push(result.reason);
+        if (!failures && errors.length)
+            throw new AggregateError(errors, 'Registry operation failed to settle.');
+    }
+}
+function profileOptions(profile) {
+    return { ...(profile?.extensionPaths ? { extensionPaths: profile.extensionPaths } : {}), ...(profile?.allowedTools ? { allowedTools: profile.allowedTools } : {}),
+        ...(profile?.extensionConfigOverrides ? { extensionConfigOverrides: profile.extensionConfigOverrides } : {}) };
+}
+function directoryOf(path) { return path.slice(0, path.lastIndexOf('/')) || '/'; }
+function registryError(code, message) { return Object.assign(new Error(message), { code }); }
+//# sourceMappingURL=registry.js.map