@aiwg/cli 2026.10.3 → 2026.10.4

package/tools/ralph-external/lib/launcher-recovery-evidence.mjs

@@ -0,0 +1,55 @@
+import { runRecoveryProbe } from './recovery-probe.mjs';
+
+/** Recovery evidence observed outside worker output by the launch owner. */
+const observations = new WeakMap();
+const failureHints = new WeakMap();
+
+export function recordLauncherRecoveryHint(result, reasonCode) {
+  failureHints.set(result, reasonCode);
+}
+const HOST_ERRORS = new Set(['ENOMEM', 'ENOSPC', 'EAGAIN', 'EMFILE', 'ENFILE']);
+const HOST_RESULTS = new Set(['oom-kill', 'resources']);
+
+export function launcherRecoveryEvidence(result) {
+  return observations.get(result) ?? null;
+}
+
+/**
+ * A failed task's transcript cannot attest an upstream outage. Independently
+ * check only an endpoint already authorized by installation qualification.
+ * HEAD sends no task, credentials or response body and never follows redirects.
+ * Only upstream failure hints warrant this check; hints never attest an outage.
+ * beforeRequest checks the remaining task deadline; onDispatch charges allowance.
+ */
+export async function observeLauncherRecoveryOutcome({ invocation, result, installation, breaker,
+  failureHint = '', beforeRequest, onDispatch, fetchImpl = globalThis.fetch, wallNowMs = Date.now, timeoutMs = 10_000 } = {}) {
+  if (!result || result.attemptOutcome !== 'failed' || result.cancelled) return;
+  const backend = invocation?.selected?.inferenceProvider;
+  if (HOST_ERRORS.has(result.errorCode) || HOST_RESULTS.has(result.nativeResult)) {
+    const corroboratedBackends = breaker?.observeHostFailure({ invocationId: result.invocationId,
+      inferenceProvider: backend, reasonCode: 'RESOURCE' }) ?? [];
+    if (corroboratedBackends.length >= 2) observations.set(result, {
+      reasonCode: 'RESOURCE', evidenceSource: 'launcher', hostId: 'local', corroboratedBackends,
+    });
+    return;
+  }
+  if (!['RATE_LIMIT', 'NETWORK'].includes(failureHints.get(result) ?? result.health?.reasonCode)
+    && !/\b429\b|rate.limit|quota.exceeded|\b(?:ECONNRESET|ENOTFOUND|ETIMEDOUT|EAI_AGAIN|50[234])\b/i.test(String(failureHint).slice(0, 8192))) return;
+  const endpoint = installation?.endpoints?.[0];
+  if (typeof endpoint !== 'string' || typeof beforeRequest !== 'function' || typeof fetchImpl !== 'function') return;
+  const remaining = () => typeof timeoutMs === 'function' ? timeoutMs() : timeoutMs;
+  if (!Number.isFinite(remaining()) || remaining() <= 0) return;
+  try {
+    if (!await beforeRequest()) return;
+    const requestTimeoutMs = remaining();
+    if (!Number.isFinite(requestTimeoutMs) || requestTimeoutMs <= 0) return;
+    const observed = await runRecoveryProbe({ driver: { qualification: { installation } }, invocation: invocation ?? { transport: 'shell' },
+      timeoutMs: Math.min(10_000, requestTimeoutMs), maxOutputBytes: 65_536, onDispatch, fetchImpl, wallNowMs });
+    if (observed.reason === 'probe-rate-limited') {
+      observations.set(result, { reasonCode: 'RATE_LIMIT', evidenceSource: 'launcher',
+        retryAfterSeconds: observed.retryAfterSeconds });
+    } else if (observed.status >= 500 && observed.status <= 599) {
+      observations.set(result, { reasonCode: 'NETWORK', evidenceSource: 'launcher' });
+    }
+  } catch { /* A failed diagnostic is not evidence of a provider-wide outage. */ }
+}

package/tools/ralph-external/lib/omp-adapter.mjs

@@ -134,7 +134,7 @@ export class OmpAdapter extends ProviderAdapter {
     if (event.type === 'rpc_frame_error' || event.type === 'error') return { kind: 'error', reasonCode: 'provider-failed' };
     return null;
   }
