mtech-ai-local-runner 0.1.48 → 0.1.49

package/README.md

@@ -1,4 +1,37 @@
-## Unreleased: AI-first ask delivery and messenger mode (disabled)
+## 0.1.49: one push transport instead of two long-polls
+
+The daemon no longer long-polls the Gateway (Work Item 25d8ea74). It keeps one Pusher protocol 7 WebSocket to the
+ELSA development Reverb server, which only rings, and calls `local_agent_runner_sync` once, with no wait: on start,
+after each subscribe, on each signal, every 30 s while subscribed, and every 8 s while the socket is down or the
+Gateway gives no push block. A job is claimed with `local_agent_jobs_wait` at `wait_seconds` 0, and only when the
+sync says one is claimable. Session opens, ask deliveries and closures arrive on the sync result, and a closure is
+acknowledged on the next sync. The full heartbeat goes out on a change or every 10 minutes. While the daemon takes no
+jobs (reconciling at start, or suspended for recovery), it reports every adapter blocked with
+`RUNNER_NOT_ACCEPTING_JOBS`, so the Gateway routes no job to it.
+
+The socket sends `User-Agent: mtec-ai-local-runner/<version>`; the server's firewall refuses an upgrade without one.
+The runner needs a Gateway with `local_agent_runner_sync` and `local_agent_runner_channel_auth`, so deploy the
+Gateway before upgrading a runner. Push stays off until the Gateway's push switch names the employee; until then the
+runner syncs every 8 s.
+
+## 0.1.48: local_edit takes the complete file, not a patch
+
+Read the existing file first, then pass its complete desired new contents in
+`local_edit.content`, including unchanged text. The operation replaces the whole
+file or creates it; it never applies a diff. Recognizable apply_patch directives,
+unified hunk lines and diff headers return `DENIED_PATCH_CONTENT` before a write.
+The isolated writer enforces the same guard. Literal patch blocks in a document
+are also rejected by this conservative API; ordinary source string literals and
+YAML separators remain accepted. No partial old/new edit tool is introduced.
+
+Gateway and Runner must agree on the new tool inventory hash. Package runtime
+receipts change, while the reviewed Codex CLI release manifest identity stays
+unchanged. Keep existing -2G allowed paths; deploy the matching Gateway registry
+and exact runtime pins before switching a daemon. The candidate contains the
+newer development ask/messenger code documented below and
+the 0.1.46/0.1.47 fixes; no integration is installed merely by preparing it.
+
+### Also in 0.1.48: AI-first ask delivery and messenger mode (disabled)
 
 The runner can put an AI Gateway ask (a Work Decision, a named review or a work request), and the answer to it,
 into the employee's own running Claude Code or Codex session before any Slack message is sent (Work Item e1c08b33,
@@ -70,23 +103,6 @@ its pilot list. Until then an existing runner works as before: setup never turns
 installs no integration it was not asked for. The one change without the switch is that setup on a fresh Mac without an
 admitted executor completes as a messenger instead of failing. Deploy the Gateway receivers before upgrading a runner.
 
-## 0.1.48: local_edit takes the complete file, not a patch
-
-Read the existing file first, then pass its complete desired new contents in
-`local_edit.content`, including unchanged text. The operation replaces the whole
-file or creates it; it never applies a diff. Recognizable apply_patch directives,
-unified hunk lines and diff headers return `DENIED_PATCH_CONTENT` before a write.
-The isolated writer enforces the same guard. Literal patch blocks in a document
-are also rejected by this conservative API; ordinary source string literals and
-YAML separators remain accepted. No partial old/new edit tool is introduced.
-
-Gateway and Runner must agree on the new tool inventory hash. Package runtime
-receipts change, while the reviewed Codex CLI release manifest identity stays
-unchanged. Keep existing -2G allowed paths; deploy the matching Gateway registry
-and exact runtime pins before switching a daemon. The candidate contains the
-newer development ask/messenger code documented in the Unreleased section and
-the 0.1.46/0.1.47 fixes; no integration is installed merely by preparing it.
-
 ## 0.1.47: Claude security host wiring remains gated
 
 Claude now shares the job security session and checks a live opaque executable

package/dist/src/asks/messenger.js

@@ -5,16 +5,22 @@ import { Daemon } from "../daemon/daemon.js";
 import { ProcessLock } from "../daemon/process-lock.js";
 import { runnerDisplayName } from "../daemon/runtime.js";
 import { SessionOpener, sessionOpenAdvertisement } from "../daemon/session-opener.js";
-import { SessionOpenPoller, abortableDelay } from "../daemon/session-open-poller.js";
+import { RunnerTransport } from "../transport/runner-transport.js";
+import { ReverbSocket } from "../transport/reverb-socket.js";
+import { PendingClosureAcks, createSyncDispatcher } from "../transport/sync-dispatch.js";
+import { abortableDelay } from "../transport/abortable-delay.js";
+import { sideLoops, tickingHeartbeat } from "../transport/side-loops.js";
 import { packageVersion } from "../package-version.js";
 import { AskRuntime, withAsks } from "./runtime.js";
 /*
  * Messenger mode (Work Item e1c08b33, spec section 8.1). Setup chose it because no executor is admitted on
- * this Mac. The daemon runs the session-open loop only: there is no jobs loop, no adapter probe, no PreToolUse
- * self-test and no executor host, so nothing built here can start an executor.
+ * this Mac. The daemon runs the push transport only (Work Item 25d8ea74): there is no jobs loop, no adapter probe,
+ * no PreToolUse self-test and no executor host, so nothing built here can start an executor.
  */
-/** A messenger has no jobs loop, so its session-open loop sends the heartbeat: at daemon start, then every 600 s. */
+/** A messenger has no jobs loop, so it sends the heartbeat itself: at daemon start, then every 600 s. */
 export const MESSENGER_HEARTBEAT_MS = 600_000;
