@vantran-se/openchamber-web 1.23.0 → 1.24.3

package/server/lib/routing/store.test.js

@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'vitest';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { createRoutingStore, parseEffectiveConfig, resolveEffectiveConfig, toStoredConfig } from './store.js';
+import { BUILTIN_CATEGORIES } from './defaults.js';
+
+const tempDir = () => fs.mkdtemp(path.join(os.tmpdir(), 'routing-store-'));
+
+const sampleConfig = (patch = {}) => ({
+  enabled: true,
+  fallback: { model: { providerID: 'anthropic', modelID: 'claude-sonnet-5' }, variant: 'medium' },
+  minConfidence: 0.6,
+  safetyNet: { enabled: true, threshold: 0.6 },
+  categories: resolveEffectiveConfig(null).categories,
+  ...patch,
+});
+
+describe('routing store', () => {
+  it('resolves the defaults when nothing is stored', async () => {
+    const store = createRoutingStore({ dataDir: await tempDir() });
+    const config = await store.readConfig();
+    expect(config.enabled).toBe(false);
+    expect(config.fallback).toBeNull();
+    expect(config.categories.map((c) => c.id)).toEqual(BUILTIN_CATEGORIES.map((c) => c.id));
+    expect(config.categories.every((c) => c.builtin && c.enabled && c.model === null)).toBe(true);
+  });
+
+  it('stores only deviations from the built-ins and round-trips them', async () => {
+    const dir = await tempDir();
+    const store = createRoutingStore({ dataDir: dir });
+    const config = sampleConfig();
+    config.categories[0] = { ...config.categories[0], enabled: false };
+    config.categories[3] = { ...config.categories[3], model: { providerID: 'openai', modelID: 'gpt-6-astra' }, variant: 'high', agent: 'plan' };
+    config.categories.push({ id: 'my-refactors', builtin: false, enabled: true, name: 'My refactors', description: 'Refactors across modules.', model: null, variant: null, agent: null });
+    await store.writeConfig(config);
+
+    const stored = JSON.parse(await fs.readFile(path.join(dir, 'routing.json'), 'utf8'));
+    expect(stored.categories).toEqual({
+      trivial: { builtin: true, disabled: true },
+      hard: { builtin: true, model: { providerID: 'openai', modelID: 'gpt-6-astra' }, variant: 'high', agent: 'plan' },
+      'my-refactors': { builtin: false, name: 'My refactors', description: 'Refactors across modules.' },
+    });
+    expect(await store.readConfig()).toEqual(config);
+  });
+
+  it('records a removed built-in as deleted and keeps the others', async () => {
+    const config = sampleConfig();
+    config.categories = config.categories.filter((c) => c.id !== 'research');
+    const stored = toStoredConfig(config);
+    expect(stored.categories.research).toEqual({ builtin: true, deleted: true });
+    const resolved = resolveEffectiveConfig(stored);
+    expect(resolved.categories.map((c) => c.id)).toEqual(['trivial', 'implement', 'hard']);
+  });
+
+  it('applies later built-in text to an untouched category but keeps an edited one', () => {
+    const edited = resolveEffectiveConfig({ version: 1, categories: { hard: { builtin: true, description: 'My own hard.' } } });
+    expect(edited.categories.find((c) => c.id === 'hard').description).toBe('My own hard.');
+    expect(edited.categories.find((c) => c.id === 'trivial').description).toBe(BUILTIN_CATEGORIES[0].description);
+  });
+
+  it('rejects a malformed file instead of treating it as empty', async () => {
+    const dir = await tempDir();
+    await fs.writeFile(path.join(dir, 'routing.json'), '{"version":1,"categories":{"x":{"builtin":false}}}');
+    const store = createRoutingStore({ dataDir: dir });
+    await expect(store.readConfig()).rejects.toThrow(/Invalid routing.json/);
+  });
+
+  it('rejects an invalid PUT body with a 400 status', () => {
+    expect(() => parseEffectiveConfig({ enabled: true })).toThrow(expect.objectContaining({ status: 400 }));
+    const duplicate = sampleConfig();
+    duplicate.categories = [...duplicate.categories, { ...duplicate.categories[0], builtin: false }];
+    expect(() => parseEffectiveConfig(duplicate)).toThrow(/Duplicate category id/);
+  });
+
+  it('refuses the Auto sentinel as a fallback or category model', () => {
+    const asFallback = sampleConfig({ fallback: { model: { providerID: 'openchamber', modelID: 'auto' }, variant: null } });
+    expect(() => parseEffectiveConfig(asFallback)).toThrow(/Auto model cannot be a routing target/);
+    const asCategory = sampleConfig();
+    asCategory.categories = asCategory.categories.map((c, i) => (i === 0 ? { ...c, model: { providerID: 'openchamber', modelID: 'auto' } } : c));
+    expect(() => parseEffectiveConfig(asCategory)).toThrow(/Auto model cannot be a routing target/);
+  });
+
+  it('keeps the token in its own 0600 file and clears it', async () => {
+    const dir = await tempDir();
+    const store = createRoutingStore({ dataDir: dir });
+    expect(await store.readToken()).toBeNull();
+    await store.writeToken('ts-secret');
+    expect(await store.readToken()).toBe('ts-secret');
+    const stat = await fs.stat(path.join(dir, 'routing-auth.json'));
+    if (process.platform !== 'win32') expect(stat.mode & 0o777).toBe(0o600);
+    expect(JSON.stringify(JSON.parse(await fs.readFile(path.join(dir, 'routing.json'), 'utf8').catch(() => '{}')))).not.toContain('ts-secret');
+    await store.clearToken();
+    expect(await store.readToken()).toBeNull();
+  });
+});

