nterminal 1.3.3 → 1.3.5

package/dist/server/terminal/TerminalManager.js

@@ -1,13 +1,37 @@
 import { createHash, randomUUID } from 'node:crypto';
 import path from 'node:path';
+import { stat as statFile } from 'node:fs/promises';
 import { normalizeTerminalTitle } from './PtyAdapter.js';
+import { codexSessionCreatedAtMs } from './codexTranscriptSource.js';
 import { resolveProcessCwd } from './cwdResolver.js';
 import { OutputBuffer } from './outputBuffer.js';
 import { readTranscriptHistoryPage } from './transcriptHistory.js';
 import { TranscriptStore } from './transcriptStore.js';
-import { AgentTranscriptTracker } from './agentTranscriptStatus.js';
+import { AgentTranscriptTracker, readAgentTranscriptConfirmation } from './agentTranscriptStatus.js';
 import { listTerminalSubagents, resolveSubagentTranscriptSource, subagentSummary } from './subagentSources.js';
 import { mapWithConcurrency } from './asyncCommand.js';
+import { isLowPriorityLifecycleEvent, reduceLifecycle, reconcileLifecycle } from '../hooks/lifecycle.js';
+import { readHookOwner, validateHookTranscript } from '../hooks/hookBinding.js';
+import { verifyHookPaneOwner } from '../hooks/hookProcess.js';
+// Manager queue: tool events are dropped first; stop/completion events keep
+// a reserved share. The receiver in front of it applies the same policy.
+const HOOK_QUEUE_LOW_PRIORITY_LIMIT = 64;
+const HOOK_QUEUE_LIMIT = 160;
+// Failed shared-daemon resolutions for a session are reused this long unless
+// a SessionStart/UserPromptSubmit for it arrives.
+const SHARED_HOOK_MISS_TTL_MS = 5_000;
+const HOOK_SESSION_MEMORY_LIMIT = 256;
+// A fresh TUI creates its thread while starting; a daemon cold start and
+// MCP initialization can delay that by several seconds.
+const SHARED_LAUNCH_SKEW_MS = 5_000;
+const SHARED_LAUNCH_WINDOW_MS = 30_000;
+const HOOK_UNBOUND_REPORT_LIMIT = 16;
+function boundedSet(map, key, value, limit) {
+    map.delete(key);
+    while (map.size >= limit)
+        map.delete(map.keys().next().value);
+    map.set(key, value);
+}
 // Window for the output-rate component of busy detection. Slightly larger
 // than the poll interval so a tab that just stopped emitting output
 // transitions to idle on the very next poll (rather than lagging a tick),
