@cmgmyr/hive 1.3.0 → 1.5.0

package/dist/leadState.js

@@ -0,0 +1,63 @@
+import { db } from "./db.js";
+import { FIRST_MESSAGE_SHA_ENV, firstMessageDigest } from "./firstMessage.js";
+export function readLeadTurnState(agentId) {
+    return db.prepare("SELECT * FROM lead_turn_state WHERE agent_id = ?").get(agentId) ?? null;
+}
+function isHiveFirstMessage(payload) {
+    if (typeof payload.prompt !== "string")
+        return false;
+    const prompt = payload.prompt.trim();
+    const launched = process.env[FIRST_MESSAGE_SHA_ENV];
+    return !!launched && firstMessageDigest(prompt) === launched;
+}
+// "idle" means the lead's turn ended after a prompt hive did not type itself, in this pane launch
+// and this session. It never means the lead finished all its work.
+export function nextLeadTurn(cur, panePid, event, payload, subagentsLive) {
+    const sessionId = typeof payload.session_id === "string" ? payload.session_id : "";
+    if (sessionId === "")
+        return null;
+    const sameEpoch = cur !== null && cur.pane_pid === panePid && cur.session_id === sessionId;
+    const base = sameEpoch
+        ? { pane_pid: panePid, session_id: sessionId, state: cur.state, idle_seq: cur.idle_seq }
+        : { pane_pid: panePid, session_id: sessionId, state: "unknown", idle_seq: cur?.idle_seq ?? 0 };
+    switch (event) {
+        case "prompt":
+            return isHiveFirstMessage(payload) ? base : { ...base, state: "working" };
+        case "stop":
+            if (base.state !== "working" || subagentsLive())
+                return base;
+            return { ...base, state: "idle", idle_seq: base.idle_seq + 1 };
+        case "session_end":
+            if (cur === null || cur.session_id !== sessionId)
+                return null;
+            return { pane_pid: cur.pane_pid, session_id: sessionId, state: "unknown", idle_seq: cur.idle_seq };
+        default:
+            return null;
+    }
+}
+const applyInTransaction = db.transaction((agentId, panePid, event, payload, subagentsLive) => {
+    const cur = readLeadTurnState(agentId);
+    const next = nextLeadTurn(cur, panePid, event, payload, subagentsLive);
+    if (next === null)
+        return;
+    if (cur !== null &&
+        cur.pane_pid === next.pane_pid &&
+        cur.session_id === next.session_id &&
+        cur.state === next.state &&
+        cur.idle_seq === next.idle_seq) {
+        return;
+    }
+    db.prepare(`INSERT INTO lead_turn_state (agent_id, pane_pid, session_id, state, idle_seq, last_event, changed_at)
+       VALUES (?, ?, ?, ?, ?, ?, strftime('%Y-%m-%d %H:%M:%f', 'now'))
+       ON CONFLICT(agent_id) DO UPDATE SET pane_pid = excluded.pane_pid, session_id = excluded.session_id,
+         state = excluded.state, idle_seq = excluded.idle_seq, last_event = excluded.last_event,
+         changed_at = excluded.changed_at`).run(agentId, next.pane_pid, next.session_id, next.state, next.idle_seq, event);
+});
+export function applyLeadHook(actorId, event, payload, subagentsLive) {
+    const lead = db
+        .prepare("SELECT id, pane_pid FROM agents WHERE actor_id = ? AND kind = 'lead' AND status = 'running' ORDER BY id DESC LIMIT 1")
+        .get(actorId);
+    if (!lead)
+        return;
+    applyInTransaction.immediate(lead.id, lead.pane_pid, event, payload, subagentsLive);
+}

package/dist/leadWatch.js

