@shanesaravia/hive 0.3.0 → 0.4.0

package/packages/server/dist/api/ws.js

@@ -1,11 +1,34 @@
 import { buildFleetSnapshot } from "../roster/rosterBuilder.js";
+/** Strictly parse the only client messages that may affect terminal delivery. */
+export function parseTerminalSubscription(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const message = raw;
+    if (message.type !== "terminal/subscribe" && message.type !== "terminal/unsubscribe")
+        return undefined;
+    if (typeof message.missionId !== "string" || !message.missionId.trim())
+        return undefined;
+    if (message.source !== undefined && typeof message.source !== "string")
+        return undefined;
+    const source = typeof message.source === "string" ? message.source.trim() : "orchestrator";
+    if (!source)
+        return undefined;
+    const numericAfter = typeof message.after === "number" ? message.after : 0;
+    return {
+        action: message.type === "terminal/subscribe" ? "subscribe" : "unsubscribe",
+        missionId: message.missionId.trim(),
+        source,
+        after: Number.isFinite(numericAfter) ? Math.max(0, Math.floor(numericAfter)) : 0,
+    };
+}
 /**
  * Single WS endpoint pushing roster + event deltas. The frontend never polls
  * REST for live state — this is the only steady-state channel.
  */
 export function registerWs(app, deps) {
-    const { sessionsWatcher, jobsWatcher, events, missions, messages, plans, workerIdentity, webBuild } = deps;
+    const { sessionsWatcher, jobsWatcher, events, missions, messages, plans, workerIdentity, terminalStream, terminalObservability, webBuild } = deps;
     const clients = new Set();
+    const terminalSubscriptions = new Map();
     // Every roster the client ever sees is built the same way. The first one
     // used to be built without the identity store, so a reload resolved workers
     // from the bare event window and the next broadcast disagreed with it.
@@ -44,11 +67,52 @@ export function registerWs(app, deps) {
         broadcastEvent(event);
         broadcastRoster();
     });
+    const stopTerminalEvents = terminalStream.onEvent((event) => {
+        const key = `${event.missionId}:${event.source}`;
+        const message = JSON.stringify({ type: "terminal/event", event });
+        for (const client of clients) {
+            if (!terminalSubscriptions.get(client)?.has(key))
+                continue;
+            // A slow browser catches up through sequence replay; never let terminal
+            // output grow the ws library's pending buffer without bound.
+            if (client.readyState === 1 && client.bufferedAmount < 1_000_000)
+                client.send(message);
+            else
+                terminalObservability.metric("stream.slow_client_recovery");
+        }
+    });
+    app.addHook("onClose", async () => stopTerminalEvents());
     app.get("/ws", { websocket: true }, (socket) => {
         clients.add(socket);
+        terminalSubscriptions.set(socket, new Set());
         if (webBuild)
             socket.send(JSON.stringify({ type: "hello", build: webBuild }));
         socket.send(JSON.stringify({ type: "roster", snapshot: currentRoster() }));
-        socket.on("close", () => clients.delete(socket));
+        socket.on("message", (raw) => {
+            let parsed;
+            try {
+                parsed = JSON.parse(String(raw));
+            }
+            catch {
+                return;
+            }
+            const message = parseTerminalSubscription(parsed);
+            if (!message)
+                return;
+            const { missionId, source } = message;
+            const key = `${missionId}:${source}`;
+            if (message.action === "unsubscribe") {
+                terminalSubscriptions.get(socket)?.delete(key);
+                return;
+            }
+            terminalSubscriptions.get(socket)?.add(key);
+            const replay = terminalStream.replay(missionId, source, message.after);
+            terminalObservability.metric(message.after > 0 ? "stream.reconnect" : "stream.subscription");
+            if (replay.truncated)
+                terminalObservability.metric("stream.truncated_recovery");
+            if (socket.readyState === 1)
+                socket.send(JSON.stringify({ type: "terminal/replay", missionId, source, ...replay }));
+        });
+        socket.on("close", () => { clients.delete(socket); terminalSubscriptions.delete(socket); });
     });
 }

package/packages/server/dist/control/missionQuiesce.js

