@aron98/load-lock 0.1.1 → 1.0.0

package/dist/cli/main.js

@@ -7,12 +7,15 @@
  */
 import { spawn } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
 import { LLClient, withClient } from "../shared/client.js";
 import { ProtocolError } from "../shared/protocol.js";
+import { waitForTurn } from "../shared/wait-turn.js";
+import { stateDir, socketPath } from "../core/persist.js";
+import { isWindows, probeTransport, killProcessGroup } from "../shared/transport.js";
 import { installCommand, uninstallCommand } from "./install.js";
 import { hookCommand } from "./hook.js";
+import { topCommand } from "./top.js";
 // ---------------------------------------------------------------- arg parsing
 const argv = process.argv.slice(2);
 let flags = {};
@@ -81,6 +84,13 @@ async function main() {
             });
             return;
         }
+        // ------------------------------------------------------------- dashboard
+        case "top": {
+            // Full-screen live dashboard (read-only, never acquires a permit).
+            // Falls back to a single rendered frame when stdout is not a TTY.
+            await topCommand({ once: B("once") });
+            return;
+        }
         case "inspect":
         case "machine":
             out(await withClient((c) => c.request("inspect", {})));
@@ -108,6 +118,8 @@ async function main() {
                     changes.offerTimeoutMs = N("offer-timeout-ms", 0);
                 if (S("max-wait-ms"))
                     changes.maxWaitMs = N("max-wait-ms", 0);
+                if (S("max-turn-wait-ms"))
+                    changes.maxTurnWaitMs = N("max-turn-wait-ms", 0);
                 if (S("start-timeout-ms"))
                     changes.startTimeoutMs = N("start-timeout-ms", 0);
                 if (S("untracked-lease-ms"))
@@ -115,7 +127,7 @@ async function main() {
                 if (S("heavy-work-heuristic"))
                     changes.guidance = { heavyWorkHeuristic: S("heavy-work-heuristic") };
                 if (!Object.keys(changes).length)
-                    fail("configure: no changes given (--capacity, --offer-timeout-ms, --max-wait-ms, --start-timeout-ms, --untracked-lease-ms, --heavy-work-heuristic)");
+                    fail("configure: no changes given (--capacity, --offer-timeout-ms, --max-wait-ms, --max-turn-wait-ms, --start-timeout-ms, --untracked-lease-ms, --heavy-work-heuristic)");
                 out(await c.request("configure", { expectedVersion: expected, changes, reason, author }));
             });
             return;
