@worca/app 0.0.1

package/src/core/skills.mjs

@@ -0,0 +1,210 @@
+// src/core/skills.mjs
+// Declared-skill resolution, validation, and worktree injection.
+//
+// Worca CC agents may declare `requiresSkills: string[]` in their meta sidecar.
+// A skill is only reachable by the headless `claude -p` child when it sits on a
+// scan path: `<cwd>/.claude/skills/<name>/` or `~/.claude/skills/<name>/`.
+// Worca CC's own repo `skills/` dir is on NEITHER, so a bundled skill must be
+// COPIED into the run's worktree before any node runs. This module:
+//   - resolveSkill()          pure: where does a skill live? (bundle|global|project|none)
+//   - collectRequiredSkills() pure: union of requiresSkills across the plan's agents
+//   - validateSkills()        gate: throw a structured abort if any are unresolvable
+//   - injectSkills()          side-effect: copy bundle/plugin skills into given target(s)
+
+import { existsSync } from 'node:fs';
+import { cp } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { readPluginsLock, pluginCurrentDir } from './plugins-lock.mjs'; // plugin skill roots (Task 2)
+
+/**
+ * Ordered plugin skill roots for resolveSkill's ctx.pluginDirs: every ENABLED
+ * plugin's current/skills dir that exists, lexicographic by plugin name (the
+ * same determinism as pluginAgentLayers). try/catch mirrors userAgentsDir():
+ * no resolvable home / no lock => [] — zero plugins is byte-identical to today.
+ * @returns {Array<{plugin: string, dir: string}>}
+ */
+export function pluginSkillDirs() {
+  try {
+    const lock = readPluginsLock();
+    return Object.keys(lock)
+      .sort()
+      .filter((name) => lock[name] && lock[name].enabled !== false)
+      .map((name) => ({ plugin: name, dir: join(pluginCurrentDir(name), 'skills') }))
+      .filter(({ dir }) => existsSync(dir));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * S2 (path-segment guard). A skill name is used as a PATH SEGMENT at both mount
+ * sites — `injectSkills`' `join(t, '.claude', 'skills', skill)` and
+ * `assembleSkills`' `join(target, effective)` (run-context.mjs) — and it arrives
+ * from author-controlled agent frontmatter (`requiresSkills`) or, on resume, from a
+ * disk-read `run.json.skillResolutions`. Unvalidated, `../../x` turns either mount
+ * into a write-anywhere primitive.
+ *
+ * The standard is `createWorktree`'s, verbatim (worktree.mjs S2/checkoutName): the
+ * conservative `[A-Za-z0-9._-]+` class plus the two dot cases the class alone still
+ * admits. Callers differ only in POSTURE — a declared skill is rejected LOUDLY at
+ * preflight (validateSkills), a manifest entry is SKIPPED with a warning (§8.20:
+ * a corrupt run.json must not make a paused run unresumable).
+ * @param {unknown} name
+ * @returns {boolean}
+ */
+export function isValidSkillName(name) {
+  return typeof name === 'string' && /^[A-Za-z0-9._-]+$/.test(name) && name !== '.' && name !== '..';
+}
+
+/**
+ * Resolve a skill name to its source, in priority order:
+ *   0. plugin (OWNER)  — <plugins>/<name>/current/skills/<skill>/SKILL.md, only for
+ *                        the plugin named by ctx.origin ('plugin:<name>' — the
+ *                        requesting agent's registry origin)
+ *   1. bundle  — <repoRoot>/skills/<name>/SKILL.md     (injectSkills copies this into the worktree)
+ *   2. global  — <homeDir>/.claude/skills/<name>/SKILL.md   (already on the scan path)
+ *   3. project — <projectDir>/.claude/skills/<name>/SKILL.md (committed; already on the scan path)
+ *   4. plugin (others) — every remaining ctx.pluginDirs entry, in given order
+ *   5. none    — unresolvable
+ * pluginDirs entries are { plugin, dir } (pluginSkillDirs()); a plain-string dir is
+ * tolerated (never owner, source 'plugin'). pluginDirs=[] + origin=null keeps the
+ * legacy 3-path chain and 3-entry `searched` byte-identical. Pure: existsSync only.
+ * @param {string} name
+ * @param {{repoRoot:string, projectDir:string, homeDir?:string,
+ *          pluginDirs?:Array<{plugin:string,dir:string}|string>, origin?:string|null}} ctx
+ * @returns {{source:string|null, path:string|null, searched:string[]}}
+ */
+export function resolveSkill(name, { repoRoot, projectDir, homeDir = homedir(), pluginDirs = [], origin = null }) {
+  const dirs = (Array.isArray(pluginDirs) ? pluginDirs : [])
+    .map((p) => (typeof p === 'string' ? { plugin: null, dir: p } : p))
+    .filter((p) => p && typeof p.dir === 'string' && p.dir);
+  const ownerName = typeof origin === 'string' && origin.startsWith('plugin:')
+    ? origin.slice('plugin:'.length)
+    : null;
+  const asHit = (p) => ({ source: p.plugin ? `plugin:${p.plugin}` : 'plugin', dir: join(p.dir, name) });
+  const chain = [
+    ...dirs.filter((p) => p.plugin !== null && p.plugin === ownerName).map(asHit), // owner FIRST
+    { source: 'bundle',  dir: join(repoRoot, 'skills', name) },
+    { source: 'global',  dir: join(homeDir, '.claude', 'skills', name) },
+    { source: 'project', dir: join(projectDir, '.claude', 'skills', name) },
+    ...dirs.filter((p) => p.plugin === null || p.plugin !== ownerName).map(asHit), // others LAST
+  ];
+  const searched = chain.map((c) => join(c.dir, 'SKILL.md'));
+  for (let i = 0; i < chain.length; i++) {
+    if (existsSync(searched[i])) return { source: chain[i].source, path: chain[i].dir, searched };
+  }
+  return { source: null, path: null, searched };
+}
+
+/**
+ * Union of `requiresSkills` across the agents that appear in the resolved plan.
+ * Returns one entry per distinct skill with the agent keys that require it (for
+ * error attribution), sorted by skill name.
+ *
+ * `registry` is the plain object returned by loadAgentRegistry (keyed by agent
+ * key); `plan.steps` is Array<Array<node>> and each node has `.key`.
+ * @param {Record<string, {requiresSkills?: string[]}>} registry
+ * @param {{steps?: Array<Array<{key:string}>>}} plan
+ * @returns {Array<{skill:string, requiredBy:string[]}>}
+ */
+export function collectRequiredSkills(registry, plan) {
+  const nodeKeys = new Set();
+  for (const group of plan?.steps || []) for (const node of group) nodeKeys.add(node.key);
+  /** @type {Map<string, Set<string>>} */
+  const bySkill = new Map();
+  for (const key of nodeKeys) {
+    for (const skill of registry?.[key]?.requiresSkills || []) {
+      if (!bySkill.has(skill)) bySkill.set(skill, new Set());
+      bySkill.get(skill).add(key);
+    }
+  }
+  return [...bySkill.keys()].sort().map((skill) => {
+    const requiredBy = [...bySkill.get(skill)].sort();
+    // Owner attribution for plugin-first search: the FIRST (sorted) requiring
+    // agent whose registry meta carries a plugin origin. The key is OMITTED when
+    // none does, so legacy fixtures/deepEqual call sites are byte-identical.
+    const origin = requiredBy
+      .map((k) => registry?.[k]?.origin)
+      .find((o) => typeof o === 'string' && o.startsWith('plugin:'));
+    return origin ? { skill, requiredBy, origin } : { skill, requiredBy };
+  });
+}
+
+/**
+ * Preflight gate. Resolve every required skill; if ANY is unresolvable, throw a
+ * single aggregated error naming each (requiring agent(s), skill, searched paths)
+ * so the user fixes them all at once. On success, return the resolutions keyed by
+ * skill (consumed by injectSkills). Throws BEFORE any node runs; the thrown plain
+ * Error lands in run()'s error branch → run ends with status 'error', message
+ * surfaced.
+ * @param {Array<{skill:string, requiredBy:string[]}>} required
+ * @param {{repoRoot:string, projectDir:string, homeDir?:string}} ctx
+ * @returns {Map<string, {source:string, path:string, requiredBy:string[]}>}
+ */
+export function validateSkills(required, ctx) {
+  const resolved = new Map();
+  const missing = [];
+  const invalid = [];
+  for (const { skill, requiredBy, origin } of required) {
+    // S2 FIRST: a name that cannot be a path segment is never searched, so a
+    // traversal is always reported as a traversal instead of being masked by a
+    // "not found" listing of three joined-and-normalized paths.
+    if (!isValidSkillName(skill)) { invalid.push({ skill, requiredBy }); continue; }
+    const r = resolveSkill(skill, { ...ctx, origin: origin ?? null });
+    if (r.source === null) missing.push({ skill, requiredBy, searched: r.searched });
+    else resolved.set(skill, { source: r.source, path: r.path, requiredBy });
+  }
+  if (invalid.length) {
+    throw new Error(
+      `Preflight failed: ${invalid.length} required skill(s) have an invalid skill name. ` +
+        'A skill name becomes a directory name under `.claude/skills/`, so it may contain only ' +
+        'letters, digits, `.`, `_` and `-`, and may not be `.` or `..`:\n' +
+        invalid
+          .map((m) => `  - ${JSON.stringify(m.skill)} (required by ${m.requiredBy.join(', ')})`)
+          .join('\n'),
+    );
+  }
+  if (missing.length) {
+    const lines = missing.map(
+      (m) =>
+        `  - skill "${m.skill}" (required by ${m.requiredBy.join(', ')}) not found. Searched:\n` +
+        m.searched.map((p) => `      ${p}`).join('\n'),
+    );
+    throw new Error(
+      `Preflight failed: ${missing.length} required skill(s) unavailable. ` +
+        `Bundle them in the worca-cc repo (skills/<name>/) or install under ~/.claude/skills/:\n` +
+        lines.join('\n'),
+    );
+  }
+  return resolved;
+}
+
+/**
+ * Copy each BUNDLE- or PLUGIN-sourced skill into every given target's
+ * .claude/skills/ (global/project skills are already on the scan path — nothing to
+ * copy). Runs ONLY after validateSkills passes. A copy failure rejects, aborting
+ * the run before any node starts (no half-injected skill dir reaches a node).
+ *
+ * `targets` MUST be dirs worca-cc owns — real isolated checkouts (never the main
+ * projectDir) or a run root. The orchestrator guards this before calling (see §5)
+ * so injection cannot pollute the user's working tree. The parameter is generic
+ * because a detached WORKSPACE run mounts once at the run root instead of N
+ * worktrees (§5.6 entry class 3); that call site lives in run-context.mjs, so under
+ * `detached` this function is not the delivery path at all — it stays the byte-
+ * identical LEGACY one (§10 rollback contract).
+ * @param {Map<string, {source:string, path:string}>} resolutions
+ * @param {{targets:string[]}} ctx
+ * @returns {Promise<string[]>} skill names actually injected
+ */
+export async function injectSkills(resolutions, { targets }) {
+  const injected = [];
+  for (const [skill, r] of resolutions) {
+    if (r.source !== 'bundle' && !String(r.source || '').startsWith('plugin:')) continue;
+    for (const t of targets || []) {
+      await cp(r.path, join(t, '.claude', 'skills', skill), { recursive: true });
+    }
+    injected.push(skill);
+  }
+  return injected;
+}

package/src/core/sources.mjs

@@ -0,0 +1,232 @@
+// src/core/sources.mjs
+// The task-source seam (spec §7.3): every way a pipeline acquires its task —
+// inline prompt, markdown file/text, or a plugin task-source connector — resolves
+// through ONE path yielding { promptText, promptFile, sourceMeta }.
+// Feature-off bar: with zero plugins installed, 'prompt'/'markdown' resolution is
+// byte-identical to the old inline prompt||promptFile branching in createPipeline.
+
+import { readFile } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { callSource } from './plugin-shim.mjs';
+import { readPluginsLock, pluginCurrentDir } from './plugins-lock.mjs';
+import { normalizeManifest } from './plugin-manifest.mjs';
+import { getDb } from './db.mjs';
+import { runDirForRow, readStoreMeta } from './artifacts.mjs';
+import { RESULTS_FILE } from './results.mjs';
+import { hasGh, findPrForBranch } from './git-info.mjs';
+
+/** Same resolve-against-projectDir semantics as artifacts.mjs#resolveAgainst. */
+function resolveAgainst(base, p) {
+  return isAbsolute(p) ? p : resolve(base, p);
+}
+
+/**
+ * Every selectable task source: the two built-ins plus one entry per task source
+ * of every ENABLED installed plugin (lexicographic plugin order, manifest order
+ * within a plugin). Broken/missing manifests are skipped — the pane must render.
+ * @returns {Array<{type:string, displayName:string, plugin?:string, sourceId?:string, inputs?:Array}>}
+ */
+export function listTaskSources() {
+  const sources = [
+    { type: 'prompt', displayName: 'Prompt' },
+    { type: 'markdown', displayName: 'Markdown' },
+  ];
+  let lock = {};
+  try { lock = readPluginsLock(); } catch { lock = {}; }
+  for (const name of Object.keys(lock).sort()) {
+    if (lock[name]?.enabled === false) continue;
+    let manifest = null;
+    try {
+      const dir = pluginCurrentDir(name);
+      const norm = normalizeManifest(JSON.parse(readFileSync(join(dir, 'worca-cc-plugin.json'), 'utf8')), { dir });
+      manifest = norm.ok ? norm.manifest : null;
+    } catch { manifest = null; }
+    if (!manifest) continue;
+    for (const ts of manifest.taskSources || []) {
+      sources.push({
+        type: 'plugin',
+        plugin: name,
+        sourceId: ts.id,
+        displayName: ts.displayName || `${name}/${ts.id}`,
+        inputs: ts.inputs || [],
+      });
+    }
+  }
+  return sources;
+}
+
+/** `# title\n\nbody` + a fenced json meta block when the provider bag is non-empty. */
+function taskPromptText(task) {
+  let text = `# ${task.title || task.id}\n\n${task.body || ''}`;
+  if (task.meta && typeof task.meta === 'object' && Object.keys(task.meta).length > 0) {
+    text += `\n\n\`\`\`json meta\n${JSON.stringify(task.meta, null, 2)}\n\`\`\``;
+  }
+  return text;
+}
+
+/**
+ * Resolve a source descriptor to the pipeline's task input.
+ *   { type:'prompt', prompt } | { type:'markdown', promptText?, promptFile? }
+ * | { type:'plugin', plugin, sourceId, taskId, inputs? }
+ * @returns {Promise<{promptText:string, promptFile:string|null,
+ *   sourceMeta:{plugin,sourceId,taskId,url,title}|null}>}
+ */
+export async function resolveTaskInput(source, { projectDir } = {}) {
+  const src = source && typeof source === 'object' ? source : { type: 'prompt', prompt: '' };
+  const type = src.type || 'prompt';
+
+  if (type === 'prompt') {
+    return { promptText: typeof src.prompt === 'string' ? src.prompt : '', promptFile: null, sourceMeta: null };
+  }
+
+  if (type === 'markdown') {
+    if (src.promptFile) {
+      let promptText = '';
+      try {
+        promptText = await readFile(resolveAgainst(projectDir, src.promptFile), 'utf8');
+      } catch {
+        promptText = ''; // exactly the legacy createPipeline catch{} degradation
+      }
+      return { promptText, promptFile: src.promptFile, sourceMeta: null };
+    }
+    return { promptText: typeof src.promptText === 'string' ? src.promptText : '', promptFile: null, sourceMeta: null };
+  }
+
+  if (type === 'plugin') {
+    const task = await callSource({ plugin: src.plugin, sourceId: src.sourceId, op: 'getTask', args: { id: src.taskId } });
+    if (!task) {
+      throw new Error(`task-source ${src.plugin}/${src.sourceId}: task "${src.taskId}" not found`);
+    }
+    return {
+      promptText: taskPromptText(task),
+      promptFile: null,
+      sourceMeta: {
+        plugin: src.plugin,
+        sourceId: src.sourceId,
+        taskId: src.taskId,
+        url: task.url ?? null,
+        title: task.title ?? null,
+      },
+    };
+  }
+
+  throw new Error(`unknown task source type "${type}"`);
+}
+
+// ── result write-back (spec §7.5) ──────────────────────────────────────────────
+
+/** Map a pipeline row status onto the connector reportResult vocabulary (§7.1). */
+function statusToResult(status) {
+  if (status === 'done') return 'completed';
+  if (status === 'error' || status === 'stopped') return 'failed';
+  return 'needs-human'; // paused | interrupted | anything non-terminal (manual retry path)
+}
+
+/** Markdown summary assembled from the persisted results view (results.mjs#assembleResults shape). */
+function buildResultSummary(row, bundle) {
+  const lines = [`### Worca CC run \`${row.id}\` — ${row.status}`];
+  if (row.title) lines.push('', `**${row.title}**`);
+  const s = bundle?.results?.summary; // { filesNew, filesChanged, filesDeleted, linesAdded, linesRemoved, blockingIssues, nitpicks }
+  if (s) {
+    lines.push('', `- Diffstat: ${s.filesChanged ?? 0} changed, ${s.filesNew ?? 0} new, ${s.filesDeleted ?? 0} deleted, +${s.linesAdded ?? 0} / -${s.linesRemoved ?? 0}`);
+    lines.push(`- Review: ${s.blockingIssues ?? 0} blocking, ${s.nitpicks ?? 0} nitpicks`);
+  }
+  if (bundle?.branch) lines.push(`- Branch: \`${bundle.branch}\``); // local branches have no URL — named here, linked below only as a PR
+  const checks = Array.isArray(bundle?.results?.keyThingsToCheck) ? bundle.results.keyThingsToCheck : [];
+  if (checks.length) {
+    lines.push('', 'Key things to check:');
+    for (const c of checks.slice(0, 5)) lines.push(`- [${c.severity}] ${c.title}${c.file ? ` (\`${c.file}\`)` : ''}`);
+  }
+  return lines.join('\n');
+}
+
+/** Tracker-comment links: the PR when the bundle knows one. */
+function buildResultLinks(bundle) {
+  const links = [];
+  if (bundle?.prUrl) links.push({ title: 'Pull request', url: bundle.prUrl });
+  return links;
+}
+
+/**
+ * Report a finished pipeline back to its plugin task source. NEVER throws and
+ * NEVER blocks completion semantics: every failure collapses to { ok:false,
+ * error } for the caller to log/surface. Silent skip ({ ok:true, skipped:true })
+ * for prompt/markdown rows and refs that cannot be parsed.
+ * @param {object} pipelineRow  raw pipelines row (source_type/source_ref/status/title)
+ * @param {{results:object|null, branch:string|null, prUrl:string|null}} resultsBundle
+ * @returns {Promise<{ok:true, skipped?:true} | {ok:false, error:string}>}
+ */
+export async function reportResultForPipeline(pipelineRow, resultsBundle) {
+  try {
+    if ((pipelineRow?.source_type || 'prompt') !== 'plugin') return { ok: true, skipped: true };
+    let ref = null;
+    try { ref = pipelineRow.source_ref ? JSON.parse(pipelineRow.source_ref) : null; } catch { ref = null; }
+    if (!ref?.plugin || !ref?.sourceId || !ref?.taskId) return { ok: true, skipped: true };
+
+    // Capability probe with a TOLERANT DEFAULT. capabilities() is optional in the
+    // connector contract (§7.1: "defaults: writeBack true"): a connector without
+    // the op makes the child answer { ok:false, error:{ kind:'plugin', message:
+    // 'connector does not implement op "capabilities"' } } -> callSource throws
+    // PluginOpError('plugin') -> we default to writeBack:true. Transport errors
+    // (auth/network/timeout/protocol) ALSO default to true — the reportResult
+    // call below is the one that surfaces the real failure to the caller.
+    let writeBack = true;
+    try {
+      const caps = await callSource({ plugin: ref.plugin, sourceId: ref.sourceId, op: 'capabilities', args: {} });
+      if (caps && caps.writeBack === false) writeBack = false;
+    } catch {
+      writeBack = true;
+    }
+    if (!writeBack) return { ok: true, skipped: true };
+
+    await callSource({
+      plugin: ref.plugin,
+      sourceId: ref.sourceId,
+      op: 'reportResult',
+      args: {
+        id: ref.taskId,
+        status: statusToResult(pipelineRow.status),
+        summary: buildResultSummary(pipelineRow, resultsBundle),
+        links: buildResultLinks(resultsBundle),
+      },
+    });
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err?.message || String(err) };
+  }
+}
+
+/**
+ * Load everything write-back needs for one pipeline and report it. Used by the
+ * orchestrator's terminal hook AND (Task 15) the results-view "Report result"
+ * retry endpoint. Skips BEFORE any bundle work for prompt/markdown rows, so
+ * feature-off runs never touch git/gh/results here. NEVER throws.
+ * @param {string} pipelineId
+ */
+export async function retryWriteback(pipelineId) {
+  try {
+    const row = getDb().prepare('SELECT * FROM pipelines WHERE id = ?').get(pipelineId);
+    if (!row) return { ok: false, error: `unknown pipeline "${pipelineId}"` };
+    if ((row.source_type || 'prompt') !== 'plugin') return { ok: true, skipped: true };
+
+    const dir = await runDirForRow(row);
+    let results = null;
+    try { results = JSON.parse(await readFile(join(dir, RESULTS_FILE), 'utf8')); } catch { results = null; }
+    let branch = null;
+    try { branch = row.branch ? (JSON.parse(row.branch)?.feature ?? null) : null; } catch { branch = null; }
+    // PR link, best-effort (same hasGh-gated pattern as artifacts.mjs#rowToHistoryEntry).
+    let prUrl = null;
+    if (branch) {
+      try {
+        const meta = readStoreMeta(row.project_key);
+        if (meta?.path && (await hasGh())) {
+          prUrl = (await findPrForBranch({ projectDir: meta.path, head: branch }))?.url || null;
+        }
+      } catch { prUrl = null; }
+    }
+    return await reportResultForPipeline(row, { results, branch, prUrl });
+  } catch (err) {
+    return { ok: false, error: err?.message || String(err) };
+  }
+}

package/src/core/stats.mjs

@@ -0,0 +1,182 @@
+// src/core/stats.mjs
+// Statistics over ALL pipeline records — archived included, deliberately: the
+// archive exists so these numbers survive history cleanup (spec §6.9). Pure
+// synchronous DB reads; no gh, no git, offline-correct.
+//
+// Attribution: money = cost_ledger by event timestamp (exact); runs, time,
+// and PRs = cohort by started_at (a run belongs to the bucket its start falls
+// in, with its CURRENT status). 'today' differs: its totals count runs whose
+// lifespan [started_at, updated_at] overlaps the day ("active today"), and its
+// hourly bars attribute terminal outcomes to the hour of the terminal write
+// (updated_at). 'all' money/time use the fallback-aware pipelines sums so
+// pre-ledger history still counts.
+
+import { prepare } from './db.mjs';
+import {
+  budgetStatus, costWindowStart, costWindowEnd, allTimeTotals, roundUsd,
+} from './cost-budget.mjs';
+
+const RANGES = ['today', 'week', 'month', 'all'];
+
+function hourStart(d) { return new Date(d.getFullYear(), d.getMonth(), d.getDate(), d.getHours()); }
+function dayStart(d) { return new Date(d.getFullYear(), d.getMonth(), d.getDate()); }
+function monthStart(d) { return new Date(d.getFullYear(), d.getMonth(), 1); }
+
+const TOTALS_SELECT = `
+    SELECT COUNT(*) AS runs,
+      COALESCE(SUM(status = 'done'), 0)                                      AS finished,
+      COALESCE(SUM(status = 'stopped'), 0)                                   AS stopped,
+      COALESCE(SUM(status = 'error'), 0)                                     AS failed,
+      COALESCE(SUM(status IN ('paused','interrupted')), 0)                   AS paused,
+      COALESCE(SUM(status IN ('created','starting','running','pausing')), 0) AS running,
+      COALESCE(SUM(pr_url IS NOT NULL), 0)                                   AS prsOpened,
+      COALESCE(SUM(pr_state = 'MERGED'), 0)                                  AS prsMerged,
+      COALESCE(SUM(CASE WHEN p.total_cost_usd  > 0 THEN p.total_cost_usd  ELSE COALESCE(s.sc, 0) END), 0) AS spend,
+      COALESCE(SUM(CASE WHEN p.total_active_ms > 0 THEN p.total_active_ms ELSE COALESCE(s.sa, 0) END), 0) AS active
+    FROM pipelines p
+    LEFT JOIN (SELECT pipeline_id, SUM(cost_usd) sc, SUM(active_ms) sa
+               FROM pipeline_steps GROUP BY pipeline_id) s ON s.pipeline_id = p.id`;
+
+function totalsRow(sql, isoA, isoB) {
+  const row = prepare(sql).get(isoA, isoB);
+  return {
+    runs: row.runs, finished: row.finished, stopped: row.stopped, failed: row.failed,
+    paused: row.paused, running: row.running,
+    prsOpened: row.prsOpened, prsMerged: row.prsMerged,
+    workedMs: Number(row.active || 0),
+    cohortSpendUsd: roundUsd(row.spend || 0),
+  };
+}
+
+/** Cohort totals over runs started in [fromMs, toMs). Legacy fs->db imports have
+ *  no started_at; they fall back to updated_at so their money (which always
+ *  lands in the all-time sums) is never counted without its run. */
+function cohortTotals(fromMs, toMs) {
+  return totalsRow(`${TOTALS_SELECT}
+    WHERE COALESCE(p.started_at, p.updated_at) >= ?
+      AND COALESCE(p.started_at, p.updated_at) <  ?`,
+    new Date(fromMs).toISOString(), new Date(toMs).toISOString());
+}
+
+/** Runs whose lifespan [started_at, updated_at] overlaps [fromMs, toMs) —
+ *  "active in the window": started, updated, or finished inside it. There is
+ *  no finished_at column; updated_at is the terminal-write proxy. */
+function activeTotals(fromMs, toMs) {
+  return totalsRow(`${TOTALS_SELECT}
+    WHERE COALESCE(p.started_at, p.updated_at) <  ?
+      AND COALESCE(p.updated_at, p.started_at) >= ?`,
+    new Date(toMs).toISOString(), new Date(fromMs).toISOString());
+}
+
+/** Runs whose LAST write (updated_at, ≈ the terminal write for finished runs)
+ *  falls in [fromMs, toMs) — hourly outcome attribution for the today range. */
+function updatedTotals(fromMs, toMs) {
+  return totalsRow(`${TOTALS_SELECT}
+    WHERE COALESCE(p.updated_at, p.started_at) >= ?
+      AND COALESCE(p.updated_at, p.started_at) <  ?`,
+    new Date(fromMs).toISOString(), new Date(toMs).toISOString());
+}
+
+/** Ledger spend in [fromMs, toMs). */
+function ledgerSpend(fromMs, toMs) {
+  const row = prepare(
+    'SELECT SUM(amount_usd) AS s FROM cost_ledger WHERE ts >= ? AND ts < ?').get(fromMs, toMs);
+  return roundUsd(row?.s || 0);
+}
+
+/** Build zero-filled buckets [{startMs, endMs}] from windowStart through `now`. */
+function buildBuckets(windowStart, now, bucket) {
+  const out = [];
+  if (bucket === 'hour') {
+    for (let h = hourStart(windowStart); h <= now;
+         h = new Date(h.getFullYear(), h.getMonth(), h.getDate(), h.getHours() + 1)) {
+      out.push({ startMs: h.getTime(),
+        endMs: new Date(h.getFullYear(), h.getMonth(), h.getDate(), h.getHours() + 1).getTime() });
+    }
+  } else if (bucket === 'day') {
+    for (let d = dayStart(windowStart); d <= now; d = new Date(d.getFullYear(), d.getMonth(), d.getDate() + 1)) {
+      out.push({ startMs: d.getTime(), endMs: new Date(d.getFullYear(), d.getMonth(), d.getDate() + 1).getTime() });
+    }
+  } else {
+    for (let m = monthStart(windowStart); m <= now; m = new Date(m.getFullYear(), m.getMonth() + 1, 1)) {
+      out.push({ startMs: m.getTime(), endMs: new Date(m.getFullYear(), m.getMonth() + 1, 1).getTime() });
+    }
+  }
+  return out;
+}
+
+/** GET /api/stats backing (spec §6.9). @throws {RangeError} on unknown range. */
+export function getStats({ range = 'month', now = new Date() } = {}) {
+  if (!RANGES.includes(range)) throw new RangeError(`unknown stats range: ${range}`);
+  const budget = budgetStatus(now);
+
+  let windowStart, windowEnd, prevStart, prevEnd, bucket;
+  if (range === 'today') {
+    windowStart = dayStart(now);
+    windowEnd = new Date(now.getFullYear(), now.getMonth(), now.getDate() + 1);
+    prevStart = new Date(now.getFullYear(), now.getMonth(), now.getDate() - 1);
+    prevEnd = windowStart; bucket = 'hour';
+  } else if (range === 'week') {
+    windowStart = costWindowStart(now, 'weekly'); windowEnd = costWindowEnd(now, 'weekly');
+    prevStart = new Date(windowStart.getFullYear(), windowStart.getMonth(), windowStart.getDate() - 7);
+    prevEnd = windowStart; bucket = 'day';
+  } else if (range === 'month') {
+    windowStart = costWindowStart(now, 'monthly'); windowEnd = costWindowEnd(now, 'monthly');
+    prevStart = new Date(windowStart.getFullYear(), windowStart.getMonth() - 1, 1);
+    prevEnd = windowStart; bucket = 'day';
+  } else {
+    // all time: series over the last 12 months; totals over everything
+    windowStart = new Date(now.getFullYear(), now.getMonth() - 11, 1);
+    windowEnd = new Date(now.getFullYear(), now.getMonth() + 1, 1);
+    prevStart = null; prevEnd = null; bucket = 'month';
+  }
+
+  // 'today' counts runs ACTIVE in the window (Q&A: started, updated, or
+  // finished today); every other range keeps cohort-by-start. prev flows
+  // through the same closure, so the yesterday delta compares like with like.
+  const windowTotalsFn = range === 'today' ? activeTotals : cohortTotals;
+  const shapeTotals = (fromMs, toMs) => {
+    const c = windowTotalsFn(fromMs, toMs);
+    return {
+      spentUsd: ledgerSpend(fromMs, toMs),
+      workedMs: c.workedMs,
+      runs: c.runs, finished: c.finished, stopped: c.stopped, failed: c.failed,
+      paused: c.paused, running: c.running,
+      prsOpened: c.prsOpened, prsMerged: c.prsMerged,
+    };
+  };
+
+  let totals;
+  if (range === 'all') {
+    const at = allTimeTotals();
+    const c = cohortTotals(0, windowEnd.getTime());
+    totals = {
+      spentUsd: at.spendUsd, workedMs: at.activeMs,
+      runs: c.runs, finished: c.finished, stopped: c.stopped, failed: c.failed,
+      paused: c.paused, running: c.running,
+      prsOpened: c.prsOpened, prsMerged: c.prsMerged,
+    };
+  } else {
+    totals = shapeTotals(windowStart.getTime(), windowEnd.getTime());
+  }
+
+  const prev = prevStart ? shapeTotals(prevStart.getTime(), prevEnd.getTime()) : null;
+
+  // Hourly bars pin terminal outcomes to the hour of the terminal write; the
+  // day/month bars keep cohort-by-start. Money is ledger-exact either way.
+  const bucketTotalsFn = range === 'today' ? updatedTotals : cohortTotals;
+  const series = buildBuckets(windowStart, now, bucket).map(({ startMs, endMs }) => {
+    const c = bucketTotalsFn(startMs, endMs);
+    return {
+      bucketStartMs: startMs,
+      spentUsd: ledgerSpend(startMs, endMs),
+      finished: c.finished, stopped: c.stopped, failed: c.failed,
+    };
+  });
+
+  return {
+    range, bucket,
+    windowStartMs: windowStart.getTime(), windowEndMs: windowEnd.getTime(),
+    totals, prev, budget, series,
+  };
+}