@clear-capabilities/agentic-security-scanner 0.174.0 → 0.176.0

package/src/posture/fleet/enterprise-graph.js

@@ -0,0 +1,148 @@
+// The enterprise graph (PRD 4, requirements 6 to 8): the repositories, APIs, queues, databases, external providers and trust zones
+// of an organization, with every edge carrying the evidence it came from.
+//
+// Two kinds of edge, never confused:
+//   * `depends-on` edges come from each repository's own package manifest (the declared name and the spec it pins). A flaw in the
+//     dependency can affect the dependent. They are NOT movement an attacker makes.
+//   * REACH edges are what an attacker can move along: a call from one service to another, a producer to a queue, a queue to its
+//     consumer, a service to a database or an external provider, and the Internet to anything declared Internet-facing. Those come
+//     from the fleet manifest, which is operator-declared. They are labelled `source: fleet-manifest` and are exactly as good as the
+//     operator's declaration; nothing here pretends to have discovered them. (Code-derived call and queue edges are what the Data
+//     Flow Explorer's per-repository graph provides; joining that in is not built.)
+//
+// A graph edge without evidence is a bug, and `validateEnterpriseGraph` says so: "every graph edge traceable to source evidence".
+import { createHash } from 'node:crypto';
+
+const ENTERPRISE_GRAPH_SCHEMA = 'agentic-security/enterprise-graph';
+export const INTERNET = 'internet';
+const MAX_PATHS = 200;
+export const MAX_DEPTH = 8;
+const AUTH_CWES = new Set(['CWE-287', 'CWE-306', 'CWE-285', 'CWE-862', 'CWE-863', 'CWE-384', 'CWE-613', 'CWE-639', 'CWE-290', 'CWE-294', 'CWE-308', 'CWE-1390']);
+
+const edgeId = (type, from, to) => `edge:${type}:${from}:${to}`;
+const hash = (v) => createHash('sha256').update(JSON.stringify(v)).digest('hex');
+
+export function buildEnterpriseGraph({ manifest, dependencyGraph, discovered = null }) {
+  const nodes = new Map();
+  const edges = new Map();
+  const addNode = (n) => nodes.set(n.id, n);
+  const addEdge = (type, from, to, evidence, reach) => {
+    const id = edgeId(type, from, to);
+    const e = edges.get(id) ?? { id, type, from, to, reach, evidence: [] };
+    e.evidence.push(evidence);
+    edges.set(id, e);
+  };
+  addNode({ id: INTERNET, type: 'internet', kind: 'internet', internetFacing: false, environment: null, dataClasses: [], trustZone: 'internet', required: false });
+  for (const r of manifest.repositories) addNode({ id: r.id, type: 'repository', kind: r.kind, internetFacing: r.internetFacing, environment: r.environment, dataClasses: r.dataClasses, trustZone: r.trustZone, required: r.required });
+  for (const r of manifest.resources ?? []) addNode({ id: r.id, type: r.kind, kind: r.kind, internetFacing: r.internetFacing, environment: r.environment, dataClasses: r.dataClasses, trustZone: r.trustZone, required: false });
+
+  const ev = (repo, field, value) => ({ source: 'fleet-manifest', repo, field, value });
+  for (const n of [...nodes.values()]) if (n.internetFacing) addEdge('exposes', INTERNET, n.id, ev(n.id, 'internetFacing', true), true);
+  for (const r of manifest.repositories) {
+    for (const t of r.calls) addEdge('calls', r.id, t, ev(r.id, 'calls', t), true);
+    for (const t of r.produces) addEdge('produces', r.id, t, ev(r.id, 'produces', t), true);
+    for (const t of r.consumes) addEdge('consumes', t, r.id, ev(r.id, 'consumes', t), true);
+    for (const t of r.reads) addEdge('reads', r.id, t, ev(r.id, 'reads', t), true);
+    for (const t of r.writes) addEdge('writes', r.id, t, ev(r.id, 'writes', t), true);
+    for (const t of r.providers) addEdge('uses-provider', r.id, t, ev(r.id, 'providers', t), true);
+  }
+  for (const d of dependencyGraph?.edges ?? []) addEdge('depends-on', d.from, d.to, d.evidence?.[0] ?? { source: 'package-manifest', repo: d.from, file: null, declared: d.via, spec: null }, false);
+  // Edges found in the code. They share an id with a declared edge of the same type and endpoints, so the evidence list shows both; an
+  // edge with ONLY discovered evidence is marked `discovered: true` so a query can say it rests on a code literal, not on a declaration.
+  for (const d of discovered?.edges ?? []) for (const evidence of d.evidence) addEdge(d.type, d.from, d.to, evidence, true);
+  for (const e of edges.values()) e.discovered = e.evidence.every((x) => x.source === 'discovered-code-literal');
+  return { schema: ENTERPRISE_GRAPH_SCHEMA, version: 1, organization: manifest.organization, nodes: [...nodes.values()], edges: [...edges.values()], digest: null };
+}
+
+export function finalizeGraph(graph) { return { ...graph, digest: hash({ n: graph.nodes, e: graph.edges }) }; }
+
+/** Every edge has evidence, every endpoint exists. Returns a list of problems. */
+export function validateEnterpriseGraph(g) {
+  const errs = [];
+  const ids = new Set((g?.nodes ?? []).map((n) => n.id));
+  for (const e of g?.edges ?? []) {
+    if (!Array.isArray(e.evidence) || !e.evidence.length || !e.evidence.every((x) => x && typeof x.source === 'string')) errs.push(`edge ${e.id} has no source evidence`);
+    if (!ids.has(e.from) || !ids.has(e.to)) errs.push(`edge ${e.id} points at a node that is not in the graph`);
+  }
+  return errs;
+}
+
+const nodeOf = (g, id) => g.nodes.find((n) => n.id === id);
+
+/** Repositories that match a "vulnerable code" selector, and everything that depends on them. */
+export function vulnerableSet({ graph, findingsByRepo = new Map(), selector }) {
+  const direct = new Set(); const why = new Map();
+  if (selector.repo) { direct.add(selector.repo); why.set(selector.repo, 'named'); }
+  for (const [repo, findings] of findingsByRepo) {
+    const hit = (findings ?? []).find((f) => (selector.family === 'auth' ? (AUTH_CWES.has(String(f.cwe)) || /auth/i.test(String(f.family ?? ''))) : selector.family ? new RegExp(selector.family, 'i').test(String(f.family ?? f.vuln ?? '')) : false) || (selector.cwe && selector.cwe.includes(String(f.cwe))));
+    if (hit) { direct.add(repo); why.set(repo, `finding ${hit.id ?? hit.stableId ?? ''} ${hit.cwe ?? ''}`.trim()); }
+  }
+  const incoming = new Map();
+  for (const e of graph.edges) if (e.type === 'depends-on') { if (!incoming.has(e.to)) incoming.set(e.to, []); incoming.get(e.to).push(e.from); }
+  const all = new Set(direct); const stack = [...direct];
+  while (stack.length) { const c = stack.pop(); for (const f of incoming.get(c) ?? []) if (!all.has(f)) { all.add(f); why.set(f, `depends on ${c}`); stack.push(f); } }
+  return { direct, all, why };
+}
+
+/**
+ * Attack paths: simple paths from the Internet to any node holding `toDataClass`, along reach edges only. A path is "involving"
+ * when it passes through a repository in `involving`. Bounded in depth and count; `truncated` says when a bound was hit.
+ */
+export function attackPaths({ graph, toDataClass, from = INTERNET, involving = null, maxDepth = MAX_DEPTH, maxPaths = MAX_PATHS }) {
+  const out = new Map();
+  for (const e of graph.edges) if (e.reach) { if (!out.has(e.from)) out.set(e.from, []); out.get(e.from).push(e); }
+  const results = []; let truncated = false;
+  const targets = new Set(graph.nodes.filter((n) => n.dataClasses.includes(toDataClass)).map((n) => n.id));
+  const walk = (id, nodePath, edgePath) => {
+    if (results.length >= maxPaths) { truncated = true; return; }
+    if (targets.has(id) && nodePath.length > 1) {
+      const inv = involving ? nodePath.filter((n) => involving.all.has(n)) : [];
+      if (!involving || inv.length) results.push({ nodes: [...nodePath], edges: edgePath.map((e) => e.id), involving: inv, discoveredEdges: edgePath.filter((e) => e.discovered).map((e) => e.id), evidence: edgePath.flatMap((e) => e.evidence.map((x) => ({ edge: e.id, ...x }))) });
+    }
+    if (nodePath.length > maxDepth) { truncated = true; return; }
+    for (const e of out.get(id) ?? []) if (!nodePath.includes(e.to)) walk(e.to, [...nodePath, e.to], [...edgePath, e]);
+  };
+  if (nodeOf(graph, from)) walk(from, [from], []);
+  return { dataClass: toDataClass, targets: [...targets], paths: results, truncated, bounds: { maxDepth, maxPaths } };
+}
+
+/** The shared-component report: who depends on `component` (transitively), and how many of them are exposed, in production, or hold regulated data. */
+export function componentBlastRadius({ graph, component, version = null }) {
+  if (!nodeOf(graph, component)) return null;
+  const incoming = new Map();
+  for (const e of graph.edges) if (e.type === 'depends-on') { if (!incoming.has(e.to)) incoming.set(e.to, []); incoming.get(e.to).push(e); }
+  const found = new Map(); const queue = [{ id: component, path: [component], vm: 'not-asked' }];
+  while (queue.length) {
+    const { id, path, vm: parentVm } = queue.shift();
+    for (const e of incoming.get(id) ?? []) {
+      if (found.has(e.from)) continue;
+      const spec = e.evidence.map((x) => x.spec).find((x) => x != null) ?? null;
+      // only the dependents that pin the component itself can be judged against a version; one reached THROUGH another repository
+      // inherits that repository's status, and is not reached at all when the repository in between was ruled out
+      const direct = id === component;
+      const vm = direct ? (version == null ? 'not-asked' : spec == null ? 'unknown' : String(spec).includes(version) ? 'matched' : 'mismatch') : parentVm;
+      found.set(e.from, { id: e.from, depth: path.length, path: [...path, e.from], spec, versionMatch: vm, inherited: !direct, evidence: e.evidence });
+      if (vm !== 'mismatch') queue.push({ id: e.from, path: [...path, e.from], vm });
+    }
+  }
+  const all = [...found.values()].sort((a, b) => a.depth - b.depth || a.id.localeCompare(b.id));
+  const counted = all.filter((d) => d.versionMatch !== 'mismatch');
+  const attrs = (d) => nodeOf(graph, d.id);
+  const classes = {};
+  for (const d of counted) for (const c of attrs(d).dataClasses) classes[c] = (classes[c] ?? 0) + 1;
+  return {
+    component, version, dependents: all,
+    counts: { repositories: counted.length, internetFacing: counted.filter((d) => attrs(d).internetFacing).length, production: counted.filter((d) => attrs(d).environment === 'production').length, byDataClass: classes },
+    excludedByVersion: all.filter((d) => d.versionMatch === 'mismatch').map((d) => d.id),
+    unknownVersion: counted.filter((d) => d.versionMatch === 'unknown').map((d) => d.id),
+  };
+}
+
+export function renderBlastRadius(r) {
+  const n = (k, one, many) => `${k} ${k === 1 ? one : many}`;
+  const L = [`${r.component}${r.version ? `@${r.version}` : ''}`, '', 'Used by:', n(r.counts.repositories, 'repository', 'repositories'), n(r.counts.internetFacing, 'Internet-facing service', 'Internet-facing services'), n(r.counts.production, 'production app', 'production apps')];
+  for (const [c, k] of Object.entries(r.counts.byDataClass).sort()) L.push(n(k, `${c.toUpperCase()}-scoped service`, `${c.toUpperCase()}-scoped services`));
+  if (r.excludedByVersion.length) L.push('', `Excluded, their pinned version does not match: ${r.excludedByVersion.join(', ')}`);
+  if (r.unknownVersion.length) L.push('', `Counted, but their pinned version could not be read: ${r.unknownVersion.join(', ')}`);
+  return L.join('\n');
+}

