@cmgmyr/hive 1.0.0 → 1.2.0

package/README.md

@@ -67,3 +67,7 @@ hive is a personal daily-driver tool, released low-key. It is single-user by des
 | [Tools](docs/tools.md) | The 45 MCP tools: what each does and when to use it |
 | [tmux settings](docs/tmux.md) | Attach modes, pane options, and what to put in `~/.tmux.conf` |
 | [Development](docs/development.md) | Building and testing hive itself |
+
+## Updating
+
+Run `hive upgrade` for a global npm install, or `hive upgrade --check` to preview the commands without changing your install. In a git checkout, the default prints the recipe; `hive upgrade --run` executes it. Upgrade reports Claude Code and Codex registration repairs without editing their configs. Restart every session with hive loaded after the upgrade. See [Updating and recovery](docs/install.md#updating).

package/dist/build-info.json

@@ -1 +1 @@
-{"version":"1.0.0","sha":"119838a","dirty":false}
+{"version":"1.2.0","sha":"6abbb1c","dirty":false,"build_id":"7bfa0131-a4ec-4341-a842-7d0cc0cd803d"}

package/dist/cli.js

@@ -11,14 +11,17 @@ import { versionInfo } from "./version.js";
 import { claudeConfigDir } from "./claudeDir.js";
 import { ATTACH_MODES, AUTO_ATTACH_MODES, attachMode, isAttachMode, isAutoAttach, resolvedAttachMode, resolvedAutoAttach, setAttachMode, setAutoAttach, } from "./config.js";
 import { cliPath, dispatcherDir, dispatcherPath, dispatcherScript, durabilityLines, firstHiveOnPath, linkedWorktreePin, pathAdvice, readDispatcher, } from "./dispatcher.js";
-import { codexConfigPath, codexHiveRegistrations, hiveRegistrations, registrationOffer, registrationProblem, } from "./mcpConfig.js";
+import { codexConfigPath, codexHiveRegistrations, codexRegistrationProblem, hiveRegistrations, registrationOffer, registrationProblem, } from "./mcpConfig.js";
 import { DEFAULT_DATA_DIR } from "./dataDir.js";
-import { dataDir, db, migrate } from "./db.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 { ensureHooksFile } from "./hooks.js";
 import { errorMessage, parseTags, 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 { readTurnCount } from "./turnCount.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";
@@ -56,6 +59,8 @@ 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 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
                              was compiled for; re-run after every update
   hive setup --attach <mode> auto|raw|control: whether tmux attaches carry -CC
@@ -558,13 +563,20 @@ placement: split                # placement for workers and visible processes: s
 
 # lead: claude --model opus     # custom command for the lead window (default: claude)
 
+# agents: [claude, codex]       # crew harness pool; the first entry is the default
+
 # lead_branches: [main, master] # branches where a session gets hive's kickoff
 
 # context_checkpoint_percent: null # unset means off; integer 1-100 to enable
 
+# lead_turn_budget: {warn: 300, stop: 600} # optional lead statusline thresholds
+
+# dashboard: true               # write .hive/dashboard.html (default: false)
+
 # review_tags: [from-review]    # todo tags \`hive doctor\` counts as review findings and
                                 # reports as triaged (has a comment, completed, or archived)
-                                # or untriaged. Absent means doctor tracks none.
+                                # or untriaged. A tag also matches its own suffixed rounds.
+                                # Absent means it tracks none.
 
 # vars:                         # substituted into the profile runbook
 #   repo: owner/name            # {{repo}}
@@ -1451,6 +1463,74 @@ const verboseInfo = (_check, label, ...lines) => {
         report("info", label, lines);
 };
 const isReviewFindingTag = (bases, tag) => bases.some((base) => tag === base || tag.startsWith(`${base}-`));
+function cmdUpgrade(argv) {
+    const parsed = parseArgs(argv, { flags: ["--check", "--run"] });
+    rejectUnknownFlags("upgrade", parsed, "--check, --run");
+    if (parsed.positional.length || (parsed.flags.has("--check") && parsed.flags.has("--run"))) {
+        console.error("hive upgrade: use --check or --run, without positional arguments.");
+        process.exitCode = 1;
+        return;
+    }
+    const shape = detectInstallShape();
+    if (shape.kind === "unknown") {
+        console.error(`Cannot upgrade this install: ${shape.reason}`);
+        console.error(`CLI: ${shape.cli}\nPackage root: ${shape.packageRoot}\n.git: ${shape.gitState}\nnpm root -g: ${shape.npmRoot ?? "unavailable"}`);
+        console.error("Put the npm for this package's global root first on PATH, or use a git checkout.");
+        process.exitCode = 1;
+        return;
+    }
+    if (shape.kind === "global" && parsed.flags.has("--run")) {
+        console.error("hive upgrade: --run is only for checkouts; global installs upgrade by default.");
+        process.exitCode = 1;
+        return;
+    }
+    const steps = shape.kind === "checkout" ? checkoutUpgradeSteps(shape.packageRoot) : globalUpgradeSteps(shape);
+    const render = (step) => [step.command, ...step.args]
+        .map((arg) => /^[a-zA-Z0-9_@./=-]+$/.test(arg) ? arg : `'${arg.replaceAll("'", "'\\''")}'`).join(" ");
+    const restart = "Restart every Claude Code or Codex session that has hive loaded; existing sessions keep running old in-memory code.";
+    if (shape.kind === "global") {
+        const update = queryUpdate();
+        console.log(updateLine(update));
+        if (update.status === "unknown") {
+            console.error("not upgrading: could not read the latest version");
+            process.exitCode = 1;
+            return;
+        }
+        if (update.status === "current")
+            return;
+    }
+    if (parsed.flags.has("--check") || (shape.kind === "checkout" && !parsed.flags.has("--run"))) {
+        console.log(shape.kind === "checkout" ? `Checkout: ${shape.packageRoot}\nRun in that directory, or use hive upgrade --run:` : "Would run:");
+        for (const step of steps)
+            console.log(`  ${render(step)}`);
+        console.log(restart);
+        return;
+    }
+    for (const [index, step] of steps.entries()) {
+        console.log(`\n${step.label}: ${render(step)}`);
+        const result = spawnSync(step.command, step.args, { cwd: step.cwd, stdio: "inherit" });
+        if (result.status === 0 && !result.error && !result.signal)
+            continue;
+        console.error(`${step.label} failed: ${result.error?.message ?? (result.signal ? `signal ${result.signal}` : `exit ${result.status}`)}`);
+        if (shape.kind === "global") {
+            console.error(index === 0
+                ? "npm may have left the global package partially changed. Retry the install, then repair setup:"
+                : "The package is new, but the dispatcher was not confirmed re-pinned. Repair setup:");
+            for (const remaining of steps.slice(index))
+                console.error(`  ${render(remaining)}`);
+            console.error("  hive doctor --strict");
+        }
+        else {
+            console.error(`Stopped at ${render(step)}. Remaining recipe not run:`);
+            for (const remaining of steps.slice(index + 1))
+                console.error(`  ${render(remaining)}`);
+        }
+        console.error(`After repair: ${restart}`);
+        process.exitCode = 1;
+        return;
+    }
+    console.log(`\nUpgrade complete. ${restart}`);
+}
 function cmdSetup(argv) {
     const parsed = parseArgs(argv, { flags: ["--force"], valued: ["--dir", "--attach", "--auto-attach"] });
     rejectUnknownFlags("setup", parsed, "--dir, --attach, --auto-attach, --force");
@@ -1528,8 +1608,8 @@ function cmdSetup(argv) {
     console.log("");
     for (const line of durabilityLines(node))
         console.log(line);
-    console.log("\nA rebuild does not re-pin anything on its own. After every update:");
-    console.log("  npm install && npm run build && hive setup");
+    console.log("\nFor future updates, run hive upgrade. It re-pins after installing;");
+    console.log("checkouts print the recipe and run it only with --run.");
     console.log(`\nPATH: ${pathAdvice(dir, file).join("\n")}`);
     reportSetupRegistrations(node);
 }
@@ -1546,7 +1626,14 @@ function reportSetupRegistrations(pinned) {
             for (const line of lines.slice(1))
                 console.log(`  ${line}`);
         }
-        return;
+    }
+    for (const r of codexHiveRegistrations()) {
+        const lines = codexRegistrationProblem(r, pinned);
+        if (!lines)
+            continue;
+        console.log(`\n  mcp registration (codex): ${lines[0]}`);
+        for (const line of lines.slice(1))
+            console.log(`  ${line}`);
     }
     const offer = registrationOffer(pinned, found);
     if (offer) {
@@ -1652,6 +1739,9 @@ function reportMcpRegistrations(project) {
     }
     for (const r of codexRegistrations) {
         info("mcp registration (codex)", [r.command, ...r.args].join(" "));
+        const problem = codexRegistrationProblem(r, process.execPath);
+        if (problem)
+            gatingWarn("mcp registration (codex)", ...problem);
     }
 }
 const PTY_OVERRIDE_VARS = ["HIVE_PTY_HEADROOM_JSON", "HIVE_PTY_PS_ROWS_JSON", "HIVE_ORPHAN_SCRATCH_JSON"];
@@ -1960,6 +2050,13 @@ function cmdDoctor(argv) {
         const { line, drift } = versionInfo();
         return drift ? [line, drift].join("\n        ") : line;
     });
+    let cachedUpdate = readCachedUpdate();
+    if (cacheIsStale(cachedUpdate) && shouldAutoRefresh())
+        cachedUpdate = refreshUpdate();
+    if (cachedUpdate?.status === "newer" && cachedUpdate.checkedAt) {
+        const hours = Math.max(0, Math.floor((Date.now() - Date.parse(cachedUpdate.checkedAt)) / (60 * 60 * 1000)));
+        warn("update", `${updateLine(cachedUpdate)} (checked ${hours}h ago)`);
+    }
     check("node", () => describeInterpreter());
     check("better-sqlite3", () => {
         const status = checkAbi();
@@ -1978,6 +2075,10 @@ function cmdDoctor(argv) {
     check("claude", () => execFileSync("which", ["claude"], { encoding: "utf8" }).trim());
     check("database", () => {
         const n = db.prepare("SELECT COUNT(*) AS n FROM migrations").get().n;
+        const ahead = storeSchemaAhead(db);
+        if (ahead) {
+            warn("database", `store schema v${ahead.store} is ahead of this build (v${ahead.build}): a newer hive has migrated your shared store. Upgrade this install before relying on it.`);
+        }
         return `${dataDir} (schema v${n})`;
     });
     check("hooks file", () => ensureHooksFile());
@@ -2388,6 +2489,7 @@ function cmdStatusline() {
        AND NOT EXISTS (${OPEN_BLOCKERS_SQL})`);
     const pads = count("SELECT COUNT(*) AS n FROM pads WHERE project_id = ? AND archived = 0");
     const wakes = count(`SELECT COUNT(*) AS n FROM wakes WHERE project_id = ? AND ${ACTIVE_TIMER_WHERE}`);
+    const schemaAhead = storeSchemaAhead(db);
     // One statement, not two: the count and the chosen row must come from the same read, or a wake that
     // delivers/re-arms between two separate queries leaves the second with no row to read.
     const held = db
@@ -2403,7 +2505,7 @@ function cmdStatusline() {
          (SELECT held_reason FROM chosen) AS held_reason,
          (SELECT first_held_at FROM chosen) AS first_held_at`)
         .get(project.id, `${HELD_REASON_UNSUBMITTED_INPUT_PREFIX}%`, `${HELD_REASON_UNCLASSIFIABLE_PANE_PREFIX}%`, project.id);
-    if (agents + commands + todos + pads + wakes === 0)
+    if (agents + commands + todos + pads + wakes === 0 && !schemaAhead)
         return;
     const s = (n) => (n === 1 ? "" : "s");
     const parts = [
@@ -2419,6 +2521,34 @@ function cmdStatusline() {
         const age = held.first_held_at ? humanizeAge(ageSecondsSince(held.first_held_at)) : "?";
         parts.push(`${held.n} held (${age}, ${heldReasonLabel(held.held_reason)})`);
     }
+    if (schemaAhead)
+        parts.push("store ahead (update hive)");
+    let turns = null;
+    let budget = null;
+    try {
+        const actorId = process.env.HIVE_AGENT_ID;
+        if (actorId) {
+            const lead = db.prepare("SELECT 1 AS lead FROM agents WHERE project_id = ? AND actor_id = ? AND kind = 'lead' AND status = 'running'").get(project.id, actorId);
+            if (lead) {
+                let inputPath = "";
+                if (!process.stdin.isTTY) {
+                    try {
+                        const raw = readFileSync(0, "utf8").trim();
+                        const input = raw ? JSON.parse(raw) : null;
+                        inputPath = typeof input?.transcript_path === "string" ? input.transcript_path : "";
+                    }
+                    catch { }
+                }
+                turns = readTurnCount(inputPath);
+                budget = loadProjectYml(project.path).config?.lead_turn_budget ?? null;
+            }
+        }
+    }
+    catch { }
+    if (turns !== null) {
+        const color = budget === null ? "" : turns >= budget.stop ? "\x1b[31m" : turns >= budget.warn ? "\x1b[33m" : "";
+        parts.push(`${color}turns ${turns}${color ? "\x1b[0m" : ""}`);
+    }
     console.log(`\x1b[33m⬡\x1b[0m \x1b[2mhive:\x1b[0m ${parts.join(" \x1b[2m·\x1b[0m ")}`);
 }
 // test/docs.test.mjs fails if a label here is missing from docs/install.md. It checks
@@ -2801,10 +2931,21 @@ if (command === "--version" || command === "-v") {
     console.log(line);
     if (drift)
         console.log(`! ${drift}`);
+    if (rest.includes("--check")) {
+        if (process.env.HIVE_NO_UPDATE_CHECK === "1")
+            console.log("update check disabled (HIVE_NO_UPDATE_CHECK)");
+        else
+            console.log(updateLine(refreshUpdate()));
+    }
+    else {
+        const cached = readCachedUpdate();
+        if (cached?.status === "newer" && !cacheIsStale(cached))
+            console.log(`! ${updateLine(cached)}`);
+    }
     process.exit(0);
 }
 const COMMANDS = [
-    "lead", "init", "attach", "start", "stop", "show", "hide", "status", "setup", "doctor",
+    "lead", "init", "attach", "start", "stop", "show", "hide", "status", "setup", "upgrade", "doctor",
     LEAD_PANE_EXITED_VERB,
     "pads", "pad", "todos", "todo", "backups", "restore", "runbook", "posture", "profile", "kickoff", "statusline",
 ];
@@ -2821,7 +2962,8 @@ if (!COMMANDS.includes(command)) {
         usage();
     }
 }
-migrate();
+if (command !== "upgrade")
+    migrate();
 try {
     switch (command) {
         case "lead":
@@ -2854,6 +2996,9 @@ try {
         case "setup":
             cmdSetup(rest);
             break;
+        case "upgrade":
+            cmdUpgrade(rest);
+            break;
         case "doctor":
             cmdDoctor(rest);
             break;

package/dist/db.js

@@ -370,6 +370,17 @@ CREATE INDEX idx_wakes_active ON wakes(project_id, kind)
 CREATE INDEX idx_wakes_parent ON wakes(parent_wake_id) WHERE parent_wake_id IS NOT NULL;
 `,
 ];
+export function storeSchemaAhead(database) {
+    try {
+        const { version } = database.prepare("SELECT MAX(version) AS version FROM migrations").get();
+        if (version == null || !Number.isFinite(version) || version <= MIGRATIONS.length)
+            return null;
+        return { store: version, build: MIGRATIONS.length };
+    }
+    catch {
+        return null;
+    }
+}
 function readAppliedVersions() {
     return new Set(db.prepare("SELECT version FROM migrations").all().map((r) => r.version));
 }

package/dist/help.js

@@ -153,7 +153,9 @@ runbook (fork it first), not a pad write.`,
   agent_status(name|agent_id, include_brief?) — liveness, current command,
     short tail, and the path to the brief this worker was given
     (include_brief=true returns its text; no transcript records it).
-  agent_list(include_closed?) — all agents with live status.
+  agent_list(include_closed?, limit?, before_id?) — agents with live status.
+    include_closed adds closed/parked rows, newest first, limit 20/max 100;
+    page with before_id set to the receipt's next_before_id.
   agent_rename(name|agent_id, new_name) — change the display name. actor_id
     stays agent:N, so older pad writes and todo comments still point here.
     A live claude worker is told to retitle its own session, which arrives as

package/dist/mcpConfig.js

@@ -1,14 +1,27 @@
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parse as parseToml } from "smol-toml";
-const serverPath = () => fileURLToPath(new URL("./index.js", import.meta.url));
+export const serverPath = () => fileURLToPath(new URL("./index.js", import.meta.url));
+function serverProblem(args, expected) {
+    const server = args[0];
+    if (!server)
+        return "has no server path.";
+    if (!existsSync(server))
+        return `points at a missing server: ${server}`;
+    try {
+        if (realpathSync(server) === realpathSync(expected))
+            return null;
+    }
+    catch { }
+    return `points at a different server: ${server} (expected ${expected})`;
+}
 function addCommand(scope, name, pinned, args) {
     return `  claude mcp add --scope ${scope} ${name} -- ${[pinned, ...args].map((a) => `"${a}"`).join(" ")}`;
 }
-export function registrationProblem(r, pinned) {
-    const reRegister = [addCommand(r.scope, r.name, pinned, r.args)];
+export function registrationProblem(r, pinned, expectedServer = serverPath()) {
+    const reRegister = [addCommand(r.scope, r.name, pinned, [expectedServer])];
     if (!r.command.includes("/")) {
         return [
             `runs "${r.command}", which a Node version manager re-resolves per`,
@@ -25,7 +38,23 @@ export function registrationProblem(r, pinned) {
             ...reRegister,
         ];
     }
-    return null;
+    const problem = serverProblem(r.args, expectedServer);
+    return problem ? [problem, `Re-register in ${r.source}:`, ...reRegister] : null;
+}
+export function codexRegistrationProblem(r, pinned, expectedServer = serverPath()) {
+    const problem = !r.command.includes("/")
+        ? `runs "${r.command}", which a Node version manager re-resolves per directory.`
+        : r.command !== pinned
+            ? `pins a different interpreter than this CLI runs (${pinned}).`
+            : serverProblem(r.args, expectedServer);
+    if (!problem)
+        return null;
+    return [
+        problem,
+        `Re-register in ${r.source}:`,
+        `  codex mcp remove ${r.name}`,
+        `  codex mcp add ${r.name} -- "${pinned}" "${expectedServer}"`,
+    ];
 }
 function readJson(file) {
     try {

package/dist/projectYml.js

@@ -65,6 +65,22 @@ export function loadProjectYml(projectPath) {
             warnings.push("context_checkpoint_percent must be an integer from 1 through 100; ignoring it.");
         }
     }
+    let lead_turn_budget = null;
+    if (root.lead_turn_budget != null) {
+        const value = root.lead_turn_budget;
+        const budget = typeof value === "object" && value !== null && !Array.isArray(value)
+            ? value
+            : null;
+        const warn = budget?.warn;
+        const stop = budget?.stop;
+        if (typeof warn === "number" && Number.isInteger(warn) && warn > 0 &&
+            typeof stop === "number" && Number.isInteger(stop) && stop > warn) {
+            lead_turn_budget = { warn, stop };
+        }
+        else {
+            warnings.push("lead_turn_budget must contain positive integer warn and stop values, with stop greater than warn; ignoring it.");
+        }
+    }
     const lead = typeof root.lead === "string" && root.lead.trim() !== "" ? root.lead.trim() : null;
     let placement = null;
     if (root.placement != null) {
@@ -231,6 +247,7 @@ export function loadProjectYml(projectPath) {
             review_tags,
             lead_branches,
             context_checkpoint_percent,
+            lead_turn_budget,
             dashboard,
             vars,
             processes,

package/dist/result.js

@@ -1,3 +1,4 @@
+import { runningBuildChange, runningBuildNotice } from "./version.js";
 export function errorMessage(e) {
     return e instanceof Error ? e.message : String(e);
 }
@@ -14,10 +15,32 @@ export function registrationNoticeText(notice) {
         `it if it owns nothing yet, run the session from the intended directory, or call ` +
         `project_select.`);
 }
+const reportedBuilds = new Set();
+export async function appendRunningBuildNotice(result, session) {
+    try {
+        const change = runningBuildChange();
+        if (!change || reportedBuilds.has(change.disk.build_id))
+            return result;
+        const actor = process.env.HIVE_AGENT_ID;
+        if (actor) {
+            const { db } = await import("./db.js");
+            const row = db.prepare("SELECT kind FROM agents WHERE actor_id = ?").get(actor);
+            if (row?.kind === "agent")
+                return result;
+        }
+        if (reportedBuilds.has(change.disk.build_id))
+            return result;
+        result.content.push({ type: "text", text: runningBuildNotice(change, session) });
+        reportedBuilds.add(change.disk.build_id);
+    }
+    catch {
+    }
+    return result;
+}
 export async function run(fn) {
     const { storeReplaced } = await import("./db.js");
     if (storeReplaced()) {
-        return { content: [{ type: "text", text: STORE_REPLACED_MESSAGE }], isError: true };
+        return appendRunningBuildNotice({ content: [{ type: "text", text: STORE_REPLACED_MESSAGE }], isError: true });
     }
     const { takeRegistrationNotice } = await import("./context.js");
     let result;
@@ -31,7 +54,7 @@ export async function run(fn) {
     if (notice) {
         result.content.push({ type: "text", text: registrationNoticeText(notice) });
     }
-    return result;
+    return appendRunningBuildNotice(result);
 }
 export function parseTags(text) {
     try {

package/dist/scheduler.js

@@ -1,3 +1,4 @@
+import { runningBuildChange, runningBuildNotice } from "./version.js";
 import { existsSync, mkdirSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, join, sep } from "node:path";
 import { dataDir, db, storeReplaced } from "./db.js";
@@ -161,6 +162,25 @@ function reportDeadProcess(agent, snapshot) {
     catch {
     }
 }
+const reportedBuilds = new Set();
+export function reportRunningBuildChange(snapshot) {
+    try {
+        const change = runningBuildChange();
+        const actor = process.env.HIVE_AGENT_ID;
+        if (!change || !actor || reportedBuilds.has(change.disk.build_id))
+            return;
+        const lead = stmt(`SELECT project_id, actor_id, tmux_target, tmux_socket, pane_pid, command FROM agents
+       WHERE actor_id = ? AND kind = ? AND status = 'running'`).get(actor, LEAD_KIND);
+        if (!lead?.tmux_target || !screenClassifiable(lead.command) ||
+            rowAlive(lead.tmux_socket, lead.tmux_target, snapshot) !== true ||
+            paneReissued(lead.pane_pid, rowAliveProbe(lead.tmux_socket, lead.tmux_target, snapshot)))
+            return;
+        insertNotice({ project_id: lead.project_id, owner: lead.actor_id }, lead.actor_id, lead.tmux_target, runningBuildNotice(change), null);
+        reportedBuilds.add(change.disk.build_id);
+    }
+    catch {
+    }
+}
 const deadProcessBody = (name) => `[hive] process "${name}" exited on its own; its pane is gone. Restart it with: hive start "${name}"`;
 export function janitor(snapshot = liveTargets()) {
     const reapedCodexHomes = reapClosedCodexHomes();
@@ -359,6 +379,8 @@ export async function tick(snapshot) {
         if (snapshot === undefined)
             snapshot = liveTargets();
         janitor(snapshot);
+        if (snapshot)
+            reportRunningBuildChange(snapshot);
         checkConfirmations();
         pruneStateLog();
         maybeBackupHourly(db, dataDir);

package/dist/tools/agents.js

@@ -837,18 +837,53 @@ export function registerAgents(server) {
         };
     }));
     server.registerTool("agent_list", {
-        description: "List this project's agents with live status.",
+        description: "List this project's agents with live status. Without include_closed, this is every running agent, in full. With include_closed, it is every agent (running and closed/parked), newest first, bounded by limit (default 20, max 100); when the receipt carries next_before_id, page through the rest by passing it back as before_id.",
         inputSchema: {
             include_closed: z.boolean().optional(),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .optional()
+                .describe("Max rows to return when include_closed is true, newest first. Default 20, max 100. Ignored otherwise."),
+            before_id: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("Page cursor for include_closed: only rows with id below this value. Pass the previous receipt's next_before_id to get the next page."),
             project_id: projectIdParam,
         },
     }, (args) => run(() => {
         const project = resolveProject(args.project_id);
-        let sql = "SELECT * FROM agents WHERE project_id = ?";
-        if (!args.include_closed)
-            sql += " AND status = 'running'";
-        const rows = db.prepare(`${sql} ORDER BY id`).all(project.id);
         const snapshot = liveTargets();
+        let rows;
+        let total;
+        let nextBeforeId;
+        if (args.include_closed) {
+            const limit = Math.min(args.limit ?? 20, 100);
+            total = db.prepare("SELECT COUNT(*) AS n FROM agents WHERE project_id = ?").get(project.id).n;
+            let sql = "SELECT * FROM agents WHERE project_id = ?";
+            const params = [project.id];
+            if (args.before_id != null) {
+                sql += " AND id < ?";
+                params.push(args.before_id);
+            }
+            sql += " ORDER BY id DESC LIMIT ?";
+            params.push(limit + 1);
+            const page = db.prepare(sql).all(...params);
+            const truncated = page.length > limit;
+            rows = truncated ? page.slice(0, limit) : page;
+            if (truncated)
+                nextBeforeId = rows[rows.length - 1].id;
+        }
+        else {
+            rows = db
+                .prepare("SELECT * FROM agents WHERE project_id = ? AND status = 'running' ORDER BY id")
+                .all(project.id);
+            total = rows.length;
+        }
         return {
             project_id: project.id,
             project_name: project.name,
@@ -857,6 +892,9 @@ export function registerAgents(server) {
                     note: `${PROBE_FAILED_NOTE} These rows are what the store holds; do not conclude a worker died.`,
                 }
                 : {}),
+            total,
+            returned: rows.length,
+            ...(nextBeforeId !== undefined ? { next_before_id: nextBeforeId } : {}),
             agents: rows.map((r) => {
                 const summary = agentSummary(r, snapshot);
                 return {

package/dist/transcript.js

@@ -8,6 +8,9 @@ export function transcriptDirName(cwd) {
 export function transcriptDir(cwd) {
     return join(claudeConfigDir(), "projects", transcriptDirName(cwd));
 }
+export function transcriptPath(cwd, sessionId, explicitPath = "") {
+    return explicitPath || (sessionId ? join(transcriptDir(cwd), `${sessionId}.jsonl`) : "");
+}
 export function resolveTranscriptDir(cwd) {
     const dir = transcriptDir(cwd);
     return existsSync(dir) ? dir : null;
@@ -116,8 +119,8 @@ export function readContextFill(kind, worker) {
         used_tokens: used, window_tokens: window, used_percent: Math.round(used * 100 / window),
     };
 }
-export function readContextTokens(cwd, sessionId, transcriptPath = "") {
-    if (!sessionId && !transcriptPath)
+export function readContextTokens(cwd, sessionId, explicitPath = "") {
+    if (!sessionId && !explicitPath)
         return null;
-    return claudeTokens(tailRecords(transcriptPath || join(transcriptDir(cwd), `${sessionId}.jsonl`)));
+    return claudeTokens(tailRecords(transcriptPath(cwd, sessionId, explicitPath)));
 }

package/dist/turnCount.js

@@ -0,0 +1,26 @@
+import { readFileSync } from "node:fs";
+export function readTurnCount(path) {
+    if (!path)
+        return null;
+    try {
+        const ids = new Set();
+        for (const line of readFileSync(path, "utf8").split("\n")) {
+            if (!line.includes('"type":"assistant"'))
+                continue;
+            try {
+                const record = JSON.parse(line);
+                if (record.type !== "assistant")
+                    continue;
+                const message = record.message;
+                if (typeof message?.id !== "string" || message.id === "" || message.model === "<synthetic>")
+                    continue;
+                ids.add(message.id);
+            }
+            catch { }
+        }
+        return ids.size;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/updateCheck.js

@@ -0,0 +1,111 @@
+import { execFileSync } from "node:child_process";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { storeDir } from "./dataDir.js";
+import { versionInfo } from "./version.js";
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const CACHE_FILE = "update-check.json";
+const VERSION_RE = /^(\d+)\.(\d+)\.(\d+)$/;
+function currentVersion() {
+    return versionInfo().line.match(/^hive\s+(\S+)/)?.[1] ?? "0.0.0";
+}
+function compareVersions(current, latest) {
+    const currentMatch = VERSION_RE.exec(current);
+    const latestMatch = VERSION_RE.exec(latest);
+    if (!currentMatch || !latestMatch)
+        return "unknown";
+    for (let i = 1; i <= 3; i += 1) {
+        const difference = Number(latestMatch[i]) - Number(currentMatch[i]);
+        if (difference > 0)
+            return "newer";
+        if (difference < 0)
+            return "current";
+    }
+    return "current";
+}
+function fromCache(record) {
+    const current = currentVersion();
+    if (record.error !== null) {
+        return { current, latest: null, status: "unknown", reason: record.error, checkedAt: record.checked_at };
+    }
+    const latest = typeof record.latest === "string" ? record.latest : null;
+    const status = latest === null ? "unknown" : compareVersions(current, latest);
+    return {
+        current,
+        latest,
+        status,
+        reason: status === "unknown" ? "unparseable version" : null,
+        checkedAt: record.checked_at,
+    };
+}
+function cachePath() {
+    return join(storeDir(), CACHE_FILE);
+}
+export function readCachedUpdate() {
+    try {
+        const raw = JSON.parse(readFileSync(cachePath(), "utf8"));
+        if (typeof raw.checked_at !== "string" || (typeof raw.latest !== "string" && raw.latest !== null) || (typeof raw.error !== "string" && raw.error !== null)) {
+            return null;
+        }
+        return fromCache({ checked_at: raw.checked_at, latest: raw.latest, error: raw.error });
+    }
+    catch {
+        return null;
+    }
+}
+function writeCache(result) {
+    const dir = storeDir();
+    mkdirSync(dir, { recursive: true });
+    const path = cachePath();
+    const temporary = `${path}.${process.pid}.tmp`;
+    writeFileSync(temporary, JSON.stringify({ checked_at: result.checkedAt, latest: result.latest, error: result.reason }));
+    renameSync(temporary, path);
+}
+export function queryUpdate() {
+    const current = currentVersion();
+    const checkedAt = new Date().toISOString();
+    let latest = null;
+    let reason = null;
+    if (process.env.HIVE_NO_UPDATE_CHECK === "1") {
+        reason = "disabled (HIVE_NO_UPDATE_CHECK)";
+    }
+    else {
+        try {
+            latest = execFileSync("npm", ["view", "@cmgmyr/hive", "version"], {
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "pipe"],
+                timeout: 5000,
+            }).trim();
+            if (!VERSION_RE.test(latest) || !VERSION_RE.test(current))
+                reason = "unparseable version";
+        }
+        catch (error) {
+            const code = error.code;
+            reason = code === "ENOENT" ? "npm not found" : code === "ETIMEDOUT" ? "timed out" : "offline or npm failed";
+        }
+    }
+    const status = reason === null && latest !== null ? compareVersions(current, latest) : "unknown";
+    return { current, latest, status, reason, checkedAt };
+}
+export function refreshUpdate() {
+    const result = queryUpdate();
+    writeCache(result);
+    return result;
+}
+export function cacheIsStale(update, now = Date.now()) {
+    if (!update?.checkedAt)
+        return true;
+    const checked = Date.parse(update.checkedAt);
+    return !Number.isFinite(checked) || now - checked >= CACHE_TTL_MS;
+}
+export function updateLine(update) {
+    if (update.status === "newer" && update.latest) {
+        return `update available: hive ${update.latest} (you have ${update.current}); run: hive upgrade`;
+    }
+    if (update.status === "current")
+        return `up to date: hive ${update.current} is the latest on npm`;
+    return `update check: unknown (${update.reason ?? "offline or npm failed"})`;
+}
+export function shouldAutoRefresh() {
+    return process.stdout.isTTY === true && !process.env.CI && process.env.HIVE_NO_UPDATE_CHECK !== "1";
+}

package/dist/upgrade.js

@@ -0,0 +1,49 @@
+import { execFileSync } from "node:child_process";
+import { realpathSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join } from "node:path";
+import { cliPath } from "./dispatcher.js";
+export function detectInstallShape(cli = cliPath(), npmCommand = "npm") {
+    const packageRoot = dirname(dirname(cli));
+    let gitState = "absent";
+    try {
+        const git = statSync(join(packageRoot, ".git"));
+        if (git.isDirectory() || git.isFile())
+            return { kind: "checkout", packageRoot };
+        gitState = "neither file nor directory";
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            gitState = String(error);
+    }
+    let npmRoot = null;
+    let reason;
+    try {
+        npmRoot = execFileSync(npmCommand, ["root", "-g"], {
+            encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 5000,
+        }).trim();
+        if (!isAbsolute(npmRoot))
+            throw new Error("npm root -g did not return an absolute path");
+        if (realpathSync(packageRoot) === realpathSync(join(npmRoot, "@cmgmyr/hive"))) {
+            return { kind: "global", packageRoot, npmRoot, npmCommand };
+        }
+        reason = "npm root -g does not own the running package";
+    }
+    catch (error) {
+        reason = `could not confirm npm root ownership: ${String(error)}`;
+    }
+    return { kind: "unknown", packageRoot, cli, gitState, npmRoot, reason };
+}
+export function checkoutUpgradeSteps(packageRoot, node = process.execPath) {
+    return [
+        { label: "pull", command: "git", args: ["pull", "--ff-only"], cwd: packageRoot },
+        { label: "install", command: "npm", args: ["install"], cwd: packageRoot },
+        { label: "build", command: "npm", args: ["run", "build"], cwd: packageRoot },
+        { label: "setup", command: node, args: [join(packageRoot, "dist/cli.js"), "setup"], cwd: packageRoot },
+    ];
+}
+export function globalUpgradeSteps(shape, node = process.execPath) {
+    return [
+        { label: "install", command: shape.npmCommand, args: ["install", "-g", "@cmgmyr/hive@latest"] },
+        { label: "setup", command: node, args: [join(shape.npmRoot, "@cmgmyr/hive/dist/cli.js"), "setup"] },
+    ];
+}

package/dist/version.js

@@ -1,5 +1,5 @@
 import { execFileSync } from "node:child_process";
-import { readFileSync } from "node:fs";
+import { readFileSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 const moduleDir = dirname(fileURLToPath(import.meta.url));
@@ -13,6 +13,43 @@ function readBuildInfo() {
         return null;
     }
 }
+function readRunningBuild() {
+    const info = readBuildInfo();
+    return info && typeof info.build_id === "string" && info.build_id.trim() !== "" &&
+        (info.sha === null || typeof info.sha === "string") && typeof info.dirty === "boolean"
+        ? info : null;
+}
+const loadedBuild = readRunningBuild();
+let diskSignature;
+let diskBuild = null;
+export function runningBuildChange() {
+    try {
+        if (!loadedBuild)
+            return null;
+        const stat = statSync(join(moduleDir, "build-info.json"));
+        const signature = `${stat.ino}:${stat.size}:${stat.mtimeMs}`;
+        if (signature !== diskSignature) {
+            diskBuild = readRunningBuild();
+            diskSignature = signature;
+        }
+        return diskBuild && diskBuild.build_id !== loadedBuild.build_id
+            ? { loaded: loadedBuild, disk: diskBuild } : null;
+    }
+    catch {
+        diskSignature = undefined;
+        diskBuild = null;
+        return null;
+    }
+}
+export function runningBuildNotice(change, session) {
+    const subject = session ? `session ${JSON.stringify(session)}'s` : "this session's";
+    const detail = (info) => info.sha === null ? "no git sha" : describe(info.sha, info.dirty);
+    const sameDescription = change.loaded.version === change.disk.version && detail(change.loaded) === detail(change.disk);
+    const label = (info) => `hive ${info.version} (${detail(info)}${sameDescription ? `, build ${info.build_id.slice(0, 8)}` : ""})`;
+    return `hive: ${subject} hive server loaded ${label(change.loaded)}; ` +
+        `the build on disk changed to ${label(change.disk)}. ` +
+        "Restart this session, or reconnect hive in /mcp, to pick it up.";
+}
 function packageVersion() {
     try {
         const raw = JSON.parse(readFileSync(join(checkoutRoot, "package.json"), "utf8"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cmgmyr/hive",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Shared memory and coordination for Claude Code sessions: one lead, many tmux workers, one project-scoped store.",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   },
   "scripts": {
     "build": "tsc && node scripts/gen-version.mjs",
+    "check:mermaid": "node scripts/check-mermaid.mjs",
     "prepublishOnly": "npm run build",
     "watch": "tsc --watch",
     "start": "node dist/index.js",