mtech-ai-local-runner 0.1.30 → 0.1.31

package/dist/src/adapters/codex/adapter.js

@@ -185,6 +185,21 @@ export class CodexAdapter {
             await this.cancel();
         }
     }
+    async freezeForPublication() {
+        if (!this.usingOfficialExec || !this.ownedExec)
+            throw Error('CODEX_PUBLICATION_FREEZE_UNCONFIRMED');
+        let timer;
+        try {
+            await Promise.race([Promise.all([this.ownedExec.freezeForPublication(), this.cancel()]), new Promise((_, reject) => { timer = setTimeout(() => reject(Error('CODEX_PUBLICATION_FREEZE_UNCONFIRMED')), 10000); })]);
+        }
+        catch {
+            throw Error('CODEX_PUBLICATION_FREEZE_UNCONFIRMED');
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
     async cancel() {
         this.cancelled = true;
         try {

package/dist/src/adapters/codex/exec-launch-host.js

@@ -246,6 +246,28 @@ export class CodexExecLaunchHost {
         }
         return this.readAudit ? structuredClone(this.readAudit) : undefined;
     }
+    /** A kill request is not an exit proof. Publication alone requires the trusted
+     * process-group host to observe real exit, closed pipes and group disappearance.
+     * This deadline bounds teardown only, never model execution duration. */
+    async freezeForPublication() {
+        let timer;
+        try {
+            if (!this.ownsAttempt || !this.handle?.waitForOwnedExit)
+                throw fail();
+            const handle = this.handle;
+            await Promise.race([
+                Promise.all([this.cancel(), handle.waitForOwnedExit(10000)]),
+                new Promise((_, reject) => { timer = setTimeout(() => reject(fail()), 10000); }),
+            ]);
+        }
+        catch {
+            throw Error('CODEX_PUBLICATION_FREEZE_UNCONFIRMED');
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
     cancel() {
         if (this.closePromise)
             return this.closePromise;

package/dist/src/cli.js

@@ -1,4 +1,8 @@
 #!/usr/bin/env node
+import { recoverLocalFixPublication } from './publication/recovery.js';
+import { loadInstalledLocalFixHost } from './publication/installed-host.js';
+import { FileDaemonStateStore } from './state-store.js';
+import { ProcessLock } from './daemon/process-lock.js';
 import { runManualCodexJob } from './daemon/manual-codex.js';
 import { unlinkSync, realpathSync } from "node:fs";
 import { join } from "node:path";
@@ -228,6 +232,25 @@ export async function main(argv, env, io = {}) {
             const credentialStore = new FileOAuthCredentialStore(config.stateRoot);
             const oauthClient = new OAuthClient({ resource: local.gatewayMcpUrl, fetchFn });
             const tokenProvider = new OAuthTokenProvider({ store: credentialStore, oauthClient, resource: local.gatewayMcpUrl, tokenOverride: env.AI_GATEWAY_LOCAL_RUNNER_TOKEN, allowRefresh: config.mode !== 'manual-codex', clock: () => Date.now() });
+            if (config.mode === 'publication-recover') {
+                const lock = new ProcessLock(join(config.stateRoot, 'daemon.lock'));
+                await lock.acquire();
+                try {
+                    const gateway = new McpGatewayClient({ mcpUrl: local.gatewayMcpUrl, runnerId: local.runnerId, tokenProvider, fetchFn });
+                    const host = await loadInstalledLocalFixHost({ stateRoot: config.stateRoot, runnerId: local.runnerId, gateway });
+                    if (!host)
+                        throw new Error('LOCAL_FIX_INSTALLATION_REQUIRED');
+                    const state = new FileDaemonStateStore(config.stateRoot), stored = await state.load();
+                    if (!stored)
+                        throw new Error('LOCAL_PUBLICATION_RECOVERY_STATE_REQUIRED');
+                    await recoverLocalFixPublication({ jobId: config.manualJobId, stored: stored, host, gateway, state });
+                    stdout(JSON.stringify({ status: 'completed', jobId: config.manualJobId, modelStarted: false }));
+                    return 0;
+                }
+                finally {
+                    await lock.release();
+                }
+            }
             if (config.mode === "doctor") {
                 const adapters = doctorAdapters;
                 const localChecks = Promise.allSettled([

package/dist/src/config.js

@@ -6,11 +6,11 @@ export function isExecutionConfig(config) {
     return config.mode === "shadow" || config.mode === "once";
 }
 export function isServiceConfig(config) {
-    return ["setup", "doctor", "run", "start", "stop", "status", "uninstall", "manual-codex"].includes(config.mode);
+    return ["setup", "doctor", "run", "start", "stop", "status", "uninstall", "manual-codex", "publication-recover"].includes(config.mode);
 }
 const EXECUTION_MODES = ["shadow", "once"];
 const AUTH_MODES = ["login", "logout"];
-const SERVICE_MODES = ["setup", "doctor", "run", "start", "stop", "status", "uninstall", "manual-codex"];
+const SERVICE_MODES = ["setup", "doctor", "run", "start", "stop", "status", "uninstall", "manual-codex", "publication-recover"];
 const ALL_MODES = [...EXECUTION_MODES, ...AUTH_MODES, ...SERVICE_MODES];
 export const DEFAULT_GATEWAY_MCP_URL = "https://cloud.dev.service.ai-gateway.laravelvapor.org/api/v1/web/ai-gateway/mcp";
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -101,9 +101,9 @@ export function loadConfig(argv, env) {
     const stateRoot = defaultStateRootFromEnv(env);
     if (SERVICE_MODES.includes(mode)) {
         let manualJobId;
-        if (mode === 'manual-codex') {
+        if (mode === 'manual-codex' || mode === 'publication-recover') {
             if (rest.length !== 1 || !rest[0].startsWith('--job-id=') || !UUID_PATTERN.test(rest[0].slice(9)))
-                throw new Error('manual-codex requires exactly --job-id=<uuid>');
+                throw new Error(`${mode} requires exactly --job-id=<uuid>`);
             manualJobId = rest[0].slice(9).toLowerCase();
         }
         return {

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

@@ -1,3 +1,4 @@
+import { PublicationOutcomeUnknownError } from '../publication/publisher.js';
 import { executionError, executionFailure } from '../safety/execution-failure.js';
 import { requireSecurityRequirements } from '../safety/security-requirements.js';
 import { GatewayToolError } from "../gateway-client.js";
@@ -42,6 +43,8 @@ function immutable(value) {
 }
 class PreparationDeadlineError extends Error {
 }
+class LocalFixHostRequired extends Error {
+}
 export class ExecutionCoordinator {
     deps;
     constructor(deps) {
@@ -53,6 +56,10 @@ export class ExecutionCoordinator {
         let workspace;
         let adapter;
         let binding;
+        let fixSession;
+        let localFixPublication;
+        const isLocalFix = job.taskPackage.local_fix_scope !== undefined;
+        const lifecycle = { frozen: false, current: true };
         const deadline = Date.now() + (this.deps.preparationTimeoutMs ?? 900_000);
         const step = async (operation) => {
             const remaining = deadline - Date.now();
@@ -71,6 +78,8 @@ export class ExecutionCoordinator {
         };
         try {
             const pkg = job.taskPackage;
+            if (isLocalFix && (!this.deps.localFixHost || pkg.repository?.access !== "write"))
+                throw new LocalFixHostRequired();
             const repository = pkg.repository;
             const adapterId = text(pkg.runtime_adapter, "runtime adapter");
             const adapterVersion = text(pkg.runtime_adapter_version, "runtime adapter version");
@@ -85,6 +94,7 @@ export class ExecutionCoordinator {
                 repositoryKey: text(repository?.key, "repository key"),
                 providerUrl: text(repository?.provider_url, "repository provider URL"),
                 baseCommitSha: text(repository?.base_commit_sha, "repository SHA"),
+                ...(isLocalFix ? { workingBranch: text(repository?.working_branch, "approved fix branch") } : {})
             }));
             stage = "adapter";
             adapter = await step(() => this.deps.registry.select(adapterId, adapterVersion, { worktreePath: workspace.path, jobId: job.id }));
@@ -98,9 +108,13 @@ export class ExecutionCoordinator {
             stage = "binding";
             await this.deps.state.save({ jobId: job.id, generation: job.generation, leaseToken: job.leaseToken, phase: "binding" });
             binding = await step(() => this.deps.gateway.createBinding({ ...job, checkoutPath: workspace.path }));
+            if (isLocalFix)
+                fixSession = await step(() => this.deps.localFixHost.prepare({ job, checkoutPath: workspace.path, bindingId: binding.bindingId, lifecycle: { isFrozen: () => lifecycle.frozen, isCurrent: () => lifecycle.current, securityReceipt: () => adapter.securityReceipt?.() } }));
         }
         catch (error) {
             const diagnostic = { stage, code: "PREPARATION_FAILED" };
+            if (error instanceof LocalFixHostRequired)
+                diagnostic.code = "LOCAL_FIX_HOST_REQUIRED";
             if (error instanceof PreparationDeadlineError)
                 diagnostic.code = "PREPARATION_DEADLINE_EXCEEDED";
             if (error instanceof GatewayToolError) {
@@ -141,6 +155,7 @@ export class ExecutionCoordinator {
                     if (controlsStopped)
                         return;
                     if (["cancel", "pause", "request_replan"].includes(command.command)) {
+                        lifecycle.current = false;
                         requestedTerminal = { eventType: command.command === "cancel" ? "cancelled" : "blocked", summary: `supervisor ${command.command} acknowledged` };
                         await adapter.cancel();
                     }
@@ -167,6 +182,7 @@ export class ExecutionCoordinator {
         };
         const heartbeatTimer = this.deps.gateway.heartbeat || this.deps.gateway.readCommands ? setInterval(() => {
             void (async () => { await this.deps.gateway.heartbeat?.(binding.bindingId, job); await readControls(); })().catch(async (error) => {
+                lifecycle.current = false;
                 heartbeatFailure = executionError(error, 'heartbeat', 'EXECUTION_FAILED');
                 await adapter.cancel().catch(() => undefined);
             });
@@ -181,14 +197,17 @@ export class ExecutionCoordinator {
             let payload = event.payload;
             if (isTerminalEventType(event.eventType)) {
                 executionStage = 'terminal_evidence';
-                const evidence = this.deps.terminalEvidenceCollector.collect({ checkoutPath: workspace.path, baseSha: workspace.baseCommitSha });
+                const evidence = localFixPublication && typeof localFixPublication.diff_hash === 'string' && typeof localFixPublication.changed_file_manifest_hash === 'string' ? { diffHash: localFixPublication.diff_hash, changedFileManifestHash: localFixPublication.changed_file_manifest_hash } : this.deps.terminalEvidenceCollector.collect({ checkoutPath: workspace.path, baseSha: workspace.baseCommitSha });
                 payload = { ...payload, diff_hash: evidence.diffHash, changed_file_manifest_hash: evidence.changedFileManifestHash };
             }
             // A vendor report cannot supply host observations, even when its shape looks valid.
             if (payload) {
                 payload = { ...payload };
                 delete payload.local_read_observations;
+                delete payload.local_fix_publication;
             }
+            if (event.eventType === "completed" && localFixPublication)
+                payload = { ...payload, local_fix_publication: structuredClone(localFixPublication) };
             if (isTerminalEventType(event.eventType) || event.eventType === 'blocked' || event.eventType === 'scope_conflict') {
                 const reads = safeLocalReadObservations(adapter.localReadObservations?.());
                 if (reads)
@@ -236,6 +255,40 @@ export class ExecutionCoordinator {
                             await controlsInFlight;
                         if (requestedTerminal)
                             break;
+                        if (event.eventType === "completed" && fixSession) {
+                            // Stop only this owned model before running verified host publication.
+                            // Controls/heartbeat remain active throughout the publication phase.
+                            if (this.deps.localFixHost?.requiresOwnedFreeze) {
+                                if (!adapter.freezeForPublication)
+                                    throw new Error('LOCAL_FIX_OWNED_FREEZE_UNAVAILABLE');
+                                await adapter.freezeForPublication();
+                            }
+                            else
+                                await adapter.cancel();
+                            lifecycle.frozen = true;
+                            await readControls();
+                            if (requestedTerminal || heartbeatFailure)
+                                break;
+                            executionStage = 'local_fix_publication';
+                            await 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 } });
+                            localFixPublication = await fixSession.finalize();
+                            if (this.deps.gateway.syncPublicationCursor) {
+                                try {
+                                    const cursor = await this.deps.gateway.syncPublicationCursor(binding.bindingId, sequence);
+                                    if (!Number.isSafeInteger(cursor) || cursor < sequence)
+                                        throw new Error('Invalid event cursor');
+                                    sequence = cursor;
+                                }
+                                catch {
+                                    throw new PublicationOutcomeUnknownError();
+                                }
+                            }
+                            if (controlsInFlight)
+                                await controlsInFlight;
+                            if (requestedTerminal || heartbeatFailure)
+                                break;
+                            executionStage = 'event_stream';
+                        }
                         controlsStopped = true;
                     }
                     await append(event);
@@ -261,6 +314,11 @@ export class ExecutionCoordinator {
             }
         }
         catch (error) {
+            if (error instanceof PublicationOutcomeUnknownError) {
+                // 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');
+            }
             await adapter.cancel().catch(() => undefined);
             // Do not complete a job whose terminal evidence was not acknowledged.
             // A safe bounded reason prevents raw adapter/transport errors leaking.
@@ -278,6 +336,8 @@ export class ExecutionCoordinator {
             controlsStopped = true;
             if (heartbeatTimer)
                 clearInterval(heartbeatTimer);
+            lifecycle.current = false;
+            await fixSession?.close();
         }
         const status = terminal.eventType === "completed" ? "completed" : terminal.eventType === "cancelled" ? "cancelled" : terminal.eventType === "blocked" || terminal.eventType === "scope_conflict" ? "blocked" : "failed";
         const diagnostic = status === "failed" || terminal.eventType === "blocked" ? completionReportDiagnostic(terminal.payload?.completion_report) : undefined;
@@ -285,7 +345,7 @@ export class ExecutionCoordinator {
             ? diagnostic.code === "CODEX_COMPLETION_REPORT_BLOCKED" : diagnostic.code !== "CODEX_COMPLETION_REPORT_BLOCKED") ? diagnostic : undefined;
         const securityReceipt = adapter.securityReceipt?.();
         const reads = safeLocalReadObservations(adapter.localReadObservations?.());
-        const completionRequest = structuredClone({ jobId: job.id, generation: job.generation, leaseToken: job.leaseToken, status, result: { binding_id: binding.bindingId, event_type: terminal.eventType, summary: terminal.summary, ...(reads ? { local_read_observations: reads } : {}), ...(failureDiagnostic ? { execution_failure: { ...failureDiagnostic } } : {}), ...(reportDiagnostic ? { completion_report: reportDiagnostic } : {}), ...(securityReceipt ? { security_receipt: securityReceipt } : {}) } });
+        const completionRequest = structuredClone({ jobId: job.id, generation: job.generation, leaseToken: job.leaseToken, status, result: { binding_id: binding.bindingId, event_type: terminal.eventType, summary: terminal.summary, ...(localFixPublication ? { local_fix_publication: structuredClone(localFixPublication) } : {}), ...(reads ? { local_read_observations: reads } : {}), ...(failureDiagnostic ? { execution_failure: { ...failureDiagnostic } } : {}), ...(reportDiagnostic ? { completion_report: reportDiagnostic } : {}), ...(securityReceipt ? { security_receipt: securityReceipt } : {}) } });
         await this.deps.state.save({ jobId: job.id, generation: job.generation, leaseToken: job.leaseToken,
             phase: "terminal_pending", bindingId: binding.bindingId, terminalEventType: terminal.eventType,
             completionRequest: structuredClone(completionRequest) });

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';
@@ -26,6 +27,7 @@ export async function buildDaemon(input) {
     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;
     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,6 +47,7 @@ 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(),
@@ -56,6 +59,8 @@ export async function buildDaemon(input) {
                 jobId: job.id, generation: job.generation, jobLeaseToken: job.leaseToken,
                 launchGrant: job.launchGrant, workLoopId: job.workLoopId, checkoutPath: job.checkoutPath,
             }),
+            publicationRecoveryContext: bindingId => gateway.exportLocalPublicationRecoveryContext(bindingId),
+            syncPublicationCursor: (bindingId, cursor) => gateway.syncLocalPublicationCursor(bindingId, cursor),
             readCommands: (bindingId, cursor) => gateway.readCommands(bindingId, cursor),
             acknowledgeCommand: (bindingId, sequence) => gateway.acknowledgeCommand(bindingId, sequence),
             appendEvent: (bindingId, event) => gateway.appendEvent(bindingId, event),
@@ -102,8 +107,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),
             });
         },
         wait: async () => {
@@ -146,6 +150,8 @@ export async function buildDaemon(input) {
 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 (["publication_pending", "publication_terminal_pending"].includes(previous.phase ?? ""))
+        throw new Error("Publication outcome requires reconciliation before runner polling");
     if (previous.phase === "binding" || previous.phase === "binding_uncertain") {
         throw new Error("Binding outcome requires reconciliation before runner polling");
     }
@@ -159,3 +165,13 @@ 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) {
+    return probes.map(probe => {
+        const authenticated = probe.available && probe.authenticated;
+        const capabilities = probe.capabilities.filter(value => value !== 'local_fix_publication_v1');
+        if (trustedLocalFixHost && authenticated && probe.id === 'codex_cli')
+            capabilities.push('local_fix_publication_v1');
+        return { adapter: probe.id, version: probe.version, authenticated, capabilities };
+    });
+}

package/dist/src/gateway-client.js

@@ -480,6 +480,73 @@ 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 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;

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

@@ -1,4 +1,4 @@
-import { chmod, mkdir, rename, writeFile } from "node:fs/promises";
+import { access, chmod, mkdir, rename, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
@@ -11,6 +11,7 @@ const defaultRun = async (file, args) => {
     const result = await execFileAsync(file, args, { encoding: "utf8" });
     return { stdout: result.stdout, stderr: result.stderr };
 };
+const defaultExists = async (path) => access(path).then(() => true, () => false);
 const defaultWriteAtomic = async (path, contents, mode) => {
     await mkdir(dirname(path), { recursive: true, mode: 0o700 });
     const temporary = `${path}.${process.pid}.tmp`;
@@ -47,8 +48,18 @@ export class LaunchdService {
         await (this.deps.run ?? defaultRun)("/bin/launchctl", ["bootout", `gui/${this.deps.uid}/${LAUNCHD_LABEL}`])
             .catch(() => undefined);
     }
+    // `stop` boots the agent out of launchd, and kickstart cannot start a service launchd no
+    // longer knows, so start loads the installed plist again first. It never writes a plist:
+    // a missing one means setup has not run.
     async start() {
-        await (this.deps.run ?? defaultRun)("/bin/launchctl", ["kickstart", "-k", `gui/${this.deps.uid}/${LAUNCHD_LABEL}`]);
+        const run = this.deps.run ?? defaultRun;
+        if (!(await this.status()).loaded) {
+            if (!(await (this.deps.exists ?? defaultExists)(this.plistPath))) {
+                throw new Error(`The runner service is not installed (${this.plistPath} is missing). Run npx mtech-ai-local-runner setup.`);
+            }
+            await run("/bin/launchctl", ["bootstrap", `gui/${this.deps.uid}`, this.plistPath]);
+        }
+        await run("/bin/launchctl", ["kickstart", "-k", `gui/${this.deps.uid}/${LAUNCHD_LABEL}`]);
     }
     async status() {
         try {

package/dist/src/process/node-process-group-host.js

@@ -31,6 +31,10 @@ export class NodeProcessGroupHost {
         });
         child.stdin.once('finish', () => observations.add('host_stdin_finished'));
         let failure;
+        let realExit = false, closed = false;
+        let closedResolve;
+        const processClosed = new Promise(resolve => { closedResolve = resolve; });
+        child.once('close', () => { closed = true; closedResolve(); });
         let owned = true;
         let finished = false, consumed = false, queuedBytes = 0, wake;
         const lines = [];
@@ -119,6 +123,7 @@ export class NodeProcessGroupHost {
         child.stderr.once('end', () => { observations.add('host_stderr_ended'); for (const marker of markers)
             marker.prefix = ''; });
         child.once("exit", (code, signal) => {
+            realExit = true;
             observations.add('host_process_exited');
             try {
                 kill();
@@ -131,7 +136,7 @@ export class NodeProcessGroupHost {
         // Drain from spawn, not from the first adapter event read: official exec can
         // emit startup events before it initializes MCP, while the adapter awaits
         // that initialization before consuming events. Bound the pre-consumer queue.
-        void (async () => {
+        const stdoutDrained = (async () => {
             let pending = Buffer.alloc(0);
             const enqueue = (line) => {
                 if (line.length > 256_000)
@@ -212,6 +217,36 @@ export class NodeProcessGroupHost {
                     }
                 } },
             kill: (signal) => kill((signal ?? "SIGKILL")),
+            waitForOwnedExit: async (timeoutMs) => {
+                if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 10000)
+                    throw Error('OWNED_PROCESS_EXIT_UNCONFIRMED');
+                const deadline = Date.now() + timeoutMs;
+                let timer;
+                try {
+                    await Promise.race([Promise.all([processClosed, stdoutDrained]), new Promise((_, reject) => { timer = setTimeout(() => reject(Error('OWNED_PROCESS_EXIT_UNCONFIRMED')), timeoutMs); })]);
+                    if (!realExit || !closed || !child.pid)
+                        throw Error('OWNED_PROCESS_EXIT_UNCONFIRMED');
+                    // Inspect only the exact process group created by this spawn. Never
+                    // scan processes or signal an unrelated PID/group during verification.
+                    for (;;) {
+                        try {
+                            process.kill(-child.pid, 0);
+                        }
+                        catch (error) {
+                            if (error.code === 'ESRCH')
+                                return;
+                            throw Error('OWNED_PROCESS_EXIT_UNCONFIRMED');
+                        }
+                        if (Date.now() >= deadline)
+                            throw Error('OWNED_PROCESS_EXIT_UNCONFIRMED');
+                        await new Promise(resolve => setTimeout(resolve, 10));
+                    }
+                }
+                finally {
+                    if (timer)
+                        clearTimeout(timer);
+                }
+            },
             once: (_event, callback) => { if (termination) {
                 const ended = termination;
                 queueMicrotask(() => callback(ended.code, ended.signal));

package/dist/src/publication/candidate.js

@@ -0,0 +1,95 @@
+import { createHash } from 'node:crypto';
+import { lstat, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { measureCommandFile } from '../safety/registered-command-integrity.js';
+export function protocolHash(value) {
+    const canonical = (v) => Array.isArray(v) ? v.map(canonical) : v && typeof v === 'object' ? Object.fromEntries(Object.entries(v).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([k, c]) => [k, canonical(c)])) : v;
+    return createHash('sha256').update(JSON.stringify(canonical(value)).replace(/[\u007f-\uffff]/g, c => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`)).digest('hex');
+}
+const denied = () => new Error('CANDIDATE_REJECTED');
+function freeze(v) { if (v && typeof v === 'object') {
+    for (const c of Object.values(v))
+        freeze(c);
+    Object.freeze(v);
+} return v; }
+const sensitive = (s) => /^(?:\.git|\.mcp(?:\..*)?|\.npmrc|\.netrc|id_rsa|id_ed25519|\.local-runner|\.runner|\.env(?:\..*)?|\.codex|\.claude|\.ssh|\.aws|\.config|auth\.(?:json|toml|ya?ml)(?:\..*)?|credentials(?:\..*)?|AGENTS\.md|CLAUDE\.md|mcp\.(?:json|toml|ya?ml)(?:\..*)?)$/i.test(s);
+const validPath = (p) => typeof p === 'string' && p.length > 0 && !p.includes('\0') && !p.includes('\\') && !path.isAbsolute(p) && p.split('/').every(s => s !== '.' && s !== '..' && s !== '' && !sensitive(s));
+function matches(file, scope) { if (scope.endsWith('/**')) {
+    const dir = scope.slice(0, -3);
+    return validPath(dir) && (file === dir || file.startsWith(dir + '/'));
+} return validPath(scope) && file === scope; }
+/** Object identity is host authority; serializing an evidence envelope cannot mint it.
+ * This is a verification foundation, not host adapter registration or a Gateway attestation. */
+export class CandidateVerifier {
+    options;
+    issued = new WeakSet();
+    constructor(options) { this.options = { ...options, binding: freeze(structuredClone(options.binding)), commands: freeze(structuredClone(options.commands)), allowedPaths: [...options.allowedPaths], blockedPaths: [...options.blockedPaths] }; }
+    async snapshot() {
+        const o = this.options, b = o.binding;
+        if (!await o.current() || !Number.isSafeInteger(b.generation) || b.generation < 1 || !Number.isSafeInteger(o.maxFiles) || o.maxFiles < 1 || !Number.isSafeInteger(o.maxDiffBytes) || o.maxDiffBytes < 1 || !Number.isSafeInteger(o.maxFileBytes) || o.maxFileBytes < 1 || Object.values(b).some(v => v === '') || ![b.contract_fingerprint, b.task_package_fingerprint, b.launch_fingerprint].every(v => /^[a-f0-9]{64}$/.test(v)) || !/^[a-f0-9]{40}$/.test(b.base_commit_sha) || b.working_branch !== `ai-work/local/${b.attempt_id}` || !/^[A-Za-z0-9-]+$/.test(b.attempt_id) || !path.isAbsolute(o.root) || await realpath(o.root) !== o.root)
+            throw denied();
+        const observation = structuredClone(await o.observe());
+        if (observation.base_commit_sha !== b.base_commit_sha || observation.head_commit_sha !== b.base_commit_sha || observation.working_branch !== b.working_branch || Buffer.byteLength(observation.diff) > o.maxDiffBytes || !observation.diff.length || !observation.changed_files.length || observation.changed_files.length > o.maxFiles || new Set(observation.changed_files.map(f => f.path)).size !== observation.changed_files.length)
+            throw denied();
+        const entries = [];
+        for (const f of [...observation.changed_files].sort((a, b) => a.path < b.path ? -1 : 1)) {
+            if (!validPath(f.path) || !['added', 'modified', 'deleted'].includes(f.status) || !o.allowedPaths.some(s => matches(f.path, s)) || o.blockedPaths.some(s => s === '.env.*' ? f.path.startsWith('.env.') : matches(f.path, s)))
+                throw denied();
+            let current = o.root;
+            const parts = f.path.split('/');
+            for (let i = 0; i < parts.length; i++) {
+                current = path.join(current, parts[i]);
+                try {
+                    const stat = await lstat(current);
+                    if ((i === parts.length - 1 && stat.size > o.maxFileBytes) || stat.isSymbolicLink() || (i < parts.length - 1 && !stat.isDirectory()) || (i === parts.length - 1 && f.status === 'deleted'))
+                        throw denied();
+                }
+                catch (e) {
+                    if (e.code === 'ENOENT' && i === parts.length - 1 && f.status === 'deleted')
+                        break;
+                    throw denied();
+                }
+            }
+            entries.push({ ...f, content_sha256: f.status === 'deleted' ? null : await measureCommandFile(path.join(o.root, f.path)) });
+        }
+        if (!o.commands.length || new Set(o.commands.map(c => c.id)).size !== o.commands.length || o.commands.some(c => !c.id || !path.isAbsolute(c.executable) || !c.integrity || !c.argv.every(a => typeof a === 'string')))
+            throw denied();
+        const commands = o.commands.map(c => ({ id: c.id, fingerprint: protocolHash(c) }));
+        const diff_hash = createHash('sha256').update(observation.diff).digest('hex');
+        const changed_file_manifest_hash = protocolHash(entries.map(({ content_sha256: _, ...f }) => f));
+        const snapshot_fingerprint = protocolHash({ binding: b, entries, diff_hash, changed_file_manifest_hash, commands });
+        if (!await o.current())
+            throw denied();
+        return freeze({ snapshot_fingerprint, changed_file_manifest_hash, diff_hash, commands, changed_files: observation.changed_files, diff_bytes: Buffer.byteLength(observation.diff) });
+    }
+    async verify() {
+        try {
+            const snapshot = await this.snapshot(), outcomes = structuredClone(await this.options.verify(snapshot));
+            if (outcomes.length !== snapshot.commands.length || new Set(outcomes.map(r => r.command_id)).size !== outcomes.length || snapshot.commands.some(c => !outcomes.some(r => r.command_id === c.id && r.command_fingerprint === c.fingerprint && r.snapshot_fingerprint === snapshot.snapshot_fingerprint && r.status === 'passed')) || protocolHash(await this.snapshot()) !== protocolHash(snapshot))
+                throw denied();
+            const b = this.options.binding, verification_fingerprint = protocolHash({ binding: b, snapshot_fingerprint: snapshot.snapshot_fingerprint, outcomes: [...outcomes].sort((a, b) => a.command_id < b.command_id ? -1 : 1) });
+            const evidence = { ...b, ...snapshot, verification_fingerprint, verification_status: 'passed', snapshot_reference: { kind: 'runner_local_snapshot', fingerprint: snapshot.snapshot_fingerprint, runner_id: b.runner_id, job_id: b.job_id, generation: b.generation } };
+            const { commands: _, ...wire } = evidence;
+            const candidate = freeze({ evidence: { ...wire, candidate_fingerprint: protocolHash(wire) }, testReceipts: outcomes });
+            this.issued.add(candidate);
+            return candidate;
+        }
+        catch {
+            throw denied();
+        }
+    }
+    async assertCurrent(candidate) {
+        try {
+            if (!this.issued.has(candidate) || !await this.options.current())
+                throw denied();
+            if (this.options.assertRetainedSeal)
+                await this.options.assertRetainedSeal();
+            else if (candidate.evidence.snapshot_fingerprint !== (await this.snapshot()).snapshot_fingerprint)
+                throw denied();
+            return candidate.evidence;
+        }
+        catch {
+            throw denied();
+        }
+    }
+}