@@ -0,0 +1,73 @@
+import { db } from "./db.js";
+import { paneClassifierFor } from "./harnesses.js";
+import { readLeadTurnState } from "./leadState.js";
+import { LEAD_KIND } from "./spawn.js";
+import { holdsHumanInput, paneReissued, rowAliveProbe } from "./tmux.js";
+export const LEAD_TARGET_GONE = "LEAD_TARGET_GONE";
+export const LEAD_TARGET_REISSUED = "LEAD_TARGET_REISSUED";
+export const LEAD_TARGET_RESTARTED = "LEAD_TARGET_RESTARTED";
+const directPaneReaders = {
+    awaitingChoice: (pane, command) => paneClassifierFor(command)?.choiceCheck(pane).awaitingChoice ?? null,
+    holdsInput: (pane, command) => holdsHumanInput(paneClassifierFor(command)?.inputBoxState(pane) ?? null),
+};
+export function leadSubscription(wakeId) {
+    return (db.prepare("SELECT * FROM lead_idle_subscriptions WHERE wake_id = ?").get(wakeId) ??
+        null);
+}
+export function runningLeadOf(projectId) {
+    return (db
+        .prepare(`SELECT id, name, status, tmux_target, tmux_socket, pane_pid, command FROM agents
+          WHERE project_id = ? AND kind = ? AND status = 'running' ORDER BY id LIMIT 1`)
+        .get(projectId, LEAD_KIND) ?? null);
+}
+// Reads the watched lead's screen only to stay quiet; it can never make a lead read idle.
+export function paneVeto(lead, readers = directPaneReaders) {
+    const choice = readers.awaitingChoice(lead.tmux_target, lead.command);
+    if (choice === true)
+        return "it is on a dialog";
+    if (choice === null)
+        return "its screen could not be read";
+    if (readers.holdsInput(lead.tmux_target, lead.command))
+        return "it has unsubmitted text in its input box";
+    return null;
+}
+export function evaluateLeadWatch(sub, mode, snapshot, readers) {
+    const lead = db
+        .prepare("SELECT id, name, status, tmux_target, tmux_socket, pane_pid, command FROM agents WHERE id = ? AND kind = ?")
+        .get(sub.agent_id, LEAD_KIND);
+    if (!lead || lead.status !== "running")
+        return { kind: "invalid", reason: LEAD_TARGET_GONE };
+    if (lead.pane_pid !== sub.pane_pid)
+        return { kind: "invalid", reason: LEAD_TARGET_RESTARTED };
+    if (snapshot === null)
+        return { kind: "pending", reason: "tmux did not answer" };
+    const probe = rowAliveProbe(lead.tmux_socket, lead.tmux_target, snapshot);
+    if (probe.live === null)
+        return { kind: "pending", reason: "its pane cannot be probed from this process" };
+    if (!probe.live)
+        return { kind: "invalid", reason: LEAD_TARGET_GONE };
+    if (paneReissued(sub.pane_pid, probe))
+        return { kind: "invalid", reason: LEAD_TARGET_REISSUED };
+    const state = readLeadTurnState(lead.id);
+    if (state === null || state.pane_pid !== sub.pane_pid)
+        return { kind: "pending", reason: "no turn recorded yet" };
+    let session = sub.session_id;
+    if (session === "" && state.state !== "unknown") {
+        session = state.session_id;
+        try {
+            db.prepare("UPDATE lead_idle_subscriptions SET session_id = ? WHERE wake_id = ? AND session_id = ''").run(session, sub.wake_id);
+        }
+        catch {
+            // Unbound for another tick; the in-memory binding still judges this one.
+        }
+    }
+    if (session !== "" && state.session_id !== session)
+        return { kind: "invalid", reason: LEAD_TARGET_RESTARTED };
+    const ended = mode === "any" ? state.idle_seq > sub.baseline_idle_seq : state.state === "idle";
+    if (!ended)
+        return { kind: "pending", reason: `its turn state is ${state.state}` };
+    const vetoed = paneVeto(lead, readers);
+    if (vetoed !== null)
+        return { kind: "pending", reason: `its turn ended, but ${vetoed}` };
+    return { kind: "idle", idle_seq: state.idle_seq };
+}

package/dist/portfolio.js

