@cmgmyr/hive 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Gmyr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+<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>
+
+Shared, persistent memory and a visible crew of tmux workers for Claude Code and Codex sessions on one project.
+
+- Visible workers: each one is a real tmux pane you can read and type into.
+- Exact state: workers report it through their own CLI's hooks, so nothing polls.
+- One local SQLite store: no daemon, and nothing leaves your machine.
+
+![hive: a lead plans, spawns workers, and is woken when they finish](https://raw.githubusercontent.com/cmgmyr/hive/main/docs/assets/demo.svg)
+
+## Install
+
+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
+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
+hive doctor          # verify: node, ABI, tmux, claude, database, hooks all green
+```
+
+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
+
+Run `cd ~/Code/your-project && hive`. It is shorthand for `hive lead`, and it opens a `lead` window running Claude in this project's tmux session, with the lead session named after the project so your other Claude Code sessions can address it by that name; ask it to triage, and it reads the standing process and proposes work. Spawn workers with `agent_spawn`, and watch or take over any of them with `tmux -CC attach -t hive-main` (or plain `tmux attach`).
+
+## How it works
+
+Each Claude Code session runs its own `hive` MCP server over stdio, and every instance reads and writes one SQLite database (WAL mode) at `~/.hive/hive.db`, so every session sees the same state. There is no daemon and nothing leaves your machine. State is scoped to a project (a directory), resolved from the working directory; a lead spawns workers into tmux panes locked to that project.
+
+## Why not subagents?
+
+| | Subagents | hive workers |
+|---|---|---|
+| Visibility | report at the end | live terminal you read and type into |
+| Persistence | vanish with the conversation | pads and todos outlive every session |
+| Lifetime | die with the parent | keep running when the lead detaches |
+| Scope | one session | several sessions, terminals, humans |
+
+Hive workers can still use subagents. See [Why not subagents?](docs/concepts.md#why-not-subagents) for the longer answer.
+
+## Status
+
+hive is a personal daily-driver tool, released low-key. It is single-user by design and dogfooded daily by its author on macOS. The test suite also runs on Linux in CI, but nobody drives hive there yet. Issues are welcome; for bigger changes, open a discussion first. See [CONTRIBUTING.md](CONTRIBUTING.md). MIT licensed.
+
+## Docs
+
+| Page | What's there |
+|---|---|
+| [Architecture](docs/architecture.md) | Seven diagrams: process topology, module layering, spawn sequence, wake lifecycle, worker state, project scoping, store and server identity |
+| [Patterns](docs/patterns.md) | Standing trades, refused approaches, evidence standards, and guard shapes distilled from the project's own decisions and dead-ends |
+| [Concepts](docs/concepts.md) | Vocabulary, why not subagents, identity, the workflow, project scope, the shared store |
+| [Daily driver](docs/daily-driver.md) | A day with hive, starting a session, watching workers, wake-ups |
+| [Commands](docs/commands.md) | Every `hive` subcommand and what it does |
+| [Configuration](docs/configuration.md) | The `HIVE_*` environment variables |
+| [Profiles](docs/profiles.md) | Standing instructions across projects, the session-start plugin |
+| [Projects](docs/projects.md) | `hive init`, `hive.yml`, automatic backups, pads and todos from the shell |
+| [Dashboard](docs/dashboard.md) | The generated dashboard: enabling it, where it lives, what it shows |
+| [Install details](docs/install.md) | The interpreter pin, iTerm settings, the status line, MCP scope, codex workers, updating, uninstalling |
+| [Troubleshooting](docs/troubleshooting.md) | Common errors and their fixes |
+| [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 |

package/claude-plugin/.claude-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
+  "name": "hive",
+  "displayName": "hive",
+  "description": "Injects hive's live project state at session start when you open a lead session in a hive project.",
+  "version": "0.1.0"
+}

package/claude-plugin/README.md

@@ -0,0 +1,47 @@
+# hive plugin
+
+Registers one SessionStart hook. When you open a session in a hive project's
+root, on a lead branch, with a profile hive can resolve, it injects the
+project's live state (board pad, in-flight and dispatchable todos, running
+workers, pending wake-ups) and asks the lead to run triage. Everywhere else it
+prints nothing.
+
+The gates live in `hive kickoff`, not here, so they upgrade with the binary
+instead of going stale in a copied script. Run `hive kickoff --explain` in any
+directory to see what it decided and why.
+
+## Install
+
+```
+ln -s <checkout>/claude-plugin ~/.claude/skills/hive
+```
+
+That is the whole install. A folder under a skills directory holding
+`.claude-plugin/plugin.json` loads as a plugin on the next session, discovered
+in place rather than copied, so `git pull && npm run build` upgrades the hook
+along with the rest of hive. `rm ~/.claude/skills/hive` uninstalls it.
+
+The hook lives here, and so does a skill (`skills/cleanup`, `/hive:cleanup`).
+hive's posture and worker briefs still travel as command-line flags from
+`hive lead` and `agent_spawn`, because a plugin has no way to ship always-on
+instructions: plugin `CLAUDE.md` is not loaded as context, and the one
+always-on mechanism a plugin has, a `force-for-plugin` output style, would
+override whatever output style you have selected - hive must never do that. A
+skill is not always-on, which is exactly why it is fine here where an output
+style is not: it costs nothing on a session that never matches it, and it
+overrides nothing the user chose. It only acts when its own description
+matches the moment, the same as any other skill.
+
+## Why kickoff.mjs exists
+
+`${CLAUDE_PLUGIN_ROOT}` is the path the plugin was found at. For the install
+above that is the symlink, `~/.claude/skills/hive`, not the checkout. node
+normalizes `..` lexically before touching the filesystem, so a hook command of
+`node "${CLAUDE_PLUGIN_ROOT}"/../dist/kickoff.js` collapses to
+`~/.claude/skills/dist/kickoff.js` and fails with MODULE_NOT_FOUND, even
+though the kernel would have resolved that same path fine.
+
+`kickoff.mjs` sidesteps it. The hook command has no `..` in it, so the symlink
+resolves normally; node then realpaths the main entry, which puts the shim's
+own `../dist/kickoff.js` import inside the real checkout. No absolute machine
+path is ever written into a committed file.

package/claude-plugin/hooks/hooks.json

@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/kickoff.mjs\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/claude-plugin/kickoff.mjs

@@ -0,0 +1,41 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+async function reexecUnderPinnedInterpreter() {
+
+  if (process.env.HIVE_KICKOFF_REEXEC) return;
+
+  if (process.env.HIVE_AGENT_ID && process.env.HIVE_LEAD !== "1") return;
+  if (!existsSync(join(process.cwd(), "hive.yml"))) return;
+
+  const { checkAbi } = await import("../dist/abi.js");
+  if (checkAbi().ok) return;
+
+  const { dispatcherPath, readDispatcher } = await import("../dist/dispatcher.js");
+  const dispatcher = readDispatcher(dispatcherPath());
+
+  const node = dispatcher?.node ?? null;
+
+  if (!node) return;
+
+  if (node === process.execPath || !existsSync(node)) return;
+
+  const result = spawnSync(node, [fileURLToPath(import.meta.url), ...process.argv.slice(2)], {
+    stdio: "inherit",
+    env: { ...process.env, HIVE_KICKOFF_REEXEC: "1" },
+  });
+
+  if (result.error) return;
+  process.exit(result.status ?? 1);
+}
+
+try {
+  await reexecUnderPinnedInterpreter();
+} catch {
+
+}
+
+const { runKickoff } = await import("../dist/kickoff.js");
+await runKickoff(process.argv.slice(2));

package/claude-plugin/skills/cleanup/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: cleanup
+description: Trims a hive project's board pad, closes finished todos on evidence, archives pads that describe finished work, and cancels stale wake-ups. Fires proactively, not only when asked - use it when a lane or wave has just finished, a worker was just closed, a merge just landed, the session is wrapping up, or the board pad describes state that is no longer true, as well as when the user says /hive:cleanup, "clean up the board", "tidy the store", "close this out", or "the board is stale".
+---
+
+# hive cleanup
+
+## Read everything first
+
+You cannot tell live state from dead state off a partial view. Before changing anything, read the board pad in full, `todo_list(status="open")`, `pad_list`, `agent_list`, and `wake_list`. A trim done off a truncated board deletes state nobody read.
+
+## The test for the board
+
+One question, asked of every block: is this true right now? Not "was it true," not "is it interesting," not "did it take effort to learn." A board is live state. A lane that merged, a worker that is gone, a hypothesis that was killed, a baseline that was superseded, a question that got answered - all of it becomes history the moment it stops being true, however recently it was written.
+
+## Never delete evidence - route it
+
+This is the rule that keeps a cleanup from being a loss. Before removing a block, decide where it belongs and put it there first:
+
+- a number someone will reuse (a baseline, a measurement, a count) -> the todo it belongs to, as a comment, or the project's own standing-lessons record if it keeps one
+- why something was decided -> a comment on that todo
+- a standing lesson that outlives this work -> wherever this project keeps standing lessons, if it keeps any
+- what a lane shipped -> its todo's close-out comment and the commit message
+- live state that has simply stopped being live -> delete it, that is the job
+
+The failure this guards against is specific: trimming a board and destroying the only record of a measurement, because it was written on the board and nowhere else.
+
+## Archive the old board before you rewrite it
+
+`pad_archive` the board, then write a fresh one carrying forward only what is still live. The old picture stays readable with `pad_list(include_archived=true)`. This is the shipped idiom - a hive project's own starter runbook says it under board discipline - and it is what makes a bad trim recoverable instead of permanent.
+
+## Todos: close what is done, and only on evidence
+
+A merge sha, a shipped file, a recorded decision - not a worker's summary and not your own memory of the session. If you cannot name the evidence, leave it open and say why.
+
+Write the close-out comment before completing, never after and never not at all: what landed, what was deliberately not built, and what a future reader would otherwise re-derive. A todo closed with no close-out has thrown away the only durable record of the work.
+
+`todo_complete` returns `newly_unblocked`. Say what the closure freed - that is the queue moving, and it is invisible if you do not report it.
+
+A todo whose body has been superseded by its own comments is not done, it is misleading. Say so on the todo rather than closing it.
+
+## Pads: a plan pad for a lane that shipped is history
+
+Archive it. A pad still describing in-flight state for work that finished is worse than no pad, because the next session reads it as current. Archiving is reversible and deleting is not, so archive by default and delete only what was never anything but scratch.
+
+## Wakes: cancel what is finished, keep what is deliberate
+
+A watch armed for a crew that is gone is noise. A dated reminder someone set on purpose is not - cancelling one silently loses a commitment nobody will notice missing until the date passes. If you cannot tell which it is, leave it and say so.
+
+## Residue you report and do not remove
+
+Worktrees, branches, running agents. Removing a worktree can destroy uncommitted work, and a running agent may be mid-turn. Name what you found and let the human or the lead decide.
+
+## Finish by saying what you left, not just what you changed
+
+A cleanup that reports only its edits cannot be audited, and the interesting part is usually what was deliberately not touched. Leave the board in the shape the next session needs: where the code is now, whatever verification number this project quotes, what is genuinely in flight (often nothing), and what is waiting on a human.
+
+## Where to route evidence in this project
+
+The board pad is universal - `hive init` seeds one in every hive project, and the shipped runbook template defines board discipline, so route freely to it. A pad for standing lessons is not universal; it is one team's convention, under whatever name that team gave it. Use one only if this project already has one. If it does not, put the evidence in a todo comment rather than inventing a pad the project never agreed to.

package/dist/abi.js

@@ -0,0 +1,220 @@
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { cliPath, dispatcherPath, readDispatcher } from "./dispatcher.js";
+const requireFromHere = createRequire(import.meta.url);
+export function classifyAddonLoadError(error) {
+    return /NODE_MODULE_VERSION \d+|Module did not self-register/i.test(error) ? "mismatch" : "load";
+}
+export function requiredNodeApi() {
+    try {
+        const root = dirname(requireFromHere.resolve("better-sqlite3/package.json"));
+        const found = /NAPI_VERSION=(\d+)/.exec(readFileSync(join(root, "binding.gyp"), "utf8"));
+        return found ? Number(found[1]) : null;
+    }
+    catch {
+        return null;
+    }
+}
+const NODE_API_STARTS = {
+    10: ["22.14.0", "23.6.0"],
+};
+function describeNodeApi(napi) {
+    return napi === null ? "none reported" : String(napi);
+}
+export function nodeRangeForNodeApi(napi) {
+    const starts = NODE_API_STARTS[napi];
+    if (!starts)
+        return null;
+    return starts.map((v, i) => (i === starts.length - 1 ? `>=${v}` : `^${v}`)).join(" || ");
+}
+function isLinuxMusl() {
+    if (process.platform !== "linux")
+        return false;
+    const report = process.report?.getReport();
+    return !report?.header?.glibcVersionRuntime;
+}
+function addonPath() {
+    try {
+        const root = dirname(requireFromHere.resolve("better-sqlite3/package.json"));
+        if (["linux", "darwin", "win32"].includes(process.platform) && ["x64", "arm64"].includes(process.arch)) {
+            const target = `${isLinuxMusl() ? "linuxmusl" : process.platform}-${process.arch}`;
+            const prebuild = join(root, "prebuilds", `${target}.node`);
+            if (existsSync(prebuild))
+                return prebuild;
+        }
+        for (const build of ["Debug", "Release"]) {
+            const file = join(root, "build", build, "better_sqlite3.node");
+            if (existsSync(file))
+                return file;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export function checkAbi() {
+    const running = Number(process.versions.modules);
+    const napi = Number(process.versions.napi);
+    const nodeApi = Number.isFinite(napi) ? napi : null;
+    const nodeApiRequired = requiredNodeApi();
+    const addon = addonPath();
+    if (!addon) {
+        return {
+            addon: null,
+            running,
+            nodeApi,
+            nodeApiRequired,
+            builtFor: null,
+            failure: "missing",
+            ok: false,
+            error: "better-sqlite3's native addon is missing; it has not been built here",
+        };
+    }
+    if (nodeApiRequired !== null && (nodeApi === null || nodeApi < nodeApiRequired)) {
+        return {
+            addon,
+            running,
+            nodeApi,
+            nodeApiRequired,
+            builtFor: null,
+            failure: "napi",
+            ok: false,
+            error: `better-sqlite3's addon is built against Node-API ${nodeApiRequired}; this Node provides Node-API ${describeNodeApi(nodeApi)}`,
+        };
+    }
+    try {
+        requireFromHere(addon);
+        return { addon, running, nodeApi, nodeApiRequired, builtFor: null, failure: null, ok: true, error: null };
+    }
+    catch (e) {
+        const error = e instanceof Error ? e.message : String(e);
+        const found = [...error.matchAll(/NODE_MODULE_VERSION (\d+)/g)].map((m) => Number(m[1]));
+        return {
+            addon,
+            running,
+            nodeApi,
+            nodeApiRequired,
+            builtFor: found[0] ?? null,
+            failure: classifyAddonLoadError(error),
+            ok: false,
+            error,
+        };
+    }
+}
+export function describeInterpreter() {
+    return `${process.version} (NODE_MODULE_VERSION ${process.versions.modules}) at ${process.execPath}`;
+}
+export function describeAbi(status) {
+    if (status.ok) {
+        return status.nodeApiRequired === null
+            ? `addon loaded under this interpreter (NODE_MODULE_VERSION ${status.running})`
+            : `addon loaded; built against Node-API ${status.nodeApiRequired}, this interpreter provides Node-API ${describeNodeApi(status.nodeApi)}`;
+    }
+    if (status.failure === "napi") {
+        const need = status.nodeApiRequired;
+        const range = need === null ? null : nodeRangeForNodeApi(need);
+        return (`addon is built against Node-API ${need}${range ? ` (needs Node ${range})` : ""},` +
+            ` this interpreter provides Node-API ${describeNodeApi(status.nodeApi)}`);
+    }
+    if (status.failure === "mismatch" && status.builtFor === null) {
+        return `addon did not register under this interpreter (NODE_MODULE_VERSION ${status.running}); its built-for version is not reported`;
+    }
+    if (status.builtFor === null)
+        return status.error ?? "addon did not load";
+    return `addon built for NODE_MODULE_VERSION ${status.builtFor}, this interpreter needs ${status.running}`;
+}
+export function abiFixLines(status, pinned) {
+    if (status.failure === "napi") {
+        const need = status.nodeApiRequired;
+        const range = need === null ? null : nodeRangeForNodeApi(need);
+        const good = pinned ? `"${pinned}"` : `<a Node matching ${range ?? "that Node-API level"}>`;
+        return [
+            `better-sqlite3's addon is built against Node-API ${need}${range ? `, which only Node ${range} provides` : ""}.`,
+            `This interpreter provides Node-API ${describeNodeApi(status.nodeApi)}, so the addon cannot load here.`,
+            "Loading it anyway does not raise an error hive could report - the process dies",
+            "inside dlopen - so hive refuses before the load rather than after.",
+            "",
+            "Rebuilding does NOT help: better-sqlite3's own binding.gyp requests the same",
+            "Node-API level, so a build from source asks for exactly the same interpreter.",
+            "",
+            `Run hive under a Node matching ${range ?? "that Node-API level"}, and re-pin the \`hive\` command`,
+            "to it (setup pins whatever Node runs it, so it has to be that one):",
+            `  ${good} "${cliPath()}" setup`,
+        ];
+    }
+    if (status.failure === "missing") {
+        return [
+            "Reinstall the package:  rm -rf node_modules/better-sqlite3 && npm install",
+            "",
+            "better-sqlite3 13 ships the addon prebuilt, so the file comes out of the",
+            "tarball rather than a build. A plain `npm install` will NOT bring it back:",
+            "with the package already unpacked at the locked version, npm reports `up to",
+            "date` without ever looking at the addon. Removing the directory first is what",
+            "makes npm fetch it again. `npm ci` does the same for the whole tree.",
+            "hive's own `npm run build` only compiles TypeScript and is not part of this.",
+            "",
+            "If it is still missing after that, this platform/arch has no prebuild in the",
+            "tarball, and the source build npm attempts during install did not succeed.",
+            "Run it by hand inside the package, where its output is readable:",
+            "  cd node_modules/better-sqlite3 && npm run build-release    (needs node-gyp)",
+        ];
+    }
+    if (status.failure !== "mismatch") {
+        return ["Build it:  npm install && npm run build"];
+    }
+    const good = pinned ? `"${pinned}"` : "<the Node that built it>";
+    return [
+        "better-sqlite3's addon is ABI-locked to the Node that compiled it, and a Node",
+        "version manager resolves `node` from the working directory, so a `cd` is enough",
+        "to swap it.",
+        "",
+        "Run hive under the Node it was built for, and re-pin the `hive` command to it",
+        "(setup pins whatever Node runs it, so it has to be that one):",
+        `  ${good} "${cliPath()}" setup`,
+        "",
+        "Or rebuild the addon for the Node you are on, and re-pin to that:",
+        "  npm install && npm run build && hive setup",
+    ];
+}
+function workingInterpreterFromDispatcher() {
+    const node = readDispatcher(dispatcherPath())?.node;
+    return node && node !== process.execPath && existsSync(node) ? node : null;
+}
+function prunedPinLines() {
+    const node = readDispatcher(dispatcherPath())?.node;
+    if (!node || existsSync(node))
+        return [];
+    return [
+        "",
+        `The \`hive\` dispatcher pins ${node}, which is not on disk. A version manager can`,
+        "remove one. That is also the interpreter hive's SessionStart hook re-execs into when a",
+        "directory's own `node` cannot load the addon, so with it gone nothing caught this.",
+    ];
+}
+export function guardAbi() {
+    const status = checkAbi();
+    if (status.ok)
+        return;
+    const doctor = process.argv[2] === "doctor";
+    const headline = status.failure === "mismatch"
+        ? "hive: cannot run under this Node."
+        : status.failure === "napi"
+            ? "hive: this Node is too old for better-sqlite3's native addon."
+            : status.failure === "missing"
+                ? "hive: better-sqlite3's native addon is not built here."
+                : "hive: cannot load better-sqlite3's native addon.";
+    const lines = [
+        ...(doctor ? ["hive doctor", ""] : [headline, ""]),
+        `  FAIL  node: ${describeInterpreter()}`,
+        `  FAIL  better-sqlite3: ${describeAbi(status)}`,
+        ...(status.addon ? [`        ${status.addon}`] : []),
+        ...prunedPinLines(),
+        "",
+        ...abiFixLines(status, workingInterpreterFromDispatcher()),
+        ...(doctor ? ["", "1 problem(s) found, 0 warning(s)."] : []),
+    ];
+    (doctor ? console.log : console.error)(lines.join("\n"));
+    process.exit(1);
+}

