@openchambery/web 1.19.20 → 2.0.0-beta.1

package/server/lib/message-queue/opencode-adapter.test.js

@@ -1,24 +1,52 @@
 import { describe, expect, it, vi } from 'vitest';
 
-vi.mock('@opencode-ai/sdk/v2', () => ({ createOpencodeClient: vi.fn() }));
-const { createOpencodeClient } = await import('@opencode-ai/sdk/v2');
+vi.mock('../opencode/v2-client.js', () => ({ makeOpenCodeV2Client: vi.fn() }));
+const { makeOpenCodeV2Client } = await import('../opencode/v2-client.js');
 const { createOpenCodeMessageQueueAdapter } = await import('./opencode-adapter.js');
 const { createSessionTurnGate } = await import('./session-turn-gate.js');
 
+const notFound = (status = 404) => Object.assign(new Error('not_found'), { status, code: 'not_found' });
+const v2Client = ({ active = {}, list = { data: [] }, inbox = [], message } = {}) => ({
+  session: {
+    active: vi.fn(async () => active),
+    inbox: { list: vi.fn(async () => inbox) },
+    message: vi.fn(async ({ messageID }) => {
+      if (typeof message === 'function') return message(messageID);
+      if (message && typeof message === 'object' && messageID in message) return message[messageID];
+      throw notFound();
+    }),
+  },
+  message: { list: vi.fn(async () => list) },
+});
+
 describe('OpenCode message queue adapter', () => {
   it('waits for readiness without forwarding worker options', async () => {
     const waitForReady = vi.fn(); const adapter = createOpenCodeMessageQueueAdapter({ waitForReady });
     await adapter.waitForReady({ signal: new AbortController().signal });
     expect(waitForReady).toHaveBeenCalledWith();
   });
-  it('captures runtime, materializes text and files, and sends the captured configuration', async () => {
-    const promptAsync = vi.fn(() => ({ data: {}, response: { status: 204 } })); createOpencodeClient.mockReturnValue({ session: { promptAsync, messages: vi.fn(() => ({ data: [] })) } });
+  it('captures runtime, materializes text and files, and applies sendConfig before prompt', async () => {
+    const fetchMock = vi.fn(async () => ({ ok: true, status: 204, json: async () => ({}) }));
+    vi.stubGlobal('fetch', fetchMock);
+    makeOpenCodeV2Client.mockReturnValue(v2Client());
     let generation = 1;
     const adapter = createOpenCodeMessageQueueAdapter({ waitForReady: vi.fn(), buildOpenCodeUrl: () => 'http://open.code/', getOpenCodeAuthHeaders: () => ({ Authorization: 'secret' }), getRuntimeConfig: () => ({ apiBaseUrl: 'http://open.code' }), getRuntimeGeneration: () => generation, getSessionEligibility: () => ({ idle: true, settled: true }), getLatestMessageID: () => 'old', readAttachment: () => ({ type: 'file', url: 'file:///attachment' }) });
     const runtime = adapter.captureRuntime(); const scope = { sessionID: 'session', directory: '/repo' }; expect(await adapter.checkEligibility(scope)).toMatchObject({ available: true, idle: true, settled: true, latestMessageID: 'old' });
     const parts = await adapter.materializeAttachments({ content: 'text', attachments: [{}] }); expect(parts).toEqual([{ type: 'text', text: 'text' }, { type: 'file', url: 'file:///attachment' }]);
-    await adapter.send({ scope, messageID: 'message', runtime, sendConfig: { providerID: 'p', modelID: 'm', agent: 'a', variant: 'v' }, parts }); expect(promptAsync).toHaveBeenCalledWith(expect.objectContaining({ sessionID: 'session', directory: '/repo', messageID: 'message', model: { providerID: 'p', modelID: 'm' }, agent: 'a', variant: 'v', parts }), expect.any(Object));
+    await adapter.send({ scope, messageID: 'message', runtime, sendConfig: { providerID: 'p', modelID: 'm', agent: 'a', variant: 'v' }, parts });
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+    expect(String(fetchMock.mock.calls[0][0])).toContain('/api/session/session/agent');
+    expect(JSON.parse(fetchMock.mock.calls[0][1].body)).toEqual({ agent: 'a' });
+    expect(String(fetchMock.mock.calls[1][0])).toContain('/api/session/session/model');
+    expect(JSON.parse(fetchMock.mock.calls[1][1].body)).toEqual({ model: { id: 'm', providerID: 'p', variant: 'v' } });
+    expect(String(fetchMock.mock.calls[2][0])).toContain('/api/session/session/prompt');
+    const promptBody = JSON.parse(fetchMock.mock.calls[2][1].body);
+    expect(promptBody).toEqual(expect.objectContaining({ id: 'message', delivery: 'steer', text: 'text' }));
+    expect(promptBody.model).toBeUndefined();
+    expect(promptBody.agent).toBeUndefined();
+    expect(promptBody.variant).toBeUndefined();
     generation = 2; expect(await adapter.send({ scope, runtime, sendConfig: { providerID: 'p', modelID: 'm' } })).toMatchObject({ code: 'runtime_stale' });
+    vi.unstubAllGlobals();
   });
   it('materializes Assistant attachment IDs in delivery order', async () => {
     const readAttachment = vi.fn((attachment) => ({ type: 'file', url: `file:///${attachment.attachmentID}`, filename: attachment.filename }));
@@ -30,110 +58,352 @@ describe('OpenCode message queue adapter', () => {
     expect(readAttachment).toHaveBeenCalledWith({ attachmentID: 'image', filename: 'image.png' }, expect.any(Object), expect.any(Object));
   });
   it('uses the injected upstream runtime URL and detects its changes', async () => {
-    const promptAsync = vi.fn(() => ({ data: {}, response: { status: 204 } }));
-    createOpencodeClient.mockReturnValue({ session: { promptAsync, messages: vi.fn(() => ({ data: [] })) } });
+    const fetchMock = vi.fn(async () => ({ ok: true, status: 204, json: async () => ({}) }));
+    vi.stubGlobal('fetch', fetchMock);
+    makeOpenCodeV2Client.mockReturnValue(v2Client());
     let upstreamUrl = 'http://opencode-upstream:4096/';
     const adapter = createOpenCodeMessageQueueAdapter({ buildOpenCodeUrl: () => upstreamUrl, getOpenCodeAuthHeaders: () => ({}), getRuntimeConfig: () => ({ apiBaseUrl: upstreamUrl }), readAttachment: () => null });
     const runtime = adapter.captureRuntime();
     await adapter.send({ scope: { sessionID: 's', directory: '/repo' }, messageID: 'msg_1', runtime, sendConfig: { providerID: 'p', modelID: 'm' }, parts: [] });
-    expect(createOpencodeClient).toHaveBeenCalledWith(expect.objectContaining({ baseUrl: 'http://opencode-upstream:4096' }));
+    const promptCall = fetchMock.mock.calls.find(([url]) => String(url).includes('/prompt'));
+    expect(String(promptCall[0])).toContain('http://opencode-upstream:4096/api/session/s/prompt');
     upstreamUrl = 'http://opencode-upstream:4097/';
     expect(adapter.isCurrent(runtime)).toBe(false);
+    vi.unstubAllGlobals();
   });
   it('classifies SDK results and exact reconciliation matches without exposing transport details', async () => {
-    const messages = vi.fn(() => ({ data: [{ id: 'other' }, { id: 'wanted' }] })); createOpencodeClient.mockReturnValue({ session: { promptAsync: vi.fn(() => ({ error: {}, response: { status: 503 } })), messages } });
+    const fetchMock = vi.fn(async () => ({ ok: false, status: 503, json: async () => ({}) }));
+    vi.stubGlobal('fetch', fetchMock);
+    makeOpenCodeV2Client.mockReturnValue(v2Client({ inbox: [{ id: 'wanted', sessionID: 's' }] }));
     const adapter = createOpenCodeMessageQueueAdapter({ buildOpenCodeUrl: () => 'http://open.code/', getOpenCodeAuthHeaders: () => ({}), getSessionEligibility: () => ({ idle: true, settled: true }), getLatestMessageID: () => null, readAttachment: () => null });
-    expect(await adapter.send({ scope: { sessionID: 's', directory: '/d' }, messageID: 'm', sendConfig: { providerID: 'p', modelID: 'm' } })).toMatchObject({ kind: 'ambiguous', status: 503 }); expect(await adapter.findMessage({ sessionID: 's', directory: '/d' }, 'wanted')).toEqual({ found: true });
+    // Prompt-only path (no sendConfig) classifies transport status on the POST itself.
+    expect(await adapter.send({ scope: { sessionID: 's', directory: '/d' }, messageID: 'm', parts: [] })).toMatchObject({ kind: 'ambiguous', status: 503 });
+    expect(await adapter.findMessage({ sessionID: 's', directory: '/d' }, 'wanted')).toEqual({ found: true });
+    vi.unstubAllGlobals();
   });
   it('treats explicit 2xx empty bodies as ok and never treats undefined/malformed results as success', async () => {
-    const promptAsync = vi.fn()
-      .mockReturnValueOnce({ data: undefined, error: null, response: { status: 204 } })
-      .mockReturnValueOnce({ data: undefined, error: undefined, response: { status: 202 } })
-      .mockReturnValueOnce({ data: {}, error: null, response: { status: 200 } })
-      .mockReturnValueOnce(undefined)
-      .mockReturnValueOnce(null)
-      .mockReturnValueOnce({});
-    createOpencodeClient.mockReturnValue({ session: { promptAsync, messages: vi.fn(() => ({ data: [] })) } });
+    const fetchMock = vi.fn()
+      .mockResolvedValueOnce({ ok: true, status: 204, json: async () => undefined })
+      .mockResolvedValueOnce({ ok: true, status: 202, json: async () => undefined })
+      .mockResolvedValueOnce({ ok: true, status: 200, json: async () => ({}) })
+      .mockResolvedValueOnce(undefined)
+      .mockResolvedValueOnce(null)
+      .mockResolvedValueOnce({});
+    vi.stubGlobal('fetch', fetchMock);
     const adapter = createOpenCodeMessageQueueAdapter({ buildOpenCodeUrl: () => 'http://open.code/', getOpenCodeAuthHeaders: () => ({}), getRuntimeConfig: () => ({ apiBaseUrl: 'http://open.code' }), readAttachment: () => null });
-    const base = { scope: { sessionID: 's', directory: '/d' }, messageID: 'm', sendConfig: { providerID: 'p', modelID: 'm' }, parts: [] };
+    const base = { scope: { sessionID: 's', directory: '/d' }, messageID: 'm', parts: [] };
     await expect(adapter.send(base)).resolves.toMatchObject({ ok: true, status: 204 });
     await expect(adapter.send(base)).resolves.toMatchObject({ ok: true, status: 202 });
     await expect(adapter.send(base)).resolves.toMatchObject({ ok: true, status: 200 });
     await expect(adapter.send(base)).resolves.toMatchObject({ ok: false, kind: 'ambiguous', code: 'malformed_result' });
     await expect(adapter.send(base)).resolves.toMatchObject({ ok: false, kind: 'ambiguous', code: 'malformed_result' });
     await expect(adapter.send(base)).resolves.toMatchObject({ ok: false, kind: 'ambiguous', code: 'malformed_result' });
+    vi.unstubAllGlobals();
   });
   it('reads failure status from error.status and classifies definitive 4xx failures', async () => {
-    const promptAsync = vi.fn()
-      .mockReturnValueOnce({ error: { status: 400 }, response: undefined })
-      .mockReturnValueOnce({ error: {}, response: { status: 422 } })
-      .mockReturnValueOnce({ error: { status: 429 } })
-      .mockReturnValueOnce({ error: { status: 408 } });
-    createOpencodeClient.mockReturnValue({ session: { promptAsync, messages: vi.fn(() => ({ data: [] })) } });
+    const fetchMock = vi.fn()
+      .mockResolvedValueOnce({ ok: false, status: 400, json: async () => ({}) })
+      .mockResolvedValueOnce({ ok: false, status: 422, json: async () => ({}) })
+      .mockResolvedValueOnce({ ok: false, status: 429, json: async () => ({}) })
+      .mockResolvedValueOnce({ ok: false, status: 408, json: async () => ({}) })
+      .mockResolvedValueOnce({ ok: false, status: 409, json: async () => ({ _tag: 'SessionBusyError' }) });
+    vi.stubGlobal('fetch', fetchMock);
     const adapter = createOpenCodeMessageQueueAdapter({ buildOpenCodeUrl: () => 'http://open.code/', getOpenCodeAuthHeaders: () => ({}), readAttachment: () => null });
-    const base = { scope: { sessionID: 's', directory: '/d' }, messageID: 'm', sendConfig: { providerID: 'p', modelID: 'm' }, parts: [] };
+    const base = { scope: { sessionID: 's', directory: '/d' }, messageID: 'm', parts: [] };
     await expect(adapter.send(base)).resolves.toMatchObject({ ok: false, kind: 'failed', status: 400 });
     await expect(adapter.send(base)).resolves.toMatchObject({ ok: false, kind: 'failed', status: 422 });
     await expect(adapter.send(base)).resolves.toMatchObject({ ok: false, kind: 'ambiguous', status: 429 });
     await expect(adapter.send(base)).resolves.toMatchObject({ ok: false, kind: 'ambiguous', status: 408 });
+    await expect(adapter.send(base)).resolves.toMatchObject({ ok: false, kind: 'retry', code: 'session_busy' });
+    vi.unstubAllGlobals();
   });
   it('prefers client.v2.session.message exact lookup and treats 404 as found:false', async () => {
-    const exact = vi.fn()
-      .mockReturnValueOnce({ data: { info: { id: 'wanted' } } })
-      .mockReturnValueOnce({ error: { status: 404 }, response: { status: 404 } });
-    const messages = vi.fn(() => ({ data: [{ id: 'other' }] }));
-    createOpencodeClient.mockReturnValue({ v2: { session: { message: exact } }, session: { messages, promptAsync: vi.fn() } });
+    const api = v2Client({
+      inbox: [],
+      message: { wanted: { id: 'wanted', type: 'user' } },
+    });
+    makeOpenCodeV2Client.mockReturnValue(api);
     const adapter = createOpenCodeMessageQueueAdapter({ buildOpenCodeUrl: () => 'http://open.code/', getOpenCodeAuthHeaders: () => ({}), readAttachment: () => null });
     await expect(adapter.findMessage({ sessionID: 's', directory: '/d' }, 'wanted')).resolves.toEqual({ found: true });
     await expect(adapter.findMessage({ sessionID: 's', directory: '/d' }, 'missing')).resolves.toEqual({ found: false });
-    expect(messages).not.toHaveBeenCalled();
-    expect(exact).toHaveBeenCalledWith({ sessionID: 's', messageID: 'wanted', directory: '/d' }, expect.any(Object));
-  });
-  it('falls back from unsupported exact lookup to legacy session.message then bounded messages', async () => {
-    const legacyMessage = vi.fn()
-      .mockReturnValueOnce({ data: { info: { id: 'legacy-hit' } } })
-      .mockReturnValueOnce({ error: { status: 404 }, response: { status: 404 } });
-    const messages = vi.fn(() => ({ data: [{ id: 'bounded-hit' }] }));
-    createOpencodeClient
-      .mockReturnValueOnce({ session: { message: legacyMessage, messages, promptAsync: vi.fn() } })
-      .mockReturnValueOnce({ session: { message: legacyMessage, messages, promptAsync: vi.fn() } })
-      .mockReturnValueOnce({ session: { messages, promptAsync: vi.fn() } });
+    expect(api.session.inbox.list).toHaveBeenCalled();
+    expect(api.session.message).toHaveBeenCalledWith({ sessionID: 's', messageID: 'wanted' }, expect.any(Object));
+  });
+  it('reconciles inbox then session.message without session.messages or 1.x fallback', async () => {
+    const api = v2Client({
+      inbox: [{ id: 'legacy-hit' }],
+      message: { 'bounded-hit': { id: 'bounded-hit', type: 'user' } },
+    });
+    makeOpenCodeV2Client.mockReturnValue(api);
     const adapter = createOpenCodeMessageQueueAdapter({ buildOpenCodeUrl: () => 'http://open.code/', getOpenCodeAuthHeaders: () => ({}), readAttachment: () => null });
     await expect(adapter.findMessage({ sessionID: 's', directory: '/d' }, 'legacy-hit')).resolves.toEqual({ found: true });
     await expect(adapter.findMessage({ sessionID: 's', directory: '/d' }, 'missing')).resolves.toEqual({ found: false });
     await expect(adapter.findMessage({ sessionID: 's', directory: '/d' }, 'bounded-hit')).resolves.toEqual({ found: true });
-    expect(messages).toHaveBeenCalledTimes(1);
+    expect(api.session.status).toBeUndefined();
+    expect(api.session.messages).toBeUndefined();
+    expect(api.session.promptAsync).toBeUndefined();
   });
-  it('falls back when v2 exact lookup returns 405/501 unsupported', async () => {
-    const exact = vi.fn().mockReturnValueOnce({ error: { status: 405 }, response: { status: 405 } });
-    const messages = vi.fn(() => ({ data: [{ info: { id: 'wanted' } }] }));
-    createOpencodeClient.mockReturnValue({ v2: { session: { message: exact } }, session: { messages, promptAsync: vi.fn() } });
+  it('marks non-404 inbox/message failures unavailable instead of falling back', async () => {
+    const api = v2Client();
+    api.session.inbox.list.mockRejectedValue(Object.assign(new Error('unsupported'), { status: 405 }));
+    makeOpenCodeV2Client.mockReturnValue(api);
     const adapter = createOpenCodeMessageQueueAdapter({ buildOpenCodeUrl: () => 'http://open.code/', getOpenCodeAuthHeaders: () => ({}), readAttachment: () => null });
-    await expect(adapter.findMessage({ sessionID: 's', directory: '/d' }, 'wanted')).resolves.toEqual({ found: true });
-    expect(messages).toHaveBeenCalledTimes(1);
+    await expect(adapter.findMessage({ sessionID: 's', directory: '/d' }, 'wanted')).resolves.toEqual({ unavailable: true });
   });
-  it('uses absent session status as idle and derives settlement from the message tail', async () => {
-    const messages = vi.fn(() => ({ data: [] })); createOpencodeClient.mockReturnValue({ session: { messages, status: vi.fn(() => ({ data: {} })) } });
+  it('uses absent session.active membership as idle and derives settlement from type and time.completed', async () => {
+    const list = vi.fn(async () => ({ data: [] }));
+    const active = vi.fn(async () => ({}));
+    makeOpenCodeV2Client.mockReturnValue({ session: { active, inbox: { list: vi.fn() }, message: vi.fn() }, message: { list } });
     const adapter = createOpenCodeMessageQueueAdapter({ buildOpenCodeUrl: () => 'http://open.code/', getOpenCodeAuthHeaders: () => ({}), readAttachment: () => null });
     expect(await adapter.checkEligibility({ sessionID: 's', directory: '/d' })).toMatchObject({ idle: true, settled: true });
-    messages.mockReturnValueOnce({ data: [{ info: { id: 'user', role: 'user' } }] }); expect((await adapter.checkEligibility({ sessionID: 's', directory: '/d' })).settled).toBe(false);
-    messages.mockReturnValueOnce({ data: [{ info: { id: 'assistant', role: 'assistant', time: { completed: 1 } } }] }); expect((await adapter.checkEligibility({ sessionID: 's', directory: '/d' })).settled).toBe(true);
+    list.mockResolvedValueOnce({ data: [{ id: 'user', type: 'user', time: { created: 1 } }] });
+    expect((await adapter.checkEligibility({ sessionID: 's', directory: '/d' })).settled).toBe(false);
+    list.mockResolvedValueOnce({ data: [{ id: 'assistant', type: 'assistant', time: { completed: 1 } }] });
+    expect((await adapter.checkEligibility({ sessionID: 's', directory: '/d' })).settled).toBe(true);
+    expect(list).toHaveBeenCalledWith({ sessionID: 's', limit: 1, order: 'desc' }, expect.any(Object));
+  });
+  it('treats a sessionID present in session.active as not idle', async () => {
+    makeOpenCodeV2Client.mockReturnValue(v2Client({
+      active: { s: { type: 'running' } },
+      list: { data: [{ id: 'assistant', type: 'assistant', time: { completed: 1 } }] },
+    }));
+    const adapter = createOpenCodeMessageQueueAdapter({ buildOpenCodeUrl: () => 'http://open.code/', getOpenCodeAuthHeaders: () => ({}), readAttachment: () => null });
+    expect(await adapter.checkEligibility({ sessionID: 's', directory: '/d' })).toMatchObject({ available: true, idle: false });
   });
   it('recovers an idle incomplete assistant tail without treating fetch failure as empty', async () => {
     let now = 0; const turnGate = createSessionTurnGate({ clock: () => now });
-    const messages = vi.fn(() => ({ data: [{ info: { id: 'assistant', role: 'assistant', time: { created: 1 } } }] }));
-    const status = vi.fn(() => ({ data: {} })); createOpencodeClient.mockReturnValue({ session: { messages, status } });
+    const list = vi.fn(async () => ({ data: [{ id: 'assistant', type: 'assistant', time: { created: 1 } }] }));
+    const active = vi.fn(async () => ({}));
+    makeOpenCodeV2Client.mockReturnValue({ session: { active, inbox: { list: vi.fn() }, message: vi.fn() }, message: { list } });
     const adapter = createOpenCodeMessageQueueAdapter({ buildOpenCodeUrl: () => 'http://open.code/', getOpenCodeAuthHeaders: () => ({}), readAttachment: () => null, turnGate });
     expect(await adapter.checkEligibility({ sessionID: 's', directory: '/d' })).toMatchObject({ settled: false, settlementReason: 'tail_unsettled' });
-    status.mockReturnValueOnce({ error: {} }); now = 3_000;
+    active.mockRejectedValueOnce(Object.assign(new Error('upstream'), { status: 500 })); now = 3_000;
     await expect(adapter.checkEligibility({ sessionID: 's', directory: '/d' })).resolves.toEqual({ available: false, idle: false, settled: false });
     expect(await adapter.checkEligibility({ sessionID: 's', directory: '/d' })).toMatchObject({ settled: false, settlementReason: 'tail_unsettled' });
     now = 6_000;
     expect(await adapter.checkEligibility({ sessionID: 's', directory: '/d' })).toMatchObject({ settled: true, settlementReason: 'stopped_assistant' });
   });
   it('marks malformed or failed authoritative eligibility reads unavailable', async () => {
-    createOpencodeClient.mockReturnValue({ session: { messages: vi.fn(() => ({ data: [] })), status: vi.fn(() => ({ error: {} })) } });
+    makeOpenCodeV2Client.mockReturnValue({
+      session: { active: vi.fn(async () => { throw Object.assign(new Error('upstream'), { status: 500 }); }), inbox: { list: vi.fn() }, message: vi.fn() },
+      message: { list: vi.fn(async () => ({ data: [] })) },
+    });
     const adapter = createOpenCodeMessageQueueAdapter({ buildOpenCodeUrl: () => 'http://open.code/', getOpenCodeAuthHeaders: () => ({}), readAttachment: () => null });
     await expect(adapter.checkEligibility({ sessionID: 's', directory: '/d' })).resolves.toEqual({ available: false, idle: false, settled: false });
   });
 });
+
+describe('sendConfig serial boundary (v2 prompt contract)', () => {
+  it('applies different models in agent→model→prompt order per item', async () => {
+    const calls = [];
+    const fetchMock = vi.fn(async (url, init) => {
+      calls.push({ url: String(url), body: init?.body ? JSON.parse(init.body) : null });
+      return { ok: true, status: 204, json: async () => ({}) };
+    });
+    vi.stubGlobal('fetch', fetchMock);
+    const adapter = createOpenCodeMessageQueueAdapter({
+      buildOpenCodeUrl: () => 'http://open.code/',
+      getOpenCodeAuthHeaders: () => ({}),
+      readAttachment: () => null,
+    });
+    const scope = { sessionID: 's', directory: '/d' };
+    await adapter.send({
+      scope, messageID: 'msg_a', parts: [{ type: 'text', text: 'first' }],
+      sendConfig: { providerID: 'openai', modelID: 'gpt-a', agent: 'build', variant: 'fast' },
+    });
+    await adapter.send({
+      scope, messageID: 'msg_b', parts: [{ type: 'text', text: 'second' }],
+      sendConfig: { providerID: 'anthropic', modelID: 'claude-b', agent: 'plan' },
+    });
+    expect(calls.map((c) => c.url.replace(/^.*\/api\/session\/s\//, ''))).toEqual([
+      'agent?directory=%2Fd',
+      'model?directory=%2Fd',
+      'prompt?directory=%2Fd',
+      'agent?directory=%2Fd',
+      'model?directory=%2Fd',
+      'prompt?directory=%2Fd',
+    ]);
+    expect(calls[0].body).toEqual({ agent: 'build' });
+    expect(calls[1].body).toEqual({ model: { id: 'gpt-a', providerID: 'openai', variant: 'fast' } });
+    expect(calls[2].body).toEqual(expect.objectContaining({ id: 'msg_a', text: 'first', delivery: 'steer' }));
+    expect(calls[2].body.model).toBeUndefined();
+    expect(calls[3].body).toEqual({ agent: 'plan' });
+    expect(calls[4].body).toEqual({ model: { id: 'claude-b', providerID: 'anthropic' } });
+    expect(calls[5].body).toEqual(expect.objectContaining({ id: 'msg_b', text: 'second' }));
+    vi.unstubAllGlobals();
+  });
+
+  it('does not POST prompt when model switch fails', async () => {
+    const fetchMock = vi.fn(async (url) => {
+      if (String(url).includes('/model')) return { ok: false, status: 400, json: async () => ({ _tag: 'InvalidRequestError' }) };
+      return { ok: true, status: 204, json: async () => ({}) };
+    });
+    vi.stubGlobal('fetch', fetchMock);
+    const adapter = createOpenCodeMessageQueueAdapter({
+      buildOpenCodeUrl: () => 'http://open.code/',
+      getOpenCodeAuthHeaders: () => ({}),
+      readAttachment: () => null,
+    });
+    const result = await adapter.send({
+      scope: { sessionID: 's', directory: '/d' },
+      messageID: 'msg_fail',
+      parts: [{ type: 'text', text: 'nope' }],
+      sendConfig: { providerID: 'p', modelID: 'm', agent: 'a' },
+    });
+    expect(result).toMatchObject({ ok: false, kind: 'failed', code: 'config_switch_failed', status: 400 });
+    expect(fetchMock.mock.calls.some(([url]) => String(url).includes('/prompt'))).toBe(false);
+    expect(fetchMock.mock.calls.some(([url]) => String(url).includes('/agent'))).toBe(true);
+    expect(fetchMock.mock.calls.some(([url]) => String(url).includes('/model'))).toBe(true);
+    vi.unstubAllGlobals();
+  });
+
+  it('treats session busy on switch as retry without prompt', async () => {
+    const fetchMock = vi.fn(async (url) => {
+      if (String(url).includes('/agent')) return { ok: false, status: 409, json: async () => ({ _tag: 'SessionBusyError' }) };
+      return { ok: true, status: 200, json: async () => ({}) };
+    });
+    vi.stubGlobal('fetch', fetchMock);
+    const adapter = createOpenCodeMessageQueueAdapter({
+      buildOpenCodeUrl: () => 'http://open.code/',
+      getOpenCodeAuthHeaders: () => ({}),
+      readAttachment: () => null,
+    });
+    const result = await adapter.send({
+      scope: { sessionID: 's', directory: '/d' },
+      messageID: 'msg_busy',
+      parts: [{ type: 'text', text: 'wait' }],
+      sendConfig: { providerID: 'p', modelID: 'm', agent: 'a' },
+    });
+    expect(result).toMatchObject({ ok: false, kind: 'retry', code: 'session_busy' });
+    expect(fetchMock.mock.calls.some(([url]) => String(url).includes('/prompt'))).toBe(false);
+    vi.unstubAllGlobals();
+  });
+
+  it('maps MessageNotFoundError _tag from projection to found:false', async () => {
+    const api = v2Client({ inbox: [] });
+    api.session.message.mockRejectedValue({
+      _tag: 'MessageNotFoundError',
+      sessionID: 's',
+      messageID: 'missing',
+      message: 'not found',
+    });
+    makeOpenCodeV2Client.mockReturnValue(api);
+    const adapter = createOpenCodeMessageQueueAdapter({
+      buildOpenCodeUrl: () => 'http://open.code/',
+      getOpenCodeAuthHeaders: () => ({}),
+      readAttachment: () => null,
+    });
+    await expect(adapter.findMessage({ sessionID: 's', directory: '/d' }, 'missing')).resolves.toEqual({ found: false });
+  });
+
+  it('awaits projection rejections so non-404 stays unavailable instead of escaping', async () => {
+    const api = v2Client({ inbox: [] });
+    api.session.message.mockRejectedValue(Object.assign(new Error('boom'), { status: 500 }));
+    makeOpenCodeV2Client.mockReturnValue(api);
+    const adapter = createOpenCodeMessageQueueAdapter({
+      buildOpenCodeUrl: () => 'http://open.code/',
+      getOpenCodeAuthHeaders: () => ({}),
+      readAttachment: () => null,
+    });
+    await expect(adapter.findMessage({ sessionID: 's', directory: '/d' }, 'wanted')).resolves.toEqual({ unavailable: true });
+  });
+});
+
+describe('intent queue prompt/inbox authority (ticket 12)', () => {
+  const jsonResponse = (status, body) => ({
+    ok: status >= 200 && status < 300,
+    status,
+    json: async () => body,
+    text: async () => JSON.stringify(body),
+    headers: { get: () => 'application/json' },
+  });
+
+  it('sends via v2 prompt/inbox and does not treat local parts as the body of record', async () => {
+    const fetchMock = vi.fn(async () => jsonResponse(200, {
+      id: 'msg_inbox',
+      sessionID: 's',
+      delivery: 'steer',
+      payload: { text: 'from-projection' },
+    }));
+    vi.stubGlobal('fetch', fetchMock);
+    const adapter = createOpenCodeMessageQueueAdapter({
+      buildOpenCodeUrl: (pathname) => `http://open.code${pathname}`,
+      getOpenCodeAuthHeaders: () => ({ Authorization: 'Basic secret' }),
+      readAttachment: () => ({ type: 'file', url: 'file:///staged' }),
+    });
+    const localParts = [{ type: 'text', text: 'stale-local-parts' }];
+    const result = await adapter.send({
+      scope: { sessionID: 's', directory: '/d' },
+      messageID: 'msg_inbox',
+      sendConfig: { providerID: 'p', modelID: 'm' },
+      parts: localParts,
+      content: 'stale-local-parts',
+    });
+    expect(result).toMatchObject({ ok: true, status: 200 });
+    const promptCall = fetchMock.mock.calls.find(([url]) => String(url).includes('/prompt'));
+    expect(promptCall).toBeTruthy();
+    const [url, init] = promptCall;
+    expect(String(url)).toContain('/api/session/s/prompt');
+    const body = JSON.parse(init.body);
+    expect(body.delivery).toMatch(/steer|queue/);
+    expect(body.id).toBe('msg_inbox');
+    expect(body.model).toBeUndefined();
+    expect(init.method).toBe('POST');
+    vi.unstubAllGlobals();
+  });
+
+  it('reconciles only against OpenCode inbox and projection, never a local parts scan', async () => {
+    const list = vi.fn(async () => ({ data: [{ id: 'wanted', type: 'user', text: 'local-scan' }] }));
+    const api = v2Client({
+      inbox: [{ id: 'wanted', sessionID: 's', delivery: 'steer', payload: { text: 'inbox' } }],
+      message: { wanted: { id: 'wanted', type: 'user' } },
+    });
+    api.message.list = list;
+    makeOpenCodeV2Client.mockReturnValue(api);
+    const adapter = createOpenCodeMessageQueueAdapter({
+      buildOpenCodeUrl: (pathname) => `http://open.code${pathname}`,
+      getOpenCodeAuthHeaders: () => ({}),
+      readAttachment: () => null,
+    });
+    await expect(adapter.findMessage({ sessionID: 's', directory: '/d' }, 'wanted')).resolves.toEqual({ found: true });
+    expect(list).not.toHaveBeenCalled();
+    expect(api.session.inbox.list).toHaveBeenCalledWith({ sessionID: 's' }, expect.any(Object));
+  });
+
+  it('keeps staged attachment files until prompt is accepted, then projection wins', async () => {
+    const fetchMock = vi.fn(async () => jsonResponse(200, {
+      id: 'msg_att',
+      sessionID: 's',
+      delivery: 'steer',
+      payload: { text: 'accepted' },
+    }));
+    vi.stubGlobal('fetch', fetchMock);
+    const readAttachment = vi.fn(() => ({ type: 'file', url: 'file:///staged-disk', filename: 'note.txt' }));
+    const adapter = createOpenCodeMessageQueueAdapter({
+      buildOpenCodeUrl: (pathname) => `http://open.code${pathname}`,
+      getOpenCodeAuthHeaders: () => ({}),
+      readAttachment,
+    });
+    const parts = await adapter.materializeAttachments({
+      content: 'caption',
+      attachments: [{ attachmentID: 'att-1', filename: 'note.txt' }],
+    });
+    expect(parts).toEqual([
+      { type: 'text', text: 'caption' },
+      { type: 'file', url: 'file:///staged-disk', filename: 'note.txt' },
+    ]);
+    const result = await adapter.send({
+      scope: { sessionID: 's', directory: '/d' },
+      messageID: 'msg_att',
+      sendConfig: { providerID: 'p', modelID: 'm' },
+      parts,
+    });
+    expect(result.ok).toBe(true);
+    expect(readAttachment).toHaveBeenCalled();
+    const promptCall = fetchMock.mock.calls.find(([url]) => String(url).includes('/prompt'));
+    const body = JSON.parse(promptCall[1].body);
+    expect(body.files?.length || body.parts).toBeTruthy();
+    expect(body.model).toBeUndefined();
+    vi.unstubAllGlobals();
+  });
+});

package/server/lib/message-queue/runtime.test.js

@@ -4,24 +4,24 @@ import os from 'node:os';
 import path from 'node:path';
 import { describe, expect, it, vi } from 'vitest';
 
-vi.mock('@opencode-ai/sdk/v2', () => ({ createOpencodeClient: vi.fn() }));
-const { createOpencodeClient } = await import('@opencode-ai/sdk/v2');
+vi.mock('../opencode/v2-client.js', () => ({ makeOpenCodeV2Client: vi.fn() }));
+const { makeOpenCodeV2Client } = await import('../opencode/v2-client.js');
 import { createMessageQueueRuntime } from './runtime.js';
 
 describe('message queue runtime ownership', () => {
   it('keeps the durable queue identity separate from the upstream OpenCode adapter URL', async () => {
     const root = fs.mkdtempSync(path.join(os.tmpdir(), 'message-queue-runtime-'));
     const uiUrl = 'http://127.0.0.1:57123'; const upstreamUrl = 'http://127.0.0.1:4096/';
-    const status = vi.fn(() => ({ data: {} })); const messages = vi.fn(() => ({ data: [] }));
-    createOpencodeClient.mockReturnValue({ session: { status, messages, promptAsync: vi.fn() } });
+    const active = vi.fn(() => ({})); const list = vi.fn(() => ({ data: [] }));
+    makeOpenCodeV2Client.mockReturnValue({ session: { active, prompt: vi.fn() }, message: { list } });
     const runtime = createMessageQueueRuntime({ dbPath: path.join(root, 'queue.sqlite'), getRuntimeConfig: () => ({ apiBaseUrl: uiUrl }), getOpenCodeRuntimeConfig: () => ({ apiBaseUrl: upstreamUrl }), buildOpenCodeUrl: () => upstreamUrl, getOpenCodeAuthHeaders: () => ({}) });
     try {
       const adapterRuntime = runtime.adapter.captureRuntime();
       await runtime.adapter.checkEligibility({ directory: '/repo', sessionID: 'session' }, adapterRuntime);
       expect(runtime.service.getRuntimeKey()).toBe(crypto.createHash('sha256').update(`url:${uiUrl}`).digest('hex'));
       expect(adapterRuntime.config.apiBaseUrl).toBe(upstreamUrl);
-      expect(createOpencodeClient).toHaveBeenCalledWith(expect.objectContaining({ baseUrl: 'http://127.0.0.1:4096' }));
-      expect(createOpencodeClient.mock.calls.map(([options]) => options.baseUrl)).not.toContain(uiUrl);
+      expect(makeOpenCodeV2Client).toHaveBeenCalledWith(expect.objectContaining({ baseUrl: 'http://127.0.0.1:4096' }));
+      expect(makeOpenCodeV2Client.mock.calls.map(([options]) => options.baseUrl)).not.toContain(uiUrl);
     } finally {
       await runtime.stop(); fs.rmSync(root, { recursive: true, force: true });
     }

package/server/lib/message-queue/worker.js

@@ -109,7 +109,13 @@ export const createMessageQueueWorker = ({ service, adapter, workerID, concurren
   };
   const run = async () => {
     if (paused || stopping) return status();
-    const runtimeKey = service.getRuntimeKey(); const runtime = adapter.captureRuntime(); const authority = service.getAuthority({ runtimeKey });
+    const runtimeKey = service.getRuntimeKey();
+    // The managed OpenCode service may still be booting when the worker starts;
+    // captureRuntime throws until its port is detected. Leave queued work
+    // pending and retry on the next tick instead of failing the flight.
+    let runtime;
+    try { runtime = adapter.captureRuntime(); } catch { return status(); }
+    const authority = service.getAuthority({ runtimeKey });
     if (authority?.authority !== 'active') return status();
     service.recoverExpiredSending?.({ runtimeKey });
     // Start dispatch probes before awaiting reconciling work so a hung findMessage

package/server/lib/opencode/DOCUMENTATION.md

@@ -11,8 +11,10 @@ This module provides OpenCode server integration utilities for the web server ru
 - `packages/web/server/lib/opencode/cli-entry-runtime.js`: CLI entrypoint runtime that detects direct execution, forces `OPENCHAMBER_RUNTIME=web` unless already `ssh-remote` (so `dev:server` cannot inherit a leftover desktop env and host a relay, while SSH-managed remotes may), parses CLI options, and starts server bootstrap.
 - `packages/web/server/lib/opencode/routes.js`: OpenCode/provider settings and auth-related route registration.
 - `packages/web/server/lib/opencode/lifecycle.js`: OpenCode process lifecycle runtime (startup, restart, readiness, health monitoring). Managed child env inherits the user shell environment unchanged; experimental flags such as `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS` follow the user's own environment and are never injected by OpenChamber.
+- `packages/web/server/lib/opencode/v1-migration-gate.js`: pure V1→v2 migration admission gate (`GET /api/experimental/migration/v1` → whether transcript may be fetched).
 - `packages/web/server/lib/opencode/managed-capabilities-runtime.js`: managed-child scheduled-task resources, config injection, rotating bridge identity, and bridge authorization.
 - `packages/web/server/lib/opencode/env-runtime.js`: OpenCode CLI/binary resolution and shell environment runtime.
+- `packages/web/server/lib/opencode/ensure-cli.js`: detect local `opencode2` version and install the pinned official V2 into the OpenChamber data dir when missing or too old. Never uses a packaged/bundled binary.
 - `packages/web/server/lib/opencode/env-config.js`: OpenCode-related environment variable parsing and validation (host/port/hostname).
 - `packages/web/server/lib/opencode/hmr-state-runtime.js`: HMR-persistent runtime state initialization, auth-state bootstrap, and HMR sync helpers.
 - `packages/web/server/lib/opencode/bootstrap-runtime.js`: base app bootstrap runtime for status/auth/tts/notification/OpenChamber route wiring.
@@ -112,8 +114,27 @@ This module provides OpenCode server integration utilities for the web server ru
   membership — that remains a UI-side authoritative pull fused with directory
   `/session/status`.
 
+## Public exports (opencode2-pin.js)
+- `PINNED_OPENCODE2_VERSION`: exact desktop/runtime pin (never 1.x).
+- `OPENCODE2_NPM_PACKAGE`: `@opencode/cli` (global install that ships the `opencode2` binary; not 1.x `opencode-ai`).
+- `parseOpenCode2VersionOutput(stdout)` / `compareOpenCode2Versions(left, right)` / `isOpenCode2VersionAtLeast(version, minimum)`: CLI `--version` parse and pin comparison.
+- `openCode2BinaryName(platform)` / `npmPackageForOpenCode2(platform, arch)`: staged binary name `opencode2` and official platform package `@opencode/cli-<os>-<arch>[-baseline]`.
+- `isOpenCode1xVersion(value)` / `isAcceptableOpenCode2HealthVersion(value)` / `evaluateOpenCodeHealthBody(body)`: health admission rejects 1.x and missing/unknown versions even when `healthy: true`.
+- `resolveOpenCode2UpgradeTarget(target)` / `rejectOpenCode1xUpgradeTarget(target)`: upgrade targets default to the pin and refuse 1.x.
+
+## Public exports (ensure-cli.js)
+- `ensurePinnedOpenCode2Cli({ discoveredPath, pin, autoInstall, install, readVersion })`: reuse any discovered acceptable 2.x CLI (official name `opencode`, alias `opencode2`). Install the pin into `~/.config/openchamber/opencode-cli/<pin>/opencode` only when nothing usable is installed. `OPENCHAMBER_OPENCODE2_AUTO_INSTALL=0` disables download (`OPENCODE_CLI_MISSING`).
+- `installPinnedOpenCode2Cli(options)`: download `@opencode/cli-<os>-<arch>@pin`, extract, copy as `opencode`, chmod, verify `--version`.
+- `installedOpenCode2BinaryPath(version)` / `readOpenCode2BinaryVersion(path)` / `isOpenCode2AutoInstallEnabled()`.
+
+## Public exports (v1-migration-gate.js)
+- `OPENCODE_V1_MIGRATION_PATH`: `/api/experimental/migration/v1`.
+- `V1_MIGRATION_USER_NOTICE`: user-visible backfill notes (reuse message ids; in-progress tools become interrupted; V1 subtasks omitted from v2).
+- `evaluateV1MigrationGate(input)`: pure function. Accepts migration JSON (`{ status }`), an HTTP envelope (`{ httpStatus|status, body }`), or a transport failure (`{ error }`). Returns `{ admitTranscript, phase, progress?, error?, userNotice? }`. `required` / `running` / `error` / network failure → `admitTranscript: false`. `completed` or HTTP 404 (no V1 library) → `true`. Unknown or empty bodies fail closed and are never treated as an empty-list success.
+- `fetchV1MigrationGate({ url, headers, signal, fetchImpl })`: GET-only status poll used by lifecycle.
+
 ## Public exports (lifecycle.js)
-- `createOpenCodeLifecycleRuntime(dependencies)`: creates lifecycle runtime for managed/external OpenCode process orchestration.
+- `createOpenCodeLifecycleRuntime(dependencies)`: creates lifecycle runtime for managed/external OpenCode process orchestration. Bootstrap reuses a healthy v2 `opencode serve` when present; otherwise starts managed `opencode serve`. Before managed spawn, `ensurePinnedOpenCode2CliEnv()` detects the local CLI version and installs the pinned official V2 when missing or too old (skipped for external skip-start). Startup accepts both `server listening on http://127.0.0.1:PORT` and the legacy `opencode server listening on …` line. Readiness/health probes `GET /api/info` first, then `/global/health`, with Basic auth (username `opencode`). A body is admitted only when `evaluateOpenCodeHealthBody` accepts the version (rejects 1.x and missing/unknown). After health ok, `startOpenCode` / `waitForOpenCodeReady` poll `GET /api/experimental/migration/v1` (no POST; backfill is owned by opencode2). Each readiness attempt uses one abort timer that covers **both** health and migration so a hung migration cannot outrun the per-attempt budget. External instances are a read-only mount: restart/refresh only re-probe health + V1 migration (never kill, spawn, clear port, or flip `isExternalOpenCode`); health monitoring skips them; upgrade routes return 409. After readiness admits, lifecycle warms recent directories via optional `getWarmupDirectories` (sequential best-effort `GET /api/session?directory=&limit=1`). External skip-start / auto-detect attach leave `isOpenCodeReady` false until the gate admits. `isOpenCodeReady` means transcript may be fetched only when the gate admits (`completed`, or no V1 library such as HTTP 404). `required` / `running` / `error` keep the ready gate closed; `error` is retried. The last gate result is stored on `state.v1Migration` and published on the OpenChamber `/health` snapshot so UI can render `phase` and running `progress` (`label` / `numerator` / `denominator`) plus `userNotice` (reuse message ids; in-progress tools become interrupted; V1 subtasks do not appear in v2).
 - Returned API:
   - `startOpenCode()`
   - `restartOpenCode()`
@@ -127,11 +148,13 @@ This module provides OpenCode server integration utilities for the web server ru
   - `killProcessOnPort(port)`
 
 ## Public exports (env-runtime.js)
-- `createOpenCodeEnvRuntime(dependencies)`: creates runtime that owns OpenCode CLI environment and binary discovery state.
+- `createOpenCodeEnvRuntime(dependencies)`: creates runtime that owns OpenCode CLI environment and binary discovery state. Auto-discovery matches master: settings/env, then PATH `opencode` (official v2) with `opencode2` as alias, then known install locations, then a previously installed pin under the OpenChamber data dir. 1.x binaries are skipped by `--version`, not by basename. `resolveOpencodeCliPath()` never prefers a packaged/bundled Electron extraResource. Managed startup calls `ensurePinnedOpenCode2CliEnv()` and installs the pin only when no usable 2.x CLI exists; if pin install fails (or auto-install is disabled), it may last-resort to a 2.x binary under `OPENCHAMBER_BUNDLED_OPENCODE_CLI_DIR` or `process.resourcesPath/opencode-cli` (source `bundled`). Explicit `OPENCODE_BINARY` that reports 1.x fails closed with `OPENCODE_BINARY_INVALID`. Bootstrap reuses a healthy v2 `opencode serve` on port 4096 when present; otherwise it starts generic `opencode serve`.
+- VS Code keeps a copied sidecar (`packages/vscode/src/opencode-sidecar.ts`) with the same invariants: discovery order may differ (no Electron bundled fallback), but reject list, listening lines, health path order (`/api/health` then `/global/health`), `{ healthy: true }`, and Basic username `opencode` must stay aligned. Changing one copy requires changing the other.
 - Returned API:
   - `applyLoginShellEnvSnapshot()`
   - `getLoginShellEnvSnapshot()`
   - `ensureOpencodeCliEnv()`
+  - `ensurePinnedOpenCode2CliEnv()`
   - `applyOpencodeBinaryFromSettings()`
   - `resolveOpencodeCliPath()`
   - `resolveManagedOpenCodeLaunchSpec(opencodePath)`: resolves the effective managed OpenCode launch target, unwrapping Windows package-manager shims to a direct native binary or explicit runtime+script when possible.
@@ -175,7 +198,7 @@ This module provides OpenCode server integration utilities for the web server ru
 ## Public exports (network-runtime.js)
 - `createOpenCodeNetworkRuntime(dependencies)`: creates runtime for OpenCode network and URL concerns.
 - Returned API:
-  - `waitForReady(url, timeoutMs?)`
+  - `waitForReady(url, timeoutMs?)`: probes `GET /api/health` then `/global/health` with `getOpenCodeAuthHeaders()`; `{ healthy: true }` is ready.
   - `normalizeApiPrefix(prefix)`
   - `setDetectedOpenCodeApiPrefix()`
   - `buildOpenCodeUrl(path, prefixOverride?)`
@@ -382,9 +405,9 @@ When adding or changing Host HTTP APIs that mobile/desktop clients reach over Pr
   - SSE forwarders: `GET /api/global/event`, `GET /api/event` (optional `includeReasoning=false` parse-filters reasoning events on the Host send path; param never forwarded upstream; enabled path remains byte passthrough)
   - Official session.messages list: `GET /api/session/:sessionID/message` (optional `includeReasoning=false` strips reasoning parts; exact message GET is owned by session-turn-pages)
   - Session message forwarder: `POST /api/session/:sessionId/message`
-  - Generic `/api/*` forwarding with hop-by-hop header filtering
+  - Generic `/api/*` forwarding with hop-by-hop header filtering. v2 upstream routes live under `/api` (`@opencode-ai/protocol`); the proxy restores that prefix after Express strips the `/api` mount. Forwarding `/agent` (v1 root) hits the v2 Web UI HTML fallback.
   - Windows `/session` merge fallback path behavior
-  - OpenCode readiness gate for proxied `/api` requests
+  - OpenCode readiness gate for proxied `/api` requests: process warmup still uses `OPEN_CODE_READY_GRACE_MS`; `state.v1Migration.admitTranscript !== true` holds with no grace until the gate admits or the client cancels, so a `running` migration past 12s cannot `next()` an empty session list through as success
 
 ## Public exports (watcher.js)
 - `createOpenCodeWatcherRuntime(dependencies)`: creates global event watcher runtime backed by the shared upstream SSE reader.