@xenosystem/agent-interface-host 0.1.4 → 0.1.6

package/dist/session/nativeTuiSessionPty.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nativeTuiSessionPty.js","sourceRoot":"","sources":["../../src/session/nativeTuiSessionPty.ts"],"names":[],"mappings":"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"}

package/dist/session/nodePtyLoader.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The one place `node-pty` is loaded.
+ *
+ * Lazy and failure-tolerant on purpose: it is a native module, it is absent in
+ * a headless or web composition, and a host that cannot load it must still
+ * serve every other method rather than fail to construct.
+ *
+ * 🔴 Extracted rather than copied. `WorkspaceHostService` had this logic
+ * inline, and the `native-tui` session PTY needs exactly the same thing — two
+ * copies of "how do we load the native terminal, and what do we say when we
+ * cannot" is how the two come to disagree about whether a terminal is
+ * available.
+ */
+export type NodePtyModule = typeof import('node-pty');
+export interface NodePtyLoad {
+    module: NodePtyModule | null;
+    /** Why not, when not — never a bare null. */
+    error: string | null;
+}
+export declare function loadNodePty(): Promise<NodePtyLoad>;
+/** Test seam. Never called in production — the cache is process-lifetime. */
+export declare function resetNodePtyLoaderForTests(): void;
+//# sourceMappingURL=nodePtyLoader.d.ts.map

package/dist/session/nodePtyLoader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodePtyLoader.d.ts","sourceRoot":"","sources":["../../src/session/nodePtyLoader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,aAAa,GAAG,cAAc,UAAU,CAAC,CAAA;AAErD,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,aAAa,GAAG,IAAI,CAAA;IAC5B,6CAA6C;IAC7C,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CACrB;AAID,wBAAgB,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,CAqBlD;AAED,6EAA6E;AAC7E,wBAAgB,0BAA0B,IAAI,IAAI,CAEjD"}

package/dist/session/nodePtyLoader.js

@@ -0,0 +1,41 @@
+/**
+ * The one place `node-pty` is loaded.
+ *
+ * Lazy and failure-tolerant on purpose: it is a native module, it is absent in
+ * a headless or web composition, and a host that cannot load it must still
+ * serve every other method rather than fail to construct.
+ *
+ * 🔴 Extracted rather than copied. `WorkspaceHostService` had this logic
+ * inline, and the `native-tui` session PTY needs exactly the same thing — two
+ * copies of "how do we load the native terminal, and what do we say when we
+ * cannot" is how the two come to disagree about whether a terminal is
+ * available.
+ */
+let cached;
+export function loadNodePty() {
+    if (!cached) {
+        cached = import('node-pty')
+            .then((loaded) => {
+            const namespace = loaded;
+            const module = (namespace.default || namespace);
+            // Present-but-wrong is a real case: a stub, a browser shim, or a build
+            // that resolved the package without its native binding.
+            if (typeof module.spawn !== 'function') {
+                throw new Error('node-pty did not expose a spawn function.');
+            }
+            return { module, error: null };
+        })
+            .catch((error) => ({
+            module: null,
+            error: error instanceof Error && error.message.trim()
+                ? error.message.slice(0, 1_000)
+                : 'Failed to load node-pty.',
+        }));
+    }
+    return cached;
+}
+/** Test seam. Never called in production — the cache is process-lifetime. */
+export function resetNodePtyLoaderForTests() {
+    cached = undefined;
+}
+//# sourceMappingURL=nodePtyLoader.js.map

