mtech-ai-local-runner 0.1.30 → 0.1.32

package/dist/src/daemon/manual-codex.js

@@ -36,9 +36,10 @@ export async function runManualCodexJob(input, deps) {
         let leaseExpires = claim.job.lease_expires_at;
         if (!Number.isSafeInteger(leaseExpires))
             throw Error('MANUAL_PILOT_LEASE_MISSING');
-        const job = { id: claim.job.id, generation: claim.job.generation, workLoopId: claim.job.work_loop_id, leaseToken: claim.lease_token, launchGrant: claim.launch_grant, taskPackage: claim.task_package, launchFingerprint: claim.job.launch_fingerprint, gatewayContractFingerprint: claim.contract_fingerprint, gatewayTaskPackageFingerprint: claim.task_package_fingerprint };
+        const job = { id: claim.job.id, generation: claim.job.generation, leaseExpiresAt: claim.job.lease_expires_at, workLoopId: claim.job.work_loop_id, leaseToken: claim.lease_token, launchGrant: claim.launch_grant, taskPackage: claim.task_package, launchFingerprint: claim.job.launch_fingerprint, gatewayContractFingerprint: claim.contract_fingerprint, gatewayTaskPackageFingerprint: claim.task_package_fingerprint };
         await state.save({ jobId: job.id, generation: job.generation, leaseToken: job.leaseToken, phase: 'claimed' });
         let result = { jobId: job.id, status: 'unacknowledged' };
+        const confirmJobLease = (j, expires) => { host?.heartbeat(j.id, j.generation, expires); leaseExpires = expires; claim.job.lease_expires_at = expires; };
         const coordinator = new ExecutionCoordinator({ state, workspaces: deps?.workspaces ?? new WorkspaceManager({ root: input.workspaceRoot, git: new GitClient() }), terminalEvidenceCollector: deps?.terminalEvidenceCollector ?? buildTerminalEvidenceCollector(),
             reportExecutionFailure: d => process.stderr.write(JSON.stringify({ event: 'manual_execution_failed', ...d }) + '\n'),
             reportPreparationFailure: d => process.stderr.write(JSON.stringify({ event: 'manual_preparation_failed', ...d }) + '\n'),
@@ -61,8 +62,14 @@ export async function runManualCodexJob(input, deps) {
                     adapter = await plugin.create(options);
                     return adapter;
                 } },
-            gateway: { shadow: j => input.gateway.localJobShadow({ workLoopId: j.workLoopId, contractFingerprint: j.gatewayContractFingerprint, taskPackageFingerprint: j.gatewayTaskPackageFingerprint }), createBinding: j => input.gateway.createLocalJobBinding({ jobId: j.id, generation: j.generation, jobLeaseToken: j.leaseToken, launchGrant: j.launchGrant, workLoopId: j.workLoopId, checkoutPath: j.checkoutPath }), appendEvent: (id, event) => input.gateway.appendEvent(id, event), readCommands: (id, cursor) => input.gateway.readCommands(id, cursor), acknowledgeCommand: (id, sequence) => input.gateway.acknowledgeCommand(id, sequence), async heartbeat(id, j) { await input.gateway.heartbeat(id); const renewed = await input.gateway.heartbeatLocalJob({ jobId: j.id, generation: j.generation, leaseToken: j.leaseToken }); if (!renewed?.job || renewed.job.id !== job.id || renewed.job.generation !== job.generation)
-                    throw Error('MANUAL_PILOT_LEASE_FENCE'); leaseExpires = renewed.job.lease_expires_at; host?.heartbeat(job.id, job.generation, leaseExpires); }, async complete(value) { await input.gateway.completeLocalJob(value); result = { jobId: value.jobId, status: value.status }; } },
+            gateway: {
+                renewJob: (j, signal) => input.gateway.heartbeatLocalJob({ jobId: j.id, generation: j.generation, leaseToken: j.leaseToken }, signal), confirmJobLease,
+                shadow: (j, signal) => input.gateway.localJobShadow({ workLoopId: j.workLoopId, contractFingerprint: j.gatewayContractFingerprint, taskPackageFingerprint: j.gatewayTaskPackageFingerprint }, signal),
+                createBinding: (j, signal) => input.gateway.createLocalJobBinding({ jobId: j.id, generation: j.generation, jobLeaseToken: j.leaseToken, launchGrant: j.launchGrant, workLoopId: j.workLoopId, checkoutPath: j.checkoutPath }, signal),
+                appendEvent: (id, event) => input.gateway.appendEvent(id, event), readCommands: (id, cursor, signal) => input.gateway.readCommands(id, cursor, signal), acknowledgeCommand: (id, sequence, signal) => input.gateway.acknowledgeCommand(id, sequence, signal),
+                async heartbeat(id, j, signal) { await input.gateway.heartbeat(id, signal); signal.throwIfAborted(); return input.gateway.heartbeatLocalJob({ jobId: j.id, generation: j.generation, leaseToken: j.leaseToken }, signal); },
+                async complete(value) { await input.gateway.completeLocalJob(value); result = { jobId: value.jobId, status: value.status }; }
+            },
         });
         await coordinator.execute(job);
         return result;

