mtech-ai-local-runner 0.1.11 → 0.1.13

package/README.md

@@ -125,6 +125,32 @@ or cost termination limits on an approved unbounded employee-local Claude run.
 Existing generation fencing, scope restrictions, cancellation and audit remain
 in force.
 
+### MCP startup failure diagnostics (0.1.13)
+
+Codex startup now distinguishes an owned process exiting before admission,
+preparation timeout, explicit abort and rejected MCP discovery. A fixed `detail`
+reports whether initialize, initialized notification or tool inventory is still
+missing (or discovery completed). The first issued cause survives cleanup and
+outer catches and reaches both the failed event and terminal Job result.
+Raw provider stderr remains excluded. These diagnostics do not establish the
+historical failure cause or prove whether provider inference occurred.
+
+The preparation deadline and mandatory authenticated MCP checks are unchanged.
+There is no automatic model retry or task duration/count cap. Installing this
+patch does not authorize another actual Codex attempt or change login/settings.
+
+### Post-binding execution diagnostics (0.1.12)
+
+The manual command and daemon log an `execution_failed` diagnostic (the manual
+command uses `manual_execution_failed`) before attempting Gateway failure
+reporting. Failed events and completion results carry `execution_failure` with
+a fixed `stage` and `code`. Inner host-issued diagnostics survive outer catches;
+unknown errors use a generic code. Credential values, raw exceptions, causes,
+stacks, filesystem paths and provider stderr are not included. These diagnostics
+do not prove whether provider inference occurred. A Gateway reporting outage
+retains the local diagnostic and does not turn an unacknowledged terminal event
+into a completed job. Existing reconciliation rules still apply.
+
 ### Manual Codex pilot (0.1.11)
 
 The reviewed manual Codex path preserves the existing CLI and ChatGPT login. It is separate from unattended daemon readiness. After the exact CLI/native reader and Gateway release are installed, an employee-authorized foreground pilot uses `mtec-ai-local-runner manual-codex --job-id=<approved Job UUID>`. It refuses a running daemon, unresolved recovery state, unknown release/account or a different Job. It does not stop services or alter personal settings. A direct administrator policy inventory occurs just before the approved execution; historical inventory is not continuous MDM monitoring. The Gateway OAuth client refuses refresh in this manual command. Actual vendor account startup may still refresh shared credentials and requires disclosure in the exact launch approval.

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

@@ -1,3 +1,4 @@
+import { executionError } from '../../safety/execution-failure.js';
 import { CodexExecLaunchHost } from './exec-launch-host.js';
 import { requireSecurityRequirements } from '../../safety/security-requirements.js';
 import { createJobSecurityReceipt } from '../../safety/job-security-receipt.js';
@@ -47,19 +48,27 @@ export class CodexAdapter {
                 await this.options.closeOfficialExec?.();
                 throw new Error('CODEX_EXEC_PREFLIGHT_REJECTED');
             }
-            host.assertAvailableContext(ctx, this.options.jobId);
+            try {
+                host.assertAvailableContext(ctx, this.options.jobId);
+            }
+            catch (error) {
+                throw executionError(error, 'codex_context', 'CODEX_EXEC_PREFLIGHT_REJECTED');
+            }
             this.ownedExec = host;
             this.usingOfficialExec = true;
+            let stage = 'codex_prompt';
             try {
                 const prompt = compileCodexPrompt(object(ctx.taskPackage), this.options.jobId);
+                stage = 'codex_launch';
                 this.handle = await this.ownedExec.start(ctx, this.options.jobId, prompt, this.startupAbort.signal);
                 this.receipt = this.ownedExec.receipt();
                 this.assertNotCancelled();
                 return;
             }
-            catch {
-                await this.cancel();
-                throw new Error('CODEX_EXEC_PREFLIGHT_REJECTED');
+            catch (error) {
+                const safe = executionError(error, stage, 'CODEX_EXEC_PREFLIGHT_REJECTED');
+                await this.cancel().catch(() => { });
+                throw safe;
             }
         }
         if (!this.options.startVerifiedSession)

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