-  async getVersion() { const result = spawnSync(this.getBinary(), ['--version'], { encoding: 'utf8', timeout: 5000, maxBuffer: 65536 }); return result.status === 0 ? result.stdout.trim() : null; }
+  async getVersion() { const result = spawnSync(this.getBinary(), ['--version'], { encoding: 'utf8', timeout: 5000, maxBuffer: 65536, killSignal: 'SIGKILL' }); return result.status === 0 ? result.stdout.trim() : null; }
   async isAvailable() { return Boolean(await this.getVersion()); }
   getName() { return 'omp'; }
   getBinary() { return process.env.AIWG_OMP_BIN || 'omp'; }

package/tools/ralph-external/lib/pi-adapter.mjs

@@ -1,5 +1,4 @@
 /** Pi Coding Agent adapter for headless External Ralph sessions. */
-import { spawnSync } from 'child_process';
 import { homedir } from 'os';
 import { join } from 'path';
 import { ProviderAdapter, registerProvider } from './provider-adapter.mjs';
@@ -113,9 +112,6 @@ export class PiAdapter extends ProviderAdapter {
       rpcAbort: false };
   }
   async isAvailable() {
-    const node = spawnSync(process.execPath, ['-p', 'process.versions.node'], { encoding: 'utf8', timeout: 5000 });
-    const [major, minor] = String(node.stdout).trim().split('.').map(Number);
-    if (node.status !== 0 || major < 22 || (major === 22 && minor < 19)) return false;
     if (!await super.isAvailable()) return false;
     return isSupportedPiVersion(await this.getVersion());
   }

package/tools/ralph-external/lib/provider-adapter.mjs

@@ -448,18 +448,76 @@ export class ProviderAdapter {
     return this.parseWorkerOutput(output, options);
   }
 