package/src/posture/fleet/fleet-graph.js

@@ -27,8 +27,10 @@ function readBounded(p, maxBytes = 1024 * 1024) {
 function parsePackageJson(text) {
   let j;
   try { j = JSON.parse(text); } catch { return { name: null, deps: new Set() }; }
+  const specs = new Map();
+  for (const block of [j.peerDependencies, j.devDependencies, j.dependencies]) for (const [k, v] of Object.entries(block || {})) if (typeof v === 'string') specs.set(k, v.slice(0, 200));
   const deps = new Set([...Object.keys(j.dependencies || {}), ...Object.keys(j.devDependencies || {}), ...Object.keys(j.peerDependencies || {})]);
-  return { name: typeof j.name === 'string' ? j.name : null, deps };
+  return { name: typeof j.name === 'string' ? j.name : null, deps, specs, version: typeof j.version === 'string' ? j.version : null };
 }
 
 function parseGoMod(text) {
@@ -85,15 +87,18 @@ export function readRepoManifest(repoPath) {
   let name = null;
   const deps = new Set();
   const ecosystems = new Set();
+  const specs = new Map();
+  const files = new Map();
   for (const { file, ecosystem } of MANIFESTS) {
     const text = readBounded(path.join(repoPath, file));
     if (text == null) continue;
     const parsed = PARSERS[file](text);
     if (parsed.name && !name) name = parsed.name;
-    for (const d of parsed.deps) deps.add(d);
+    for (const d of parsed.deps) { deps.add(d); if (!files.has(d)) files.set(d, file); }
+    for (const [d, spec] of parsed.specs ?? []) specs.set(d, spec);
     ecosystems.add(ecosystem);
   }
-  return { name, deps, ecosystems: [...ecosystems] };
+  return { name, deps, ecosystems: [...ecosystems], specs, files };
 }
 
 /**
@@ -116,7 +121,7 @@ export function buildFleetDependencyGraph(repos) {
     for (const dep of r.manifest.deps) {
       const targets = byName.get(dep);
       if (!targets) continue;
-      for (const to of targets) if (to !== id) edges.push({ from: id, to, via: dep });
+      for (const to of targets) if (to !== id) edges.push({ from: id, to, via: dep, evidence: [{ source: 'package-manifest', repo: id, file: r.manifest.files.get(dep) ?? null, declared: dep, spec: r.manifest.specs.get(dep) ?? null }] });
     }
   }
   const nodes = [...manifests.values()].map((r) => ({ id: r.id, path: r.path, declaredName: r.manifest.name, ecosystems: r.manifest.ecosystems }));

package/src/posture/fleet/fleet-manifest.js

@@ -14,7 +14,13 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { load as loadYaml } from '../../util/yaml.js';
 
-const FLEET_MANIFEST_SCHEMA_KEYS = Object.freeze(['organization', 'repositories', 'workers', 'perRepoTimeout']);
+const FLEET_MANIFEST_SCHEMA_KEYS = Object.freeze(['organization', 'repositories', 'workers', 'perRepoTimeout', 'retries', 'resources']);
+const REPO_KEYS = Object.freeze(['id', 'path', 'required', 'kind', 'internetFacing', 'environment', 'dataClasses', 'trustZone', 'calls', 'produces', 'consumes', 'reads', 'writes', 'providers', 'aliases']);
+const RESOURCE_KEYS = Object.freeze(['id', 'kind', 'dataClasses', 'trustZone', 'internetFacing', 'environment', 'aliases']);
+const REPO_KINDS = Object.freeze(['service', 'library', 'frontend', 'worker', 'gateway']);
+const RESOURCE_KINDS = Object.freeze(['queue', 'database', 'external-provider', 'gateway']);
+export const ENVIRONMENTS = Object.freeze(['production', 'staging', 'development']);
+const NAME_RE = /^[a-z][a-z0-9-]{0,63}$/;
 const DURATION_RE = /^(\d+)(s|m|h)$/;
 
 export function parseDuration(s, fallbackMs) {
@@ -34,9 +40,13 @@ export function validateFleetManifest(doc, { baseDir = '.' } = {}) {
   if (!Array.isArray(doc.repositories) || doc.repositories.length === 0) errors.push('repositories must be a non-empty array');
   const seen = new Set();
   const repos = [];
+  const idList = (v, where) => { if (v === undefined) return []; if (!Array.isArray(v) || !v.every((x) => typeof x === 'string' && NAME_RE.test(x))) { errors.push(`${where} must be a list of ids`); return []; } return v; };
+  const aliasList = (v, where) => { if (v === undefined) return []; if (!Array.isArray(v) || v.length > 16 || !v.every((x) => typeof x === 'string' && /^[a-z0-9][a-z0-9._-]{0,99}$/.test(x))) { errors.push(`${where} must be a list of up to 16 lower-case names or hostnames`); return []; } return v; };
+  const classes = (v, where) => { if (v === undefined) return []; if (!Array.isArray(v) || !v.every((x) => typeof x === 'string' && /^[a-z][a-z0-9-]{0,30}$/.test(x))) { errors.push(`${where} must be a list of data class names such as pci or pii`); return []; } return v; };
   for (const [i, r] of (Array.isArray(doc.repositories) ? doc.repositories : []).entries()) {
     if (!r || typeof r !== 'object') { errors.push(`repositories[${i}] must be a mapping`); continue; }
-    if (typeof r.id !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(r.id)) { errors.push(`repositories[${i}].id must be a lowercase kebab-case string`); continue; }
+    for (const k of Object.keys(r)) if (!REPO_KEYS.includes(k)) errors.push(`repositories[${i}]: unknown key ${k}`);
+    if (typeof r.id !== 'string' || !NAME_RE.test(r.id)) { errors.push(`repositories[${i}].id must be a lowercase kebab-case string`); continue; }
     if (seen.has(r.id)) { errors.push(`duplicate repository id: ${r.id}`); continue; }
     seen.add(r.id);
     if (typeof r.path !== 'string' || !r.path) { errors.push(`repositories[${i}].path is required`); continue; }
@@ -44,16 +54,51 @@ export function validateFleetManifest(doc, { baseDir = '.' } = {}) {
     let isDir = false;
     try { isDir = fs.statSync(abs).isDirectory(); } catch { /* reported below */ }
     if (!isDir) errors.push(`repositories[${i}].path does not resolve to a directory: ${r.path}`);
-    repos.push({ id: r.id, path: abs });
+    if (r.kind !== undefined && !REPO_KINDS.includes(r.kind)) errors.push(`repositories[${i}].kind must be one of ${REPO_KINDS.join(', ')}`);
+    if (r.environment !== undefined && !ENVIRONMENTS.includes(r.environment)) errors.push(`repositories[${i}].environment must be one of ${ENVIRONMENTS.join(', ')}`);
+    for (const k of ['required', 'internetFacing']) if (r[k] !== undefined && typeof r[k] !== 'boolean') errors.push(`repositories[${i}].${k} must be true or false`);
+    if (r.trustZone !== undefined && !(typeof r.trustZone === 'string' && NAME_RE.test(r.trustZone))) errors.push(`repositories[${i}].trustZone must be a name`);
+    repos.push({
+      id: r.id, path: abs, required: r.required !== false, kind: r.kind ?? null, internetFacing: r.internetFacing === true, environment: r.environment ?? null,
+      dataClasses: classes(r.dataClasses, `repositories[${i}].dataClasses`), trustZone: r.trustZone ?? null,
+      aliases: aliasList(r.aliases, `repositories[${i}].aliases`), calls: idList(r.calls, `repositories[${i}].calls`), produces: idList(r.produces, `repositories[${i}].produces`), consumes: idList(r.consumes, `repositories[${i}].consumes`),
+      reads: idList(r.reads, `repositories[${i}].reads`), writes: idList(r.writes, `repositories[${i}].writes`), providers: idList(r.providers, `repositories[${i}].providers`),
+    });
+  }
+  const resources = [];
+  const resIds = new Set();
+  if (doc.resources !== undefined && !Array.isArray(doc.resources)) errors.push('resources must be a list');
+  for (const [i, r] of (Array.isArray(doc.resources) ? doc.resources : []).entries()) {
+    if (!r || typeof r !== 'object') { errors.push(`resources[${i}] must be a mapping`); continue; }
+    for (const k of Object.keys(r)) if (!RESOURCE_KEYS.includes(k)) errors.push(`resources[${i}]: unknown key ${k}`);
+    if (typeof r.id !== 'string' || !NAME_RE.test(r.id)) { errors.push(`resources[${i}].id must be a lowercase kebab-case string`); continue; }
+    if (seen.has(r.id) || resIds.has(r.id)) { errors.push(`resource id ${r.id} collides with another repository or resource`); continue; }
+    resIds.add(r.id);
+    if (!RESOURCE_KINDS.includes(r.kind)) errors.push(`resources[${i}].kind must be one of ${RESOURCE_KINDS.join(', ')}`);
+    if (r.environment !== undefined && !ENVIRONMENTS.includes(r.environment)) errors.push(`resources[${i}].environment must be one of ${ENVIRONMENTS.join(', ')}`);
+    if (r.internetFacing !== undefined && typeof r.internetFacing !== 'boolean') errors.push(`resources[${i}].internetFacing must be true or false`);
+    resources.push({ id: r.id, kind: r.kind, aliases: aliasList(r.aliases, `resources[${i}].aliases`), dataClasses: classes(r.dataClasses, `resources[${i}].dataClasses`), trustZone: r.trustZone ?? null, internetFacing: r.internetFacing === true, environment: r.environment ?? null });
+  }
+  const known = new Set([...seen, ...resIds]);
+  for (const r of repos) {
+    for (const [field, kinds] of [['calls', ['repo', 'gateway']], ['produces', ['queue']], ['consumes', ['queue']], ['reads', ['database']], ['writes', ['database']], ['providers', ['external-provider']]]) {
+      for (const target of r[field]) {
+        if (!known.has(target)) { errors.push(`repository ${r.id}: ${field} names ${target}, which is neither a repository nor a resource`); continue; }
+        const res = resources.find((x) => x.id === target);
+        const ok = res ? kinds.includes(res.kind) : kinds.includes('repo');
+        if (!ok) errors.push(`repository ${r.id}: ${field} cannot point at ${target}${res ? ` (a ${res.kind})` : ' (a repository)'}`);
+      }
+    }
   }
   if (doc.workers != null && !(Number.isInteger(doc.workers) && doc.workers >= 1 && doc.workers <= 32)) errors.push('workers must be an integer in 1..32');
