@rryando/arcs 3.11.0 → 4.0.0

package/dist/web-server/run-event-log.js

@@ -0,0 +1,468 @@
+/**
+ * Per-run stdout event log — the durable spine of a headless `claude -p` run.
+ *
+ * Owns `sessions/{normalizedId}.run-{runId}.events.jsonl`: every byte the child
+ * writes to stdout lands here VERBATIM, one file line per stdout line, BEFORE
+ * anything parses it. That ordering is the whole point — the log is the source
+ * of truth and the runner's NDJSON reader is merely its first consumer, so a
+ * line the reader cannot parse (drifted wire format, truncated JSON, an event
+ * type that did not exist when this shipped) is still on disk, and a process
+ * that dies mid-run still leaves behind everything that arrived.
+ *
+ * Writes are synchronous (`writeSync` against an fd opened with "a") for
+ * exactly that reason: an async queue would only ever have *issued* the write
+ * before the parse, and a hard kill would lose whatever was still in flight.
+ * The chunks are small and few (one per stdout chunk of a single child), so the
+ * event-loop cost is a rounding error against a run measured in minutes.
+ *
+ * The `runId` in the filename is the SAME id the route persists as
+ * `currentRunId`, so the log's name and the session record can never disagree
+ * about which run produced it.
+ *
+ * Total by construction, like the reader it feeds: nothing here throws. A log
+ * that cannot be opened or written reports itself through `RunEventLogStats`
+ * and the run proceeds untouched — a logging failure must never fail a run.
+ * Reporting is the whole point: a log that hit its size cap or lost bytes to a
+ * short write says so on `truncated`, which rides all the way out to
+ * `metadata.run.eventLogTruncated`. A silent fallback here would make an empty
+ * log and a capped one look identical to every consumer downstream.
+ *
+ * At settle the log folds down into the transcript sidecar (assistant text plus
+ * one turn per `tool_use`) through `appendSessionTurn`, and older logs for the
+ * same session are pruned so the sessions dir cannot grow without limit.
+ */
+import { closeSync, mkdirSync, openSync, writeSync } from "node:fs";
+import { readdir, readFile, stat, unlink } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { appendSessionTurn, readSessionTurns } from "../utils/claude-transcript.js";
+import { normalizeIdentifier } from "../utils/slug.js";
+/**
+ * Ceiling on one run's log — a runaway child cannot fill the disk.
+ *
+ * The finished file is never LARGER than this, terminator included: the writer
+ * refuses a chunk that would take it TO the cap (`>=`, not `>`), leaving the one
+ * byte `flush()` may still need. The off-by-one that leaves matters because
+ * `foldRunEventLog` refuses to read anything past this size — a writer allowed
+ * to land on exactly the cap and then add a terminator produces a file its own
+ * fold silently discards.
+ *
+ * Reaching it does not close the log: only the crossing chunk is refused, later
+ * chunks that still fit are still written, and `RunEventLogStats.truncated`
+ * reports that bytes are missing. The file always ends on a line boundary, so an
+ * offset-based tail never reads half a record.
+ */
+export const RUN_EVENT_LOG_MAX_BYTES = 32 * 1024 * 1024;
+/**
+ * How many event logs a single session keeps. Count-based rather than
+ * age-based: a count is a hard bound (N logs per session, at most
+ * RUN_EVENT_LOG_MAX_BYTES each), while an age window still admits unbounded
+ * growth from a session that runs in a tight loop.
+ */
+export const RUN_EVENT_LOG_RETENTION = 5;
+const LOG_SUFFIX = ".events.jsonl";
+const NEWLINE = 0x0a;
+/** The only byte the log ever adds of its own: a line terminator. */
+const TERMINATOR = Buffer.from("\n", "utf-8");
+/**
+ * Filename-safe form of a run id. The id reaches a path, so it is sanitized
+ * rather than trusted: anything outside `[A-Za-z0-9_-]` (`/`, `.`, `..`) becomes
+ * `-` before it can traverse out of the sessions dir.
+ */
+export function runEventLogSegment(runId) {
+    const safe = runId.replace(/[^A-Za-z0-9_-]/g, "-").slice(0, 64);
+    return safe === "" ? "unknown" : safe;
+}
+/**
+ * Log path for one run. Keys on the session's canonical `normalizedId` exactly
+ * as the transcript sidecar does, so both files for a session sort together and
+ * neither can be derived from a raw route id.
+ */
+export function runEventLogPath(projectDir, sessionId, runId) {
+    const name = `${normalizeIdentifier(sessionId)}.run-${runEventLogSegment(runId)}${LOG_SUFFIX}`;
+    return join(projectDir, "sessions", name);
+}
+/** The handle a run with no log target gets — every method is a no-op. */
+const NOOP_HANDLE = {
+    path: "",
+    push() { },
+    flush() { },
+    close() {
+        return { lines: 0, bytes: 0, truncated: false };
+    },
+};
+/**
+ * Opens (creating) the run's log and returns a write-through handle.
+ *
+ * The file is created up front, so a run that produces no stdout at all — a
+ * child killed at its deadline before it spoke, an immediate non-zero exit —
+ * still leaves the log behind. `undefined` target yields the no-op handle, which
+ * is how the runner stays usable without a project dir (tests, and any caller
+ * that does not want a log).
+ */
+export function openRunEventLog(target) {
+    if (target === undefined)
+        return NOOP_HANDLE;
+    const path = runEventLogPath(target.projectDir, target.sessionId, target.runId);
+    let fd = null;
+    let lines = 0;
+    let bytes = 0;
+    let truncated = false;
+    let closed = false;
+    let endsWithNewline = true;
+    /**
+     * Bytes were dropped part-way through a record, so the stream now continues
+     * INSIDE a line this file does not have. Appending those bytes would splice
+     * the tail of a record the log never took onto whatever precedes it and emit
+     * a line the child never wrote, so they are dropped until the next newline.
+     */
+    let resyncing = false;
+    let error;
+    const note = (err) => {
+        if (error === undefined)
+            error = String(err);
+    };
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        // "a" — the kernel appends at every write, so nothing here has to track a
+        // file position and a concurrent reader (the tail) can never see a hole.
+        fd = openSync(path, "a");
+    }
+    catch (err) {
+        note(err);
+    }
+    const stats = () => ({
+        lines,
+        bytes,
+        truncated,
+        ...(error !== undefined && { error }),
+    });
+    /**
+     * Appends `buf` whole, returning how many of its bytes actually landed.
+     *
+     * `writeSync` may return SHORT — a signal interrupting the syscall (EINTR), a
+     * filesystem that ran out of room mid-buffer (ENOSPC) — and its return value
+     * is the only place that ever shows. Discarding it emits half a record while
+     * counting a whole one, which breaks "always ends on a line boundary" exactly
+     * when the disk is full. So the loop keeps writing while the fd makes
+     * progress, and reports precisely how far it got. `n <= 0` ends the loop
+     * rather than spinning on an fd that has stopped accepting bytes.
+     */
+    const writeAll = (handle, buf) => {
+        let written = 0;
+        while (written < buf.length) {
+            let n;
+            try {
+                n = writeSync(handle, buf, written, buf.length - written);
+            }
+            catch (err) {
+                note(err);
+                break;
+            }
+            if (n <= 0)
+                break;
+            written += n;
+        }
+        return written;
+    };
+    /** Counts what landed: bytes, whole lines, and where the file now ends. */
+    const account = (buf) => {
+        if (buf.length === 0)
+            return;
+        bytes += buf.length;
+        // Native indexOf rather than a per-byte loop: a megabyte chunk must not
+        // cost a million iterations on the event loop.
+        for (let at = buf.indexOf(NEWLINE); at !== -1; at = buf.indexOf(NEWLINE, at + 1)) {
+            lines += 1;
+        }
+        endsWithNewline = buf[buf.length - 1] === NEWLINE;
+    };
+    /**
+     * Closes a line the child left open. The only byte the log adds of its own,
+     * and only when the file would otherwise not end on a line boundary — an
+     * offset-based tail would mis-frame the last record without it.
+     *
+     * Runs at flush() AND the instant a chunk is refused or lands short, not just
+     * at close: after a gap in the stream the next accepted chunk must start its
+     * own line rather than extend the fragment before the gap.
+     *
+     * The terminator write can itself fail, and failing SILENTLY is how a
+     * fabricated line survives every other guard here: the file is left
+     * un-line-closed with `resyncing` unset, so an fd that recovers splices the
+     * next chunk onto the open fragment. A terminator that does not land therefore
+     * sets BOTH flags — `truncated` because the file is no longer line-framed, and
+     * `resyncing` because nothing may extend that fragment ever again.
+     */
+    const terminate = (handle) => {
+        if (endsWithNewline || bytes === 0)
+            return;
+        if (writeAll(handle, TERMINATOR) !== TERMINATOR.length) {
+            truncated = true;
+            resyncing = true;
+            return;
+        }
+        account(TERMINATOR);
+    };
+    return {
+        path,
+        push(chunk) {
+            if (fd === null || closed)
+                return;
+            let buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, "utf-8");
+            if (buf.length === 0)
+                return;
+            if (resyncing) {
+                const at = buf.indexOf(NEWLINE);
+                // Still inside the record whose bytes were dropped — all of it belongs
+                // to that record, none of it is a line this file may claim to hold.
+                if (at === -1)
+                    return;
+                buf = buf.subarray(at + 1);
+                resyncing = false;
+                // The stream is back at a record start, but the FILE may not be: a
+                // terminator that failed AT the gap left an open fragment behind, and
+                // knowing where the stream resumed does nothing about it. Close it here,
+                // before any of these bytes can land on it — the two questions are
+                // different and only this one keeps the next whole record off the
+                // fragment. A no-op whenever the file already ends on a boundary.
+                terminate(fd);
+                // Still open: the fd will not take even one byte, so stay resynced (a
+                // failed terminate re-arms it) and drop this record too. A fabricated
+                // line is not detectable downstream; a missing one is.
+                if (resyncing)
+                    return;
+                if (buf.length === 0)
+                    return;
+            }
+            if (bytes + buf.length >= RUN_EVENT_LOG_MAX_BYTES) {
+                // The CROSSING chunk is refused whole — never half a record — but the
+                // log stays open. Returning early here for the rest of the run turned
+                // one oversized chunk into a 0-byte file; now every later chunk that
+                // still fits is still kept, and `truncated` is what says the file is no
+                // longer the whole stream. `>=` reserves the byte terminate() may add,
+                // so the finished file never exceeds the size the fold agrees to read.
+                truncated = true;
+                // The dropped bytes end mid-record unless the chunk's own last byte was
+                // a terminator; only then does the next chunk start a fresh line.
+                resyncing = buf[buf.length - 1] !== NEWLINE;
+                terminate(fd);
+                return;
+            }
+            const written = writeAll(fd, buf);
+            account(buf.subarray(0, written));
+            if (written === buf.length)
+                return;
+            // A short write: this record is on disk in part only and the stream
+            // continues from bytes that are gone. Same treatment as the cap — say the
+            // file is incomplete, close the half-written line, and skip to the next
+            // boundary instead of splicing the next chunk onto a fragment.
+            truncated = true;
+            // The lost bytes are `buf[written..]`, so the stream stands exactly where
+            // it does after a refusal: at `buf`'s last byte. Same rule as the cap,
+            // deliberately — hardcoding a resync here is safe in direction but throws
+            // away a whole record that begins at a record boundary, for nothing.
+            resyncing = buf[buf.length - 1] !== NEWLINE;
+            terminate(fd);
+        },
+        flush() {
+            if (fd === null || closed)
+                return;
+            terminate(fd);
+        },
+        close() {
+            if (fd !== null && !closed) {
+                try {
+                    closeSync(fd);
+                }
+                catch (err) {
+                    note(err);
+                }
+            }
+            closed = true;
+            return stats();
+        },
+    };
+}
+const EMPTY_FOLD = {
+    appended: 0,
+    alreadyFolded: false,
+    assistantTextFolded: false,
+};
+function isBlock(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Turns one stream-json `assistant` event yields, in content-block order.
+ *
+ * Consecutive text blocks coalesce into one turn; every `tool_use` block gets
+ * its own turn (unlike the transcript mirror, which keeps only the first) so a
+ * message that fans out to three tools reads as three rows. Only completed
+ * `assistant` messages are folded: `stream_event` deltas repeat their text and
+ * the terminal `result` repeats the final message, so both would duplicate.
+ */
+function foldAssistantEvent(event) {
+    const message = event.message;
+    if (!isBlock(message))
+        return [];
+    const content = message.content;
+    if (typeof content === "string")
+        return content === "" ? [] : [{ text: content }];
+    if (!Array.isArray(content))
+        return [];
+    const turns = [];
+    let text = "";
+    const flushText = () => {
+        if (text === "")
+            return;
+        turns.push({ text });
+        text = "";
+    };
+    for (const block of content) {
+        if (!isBlock(block))
+            continue;
+        if (block.type === "text" && typeof block.text === "string") {
+            text += block.text;
+            continue;
+        }
+        if (block.type === "tool_use" && typeof block.name === "string") {
+            flushText();
+            turns.push({ text: "", tool: { name: block.name } });
+        }
+    }
+    flushText();
+    return turns;
+}
+/** Every turn the log implies, in the order the child emitted them. */
+function foldTurns(raw) {
+    const turns = [];
+    for (const line of raw.split("\n")) {
+        const text = (line.endsWith("\r") ? line.slice(0, -1) : line).trim();
+        if (text === "")
+            continue;
+        let value;
+        try {
+            value = JSON.parse(text);
+        }
+        catch {
+            continue; // unparsable lines stay in the log; they just fold to nothing
+        }
+        if (!isBlock(value) || value.type !== "assistant")
+            continue;
+        turns.push(...foldAssistantEvent(value));
+    }
+    return turns;
+}
+/**
+ * Folds a run's event log down into the session's transcript sidecar: assistant
+ * text plus one turn per `tool_use`, appended through `appendSessionTurn` in
+ * stream order, each tagged with the run id.
+ *
+ * Idempotence mechanism: the fold's OWN OUTPUT is the marker. Every appended
+ * turn carries `run: <runId>`, and a fold refuses as soon as the sidecar holds
+ * any turn tagged with that id. This was chosen over a separate marker (a
+ * `foldedAt` on the run record, a `.folded` sentinel file) precisely because a
+ * separate marker has a window: a crash between "turns appended" and "marker
+ * written" would re-fold and duplicate the whole run on the next settle. Here
+ * there is no window — the evidence and the mark are the same bytes. The cost
+ * is at-most-once rather than exactly-once under a crash MID-fold (the turns
+ * already appended are tagged, so the remainder is never completed), which is
+ * the safe direction: a short transcript, never a doubled one.
+ *
+ * Never throws — a fold that cannot read the log or write the sidecar reports
+ * an empty result and the settle continues.
+ */
+export async function foldRunEventLog(projectDir, sessionId, runId) {
+    try {
+        const path = runEventLogPath(projectDir, sessionId, runId);
+        const info = await stat(path);
+        if (!info.isFile() || info.size > RUN_EVENT_LOG_MAX_BYTES)
+            return EMPTY_FOLD;
+        // The mark IS the data: any turn already tagged with this run id means a
+        // previous fold got there first.
+        const existing = await readSessionTurns(projectDir, sessionId);
+        const tagged = existing.filter((turn) => turn.run === runId);
+        if (tagged.length > 0) {
+            return {
+                appended: 0,
+                alreadyFolded: true,
+                assistantTextFolded: tagged.some((turn) => turn.type === "assistant" && turn.text !== ""),
+            };
+        }
+        const turns = foldTurns(await readFile(path, "utf-8"));
+        if (turns.length === 0)
+            return EMPTY_FOLD;
+        let appended = 0;
+        let assistantTextFolded = false;
+        for (const turn of turns) {
+            // Sequential on purpose: `appendSessionTurn` mints its negative id from
+            // what is already on disk, so concurrent appends would collide.
+            await appendSessionTurn(projectDir, sessionId, {
+                type: "assistant",
+                text: turn.text,
+                run: runId,
+                ...(turn.tool !== undefined && { tool: turn.tool }),
+            });
+            appended += 1;
+            if (turn.tool === undefined && turn.text !== "")
+                assistantTextFolded = true;
+        }
+        return { appended, alreadyFolded: false, assistantTextFolded };
+    }
+    catch {
+        // Missing log, unreadable sidecar, a full disk — all fold to nothing.
+        return EMPTY_FOLD;
+    }
+}
+// ---------------------------------------------------------------------------
+// Retention
+// ---------------------------------------------------------------------------
+/**
+ * Keeps the newest `keep` event logs for one session and deletes the rest.
+ *
+ * Called at EVERY settle (after the fold), so the log that just settled is
+ * always among the survivors and the sessions dir is bounded at `keep` logs per
+ * session no matter how many runs a session accumulates. "Every settle" means
+ * the startup orphan sweep too (`settleOrphanedRuns`): a server that dies
+ * mid-run never reaches the route's write-back, so without that call site a
+ * session whose runs are always interrupted grows one capped log per run
+ * forever. `keep: 0` drops them all — what session deletion uses.
+ *
+ * Never throws; returns how many files it removed.
+ */
+export async function pruneRunEventLogs(projectDir, sessionId, keep = RUN_EVENT_LOG_RETENTION) {
+    try {
+        const sessionsDir = join(projectDir, "sessions");
+        const prefix = `${normalizeIdentifier(sessionId)}.run-`;
+        const names = (await readdir(sessionsDir)).filter((name) => name.startsWith(prefix) &&
+            name.endsWith(LOG_SUFFIX) &&
+            name.length > prefix.length + LOG_SUFFIX.length);
+        if (names.length <= keep)
+            return 0;
+        const dated = await Promise.all(names.map(async (name) => {
+            try {
+                return { name, mtimeMs: (await stat(join(sessionsDir, name))).mtimeMs };
+            }
+            catch {
+                // Vanished under us — sort it to the front so it is dropped first.
+                return { name, mtimeMs: 0 };
+            }
+        }));
+        // Newest first; the name breaks mtime ties (same-millisecond runs) so the
+        // ordering is total and the prune is deterministic.
+        dated.sort((a, b) => b.mtimeMs - a.mtimeMs || (a.name < b.name ? 1 : -1));
+        let pruned = 0;
+        for (const entry of dated.slice(Math.max(keep, 0))) {
+            try {
+                await unlink(join(sessionsDir, entry.name));
+                pruned += 1;
+            }
+            catch {
+                // Already gone or locked — retention is best-effort.
+            }
+        }
+        return pruned;
+    }
+    catch {
+        return 0;
+    }
+}
+//# sourceMappingURL=run-event-log.js.map

package/dist/web-server/run-event-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-event-log.js","sourceRoot":"","sources":["../../src/web-server/run-event-log.ts"],"names":[],"mappings":"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"}

package/dist/web-server/session-reconciler.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Session liveness reconciliation — the world's opinion on top of the store's.
+ *
+ * `deriveSessionPhase` (session-store) answers "what does this record claim" from
+ * persisted evidence alone. This module answers "is that still true", using the
+ * two liveness sources that exist outside the DAG:
+ *
+ *  - a run claim's pid, probed with signal 0. ARCS-driven runs are headless
+ *    `claude -p` children ARCS spawned itself, so their liveness is a local
+ *    process fact — and the persisted pid is what makes it readable from a
+ *    server process that did not spawn them.
+ *  - `claude agents --json`, which lists the live interactive/background
+ *    sessions a terminal is driving. That is the only way to tell a session ARCS
+ *    merely observes from one whose terminal has since been closed.
+ *
+ * Two shapes of work, deliberately separated:
+ *
+ *  - `settleOrphanedRuns` WRITES: a claim whose process is gone settles as
+ *    outcome `interrupted`, the claim is cleared and the session's run event
+ *    logs are pruned. Runs once at startup (see app.ts), because a claim
+ *    persisted by a previous process can never be live in this one unless its
+ *    child outlived the restart.
+ *  - `reconcileSessionPhases` READS: it returns demoted phases and never writes.
+ *    On-demand only — there is no timer here, and no poller.
+ *
+ * Everything that touches the outside world is tolerant by construction: the
+ * probe is a subprocess of a binary that may not exist, running a command whose
+ * output shape is claude's to change. A missing binary, a non-zero exit, an
+ * empty stdout or unparsable JSON all degrade to the store-derived phase and
+ * NEVER throw — a reconciler that can fail would take the sessions UI down with
+ * every claude release.
+ */
+import { type SessionMeta, type SessionPhase } from "../utils/session-store.js";
+/**
+ * One live agent as reported by `claude agents --json` (verified on claude
+ * 2.1.223: live interactive and background sessions, `{pid, cwd, sessionId,
+ * name, state|status}`). Every field is optional because the wire shape belongs
+ * to claude — a release that renames one must degrade this module, not break it.
+ */
+export interface LiveAgent {
+    pid?: number;
+    cwd?: string;
+    sessionId?: string;
+    name?: string;
+    /** `status`, falling back to `state` — reported, never branched on. */
+    status?: string;
+}
+/** Raw probe result: `ok:false` covers missing binary, non-zero exit, timeout. */
+export type AgentsProbeResult = {
+    ok: true;
+    stdout: string;
+} | {
+    ok: false;
+};
+export type AgentsProbe = () => Promise<AgentsProbeResult>;
+/**
+ * Parses `claude agents --json` stdout into live agents.
+ *
+ * `null` means "the probe answered nothing usable" (empty output, non-JSON, a
+ * JSON shape carrying no array) and is NOT the same as `[]`, which means "the
+ * probe worked and no agent is live". Only the second may demote a session:
+ * conflating them would mark every observed session idle the day claude changes
+ * its output.
+ */
+export declare function parseLiveAgents(stdout: string): LiveAgent[] | null;
+/**
+ * Runs the probe and parses it. `null` on every degraded path — missing binary,
+ * non-zero exit, timeout, unparsable output, or a probe that threw.
+ */
+export declare function listLiveClaudeAgents(options?: {
+    probe?: AgentsProbe;
+}): Promise<LiveAgent[] | null>;
+/**
+ * Whether a pid is a live process, via signal 0 (no signal delivered).
+ *
+ * SHORTCUT: pids are reused, so a recycled pid reads alive and keeps an orphan
+ * claim standing; upgrade to a start-time check (`/proc/<pid>/stat` field 22 or
+ * `ps -o lstart`) when a stuck claim is ever actually observed.
+ */
+export declare function isProcessAlive(pid: number): boolean;
+export interface ReconcileOptions {
+    /** Injectable `claude agents --json` probe (tests). */
+    probe?: AgentsProbe;
+    /** Injectable pid liveness (tests). */
+    isAlive?: (pid: number) => boolean;
+    /** Clock in epoch ms; defaults to `Date.now()`. */
+    now?: number;
+}
+export interface SessionPhaseView {
+    sessionId: string;
+    phase: SessionPhase;
+}
+/**
+ * The store-derived phase, demoted when the world disagrees.
+ *
+ * Demotion is one-way: this can turn `running` into `idle`, never the reverse.
+ * Nothing outside the record may promote a session — the DAG stays the source
+ * of truth and the probe is only ever allowed to take evidence away.
+ *
+ * Which evidence applies depends on what the record claims, not on its origin:
+ *  - a run claim is checked against its pid. `claude agents` never lists a
+ *    headless `claude -p` child, so asking it about an ARCS run would demote
+ *    every healthy run.
+ *  - everything else is checked against the agent list. `agents === null` (the
+ *    probe degraded) leaves the `lastCheckpointAt`-derived phase untouched.
+ */
+export declare function reconcilePhase(session: SessionMeta, agents: LiveAgent[] | null, options?: ReconcileOptions): SessionPhase;
+/**
+ * Reconciled phase for every session in a project. Read-only: no writes, no
+ * timer, and at most ONE `claude agents --json` for the whole index — never one
+ * per session.
+ *
+ * The probe is LAZY: `claude agents --json` costs ~0.35s of wall clock and a
+ * whole subprocess, and its answer is read at a single branch of
+ * `reconcilePhase`. Every terminal record, every idle one and every ARCS run
+ * holding a claim decides without it, so a probe fired before the phases are
+ * derived is a subprocess whose result is thrown away — on EVERY sessions
+ * request, list and detail alike, at whatever rate the watcher invalidates the
+ * query. So the derivation runs first and the probe only follows when some
+ * record actually reaches that branch.
+ *
+ * Skipping it passes `null` — the same value a degraded probe yields, and the
+ * value no session left in this pass can read: reaching the `agents` branch is
+ * precisely the condition that would have run the probe.
+ */
+export declare function reconcileSessionPhases(projectDir: string, options?: ReconcileOptions): Promise<SessionPhaseView[]>;
+export interface SettledOrphan {
+    sessionId: string;
+    runId: string;
+    pid?: number;
+}
+/**
+ * Settles every run claim in a project whose process is gone.
+ *
+ * A claim only survives when its pid is still alive — a run spawned by a
+ * previous server process either outlived the restart (leave it be; it still
+ * holds the write-target) or died with it, and a dead claim that is never
+ * cleared is a session stuck on `running` for good. The settled run keeps
+ * whatever `metadata.run` already held and gains `outcome: "interrupted"`,
+ * which no live run can ever produce.
+ *
+ * A settle here also prunes the session's run event logs, exactly as the route's
+ * own write-back does — this is the ONLY settle an interrupted run ever gets, so
+ * it is the only place that can bound the logs of a session whose runs never
+ * settle normally.
+ *
+ * Never throws: a project whose index cannot be read is skipped, and a record
+ * deleted mid-sweep is simply not settled.
+ */
+export declare function settleOrphanedRuns(projectDir: string, options?: ReconcileOptions): Promise<SettledOrphan[]>;
+/**
+ * Startup sweep across every registered project.
+ *
+ * Composition-time work (app.ts calls it once, fire-and-forget) but the logic
+ * lives here. One pass, no timer: liveness questions after startup are answered
+ * on demand by `reconcileSessionPhases`.
+ *
+ * Never throws — a data dir without a readable meta.json settles nothing and
+ * reports it, rather than taking the server down at boot.
+ */
+export declare function settleOrphanedRunsOnStartup(dataDir?: string, options?: ReconcileOptions): Promise<SettledOrphan[]>;
+//# sourceMappingURL=session-reconciler.d.ts.map

package/dist/web-server/session-reconciler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-reconciler.d.ts","sourceRoot":"","sources":["../../src/web-server/session-reconciler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAMH,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,YAAY,EAGlB,MAAM,2BAA2B,CAAC;AAQnC;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,kFAAkF;AAClF,MAAM,MAAM,iBAAiB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC;AAC7E,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAoF3D;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,IAAI,CAiBlE;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,WAAW,CAAA;CAAO,GACpC,OAAO,CAAC,SAAS,EAAE,GAAG,IAAI,CAAC,CAU7B;AAMD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CASnD;AAMD,MAAM,WAAW,gBAAgB;IAC/B,uDAAuD;IACvD,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,uCAAuC;IACvC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACnC,mDAAmD;IACnD,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,YAAY,CAAC;CACrB;AAcD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,WAAW,EACpB,MAAM,EAAE,SAAS,EAAE,GAAG,IAAI,EAC1B,OAAO,GAAE,gBAAqB,GAC7B,YAAY,CAad;AAeD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,sBAAsB,CAC1C,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAa7B;AAMD,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAQD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,aAAa,EAAE,CAAC,CAqC1B;AAED;;;;;;;;;GASG;AACH,wBAAsB,2BAA2B,CAC/C,OAAO,GAAE,MAAqB,EAC9B,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,aAAa,EAAE,CAAC,CAa1B"}