@openchambery/web 1.19.15 → 1.19.17-beta.1

package/server/lib/assistants/memory.js

@@ -0,0 +1,124 @@
+import { createHash } from 'node:crypto';
+import { getContactAssistantContextBoundary, getContactContextBoundary, getContactGeneration } from './contact-store.js';
+
+const SCAN_LIMIT = 200;
+const fail = (code) => { throw Object.assign(new Error(code), { code }); };
+const paramsObject = (value, keys) => {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some((key) => !keys.includes(key))) fail('validation_error');
+};
+const integer = (value, fallback, min, max) => {
+  if (value === undefined) return fallback;
+  if (!Number.isSafeInteger(value) || value < min || value > max) fail('validation_error');
+  return value;
+};
+const time = (value) => {
+  if (value === undefined) return null;
+  if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}T.+(?:Z|[+-]\d{2}:\d{2})$/u.test(value)) fail('validation_error');
+  const result = Date.parse(value);
+  if (!Number.isFinite(result)) fail('validation_error');
+  return result;
+};
+
+// Project only authored text, ordered exactly as the contact transcript.
+// Attachment bodies, URLs, peer DMs, diagnostics and tool payloads never leave this reader.
+const textRows = (count) => `
+  WITH text_parts AS (
+    SELECT message_id, json_extract(part_json, '$.text') AS text
+    FROM assistant_contact_part
+    WHERE message_id IN (${Array(count).fill('?').join(',')})
+      AND json_extract(part_json, '$.type') = 'text'
+      AND substr(json_extract(part_json, '$.text'), 1, 10) <> 'oc.settle.'
+    ORDER BY message_id, ordinal, part_id
+  ), texts AS (
+    SELECT message_id, group_concat(text, '') AS text FROM text_parts GROUP BY message_id
+  )`;
+
+/** One contact turn's read-only view, fenced again against live memory state on every call. */
+export function createContactMemoryReader(db, assistantID, { beforeOrdinal = null, assertAvailable = () => {} } = {}) {
+  const boundary = getContactContextBoundary(db, assistantID);
+  const assistantBoundary = getContactAssistantContextBoundary(db, assistantID);
+  const generation = getContactGeneration(db, assistantID);
+  const ceiling = Number(db.prepare('SELECT COALESCE(MAX(ordinal), 0) AS value FROM assistant_contact_message WHERE assistant_id=?').get(assistantID).value);
+  const eligible = (row) => row.role !== 'peer' && ['user', 'assistant'].includes(row.role)
+    && row.status === 'complete' && !row.from_assistant_id
+    && (row.role !== 'assistant' || row.ordinal > assistantBoundary)
+    && (row.role !== 'user' || beforeOrdinal === null || row.ordinal < beforeOrdinal);
+  const check = () => {
+    assertAvailable();
+    if (getContactGeneration(db, assistantID) !== generation || getContactContextBoundary(db, assistantID) !== boundary
+      || getContactAssistantContextBoundary(db, assistantID) !== assistantBoundary) fail('memory_scope_changed');
+  };
+  return {
+    search(params = {}) {
+      check();
+      paramsObject(params, ['query', 'from', 'to', 'limit', 'cursor']);
+      const query = params.query === undefined ? '' : params.query;
+      if (typeof query !== 'string' || query.length > 256) fail('validation_error');
+      const from = time(params.from);
+      const to = time(params.to);
+      if (from !== null && to !== null && from > to) fail('validation_error');
+      const limit = integer(params.limit, 10, 1, 20);
+      const scope = createHash('sha256').update(JSON.stringify([assistantID, boundary, assistantBoundary, generation, ceiling, beforeOrdinal, query, from, to])).digest('hex');
+      let cursor = null;
+      if (params.cursor !== undefined) {
+        if (typeof params.cursor !== 'string' || params.cursor.length > 2048 || !/^[A-Za-z0-9_-]+$/u.test(params.cursor)) fail('invalid_memory_cursor');
+        try { cursor = JSON.parse(Buffer.from(params.cursor, 'base64url').toString('utf8')); } catch { fail('invalid_memory_cursor'); }
+        if (cursor?.v !== 1 || cursor.scope !== scope || !Number.isSafeInteger(cursor.ordinal)
+          || cursor.ordinal <= boundary || cursor.ordinal > ceiling || typeof cursor.messageID !== 'string'
+          || !cursor.messageID || cursor.messageID.length > 512) fail('invalid_memory_cursor');
+      }
+      const rows = db.prepare(`SELECT message_id, role, created_at, ordinal, status, from_assistant_id
+        FROM assistant_contact_message WHERE assistant_id=? AND ordinal>? AND ordinal<=?
+        ${cursor ? 'AND (ordinal, message_id) < (?, ?)' : ''}
+        ORDER BY ordinal DESC, message_id DESC LIMIT ?`).all(
+        assistantID, boundary, ceiling, ...(cursor ? [cursor.ordinal, cursor.messageID] : []), SCAN_LIMIT + 1,
+      );
+      const candidates = rows.slice(0, SCAN_LIMIT);
+      const ids = candidates.filter((row) => eligible(row)
+        && (from === null || row.created_at >= from) && (to === null || row.created_at <= to)).map((row) => row.message_id);
+      const snippets = ids.length === 0 ? [] : db.prepare(`${textRows(ids.length)}
+        SELECT message_id, substr(text, max(instr(lower(text), lower(?)) - 80, 1), 400) AS snippet,
+          max(instr(lower(text), lower(?)) - 81, 0) AS snippet_offset, length(text) AS total_chars
+        FROM texts WHERE length(trim(text)) > 0 AND (? = '' OR instr(lower(text), lower(?)) > 0)
+      `).all(...ids, query, query, query, query);
+      const byID = new Map(snippets.map((row) => [row.message_id, row]));
+      const matches = [];
+      let scanned = 0;
+      for (const row of candidates) {
+        scanned += 1;
+        const snippet = byID.get(row.message_id);
+        if (snippet) matches.push({
+          messageID: row.message_id, role: row.role, createdAt: row.created_at,
+          snippet: snippet.snippet, offset: snippet.snippet_offset, totalChars: snippet.total_chars,
+        });
+        if (matches.length === limit) break;
+      }
+      const last = candidates[scanned - 1];
+      const hasMore = scanned < rows.length;
+      const nextCursor = hasMore && last ? Buffer.from(JSON.stringify({
+        v: 1, scope, ordinal: last.ordinal, messageID: last.message_id,
+      })).toString('base64url') : null;
+      return { matches, nextCursor, complete: nextCursor === null, scanned };
+    },
+    read(params = {}) {
+      check();
+      paramsObject(params, ['messageID', 'offset', 'maxChars']);
+      if (typeof params.messageID !== 'string' || !params.messageID || params.messageID.length > 512) fail('validation_error');
+      const offset = integer(params.offset, 0, 0, Number.MAX_SAFE_INTEGER);
+      const maxChars = integer(params.maxChars, 4000, 1, 8000);
+      const row = db.prepare(`SELECT message_id, role, created_at, ordinal, status, from_assistant_id
+        FROM assistant_contact_message WHERE assistant_id=? AND message_id=? AND ordinal>? AND ordinal<=?`).get(
+        assistantID, params.messageID, boundary, ceiling,
+      );
+      if (!row || !eligible(row)) fail('memory_not_found');
+      const content = db.prepare(`${textRows(1)} SELECT substr(text, ?, ?) AS text, length(text) AS total_chars FROM texts`).get(row.message_id, offset + 1, maxChars);
+      if (!content || !content.total_chars) fail('memory_not_found');
+      if (offset > content.total_chars) fail('validation_error');
+      const nextOffset = offset + maxChars < content.total_chars ? offset + maxChars : null;
+      return {
+        messageID: row.message_id, role: row.role, createdAt: row.created_at,
+        text: content.text, offset, totalChars: content.total_chars, nextOffset, complete: nextOffset === null,
+      };
+    },
+  };
+}

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

