@cmgmyr/hive 0.1.0

package/dist/sessionProbe.js

@@ -0,0 +1,131 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { nodeRangeForNodeApi, requiredNodeApi } from "./abi.js";
+import { cliPath, dispatcherPath, readDispatcher } from "./dispatcher.js";
+const PROBE_TIMEOUT_MS = 10_000;
+const probeEntry = () => fileURLToPath(new URL("./abiProbe.js", import.meta.url));
+export function reexecTarget() {
+    const path = readDispatcher(dispatcherPath())?.node ?? null;
+    if (path === null)
+        return null;
+    if (!existsSync(path))
+        return { path, state: "gone" };
+    const probe = probeInterpreter(path);
+    if (!probe.probed)
+        return { path, state: "unverified", detail: probe.detail };
+    return probe.ok ? { path, state: "loads" } : { path, state: "cannot", detail: probe.detail };
+}
+export function probeSessionInterpreter(dir) {
+    return runProbe("node", dir);
+}
+export function probeInterpreter(node) {
+    return runProbe(node, undefined);
+}
+function runProbe(command, cwd) {
+    const unprobed = (detail) => ({ probed: false, detail });
+    const result = spawnSync(command, [probeEntry()], {
+        cwd,
+        env: process.env,
+        encoding: "utf8",
+        timeout: PROBE_TIMEOUT_MS,
+        killSignal: "SIGKILL",
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    if (result.error)
+        return unprobed(`could not run \`${command}\`: ${result.error.message}`);
+    let parsed;
+    try {
+        parsed = JSON.parse(result.stdout.trim());
+    }
+    catch {
+        const noise = (result.stderr || result.stdout).trim().split("\n")[0] ?? "";
+        return unprobed(`\`${command}\` did not answer the probe (exit ${result.status ?? "killed"})` +
+            (noise ? `: ${noise.slice(0, 200)}` : ""));
+    }
+    return {
+        probed: true,
+        ok: parsed.ok,
+        execPath: parsed.execPath,
+        version: parsed.version,
+        detail: parsed.detail,
+    };
+}
+export function sessionStartVerdict(probe, target) {
+    if (!probe.probed) {
+        return {
+            level: "warn",
+            lines: [
+                "hive cannot say whether a session starting there would work.",
+                probe.detail,
+            ],
+        };
+    }
+    const runs = `a session there runs ${probe.execPath} (${probe.version})`;
+    if (probe.ok)
+        return { level: "info", lines: [`${runs}, which loads hive's addon`] };
+    const cannot = [`${runs}, which CANNOT load hive's addon.`, probe.detail];
+    const hookOnly = [
+        "Either way that is the hook only. A bare `node` in hive's MCP registration resolves per",
+        "directory as well, and nothing re-execs that; doctor reports it separately.",
+    ];
+    const pinned = target();
+    if (pinned !== null && pinned.state !== "gone" && pinned.path !== probe.execPath) {
+        if (pinned.state === "loads") {
+            return {
+                level: "warn",
+                lines: [
+                    ...cannot,
+                    "The SessionStart hook survives this by re-execing into the interpreter the dispatcher",
+                    `pins, ${pinned.path}, and hive loaded the addon under that interpreter to check.`,
+                    "If a version manager retires it, a session here loses hive's session-start digest and",
+                    "prints the addon banner instead, naming the Node rather than this project.",
+                    ...hookOnly,
+                ],
+            };
+        }
+        if (pinned.state === "cannot") {
+            return {
+                level: "warn",
+                lines: [
+                    ...cannot,
+                    `The SessionStart hook re-execs into ${pinned.path}, which CANNOT load the addon either:`,
+                    pinned.detail,
+                    "So the re-exec does not rescue this: a session starting there prints the addon banner",
+                    "after re-execing, and nothing in that banner names this project or that pin.",
+                    ...hookOnly,
+                ],
+            };
+        }
+        return {
+            level: "warn",
+            lines: [
+                ...cannot,
+                `The SessionStart hook would re-exec into ${pinned.path}, but hive could not verify that`,
+                `interpreter, so whether that rescues a session here is unknown: ${pinned.detail}`,
+                ...hookOnly,
+            ],
+        };
+    }
+    const why = pinned === null
+        ? ["There is no dispatcher at all, so the SessionStart hook has nothing to re-exec into."]
+        : pinned.state === "gone"
+            ? [`The dispatcher pins ${pinned.path}, which is not on disk, so the SessionStart hook has`, "nothing to re-exec into."]
+            : ["The dispatcher pins this same interpreter, so re-execing into it would change nothing."];
+    return {
+        level: "warn",
+        lines: [
+            ...cannot,
+            ...why,
+            "A session starting there gets the addon banner instead of hive's session-start digest.",
+            "Give the hook something to re-exec into, naming the interpreter (setup pins whatever Node",
+            "runs it, so the way out always names one):",
+            `  <a Node matching ${nodeRange()}> "${cliPath()}" setup`,
+            ...hookOnly,
+        ],
+    };
+}
+function nodeRange() {
+    const need = requiredNodeApi();
+    return (need === null ? null : nodeRangeForNodeApi(need)) ?? "that Node-API level";
+}

package/dist/slug.js

@@ -0,0 +1,29 @@
+export const SLUG_MAX_LEN = 40;
+const CONTROL_CHARS_RE = /[\x00-\x1F\x7F]+/g;
+function stripControlChars(text) {
+    return text.replace(CONTROL_CHARS_RE, " ");
+}
+const ELLIPSIS = "…";
+const CUT_BUDGET = SLUG_MAX_LEN - 1;
+export function cutToUnitBudget(text, budget) {
+    let cut = "";
+    for (const ch of text) {
+        if (cut.length + ch.length > budget)
+            break;
+        cut += ch;
+    }
+    return cut;
+}
+export function fallbackSlug(title) {
+    const trimmed = stripControlChars(title).trim();
+    if (trimmed.length <= SLUG_MAX_LEN)
+        return trimmed;
+    const cut = cutToUnitBudget(trimmed, CUT_BUDGET);
+    const lastSpace = cut.lastIndexOf(" ");
+    return (lastSpace > CUT_BUDGET / 2 ? cut.slice(0, lastSpace) : cut) + ELLIPSIS;
+}
+// Every field interpolated into text that hive types into a pane goes through here. A raw control byte
+// reaches tmux as a keystroke rather than as text, so a \r in an interpolated name or body submits the
+// prompt early and splits the message; flattening half a string is worse than none, because the next
+// reader stops looking. Wider than stripControlChars above, which is the slug path and stays as it is.
+export const flatten = (text) => text.replace(/[\p{Cc}\p{Cf}]/gu, " ").replace(/\s+/g, " ").trim();

package/dist/spawn.js

@@ -0,0 +1,370 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { preservedRolloutPath, reapCodexHome } from "./codexHome.js";
+import { getProject } from "./context.js";
+import { dataDir, db } from "./db.js";
+import { loadProjectYml } from "./projectYml.js";
+import { applyLayout, claimInitialWindow, createWindow, DEFAULT_LAYOUT, ensureSession, crossServerRefusal, findProcessesWindow, findProjectWindow, isPaneTarget, panePid, paneWindow, PROCESSES_LAYOUT, processesPaneTitle, processesWindowName, retainOnExitArgs, rowLive, sessionName, setPaneTitle, makeProcessesWindow, tmux, tmuxSocketPath, untrustedTmuxServer, waitForPaneEstablished, windowLayout, windowOwner, windowTitle, } from "./tmux.js";
+export function withWindowClaim(claim) {
+    if (db.inTransaction) {
+        throw new Error("withWindowClaim was called from inside an already-open transaction. better-sqlite3 nests a " +
+            "transaction inside another one as a no-op SAVEPOINT rather than throwing, so this call would " +
+            "take no writer slot of its own and the machine-wide window-claim exclusion would silently " +
+            "disappear - no error, no failing test, just the read-then-create race back. Move the outer " +
+            "transaction so it does not wrap this call, or move the work it does inside this claim instead: " +
+            "withWindowClaim must be the outermost transaction on its call stack.");
+    }
+    return db.transaction(claim).immediate();
+}
+export function splitTargetWindow(session, projectId, parentActor) {
+    const parent = db
+        .prepare("SELECT tmux_target, tmux_socket FROM agents WHERE actor_id = ? AND status = 'running' ORDER BY id DESC LIMIT 1")
+        .get(parentActor);
+    if (parent && rowLive(parent.tmux_socket, parent.tmux_target) === true) {
+        const window = paneWindow(parent.tmux_target);
+        if (window)
+            return `${session}:${window.split(":")[1]}`;
+    }
+    return findProjectWindow(session, projectId) ?? null;
+}
+export function buildEnvFlags(env) {
+    return Object.entries(env).flatMap(([k, v]) => ["-e", `${k}=${v}`]);
+}
+function agentIdentityEnv(actorId, name, projectPath) {
+    return {
+        HIVE_AGENT_ID: actorId,
+        HIVE_AGENT_NAME: name,
+        HIVE_PROJECT_LOCK: "1",
+        HIVE_PROJECT_PATH: projectPath,
+        HIVE_DATA_DIR: dataDir,
+        HIVE_LEAD: "",
+    };
+}
+function recordPane(agentId, target, socket) {
+    return (db
+        .prepare("UPDATE agents SET tmux_target = ?, tmux_socket = ?, pane_pid = ? WHERE id = ? AND status = 'running'")
+        .run(target, socket, panePid(target), agentId).changes > 0);
+}
+// Two callers, one meaning: whatever is left in the window re-tiles to the layout it was arranged
+// with. agent_close kills a worker's pane through this; stopProcess (src/processes.ts) is the only
+// thing that kills a command's, and its graceful leg loses the pane without a kill at all - which is
+// why the re-tile is reachable on its own.
+export function relayoutAfterPaneLeft(window) {
+    if (!window)
+        return;
+    const ownerId = windowOwner(window);
+    const ownerProject = ownerId != null ? getProject(ownerId) : undefined;
+    applyLayout(window, windowLayout(window) ?? (ownerProject ? loadProjectYml(ownerProject.path).config?.layout : undefined) ?? DEFAULT_LAYOUT);
+}
+export function killAgentPane(target) {
+    const pane = isPaneTarget(target);
+    const window = pane ? paneWindow(target) : null;
+    tmux(pane ? "kill-pane" : "kill-window", "-t", target);
+    relayoutAfterPaneLeft(window);
+}
+export function discardOrphanedPane(target) {
+    try {
+        waitForPaneEstablished(target);
+        tmux("kill-pane", "-t", target);
+    }
+    catch {
+    }
+}
+const paneRacedRetirement = (agentId) => new Error(`Agent ${agentId}'s row was retired (closed or parked) while its pane was being created, so the pane was ` +
+    "discarded rather than recorded against a row that is no longer running. Nothing is left running for it. " +
+    "Re-read the row with agent_status and resume or spawn again if that was not what you intended.");
+export function asNameClash(e, name) {
+    const err = e;
+    const message = err.message ?? "";
+    if (err.code === "SQLITE_CONSTRAINT_UNIQUE" &&
+        (message.includes("agents.name") || message.includes("idx_agents_running_name"))) {
+        if (name === LEAD_NAME) {
+            return new Error("Another `hive lead` won the race to start this project's lead session. Re-run `hive lead`; " +
+                "it will find and reuse the row that invocation just created.");
+        }
+        return new Error(`A running agent named "${name}" already exists. Pick another name.`);
+    }
+    return e;
+}
+export const LEAD_KIND = "lead";
+export const LEAD_ACTOR_PREFIX = `${LEAD_KIND}:`;
+export const isLeadActorId = (actorId) => actorId.startsWith(LEAD_ACTOR_PREFIX);
+export const mintLeadActorId = (agentId) => `${LEAD_ACTOR_PREFIX}${agentId}`;
+export const isRunningLeadActor = (actorId) => !!db.prepare("SELECT 1 FROM agents WHERE actor_id = ? AND kind = ? AND status = 'running'").get(actorId, LEAD_KIND);
+export const LEAD_NAME = LEAD_KIND;
+export const isReservedAgentName = (name) => name.toLowerCase() === LEAD_NAME;
+export function upsertActor(actorId, name, kind) {
+    db.prepare(`INSERT INTO actors (id, name, kind) VALUES (?, ?, ?)
+     ON CONFLICT(id) DO UPDATE SET name = excluded.name, last_seen_at = datetime('now')`).run(actorId, name, kind);
+}
+function placeAgentPane(session, spec, envFlags, commandString, title) {
+    let landedInProjectId = null;
+    let layoutApplied = false;
+    let inProcessesWindow = false;
+    const target = withWindowClaim(() => {
+        const windowName = spec.placement === "split" ? spec.projectName : title;
+        const windowOwnerId = spec.placement === "split" ? spec.projectId : null;
+        const started = ensureSession(session, spec.cwd, { envFlags, command: commandString });
+        if (started.created) {
+            // Deliberate for placement "processes" too: this pane IS the new session's initial window, so it
+            // takes that window rather than a tile. The caller reports it; `hive hide` moves it in later.
+            return claimInitialWindow(started, windowName, windowOwnerId).pane;
+        }
+        const splitInto = (window, layout) => {
+            const pane = tmux("split-window", "-d", "-P", "-F", "#{pane_id}", "-t", window, "-c", spec.cwd, ...envFlags, commandString, ...(spec.retainOnExit ? retainOnExitArgs(window) : []));
+            applyLayout(window, layout);
+            layoutApplied = true;
+            return pane;
+        };
+        if (spec.placement === "processes") {
+            let pane;
+            const existing = findProcessesWindow(session, spec.projectId);
+            if (existing) {
+                pane = splitInto(existing, PROCESSES_LAYOUT);
+            }
+            else {
+                const made = createWindow(session, processesWindowName(spec.projectName), spec.cwd, envFlags, commandString, null, true, spec.retainOnExit ?? false);
+                makeProcessesWindow(made.window, spec.projectId);
+                pane = made.pane;
+            }
+            setPaneTitle(pane, processesPaneTitle(spec.projectName, spec.name));
+            inProcessesWindow = true;
+            return pane;
+        }
+        if (spec.placement === "split") {
+            const found = splitTargetWindow(session, spec.projectId, spec.parentActor);
+            if (found) {
+                const pane = splitInto(found, spec.layout ?? DEFAULT_LAYOUT);
+                const owner = windowOwner(found);
+                if (owner !== null && owner !== spec.projectId)
+                    landedInProjectId = owner;
+                return pane;
+            }
+        }
+        return createWindow(session, windowName, spec.cwd, envFlags, commandString, windowOwnerId, true, spec.retainOnExit ?? false).pane;
+    });
+    return { target, landedInProjectId, layoutApplied, inProcessesWindow };
+}
+export function launchAgent(spec) {
+    if (untrustedTmuxServer())
+        throw crossServerRefusal("spawn");
+    const socket = tmuxSocketPath(process.env.TMUX, process.env.TMUX_TMPDIR);
+    let info;
+    try {
+        info = db
+            .prepare("INSERT INTO agents (project_id, name, command, cwd, kind, parent_actor_id, tmux_socket, session_id, codex_home) " +
+            "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)")
+            .run(spec.projectId, spec.name, typeof spec.commandString === "string" ? spec.commandString : "", spec.cwd, spec.kind, spec.parentActor, socket, spec.sessionId ?? "", spec.codexHome ?? "");
+    }
+    catch (e) {
+        throw asNameClash(e, spec.name);
+    }
+    const agentId = Number(info.lastInsertRowid);
+    const actorId = `${spec.kind}:${agentId}`;
+    let paneUp = false;
+    try {
+        const commandString = typeof spec.commandString === "string" ? spec.commandString : spec.commandString({ agentId, actorId });
+        db.prepare("UPDATE agents SET actor_id = ?, command = ? WHERE id = ?").run(actorId, commandString, agentId);
+        upsertActor(actorId, spec.name, spec.kind);
+        const session = sessionName();
+        const env = spec.kind === "agent"
+            ? { ...spec.env, ...agentIdentityEnv(actorId, spec.name, spec.projectPath) }
+            : spec.env;
+        const envFlags = buildEnvFlags(env);
+        const title = windowTitle(spec.projectName, spec.name);
+        const { target, landedInProjectId, layoutApplied, inProcessesWindow } = placeAgentPane(session, spec, envFlags, commandString, title);
+        paneUp = true;
+        if (!recordPane(agentId, target, socket)) {
+            discardOrphanedPane(target);
+            throw paneRacedRetirement(agentId);
+        }
+        return { agentId, actorId, target, landedInProjectId, layoutApplied, inProcessesWindow };
+    }
+    catch (e) {
+        if (paneUp)
+            throw e;
+        db.prepare("DELETE FROM agents WHERE id = ?").run(agentId);
+        throw e;
+    }
+}
+export const RESUME_FLIP_COLUMNS = [
+    "status",
+    "closed_at",
+    "tmux_target",
+    "pane_pid",
+    "agent_state",
+    "state_changed_at",
+    "parked_at",
+    "parked_branch",
+    "resumed_at",
+    "tmux_socket",
+    "command",
+];
+export function resumeFlipSql() {
+    return ("UPDATE agents SET status = 'running', closed_at = NULL, tmux_target = '', pane_pid = '', " +
+        `agent_state = 'unknown', state_changed_at = NULL, ${PARK_STAMP_CLEARED}, ` +
+        "resumed_at = datetime('now'), tmux_socket = ?, command = ? " +
+        "WHERE id = ? AND status = 'closed'");
+}
+function restoreFlippedRow(agentId, before) {
+    db.prepare(`UPDATE agents SET ${RESUME_FLIP_COLUMNS.map((c) => `${c} = ?`).join(", ")} ` +
+        "WHERE id = ? AND status = 'running' AND tmux_target = ''").run(...RESUME_FLIP_COLUMNS.map((c) => before[c] ?? null), agentId);
+}
+export function resumeAgent(spec) {
+    if (untrustedTmuxServer())
+        throw crossServerRefusal("resume");
+    const socket = tmuxSocketPath(process.env.TMUX, process.env.TMUX_TMPDIR);
+    let flip;
+    const captureBeforeFlip = db.prepare(`SELECT ${RESUME_FLIP_COLUMNS.join(", ")} FROM agents WHERE id = ?`);
+    const flipStatement = db.prepare(resumeFlipSql());
+    try {
+        flip = db
+            .transaction(() => ({
+            before: captureBeforeFlip.get(spec.agentId),
+            changes: flipStatement.run(socket, spec.commandString, spec.agentId).changes,
+        }))
+            .immediate();
+    }
+    catch (e) {
+        const err = e;
+        const message = err.message ?? "";
+        if (err.code === "SQLITE_CONSTRAINT_UNIQUE" &&
+            (message.includes("agents.name") || message.includes("idx_agents_running_name"))) {
+            throw new Error(`Cannot resume agent ${spec.agentId}: a running agent already has the name "${spec.name}". Rename or ` +
+                "close that one first, or resume a different agent_id.");
+        }
+        throw e;
+    }
+    if (flip.changes === 0) {
+        throw new Error(`Agent ${spec.agentId} is not closed - another caller may have resumed it first.`);
+    }
+    let paneUp = false;
+    try {
+        upsertActor(spec.actorId, spec.name, "agent");
+        const envFlags = buildEnvFlags({
+            ...spec.env,
+            ...agentIdentityEnv(spec.actorId, spec.name, spec.projectPath),
+        });
+        const session = sessionName();
+        const title = windowTitle(spec.projectName, spec.name);
+        const { target, landedInProjectId } = placeAgentPane(session, spec, envFlags, spec.commandString, title);
+        paneUp = true;
+        if (!recordPane(spec.agentId, target, socket)) {
+            discardOrphanedPane(target);
+            throw paneRacedRetirement(spec.agentId);
+        }
+        return { target, landedInProjectId };
+    }
+    catch (e) {
+        if (!paneUp) {
+            if (flip.before)
+                restoreFlippedRow(spec.agentId, flip.before);
+            else
+                closeAgentRow(spec.agentId);
+        }
+        throw e;
+    }
+}
+function ownsItsWindow(target, expectedTitle) {
+    try {
+        const [name, projectStamp, owned] = tmux("list-panes", "-t", target, "-F", "#{window_name}\t#{@hive-project-id}\t#{@hive-owned}")
+            .split("\n")[0]
+            .split("\t");
+        return name === expectedTitle && (projectStamp ?? "") === "" && owned === "1";
+    }
+    catch {
+        return false;
+    }
+}
+export function renameAgent(agent, newName, projectName) {
+    try {
+        db.transaction(() => {
+            db.prepare("UPDATE agents SET name = ? WHERE id = ?").run(newName, agent.id);
+            db.prepare("UPDATE actors SET name = ? WHERE id = ?").run(newName, agent.actor_id);
+        })();
+    }
+    catch (e) {
+        throw asNameClash(e, newName);
+    }
+    if (projectName !== null && ownsItsWindow(agent.tmux_target, windowTitle(projectName, agent.name))) {
+        try {
+            tmux("rename-window", "-t", agent.tmux_target, windowTitle(projectName, newName));
+        }
+        catch {
+        }
+    }
+}
+export function branchAt(cwd) {
+    const git = (args) => {
+        try {
+            return execFileSync("git", args, {
+                cwd,
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "ignore"],
+                timeout: 2000,
+            }).trim();
+        }
+        catch {
+            return null;
+        }
+    };
+    const branch = git(["rev-parse", "--abbrev-ref", "HEAD"]);
+    if (branch === null)
+        return "";
+    if (branch !== "HEAD")
+        return branch;
+    return git(["rev-parse", "--short", "HEAD"]) ?? "";
+}
+export function parkAgentRow(agentId, expectedTmuxTarget, branch) {
+    return db
+        .prepare("UPDATE agents SET status = 'closed', closed_at = datetime('now'), parked_at = datetime('now'), " +
+        "parked_branch = ? WHERE id = ? AND status = 'running' AND tmux_target = ? RETURNING parked_at")
+        .get(branch, agentId, expectedTmuxTarget)?.parked_at;
+}
+export const PARK_STAMP_CLEARED = "parked_at = '', parked_branch = ''";
+export function releaseParkRow(agentId) {
+    return (db
+        .prepare(`UPDATE agents SET ${PARK_STAMP_CLEARED} WHERE id = ? AND status = 'closed' AND parked_at != ''`)
+        .run(agentId).changes > 0);
+}
+// Row status alone is not the orphan test: a PARKED row is `status = 'closed'` too
+// (parkAgentRow above), and agent_park expects to resume it, cold-cache and all. `parked_at = ''`
+// is named explicitly rather than left to fall out of "closed" incidentally: codex can now be
+// parked too (harnessFor("codex").supportsResume, todo 563), exactly as this predicate already
+// assumed some non-claude harness eventually would - deriving the exclusion from harness capability
+// instead would have made this reap query's correctness depend on a table this file does not own.
+//
+// No conditional-UPDATE claim guards this, unlike closeAgentRow's "the conditional UPDATE is the
+// claim" - a deliberate difference, not a gap. That pattern earns its keep against an OBSERVABLE
+// side effect: a wake fired twice types into a pane twice. A reap has none - two instances racing
+// the same directory produce one deleted directory (rmSync's force:true swallows ENOENT even mid
+// recursive delete, not just on the top-level path), and the loser's `codex_home` update just
+// matches zero rows. Deleted twice is deleted once, so there is nothing here for a claim to arbitrate.
+//
+// rmSync runs before the clear, not after: if it throws (permissions, a mid-delete race), codex_home
+// stays set and this row is picked up again - by the next agent_close call, or by the janitor's own
+// backstop sweep - rather than the failure being silently swallowed by a claim that already fired.
+// The column IS the retry token; that is the guard here, it is just not shaped like a CAS.
+// Both callers wrap this, so a failure here costs a retry, never the close or the sweep it runs inside.
+// The target comes from the row's own transcript_path, not from reapCodexHome's returned list, so
+// a retry and a racing reap converge on the same file; the rewrite runs before the codex_home clear.
+export function reapCodexHomeForClosedAgent(agentId, codexHome) {
+    const before = db.prepare("SELECT transcript_path FROM agents WHERE id = ?").get(agentId);
+    const oldTranscriptPath = before?.transcript_path ?? "";
+    const dest = oldTranscriptPath ? preservedRolloutPath(codexHome, oldTranscriptPath) : undefined;
+    reapCodexHome(codexHome);
+    if (dest && existsSync(dest)) {
+        db.prepare("UPDATE agents SET transcript_path = ? WHERE id = ? AND transcript_path = ?").run(dest, agentId, oldTranscriptPath);
+    }
+    db.prepare("UPDATE agents SET codex_home = '' WHERE id = ? AND codex_home = ?").run(agentId, codexHome);
+}
+export function closeAgentRow(agentId, expectedTmuxTarget) {
+    const info = expectedTmuxTarget === undefined
+        ? db
+            .prepare("UPDATE agents SET status = 'closed', closed_at = datetime('now') WHERE id = ? AND status = 'running'")
+            .run(agentId)
+        : db
+            .prepare("UPDATE agents SET status = 'closed', closed_at = datetime('now') WHERE id = ? AND status = 'running' AND tmux_target = ?")
+            .run(agentId, expectedTmuxTarget);
+    return info.changes > 0;
+}

package/dist/stateProvenance.js

@@ -0,0 +1,97 @@
+import { db } from "./db.js";
+import { awaitingFirstPrompt } from "./firstPrompt.js";
+import { harnessFor } from "./harnesses.js";
+import { sanitizeEventForDisplay } from "./tmux.js";
+const prepared = new Map();
+function stmt(sql) {
+    let s = prepared.get(sql);
+    if (!s) {
+        s = db.prepare(sql);
+        prepared.set(sql, s);
+    }
+    return s;
+}
+function parseStoreTimestamp(ts) {
+    return new Date(`${ts.replace(" ", "T")}Z`).getTime();
+}
+export function ageSecondsSince(storeTimestamp, now = Date.now()) {
+    return Math.max(0, Math.round((now - parseStoreTimestamp(storeTimestamp)) / 1000));
+}
+export function humanizeAge(seconds) {
+    if (seconds < 60)
+        return `${seconds}s`;
+    if (seconds < 3600)
+        return `${Math.floor(seconds / 60)}m`;
+    return `${Math.floor(seconds / 3600)}h`;
+}
+export function deriveProvenance(row, alive, now = Date.now()) {
+    const lastSeenRow = stmt("SELECT last_seen_at FROM actors WHERE id = ?").get(row.actor_id);
+    const last_seen = lastSeenRow?.last_seen_at ?? null;
+    if (alive === false) {
+        return { state: "gone", source: "tmux-probe", event: null, since: null, age_seconds: null, last_seen };
+    }
+    if (!reportsAgentStateLog(row)) {
+        return {
+            state: row.agent_state,
+            source: "not-instrumented",
+            event: null,
+            since: null,
+            age_seconds: null,
+            last_seen,
+        };
+    }
+    const since = row.state_changed_at;
+    const age_seconds = since ? ageSecondsSince(since, now) : null;
+    const logRow = since
+        ? stmt("SELECT event FROM agent_state_log WHERE actor_id = ? AND state = ? ORDER BY id DESC LIMIT 1").get(row.actor_id, row.agent_state)
+        : undefined;
+    return {
+        state: row.agent_state,
+        source: logRow ? "hook" : "no-record",
+        event: logRow ? logRow.event : null,
+        since,
+        age_seconds,
+        last_seen,
+        ...(awaitingFirstPrompt(row) ? { awaiting_first_prompt: true } : {}),
+    };
+}
+export function describeForHuman(prov, now = Date.now()) {
+    if (prov.awaiting_first_prompt && prov.state === "idle") {
+        return prov.age_seconds == null
+            ? "idle (no assignment yet)"
+            : `idle (no assignment yet, ${humanizeAge(prov.age_seconds)} ago)`;
+    }
+    switch (prov.source) {
+        case "not-instrumented":
+            return `${prov.state} (not instrumented)`;
+        case "tmux-probe":
+            return prov.last_seen
+                ? `${prov.state} (last seen ${humanizeAge(ageSecondsSince(prov.last_seen, now))} ago)`
+                : prov.state;
+        case "no-record":
+            return prov.age_seconds == null
+                ? `${prov.state} (no record)`
+                : `${prov.state} (no record, ${humanizeAge(prov.age_seconds)} ago)`;
+        case "hook":
+            return `${prov.state} (${prov.event}, ${humanizeAge(prov.age_seconds)} ago)`;
+    }
+}
+export function lastLogEvent(actorId, now = Date.now()) {
+    const row = stmt("SELECT event, state, created_at FROM agent_state_log WHERE actor_id = ? ORDER BY id DESC LIMIT 1").get(actorId);
+    if (!row)
+        return null;
+    return { event: row.event, state: row.state, age_seconds: ageSecondsSince(row.created_at, now), at: row.created_at };
+}
+export function describeLastLogEvent(log) {
+    return log ? `${sanitizeEventForDisplay(log.event)} (${humanizeAge(log.age_seconds)} ago)` : "no record";
+}
+export function reportsAgentStateLog(row) {
+    return row.kind === "agent" && harnessFor(row.command).stateSource;
+}
+const PERMISSION_MODE_RE = /"permission_mode":"([a-zA-Z]+)"/;
+// Regex over raw payload, not the last row's JSON.parse: a Notification row never carries this key.
+export function lastPermissionMode(actorId) {
+    const row = stmt("SELECT payload FROM agent_state_log WHERE actor_id = ? AND payload LIKE '%\"permission_mode\":%' ORDER BY id DESC LIMIT 1").get(actorId);
+    const match = row ? PERMISSION_MODE_RE.exec(row.payload) : null;
+    return match ? match[1] : null;
+}