@aiworker/web 1.22.2 → 1.23.0

package/server/lib/relay/tunnel-codec.js

@@ -34,6 +34,7 @@ export const TunnelFrameType = {
   WsClose: 10,
   Ping: 11,
   Pong: 12,
+  DeliveryAck: 13,
 };
 
 const TUNNEL_FRAME_TYPE_VALUES = new Set(Object.values(TunnelFrameType));
@@ -43,6 +44,14 @@ export const isTunnelFrameType = (value) => TUNNEL_FRAME_TYPE_VALUES.has(value);
 
 const MAX_STREAM_ID = 0xffffffff;
 
+/** Decode the client's cumulative raw tunnel-frame byte count. */
+export const decodeDeliveryAck = (payload) => {
+  if (payload.length !== 8) throw new Error('invalid delivery acknowledgement');
+  const bytes = Number(new DataView(payload.buffer, payload.byteOffset, payload.byteLength).getBigUint64(0));
+  if (!Number.isSafeInteger(bytes)) throw new Error('invalid delivery acknowledgement');
+  return bytes;
+};
+
 export class TunnelCodecError extends Error {
   constructor(message) {
     super(message);

package/server/lib/relay/tunnel-host.js

@@ -15,7 +15,6 @@ import {
   createFragmentAssembler,
   decodeJsonPayload,
   decodeTunnelFrame,
-  encodeFragmentedMessage,
   encodeJsonPayload,
   encodeTunnelFrame,
 } from './tunnel-codec.js';
@@ -74,6 +73,11 @@ const BODY_BUFFER_MAX_BYTES = 512 * 1024;
 // completes, so a stalled tunnel converts into an ambiguous transport failure
 // (which the client already retries) instead of a hung loopback request.
 const BODY_DELIVERY_TIMEOUT_MS = 15_000;
+const MAX_PENDING_WS_BYTES = 16 * 1024 * 1024;
+const MAX_PENDING_WS_MESSAGES = 1024;
+// Node ws supports read backpressure. Bun's ws shim does not implement pause;
+// there the bounded queue fails the affected substream explicitly on overflow.
+const CAN_PAUSE_WS_READS = !process.versions.bun;
 
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
@@ -99,13 +103,17 @@ const isWsClosePayload = (parsed) => Boolean(parsed && typeof parsed === 'object
  *   sendFrame: (plaintextFrame: Uint8Array) => void | Promise<void>,
  *   getBufferedAmount: () => number,
  *   bodyDeliveryTimeoutMs?: number,
+ *   responseChunkBytes?: number,
+ *   cancelPendingFrames?: (streamId: number) => void,
  * }} deps
  */
-export const createTunnelHost = ({ connectionId, getLocalPort, sendFrame, getBufferedAmount, bodyDeliveryTimeoutMs = BODY_DELIVERY_TIMEOUT_MS }) => {
+export const createTunnelHost = ({ connectionId, getLocalPort, sendFrame, getBufferedAmount, bodyDeliveryTimeoutMs = BODY_DELIVERY_TIMEOUT_MS, responseChunkBytes = MAX_TUNNEL_PAYLOAD_BYTES, cancelPendingFrames = () => {} }) => {
   /** @type {Map<number, { kind: 'http', abort: AbortController, body: { enqueue(payload: Uint8Array): void, close(): void, error(error: Error): void } | null, noBody: boolean } | { kind: 'ws', socket: WebSocket, opened: boolean }>} */
   const streams = new Map();
   const assembler = createFragmentAssembler();
   let closed = false;
+  let pendingWsBytes = 0;
+  let pendingWsMessages = 0;
 
   const send = async (frame) => {
     if (closed) return;
@@ -128,6 +136,7 @@ export const createTunnelHost = ({ connectionId, getLocalPort, sendFrame, getBuf
     const stream = streams.get(streamId);
     if (!stream) return;
     dropStream(streamId);
+    cancelPendingFrames(streamId);
     if (stream.kind === 'http') {
       try {
         stream.body?.error(new Error(String(reason ?? 'aborted')));
@@ -205,17 +214,27 @@ export const createTunnelHost = ({ connectionId, getLocalPort, sendFrame, getBuf
       if (STRIPPED_RESPONSE_HEADERS.has(name)) continue;
       responseHeaders[name] = value;
     }
-    await sendJson(TunnelFrameType.HttpResponse, streamId, { status: response.status, headers: responseHeaders });
+    if (closed || stream.abort.signal.aborted) {
+      await response.body?.cancel();
+      return;
+    }
 
     try {
+      await sendJson(TunnelFrameType.HttpResponse, streamId, { status: response.status, headers: responseHeaders });
       if (response.body) {
         for await (const chunk of response.body) {
           if (closed || stream.abort.signal.aborted) return;
           const bytes = chunk instanceof Uint8Array ? chunk : new Uint8Array(chunk);
-          for (const piece of chunkPayload(bytes, MAX_TUNNEL_PAYLOAD_BYTES)) {
+          const pieces = chunkPayload(bytes, responseChunkBytes);
+          // Offer at most one plaintext-frame budget at a time. The scheduler
+          // can batch small slices and interleave streams without buffering the
+          // entire source or encrypting hundreds of tiny messages separately.
+          const groupSize = Math.max(1, Math.floor(MAX_TUNNEL_PAYLOAD_BYTES / responseChunkBytes));
+          for (let offset = 0; offset < pieces.length; offset += groupSize) {
             await waitForBackpressure(stream.abort.signal);
             if (closed || stream.abort.signal.aborted) return;
-            await send(encodeTunnelFrame(TunnelFrameType.HttpBody, streamId, piece));
+            await Promise.all(pieces.slice(offset, offset + groupSize).map(piece =>
+              send(encodeTunnelFrame(TunnelFrameType.HttpBody, streamId, piece))));
           }
         }
       }
@@ -448,6 +467,7 @@ export const createTunnelHost = ({ connectionId, getLocalPort, sendFrame, getBuf
     try {
       socket = new WebSocket(url, open.protocols, {
         headers: dialHeaders,
+        maxPayload: MAX_PENDING_WS_BYTES,
       });
     } catch (error) {
       void sendAbort(streamId, error?.message ?? 'ws dial failed');
@@ -455,6 +475,8 @@ export const createTunnelHost = ({ connectionId, getLocalPort, sendFrame, getBuf
     }
     const stream = { kind: 'ws', socket, opened: false };
     streams.set(streamId, stream);
+    let outputChain = Promise.resolve();
+    let socketPendingMessages = 0;
 
     socket.on('open', () => {
       if (streams.get(streamId) !== stream) return;
@@ -465,23 +487,47 @@ export const createTunnelHost = ({ connectionId, getLocalPort, sendFrame, getBuf
       if (streams.get(streamId) !== stream || closed) return;
       const bytes = Buffer.isBuffer(data) ? new Uint8Array(data) : new Uint8Array(Buffer.concat(data));
       const frameType = isBinary ? TunnelFrameType.WsBinary : TunnelFrameType.WsText;
-      void (async () => {
-        for (const frame of encodeFragmentedMessage(frameType, streamId, bytes)) {
+      if (pendingWsBytes + bytes.length > MAX_PENDING_WS_BYTES || pendingWsMessages >= MAX_PENDING_WS_MESSAGES) {
+        abortLocalStream(streamId, 'upstream WebSocket exceeded downstream queue limit');
+        void sendAbort(streamId, 'upstream WebSocket exceeded downstream queue limit');
+        return;
+      }
+      pendingWsBytes += bytes.length;
+      pendingWsMessages += 1;
+      socketPendingMessages += 1;
+      if (CAN_PAUSE_WS_READS) socket.pause();
+      outputChain = outputChain.then(async () => {
+        // Serialize entire messages, including their fragments. A later close
+        // must also wait here or it can overtake the final output.
+        const chunks = chunkPayload(bytes, responseChunkBytes);
+        const groupSize = Math.max(1, Math.floor(MAX_TUNNEL_PAYLOAD_BYTES / responseChunkBytes));
+        for (let offset = 0; offset < chunks.length; offset += groupSize) {
           await waitForBackpressure(null);
           if (streams.get(streamId) !== stream || closed) return;
-          await send(frame);
+          await Promise.all(chunks.slice(offset, offset + groupSize).map((chunk, index) =>
+            send(encodeTunnelFrame(frameType, streamId, chunk, offset + index < chunks.length - 1))));
         }
-      })();
+      }).catch(() => {
+        abortLocalStream(streamId, 'upstream WebSocket forwarding failed');
+        void sendAbort(streamId, 'upstream WebSocket forwarding failed');
+      }).finally(() => {
+        pendingWsBytes -= bytes.length;
+        pendingWsMessages -= 1;
+        socketPendingMessages -= 1;
+        if (CAN_PAUSE_WS_READS && socketPendingMessages === 0 && streams.get(streamId) === stream && socket.readyState === WebSocket.OPEN) socket.resume();
+      });
     });
     socket.on('close', (code, reasonBuffer) => {
-      if (streams.get(streamId) !== stream) return;
-      dropStream(streamId);
-      const reason = reasonBuffer ? reasonBuffer.toString('utf8') : '';
-      if (stream.opened) {
-        void sendJson(TunnelFrameType.WsClose, streamId, { code: code || 1000, reason });
-      } else {
-        void sendAbort(streamId, reason || `upstream ws closed (${code || 'no code'})`);
-      }
+      void outputChain.then(async () => {
+        if (streams.get(streamId) !== stream) return;
+        dropStream(streamId);
+        const reason = reasonBuffer ? reasonBuffer.toString('utf8') : '';
+        if (stream.opened) {
+          await sendJson(TunnelFrameType.WsClose, streamId, { code: code || 1000, reason });
+        } else {
+          await sendAbort(streamId, reason || `upstream ws closed (${code || 'no code'})`);
+        }
+      });
     });
     socket.on('error', (error) => {
       if (streams.get(streamId) !== stream) return;
@@ -512,6 +558,7 @@ export const createTunnelHost = ({ connectionId, getLocalPort, sendFrame, getBuf
     const stream = streams.get(streamId);
     if (!stream || stream.kind !== 'ws') return;
     dropStream(streamId);
+    cancelPendingFrames(streamId);
     let close = { code: 1000, reason: '' };
     try {
       close = decodeJsonPayload(payload, isWsClosePayload);
@@ -520,6 +567,8 @@ export const createTunnelHost = ({ connectionId, getLocalPort, sendFrame, getBuf
     }
     const code = Number.isInteger(close.code) && close.code >= 1000 && close.code <= 4999 ? close.code : 1000;
     try {
+      // A paused receiver still needs to read the peer's close handshake.
+      if (CAN_PAUSE_WS_READS) stream.socket.resume();
       stream.socket.close(code, typeof close.reason === 'string' ? close.reason : '');
     } catch {
       stream.socket.terminate();

package/server/lib/session-assist/runtime.js

@@ -11,6 +11,7 @@
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
+import { readMergedSettingsSync } from '../opencode/settings-files.js';
 
 const AIWORKER_SETTINGS_FILE = path.join(
   process.env.AIWORKER_DATA_DIR
@@ -23,16 +24,11 @@ const AIWORKER_SETTINGS_FILE = path.join(
 // off, no small-model calls and no metadata writes happen at all. Existing
 // payloads stay untouched — clients keep showing them and dismissal still works.
 const getSessionAssistTargets = () => {
-  try {
-    const raw = fs.readFileSync(AIWORKER_SETTINGS_FILE, 'utf8');
-    const settings = JSON.parse(raw);
-    return {
-      recap: settings?.sessionRecapEnabled !== false,
-      suggestion: settings?.sessionSuggestionEnabled !== false,
-    };
-  } catch {
-    return { recap: true, suggestion: true };
-  }
+  const settings = readMergedSettingsSync({ fs, path, settingsFilePath: AIWORKER_SETTINGS_FILE });
+  return {
+    recap: settings.sessionRecapEnabled !== false,
+    suggestion: settings.sessionSuggestionEnabled !== false,
+  };
 };
 
 const IDLE_QUIET_MS = 60_000;

package/server/lib/session-goal/runtime.js

@@ -19,6 +19,7 @@ import os from 'os';
 import path from 'path';
 
 import { GOAL_OBJECTIVE_CHAR_LIMIT, readObjective } from './objectives.js';
+import { readMergedSettingsSync } from '../opencode/settings-files.js';
 
 const AIWORKER_SETTINGS_FILE = path.join(
   process.env.AIWORKER_DATA_DIR
@@ -27,15 +28,9 @@ const AIWORKER_SETTINGS_FILE = path.join(
   'settings.json',
 );
 
-const isSessionGoalEnabled = () => {
-  try {
-    const raw = fs.readFileSync(AIWORKER_SETTINGS_FILE, 'utf8');
-    const settings = JSON.parse(raw);
-    return settings?.sessionGoalEnabled !== false;
-  } catch {
-    return true;
-  }
-};
+const isSessionGoalEnabled = () => (
+  readMergedSettingsSync({ fs, path, settingsFilePath: AIWORKER_SETTINGS_FILE }).sessionGoalEnabled !== false
+);
 
 const IDLE_QUIET_MS = 15_000;
 // A goal set while the session is already idle should kick off promptly.

package/server/lib/small-model/DOCUMENTATION.md

@@ -117,8 +117,9 @@ other runtime API.
   - Everything else: OpenAI-compatible `/chat/completions` against the
     provider's base URL, resolved from (1) `provider.<id>.options.baseURL`
     in the OpenCode config, (2) the hardcoded `https://api.openai.com/v1`
-     endpoint, (3) the endpoint OpenCode resolved at runtime, or (4) the
-    provider's `api` field from the models.dev catalog. The credential follows
+     endpoint, (3) the selected model's endpoint OpenCode resolved at runtime,
+     (4) the provider-level runtime endpoint, or (5) the provider's `api` field
+     from the models.dev catalog. The credential follows
     the same shape: config `options.apiKey`, then the runtime credential, then
     the auth.json entry. `provider.<id>.options.headers` is sent with the
     request and overrides the bearer default, so gateways that authenticate on

package/server/lib/small-model/call.js

@@ -606,6 +606,8 @@ const readProviderConfig = (workingDirectory, providerID) => {
   }
 }
 
+const getRuntimeModel = (runtimeProvider, modelID) => runtimeProvider?.models?.get(modelID) ?? null;
+
 // ---------------------------------------------------------------------------
 // Dispatch
 // ---------------------------------------------------------------------------
@@ -650,6 +652,7 @@ export async function callSmallModel({ auth, catalog, workingDirectory, sessionI
   const tokens = Number(maxOutputTokens) > 0 ? Number(maxOutputTokens) : DEFAULT_MAX_OUTPUT_TOKENS;
   const providerConfig = readProviderConfig(workingDirectory, providerID);
   const runtimeProvider = await getRuntimeProvider(providerID);
+  const runtimeModel = getRuntimeModel(runtimeProvider, modelID);
   // Match OpenCode's resolveSDK precedence: config `provider.<id>.options`
   // wins, then what OpenCode itself resolved at runtime (the only place a
   // plugin's credential exists), and the auth.json entry last.
@@ -759,9 +762,10 @@ export async function callSmallModel({ auth, catalog, workingDirectory, sessionI
   // base URL for that provider (openai itself included). When a custom provider
   // is not in the catalog (e.g. a user-configured OpenAI-compatible proxy),
   // fall back to its baseURL from the OpenCode provider config, then to the
-  // endpoint OpenCode resolved at runtime — which for a plugin provider is the
-  // only place it exists, and for several of them is a local proxy the plugin
-  // itself runs. The openai provider also respects
+  // selected model's endpoint OpenCode resolved at runtime, then to the
+  // provider-level runtime endpoint. For a plugin provider, the runtime listing
+  // is the only place those endpoints exist, and several are local proxies the
+  // plugin itself runs. The openai provider also respects
   // provider.openai.options.baseURL — OpenCode itself uses the same config for
   // all providers including openai.
   const provider = getCatalogProvider(catalog, providerID);
@@ -771,7 +775,8 @@ export async function callSmallModel({ auth, catalog, workingDirectory, sessionI
     ? providerConfigUrl
     : providerID === 'openai'
       ? defaultOpenaiUrl
-      : runtimeProvider?.baseURL
+      : runtimeModel?.api?.url
+        ?? runtimeProvider?.baseURL
         ?? (typeof provider?.api === 'string' && provider.api
           ? provider.api
           : null);

package/server/lib/small-model/call.test.js

@@ -565,6 +565,35 @@ describe('callSmallModel — custom provider config', () => {
       expect(init.headers.Authorization).toBe('Bearer plugin-key');
     });
 
+    it('uses the selected runtime model endpoint', async () => {
+      readConfig.mockReturnValue({});
+      getRuntimeProvider.mockResolvedValue({
+        id: 'runtime-provider',
+        apiKey: 'plugin-key',
+        baseURL: 'https://runtime-provider/v1beta',
+        models: new Map([
+          ['first-model', { api: { url: 'https://runtime-provider/v1beta', npm: '@ai-sdk/google' } }],
+          ['selected-model', { api: { url: 'https://runtime-provider/v1', npm: '@ai-sdk/openai' } }],
+        ]),
+        anonymousZen: false,
+      });
+      fetchMock.mockResolvedValue(ok('done'));
+
+      await callSmallModel({
+        auth: {},
+        catalog: {},
+        workingDirectory: '/proj',
+        providerID: 'runtime-provider',
+        modelID: 'selected-model',
+        prompt: 'hi',
+      });
+
+      const { url, init } = lastCall(fetchMock);
+      expect(url).toBe('https://runtime-provider/v1/chat/completions');
+      expect(url).not.toContain('/v1beta');
+      expect(JSON.parse(init.body).model).toBe('selected-model');
+    });
+
     it('keeps the ChatGPT-plan login on its own transport instead of the runtime key', async () => {
       readConfig.mockReturnValue({});
       // OpenCode reports an OAuth access token as `options.apiKey` for openai;

package/server/lib/small-model/index.js

@@ -6,6 +6,7 @@ import { readConfigLayers } from '../opencode/shared.js';
 import { getModelCatalog } from './catalog.js';
 import { resolveSmallModel, parseModelRef, isUsableAuthEntry, getAuthEntryForProvider } from './resolve.js';
 import { DEDICATED_WIRE_FORMAT_PROVIDERS, callSmallModel, resolveProviderLogin } from './call.js';
+import { readMergedSettingsSync } from '../opencode/settings-files.js';
 import { getRuntimeProviderSnapshot } from './runtime-providers.js';
 
 // Never a small model, whatever the transport looks like. A plugin can publish
@@ -26,16 +27,10 @@ const AIWORKER_SETTINGS_FILE = path.join(
 // AiWorker's own settings: when the user unchecks "use default small model"
 // their explicit override outranks every other resolution step.
 const readSmallModelSettingsOverride = () => {
-  try {
-    const raw = fs.readFileSync(AIWORKER_SETTINGS_FILE, 'utf8');
-    const settings = JSON.parse(raw);
-    if (!settings || typeof settings !== 'object') return null;
-    if (settings.smallModelUseDefault !== false) return null;
-    const override = typeof settings.smallModelOverride === 'string' ? settings.smallModelOverride.trim() : '';
-    return override || null;
-  } catch {
-    return null;
-  }
+  const settings = readMergedSettingsSync({ fs, path, settingsFilePath: AIWORKER_SETTINGS_FILE });
+  if (settings.smallModelUseDefault !== false) return null;
+  const override = typeof settings.smallModelOverride === 'string' ? settings.smallModelOverride.trim() : '';
+  return override || null;
 };
 
 // Rough safety clamp so a huge input never blows the model's context window.

package/server/lib/small-model/runtime-providers.js

@@ -8,7 +8,8 @@
 //
 // `GET /provider` is where that state becomes visible. It reports, per
 // provider, the resolved `options.baseURL` and `options.apiKey`, and per model
-// the wire adapter (`api.npm`) and endpoint (`api.url`).
+// the wire adapter (`api.npm`) and endpoint (`api.url`). The provider-level
+// endpoint remains only as a fallback when the selected model has no endpoint.
 //
 // What it does NOT report is `options.fetch`. OpenCode strips functions from
 // the response, and a plugin is free to put its whole protocol in there:
@@ -61,8 +62,8 @@ export function resetOpenCodeRuntimeProviders() {
 /**
  * The boundary. Everything the `/provider` payload claims is checked here, so
  * the rest of this module and its callers work with settled values:
- * a credential we may use, an endpoint, and whether the provider is the
- * anonymous zen case.
+ * a credential we may use, provider and model endpoints, and whether the
+ * provider is the anonymous zen case.
  *
  * The credential deliberately prefers `options.apiKey` over the `key` field:
  * for a plugin provider the former is what its auth loader produced and what
@@ -82,13 +83,22 @@ function parseProviderListing(payload) {
     const id = text(record(raw).id);
     if (!id) continue;
     const options = record(record(raw).options);
-    const firstModel = record(Object.values(record(record(raw).models))[0]);
+    const models = new Map();
+    for (const [modelID, rawModel] of Object.entries(record(record(raw).models))) {
+      const model = record(rawModel);
+      const api = record(model.api);
+      const modelURL = endpoint(api.url);
+      const modelNpm = text(api.npm);
+      models.set(modelID, { api: { url: modelURL, npm: modelNpm } });
+    }
+    const firstModel = models.values().next().value;
     const declaredKey = text(options.apiKey);
     providers.set(id, {
       id,
       source: text(record(raw).source),
       apiKey: declaredKey === ZEN_ANONYMOUS_API_KEY ? null : (declaredKey ?? text(record(raw).key)),
-      baseURL: endpoint(options.baseURL) ?? endpoint(record(firstModel.api).url),
+      baseURL: endpoint(options.baseURL) ?? firstModel?.api?.url ?? null,
+      models,
       // True only for the zen-without-login case: a provider that is present
       // and usable through OpenCode, but that we must not call ourselves.
       anonymousZen: declaredKey === ZEN_ANONYMOUS_API_KEY,
@@ -152,5 +162,3 @@ export async function getRuntimeProvider(providerID) {
   const current = await getRuntimeProviderSnapshot();
   return current?.providers.get(providerID) ?? null;
 }
-
-

package/server/lib/small-model/runtime-providers.test.js

@@ -14,7 +14,10 @@ const providerPayload = (overrides = {}) => ({
       id: 'llmapi',
       source: 'config',
       options: { apiKey: 'plugin-key', baseURL: 'https://api.llmapi.ai/v1/' },
-      models: { 'claude-opus-4-8': { api: { id: 'claude-opus-4-8', url: '', npm: '@ai-sdk/anthropic' } } },
+      models: {
+        'claude-opus-4-8': { api: { id: 'claude-opus-4-8', url: '', npm: '@ai-sdk/anthropic' } },
+        'gpt-5.6-luna': { api: { id: 'gpt-5.6-luna', url: 'https://api.llmapi.ai/v1', npm: '@ai-sdk/openai' } },
+      },
     },
     {
       id: 'opencode',
@@ -59,6 +62,9 @@ describe('OpenCode runtime provider snapshot', () => {
     const provider = await getRuntimeProvider('llmapi');
 
     expect(provider).toMatchObject({ apiKey: 'plugin-key', baseURL: 'https://api.llmapi.ai/v1' });
+    expect(provider.models.get('gpt-5.6-luna')).toEqual({
+      api: { url: 'https://api.llmapi.ai/v1', npm: '@ai-sdk/openai' },
+    });
     expect(fetchMock.mock.calls[0][0]).toBe('http://127.0.0.1:4096/provider');
     expect(fetchMock.mock.calls[0][1].headers).toMatchObject({ Authorization: 'Basic test' });
   });

package/server/lib/terminal/DOCUMENTATION.md

@@ -9,7 +9,7 @@
 `/api/terminal/ws` is the only terminal data transport. It uses v3 binary JSON control frames and is opened through `openRuntimeWebSocket`, preserving direct, Electron proxy, URL-token authentication, and private-relay routing.
 
 - `attach` registers a connection for one terminal. One socket may attach to many terminals.
-- Every attach and reconnect begins with an authoritative `snapshot` containing bounded history and the current sequence.
+- Every attach and reconnect begins with an authoritative `snapshot` containing bounded history, the current sequence, and the PTY `cols`/`rows` the history was drawn for. The client replays the history at that size before fitting its viewport; replaying shell output at another width leaves stray fragments that the shell's own SIGWINCH redraw never clears.
 - A current socket that closes or errors before its initial `open` invalidates its URL-scoped auth token before retrying, so retries mint a fresh token instead of backing off against a rejected upgrade. Hidden or offline clients wait 60 seconds and wake promptly on visibility/online recovery.
 - `output`, `exit`, and `restarted` carry monotonically increasing per-terminal sequences. Output carries raw live bytes plus replay-safe bytes with terminal query exchanges removed.
 - Attach registers before capturing the snapshot, buffers concurrent events, drops events represented by the snapshot sequence, then enters live delivery.
@@ -28,14 +28,14 @@ HTTP remains the authenticated command plane for create, resize, appearance upda
 - Concurrent creates for one ID are single-flight only when working directory, shell preference, login mode, launch mode, and session purpose match. Command-mode creates must also match the command text, unless the purpose is a project action that is already running for the same resolved `(cwd, actionId)` pair. In that case the runtime returns the existing session and its existing execution identity, even when another client requested a different session ID. Existing IDs cannot be reused for another working directory or another purpose.
 - Dimensions are bounded to 1-1000 columns and 1-500 rows; input is capped at 64 KiB.
 - A client may create before its renderer has mounted. It derives an initial size from the container and font metrics (falling back to 80x24 when unavailable), then sends a resize once Ghostty reports its final dimensions. This allows shell startup and renderer initialization to overlap.
-- PTY children explicitly clear `NODE_CHANNEL_FD`; daemon IPC descriptors are host-private and invalid after PTY descriptor cleanup.
-- PTY children also strip AppImage `ARGV0` (and other host-private shell vars such as `ELECTRON_RUN_AS_NODE`, `BASH_ENV`, `ENV`, `BASH_XTRACEFD`). An exported `ARGV0` makes zsh rewrite argv[0] for every external command, which breaks Python venv detection and other argv[0]/$0 consumers while leaving `/proc/self/exe` correct. On Linux, PTY spawn is wrapped with `env -u ARGV0` because `bun-pty` merges the native OS environ and would otherwise reintroduce `ARGV0` after a JS-only delete.
+- PTY children never inherit `NODE_CHANNEL_FD`; daemon IPC descriptors are host-private and invalid after PTY descriptor cleanup, and an inherited value (even empty) makes Node CLIs such as opencode print `Failed to parse IPC channel number` on exit.
+- PTY children also strip AppImage `ARGV0` (and other host-private shell vars such as `ELECTRON_RUN_AS_NODE`, `BASH_ENV`, `ENV`, `BASH_XTRACEFD`). An exported `ARGV0` makes zsh rewrite argv[0] for every external command, which breaks Python venv detection and other argv[0]/$0 consumers while leaving `/proc/self/exe` correct. On POSIX, PTY spawn is wrapped with `env -u ARGV0 -u NODE_CHANNEL_FD` (`resolvePosixPtyLaunch`) because `bun-pty` merges the native OS environ and would otherwise reintroduce both after a JS-only delete.
 - `GET /api/terminal/shells` reports shell IDs available on the active server using the same augmented PATH provided to spawned PTYs, plus whether each executable has a supported login-mode argument. `auto` preserves environment/platform fallback order; an explicit unavailable shell fails creation instead of silently running a different shell. Login mode is opt-in and uses only built-in arguments for known shells. Interactive shells still launch as before. Command-mode launches reuse the same environment and login support, but switch argv by shell family: POSIX and Fish use interactive `-c`, Nushell uses `-c`, PowerShell uses `-Command`, and cmd uses `/d /s /c`. Preference changes affect new sessions and explicit restarts, not running PTYs.
 - PTY data and exit callbacks enter one FIFO queue. The runtime wires those listeners in the same synchronous turn that receives the PTY object. `node-pty` and `bun-pty` both expose the PTY before dispatching registered callbacks. If a backend emitted exit before listener registration, this layer could not recover it, so the wiring stays adjacent to PTY creation.
 - Scrollback is retained on the server and capped at 512 KiB with UTF-8-safe trimming. Device-status, device-attribute, cursor-position reply, and color-query exchanges are removed from replay history with incomplete control sequences carried across PTY chunks; live output remains byte-for-byte unchanged.
 - Exited sessions remain attachable until explicit close, idle cleanup, or a successful replacement of the same project action. Creating a replacement retires only exited records for the same resolved directory and action, after the new PTY starts. Failed creation preserves the old record and output. These replaced records do not exhaust the terminal capacity limit.
 - Deduplicated create responses may describe another client's execution. Cancellation cleanup closes only the terminal ID allocated for the cancelled request; it never closes an adopted peer execution.
-- Create and restart validate the working directory with a real `stat` and answer HTTP 400 `Invalid working directory` when it is not a directory. When the path does not exist at all (`ENOENT`/`ENOTDIR`, a worktree deleted outside AiWorker) the body also carries `code: "TERMINAL_CWD_MISSING"`. That is the one rejection the client can recover from: the session, not the terminal, is stranded, and the shared UI moves it to its project directory and starts a terminal there. Every other rejection stays generic; the runtime never substitutes a parent directory on its own.
+- Create and restart validate the working directory with a real `stat` and answer HTTP 400 `Invalid working directory` when it is not a directory. When the path does not exist at all (`ENOENT`/`ENOTDIR`, a worktree deleted outside AiWorker) the body also carries `code: "TERMINAL_CWD_MISSING"`. The client shows the failure without moving the session. The runtime never substitutes a parent directory on its own.
 - Restarts are serialized per terminal. Each restart spawns and wires the replacement before terminating the old process, retaining the terminal ID. Command-mode sessions reject restart with HTTP 400 instead of silently turning into interactive shells with stale action metadata.
 - A delete that arrives while create is still pending leaves a cancellation tombstone. When the PTY arrives, the runtime terminates it immediately, never inserts the session into the live map, and returns a create error while the delete still succeeds.
 - Close uses SIGTERM with bounded SIGKILL escalation. Force-kill, idle cleanup, and runtime shutdown terminate process groups immediately where supported. Removal explicitly sends a fatal scoped closure and evicts client projections even when a PTY backend fails to emit `onExit`; attached terminals are not considered idle.

package/server/lib/terminal/runtime.js

@@ -10,7 +10,7 @@ import {
 import { sanitizeTerminalHistoryChunk } from './history.js';
 import { consumeTerminalThemeQueries, terminalThemeModeReport } from './theme-response.js';
 import { buildTerminalShellLaunch, createTerminalShellResolver, normalizeTerminalShell } from './shells.js';
-import { stripAppImageArgv0Leak, resolveLinuxPtyLaunch } from '../inherited-env.js';
+import { stripAppImageArgv0Leak, resolvePosixPtyLaunch } from '../inherited-env.js';
 
 const MAX_SESSIONS = 20;
 const MAX_HISTORY_BYTES = 512 * 1024;
@@ -123,15 +123,16 @@ export function createTerminalRuntime({
     for (const executable of resolvedShell.executables) {
       try {
         const env = { ...process.env, PATH: buildAugmentedPath(), TERM: 'xterm-256color', COLORTERM: 'truecolor', COLORFGBG: themeMode === 'light' ? '0;15' : '15;0' };
-        // The daemon's IPC fd is closed inside the PTY. An explicit override is
-        // required because bun-pty also inherits Bun's native process environment.
-        env.NODE_CHANNEL_FD = '';
+        // The daemon's IPC fd is closed inside the PTY; an inherited NODE_CHANNEL_FD
+        // (even an empty one) makes Node CLIs warn about an unparsable IPC channel.
+        delete env.NODE_CHANNEL_FD;
         delete env.BASH_XTRACEFD; delete env.BASH_ENV; delete env.ENV; delete env.ELECTRON_RUN_AS_NODE;
         // AppImage exports ARGV0; zsh would otherwise rewrite argv[0] for every command (#2588).
-        // bun-pty also merges the native OS environ, so wrap with `env -u ARGV0` on Linux.
         stripAppImageArgv0Leak(env);
         const shellLaunch = buildTerminalShellLaunch(executable, { mode, command, loginShell });
-        const launch = resolveLinuxPtyLaunch(shellLaunch.executable, shellLaunch.args);
+        // bun-pty merges the native OS environ back in, so the POSIX launch is
+        // wrapped with `env -u` for the variables deleted above.
+        const launch = resolvePosixPtyLaunch(shellLaunch.executable, shellLaunch.args);
         const options = { name: 'xterm-256color', cwd, cols, rows, env };
         if (process.platform === 'win32') options.useConpty = true;
         return { process: await provider.spawn(launch.executable, launch.args, options), backend: provider.backend, shell: resolvedShell.id, loginShell };
@@ -184,6 +185,10 @@ export function createTerminalRuntime({
 
   const snapshot = (session) => ({
     t: 'snapshot', v: 3, s: session.id, q: session.sequence, history: session.history,
+    // The PTY size the history was drawn for: a client replays history at this
+    // size before fitting its own viewport, so shell output wrapped for one
+    // width never gets re-laid-out at another.
+    cols: session.cols, rows: session.rows,
     status: session.status, exitCode: session.exitCode, signal: session.signal,
     mode: session.mode ?? INTERACTIVE_TERMINAL_MODE, purpose: getSessionPurpose(session),
     runtime, ptyBackend: session.backend,

package/server/lib/terminal/runtime.test.js

@@ -319,12 +319,12 @@ describe('terminal runtime', () => {
       expect(response.body).toEqual({ sessionId: 'term-1', cols: 120, rows: 40, status: 'running', mode: 'interactive', purpose: { type: 'terminal' } });
       expect(harness.processes[0].options.cwd).toBe('/repo');
       expect(harness.processes[0].options.env.COLORFGBG).toBe('0;15');
-      expect(harness.processes[0].options.env.NODE_CHANNEL_FD).toBe('');
+      expect(harness.processes[0].options.env).not.toHaveProperty('NODE_CHANNEL_FD');
       expect(harness.processes[0].options.env).not.toHaveProperty('ARGV0');
       expect(harness.processes[0].options.env).not.toHaveProperty('ELECTRON_RUN_AS_NODE');
-      if (process.platform === 'linux') {
+      if (process.platform !== 'win32') {
         expect(harness.processes[0].shell).toMatch(/\/env$/);
-        expect(harness.processes[0].args.slice(0, 3)).toEqual(['-u', 'ARGV0', expect.any(String)]);
+        expect(harness.processes[0].args.slice(0, 5)).toEqual(['-u', 'ARGV0', '-u', 'NODE_CHANNEL_FD', expect.any(String)]);
       }
       harness.processes[0].emitData('\u001b[?2031h\u001b]10;?\u0007\u001b]11;?\u0007\u001b[0c');
       expect(harness.processes[0].writes).toEqual(['\u001b]10;rgb:1b1b/1b1b/1b1b\u001b\\', '\u001b]11;rgb:fafa/f8f8/f0f0\u001b\\', '\u001b[?1;2c']);
@@ -380,7 +380,7 @@ describe('terminal runtime', () => {
       await harness.routes.post.get('/api/terminal/create')({ body: { sessionId: 'term-argv0', cwd: '/repo', cols: 80, rows: 24 } }, response);
       expect(response.statusCode).toBe(200);
       expect(harness.processes[0].options.env).not.toHaveProperty('ARGV0');
-      if (process.platform === 'linux') {
+      if (process.platform !== 'win32') {
         expect(harness.processes[0].shell).toMatch(/\/env$/);
         expect(harness.processes[0].args[0]).toBe('-u');
         expect(harness.processes[0].args[1]).toBe('ARGV0');
@@ -417,9 +417,9 @@ describe('terminal runtime', () => {
       const created = createResponse();
       await harness.routes.post.get('/api/terminal/create')({ body: { sessionId: 'term-shell', cwd: '/repo', shell: 'zsh', loginShell: true } }, created);
       expect(created.statusCode).toBe(200);
-      if (process.platform === 'linux') {
+      if (process.platform !== 'win32') {
         expect(harness.processes[0].shell).toMatch(/\/env$/);
-        expect(harness.processes[0].args).toEqual(['-u', 'ARGV0', '/bin/zsh', '-l']);
+        expect(harness.processes[0].args).toEqual(['-u', 'ARGV0', '-u', 'NODE_CHANNEL_FD', '/bin/zsh', '-l']);
       } else {
         expect(harness.processes[0].shell).toBe('/bin/zsh');
         expect(harness.processes[0].args).toEqual(['-l']);
@@ -428,9 +428,9 @@ describe('terminal runtime', () => {
       const restarted = createResponse();
       await harness.routes.post.get('/api/terminal/:sessionId/restart')({ params: { sessionId: 'term-shell' }, body: { shell: 'bash', loginShell: true } }, restarted);
       expect(restarted.statusCode).toBe(200);
-      if (process.platform === 'linux') {
+      if (process.platform !== 'win32') {
         expect(harness.processes[1].shell).toMatch(/\/env$/);
-        expect(harness.processes[1].args).toEqual(['-u', 'ARGV0', '/bin/bash', '-l']);
+        expect(harness.processes[1].args).toEqual(['-u', 'ARGV0', '-u', 'NODE_CHANNEL_FD', '/bin/bash', '-l']);
       } else {
         expect(harness.processes[1].shell).toBe('/bin/bash');
         expect(harness.processes[1].args).toEqual(['-l']);
@@ -682,8 +682,8 @@ describe('terminal runtime', () => {
       sockets.push(first.socket);
       first.socket.send(createTerminalWsControlFrame({ t: 'attach', v: 3, s: 'term-live' }));
       first.socket.send(createTerminalWsControlFrame({ t: 'attach', v: 3, s: 'term-second' }));
-      expect(await first.next('snapshot', 'term-live')).toMatchObject({ s: 'term-live', q: 0, history: '', status: 'running' });
-      expect(await first.next('snapshot', 'term-second')).toMatchObject({ s: 'term-second', q: 0, history: '', status: 'running' });
+      expect(await first.next('snapshot', 'term-live')).toMatchObject({ s: 'term-live', q: 0, history: '', status: 'running', cols: 80, rows: 24 });
+      expect(await first.next('snapshot', 'term-second')).toMatchObject({ s: 'term-second', q: 0, history: '', status: 'running', cols: 80, rows: 24 });
       first.socket.send(createTerminalWsControlFrame({ t: 'write', v: 3, s: 'term-live', d: 'echo ok\r' }));
       first.socket.send(createTerminalWsControlFrame({ t: 'write', v: 3, s: 'term-second', d: 'pwd\r' }));
       first.socket.send(createTerminalWsControlFrame({ t: 'write', v: 3, s: 'term-live', d: 'echo next\r' }));
@@ -707,10 +707,17 @@ describe('terminal runtime', () => {
       expect(secondClosed.status).toBe(200);
       first.socket.close();
 
+      // A reconnecting client replays history at the size the PTY currently has.
+      const resized = await fetch(`${base}/api/terminal/term-live/resize`, {
+        method: 'POST', headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ cols: 120, rows: 40 }),
+      });
+      expect(resized.status).toBe(200);
+
       const second = await openTerminalSocket(socketUrl);
       sockets.push(second.socket);
       second.socket.send(createTerminalWsControlFrame({ t: 'attach', v: 3, s: 'term-live' }));
-      expect(await second.next('snapshot')).toMatchObject({ s: 'term-live', q: 2, history: 'ok\r\n', status: 'running' });
+      expect(await second.next('snapshot')).toMatchObject({ s: 'term-live', q: 2, history: 'ok\r\n', status: 'running', cols: 120, rows: 40 });
       processes[0].emitExit(7);
       expect(await second.next('exit')).toMatchObject({ s: 'term-live', q: 3, exitCode: 7 });
 
@@ -750,9 +757,9 @@ describe('terminal runtime', () => {
 
       expect(response.statusCode).toBe(200);
       expect(response.body).toEqual({ sessionId: 'term-command', cols: 80, rows: 24, status: 'running', mode: 'command', purpose: { type: 'terminal' } });
-      if (process.platform === 'linux') {
+      if (process.platform !== 'win32') {
         expect(harness.processes[0].shell).toMatch(/\/env$/);
-        expect(harness.processes[0].args).toEqual(['-u', 'ARGV0', '/bin/bash', '-l', '-i', '-c', 'printf ready']);
+        expect(harness.processes[0].args).toEqual(['-u', 'ARGV0', '-u', 'NODE_CHANNEL_FD', '/bin/bash', '-l', '-i', '-c', 'printf ready']);
       } else {
         expect(harness.processes[0].args).toEqual(['-l', '-i', '-c', 'printf ready']);
       }