@cmgmyr/hive 1.3.0 → 1.4.0

package/dist/tools/wakes.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { db } from "../db.js";
-import { currentActor, effectiveProjectId } from "../context.js";
+import { commitQueenStateWrite } from "../queenAudit.js";
+import { currentActor, effectiveProjectId, getProject, isQueenLead } from "../context.js";
 import { run } from "../result.js";
 import { findAgent, isLive, probeFailed, summaryLiveness } from "./agents.js";
 import { ACTIVE_TIMER_WHERE, LOG_RETENTION, OWNED_BY_WATCH, WATCH_SCOPE_PROJECT, seedGoneCursor, } from "../scheduler.js";
@@ -8,7 +9,9 @@ import { idParam, projectIdParam } from "./params.js";
 import { cutToUnitBudget } from "../slug.js";
 import { awaitingFirstPrompt } from "../firstPrompt.js";
 import { deriveProvenance } from "../stateProvenance.js";
-import { findUnsafeControlChar, liveTargets, TEXT_ALLOWED_CONTROL_CHARS } from "../tmux.js";
+import { findUnsafeControlChar, liveTargets, paneReissued, rowAliveProbe, TEXT_ALLOWED_CONTROL_CHARS, } from "../tmux.js";
+import { readLeadTurnState } from "../leadState.js";
+import { LEAD_TARGET_GONE, LEAD_TARGET_REISSUED, leadSubscription, paneVeto, runningLeadOf } from "../leadWatch.js";
 import { isRunningLeadActor, LEAD_KIND } from "../spawn.js";
 import { commandHead, screenClassifiable } from "../harnesses.js";
 const agentRefParam = z
