@cmgmyr/hive 1.2.2 → 1.4.0

package/dist/globalConfig.js

@@ -0,0 +1,247 @@
+import { randomUUID } from "node:crypto";
+import { chmodSync, closeSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { isMap, parse, parseDocument } from "yaml";
+import { storeDir } from "./dataDir.js";
+import { errorMessage } from "./result.js";
+export const ATTACH_MODES = ["auto", "raw", "control"];
+export const AUTO_ATTACH_MODES = ["auto", "on", "off"];
+export function isAttachMode(value) {
+    return ATTACH_MODES.includes(value);
+}
+export function isAutoAttach(value) {
+    return AUTO_ATTACH_MODES.includes(value);
+}
+export function globalConfigPath() {
+    return join(storeDir(), "hive.yml");
+}
+function isMapping(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+export function isEmptyYamlDocument(text) {
+    return text.split(/\r?\n/).every((line) => /^\s*(?:#.*)?$/.test(line));
+}
+function readLayer(path, kind, warnings) {
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            warnings.push(`${path}: could not read configuration: ${errorMessage(error)}`);
+        }
+        return null;
+    }
+    let value;
+    try {
+        value = kind === "yaml" ? parse(text) : JSON.parse(text);
+    }
+    catch (error) {
+        warnings.push(`${path}: ${kind === "yaml" ? "hive.yml is not valid YAML" : "config.json is not valid JSON"}: ${errorMessage(error)}`);
+        return null;
+    }
+    if (kind === "yaml" && value == null && isEmptyYamlDocument(text))
+        return null;
+    if (!isMapping(value)) {
+        warnings.push(`${path}: ${kind === "yaml" ? "configuration must be a YAML mapping." : "config.json must be a JSON object."}`);
+        return null;
+    }
+    return value;
+}
+export function readGlobalConfig() {
+    const dir = storeDir();
+    const warnings = [];
+    const root = readLayer(join(dir, "hive.yml"), "yaml", warnings);
+    const legacy = readLayer(join(dir, "config.json"), "json", warnings) ?? {};
+    return { root, legacy, warnings };
+}
+function readEditableDocument(path, allowMissing) {
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (allowMissing && error.code === "ENOENT")
+            return parseDocument("");
+        throw new Error(`${path}: could not read hive.yml: ${errorMessage(error)}`);
+    }
+    const document = parseDocument(text);
+    if (document.errors.length > 0) {
+        throw new Error(`${path}: hive.yml is not valid YAML: ${document.errors.map(errorMessage).join("; ")}`);
+    }
+    if (!isMap(document.contents))
+        throw new Error(`${path}: hive.yml must be a YAML mapping.`);
+    return document;
+}
+function writeAtomicYaml(path, text) {
+    let mode = 0o600;
+    try {
+        mode = statSync(path).mode & 0o777;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const candidate = join(dirname(path), `.${basename(path)}.${process.pid}.${randomUUID()}.tmp`);
+    let temp = null;
+    let fd = null;
+    try {
+        fd = openSync(candidate, "wx", 0o600);
+        temp = candidate;
+        writeFileSync(fd, text, { encoding: "utf8" });
+        closeSync(fd);
+        fd = null;
+        chmodSync(candidate, mode);
+        renameSync(candidate, path);
+        temp = null;
+    }
+    finally {
+        if (fd !== null) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+            }
+        }
+        if (temp !== null) {
+            try {
+                unlinkSync(temp);
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+        }
+    }
+}
+function updateGlobalDocument(dir, update) {
+    mkdirSync(dir, { recursive: true });
+    const path = join(dir, "hive.yml");
+    const document = readEditableDocument(path, true);
+    if (!update(document))
+        return false;
+    let text;
+    try {
+        text = document.toString();
+    }
+    catch (error) {
+        throw new Error(`${path}: could not serialize hive.yml: ${errorMessage(error)}`);
+    }
+    try {
+        writeAtomicYaml(path, text);
+    }
+    catch (error) {
+        throw new Error(`${path}: could not write hive.yml: ${errorMessage(error)}`);
+    }
+    return true;
+}
+export function writeGlobalConfigKey(key, value) {
+    const dir = storeDir();
+    updateGlobalDocument(dir, (document) => {
+        document.set(key, value);
+        return true;
+    });
+}
+export function migrateLegacyConfig() {
+    const dir = storeDir();
+    const legacyPath = join(dir, "config.json");
+    const archivePath = `${legacyPath}.migrated`;
+    const globalPath = join(dir, "hive.yml");
+    const refusal = (path, warning) => ({
+        migrated: false,
+        notice: null,
+        warnings: [`${path}: ${warning}`],
+    });
+    let legacyText;
+    try {
+        legacyText = readFileSync(legacyPath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { migrated: false, notice: null, warnings: [] };
+        return refusal(legacyPath, `could not read config.json: ${errorMessage(error)}`);
+    }
+    try {
+        lstatSync(archivePath);
+        return refusal(legacyPath, `archive ${archivePath} already exists; refusing to overwrite it.`);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            return refusal(archivePath, `could not check migration archive: ${errorMessage(error)}`);
+        }
+    }
+    let legacy;
+    try {
+        const raw = JSON.parse(legacyText);
+        if (!isMapping(raw))
+            return refusal(legacyPath, "config.json must be a JSON object.");
+        legacy = raw;
+    }
+    catch (error) {
+        return refusal(legacyPath, `config.json is not valid JSON: ${errorMessage(error)}`);
+    }
+    try {
+        updateGlobalDocument(dir, (document) => {
+            let changed = false;
+            for (const [key, value] of Object.entries(legacy)) {
+                if (key === "review_tags" || document.has(key))
+                    continue;
+                document.set(key, value);
+                changed = true;
+            }
+            return changed;
+        });
+    }
+    catch (error) {
+        const message = errorMessage(error);
+        const warning = message.startsWith(`${globalPath}:`)
+            ? message
+            : `${globalPath}: could not update hive.yml: ${message}`;
+        return { migrated: false, notice: null, warnings: [warning] };
+    }
+    try {
+        renameSync(legacyPath, archivePath);
+    }
+    catch (error) {
+        return refusal(legacyPath, `could not archive config.json as ${archivePath}: ${errorMessage(error)}`);
+    }
+    return {
+        migrated: true,
+        notice: `hive: migrated ${legacyPath} into ${globalPath}; original saved as ${archivePath}.`,
+        warnings: [],
+    };
+}
+export function resolveAttachSetting(key, global, legacy, warnings) {
+    const mode = key === "attach";
+    const env = mode
+        ? isAttachMode(process.env.HIVE_ATTACH_MODE) ? process.env.HIVE_ATTACH_MODE : null
+        : process.env.HIVE_AUTO_ATTACH === "0"
+            ? "off"
+            : isAutoAttach(process.env.HIVE_AUTO_ATTACH) ? process.env.HIVE_AUTO_ATTACH : null;
+    if (env != null)
+        return mode ? { mode: env, source: "env" } : { value: env, source: "env" };
+    const path = globalConfigPath();
+    if (global && Object.hasOwn(global, key)) {
+        const value = global[key];
+        if (value == null)
+            return mode ? { mode: "auto", source: "global" } : { value: "auto", source: "global" };
+        if (mode ? isAttachMode(value) : isAutoAttach(value)) {
+            return mode ? { mode: value, source: "global" } : { value: value, source: "global" };
+        }
+        warnings.push(`${path}: ${key} must be one of ${(mode ? ["auto", "raw", "control"] : ["auto", "on", "off"]).join(", ")}; ignoring "${String(value)}".`);
+        return mode ? { mode: "auto", source: "built-in" } : { value: "auto", source: "built-in" };
+    }
+    if (Object.hasOwn(legacy, key)) {
+        const value = legacy[key];
+        if (value == null)
+            return mode ? { mode: "auto", source: "global" } : { value: "auto", source: "global" };
+        if (mode ? isAttachMode(value) : isAutoAttach(value)) {
+            return mode ? { mode: value, source: "global" } : { value: value, source: "global" };
+        }
+        warnings.push(`${path.replace(/hive\.yml$/, "config.json")}: ${key} has an invalid value; ignoring it.`);
+    }
+    return mode ? { mode: "auto", source: "built-in" } : { value: "auto", source: "built-in" };
+}

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
@@ -171,3 +173,11 @@ export function transcriptDirFor(command) {
 export function hasTranscriptSignal(row) {
     return transcriptDirFor(row.command) || row.transcript_path !== "";
 }
+export function readOnlyExtraArgsAllowed(harness, args = []) {
+    const allowlist = {
+        codex: { flag: "-c", value: /^model_reasoning_effort=(low|medium|high|xhigh)$/ },
+        claude: { flag: "--effort", value: /^(low|medium|high|xhigh|max)$/ },
+    };
+    const allowed = allowlist[harness];
+    return allowed != null && args.length % 2 === 0 && args.every((arg, index) => index % 2 === 0 ? arg === allowed.flag : allowed.value.test(arg));
+}

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
@@ -126,7 +128,7 @@ If the human asks to change how work runs here, that is an edit to the
 runbook (fork it first), not a pad write.`,
     agents: `AGENTS — spawn and drive worker sessions in tmux
 
-  agent_spawn(name?, model?, command?, extra_args?, cwd?, placement?, layout?) —
+  agent_spawn(name?, model?, command?, extra_args?, read_only?, cwd?, placement?, layout?) —
     start a worker (default command: claude) in session hive-main.
     placement="split" (default) tiles the worker as a pane in the lead's
     window so the whole crew shares one screen; placement="window" gives it
@@ -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
@@ -246,7 +254,8 @@ Every pad, todo, kv entry, and lease belongs to one project (a directory).
   project_select(project_id) — set this session's default scope
   project_prune() — 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
 
 Resolution order: explicit project_id argument, then session selection, then
 working-directory auto-detection. When the working directory matches no
@@ -262,7 +271,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 +359,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/hooks.js

@@ -39,7 +39,8 @@ export function ensureWorkerHooksFile(agentId, options) {
     const settings = {
         ...stateHookSettings(),
         statusLine: statusLineEntry(effectiveClaudeStatusLine(worker.cwd)),
-        permissions: { deny: ["SendMessage", "ListAgents"] },
+        permissions: { deny: ["SendMessage", "ListAgents", ...(options.readOnly ? ["Edit", "Write", "NotebookEdit"] : [])] },
+        ...(options.readOnly ? { sandbox: { enabled: true, failIfUnavailable: true, autoAllowBashIfSandboxed: true, allowUnsandboxedCommands: false, filesystem: { denyWrite: ["//"] } } } : {}),
         crossSessionInbound: "refuse",
     };
     if (options.includePostToolUse)

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

@@ -1,8 +1,8 @@
 import { execFileSync } from "node:child_process";
-import { existsSync, realpathSync } from "node:fs";
-import { join } from "node:path";
+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;
@@ -97,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)" };
@@ -116,33 +128,25 @@ export async function evaluate(cwd, opts = {}) {
     catch {
         return { fired: false, reason: "cwd does not exist" };
     }
-    if (!existsSync(join(dir, "hive.yml")))
-        return { fired: false, reason: "no hive.yml here" };
-    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 });
-    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);
@@ -150,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");
@@ -168,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");

