@vantran-se/openchamber-web 1.23.0 → 1.24.3

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

@@ -0,0 +1,203 @@
+import { createServer } from 'node:http';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createSessionAssistRuntime } from './runtime.js';
+
+const resources = [];
+const message = (id, role, text, extra = {}) => ({
+  info: { id, role, parentID: 'user', finish: 'stop', time: { completed: 1 }, providerID: 'test-provider', modelID: 'test-model', ...extra },
+  parts: [{ type: 'text', text }],
+});
+const output = (recap = 'Зміни готові', suggestion = '') => ({ text: JSON.stringify({ recap, suggestion }), providerID: 'test-provider', modelID: 'test-model' });
+const pause = () => new Promise((resolve) => setTimeout(resolve, 15));
+
+async function fixture(generate = async () => output()) {
+  const state = {
+    messages: [message('user', 'user', 'Виправ помилку'), message('answer', 'assistant', 'Виправлено')],
+    session: { id: 'session', directory: '/project', time: {}, metadata: { external: 'keep', openchamber: { note: 'keep' } } },
+    targets: { recap: true, suggestion: true },
+    gets: 0, failFresh: false, patches: [], requests: [], calls: [],
+  };
+  const server = createServer(async (request, response) => {
+    const url = new URL(request.url, 'http://localhost');
+    state.requests.push({ method: request.method, directory: url.searchParams.get('directory'), limit: url.searchParams.get('limit'), auth: request.headers['x-test-auth'] });
+    response.setHeader('content-type', 'application/json');
+    if (request.method === 'PATCH') {
+      const chunks = [];
+      for await (const chunk of request) chunks.push(chunk);
+      state.patches.push(JSON.parse(Buffer.concat(chunks).toString()));
+      response.end(JSON.stringify(state.session));
+    } else if (url.pathname.endsWith('/message')) {
+      response.end(JSON.stringify(url.searchParams.get('limit') === '1' ? state.messages.slice(-1) : state.messages));
+    } else {
+      state.gets++;
+      response.statusCode = state.failFresh && state.gets > 1 ? 500 : 200;
+      response.end(JSON.stringify(state.session));
+    }
+  });
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const base = `http://127.0.0.1:${server.address().port}`;
+  state.base = base;
+  const runtime = createSessionAssistRuntime({
+    buildOpenCodeUrl: (route) => state.base + route,
+    getOpenCodeAuthHeaders: () => ({ 'x-test-auth': 'fixture' }),
+    getTargets: () => state.targets,
+    quietMs: 1,
+    getSmallModelService: async () => ({
+      describeSmallModel: async () => ({ inputCharBudget: 64_000 }),
+      generateSmallModelText: async (args) => { state.calls.push(args); return generate(args, state); },
+    }),
+  });
+  resources.push({ runtime, server });
+  const status = (type) => runtime.processPayload({ type: 'session.status', properties: { sessionID: 'session', status: { type } } }, '/project');
+  return { state, runtime, status };
+}
+
+afterEach(async () => {
+  for (const { runtime, server } of resources.splice(0)) {
+    runtime.stop();
+    server.closeAllConnections();
+    await new Promise((resolve) => server.close(resolve));
+  }
+  vi.restoreAllMocks();
+});
+
+describe('session assist runtime', () => {
+  it('uses bounded authenticated SDK reads and preserves metadata with an empty suggestion', async () => {
+    const { state, status } = await fixture(async (_args, current) => {
+      current.session.metadata.openchamber.concurrent = 'new';
+      return output();
+    });
+    status('idle');
+    await vi.waitFor(() => expect(state.patches).toHaveLength(1));
+    expect(state.requests.every((r) => r.directory === '/project' && r.auth === 'fixture')).toBe(true);
+    expect(state.requests.filter((r) => r.limit).map((r) => r.limit)).toEqual(['50', '1']);
+    expect(state.calls[0]).toMatchObject({ restrictToPreferredProvider: true, onOverflow: 'error', preferredProviderID: 'test-provider', preferredModelID: 'test-model', sessionID: 'session' });
+    expect(state.patches[0].metadata).toMatchObject({ external: 'keep', openchamber: {
+      note: 'keep', concurrent: 'new', assist: { recap: 'Зміни готові', suggestion: '', forMessageID: 'answer' },
+    } });
+  });
+
+  it('does no work with both settings off and skips child, archived, or reverted sessions', async () => {
+    const { state, status } = await fixture();
+    state.targets = { recap: false, suggestion: false };
+    status('idle');
+    await pause();
+    expect(state.requests).toHaveLength(0);
+    state.targets.recap = true;
+    state.session.parentID = 'parent';
+    status('idle');
+    await vi.waitFor(() => expect(state.gets).toBe(1));
+    delete state.session.parentID;
+    state.session.revert = { messageID: 'user' };
+    status('idle');
+    await vi.waitFor(() => expect(state.gets).toBe(2));
+    delete state.session.revert;
+    state.session.time.archived = 1;
+    status('idle');
+    await vi.waitFor(() => expect(state.gets).toBe(3));
+    expect(state.calls).toHaveLength(0);
+  });
+
+  it('keeps recent context for recap-only and performs no write for an empty suggestion-only result', async () => {
+    const { state, status } = await fixture();
+    state.targets.suggestion = false;
+    state.messages.unshift(message('previous-user', 'user', 'Попередня задача'), message('previous-answer', 'assistant', 'Зміст зробленого', { parentID: 'previous-user' }));
+    status('idle');
+    await vi.waitFor(() => expect(state.patches).toHaveLength(1));
+    expect(state.calls[0].prompt).toContain('Зміст зробленого');
+    expect(state.calls[0].system).not.toContain('suggestion');
+    state.targets = { recap: false, suggestion: true };
+    status('idle');
+    await vi.waitFor(() => expect(state.calls).toHaveLength(2));
+    await pause();
+    expect(state.patches).toHaveLength(1);
+  });
+
+  it('does not write a stale result when the tail moves during generation', async () => {
+    const { state, status } = await fixture(async (_args, current) => {
+      current.messages.push(message('new-user', 'user', 'Нова задача'));
+      return output();
+    });
+    status('idle');
+    await vi.waitFor(() => expect(state.requests.some((r) => r.limit === '1')).toBe(true));
+    await pause();
+    expect(state.patches).toHaveLength(0);
+  });
+
+  it('does not fall back to stale metadata when the fresh read fails', async () => {
+    const warning = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const { state, status } = await fixture();
+    state.failFresh = true;
+    status('idle');
+    await vi.waitFor(() => expect(warning).toHaveBeenCalled());
+    expect(state.gets).toBe(2);
+    expect(state.patches).toHaveLength(0);
+  });
+
+  it('cancels old work and retains an expired newer idle timer until it can run', async () => {
+    const releases = [];
+    const { state, status } = await fixture(() => new Promise((resolve) => releases.push(resolve)));
+    status('idle');
+    await vi.waitFor(() => expect(releases).toHaveLength(1));
+    status('busy');
+    expect(state.calls[0].signal.aborted).toBe(true);
+    state.messages.push(message('next-user', 'user', 'Далі'), message('next-answer', 'assistant', 'Готово', { parentID: 'next-user' }));
+    status('idle');
+    await pause();
+    releases[0](output('Старий результат'));
+    await vi.waitFor(() => expect(releases).toHaveLength(2));
+    expect(state.patches).toHaveLength(0);
+    releases[1](output('Новий результат'));
+    await vi.waitFor(() => expect(state.patches).toHaveLength(1));
+    expect(state.patches[0].metadata.openchamber.assist).toMatchObject({ recap: 'Новий результат', forMessageID: 'next-answer' });
+  });
+
+  it('aborts on stop and honors settings switched off during generation', async () => {
+    let release;
+    const { state, runtime, status } = await fixture(() => new Promise((resolve) => { release = resolve; }));
+    status('idle');
+    await vi.waitFor(() => expect(state.calls).toHaveLength(1));
+    runtime.stop();
+    expect(state.calls[0].signal.aborted).toBe(true);
+    release(output());
+    await pause();
+    expect(state.patches).toHaveLength(0);
+    const second = await fixture(async (_args, current) => {
+      current.targets = { recap: false, suggestion: false };
+      return output();
+    });
+    second.status('idle');
+    await vi.waitFor(() => expect(second.state.gets).toBe(2));
+    await pause();
+    expect(second.state.patches).toHaveLength(0);
+  });
+
+  it('ignores historical user updates but cancels a new request during generation', async () => {
+    let release;
+    const { state, runtime, status } = await fixture(() => new Promise((resolve) => { release = resolve; }));
+    status('idle');
+    await vi.waitFor(() => expect(state.calls).toHaveLength(1));
+    const userUpdate = (created) => runtime.processPayload({ type: 'message.updated', properties: {
+      info: { id: 'user', sessionID: 'session', role: 'user', time: { created } },
+    } });
+    userUpdate(1);
+    expect(state.calls[0].signal.aborted).toBe(false);
+    userUpdate(Date.now());
+    expect(state.calls[0].signal.aborted).toBe(true);
+    release(output());
+    await pause();
+    expect(state.patches).toHaveLength(0);
+  });
+
+  it('rejects endpoint changes before writing instead of carrying a session into a new runtime', async () => {
+    const warning = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const { state, status } = await fixture(async (_args, current) => {
+      current.base = 'http://unreachable.invalid';
+      return output();
+    });
+    status('idle');
+    await vi.waitFor(() => expect(warning).toHaveBeenCalled());
+    expect(state.patches).toHaveLength(0);
+    expect(state.gets).toBe(1);
+  });
+});

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

