mtech-ai-local-runner 0.1.11 → 0.1.12

package/README.md

@@ -125,6 +125,18 @@ or cost termination limits on an approved unbounded employee-local Claude run.
 Existing generation fencing, scope restrictions, cancellation and audit remain
 in force.
 
+### 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,6 +62,7 @@ export class CodexExecLaunchHost {
         claimOfficialExecPlan(this.plan);
         this.ownsAttempt = true;
         this.used = true;
+        let stage = 'codex_context';
         let timer, external;
         try {
             this.assertContext(ctx, jobId);
@@ -70,6 +72,7 @@ export class CodexExecLaunchHost {
             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 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 +87,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) {
@@ -119,6 +123,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 +152,10 @@ export class CodexExecLaunchHost {
             })();
             return await Promise.race([preparation, stopped]);
         }
-        catch {
+        catch (error) {
+            const safe = executionError(error, stage, 'CODEX_EXEC_PREFLIGHT_REJECTED');
             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/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,32 @@
+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) {
+    const diagnostic = executionFailure(error, stage, fallback);
+    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.12",
   "private": false,
   "license": "UNLICENSED",
   "bin": {