@cmgmyr/hive 0.1.0

package/dist/hook.js

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { awaitingFirstPromptSql } from "./firstPrompt.js";
+import { liveBackgroundTasks, SUBAGENT_LATCH_SQL, withholdsIdle } from "./backgroundTasks.js";
+let raw;
+function readRaw() {
+    if (raw === undefined) {
+        try {
+            raw = readFileSync(0, "utf8");
+        }
+        catch {
+            raw = null;
+        }
+    }
+    return raw;
+}
+let payload;
+function readPayload() {
+    if (payload === undefined) {
+        try {
+            payload = JSON.parse(readRaw() ?? "");
+        }
+        catch {
+            payload = {};
+        }
+    }
+    return payload;
+}
+const PAYLOAD_LIMIT = 10_000;
+const UNCHANGED = "unchanged";
+function record(actorId, event, state) {
+    try {
+        const payload = readRaw() ?? "";
+        const stored = payload.length > PAYLOAD_LIMIT
+            ? payload.slice(0, PAYLOAD_LIMIT) + `\n[hive: truncated at ${PAYLOAD_LIMIT} bytes]`
+            : payload;
+        db.prepare("INSERT INTO agent_state_log (actor_id, event, state, payload) VALUES (?, ?, ?, ?)").run(actorId, event, state, stored);
+    }
+    catch {
+    }
+}
+// Only a subagent withholds the latch. A shell or a monitor need never terminate, so latching on one
+// would make a worker that leaves any long-running process never read idle - src/scheduler.ts names
+// them in the standing notice instead (todo 468).
+//
+// Reads whichever channel the payload actually carries, never both: claude's Stop always carries
+// background_tasks, codex's never does. Mechanism and rationale: hive-internals, worker-state.md.
+function waitingOnSubagents(actorId, payload) {
+    if (payload.background_tasks !== undefined) {
+        return liveBackgroundTasks(payload.background_tasks).some(withholdsIdle);
+    }
+    return hasOpenSubagent(actorId);
+}
+// Subagents are a SET keyed by agent_id, not a stack of one - reduces every subagent_start/stop row
+// within SUBAGENT_LATCH_MAX_AGE_SECONDS in order, tracking which agent_ids are still unmatched.
+//
+// ACCEPTED, NOT OVERLOOKED: a subagent that genuinely outlives SUBAGENT_LATCH_MAX_AGE_SECONDS falls
+// out of this window, and the worker reads idle while it is still live - a false idle, the exact
+// direction this lane exists to prevent. Deliberate: latching forever is worse, and past this age
+// hive already treats the worker as stall-worthy on its own. Retention evicting a row early cannot
+// produce a NEW failure mode either, only an earlier instance of this same accepted one - see
+// .claude/skills/hive-internals/references/worker-state.md for the residual this does not fully close.
+function hasOpenSubagent(actorId) {
+    const rows = db
+        .prepare(`SELECT event, payload FROM agent_state_log
+        WHERE actor_id = ? AND event IN ('subagent_start', 'subagent_stop')
+          AND created_at >= datetime('now', ?)
+        ORDER BY id ASC`)
+        .all(actorId, SUBAGENT_LATCH_SQL);
+    const open = new Set();
+    for (const row of rows) {
+        let agentId;
+        try {
+            agentId = JSON.parse(row.payload).agent_id;
+        }
+        catch {
+            continue;
+        }
+        if (typeof agentId !== "string" || agentId === "")
+            continue;
+        if (row.event === "subagent_start")
+            open.add(agentId);
+        else
+            open.delete(agentId);
+    }
+    return open.size > 0;
+}
+// Claude-Code-Notification-only. Proven unreachable for codex, not merely unused: codex's own
+// hooks.json (src/codexHome.ts) never wires an event through the "notify" argv label, and never
+// wires PermissionRequest at all - see test/codex-notify-unreachable.test.mjs, which pins the event
+// list itself so a later lane adding an entry there has to decide this deliberately, not silently.
+function stateForNotification(payload) {
+    const type = payload.notification_type;
+    const idlePrompt = typeof type === "string"
+        ? type === "idle_prompt"
+        : /waiting for your input/i.test(String(payload.message ?? ""));
+    return idlePrompt ? null : "waiting";
+}
+// Each harness keys its own terminal-reason allowlist (HarnessCapabilities.terminalSessionEndReasons,
+// src/harnesses.ts) rather than sharing one: claude's `clear`, `other`, and an unobserved reason all
+// stop nothing (todo 765; test/fixtures/hook-payloads/README.md), and codex's vocabulary is disjoint
+// from claude's rather than a superset of it (todo 782).
+//
+// ~/.hive/hooks.json is one file per store, shared by every lead and every worker of every project,
+// so this event fires far more often than it acts. HIVE_LEAD is set only in a lead's own pane
+// (src/cli.ts, cmdLead's envFlags), and the project comes from that lead's own row rather than cwd.
+async function stopProcessesForEndedLead(actorId, payload) {
+    if (process.env.HIVE_LEAD !== "1")
+        return;
+    if (typeof payload.reason !== "string")
+        return;
+    const row = db
+        .prepare("SELECT project_id, command FROM agents WHERE actor_id = ? AND kind = 'lead' AND status = 'running'")
+        .get(actorId);
+    if (!row)
+        return;
+    // Imported here and nowhere above: harnesses.ts itself pulls tmux at module scope, and every
+    // other event in this file runs on every turn of every session without needing any of it.
+    const { harnessFor } = await import("./harnesses.js");
+    if (!harnessFor(row.command).terminalSessionEndReasons.includes(payload.reason))
+        return;
+    const { stopAllProcesses, STOP_REASONS } = await import("./processes.js");
+    stopAllProcesses(row.project_id, STOP_REASONS.leadSessionEnded);
+}
+function reconcileSessionId(actorId, payload) {
+    const sessionId = typeof payload.session_id === "string" ? payload.session_id : "";
+    if (!sessionId)
+        return;
+    db.prepare("UPDATE agents SET session_id = ? WHERE actor_id = ? AND kind = 'agent' AND session_id IS NOT ?").run(sessionId, actorId, sessionId);
+}
+// Claude's own payload carries transcript_path too (a directory-resolvable case hive already
+// covers via cwd), so this stores it for whichever harness sends it rather than special-casing
+// codex - the staleness reader is what decides which source to trust per harness (todo 591).
+function reconcileTranscriptPath(actorId, payload) {
+    const path = typeof payload.transcript_path === "string" ? payload.transcript_path : "";
+    if (!path)
+        return;
+    db.prepare("UPDATE agents SET transcript_path = ? WHERE actor_id = ? AND kind = 'agent' AND transcript_path IS NOT ?").run(path, actorId, path);
+}
+function stateFor(event, actorId) {
+    switch (event) {
+        case "prompt":
+            return "working";
+        case "stop":
+            return waitingOnSubagents(actorId, readPayload()) ? "working" : "idle";
+        case "notify":
+            return stateForNotification(readPayload());
+        // Log-only, like idle_prompt's null above: nothing forces a state write when a subagent starts
+        // or stops. hasOpenSubagent reads these rows back from agent_state_log at the next "stop" - the
+        // record() call below writes the row regardless of what this case returns.
+        case "subagent_start":
+        case "subagent_stop":
+            return null;
+        // An event hive has no case for does nothing, rather than asserting a state it doesn't have.
+        // Was "waiting" - proven indistinguishable from a real notify payload's own fallback (R4, TEST 3
+        // vs TEST 4: a PermissionRequest payload and a wholly unmapped event produced the identical
+        // "waiting"). That collision, not argv-vs-payload dispatch, was the actual defect.
+        default:
+            return null;
+    }
+}
+if (process.argv[2] === "post_tool_use") {
+    try {
+        const { runContextCheckpointHook } = await import("./contextCheckpoint.js");
+        runContextCheckpointHook(process.argv[3]);
+    }
+    catch { }
+    process.exit(0);
+}
+const { db } = await import("./db.js");
+try {
+    const actorId = process.env.HIVE_AGENT_ID;
+    if (actorId) {
+        const event = process.argv[2] ?? "";
+        const state = stateFor(event, actorId);
+        if (state !== null) {
+            db.prepare("UPDATE agents SET agent_state = ?, state_changed_at = datetime('now') WHERE actor_id = ? AND kind = 'agent'").run(state, actorId);
+        }
+        if (event === "prompt") {
+            db.prepare(`UPDATE agents SET resumed_at = '' WHERE actor_id = ? AND kind = 'agent' AND ${awaitingFirstPromptSql("agents")}`).run(actorId);
+        }
+        if (event === "session_end") {
+            try {
+                await stopProcessesForEndedLead(actorId, readPayload());
+            }
+            catch {
+            }
+        }
+        reconcileSessionId(actorId, readPayload());
+        reconcileTranscriptPath(actorId, readPayload());
+        db.prepare("UPDATE actors SET last_seen_at = datetime('now') WHERE id = ?").run(actorId);
+        record(actorId, event, state ?? UNCHANGED);
+    }
+}
+catch {
+}
+process.exit(0);