package/dist/session/nodePtyLoader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodePtyLoader.js","sourceRoot":"","sources":["../../src/session/nodePtyLoader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAUH,IAAI,MAAwC,CAAA;AAE5C,MAAM,UAAU,WAAW;IACzB,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,GAAG,MAAM,CAAC,UAAU,CAAC;aACxB,IAAI,CAAC,CAAC,MAAe,EAAE,EAAE;YACxB,MAAM,SAAS,GAAG,MAA8D,CAAA;YAChF,MAAM,MAAM,GAAG,CAAC,SAAS,CAAC,OAAO,IAAI,SAAS,CAAkB,CAAA;YAChE,uEAAuE;YACvE,wDAAwD;YACxD,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;gBACvC,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAA;YAC9D,CAAC;YACD,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;QAChC,CAAC,CAAC;aACD,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE,CAAC,CAAC;YAC1B,MAAM,EAAE,IAAI;YACZ,KAAK,EAAE,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE;gBACnD,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC;gBAC/B,CAAC,CAAC,0BAA0B;SAC/B,CAAC,CAAC,CAAA;IACP,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,0BAA0B;IACxC,MAAM,GAAG,SAAS,CAAA;AACpB,CAAC"}

package/dist/session/renderSupport.d.ts

@@ -15,6 +15,22 @@ import type { AgentRenderSupport } from '@xenosystem/agent-interface-core';
  * PTY lane is built it replaces this function, and `renderSupportFor`'s tests
  * already prove a `true` answer flows through — so the day it lands, the mode
  * becomes available by construction instead of by someone remembering.
