nubos-pilot 1.2.4 → 1.3.1

package/bin/np-tools/spawn-headless.cjs

@@ -9,8 +9,35 @@ const { NubosPilotError, atomicWriteFileSync, appendJsonl, findProjectRoot } = r
 const runContext = require('../../lib/run-context.cjs');
 const safePath = require('../../lib/safe-path.cjs');
 const headlessGuard = require('../../lib/headless-guard.cjs');
+const compress = require('../../lib/compress.cjs');
+const elision = require('../../lib/elision.cjs');
+const elisionProxy = require('../../lib/elision-proxy.cjs');
+const steering = require('../../lib/output-steering.cjs');
+const logger = require('../../lib/logger.cjs').child('spawn-headless');
 const args = require('./_args.cjs');
 
+const PROXY_START_TIMEOUT_MS = 5000;
+
+function _startCompressionProxy(cwd) {
+  const upstream = process.env.ANTHROPIC_BASE_URL || '';
+  return new Promise((resolve, reject) => {
+    const proc = child_process.fork(path.join(__dirname, '_elision-proxy-entry.cjs'), [], {
+      env: Object.assign({}, process.env, { ELISION_PROXY_CWD: cwd, ELISION_PROXY_UPSTREAM: upstream }),
+      stdio: ['ignore', 'ignore', 'inherit', 'ipc'],
+    });
+    const timer = setTimeout(() => {
+      try { proc.kill(); } catch { /* already gone */ }
+      reject(new NubosPilotError('elision-proxy-start-timeout', 'compression proxy did not report ready in time', {}));
+    }, PROXY_START_TIMEOUT_MS);
+    proc.once('message', (m) => {
+      clearTimeout(timer);
+      if (m && m.ready) resolve({ proc, baseUrl: m.baseUrl });
+      else { try { proc.kill(); } catch { /* already gone */ } reject(new NubosPilotError('elision-proxy-start-failed', String(m && m.error), {})); }
+    });
+    proc.once('error', (err) => { clearTimeout(timer); reject(err); });
+  });
+}
+
 function _sha256(s) {
   return crypto.createHash('sha256').update(s == null ? '' : String(s)).digest('hex');
 }
@@ -159,6 +186,20 @@ function _composePrompt(agentBody, userPrompt) {
   return agentBody.trimEnd() + '\n\n---\n\n' + userPrompt.trimEnd() + '\n';
 }
 
