agent-working-memory 0.5.6 → 0.6.0

package/src/coordination/routes.ts

@@ -10,11 +10,12 @@ import type { FastifyInstance } from 'fastify';
 import type Database from 'better-sqlite3';
 import { randomUUID } from 'node:crypto';
 import {
-  checkinSchema, checkoutSchema, pulseSchema,
+  checkinSchema, checkoutSchema, pulseSchema, nextSchema,
   assignCreateSchema, assignmentQuerySchema, assignmentClaimSchema, assignmentUpdateSchema, assignmentIdParamSchema,
   lockAcquireSchema, lockReleaseSchema,
   commandCreateSchema, commandWaitQuerySchema,
   findingCreateSchema, findingsQuerySchema, findingIdParamSchema,
+  decisionsQuerySchema,
   eventsQuerySchema, staleQuerySchema, workersQuerySchema,
 } from './schemas.js';
 import { detectStale, cleanupStale } from './stale.js';
@@ -46,24 +47,31 @@ export function registerCoordinationRoutes(app: FastifyInstance, db: Database.Da
     const { name, role, pid, metadata, capabilities, workspace } = parsed.data;
     const capsJson = capabilities ? JSON.stringify(capabilities) : null;
 
+    // Look up ANY existing agent with same name+workspace — including dead ones (upsert)
     const existing = workspace
       ? db.prepare(
-          `SELECT id, status FROM coord_agents WHERE name = ? AND workspace = ? AND status != 'dead'`
+          `SELECT id, status FROM coord_agents WHERE name = ? AND workspace = ? ORDER BY last_seen DESC LIMIT 1`
         ).get(name, workspace) as { id: string; status: string } | undefined
       : db.prepare(
-          `SELECT id, status FROM coord_agents WHERE name = ? AND workspace IS NULL AND status != 'dead'`
+          `SELECT id, status FROM coord_agents WHERE name = ? AND workspace IS NULL ORDER BY last_seen DESC LIMIT 1`
         ).get(name) as { id: string; status: string } | undefined;
 
     if (existing) {
+      const wasDead = existing.status === 'dead';
       db.prepare(
         `UPDATE coord_agents SET last_seen = datetime('now'), status = CASE WHEN status = 'dead' THEN 'idle' ELSE status END, pid = COALESCE(?, pid), capabilities = COALESCE(?, capabilities) WHERE id = ?`
       ).run(pid ?? null, capsJson, existing.id);
 
+      const eventType = wasDead ? 'reconnected' : 'heartbeat';
+      const detail = wasDead ? `${name} reconnected (was dead)` : `heartbeat from ${name}`;
       db.prepare(
-        `INSERT INTO coord_events (agent_id, event_type, detail) VALUES (?, 'heartbeat', ?)`
-      ).run(existing.id, `heartbeat from ${name}`);
+        `INSERT INTO coord_events (agent_id, event_type, detail) VALUES (?, ?, ?)`
+      ).run(existing.id, eventType, detail);
 
-      return reply.send({ agentId: existing.id, action: 'heartbeat', status: existing.status, workspace });
+      if (wasDead) coordLog(`${name} reconnected (reusing UUID ${existing.id.slice(0, 8)})`);
+      const action = wasDead ? 'reconnected' : 'heartbeat';
+      const status = wasDead ? 'idle' : existing.status;
+      return reply.send({ agentId: existing.id, action, status, workspace });
     }
 
     const id = randomUUID();
@@ -109,17 +117,117 @@ export function registerCoordinationRoutes(app: FastifyInstance, db: Database.Da
     return reply.send({ ok: true });
   });
 