@@ -44,6 +68,23 @@ export class TerminalManager {
     shellBasename;
     terminalCapabilities;
     agentTranscriptTracker = new AgentTranscriptTracker();
+    hookBindings = new Map();
+    retiredHookSessions = new Map();
+    activitySubscribers = new Set();
+    hookEpoch = randomUUID();
+    hookRevision = 0;
+    hookTail = Promise.resolve();
+    hookPending = 0;
+    queuedToolEvents = new Map();
+    // Keyed by `${daemonPid}:${startTicks}:${sessionId}`; bounded LRU maps.
+    sharedHookMisses = new Map();
+    sharedSessionStarts = new Map();
+    // The TUI process identity behind each pane's shared bindings, and the time
+    // of its last bound event. Distinguishes a first binding from a switch.
+    paneHookClients = new Map();
+    hookUnbound = new Map();
+    hookDependencies;
+    isHookProviderEnabled;
     transcriptStore;
     transcriptQueue = [];
     lastDiagnosticAt = new Map();
@@ -70,6 +111,10 @@ export class TerminalManager {
         this.now = options.now ?? (() => new Date());
         this.onCompletion = options.onCompletion ?? null;
         this.onDiagnostic = options.onDiagnostic ?? null;
+        this.hookDependencies = options.hookDependencies ?? {
+            readOwner: readHookOwner, verifyPaneOwner: verifyHookPaneOwner, validateTranscript: validateHookTranscript
+        };
+        this.isHookProviderEnabled = options.isHookProviderEnabled ?? (async () => true);
         this.shellBasename = path.basename(this.config.shell);
         this.terminalCapabilities =
             typeof this.ptyAdapter.scrollbackScroll === 'function' &&
@@ -106,11 +151,17 @@ export class TerminalManager {
     }
     async pollOnce() {
         const poll = this.ptyAdapter.pollSessions;
-        if (!poll)
+        if (!poll) {
+            for (const id of this.hookBindings.keys())
+                this.scheduleTranscriptRefresh(id);
             return;
+        }
+        const startedAt = Date.now();
         const result = await poll.call(this.ptyAdapter);
         const now = Date.now();
         for (const [terminalId, snapshot] of result) {
+            if ((this.hookBindings.get(terminalId)?.observedAt ?? 0) > startedAt)
+                continue;
             try {
                 this.applyProcessSnapshot(terminalId, snapshot, now);
             }
@@ -136,6 +187,9 @@ export class TerminalManager {
         let summaryChanged = commandChanged;
         record.summary.currentCommand = nextCommand;
         if (!nextCommand) {
+            this.hookBindings.delete(terminalId);
+            this.paneHookClients.delete(terminalId);
+            this.hookUnbound.delete(terminalId);
             this.agentTranscriptTracker.reset(terminalId);
             record.transcriptSourceMissingSince = null;
             if (record.summary.agentStatus) {
@@ -175,6 +229,11 @@ export class TerminalManager {
         const record = this.terminals.get(terminalId);
         if (!record || record.summary.status !== 'running' || record.closing || !record.summary.currentCommand)
             return;
+        const hook = this.hookBindings.get(terminalId);
+        if (hook && hook.state.status.state !== 'finishing' && Date.now() - hook.transcriptReadAt < 30_000)
+            return;
+        if (hook)
+            hook.transcriptReadAt = Date.now();
         if (record.transcriptRefreshState === 'running') {
             record.transcriptRerun = true;
             return;
@@ -237,16 +296,41 @@ export class TerminalManager {
         if (!record || record.summary.status !== 'running' || record.closing || !currentCommand)
             return;
         const generation = record.transcriptGeneration;
+        const hook = this.hookBindings.get(terminalId);
         const isCurrent = () => !this.disposed &&
             this.terminals.get(terminalId) === record &&
             record.summary.status === 'running' &&
             !record.closing &&
             record.transcriptGeneration === generation &&
-            record.summary.currentCommand === currentCommand;
+            record.summary.currentCommand === currentCommand &&
+            this.hookBindings.get(terminalId) === hook;
         const transcript = await this.resolveAgentTranscript(terminalId, currentCommand, isCurrent);
         if (transcript === null || !isCurrent())
             return;
-        const nextAgentStatus = transcript?.status;
+        if (hook) {
+            const paneOwned = await this.hookPaneStillOwned(terminalId, record, hook);
+            const owner = await this.hookDependencies.readOwner(hook.owner, hook.owner.provider);
+            if (!isCurrent() || this.hookBindings.get(terminalId) !== hook)
+                return;
+            if (!hookOwnerMatches(owner, hook.owner)) {
+                this.forgetHookBinding(terminalId, hook);
+                return;
+            }
+            if (!paneOwned)
+                return;
+        }
+        let confirmedCompletion;
+        if (hook && transcript && transcript.status.sessionId === hook.state.status.sessionId) {
+            const state = reconcileLifecycle(hook.state, transcript.completion);
+            if (state !== hook.state) {
+                const previousCompletion = hook.state.status.completion;
+                state.status = { ...state.status, epoch: this.hookEpoch, revision: ++this.hookRevision };
+                hook.state = state;
+                if (state.status.completion?.id !== previousCompletion?.id)
+                    confirmedCompletion = state.status.completion;
+            }
+        }
+        const nextAgentStatus = this.hookBindings.get(terminalId)?.state.status ?? transcript?.status;
         const nextAgentCache = transcript?.cache;
         if (agentSessionChanged(record.summary.agentStatus?.sessionId ?? null, nextAgentStatus?.sessionId ?? null)) {
             record.transcriptGeneration += 1;
@@ -277,12 +361,24 @@ export class TerminalManager {
         record.summary.updatedAt = this.timestamp();
         this.publish(record, { type: 'terminal_updated', terminal: cloneSummary(record.summary) });
         this.trackCompletion(record.summary);
+        if (confirmedCompletion && hook) {
+            this.emitCompletion({ terminalId, terminalTitle: record.summary.title, provider: hook.owner.provider,
+                completionId: confirmedCompletion.id, occurredAt: confirmedCompletion.occurredAt,
+                outcome: confirmedCompletion.outcome, commandName: currentCommand });
+        }
     }
     // Allow the process to shut down cleanly without leaking the polling
     // interval — called by the server's graceful-shutdown path.
     dispose() {
         this.disposed = true;
         this.transcriptStore.dispose();
+        this.hookBindings.clear();
+        this.retiredHookSessions.clear();
+        this.paneHookClients.clear();
+        this.hookUnbound.clear();
+        this.sharedHookMisses.clear();
+        this.sharedSessionStarts.clear();
+        this.activitySubscribers.clear();
         this.shutdownRequested = true;
         if (this.statusPollTimer) {
             clearInterval(this.statusPollTimer);
@@ -601,6 +697,9 @@ export class TerminalManager {
         delete record.summary.agentCache;
         this.agentTranscriptTracker.reset(id);
         this.completionStates.delete(id);
+        this.hookBindings.delete(id);
+        this.paneHookClients.delete(id);
+        this.hookUnbound.delete(id);
         this.publish(record, { type: 'exit', terminalId: id, exitCode });
     }
     // Spawn a fresh local client for a restored session that hasn't been
@@ -623,6 +722,449 @@ export class TerminalManager {
     listTerminals() {
         return [...this.terminals.values()].map((record) => cloneSummary(record.summary));
     }
+    subscribeActivity(listener) {
+        this.activitySubscribers.add(listener);
+        return () => { this.activitySubscribers.delete(listener); };
+    }
+    getLifecycleHookStatus(provider) {
+        const bindings = [...this.hookBindings.values()].filter(binding => binding.owner.provider === provider);
+        const latest = bindings.reduce((at, binding) => Math.max(at, binding.observedAt), 0);
+        const unboundPanes = [];
+        // Only Codex has a shared daemon whose sessions can be unattributable.
+        if (provider === 'codex') {
+            for (const [id, record] of this.terminals) {
+                if (unboundPanes.length >= HOOK_UNBOUND_REPORT_LIMIT)
+                    break;
+                if (this.hookBindings.has(id) || record.summary.status !== 'running' || record.closing)
+                    continue;
+                if (this.ptyAdapter.pollSessions && !foregroundMayRunProvider(record.summary, 'codex'))
+                    continue;
+                const reason = this.ptyAdapter.getTranscriptAmbiguity?.(id) === 'codex_shared_daemon_same_cwd'
+                    ? 'shared_daemon_same_cwd' : this.hookUnbound.get(id)?.reason;
+                if (reason)
+                    unboundPanes.push({ terminalId: id, title: record.summary.title, reason });
+            }
+        }
+        return { observed: bindings.length > 0, activeSessions: bindings.length, lastEventAt: latest ? new Date(latest).toISOString() : null,
+            ...(unboundPanes.length ? { unboundPanes } : {}) };
+    }
+    invalidateLifecycleHooks(provider) {
+        this.sharedHookMisses.clear();
+        for (const [id, binding] of this.hookBindings) {
+            if (binding.owner.provider !== provider)
+                continue;
+            this.hookBindings.delete(id);
+            this.paneHookClients.delete(id);
+            this.completionStates.delete(id);
+            const record = this.terminals.get(id);
+            if (!record)
+                continue;
+            record.transcriptGeneration++;
+            record.summary.agentStatus = { provider, state: 'unknown', source: 'transcript' };
+            record.summary.updatedAt = this.timestamp();
+            this.publish(record, { type: 'terminal_updated', terminal: cloneSummary(record.summary) });
+            this.scheduleTranscriptRefresh(id);
+        }
+    }
+    receiveLifecycle(event) {
+        if (this.disposed || event.agentId || event.background || event.event.startsWith('Subagent'))
+            return Promise.resolve();
+        // Tool events are coalescible and dropped first; completion/stop events
+        // keep a reserved share of the bounded queue.
+        const low = isLowPriorityLifecycleEvent(event);
+        if (this.hookPending >= (low ? HOOK_QUEUE_LOW_PRIORITY_LIMIT : HOOK_QUEUE_LIMIT))
+            return Promise.resolve();
+        const coalesceKey = low ? `${event.provider}:${event.sessionId}` : null;
+        if (coalesceKey)
+            this.queuedToolEvents.set(coalesceKey, (this.queuedToolEvents.get(coalesceKey) ?? 0) + 1);
+        this.hookPending += 1;
+        const result = this.hookTail.then(() => {
+            if (coalesceKey) {
+                const remaining = (this.queuedToolEvents.get(coalesceKey) ?? 1) - 1;
+                if (remaining > 0) {
+                    // A later tool event for this session is already queued and has
+                    // the same effect (working). Skip this one without any lookup.
+                    this.queuedToolEvents.set(coalesceKey, remaining);
+                    return;
+                }
+                this.queuedToolEvents.delete(coalesceKey);
+            }
+            return this.applyLifecycleEvent(event);
+        });
+        this.hookTail = result.catch(() => undefined);
+        return result.finally(() => { this.hookPending -= 1; });
+    }
+    async applyLifecycleEvent(event) {
+        // Fence all awaits, including owner/config/path validation, against a pane
+        // switching commands or losing its binding while this event is in flight.
+        const targets = [...this.terminals].map(([id, record]) => ({
+            id, record, generation: record.transcriptGeneration, old: this.hookBindings.get(id)
+        }));
+        if (this.disposed || !await this.isHookProviderEnabled(event.provider))
+            return;
+        let owner = null;
+        for (const identity of event.ancestors.slice(0, 32)) {
+            owner = await this.hookDependencies.readOwner(identity, event.provider);
+            if (owner)
+                break;
+        }
+        if (!owner || (!owner.foreground && !owner.shared) || this.disposed)
+            return;
+        const ownerKey = `${owner.pid}:${owner.startTicks}`;
+        const sharedSessionKey = `${ownerKey}:${event.sessionId}`;
+        if (!owner.foreground && event.event === 'SessionStart') {
+            boundedSet(this.sharedSessionStarts, sharedSessionKey, Date.parse(event.occurredAt), HOOK_SESSION_MEMORY_LIMIT);
+        }
+        let sourceFromHook = null;
+        let sourceValidated = false;
+        const knownObservers = new Set(!owner.foreground && event.event !== 'SessionStart'
+            ? [...this.hookBindings].filter(([, binding]) => binding.owner.pid === owner.pid
+                && binding.owner.startTicks === owner.startTicks && binding.state.status.sessionId === event.sessionId).map(([id]) => id)
+            : []);
+        const lowPriority = isLowPriorityLifecycleEvent(event);
+        if (!owner.foreground && knownObservers.size === 0) {
+            // No pane owns this shared-daemon session. Tool events never pay for a
+            // daemon resolution; they cannot establish a binding. A recent failed
+            // resolution is reused until a prompt/start can change the answer.
+            if (lowPriority)
+                return;
+            if (event.event === 'SessionStart' || event.event === 'UserPromptSubmit')
+                this.sharedHookMisses.delete(sharedSessionKey);
+            else if ((this.sharedHookMisses.get(sharedSessionKey) ?? 0) > Date.now())
+                return;
+        }
+        const proposals = [];
+        const commit = async ({ id, record, generation, old }, panePid, paneIdentity, source, options) => {
+            const sameOwner = old && hookOwnerMatches(old.owner, owner);
+            if (!sourceValidated) {
+                sourceValidated = true;
+                if (event.transcriptPath)
+                    sourceFromHook = await this.hookDependencies.validateTranscript(owner, event.sessionId, event.transcriptPath);
+            }
+            if (!owner.foreground && !await this.verifySharedHookAssociation(id, owner, event.sessionId, lowPriority && !options.created))
+                return;
+            const currentPanePid = await this.ptyAdapter.getSessionPid?.(id) ?? record.summary.pid;
+            const currentOwner = await this.hookDependencies.readOwner(owner, event.provider);
+            if (currentPanePid !== panePid || !hookOwnerMatches(currentOwner, owner)
+                || (owner.foreground && (!paneIdentity || !await this.hookDependencies.verifyPaneOwner(owner, paneIdentity)))
+                || !this.transcriptRequestStillLive(id, record, generation) || this.hookBindings.get(id) !== old)
+                return;
+            if (options.created && !owner.foreground && this.sharedSessionBoundElsewhere(id, owner, event.sessionId))
+                return;
+            const previous = sameOwner ? old.state : undefined;
+            let state = reduceLifecycle(previous, event);
+            if (!state || state === previous)
+                return;
+            if (options.created && !owner.foreground && state.status.completion
+                && state.status.completion.id !== previous?.status.completion?.id) {
+                // A shared binding established by this very event did not observe
+                // the turn; its outcome is not attributable to this pane.
+                const { completion: _unobserved, ...status } = state.status;
+                state = { ...state, status: { ...status, state: 'idle' } };
+            }
+            if (options.wasRetired)
+                this.retiredHookSessions.get(id)?.sessions.delete(event.sessionId);
+            const sessionChanged = record.summary.agentStatus?.sessionId !== event.sessionId;
+            if (sessionChanged) {
+                if (old)
+                    this.retireHookSession(id, old);
+                this.ptyAdapter.invalidateTranscriptSource?.(id);
+                record.transcriptGeneration += 1;
+                this.agentTranscriptTracker.reset(id);
+                delete record.summary.agentCache;
+            }
+            const statusChanged = record.summary.agentStatus?.source !== 'hook' || sessionChanged
+                || record.summary.agentStatus.state !== state.status.state
+                || record.summary.agentStatus.completion?.id !== state.status.completion?.id;
+            state.status = { ...state.status, epoch: this.hookEpoch,
+                revision: statusChanged ? ++this.hookRevision : record.summary.agentStatus.revision };
+            this.hookBindings.set(id, {
+                owner: owner,
+                ...(owner.foreground && paneIdentity ? { paneIdentity } : {}),
+                state,
+                source: sourceFromHook ?? source ?? (!sessionChanged ? old?.source ?? null : null),
+                transcriptPath: event.transcriptPath ?? (!sessionChanged ? old?.transcriptPath : undefined),
+                observedAt: Date.now(),
+                transcriptReadAt: sessionChanged ? 0 : old?.transcriptReadAt ?? 0,
+                cacheReadAt: sessionChanged ? 0 : old?.cacheReadAt ?? 0,
+                ...(!sessionChanged && old?.confirmation ? { confirmation: old.confirmation } : {})
+            });
+            this.hookUnbound.delete(id);
+            if (!owner.foreground) {
+                const history = this.paneHookClients.get(id);
+                const clientKey = options.client ? `${options.client.pid}:${options.client.startTicks}` : history?.client;
+                if (clientKey)
+                    this.paneHookClients.set(id, { client: clientKey, lastBoundAt: Date.parse(event.occurredAt) });
+            }
+            record.summary.agentStatus = state.status;
+            // The hook may arrive before the next process catalog poll.
+            if (!record.summary.currentCommand)
+                record.summary.currentCommand = event.provider;
+            record.summary.activity = activityFromSignals({ busy: false, recentOutput: false, agentStatus: state.status });
+            if (statusChanged) {
+                record.summary.updatedAt = this.timestamp();
+                this.publish(record, { type: 'terminal_updated', terminal: cloneSummary(record.summary) });
+            }
+            this.completionStates.delete(id);
+            if (state.status.completion && state.status.completion.id !== previous?.status.completion?.id) {
+                this.emitCompletion({
+                    terminalId: id,
+                    terminalTitle: record.summary.title,
+                    provider: event.provider,
+                    outcome: state.status.completion.outcome,
+                    occurredAt: state.status.completion.occurredAt,
+                    completionId: state.status.completion.id,
+                    commandName: record.summary.currentCommand
+                });
+            }
+            if (event.event === 'SessionEnd')
+                this.forgetHookBinding(id, this.hookBindings.get(id));
+            else {
+                this.startStatusPoller();
+                this.scheduleTranscriptRefresh(id);
+            }
+        };
+        for (const target of targets) {
+            const { id, record, generation, old } = target;
+            if (knownObservers.size > 0 && !knownObservers.has(id))
+                continue;
+            if (!this.transcriptRequestStillLive(id, record, generation) || this.hookBindings.get(id) !== old)
+                continue;
+            const panePid = await this.ptyAdapter.getSessionPid?.(id) ?? record.summary.pid;
+            const paneIdentity = event.ancestors.find((identity) => identity.pid === panePid);
+            let matched = owner.foreground && !!paneIdentity
+                && await this.hookDependencies.verifyPaneOwner(owner, paneIdentity);
+            let resolution = null;
+            let source = null;
+            const established = !owner.foreground && !!old && hookOwnerMatches(old.owner, owner) && old.state.status.sessionId === event.sessionId;
+            if (!matched) {
+                if (owner.foreground)
+                    continue;
+                if (record.summary.agentStatus?.provider && record.summary.agentStatus.provider !== event.provider)
+                    continue;
+                // A pane at its shell prompt, or running the other provider, cannot
+                // own one of this provider's daemon sessions: skip it without a lookup.
+                if (!established && this.ptyAdapter.pollSessions && !foregroundMayRunProvider(record.summary, event.provider))
+                    continue;
+                // A shared app-server may not descend from its TUI. Only an existing
+                // exact native binding can bridge it; cwd/candidate lists cannot.
+                resolution = established ? await this.resolveHookNativeResolution(id, false) : await this.resolveFreshHookNativeResolution(id);
+                if (established && (resolution?.source.provider !== event.provider || resolution.source.sessionId !== event.sessionId)) {
+                    resolution = await this.resolveFreshHookNativeResolution(id);
+                }
+                source = resolution?.source ?? null;
+                matched = source?.provider === event.provider && source.sessionId === event.sessionId;
+            }
+            if (!matched || !this.transcriptRequestStillLive(id, record, generation))
+                continue;
+            const sameOwner = old && hookOwnerMatches(old.owner, owner);
+            const retired = this.retiredHookSessions.get(id);
+            const wasRetired = retired?.owner === ownerKey && retired.sessions.has(event.sessionId);
+            if (wasRetired && event.event !== 'SessionStart')
+                continue;
+            if (wasRetired || (sameOwner && old.state.status.sessionId !== event.sessionId && event.event !== 'SessionStart')) {
+                if (owner.foreground)
+                    this.ptyAdapter.invalidateTranscriptSource?.(id);
+                const native = owner.foreground ? await this.resolveHookNativeSource(id, true)
+                    : await this.resolveFreshHookNativeSource(id);
+                if (native?.provider !== event.provider || native.sessionId !== event.sessionId
+                    || !this.transcriptRequestStillLive(id, record, generation))
+                    continue;
+            }
+            if (!owner.foreground && !established) {
+                // A daemon cwd match is not tied to this TUI. A new shared binding
+                // needs independent corroboration, and is committed only when this
+                // is the sole pane proposing it.
+                if (!this.corroborateSharedBinding(id, event, sharedSessionKey, resolution)) {
+                    this.noteHookUnbound(id, 'shared_daemon_unverified');
+                    continue;
+                }
+                proposals.push({ target, panePid, source: source, client: resolution?.client });
+                continue;
+            }
+            await commit(target, panePid, paneIdentity, source, { created: false, wasRetired });
+        }
+        if (proposals.length === 1) {
+            const [{ target, panePid, source, client }] = proposals;
+            const retired = this.retiredHookSessions.get(target.id);
+            await commit(target, panePid, undefined, source, {
+                created: true, client, wasRetired: retired?.owner === ownerKey && retired.sessions.has(event.sessionId)
+            });
+        }
+        else if (proposals.length > 1) {
+            for (const { target } of proposals)
+                this.noteHookUnbound(target.id, 'shared_daemon_same_cwd');
+        }
+        if (!owner.foreground && !lowPriority && ![...this.hookBindings.values()].some(binding => binding.owner.pid === owner.pid
+            && binding.owner.startTicks === owner.startTicks && binding.state.status.sessionId === event.sessionId)) {
+            boundedSet(this.sharedHookMisses, sharedSessionKey, Date.now() + SHARED_HOOK_MISS_TTL_MS, HOOK_SESSION_MEMORY_LIMIT);
+        }
+    }
+    // Corroboration for a NEW shared-daemon binding of `event.sessionId` on a
+    // pane whose fresh daemon lookup already names it uniquely:
+    // - live: the pane's own process holds the rollout open (exact);
+    // - argv: first binding for this TUI process and `resume <id>` names it;
+    // - launch: first binding for this TUI process and the UUIDv7 thread was
+    //   created while that process was starting (fresh `codex`/`codex fork`);
+    // - session-start: a later switch in the same TUI process (/new, /resume),
+    //   where this session's SessionStart arrived after the pane's last bound
+    //   event. Anything else fails closed.
+    corroborateSharedBinding(id, event, sharedSessionKey, resolution) {
+        if (!resolution)
+            return null;
+        if (resolution.evidence === 'live')
+            return 'live';
+        const client = resolution.client;
+        if (resolution.evidence !== 'daemon' || !client)
+            return null;
+        const history = this.paneHookClients.get(id);
+        if (history?.client !== `${client.pid}:${client.startTicks}`) {
+            if (client.statedSessionId === event.sessionId)
+                return 'argv';
+            const created = event.provider === 'codex' ? codexSessionCreatedAtMs(event.sessionId) : null;
+            if (created !== null && client.startedAtMs !== null && created >= client.startedAtMs - SHARED_LAUNCH_SKEW_MS
+                && created <= client.startedAtMs + SHARED_LAUNCH_WINDOW_MS)
+                return 'launch';
+            return null;
+        }
+        const started = this.sharedSessionStarts.get(sharedSessionKey);
+        return started !== undefined && started > history.lastBoundAt ? 'session-start' : null;
+    }
+    sharedSessionBoundElsewhere(id, owner, sessionId) {
+        for (const [other, binding] of this.hookBindings) {
+            if (other !== id && binding.owner.pid === owner.pid && binding.owner.startTicks === owner.startTicks
+                && binding.state.status.sessionId === sessionId)
+                return true;
+        }
+        return false;
+    }
+    noteHookUnbound(id, reason) {
+        if (this.hookBindings.has(id) || !this.terminals.has(id))
+            return;
+        this.hookUnbound.set(id, { reason, at: Date.now() });
+    }
+    retireHookSession(id, binding) {
+        const owner = `${binding.owner.pid}:${binding.owner.startTicks}`;
+        const previous = this.retiredHookSessions.get(id);
+        const sessions = previous?.owner === owner ? previous.sessions : new Set();
+        if (binding.state.status.sessionId)
+            sessions.add(binding.state.status.sessionId);
+        while (sessions.size > 128)
+            sessions.delete(sessions.values().next().value);
+        this.retiredHookSessions.set(id, { owner, sessions });
+    }
+    forgetHookBinding(id, binding, replacement) {
+        if (this.hookBindings.get(id) !== binding)
+            return;
+        this.retireHookSession(id, binding);
+        this.hookBindings.delete(id);
+        this.completionStates.delete(id);
+        this.agentTranscriptTracker.reset(id);
+        const record = this.terminals.get(id);
+        if (!record)
+            return;
+        record.transcriptGeneration++;
+        delete record.summary.agentStatus;
+        delete record.summary.agentCache;
+        if (replacement)
+            record.summary.agentStatus = { provider: replacement.provider, sessionId: replacement.sessionId, state: 'unknown', source: 'transcript' };
+        if (!this.ptyAdapter.pollSessions)
+            record.summary.currentCommand = replacement?.provider ?? null;
+        record.summary.activity = activityFromSignals({ busy: record.lastKernelBusy, recentOutput: false, agentStatus: undefined });
+        record.summary.updatedAt = this.timestamp();
+        this.publish(record, { type: 'terminal_updated', terminal: cloneSummary(record.summary) });
+    }
+    async liveHookSource(id) {
+        const binding = this.hookBindings.get(id);
+        const record = this.terminals.get(id);
+        if (!binding || !record)
+            return null;
+        const generation = record.transcriptGeneration;
+        const isCurrent = () => this.transcriptRequestStillLive(id, record, generation) && this.hookBindings.get(id) === binding;
+        if (!await this.isHookProviderEnabled(binding.owner.provider)) {
+            this.invalidateLifecycleHooks(binding.owner.provider);
+            return null;
+        }
+        const owner = await this.hookDependencies.readOwner(binding.owner, binding.owner.provider);
+        if (!isCurrent())
+            return null;
+        if (!hookOwnerMatches(owner, binding.owner)) {
+            this.forgetHookBinding(id, binding);
+            return null;
+        }
+        if (binding.owner.foreground && (!await this.hookPaneStillOwned(id, record, binding) || !isCurrent()))
+            return null;
+        const native = await this.resolveHookNativeSource(id, binding.owner.foreground, { provider: binding.owner.provider, sessionId: binding.state.status.sessionId });
+        if (!isCurrent())
+            return null;
+        // A discovery gap is not evidence of a new session. Shared owners stay
+        // bound but cannot supply transcript data until their association returns.
+        if (!binding.owner.foreground && !native)
+            return null;
+        const changed = native && (native.provider !== binding.owner.provider || native.sessionId !== binding.state.status.sessionId);
+        const filePath = native?.filePath ?? binding.source?.filePath ?? binding.transcriptPath;
+        const source = !changed && filePath
+            ? await this.hookDependencies.validateTranscript(binding.owner, binding.state.status.sessionId, filePath) : null;
+        // Native discovery and path validation can both outlive the provider.
+        const currentNative = !binding.owner.foreground ? await this.resolveFreshHookNativeSource(id) : null;
+        const paneOwned = binding.owner.foreground ? await this.hookPaneStillOwned(id, record, binding)
+            : !!native && currentNative?.provider === native.provider && currentNative.sessionId === native.sessionId
+                && currentNative.filePath === native.filePath;
+        const currentOwner = await this.hookDependencies.readOwner(binding.owner, binding.owner.provider);
+        if (!isCurrent())
+            return null;
+        if (!hookOwnerMatches(currentOwner, binding.owner)) {
+            this.forgetHookBinding(id, binding);
+            return null;
+        }
+        if (!paneOwned)
+            return null;
+        if (changed) {
+            this.forgetHookBinding(id, binding, native);
+            return null;
+        }
+        binding.source = source;
+        return source;
+    }
+    async hookPaneStillOwned(id, record, binding) {
+        if (!binding.owner.foreground)
+            return this.verifySharedHookAssociation(id, binding.owner, binding.state.status.sessionId);
+        const pane = binding.paneIdentity;
+        return !!pane && (await this.ptyAdapter.getSessionPid?.(id) ?? record.summary.pid) === pane.pid
+            && await this.hookDependencies.verifyPaneOwner(binding.owner, pane);
+    }
+    // `allowCached` is only for tool events of an already-established binding:
+    // they can mark the pane working but never publish a completion.
+    async verifySharedHookAssociation(id, owner, sessionId, allowCached = false) {
+        if (!owner.shared)
+            return false;
+        if (allowCached) {
+            const cached = await this.resolveHookNativeSource(id, false);
+            if (cached?.provider === owner.provider && cached.sessionId === sessionId)
+                return true;
+        }
+        const current = await this.resolveFreshHookNativeSource(id);
+        return current?.provider === owner.provider && current.sessionId === sessionId;
+    }
+    async resolveFreshHookNativeSource(id) {
+        return (await this.resolveFreshHookNativeResolution(id))?.source ?? null;
+    }
+    async resolveFreshHookNativeResolution(id) {
+        const resolution = await this.ptyAdapter.resolveTranscriptSourceEvidence?.(id, { fresh: true });
+        return resolution && (resolution.evidence === 'live' || resolution.evidence === 'daemon') ? resolution : null;
+    }
+    async resolveHookNativeSource(id, foreground, expected) {
+        return (await this.resolveHookNativeResolution(id, foreground, expected))?.source ?? null;
+    }
+    async resolveHookNativeResolution(id, foreground, expected) {
+        const resolution = await this.ptyAdapter.resolveTranscriptSourceEvidence?.(id);
+        // Weak evidence can locate an already-authoritative foreground session,
+        // but cannot establish a shared owner or change the hook's session ID.
+        const locator = foreground && expected && resolution?.source.provider === expected.provider
+            && resolution.source.sessionId === expected.sessionId;
+        return resolution && (resolution.evidence === 'live' || (!foreground && resolution.evidence === 'daemon') || locator)
+            ? resolution : null;
+    }
     getTerminal(id) {
         const record = this.terminals.get(id);
         return record ? cloneSummary(record.summary) : null;
@@ -688,11 +1230,18 @@ export class TerminalManager {
         if (selection.candidateId) {
             const result = await this.ptyAdapter.resolveTranscriptCandidates?.(id);
             source = result?.candidates.find((candidate) => this.transcriptCandidateId(id, result.binding, candidate) === selection.candidateId);
+            const binding = this.hookBindings.get(id);
+            if (source && binding) {
+                const live = await this.liveHookSource(id);
+                source = live && live.provider === source.provider && live.sessionId === source.sessionId
+                    && live.filePath === source.filePath ? live : null;
+            }
         }
         else {
-            source = await this.ptyAdapter.resolveTranscriptSource?.(id);
+            source = await this.resolveTranscriptWithHooks(id);
         }
         if (!source ||
+            !this.hookSourceMatches(id, source) ||
             (selection.expectedSessionId !== undefined && source.sessionId !== selection.expectedSessionId) ||
             !transcriptSourceMatchesForeground(record.summary, source.provider) ||
             !this.transcriptRequestStillLive(id, record, generation)) {
@@ -703,6 +1252,16 @@ export class TerminalManager {
     transcriptCandidateId(id, binding, source) {
         return createHash('sha256').update(JSON.stringify([id, binding, source.provider, source.sessionId, source.filePath])).digest('hex');
     }
+    hookSourceMatches(id, source) {
+        const hook = this.hookBindings.get(id);
+        return !hook || (source.provider === hook.owner.provider && source.sessionId === hook.state.status.sessionId);
+    }
+    async resolveTranscriptWithHooks(id) {
+        const source = await this.liveHookSource(id);
+        if (source || this.hookBindings.has(id))
+            return source;
+        return await this.ptyAdapter.resolveTranscriptSource?.(id) ?? null;
+    }
     async transcriptSelectionStillLive(id, live, selection) {
         if (!this.transcriptRequestStillLive(id, live.record, live.generation))
             return false;
@@ -711,7 +1270,7 @@ export class TerminalManager {
             current.source.sessionId === live.source.sessionId && current.source.filePath === live.source.filePath);
     }
     transcriptRequestStillLive(id, record, generation) {
-        return this.terminals.get(id) === record &&
+        return !this.disposed && this.terminals.get(id) === record &&
             record.summary.status === 'running' &&
             !record.closing &&
             record.transcriptGeneration === generation;
@@ -721,10 +1280,29 @@ export class TerminalManager {
             return null;
         const live = await this.resolveLiveTranscriptSource(id, options);
         if (!live || signal?.aborted) {
-            return null;
+            return live || signal?.aborted ? null : await this.transcriptSessionChangedPage(id, options);
         }
         const page = await this.transcriptStore.readPage(id, live.source, { ...options, includeTools: options.includeTools ?? false }, signal);
-        return !signal?.aborted && await this.transcriptSelectionStillLive(id, live, options) ? page : null;
+        if (signal?.aborted)
+            return null;
+        return await this.transcriptSelectionStillLive(id, live, options) ? page : await this.transcriptSessionChangedPage(id, options);
+    }
+    // A reader pinned to one session gets a bare identity of the pane's current
+    // session (never its content) so the client can say the session changed
+    // instead of reporting the transcript as temporarily unavailable.
+    async transcriptSessionChangedPage(id, options) {
+        if (options.expectedSessionId === undefined || options.candidateId)
+            return null;
+        const current = await this.resolveLiveTranscriptSource(id);
+        if (!current || current.source.sessionId === options.expectedSessionId)
+            return null;
+        return {
+            terminalId: id,
+            source: { provider: current.source.provider, sessionId: current.source.sessionId },
+            cursor: null,
+            hasMore: false,
+            output: []
+        };
     }
     async searchTerminalTranscript(id, options, signal) {
         if (signal?.aborted)
@@ -751,7 +1329,7 @@ export class TerminalManager {
         return {
             terminalId: id,
             source: live ? { provider: live.source.provider, sessionId: live.source.sessionId } : null,
-            candidates: (choices?.candidates ?? []).filter((source) => transcriptSourceMatchesForeground(record.summary, source.provider)).map((source) => ({
+            candidates: (choices?.candidates ?? []).filter((source) => this.hookSourceMatches(id, source) && transcriptSourceMatchesForeground(record.summary, source.provider)).map((source) => ({
                 id: this.transcriptCandidateId(id, choices.binding, source),
                 provider: source.provider, sessionId: source.sessionId,
                 title: (source.title ?? '').slice(0, 240), cwd: source.cwd ?? '', updatedAt: source.updatedAt ?? null
@@ -1096,6 +1674,7 @@ export class TerminalManager {
             }
             this.disposeRecord(record);
             this.terminals.delete(id);
+            this.publishRemovedActivity(record);
             return true;
         }, 0, true);
         const close = queuedClose.catch(async (error) => {
@@ -1136,6 +1715,7 @@ export class TerminalManager {
         if (persistentState === false) {
             this.disposeRecord(record);
             this.terminals.delete(record.summary.id);
+            this.publishRemovedActivity(record);
             return true;
         }
         record.summary.status = 'running';
@@ -1359,8 +1939,32 @@ export class TerminalManager {
         for (const subscriber of record.subscribers) {
             subscriber(message);
         }
+        if (message.type === 'terminal_updated' || message.type === 'exit')
+            this.publishActivity(record.summary);
+    }
+    publishActivity(summary) {
+        for (const subscriber of this.activitySubscribers) {
+            try {
+                subscriber(cloneSummary(summary));
+            }
+            catch { /* A failed observer cannot stop a terminal. */ }
+        }
+    }
+    publishRemovedActivity(record) {
+        const removed = { ...cloneSummary(record.summary), status: 'exited', pid: null, updatedAt: this.timestamp() };
+        delete removed.agentStatus;
+        delete removed.agentCache;
+        delete removed.activity;
+        delete removed.currentCommand;
+        this.publishActivity(removed);
     }
     trackCompletion(summary) {
+        // Verified hooks emit one semantic completion below, never a second alarm
+        // inferred from process activity or a transcript poll.
+        if (summary.agentStatus?.source === 'hook') {
+            this.completionStates.delete(summary.id);
+            return;
+        }
         if (summary.status !== 'running') {
             this.completionStates.delete(summary.id);
             return;
@@ -1420,9 +2024,13 @@ export class TerminalManager {
         const record = this.terminals.get(terminalId);
         const inferredProvider = inferAgentProviderFromCommand(currentCommand);
         const graceProvider = expectedAgentProvider(currentCommand, record?.summary.agentStatus?.provider);
-        const source = await this.ptyAdapter.resolveTranscriptSource?.(terminalId);
+        const source = await this.resolveTranscriptWithHooks(terminalId);
         if (!isCurrent())
             return null;
+        if (source && !this.hookSourceMatches(terminalId, source)) {
+            const hook = this.hookBindings.get(terminalId);
+            return { status: hook.state.status, cache: null };
+        }
         const providerMismatch = Boolean(source && graceProvider && source.provider !== graceProvider);
         if (!source || providerMismatch) {
             const now = Date.now();
@@ -1460,6 +2068,29 @@ export class TerminalManager {
         if (record)
             record.transcriptSourceMissingSince = null;
         try {
+            const hook = this.hookBindings.get(terminalId);
+            if (hook) {
+                // Confirm near the file tail so megabytes of tool output cannot hold
+                // up a completion while the usage/cache reader catches up separately.
+                const info = await statFile(source.filePath);
+                const fingerprint = JSON.stringify([source.filePath, info.dev, info.ino, info.size, info.mtimeMs, info.ctimeMs]);
+                if (hook.confirmation?.fingerprint !== fingerprint) {
+                    hook.confirmation = { fingerprint, value: await readAgentTranscriptConfirmation(source) };
+                }
+                const completion = hook.confirmation.value;
+                if (!isCurrent())
+                    return null;
+                let snapshot;
+                if (Date.now() - hook.cacheReadAt < 30_000) {
+                    snapshot = { status: hook.state.status, cache: record?.summary.agentCache ?? null };
+                }
+                else {
+                    hook.cacheReadAt = Date.now();
+                    snapshot = await this.agentTranscriptTracker.readSnapshot(terminalId, source);
+                }
+                const { completion: staleCompletion, ...current } = snapshot;
+                return isCurrent() ? { ...current, ...(completion ? { completion } : {}) } : null;
+            }
             const snapshot = await this.agentTranscriptTracker.readSnapshot(terminalId, source);
             return isCurrent() ? snapshot : null;
         }
@@ -1468,6 +2099,10 @@ export class TerminalManager {
         }
     }
     disposeRecord(record) {
+        this.hookBindings.delete(record.summary.id);
+        this.paneHookClients.delete(record.summary.id);
+        this.hookUnbound.delete(record.summary.id);
+        this.retiredHookSessions.delete(record.summary.id);
         record.transcriptGeneration += 1;
         this.agentTranscriptTracker.reset(record.summary.id);
         this.completionStates.delete(record.summary.id);
@@ -1538,6 +2173,11 @@ export class TerminalManager {
         return tracked;
     }
 }
+function hookOwnerMatches(current, expected) {
+    return current?.pid === expected.pid && current.startTicks === expected.startTicks
+        && current.provider === expected.provider && current.foreground === expected.foreground
+        && current.shared === expected.shared;
+}
 function agentCompletionOutcome(state) {
     if (state === 'done')
         return 'finished';
@@ -1580,11 +2220,15 @@ function cloneSummary(summary) {
     return {
         ...summary,
         ...(summary.capabilities ? { capabilities: { ...summary.capabilities } } : {}),
-        ...(summary.agentStatus ? { agentStatus: { ...summary.agentStatus } } : {}),
+        ...(summary.agentStatus ? { agentStatus: { ...summary.agentStatus,
+                ...(summary.agentStatus.completion ? { completion: { ...summary.agentStatus.completion } } : {}) } } : {}),
         ...(summary.agentCache ? { agentCache: { ...summary.agentCache, source: { ...summary.agentCache.source } } } : {})
     };
 }
 function activityFromSignals(options) {
+    if (options.agentStatus?.source === 'hook') {
+        return options.agentStatus.state === 'working' || options.agentStatus.state === 'finishing' ? 'busy' : 'idle';
+    }
     if (options.busy || options.recentOutput || options.agentStatus?.state === 'working') {
         return 'busy';
     }
@@ -1595,7 +2239,8 @@ function activityFromSignals(options) {
     return 'idle';
 }
 function agentStatusEquals(left, right) {
-    return left?.provider === right?.provider && left?.sessionId === right?.sessionId && left?.state === right?.state;
+    return left?.provider === right?.provider && left?.sessionId === right?.sessionId && left?.state === right?.state
+        && left?.source === right?.source && left?.revision === right?.revision && left?.epoch === right?.epoch;
 }
 function agentCacheEquals(left, right) {
     if (!left || !right) {
@@ -1626,6 +2271,14 @@ function isAgentRuntimeWrapperCommand(command) {
 function expectedAgentProvider(command, existingProvider) {
     return inferAgentProviderFromCommand(command) ?? (isAgentRuntimeWrapperCommand(command) ? existingProvider ?? null : null);
 }
+// Wrappers other than node keep their own name, so only an idle shell or the
+// other agent provider rules a pane out.
+function foregroundMayRunProvider(summary, provider) {
+    if (!summary.currentCommand)
+        return false;
+    const inferred = inferAgentProviderFromCommand(summary.currentCommand);
+    return inferred === null || inferred === provider;
+}
 function transcriptSourceMatchesForeground(summary, sourceProvider) {
     if (!summary.currentCommand) {
         return false;