@aiwg/cli 2026.10.1 → 2026.10.4

package/tools/providers/deepseek-harness-transport.mjs

@@ -0,0 +1,360 @@
+import { importImpl } from '../_resolve-impl.mjs';
+import { createHash } from 'node:crypto';
+import { mkdtemp, readFile, rm, writeFile, chmod } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { spawn } from 'node:child_process';
+const { signalChild } = await importImpl(import.meta.url, 'process/signal-child.mjs');
+
+export const DSH_SUPPORTED_VERSIONS = Object.freeze(['0.1.1-rc.2', '0.1.2-rc.1', '0.1.3-alpha.1']);
+export const DSH_MAX_FRAME_BYTES = 1024 * 1024;
+export const DSH_MAX_OUTPUT_BYTES = 16 * 1024 * 1024;
+export const DSH_UPSTREAM_SOURCE = 'https://github.com/deepseek-ai/deepseek-harness';
+export const DSH_UPSTREAM_REVISION = 'd347e703908d0406b7a7ef80e3a0e594d86b2215';
+
+const SAFE_ID = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const SAFE_MODEL = /^[A-Za-z0-9][A-Za-z0-9._:/+-]{0,191}$/;
+const SAFE_ENV = /^[A-Z][A-Z0-9_]{0,127}$/;
+const BASE_ENV = ['PATH', 'HOME', 'USER', 'LOGNAME', 'LANG', 'LC_ALL', 'TMPDIR', 'TEMP', 'TMP', 'SystemRoot', 'ComSpec', 'PATHEXT'];
+const SDK_SERVER_NAME = 'deepseek-harness-sdk-runtime';
+const SDK_NOTIFICATION_METHODS = new Set(['session.event', 'session.status', 'subagent.started', 'subagent.finished']);
+
+export function assertSupportedDshVersion(version) {
+  const normalized = String(version).trim().replace(/^dsh\s+v?/, '').replace(/^v/, '');
+  if (!DSH_SUPPORTED_VERSIONS.includes(normalized)) {
+    throw new Error(`Unsupported DeepSeek Harness version ${normalized || '(empty)'}; supported: ${DSH_SUPPORTED_VERSIONS.join(', ')}`);
+  }
+  return normalized;
+}
+
+export function buildCredentialEnvironment({ credentialEnv, credentialValue, dshHome, env = process.env }) {
+  if (credentialEnv !== undefined && !SAFE_ENV.test(credentialEnv)) throw new Error('credentialEnv must be an uppercase environment-variable name');
+  if ((credentialEnv === undefined) !== (credentialValue === undefined)) throw new Error('credentialEnv and credentialValue must be supplied together');
+  if (credentialEnv !== undefined && (typeof credentialValue !== 'string' || credentialValue.length === 0)) throw new Error(`Missing credential value for ${credentialEnv}`);
+  if (typeof dshHome !== 'string' || !dshHome) throw new Error('dshHome is required');
+  const child = {};
+  for (const name of BASE_ENV) if (env[name]) child[name] = env[name];
+  if (credentialEnv !== undefined) child[credentialEnv] = credentialValue;
+  child.DSH_HOME = resolve(dshHome);
+  child.DSH_PERMISSION_MODE = 'workspace-write';
+  child.DSH_TELEMETRY_DISABLED = '1';
+  return child;
+}
+
+export async function inspectDshVersion({ binary = 'dsh', cwd = process.cwd(), dshHome, timeoutMs = 10_000 }) {
+  const env = buildCredentialEnvironment({ dshHome });
+  const result = await runBounded(binary, ['--version'], { cwd: resolve(cwd), env, timeoutMs });
+  if (result.code !== 0) throw new Error(`DeepSeek Harness version probe failed (${result.code ?? result.signal})`);
+  return assertSupportedDshVersion(result.stdout.trim());
+}
+
+export function buildRoutePatch({ route = 'openrouter', model, credentialEnv = 'OPENROUTER_API_KEY' }) {
+  if (!SAFE_ID.test(route)) throw new Error('route must be a lowercase hyphenated identifier');
+  if (!SAFE_MODEL.test(model)) throw new Error('model contains unsupported characters');
+  if (!SAFE_ENV.test(credentialEnv)) throw new Error('credentialEnv must be an uppercase environment-variable name');
+  return [
+    '- id: llm-pi-ai',
+    '  config:',
+    '    providers:',
+    `      ${route}:`,
+    `        apiKeyEnv: ${credentialEnv}`,
+    '- id: agent-default-model',
+    '  config:',
+    `    provider: ${route}`,
+    `    model: ${model}`,
+    '',
+  ].join('\n');
+}
+
+export async function createEphemeralRoutePatch(options) {
+  const directory = await mkdtemp(join(tmpdir(), 'aiwg-dsh-route-'));
+  const path = join(directory, 'route.cordis.patch.yml');
+  const content = buildRoutePatch(options);
+  await writeFile(path, content, { encoding: 'utf8', mode: 0o600 });
+  await chmod(path, 0o600);
+  return {
+    path,
+    hash: `sha256:${createHash('sha256').update(content).digest('hex')}`,
+    async cleanup() { await rm(directory, { recursive: true, force: true }); },
+  };
+}
+
+export async function runDshHeadless({ prompt, cwd, dshHome, projectPatch, routePatch, route, model, credentialEnv, credentialValue, binary = 'dsh', timeoutMs = 120_000, terminateGraceMs = 1_000, signal, version }) {
+  if (typeof prompt !== 'string' || !prompt.trim()) throw new Error('prompt is required');
+  const env = buildCredentialEnvironment({ credentialEnv, credentialValue, dshHome });
+  const runtimeVersion = version === undefined
+    ? await inspectDshVersion({ binary, cwd, dshHome, timeoutMs: Math.min(timeoutMs, 10_000) })
+    : assertSupportedDshVersion(version);
+  const args = ['--profile', 'headless', '--patch', resolve(projectPatch), '--patch', resolve(routePatch), prompt];
+  const result = await runBounded(binary, args, { cwd: resolve(cwd), env, timeoutMs, terminateGraceMs, signal });
+  return { ...result, provenance: await provenance({ binary, version: runtimeVersion, profile: 'headless', projectPatch, routePatch, route, model }) };
+}
+
+export class DshJsonRpcClient {
+  constructor({ cwd, dshHome, projectPatch, routePatch, credentialEnv, credentialValue, binary = 'dsh', timeoutMs = 120_000, version }) {
+    this.options = { cwd, dshHome, projectPatch, routePatch, credentialEnv, credentialValue, binary, timeoutMs, version };
+    this.nextId = 1;
+    this.pending = new Map();
+    this.notifications = [];
+    this.notificationWaiters = new Set();
+    this.buffer = '';
+    this.outputBytes = 0;
+  }
+
+  start() {
+    if (this.child) return;
+    const o = this.options;
+    const env = buildCredentialEnvironment(o);
+    const args = ['--profile', 'sdk', '--patch', resolve(o.projectPatch), '--patch', resolve(o.routePatch)];
+    this.child = spawn(o.binary, args, { cwd: resolve(o.cwd), env, stdio: ['pipe', 'pipe', 'pipe'] });
+    this.stderr = '';
+    this.child.stdout.on('data', chunk => this.onData(chunk));
+    this.child.stderr.on('data', chunk => {
+      try {
+        this.accountOutput(chunk);
+        this.stderr = appendBounded(this.stderr, chunk, DSH_MAX_OUTPUT_BYTES);
+      }
+      catch (error) { this.abort(error); }
+    });
+    this.child.once('error', error => this.rejectAll(error));
+    this.child.once('exit', (code, signal) => {
+      const suffix = this.buffer.length ? '; truncated JSON-RPC frame remained on stdout' : '';
+      this.rejectAll(new Error(`DeepSeek Harness JSON-RPC exited (${code ?? signal})${suffix}`));
+    });
+  }
+
+  accountOutput(chunk) {
+    this.outputBytes += chunk.length;
+    if (this.outputBytes > DSH_MAX_OUTPUT_BYTES) throw new Error('DeepSeek Harness JSON-RPC aggregate output limit exceeded');
+  }
+
+  onData(chunk) {
+    try { this.accountOutput(chunk); }
+    catch (error) { return this.abort(error); }
+    this.buffer += chunk.toString('utf8');
+    for (;;) {
+      const nl = this.buffer.indexOf('\n');
+      if (nl < 0) break;
+      const line = this.buffer.slice(0, nl).replace(/\r$/, '');
+      this.buffer = this.buffer.slice(nl + 1);
+      if (Buffer.byteLength(line) > DSH_MAX_FRAME_BYTES) return this.abort(new Error('DeepSeek Harness JSON-RPC frame limit exceeded'));
+      if (!line.trim()) continue;
+      let message;
+      try { message = JSON.parse(line); } catch { return this.abort(new Error('Malformed DeepSeek Harness JSON-RPC frame')); }
+      if (message.jsonrpc !== '2.0') return this.abort(new Error('Invalid DeepSeek Harness JSON-RPC version'));
+      if (message.id !== undefined) {
+        const pending = this.pending.get(message.id);
+        if (!pending) continue;
+        this.pending.delete(message.id);
+        clearTimeout(pending.timer);
+        if (message.error) pending.reject(new Error(`DeepSeek Harness JSON-RPC error ${message.error.code}: ${message.error.message}`));
+        else pending.resolve(message.result);
+      } else if (typeof message.method === 'string') {
+        if (!SDK_NOTIFICATION_METHODS.has(message.method)) return this.abort(new Error(`Unsupported DeepSeek Harness JSON-RPC notification: ${message.method}`));
+        this.notifications.push(message);
+        for (const waiter of [...this.notificationWaiters]) {
+          if (waiter.predicate(message)) {
+            this.notificationWaiters.delete(waiter);
+            clearTimeout(waiter.timer);
+            waiter.resolve(message);
+          }
+        }
+      } else return this.abort(new Error('Invalid DeepSeek Harness JSON-RPC message shape'));
+    }
+    if (Buffer.byteLength(this.buffer) > DSH_MAX_FRAME_BYTES) return this.abort(new Error('DeepSeek Harness JSON-RPC frame limit exceeded'));
+  }
+
+  request(method, params, { signal, timeoutMs = this.options.timeoutMs } = {}) {
+    this.start();
+    const id = this.nextId++;
+    const frame = JSON.stringify({ jsonrpc: '2.0', id, method, params });
+    if (Buffer.byteLength(frame) > DSH_MAX_FRAME_BYTES) return Promise.reject(new Error('DeepSeek Harness JSON-RPC request exceeds frame limit'));
+    return new Promise((resolvePromise, reject) => {
+      const fail = error => this.abort(error);
+      const cancel = () => fail(new Error(`DeepSeek Harness JSON-RPC ${method} cancelled`));
+      const timer = setTimeout(() => fail(new Error(`DeepSeek Harness JSON-RPC ${method} timed out`)), timeoutMs);
+      this.pending.set(id, {
+        resolve: value => { signal?.removeEventListener('abort', cancel); resolvePromise(value); },
+        reject: error => { signal?.removeEventListener('abort', cancel); reject(error); },
+        timer,
+      });
+      if (signal?.aborted) return cancel();
+      signal?.addEventListener('abort', cancel, { once: true });
+      this.child.stdin.write(`${frame}\n`, error => { if (error) fail(error); });
+    });
+  }
+
+  async initialize({ provider, model, reasoningEffort, maxTokens }) {
+    this.version = this.options.version === undefined
+      ? await inspectDshVersion({ binary: this.options.binary, cwd: this.options.cwd, dshHome: this.options.dshHome, timeoutMs: Math.min(this.options.timeoutMs, 10_000) })
+      : assertSupportedDshVersion(this.options.version);
+    const result = await this.request('initialize', { cwd: resolve(this.options.cwd), provider, model, ...(reasoningEffort ? { reasoningEffort } : {}), ...(maxTokens ? { maxTokens } : {}) });
+    if (!result || typeof result !== 'object' || result.serverInfo?.name !== SDK_SERVER_NAME || typeof result.serverInfo?.version !== 'string') throw new Error('DeepSeek Harness initialize returned an incompatible server identity');
+    this.route = provider;
+    this.model = model;
+    return result;
+  }
+  async prompt(sessionId, contentBlocks, options) {
+    const result = await this.request('session/prompt', { sessionId, contentBlocks }, options);
+    if (!result || typeof result !== 'object' || typeof result.messageId !== 'string') throw new Error('DeepSeek Harness session/prompt returned no message id');
+    return result;
+  }
+  waitForNotification(predicate, { from = 0, timeoutMs = this.options.timeoutMs } = {}) {
+    const existing = this.notifications.slice(from).find(predicate);
+    if (existing) return Promise.resolve(existing);
+    return new Promise((resolvePromise, reject) => {
+      const waiter = { predicate, resolve: resolvePromise, reject, timer: undefined };
+      waiter.timer = setTimeout(() => {
+        this.notificationWaiters.delete(waiter);
+        reject(new Error('DeepSeek Harness notification wait timed out'));
+      }, timeoutMs);
+      this.notificationWaiters.add(waiter);
+    });
+  }
+  async promptAndWait(sessionId, contentBlocks, { signal, onNotification, timeoutMs = this.options.timeoutMs } = {}) {
+    const from = this.notifications.length;
+    const result = await this.prompt(sessionId, contentBlocks, { signal, timeoutMs });
+    const deadline = Date.now() + timeoutMs;
+    let cursor = from;
+    let rootRan = false;
+    const active = new Set();
+    const events = [];
+    for (;;) {
+      if (signal?.aborted) this.abort(new Error('DeepSeek Harness prompt settlement cancelled'));
+      const notification = this.notifications[cursor] ?? await this.waitForNotification(() => true, {
+        from: cursor,
+        timeoutMs: Math.max(1, deadline - Date.now()),
+      });
+      cursor = this.notifications.indexOf(notification, cursor) + 1;
+      onNotification?.(notification);
+      events.push(summarizeNotification(notification));
+      const params = notification.params && typeof notification.params === 'object' ? notification.params : {};
+      if (notification.method === 'subagent.started' && params.parentSessionId === sessionId && typeof params.childSessionId === 'string') active.add(params.childSessionId);
+      if (notification.method === 'subagent.finished' && typeof params.childSessionId === 'string') active.delete(params.childSessionId);
+      if (notification.method === 'session.status' && params.sessionId === sessionId) {
+        if (params.status === 'running') rootRan = true;
+        if (params.status === 'idle' && rootRan && active.size === 0) {
+          return { messageId: result.messageId, events, provenance: { provider: 'deepseek-harness', version: this.version, profile: 'sdk', route: this.route, model: this.model } };
+        }
+      }
+    }
+  }
+  shutdown() { return this.request('shutdown', {}); }
+  abort(error = new Error('DeepSeek Harness JSON-RPC client closed')) {
+    if (this.child && !this.child.killed) {
+      signalChild(this.child, 'SIGTERM');
+      const child = this.child;
+      const escalation = setTimeout(() => { if (child.exitCode === null) signalChild(child, 'SIGKILL'); }, 1_000);
+      child.once('exit', () => clearTimeout(escalation));
+    }
+    this.rejectAll(error);
+  }
+  rejectAll(error) {
+    for (const pending of this.pending.values()) { clearTimeout(pending.timer); pending.reject(error); }
+    this.pending.clear();
+    for (const waiter of this.notificationWaiters) { clearTimeout(waiter.timer); waiter.reject(error); }
+    this.notificationWaiters.clear();
+  }
+}
+
+async function provenance({ binary, version, profile, projectPatch, routePatch, route, model }) {
+  const [project, routeBytes] = await Promise.all([readFile(projectPatch), readFile(routePatch)]);
+  const projectPatchHash = `sha256:${createHash('sha256').update(project).digest('hex')}`;
+  const routePatchHash = `sha256:${createHash('sha256').update(routeBytes).digest('hex')}`;
+  const profileHash = `sha256:${createHash('sha256').update(JSON.stringify({ profile, projectPatchHash, routePatchHash })).digest('hex')}`;
+  return {
+    provider: 'deepseek-harness', binary, version, profile, route, model,
+    upstreamSource: DSH_UPSTREAM_SOURCE,
+    upstreamRevision: DSH_UPSTREAM_REVISION,
+    profileHash,
+    projectPatchHash,
+    routePatchHash,
+  };
+}
+
+function summarizeNotification(message) {
+  const params = message.params && typeof message.params === 'object' ? message.params : {};
+  if (message.method !== 'session.event') return { method: message.method, ...copyScalars(params) };
+  const event = params.event && typeof params.event === 'object' ? params.event : {};
+  const data = event.data && typeof event.data === 'object' ? event.data : {};
+  const summary = { method: message.method, sessionId: params.sessionId, type: event.type, seq: event.seq, time: event.time };
+  if (event.type === 'assistant/message') {
+    const messageData = data.message && typeof data.message === 'object' ? data.message : {};
+    summary.text = textBlocks(messageData.content);
+  } else if (String(event.type).startsWith('tool/')) {
+    summary.toolName = typeof data.name === 'string' ? data.name : typeof data.toolName === 'string' ? data.toolName : undefined;
+    summary.toolCallId = typeof data.id === 'string' ? data.id : typeof data.toolCallId === 'string' ? data.toolCallId : undefined;
+    summary.redacted = true;
+  } else if (String(event.type).includes('question')) {
+    summary.question = typeof data.question === 'string' ? data.question : undefined;
+  }
+  return summary;
+}
+
+function copyScalars(value) {
+  return Object.fromEntries(Object.entries(value).filter(([, item]) => ['string', 'number', 'boolean'].includes(typeof item)));
+}
+
+function textBlocks(value) {
+  if (!Array.isArray(value)) return '';
+  return value.flatMap(item => item && typeof item === 'object' && item.type === 'text' && typeof item.text === 'string' ? [item.text] : []).join('\n');
+}
+
+function appendBounded(current, chunk, max) {
+  const next = current + chunk.toString('utf8');
+  if (Buffer.byteLength(next) > max) throw new Error('DeepSeek Harness output limit exceeded');
+  return next;
+}
+
+function runBounded(binary, args, { cwd, env, timeoutMs, terminateGraceMs = 1_000, signal }) {
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn(binary, args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = ''; let stderr = ''; let outputBytes = 0; let settled = false; let stopError; let escalation;
+    const finish = (error, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      clearTimeout(escalation);
+      signal?.removeEventListener('abort', cancel);
+      error ? reject(error) : resolvePromise(value);
+    };
+    const terminate = error => {
+      if (settled || stopError) return;
+      stopError = error;
+      // A descendant may retain pipes after the direct child exits. Keep the
+      // deadline bounded even when there is no live direct child to terminate.
+      if (child.exitCode !== null || child.signalCode !== null) {
+        child.stdout.destroy();
+        child.stderr.destroy();
+        finish(error);
+        return;
+      }
+      signalChild(child, 'SIGTERM');
+      if (settled) return;
+      escalation = setTimeout(() => {
+        if (child.exitCode === null && child.signalCode === null) signalChild(child, 'SIGKILL');
+      }, terminateGraceMs);
+    };
+    const cancel = () => terminate(new Error('DeepSeek Harness run cancelled'));
+    const timer = setTimeout(() => terminate(new Error('DeepSeek Harness run timed out')), timeoutMs);
+    signal?.addEventListener('abort', cancel, { once: true });
+    if (signal?.aborted) cancel();
+    child.once('error', error => finish(error));
+    const capture = (current, chunk) => {
+      outputBytes += chunk.length;
+      if (outputBytes > DSH_MAX_OUTPUT_BYTES) throw new Error('DeepSeek Harness aggregate output limit exceeded');
+      return appendBounded(current, chunk, DSH_MAX_OUTPUT_BYTES);
+    };
+    child.stdout.on('data', chunk => { try { stdout = capture(stdout, chunk); } catch (error) { terminate(error); } });
+    child.stderr.on('data', chunk => { try { stderr = capture(stderr, chunk); } catch (error) { terminate(error); } });
+    child.once('exit', () => {
+      if (stopError) {
+        child.stdout.destroy();
+        child.stderr.destroy();
+        finish(stopError);
+      }
+    });
+    // 'exit' can precede the final stdout/stderr data events.
+    child.once('close', (code, exitSignal) => finish(stopError, { code, signal: exitSignal, stdout, stderr }));
+  });
+}

