@cmgmyr/hive 1.10.1 → 1.11.1

package/dist/leadHandoffCli.js

@@ -0,0 +1,295 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { openSync } from "node:fs";
+import { join } from "node:path";
+import { dataDir, db } from "./db.js";
+import { cliPath } from "./dispatcher.js";
+import { FIRST_MESSAGE_SHA_ENV, firstMessageDigest } from "./firstMessage.js";
+import { ensureLeadHooksFile } from "./hooks.js";
+import { appendClaudeLeadArgs, crewPluginDir, isTrusted, leadIdentityEnv, renderLeadPosture } from "./leadLaunch.js";
+import { loadProjectYml } from "./projectYml.js";
+import { buildEnvFlags } from "./spawn.js";
+import { panePidForRecord, rowOwnership, shellQuote, tmux, TmuxTimeoutError } from "./tmux.js";
+import { automationBlocker, failHandoff, missingHeadings, padProblem, readPad, RESPAWN_WAIT_LIMIT_SECONDS, respawnVerdict, runningLeadByActor, sha256, successorPrompt, } from "./leadHandoff.js";
+import { casHandoff, nowSql, olderThan, postponeGrace, quotedPolicy, readHandoff } from "./leadHandoffState.js";
+import { readLeadSafetySnapshot } from "./leadState.js";
+import { readTurnCount } from "./turnCount.js";
+import { harnessFor } from "./harnesses.js";
+const POLL_MS = 1_000;
+const HANDOFF_PAD_SOFT_CAP = 8_000;
+function flags(argv, names) {
+    const out = {};
+    for (let i = 0; i < argv.length; i++) {
+        const name = argv[i].replace(/^--/, "");
+        if (!argv[i].startsWith("--") || !names.includes(name) || argv[i + 1] === undefined)
+            return `unexpected argument "${argv[i]}"`;
+        out[name] = argv[++i];
+    }
+    const absent = names.filter((n) => out[n] === undefined);
+    return absent.length > 0 ? `missing --${absent.join(", --")}` : out;
+}
+const intFlag = (value) => (/^\d+$/.test(value) ? Number(value) : null);
+function runningLeadById(id) {
+    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.id = ? AND a.kind = 'lead' AND a.status = 'running'`)
+        .get(id);
+}
+export async function cmdLeadHandoff(argv) {
+    const refuse = (why) => {
+        console.error(`hive lead-handoff: ${why}. This session stays as it is.`);
+        return 1;
+    };
+    const parsed = flags(argv, ["request", "pad", "revision"]);
+    if (typeof parsed === "string")
+        return refuse(`${parsed}; usage: hive lead-handoff --request <id> --pad <id> --revision <n>`);
+    const [requestId, padId, revision] = [intFlag(parsed.request), intFlag(parsed.pad), intFlag(parsed.revision)];
+    if (requestId === null || padId === null || revision === null)
+        return refuse("--request, --pad and --revision take whole numbers");
+    const actor = process.env.HIVE_AGENT_ID ?? "";
+    const lead = process.env.HIVE_LEAD === "1" ? runningLeadByActor(actor) : undefined;
+    if (lead === undefined)
+        return refuse("only a running lead can hand itself off");
+    if ((process.env.TMUX_PANE ?? "") !== lead.tmux_target || rowOwnership(lead) !== "live") {
+        return refuse("this is not running in the lead's own recorded pane");
+    }
+    const row = readHandoff(requestId);
+    if (row === null || row.lead_agent_id !== lead.id)
+        return refuse(`there is no handoff request #${requestId} for this lead`);
+    if (row.state !== "requested")
+        return refuse(`handoff #${requestId} is ${row.state}, not waiting for this command`);
+    const snapshot = readLeadSafetySnapshot(lead.id);
+    if (lead.pane_pid !== row.predecessor_pane_pid || snapshot?.session_id !== row.predecessor_session_id) {
+        return refuse(`handoff #${requestId} was requested for a different session of this lead`);
+    }
+    const pad = readPad(padId);
+    const problem = padProblem(pad, lead.project_id, revision);
+    if (problem !== null)
+        return refuse(problem);
+    if (row.pad_id === pad.id && row.pad_revision !== null && pad.revision <= row.pad_revision) {
+        return refuse("this attempt was postponed, so refresh the pad (write it again) and pass the new revision");
+    }
+    const missing = missingHeadings(pad.content);
+    if (missing.length > 0)
+        return refuse(`the pad is missing these headings, in this order: ${missing.join("; ")}`);
+    const inFlight = automationBlocker(lead, null);
+    if (inFlight !== null)
+        return refuse(`${inFlight}; run this command again in a minute`);
+    const token = randomUUID();
+    const policy = quotedPolicy(row);
+    const claimed = casHandoff(row.id, ["requested"], {
+        state: "grace",
+        attempt: row.attempt + 1,
+        owner_token: token,
+        grace_seconds: policy.graceSeconds,
+        grace_started_at: nowSql(),
+        human_prompt_baseline: snapshot.human_prompt_seq,
+        pad_id: pad.id,
+        pad_revision: pad.revision,
+        pad_length: pad.content.length,
+        pad_sha256: sha256(pad.content),
+        predecessor_turns: readTurnCount(snapshot.transcript_path),
+        hold_since: row.hold_since ?? nowSql(),
+        hold_released_at: null,
+    }, { attempt: row.attempt });
+    if (!claimed)
+        return refuse(`handoff #${requestId} changed while this command ran`);
+    const attempt = row.attempt + 1;
+    try {
+        const log = openSync(join(dataDir, `lead-handoff-${row.id}.log`), "a");
+        const child = spawn(process.execPath, [cliPath(), "lead-handoff-grace", "--request", String(row.id), "--attempt", String(attempt), "--token", token], { detached: true, stdio: ["ignore", log, log], env: process.env });
+        child.unref();
+        if (child.pid === undefined)
+            throw new Error("no process id");
+        casHandoff(row.id, ["grace"], { owner_pid: child.pid }, { attempt, owner_token: token });
+    }
+    catch (e) {
+        failHandoff(row.id, `the grace owner could not start: ${e instanceof Error ? e.message : String(e)}`, ["grace"], {
+            attempt,
+            owner_token: token,
+        });
+        return refuse("the grace owner could not start, so the handoff failed");
+    }
+    if (pad.content.length > HANDOFF_PAD_SOFT_CAP) {
+        console.log(`! the pad is ${pad.content.length} characters, over the ${HANDOFF_PAD_SOFT_CAP}-character guide; point into the store instead of copying it.`);
+    }
+    console.log(`Handoff #${row.id} armed (attempt ${attempt}, pad #${pad.id} revision ${pad.revision}). hive replaces this session in ` +
+        `${policy.graceSeconds} s if nothing happens; any human input postpones it. End your turn now.`);
+    return 0;
+}
+// Prepared before the destructive claim: a launch that cannot be built leaves the predecessor alive.
+async function successorLaunch(row, lead, attempt, token) {
+    const config = loadProjectYml(lead.path).config;
+    let command = "claude";
+    if (config?.lead) {
+        if (!isTrusted(lead.project_id, "lead", config.lead, null, {}))
+            throw new Error("the configured lead command is not trusted");
+        command = config.lead;
+    }
+    const harness = harnessFor(command);
+    if (harness.name !== "claude" || !harness.briefDelivery)
+        throw new Error("the configured lead command is not a Claude lead");
+    const firstMessage = successorPrompt(row);
+    const built = appendClaudeLeadArgs({
+        command,
+        harness,
+        projectId: lead.project_id,
+        projectName: lead.name,
+        hooksPath: ensureLeadHooksFile(lead.project_id, config?.quiet_messaging === true),
+        sidebarPluginDir: config?.lead_sidebar === true ? crewPluginDir() : null,
+        posture: renderLeadPosture(config).rendered,
+        firstMessage,
+    });
+    const bootstrap = [process.execPath, cliPath(), "lead-handoff-start", "--request", String(row.id), "--attempt", String(attempt), "--token", token]
+        .map(shellQuote)
+        .join(" ");
+    return {
+        launch: `${bootstrap} && exec ${built.command}${built.promptSuffix}`,
+        env: buildEnvFlags({ ...leadIdentityEnv(lead.actor_id), [FIRST_MESSAGE_SHA_ENV]: firstMessageDigest(firstMessage) }),
+    };
+}
+const sleepMs = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+// `hive lead-handoff-grace`: the one detached owner of an attempt. It never outlives a changed
+// attempt or token, and after it claims the respawn it never repeats the kill.
+export async function runHandoffGrace(argv) {
+    try {
+        return await graceLoop(argv);
+    }
+    catch (e) {
+        const parsed = flags(argv, ["request", "attempt", "token"]);
+        const id = typeof parsed === "string" ? null : intFlag(parsed.request);
+        const attempt = typeof parsed === "string" ? null : intFlag(parsed.attempt);
+        if (id !== null && attempt !== null && typeof parsed !== "string") {
+            failHandoff(id, `the grace owner failed: ${e instanceof Error ? e.message : String(e)}`, ["grace"], {
+                attempt,
+                owner_token: parsed.token,
+            });
+        }
+        return 1;
+    }
+}
+async function graceLoop(argv) {
+    const parsed = flags(argv, ["request", "attempt", "token"]);
+    if (typeof parsed === "string")
+        return 1;
+    const id = intFlag(parsed.request);
+    const attempt = intFlag(parsed.attempt);
+    const token = parsed.token;
+    if (id === null || attempt === null)
+        return 1;
+    const own = (row) => row !== null && row.state === "grace" && row.attempt === attempt && row.owner_token === token;
+    let waitingSince = null;
+    for (;;) {
+        const row = readHandoff(id);
+        if (!own(row))
+            return 0;
+        const lead = runningLeadById(row.lead_agent_id);
+        const snapshot = lead === undefined ? null : readLeadSafetySnapshot(lead.id);
+        if (snapshot !== null && row.human_prompt_baseline !== null && snapshot.human_prompt_seq > row.human_prompt_baseline) {
+            postponeGrace(row, { attempt: row.attempt, owner_token: token }, "a human prompt arrived during grace", true);
+            return 0;
+        }
+        if (!olderThan(row.grace_started_at, row.grace_seconds ?? 120)) {
+            await sleepMs(POLL_MS);
+            continue;
+        }
+        const budget = lead === undefined ? null : (loadProjectYml(lead.path).config?.lead_turn_budget ?? null);
+        const verdict = await respawnVerdict(row, lead, budget);
+        if ("fail" in verdict) {
+            failHandoff(row.id, verdict.fail, ["grace"], { attempt, owner_token: token });
+            return 0;
+        }
+        if ("postpone" in verdict) {
+            postponeGrace(row, { attempt: row.attempt, owner_token: token }, verdict.postpone, verdict.escalate);
+            return 0;
+        }
+        if ("wait" in verdict) {
+            waitingSince ??= Date.now();
+            if (row.blocked_reason !== verdict.wait)
+                casHandoff(row.id, ["grace"], { blocked_reason: verdict.wait }, { attempt, owner_token: token });
+            if (Date.now() - waitingSince >= RESPAWN_WAIT_LIMIT_SECONDS * 1000) {
+                postponeGrace(row, { attempt: row.attempt, owner_token: token }, verdict.wait, false);
+                return 0;
+            }
+            await sleepMs(POLL_MS);
+            continue;
+        }
+        let launch;
+        try {
+            launch = await successorLaunch(row, lead, attempt, token);
+        }
+        catch (e) {
+            failHandoff(row.id, `the successor launch could not be prepared: ${e instanceof Error ? e.message : String(e)}`, ["grace"], {
+                attempt,
+                owner_token: token,
+            });
+            return 0;
+        }
+        if (!casHandoff(row.id, ["grace"], { state: "respawning", owner_pid: process.pid, respawn_claimed_at: nowSql() }, { attempt, owner_token: token }))
+            return 0;
+        try {
+            tmux("respawn-pane", "-k", "-t", row.pane_target, "-c", lead.path, ...launch.env, launch.launch);
+        }
+        catch (e) {
+            const detail = e instanceof Error ? e.message : String(e);
+            if (e instanceof TmuxTimeoutError) {
+                casHandoff(row.id, ["respawning"], { state: "ambiguous", failure: `respawn-pane timed out; the pane's owner is unknown: ${detail}` }, { attempt, owner_token: token });
+            }
+            else {
+                failHandoff(row.id, `respawn-pane refused: ${detail}`, ["respawning"], { attempt, owner_token: token });
+            }
+        }
+        return 0;
+    }
+}
+// `hive lead-handoff-start`: runs in the respawned pane before Claude. It publishes the successor's
+// pid on the same lead row by CAS against the predecessor, and only then lets the shell exec Claude.
+export async function runHandoffStart(argv) {
+    const parsed = flags(argv, ["request", "attempt", "token"]);
+    const refuse = (why, id) => {
+        if (id !== undefined) {
+            casHandoff(id, ["respawning", "ambiguous"], { state: "failed", failure: `the successor bootstrap refused: ${why}`, owner_token: null, owner_pid: null });
+        }
+        console.error(`hive lead-handoff-start: ${why}. The handoff pad stays active; run hive lead to start a lead.`);
+        return 1;
+    };
+    if (typeof parsed === "string")
+        return refuse(parsed);
+    const id = intFlag(parsed.request);
+    const attempt = intFlag(parsed.attempt);
+    if (id === null || attempt === null)
+        return refuse("bad arguments");
+    const row = readHandoff(id);
+    if (row === null || (row.state !== "respawning" && row.state !== "ambiguous") || row.attempt !== attempt || row.owner_token !== parsed.token) {
+        return refuse("this bootstrap does not own a respawning handoff");
+    }
+    const pane = process.env.TMUX_PANE ?? "";
+    if (pane !== row.pane_target)
+        return refuse("this is not the pane the handoff respawned", id);
+    const pid = panePidForRecord(pane);
+    if (pid === "" || pid !== String(process.ppid))
+        return refuse("the pane's process id does not match this bootstrap's shell", id);
+    const publish = db.transaction(() => {
+        const moved = db
+            .prepare(`UPDATE agents SET pane_pid = ?, claude_messaging_socket = '', claude_messaging_pane_pid = ''
+          WHERE id = ? AND kind = 'lead' AND status = 'running' AND tmux_target = ? AND pane_pid = ?`)
+            .run(pid, row.lead_agent_id, row.pane_target, row.predecessor_pane_pid).changes;
+        if (moved !== 1)
+            return false;
+        const started = casHandoff(id, ["respawning", "ambiguous"], { state: "started", successor_pane_pid: pid, started_at: nowSql(), owner_token: null, owner_pid: null, failure: null }, { attempt, owner_token: parsed.token });
+        if (!started)
+            throw new Error("handoff changed");
+        return true;
+    });
+    let published;
+    try {
+        published = publish.immediate();
+    }
+    catch {
+        published = false;
+    }
+    if (!published)
+        return refuse("the lead row could not be moved to the new pane process", id);
+    console.log(`hive: handoff #${id}: starting a fresh lead session in this pane.`);
+    return 0;
+}

