@aron98/load-lock 1.3.0 → 1.5.0

package/dist/cli/service.js

@@ -0,0 +1,261 @@
+/**
+ * `load-lock service start|stop|restart|status` (issue #38): daemon
+ * lifecycle, extracted from main.ts so `service restart` and
+ * `load-lock update` (which restarts after applying) compose the same
+ * hardened stop + honest start paths instead of duplicating them.
+ *
+ *  - stop (hardened): SIGTERM → bounded wait → SIGKILL → verify the
+ *    socket is actually free; crash leftovers cleaned either way.
+ *  - start (honest): auto-spawn via connect, hello confirmation;
+ *    refusals name the conflicting pid.
+ *  - restart: stop then start, reporting both phases; any failure names
+ *    the phase and reason.
+ *
+ * Failures throw ServiceError (message + exit code); callers decide how
+ * to exit so composition can annotate ("restart failed in the STOP
+ * phase: ...").
+ */
+import { existsSync, readFileSync, rmSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { connect } from "node:net";
+import { setTimeout as delay } from "node:timers/promises";
+import { withClient } from "../shared/client.js";
+import { isWindows, probeTransport } from "../shared/transport.js";
+import { compareVersions, packageVersion } from "../shared/version.js";
+import { stateDir, socketPath } from "../core/persist.js";
+/** A service-phase failure with the exit code the CLI should use. */
+export class ServiceError extends Error {
+    exitCode;
+    constructor(message, exitCode = 70) {
+        super(message);
+        this.exitCode = exitCode;
+    }
+}
+/** daemon.json contents, or null when missing/unreadable. */
+export function readDaemonInfo(dir) {
+    try {
+        return JSON.parse(readFileSync(join(dir, "daemon.json"), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Version-less hello over a raw socket connection: deliberately does NOT
+ * send clientVersion, so asking a daemon for its identity never orders it
+ * to self-restart (used by `service stop` and post-restart confirmation).
+ * Best-effort: resolves null on any failure.
+ */
+export function rawHello(sockPath, timeoutMs = 2000) {
+    return new Promise((resolve) => {
+        let settled = false;
+        let buf = "";
+        const done = (v) => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                sock.destroy();
+            }
+            catch {
+                /* ignore */
+            }
+            resolve(v);
+        };
+        const sock = connect(sockPath, () => {
+            sock.write(JSON.stringify({ id: 1, method: "hello", params: {} }) + "\n");
+        });
+        sock.on("data", (chunk) => {
+            buf += chunk.toString("utf8");
+            const idx = buf.indexOf("\n");
+            if (idx === -1)
+                return;
+            try {
+                const msg = JSON.parse(buf.slice(0, idx));
+                done(msg.ok ? msg.result : null);
+            }
+            catch {
+                done(null);
+            }
+        });
+        sock.on("error", () => done(null));
+        const timer = setTimeout(() => done(null), timeoutMs);
+        timer.unref?.();
+    });
+}
+/** Poll the socket until nothing answers there (bounded). */
+async function waitSocketFree(sockPath, timeoutMs) {
+    const deadline = Date.now() + Math.max(0, timeoutMs);
+    for (;;) {
+        if (!(await probeTransport(sockPath)))
+            return true;
+        if (Date.now() >= deadline)
+            return false;
+        await delay(100);
+    }
+}
+/**
+ * After ordering a self-restart, wait for the daemon to come back running
+ * at least `installed` (the version of this CLI copy). Resolves its hello
+ * result, or null if it did not come back (or an older/pre-handshake
+ * daemon answered again — e.g. the daemon's copy is not actually updated).
+ */
+export async function awaitDaemonUpgraded(sockPath, timeoutMs, installed) {
+    const deadline = Date.now() + Math.max(0, timeoutMs);
+    for (;;) {
+        const h = await rawHello(sockPath, 1500);
+        if (h && typeof h.daemonVersion === "string" && compareVersions(h.daemonVersion, installed) >= 0)
+            return h;
+        if (Date.now() >= deadline)
+            return null;
+        await delay(250);
+    }
+}
+/**
+ * Hardened stop: signal the daemon, wait bounded for its socket to go
+ * silent, escalate to SIGKILL, and only report success once the endpoint
+ * is verifiably free. A leftover silent socket file or daemon.json (crash
+ * leftovers) is cleaned up either way. Returns the report line; throws
+ * ServiceError on failure.
+ */
+export async function serviceStop(timeoutMs) {
+    const dir = stateDir();
+    const sock = socketPath();
+    const info = readDaemonInfo(dir);
+    const answering = await probeTransport(sock);
+    if (!answering) {
+        // Nothing is listening: no daemon to stop. Clean crash leftovers.
+        try {
+            if (!isWindows() && existsSync(sock))
+                unlinkSync(sock);
+        }
+        catch {
+            /* ignore */
+        }
+        try {
+            rmSync(join(dir, "daemon.json"), { force: true });
+        }
+        catch {
+            /* ignore */
+        }
+        return "no running daemon found (stale files cleaned)";
+    }
+    // Identify the daemon: prefer daemon.json, else ask it directly
+    // (version-less hello — stopping must not order a self-restart).
+    let pid = typeof info?.pid === "number" ? info.pid : undefined;
+    if (!pid) {
+        const hello = await rawHello(sock, 1500);
+        if (hello && typeof hello.pid === "number")
+            pid = hello.pid;
+    }
+    if (!pid) {
+        throw new ServiceError(`the socket ${sock} answers but no pid could be identified (daemon did not respond and daemon.json names none) ` +
+            `— cannot stop safely; run \`load-lock doctor\``);
+    }
+    let how = "SIGTERM";
+    let stopped = false;
+    try {
+        process.kill(pid, "SIGTERM");
+    }
+    catch (e) {
+        if (e?.code === "ESRCH")
+            stopped = true; // already gone
+        else
+            throw new ServiceError(`cannot signal daemon pid ${pid}: ${e?.message ?? e}`);
+    }
+    if (!stopped)
+        stopped = await waitSocketFree(sock, timeoutMs);
+    if (!stopped) {
+        how = "SIGKILL";
+        try {
+            process.kill(pid, "SIGKILL");
+        }
+        catch {
+            /* already dead */
+        }
+        stopped = await waitSocketFree(sock, timeoutMs);
+    }
+    if (!stopped) {
+        throw new ServiceError(`daemon pid ${pid} did not stop within ${timeoutMs}ms even after SIGKILL — run \`load-lock doctor\``);
+    }
+    try {
+        if (!isWindows() && existsSync(sock))
+            unlinkSync(sock);
+    }
+    catch {
+        /* ignore */
+    }
+    try {
+        rmSync(join(dir, "daemon.json"), { force: true });
+    }
+    catch {
+        /* ignore */
+    }
+    return `daemon (pid ${pid}) stopped${how === "SIGKILL" ? " (required SIGKILL after SIGTERM)" : ""}`;
+}
+/**
+ * Honest start: connecting auto-spawns a detached daemon (see
+ * shared/client.ts); hello confirms it is up. Refusals name the
+ * conflicting pid. Returns the report line; throws ServiceError on
+ * failure.
+ */
+export async function serviceStart(timeoutMs) {
+    const sock = socketPath();
+    const installed = packageVersion();
+    try {
+        const r = (await withClient((c) => c.request("hello", {}, timeoutMs)));
+        const dv = typeof r.daemonVersion === "string" ? r.daemonVersion : undefined;
+        if (dv && compareVersions(dv, installed) < 0) {
+            // The handshake just ordered this old daemon to self-restart;
+            // confirm it comes back on updated code.
+            const up = await awaitDaemonUpgraded(sock, 8000, installed);
+            if (up) {
+                return `daemon self-restarted ${r.pid} -> ${up.pid} (v${dv} -> v${up.daemonVersion}), running on ${sock}`;
+            }
+            return (`daemon running on pid ${r.pid} (${sock}), daemon v${dv} — older than this CLI v${installed}; ` +
+                `self-restart ordered but not confirmed (its copy may not be updated in place — see docs/OPERATIONS.md)`);
+        }
+        return `daemon running on pid ${r.pid} (${sock})${dv ? `, daemon v${dv}` : ""}`;
+    }
+    catch (e) {
+        if (await probeTransport(sock)) {
+            // Something owns the endpoint. Name it.
+            const hello = await rawHello(sock, 1500);
+            if (hello && typeof hello.pid === "number") {
+                throw new ServiceError(`start refused: socket answered from pid ${hello.pid} — another daemon owns ${sock}; ` +
+                    `if it is stale, run \`load-lock service stop\` first`);
+            }
+            const info = readDaemonInfo(stateDir());
+            if (info && typeof info.pid === "number") {
+                throw new ServiceError(`socket ${sock} answers but the daemon did not respond (daemon.json names pid ${info.pid}) — likely hung; ` +
+                    `run \`load-lock service stop\``);
+            }
+            throw new ServiceError(`start refused: ${sock} is in use but nothing responsive owns it — run \`load-lock doctor\``);
+        }
+        throw e;
+    }
+}
+/**
+ * `service restart` (issue #38): hardened stop, then honest start — both
+ * phases reported; a failure names the phase and reason. Stopping when
+ * nothing runs is fine: the start phase simply spawns a fresh daemon.
+ */
+export async function serviceRestart(stopTimeoutMs = 5000, startTimeoutMs = 10_000) {
+    let stop;
+    try {
+        stop = await serviceStop(stopTimeoutMs);
+    }
+    catch (e) {
+        const reason = e instanceof ServiceError ? e.message : String(e?.message ?? e);
+        throw new ServiceError(`restart failed in the STOP phase: ${reason}`, e instanceof ServiceError ? e.exitCode : 70);
+    }
+    let start;
+    try {
+        start = await serviceStart(startTimeoutMs);
+    }
+    catch (e) {
+        const reason = e instanceof ServiceError ? e.message : String(e?.message ?? e);
+        throw new ServiceError(`restart failed in the START phase (stop phase succeeded: ${stop}) — ${reason}`, e instanceof ServiceError ? e.exitCode : 70);
+    }
+    return { stop, start };
+}

package/dist/cli/update.d.ts

@@ -0,0 +1,53 @@
+export type SelfLocationKind = "bun-global" | "npm-global" | "opencode-cache" | "repo-checkout" | "unknown";
+export interface SelfLocation {
+    kind: SelfLocationKind;
+    /** Package root of this copy. */
+    path: string;
+    /** Explanation shown in reports (part of the refusal reason when refusing). */
+    detail: string;
+}
+/** Inputs classifySelf needs; callers resolve them (tests plant values). */
+export interface ClassifyCtx {
+    home: string;
+    /** bun global node_modules root; default <home>/.bun/install/global/node_modules. */
+    bunGlobalRoot?: string;
+    /** `npm root -g` result; null when npm could not answer. */
+    npmGlobalRoot: string | null;
+    /** opencode cache root (XDG_CACHE_HOME | platform default); null when unknown. */
+    cacheRoot: string | null;
+}
+/**
+ * Classify where this copy of load-lock lives, BEFORE touching anything:
+ *  - bun global (<home>/.bun/install/global/node_modules/...) → update via bun
+ *  - npm global (under `npm root -g`) → update via npm
+ *  - opencode cache copy (<cache>/opencode/npm/...) → refuse: opencode
+ *    manages this copy and refreshes it on its own schedule
+ *  - repo checkout (nearest .git found by walking up, like the omac
+ *    read-grant logic) → refuse with a pointer to the git workflow
+ *  - anything else → unknown → refuse honestly rather than guessing
+ */
+export declare function classifySelf(pkgRoot: string, ctx: ClassifyCtx): SelfLocation;
+export type UpdatePlan = {
+    action: "install";
+    argv: string[];
+    detail: string;
+} | {
+    action: "refuse";
+    reason: string;
+};
+/** What to run for the detected location — or why we refuse to guess. */
+export declare function planUpdate(loc: SelfLocation): UpdatePlan;
+export interface UpdateOptions {
+    /** --check: report only, never install or restart. */
+    check: boolean;
+    /** --json: machine-readable output (house style: humans get prose). */
+    json: boolean;
+}
+/**
+ * The `load-lock update` command. Prints a structured report (JSON with
+ * --json, prose otherwise) and returns the exit code:
+ *   0  up-to-date (check) or applied successfully
+ *   1  update available (--check; includes "cannot self-apply" refusals)
+ *   70 failure or refusal in apply mode
+ */
+export declare function updateCommand(opts: UpdateOptions): Promise<number>;

package/dist/cli/update.js

@@ -0,0 +1,274 @@
+/**
+ * `load-lock update` (issue #38): check the npm registry for a newer
+ * version (npm is the only distribution channel), classify where THIS copy
+ * lives before touching anything, and apply the update via the detected
+ * package manager — or refuse honestly (repo checkouts, opencode-managed
+ * cache copies, unknown locations) rather than guessing. After a
+ * successful apply, `service restart` moves the daemon onto the new code
+ * immediately; the v1.3.0 version handshake stays as the safety net for
+ * daemons nobody explicitly restarts.
+ *
+ * Classification and planning are pure functions of their arguments
+ * (planted-layout testable, like shared/transport.ts); the registry and
+ * package-manager spawns resolve `npm` through PATH so tests stub them
+ * with a fake `npm` on PATH — the real registry is never contacted in
+ * tests and nothing is ever installed by them.
+ *
+ * Exit codes: 0 up-to-date / applied; 1 update available (`--check`,
+ * including "an update exists but this copy cannot self-apply" refusals);
+ * 70 failure (registry unreachable, package manager failed, refused in
+ * apply mode, or restart failed after an applied update).
+ */
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join, sep } from "node:path";
+import { homedir } from "node:os";
+import { compareVersions, packageVersion } from "../shared/version.js";
+import { opencodeCacheRoot, PKG_NAME } from "../shared/pkginfo.js";
+import { thisCopy } from "./copies.js";
+import { serviceRestart, ServiceError } from "./service.js";
+/** Path containment with separator awareness ("a" contains "a" and "a/b"). */
+function isUnder(dir, root) {
+    if (dir === root)
+        return true;
+    return dir.startsWith(root.endsWith(sep) ? root : root + sep);
+}
+/**
+ * Classify where this copy of load-lock lives, BEFORE touching anything:
+ *  - bun global (<home>/.bun/install/global/node_modules/...) → update via bun
+ *  - npm global (under `npm root -g`) → update via npm
+ *  - opencode cache copy (<cache>/opencode/npm/...) → refuse: opencode
+ *    manages this copy and refreshes it on its own schedule
+ *  - repo checkout (nearest .git found by walking up, like the omac
+ *    read-grant logic) → refuse with a pointer to the git workflow
+ *  - anything else → unknown → refuse honestly rather than guessing
+ */
+export function classifySelf(pkgRoot, ctx) {
+    const bunRoot = ctx.bunGlobalRoot ?? join(ctx.home, ".bun", "install", "global", "node_modules");
+    if (isUnder(pkgRoot, bunRoot)) {
+        return { kind: "bun-global", path: pkgRoot, detail: `bun global install under ${bunRoot}` };
+    }
+    if (ctx.npmGlobalRoot && isUnder(pkgRoot, ctx.npmGlobalRoot)) {
+        return { kind: "npm-global", path: pkgRoot, detail: `npm global install under ${ctx.npmGlobalRoot}` };
+    }
+    if (ctx.cacheRoot && isUnder(pkgRoot, join(ctx.cacheRoot, "opencode", "npm"))) {
+        return { kind: "opencode-cache", path: pkgRoot, detail: `opencode-managed cache copy under ${ctx.cacheRoot}` };
+    }
+    for (let dir = pkgRoot;;) {
+        if (existsSync(join(dir, ".git"))) {
+            return { kind: "repo-checkout", path: pkgRoot, detail: `git checkout (.git at ${dir})` };
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return { kind: "unknown", path: pkgRoot, detail: "not a recognized bun/npm global, opencode cache, or git checkout location" };
+}
+/** What to run for the detected location — or why we refuse to guess. */
+export function planUpdate(loc) {
+    switch (loc.kind) {
+        case "bun-global":
+            return { action: "install", argv: ["bun", "i", "-g", `${PKG_NAME}@latest`], detail: loc.detail };
+        case "npm-global":
+            return { action: "install", argv: ["npm", "i", "-g", `${PKG_NAME}@latest`], detail: loc.detail };
+        case "opencode-cache":
+            return {
+                action: "refuse",
+                reason: `this copy lives in opencode's npm cache (${loc.path}); opencode manages it and refreshes it on its own schedule — ` +
+                    `update the PATH-installed CLI instead (npm i -g ${PKG_NAME}@latest)`,
+            };
+        case "repo-checkout":
+            return {
+                action: "refuse",
+                reason: `this copy is a git checkout (${loc.path}) — update it via your git workflow (e.g. git pull), not a package manager`,
+            };
+        case "unknown":
+            return {
+                action: "refuse",
+                reason: `cannot tell how this copy (${loc.path}) was installed — refusing to guess; ` +
+                    `if it is a global install, run npm i -g ${PKG_NAME}@latest (or the bun equivalent) by hand`,
+            };
+    }
+}
+/** One npm invocation, bounded; resolves null on timeout/spawn failure. */
+function npmOutput(args, timeoutMs) {
+    return new Promise((resolve) => {
+        let stdout = "";
+        let stderr = "";
+        let child;
+        try {
+            child = spawn("npm", args, { stdio: ["ignore", "pipe", "pipe"] });
+        }
+        catch {
+            resolve(null);
+            return;
+        }
+        const timer = setTimeout(() => {
+            child.kill("SIGKILL");
+            resolve(null);
+        }, timeoutMs);
+        timer.unref?.();
+        child.stdout?.on("data", (b) => (stdout += b));
+        child.stderr?.on("data", (b) => (stderr += b));
+        child.once("error", () => {
+            clearTimeout(timer);
+            resolve(null);
+        });
+        child.once("exit", (code) => {
+            clearTimeout(timer);
+            resolve({ code, stdout, stderr });
+        });
+    });
+}
+/** Latest published version from the npm registry, or null on failure. */
+async function viewLatest(timeoutMs) {
+    const r = await npmOutput(["view", PKG_NAME, "version"], timeoutMs);
+    if (!r || r.code !== 0)
+        return null;
+    // `npm view <pkg> version` prints the bare version (possibly quoted).
+    const line = r.stdout.trim().split("\n").pop() ?? "";
+    const v = line.replace(/^"|"$/g, "").trim();
+    return /^\d+(\.\d+)*(-.*)?$/.test(v) ? v : null;
+}
+/** `npm root -g` (the global node_modules dir), or null on failure. */
+async function npmGlobalRoot(timeoutMs) {
+    const r = await npmOutput(["root", "-g"], timeoutMs);
+    if (!r || r.code !== 0)
+        return null;
+    const line = r.stdout.trim().split("\n").pop() ?? "";
+    return line || null;
+}
+function fail(msg, code = 70) {
+    process.stderr.write(`load-lock: ${msg}\n`);
+    process.exit(code);
+}
+/**
+ * The `load-lock update` command. Prints a structured report (JSON with
+ * --json, prose otherwise) and returns the exit code:
+ *   0  up-to-date (check) or applied successfully
+ *   1  update available (--check; includes "cannot self-apply" refusals)
+ *   70 failure or refusal in apply mode
+ */
+export async function updateCommand(opts) {
+    const timeoutMs = 30_000;
+    const out = (v, human) => {
+        if (opts.json)
+            process.stdout.write(JSON.stringify(v, null, 2) + "\n");
+        else
+            process.stdout.write(human() + "\n");
+    };
+    const locationReport = (loc) => ({ kind: loc.kind, path: loc.path });
+    // 1. Classify self BEFORE touching anything (local only, no registry).
+    const self = thisCopy();
+    const own = packageVersion();
+    if (!self) {
+        fail(`cannot resolve this copy's package root — run \`load-lock doctor\``);
+    }
+    const root = await npmGlobalRoot(timeoutMs);
+    const loc = classifySelf(self.path, {
+        home: process.env.HOME ?? homedir(),
+        npmGlobalRoot: root,
+        cacheRoot: opencodeCacheRoot(process.platform, process.env),
+    });
+    // 2. Check the registry (npm is the only distribution channel).
+    const latest = await viewLatest(timeoutMs);
+    if (latest === null) {
+        fail(`could not determine the latest published version of ${PKG_NAME} (npm view failed — is the registry reachable?)`);
+    }
+    // 3. Up to date (or this copy is ahead of the registry — nothing to do).
+    if (compareVersions(latest, own) <= 0) {
+        const ahead = compareVersions(latest, own) < 0;
+        const report = {
+            state: "up-to-date",
+            current_version: own,
+            latest_version: latest,
+            location: locationReport(loc),
+            ...(ahead ? { note: `this copy (v${own}) is newer than the registry latest (v${latest}) — nothing to do` } : {}),
+        };
+        out(report, () => `load-lock: up to date (v${own}; registry latest v${latest}; location: ${loc.kind})` +
+            (ahead ? ` — this copy is ahead of the registry` : ""));
+        return 0;
+    }
+    // 4. An update exists: plan the apply for the classified location.
+    const plan = planUpdate(loc);
+    if (plan.action === "refuse") {
+        const report = {
+            state: "refused",
+            current_version: own,
+            latest_version: latest,
+            location: locationReport(loc),
+            reason: plan.reason,
+            next_action: "resolve the location issue, then run `load-lock update` again (see docs/OPERATIONS.md)",
+        };
+        out(report, () => `load-lock: update to v${latest} available, but refused: ${plan.reason}`);
+        if (opts.check)
+            return 1; // an update exists — this copy just cannot self-apply it
+        process.stderr.write(`load-lock: update refused — ${plan.reason}\n`);
+        return 70;
+    }
+    // 5. --check: report what WOULD happen; touch nothing.
+    if (opts.check) {
+        const report = {
+            state: "update-available",
+            current_version: own,
+            latest_version: latest,
+            location: locationReport(loc),
+            command: plan.argv,
+            next_action: "run `load-lock update` to apply it; the service restarts automatically afterwards",
+        };
+        out(report, () => `load-lock: update available: v${own} -> v${latest} (location: ${loc.kind}; would run: ${plan.argv.join(" ")})`);
+        return 1;
+    }
+    // 6. Apply: run the detected package manager (output shown live).
+    process.stdout.write(opts.json
+        ? JSON.stringify({ state: "applying", current_version: own, latest_version: latest, command: plan.argv }, null, 2) + "\n"
+        : `load-lock: updating v${own} -> v${latest} via ${plan.argv.join(" ")}\n`);
+    const code = await new Promise((resolve) => {
+        let child;
+        try {
+            child = spawn(plan.argv[0], plan.argv.slice(1), { stdio: "inherit" });
+        }
+        catch (e) {
+            fail(`cannot run ${plan.argv[0]}: ${e.message}`);
+        }
+        child.once("error", (e) => fail(`cannot run ${plan.argv[0]}: ${e.message}`));
+        child.once("exit", (c) => resolve(c));
+    });
+    if (code !== 0) {
+        fail(`update not applied: ${plan.argv.join(" ")} exited with code ${code} — the daemon keeps running the current code`);
+    }
+    // 7. Restart the service so the daemon moves onto the new code now
+    // (the version handshake remains the safety net, not the primary means).
+    try {
+        const r = await serviceRestart();
+        const report = {
+            state: "updated",
+            from: own,
+            to: latest,
+            location: locationReport(loc),
+            command: plan.argv,
+            restarted: true,
+            restart: { stop: r.stop, start: r.start },
+        };
+        out(report, () => `load-lock: updated v${own} -> v${latest}; ${r.stop}; ${r.start}`);
+        return 0;
+    }
+    catch (e) {
+        const reason = e instanceof ServiceError ? e.message : String(e?.message ?? e);
+        const report = {
+            state: "updated",
+            from: own,
+            to: latest,
+            location: locationReport(loc),
+            command: plan.argv,
+            restarted: false,
+            restart_error: reason,
+            next_action: "the update IS applied; the daemon still runs old code — the version handshake will self-restart it on the " +
+                "next client contact, or run `load-lock service restart` manually (see docs/OPERATIONS.md)",
+        };
+        out(report, () => `load-lock: updated v${own} -> v${latest}, but the service restart failed: ${reason}`);
+        process.stderr.write(`load-lock: ${reason}\n`);
+        return 70;
+    }
+}

package/dist/core/daemon.d.ts

@@ -27,6 +27,8 @@ export declare class Daemon {
      *  restart via the event cursor) and the process can exit promptly. */
     private conns;
     private waiters;
+    /** wait_for_completion calls blocked on tracked jobs; multiple waiters per job are fine. */
+    private completionWaiters;
     private sentEventId;
     private stateDirPath;
     private socketPath;
@@ -77,6 +79,28 @@ export declare class Daemon {
      * push notifications — no model-authored busy-polling required.
      */
     private waitForAdmission;
+    /**
+     * Bounded blocking wait for a daemon-tracked job's completion. Mirrors
+     * waitForAdmission: the call is held server-side and woken by
+     * resolveCompletionWaiters() when the job is observed done — which always
+     * happens AFTER the permit has been released (finish() frees capacity
+     * before the event is emitted, and waiters are resolved after that).
+     * timeoutMs 0 is check-only. Never blocks unbounded.
+     */
+    private waitForJobCompletion;
+    /**
+     * Classify a request whose entry is no longer held (released, reclaimed,
+     * cancelled, or never started) into a structured completion result, using
+     * the most recent event for the request.
+     */
+    private classifyEntryCompletion;
+    /**
+     * Wake blocked wait_for_completion calls whose tracked job has ended.
+     * Called after every machine transition (afterOp, sweep, expiry timer) —
+     * always AFTER finish() has freed capacity and after the event flush, so
+     * a woken agent observes the pool as free. Entries still held are skipped.
+     */
+    private resolveCompletionWaiters;
     /** Runs after every dispatch: sweep deadlines, auto-claim for waiters, flush events, journal. */
     private afterOp;
     private armExpiryTimer;