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

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');

package/lib/types/retention.d.ts

@@ -0,0 +1,53 @@
+import type { SubprocessTerminalActivity } from '@deepseek-ai/dsh-subprocess';
+import type { TerminalRetentionFrame } from './types.ts';
+/** Validated Host timing policy for unattended terminal cleanup. */
+export interface TerminalRetentionPolicy {
+    readonly unattendedTimeoutMs: number;
+    readonly activityPollIntervalMs: number;
+    readonly cleanupRetryMs: number;
+}
+/** Exactly one owner orders holds, observation, and retryable process cleanup. */
+export declare class TerminalRetention {
+    private readonly policy;
+    private readonly inspect;
+    private readonly terminate;
+    private readonly failed;
+    private readonly lifetime;
+    private readonly holders;
+    private epoch;
+    private timer;
+    private observation;
+    private idle;
+    private closing;
+    private disposed;
+    private cleanup;
+    /**
+     * @param policy - deployment timing choices.
+     * @param inspect - fresh shell and owned-job observation.
+     * @param terminate - mark the identity closed, await process quiescence, and remove its owner record.
+     * @param failed - diagnostic sink for failed automatic cleanup.
+     */
+    constructor(policy: TerminalRetentionPolicy, inspect: () => Promise<SubprocessTerminalActivity>, terminate: () => Promise<void>, failed: (error: unknown) => void);
+    /**
+     * Hold one terminal for one physical Remote stream, independently of screen subscriptions.
+     * @param signal - transport generation lifetime.
+     * @returns acknowledgement followed by an open stream until cancellation or terminal closure.
+     */
+    retain(signal: AbortSignal): AsyncIterable<TerminalRetentionFrame>;
+    /** Invalidate outstanding idle observations before accepting input. */
+    invalidate(): void;
+    /**
+     * Start or join cleanup; failure keeps the identity closed and schedules one retry.
+     * @returns after owned process cleanup succeeds, or rejects with its failure.
+     */
+    close(): Promise<void>;
+    /**
+     * Stop timers and streams and await both observation and final cleanup.
+     * @returns after process quiescence; cleanup failure is reported to the disposing owner.
+     */
+    dispose(): Promise<void>;
+    private cancelTimer;
+    private schedule;
+    private observe;
+}
+//# sourceMappingURL=retention.d.ts.map

package/lib/types/retention.js