package/dist/leadHandoffState.js

@@ -0,0 +1,96 @@
+import { db } from "./db.js";
+export const PRE_RESPAWN_STATES = ["pending", "wind_down", "requested", "grace", "postponed"];
+export const PASS_TIMEOUT_SECONDS = 10 * 60;
+export const STOP_HOLD_CAP_SECONDS = 15 * 60;
+// The fence trigger's ceiling on lead_handoffs.updated_at age (src/db.ts); change both together.
+export const HOLD_CEILING_SECONDS = 3600;
+export const SUCCESSOR_NOT_READY = "the successor has not completed its first turn";
+// The policy the request body quoted, never one recomputed after a warn->stop upgrade.
+export const quotedPolicy = (row) => passPolicy(row.pass, row.request_reason ?? row.reason);
+export function passPolicy(pass, reason) {
+    if (reason === "stop" || pass >= 4) {
+        return { graceSeconds: 45, humanQuietSeconds: 60, automationQuietSeconds: null, holdsFromRequest: true, requestNeedsQuiet: false };
+    }
+    if (pass === 3) {
+        return { graceSeconds: 60, humanQuietSeconds: 75, automationQuietSeconds: 30, holdsFromRequest: true, requestNeedsQuiet: false };
+    }
+    if (pass === 2) {
+        return { graceSeconds: 90, humanQuietSeconds: 150, automationQuietSeconds: 60, holdsFromRequest: true, requestNeedsQuiet: false };
+    }
+    return { graceSeconds: 120, humanQuietSeconds: 300, automationQuietSeconds: 120, holdsFromRequest: false, requestNeedsQuiet: true };
+}
+export function readHandoff(id) {
+    return db.prepare("SELECT * FROM lead_handoffs WHERE id = ?").get(id) ?? null;
+}
+export function readActiveHandoff(leadAgentId) {
+    return (db
+        .prepare("SELECT * FROM lead_handoffs WHERE lead_agent_id = ? AND state NOT IN ('completed', 'failed')")
+        .get(leadAgentId) ?? null);
+}
+export function handoffHoldsAutomation(row) {
+    switch (row.state) {
+        case "grace":
+            return true;
+        case "started":
+            return !olderThan(row.updated_at, HOLD_CEILING_SECONDS);
+        case "respawning":
+        case "ambiguous":
+            return row.hold_released_at === null;
+        case "wind_down":
+            return row.hold_released_at === null;
+        case "requested":
+            return row.hold_released_at === null && passPolicy(row.pass, row.reason).holdsFromRequest;
+        case "postponed":
+            return row.hold_released_at === null && row.reason === "stop";
+        default:
+            return false;
+    }
+}
+// The one predicate every automated lead delivery consults before it writes to the lead.
+export function readHandoffGate(leadAgentId) {
+    const row = readActiveHandoff(leadAgentId);
+    return row === null
+        ? null
+        : { requestId: row.id, requestWakeId: row.request_wake_id, holdAutomation: handoffHoldsAutomation(row) };
+}
+export const HELD_REASON_HANDOFF = "the lead is handing off to a fresh session; held through the wind-down and the successor's boot, and delivered to " +
+    "the lead row once the successor completes its first turn, or when the handoff fails or releases its hold";
+// A wake addressed to a lead row is held while that lead's handoff holds automation, except the
+// current request wake itself, which still passes every human-input and ownership guard.
+export function handoffHoldsWake(wakeId, deliverRowId) {
+    if (deliverRowId === null)
+        return false;
+    const gate = readHandoffGate(deliverRowId);
+    return gate !== null && gate.holdAutomation && gate.requestWakeId !== wakeId;
+}
+const NOW_SQL = "strftime('%Y-%m-%d %H:%M:%f', 'now')";
+export function olderThan(ts, seconds) {
+    if (ts === null)
+        return true;
+    return db.prepare("SELECT (julianday('now') - julianday(?)) * 86400 >= ? AS old").get(ts, seconds).old === 1;
+}
+export const nowSql = () => db.prepare(`SELECT ${NOW_SQL} AS now`).get().now;
+// Every transition is a compare-and-set on the row's state; callers bind any extra identity
+// (attempt, owner token) through `where`.
+export function casHandoff(id, from, set, where = {}) {
+    const setKeys = Object.keys(set);
+    const whereKeys = Object.keys(where);
+    const sql = `UPDATE lead_handoffs SET ${[...setKeys.map((k) => `${k} = ?`), "updated_at = strftime('%Y-%m-%d %H:%M:%f', 'now')"].join(", ")}
+      WHERE id = ? AND state IN (${from.map(() => "?").join(", ")})` +
+        whereKeys.map((k) => ` AND ${k} IS ?`).join("");
+    const result = db
+        .prepare(sql)
+        .run(...setKeys.map((k) => set[k] ?? null), id, ...from, ...whereKeys.map((k) => where[k] ?? null));
+    return result.changes === 1;
+}
+// The one writer of the grace -> postponed transition; `where` binds the caller's identity, and pass is always bound.
+export function postponeGrace(row, where, reason, escalate) {
+    return casHandoff(row.id, ["grace"], {
+        state: "postponed",
+        pass: escalate ? row.pass + 1 : row.pass,
+        pass_started_at: nowSql(),
+        owner_token: null,
+        owner_pid: null,
+        blocked_reason: reason,
+    }, { ...where, pass: row.pass });
+}

