mtech-ai-local-runner 0.1.19 → 0.1.20

package/README.md

@@ -10,6 +10,21 @@ 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.20: distinguish owned wrapper and target startup
+
+Add bounded, read-only process-name/state/wait hints for the exact owned
+wrapper PID. At most seven one-second queries run during preparation and stop
+at admission, failure, cancellation or exit. Fixed categories exclude raw names,
+paths, process IDs, arguments and environment. Cancellation hard-stops only its
+owned query. Local logging receives a deep diagnostic copy so it cannot mutate
+the evidence later reported to Gateway.
+
+These are direct-child hints, not executable identity, native function or
+historical cause proof; forked descendants are not inspected. Preparation
+deadlines, authenticated MCP/tool gates and unlimited admitted employee work
+remain unchanged. Installation does not update the daemon or run Codex.
+See [owned launch observation](https://bitbucket.org/mtechbal/api-cloud-service-ai-gateway/src/development/docs/ai-ops-gateway/codex-owned-launch-observation.md).
+
 ## 0.1.19: bounded preparation phase timing
 
 Record fixed host milestones with monotonic elapsed milliseconds and remaining

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

@@ -1,7 +1,7 @@
 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 { processStartupObservations, freezeProcessLaunchObservation } from '../../process/node-process-group-host.js';
 import { executionError } from '../../safety/execution-failure.js';
 import { UNMANAGED_EXEC_MODE } from './unmanaged-scope.js';
 import { fingerprint as taskFingerprint } from '../../daemon/execution-coordinator.js';
@@ -70,9 +70,10 @@ 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 launchObservation = () => this.handle ? freezeProcessLaunchObservation(this.handle) : undefined;
         const timing = new PreparationClock();
         timing.mark('preparation_start');
-        const interrupt = (code) => { timing.mark('preparation_failed'); interruption ??= executionError(fail(), stage, code, mcpDetail(), observations(), timing.snapshot()); };
+        const interrupt = (code) => { timing.mark('preparation_failed'); interruption ??= executionError(fail(), stage, code, mcpDetail(), observations(), timing.snapshot(), launchObservation()); };
         // 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.
@@ -174,7 +175,7 @@ export class CodexExecLaunchHost {
                     requireExecHandshake(observed, h, this.plan);
                     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 });
+                    this.receiptValue = Object.freeze({ preparation_timing: timing.snapshot(), ...(launchObservation() ? { launch_process: launchObservation() } : {}), 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');
@@ -204,14 +205,14 @@ export class CodexExecLaunchHost {
                 requireExecHandshake(handshake, h, this.plan);
                 assertPreparationBudget();
                 timing.mark('preparation_authorized');
-                this.receiptValue = Object.freeze({ ...receipt, preparation_timing: timing.snapshot() });
+                this.receiptValue = Object.freeze({ ...receipt, preparation_timing: timing.snapshot(), ...(launchObservation() ? { launch_process: launchObservation() } : {}) });
                 return h;
             })();
             return await Promise.race([preparation, stopped]);
         }
         catch (error) {
             timing.mark('preparation_failed');
-            const safe = executionError(interruption ?? error, stage, 'CODEX_EXEC_PREFLIGHT_REJECTED', mcpDetail(), observations(), timing.snapshot());
+            const safe = executionError(interruption ?? error, stage, 'CODEX_EXEC_PREFLIGHT_REJECTED', mcpDetail(), observations(), timing.snapshot(), launchObservation());
             await this.cancel().catch(() => { });
             throw safe;
         }

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

