@cmgmyr/hive 1.3.0 → 1.4.0

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { execFileSync, spawn, spawnSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { chmodSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, unlinkSync, writeFileSync, } from "node:fs";
+import { chmodSync, existsSync, linkSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, unlinkSync, writeFileSync, } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { join, resolve, sep } from "node:path";
 import { createInterface } from "node:readline/promises";
@@ -12,16 +12,18 @@ import { claudeConfigDir } from "./claudeDir.js";
 import { ATTACH_MODES, AUTO_ATTACH_MODES, attachMode, isAttachMode, isAutoAttach, migrateLegacyConfig, resolvedAutoAttach, setAttachMode, setAutoAttach, } from "./config.js";
 import { cliPath, dispatcherDir, dispatcherPath, dispatcherScript, durabilityLines, firstHiveOnPath, linkedWorktreePin, pathAdvice, readDispatcher, } from "./dispatcher.js";
 import { codexConfigPath, codexHiveRegistrations, codexRegistrationProblem, hiveRegistrations, registrationOffer, registrationProblem, } from "./mcpConfig.js";
-import { DEFAULT_DATA_DIR } from "./dataDir.js";
+import { DEFAULT_DATA_DIR, storeDir } from "./dataDir.js";
 import { dataDir, db, migrate, storeSchemaAhead } from "./db.js";
 import { cacheIsStale, queryUpdate, readCachedUpdate, refreshUpdate, shouldAutoRefresh, updateLine } from "./updateCheck.js";
 import { checkoutUpgradeSteps, detectInstallShape, globalUpgradeSteps } from "./upgrade.js";
 import { isLowHeadroom, orphanLoginShellDetails, ptyHeadroom } from "./ptys.js";
-import { addProject, agentProjectPin, currentActor, effectiveProjectId, findProjectForCwd, getProjectByPath, gitPrimaryRoot, getProject, listProjects, registeredAncestor, takeRegistrationNotice, } from "./context.js";
+import { addProject, agentProjectPin, assertQueenCrossProjectWrite, captureQueenWriteIdentity, currentActor, effectiveProjectId, findProjectForCwd, findProjectForDir, getProjectByPath, gitPrimaryRoot, getProject, listProjects, QUEEN_PROFILE, queenHomeDir, registeredAncestor, takeRegistrationNotice, } from "./context.js";
+import { confirmQueenWrite, listQueenAudit } from "./queenAudit.js";
 import { ensureHooksFile } from "./hooks.js";
 import { errorMessage, registrationNoticeText, withTrailingNewline } from "./result.js";
-import { ACTIVE_TIMER_WHERE, dashboardFileContained, describeStall, HELD_REASON_CONVERSATION, HELD_REASON_LEAD_PANE_DEAD, HELD_REASON_UNCLASSIFIABLE_PANE_PREFIX, isUnclassifiablePaneHold, HELD_REASON_UNSUBMITTED_INPUT_PREFIX, isUnsubmittedInputHold, janitor, resolveDashboardFile, transcriptStaleness, wasHeldForPaneReissue, } from "./scheduler.js";
+import { ACTIVE_TIMER_WHERE, dashboardFileContained, describeStall, HELD_REASON_CONVERSATION, HELD_REASON_LEAD_PANE_DEAD, HELD_REASON_UNCLASSIFIABLE_PANE_PREFIX, isUnclassifiablePaneHold, HELD_REASON_UNSUBMITTED_INPUT_PREFIX, isUnsubmittedInputHold, janitor, resolveDashboardFile, generateQueenDashboardNow, transcriptStaleness, wasHeldForPaneReissue, } from "./scheduler.js";
 import { readTurnCount } from "./turnCount.js";
+import { collectPortfolio, leadText } from "./portfolio.js";
 import { STALL_BOUND_SECONDS } from "./backgroundTasks.js";
 import { probeSessionInterpreter, reexecTarget, sessionStartVerdict, } from "./sessionProbe.js";
 import { backupHealth, backupNow, backupsDir, formatBytes, listSnapshots, previewRestore, restoreSnapshot, totalSizeBytes, } from "./backup.js";
@@ -30,11 +32,11 @@ import { asNameClash, buildEnvFlags, closeAgentRow, isReservedAgentName, launchA
 import { adoptableWindow, applyLayout, claimInitialWindow, configureHiveWindow, controlModeFor, createWindow, DEFAULT_LAYOUT, describePaneChoice, ensureSession, findProjectWindow, foreignSocket, isPaneTarget, isViewSessionName, listOwnedWindows, ORPHAN_MIN_AGE_MS, orphanScratchServers, orphansWorthWarningAbout, paneIsAloneInWindow, paneVisibility, panePid, PROCESSES_LAYOUT, processesPaneTitle, processesWindowName, projectWindows, RAW_ATTACH_TMUX_CONFIG, renderAttachCommand, resolveAttachTarget, resolveInTmuxTarget, paneReissued, rowLive, rowLiveProbe, SESSION_PREFIX, appendGlobalHook, globalHooks, replaceGlobalHooks, sessionName, setPaneTitle, shellQuote, shownPaneTitle, makeProcessesWindow, tmux, TMUX_DOC, tmuxSaysNothingThere, tmuxTimeoutOverride, tmuxSocketPath, untrustedTmuxServer, waitForPaneEstablished, windowLayout, } from "./tmux.js";
 import { describeVisibility, processCounts } from "./dashboard.js";
 import { runningCommandRow, runningCommandRows, snapshotProcesses, stopAllProcesses, stopLine, stopProcess, STOP_REASONS, } from "./processes.js";
-import { activeProfile, agentVarKeys, BUILT_IN_PROJECT_YML, configHash, loadProjectYml, mergedProjectVars, NO_PROFILE, PROJECT_YML_KEYS, resolveCommandDir, } from "./projectYml.js";
+import { activeProfile, agentVarKeys, BUILT_IN_PROJECT_YML, configHash, loadProjectYml, mergedProjectVars, NO_PROFILE, PROJECT_YML_KEYS, resolveCommandDir, resolveFirstMessage, } from "./projectYml.js";
 import { writeProjectPosture } from "./brief.js";
 import { carriesNameFlag, harnessFor, hasTranscriptSignal, paneClassifierFor, transcriptDirFor } from "./harnesses.js";
 import { codexHomeDir, codexInstructionsPhrase, ensureCodexHome, reapCodexHome } from "./codexHome.js";
-import { TRIAGE_MESSAGE } from "./kickoff.js";
+import { FIRST_MESSAGE_SHA_ENV, firstMessageDigest } from "./firstMessage.js";
 import { ageSecondsSince, deriveProvenance, describeForHuman, describeLastLogEvent, humanizeAge, lastLogEvent, lastPermissionMode, reportsAgentStateLog, } from "./stateProvenance.js";
 import { awaitingFirstPromptSql } from "./firstPrompt.js";
 import { checkoutRoot, createProfile, forkProfile, PROFILE_FILES, ProfileError, profileExists, profileFileNames, profileNames, profileStatus, readProfileFile, referencedPads, referencedPaths, renderProfileFile, resolveProfileFile, REWRITE_THRESHOLD, templateVars, userProfilesDir, } from "./profiles.js";
@@ -46,11 +48,16 @@ function usage() {
 Usage:
   hive --version              version, short sha, and dirty marker for this build
   hive [path]                open the project's session with a lead window
-  hive lead [path] [--no-dashboard]
+  hive lead [path] [--no-dashboard] [--detach]
                              same; lead is the default command. --no-dashboard
                              skips this run's dashboard auto-open -
                              scripts/restart-lead.sh passes it; a human rarely
-                             needs to
+                             needs it. --detach starts or adopts the lead and
+                             prints its pane and attach command without attaching
+  hive queen [--no-dashboard]
+                             start, or reattach to, the lead that reads across
+                             every registered project; its home is
+                             <data dir>/queen, created on first run
   hive init [path] [--profile <name>|--no-profile]
                              set the project up: hive.yml, profile, starter pads
   hive attach [path]         attach without adding windows
@@ -59,6 +66,14 @@ Usage:
   hive show <process> [path]  move a running process's pane beside the lead
   hive hide <process> [path]  move it back into the <project>/processes window
   hive status                overview of agents, todos, and wake-ups everywhere
+  hive portfolio [--json]    one row per registered project: lane, lead, workers,
+                             todos, needs-human count, wakes; read-only
+  hive queen-audit           confirmed queen writes, newest first; 30-day history
+    [--project-id <id>]      filter the target project (queen only across projects)
+    [--limit <n>] [--json]   default 20, maximum 100; JSON prints one object
+  hive next [--print]        attach to the lead of the project that needs you most
+                             (waiting on you, then stuck), starting a dead or
+                             missing lead first; --print only names the choice
   hive upgrade [--check]    upgrade a global npm install; preview with --check
   hive upgrade --run        run the printed pull/install/build/setup checkout recipe
   hive setup [--dir <dir>]   write a \`hive\` that runs the interpreter this build
@@ -124,6 +139,27 @@ function resolveProject(path, onNotice) {
     const pinnedProject = getProject(pinned);
     throw new Error(`This session is locked to project ${pinned} ("${pinnedProject.name}") but "${path}" resolves to ${target ? `project ${target.id} ("${target.name}")` : "no registered project"}. An explicit path argument cannot escape HIVE_PROJECT_LOCK=1. Unset HIVE_AGENT_ID and HIVE_PROJECT_LOCK in this pane, or open a new one, to act on a different project.`);
 }
+function resolveProjectForWrite(verb, path, onNotice) {
+    assertQueenCrossProjectWrite(verb, findProjectForDir(path ?? process.cwd())?.id ?? null, {});
+    return resolveProject(path, onNotice);
+}
+function resolveProjectForRead(verb, path) {
+    if (path) {
+        process.chdir(path);
+        const pinned = agentProjectPin();
+        if (pinned != null) {
+            const target = findProjectForCwd();
+            if (target == null || target.id !== pinned) {
+                throw new Error(`This session is locked to project ${pinned} ("${getProject(pinned).name}") but "${path}" resolves to ${target ? `project ${target.id} ("${target.name}")` : "no registered project"}. An explicit path argument cannot escape HIVE_PROJECT_LOCK=1. Unset HIVE_AGENT_ID and HIVE_PROJECT_LOCK in this pane, or open a new one, to act on a different project.`);
+            }
+        }
+    }
+    const project = pinnedOrCwdProject();
+    if (project)
+        return project;
+    console.error(`hive ${verb}: this directory is not a registered hive project. cd to a registered checkout, or run \`hive init\` here to register it.`);
+    process.exit(1);
+}
 function pinnedOrCwdProject() {
     const pinned = agentProjectPin();
     if (pinned != null)
@@ -139,12 +175,9 @@ async function confirmYesNo(question) {
     return /^y(es)?$/i.test(answer.trim());
 }
 async function ensureTrusted(projectId, name, command, dir, env) {
-    const hash = configHash(name, command, dir, env);
-    const trusted = db
-        .prepare("SELECT 1 FROM command_trust WHERE project_id = ? AND name = ? AND config_hash = ?")
-        .get(projectId, name, hash);
-    if (trusted)
+    if (isTrusted(projectId, name, command, dir, env))
         return true;
+    const hash = configHash(name, command, dir, env);
     if (!process.stdin.isTTY || !process.stdout.isTTY) {
         console.log(`! "${name}" is not trusted yet; run hive interactively to review it.`);
         return false;
@@ -162,6 +195,12 @@ async function ensureTrusted(projectId, name, command, dir, env) {
     db.prepare("INSERT OR IGNORE INTO command_trust (project_id, name, config_hash) VALUES (?, ?, ?)").run(projectId, name, hash);
     return true;
 }
+function isTrusted(projectId, name, command, dir, env) {
+    const hash = configHash(name, command, dir, env);
+    return !!db
+        .prepare("SELECT 1 FROM command_trust WHERE project_id = ? AND name = ? AND config_hash = ?")
+        .get(projectId, name, hash);
+}
 function startYmlCommand(project, name, proc, config) {
     if (isReservedAgentName(name)) {
         return `skipped: "lead" is reserved for this project's lead session and cannot be used as a process name`;
@@ -318,24 +357,39 @@ function reportMigrationResult(result) {
         console.error(`! ${warning}`);
 }
 async function cmdLead(argv) {
-    const unknownFlag = argv.find((a) => a.startsWith("--") && a !== "--no-dashboard");
+    const unknownFlag = argv.find((a) => a.startsWith("--") && a !== "--no-dashboard" && a !== "--detach");
     if (unknownFlag !== undefined) {
-        console.error(`hive lead: unknown flag "${unknownFlag}". The only flag is --no-dashboard.`);
+        console.error(`hive lead: unknown flag "${unknownFlag}". Flags are --no-dashboard and --detach.`);
         process.exit(1);
     }
     const noDashboard = argv.includes("--no-dashboard");
+    const detach = argv.includes("--detach");
     const path = argv.find((a) => !a.startsWith("--"));
     let registrationNotice = null;
     try {
-        const project = resolveProject(path, (text) => {
+        const project = resolveProjectForWrite("hive lead", path, (text) => {
             registrationNotice = text;
         });
+        const auditIdentity = captureQueenWriteIdentity(project.id);
+        const { config, warnings, sources } = loadProjectYml(project.path);
+        if (detach && (!process.stdin.isTTY || !process.stdout.isTTY)) {
+            let untrusted;
+            if (config?.lead && !isTrusted(project.id, "lead", config.lead, null, {}))
+                untrusted = "lead";
+            if (!untrusted && config) {
+                untrusted = Object.entries(config.processes).find(([name, proc]) => proc.auto_start !== false && !isTrusted(project.id, name, proc.command, proc.dir, proc.env))?.[0];
+            }
+            if (untrusted) {
+                console.error(`hive lead: "${untrusted}" is not trusted; run hive lead <path> interactively once`);
+                process.exitCode = 1;
+                return;
+            }
+        }
         reportMigrationResult(migrateLegacyConfig());
-        const session = sessionName();
-        const hooksPath = ensureHooksFile();
-        const { config, warnings } = loadProjectYml(project.path);
         for (const w of warnings)
             console.log(`! ${w}`);
+        const session = sessionName();
+        const hooksPath = ensureHooksFile();
         let leadCommand = "claude";
         if (!config) {
             console.log("No hive.yml here; starting a plain claude lead. Add a hive.yml to define project commands and a custom lead (run hive --help for the format).");
@@ -349,6 +403,10 @@ async function cmdLead(argv) {
             }
         }
         const leadHarness = harnessFor(leadCommand);
+        let firstMessage = resolveFirstMessage(config, sources).message;
+        if (firstMessage !== "" && !(await (await import("./kickoff.js")).kickoffGate(project.path)).ok)
+            firstMessage = "";
+        let promptSuffix = "";
         // Posture is rendered once, then delivered through whichever channel this harness has: a
         // claude lead gets it as --append-system-prompt-file below; a codex lead gets the identical
         // text as config.toml's developer_instructions, built after ensureLeadRow (it needs leadActorId).
@@ -386,6 +444,9 @@ async function cmdLead(argv) {
                 leadCommand += ` ${leadHarness.briefDelivery.systemPromptArgs(posturePath).map(shellQuote).join(" ")}`;
                 console.log(`- profile: ${profile} (${postureSource} posture; see it with: hive posture)`);
             }
+            if (leadHarness.initialPromptArgs && firstMessage !== "") {
+                promptSuffix = ` ${leadHarness.initialPromptArgs(firstMessage).map(shellQuote).join(" ")}`;
+            }
         }
         const windowName = project.name;
         const { agentId: leadAgentId, actorId: leadActorId, previousTarget, previousSocket, previousPanePid, previousCommand, previousCodexHome, casExpected, } = ensureLeadRow(project, leadCommand);
@@ -430,8 +491,8 @@ async function cmdLead(argv) {
                 throw e;
             }
             leadCommand += ` ${homeArgs.map(shellQuote).join(" ")}`;
-            if (leadHarness.initialPromptArgs) {
-                leadCommand += ` ${leadHarness.initialPromptArgs(TRIAGE_MESSAGE).map(shellQuote).join(" ")}`;
+            if (leadHarness.initialPromptArgs && firstMessage !== "") {
+                promptSuffix = ` ${leadHarness.initialPromptArgs(firstMessage).map(shellQuote).join(" ")}`;
             }
             if (renderedPosture !== null) {
                 console.log(`- profile: ${profile} (${postureSource} posture; see it with: hive posture)`);
@@ -442,13 +503,15 @@ async function cmdLead(argv) {
         }
         const envFlags = buildEnvFlags({
             ...leadEnv,
+            [FIRST_MESSAGE_SHA_ENV]: promptSuffix !== "" ? firstMessageDigest(firstMessage) : "",
             ...(newCodexHomeKey ? { CODEX_HOME: codexHomeDir(newCodexHomeKey) } : {}),
         });
+        const launchCommand = leadCommand + promptSuffix;
         const { leadPane, leadWindow, createdPane } = withWindowClaim(() => {
             let leadPane;
             let leadWindow;
             let createdPane;
-            const started = ensureSession(session, project.path, { envFlags, command: leadCommand });
+            const started = ensureSession(session, project.path, { envFlags, command: launchCommand });
             if (started.created) {
                 const claimed = claimInitialWindow(started, windowName, project.id);
                 leadPane = claimed.pane;
@@ -467,13 +530,13 @@ async function cmdLead(argv) {
                     createdPane = false;
                 }
                 else if (!foundWindow) {
-                    const fresh = createWindow(session, windowName, project.path, envFlags, leadCommand, project.id);
+                    const fresh = createWindow(session, windowName, project.path, envFlags, launchCommand, project.id, detach);
                     leadPane = fresh.pane;
                     leadWindow = fresh.window;
                     createdPane = true;
                 }
                 else {
-                    leadPane = tmux("split-window", "-P", "-F", "#{pane_id}", "-t", foundWindow, "-c", project.path, ...envFlags, leadCommand);
+                    leadPane = tmux("split-window", ...(detach ? ["-d"] : []), "-P", "-F", "#{pane_id}", "-t", foundWindow, "-c", project.path, ...envFlags, launchCommand);
                     leadWindow = foundWindow;
                     createdPane = true;
                 }
@@ -495,18 +558,7 @@ async function cmdLead(argv) {
         // also reaps a stale codex home left over from a lead config that has since switched away from
         // codex, since createdPane's branch does not require leadHarness.needsHome to fire.
         const recordedCodexHome = createdPane ? (newCodexHomeKey ?? "") : previousCodexHome;
-        const wonRace = db.transaction(() => {
-            const updated = db
-                .prepare("UPDATE agents SET tmux_target = ?, tmux_socket = ?, pane_pid = ?, command = ?, codex_home = ? WHERE id = ? AND tmux_target = ? AND status = 'running'")
-                .run(leadPane, tmuxSocketPath(process.env.TMUX, process.env.TMUX_TMPDIR), panePid(leadPane), recordedCommand, recordedCodexHome, leadAgentId, casExpected).changes;
-            if (updated === 0)
-                return false;
-            db.prepare(`UPDATE wakes SET deliver_pane = ?, held_at = NULL, held_reason = NULL
-         WHERE ${ACTIVE_TIMER_WHERE} AND deliver_actor = ?
-           AND (? = 1 OR held_reason IS NULL OR held_reason NOT LIKE ?)`).run(leadPane, leadActorId, createdPane ? 1 : 0, `${HELD_REASON_UNCLASSIFIABLE_PANE_PREFIX}%`);
-            return true;
-        })();
-        if (!wonRace) {
+        const abandonClaim = () => {
             if (createdPane) {
                 try {
                     waitForPaneEstablished(leadPane);
@@ -517,6 +569,31 @@ async function cmdLead(argv) {
             }
             if (newCodexHomeKey)
                 reapCodexHome(newCodexHomeKey);
+        };
+        let wonRace;
+        try {
+            wonRace = db.transaction(() => {
+                const updated = db
+                    .prepare("UPDATE agents SET tmux_target = ?, tmux_socket = ?, pane_pid = ?, command = ?, codex_home = ? WHERE id = ? AND tmux_target = ? AND status = 'running'")
+                    .run(leadPane, tmuxSocketPath(process.env.TMUX, process.env.TMUX_TMPDIR), panePid(leadPane), recordedCommand, recordedCodexHome, leadAgentId, casExpected).changes;
+                if (updated === 0)
+                    return false;
+                db.prepare(`UPDATE wakes SET deliver_pane = ?, held_at = NULL, held_reason = NULL
+           WHERE ${ACTIVE_TIMER_WHERE} AND deliver_actor = ?
+             AND (? = 1 OR held_reason IS NULL OR held_reason NOT LIKE ?)`).run(leadPane, leadActorId, createdPane ? 1 : 0, `${HELD_REASON_UNCLASSIFIABLE_PANE_PREFIX}%`);
+                confirmQueenWrite("hive lead", project.id, { detach }, {
+                    agent_id: leadAgentId,
+                    disposition: createdPane ? "started" : "adopted",
+                }, auditIdentity);
+                return true;
+            })();
+        }
+        catch (e) {
+            abandonClaim();
+            throw e;
+        }
+        if (!wonRace) {
+            abandonClaim();
             throw new Error("Another `hive lead` won the race to record a live pane for this project's lead session (both saw the " +
                 "same dead pane and both tried to replace it, or this row was closed by another process mid-restart). " +
                 "Re-run `hive lead`; it will attach to the pane that invocation recorded.");
@@ -550,6 +627,11 @@ async function cmdLead(argv) {
             console.error(registrationNotice);
             registrationNotice = null;
         }
+        if (detach) {
+            console.log(`LEAD_PANE=${leadPane}`);
+            console.log(`ATTACH_COMMAND=hive attach ${shellQuote(project.path)}`);
+            return;
+        }
         if (!noDashboard)
             maybeOpenDashboard(project, !!config?.dashboard);
         attach(session, project, leadWindow);
@@ -560,6 +642,60 @@ async function cmdLead(argv) {
         throw e;
     }
 }
+function publishQueenYml(home) {
+    const yml = join(home, "hive.yml");
+    const staged = join(home, `.hive.yml.${process.pid}.${randomUUID()}`);
+    writeFileSync(staged, `profile: ${QUEEN_PROFILE}\n`, { flag: "wx" });
+    try {
+        linkSync(staged, yml);
+    }
+    catch (e) {
+        if (e.code !== "EEXIST")
+            throw e;
+    }
+    finally {
+        unlinkSync(staged);
+    }
+    if (lstatSync(yml).isSymbolicLink()) {
+        throw new Error(`hive queen: ${yml} is a symlink. The queen's config must be a real file; remove the link and run hive queen again.`);
+    }
+    const { config } = loadProjectYml(home);
+    if (activeProfile(config) !== QUEEN_PROFILE) {
+        throw new Error(`hive queen: ${yml} already exists and does not select "profile: ${QUEEN_PROFILE}". hive will not ` +
+            "overwrite it. Add that line yourself, or move the file away and run hive queen again.");
+    }
+}
+async function cmdQueen(argv) {
+    const parsed = parseArgs(argv, { flags: ["--no-dashboard"] });
+    rejectUnknownFlags("queen", parsed, "--no-dashboard");
+    if (parsed.positional.length > 0) {
+        console.error(`hive queen: takes no path. The queen lives in the data dir (${queenHomeDir()}).`);
+        process.exit(1);
+    }
+    if (process.env.HIVE_PROJECT_LOCK === "1" || agentProjectPin() != null) {
+        throw new Error("hive queen: this session is locked to its own project (HIVE_PROJECT_LOCK=1), so it cannot create or " +
+            "start the queen. Run hive queen from your own terminal.");
+    }
+    const home = queenHomeDir();
+    let existing = null;
+    try {
+        existing = lstatSync(home);
+    }
+    catch {
+        existing = null;
+    }
+    if (existing?.isSymbolicLink() || (existing && !existing.isDirectory())) {
+        throw new Error(`hive queen: ${home} exists and is not a plain directory. The queen's home must be a real directory ` +
+            "inside the data dir; move it away and run hive queen again.");
+    }
+    mkdirSync(home, { recursive: true });
+    publishQueenYml(home);
+    const queen = addProject(home, "queen");
+    generateQueenDashboardNow();
+    if (!parsed.flags.has("--no-dashboard"))
+        maybeOpenQueenDashboard(queen);
+    await cmdLead([home, ...parsed.flags]);
+}
 const HIVE_YML_TEMPLATE = `# hive project config. Read by \`hive lead\` from the project root.
 # Commands defined here run only after a one-time interactive approval,
 # and re-require it whenever they change.
@@ -577,6 +713,7 @@ const HIVE_YML_TEMPLATE = `# hive project config. Read by \`hive lead\` from the
 # agents: [claude, codex]       # crew harness pool; the first entry is the default
 
 # lead_branches: [main, master] # branches where a session gets hive's kickoff
+# first_message: "..."         # a lead's first turn; absent or "" sends none
 
 # context_checkpoint_percent: null # unset means off; integer 1-100 to enable
 
@@ -778,6 +915,7 @@ async function cmdInit(argv) {
             process.exit(1);
         }
         const existing = getProjectByPath(registration);
+        assertQueenCrossProjectWrite("hive init", existing?.id ?? null, {});
         project = existing ?? addProject(registration);
         newlyRegistered = existing == null;
     }
@@ -894,7 +1032,7 @@ itself to this project before any real work runs.`);
 }
 const NO_RUNBOOK_PAD_MESSAGE = `is on "profile: none" but has no runbook pad. Create one with: hive init`;
 function cmdRunbook(path) {
-    const project = resolveProject(path);
+    const project = resolveProjectForRead("runbook", path);
     const { config, warnings } = loadProjectYml(project.path);
     for (const w of warnings)
         console.log(`! ${w}`);
@@ -919,7 +1057,7 @@ function cmdRunbook(path) {
     process.stdout.write(withTrailingNewline(rendered));
 }
 function cmdPosture(path) {
-    const project = resolveProject(path);
+    const project = resolveProjectForRead("posture", path);
     const { config, warnings } = loadProjectYml(project.path);
     for (const w of warnings)
         console.log(`! ${w}`);
@@ -1060,7 +1198,7 @@ function cmdProfile(argv) {
                     vars = mergedProjectVars(here ? loadProjectYml(here.path).config : null);
                 }
                 else {
-                    const project = resolveProject();
+                    const project = resolveProjectForRead("profile read");
                     const { config, warnings } = loadProjectYml(project.path);
                     for (const w of warnings)
                         console.log(`! ${w}`);
@@ -1107,6 +1245,22 @@ function maybeOpenDashboard(project, dashboardEnabled) {
         return;
     if (!dashboardFileContained(dashboardFile, project.path))
         return;
+    openDashboardOnce(project, dashboardFile);
+}
+function maybeOpenQueenDashboard(project) {
+    if (process.platform !== "darwin")
+        return;
+    const dashboardFile = join(project.path, "dashboard.html");
+    try {
+        if (!existsSync(dashboardFile) || !dashboardFileContained(dashboardFile, project.path))
+            return;
+    }
+    catch {
+        return;
+    }
+    openDashboardOnce(project, dashboardFile);
+}
+function openDashboardOnce(project, dashboardFile) {
     const actor = currentActor();
     const claim = db
         .prepare(`INSERT INTO kv (project_id, key, value, updated_by, expires_at)
@@ -1132,7 +1286,7 @@ function cmdAttach(argv) {
         process.exit(1);
     }
     const path = argv.find((a) => !a.startsWith("--"));
-    const project = resolveProject(path);
+    const project = resolveProjectForWrite("hive attach", path);
     maybeOpenDashboard(project, !!loadProjectYml(project.path).config?.dashboard);
     const session = sessionName();
     const window = withWindowClaim(() => {
@@ -1160,7 +1314,7 @@ async function cmdStart(argv) {
         console.log("Usage: hive start <process> [path]");
         process.exit(1);
     }
-    const project = resolveProject(path);
+    const project = resolveProjectForWrite("hive start", path);
     const { config, warnings } = loadProjectYml(project.path);
     for (const w of warnings)
         console.log(`! ${w}`);
@@ -1188,7 +1342,7 @@ function resolveNamedProcess(argv, verb) {
         console.log(`Usage: hive ${verb} <process> [path]`);
         process.exit(1);
     }
-    const project = resolveProject(parsed.positional[1]);
+    const project = resolveProjectForWrite(`hive ${verb}`, parsed.positional[1]);
     const { config, warnings } = loadProjectYml(project.path);
     for (const w of warnings)
         console.log(`! ${w}`);
@@ -1228,7 +1382,7 @@ function leadPaneExitedHookCommand() {
     // started from inside a worker's pane hands them to every run-shell it ever runs, where a stale
     // HIVE_AGENT_ID is a hard refusal before the verb is reached at all. The same clearing
     // scripts/restart-lead.sh does around its own `hive lead`, plus the two project vars.
-    const clear = ["HIVE_AGENT_ID", "HIVE_AGENT_NAME", "HIVE_LEAD", "HIVE_PROJECT_LOCK", "HIVE_PROJECT_PATH"]
+    const clear = ["HIVE_AGENT_ID", "HIVE_AGENT_NAME", "HIVE_LEAD", FIRST_MESSAGE_SHA_ENV, "HIVE_PROJECT_LOCK", "HIVE_PROJECT_PATH"]
         .flatMap((name) => ["-u", name]);
     // Redirected because tmux prints a run-shell's output into the pane it fires from, which is a
     // human's own window: a backstop that failed to start must not type into it.
@@ -1310,7 +1464,7 @@ function cmdStop(argv) {
     const parsed = parseArgs(argv, { flags: ["--all"] });
     rejectUnknownFlags("stop", parsed, "--all");
     if (parsed.flags.has("--all")) {
-        const project = resolveProject(parsed.positional[0]);
+        const project = resolveProjectForWrite("hive stop", parsed.positional[0]);
         const stopped = stopAllProcesses(project.id, STOP_REASONS.byHand);
         console.log(stopped.length === 0 ? "No processes are running." : stopped.map(stopLine).join("\n"));
         return;
@@ -1320,7 +1474,7 @@ function cmdStop(argv) {
         console.log("Usage: hive stop <process> [path] | hive stop --all [path]");
         process.exit(1);
     }
-    const project = resolveProject(parsed.positional[1]);
+    const project = resolveProjectForWrite("hive stop", parsed.positional[1]);
     const row = runningCommandRow(project.id, name);
     if (!row) {
         const { config, warnings } = loadProjectYml(project.path);
@@ -1723,7 +1877,7 @@ function reportProjectScope(here) {
         if (locked && project.id !== here?.id)
             continue;
         if (project.path === homePath || project.path === "/") {
-            warn("project scope", `"${project.name}" (${project.path}) is a home directory; every unregistered directory under it resolves to this project. hive project prune removes it once it holds nothing.`);
+            warn("project scope", `"${project.name}" (${project.path}) is a home directory; every unregistered directory under it resolves to this project. The project_prune tool with this project's id (from any hive session) removes it once it holds nothing.`);
         }
     }
     for (const parent of projects) {
@@ -2595,6 +2749,144 @@ function findPadExports(projectId, name) {
         .filter((f) => f.startsWith(prefix) && f.endsWith(".md"))
         .map((f) => join(tmpdir(), f));
 }
+function canonicalPath(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return resolve(path);
+    }
+}
+function nextCandidates() {
+    const queenRoot = canonicalPath(join(storeDir(), "queen"));
+    const byCount = (a, b) => b - a;
+    return collectPortfolio()
+        .projects.filter((p) => (p.lane === "waiting_on_you" || p.lane === "stuck" || (p.lane === "moving" && p.needs_human > 0)) &&
+        canonicalPath(p.root) !== queenRoot)
+        .sort((a, b) => {
+        const tier = (p) => (p.lane === "waiting_on_you" ? 0 : p.needs_human > 0 ? 1 : 2);
+        if (tier(a) !== tier(b))
+            return tier(a) - tier(b);
+        if (a.lane === "waiting_on_you") {
+            return (byCount(a.needs_human, b.needs_human) ||
+                a.last_activity_at.localeCompare(b.last_activity_at) ||
+                a.id - b.id);
+        }
+        return (byCount(a.needs_human, b.needs_human) ||
+            byCount(a.todos.blocked_in_progress, b.todos.blocked_in_progress) ||
+            byCount(a.wakes.overdue, b.wakes.overdue) ||
+            byCount(a.workers.needs_input, b.workers.needs_input) ||
+            a.last_activity_at.localeCompare(b.last_activity_at) ||
+            a.id - b.id);
+    });
+}
+function collectProjectById(id) {
+    return collectPortfolio().projects.find((p) => p.id === id);
+}
+async function cmdNext(argv) {
+    const parsed = parseArgs(argv, { flags: ["--print"] });
+    if (parsed.positional.length > 0)
+        parsed.unknown.push(parsed.positional[0]);
+    rejectUnknownFlags("next", parsed, "--print");
+    if (process.env.HIVE_PROJECT_LOCK === "1") {
+        console.error("hive next: this session is locked to one project (HIVE_PROJECT_LOCK=1) and cannot jump to another. Run it from a pane outside a worker session.");
+        process.exit(1);
+    }
+    const chosen = nextCandidates()[0];
+    if (!chosen) {
+        console.log("No project needs you: none is waiting, stuck, or holding a needs-human item.");
+        return;
+    }
+    console.log(JSON.stringify({
+        project_id: chosen.id,
+        name: chosen.name,
+        root: chosen.root,
+        lane: chosen.lane,
+        reasons: chosen.reasons,
+        lead_state: chosen.lead.state,
+    }));
+    if (parsed.flags.has("--print"))
+        return;
+    assertQueenCrossProjectWrite("hive next", chosen.id, {});
+    if (!chosen.root_exists) {
+        console.error(`hive next: project ${chosen.id} ("${chosen.name}") root is missing: ${chosen.root}. Remove the stale project with the project_prune tool, or restore the directory.`);
+        process.exit(1);
+    }
+    let state = collectProjectById(chosen.id)?.lead.state ?? "none";
+    if (state === "unknown") {
+        console.error(`hive next: cannot tell whether the lead for project ${chosen.id} ("${chosen.name}") is alive (tmux did not answer for its socket). Starting nothing.`);
+        process.exit(1);
+    }
+    await cmdLead([chosen.root, "--detach"]);
+    state = collectProjectById(chosen.id)?.lead.state ?? "none";
+    if (state !== "alive" || (process.exitCode !== undefined && process.exitCode !== 0)) {
+        console.error(`hive next: the lead for project ${chosen.id} ("${chosen.name}") did not start cleanly (${state}). Not attaching.`);
+        process.exit(1);
+    }
+    cmdAttach([chosen.root]);
+}
+function cmdQueenAudit(argv) {
+    const parsed = parseArgs(argv, { flags: ["--json"], valued: ["--project-id", "--limit"] });
+    if (parsed.positional.length > 0)
+        parsed.unknown.push(parsed.positional[0]);
+    rejectUnknownFlags("queen-audit", parsed, "--project-id <id>, --limit <n>, --json");
+    requireFlagValues("queen-audit", parsed);
+    let report;
+    try {
+        const project = pinnedOrCwdProject();
+        if (!project)
+            throw new Error("hive queen-audit: the cwd is not a registered project. Run this command from a registered project.");
+        report = listQueenAudit({
+            project_id: parsed.values.has("--project-id") ? Number(parsed.values.get("--project-id")) : undefined,
+            limit: parsed.values.has("--limit") ? Number(parsed.values.get("--limit")) : undefined,
+        }, project.id);
+    }
+    catch (e) {
+        console.error(errorMessage(e));
+        process.exitCode = 1;
+        return;
+    }
+    if (parsed.flags.has("--json")) {
+        console.log(JSON.stringify(report));
+        return;
+    }
+    if (report.entries.length === 0) {
+        console.log("No queen actions recorded.");
+        return;
+    }
+    for (const entry of report.entries) {
+        console.log(`${entry.created_at} UTC  ${entry.actor_id} -> target #${entry.target_project_id}\n` +
+            `  ${entry.operation}  ${entry.resource_type} #${entry.resource_id}\n  ${entry.summary}`);
+    }
+}
+function cmdPortfolio(argv) {
+    const parsed = parseArgs(argv, { flags: ["--json"] });
+    if (parsed.positional.length > 0)
+        parsed.unknown.push(parsed.positional[0]);
+    rejectUnknownFlags("portfolio", parsed, "--json");
+    const report = collectPortfolio();
+    if (parsed.flags.has("--json")) {
+        console.log(JSON.stringify(report));
+        return;
+    }
+    if (report.projects.length === 0) {
+        console.log("No registered projects.");
+        return;
+    }
+    for (const p of report.projects) {
+        const w = p.workers;
+        const t = p.todos;
+        console.log(`${p.lane.padEnd(14)} ${p.name} (#${p.id})${p.root_exists ? "" : "  [root missing]"}\n` +
+            `  why: ${p.reasons.join(", ")}\n` +
+            `  lead ${leadText(p)}; workers ${w.working} working, ${w.idle} idle, ${w.needs_input} needs input, ` +
+            `${w.other} other, ${w.unreachable} unreachable, ${w.unconfirmed} unconfirmed\n` +
+            `  todos ${t.open} open, ${t.in_progress} in progress, ${t.blocked} blocked, ${t.high} high; ` +
+            `needs human ${p.needs_human}; wakes ${p.wakes.pending} pending, ${p.wakes.overdue} overdue\n` +
+            `  last activity ${p.last_activity_at} UTC`);
+    }
+    const l = report.totals.lanes;
+    console.log(`\n${report.totals.projects} project(s): ${l.waiting_on_you} waiting on you, ${l.stuck} stuck, ${l.moving} moving, ${l.quiet} quiet`);
+}
 function cmdBackups() {
     const snapshots = listSnapshots(dataDir);
     if (snapshots.length === 0) {
@@ -2762,9 +3054,7 @@ function requireFlagValues(command, parsed) {
     process.exit(1);
 }
 function cmdTodos(argv) {
-    const project = pinnedOrCwdProject();
-    if (!project)
-        return;
+    const project = resolveProjectForRead("todos");
     const all = argv.includes("--all");
     const statusIdx = argv.indexOf("--status");
     const status = flagValue(argv, "--status");
@@ -2808,9 +3098,7 @@ function cmdTodos(argv) {
     }
 }
 function cmdTodo(argv) {
-    const project = pinnedOrCwdProject();
-    if (!project)
-        return;
+    const project = resolveProjectForRead("todo");
     const id = Number(argv.find((a) => !a.startsWith("--")));
     if (!Number.isInteger(id)) {
         console.log("Usage: hive todo <id>  (run inside the project)");
@@ -2851,7 +3139,7 @@ function cmdTodo(argv) {
     }
 }
 function cmdPads() {
-    const project = resolveProject();
+    const project = resolveProjectForRead("pads");
     const pads = listActivePads(project.id);
     if (pads.length === 0) {
         console.log(`No pads in project "${project.name}".`);
@@ -2870,7 +3158,7 @@ function cmdPad(argv) {
         console.log("Usage: hive pad <name> [--edit | --save [file]]  (run inside the project)");
         process.exit(1);
     }
-    const project = resolveProject();
+    const project = parsed.flags.has("--save") ? resolveProjectForWrite("hive pad --save") : resolveProjectForRead("pad");
     const pad = getActivePadByName(project.id, name);
     if (!pad) {
         console.log(`No pad named "${name}" in project "${project.name}". List them with: hive pads`);
@@ -2940,6 +3228,11 @@ function cmdPad(argv) {
     }
     process.stdout.write(withTrailingNewline(pad.content));
 }
+process.stdout.on("error", (error) => {
+    if (error.code === "EPIPE")
+        process.exit(0);
+    throw error;
+});
 const args = process.argv.slice(2);
 let command = args[0] ?? "lead";
 let rest = args.slice(1);
@@ -2964,7 +3257,7 @@ if (command === "--version" || command === "-v") {
     process.exit(0);
 }
 const COMMANDS = [
-    "lead", "init", "attach", "start", "stop", "show", "hide", "status", "setup", "upgrade", "doctor",
+    "lead", "queen", "queen-audit", "init", "attach", "start", "stop", "show", "hide", "status", "portfolio", "next", "setup", "upgrade", "doctor",
     LEAD_PANE_EXITED_VERB,
     "pads", "pad", "todos", "todo", "backups", "restore", "runbook", "posture", "profile", "kickoff", "statusline",
 ];
@@ -2988,6 +3281,9 @@ try {
         case "lead":
             await cmdLead(rest);
             break;
+        case "queen":
+            await cmdQueen(rest);
+            break;
         case "init":
             await cmdInit(rest);
             break;
@@ -3012,6 +3308,15 @@ try {
         case "status":
             cmdStatus();
             break;
+        case "portfolio":
+            cmdPortfolio(rest);
+            break;
+        case "queen-audit":
+            cmdQueenAudit(rest);
+            break;
+        case "next":
+            await cmdNext(rest);
+            break;
         case "setup":
             cmdSetup(rest);
             break;