package/dist/leadLaunch.js

@@ -0,0 +1,54 @@
+import { writeProjectPosture } from "./brief.js";
+import { dataDir, db } from "./db.js";
+import { carriesNameFlag } from "./harnesses.js";
+import { join } from "node:path";
+import { checkoutRoot, renderProfileFile, resolveProfileFile } from "./profiles.js";
+import { activeProfile, configHash, mergedProjectVars } from "./projectYml.js";
+import { LEAD_NAME } from "./spawn.js";
+import { shellQuote } from "./tmux.js";
+// What `hive lead` and the handoff bootstrap both need to launch a claude lead: trust, posture,
+// hooks and identity env. Pane adoption and leftover cleanup stay in cmdLead.
+export function isTrusted(projectId, name, command, dir, env) {
+    const hash = configHash(name, command, dir, env);
+    return !!db
+        .prepare("SELECT 1 FROM command_trust WHERE project_id = ? AND name = ? AND config_hash = ?")
+        .get(projectId, name, hash);
+}
+export function crewPluginDir() {
+    return join(checkoutRoot, "claude-plugin", "crew");
+}
+export function renderLeadPosture(config) {
+    const profile = activeProfile(config);
+    if (!profile)
+        return { profile: null, rendered: null };
+    const posture = resolveProfileFile(profile, "posture.md");
+    if (!posture)
+        return { profile, rendered: null };
+    return { profile, rendered: renderProfileFile(profile, "posture.md", mergedProjectVars(config)) ?? "", source: posture.source };
+}
+export function appendClaudeLeadArgs(input) {
+    const delivery = input.harness.briefDelivery;
+    let command = input.command;
+    if (!carriesNameFlag(command.trim().split(/\s+/)))
+        command += ` --name ${shellQuote(input.projectName)}`;
+    command += ` ${delivery.settingsArgs(input.hooksPath).map(shellQuote).join(" ")}`;
+    if (input.sidebarPluginDir !== null)
+        command += ` ${["--plugin-dir", input.sidebarPluginDir].map(shellQuote).join(" ")}`;
+    if (input.posture !== null) {
+        command += ` ${delivery.systemPromptArgs(writeProjectPosture(input.projectId, input.posture)).map(shellQuote).join(" ")}`;
+    }
+    const promptSuffix = input.harness.initialPromptArgs && input.firstMessage !== ""
+        ? ` ${input.harness.initialPromptArgs(input.firstMessage).map(shellQuote).join(" ")}`
+        : "";
+    return { command, promptSuffix };
+}
+export function leadIdentityEnv(actorId) {
+    return {
+        HIVE_AGENT_ID: actorId,
+        HIVE_AGENT_NAME: LEAD_NAME,
+        HIVE_LEAD: "1",
+        HIVE_DATA_DIR: dataDir,
+        HIVE_PROJECT_LOCK: "",
+        HIVE_PROJECT_PATH: "",
+    };
+}