@@ -0,0 +1,210 @@
+import { db } from "./db.js";
+import { listProjects } from "./context.js";
+import { existsSync } from "node:fs";
+import { parseTags } from "./result.js";
+import { OPEN_BLOCKERS_SQL } from "./tools/todos.js";
+import { readLeadTurnState } from "./leadState.js";
+import { liveTargets, paneReissued, rowAlive, rowAliveProbe } from "./tmux.js";
+export const PORTFOLIO_REASONS = [
+    "needs_human",
+    "dead_lead_pane",
+    "missing_root_with_work",
+    "worker_needs_input",
+    "wake_overdue_5m",
+    "in_progress_blocked",
+    "all_active_todos_blocked",
+    "stale_in_progress_48h",
+    "worker_working",
+    "todo_in_progress",
+    "wake_due_24h",
+    "quiet",
+];
+export const NEEDS_HUMAN_TAG = "needs-human";
+const NEEDS_HUMAN_ITEM_CAP = 5;
+const WAKE_OVERDUE_GRACE = "-5 minutes";
+const STALE_IN_PROGRESS = "-48 hours";
+const WAKE_UPCOMING = "+24 hours";
+export const ACTIVE_WAKE_WHERE = "cancelled_at IS NULL AND (fired_at IS NULL OR repeat_every_ms IS NOT NULL)";
+export function leadText(p) {
+    return p.lead.state === "alive" && p.lead.turn !== "unknown"
+        ? `alive, turn ${p.lead.turn === "working" ? "working" : "ended"}`
+        : p.lead.state;
+}
+function leadTurnFor(agentId, panePid) {
+    const row = readLeadTurnState(agentId);
+    if (row === null || row.pane_pid !== panePid)
+        return "unknown";
+    return row.state === "working" ? "working" : row.state === "idle" ? "turn_ended" : "unknown";
+}
+const ONE = (sql, ...params) => db.prepare(sql).get(...params);
+function shiftedClock(now, modifier) {
+    return ONE("SELECT datetime(?, ?) AS t", now, modifier).t;
+}
+function lastActivity(projectId, countWakeFires = true) {
+    const row = ONE(`SELECT MAX(t) AS t FROM (
+       SELECT created_at AS t FROM projects WHERE id = :pid
+       UNION ALL SELECT updated_at FROM todos WHERE project_id = :pid
+       UNION ALL SELECT c.created_at FROM todo_comments c JOIN todos t ON t.id = c.todo_id WHERE t.project_id = :pid
+       UNION ALL SELECT updated_at FROM pads WHERE project_id = :pid
+       UNION ALL SELECT created_at FROM agents WHERE project_id = :pid
+       UNION ALL SELECT state_changed_at FROM agents WHERE project_id = :pid
+       UNION ALL SELECT substr(l.created_at, 1, 19) FROM agent_state_log l
+         WHERE l.actor_id IN (SELECT actor_id FROM agents WHERE project_id = :pid)
+       UNION ALL SELECT created_at FROM wakes WHERE project_id = :pid
+       ${countWakeFires ? "UNION ALL SELECT fired_at FROM wakes WHERE project_id = :pid" : ""}
+     )`, { pid: projectId });
+    return row.t;
+}
+function projectRow(project, now, snapshot) {
+    const rootExists = existsSync(project.path);
+    const todoRows = db
+        .prepare(`SELECT t.id, t.title, t.slug, t.priority, t.status, t.tags, t.updated_at,
+              EXISTS (${OPEN_BLOCKERS_SQL}) AS blocked
+         FROM todos t
+        WHERE t.project_id = ? AND t.status IN ('open', 'in_progress') AND t.archived_at IS NULL`)
+        .all(project.id);
+    const todos = { open: 0, in_progress: 0, blocked: 0, blocked_in_progress: 0, high: 0 };
+    const tagged = [];
+    for (const t of todoRows) {
+        if (t.status === "open")
+            todos.open++;
+        else
+            todos.in_progress++;
+        if (t.blocked) {
+            todos.blocked++;
+            if (t.status === "in_progress")
+                todos.blocked_in_progress++;
+        }
+        if (t.priority === "high")
+            todos.high++;
+        if (parseTags(t.tags).includes(NEEDS_HUMAN_TAG))
+            tagged.push(t);
+    }
+    tagged.sort((a, b) => (a.updated_at < b.updated_at ? -1 : a.updated_at > b.updated_at ? 1 : a.id - b.id));
+    const agents = db
+        .prepare("SELECT id, kind, agent_state, tmux_target, tmux_socket, pane_pid FROM agents WHERE project_id = ? AND status = 'running' ORDER BY id")
+        .all(project.id);
+    const liveness = (a) => snapshot ? rowAlive(a.tmux_socket, a.tmux_target, snapshot) : null;
+    const reissued = (a) => snapshot !== null && paneReissued(a.pane_pid, rowAliveProbe(a.tmux_socket, a.tmux_target, snapshot));
+    const workers = { working: 0, idle: 0, needs_input: 0, other: 0, unreachable: 0, unconfirmed: 0 };
+    let liveWorking = 0;
+    let liveWaiting = 0;
+    let lead = { state: "none", agent_id: null, turn: "unknown" };
+    for (const a of agents) {
+        if (a.kind === "lead") {
+            const live = reissued(a) ? false : liveness(a);
+            lead = {
+                state: live === true ? "alive" : live === false ? "dead_pane" : "unknown",
+                agent_id: a.id,
+                turn: live === true ? leadTurnFor(a.id, a.pane_pid) : "unknown",
+            };
+            continue;
+        }
+        if (a.kind !== "agent")
+            continue;
+        const live = reissued(a) ? false : liveness(a);
+        if (live === false)
+            workers.unreachable++;
+        else if (live === null)
+            workers.unconfirmed++;
+        else if (a.agent_state === "working") {
+            workers.working++;
+            liveWorking++;
+        }
+        else if (a.agent_state === "idle")
+            workers.idle++;
+        else if (a.agent_state === "waiting") {
+            workers.needs_input++;
+            liveWaiting++;
+        }
+        else
+            workers.other++;
+    }
+    const overdueBefore = shiftedClock(now, WAKE_OVERDUE_GRACE);
+    const upcomingUntil = shiftedClock(now, WAKE_UPCOMING);
+    const wakeCounts = db
+        .prepare(`SELECT COUNT(*) AS pending,
+              COALESCE(SUM(held_at IS NULL AND COALESCE(due_at, max_wait_at) < ?), 0) AS overdue,
+              COALESCE(SUM(held_at IS NULL AND COALESCE(due_at, max_wait_at) <= ?), 0) AS overdue_grace,
+              COALESCE(SUM(COALESCE(due_at, max_wait_at) > ? AND COALESCE(due_at, max_wait_at) <= ?), 0) AS upcoming
+         FROM wakes WHERE project_id = ? AND ${ACTIVE_WAKE_WHERE}`)
+        .get(now, overdueBefore, overdueBefore, upcomingUntil, project.id);
+    const lastActivityAt = lastActivity(project.id);
+    const staleClock = lastActivity(project.id, false);
+    const staleBefore = shiftedClock(now, STALE_IN_PROGRESS);
+    const activeTodos = todos.open + todos.in_progress;
+    const found = new Set();
+    if (tagged.length > 0)
+        found.add("needs_human");
+    if (lead.state === "dead_pane" && (todos.in_progress > 0 || wakeCounts.pending > 0))
+        found.add("dead_lead_pane");
+    if (!rootExists && (activeTodos > 0 || wakeCounts.pending > 0))
+        found.add("missing_root_with_work");
+    if (liveWaiting > 0)
+        found.add("worker_needs_input");
+    if (wakeCounts.overdue_grace > 0)
+        found.add("wake_overdue_5m");
+    if (todos.blocked_in_progress > 0)
+        found.add("in_progress_blocked");
+    if (activeTodos > 0 && todos.blocked === activeTodos)
+        found.add("all_active_todos_blocked");
+    if (todos.in_progress > 0 && liveWorking === 0 && staleClock <= staleBefore)
+        found.add("stale_in_progress_48h");
+    if (liveWorking > 0)
+        found.add("worker_working");
+    if (todos.in_progress > 0)
+        found.add("todo_in_progress");
+    if (wakeCounts.upcoming > 0)
+        found.add("wake_due_24h");
+    const HARD_STALL = [
+        "dead_lead_pane",
+        "missing_root_with_work",
+        "worker_needs_input",
+        "wake_overdue_5m",
+    ];
+    const TODO_GRAPH = ["in_progress_blocked", "all_active_todos_blocked", "stale_in_progress_48h"];
+    const freshInProgress = todos.in_progress > todos.blocked_in_progress && !found.has("stale_in_progress_48h");
+    const movingSignal = liveWorking > 0 || freshInProgress;
+    let lane;
+    if (HARD_STALL.some((r) => found.has(r)))
+        lane = "stuck";
+    else if (movingSignal)
+        lane = "moving";
+    else if (found.has("needs_human"))
+        lane = "waiting_on_you";
+    else if (TODO_GRAPH.some((r) => found.has(r)))
+        lane = "stuck";
+    else {
+        lane = "quiet";
+        found.add("quiet");
+    }
+    return {
+        id: project.id,
+        name: project.name,
+        root: project.path,
+        root_exists: rootExists,
+        lane,
+        reasons: PORTFOLIO_REASONS.filter((r) => found.has(r)),
+        lead,
+        workers,
+        todos,
+        needs_human: tagged.length,
+        needs_human_items: tagged.slice(0, NEEDS_HUMAN_ITEM_CAP).map((t) => ({
+            todo_id: t.id,
+            title: t.title,
+            slug: t.slug === "" ? null : t.slug,
+            updated_at: t.updated_at,
+        })),
+        last_activity_at: lastActivityAt,
+        wakes: { pending: wakeCounts.pending, overdue: wakeCounts.overdue },
+    };
+}
+export function collectPortfolio(now) {
+    const asOf = now ?? ONE("SELECT datetime('now') AS now").now;
+    const snapshot = liveTargets();
+    const projects = listProjects().map((p) => projectRow(p, asOf, snapshot));
+    const lanes = { waiting_on_you: 0, stuck: 0, moving: 0, quiet: 0 };
+    for (const p of projects)
+        lanes[p.lane]++;
+    return { schema_version: 1, as_of: asOf, totals: { projects: projects.length, lanes }, projects };
+}