package/server/lib/scheduled-tasks/DOCUMENTATION.md

@@ -25,6 +25,12 @@ in shared project config under the project write lock:
   from the winner's persisted `nextRunAt`.
 - Project config writes also take a cross-process `.json.lock` file so the
   read-modify-write is serialized across processes, not only within one process.
+- `syncAllProjects` (startup and every full resync) syncs each registered
+  project on its own: a project whose config cannot be read or written (a
+  broken file, a lock timeout) is logged with its id and skipped, and every
+  other project's tasks are still scheduled. Only `listProjects` failing
+  aborts the sync as a whole. `syncProject` for one project still throws, so
+  a route for that project reports the failure.
 - The sharing processes may run different OpenChamber versions. Normalization
   keeps only the fields a build knows, so every writer persists tasks it did
   not change verbatim from disk and swaps only `state` onto a task whose state
@@ -63,7 +69,9 @@ in shared project config under the project write lock:
 - Claiming always writes `nextRunAt` (including `undefined`) so a past once-slot
   is cleared when there is no following occurrence.
 
-Manual `runNow` does not claim a schedule occurrence.
+Manual `runNow` does not claim a schedule occurrence. It also runs paused
+(`enabled: false`) tasks — that is the point of the button — while scheduled
+dispatches still skip disabled tasks, and completion never re-arms a paused task.
 
 ## Files
 

package/server/lib/scheduled-tasks/issue-2710-double-execution.test.js

@@ -485,4 +485,32 @@ describe('issue 2710: daily scheduled task double execution at the configured ti
 
     runtime.stop();
   });