package/dist/src/daemon/preparation-lease.js

@@ -0,0 +1,142 @@
+import { GatewayToolError } from '../gateway-client.js';
+function requireJobIdentity(job) {
+    if (typeof job.id !== 'string' || !job.id.trim() || !Number.isSafeInteger(job.generation) || job.generation < 1) {
+        throw new GatewayToolError('Job claim identity is invalid', 'local_agent_jobs_wait', 'JOB_LEASE_FENCE_INVALID');
+    }
+}
+export function validateJobLease(receipt, job, allowRunning, allowReviewPending = allowRunning) {
+    requireJobIdentity(job);
+    const renewed = receipt?.job;
+    if (!renewed || renewed.id !== job.id || renewed.generation !== job.generation
+        || !(allowRunning ? ['claimed', 'shadowing', 'running', ...(allowReviewPending ? ['review_pending'] : [])] : ['claimed', 'shadowing']).includes(renewed.status)
+        || !Number.isSafeInteger(renewed.lease_expires_at) || renewed.lease_expires_at * 1000 <= Date.now()) {
+        throw new GatewayToolError('Job lease fence is invalid', 'local_agent_job_heartbeat', 'JOB_LEASE_FENCE_INVALID');
+    }
+    return renewed.lease_expires_at;
+}
+/** Preparation-only rolling Job fence. The Work Loop remains Gateway-owned. */
+export class PreparationLease {
+    job;
+    deadline;
+    renew;
+    confirmed;
+    controller = new AbortController();
+    failure;
+    leaseExpiresAt;
+    bindingStarted = false;
+    stopped = false;
+    schedule;
+    boundary;
+    backoff;
+    pending;
+    rejectAbort;
+    aborted = new Promise((_, reject) => { this.rejectAbort = reject; });
+    constructor(job, deadline, renew, confirmed) {
+        this.job = job;
+        this.deadline = deadline;
+        this.renew = renew;
+        this.confirmed = confirmed;
+        void this.aborted.catch(() => { });
+        requireJobIdentity(job);
+        if (Number.isSafeInteger(job.leaseExpiresAt))
+            this.leaseExpiresAt = job.leaseExpiresAt;
+        this.armBoundary();
+    }
+    get signal() { return this.controller.signal; }
+    get hasLiveFence() { return this.leaseExpiresAt !== undefined && this.leaseExpiresAt * 1000 > Date.now() && (!this.failure || this.failure instanceof PreparationDeadlineError); }
+    assert() {
+        if (this.failure)
+            throw this.failure;
+        if (Date.now() >= this.deadline)
+            this.fail(new PreparationDeadlineError());
+        if (this.leaseExpiresAt !== undefined && Date.now() >= this.leaseExpiresAt * 1000)
+            this.fail(new Error('Job lease expired during preparation'));
+        if (this.failure)
+            throw this.failure;
+    }
+    fail(error) {
+        if (this.failure)
+            return;
+        this.failure = error;
+        this.clearTimers();
+        this.controller.abort();
+        this.rejectAbort(error);
+    }
+    async step(operation, late) {
+        this.assert();
+        const work = operation().then(async (value) => {
+            if (this.signal.aborted) {
+                await late?.(value);
+                this.assert();
+            }
+            this.assert();
+            return value;
+        });
+        return Promise.race([work, this.aborted]);
+    }
+    start() { return this.renewOnce(); }
+    beginBinding() { this.assert(); this.bindingStarted = true; }
+    async stop() {
+        this.stopped = true;
+        if (this.schedule)
+            clearTimeout(this.schedule);
+        try {
+            if (this.pending)
+                await this.pending;
+            this.assert();
+        }
+        finally {
+            this.clearTimers();
+        }
+    }
+    dispose() { this.stopped = true; this.clearTimers(); this.controller.abort(); }
+    clearTimers() { if (this.schedule)
+        clearTimeout(this.schedule); if (this.boundary)
+        clearTimeout(this.boundary); if (this.backoff)
+        clearTimeout(this.backoff); }
+    armBoundary() {
+        if (this.boundary)
+            clearTimeout(this.boundary);
+        const expires = this.leaseExpiresAt === undefined ? this.deadline : Math.min(this.deadline, this.leaseExpiresAt * 1000);
+        this.boundary = setTimeout(() => this.fail(expires >= this.deadline ? new PreparationDeadlineError() : new Error('Job lease expired during preparation')), Math.max(0, expires - Date.now()));
+        this.boundary.unref?.();
+    }
+    renewOnce() {
+        if (this.pending)
+            return this.pending;
+        const run = async () => {
+            let retries = 0;
+            while (true) {
+                this.assert();
+                try {
+                    const receipt = await Promise.race([this.renew(this.signal), this.aborted]);
+                    this.assert();
+                    const expiry = validateJobLease(receipt, this.job, this.bindingStarted, false);
+                    this.confirmed?.(expiry);
+                    this.leaseExpiresAt = expiry;
+                    if (!this.stopped)
+                        this.armBoundary();
+                    return;
+                }
+                catch (error) {
+                    this.assert();
+                    const transient = error instanceof GatewayToolError && (error.code === 'GATEWAY_TRANSPORT_ERROR' || /^GATEWAY_HTTP_50[0234]$/.test(error.code));
+                    if (!transient || !this.hasLiveFence || retries >= 3)
+                        throw error;
+                    const delay = Math.min(1000 * 2 ** retries++, 4000);
+                    await this.step(() => new Promise(resolve => { this.backoff = setTimeout(resolve, delay); }));
+                }
+            }
+        };
+        this.pending = run().catch(error => { this.fail(error); throw error; }).finally(() => {
+            this.pending = undefined;
+            if (!this.stopped && !this.signal.aborted) {
+                this.schedule = setTimeout(() => { void this.renewOnce().catch(error => this.fail(error)); }, 30_000);
+                this.schedule.unref?.();
+            }
+        });
+        return this.pending;
+    }
+}
+export class PreparationDeadlineError extends Error {
+}