package/dist/projectRemove.js

@@ -0,0 +1,68 @@
+import { backupNow } from "./backup.js";
+import { dataDir, db } from "./db.js";
+export const PROJECT_OWNER_TABLES = [
+    "pads",
+    "todos",
+    "kv",
+    "leases",
+    "agents",
+    "wakes",
+    "command_trust",
+];
+const COUNTED_TABLES = [
+    ...PROJECT_OWNER_TABLES.map((t) => [t, `SELECT COUNT(*) AS n FROM ${t} WHERE project_id = ?`]),
+    ["todo_comments", "SELECT COUNT(*) AS n FROM todo_comments WHERE todo_id IN (SELECT id FROM todos WHERE project_id = ?)"],
+    ["agent_messages", "SELECT COUNT(*) AS n FROM agent_messages WHERE project_id = ?"],
+];
+export function projectRowCounts(projectId) {
+    const counts = {};
+    for (const [table, sql] of COUNTED_TABLES) {
+        const n = db.prepare(sql).get(projectId).n;
+        if (n > 0)
+            counts[table] = n;
+    }
+    return counts;
+}
+export function formatRowCounts(counts) {
+    return Object.entries(counts)
+        .map(([table, n]) => `${table}: ${n}`)
+        .join(", ");
+}
+function assertNoRunningAgents(projectId, name) {
+    const running = db
+        .prepare("SELECT id, name FROM agents WHERE project_id = ? AND status = 'running' ORDER BY id")
+        .all(projectId);
+    if (running.length === 0)
+        return;
+    const names = running.map((a) => `${a.name} (agent ${a.id})`).join(", ");
+    throw new Error(`project ${projectId} ("${name}") has running agents: ${names}. Nothing deleted. Run hive doctor to close rows whose panes are gone, or agent_close them.`);
+}
+const deleteProjectRows = db.transaction((projectId, name, expected, after) => {
+    assertNoRunningAgents(projectId, name);
+    if (JSON.stringify(projectRowCounts(projectId)) !== JSON.stringify(expected)) {
+        throw new Error(`project ${projectId} ("${name}") changed while the snapshot was taken; nothing removed, run it again.`);
+    }
+    db.prepare("DELETE FROM agent_messages WHERE project_id = ?").run(projectId);
+    if (db.prepare("DELETE FROM projects WHERE id = ?").run(projectId).changes === 0) {
+        throw new Error(`no project ${projectId}.`);
+    }
+    after();
+});
+export function removeProject(projectId, opts) {
+    const target = db.prepare("SELECT id, name, path FROM projects WHERE id = ?").get(projectId);
+    if (!target)
+        throw new Error(`no project ${projectId}.`);
+    assertNoRunningAgents(projectId, target.name);
+    const counts = projectRowCounts(projectId);
+    let snapshot = null;
+    if (opts.snapshot) {
+        const result = backupNow(db, dataDir, "manual");
+        if (!result.ok)
+            throw new Error(`could not snapshot the store first, nothing deleted: ${result.error ?? "unknown error"}`);
+        snapshot = result.path ?? null;
+    }
+    opts.afterSnapshot?.();
+    const removed = { deleted: { id: target.id, name: target.name, path: target.path }, counts, snapshot };
+    deleteProjectRows.immediate(projectId, target.name, counts, () => opts.onRemoved?.(removed));
+    return removed;
+}