@@ -0,0 +1,159 @@
+import { createRequire } from 'node:module';
+import { afterEach, describe, expect, it } from 'vitest';
+import { createContactMemoryReader } from './memory.js';
+import { bumpContactGeneration, clearContactMemory, contactHistoryForLlm, deleteContactMessages, ensureContactSchema, insertContactMessage } from './contact-store.js';
+
+const Database = createRequire(import.meta.url)('better-sqlite3');
+const databases = [];
+afterEach(() => { while (databases.length) databases.pop().close(); });
+const fixture = () => {
+  const db = new Database(':memory:');
+  databases.push(db);
+  ensureContactSchema(db);
+  let ordinal = 0;
+  const insert = (messageID, text, { assistantID = 'a', role = 'user', turnID = messageID, ...extra } = {}) => {
+    insertContactMessage(db, {
+      messageID, assistantID, role, turnID, ordinal: ++ordinal, createdAt: 1_700_000_000_000 + ordinal,
+      parts: [{ type: 'text', text }], ...extra,
+    });
+    return ordinal;
+  };
+  return { db, insert };
+};
+
+describe('contact memory boundaries', () => {
+  it('forgets a preceding turn late reply while preserving queued users after clear-memory admission', () => {
+    const { db, insert } = fixture();
+    insert('prior', 'Old decision');
+    const clearing = insert('clearing', 'Clear memory');
+    insert('queued', 'New topic');
+    insert('late-prior', 'Old decision details', { role: 'assistant', turnID: 'prior' });
+    clearContactMemory(db, 'a', { upToOrdinal: clearing });
+    insert('reset-confirm', 'Ready for a new topic', { role: 'assistant', turnID: 'clearing' });
+    const reader = createContactMemoryReader(db, 'a');
+    expect(reader.search().matches.map((m) => m.messageID)).toEqual(['reset-confirm', 'queued']);
+    expect(() => reader.read({ messageID: 'late-prior' })).toThrow('memory_not_found');
+    expect(contactHistoryForLlm(db, 'a').map((m) => m.content)).toEqual(['New topic', 'Ready for a new topic']);
+  });
+
+  it('scopes exact reads, search and cursors to one assistant and rejects target overrides', () => {
+    const { db, insert } = fixture();
+    insert('a1', 'needle own'); insert('a2', 'needle own later');
+    insert('b1', 'needle other', { assistantID: 'b' });
+    const a = createContactMemoryReader(db, 'a');
+    const b = createContactMemoryReader(db, 'b');
+    expect(a.search({ query: 'needle' }).matches.map((m) => m.messageID)).toEqual(['a2', 'a1']);
+    expect(() => a.read({ messageID: 'b1' })).toThrow('memory_not_found');
+    expect(() => a.search({ assistantID: 'b' })).toThrow('validation_error');
+    expect(() => b.search({ query: 'needle', cursor: a.search({ query: 'needle', limit: 1 }).nextCursor })).toThrow('invalid_memory_cursor');
+  });
+
+  it('bounds scans and exposes empty partial pages until an older match is reached', () => {
+    const { db, insert } = fixture();
+    insert('old', 'rare decision');
+    for (let i = 0; i < 410; i++) insert(`filler-${i}`, 'ordinary');
+    const reader = createContactMemoryReader(db, 'a');
+    let page = reader.search({ query: 'rare' });
+    expect(page).toMatchObject({ matches: [], complete: false, scanned: 200 });
+    page = reader.search({ query: 'rare', cursor: page.nextCursor });
+    expect(page).toMatchObject({ matches: [], complete: false, scanned: 200 });
+    page = reader.search({ query: 'rare', cursor: page.nextCursor });
+    expect(page.matches.map((m) => m.messageID)).toEqual(['old']);
+    expect(page.complete).toBe(true);
+    expect(page.scanned).toBe(11);
+  });
+
+  it('paginates matching rows without gaps and returns literal, dated snippets', () => {
+    const { db, insert } = fixture();
+    for (let i = 0; i < 7; i++) insert(`match-${i}`, `100%_literal ${i}`);
+    const reader = createContactMemoryReader(db, 'a');
+    const ids = [];
+    let cursor;
+    do {
+      const page = reader.search({ query: '%_', limit: 2, ...(cursor ? { cursor } : {}) });
+      ids.push(...page.matches.map((m) => m.messageID));
+      cursor = page.nextCursor;
+    } while (cursor);
+    expect(ids).toEqual(['match-6', 'match-5', 'match-4', 'match-3', 'match-2', 'match-1', 'match-0']);
+    const page = reader.search({ from: new Date(1_700_000_000_003).toISOString(), to: new Date(1_700_000_000_004).toISOString() });
+    expect(page.matches.map((m) => m.messageID)).toEqual(['match-3', 'match-2']);
+  });
+
+  it('reads long Unicode messages by character offsets, including a match beyond the first chunk', () => {
+    const { db, insert } = fixture();
+    const text = '你好🙂'.repeat(2000) + 'rare ending';
+    insert('long', text);
+    const reader = createContactMemoryReader(db, 'a');
+    const found = reader.search({ query: 'rare' }).matches[0];
+    expect(found.snippet).toContain('rare ending');
+    expect(found.offset).toBeGreaterThan(4000);
+    let offset = 0;
+    let recovered = '';
+    do {
+      const page = reader.read({ messageID: 'long', offset, maxChars: 997 });
+      recovered += page.text;
+      offset = page.nextOffset;
+    } while (offset !== null);
+    expect(recovered).toBe(text);
+    expect(() => reader.read({ messageID: 'long', offset: 99999 })).toThrow('validation_error');
+  });
+
+  it('invalidates captured readers and cursors on clear and wipe, retaining visible history only for clear', () => {
+    const { db, insert } = fixture();
+    insert('old-1', 'old'); insert('old-2', 'old');
+    const reader = createContactMemoryReader(db, 'a');
+    const cursor = reader.search({ limit: 1 }).nextCursor;
+    clearContactMemory(db, 'a');
+    expect(() => reader.search({ cursor })).toThrow('memory_scope_changed');
+    expect(() => reader.read({ messageID: 'old-1' })).toThrow('memory_scope_changed');
+    const fresh = createContactMemoryReader(db, 'a');
+    expect(fresh.search().matches).toEqual([]);
+    expect(() => fresh.read({ messageID: 'old-1' })).toThrow('memory_not_found');
+    expect(() => fresh.search({ cursor })).toThrow('invalid_memory_cursor');
+    deleteContactMessages(db, 'a'); bumpContactGeneration(db, 'a');
+    expect(() => fresh.search()).toThrow('memory_scope_changed');
+    expect(createContactMemoryReader(db, 'a').search().matches).toEqual([]);
+  });
+
+  it('excludes peers, errors, internal markers, attachment bodies and later queued admissions', () => {
+    const { db, insert } = fixture();
+    insert('visible', 'visible');
+    const current = insert('current', 'current question');
+    insert('queued', 'queued secret');
+    insert('error', 'error secret', { role: 'assistant', status: 'error' });
+    insert('peer', 'peer secret', { role: 'peer', fromAssistantID: 'b' });
+    insert('internal', 'oc.settle.complete', { role: 'assistant' });
+    insert('file', '', { parts: [{ type: 'file', mime: 'text/plain', url: 'data:text/plain;base64,c2VjcmV0', filename: 'private.txt' }] });
+    const reader = createContactMemoryReader(db, 'a', { beforeOrdinal: current });
+    insert('future', 'future secret');
+    expect(reader.search().matches.map((m) => m.messageID)).toEqual(['visible']);
+    for (const id of ['current', 'queued', 'error', 'peer', 'internal', 'file', 'future']) expect(() => reader.read({ messageID: id })).toThrow('memory_not_found');
+  });
+
+  it('rejects malformed arguments and changed-filter cursors while database failures remain errors', () => {
+    const { db, insert } = fixture();
+    insert('one', 'needle'); insert('two', 'needle');
+    const reader = createContactMemoryReader(db, 'a');
+    for (const params of [{ limit: 21 }, { query: 1 }, { from: 'yesterday' }, { cursor: '{}' }, { cursor: 'bnVsbA' }]) expect(() => reader.search(params)).toThrow();
+    const cursor = reader.search({ query: 'needle', limit: 1 }).nextCursor;
+    expect(() => reader.search({ query: 'different', cursor })).toThrow('invalid_memory_cursor');
+    db.exec('DROP TABLE assistant_contact_part');
+    expect(() => reader.search()).toThrow();
+    expect(() => reader.read({ messageID: 'one' })).toThrow();
+  });
+
+  it('migrates existing boundaries and rolls both watermarks back on failed transactions', () => {
+    const { db, insert } = fixture();
+    insert('old', 'old text');
+    db.exec('ALTER TABLE assistant_contact_context_boundary DROP COLUMN assistant_after_ordinal');
+    db.prepare('INSERT INTO assistant_contact_context_boundary VALUES (?,?,?)').run('a', 1, 1);
+    ensureContactSchema(db);
+    insert('new', 'new text');
+    const reader = createContactMemoryReader(db, 'a');
+    expect(reader.search().matches.map((m) => m.messageID)).toEqual(['new']);
+    db.exec('BEGIN');
+    clearContactMemory(db, 'a');
+    db.exec('ROLLBACK');
+    expect(reader.search().matches.map((m) => m.messageID)).toEqual(['new']);
+  });
+});

