mtech-ai-local-runner 0.1.18 → 0.1.19

package/README.md

@@ -10,6 +10,22 @@ 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

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

@@ -1,4 +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';
@@ -11,7 +12,6 @@ import { officialExecObservationLimits } from './exec-observer.js';
 import { EXEC_GATES, assessExecPreflight, requireExecHandshake } from './exec-preflight.js';
 import { EXEC_MODE, isReleaseExecMode, EXEC_TRANSPORT, assertOfficialExecPlanAvailable, claimOfficialExecPlan, requireOfficialExecPlan } from './exec-invocation.js';
 const fail = () => new Error('CODEX_EXEC_PREFLIGHT_REJECTED');
-const PREPARATION_TIMEOUT_MS = 30_000;
 /** No default native inspector, handshake observer or OS process host is created.
  * Missing per-execution evidence blocks before spawn. Synthetic callbacks grant
  * only the fake host used by tests, never a compiled production release entry. */
@@ -70,11 +70,13 @@ 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 = performance.now() + PREPARATION_TIMEOUT_MS;
+        const deadline = timing.deadline;
         const assertPreparationBudget = () => { if (performance.now() >= deadline) {
             interrupt('CODEX_EXEC_PREPARATION_TIMEOUT');
             throw interruption;
@@ -85,11 +87,13 @@ export class CodexExecLaunchHost {
             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(); }, PREPARATION_TIMEOUT_MS); });
+            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)
@@ -104,11 +108,15 @@ export class CodexExecLaunchHost {
                 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();
@@ -141,15 +149,21 @@ 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);
@@ -159,10 +173,13 @@ export class CodexExecLaunchHost {
                     assertPreparationBudget();
                     requireExecHandshake(observed, h, this.plan);
                     assertPreparationBudget();
-                    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 });
+                    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);
@@ -174,21 +191,27 @@ export class CodexExecLaunchHost {
                 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);
                 assertPreparationBudget();
-                this.receiptValue = receipt;
+                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.18",
+  "version": "0.1.19",
   "private": false,
   "license": "UNLICENSED",
   "bin": {