+  if (doc.retries != null && !(Number.isInteger(doc.retries) && doc.retries >= 0 && doc.retries <= 5)) errors.push('retries must be an integer in 0..5');
   if (doc.perRepoTimeout != null && parseDuration(doc.perRepoTimeout, null) == null) errors.push(`perRepoTimeout is not a valid duration: ${doc.perRepoTimeout}`);
   if (errors.length) return { ok: false, errors };
   return {
     ok: true, errors: [],
     manifest: {
-      organization: doc.organization, repositories: repos,
-      workers: doc.workers ?? 4, perRepoTimeoutMs: parseDuration(doc.perRepoTimeout, 20 * 60000),
+      organization: doc.organization, repositories: repos, resources,
+      workers: doc.workers ?? 4, retries: doc.retries ?? 1, perRepoTimeoutMs: parseDuration(doc.perRepoTimeout, 20 * 60000),
     },
   };
 }

package/src/posture/fleet/job-runner.js

@@ -0,0 +1,153 @@
+// The fleet scan controller (PRD 4, requirements 2 to 5). It turns a manifest into jobs in the job store and runs them with bounded
+// workers, each scan in its own child process under a hard timeout, so one hung repository costs one worker for one timeout and
+// nothing else. Every state change is in the store, which is what makes `fleet resume` an ordinary continuation.
+//
+//   plan      fingerprint each repository, derive its cache key, enqueue one idempotent job per repository
+//   run       claim -> (cache hit | scan in a supervised child, heartbeating) -> complete | fail-with-retry
+//   recover   an expired lease, or a lease held by a dead process on this host, goes back in the queue
+//
+// A worker that loses its lease (it stopped heartbeating long enough for another worker to take the job) is fenced out: its late
+// result is refused by the store and its scan is aborted. Results are written per attempt (`<repo>.<epoch>.json`) and the job row
+// points at the winning one, so a retry can never produce two sets of findings for one repository.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { superviseSpawn } from '../../sandbox/supervise.js';
+import { statePath } from '../state-dir.js';
+import { repoFingerprint, scannerIdentity, cacheKey, readCache, writeCache } from './scan-cache.js';
+import { BEGIN, END } from './scan-child.js';
+
+const SCAN_CHILD = fileURLToPath(new URL('./scan-child.js', import.meta.url));
+const sha = (s) => createHash('sha256').update(s).digest('hex');
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export const DEFAULTS = Object.freeze({ leaseMs: 30_000, heartbeatMs: 10_000, retryDelayMs: 2_000, pollMs: 100 });
+
+/** The default scan: one supervised child process per repository. Throws `{code: 'TIMEOUT'|'ERROR', message}`. */
+export async function childScan(repoPath, { timeoutMs, signal }) {
+  const r = await superviseSpawn(process.execPath, [SCAN_CHILD, repoPath], { cwd: repoPath, env: { ...process.env, AGENTIC_SECURITY_NO_STATE: '1' }, timeoutMs, signal, maxOutputBytes: 96 * 1024 * 1024 });
+  const fail = (code, message) => Object.assign(new Error(message), { code });
+  if (r.timedOut) throw fail('TIMEOUT', `no result within ${Math.round(timeoutMs / 1000)}s`);
+  if (r.cancelled) throw fail('CANCELLED', 'cancelled');
+  if (r.spawnError) throw fail('ERROR', `could not start the scan: ${r.spawnError}`);
+  if (r.outputCapped) throw fail('ERROR', 'the scan produced more output than allowed');
+  if (r.exitCode !== 0) throw fail('ERROR', `scan exited ${r.exitCode}: ${String(r.stderr).trim().split('\n').pop()?.slice(0, 200) ?? ''}`);
+  const a = r.stdout.indexOf(BEGIN); const b = r.stdout.indexOf(END);
+  if (a < 0 || b < a) throw fail('ERROR', 'the scan produced no result block');
+  try { return JSON.parse(r.stdout.slice(a + BEGIN.length, b)); } catch (e) { throw fail('ERROR', `unreadable scan result: ${e.message}`); }
+}
+
+const hostId = () => os.hostname();
+const pidAlive = (pid) => { try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; } };
+
+/** Free jobs held by workers on THIS host whose process no longer exists. Other hosts are handled by lease expiry alone. */
+export function reclaimDeadWorkers(store, runId, { host = hostId(), alive = pidAlive, self = null } = {}) {
+  let freed = 0;
+  const seen = new Set();
+  for (const j of store.listJobs(runId)) {
+    if (j.status !== 'leased' || !j.worker || seen.has(j.worker) || j.worker === self) continue;
+    const m = /^(.*):(\d+):\d+$/.exec(j.worker);
+    if (!m || m[1] !== host) continue;
+    seen.add(j.worker);
+    if (!alive(Number(m[2]))) freed += store.reclaimWorker(runId, j.worker);
+  }
+  return freed;
+}
+
+export function planRun({ manifest, manifestHash, store, runId = null, config = {}, now = Date.now(), identity = scannerIdentity(), fingerprint = repoFingerprint, retries = manifest.retries, meta = {} }) {
+  const scanConfig = { provenance: false, ...config };
+  const prints = manifest.repositories.map((r) => ({ r, fp: fingerprint(r.path) }));
+  const configHash = sha(JSON.stringify(scanConfig));
+  const id = runId ?? `frun-${sha(JSON.stringify({ manifestHash, configHash, identity, t: now, prints: prints.map((p) => [p.r.id, p.fp.content]) })).slice(0, 16)}`;
+  store.begin({ runId: id, organization: manifest.organization, manifestHash, configHash, scannerIdentity: identity, createdAt: now, meta: { workers: manifest.workers, perRepoTimeoutMs: manifest.perRepoTimeoutMs, retries, ...meta } });
+  const created = store.enqueue(id, prints.map(({ r, fp }) => ({ jobId: `${id}:${r.id}`, repoId: r.id, commit: fp.commit, cacheKey: cacheKey({ fingerprint: fp, config: scanConfig, identity }), timeoutMs: manifest.perRepoTimeoutMs, maxAttempts: retries + 1, required: r.required })), { now });
+  return { runId: id, created, identity };
+}
+
+/**
+ * Run (or continue) a planned run until no job is queued or leased by a live worker. Returns when the work is done, the signal
+ * aborts, or `maxWaitMs` passes with only other workers' leases outstanding.
+ */
+export async function runJobs({ manifest, store, runId, root, scan = childScan, workers = manifest.workers, leaseMs = DEFAULTS.leaseMs, heartbeatMs = DEFAULTS.heartbeatMs, retryDelayMs = DEFAULTS.retryDelayMs, pollMs = DEFAULTS.pollMs, maxWaitMs = null, signal, now = () => Date.now(), onEvent = () => {}, cacheDir = null, artifactDir = null, useCache = true }) {
+  const repoById = new Map(manifest.repositories.map((r) => [r.id, r]));
+  const cacheD = cacheDir ?? statePath(root, 'fleet', 'cache');
+  const artD = artifactDir ?? statePath(root, 'fleet', 'artifacts', runId);
+  fs.mkdirSync(artD, { recursive: true, mode: 0o700 });
+  const deadline = maxWaitMs ?? (manifest.perRepoTimeoutMs * 3 + leaseMs);
+  const writeArtifact = (job, payload) => {
+    const text = JSON.stringify({ schema: 'agentic-security/fleet-scan-artifact', version: 1, runId, repoId: job.repoId, epoch: job.epoch, commit: job.commit, ...payload });
+    const file = path.join(artD, `${job.repoId}.${job.epoch}.json`);
+    fs.writeFileSync(file, text, { mode: 0o600 });
+    return { file, sha256: sha(text) };
+  };
+
+  async function worker(slot) {
+    const id = `${hostId()}:${process.pid}:${slot}`;
+    let idleSince = null;
+    for (;;) {
+      if (signal?.aborted) return;
+      store.reclaimExpired(runId, { now: now() });
+      const job = store.claim(runId, { worker: id, leaseMs, now: now() });
+      if (!job) {
+        const open = store.listJobs(runId).filter((j) => j.status === 'queued' || j.status === 'leased');
+        if (!open.length) return;
+        idleSince ??= now();
+        if (now() - idleSince > deadline) return;
+        await sleep(pollMs);
+        continue;
+      }
+      idleSince = null;
+      const repo = repoById.get(job.repoId);
+      onEvent({ type: 'start', repo: job.repoId, attempt: job.attempts });
+      const cached = useCache ? readCache(cacheD, job.cacheKey) : null;
+      if (cached) {
+        const a = writeArtifact(job, { entry: cached.entry, findings: cached.findings, findingsTruncated: !!cached.findingsTruncated, cached: true });
+        const status = cached.entry?.scanHealth && cached.entry.scanHealth.status !== 'complete' ? 'partial' : 'succeeded';
+        if (store.complete(job.jobId, job.epoch, { status, artifactSha256: a.sha256, summary: { total: cached.entry?.total ?? null, cached: true, artifact: path.basename(a.file) }, now: now() })) onEvent({ type: 'done', repo: job.repoId, cached: true, status });
+        continue;
+      }
+      const ac = new AbortController();
+      const onAbort = () => ac.abort();
+      signal?.addEventListener('abort', onAbort, { once: true });
+      let lost = false;
+      const hb = setInterval(() => { if (!store.heartbeat(job.jobId, job.epoch, { now: now(), leaseMs })) { lost = true; ac.abort(); } }, heartbeatMs);
+      try {
+        const out = await scan(repo.path, { timeoutMs: job.timeoutMs, signal: ac.signal });
+        clearInterval(hb);
+        if (lost) { onEvent({ type: 'fenced', repo: job.repoId }); continue; }
+        if (!out?.entry) throw Object.assign(new Error('the scan returned no entry'), { code: 'ERROR' });
+        if (out.entry.ok === false) throw Object.assign(new Error(out.entry.error || 'the scan failed'), { code: 'ERROR' });
+        const a = writeArtifact(job, { entry: out.entry, findings: out.findings ?? [], findingsTruncated: !!out.findingsTruncated });
+        const status = out.entry.scanHealth && out.entry.scanHealth.status !== 'complete' ? 'partial' : 'succeeded';
+        if (store.complete(job.jobId, job.epoch, { status, artifactSha256: a.sha256, summary: { total: out.entry.total ?? null, cached: false, artifact: path.basename(a.file) }, now: now() })) {
+          if (useCache && status === 'succeeded') writeCache(cacheD, job.cacheKey, { entry: out.entry, findings: out.findings ?? [], findingsTruncated: !!out.findingsTruncated });
+          onEvent({ type: 'done', repo: job.repoId, cached: false, status });
+        } else onEvent({ type: 'fenced', repo: job.repoId });
+      } catch (e) {
+        clearInterval(hb);
+        if (lost || e?.code === 'CANCELLED') { if (e?.code === 'CANCELLED' && !lost) store.fail(job.jobId, job.epoch, { error: 'cancelled', now: now(), retryDelayMs: 0 }); continue; }
+        const r = store.fail(job.jobId, job.epoch, { error: e?.message ?? String(e), timedOut: e?.code === 'TIMEOUT', now: now(), retryDelayMs });
+        onEvent({ type: 'failed', repo: job.repoId, error: e?.message ?? String(e), timedOut: e?.code === 'TIMEOUT', next: r?.state ?? null });
+      } finally { clearInterval(hb); signal?.removeEventListener('abort', onAbort); }
+    }
+  }
+  await Promise.all(Array.from({ length: Math.max(1, Math.min(workers, 32)) }, (_, i) => worker(i)));
+  return { aborted: !!signal?.aborted };
+}
+
+/** Load the artifacts the jobs point at, verifying each against the hash the store recorded. A missing or altered artifact is reported, not used. */
+export function loadArtifacts({ store, runId, root, artifactDir = null }) {
+  const dir = artifactDir ?? statePath(root, 'fleet', 'artifacts', runId);
+  const out = new Map(); const problems = [];
+  for (const j of store.listJobs(runId)) {
+    if (!['succeeded', 'partial'].includes(j.status)) continue;
+    const file = path.join(dir, j.summary?.artifact ?? `${j.repoId}.${j.epoch}.json`);
+    try {
+      const text = fs.readFileSync(file, 'utf8');
+      if (sha(text) !== j.artifactSha256) { problems.push({ repoId: j.repoId, problem: 'artifact does not match the recorded hash' }); continue; }
+      out.set(j.repoId, JSON.parse(text));
+    } catch { problems.push({ repoId: j.repoId, problem: 'artifact is missing or unreadable' }); }
+  }
+  return { artifacts: out, problems };
+}