@@ -256,7 +256,7 @@ export class ExecutionCoordinator {
             failureDiagnostic = diagnostic;
             // Log before reporting so an unavailable Gateway does not erase the cause.
             try {
-                this.deps.reportExecutionFailure?.({ ...diagnostic });
+                this.deps.reportExecutionFailure?.(structuredClone(diagnostic));
             }
             catch { /* logging must not change terminal reconciliation */ }
             terminal = { eventType: "failed", summary: "daemon execution or event reporting failed", payload: { execution_failure: { ...diagnostic } } };

package/dist/src/process/node-process-group-host.js

@@ -1,4 +1,8 @@
+import path from 'node:path';
+import { OwnedLaunchObserver } from './owned-launch-observer.js';
 const startup = new WeakMap();
+const launchObservers = new WeakMap();
+export function freezeProcessLaunchObservation(handle) { return launchObservers.get(handle)?.freeze(); }
 /** Fixed lifecycle/text observations from this owned host only. Never raw stderr or authority. */
 export function processStartupObservations(handle) { return [...(startup.get(handle) ?? [])]; }
 import { spawn } from "node:child_process";
@@ -9,7 +13,22 @@ export class NodeProcessGroupHost {
             throw new Error("Codex process isolation requires macOS");
         const child = spawn(command, args, { ...options, shell: false, detached: true, stdio: ["pipe", "pipe", "pipe"] });
         const observations = new Set(['host_observer_v2']);
-        child.once('spawn', () => observations.add('host_process_spawned'));
+        let launch;
+        child.once('spawn', () => {
+            observations.add('host_process_spawned');
+            if (command === '/usr/bin/sandbox-exec' && args[0] === '-p' && path.isAbsolute(args[2] ?? '')) {
+                try {
+                    launch = new OwnedLaunchObserver({ pid: child.pid, parentPid: process.pid, wrapperName: path.basename(command), targetName: path.basename(args[2]), alive: () => owned && child.exitCode === null && child.signalCode === null, onSample: sample => {
+                            observations.add(sample.status === 'observed' ? sample.image === 'wrapper_name_match' ? 'host_os_wrapper_name_seen' : sample.image === 'target_name_match' ? 'host_os_target_name_seen' : 'host_os_other_name_seen' : 'host_os_query_unavailable');
+                        } });
+                    launchObservers.set(handle, launch);
+                    launch.start();
+                }
+                catch {
+                    observations.add('host_os_query_unavailable');
+                }
+            }
+        });
         child.stdin.once('finish', () => observations.add('host_stdin_finished'));
         let failure;
         let owned = true;
@@ -27,6 +46,7 @@ export class NodeProcessGroupHost {
                 callback(code, signal);
         };
         const kill = (signal = "SIGKILL") => {
+            launch?.stop();
             if (!owned || !child.pid)
                 return;
             try {

package/dist/src/process/owned-launch-observer.js

@@ -0,0 +1,132 @@
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { performance } from 'node:perf_hooks';
+const issued = new WeakMap();
+export function trustedLaunchObservation(token) {
+    const value = token && typeof token === 'object' ? issued.get(token) : undefined;
+    return value ? structuredClone(value) : undefined;
+}
+/** Only one exact, directly-owned PID. No argv/environment/descendant scan,
+ * stack attachment, credentials, network, or privileged query. */
+async function queryOwnedPid(pid, signal) {
+    return new Promise(resolve => {
+        let output = '', settled = false;
+        let timer;
+        let onAbort;
+        const finish = (value) => { if (settled)
+            return; settled = true; if (timer)
+            clearTimeout(timer); if (onAbort)
+            signal.removeEventListener('abort', onAbort); resolve(value); };
+        try {
+            const child = spawn('/bin/ps', ['-p', String(pid), '-o', 'pid=,ppid=,stat=,wchan=,comm='], { shell: false, env: { PATH: '/usr/bin:/bin', LANG: 'C', LC_ALL: 'C' }, stdio: ['ignore', 'pipe', 'ignore'] });
+            child.stdout.on('data', (chunk) => { if (settled)
+                return; if (Buffer.byteLength(output) + chunk.length > 8192) {
+                finish({ status: 'output_invalid' });
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch { /* owned query already gone */ }
+                return;
+            } output += chunk.toString('utf8'); });
+            child.on('error', () => finish({ status: 'query_failed' }));
+            child.once('close', code => finish(code === 0 ? { status: 'ok', output } : { status: 'query_failed' }));
+            onAbort = () => { if (settled)
+                return; try {
+                child.kill('SIGKILL');
+            }
+            catch { /* owned query already gone */ } finish({ status: 'query_failed' }); };
+            signal.addEventListener('abort', onAbort, { once: true });
+            if (signal.aborted) {
+                onAbort();
+                return;
+            }
+            timer = setTimeout(() => { finish({ status: 'query_timeout' }); try {
+                child.kill('SIGKILL');
+            }
+            catch { /* owned query already gone */ } }, 1000);
+            timer.unref();
+        }
+        catch {
+            finish({ status: 'query_failed' });
+        }
+    });
+}
+/** Names/wait symbols are observational hints, never executable identity or a
+ * native function attestation. Arbitrary process strings never leave this file. */
+export class OwnedLaunchObserver {
+    input;
+    origin = performance.now();
+    active = false;
+    used = false;
+    pending = false;
+    discarded = false;
+    abort = new AbortController();
+    timer;
+    values = [];
+    frozen;
+    constructor(input) {
+        this.input = input;
+        if (!Number.isSafeInteger(input.pid) || input.pid < 1 || !Number.isSafeInteger(input.parentPid) || input.parentPid < 1)
+            throw Error('OWNED_LAUNCH_OBSERVER_REJECTED');
+    }
+    start() { if (this.used || this.frozen)
+        return; this.used = true; this.active = true; void this.sample(0); }
+    async sample(index) {
+        if (!this.active || !this.input.alive())
+            return;
+        this.pending = true;
+        let result;
+        try {
+            result = await (this.input.query ?? queryOwnedPid)(this.input.pid, this.abort.signal);
+        }
+        catch {
+            result = { status: 'query_failed' };
+        }
+        this.pending = false;
+        if (!this.active || !this.input.alive())
+            return;
+        const previous = this.values.at(-1)?.elapsed_ms ?? 0, value = performance.now() - this.origin;
+        const elapsed_ms = Math.max(previous, Number.isFinite(value) ? Math.min(2147483647, Math.max(0, Math.floor(value))) : previous);
+        const sample = { elapsed_ms, status: result.status === 'ok' ? 'output_invalid' : result.status };
+        if (result.status === 'ok' && typeof result.output === 'string' && result.output.length <= 8192) {
+            const line = result.output.trim();
+            const match = /^(\d+)\s+(\d+)\s+(\S+)\s+(\S+)\s+([^\r\n\0]+)$/.exec(line);
+            if (match) {
+                if (Number(match[1]) !== this.input.pid || Number(match[2]) !== this.input.parentPid)
+                    sample.status = 'owner_mismatch';
+                else {
+                    sample.status = 'observed';
+                    const name = path.basename(match[5].trim());
+                    sample.image = name === this.input.wrapperName ? 'wrapper_name_match' : name === this.input.targetName ? 'target_name_match' : 'other';
+                    const states = { R: 'running', S: 'sleeping', I: 'sleeping', U: 'uninterruptible', D: 'uninterruptible', T: 'stopped', Z: 'zombie' };
+                    sample.state = states[match[3][0]] ?? 'other';
+                    const wait = match[4].toLowerCase();
+                    sample.wait = ['-', '0', '0x0', '??'].includes(wait) ? 'not_reported' : /^(?:__)?psynch(?:_|$)/.test(wait) ? 'psynch' : /^mach_msg(?:_|$)/.test(wait) ? 'mach_message' : /^kevent/.test(wait) ? 'kevent' : /^(?:pipe_?read|piperd)$/.test(wait) ? 'pipe_read' : /^(?:wait4|wait)$/.test(wait) ? 'child_wait' : 'other';
+                }
+            }
+        }
+        this.values.push(sample);
+        try {
+            this.input.onSample?.(structuredClone(sample));
+        }
+        catch { /* telemetry cannot alter execution */ }
+        const schedule = [0, 100, 500, 1500, 5000, 15000, 25000];
+        const next = schedule[index + 1];
+        if (next !== undefined && this.active) {
+            this.timer = setTimeout(() => { void this.sample(index + 1); }, Math.max(0, next - (performance.now() - this.origin)));
+            this.timer.unref();
+        }
+    }
+    stop() { this.used = true; if (!this.active)
+        return; this.active = false; this.discarded ||= this.pending; if (this.timer)
+        clearTimeout(this.timer); this.abort.abort(); }
+    freeze() {
+        if (!this.frozen) {
+            this.stop();
+            this.frozen = { version: 'owned-launch-process-v1', collector: 'owned_pid_ps', samples: structuredClone(this.values), pending_query_discarded: this.discarded };
+        }
+        const token = structuredClone(this.frozen);
+        issued.set(token, structuredClone(this.frozen));
+        return token;
+    }
+}

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

@@ -1,7 +1,9 @@
+import { trustedLaunchObservation } from '../process/owned-launch-observer.js';
 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([
+    'host_os_wrapper_name_seen', 'host_os_target_name_seen', 'host_os_other_name_seen', 'host_os_query_unavailable',
     'host_observer_v2', 'host_process_spawned', 'host_process_spawn_failed', 'host_process_exited',
     'host_stdin_write_requested', 'host_stdin_end_requested', 'host_stdin_finished', 'host_stdin_failed',
     'host_stdout_data', 'host_stdout_line', 'host_stdout_ended', 'host_stderr_data', 'host_stderr_ended',
@@ -36,7 +38,7 @@ export function executionFailure(error, stage, fallback = 'EXECUTION_FAILED') {
     }
     return { stage, code: fallback };
 }
-export function executionError(error, stage, fallback, detail, observations, preparationTiming) {
+export function executionError(error, stage, fallback, detail, observations, preparationTiming, launchObservation) {
     const diagnostic = executionFailure(error, stage, fallback);
     // Only trusted callers supply this fixed vocabulary. Serialized provider
     // errors, messages and stderr never become diagnostic authority.
@@ -52,6 +54,11 @@ export function executionError(error, stage, fallback, detail, observations, pre
         if (timing)
             diagnostic.preparation_timing = timing;
     }
+    if (!diagnostic.launch_process) {
+        const observed = trustedLaunchObservation(launchObservation);
+        if (observed)
+            diagnostic.launch_process = observed;
+    }
     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.19",
+  "version": "0.1.20",
   "private": false,
   "license": "UNLICENSED",
   "bin": {