@@ -0,0 +1,66 @@
+/**
+ * Job states in which the provider is holding a turn open — running one, or
+ * parked partway through one waiting for an answer. A resume cannot join a
+ * turn that is already in progress; it starts a second one beside it.
+ */
+const MID_TURN_JOB_STATES = ["working", "busy", "queued", "blocked"];
+/**
+ * Whether the provider can still act through this job.
+ *
+ * Live is not the same as mid-turn, and reading it that way is what let this
+ * go unnoticed for a day. A background orchestrator that has finished its turn
+ * keeps whatever it armed while running — background monitors, scheduled
+ * wake-ups, polling shells — and the daemon brings it back to act on them
+ * minutes or hours later. Mission f7ae71c7's first manager sat at "blocked"
+ * for 24 hours and spawned workers, pushed commits and re-closed gates the
+ * whole time.
+ *
+ * The session record is the honest signal: the daemon writes one while the
+ * session exists and removes it when the session is gone. While it is there,
+ * something can still wake the job.
+ */
+export function jobIsLive(jobId, job, sessions) {
+    if (MID_TURN_JOB_STATES.includes(job.state))
+        return true;
+    for (const session of sessions) {
+        if (session.jobId === jobId)
+            return true;
+        if (job.sessionId && session.sessionId === job.sessionId)
+            return true;
+        if (job.resumeSessionId && session.sessionId === job.resumeSessionId)
+            return true;
+    }
+    return false;
+}
+/**
+ * The jobs that must be stopped before a mission is resumed, so that the
+ * resume leaves exactly one manager able to act.
+ *
+ * `claude --resume` forks. The session it resumes goes on running — with its
+ * armed monitors, its scheduled wake-ups and its background shells intact —
+ * while the fork carries the conversation on under a fresh session id, and
+ * Hive repoints the mission at the fork. Nothing ever addresses the old branch
+ * again, but nothing stops it either. On mission f7ae71c7 thirteen sends left
+ * five managers alive at once against one worktree and one merge request: each
+ * re-closed the same gate, each spawned its own worker for the same plan task,
+ * and each read the others' commits as changes it had never asked for and
+ * blamed them on its own worker.
+ *
+ * The resume target is spared while it is between turns — that is the ordinary
+ * case, where the resume continues the conversation rather than branching it.
+ * A target that is mid-turn or parked is stopped first, which is what the
+ * handoff and parked-permission paths already do before resuming.
+ */
+export function jobsToQuiesce(input) {
+    const stop = [];
+    for (const { jobId, job, missionId } of input.jobs) {
+        if (missionId !== input.missionId)
+            continue;
+        if (!jobIsLive(jobId, job, input.sessions))
+            continue;
+        if (jobId === input.targetJobId && !MID_TURN_JOB_STATES.includes(job.state))
+            continue;
+        stop.push(jobId);
+    }
+    return stop;
+}

package/packages/server/dist/health/deriveAlerts.js

