@shanesaravia/hive 0.1.0

package/dist/bin/hive.js

@@ -0,0 +1,506 @@
+#!/usr/bin/env node
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+const currentFile = fileURLToPath(import.meta.url);
+const sourceMode = currentFile.endsWith(".ts");
+const packageRoot = path.resolve(path.dirname(currentFile), sourceMode ? ".." : "../..");
+const defaultPort = 4317;
+export function resolveUserPaths(input = {}) {
+    const home = input.home ?? os.homedir();
+    const platform = input.platform ?? process.platform;
+    const env = input.env ?? process.env;
+    const legacyRoot = path.join(home, ".claude-hive");
+    const legacyExists = input.legacyExists ?? fs.existsSync(legacyRoot);
+    const overrides = (defaults) => ({
+        ...defaults,
+        config: path.resolve(env.HIVE_CONFIG_DIR ?? defaults.config),
+        state: path.resolve(env.HIVE_STATE_DIR ?? defaults.state),
+        logs: path.resolve(env.HIVE_LOG_DIR ?? defaults.logs),
+    });
+    if (env.HIVE_DATA_DIR) {
+        const data = path.resolve(env.HIVE_DATA_DIR);
+        return overrides({
+            data,
+            config: data,
+            state: data,
+            logs: path.join(data, "logs"),
+            legacy: false,
+        });
+    }
+    if (legacyExists) {
+        return overrides({ data: legacyRoot, config: legacyRoot, state: legacyRoot, logs: path.join(legacyRoot, "logs"), legacy: true });
+    }
+    if (platform === "darwin") {
+        const data = path.join(home, "Library", "Application Support", "Hive");
+        return overrides({ data, config: data, state: data, logs: path.join(home, "Library", "Logs", "Hive"), legacy: false });
+    }
+    if (platform === "win32") {
+        const data = path.join(env.LOCALAPPDATA ?? path.join(home, "AppData", "Local"), "Hive");
+        const config = path.join(env.APPDATA ?? path.join(home, "AppData", "Roaming"), "Hive");
+        return overrides({ data, config, state: data, logs: path.join(data, "logs"), legacy: false });
+    }
+    const data = path.join(env.XDG_DATA_HOME ?? path.join(home, ".local", "share"), "hive");
+    const config = path.join(env.XDG_CONFIG_HOME ?? path.join(home, ".config"), "hive");
+    const state = path.join(env.XDG_STATE_HOME ?? path.join(home, ".local", "state"), "hive");
+    return overrides({ data, config, state, logs: path.join(state, "logs"), legacy: false });
+}
+function userPaths() {
+    return resolveUserPaths();
+}
+function dataDir() {
+    return userPaths().data;
+}
+function runtimePath() {
+    return path.join(userPaths().state, "runtime.json");
+}
+function configPath() {
+    return path.join(userPaths().config, "config.json");
+}
+function logPath() {
+    return path.join(userPaths().logs, "hive.log");
+}
+function readCliConfig() {
+    try {
+        return JSON.parse(fs.readFileSync(configPath(), "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+function writeCliConfig(config) {
+    fs.mkdirSync(path.dirname(configPath()), { recursive: true });
+    const temporary = `${configPath()}.tmp-${process.pid}`;
+    fs.writeFileSync(temporary, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(temporary, configPath());
+}
+function serverEntry() {
+    return path.join(packageRoot, "packages", "server", sourceMode ? path.join("src", "index.ts") : path.join("dist", "index.js"));
+}
+function webEntry() {
+    return path.join(packageRoot, "packages", "web", "dist", "index.html");
+}
+function templatePath() {
+    return path.join(packageRoot, "templates", "agents", "hive-orchestrator.md");
+}
+function emitEntry() {
+    return path.join(packageRoot, sourceMode ? "bin" : path.join("dist", "bin"), sourceMode ? "hive-emit.ts" : "hive-emit.js");
+}
+function packageVersion() {
+    try {
+        const value = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+        return value.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function modulePath(compiled, source) {
+    return path.join(packageRoot, "packages", "server", sourceMode ? source : compiled);
+}
+async function importRuntimeModule(compiled, source) {
+    const target = modulePath(compiled, source);
+    if (!fs.existsSync(target)) {
+        throw new Error(`Required Hive runtime module is missing at ${target}. Run \`npm run build\` first.`);
+    }
+    return import(pathToFileURL(target).href);
+}
+export function isSupportedNodeVersion(version = process.versions.node) {
+    return Number(version.split(".")[0]) >= 20;
+}
+export function parseStartOptions(args) {
+    let port = Number(process.env.HIVE_PORT ?? readCliConfig().port ?? defaultPort);
+    let open = true;
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (arg === "--no-open")
+            open = false;
+        else if (arg === "--port") {
+            port = Number(args[++index]);
+        }
+        else {
+            throw new Error(`Unknown start option: ${arg}`);
+        }
+    }
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error("Port must be an integer between 1 and 65535.");
+    }
+    return { port, open };
+}
+function readRuntimeState() {
+    try {
+        const state = JSON.parse(fs.readFileSync(runtimePath(), "utf8"));
+        return Number.isInteger(state.pid) && Number.isInteger(state.port) ? state : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function writeRuntimeState(state) {
+    fs.mkdirSync(path.dirname(runtimePath()), { recursive: true });
+    fs.writeFileSync(runtimePath(), `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+}
+function clearRuntimeState(pid) {
+    const state = readRuntimeState();
+    if (pid !== undefined && state?.pid !== pid)
+        return;
+    try {
+        fs.unlinkSync(runtimePath());
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+function processExists(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+async function health(port, timeoutMs = 800) {
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), timeoutMs);
+        const response = await fetch(`http://127.0.0.1:${port}/health`, { signal: controller.signal });
+        clearTimeout(timeout);
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+}
+async function waitForHealth(port, child, timeoutMs = 12_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (child.exitCode !== null)
+            throw new Error(`Hive server exited during startup with code ${child.exitCode}.`);
+        if (await health(port))
+            return;
+        await new Promise((resolve) => setTimeout(resolve, 150));
+    }
+    throw new Error(`Hive did not become healthy on port ${port} within ${timeoutMs / 1000} seconds.`);
+}
+function launchBrowser(url) {
+    const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+    const child = spawn(command, args, { detached: true, stdio: "ignore" });
+    child.on("error", () => console.warn(`Could not open a browser automatically. Open ${url}`));
+    child.unref();
+}
+async function runStart(args, openByDefault = true) {
+    const options = parseStartOptions(openByDefault ? args : ["--no-open", ...args]);
+    const url = `http://127.0.0.1:${options.port}`;
+    const state = readRuntimeState();
+    if (await health(options.port)) {
+        console.log(`Hive is already running at ${url}`);
+        if (options.open)
+            launchBrowser(url);
+        return;
+    }
+    if (state && !processExists(state.pid))
+        clearRuntimeState(state.pid);
+    if (!isSupportedNodeVersion()) {
+        throw new Error(`Hive requires Node.js 20 or newer; found ${process.versions.node}.`);
+    }
+    if (!fs.existsSync(serverEntry()) || (!sourceMode && !fs.existsSync(webEntry()))) {
+        throw new Error("Hive production assets are missing. Run `npm run build` before starting Hive.");
+    }
+    if (!readCliConfig().setupCompletedAt) {
+        console.log("First-run provider setup is optional. Run `hive setup` to preview it; Hive will start without changing provider configuration.");
+    }
+    fs.mkdirSync(dataDir(), { recursive: true });
+    fs.mkdirSync(path.dirname(logPath()), { recursive: true });
+    const log = fs.createWriteStream(logPath(), { flags: "a", mode: 0o600 });
+    log.write(`\n--- Hive ${packageVersion()} started ${new Date().toISOString()} on ${url} ---\n`);
+    const executable = sourceMode ? path.join(packageRoot, "node_modules", ".bin", "tsx") : process.execPath;
+    const child = spawn(executable, [serverEntry()], {
+        env: {
+            ...process.env,
+            HIVE_DATA_DIR: dataDir(),
+            HIVE_PORT: String(options.port),
+            HIVE_DASHBOARD_URL: url,
+            NODE_ENV: sourceMode ? process.env.NODE_ENV : "production",
+        },
+        stdio: ["inherit", "pipe", "pipe"],
+    });
+    child.stdout.pipe(process.stdout);
+    child.stderr.pipe(process.stderr);
+    child.stdout.pipe(log, { end: false });
+    child.stderr.pipe(log, { end: false });
+    const forward = (signal) => {
+        if (child.exitCode === null)
+            child.kill(signal);
+    };
+    process.once("SIGINT", forward);
+    process.once("SIGTERM", forward);
+    try {
+        await waitForHealth(options.port, child);
+        writeRuntimeState({ pid: child.pid, port: options.port, startedAt: new Date().toISOString(), version: packageVersion() });
+        console.log(`Hive is running at ${url}`);
+        if (options.open)
+            launchBrowser(url);
+        const exitCode = await new Promise((resolve, reject) => {
+            child.once("error", reject);
+            child.once("exit", (code) => resolve(code ?? 0));
+        });
+        if (exitCode)
+            process.exitCode = exitCode;
+    }
+    catch (error) {
+        if (child.exitCode === null)
+            child.kill("SIGTERM");
+        throw error;
+    }
+    finally {
+        process.removeListener("SIGINT", forward);
+        process.removeListener("SIGTERM", forward);
+        clearRuntimeState(child.pid);
+        log.end();
+    }
+}
+function renderedPersona() {
+    const source = templatePath();
+    if (!fs.existsSync(source) || !fs.existsSync(emitEntry())) {
+        throw new Error("Hive setup assets are missing. Run `npm run build` first.");
+    }
+    const destination = path.join(os.homedir(), ".claude", "agents", "hive-orchestrator.md");
+    const emitCommand = sourceMode
+        ? `${shellQuote(path.join(packageRoot, "node_modules", ".bin", "tsx"))} ${shellQuote(emitEntry())}`
+        : `${shellQuote(process.execPath)} ${shellQuote(emitEntry())}`;
+    const rendered = fs.readFileSync(source, "utf8").replaceAll("{{HIVE_EMIT_CMD}}", emitCommand);
+    const existing = fs.existsSync(destination) ? fs.readFileSync(destination, "utf8") : undefined;
+    return { destination, content: rendered, changed: existing !== rendered };
+}
+function installPersona(persona) {
+    fs.mkdirSync(path.dirname(persona.destination), { recursive: true });
+    fs.writeFileSync(persona.destination, persona.content);
+}
+async function runSetup(assumeYes) {
+    process.env.HIVE_DATA_DIR ??= dataDir();
+    const persona = renderedPersona();
+    const hooks = await importRuntimeModule("dist/hooks/setupHooks.js", "src/hooks/setupHooks.ts");
+    const hookPlan = hooks.planHookSetup();
+    console.log("Hive setup plan:");
+    console.log(`  ${persona.changed ? "+" : "✓"} Claude orchestrator persona: ${persona.destination}`);
+    console.log(`  ${hookPlan.changed ? "+" : "✓"} Additive Claude event hooks: ${path.join(os.homedir(), ".claude", "settings.json")}`);
+    console.log(`  • Hive data: ${dataDir()}${userPaths().legacy ? " (existing legacy location preserved)" : ""}`);
+    if (!persona.changed && !hookPlan.changed && readCliConfig().setupCompletedAt) {
+        console.log("Setup is already complete — nothing to change.");
+        return;
+    }
+    if (!assumeYes) {
+        console.log("No files were changed. Existing hooks are preserved and settings are backed up before any hook changes.");
+        console.log("Re-run with --yes to apply.");
+        return;
+    }
+    if (persona.changed)
+        installPersona(persona);
+    if (hookPlan.changed)
+        hooks.applyHookSetup();
+    writeCliConfig({ ...readCliConfig(), setupCompletedAt: new Date().toISOString() });
+    console.log("Hive provider setup is complete.");
+}
+async function runStatus() {
+    const state = readRuntimeState();
+    const port = state?.port ?? Number(process.env.HIVE_PORT ?? defaultPort);
+    // Initial repository/session discovery can briefly occupy the server after it
+    // starts. Give an interactive status check enough time to get a response
+    // instead of reporting a healthy process as offline under CI or on large homes.
+    const healthy = await health(port, 3_000);
+    if (healthy) {
+        console.log(`Hive is running at http://127.0.0.1:${port}${state ? ` (pid ${state.pid})` : ""}.`);
+        return;
+    }
+    if (state && !processExists(state.pid))
+        clearRuntimeState(state.pid);
+    console.log("Hive is not running.");
+    process.exitCode = 1;
+}
+async function runOpen() {
+    const state = readRuntimeState();
+    const port = state?.port ?? Number(process.env.HIVE_PORT ?? defaultPort);
+    if (!(await health(port, 3_000)))
+        throw new Error("Hive is not running. Start it with `hive`.");
+    const url = `http://127.0.0.1:${port}`;
+    launchBrowser(url);
+    console.log(`Opened ${url}`);
+}
+async function runStop() {
+    const state = readRuntimeState();
+    if (!state || !processExists(state.pid)) {
+        if (state)
+            clearRuntimeState(state.pid);
+        console.log("Hive is not running.");
+        return;
+    }
+    process.kill(state.pid, "SIGTERM");
+    const deadline = Date.now() + 5_000;
+    while (Date.now() < deadline && processExists(state.pid)) {
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    if (processExists(state.pid))
+        throw new Error(`Hive process ${state.pid} did not stop gracefully.`);
+    clearRuntimeState(state.pid);
+    console.log("Hive stopped.");
+}
+function commandVersion(command) {
+    const result = spawnSync(command, ["--version"], { encoding: "utf8", timeout: 3_000 });
+    if (result.error || result.status !== 0)
+        return undefined;
+    return (result.stdout || result.stderr).trim().split("\n")[0];
+}
+function providerAuthentication(command) {
+    if (command === "claude") {
+        const result = spawnSync(command, ["auth", "status", "--json"], { encoding: "utf8", timeout: 3_000 });
+        if (result.error)
+            return { ok: false, detail: "authentication status unavailable" };
+        try {
+            const status = JSON.parse(result.stdout);
+            return status.loggedIn
+                ? { ok: true, detail: `authenticated${status.authMethod ? ` (${status.authMethod})` : ""}` }
+                : { ok: false, detail: "not authenticated" };
+        }
+        catch {
+            return { ok: false, detail: "authentication status unavailable" };
+        }
+    }
+    const result = spawnSync(command, ["login", "status"], { encoding: "utf8", timeout: 3_000 });
+    return result.status === 0
+        ? { ok: true, detail: result.stdout.trim().split("\n")[0] || "authenticated" }
+        : { ok: false, detail: "not authenticated" };
+}
+async function runDoctor() {
+    const checks = [];
+    checks.push({ ok: isSupportedNodeVersion(), required: true, label: "Node.js", detail: process.versions.node });
+    checks.push({ ok: fs.existsSync(serverEntry()), required: true, label: "Server build", detail: serverEntry() });
+    checks.push({ ok: sourceMode || fs.existsSync(webEntry()), required: true, label: "Web build", detail: webEntry() });
+    try {
+        fs.mkdirSync(dataDir(), { recursive: true });
+        fs.accessSync(dataDir(), fs.constants.R_OK | fs.constants.W_OK);
+        checks.push({ ok: true, required: true, label: "Data directory", detail: dataDir() });
+    }
+    catch (error) {
+        checks.push({ ok: false, required: true, label: "Data directory", detail: error.message });
+    }
+    for (const provider of ["claude", "codex"]) {
+        const version = commandVersion(provider);
+        checks.push({ ok: Boolean(version), required: false, label: `${provider[0].toUpperCase()}${provider.slice(1)} CLI`, detail: version ?? "not found (optional)" });
+        if (version) {
+            const authentication = providerAuthentication(provider);
+            checks.push({ ok: authentication.ok, required: false, label: `${provider[0].toUpperCase()}${provider.slice(1)} auth`, detail: authentication.detail });
+        }
+    }
+    const state = readRuntimeState();
+    const port = state?.port ?? Number(process.env.HIVE_PORT ?? defaultPort);
+    checks.push({ ok: await health(port), required: false, label: "Hive runtime", detail: `http://127.0.0.1:${port}` });
+    checks.push({ ok: true, required: false, label: "Configuration", detail: configPath() });
+    checks.push({ ok: true, required: false, label: "Runtime state", detail: runtimePath() });
+    checks.push({ ok: true, required: false, label: "Logs", detail: logPath() });
+    for (const check of checks) {
+        console.log(`${check.ok ? "✓" : check.required ? "✗" : "○"} ${check.label}: ${check.detail}`);
+    }
+    const failures = checks.filter((check) => check.required && !check.ok);
+    const providers = checks.filter((check) => check.label.endsWith(" CLI") && check.ok);
+    const authenticatedProviders = checks.filter((check) => check.label.endsWith(" auth") && check.ok);
+    if (!providers.length)
+        console.log("\nInstall and authenticate Claude Code or Codex before launching a mission.");
+    else if (!authenticatedProviders.length)
+        console.log("\nAuthenticate at least one installed provider CLI before launching a mission.");
+    if (failures.length) {
+        process.exitCode = 1;
+        console.log(`\n${failures.length} required check${failures.length === 1 ? "" : "s"} failed.`);
+    }
+    else {
+        console.log("\nHive is ready.");
+    }
+}
+async function runOrchestratorStart(args) {
+    const worktreeIndex = args.indexOf("--worktree");
+    const nameIndex = args.indexOf("--name");
+    let worktree;
+    if (worktreeIndex !== -1) {
+        worktree = true;
+        args.splice(worktreeIndex, 1);
+    }
+    let name;
+    if (nameIndex !== -1) {
+        name = args[nameIndex + 1];
+        args.splice(nameIndex, 2);
+    }
+    const task = args.join(" ").trim();
+    if (!task)
+        throw new Error('Usage: hive orchestrator start "<task>" [--worktree] [--name <name>]');
+    const launcher = await importRuntimeModule("dist/control/launcher.js", "src/control/launcher.ts");
+    const result = await launcher.startOrchestrator({ task, worktree, name });
+    console.log(`Started orchestrator pid=${result.pid}`);
+}
+function printHelp() {
+    console.log(`Hive ${packageVersion()} — provider-neutral mission control
+
+Usage:
+  hive [start] [--port <port>] [--no-open]  Start Hive and open the dashboard
+  hive doctor                              Check local requirements and providers
+  hive setup [--yes]                       Install the orchestrator persona and hooks
+  hive status                              Show whether Hive is running
+  hive open                                Open the running dashboard
+  hive stop                                Gracefully stop a recorded Hive server
+  hive --version                           Print the installed version
+  hive --help                              Show this help
+
+Compatibility:
+  hive serve [--port <port>]               Start Hive without opening a browser
+  hive orchestrator start "<task>" [--worktree] [--name <name>]`);
+}
+export async function main(argv = process.argv.slice(2)) {
+    const [command, ...args] = argv;
+    switch (command) {
+        case undefined:
+        case "start": return runStart(args);
+        case "serve": return runStart(args, false);
+        case "doctor": return runDoctor();
+        case "setup": return runSetup(args.includes("--yes"));
+        case "status": return runStatus();
+        case "open": return runOpen();
+        case "stop": return runStop();
+        case "--version":
+        case "-v":
+            console.log(packageVersion());
+            return;
+        case "--help":
+        case "-h":
+        case "help":
+            printHelp();
+            return;
+        case "orchestrator":
+            if (args[0] === "start")
+                return runOrchestratorStart(args.slice(1));
+            break;
+    }
+    printHelp();
+    throw new Error(`Unknown Hive command: ${command}`);
+}
+function isMainModule(argvEntry) {
+    if (!argvEntry)
+        return false;
+    try {
+        return fs.realpathSync(argvEntry) === fs.realpathSync(currentFile);
+    }
+    catch {
+        return path.resolve(argvEntry) === currentFile;
+    }
+}
+if (isMainModule(process.argv[1])) {
+    main().catch((error) => {
+        console.error(`Hive error: ${error.message}`);
+        process.exit(1);
+    });
+}

package/node_modules/@hive/shared/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./types.js";
+export * from "./status.js";

package/node_modules/@hive/shared/dist/index.js

@@ -0,0 +1,2 @@
+export * from "./types.js";
+export * from "./status.js";

package/node_modules/@hive/shared/dist/status.d.ts

@@ -0,0 +1,12 @@
+import type { ClaudeJob, ClaudeSession, DerivedStatus, HiveEvent } from "./types.js";
+/**
+ * Pure status derivation — no network/LLM calls. Joins the raw session/job
+ * records already on disk. A job still marked "working" with no matching
+ * live session file is flagged stale/error rather than silently dropped,
+ * since that's the one case pure file-watching can otherwise miss (the
+ * process died without a clean shutdown).
+ */
+export declare function deriveStatus(session: ClaudeSession | undefined, job: ClaudeJob | undefined, recentEvents?: HiveEvent[]): {
+    status: DerivedStatus;
+    stale: boolean;
+};

package/node_modules/@hive/shared/dist/status.js

@@ -0,0 +1,52 @@
+const STALE_JOB_STATES = new Set(["working", "busy"]);
+/**
+ * Pure status derivation — no network/LLM calls. Joins the raw session/job
+ * records already on disk. A job still marked "working" with no matching
+ * live session file is flagged stale/error rather than silently dropped,
+ * since that's the one case pure file-watching can otherwise miss (the
+ * process died without a clean shutdown).
+ */
+export function deriveStatus(session, job, recentEvents = []) {
+    // The daemon's idle notification ("Claude is waiting for your input") fires
+    // after every completed turn — it means "session idle", not "the assistant
+    // asked you something", so it must not read as waiting_on_you. Permission
+    // notifications and emitted blocked_on_user decisions still do.
+    const latestDecisionEvent = [...recentEvents].reverse().find((e) => e.phase === "blocked_on_user" || e.phase === "decision_resolved"
+        || (e.hookEventName === "Notification" && !/waiting for your input/i.test(e.detail ?? "")));
+    const blockedEvent = latestDecisionEvent?.phase !== "decision_resolved" ? latestDecisionEvent : undefined;
+    // An inferred wait (a "waiting for your input" Notification or an emitted
+    // blocked_on_user) is only current while nothing newer happened. The daemon
+    // fires idle Notifications even while subagents run, and activity resuming
+    // after one proves the session isn't parked on the user.
+    const latestEventTs = recentEvents.at(-1)?.ts ?? 0;
+    const blockedEventIsCurrent = blockedEvent !== undefined && blockedEvent.ts >= latestEventTs;
+    if (!session && job && STALE_JOB_STATES.has(job.state)) {
+        return { status: "error", stale: true };
+    }
+    if (!session) {
+        return { status: job?.state === "done" ? "done" : "idle", stale: false };
+    }
+    if (session.status === "waiting") {
+        return { status: "waiting_on_you", stale: false };
+    }
+    if (job?.state === "blocked") {
+        return { status: "waiting_on_you", stale: false };
+    }
+    // Mid-turn park: a permission prompt keeps state "working" but the daemon
+    // flips tempo to blocked and puts the ask in needs ("approve Bash: …").
+    if (job?.tempo === "blocked" && job.needs) {
+        return { status: "waiting_on_you", stale: false };
+    }
+    // A busy session outranks event-inferred waiting: the runtime is provably
+    // doing work (e.g. orchestrating subagents), not parked on the user.
+    if (session.status === "busy") {
+        return { status: "working", stale: false };
+    }
+    if (blockedEventIsCurrent) {
+        return { status: "waiting_on_you", stale: false };
+    }
+    if (job?.state === "done") {
+        return { status: "done", stale: false };
+    }
+    return { status: "idle", stale: false };
+}