mtech-ai-local-runner 0.1.17 → 0.1.19

package/README.md

@@ -10,6 +10,34 @@ The package stores safe runner configuration locally and keeps OAuth refresh cre
 
 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`).
 
+## 0.1.19: bounded preparation phase timing
+
+Record fixed host milestones with monotonic elapsed milliseconds and remaining
+original 30-second budget: inspection, before-spawn checks, spawn request/return,
+prompt write/end request/return, MCP wait/discovery and authorization/failure.
+Safe timing survives cleanup into local diagnostics, failed events and terminal
+results; successful admission also retains it in the security receipt. No prompts,
+arguments, paths, URLs, credentials or raw provider text are included.
+
+This separates pre-spawn budget consumption from post-spawn MCP waiting. Spawn
+return and pipe-call return do not prove native start or stdin consumption, and
+these timings do not establish the historical native wait's cause. The deadline,
+tool/identity checks and unlimited admitted employee work are unchanged. No
+sampler, extra permission, retry, real account run or daemon update is implied.
+See [phase timing and remaining conditions](https://bitbucket.org/mtechbal/api-cloud-service-ai-gateway/src/development/docs/ai-ops-gateway/codex-preparation-phase-timing.md).
+
+## 0.1.18: preparation deadline enforcement
+
+The overall 30-second preparation budget also covers release inspection. A
+synchronous metadata check can delay JavaScript timer callbacks. Local guards
+now use a monotonic deadline after inspection and at spawn/input/admission
+boundaries, refusing expired preparation even when its timer has not run. The
+budget is not reset or extended; admitted employee work remains unbounded.
+Fake callbacks reproduce the late-admission defect. Existing 0.1.17 receipts do
+not contain phase timing, so this is not proof of the historical native wait's
+cause or successful real-account connectivity. No new native stack sampler,
+account operation, daemon change or actual CLI run is part of this correction.
+
 ## 0.1.17: owned startup, pipe and transport observations
 
 An owned-process collector marker distinguishes available diagnostics from a

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

@@ -1,3 +1,5 @@
+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 { processStartupObservations } from '../../process/node-process-group-host.js';
 import { executionError } from '../../safety/execution-failure.js';
@@ -68,18 +70,31 @@ export class CodexExecLaunchHost {
         let interruption;
         const mcpDetail = () => stage === 'codex_mcp' ? this.deps.execTools?.discoveryDetail() : undefined;
         const observations = () => { const invocation = requireOfficialExecPlan(this.plan); return [...(this.handle ? processStartupObservations(this.handle) : []), ...localEndpointObservations(this.plan.endpoint, invocation.env.AI_GATEWAY_JOB_MCP_TOKEN)]; };
-        const interrupt = (code) => { interruption ??= executionError(fail(), stage, code, mcpDetail(), observations()); };
+        const timing = new PreparationClock();
+        timing.mark('preparation_start');
+        const interrupt = (code) => { timing.mark('preparation_failed'); interruption ??= executionError(fail(), stage, code, mcpDetail(), observations(), timing.snapshot()); };
+        // Timer callbacks cannot interrupt synchronous native metadata checks. Keep
+        // the same total budget and enforce it at effect boundaries with a monotonic
+        // clock, rather than spawning/submitting after an already expired inspection.
+        const deadline = timing.deadline;
+        const assertPreparationBudget = () => { if (performance.now() >= deadline) {
+            interrupt('CODEX_EXEC_PREPARATION_TIMEOUT');
+            throw interruption;
+        } };
         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 = () => { 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 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(); }, CODEX_PREPARATION_BUDGET_MS); });
             const preparation = (async () => {
                 const supported = isReleaseExecMode(this.plan.mode);
                 stage = 'codex_inspection';
+                timing.mark('inspection_start');
                 this.inspection = await (supported ? this.deps.inspectRelease?.(this.plan, this.abort.signal) : this.deps.inspect?.(this.plan, this.abort.signal));
+                timing.mark('inspection_complete');
+                assertPreparationBudget();
                 const assessment = supported ? assessReleaseExec(this.inspection?.snapshot, this.plan) : assessExecPreflight(this.inspection?.snapshot, this.plan);
                 if (!supported && !this.deps.inspect)
                     assessment.reasonCodes.push(...officialExecObservationLimits());
@@ -92,10 +107,16 @@ export class CodexExecLaunchHost {
                 const manual = ctx.approvedTaskPackage?.security_requirements?.mdm_verification === 'manual_prelaunch';
                 if (manual && typeof this.inspection.beforeSpawn !== 'function')
                     throw fail();
+                assertPreparationBudget();
+                timing.mark('before_spawn_start');
                 this.inspection.beforeSpawn?.();
+                timing.mark('before_spawn_complete');
+                assertPreparationBudget();
                 stage = 'codex_spawn';
+                timing.mark('spawn_requested');
                 const h = this.deps.processHost.spawn(invocation.binary, invocation.args, { cwd: this.plan.cwd, env: invocation.env });
                 this.handle = h;
+                timing.mark('spawn_returned');
                 if (this.stopped) {
                     h.kill('SIGKILL');
                     throw fail();
@@ -115,6 +136,7 @@ export class CodexExecLaunchHost {
                     void this.cancel().catch(() => { });
                 });
                 this.current();
+                assertPreparationBudget();
                 if (supported) {
                     const gate = this.deps.execTools;
                     gate.bind(h, () => { try {
@@ -126,42 +148,70 @@ export class CodexExecLaunchHost {
                     } });
                     // Vendor exec consumes stdin before it can initialize its required MCP.
                     // Prompt submission may cause provider/account effects; do not call this no-model.
+                    assertPreparationBudget();
+                    timing.mark('prompt_write_requested');
                     h.stdin.write(prompt);
+                    timing.mark('prompt_write_returned');
                     this.current();
+                    assertPreparationBudget();
+                    timing.mark('prompt_end_requested');
                     h.stdin.end();
+                    timing.mark('prompt_end_returned');
                     this.current();
+                    assertPreparationBudget();
                     gate.promptSubmitted(h);
                     stage = 'codex_mcp';
+                    timing.mark('mcp_wait_started');
                     const observed = await gate.wait(h, this.abort.signal);
+                    timing.mark('mcp_discovery_complete');
                     this.current();
+                    assertPreparationBudget();
                     requireExecHandshake(observed, h, this.plan);
+                    assertPreparationBudget();
                     gate.authorize(h);
                     this.current();
+                    assertPreparationBudget();
                     requireExecHandshake(observed, h, this.plan);
-                    this.receiptValue = Object.freeze({ receipt_version: this.plan.mode === UNMANAGED_EXEC_MODE ? 'cli-exec-job-security-receipt-v3' : 'cli-exec-job-security-receipt-v2', evidence_origin: 'employee_runner', transport: EXEC_TRANSPORT, security_mode: this.plan.mode, ...(this.plan.mode === UNMANAGED_EXEC_MODE ? { policy_scope: this.inspection.snapshot.policyScope } : {}), phase: 'post_prompt_mcp_authorized', policy_evidence: 'reviewed_release_and_current_inputs', mcp_evidence: 'authenticated_server_discovery', native_policy_observed: false, first_inference_observed: false, execution_nonce: this.plan.executionNonce, invocation_fingerprint: this.plan.invocationFingerprint, ...this.plan.identity });
+                    assertPreparationBudget();
+                    timing.mark('preparation_authorized');
+                    this.receiptValue = Object.freeze({ preparation_timing: timing.snapshot(), receipt_version: this.plan.mode === UNMANAGED_EXEC_MODE ? 'cli-exec-job-security-receipt-v3' : 'cli-exec-job-security-receipt-v2', evidence_origin: 'employee_runner', transport: EXEC_TRANSPORT, security_mode: this.plan.mode, ...(this.plan.mode === UNMANAGED_EXEC_MODE ? { policy_scope: this.inspection.snapshot.policyScope } : {}), phase: 'post_prompt_mcp_authorized', policy_evidence: 'reviewed_release_and_current_inputs', mcp_evidence: 'authenticated_server_discovery', native_policy_observed: false, first_inference_observed: false, execution_nonce: this.plan.executionNonce, invocation_fingerprint: this.plan.invocationFingerprint, ...this.plan.identity });
                     return h;
                 }
+                timing.mark('mcp_wait_started');
                 const handshake = await this.deps.handshake?.(h, this.plan, this.abort.signal);
+                timing.mark('mcp_discovery_complete');
                 this.current();
+                assertPreparationBudget();
                 requireExecHandshake(handshake, h, this.plan);
                 this.handshake = handshake;
                 // An input hash is not a native effective-config certificate. Preserve the
                 // evidence origin in the audit receipt and never reuse AppServer authority.
                 const receipt = Object.freeze({ receipt_version: 'cli-exec-job-security-receipt-v1', evidence_origin: 'employee_runner', transport: EXEC_TRANSPORT, security_mode: EXEC_MODE, phase: 'exec_pre_prompt', execution_nonce: this.plan.executionNonce, invocation_fingerprint: this.plan.invocationFingerprint, ...this.plan.identity });
                 this.current();
+                assertPreparationBudget();
                 requireExecHandshake(handshake, h, this.plan);
+                assertPreparationBudget();
+                timing.mark('prompt_write_requested');
                 h.stdin.write(prompt);
+                timing.mark('prompt_write_returned');
                 this.current();
+                assertPreparationBudget();
+                timing.mark('prompt_end_requested');
                 h.stdin.end();
+                timing.mark('prompt_end_returned');
                 this.current();
+                assertPreparationBudget();
                 requireExecHandshake(handshake, h, this.plan);
-                this.receiptValue = receipt;
+                assertPreparationBudget();
+                timing.mark('preparation_authorized');
+                this.receiptValue = Object.freeze({ ...receipt, preparation_timing: timing.snapshot() });
                 return h;
             })();
             return await Promise.race([preparation, stopped]);
         }
         catch (error) {
-            const safe = executionError(interruption ?? error, stage, 'CODEX_EXEC_PREFLIGHT_REJECTED', mcpDetail(), observations());
+            timing.mark('preparation_failed');
+            const safe = executionError(interruption ?? error, stage, 'CODEX_EXEC_PREFLIGHT_REJECTED', mcpDetail(), observations(), timing.snapshot());
             await this.cancel().catch(() => { });
             throw safe;
         }

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

@@ -1,3 +1,4 @@
+import { trustedPreparationTiming } from './preparation-timing.js';
 import { GatewayToolError } from '../gateway-client.js';
 /** Observations only: provider text cannot authorize a tool or certify a cause. */
 export const STARTUP_OBSERVATIONS = Object.freeze([
@@ -15,7 +16,7 @@ export function executionFailure(error, stage, fallback = 'EXECUTION_FAILED') {
     if (error && typeof error === 'object') {
         const trusted = issued.get(error);
         if (trusted)
-            return { ...trusted, ...(trusted.observations ? { observations: [...trusted.observations] } : {}) };
+            return structuredClone(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 };
@@ -35,7 +36,7 @@ export function executionFailure(error, stage, fallback = 'EXECUTION_FAILED') {
     }
     return { stage, code: fallback };
 }
-export function executionError(error, stage, fallback, detail, observations) {
+export function executionError(error, stage, fallback, detail, observations, preparationTiming) {
     const diagnostic = executionFailure(error, stage, fallback);
     // Only trusted callers supply this fixed vocabulary. Serialized provider
     // errors, messages and stderr never become diagnostic authority.
@@ -46,6 +47,11 @@ export function executionError(error, stage, fallback, detail, observations) {
         if (fixed.length)
             diagnostic.observations = fixed;
     }
+    if (!diagnostic.preparation_timing) {
+        const timing = trustedPreparationTiming(preparationTiming);
+        if (timing)
+            diagnostic.preparation_timing = timing;
+    }
     const safe = new Error(fallback);
     issued.set(safe, Object.freeze(diagnostic));
     return safe;

package/dist/src/safety/preparation-timing.js

@@ -0,0 +1,37 @@
+import { performance } from 'node:perf_hooks';
+export const CODEX_PREPARATION_BUDGET_MS = 30_000;
+const PHASES = [
+    'preparation_start', 'inspection_start', 'inspection_complete', 'before_spawn_start', 'before_spawn_complete',
+    'spawn_requested', 'spawn_returned', 'prompt_write_requested', 'prompt_write_returned',
+    'prompt_end_requested', 'prompt_end_returned', 'mcp_wait_started', 'mcp_discovery_complete',
+    'preparation_authorized', 'preparation_failed',
+];
+// Only snapshots issued here are accepted by the error-reporting boundary.
+// JSON/provider/task objects, getters and copied snapshots carry no authority.
+const issued = new WeakMap();
+export function trustedPreparationTiming(value) {
+    const data = value && typeof value === 'object' ? issued.get(value) : undefined;
+    return data ? structuredClone(data) : undefined;
+}
+/** Fixed, one-shot milestone set: no payloads, wall-clock dates, polling or I/O.
+ * Times describe the host boundary, never native stdin consumption or policy. */
+export class PreparationClock {
+    started = performance.now();
+    deadline = this.started + CODEX_PREPARATION_BUDGET_MS;
+    points = [];
+    mark(phase) {
+        if (!PHASES.includes(phase) || this.points.some(p => p.phase === phase))
+            return;
+        const previous = this.points.at(-1)?.elapsed_ms ?? 0, elapsed = performance.now() - this.started;
+        // Bound serialized numbers and keep telemetry monotonic even on an invalid
+        // clock reading. The operational deadline still uses the original clock.
+        const elapsed_ms = Math.max(previous, Number.isFinite(elapsed) ? Math.min(2_147_483_647, Math.max(0, Math.floor(elapsed))) : previous);
+        this.points.push({ phase, elapsed_ms, remaining_ms: Math.max(0, CODEX_PREPARATION_BUDGET_MS - elapsed_ms) });
+    }
+    snapshot() {
+        const data = { version: 'codex-preparation-timing-v1', budget_ms: CODEX_PREPARATION_BUDGET_MS, points: structuredClone(this.points) };
+        const token = structuredClone(data);
+        issued.set(token, data);
+        return token;
+    }
+}

package/package.json

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