package/dist/projectYml.js

@@ -14,6 +14,7 @@ export const BUILT_IN_PROJECT_YML = Object.freeze({
     profile: null,
     agents: null,
     lead_branches: null,
+    first_message: null,
     context_checkpoint_percent: null,
     lead_turn_budget: null,
     dashboard: false,
@@ -55,6 +56,15 @@ export function mergedProjectVars(config) {
         delete safe[key];
     return { ...safe, ...agentVars(config) };
 }
+// Absent sends nothing; "" (or whitespace only) also sends nothing, and a project one beats a global message.
+export function resolveFirstMessage(config, sources = {}) {
+    const value = config?.first_message;
+    if (value == null)
+        return { message: "", source: "unset" };
+    if (value.trim() === "")
+        return { message: "", source: "empty" };
+    return { message: value, source: sources.first_message === "global" ? "global" : "project" };
+}
 function isMapping(value) {
     if (value === null || typeof value !== "object" || Array.isArray(value))
         return false;
@@ -225,6 +235,15 @@ function applyLayer(root, path, source, config, sources, warnings) {
         else
             warn("lead_branches must be a list of branch names; ignoring it.");
     }
+    if (has("first_message")) {
+        const value = root.first_message;
+        if (value == null || typeof value === "string") {
+            config.first_message = value ?? "";
+            sources.first_message = source;
+        }
+        else
+            warn("first_message must be a string; ignoring it.");
+    }
     if (has("vars")) {
         const value = root.vars;
         if (value == null) {

package/dist/queenAudit.js

@@ -0,0 +1,132 @@
+import { captureQueenWriteIdentity, effectiveProjectId, isQueenLead } from "./context.js";
+import { db } from "./db.js";
+import { cutToUnitBudget, flatten } from "./slug.js";
+export const QUEEN_AUDIT_SUMMARY_MAX = 160;
+export const QUEEN_AUDIT_DEFAULT_LIMIT = 20;
+export const QUEEN_AUDIT_MAX_LIMIT = 100;
+export const QUEEN_AUDIT_RETENTION = "-30 days";
+export const QUEEN_AUDIT_MAX_ROWS = 20_000;
+function resource(type, value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0 ? { type, id: value } : null;
+}
+function removalSummary(r) {
+    const counts = Object.entries((r.counts ?? {})).map(([t, n]) => `${t} ${n}`);
+    return `removed project "${r.name}"${counts.length > 0 ? ` with ${counts.join(", ")}` : ""}`;
+}
+export const QUEEN_AUDIT_OPERATIONS = {
+    todo_create: {
+        mode: "database",
+        resource: (r) => resource("todo", r.todo_id),
+        summary: (a) => String(a.title),
+    },
+    todo_comment: {
+        mode: "database",
+        resource: (r) => resource("todo_comment", r.comment_id),
+        summary: (a) => `todo #${a.todo_id}: ${a.body}`,
+    },
+    wake_set: {
+        mode: "database",
+        resource: (r) => resource("wake", r.wake_id),
+        summary: (a, r) => `to ${r.deliver_to}: ${a.body}`,
+    },
+    wake_when_idle: {
+        mode: "database",
+        resource: (r) => r.status === "already_satisfied" ? null : resource("wake", r.wake_id),
+        summary: (a, r) => `${a.mode ?? "any"} to ${r.deliver_to}: ${a.body}`,
+    },
+    wake_update: {
+        mode: "database",
+        resource: (r) => r.updated === true ? resource("wake", r.wake_id) : null,
+        summary: (a) => `changed ${["body", "delay_seconds", "repeat_every_seconds"].filter((key) => a[key] !== undefined).join(", ")}${a.body === undefined ? "" : `: ${a.body}`}`,
+    },
+    wake_cancel: {
+        mode: "database",
+        resource: (r) => r.cancelled === true ? resource("wake", r.wake_id) : null,
+        summary: (_a, r) => `cancelled; notices ${r.cancelled_notices ?? 0}`,
+    },
+    agent_send: {
+        mode: "external",
+        resource: (r) => r.sent === true ? resource("agent", r.agent_id) : null,
+        summary: (a, r) => `agent #${r.agent_id} ${a.submit === false ? "pasted without submit" : "submitted"}: ${a.text}`,
+    },
+    project_prune: {
+        mode: "database",
+        resource: (r) => resource("project", r.project_id),
+        summary: (_a, r) => removalSummary(r),
+    },
+    "hive project rm": {
+        mode: "database",
+        resource: (r) => resource("project", r.project_id),
+        summary: (_a, r) => removalSummary(r),
+    },
+    "hive lead": {
+        mode: "external",
+        resource: (r) => r.disposition === "started" || r.disposition === "adopted" ? resource("agent", r.agent_id) : null,
+        summary: (a, r) => `${r.disposition} lead #${r.agent_id}${a.detach ? " detached" : ""}`,
+    },
+};
+function descriptor(operation) {
+    const found = Object.hasOwn(QUEEN_AUDIT_OPERATIONS, operation) ? QUEEN_AUDIT_OPERATIONS[operation] : undefined;
+    if (!found)
+        throw new Error(`[queen_audit:missing-coverage] ${operation} has no audit descriptor`);
+    return found;
+}
+function insertAudit(operation, targetProjectId, args, receipt, identity) {
+    const spec = descriptor(operation);
+    const touched = spec.resource(receipt);
+    if (!touched)
+        return;
+    const text = flatten(spec.summary(args, receipt));
+    const summary = text.length <= QUEEN_AUDIT_SUMMARY_MAX ? text : cutToUnitBudget(text, QUEEN_AUDIT_SUMMARY_MAX - 1) + "…";
+    db.prepare(`INSERT INTO queen_audit (actor_id, home_project_id, target_project_id, operation, resource_type, resource_id, summary)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`).run(identity.actor_id, identity.home_project_id, targetProjectId, operation, touched.type, touched.id, summary);
+}
+export function commitQueenStateWrite(operation, targetProjectId, args, mutate) {
+    const identity = captureQueenWriteIdentity(targetProjectId);
+    if (!identity)
+        return mutate();
+    const spec = descriptor(operation);
+    if (spec.mode !== "database")
+        throw new Error(`[queen_audit:wrong-mode] ${operation} is not a database write`);
+    return db.transaction(() => {
+        const receipt = mutate();
+        insertAudit(operation, targetProjectId, args, receipt, identity);
+        return receipt;
+    }).immediate();
+}
+export function confirmQueenWrite(operation, targetProjectId, args, receipt, identity = captureQueenWriteIdentity(targetProjectId)) {
+    if (!identity)
+        return;
+    try {
+        insertAudit(operation, targetProjectId, args, receipt, identity);
+    }
+    catch (e) {
+        if (operation !== "agent_send")
+            throw e;
+        throw new Error(`[queen_audit:write-completed-audit-failed] agent #${receipt.agent_id}: the text already landed. Do not resend blindly. ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+function positiveInteger(value, name) {
+    if (!Number.isInteger(value) || value <= 0)
+        throw new Error(`${name} must be a positive integer`);
+}
+export function recentQueenAudit(limit) {
+    return db.prepare("SELECT * FROM queen_audit ORDER BY id DESC LIMIT ?").all(limit);
+}
+export function listQueenAudit(options = {}, homeProjectId) {
+    const requestedLimit = options.limit ?? QUEEN_AUDIT_DEFAULT_LIMIT;
+    positiveInteger(requestedLimit, "limit");
+    if (options.project_id !== undefined)
+        positiveInteger(options.project_id, "project_id");
+    const target = options.project_id === undefined ? null : effectiveProjectId(options.project_id);
+    const queen = isQueenLead();
+    const home = queen ? null : homeProjectId ?? effectiveProjectId();
+    if (!queen && target !== null && target !== home)
+        throw new Error("Queen audit access is limited to your own project");
+    const projectId = target ?? home;
+    const limit = Math.min(requestedLimit, QUEEN_AUDIT_MAX_LIMIT);
+    const entries = (projectId === null
+        ? db.prepare("SELECT * FROM queen_audit ORDER BY id DESC LIMIT ?").all(limit)
+        : db.prepare("SELECT * FROM queen_audit WHERE target_project_id = ? ORDER BY id DESC LIMIT ?").all(projectId, limit));
+    return { entries, limit, project_id: projectId };
+}