mtech-ai-local-runner 0.1.29 → 0.1.31

package/README.md

@@ -1,4 +1,17 @@
-## 0.1.29 candidate: reviewed daemon Codex admission
+## 0.1.30: governed local alert investigation evidence
+
+The Gateway candidate offers explicit Local Codex Runner or Local Claude Runner
+selection for read-only Sentry investigation. It binds the chosen adapter/model
+and employee device to the exact approved launch; it never falls back to another
+adapter. Each adapter retains authenticated host-owned bounded read observations
+through completion and cleanup. These counts are employee-runner evidence, not
+independent root-cause verification.
+
+This release does not remove Claude's current unsupported host-admission gate.
+An installed or authenticated CLI alone is not execution permission. Gateway
+deployment, feature activation and actual execution approvals remain separate.
+
+## 0.1.29: reviewed daemon Codex admission
 
 This candidate connects the installed, hash-pinned root policy observer to the
 existing employee-privileged Codex CLI adapter. The observer accepts only its
@@ -35,7 +48,15 @@ npx mtech-ai-local-runner setup
 
 The package stores safe runner configuration locally and keeps OAuth refresh credentials in macOS Keychain when available.
 
-Public npm installation requires no npm account or publishing OTP. Setup requires Gateway OAuth login, and local Claude Code must already be authenticated (`claude auth status`).
+Public npm installation requires no npm account or publishing OTP. Setup requires
+the employee's own Gateway OAuth login and a supported, authenticated selected
+CLI. Codex uses the employee's ChatGPT account. Claude requires its own login
+and a separately verified host admission; it is currently not admitted.
+
+For the current unattended Codex pilot, an administrator must separately install
+the reviewed, employee-UID-bound policy observer on that Mac. The npm setup
+command does not install that privileged service. A fresh employee computer is
+not ready merely because npm installation succeeds.
 
 ## 0.1.28: completion receipt wire compatibility
 

package/dist/src/adapters/claude-code/adapter.js

@@ -8,6 +8,7 @@ import { completionEvent } from "./completion-report.js";
 import { requireJobSecurity } from "../../safety/job-security-policy.js";
 import { HOOK_POLICY_ENV_VAR, buildHookPolicy, encodeHookPolicy } from "../../safety/hook-policy-builder.js";
 import { formatHookCommand } from "../../safety/hook-command.js";
+import { localEndpointReadObservations } from '../../safety/local-tool-server.js';
 const ALLOWED_ENV_KEYS = ["PATH", "HOME", "USER", "LOGNAME", "LANG", "LC_ALL", "TMPDIR", "NODE_ENV", "CLAUDE_CONFIG_DIR"];
 const ALLOWED_SUPERVISOR_COMMANDS = new Set(["continue", "answer_question", "request_revision", "request_checkpoint", "submit_for_review"]);
 const LOCAL_NAMES = ["local_read", "local_search", "local_edit", "local_test"].map(name => `mcp__ai_local__${name}`);
@@ -44,7 +45,16 @@ export class ClaudeCodeAdapter {
     cancelled = false;
     started = false;
     receipt;
+    toolEndpoint;
+    readSnapshot;
     securityReceipt() { return this.receipt ? structuredClone(this.receipt) : undefined; }
+    localReadObservations() {
+        const endpoint = this.toolEndpoint;
+        const observed = endpoint ? localEndpointReadObservations(endpoint.url, endpoint.token) : undefined;
+        if (observed)
+            this.readSnapshot = observed;
+        return this.readSnapshot ? structuredClone(this.readSnapshot) : undefined;
+    }
     constructor(options) {
         this.options = options;
     }
@@ -97,6 +107,7 @@ export class ClaudeCodeAdapter {
             if (this.cancelled)
                 throw new Error("adapter startup cancelled");
             const endpoint = await this.tools.start();
+            this.toolEndpoint = endpoint;
             if (this.cancelled)
                 throw new Error("adapter startup cancelled");
             const mcpConfigPath = this.options.writeLocalMcpConfig(endpoint);
@@ -222,6 +233,8 @@ export class ClaudeCodeAdapter {
         await this.cleanup();
     }
     async cleanup() {
+        this.localReadObservations();
+        this.toolEndpoint = undefined;
         const tools = this.tools;
         const handle = this.handle;
         this.tools = undefined;

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

@@ -19,6 +19,7 @@ export class CodexAdapter {
     started = false;
     receipt;
     terminalAudit;
+    localReadObservations() { return this.usingOfficialExec ? this.ownedExec?.localReadObservations() : undefined; }
     securityReceipt() { return this.terminalAudit ? structuredClone(this.terminalAudit) : this.usingOfficialExec ? this.ownedExec?.receipt() : this.receipt ? structuredClone(this.receipt) : undefined; }
     cancelled = false;
     usingOfficialExec = false;
@@ -184,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

@@ -1,6 +1,6 @@
 import { performance } from 'node:perf_hooks';
 import { PreparationClock, CODEX_PREPARATION_BUDGET_MS } from '../../safety/preparation-timing.js';
-import { localEndpointObservations } from '../../safety/local-tool-server.js';
+import { localEndpointObservations, localEndpointReadObservations } from '../../safety/local-tool-server.js';
 import { processStartupObservations, freezeProcessLaunchObservation } from '../../process/node-process-group-host.js';
 import { executionError } from '../../safety/execution-failure.js';
 import { UNMANAGED_EXEC_MODE } from './unmanaged-scope.js';
@@ -24,6 +24,7 @@ export class CodexExecLaunchHost {
     handle;
     inspection;
     exitAudit;
+    readAudit;
     inspectionFingerprint;
     handshake;
     receiptValue;
@@ -233,9 +234,44 @@ export class CodexExecLaunchHost {
     catch {
         return undefined;
     } }
+    localReadObservations() {
+        if (!this.stopped) {
+            try {
+                const token = requireOfficialExecPlan(this.plan).env.AI_GATEWAY_JOB_MCP_TOKEN;
+                const current = token ? localEndpointReadObservations(this.plan.endpoint, token) : undefined;
+                if (current)
+                    this.readAudit = current;
+            }
+            catch { /* Absent observation is never interpreted as successful reads. */ }
+        }
+        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;
+        this.localReadObservations();
         this.stopped = true;
         this.receiptValue = undefined;
         if (!this.ownsAttempt) {

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,9 +197,22 @@ 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)
+                    payload = { ...payload, local_read_observations: reads };
+            }
             const normalized = {
                 protocolVersion: PROTOCOL_VERSION, bindingId: binding.bindingId,
                 sequence: sequence + 1, eventType: event.eventType,
@@ -226,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);
@@ -251,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.
@@ -268,13 +336,16 @@ 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;
         const reportDiagnostic = diagnostic && (terminal.eventType === "blocked"
             ? diagnostic.code === "CODEX_COMPLETION_REPORT_BLOCKED" : diagnostic.code !== "CODEX_COMPLETION_REPORT_BLOCKED") ? diagnostic : undefined;
         const securityReceipt = adapter.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, ...(failureDiagnostic ? { execution_failure: { ...failureDiagnostic } } : {}), ...(reportDiagnostic ? { completion_report: reportDiagnostic } : {}), ...(securityReceipt ? { security_receipt: 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, ...(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) });
@@ -282,3 +353,4 @@ export class ExecutionCoordinator {
         await this.deps.state.clear();
     }
 }
+import { safeLocalReadObservations } from '../safety/local-read-observations.js';

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));