+
+  it('manual runNow runs a paused task but does not schedule future runs', async () => {
+    vi.setSystemTime(UTC(2026, 0, 1, 14, 0, 0));
+    const task = { ...makeTask({ kind: 'daily', times: ['15:00'] }), enabled: false };
+    const projectConfigRuntime = createSharedProjectConfigRuntime(task);
+
+    const runtime = createScheduledTasksRuntime(createRuntimeDeps(projectConfigRuntime));
+    await runtime.start();
+
+    // The scheduler must not fire a disabled task on its own.
+    await vi.advanceTimersByTimeAsync(HOUR + 3_000);
+    expect(sdk.sessionCreates.length).toBe(0);
+
+    const manual = await runtime.runNow('p1', 'task-1');
+    expect(manual.ok).toBe(true);
+    expect(manual.sessionID).toBeTruthy();
+    expect(sdk.sessionCreates.length).toBe(1);
+    expect(runtime.getStatus().runningScheduledTasksCount).toBe(0);
+
+    // Completion records state but leaves the task paused with no next run.
+    const tasks = await projectConfigRuntime.listScheduledTasks('p1');
+    expect(tasks[0].enabled).toBe(false);
+    expect(tasks[0].state.lastStatus).toBe('success');
+    expect(tasks[0].state.lastSessionId).toBe('sess-1');
+    expect(tasks[0].state.nextRunAt).toBeUndefined();
+
+    runtime.stop();
+  });
 });

package/server/lib/scheduled-tasks/runtime.js

@@ -1,6 +1,6 @@
 import { createOpencodeClient } from '@opencode-ai/sdk/v2';
 import { DateTime } from 'luxon';
-import parser from 'cron-parser';
+import { CronExpressionParser } from 'cron-parser';
 import { expandSnippets } from '../opencode/snippets.js';
 import { buildGoalIntroText, createSessionGoal } from '../session-goal/create.js';
 import { discoverLoops } from './loops.js';