package/src/posture/fleet/job-store.js

@@ -0,0 +1,136 @@
+// The fleet job store (PRD 4, requirements 2 and 3): jobs with a lease, a heartbeat, a retry count, a timeout and a result hash,
+// behind one small interface so the storage can change without the scheduler noticing.
+//
+//   createSqliteJobStore({ file })   local deployment, one file, no server (node:sqlite)
+//   createMemoryJobStore()           the reference implementation; the conformance tests run the SAME assertions against both,
+//                                    which is what shows the interface does not secretly depend on SQLite. A PostgreSQL or a
+//                                    queue-backed store would be a third implementation of the same methods.
+//
+// Semantics that matter (and are tested on both stores):
+//   * IDEMPOTENT: a job's id is derived from its run, repository, commit and configuration, and `enqueue` of an existing id does
+//     nothing. Enqueueing a run twice does not make two jobs.
+//   * LEASED: `claim` hands one queued job to one worker, increments a fencing `epoch`, and starts a lease. A worker that stops
+//     heartbeating loses the job when the lease expires; `reclaimExpired` puts it back in the queue.
+//   * FENCED: `heartbeat`, `complete` and `fail` must present the epoch they were given. A worker that lost its lease (and whose
+//     job another worker now holds) is refused, so a slow zombie can neither extend a lease it no longer has nor overwrite the
+//     result of the worker that replaced it. That is what keeps a retry from duplicating findings.
+//   * BOUNDED RETRIES: a failure puts the job back in the queue until `maxAttempts`, then it is `failed` (or `timed_out`),
+//     terminal, and visible in the organization's health. A job is never silently dropped.
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const JOB_STATUSES = Object.freeze(['queued', 'leased', 'succeeded', 'partial', 'failed', 'timed_out', 'cancelled']);
+const TERMINAL = new Set(['succeeded', 'partial', 'failed', 'timed_out', 'cancelled']);
+export const isTerminal = (s) => TERMINAL.has(s);
+
+const jobOf = (r) => (r ? {
+  jobId: r.job_id, runId: r.run_id, repoId: r.repo_id, commit: r.commit_sha ?? null, cacheKey: r.cache_key ?? null, status: r.status, worker: r.worker ?? null,
+  epoch: r.epoch, leaseExpiresAt: r.lease_expires_at ?? null, heartbeatAt: r.heartbeat_at ?? null, attempts: r.attempts, maxAttempts: r.max_attempts,
+  timeoutMs: r.timeout_ms, nextAttemptAt: r.next_attempt_at ?? 0, artifactSha256: r.artifact_sha256 ?? null, summary: r.summary ? JSON.parse(r.summary) : null,
+  error: r.error ?? null, createdAt: r.created_at, startedAt: r.started_at ?? null, finishedAt: r.finished_at ?? null, required: !!r.required,
+} : null);
+
+// ------------------------------------------------------------------------------------------------------- memory
+export function createMemoryJobStore() {
+  const runs = new Map(); const jobs = new Map();
+  const all = (runId) => [...jobs.values()].filter((j) => j.runId === runId);
+  const store = {
+    kind: 'memory',
+    begin(run) { if (!runs.has(run.runId)) runs.set(run.runId, { ...run }); return runs.get(run.runId); },
+    getRun: (runId) => runs.get(runId) ?? null,
+    listRuns: () => [...runs.values()].sort((a, b) => String(b.createdAt).localeCompare(String(a.createdAt))),
+    enqueue(runId, list, { now = Date.now() } = {}) {
+      let created = 0;
+      for (const j of list) { if (jobs.has(j.jobId)) continue; jobs.set(j.jobId, { runId, repoId: j.repoId, jobId: j.jobId, commit: j.commit ?? null, cacheKey: j.cacheKey ?? null, status: 'queued', worker: null, epoch: 0, leaseExpiresAt: null, heartbeatAt: null, attempts: 0, maxAttempts: j.maxAttempts ?? 2, timeoutMs: j.timeoutMs, nextAttemptAt: 0, artifactSha256: null, summary: null, error: null, createdAt: now, startedAt: null, finishedAt: null, required: j.required !== false }); created++; }
+      return created;
+    },
+    claim(runId, { worker, leaseMs, now = Date.now() }) {
+      const j = all(runId).filter((x) => x.status === 'queued' && x.nextAttemptAt <= now).sort((a, b) => a.createdAt - b.createdAt || a.repoId.localeCompare(b.repoId))[0];
+      if (!j) return null;
+      Object.assign(j, { status: 'leased', worker, epoch: j.epoch + 1, attempts: j.attempts + 1, leaseExpiresAt: now + leaseMs, heartbeatAt: now, startedAt: now, error: null });
+      return { ...j };
+    },
+    heartbeat(jobId, epoch, { now = Date.now(), leaseMs }) { const j = jobs.get(jobId); if (!j || j.status !== 'leased' || j.epoch !== epoch) return false; j.heartbeatAt = now; j.leaseExpiresAt = now + leaseMs; return true; },
+    complete(jobId, epoch, { status = 'succeeded', artifactSha256 = null, summary = null, now = Date.now() }) {
+      const j = jobs.get(jobId); if (!j || j.status !== 'leased' || j.epoch !== epoch) return false;
+      Object.assign(j, { status, artifactSha256, summary, finishedAt: now, leaseExpiresAt: null, error: null }); return true;
+    },
+    fail(jobId, epoch, { error, timedOut = false, now = Date.now(), retryDelayMs = 0 }) {
+      const j = jobs.get(jobId); if (!j || j.status !== 'leased' || j.epoch !== epoch) return null;
+      j.error = String(error ?? '').slice(0, 500); j.leaseExpiresAt = null; j.worker = null;
+      if (j.attempts < j.maxAttempts) { j.status = 'queued'; j.nextAttemptAt = now + retryDelayMs; return { state: 'queued', attempts: j.attempts }; }
+      j.status = timedOut ? 'timed_out' : 'failed'; j.finishedAt = now; return { state: j.status, attempts: j.attempts };
+    },
+    reclaimExpired(runId, { now = Date.now() }) { let n = 0; for (const j of all(runId)) if (j.status === 'leased' && j.leaseExpiresAt != null && j.leaseExpiresAt <= now) { j.status = 'queued'; j.worker = null; j.leaseExpiresAt = null; j.nextAttemptAt = 0; j.error = 'lease expired'; n++; } return n; },
+    reclaimWorker(runId, worker) { let n = 0; for (const j of all(runId)) if (j.status === 'leased' && j.worker === worker) { j.status = 'queued'; j.worker = null; j.leaseExpiresAt = null; j.nextAttemptAt = 0; j.error = 'worker is gone'; n++; } return n; },
+    cancel(runId, { now = Date.now() }) { let n = 0; for (const j of all(runId)) if (!TERMINAL.has(j.status)) { j.status = 'cancelled'; j.finishedAt = now; j.leaseExpiresAt = null; n++; } return n; },
+    retime(runId, timeoutMs) { let n = 0; for (const j of all(runId)) if (j.status === 'queued') { j.timeoutMs = timeoutMs; n++; } return n; },
+    requeueTerminal(runId, statuses) { let n = 0; for (const j of all(runId)) if (statuses.includes(j.status)) { Object.assign(j, { status: 'queued', worker: null, attempts: 0, nextAttemptAt: 0, leaseExpiresAt: null, finishedAt: null, error: null }); n++; } return n; },
+    listJobs: (runId) => all(runId).map((j) => ({ ...j })).sort((a, b) => a.repoId.localeCompare(b.repoId)),
+    getJob: (jobId) => (jobs.get(jobId) ? { ...jobs.get(jobId) } : null),
+    close() {},
+  };
+  return store;
+}
+
+// ------------------------------------------------------------------------------------------------------- sqlite
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS fleet_runs (run_id TEXT PRIMARY KEY, organization TEXT NOT NULL, manifest_hash TEXT NOT NULL, config_hash TEXT NOT NULL, scanner_identity TEXT, created_at INTEGER NOT NULL, meta TEXT);
+CREATE TABLE IF NOT EXISTS fleet_jobs (
+  job_id TEXT PRIMARY KEY, run_id TEXT NOT NULL REFERENCES fleet_runs(run_id), repo_id TEXT NOT NULL, commit_sha TEXT, cache_key TEXT,
+  status TEXT NOT NULL, worker TEXT, epoch INTEGER NOT NULL DEFAULT 0, lease_expires_at INTEGER, heartbeat_at INTEGER,
+  attempts INTEGER NOT NULL DEFAULT 0, max_attempts INTEGER NOT NULL, timeout_ms INTEGER NOT NULL, next_attempt_at INTEGER NOT NULL DEFAULT 0,
+  artifact_sha256 TEXT, summary TEXT, error TEXT, created_at INTEGER NOT NULL, started_at INTEGER, finished_at INTEGER, required INTEGER NOT NULL DEFAULT 1
+);
+CREATE INDEX IF NOT EXISTS fleet_jobs_run_status ON fleet_jobs (run_id, status);
+`;
+
+export async function createSqliteJobStore({ file }) {
+  const { DatabaseSync } = await import('node:sqlite');
+  if (file !== ':memory:') fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const db = new DatabaseSync(file);
+  db.exec('PRAGMA journal_mode = WAL; PRAGMA busy_timeout = 5000; PRAGMA foreign_keys = ON;');
+  db.exec(SCHEMA);
+  const tx = (fn) => { db.exec('BEGIN IMMEDIATE'); try { const r = fn(); db.exec('COMMIT'); return r; } catch (e) { try { db.exec('ROLLBACK'); } catch { /* already rolled back */ } throw e; } };
+  const q = (sql, ...p) => db.prepare(sql).all(...p);
+  const one = (sql, ...p) => db.prepare(sql).get(...p);
+  const run = (sql, ...p) => db.prepare(sql).run(...p);
+  return {
+    kind: 'sqlite', file,
+    begin(r) { run('INSERT OR IGNORE INTO fleet_runs (run_id, organization, manifest_hash, config_hash, scanner_identity, created_at, meta) VALUES (?,?,?,?,?,?,?)', r.runId, r.organization, r.manifestHash, r.configHash, r.scannerIdentity ?? null, r.createdAt, JSON.stringify(r.meta ?? {})); return this.getRun(r.runId); },
+    getRun(runId) { const r = one('SELECT * FROM fleet_runs WHERE run_id = ?', runId); return r ? { runId: r.run_id, organization: r.organization, manifestHash: r.manifest_hash, configHash: r.config_hash, scannerIdentity: r.scanner_identity, createdAt: r.created_at, meta: JSON.parse(r.meta ?? '{}') } : null; },
+    listRuns() { return q('SELECT * FROM fleet_runs ORDER BY created_at DESC').map((r) => ({ runId: r.run_id, organization: r.organization, manifestHash: r.manifest_hash, createdAt: r.created_at })); },
+    enqueue(runId, list, { now = Date.now() } = {}) {
+      return tx(() => { let created = 0; for (const j of list) { const r = run('INSERT OR IGNORE INTO fleet_jobs (job_id, run_id, repo_id, commit_sha, cache_key, status, max_attempts, timeout_ms, created_at, required) VALUES (?,?,?,?,?,?,?,?,?,?)', j.jobId, runId, j.repoId, j.commit ?? null, j.cacheKey ?? null, 'queued', j.maxAttempts ?? 2, j.timeoutMs, now, j.required === false ? 0 : 1); created += Number(r.changes); } return created; });
+    },
+    claim(runId, { worker, leaseMs, now = Date.now() }) {
+      return tx(() => {
+        const j = one("SELECT job_id FROM fleet_jobs WHERE run_id = ? AND status = 'queued' AND next_attempt_at <= ? ORDER BY created_at, repo_id LIMIT 1", runId, now);
+        if (!j) return null;
+        run("UPDATE fleet_jobs SET status = 'leased', worker = ?, epoch = epoch + 1, attempts = attempts + 1, lease_expires_at = ?, heartbeat_at = ?, started_at = ?, error = NULL WHERE job_id = ?", worker, now + leaseMs, now, now, j.job_id);
+        return jobOf(one('SELECT * FROM fleet_jobs WHERE job_id = ?', j.job_id));
+      });
+    },
+    heartbeat(jobId, epoch, { now = Date.now(), leaseMs }) { return Number(run("UPDATE fleet_jobs SET heartbeat_at = ?, lease_expires_at = ? WHERE job_id = ? AND status = 'leased' AND epoch = ?", now, now + leaseMs, jobId, epoch).changes) === 1; },
+    complete(jobId, epoch, { status = 'succeeded', artifactSha256 = null, summary = null, now = Date.now() }) { return Number(run("UPDATE fleet_jobs SET status = ?, artifact_sha256 = ?, summary = ?, finished_at = ?, lease_expires_at = NULL, error = NULL WHERE job_id = ? AND status = 'leased' AND epoch = ?", status, artifactSha256, summary ? JSON.stringify(summary) : null, now, jobId, epoch).changes) === 1; },
+    fail(jobId, epoch, { error, timedOut = false, now = Date.now(), retryDelayMs = 0 }) {
+      return tx(() => {
+        const j = one("SELECT attempts, max_attempts FROM fleet_jobs WHERE job_id = ? AND status = 'leased' AND epoch = ?", jobId, epoch);
+        if (!j) return null;
+        const msg = String(error ?? '').slice(0, 500);
+        if (j.attempts < j.max_attempts) { run("UPDATE fleet_jobs SET status = 'queued', worker = NULL, lease_expires_at = NULL, next_attempt_at = ?, error = ? WHERE job_id = ?", now + retryDelayMs, msg, jobId); return { state: 'queued', attempts: j.attempts }; }
+        const st = timedOut ? 'timed_out' : 'failed';
+        run('UPDATE fleet_jobs SET status = ?, worker = NULL, lease_expires_at = NULL, finished_at = ?, error = ? WHERE job_id = ?', st, now, msg, jobId);
+        return { state: st, attempts: j.attempts };
+      });
+    },
+    reclaimExpired(runId, { now = Date.now() }) { return Number(run("UPDATE fleet_jobs SET status = 'queued', worker = NULL, lease_expires_at = NULL, next_attempt_at = 0, error = 'lease expired' WHERE run_id = ? AND status = 'leased' AND lease_expires_at IS NOT NULL AND lease_expires_at <= ?", runId, now).changes); },
+    reclaimWorker(runId, worker) { return Number(run("UPDATE fleet_jobs SET status = 'queued', worker = NULL, lease_expires_at = NULL, next_attempt_at = 0, error = 'worker is gone' WHERE run_id = ? AND status = 'leased' AND worker = ?", runId, worker).changes); },
+    cancel(runId, { now = Date.now() }) { return Number(run("UPDATE fleet_jobs SET status = 'cancelled', finished_at = ?, lease_expires_at = NULL WHERE run_id = ? AND status IN ('queued','leased')", now, runId).changes); },
+    retime(runId, timeoutMs) { return Number(run("UPDATE fleet_jobs SET timeout_ms = ? WHERE run_id = ? AND status = 'queued'", timeoutMs, runId).changes); },
+    requeueTerminal(runId, statuses) { return Number(run(`UPDATE fleet_jobs SET status = 'queued', worker = NULL, attempts = 0, next_attempt_at = 0, lease_expires_at = NULL, finished_at = NULL, error = NULL WHERE run_id = ? AND status IN (${statuses.map(() => '?').join(',')})`, runId, ...statuses).changes); },
+    listJobs: (runId) => q('SELECT * FROM fleet_jobs WHERE run_id = ? ORDER BY repo_id', runId).map(jobOf),
+    getJob: (jobId) => jobOf(one('SELECT * FROM fleet_jobs WHERE job_id = ?', jobId)),
+    close() { try { db.close(); } catch { /* already closed */ } },
+  };
+}