@@ -8,6 +8,14 @@ export function deriveAlerts(input) {
     const alerts = [];
     if (input.stale)
         alerts.push({ id: "stale-job", severity: "critical", title: "Stale job state", explanation: "Claude reports this job as working, but Hive cannot find its live process.", evidence: "A working/busy job record exists without a matching session record.", recovery: "Restart or resume the mission; archive the stale record if the work is no longer needed." });
+    // A mission is meant to have one manager. More than one means a resume
+    // forked instead of continuing, and the extras did not stop: they share the
+    // worktree, the branch and the plan, so each redoes the other's work and
+    // reads the other's commits as changes it never made. The board shows only
+    // the newest, which is exactly why this needs saying.
+    const live = input.liveJobIds ?? [];
+    if (live.length > 1)
+        alerts.push({ id: "concurrent-jobs", severity: "critical", title: "More than one manager is live on this mission", explanation: "Several orchestrator jobs for this mission can still act, and they share one worktree, branch and plan. Expect duplicated delegations, repeated gate transitions, and each manager reporting the others' commits as work it never asked for.", evidence: `${live.length} live jobs: ${live.map((jobId) => jobId.slice(0, 8)).join(", ")}`, recovery: "Send the mission a message: resuming now stops every superseded manager first. Any that survive that can be stopped from the sessions list." });
     for (const worker of input.workers.filter((item) => !item.doneAt && (item.jobState === "working" || item.jobState === "busy"))) {
         const workerEvents = input.events.filter((event) => matchesWorker(event.targetWorker, worker));
         const lastUpdate = Math.max(worker.startedAt, worker.jobUpdatedAt ?? 0, ...workerEvents.map((event) => event.ts));

package/packages/server/dist/index.js

@@ -18,7 +18,11 @@ import { registerWs } from "./api/ws.js";
 import { drainHookSpool } from "./hooks/hookSpool.js";
 import { PoliciesStore } from "./policies/policiesStore.js";
 import { CodexRuntime } from "./control/codexRuntime.js";
+import { LoopStore } from "./loops/loopStore.js";
+import { LoopScheduler } from "./loops/loopScheduler.js";
 import { allowedBrowserOrigins, browserOriginAllowed } from "./security/originPolicy.js";
+import { TerminalRuntime } from "./terminals/terminalRuntime.js";
+import { TerminalObservability } from "./terminals/terminalObservability.js";
 async function main() {
     const app = Fastify({ logger: true });
     const browserOrigins = allowedBrowserOrigins({
@@ -45,6 +49,9 @@ async function main() {
     const workerIdentity = new WorkerIdentityStore();
     const policies = new PoliciesStore();
     const codex = new CodexRuntime();
+    const terminalObservability = new TerminalObservability((record) => app.log.info({ terminalAudit: record }, "terminal input operation"));
+    const terminalRuntime = new TerminalRuntime(undefined, undefined, terminalObservability);
+    const loops = new LoopStore();
     events.init();
     policies.init();
     codex.init();
@@ -68,8 +75,25 @@ async function main() {
     // data — a fixed bug reported again from a stale tab. The client reloads
     // when this changes.
     const webBuild = webBuildId(webRoot);
-    registerRest(app, { sessionsWatcher, jobsWatcher, events, missions, messages, plans, policies, codex, workerIdentity });
-    registerWs(app, { sessionsWatcher, jobsWatcher, events, missions, messages, plans, workerIdentity, webBuild });
+    const { sendToMission } = registerRest(app, { sessionsWatcher, jobsWatcher, events, missions, messages, plans, policies, codex, workerIdentity, terminalRuntime, loops });
+    // Loops survive a restart because they live in the database, so the
+    // scheduler picks up whatever was already running the moment it starts.
+    const loopScheduler = new LoopScheduler({
+        loops,
+        send: (missionId, prompt) => sendToMission(missionId, prompt),
+        // Never interrupt a live turn: a loop that fires mid-conversation would
+        // quiesce whatever the agent is currently saying.
+        isBusy: (missionId) => [...jobsWatcher.getAll()].some(([jobId, job]) => missions.missionFor(jobId) === missionId && job.state !== "done" && job.state !== "failed"),
+        // A finished or archived mission has no session left to wake.
+        isRunnable: (missionId) => {
+            const lifecycle = missions.get(missionId)?.lifecycleStatus;
+            return Boolean(lifecycle) && lifecycle !== "archived" && lifecycle !== "completed";
+        },
+        onError: (loop, error) => app.log.warn({ loopId: loop.id, missionId: loop.missionId, err: error.message }, "loop turn failed"),
+    });
+    loopScheduler.start();
+    registerWs(app, { sessionsWatcher, jobsWatcher, events, missions, messages, plans, workerIdentity, terminalStream: terminalRuntime.stream, terminalObservability, webBuild });
+    app.addHook("onClose", async () => terminalRuntime.close());
     app.get("/health", async () => ({ ok: true, webBuild }));
     const isCompiledRuntime = fileURLToPath(import.meta.url).includes(`${path.sep}dist${path.sep}`);
     if (existsSync(path.join(webRoot, "index.html"))) {

package/packages/server/dist/loops/loopCommand.js

@@ -0,0 +1,56 @@
+/** The shortest useful cadence; anything faster is a runaway, not a loop. */
+export const MIN_LOOP_INTERVAL_MS = 30_000;
+export const MAX_LOOP_INTERVAL_MS = 24 * 60 * 60 * 1000;
+export const DEFAULT_LOOP_INTERVAL_MS = 5 * 60 * 1000;
+const UNITS = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 };
+/**
+ * "5m", "30s", "1h30m" — the same shorthand the CLI's own `/loop` accepts.
+ * Returns undefined for anything that is not purely an interval, so a prompt
+ * beginning with a word is never silently eaten as a duration.
+ */
+export function parseInterval(token) {
+    const trimmed = token.trim().toLowerCase();
+    if (!trimmed || !/^(\d+(?:\.\d+)?[smhd])+$/.test(trimmed))
+        return undefined;
+    let total = 0;
+    for (const [, amount, unit] of trimmed.matchAll(/(\d+(?:\.\d+)?)([smhd])/g)) {
+        total += Number(amount) * UNITS[unit];
+    }
+    return total > 0 ? total : undefined;
+}
+export function formatInterval(ms) {
+    const hours = Math.floor(ms / 3_600_000);
+    const minutes = Math.floor((ms % 3_600_000) / 60_000);
+    const seconds = Math.round((ms % 60_000) / 1000);
+    return [hours && `${hours}h`, minutes && `${minutes}m`, seconds && `${seconds}s`].filter(Boolean).join("") || "0s";
+}
+/**
+ * Reads `/loop …` typed into a mission conversation.
+ *
+ * Returns undefined when the text is not a loop command at all, so ordinary
+ * messages fall straight through to the mission.
+ */
+export function parseLoopCommand(text) {
+    const match = text.trim().match(/^\/loop\b\s*([\s\S]*)$/i);
+    if (!match)
+        return undefined;
+    const rest = match[1].trim();
+    if (!rest || rest.toLowerCase() === "list")
+        return { kind: "list" };
+    const stop = rest.match(/^stop\b\s*(\S*)$/i);
+    if (stop)
+        return { kind: "stop", loopId: stop[1] || undefined };
+    const [first, ...remainder] = rest.split(/\s+/);
+    const parsed = parseInterval(first);
+    const intervalMs = parsed ?? DEFAULT_LOOP_INTERVAL_MS;
+    const prompt = (parsed ? remainder.join(" ") : rest).trim();
+    if (!prompt)
+        return { kind: "error", message: "A loop needs something to run: /loop 10m check for new PR comments" };
+    if (intervalMs < MIN_LOOP_INTERVAL_MS) {
+        return { kind: "error", message: `The shortest loop interval is ${formatInterval(MIN_LOOP_INTERVAL_MS)}; ${formatInterval(intervalMs)} would run away.` };
+    }
+    if (intervalMs > MAX_LOOP_INTERVAL_MS) {
+        return { kind: "error", message: `The longest loop interval is ${formatInterval(MAX_LOOP_INTERVAL_MS)}.` };
+    }
+    return { kind: "start", intervalMs, prompt };
+}

package/packages/server/dist/loops/loopNoop.js

@@ -0,0 +1,38 @@
+/**
+ * The line a looping agent ends on when its pass found nothing to do.
+ *
+ * Bracketed and namespaced so it cannot be mistaken for prose the agent meant
+ * to say, and so a reply that merely discusses looping is not mistaken for a
+ * quiet run.
+ */
+export const NOOP_MARKER = "[hive:no-change]";
+const NOOP_PATTERN = new RegExp(`\\n*\\s*${NOOP_MARKER.replace(/[[\]]/g, "\\$&")}\\s*$`, "i");
+/**
+ * What Hive appends when it re-sends a loop's prompt.
+ *
+ * Kept off the stored prompt so the Tasks panel shows what the reader actually
+ * asked for, not Hive's bookkeeping.
+ */
+export function withLoopInstructions(prompt) {
+    return `${prompt}\n\n(Hive loop: this prompt runs on a schedule. If this pass found nothing new to act on, end your reply with the single line ${NOOP_MARKER} — Hive folds those away so the quiet runs do not bury the ones that mattered.)`;
+}
+const INSTRUCTION_PATTERN = /\n*\(Hive loop: this prompt runs on a schedule\.[\s\S]*?\)\s*$/;
+/**
+ * Removes Hive's own appended instruction from a recorded prompt.
+ *
+ * The job records the full text that was sent, but the bookkeeping half was
+ * never the reader's words and has no business in their chat bubble.
+ */
+export function stripLoopInstructions(text) {
+    return text.replace(INSTRUCTION_PATTERN, "").trimEnd();
+}
+/**
+ * Splits the marker off a reply.
+ *
+ * The marker is bookkeeping, not something the reader should have to look at,
+ * so it never reaches the transcript — only the flag it sets does.
+ */
+export function stripNoopMarker(text) {
+    const stripped = text.replace(NOOP_PATTERN, "");
+    return stripped === text ? { text, noop: false } : { text: stripped.trimEnd(), noop: true };
+}

package/packages/server/dist/loops/loopScheduler.js

@@ -0,0 +1,58 @@
+import { withLoopInstructions } from "./loopNoop.js";
+export const LOOP_TICK_MS = 15_000;
+/**
+ * Fires due loops.
+ *
+ * A loop never overlaps itself: the run is marked before the send, so a slow
+ * turn delays the next firing rather than stacking a second one behind it.
+ * A mission that has gone away stops its loops instead of failing forever.
+ */
+export class LoopScheduler {
+    deps;
+    timer;
+    running = new Set();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    start(intervalMs = LOOP_TICK_MS) {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => { void this.tick(); }, intervalMs);
+        this.timer.unref?.();
+    }
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = undefined;
+    }
+    async tick(now = Date.now()) {
+        for (const loop of this.deps.loops.due(now)) {
+            if (this.running.has(loop.id))
+                continue;
+            if (!this.deps.isRunnable(loop.missionId)) {
+                this.deps.loops.stop(loop.id, "the mission is no longer running");
+                continue;
+            }
+            // Deferred, not skipped: nextRunAt stays in the past, so the loop fires
+            // on the first tick after the mission goes quiet rather than losing its
+            // turn or interrupting one.
+            if (this.deps.isBusy(loop.missionId))
+                continue;
+            this.running.add(loop.id);
+            // Marked before the send: a turn that outlasts the interval must push the
+            // next firing out, never queue another on top of it.
+            this.deps.loops.markRun(loop.id, now);
+            try {
+                // The stored prompt stays exactly what was asked for; the folding
+                // instruction is added only on the way out.
+                await this.deps.send(loop.missionId, withLoopInstructions(loop.prompt));
+            }
+            catch (error) {
+                this.deps.onError?.(loop, error);
+            }
+            finally {
+                this.running.delete(loop.id);
+            }
+        }
+    }
+}

package/packages/server/dist/loops/loopStore.js

@@ -0,0 +1,118 @@
+import { randomUUID } from "node:crypto";
+import Database from "better-sqlite3";
+import { config } from "../config.js";
+function toLoop(row) {
+    return {
+        id: row.id,
+        missionId: row.mission_id,
+        prompt: row.prompt,
+        intervalMs: row.interval_ms,
+        status: row.status,
+        createdAt: row.created_at,
+        ...(row.last_run_at ? { lastRunAt: row.last_run_at } : {}),
+        nextRunAt: row.next_run_at,
+        runCount: row.run_count,
+        ...(row.stopped_reason ? { stoppedReason: row.stopped_reason } : {}),
+    };
+}
+/**
+ * Recurring prompts Hive re-sends to a mission.
+ *
+ * Persisted rather than held in memory: a loop that quietly dies when the
+ * server restarts is a loop the reader still believes is running, which is the
+ * failure this whole feature exists to prevent.
+ */
+export class LoopStore {
+    db;
+    listeners = new Set();
+    constructor(filePath = config.databasePath) {
+        this.db = new Database(filePath);
+        this.db.pragma("journal_mode = WAL");
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS mission_loops (
+        id TEXT PRIMARY KEY,
+        mission_id TEXT NOT NULL,
+        prompt TEXT NOT NULL,
+        interval_ms INTEGER NOT NULL,
+        status TEXT NOT NULL,
+        created_at INTEGER NOT NULL,
+        last_run_at INTEGER,
+        next_run_at INTEGER NOT NULL,
+        run_count INTEGER NOT NULL DEFAULT 0,
+        stopped_reason TEXT
+      );
+      CREATE INDEX IF NOT EXISTS idx_mission_loops_mission ON mission_loops (mission_id, status);
+      CREATE INDEX IF NOT EXISTS idx_mission_loops_due ON mission_loops (status, next_run_at);
+    `);
+    }
+    close() { this.db.close(); }
+    onChange(listener) { this.listeners.add(listener); }
+    notify() { for (const listener of this.listeners)
+        listener(); }
+    create(input) {
+        const now = input.now ?? Date.now();
+        const loop = {
+            id: randomUUID().slice(0, 8),
+            mission_id: input.missionId,
+            prompt: input.prompt,
+            interval_ms: input.intervalMs,
+            status: "active",
+            created_at: now,
+            last_run_at: null,
+            // The first run is one interval away, not immediate: the message that
+            // created the loop is itself the first pass.
+            next_run_at: now + input.intervalMs,
+            run_count: 0,
+            stopped_reason: null,
+        };
+        this.db.prepare(`
+      INSERT INTO mission_loops (id, mission_id, prompt, interval_ms, status, created_at, last_run_at, next_run_at, run_count, stopped_reason)
+      VALUES (@id, @mission_id, @prompt, @interval_ms, @status, @created_at, @last_run_at, @next_run_at, @run_count, @stopped_reason)
+    `).run(loop);
+        this.notify();
+        return toLoop(loop);
+    }
+    get(id) {
+        const row = this.db.prepare("SELECT * FROM mission_loops WHERE id = ?").get(id);
+        return row ? toLoop(row) : undefined;
+    }
+    /** Active loops, soonest first. Stopped ones are history, not state. */
+    active(missionId) {
+        const rows = missionId
+            ? this.db.prepare("SELECT * FROM mission_loops WHERE status = 'active' AND mission_id = ? ORDER BY next_run_at").all(missionId)
+            : this.db.prepare("SELECT * FROM mission_loops WHERE status = 'active' ORDER BY next_run_at").all();
+        return rows.map(toLoop);
+    }
+    due(now = Date.now()) {
+        return this.db.prepare("SELECT * FROM mission_loops WHERE status = 'active' AND next_run_at <= ? ORDER BY next_run_at").all(now).map(toLoop);
+    }
+    /** Records a firing and schedules the next one from now, not from the due time. */
+    markRun(id, now = Date.now()) {
+        this.db.prepare(`
+      UPDATE mission_loops
+      SET last_run_at = @now, next_run_at = @now + interval_ms, run_count = run_count + 1
+      WHERE id = @id AND status = 'active'
+    `).run({ id, now });
+        this.notify();
+    }
+    stop(id, reason) {
+        const result = this.db
+            .prepare("UPDATE mission_loops SET status = 'stopped', stopped_reason = ? WHERE id = ? AND status = 'active'")
+            .run(reason ?? null, id);
+        if (result.changes)
+            this.notify();
+        return result.changes > 0;
+    }
+    stopMission(missionId, reason) {
+        const result = this.db
+            .prepare("UPDATE mission_loops SET status = 'stopped', stopped_reason = ? WHERE mission_id = ? AND status = 'active'")
+            .run(reason ?? null, missionId);
+        if (result.changes)
+            this.notify();
+        return result.changes;
+    }
+    removeMission(missionId) {
+        this.db.prepare("DELETE FROM mission_loops WHERE mission_id = ?").run(missionId);
+        this.notify();
+    }
+}

package/packages/server/dist/loops/monitors.js

@@ -0,0 +1,38 @@
+/**
+ * Background watchers a mission's agent has open, each by name.
+ *
+ * They come from the job's fan rather than the `inFlight.kinds` tally, which
+ * only ever yields a count — and a count cannot tell you whether the watcher
+ * you are looking for is the one still running.
+ *
+ * Hive does not start these and the CLI has no per-watcher stop (`claude stop`
+ * takes a session), so the turn that owns them is what can actually be ended.
+ * Naming them is what makes that choice an informed one.
+ */
+export function activeMonitors(jobs, missionFor, missionName) {
+    const monitors = [];
+    for (const [jobId, job] of jobs) {
+        // A finished turn's watchers are finished with it. Real job records keep
+        // fan entries with no doneAt long after the turn ended, so trusting the
+        // entry alone would report watchers that stopped days ago.
+        if (job.state === "done" || job.state === "failed")
+            continue;
+        const missionId = missionFor(jobId);
+        if (!missionId)
+            continue;
+        for (const entry of job.fan ?? []) {
+            if (entry.kind !== "monitor" || entry.doneAt)
+                continue;
+            monitors.push({
+                missionId,
+                missionName: missionName(missionId),
+                jobId,
+                id: entry.id,
+                label: entry.label?.trim() || "unnamed watcher",
+                startedAt: entry.startedAt || Date.parse(job.createdAt ?? "") || 0,
+                ...(job.detail ? { detail: job.detail } : {}),
+            });
+        }
+    }
+    return monitors.sort((a, b) => a.startedAt - b.startedAt);
+}

package/packages/server/dist/messages/attachmentStore.js

@@ -0,0 +1,92 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { config } from "../config.js";
+/** What a pasted screenshot can actually be, and the extension it lands under. */
+const EXTENSIONS = {
+    "image/png": "png",
+    "image/jpeg": "jpg",
+    "image/gif": "gif",
+    "image/webp": "webp",
+};
+export const MAX_ATTACHMENT_BYTES = 10 * 1024 * 1024;
+export function isSupportedMediaType(mediaType) {
+    return mediaType in EXTENSIONS;
+}
+/**
+ * Images pasted into a mission conversation, written to disk so the agent can
+ * open them.
+ *
+ * The model does not receive bytes — Hive hands the session an absolute path
+ * and the agent reads it with its own Read tool, which is the one route that
+ * works identically for every provider and needs no protocol of its own.
+ */
+export class AttachmentStore {
+    root;
+    constructor(root = path.join(config.hiveDataDir, "attachments")) {
+        this.root = root;
+    }
+    /** Ids are opaque and generated here, so a caller can never address a path. */
+    fileFor(missionId, id) {
+        const dir = path.join(this.root, encodeURIComponent(missionId));
+        let entries;
+        try {
+            entries = fs.readdirSync(dir);
+        }
+        catch {
+            return undefined;
+        }
+        const match = entries.find((entry) => path.basename(entry, path.extname(entry)) === id);
+        return match ? path.join(dir, match) : undefined;
+    }
+    save(missionId, input) {
+        const extension = EXTENSIONS[input.mediaType];
+        if (!extension)
+            throw new Error(`unsupported attachment type: ${input.mediaType}`);
+        if (input.data.byteLength > MAX_ATTACHMENT_BYTES)
+            throw new Error("attachment is larger than 10MB");
+        const id = randomUUID();
+        const dir = path.join(this.root, encodeURIComponent(missionId));
+        fs.mkdirSync(dir, { recursive: true });
+        const file = path.join(dir, `${id}.${extension}`);
+        fs.writeFileSync(file, input.data);
+        return {
+            id,
+            name: input.name?.trim() || `pasted-image.${extension}`,
+            mediaType: input.mediaType,
+            bytes: input.data.byteLength,
+            path: file,
+            url: `/api/mission/${encodeURIComponent(missionId)}/attachment/${id}`,
+        };
+    }
+    read(missionId, id) {
+        const file = this.fileFor(missionId, id);
+        if (!file)
+            return undefined;
+        const extension = path.extname(file).slice(1);
+        const mediaType = Object.entries(EXTENSIONS).find(([, value]) => value === extension)?.[0];
+        return mediaType ? { file, mediaType } : undefined;
+    }
+    /** The stored descriptor, rebuilt from disk so a caller cannot assert one. */
+    describe(missionId, id, name) {
+        const found = this.read(missionId, id);
+        if (!found)
+            return undefined;
+        let bytes = 0;
+        try {
+            bytes = fs.statSync(found.file).size;
+        }
+        catch { /* reported as zero */ }
+        return {
+            id,
+            name: name?.trim() || path.basename(found.file),
+            mediaType: found.mediaType,
+            bytes,
+            path: found.file,
+            url: `/api/mission/${encodeURIComponent(missionId)}/attachment/${id}`,
+        };
+    }
+    removeMission(missionId) {
+        fs.rmSync(path.join(this.root, encodeURIComponent(missionId)), { recursive: true, force: true });
+    }
+}