@@ -216,7 +216,7 @@ export const computeNextRunAt = (task, nowMs = Date.now()) => {
 
   if (schedule.kind === 'cron') {
     try {
-      const iterator = parser.parseExpression(schedule.cron, {
+      const iterator = CronExpressionParser.parse(schedule.cron, {
         tz: zone,
         currentDate: new Date(nowMs),
       });
@@ -426,7 +426,16 @@ export const createScheduledTasksRuntime = (deps) => {
     }
 
     for (const projectID of activeProjectIDs) {
-      await syncProject(projectID);
+      try {
+        await syncProject(projectID);
+      } catch (error) {
+        // One project's config being unusable (a broken file, a lock timeout)
+        // must not keep every other project's tasks from being scheduled.
+        logger.warn?.('[ScheduledTasks] failed to sync project', {
+          projectID,
+          error: error?.message ?? String(error),
+        });
+      }
     }
   };
 
@@ -676,7 +685,8 @@ export const createScheduledTasksRuntime = (deps) => {
   const runTask = async (projectID, taskID, reason, scheduledFor) => {
     const taskMap = tasksByProject.get(projectID);
     const task = taskMap?.get(taskID);
-    if (!task || !task.enabled) {
+    // Manual runNow runs paused tasks too; only scheduled dispatches skip them.
+    if (!task || (reason !== 'manual' && !task.enabled)) {
       return { ok: false, skipped: true };
     }
 

package/server/lib/scheduled-tasks/runtime.test.js

@@ -12,6 +12,20 @@ import {
 import { createProjectConfigRuntime } from '../projects/project-config.js';
 
 describe('scheduled-tasks runtime helpers', () => {
+  it.each([
+    ['*/15 * * * *', 'UTC', '2026-09-18T08:07:00Z', '2026-09-18T08:15:00Z'],
+    ['30 */5 * * * *', 'UTC', '2026-09-18T08:07:00Z', '2026-09-18T08:10:30Z'],
+    ['0 9 * * MON-FRI', 'Europe/Kyiv', '2026-09-18T07:00:00Z', '2026-09-21T06:00:00Z'],
+    ['0 9 * * *', 'Europe/Kyiv', '2026-03-28T08:00:00Z', '2026-03-29T06:00:00Z'],
+    ['0 9 * * *', 'Europe/Kyiv', '2026-10-24T08:00:00Z', '2026-10-25T07:00:00Z'],
+    ['0 0 L * *', 'UTC', '2026-02-01T00:00:00Z', '2026-02-28T00:00:00Z'],
+  ])('computes cron %s in %s from %s', (cron, timezone, now, expected) => {
+    expect(computeNextRunAt({
+      enabled: true,
+      schedule: { kind: 'cron', cron, timezone },
+    }, Date.parse(now))).toBe(Date.parse(expected));
+  });
+
   it('computes next daily run in timezone', () => {
     const nowUtc = Date.UTC(2025, 0, 1, 8, 0, 0);
     const next = computeNextRunAt({
@@ -206,3 +220,56 @@ Run daily.
     }
   });
 });
+
+describe('scheduled-tasks runtime syncAllProjects', () => {
+  it('keeps scheduling the other projects when one project cannot be synced', async () => {
+    const tempRoot = await mkdtemp(path.join(os.tmpdir(), 'oc-runtime-sync-all-'));
+    try {
+      const brokenPath = path.join(tempRoot, 'broken');
+      const healthyPath = path.join(tempRoot, 'healthy');
+      await mkdir(path.join(healthyPath, '.agents', 'loops'), { recursive: true });
+      await mkdir(brokenPath, { recursive: true });
+      await writeFile(path.join(healthyPath, '.agents', 'loops', 'daily.md'), `---
+name: daily
+schedule: "0 9 * * *"
+enabled: true
+model: openai/gpt-5
+---
+Run daily.
+`, 'utf8');
+
+      const projectConfigRuntime = createProjectConfigRuntime({
+        fsPromises: await import('fs/promises'),
+        path,
+        projectsDirPath: path.join(tempRoot, 'config'),
+        createTaskID: () => 'task-fixed-id',
+      });
+      await mkdir(path.join(tempRoot, 'config'), { recursive: true });
+      await writeFile(projectConfigRuntime.resolveProjectConfigPath('broken'), '{ not json', 'utf8');
+
+      const warnings = [];
+      const runtime = createScheduledTasksRuntime({
+        buildOpenCodeUrl: () => 'http://localhost',
+        getOpenCodeAuthHeaders: () => ({}),
+        waitForOpenCodeReady: async () => {},
+        projectConfigRuntime,
+        listProjects: async () => [
+          { id: 'broken', path: brokenPath },
+          { id: 'healthy', path: healthyPath },
+        ],
+        logger: { warn: (...args) => warnings.push(args) },
+      });
+
+      await expect(runtime.start()).resolves.toBeUndefined();
+
+      expect(runtime.getStatus().enabledScheduledTasksCount).toBe(1);
+      const healthyTasks = await projectConfigRuntime.listScheduledTasks('healthy');
+      expect(healthyTasks.map((task) => task.id)).toEqual(['loop:project:daily']);
+      expect(warnings).toHaveLength(1);
+      expect(warnings[0][1]).toMatchObject({ projectID: 'broken' });
+      runtime.stop();
+    } finally {
+      await rm(tempRoot, { recursive: true, force: true });
+    }
+  });
+});

package/server/lib/security/request-security.js

@@ -1,3 +1,5 @@
+import { sessionCookieNameForRequest } from '../ui-auth/session-cookie.js';
+
 export const createRequestSecurityRuntime = (deps) => {
   const { readSettingsFromDiskMigrated } = deps;
   // Origins of packaged (non-browser) clients whose WebView origin never
@@ -17,12 +19,14 @@ export const createRequestSecurityRuntime = (deps) => {
     if (!cookieHeader || typeof cookieHeader !== 'string') {
       return null;
     }
-    const segments = cookieHeader.split(';');
-    for (const segment of segments) {
+    // Match the exact slot for the host:port this request arrived on. A browser
+    // shares cookies across ports on LAN and loopback hosts. This extracts
+    // notification/session identity, not a CSRF token, using the same name
+    // as ui-auth's session issuance and validation.
+    const expected = sessionCookieNameForRequest(req);
+    for (const segment of cookieHeader.split(';')) {
       const [rawName, ...rest] = segment.split('=');
-      const name = rawName?.trim();
-      if (!name) continue;
-      if (name !== 'oc_ui_session') continue;
+      if (rawName?.trim() !== expected) continue;
       const value = rest.join('=').trim();
       try {
         return decodeURIComponent(value || '');

package/server/lib/security/request-security.test.js

@@ -80,4 +80,41 @@ describe('request security runtime', () => {
       headers: { ...request.headers, origin: 'https://evil.example.com' },
     })).toBe(false);
   });
+
+  test('reads the slot for the request port when a browser shares jars across LAN ports', () => {
+    const runtime = createRuntime();
+    // Two instances on one LAN IP: the browser sends BOTH session cookies to
+    // either port (browsers key cookie jars on host, not port — issue #2377).
+    const req = {
+      headers: {
+        host: '192.168.0.1:3001',
+        cookie: 'oc_ui_session_3000=token-a; oc_ui_session_3001=token-b',
+      },
+    };
+    expect(runtime.getUiSessionTokenFromRequest(req)).toBe('token-b');
+  });
+
+  test('never reads another port cookie when this port has none of its own', () => {
+    const runtime = createRuntime();
+    // Reaching :3001 with only the :3000 cookie in the jar must NOT borrow the
+    // other instance's session — it stays unauthenticated for this port.
+    const req = {
+      headers: { host: '192.168.0.1:3001', cookie: 'oc_ui_session_3000=token-a' },
+    };
+    expect(runtime.getUiSessionTokenFromRequest(req)).toBeNull();
+  });
+
+  test('reads the bare cookie for a host without an explicit port', () => {
+    const runtime = createRuntime();
+    const req = {
+      headers: { host: '192.168.0.1', cookie: 'oc_ui_session=token-bare' },
+    };
+    expect(runtime.getUiSessionTokenFromRequest(req)).toBe('token-bare');
+  });
+
+  test('returns null when no session cookie is present', () => {
+    const runtime = createRuntime();
+    const req = { headers: { host: '192.168.0.1:3000', cookie: 'theme=dark; oc_url_token=x' } };
+    expect(runtime.getUiSessionTokenFromRequest(req)).toBeNull();
+  });
 });

package/server/lib/session-assist/DOCUMENTATION.md

@@ -1,66 +1,131 @@
-# Session Assist
-
-Server-side watcher that generates a short recap of the agent's last reply
-and one suggested user follow-up with the small model
-(`lib/small-model`), storing both on the session's metadata under
-`metadata.openchamber.assist`.
-
-## Flow
-
-1. `createSessionAssistRuntime` is a consumer of the server's global SSE
-   fan-out (`index.js` → `onPayload`), riding the same upstream connection as
-   notifications. Purely event-driven — dormant sessions never generate
-   anything, there is no backfill and no session scanning.
-2. `session.status: idle` arms a 60-second per-session timer; any `busy`/
-   `retry` status or a user `message.updated` clears it (the "1 minute of
-   quiet" rule).
-3. On fire: fetch the session (skip sub-agent sessions with `parentID`),
-   take the LAST exchange only — the final assistant reply plus the user
-   message it answered (assistant `parentID` → user id) — and call
-   `generateSmallModelText` with the
-   session's own provider/model taken from the last assistant message — so
-   the utility call spends the same subscription as the conversation.
-   `restrictToPreferredProvider` forbids the resolver's global fallback:
-   conversation content never goes to a provider the user didn't pick for
-   the session, unless the small model was chosen explicitly (settings
-   override or opencode config). A resolver 404 is silently skipped.
-4. The requested JSON fields (`recap`, `suggestion`, or both) are clamped and
-   PATCHed onto the session metadata together with `forMessageID` (the last
-   assistant message id) and `generatedAt`. Before writing, the session tail is
-   re-checked (a stale result is dropped) and the metadata is merged from a
-   fresh session read so concurrent metadata writes made during generation are
-   preserved.
-
-## Settings gate
-
-`sessionRecapEnabled` and `sessionSuggestionEnabled` in OpenChamber settings
-(Settings → Chat, default on) are hard generation switches checked at fire
-time. When both are off, no small-model calls run and nothing is written. When
-one is on, the runtime still makes at most one small-model call and asks only
-for that field. The UI also hides disabled payload types immediately.
-
-## Freshness contract (no clearing writes)
-
-Clients do not need the payload to be deleted: they render it only while
-`assist.forMessageID` still equals the session's last assistant message id
-(and the session is idle). Any new message invalidates the payload
-everywhere instantly and offline; the next idle cycle overwrites it.
-
-## UI consumers (packages/ui)
-
-- `lib/sessionAssistMetadata.ts` — payload parsing.
-- `hooks/useSessionAssist.ts` — freshness gating + the 1-minute quiet window
-  for the recap (single timeout to the boundary, no polling).
-- `components/chat/SessionRecapSpacer.tsx` — renders the recap inside the
-  fixed-height reserved gap under the last message (height never changes).
-- `components/chat/SessionSuggestionChip.tsx` — one tappable suggestion chip
-  near the composer (desktop chips row + above the mobile pill); hidden as
-  soon as the composer has any content. Tap fills the input, never sends.
-
-## Limitations
-
-- The watcher lives in the web server, so VS Code (extension-only, no web
-  server) does not generate assists; it still renders payloads produced by a
-  web/desktop instance of the same OpenCode server via `session.updated`.
-- Metadata payloads ride every `session.updated` event — keep the clamps
-  (`RECAP_CHAR_LIMIT`, `SUGGESTION_CHAR_LIMIT`) small.
+# Session assist
+
+The server generates a short reminder of recent work and an optional next user
+message with Small Model. Results live in `metadata.openchamber.assist` with
+`recap`, `suggestion`, `forMessageID`, and `generatedAt`. The payload shape is
+unchanged; an empty suggestion is a successful outcome.
+
+## Ownership
+
+- `runtime.js` owns idle timers, cancellation, provider selection, SDK reads,
+  freshness checks, settings gates, and metadata writes.
+- `context.js` reads bounded history and constructs human turns. It removes
+  tool payloads and injected prompts before retaining message text.
+- `prompt.js` owns the generation instructions and total input budget.
+- `../small-model/DOCUMENTATION.md` owns provider/auth resolution, generation,
+  output limits, and overflow behavior.
+
+## What the model receives
+
+Read backward through the official SDK in pages of 50 messages until three
+human turns are covered, history ends, or eight pages have been read. A failed
+page or repeated cursor aborts generation; it is not treated as complete history.
+At the page limit, use fewer available human turns. If the latest answer's human
+request has not been found, skip generation rather than invent its context.
+
+Three turns retain the substance behind short commit confirmations without
+bringing an entire old task back into the prompt. This was compared against
+one, five, ten, and full-history contexts on long maintainer sessions. There
+is no full-history cache and no assumed provider prefix-cache behavior.
+
+The latest record must be a completed, successful, non-summary assistant answer
+with visible text. Child, archived, and reverted sessions are skipped. A new
+prompt clears the revert boundary before its next idle event.
+
+Human turns follow chronological message intervals. OpenCode can insert
+synthetic continuation users during compaction, so a final answer's `parentID`
+need not point directly at the original human request. These continuations stay
+within their human turn; compaction summaries are excluded. An interrupted
+request remains context with its last visible progress explicitly labeled as
+unfinished, rather than being dropped or called a final answer.
+An answer must still reference that human user or one of its continuation
+users; a late answer for an older request cannot be assigned to a newer request.
+
+### Attached context and language
+
+The persisted attachment contract is owned by
+`packages/ui/src/lib/messages/contextParts.ts`. Its user-facing Markdown
+formatter is `packages/ui/src/lib/messages/messageMarkdown.ts`.
+
+The server projects those persisted parts into model context without importing
+the UI runtime: code comments, file/chat quotes, browser annotations, PR comments,
+checks, terminal selections, and linked GitHub/Linear items remain attached to
+the user turn even when their transport part is synthetic. The OpenCode
+`opencodeComment` mirror is also accepted. Unrecognized synthetic prompts and
+ignored parts are excluded. Malformed attached text fails the generation.
+
+Quoted material and the user's own comment are separate blocks. The user's
+authored text is also supplied separately for language selection. Quoted source,
+logs, assistant replies, and injected memory instructions do not choose the
+language. A language-neutral final acknowledgment can use recent authored text.
+The existing Cyrillic/CJK mismatch guard uses that authored sample per field;
+it is not a complete language detector, and it is skipped if no sample exists.
+
+### Input bounds
+
+User text is bounded to 8,000 characters and each assistant answer to 16,000.
+Attached quote bodies have their own 4,000-character limit so a large quote
+does not consume the user's comment. Excerpts preserve both ends with an
+explicit omission marker, including the conclusion of a long final report.
+
+The complete user prompt is limited to 32,000 characters and the resolved small
+model's input allowance, reserving space for the system prompt. Under pressure,
+drop older whole turns first. If the latest pair itself is too large, excerpt
+both its user request and answer rather than discarding either side. If even
+the minimum prompt cannot fit, skip generation. `onOverflow: 'error'` prevents
+the Small Model service from silently cutting off the instructions. Expected
+context/output-budget failures are quiet and do not write metadata.
+
+OpenCode message pages still contain complete tool payloads on the wire. A
+single long turn can therefore require substantial I/O even though its retained
+model context is small. Page/count bounds are not a network-byte quota.
+
+## Generation and lifecycle
+
+1. The server's existing global event fan-out calls `processPayload`. An idle
+   event arms the 60-second quiet window. No history scan or startup backfill runs.
+2. Busy/retry events and newly created user messages clear pending work and
+   abort in-flight reads/generation. Re-emitted old user updates do not cancel it.
+3. One generation runs per session. If a newer quiet window expires while an
+   old canceled request is still settling, retain that pending run and start it
+   after the old one finishes. Later activity cancels the pending run as well.
+4. Resolve the small model using the last answer's provider/model and the
+   existing explicit settings/config overrides. `restrictToPreferredProvider`
+   prevents an implicit cross-provider fallback. Production does not pin the
+   experimental model. Generation accepts an abort signal and a 120-second limit.
+5. Recap describes the substantive work and its current result, including the
+   work behind a closing commit or acknowledgment. Suggestion is independent:
+   only unfinished requested agent work should produce a sendable user message.
+   Completed work, optional offers, or a decision/action belonging to the user
+   should return an empty suggestion. This is model judgment, not authorization
+   enforcement or a guarantee that every generated field is factually correct.
+6. Re-read the latest message and fresh session before writing. A moved tail,
+   canceled run, changed endpoint/directory, archive, revert, or failed fresh
+   read discards the result. Never merge from the old pre-generation metadata.
+7. Re-check settings, clamp the enabled fields, and merge into fresh metadata.
+   The OpenCode update endpoint has no compare-and-set operation; another
+   writer after the final read is not guarded atomically.
+
+Stopping the runtime clears pending timers/runs and aborts in-flight operations.
+No failed session blocks another session.
+
+## Settings and consumers
+
+`sessionRecapEnabled` and `sessionSuggestionEnabled` default on and are checked
+before work and before writing. With both off there are no reads, model calls,
+or writes. With one on, the shared recent context is still available, but only
+that field is requested. An empty suggestion does not erase a valid recap.
+
+Clients render an assist only while its `forMessageID` is the last message and
+the session is idle. A new message invalidates it without clearing writes.
+
+- `packages/ui/src/lib/sessionAssistMetadata.ts` parses the payload.
+- `packages/ui/src/hooks/useSessionAssist.ts` owns freshness/settings gating.
+- `SessionRecapSpacer` shows the reminder in the reserved gap under the reply.
+- `SessionSuggestionChip` fills the composer; it never sends automatically.
+
+Web, Electron, hosted mobile, and Capacitor use the server watcher. VS Code's
+extension-only runtime does not generate assists; shared UI can render payloads
+produced by a server. The background watcher cannot use the browser's message
+store when the UI is closed. Manual AI rename uses that store through
+`SessionMessageLoader`; these are intentionally different retrieval lifecycles.