package/tools/providers/omp-transport.mjs

@@ -0,0 +1,194 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { importImpl } from '../_resolve-impl.mjs';
+const { signalChild } = await importImpl(import.meta.url, 'process/signal-child.mjs');
+
+const { positiveTimeoutMs } = await importImpl(import.meta.url, 'process/bounded-child-process.mjs');
+
+/** Preserve process identity and state: zombies still fail the cleanup gate. */
+export async function inspectOmpProcess({ pid, startTime }) {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return { pid, present: false };
+  try {
+    const stat = await readFile(`/proc/${pid}/stat`, 'utf8');
+    const fields = stat.slice(stat.lastIndexOf(')') + 2).trim().split(/\s+/);
+    return { pid, state: fields[0], parentPid: Number(fields[1]), processGroup: Number(fields[2]), startTime: fields[19], present: !startTime || startTime === fields[19], identityChanged: Boolean(startTime && startTime !== fields[19]) };
+  } catch (error) {
+    if (process.platform === 'linux' && error.code === 'ENOENT') return { pid, present: false };
+    try { process.kill(pid, 0); return { pid, present: true, state: 'unknown' }; }
+    catch (probe) { return { pid, present: probe.code !== 'ESRCH', state: probe.code === 'ESRCH' ? undefined : 'unknown' }; }
+  }
+}
+
+export async function waitForOmpProcessCleanup(processes, { timeoutMs = 3000 } = {}) {
+  const started = Date.now();
+  const initial = await Promise.all(processes.map(inspectOmpProcess));
+  let final = initial;
+  while (final.some(item => item.present) && Date.now() - started < timeoutMs) {
+    await new Promise(resolve => setTimeout(resolve, Math.min(50, Math.max(1, timeoutMs - (Date.now() - started)))));
+    final = await Promise.all(processes.map(inspectOmpProcess));
+  }
+  return { initial, final, elapsedMs: Date.now() - started, complete: final.every(item => !item.present) };
+}
+
+
+export const MAX_FRAME = 1024 * 1024;
+export const MAX_MESSAGE = 64 * MAX_FRAME;
+function parseFrameJson(text) { try { return JSON.parse(text); } catch { throw new Error('Malformed OMP JSON frame'); } }
+/** Bounded physical JSONL frames and ordered OMP v2 chunk reassembly. */
+export class OmpFrameDecoder {
+  constructor({ frameLimit = MAX_FRAME, messageLimit = MAX_MESSAGE } = {}) {
+    this.frameLimit = frameLimit; this.messageLimit = messageLimit; this.buffer = Buffer.alloc(0); this.pending = null;
+  }
+  push(chunk) {
+    const frames = [];
+    // Split incoming data before buffering to keep individual frame allocations bounded.
+    for (const part of Buffer.from(chunk).toString('binary').split('\n').entries()) {
+      const [index, value] = part;
+      if (index) { if (this.buffer.length) { const frame = this.decode(parseFrameJson(new TextDecoder('utf-8', { fatal: true }).decode(this.buffer))); if (frame) frames.push(frame); } this.buffer = Buffer.alloc(0); }
+      const bytes = Buffer.from(value, 'binary');
+      if (this.buffer.length + bytes.length + 1 > this.frameLimit) throw new Error('OMP physical frame limit exceeded');
+      this.buffer = Buffer.concat([this.buffer, bytes]);
+    }
+    return frames;
+  }
+  decode(frame) {
+    if (!frame || typeof frame !== 'object' || Array.isArray(frame)) throw new Error('OMP frame must be an object');
+    if (frame.type !== 'rpc_chunk') { if (this.pending) throw new Error('OMP chunk sequence interrupted'); return frame; }
+    const { chunkId, count, index, byteLength, data } = frame;
+    if (typeof chunkId !== 'string' || !chunkId || chunkId.length > 128 || !Number.isSafeInteger(count) || count < 2 || count > 256 || !Number.isSafeInteger(index) || index < 0 || index >= count || !Number.isSafeInteger(byteLength) || byteLength < MAX_FRAME || byteLength > this.messageLimit || typeof data !== 'string' || !data || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(data)) throw new Error('Invalid OMP chunk metadata');
+    const bytes = Buffer.from(data, 'base64');
+    if (bytes.toString('base64') !== data || bytes.length > 256 * 1024) throw new Error('Invalid OMP chunk payload');
+    if (!this.pending) this.pending = { chunkId, count, byteLength, next: 0, size: 0, parts: [] };
+    const p = this.pending;
+    if (p.chunkId !== chunkId || p.count !== count || p.byteLength !== byteLength || p.next !== index) throw new Error('OMP chunk sequence mismatch');
+    p.size += bytes.length; p.next++; p.parts.push(bytes);
+    if (p.size > byteLength) throw new Error('OMP chunk declared size exceeded');
+    if (p.next < count) return;
+    if (p.size !== byteLength) throw new Error('OMP chunk size mismatch');
+    this.pending = null;
+    const result = parseFrameJson(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(p.parts)));
+    if (!result || typeof result !== 'object' || Array.isArray(result) || result.type === 'rpc_chunk') throw new Error('Invalid OMP logical frame');
+    return result;
+  }
+  end() { if (this.buffer.length || this.pending) throw new Error('Truncated OMP JSONL output'); }
+}
+
+export function summarizeOmpEvents(events, { exitCode = 0 } = {}) {
+  let terminal = false, failed = false, aborted = false, assistant = null, elided = false;
+  for (const event of events) {
+    if (/elided for RPC frame|rpcFrameElidedKeys/.test(JSON.stringify(event))) elided = true;
+    if (event.type === 'agent_start' || (event.type === 'agent_end' && event.willContinue === true)) terminal = false;
+    if (event.type === 'agent_end' && event.willContinue !== true) terminal = true;
+    if (event.type === 'rpc_frame_error' || event.type === 'error' || (event.type === 'tool_execution_end' && event.isError)) failed = true;
+    for (const message of [...(event.messages ?? []), ...(event.message ? [event.message] : [])]) {
+      if (message.role === 'assistant') assistant = message;
+      if (message.stopReason === 'error') failed = true;
+      if (message.stopReason === 'aborted') aborted = true;
+    }
+  }
+  const text = (assistant?.content ?? []).filter(c => c.type === 'text').map(c => c.text).join('\n');
+  return { events, settled: terminal, success: terminal && Boolean(assistant) && !failed && !aborted && !elided && exitCode === 0, failed, aborted, elided, text };
+}
+
+/** Owns one native RPC process. Commands correlate by id; prompt ack is never completion. */
+export class OmpRpcClient {
+  // `readyTimeoutMs` bounds only the initial RPC-readiness wait; `timeoutMs` keeps bounding every
+  // command and prompt after that, so widening the first-start budget (#2999) never also widens
+  // this client's ordinary command/prompt deadlines.
+  constructor({ binary = process.env.AIWG_OMP_BIN || 'omp', args = [], cwd, env = process.env, timeoutMs = 30000, readyTimeoutMs = timeoutMs,
+    eventLimit = 16 * MAX_FRAME, closeGraceMs = 5000 } = {}) {
+    this.closeGraceMs = closeGraceMs; this.timeoutMs = timeoutMs; this.events = []; this.eventBytes = 0; this.eventLimit = eventLimit; this.pending = new Map(); this.counter = 0; this.protocolVersion = 1;
+    this.child = spawn(binary, ['--mode', 'rpc', ...args], { cwd, env, stdio: ['pipe', 'pipe', 'pipe'], detached: process.platform !== 'win32' });
+    this.decoder = new OmpFrameDecoder(); this.stderr = '';
+    this.ready = new Promise((resolve, reject) => { this.readyResolve = resolve; this.readyReject = reject; });
+    this.ready.catch(() => {});
+    this.readyTimer = setTimeout(() => this.fail(new Error('OMP RPC ready timeout')), readyTimeoutMs);
+    this.closed = new Promise(resolve => this.child.once('close', (code) => { this.isClosed = true; try { this.decoder.end(); } catch (e) { this.fail(e); } this.fail(new Error(`OMP RPC exited ${code}`)); resolve(code); }));
+    this.child.on('error', e => this.fail(e)); this.child.stdin.on('error', e => this.fail(e));
+    this.child.stderr.on('data', b => { this.stderr = (this.stderr + b.toString()).slice(-4096); });
+    this.child.stdout.on('data', b => { try { for (const frame of this.decoder.push(b)) this.receive(frame); } catch (e) { this.fail(e); } });
+  }
+  receive(frame) {
+    if (frame.type === 'ready') { clearTimeout(this.readyTimer); this.readyResolve(frame); return; }
+    if (frame.type === 'response') {
+      const pending = this.pending.get(frame.id);
+      if (pending) { this.pending.delete(frame.id); clearTimeout(pending.timer); if (frame.command !== pending.type) pending.reject(new Error('OMP response command mismatch')); else if (!frame.success) pending.reject(new Error(`OMP ${pending.type} failed`)); else pending.resolve(frame.data); }
+      return;
+    }
+    const size = Buffer.byteLength(JSON.stringify(frame));
+    if ((this.eventBytes += size) > this.eventLimit) throw new Error('OMP event retention limit exceeded');
+    this.events.push(frame); this.onEvent?.(frame);
+  }
+  async connect() { const ready = await this.ready; if (ready.supportedProtocolVersions?.includes(2)) { await this.command('negotiate_protocol', { protocolVersion: 2 }); this.protocolVersion = 2; } return this; }
+  async command(type, data = {}) {
+    if (this.failure || this.isClosed) throw this.failure ?? new Error('OMP closed');
+    const id = `aiwg-${++this.counter}`;
+    const line = JSON.stringify({ ...data, type, id }) + '\n';
+    if (Buffer.byteLength(line) > MAX_FRAME) throw new Error('OMP command frame limit exceeded');
+    const response = new Promise((resolve, reject) => { const timer = setTimeout(() => { this.pending.delete(id); reject(new Error(`OMP ${type} timeout`)); void this.close(); }, this.timeoutMs); this.pending.set(id, { resolve, reject, timer, type }); });
+    // Awaiting write's callback applies backpressure and catches pipe failure.
+    await new Promise((resolve, reject) => this.child.stdin.write(line, error => error ? reject(error) : resolve())).catch(error => this.fail(error));
+    return response;
+  }
+  async prompt(message, { signal } = {}) {
+    if (this.running) throw new Error('OMP client permits one in-flight prompt');
+    this.running = true; this.events = []; this.eventBytes = 0;
+    try {
+      const terminal = new Promise((resolve, reject) => {
+        this.promptReject = reject;
+        this.onEvent = frame => { if (frame.type === 'agent_end' && frame.willContinue !== true) resolve(); };
+      });
+      terminal.catch(() => {});
+      const abort = () => { this.promptReject?.(new Error('OMP prompt aborted')); void this.close(); };
+      signal?.addEventListener('abort', abort, { once: true });
+      const timer = setTimeout(abort, this.timeoutMs);
+      try { if (signal?.aborted) abort(); await this.command('prompt', { message }); await terminal; const state = await this.command('get_state'); if (state?.isStreaming || state?.queuedMessageCount > 0 || state?.isCompacting) throw new Error('OMP terminal event preceded pending work'); return summarizeOmpEvents(this.events); }
+      finally { clearTimeout(timer); signal?.removeEventListener('abort', abort); this.onEvent = null; this.promptReject = null; }
+    } catch (error) { await this.close(); throw error; } finally { this.running = false; }
+  }
+  fail(error) { if (this.failure) return; this.failure = error; clearTimeout(this.readyTimer); this.readyReject(error); this.promptReject?.(error); for (const p of this.pending.values()) { clearTimeout(p.timer); p.reject(error); } this.pending.clear(); if (!this.isClosed) this.kill('SIGKILL'); }
+  kill(signal) { try { if (process.platform !== 'win32' && Number.isSafeInteger(this.child.pid) && this.child.pid > 0) process.kill(-this.child.pid, signal); else signalChild(this.child, signal); } catch { /* already exited */ } }
+  async close() {
+    if (this.isClosed) return this.closed;
+    if (this.closing) return this.closing;
+    this.closing = (async () => {
+      // Native EOF drains accepted commands and disposes sessions/MCP clients.
+      // Signalling the whole group first can orphan children before OMP reaps them.
+      if (!this.child.stdin.destroyed && !this.child.stdin.writableEnded)
+        this.child.stdin.end(JSON.stringify({ type: 'abort', id: 'aiwg-close' }) + '\n');
+      let killTimer;
+      const termTimer = setTimeout(() => {
+        this.kill('SIGTERM');
+        killTimer = setTimeout(() => this.kill('SIGKILL'), 500);
+      }, this.closeGraceMs);
+      try { return await this.closed; }
+      finally { clearTimeout(termTimer); clearTimeout(killTimer); this.kill('SIGKILL'); }
+    })();
+    return this.closing;
+  }
+}
+
+/**
+ * #2999: a pinned native binary's first cold start competes with whatever else the host is
+ * running (e.g. another CI job) for CPU and page cache, so a fixed RPC-readiness wait can fail
+ * even though the binary is healthy. `warmArgs` touches the binary once, strictly before the RPC
+ * process starts, outside the readiness window (default `--version`, matching the warm-up
+ * `omp-conformance.mjs` already performs) so most of that cold-start cost lands on `warmedMs`
+ * instead of the RPC `readyMs` budget. Callers pass a larger `readyTimeoutMs` (never `timeoutMs`,
+ * which would also widen every later command/prompt deadline on the returned client) for the
+ * first-start budget. All three durations/outcomes are returned so a caller can record them: a
+ * slow start then shows up as a growing number in a conformance report, not only as a timeout.
+ */
+export async function warmAndConnectOmpRpcClient({ binary, cwd, env, warmArgs = ['--version'], warmTimeoutMs = 15000, ...clientOptions }) {
+  const warmStarted = Date.now();
+  // warmTimeoutMs is caller-controlled; clamp it so a caller passing 0 (or
+  // anything else non-positive) can't disable the bound (#3062 B/C finding 8).
+  const warmup = spawnSync(binary, warmArgs, { cwd, env, encoding: 'utf8', timeout: positiveTimeoutMs(warmTimeoutMs, 15000), killSignal: 'SIGKILL' });
+  const warmedMs = Date.now() - warmStarted;
+  const warmupResult = { status: warmup.status ?? null, signal: warmup.signal ?? null, error: warmup.error ? String(warmup.error.message ?? warmup.error) : null };
+  const readyStarted = Date.now();
+  const client = new OmpRpcClient({ binary, cwd, env, ...clientOptions });
+  try { await client.connect(); }
+  catch (error) { await client.close(); throw error; }
+  return { client, warmup: warmupResult, warmedMs, readyMs: Date.now() - readyStarted };
+}