atris 3.12.1 → 3.14.0

package/commands/visualize.js

@@ -1,20 +1,24 @@
 const fs = require('fs');
 const path = require('path');
+const { spawnSync } = require('child_process');
 const { getLogPath } = require('../lib/journal');
+const { ensureValidCredentials } = require('../utils/auth');
+const { apiRequestJson } = require('../utils/api');
+const { loadConfig } = require('../utils/config');
 
-function visualizeAtris() {
-  const { logFile, dateFormatted } = getLogPath();
+const DEFAULT_MODEL = 'gpt-image-2';
+const DEFAULT_SIZE = '1536x1024';
+const DEFAULT_QUALITY = 'high';
+
+function legacyVisualizeInbox() {
+  const { logFile } = getLogPath();
 
-  // Check if log exists
   if (!fs.existsSync(logFile)) {
     console.log('✗ No journal entry for today. Run "atris log" to create one.');
     process.exit(1);
   }
 
-  // Read the log file
   const logContent = fs.readFileSync(logFile, 'utf8');
-
-  // Extract Inbox section
   const inboxMatch = logContent.match(/## Inbox\n([\s\S]*?)(?=\n##|$)/);
   if (!inboxMatch || !inboxMatch[1].trim()) {
     console.log('✗ No items in Inbox. Add ideas to your journal first.');
@@ -35,7 +39,6 @@ function visualizeAtris() {
     process.exit(1);
   }
 
-  // Display visualization template
   console.log('');
   console.log('┌─────────────────────────────────────────────────────────────┐');
   console.log('│ Atris Visualize — Break Down & Approval Gate                │');
@@ -68,7 +71,320 @@ function visualizeAtris() {
   console.log('');
 }
 
+function parseVisualizeArgs(args = []) {
+  const options = {
+    model: DEFAULT_MODEL,
+    size: DEFAULT_SIZE,
+    quality: DEFAULT_QUALITY,
+    outputFormat: 'png',
+    dryRun: false,
+    open: false,
+    timeoutMs: 180000,
+  };
+  const promptParts = [];
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--') {
+      promptParts.push(...args.slice(i + 1));
+      break;
+    }
+    if (arg === '--help' || arg === '-h') options.help = true;
+    else if (arg === '--dry-run') options.dryRun = true;
+    else if (arg === '--open') options.open = true;
+    else if (arg === '--no-open') options.open = false;
+    else if (arg === '--raw') options.raw = true;
+    else if (arg === '--agent' && args[i + 1]) options.agentId = args[++i];
+    else if (arg.startsWith('--agent=')) options.agentId = arg.slice('--agent='.length);
+    else if (arg === '--model' && args[i + 1]) options.model = args[++i];
+    else if (arg.startsWith('--model=')) options.model = arg.slice('--model='.length);
+    else if (arg === '--size' && args[i + 1]) options.size = args[++i];
+    else if (arg.startsWith('--size=')) options.size = arg.slice('--size='.length);
+    else if (arg === '--quality' && args[i + 1]) options.quality = args[++i];
+    else if (arg.startsWith('--quality=')) options.quality = arg.slice('--quality='.length);
+    else if (arg === '--out' && args[i + 1]) options.out = args[++i];
+    else if (arg.startsWith('--out=')) options.out = arg.slice('--out='.length);
+    else if (arg === '--timeout' && args[i + 1]) options.timeoutMs = Number(args[++i]) * 1000;
+    else if (arg.startsWith('--timeout=')) options.timeoutMs = Number(arg.slice('--timeout='.length)) * 1000;
+    else if (arg === '--format' && args[i + 1]) options.outputFormat = args[++i];
+    else if (arg.startsWith('--format=')) options.outputFormat = arg.slice('--format='.length);
+    else promptParts.push(arg);
+  }
+
+  return { prompt: promptParts.join(' ').trim(), options };
+}
+
+function showVisualizeHelp() {
+  console.log('');
+  console.log('Usage: atris visualize <prompt> [options]');
+  console.log('');
+  console.log('Generate a Slack/deck-ready business visual from workspace context.');
+  console.log('');
+  console.log('Options:');
+  console.log('  --model <name>     Image model (default: gpt-image-2)');
+  console.log('  --size <WxH>       Output size (default: 1536x1024)');
+  console.log('  --quality <level>  Quality (default: high)');
+  console.log('  --out <path>       Save path (default: atris/reports/visuals/<slug>.png)');
+  console.log('  --agent <id>       Agent id for backend image endpoint');
+  console.log('  --dry-run          Print generated prompt without calling the backend');
+  console.log('  --open             Open the saved PNG after generation');
+  console.log('  --raw              Send your prompt as-is, without workspace prompt shaping');
+  console.log('');
+  console.log('No prompt keeps the legacy inbox visualization helper.');
+  console.log('');
+}
+
+function readTextIfExists(filePath, maxChars) {
+  try {
+    if (!fs.existsSync(filePath)) return '';
+    return fs.readFileSync(filePath, 'utf8').slice(0, maxChars);
+  } catch {
+    return '';
+  }
+}
+
+function readBusinessMeta(cwd = process.cwd()) {
+  const businessPath = path.join(cwd, '.atris', 'business.json');
+  try {
+    if (!fs.existsSync(businessPath)) return {};
+    return JSON.parse(fs.readFileSync(businessPath, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function findRelevantContextFiles(cwd, prompt) {
+  const roots = [
+    path.join(cwd, 'atris', 'context'),
+    path.join(cwd, 'atris', 'wiki'),
+  ];
+  const words = new Set(
+    prompt.toLowerCase().split(/[^a-z0-9]+/).filter(w => w.length >= 4)
+  );
+  const files = [];
+
+  function walk(dir) {
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.isFile() && entry.name.endsWith('.md')) files.push(full);
+    }
+  }
+
+  roots.forEach(walk);
+  return files
+    .map(file => {
+      const rel = path.relative(cwd, file);
+      const haystack = rel.toLowerCase();
+      let score = 0;
+      for (const word of words) {
+        if (haystack.includes(word)) score += 3;
+      }
+      const body = readTextIfExists(file, 1200).toLowerCase();
+      for (const word of words) {
+        if (body.includes(word)) score += 1;
+      }
+      return { file, rel, score };
+    })
+    .filter(item => item.score > 0)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, 4);
+}
+
+function collectWorkspaceContext(prompt, cwd = process.cwd()) {
+  const business = readBusinessMeta(cwd);
+  const chunks = [];
+  if (business.name || business.slug) {
+    chunks.push(`Workspace: ${business.name || business.slug} (${business.slug || 'no-slug'})`);
+  }
+
+  const mapSnippet = readTextIfExists(path.join(cwd, 'atris', 'MAP.md'), 1400);
+  if (mapSnippet) chunks.push(`MAP excerpt:\n${mapSnippet}`);
+
+  const todoSnippet = readTextIfExists(path.join(cwd, 'atris', 'TODO.md'), 1000);
+  if (todoSnippet) chunks.push(`TODO excerpt:\n${todoSnippet}`);
+
+  const relevant = findRelevantContextFiles(cwd, prompt);
+  for (const item of relevant) {
+    chunks.push(`${item.rel}:\n${readTextIfExists(item.file, 900)}`);
+  }
+
+  return chunks.join('\n\n---\n\n').slice(0, 6000);
+}
+
+function classifyArtifact(prompt) {
+  const p = prompt.toLowerCase();
+  if (/security|compliance|soc2|soc 2|questionnaire|risk|posture/.test(p)) return 'security posture';
+  if (/wbr|weekly|metric|metrics|revenue|p&l|pnl|forecast|dashboard/.test(p)) return 'metric story';
+  if (/onboard|setup|connect|workflow|process|flow|steps|how to/.test(p)) return 'workflow';
+  if (/architecture|system|infra|stack|api|database|service/.test(p)) return 'architecture';
+  if (/compare|comparison|versus|\bvs\b|tradeoff/.test(p)) return 'comparison';
+  if (/status|update|recap|progress|roadmap/.test(p)) return 'status update';
+  return 'business explainer';
+}
+
+function slugify(input) {
+  return String(input || 'visual')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 54) || 'visual';
+}
+
+function defaultOutputPath(prompt, cwd = process.cwd()) {
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+  const visualsDir = fs.existsSync(path.join(cwd, 'atris'))
+    ? path.join(cwd, 'atris', 'reports', 'visuals')
+    : path.join(cwd, 'visuals');
+  return path.join(visualsDir, `${slugify(prompt)}-${stamp}.png`);
+}
+
+function resolveOutputPath(out, prompt, cwd = process.cwd()) {
+  if (!out) return defaultOutputPath(prompt, cwd);
+  return path.isAbsolute(out) ? out : path.join(cwd, out);
+}
+
+function buildImagePrompt(userPrompt, options = {}, cwd = process.cwd()) {
+  if (options.raw) return userPrompt;
+
+  const artifactType = classifyArtifact(userPrompt);
+  const context = collectWorkspaceContext(userPrompt, cwd);
+  const contextBlock = context ? `\nWorkspace context to respect:\n${context}\n` : '';
+
+  return `Use case: productivity-visual
+Asset type: Slack-shareable and deck-ready business artifact
+Artifact type: ${artifactType}
+Primary request: ${userPrompt}
+${contextBlock}
+Design requirements:
+- Create a polished, modern SaaS-style visual on a clean light background.
+- Use business-appropriate typography, generous spacing, and a restrained palette.
+- Make the visual useful at Slack preview size: large labels, short text, no tiny paragraphs.
+- Prefer a clear structure: flow, comparison, architecture diagram, metric story, or status map depending on the request.
+- If rendering text, keep it concise and accurate; do not invent unsupported names, numbers, claims, or logos.
+- Do not use real third-party logos unless the user explicitly asks.
+- Avoid decorative stock-art scenes. The output should feel like a usable work artifact.
+- Include enough visual hierarchy that a busy operator can understand it in 5 seconds.
+`;
+}
+
+async function resolveAgentId(token, explicitAgentId) {
+  if (explicitAgentId) return { id: explicitAgentId, label: explicitAgentId };
+
+  const agentsResult = await apiRequestJson('/agent/my-agents', { method: 'GET', token });
+  const agents = agentsResult.data?.my_agents || agentsResult.data?.agents || [];
+  const activeAgents = agents.filter(agent => agent.status !== 'inactive' && agent.id);
+  const agentById = new Map(activeAgents.map(agent => [agent.id, agent]));
+  const fromAccessible = (agentId, fallbackLabel) => {
+    if (!agentId || !agentById.has(agentId)) return null;
+    const agent = agentById.get(agentId);
+    return { id: agent.id, label: agent.name || fallbackLabel || agent.id };
+  };
+
+  const config = loadConfig();
+  const configAgent = fromAccessible(config.agent_id, config.agent_name);
+  if (configAgent) return configAgent;
+
+  const business = readBusinessMeta();
+  const localBusinessAgent = fromAccessible(business.agent_id, business.agent_name);
+  if (localBusinessAgent) return localBusinessAgent;
+
+  if (business.slug) {
+    const list = await apiRequestJson('/business/', { method: 'GET', token });
+    const businesses = Array.isArray(list.data) ? list.data : [];
+    const match = businesses.find(b => b.slug === business.slug || b.name === business.name);
+    const agentId = match?.agent_id || match?.default_agent_id || match?.agent?.id;
+    const businessAgent = fromAccessible(agentId, match?.agent_name || match?.agent?.name);
+    if (businessAgent) return businessAgent;
+  }
+
+  if (activeAgents.length === 1) return { id: activeAgents[0].id, label: activeAgents[0].name || activeAgents[0].id };
+  if (activeAgents.length > 1) return { id: activeAgents[0].id, label: activeAgents[0].name || activeAgents[0].id };
+
+  throw new Error('No agent found. Run "atris agent" or pass --agent <agent_id>.');
+}
+
+function writeImageFile(base64Image, outputPath) {
+  const clean = String(base64Image || '').replace(/^data:image\/[a-zA-Z0-9.+-]+;base64,/, '');
+  if (!clean) throw new Error('Backend returned no image data.');
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, Buffer.from(clean, 'base64'));
+}
+
+function maybeOpenImage(outputPath) {
+  if (process.platform === 'darwin') spawnSync('open', [outputPath], { stdio: 'ignore' });
+  else if (process.platform === 'win32') spawnSync('cmd', ['/c', 'start', '', outputPath], { stdio: 'ignore' });
+  else spawnSync('xdg-open', [outputPath], { stdio: 'ignore' });
+}
+
+async function generateVisual(prompt, options = {}) {
+  const outputPath = resolveOutputPath(options.out, prompt);
+  const imagePrompt = buildImagePrompt(prompt, options);
+
+  if (options.dryRun) {
+    console.log('Atris Visualize dry run');
+    console.log(`Model:  ${options.model}`);
+    console.log(`Size:   ${options.size}`);
+    console.log(`Output: ${outputPath}`);
+    console.log('');
+    console.log(imagePrompt.trim());
+    return { outputPath, imagePrompt, dryRun: true };
+  }
+
+  const ensured = await ensureValidCredentials(apiRequestJson);
+  const creds = ensured.error ? null : ensured.credentials;
+  if (!creds?.token) {
+    const detail = ensured.detail || ensured.error;
+    throw new Error(detail ? `Authentication failed: ${detail}. Run "atris login".` : 'Not logged in. Run "atris login".');
+  }
+
+  const agent = await resolveAgentId(creds.token, options.agentId);
+  console.log(`Generating visual with ${options.model} via agent ${agent.label}...`);
+
+  const result = await apiRequestJson(`/agent/${agent.id}/image/generate`, {
+    method: 'POST',
+    token: creds.token,
+    timeoutMs: options.timeoutMs,
+    body: {
+      prompt: imagePrompt,
+      n: 1,
+      size: options.size,
+      model: options.model,
+      quality: options.quality,
+      output_format: options.outputFormat,
+    },
+  });
+
+  if (!result.ok) {
+    throw new Error(`Image generation failed (${result.status}): ${result.error || result.text || 'unknown error'}`);
+  }
+
+  const image = result.data?.images?.[0];
+  writeImageFile(image, outputPath);
+  console.log(`Saved: ${outputPath}`);
+  if (options.open) maybeOpenImage(outputPath);
+  return { outputPath, imagePrompt, model: result.data?.model_used || options.model };
+}
+
+async function visualizeAtris(args = process.argv.slice(3)) {
+  const { prompt, options } = parseVisualizeArgs(args);
+  if (options.help) {
+    showVisualizeHelp();
+    return;
+  }
+  if (!prompt) {
+    legacyVisualizeInbox();
+    return;
+  }
+  await generateVisual(prompt, options);
+}
 
 module.exports = {
-  visualizeAtris
+  visualizeAtris,
+  parseVisualizeArgs,
+  buildImagePrompt,
+  classifyArtifact,
+  resolveOutputPath,
+  generateVisual,
 };

package/lib/task-db.js

@@ -0,0 +1,288 @@
+// SQLite-backed task store. node:sqlite (built-in, v22+).
+// Local state layer for `atris task`. TODO.md stays the human-readable
+// project board; this store gives agents atomic claims and a compact sync row.
+//
+// Path: ~/.atris/tasks.db (gitignored, never blobbed). Per-workspace scope via
+// workspace_root column. Rows survive across machines only when explicitly
+// synced (out of scope for tick 1).
+
+'use strict';
+
+// node:sqlite emits an ExperimentalWarning. Suppress only that exact class by
+// monkey-patching process.emit at this narrow filter — other warnings (and
+// any pre-existing listeners installed by host code) are untouched.
+{
+  const originalEmit = process.emit;
+  process.emit = function patchedEmit(name, data, ...args) {
+    if (name === 'warning' && data && data.name === 'ExperimentalWarning'
+        && /SQLite/i.test(data.message || '')) {
+      return false;
+    }
+    return originalEmit.apply(process, [name, data, ...args]);
+  };
+}
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+const { DatabaseSync } = require('node:sqlite');
+
+const DEFAULT_DB_PATH = path.join(os.homedir(), '.atris', 'tasks.db');
+
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS tasks (
+  id              TEXT PRIMARY KEY,
+  title           TEXT NOT NULL,
+  status          TEXT NOT NULL DEFAULT 'open',
+  tag             TEXT,
+  workspace_root  TEXT NOT NULL,
+  source_key      TEXT,
+  claimed_by      TEXT,
+  claimed_at      INTEGER,
+  created_at      INTEGER NOT NULL,
+  updated_at      INTEGER NOT NULL,
+  done_at         INTEGER,
+  metadata        TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_tasks_status      ON tasks(status);
+CREATE INDEX IF NOT EXISTS idx_tasks_workspace   ON tasks(workspace_root);
+CREATE INDEX IF NOT EXISTS idx_tasks_claimed_by  ON tasks(claimed_by);
+CREATE UNIQUE INDEX IF NOT EXISTS uq_tasks_source ON tasks(workspace_root, source_key)
+  WHERE source_key IS NOT NULL;
+`;
+
+let _cachedDb = null;
+let _cachedPath = null;
+
+function getDbPath() {
+  return process.env.ATRIS_TASKS_DB || DEFAULT_DB_PATH;
+}
+
+function open(dbPath) {
+  const target = dbPath || getDbPath();
+  if (_cachedDb && _cachedPath === target) return _cachedDb;
+  const dir = path.dirname(target);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  const db = new DatabaseSync(target);
+  // Concurrency: WAL gives readers + one writer concurrency; busy_timeout
+  // makes contended writers wait instead of returning SQLITE_BUSY at the
+  // C library level. We additionally wrap the setup PRAGMAs + DDL in our
+  // own retry — under heavy spawn-storm contention, node:sqlite leaks
+  // SQLITE_BUSY past the busy_timeout for `db.exec()` calls.
+  withBusyRetry(() => db.exec('PRAGMA journal_mode = WAL'));
+  withBusyRetry(() => db.exec('PRAGMA busy_timeout = 30000'));
+  withBusyRetry(() => db.exec('PRAGMA foreign_keys = ON'));
+  withBusyRetry(() => db.exec(SCHEMA));
+  // Schema version. Bump at every additive migration; tick 1 ships at v1.
+  // Future migrations read this and apply diffs idempotently.
+  withBusyRetry(() => db.exec('PRAGMA user_version = 1'));
+  _cachedDb = db;
+  _cachedPath = target;
+  return db;
+}
+
+function close() {
+  if (_cachedDb) {
+    try { _cachedDb.close(); } catch (_) {}
+    _cachedDb = null;
+    _cachedPath = null;
+  }
+}
+
+// 26-char ULID-ish (sortable by time prefix). Crockford-safe alphabet.
+const ULID_ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+function newId() {
+  const ts = Date.now();
+  let head = '';
+  let n = ts;
+  for (let i = 0; i < 10; i++) {
+    head = ULID_ALPHABET[n % 32] + head;
+    n = Math.floor(n / 32);
+  }
+  let tail = '';
+  const rand = crypto.randomBytes(10);
+  for (let i = 0; i < 16; i++) tail += ULID_ALPHABET[rand[i % rand.length] % 32];
+  return head + tail;
+}
+
+// Walk up from `start` to find the canonical workspace root. We check for
+// .git, then atris/, then .atris/. If none found, fall back to `start`. This
+// makes `atris task add` from a subdirectory write the same workspace_root
+// as parseTodo() reads from the project's atris/TODO.md.
+function findWorkspaceRoot(start) {
+  let cur = path.resolve(start || process.cwd());
+  // Cap the walk at 32 levels to avoid pathological symlink loops.
+  for (let i = 0; i < 32; i++) {
+    if (fs.existsSync(path.join(cur, '.git'))) return cur;
+    if (fs.existsSync(path.join(cur, 'atris'))) return cur;
+    if (fs.existsSync(path.join(cur, '.atris'))) return cur;
+    const parent = path.dirname(cur);
+    if (parent === cur) break;
+    cur = parent;
+  }
+  return path.resolve(start || process.cwd());
+}
+
+function workspaceRoot(cwd) {
+  // Normalize symlinks (notably macOS /tmp → /private/tmp), then walk up to
+  // the project root so subdirs and the repo root agree on the same key.
+  let target = cwd || process.cwd();
+  try { target = fs.realpathSync(target); } catch {}
+  return findWorkspaceRoot(target);
+}
+
+function normalizeTitle(t) {
+  return String(t || '').toLowerCase().trim().replace(/\s+/g, ' ').replace(/[^a-z0-9 ]/g, '');
+}
+
+function sourceKey(sourceFile, title) {
+  if (!sourceFile) return null;
+  // Realpath the source file so symlinked / relative imports collapse to the
+  // same key. Falls back to input string when the path doesn't resolve.
+  let canonical = sourceFile;
+  try { canonical = fs.realpathSync(sourceFile); } catch {}
+  const h = crypto.createHash('sha1');
+  h.update(`${canonical}${normalizeTitle(title)}`);
+  return h.digest('hex');
+}
+
+function addTask(db, { title, tag, workspaceRoot: ws, sourceKey: sk, metadata, status, claimedBy }) {
+  if (!title || !String(title).trim()) throw new Error('title required');
+  const now = Date.now();
+  const id = newId();
+  const taskStatus = ['open', 'claimed', 'done', 'failed'].includes(status) ? status : 'open';
+  const claimedAt = taskStatus === 'claimed' ? now : null;
+  // Idempotent on (workspace_root, source_key) when source_key supplied.
+  if (sk) {
+    const existing = db.prepare(
+      'SELECT id FROM tasks WHERE workspace_root = ? AND source_key = ?'
+    ).get(ws, sk);
+    if (existing) return { id: existing.id, inserted: false };
+  }
+  withBusyRetry(() => db.prepare(`
+    INSERT INTO tasks (id, title, status, tag, workspace_root, source_key,
+                       claimed_by, claimed_at, created_at, updated_at, metadata)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    id,
+    String(title).trim(),
+    taskStatus,
+    tag || null,
+    ws,
+    sk || null,
+    taskStatus === 'claimed' ? (claimedBy || null) : null,
+    claimedAt,
+    now,
+    now,
+    metadata ? JSON.stringify(metadata) : null,
+  ));
+  return { id, inserted: true };
+}
+
+function listTasks(db, { workspaceRoot: ws, status, claimedBy, limit }) {
+  const where = [];
+  const args = [];
+  if (ws) { where.push('workspace_root = ?'); args.push(ws); }
+  if (status) { where.push('status = ?'); args.push(status); }
+  if (claimedBy) { where.push('claimed_by = ?'); args.push(claimedBy); }
+  const sql = `
+    SELECT id, title, status, tag, workspace_root, source_key, claimed_by, claimed_at, created_at, updated_at, done_at, metadata
+    FROM tasks
+    ${where.length ? 'WHERE ' + where.join(' AND ') : ''}
+    ORDER BY
+      CASE status WHEN 'open' THEN 0 WHEN 'claimed' THEN 1 WHEN 'failed' THEN 2 WHEN 'done' THEN 3 ELSE 4 END,
+      created_at DESC
+    ${limit ? 'LIMIT ' + Number(limit) : ''}
+  `;
+  return db.prepare(sql).all(...args).map(r => ({
+    ...r,
+    metadata: r.metadata ? safeJSON(r.metadata) : null,
+  }));
+}
+
+// Atomic claim. Returns { claimed: true, row } only if THIS call won the row.
+// Race-safe via single UPDATE with WHERE status='open' guard. SQLite serializes
+// writes; busy_timeout absorbs contention. Caller must check `.claimed`.
+function claimTask(db, { id, claimedBy }) {
+  if (!id) throw new Error('id required');
+  if (!claimedBy) throw new Error('claimedBy required');
+  const now = Date.now();
+  const stmt = db.prepare(`
+    UPDATE tasks
+       SET status = 'claimed',
+           claimed_by = ?,
+           claimed_at = ?,
+           updated_at = ?
+     WHERE id = ?
+       AND status = 'open'
+  `);
+  const result = withBusyRetry(() => stmt.run(claimedBy, now, now, id));
+  if (result.changes === 1) {
+    const row = db.prepare('SELECT * FROM tasks WHERE id = ?').get(id);
+    return { claimed: true, row: { ...row, metadata: row.metadata ? safeJSON(row.metadata) : null } };
+  }
+  // Either id doesn't exist or status != 'open'. Tell the caller which.
+  const row = db.prepare('SELECT id, status, claimed_by FROM tasks WHERE id = ?').get(id);
+  if (!row) return { claimed: false, reason: 'not_found' };
+  return { claimed: false, reason: 'already_' + row.status, claimed_by: row.claimed_by };
+}
+
+function doneTask(db, { id, status }) {
+  if (!id) throw new Error('id required');
+  const final = status || 'done';
+  if (!['done', 'failed'].includes(final)) throw new Error('status must be done|failed');
+  const now = Date.now();
+  const result = withBusyRetry(() => db.prepare(`
+    UPDATE tasks
+       SET status = ?, done_at = ?, updated_at = ?
+     WHERE id = ?
+       AND status IN ('open', 'claimed')
+  `).run(final, now, now, id));
+  return { updated: result.changes === 1 };
+}
+
+function safeJSON(s) {
+  try { return JSON.parse(s); } catch { return null; }
+}
+
+// Wrap a write op so SQLITE_BUSY (concurrent writers from other processes)
+// retries with exponential backoff. busy_timeout pragma alone leaks busy
+// errors under spawn-storm contention with node:sqlite (~3% raw lock rate
+// observed at 1000 attempts). Total wait ≤ ~6s; well above realistic
+// contention windows for our agent fleet.
+function withBusyRetry(fn, attempts = 8) {
+  let delay = 5;
+  let lastErr;
+  for (let i = 0; i < attempts; i++) {
+    try { return fn(); }
+    catch (e) {
+      lastErr = e;
+      const msg = String(e && e.message || '');
+      const code = e && (e.code || e.errcode);
+      const busy = /SQLITE_BUSY|database is locked/i.test(msg) || code === 'SQLITE_BUSY' || code === 5;
+      if (!busy) throw e;
+      // Sleep synchronously — node:sqlite is sync; matches the rest of the API
+      const end = Date.now() + delay + Math.floor(Math.random() * delay);
+      while (Date.now() < end) {} // tight loop is fine, delay is small
+      delay = Math.min(delay * 2, 500);
+    }
+  }
+  throw lastErr;
+}
+
+module.exports = {
+  open,
+  close,
+  getDbPath,
+  workspaceRoot,
+  sourceKey,
+  normalizeTitle,
+  addTask,
+  listTasks,
+  claimTask,
+  doneTask,
+  newId,
+  // Test surface
+  _SCHEMA: SCHEMA,
+};