@@ -196,55 +208,24 @@ async function main() {
         case "wait": {
             // Watches a queued request; auto-claims the offer when capacity is
             // handed to it and prints the permit token. Honest bounded blocking
-            // for scriptable flows (aider, plain shell scripts).
+            // for scriptable flows (aider, plain shell scripts). Shares the exact
+            // implementation with the MCP wait_for_turn tool and the OpenCode
+            // plugin (src/shared/wait-turn.ts).
             const id = S("id") || fail("wait: --id <request-id> required");
             const timeoutMs = N("timeout", 600_000);
             const agent = S("agent", defaultAgent());
             const c = new LLClient();
             await c.connect();
             try {
-                let last = 0;
-                let resolved = false;
-                const permit = await new Promise((resolve) => {
-                    const finish = (v) => {
-                        if (!resolved) {
-                            resolved = true;
-                            resolve(v);
-                        }
-                    };
-                    const timer = timeoutMs > 0 ? setTimeout(() => finish(null), timeoutMs) : null;
-                    void (async () => {
-                        while (!resolved) {
-                            try {
-                                const r = (await c.request("events", { sinceEventId: last, agentId: agent }));
-                                last = r.latestEventId;
-                                for (const ev of r.events) {
-                                    if (ev.entry?.requestId !== id)
-                                        continue;
-                                    if (ev.type === "offered" && ev.offerToken) {
-                                        const claimed = (await c.request("claim", { offerToken: ev.offerToken }));
-                                        if (timer)
-                                            clearTimeout(timer);
-                                        finish(claimed.entry.permitToken);
-                                    }
-                                    else if (ev.type === "cancelled" || ev.type === "paused" || ev.type === "reclaimed") {
-                                        if (timer)
-                                            clearTimeout(timer);
-                                        finish(null);
-                                    }
-                                }
-                            }
-                            catch {
-                                /* transient; retry */
-                            }
-                            await new Promise((r2) => setTimeout(r2, 200));
-                        }
-                    })();
-                });
-                if (!permit)
-                    fail("wait: timed out or the request was cancelled/paused/reclaimed", 69);
-                out({ permit_token: permit });
-                return;
+                const r = await waitForTurn({ client: c, agentId: agent, requestId: id, timeoutMs });
+                if (r.state === "granted" && r.entry?.permitToken) {
+                    out({ permit_token: r.entry.permitToken, state: r.state, request_id: r.requestId, auto_claimed: r.autoClaimed ?? false });
+                    return;
+                }
+                out({ state: r.state, request_id: r.requestId, detail: r.detail ?? r.nextAction });
+                if (r.state === "still_queued")
+                    fail(`wait: still queued (position ${r.queuePosition ?? "?"}) after ${r.waitedMs}ms`, 68);
+                fail(`wait: request is ${r.state.replace("_", " ")} — ${r.nextAction}`, 69);
             }
             finally {
                 c.close();
@@ -264,7 +245,7 @@ async function main() {
             const sub = rest[0] ?? "status";
             if (sub === "stop") {
                 // Connect and ask... simplest: SIGTERM via daemon.json pid.
-                const dir = process.env.LOAD_LOCK_STATE_DIR || join(process.env.HOME ?? "~", ".local", "state", "load-lock");
+                const dir = stateDir();
                 try {
                     const info = JSON.parse(readFileSync(join(dir, "daemon.json"), "utf8"));
                     process.kill(info.pid, "SIGTERM");
@@ -291,9 +272,13 @@ async function main() {
             const report = {};
             report.node = process.version;
             report.platform = process.platform;
-            const dir = process.env.LOAD_LOCK_STATE_DIR || join(homedir(), ".local", "state", "load-lock");
+            const dir = stateDir();
             report.stateDir = dir;
-            report.socketExists = existsSync(join(dir, "daemon.sock"));
+            const sock = socketPath();
+            report.socket = sock;
+            // Named pipes are kernel objects, not filesystem entries — probe by
+            // connecting on Windows; on POSIX a file check is enough.
+            report.socketExists = isWindows() ? await probeTransport(sock) : existsSync(sock);
             report.configExists = existsSync(join(dir, "config.json"));
             report.journalExists = existsSync(join(dir, "journal.json"));
             try {
@@ -356,7 +341,7 @@ async function main() {
             return;
         }
         default:
-            fail(`unknown command "${cmd}". Commands: status, inspect, config, pending, events, acquire, claim, release, cancel, rejoin, mark-started, attach-pid, wait, run, service, doctor, recover, install, uninstall, hook, agent-guide`);
+            fail(`unknown command "${cmd}". Commands: status, top, inspect, config, pending, events, acquire, claim, release, cancel, rejoin, mark-started, attach-pid, wait, run, service, doctor, recover, install, uninstall, hook, agent-guide`);
     }
 }
 // ------------------------------------------------------------------ run helper
@@ -416,21 +401,11 @@ async function runWithPermit(jobArgv) {
             await client.request("start_job", { permitToken, pid: child.pid, pgid });
         }
         catch (err) {
-            try {
-                process.kill(-pgid, "SIGKILL");
-            }
-            catch {
-                /* already gone */
-            }
+            killProcessGroup(pgid, "SIGKILL");
             fail(`permit no longer startable (${err.message}); job not started`, 69);
         }
         const forward = (sig) => {
-            try {
-                process.kill(-pgid, sig);
-            }
-            catch {
-                /* already gone */
-            }
+            killProcessGroup(pgid, sig);
         };
         process.on("SIGTERM", () => forward("SIGTERM"));
         process.on("SIGINT", () => forward("SIGINT"));

package/dist/cli/top.d.ts

@@ -0,0 +1,7 @@
+export interface TopOptions {
+    /** Render one frame and exit (also implied when stdout is not a TTY). */
+    once?: boolean;
+    /** Local re-render cadence for countdowns (default 500 ms). */
+    tickMs?: number;
+}
+export declare function topCommand(opts?: TopOptions): Promise<void>;

package/dist/cli/top.js

@@ -0,0 +1,98 @@
+/**
+ * `load-lock top` — portable, zero-dependency full-screen terminal dashboard
+ * for the machine-wide budget. Uses the library's own client + protocol
+ * (never scrapes CLI output); live updates come from the `watch` event
+ * stream, with reconnect + event-cursor resume across daemon restarts.
+ *
+ * Read-only. The viewer itself is light work — it never acquires a permit.
+ */
+import { DashboardFeed } from "../dashboard/feed.js";
+import { renderFrame } from "../dashboard/frame.js";
+import { LLClient } from "../shared/client.js";
+const HIDE_CURSOR = "\x1b[?25l";
+const SHOW_CURSOR = "\x1b[?25h";
+const ALT_SCREEN = "\x1b[?1049h";
+const LEAVE_ALT = "\x1b[?1049l";
+export async function topCommand(opts = {}) {
+    const once = opts.once || !process.stdout.isTTY;
+    const client = new LLClient();
+    const feed = new DashboardFeed(client);
+    try {
+        await feed.start();
+        if (once) {
+            const frame = renderFrame(feed.view(), process.stdout.columns || 100, 1000);
+            process.stdout.write(frame.join("\n") + "\n");
+            return;
+        }
+        await runLive(feed, opts);
+    }
+    finally {
+        await feed.stop();
+    }
+}
+async function runLive(feed, opts) {
+    const out = process.stdout;
+    const tickMs = Math.max(100, opts.tickMs ?? 500);
+    let stopped = false;
+    const paint = () => {
+        const width = out.columns || 100;
+        const height = out.rows || 40;
+        const frame = renderFrame(feed.view(), width, Math.max(1, height - 1));
+        // Pad to full height so old content never lingers after shrinking.
+        while (frame.length < height - 1)
+            frame.push("");
+        const body = frame.map((l) => l + "\x1b[K").join("\n");
+        out.write(`\x1b[H\x1b[2J${body}\n`);
+    };
+    // The feed signals change asynchronously; the tick loop below repaints on
+    // every tick anyway (cheap string render) so new events and countdowns
+    // both appear promptly without a paint storm per event burst.
+    out.write(ALT_SCREEN + HIDE_CURSOR);
+    out.write("\x1b[H\x1b[2J");
+    process.stdin.setRawMode?.(true);
+    process.stdin.resume();
+    const restore = () => {
+        process.stdin.setRawMode?.(false);
+        out.write(SHOW_CURSOR + LEAVE_ALT);
+    };
+    let exiting = false;
+    const quit = () => {
+        if (exiting)
+            return;
+        exiting = true;
+        restore();
+        stopped = true;
+        process.stdin.pause();
+    };
+    const onKey = (data) => {
+        const k = data.toString("utf8");
+        if (k === "q" || k === "Q" || k === "\x1b" || k === "\x03")
+            quit();
+        else if (k === "r" || k === "R")
+            void feed.resync().catch(() => { });
+    };
+    process.stdin.on("data", onKey);
+    const onResize = () => paint();
+    out.on("resize", onResize);
+    const onSignal = () => {
+        quit();
+    };
+    process.on("SIGINT", onSignal);
+    process.on("SIGTERM", onSignal);
+    paint();
+    try {
+        while (!stopped) {
+            await new Promise((r) => setTimeout(r, tickMs));
+            if (stopped)
+                continue;
+            paint(); // cheap local re-render keeps countdowns ticking and shows new events
+        }
+    }
+    finally {
+        restore();
+        process.stdin.removeListener("data", onKey);
+        out.removeListener("resize", onResize);
+        process.removeListener("SIGINT", onSignal);
+        process.removeListener("SIGTERM", onSignal);
+    }
+}

package/dist/core/daemon.d.ts

@@ -22,6 +22,10 @@ export declare class Daemon {
     machine: Machine;
     server: Server | null;
     private watchers;
+    /** All open client connections — destroyed on stop() so a graceful
+     *  shutdown cuts waiting clients loose (they reconnect + detect the
+     *  restart via the event cursor) and the process can exit promptly. */
+    private conns;
     private waiters;
     private sentEventId;
     private stateDirPath;
@@ -36,7 +40,11 @@ export declare class Daemon {
         recover?: boolean;
     });
     start(): Promise<void>;
-    /** Bind the socket, replacing it only if it is verifiably stale. */
+    /**
+     * Bind the endpoint, replacing it only if it is verifiably stale.
+     * Windows: named pipes are kernel objects — no stale file can exist, so
+     * just refuse if another daemon owns the pipe.
+     */
     private claimSocket;
     stop(): void;
     private onConnection;
@@ -65,15 +73,28 @@ export declare class Daemon {
      */
     private sweep;
 }
-/** Linux: /proc/<pid>/stat field 22 (starttime) defeats pid reuse. */
-export declare function isProcessAlive(pid: number, expectedStartTime?: string): boolean | null;
+/**
+ * Liveness via signal 0 — the /proc-less fallback (macOS, Windows).
+ * EPERM counts as alive: the process exists but is not signalable by us.
+ */
+export declare function aliveBySignalZero(pid: number): boolean;
+/**
+ * Linux: /proc/<pid>/stat field 22 (starttime) defeats pid reuse.
+ * Windows: no /proc and no start time — signal-0 fallback only; the
+ * pid-reuse defense is unavailable there (documented limitation).
+ * macOS: /proc is absent, so the signal-0 fallback applies too.
+ */
+export declare function isProcessAlive(pid: number, expectedStartTime?: string, platform?: NodeJS.Platform): boolean | null;
 /**
  * Job liveness: a tracked job is alive if its pid is alive (start-time
  * matched) OR any process in its process group is alive — covering
  * subprocesses and background jobs that outlive their parent. Returns
  * true/false on Linux; on platforms without /proc the pgid scan is
  * unavailable and the result may be null (unknown => conservative keep).
+ * Windows: no process groups — only the main pid is checked, so a permit
+ * is released once the main pid dies even if children survive (documented
+ * limitation; adapters should kill the tree via taskkill /T).
  */
-export declare function jobAlive(pid?: number, pgid?: number, pidStartTime?: string): boolean | null;
+export declare function jobAlive(pid?: number, pgid?: number, pidStartTime?: string, platform?: NodeJS.Platform): boolean | null;
 /** Read the Linux start time of a pid (pid-reuse-safe association). */
 export declare function processStartTime(pid: number): string | undefined;

package/dist/core/daemon.js

@@ -16,7 +16,7 @@
  * All state mutations run on one event loop => every RPC is atomic wrt all
  * others; start_job is therefore atomic wrt reclamation.
  */
-import { connect, createServer } from "node:net";
+import { createServer } from "node:net";
 import { existsSync, mkdirSync, unlinkSync, writeFileSync, readFileSync, rmSync } from "node:fs";
 import { readdirSync } from "node:fs";
 import { join } from "node:path";
@@ -24,10 +24,15 @@ import { Machine } from "./state.js";
 import { loadState, saveState, loadJournal, saveJournal, socketPath as defaultSocket, stateDir as defaultStateDir } from "./persist.js";
 import { inspectMachine } from "./sysinfo.js";
 import { ProtocolError } from "../shared/protocol.js";
+import { isWindows, probeTransport } from "../shared/transport.js";
 export class Daemon {
     machine;
     server = null;
     watchers = new Set();
+    /** All open client connections — destroyed on stop() so a graceful
+     *  shutdown cuts waiting clients loose (they reconnect + detect the
+     *  restart via the event cursor) and the process can exit promptly. */
+    conns = new Set();
     waiters = new Map();
     sentEventId;
     stateDirPath;
@@ -70,10 +75,20 @@ export class Daemon {
         this.sweepTimer.unref?.();
         this.sweep(); // catch anything that expired while we were down
     }
-    /** Bind the socket, replacing it only if it is verifiably stale. */
+    /**
+     * Bind the endpoint, replacing it only if it is verifiably stale.
+     * Windows: named pipes are kernel objects — no stale file can exist, so
+     * just refuse if another daemon owns the pipe.
+     */
     async claimSocket() {
+        if (isWindows()) {
+            if (await probeTransport(this.socketPath)) {
+                throw new ProtocolError("denied", `another daemon is already listening on ${this.socketPath}`);
+            }
+            return;
+        }
         if (existsSync(this.socketPath)) {
-            const live = await probeUnixSocket(this.socketPath);
+            const live = await probeTransport(this.socketPath);
             if (live) {
                 throw new ProtocolError("denied", `another daemon is already listening on ${this.socketPath}`);
             }
@@ -96,13 +111,23 @@ export class Daemon {
         for (const w of this.watchers)
             w.socket.destroy();
         this.watchers.clear();
+        // Cut every client loose too: a graceful stop must not leave a zombie
+        // serving already-connected clients while the socket path moves on.
+        // Clients see the disconnect, reconnect, and detect the restart.
+        for (const s of this.conns)
+            s.destroy();
+        this.conns.clear();
         this.server?.close();
-        try {
-            if (existsSync(this.socketPath))
-                unlinkSync(this.socketPath);
-        }
-        catch {
-            /* ignore */
+        if (!isWindows()) {
+            // Windows: the named pipe is a kernel object and vanishes on close;
+            // touching the pipe path from the filesystem side can block.
+            try {
+                if (existsSync(this.socketPath))
+                    unlinkSync(this.socketPath);
+            }
+            catch {
+                /* ignore */
+            }
         }
         try {
             rmSync(join(this.stateDirPath, "daemon.json"), { force: true });
@@ -113,6 +138,7 @@ export class Daemon {
     }
     // ----------------------------------------------------------------- framing
     onConnection(sock) {
+        this.conns.add(sock);
         let buf = "";
         sock.on("data", (chunk) => {
             buf += chunk.toString("utf8");
@@ -126,6 +152,7 @@ export class Daemon {
         });
         sock.on("error", () => sock.destroy());
         sock.on("close", () => {
+            this.conns.delete(sock);
             for (const w of [...this.watchers])
                 if (w.socket === sock)
                     this.watchers.delete(w);
@@ -428,18 +455,31 @@ export class Daemon {
     }
 }
 // --------------------------------------------------------------------- helpers
-async function probeUnixSocket(path) {
-    return new Promise((resolve) => {
-        const sock = connect(path);
-        sock.once("connect", () => {
-            sock.end();
-            resolve(true);
-        });
-        sock.once("error", () => resolve(false));
-    });
+/**
+ * Liveness via signal 0 — the /proc-less fallback (macOS, Windows).
+ * EPERM counts as alive: the process exists but is not signalable by us.
+ */
+export function aliveBySignalZero(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err?.code === "EPERM";
+    }
 }
-/** Linux: /proc/<pid>/stat field 22 (starttime) defeats pid reuse. */
-export function isProcessAlive(pid, expectedStartTime) {
+/**
+ * Linux: /proc/<pid>/stat field 22 (starttime) defeats pid reuse.
+ * Windows: no /proc and no start time — signal-0 fallback only; the
+ * pid-reuse defense is unavailable there (documented limitation).
+ * macOS: /proc is absent, so the signal-0 fallback applies too.
+ */
+export function isProcessAlive(pid, expectedStartTime, platform = process.platform) {
+    if (isWindows(platform)) {
+        // Start time is unobtainable without native APIs; pid reuse is possible
+        // during this window (documented in docs/OPERATIONS.md).
+        return aliveBySignalZero(pid);
+    }
     try {
         const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
         if (expectedStartTime !== undefined) {
@@ -455,13 +495,7 @@ export function isProcessAlive(pid, expectedStartTime) {
         // /proc unavailable (macOS): fall back to signal 0. Pid reuse is possible
         // here; documented limitation — that is why adapters should prefer
         // run_with_permit / process-group tracking where available.
-        try {
-            process.kill(pid, 0);
-            return true;
-        }
-        catch {
-            return false;
-        }
+        return aliveBySignalZero(pid);
     }
 }
 /**
@@ -470,14 +504,17 @@ export function isProcessAlive(pid, expectedStartTime) {
  * subprocesses and background jobs that outlive their parent. Returns
  * true/false on Linux; on platforms without /proc the pgid scan is
  * unavailable and the result may be null (unknown => conservative keep).
+ * Windows: no process groups — only the main pid is checked, so a permit
+ * is released once the main pid dies even if children survive (documented
+ * limitation; adapters should kill the tree via taskkill /T).
  */
-export function jobAlive(pid, pgid, pidStartTime) {
+export function jobAlive(pid, pgid, pidStartTime, platform = process.platform) {
     if (pid !== undefined) {
-        const alive = isProcessAlive(pid, pidStartTime);
+        const alive = isProcessAlive(pid, pidStartTime, platform);
         if (alive === true)
             return true;
     }
-    if (pgid !== undefined) {
+    if (pgid !== undefined && !isWindows(platform)) {
         const scan = scanProcessGroup(pgid);
         if (scan !== null)
             return scan;

package/dist/core/persist.js

@@ -1,6 +1,7 @@
 /**
  * Atomic JSON persistence for daemon config + change history.
- * State dir: $XDG_STATE_HOME/load-lock (default ~/.local/state/load-lock).
+ * State dir: $XDG_STATE_HOME/load-lock (default ~/.local/state/load-lock;
+ * Windows: %LOCALAPPDATA%\load-lock — see shared/transport.ts).
  *
  * Only *configuration* persists across daemon restarts. Permits and queue
  * are ephemeral by design (see docs/ARCHITECTURE.md — restart behavior):
@@ -9,20 +10,12 @@
 import { mkdirSync, writeFileSync, renameSync, readFileSync, existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { defaultConfig } from "./state.js";
+import { resolveStateDir, resolveSocketPath } from "../shared/transport.js";
 export function stateDir(override) {
-    if (override)
-        return override;
-    if (process.env.LOAD_LOCK_STATE_DIR)
-        return process.env.LOAD_LOCK_STATE_DIR;
-    const xdg = process.env.XDG_STATE_HOME || join(process.env.HOME ?? "~", ".local", "state");
-    return join(xdg, "load-lock");
+    return resolveStateDir(process.platform, process.env, override);
 }
 export function socketPath(override) {
-    if (override)
-        return override;
-    if (process.env.LOAD_LOCK_SOCKET)
-        return process.env.LOAD_LOCK_SOCKET;
-    return join(stateDir(), "daemon.sock");
+    return resolveSocketPath(process.platform, process.env, override);
 }
 export function loadState(dir) {
     const path = join(dir, "config.json");

package/dist/core/state.js

@@ -42,6 +42,7 @@ export function defaultConfig() {
         pools: { heavy: { capacity: 1 } },
         offerTimeoutMs: 30_000,
         maxWaitMs: 5_000,
+        maxTurnWaitMs: 600_000,
         startTimeoutMs: 120_000,
         untrackedLeaseMs: 15 * 60_000,
         guidance: {},
@@ -635,6 +636,7 @@ export class Machine {
                 pools: this.config.pools,
                 offerTimeoutMs: this.config.offerTimeoutMs,
                 maxWaitMs: this.config.maxWaitMs,
+                maxTurnWaitMs: this.config.maxTurnWaitMs,
                 startTimeoutMs: this.config.startTimeoutMs,
                 untrackedLeaseMs: this.config.untrackedLeaseMs,
             },
@@ -755,6 +757,9 @@ export class Machine {
         if (c.maxWaitMs !== undefined && (c.maxWaitMs < 0 || c.maxWaitMs > 600_000)) {
             throw new ProtocolError("invalid", "maxWaitMs must be within [0, 600000]");
         }
+        if (c.maxTurnWaitMs !== undefined && (c.maxTurnWaitMs < 1000 || c.maxTurnWaitMs > 3_600_000)) {
+            throw new ProtocolError("invalid", "maxTurnWaitMs must be within [1000, 3600000]");
+        }
         if (c.startTimeoutMs !== undefined && (c.startTimeoutMs < 1000 || c.startTimeoutMs > 3_600_000)) {
             throw new ProtocolError("invalid", "startTimeoutMs must be within [1000, 3600000]");
         }
@@ -770,6 +775,8 @@ export class Machine {
             this.config.offerTimeoutMs = c.offerTimeoutMs;
         if (c.maxWaitMs !== undefined)
             this.config.maxWaitMs = c.maxWaitMs;
+        if (c.maxTurnWaitMs !== undefined)
+            this.config.maxTurnWaitMs = c.maxTurnWaitMs;
         if (c.startTimeoutMs !== undefined)
             this.config.startTimeoutMs = c.startTimeoutMs;
         if (c.untrackedLeaseMs !== undefined)

package/dist/dashboard/feed.d.ts

@@ -0,0 +1,74 @@
+import { type DashboardView, type FeedState } from "./view.js";
+/** Structural subset of LLClient the feed needs (LLClient satisfies it). */
+export interface FeedClient {
+    connect(): Promise<void>;
+    request<T = any>(method: string, params?: Record<string, unknown>): Promise<T>;
+    watch(agentId: string, onEvent: (ev: Record<string, unknown>) => void): Promise<void>;
+    onDisconnect(cb: () => void): unknown;
+    close(): void;
+}
+export interface FeedOptions {
+    /** Rolling event history length (default 60). */
+    eventHistory?: number;
+    /** Slow safety refresh while live (default 15_000 ms; 0 disables). */
+    slowRefreshMs?: number;
+    /** Debounce window for post-event status pulls (default 40 ms). */
+    refreshDebounceMs?: number;
+    /** Inspect refresh cadence (default 60_000 ms). */
+    inspectEveryMs?: number;
+    /** Reconnect backoff base (default 250 ms). */
+    reconnectBaseMs?: number;
+}
+export declare class DashboardFeed {
+    private client;
+    private opts;
+    private events;
+    private latestEventId;
+    private status;
+    private inspect;
+    private inspectAt;
+    private lastSyncAt;
+    private state;
+    private restartNote;
+    private daemonStartedAt;
+    private refreshTimer;
+    private slowTimer;
+    private stopped;
+    private unsub;
+    private connecting;
+    private viewSeq;
+    /** Fired whenever the rendered view might have changed (state or data). */
+    onChange?: () => void;
+    /** Fired on connection-state transitions. */
+    onState?: (s: FeedState) => void;
+    constructor(client: FeedClient, opts?: FeedOptions);
+    currentState(): FeedState;
+    private setState;
+    private emitChange;
+    /** Connect, subscribe, and pull an initial full snapshot. */
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private connectAndSync;
+    /**
+     * Full snapshot: status + events since cursor (+ inspect if stale).
+     * Detects daemon restarts two ways — event ids going backwards, or the
+     * daemon's own startedAt changing — then resets the cursor and re-pulls
+     * history (ids are durable per daemon lifetime, not across restarts).
+     */
+    resync(): Promise<void>;
+    /** Status-only pull (used after event bursts; keeps inspect cached). */
+    refresh(): Promise<void>;
+    private refreshInspect;
+    private handleEvent;
+    private mergeEvents;
+    private handleDisconnect;
+    private reconnectLoop;
+    /**
+     * Admin force-release. Callers MUST gate this behind their own explicit
+     * confirm step — the feed itself never initiates destructive actions.
+     * Returns the reclaimed request's one-line description for toasts.
+     */
+    forceRelease(requestId: string): Promise<void>;
+    /** Render-ready snapshot; countdowns are computed at `now`. */
+    view(now?: number): DashboardView;
+}