@@ -125,6 +128,7 @@ const baseWakeFields = (t, { truncate = true } = {}) => ({
     deliver_to: t.deliver_actor,
     ...(t.watch_scope ? { scope: t.watch_scope, standing: true } : {}),
     ...(t.parent_wake_id != null ? { parent_wake_id: t.parent_wake_id } : {}),
+    ...leadWatchFields(t),
 });
 const STANDING_WATCH_LIFETIME_SECONDS = 4 * 60 * 60;
 const openStandingWatch = db.transaction((projectId, owner, body, deliverActor, deliverPane, maxWait) => {
@@ -172,6 +176,112 @@ function createStandingWatch(projectId, args) {
             "finished before the watch was set is exactly the finish a one-shot loses. Go quiet.",
     };
 }
+export const LEAD_WATCH_QUEEN_ONLY = "LEAD_WATCH_QUEEN_ONLY";
+const openLeadWatch = db.transaction((homeProjectId, body, mode, delivery, maxWait, target) => {
+    const state = readLeadTurnState(target.agentId);
+    const sameLaunch = state !== null && state.pane_pid === target.panePid;
+    const sessionId = sameLaunch && state.state !== "unknown" ? state.session_id : "";
+    const baseline = state?.idle_seq ?? 0;
+    const row = db
+        .prepare(`INSERT INTO wakes (project_id, owner, body, kind, watch, deliver_actor, deliver_pane, max_wait_at)
+         VALUES (?, ?, ?, ?, '[]', ?, ?, datetime('now', printf('+%d seconds', ?)))
+         RETURNING id`)
+        .get(homeProjectId, currentActor(), body, `idle_${mode}`, delivery.actor, delivery.pane, maxWait);
+    db.prepare(`INSERT INTO lead_idle_subscriptions (wake_id, target_project_id, agent_id, pane_pid, session_id, baseline_idle_seq)
+       VALUES (?, ?, ?, ?, ?, ?)`).run(row.id, target.projectId, target.agentId, target.panePid, sessionId, baseline);
+    return { id: row.id, session_id: sessionId, baseline_idle_seq: baseline };
+});
+function createLeadWatch(leadProjectId, args) {
+    if (!isQueenLead()) {
+        throw new Error(`${LEAD_WATCH_QUEEN_ONLY}: lead_project_id is the queen's alone. Only the running queen lead, in its own ` +
+            "project and without HIVE_PROJECT_LOCK, may wait on another project's lead; a project's own lead and " +
+            "every worker are refused. A worker is watched with agents=[...] or scope=\"project\" instead.");
+    }
+    if (args.project_id != null || args.deliver_to != null) {
+        throw new Error("lead_project_id refuses project_id and deliver_to: the wake is always stored in the queen's own project " +
+            "and delivered to the queen's own pane, so neither has anything to choose. Name the watched project " +
+            "with lead_project_id alone.");
+    }
+    const home = effectiveProjectId();
+    if (leadProjectId === home) {
+        throw new Error("lead_project_id names the queen's own project, and the queen cannot wait on itself.");
+    }
+    const project = getProject(leadProjectId);
+    if (!project)
+        throw new Error(`Unknown project_id ${leadProjectId}. Call project_list to see options.`);
+    const lead = runningLeadOf(leadProjectId);
+    if (!lead)
+        throw new Error(`${LEAD_TARGET_GONE}: project ${leadProjectId} ("${project.name}") has no running lead to watch.`);
+    if (!screenClassifiable(lead.command)) {
+        throw new Error(`Project ${leadProjectId}'s lead runs ${JSON.stringify(commandHead(lead.command))}, whose screen hive cannot ` +
+            "classify, so a turn ending while a human is typing to it could not be told apart from one nobody is at.");
+    }
+    if (lead.pane_pid === "") {
+        throw new Error(`${LEAD_TARGET_REISSUED}: project ${leadProjectId}'s lead has no recorded pane pid, so a reused pane id ` +
+            "could not be told from this lead. Restart it with hive lead to record one.");
+    }
+    const snapshot = liveTargets();
+    if (snapshot === null)
+        throw new Error("tmux did not answer, so the watched lead's pane cannot be verified. Try again.");
+    const probe = rowAliveProbe(lead.tmux_socket, lead.tmux_target, snapshot);
+    if (probe.live === null) {
+        throw new Error(`Project ${leadProjectId}'s lead lives on a tmux socket this process cannot probe.`);
+    }
+    if (!probe.live)
+        throw new Error(`${LEAD_TARGET_GONE}: project ${leadProjectId}'s lead pane is gone.`);
+    if (paneReissued(lead.pane_pid, probe)) {
+        throw new Error(`${LEAD_TARGET_REISSUED}: project ${leadProjectId}'s lead pane id now belongs to another process.`);
+    }
+    const mode = args.mode ?? "any";
+    const state = readLeadTurnState(lead.id);
+    const idleNow = state !== null && state.pane_pid === lead.pane_pid && state.state === "idle";
+    if (mode === "all" && idleNow && paneVeto(lead) === null) {
+        return {
+            status: "already_satisfied",
+            note: `Project ${leadProjectId}'s lead has already ended its turn; nothing was scheduled. Read it now.`,
+        };
+    }
+    const delivery = resolveDelivery(home);
+    const maxWait = args.max_wait_seconds ?? 900;
+    const row = openLeadWatch.immediate(home, args.body, mode, delivery, maxWait, {
+        projectId: leadProjectId,
+        agentId: lead.id,
+        panePid: lead.pane_pid,
+    });
+    return {
+        wake_id: row.id,
+        mode,
+        lead_watch: {
+            project_id: leadProjectId,
+            agent_id: lead.id,
+            name: lead.name,
+            state: state !== null && state.pane_pid === lead.pane_pid ? state.state : "unknown",
+            baseline_idle_seq: row.baseline_idle_seq,
+        },
+        max_wait_seconds: maxWait,
+        deliver_to: delivery.actor,
+        note: (mode === "any"
+            ? "Fires on the lead's NEXT turn ending; a turn that already ended does not count. "
+            : "Fires once the lead's turn has ended. ") +
+            "A turn ending is not the lead finishing its work: read it before acting. A dead, restarted or reissued " +
+            "lead pane ends the watch with that reason instead.",
+    };
+}
+function leadWatchFields(t) {
+    const sub = leadSubscription(t.id);
+    if (sub === null)
+        return {};
+    return {
+        lead_watch: {
+            project_id: sub.target_project_id,
+            agent_id: sub.agent_id,
+            pane_pid: sub.pane_pid,
+            session_id: sub.session_id,
+            baseline_idle_seq: sub.baseline_idle_seq,
+            ...(sub.terminal_reason !== null ? { terminal_reason: sub.terminal_reason } : {}),
+        },
+    };
+}
 export function registerWakes(server) {
     server.registerTool("wake_set", {
         description: "Schedule a wake-up: after delay_seconds the body is typed into the target session's terminal " +
@@ -202,20 +312,22 @@ export function registerWakes(server) {
         rejectUnsafeBody(args.body);
         const projectId = effectiveProjectId(args.project_id);
         const delivery = resolveDelivery(projectId, args.deliver_to);
-        const row = db
-            .prepare(`INSERT INTO wakes (project_id, owner, body, kind, deliver_actor, deliver_pane, due_at, repeat_every_ms)
-             VALUES (?, ?, ?, 'delay', ?, ?, datetime('now', printf('+%d seconds', ?)), ?)
-             RETURNING id, due_at`)
-            .get(projectId, currentActor(), args.body, delivery.actor, delivery.pane, args.delay_seconds, args.repeat_every_seconds != null ? args.repeat_every_seconds * 1000 : null);
-        return {
-            wake_id: row.id,
-            due_at: row.due_at,
-            deliver_to: delivery.actor,
-            repeating: args.repeat_every_seconds != null,
-        };
+        return commitQueenStateWrite("wake_set", projectId, args, () => {
+            const row = db
+                .prepare(`INSERT INTO wakes (project_id, owner, body, kind, deliver_actor, deliver_pane, due_at, repeat_every_ms)
+               VALUES (?, ?, ?, 'delay', ?, ?, datetime('now', printf('+%d seconds', ?)), ?)
+               RETURNING id, due_at`)
+                .get(projectId, currentActor(), args.body, delivery.actor, delivery.pane, args.delay_seconds, args.repeat_every_seconds != null ? args.repeat_every_seconds * 1000 : null);
+            return {
+                wake_id: row.id,
+                due_at: row.due_at,
+                deliver_to: delivery.actor,
+                repeating: args.repeat_every_seconds != null,
+            };
+        });
     }));
     server.registerTool("wake_when_idle", {
-        description: "Wake up when watched agents go idle (exact state from Claude Code hooks) or max_wait_seconds passes - except delivery HOLDS past that bound instead, for as long as the target pane is on a dialog or has unsubmitted human text in it, rather than pasting the wake body into either (.claude/rules/tmux-and-panes.md). Two shapes, and you pass EXACTLY ONE of them. agents=[...] is a ONE-SHOT over a named list: mode=any fires on the first fresh idle transition, mode=all fires when every watched agent is idle (returns already_satisfied without scheduling anything if they all are now), and either way it stops watching once it fires. scope=\"project\" is a STANDING WATCH over the crew you spawn in this project, including workers spawned later: it never stops watching, and on each finish it delivers a roster naming who finished and who is still going, until max_wait_seconds runs out or you wake_cancel it. You may hold ONE standing watch per project: a second call is refused and names the one already running, since two would report every finish twice. Use the standing watch when you are running more than one worker - a one-shot leaves every other worker unwatched from the moment it fires. Use either instead of polling. Refuses a lead target: a lead has no idle/working state channel.",
+        description: "Wake up when watched agents go idle (exact state from Claude Code hooks) or max_wait_seconds passes - except delivery HOLDS past that bound instead, for as long as the target pane is on a dialog or has unsubmitted human text in it, rather than pasting the wake body into either (.claude/rules/tmux-and-panes.md). Two shapes for workers, plus one for the queen, and you pass EXACTLY ONE of them. agents=[...] is a ONE-SHOT over a named list: mode=any fires on the first fresh idle transition, mode=all fires when every watched agent is idle (returns already_satisfied without scheduling anything if they all are now), and either way it stops watching once it fires. scope=\"project\" is a STANDING WATCH over the crew you spawn in this project, including workers spawned later: it never stops watching, and on each finish it delivers a roster naming who finished and who is still going, until max_wait_seconds runs out or you wake_cancel it. You may hold ONE standing watch per project: a second call is refused and names the one already running, since two would report every finish twice. Use the standing watch when you are running more than one worker - a one-shot leaves every other worker unwatched from the moment it fires. Use either instead of polling. agents=[...] refuses a lead: it watches worker state, which a lead does not write. lead_project_id is the QUEEN's alone: a one-shot that fires when another registered project's running lead ENDS A TURN (never 'finished its work'), stored in and delivered to the queen's own project, and ended with a named reason if that lead's pane dies, is reissued, or restarts.",
         annotations: {
             readOnlyHint: false,
             destructiveHint: false,
@@ -244,11 +356,17 @@ export function registerWakes(server) {
                 "scope=\"project\": THE WATCH'S LIFETIME, default 14400 (4 hours), after which it delivers one " +
                 "last wake saying it has expired and stops watching. Not a hard deadline either way: delivery " +
                 "holds past it while the target pane is on a dialog or has unsubmitted text, until the pane clears."),
+            lead_project_id: idParam
+                .optional()
+                .describe("QUEEN ONLY: wake when the running lead of this OTHER registered project ends a turn. The wake is " +
+                "stored in the queen's own project and delivered only to the queen; the watched lead is read, never " +
+                "typed into. Mutually exclusive with agents and scope; refuses project_id and deliver_to."),
             deliver_to: agentRefParam.optional().describe("Deliver to a spawned agent instead of this session."),
             project_id: projectIdParam,
         },
         outputSchema: {
             status: z.literal("already_satisfied").optional(),
+            lead_watch: z.record(z.string(), z.unknown()).optional(),
             wake_id: idParam.optional(),
             scope: z.literal("project").optional(),
             standing: z.boolean().optional(),
@@ -270,13 +388,18 @@ export function registerWakes(server) {
     }, (args) => run(() => {
         rejectUnsafeBody(args.body);
         const projectId = effectiveProjectId(args.project_id);
-        if ((args.agents == null) === (args.scope == null)) {
-            throw new Error("wake_when_idle needs exactly one of agents=[...] (a one-shot over a named list) or " +
-                'scope="project" (a standing watch over this project\'s crew). ' +
-                (args.agents == null
-                    ? "You passed neither."
-                    : "You passed both, and they mean different things: a standing watch computes its own " +
-                        "membership every tick, so the list would be ignored."));
+        const selectors = [
+            args.agents != null && "agents",
+            args.scope != null && "scope",
+            args.lead_project_id != null && "lead_project_id",
+        ].filter((x) => x !== false);
+        if (selectors.length !== 1) {
+            throw new Error("wake_when_idle needs exactly one of agents=[...] (a one-shot over a named list), " +
+                'scope="project" (a standing watch over this project\'s crew), or lead_project_id (the queen ' +
+                "waiting on another project's lead). " +
+                (selectors.length === 0
+                    ? "You passed none."
+                    : `You passed ${selectors.length === 2 ? "both" : "all of"} ${selectors.join(" and ")}, and they mean different things.`));
         }
         if (args.scope != null && args.mode != null) {
             throw new Error(`mode="${args.mode}" has no meaning for a standing watch: a standing watch reports EACH crew ` +
@@ -285,14 +408,17 @@ export function registerWakes(server) {
         }
         if (args.scope != null)
             return createStandingWatch(projectId, args);
+        if (args.lead_project_id != null)
+            return createLeadWatch(args.lead_project_id, args);
         const mode = args.mode ?? "any";
         const watched = (args.agents ?? []).map((ref) => resolveAgentRef(projectId, ref));
         const leadWatched = watched.find((a) => a.kind === LEAD_KIND);
         if (leadWatched) {
-            throw new Error(`Agent ${leadWatched.id} ("${leadWatched.name}") is this project's lead session, which has no ` +
-                "idle/working state channel: its hook writes only agent_state_log, never agent_state. " +
-                "wake_when_idle refuses a lead target; it could only ever fire at max_wait_seconds, reported " +
-                "as a timeout instead of the failure it actually is.");
+            throw new Error(`Agent ${leadWatched.id} ("${leadWatched.name}") is this project's lead session, and agents=[...] ` +
+                "watches worker state, which a lead does not write: its hook never moves agent_state. " +
+                "wake_when_idle refuses a lead target in agents=[...]; it could only ever fire at max_wait_seconds, " +
+                "reported as a timeout instead of the failure it actually is. A lead's turn has its own channel, " +
+                "which only the queen may watch, with lead_project_id=<that lead's project id>.");
         }
         const delivery = resolveDelivery(projectId, args.deliver_to);
         const snapshot = liveTargets();
@@ -311,24 +437,26 @@ export function registerWakes(server) {
             }
         }
         const maxWait = args.max_wait_seconds ?? 900;
-        const info = db
-            .prepare(`INSERT INTO wakes (project_id, owner, body, kind, watch, deliver_actor, deliver_pane,
-               max_wait_at)
-             VALUES (?, ?, ?, ?, ?, ?, ?, datetime('now', printf('+%d seconds', ?)))`)
-            .run(projectId, currentActor(), args.body, `idle_${mode}`, JSON.stringify(watched.map((a) => a.id)), delivery.actor, delivery.pane, maxWait);
-        return {
-            wake_id: Number(info.lastInsertRowid),
-            mode,
-            watching: watched.map((a) => {
-                const { state, ...provenance } = deriveProvenance(a, summaryLiveness(a, snapshot));
-                return { agent_id: a.id, name: a.name, state, provenance };
-            }),
-            max_wait_seconds: maxWait,
-            deliver_to: delivery.actor,
-            note: mode === "any"
-                ? "Fires on the next fresh idle transition; agents already idle now do not count."
-                : "Fires when all watched agents are idle.",
-        };
+        return commitQueenStateWrite("wake_when_idle", projectId, args, () => {
+            const info = db
+                .prepare(`INSERT INTO wakes (project_id, owner, body, kind, watch, deliver_actor, deliver_pane,
+                 max_wait_at)
+               VALUES (?, ?, ?, ?, ?, ?, ?, datetime('now', printf('+%d seconds', ?)))`)
+                .run(projectId, currentActor(), args.body, `idle_${mode}`, JSON.stringify(watched.map((a) => a.id)), delivery.actor, delivery.pane, maxWait);
+            return {
+                wake_id: Number(info.lastInsertRowid),
+                mode,
+                watching: watched.map((a) => {
+                    const { state, ...provenance } = deriveProvenance(a, summaryLiveness(a, snapshot));
+                    return { agent_id: a.id, name: a.name, state, provenance };
+                }),
+                max_wait_seconds: maxWait,
+                deliver_to: delivery.actor,
+                note: mode === "any"
+                    ? "Fires on the next fresh idle transition; agents already idle now do not count."
+                    : "Fires when all watched agents are idle.",
+            };
+        });
     }));
     server.registerTool("wake_get", {
         description: "Read one wake-up by id, in this project, with its UNTRUNCATED body. wake_list truncates " +
@@ -416,12 +544,14 @@ export function registerWakes(server) {
             params.push(args.delay_seconds);
         }
         params.push(args.wake_id, projectId, currentActor());
-        const row = db
-            .prepare(`UPDATE wakes SET ${sets.join(", ")}
-             WHERE id = ? AND project_id = ? AND owner = ? AND parent_wake_id IS NULL AND ${ACTIVE_TIMER_WHERE}
-             RETURNING due_at`)
-            .get(...params);
-        return { wake_id: args.wake_id, updated: row !== undefined, due_at: row?.due_at ?? null };
+        return commitQueenStateWrite("wake_update", projectId, args, () => {
+            const row = db
+                .prepare(`UPDATE wakes SET ${sets.join(", ")}
+               WHERE id = ? AND project_id = ? AND owner = ? AND parent_wake_id IS NULL AND ${ACTIVE_TIMER_WHERE}
+               RETURNING due_at`)
+                .get(...params);
+            return { wake_id: args.wake_id, updated: row !== undefined, due_at: row?.due_at ?? null };
+        });
     }));
     server.registerTool("wake_cancel", {
         description: "Cancel a pending wake-up you own, or - if you are a running lead - any pending wake-up in this " +
@@ -448,22 +578,24 @@ export function registerWakes(server) {
     }, (args) => run(() => {
         const projectId = effectiveProjectId(args.project_id);
         const isLead = isRunningLeadActor(currentActor());
-        const info = isLead
-            ? db
-                .prepare(`UPDATE wakes SET cancelled_at = datetime('now')
-                 WHERE id = ? AND project_id = ? AND cancelled_at IS NULL`)
-                .run(args.wake_id, projectId)
-            : db
-                .prepare(`UPDATE wakes SET cancelled_at = datetime('now')
-                 WHERE id = ? AND project_id = ? AND owner = ? AND cancelled_at IS NULL`)
-                .run(args.wake_id, projectId, currentActor());
-        const notices = info.changes > 0
-            ? db
-                .prepare(`UPDATE wakes SET cancelled_at = datetime('now')
-                   WHERE parent_wake_id = ? AND cancelled_at IS NULL AND fired_at IS NULL`)
-                .run(args.wake_id).changes
-            : 0;
-        return { wake_id: args.wake_id, cancelled: info.changes > 0, cancelled_notices: notices };
+        return commitQueenStateWrite("wake_cancel", projectId, args, () => {
+            const info = isLead
+                ? db
+                    .prepare(`UPDATE wakes SET cancelled_at = datetime('now')
+                   WHERE id = ? AND project_id = ? AND cancelled_at IS NULL`)
+                    .run(args.wake_id, projectId)
+                : db
+                    .prepare(`UPDATE wakes SET cancelled_at = datetime('now')
+                   WHERE id = ? AND project_id = ? AND owner = ? AND cancelled_at IS NULL`)
+                    .run(args.wake_id, projectId, currentActor());
+            const notices = info.changes > 0
+                ? db
+                    .prepare(`UPDATE wakes SET cancelled_at = datetime('now')
+                     WHERE parent_wake_id = ? AND cancelled_at IS NULL AND fired_at IS NULL`)
+                    .run(args.wake_id).changes
+                : 0;
+            return { wake_id: args.wake_id, cancelled: info.changes > 0, cancelled_notices: notices };
+        });
     }));
     server.registerTool("wake_list", {
         description: "List pending wake-ups in this project, plus recently_delivered: the last " +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cmgmyr/hive",
-  "version": "1.3.0",
+  "version": "1.4.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": {
@@ -47,15 +47,15 @@
     "coordination"
   ],
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@modelcontextprotocol/sdk": "^1.30.1",
     "better-sqlite3": "^13.0.3",
-    "smol-toml": "^1.8.0",
+    "smol-toml": "^1.9.0",
     "yaml": "^2.9.1",
     "zod": "^4.6.5"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^9.6.0",
-    "@types/node": "^26.6.2",
+    "@types/node": "^26.6.3",
     "typescript": "^7.0.2"
   },
   "allowScripts": {

package/profiles/orchestration/worker.md

@@ -7,7 +7,7 @@ Coordinate through the hive MCP tools:
 - pad_list / pad_read for the shared plan and findings. Record decisions there.
 - todo_list(is_blocked=false, status="open") for dispatchable work; set status to in_progress while working.
 - todo_comment for handoffs (changed files, tests run, remaining risk), then todo_complete.
-- lease_acquire before editing shared file areas; leases expire on their own.
+- lease_acquire before changing state another session can also change (a shared checkout, a dev database, a port); files in a directory only you work in need none. Leases expire on their own.
 <!--if:primary_root-->
 The primary checkout is at {{primary_root}} - untracked project files (a session corpus, local notes) live there, not in your worktree, if this project keeps any.
 <!--end-->

package/profiles/queen/posture.md

@@ -0,0 +1,31 @@
+You are the queen: the lead of hive's own queen home, started by `hive queen`.
+Every other lead owns one project. You watch all of them and steer; you do not
+do their work.
+
+- Read any registered project. `hive portfolio` gives one row per project;
+  pad_read, todo_list, todo_get and agent_status with that project's
+  project_id give the detail. Read fresh before you answer: a row you read an
+  hour ago is not the state now.
+- Always pass project_id to reach another project; never project_select,
+  which hive refuses for the queen.
+- Write into another project only through its lead. hive lets you do exactly
+  this there, and refuses the rest with QUEEN_CROSS_PROJECT_WRITE_REFUSED:
+  - todo_create and todo_comment, to hand work or a question to that project;
+  - wake_set and wake_when_idle with deliver_to set to that project's running
+    lead, and wake_update or wake_cancel on a wake of yours addressed to it;
+  - wake_when_idle with lead_project_id set to a project's id, to be woken
+    when that project's lead ends a turn;
+  - agent_send text (never keys) to that project's running lead;
+  - `hive lead <path>` to start a project's lead when it has none.
+  Pads, todo status, kv, leases and workers in another project belong to its
+  lead. Ask; do not reach in.
+- queen_audit_list (or `hive queen-audit`) lists your confirmed writes into
+  other projects, newest first.
+- Your own home is an ordinary project. Pads, todos and workers here are
+  yours, and workers you spawn stay locked to it.
+- Carry a short label with any id you show anyone, and name its project:
+  "todo 318 in api (give todos a slug)", not "todo 318". Your reader is
+  rarely standing in that project.
+- Anything outward-facing (pushes, published PRs, anything that leaves the
+  machine) waits for explicit human approval.
+- When the human asks how work runs here, read `hive runbook`.

package/profiles/queen/runbook.md

@@ -0,0 +1,26 @@
+RUNBOOK - how the queen works. This is hive's skeleton, not your process.
+Fork it and fill it in:
+
+    hive profile fork queen runbook.md
+
+Angle brackets are yours to replace.
+
+WHAT THE QUEEN IS FOR
+<the questions you bring to the queen rather than to a project's lead>
+
+READING THE PORTFOLIO
+Start from `hive portfolio`. It is deterministic and read-only: lead state,
+workers by state, todo counts, needs-human todos and wakes, per project.
+Open a project's pads and todos by project_id only when a row needs it.
+
+ROUTING WORK
+A finding about another project becomes a todo in that project
+(todo_create with its project_id), or a comment on the todo it concerns.
+Tell its lead with agent_send text or a wake addressed to that lead. The lead
+decides what happens next; the queen does not edit its board.
+
+STARTING A LEAD
+<when a project with no running lead should get one: hive lead <path>>
+
+ON A SCHEDULE
+<the check-ins you want, set with wake_set on your own pane>