@cmgmyr/hive 1.10.0 → 1.11.0

package/dist/hook.js

@@ -177,6 +177,13 @@ async function stopProcessesForEndedLead(actorId, payload) {
         .get(actorId);
     if (!row)
         return;
+    // A deliberate handoff's predecessor ending is not the lead ending; its successor keeps the crew.
+    const lead = db.prepare("SELECT id FROM agents WHERE actor_id = ? AND kind = 'lead' AND status = 'running'").get(actorId);
+    if (lead !== undefined) {
+        const { predecessorFence } = await import("./leadState.js");
+        if (predecessorFence(lead.id, payload.session_id))
+            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");
@@ -313,7 +320,8 @@ try {
         if (!guarded)
             state = applyWorkerTransition(actorId, event);
         // A lead's turn state is its own table; agents.agent_state stays worker-only.
-        if (process.env.HIVE_LEAD === "1" && (event === "prompt" || event === "stop" || event === "session_end")) {
+        if (process.env.HIVE_LEAD === "1" &&
+            ["prompt", "stop", "session_end"].includes(event)) {
             try {
                 const { applyLeadHook } = await import("./leadState.js");
                 applyLeadHook(actorId, event, readPayload(), () => waitingOnSubagents(actorId, readPayload()));
@@ -321,6 +329,18 @@ try {
             catch {
             }
         }
+        if (event === "stop" && process.env.HIVE_LEAD === "1") {
+            try {
+                const started = db
+                    .prepare(`SELECT 1 AS hit FROM lead_handoffs h JOIN agents a ON a.id = h.lead_agent_id
+              WHERE a.actor_id = ? AND a.kind = 'lead' AND h.state = 'started'`)
+                    .get(actorId);
+                if (started !== undefined)
+                    (await import("./leadHandoff.js")).completeHandoffOnStop(actorId);
+            }
+            catch {
+            }
+        }
         if (event === "session_start" && process.env.HIVE_LEAD === "1") {
             try {
                 await registerLeadMessagingSocket(actorId);
@@ -340,7 +360,17 @@ try {
             reconcileTranscriptPath(actorId, hookPayload);
             db.prepare("UPDATE actors SET last_seen_at = datetime('now') WHERE id = ?").run(actorId);
         }
-        record(actorId, event, state ?? UNCHANGED);
+        let logState = state ?? UNCHANGED;
+        if (event === "prompt" && process.env.HIVE_LEAD === "1") {
+            try {
+                const { isHiveFirstMessage, FIRST_MESSAGE_LOG_STATE } = await import("./leadState.js");
+                if (isHiveFirstMessage(readPayload()))
+                    logState = FIRST_MESSAGE_LOG_STATE;
+            }
+            catch {
+            }
+        }
+        record(actorId, event, logState);
     }
 }
 catch {

package/dist/index.js

@@ -10,6 +10,7 @@ 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 { registerQuestions } from "./tools/questions.js";
 import { registerQueenAudit } from "./tools/queenAudit.js";
 import { registerPrompts } from "./prompts.js";
 import { schedulerIntervalMs, startScheduler } from "./scheduler.js";
@@ -34,6 +35,7 @@ registerTodos(server);
 registerKv(server);
 registerLeases(server);
 registerWakes(server);
+registerQuestions(server);
 registerQueenAudit(server);
 registerPrompts(server);
 startScheduler(schedulerIntervalMs());

package/dist/kickoff.js

@@ -97,6 +97,20 @@ async function digest(projectPath, profile, warnings) {
     lines.push("", "Standing process for this project: run `hive runbook`.");
     return truncate(lines.join("\n"), CONTEXT_BUDGET);
 }
+// Lead-only: a worker returned above, and a session hive did not start as a lead gets nothing.
+async function leadHandoffText() {
+    const actor = process.env.HIVE_AGENT_ID;
+    if (process.env.HIVE_LEAD !== "1" || !actor)
+        return null;
+    try {
+        const { migrate } = await import("./db.js");
+        migrate();
+        return (await import("./leadHandoff.js")).handoffInjection(actor);
+    }
+    catch {
+        return null;
+    }
+}
 // Shared with `hive lead`, which passes the first message on the command line only when this holds.
 export async function kickoffGate(dir) {
     const { activeProfile, DEFAULT_LEAD_BRANCHES, loadProjectYml } = await import("./projectYml.js");
@@ -128,13 +142,20 @@ export async function evaluate(cwd, opts = {}) {
     catch {
         return { fired: false, reason: "cwd does not exist" };
     }
+    const handoff = await leadHandoffText();
+    const handoffOnly = (warnings) => ({
+        fired: true,
+        payload: JSON.stringify({ hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: handoff } }),
+        warnings,
+    });
     const gate = await kickoffGate(dir);
     if (!gate.ok)
-        return { fired: false, reason: gate.reason, warnings: gate.warnings };
+        return handoff === null ? { fired: false, reason: gate.reason, warnings: gate.warnings } : handoffOnly(gate.warnings);
     const { config, warnings, sources, profile } = gate;
     const context = await digest(dir, profile, warnings);
-    if (context == null)
-        return { fired: false, reason: "not a registered hive project root", warnings };
+    if (context == null) {
+        return handoff === null ? { fired: false, reason: "not a registered hive project root", warnings } : handoffOnly(warnings);
+    }
     // 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.
@@ -145,13 +166,15 @@ export async function evaluate(cwd, opts = {}) {
     const build = (text) => JSON.stringify({
         hookSpecificOutput: {
             hookEventName: "SessionStart",
-            additionalContext: text,
+            additionalContext: handoff === null ? text : `${text}\n\n${handoff}`,
             ...(hookMessage === null ? {} : { initialUserMessage: hookMessage }),
         },
     });
     let payload = build(context);
-    if (payload.length > OUTPUT_BUDGET) {
-        const overflow = payload.length - OUTPUT_BUDGET;
+    // The handoff rides outside the digest budget: only the digest is ever cut to fit.
+    const budget = OUTPUT_BUDGET + (handoff === null ? 0 : JSON.stringify(handoff).length);
+    if (payload.length > budget) {
+        const overflow = payload.length - budget;
         payload = build(truncate(context, Math.max(0, context.length - overflow - 32)));
     }
     return { fired: true, payload, warnings, firstMessage: first };

package/dist/leadHandoff.js

@@ -0,0 +1,525 @@
+import { createHash } from "node:crypto";
+import { db } from "./db.js";
+import { harnessFor, paneClassifierFor } from "./harnesses.js";
+import { casHandoff, HELD_REASON_HANDOFF, handoffHoldsAutomation, nowSql, olderThan, PASS_TIMEOUT_SECONDS, PRE_RESPAWN_STATES, passPolicy, quotedPolicy, readActiveHandoff, readHandoff, STOP_HOLD_CAP_SECONDS, SUCCESSOR_NOT_READY, } from "./leadHandoffState.js";
+import { holdsHumanInput, paneInCopyMode, rowOwnership, tmuxSocketPath } from "./tmux.js";
+import { readLeadSafetySnapshot } from "./leadState.js";
+import { readTurnCount } from "./turnCount.js";
+// Tests read these through this module; the leaf owns them.
+export { casHandoff, HELD_REASON_HANDOFF, handoffHoldsWake, readActiveHandoff, readHandoff, readHandoffGate, SUCCESSOR_NOT_READY, } from "./leadHandoffState.js";
+export const HANDOFF_PAD_NAME = "hive-lead-handoff";
+export const sha256 = (text) => createHash("sha256").update(text).digest("hex");
+export function handoffEligibility(lead, budget, snapshot = readLeadSafetySnapshot(lead.id)) {
+    if (budget === null || budget.auto_handoff !== true)
+        return { eligible: false, why: "auto_handoff is not enabled" };
+    if (harnessFor(lead.command).name !== "claude")
+        return { eligible: false, why: "the lead is not a Claude lead" };
+    if (lead.pane_pid === "")
+        return { eligible: false, why: "the lead's pane pid is unknown" };
+    if (snapshot === null ||
+        snapshot.session_id === "" ||
+        snapshot.pane_pid !== lead.pane_pid ||
+        snapshot.snapshot_pane_pid !== lead.pane_pid ||
+        snapshot.snapshot_session_id !== snapshot.session_id) {
+        return { eligible: false, why: "the lead's current epoch is unknown" };
+    }
+    const turns = readTurnCount(snapshot.transcript_path);
+    if (turns === null)
+        return { eligible: false, why: "the lead's turn count is unavailable" };
+    if (turns < budget.warn)
+        return { eligible: false, why: "below the warn budget" };
+    return {
+        eligible: true,
+        reason: turns >= budget.stop ? "stop" : "warn",
+        turns,
+        epoch: { pane_pid: lead.pane_pid, session_id: snapshot.session_id },
+    };
+}
+// Respawn safety, not idleness: any live background task of any type (live subagents included), a
+// Stop without background evidence, or a prompt newer than the last Stop vetoes. No expiry.
+export function backgroundVeto(snapshot) {
+    if (snapshot === null || snapshot.snapshot_session_id !== snapshot.session_id || snapshot.session_id === "") {
+        return "no background evidence for the current session";
+    }
+    if (snapshot.stop_prompt_seq === null)
+        return "no completed turn yet in this session";
+    if (snapshot.stop_prompt_seq !== snapshot.prompt_seq)
+        return "a turn started after the last completed one";
+    if (snapshot.stop_background === null)
+        return "the last completed turn reported no background-task evidence";
+    let live;
+    try {
+        live = JSON.parse(snapshot.stop_background);
+    }
+    catch {
+        return "the background-task evidence is unreadable";
+    }
+    if (live.length > 0) {
+        const types = [...new Set(live.map((t) => t.type || "unknown"))].sort().join(", ");
+        return `${live.length} background task${live.length === 1 ? "" : "s"} still live (${types})`;
+    }
+    return null;
+}
+// One request and one request wake per epoch. The wake carries no due_at: the scheduler sets it
+// when the pass's quiet rule allows, so nothing ordinary can deliver it early.
+const armTransaction = db.transaction((input) => {
+    const inserted = db
+        .prepare(`INSERT INTO lead_handoffs (project_id, lead_agent_id, pane_target, tmux_socket, predecessor_pane_pid,
+         predecessor_session_id, reason, state, pass, pass_started_at, hold_since)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, 1, strftime('%Y-%m-%d %H:%M:%f', 'now'),
+         CASE WHEN ? = 'stop' THEN strftime('%Y-%m-%d %H:%M:%f', 'now') END)
+       ON CONFLICT DO NOTHING
+       RETURNING id`)
+        .get(input.lead.project_id, input.lead.id, input.lead.tmux_target, input.lead.tmux_socket, input.epoch.pane_pid, input.epoch.session_id, input.reason, input.reason === "stop" ? "wind_down" : "pending", input.reason);
+    if (inserted === undefined) {
+        const existing = db
+            .prepare(`SELECT id FROM lead_handoffs WHERE project_id = ? AND lead_agent_id = ?
+           AND predecessor_pane_pid = ? AND predecessor_session_id = ?`)
+            .get(input.lead.project_id, input.lead.id, input.epoch.pane_pid, input.epoch.session_id);
+        const active = existing ?? readActiveHandoff(input.lead.id) ?? undefined;
+        return { requestId: active?.id ?? 0, created: false };
+    }
+    const wake = db
+        .prepare(`INSERT INTO wakes (project_id, owner, body, kind, deliver_actor, deliver_pane, due_at)
+       SELECT ?, ?, ?, 'delay', actor_id, tmux_target, NULL FROM agents WHERE id = ?
+       RETURNING id`)
+        .get(input.lead.project_id, input.ownerActor, input.requestBody(inserted.id), input.lead.id);
+    db.prepare("UPDATE lead_handoffs SET request_wake_id = ? WHERE id = ?").run(wake.id, inserted.id);
+    return { requestId: inserted.id, created: true };
+});
+export function armHandoffRequest(input) {
+    return armTransaction.immediate(input);
+}
+const failTransaction = db.transaction((id, failure, from, where) => {
+    if (!casHandoff(id, from, { state: "failed", failure, owner_token: null, owner_pid: null }, where))
+        return false;
+    db.prepare(`UPDATE wakes SET cancelled_at = datetime('now'), held_reason = ?
+      WHERE id = (SELECT request_wake_id FROM lead_handoffs WHERE id = ?) AND fired_at IS NULL AND cancelled_at IS NULL`).run(`lead handoff #${id} failed: ${failure}`, id);
+    return true;
+});
+export function failHandoff(id, failure, from = PRE_RESPAWN_STATES, where = {}) {
+    return failTransaction.immediate(id, failure, from, where);
+}
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === "EPERM";
+    }
+}
+// After the destructive claim nothing is retried: a successor the row no longer names fails the row,
+// and a respawn that never settled releases its holds after the cap.
+function settleAfterRespawn(row, lead) {
+    if (row.state === "started" && row.successor_pane_pid !== null && lead.pane_pid !== row.successor_pane_pid) {
+        casHandoff(row.id, ["started"], { state: "failed", failure: "the lead pane no longer runs the successor this handoff started" });
+        return;
+    }
+    if (row.state === "started" && row.blocked_reason !== SUCCESSOR_NOT_READY && olderThan(row.started_at, STOP_HOLD_CAP_SECONDS)) {
+        casHandoff(row.id, ["started"], { blocked_reason: SUCCESSOR_NOT_READY });
+        return;
+    }
+    if ((row.state === "respawning" || row.state === "ambiguous") && row.hold_released_at === null && olderThan(row.updated_at, STOP_HOLD_CAP_SECONDS)) {
+        casHandoff(row.id, [row.state], { hold_released_at: nowSql(), blocked_reason: row.failure ?? "the respawn never settled" });
+    }
+}
+export const REQUEST_BODY_PREFIX = "hive lead handoff request #";
+export const HANDOFF_HEADINGS = [
+    "IN FLIGHT",
+    "WAITING ON",
+    "QUEUED NEXT",
+    "OPEN QUESTIONS FOR THE HUMAN",
+    "HUMAN INSTRUCTIONS THIS SESSION",
+    "HUMAN'S LAST REQUEST",
+    "VERIFY ON ARRIVAL",
+    "DON'T REDO",
+    "SESSION WORK TO RESTORE",
+];
+export function requestBody(row, turns) {
+    const policy = passPolicy(row.pass, row.reason);
+    return [
+        `${REQUEST_BODY_PREFIX}${row.id} (pass ${row.pass}, ${row.reason} budget` +
+            `${turns === null ? "" : `, ${turns} turns`}). hive will replace this session with a fresh one in the same pane.`,
+        "",
+        "1. Finish or park any write you have in progress, so the project's own records are current.",
+        `2. Write the pad "${HANDOFF_PAD_NAME}" with exactly these headings, in this order. "none" is a valid entry; ` +
+            "point into the store rather than copying it, and keep it under about 8,000 characters:",
+        ...HANDOFF_HEADINGS.map((h) => `   ${h}`),
+        "   Under SESSION WORK TO RESTORE list every /loop, cron, ScheduleWakeup, monitor or in-session task list " +
+            "and how to re-arm it; none of them survive the new session. Re-arm what you can as hive wakes now.",
+        "3. Read the pad back and note its id and revision.",
+        `4. Tell the human in plain words: "I will hand off after ${policy.graceSeconds} quiet seconds. Human input postpones it."`,
+        `5. Run: hive lead-handoff --request ${row.id} --pad <pad id> --revision <revision>`,
+        "",
+        "If you cannot write the pad, say so and do not run the command; this session stays as it is.",
+    ].join("\n");
+}
+// Automated deliveries to the lead other than the handoff's own request wakes.
+export function automationBlocker(lead, seconds) {
+    const inFlight = db
+        .prepare(`SELECT 1 AS hit FROM agent_messages WHERE to_agent_id = ? AND delivery_status IN ('socket-pending', 'fallback-claimed')
+        AND created_at >= datetime('now', '-7 days')
+       UNION ALL
+       SELECT 1 FROM wakes WHERE deliver_actor = ? AND body NOT LIKE ? AND fired_at IS NOT NULL AND cancelled_at IS NULL
+        AND delivery_method LIKE 'socket%' AND confirmed_at IS NULL AND socket_attempt_at >= datetime('now', '-7 days')
+       LIMIT 1`)
+        .get(lead.id, lead.actor_id, `${REQUEST_BODY_PREFIX}%`);
+    if (inFlight !== undefined)
+        return "a delivery to the lead is still in flight";
+    if (seconds === null)
+        return null;
+    const window = `-${seconds} seconds`;
+    const recent = db
+        .prepare(`SELECT 1 AS hit FROM wakes WHERE deliver_actor = ? AND body NOT LIKE ?
+         AND (fired_at >= datetime('now', ?) OR typed_at >= datetime('now', ?) OR socket_attempt_at >= datetime('now', ?))
+         AND NOT (kind IN ('idle_any', 'idle_all') AND watch_scope IS NULL)
+         AND NOT EXISTS (SELECT 1 FROM wake_idle_notices n JOIN wakes p ON p.id = wakes.parent_wake_id
+                          WHERE n.notice_wake_id = wakes.id AND p.watch_scope IS NOT NULL)
+       UNION ALL
+       SELECT 1 FROM agent_messages WHERE to_agent_id = ? AND created_at >= datetime('now', ?)
+       LIMIT 1`)
+        .get(lead.actor_id, `${REQUEST_BODY_PREFIX}%`, window, window, window, lead.id, window);
+    return recent === undefined ? null : `an automated delivery reached the lead in the last ${seconds} s`;
+}
+function requestBlocker(lead, row, snapshot) {
+    if (snapshot === null || snapshot.state !== "idle")
+        return { reason: "the lead's turn has not ended", background: false };
+    const background = backgroundVeto(snapshot);
+    if (background !== null)
+        return { reason: background, background: true };
+    const policy = passPolicy(row.pass, row.reason);
+    if (!policy.requestNeedsQuiet)
+        return null;
+    if (!olderThan(snapshot.human_prompt_at, policy.humanQuietSeconds)) {
+        return { reason: `a human prompt arrived in the last ${policy.humanQuietSeconds} s`, background: false };
+    }
+    const automation = automationBlocker(lead, policy.automationQuietSeconds);
+    return automation === null ? null : { reason: automation, background: false };
+}
+const requestTransaction = db.transaction((row, lead, turns) => {
+    const current = readHandoff(row.id);
+    if (current === null || current.state !== row.state || current.pass !== row.pass)
+        return false;
+    const waiting = current.request_wake_id === null
+        ? undefined
+        : db
+            .prepare("SELECT id FROM wakes WHERE id = ? AND due_at IS NULL AND fired_at IS NULL AND cancelled_at IS NULL")
+            .get(current.request_wake_id);
+    let wakeId;
+    if (waiting !== undefined) {
+        db.prepare("UPDATE wakes SET due_at = datetime('now'), body = ? WHERE id = ?").run(requestBody(current, turns), waiting.id);
+        wakeId = waiting.id;
+    }
+    else {
+        wakeId = db
+            .prepare(`INSERT INTO wakes (project_id, owner, body, kind, deliver_actor, deliver_pane, due_at)
+           VALUES (?, ?, ?, 'delay', ?, ?, datetime('now')) RETURNING id`)
+            .get(current.project_id, lead.actor_id, requestBody(current, turns), lead.actor_id, lead.tmux_target).id;
+    }
+    const holds = passPolicy(current.pass, current.reason).holdsFromRequest;
+    return casHandoff(current.id, [current.state], {
+        state: "requested",
+        request_reason: current.reason,
+        request_wake_id: wakeId,
+        hold_released_at: null,
+        // The stop-hold clock runs across passes; only re-arming a released hold restarts it.
+        hold_since: !holds ? null : current.hold_released_at !== null || current.hold_since === null ? nowSql() : current.hold_since,
+        blocked_reason: null,
+    }, { pass: current.pass });
+});
+function maintainHold(row, reason) {
+    const holds = handoffHoldsAutomation(row);
+    if (holds && row.hold_since === null) {
+        casHandoff(row.id, [row.state], { hold_since: nowSql() }, { hold_since: null });
+        return;
+    }
+    if (holds && row.state !== "grace" && olderThan(row.hold_since, STOP_HOLD_CAP_SECONDS)) {
+        casHandoff(row.id, [row.state], { hold_released_at: nowSql(), blocked_reason: reason ?? "no quiet moment" }, { hold_released_at: null });
+        return;
+    }
+    if (reason !== row.blocked_reason && reason !== null)
+        casHandoff(row.id, [row.state], { blocked_reason: reason });
+}
+// The scheduler's WHEN: arm at warn, wind down at stop, request at the pass's quiet moment, escalate
+// a pass that found none in 10 minutes, and release a hold that has lasted 15. Never touches a pane.
+export function driveLeadHandoff(actorId, budgetFor) {
+    const lead = db
+        .prepare(`SELECT a.id, a.project_id, a.actor_id, a.command, a.pane_pid, a.tmux_target, a.tmux_socket, p.path
+         FROM agents a JOIN projects p ON p.id = a.project_id
+        WHERE a.actor_id = ? AND a.kind = 'lead' AND a.status = 'running'`)
+        .get(actorId);
+    if (lead === undefined)
+        return;
+    const budget = budgetFor(lead.path);
+    const snapshot = readLeadSafetySnapshot(lead.id);
+    let row = readActiveHandoff(lead.id);
+    if (row === null) {
+        const eligibility = handoffEligibility(lead, budget, snapshot);
+        if (!eligibility.eligible)
+            return;
+        armHandoffRequest({
+            lead,
+            ownerActor: lead.actor_id,
+            reason: eligibility.reason,
+            epoch: eligibility.epoch,
+            requestBody: (id) => requestBody({ id, pass: 1, reason: eligibility.reason }, eligibility.turns),
+        });
+        row = readActiveHandoff(lead.id);
+        if (row === null)
+            return;
+    }
+    if (!PRE_RESPAWN_STATES.includes(row.state)) {
+        settleAfterRespawn(row, lead);
+        return;
+    }
+    if (budget?.auto_handoff !== true) {
+        failHandoff(row.id, "lead_turn_budget.auto_handoff is no longer on");
+        return;
+    }
+    if (lead.pane_pid !== row.predecessor_pane_pid || snapshot?.session_id !== row.predecessor_session_id) {
+        failHandoff(row.id, "the lead's pane or session changed before the handoff (a restart, /clear or /resume)");
+        return;
+    }
+    if (row.state === "grace") {
+        const deadline = (row.grace_seconds ?? 120) + RESPAWN_WAIT_LIMIT_SECONDS + 120;
+        const dead = row.owner_pid !== null && !processAlive(row.owner_pid);
+        if (dead || olderThan(row.grace_started_at, deadline)) {
+            failHandoff(row.id, dead ? "the grace owner process died" : "the grace ran far past its deadline", ["grace"], {
+                attempt: row.attempt,
+                owner_token: row.owner_token,
+            });
+        }
+        return;
+    }
+    const eligibility = handoffEligibility(lead, budget, snapshot);
+    if (eligibility.eligible && eligibility.reason === "stop" && row.reason === "warn") {
+        casHandoff(row.id, [row.state], { reason: "stop", ...(row.state === "pending" ? { state: "wind_down" } : {}) }, { reason: "warn" });
+        row = readHandoff(row.id);
+    }
+    const blocker = requestBlocker(lead, row, snapshot);
+    if (row.state === "requested") {
+        maintainHold(row, blocker?.reason ?? null);
+        return;
+    }
+    if (blocker === null) {
+        requestTransaction.immediate(row, lead, eligibility.eligible ? eligibility.turns : null);
+        return;
+    }
+    if (!blocker.background && olderThan(row.pass_started_at, PASS_TIMEOUT_SECONDS)) {
+        casHandoff(row.id, [row.state], {
+            pass: row.pass + 1,
+            pass_started_at: nowSql(),
+            blocked_reason: blocker.reason,
+        }, { pass: row.pass });
+        return;
+    }
+    maintainHold(row, blocker.reason);
+}
+export const RESPAWN_WAIT_LIMIT_SECONDS = 10 * 60;
+export function missingHeadings(content) {
+    const lines = content.split("\n").map((l) => l.replace(/^[#\s*_]+|[\s*_:]+$/g, "").toUpperCase());
+    const missing = [];
+    let from = 0;
+    for (const heading of HANDOFF_HEADINGS) {
+        const at = lines.indexOf(heading, from);
+        if (at === -1)
+            missing.push(heading);
+        else
+            from = at + 1;
+    }
+    return missing;
+}
+export function successorPrompt(row) {
+    return [
+        `You are taking over as this project's lead from session ${row.predecessor_session_id} (hive handoff #${row.id}).`,
+        `Read the "${HANDOFF_PAD_NAME}" handoff hive injected at session start (if none arrived, pad_read it by name), ` +
+            "then the project's durable state.",
+        "Open your first reply with exactly one line:",
+        `"Took over from session ${row.predecessor_session_id} at turn ${row.predecessor_turns ?? "?"} (${row.reason}, pass ${row.pass}). ` +
+            'Carried over: <a> in flight, <b> queued, <c> questions for you."',
+        "counting the IN FLIGHT, QUEUED NEXT and OPEN QUESTIONS FOR THE HUMAN entries, then quote OPEN QUESTIONS FOR THE HUMAN verbatim.",
+        "Re-arm everything under SESSION WORK TO RESTORE, check VERIFY ON ARRIVAL, then continue with QUEUED NEXT.",
+    ].join("\n");
+}
+export function runningLeadByActor(actorId) {
+    return db
+        .prepare(`SELECT a.id, a.project_id, a.actor_id, a.command, a.pane_pid, a.tmux_target, a.tmux_socket, p.path, p.name
+         FROM agents a JOIN projects p ON p.id = a.project_id
+        WHERE a.actor_id = ? AND a.kind = 'lead' AND a.status = 'running'`)
+        .get(actorId);
+}
+export const readPad = (id) => db.prepare("SELECT id, project_id, name, archived, revision, content FROM pads WHERE id = ?").get(id);
+export function padProblem(pad, projectId, revision) {
+    if (pad === undefined || pad.project_id !== projectId)
+        return "that pad does not exist in this project";
+    if (pad.name !== HANDOFF_PAD_NAME || pad.archived !== 0)
+        return `that pad is not the active "${HANDOFF_PAD_NAME}" pad`;
+    if (pad.revision !== revision)
+        return `that pad is at revision ${pad.revision}, not ${revision}; read it back and pass its current revision`;
+    if (pad.content.trim() === "")
+        return "the pad is empty";
+    return null;
+}
+// The final quiet check. A screen or probe that cannot be read waits; it never establishes quiet.
+export async function respawnVerdict(row, lead, budget) {
+    if (budget?.auto_handoff !== true)
+        return { fail: "lead_turn_budget.auto_handoff is no longer on" };
+    if (lead === undefined || lead.pane_pid !== row.predecessor_pane_pid || lead.tmux_target !== row.pane_target) {
+        return { fail: "the lead row no longer names the pane this handoff was requested for" };
+    }
+    if (tmuxSocketPath(process.env.TMUX, process.env.TMUX_TMPDIR) !== row.tmux_socket) {
+        return { fail: "the grace owner is not talking to the lead's tmux server" };
+    }
+    const snapshot = readLeadSafetySnapshot(lead.id);
+    if (snapshot?.session_id !== row.predecessor_session_id)
+        return { fail: "the lead's session changed" };
+    if (snapshot.human_prompt_seq !== row.human_prompt_baseline)
+        return { postpone: "a human prompt arrived during grace", escalate: true };
+    const ownership = rowOwnership(lead);
+    if (ownership === "unknown")
+        return { wait: "the lead's pane ownership reads unknown" };
+    if (ownership !== "live")
+        return { fail: `the lead's pane is ${ownership}` };
+    if (snapshot.state !== "idle")
+        return { wait: "the lead's turn has not ended" };
+    const background = backgroundVeto(snapshot);
+    if (background !== null)
+        return { wait: background };
+    const pad = row.pad_id === null ? undefined : readPad(row.pad_id);
+    if (padProblem(pad, lead.project_id, row.pad_revision ?? -1) !== null) {
+        return { postpone: "the handoff pad changed after the command", escalate: false };
+    }
+    const policy = quotedPolicy(row);
+    if (!olderThan(snapshot.human_prompt_at, policy.humanQuietSeconds)) {
+        return { wait: `a human prompt arrived in the last ${policy.humanQuietSeconds} s` };
+    }
+    const automation = automationBlocker(lead, policy.automationQuietSeconds);
+    if (automation !== null)
+        return { wait: automation };
+    if (paneInCopyMode(lead.tmux_target) !== false)
+        return { wait: "the lead's pane is in copy mode or unreadable" };
+    const classifier = paneClassifierFor(lead.command);
+    if (!classifier)
+        return { fail: "hive cannot classify the lead's screen" };
+    const choice = classifier.choiceCheck(lead.tmux_target).awaitingChoice;
+    if (choice !== false)
+        return { wait: choice ? "the lead's pane is waiting on a choice" : "the lead's pane could not be read" };
+    const box = classifier.inputBoxState(lead.tmux_target);
+    if (holdsHumanInput(box))
+        return { postpone: "unsubmitted text is in the lead's input box", escalate: true };
+    if (box === null || (box.state !== "empty" && box.state !== "ghost"))
+        return { wait: "the lead's input box could not be read" };
+    return { go: true };
+}
+const MARKER_SECONDS = 30 * 60;
+// The SessionStart payload for a starting lead whose project holds an active handoff pad: the pad in
+// full, plus what hive itself knows. Never truncated; never shown to a worker.
+export function handoffInjection(leadActor) {
+    const lead = runningLeadByActor(leadActor);
+    if (lead === undefined)
+        return null;
+    const pad = db
+        .prepare("SELECT id, revision, content, updated_at FROM pads WHERE project_id = ? AND name = ? AND archived = 0")
+        .get(lead.project_id, HANDOFF_PAD_NAME);
+    if (pad === undefined)
+        return null;
+    const row = db
+        .prepare(`SELECT * FROM lead_handoffs WHERE lead_agent_id = ? AND pad_id = ?
+         AND (state IN ('started', 'ambiguous') OR (state = 'failed' AND respawn_claimed_at IS NOT NULL))
+       ORDER BY id DESC LIMIT 1`)
+        .get(lead.id, pad.id);
+    if (row === undefined)
+        return null;
+    const workers = db
+        .prepare("SELECT name, agent_state FROM agents WHERE project_id = ? AND kind = 'agent' AND status = 'running' ORDER BY id")
+        .all(lead.project_id);
+    const pending = db
+        .prepare("SELECT COUNT(*) AS n FROM wakes WHERE deliver_actor = ? AND fired_at IS NULL AND cancelled_at IS NULL")
+        .get(lead.actor_id).n;
+    const heldWakes = db.prepare("SELECT COUNT(*) AS n FROM wakes WHERE deliver_actor = ? AND held_reason = ? AND cancelled_at IS NULL").get(lead.actor_id, HELD_REASON_HANDOFF).n;
+    const heldMessages = db
+        .prepare("SELECT COUNT(*) AS n FROM agent_messages WHERE to_agent_id = ? AND delivery_status = 'fallback-pending' AND created_at >= datetime('now', '-7 days')")
+        .get(lead.id).n;
+    const lines = [`[hive] LEAD HANDOFF: pad "${HANDOFF_PAD_NAME}" #${pad.id} revision ${pad.revision}, written ${pad.updated_at} UTC.`];
+    {
+        lines.push(`Handed off by session ${row.predecessor_session_id} at turn ${row.predecessor_turns ?? "?"} (${row.reason}, pass ${row.pass})` +
+            `${row.started_at ? ` at ${row.started_at} UTC` : ""}; handoff #${row.id} is ${row.state}.`);
+    }
+    lines.push(workers.length === 0 ? "Workers: none running." : `Workers: ${workers.map((w) => `${w.name} [${w.agent_state}]`).join(", ")}.`, `Wakes pending for this lead: ${pending}. Held for the handoff and ${row.state === "started" ? "delivered to you once your first turn ends" : "released to you now"}: ` +
+        `${heldWakes} wake(s), ${heldMessages} message(s).`, row.state === "started" && row.successor_pane_pid === lead.pane_pid
+        ? `hive archives this pad after your first completed turn. Then append one line to it with ` +
+            `pad_append(pad_id: ${pad.id}): "missing from the handoff: <what you had to find yourself>" or "missing from the handoff: none".`
+        : `This handoff did not complete (${row.state === "started" ? "its successor is gone" : row.state}${row.failure ? `: ${row.failure}` : ""}), so hive will not archive the pad; ` +
+            `archive it with pad_archive(pad_id: ${pad.id}) once you have taken it over.`, "", pad.content);
+    return lines.join("\n");
+}
+// An appended line (the successor's gaps note) keeps the delivered text as a prefix and still archives.
+function stillDelivered(row) {
+    if (row.pad_id === null || row.pad_revision === null || row.pad_length === null || row.pad_sha256 === null)
+        return null;
+    const pad = readPad(row.pad_id);
+    if (pad === undefined || pad.archived !== 0 || pad.name !== HANDOFF_PAD_NAME || pad.revision < row.pad_revision)
+        return null;
+    return sha256(pad.content.slice(0, row.pad_length)) === row.pad_sha256 ? { revision: pad.revision } : null;
+}
+const completeTransaction = db.transaction((row, sessionId) => {
+    const current = stillDelivered(row);
+    const archived = current !== null &&
+        db
+            .prepare(`UPDATE pads SET archived = 1, revision = revision + 1, updated_by = 'hive', updated_at = datetime('now')
+          WHERE id = ? AND revision = ? AND archived = 0 AND name = ?`)
+            .run(row.pad_id, current.revision, HANDOFF_PAD_NAME).changes === 1;
+    const completedAt = nowSql();
+    casHandoff(row.id, ["started"], {
+        state: "completed",
+        successor_session_id: sessionId,
+        completed_at: completedAt,
+        hold_released_at: completedAt,
+        blocked_reason: null,
+        delivered_pad_id: archived ? row.pad_id : null,
+        delivered_pad_revision: archived ? row.pad_revision : null,
+        failure: archived ? null : "the delivered handoff text was edited after the command, so the pad was left active",
+    });
+});
+// The successor's first completed turn: a Stop in a new session on the successor's pane, after at
+// least one prompt there, with no background work. Anything else leaves the pad active.
+export function completeHandoffOnStop(actorId) {
+    const lead = runningLeadByActor(actorId);
+    if (lead === undefined)
+        return false;
+    const row = db.prepare("SELECT * FROM lead_handoffs WHERE lead_agent_id = ? AND state = 'started'").get(lead.id);
+    if (row === undefined || lead.pane_pid !== row.successor_pane_pid)
+        return false;
+    const snapshot = readLeadSafetySnapshot(lead.id);
+    if (snapshot === null ||
+        snapshot.pane_pid !== lead.pane_pid ||
+        snapshot.snapshot_session_id !== snapshot.session_id ||
+        snapshot.session_id === row.predecessor_session_id ||
+        snapshot.stop_prompt_seq === null ||
+        snapshot.stop_prompt_seq < 1 ||
+        snapshot.stop_prompt_seq !== snapshot.prompt_seq) {
+        return false;
+    }
+    completeTransaction.immediate(row, snapshot.session_id);
+    return readHandoff(row.id)?.state === "completed";
+}
+export function handoffStatusSegment(leadAgentId) {
+    const row = readActiveHandoff(leadAgentId);
+    if (row !== null) {
+        if (row.state === "started")
+            return row.blocked_reason === SUCCESSOR_NOT_READY ? `handoff started: ${SUCCESSOR_NOT_READY}` : "handoff started";
+        if (row.hold_released_at !== null)
+            return `handoff blocked: ${row.blocked_reason ?? "no quiet moment"}`;
+        if (row.state === "grace")
+            return "handoff in grace";
+        return `handoff ${row.state.replace("_", " ")}`;
+    }
+    const done = db
+        .prepare(`SELECT CAST((julianday('now') - julianday(completed_at)) * 86400 AS INTEGER) AS age FROM lead_handoffs
+        WHERE lead_agent_id = ? AND state = 'completed' ORDER BY id DESC LIMIT 1`)
+        .get(leadAgentId);
+    if (done === undefined || done.age > MARKER_SECONDS)
+        return null;
+    return `handed off ${done.age < 60 ? `${done.age}s` : `${Math.floor(done.age / 60)}m`} ago`;
+}