@cmgmyr/hive 1.11.9 → 1.12.0

package/dist/tools/agents.js

@@ -7,23 +7,28 @@ export { CLOSED_ROW_ORDER, findAgent, getAgentRow, notOwnedError, observeOwnersh
 import { confirmQueenWrite } from "../queenAudit.js";
 import { captureQueenWriteIdentity, resolveQueenLeadTarget } from "../context.js";
 import { agentBriefPath, mergedBriefVars, readAgentBrief, workerBrief, workerCommandString, writeAgentBrief, } from "../brief.js";
-import { codexHomeDir, codexInstructionsPhrase, codexLaunchArgs, ensureCodexHome, ensureCodexHooksFile, refreshCodexMcpEnv } from "../codexHome.js";
+import { codexHomeDir, codexInstructionsPhrase, ensureCodexHome, ensureCodexHooksFile, findCodexFork, readCodexForkSeed, seedCodexFork } from "../codexHome.js";
 import { currentActor, findProjectForDir, getProject, linkedWorktreePrimaryRoot, resolveProject } from "../context.js";
 import { commandHead, harnessFor, harnessNames, readOnlyExtraArgsAllowed, paneClassifierFor, resolvedCommandPrefix, screenClassifiable, } from "../harnesses.js";
 import { ensureWorkerHooksFile } from "../hooks.js";
 import { activeProfile, allowedAgents, loadProjectYml } from "../projectYml.js";
 import { classifyMiss, DELIVERY_FIELDS, LEAD_MESSAGE_THRESHOLD, leadPointerMarker, missMessage, readLeadMessage, renderLeadPointer, senderTag, shortenedSendFailureClause, shortenedSendNote, storeLeadMessage, } from "../leadMessage.js";
-import { sendQuietLeadMessage } from "../leadMessageDelivery.js";
+import { sendQuietLeadMessage, sendUsageHeldMessage } from "../leadMessageDelivery.js";
+import { observeUsageLimit, usageLimitGate } from "../usageLimit.js";
 import { run } from "../result.js";
 import { markGoneReported } from "../scheduler.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 { agentIdentityEnv, branchAt, closeAgentRow, currentOwnership, discardOrphanedPane, isReservedAgentName, isRunningLeadActor, killAgentPane, launchAgent, LEAD_KIND, PaneOwnershipLost, paneIdentity, parkAgentRow, reapCodexHomeForClosedAgent, requireStillOwned, releaseParkRow, renameAgent, storedLaunchOptions, } from "../spawn.js";
 import { COMMAND_KIND, runningCommandRow, stopLine, stopProcess, STOP_REASONS } from "../processes.js";
+import { markWorkerRetirementIntent } from "../workerRecovery.js";
+import { contextCheckpointEnv, refuseLimitedHarness, resumeWorker } from "../agentResume.js";
 import { readContextTokens, readContextFill, resolveTranscriptDir } from "../transcript.js";
 import { leadSessionEnded } from "../leadState.js";
 import { capturePane, captureFinalScreen, DEFAULT_LAYOUT, cancelCopyMode, describePaneChoice, ensureAttached, findUnsafeControlChar, holdsHumanInput, liveTargets, observationFailed, ownershipLiveness, paneCurrentCommand, paneInCopyMode, 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 unknownOwnershipNote = (snapshot) => observationFailed(snapshot) ? PROBE_FAILED_NOTE : UNVERIFIED_OWNERSHIP_NOTE;
+class UsageLimitActive extends Error {
+}
 export function classifyLostCas(row) {
     return row.status !== "running" ? { outcome: "retired", parked: !!row.parked_at } : { outcome: "revived" };
 }
@@ -93,6 +98,24 @@ function closeRowOnly(agent, 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") {
+        if (agent.kind === "agent" && agent.recovery_state === "pending") {
+            if (!markWorkerRetirementIntent(agent.id, paneIdentity(agent))) {
+                throw new Error(`Agent ${agent.id} changed before its recovery was abandoned. Nothing was changed.`);
+            }
+            let releasedHome = null;
+            if (agent.codex_home) {
+                try {
+                    releasedHome = reapCodexHomeForClosedAgent(agent.id, agent.codex_home);
+                }
+                catch {
+                }
+            }
+            return {
+                ...receipt,
+                ...(agent.parked_at ? { parked: true } : {}),
+                note: pendingRecoveryAbandonmentNote(agent.id, agent.codex_home, releasedHome),
+            };
+        }
         return {
             ...receipt,
             ...(agent.parked_at ? { parked: true } : {}),
@@ -107,6 +130,9 @@ function closeRowOnly(agent, confirmSelf) {
                 ? "Restart or end the lead from its own terminal."
                 : "Use agent_close without row_only to stop it."));
     }
+    if (agent.kind === "agent" && !markWorkerRetirementIntent(agent.id, paneIdentity(agent))) {
+        throw new Error(`Agent ${agent.id} changed before row-only retirement. Nothing was changed.`);
+    }
     if (!closeAgentRow(agent.id, paneIdentity(agent))) {
         const after = getAgentRow(agent.project_id, agent.id, "Call agent_list(include_closed: true).");
         if (after.status !== "running") {
@@ -125,6 +151,22 @@ function closeRowOnly(agent, confirmSelf) {
             (ownership === "unknown" ? " Anything still running in that pane was left alone." : ""),
     };
 }
+function pendingRecoveryAbandonmentNote(agentId, codexHome, releasedHome) {
+    const row = db.prepare("SELECT status, recovery_state FROM agents WHERE id = ?").get(agentId);
+    if (row?.status === "running")
+        return "A concurrent resume now owns the row; no Codex home was released.";
+    const stateNote = row?.recovery_state === "excluded"
+        ? "The recovery marker changed to excluded"
+        : "The recovery marker could not be changed to excluded";
+    const homeNote = !codexHome
+        ? "no Codex home was associated with this row and none was released"
+        : releasedHome === true
+            ? "the Codex home directory existed and was released"
+            : releasedHome === false
+                ? "no Codex home directory existed to release"
+                : "the Codex home was not released because the row changed";
+    return `${stateNote}; ${homeNote}.`;
+}
 // 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));
@@ -217,6 +259,65 @@ function stripSessionArgs(args) {
     }
     return stripped;
 }
+function effortForAgent(agent, harness) {
+    const args = storedLaunchOptions(agent.extra_args).args;
+    if (harness === "claude") {
+        for (let i = args.length - 1; i >= 0; i--) {
+            if (args[i].startsWith("--effort="))
+                return args[i].slice("--effort=".length);
+            if (args[i] === "--effort" && i + 1 < args.length)
+                return args[i + 1];
+        }
+        return undefined;
+    }
+    for (let i = args.length - 1; i >= 0; i--) {
+        const value = args[i] === "-c" ? args[i + 1] : args[i].startsWith("-c") ? args[i].slice(2) : args[i];
+        const match = /^model_reasoning_effort=(low|medium|high|xhigh)$/.exec(value ?? "");
+        if (match)
+            return match[1];
+    }
+    return undefined;
+}
+function effortArgs(harness, effort) {
+    if (!effort)
+        return [];
+    const allowed = harness === "claude" ? ["low", "medium", "high", "xhigh", "max"] : ["low", "medium", "high", "xhigh"];
+    if (!allowed.includes(effort))
+        throw new Error(`effort "${effort}" is not supported by ${harness}.`);
+    return harness === "claude" ? ["--effort", effort] : ["-c", `model_reasoning_effort=${effort}`];
+}
+async function waitForCodexFork(childKey, sourceSessionId, deadline) {
+    while (Date.now() < deadline) {
+        const found = findCodexFork(childKey, sourceSessionId);
+        if (found)
+            return found;
+        await sleep(Math.min(250, Math.max(1, deadline - Date.now())));
+    }
+    return findCodexFork(childKey, sourceSessionId);
+}
+function retireForkChild(projectId, childId) {
+    const child = getAgentRow(projectId, childId, "Check agent_list(include_closed: true).");
+    if (child.status !== "running")
+        return;
+    const ownership = observeOwnership(child);
+    if (ownership === "unknown") {
+        throw new Error(`Fork child agent_id ${child.id} is retained because its pane ownership is unknown.`);
+    }
+    const live = ownership === "live" && stillOwnsPane(child, "agent_fork cleanup");
+    if (live)
+        killAgentPane(child.tmux_target);
+    if (!closeAgentRow(child.id, paneIdentity(child))) {
+        const after = getAgentRow(projectId, child.id, "Check agent_list(include_closed: true).");
+        if (after.status !== "closed") {
+            throw new Error(`Fork child agent_id ${child.id} changed during cleanup and is retained for recovery.`);
+        }
+    }
+    if (child.codex_home) {
+        const closed = getAgentRow(projectId, child.id, "Check agent_list(include_closed: true).");
+        if (closed.codex_home)
+            reapCodexHomeForClosedAgent(child.id, closed.codex_home);
+    }
+}
 function requestsExistingSession(extraArgs) {
     return (extraArgs ?? []).some((arg) => arg === "--resume" ||
         arg.startsWith("--resume=") ||
@@ -305,14 +406,13 @@ function agentSummary(row, snapshot) {
         cwd: row.cwd,
         parent_actor_id: row.parent_actor_id,
         todo_id: row.todo_id,
+        ...(row.forked_from_agent_id != null
+            ? { forked_from_agent_id: row.forked_from_agent_id, forked_from_session_id: row.forked_from_session_id }
+            : {}),
         created_at: row.created_at,
         ...(dormant ? { dormant_since: dormant.ended_at } : {}),
     };
 }
-export function contextCheckpointEnv(config) {
-    const value = config?.context_checkpoint_percent;
-    return value == null ? {} : { HIVE_CONTEXT_CHECKPOINT_PERCENT: String(value) };
-}
 export function worktreeInstallNotice(cwd, projectPath, config) {
     const install = config?.vars?.install?.trim();
     if (!install)
@@ -324,7 +424,7 @@ export function worktreeInstallNotice(cwd, projectPath, config) {
 }
 export function registerAgents(server) {
     server.registerTool("agent_spawn", {
-        description: "Spawn a worker agent (default: claude, or the project's hive.yml agents: default). A claude worker is briefed automatically: the full brief is appended to its system prompt, so send it its assignment directly. A command or harness that resolves to a known harness (claude, codex) not listed in the project's hive.yml agents: is refused; absent agents: means claude only. A command hive cannot classify the screen of (claude and codex both do; a harness with no entry does not) can be spawned but NOT typed into: the receipt carries brief_path and says so, and agent_send's text path and wakes both refuse that pane. Set read_only: true to block local file writes and mutating shell while keeping Hive MCP available; agent_resume preserves this mode and agent_status reports it. Only bare claude/codex executables are supported in this mode, with only effort-setting extra_args. The worker is locked to this project. Humans can watch with: tmux attach -t hive-main.",
+        description: "Spawn a worker agent (default: claude, or the project's hive.yml agents: default). A claude worker is briefed automatically: the full brief is appended to its system prompt, so send it its assignment directly. A command or harness that resolves to a known harness (claude, codex) not listed in the project's hive.yml agents: is refused; absent agents: means claude only. A command hive cannot classify the screen of (claude and codex both do; a harness with no entry does not) can be spawned but NOT typed into: the receipt carries brief_path and says so, and agent_send's text path and wakes both refuse that pane. A same-project worker or lead on that harness's active usage limit makes this spawn retryable until its reset or bounded deadline; hive does not queue spawns. Set read_only: true to block local file writes and mutating shell while keeping Hive MCP available; agent_resume preserves this mode and agent_status reports it. Only bare claude/codex executables are supported in this mode, with only effort-setting extra_args. The worker is locked to this project. Humans can watch with: tmux attach -t hive-main.",
         annotations: {
             readOnlyHint: false,
             destructiveHint: false,
@@ -357,7 +457,7 @@ export function registerAgents(server) {
             placement: z
                 .enum(["split", "window"])
                 .optional()
-                .describe("split (default): the worker appears as a pane in the lead's window, auto-tiled, so the whole crew shares one screen. window: its own tmux window (an iTerm tab under control mode)."),
+                .describe("Omit this to use the project's hive.yml placement, else HIVE_SPAWN_PLACEMENT, else split. split: the worker appears as a pane in the lead's window, auto-tiled, so the whole crew shares one screen. window: its own tmux window (an iTerm tab under control mode). agent_output reads scrollback, so a crowded window does not limit what a lead can read. If workers end up in other windows, run hive layout to gather them."),
             layout: z
                 .enum(WINDOW_LAYOUTS)
                 .optional()
@@ -442,6 +542,8 @@ export function registerAgents(server) {
             throw new Error(`[agent_spawn:harness-not-allowed] "${harness.name}" is not in this project's hive.yml ` +
                 `agents: list (${allowed.join(", ")}). Add it to agents: to allow spawning it.`);
         }
+        if (harnessNames().includes(harness.name))
+            refuseLimitedHarness(project.id, harness.name);
         if (args.read_only && (!["claude", "codex"].includes(harness.name) ||
             !/^[A-Za-z0-9_./-]+$/.test(baseCommand) ||
             !readOnlyExtraArgsAllowed(harness.name, args.extra_args))) {
@@ -488,9 +590,11 @@ export function registerAgents(server) {
                 briefPath,
             });
         };
-        const placement = args.placement ??
-            projectConfig?.placement ??
-            (process.env.HIVE_SPAWN_PLACEMENT === "window" ? "window" : "split");
+        const configuredPlacement = projectConfig?.placement ?? (process.env.HIVE_SPAWN_PLACEMENT === "window" ? "window" : "split");
+        const placement = args.placement ?? configuredPlacement;
+        const placementNote = args.placement === "window" && configuredPlacement === "split"
+            ? 'This worker got its own window because per-call placement "window" overrides this project\'s split config; run `hive layout` to gather it.'
+            : undefined;
         const layout = args.layout ?? projectConfig?.layout ?? DEFAULT_LAYOUT;
         let spawned;
         try {
@@ -617,10 +721,270 @@ export function registerAgents(server) {
             const existingNote = typeof receipt.note === "string" ? receipt.note : "";
             receipt.note = existingNote ? `${existingNote} ${omittedTodoWarning}` : omittedTodoWarning;
         }
+        if (placementNote) {
+            const existingNote = typeof receipt.note === "string" ? receipt.note : "";
+            receipt.note = existingNote ? `${existingNote} ${placementNote}` : placementNote;
+        }
         return receipt;
     }));
+    server.registerTool("agent_fork", {
+        description: "Fork a same-project Claude Code or Codex worker into a new worker with a new identity and pane. The child starts from a copy of the source conversation, gets a fresh brief, and does not inherit the source todo. Claude Code process-scoped permission grants are not copied and may need approval again.",
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        inputSchema: {
+            agent_id: idParam.describe("Numeric id of the same-project worker to fork."),
+            name: z.string().describe("Required name for the new child worker."),
+            cwd: z.string().optional().describe("Child working directory; defaults to the source worker's directory."),
+            model: z.string().min(1).optional().describe("Model override; defaults to the source worker's model."),
+            effort: z.enum(["low", "medium", "high", "xhigh", "max"]).optional().describe("Reasoning effort override; defaults to the source worker's effort."),
+            read_only: z.boolean().optional().describe("Read-only mode override; defaults to the source worker's mode."),
+            todo_id: idParam.optional().describe("Explicit todo for this new child; absent means no todo link."),
+            placement: z.enum(["split", "window"]).optional(),
+            layout: z.enum(WINDOW_LAYOUTS).optional(),
+            project_id: projectIdParam,
+        },
+        outputSchema: {
+            agent_id: idParam,
+            actor_id: z.string(),
+            name: z.string(),
+            tmux_target: z.string(),
+            forked_from_agent_id: idParam,
+            forked_from_session_id: z.string(),
+            session_id: z.string(),
+            ready: z.boolean(),
+            permission_note: z.string(),
+            note: z.string().optional(),
+            tail: z.string().optional(),
+        },
+    }, (args) => run(async () => {
+        const callerProject = resolveProject();
+        const project = args.project_id === undefined ? callerProject : resolveProject(args.project_id);
+        if (project.id !== callerProject.id)
+            throw new Error("agent_fork is same-project only; source and child must belong to this session's project.");
+        const source = getAgentRow(project.id, args.agent_id, "Call agent_list(include_closed: true). agent_fork is same-project only.");
+        if (source.kind !== "agent")
+            throw new Error("agent_fork only accepts a worker, not a lead or command row.");
+        if (source.status !== "running" && source.status !== "closed") {
+            throw new Error(`Agent ${source.id} cannot be forked from status ${source.status}.`);
+        }
+        const harness = harnessFor(source.command);
+        refuseLimitedHarness(project.id, harness.name, "agent_fork");
+        if (!["claude", "codex"].includes(harness.name)) {
+            throw new Error(`Agent ${source.id} uses unsupported fork harness "${harness.name}".`);
+        }
+        if (harness.name === "codex" && source.status === "closed" && !source.parked_at) {
+            throw new Error(`Closed Codex agent ${source.id} is not parked; its fork home may have been reaped.`);
+        }
+        if (harness.name === "codex" && !source.codex_home) {
+            throw new Error(`Codex agent ${source.id} has no recorded CODEX_HOME; it cannot be forked.`);
+        }
+        if (!source.session_id)
+            throw new Error(`Agent ${source.id} has no recorded session id and cannot be forked.`);
+        if (!source.cwd || !existsSync(source.cwd) || !statSync(source.cwd).isDirectory()) {
+            throw new Error(`Agent ${source.id} has no readable working directory and cannot be forked.`);
+        }
+        if (!source.transcript_path || !existsSync(source.transcript_path) || !statSync(source.transcript_path).isFile()) {
+            throw new Error(`Agent ${source.id} has no readable transcript and cannot be forked.`);
+        }
+        const codexSeed = harness.name === "codex" ? readCodexForkSeed(source) : undefined;
+        const name = normalizeAgentName(args.name, "name");
+        requireNameFree(project.id, name);
+        let cwd = source.cwd;
+        if (args.cwd !== undefined) {
+            cwd = realpathSync(args.cwd);
+            if (!statSync(cwd).isDirectory())
+                throw new Error(`cwd is not a directory: ${args.cwd}`);
+            const cwdProject = findProjectForDir(cwd);
+            if (cwdProject && cwdProject.id !== project.id) {
+                throw new Error(`cwd ${cwd} belongs to project "${cwdProject.name}" (id ${cwdProject.id}), not source project "${project.name}" (id ${project.id}).`);
+            }
+        }
+        if (args.todo_id !== undefined) {
+            const linked = db.prepare("SELECT archived_at FROM todos WHERE id = ? AND project_id = ?").get(args.todo_id, project.id);
+            if (!linked)
+                throw new Error(`todo_id ${args.todo_id} is not a todo in project "${project.name}" (id ${project.id}).`);
+            if (linked.archived_at != null)
+                throw new Error(`todo_id ${args.todo_id} is archived; unarchive it or link another todo.`);
+        }
+        const model = args.model ?? source.model ?? extractCommandFlag(source.command, "--model");
+        const launchOptions = storedLaunchOptions(source.extra_args);
+        const readOnly = args.read_only ?? launchOptions.readOnly;
+        const effort = args.effort ?? effortForAgent(source, harness.name);
+        const forkEffort = effortArgs(harness.name, effort);
+        const projectConfig = loadProjectYml(project.path).config;
+        const placement = args.placement ?? projectConfig?.placement ?? (process.env.HIVE_SPAWN_PLACEMENT === "window" ? "window" : "split");
+        const layout = args.layout ?? projectConfig?.layout ?? DEFAULT_LAYOUT;
+        const childSessionId = harness.name === "claude" ? randomUUID() : "";
+        const codexHomeKey = harness.name === "codex" ? randomUUID() : undefined;
+        const deadline = Date.now() + PANE_READY_MS;
+        let instructionLayers = [];
+        const buildCommand = ({ agentId, actorId }) => {
+            const brief = workerBrief({
+                name,
+                actorId,
+                projectName: project.name,
+                projectPath: project.path,
+                cwd,
+                profile: activeProfile(projectConfig),
+                vars: mergedBriefVars(projectConfig?.vars, harness.name),
+            });
+            if (harness.name === "codex" && codexHomeKey) {
+                const home = ensureCodexHome({
+                    key: codexHomeKey,
+                    actorId,
+                    serverEnv: agentIdentityEnv(actorId, name, project.path),
+                    cwd,
+                    brief,
+                    readOnly,
+                    includePostToolUse: projectConfig?.context_checkpoint_percent != null,
+                });
+                instructionLayers = home.instructionLayers;
+                ensureCodexHooksFile(codexHomeKey, { includePostToolUse: projectConfig?.context_checkpoint_percent != null });
+                seedCodexFork(source, codexHomeKey, codexSeed);
+                if (findCodexFork(codexHomeKey, source.session_id)) {
+                    throw new Error("Fresh Codex fork home already contains a child rollout before launch.");
+                }
+                return workerCommandString({
+                    command: resolvedCommandPrefix(source.command) || "codex",
+                    model,
+                    displayName: name,
+                    extraArgs: [...home.extraArgs, "-C", cwd, ...forkEffort, "fork", source.session_id],
+                });
+            }
+            const briefPath = writeAgentBrief(agentId, brief);
+            const settingsPath = ensureWorkerHooksFile(agentId, { readOnly, includePostToolUse: projectConfig?.context_checkpoint_percent != null });
+            return workerCommandString({
+                command: resolvedCommandPrefix(source.command) || "claude",
+                model,
+                displayName: name,
+                settingsPath,
+                briefPath,
+                extraArgs: [...forkEffort, "--session-id", childSessionId, "--resume", source.session_id, "--fork-session"],
+            });
+        };
+        let spawned;
+        try {
+            spawned = launchAgent({
+                projectId: project.id,
+                projectName: project.name,
+                projectPath: project.path,
+                name,
+                kind: "agent",
+                commandString: buildCommand,
+                cwd,
+                env: { ...contextCheckpointEnv(projectConfig), ...(codexHomeKey ? { CODEX_HOME: codexHomeDir(codexHomeKey) } : {}) },
+                placement,
+                layout,
+                parentActor: currentActor(),
+                sessionId: childSessionId,
+                codexHome: codexHomeKey,
+                model,
+                extraArgs: forkEffort,
+                readOnly,
+                todoId: args.todo_id,
+                forkedFromAgentId: source.id,
+                forkedFromSessionId: source.session_id,
+                retainOnExit: true,
+            });
+        }
+        catch (error) {
+            if (codexHomeKey)
+                rmSync(codexHomeDir(codexHomeKey), { recursive: true, force: true });
+            throw error;
+        }
+        const classifier = paneClassifierFor(source.command);
+        const readiness = await pollPaneReadiness(spawned.target, Math.max(0, deadline - Date.now()), classifier.hasInputBox);
+        if (harness.name === "codex") {
+            let found;
+            try {
+                found = await waitForCodexFork(codexHomeKey, source.session_id, deadline);
+            }
+            catch (error) {
+                try {
+                    retireForkChild(project.id, spawned.agentId);
+                }
+                catch (cleanupError) {
+                    throw new Error(`Codex fork discovery failed (${String(error)}); child agent_id ${spawned.agentId} needs recovery (${String(cleanupError)}).`);
+                }
+                throw error;
+            }
+            if (!found) {
+                try {
+                    retireForkChild(project.id, spawned.agentId);
+                }
+                catch (cleanupError) {
+                    throw new Error(`Codex fork session was not identified within ${PANE_READY_MS}ms; child agent_id ${spawned.agentId} needs recovery (${String(cleanupError)}).`);
+                }
+                throw new Error(`Codex fork session was not identified within ${PANE_READY_MS}ms; child agent_id ${spawned.agentId} was retired.`);
+            }
+            if (readiness === "gone") {
+                retireForkChild(project.id, spawned.agentId);
+                throw new Error(`Codex fork child agent_id ${spawned.agentId} exited before it became ready.`);
+            }
+            const child = getAgentRow(project.id, spawned.agentId, "Call agent_list(include_closed: true).");
+            if (!stillOwnsPane(child, "agent_fork session discovery")) {
+                retireForkChild(project.id, spawned.agentId);
+                throw new Error(`Codex fork child agent_id ${spawned.agentId} no longer owns its pane.`);
+            }
+            const bound = db.prepare("UPDATE agents SET session_id = ?, transcript_path = ? WHERE id = ? AND status = 'running' AND tmux_target = ? AND tmux_socket = ? AND pane_pid = ? AND session_id = '' AND forked_from_session_id = ?").run(found.sessionId, found.transcriptPath, child.id, child.tmux_target, child.tmux_socket, child.pane_pid, source.session_id);
+            if (bound.changes !== 1) {
+                retireForkChild(project.id, spawned.agentId);
+                throw new Error(`Codex fork identity could not be bound to child agent_id ${spawned.agentId}; the child was retired.`);
+            }
+            const choice = readiness === "ready" ? classifier.choiceCheck(spawned.target) : { awaitingChoice: null, tail: "" };
+            return {
+                agent_id: spawned.agentId,
+                actor_id: spawned.actorId,
+                name,
+                tmux_target: spawned.target,
+                forked_from_agent_id: source.id,
+                forked_from_session_id: source.session_id,
+                session_id: found.sessionId,
+                ready: readiness === "ready" && choice.awaitingChoice !== true,
+                permission_note: "Claude Code process-scoped permission grants are not copied to a fork; approve them again in the child if prompted.",
+                ...(readiness !== "ready" || choice.awaitingChoice === true ? {
+                    note: readiness === "timeout" ? "The child session was found, but its pane did not reach a classifiable input box before the readiness deadline." : "The child session was found, but the pane is waiting on a choice. Clear it before sending an assignment.",
+                    tail: choice.tail || capturePaneQuietly(spawned.target),
+                } : {}),
+            };
+        }
+        let tail;
+        let exited = false;
+        let dialog = false;
+        if (readiness === "gone") {
+            exited = true;
+            tail = captureFinalScreen(spawned.target, 30);
+            db.prepare("UPDATE agents SET exit_tail = ? WHERE id = ?").run(tail, spawned.agentId);
+            discardOrphanedPane(spawned.target);
+        }
+        else if (readiness === "ready") {
+            const choice = classifier.choiceCheck(spawned.target);
+            dialog = choice.awaitingChoice === true;
+            if (dialog)
+                tail = choice.tail;
+        }
+        else {
+            tail = capturePaneQuietly(spawned.target);
+        }
+        return {
+            agent_id: spawned.agentId,
+            actor_id: spawned.actorId,
+            name,
+            tmux_target: spawned.target,
+            forked_from_agent_id: source.id,
+            forked_from_session_id: source.session_id,
+            session_id: childSessionId,
+            ready: readiness === "ready" && !dialog,
+            permission_note: "Claude Code process-scoped permission grants are not copied to a fork; approve them again in the child if prompted.",
+            ...(exited ? { note: "The forked session was created, but its pane exited before becoming ready.", tail } : dialog ? { note: "The forked session is waiting on a choice. Clear it before sending an assignment.", tail } : readiness === "timeout" ? { note: "The forked session was created, but its pane did not reach a classifiable input box before the readiness deadline.", tail } : {}),
+        };
+    }));
     server.registerTool("agent_resume", {
-        description: "Resume a CLOSED claude or codex worker from its recorded session id (claude --resume / codex resume): a fresh pane, the same actor_id, and the worker's full prior context. Addressed by name or agent_id among closed agents (agent_list(include_closed: true)). Send it its next instruction with agent_send once resumed - this tool does not.",
+        description: "Resume a CLOSED claude or codex worker from its recorded session id (claude --resume / codex resume): a fresh pane, the same actor_id, and the worker's full prior context. A same-project worker or lead on that harness's active usage limit makes this resume retryable until its reset or bounded deadline; hive does not queue resumes. Addressed by name or agent_id among closed agents (agent_list(include_closed: true)). Send it its next instruction with agent_send once resumed - this tool does not.",
         annotations: {
             readOnlyHint: false,
             destructiveHint: false,
@@ -647,120 +1011,9 @@ export function registerAgents(server) {
     }, (args) => run(async () => {
         const project = resolveProject(args.project_id);
         const agent = findClosedAgent(project.id, args);
-        if (agent.kind === LEAD_KIND) {
-            throw new Error(`Agent ${agent.id} ("${agent.name}") is this project's lead session. agent_resume is for workers; ` +
-                "start a lead session with `hive lead`.");
-        }
-        const resumeHarness = harnessFor(agent.command);
-        if (!resumeHarness.supportsResume) {
-            throw new Error(`Agent ${agent.id} ("${agent.name}")'s harness ("${resumeHarness.name}", command: "${agent.command}") ` +
-                "does not support resume, so it has no session id to resume from.");
-        }
-        if (!agent.session_id) {
-            throw new Error(`Agent ${agent.id} ("${agent.name}") has no recorded session id, so it cannot be resumed. It may ` +
-                "predate this feature, or it may have closed before its first hook event ever fired. Spawn a new " +
-                "worker instead.");
-        }
-        if (resumeHarness.name === "codex" && !agent.codex_home) {
-            throw new Error(`Agent ${agent.id} ("${agent.name}") has no recorded CODEX_HOME, so its session cannot be resumed. ` +
-                (agent.parked_at
-                    ? "This should not happen for a parked codex worker - its home is only reaped on agent_close. " +
-                        "Check agent_status for how it actually got here."
-                    : "It was closed with agent_close, which reaps a codex worker's home (rollout files included) " +
-                        "immediately - only a PARKED codex worker keeps its home. Nothing here to resume; spawn a new " +
-                        "worker instead."));
-        }
-        if (!existsSync(agent.cwd)) {
-            const recreate = agent.parked_branch
-                ? `git worktree add ${agent.cwd} ${agent.parked_branch}`
-                : `recreate a checkout at ${agent.cwd} (no branch was recorded for it - agent_park records one)`;
-            const reason = resumeHarness.name === "codex"
-                ? "It resumes into that directory as its working directory"
-                : "Its transcript is resolved from that path";
-            throw new Error(`Agent ${agent.id} ("${agent.name}")'s working directory is gone: ${agent.cwd}. ${reason}, so ` +
-                `recreate it and the resume works unchanged: ${recreate}`);
-        }
-        const branchNow = agent.parked_branch ? branchAt(agent.cwd) : "";
-        const branchDrift = branchNow && branchNow !== agent.parked_branch
-            ? { parked_branch: agent.parked_branch, branch_now: branchNow }
-            : null;
-        const collision = runningAgentNamed(project.id, agent.name);
-        if (collision) {
-            throw new Error(`Cannot resume agent ${agent.id} ("${agent.name}") under its recorded name: a running agent ` +
-                `(agent ${collision.id}) already has it. agent_resume does not rename on your behalf - the ` +
-                `${agent.parked_at ? "parked" : "closed"} lane is not lost, it just cannot come back under a name ` +
-                "someone else is using. Free the name first (agent_rename or agent_close on the running one), " +
-                `then retry agent_resume(agent_id: ${agent.id}).`);
-        }
-        const { config: projectConfig } = loadProjectYml(project.path);
-        const placement = projectConfig?.placement ?? (process.env.HIVE_SPAWN_PLACEMENT === "window" ? "window" : "split");
-        const layout = projectConfig?.layout ?? DEFAULT_LAYOUT;
-        const launchOptions = storedLaunchOptions(agent.extra_args);
-        let commandString;
-        let resumeEnv = contextCheckpointEnv(projectConfig);
-        if (resumeHarness.name === "codex") {
-            commandString = workerCommandString({
-                command: resolvedCommandPrefix(agent.command) || "codex",
-                // Recovered from the row's own recorded command: every codex worker hive spawns
-                // carries a pinned model (codex has no bare alias), so dropping this would silently
-                // resume on codex's default model instead of the one the lane actually chose.
-                model: agent.model ?? extractCommandFlag(agent.command, "--model"),
-                displayName: agent.name,
-                // Subcommand positional, not a flag - live-verified on v0.149.0 (`codex resume --help`:
-                // "Usage: codex resume [OPTIONS] [SESSION_ID] [PROMPT]"). No --settings/hooks file: a
-                // codex worker's hooks come from its own home's hooks.json, never claude's shared one.
-                extraArgs: [
-                    ...codexLaunchArgs(agent.cwd, launchOptions.readOnly),
-                    ...stripSessionArgs(launchOptions.args),
-                    "resume",
-                    agent.session_id,
-                ],
-            });
-            resumeEnv = { ...resumeEnv, CODEX_HOME: codexHomeDir(agent.codex_home) };
-            ensureCodexHooksFile(agent.codex_home, { includePostToolUse: projectConfig?.context_checkpoint_percent != null });
-            refreshCodexMcpEnv(agent.codex_home, agentIdentityEnv(agent.actor_id, agent.name, project.path));
-        }
-        else {
-            const claudeBinary = resolvedCommandPrefix(agent.command) || "claude";
-            commandString = workerCommandString({
-                command: claudeBinary,
-                displayName: agent.name,
-                model: agent.model ?? undefined,
-                extraArgs: [
-                    ...stripSessionArgs(launchOptions.args),
-                    "--resume",
-                    agent.session_id,
-                ],
-                settingsPath: ensureWorkerHooksFile(agent.id, { readOnly: launchOptions.readOnly, includePostToolUse: projectConfig?.context_checkpoint_percent != null }),
-            });
-        }
-        const { target, landedInProjectId } = resumeAgent({
-            agentId: agent.id,
-            actorId: agent.actor_id,
-            name: agent.name,
-            projectId: project.id,
-            projectName: project.name,
-            projectPath: project.path,
-            cwd: agent.cwd,
-            commandString,
-            env: resumeEnv,
-            placement,
-            layout,
-            parentActor: currentActor(),
-        });
+        const receipt = await resumeWorker(project.id, agent.id, { parentActor: currentActor() });
         ensureAttached(sessionName());
-        return {
-            agent_id: agent.id,
-            actor_id: agent.actor_id,
-            name: agent.name,
-            tmux_target: target,
-            resumed_session_id: agent.session_id,
-            ...(agent.parked_at ? { was_parked_at: agent.parked_at } : {}),
-            ...(branchDrift ? { branch_drift: branchDrift } : {}),
-            ...(landedInProjectId != null
-                ? { landed_in_project: getProject(landedInProjectId)?.name ?? `project ${landedInProjectId}` }
-                : {}),
-        };
+        return receipt;
     }));
     server.registerTool("agent_park", {
         description: "Park a claude or codex worker for the night: kill its pane, mark the row PARKED rather than plain closed, record the branch, and hand back a board line plus the one call that brings it back. Use this instead of agent_close when the lane is paused, not finished - `closed` alone cannot tell a next-morning lead which is which. Resume it with agent_resume.",
@@ -825,6 +1078,9 @@ export function registerAgents(server) {
         const branch = branchAt(agent.cwd);
         if (live)
             live = stillOwnsPane(agent, "agent_park");
+        if (agent.kind === "agent" && !markWorkerRetirementIntent(agent.id, paneIdentity(agent))) {
+            throw new Error(`Agent ${agent.id} changed before its park intent was recorded. Nothing was changed.`);
+        }
         if (live)
             killAgentPane(agent.tmux_target);
         const parkedAt = parkAgentRow(agent.id, paneIdentity(agent), branch);
@@ -891,11 +1147,18 @@ export function registerAgents(server) {
             throw notOwnedError(agent, ownership);
         const live = ownership === "live";
         const identity = paneIdentity(agent);
+        const renameHarness = harnessFor(agent.command);
+        if (live && renameHarness.supportsRename) {
+            observeUsageLimit(agent.id, Date.now());
+            const limit = usageLimitGate(agent.id, Date.now());
+            if (limit.held) {
+                throw new Error(`agent_rename is retryable after the target usage limit at ${limit.until}; the row and pane were not renamed.`);
+            }
+        }
         renameAgent(agent, newName, live ? project.name : null);
         let retitled = false;
         let heldNote;
         let heldTail;
-        const renameHarness = harnessFor(agent.command);
         if (live && renameHarness.supportsRename) {
             const classifier = renameHarness.paneClassifier;
             const { awaitingChoice, tail } = classifier.choiceCheck(agent.tmux_target);
@@ -1080,7 +1343,7 @@ export function registerAgents(server) {
         };
     }));
     server.registerTool("agent_send", {
-        description: "Type into an agent's terminal, addressed by name (or agent_id). text of any shape is prefixed with the sender tag, delivered as one bracketed paste and submitted with Enter unless submit=false. ONE EXCEPTION: text over 300 characters sent to a LEAD by anyone who is not that lead is stored and delivered as a one-line pointer instead, because a lead's pane is a human's own window; the receipt says so and names agent_message_get for the full text. Worker-bound text is never shortened at any length. With quiet_messaging on, a worker's submitted text to a Claude lead is stored with a message id and posted over the lead's messaging socket instead of typed (the same pointer when over 300 characters): the receipt says pending until the lead's prompt confirms it, hive types it into the pane once if no confirmation comes, and the socket post skips the pane checks below; do not resend a pending send. Alternatively pass keys (tmux key names like Escape, C-c, Enter). wait_ms (250-10000) returns the terminal tail after sending. A claude worker is already briefed by agent_spawn. A worker whose screen hive cannot classify is REFUSED on the text path entirely (its brief is at the spawn receipt's brief_path); keys still reaches it. A pane in tmux copy mode is REFUSED too, and retriably: tmux clears its bracketed-paste flag there, so the paste would lose its markers and the Enter would be eaten - leave copy mode (or agent_send(keys: [\"-X\", \"cancel\"]) to cancel it deliberately) and send again.",
+        description: "Type into an agent's terminal, addressed by name (or agent_id). text of any shape is prefixed with the sender tag, delivered as one bracketed paste and submitted with Enter unless submit=false. A submitted text send to a target on its current usage limit is stored and held in its message row until release; its receipt says pending, so do not resend it. keys and submit=false remain manual recovery paths. ONE EXCEPTION: text over 300 characters sent to a LEAD by anyone who is not that lead is stored and delivered as a one-line pointer instead, because a lead's pane is a human's own window; the receipt says so and names agent_message_get for the full text. Worker-bound text is never shortened at any length. With quiet_messaging on, a worker's submitted text to a Claude lead is stored with a message id and posted over the lead's messaging socket instead of typed (the same pointer when over 300 characters): the receipt says pending until the lead's prompt confirms it, hive types it into the pane once if no confirmation comes, and the socket post skips the pane checks below; do not resend a pending send. Alternatively pass keys (tmux key names like Escape, C-c, Enter). wait_ms (250-10000) returns the terminal tail after sending. A claude worker is already briefed by agent_spawn. A worker whose screen hive cannot classify is REFUSED on the text path entirely (its brief is at the spawn receipt's brief_path); keys still reaches it. A pane in tmux copy mode is REFUSED too, and retriably: tmux clears its bracketed-paste flag there, so the paste would lose its markers and the Enter would be eaten - leave copy mode (or agent_send(keys: [\"-X\", \"cancel\"]) to cancel it deliberately) and send again.",
         annotations: {
             readOnlyHint: false,
             destructiveHint: true,
@@ -1139,13 +1402,14 @@ export function registerAgents(server) {
                     "turning a text call into a keys call. Tab and newline are the only control characters " +
                     'allowed. To send an actual keystroke on purpose, use keys instead (e.g. keys: ["C-c"]).');
             }
-            const quiet = await sendQuietLeadMessage({
+            const messageOptions = {
                 projectId: project.id,
                 fromActor: currentActor(),
                 target: agent,
                 text: args.text,
                 submit: args.submit !== false,
-            });
+            };
+            const quiet = await sendUsageHeldMessage(messageOptions) ?? await sendQuietLeadMessage(messageOptions);
             if (quiet !== null) {
                 if (quiet.sent) {
                     confirmQueenWrite("agent_send", project.id, args, { sent: true, agent_id: agent.id }, auditIdentity);
@@ -1233,6 +1497,15 @@ export function registerAgents(server) {
                     };
                 }
             }
+            const newlyHeld = await sendUsageHeldMessage({
+                projectId: project.id,
+                fromActor: currentActor(),
+                target: agent,
+                text: args.text,
+                submit: submitting,
+            });
+            if (newlyHeld !== null)
+                return newlyHeld;
             if (agent.kind === LEAD_KIND &&
                 !isRunningLeadActor(currentActor()) &&
                 args.text.length > LEAD_MESSAGE_THRESHOLD) {
@@ -1257,9 +1530,32 @@ export function registerAgents(server) {
                     pasted = true;
                 }, () => {
                     buffered = true;
-                }, () => requireStillOwned(agent.id, identity, "agent_send"));
+                }, () => {
+                    requireStillOwned(agent.id, identity, "agent_send");
+                    if (submitting) {
+                        observeUsageLimit(agent.id, Date.now());
+                        const gate = usageLimitGate(agent.id, Date.now());
+                        if (gate.held)
+                            throw new UsageLimitActive(`the target harness is stopped by a usage limit until ${gate.until}`);
+                    }
+                });
             }
             catch (err) {
+                if (err instanceof UsageLimitActive && !pasted) {
+                    const held = await sendUsageHeldMessage({
+                        projectId: project.id,
+                        fromActor: currentActor(),
+                        target: agent,
+                        text: args.text,
+                        submit: submitting,
+                    });
+                    if (held !== null)
+                        return held;
+                }
+                if (err instanceof UsageLimitActive && pasted) {
+                    throw new Error(`[agent_send:usage-limit-after-paste] ${err.message}. The text was pasted but no Enter was sent; ` +
+                        "read the pane before deciding whether to submit or clear it.", { cause: err });
+                }
                 const shortenedClause = shortened === null ? "" : shortenedSendFailureClause(shortened.marker, shortened.message_id);
                 if (err instanceof PaneOwnershipLost) {
                     if (!pasted)
@@ -1434,6 +1730,25 @@ export function registerAgents(server) {
             }
             return { agent_id: agent.id, name: agent.name, closed: true, park_released: true };
         }
+        if (agent.status === "closed" && agent.kind === "agent" && agent.recovery_state === "pending") {
+            if (!markWorkerRetirementIntent(agent.id, paneIdentity(agent))) {
+                throw new Error(`Agent ${agent.id} changed before its recovery was abandoned. Nothing was changed.`);
+            }
+            let releasedHome = null;
+            if (agent.codex_home) {
+                try {
+                    releasedHome = reapCodexHomeForClosedAgent(agent.id, agent.codex_home);
+                }
+                catch {
+                }
+            }
+            return {
+                agent_id: agent.id,
+                name: agent.name,
+                closed: true,
+                note: pendingRecoveryAbandonmentNote(agent.id, agent.codex_home, releasedHome),
+            };
+        }
         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 ` +
@@ -1465,6 +1780,9 @@ export function registerAgents(server) {
         }
         if (live)
             live = stillOwnsPane(agent, "agent_close");
+        if (agent.kind === "agent" && !markWorkerRetirementIntent(agent.id, paneIdentity(agent))) {
+            throw new Error(`Agent ${agent.id} changed before its close intent was recorded. Nothing was changed.`);
+        }
         if (live)
             killAgentPane(agent.tmux_target);
         if (!closeAgentRow(agent.id, paneIdentity(agent))) {