mtech-ai-local-runner 0.1.57 → 0.1.59

package/README.md

@@ -1,3 +1,7 @@
+## 0.1.59: completed publication acknowledgement
+
+Runner 0.1.59 corrects post-publication completion acknowledgement. The Gateway binding primary key is independent of the client session UUID. Recovery uses the saved binding/Job/generation mapping and exact server completion receipt; it does not renew an expired lease or replay a completed publication. Unverified PRs retain `unverified` / `CI not_run` status.
+
 ## 0.1.57: answers go to the session the person is using
 
 An answer names the asker's sessions linked to the Work Item. A named session now gets it only if a person typed in it in
@@ -911,3 +915,11 @@ not evidence of logout. These diagnostics do not bypass per-job admission.
 Use `local_replace({path, old, new})` for a small approved edit after reading the file: `old` must be nonempty and match exactly once, including whitespace. Zero or overlapping/multiple matches are rejected with distinct errors and no write. Replacement text must not be a patch; the result retains the same scoped write, size, link and revocation protections as `local_edit`. `local_edit` remains a complete-file replacement API.
 
 Both CLI adapters require the five-tool inventory. Gateway tools descriptors and runtime pins must match this release; CLI release manifests and the standalone binary stay fixed. In `gateway_publish_v1`, missing registered tests is expected: report not_run/unverified, apply only the smallest source-evidenced correction, disclose uncertainty and seal for a human-reviewed Gateway PR. Historical contracts and attempts are not edited. Reverb 0.1.49 is retained; installation, deployment and real model execution remain separate approvals.
+
+## 0.1.58: publication completion and diagnostic compatibility
+
+Publication cursor synchronization now validates the exact server proof for the selected mode: `progress/server_publication` with `unverified` and `CI not_run` for `gateway_publish_v1`, or the existing verified test-result form for `gateway_ci_v1`. It checks the frozen Job, current host context and completed publication fingerprints before advancing the cursor. No model output can grant publication authority.
+
+Cursor failures retain recovery state and report `LOCAL_FIX_PUBLICATION_CURSOR_REJECTED` / `cursor_sync`. Runner advertisement failures use `RUNNER_HEARTBEAT_SEND_FAILED`; execution Job heartbeat failures use `JOB_HEARTBEAT_FAILED`. Diagnostics expose only bounded elapsed milliseconds, HTTP status and allowlisted OS codes. The existing fence/cancellation policy is unchanged. This package does not repair expired leases or existing completed-PR projections by itself, and installing it does not authorize a model rerun.
+
+For `gateway_publish_v1` only, a matched final `server_reconciliation` completed event acknowledges the Gateway's atomic Job/binding completion. The Runner reads once before cursor/terminal work, and once on a terminal-path rejection if necessary, then skips duplicate terminal and Job writes only when every identity/publication field matches the stored server response. Unknown evidence remains suspended for recovery. The Loop's paused/human-review projection remains entirely Gateway-owned; unverified tests remain unverified. This does not execute or archive the existing40bf recovery.

package/dist/src/daemon/execution-coordinator.js

@@ -1,7 +1,8 @@
 import { completionRejectionDiagnostic } from '../adapters/completion-report.js';
+import { publicationError } from '../publication/failure.js';
 import { PublicationOutcomeUnknownError } from '../publication/publisher.js';
 import { assertP1Bindings, hasP1, p1ModelEvent } from '../verification/p1-execution-host.js';
-import { executionError, executionFailure } from '../safety/execution-failure.js';
+import { executionError, executionFailure, jobHeartbeatError } from '../safety/execution-failure.js';
 import { isUnsupportedSupervisorCommand } from '../safety/unsupported-supervisor-command.js';
 import { requireSecurityRequirements } from '../safety/security-requirements.js';
 import { GatewayToolError } from "../gateway-client.js";