package/dist/leadMessageDelivery.js

@@ -3,7 +3,8 @@ import { dataDir, db } from "./db.js";
 import { CROSS_SESSION_CLOSE, postClaudeWake, senderAddress } from "./claudeWake.js";
 import { harnessFor, paneClassifierFor } from "./harnesses.js";
 import { LEAD_MESSAGE_THRESHOLD, renderLeadMessage, senderTag, shortenedSendNote, storeLeadMessage, } from "./leadMessage.js";
-import { readLeadTurnState } from "./leadState.js";
+import { readHandoffGate } from "./leadHandoffState.js";
+import { HANDED_OFF_STATES_SQL, readLeadTurnState } from "./leadState.js";
 import { loadProjectYml } from "./projectYml.js";
 import { currentOwnership, PaneOwnershipLost, paneIdentity, requireStillOwned } from "./spawn.js";
 import { holdsHumanInput, paneInCopyMode, sendText, sleep, TmuxTimeoutError, } from "./tmux.js";
@@ -46,12 +47,16 @@ function quietMessagingOn(projectId) {
     const project = db.prepare("SELECT path FROM projects WHERE id = ?").get(projectId);
     return project !== undefined && loadProjectYml(project.path).config?.quiet_messaging === true;
 }
+const handoffHolds = (agentId) => readHandoffGate(agentId)?.holdAutomation === true;
+const HANDOFF_HOLD_NOTE = "the lead is handing off to a fresh session; held until the successor completes its first turn";
 function eligible(options) {
     const { projectId, fromActor, target, submit } = options;
     if (!submit || target.kind !== "lead" || target.status !== "running" || target.actor_id === fromActor)
         return false;
     if (harnessFor(target.command).name !== "claude")
         return false;
+    if (handoffHolds(target.id))
+        return true;
     const sender = db
         .prepare("SELECT 1 AS hit FROM agents WHERE project_id = ? AND actor_id = ? AND status = 'running' AND kind = 'agent'")
         .get(projectId, fromActor);
@@ -138,8 +143,38 @@ function pasteFailure(err, pasted, buffered) {
         return `the paste timed out, so the text MAY be on screen unsubmitted: ${why}`;
     return `nothing was pasted: ${why}`;
 }
+// A message accepted for a predecessor whose pane the same lead row now holds as a handed-off
+// successor is re-pointed at that successor, once, rather than failed as a replacement pane.
+function retargetAfterHandoff(row) {
+    let accepted;
+    try {
+        accepted = JSON.parse(row.target_identity ?? "{}");
+    }
+    catch {
+        return row;
+    }
+    const lead = db.prepare("SELECT * FROM agents WHERE id = ? AND kind = 'lead' AND status = 'running'").get(row.to_agent_id);
+    if (lead === undefined || accepted.pane_pid === lead.pane_pid || accepted.tmux_target !== lead.tmux_target)
+        return row;
+    const handedOff = db
+        .prepare(`SELECT 1 AS hit FROM lead_handoffs WHERE lead_agent_id = ? AND pane_target = ? AND predecessor_pane_pid = ?
+         AND successor_pane_pid = ? AND state IN ${HANDED_OFF_STATES_SQL}`)
+        .get(lead.id, lead.tmux_target, accepted.pane_pid ?? "", lead.pane_pid);
+    if (handedOff === undefined)
+        return row;
+    const identity = JSON.stringify(paneIdentity(lead));
+    try {
+        db.prepare("UPDATE agent_messages SET target_identity = ? WHERE id = ? AND target_identity IS ? AND delivery_status = ?").run(identity, row.id, row.target_identity, MESSAGE_STATUS.fallbackPending);
+    }
+    catch {
+    }
+    return readRow(row.id) ?? row;
+}
 // One guarded pane attempt. The claim is the CAS that makes it at most one per message.
-async function paneFallback(row, snapshot) {
+async function paneFallback(original, snapshot) {
+    if (handoffHolds(original.to_agent_id))
+        return hold(original, HANDOFF_HOLD_NOTE);
+    const row = retargetAfterHandoff(original);
     let identity;
     try {
         identity = paneIdentity(JSON.parse(row.target_identity ?? ""));
@@ -229,11 +264,13 @@ export async function sendQuietLeadMessage(options) {
     const base = { agent_id: target.id, name: target.name, message_id: id, ...(long ? { shortened: true } : {}) };
     const shortNote = (channel, redelivered = false) => long ? ` ${shortenedSendNote(id, renderLeadMessage(id, text, tag, redelivered).length, channel)}` : "";
     const body = socketText(id, text, tag);
-    const skip = !registeredSocket(target)
-        ? "no messaging socket registered for this lead pane"
-        : body.includes(CROSS_SESSION_CLOSE)
-            ? "the text contains the envelope's closing tag"
-            : null;
+    const skip = handoffHolds(target.id)
+        ? HANDOFF_HOLD_NOTE
+        : !registeredSocket(target)
+            ? "no messaging socket registered for this lead pane"
+            : body.includes(CROSS_SESSION_CLOSE)
+                ? "the text contains the envelope's closing tag"
+                : null;
     // One statement makes the row visible to the scheduler, already in its route's status.
     db.prepare(`UPDATE agent_messages SET delivery_status = ?, delivery_method = ?, socket_attempt_at = ${skip === null ? NOW : "NULL"},
        delivery_note = ?, target_identity = ?, sender_tag = ? WHERE id = ?`).run(skip === null ? MESSAGE_STATUS.socketPending : MESSAGE_STATUS.fallbackPending, skip === null ? MESSAGE_METHOD.socket : MESSAGE_METHOD.pty, skip, JSON.stringify(identity), tag, id);