+  /**
+   * #2915 (evidence contract): the attempt-terminal sibling of
+   * `parseWorkerFinal`/`parseWorkerOutput` below. Shares the exact same
+   * strict decoding AND the exact same per-CLI extraction every subclass's
+   * own `parseWorkerFinal` override performs — the only difference is the
+   * terminal assertion: `assertWorkerAttemptTerminal` requires the
+   * launcher/adapter-owned `attemptOutcome` (never confirmed descendant
+   * termination) instead of `assertWorkerTerminal`'s
+   * `termination: 'confirmed'`. This lets a degraded-isolation shell
+   * attempt or an MCP response — neither of which can ever produce a
+   * confirmed descendant-stop — still validate a genuinely successful
+   * attempt's final claims (session-launcher.mjs `captureOneWorker`). It
+   * never manufactures confirmed termination: the caller's own
+   * `termination`/`descendants` fields are untouched.
+   *
+   * Fixed once here, for every adapter, with NO per-adapter edit required
+   * (2915 follow-up: the previous version called `parseWorkerOutput`
+   * directly, skipping every subclass's own extraction override entirely).
+   * The trick is calling `this.parseWorkerFinal` — polymorphic dispatch
+   * picks up the ACTUAL (possibly overridden) method — with
+   * `assertTerminal` folded into `options`. Every subclass override in this
+   * directory follows the same shape: extract a CLI-specific final, then
+   * `return super.parseWorkerFinal(extracted, { ...options, format: '...' })`
+   * — the `...options` spread carries `assertTerminal` straight through to
+   * the base `parseWorkerOutput` below, so the base class never needs
+   * subclass-specific knowledge of each extraction. An adapter whose
+   * override always throws regardless of input (Warp, Copilot:
+   * `supportsAttemptVerification() === false`) throws here too, by the same
+   * unconditional path — exactly the intended "never verifiable" behavior
+   * for those two; `admitDirectWorker` treats such a CLI as `not-gated`
+   * (recovery never consulted) rather than permanently blocking it.
+   */
+  parseWorkerAttemptFinal(output, options = {}) {
+    return this.parseWorkerAttemptOutput(output, options);
+  }
+
+  async parseWorkerAttemptOutput(output, options = {}) {
+    const { assertWorkerAttemptTerminal } = await importImpl(import.meta.url, 'mission-protocol/index.js');
+    return this.parseWorkerFinal(output, { ...options, assertTerminal: assertWorkerAttemptTerminal });
+  }
+
+  /**
+   * Capability signal (#2915 follow-up), default `true`: can this adapter's
+   * `parseWorkerFinal`/`parseWorkerAttemptFinal` ever validate a genuine
+   * final for ANY input, given a real completed attempt? Override `false`
+   * only for an adapter whose `parseWorkerFinal` always throws regardless
+   * of input (no observed output envelope exists to extract from yet —
+   * Warp, Copilot). `admitDirectWorker` uses this to treat such a CLI as
+   * never eligible for recovery-breaker gating, rather than admitting a
+   * canary that can structurally never report success.
+   */
+  supportsAttemptVerification() { return true; }
+
   /** Strict group-mode path, shared by CLI and MCP. Never falls back to regex.
    * Drivers normalize qualified vendor event framing to result/message/terminal
    * JSONL, or supply one claims JSON document. Observation comes from the trusted
    * process/request owner, not from the final. This returns claims, not acceptance.
    * Called directly or through the `parseWorkerFinal()` alias; never through
    * `parseOutput()`, which keeps its own synchronous, non-group contract.
+   * `options.assertTerminal`, when supplied (by `parseWorkerAttemptOutput`
+   * above), replaces the default `assertWorkerTerminal` confirmed-termination
+   * gate with the attempt-terminal one — every other step of decoding is
+   * identical and unmodified.
    */
   async parseWorkerOutput(output, options = {}) {
     const {
       WORKER_MAX_JSON_BYTES, WORKER_MAX_NESTING_DEPTH, WorkerContractError,
       decodeWorkerProducedPayload, assertWorkerTerminal,
     } = await importImpl(import.meta.url, 'mission-protocol/index.js');
+    const assertTerminal = options.assertTerminal ?? assertWorkerTerminal;
     const fail = message => { throw new WorkerContractError('OG_CONTRACT_INVALID', message); };
     const format = options.format ?? 'jsonl';
     const streamLimit = 10 * 1024 * 1024;
@@ -561,7 +619,7 @@ export class ProviderAdapter {
     boundedJson(final, WORKER_MAX_JSON_BYTES);
     const claims = decodeWorkerProducedPayload('workerClaims', 'worker', final);
     if (options.observation?.transport !== (format === 'mcp' ? 'mcp' : 'shell')) fail('Worker transport observation mismatch.');
-    assertWorkerTerminal(options.observation);
+    assertTerminal(options.observation);
     return claims;
   }
 

package/tools/ralph-external/lib/recovery-probe.mjs

@@ -0,0 +1,72 @@
+/** A recovery probe is a conductor-owned request, never an uncontained worker. */
+export async function runRecoveryProbe({ driver, invocation, timeoutMs = 10_000, maxOutputBytes = 65_536,
+  onDispatch, fetchImpl = globalThis.fetch, wallNowMs = Date.now }) {
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 10_000
+    || !Number.isSafeInteger(maxOutputBytes) || maxOutputBytes < 1 || maxOutputBytes > 65_536) {
+    throw new RangeError('Recovery probe exceeds the 10s/64KiB bounds');
+  }
+  const failed = (reason, extra = {}) => ({ success: false, relevant: false, termination: 'confirmed', reason, ...extra });
+  // These endpoints already passed the installation authority's allowlist and
+  // are bound into its qualification digest. Never derive a URL from worker
+  // output, task argv, a prompt, or ambient provider configuration.
+  const endpoint = driver?.qualification?.installation?.endpoints?.[0];
+  if (!['shell', 'mcp'].includes(invocation?.transport) || typeof endpoint !== 'string' || typeof fetchImpl !== 'function') {
+    return failed('probe-profile-unavailable', { operatorIntervention: true });
+  }
+  let url;
+  try { url = new URL(endpoint); } catch { return failed('probe-endpoint-unavailable', { operatorIntervention: true }); }
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.hash) {
+    return failed('probe-endpoint-unavailable', { operatorIntervention: true });
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), Math.max(1, Math.floor(timeoutMs)));
+  let aborted;
+  const timeout = new Promise((_, reject) => {
+    aborted = () => reject(new Error('probe-timeout'));
+    controller.signal.addEventListener('abort', aborted, { once: true });
+  });
+  // The rejection can precede a slow allowance debit; attach a handler now
+  // while still awaiting that debit's definitive outcome before returning.
+  timeout.catch(() => {});
+  try {
+    await onDispatch?.();
+    if (controller.signal.aborted) return failed('probe-timeout');
+    try {
+      // HEAD has no task, credentials, inference body or worker filesystem.
+      // A successful endpoint check permits only one subsequent task canary.
+      const response = await Promise.race([fetchImpl(endpoint, { method: 'HEAD', redirect: 'error', signal: controller.signal }), timeout]);
+      let headerBytes = 16 + Buffer.byteLength(response.statusText ?? '');
+      for (const [name, value] of response.headers) headerBytes += Buffer.byteLength(name) + Buffer.byteLength(value) + 4;
+      try {
+        if (headerBytes > maxOutputBytes) return failed('probe-output-limit');
+        if (response.body) return failed('probe-body-unexpected');
+        const success = response.status >= 200 && response.status <= 299;
+        if (success) return { success: true, relevant: true, termination: 'confirmed', reason: 'probe-succeeded' };
+        if (response.status === 429) {
+          const after = response.headers.get('retry-after');
+          const seconds = after != null && /^\d+(?:\.\d+)?$/.test(after.trim()) ? Number(after) : null;
+          const date = seconds === null && after ? Date.parse(after) : NaN;
+          const reset = response.headers.get('x-ratelimit-reset');
+          const resetEpoch = reset != null && /^\d+(?:\.\d+)?$/.test(reset.trim()) ? Number(reset) * 1000 : NaN;
+          const resetDelay = response.headers.get('ratelimit-reset');
+          const delays = [seconds, Number.isFinite(date) ? (date - wallNowMs()) / 1000 : null,
+            Number.isFinite(resetEpoch) ? (resetEpoch - wallNowMs()) / 1000 : null,
+            resetDelay != null && /^\d+(?:\.\d+)?$/.test(resetDelay.trim()) ? Number(resetDelay) : null]
+            .filter(value => Number.isFinite(value) && value >= 0);
+          return failed('probe-rate-limited', { retryAfterSeconds: delays.length ? Math.max(...delays) : null });
+        }
+        return failed('probe-failed', { status: response.status });
+      } finally {
+        // HEAD exposes no response body on the native transport. Cancel an
+        // unexpected body without reading it, under the same absolute bound.
+        if (response.body) await Promise.race([response.body.cancel(), timeout]);
+      }
+    } catch {
+      return failed(controller.signal.aborted ? 'probe-timeout' : 'probe-unavailable');
+    }
+  } finally {
+    clearTimeout(timer);
+    controller.signal.removeEventListener('abort', aborted);
+    controller.abort();
+  }
+}

