@cmgmyr/hive 1.5.0 → 1.6.0

package/claude-plugin/skills/profile/SKILL.md

@@ -9,7 +9,27 @@ You are interviewing someone to produce, or change, a hive profile: the standing
 
 ## Read before you ask anything
 
-Run `hive profile list` and `hive doctor` (or read this project's `hive.yml` directly) before the first question. If this is an edit, also read the named profile's current, rendered behavior with `hive profile read <file> --profile <name>` for each of `posture.md`, `runbook.md`, `worker.md`, and any other `.md` it carries, so you understand what this profile actually does today. Do not ask the user to repeat anything already answered by what you just read. This rendered read is for understanding only - `references/interview.md` covers the raw template (via `hive profile path`) you must read from, and write onto, when you actually apply an edit; a rendered copy drops any conditional section whose var is unset, so it is never a safe edit source.
+Run `hive profile list` and `hive doctor` (or read this project's `hive.yml` directly) before the first question. If this is an edit, also read the named profile's current, rendered behavior for each of `posture.md`, `runbook.md`, `worker.md`, and any other `.md` it carries, using "Read a rendered file in bounded sections" below, so you understand what this profile actually does today. Do not ask the user to repeat anything already answered by what you just read. This rendered read is for understanding only - `references/interview.md` covers the raw template (via `hive profile path`) you must read from, and write onto, when you actually apply an edit; a rendered copy drops any conditional section whose var is unset, so it is never a safe edit source.
+
+## Read a rendered file in bounded sections
+
+A harness may persist tool output over about 30KB to a file and show only a short preview, so a large rendered file read straight into a tool result is read mostly unseen. Redirect first, then look. `profile_name` is a name from `hive profile list`, `profile_file` is a filename it lists, and `profile_rendered` is a disposable file:
+
+```sh
+profile_rendered=$(mktemp)
+hive profile read "$profile_file" --profile "$profile_name" > "$profile_rendered" && wc -c < "$profile_rendered"
+printf '%s\n' "$profile_rendered"
+```
+
+Shell variables do not survive between tool calls. Note the path the last line printed and write that literal path into every later command and every file-reader call; do not rely on `$profile_rendered` after this call.
+
+Use the saved content only if the read command succeeded. `wc -c` is the rendered size in bytes, the same number `hive profile list` and `hive doctor` show. If it is 25600 or less, read the whole file with your file reader. Above that, never read the whole file in one tool call; read it in sections of at most 16000 bytes each:
+
+1. Check for long lines first: `awk 'length > 2000 {print NR; exit}' PATH`. A file reader truncates any line over 2000 characters, so if this prints a line number, read the whole file by bytes with step 3 instead of with line ranges.
+2. Otherwise pick a line range with your file reader's offset and limit, and measure it first: `sed -n '1,80p' PATH | wc -c`. Shrink the range until the count is 16000 or less, then read it. Continue from the next line until you have read the last line. A scan of the headers is not a read.
+3. To read by bytes: `dd if=PATH bs=1 skip=0 count=16000 2>/dev/null`. Advance `skip` by 15996 each time, which overlaps 4 bytes so text split at a section edge shows whole in the next section. Stop when a section reaches the byte count from `wc -c`.
+
+Delete the temporary file when you are done. It is for understanding and checking only, never a source for an edit (see below).
 
 ## Discovery first, not a checklist
 
@@ -70,7 +90,7 @@ A command, a repository name, a ticket prefix: these belong in `hive.yml` `vars`
 
 ## Validate before you tell them it's done
 
-After writing, run `hive doctor` and `hive profile read <file> --profile <name>` for each file you touched, from the project the profile is meant to serve. A profile with no readable `runbook.md` fails `hive doctor` outright; `posture.md` and `worker.md` do not, but check them anyway. Tell the user to restart any running hive session so it picks up the change, and invite one small follow-up edit once they've tried it - that is the expected way a profile keeps improving.
+After writing, run `hive doctor` and read each file you touched with "Read a rendered file in bounded sections" above, from the project the profile is meant to serve. Read it to the last line: a change near the end of a large file is easy to miss. A profile with no readable `runbook.md` fails `hive doctor` outright; `posture.md` and `worker.md` do not, but check them anyway. Tell the user to restart any running hive session so it picks up the change, and invite one small follow-up edit once they've tried it - that is the expected way a profile keeps improving.
 
 ## What this skill does not do
 

package/dist/build-info.json

@@ -1 +1 @@
-{"version":"1.5.0","sha":"c050e7f","dirty":false,"build_id":"56840ccc-881f-49ae-bbc4-440224077976"}
+{"version":"1.6.0","sha":"ac13530","dirty":false,"build_id":"428a468f-98af-497e-a40c-fb87feef27ac"}

package/dist/cli.js

@@ -30,7 +30,7 @@ import { probeSessionInterpreter, reexecTarget, sessionStartVerdict, } from "./s
 import { backupHealth, backupNow, backupsDir, formatBytes, listSnapshots, previewRestore, restoreSnapshot, totalSizeBytes, } from "./backup.js";
 import { describeTeardownWindow, readTeardowns, teardownLogPath, } from "./teardown.js";
 import { asNameClash, buildEnvFlags, closeAgentRow, isReservedAgentName, launchAgent, LEAD_KIND, LEAD_NAME, mintLeadActorId, upsertActor, withWindowClaim, } from "./spawn.js";
-import { adoptableWindow, applyLayout, claimInitialWindow, configureHiveWindow, controlModeFor, createWindow, DEFAULT_LAYOUT, describePaneChoice, ensureSession, findProjectWindow, foreignSocket, isPaneTarget, isViewSessionName, listOwnedWindows, ORPHAN_MIN_AGE_MS, orphanScratchServers, orphansWorthWarningAbout, paneIsAloneInWindow, paneVisibility, panePid, PROCESSES_LAYOUT, processesPaneTitle, processesWindowName, projectWindows, RAW_ATTACH_TMUX_CONFIG, renderAttachCommand, resolveAttachTarget, resolveInTmuxTarget, paneReissued, rowLive, rowLiveProbe, SESSION_PREFIX, appendGlobalHook, globalHooks, replaceGlobalHooks, sessionName, setPaneTitle, shellQuote, shownPaneTitle, makeProcessesWindow, tmux, TMUX_DOC, tmuxSaysNothingThere, tmuxTimeoutOverride, tmuxSocketPath, untrustedTmuxServer, waitForPaneEstablished, windowLayout, } from "./tmux.js";
+import { adoptableWindow, applyLayout, claimInitialWindow, configureHiveWindow, controlModeFor, createWindow, DEFAULT_LAYOUT, describePaneChoice, ensureSession, findProjectWindow, foreignSocket, isPaneTarget, isViewSessionName, listOwnedWindows, liveTargets, observationFailed, ORPHAN_MIN_AGE_MS, orphanScratchServers, orphansWorthWarningAbout, paneIsAloneInWindow, paneVisibility, panePid, PROCESSES_LAYOUT, processesPaneTitle, processesWindowName, projectWindows, RAW_ATTACH_TMUX_CONFIG, renderAttachCommand, resolveAttachTarget, resolveInTmuxTarget, paneReissued, rowLive, rowLiveProbe, rowOwnership, SESSION_PREFIX, appendGlobalHook, globalHooks, replaceGlobalHooks, sessionName, setPaneTitle, shellQuote, shownPaneTitle, makeProcessesWindow, tmux, TMUX_DOC, tmuxSaysNothingThere, tmuxTimeoutOverride, tmuxSocketPath, untrustedTmuxServer, waitForPaneEstablished, windowLayout, } from "./tmux.js";
 import { describeVisibility, processCounts } from "./dashboard.js";
 import { runningCommandRow, runningCommandRows, snapshotProcesses, stopAllProcesses, stopLine, stopProcess, STOP_REASONS, } from "./processes.js";
 import { activeProfile, agentVarKeys, BUILT_IN_PROJECT_YML, configHash, loadProjectYml, mergedProjectVars, NO_PROFILE, PROJECT_YML_KEYS, resolveCommandDir, resolveFirstMessage, } from "./projectYml.js";
@@ -1111,6 +1111,16 @@ function profileDriftText(f) {
         text: `hive's default ${f.file} changed since you forked it${pct != null ? ` (${pct}% diverged)` : ""}`,
     };
 }
+const PROFILE_SIZE_WARNING_BYTES = 25600;
+function profileRenderedBytes(name, file, vars) {
+    const rendered = renderProfileFile(name, file, vars);
+    return rendered == null ? null : Buffer.byteLength(withTrailingNewline(rendered), "utf8");
+}
+function profileSizeAdvisory(name, file) {
+    return (`${name}/${file}: rendered size exceeds ${PROFILE_SIZE_WARNING_BYTES} bytes. A harness may persist tool output ` +
+        "over about 30KB and show only a short preview. Split into smaller profile files read with hive profile read, " +
+        "or redirect hive profile read to a file and read by section.");
+}
 function cmdProfile(argv) {
     const [sub, ...rest] = argv;
     try {
@@ -1125,7 +1135,9 @@ function cmdProfile(argv) {
                     return;
                 }
                 const here = findProjectForCwd();
-                const current = here ? activeProfile(loadProjectYml(here.path).config) : null;
+                const hereConfig = here ? loadProjectYml(here.path).config : null;
+                const current = here ? activeProfile(hereConfig) : null;
+                const listVars = mergedProjectVars(hereConfig);
                 const statuses = names.map((profile) => profileStatus(profile));
                 const fileWidth = Math.max(11, ...statuses.flatMap((s) => s.files.map((f) => f.file.length)));
                 for (const [i, profile] of names.entries()) {
@@ -1133,7 +1145,11 @@ function cmdProfile(argv) {
                     console.log(`${profile === current ? "*" : " "} ${profile}`);
                     for (const f of status.files) {
                         const drift = profileDriftText(f);
-                        console.log(`    ${f.file.padEnd(fileWidth)} ${f.source.padEnd(7)} ${f.path}${drift ? `   (${drift.text})` : ""}`);
+                        const bytes = profileRenderedBytes(profile, f.file, listVars);
+                        const size = bytes == null ? "[rendered size unavailable]" : `[${bytes} rendered bytes]`;
+                        console.log(`    ${f.file.padEnd(fileWidth)} ${f.source.padEnd(7)} ${f.path}${drift ? `   (${drift.text})` : ""} ${size}`);
+                        if (bytes != null && bytes > PROFILE_SIZE_WARNING_BYTES)
+                            console.log(`      ${profileSizeAdvisory(profile, f.file)}`);
                     }
                 }
                 if (current)
@@ -1550,9 +1566,17 @@ function cmdHide(argv) {
         return `${name}: hidden`;
     }));
 }
+const LEAD_OWNERSHIP_LABEL = {
+    live: "running",
+    gone: "no live pane",
+    reissued: "no live pane",
+    unknown: "pane identity unknown",
+};
 function cmdStatus() {
     janitor();
     let anyOutput = false;
+    let snapshot;
+    const statusSnapshot = () => (snapshot === undefined ? (snapshot = liveTargets()) : snapshot);
     let windows;
     let windowsError;
     const ownedWindows = () => {
@@ -1598,7 +1622,9 @@ function cmdStatus() {
         for (const a of agents) {
             const state = a.kind === "agent"
                 ? describeForHuman(deriveProvenance(a, null))
-                : (whereIs.get(a.name) ?? "running");
+                : a.kind === LEAD_KIND
+                    ? LEAD_OWNERSHIP_LABEL[rowOwnership(a, statusSnapshot())]
+                    : (whereIs.get(a.name) ?? "running");
             const label = a.kind === "command" ? "cmd  " : a.kind === LEAD_KIND ? "lead " : "agent";
             console.log(`  ${label}  ${a.name.padEnd(20)} ${state}`);
             if (reportsAgentStateLog(a)) {
@@ -2153,7 +2179,7 @@ function reportCrewTeardown(projectId) {
 }
 function reportStalledWorkers(projectId) {
     const latched = db
-        .prepare(`SELECT name, command, kind, cwd, session_id, transcript_path, agent_state, state_changed_at, tmux_target, tmux_socket
+        .prepare(`SELECT name, command, kind, cwd, session_id, transcript_path, agent_state, state_changed_at, tmux_target, tmux_socket, pane_pid
            FROM agents
           WHERE project_id = ? AND status = 'running' AND kind = 'agent'
             AND agent_state IN ('working', 'waiting') AND state_changed_at IS NOT NULL
@@ -2164,6 +2190,7 @@ function reportStalledWorkers(projectId) {
         // never this latch"), and a harness with no transcript to check would have nothing to read.
         .filter((row) => reportsAgentStateLog(row) && hasTranscriptSignal(row) && row.session_id !== "");
     const stalled = [];
+    let snapshot;
     for (const row of latched) {
         const latchedFor = ageSecondsSince(row.state_changed_at);
         if (latchedFor < STALL_BOUND_SECONDS)
@@ -2180,7 +2207,9 @@ function reportStalledWorkers(projectId) {
         if (stale !== "never" && stale.seconds < STALL_BOUND_SECONDS)
             continue;
         if (row.agent_state === "waiting") {
-            if (foreignSocket(row.tmux_socket))
+            if (snapshot === undefined)
+                snapshot = liveTargets();
+            if (rowOwnership(row, snapshot) !== "live")
                 continue;
             const choiceCheck = paneClassifierFor(row.command)?.choiceCheck;
             if (!choiceCheck || choiceCheck(row.tmux_target).awaitingChoice !== false)
@@ -2359,6 +2388,12 @@ function cmdDoctor(argv) {
             warn("profile vars", `hive.yml vars ${collisions.join(", ")} are derived from agents: and are ignored.`);
         }
         const vars = mergedProjectVars(cfg);
+        for (const f of resolved) {
+            const bytes = profileRenderedBytes(name, f.file, vars);
+            info("profile size", bytes == null ? `${name}/${f.file}: rendered size unavailable` : `${name}/${f.file}: ${bytes} rendered bytes`);
+            if (bytes != null && bytes > PROFILE_SIZE_WARNING_BYTES)
+                info("profile size warning", profileSizeAdvisory(name, f.file));
+        }
         const renderedText = profileFileNames(name)
             .map((file) => renderProfileFile(name, file, vars))
             .filter((t) => t != null)
@@ -2408,21 +2443,36 @@ function cmdDoctor(argv) {
     });
     if (here) {
         const lead = db
-            .prepare("SELECT tmux_target, tmux_socket FROM agents WHERE project_id = ? AND kind = ? AND status = 'running' ORDER BY id")
+            .prepare("SELECT id, tmux_target, tmux_socket, pane_pid FROM agents WHERE project_id = ? AND kind = ? AND status = 'running' ORDER BY id")
             .get(here.id, LEAD_KIND);
         if (lead) {
-            const live = rowLive(lead.tmux_socket, lead.tmux_target);
-            if (live === false) {
-                warn("lead", "the lead's row is running but its pane is not live. The janitor leaves lead rows alone on " +
+            const snapshot = liveTargets();
+            const ownership = rowOwnership(lead, snapshot);
+            const unobserved = !foreignSocket(lead.tmux_socket) && observationFailed(snapshot);
+            if (ownership === "gone" || ownership === "reissued") {
+                warn("lead", (ownership === "reissued"
+                    ? "the lead's row is running but its pane id now belongs to a different process. "
+                    : "the lead's row is running but its pane is not live. ") +
+                    "The janitor leaves lead rows alone on " +
                     "purpose, so nothing will fix this by itself. Run `hive lead` to record a fresh pane and reuse " +
                     "this identity, or ask a claude session connected to this project's hive MCP server to call " +
-                    "the agent_close tool on it to retire the row for good - required before `hive restore`, which " +
+                    (ownership === "reissued"
+                        ? `agent_close({agent_id: ${lead.id}, row_only: true}) on it (plain agent_close refuses a pane id ` +
+                            "that still exists)"
+                        : "the agent_close tool on it") +
+                    " to retire the row for good - required before `hive restore`, which " +
                     "otherwise refuses while any lead row reads running, and end that session too, since it also " +
                     "holds this store open.");
             }
-            else if (live === null) {
+            else if (ownership === "unknown" && unobserved) {
                 warn("lead", "the lead's pane liveness could not be probed (tmux did not answer).");
             }
+            else if (ownership === "unknown") {
+                warn("lead", `pane identity unknown: the lead's row (agents.id ${lead.id}) cannot be verified as owning pane ` +
+                    `${lead.tmux_target || "(none)"}, because it is on another tmux socket or no pane pid was recorded ` +
+                    "for it. Its screen was not read. If this lead is gone, a human or peer lead (never a worker) can " +
+                    `retire the row with the MCP tool agent_close({agent_id: ${lead.id}, row_only: true}).`);
+            }
         }
         const stuck = db
             .prepare("SELECT name, kind, tmux_socket FROM agents WHERE project_id = ? AND status = 'running' AND kind != ?")
@@ -2441,19 +2491,21 @@ function cmdDoctor(argv) {
     }
     if (here) {
         const workers = db
-            .prepare("SELECT name, actor_id, command, kind, tmux_target, tmux_socket FROM agents WHERE project_id = ? AND status = 'running' AND kind = 'agent' ORDER BY id")
+            .prepare("SELECT name, actor_id, command, kind, tmux_target, tmux_socket, pane_pid FROM agents WHERE project_id = ? AND status = 'running' AND kind = 'agent' ORDER BY id")
             .all(here.id);
+        const paneSnapshot = workers.length > 0 ? liveTargets() : null;
         let inputBoxClean = 0;
         let inputBoxDrifted = 0;
         let inputBoxUnclassified = 0;
         let leadsProbed = 0;
         let workersProbed = 0;
         const leadRows = db
-            .prepare("SELECT name, command, tmux_target, tmux_socket FROM agents WHERE project_id = ? AND kind = ? AND status = 'running' ORDER BY id")
+            .prepare("SELECT name, command, tmux_target, tmux_socket, pane_pid FROM agents WHERE project_id = ? AND kind = ? AND status = 'running' ORDER BY id")
             .all(here.id, LEAD_KIND);
+        const leadSnapshot = leadRows.length > 0 ? (paneSnapshot ?? liveTargets()) : null;
         for (const leadBox of leadRows) {
             const leadHarness = harnessFor(leadBox.command);
-            if (!leadHarness.classifiesPaneScreen || foreignSocket(leadBox.tmux_socket))
+            if (!leadHarness.classifiesPaneScreen || rowOwnership(leadBox, leadSnapshot) !== "live")
                 continue;
             leadsProbed += 1;
             const box = leadHarness.paneClassifier.inputBoxState(leadBox.tmux_target);
@@ -2478,20 +2530,26 @@ function cmdDoctor(argv) {
                 workersReported += 1;
                 // Dispatched through w's OWN harness, never the claude-only import - reading a codex pane
                 // with claude's dialog regexes fails silently in either direction (.claude/rules/tmux-and-panes.md).
+                const ownership = rowOwnership(w, paneSnapshot);
                 const foreign = foreignSocket(w.tmux_socket);
+                const unowned = ownership !== "live";
                 const workerChoiceCheck = paneClassifierFor(w.command)?.choiceCheck;
-                const { awaitingChoice, tail } = foreign || !workerChoiceCheck ? { awaitingChoice: null, tail: "" } : workerChoiceCheck(w.tmux_target);
+                const { awaitingChoice, tail } = unowned || !workerChoiceCheck ? { awaitingChoice: null, tail: "" } : workerChoiceCheck(w.tmux_target);
                 if (awaitingChoice === true)
                     dialogCount += 1;
                 verboseInfo("worker live state", `worker ${w.name}`, `last log event: ${describeLastLogEvent(lastLogEvent(w.actor_id))}`, `permission mode: ${lastPermissionMode(w.actor_id) ?? "unknown (no record)"}`, foreign
                     ? `pane: recorded on a different tmux socket (${w.tmux_socket}); this process cannot read it`
-                    : `pane: ${describePaneChoice(awaitingChoice)}`, ...(foreign
+                    : unowned
+                        ? `pane: not read - pane ownership ${ownership}`
+                        : `pane: ${describePaneChoice(awaitingChoice)}`, ...(foreign
                     ? ["tail: (not read - foreign socket)"]
-                    : awaitingChoice === null
-                        ? ["tail: (pane could not be read)"]
-                        : tail === ""
-                            ? ["tail: (pane rendered nothing)"]
-                            : ["tail:", ...tail.split("\n").map((line) => `| ${line}`)]));
+                    : unowned
+                        ? [`tail: (not read - pane ownership ${ownership})`]
+                        : awaitingChoice === null
+                            ? ["tail: (pane could not be read)"]
+                            : tail === ""
+                                ? ["tail: (pane rendered nothing)"]
+                                : ["tail:", ...tail.split("\n").map((line) => `| ${line}`)]));
             }
             // Gated on classifiesPaneScreen, not reportsAgentStateLog: this drift check only needs the pane,
             // and a codex worker's pane has been readable since todo 524, independent of whether its
@@ -2499,7 +2557,7 @@ function cmdDoctor(argv) {
             // own harness, never the claude-only import above, or a codex worker's screen gets read with
             // claude's regexes (see hive-internals).
             const harness = harnessFor(w.command);
-            if (!harness.classifiesPaneScreen || foreignSocket(w.tmux_socket))
+            if (!harness.classifiesPaneScreen || rowOwnership(w, paneSnapshot) !== "live")
                 continue;
             workersProbed += 1;
             const box = harness.paneClassifier.inputBoxState(w.tmux_target);

package/dist/contextCheckpoint.js

@@ -24,7 +24,7 @@ export function contextCheckpointAdditionalContext(actorId, thresholdPercent, fi
         return null;
     }
 }
-export function runContextCheckpointHook(kind) {
+export function runContextCheckpointHook(kind, suppliedPayload) {
     const thresholdText = process.env.HIVE_CONTEXT_CHECKPOINT_PERCENT;
     if (!thresholdText || !/^\d+$/.test(thresholdText))
         return;
@@ -35,7 +35,7 @@ export function runContextCheckpointHook(kind) {
     if (!actorId.startsWith("agent:") || (kind !== "claude" && kind !== "codex"))
         return;
     try {
-        const payload = JSON.parse(readFileSync(0, "utf8"));
+        const payload = suppliedPayload === undefined ? JSON.parse(readFileSync(0, "utf8")) : suppliedPayload;
         if (payload === null || typeof payload !== "object" || Array.isArray(payload))
             return;
         const fill = readContextFill(kind, {

package/dist/help.js

@@ -175,7 +175,10 @@ runbook (fork it first), not a pad write.`,
   agent_close(name|agent_id) — kill the worker's pane and mark closed. Capture
     handoffs first; output is not retained. Self-close needs confirm_self.
     On a PARKED row (by agent_id) it releases the park instead, which is how
-    you abandon a lane you have decided not to resume.
+    you abandon a lane you have decided not to resume. row_only=true marks
+    a stale row closed with no kill, stop or typing; a human or peer lead
+    only, refused for a row that provably owns a live pane or when tmux
+    could not be probed.
 
 Address a worker by its name, not its id: agent_send(name="impl", ...). A
 partial name works when it matches one running worker, so name="123" finds
@@ -257,8 +260,9 @@ Every pad, todo, kv entry, and lease belongs to one project (a directory).
     under HIVE_PROJECT_LOCK=1 since it sweeps every project, not just yours.
     With project_id, removes only that project, and only if it owns no rows.
     With project_id and confirm_name (its exact name), removes it with every
-    row it owns after a snapshot; refuses while it has a running agent. From a
-    terminal: hive project rm <id|path> [--yes].
+    row it owns after a snapshot; refuses while a running row owns a live
+    pane or cannot be verified (agent_close row_only retires the latter).
+    From a terminal: hive project rm <id|path> [--yes].
 
 Resolution order: explicit project_id argument, then session selection, then
 working-directory auto-detection. When the working directory matches no

package/dist/hook.js

@@ -1,7 +1,70 @@
 #!/usr/bin/env node
-import { readFileSync } from "node:fs";
+import { readFileSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, join, parse, relative, sep } from "node:path";
 import { awaitingFirstPromptSql } from "./firstPrompt.js";
 import { liveBackgroundTasks, SUBAGENT_LATCH_SQL, withholdsIdle } from "./backgroundTasks.js";
+function canonicalPathWithMissingSuffix(input) {
+    if (!isAbsolute(input) || input.includes("\0"))
+        return null;
+    let current = parse(input).root;
+    const missing = [];
+    try {
+        current = realpathSync(current);
+    }
+    catch {
+        return null;
+    }
+    for (const part of input.slice(parse(input).root.length).split(sep)) {
+        if (part === "" || part === ".")
+            continue;
+        if (part === "..") {
+            if (missing.length)
+                missing.pop();
+            else
+                current = dirname(current);
+            continue;
+        }
+        if (missing.length) {
+            missing.push(part);
+            continue;
+        }
+        const candidate = join(current, part);
+        try {
+            current = realpathSync(candidate);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                return null;
+            missing.push(part);
+        }
+    }
+    return join(current, ...missing);
+}
+function acceptsWorkerHook(row, payload, sessionsRoot) {
+    if (!row || row.kind !== "agent" || row.codex_home === "" || sessionsRoot === undefined)
+        return true;
+    const transcript = payload.transcript_path;
+    if (typeof transcript === "string" && transcript !== "") {
+        const canonicalRoot = canonicalPathWithMissingSuffix(sessionsRoot);
+        const canonicalTranscript = canonicalPathWithMissingSuffix(transcript);
+        if (canonicalRoot === null || canonicalTranscript === null)
+            return false;
+        const rel = relative(canonicalRoot, canonicalTranscript);
+        return rel !== "" && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+    }
+    if (transcript !== undefined && transcript !== null && transcript !== "")
+        return false;
+    return (typeof row.session_id === "string" && row.session_id !== "" &&
+        typeof payload.session_id === "string" && payload.session_id !== "" &&
+        row.session_id === payload.session_id);
+}
+function validCheckpointThreshold() {
+    const text = process.env.HIVE_CONTEXT_CHECKPOINT_PERCENT;
+    if (!text || !/^\d+$/.test(text))
+        return false;
+    const value = Number(text);
+    return Number.isInteger(value) && value >= 1 && value <= 100;
+}
 let raw;
 function readRaw() {
     if (raw === undefined) {
@@ -161,8 +224,33 @@ function stateFor(event, actorId) {
 }
 if (process.argv[2] === "post_tool_use") {
     try {
+        const kind = process.argv[3];
+        const actorId = process.env.HIVE_AGENT_ID ?? "";
+        let suppliedPayload;
+        if (kind === "codex" && validCheckpointThreshold() && actorId.startsWith("agent:")) {
+            suppliedPayload = readPayload();
+            const { db } = await import("./db.js");
+            const row = db.prepare("SELECT kind, command, status, codex_home, session_id FROM agents WHERE actor_id = ?")
+                .get(actorId);
+            if (row?.kind === "agent") {
+                const { harnessFor } = await import("./harnesses.js");
+                if (harnessFor(row.command).name === "codex") {
+                    if (row.status !== "running")
+                        process.exit(0);
+                    if (typeof row.codex_home === "string" && row.codex_home !== "") {
+                        const { codexHomeDir } = await import("./codexHome.js");
+                        if (!acceptsWorkerHook(row, suppliedPayload, join(codexHomeDir(row.codex_home), "sessions"))) {
+                            process.exit(0);
+                        }
+                    }
+                }
+            }
+        }
         const { runContextCheckpointHook } = await import("./contextCheckpoint.js");
-        runContextCheckpointHook(process.argv[3]);
+        if (suppliedPayload === undefined)
+            runContextCheckpointHook(kind);
+        else
+            runContextCheckpointHook(kind, suppliedPayload);
     }
     catch { }
     process.exit(0);
@@ -172,13 +260,43 @@ try {
     const actorId = process.env.HIVE_AGENT_ID;
     if (actorId) {
         const event = process.argv[2] ?? "";
-        const state = stateFor(event, actorId);
-        if (state !== null) {
-            db.prepare("UPDATE agents SET agent_state = ?, state_changed_at = datetime('now') WHERE actor_id = ? AND kind = 'agent'").run(state, actorId);
-        }
-        if (event === "prompt") {
-            db.prepare(`UPDATE agents SET resumed_at = '' WHERE actor_id = ? AND kind = 'agent' AND ${awaitingFirstPromptSql("agents")}`).run(actorId);
+        const hookPayload = readPayload();
+        const row = db.prepare("SELECT kind, command, status, codex_home, session_id FROM agents WHERE actor_id = ?")
+            .get(actorId);
+        let guarded = false;
+        let state = null;
+        if (row?.kind === "agent") {
+            const { harnessFor } = await import("./harnesses.js");
+            if (harnessFor(row.command).name === "codex") {
+                if (row.status !== "running")
+                    process.exit(0);
+                const { codexHomeDir } = await import("./codexHome.js");
+                const result = db.transaction(() => {
+                    const current = db.prepare("SELECT kind, command, status, codex_home, session_id FROM agents WHERE actor_id = ?")
+                        .get(actorId);
+                    if (current?.kind === "agent" && harnessFor(current.command).name === "codex" && current.status !== "running") {
+                        return { status: "inactive", state: null };
+                    }
+                    if (!current || current.kind !== "agent" || typeof current.codex_home !== "string" || !current.codex_home || harnessFor(current.command).name !== "codex") {
+                        return { status: "changed", state: null };
+                    }
+                    const sessionsRoot = join(codexHomeDir(current.codex_home), "sessions");
+                    if (!acceptsWorkerHook(current, hookPayload, sessionsRoot))
+                        return { status: "rejected", state: null };
+                    const state = applyWorkerTransition(actorId, event);
+                    reconcileSessionId(actorId, hookPayload);
+                    reconcileTranscriptPath(actorId, hookPayload);
+                    db.prepare("UPDATE actors SET last_seen_at = datetime('now') WHERE id = ?").run(actorId);
+                    return { status: "accepted", state };
+                }).immediate();
+                if (result.status === "rejected" || result.status === "inactive")
+                    process.exit(0);
+                guarded = result.status === "accepted";
+                state = result.state;
+            }
         }
+        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")) {
             try {
@@ -195,12 +313,24 @@ try {
             catch {
             }
         }
-        reconcileSessionId(actorId, readPayload());
-        reconcileTranscriptPath(actorId, readPayload());
-        db.prepare("UPDATE actors SET last_seen_at = datetime('now') WHERE id = ?").run(actorId);
+        if (!guarded) {
+            reconcileSessionId(actorId, hookPayload);
+            reconcileTranscriptPath(actorId, hookPayload);
+            db.prepare("UPDATE actors SET last_seen_at = datetime('now') WHERE id = ?").run(actorId);
+        }
         record(actorId, event, state ?? UNCHANGED);
     }
 }
 catch {
 }
 process.exit(0);
+function applyWorkerTransition(actorId, event) {
+    const state = stateFor(event, actorId);
+    if (state !== null) {
+        db.prepare("UPDATE agents SET agent_state = ?, state_changed_at = datetime('now') WHERE actor_id = ? AND kind = 'agent'").run(state, actorId);
+    }
+    if (event === "prompt") {
+        db.prepare(`UPDATE agents SET resumed_at = '' WHERE actor_id = ? AND kind = 'agent' AND ${awaitingFirstPromptSql("agents")}`).run(actorId);
+    }
+    return state;
+}

package/dist/portfolio.js

@@ -4,7 +4,7 @@ import { existsSync } from "node:fs";
 import { parseTags } from "./result.js";
 import { OPEN_BLOCKERS_SQL } from "./tools/todos.js";
 import { readLeadTurnState } from "./leadState.js";
-import { liveTargets, paneReissued, rowAlive, rowAliveProbe } from "./tmux.js";
+import { liveTargets, ownershipLiveness, rowOwnership } from "./tmux.js";
 export const PORTFOLIO_REASONS = [
     "needs_human",
     "dead_lead_pane",
@@ -84,15 +84,14 @@ function projectRow(project, now, snapshot) {
     const agents = db
         .prepare("SELECT id, kind, agent_state, tmux_target, tmux_socket, pane_pid FROM agents WHERE project_id = ? AND status = 'running' ORDER BY id")
         .all(project.id);
-    const liveness = (a) => snapshot ? rowAlive(a.tmux_socket, a.tmux_target, snapshot) : null;
-    const reissued = (a) => snapshot !== null && paneReissued(a.pane_pid, rowAliveProbe(a.tmux_socket, a.tmux_target, snapshot));
+    const liveness = (a) => ownershipLiveness(rowOwnership(a, snapshot));
     const workers = { working: 0, idle: 0, needs_input: 0, other: 0, unreachable: 0, unconfirmed: 0 };
     let liveWorking = 0;
     let liveWaiting = 0;
     let lead = { state: "none", agent_id: null, turn: "unknown" };
     for (const a of agents) {
         if (a.kind === "lead") {
-            const live = reissued(a) ? false : liveness(a);
+            const live = liveness(a);
             lead = {
                 state: live === true ? "alive" : live === false ? "dead_pane" : "unknown",
                 agent_id: a.id,
@@ -102,7 +101,7 @@ function projectRow(project, now, snapshot) {
         }
         if (a.kind !== "agent")
             continue;
-        const live = reissued(a) ? false : liveness(a);
+        const live = liveness(a);
         if (live === false)
             workers.unreachable++;
         else if (live === null)

package/dist/projectRemove.js

@@ -1,5 +1,7 @@
 import { backupNow } from "./backup.js";
 import { dataDir, db } from "./db.js";
+import { LEAD_KIND } from "./spawn.js";
+import { foreignSocket, liveTargets, observationFailed, rowOwnership } from "./tmux.js";
 export const PROJECT_OWNER_TABLES = [
     "pads",
     "todos",
@@ -28,17 +30,49 @@ export function formatRowCounts(counts) {
         .map(([table, n]) => `${table}: ${n}`)
         .join(", ");
 }
-function assertNoRunningAgents(projectId, name) {
-    const running = db
-        .prepare("SELECT id, name FROM agents WHERE project_id = ? AND status = 'running' ORDER BY id")
-        .all(projectId);
+const runningRows = (projectId) => db
+    .prepare("SELECT id, name, kind, tmux_target, tmux_socket, pane_pid FROM agents WHERE project_id = ? AND status = 'running' ORDER BY id")
+    .all(projectId);
+const identities = (rows) => JSON.stringify(rows.map((r) => [r.id, r.tmux_target, r.tmux_socket, r.pane_pid]));
+function assertNoRunningAgents(projectId, name, running, panes) {
     if (running.length === 0)
         return;
-    const names = running.map((a) => `${a.name} (agent ${a.id})`).join(", ");
-    throw new Error(`project ${projectId} ("${name}") has running agents: ${names}. Nothing deleted. Run hive doctor to close rows whose panes are gone, or agent_close them.`);
+    const snapshot = panes === undefined ? liveTargets() : panes;
+    const blockers = running
+        .map((a) => ({ ...a, ownership: rowOwnership(a, snapshot) }))
+        .filter((a) => a.ownership === "live" || a.ownership === "unknown");
+    if (blockers.length === 0)
+        return;
+    const names = blockers
+        .map((a) => `${a.name} (agent ${a.id}, ${a.ownership === "live" ? "owns a live pane" : "pane identity unknown"})`)
+        .join(", ");
+    const hints = [];
+    const liveLeads = blockers.filter((a) => a.ownership === "live" && a.kind === LEAD_KIND);
+    const liveOthers = blockers.filter((a) => a.ownership === "live" && a.kind !== LEAD_KIND);
+    const unknown = blockers.filter((a) => a.ownership === "unknown");
+    if (liveLeads.length > 0)
+        hints.push("A live lead is stopped or restarted from its own terminal, never retired with row_only.");
+    if (liveOthers.length > 0)
+        hints.push("Stop a live worker or command with agent_close first.");
+    if (unknown.length > 0 && observationFailed(snapshot)) {
+        hints.push("tmux could not be probed, so no row's ownership could be checked. Retry in a few seconds.");
+    }
+    else if (unknown.length > 0) {
+        const foreign = unknown.some((a) => foreignSocket(a.tmux_socket));
+        hints.push("A row whose pane cannot be verified is retired explicitly by a human or peer lead through this project's MCP " +
+            `tool, ${unknown.map((a) => `agent_close({agent_id: ${a.id}, row_only: true})`).join(", ")}` +
+            (foreign
+                ? ", or run this again from the tmux socket a foreign-socket row was recorded on, where its ownership can be verified."
+                : "."));
+    }
+    throw new Error(`project ${projectId} ("${name}") has running agents: ${names}. Nothing deleted. ${hints.join(" ")}`);
 }
-const deleteProjectRows = db.transaction((projectId, name, expected, after) => {
-    assertNoRunningAgents(projectId, name);
+const deleteProjectRows = db.transaction((projectId, name, expected, observed, after) => {
+    const running = runningRows(projectId);
+    if (identities(running) !== observed.rows) {
+        throw new Error(`project ${projectId} ("${name}") changed while the snapshot was taken; nothing removed, run it again.`);
+    }
+    assertNoRunningAgents(projectId, name, running, observed.panes);
     if (JSON.stringify(projectRowCounts(projectId)) !== JSON.stringify(expected)) {
         throw new Error(`project ${projectId} ("${name}") changed while the snapshot was taken; nothing removed, run it again.`);
     }
@@ -52,7 +86,7 @@ export function removeProject(projectId, opts) {
     const target = db.prepare("SELECT id, name, path FROM projects WHERE id = ?").get(projectId);
     if (!target)
         throw new Error(`no project ${projectId}.`);
-    assertNoRunningAgents(projectId, target.name);
+    assertNoRunningAgents(projectId, target.name, runningRows(projectId));
     const counts = projectRowCounts(projectId);
     let snapshot = null;
     if (opts.snapshot) {
@@ -62,7 +96,9 @@ export function removeProject(projectId, opts) {
         snapshot = result.path ?? null;
     }
     opts.afterSnapshot?.();
+    const rows = runningRows(projectId);
+    const observed = { rows: identities(rows), panes: rows.length > 0 ? liveTargets() : null };
     const removed = { deleted: { id: target.id, name: target.name, path: target.path }, counts, snapshot };
-    deleteProjectRows.immediate(projectId, target.name, counts, () => opts.onRemoved?.(removed));
+    deleteProjectRows.immediate(projectId, target.name, counts, observed, () => opts.onRemoved?.(removed));
     return removed;
 }

package/dist/spawn.js

@@ -371,13 +371,18 @@ export function reapCodexHomeForClosedAgent(agentId, codexHome) {
     }
     db.prepare("UPDATE agents SET codex_home = '' WHERE id = ? AND codex_home = ?").run(agentId, codexHome);
 }
-export function closeAgentRow(agentId, expectedTmuxTarget) {
-    const info = expectedTmuxTarget === undefined
+export function closeAgentRow(agentId, expected) {
+    const info = expected === undefined
         ? db
             .prepare("UPDATE agents SET status = 'closed', closed_at = datetime('now') WHERE id = ? AND status = 'running'")
             .run(agentId)
-        : db
-            .prepare("UPDATE agents SET status = 'closed', closed_at = datetime('now') WHERE id = ? AND status = 'running' AND tmux_target = ?")
-            .run(agentId, expectedTmuxTarget);
+        : typeof expected === "string"
+            ? db
+                .prepare("UPDATE agents SET status = 'closed', closed_at = datetime('now') WHERE id = ? AND status = 'running' AND tmux_target = ?")
+                .run(agentId, expected)
+            : db
+                .prepare("UPDATE agents SET status = 'closed', closed_at = datetime('now') WHERE id = ? AND status = 'running' " +
+                "AND tmux_target = ? AND tmux_socket = ? AND pane_pid = ?")
+                .run(agentId, expected.tmux_target, expected.tmux_socket, expected.pane_pid);
     return info.changes > 0;
 }

package/dist/tmux.js

@@ -470,6 +470,31 @@ 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";
+}
+export function ownershipLiveness(ownership) {
+    return ownership === "live" ? true : ownership === "unknown" ? null : false;
+}
 export const RAW_ATTACH_TMUX_CONFIG = [
     "set -g allow-passthrough all",
 ];

package/dist/tools/agents.js

@@ -16,7 +16,7 @@ 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 { 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, foreignSocket, holdsHumanInput, liveTargets, observationFailed, ownershipLiveness, paneCurrentCommand, paneInCopyMode, paneWindow, pollPaneReadiness, rowLive, 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,12 +129,60 @@ function buildParkReceipt(project, agent, parkedAt, branch, note) {
         ...(note ? { note } : {}),
     };
 }
+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 observes = !foreignSocket(agent.tmux_socket) && agent.tmux_target !== "";
+    const snapshot = observes ? liveTargets() : null;
+    if (observes && observationFailed(snapshot))
+        throw probeFailed(agent);
+    const ownership = rowOwnership(agent, snapshot);
+    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, { tmux_target: agent.tmux_target, tmux_socket: agent.tmux_socket, pane_pid: agent.pane_pid })) {
+        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 function isLive(agent) {
     if (agent.status !== "running")
         return false;
     return rowLive(agent.tmux_socket, agent.tmux_target);
 }
 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}`);
 function requireLive(agent) {
     if (agent.status !== "running") {
@@ -250,11 +298,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 {
@@ -1031,11 +1075,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,
@@ -1285,7 +1330,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 +1342,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 +1360,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 +1378,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 " +

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cmgmyr/hive",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Run a crew of Claude Code and Codex workers from one lead session: visible tmux panes, exact state from hooks, one local SQLite store.",
   "type": "module",
   "bin": {