@@ -0,0 +1,153 @@
+/** Window holds and conservative idle reclamation for one terminal owner. */
+import { RemoteError } from '@deepseek-ai/dsh-typert-protocol';
+/** Exactly one owner orders holds, observation, and retryable process cleanup. */
+export class TerminalRetention {
+    policy;
+    inspect;
+    terminate;
+    failed;
+    lifetime = new AbortController();
+    holders = new Set();
+    epoch = 0;
+    timer;
+    observation;
+    idle;
+    closing = false;
+    disposed = false;
+    cleanup;
+    /**
+     * @param policy - deployment timing choices.
+     * @param inspect - fresh shell and owned-job observation.
+     * @param terminate - mark the identity closed, await process quiescence, and remove its owner record.
+     * @param failed - diagnostic sink for failed automatic cleanup.
+     */
+    constructor(policy, inspect, terminate, failed) {
+        this.policy = policy;
+        this.inspect = inspect;
+        this.terminate = terminate;
+        this.failed = failed;
+        this.schedule(0);
+    }
+    /**
+     * Hold one terminal for one physical Remote stream, independently of screen subscriptions.
+     * @param signal - transport generation lifetime.
+     * @returns acknowledgement followed by an open stream until cancellation or terminal closure.
+     */
+    async *retain(signal) {
+        signal.throwIfAborted();
+        if (this.closing || this.disposed)
+            throw new RemoteError('terminal/unavailable', 'Terminal is closing or unavailable', {});
+        const holder = {};
+        const ended = Promise.withResolvers();
+        const combined = AbortSignal.any([signal, this.lifetime.signal]);
+        const release = () => {
+            if (!this.holders.delete(holder))
+                return;
+            combined.removeEventListener('abort', release);
+            this.invalidate();
+            ended.resolve();
+            this.schedule(0);
+        };
+        this.holders.add(holder);
+        this.invalidate();
+        this.cancelTimer();
+        combined.addEventListener('abort', release, { once: true });
+        try {
+            yield { type: 'retained' };
+            await ended.promise;
+        }
+        finally {
+            release();
+        }
+    }
+    /** Invalidate outstanding idle observations before accepting input. */
+    invalidate() { this.epoch++; this.idle = undefined; }
+    /**
+     * Start or join cleanup; failure keeps the identity closed and schedules one retry.
+     * @returns after owned process cleanup succeeds, or rejects with its failure.
+     */
+    close() {
+        if (this.cleanup !== undefined)
+            return this.cleanup;
+        this.closing = true;
+        this.invalidate();
+        this.lifetime.abort(new Error('Terminal closed'));
+        this.cancelTimer();
+        this.cleanup = this.terminate().catch((error) => {
+            this.cleanup = undefined;
+            this.schedule(this.policy.cleanupRetryMs);
+            throw error;
+        });
+        return this.cleanup;
+    }
+    /**
+     * Stop timers and streams and await both observation and final cleanup.
+     * @returns after process quiescence; cleanup failure is reported to the disposing owner.
+     */
+    async dispose() {
+        this.disposed = true;
+        this.cancelTimer();
+        const observation = this.observation;
+        try {
+            await this.close();
+        }
+        finally {
+            await observation;
+        }
+    }
+    cancelTimer() { clearTimeout(this.timer); this.timer = undefined; }
+    schedule(delay) {
+        if (this.disposed || this.timer !== undefined)
+            return;
+        if (!this.closing && (this.holders.size > 0 || this.policy.unattendedTimeoutMs === 0))
+            return;
+        const due = performance.now() + delay;
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            const remaining = due - performance.now();
+            if (remaining > 0) {
+                this.schedule(remaining);
+                return;
+            }
+            if (this.closing) {
+                void this.close().catch(this.failed);
+                return;
+            }
+            this.observe();
+        }, Math.min(delay, 2_147_483_647));
+        this.timer.unref();
+    }
+    observe() {
+        if (this.observation !== undefined)
+            return;
+        const epoch = this.epoch;
+        this.observation = (async () => {
+            let activity;
+            try {
+                activity = await this.inspect();
+            }
+            catch (_activityUnavailable) {
+                activity = { state: 'unknown', revision: 0 };
+            }
+            if (this.disposed || this.closing || this.holders.size > 0 || epoch !== this.epoch)
+                return;
+            const now = performance.now();
+            if (activity.state !== 'idle') {
+                this.idle = undefined;
+                return;
+            }
+            if (this.idle?.revision !== activity.revision || now - this.idle.observedAt > this.policy.activityPollIntervalMs * 2) {
+                this.idle = { since: now, observedAt: now, revision: activity.revision };
+            }
+            else
+                this.idle.observedAt = now;
+            if (now - this.idle.since >= this.policy.unattendedTimeoutMs)
+                await this.close();
+        })().catch(this.failed).finally(() => {
+            this.observation = undefined;
+            if (!this.closing)
+                this.schedule(this.policy.activityPollIntervalMs);
+        });
+    }
+}
+//# sourceMappingURL=retention.js.map

package/lib/types/terminal.d.ts

@@ -1,5 +1,6 @@
 import type { SubprocessTerminalHandle } from '@deepseek-ai/dsh-subprocess';