package/tools/ralph-external/lib/session-environment.mjs

@@ -0,0 +1,28 @@
+import { readFileSync } from 'node:fs';
+
+// Provider-owned session policy; single-shot worker allowlists stay independent.
+const { providers } = JSON.parse(readFileSync(
+  new URL('../../../agentic/code/providers/model-capabilities.v1.json', import.meta.url), 'utf8'));
+
+const baseNames = new Set([
+  'PATH', 'HOME', 'USER', 'LOGNAME', 'SHELL', 'LANG', 'LANGUAGE',
+  'TERM', 'COLORTERM', 'TERM_PROGRAM', 'TMPDIR', 'TMP', 'TEMP',
+  'SSH_AUTH_SOCK', 'SSH_AGENT_PID', 'CI', 'NO_COLOR', 'FORCE_COLOR',
+  'NODE_OPTIONS', 'NODE_EXTRA_CA_CERTS', 'SSL_CERT_FILE', 'SSL_CERT_DIR',
+  'HTTP_PROXY', 'HTTPS_PROXY', 'ALL_PROXY', 'NO_PROXY', 'FTP_PROXY',
+  'SYSTEMROOT', 'WINDIR', 'COMSPEC', 'PATHEXT', 'USERPROFILE',
+  'HOMEDRIVE', 'HOMEPATH', 'APPDATA', 'LOCALAPPDATA', 'PROGRAMDATA',
+]);
+
+/** Build the legacy full-session environment. Explicit adapter overrides win. */
+export function buildSessionEnvironment(provider = 'claude', envOverrides = {}, env = process.env) {
+  const providerNames = new Set(providers[provider]?.sessionEnvAllowlist ?? []);
+  const inherited = Object.fromEntries(Object.entries(env).filter(([name, value]) => {
+    if (value === undefined) return false;
+    // Windows names are case insensitive; proxy tools also use lowercase names.
+    const baseName = name.toUpperCase();
+    return baseNames.has(baseName) || /^(LC_|XDG_|GIT_)/.test(baseName)
+      || providerNames.has(name);
+  }));
+  return { ...inherited, ...envOverrides };
+}

