@openchambery/web 1.19.11 → 1.19.13-beta.1

package/server/lib/assistants/assign.test.js

@@ -6,8 +6,16 @@ import {
   ASSIGN_CODES,
   PROJECT_REQUIRED_MESSAGE,
   assignSession,
+  attachmentScopeKey,
+  buildAssignParts,
+  hasAssignImageParts,
+  isAmbiguousPromptFailure,
   isManagedAssistantWorkspace,
+  requireProvidedString,
   resolveAssignDirectory,
+  resolveAssignWorkerModel,
+  resolveAssignWorkerVariant,
+  sanitizeAssignFileParts,
 } from './assign.js';
 
 const root = () => fs.mkdtempSync(path.join(os.tmpdir(), 'assign-'));
@@ -54,6 +62,157 @@ describe('resolveAssignDirectory', () => {
   });
 });
 
+describe('requireProvidedString / resolveAssignWorkerModel', () => {
+  const catalog = {
+    models: [
+      { providerID: 'openai', modelID: 'gpt-4o', name: 'GPT-4o', acceptsImages: true },
+      { providerID: 'xai', modelID: 'grok-4.6', name: 'Grok 4.6', acceptsImages: true },
+      { providerID: 'opencode-go', modelID: 'deepseek-v4-flash', name: 'deepseek-v4-flash', acceptsImages: false },
+      { providerID: 'other', modelID: 'deepseek-v4-flash', name: 'clone', acceptsImages: false },
+    ],
+  };
+
+  it('defaults to the assistant model without requiring catalog', () => {
+    expect(resolveAssignWorkerModel({
+      fallback: { providerID: 'p', modelID: 'm' },
+    })).toEqual({
+      providerID: 'p',
+      modelID: 'm',
+      source: 'assistant',
+      name: null,
+      acceptsImages: null,
+    });
+  });
+
+  it('resolves explicit provider/model against the connected catalog', () => {
+    expect(resolveAssignWorkerModel({
+      model: 'xai/grok-4.6',
+      fallback: { providerID: 'p', modelID: 'm' },
+      catalog,
+    })).toMatchObject({
+      providerID: 'xai',
+      modelID: 'grok-4.6',
+      source: 'explicit',
+      acceptsImages: true,
+    });
+  });
+
+  it('fails closed for missing or ambiguous model names', () => {
+    expect(() => resolveAssignWorkerModel({
+      model: 'missing-model',
+      fallback: { providerID: 'p', modelID: 'm' },
+      catalog,
+    })).toThrowError(expect.objectContaining({ code: ASSIGN_CODES.MODEL_NOT_FOUND }));
+    expect(() => resolveAssignWorkerModel({
+      modelID: 'deepseek-v4-flash',
+      fallback: { providerID: 'p', modelID: 'm' },
+      catalog,
+    })).toThrowError(expect.objectContaining({ code: ASSIGN_CODES.MODEL_AMBIGUOUS }));
+    expect(() => resolveAssignWorkerModel({
+      model: 'xai/grok-4.6',
+      fallback: { providerID: 'p', modelID: 'm' },
+      catalog: null,
+    })).toThrowError(expect.objectContaining({ code: ASSIGN_CODES.UPSTREAM }));
+  });
+
+  it('fails closed on illegal provided explicit model fields (no silent null fallback)', () => {
+    expect(() => requireProvidedString({ x: 1 }, { field: 'model', max: 512 })).toThrowError(
+      expect.objectContaining({ code: ASSIGN_CODES.VALIDATION }),
+    );
+    expect(() => requireProvidedString('x'.repeat(513), { field: 'model', max: 512 })).toThrowError(
+      expect.objectContaining({ code: ASSIGN_CODES.VALIDATION, message: expect.stringMatching(/exceeds 512/) }),
+    );
+    expect(() => requireProvidedString('   ', { field: 'modelID', max: 256 })).toThrowError(
+      expect.objectContaining({ code: ASSIGN_CODES.VALIDATION }),
+    );
+    expect(() => resolveAssignWorkerModel({
+      model: 'x'.repeat(513),
+      fallback: { providerID: 'p', modelID: 'm' },
+      catalog,
+    })).toThrowError(expect.objectContaining({ code: ASSIGN_CODES.VALIDATION }));
+    expect(() => resolveAssignWorkerModel({
+      model: { providerID: 'xai', modelID: 'grok-4.6' },
+      fallback: { providerID: 'p', modelID: 'm' },
+      catalog,
+    })).toThrowError(expect.objectContaining({ code: ASSIGN_CODES.VALIDATION }));
+    expect(() => resolveAssignWorkerModel({
+      providerID: 'xai',
+      modelID: 'grok-4.6',
+      model: 'openai/gpt-4o',
+      fallback: { providerID: 'p', modelID: 'm' },
+      catalog,
+    })).toThrowError(expect.objectContaining({
+      code: ASSIGN_CODES.VALIDATION,
+      message: expect.stringMatching(/conflicts/),
+    }));
+  });
+});
+
+describe('resolveAssignWorkerVariant', () => {
+  it('reuses assistant variant only for same/default model; drops it cross-model', () => {
+    expect(resolveAssignWorkerVariant({
+      source: 'assistant',
+      workerProviderID: 'p',
+      workerModelID: 'm',
+      assistant: { providerID: 'p', modelID: 'm', variant: 'fast' },
+    })).toBe('fast');
+    expect(resolveAssignWorkerVariant({
+      source: 'explicit',
+      workerProviderID: 'xai',
+      workerModelID: 'grok-4.6',
+      assistant: { providerID: 'p', modelID: 'm', variant: 'fast' },
+    })).toBeNull();
+    expect(resolveAssignWorkerVariant({
+      source: 'explicit',
+      workerProviderID: 'xai',
+      workerModelID: 'grok-4.6',
+      assistant: { providerID: 'p', modelID: 'm', variant: 'fast' },
+      variant: 'default',
+    })).toBe('default');
+    expect(() => resolveAssignWorkerVariant({
+      source: 'explicit',
+      workerProviderID: 'xai',
+      workerModelID: 'grok-4.6',
+      variant: 'x'.repeat(300),
+    })).toThrowError(expect.objectContaining({ code: ASSIGN_CODES.VALIDATION }));
+  });
+});
+
+describe('assign file parts', () => {
+  it('keeps attachment order and fingerprints content without exposing file data', () => {
+    const first = { type: 'file', mime: 'text/plain', filename: 'first.txt', url: 'data:text/plain;base64,Zmlyc3Q=' };
+    const second = { ...first, filename: 'second.txt', url: 'data:text/plain;base64,c2Vjb25k' };
+    const key = attachmentScopeKey([first, second]);
+    expect(key).toEqual(attachmentScopeKey([{ ...first }, { ...second }]));
+    expect(key).not.toEqual(attachmentScopeKey([second, first]));
+    expect(JSON.stringify(key)).not.toContain(first.url);
+    expect(JSON.stringify(key)).not.toContain(first.filename);
+  });
+  it('sanitizes file parts and builds prompt+file worker parts', () => {
+    const image = { type: 'file', mime: 'image/png', url: 'data:image/png;base64,aa', filename: 'shot.png' };
+    const bad = { type: 'file', mime: 'image/png' };
+    expect(sanitizeAssignFileParts([image, bad, { type: 'text', text: 'x' }])).toEqual([image]);
+    expect(hasAssignImageParts([image])).toBe(true);
+    expect(buildAssignParts({ prompt: 'Fix width', fileParts: [image] })).toEqual([
+      { type: 'text', text: 'Fix width' },
+      image,
+    ]);
+    expect(attachmentScopeKey([image])).toEqual([
+      expect.stringMatching(/^[a-f0-9]{64}$/),
+    ]);
+    expect(JSON.stringify(attachmentScopeKey([image]))).not.toContain('base64');
+  });
+});
+
+describe('isAmbiguousPromptFailure', () => {
+  it('treats transport/5xx/no-status as ambiguous and 4xx as definite', () => {
+    expect(isAmbiguousPromptFailure(Object.assign(new Error('fetch failed'), { name: 'TypeError' }), null)).toBe(true);
+    expect(isAmbiguousPromptFailure(null, { error: { status: 500 }, response: { status: 500 } })).toBe(true);
+    expect(isAmbiguousPromptFailure(null, { error: { status: 400 }, response: { status: 400 } })).toBe(false);
+    expect(isAmbiguousPromptFailure(null, { response: { status: 204 } })).toBe(false);
+  });
+});
+
 describe('assignSession', () => {
   it('creates a visible worker session and prompts it', async () => {
     const directory = root();
@@ -77,6 +236,7 @@ describe('assignSession', () => {
       title: 'Login',
       status: 'busy',
       reused: false,
+      model: { providerID: 'openai', modelID: 'gpt-5.2' },
     });
     expect(createSession).toHaveBeenCalledWith(expect.objectContaining({
       directory: fs.realpathSync(project),
@@ -96,11 +256,200 @@ describe('assignSession', () => {
     }));
   });
 
+  it('forwards current-turn images into promptAsync with an explicit vision model', async () => {
+    const directory = root();
+    fs.mkdirSync(directory, { recursive: true });
+    const image = { type: 'file', mime: 'image/png', url: 'data:image/png;base64,aa', filename: 'card.png' };
+    const createSession = vi.fn(async () => ({ data: { id: 'ses_img' } }));
+    const promptExisting = vi.fn(async () => ({ response: { status: 204 } }));
+    const assigned = await assignSession({
+      prompt: 'Fix mobile card width from this screenshot',
+      directory,
+      assistant: { id: 'asst_1', name: 'Ada', providerID: 'p', modelID: 'm', variant: 'fast' },
+      model: { providerID: 'xai', modelID: 'grok-4.6', acceptsImages: true },
+      fileParts: [image],
+      allowedRoots: [directory],
+      managedWorkspaceRoot: path.join(directory, 'assistant-workspaces'),
+      createSession,
+      promptExisting,
+    });
+    expect(assigned.model).toEqual({ providerID: 'xai', modelID: 'grok-4.6' });
+    expect(promptExisting).toHaveBeenCalledWith(expect.objectContaining({
+      model: { providerID: 'xai', modelID: 'grok-4.6' },
+      parts: [
+        { type: 'text', text: 'Fix mobile card width from this screenshot' },
+        image,
+      ],
+    }));
+    // Cross-model must not reuse contact-only variant.
+    expect(promptExisting.mock.calls[0][0].variant).toBeUndefined();
+  });
+
+  it('reuses assistant variant only when the worker model matches the contact', async () => {
+    const directory = root();
+    fs.mkdirSync(directory, { recursive: true });
+    const promptExisting = vi.fn(async () => ({ response: { status: 204 } }));
+    await assignSession({
+      prompt: 'Fix',
+      directory,
+      assistant: { providerID: 'p', modelID: 'm', variant: 'fast' },
+      allowedRoots: [directory],
+      managedWorkspaceRoot: path.join(directory, 'assistant-workspaces'),
+      createSession: async () => ({ data: { id: 'ses_var' } }),
+      promptExisting,
+    });
+    expect(promptExisting).toHaveBeenCalledWith(expect.objectContaining({ variant: 'fast' }));
+  });
+
+  it('rejects image attachments for non-vision worker models before create', async () => {
+    const directory = root();
+    fs.mkdirSync(directory, { recursive: true });
+    const createSession = vi.fn();
+    await expect(assignSession({
+      prompt: 'Look at this',
+      directory,
+      assistant: { providerID: 'p', modelID: 'm' },
+      model: { providerID: 'opencode-go', modelID: 'deepseek-v4-flash', acceptsImages: false },
+      fileParts: [{ type: 'file', mime: 'image/png', url: 'data:image/png;base64,aa', filename: 'x.png' }],
+      allowedRoots: [directory],
+      managedWorkspaceRoot: path.join(directory, 'assistant-workspaces'),
+      createSession,
+      promptExisting: vi.fn(),
+    })).rejects.toMatchObject({ code: ASSIGN_CODES.IMAGE_NOT_SUPPORTED });
+    expect(createSession).not.toHaveBeenCalled();
+  });
+
+  it('deletes a newly created worker on definite prompt failure (4xx)', async () => {
+    const directory = root();
+    fs.mkdirSync(directory, { recursive: true });
+    const createSession = vi.fn(async () => ({ data: { id: 'ses_orphan' } }));
+    const promptExisting = vi.fn(async () => ({ error: { status: 400 }, response: { status: 400 } }));
+    const deleteSession = vi.fn(async () => ({ data: true }));
+    await expect(assignSession({
+      prompt: 'Fix',
+      directory,
+      assistant: { providerID: 'p', modelID: 'm' },
+      allowedRoots: [directory],
+      managedWorkspaceRoot: path.join(directory, 'assistant-workspaces'),
+      createSession,
+      promptExisting,
+      deleteSession,
+    })).rejects.toMatchObject({ code: ASSIGN_CODES.UPSTREAM });
+    expect(deleteSession).toHaveBeenCalledWith({
+      sessionID: 'ses_orphan',
+      directory: fs.realpathSync(directory),
+    });
+  });
+
+  it('does not delete on ambiguous prompt network/5xx; marks prompt_ambiguous with sessionID', async () => {
+    const directory = root();
+    fs.mkdirSync(directory, { recursive: true });
+    const createSession = vi.fn(async () => ({ data: { id: 'ses_maybe' } }));
+    const promptExisting = vi.fn(async () => {
+      throw Object.assign(new Error('fetch failed'), { name: 'TypeError' });
+    });
+    const deleteSession = vi.fn(async () => ({ data: true }));
+    await expect(assignSession({
+      prompt: 'Fix',
+      directory,
+      messageID: 'msg_assign_fixed',
+      assistant: { providerID: 'p', modelID: 'm' },
+      allowedRoots: [directory],
+      managedWorkspaceRoot: path.join(directory, 'assistant-workspaces'),
+      createSession,
+      promptExisting,
+      deleteSession,
+    })).rejects.toMatchObject({
+      code: ASSIGN_CODES.PROMPT_AMBIGUOUS,
+      ambiguous: true,
+      sessionID: 'ses_maybe',
+      messageID: 'msg_assign_fixed',
+    });
+    expect(deleteSession).not.toHaveBeenCalled();
+  });
+
+  it('confirms ambiguous prompt via lookupMessage instead of deleting or recreating', async () => {
+    const directory = root();
+    fs.mkdirSync(directory, { recursive: true });
+    const promptExisting = vi.fn(async () => ({ error: { status: 503 }, response: { status: 503 } }));
+    const deleteSession = vi.fn();
+    const lookupMessage = vi.fn(async () => ({ found: true, id: 'msg_assign_ok' }));
+    const assigned = await assignSession({
+      prompt: 'Fix',
+      directory,
+      messageID: 'msg_assign_ok',
+      assistant: { providerID: 'p', modelID: 'm' },
+      allowedRoots: [directory],
+      managedWorkspaceRoot: path.join(directory, 'assistant-workspaces'),
+      createSession: async () => ({ data: { id: 'ses_confirmed' } }),
+      promptExisting,
+      deleteSession,
+      lookupMessage,
+    });
+    expect(assigned).toMatchObject({
+      sessionID: 'ses_confirmed',
+      messageID: 'msg_assign_ok',
+      promptStatus: 'confirmed',
+    });
+    expect(deleteSession).not.toHaveBeenCalled();
+    expect(lookupMessage).toHaveBeenCalledWith(expect.objectContaining({
+      sessionID: 'ses_confirmed',
+      messageID: 'msg_assign_ok',
+    }));
+  });
+
+  it.each([false, true])('confirms an ambiguous response for reused=%s through one admission path', async (reused) => {
+    const directory = root();
+    const deleteSession = vi.fn();
+    const createSession = vi.fn(async () => ({ data: { id: 'ses_common' } }));
+    const result = await assignSession({
+      prompt: 'Fix', directory, allowedRoots: [directory],
+      assistant: { providerID: 'p', modelID: 'm' },
+      ...(reused ? { sessionID: 'ses_common' } : {}),
+      createSession, deleteSession,
+      promptExisting: async () => ({ error: { status: 503 } }),
+      lookupMessage: async () => ({ found: true }),
+    });
+    expect(result).toMatchObject({ sessionID: 'ses_common', reused, promptStatus: 'confirmed' });
+    expect(createSession).toHaveBeenCalledTimes(reused ? 0 : 1);
+    expect(deleteSession).not.toHaveBeenCalled();
+  });
+
+  it.each([false, true])('cleans up only new workers after definite rejection, reused=%s', async (reused) => {
+    const directory = root();
+    const deleteSession = vi.fn();
+    await expect(assignSession({
+      prompt: 'Fix', directory, allowedRoots: [directory],
+      assistant: { providerID: 'p', modelID: 'm' },
+      ...(reused ? { sessionID: 'ses_common' } : {}),
+      createSession: async () => ({ data: { id: 'ses_common' } }),
+      deleteSession,
+      promptExisting: async () => ({ error: { status: 400 } }),
+    })).rejects.toMatchObject({ code: ASSIGN_CODES.UPSTREAM });
+    expect(deleteSession).toHaveBeenCalledTimes(reused ? 0 : 1);
+  });
+
+  it('bounds create/prompt with deadlines', async () => {
+    const directory = root();
+    fs.mkdirSync(directory, { recursive: true });
+    await expect(assignSession({
+      prompt: 'Fix',
+      directory,
+      assistant: { providerID: 'p', modelID: 'm' },
+      allowedRoots: [directory],
+      managedWorkspaceRoot: path.join(directory, 'assistant-workspaces'),
+      createTimeoutMs: 20,
+      createSession: async () => new Promise(() => {}),
+      promptExisting: vi.fn(),
+    })).rejects.toMatchObject({ code: ASSIGN_CODES.UPSTREAM, message: expect.stringMatching(/timed out/) });
+  });
+
   it('reuses an existing session without creating another', async () => {
     const directory = root();
     fs.mkdirSync(directory, { recursive: true });
     const createSession = vi.fn();
     const promptExisting = vi.fn(async () => ({ response: { status: 204 } }));
+    const deleteSession = vi.fn();
     const assigned = await assignSession({
       prompt: 'Continue login',
       sessionID: 'ses_existing',
@@ -110,9 +459,11 @@ describe('assignSession', () => {
       managedWorkspaceRoot: path.join(directory, 'assistant-workspaces'),
       createSession,
       promptExisting,
+      deleteSession,
     });
     expect(assigned).toMatchObject({ sessionID: 'ses_existing', reused: true, status: 'busy' });
     expect(createSession).not.toHaveBeenCalled();
+    expect(deleteSession).not.toHaveBeenCalled();
     expect(promptExisting).toHaveBeenCalledWith(expect.objectContaining({ sessionID: 'ses_existing' }));
   });
 });

package/server/lib/assistants/contact-active-turn.http.test.js

@@ -0,0 +1,134 @@
+/**
+ * Isolated acceptance for server-authoritative contact working without touching :3001.
+ * Exercises the same snapshot DTO shape HTTP clients pull after APP reload.
+ */
+import fs from 'node:fs';
+import http from 'node:http';
+import os from 'node:os';
+import path from 'node:path';
+import express from 'express';
+import { afterEach, describe, expect, it } from 'vitest';
+import { createAssistantsService } from './service.js';
+
+const root = () => fs.mkdtempSync(path.join(os.tmpdir(), 'contact-http-'));
+const closers = [];
+
+const listen = (app) => new Promise((resolve) => {
+  const server = http.createServer(app);
+  server.listen(0, '127.0.0.1', () => {
+    const { port } = server.address();
+    closers.push(() => new Promise((done) => server.close(() => done())));
+    resolve({ port, base: `http://127.0.0.1:${port}` });
+  });
+});
+
+const json = async (base, pathName, init = {}) => {
+  const response = await fetch(`${base}${pathName}`, {
+    ...init,
+    headers: { 'content-type': 'application/json', ...(init.headers || {}) },
+  });
+  const body = await response.json().catch(() => null);
+  return { status: response.status, body };
+};
+
+afterEach(async () => {
+  while (closers.length) {
+    await closers.pop()();
+  }
+});
+
+describe('contact active turn HTTP snapshot (isolated)', () => {
+  it('admission → running → settle is visible on snapshot GET; APP reload matches; missed-end idle poll converges', async () => {
+    const directory = root();
+    let release;
+    const blocked = new Promise((resolve) => { release = resolve; });
+    const service = createAssistantsService({
+      dbPath: path.join(directory, 'assistants.sqlite'),
+      dataDir: directory,
+      getAllowedRoots: () => [directory],
+      buildOpenCodeUrl: () => 'http://127.0.0.1:1',
+      getOpenCodeAuthHeaders: () => ({}),
+      clientFactory: () => ({
+        session: {
+          create: async () => ({ data: { id: 'ses_x' } }),
+          get: async () => ({ data: { id: 'ses_x' } }),
+          update: async () => ({ data: { id: 'ses_x' } }),
+          promptAsync: async () => ({ response: { status: 204 } }),
+          summarize: async () => ({ data: true }),
+          delete: async () => ({ data: true }),
+        },
+      }),
+      runContactTurn: async () => {
+        await blocked;
+        return { text: 'done', bubbles: ['done'] };
+      },
+      createChatCompletion: async () => ({ choices: [{ message: { content: 'x' } }] }),
+    });
+    closers.push(async () => service.close());
+    service.setEnabled({ enabled: true, expectedRevision: service.snapshot().revision });
+    const assistant = service.createAssistant({
+      name: 'HTTP Bot',
+      providerID: 'p',
+      modelID: 'm',
+      defaultPrompt: '',
+      mode: 'continuous',
+    });
+
+    const app = express();
+    app.use(express.json({ limit: '2mb' }));
+    app.get('/api/openchamber/assistants/snapshot', (_req, res) => res.json(service.snapshot()));
+    app.post('/api/openchamber/assistants/:id/messages', async (req, res) => {
+      try {
+        const body = await service.send(req.params.id, req.body);
+        res.status(202).json(body);
+      } catch (error) {
+        res.status(400).json({ error: error.code || 'error', message: error.message });
+      }
+    });
+    const { base } = await listen(app);
+
+    // Fresh client: idle
+    let snap = await json(base, '/api/openchamber/assistants/snapshot');
+    expect(snap.status).toBe(200);
+    expect(snap.body.assistants[0]).toMatchObject({
+      id: assistant.id,
+      working: false,
+      activeContactTurn: null,
+    });
+
+    const admitted = await json(base, `/api/openchamber/assistants/${encodeURIComponent(assistant.id)}/messages`, {
+      method: 'POST',
+      body: JSON.stringify({ messageID: 'http_turn_1', parts: [{ type: 'text', text: 'hi' }] }),
+    });
+    expect(admitted.status).toBe(202);
+    expect(admitted.body).toMatchObject({ admitted: true, messageID: 'http_turn_1', revision: expect.any(Number) });
+
+    // Live client observes working after admit
+    snap = await json(base, '/api/openchamber/assistants/snapshot');
+    expect(snap.body.assistants[0].working).toBe(true);
+    expect(snap.body.assistants[0].activeContactTurn).toMatchObject({
+      turnID: 'http_turn_1',
+      messageID: 'http_turn_1',
+      status: expect.stringMatching(/^(queued|running)$/),
+    });
+
+    // APP reload / new client: same authoritative snapshot
+    const reloaded = await json(base, '/api/openchamber/assistants/snapshot');
+    expect(reloaded.body.assistants[0].working).toBe(true);
+    expect(reloaded.body.assistants[0].activeContactTurn.turnID).toBe('http_turn_1');
+
+    // Missed contact-turn-end: poll until idle
+    release();
+    await service.whenContactTurnSettled('http_turn_1');
+    let idle = null;
+    for (let attempt = 0; attempt < 20; attempt += 1) {
+      idle = await json(base, '/api/openchamber/assistants/snapshot');
+      if (!idle.body.assistants[0].working) break;
+      await new Promise((r) => setTimeout(r, 25));
+    }
+    expect(idle.body.assistants[0]).toMatchObject({
+      working: false,
+      activeContactTurn: null,
+    });
+  });
+});

package/server/lib/assistants/contact-store.js

@@ -108,6 +108,32 @@ export function nextContactOrdinal(db, assistantID) {
   ).get(assistantID).next);
 }
 
+/** Load one contact row by message id (null when missing). */
+export function getContactMessage(db, messageID) {
+  if (typeof messageID !== 'string' || !messageID) return null;
+  const row = db.prepare('SELECT * FROM assistant_contact_message WHERE message_id=?').get(messageID);
+  if (!row) return null;
+  return hydrateMessage(db, row);
+}
+
+/** Stable fingerprint for idempotent contact admission replay. */
+export function contactPartsFingerprint(parts) {
+  const list = Array.isArray(parts) ? parts : [];
+  return json(list.map((part) => {
+    if (!part || typeof part !== 'object') return null;
+    if (part.type === 'text') return { type: 'text', text: typeof part.text === 'string' ? part.text : '' };
+    if (part.type === 'file') {
+      return {
+        type: 'file',
+        mime: typeof part.mime === 'string' ? part.mime : '',
+        url: typeof part.url === 'string' ? part.url : '',
+        ...(typeof part.filename === 'string' && part.filename ? { filename: part.filename } : {}),
+      };
+    }
+    return part;
+  }));
+}
+
 export function insertContactMessage(db, {
   messageID,
   assistantID,
@@ -338,6 +364,44 @@ export function trimContactHistoryForLlm(messages, {
  *   rows (queued turns) must not be injected into this turn; assistant rows written
  *   after that ordinal by a prior completed lane turn still enter the window.
  */
+/**
+ * In-process contact-turn activity (not SQLite). Process memory only: APP
+ * restart while the server keeps running can rehydrate from snapshot; a server
+ * process restart clears every active turn so the green dot cannot stick forever.
+ * Status ladder: admission → queued → running → settled (removed).
+ */
+export const CONTACT_ACTIVE_TURN_STATUSES = Object.freeze(['queued', 'running']);
+
+export function createActiveContactTurn({ turnID, messageID, status = 'queued', admittedAt }) {
+  if (typeof turnID !== 'string' || !turnID.trim()) return null;
+  if (typeof messageID !== 'string' || !messageID.trim()) return null;
+  if (!CONTACT_ACTIVE_TURN_STATUSES.includes(status)) return null;
+  const at = Number(admittedAt);
+  if (!Number.isFinite(at)) return null;
+  return {
+    turnID: turnID.trim(),
+    messageID: messageID.trim(),
+    status,
+    admittedAt: Math.trunc(at),
+  };
+}
+
+/** Earliest admitted active turn; running preferred when admittedAt ties. */
+export function projectActiveContactTurn(activeTurns) {
+  const list = Array.isArray(activeTurns)
+    ? activeTurns
+    : (activeTurns instanceof Map ? [...activeTurns.values()] : []);
+  const valid = list
+    .map((item) => createActiveContactTurn(item))
+    .filter(Boolean)
+    .sort((left, right) => {
+      if (left.admittedAt !== right.admittedAt) return left.admittedAt - right.admittedAt;
+      if (left.status === right.status) return left.turnID.localeCompare(right.turnID);
+      return left.status === 'running' ? -1 : 1;
+    });
+  return valid[0] ?? null;
+}
+
 export function contactHistoryForLlm(db, assistantID, { excludeMessageIDs = [], beforeOrdinal = null } = {}) {
   const afterOrdinal = getContactContextBoundary(db, assistantID);
   const exclude = new Set(

package/server/lib/assistants/contact-store.test.js

@@ -11,12 +11,14 @@ import {
   CONTACT_LLM_MAX_TURNS,
   clearContactMemory,
   contactHistoryForLlm,
+  createActiveContactTurn,
   deleteContactMessages,
   ensureContactSchema,
   getContactContextBoundary,
   insertContactMessage,
   listContactMessages,
   nextContactOrdinal,
+  projectActiveContactTurn,
   trimContactHistoryForLlm,
 } from './contact-store.js';
 
@@ -231,6 +233,16 @@ describe('contact LLM history trim', () => {
     reopened.close();
   });
 
+  it('projects the earliest active contact turn for snapshot recovery', () => {
+    expect(createActiveContactTurn({ turnID: '', messageID: 'm', status: 'queued', admittedAt: 1 })).toBeNull();
+    expect(createActiveContactTurn({ turnID: 't', messageID: 'm', status: 'settled', admittedAt: 1 })).toBeNull();
+    const queued = createActiveContactTurn({ turnID: 't1', messageID: 'm1', status: 'queued', admittedAt: 20 });
+    const running = createActiveContactTurn({ turnID: 't0', messageID: 'm0', status: 'running', admittedAt: 10 });
+    expect(projectActiveContactTurn([queued, running])).toEqual(running);
+    expect(projectActiveContactTurn(new Map([['t1', queued]]))).toEqual(queued);
+    expect(projectActiveContactTurn([])).toBeNull();
+  });
+
   it('keeps the previous boundary when clearContactMemory write fails inside a transaction', () => {
     const db = openDb();
     const assistantID = 'asst_fail';