+ *
+ * ⚠️ That claim was NOT true until 2026-08-24, and the way it was false is
+ * worth keeping. Construction reached as far as this file and stopped one
+ * caller short, in two places at once:
+ *
+ *   1. `AgentHostCoordinator` never accepted a `nativeTuiLane`, so no
+ *      composition could reach the seam. Injectable and unreachable.
+ *   2. `openSessionForRun` built the ACP protocol channel UNCONDITIONALLY,
+ *      and `open()` refuses `native-tui` when one is present — so a lane
+ *      returning true would have made every session on that provider fail
+ *      with `protocol_channel_forbidden`.
+ *
+ * Both are fixed and mutation-checked at the caller. The lesson generalises:
+ * a seam proves a value can flow THROUGH the function that declares it, never
+ * that anything calls that function correctly. `renderSupport.test.ts` proved
+ * the first and read as proving the second.
  */
 export declare function noNativeTuiLane(): boolean;
 export interface RenderSupportOptions {
@@ -48,6 +64,24 @@ export interface RenderSupportOptions {
  * A provider no adapter supports gets `{ nativeTui: false, acp: false }`, and
  * `selectSessionRenderMode` REFUSES it by name. That is the honest outcome: the
  * alternative is a session that opens, renders nothing, and reports no error.
+ *
+ * 🔴 AND BEING BLOCKED COUNTS AS "cannot run" — measured 2026-08-24.
+ *
+ * `AcpAgentTurnExecutionAdapter.supports()` is `provider.kind === 'acp'`. It
+ * answers "is this the right KIND", not "can this actually run", so a blocked
+ * endpoint reported `acp: true` and, with a TUI present, `switchable: true` —
+ * a toggle that switched into an empty terminal.
+ *
+ * Latent until now, because a blocked provider cannot start a turn and no
+ * session was ever opened for one. It stops being latent the moment a TUI-only
+ * agent is registered — Grok Build, agy and opencode have no ACP adapter in
+ * `xeno-acp`, so they arrive blocked AND with a real interface, which is
+ * exactly the combination that had no honest answer.
+ *
+ * Fixed HERE rather than in `supports()`: that predicate also routes turn
+ * EXECUTION, and narrowing it would change which adapter is found for a run
+ * that is refused for other reasons. This question — "can we render this
+ * agent's structured stream" — is the one that needs the stricter answer.
  */
 export declare function renderSupportFor(provider: AgentRuntimeProviderDescriptor, options: RenderSupportOptions): AgentRenderSupport;
 //# sourceMappingURL=renderSupport.d.ts.map

package/dist/session/renderSupport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"renderSupport.d.ts","sourceRoot":"","sources":["../../src/session/renderSupport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,sCAAsC,CAAA;AAC1F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAA;AAE1E;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAEzC;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;;;OAUG;IACH,QAAQ,EAAE,SAAS;QAAE,QAAQ,CAAC,QAAQ,EAAE,8BAA8B,GAAG,OAAO,CAAA;KAAE,EAAE,CAAA;IACpF,+EAA+E;IAC/E,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,8BAA8B,KAAK,OAAO,CAAA;CACtE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,8BAA8B,EACxC,OAAO,EAAE,oBAAoB,GAC5B,kBAAkB,CAMpB"}
+{"version":3,"file":"renderSupport.d.ts","sourceRoot":"","sources":["../../src/session/renderSupport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,sCAAsC,CAAA;AAC1F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAA;AAE1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAEzC;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;;;OAUG;IACH,QAAQ,EAAE,SAAS;QAAE,QAAQ,CAAC,QAAQ,EAAE,8BAA8B,GAAG,OAAO,CAAA;KAAE,EAAE,CAAA;IACpF,+EAA+E;IAC/E,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,8BAA8B,KAAK,OAAO,CAAA;CACtE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,8BAA8B,EACxC,OAAO,EAAE,oBAAoB,GAC5B,kBAAkB,CAUpB"}

package/dist/session/renderSupport.js

@@ -13,6 +13,22 @@
  * PTY lane is built it replaces this function, and `renderSupportFor`'s tests
  * already prove a `true` answer flows through — so the day it lands, the mode
  * becomes available by construction instead of by someone remembering.
+ *
+ * ⚠️ That claim was NOT true until 2026-08-24, and the way it was false is
+ * worth keeping. Construction reached as far as this file and stopped one
+ * caller short, in two places at once:
+ *
+ *   1. `AgentHostCoordinator` never accepted a `nativeTuiLane`, so no
+ *      composition could reach the seam. Injectable and unreachable.
+ *   2. `openSessionForRun` built the ACP protocol channel UNCONDITIONALLY,
+ *      and `open()` refuses `native-tui` when one is present — so a lane
+ *      returning true would have made every session on that provider fail
+ *      with `protocol_channel_forbidden`.
+ *
+ * Both are fixed and mutation-checked at the caller. The lesson generalises:
+ * a seam proves a value can flow THROUGH the function that declares it, never
+ * that anything calls that function correctly. `renderSupport.test.ts` proved
+ * the first and read as proving the second.
  */
 export function noNativeTuiLane() {
     return false;
@@ -30,12 +46,34 @@ export function noNativeTuiLane() {
  * A provider no adapter supports gets `{ nativeTui: false, acp: false }`, and
  * `selectSessionRenderMode` REFUSES it by name. That is the honest outcome: the
  * alternative is a session that opens, renders nothing, and reports no error.
+ *
+ * 🔴 AND BEING BLOCKED COUNTS AS "cannot run" — measured 2026-08-24.
+ *
+ * `AcpAgentTurnExecutionAdapter.supports()` is `provider.kind === 'acp'`. It
+ * answers "is this the right KIND", not "can this actually run", so a blocked
+ * endpoint reported `acp: true` and, with a TUI present, `switchable: true` —
+ * a toggle that switched into an empty terminal.
+ *
+ * Latent until now, because a blocked provider cannot start a turn and no
+ * session was ever opened for one. It stops being latent the moment a TUI-only
+ * agent is registered — Grok Build, agy and opencode have no ACP adapter in
+ * `xeno-acp`, so they arrive blocked AND with a real interface, which is
+ * exactly the combination that had no honest answer.
+ *
+ * Fixed HERE rather than in `supports()`: that predicate also routes turn
+ * EXECUTION, and narrowing it would change which adapter is found for a run
+ * that is refused for other reasons. This question — "can we render this
+ * agent's structured stream" — is the one that needs the stricter answer.
  */
 export function renderSupportFor(provider, options) {
     const nativeTuiLane = options.nativeTuiLane ?? noNativeTuiLane;
     return {
         nativeTui: nativeTuiLane(provider),
-        acp: options.adapters.some((adapter) => adapter.supports(provider)),
+        // Both halves, and `blocked` fails the second one: a run that cannot
+        // execute emits no runtime events, so there is no structured stream to
+        // render and claiming otherwise offers an empty terminal.
+        acp: provider.availability !== 'blocked'
+            && options.adapters.some((adapter) => adapter.supports(provider)),
     };
 }
 //# sourceMappingURL=renderSupport.js.map

package/dist/session/renderSupport.js.map

@@ -1 +1 @@
-{"version":3,"file":"renderSupport.js","sourceRoot":"","sources":["../../src/session/renderSupport.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,KAAK,CAAA;AACd,CAAC;AAmBD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,gBAAgB,CAC9B,QAAwC,EACxC,OAA6B;IAE7B,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,eAAe,CAAA;IAC9D,OAAO;QACL,SAAS,EAAE,aAAa,CAAC,QAAQ,CAAC;QAClC,GAAG,EAAE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;KACpE,CAAA;AACH,CAAC"}
+{"version":3,"file":"renderSupport.js","sourceRoot":"","sources":["../../src/session/renderSupport.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,KAAK,CAAA;AACd,CAAC;AAmBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,gBAAgB,CAC9B,QAAwC,EACxC,OAA6B;IAE7B,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,eAAe,CAAA;IAC9D,OAAO;QACL,SAAS,EAAE,aAAa,CAAC,QAAQ,CAAC;QAClC,qEAAqE;QACrE,uEAAuE;QACvE,0DAA0D;QAC1D,GAAG,EAAE,QAAQ,CAAC,YAAY,KAAK,SAAS;eACnC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;KACpE,CAAA;AACH,CAAC"}

package/dist/workspace/WorkspaceHostService.d.ts

@@ -1,4 +1,5 @@
 import { type CommandExecutionPort } from '../isolation/CommandExecution.js';
+import type { CommandStreamPort } from '../isolation/CommandStream.js';
 import type { AgentHostEventType, AgentHostClientIdentity, AgentWorkspaceAccessContext, AgentWorkspaceCommandRunRequest, AgentWorkspaceCommandRunResult, AgentWorkspaceDirectoryListRequest, AgentWorkspaceDirectoryListResult, AgentWorkspaceFileReadRequest, AgentWorkspaceFileReadResult, AgentWorkspaceFileWriteRequest, AgentWorkspaceFileWriteResult, AgentWorkspaceGrantRequest, AgentWorkspaceGrantResult, AgentWorkspacePtyInputRequest, AgentWorkspacePtyResizeRequest, AgentWorkspacePtySnapshotRequest, AgentWorkspacePtySnapshotResult, AgentWorkspacePtyStartRequest, AgentWorkspacePtyStartResult, AgentWorkspaceTerminalControlRequest, AgentWorkspaceTerminalControlResult, AgentWorkspaceTerminalStartRequest, AgentWorkspaceTerminalStartResult } from '@xenosystem/agent-interface-contract';
 type WorkspaceEventSink = (type: AgentHostEventType, payload: Record<string, unknown>) => void;
 interface PersistedApplicationGrant {
@@ -33,7 +34,21 @@ export interface WorkspaceHostServiceOptions {
  * which executor serves a conversation.
  */
 export interface RunCommandExecutionEnvironment {
-    executorFor(conversationId: string | undefined): CommandExecutionPort;
+    /**
+     * Executor AND containment for this conversation's current run.
+     *
+     * 🔴 One lookup, not two. argv depends on the destination — a Linux sandbox
+     * cannot run `powershell.exe` — so a caller that asked for the executor and
+     * then guessed the shell would pick the host's argv the moment isolation
+     * turned on. See `commandShellArgv`.
+     */
+    resolutionForConversation(conversationId: string | undefined): {
+        executor: CommandExecutionPort;
+        isolation: {
+            isolation: string;
+        };
+        stream?: CommandStreamPort;
+    };
 }
 export interface WorkspacePathAuthorizationRequest extends AgentWorkspaceAccessContext {
     path: string;
@@ -102,7 +117,7 @@ export declare class WorkspaceHostService {
     readFile(request: AgentWorkspaceFileReadRequest): AgentWorkspaceFileReadResult;
     writeFile(request: AgentWorkspaceFileWriteRequest): AgentWorkspaceFileWriteResult;
     runCommand(request: AgentWorkspaceCommandRunRequest): Promise<AgentWorkspaceCommandRunResult>;
-    startTerminal(request: AgentWorkspaceTerminalStartRequest): AgentWorkspaceTerminalStartResult;
+    startTerminal(request: AgentWorkspaceTerminalStartRequest): Promise<AgentWorkspaceTerminalStartResult>;
     stopTerminal(request: AgentWorkspaceTerminalControlRequest): AgentWorkspaceTerminalControlResult;
     startPty(request: AgentWorkspacePtyStartRequest): Promise<AgentWorkspacePtyStartResult>;
     snapshotPty(request: AgentWorkspacePtySnapshotRequest): AgentWorkspacePtySnapshotResult;
@@ -111,6 +126,16 @@ export declare class WorkspaceHostService {
     clearPty(request: AgentWorkspaceTerminalControlRequest): AgentWorkspaceTerminalControlResult;
     stopPty(request: AgentWorkspaceTerminalControlRequest): AgentWorkspaceTerminalControlResult;
     close(): void;
+    /**
+     * The stream for a confined run — or a refusal.
+     *
+     * 🔴 When the run reports `sandboxed` there is no host fallback. A missing
+     * stream here is a composition bug; spawning `node-pty` as the signed-in
+     * user would be the lie `isolationIsNotObservation` exists to refuse.
+     */
+    private confineStream;
+    private startSandboxedTerminal;
+    private startSandboxedPty;
     private authorizePath;
     private authorizeSession;
     private effectiveAllowedRoots;

package/dist/workspace/WorkspaceHostService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WorkspaceHostService.d.ts","sourceRoot":"","sources":["../../src/workspace/WorkspaceHostService.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"WorkspaceHostService.d.ts","sourceRoot":"","sources":["../../src/workspace/WorkspaceHostService.ts"],"names":[],"mappings":"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"}

package/dist/workspace/WorkspaceHostService.js

@@ -1,21 +1,19 @@
 import { spawn } from 'node:child_process';
 import { commandSucceeded } from '../isolation/CommandExecution.js';
+import { Utf8StreamDecoder } from '../isolation/CommandStream.js';
 import { LocalCommandExecutor } from '../isolation/LocalCommandExecutor.js';
+import { SANDBOX_STREAM_MAX_TIMEOUT_MS } from '../isolation/SandboxCommandStream.js';
+import { commandShellArgv } from '../isolation/shellArgv.js';
 /**
- * ⚠️ This file has THREE process starts. Only ONE is adopted, and naming all
- * three matters — an earlier version of this note said "the PTY is not part of
- * this adoption", which was true and skipped `startTerminal` entirely. Naming
- * one of several paths is the same mistake as naming the wrong one.
+ * ⚠️ This file has THREE process starts. Two of them are adopted when a run is
+ * sandboxed, and naming all three still matters.
  *
  * 1. `runCommand` — ADOPTED. Runs through `CommandExecutionPort`.
- * 2. `startTerminal` — still spawns directly. A fire-and-forget session that
- *    outlives its request and is reaped by its own timer, so it is not the
- *    port's one-call-one-result shape either.
- * 3. `startPty` — a streaming, interactive session: stdin, resize, continuous
- *    output. `xeno-use`'s exec surface has the SAME gap — `Command::output()`
- *    buffers to completion — so streaming exec is recorded there as a new
- *    capability rather than a defect. Forcing either through this port would
- *    mean inventing a shape neither side has.
+ * 2. `startTerminal` — ADOPTED when confined (`CommandStreamPort` / exec-stream).
+ *    Unconfined still spawns on the host.
+ * 3. `startPty` — ADOPTED when confined, through `CommandStreamPort`. The
+ *    session's `tty` is asked from the runtime (`supports_exec_tty`), never
+ *    assumed. Unconfined still uses `node-pty`.
  */
 const commandExecutor = new LocalCommandExecutor();
 import { closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, statSync, writeFileSync, } from 'node:fs';
@@ -300,20 +298,19 @@ export class WorkspaceHostService {
          * shell it runs in does not confine anything; these reduce what gets asked
          * for, and the substrate is what will refuse.
          *
-         * `shellInvocation` already returns `{command, args}`, so this site needed
-         * no argv change at all — it was already spelling a shell AS argv, which is
-         * the pattern the port's rule generalises rather than imposes.
+         * argv comes from `commandShellArgv` so a sandboxed run does not send
+         * `powershell.exe` into a Linux container.
          */
-        const invocation = shellInvocation(command, true);
         // 🔴 Resolved PER CALL, from the conversation this request belongs to.
         // Caching an executor on the service would outlive the run that justified
         // it and keep sending commands to a torn-down container — or, worse, keep
         // reporting containment after it ended. With no environment injected this
         // is the module's local executor, exactly as before.
-        const executor = this.executionEnvironment?.executorFor(request.conversationId)
-            ?? commandExecutor;
+        const resolution = this.executionEnvironment?.resolutionForConversation(request.conversationId);
+        const executor = resolution?.executor ?? commandExecutor;
+        const destination = resolution?.isolation.isolation === 'sandboxed' ? 'sandbox' : 'host';
         const result = await executor.execute({
-            argv: [invocation.command, ...invocation.args],
+            argv: commandShellArgv(command, destination),
             cwd,
             timeoutMs,
             maxOutputBytes: MAX_COMMAND_OUTPUT_BYTES,
@@ -332,7 +329,7 @@ export class WorkspaceHostService {
             truncated: result.truncated,
         };
     }
-    startTerminal(request) {
+    async startTerminal(request) {
         const command = String(request.command || '').trim();
         if (!command)
             return terminalStartFailure('Command is empty.');
@@ -344,8 +341,21 @@ export class WorkspaceHostService {
         const cwd = denied.path;
         const timeoutMs = clampInteger(request.timeoutMs, 300_000, 1_000, 900_000);
         const terminalId = uniqueId('terminal');
-        const invocation = shellInvocation(command, false);
+        const confined = this.confineStream(request.conversationId);
+        if (confined.error)
+            return terminalStartFailure(confined.error);
+        if (confined.stream) {
+            return this.startSandboxedTerminal({
+                request,
+                command,
+                cwd,
+                terminalId,
+                timeoutMs,
+                stream: confined.stream,
+            });
+        }
         try {
+            const invocation = shellInvocation(command, false);
             const child = spawn(invocation.command, invocation.args, {
                 cwd,
                 windowsHide: true,
@@ -357,7 +367,7 @@ export class WorkspaceHostService {
                 ownerInstanceId: request.client.instanceId,
                 command,
                 cwd,
-                process: child,
+                process: { kill: () => { child.kill(); } },
                 timer: null,
                 timedOut: false,
             };
@@ -425,6 +435,19 @@ export class WorkspaceHostService {
         const terminalId = uniqueId('pty');
         const cols = clampInteger(request.cols, 80, 20, 240);
         const rows = clampInteger(request.rows, 24, 6, 120);
+        const confined = this.confineStream(request.conversationId);
+        if (confined.error)
+            return ptyStartFailure(confined.error, cwd);
+        if (confined.stream) {
+            return this.startSandboxedPty({
+                request,
+                cwd,
+                terminalId,
+                cols,
+                rows,
+                stream: confined.stream,
+            });
+        }
         try {
             const nodePty = await this.loadNodePty();
             if (!nodePty) {
@@ -444,7 +467,15 @@ export class WorkspaceHostService {
                 id: terminalId,
                 ownerInstanceId: request.client.instanceId,
                 cwd,
-                process: processHandle,
+                process: {
+                    tty: true,
+                    write: (data) => { processHandle.write(data); },
+                    resize: (nextCols, nextRows) => {
+                        processHandle.resize(nextCols, nextRows);
+                        return { ok: true };
+                    },
+                    kill: () => { processHandle.kill(); },
+                },
                 output: new ScrollbackBuffer(MAX_PTY_SCROLLBACK_BYTES),
             };
             this.ptySessions.set(terminalId, session);
@@ -465,7 +496,7 @@ export class WorkspaceHostService {
                     ownerInstanceId: active?.ownerInstanceId || request.client.instanceId,
                 });
             });
-            return { success: true, terminalId, cwd, error: null };
+            return { success: true, terminalId, cwd, error: null, tty: true };
         }
         catch (error) {
             return { success: false, terminalId: null, cwd, error: safeError(error, 'Failed to start PTY terminal.') };
@@ -493,7 +524,9 @@ export class WorkspaceHostService {
         const denied = this.authorizeSession(request, session);
         if (denied)
             return { success: false, error: denied };
-        session.process.resize(clampInteger(request.cols, 80, 20, 240), clampInteger(request.rows, 24, 6, 120));
+        const resized = session.process.resize(clampInteger(request.cols, 80, 20, 240), clampInteger(request.rows, 24, 6, 120));
+        if (!resized.ok)
+            return { success: false, error: resized.error };
         return { success: true, error: null };
     }
     clearPty(request) {
@@ -531,6 +564,155 @@ export class WorkspaceHostService {
         }
         this.ptySessions.clear();
     }
+    /**
+     * The stream for a confined run — or a refusal.
+     *
+     * 🔴 When the run reports `sandboxed` there is no host fallback. A missing
+     * stream here is a composition bug; spawning `node-pty` as the signed-in
+     * user would be the lie `isolationIsNotObservation` exists to refuse.
+     */
+    confineStream(conversationId) {
+        const resolution = this.executionEnvironment?.resolutionForConversation(conversationId);
+        if (resolution?.isolation.isolation !== 'sandboxed')
+            return {};
+        if (!resolution.stream) {
+            return { error: 'This run is sandboxed but has no command stream, so the terminal was not started.' };
+        }
+        return { stream: resolution.stream };
+    }
+    async startSandboxedTerminal(input) {
+        const decoder = new Utf8StreamDecoder();
+        let live;
+        this.terminalSessions.set(input.terminalId, {
+            id: input.terminalId,
+            ownerInstanceId: input.request.client.instanceId,
+            command: input.command,
+            cwd: input.cwd,
+            process: { kill: () => { void live?.kill(); } },
+            timer: null,
+            timedOut: false,
+        });
+        const started = await input.stream.start({
+            argv: commandShellArgv(input.command, 'sandbox'),
+            cwd: input.cwd,
+            timeoutMs: input.timeoutMs,
+        }, {
+            onChunk: (chunk) => {
+                const text = decoder.push(chunk.bytes);
+                if (!text)
+                    return;
+                this.eventSink('workspace.terminal.data', {
+                    terminalId: input.terminalId,
+                    stream: chunk.stream,
+                    chunk: text,
+                });
+            },
+            onExit: (exit) => {
+                const flushed = decoder.flush();
+                if (flushed) {
+                    this.eventSink('workspace.terminal.data', {
+                        terminalId: input.terminalId,
+                        stream: 'stdout',
+                        chunk: flushed,
+                    });
+                }
+                const active = this.cleanupTerminal(input.terminalId);
+                if (!active)
+                    return;
+                this.eventSink('workspace.terminal.exit', {
+                    terminalId: input.terminalId,
+                    command: input.command,
+                    cwd: input.cwd,
+                    success: !active.timedOut && exit.exitCode === 0,
+                    exitCode: exit.exitCode,
+                    error: active.timedOut || exit.timedOut
+                        ? `Command timed out after ${input.timeoutMs}ms.`
+                        : null,
+                    ownerInstanceId: active.ownerInstanceId,
+                });
+            },
+        });
+        if (started.error || !started.session) {
+            this.terminalSessions.delete(input.terminalId);
+            return terminalStartFailure(started.error || 'Failed to start sandboxed terminal command.');
+        }
+        live = started.session;
+        return { success: true, terminalId: input.terminalId, cwd: input.cwd, error: null };
+    }
+    async startSandboxedPty(input) {
+        const decoder = new Utf8StreamDecoder();
+        const output = new ScrollbackBuffer(MAX_PTY_SCROLLBACK_BYTES);
+        let live;
+        this.ptySessions.set(input.terminalId, {
+            id: input.terminalId,
+            ownerInstanceId: input.request.client.instanceId,
+            cwd: input.cwd,
+            process: sandboxPtyHandle({
+                get tty() { return live?.tty === true; },
+                write: (bytes) => live ? live.write(bytes) : Promise.resolve(),
+                closeStdin: () => live ? live.closeStdin() : Promise.resolve(),
+                resize: (cols, rows) => live
+                    ? live.resize(cols, rows)
+                    : Promise.resolve({ ok: false, error: 'the sandbox PTY has not started' }),
+                kill: () => live ? live.kill() : Promise.resolve(),
+            }),
+            output,
+        });
+        const started = await input.stream.start({
+            argv: ['/bin/sh', '-i'],
+            cwd: input.cwd,
+            timeoutMs: SANDBOX_STREAM_MAX_TIMEOUT_MS,
+            tty: true,
+        }, {
+            onChunk: (chunk) => {
+                const text = decoder.push(chunk.bytes);
+                if (!text)
+                    return;
+                const active = this.ptySessions.get(input.terminalId);
+                if (!active)
+                    return;
+                active.output.append(text);
+                this.eventSink('workspace.pty.data', {
+                    terminalId: input.terminalId,
+                    data: text,
+                    ownerInstanceId: active.ownerInstanceId,
+                });
+            },
+            onExit: (exit) => {
+                const flushed = decoder.flush();
+                const active = this.ptySessions.get(input.terminalId);
+                if (flushed && active)
+                    active.output.append(flushed);
+                this.ptySessions.delete(input.terminalId);
+                this.eventSink('workspace.pty.exit', {
+                    terminalId: input.terminalId,
+                    exitCode: exit.exitCode,
+                    signal: null,
+                    ownerInstanceId: active?.ownerInstanceId || input.request.client.instanceId,
+                });
+            },
+        });
+        if (started.error || !started.session) {
+            this.ptySessions.delete(input.terminalId);
+            return ptyStartFailure(started.error || 'Failed to start sandboxed PTY.', input.cwd);
+        }
+        live = started.session;
+        if (started.session.tty) {
+            const sized = await started.session.resize(input.cols, input.rows);
+            if (!sized.ok) {
+                await started.session.kill();
+                this.ptySessions.delete(input.terminalId);
+                return ptyStartFailure(sized.error, input.cwd);
+            }
+        }
+        return {
+            success: true,
+            terminalId: input.terminalId,
+            cwd: input.cwd,
+            error: null,
+            tty: started.session.tty,
+        };
+    }
     authorizePath(request, rawPath, action, id, allowMissing = false) {
         const path = cleanPath(rawPath);
         if (!path)
@@ -835,6 +1017,20 @@ function terminalStartFailure(error) {
 function ptyStartFailure(error, cwd = null) {
     return { success: false, terminalId: null, cwd, error };
 }
+function sandboxPtyHandle(session) {
+    return {
+        get tty() { return session.tty; },
+        write: (data) => { void session.write(Buffer.from(data, 'utf8')); },
+        resize: (cols, rows) => {
+            if (!session.tty) {
+                return { ok: false, error: 'this runtime has no sandbox TTY (supports_exec_tty is false)' };
+            }
+            void session.resize(cols, rows);
+            return { ok: true };
+        },
+        kill: () => { void session.kill(); },
+    };
+}
 function safeError(error, fallback) {
     return error instanceof Error && error.message.trim() ? error.message.slice(0, 1_000) : fallback;
 }