package/server/lib/assistants/service.js

@@ -5,6 +5,7 @@ import path from 'node:path';
 import { createOpencodeClient } from '@opencode-ai/sdk/v2';
 import { validAssistantDeliveryParts } from '../assistant-delivery-parts.js';
 import { reduceBackfillState } from './history-state.js';
+import { createContactMemoryReader } from './memory.js';
 import { getWorktrees as defaultListWorktrees } from '../git/service.js';
 import { contactCardIdentity, parseContactCard, parseContactPart } from './cards.js';
 import {
@@ -2240,7 +2241,10 @@ export const createAssistantsService = ({ dbPath, dataDir, buildOpenCodeUrl, get
           history,
           { budgetBytes: CONTACT_ATTACHMENT_TURN_BUDGET_BYTES },
         );
+        const memory = createContactMemoryReader(db, assistantID, { assertAvailable: () => editable(assistantID) });
         const tools = createContactTools({
+          searchMemory: memory.search,
+          readMemory: memory.read,
           assignWork: (params) => assignWork(live, params),
           watchSession: (params) => watchSessionWork(live, params),
           stopSession: (params) => stopSessionWork(live, params),
@@ -2570,7 +2574,12 @@ export const createAssistantsService = ({ dbPath, dataDir, buildOpenCodeUrl, get
             (Array.isArray(executionParts) ? executionParts : []).filter((part) => part?.type === 'file'),
           );
           const turnAttachmentScope = attachmentScopeKey(turnFileParts);
+          const memory = createContactMemoryReader(db, row.assistant_id, {
+            beforeOrdinal, assertAvailable: () => editable(row.assistant_id),
+          });
           const tools = createContactTools({
+            searchMemory: memory.search,
+            readMemory: memory.read,
             assignWork: (params) => assignWork(row, params),
             watchSession: (params) => watchSessionWork(row, params),
             stopSession: (params) => stopSessionWork(row, params),

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

@@ -25,6 +25,8 @@ Server-owned scheduled task runtime and routes for OpenChamber-only automation.
   - Independent SQLite file `scheduled-task-runs.sqlite` (WAL)
   - Keyset-paginated list of run records
   - On open, converges leftover `running` rows to `error` with an interrupted message
+  - Scheduled runs claim `(project_id, task_id, slot_at)` so multiple OpenChamber
+    processes sharing a data dir cannot occupy the same fire slot
 
 - `packages/web/server/lib/scheduled-tasks/routes.js`
   - Global scheduled task list endpoint with per-project partial-result handling
@@ -101,6 +103,11 @@ Persisted columns:
 | `started_at` | Epoch ms |
 | `finished_at` | Nullable epoch ms |
 | `duration_ms` | Nullable |
+| `slot_at` | Scheduled occupancy key (the armed `nextRunAt`). Null for manual runs. List DTO omits this column. |
+
+Partial unique index `scheduled_task_run_scheduled_slot` on
+`(project_id, task_id, slot_at)` where `trigger = 'scheduled' AND slot_at IS NOT NULL`.
+A second `startRun` for the same slot throws `SCHEDULED_SLOT_CLAIMED`.
 
 Indexes support `started_at DESC, run_id DESC` listing with project/task filters.
 
@@ -168,6 +175,9 @@ failure preserves tasks from completed projects and adds that project ID to
 Every actual run (timer or manual):
 
 1. Allocate a unique `runID` and persist `status=running` in the history store.
+   Timer fires pass the armed `nextRunAt` as `slotAt`. A duplicate scheduled
+   slot claim skips the run: no session, no task-state write, no notification.
+   The losing scheduler arms the next occurrence and returns `{ skipped: true }`.
 2. Persist task state `lastStatus=running`.
 3. Create a per-run `AbortController` and race `runTaskWithWatchdog` against
    `maxRunDurationMs` (default 2 hours). Only this watchdog timeout aborts

package/server/lib/scheduled-tasks/run-history-store.js

@@ -8,6 +8,8 @@ const require = createRequire(import.meta.url);
 const DEFAULT_LIMIT = 20;
 const MAX_LIMIT = 100;
 const INTERRUPTED_ERROR = 'Run interrupted by process restart';
+export const SCHEDULED_SLOT_CLAIMED_CODE = 'SCHEDULED_SLOT_CLAIMED';
+const SQLITE_UNIQUE_CODES = new Set(['SQLITE_CONSTRAINT', 'SQLITE_CONSTRAINT_UNIQUE']);
 
 const asNonEmptyString = (value) => {
   if (typeof value !== 'string') {
@@ -105,6 +107,18 @@ export const createScheduledTaskRunHistoryStore = ({ dbPath, clock = () => Date.
       ON scheduled_task_run (project_id, task_id, started_at DESC, run_id DESC);
   `);
 
+  const hasSlotAt = db.prepare(`
+    SELECT 1 AS ok FROM pragma_table_info('scheduled_task_run') WHERE name = 'slot_at'
+  `).get();
+  if (!hasSlotAt) {
+    db.exec('ALTER TABLE scheduled_task_run ADD COLUMN slot_at INTEGER');
+  }
+  db.exec(`
+    CREATE UNIQUE INDEX IF NOT EXISTS scheduled_task_run_scheduled_slot
+      ON scheduled_task_run (project_id, task_id, slot_at)
+      WHERE trigger = 'scheduled' AND slot_at IS NOT NULL
+  `);
+
   const now = () => Math.trunc(clock());
 
   const convergeInterruptedRuns = () => {
@@ -137,17 +151,29 @@ export const createScheduledTaskRunHistoryStore = ({ dbPath, clock = () => Date.
     const trigger = record.trigger === 'manual' ? 'manual' : 'scheduled';
     const directory = asNonEmptyString(record.directory);
     const startedAt = asFiniteInteger(record.startedAt) ?? now();
+    const slotAt = trigger === 'scheduled'
+      ? asFiniteInteger(record.slotAt ?? record.slot_at)
+      : null;
 
     if (!projectId || !taskId) {
       throw new Error('projectId and taskId are required');
     }
 
-    db.prepare(`
-      INSERT INTO scheduled_task_run (
-        run_id, project_id, task_id, task_name, trigger, status,
-        session_id, directory, error, started_at, finished_at, duration_ms
-      ) VALUES (?, ?, ?, ?, ?, 'running', NULL, ?, NULL, ?, NULL, NULL)
-    `).run(id, projectId, taskId, taskName, trigger, directory, startedAt);
+    try {
+      db.prepare(`
+        INSERT INTO scheduled_task_run (
+          run_id, project_id, task_id, task_name, trigger, status,
+          session_id, directory, error, started_at, finished_at, duration_ms, slot_at
+        ) VALUES (?, ?, ?, ?, ?, 'running', NULL, ?, NULL, ?, NULL, NULL, ?)
+      `).run(id, projectId, taskId, taskName, trigger, directory, startedAt, slotAt);
+    } catch (error) {
+      if (slotAt !== null && SQLITE_UNIQUE_CODES.has(error?.code)) {
+        const claimed = new Error('scheduled slot already claimed');
+        claimed.code = SCHEDULED_SLOT_CLAIMED_CODE;
+        throw claimed;
+      }
+      throw error;
+    }
 
     return rowToDto(db.prepare('SELECT * FROM scheduled_task_run WHERE run_id = ?').get(id));
   };

package/server/lib/scheduled-tasks/run-history-store.test.js

@@ -1,9 +1,12 @@
 import fs from 'node:fs';
+import { createRequire } from 'node:module';
 import os from 'node:os';
 import path from 'node:path';
 import { afterEach, describe, expect, it } from 'vitest';
 import { createScheduledTaskRunHistoryStore } from './run-history-store.js';
 
+const require = createRequire(import.meta.url);
+
 const directories = [];
 
 const createTempDbPath = () => {
@@ -26,6 +29,7 @@ const startSample = (store, overrides = {}) => store.startRun({
   trigger: overrides.trigger ?? 'scheduled',
   directory: overrides.directory ?? '/tmp/project-a',
   startedAt: overrides.startedAt,
+  slotAt: overrides.slotAt,
 });
 
 describe('scheduled task run history store', () => {
@@ -160,4 +164,74 @@ describe('scheduled task run history store', () => {
     expect(() => store.listRuns({ limit: -3 })).toThrow(/limit/i);
     store.close();
   });
+
+  it('lets only one scheduled startRun occupy a slot, including across store handles', () => {
+    const dbPath = createTempDbPath();
+    const first = createScheduledTaskRunHistoryStore({ dbPath });
+    startSample(first, { id: 'run-a', slotAt: 1_700_000_000_000 });
+
+    expect(() => startSample(first, { id: 'run-b', slotAt: 1_700_000_000_000 })).toThrow(
+      /already claimed/,
+    );
+
+    const second = createScheduledTaskRunHistoryStore({ dbPath });
+    expect(() => startSample(second, { id: 'run-c', slotAt: 1_700_000_000_000 })).toThrow(
+      /already claimed/,
+    );
+
+    startSample(first, { id: 'run-next-slot', slotAt: 1_700_000_000_000 + 60_000 });
+    startSample(first, {
+      id: 'run-manual',
+      trigger: 'manual',
+      slotAt: 1_700_000_000_000,
+    });
+
+    expect(first.listRuns({}).runs.map((run) => run.id).sort()).toEqual([
+      'run-a',
+      'run-manual',
+      'run-next-slot',
+    ].sort());
+
+    first.close();
+    second.close();
+  });
+
+  it('adds slot occupancy to databases created before slot_at existed', () => {
+    const dbPath = createTempDbPath();
+    const Database = require('better-sqlite3');
+    const legacy = new Database(dbPath);
+    legacy.exec(`
+      CREATE TABLE scheduled_task_run (
+        run_id TEXT PRIMARY KEY NOT NULL,
+        project_id TEXT NOT NULL,
+        task_id TEXT NOT NULL,
+        task_name TEXT NOT NULL,
+        trigger TEXT NOT NULL,
+        status TEXT NOT NULL,
+        session_id TEXT,
+        directory TEXT,
+        error TEXT,
+        started_at INTEGER NOT NULL,
+        finished_at INTEGER,
+        duration_ms INTEGER
+      );
+    `);
+    legacy.prepare(`
+      INSERT INTO scheduled_task_run (
+        run_id, project_id, task_id, task_name, trigger, status,
+        session_id, directory, error, started_at, finished_at, duration_ms
+      ) VALUES ('legacy-run', 'project-a', 'task-1', 'Morning Sync', 'scheduled',
+        'success', NULL, '/tmp/project-a', NULL, 50, 60, 10)
+    `).run();
+    legacy.close();
+
+    const store = createScheduledTaskRunHistoryStore({ dbPath });
+    expect(store.listRuns({}).runs).toHaveLength(1);
+    startSample(store, { id: 'run-a', slotAt: 1_700_000_000_000 });
+    expect(() => startSample(store, { id: 'run-b', slotAt: 1_700_000_000_000 })).toThrow(
+      /already claimed/,
+    );
+    expect(store.listRuns({}).runs.map((run) => run.id)).toEqual(['run-a', 'legacy-run']);
+    store.close();
+  });
 });

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

@@ -3,6 +3,7 @@ import { createOpencodeClient } from '@opencode-ai/sdk/v2';
 import { DateTime } from 'luxon';
 import parser from 'cron-parser';
 import { expandSnippets } from '../opencode/snippets.js';
+import { SCHEDULED_SLOT_CLAIMED_CODE } from './run-history-store.js';
 
 const DEFAULT_GLOBAL_CONCURRENCY = 4;
 const DEFAULT_PROJECT_CONCURRENCY = 2;
@@ -535,7 +536,7 @@ export const createScheduledTasksRuntime = (deps) => {
       if (!task || !task.enabled) {
         return;
       }
-      queueTaskRun(projectID, taskID, 'scheduled');
+      queueTaskRun(projectID, taskID, 'scheduled', nextRunAt);
       pumpQueue();
     }, boundedDelay);
 
@@ -669,13 +670,13 @@ export const createScheduledTasksRuntime = (deps) => {
     }
   };
 
-  const queueTaskRun = (projectID, taskID, reason) => {
+  const queueTaskRun = (projectID, taskID, reason, slotAt) => {
     const taskKey = buildTaskKey(projectID, taskID);
     if (queuedTaskKeys.has(taskKey) || runningTaskKeys.has(taskKey)) {
       return;
     }
     queuedTaskKeys.add(taskKey);
-    queue.push({ projectID, taskID, reason });
+    queue.push({ projectID, taskID, reason, slotAt });
   };
 
   const canRunTask = (projectID) => {
@@ -1231,7 +1232,7 @@ export const createScheduledTasksRuntime = (deps) => {
     }
   };
 
-  const runTask = async (projectID, taskID, reason) => {
+  const runTask = async (projectID, taskID, reason, slotAt) => {
     const taskMap = tasksByProject.get(projectID);
     const task = taskMap?.get(taskID);
     if (!task || !task.enabled) {
@@ -1264,6 +1265,9 @@ export const createScheduledTasksRuntime = (deps) => {
       if (runHistoryStore && typeof runHistoryStore.startRun === 'function') {
         try {
           runID = crypto.randomUUID();
+          const resolvedSlotAt = reason === 'scheduled' && Number.isFinite(slotAt)
+            ? Math.trunc(slotAt)
+            : undefined;
           runHistoryStore.startRun({
             id: runID,
             projectId: projectID,
@@ -1272,8 +1276,20 @@ export const createScheduledTasksRuntime = (deps) => {
             trigger: reason === 'manual' ? 'manual' : 'scheduled',
             directory: projectPath,
             startedAt: runStartedAt,
+            ...(resolvedSlotAt !== undefined ? { slotAt: resolvedSlotAt } : {}),
           });
         } catch (error) {
+          if (error?.code === SCHEDULED_SLOT_CLAIMED_CODE) {
+            const nextRunAt = computeNextRunAt(task, Date.now());
+            if (task.enabled && Number.isFinite(nextRunAt)) {
+              scheduleTask(projectID, taskID, nextRunAt);
+            }
+            logger.info?.('[ScheduledTasks] skipped duplicate scheduled slot', {
+              projectID,
+              taskID,
+            });
+            return { ok: false, skipped: true };
+          }
           errorMessage = safeErrorMessage(error);
           runID = null;
           logger.warn?.('[ScheduledTasks] failed to start run history', {
@@ -1547,7 +1563,7 @@ export const createScheduledTasksRuntime = (deps) => {
       queuedTaskKeys.delete(taskKey);
       consumed = true;
 
-      void runTask(item.projectID, item.taskID, item.reason).finally(() => {
+      void runTask(item.projectID, item.taskID, item.reason, item.slotAt).finally(() => {
         pumpQueue();
       });
     }