package/tools/ralph-external/lib/systemd-client.mjs

@@ -0,0 +1,49 @@
+import { accessSync, constants, realpathSync, statSync } from 'node:fs';
+import path from 'node:path';
+
+export const CONNECTION_NAMES = ['XDG_RUNTIME_DIR', 'DBUS_SESSION_BUS_ADDRESS', 'SYSTEMD_BUS_ADDRESS'];
+
+export function isClientControlVariable(name) {
+  return /^(LD_|DYLD_|GLIBC_)/.test(name) || ['NODE_OPTIONS', 'NODE_PATH'].includes(name);
+}
+
+/** Conductor PATH directories and symlink targets must be protected from
+ * untrusted writers; canonicalization does not check ownership or prevent races. */
+export function resolveSystemdClient(name) {
+  if (!['systemd-run', 'systemctl'].includes(name)) throw new Error('Invalid systemd client');
+  for (const directory of (process.env.PATH ?? '/usr/bin:/bin').split(path.delimiter)) {
+    // Relative/empty entries would let the working directory select the client.
+    if (!path.isAbsolute(directory)) continue;
+    const candidate = path.join(directory, name);
+    try {
+      const canonical = realpathSync(candidate);
+      accessSync(canonical, constants.X_OK);
+      if (statSync(canonical).isFile()) return canonical;
+    } catch { /* try the next conductor PATH entry */ }
+  }
+  throw new Error(`${name} is unavailable on the conductor's absolute PATH`);
+}
+
+export function resolveSystemdRun() { return resolveSystemdClient('systemd-run'); }
+
+/** Reject bootstrap controls before the client loader can act on them. */
+export function unitEnvironmentNames(envNames) {
+  for (const name of envNames) {
+    if (isClientControlVariable(name)) throw new Error('Worker environment cannot alter trusted transport bootstrap');
+  }
+  return envNames.filter(name => !CONNECTION_NAMES.includes(name));
+}
+
+/** Import caller values for bare --setenv; connections belong only to the conductor. */
+export function buildSystemdClientEnv({ env = process.env, envNames = ['PATH', 'HOME'] } = {}) {
+  const clientEnv = {};
+  for (const name of ['PATH', 'HOME', ...CONNECTION_NAMES]) {
+    if (process.env[name] !== undefined) clientEnv[name] = process.env[name];
+  }
+  for (const name of envNames) {
+    if (CONNECTION_NAMES.includes(name) || isClientControlVariable(name)) continue;
+    if (env?.[name] === undefined) delete clientEnv[name];
+    else clientEnv[name] = env[name];
+  }
+  return clientEnv;
+}

package/tools/ralph-external/lib/worker-health.mjs

@@ -387,7 +387,7 @@ export async function sampleOwnedWorktreeContent(root, { files, maxFiles = 128,
     if (!candidates) {
       const status = execFileSync('git', ['--no-optional-locks', '-c', 'core.fsmonitor=false', '-c', 'core.untrackedCache=false',
         '-C', root, 'status', '--porcelain=v1', '-z', '--untracked-files=all'],
-        { timeout: 1000, maxBuffer: 65536, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], env: { ...process.env, GIT_OPTIONAL_LOCKS: '0', GIT_CONFIG_COUNT: '0' } });
+        { timeout: 1000, maxBuffer: 65536, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], env: { ...process.env, GIT_OPTIONAL_LOCKS: '0', GIT_CONFIG_COUNT: '0' }, killSignal: 'SIGKILL' });
       candidates = [];
       const records = status.split('\0');
       for (let i = 0; i < records.length; i++) {