zcode-acp-server 0.1.0

package/dist/backend/client.js

@@ -0,0 +1,344 @@
+/**
+ * ZCode subprocess client: spawn, read-loop multiplexer, async request/response.
+ *
+ * The ZCode app-server is launched as a subprocess (`zcode app-server --stdio`)
+ * speaking line-delimited JSON over stdio. A single async read loop demultiplexes
+ * inbound messages into three channels:
+ *   - responses (id, no method) → resolve the matching pending request promise
+ *   - server→client requests (id + method, id not pending) → server-request queue
+ *   - notifications (no id):
+ *       - `session/event` → routed to the registered session listener
+ *       - anything else   → general notification queue
+ *
+ * Process-group isolation: the subprocess is its own process-group leader
+ * (`detached: true`) so `close()` can kill the whole tree (zcode + its model
+ * workers) with `process.kill(-pid)` and leave no orphans.
+ */
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import process from "node:process";
+import { log, warn } from "../utils.js";
+export class ZcodeBackend {
+    proc;
+    pending = new Map();
+    serverRequests = [];
+    listeners = new Map();
+    readerDead = false;
+    /** Monotonic id for fire-and-forget sends (send()). Uses a high range to
+     *  avoid collisions with the server's request ids (low range). */
+    sendIdCounter = 1_000_000_000;
+    /** Watchdog process that kills the zcode group if this bridge dies (SIGKILL). */
+    watchdog = null;
+    constructor(argv, env) {
+        this.proc = spawn(argv[0], argv.slice(1), {
+            stdio: ["pipe", "pipe", "ignore"],
+            env,
+            detached: true, // own process group → kill(-pid) reaps the whole tree
+        });
+        // Node stream write errors (EPIPE on a closed stdin) are emitted as async
+        // 'error' events, NOT thrown synchronously — without a listener the process
+        // crashes with an unhandled 'error' event. Catch them here and mark the
+        // reader dead so the rest of the bridge stops talking to a gone backend.
+        this.proc.stdin?.on("error", (err) => {
+            this.readerDead = true;
+            warn(`backend: stdin error: ${err.message}`);
+        });
+        this.startReader();
+        this.startWatchdog();
+        log(`backend: started zcode app-server (pid=${this.proc.pid})`);
+    }
+    /**
+     * Spawn a tiny detached watchdog that kills the zcode process group if this
+     * bridge process disappears.
+     *
+     * The detached/kill(-pid) cleanup in `close()` only runs when the bridge
+     * exits cleanly enough for the signal handlers to fire (SIGTERM/SIGINT/etc).
+     * If the bridge is SIGKILLed (Zed force-kill on reconnect, crash, OOM), the
+     * handler never runs and the zcode subprocess group is orphaned. The
+     * watchdog closes that gap: it polls the bridge pid every 2s and, once the
+     * bridge is gone, sends SIGKILL to the zcode process group, then exits.
+     *
+     * The watchdog is its own process-group leader (detached) and `unref`'d, so
+     * it never holds the event loop open and is not part of the zcode group it
+     * kills. It self-terminates as soon as the zcode process exits, so a normal
+     * shutdown leaves no lingering watchdog.
+     */
+    startWatchdog() {
+        const bridgePid = process.pid;
+        const zcodePid = this.proc.pid;
+        if (!bridgePid || !zcodePid)
+            return;
+        // Inline script: poll bridge liveness, kill zcode group on bridge death.
+        const script = `
+      const bridgePid = ${bridgePid};
+      const zcodePid = ${zcodePid};
+      const tick = () => {
+        // Bridge gone? → reap the whole zcode process group, then exit.
+        try { process.kill(bridgePid, 0); }
+        catch {
+          try { process.kill(-zcodePid, 'SIGKILL'); } catch {}
+          process.exit(0);
+        }
+        // zcode already exited? → watchdog has no job left.
+        try { process.kill(-zcodePid, 0); }
+        catch { process.exit(0); }
+      };
+      setInterval(tick, 2000);
+      tick();
+    `;
+        this.watchdog = spawn(process.execPath, ["-e", script], {
+            stdio: "ignore",
+            detached: true, // own process group, not part of the zcode group
+        });
+        this.watchdog.unref();
+    }
+    // ---------- read loop ----------
+    startReader() {
+        const stdout = this.proc.stdout;
+        if (!stdout) {
+            this.markReaderDead("no stdout");
+            return;
+        }
+        const rl = createInterface({ input: stdout });
+        rl.on("line", (line) => {
+            const trimmed = line.trim();
+            if (!trimmed)
+                return;
+            let msg;
+            try {
+                msg = JSON.parse(trimmed);
+            }
+            catch {
+                return; // unparseable line: ignore
+            }
+            this.route(msg);
+        });
+        rl.on("close", () => this.markReaderDead("stdout closed"));
+    }
+    route(msg) {
+        const method = msg.method;
+        const id = msg.id;
+        if (id !== undefined && method === undefined) {
+            // Response (id, no method) → resolve pending request.
+            this.resolvePending(id, msg);
+            return;
+        }
+        if (id !== undefined && method !== undefined) {
+            // id + method: our pending response wins the race; else it's a server→client request.
+            if (this.pending.has(id)) {
+                this.resolvePending(id, msg);
+            }
+            else {
+                this.serverRequests.push({
+                    id,
+                    method,
+                    params: (msg.params ?? {}),
+                });
+            }
+            return;
+        }
+        if (method !== undefined) {
+            // Notification.
+            if (method === "session/event") {
+                const ev = (msg.params ?? {});
+                const sid = ev.sessionId;
+                const listener = sid ? this.listeners.get(sid) : undefined;
+                listener?.handleEvent(ev);
+            }
+            // Other notifications are currently ignored (state.updated, etc.).
+        }
+    }
+    resolvePending(id, resp) {
+        const p = this.pending.get(id);
+        if (!p)
+            return;
+        clearTimeout(p.timer);
+        this.pending.delete(id);
+        p.resolve(resp);
+    }
+    markReaderDead(reason) {
+        if (this.readerDead)
+            return;
+        this.readerDead = true;
+        warn(`backend: reader exited (${reason})`);
+        for (const [, p] of this.pending) {
+            clearTimeout(p.timer);
+            p.resolve({
+                id: 0,
+                error: { message: "zcode backend reader exited (backend dead)" },
+            });
+        }
+        this.pending.clear();
+    }
+    // ---------- listeners / server requests ----------
+    registerEventListener(zcodeSid, listener) {
+        this.listeners.set(zcodeSid, listener);
+    }
+    unregisterEventListener(zcodeSid) {
+        this.listeners.delete(zcodeSid);
+    }
+    /** Non-blocking drain of pending server→client requests. */
+    pollServerRequests() {
+        if (this.serverRequests.length === 0)
+            return [];
+        return this.serverRequests.splice(0, this.serverRequests.length);
+    }
+    /** Reply to a zcode server→client request with a result (id + result). */
+    sendReply(id, result) {
+        const stdin = this.proc.stdin;
+        if (!stdin || stdin.destroyed) {
+            warn("backend: sendReply dropped (stdin closed)");
+            return;
+        }
+        // Write errors (EPIPE) are delivered via the stdin 'error' listener
+        // installed in the constructor (synchronous try/catch cannot catch them);
+        // no try/catch needed here.
+        stdin.write(JSON.stringify({ id, result }) + "\n");
+    }
+    /** Reply to a zcode server→client request with an error. */
+    sendError(id, code, message) {
+        const stdin = this.proc.stdin;
+        if (!stdin || stdin.destroyed) {
+            warn("backend: sendError dropped (stdin closed)");
+            return;
+        }
+        stdin.write(JSON.stringify({ id, error: { code, message } }) + "\n");
+    }
+    // ---------- send / request ----------
+    /** Fire-and-forget notification to ZCode (no id, no response). */
+    notify(method, params) {
+        const stdin = this.proc.stdin;
+        if (!stdin || stdin.destroyed) {
+            warn("backend: notify dropped (stdin closed)");
+            return;
+        }
+        stdin.write(JSON.stringify({ method, params }) + "\n");
+    }
+    /**
+     * Send a message with an id but WITHOUT registering a pending response
+     * (fire-and-forget). Mirrors Python's `_backend.send({"id": ..., ...})` for
+     * `session/stop`: some backends route by id presence, so carrying an id is
+     * more robust than a bare notify. If the backend replies, the reader's
+     * `resolvePending` finds no pending entry and safely discards it.
+     */
+    send(method, params) {
+        const stdin = this.proc.stdin;
+        if (!stdin || stdin.destroyed) {
+            warn("backend: send dropped (stdin closed)");
+            return;
+        }
+        const id = this.sendIdCounter++;
+        stdin.write(JSON.stringify({ id, method, params: params ?? {} }) + "\n");
+    }
+    /**
+     * Synchronous request/response: register a pending promise, send, await.
+     * Other notifications arriving during the wait are routed async by the
+     * reader loop (they don't get swallowed).
+     *
+     * Returns `{error}` on dead backend, broken pipe, or timeout — never throws.
+     */
+    async request(id, method, params, timeoutMs = 30000) {
+        if (this.readerDead) {
+            return { id, error: { message: "zcode backend reader exited (backend dead)" } };
+        }
+        const promise = new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                if (this.pending.delete(id)) {
+                    resolve({ id, error: { message: "timeout" } });
+                }
+            }, timeoutMs);
+            this.pending.set(id, { resolve, timer });
+        });
+        try {
+            const stdin = this.proc.stdin;
+            if (!stdin || stdin.destroyed)
+                throw new Error("stdin closed");
+            stdin.write(JSON.stringify({ id, method, params: params ?? {} }) + "\n");
+        }
+        catch (e) {
+            this.pending.delete(id);
+            this.readerDead = true;
+            return {
+                id,
+                error: {
+                    message: `zcode backend pipe broken: ${e instanceof Error ? e.message : String(e)}`,
+                },
+            };
+        }
+        return promise;
+    }
+    // ---------- lifecycle ----------
+    /**
+     * Kill the whole zcode process group and wait for it to die.
+     *
+     * SIGTERM → wait up to 3s → SIGKILL if still alive. Mirrors the Python
+     * `os.killpg` + `proc.wait(3)` + SIGKILL escalation. Note `proc.killed` is
+     * NOT set by `process.kill(-pid)` (group signal), so we track liveness via
+     * `exitCode === null` instead. Async so the caller can `await` a full reap
+     * before the parent exits (an unref'd timer could be skipped on fast exit,
+     * leaving orphans).
+     */
+    async close() {
+        const proc = this.proc;
+        if (!proc.pid)
+            return;
+        try {
+            // Already exited?
+            if (proc.exitCode !== null || proc.signalCode)
+                return;
+            try {
+                process.kill(-proc.pid, "SIGTERM");
+            }
+            catch {
+                return; // group already gone
+            }
+            // Wait up to 3s for a clean exit.
+            const exited = await new Promise((resolve) => {
+                let timer;
+                const done = () => {
+                    clearTimeout(timer); // don't let the timeout keep the event loop alive
+                    resolve(true);
+                };
+                proc.once("exit", done);
+                timer = setTimeout(() => {
+                    proc.removeListener("exit", done);
+                    resolve(false);
+                }, 3000);
+            });
+            if (exited)
+                return;
+            // Still alive → SIGKILL the whole group.
+            try {
+                if (proc.pid && proc.exitCode === null)
+                    process.kill(-proc.pid, "SIGKILL");
+            }
+            catch {
+                // already gone
+            }
+        }
+        finally {
+            // Stop the watchdog — it would self-exit on its next tick once the zcode
+            // group is gone, but killing it here avoids the up-to-2s delay.
+            this.killWatchdog();
+        }
+    }
+    /** Terminate the watchdog process if it is still running. */
+    killWatchdog() {
+        const wd = this.watchdog;
+        if (!wd)
+            return;
+        this.watchdog = null;
+        if (wd.pid && wd.exitCode === null) {
+            try {
+                process.kill(wd.pid, "SIGTERM");
+            }
+            catch {
+                // already gone
+            }
+        }
+    }
+    get isDead() {
+        return this.readerDead;
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/backend/client.js.map

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

package/dist/backend/credentials.d.ts

@@ -0,0 +1,31 @@
+/**
+ * ZCode credential and environment handling.
+ *
+ * Vendored from the reference Python implementation so this package stays
+ * self-contained. The ZCode desktop app stores provider credentials in
+ * `~/.zcode/v2/config.json`; GUI-launched processes don't inherit shell env
+ * vars, so we read the config and inject the active provider's settings into
+ * the subprocess environment.
+ */
+/** Credentials extracted from the active provider. */
+export interface ZcodeCredentials {
+    ZCODE_MODEL?: string;
+    ZCODE_BASE_URL?: string;
+    ANTHROPIC_API_KEY?: string;
+}
+/** Read the active provider's credentials from config.json. Best-effort. */
+export declare function loadZcodeCredentials(): ZcodeCredentials;
+/**
+ * Merge process.env with config credentials.
+ *
+ * Explicit non-empty env vars override config (so `ZCODE_MODEL=foo` works as a
+ * temporary override). Empty-string env vars are treated as unset so they
+ * don't clobber the config value.
+ *
+ * Also self-heals a stale `ZCODE_BASE_URL`: if the env value is the endpoint
+ * of a *different* provider in config (a leftover from switching plans in the
+ * App), revert to the enabled provider's URL. User-defined custom endpoints
+ * are respected.
+ */
+export declare function mergeEnvWithCreds(creds: ZcodeCredentials): NodeJS.ProcessEnv;
+//# sourceMappingURL=credentials.d.ts.map

package/dist/backend/credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../../src/backend/credentials.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAkBH,sDAAsD;AACtD,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,4EAA4E;AAC5E,wBAAgB,oBAAoB,IAAI,gBAAgB,CAoBvD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAAC,UAAU,CAuB5E"}

package/dist/backend/credentials.js

@@ -0,0 +1,93 @@
+/**
+ * ZCode credential and environment handling.
+ *
+ * Vendored from the reference Python implementation so this package stays
+ * self-contained. The ZCode desktop app stores provider credentials in
+ * `~/.zcode/v2/config.json`; GUI-launched processes don't inherit shell env
+ * vars, so we read the config and inject the active provider's settings into
+ * the subprocess environment.
+ */
+import { readFileSync } from "node:fs";
+import process from "node:process";
+import { log, ZCODE_CREDS_PATH } from "../utils.js";
+/** Read the active provider's credentials from config.json. Best-effort. */
+export function loadZcodeCredentials() {
+    try {
+        const cfg = JSON.parse(readFileSync(ZCODE_CREDS_PATH, "utf8"));
+        for (const [, p] of Object.entries(cfg.provider ?? {})) {
+            if (p?.enabled) {
+                const opts = p.options ?? {};
+                const models = p.models ?? {};
+                return {
+                    ZCODE_MODEL: Object.keys(models)[0] ?? "GLM-5.2",
+                    ZCODE_BASE_URL: opts.baseURL ?? "",
+                    ANTHROPIC_API_KEY: opts.apiKey ?? "",
+                };
+            }
+        }
+    }
+    catch (e) {
+        log(`credentials: failed to read ${ZCODE_CREDS_PATH}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    return {};
+}
+/**
+ * Merge process.env with config credentials.
+ *
+ * Explicit non-empty env vars override config (so `ZCODE_MODEL=foo` works as a
+ * temporary override). Empty-string env vars are treated as unset so they
+ * don't clobber the config value.
+ *
+ * Also self-heals a stale `ZCODE_BASE_URL`: if the env value is the endpoint
+ * of a *different* provider in config (a leftover from switching plans in the
+ * App), revert to the enabled provider's URL. User-defined custom endpoints
+ * are respected.
+ */
+export function mergeEnvWithCreds(creds) {
+    const merged = { ...process.env, ...creds };
+    for (const k of ["ZCODE_MODEL", "ZCODE_BASE_URL", "ANTHROPIC_API_KEY"]) {
+        const v = process.env[k];
+        if (v)
+            merged[k] = v;
+    }
+    // Stale-baseURL self-heal.
+    const envBu = process.env.ZCODE_BASE_URL ?? "";
+    const configBu = creds.ZCODE_BASE_URL ?? "";
+    if (envBu && configBu && envBu !== configBu) {
+        const allHosts = collectProviderHosts();
+        const envHost = hostOf(envBu);
+        const configHost = hostOf(configBu);
+        if (envHost && configHost && envHost !== configHost && allHosts.has(envHost)) {
+            merged.ZCODE_BASE_URL = configBu;
+            log(`credentials: ZCODE_BASE_URL stale-host detected (env='${envBu}' is another ` +
+                `provider's endpoint); reverted to config='${configBu}'.`);
+        }
+    }
+    return merged;
+}
+function collectProviderHosts() {
+    const hosts = new Set();
+    try {
+        const cfg = JSON.parse(readFileSync(ZCODE_CREDS_PATH, "utf8"));
+        for (const p of Object.values(cfg.provider ?? {})) {
+            const bu = p?.options?.baseURL ?? "";
+            const h = hostOf(bu);
+            if (h)
+                hosts.add(h);
+        }
+    }
+    catch {
+        // ignore — stale detection just degrades gracefully
+    }
+    return hosts;
+}
+function hostOf(url) {
+    try {
+        const u = new URL(url);
+        return `${u.protocol}//${u.host}`;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=credentials.js.map

package/dist/backend/credentials.js.map

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

package/dist/backend/index.d.ts

@@ -0,0 +1,7 @@
+/** Backend layer barrel: ZCode subprocess client + listener + resolve + credentials. */
+export { ZcodeBackend, type ServerRequest, type EventListener } from "./client.js";
+export { EventStreamListener, TurnMonitor, type NextId } from "./listener.js";
+export { resolveZcodeCommand } from "./resolve.js";
+export { loadZcodeCredentials, mergeEnvWithCreds, type ZcodeCredentials } from "./credentials.js";
+export type { ZcodeRequest, ZcodeNotification, ZcodeResponse, ZcodeInbound, ZcodeSessionInfo, ZcodeCreateResult, ZcodeSessionListItem, ZcodeListResult, ZcodeEvent, ZcodeEventType, ZcodeSubscribeResult, ZcodeSnapshot, ZcodeProjection, ZcodeMessage, ZcodeMessagePart, ZcodeMessagesResult, ZcodeReadResult, ZcodeInteractionPermissionParams, ZcodeInteractionUserInputParams, ZcodeInteractionResponse, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/backend/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/backend/index.ts"],"names":[],"mappings":"AAAA,wFAAwF;AAExF,OAAO,EAAE,YAAY,EAAE,KAAK,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACnF,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,KAAK,MAAM,EAAE,MAAM,eAAe,CAAC;AAC9E,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAClG,YAAY,EACV,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,EACpB,eAAe,EACf,UAAU,EACV,cAAc,EACd,oBAAoB,EACpB,aAAa,EACb,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,mBAAmB,EACnB,eAAe,EACf,gCAAgC,EAChC,+BAA+B,EAC/B,wBAAwB,GACzB,MAAM,YAAY,CAAC"}

package/dist/backend/index.js

@@ -0,0 +1,6 @@
+/** Backend layer barrel: ZCode subprocess client + listener + resolve + credentials. */
+export { ZcodeBackend } from "./client.js";
+export { EventStreamListener, TurnMonitor } from "./listener.js";
+export { resolveZcodeCommand } from "./resolve.js";
+export { loadZcodeCredentials, mergeEnvWithCreds } from "./credentials.js";
+//# sourceMappingURL=index.js.map

package/dist/backend/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/backend/index.ts"],"names":[],"mappings":"AAAA,wFAAwF;AAExF,OAAO,EAAE,YAAY,EAA0C,MAAM,aAAa,CAAC;AACnF,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAe,MAAM,eAAe,CAAC;AAC9E,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAyB,MAAM,kBAAkB,CAAC"}

package/dist/backend/listener.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Event-stream listener and turn monitor.
+ *
+ * `EventStreamListener` subscribes to ZCode's `session/subscribe` event push
+ * (deliveryKind `desktop-continuous`) and queues `session/event` notifications
+ * for the turn loop to consume. It tracks a `lastSeq` watermark and can
+ * resubscribe from it to recover missed events after a stall.
+ *
+ * `TurnMonitor` is the legacy snapshot path: a one-shot `session/read` that
+ * returns the authoritative projection. Used for stall reconciliation and
+ * lock-release probing.
+ */
+import type { ZcodeBackend } from "./client.js";
+import type { ZcodeEvent, ZcodeProjection, ZcodeSnapshot } from "./types.js";
+/** ID generator function (the server's `_next_id`). */
+export type NextId = () => number;
+export declare class EventStreamListener {
+    private readonly backend;
+    readonly sid: string;
+    /** High-watermark of consumed event sequence numbers. */
+    lastSeq: number;
+    subscribed: boolean;
+    private readonly queue;
+    private readonly waiters;
+    constructor(backend: ZcodeBackend, zcodeSid: string);
+    /**
+     * Subscribe and capture the initial snapshot + eventSeq watermark.
+     *
+     * Returns the snapshot (with projection/messages) or null on failure. ZCode
+     * CLI 0.14.8+ always supports this; null means an old/ broken backend and
+     * the caller should surface an error (polling fallback was removed).
+     */
+    subscribe(nextId: NextId): Promise<ZcodeSnapshot | null>;
+    /** Called by the backend reader when a `session/event` arrives. */
+    handleEvent(event: ZcodeEvent): void;
+    /**
+     * Wait for the next event, resolving once one arrives or `timeoutMs` elapses
+     * (resolves null on timeout). Events arriving with no active waiter are
+     * queued. A timed-out waiter is marked `done` so a later event skips it
+     * instead of being silently dropped on a settled promise.
+     */
+    pollEvent(timeoutMs?: number): Promise<ZcodeEvent | null>;
+    /**
+     * Stall recovery: resubscribe from `lastSeq` so the server replays missed
+     * events. Failure is logged but non-fatal — the caller degrades to polling.
+     * The snapshot (if returned despite `includeSnapshot:false`) is intentionally
+     * not consumed; resubscribe only refreshes the watermark + resumes the push.
+     */
+    resubscribe(nextId: NextId): Promise<boolean>;
+}
+/**
+ * Legacy snapshot path: a single `session/read` returning the authoritative
+ * projection. Used in stall reconciliation and lock-release probing.
+ */
+export declare class TurnMonitor {
+    private readonly backend;
+    private readonly zcodeSid;
+    private readonly nextId;
+    constructor(backend: ZcodeBackend, zcodeSid: string, nextId: NextId);
+    /** Returns the projection snapshot, or null on error. */
+    pollOnce(): Promise<ZcodeProjection | null>;
+}
+//# sourceMappingURL=listener.d.ts.map

package/dist/backend/listener.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listener.d.ts","sourceRoot":"","sources":["../../src/backend/listener.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,aAAa,EAAwB,MAAM,YAAY,CAAC;AAEnG,uDAAuD;AACvD,MAAM,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC;AAUlC,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,OAAO,SAAK;IACZ,UAAU,UAAS;IACnB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;gBAE5B,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM;IAKnD;;;;;;OAMG;IACG,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAqB9D,mEAAmE;IACnE,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAepC;;;;;OAKG;IACH,SAAS,CAAC,SAAS,SAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAoBtD;;;;;OAKG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAqBpD;AAED;;;GAGG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAMnE,yDAAyD;IACnD,QAAQ,IAAI,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;CAWlD"}