-import type { TerminalAttachmentId, TerminalFrame, WebTerminalInfo } from './types.ts';
+import { type TerminalRetentionPolicy } from './retention.ts';
+import type { TerminalAttachmentId, TerminalFrame, TerminalRetentionFrame, WebTerminalInfo } from './types.ts';
 /** Process lifetime is independent of follower and component lifetimes. */
 export declare class BrowserTerminal {
     private readonly handle;
@@ -12,6 +13,7 @@ export declare class BrowserTerminal {
     private operations;
     private readonly drained;
     private closing;
+    private retention;
     private controller;
     /**
      * @param handle - allocated terminal process range.
@@ -20,6 +22,20 @@ export declare class BrowserTerminal {
      * @param maxBufferedBytes - per-follower queue cap.
      */
     constructor(handle: SubprocessTerminalHandle, info: WebTerminalInfo, scrollback: number, maxBufferedBytes: number);
+    /**
+     * Start monitoring after this allocation is committed to its Session owner.
+     * @param policy - validated Host timing policy.
+     * @param closing - closes the id before any asynchronous termination.
+     * @param closed - removes the exact successfully terminated owner record.
+     * @param failed - diagnostic sink for background cleanup failure.
+     */
+    monitor(policy: TerminalRetentionPolicy, closing: () => void, closed: () => void, failed: (error: unknown) => void): void;
+    /**
+     * Retain this committed process independently of output attachment.
+     * @param signal - physical window stream lifetime.
+     * @returns its hold acknowledgement and lifetime.
+     */
+    retain(signal: AbortSignal): AsyncIterable<TerminalRetentionFrame>;
     /**
      * Attach with exclusive input control; an older attachment becomes read-only.
      * @param id - browser attachment identity.
@@ -52,6 +68,12 @@ export declare class BrowserTerminal {
      * @returns after process cleanup and final output drainage; failures remain retryable.
      */
     close(): Promise<void>;
+    /**
+     * Stop unattended cleanup scheduling and await final process cleanup.
+     * @returns after terminal and monitor quiescence.
+     */
+    dispose(): Promise<void>;
+    private closeProcess;
     private requireController;
     private broadcast;
     private enqueue;

package/lib/types/terminal.js

@@ -1,15 +1,10 @@
 /** One PTY, a bounded terminal emulator and its detachable browser followers. */
-import { createRequire } from 'node:module';
 import { RemoteError } from '@deepseek-ai/dsh-typert-protocol';
+import { createLazyRequire } from '@deepseek-ai/dsh-lazy-require';
 import { TerminalFollower } from "./stream.js";
-const { Terminal, SerializeAddon } = loadXterm();
-function loadXterm() {
-    // The Preview's CommonJS wrapper owns its outer require binding; these literal calls also retain the CJS entries.
-    const require = createRequire(import.meta.url);
-    const { Terminal } = require('@xterm/headless');
-    const { SerializeAddon } = require('@xterm/addon-serialize');
-    return { Terminal, SerializeAddon };
-}
+import { TerminalRetention } from "./retention.js";
+const requireHeadless = createLazyRequire('@xterm/headless', import.meta.url);
+const requireSerialize = createLazyRequire('@xterm/addon-serialize', import.meta.url);
 /** Process lifetime is independent of follower and component lifetimes. */
 export class BrowserTerminal {
     handle;
@@ -22,6 +17,7 @@ export class BrowserTerminal {
     operations = Promise.resolve();
     drained;
     closing;
+    retention;
     controller;
     /**
      * @param handle - allocated terminal process range.
@@ -33,11 +29,37 @@ export class BrowserTerminal {
         this.handle = handle;
         this.info = info;
         this.maxBufferedBytes = maxBufferedBytes;
+        const { Terminal } = requireHeadless();
+        const { SerializeAddon } = requireSerialize();
         this.screen = new Terminal({ cols: info.cols, rows: info.rows, scrollback, allowProposedApi: true });
         this.serializer = new SerializeAddon();
         this.screen.loadAddon(this.serializer);
         this.drained = this.consume();
     }
+    /**
+     * Start monitoring after this allocation is committed to its Session owner.
+     * @param policy - validated Host timing policy.
+     * @param closing - closes the id before any asynchronous termination.
+     * @param closed - removes the exact successfully terminated owner record.
+     * @param failed - diagnostic sink for background cleanup failure.
+     */
+    monitor(policy, closing, closed, failed) {
+        this.retention = new TerminalRetention(policy, () => this.handle.inspectActivity(), async () => {
+            closing();
+            await this.closeProcess();
+            closed();
+        }, failed);
+    }
+    /**
+     * Retain this committed process independently of output attachment.
+     * @param signal - physical window stream lifetime.
+     * @returns its hold acknowledgement and lifetime.
+     */
+    retain(signal) {
+        if (this.retention === undefined)
+            throw new Error('Terminal has not been committed');
+        return this.retention.retain(signal);
+    }
     /**
      * Attach with exclusive input control; an older attachment becomes read-only.
      * @param id - browser attachment identity.
@@ -78,6 +100,7 @@ export class BrowserTerminal {
      * @returns when the provider accepts the input.
      */
     write(id, data) {
+        this.retention?.invalidate();
         return this.enqueue(async () => { this.requireController(id); await this.handle.write(data); });
     }
     /**
@@ -109,6 +132,14 @@ export class BrowserTerminal {
      * @returns after process cleanup and final output drainage; failures remain retryable.
      */
     close() {
+        return this.retention?.close() ?? this.closeProcess();
+    }
+    /**
+     * Stop unattended cleanup scheduling and await final process cleanup.
+     * @returns after terminal and monitor quiescence.
+     */
+    dispose() { return this.retention?.dispose() ?? this.closeProcess(); }
+    closeProcess() {
         if (this.closing !== undefined)
             return this.closing;
         this.closing = (async () => {

package/lib/types/types.d.ts

@@ -2,6 +2,8 @@
 import type { Branded } from '@deepseek-ai/dsh-brand';
 declare module '@deepseek-ai/dsh-typert-protocol' {
     interface RemoteErrorDetailsMap {
+        /** The terminal identity is missing or has begun process cleanup. */
+        'terminal/unavailable': Record<string, never>;
         /** Input or resize was refused without invalidating the output attachment. */
         'terminal/control-unavailable': {
             readonly reason: 'read-only' | 'not-running';
@@ -16,6 +18,10 @@ declare module '@deepseek-ai/dsh-typert-protocol' {
 export type WebTerminalId = Branded<'WebTerminalId'>;
 /** An attachment allowed to write and resize one terminal. */
 export type TerminalAttachmentId = Branded<'TerminalAttachmentId'>;
+/** Acknowledges one physical window hold without taking screen or input control. */
+export interface TerminalRetentionFrame {
+    readonly type: 'retained';
+}
 /** An executable shell verified in the subprocess provider's execution environment. */
 export interface TerminalShell {
     readonly path: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-api-terminal-controller",
   "description": "Session-owned interactive terminals with shell discovery, screen recovery and typed Remote control",
-  "version": "0.1.6-alpha.1",
+  "version": "0.1.7-alpha.1",
   "publishConfig": {
     "access": "public"
   },
@@ -53,28 +53,30 @@
     "@xterm/headless": "^6.0.0",
     "@xterm/addon-serialize": "^0.14.0",
     "zod": "^4.4.3",
-    "@deepseek-ai/dsh-deque": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-typert-protocol": "^0.1.6-alpha.1",
-    "@deepseek-ai/schemastery": "^3.18.2"
+    "@deepseek-ai/dsh-lazy-require": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-deque": "^0.1.7-alpha.1",
+    "@deepseek-ai/schemastery": "^3.18.3"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-subprocess": "^0.1.6-alpha.1",
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/dsh-subprocess": "^0.1.7-alpha.1",
+    "@deepseek-ai/cordis": "^4.0.3"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-agent": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-api-gateway": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-brand": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-client-store": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-fs": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-sandbox": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-sandbox-policy": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-session": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-session-projection": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-subprocess-local": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-util-crypto": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-subprocess": "^0.1.6-alpha.1"
+    "@deepseek-ai/cordis": "^4.0.3",
+    "@deepseek-ai/dsh-agent": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-brand": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-api-gateway": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-client-store": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-fs": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-remote-mock": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-sandbox": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-session-projection": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-session": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-subprocess": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-subprocess-local": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-util-crypto": "^0.1.7-alpha.1"
   },
   "files": [
     "lib/index.js",