package/dist/src/daemon/runtime.js

@@ -1,3 +1,4 @@
+import { loadInstalledLocalFixHost } from '../publication/installed-host.js';
 import { createCodexDaemonHost } from '../safety/codex-daemon-host.js';
 import { reconcileTerminalState } from './terminal-recovery.js';
 import { packageVersion } from '../package-version.js';
@@ -25,7 +26,18 @@ export async function buildDaemon(input) {
         throw new Error('CODEX_SUPPORTED_HOST_REQUIRED');
     const production = !input.codexSecurityHost && !input.codexSupportedProbe ? createCodexDaemonHost({ runnerId: input.runnerId, binary: input.env.AI_GATEWAY_LOCAL_RUNNER_CODEX_BINARY ?? 'codex', home: input.env.HOME ?? '', codexHome: input.env.CODEX_HOME, searchPath: input.env.PATH }) : undefined;
     let pendingCodexClaim;
+    let registeredCodexJob;
+    const confirmJobLease = (job, expiresAt) => {
+        if (job.taskPackage.runtime_adapter !== 'codex_cli' || !production)
+            return;
+        if (!pendingCodexClaim?.job || pendingCodexClaim.job.id !== job.id || pendingCodexClaim.job.generation !== job.generation)
+            throw new Error('CODEX_JOB_LEASE_FENCE_MISMATCH');
+        if (registeredCodexJob === job.id)
+            production.heartbeat(job.id, job.generation, expiresAt);
+        pendingCodexClaim.job.lease_expires_at = expiresAt;
+    };
     const gateway = new McpGatewayClient({ mcpUrl: input.gatewayMcpUrl, tokenProvider: input.tokenProvider, runnerId: input.runnerId, fetchFn: input.fetchFn });
+    const localFixHost = input.localFixHost ?? await loadInstalledLocalFixHost({ stateRoot: input.stateRoot, runnerId: input.runnerId, gateway });
     // The same parts the CLI self-test ran before starting this daemon (verifyPackagedHook).
     const hook = packagedHookCommandParts();
     const plugin = new ClaudeCodePlugin({
@@ -45,36 +57,37 @@ export async function buildDaemon(input) {
     const versions = Object.fromEntries(probes.filter((probe) => probe.available && probe.authenticated).map((probe) => [probe.id, probe.version]));
     const state = new FileDaemonStateStore(input.stateRoot);
     const coordinator = new ExecutionCoordinator({
+        localFixHost,
         reportExecutionFailure: (diagnostic) => { process.stderr.write(`${JSON.stringify({ event: "execution_failed", ...diagnostic })}\n`); },
         reportPreparationFailure: (diagnostic) => { process.stderr.write(`${JSON.stringify({ event: "preparation_failed", ...diagnostic })}\n`); },
         terminalEvidenceCollector: buildTerminalEvidenceCollector(),
         gateway: {
-            shadow: (job) => gateway.localJobShadow({ workLoopId: job.workLoopId,
+            renewJob: (job, signal) => gateway.heartbeatLocalJob({ jobId: job.id, generation: job.generation, leaseToken: job.leaseToken }, signal),
+            confirmJobLease,
+            shadow: (job, signal) => gateway.localJobShadow({ workLoopId: job.workLoopId,
                 contractFingerprint: job.gatewayContractFingerprint ?? "",
-                taskPackageFingerprint: job.gatewayTaskPackageFingerprint ?? "" }),
-            createBinding: async (job) => gateway.createLocalJobBinding({
+                taskPackageFingerprint: job.gatewayTaskPackageFingerprint ?? "" }, signal),
+            createBinding: async (job, signal) => gateway.createLocalJobBinding({
                 jobId: job.id, generation: job.generation, jobLeaseToken: job.leaseToken,
                 launchGrant: job.launchGrant, workLoopId: job.workLoopId, checkoutPath: job.checkoutPath,
-            }),
-            readCommands: (bindingId, cursor) => gateway.readCommands(bindingId, cursor),
-            acknowledgeCommand: (bindingId, sequence) => gateway.acknowledgeCommand(bindingId, sequence),
+            }, signal),
+            publicationRecoveryContext: bindingId => gateway.exportLocalPublicationRecoveryContext(bindingId),
+            syncPublicationCursor: (bindingId, cursor) => gateway.syncLocalPublicationCursor(bindingId, cursor),
+            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),
-            heartbeat: async (bindingId, job) => {
-                const [, renewed] = await Promise.all([gateway.heartbeat(bindingId), gateway.heartbeatLocalJob({ jobId: job.id, generation: job.generation, leaseToken: job.leaseToken })]);
-                if (renewed?.job) {
-                    if (renewed.job.id !== job.id || renewed.job.generation !== job.generation)
-                        throw new Error('CODEX_JOB_LEASE_FENCE_MISMATCH');
-                    if (job.taskPackage.runtime_adapter === 'codex_cli')
-                        production?.heartbeat(job.id, job.generation, renewed.job.lease_expires_at);
-                }
+            heartbeat: async (bindingId, job, signal) => {
+                const [, renewed] = await Promise.all([gateway.heartbeat(bindingId, signal), gateway.heartbeatLocalJob({ jobId: job.id, generation: job.generation, leaseToken: job.leaseToken }, signal)]);
+                return renewed;
             },
-            complete: async (result) => { await gateway.completeLocalJob(result); await production?.releaseJob(result.jobId); pendingCodexClaim = undefined; },
+            complete: async (result) => { await gateway.completeLocalJob(result); await production?.releaseJob(result.jobId); pendingCodexClaim = undefined; registeredCodexJob = undefined; },
         },
         registry: { select: async (id, version, options) => {
                 if (production && id === 'codex_cli') {
                     if (!pendingCodexClaim || pendingCodexClaim.job?.id !== options.jobId)
                         throw new Error('CODEX_TRUSTED_CLAIM_REQUIRED');
                     production.registerClaim(pendingCodexClaim);
+                    registeredCodexJob = options.jobId;
                 }
                 return registry.select(id, version, options);
             } },
@@ -102,8 +115,7 @@ export async function buildDaemon(input) {
             await gateway.heartbeatLocalRunner({
                 deviceFingerprint: createHash("sha256").update(`${process.getuid?.() ?? 0}|${runnerDisplayName()}|${input.gatewayMcpUrl}`).digest("hex"),
                 displayName: runnerDisplayName(), packageVersion: packageVersion(),
-                capabilities: probes.map((probe) => ({ adapter: probe.id, version: probe.version,
-                    capabilities: probe.capabilities, authenticated: probe.available && probe.authenticated })),
+                capabilities: localRunnerCapabilities(probes, !!localFixHost, localFixHost?.verificationMode),
             });
         },
         wait: async () => {
@@ -111,12 +123,13 @@ export async function buildDaemon(input) {
             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')
-                pendingCodexClaim = claim;
+                pendingCodexClaim = structuredClone(claim);
             const job = {
                 id: claim.job.id, generation: claim.job.generation, leaseToken: claim.lease_token, launchGrant: claim.launch_grant,
                 workLoopId: claim.job.work_loop_id, taskPackage: claim.task_package,
                 launchFingerprint: claim.job.launch_fingerprint, gatewayContractFingerprint: claim.contract_fingerprint,
                 gatewayTaskPackageFingerprint: claim.task_package_fingerprint,
+                leaseExpiresAt: claim.job.lease_expires_at,
             };
             await state.save({ jobId: job.id, generation: job.generation, leaseToken: job.leaseToken, phase: "claimed" });
             return { status: "claimed", job };
@@ -133,21 +146,37 @@ export async function buildDaemon(input) {
             if (await reconcileTerminalState(previous, { gateway: { complete: request => gateway.completeLocalJob(request) }, state }))
                 return;
             if (await reconcilePreparationState(previous, {
-                complete: (result) => gateway.completeLocalJob(result), clear: () => state.clear(),
+                complete: (result) => gateway.completeLocalJob(result), clear: () => state.clear(), save: receipt => state.save(receipt),
             }))
                 return;
-            await state.clear();
+            throw new Error('Runner state requires authoritative reconciliation');
         },
         poller,
+        reportRecoveryRequired: reason => { process.stderr.write(`${JSON.stringify({ event: 'runner_recovery_required', reason })}\n`); },
     });
     // Model tools have no Gateway relay. Each adapter owns and closes its job endpoint.
-    return { daemon, close: async () => { poller.stop(); await production?.close(); } };
+    return { daemon, close: async () => { daemon.stop(); await production?.close(); } };
 }
 export function runnerDisplayName() { return `${hostname()} local AI`; }
 /** Unknown mutation outcomes halt polling; known failures replay only their terminal receipt. */
 export async function reconcilePreparationState(previous, deps) {
-    if (previous.phase === "binding" || previous.phase === "binding_uncertain") {
-        throw new Error("Binding outcome requires reconciliation before runner polling");
+    if (["publication_pending", "publication_terminal_pending"].includes(previous.phase ?? ""))
+        throw new Error("Publication outcome requires reconciliation before runner polling");
+    if (previous.phase === 'running' || previous.phase === 'reconciling')
+        throw new Error('Executor cleanup requires authoritative reconciliation');
+    if (['claimed', 'shadow', 'binding', 'binding_uncertain'].includes(previous.phase ?? '')) {
+        if (!deps.save)
+            throw new Error('Binding outcome requires reconciliation before runner polling');
+        if (typeof previous.jobId !== 'string' || !previous.jobId.trim() || !Number.isSafeInteger(previous.generation) || Number(previous.generation) < 1 || typeof previous.leaseToken !== 'string' || !previous.leaseToken.trim())
+            throw new Error('Recovery receipt is missing its job fence');
+        const reason = previous.phase === 'binding' || previous.phase === 'binding_uncertain' ? 'binding_outcome_unknown' : 'runner_restarted';
+        // A Job recovery result records client interruption facts. The server closer proves
+        // Job/binding lineage independently and supplies its own server fact reason.
+        const completionRequest = { jobId: previous.jobId, generation: previous.generation, leaseToken: previous.leaseToken, status: reason === 'binding_outcome_unknown' ? 'blocked' : 'failed', result: { reason, recovery: { version: 'local-runner-recovery-v1', phase: previous.phase } } };
+        await deps.save({ jobId: previous.jobId, generation: previous.generation, leaseToken: previous.leaseToken, phase: 'terminal_pending', completionRequest: structuredClone(completionRequest) });
+        await deps.complete(structuredClone(completionRequest));
+        await deps.clear();
+        return true;
     }
     if (!previous.preparationFailure)
         return false;
@@ -159,3 +188,16 @@ export async function reconcilePreparationState(previous, deps) {
     await deps.clear();
     return true;
 }
+/** Vendor capability text cannot claim a host-owned publication facility. */
+export function localRunnerCapabilities(probes, trustedLocalFixHost = false, verificationMode) {
+    return probes.map(probe => {
+        const authenticated = probe.available && probe.authenticated;
+        const capabilities = probe.capabilities.filter(value => value !== 'local_fix_publication_v1' && value !== 'local_fix_gateway_ci_v1');
+        if (trustedLocalFixHost && authenticated && probe.id === 'codex_cli') {
+            capabilities.push('local_fix_publication_v1');
+            if (verificationMode === 'gateway_ci_v1')
+                capabilities.push('local_fix_gateway_ci_v1');
+        }
+        return { adapter: probe.id, version: probe.version, authenticated, capabilities };
+    });
+}

package/dist/src/daemon/terminal-recovery.js

@@ -1,4 +1,5 @@
 import { isTerminalEventType } from '../protocol.js';
+import { DAEMON_BLOCKED_REASONS, DAEMON_CANCELLED_REASONS } from '../state-store.js';
 function record(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
@@ -11,13 +12,19 @@ export async function reconcileTerminalState(previous, deps) {
     if (!record(previous))
         invalid();
     if (previous.phase !== 'terminal_pending') {
-        if (!['claimed', 'shadow', 'binding', 'binding_uncertain', 'preparation_failed'].includes(String(previous.phase))
+        if (typeof previous.phase !== 'string' || !['claimed', 'shadow', 'binding', 'binding_uncertain', 'preparation_failed', 'running'].includes(previous.phase)
             || !nonempty(previous.jobId) || !Number.isSafeInteger(previous.generation) || previous.generation < 1
             || !nonempty(previous.leaseToken))
             invalid();
-        // Only preparation states without execution evidence may reach the legacy
-        // preparation handler (whose caller may clear an unhandled receipt).
+        // Validate known states for the recovery handler. A running state remains
+        // suspended there: neither a terminal flag nor its fence proves OS cleanup.
         const allowed = ['phase', 'jobId', 'generation', 'leaseToken', 'workspaceManifest'];
+        if (previous.phase === 'running') {
+            allowed.push('bindingId', 'eventCursor', 'terminalEventType');
+            if (!nonempty(previous.bindingId) || (previous.eventCursor !== undefined && (!Number.isSafeInteger(previous.eventCursor) || previous.eventCursor < 0))
+                || (previous.terminalEventType !== undefined && (typeof previous.terminalEventType !== 'string' || !isTerminalEventType(previous.terminalEventType))))
+                invalid();
+        }
         if (previous.phase === 'preparation_failed' || previous.phase === 'binding_uncertain')
             allowed.push('preparationFailure');
         if (Object.keys(previous).some(key => !allowed.includes(key)))
@@ -38,12 +45,29 @@ export async function reconcileTerminalState(previous, deps) {
         || request.generation !== previous.generation || request.leaseToken !== previous.leaseToken || !record(request.result))
         invalid();
     const result = request.result;
-    if (previous.bindingId !== undefined) {
+    if (result.recovery !== undefined) {
+        const recovery = result.recovery;
+        if (Object.keys(previous).sort().join(',') !== 'completionRequest,generation,jobId,leaseToken,phase'
+            || Object.keys(result).sort().join(',') !== 'reason,recovery' || !record(recovery)
+            || Object.keys(recovery).sort().join(',') !== 'phase,version' || recovery.version !== 'local-runner-recovery-v1'
+            || typeof recovery.phase !== 'string' || !['claimed', 'shadow', 'binding', 'binding_uncertain'].includes(recovery.phase)
+            || result.reason !== (recovery.phase === 'binding' || recovery.phase === 'binding_uncertain' ? 'binding_outcome_unknown' : 'runner_restarted')
+            || request.status !== (result.reason === 'binding_outcome_unknown' ? 'blocked' : 'failed'))
+            invalid();
+    }
+    else if (previous.bindingId !== undefined) {
         const eventType = result.event_type;
         if (!nonempty(previous.bindingId) || result.binding_id !== previous.bindingId || typeof eventType !== 'string'
             || (!isTerminalEventType(eventType) && eventType !== 'blocked' && eventType !== 'scope_conflict') || previous.terminalEventType !== eventType || typeof result.summary !== 'string')
             invalid();
-        const status = eventType === 'completed' ? 'completed' : eventType === 'cancelled' ? 'cancelled'
+        const reason = result.reason;
+        const blocked = eventType === 'failed' && typeof reason === 'string' && DAEMON_BLOCKED_REASONS.includes(reason);
+        // Old blocked/scope_conflict receipts remain replayable byte-for-byte. New
+        // failed/blocked pairs require one explicit daemon outcome reason.
+        if (reason !== undefined && eventType !== 'blocked' && eventType !== 'scope_conflict' && !(blocked || (eventType === 'cancelled' && typeof reason === 'string'
+            && DAEMON_CANCELLED_REASONS.includes(reason))))
+            invalid();
+        const status = blocked ? 'blocked' : eventType === 'completed' ? 'completed' : eventType === 'cancelled' ? 'cancelled'
             : eventType === 'blocked' || eventType === 'scope_conflict' ? 'blocked' : 'failed';
         if (request.status !== status)
             invalid();

package/dist/src/gateway-client.js

@@ -122,16 +122,25 @@ export class McpGatewayClient {
         }
         throw new Error("No token provider or static token configured");
     }
-    async callTool(name, args) {
+    async callTool(name, args, signal) {
         let failureCode = "GATEWAY_TRANSPORT_ERROR";
         try {
             const token = await this.resolveToken();
+            signal?.throwIfAborted();
             const response = await this.fetchFn(this.mcpUrl, {
+                ...(signal ? { signal } : {}),
                 method: "POST",
                 headers: { Authorization: `Bearer ${token}`, "content-type": "application/json" },
                 body: JSON.stringify({ jsonrpc: "2.0", id: ++this.requestId, method: "tools/call", params: { name, arguments: args } }),
             });
+            signal?.throwIfAborted();
+            if (!response.ok) {
+                failureCode = `GATEWAY_HTTP_${response.status}`;
+                throw new Error(`Gateway MCP ${name} failed with status ${response.status}`);
+            }
+            failureCode = 'GATEWAY_INVALID_TOOL_RESULT';
             const body = (await response.json());
+            signal?.throwIfAborted();
             if (!response.ok || body.error) {
                 failureCode = !response.ok ? `GATEWAY_HTTP_${response.status}` : "GATEWAY_RPC_ERROR";
                 throw new Error(`Gateway MCP ${name} failed with status ${response.status}: ${JSON.stringify(body.error ?? body)}`);
@@ -146,6 +155,7 @@ export class McpGatewayClient {
                 failureCode = envelope.status === "failed" ? "GATEWAY_TOOL_REJECTED" : "GATEWAY_INVALID_TOOL_RESULT";
                 throw new Error(`Gateway MCP ${name} did not complete: ${JSON.stringify(envelope)}`);
             }
+            signal?.throwIfAborted();
             return nested(envelope, "result.data");
         }
         catch (error) {
@@ -377,28 +387,29 @@ export class McpGatewayClient {
                 : {}),
         };
     }
-    async readCommands(bindingId, afterSequence) {
+    async readCommands(bindingId, afterSequence, signal) {
         const result = await this.callTool("agent_runtime_commands_read", {
             binding_id: bindingId,
             runner_id: this.runnerId,
             after_sequence: afterSequence,
             limit: 100,
-        });
+        }, signal);
         return result.commands ?? [];
     }
-    async acknowledgeCommand(bindingId, sequence) {
+    async acknowledgeCommand(bindingId, sequence, signal) {
         await this.callTool("agent_runtime_command_acknowledge", {
             binding_id: bindingId,
             runner_id: this.runnerId,
             command_sequence: sequence,
-        });
+        }, signal);
     }
-    async heartbeat(bindingId) {
+    async heartbeat(bindingId, signal) {
         const context = this.requireContext(bindingId);
         const result = await this.callTool("work_loop_heartbeat", {
             work_loop_id: context.workLoopId,
             lease_token: context.leaseToken,
-        });
+        }, signal);
+        signal?.throwIfAborted();
         context.leaseExpiresAt = epochToIso(result.loop.lease_expires_at);
         return { leaseExpiresAt: context.leaseExpiresAt };
     }
@@ -432,26 +443,31 @@ export class McpGatewayClient {
     async localRunnerStatus() {
         return this.callTool("local_agent_runner_status", { runner_id: this.runnerId });
     }
-    async localJobShadow(input) {
-        const shown = await this.callTool("work_loop_show", { work_loop_id: input.workLoopId });
-        if (shown.loop.environment !== "development")
-            throw new Error("local agent runtime is development-only");
+    async localJobShadow(input, signal) {
+        const shown = await this.callTool("work_loop_show", { work_loop_id: input.workLoopId }, signal);
+        if (shown?.loop?.environment !== "development")
+            throw new GatewayToolError("local agent runtime is development-only", 'work_loop_show', 'GATEWAY_INVALID_TOOL_RESULT');
         if (shown.loop.status === "cancelled")
             throw new GatewayToolError("Work Loop is cancelled", "work_loop_show", "WORK_LOOP_CANCELLED");
+        const contractId = shown.loop.work_execution_contract_id;
+        if (typeof contractId !== 'string' || !contractId)
+            throw new GatewayToolError('Gateway response is missing execution contract ID', 'work_loop_show', 'GATEWAY_INVALID_TOOL_RESULT');
         const result = await this.callTool("work_execution_contract_show", {
-            contract_id: requiredString(shown.loop.work_execution_contract_id, "execution contract ID"),
-        });
-        if (result.contract.status !== "approved")
-            throw new Error("execution contract is not approved");
+            contract_id: contractId,
+        }, signal);
+        if (result?.contract?.status !== "approved")
+            throw new GatewayToolError("execution contract is not approved", 'work_execution_contract_show', 'GATEWAY_TOOL_REJECTED');
         const payload = result.contract.contract_payload;
         if (!payload || typeof payload !== "object" || Array.isArray(payload))
-            throw new Error("Gateway response is missing contract payload");
-        const storedFingerprint = requiredString(result.contract.content_fingerprint, "contract fingerprint");
+            throw new GatewayToolError("Gateway response is missing contract payload", 'work_execution_contract_show', 'GATEWAY_INVALID_TOOL_RESULT');
+        const storedFingerprint = result.contract.content_fingerprint;
+        if (typeof storedFingerprint !== 'string' || !storedFingerprint)
+            throw new GatewayToolError('Gateway response is missing contract fingerprint', 'work_execution_contract_show', 'GATEWAY_INVALID_TOOL_RESULT');
         if (storedFingerprint !== input.contractFingerprint)
-            throw new Error("claimed contract fingerprint differs from approved contract");
+            throw new GatewayToolError("claimed contract fingerprint differs from approved contract", 'work_execution_contract_show', 'GATEWAY_INVALID_TOOL_RESULT');
         return { contractFingerprint: storedFingerprint, taskPackageFingerprint: input.taskPackageFingerprint, contractPayload: payload };
     }
-    async createLocalJobBinding(input) {
+    async createLocalJobBinding(input, signal) {
         const clientSessionReference = uuidv5(`local-agent-job:${input.jobId}:${input.generation}`, uuidv5.URL);
         const result = await this.callTool("local_agent_job_binding_create", {
             job_id: input.jobId,
@@ -460,9 +476,10 @@ export class McpGatewayClient {
             launch_grant: input.launchGrant,
             runner_id: this.runnerId,
             client_session_reference: clientSessionReference,
-        });
+        }, signal);
         const bindingId = requiredString(result.binding.id, "binding ID");
         const iterationId = requiredString(result.binding.iteration_id, "iteration ID");
+        signal?.throwIfAborted();
         this.context = {
             workLoopId: requiredString(result.work_loop_id, "Work Loop ID"),
             leaseToken: requiredString(result.lease_token, "Work Loop lease token"),
@@ -480,6 +497,87 @@ export class McpGatewayClient {
             resolvedModelId: requiredString(result.binding.resolved_model_id, "resolved model ID"),
         };
     }
+    /** 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;
+        }
+        if (!verified)
+            throw new Error('LOCAL_PUBLICATION_EVENT_CURSOR_REJECTED');
+        return cursor;
+    }
+    /** 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,
+            launch_grant: input.launchGrant, binding_id: input.bindingId, runner_id: this.runnerId };
+    }
+    exportLocalPublicationRecoveryContext(bindingId) {
+        const c = this.requireContext(bindingId);
+        return structuredClone({ ...c, bundle: { contract: { content_fingerprint: requiredString(nested(c.bundle, 'contract.content_fingerprint'), 'contract fingerprint') } } });
+    }
+    async restoreLocalPublicationRecoveryContext(input, stored, terminalReplay = false) {
+        if (terminalReplay) {
+            if (stored.bindingId !== input.bindingId || typeof stored.leaseToken !== 'string' || !stored.leaseToken)
+                throw new Error('LOCAL_PUBLICATION_RECOVERY_CONTEXT_REJECTED');
+            this.context = structuredClone(stored);
+            return;
+        }
+        const current = (await this.localPublicationContext(input)).context;
+        if (stored.bindingId !== input.bindingId || stored.workLoopId !== current.work_loop_id || nested(stored.bundle, 'contract.content_fingerprint') !== current.contract_fingerprint || typeof stored.leaseToken !== 'string' || !stored.leaseToken)
+            throw new Error('LOCAL_PUBLICATION_RECOVERY_CONTEXT_REJECTED');
+        this.context = structuredClone(stored);
+    }
+    async localPublicationContext(input) {
+        return this.callTool('local_agent_publication_context', this.localPublicationFence(input));
+    }
+    async executeServerCiPublication(input) {
+        const body = { ...this.localPublicationFence(input), operation: input.operation };
+        if (input.operation === 'stage') {
+            const receipt = { ...input.securityReceipt };
+            if (receipt.transport === 'official_exec_v1' && ['cli-exec-job-security-receipt-v2', 'cli-exec-job-security-receipt-v3'].includes(String(receipt.receipt_version))) {
+                delete receipt.preparation_timing;
+                delete receipt.launch_process;
+            }
+            Object.assign(body, { files: input.files, security_receipt: receipt, host_receipt: input.hostReceipt });
+        }
+        else
+            Object.assign(body, { publication_id: input.publicationId, ...(input.canonicalApprovalId ? { canonical_approval_id: input.canonicalApprovalId } : {}) });
+        return this.callTool('local_agent_server_publication', body);
+    }
+    async executeLocalPublicationPr(input) {
+        return this.callTool('local_agent_publication_execute_pr', { ...this.localPublicationFence(input), publication_id: input.publicationId, signed_request: input.signedRequest, ...(input.canonicalApprovalId ? { canonical_approval_id: input.canonicalApprovalId } : {}) });
+    }
+    async authorizeLocalPublication(input) {
+        const receipt = { ...input.securityReceipt };
+        if (receipt.transport === 'official_exec_v1' && ['cli-exec-job-security-receipt-v2', 'cli-exec-job-security-receipt-v3'].includes(String(receipt.receipt_version))) {
+            delete receipt.preparation_timing;
+            delete receipt.launch_process;
+        }
+        return this.callTool('local_agent_publication_authorize', { ...this.localPublicationFence(input),
+            candidate: input.candidate, test_receipts: input.testReceipts, security_receipt: receipt, host_receipt: input.hostReceipt });
+    }
+    async issueLocalPublicationAction(input) {
+        return this.callTool('local_agent_publication_issue_action', { ...this.localPublicationFence(input),
+            publication_id: input.publicationId, action: input.action, commit_message: input.commitMessage,
+            pull_request_title: input.pullRequestTitle, pull_request_body: input.pullRequestBody });
+    }
+    async acceptLocalPublicationResult(input) {
+        return this.callTool('local_agent_publication_accept_result', { ...this.localPublicationFence(input),
+            publication_id: input.publicationId, action: input.action, result: input.result });
+    }
     async completeLocalJob(input) {
         let result = input.result;
         const receipt = result.security_receipt;
@@ -502,13 +600,13 @@ export class McpGatewayClient {
             result,
         });
     }
-    async heartbeatLocalJob(input) {
+    async heartbeatLocalJob(input, signal) {
         return this.callTool("local_agent_job_heartbeat", {
             job_id: input.jobId,
             generation: input.generation,
             lease_token: input.leaseToken,
             runner_id: this.runnerId,
-        });
+        }, signal);
     }
     requireContext(bindingId) {
         if (!this.context || this.context.bindingId !== bindingId) {