+  // ─── Next (combined checkin + commands + assignment poll) ───────
+
+  app.post('/next', async (req, reply) => {
+    const parsed = nextSchema.safeParse(req.body);
+    if (!parsed.success) return reply.code(400).send({ error: parsed.error.issues[0].message });
+    const { name, workspace, role, capabilities } = parsed.data;
+    const capsJson = capabilities ? JSON.stringify(capabilities) : null;
+
+    // Step 1: Upsert agent (checkin / heartbeat) — including dead agents (reuse UUID)
+    const existing = workspace
+      ? db.prepare(
+          `SELECT id, status FROM coord_agents WHERE name = ? AND workspace = ? ORDER BY last_seen DESC LIMIT 1`
+        ).get(name, workspace) as { id: string; status: string } | undefined
+      : db.prepare(
+          `SELECT id, status FROM coord_agents WHERE name = ? AND workspace IS NULL ORDER BY last_seen DESC LIMIT 1`
+        ).get(name) as { id: string; status: string } | undefined;
+
+    let agentId: string;
+    if (existing) {
+      agentId = existing.id;
+      const wasDead = existing.status === 'dead';
+      db.prepare(
+        `UPDATE coord_agents SET last_seen = datetime('now'), status = CASE WHEN status = 'dead' THEN 'idle' ELSE status END, capabilities = COALESCE(?, capabilities) WHERE id = ?`
+      ).run(capsJson, agentId);
+      const eventType = wasDead ? 'reconnected' : 'heartbeat';
+      const detail = wasDead ? `${name} reconnected via /next` : `heartbeat from ${name}`;
+      db.prepare(
+        `INSERT INTO coord_events (agent_id, event_type, detail) VALUES (?, ?, ?)`
+      ).run(agentId, eventType, detail);
+      if (wasDead) coordLog(`${name} reconnected via /next (reusing UUID ${agentId.slice(0, 8)})`);
+    } else {
+      agentId = randomUUID();
+      db.prepare(
+        `INSERT INTO coord_agents (id, name, role, pid, status, metadata, capabilities, workspace) VALUES (?, ?, ?, NULL, 'idle', NULL, ?, ?)`
+      ).run(agentId, name, role ?? 'worker', capsJson, workspace ?? null);
+      db.prepare(
+        `INSERT INTO coord_events (agent_id, event_type, detail) VALUES (?, 'registered', ?)`
+      ).run(agentId, `${name} joined as ${role ?? 'worker'} via /next`);
+      coordLog(`${name} registered via /next (${role ?? 'worker'})${capabilities ? ' [' + capabilities.join(', ') + ']' : ''}`);
+    }
+
+    // Step 2: Get active commands
+    const activeCommands = workspace
+      ? db.prepare(
+          `SELECT id, command, reason, issued_by, issued_at, workspace
+           FROM coord_commands WHERE cleared_at IS NULL AND (workspace = ? OR workspace IS NULL)
+           ORDER BY issued_at DESC`
+        ).all(workspace) as Array<{ id: number; command: string; reason: string; issued_by: string; issued_at: string; workspace: string | null }>
+      : db.prepare(
+          `SELECT id, command, reason, issued_by, issued_at, workspace
+           FROM coord_commands WHERE cleared_at IS NULL
+           ORDER BY issued_at DESC`
+        ).all() as Array<{ id: number; command: string; reason: string; issued_by: string; issued_at: string; workspace: string | null }>;
+
+    // Step 3: Get or auto-claim assignment
+    let assignment = db.prepare(
+      `SELECT * FROM coord_assignments WHERE agent_id = ? AND status IN ('assigned', 'in_progress') ORDER BY created_at DESC LIMIT 1`
+    ).get(agentId) as Record<string, unknown> | undefined;
+
+    if (!assignment) {
+      const agentWorkspace = workspace ?? null;
+      // Priority-ordered dispatch: higher priority first, then FIFO.
+      // Skip assignments blocked by incomplete dependencies.
+      const blockedFilter = `AND (blocked_by IS NULL OR blocked_by IN (SELECT id FROM coord_assignments WHERE status = 'completed'))`;
+      const pending = agentWorkspace
+        ? db.prepare(
+            `SELECT * FROM coord_assignments WHERE status = 'pending' AND (workspace = ? OR workspace IS NULL) ${blockedFilter} ORDER BY priority DESC, created_at ASC LIMIT 1`
+          ).get(agentWorkspace) as { id: string } | undefined
+        : db.prepare(
+            `SELECT * FROM coord_assignments WHERE status = 'pending' ${blockedFilter} ORDER BY priority DESC, created_at ASC LIMIT 1`
+          ).get() as { id: string } | undefined;
+
+      if (pending) {
+        const claimed = db.prepare(
+          `UPDATE coord_assignments SET agent_id = ?, status = 'assigned', started_at = datetime('now') WHERE id = ? AND status = 'pending'`
+        ).run(agentId, pending.id);
+
+        if (claimed.changes > 0) {
+          db.prepare(
+            `UPDATE coord_agents SET status = 'working', current_task = ? WHERE id = ?`
+          ).run(pending.id, agentId);
+          db.prepare(
+            `INSERT INTO coord_events (agent_id, event_type, detail) VALUES (?, 'assignment_claimed', ?)`
+          ).run(agentId, `auto-claimed assignment ${pending.id} via /next`);
+          assignment = db.prepare(`SELECT * FROM coord_assignments WHERE id = ?`).get(pending.id) as Record<string, unknown> | undefined;
+        }
+      }
+    }
+
+    // Read current agent status after all mutations
+    const agentRow = db.prepare(`SELECT status FROM coord_agents WHERE id = ?`).get(agentId) as { status: string };
+
+    return reply.send({
+      agentId,
+      status: agentRow.status,
+      assignment: assignment ?? null,
+      commands: activeCommands,
+    });
+  });
+
   // ─── Assignments ────────────────────────────────────────────────
 
   app.post('/assign', async (req, reply) => {
     const parsed = assignCreateSchema.safeParse(req.body);
     if (!parsed.success) return reply.code(400).send({ error: parsed.error.issues[0].message });
-    const { agentId, task, description, workspace } = parsed.data;
+    const { agentId, task, description, workspace, priority, blocked_by } = parsed.data;
 
     const id = randomUUID();
     db.prepare(
-      `INSERT INTO coord_assignments (id, agent_id, task, description, status, workspace) VALUES (?, ?, ?, ?, ?, ?)`
-    ).run(id, agentId ?? null, task, description ?? null, agentId ? 'assigned' : 'pending', workspace ?? null);
+      `INSERT INTO coord_assignments (id, agent_id, task, description, status, priority, blocked_by, workspace) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`
+    ).run(id, agentId ?? null, task, description ?? null, agentId ? 'assigned' : 'pending', priority, blocked_by ?? null, workspace ?? null);
 
     if (agentId) {
       db.prepare(
@@ -142,7 +250,20 @@ export function registerCoordinationRoutes(app: FastifyInstance, db: Database.Da
   });
 
   app.get('/assignment', async (req, reply) => {
-    const agentId = (req.headers['x-agent-id'] as string | undefined) ?? assignmentQuerySchema.parse(req.query).agentId;
+    const q = assignmentQuerySchema.parse(req.query);
+    let agentId = (req.headers['x-agent-id'] as string | undefined) ?? q.agentId;
+
+    // Fallback: resolve agentId from name + workspace
+    if (!agentId && q.name) {
+      const found = q.workspace
+        ? db.prepare(
+            `SELECT id FROM coord_agents WHERE name = ? AND workspace = ? AND status != 'dead'`
+          ).get(q.name, q.workspace) as { id: string } | undefined
+        : db.prepare(
+            `SELECT id FROM coord_agents WHERE name = ? AND workspace IS NULL AND status != 'dead'`
+          ).get(q.name) as { id: string } | undefined;
+      agentId = found?.id;
+    }
 
     if (!agentId) {
       return reply.send({ assignment: null });
@@ -157,12 +278,13 @@ export function registerCoordinationRoutes(app: FastifyInstance, db: Database.Da
     const agentRow = db.prepare(`SELECT workspace FROM coord_agents WHERE id = ?`).get(agentId) as { workspace: string | null } | undefined;
     const agentWorkspace = agentRow?.workspace;
 
+    const blockedFilter = `AND (blocked_by IS NULL OR blocked_by IN (SELECT id FROM coord_assignments WHERE status = 'completed'))`;
     const pending = agentWorkspace
       ? db.prepare(
-          `SELECT * FROM coord_assignments WHERE status = 'pending' AND (workspace = ? OR workspace IS NULL) ORDER BY created_at ASC LIMIT 1`
+          `SELECT * FROM coord_assignments WHERE status = 'pending' AND (workspace = ? OR workspace IS NULL) ${blockedFilter} ORDER BY priority DESC, created_at ASC LIMIT 1`
         ).get(agentWorkspace) as { id: string } | undefined
       : db.prepare(
-          `SELECT * FROM coord_assignments WHERE status = 'pending' ORDER BY created_at ASC LIMIT 1`
+          `SELECT * FROM coord_assignments WHERE status = 'pending' ${blockedFilter} ORDER BY priority DESC, created_at ASC LIMIT 1`
         ).get() as { id: string } | undefined;
 
     if (pending) {
@@ -217,11 +339,23 @@ export function registerCoordinationRoutes(app: FastifyInstance, db: Database.Da
     return reply.send({ ok: true, assignmentId: id });
   });
 
-  function handleAssignmentUpdate(id: string, status: string, result: string | undefined) {
+  function handleAssignmentUpdate(id: string, status: string, result: string | undefined, commitSha: string | undefined): { error?: string } {
+    // Verification gate: completed status requires structured proof of work
+    if (status === 'completed') {
+      if (!result || result.trim().length < 20) {
+        return { error: 'completion requires a result summary — minimum 20 characters describing what was done' };
+      }
+      // Must mention at least one of: commit/SHA, build, audit, test, verified, fix, created, updated, implemented
+      const actionWords = /\b(commit|sha|[0-9a-f]{7,40}|build|audit|test|verified|fix|created|updated|implemented|added|refactored|documented)\b/i;
+      if (!actionWords.test(result)) {
+        return { error: 'completion result must describe the work done — include what was committed, built, tested, or verified' };
+      }
+    }
+
     if (['completed', 'failed'].includes(status)) {
       db.prepare(
-        `UPDATE coord_assignments SET status = ?, result = ?, completed_at = datetime('now') WHERE id = ?`
-      ).run(status, result ?? null, id);
+        `UPDATE coord_assignments SET status = ?, result = ?, commit_sha = ?, completed_at = datetime('now') WHERE id = ?`
+      ).run(status, result ?? null, commitSha ?? null, id);
     } else {
       db.prepare(
         `UPDATE coord_assignments SET status = ?, result = ? WHERE id = ?`
@@ -237,9 +371,12 @@ export function registerCoordinationRoutes(app: FastifyInstance, db: Database.Da
       }
     }
 
+    const eventDetail = ['completed', 'failed'].includes(status)
+      ? `${id} → ${status}${commitSha ? ' [' + commitSha + ']' : ''}: ${(result ?? '').slice(0, 300)}`
+      : `${id} → ${status}`;
     db.prepare(
       `INSERT INTO coord_events (agent_id, event_type, detail) VALUES ((SELECT agent_id FROM coord_assignments WHERE id = ?), 'assignment_update', ?)`
-    ).run(id, `${id} → ${status}`);
+    ).run(id, eventDetail);
 
     // Log completion/failure with agent name and task
     if (['completed', 'failed'].includes(status)) {
@@ -248,13 +385,39 @@ export function registerCoordinationRoutes(app: FastifyInstance, db: Database.Da
       ).get(id) as { task: string; agent_name: string | null } | undefined;
       coordLog(`${info?.agent_name ?? 'unknown'} ${status}: ${info?.task?.slice(0, 80) ?? id}`);
     }
+
+    return {};
   }
 
+  app.get('/assignment/:id', async (req, reply) => {
+    const { id } = assignmentIdParamSchema.parse(req.params);
+    const assignment = db.prepare(
+      `SELECT a.*, g.name AS agent_name FROM coord_assignments a LEFT JOIN coord_agents g ON a.agent_id = g.id WHERE a.id = ?`
+    ).get(id);
+    if (!assignment) return reply.code(404).send({ error: 'assignment not found' });
+    return reply.send({ assignment });
+  });
+
+  // List all non-completed assignments with priority and blocked_by status
+  app.get('/assignments', async (req, reply) => {
+    const assignments = db.prepare(
+      `SELECT a.*, g.name AS agent_name,
+              CASE WHEN a.blocked_by IS NOT NULL AND a.blocked_by NOT IN (SELECT id FROM coord_assignments WHERE status = 'completed')
+                   THEN 1 ELSE 0 END AS is_blocked
+       FROM coord_assignments a
+       LEFT JOIN coord_agents g ON a.agent_id = g.id
+       WHERE a.status NOT IN ('completed', 'failed')
+       ORDER BY a.priority DESC, a.created_at ASC`
+    ).all();
+    return reply.send({ assignments });
+  });
+
   app.post('/assignment/:id/update', async (req, reply) => {
     const { id } = assignmentIdParamSchema.parse(req.params);
     const parsed = assignmentUpdateSchema.safeParse(req.body);
     if (!parsed.success) return reply.code(400).send({ error: parsed.error.issues[0].message });
-    handleAssignmentUpdate(id, parsed.data.status, parsed.data.result);
+    const gate = handleAssignmentUpdate(id, parsed.data.status, parsed.data.result, parsed.data.commit_sha);
+    if (gate.error) return reply.code(400).send({ error: gate.error });
     return reply.send({ ok: true });
   });
 
@@ -262,7 +425,8 @@ export function registerCoordinationRoutes(app: FastifyInstance, db: Database.Da
     const { id } = assignmentIdParamSchema.parse(req.params);
     const parsed = assignmentUpdateSchema.safeParse(req.body);
     if (!parsed.success) return reply.code(400).send({ error: parsed.error.issues[0].message });
-    handleAssignmentUpdate(id, parsed.data.status, parsed.data.result);
+    const gate = handleAssignmentUpdate(id, parsed.data.status, parsed.data.result, parsed.data.commit_sha);
+    if (gate.error) return reply.code(400).send({ error: gate.error });
     return reply.send({ ok: true });
   });
 
@@ -270,7 +434,8 @@ export function registerCoordinationRoutes(app: FastifyInstance, db: Database.Da
     const { id } = assignmentIdParamSchema.parse(req.params);
     const parsed = assignmentUpdateSchema.safeParse(req.body);
     if (!parsed.success) return reply.code(400).send({ error: parsed.error.issues[0].message });
-    handleAssignmentUpdate(id, parsed.data.status, parsed.data.result);
+    const gate = handleAssignmentUpdate(id, parsed.data.status, parsed.data.result, parsed.data.commit_sha);
+    if (gate.error) return reply.code(400).send({ error: gate.error });
     return reply.send({ ok: true });
   });
 
@@ -507,6 +672,31 @@ export function registerCoordinationRoutes(app: FastifyInstance, db: Database.Da
     return reply.send({ total: total.total, bySeverity, byCategory });
   });
 
+  // ─── Decisions (cross-agent propagation) ────────────────────────
+
+  app.get('/decisions', async (req, reply) => {
+    const q = decisionsQuerySchema.safeParse(req.query);
+    const { since_id, assignment_id, limit } = q.success ? q.data : { since_id: 0, assignment_id: undefined, limit: 20 };
+
+    let sql = `
+      SELECT d.id, d.author_id, a.name AS author_name, d.assignment_id, d.tags, d.summary, d.created_at
+      FROM coord_decisions d JOIN coord_agents a ON d.author_id = a.id
+      WHERE d.id > ?
+    `;
+    const params: unknown[] = [since_id];
+
+    if (assignment_id) {
+      sql += ` AND d.assignment_id = ?`;
+      params.push(assignment_id);
+    }
+
+    sql += ` ORDER BY d.created_at ASC LIMIT ?`;
+    params.push(limit);
+
+    const decisions = db.prepare(sql).all(...params);
+    return reply.send({ decisions });
+  });
+
   // ─── Status ─────────────────────────────────────────────────────
 
   app.get('/status', async (_req, reply) => {

package/src/coordination/schema.ts

@@ -24,6 +24,10 @@ CREATE TABLE IF NOT EXISTS coord_agents (
   workspace    TEXT
 );
 
+-- Prevent duplicate agent registrations for the same name+workspace
+CREATE UNIQUE INDEX IF NOT EXISTS idx_coord_agents_name_workspace
+  ON coord_agents (name, COALESCE(workspace, ''));
+
 -- Coordination: assignments
 CREATE TABLE IF NOT EXISTS coord_assignments (
   id           TEXT PRIMARY KEY,
@@ -31,12 +35,16 @@ CREATE TABLE IF NOT EXISTS coord_assignments (
   task         TEXT NOT NULL,
   description  TEXT,
   status       TEXT NOT NULL DEFAULT 'pending',
+  priority     INTEGER NOT NULL DEFAULT 0,
+  blocked_by   TEXT,
   created_at   TEXT NOT NULL DEFAULT (datetime('now')),
   started_at   TEXT,
   completed_at TEXT,
   result       TEXT,
+  commit_sha   TEXT,
   workspace    TEXT,
-  FOREIGN KEY (agent_id) REFERENCES coord_agents(id)
+  FOREIGN KEY (agent_id) REFERENCES coord_agents(id),
+  FOREIGN KEY (blocked_by) REFERENCES coord_assignments(id)
 );
 
 -- Coordination: file locks
@@ -75,6 +83,19 @@ CREATE TABLE IF NOT EXISTS coord_findings (
   FOREIGN KEY (agent_id) REFERENCES coord_agents(id)
 );
 
+-- Coordination: cross-agent decision propagation
+CREATE TABLE IF NOT EXISTS coord_decisions (
+  id             INTEGER PRIMARY KEY AUTOINCREMENT,
+  author_id      TEXT NOT NULL,
+  assignment_id  TEXT,
+  tags           TEXT,
+  summary        TEXT NOT NULL,
+  created_at     TEXT NOT NULL DEFAULT (datetime('now')),
+  FOREIGN KEY (author_id) REFERENCES coord_agents(id)
+);
+CREATE INDEX IF NOT EXISTS idx_coord_decisions_assignment
+  ON coord_decisions (assignment_id, created_at);
+
 -- Coordination: event audit trail
 CREATE TABLE IF NOT EXISTS coord_events (
   id           INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -91,4 +112,9 @@ CREATE TABLE IF NOT EXISTS coord_events (
  */
 export function initCoordinationTables(db: Database.Database): void {
   db.exec(COORDINATION_TABLES);
+
+  // Migrations: add columns to existing coord_assignments tables
+  try { db.exec(`ALTER TABLE coord_assignments ADD COLUMN commit_sha TEXT`); } catch { /* exists */ }
+  try { db.exec(`ALTER TABLE coord_assignments ADD COLUMN priority INTEGER NOT NULL DEFAULT 0`); } catch { /* exists */ }
+  try { db.exec(`ALTER TABLE coord_assignments ADD COLUMN blocked_by TEXT`); } catch { /* exists */ }
 }

package/src/coordination/schemas.ts

@@ -43,13 +43,23 @@ export const assignCreateSchema = z.object({
   task: z.string().min(1).max(1000),
   description: z.string().max(5000).optional(),
   workspace: z.string().max(50).optional(),
+  priority: z.number().int().min(0).max(10).default(0),
+  blocked_by: z.string().uuid().optional(),
 });
 
 export const assignmentQuerySchema = z.object({
   agentId: z.string().uuid().optional(),
+  name: z.string().min(1).max(50).optional(),
   workspace: z.string().max(50).optional(),
 });
 
+export const nextSchema = z.object({
+  name: z.string().min(1).max(50),
+  workspace: z.string().max(50).optional(),
+  role: agentRoleEnum.default('worker'),
+  capabilities: z.array(z.string().max(50)).max(20).optional(),
+});
+
 export const assignmentClaimSchema = z.object({
   agentId: z.string().uuid(),
 });
@@ -57,6 +67,7 @@ export const assignmentClaimSchema = z.object({
 export const assignmentUpdateSchema = z.object({
   status: assignmentStatusEnum,
   result: z.string().max(10000).optional(),
+  commit_sha: z.string().max(100).optional(),
 });
 
 // ─── Locks ──────────────────────────────────────────────────────
@@ -118,6 +129,14 @@ export const pulseSchema = z.object({
   agentId: z.string().uuid(),
 });
 
+// ─── Decisions ─────────────────────────────────────────────────
+
+export const decisionsQuerySchema = z.object({
+  since_id: z.coerce.number().int().min(0).default(0),
+  assignment_id: z.string().max(100).optional(),
+  limit: z.coerce.number().int().min(1).max(200).default(20),
+});
+
 // ─── Status / Events ────────────────────────────────────────────
 
 export const eventsQuerySchema = z.object({

package/src/coordination/stale.ts

@@ -70,6 +70,14 @@ export function pruneOldHeartbeats(db: Database.Database): number {
   return result.changes;
 }
 
+/** Purge dead agents older than 24 hours to prevent table bloat. */
+export function purgeDeadAgents(db: Database.Database, maxAgeHours = 24): number {
+  const result = db.prepare(
+    `DELETE FROM coord_agents WHERE status = 'dead' AND last_seen < datetime('now', '-' || ? || ' hours')`
+  ).run(maxAgeHours);
+  return result.changes;
+}
+
 /** Clean slate on startup: mark all live agents dead, release locks, clear commands. */
 export function cleanSlate(db: Database.Database): void {
   const alive = db.prepare(