@cmgmyr/hive 1.11.8 → 1.12.0

package/dist/codexHome.js

@@ -1,4 +1,4 @@
-import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, symlinkSync, unlinkSync, writeFileSync, } from "node:fs";
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, symlinkSync, unlinkSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -6,6 +6,7 @@ import { parse as parseToml } from "smol-toml";
 import { gitPrimaryRoot } from "./context.js";
 import { storeDir } from "./dataDir.js";
 import { hookEntry } from "./hooks.js";
+import { harnessFor } from "./harnesses.js";
 import { shellQuote } from "./tmux.js";
 export function codexHomeDir(key) {
     return join(storeDir(), "codex-homes", key);
@@ -21,6 +22,109 @@ export function preservedRolloutPath(key, transcriptPath) {
     return join(codexRolloutsDir(key), transcriptPath.slice(sessionsPrefix.length));
 }
 const ROLLOUT_FILE = /^rollout-.*\.jsonl$/;
+const MAX_FORK_ROLLOUT_BYTES = 64 * 1024 * 1024;
+function firstSessionMeta(path) {
+    const firstLine = readFileSync(path, "utf8").split("\n", 1)[0];
+    let record;
+    try {
+        record = JSON.parse(firstLine);
+    }
+    catch {
+        if (firstLine.includes("\"forked_from_id\""))
+            throw new Error("Codex fork rollout has malformed session metadata.");
+        return null;
+    }
+    if (!record || typeof record !== "object" || record.type !== "session_meta")
+        return null;
+    const payload = record.payload;
+    return payload && typeof payload === "object" ? payload : record;
+}
+function checkedSessionsPath(home, transcriptPath) {
+    const sessionsRoot = realpathSync(join(home, "sessions"));
+    const sourcePath = realpathSync(transcriptPath);
+    const relativePath = relative(sessionsRoot, sourcePath);
+    if (!relativePath || relativePath === ".." || relativePath.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`)) {
+        throw new Error("Codex transcript is outside its recorded CODEX_HOME sessions directory.");
+    }
+    const file = lstatSync(sourcePath);
+    if (!file.isFile() || !ROLLOUT_FILE.test(sourcePath.split(/[\\/]/).at(-1) ?? "")) {
+        throw new Error("Codex transcript is not a regular rollout file.");
+    }
+    return { sessionsRoot, sourcePath, relativePath };
+}
+export function seedCodexFork(source, childKey, seed = readCodexForkSeed(source)) {
+    writeCodexForkSeed(source, childKey, seed);
+}
+export function readCodexForkSeed(source) {
+    if (harnessFor(source.command).name !== "codex")
+        throw new Error("Only a Codex worker can seed a Codex fork.");
+    if (!source.session_id || !source.codex_home || !source.transcript_path) {
+        throw new Error("Codex source must have a recorded session, CODEX_HOME, and transcript path.");
+    }
+    const sourceHome = codexHomeDir(source.codex_home);
+    const { sessionsRoot, sourcePath, relativePath } = checkedSessionsPath(sourceHome, source.transcript_path);
+    const size = lstatSync(sourcePath).size;
+    if (size > MAX_FORK_ROLLOUT_BYTES)
+        throw new Error("Codex source rollout exceeds the 64 MiB fork-seed limit.");
+    const contents = readFileSync(sourcePath);
+    const lastNewline = contents.lastIndexOf(0x0a);
+    if (lastNewline < 0)
+        throw new Error("Codex source rollout has no complete JSONL records.");
+    const completePrefix = contents.subarray(0, lastNewline + 1);
+    const lines = completePrefix.toString("utf8").split("\n").filter(Boolean);
+    let sessionMeta = null;
+    try {
+        for (const line of lines) {
+            const record = JSON.parse(line);
+            if (record?.type === "session_meta") {
+                const payload = record.payload;
+                sessionMeta = payload && typeof payload === "object" ? payload : record;
+            }
+        }
+    }
+    catch {
+        throw new Error("Codex source rollout contains a malformed complete JSONL record.");
+    }
+    if (sessionMeta?.id !== source.session_id) {
+        throw new Error("Codex source rollout metadata.id does not match its recorded session id.");
+    }
+    return { sourceSessionId: source.session_id, relativePath, contents: completePrefix };
+}
+function writeCodexForkSeed(source, childKey, seed) {
+    if (seed.sourceSessionId !== source.session_id)
+        throw new Error("Codex fork seed no longer matches the captured source session.");
+    const childSessions = join(codexHomeDir(childKey), "sessions");
+    mkdirSync(childSessions, { recursive: true });
+    const destination = join(childSessions, seed.relativePath);
+    mkdirSync(dirname(destination), { recursive: true });
+    if (existsSync(destination))
+        throw new Error("Fresh Codex child home already contains the source rollout path.");
+    writeFileSync(destination, seed.contents, { flag: "wx" });
+}
+export function findCodexFork(childKey, sourceSessionId) {
+    const sessionsRoot = join(codexHomeDir(childKey), "sessions");
+    const matches = [];
+    for (const path of collectRolloutFiles(sessionsRoot)) {
+        let meta;
+        try {
+            meta = firstSessionMeta(path);
+        }
+        catch (e) {
+            if (e.code === "ENOENT")
+                continue;
+            throw e;
+        }
+        if (meta?.forked_from_id !== sourceSessionId)
+            continue;
+        if (typeof meta.id !== "string" || !meta.id || meta.id === sourceSessionId) {
+            throw new Error("Codex fork rollout has malformed session metadata.");
+        }
+        matches.push({ sessionId: meta.id, transcriptPath: path });
+    }
+    if (matches.length > 1)
+        throw new Error(`Found ${matches.length} Codex rollouts forked from the source session.`);
+    return matches[0] ?? null;
+}
 // Dirent.isFile()/.isDirectory() answer about the entry itself, not its target, so a symlinked
 // file or directory under sessions/ is neither and is silently skipped - never followed, never
 // moved. That is what keeps this walk off the auth.json symlink without naming it specially.

package/dist/context.js

@@ -354,6 +354,7 @@ export const QUEEN_REACH = {
     lease_release: "home",
     agent_spawn: "home",
     agent_resume: "home",
+    agent_fork: "home",
     agent_park: "home",
     agent_rename: "home",
     agent_close: "home",

package/dist/db.js

@@ -612,6 +612,31 @@ WHEN (NEW.fire_count > OLD.fire_count
 BEGIN
   SELECT RAISE(IGNORE);
 END;
+`,
+    `
+ALTER TABLE agents ADD COLUMN recovery_state TEXT NOT NULL DEFAULT ''
+  CHECK (recovery_state IN ('', 'pending', 'excluded'));
+`,
+    `
+CREATE TABLE agent_usage_limits (
+  agent_id INTEGER PRIMARY KEY REFERENCES agents(id) ON DELETE CASCADE,
+  project_id INTEGER NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
+  harness TEXT NOT NULL CHECK (harness IN ('claude', 'codex')),
+  pane_pid TEXT NOT NULL,
+  session_id TEXT NOT NULL,
+  signal_key TEXT NOT NULL,
+  observed_at TEXT NOT NULL,
+  reset_at TEXT,
+  expires_at TEXT NOT NULL,
+  released_at TEXT,
+  continue_claimed_at TEXT
+);
+CREATE INDEX idx_agent_usage_limits_gate ON agent_usage_limits(project_id, harness, expires_at)
+  WHERE released_at IS NULL;
+`,
+    `
+ALTER TABLE agents ADD COLUMN forked_from_agent_id INTEGER REFERENCES agents(id);
+ALTER TABLE agents ADD COLUMN forked_from_session_id TEXT NOT NULL DEFAULT '';
 `,
 ];
 export function storeSchemaAhead(database) {

package/dist/help.js

@@ -21,7 +21,7 @@ PROMPTS — invokable prompts (slash commands in MCP clients)
   runbook — load this project's own standing process
 
 AGENTS — spawn and drive worker sessions in tmux
-  agent_spawn, agent_list, agent_status, agent_send, agent_output,
+  agent_spawn, agent_fork, agent_list, agent_status, agent_send, agent_output,
   agent_message_get, agent_rename, agent_park, agent_resume, agent_close
 
 WAKE-UPS — scheduled nudges instead of polling
@@ -53,6 +53,23 @@ ACTORS — who is writing
   actor_prune`;
 }
 export const HELP_TOPICS = {
+    "crew-restore": `CREW RESTORE — resume crashed workers for this project
+
+Run \`hive crew-restore [--dry-run] [--json]\` from a registered project.
+The command resumes rows marked pending after a confirmed worker pane loss.
+It skips live, unknown, parked, deliberately closed and historical rows.
+The dry run reports candidates and blockers without changing rows or panes.
+Each restored worker keeps its row, actor, session, working directory and
+launch options. The command does not replay its previous assignment.
+
+This is a CLI command for the local tmux environment, not an MCP tool.`,
+    layout: `LAYOUT — restore a project's worker pane layout
+
+Run \`hive layout\` in a project to gather its live worker panes into the lead
+window and re-apply the merged hive.yml layout. The command takes no flags. It
+does nothing when the resolved placement is "window".
+
+This is a CLI command for the local tmux environment, not an MCP tool.`,
     workflow: `WORKFLOW — lead/worker orchestration
 
 One session acts as the lead. It spawns and drives workers with the agent
@@ -146,8 +163,18 @@ runbook (fork it first), not a pad write.`,
     and layout in hive.yml; an explicit argument overrides it. cwd defaults to the project root; pass
     a git worktree path to isolate parallel file edits. A claude worker gets
     its brief in the system prompt; other commands return instructions to
-    PREPEND to the first prompt.
+    PREPEND to the first prompt. A same-project worker or lead currently
+    stopped by that harness's usage limit makes spawn retryable until its
+    reset or bounded deadline; hive does not queue spawns.
     Workers run with HIVE_PROJECT_LOCK=1.
+  agent_fork(agent_id, name, cwd?, model?, effort?, read_only?, todo_id?,
+    placement?, layout?):
+    make a new worker from a same-project Claude or Codex session. The child
+    gets a new identity, pane, session and brief, and receives no assignment
+    until you send one. It does not copy the source worktree, Hive todo link,
+    or promise that harness todos or tasks copy. Claude process-scoped grants
+    need approval again. A Codex child gets a fresh home seeded with the
+    source rollout; a closed Codex worker whose home was reaped cannot fork.
   agent_send(name|agent_id, text?, keys?, submit?, wait_ms?) — type into the
     worker's terminal. Multi-line text pastes safely; keys sends tmux key
     names like Escape or C-c. wait_ms returns the terminal tail after.
@@ -159,12 +186,15 @@ runbook (fork it first), not a pad write.`,
     posted to the lead's messaging socket instead; the receipt says pending
     until the lead's prompt confirms it, and hive types it into the pane once
     if nothing does. Do not resend a pending send.
+    A submitted text send to a target stopped by its usage limit is stored
+    as pending until release. keys and submit=false remain manual recovery.
   agent_message_get(message_id) — the full text behind a pointer line, plus
     the delivery state of a quiet message. Kept 7 days; a lookup for a pruned id says it expired, not that it is missing.
   agent_output(name|agent_id, lines?) — read the rendered terminal.
   agent_status(name|agent_id, include_brief?) — liveness, current command,
     short tail, and the path to the brief this worker was given
-    (include_brief=true returns its text; no transcript records it).
+    (include_brief=true returns its text; no transcript records it). Forked
+    workers show forked_from_agent_id and forked_from_session_id.
   agent_list(include_closed?, limit?, before_id?) — agents with live status.
     include_closed adds closed/parked rows, newest first, limit 20/max 100;
     page with before_id set to the receipt's next_before_id.
@@ -181,7 +211,9 @@ runbook (fork it first), not a pad write.`,
     claude or codex worker on a fresh pane from its recorded session id,
     with the same actor_id and its full prior context. It does not send
     the assignment; agent_send it afterwards. Read the pane before
-    believing any wake about a worker you just resumed.
+    believing any wake about a worker you just resumed. A same-project
+    harness limit makes resume retryable until its reset or bounded deadline;
+    hive does not queue resumes.
   agent_close(name|agent_id, confirm_self?, row_only?) — 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
@@ -253,7 +285,9 @@ Delivery contract:
   and the next action. Plain English, no markup.
   Waking your OWN lead pane is the exception: it is not cold, so carry the
   action and the ids and point at where the detail lives.
-  With lead_turn_budget.auto_handoff on, a lead past its warn budget gets
+  With a lead_turn_budget, auto_handoff is on by default. Set
+  lead_turn_budget.auto_handoff to false to keep the lead in this session.
+  When enabled, a lead past its warn budget gets
   a "hive lead handoff request #N" wake: follow its steps, then run
   hive lead-handoff. A human prompt during the grace postpones it.
 
@@ -378,7 +412,9 @@ since every read pays for its full length.`,
 Blockers form a dependency graph (cycles are rejected). A todo is blocked
 while any of its blockers is not completed. Archived and completed are
 independent axes: archiving hides a closed lane's scaffolding from
-todo_list without marking anything done.`,
+todo_list without marking anything done. A project's optional completion_gate
+in hive.yml runs before a todo becomes completed; hive lead reviews its
+command at startup, and a refused gate leaves the todo unchanged.`,
     kv: `KV — small shared status values
 
   kv_set(key, value, ttl_seconds?) — value is any JSON; TTL optional

package/dist/hook.js

@@ -58,6 +58,26 @@ function acceptsWorkerHook(row, payload, sessionsRoot) {
         typeof payload.session_id === "string" && payload.session_id !== "" &&
         row.session_id === payload.session_id);
 }
+async function acceptsForkHook(row, payload, sessionsRoot) {
+    if (!row.forked_from_session_id)
+        return acceptsWorkerHook(row, payload, sessionsRoot);
+    if (payload.session_id === row.forked_from_session_id)
+        return false;
+    if (typeof payload.session_id !== "string" || typeof payload.transcript_path !== "string")
+        return false;
+    try {
+        const { findCodexFork } = await import("./codexHome.js");
+        const child = findCodexFork(row.codex_home, row.forked_from_session_id);
+        if (!child || child.sessionId !== payload.session_id)
+            return false;
+        const reported = canonicalPathWithMissingSuffix(payload.transcript_path);
+        const discovered = canonicalPathWithMissingSuffix(child.transcriptPath);
+        return reported !== null && reported === discovered && acceptsWorkerHook(row, payload, sessionsRoot);
+    }
+    catch {
+        return false;
+    }
+}
 function validCheckpointThreshold() {
     const text = process.env.HIVE_CONTEXT_CHECKPOINT_PERCENT;
     if (!text || !/^\d+$/.test(text))
@@ -252,14 +272,21 @@ if (process.argv[2] === "post_tool_use") {
         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 = ?")
+            const row = db.prepare("SELECT kind, command, status, codex_home, session_id, forked_from_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 !== "") {
+                    if (row.forked_from_session_id) {
+                        if (!row.codex_home)
+                            process.exit(0);
+                        const { codexHomeDir } = await import("./codexHome.js");
+                        if (!await acceptsForkHook(row, suppliedPayload, join(codexHomeDir(row.codex_home), "sessions")))
+                            process.exit(0);
+                    }
+                    else 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);
@@ -283,8 +310,31 @@ try {
     if (actorId) {
         const event = process.argv[2] ?? "";
         const hookPayload = readPayload();
-        const row = db.prepare("SELECT kind, command, status, codex_home, session_id FROM agents WHERE actor_id = ?")
+        if (event === "stop_failure") {
+            try {
+                const { observeClaudeStopFailure } = await import("./usageLimit.js");
+                const row = db.prepare("SELECT id, command, kind, status FROM agents WHERE actor_id = ? AND status = 'running'")
+                    .get(actorId);
+                const { harnessFor } = await import("./harnesses.js");
+                if (row && ["agent", "lead"].includes(row.kind) && harnessFor(row.command).name === "claude" && hookPayload.error === "rate_limit") {
+                    reconcileSessionId(actorId, hookPayload);
+                    reconcileTranscriptPath(actorId, hookPayload);
+                    observeClaudeStopFailure(row.id, hookPayload, Date.now());
+                }
+            }
+            catch { }
+            record(actorId, event, UNCHANGED);
+            process.exit(0);
+        }
+        const row = db.prepare("SELECT kind, command, status, codex_home, session_id, forked_from_session_id FROM agents WHERE actor_id = ?")
             .get(actorId);
+        if (row?.kind === "agent" && row.forked_from_session_id) {
+            if (hookPayload.session_id === row.forked_from_session_id)
+                process.exit(0);
+            const { harnessFor } = await import("./harnesses.js");
+            if (harnessFor(row.command).name === "claude" && hookPayload.session_id !== row.session_id)
+                process.exit(0);
+        }
         let guarded = false;
         let state = null;
         if (row?.kind === "agent") {
@@ -293,8 +343,13 @@ try {
                 if (row.status !== "running")
                     process.exit(0);
                 const { codexHomeDir } = await import("./codexHome.js");
+                if (row.forked_from_session_id) {
+                    if (!row.codex_home || !await acceptsForkHook(row, hookPayload, join(codexHomeDir(row.codex_home), "sessions"))) {
+                        process.exit(0);
+                    }
+                }
                 const result = db.transaction(() => {
-                    const current = db.prepare("SELECT kind, command, status, codex_home, session_id FROM agents WHERE actor_id = ?")
+                    const current = db.prepare("SELECT kind, command, status, codex_home, session_id, forked_from_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 };
@@ -303,8 +358,9 @@ try {
                         return { status: "changed", state: null };
                     }
                     const sessionsRoot = join(codexHomeDir(current.codex_home), "sessions");
-                    if (!acceptsWorkerHook(current, hookPayload, sessionsRoot))
+                    if (current.forked_from_session_id !== row.forked_from_session_id || !acceptsWorkerHook(current, hookPayload, sessionsRoot)) {
                         return { status: "rejected", state: null };
+                    }
                     const state = applyWorkerTransition(actorId, event);
                     reconcileSessionId(actorId, hookPayload);
                     reconcileTranscriptPath(actorId, hookPayload);

package/dist/hooks.js

@@ -40,6 +40,7 @@ function stateHookSettings() {
     return {
         hooks: {
             Stop: [hookEntry("stop")],
+            StopFailure: [{ ...hookEntry("stop_failure"), matcher: "rate_limit" }],
             UserPromptSubmit: [hookEntry("prompt")],
             Notification: [hookEntry("notify")],
             SessionEnd: [hookEntry("session_end")],

package/dist/leadHandoff.js

@@ -11,8 +11,11 @@ import { readTurnCount } from "./turnCount.js";
 export { casHandoff, HELD_REASON_HANDOFF, handoffHoldsWake, readActiveHandoff, readHandoff, readHandoffGate, SUCCESSOR_NOT_READY, } from "./leadHandoffState.js";
 export const HANDOFF_PAD_NAME = "hive-lead-handoff";
 export const sha256 = (text) => createHash("sha256").update(text).digest("hex");
+function autoHandoffEnabled(budget) {
+    return budget !== null && (budget.auto_handoff ?? true);
+}
 export function handoffEligibility(lead, budget, snapshot = readLeadSafetySnapshot(lead.id)) {
-    if (budget === null || budget.auto_handoff !== true)
+    if (budget === null || !autoHandoffEnabled(budget))
         return { eligible: false, why: "auto_handoff is not enabled" };
     if (harnessFor(lead.command).name !== "claude")
         return { eligible: false, why: "the lead is not a Claude lead" };
@@ -274,7 +277,7 @@ export function driveLeadHandoff(actorId, budgetFor) {
         settleAfterRespawn(row, lead);
         return;
     }
-    if (budget?.auto_handoff !== true) {
+    if (!autoHandoffEnabled(budget)) {
         failHandoff(row.id, "lead_turn_budget.auto_handoff is no longer on");
         return;
     }
@@ -364,7 +367,7 @@ export function padProblem(pad, projectId, revision) {
 }
 // The final quiet check. A screen or probe that cannot be read waits; it never establishes quiet.
 export async function respawnVerdict(row, lead, budget) {
-    if (budget?.auto_handoff !== true)
+    if (!autoHandoffEnabled(budget))
         return { fail: "lead_turn_budget.auto_handoff is no longer on" };
     if (lead === undefined || lead.pane_pid !== row.predecessor_pane_pid || lead.tmux_target !== row.pane_target) {
         return { fail: "the lead row no longer names the pane this handoff was requested for" };

package/dist/leadHandoffCli.js

@@ -7,7 +7,7 @@ import { cliPath } from "./dispatcher.js";
 import { FIRST_MESSAGE_SHA_ENV, firstMessageDigest } from "./firstMessage.js";
 import { ensureLeadHooksFile } from "./hooks.js";
 import { appendClaudeLeadArgs, crewPluginDir, isTrusted, leadIdentityEnv, renderLeadPosture } from "./leadLaunch.js";
-import { loadProjectYml } from "./projectYml.js";
+import { leadSidebarEnabled, loadProjectYml, quietMessagingEnabled } from "./projectYml.js";
 import { buildEnvFlags } from "./spawn.js";
 import { panePidForRecord, rowOwnership, shellQuote, tmux, TmuxTimeoutError } from "./tmux.js";
 import { automationBlocker, failHandoff, missingHeadings, padProblem, readPad, RESPAWN_WAIT_LIMIT_SECONDS, respawnVerdict, runningLeadByActor, sha256, successorPrompt, } from "./leadHandoff.js";
@@ -152,8 +152,8 @@ async function successorLaunch(row, lead, attempt, token) {
         harness,
         projectId: lead.project_id,
         projectName: lead.name,
-        hooksPath: ensureLeadHooksFile(lead.project_id, config?.quiet_messaging === true),
-        sidebarPluginDir: config?.lead_sidebar === true ? crewPluginDir() : null,
+        hooksPath: ensureLeadHooksFile(lead.project_id, quietMessagingEnabled(config)),
+        sidebarPluginDir: leadSidebarEnabled(config) ? crewPluginDir() : null,
         posture: renderLeadPosture(config).rendered,
         firstMessage,
     });

package/dist/leadMessageDelivery.js

@@ -1,10 +1,11 @@
 import { dataDir, db } from "./db.js";
-import { CROSS_SESSION_CLOSE, promptMarkerEvidenceSql, postClaudeWake, quietMessagingOn, socketGraceDue, socketSenderAddress, SOCKET_MESSAGE_FOOTER, } from "./claudeWake.js";
+import { CROSS_SESSION_CLOSE, promptMarkerEvidenceSql, quietMessagingHooksLaunched, postClaudeWake, quietMessagingOn, socketGraceDue, socketSenderAddress, SOCKET_MESSAGE_FOOTER, } from "./claudeWake.js";
 import { harnessFor, paneClassifierFor } from "./harnesses.js";
 import { LEAD_MESSAGE_THRESHOLD, MESSAGE_METHOD, MESSAGE_RETENTION, MESSAGE_STATUS, renderLeadMessage, senderTag, shortenedSendNote, storeLeadMessage, } from "./leadMessage.js";
 import { readHandoffGate } from "./leadHandoffState.js";
 import { HANDED_OFF_STATES_SQL, readLeadTurnState } from "./leadState.js";
 import { currentOwnership, PaneOwnershipLost, paneIdentity, requireStillOwned } from "./spawn.js";
+import { observeUsageLimit, usageLimitGate } from "./usageLimit.js";
 import { PANE_LEASE_SETTLE_MS, releasePaneLease, tryAcquirePaneLease } from "./leaseStore.js";
 import { holdsHumanInput, paneInCopyMode, sendText, sleep, TmuxTimeoutError, } from "./tmux.js";
 const EV_MARKER = "(agent_messages.sender_tag || '[message #' || agent_messages.id || ',')";
@@ -18,6 +19,12 @@ const messageEvidenceSql = (select) => `
      AND ${promptMarkerEvidenceSql(messageMarkerAt)}`;
 const RETAINED = `agent_messages.created_at >= datetime('now', '${MESSAGE_RETENTION}')`;
 const handoffHolds = (agentId) => readHandoffGate(agentId)?.holdAutomation === true;
+function usageLimitUntil(target) {
+    const now = Date.now();
+    observeUsageLimit(target.id, now);
+    const gate = usageLimitGate(target.id, now);
+    return gate.held ? gate.until : null;
+}
 const HANDOFF_HOLD_NOTE = "the lead is handing off to a fresh session; held until the successor completes its first turn";
 function eligible(options) {
     const { projectId, fromActor, target, submit } = options;
@@ -30,7 +37,7 @@ function eligible(options) {
     const sender = db
         .prepare("SELECT 1 AS hit FROM agents WHERE project_id = ? AND actor_id = ? AND status = 'running' AND kind = 'agent'")
         .get(projectId, fromActor);
-    return sender !== undefined && quietMessagingOn(projectId);
+    return sender !== undefined && quietMessagingOn(projectId) && quietMessagingHooksLaunched(projectId, target.command);
 }
 function registeredSocket(target) {
     return (target.claude_messaging_socket !== "" &&
@@ -67,6 +74,8 @@ function stamp(id, column) {
 function socketText(id, text, tag) {
     return `${renderLeadMessage(id, text, tag)}\n\n${SOCKET_MESSAGE_FOOTER}`;
 }
+class UsageLimitRace extends Error {
+}
 function hold(row, reason) {
     try {
         db.prepare("UPDATE agent_messages SET delivery_note = ? WHERE id = ? AND delivery_status = ?").run(reason, row.id, MESSAGE_STATUS.fallbackPending);
@@ -119,6 +128,10 @@ function retargetAfterHandoff(row) {
 }
 // One guarded pane attempt. The claim is the CAS that makes it at most one per message.
 async function paneFallback(original, snapshot) {
+    const initialTarget = db.prepare("SELECT * FROM agents WHERE id = ?").get(original.to_agent_id);
+    const heldUntil = initialTarget ? usageLimitUntil(initialTarget) : null;
+    if (heldUntil !== null)
+        return hold(original, `the target harness is stopped by a usage limit until ${heldUntil}`);
     if (handoffHolds(original.to_agent_id))
         return hold(original, HANDOFF_HOLD_NOTE);
     const row = retargetAfterHandoff(original);
@@ -156,6 +169,10 @@ async function paneFallback(original, snapshot) {
             return hold(row, choice ? "the lead's pane is waiting on a choice" : "the lead's pane could not be read");
         if (holdsHumanInput(classifier.inputBoxState(pane)))
             return hold(row, "the lead's input box holds unsubmitted text");
+        const latestTarget = db.prepare("SELECT * FROM agents WHERE id = ?").get(row.to_agent_id);
+        const latestHold = latestTarget ? usageLimitUntil(latestTarget) : null;
+        if (latestHold !== null)
+            return hold(row, `the target harness is stopped by a usage limit until ${latestHold}`);
         const claimed = (() => {
             try {
                 return (db
@@ -173,14 +190,29 @@ async function paneFallback(original, snapshot) {
         let buffered = false;
         wrote = true;
         try {
-            await sendText(pane, renderLeadMessage(row.id, row.text, row.sender_tag ?? "", row.socket_attempt_at !== null), true, () => {
+            await sendText(pane, target.kind === "lead"
+                ? renderLeadMessage(row.id, row.text, row.sender_tag ?? "", row.socket_attempt_at !== null)
+                : `${row.sender_tag ?? ""}${row.text}`, true, () => {
                 pasted = true;
                 stamp(row.id, "typed_at");
             }, () => {
                 buffered = true;
-            }, () => requireStillOwned(row.to_agent_id, identity, `message #${row.id} fallback`));
+            }, () => {
+                const current = db.prepare("SELECT * FROM agents WHERE id = ?").get(row.to_agent_id);
+                if (current) {
+                    const until = usageLimitUntil(current);
+                    if (until !== null)
+                        throw new UsageLimitRace(`the target harness is stopped by a usage limit until ${until}`);
+                }
+                requireStillOwned(row.to_agent_id, identity, `message #${row.id} fallback`);
+            });
         }
         catch (err) {
+            if (err instanceof UsageLimitRace && !pasted) {
+                const reason = err.message;
+                setStatus(row.id, MESSAGE_STATUS.fallbackClaimed, MESSAGE_STATUS.fallbackPending, { delivery_note: reason });
+                return { kind: "held", reason };
+            }
             const reason = pasteFailure(err, pasted, buffered);
             setStatus(row.id, MESSAGE_STATUS.fallbackClaimed, MESSAGE_STATUS.failed, { delivery_note: reason });
             return { kind: "failed", reason };
@@ -201,8 +233,33 @@ function earlierFallbackPending(row) {
         .get(row.from_actor, row.to_agent_id, row.id, MESSAGE_STATUS.fallbackPending) !== undefined);
 }
 const DO_NOT_RESEND = "do not resend";
+export async function sendUsageHeldMessage(options) {
+    if (!options.submit || options.target.status !== "running")
+        return null;
+    const until = usageLimitUntil(options.target);
+    if (until === null)
+        return null;
+    const { projectId, fromActor, target, text } = options;
+    const { id } = storeLeadMessage(projectId, fromActor, target.id, text);
+    const tag = senderTag(projectId, fromActor);
+    db.prepare(`UPDATE agent_messages SET delivery_status = ?, delivery_method = ?, delivery_note = ?,
+      target_identity = ?, sender_tag = ? WHERE id = ?`)
+        .run(MESSAGE_STATUS.fallbackPending, MESSAGE_METHOD.pty, `held for usage limit until ${until}`, JSON.stringify(paneIdentity(target)), tag, id);
+    return {
+        agent_id: target.id,
+        name: target.name,
+        sent: false,
+        pending: true,
+        message_id: id,
+        delivery_method: MESSAGE_METHOD.pty,
+        note: `Message #${id} is accepted and stored, held for the target's usage limit until ${until}; do NOT resubmit it. agent_message_get(${id}) shows its delivery state.`,
+    };
+}
 // null means this send is not eligible, and agent_send's ordinary pane path runs unchanged.
 export async function sendQuietLeadMessage(options) {
+    const held = await sendUsageHeldMessage(options);
+    if (held !== null)
+        return held;
     if (!eligible(options))
         return null;
     const { projectId, fromActor, target, text } = options;
@@ -231,6 +288,14 @@ export async function sendQuietLeadMessage(options) {
             text: body,
             beforeWrite: () => {
                 requireStillOwned(target.id, identity, `message #${id} socket delivery`);
+                const until = usageLimitUntil(target);
+                if (until !== null) {
+                    setStatus(id, MESSAGE_STATUS.socketPending, MESSAGE_STATUS.fallbackPending, {
+                        delivery_method: MESSAGE_METHOD.pty,
+                        delivery_note: `held for usage limit until ${until}`,
+                    });
+                    return false;
+                }
                 const now = db
                     .prepare(`SELECT a.status, a.kind, a.pane_pid, a.claude_messaging_socket AS socket, a.claude_messaging_pane_pid AS pid,
                     m.delivery_status
@@ -311,7 +376,9 @@ function expireGrace() {
         .all(MESSAGE_STATUS.socketPending);
     for (const row of pending) {
         try {
-            const target = db.prepare("SELECT actor_id FROM agents WHERE id = ?").get(row.to_agent_id);
+            const target = db.prepare("SELECT * FROM agents WHERE id = ?").get(row.to_agent_id);
+            if (target && usageLimitUntil(target) !== null)
+                continue;
             const panePid = JSON.parse(row.target_identity ?? "{}").pane_pid ?? "";
             if (target === undefined || !graceExpired(row, target.actor_id, panePid))
                 continue;
@@ -345,6 +412,13 @@ export async function retryQuietLeadMessages(snapshot) {
         if (blocked.has(pair))
             continue;
         try {
+            const target = db.prepare("SELECT * FROM agents WHERE id = ?").get(row.to_agent_id);
+            const until = target ? usageLimitUntil(target) : null;
+            if (until !== null) {
+                hold(row, `the target harness is stopped by a usage limit until ${until}`);
+                blocked.add(pair);
+                continue;
+            }
             const outcome = await paneFallback(row, snapshot);
             if (outcome.kind === "held")
                 blocked.add(pair);