@@ -1,3 +1,4 @@
+import { executionError } from '../../safety/execution-failure.js';
 import { UNMANAGED_EXEC_MODE } from './unmanaged-scope.js';
 import { fingerprint as taskFingerprint } from '../../daemon/execution-coordinator.js';
 import { securityRequirementsFingerprint as hash } from '../../safety/security-requirements.js';
@@ -61,15 +62,20 @@ export class CodexExecLaunchHost {
         claimOfficialExecPlan(this.plan);
         this.ownsAttempt = true;
         this.used = true;
+        let stage = 'codex_context';
+        let interruption;
+        const mcpDetail = () => stage === 'codex_mcp' ? this.deps.execTools?.discoveryDetail() : undefined;
+        const interrupt = (code) => { interruption ??= executionError(fail(), stage, code, mcpDetail()); };
         let timer, external;
         try {
             this.assertContext(ctx, jobId);
             requireOfficialExecPlan(this.plan);
             if (typeof prompt !== 'string' || !prompt || prompt.length > 1_000_000 || signal?.aborted)
                 throw fail();
-            const stopped = new Promise((_, reject) => { external = () => { void this.cancel().catch(() => { }); reject(fail()); }; this.abort.signal.addEventListener('abort', () => reject(fail()), { once: true }); signal?.addEventListener('abort', external, { once: true }); timer = setTimeout(external, 30_000); });
+            const stopped = new Promise((_, reject) => { external = () => { interrupt('CODEX_EXEC_ABORTED'); void this.cancel().catch(() => { }); reject(interruption); }; this.abort.signal.addEventListener('abort', () => reject(interruption ?? fail()), { once: true }); signal?.addEventListener('abort', external, { once: true }); timer = setTimeout(() => { interrupt('CODEX_EXEC_PREPARATION_TIMEOUT'); external(); }, 30_000); });
             const preparation = (async () => {
                 const supported = isReleaseExecMode(this.plan.mode);
+                stage = 'codex_inspection';
                 this.inspection = await (supported ? this.deps.inspectRelease?.(this.plan, this.abort.signal) : this.deps.inspect?.(this.plan, this.abort.signal));
                 const assessment = supported ? assessReleaseExec(this.inspection?.snapshot, this.plan) : assessExecPreflight(this.inspection?.snapshot, this.plan);
                 if (!supported && !this.deps.inspect)
@@ -84,6 +90,7 @@ export class CodexExecLaunchHost {
                 if (manual && typeof this.inspection.beforeSpawn !== 'function')
                     throw fail();
                 this.inspection.beforeSpawn?.();
+                stage = 'codex_spawn';
                 const h = this.deps.processHost.spawn(invocation.binary, invocation.args, { cwd: this.plan.cwd, env: invocation.env });
                 this.handle = h;
                 if (this.stopped) {
@@ -91,6 +98,8 @@ export class CodexExecLaunchHost {
                     throw fail();
                 }
                 h.once('exit', (code, signal) => {
+                    if (!this.stopped && !this.receiptValue)
+                        interrupt('CODEX_EXEC_PROCESS_EXITED');
                     // Preserve audit only for a clean owned exit that was still authorized.
                     // This immutable record never restores tool or spawn authority.
                     if (code === 0 && signal === null && !this.stopped && this.receiptValue) {
@@ -119,6 +128,7 @@ export class CodexExecLaunchHost {
                     h.stdin.end();
                     this.current();
                     gate.promptSubmitted(h);
+                    stage = 'codex_mcp';
                     const observed = await gate.wait(h, this.abort.signal);
                     this.current();
                     requireExecHandshake(observed, h, this.plan);
@@ -147,9 +157,10 @@ export class CodexExecLaunchHost {
             })();
             return await Promise.race([preparation, stopped]);
         }
-        catch {
+        catch (error) {
+            const safe = executionError(interruption ?? error, stage, 'CODEX_EXEC_PREFLIGHT_REJECTED', mcpDetail());
             await this.cancel().catch(() => { });
-            throw fail();
+            throw safe;
         }
         finally {
             if (timer)

package/dist/src/adapters/codex/exec-runtime-options.js

@@ -1,3 +1,4 @@
+import { executionError } from '../../safety/execution-failure.js';
 import path from 'node:path';
 import { mkdtemp, mkdir, realpath, writeFile, rm, lstat } from 'node:fs/promises';
 import { NodeProcessGroupHost } from '../../process/node-process-group-host.js';
@@ -46,12 +47,14 @@ export function buildCodexExecJobOptions(input) {
             used = true;
             const abort = () => { void close().catch(() => { }); };
             signal.addEventListener('abort', abort, { once: true });
+            let stage = 'codex_prepare';
             try {
                 job = input.productionJob();
                 job.attachCleanup(close);
                 const admitted = await job.prepare(ctx);
                 if (closed || signal.aborted)
                     throw reject();
+                stage = 'codex_storage';
                 if (!input.env.HOME || !path.isAbsolute(input.stateRoot))
                     throw reject();
                 const account = path.resolve(input.env.CODEX_HOME ?? path.join(input.env.HOME, '.codex'));
@@ -64,6 +67,7 @@ export function buildCodexExecJobOptions(input) {
                 await Promise.all([cwd, ...Object.values(scratch)].map(p => mkdir(p, { mode: 0o700 })));
                 if (closed || signal.aborted)
                     throw reject();
+                stage = 'codex_config_ancestry';
                 for (let dir = cwd;; dir = path.dirname(dir)) {
                     for (const base of ['.codex/config.toml']) {
                         const f = path.join(dir, base);
@@ -81,16 +85,20 @@ export function buildCodexExecJobOptions(input) {
                     if (dir === path.dirname(dir))
                         break;
                 }
+                stage = 'codex_storage';
                 const schema = path.join(control, 'report-schema.json');
                 await writeFile(schema, JSON.stringify(CODEX_REPORT_SCHEMA), { mode: 0o600, flag: 'wx' });
                 if (closed || signal.aborted)
                     throw reject();
                 const approved = ctx.approvedTaskPackage, requirements = approved.security_requirements;
+                stage = 'codex_tool_policy';
                 policy = new LocalToolPolicy(jobToolPolicyOptions(source, ctx.taskPackage, approved, admitted.release.commands, { runtimeAdapter: 'codex_cli', runtimeAdapterVersion: '1' }));
+                stage = 'codex_tool_server';
                 server = new LocalToolServer({ policy, authorizeCall: () => gate?.allowsCall() === true, onDiscovery: (event, scope) => gate?.discovery(event, scope) });
                 const endpoint = await server.start();
                 if (closed || signal.aborted)
                     throw reject();
+                stage = 'codex_invocation';
                 const plan = buildOfficialExecPlan({ policyMode: admitted.release.securityMode, binary: admitted.binary, credentialBackend: admitted.release.credentialBackend, identity: { jobId: input.jobId, generation: ctx.generation, actorId: admitted.actorId, runnerId: admitted.runnerId, sourceSha: String(approved.repository.base_commit_sha), binarySha256: admitted.release.binarySha256, releaseManifestFingerprint: String(requirements.release_manifest_sha256), requirementsFingerprint: String(requirements.fingerprint), contractFingerprint: ctx.securityBinding.contractFingerprint, taskPackageFingerprint: ctx.securityBinding.taskPackageFingerprint, launchFingerprint: ctx.securityBinding.launchFingerprint, commandsFingerprint: commandRegistryFingerprint(admitted.release.commands), toolSchemaFingerprint: fingerprint({ tools: localToolInventory() }), barrierFingerprint: admitted.release.fixturesFingerprint }, invocation: { modelId: ctx.resolvedModelId, worktreeRoot: cwd, sourceRoot: source, schemaPath: schema, endpoint, env, scratch } });
                 gate = new ExecToolGate(plan);
                 const host = new CodexExecLaunchHost(plan, { processHost, inspectRelease: p => job.inspect(p), execTools: gate, revokeTools: () => { gate?.revoke(); server?.revoke(); policy?.revoke(); job?.revoke(); }, closeTools: dispose });
@@ -99,11 +107,12 @@ export function buildCodexExecJobOptions(input) {
                     throw reject();
                 return host;
             }
-            catch {
+            catch (error) {
+                const safe = executionError(error, stage, 'CODEX_EXEC_COMPOSITION_REJECTED');
                 await close().catch(() => { });
                 if (control)
                     await rm(control, { recursive: true, force: true }).catch(() => { });
-                throw reject();
+                throw safe;
             }
             finally {
                 signal.removeEventListener('abort', abort);

package/dist/src/adapters/codex/exec-tool-gate.js

@@ -1,6 +1,7 @@
 import { isReleaseExecMode, requireOfficialExecPlan } from './exec-invocation.js';
 import { localDiscoveryScopeMatches, localToolInventory } from '../../safety/local-tool-server.js';
 import { securityRequirementsFingerprint as hash } from '../../safety/security-requirements.js';
+import { executionError } from '../../safety/execution-failure.js';
 const denied = () => Error('EXEC_TOOL_GATE_REJECTED');
 /** Host-owned capability, never populated from stdout/task data. Authenticated
  * discovery is server-side evidence; it does not attest OS client identity. */
@@ -29,6 +30,9 @@ export class ExecToolGate {
     catch {
         return false;
     } }
+    /** Metadata only: survives revocation; contains no endpoint or credential. */
+    discoveryDetail() { return ['mcp_initialize_missing', 'mcp_initialized_missing', 'mcp_inventory_missing', 'mcp_discovery_complete'][this.stage]; }
+    readinessError() { return executionError(denied(), 'codex_mcp', 'CODEX_EXEC_MCP_REJECTED', this.discoveryDetail()); }
     promptSubmitted(process) { if (this.process !== process || this.submitted || !this.active())
         throw denied(); this.submitted = true; }
     discovery = (event, scope) => {
@@ -60,17 +64,17 @@ export class ExecToolGate {
     };
     async wait(process, signal) {
         if (this.process !== process || !this.submitted || !this.active() || signal.aborted)
-            throw denied();
+            throw this.readinessError();
         if (this.stage !== 3)
             await new Promise((resolve, reject) => {
-                const abort = () => { clear(); reject(denied()); };
+                const abort = () => { clear(); reject(this.readinessError()); };
                 const clear = () => { signal.removeEventListener('abort', abort); this.settle = undefined; this.reject = undefined; };
                 this.reject = abort;
                 this.settle = () => { clear(); resolve(); };
                 signal.addEventListener('abort', abort, { once: true });
             });
         if (!this.active() || signal.aborted || this.stage !== 3)
-            throw denied();
+            throw this.readinessError();
         return { process, executionNonce: this.plan.executionNonce, endpoint: this.plan.endpoint, authenticated: true, ready: true, toolSchemaFingerprint: this.plan.identity.toolSchemaFingerprint, tools: localToolInventory().map(t => t.name), isCurrent: () => this.active() && this.stage === 3 };
     }
     authorize(process) { if (process !== this.process || !this.active() || this.stage !== 3)

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

@@ -1,3 +1,4 @@
+import { executionError, executionFailure } from '../safety/execution-failure.js';
 import { requireSecurityRequirements } from '../safety/security-requirements.js';
 import { GatewayToolError } from "../gateway-client.js";
 import { createHash } from "node:crypto";
@@ -122,7 +123,8 @@ export class ExecutionCoordinator {
             return;
         }
         await this.deps.state.save({ jobId: job.id, generation: job.generation, leaseToken: job.leaseToken, phase: "running", bindingId: binding.bindingId, workspaceManifest: workspace.manifest });
-        let heartbeatFailure = null;
+        let heartbeatFailure;
+        let executionStage = 'binding_model';
         let requestedTerminal;
         let commandCursor = 0;
         let controlsStopped = false;
@@ -154,23 +156,29 @@ export class ExecutionCoordinator {
             try {
                 await controlsInFlight;
             }
+            catch (error) {
+                throw executionError(error, 'commands', 'EXECUTION_FAILED');
+            }
             finally {
                 controlsInFlight = undefined;
             }
         };
         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) => {
-                heartbeatFailure = error instanceof Error ? error : new Error(String(error));
+                heartbeatFailure = executionError(error, 'heartbeat', 'EXECUTION_FAILED');
                 await adapter.cancel().catch(() => undefined);
             });
         }, 30_000) : undefined;
         heartbeatTimer?.unref();
         let terminal;
+        let failureDiagnostic;
         let sequence = 0;
         let checkpointSeen = false;
         const append = async (event) => {
+            const previousStage = executionStage;
             let payload = event.payload;
             if (isTerminalEventType(event.eventType)) {
+                executionStage = 'terminal_evidence';
                 const evidence = this.deps.terminalEvidenceCollector.collect({ checkoutPath: workspace.path, baseSha: workspace.baseCommitSha });
                 payload = { ...payload, diff_hash: evidence.diffHash, changed_file_manifest_hash: evidence.changedFileManifestHash };
             }
@@ -181,21 +189,27 @@ export class ExecutionCoordinator {
                 ...(payload ? { payload } : {}),
                 idempotencyKey: `${binding.bindingId}:${sequence + 1}`, occurredAt: new Date().toISOString(),
             };
+            executionStage = 'event_report';
             validateEvent(normalized);
             if (!this.deps.gateway.appendEvent)
                 throw new Error("daemon event reporting is unavailable");
             await this.deps.gateway.appendEvent(binding.bindingId, normalized);
             sequence = normalized.sequence;
+            executionStage = 'state_save';
             if (event.eventType === "checkpoint_ready")
                 checkpointSeen = true;
             await this.deps.state.save({ jobId: job.id, generation: job.generation, leaseToken: job.leaseToken, phase: "running", bindingId: binding.bindingId, eventCursor: sequence, ...(isTerminalEventType(event.eventType) ? { terminalEventType: event.eventType } : {}), workspaceManifest: workspace.manifest });
+            executionStage = previousStage;
         };
         try {
             if (!job.taskPackage.resolved_model_id
                 || binding.resolvedModelId !== job.taskPackage.resolved_model_id)
                 throw new Error("Binding model differs from approved launch");
+            executionStage = 'adapter_start';
             await adapter.start({ securityBinding: { launchFingerprint: job.launchFingerprint, contractFingerprint: job.gatewayContractFingerprint, taskPackageFingerprint: job.gatewayTaskPackageFingerprint }, generation: job.generation, approvedTaskPackage: job.taskPackage, bindingId: binding.bindingId, sessionId: binding.bindingId, taskPackage: binding.taskPackage, resolvedModelId: binding.resolvedModelId });
+            executionStage = 'commands';
             await readControls();
+            executionStage = 'event_stream';
             if (adapter.events && !requestedTerminal) {
                 for await (const event of adapter.events()) {
                     if (heartbeatFailure)
@@ -238,7 +252,14 @@ export class ExecutionCoordinator {
             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.
-            terminal = { eventType: "failed", summary: "daemon execution or event reporting failed" };
+            const diagnostic = executionFailure(error, executionStage);
+            failureDiagnostic = diagnostic;
+            // Log before reporting so an unavailable Gateway does not erase the cause.
+            try {
+                this.deps.reportExecutionFailure?.({ ...diagnostic });
+            }
+            catch { /* logging must not change terminal reconciliation */ }
+            terminal = { eventType: "failed", summary: "daemon execution or event reporting failed", payload: { execution_failure: { ...diagnostic } } };
             await append(terminal);
         }
         finally {
@@ -247,7 +268,7 @@ export class ExecutionCoordinator {
                 clearInterval(heartbeatTimer);
         }
         const status = terminal.eventType === "completed" ? "completed" : terminal.eventType === "cancelled" ? "cancelled" : terminal.eventType === "blocked" || terminal.eventType === "scope_conflict" ? "blocked" : "failed";
-        await this.deps.gateway.complete({ jobId: job.id, generation: job.generation, leaseToken: job.leaseToken, status, result: { binding_id: binding.bindingId, event_type: terminal.eventType, summary: terminal.summary, ...(adapter.securityReceipt?.() ? { security_receipt: adapter.securityReceipt() } : {}) } });
+        await this.deps.gateway.complete({ 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 } } : {}), ...(adapter.securityReceipt?.() ? { security_receipt: adapter.securityReceipt() } : {}) } });
         await this.deps.state.clear();
     }
 }

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

@@ -40,6 +40,7 @@ export async function runManualCodexJob(input, deps) {
         await state.save({ jobId: job.id, generation: job.generation, leaseToken: job.leaseToken, phase: 'claimed' });
         let result = { jobId: job.id, status: 'unacknowledged' };
         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'),
             registry: { async select(id, version, options) {
                     if (id !== 'codex_cli' || version !== '1' || options.jobId !== job.id)

package/dist/src/daemon/runtime.js

@@ -43,6 +43,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({
+        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: {

package/dist/src/safety/codex-manual-controller.js

@@ -1,3 +1,4 @@
+import { executionError } from './execution-failure.js';
 import { eligiblePersonalAccount } from '../adapters/codex/unmanaged-scope.js';
 import { securityRequirementsFingerprint as hash } from './security-requirements.js';
 import { commandRegistryFingerprint } from './job-security-session.js';
@@ -29,26 +30,33 @@ export function createManualPilotController(input, deps) {
             if (used || closed)
                 throw rejected();
             used = true;
+            let stage = 'codex_manual_inputs';
             try {
                 if (!readLocal || !path.isAbsolute(input.binary) || !path.isAbsolute(input.home) || await realpath(input.home) !== input.home || await realpath(account) !== account)
                     throw rejected();
+                stage = 'codex_manual_release';
                 const sha = await measureCommandFile(input.binary), matches = releases.filter(r => reviewedCodexExecRelease(r) && r.mdmVerification === 'manual_prelaunch' && r.binarySha256 === sha);
                 if (matches.length !== 1)
                     throw rejected();
                 const release = matches[0], requirements = claim.task_package?.security_requirements;
+                stage = 'codex_manual_config';
                 const config = parse((await readStableText(path.join(account, 'config.toml'))).text);
                 if ((config.cli_auth_credentials_store ?? 'auto') !== release.credentialBackend || requirements?.release_manifest_sha256 !== execReleaseFingerprint(release) || requirements?.mdm_verification !== 'manual_prelaunch')
                     throw rejected();
                 host = createCodexExecProductionHost({ runnerId: input.runnerId, binary: input.binary, home: input.home, codexHome: account, releases: [release], readNativeAuth: deps?.readNativeAuth, policyScopeVerifier: { observe() { if (closed || !manual)
                             throw rejected(); return manual.observe(); } } });
                 // Full claim/requirements validation precedes any privileged query.
+                stage = 'codex_manual_claim';
                 host.registerClaim(claim);
+                stage = 'codex_manual_auth';
                 const credential = release.credentialBackend === 'auto' ? deps?.readNativeAuth?.(account, 'auto') : await readCodexCredentialStatus(account);
                 if (!credential || credential.backend !== release.credentialBackend || !credential.available || !Number.isFinite(credential.expiresAt) || credential.expiresAt <= now())
                     throw rejected();
+                stage = 'codex_manual_requirements';
                 const job = claim.job, p = claim.task_package, r = requirements;
                 if (r.security_mode !== release.securityMode || r.binary_sha256 !== release.binarySha256 || r.fixtures_sha256 !== release.fixturesFingerprint || r.commands_sha256 !== commandRegistryFingerprint(release.commands) || r.tools_sha256 !== fingerprint({ tools: localToolInventory() }) || !isDeepStrictEqual(r.model_ids, release.modelIds) || !release.modelIds.includes(String(p.resolved_model_id)))
                     throw rejected();
+                stage = 'codex_manual_local_policy';
                 const local = readLocal();
                 if (!eligiblePersonalAccount(local.account) || local.account.backend !== release.credentialBackend || local.account.rootFingerprint !== hash({ accountRoot: account }) || !isDeepStrictEqual(Object.keys(local.sources).sort(), ['legacy_managed', 'system_defaults', 'system_requirements']) || Object.values(local.sources).some(s => !isDeepStrictEqual(Object.keys(s).sort(), ['fingerprint', 'status']) || !/^[a-f0-9]{64}$/.test(s.fingerprint)))
                     throw rejected();
@@ -56,17 +64,21 @@ export function createManualPilotController(input, deps) {
                     throw rejected();
                 if (closed)
                     throw rejected();
+                stage = 'codex_manual_inventory';
                 const inventory = await (deps?.collectInventory ?? createManualProfileQuery().collectOnce)();
                 if (closed)
                     throw rejected();
+                stage = 'codex_manual_policy_scope';
                 manual = createManualPolicyScopeVerifier({ binding: { jobId: job.id, generation: job.generation, actorId: claim.security_context.actor_id, runnerId: input.runnerId, sourceSha: p.repository.base_commit_sha, binarySha256: release.binarySha256, releaseManifestFingerprint: String(r.release_manifest_sha256), requirementsFingerprint: String(r.fingerprint), contractFingerprint: claim.contract_fingerprint, taskPackageFingerprint: claim.task_package_fingerprint, launchFingerprint: job.launch_fingerprint, commandsFingerprint: String(r.commands_sha256), toolSchemaFingerprint: String(r.tools_sha256), barrierFingerprint: String(r.fixtures_sha256) }, leaseDigest: createHash('sha256').update(claim.lease_token).digest('hex'), inventory, readLocal, now });
+                stage = 'codex_manual_host_probe';
                 if (!(await host.probe()).available || closed)
                     throw rejected();
                 return host;
             }
-            catch {
+            catch (error) {
+                const safe = executionError(error, stage, 'CODEX_MANUAL_PILOT_REJECTED');
                 await close().catch(() => { });
-                throw rejected();
+                throw safe;
             }
         } });
 }

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

@@ -0,0 +1,36 @@
+import { GatewayToolError } from '../gateway-client.js';
+const issued = new WeakMap();
+export function executionFailure(error, stage, fallback = 'EXECUTION_FAILED') {
+    if (error && typeof error === 'object') {
+        const trusted = issued.get(error);
+        if (trusted)
+            return { ...trusted };
+        try {
+            if (error instanceof GatewayToolError && (error.code === 'GATEWAY_TOOL_REJECTED' || error.code === 'GATEWAY_TRANSPORT_ERROR' || error.code === 'WORK_LOOP_CANCELLED')) {
+                return { stage, code: error.code };
+            }
+        }
+        catch { /* revoked proxies and prototype traps have no diagnostic authority */ }
+        // Do not invoke error getters or accept arbitrary uppercase strings.
+        let code;
+        try {
+            code = Object.getOwnPropertyDescriptor(error, 'code')?.value;
+        }
+        catch { /* hostile proxy has no diagnostic authority */ }
+        const mapped = code === 'EACCES' || code === 'EPERM' ? 'LOCAL_ACCESS_DENIED'
+            : code === 'ENOENT' ? 'LOCAL_FILE_MISSING' : code === 'ENOSPC' ? 'LOCAL_STORAGE_FULL' : undefined;
+        if (mapped)
+            return { stage, code: mapped };
+    }
+    return { stage, code: fallback };
+}
+export function executionError(error, stage, fallback, detail) {
+    const diagnostic = executionFailure(error, stage, fallback);
+    // Only trusted callers supply this fixed vocabulary. Serialized provider
+    // errors, messages and stderr never become diagnostic authority.
+    if (!issued.has(error) && ['mcp_initialize_missing', 'mcp_initialized_missing', 'mcp_inventory_missing', 'mcp_discovery_complete'].includes(detail))
+        diagnostic.detail = detail;
+    const safe = new Error(fallback);
+    issued.set(safe, Object.freeze(diagnostic));
+    return safe;
+}

package/package.json

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