+/** How often the heartbeat decides whether a beat is due (Work Item 25d8ea74); it used to run on every wait. */
+export const MESSENGER_HEARTBEAT_TICK_MS = 30_000;
 const HEARTBEAT_RETRY_MS = 60_000;
 /**
  * The waits before resending a heartbeat that had to leave session_open out, one after another: 60, 120, 240 s, then the
@@ -108,21 +114,42 @@ export async function buildMessengerDaemon(input) {
     }, { now: input.now, reportError: code => log({ event: "messenger_heartbeat_failed", code }),
         advertised: async () => JSON.stringify(await asks.advertisement() ?? null) });
     const opener = new SessionOpener({ home });
-    const sessionOpens = new SessionOpenPoller({
-        wait: async (signal) => {
-            await heartbeat(signal);
-            const result = await gateway.waitForSessionOpens(25, signal);
-            await asks.handleWait(result);
-            return result;
-        },
+    const stopping = new AbortController();
+    const closureAcks = new PendingClosureAcks();
+    const dispatch = createSyncDispatcher({
         open: request => opener.open(request),
         report: async (openId, result, signal) => {
             await gateway.reportSessionOpen({ openId, status: result.status, surface: result.surface,
                 failureCode: result.status === "failed" ? result.failureCode : undefined }, signal);
         },
+        asks,
+        closureAcks,
         delay: abortableDelay,
+        signal: stopping.signal,
         reportError: diagnostic => log({ event: "session_open_poller_failed", ...diagnostic }),
     });
+    // No executor: the messenger sends no adapter versions, and the Gateway never says a job is claimable.
+    const transport = new RunnerTransport({
+        sync: async (reason, signal) => {
+            const acknowledged = closureAcks.take();
+            try {
+                return await gateway.syncRunner({ adapterVersions: {}, reason, acknowledgedClosureIds: acknowledged }, signal);
+            }
+            catch (error) {
+                closureAcks.restore(acknowledged);
+                throw error;
+            }
+        },
+        authorize: (socketId, signal) => gateway.authorizeRunnerChannel(socketId, signal),
+        dispatch,
+        openSocket: (target, events) => new ReverbSocket(target, events, { packageVersion: packageVersion() }),
+        report: log,
+    });
+    const sessionOpens = sideLoops({
+        heartbeat: tickingHeartbeat(heartbeat, input.heartbeatTickMs ?? MESSENGER_HEARTBEAT_TICK_MS, stopping.signal),
+        transport,
+        onStop: () => stopping.abort(),
+    });
     const daemon = new Daemon({
         lock: new ProcessLock(join(input.stateRoot, "daemon.lock")),
         // Job state belongs to a full runner: a messenger never reads, reconciles or suspends on it.

package/dist/src/asks/runtime.js

@@ -102,17 +102,24 @@ export class AskRuntime {
      * the runner's person is a pilot actor and it has stored this runner's ask_inbox. A result without ask_deliveries
      * therefore means asks are off, and every stored delivery ends here with no report: the Gateway's fallback owns them.
      * A result with the key present but empty changes nothing.
+     *
+     * Resolves false when the result's closures could not be handled (the hub is down, or closing failed), so the push
+     * transport does not acknowledge them and the Gateway lists them again (Work Item 25d8ea74).
      */
     async handleWait(result) {
         if (!this.started)
-            return;
+            return false;
+        let closuresHandled = true;
         try {
             if (result.askDeliveries === undefined) {
                 await this.inbox.endAll();
-                return;
+                return true;
             }
-            if (result.closedDeliveryIds !== undefined && result.closedDeliveryIds.length > 0)
+            if (result.closedDeliveryIds !== undefined && result.closedDeliveryIds.length > 0) {
+                closuresHandled = false;
                 await this.inbox.close(result.closedDeliveryIds);
+                closuresHandled = true;
+            }
             if (result.askDeliveries.length > 0)
                 await this.inbox.receive(result.askDeliveries);
         }
@@ -120,6 +127,7 @@ export class AskRuntime {
             this.log({ event: "ask_delivery_failed", code: errorCode(error) });
         }
         this.flushSoon();
+        return closuresHandled;
     }
     /**
      * heartbeat runner.session_open.ask_inbox, or undefined when the hub is down or nothing is installed. While a start is

package/dist/src/daemon/heartbeat-scheduler.js

@@ -0,0 +1,63 @@
+export class HeartbeatScheduler {
+    deps;
+    lastKey;
+    lastSentAt = Number.NEGATIVE_INFINITY;
+    timer;
+    stopped = false;
+    chain = Promise.resolve();
+    release;
+    done = new Promise(resolve => { this.release = resolve; });
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** One heartbeat check now, after any check in progress; never throws. */
+    tick() {
+        this.chain = this.chain.then(() => this.check());
+        return this.chain;
+    }
+    async check() {
+        let snapshot;
+        try {
+            snapshot = await this.deps.snapshot();
+        }
+        catch {
+            this.report("HEARTBEAT_SNAPSHOT_FAILED");
+            return;
+        }
+        const key = JSON.stringify(snapshot);
+        const now = (this.deps.now ?? Date.now)();
+        if (key === this.lastKey && now - this.lastSentAt < (this.deps.maxAgeMs ?? 600_000))
+            return;
+        try {
+            await this.deps.send(snapshot);
+            this.lastKey = key;
+            this.lastSentAt = now;
+        }
+        catch {
+            this.report("HEARTBEAT_SEND_FAILED");
+        }
+    }
+    /** Keeps ticking until stop(). The first tick comes one interval in: the caller sends the first heartbeat itself. */
+    async run() {
+        const loop = () => {
+            if (this.stopped)
+                return;
+            this.timer = setTimeout(() => { void this.tick().then(loop); }, this.deps.intervalMs ?? 60_000);
+        };
+        loop();
+        await this.done;
+    }
+    stop() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        clearTimeout(this.timer);
+        this.release();
+    }
+    report(code) {
+        try {
+            this.deps.reportError?.(code);
+        }
+        catch { /* Logging cannot stop heartbeats. */ }
+    }
+}

package/dist/src/daemon/job-runner.js

@@ -0,0 +1,99 @@
+export class JobRunner {
+    deps;
+    armed = false;
+    busy = false;
+    pending = false;
+    stopped = false;
+    inFlight;
+    release;
+    done = new Promise(resolve => { this.release = resolve; });
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** True while a claim or a job is in progress. */
+    get running() {
+        return this.busy;
+    }
+    /**
+     * True while this runner may claim: after run() started and before stop(). A runner that does not accept jobs
+     * (still reconciling, or suspended after an unknown outcome) must not look ready to the Gateway.
+     */
+    get accepting() {
+        return this.armed && !this.stopped;
+    }
+    notify() {
+        if (this.stopped)
+            return;
+        if (!this.armed || this.busy) {
+            this.pending = true;
+            return;
+        }
+        this.start();
+    }
+    async run() {
+        // A pending promise alone does not keep Node alive; this referenced timer does until stop().
+        const keepAlive = setInterval(() => undefined, 60_000);
+        try {
+            this.armed = true;
+            if (!this.stopped) {
+                try {
+                    this.deps.onArmed?.();
+                }
+                catch { /* Telling the Gateway is best effort; claims still start. */ }
+            }
+            if (this.pending && !this.stopped) {
+                this.pending = false;
+                this.start();
+            }
+            await this.done;
+            // Like the old poll loop, run() ends only after the claim or job in progress has finished.
+            await this.inFlight;
+        }
+        finally {
+            clearInterval(keepAlive);
+        }
+    }
+    stop() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        this.release();
+    }
+    start() {
+        const cycle = this.cycle();
+        this.inFlight = cycle;
+        void cycle.finally(() => { if (this.inFlight === cycle)
+            this.inFlight = undefined; });
+    }
+    async cycle() {
+        this.busy = true;
+        let stage = "claim";
+        try {
+            const claim = await this.deps.claim();
+            if (claim.status === "claimed" && claim.job !== undefined && !this.stopped) {
+                stage = "execute";
+                await this.deps.execute(claim.job);
+                this.deps.requestSync("after_job");
+            }
+        }
+        catch {
+            try {
+                this.deps.reportError?.({ stage, code: stage === "execute" ? "EXECUTION_UNACKNOWLEDGED" : "GATEWAY_UNAVAILABLE" });
+            }
+            catch { /* Observational logging cannot bypass the stop below or discard recovery state. */ }
+            // Unknown execution or terminal outcomes must reconcile before any new claim.
+            if (stage === "execute") {
+                this.busy = false;
+                this.stop();
+                return;
+            }
+        }
+        finally {
+            this.busy = false;
+        }
+        if (this.pending && !this.stopped) {
+            this.pending = false;
+            this.start();
+        }
+    }
+}