@@ -194,6 +195,8 @@ export class ExecutionCoordinator {
         const controlStopped = new Promise((_, reject) => { rejectControlStop = reject; });
         void controlStopped.catch(() => { });
         let publicationPending = false;
+        let serverCompletionConfirmed = false, serverCompletionCheckFailed = false;
+        let publicationRecoveryState;
         let commandCursor = 0;
         let controlsStopped = false;
         let controlsInFlight;
@@ -315,14 +318,19 @@ export class ExecutionCoordinator {
                 await readControls();
                 requireControlFence();
                 if (!requestedTerminal && this.deps.gateway.heartbeat) {
-                    const renewed = await fenced(this.deps.gateway.heartbeat(binding.bindingId, job, controlAbort.signal));
-                    requireControlFence();
-                    const expiry = validateJobLease(renewed, job, true);
-                    if (!['running', 'review_pending'].includes(renewed.job.status))
-                        throw new GatewayToolError('Running Job lease status is invalid', 'local_agent_job_heartbeat', 'JOB_LEASE_FENCE_INVALID');
-                    this.deps.gateway.confirmJobLease?.(job, expiry);
-                    leaseExpiresAt = expiry;
-                    armLeaseBoundary();
+                    try {
+                        const renewed = await fenced(this.deps.gateway.heartbeat(binding.bindingId, job, controlAbort.signal));
+                        requireControlFence();
+                        const expiry = validateJobLease(renewed, job, true);
+                        if (!['running', 'review_pending'].includes(renewed.job.status))
+                            throw new GatewayToolError('Running Job lease status is invalid', 'local_agent_job_heartbeat', 'JOB_LEASE_FENCE_INVALID');
+                        this.deps.gateway.confirmJobLease?.(job, expiry);
+                        leaseExpiresAt = expiry;
+                        armLeaseBoundary();
+                    }
+                    catch (error) {
+                        throw jobHeartbeatError(error);
+                    }
                 }
             })().catch((error) => {
                 failFence(error);
@@ -334,6 +342,17 @@ export class ExecutionCoordinator {
         let sequence = 0;
         let checkpointSeen = false;
         let eventUncertain = false;
+        const recognizeServerCompletion = async () => {
+            if (!localFixPublication || serverCompletionCheckFailed || job.taskPackage.local_fix_scope?.verification_mode !== 'gateway_publish_v1' || !this.deps.gateway.confirmServerPublicationCompletion)
+                return false;
+            try {
+                return await this.deps.gateway.confirmServerPublicationCompletion(binding.bindingId, sequence, job, localFixPublication);
+            }
+            catch (error) {
+                serverCompletionCheckFailed = true;
+                throw publicationError('server_completion', 'LOCAL_FIX_SERVER_COMPLETION_REJECTED', true, error);
+            }
+        };
         const stop = async (ignoreControlFailure = false) => {
             controlsStopped = true;
             const cancelled = stopExecutor();
@@ -514,18 +533,31 @@ export class ExecutionCoordinator {
                                 executionStage = 'local_fix_publication';
                                 if (!checkpointSeen)
                                     await append({ eventType: 'checkpoint_ready', summary: 'final checkpoint ready' });
-                                await publicationStep(() => this.deps.state.save({ jobId: job.id, generation: job.generation, leaseToken: job.leaseToken, phase: 'publication_pending', bindingId: binding.bindingId, eventCursor: sequence, workspaceManifest: workspace.manifest, publicationRecovery: { version: 1, job, checkoutPath: workspace.path, bindingId: binding.bindingId, completedEvent: event, gatewayContext: this.deps.gateway.publicationRecoveryContext?.(binding.bindingId), securityReceipt: adapter.securityReceipt?.(), freezeConfirmed: lifecycle.frozen } }));
+                                publicationRecoveryState = { jobId: job.id, generation: job.generation, leaseToken: job.leaseToken, phase: 'publication_pending', bindingId: binding.bindingId, eventCursor: sequence, workspaceManifest: workspace.manifest, publicationRecovery: { version: 1, job, checkoutPath: workspace.path, bindingId: binding.bindingId, completedEvent: event, gatewayContext: this.deps.gateway.publicationRecoveryContext?.(binding.bindingId), securityReceipt: adapter.securityReceipt?.(), freezeConfirmed: lifecycle.frozen } };
+                                await publicationStep(() => this.deps.state.save(publicationRecoveryState));
                                 publicationPending = true;
-                                localFixPublication = await publicationStep(() => fixSession.finalize(event));
+                                localFixPublication = await publicationStep(async () => { localFixPublication = await fixSession.finalize(event); return localFixPublication; });
+                                publicationRecoveryState = { ...publicationRecoveryState, publicationRecovery: { ...publicationRecoveryState.publicationRecovery, completedPublication: structuredClone(localFixPublication) } };
+                                try {
+                                    await this.deps.state.save(publicationRecoveryState);
+                                }
+                                catch (error) {
+                                    throw publicationError('journal', 'LOCAL_FIX_PUBLICATION_OUTCOME_UNKNOWN', true, error);
+                                }
+                                if (await recognizeServerCompletion()) {
+                                    serverCompletionConfirmed = true;
+                                    terminal = event;
+                                    break;
+                                }
                                 if (this.deps.gateway.syncPublicationCursor) {
                                     try {
-                                        const cursor = await publicationStep(() => this.deps.gateway.syncPublicationCursor(binding.bindingId, sequence));
+                                        const cursor = await publicationStep(() => this.deps.gateway.syncPublicationCursor(binding.bindingId, sequence, job, localFixPublication));
                                         if (!Number.isSafeInteger(cursor) || cursor < sequence)
                                             throw new Error('Invalid event cursor');
                                         sequence = cursor;
                                     }
-                                    catch {
-                                        throw new PublicationOutcomeUnknownError();
+                                    catch (error) {
+                                        throw publicationError('cursor_sync', 'LOCAL_FIX_PUBLICATION_CURSOR_REJECTED', true, error);
                                     }
                                 }
                                 if (controlsInFlight)
@@ -563,18 +595,20 @@ export class ExecutionCoordinator {
                         await iterator.return?.();
                 }
             }
-            await stop();
-            if (publicationPending && requestedTerminal)
-                throw new PublicationOutcomeUnknownError();
-            if (requestedTerminal)
-                terminal = requestedTerminal;
-            if (!terminal) {
-                terminal = { eventType: "failed", summary: "adapter ended without a terminal event" };
+            await stop(serverCompletionConfirmed);
+            if (!serverCompletionConfirmed) {
+                if (publicationPending && requestedTerminal)
+                    throw new PublicationOutcomeUnknownError();
+                if (requestedTerminal)
+                    terminal = requestedTerminal;
+                if (!terminal) {
+                    terminal = { eventType: "failed", summary: "adapter ended without a terminal event" };
+                }
+                terminal = daemonOutcome(terminal).event;
+                if (terminal.eventType === 'completed' && !checkpointSeen)
+                    await append({ eventType: 'checkpoint_ready', summary: 'final checkpoint ready' });
+                await append(terminal);
             }
-            terminal = daemonOutcome(terminal).event;
-            if (terminal.eventType === 'completed' && !checkpointSeen)
-                await append({ eventType: 'checkpoint_ready', summary: 'final checkpoint ready' });
-            await append(terminal);
         }
         catch (error) {
             try {
@@ -593,36 +627,47 @@ export class ExecutionCoordinator {
                 catch { /* logging must not change terminal reconciliation */ }
                 throw cleanupError;
             }
-            if (error instanceof PublicationOutcomeUnknownError || (publicationPending && (heartbeatFailure || requestedTerminal))) {
+            if (!serverCompletionCheckFailed) {
                 try {
-                    this.deps.reportExecutionFailure?.(executionFailure(error, executionStage));
+                    if (await recognizeServerCompletion())
+                        serverCompletionConfirmed = true;
+                }
+                catch (reconciliationError) {
+                    error = reconciliationError;
                 }
-                catch { /* fixed diagnostics must not alter reconciliation */ }
-                // The provider may already have committed/pushed/opened a PR. Do not
-                // release this run as failed or let restart begin another model session.
-                throw new Error('Local publication outcome requires reconciliation');
-            }
-            if (requestedTerminal && !heartbeatFailure && !eventUncertain) {
-                terminal = daemonOutcome(requestedTerminal).event;
             }
-            else {
-                // Do not complete a job whose terminal evidence was not acknowledged.
-                // A safe bounded reason prevents raw adapter/transport errors leaking.
-                const diagnostic = executionFailure(error, executionStage);
-                failureDiagnostic = diagnostic;
-                // Log before reporting so an unavailable Gateway does not erase the cause.
-                try {
-                    this.deps.reportExecutionFailure?.(structuredClone(diagnostic));
+            if (!serverCompletionConfirmed) {
+                if (error instanceof PublicationOutcomeUnknownError || (publicationPending && (heartbeatFailure || requestedTerminal))) {
+                    try {
+                        this.deps.reportExecutionFailure?.(executionFailure(error, executionStage));
+                    }
+                    catch { /* fixed diagnostics must not alter reconciliation */ }
+                    // The provider may already have committed/pushed/opened a PR. Do not
+                    // release this run as failed or let restart begin another model session.
+                    throw new Error('Local publication outcome requires reconciliation');
                 }
-                catch { /* logging must not change terminal reconciliation */ }
-                if (heartbeatFailure)
-                    throw error;
-                if (eventUncertain || ['GATEWAY_TOOL_REJECTED', 'GATEWAY_TRANSPORT_ERROR', 'WORK_LOOP_CANCELLED'].includes(diagnostic.code)
-                    || diagnostic.stage === 'terminal_evidence')
-                    throw error;
-                terminal = { eventType: "failed", summary: "daemon execution or event reporting failed", payload: { execution_failure: { ...diagnostic } } };
+                if (requestedTerminal && !heartbeatFailure && !eventUncertain) {
+                    terminal = daemonOutcome(requestedTerminal).event;
+                }
+                else {
+                    // Do not complete a job whose terminal evidence was not acknowledged.
+                    // A safe bounded reason prevents raw adapter/transport errors leaking.
+                    const diagnostic = executionFailure(error, executionStage);
+                    failureDiagnostic = diagnostic;
+                    // Log before reporting so an unavailable Gateway does not erase the cause.
+                    try {
+                        this.deps.reportExecutionFailure?.(structuredClone(diagnostic));
+                    }
+                    catch { /* logging must not change terminal reconciliation */ }
+                    if (heartbeatFailure)
+                        throw error;
+                    if (eventUncertain || ['GATEWAY_TOOL_REJECTED', 'GATEWAY_TRANSPORT_ERROR', 'WORK_LOOP_CANCELLED'].includes(diagnostic.code)
+                        || diagnostic.stage === 'terminal_evidence')
+                        throw error;
+                    terminal = { eventType: "failed", summary: "daemon execution or event reporting failed", payload: { execution_failure: { ...diagnostic } } };
+                }
+                await append(terminal);
             }
-            await append(terminal);
         }
         finally {
             controlsStopped = true;
@@ -634,6 +679,13 @@ export class ExecutionCoordinator {
                 clearTimeout(leaseBoundary);
             await fixSession?.close();
         }
+        if (serverCompletionConfirmed) {
+            await this.deps.gateway.releaseServerCompletedJob?.(job.id);
+            await this.deps.state.clear();
+            return;
+        }
+        if (!terminal)
+            throw publicationError('server_completion', 'LOCAL_FIX_SERVER_COMPLETION_REJECTED', true);
         const { status, reason } = daemonOutcome(terminal);
         const diagnostic = status === "failed" || status === "blocked" ? completionReportDiagnostic(terminal.payload?.completion_report) : undefined;
         const reportDiagnostic = diagnostic && (status === "blocked"

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

@@ -1,3 +1,4 @@
+import { transportDiagnostic } from '../safety/transport-diagnostic.js';
 export class HeartbeatScheduler {
     deps;
     lastKey;
@@ -33,8 +34,8 @@ export class HeartbeatScheduler {
             this.lastKey = key;
             this.lastSentAt = now;
         }
-        catch {
-            this.report("HEARTBEAT_SEND_FAILED");
+        catch (error) {
+            this.report("RUNNER_HEARTBEAT_SEND_FAILED", transportDiagnostic(error));
         }
     }
     /** Keeps ticking until stop(). The first tick comes one interval in: the caller sends the first heartbeat itself. */
@@ -54,9 +55,9 @@ export class HeartbeatScheduler {
         clearTimeout(this.timer);
         this.release();
     }
-    report(code) {
+    report(code, diagnostic) {
         try {
-            this.deps.reportError?.(code);
+            this.deps.reportError?.(code, diagnostic);
         }
         catch { /* Logging cannot stop heartbeats. */ }
     }

package/dist/src/daemon/runtime.js

@@ -103,7 +103,9 @@ export async function buildDaemon(input) {
                 launchGrant: job.launchGrant, workLoopId: job.workLoopId, checkoutPath: job.checkoutPath,
             }, signal),
             publicationRecoveryContext: bindingId => gateway.exportLocalPublicationRecoveryContext(bindingId),
-            syncPublicationCursor: (bindingId, cursor) => gateway.syncLocalPublicationCursor(bindingId, cursor),
+            syncPublicationCursor: (bindingId, cursor, job, receipt) => gateway.syncLocalPublicationCursor(bindingId, cursor, job, receipt),
+            confirmServerPublicationCompletion: (bindingId, cursor, job, receipt) => gateway.confirmServerPublicationCompletion(bindingId, cursor, job, receipt),
+            releaseServerCompletedJob: async (jobId) => { await production?.releaseJob(jobId); pendingCodexClaim = undefined; registeredCodexJob = undefined; },
             readCommands: (bindingId, cursor, signal) => gateway.readCommands(bindingId, cursor, signal),
             acknowledgeCommand: (bindingId, sequence, signal) => gateway.acknowledgeCommand(bindingId, sequence, signal),
             appendEvent: (bindingId, event) => gateway.appendEvent(bindingId, event),
@@ -217,7 +219,7 @@ export async function buildDaemon(input) {
             };
         },
         send: async (payload) => { await gateway.heartbeatLocalRunner(payload); },
-        reportError: code => { process.stderr.write(`${JSON.stringify({ event: "heartbeat_failed", code })}\n`); },
+        reportError: (code, diagnostic) => { process.stderr.write(`${JSON.stringify({ event: "heartbeat_failed", code, heartbeat_channel: "runner", timestamp: new Date().toISOString(), ...diagnostic })}\n`); },
     });
     const stopping = new AbortController();
     const closureAcks = new PendingClosureAcks();

package/dist/src/gateway-client.js

@@ -1,3 +1,5 @@
+import { publicationError } from './publication/failure.js';
+import { issueTransportDiagnostic } from './safety/transport-diagnostic.js';
 import { createHash } from "node:crypto";
 import { v5 as uuidv5 } from "uuid";
 import { bindingApprovalIdFromEnv, redact } from "./config.js";
@@ -173,6 +175,8 @@ export class McpGatewayClient {
         throw new Error("No token provider or static token configured");
     }
     async callTool(name, args, signal) {
+        const started = performance.now();
+        let httpStatus;
         let failureCode = "GATEWAY_TRANSPORT_ERROR";
         try {
             const token = await this.resolveToken();
@@ -183,6 +187,7 @@ export class McpGatewayClient {
                 headers: { Authorization: `Bearer ${token}`, "content-type": "application/json" },
                 body: JSON.stringify({ jsonrpc: "2.0", id: ++this.requestId, method: "tools/call", params: { name, arguments: args } }),
             });
+            httpStatus = response.status;
             signal?.throwIfAborted();
             if (!response.ok) {
                 failureCode = `GATEWAY_HTTP_${response.status}`;
@@ -222,7 +227,9 @@ export class McpGatewayClient {
             }
             const leaseToken = this.context?.leaseToken ?? this.initialLeaseToken ?? "";
             sanitized = redact(sanitized, leaseToken);
-            throw new GatewayToolError(redact(sanitized, this.bindingApprovalId ?? ""), name, failureCode);
+            const wrapped = new GatewayToolError(redact(sanitized, this.bindingApprovalId ?? ""), name, failureCode);
+            issueTransportDiagnostic(wrapped, error, performance.now() - started, httpStatus);
+            throw wrapped;
         }
     }
     async resolveCompatibility(input) {
@@ -619,26 +626,85 @@ export class McpGatewayClient {
     }
     /** Account for the server-authored verification event before appending a
      * terminal event. Never infer a cursor from model output or a local counter. */
-    async syncLocalPublicationCursor(bindingId, afterSequence) {
-        const page = await this.callTool('agent_runtime_events_read', {
-            binding_id: bindingId, after_sequence: afterSequence, limit: 100,
-        });
-        const events = page.events ?? [];
-        if (page.terminal || events.length === 0 || events.length >= 100)
-            throw new Error('LOCAL_PUBLICATION_EVENT_CURSOR_REJECTED');
-        let cursor = afterSequence, verified = false;
-        for (const event of events) {
-            if (!Number.isSafeInteger(event.sequence) || event.sequence !== cursor + 1 || isTerminalEventType(String(event.event_type)))
-                throw new Error('LOCAL_PUBLICATION_EVENT_CURSOR_REJECTED');
-            cursor = event.sequence;
-            const proof = event.payload?.local_publication;
-            if (event.event_type === 'test_result' && event.stage === 'local_publication_verification' && typeof proof?.gateway_mac === 'string' && /^[a-f0-9]{64}$/.test(proof.gateway_mac))
-                verified = true;
+    async syncLocalPublicationCursor(bindingId, afterSequence, job, receipt) {
+        const reject = () => new Error('LOCAL_PUBLICATION_EVENT_CURSOR_REJECTED');
+        const mode = nested(job?.taskPackage, 'local_fix_scope.verification_mode');
+        if (!Number.isSafeInteger(afterSequence) || afterSequence < 0 || (mode !== undefined && !['gateway_ci_v1', 'gateway_publish_v1'].includes(String(mode))) || receipt?.status !== 'completed' || receipt.verification_mode !== mode)
+            throw reject();
+        const context = (await this.localPublicationContext({ jobId: job.id, generation: job.generation, leaseToken: job.leaseToken, launchGrant: job.launchGrant, bindingId })).context;
+        const expected = { binding_id: bindingId, runner_id: this.runnerId, job_id: job.id, generation: job.generation, work_loop_id: job.workLoopId, attempt_id: nested(job.taskPackage, 'local_fix_scope.attempt_id'), repository_key: nested(job.taskPackage, 'repository.key'), base_commit_sha: nested(job.taskPackage, 'repository.base_commit_sha'), working_branch: nested(job.taskPackage, 'repository.working_branch'), contract_fingerprint: job.gatewayContractFingerprint, task_package_fingerprint: job.gatewayTaskPackageFingerprint, launch_fingerprint: job.launchFingerprint };
+        if (!context || Object.entries(expected).some(([k, v]) => v === undefined || v === '' || context[k] !== v))
+            throw reject();
+        const identity = [...Object.keys(expected), 'actor_id', 'execution_contract_id', 'repository_lease_id'];
+        if (identity.some(k => k === 'generation' ? !Number.isSafeInteger(context[k]) : typeof context[k] !== 'string' || !context[k]))
+            throw reject();
+        const hashes = ['candidate_fingerprint', 'snapshot_fingerprint', 'verification_fingerprint', 'diff_hash', 'changed_file_manifest_hash'];
+        if (hashes.some(k => typeof receipt[k] !== 'string' || !/^[a-f0-9]{64}$/.test(receipt[k])))
+            throw reject();
+        const page = await this.callTool('agent_runtime_events_read', { binding_id: bindingId, after_sequence: afterSequence, limit: 100 });
+        const events = page.events;
+        if (page.terminal || !Array.isArray(events) || events.length === 0 || events.length >= 100)
+            throw reject();
+        let cursor = afterSequence, proofs = 0;
+        for (const e of events) {
+            if (!Number.isSafeInteger(e.sequence) || e.sequence !== cursor + 1 || isTerminalEventType(String(e.event_type)))
+                throw reject();
+            cursor = e.sequence;
+            const proof = e.payload?.local_publication;
+            if (!proof || typeof proof !== 'object' || Array.isArray(proof) || identity.some(k => proof[k] !== context[k]) || hashes.some(k => proof[k] !== receipt[k]) || proof.verification_mode !== mode || typeof proof.gateway_mac !== 'string' || !/^[a-f0-9]{64}$/.test(proof.gateway_mac))
+                throw reject();
+            const publish = mode === 'gateway_publish_v1';
+            if (e.event_type !== (publish ? 'progress' : 'test_result') || !(publish ? e.stage === 'server_publication' : mode === 'gateway_ci_v1' ? ['server_ci_verification', 'local_publication_verification'].includes(String(e.stage)) : e.stage === 'local_publication_verification') || proof.verification_status !== (publish ? 'unverified' : 'passed') || (publish && nested(proof, 'ci.status') !== 'not_run'))
+                throw reject();
+            proofs++;
         }
-        if (!verified)
-            throw new Error('LOCAL_PUBLICATION_EVENT_CURSOR_REJECTED');
+        if (proofs !== 1)
+            throw reject();
         return cursor;
     }
+    /** Read-only acknowledgement of Route B's atomic server completion.
+     * No lease renewal, replay or publication write is authorized here. Retained context
+     * identifies the server-issued binding; its ID is not the client session UUID. */
+    async confirmServerPublicationCompletion(bindingId, afterSequence, job, receipt) {
+        if (nested(job.taskPackage, 'local_fix_scope.verification_mode') !== 'gateway_publish_v1')
+            return false;
+        try {
+            const context = this.requireContext(bindingId);
+            if (context.jobFence?.job_id !== job.id || context.jobFence?.generation !== job.generation)
+                throw Error();
+            if (!Number.isSafeInteger(job.generation) || job.generation < 1 || typeof job.id !== 'string' || !job.id
+                || !Number.isSafeInteger(afterSequence) || afterSequence < 0 || receipt.status !== 'completed' || receipt.verification_mode !== 'gateway_publish_v1' || receipt.verification_status !== 'unverified' || nested(receipt, 'ci.status') !== 'not_run'
+                || typeof receipt.publication_id !== 'string' || !receipt.publication_id || typeof receipt.commit_sha !== 'string' || !/^[a-f0-9]{40}$/.test(receipt.commit_sha) || typeof receipt.pr_url !== 'string' || !receipt.pr_url)
+                throw Error();
+            const page = await this.callTool('agent_runtime_events_read', { binding_id: bindingId, after_sequence: afterSequence, limit: 100 });
+            const events = page.events;
+            if (typeof page.terminal !== 'boolean' || !Array.isArray(events) || events.length >= 100)
+                throw Error();
+            let cursor = afterSequence;
+            for (const e of events) {
+                if (!Number.isSafeInteger(e.sequence) || e.sequence !== cursor + 1)
+                    throw Error();
+                cursor = e.sequence;
+            }
+            if (page.next_cursor !== undefined && page.next_cursor !== cursor)
+                throw Error();
+            const terminals = events.filter(e => ['completed', 'failed', 'blocked', 'cancelled'].includes(String(e.event_type)));
+            if (!page.terminal) {
+                if (terminals.length)
+                    throw Error();
+                return false;
+            }
+            const last = events.at(-1), payload = last?.payload;
+            if (terminals.length !== 1 || terminals[0] !== last || last?.event_type !== 'completed' || !payload || payload.provenance !== 'server_reconciliation' || payload.reason !== 'completed_publication_without_terminal'
+                || payload.job_id !== job.id || payload.generation !== job.generation || !Number.isSafeInteger(payload.generation)
+                || ['publication_id', 'commit_sha', 'pr_url'].some(k => payload[k] !== receipt[k]))
+                throw Error();
+            return true;
+        }
+        catch (error) {
+            throw publicationError('server_completion', 'LOCAL_FIX_SERVER_COMPLETION_REJECTED', true, error);
+        }
+    }
     /** Host-only publication envelope. This client is never a model MCP relay. */
     localPublicationFence(input) {
         return { job_id: input.jobId, generation: input.generation, lease_token: input.leaseToken,
@@ -650,7 +716,7 @@ export class McpGatewayClient {
     }
     async restoreLocalPublicationRecoveryContext(input, stored, terminalReplay = false) {
         if (terminalReplay) {
-            if (stored.bindingId !== input.bindingId || typeof stored.leaseToken !== 'string' || !stored.leaseToken)
+            if (stored.bindingId !== input.bindingId || nested(stored, 'jobFence.job_id') !== input.jobId || nested(stored, 'jobFence.generation') !== input.generation || typeof stored.leaseToken !== 'string' || !stored.leaseToken)
                 throw new Error('LOCAL_PUBLICATION_RECOVERY_CONTEXT_REJECTED');
             this.context = structuredClone(stored);
             return;

package/dist/src/platform/macos/launchd.js

@@ -1,9 +1,14 @@
 import { access, chmod, mkdir, rename, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { execFile } from "node:child_process";
+import { setTimeout as delay } from "node:timers/promises";
 import { promisify } from "node:util";
 const execFileAsync = promisify(execFile);
 export const LAUNCHD_LABEL = "com.mtec.ai-local-runner";
+const BOOTOUT_POLLS = 40;
+const BOOTOUT_POLL_MS = 250;
+const BOOTSTRAP_ATTEMPTS = 3;
+const BOOTSTRAP_RETRY_MS = 1000;
 function xml(value) {
     return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
 }
@@ -45,7 +50,38 @@ export class LaunchdService {
         const run = this.deps.run ?? defaultRun;
         await (this.deps.writeAtomic ?? defaultWriteAtomic)(this.plistPath, this.render(executablePath, stateRoot), 0o600);
         await run("/bin/launchctl", ["bootout", `gui/${this.deps.uid}/${LAUNCHD_LABEL}`]).catch(() => undefined);
-        await run("/bin/launchctl", ["bootstrap", `gui/${this.deps.uid}`, this.plistPath]);
+        await this.waitUntilUnloaded();
+        await this.bootstrapAfterBootout();
+    }
+    // bootout returns before launchd has removed a service whose process is still exiting, and a
+    // bootstrap in that window fails with "5: Input/output error". The service is gone afterwards,
+    // so a setup rerun on a Mac with the runner loaded left it offline (runner 0.1.57, 2026-10-26).
+    async waitUntilUnloaded() {
+        const sleep = this.deps.sleep ?? delay;
+        for (let poll = 0; poll < BOOTOUT_POLLS; poll++) {
+            if (!(await this.status()).loaded)
+                return;
+            await sleep(BOOTOUT_POLL_MS);
+        }
+    }
+    async bootstrapAfterBootout() {
+        const run = this.deps.run ?? defaultRun;
+        for (let attempt = 1;; attempt++) {
+            try {
+                await run("/bin/launchctl", ["bootstrap", `gui/${this.deps.uid}`, this.plistPath]);
+                return;
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                const ioError = /Bootstrap failed: 5: Input\/output error/.exec(message);
+                if (!ioError)
+                    throw error;
+                if (attempt === BOOTSTRAP_ATTEMPTS) {
+                    throw new Error(`launchd did not load the runner service: ${ioError[0]} (${attempt} attempts). Rerun npx mtech-ai-local-runner setup.`);
+                }
+                await (this.deps.sleep ?? delay)(BOOTSTRAP_RETRY_MS);
+            }
+        }
     }
     async uninstall() {
         await (this.deps.run ?? defaultRun)("/bin/launchctl", ["bootout", `gui/${this.deps.uid}/${LAUNCHD_LABEL}`])

package/dist/src/publication/failure.js

@@ -1,14 +1,15 @@
+import { transportDiagnostic } from '../safety/transport-diagnostic.js';
 import { PublicationOutcomeUnknownError } from './publisher.js';
-export const PUBLICATION_STEPS = ['validation_report', 'current_fence', 'snapshot_observe', 'snapshot_materialize', 'candidate_limits', 'delta_format', 'delta_modes', 'delta_scope', 'candidate_files', 'journal', 'security_receipt', 'stage', 'advance', 'result', 'cleanup'];
-export const PUBLICATION_CODES = ['LOCAL_FIX_CHANGE_LIMIT_REJECTED', 'LOCAL_FIX_PAYLOAD_LIMIT_REJECTED', 'LOCAL_FIX_CHANGE_MEASUREMENT_REJECTED', 'LOCAL_FIX_CHECK_REJECTED', 'LOCAL_FIX_REPORT_REJECTED', 'LOCAL_FIX_DIFF_LIMIT_REJECTED', 'LOCAL_FIX_FILE_COUNT_REJECTED', 'LOCAL_FIX_FILE_LIMIT_REJECTED', 'LOCAL_FIX_FILE_ENCODING_REJECTED', 'LOCAL_FIX_PUBLICATION_OUTCOME_UNKNOWN', 'LOCAL_FIX_CLEANUP_FAILED'];
+export const PUBLICATION_STEPS = ['validation_report', 'current_fence', 'snapshot_observe', 'snapshot_materialize', 'candidate_limits', 'delta_format', 'delta_modes', 'delta_scope', 'candidate_files', 'journal', 'security_receipt', 'stage', 'advance', 'result', 'cleanup', 'cursor_sync', 'server_completion'];
+export const PUBLICATION_CODES = ['LOCAL_FIX_CHANGE_LIMIT_REJECTED', 'LOCAL_FIX_PAYLOAD_LIMIT_REJECTED', 'LOCAL_FIX_CHANGE_MEASUREMENT_REJECTED', 'LOCAL_FIX_CHECK_REJECTED', 'LOCAL_FIX_REPORT_REJECTED', 'LOCAL_FIX_DIFF_LIMIT_REJECTED', 'LOCAL_FIX_FILE_COUNT_REJECTED', 'LOCAL_FIX_FILE_LIMIT_REJECTED', 'LOCAL_FIX_FILE_ENCODING_REJECTED', 'LOCAL_FIX_PUBLICATION_OUTCOME_UNKNOWN', 'LOCAL_FIX_CLEANUP_FAILED', 'LOCAL_FIX_PUBLICATION_CURSOR_REJECTED', 'LOCAL_FIX_SERVER_COMPLETION_REJECTED'];
 const issued = new WeakMap();
 const cleanupFailures = new WeakSet();
 /** Host vocabulary only; serialized fields/messages never carry diagnostic authority. */
-export function publicationError(step, code = 'LOCAL_FIX_CHECK_REJECTED', unknown = false) {
+export function publicationError(step, code = 'LOCAL_FIX_CHECK_REJECTED', unknown = false, origin) {
     const safeStep = PUBLICATION_STEPS.includes(step) ? step : 'result';
     const safeCode = PUBLICATION_CODES.includes(code) ? code : 'LOCAL_FIX_CHECK_REJECTED';
     const e = unknown ? new PublicationOutcomeUnknownError() : new Error('LOCAL_FIX_SERVER_CI_REJECTED');
-    issued.set(e, Object.freeze({ stage: 'local_fix_publication', code: safeCode, publication_step: safeStep }));
+    issued.set(e, Object.freeze({ stage: 'local_fix_publication', code: safeCode, publication_step: safeStep, ...transportDiagnostic(origin) }));
     return e;
 }
 export function trustedPublicationFailure(error) { const d = issued.get(error); return d ? { ...d } : undefined; }

package/dist/src/publication/recovery.js

@@ -1,5 +1,6 @@
 import { fingerprint } from '../daemon/execution-coordinator.js';
 import { PROTOCOL_VERSION } from '../protocol.js';
+import { publicationError } from './failure.js';
 import { PublicationOutcomeUnknownError } from './publisher.js';
 /** Explicit one-Job operation. No adapter factory/model/claim/automatic retry.
  * Existing publication intents reconcile before effects; expired/revoked server
@@ -12,12 +13,45 @@ export async function recoverLocalFixPublication(input) {
     if (!job || job.id !== s.jobId || job.generation !== s.generation || job.leaseToken !== s.leaseToken || bindingId !== s.bindingId || event?.eventType !== 'completed' || typeof r.checkoutPath !== 'string' || job.gatewayTaskPackageFingerprint !== fingerprint(job.taskPackage))
         throw Error('LOCAL_PUBLICATION_RECOVERY_REJECTED');
     const fence = { jobId: job.id, generation: job.generation, leaseToken: job.leaseToken, launchGrant: job.launchGrant, bindingId };
+    const confirmed = async (receipt, cursor = s.eventCursor ?? 0) => {
+        if (!receipt || !input.gateway.confirmServerPublicationCompletion || job.taskPackage.local_fix_scope?.verification_mode !== 'gateway_publish_v1')
+            return false;
+        return input.gateway.confirmServerPublicationCompletion(bindingId, cursor, job, receipt);
+    };
+    if (s.phase === 'publication_terminal_pending') {
+        const pending = s.publicationTerminal;
+        if (!pending || pending.event.bindingId !== bindingId || pending.event.eventType !== 'completed' || pending.completion.jobId !== job.id || pending.completion.generation !== job.generation || pending.completion.leaseToken !== job.leaseToken)
+            throw Error('LOCAL_PUBLICATION_RECOVERY_REJECTED');
+    }
+    const savedReceipt = (s.phase === 'publication_terminal_pending' ? s.publicationTerminal?.completion.result.local_fix_publication : r.completedPublication);
+    // Rehydrate only the recorded identity before a read-only terminal check.
+    // No live fence renewal or publication effect is permitted by this branch.
+    if (savedReceipt && input.gateway.confirmServerPublicationCompletion && job.taskPackage.local_fix_scope?.verification_mode === 'gateway_publish_v1')
+        await input.gateway.restoreLocalPublicationRecoveryContext(fence, r.gatewayContext, true);
+    if (await confirmed(savedReceipt)) {
+        await input.state.clear();
+        return;
+    }
+    const appendOrConfirm = async (event, receipt) => {
+        try {
+            await input.gateway.appendEvent(bindingId, event);
+            return false;
+        }
+        catch (error) {
+            if (await confirmed(receipt, event.sequence - 1))
+                return true;
+            throw error;
+        }
+    };
     if (s.phase === 'publication_terminal_pending') {
         const pending = s.publicationTerminal;
         if (!pending || pending.event.bindingId !== bindingId || pending.event.eventType !== 'completed' || pending.completion.jobId !== job.id || pending.completion.generation !== job.generation || pending.completion.leaseToken !== job.leaseToken)
             throw Error('LOCAL_PUBLICATION_RECOVERY_REJECTED');
         await input.gateway.restoreLocalPublicationRecoveryContext(fence, r.gatewayContext, true);
-        await input.gateway.appendEvent(bindingId, pending.event);
+        if (await appendOrConfirm(pending.event, savedReceipt)) {
+            await input.state.clear();
+            return;
+        }
         await input.state.save({ ...s, phase: 'terminal_pending', completionRequest: pending.completion });
         await input.gateway.completeLocalJob(pending.completion);
         await input.state.clear();
@@ -33,14 +67,38 @@ export async function recoverLocalFixPublication(input) {
     try {
         session = await input.host.prepare({ job, checkoutPath: r.checkoutPath, bindingId, lifecycle: { isFrozen: () => true, isCurrent: () => current, securityReceipt: () => r.securityReceipt } });
         const receipt = await session.finalize(event);
+        const completedState = { ...s, publicationRecovery: { ...r, completedPublication: structuredClone(receipt) } };
+        try {
+            await input.state.save(completedState);
+        }
+        catch (error) {
+            throw publicationError('journal', 'LOCAL_FIX_PUBLICATION_OUTCOME_UNKNOWN', true, error);
+        }
+        if (await confirmed(receipt)) {
+            await session.close();
+            session = undefined;
+            await input.state.clear();
+            return;
+        }
         if (heartbeatError)
             throw new PublicationOutcomeUnknownError();
-        const cursor = await input.gateway.syncLocalPublicationCursor(bindingId, s.eventCursor ?? 0);
+        let cursor;
+        try {
+            cursor = await input.gateway.syncLocalPublicationCursor(bindingId, s.eventCursor ?? 0, job, receipt);
+        }
+        catch (error) {
+            throw publicationError('cursor_sync', 'LOCAL_FIX_PUBLICATION_CURSOR_REJECTED', true, error);
+        }
         const payload = { ...event.payload, local_fix_publication: receipt, security_receipt: r.securityReceipt, diff_hash: receipt.diff_hash, changed_file_manifest_hash: receipt.changed_file_manifest_hash };
         const normalized = { protocolVersion: PROTOCOL_VERSION, bindingId, sequence: cursor + 1, eventType: 'completed', summary: event.summary, payload, idempotencyKey: `local-job:${job.id}:${job.generation}:event:${cursor + 1}`, occurredAt: new Date().toISOString() };
         const completionRequest = { jobId: job.id, generation: job.generation, leaseToken: job.leaseToken, status: 'completed', result: { binding_id: bindingId, event_type: 'completed', summary: event.summary, local_fix_publication: receipt, security_receipt: r.securityReceipt } };
-        await input.state.save({ ...s, phase: 'publication_terminal_pending', publicationTerminal: { event: normalized, completion: completionRequest } });
-        await input.gateway.appendEvent(bindingId, normalized);
+        await input.state.save({ ...completedState, phase: 'publication_terminal_pending', publicationTerminal: { event: normalized, completion: completionRequest } });
+        if (await appendOrConfirm(normalized, receipt)) {
+            await session.close();
+            session = undefined;
+            await input.state.clear();
+            return;
+        }
         await input.state.save({ ...s, phase: 'terminal_pending', completionRequest });
         await input.gateway.completeLocalJob(completionRequest);
         await input.state.clear();

package/dist/src/safety/execution-failure.js

@@ -1,3 +1,4 @@
+import { transportDiagnostic } from './transport-diagnostic.js';
 import { trustedPublicationCleanupFailure, trustedPublicationFailure } from '../publication/failure.js';
 import { trustedServerCiFailure } from '../publication/server-ci-error.js';
 import { trustedLaunchObservation } from '../process/owned-launch-observer.js';
@@ -29,6 +30,11 @@ export const STARTUP_OBSERVATIONS = Object.freeze([
     'cleanup_guardian_root_exited', 'cleanup_guardian_root_running',
 ]);
 const issued = new WeakMap();
+export function jobHeartbeatError(error) {
+    const wrapped = new Error('JOB_HEARTBEAT_FAILED');
+    issued.set(wrapped, Object.freeze({ stage: 'heartbeat', code: 'JOB_HEARTBEAT_FAILED', heartbeat_channel: 'job', ...transportDiagnostic(error) }));
+    return wrapped;
+}
 export function executionFailure(error, stage, fallback = 'EXECUTION_FAILED') {
     if (error && typeof error === 'object') {
         const ci = trustedServerCiFailure(error);

package/dist/src/safety/transport-diagnostic.js

@@ -0,0 +1,15 @@
+const issued = new WeakMap();
+const allowed = new Set(['ECONNRESET', 'ECONNREFUSED', 'ETIMEDOUT', 'ENOTFOUND', 'EAI_AGAIN', 'EPIPE', 'ENETUNREACH', 'EHOSTUNREACH', 'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_HEADERS_TIMEOUT', 'UND_ERR_BODY_TIMEOUT', 'UND_ERR_SOCKET', 'ABORT_ERR']);
+function own(value, key) { try {
+    return value && typeof value === 'object' ? Object.getOwnPropertyDescriptor(value, key)?.value : undefined;
+}
+catch {
+    return undefined;
+} }
+export function issueTransportDiagnostic(target, error, elapsed, status) {
+    const code = own(error, 'code') ?? own(own(error, 'cause'), 'code');
+    const d = { elapsed_ms: Number.isFinite(elapsed) ? Math.min(86400000, Math.max(0, Math.trunc(elapsed))) : 0, ...(typeof status === 'number' && Number.isInteger(status) && status >= 100 && status <= 599 ? { http_status: status } : {}), ...(typeof code === 'string' && allowed.has(code) ? { os_error: code } : {}) };
+    issued.set(target, Object.freeze(d));
+}
+export function transportDiagnostic(error) { if (!error || typeof error !== 'object')
+    return; const d = issued.get(error); return d ? { ...d } : undefined; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mtech-ai-local-runner",
-  "version": "0.1.57",
+  "version": "0.1.59",
   "private": false,
   "license": "UNLICENSED",
   "bin": {