package/dist/abiProbe.js

@@ -0,0 +1,9 @@
+import { checkAbi, describeAbi } from "./abi.js";
+const status = checkAbi();
+process.stdout.write(`${JSON.stringify({
+    execPath: process.execPath,
+    version: process.version,
+    ok: status.ok,
+    failure: status.failure,
+    detail: describeAbi(status),
+})}\n`);

package/dist/backgroundTasks.js

@@ -0,0 +1,51 @@
+import { cutToUnitBudget, flatten } from "./slug.js";
+const TERMINAL_STATUSES = new Set(["completed", "failed", "cancelled", "canceled", "killed", "error"]);
+// Every background_tasks[].type ever observed in a Stop payload, and what hive does with it. "latch"
+// withholds the worker's idle; "name" only names it in a standing notice. An unlisted type is
+// treated as "name" - see unknownTypeIsNamedNotLatched below.
+export const BACKGROUND_TASK_DISPOSITION = {
+    subagent: "latch",
+    shell: "name",
+    monitor: "name",
+};
+export const STALL_BOUND_SECONDS = 15 * 60;
+// Derived, not copied: past the stall bound hive already treats a latched worker as stall-worthy,
+// so that is the ceiling on how long a live subagent may explain one. Keep the reference, not the
+// literal - see .claude/skills/hive-internals/references/worker-state.md.
+export const SUBAGENT_LATCH_MAX_AGE_SECONDS = STALL_BOUND_SECONDS;
+export const SUBAGENT_LATCH_SQL = `-${SUBAGENT_LATCH_MAX_AGE_SECONDS} seconds`;
+export function liveBackgroundTasks(tasks) {
+    if (!Array.isArray(tasks))
+        return [];
+    const live = [];
+    for (const entry of tasks) {
+        const task = entry;
+        const status = String(task?.status ?? "");
+        if (TERMINAL_STATUSES.has(status))
+            continue;
+        live.push({
+            type: String(task?.type ?? ""),
+            status,
+            description: String(task?.description ?? ""),
+        });
+    }
+    return live;
+}
+export const withholdsIdle = (task) => BACKGROUND_TASK_DISPOSITION[task.type] === "latch";
+const typeOf = (task) => flatten(task.type) || "unknown";
+const groupsOf = (tasks) => [...new Set(tasks.map(typeOf))].sort();
+export function describeLiveTasks(tasks) {
+    const types = groupsOf(tasks);
+    const plural = tasks.length === 1 ? "" : "s";
+    return types.length === 1
+        ? `${tasks.length} background ${types[0]}${plural}`
+        : `${tasks.length} background task${plural} (${types.join(", ")})`;
+}
+const DESCRIPTION_BUDGET = 80;
+export function describeOneTask(task) {
+    const flat = flatten(task.description);
+    if (flat === "")
+        return typeOf(task);
+    const text = flat.length > DESCRIPTION_BUDGET ? `${cutToUnitBudget(flat, DESCRIPTION_BUDGET)}…` : flat;
+    return `${typeOf(task)}: "${text}"`;
+}