package/dist/hooks.js

@@ -0,0 +1,50 @@
+import { existsSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { dataDir, db } from "./db.js";
+import { shellQuote } from "./tmux.js";
+import { effectiveClaudeStatusLine, statusLineEntry } from "./statusline.js";
+// The single builder every generated hooks file wires an event through - reused by ensureHooksFile
+// (claude, one file per store) and ensureCodexHooksFile (codex, one file per worker CODEX_HOME),
+// so the two can never drift into different nesting for the same event name. See
+// .claude/skills/hive-internals/references/tmux-and-panes.md, "the hooks.json schema trap".
+export function hookEntry(event, contextRecord) {
+    const hookScript = join(dirname(fileURLToPath(import.meta.url)), "hook.js");
+    if (!existsSync(process.execPath)) {
+        throw new Error(`hive: this process's own interpreter (${process.execPath}) no longer exists on disk; refusing to register worker-state hooks under a path that would start nothing.`);
+    }
+    const node = shellQuote(process.execPath);
+    return { hooks: [{ type: "command", command: `${node} ${shellQuote(hookScript)} ${event}${contextRecord ? ` ${contextRecord}` : ""}` }] };
+}
+export function ensureHooksFile() {
+    const settings = stateHookSettings();
+    const path = join(dataDir, "hooks.json");
+    writeFileSync(path, JSON.stringify(settings, null, 2) + "\n");
+    return path;
+}
+function stateHookSettings() {
+    return {
+        hooks: {
+            Stop: [hookEntry("stop")],
+            UserPromptSubmit: [hookEntry("prompt")],
+            Notification: [hookEntry("notify")],
+            SessionEnd: [hookEntry("session_end")],
+        },
+    };
+}
+export function ensureWorkerHooksFile(agentId, options) {
+    const worker = db.prepare("SELECT cwd FROM agents WHERE id = ? AND kind = 'agent'").get(agentId);
+    if (!worker)
+        throw new Error(`hive: worker ${agentId} does not exist`);
+    const settings = {
+        ...stateHookSettings(),
+        statusLine: statusLineEntry(effectiveClaudeStatusLine(worker.cwd)),
+        permissions: { deny: ["SendMessage", "ListAgents"] },
+        crossSessionInbound: "refuse",
+    };
+    if (options.includePostToolUse)
+        settings.hooks.PostToolUse = [hookEntry("post_tool_use", "claude")];
+    const path = join(dataDir, `worker-${agentId}-hooks.json`);
+    writeFileSync(path, JSON.stringify(settings, null, 2) + "\n");
+    return path;
+}

package/dist/index.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { migrate } from "./db.js";
+import { registerAgents } from "./tools/agents.js";
+import { registerMeta } from "./tools/meta.js";
+import { registerPads } from "./tools/pads.js";
+import { registerTodos } from "./tools/todos.js";
+import { registerKv } from "./tools/kv.js";
+import { registerLeases } from "./tools/leases.js";
+import { registerWakes } from "./tools/wakes.js";
+import { registerPrompts } from "./prompts.js";
+import { startScheduler } from "./scheduler.js";
+import { enforceStrictInput } from "./strictInput.js";
+const server = enforceStrictInput(new McpServer({ name: "hive", version: "0.1.0" }, {
+    instructions: `Hive gives Claude Code sessions shared, persistent state for coordinating work on a project: pads for plans and findings, todos for tracked work with blockers, kv for small shared values, leases for claiming shared work areas, agents for spawning and directing other sessions, and wake-ups for scheduled or idle-triggered check-ins. Search for these tools when a task needs to persist past this conversation, hand off to or watch another session, or track multi-step work with dependencies.
+Getting started:
+1. Call whoami to see your actor identity and effective project scope.
+2. Call help for an overview, or help(topic="workflow") for the lead/worker playbook.
+3. Pads hold shared plans and findings. Todos coordinate work with blockers and comments. KV holds small shared values; leases claim shared work areas and expire on their own.
+4. Before triaging or orchestrating work, read the standing process: run \`hive runbook\` in a shell. It prints the project's profile runbook, or its runbook pad when the project has no profile. Do not read the pad first; most projects with a profile have no runbook pad at all.
+Scope discipline: all state is project-scoped, and the current project is the working directory's. An empty result means there is nothing IN THIS PROJECT; report that and stop. Never browse other projects' state (project_id overrides, project_select) unless the user explicitly names another project and asks for it.`,
+}));
+migrate();
+registerMeta(server);
+registerAgents(server);
+registerPads(server);
+registerTodos(server);
+registerKv(server);
+registerLeases(server);
+registerWakes(server);
+registerPrompts(server);
+startScheduler();
+await server.connect(new StdioServerTransport());

package/dist/kickoff.js

@@ -0,0 +1,191 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { cutToUnitBudget } from "./slug.js";
+export const OUTPUT_BUDGET = 10_000;
+const CONTEXT_BUDGET = 6_000;
+const BOARD_BUDGET = 1_800;
+function currentBranch(dir) {
+    try {
+        return execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+            cwd: dir,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+export function truncate(text, limit) {
+    if (text.length <= limit)
+        return text;
+    return `${cutToUnitBudget(text, limit).trimEnd()}\n[truncated]`;
+}
+async function digest(projectPath, profile, warnings) {
+    const { migrate, db } = await import("./db.js");
+    const { findProjectForCwd } = await import("./context.js");
+    const { ACTIVE_TIMER_WHERE } = await import("./scheduler.js");
+    const { getActivePadByName } = await import("./tools/pads.js");
+    const { OPEN_BLOCKERS_SQL } = await import("./tools/todos.js");
+    migrate();
+    const project = findProjectForCwd();
+    if (!project || project.path !== projectPath)
+        return null;
+    const lines = [`[hive] Project "${project.name}" (profile: ${profile}).`];
+    for (const w of warnings)
+        lines.push(`! hive.yml: ${w}`);
+    const headerLines = lines.length;
+    const board = getActivePadByName(project.id, "board");
+    if (board) {
+        lines.push("", "BOARD (top of the pad; pad_read for the rest)", truncate(board.content.trim(), BOARD_BUDGET));
+    }
+    const inFlight = db
+        .prepare("SELECT id, title, status, slug FROM todos WHERE project_id = ? AND status = 'in_progress' AND archived_at IS NULL ORDER BY updated_at DESC LIMIT 10")
+        .all(project.id);
+    const ready = db
+        .prepare(`SELECT id, title, slug FROM todos t
+       WHERE t.project_id = ? AND t.status = 'open' AND t.archived_at IS NULL
+         AND NOT EXISTS (${OPEN_BLOCKERS_SQL})
+       ORDER BY CASE priority WHEN 'high' THEN 0 WHEN 'medium' THEN 1 ELSE 2 END, id
+       LIMIT 10`)
+        .all(project.id);
+    const blocked = db
+        .prepare(`SELECT COUNT(*) AS n FROM todos t
+         WHERE t.project_id = ? AND t.status IN ('open', 'in_progress') AND t.archived_at IS NULL
+           AND EXISTS (${OPEN_BLOCKERS_SQL})`)
+        .get(project.id).n;
+    if (inFlight.length > 0) {
+        lines.push("", "IN FLIGHT");
+        for (const t of inFlight)
+            lines.push(`  #${t.id} ${t.slug ? `[${t.slug}] ` : ""}${t.title}`);
+    }
+    if (ready.length > 0) {
+        lines.push("", "READY (unblocked, highest priority first)");
+        for (const t of ready)
+            lines.push(`  #${t.id} ${t.slug ? `[${t.slug}] ` : ""}${t.title}`);
+    }
+    if (blocked > 0)
+        lines.push("", `BLOCKED: ${blocked} todo(s) waiting on a blocker.`);
+    const agents = db
+        .prepare("SELECT name, actor_id, command, agent_state, state_changed_at, kind, tmux_target, cwd, resumed_at " +
+        "FROM agents WHERE project_id = ? AND status = 'running' AND kind = 'agent' ORDER BY id")
+        .all(project.id);
+    if (agents.length > 0) {
+        const { deriveProvenance, describeForHuman } = await import("./stateProvenance.js");
+        lines.push("", "WORKERS (per the store, NOT probed; agent_list to confirm they are alive)");
+        for (const a of agents) {
+            lines.push(`  ${a.name} [${describeForHuman(deriveProvenance(a, null))}] ${a.cwd}`);
+        }
+    }
+    const parked = db
+        .prepare("SELECT COUNT(*) AS n FROM agents WHERE project_id = ? AND status = 'closed' AND parked_at != ''")
+        .get(project.id).n;
+    if (parked > 0) {
+        lines.push("", `PARKED: ${parked} lane(s) paused rather than finished, waiting to be resumed. ` +
+            "`hive status` lists each with its branch and the one call that brings it back.");
+    }
+    const wakes = db
+        .prepare(`SELECT COUNT(*) AS n FROM wakes WHERE project_id = ? AND ${ACTIVE_TIMER_WHERE}`)
+        .get(project.id);
+    if (wakes.n > 0)
+        lines.push("", `WAKE-UPS: ${wakes.n} pending (wake_list for detail).`);
+    if (lines.length === headerLines) {
+        lines.push("", "The store is empty for this project. Nothing is in flight.");
+    }
+    lines.push("", "Standing process for this project: run `hive runbook`.");
+    return truncate(lines.join("\n"), CONTEXT_BUDGET);
+}
+// Exported so src/cli.ts can hand the identical text to a codex lead as its initial CLI prompt -
+// codex's SessionStart hook rejects the whole payload if this rides inside hookSpecificOutput
+// (see the `forCodex` branch below), so a codex lead gets it a different way, not a different
+// message. Keep the two in sync by construction rather than by two literals staying equal.
+export const TRIAGE_MESSAGE = "Start with morning triage. Run `hive runbook` for this project's standing process, then " +
+    "reconcile the state hive just injected against what is really there (agent_list, todo_list, " +
+    "wake_list) and report it in a few lines. Propose today's lanes and confirm them with me before " +
+    "dispatching anything.";
+export async function evaluate(cwd, opts = {}) {
+    if (process.env.HIVE_AGENT_ID && process.env.HIVE_LEAD !== "1") {
+        return { fired: false, reason: "worker session (HIVE_AGENT_ID is set)" };
+    }
+    let dir;
+    try {
+        dir = realpathSync(cwd);
+    }
+    catch {
+        return { fired: false, reason: "cwd does not exist" };
+    }
+    if (!existsSync(join(dir, "hive.yml")))
+        return { fired: false, reason: "no hive.yml here" };
+    const { activeProfile, DEFAULT_LEAD_BRANCHES, loadProjectYml } = await import("./projectYml.js");
+    const { profileExists } = await import("./profiles.js");
+    const { config, warnings } = loadProjectYml(dir);
+    const silent = (reason) => ({ fired: false, reason, warnings });
+    const profile = activeProfile(config);
+    if (!profile)
+        return silent("no profile in hive.yml");
+    if (!profileExists(profile))
+        return silent(`profile "${profile}" is not on this machine`);
+    const branch = currentBranch(dir);
+    const leadBranches = config?.lead_branches ?? DEFAULT_LEAD_BRANCHES;
+    if (branch != null && !leadBranches.includes(branch)) {
+        return silent(`branch "${branch}" is not a lead branch (${leadBranches.join(", ")})`);
+    }
+    const context = await digest(dir, profile, warnings);
+    if (context == null)
+        return silent("not a registered hive project root");
+    // Codex's SessionStartHookSpecificOutputWire is additionalProperties:false and permits only
+    // hookEventName/additionalContext - initialUserMessage inside it fails the whole payload
+    // ("SessionStart Failed"), silently dropping the board too. Measured, todo 567 comment 1864.
+    const build = (text) => JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: "SessionStart",
+            additionalContext: text,
+            ...(opts.forCodex ? {} : { initialUserMessage: TRIAGE_MESSAGE }),
+        },
+    });
+    let payload = build(context);
+    if (payload.length > OUTPUT_BUDGET) {
+        const overflow = payload.length - OUTPUT_BUDGET;
+        payload = build(truncate(context, Math.max(0, context.length - overflow - 32)));
+    }
+    return { fired: true, payload, warnings };
+}
+export async function runKickoff(argv = []) {
+    const explain = argv.includes("--explain");
+    const forCodex = argv.includes("--codex");
+    let result;
+    try {
+        result = await evaluate(process.cwd(), { forCodex });
+    }
+    catch (e) {
+        if (explain)
+            console.log(`hive kickoff: silent (${e instanceof Error ? e.message : String(e)}).`);
+        return;
+    }
+    if (explain)
+        for (const w of result.warnings ?? [])
+            console.log(`! hive.yml: ${w}`);
+    if (result.fired && result.payload) {
+        process.stdout.write(result.payload);
+        if (explain)
+            process.stdout.write("\n");
+        return;
+    }
+    if (explain)
+        console.log(`hive kickoff: silent (${result.reason}).`);
+}
+const runDirectly = (() => {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    try {
+        return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+})();
+if (runDirectly)
+    await runKickoff(process.argv.slice(2));

package/dist/leadMessage.js

@@ -0,0 +1,98 @@
+import { db } from "./db.js";
+import { cutToUnitBudget, flatten } from "./slug.js";
+// 300 sits in the empty band between the two measured populations (todo 475): the largest lead-bound
+// message anyone has argued must arrive whole is 143 bytes, and the smallest real worker report is 440.
+export const LEAD_MESSAGE_THRESHOLD = 300;
+// Budgeted against that same 143, so a message of the class that must arrive whole survives as the head
+// essentially intact. A threshold alone only half-delivers the urgent case: a 450-character message whose
+// first line is "BLOCKED" is exactly what must not become a tool call. Do not trim this to save space.
+const HEAD_BUDGET = 140;
+const ELLIPSIS = "…";
+export const MESSAGE_RETENTION = "-7 days";
+// Bounds the ID RANGE, not the row count, copying LOG_MAX_ROWS's shipped shape: after a time prune leaves
+// a sparse id space it can fire with fewer rows than the name implies, which for a backstop is the safe
+// direction. Far above any observed rate, and lower than agent_state_log's 20,000 because a row here
+// holds unbounded message text rather than a hook payload.
+export const MESSAGE_MAX_ROWS = 5_000;
+function senderName(projectId, actorId) {
+    const row = db
+        .prepare(`SELECT name FROM agents WHERE project_id = ? AND actor_id = ?
+        ORDER BY (status = 'running') DESC, id DESC LIMIT 1`)
+        .get(projectId, actorId);
+    if (row !== undefined)
+        return row.name;
+    const actor = db.prepare("SELECT name FROM actors WHERE id = ?").get(actorId);
+    return actor?.name?.trim() || actorId;
+}
+export function senderTag(projectId, actorId) {
+    const row = db
+        .prepare(`SELECT name, kind FROM agents WHERE project_id = ? AND actor_id = ?
+        ORDER BY (status = 'running') DESC, id DESC LIMIT 1`)
+        .get(projectId, actorId);
+    if (row?.kind === "lead")
+        return "[hive:lead] ";
+    const name = row?.name ?? senderName(projectId, actorId);
+    return `[hive:${row ? "worker" : "agent"} ${flatten(name)}] `;
+}
+export function storeLeadMessage(projectId, fromActor, toAgentId, text) {
+    const fromName = senderName(projectId, fromActor);
+    const { id } = db
+        .prepare(`INSERT INTO agent_messages (project_id, from_actor, from_name, to_agent_id, text)
+       VALUES (?, ?, ?, ?, ?) RETURNING id`)
+        .get(projectId, fromActor, fromName, toAgentId, text);
+    return { id, fromName };
+}
+export function readLeadMessage(projectId, messageId) {
+    return db
+        .prepare(`SELECT id, from_actor, from_name, to_agent_id, text, created_at
+         FROM agent_messages WHERE id = ? AND project_id = ?`)
+        .get(messageId, projectId);
+}
+export function classifyMiss(messageId) {
+    const issued = db.prepare("SELECT seq FROM sqlite_sequence WHERE name = 'agent_messages'").get()?.seq;
+    if (issued === undefined || messageId > issued)
+        return "never-issued";
+    const elsewhere = db.prepare("SELECT 1 AS hit FROM agent_messages WHERE id = ?").get(messageId);
+    return elsewhere === undefined ? "pruned" : "other-project";
+}
+export function missMessage(messageId, kind) {
+    if (kind === "never-issued") {
+        return (`[agent_message_get:never-issued] No message ${messageId} has ever been issued in this store. ` +
+            "Nothing was pruned and nothing is being withheld: this id has not been handed out yet, so check " +
+            "the id in the pointer line you are reading it from.");
+    }
+    if (kind === "other-project") {
+        return (`[agent_message_get:other-project] Message ${messageId} exists but belongs to a different project, ` +
+            "and hive refuses cross-project reads. Read it from a session scoped to that project.");
+    }
+    return (`[agent_message_get:pruned] Message ${messageId} EXISTED and has since been pruned - this is expiry, ` +
+        `not a wrong id and not a scoping refusal. hive keeps agent messages for ${MESSAGE_RETENTION.replace("-", "")} ` +
+        `(and at most ${MESSAGE_MAX_ROWS} rows), and the janitor has deleted this one. The pointer line in your ` +
+        "scrollback outlives the row it names, by design: the text is gone from the store, so look for what the " +
+        "sender wrote to its todo or pad instead, which is the durable copy.");
+}
+// flatten, not slug.ts's stripControlChars: that one is [\x00-\x1F\x7F] and this is \p{Cc}\p{Cf}, which
+// also covers format characters. The head comes from outside, and a raw control byte in it reaches tmux
+// as a keystroke rather than as text, submitting this pointer early and splitting it. The sender's name
+// is flattened by senderTag when it builds the tag ahead of this marker - the tag is who, this is what.
+export function leadPointerMarker(id, text) {
+    return `[message #${id}, ${text.length} chars]`;
+}
+export function renderLeadPointer(id, text, tag) {
+    const flat = flatten(text);
+    const head = flat.length > HEAD_BUDGET ? cutToUnitBudget(flat, HEAD_BUDGET) + ELLIPSIS : flat;
+    return `${tag}${leadPointerMarker(id, text)} ${head} agent_message_get(${id}) for the full text.`;
+}
+export function shortenedSendNote(id, deliveredChars) {
+    return (`Over ${LEAD_MESSAGE_THRESHOLD} characters to a LEAD, so that pane got a ${deliveredChars}-character ` +
+        `pointer instead of this text: a lead's pane is a human's own window and hive keeps it quiet. Nothing ` +
+        `was lost - the full text is stored as message ${id} and the pointer names agent_message_get(${id}) - ` +
+        `but the lead reads the rest only if it chooses to. Put whatever must be ACTED on in the first ` +
+        `${HEAD_BUDGET} characters, or on the todo, where it is durable. Worker-bound sends are never shortened.`);
+}
+export function shortenedSendFailureClause(marker, id) {
+    return (` WHAT IS ON THAT SCREEN IS NOT YOUR TEXT. This send was over ${LEAD_MESSAGE_THRESHOLD} characters to a ` +
+        `LEAD, so what was pasted is hive's one-line pointer, opening \`${marker}\` - look for THAT line, not for ` +
+        `your own words, or you will conclude nothing arrived and resend. Your full text is already stored as ` +
+        `message ${id} whatever happens next: agent_message_get(${id}) returns it, so none of it is at risk here.`);
+}