package/dist/src/daemon/runtime.js

@@ -17,11 +17,16 @@ import { WorkspaceManager } from "../workspace/workspace-manager.js";
 import { GitClient } from "../workspace/git-client.js";
 import { FileDaemonStateStore } from "../state-store.js";
 import { ExecutionCoordinator } from "./execution-coordinator.js";
-import { JobPoller } from "./job-poller.js";
+import { JobRunner } from "./job-runner.js";
+import { HeartbeatScheduler } from "./heartbeat-scheduler.js";
 import { ProcessLock } from "./process-lock.js";
 import { Daemon } from "./daemon.js";
 import { SessionOpener, sessionOpenAdvertisement } from "./session-opener.js";
-import { SessionOpenPoller, abortableDelay } from "./session-open-poller.js";
+import { RunnerTransport } from "../transport/runner-transport.js";
+import { ReverbSocket } from "../transport/reverb-socket.js";
+import { PendingClosureAcks, createSyncDispatcher } from "../transport/sync-dispatch.js";
+import { abortableDelay } from "../transport/abortable-delay.js";
+import { sideLoops } from "../transport/side-loops.js";
 import { buildTerminalEvidenceCollector } from "../safety/terminal-evidence.js";
 import { packagedHookCommandParts } from "../safety/hook-command.js";
 import { composeReviewedP1Host } from '../verification/p1-host-composition.js';
@@ -115,60 +120,15 @@ export async function buildDaemon(input) {
         workspaces: new WorkspaceManager({ root: input.workspaceRoot, git: new GitClient() }),
         state,
     });