@@ -118,14 +118,26 @@ other runtime API.
     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 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
+     (4) the provider-level runtime endpoint, (5) the provider's `api` field
+     from the models.dev catalog, or (6) `SDK_DEFAULT_BASE_URLS` — providers
+     such as Groq, xAI, and Mistral keep their endpoint inside a dedicated AI
+     SDK package, so neither the catalog nor OpenCode reports one. 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
     their own header work here exactly as they do in a chat turn. Configured API
     keys and header values honor OpenCode's `{env:NAME}` and `{file:path}`
     substitutions; file contents and resolved credentials remain server-side.
+  - `thinking: { type: 'disabled' }` is sent in two cases, mirroring OpenCode's
+    `transform.ts`. The GLM switch belongs to the endpoint, not the model
+    family: it goes to a provider whose id contains `zai`/`zhipu` or whose
+    base URL is on `api.z.ai`/`bigmodel.cn`, because the same GLM model served
+    by another provider (OpenCode Go) rejects the unknown field with a 400.
+    The MiniMax M3 switch goes only behind the `@ai-sdk/openai-compatible` and
+    `@ai-sdk/anthropic` adapters (runtime model, then catalog model, then
+    catalog provider `npm`); a provider that reports no adapter counts as
+    OpenAI-compatible.
   - The runtime credential is refused for providers listed in
     `OWN_CREDENTIAL_HANDLING`. Their branches need the stored entry rather than
     a bearer token: the clearest case is the ChatGPT-plan `openai` login, whose

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