+function _maybeCompressPrompt(prompt, cwd) {
+  const none = { prompt, stats: null };
+  const cx = elision.compressionContext(cwd);
+  if (!cx.enabled) return none;
+  try {
+    const out = compress.compressPrompt(prompt, { minBlockBytes: cx.minBlockBytes, store: cx.store });
+    if (!out || out.stats.blocks_compressed === 0) return none;
+    return { prompt: out.text, stats: out.stats };
+  } catch (err) {
+    logger.warn('compression skipped', { cause: err && err.message });
+    return none;
+  }
+}
+
 function _stripFrontmatter(md) {
   if (!md.startsWith('---\n')) return md;
   const end = md.indexOf('\n---\n', 4);
@@ -166,7 +207,88 @@ function _stripFrontmatter(md) {
   return md.slice(end + 5);
 }
 
-function run(argv, ctx) {
+function _defaultResolveKind(agent, cwd) {
+  const { resolveFromConfig } = require('./resolve-model.cjs');
+  return resolveFromConfig({ agentOrTier: agent, cwd });
+}
+
+async function _runOffHost(o) {
+  const dispatch = o.dispatchImpl || require('../../lib/runtime/dispatch.cjs').dispatchOffHost;
+  const startedAt = o.startedAt;
+  let result = null;
+  let errObj = null;
+  try {
+    result = await dispatch({ agent: o.agent, task: o.userPrompt, cwd: o.cwd });
+  } catch (err) {
+    errObj = {
+      code: (err && err.code) || 'spawn-headless-offhost-failed',
+      message: (err && err.message) || 'off-host dispatch failed',
+    };
+  }
+  const endedAt = new Date().toISOString();
+  const content = result ? (result.content || '') : '';
+
+  const envelope = JSON.stringify({
+    type: 'result',
+    result: content,
+    model: result ? result.model : null,
+    provider: result ? result.provider : null,
+    is_error: !!errObj,
+  });
+  atomicWriteFileSync(o.resolvedOutput, envelope, 'utf-8', 0o600);
+
+  const exitCode = errObj ? 2 : 0;
+  const spawnTrailPath = _spawnTrailPath(o.cwd);
+  const spawnRecord = {
+    run_id: o.runId,
+    started_at: startedAt,
+    ended_at: endedAt,
+    duration_ms: Math.max(0, Date.parse(endedAt) - Date.parse(startedAt)),
+    agent: o.agent,
+    bin: 'off-host:' + (result ? result.provider : 'unknown'),
+    exit_code: exitCode,
+    timed_out: false,
+    prompt_sha256: _sha256(o.userPrompt),
+    prompt_bytes: Buffer.byteLength(o.userPrompt || '', 'utf-8'),
+    response_sha256: _sha256(content),
+    response_bytes: Buffer.byteLength(content, 'utf-8'),
+    stderr_excerpt: errObj ? _redactSecrets(String(errObj.message)).slice(-STDERR_TAIL_BYTES) : '',
+    model_actual: result ? result.model : null,
+    tokens_in: null,
+    tokens_out: null,
+    payload_parse_ok: !errObj,
+    runtime: result ? result.provider : 'off-host',
+  };
+  try { appendJsonl(spawnTrailPath, spawnRecord, { maxLineBytes: 16 * 1024, mode: 0o600 }); }
+  catch (err) {
+    throw new NubosPilotError(
+      'spawn-headless-audit-persist-failed',
+      'spawn-trail append failed; refusing to commit response without audit record',
+      { file: 'spawns.jsonl', cause: (err && err.code) || 'unknown' },
+    );
+  }
+
+  const payload = {
+    agent: o.agent,
+    output_path: o.outputPath,
+    output_path_resolved: o.resolvedOutput,
+    exit_code: exitCode,
+    stderr_excerpt: spawnRecord.stderr_excerpt,
+    bin: spawnRecord.bin,
+    timed_out: false,
+    run_id: o.runId,
+    spawn_trail_path: spawnTrailPath,
+    model_actual: spawnRecord.model_actual,
+    tokens_in: null,
+    tokens_out: null,
+    payload_parse_ok: spawnRecord.payload_parse_ok,
+    off_host: true,
+  };
+  o.stdout.write(JSON.stringify(payload) + '\n');
+  return exitCode;
+}
+
+async function run(argv, ctx) {
   const context = ctx || {};
   const cwd = context.cwd || process.cwd();
   const stdout = context.stdout || process.stdout;
@@ -223,13 +345,29 @@ function run(argv, ctx) {
   }
 
   const agentPath = _resolveAgentPath(agent, cwd);
-  const agentBody = _stripFrontmatter(fs.readFileSync(agentPath, 'utf-8'));
+  let agentBody = _stripFrontmatter(fs.readFileSync(agentPath, 'utf-8'));
+  const _os = elision.compressionContext(cwd).outputSteering;
+  if (_os && _os.enabled) agentBody = steering.enrichSystemPrompt(agentBody, _os.profile);
   const userPrompt = _readPromptFile(promptPath, cwd);
-  const composedPrompt = _composePrompt(agentBody, userPrompt);
+  let composedPrompt = _composePrompt(agentBody, userPrompt);
   const resolvedOutput = _ensureOutputDir(outputPath, cwd);
 
   const runId = runContext.getRunId();
 
+  const resolveKind = context.resolveImpl || _defaultResolveKind;
+  let routed;
+  try { routed = resolveKind(agent, cwd); } catch { routed = { kind: 'native' }; }
+  if (routed && routed.kind === 'openai-compat') {
+    return _runOffHost({
+      agent, userPrompt, resolvedOutput, outputPath, cwd, runId, stdout,
+      startedAt: new Date().toISOString(),
+      dispatchImpl: context.dispatchImpl,
+    });
+  }
+
+  const compression = _maybeCompressPrompt(composedPrompt, cwd);
+  composedPrompt = compression.prompt;
+
   let lockRoot;
   try { lockRoot = findProjectRoot(cwd); }
   catch { lockRoot = cwd; }
@@ -245,6 +383,17 @@ function run(argv, ctx) {
   const childEnv = _filterSpawnEnv(process.env);
   Object.assign(childEnv, headlessGuard.childSpawnEnv(process.env));
 
+  let proxyProc = null;
+  if (elisionProxy.proxyEnabled(cwd)) {
+    try {
+      const started = await _startCompressionProxy(cwd);
+      proxyProc = started.proc;
+      childEnv.ANTHROPIC_BASE_URL = started.baseUrl;
+    } catch (err) {
+      logger.warn('compression proxy unavailable; spawning without it', { cause: err && err.message });
+    }
+  }
+
   const bin = _claudeBinary();
   const claudeArgs = ['-p', '--output-format', 'json'];
   const startedAt = new Date().toISOString();
@@ -266,6 +415,7 @@ function run(argv, ctx) {
       { bin, cause: err && err.code },
     );
   } finally {
+    if (proxyProc) { try { proxyProc.kill(); } catch { /* already exited */ } }
     lock.release();
   }
   if (result.error && result.error.code === 'ENOENT') {
@@ -307,6 +457,7 @@ function run(argv, ctx) {
     tokens_in: claudeMeta.tokens_in == null ? null : claudeMeta.tokens_in,
     tokens_out: claudeMeta.tokens_out == null ? null : claudeMeta.tokens_out,
     payload_parse_ok: claudeMeta.parse_ok,
+    compression: compression.stats || null,
   };
   try { appendJsonl(spawnTrailPath, spawnRecord, { maxLineBytes: 16 * 1024, mode: 0o600 }); }
   catch (err) {
@@ -332,6 +483,7 @@ function run(argv, ctx) {
     tokens_in: spawnRecord.tokens_in,
     tokens_out: spawnRecord.tokens_out,
     payload_parse_ok: spawnRecord.payload_parse_ok,
+    compression: compression.stats || null,
   };
   stdout.write(JSON.stringify(payload) + '\n');
   if (exitCode !== 0) return 2;

package/bin/np-tools/spawn-headless.test.cjs

@@ -56,30 +56,30 @@ function _setEnv(k, v) {
   else process.env[k] = v;
 }
 
-test('SH-1: spawn-headless requires --agent', () => {
+test('SH-1: spawn-headless requires --agent', async () => {
   const r = _mkRoot();
   const cap = _cap();
-  assert.throws(
-    () => spawnHeadless.run([], { cwd: r, stdout: cap.stub }),
+  await assert.rejects(
+    async () => spawnHeadless.run([], { cwd: r, stdout: cap.stub }),
     (err) => err && err.code === 'spawn-headless-missing-agent',
   );
 });
 
-test('SH-2: spawn-headless requires --prompt-path', () => {
+test('SH-2: spawn-headless requires --prompt-path', async () => {
   const r = _mkRoot();
   const cap = _cap();
-  assert.throws(
-    () => spawnHeadless.run(['--agent', 'np-test-critic'], { cwd: r, stdout: cap.stub }),
+  await assert.rejects(
+    async () => spawnHeadless.run(['--agent', 'np-test-critic'], { cwd: r, stdout: cap.stub }),
     (err) => err && err.code === 'spawn-headless-missing-prompt-path',
   );
 });
 
-test('SH-3: spawn-headless requires --output-path', () => {
+test('SH-3: spawn-headless requires --output-path', async () => {
   const r = _mkRoot();
   fs.writeFileSync(path.join(r, 'p.md'), 'do the audit', 'utf-8');
   const cap = _cap();
-  assert.throws(
-    () => spawnHeadless.run(
+  await assert.rejects(
+    async () => spawnHeadless.run(
       ['--agent', 'np-test-critic', '--prompt-path', 'p.md'],
       { cwd: r, stdout: cap.stub },
     ),
@@ -87,11 +87,11 @@ test('SH-3: spawn-headless requires --output-path', () => {
   );
 });
 
-test('SH-4: spawn-headless rejects path traversal on prompt-path', () => {
+test('SH-4: spawn-headless rejects path traversal on prompt-path', async () => {
   const r = _mkRoot();
   const cap = _cap();
-  assert.throws(
-    () => spawnHeadless.run(
+  await assert.rejects(
+    async () => spawnHeadless.run(
       ['--agent', 'np-test-critic',
         '--prompt-path', '/etc/passwd',
         '--output-path', 'out.json'],
@@ -101,12 +101,12 @@ test('SH-4: spawn-headless rejects path traversal on prompt-path', () => {
   );
 });
 
-test('SH-5: spawn-headless rejects unknown agent', () => {
+test('SH-5: spawn-headless rejects unknown agent', async () => {
   const r = _mkRoot();
   fs.writeFileSync(path.join(r, 'p.md'), 'audit', 'utf-8');
   const cap = _cap();
-  assert.throws(
-    () => spawnHeadless.run(
+  await assert.rejects(
+    async () => spawnHeadless.run(
       ['--agent', 'np-does-not-exist',
         '--prompt-path', 'p.md',
         '--output-path', 'out.json'],
@@ -116,12 +116,12 @@ test('SH-5: spawn-headless rejects unknown agent', () => {
   );
 });
 
-test('SH-6: spawn-headless rejects invalid agent name (path-injection guard)', () => {
+test('SH-6: spawn-headless rejects invalid agent name (path-injection guard)', async () => {
   const r = _mkRoot();
   fs.writeFileSync(path.join(r, 'p.md'), 'audit', 'utf-8');
   const cap = _cap();
-  assert.throws(
-    () => spawnHeadless.run(
+  await assert.rejects(
+    async () => spawnHeadless.run(
       ['--agent', '../../etc/passwd',
         '--prompt-path', 'p.md',
         '--output-path', 'out.json'],
@@ -131,13 +131,13 @@ test('SH-6: spawn-headless rejects invalid agent name (path-injection guard)', (
   );
 });
 
-test('SH-7: spawn-headless reports claude-not-found when binary missing', () => {
+test('SH-7: spawn-headless reports claude-not-found when binary missing', async () => {
   const r = _mkRoot();
   fs.writeFileSync(path.join(r, 'p.md'), 'audit', 'utf-8');
   _setEnv('NUBOS_PILOT_CLAUDE_BIN', path.join(r, 'no-such-binary'));
   const cap = _cap();
-  assert.throws(
-    () => spawnHeadless.run(
+  await assert.rejects(
+    async () => spawnHeadless.run(
       ['--agent', 'np-test-critic',
         '--prompt-path', 'p.md',
         '--output-path', 'out.json'],
@@ -147,7 +147,7 @@ test('SH-7: spawn-headless reports claude-not-found when binary missing', () =>
   );
 });
 
-test('SH-8: spawn-headless captures stdout to output-path on success (mock binary)', () => {
+test('SH-8: spawn-headless captures stdout to output-path on success (mock binary)', async () => {
   const r = _mkRoot();
   fs.writeFileSync(path.join(r, 'p.md'), 'audit', 'utf-8');
   const mockBin = path.join(r, 'mock-claude.sh');
@@ -155,7 +155,7 @@ test('SH-8: spawn-headless captures stdout to output-path on success (mock binar
   fs.chmodSync(mockBin, 0o755);
   _setEnv('NUBOS_PILOT_CLAUDE_BIN', mockBin);
   const cap = _cap();
-  const rc = spawnHeadless.run(
+  const rc = await spawnHeadless.run(
     ['--agent', 'np-test-critic',
       '--prompt-path', 'p.md',
       '--output-path', 'out.json'],
@@ -169,7 +169,7 @@ test('SH-8: spawn-headless captures stdout to output-path on success (mock binar
   assert.match(written, /"verdict":"passed"/);
 });
 
-test('SH-9: spawn-headless surfaces non-zero subprocess exit (mock failure)', () => {
+test('SH-9: spawn-headless surfaces non-zero subprocess exit (mock failure)', async () => {
   const r = _mkRoot();
   fs.writeFileSync(path.join(r, 'p.md'), 'audit', 'utf-8');
   const mockBin = path.join(r, 'mock-fail.sh');
@@ -177,7 +177,7 @@ test('SH-9: spawn-headless surfaces non-zero subprocess exit (mock failure)', ()
   fs.chmodSync(mockBin, 0o755);
   _setEnv('NUBOS_PILOT_CLAUDE_BIN', mockBin);
   const cap = _cap();
-  const rc = spawnHeadless.run(
+  const rc = await spawnHeadless.run(
     ['--agent', 'np-test-critic',
       '--prompt-path', 'p.md',
       '--output-path', 'out.json'],
@@ -189,12 +189,12 @@ test('SH-9: spawn-headless surfaces non-zero subprocess exit (mock failure)', ()
   assert.match(payload.stderr_excerpt, /boom/);
 });
 
-test('SH-10: spawn-headless rejects --timeout-ms below 1000', () => {
+test('SH-10: spawn-headless rejects --timeout-ms below 1000', async () => {
   const r = _mkRoot();
   fs.writeFileSync(path.join(r, 'p.md'), 'audit', 'utf-8');
   const cap = _cap();
-  assert.throws(
-    () => spawnHeadless.run(
+  await assert.rejects(
+    async () => spawnHeadless.run(
       ['--agent', 'np-test-critic',
         '--prompt-path', 'p.md',
         '--output-path', 'out.json',
@@ -205,7 +205,7 @@ test('SH-10: spawn-headless rejects --timeout-ms below 1000', () => {
   );
 });
 
-test('SH-11: spawn-headless writes output atomically (no .tmp residue)', () => {
+test('SH-11: spawn-headless writes output atomically (no .tmp residue)', async () => {
   const r = _mkRoot();
   fs.writeFileSync(path.join(r, 'p.md'), 'audit', 'utf-8');
   const mockBin = path.join(r, 'mock-claude.sh');
@@ -213,7 +213,7 @@ test('SH-11: spawn-headless writes output atomically (no .tmp residue)', () => {
   fs.chmodSync(mockBin, 0o755);
   _setEnv('NUBOS_PILOT_CLAUDE_BIN', mockBin);
   const cap = _cap();
-  const rc = spawnHeadless.run(
+  const rc = await spawnHeadless.run(
     ['--agent', 'np-test-critic',
       '--prompt-path', 'p.md',
       '--output-path', 'out.json'],
@@ -321,7 +321,7 @@ test('SH-REDACT-2 _redactSecrets is a no-op on safe text', () => {
   assert.equal(spawnHeadless._redactSecrets(safe), safe);
 });
 
-test('SH-AUDIT-FIRST spawn-trail is written BEFORE caller-visible output (audit-first)', () => {
+test('SH-AUDIT-FIRST spawn-trail is written BEFORE caller-visible output (audit-first)', async () => {
   const r = _mkRoot();
   fs.writeFileSync(path.join(r, 'p.md'), 'audit', 'utf-8');
   const mockBin = path.join(r, 'mock.sh');
@@ -335,7 +335,7 @@ test('SH-AUDIT-FIRST spawn-trail is written BEFORE caller-visible output (audit-
   const cap = _cap();
   let thrown = null;
   try {
-    spawnHeadless.run(
+    await spawnHeadless.run(
       ['--agent', 'np-test-critic', '--prompt-path', 'p.md', '--output-path', 'out.json'],
       { cwd: r, stdout: cap.stub },
     );
@@ -348,7 +348,7 @@ test('SH-AUDIT-FIRST spawn-trail is written BEFORE caller-visible output (audit-
     'output must NOT exist if audit append failed (audit-first invariant)');
 });
 
-test('SH-PARSE-OK payload_parse_ok=false when claude returns non-JSON output', () => {
+test('SH-PARSE-OK payload_parse_ok=false when claude returns non-JSON output', async () => {
   const r = _mkRoot();
   fs.writeFileSync(path.join(r, 'p.md'), 'audit', 'utf-8');
   const mockBin = path.join(r, 'mock-plain.sh');
@@ -357,7 +357,7 @@ test('SH-PARSE-OK payload_parse_ok=false when claude returns non-JSON output', (
   _setEnv('NUBOS_PILOT_CLAUDE_BIN', mockBin);
   _setEnv('NUBOS_PILOT_RUN_ID', 'r-parse-test');
   const cap = _cap();
-  spawnHeadless.run(
+  await spawnHeadless.run(
     ['--agent', 'np-test-critic', '--prompt-path', 'p.md', '--output-path', 'out.json'],
     { cwd: r, stdout: cap.stub },
   );
@@ -415,7 +415,7 @@ test('SH-ENV-3 NUBOS_PILOT_SPAWN_ENV_PASSTHROUGH allow-lists by exact key name',
   assert.equal(filtered.NOT_LISTED, undefined);
 });
 
-test('SH-TRAIL-1 spawn writes append-only spawn-trail record with run_id + prompt/response sha256 + timing', () => {
+test('SH-TRAIL-1 spawn writes append-only spawn-trail record with run_id + prompt/response sha256 + timing', async () => {
   const r = _mkRoot();
   fs.writeFileSync(path.join(r, 'p.md'), 'do the audit', 'utf-8');
   const mockBin = path.join(r, 'mock-claude.sh');
@@ -424,7 +424,7 @@ test('SH-TRAIL-1 spawn writes append-only spawn-trail record with run_id + promp
   _setEnv('NUBOS_PILOT_CLAUDE_BIN', mockBin);
   _setEnv('NUBOS_PILOT_RUN_ID', 'r-traceme-deadbeef');
   const cap = _cap();
-  const rc = spawnHeadless.run(
+  const rc = await spawnHeadless.run(
     ['--agent', 'np-test-critic', '--prompt-path', 'p.md', '--output-path', 'out.json'],
     { cwd: r, stdout: cap.stub },
   );
@@ -452,7 +452,7 @@ test('SH-TRAIL-1 spawn writes append-only spawn-trail record with run_id + promp
   assert.ok(Number.isFinite(rec.duration_ms) && rec.duration_ms >= 0);
 });
 
-test('SH-TRAIL-1b run_id is seeded BEFORE spawn so the child env inherits NUBOS_PILOT_RUN_ID', () => {
+test('SH-TRAIL-1b run_id is seeded BEFORE spawn so the child env inherits NUBOS_PILOT_RUN_ID', async () => {
   const r = _mkRoot();
   fs.writeFileSync(path.join(r, 'p.md'), 'audit', 'utf-8');
   // Mock-claude echoes its own ENV var so we can prove the child saw it.
@@ -465,7 +465,7 @@ test('SH-TRAIL-1b run_id is seeded BEFORE spawn so the child env inherits NUBOS_
   // Crucially: do NOT set NUBOS_PILOT_RUN_ID; the lazy-seed must happen.
   runContext._resetForTests();
   const cap = _cap();
-  spawnHeadless.run(
+  await spawnHeadless.run(
     ['--agent', 'np-test-critic', '--prompt-path', 'p.md', '--output-path', 'out.json'],
     { cwd: r, stdout: cap.stub },
   );
@@ -475,7 +475,7 @@ test('SH-TRAIL-1b run_id is seeded BEFORE spawn so the child env inherits NUBOS_
   assert.equal(childRunId, payload.run_id, 'child must inherit parent NUBOS_PILOT_RUN_ID via filtered env');
 });
 
-test('SH-TRAIL-2 two sequential spawns append two parseable trail lines (jsonl integrity)', () => {
+test('SH-TRAIL-2 two sequential spawns append two parseable trail lines (jsonl integrity)', async () => {
   const r = _mkRoot();
   fs.writeFileSync(path.join(r, 'p.md'), 'audit X', 'utf-8');
   const mockBin = path.join(r, 'mock.sh');
@@ -485,7 +485,7 @@ test('SH-TRAIL-2 two sequential spawns append two parseable trail lines (jsonl i
   _setEnv('NUBOS_PILOT_RUN_ID', 'r-test-multi-aaa1');
   const cap = _cap();
   for (let i = 0; i < 2; i++) {
-    spawnHeadless.run(
+    await spawnHeadless.run(
       ['--agent', 'np-test-critic', '--prompt-path', 'p.md', '--output-path', 'out' + i + '.json'],
       { cwd: r, stdout: cap.stub },
     );
@@ -496,15 +496,15 @@ test('SH-TRAIL-2 two sequential spawns append two parseable trail lines (jsonl i
   for (const l of lines) JSON.parse(l);
 });
 
-test('SH-GUARD-1 refuses to spawn when NUBOS_PILOT_HEADLESS=1 (reentrancy guard)', () => {
+test('SH-GUARD-1 refuses to spawn when NUBOS_PILOT_HEADLESS=1 (reentrancy guard)', async () => {
   const r = _mkRoot();
   fs.writeFileSync(path.join(r, 'p.md'), 'audit', 'utf-8');
   const mockBin = _mockClaude(r, 'mock.sh', '#!/bin/sh\ncat > /dev/null\necho "{}"\n');
   _setEnv('NUBOS_PILOT_CLAUDE_BIN', mockBin);
   _setEnv('NUBOS_PILOT_HEADLESS', '1');
   const cap = _cap();
-  assert.throws(
-    () => spawnHeadless.run(
+  await assert.rejects(
+    spawnHeadless.run(
       ['--agent', 'np-test-critic', '--prompt-path', 'p.md', '--output-path', 'out.json'],
       { cwd: r, stdout: cap.stub },
     ),
@@ -513,15 +513,15 @@ test('SH-GUARD-1 refuses to spawn when NUBOS_PILOT_HEADLESS=1 (reentrancy guard)
   assert.equal(fs.existsSync(path.join(r, 'out.json')), false, 'no claude must be spawned inside a headless run');
 });
 
-test('SH-GUARD-2 refuses to spawn when hook depth has reached the cap (depth guard)', () => {
+test('SH-GUARD-2 refuses to spawn when hook depth has reached the cap (depth guard)', async () => {
   const r = _mkRoot();
   fs.writeFileSync(path.join(r, 'p.md'), 'audit', 'utf-8');
   const mockBin = _mockClaude(r, 'mock.sh', '#!/bin/sh\ncat > /dev/null\necho "{}"\n');
   _setEnv('NUBOS_PILOT_CLAUDE_BIN', mockBin);
   _setEnv('NUBOS_PILOT_HOOK_DEPTH', '1');
   const cap = _cap();
-  assert.throws(
-    () => spawnHeadless.run(
+  await assert.rejects(
+    spawnHeadless.run(
       ['--agent', 'np-test-critic', '--prompt-path', 'p.md', '--output-path', 'out.json'],
       { cwd: r, stdout: cap.stub },
     ),
@@ -529,14 +529,14 @@ test('SH-GUARD-2 refuses to spawn when hook depth has reached the cap (depth gua
   );
 });
 
-test('SH-GUARD-3 child env carries NUBOS_PILOT_HEADLESS=1 and depth=1 (one level deep only)', () => {
+test('SH-GUARD-3 child env carries NUBOS_PILOT_HEADLESS=1 and depth=1 (one level deep only)', async () => {
   const r = _mkRoot();
   fs.writeFileSync(path.join(r, 'p.md'), 'audit', 'utf-8');
   const mockBin = _mockClaude(r, 'mock.sh',
     '#!/bin/sh\ncat > /dev/null\nprintf \'{"hl":"\'$NUBOS_PILOT_HEADLESS\'","depth":"\'$NUBOS_PILOT_HOOK_DEPTH\'"}\\n\'\n');
   _setEnv('NUBOS_PILOT_CLAUDE_BIN', mockBin);
   const cap = _cap();
-  const rc = spawnHeadless.run(
+  const rc = await spawnHeadless.run(
     ['--agent', 'np-test-critic', '--prompt-path', 'p.md', '--output-path', 'out.json'],
     { cwd: r, stdout: cap.stub },
   );
@@ -546,7 +546,7 @@ test('SH-GUARD-3 child env carries NUBOS_PILOT_HEADLESS=1 and depth=1 (one level
   assert.equal(child.depth, '1', 'child claude must run at hook depth 1');
 });
 
-test('SH-GUARD-4 refuses to spawn while a live lock for the same agent is held (concurrency guard)', () => {
+test('SH-GUARD-4 refuses to spawn while a live lock for the same agent is held (concurrency guard)', async () => {
   const r = _mkRoot();
   fs.writeFileSync(path.join(r, 'p.md'), 'audit', 'utf-8');
   const mockBin = _mockClaude(r, 'mock.sh', '#!/bin/sh\ncat > /dev/null\necho "{}"\n');
@@ -555,8 +555,8 @@ test('SH-GUARD-4 refuses to spawn while a live lock for the same agent is held (
   assert.equal(held.acquired, true);
   const cap = _cap();
   try {
-    assert.throws(
-      () => spawnHeadless.run(
+    await assert.rejects(
+      spawnHeadless.run(
         ['--agent', 'np-test-critic', '--prompt-path', 'p.md', '--output-path', 'out.json'],
         { cwd: r, stdout: cap.stub },
       ),
@@ -567,14 +567,14 @@ test('SH-GUARD-4 refuses to spawn while a live lock for the same agent is held (
   }
 });
 
-test('SH-GUARD-5 lock is released after a successful spawn (re-spawnable)', () => {
+test('SH-GUARD-5 lock is released after a successful spawn (re-spawnable)', async () => {
   const r = _mkRoot();
   fs.writeFileSync(path.join(r, 'p.md'), 'audit', 'utf-8');
   const mockBin = _mockClaude(r, 'mock.sh', '#!/bin/sh\ncat > /dev/null\necho "{}"\n');
   _setEnv('NUBOS_PILOT_CLAUDE_BIN', mockBin);
   const cap = _cap();
   for (let i = 0; i < 2; i++) {
-    const rc = spawnHeadless.run(
+    const rc = await spawnHeadless.run(
       ['--agent', 'np-test-critic', '--prompt-path', 'p.md', '--output-path', 'out' + i + '.json'],
       { cwd: r, stdout: cap.stub },
     );
@@ -583,7 +583,7 @@ test('SH-GUARD-5 lock is released after a successful spawn (re-spawnable)', () =
   assert.equal(fs.existsSync(headlessGuard._lockPath(r, 'np-test-critic')), false, 'no lock residue after spawns');
 });
 
-test('SH-GUARD-6 a held lock for one agent does NOT block a different agent (per-agent scope)', () => {
+test('SH-GUARD-6 a held lock for one agent does NOT block a different agent (per-agent scope)', async () => {
   const r = _mkRoot();
   fs.writeFileSync(
     path.join(r, '.nubos-pilot', 'agents', 'np-other-critic.md'),
@@ -597,7 +597,7 @@ test('SH-GUARD-6 a held lock for one agent does NOT block a different agent (per
   assert.equal(held.acquired, true);
   const cap = _cap();
   try {
-    const rc = spawnHeadless.run(
+    const rc = await spawnHeadless.run(
       ['--agent', 'np-other-critic', '--prompt-path', 'p.md', '--output-path', 'out.json'],
       { cwd: r, stdout: cap.stub },
     );
@@ -607,13 +607,13 @@ test('SH-GUARD-6 a held lock for one agent does NOT block a different agent (per
   }
 });
 
-test('SH-GUARD-7 lock is released even when the spawn errors (claude-not-found)', () => {
+test('SH-GUARD-7 lock is released even when the spawn errors (claude-not-found)', async () => {
   const r = _mkRoot();
   fs.writeFileSync(path.join(r, 'p.md'), 'audit', 'utf-8');
   _setEnv('NUBOS_PILOT_CLAUDE_BIN', path.join(r, 'no-such-binary'));
   const cap = _cap();
-  assert.throws(
-    () => spawnHeadless.run(
+  await assert.rejects(
+    spawnHeadless.run(
       ['--agent', 'np-test-critic', '--prompt-path', 'p.md', '--output-path', 'out.json'],
       { cwd: r, stdout: cap.stub },
     ),
@@ -639,3 +639,53 @@ test('SH-ENV-4 NUBOS_PILOT_/CLAUDE_/ANTHROPIC_ prefixed vars pass through (white
   assert.equal(filtered.ANTHROPIC_BASE_URL, 'https://api.anthropic.com');
   assert.equal(filtered.UNRELATED_FOO, undefined);
 });
+
+test('SH-OFFHOST-1: openai-compat routing runs dispatchOffHost and writes a {result} envelope (no claude -p)', async () => {
+  const r = _mkRoot();
+  fs.writeFileSync(path.join(r, 'p.md'), 'review this diff', 'utf-8');
+  const cap = _cap();
+  let claudeWasCalled = false;
+  _setEnv('NUBOS_PILOT_CLAUDE_BIN', path.join(r, 'nonexistent-claude-should-not-run'));
+  let dispatchArgs = null;
+  const code = await spawnHeadless.run(
+    ['--agent', 'np-test-critic', '--prompt-path', 'p.md', '--output-path', 'out.json'],
+    {
+      cwd: r,
+      stdout: cap.stub,
+      resolveImpl: () => ({ kind: 'openai-compat', provider: 'ollama', model: 'qwen2.5-coder:32b' }),
+      dispatchImpl: async (o) => { dispatchArgs = o; return { content: 'REVIEW: 0 risks', model: 'qwen2.5-coder:32b', provider: 'ollama' }; },
+    },
+  );
+  assert.equal(code, 0);
+  // dispatch received the agent + the prompt body as the task
+  assert.equal(dispatchArgs.agent, 'np-test-critic');
+  assert.match(dispatchArgs.task, /review this diff/);
+  // output is the claude-compatible {result} envelope so review/extract parse it unchanged
+  const out = JSON.parse(fs.readFileSync(path.join(r, 'out.json'), 'utf-8'));
+  assert.equal(out.result, 'REVIEW: 0 risks');
+  assert.equal(out.provider, 'ollama');
+  // caller-visible payload marks it off-host and the native claude bin was never invoked
+  const payload = JSON.parse(cap.get().trim());
+  assert.equal(payload.off_host, true);
+  assert.equal(payload.exit_code, 0);
+  assert.equal(claudeWasCalled, false);
+});
+
+test('SH-OFFHOST-2: a failing off-host dispatch returns exit 2 with an empty result (soft-fail parity)', async () => {
+  const r = _mkRoot();
+  fs.writeFileSync(path.join(r, 'p.md'), 'review', 'utf-8');
+  const cap = _cap();
+  const code = await spawnHeadless.run(
+    ['--agent', 'np-test-critic', '--prompt-path', 'p.md', '--output-path', 'out.json'],
+    {
+      cwd: r,
+      stdout: cap.stub,
+      resolveImpl: () => ({ kind: 'openai-compat', provider: 'ollama', model: 'x' }),
+      dispatchImpl: async () => { const e = new Error('provider unreachable'); e.code = 'preflight-failed'; throw e; },
+    },
+  );
+  assert.equal(code, 2);
+  const out = JSON.parse(fs.readFileSync(path.join(r, 'out.json'), 'utf-8'));
+  assert.equal(out.result, '');
+  assert.equal(out.is_error, true);
+});