@cmgmyr/hive 0.1.0 → 1.1.0

package/README.md

@@ -1,5 +1,5 @@
 <p align="center"><img src="https://raw.githubusercontent.com/cmgmyr/hive/main/docs/assets/logo-card.svg" alt="hive" height="112"></p>
-<p align="center"><a href="https://github.com/cmgmyr/hive/actions/workflows/ci.yml"><img src="https://github.com/cmgmyr/hive/actions/workflows/ci.yml/badge.svg" alt="CI"></a></p>
+<p align="center"><a href="https://www.npmjs.com/package/@cmgmyr/hive"><img src="https://img.shields.io/npm/v/%40cmgmyr%2Fhive?label=npm" alt="npm"></a> <a href="https://github.com/cmgmyr/hive/actions/workflows/ci.yml"><img src="https://github.com/cmgmyr/hive/actions/workflows/ci.yml/badge.svg" alt="CI"></a></p>
 
 Shared, persistent memory and a visible crew of tmux workers for Claude Code and Codex sessions on one project.
 
@@ -14,17 +14,16 @@ Shared, persistent memory and a visible crew of tmux workers for Claude Code and
 Requirements: macOS, Node `^22.14.0 || >=23.6.0`, [Claude Code](https://claude.com/claude-code), and tmux for the agent tools. codex is optional, only needed if a project opts a worker into it; see [docs/install.md](docs/install.md#codex-workers).
 
 ```bash
-git clone https://github.com/cmgmyr/hive.git hive && cd hive
-npm install
-npm run build
-npm link             # puts the hive command on your PATH
-hive setup           # pins that command to one interpreter
+npm install -g @cmgmyr/hive
+hive setup           # pins the hive command to one interpreter, prints the MCP line
 brew install tmux
-claude mcp add --scope user hive -- "$(command -v node)" "$(pwd)/dist/index.js"
-ln -s "$(pwd)/claude-plugin" ~/.claude/skills/hive   # optional: session-start kickoff
+claude mcp add --scope user hive -- "$(command -v node)" "$(npm root -g)/@cmgmyr/hive/dist/index.js"
+ln -s "$(npm root -g)/@cmgmyr/hive/claude-plugin" ~/.claude/skills/hive   # optional: session-start kickoff
 hive doctor          # verify: node, ABI, tmux, claude, database, hooks all green
 ```
 
+Working from a clone instead? See [docs/install.md](docs/install.md#from-source).
+
 Put `~/.local/bin` on your PATH below your version manager's block. See [Node version and the interpreter pin](docs/install.md#node-version-and-the-interpreter-pin) for why the order matters.
 
 ## First run

package/dist/build-info.json

@@ -1 +1 @@
-{"version":"0.1.0","sha":"de83214","dirty":false}
+{"version":"1.1.0","sha":"38f535a","dirty":false}

package/dist/cli.js

@@ -13,12 +13,13 @@ import { ATTACH_MODES, AUTO_ATTACH_MODES, attachMode, isAttachMode, isAutoAttach
 import { cliPath, dispatcherDir, dispatcherPath, dispatcherScript, durabilityLines, firstHiveOnPath, linkedWorktreePin, pathAdvice, readDispatcher, } from "./dispatcher.js";
 import { codexConfigPath, codexHiveRegistrations, 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 { 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";
@@ -562,6 +563,8 @@ placement: split                # placement for workers and visible processes: s
 
 # context_checkpoint_percent: null # unset means off; integer 1-100 to enable
 
+# lead_turn_budget: {warn: 300, stop: 600} # optional lead statusline thresholds
+
 # 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.
@@ -1978,6 +1981,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 +2395,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 +2411,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 +2427,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

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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cmgmyr/hive",
-  "version": "0.1.0",
+  "version": "1.1.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",
@@ -31,6 +32,7 @@
     "url": "git+https://github.com/cmgmyr/hive.git"
   },
   "homepage": "https://github.com/cmgmyr/hive#readme",
+  "funding": "https://github.com/sponsors/cmgmyr",
   "bugs": {
     "url": "https://github.com/cmgmyr/hive/issues"
   },
@@ -48,12 +50,12 @@
     "@modelcontextprotocol/sdk": "^1.30.0",
     "better-sqlite3": "^13.0.3",
     "smol-toml": "^1.8.0",
-    "yaml": "^2.9.0",
-    "zod": "^4.4.3"
+    "yaml": "^2.9.1",
+    "zod": "^4.6.5"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^9.6.0",
-    "@types/node": "^26.1.2",
+    "@types/node": "^26.6.2",
     "typescript": "^7.0.2"
   },
   "allowScripts": {