@cmgmyr/hive 1.5.0 → 1.7.0

package/dist/tmux.js

@@ -413,6 +413,10 @@ export function targetPid(target, snapshot) {
 export function panePid(target) {
     return targetLiveProbe(target).pid ?? "";
 }
+// A row recorded with an empty pid reads unknown for life, so a pane hive just created gets one retry.
+export function panePidForRecord(target) {
+    return panePid(target) || panePid(target);
+}
 const DESTROY_READINESS_BOUND_MS = 200;
 function paneHasEstablishedProcess(pid) {
     try {
@@ -470,6 +474,39 @@ export function rowAliveProbe(recordedSocket, target, snapshot) {
 export function paneReissued(recordedPid, probe) {
     return probe.live === true && recordedPid !== "" && probe.pid !== null && probe.pid !== recordedPid;
 }
+// The one place a row's claim on a pane is decided. An existing pane is "live" only when both
+// pids are known and equal; an empty recorded pid on a live id is "unknown", never "live".
+export function observationFailed(snapshot) {
+    return snapshot === null || snapshot.serverAnswered === false;
+}
+export function rowOwnership(row, snapshot) {
+    if (foreignSocket(row.tmux_socket))
+        return "unknown";
+    if (row.tmux_target === "")
+        return "gone";
+    const observed = snapshot === undefined ? liveTargets() : snapshot;
+    if (observed === null || observationFailed(observed))
+        return "unknown";
+    if (!targetAlive(row.tmux_target, observed))
+        return "gone";
+    if (!isPaneTarget(row.tmux_target))
+        return "unknown";
+    const pid = targetPid(row.tmux_target, observed) ?? "";
+    if (row.pane_pid === "" || pid === "")
+        return "unknown";
+    return pid === row.pane_pid ? "live" : "reissued";
+}
+// The one place a row's ownership is observed: a failed probe is its own answer, never unknown.
+export function observeRowOwnership(row) {
+    const observes = !foreignSocket(row.tmux_socket) && row.tmux_target !== "";
+    const snapshot = observes ? liveTargets() : null;
+    if (observes && observationFailed(snapshot))
+        return "probe-failed";
+    return rowOwnership(row, snapshot);
+}
+export function ownershipLiveness(ownership) {
+    return ownership === "live" ? true : ownership === "unknown" ? null : false;
+}
 export const RAW_ATTACH_TMUX_CONFIG = [
     "set -g allow-passthrough all",
 ];
@@ -1334,7 +1371,7 @@ export function findUnsafeControlChar(text, allowed) {
     }
     return null;
 }
-export async function sendText(target, text, submit = true, onPasted, onBuffered) {
+export async function sendText(target, text, submit = true, onPasted, onBuffered, beforePaneWrite) {
     // tmux hands a pane its input in 1022-byte writes, and only paste-buffer -p
     // brackets them, so send-keys -l loses everything before the last write.
     // An empty text skips the pair: set-buffer creates no buffer for it, so
@@ -1346,6 +1383,7 @@ export async function sendText(target, text, submit = true, onPasted, onBuffered
         tmux("set-buffer", "-b", buffer, "--", text);
         onBuffered?.();
         try {
+            beforePaneWrite?.();
             tmux("paste-buffer", "-d", "-p", "-b", buffer, "-t", target);
         }
         catch (err) {
@@ -1366,6 +1404,7 @@ export async function sendText(target, text, submit = true, onPasted, onBuffered
     }
     if (submit) {
         await sleep(ENTER_DELAY_MS);
+        beforePaneWrite?.();
         tmux("send-keys", "-t", target, "Enter");
     }
 }

package/dist/tools/agents.js

@@ -13,10 +13,10 @@ import { activeProfile, allowedAgents, loadProjectYml } from "../projectYml.js";
 import { classifyMiss, LEAD_MESSAGE_THRESHOLD, leadPointerMarker, missMessage, readLeadMessage, renderLeadPointer, senderTag, shortenedSendFailureClause, shortenedSendNote, storeLeadMessage, } from "../leadMessage.js";
 import { run } from "../result.js";
 import { markGoneReported } from "../scheduler.js";
-import { agentIdentityEnv, branchAt, closeAgentRow, discardOrphanedPane, isReservedAgentName, isRunningLeadActor, killAgentPane, launchAgent, LEAD_KIND, parkAgentRow, reapCodexHomeForClosedAgent, releaseParkRow, renameAgent, resumeAgent, storedLaunchOptions, } from "../spawn.js";
+import { agentIdentityEnv, branchAt, closeAgentRow, currentOwnership, discardOrphanedPane, isReservedAgentName, isRunningLeadActor, killAgentPane, launchAgent, LEAD_KIND, PaneOwnershipLost, paneIdentity, parkAgentRow, reapCodexHomeForClosedAgent, requireStillOwned, releaseParkRow, renameAgent, resumeAgent, storedLaunchOptions, } from "../spawn.js";
 import { COMMAND_KIND, runningCommandRow, stopLine, stopProcess, STOP_REASONS } from "../processes.js";
 import { readContextTokens, readContextFill, resolveTranscriptDir } from "../transcript.js";
-import { capturePane, captureFinalScreen, DEFAULT_LAYOUT, cancelCopyMode, describePaneChoice, ensureAttached, findUnsafeControlChar, holdsHumanInput, liveTargets, paneCurrentCommand, paneInCopyMode, paneWindow, pollPaneReadiness, rowAlive, rowLive, sendText, sessionName, setRemainOnExit, sleep, TEXT_ALLOWED_CONTROL_CHARS, tmux, TmuxTimeoutError, WINDOW_LAYOUTS, } from "../tmux.js";
+import { capturePane, captureFinalScreen, DEFAULT_LAYOUT, cancelCopyMode, describePaneChoice, ensureAttached, findUnsafeControlChar, holdsHumanInput, liveTargets, observationFailed, observeRowOwnership, ownershipLiveness, paneCurrentCommand, paneInCopyMode, paneWindow, pollPaneReadiness, rowOwnership, sendText, sessionName, setRemainOnExit, sleep, TEXT_ALLOWED_CONTROL_CHARS, tmux, TmuxTimeoutError, WINDOW_LAYOUTS, } from "../tmux.js";
 import { agentIdParam, agentNameParam, idParam, projectIdParam } from "./params.js";
 import { deriveProvenance, lastLogEvent, lastPermissionMode, reportsAgentStateLog, } from "../stateProvenance.js";
 const CLOSED_ROW_ORDER = "(parked_at != '') DESC, closed_at DESC, id DESC";
@@ -129,23 +129,84 @@ function buildParkReceipt(project, agent, parkedAt, branch, note) {
         ...(note ? { note } : {}),
     };
 }
-export function isLive(agent) {
-    if (agent.status !== "running")
-        return false;
-    return rowLive(agent.tmux_socket, agent.tmux_target);
+function closeRowOnly(agent, confirmSelf) {
+    const receipt = { row_only: true, agent_id: agent.id, name: agent.name, closed: true };
+    if (currentActor().startsWith("agent:")) {
+        throw new Error(`Agent ${agent.id} ("${agent.name}"): row_only retirement is reserved for a human at a terminal or a peer ` +
+            "lead; a worker may not retire rows this way. Nothing was changed.");
+    }
+    if (agent.actor_id === currentActor() && !confirmSelf) {
+        throw new Error("This would close your own session. Pass confirm_self=true only if the user explicitly asked you to close yourself.");
+    }
+    if (agent.status !== "running") {
+        return {
+            ...receipt,
+            ...(agent.parked_at ? { parked: true } : {}),
+            note: "Already closed; row_only changed nothing and left any park in place.",
+        };
+    }
+    const ownership = observeOwnership(agent);
+    if (ownership === "live") {
+        throw new Error(`Agent ${agent.id} ("${agent.name}") owns a live pane (its recorded pane pid matches), so row_only refuses: ` +
+            "retiring the row would orphan a running process with nothing left to stop it by. " +
+            (agent.kind === LEAD_KIND
+                ? "Restart or end the lead from its own terminal."
+                : "Use agent_close without row_only to stop it."));
+    }
+    if (!closeAgentRow(agent.id, paneIdentity(agent))) {
+        const after = getAgentRow(agent.project_id, agent.id, "Call agent_list(include_closed: true).");
+        if (after.status !== "running") {
+            return {
+                ...receipt,
+                ...(after.parked_at ? { parked: true } : {}),
+                note: "Already closed by someone else before this call's row-only retirement landed. Nothing else was changed.",
+            };
+        }
+        throw new Error(`Agent ${agent.id} ("${agent.name}")'s pane identity changed since this call read it, most likely a fresh ` +
+            "pane recorded on it. Nothing was closed. Re-read it with agent_status and decide again.");
+    }
+    return {
+        ...receipt,
+        note: `Row retired with no kill, stop or typing; its pane ownership read ${ownership}.` +
+            (ownership === "unknown" ? " Anything still running in that pane was left alone." : ""),
+    };
 }
 export const PROBE_FAILED_NOTE = "tmux could not be probed, so liveness is unknown. Nothing was changed. Retry in a few seconds.";
+const unknownOwnershipNote = (snapshot) => observationFailed(snapshot) ? PROBE_FAILED_NOTE : UNVERIFIED_OWNERSHIP_NOTE;
+const UNVERIFIED_OWNERSHIP_NOTE = "This row's pane cannot be verified as its own: it is on another tmux socket, or no pane pid was recorded for it, so liveness is unknown and no screen was read. Nothing was changed. If the row is stale, a human or peer lead can retire it with agent_close(row_only=true).";
 export const probeFailed = (agent) => new Error(`Agent ${agent.id} ("${agent.name}"): ${PROBE_FAILED_NOTE}`);
+// A failed probe throws rather than answering unknown, so callers keep the retry wording.
+export function observeOwnership(agent) {
+    const ownership = observeRowOwnership(agent);
+    if (ownership === "probe-failed")
+        throw probeFailed(agent);
+    return ownership;
+}
+export const REISSUED_PANE_NOTE = "Its recorded pane id now belongs to a different process (the recorded pane pid no longer matches), so its own process is gone and the pane is someone else's. Nothing was typed, read or killed there.";
+export function notOwnedError(agent, ownership) {
+    const who = `Agent ${agent.id} ("${agent.name}")`;
+    if (ownership === "gone") {
+        return new Error(`${who} has no live tmux window (its process exited or the window was killed). Close it with agent_close and spawn a new one.`);
+    }
+    if (ownership === "reissued") {
+        return new Error(`${who}: pane ownership reads reissued. ${REISSUED_PANE_NOTE} Close the row with agent_close, which retires it without touching that pane.`);
+    }
+    return new Error(`${who}: pane ownership reads unknown. ${UNVERIFIED_OWNERSHIP_NOTE}`);
+}
+// Rechecked just before a kill. "changed" skips the kill and lets the row CAS report the race.
+function stillOwnsPane(agent, action) {
+    const now = currentOwnership(agent.id, paneIdentity(agent));
+    if (now === "unknown")
+        throw new PaneOwnershipLost(agent.id, now, action);
+    return now === "live";
+}
 function requireLive(agent) {
     if (agent.status !== "running") {
         throw new Error(`Agent ${agent.id} ("${agent.name}") is closed.`);
     }
-    const live = isLive(agent);
-    if (live === null)
-        throw probeFailed(agent);
-    if (!live) {
-        throw new Error(`Agent ${agent.id} ("${agent.name}") has no live tmux window (its process exited or the window was killed). Close it with agent_close and spawn a new one.`);
-    }
+    const ownership = observeOwnership(agent);
+    if (ownership !== "live")
+        throw notOwnedError(agent, ownership);
 }
 function runningAgentNamed(projectId, name, exceptAgentId) {
     const needle = name.toLowerCase();
@@ -250,11 +311,7 @@ const PANE_READY_MS = Number(process.env.HIVE_SPAWN_READY_MS ?? 45_000);
 export function summaryLiveness(row, snapshot) {
     if (row.status !== "running")
         return false;
-    if (snapshot === undefined)
-        return rowLive(row.tmux_socket, row.tmux_target);
-    if (snapshot === null)
-        return null;
-    return rowAlive(row.tmux_socket, row.tmux_target, snapshot);
+    return ownershipLiveness(rowOwnership(row, snapshot));
 }
 function capturePaneQuietly(target) {
     try {
@@ -810,16 +867,19 @@ export function registerAgents(server) {
                 "would record a lane that cannot be resumed, and its branch can no longer be read. Recreate that " +
                 "path first if you want this lane back tomorrow, or close it with agent_close.");
         }
-        const live = isLive(agent);
-        if (live === null)
-            throw probeFailed(agent);
+        const ownership = observeOwnership(agent);
+        if (ownership === "unknown")
+            throw notOwnedError(agent, ownership);
+        let live = ownership === "live";
         if (agent.actor_id === currentActor() && args.confirm_self !== true) {
             throw new Error("This would park your own session. Pass confirm_self=true only if the user explicitly asked you to park yourself.");
         }
         const branch = branchAt(agent.cwd);
+        if (live)
+            live = stillOwnsPane(agent, "agent_park");
         if (live)
             killAgentPane(agent.tmux_target);
-        const parkedAt = parkAgentRow(agent.id, agent.tmux_target, branch);
+        const parkedAt = parkAgentRow(agent.id, paneIdentity(agent), branch);
         if (parkedAt === undefined) {
             const after = getAgentRow(project.id, agent.id, "Call agent_list(include_closed: true).");
             const report = classifyLostCas(after);
@@ -836,7 +896,10 @@ export function registerAgents(server) {
             }
             throw revivedError(agent, live, "a concurrent agent_resume reviving it", "Nothing was parked. Re-read it with agent_status and try again.");
         }
-        return buildParkReceipt(project, agent, parkedAt, branch);
+        return buildParkReceipt(project, agent, parkedAt, branch, live
+            ? undefined
+            : `Parked with no kill: its pane ownership read ${ownership === "live" ? "changed" : ownership}, so its own process was already gone and ` +
+                "that pane was left alone.");
     }));
     server.registerTool("agent_rename", {
         description: "Change a worker's display name. Its actor_id (agent:N) does not change, so every pad write, todo comment and lease it has already made stays attributable. A live claude worker is also told to retitle its own session, which shows up in its pane; that arrives as a user turn, so rename between assignments rather than mid-task. Refuses a lead target outright.",
@@ -875,7 +938,11 @@ export function registerAgents(server) {
         }
         const newName = normalizeAgentName(args.new_name, "new_name");
         requireNameFree(project.id, newName, agent.id);
-        const live = isLive(agent) === true;
+        const ownership = observeOwnership(agent);
+        if (ownership === "unknown")
+            throw notOwnedError(agent, ownership);
+        const live = ownership === "live";
+        const identity = paneIdentity(agent);
         renameAgent(agent, newName, live ? project.name : null);
         let retitled = false;
         let heldNote;
@@ -911,11 +978,18 @@ export function registerAgents(server) {
                 try {
                     await sendText(agent.tmux_target, `/rename ${newName}`, true, () => {
                         pasted = true;
-                    });
+                    }, undefined, () => requireStillOwned(agent.id, identity, "agent_rename"));
                     retitled = true;
                 }
-                catch {
-                    if (pasted) {
+                catch (err) {
+                    if (err instanceof PaneOwnershipLost) {
+                        heldNote =
+                            `Not retitled: ${err.message} The row IS renamed - it is "${newName}" now.` +
+                                (pasted
+                                    ? ` "/rename ${newName}" was pasted before the check failed and was left unsubmitted; no Enter was sent. Do not send keys to that pane until you know whose it is.`
+                                    : "");
+                    }
+                    else if (pasted) {
                         heldNote =
                             `Not retitled: the rename command reached the pane but the Enter that submits it failed, so "/rename ${newName}" is sitting on screen unsubmitted. The row IS renamed - it is "${newName}" now - only the pane's own title was left alone. Do not resend /rename: agent_send(name: ${JSON.stringify(newName)}, keys: ["Enter"]) finishes this exact delivery, or agent_send(name: ${JSON.stringify(newName)}, keys: ["C-a", "C-k"]) clears it.`;
                         try {
@@ -927,6 +1001,9 @@ export function registerAgents(server) {
                 }
             }
         }
+        if (!live) {
+            heldNote = `Not retitled: its pane ownership read ${ownership}, so no pane was read or typed into. The row IS renamed - it is "${newName}" now.`;
+        }
         return {
             agent_id: agent.id,
             actor_id: agent.actor_id,
@@ -1031,11 +1108,12 @@ export function registerAgents(server) {
     }, (args) => run(() => {
         const project = resolveProject(args.project_id);
         const agent = findAgent(project.id, args);
-        const summary = agentSummary(agent);
+        const snapshot = agent.status === "running" ? liveTargets() : null;
+        const summary = agentSummary(agent, snapshot);
         const briefPath = agentBriefPath(agent.id);
         return {
             ...summary,
-            ...(summary.alive === null ? { note: PROBE_FAILED_NOTE } : {}),
+            ...(summary.alive === null ? { note: unknownOwnershipNote(snapshot) } : {}),
             closed_at: agent.closed_at,
             current_command: summary.alive ? paneCurrentCommand(agent.tmux_target) : null,
             brief_path: existsSync(briefPath) ? briefPath : null,
@@ -1191,15 +1269,21 @@ export function registerAgents(server) {
                 outgoing = tag + args.text;
             let pasted = false;
             let buffered = false;
+            const identity = paneIdentity(agent);
             try {
                 await sendText(target, outgoing, submitting, () => {
                     pasted = true;
                 }, () => {
                     buffered = true;
-                });
+                }, () => requireStillOwned(agent.id, identity, "agent_send"));
             }
             catch (err) {
                 const shortenedClause = shortened === null ? "" : shortenedSendFailureClause(shortened.marker, shortened.message_id);
+                if (err instanceof PaneOwnershipLost) {
+                    if (!pasted)
+                        throw err;
+                    throw new Error(`[agent_send:paste-landed-enter-withheld] agent_send pasted into ${agent.name}'s pane, then withheld the Enter: ${err.message} The text is on that screen unsubmitted. Do NOT resend it and do NOT press Enter there: the pane may no longer be this worker's. Read it with agent_status first.${shortenedClause}`, { cause: err });
+                }
                 if (!pasted) {
                     if (buffered && err instanceof TmuxTimeoutError) {
                         throw new Error(`[agent_send:paste-timeout-ambiguous] agent_send's paste call to ${agent.name}'s pane timed out. A timed-out tmux call does not prove nothing happened - the server can finish a command after the client gives up waiting on it - so the text MAY already be on that screen, unsubmitted. Do not resend blindly: read the pane first with agent_output(name: ${JSON.stringify(agent.name)}), and only send again if the text genuinely is not there.${shortenedClause}`, { cause: err });
@@ -1285,7 +1369,8 @@ export function registerAgents(server) {
         const project = resolveProject(args.project_id);
         const agent = findAgent(project.id, args);
         const lines = Math.min(args.lines ?? 50, 200);
-        const alive = isLive(agent);
+        const snapshot = agent.status === "running" ? liveTargets() : null;
+        const alive = summaryLiveness(agent, snapshot);
         return {
             agent_id: agent.id,
             name: agent.name,
@@ -1296,14 +1381,14 @@ export function registerAgents(server) {
                 ? {}
                 : {
                     note: alive === null
-                        ? PROBE_FAILED_NOTE
-                        : "No live tmux window; output is not retained after exit.",
+                        ? unknownOwnershipNote(snapshot)
+                        : "No live tmux window this row owns; output is not retained after exit.",
                 }),
             ...(alive !== true && agent.exit_tail ? { exit_tail: agent.exit_tail } : {}),
         };
     }));
     server.registerTool("agent_close", {
-        description: "Kill an agent's tmux window and mark it closed, addressed by name (or agent_id). Capture handoffs (todo comments, pads) BEFORE closing; terminal output is not retained. Closing yourself requires confirm_self=true. Refuses a lead target whose pane is live; retires one whose pane is confirmed dead. A worker may never close a lead, live or dead.",
+        description: "Kill an agent's tmux window and mark it closed, addressed by name (or agent_id). Capture handoffs (todo comments, pads) BEFORE closing; terminal output is not retained. Closing yourself requires confirm_self=true. Refuses a lead target whose pane is live; retires one whose pane is confirmed dead. A worker may never close a lead, live or dead. row_only=true retires a stale row with no kill, stop or typing: for a human or peer lead only, and refused for any row that provably owns a live pane or when tmux could not be probed.",
         annotations: {
             readOnlyHint: false,
             destructiveHint: true,
@@ -1314,12 +1399,17 @@ export function registerAgents(server) {
             name: agentNameParam,
             agent_id: agentIdParam,
             confirm_self: z.boolean().optional(),
+            row_only: z
+                .boolean()
+                .optional()
+                .describe("Mark the row closed with no kill, stop or typing, for a row whose pane is gone, reissued or unverifiable. Human or peer lead only. Defaults to false."),
             project_id: projectIdParam,
         },
         outputSchema: {
             agent_id: idParam,
             name: z.string(),
             closed: z.boolean(),
+            row_only: z.boolean().optional(),
             park_released: z.boolean().optional(),
             parked: z.boolean().optional(),
             note: z.string().optional(),
@@ -1327,6 +1417,8 @@ export function registerAgents(server) {
     }, (args) => run(() => {
         const project = resolveProject(args.project_id);
         const agent = findAgent(project.id, args);
+        if (args.row_only === true)
+            return closeRowOnly(agent, args.confirm_self === true);
         if (agent.kind === LEAD_KIND && currentActor().startsWith("agent:")) {
             throw new Error(`Agent ${agent.id} ("${agent.name}") is this project's lead session. Retiring a lead - live, ` +
                 "confirmed dead, or unprobed - is reserved for a human at a terminal or a peer lead; a " +
@@ -1355,9 +1447,13 @@ export function registerAgents(server) {
             }
             return { agent_id: agent.id, name: agent.name, closed: true, park_released: true };
         }
-        const live = isLive(agent);
-        if (live === null)
-            throw probeFailed(agent);
+        const ownership = agent.status === "running" ? observeOwnership(agent) : "gone";
+        if (ownership === "unknown") {
+            throw new Error(`Agent ${agent.id} ("${agent.name}"): pane ownership reads unknown, so agent_close neither stops nor ` +
+                "retires it. " +
+                UNVERIFIED_OWNERSHIP_NOTE);
+        }
+        let live = ownership === "live";
         if (agent.kind === LEAD_KIND && live) {
             throw new Error(`Agent ${agent.id} ("${agent.name}") is this project's lead session, the one actor with no ` +
                 "supervisor above it, and its pane is still live. agent_close refuses to end a running " +
@@ -1371,17 +1467,20 @@ export function registerAgents(server) {
         const commandRow = agent.kind === COMMAND_KIND ? runningCommandRow(project.id, agent.name) : undefined;
         if (commandRow && live) {
             const stopped = stopProcess(commandRow, STOP_REASONS.byHand);
+            const after = getAgentRow(project.id, agent.id, "Call agent_list(include_closed: true).");
             return {
                 agent_id: agent.id,
                 name: agent.name,
-                closed: stopped.leg !== "still-running",
+                closed: after.status !== "running",
                 stop_leg: stopped.leg,
                 note: stopLine(stopped),
             };
         }
+        if (live)
+            live = stillOwnsPane(agent, "agent_close");
         if (live)
             killAgentPane(agent.tmux_target);
-        if (!closeAgentRow(agent.id, agent.tmux_target)) {
+        if (!closeAgentRow(agent.id, paneIdentity(agent))) {
             const after = getAgentRow(project.id, agent.id, "Call agent_list(include_closed: true).");
             const report = classifyLostCas(after);
             if (report.outcome === "retired") {
@@ -1417,6 +1516,15 @@ export function registerAgents(server) {
             catch {
             }
         }
-        return { agent_id: agent.id, name: agent.name, closed: true };
+        return {
+            agent_id: agent.id,
+            name: agent.name,
+            closed: true,
+            ...(agent.status === "running" && !live
+                ? {
+                    note: `Closed with no kill: its pane ownership read ${ownership === "live" ? "changed" : ownership}, so that pane was left alone.`,
+                }
+                : {}),
+        };
     }));
 }

package/dist/tools/meta.js

@@ -139,7 +139,7 @@ export function registerMeta(server) {
         inputSchema: { project_id: idParam },
     }, ({ project_id }) => run(() => selectProjectById(project_id)));
     server.registerTool("project_prune", {
-        description: "Delete every registered project that owns no rows anywhere in the store (pads, todos, kv, leases, agents, wakes, command_trust), verified individually before each delete. Never prunes the caller's own project. With project_id, removes exactly that one project instead of sweeping, and only if it owns no rows; otherwise refuses and names what it owns. With project_id AND confirm_name (the project's exact name), removes that one project even when it owns rows: it takes a snapshot first, refuses while the project has a running agent, then deletes the project with everything it owns (todos, comments, pads, kv, leases, agents, wakes, trust, agent messages) in one transaction and reports per-table counts and the snapshot path. queen_audit rows naming it are kept, and so are other projects' lead-idle subscriptions that target it, so a watch on its lead ends with a named reason. confirm_name without project_id is refused, and there is no forced sweep. Refuses under HIVE_PROJECT_LOCK=1: this is a whole-store sweep, and a project-locked session may only touch its own project. Immediate, permanent: no dry-run mode.",
+        description: "Delete every registered project that owns no rows anywhere in the store (pads, todos, kv, leases, agents, wakes, command_trust), verified individually before each delete. Never prunes the caller's own project. With project_id, removes exactly that one project instead of sweeping, and only if it owns no rows; otherwise refuses and names what it owns. With project_id AND confirm_name (the project's exact name), removes that one project even when it owns rows: it takes a snapshot first, refuses while a running row owns a live pane or its pane ownership cannot be verified (agent_close row_only retires the latter), then deletes the project with everything it owns (todos, comments, pads, kv, leases, agents, wakes, trust, agent messages) in one transaction and reports per-table counts and the snapshot path. queen_audit rows naming it are kept, and so are other projects' lead-idle subscriptions that target it, so a watch on its lead ends with a named reason. confirm_name without project_id is refused, and there is no forced sweep. Refuses under HIVE_PROJECT_LOCK=1: this is a whole-store sweep, and a project-locked session may only touch its own project. Immediate, permanent: no dry-run mode.",
         annotations: {
             readOnlyHint: false,
             destructiveHint: true,

package/dist/tools/pads.js

@@ -3,6 +3,13 @@ import { db } from "../db.js";
 import { currentActor, effectiveProjectId, resolveProject } from "../context.js";
 import { matchesAnyTag, parseTags, run } from "../result.js";
 import { idParam, limitParam, offsetParam, projectIdParam } from "./params.js";
+function splitsSurrogatePair(content, index) {
+    if (index <= 0 || index >= content.length)
+        return false;
+    const before = content.charCodeAt(index - 1);
+    const after = content.charCodeAt(index);
+    return before >= 0xd800 && before <= 0xdbff && after >= 0xdc00 && after <= 0xdfff;
+}
 function selectPad(projectId, padId, columns) {
     const row = db
         .prepare(`SELECT ${columns} FROM pads WHERE project_id = ? AND id = ?`)
@@ -110,7 +117,7 @@ export function registerPads(server) {
         return { pad_id: padId, revision: 1 };
     }));
     server.registerTool("pad_read", {
-        description: "Read a pad's content, revision, and metadata by pad_id or name.",
+        description: "Read a pad's content, revision, and metadata by pad_id or name. Optional offset and limit use UTF-16 code units and are nonnegative safe integers. There is no default cap; a cut inside a surrogate pair moves back one code unit, or forward if moving back would return nothing, and the result reports the effective offset.",
         annotations: {
             readOnlyHint: false,
             destructiveHint: false,
@@ -120,6 +127,8 @@ export function registerPads(server) {
         inputSchema: {
             pad_id: idParam.optional(),
             name: z.string().optional(),
+            offset: z.number().int().nonnegative().optional().describe("Start index in UTF-16 code units; an index inside a surrogate pair moves back one code unit."),
+            limit: z.number().int().nonnegative().optional().describe("Requested UTF-16 code units to read; no default cap. An end cut inside a surrogate pair moves back one code unit, or forward if moving back would return nothing."),
             project_id: projectIdParam,
         },
     }, (args) => run(() => {
@@ -139,7 +148,7 @@ export function registerPads(server) {
         else {
             throw new Error("Pass pad_id or name.");
         }
-        return {
+        const result = {
             pad_id: pad.id,
             name: pad.name,
             revision: pad.revision,
@@ -148,6 +157,23 @@ export function registerPads(server) {
             updated_at: pad.updated_at,
             content: pad.content,
         };
+        if (args.offset == null && args.limit == null)
+            return result;
+        const totalLength = pad.content.length;
+        const requestedOffset = args.offset ?? 0;
+        const offset = splitsSurrogatePair(pad.content, requestedOffset) ? requestedOffset - 1 : requestedOffset;
+        let end = args.limit == null ? totalLength : Math.min(totalLength, requestedOffset + args.limit);
+        if (splitsSurrogatePair(pad.content, end)) {
+            const backedUpEnd = end - 1;
+            end = args.limit != null && args.limit > 0 && backedUpEnd <= offset ? end + 1 : backedUpEnd;
+        }
+        return {
+            ...result,
+            content: pad.content.slice(offset, end),
+            total_length: totalLength,
+            offset,
+            next_offset: end < totalLength ? end : null,
+        };
     }));
     server.registerTool("pad_append", {
         description: "Append content to the end of a pad. Optional expected_revision guards against concurrent writes.",

package/dist/tools/wakes.js

@@ -3,13 +3,13 @@ import { db } from "../db.js";
 import { commitQueenStateWrite } from "../queenAudit.js";
 import { currentActor, effectiveProjectId, getProject, isQueenLead } from "../context.js";
 import { run } from "../result.js";
-import { findAgent, isLive, probeFailed, summaryLiveness } from "./agents.js";
+import { findAgent, observeOwnership, notOwnedError, summaryLiveness } from "./agents.js";
 import { ACTIVE_TIMER_WHERE, LOG_RETENTION, OWNED_BY_WATCH, WATCH_SCOPE_PROJECT, seedGoneCursor, } from "../scheduler.js";
 import { idParam, projectIdParam } from "./params.js";
 import { cutToUnitBudget } from "../slug.js";
 import { awaitingFirstPrompt } from "../firstPrompt.js";
 import { deriveProvenance } from "../stateProvenance.js";
-import { findUnsafeControlChar, liveTargets, paneReissued, rowAliveProbe, TEXT_ALLOWED_CONTROL_CHARS, } from "../tmux.js";
+import { findUnsafeControlChar, foreignSocket, liveTargets, observationFailed, rowOwnership, TEXT_ALLOWED_CONTROL_CHARS, } from "../tmux.js";
 import { readLeadTurnState } from "../leadState.js";
 import { LEAD_TARGET_GONE, LEAD_TARGET_REISSUED, leadSubscription, paneVeto, runningLeadOf } from "../leadWatch.js";
 import { isRunningLeadActor, LEAD_KIND } from "../spawn.js";
@@ -41,12 +41,11 @@ function resolveDelivery(projectId, deliverTo) {
         // Before the liveness probe: the harness is a durable fact about the row, while liveness is a
         // question about right now, so a dead bash worker should say what is actually wrong with it.
         refuseUnclassifiableTarget(agent);
-        const live = isLive(agent);
-        if (live === null)
-            throw probeFailed(agent);
-        if (!live) {
+        const ownership = agent.status === "running" ? observeOwnership(agent) : "gone";
+        if (ownership === "gone")
             throw new Error(`Agent "${agent.name}" has no live tmux window to deliver to.`);
-        }
+        if (ownership !== "live")
+            throw notOwnedError(agent, ownership);
         return { actor: agent.actor_id, pane: agent.tmux_target };
     }
     const actor = currentActor();
@@ -58,8 +57,13 @@ function resolveDelivery(projectId, deliverTo) {
     // against that same row's command - the never-firing timer this refusal exists to prevent.
     if (own)
         refuseUnclassifiableTarget(own);
-    if (own && isLive(own) === true) {
-        return { actor, pane: own.tmux_target };
+    if (own) {
+        const ownership = observeOwnership(own);
+        if (ownership === "live")
+            return { actor, pane: own.tmux_target };
+        // Unknown never falls through to the ambient pane: that would bind this row's actor to a pane it may not own.
+        if (ownership === "unknown")
+            throw notOwnedError(own, ownership);
     }
     const pane = process.env.TMUX_PANE;
     if (pane)
@@ -216,20 +220,20 @@ function createLeadWatch(leadProjectId, args) {
         throw new Error(`Project ${leadProjectId}'s lead runs ${JSON.stringify(commandHead(lead.command))}, whose screen hive cannot ` +
             "classify, so a turn ending while a human is typing to it could not be told apart from one nobody is at.");
     }
-    if (lead.pane_pid === "") {
-        throw new Error(`${LEAD_TARGET_REISSUED}: project ${leadProjectId}'s lead has no recorded pane pid, so a reused pane id ` +
-            "could not be told from this lead. Restart it with hive lead to record one.");
+    if (foreignSocket(lead.tmux_socket)) {
+        throw new Error(`Project ${leadProjectId}'s lead lives on a tmux socket this process cannot probe.`);
     }
     const snapshot = liveTargets();
-    if (snapshot === null)
+    if (observationFailed(snapshot))
         throw new Error("tmux did not answer, so the watched lead's pane cannot be verified. Try again.");
-    const probe = rowAliveProbe(lead.tmux_socket, lead.tmux_target, snapshot);
-    if (probe.live === null) {
-        throw new Error(`Project ${leadProjectId}'s lead lives on a tmux socket this process cannot probe.`);
+    const ownership = rowOwnership(lead, snapshot);
+    if (ownership === "unknown") {
+        throw new Error(`Project ${leadProjectId}'s lead's pane ownership is unknown: it has no recorded pane pid (or a legacy ` +
+            "window target), so a reused pane id could not be told from this lead. Restart it with hive lead to record one.");
     }
-    if (!probe.live)
+    if (ownership === "gone")
         throw new Error(`${LEAD_TARGET_GONE}: project ${leadProjectId}'s lead pane is gone.`);
-    if (paneReissued(lead.pane_pid, probe)) {
+    if (ownership === "reissued") {
         throw new Error(`${LEAD_TARGET_REISSUED}: project ${leadProjectId}'s lead pane id now belongs to another process.`);
     }
     const mode = args.mode ?? "any";
@@ -327,7 +331,7 @@ export function registerWakes(server) {
         });
     }));
     server.registerTool("wake_when_idle", {
-        description: "Wake up when watched agents go idle (exact state from Claude Code hooks) or max_wait_seconds passes - except delivery HOLDS past that bound instead, for as long as the target pane is on a dialog or has unsubmitted human text in it, rather than pasting the wake body into either (.claude/rules/tmux-and-panes.md). Two shapes for workers, plus one for the queen, and you pass EXACTLY ONE of them. agents=[...] is a ONE-SHOT over a named list: mode=any fires on the first fresh idle transition, mode=all fires when every watched agent is idle (returns already_satisfied without scheduling anything if they all are now), and either way it stops watching once it fires. scope=\"project\" is a STANDING WATCH over the crew you spawn in this project, including workers spawned later: it never stops watching, and on each finish it delivers a roster naming who finished and who is still going, until max_wait_seconds runs out or you wake_cancel it. You may hold ONE standing watch per project: a second call is refused and names the one already running, since two would report every finish twice. Use the standing watch when you are running more than one worker - a one-shot leaves every other worker unwatched from the moment it fires. Use either instead of polling. agents=[...] refuses a lead: it watches worker state, which a lead does not write. lead_project_id is the QUEEN's alone: a one-shot that fires when another registered project's running lead ENDS A TURN (never 'finished its work'), stored in and delivered to the queen's own project, and ended with a named reason if that lead's pane dies, is reissued, or restarts.",
+        description: "Wake up when watched agents go idle (exact state from Claude Code hooks) or max_wait_seconds passes - except delivery HOLDS past that bound instead, for as long as the target pane is on a dialog or has unsubmitted human text in it, rather than pasting the wake body into either (.claude/rules/tmux-and-panes.md). Two shapes for workers, plus one for the queen, and you pass EXACTLY ONE of them. agents=[...] is a ONE-SHOT over a named list: mode=any fires on the first fresh idle transition, mode=all fires when every watched agent is idle (returns already_satisfied without scheduling anything if they all are now), and either way it stops watching once it fires. Arming a one-shot of the same mode for the same deliver target and an identical watched set cancels your own older pending one and names it in the receipt's superseded. scope=\"project\" is a STANDING WATCH over the crew you spawn in this project, including workers spawned later: it never stops watching, and on each finish it delivers a roster naming who finished and who is still going, until max_wait_seconds runs out or you wake_cancel it. You may hold ONE standing watch per project: a second call is refused and names the one already running, since two would report every finish twice. Use the standing watch when you are running more than one worker - a one-shot leaves every other worker unwatched from the moment it fires. Use either instead of polling. agents=[...] refuses a lead: it watches worker state, which a lead does not write. lead_project_id is the QUEEN's alone: a one-shot that fires when another registered project's running lead ENDS A TURN (never 'finished its work'), stored in and delivered to the queen's own project, and ended with a named reason if that lead's pane dies, is reissued, or restarts.",
         annotations: {
             readOnlyHint: false,
             destructiveHint: false,
@@ -371,6 +375,7 @@ export function registerWakes(server) {
             scope: z.literal("project").optional(),
             standing: z.boolean().optional(),
             watching_now: z.array(z.string()).optional(),
+            superseded: z.array(idParam).optional(),
             mode: z.enum(["any", "all"]).optional(),
             watching: z
                 .array(z.object({
@@ -437,7 +442,24 @@ export function registerWakes(server) {
             }
         }
         const maxWait = args.max_wait_seconds ?? 900;
-        return commitQueenStateWrite("wake_when_idle", projectId, args, () => {
+        return commitQueenStateWrite("wake_when_idle", projectId, args, () => db.transaction(() => {
+            const watchedIds = watched.map((a) => a.id);
+            const sameSet = (json) => {
+                const ids = JSON.parse(json);
+                return ids.length === watchedIds.length && watchedIds.every((id) => ids.includes(id));
+            };
+            const candidates = db
+                .prepare(`SELECT id, watch FROM wakes
+                  WHERE project_id = ? AND owner = ? AND kind = ?
+                    AND watch_scope IS NULL AND deliver_actor = ? AND deliver_pane = ?
+                    AND fired_at IS NULL AND cancelled_at IS NULL
+                    AND id NOT IN (SELECT wake_id FROM lead_idle_subscriptions)`)
+                .all(projectId, currentActor(), `idle_${mode}`, delivery.actor, delivery.pane)
+                .filter((w) => sameSet(w.watch))
+                .map((w) => w.id);
+            const superseded = candidates.filter((id) => db
+                .prepare("UPDATE wakes SET cancelled_at = datetime('now') WHERE id = ? AND cancelled_at IS NULL AND fired_at IS NULL")
+                .run(id).changes === 1);
             const info = db
                 .prepare(`INSERT INTO wakes (project_id, owner, body, kind, watch, deliver_actor, deliver_pane,
                  max_wait_at)
@@ -445,6 +467,7 @@ export function registerWakes(server) {
                 .run(projectId, currentActor(), args.body, `idle_${mode}`, JSON.stringify(watched.map((a) => a.id)), delivery.actor, delivery.pane, maxWait);
             return {
                 wake_id: Number(info.lastInsertRowid),
+                ...(superseded.length > 0 ? { superseded } : {}),
                 mode,
                 watching: watched.map((a) => {
                     const { state, ...provenance } = deriveProvenance(a, summaryLiveness(a, snapshot));
@@ -456,7 +479,7 @@ export function registerWakes(server) {
                     ? "Fires on the next fresh idle transition; agents already idle now do not count."
                     : "Fires when all watched agents are idle.",
             };
-        });
+        }).immediate());
     }));
     server.registerTool("wake_get", {
         description: "Read one wake-up by id, in this project, with its UNTRUNCATED body. wake_list truncates " +