@deepseek-ai/dsh-api-terminal-controller 0.1.6-alpha.1 → 0.1.6-alpha.2

package/lib/types/client/index.js

@@ -6,6 +6,8 @@ import { createSnapshotStore } from '@deepseek-ai/dsh-client-store';
 import { randomUUID } from '@deepseek-ai/dsh-util-crypto';
 import { preferredShell, rememberShell } from "./shell-preference.js";
 import { TerminalCloseRequests } from "./close-requests.js";
+import { TerminalWindowHold } from "./retention.js";
+import { TerminalBindings } from "./bindings.js";
 /** Session and occurrence lookup, independent tab and terminal identities and background cleanup. */
 export class ClientTerminals extends Service {
     remote;
@@ -16,6 +18,10 @@ export class ClientTerminals extends Service {
     closed = new Set(this.requests.pending().map(request => request.id));
     disposed = false;
     views = new Map();
+    bindings = new TerminalBindings();
+    holds = new Map();
+    releasing = new Set();
+    openTabs = [];
     /**
      * @param ctx - Client root Context with Gateway and terminal Remote namespace.
      * @param remote - generated terminal namespace.
@@ -27,7 +33,10 @@ export class ClientTerminals extends Service {
             this.disposed = true;
             const detaching = [...this.views.values()].flatMap(views => [...views.values()].map(view => view.dispose()));
             this.views.clear();
-            await Promise.all([...detaching, ...this.closing.values()]);
+            this.bindings.clear();
+            const holds = [...this.holds.values()].flatMap(holds => [...holds.values()].map(hold => hold.dispose()));
+            this.holds.clear();
+            await Promise.all([...detaching, ...holds, ...this.releasing, ...this.closing.values()]);
         }, 'terminal-controller.client.views');
         for (const request of this.requests.pending())
             this.cleanup(request);
@@ -36,11 +45,12 @@ export class ClientTerminals extends Service {
      * Return the stable model for one sidebar occurrence.
      * @param sessionId - owning Session.
      * @param key - sidebar occurrence key.
-     * @param terminalId - existing Host identity when restoring a listed terminal.
+     * @param contentId - globally unique content identity; layout-local tab ids are not persistence keys.
+     * @param terminalId - existing Host identity when restoring a listed terminal; otherwise reuse the saved content identity.
      * @param shellPath - explicit shell for a new terminal; restored terminals retain their own shell.
      * @returns its observable state and terminal commands.
      */
-    view(sessionId, key, terminalId, shellPath) {
+    view(sessionId, key, contentId, terminalId, shellPath) {
         let views = this.views.get(sessionId);
         if (views === undefined) {
             views = new Map();
@@ -48,9 +58,12 @@ export class ClientTerminals extends Service {
         }
         let view = views.get(key);
         if (view === undefined) {
-            const id = terminalId ?? randomUUID();
-            view = new TerminalView(sessionId, this.remote, this.ctx.remote, id, terminalId === undefined, shellPath);
+            const saved = terminalId ?? this.bindings.get(sessionId, contentId);
+            const id = saved ?? randomUUID();
+            this.bindings.set(sessionId, contentId, id);
+            view = new TerminalView(sessionId, this.remote, this.ctx.remote, id, saved === undefined, shellPath, signal => this.hold(sessionId, id).ready(signal));
             views.set(key, view);
+            this.reconcileHolds();
             void view.refresh();
         }
         return view;
@@ -77,24 +90,86 @@ export class ClientTerminals extends Service {
      * Save a close intent and release the tab immediately; cleanup outlives DOM unmount and reload.
      * @param sessionId - owning Session.
      * @param key - sidebar occurrence key, including an inactive restored tab.
+     * @param contentId - globally unique content identity whose binding is removed.
      * @param terminalId - restored identity if the tab has no model yet.
      */
-    close(sessionId, key, terminalId) {
+    close(sessionId, key, contentId, terminalId) {
         const views = this.views.get(sessionId);
         const view = views?.get(key);
-        const id = view?.id ?? terminalId;
+        const id = view?.id ?? terminalId ?? this.bindings.get(sessionId, contentId);
         if (id === undefined)
             return;
         const request = { sessionId, id, title: view?.state.getSnapshot().title ?? key };
         this.closed.add(id);
         this.requests.save(request);
+        this.bindings.delete(sessionId, contentId);
         views?.delete(key);
         if (views?.size === 0)
             this.views.delete(sessionId);
         this.cleanup(request, view);
+        this.reconcileHolds();
     }
     /**
-     * Query Host terminals that have neither a tab in this page nor an unfinished close.
+     * Reconcile this window's open terminal occurrences, including dormant saved Sessions.
+     * @param tabs - terminal-kind membership supplied by the sidebar layout owner.
+     */
+    retainTabs(tabs) {
+        this.openTabs = tabs;
+        this.reconcileHolds();
+    }
+    hold(sessionId, id) {
+        let holds = this.holds.get(sessionId);
+        if (holds === undefined) {
+            holds = new Map();
+            this.holds.set(sessionId, holds);
+        }
+        let hold = holds.get(id);
+        if (hold === undefined || hold.failed) {
+            if (hold !== undefined)
+                this.release(hold);
+            hold = new TerminalWindowHold(this.ctx.remote, this.remote, sessionId, id);
+            holds.set(id, hold);
+        }
+        return hold;
+    }
+    reconcileHolds() {
+        if (this.disposed)
+            return;
+        const wanted = new Map();
+        for (const tab of this.openTabs) {
+            const id = this.bindings.get(tab.sessionId, tab.contentId);
+            if (id === undefined || this.closed.has(id))
+                continue;
+            let ids = wanted.get(tab.sessionId);
+            if (ids === undefined) {
+                ids = new Set();
+                wanted.set(tab.sessionId, ids);
+            }
+            ids.add(id);
+            const view = this.views.get(tab.sessionId)?.get(tab.tabId);
+            if (view === undefined || view.state.getSnapshot().info !== undefined) {
+                if (!this.holds.get(tab.sessionId)?.has(id))
+                    this.hold(tab.sessionId, id);
+            }
+        }
+        for (const [sessionId, holds] of this.holds) {
+            for (const [id, hold] of holds) {
+                if (!wanted.get(sessionId)?.has(id)) {
+                    holds.delete(id);
+                    this.release(hold);
+                }
+            }
+            if (holds.size === 0)
+                this.holds.delete(sessionId);
+        }
+    }
+    release(hold) {
+        const releasing = hold.dispose().finally(() => { this.releasing.delete(releasing); });
+        this.releasing.add(releasing);
+        void releasing.catch((error) => { this.ctx.logger.warn('Terminal hold release failed', error); });
+    }
+    /**
+     * Query Host terminals without a live view or unfinished close.
      * @param sessionId - Session being displayed.
      * @returns terminals available for opening as recovered tabs.
      */

package/lib/types/client/model.d.ts

@@ -40,6 +40,7 @@ export declare class TerminalView {
     readonly id: WebTerminalId;
     private readonly createWhenMissing;
     private readonly shellPath?;
+    private readonly retain?;
     /** Observable controls, process metadata and the next screen update awaiting acknowledgement. */
     readonly state: SnapshotStore<TerminalViewState>;
     private readonly lifetime;
@@ -61,8 +62,9 @@ export declare class TerminalView {
      * @param id - Host terminal identity, reused when recovering an item from its Session list.
      * @param createWhenMissing - allow allocation only for a new tab, never a listed terminal.
      * @param shellPath - explicit shell chosen at the guide; omission uses the remembered available shell.
+     * @param retain - window hold acknowledgement required before output attachment.
      */
-    constructor(sessionId: SessionId, remote: TerminalRemote, gateway: Pick<ClientRemote, '$stream'>, id: WebTerminalId, createWhenMissing?: boolean, shellPath?: string | undefined);
+    constructor(sessionId: SessionId, remote: TerminalRemote, gateway: Pick<ClientRemote, '$stream'>, id: WebTerminalId, createWhenMissing?: boolean, shellPath?: string | undefined, retain?: ((signal: AbortSignal) => Promise<void>) | undefined);
     /**
      * Attach the DOM lifetime, starting the chosen shell or reconnecting the saved process.
      * @returns a detach callback that leaves the terminal process alive.

package/lib/types/client/model.js

@@ -15,6 +15,7 @@ export class TerminalView {
     id;
     createWhenMissing;
     shellPath;
+    retain;
     /** Observable controls, process metadata and the next screen update awaiting acknowledgement. */
     state = createSnapshotStore({ phase: 'idle', writable: false });
     lifetime = new AbortController();
@@ -36,14 +37,16 @@ export class TerminalView {
      * @param id - Host terminal identity, reused when recovering an item from its Session list.
      * @param createWhenMissing - allow allocation only for a new tab, never a listed terminal.
      * @param shellPath - explicit shell chosen at the guide; omission uses the remembered available shell.
+     * @param retain - window hold acknowledgement required before output attachment.
      */
-    constructor(sessionId, remote, gateway, id, createWhenMissing = true, shellPath) {
+    constructor(sessionId, remote, gateway, id, createWhenMissing = true, shellPath, retain) {
         this.sessionId = sessionId;
         this.remote = remote;
         this.gateway = gateway;
         this.id = id;
         this.createWhenMissing = createWhenMissing;
         this.shellPath = shellPath;
+        this.retain = retain;
     }
     /**
      * Attach the DOM lifetime, starting the chosen shell or reconnecting the saved process.
@@ -117,8 +120,16 @@ export class TerminalView {
     }
     adopt(info) {
         this.patch({ info, title: info.title });
-        if (this.mounted && this.closing === undefined)
-            this.connect();
+        if (this.retain === undefined) {
+            if (this.mounted && this.closing === undefined)
+                this.connect();
+            return;
+        }
+        void this.retain(this.lifetime.signal).then(() => {
+            if (this.mounted && this.closing === undefined)
+                this.connect();
+        }).catch((error) => { if (!this.stopped())
+            this.fail(error); });
     }
     /** Reattach with a fresh screen and regain input control. */
     connect() {
@@ -128,11 +139,13 @@ export class TerminalView {
         this.detach();
         const stream = this.gateway.$stream({
             name: 'Browser terminal output',
-            open: (signal) => {
+            open: async function* (signal) {
+                await this.retain?.(signal);
+                signal.throwIfAborted();
                 const attachmentId = randomUUID();
                 this.attachmentId = attachmentId;
-                return this.remote.follow(this.sessionId, info.id, attachmentId, signal);
-            },
+                yield* this.remote.follow(this.sessionId, info.id, attachmentId, signal);
+            }.bind(this),
             ended: () => new TerminalViewError('attachmentEnded'),
             carrierFailed: () => { if (this.stream === stream)
                 this.patch({ phase: 'disconnected', writable: false }); },
@@ -311,7 +324,7 @@ export class TerminalView {
             this.patch({ writable: false, error: undefined, issue: undefined });
             return;
         }
-        const issue = failure?.code === 'terminal/view' ? failure.details.issue : failure?.code === 'terminal/limit-reached' ? 'terminalLimit' : undefined;
+        const issue = failure?.code === 'terminal/view' ? failure.details.issue : failure?.code === 'terminal/limit-reached' ? 'terminalLimit' : failure?.code === 'terminal/unavailable' ? 'missingTerminal' : undefined;
         this.patch({ phase: error instanceof RemoteStreamCarrierError ? 'disconnected' : 'failed', writable: false, issue, error: error instanceof Error ? error.message : String(error) });
     }
 }

package/lib/types/client/retention.d.ts

@@ -0,0 +1,35 @@
+/** One reconnecting window hold, shared by all occurrences of a terminal. */
+import type { ClientRemote } from '@deepseek-ai/dsh-api-gateway/client';
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { WebTerminalId } from '../types.ts';
+import type { TerminalRemote } from './model.ts';
+/** A stream acknowledgement gates output attachment for each physical connection. */
+export declare class TerminalWindowHold {
+    private readonly stream;
+    private readonly waiters;
+    private generation;
+    private failure;
+    /**
+     * @param gateway - reconnecting stream owner.
+     * @param remote - typed terminal namespace.
+     * @param sessionId - saved layout's Session, without Agent activation.
+     * @param id - existing Host terminal.
+     */
+    constructor(gateway: Pick<ClientRemote, '$stream'>, remote: TerminalRemote, sessionId: SessionId, id: WebTerminalId);
+    /** Whether a terminal-domain failure ended this hold, allowing an explicit retry. */
+    get failed(): boolean;
+    /**
+     * Wait for an acknowledged current physical hold before following its screen.
+     * @param signal - output request or view lifetime.
+     * @returns after acknowledgement, or rejects on cancellation/unavailability.
+     */
+    ready(signal: AbortSignal): Promise<void>;
+    /**
+     * Release this window's stream and all acknowledgement waiters.
+     * @returns after the stream consumer closes.
+     */
+    dispose(): Promise<void>;
+    private consume;
+    private reject;
+}
+//# sourceMappingURL=retention.d.ts.map

package/lib/types/client/retention.js

@@ -0,0 +1,77 @@
+import { RemoteError } from '@deepseek-ai/dsh-typert-protocol';
+/** A stream acknowledgement gates output attachment for each physical connection. */
+export class TerminalWindowHold {
+    stream;
+    waiters = new Set();
+    generation;
+    failure;
+    /**
+     * @param gateway - reconnecting stream owner.
+     * @param remote - typed terminal namespace.
+     * @param sessionId - saved layout's Session, without Agent activation.
+     * @param id - existing Host terminal.
+     */
+    constructor(gateway, remote, sessionId, id) {
+        this.stream = gateway.$stream({
+            name: 'Browser terminal window hold',
+            open: signal => remote.retain(sessionId, id, signal),
+            ended: () => new RemoteError('terminal/unavailable', 'Terminal hold ended', {}),
+        });
+        void this.consume();
+    }
+    /** Whether a terminal-domain failure ended this hold, allowing an explicit retry. */
+    get failed() { return this.failure !== undefined; }
+    /**
+     * Wait for an acknowledged current physical hold before following its screen.
+     * @param signal - output request or view lifetime.
+     * @returns after acknowledgement, or rejects on cancellation/unavailability.
+     */
+    async ready(signal) {
+        signal.throwIfAborted();
+        if (this.failure !== undefined)
+            throw this.failure;
+        if (this.generation !== undefined && !this.generation.aborted)
+            return;
+        const waiting = Promise.withResolvers();
+        const abort = () => { waiting.reject(signal.reason); };
+        this.waiters.add(waiting);
+        signal.addEventListener('abort', abort, { once: true });
+        try {
+            await waiting.promise;
+        }
+        finally {
+            this.waiters.delete(waiting);
+            signal.removeEventListener('abort', abort);
+        }
+    }
+    /**
+     * Release this window's stream and all acknowledgement waiters.
+     * @returns after the stream consumer closes.
+     */
+    dispose() {
+        this.reject(new Error('Terminal window hold released'));
+        return this.stream.dispose();
+    }
+    async consume() {
+        try {
+            for await (const item of this.stream) {
+                item.accept();
+                this.generation = item.signal;
+                for (const waiter of this.waiters)
+                    waiter.resolve();
+                this.waiters.clear();
+            }
+        }
+        catch (error) {
+            this.reject(error);
+        }
+    }
+    reject(error) {
+        this.failure = error instanceof Error ? error : new Error('Terminal window hold failed', { cause: error });
+        this.generation = undefined;
+        for (const waiter of this.waiters)
+            waiter.reject(error);
+        this.waiters.clear();
+    }
+}
+//# sourceMappingURL=retention.js.map

package/lib/types/index.d.ts

@@ -1,10 +1,10 @@
-/** Session-scoped browser terminals over the composed subprocess and sandbox providers. */
+/** Session-owned user terminals with the execution environment's system-user permissions. */
 import type { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
 import type { Agent } from '@deepseek-ai/dsh-agent';
 import type { SessionId } from '@deepseek-ai/dsh-session';
 import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
-import type { TerminalShell, TerminalAttachmentId, TerminalCreateRequest, TerminalEnvironment, TerminalFrame, WebTerminalId, WebTerminalInfo } from './types.ts';
+import type { TerminalShell, TerminalAttachmentId, TerminalCreateRequest, TerminalEnvironment, TerminalFrame, TerminalRetentionFrame, WebTerminalId, WebTerminalInfo } from './types.ts';
 export type * from './types.ts';
 declare module '@deepseek-ai/cordis' {
     interface Context {
@@ -39,6 +39,12 @@ export interface Config {
     readonly maxInputBytes: number;
     /** Provider process-termination grace period in milliseconds. */
     readonly disposeGraceMs: number;
+    /** Continuous confirmed idle time without window holds before reclamation; zero disables reclamation. */
+    readonly unattendedTimeoutMs: number;
+    /** Interval between unattended shell and process observations. */
+    readonly activityPollIntervalMs: number;
+    /** Delay before retrying failed owned terminal cleanup. */
+    readonly cleanupRetryMs: number;
 }
 /** Typed Remote control of transient Session-owned terminal processes. */
 export declare class TerminalController extends TypertRemoteService {
@@ -73,13 +79,21 @@ export declare class TerminalController extends TypertRemoteService {
      */
     list(sessionId: SessionId): WebTerminalInfo[];
     /**
-     * Allocate an interactive shell once for a caller-generated identity.
+     * Allocate a user shell once for a caller-generated identity, without Agent sandbox or approval restrictions.
      * @param agent - Session owner supplied by the Gateway.
      * @param request - initial dimensions and idempotency identity.
      * @param signal - allocation cancellation; committed terminals survive disconnection.
      * @returns the existing or newly committed terminal.
      */
     create(agent: Agent, request: TerminalCreateRequest, signal: AbortSignal): Promise<WebTerminalInfo>;
+    /**
+     * Retain an existing terminal for a window without activating its Agent or taking input control.
+     * @param sessionId - owning Session identity, including an inactive saved layout.
+     * @param id - retained Host terminal identity.
+     * @param signal - physical Remote stream cancellation.
+     * @returns a hold acknowledgement followed by an open lifetime stream.
+     */
+    retain(sessionId: SessionId, id: WebTerminalId, signal: AbortSignal): AsyncIterable<TerminalRetentionFrame>;
     /**
      * Attach to a terminal without binding its process lifetime to the transport.
      * @param agent - Session owner supplied by the Gateway.

package/lib/types/index.js

@@ -36,6 +36,7 @@ import z from '@deepseek-ai/schemastery';
 import { Remote, RemoteError, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
 import { discoverShells, resolveShell } from "./shells.js";
 import { BrowserTerminal } from "./terminal.js";
+import { TerminalRetention } from "./retention.js";
 /** Typed Remote control of transient Session-owned terminal processes. */
 let TerminalController = (() => {
     let _classSuper = TypertRemoteService;
@@ -44,6 +45,7 @@ let TerminalController = (() => {
     let _shells_decorators;
     let _list_decorators;
     let _create_decorators;
+    let _retain_decorators;
     let _follow_decorators;
     let _write_decorators;
     let _resize_decorators;
@@ -56,6 +58,7 @@ let TerminalController = (() => {
             _shells_decorators = [Remote];
             _list_decorators = [Remote];
             _create_decorators = [Remote];
+            _retain_decorators = [Remote({ mode: 'stream' })];
             _follow_decorators = [Remote({ mode: 'stream' })];
             _write_decorators = [Remote];
             _resize_decorators = [Remote];
@@ -65,6 +68,7 @@ let TerminalController = (() => {
             __esDecorate(this, null, _shells_decorators, { kind: "method", name: "shells", static: false, private: false, access: { has: obj => "shells" in obj, get: obj => obj.shells }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _list_decorators, { kind: "method", name: "list", static: false, private: false, access: { has: obj => "list" in obj, get: obj => obj.list }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _create_decorators, { kind: "method", name: "create", static: false, private: false, access: { has: obj => "create" in obj, get: obj => obj.create }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _retain_decorators, { kind: "method", name: "retain", static: false, private: false, access: { has: obj => "retain" in obj, get: obj => obj.retain }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _follow_decorators, { kind: "method", name: "follow", static: false, private: false, access: { has: obj => "follow" in obj, get: obj => obj.follow }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _write_decorators, { kind: "method", name: "write", static: false, private: false, access: { has: obj => "write" in obj, get: obj => obj.write }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _resize_decorators, { kind: "method", name: "resize", static: false, private: false, access: { has: obj => "resize" in obj, get: obj => obj.resize }, metadata: _metadata }, null, _instanceExtraInitializers);
@@ -73,7 +77,7 @@ let TerminalController = (() => {
             if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
         }
         config = __runInitializers(this, _instanceExtraInitializers);
-        static inject = ['subprocess', 'sandboxPolicy', 'sessionProjections', 'typert'];
+        static inject = ['subprocess', 'sandboxPolicy', 'typert'];
         static Config = z.object({
             shell: z.union([z.object({
                     path: z.string().required(), name: z.string().required(), args: z.array(z.string()).default([]),
@@ -86,6 +90,9 @@ let TerminalController = (() => {
             maxBufferedBytes: z.number().step(1).min(1024).default(2 * 1024 * 1024),
             maxInputBytes: z.number().step(1).min(1).default(64 * 1024),
             disposeGraceMs: z.number().step(1).min(1).default(1000),
+            unattendedTimeoutMs: z.number().step(1).min(0).max(Number.MAX_SAFE_INTEGER).default(7_200_000),
+            activityPollIntervalMs: z.number().step(1).min(1).max(Number.MAX_SAFE_INTEGER).default(30_000),
+            cleanupRetryMs: z.number().step(1).min(1).max(Number.MAX_SAFE_INTEGER).default(60_000),
         });
         owners = new Map();
         lifetime = new AbortController();
@@ -96,19 +103,6 @@ let TerminalController = (() => {
         constructor(ctx, config) {
             super(ctx, 'terminalController', { namespace: 'terminal' });
             this.config = config;
-            ctx.on('internal/dispatch', (_mode, eventName, args) => {
-                if (eventName !== 'session/event')
-                    return;
-                const [session, event] = args;
-                if (event.type !== 'sandbox/mode')
-                    return;
-                const owner = this.owners.get(session.id);
-                if (owner === undefined || owner.terminals.size + owner.pending.size + owner.allocations.size === 0)
-                    return;
-                const current = ctx.sessionProjections.stateOf(session, 'sandboxMode') ?? ctx.sandboxPolicy.defaultMode;
-                if (event.data.mode !== current)
-                    throw new Error('Close browser terminals before changing the Session sandbox mode');
-            }, { global: true });
             ctx.effect(() => async () => {
                 this.lifetime.abort(new Error('Terminal controller disposed'));
                 const results = await Promise.allSettled([...this.owners].map(([id, owner]) => this.disposeOwner(id, owner)));
@@ -126,7 +120,7 @@ let TerminalController = (() => {
         environment(agent, signal) {
             signal.throwIfAborted();
             const { sandboxPolicy } = this.execution(agent);
-            return { cwd: sandboxPolicy.resolve({ session: agent.session }).workspaceRoot,
+            return { cwd: agent.session.header.cwd ?? sandboxPolicy.workspaceRoot,
                 maxInputBytes: this.config.maxInputBytes, maxCols: this.config.maxCols,
                 maxRows: this.config.maxRows, scrollback: this.config.scrollback };
         }
@@ -152,7 +146,7 @@ let TerminalController = (() => {
             return [...owner.terminals.values(), ...owner.allocations.values()].map(terminal => terminal.info);
         }
         /**
-         * Allocate an interactive shell once for a caller-generated identity.
+         * Allocate a user shell once for a caller-generated identity, without Agent sandbox or approval restrictions.
          * @param agent - Session owner supplied by the Gateway.
          * @param request - initial dimensions and idempotency identity.
          * @param signal - allocation cancellation; committed terminals survive disconnection.
@@ -175,8 +169,6 @@ let TerminalController = (() => {
                 this.requireOpen(owner, request.id);
                 return terminal.info;
             }
-            if (owner.allocations.has(request.id))
-                throw new Error('Close the failed terminal allocation before creating it again');
             if (new Set([...owner.terminals.keys(), ...owner.pending.keys(), ...owner.allocations.keys()]).size >= this.config.maxTerminals)
                 throw new RemoteError('terminal/limit-reached', 'Session terminal limit reached', { limit: this.config.maxTerminals });
             const allocation = this.spawn(agent, owner, request, AbortSignal.any([signal, this.lifetime.signal, owner.lifetime.signal]));
@@ -185,6 +177,9 @@ let TerminalController = (() => {
                 const terminal = await allocation;
                 owner.terminals.set(request.id, terminal);
                 owner.allocations.delete(request.id);
+                terminal.monitor(this.config, () => { owner.closedIds.add(request.id); }, () => {
+                    owner.terminals.delete(request.id);
+                }, (error) => { this.ctx.logger.error('Browser terminal cleanup failed', error); });
                 this.requireOpen(owner, request.id);
                 return terminal.info;
             }
@@ -192,6 +187,21 @@ let TerminalController = (() => {
                 owner.pending.delete(request.id);
             }
         }
+        /**
+         * Retain an existing terminal for a window without activating its Agent or taking input control.
+         * @param sessionId - owning Session identity, including an inactive saved layout.
+         * @param id - retained Host terminal identity.
+         * @param signal - physical Remote stream cancellation.
+         * @returns a hold acknowledgement followed by an open lifetime stream.
+         */
+        retain(sessionId, id, signal) {
+            const owner = this.owners.get(sessionId);
+            const terminal = owner?.terminals.get(id);
+            if (terminal === undefined || owner?.closedIds.has(id) === true || owner?.lifetime.signal.aborted === true) {
+                throw new RemoteError('terminal/unavailable', 'Terminal is closing or unavailable', {});
+            }
+            return terminal.retain(signal);
+        }
         /**
          * Attach to a terminal without binding its process lifetime to the transport.
          * @param agent - Session owner supplied by the Gateway.
@@ -262,7 +272,7 @@ let TerminalController = (() => {
                 const allocation = owner.allocations.get(id);
                 if (allocation === undefined)
                     return;
-                await allocation.handle.terminate();
+                await allocation.cleanup.close();
                 owner.allocations.delete(id);
             }
         }
@@ -283,8 +293,8 @@ let TerminalController = (() => {
             owner.cleanup = (async () => {
                 await Promise.allSettled(owner.pending.values());
                 const results = await Promise.allSettled([
-                    ...[...owner.terminals.values()].map(terminal => terminal.close()),
-                    ...[...owner.allocations.values()].map(allocation => allocation.handle.terminate()),
+                    ...[...owner.terminals.values()].map(terminal => terminal.dispose()),
+                    ...[...owner.allocations.values()].map(allocation => allocation.cleanup.dispose()),
                 ]);
                 const errors = results.filter(result => result.status === 'rejected').map(result => result.reason);
                 if (errors.length > 0)
@@ -298,12 +308,13 @@ let TerminalController = (() => {
         terminal(agent, id) {
             const terminal = this.owners.get(agent.id)?.terminals.get(id);
             if (terminal === undefined)
-                throw new Error('Terminal no longer exists in this Session');
+                throw new RemoteError('terminal/unavailable', 'Terminal no longer exists in this Session', {});
+            this.requireOpen(this.owners.get(agent.id), id);
             return terminal;
         }
         requireOpen(owner, id) {
             if (owner.closedIds.has(id))
-                throw new Error('Terminal was closed in this Session');
+                throw new RemoteError('terminal/unavailable', 'Terminal was closed in this Session', {});
         }
         dimensions(cols, rows) {
             if (!Number.isSafeInteger(cols) || cols < 2 || cols > this.config.maxCols
@@ -320,42 +331,37 @@ let TerminalController = (() => {
         }
         async spawn(agent, owner, request, signal) {
             const environment = this.environment(agent, signal);
-            const { subprocess, sandboxPolicy } = this.execution(agent);
+            const { subprocess } = this.execution(agent);
             const shell = request.shellPath === undefined
                 ? await resolveShell(subprocess, this.config.shell, signal)
                 : (await this.shells(agent, signal)).find(candidate => candidate.path === request.shellPath);
             if (shell === undefined)
                 throw new Error('Selected shell is not available in this execution environment');
-            const policy = sandboxPolicy.resolve({ session: agent.session });
-            let argv = [shell.path, ...shell.args];
-            if (policy.mode !== 'danger-full-access') {
-                const sandbox = agent.ctx.get('sandbox');
-                if (sandbox === undefined)
-                    throw new Error('The Session sandbox mode requires an execution sandbox provider');
-                argv = (await sandbox.confine(argv, { ...policy, mode: policy.mode }, signal)).argv;
-            }
             const handle = await subprocess.spawnTerminal({
-                argv, cwd: environment.cwd, cols: request.cols, rows: request.rows,
+                argv: [shell.path, ...shell.args], cwd: environment.cwd, cols: request.cols, rows: request.rows,
                 terminalType: 'xterm-256color', env: { DSH_SESSION_ID: agent.id },
+                shellActivity: true,
                 graceMs: this.config.disposeGraceMs, signal,
             });
-            const allocation = {
-                handle,
-                info: {
-                    id: request.id, shell, title: shell.name, cwd: environment.cwd,
-                    cols: request.cols, rows: request.rows, state: 'running', exitCode: null,
-                },
+            const info = {
+                id: request.id, shell, title: shell.name, cwd: environment.cwd,
+                cols: request.cols, rows: request.rows, state: 'running', exitCode: null,
             };
-            owner.allocations.set(request.id, allocation);
             try {
                 signal.throwIfAborted();
-                return new BrowserTerminal(handle, allocation.info, this.config.scrollback, this.config.maxBufferedBytes);
+                return new BrowserTerminal(handle, info, this.config.scrollback, this.config.maxBufferedBytes);
             }
             catch (error) {
-                allocation.info = { ...allocation.info, state: 'failed', error: error instanceof Error ? error.message : String(error) };
-                try {
+                const cleanup = new TerminalRetention(this.config, handle.inspectActivity.bind(handle), async () => {
+                    owner.closedIds.add(request.id);
                     await handle.terminate();
                     owner.allocations.delete(request.id);
+                }, (cleanupError) => { this.ctx.logger.error('Browser terminal allocation cleanup failed', cleanupError); });
+                owner.allocations.set(request.id, {
+                    info: { ...info, state: 'failed', error: error instanceof Error ? error.message : String(error) }, cleanup,
+                });
+                try {
+                    await cleanup.close();
                 }
                 catch (cleanupError) {
                     throw new AggregateError([error, cleanupError], 'Terminal allocation cleanup failed');