@cmgmyr/hive 0.1.0

package/dist/codexHome.js

@@ -0,0 +1,297 @@
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, symlinkSync, unlinkSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse as parseToml } from "smol-toml";
+import { gitPrimaryRoot } from "./context.js";
+import { storeDir } from "./dataDir.js";
+import { hookEntry } from "./hooks.js";
+import { shellQuote } from "./tmux.js";
+export function codexHomeDir(key) {
+    return join(storeDir(), "codex-homes", key);
+}
+export function codexRolloutsDir(key) {
+    return join(storeDir(), "codex-rollouts", key);
+}
+// undefined means transcriptPath does not point inside this home's sessions/.
+export function preservedRolloutPath(key, transcriptPath) {
+    const sessionsPrefix = `${join(codexHomeDir(key), "sessions")}/`;
+    if (!transcriptPath.startsWith(sessionsPrefix))
+        return undefined;
+    return join(codexRolloutsDir(key), transcriptPath.slice(sessionsPrefix.length));
+}
+const ROLLOUT_FILE = /^rollout-.*\.jsonl$/;
+// Dirent.isFile()/.isDirectory() answer about the entry itself, not its target, so a symlinked
+// file or directory under sessions/ is neither and is silently skipped - never followed, never
+// moved. That is what keeps this walk off the auth.json symlink without naming it specially.
+function collectRolloutFiles(dir) {
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return [];
+        throw e;
+    }
+    const files = [];
+    for (const entry of entries) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory())
+            files.push(...collectRolloutFiles(full));
+        else if (entry.isFile() && ROLLOUT_FILE.test(entry.name))
+            files.push(full);
+    }
+    return files;
+}
+// A throw here must reach reapCodexHome before its rmSync, so a durable root that cannot be
+// written leaves the home in place rather than losing the only copy of its rollout.
+export function preserveCodexRollouts(key) {
+    const sessionsDir = join(codexHomeDir(key), "sessions");
+    if (!existsSync(sessionsDir))
+        return [];
+    const sources = collectRolloutFiles(sessionsDir);
+    const destRoot = codexRolloutsDir(key);
+    const moved = [];
+    for (const src of sources) {
+        const dest = join(destRoot, relative(sessionsDir, src));
+        mkdirSync(dirname(dest), { recursive: true });
+        try {
+            renameSync(src, dest);
+        }
+        catch (e) {
+            const code = e.code;
+            // ENOENT here is the close/janitor race, not a failure: a concurrent reap of this same key
+            // already moved this file. Whichever process's rename won, the file ends up preserved once.
+            if (code === "ENOENT") {
+                if (existsSync(dest))
+                    moved.push(dest);
+                continue;
+            }
+            if (code === "EXDEV") {
+                copyFileSync(src, dest);
+                unlinkSync(src);
+                moved.push(dest);
+                continue;
+            }
+            throw e;
+        }
+        moved.push(dest);
+    }
+    return moved;
+}
+// Never follow a link out of here: auth.json is a SYMLINK to the real ~/.codex/auth.json, and
+// rmSync unlinks entries rather than resolving them. Prove any change against a real symlink.
+export function reapCodexHome(key) {
+    const preserved = preserveCodexRollouts(key);
+    rmSync(codexHomeDir(key), { recursive: true, force: true });
+    return preserved;
+}
+// Built from character codes, not a literal \u escape range in source - see the reference on why.
+const CONTROL_CHAR = new RegExp(`[${String.fromCharCode(0)}-${String.fromCharCode(0x1f)}${String.fromCharCode(0x7f)}]`, "g");
+function tomlEscape(s, { allowLiteralNewline }) {
+    // Order matters: backslash/quote first, or the \u-escapes below get double-escaped.
+    const backslashAndQuote = s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+    return backslashAndQuote.replace(CONTROL_CHAR, (ch) => {
+        if (allowLiteralNewline && ch === "\n")
+            return ch;
+        if (ch === "\t")
+            return "\\t";
+        if (ch === "\n")
+            return "\\n";
+        if (ch === "\r")
+            return "\\r";
+        return `\\u${ch.codePointAt(0).toString(16).padStart(4, "0")}`;
+    });
+}
+// Points at kickoff.js directly, never the `hive` PATH shim: this hook runs in the minimal-PATH
+// environments hookEntry already warns about.
+function kickoffHookEntry() {
+    const kickoffScript = join(dirname(fileURLToPath(import.meta.url)), "kickoff.js");
+    const node = shellQuote(process.execPath);
+    return { hooks: [{ type: "command", command: `${node} ${shellQuote(kickoffScript)} --codex` }] };
+}
+function tomlString(s) {
+    return `"${tomlEscape(s, { allowLiteralNewline: false })}"`;
+}
+function tomlStringArray(items) {
+    return `[${items.map(tomlString).join(", ")}]`;
+}
+// Verified accepted by codex 0.149.0 under --strict-config.
+const HIVE_DEFAULT_STATUS_LINE = ["context-used"];
+// null is the ordinary case (no config yet, or TOML codex would reject), never an error.
+function readRealConfig(realConfigPath) {
+    if (!existsSync(realConfigPath))
+        return null;
+    try {
+        return parseToml(readFileSync(realConfigPath, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+// ONLY [tui].status_line, never the rest of that table: it also carries model_availability_nux,
+// which is not a display key.
+function realStatusLine(realConfig) {
+    const statusLine = realConfig?.tui?.status_line;
+    if (!Array.isArray(statusLine) || !statusLine.every((v) => typeof v === "string"))
+        return null;
+    return statusLine;
+}
+// Top level, never under [tui]. null means "not set", so the caller omits the key and codex
+// applies its own default rather than this module writing a partial one.
+function realTopLevelInteger(realConfig, key) {
+    const value = realConfig?.[key];
+    return typeof value === "number" && Number.isInteger(value) ? value : null;
+}
+function tomlMultilineString(s) {
+    // No trailing \n before the closing """, unlike the leading one - round-trips to the exact input.
+    return `"""\n${tomlEscape(s, { allowLiteralNewline: true })}"""`;
+}
+// codex has no AGENTS.local.md/CLAUDE.local.md of its own, so this order mirrors its real
+// AGENTS.md-then-project_doc_fallback_filenames precedence rather than inventing a new one.
+const LOCAL_OVERRIDE_FILENAMES = ["AGENTS.local.md", "CLAUDE.local.md"];
+function readLocalOverride(projectRoot) {
+    for (const name of LOCAL_OVERRIDE_FILENAMES) {
+        const path = join(projectRoot, name);
+        try {
+            return { path, text: readFileSync(path, "utf8") };
+        }
+        catch (e) {
+            if (e.code !== "ENOENT")
+                throw e;
+        }
+    }
+    return null;
+}
+// Names the primary checkout on purpose: a worktree cwd has no copy of this gitignored file, so a
+// worker reading its own brief must not go looking for one under its own path.
+function localOverrideHeading(path) {
+    return `# Repo-local instructions from ${path} (the primary checkout's gitignored file; a worktree cwd has no copy, so do not look for it under your own path)`;
+}
+export function codexInstructionsPhrase(layers) {
+    return layers.length ? `instructions: ${layers.join(", ")}` : undefined;
+}
+// Must be written before any [section] header, or TOML nests it inside whichever table precedes it -
+// accepted silently, delivered to nobody. See tmux-and-panes.md, "the brief-delivery TOML trap".
+function configToml(input) {
+    return ([
+        `developer_instructions = ${tomlMultilineString(input.developerInstructions)}`,
+        // hive's own default, not copied: without it a worker in an AGENTS.md-less project reads no
+        // project doc at all.
+        `project_doc_fallback_filenames = ${tomlStringArray(["CLAUDE.md"])}`,
+        // Copied when set, never defaulted: hive cannot choose a context window on anyone's behalf.
+        ...(input.modelContextWindow !== null ? [`model_context_window = ${input.modelContextWindow}`] : []),
+        ...(input.modelAutoCompactTokenLimit !== null
+            ? [`model_auto_compact_token_limit = ${input.modelAutoCompactTokenLimit}`]
+            : []),
+        "",
+        `[projects.${tomlString(input.projectRoot)}]`,
+        `trust_level = "trusted"`,
+        "",
+        `[mcp_servers.hive]`,
+        `command = ${tomlString(input.nodeBin)}`,
+        `args = [${tomlString(input.indexJs)}]`,
+        "",
+        `[mcp_servers.hive.env]`,
+        `HIVE_AGENT_ID = ${tomlString(input.actorId)}`,
+        "",
+        // Only accepted under [tui]; a top-level status_line is an unknown field to --strict-config.
+        `[tui]`,
+        `status_line = ${tomlStringArray(input.statusLine)}`,
+    ].join("\n") + "\n");
+}
+// Pure on purpose: agent_resume reuses it against an EXISTING home, so it must not write.
+export function codexLaunchArgs(cwd) {
+    const root = gitPrimaryRoot(cwd);
+    const commonDir = root ? join(root, ".git") : null;
+    return [
+        // Declining review of hive's OWN generated hooks.json, not a stranger's - see the reference.
+        "--dangerously-bypass-hook-trust",
+        // NOT parity with claude's posture, and --add-dir is NOT containment - see the reference.
+        "--dangerously-bypass-approvals-and-sandbox",
+        // Inert alongside the flag above, kept because its value seeds [projects.<root>] trust.
+        ...(commonDir ? ["--add-dir", commonDir] : []),
+    ];
+}
+export function ensureCodexHooksFile(key, options) {
+    // Subagent hooks, not the Stop payload's background_tasks, which codex never sends. No
+    // Notification: unreachable for codex by design (test/codex-notify-unreachable.test.mjs).
+    const hooks = {
+        // A worker's SessionEnd would be a no-op anyway (HIVE_LEAD gates stopProcessesForEndedLead
+        // in src/hook.ts), so a worker home carries no hook that can never act.
+        ...(options.lead ? { SessionStart: [kickoffHookEntry()], SessionEnd: [hookEntry("session_end")] } : {}),
+        ...(!options.lead && options.includePostToolUse ? { PostToolUse: [hookEntry("post_tool_use", "codex")] } : {}),
+        Stop: [hookEntry("stop")],
+        UserPromptSubmit: [hookEntry("prompt")],
+        SubagentStart: [hookEntry("subagent_start")],
+        SubagentStop: [hookEntry("subagent_stop")],
+    };
+    writeFileSync(join(codexHomeDir(key), "hooks.json"), JSON.stringify({ hooks }, null, 2) + "\n");
+    return Object.keys(hooks);
+}
+// Generates a per-worker home: auth.json symlinked (never copied), hooks.json, config.toml.
+export function ensureCodexHome(input) {
+    // Keep every refusing guard ABOVE the first write: a throw after one leaves a partial home the
+    // caller cannot tell from a real one.
+    if (!existsSync(process.execPath)) {
+        throw new Error(`hive: this process's own interpreter (${process.execPath}) no longer exists on disk; refusing to register a codex worker's MCP server under a path that would start nothing.`);
+    }
+    // Read before any write: a real (non-ENOENT) read error here must not leave a partial home.
+    const projectRoot = gitPrimaryRoot(input.cwd) ?? input.cwd;
+    const localOverride = readLocalOverride(projectRoot);
+    const developerInstructions = localOverride
+        ? `${input.brief}\n\n${localOverrideHeading(localOverride.path)}\n\n${localOverride.text}`
+        : input.brief;
+    const home = codexHomeDir(input.key);
+    mkdirSync(home, { recursive: true });
+    const authSource = input.authSource ?? join(homedir(), ".codex", "auth.json");
+    if (!existsSync(authSource)) {
+        throw new Error(`hive: no codex credentials found at ${authSource}; run \`codex login\` before spawning a codex worker.`);
+    }
+    const authLink = join(home, "auth.json");
+    rmSync(authLink, { force: true });
+    symlinkSync(authSource, authLink);
+    // GLOBAL layer: the user's own ~/.codex/AGENTS.md. Symlinked, never copied, for the same reason
+    // auth.json is - a copy goes stale the moment the real file is edited. Absent is not an error:
+    // no link, no message, same as auth.json's presence is required but this is not.
+    const globalSource = join(dirname(authSource), "AGENTS.md");
+    const globalLink = join(home, "AGENTS.md");
+    rmSync(globalLink, { force: true });
+    const hasGlobal = existsSync(globalSource);
+    if (hasGlobal)
+        symlinkSync(globalSource, globalLink);
+    // Touch only the "cleanup" entry, never skills/ itself: codex keeps its own .system there.
+    if (input.lead) {
+        const cleanupSource = join(dirname(fileURLToPath(import.meta.url)), "..", "claude-plugin", "skills", "cleanup");
+        // Codex derives the `hive:cleanup` namespace from the root this link points into, so a
+        // dangling link loses the name a user types, not just the skill. Fail fast.
+        if (!existsSync(cleanupSource)) {
+            throw new Error(`hive: cleanup skill not found at ${cleanupSource}; this checkout's claude-plugin/ is missing or incomplete.`);
+        }
+        const skillsDir = join(home, "skills");
+        mkdirSync(skillsDir, { recursive: true });
+        const cleanupLink = join(skillsDir, "cleanup");
+        rmSync(cleanupLink, { force: true });
+        symlinkSync(cleanupSource, cleanupLink);
+    }
+    const hooksWired = ensureCodexHooksFile(input.key, input);
+    const indexJs = join(dirname(fileURLToPath(import.meta.url)), "index.js");
+    const realConfigPath = input.realConfigSource ?? join(homedir(), ".codex", "config.toml");
+    const realConfig = readRealConfig(realConfigPath);
+    const statusLine = realStatusLine(realConfig) ?? HIVE_DEFAULT_STATUS_LINE;
+    const modelContextWindow = realTopLevelInteger(realConfig, "model_context_window");
+    const modelAutoCompactTokenLimit = realTopLevelInteger(realConfig, "model_auto_compact_token_limit");
+    writeFileSync(join(home, "config.toml"), configToml({
+        developerInstructions,
+        projectRoot,
+        nodeBin: process.execPath,
+        indexJs,
+        actorId: input.actorId,
+        statusLine,
+        modelContextWindow,
+        modelAutoCompactTokenLimit,
+    }));
+    const instructionLayers = [...(hasGlobal ? ["global"] : []), ...(localOverride ? ["local"] : [])];
+    return { extraArgs: codexLaunchArgs(input.cwd), hooksWired, instructionLayers };
+}

package/dist/config.js

@@ -0,0 +1,72 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { storeDir } from "./dataDir.js";
+export const ATTACH_MODES = ["auto", "raw", "control"];
+export function isAttachMode(value) {
+    return ATTACH_MODES.includes(value);
+}
+export const AUTO_ATTACH_MODES = ["auto", "on", "off"];
+export function isAutoAttach(value) {
+    return AUTO_ATTACH_MODES.includes(value);
+}
+function configPath() {
+    return join(storeDir(), "config.json");
+}
+function readConfig() {
+    const path = configPath();
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch {
+        return {};
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed !== null && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function envAttachMode() {
+    const value = process.env.HIVE_ATTACH_MODE;
+    return isAttachMode(value) ? value : null;
+}
+function envAutoAttach() {
+    const value = process.env.HIVE_AUTO_ATTACH;
+    if (value === "0")
+        return "off";
+    return isAutoAttach(value) ? value : null;
+}
+export function resolvedAttachMode() {
+    const fromEnv = envAttachMode();
+    if (fromEnv)
+        return { mode: fromEnv, source: "env" };
+    const value = readConfig().attach;
+    return isAttachMode(value) ? { mode: value, source: "config" } : { mode: "auto", source: "detection" };
+}
+export function attachMode() {
+    return resolvedAttachMode().mode;
+}
+export function resolvedAutoAttach() {
+    const fromEnv = envAutoAttach();
+    if (fromEnv)
+        return { value: fromEnv, source: "env" };
+    const value = readConfig().autoAttach;
+    return isAutoAttach(value)
+        ? { value, source: "config" }
+        : { value: "auto", source: "detection" };
+}
+export function setAttachMode(mode) {
+    const config = readConfig();
+    config.attach = mode;
+    mkdirSync(storeDir(), { recursive: true });
+    writeFileSync(configPath(), `${JSON.stringify(config, null, 2)}\n`);
+}
+export function setAutoAttach(value) {
+    const config = readConfig();
+    config.autoAttach = value;
+    mkdirSync(storeDir(), { recursive: true });
+    writeFileSync(configPath(), `${JSON.stringify(config, null, 2)}\n`);
+}

package/dist/context.js

@@ -0,0 +1,256 @@
+import { execFileSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { userInfo } from "node:os";
+import { basename, dirname, resolve, sep } from "node:path";
+import { db } from "./db.js";
+let selectedId = null;
+let cachedActorId = null;
+let lastTouchMs = 0;
+let pendingRegistrationNotice = null;
+export function takeRegistrationNotice() {
+    const notice = pendingRegistrationNotice;
+    pendingRegistrationNotice = null;
+    return notice;
+}
+export const TOUCH_INTERVAL_MS = 30_000;
+export function currentActor() {
+    if (cachedActorId) {
+        if (Date.now() - lastTouchMs > TOUCH_INTERVAL_MS) {
+            db.prepare("UPDATE actors SET last_seen_at = datetime('now') WHERE id = ?").run(cachedActorId);
+            lastTouchMs = Date.now();
+        }
+        return cachedActorId;
+    }
+    const envId = process.env.HIVE_AGENT_ID;
+    const id = envId ?? `user:${userInfo().username}`;
+    const name = process.env.HIVE_AGENT_NAME ?? id;
+    const kind = envId ? "agent" : "human";
+    db.prepare(`INSERT INTO actors (id, name, kind, tmux_pane) VALUES (?, ?, ?, ?)
+     ON CONFLICT(id) DO UPDATE SET
+       last_seen_at = datetime('now'),
+       tmux_pane = COALESCE(excluded.tmux_pane, actors.tmux_pane)`).run(id, name, kind, process.env.TMUX_PANE ?? null);
+    cachedActorId = id;
+    lastTouchMs = Date.now();
+    return id;
+}
+export function listProjects() {
+    return db.prepare("SELECT * FROM projects ORDER BY id").all();
+}
+export function getProject(id) {
+    return db.prepare("SELECT * FROM projects WHERE id = ?").get(id);
+}
+export function getProjectByPath(path) {
+    return db.prepare("SELECT * FROM projects WHERE path = ?").get(path);
+}
+export function addProject(path, name) {
+    let resolved;
+    try {
+        resolved = realpathSync(path ?? process.cwd());
+    }
+    catch {
+        throw new Error(`Path does not exist: ${path}`);
+    }
+    const existing = db.prepare("SELECT * FROM projects WHERE path = ?").get(resolved);
+    if (existing)
+        return existing;
+    db.prepare("INSERT INTO projects (name, path) VALUES (?, ?) ON CONFLICT(path) DO NOTHING").run(name ?? basename(resolved), resolved);
+    return db.prepare("SELECT * FROM projects WHERE path = ?").get(resolved);
+}
+function assertAccessible(id) {
+    const project = getProject(id);
+    if (!project)
+        throw new Error(`Unknown project_id ${id}. Call project_list to see options.`);
+    if (projectLock && id !== resolveHomeProject()) {
+        throw new Error(`This session is locked to project ${resolveHomeProject()} (HIVE_PROJECT_LOCK=1). Cross-project access is disabled.`);
+    }
+    return project;
+}
+export function selectProjectById(id) {
+    const project = assertAccessible(id);
+    selectedId = id;
+    return project;
+}
+function isSameOrUnder(path, root) {
+    return path === root || path.startsWith(root + sep);
+}
+function bestPrefixMatch(projects, dir) {
+    let best = null;
+    for (const p of projects) {
+        if (isSameOrUnder(dir, p.path)) {
+            if (!best || p.path.length > best.path.length)
+                best = p;
+        }
+    }
+    return best;
+}
+export function registeredAncestor(dir) {
+    const projects = listProjects().filter((project) => project.path !== dir);
+    return bestPrefixMatch(projects, dir);
+}
+export function gitPrimaryRoot(dir) {
+    try {
+        const { GIT_DIR: _gitDir, GIT_COMMON_DIR: _gitCommonDir, GIT_WORK_TREE: _gitWorkTree, ...env } = process.env;
+        const commonDir = execFileSync("git", ["rev-parse", "--git-common-dir"], {
+            cwd: dir,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 2000,
+            env,
+        }).trim();
+        const resolvedCommonDir = resolve(dir, commonDir);
+        if (basename(resolvedCommonDir) !== ".git")
+            return null;
+        return realpathSync(dirname(resolvedCommonDir));
+    }
+    catch {
+        return null;
+    }
+}
+function gitDirs(dir) {
+    try {
+        const { GIT_DIR: _gitDir, GIT_COMMON_DIR: _gitCommonDir, GIT_WORK_TREE: _gitWorkTree, ...env } = process.env;
+        const out = execFileSync("git", ["rev-parse", "--git-dir", "--git-common-dir"], {
+            cwd: dir,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 2000,
+            env,
+        })
+            .trim()
+            .split("\n");
+        if (out.length !== 2)
+            return null;
+        return {
+            gitDir: realpathSync(resolve(dir, out[0])),
+            commonDir: realpathSync(resolve(dir, out[1])),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function isLinkedWorktree(dir) {
+    return linkedWorktreePrimaryRoot(dir) !== null;
+}
+export function linkedWorktreePrimaryRoot(dir) {
+    const dirs = gitDirs(dir);
+    if (dirs === null || dirs.gitDir === dirs.commonDir)
+        return null;
+    return dirname(dirs.commonDir);
+}
+function hasStricterMatch(projects, directPath) {
+    return projects.some((p) => p.path !== directPath && isSameOrUnder(p.path, directPath));
+}
+function detectFromDir(dir) {
+    const projects = listProjects();
+    const direct = bestPrefixMatch(projects, dir);
+    if (direct && !hasStricterMatch(projects, direct.path)) {
+        return direct;
+    }
+    const root = gitPrimaryRoot(dir);
+    const git = root ? bestPrefixMatch(projects, root) : null;
+    if (git && (!direct || isSameOrUnder(git.path, direct.path))) {
+        return git;
+    }
+    return direct;
+}
+function detectFromCwd() {
+    return findProjectForDir(process.cwd());
+}
+export function findProjectForDir(dir) {
+    let resolved;
+    try {
+        resolved = realpathSync(dir);
+    }
+    catch {
+        return null;
+    }
+    return detectFromDir(resolved);
+}
+export function findProjectForCwd() {
+    return findProjectForDir(process.cwd());
+}
+const projectLock = process.env.HIVE_PROJECT_LOCK === "1";
+let pinFailure = null;
+function projectPathGuard(id) {
+    const expected = process.env.HIVE_PROJECT_PATH?.trim();
+    if (!expected)
+        return id;
+    const project = getProject(id);
+    let resolvedExpected;
+    try {
+        resolvedExpected = realpathSync(expected);
+    }
+    catch {
+        resolvedExpected = expected;
+    }
+    if (resolvedExpected !== project.path) {
+        pinFailure = new Error(`This worker's project pin (agents row -> project ${id} at "${project.path}") disagrees with its spawn path HIVE_PROJECT_PATH="${expected}". The store may have been swapped underneath a live worker - restart it.`);
+        throw pinFailure;
+    }
+    return id;
+}
+export function agentProjectPin() {
+    if (pinFailure)
+        throw pinFailure;
+    const actorId = process.env.HIVE_AGENT_ID;
+    if (!actorId || process.env.HIVE_PROJECT_LOCK !== "1")
+        return null;
+    const row = db
+        .prepare("SELECT project_id, status FROM agents WHERE actor_id = ? ORDER BY (status = 'running') DESC, id DESC LIMIT 1")
+        .get(actorId);
+    if (!row) {
+        pinFailure = new Error(`HIVE_AGENT_ID=${actorId} names no agents row. This worker's store does not know it - most likely a rebuilt store. Restarting in this pane will not help: HIVE_AGENT_ID and HIVE_PROJECT_LOCK are set in the pane's own environment and survive a restart. Run "unset HIVE_AGENT_ID HIVE_PROJECT_LOCK HIVE_PROJECT_PATH" first, or open a new pane.`);
+        throw pinFailure;
+    }
+    if (row.status === "closed") {
+        const expectedPath = process.env.HIVE_PROJECT_PATH?.trim();
+        if (!expectedPath)
+            return null;
+        const byCwd = findProjectForCwd();
+        if (byCwd)
+            return byCwd.id;
+        const byPath = findProjectForDir(expectedPath);
+        if (byPath)
+            return byPath.id;
+        pinFailure = new Error(`HIVE_AGENT_ID=${actorId}'s agents row is closed. Its cwd resolves to no project, and its spawn path HIVE_PROJECT_PATH="${expectedPath}" no longer resolves to one either. Unset HIVE_AGENT_ID HIVE_PROJECT_LOCK HIVE_PROJECT_PATH in this pane, or start a new one.`);
+        throw pinFailure;
+    }
+    return projectPathGuard(row.project_id);
+}
+function resolveHomeProject() {
+    if (selectedId != null)
+        return selectedId;
+    const pinned = agentProjectPin();
+    if (pinned != null) {
+        selectedId = pinned;
+        return selectedId;
+    }
+    const detected = detectFromCwd();
+    if (detected != null) {
+        selectedId = detected.id;
+        return selectedId;
+    }
+    const created = addProject(gitPrimaryRoot(process.cwd()) ?? process.cwd());
+    selectedId = created.id;
+    pendingRegistrationNotice = created;
+    return selectedId;
+}
+export function effectiveProjectId(override) {
+    if (override != null) {
+        assertAccessible(override);
+        return override;
+    }
+    return resolveHomeProject();
+}
+export function resolveProject(override) {
+    return getProject(effectiveProjectId(override));
+}
+export function trySelectedProject() {
+    try {
+        return getProject(effectiveProjectId()) ?? null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/contextCheckpoint.js

@@ -0,0 +1,55 @@
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { storeDir } from "./dataDir.js";
+import { readContextFill } from "./transcript.js";
+export function contextCheckpointAdditionalContext(actorId, thresholdPercent, fill) {
+    if (!actorId.startsWith("agent:") || !Number.isInteger(thresholdPercent) || thresholdPercent < 1 || thresholdPercent > 100)
+        return null;
+    if (!Number.isSafeInteger(fill.used_tokens) || fill.used_tokens < 0 || !Number.isSafeInteger(fill.window_tokens) || fill.window_tokens <= 0)
+        return null;
+    try {
+        const path = join(storeDir(), "context-checkpoints", `${encodeURIComponent(actorId)}.fired`);
+        if (fill.used_tokens * 100 < fill.window_tokens * thresholdPercent) {
+            if (existsSync(path))
+                unlinkSync(path);
+            return null;
+        }
+        if (existsSync(path))
+            return null;
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, "", { flag: "wx", mode: 0o600 });
+        return `Context is at ${fill.used_percent}% of its ${fill.window_tokens}-token window; the configured checkpoint threshold is ${thresholdPercent}%.`;
+    }
+    catch {
+        return null;
+    }
+}
+export function runContextCheckpointHook(kind) {
+    const thresholdText = process.env.HIVE_CONTEXT_CHECKPOINT_PERCENT;
+    if (!thresholdText || !/^\d+$/.test(thresholdText))
+        return;
+    const threshold = Number(thresholdText);
+    if (!Number.isInteger(threshold) || threshold < 1 || threshold > 100)
+        return;
+    const actorId = process.env.HIVE_AGENT_ID ?? "";
+    if (!actorId.startsWith("agent:") || (kind !== "claude" && kind !== "codex"))
+        return;
+    try {
+        const payload = JSON.parse(readFileSync(0, "utf8"));
+        if (payload === null || typeof payload !== "object" || Array.isArray(payload))
+            return;
+        const fill = readContextFill(kind, {
+            actor_id: actorId,
+            cwd: typeof payload.cwd === "string" ? payload.cwd : "",
+            session_id: typeof payload.session_id === "string" ? payload.session_id : "",
+            transcript_path: typeof payload.transcript_path === "string" ? payload.transcript_path : "",
+        });
+        if (fill === null)
+            return;
+        const additionalContext = contextCheckpointAdditionalContext(actorId, threshold, fill);
+        if (additionalContext !== null) {
+            process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext } }));
+        }
+    }
+    catch { }
+}