-    const poller = new JobPoller({
+    let transport;
+    /** The adapter probe in progress, if any: a claim waits for it, so versions never change under a claim. */
+    let probing = Promise.resolve();
+    const poller = new JobRunner({
         reportError: (diagnostic) => { process.stderr.write(`${JSON.stringify({ event: "poller_failed", ...diagnostic })}\n`); },
-        heartbeat: async () => {
-            if (input.claudeSupportedProbe) {
-                let current;
-                try {
-                    current = await plugin.probe();
-                }
-                catch {
-                    current = { available: false, authenticated: false, capabilities: [] };
-                }
-                const ready = adapterStatus(current).authenticated && !!current.executableVersion && plugin.capabilities.every(c => current.capabilities.includes(c));
-                const index = probes.findIndex(p => p.id === 'claude_code_cli');
-                if (index >= 0)
-                    probes[index] = { id: 'claude_code_cli', version: '1', ...current, available: ready };
-                if (ready)
-                    versions.claude_code_cli = '1';
-                else
-                    delete versions.claude_code_cli;
-            }
-            let current;
-            try {
-                current = await codex.probe();
-            }
-            catch {
-                current = { available: false, authenticated: false, capabilities: [] };
-            }
-            const ready = adapterStatus(current).authenticated && !!current.executableVersion && codex.capabilities.every(c => current.capabilities.includes(c));
-            const index = probes.findIndex(p => p.id === 'codex_cli');
-            if (index >= 0)
-                probes[index] = { id: 'codex_cli', version: '1', ...current, available: ready };
-            if (ready)
-                versions.codex_cli = '1';
-            else
-                delete versions.codex_cli;
-            let sessionOpen;
-            // A detection error must not stop job claims: the heartbeat simply omits the field.
-            try {
-                sessionOpen = await sessionOpenAdvertisement({ home: input.env.HOME ?? "" });
-            }
-            catch {
-                sessionOpen = undefined;
-            }
-            const askInbox = await asks.advertisement();
-            await gateway.heartbeatLocalRunner({
-                deviceFingerprint: createHash("sha256").update(`${process.getuid?.() ?? 0}|${runnerDisplayName()}|${input.gatewayMcpUrl}`).digest("hex"),
-                displayName: runnerDisplayName(), packageVersion: packageVersion(),
-                capabilities: localRunnerCapabilities(probes, !!localFixHost, localFixHost?.verificationMode),
-                mode: "full",
-                ...(sessionOpen ? { sessionOpen: { ...sessionOpen, ...(askInbox ? { ask_inbox: askInbox } : {}) } } : {}),
-            });
-        },
-        wait: async () => {
-            const claim = await gateway.waitForLocalJob(versions, 25);
+        // Push transport (Work Item 25d8ea74): claimed only when a sync says a job is claimable, with no wait.
+        claim: async () => {
+            await probing;
+            const claim = await gateway.waitForLocalJob(versions, 0);
             if (claim.status !== "claimed" || !claim.job || !claim.task_package || !claim.lease_token || !claim.launch_grant)
                 return { status: "no_job" };
             if (production && claim.task_package.runtime_adapter === 'codex_cli')
@@ -186,23 +146,107 @@ export async function buildDaemon(input) {
         execute: async (job) => {
             await coordinator.execute(job);
         },
-        delay: (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
+        requestSync: reason => { transport?.requestSync(reason); },
+        // Until now the heartbeat said this runner takes no jobs; tell the Gateway at once, and ask whether one waits.
+        onArmed: () => { void heartbeats.tick(); transport?.requestSync("start"); },
     });
-    const opener = new SessionOpener({ home: input.env.HOME ?? "" });
-    const sessionOpens = new SessionOpenPoller({
-        wait: async (signal) => {
-            const result = await gateway.waitForSessionOpens(25, signal);
-            await asks.handleWait(result);
-            return result;
+    const heartbeats = new HeartbeatScheduler({
+        intervalMs: 30_000,
+        snapshot: async () => {
+            // Adapter probes run only between jobs, as they did when the job loop sent the heartbeat.
+            if (!poller.running) {
+                const probe = (async () => {
+                    if (input.claudeSupportedProbe) {
+                        let current;
+                        try {
+                            current = await plugin.probe();
+                        }
+                        catch {
+                            current = { available: false, authenticated: false, capabilities: [] };
+                        }
+                        const ready = adapterStatus(current).authenticated && !!current.executableVersion && plugin.capabilities.every(c => current.capabilities.includes(c));
+                        const index = probes.findIndex(p => p.id === 'claude_code_cli');
+                        if (index >= 0)
+                            probes[index] = { id: 'claude_code_cli', version: '1', ...current, available: ready };
+                        if (ready)
+                            versions.claude_code_cli = '1';
+                        else
+                            delete versions.claude_code_cli;
+                    }
+                    let current;
+                    try {
+                        current = await codex.probe();
+                    }
+                    catch {
+                        current = { available: false, authenticated: false, capabilities: [] };
+                    }
+                    const ready = adapterStatus(current).authenticated && !!current.executableVersion && codex.capabilities.every(c => current.capabilities.includes(c));
+                    const index = probes.findIndex(p => p.id === 'codex_cli');
+                    if (index >= 0)
+                        probes[index] = { id: 'codex_cli', version: '1', ...current, available: ready };
+                    if (ready)
+                        versions.codex_cli = '1';
+                    else
+                        delete versions.codex_cli;
+                })();
+                probing = probe.catch(() => undefined);
+                await probe;
+            }
+            let sessionOpen;
+            // A detection error must not stop job claims: the heartbeat simply omits the field.
+            try {
+                sessionOpen = await sessionOpenAdvertisement({ home: input.env.HOME ?? "" });
+            }
+            catch {
+                sessionOpen = undefined;
+            }
+            const askInbox = await asks.advertisement();
+            return {
+                deviceFingerprint: createHash("sha256").update(`${process.getuid?.() ?? 0}|${runnerDisplayName()}|${input.gatewayMcpUrl}`).digest("hex"),
+                displayName: runnerDisplayName(), packageVersion: packageVersion(),
+                capabilities: acceptingJobs(localRunnerCapabilities(probes, !!localFixHost, localFixHost?.verificationMode), poller.accepting),
+                mode: "full",
+                ...(sessionOpen ? { sessionOpen: { ...sessionOpen, ...(askInbox ? { ask_inbox: askInbox } : {}) } } : {}),
+            };
         },
+        send: async (payload) => { await gateway.heartbeatLocalRunner(payload); },
+        reportError: code => { process.stderr.write(`${JSON.stringify({ event: "heartbeat_failed", code })}\n`); },
+    });
+    const stopping = new AbortController();
+    const closureAcks = new PendingClosureAcks();
+    const opener = new SessionOpener({ home: input.env.HOME ?? "" });
+    const dispatch = createSyncDispatcher({
         open: request => opener.open(request),
         report: async (openId, result, signal) => {
             await gateway.reportSessionOpen({ openId, status: result.status, surface: result.surface,
                 failureCode: result.status === "failed" ? result.failureCode : undefined }, signal);
         },
+        asks,
+        closureAcks,
+        jobs: poller,
         delay: abortableDelay,
+        signal: stopping.signal,
         reportError: diagnostic => { process.stderr.write(`${JSON.stringify({ event: "session_open_poller_failed", ...diagnostic })}\n`); },
     });
+    const pushTransport = new RunnerTransport({
+        sync: async (reason, signal) => {
+            const acknowledged = closureAcks.take();
+            // A runner that takes no jobs right now (reconciling, or suspended for recovery) names no adapter.
+            try {
+                return await gateway.syncRunner({ adapterVersions: poller.accepting ? versions : {}, reason, acknowledgedClosureIds: acknowledged }, signal);
+            }
+            catch (error) {
+                closureAcks.restore(acknowledged);
+                throw error;
+            }
+        },
+        authorize: (socketId, signal) => gateway.authorizeRunnerChannel(socketId, signal),
+        dispatch,
+        openSocket: (target, events) => new ReverbSocket(target, events, { packageVersion: packageVersion() }),
+        report: event => { process.stderr.write(`${JSON.stringify(event)}\n`); },
+    });
+    transport = pushTransport;
+    const sessionOpens = sideLoops({ heartbeat: heartbeats, transport: pushTransport, onStop: () => stopping.abort() });
     const daemon = new Daemon({
         lock: new ProcessLock(join(input.stateRoot, "daemon.lock")), state,
         reconcile: async (stored) => {
@@ -222,6 +266,20 @@ export async function buildDaemon(input) {
     return { daemon, close: async () => { daemon.stop(); await production?.close(); } };
 }
 export function runnerDisplayName() { return `${hostname()} local AI`; }
+/** The execution blocker a full runner reports for every adapter while it takes no jobs. */
+export const RUNNER_NOT_ACCEPTING_JOBS = "RUNNER_NOT_ACCEPTING_JOBS";
+/*
+ * Work Item 25d8ea74: sync keeps presence fresh even while the daemon reconciles or is suspended for recovery, which
+ * the old job loop's heartbeat never did. So the heartbeat itself must say the runner takes no jobs, or the Gateway
+ * would route a job to a runner that never claims it. The Gateway requires at least one capability from a full
+ * runner, so each adapter is reported blocked, with this code, instead of being left out.
+ */
+export function acceptingJobs(capabilities, accepting) {
+    if (accepting)
+        return capabilities;
+    return capabilities.map(capability => ({ ...capability, authenticated: false, execution_status: "blocked",
+        execution_reason_codes: [...new Set([RUNNER_NOT_ACCEPTING_JOBS, ...capability.execution_reason_codes])].slice(0, 20) }));
+}
 /** Unknown mutation outcomes halt polling; known failures replay only their terminal receipt. */
 export async function reconcilePreparationState(previous, deps) {
     if (["publication_pending", "publication_terminal_pending"].includes(previous.phase ?? ""))

package/dist/src/gateway-client.js

@@ -12,6 +12,51 @@ export class GatewayToolError extends Error {
         this.code = code;
     }
 }
+const PUSH_CHANNEL = /^private-ai-gateway\.[a-z0-9_-]{1,32}\.runner\.[a-z0-9:_-]{1,128}$/;
+const PUSH_APP_KEY = /^[A-Za-z0-9_-]{1,128}$/;
+const CHANNEL_AUTH = /^[^:\s]{1,128}:[a-f0-9]{64}$/;
+/*
+ * A sync result without the ask keys ends every stored delivery (the e1c08b33 kill switch), so a result that is not
+ * clearly a sync answer is refused instead of being read as "asks off": the transport retries it with backoff.
+ */
+export function parseRunnerSync(result, runnerId) {
+    const body = result && typeof result === "object" && !Array.isArray(result) ? result : undefined;
+    const malformed = (key) => body !== undefined && body[key] !== undefined && !Array.isArray(body[key]);
+    if (body === undefined || !Array.isArray(body.opens) || malformed("ask_deliveries") || malformed("closed_delivery_ids")) {
+        throw new GatewayToolError("Gateway returned an invalid runner sync result", "local_agent_runner_sync", "GATEWAY_INVALID_TOOL_RESULT");
+    }
+    return {
+        opens: body.opens,
+        ...(Array.isArray(body.ask_deliveries) ? { askDeliveries: body.ask_deliveries } : {}),
+        ...(Array.isArray(body.closed_delivery_ids) ? { closedDeliveryIds: body.closed_delivery_ids } : {}),
+        jobAvailable: body.job_available === true,
+        push: parsePush(body.push, runnerId),
+        syncSeconds: clampSeconds(body.sync_seconds, 15, 120, 30),
+        fallbackSyncSeconds: clampSeconds(body.fallback_sync_seconds, 5, 30, 8),
+    };
+}
+function clampSeconds(value, min, max, fallback) {
+    return typeof value === "number" && Number.isInteger(value) ? Math.min(max, Math.max(min, value)) : fallback;
+}
+function parsePush(value, runnerId) {
+    if (!value || typeof value !== "object")
+        return null;
+    const { url, app_key: appKey, channel, event } = value;
+    if (typeof url !== "string" || typeof appKey !== "string" || typeof channel !== "string" || event !== "runner.sync")
+        return null;
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return null;
+    }
+    if (parsed.protocol !== "wss:" || !PUSH_APP_KEY.test(appKey) || !PUSH_CHANNEL.test(channel))
+        return null;
+    if (!channel.endsWith(`.runner.${runnerId.toLowerCase()}`))
+        return null;
+    return { url, appKey, channel, event };
+}
 function nested(value, path) {
     return path.split(".").reduce((current, key) => {
         if (!current || typeof current !== "object")
@@ -479,6 +524,27 @@ export class McpGatewayClient {
             ...(input.failureCode ? { failure_code: input.failureCode } : {}),
         }, signal);
     }
+    /** acknowledgedClosureIds: closures handled since the last sync; the Gateway lists each again until acknowledged. */
+    async syncRunner(input, signal) {
+        const acknowledged = (input.acknowledgedClosureIds ?? []).slice(0, 50);
+        const result = await this.callTool("local_agent_runner_sync", {
+            runner_id: this.runnerId,
+            adapter_versions: input.adapterVersions,
+            reason: input.reason,
+            ...(acknowledged.length > 0 ? { acknowledged_closure_ids: acknowledged } : {}),
+        }, signal);
+        return parseRunnerSync(result, this.runnerId);
+    }
+    async authorizeRunnerChannel(socketId, signal) {
+        const result = await this.callTool("local_agent_runner_channel_auth", {
+            runner_id: this.runnerId,
+            socket_id: socketId,
+        }, signal);
+        if (typeof result?.channel !== "string" || typeof result.auth !== "string" || !CHANNEL_AUTH.test(result.auth)) {
+            throw new GatewayToolError("Gateway returned an invalid channel authorization", "local_agent_runner_channel_auth", "GATEWAY_INVALID_TOOL_RESULT");
+        }
+        return { channel: result.channel, auth: result.auth };
+    }
     async localRunnerStatus() {
         return this.callTool("local_agent_runner_status", { runner_id: this.runnerId });
     }

package/dist/src/transport/abortable-delay.js

@@ -0,0 +1,12 @@
+/** Resolves after the delay or at once on abort, and never leaves a listener on a long-lived signal. */
+export function abortableDelay(milliseconds, signal) {
+    return new Promise(resolve => {
+        if (signal.aborted) {
+            resolve();
+            return;
+        }
+        const onAbort = () => { clearTimeout(timer); resolve(); };
+        const timer = setTimeout(() => { signal.removeEventListener("abort", onAbort); resolve(); }, milliseconds);
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}

package/dist/src/transport/pusher-protocol.js

@@ -0,0 +1,66 @@
+const SOCKET_ID = /^\d{1,20}\.\d{1,20}$/;
+const DEFAULT_ACTIVITY_TIMEOUT_SECONDS = 30;
+export function subscribeFrame(channel, auth) {
+    return JSON.stringify({ event: "pusher:subscribe", data: { channel, auth } });
+}
+export function pingFrame() {
+    return JSON.stringify({ event: "pusher:ping", data: {} });
+}
+export function pongFrame() {
+    return JSON.stringify({ event: "pusher:pong", data: {} });
+}
+export function decodeFrame(raw, expected) {
+    let frame;
+    try {
+        frame = JSON.parse(raw);
+    }
+    catch {
+        return { kind: "ignored" };
+    }
+    if (!frame || typeof frame !== "object" || Array.isArray(frame))
+        return { kind: "ignored" };
+    const { event, channel, data } = frame;
+    if (typeof event !== "string")
+        return { kind: "ignored" };
+    switch (event) {
+        case "pusher:connection_established": {
+            const payload = parseData(data);
+            const socketId = payload?.socket_id;
+            if (typeof socketId !== "string" || !SOCKET_ID.test(socketId))
+                return { kind: "error" };
+            const timeout = payload?.activity_timeout;
+            const activityTimeoutSeconds = typeof timeout === "number" && Number.isInteger(timeout) && timeout >= 5 && timeout <= 600
+                ? timeout : DEFAULT_ACTIVITY_TIMEOUT_SECONDS;
+            return { kind: "connected", socketId, activityTimeoutSeconds };
+        }
+        case "pusher_internal:subscription_succeeded":
+            return channel === expected.channel ? { kind: "subscribed" } : { kind: "ignored" };
+        case "pusher:ping":
+            return { kind: "ping" };
+        case "pusher:pong":
+            return { kind: "pong" };
+        case "pusher:error": {
+            const code = parseData(data)?.code;
+            return typeof code === "number" ? { kind: "error", code } : { kind: "error" };
+        }
+        case "pusher:subscription_error":
+            return { kind: "error" };
+        default:
+            break;
+    }
+    if (event.startsWith("client-") || event.startsWith("pusher"))
+        return { kind: "ignored" };
+    return channel === expected.channel && event === expected.event ? { kind: "signal" } : { kind: "ignored" };
+}
+function parseData(data) {
+    if (typeof data === "string") {
+        try {
+            const parsed = JSON.parse(data);
+            return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return data && typeof data === "object" && !Array.isArray(data) ? data : undefined;
+}

package/dist/src/transport/reverb-socket.js

@@ -0,0 +1,144 @@
+import WebSocket from "ws";
+import { decodeFrame, pingFrame, pongFrame, subscribeFrame } from "./pusher-protocol.js";
+const CONNECT_TIMEOUT_MS = 10_000;
+const SUBSCRIBE_TIMEOUT_MS = 10_000;
+/** How long close() waits for the server's close frame before dropping the connection. */
+const CLOSE_GRACE_MS = 1_000;
+const PONG_TIMEOUT_MS = 10_000;
+const MAX_PING_INTERVAL_MS = 30_000;
+/*
+ * ws sends no User-Agent of its own, and the ELSA load balancer's WAF (AWS managed common rules) answers a request
+ * without one with 403 before Reverb sees it. Measured against the development Reverb on 2026-10-24.
+ */
+export function pushSocketOptions(packageVersion, connectTimeoutMs) {
+    return { handshakeTimeout: connectTimeoutMs, headers: { "User-Agent": `mtec-ai-local-runner/${packageVersion}` } };
+}
+export function pushSocketUrl(target, packageVersion) {
+    const url = new URL(target.url);
+    if (url.protocol !== "wss:")
+        throw new Error("PUSH_URL_NOT_WSS");
+    url.pathname = `/app/${encodeURIComponent(target.appKey)}`;
+    url.search = new URLSearchParams({ protocol: "7", client: "mtec-ai-local-runner", version: packageVersion, flash: "false" }).toString();
+    return url.toString();
+}
+export class ReverbSocket {
+    target;
+    events;
+    options;
+    socket;
+    ended = false;
+    ownerClosed = false;
+    pingIntervalMs;
+    connectTimer;
+    subscribeTimer;
+    pingTimer;
+    pongTimer;
+    constructor(target, events, options) {
+        this.target = target;
+        this.events = events;
+        this.options = options;
+        this.pingIntervalMs = options.maxPingIntervalMs ?? MAX_PING_INTERVAL_MS;
+        const connectTimeoutMs = options.connectTimeoutMs ?? CONNECT_TIMEOUT_MS;
+        const url = pushSocketUrl(target, options.packageVersion);
+        const create = options.createSocket ?? ((value) => new WebSocket(value, pushSocketOptions(options.packageVersion, connectTimeoutMs)));
+        this.socket = create(url);
+        this.connectTimer = setTimeout(() => this.fail("connect_timeout"), connectTimeoutMs);
+        this.socket.on("message", data => this.onMessage(String(data)));
+        this.socket.on("close", () => this.fail("closed"));
+        this.socket.on("error", () => this.fail("error"));
+    }
+    subscribe(auth) {
+        if (this.ended)
+            return;
+        clearTimeout(this.subscribeTimer);
+        this.subscribeTimer = setTimeout(() => this.fail("subscribe_timeout"), this.options.subscribeTimeoutMs ?? SUBSCRIBE_TIMEOUT_MS);
+        this.send(subscribeFrame(this.target.channel, auth));
+    }
+    close() {
+        if (this.ended)
+            return;
+        this.ownerClosed = true;
+        this.end();
+        try {
+            this.socket.close();
+        }
+        catch { /* Closing a socket that is already gone is fine. */ }
+        // ws waits up to 30 s for the server's close frame, which would hold a stopping daemon open.
+        const drop = setTimeout(() => { try {
+            this.socket.terminate();
+        }
+        catch { /* Already gone. */ } }, CLOSE_GRACE_MS);
+        drop.unref?.();
+    }
+    onMessage(raw) {
+        if (this.ended)
+            return;
+        this.armPing();
+        const frame = decodeFrame(raw, { channel: this.target.channel, event: this.target.event });
+        switch (frame.kind) {
+            case "connected":
+                clearTimeout(this.connectTimer);
+                this.pingIntervalMs = Math.min(frame.activityTimeoutSeconds * 1000, this.options.maxPingIntervalMs ?? MAX_PING_INTERVAL_MS);
+                this.armPing();
+                this.events.onConnected(frame.socketId);
+                break;
+            case "subscribed":
+                clearTimeout(this.subscribeTimer);
+                this.events.onSubscribed();
+                break;
+            case "signal":
+                this.events.onSignal();
+                break;
+            case "ping":
+                this.send(pongFrame());
+                break;
+            case "error":
+                // The Pusher close code decides how soon the transport reconnects (4000-4099: not unchanged).
+                this.fail(frame.code !== undefined && Number.isInteger(frame.code) && frame.code >= 4000 && frame.code <= 4299 ? `protocol_error_${frame.code}` : "protocol_error");
+                break;
+            default:
+                break;
+        }
+    }
+    armPing() {
+        clearTimeout(this.pongTimer);
+        this.pongTimer = undefined;
+        clearTimeout(this.pingTimer);
+        if (this.ended)
+            return;
+        this.pingTimer = setTimeout(() => {
+            this.send(pingFrame());
+            if (this.ended)
+                return;
+            this.pongTimer = setTimeout(() => this.fail("pong_timeout"), this.options.pongTimeoutMs ?? PONG_TIMEOUT_MS);
+        }, this.pingIntervalMs);
+    }
+    send(frame) {
+        if (this.ended)
+            return;
+        try {
+            this.socket.send(frame);
+        }
+        catch {
+            this.fail("send_failed");
+        }
+    }
+    fail(reason) {
+        if (this.ended)
+            return;
+        this.end();
+        try {
+            this.socket.terminate();
+        }
+        catch { /* The socket may already be gone. */ }
+        if (!this.ownerClosed)
+            this.events.onClosed(reason);
+    }
+    end() {
+        this.ended = true;
+        clearTimeout(this.connectTimer);
+        clearTimeout(this.subscribeTimer);
+        clearTimeout(this.pingTimer);
+        clearTimeout(this.pongTimer);
+    }
+}

package/dist/src/transport/runner-transport.js

@@ -0,0 +1,265 @@
+const MAX_BACKOFF_MS = 30_000;
+/** A subscription must last this long before a later loss starts the reconnect backoff from 1 s again. */
+const STABLE_SUBSCRIPTION_MS = 60_000;
+/**
+ * Pusher closes 4000-4099 mean "do not reconnect unchanged" (for example 4001 unknown app, 4009 unauthorized).
+ * The runner keeps its fallback syncs and tries the socket again only this much later, or when the push target changes.
+ */
+const REJECTED_RECONNECT_MS = 600_000;
+const REJECTED_REASON = /^protocol_error_40\d\d$/;
+/** The caught error's own failure code (such as GATEWAY_HTTP_503), never its message. */
+function causeOf(error) {
+    const code = error?.code;
+    return typeof code === "string" && /^[A-Z0-9_]{1,64}$/.test(code) ? code : undefined;
+}
+export class RunnerTransport {
+    deps;
+    controller = new AbortController();
+    current = "starting";
+    socket;
+    target;
+    syncSeconds = 30;
+    fallbackSeconds = 8;
+    /** Set by run(). A request before it is dropped: run() syncs first, and only after the first heartbeat. */
+    started = false;
+    inFlight = false;
+    dirty = false;
+    lastSyncAt = Number.NEGATIVE_INFINITY;
+    syncFailures = 0;
+    /** After a failed sync, requests before this time wait for the retry already scheduled (same backoff as before). */
+    retryNotBefore = 0;
+    socketFailures = 0;
+    syncTimer;
+    /** When the pending sync timer fires; a lost socket keeps it when it is already due sooner than the fallback. */
+    syncDueAt = Number.POSITIVE_INFINITY;
+    subscribedAt;
+    reconnectTimer;
+    release;
+    stopped = new Promise(resolve => { this.release = resolve; });
+    constructor(deps) {
+        this.deps = deps;
+    }
+    get state() { return this.current; }
+    async run() {
+        // A pending promise alone does not keep Node alive; this referenced timer does until stop().
+        const keepAlive = setInterval(() => undefined, 60_000);
+        try {
+            this.started = true;
+            this.requestSync("start");
+            await this.stopped;
+        }
+        finally {
+            clearInterval(keepAlive);
+        }
+    }
+    stop() {
+        if (this.current === "stopped")
+            return;
+        this.current = "stopped";
+        this.controller.abort();
+        clearTimeout(this.syncTimer);
+        clearTimeout(this.reconnectTimer);
+        this.closeSocket();
+        this.release();
+    }
+    requestSync(reason) {
+        if (!this.started || this.current === "stopped")
+            return;
+        if (this.inFlight) {
+            this.dirty = true;
+            return;
+        }
+        if (Date.now() < this.retryNotBefore)
+            return;
+        this.trigger(reason);
+    }
+    /** Starts a sync now, or once the minimum gap has passed. Timers call it directly: they are the backoff. */
+    trigger(reason) {
+        if (this.current === "stopped")
+            return;
+        if (this.inFlight) {
+            this.dirty = true;
+            return;
+        }
+        clearTimeout(this.syncTimer);
+        this.syncDueAt = Number.POSITIVE_INFINITY;
+        const wait = this.lastSyncAt + (this.deps.minSyncGapMs ?? 1000) - Date.now();
+        if (wait > 0) {
+            this.syncDueAt = Date.now() + wait;
+            this.syncTimer = setTimeout(() => { void this.runSync(reason); }, wait);
+            return;
+        }
+        void this.runSync(reason);
+    }
+    async runSync(reason) {
+        if (this.current === "stopped" || this.inFlight)
+            return;
+        this.inFlight = true;
+        this.lastSyncAt = Date.now();
+        let retryInMs;
+        try {
+            const result = await this.deps.sync(reason, this.controller.signal);
+            // A sync that resolves after stop() must not reopen a socket or re-arm a timer.
+            if (this.isStopped())
+                return;
+            this.syncFailures = 0;
+            this.retryNotBefore = 0;
+            this.syncSeconds = result.syncSeconds;
+            this.fallbackSeconds = result.fallbackSyncSeconds;
+            this.applyPush(result.push);
+            try {
+                await this.deps.dispatch(result);
+            }
+            catch (error) {
+                this.report({ event: "transport_dispatch_failed", cause: causeOf(error) });
+            }
+        }
+        catch (error) {
+            if (!this.isStopped()) {
+                this.syncFailures += 1;
+                retryInMs = this.backoff(this.syncFailures);
+                this.retryNotBefore = Date.now() + retryInMs;
+                this.report({ event: "transport_sync_failed", reason, cause: causeOf(error) });
+            }
+        }
+        finally {
+            this.inFlight = false;
+        }
+        if (this.isStopped())
+            return;
+        if (this.dirty) {
+            this.dirty = false;
+            // After a failed sync the signal waits out the backoff with the retry instead of skipping it.
+            if (retryInMs === undefined) {
+                this.requestSync("signal");
+                return;
+            }
+        }
+        this.schedule(retryInMs);
+    }
+    schedule(overrideMs) {
+        clearTimeout(this.syncTimer);
+        const subscribed = this.current === "subscribed";
+        const ms = overrideMs ?? (subscribed ? this.syncSeconds : this.fallbackSeconds) * 1000;
+        const reason = subscribed ? "periodic" : "fallback";
+        this.syncDueAt = Date.now() + ms;
+        this.syncTimer = setTimeout(() => this.trigger(reason), ms);
+    }
+    applyPush(push) {
+        if (this.isStopped())
+            return;
+        if (push === null) {
+            this.target = undefined;
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = undefined;
+            this.closeSocket();
+            this.current = "fallback";
+            return;
+        }
+        const changed = !this.target || this.target.url !== push.url || this.target.appKey !== push.appKey
+            || this.target.channel !== push.channel || this.target.event !== push.event;
+        this.target = push;
+        if (changed) {
+            this.closeSocket();
+            this.connect();
+            return;
+        }
+        if (!this.socket && !this.reconnectTimer)
+            this.connect();
+    }
+    connect() {
+        const target = this.target;
+        if (!target || this.current === "stopped")
+            return;
+        clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = undefined;
+        this.current = "connecting";
+        this.subscribedAt = undefined;
+        let socket;
+        const events = {
+            onConnected: socketId => { void this.subscribe(socket, socketId); },
+            onSubscribed: () => {
+                if (!socket || this.socket !== socket || this.current === "stopped")
+                    return;
+                this.current = "subscribed";
+                // The backoff restarts only once a subscription has held (see lostSocket), so a server that accepts and
+                // then drops every subscription cannot drive a reconnect and sync storm.
+                this.subscribedAt = Date.now();
+                this.report({ event: "transport_subscribed" });
+                this.requestSync("signal");
+            },
+            onSignal: () => { if (socket && this.socket === socket)
+                this.requestSync("signal"); },
+            onClosed: reason => { if (socket && this.socket === socket)
+                this.lostSocket(reason); },
+        };
+        try {
+            socket = this.deps.openSocket(target, events);
+            this.socket = socket;
+        }
+        catch (error) {
+            this.report({ event: "transport_socket_failed", cause: causeOf(error) });
+            this.lostSocket("open_failed");
+        }
+    }
+    async subscribe(socket, socketId) {
+        if (!socket || this.socket !== socket)
+            return;
+        try {
+            const { channel, auth } = await this.deps.authorize(socketId, this.controller.signal);
+            if (this.socket !== socket)
+                return;
+            if (channel !== this.target?.channel)
+                throw Object.assign(new Error("channel mismatch"), { code: "PUSH_CHANNEL_MISMATCH" });
+            socket.subscribe(auth);
+        }
+        catch (error) {
+            if (this.socket !== socket)
+                return;
+            this.report({ event: "transport_auth_failed", cause: causeOf(error) });
+            this.closeSocket();
+            this.lostSocket("auth_failed");
+        }
+    }
+    /** The socket is gone without us closing it: sync on the fallback interval and reconnect with backoff. */
+    lostSocket(reason) {
+        this.socket = undefined;
+        if (this.current === "stopped")
+            return;
+        this.current = "fallback";
+        this.report({ event: "transport_socket_closed", reason });
+        if (this.subscribedAt !== undefined && Date.now() - this.subscribedAt >= STABLE_SUBSCRIPTION_MS)
+            this.socketFailures = 0;
+        this.subscribedAt = undefined;
+        this.socketFailures += 1;
+        clearTimeout(this.reconnectTimer);
+        const reconnectInMs = REJECTED_REASON.test(reason) ? REJECTED_RECONNECT_MS : this.backoff(this.socketFailures);
+        this.reconnectTimer = setTimeout(() => { this.reconnectTimer = undefined; this.connect(); }, reconnectInMs);
+        // Keep a sync that is already due sooner (the next fallback sync, or a signal waiting out the minimum gap):
+        // restarting the timer on every lost socket would stretch the fallback interval past the latency target.
+        if (!this.inFlight && this.syncDueAt > Date.now() + this.fallbackSeconds * 1000)
+            this.schedule();
+    }
+    closeSocket() {
+        const socket = this.socket;
+        this.socket = undefined;
+        try {
+            socket?.close();
+        }
+        catch { /* Closing must not stop the transport. */ }
+    }
+    backoff(failures) {
+        const base = Math.min(MAX_BACKOFF_MS, (this.deps.backoffBaseMs ?? 1000) * (2 ** Math.min(5, failures - 1)));
+        return base + Math.floor(base * 0.2 * (this.deps.random ?? Math.random)());
+    }
+    /** Read through a method: stop() may run while a sync awaits, which narrowing on the field cannot see. */
+    isStopped() {
+        return this.current === "stopped";
+    }
+    report(event) {
+        try {
+            this.deps.report?.(event);
+        }
+        catch { /* Logging cannot stop the transport. */ }
+    }
+}

package/dist/src/transport/side-loops.js

@@ -0,0 +1,50 @@
+export function sideLoops(deps) {
+    let stopped = false;
+    return {
+        async run() {
+            await deps.heartbeat.tick();
+            if (stopped)
+                return;
+            await Promise.all([deps.transport.run(), deps.heartbeat.run()]);
+        },
+        stop() {
+            stopped = true;
+            try {
+                deps.onStop?.();
+            }
+            catch { /* Stopping must reach both loops. */ }
+            deps.transport.stop();
+            deps.heartbeat.stop();
+        },
+    };
+}
+/** A heartbeat function that decides for itself when to send (the messenger's), called on a fixed tick. */
+export function tickingHeartbeat(beat, tickMs, signal) {
+    let timer;
+    let release;
+    const stopped = new Promise(resolve => { release = resolve; });
+    let ended = false;
+    const tick = async () => { try {
+        await beat(signal);
+    }
+    catch { /* The beat reports its own failures. */ } };
+    return {
+        tick,
+        async run() {
+            const loop = () => {
+                if (ended)
+                    return;
+                timer = setTimeout(() => { void tick().then(loop); }, tickMs);
+            };
+            loop();
+            await stopped;
+        },
+        stop() {
+            if (ended)
+                return;
+            ended = true;
+            clearTimeout(timer);
+            release();
+        },
+    };
+}

package/dist/src/transport/sync-dispatch.js

@@ -0,0 +1,91 @@
+/*
+ * Closures the runner has handled and not yet acknowledged (Work Item 25d8ea74). A closure is listed until the
+ * runner acknowledges it on a later sync, so a lost sync response cannot lose it (at-least-once). take() hands the
+ * ids to the next sync; restore() puts them back when that sync fails.
+ */
+export class PendingClosureAcks {
+    ids = new Set();
+    add(ids) {
+        for (const id of ids)
+            if (typeof id === "string" && id !== "" && this.ids.size < 200)
+                this.ids.add(id);
+    }
+    take() {
+        const taken = [...this.ids].slice(0, 50);
+        for (const id of taken)
+            this.ids.delete(id);
+        return taken;
+    }
+    restore(ids) { this.add(ids); }
+}
+/** Pauses before the second and third report attempts. The Gateway treats a repeated report as idempotent. */
+const REPORT_RETRY_DELAYS_MS = [1000, 2000];
+function causeOf(error) {
+    const code = error?.code;
+    return typeof code === "string" && /^[A-Z0-9_]{1,64}$/.test(code) ? code : undefined;
+}
+export function createSyncDispatcher(deps) {
+    const fail = (stage, code, error) => {
+        const cause = causeOf(error);
+        try {
+            deps.reportError?.({ stage, code, ...(cause ? { cause } : {}) });
+        }
+        catch { /* Logging cannot stop dispatch. */ }
+    };
+    const handleOpen = async (request) => {
+        let result;
+        try {
+            result = await deps.open(request);
+        }
+        catch (error) {
+            if (!deps.signal.aborted)
+                fail("open", "SESSION_OPEN_OPEN_FAILED", error);
+            return;
+        }
+        const openId = request?.open_id;
+        if (typeof openId !== "string" || openId === "")
+            return;
+        for (let attempt = 0;; attempt += 1) {
+            try {
+                await deps.report(openId, result, deps.signal);
+                return;
+            }
+            catch (error) {
+                if (deps.signal.aborted)
+                    return;
+                const retryDelay = REPORT_RETRY_DELAYS_MS[attempt];
+                if (retryDelay === undefined) {
+                    fail("report", "SESSION_OPEN_REPORT_FAILED", error);
+                    return;
+                }
+                await deps.delay(retryDelay, deps.signal).catch(() => undefined);
+                if (deps.signal.aborted)
+                    return;
+            }
+        }
+    };
+    return async (result) => {
+        // Asks first: they are local and quick, while each open can spend seconds on report retries.
+        if (deps.asks) {
+            try {
+                const handled = await deps.asks.handleWait({
+                    ...(result.askDeliveries !== undefined ? { askDeliveries: result.askDeliveries } : {}),
+                    ...(result.closedDeliveryIds !== undefined ? { closedDeliveryIds: result.closedDeliveryIds } : {}),
+                });
+                // Acknowledged only once handled: a failed handleWait leaves them for the Gateway to list again.
+                if (handled !== false)
+                    deps.closureAcks?.add(result.closedDeliveryIds ?? []);
+            }
+            catch (error) {
+                fail("asks", "ASK_DISPATCH_FAILED", error);
+            }
+        }
+        if (result.jobAvailable)
+            deps.jobs?.notify();
+        for (const request of result.opens) {
+            if (deps.signal.aborted)
+                return;
+            await handleOpen(request);
+        }
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mtech-ai-local-runner",
-  "version": "0.1.48",
+  "version": "0.1.49",
   "private": false,
   "license": "UNLICENSED",
   "bin": {
@@ -34,11 +34,13 @@
   },
   "dependencies": {
     "smol-toml": "1.9.1",
-    "uuid": "11.1.1"
+    "uuid": "11.1.1",
+    "ws": "8.18.3"
   },
   "devDependencies": {
     "@types/node": "22.19.11",
     "@types/uuid": "10.0.0",
+    "@types/ws": "8.18.1",
     "typescript": "5.9.3",
     "vitest": "4.0.18"
   }