@@ -20,6 +20,25 @@ const DEFAULT_MAX_OUTPUT_TOKENS = 4_000;
 
 const USER_AGENT = 'opencode/1.0 openchamber';
 
+// Providers whose endpoint lives inside their dedicated AI SDK package, so the
+// models.dev catalog carries no `api` URL and OpenCode reports none at runtime.
+// Each of these serves OpenAI-compatible `/chat/completions` at the URL below.
+const SDK_DEFAULT_BASE_URLS = new Map([
+  ['groq', 'https://api.groq.com/openai/v1'],
+  ['xai', 'https://api.x.ai/v1'],
+  ['mistral', 'https://api.mistral.ai/v1'],
+  ['cerebras', 'https://api.cerebras.ai/v1'],
+  ['togetherai', 'https://api.together.xyz/v1'],
+  ['deepinfra', 'https://api.deepinfra.com/v1/openai'],
+  ['perplexity', 'https://api.perplexity.ai'],
+  ['cohere', 'https://api.cohere.ai/compatibility/v1'],
+]);
+
+// Where `thinking: { type: 'disabled' }` is a real switch rather than an
+// unknown field (mirrors the gates in OpenCode's provider/transform.ts).
+const ZAI_ENDPOINT_HOSTS = ['api.z.ai', 'bigmodel.cn'];
+const MINIMAX_THINKING_ADAPTERS = new Set(['@ai-sdk/openai-compatible', '@ai-sdk/anthropic']);
+
 const mergeHeadersCaseInsensitive = (base, overrides) => {
   const merged = { ...base };
   for (const [name, value] of Object.entries(overrides || {})) {
@@ -765,7 +784,8 @@ export async function callSmallModel({ auth, catalog, workingDirectory, sessionI
   // 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
+  // plugin itself runs. Last comes SDK_DEFAULT_BASE_URLS, for providers whose
+  // endpoint only their SDK package knows. 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);
@@ -779,7 +799,7 @@ export async function callSmallModel({ auth, catalog, workingDirectory, sessionI
         ?? runtimeProvider?.baseURL
         ?? (typeof provider?.api === 'string' && provider.api
           ? provider.api
-          : null);
+          : SDK_DEFAULT_BASE_URLS.get(providerID) ?? null);
   if (!baseURL) {
     throw new Error(`Provider "${providerID}" has no known API base URL`);
   }
@@ -790,11 +810,22 @@ export async function callSmallModel({ auth, catalog, workingDirectory, sessionI
   // parameter: unknown body fields 400 on some providers, so this stays an
   // explicit allowlist. Models without a switch (DeepSeek, Qwen, Kimi, …)
   // just get the generous output budget.
-  const lowerModel = modelID.toLowerCase();
-  const supportsThinkingToggle = providerID.includes('zai')
+  // GLM's switch belongs to the Z.ai/Zhipu endpoints, not to the model: the
+  // same GLM served by another provider (OpenCode Go) rejects the field. The
+  // host check keeps the switch for a custom-named provider pointed at them.
+  const servedByZai = providerID.includes('zai')
     || providerID.includes('zhipu')
-    || lowerModel.includes('glm')
-    || lowerModel.includes('minimax-m3');
+    || ZAI_ENDPOINT_HOSTS.some((host) => baseURL.includes(host));
+  // MiniMax M3's switch is understood only behind the adapters OpenCode sends
+  // it through. An adapter nobody reports (a custom provider) is OpenAI-
+  // compatible by OpenCode's own default.
+  const adapter = runtimeModel?.api?.npm
+    ?? provider?.models?.[modelID]?.provider?.npm
+    ?? provider?.npm
+    ?? null;
+  const minimaxSwitch = modelID.toLowerCase().includes('minimax-m3')
+    && (adapter === null || MINIMAX_THINKING_ADAPTERS.has(adapter));
+  const supportsThinkingToggle = servedByZai || minimaxSwitch;
   const extraBody = supportsThinkingToggle ? { thinking: { type: 'disabled' } } : undefined;
 
   return callOpenaiCompatible({

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

@@ -772,6 +772,188 @@ describe('callSmallModel — Google thinking configuration', () => {
   });
 });
 
+describe('callSmallModel — OpenAI-compatible thinking toggle', () => {
+  let fetchMock;
+  let originalFetch;
+
+  beforeEach(() => {
+    fetchMock = vi.fn();
+    originalFetch = globalThis.fetch;
+    globalThis.fetch = fetchMock;
+    readConfig.mockReset();
+    readConfig.mockReturnValue({});
+    readConfigLayers.mockReset();
+    readConfigLayers.mockReturnValue({ mergedConfig: {} });
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  const requestBody = async ({ providerID, modelID }) => {
+    fetchMock.mockResolvedValue(ok('done'));
+    await callSmallModel({
+      auth: { [providerID]: { type: 'api', key: 'sk-test' } },
+      catalog: { [providerID]: { id: providerID, api: 'https://provider.test/v1', models: {} } },
+      workingDirectory: '/proj',
+      providerID,
+      modelID,
+      prompt: 'summarize',
+    });
+    return JSON.parse(lastCall(fetchMock).init.body);
+  };
+
+  it('does not send the thinking field for a GLM model served by OpenCode Go', async () => {
+    const body = await requestBody({ providerID: 'opencode-go', modelID: 'glm-5.3-flash' });
+    expect(body.thinking).toBeUndefined();
+  });
+
+  it('disables thinking on the Z.ai and Zhipu endpoints', async () => {
+    const zai = await requestBody({ providerID: 'zai-coding-plan', modelID: 'glm-5.3-flash' });
+    expect(zai.thinking).toEqual({ type: 'disabled' });
+    const zhipu = await requestBody({ providerID: 'zhipuai', modelID: 'glm-5.3-flash' });
+    expect(zhipu.thinking).toEqual({ type: 'disabled' });
+  });
+
+  it('keeps the GLM switch for a custom-named provider pointed at a Z.ai endpoint', async () => {
+    fetchMock.mockResolvedValue(ok('done'));
+    await callSmallModel({
+      auth: { 'my-glm': { type: 'api', key: 'sk-test' } },
+      catalog: { 'my-glm': { id: 'my-glm', api: 'https://api.z.ai/api/coding/paas/v4', models: {} } },
+      workingDirectory: '/proj',
+      providerID: 'my-glm',
+      modelID: 'glm-5.3-flash',
+      prompt: 'summarize',
+    });
+    expect(JSON.parse(lastCall(fetchMock).init.body).thinking).toEqual({ type: 'disabled' });
+  });
+
+  const minimaxBody = async (providerEntry) => {
+    fetchMock.mockResolvedValue(ok('done'));
+    await callSmallModel({
+      auth: { host: { type: 'api', key: 'sk-test' } },
+      catalog: { host: { id: 'host', api: 'https://provider.test/v1', ...providerEntry } },
+      workingDirectory: '/proj',
+      providerID: 'host',
+      modelID: 'minimax-m3',
+      prompt: 'summarize',
+    });
+    return JSON.parse(lastCall(fetchMock).init.body);
+  };
+
+  it('disables MiniMax M3 thinking behind an OpenAI-compatible adapter', async () => {
+    const body = await minimaxBody({ npm: '@ai-sdk/openai-compatible', models: {} });
+    expect(body.thinking).toEqual({ type: 'disabled' });
+  });
+
+  it('honors a model-level adapter over the provider one for MiniMax M3', async () => {
+    const body = await minimaxBody({
+      npm: '@ai-sdk/deepinfra',
+      models: { 'minimax-m3': { provider: { npm: '@ai-sdk/anthropic' } } },
+    });
+    expect(body.thinking).toEqual({ type: 'disabled' });
+  });
+
+  it('does not send the MiniMax M3 switch through an adapter that has none', async () => {
+    const body = await minimaxBody({ npm: '@ai-sdk/deepinfra', models: {} });
+    expect(body.thinking).toBeUndefined();
+  });
+
+  it('treats a provider with no reported adapter as OpenAI-compatible for MiniMax M3', async () => {
+    const body = await minimaxBody({ models: {} });
+    expect(body.thinking).toEqual({ type: 'disabled' });
+  });
+});
+
+describe('callSmallModel — providers with an SDK-owned endpoint', () => {
+  let fetchMock;
+  let originalFetch;
+
+  beforeEach(() => {
+    fetchMock = vi.fn();
+    originalFetch = globalThis.fetch;
+    globalThis.fetch = fetchMock;
+    readConfig.mockReset();
+    readConfig.mockReturnValue({});
+    readConfigLayers.mockReset();
+    readConfigLayers.mockReturnValue({ mergedConfig: {} });
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  it.each([
+    ['groq', 'https://api.groq.com/openai/v1'],
+    ['xai', 'https://api.x.ai/v1'],
+    ['mistral', 'https://api.mistral.ai/v1'],
+    ['cerebras', 'https://api.cerebras.ai/v1'],
+    ['togetherai', 'https://api.together.xyz/v1'],
+    ['deepinfra', 'https://api.deepinfra.com/v1/openai'],
+    ['perplexity', 'https://api.perplexity.ai'],
+    ['cohere', 'https://api.cohere.ai/compatibility/v1'],
+  ])('calls %s at its default endpoint when the catalog has no api URL', async (providerID, baseURL) => {
+    fetchMock.mockResolvedValue(ok('done'));
+
+    const text = await callSmallModel({
+      auth: { [providerID]: { type: 'api', key: 'key-test' } },
+      catalog: { [providerID]: { id: providerID, api: null, models: {} } },
+      workingDirectory: '/proj',
+      providerID,
+      modelID: 'some-model',
+      prompt: 'summarize',
+    });
+
+    expect(text).toBe('done');
+    expect(lastCall(fetchMock).url).toBe(`${baseURL}/chat/completions`);
+  });
+
+  it('prefers a catalog api URL over the default endpoint', async () => {
+    fetchMock.mockResolvedValue(ok('done'));
+
+    await callSmallModel({
+      auth: { groq: { type: 'api', key: 'key-test' } },
+      catalog: { groq: { id: 'groq', api: 'https://catalog.test/v1', models: {} } },
+      workingDirectory: '/proj',
+      providerID: 'groq',
+      modelID: 'some-model',
+      prompt: 'summarize',
+    });
+
+    expect(lastCall(fetchMock).url).toBe('https://catalog.test/v1/chat/completions');
+  });
+
+  it('prefers a configured baseURL over the default endpoint', async () => {
+    readConfig.mockReturnValue({
+      provider: { groq: { options: { baseURL: 'https://proxy.test/v1' } } },
+    });
+    fetchMock.mockResolvedValue(ok('done'));
+
+    await callSmallModel({
+      auth: { groq: { type: 'api', key: 'key-test' } },
+      catalog: { groq: { id: 'groq', api: null, models: {} } },
+      workingDirectory: '/proj',
+      providerID: 'groq',
+      modelID: 'some-model',
+      prompt: 'summarize',
+    });
+
+    expect(lastCall(fetchMock).url).toBe('https://proxy.test/v1/chat/completions');
+  });
+
+  it('still fails clearly for a provider with no endpoint anywhere', async () => {
+    await expect(callSmallModel({
+      auth: { mystery: { type: 'api', key: 'sk-test' } },
+      catalog: {},
+      workingDirectory: '/proj',
+      providerID: 'mystery',
+      modelID: 'some-model',
+      prompt: 'summarize',
+    })).rejects.toThrow('has no known API base URL');
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+});
+
 describe('callSmallModel — GitHub Copilot endpoint routing', () => {
   let fetchMock;
   let originalFetch;

package/server/lib/terminal/DOCUMENTATION.md

@@ -2,7 +2,7 @@
 
 ## Ownership
 
-`runtime.js` owns terminal identity, PTY processes, launch mode, session purpose, ordered output, bounded scrollback, WebSocket attachments, and lifecycle routes. `shells.js` discovers executable shell families, resolves the persisted shell ID, and builds the per-shell argv for interactive versus command launches. Clients own tab arrangement. Interactive terminals use stable IDs; project actions keep a stable UI tab and allocate a fresh terminal ID for each command execution. Electron uses this same runtime in-process; VS Code returns an explicit unsupported error.
+`runtime.js` owns terminal identity, PTY processes, launch mode, session purpose, ordered output, bounded scrollback, WebSocket attachments, and lifecycle routes. `shutdown.js` owns bounded runtime-wide process cleanup. `shells.js` discovers executable shell families, resolves the persisted shell ID, and builds the per-shell argv for interactive versus command launches. Clients own tab arrangement. Interactive terminals use stable IDs; project actions keep a stable UI tab and allocate a fresh terminal ID for each command execution. Electron uses this same runtime in-process; VS Code returns an explicit unsupported error.
 
 ## Protocol
 
@@ -37,8 +37,11 @@ HTTP remains the authenticated command plane for create, resize, appearance upda
 - 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 OpenChamber) 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 restart rechecks session ownership before and after PTY creation. Close, force-kill, idle removal, or shutdown can invalidate it while spawn is pending. A late replacement is terminated instead of being attached to a retired session.
 - 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.
+- Close uses SIGTERM with bounded SIGKILL escalation. Force-kill and idle cleanup 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.
+- Shutdown is single-flight, rejects new creates, cancels pending creates, and waits for pending creates and restarts before clearing live sessions. A PTY that arrives during shutdown follows the same cancellation cleanup as a pending create that was explicitly closed.
+- On POSIX, shutdown disconnects input and gives terminal workloads a shared 20-second SIGTERM grace. Process-table snapshots retain descendant ownership across shell exit and separate job-control groups; PID start times guard against reused PIDs. Linux reads `/proc` directly so minimal containers do not need `ps`. Shells remain open until the workloads exit, then receive SIGHUP. An exec'ed server receives SIGTERM and the full grace even though it occupies the shell PID. Remaining processes receive SIGKILL at the deadline. A process-table failure warns and forces known owned processes closed. Windows retains ConPTY-owned teardown because it has no POSIX signal protocol.
 
 ## Security And Relay
 
@@ -50,5 +53,23 @@ Run:
 
 ```sh
 bun test packages/web/server/lib/terminal/runtime.test.js packages/web/server/lib/terminal/terminal-ws-protocol.test.js
+bun run --cwd packages/web test server/lib/terminal/shutdown.test.js
 bun test packages/web/server/lib/ui-auth/ui-auth.test.js packages/web/server/lib/relay/cross-compat.test.js
 ```
+
+The #3389 macOS ARM64 reproduction used real Electron 43.7.0 PTYs and HTTP
+servers with signal handlers that took 15 seconds to finish cleanup. On the
+baseline, File > Restart and Quit sent SIGKILL to the exec'ed server within
+3–4 ms; a foreground child in another process group received SIGHUP and outlived
+Electron. After the fix, both workloads completed after SIGTERM before Electron
+exited, in bundled and HMR runs. A noncooperative workload was killed after the
+shared 20-second deadline.
+
+Packaged test builds 1.24.90 and 1.24.91 exercised the real macOS Squirrel install
+with a loopback feed, isolated app identity/profile, and a shared test signing
+requirement. Both the normal update and closing the window during cleanup
+installed and relaunched N+1 after the terminal workloads finished. The installed
+ASAR matched N+1, and OpenCode remained bundled after its own restart. A rejected
+signature also reached the installer error handler after the 15-second cleanup.
+Linux ARM64 process regressions pass without `ps` installed. Native Windows
+ConPTY and Linux Electron installer behavior were not exercised for this fix.

package/server/lib/terminal/runtime.js

@@ -11,6 +11,7 @@ import { sanitizeTerminalHistoryChunk } from './history.js';
 import { consumeTerminalThemeQueries, terminalThemeModeReport } from './theme-response.js';
 import { buildTerminalShellLaunch, createTerminalShellResolver, normalizeTerminalShell } from './shells.js';
 import { stripAppImageArgv0Leak, resolvePosixPtyLaunch } from '../inherited-env.js';
+import { shutdownTerminalProcesses } from './shutdown.js';
 
 const MAX_SESSIONS = 20;
 const MAX_HISTORY_BYTES = 512 * 1024;
@@ -91,7 +92,7 @@ const trimHistory = (history) => {
 export function createTerminalRuntime({
   app, server, fs, path, uiAuthController, buildAugmentedPath, searchPathFor, isExecutable,
   isRequestOriginAllowed, rejectWebSocketUpgrade, TERMINAL_INPUT_WS_HEARTBEAT_INTERVAL_MS,
-  loadPtyProvider, terminalTerminationGraceMs = TERMINATION_GRACE_MS,
+  loadPtyProvider, terminalTerminationGraceMs = TERMINATION_GRACE_MS, shutdownProcesses = shutdownTerminalProcesses,
 }) {
   const sessions = new Map();
   const pendingSessionCreates = new Map();
@@ -100,6 +101,7 @@ export function createTerminalRuntime({
   const pendingTerminations = new Set();
   const runtime = typeof globalThis.Bun === 'undefined' ? 'node' : 'bun';
   let ptyProviderPromise = null;
+  let shutdownPromise = null;
   let wsServer = new WebSocketServer({ noServer: true, maxPayload: TERMINAL_WS_MAX_PAYLOAD_BYTES });
   const shellResolver = createTerminalShellResolver({ fs, path, searchPathFor, isExecutable, buildAugmentedPath });
 
@@ -135,7 +137,7 @@ export function createTerminalRuntime({
         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 };
+        return { process: await provider.spawn(launch.executable, launch.args, options), backend: provider.backend, shell: resolvedShell.id, shellExecutable: executable, loginShell };
       } catch (error) { lastError = error; }
     }
     throw lastError ?? new Error('No executable shell found');
@@ -273,6 +275,7 @@ export function createTerminalRuntime({
     if (clear) { session.history = ''; session.pendingHistoryControlSequence = ''; session.pendingThemeControlSequence = ''; session.themeModeEnabled = false; }
     session.cwd = cwd; session.cols = cols; session.rows = rows; session.process = spawned.process;
     session.backend = spawned.backend; session.shell = spawned.shell; session.loginShell = spawned.loginShell; session.status = 'running'; session.exitCode = null; session.signal = null;
+    session.shellExecutable = spawned.shellExecutable;
     session.mode = mode; session.command = mode === COMMAND_TERMINAL_MODE ? command : null;
     session.purpose = purpose;
     session.themeMode = themeMode === 'light' ? 'light' : 'dark'; session.terminalBackground = terminalBackground; session.terminalForeground = terminalForeground;
@@ -282,6 +285,7 @@ export function createTerminalRuntime({
   };
 
   const createSession = async ({ sessionId, cwd, cols = 80, rows = 24, themeMode, terminalBackground, terminalForeground, shell = 'auto', loginShell = false, mode, command, purpose }) => {
+    if (shutdownPromise) throw new Error('Terminal runtime is shutting down');
     if (!validateSize(cols, 1000) || !validateSize(rows, 500)) throw new Error('Invalid terminal dimensions');
     if (typeof loginShell !== 'boolean') throw new Error('Invalid terminal login mode');
     const normalizedShell = normalizeTerminalShell(shell);
@@ -507,11 +511,17 @@ export function createTerminalRuntime({
     const previousRestart = pendingSessionRestarts.get(session.id) ?? Promise.resolve();
     const restart = previousRestart.catch(() => {}).then(async () => {
       await validateCwd(cwd);
+      if (shutdownPromise || sessions.get(session.id) !== session) throw new Error('Terminal session was closed during restart');
       if (!validateSize(cols, 1000) || !validateSize(rows, 500)) throw new Error('Invalid terminal dimensions');
       if (typeof loginShell !== 'boolean') throw new Error('Invalid terminal login mode');
       const oldProcess = session.process;
       const spawned = await spawnPty({ cwd, cols, rows, themeMode, shell, loginShell });
+      if (shutdownPromise || sessions.get(session.id) !== session) {
+        await terminateProcess(spawned.process, true);
+        throw new Error('Terminal session was closed during restart');
+      }
       session.process = spawned.process; session.backend = spawned.backend; session.shell = spawned.shell; session.loginShell = spawned.loginShell; session.cwd = cwd; session.cols = cols; session.rows = rows;
+      session.shellExecutable = spawned.shellExecutable;
       session.history = ''; session.pendingHistoryControlSequence = ''; session.pendingThemeControlSequence = ''; session.themeModeEnabled = false; session.status = 'running'; session.exitCode = null; session.signal = null; session.eventQueue.length = 0;
       session.themeMode = themeMode === 'light' ? 'light' : 'dark'; session.terminalBackground = terminalBackground; session.terminalForeground = terminalForeground;
        wire(session, spawned.process); void terminateProcess(oldProcess); publish(session, { t: 'restarted', history: '' });
@@ -560,11 +570,19 @@ export function createTerminalRuntime({
     }
   }, 5 * 60 * 1000);
 
-  const shutdown = async () => {
+  const stop = async () => {
     server.off('upgrade', upgradeHandler); clearInterval(idleSweep);
-    await Promise.allSettled([...pendingSessionRestarts.values()]);
-    for (const session of sessions.values()) void terminateProcess(session.process, true);
+    for (const client of wsServer?.clients ?? []) client.terminate();
+    for (const pending of pendingSessionCreates.values()) pending.cancelled = true;
+    await Promise.allSettled([
+      ...[...pendingSessionCreates.values()].map((pending) => pending.promise),
+      ...pendingSessionRestarts.values(),
+    ]);
+    const terminals = [...sessions.values()]
+      .filter(session => session.status === 'running' && session.process)
+      .map(session => ({ process: session.process, shellExecutable: session.shellExecutable }));
     sessions.clear();
+    await shutdownProcesses(terminals);
     await Promise.allSettled([...pendingTerminations]);
     if (!wsServer) return;
     for (const client of wsServer.clients) client.terminate();
@@ -574,5 +592,9 @@ export function createTerminalRuntime({
     ]);
     wsServer = null;
   };
+  const shutdown = () => {
+    if (!shutdownPromise) shutdownPromise = stop();
+    return shutdownPromise;
+  };
   return { shutdown };
 }