package/dist/leadState.js

@@ -0,0 +1,63 @@
+import { db } from "./db.js";
+import { FIRST_MESSAGE_SHA_ENV, firstMessageDigest } from "./firstMessage.js";
+export function readLeadTurnState(agentId) {
+    return db.prepare("SELECT * FROM lead_turn_state WHERE agent_id = ?").get(agentId) ?? null;
+}
+function isHiveFirstMessage(payload) {
+    if (typeof payload.prompt !== "string")
+        return false;
+    const prompt = payload.prompt.trim();
+    const launched = process.env[FIRST_MESSAGE_SHA_ENV];
+    return !!launched && firstMessageDigest(prompt) === launched;
+}
+// "idle" means the lead's turn ended after a prompt hive did not type itself, in this pane launch
+// and this session. It never means the lead finished all its work.
+export function nextLeadTurn(cur, panePid, event, payload, subagentsLive) {
+    const sessionId = typeof payload.session_id === "string" ? payload.session_id : "";
+    if (sessionId === "")
+        return null;
+    const sameEpoch = cur !== null && cur.pane_pid === panePid && cur.session_id === sessionId;
+    const base = sameEpoch
+        ? { pane_pid: panePid, session_id: sessionId, state: cur.state, idle_seq: cur.idle_seq }
+        : { pane_pid: panePid, session_id: sessionId, state: "unknown", idle_seq: cur?.idle_seq ?? 0 };
+    switch (event) {
+        case "prompt":
+            return isHiveFirstMessage(payload) ? base : { ...base, state: "working" };
+        case "stop":
+            if (base.state !== "working" || subagentsLive())
+                return base;
+            return { ...base, state: "idle", idle_seq: base.idle_seq + 1 };
+        case "session_end":
+            if (cur === null || cur.session_id !== sessionId)
+                return null;
+            return { pane_pid: cur.pane_pid, session_id: sessionId, state: "unknown", idle_seq: cur.idle_seq };
+        default:
+            return null;
+    }
+}
+const applyInTransaction = db.transaction((agentId, panePid, event, payload, subagentsLive) => {
+    const cur = readLeadTurnState(agentId);
+    const next = nextLeadTurn(cur, panePid, event, payload, subagentsLive);
+    if (next === null)
+        return;
+    if (cur !== null &&
+        cur.pane_pid === next.pane_pid &&
+        cur.session_id === next.session_id &&
+        cur.state === next.state &&
+        cur.idle_seq === next.idle_seq) {
+        return;
+    }
+    db.prepare(`INSERT INTO lead_turn_state (agent_id, pane_pid, session_id, state, idle_seq, last_event, changed_at)
+       VALUES (?, ?, ?, ?, ?, ?, strftime('%Y-%m-%d %H:%M:%f', 'now'))
+       ON CONFLICT(agent_id) DO UPDATE SET pane_pid = excluded.pane_pid, session_id = excluded.session_id,
+         state = excluded.state, idle_seq = excluded.idle_seq, last_event = excluded.last_event,
+         changed_at = excluded.changed_at`).run(agentId, next.pane_pid, next.session_id, next.state, next.idle_seq, event);
+});
+export function applyLeadHook(actorId, event, payload, subagentsLive) {
+    const lead = db
+        .prepare("SELECT id, pane_pid FROM agents WHERE actor_id = ? AND kind = 'lead' AND status = 'running' ORDER BY id DESC LIMIT 1")
+        .get(actorId);
+    if (!lead)
+        return;
+    applyInTransaction.immediate(lead.id, lead.pane_pid, event, payload, subagentsLive);
+}