@cmgmyr/hive 1.3.0 → 1.5.0

package/dist/context.js

@@ -1,8 +1,10 @@
 import { execFileSync } from "node:child_process";
-import { realpathSync } from "node:fs";
+import { lstatSync, realpathSync } from "node:fs";
 import { userInfo } from "node:os";
-import { basename, dirname, resolve, sep } from "node:path";
+import { basename, dirname, join, resolve, sep } from "node:path";
+import { storeDir } from "./dataDir.js";
 import { db } from "./db.js";
+import { LEAD_KIND } from "./spawn.js";
 let selectedId = null;
 let cachedActorId = null;
 let lastTouchMs = 0;
@@ -254,3 +256,192 @@ export function trySelectedProject() {
         return null;
     }
 }
+export const QUEEN_PROFILE = "queen";
+export function queenHomeDir() {
+    return join(storeDir(), "queen");
+}
+function queenHomeProject() {
+    const home = queenHomeDir();
+    try {
+        if (lstatSync(home).isSymbolicLink())
+            return null;
+        return getProjectByPath(realpathSync(home)) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function queenProjectId() {
+    if (projectLock)
+        return null;
+    const actorId = process.env.HIVE_AGENT_ID;
+    if (!actorId)
+        return null;
+    const home = queenHomeProject();
+    if (!home)
+        return null;
+    const row = db
+        .prepare("SELECT 1 FROM agents WHERE actor_id = ? AND project_id = ? AND kind = ? AND status = 'running'")
+        .get(actorId, home.id, LEAD_KIND);
+    return row ? home.id : null;
+}
+export function isQueenLead() {
+    return queenProjectId() !== null;
+}
+export function captureQueenWriteIdentity(targetProjectId) {
+    const home = queenProjectId();
+    if (home === null || home === targetProjectId)
+        return null;
+    return { actor_id: process.env.HIVE_AGENT_ID, home_project_id: home };
+}
+export const QUEEN_REACH = {
+    whoami: "read",
+    help: "read",
+    project_list: "read",
+    pad_list: "read",
+    pad_read: "read",
+    todo_list: "read",
+    todo_get: "read",
+    kv_get: "read",
+    kv_list: "read",
+    wake_get: "read",
+    wake_list: "read",
+    agent_list: "read",
+    agent_status: "read",
+    agent_output: "read",
+    agent_message_get: "read",
+    queen_audit_list: "read",
+    todo_create: "todo",
+    todo_comment: "todo",
+    wake_set: "lead_wake",
+    wake_when_idle: "lead_wake",
+    wake_update: "owned_lead_wake",
+    wake_cancel: "owned_lead_wake",
+    agent_send: "lead_text",
+    pad_write: "home",
+    pad_append: "home",
+    pad_edit: "home",
+    pad_archive: "home",
+    pad_delete: "home",
+    todo_update: "home",
+    todo_archive: "home",
+    todo_complete: "home",
+    todo_block: "home",
+    todo_unblock: "home",
+    kv_set: "home",
+    kv_delete: "home",
+    lease_acquire: "home",
+    lease_release: "home",
+    agent_spawn: "home",
+    agent_resume: "home",
+    agent_park: "home",
+    agent_rename: "home",
+    agent_close: "home",
+    project_select: "select",
+    project_add: "global",
+    project_prune: "prune",
+    actor_prune: "global",
+    "hive lead": "spin_up",
+    "hive queen-audit": "read",
+    "hive project rm": "prune",
+    "hive init": "home",
+    "hive attach": "home",
+    "hive next": "home",
+    "hive start": "home",
+    "hive stop": "home",
+    "hive show": "home",
+    "hive hide": "home",
+    "hive pad --save": "home",
+};
+export const QUEEN_REFUSAL = "QUEEN_CROSS_PROJECT_WRITE_REFUSED";
+function runningLead(projectId) {
+    return db
+        .prepare("SELECT id, actor_id, name FROM agents WHERE project_id = ? AND kind = ? AND status = 'running' ORDER BY id LIMIT 1")
+        .get(projectId, LEAD_KIND);
+}
+function namesLead(ref, lead) {
+    return typeof ref === "number" ? ref === lead.id : ref === lead.name;
+}
+function foreignWriteProblem(reach, targetProjectId, args) {
+    switch (reach) {
+        case "spin_up":
+        case "todo":
+        case "prune":
+            return null;
+        case "lead_wake": {
+            if (args.scope !== undefined)
+                return "a standing watch in another project belongs to its lead";
+            const lead = runningLead(targetProjectId);
+            if (!lead)
+                return "that project has no running lead to address";
+            if (!namesLead(args.deliver_to, lead)) {
+                return `deliver_to must name that project's running lead ("${lead.name}" or agent id ${lead.id})`;
+            }
+            return null;
+        }
+        case "owned_lead_wake": {
+            const lead = runningLead(targetProjectId);
+            if (!lead)
+                return "that project has no running lead, so no wake of yours there is still addressed to one";
+            const wake = db
+                .prepare("SELECT owner, deliver_actor FROM wakes WHERE id = ? AND project_id = ?")
+                .get(args.wake_id, targetProjectId);
+            if (!wake || wake.owner !== process.env.HIVE_AGENT_ID || wake.deliver_actor !== lead.actor_id) {
+                return "only a wake you set there, addressed to that project's current running lead, can be changed";
+            }
+            return null;
+        }
+        case "lead_text": {
+            if (args.keys !== undefined)
+                return "keys can interrupt a lead mid-turn; send text instead";
+            const lead = runningLead(targetProjectId);
+            if (!lead)
+                return "that project has no running lead to address";
+            if (!namesLead(args.agent_id ?? args.name, lead)) {
+                return `the recipient must be that project's running lead ("${lead.name}" or agent id ${lead.id})`;
+            }
+            return null;
+        }
+        case "home":
+            return "that belongs to the project's own lead";
+        case "select":
+            return "a selection would redirect every later call that omits project_id; pass project_id on each call instead";
+    }
+}
+// targetProjectId null means the operation has no single project (a store-wide sweep, an unregistered path).
+export function assertQueenCrossProjectWrite(operation, targetProjectId, args) {
+    const home = queenProjectId();
+    if (home === null)
+        return;
+    const reach = QUEEN_REACH[operation];
+    if (reach === "read")
+        return;
+    const problem = reach === undefined
+        ? "hive has not classified this operation for the queen, so it refuses by default"
+        : reach === "global"
+            ? "it changes the whole store, not one project"
+            : targetProjectId === home
+                ? null
+                : targetProjectId === null
+                    ? "it names no registered project"
+                    : foreignWriteProblem(reach, targetProjectId, args);
+    if (problem)
+        throw queenRefusal(operation, targetProjectId, problem);
+}
+export function assertQueenToolCall(tool, args) {
+    if (!isQueenLead())
+        return;
+    const reach = QUEEN_REACH[tool];
+    if (reach === "read")
+        return;
+    const override = typeof args.project_id === "number" ? args.project_id : undefined;
+    const target = reach === undefined || reach === "global" ? null : effectiveProjectId(override);
+    assertQueenCrossProjectWrite(tool, target, args);
+}
+function queenRefusal(operation, targetProjectId, problem) {
+    const target = targetProjectId === null ? null : getProject(targetProjectId);
+    const where = target ? `in project ${target.id} ("${target.name}")` : "outside the queen's own project";
+    return new Error(`${QUEEN_REFUSAL}: the queen cannot run ${operation} ${where}: ${problem}. Into another project the ` +
+        "queen may only todo_create, todo_comment, send text or wakes to its running lead, start its lead " +
+        "with `hive lead <path>`, and run project_prune or `hive project rm` on it. Everything else there is its lead's to do.");
+}

package/dist/db.js

@@ -372,6 +372,42 @@ CREATE INDEX idx_wakes_parent ON wakes(parent_wake_id) WHERE parent_wake_id IS N
     `
 ALTER TABLE agents ADD COLUMN model TEXT;
 ALTER TABLE agents ADD COLUMN extra_args TEXT;
+`,
+    `
+CREATE TABLE lead_turn_state (
+  agent_id INTEGER PRIMARY KEY REFERENCES agents(id) ON DELETE CASCADE,
+  pane_pid TEXT NOT NULL DEFAULT '',
+  session_id TEXT NOT NULL DEFAULT '',
+  state TEXT NOT NULL DEFAULT 'unknown' CHECK (state IN ('unknown', 'working', 'idle')),
+  idle_seq INTEGER NOT NULL DEFAULT 0,
+  last_event TEXT NOT NULL DEFAULT '',
+  changed_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%d %H:%M:%f', 'now'))
+);
+
+CREATE TABLE lead_idle_subscriptions (
+  wake_id INTEGER PRIMARY KEY REFERENCES wakes(id) ON DELETE CASCADE,
+  target_project_id INTEGER NOT NULL,
+  agent_id INTEGER NOT NULL,
+  pane_pid TEXT NOT NULL,
+  session_id TEXT NOT NULL DEFAULT '',
+  baseline_idle_seq INTEGER NOT NULL DEFAULT 0,
+  terminal_reason TEXT
+);
+`,
+    `
+CREATE TABLE queen_audit (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  actor_id TEXT NOT NULL,
+  home_project_id INTEGER NOT NULL,
+  target_project_id INTEGER NOT NULL,
+  operation TEXT NOT NULL,
+  resource_type TEXT NOT NULL,
+  resource_id INTEGER NOT NULL CHECK(resource_id > 0),
+  summary TEXT NOT NULL CHECK(length(summary) <= 160),
+  created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%d %H:%M:%f','now')),
+  CHECK(home_project_id != target_project_id)
+);
+CREATE INDEX idx_queen_audit_target ON queen_audit(target_project_id, id);
 `,
 ];
 export function storeSchemaAhead(database) {
@@ -389,7 +425,7 @@ function readAppliedVersions() {
     return new Set(db.prepare("SELECT version FROM migrations").all().map((r) => r.version));
 }
 const MIGRATE_LOCK_MAX_ATTEMPTS = 24;
-function retryOnBusy(fn, label) {
+function retryOnBusy(fn, label, pending) {
     for (let attempt = 1;; attempt++) {
         try {
             return fn();
@@ -404,29 +440,36 @@ function retryOnBusy(fn, label) {
                     `wedged hive process and try again. Underlying error: ${errorMessage(e)}`);
             }
             else {
-                console.error(`hive: ${label} failed: ${errorMessage(e)}`);
+                console.error(`hive: ${label} failed: ${errorMessage(e)}${pending ? ` (${pending})` : ""}`);
             }
             process.exit(1);
         }
     }
 }
+function bookkeepingMissing() {
+    const names = db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name IN ('migrations', 'backup_meta')").all().length;
+    return names < 2 || db.prepare("SELECT 1 FROM backup_meta WHERE id = 1").get() === undefined;
+}
 export function migrate() {
-    retryOnBusy(() => {
-        db.exec(`CREATE TABLE IF NOT EXISTS migrations (
-      version INTEGER PRIMARY KEY,
-      applied_at TEXT NOT NULL DEFAULT (datetime('now'))
-    )`);
-        db.exec(`CREATE TABLE IF NOT EXISTS backup_meta (
-      id INTEGER PRIMARY KEY CHECK (id = 1),
-      last_attempt_at TEXT,
-      last_success_at TEXT,
-      last_error TEXT,
-      last_error_at TEXT
-    )`);
-        db.prepare("INSERT OR IGNORE INTO backup_meta (id) VALUES (1)").run();
-    }, "preparing the store's bookkeeping tables");
+    if (bookkeepingMissing()) {
+        retryOnBusy(() => {
+            db.exec(`CREATE TABLE IF NOT EXISTS migrations (
+          version INTEGER PRIMARY KEY,
+          applied_at TEXT NOT NULL DEFAULT (datetime('now'))
+        )`);
+            db.exec(`CREATE TABLE IF NOT EXISTS backup_meta (
+          id INTEGER PRIMARY KEY CHECK (id = 1),
+          last_attempt_at TEXT,
+          last_success_at TEXT,
+          last_error TEXT,
+          last_error_at TEXT
+        )`);
+            db.prepare("INSERT OR IGNORE INTO backup_meta (id) VALUES (1)").run();
+        }, "preparing the store's bookkeeping tables", "bookkeeping missing");
+    }
     const before = readAppliedVersions();
-    maybeBackupBeforeMigrations(db, dataDir, MIGRATIONS.length - before.size);
+    const pendingCount = MIGRATIONS.length - before.size;
+    maybeBackupBeforeMigrations(db, dataDir, pendingCount);
     const applyPending = db.transaction(() => {
         const applied = readAppliedVersions();
         MIGRATIONS.forEach((sql, i) => {
@@ -445,5 +488,5 @@ export function migrate() {
             db.prepare("INSERT INTO migrations (version) VALUES (?)").run(version);
         });
     });
-    retryOnBusy(() => applyPending.immediate(), "applying pending migrations");
+    retryOnBusy(() => applyPending.immediate(), "applying pending migrations", pendingCount > 0 ? `${pendingCount} migration${pendingCount === 1 ? "" : "s"} pending` : undefined);
 }

package/dist/firstMessage.js

@@ -0,0 +1,5 @@
+import { createHash } from "node:crypto";
+export const FIRST_MESSAGE_SHA_ENV = "HIVE_LEAD_FIRST_MESSAGE_SHA";
+export function firstMessageDigest(message) {
+    return createHash("sha256").update(message.trim()).digest("hex");
+}

package/dist/harnesses.js

@@ -1,4 +1,4 @@
-import { codexInputBoxState, codexPaneChoiceCheck, codexPaneHasInputBox, inputBoxState, paneChoiceCheck, paneHasInputBox, } from "./tmux.js";
+import { claudeTrailerView, codexInputBoxState, codexTrailerView, codexPaneChoiceCheck, codexPaneHasInputBox, inputBoxState, paneChoiceCheck, paneHasInputBox, } from "./tmux.js";
 export function commandHead(command) {
     return command.trim().split(/\s+/)[0] ?? "";
 }
@@ -52,10 +52,11 @@ const claudeHarness = {
     supportsResume: true,
     supportsRename: true,
     classifiesPaneScreen: true,
-    paneClassifier: { choiceCheck: paneChoiceCheck, inputBoxState, hasInputBox: paneHasInputBox },
+    paneClassifier: { choiceCheck: paneChoiceCheck, inputBoxState, hasInputBox: paneHasInputBox, trailerView: claudeTrailerView },
     hasScopes: true,
     needsHome: false,
-    initialPromptArgs: null,
+    // "--" so a message that starts with a dash is never read as a flag.
+    initialPromptArgs: (message) => ["--", message],
     // clear, other, and an unobserved value all stop nothing (todo 765; test/fixtures/hook-payloads/
     // README.md). Only these two are what Claude Code documents as the session being over for good.
     terminalSessionEndReasons: ["prompt_input_exit", "logout"],
@@ -79,11 +80,12 @@ export const codexHarness = {
         choiceCheck: codexPaneChoiceCheck,
         inputBoxState: codexInputBoxState,
         hasInputBox: codexPaneHasInputBox,
+        trailerView: codexTrailerView,
     },
     hasScopes: false,
     needsHome: true,
     // Auto-submits with no Enter; verified live on v0.149.0.
-    initialPromptArgs: (message) => [message],
+    initialPromptArgs: (message) => ["--", message],
     // Measured live on 0.151.0 (todo 782 S1): both `/quit` and Ctrl-C twice fire SessionEnd with
     // reason "other" - never claude's `prompt_input_exit` or `logout`. Codex's vocabulary is
     // disjoint from claude's, not a superset of it, so it gets its own set rather than joining

package/dist/help.js

@@ -37,7 +37,7 @@ TODOS — shared task tracking with dependencies
 KV — small shared status values (with optional TTL)
   kv_set, kv_get, kv_list, kv_delete
 
-LEASES — advisory expiring claims on shared work areas
+LEASES — advisory expiring claims on shared state
   lease_acquire, lease_release
 
 PROJECTS — scope management
@@ -97,8 +97,10 @@ Rules that keep this sane:
   - Keep worker prompts self-contained: include pad and todo ids.
   - Record every decision in the pad or a todo comment. Sessions die;
     the store survives.
-  - Take a lease (lease_acquire) before editing a shared file area; leases
-    expire so a dead session never wedges anyone.`,
+  - Take a lease (lease_acquire) before changing state another session can
+    also change: a checkout two sessions share, a dev database, a port. Files
+    in a directory only you work in, such as your own git worktree, need
+    none. Leases expire so a dead session never wedges anyone.`,
     profiles: `PROFILES — standing instructions shared across projects
 
 A profile is a named set of instructions this project runs under, named by
@@ -195,8 +197,9 @@ its turn), waiting (needs permission or input). Non-claude commands show
 
   wake_set(delay_seconds, body, deliver_to?, repeat_every_seconds?) —
     one-shot or repeating wake-up
-  wake_when_idle(agents | scope, body, mode?, max_wait_seconds?,
-    deliver_to?) — fire when workers go idle. Pass exactly one of:
+  wake_when_idle(agents | scope | lead_project_id, body, mode?,
+    max_wait_seconds?, deliver_to?) — fire when workers go idle. Pass
+    exactly one of:
       scope="project" — a STANDING watch over the crew you spawn in this project.
         It reports EACH worker as it finishes or its window dies, covers
         workers spawned after you set it, and keeps watching until
@@ -209,6 +212,11 @@ its turn), waiting (needs permission or input). Non-claude commands show
         others; mode=all fires when every watched agent is idle and returns
         already_satisfied instead of scheduling if they already are.
         Agents already idle when it was set do not count.
+      lead_project_id=<id> — QUEEN ONLY: a ONE-SHOT on another project's
+        running lead ENDING A TURN (not finishing its work). Stored in and
+        delivered to the queen's own project; refuses project_id and
+        deliver_to. A dead, reissued or restarted lead ends it with that
+        reason instead.
   wake_get(wake_id) — read one wake-up by id, with its untruncated body
     (wake_list truncates at 120 chars)
   wake_update(wake_id, delay_seconds?, body?, repeat_every_seconds?) — edit
@@ -244,9 +252,13 @@ Every pad, todo, kv entry, and lease belongs to one project (a directory).
   project_list — all registered projects plus the current selection
   project_add(path?, name?) — register a directory (defaults to cwd)
   project_select(project_id) — set this session's default scope
-  project_prune() — delete every registered project that owns no rows
+  project_prune(project_id?, confirm_name?) — delete every registered project that owns no rows
     anywhere in the store, verified individually; never your own; refuses
-    under HIVE_PROJECT_LOCK=1 since it sweeps every project, not just yours
+    under HIVE_PROJECT_LOCK=1 since it sweeps every project, not just yours.
+    With project_id, removes only that project, and only if it owns no rows.
+    With project_id and confirm_name (its exact name), removes it with every
+    row it owns after a snapshot; refuses while it has a running agent. From a
+    terminal: hive project rm <id|path> [--yes].
 
 Resolution order: explicit project_id argument, then session selection, then
 working-directory auto-detection. When the working directory matches no
@@ -262,7 +274,14 @@ Cross-project access is intentional-only. An empty result means there is
 nothing in this project; report that and stop. Reach into another project
 (project_select or a project_id override) only when the user explicitly
 names it. Set HIVE_PROJECT_LOCK=1 in a session's environment to reject
-cross-project access entirely; use it for worker sessions.`,
+cross-project access entirely; use it for worker sessions.
+
+The one standing exception is the queen: the running lead of <data dir>/queen,
+started by \`hive queen\`. It may read any registered project by project_id.
+Into another project it may write only todo_create and todo_comment, plus
+wake_set, wake_when_idle, wake_update, wake_cancel and agent_send text
+addressed to that project's running lead. Every other write there refuses
+with QUEEN_CROSS_PROJECT_WRITE_REFUSED. Workers the queen spawns stay locked.`,
     identity: `IDENTITY — who is writing
 
 Every write records an actor. Identity comes from environment variables read
@@ -343,13 +362,15 @@ todo_list without marking anything done.`,
 
 Use kv for values another session needs to discover: current branch, a port,
 a phase flag. Use pads for anything longer than a line or two.`,
-    leases: `LEASES — advisory expiring claims on shared work areas
+    leases: `LEASES — advisory expiring claims on shared state
 
   lease_acquire(key, ttl_seconds) — non-blocking; returns the holder if
     already taken; re-taking your own lease extends it
   lease_release(key)
 
 Keys are project-scoped and free-form; keep them stable and specific, like
-"file:src/api/routes.ts" or "todo:42". Leases expire on their own, so a
-crashed session never wedges the team.`,
+"checkout:main", "db:dev", "port:3000" or "todo:42". A lease tells other
+sessions the state is in use; it enforces nothing, and it cannot prevent a
+merge conflict between two branches. Leases expire on their own, so a crashed
+session never wedges the team.`,
 };

package/dist/hook.js

@@ -179,6 +179,15 @@ try {
         if (event === "prompt") {
             db.prepare(`UPDATE agents SET resumed_at = '' WHERE actor_id = ? AND kind = 'agent' AND ${awaitingFirstPromptSql("agents")}`).run(actorId);
         }
+        // A lead's turn state is its own table; agents.agent_state stays worker-only.
+        if (process.env.HIVE_LEAD === "1" && (event === "prompt" || event === "stop" || event === "session_end")) {
+            try {
+                const { applyLeadHook } = await import("./leadState.js");
+                applyLeadHook(actorId, event, readPayload(), () => waitingOnSubagents(actorId, readPayload()));
+            }
+            catch {
+            }
+        }
         if (event === "session_end") {
             try {
                 await stopProcessesForEndedLead(actorId, readPayload());

package/dist/index.js

@@ -2,6 +2,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { migrate } from "./db.js";
+import { assertQueenToolCall, isQueenLead } from "./context.js";
 import { registerAgents } from "./tools/agents.js";
 import { registerMeta } from "./tools/meta.js";
 import { registerPads } from "./tools/pads.js";
@@ -9,19 +10,23 @@ import { registerTodos } from "./tools/todos.js";
 import { registerKv } from "./tools/kv.js";
 import { registerLeases } from "./tools/leases.js";
 import { registerWakes } from "./tools/wakes.js";
+import { registerQueenAudit } from "./tools/queenAudit.js";
 import { registerPrompts } from "./prompts.js";
 import { schedulerIntervalMs, startScheduler } from "./scheduler.js";
 import { enforceStrictInput } from "./strictInput.js";
+migrate();
+const SCOPE_DISCIPLINE = isQueenLead()
+    ? "Scope discipline: you are the queen, the lead of hive's queen home. Your own project is the working directory's. You may read any registered project by passing its project_id. Into another project you may write only todo_create and todo_comment, plus wakes and agent_send text addressed to that project's running lead; every other write there refuses with QUEEN_CROSS_PROJECT_WRITE_REFUSED. See help(topic=\"projects\")."
+    : "Scope discipline: all state is project-scoped, and the current project is the working directory's. An empty result means there is nothing IN THIS PROJECT; report that and stop. Never browse other projects' state (project_id overrides, project_select) unless the user explicitly names another project and asks for it.";
 const server = enforceStrictInput(new McpServer({ name: "hive", version: "0.1.0" }, {
-    instructions: `Hive gives Claude Code sessions shared, persistent state for coordinating work on a project: pads for plans and findings, todos for tracked work with blockers, kv for small shared values, leases for claiming shared work areas, agents for spawning and directing other sessions, and wake-ups for scheduled or idle-triggered check-ins. Search for these tools when a task needs to persist past this conversation, hand off to or watch another session, or track multi-step work with dependencies.
+    instructions: `Hive gives Claude Code sessions shared, persistent state for coordinating work on a project: pads for plans and findings, todos for tracked work with blockers, kv for small shared values, leases for claiming shared state, agents for spawning and directing other sessions, and wake-ups for scheduled or idle-triggered check-ins. Search for these tools when a task needs to persist past this conversation, hand off to or watch another session, or track multi-step work with dependencies.
 Getting started:
 1. Call whoami to see your actor identity and effective project scope.
 2. Call help for an overview, or help(topic="workflow") for the lead/worker playbook.
-3. Pads hold shared plans and findings. Todos coordinate work with blockers and comments. KV holds small shared values; leases claim shared work areas and expire on their own.
+3. Pads hold shared plans and findings. Todos coordinate work with blockers and comments. KV holds small shared values; leases claim state more than one session can change and expire on their own.
 4. Before triaging or orchestrating work, read the standing process: run \`hive runbook\` in a shell. It prints the project's profile runbook, or its runbook pad when the project has no profile. Do not read the pad first; most projects with a profile have no runbook pad at all.
-Scope discipline: all state is project-scoped, and the current project is the working directory's. An empty result means there is nothing IN THIS PROJECT; report that and stop. Never browse other projects' state (project_id overrides, project_select) unless the user explicitly names another project and asks for it.`,
-}));
-migrate();
+${SCOPE_DISCIPLINE}`,
+}), assertQueenToolCall);
 registerMeta(server);
 registerAgents(server);
 registerPads(server);
@@ -29,6 +34,7 @@ registerTodos(server);
 registerKv(server);
 registerLeases(server);
 registerWakes(server);
+registerQueenAudit(server);
 registerPrompts(server);
 startScheduler(schedulerIntervalMs());
 await server.connect(new StdioServerTransport());

package/dist/kickoff.js

@@ -2,6 +2,7 @@ import { execFileSync } from "node:child_process";
 import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { cutToUnitBudget } from "./slug.js";
+import { FIRST_MESSAGE_SHA_ENV } from "./firstMessage.js";
 export const OUTPUT_BUDGET = 10_000;
 const CONTEXT_BUDGET = 6_000;
 const BOARD_BUDGET = 1_800;
@@ -96,14 +97,26 @@ async function digest(projectPath, profile, warnings) {
     lines.push("", "Standing process for this project: run `hive runbook`.");
     return truncate(lines.join("\n"), CONTEXT_BUDGET);
 }
-// Exported so src/cli.ts can hand the identical text to a codex lead as its initial CLI prompt -
-// codex's SessionStart hook rejects the whole payload if this rides inside hookSpecificOutput
-// (see the `forCodex` branch below), so a codex lead gets it a different way, not a different
-// message. Keep the two in sync by construction rather than by two literals staying equal.
-export const TRIAGE_MESSAGE = "Start with morning triage. Run `hive runbook` for this project's standing process, then " +
-    "reconcile the state hive just injected against what is really there (agent_list, todo_list, " +
-    "wake_list) and report it in a few lines. Propose today's lanes and confirm them with me before " +
-    "dispatching anything.";
+// Shared with `hive lead`, which passes the first message on the command line only when this holds.
+export async function kickoffGate(dir) {
+    const { activeProfile, DEFAULT_LEAD_BRANCHES, loadProjectYml } = await import("./projectYml.js");
+    const { profileExists } = await import("./profiles.js");
+    const { config, warnings, sources } = loadProjectYml(dir);
+    const no = (reason) => ({ ok: false, reason, warnings });
+    if (config == null)
+        return no("no hive.yml here");
+    const profile = activeProfile(config);
+    if (!profile)
+        return no("no profile in hive.yml");
+    if (!profileExists(profile))
+        return no(`profile "${profile}" is not on this machine`);
+    const branch = currentBranch(dir);
+    const leadBranches = config.lead_branches ?? DEFAULT_LEAD_BRANCHES;
+    if (branch != null && !leadBranches.includes(branch)) {
+        return no(`branch "${branch}" is not a lead branch (${leadBranches.join(", ")})`);
+    }
+    return { ok: true, config, warnings, sources, profile };
+}
 export async function evaluate(cwd, opts = {}) {
     if (process.env.HIVE_AGENT_ID && process.env.HIVE_LEAD !== "1") {
         return { fired: false, reason: "worker session (HIVE_AGENT_ID is set)" };
@@ -115,33 +128,25 @@ export async function evaluate(cwd, opts = {}) {
     catch {
         return { fired: false, reason: "cwd does not exist" };
     }
-    const { activeProfile, DEFAULT_LEAD_BRANCHES, loadProjectYml } = await import("./projectYml.js");
-    const { profileExists } = await import("./profiles.js");
-    const { config, warnings } = loadProjectYml(dir);
-    const silent = (reason) => ({ fired: false, reason, warnings });
-    if (config == null)
-        return silent("no hive.yml here");
-    const profile = activeProfile(config);
-    if (!profile)
-        return silent("no profile in hive.yml");
-    if (!profileExists(profile))
-        return silent(`profile "${profile}" is not on this machine`);
-    const branch = currentBranch(dir);
-    const leadBranches = config?.lead_branches ?? DEFAULT_LEAD_BRANCHES;
-    if (branch != null && !leadBranches.includes(branch)) {
-        return silent(`branch "${branch}" is not a lead branch (${leadBranches.join(", ")})`);
-    }
+    const gate = await kickoffGate(dir);
+    if (!gate.ok)
+        return { fired: false, reason: gate.reason, warnings: gate.warnings };
+    const { config, warnings, sources, profile } = gate;
     const context = await digest(dir, profile, warnings);
     if (context == null)
-        return silent("not a registered hive project root");
+        return { fired: false, reason: "not a registered hive project root", warnings };
     // Codex's SessionStartHookSpecificOutputWire is additionalProperties:false and permits only
     // hookEventName/additionalContext - initialUserMessage inside it fails the whole payload
     // ("SessionStart Failed"), silently dropping the board too. Measured, todo 567 comment 1864.
+    const { resolveFirstMessage } = await import("./projectYml.js");
+    const first = resolveFirstMessage(config, sources);
+    const onCommandLine = process.env.HIVE_LEAD === "1" && !!process.env[FIRST_MESSAGE_SHA_ENV];
+    const hookMessage = opts.forCodex || onCommandLine || first.message === "" ? null : first.message;
     const build = (text) => JSON.stringify({
         hookSpecificOutput: {
             hookEventName: "SessionStart",
             additionalContext: text,
-            ...(opts.forCodex ? {} : { initialUserMessage: TRIAGE_MESSAGE }),
+            ...(hookMessage === null ? {} : { initialUserMessage: hookMessage }),
         },
     });
     let payload = build(context);
@@ -149,7 +154,7 @@ export async function evaluate(cwd, opts = {}) {
         const overflow = payload.length - OUTPUT_BUDGET;
         payload = build(truncate(context, Math.max(0, context.length - overflow - 32)));
     }
-    return { fired: true, payload, warnings };
+    return { fired: true, payload, warnings, firstMessage: first };
 }
 export async function runKickoff(argv = []) {
     const explain = argv.includes("--explain");
@@ -167,6 +172,15 @@ export async function runKickoff(argv = []) {
         for (const w of result.warnings ?? [])
             console.log(`! hive.yml: ${w}`);
     if (result.fired && result.payload) {
+        if (explain && result.firstMessage) {
+            const { message, source } = result.firstMessage;
+            if (source === "unset")
+                console.log("first message: none (first_message is not set)");
+            else if (source === "empty")
+                console.log("first message: none (empty string in hive.yml)");
+            else
+                console.log(`first message (${source}): ${message}`);
+        }
         process.stdout.write(result.payload);
         if (explain)
             process.stdout.write("\n");