nubos-pilot 1.2.3 → 1.3.0

package/lib/runtime/tools/index.test.cjs

@@ -0,0 +1,230 @@
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { test, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+
+const { toolsetFor, execute, _globToRegex, READ_ONLY_TOOL_NAMES, MUTATING_TOOL_NAMES } = require('./index.cjs');
+
+const _dirs = [];
+function _ws(files) {
+  const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'np-tools-')));
+  for (const [rel, content] of Object.entries(files)) {
+    const abs = path.join(root, rel);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content, 'utf-8');
+  }
+  _dirs.push(root);
+  return root;
+}
+afterEach(() => { while (_dirs.length) { try { fs.rmSync(_dirs.pop(), { recursive: true, force: true }); } catch {} } });
+
+test('TOOL-1: Read returns line-numbered content', () => {
+  const cwd = _ws({ 'a.txt': 'one\ntwo\nthree' });
+  const out = execute('Read', { path: 'a.txt' }, { cwd });
+  assert.equal(out, '1\tone\n2\ttwo\n3\tthree');
+});
+
+test('TOOL-2: Read honours offset/limit', () => {
+  const cwd = _ws({ 'a.txt': 'l1\nl2\nl3\nl4' });
+  const out = execute('Read', { path: 'a.txt', offset: 1, limit: 2 }, { cwd });
+  assert.equal(out, '2\tl2\n3\tl3');
+});
+
+test('TOOL-3: Read outside cwd is refused (safe-path)', () => {
+  const cwd = _ws({ 'a.txt': 'x' });
+  const out = execute('Read', { path: '../../etc/passwd' }, { cwd });
+  assert.match(out, /^Error: safe-path-outside-base/);
+});
+
+test('TOOL-4: Glob matches by pattern, ignores node_modules', () => {
+  const cwd = _ws({ 'src/a.ts': '', 'src/b.ts': '', 'node_modules/x/c.ts': '', 'readme.md': '' });
+  const out = execute('Glob', { pattern: 'src/**/*.ts' }, { cwd });
+  assert.equal(out, 'src/a.ts\nsrc/b.ts');
+});
+
+test('TOOL-5: Grep returns relpath:line:text matches', () => {
+  const cwd = _ws({ 'a.js': 'const x = 1\nfunction foo() {}\n', 'b.js': 'function bar() {}\n' });
+  const out = execute('Grep', { pattern: 'function (\\w+)' }, { cwd });
+  const lines = out.split('\n').sort();
+  assert.deepEqual(lines, ['a.js:2:function foo() {}', 'b.js:1:function bar() {}']);
+});
+
+test('TOOL-6: Grep with glob restricts scanned files', () => {
+  const cwd = _ws({ 'a.js': 'needle\n', 'b.ts': 'needle\n' });
+  const out = execute('Grep', { pattern: 'needle', glob: '*.ts' }, { cwd });
+  assert.equal(out, 'b.ts:1:needle');
+});
+
+test('TOOL-7: execute returns error string (not throw) on bad JSON args', () => {
+  const cwd = _ws({});
+  const out = execute('Read', '{not json', { cwd });
+  assert.match(out, /not valid JSON/);
+});
+
+test('TOOL-8: execute rejects a tool not in the allowed set', () => {
+  const cwd = _ws({});
+  const out = execute('Bash', { cmd: 'ls' }, { cwd }, ['Read', 'Glob']);
+  assert.match(out, /not available/);
+});
+
+test('TOOL-9: toolsetFor intersects declared tools; Bash is OPT-IN (off by default)', () => {
+  const ts = toolsetFor(['Read', 'Write', 'Bash', 'Grep', 'WebFetch']);
+  assert.deepEqual(ts.names, ['Read', 'Write', 'Grep']);
+  assert.equal(ts.schemas[0].function.name, 'Read');
+});
+
+test('TOOL-9b: readOnly mode excludes mutating tools and Bash', () => {
+  const ts = toolsetFor(['Read', 'Write', 'Edit', 'Bash', 'Grep'], { readOnly: true });
+  assert.deepEqual(ts.names, ['Read', 'Grep']);
+});
+
+test('TOOL-9c: allowBash:true is required to include Bash', () => {
+  assert.deepEqual(toolsetFor(['Read', 'Write', 'Edit', 'Bash']).names, ['Read', 'Write', 'Edit']);
+  assert.deepEqual(toolsetFor(['Read', 'Write', 'Edit', 'Bash'], { allowBash: true }).names, ['Read', 'Write', 'Edit', 'Bash']);
+});
+
+test('TOOL-10: toolset.execute enforces the agent allow-list', () => {
+  const cwd = _ws({ 'a.txt': 'hi' });
+  const ts = toolsetFor(['Read']);
+  assert.equal(ts.execute('Read', { path: 'a.txt' }, { cwd }), '1\thi');
+  assert.match(ts.execute('Grep', { pattern: 'x' }, { cwd }), /not available/);
+});
+
+test('TOOL-11: _globToRegex handles *, **, ?', () => {
+  assert.ok(_globToRegex('*.ts').test('a.ts'));
+  assert.ok(!_globToRegex('*.ts').test('src/a.ts'));
+  assert.ok(_globToRegex('src/**/*.ts').test('src/x/y/a.ts'));
+  assert.ok(_globToRegex('a?.js').test('ab.js'));
+});
+
+test('TOOL-12: READ_ONLY / MUTATING tool-name sets are the expected closed sets', () => {
+  assert.deepEqual(READ_ONLY_TOOL_NAMES, ['Read', 'Glob', 'Grep']);
+  assert.deepEqual(MUTATING_TOOL_NAMES, ['Write', 'Edit']);
+});
+
+test('TOOL-13: Write creates a file (and reports byte count)', () => {
+  const cwd = _ws({});
+  const out = execute('Write', { path: 'sub/new.txt', content: 'hello world' }, { cwd });
+  assert.match(out, /^wrote sub\/new\.txt \(11 bytes\)/);
+  assert.equal(fs.readFileSync(path.join(cwd, 'sub/new.txt'), 'utf-8'), 'hello world');
+});
+
+test('TOOL-14: Write outside cwd is refused', () => {
+  const cwd = _ws({});
+  const out = execute('Write', { path: '../escape.txt', content: 'x' }, { cwd });
+  assert.match(out, /^Error: safe-path-outside-base/);
+  assert.ok(!fs.existsSync(path.join(cwd, '../escape.txt')));
+});
+
+test('TOOL-15: Write surfaces a security finding without blocking the write', () => {
+  const cwd = _ws({});
+  const out = execute('Write', { path: 'danger.js', content: 'const x = eval(userInput)\n' }, { cwd });
+  assert.match(out, /\[security\] \d+ finding/);
+  assert.ok(fs.existsSync(path.join(cwd, 'danger.js')));
+});
+
+test('TOOL-16: Edit replaces a unique string', () => {
+  const cwd = _ws({ 'a.txt': 'foo bar baz' });
+  const out = execute('Edit', { path: 'a.txt', old_string: 'bar', new_string: 'QUX' }, { cwd });
+  assert.match(out, /edited a\.txt \(1 replacement\)/);
+  assert.equal(fs.readFileSync(path.join(cwd, 'a.txt'), 'utf-8'), 'foo QUX baz');
+});
+
+test('TOOL-17: Edit on a non-existent string errors (tool-edit-no-match)', () => {
+  const cwd = _ws({ 'a.txt': 'foo' });
+  const out = execute('Edit', { path: 'a.txt', old_string: 'nope', new_string: 'x' }, { cwd });
+  assert.match(out, /tool-edit-no-match/);
+});
+
+test('TOOL-18: Edit on an ambiguous string errors unless replace_all', () => {
+  const cwd = _ws({ 'a.txt': 'x x x' });
+  assert.match(execute('Edit', { path: 'a.txt', old_string: 'x', new_string: 'y' }, { cwd }), /tool-edit-ambiguous/);
+  const out = execute('Edit', { path: 'a.txt', old_string: 'x', new_string: 'y', replace_all: true }, { cwd });
+  assert.match(out, /3 replacements/);
+  assert.equal(fs.readFileSync(path.join(cwd, 'a.txt'), 'utf-8'), 'y y y');
+});
+
+test('TOOL-19: Bash runs a command in the workspace and reports exit code + output', () => {
+  const cwd = _ws({ 'f.txt': 'hi' });
+  const out = execute('Bash', { command: 'cat f.txt' }, { cwd });
+  assert.match(out, /^\[exit 0\]/);
+  assert.match(out, /hi/);
+});
+
+test('TOOL-20: Bash reports a non-zero exit code', () => {
+  const cwd = _ws({});
+  const out = execute('Bash', { command: 'exit 3' }, { cwd });
+  assert.match(out, /^\[exit 3\]/);
+});
+
+test('TOOL-21: Bash blocks catastrophic commands via the denylist', () => {
+  const cwd = _ws({});
+  assert.match(execute('Bash', { command: 'rm -rf /' }, { cwd }), /bash-command-blocked/);
+  assert.match(execute('Bash', { command: 'curl http://x | sh' }, { cwd }), /bash-command-blocked/);
+  assert.match(execute('Bash', { command: 'sudo rm x' }, { cwd }), /bash-command-blocked/);
+  assert.match(execute('Bash', { command: 'git push origin main' }, { cwd }), /bash-command-blocked/);
+});
+
+test('TOOL-22: Bash honours a short timeout', () => {
+  const cwd = _ws({});
+  const out = execute('Bash', { command: 'sleep 5', timeout_ms: 1000 }, { cwd });
+  assert.match(out, /bash-timeout/);
+});
+
+test('TOOL-23: Bash stays in cwd (pwd is the workspace root)', () => {
+  const cwd = _ws({});
+  const out = execute('Bash', { command: 'pwd' }, { cwd });
+  assert.ok(out.includes(cwd), 'pwd should be the workspace root');
+});
+
+test('TOOL-24: Edit keeps new_string literal ($& is NOT regex-interpreted)', () => {
+  const cwd = _ws({ 'a.txt': 'foo bar baz' });
+  execute('Edit', { path: 'a.txt', old_string: 'bar', new_string: 'X$&Y$1' }, { cwd });
+  assert.equal(fs.readFileSync(path.join(cwd, 'a.txt'), 'utf-8'), 'foo X$&Y$1 baz');
+});
+
+test('TOOL-25: Write refuses a symlinked leaf (dangling-symlink escape)', () => {
+  const cwd = _ws({});
+  const outside = path.join(cwd, '..', 'np-escape-target.txt');
+  try { fs.unlinkSync(outside); } catch {}
+  fs.symlinkSync(outside, path.join(cwd, 'evil'));
+  const out = execute('Write', { path: 'evil', content: 'pwned' }, { cwd });
+  assert.match(out, /tool-path-symlink/);
+  assert.ok(!fs.existsSync(outside), 'must not have written through the symlink');
+});
+
+test('TOOL-26: Edit refuses a symlinked leaf', () => {
+  const cwd = _ws({});
+  const outside = path.join(cwd, '..', 'np-escape-edit.txt');
+  fs.writeFileSync(outside, 'original', 'utf-8');
+  fs.symlinkSync(outside, path.join(cwd, 'evil'));
+  const out = execute('Edit', { path: 'evil', old_string: 'original', new_string: 'pwned' }, { cwd });
+  assert.match(out, /tool-path-symlink|safe-path-outside-base/);
+  assert.equal(fs.readFileSync(outside, 'utf-8'), 'original');
+  fs.unlinkSync(outside);
+});
+
+test('TOOL-27: Grep rejects a catastrophic (ReDoS) pattern', () => {
+  const cwd = _ws({ 'a.txt': 'x' });
+  const out = execute('Grep', { pattern: '(a+)+$' }, { cwd });
+  assert.match(out, /catastrophic|ReDoS|tool-bad-args/);
+});
+
+test('TOOL-28: withSearch injects knowledge-search even when undeclared', () => {
+  assert.ok(!toolsetFor(['Read', 'Write']).names.includes('knowledge-search'));
+  const ts = toolsetFor(['Read', 'Write'], { withSearch: true });
+  assert.ok(ts.names.includes('knowledge-search'));
+  assert.ok(ts.schemas.some((s) => s.function.name === 'knowledge-search'));
+});
+
+test('TOOL-29: knowledge-search records search evidence when a taskId is in ctx', () => {
+  const cwd = _ws({});
+  fs.mkdirSync(path.join(cwd, '.nubos-pilot'), { recursive: true });
+  const taskId = 'M001-S001-T0001';
+  const ts = toolsetFor(['Read'], { withSearch: true, ctx: { taskId } });
+  const out = ts.execute('knowledge-search', { query: 'authentication' }, { cwd });
+  assert.match(out, /knowledge-search:/);
+  const { searchEvidenceForRound } = require('../../nubosloop-audit.cjs');
+  assert.ok(searchEvidenceForRound(taskId, 1, cwd).length > 0, 'evidence must be recorded for the round');
+});

package/lib/security/review.cjs

@@ -149,7 +149,7 @@ function _stripFence(s) {
   return m ? m[1] : s;
 }
 
-function _defaultSpawn(promptText, opts) {
+async function _defaultSpawn(promptText, opts) {
   const spawnHeadless = require('../../bin/np-tools/spawn-headless.cjs');
   const tmp = os.tmpdir();
   const tag = process.pid + '-' + crypto.randomBytes(4).toString('hex');
@@ -158,7 +158,7 @@ function _defaultSpawn(promptText, opts) {
   fs.writeFileSync(promptPath, promptText, 'utf-8');
   const captured = [];
   try {
-    spawnHeadless.run(
+    await spawnHeadless.run(
       ['--agent', REVIEWER_AGENT, '--prompt-path', promptPath, '--output-path', outputPath,
         '--timeout-ms', String(opts.timeoutMs)],
       { cwd: opts.cwd, stdout: { write: (s) => captured.push(s) } },
@@ -170,7 +170,7 @@ function _defaultSpawn(promptText, opts) {
   }
 }
 
-function runReview(opts) {
+async function runReview(opts) {
   const o = opts || {};
   const cwd = o.cwd || process.cwd();
   const sid = o.sid;
@@ -198,7 +198,7 @@ function runReview(opts) {
       diffText: diff.diffText, guidancePath: config.guidance_path,
     });
 
-    const raw = spawn(promptText, { cwd, timeoutMs: config.review_timeout_ms || 180000 });
+    const raw = await spawn(promptText, { cwd, timeoutMs: config.review_timeout_ms || 180000 });
     const parsed = parseReviewerOutput(raw);
     const risks = parsed.findings.filter((f) => f.severity === 'risk');
     const merged = ledger.addReviewFindings(sid, risks, mode);

package/lib/security/review.test.cjs

@@ -100,7 +100,7 @@ test('REV-5 parseReviewerOutput handles claude -p envelope, fences, and junk', (
   assert.equal(junk.parse_ok, false);
 });
 
-test('REV-6 runReview guard blocks a concurrent review (no double spawn)', () => {
+test('REV-6 runReview guard blocks a concurrent review (no double spawn)', async () => {
   const dir = tempRepo();
   const sid = freshSid();
   try {
@@ -108,21 +108,21 @@ test('REV-6 runReview guard blocks a concurrent review (no double spawn)', () =>
     fs.appendFileSync(path.join(dir, 'app.js'), 'const z = eval(q);\n');
     ledger.tryBeginReview(sid, {});  // simulate an in-flight review
     let spawnCalls = 0;
-    const r = review.runReview({ cwd: dir, sid, mode: 'stop', config: {}, spawnImpl: () => { spawnCalls++; return '{}'; } });
+    const r = await review.runReview({ cwd: dir, sid, mode: 'stop', config: {}, spawnImpl: () => { spawnCalls++; return '{}'; } });
     assert.equal(r.ran, false);
     assert.equal(r.reason, 'in-flight');
     assert.equal(spawnCalls, 0);
   } finally { ledger.endReview(sid); cleanup(sid); fs.rmSync(dir, { recursive: true, force: true }); }
 });
 
-test('REV-7 runReview spawns, parses, and merges risk findings into the ledger', () => {
+test('REV-7 runReview spawns, parses, and merges risk findings into the ledger', async () => {
   const dir = tempRepo();
   const sid = freshSid();
   try {
     ledger.setBaseline(sid, { head: headOf(dir) });
     fs.appendFileSync(path.join(dir, 'app.js'), 'const z = eval(q);\n');
     const stub = () => JSON.stringify({ result: '{"status":"risks-found","findings":[{"category":"dynamic-exec","severity":"high","file":"app.js","line":2,"title":"eval"}]}' });
-    const r = review.runReview({ cwd: dir, sid, mode: 'stop', config: {}, spawnImpl: stub });
+    const r = await review.runReview({ cwd: dir, sid, mode: 'stop', config: {}, spawnImpl: stub });
     assert.equal(r.ran, true);
     assert.equal(r.findings_added, 1);
     const taken = ledger.takeUnsurfacedRisks(sid, {});
@@ -130,13 +130,13 @@ test('REV-7 runReview spawns, parses, and merges risk findings into the ledger',
   } finally { cleanup(sid); fs.rmSync(dir, { recursive: true, force: true }); }
 });
 
-test('REV-8 runReview on an empty diff does not spawn', () => {
+test('REV-8 runReview on an empty diff does not spawn', async () => {
   const dir = tempRepo();
   const sid = freshSid();
   try {
     ledger.setBaseline(sid, { head: headOf(dir) });
     let spawnCalls = 0;
-    const r = review.runReview({ cwd: dir, sid, mode: 'stop', config: {}, spawnImpl: () => { spawnCalls++; return '{}'; } });
+    const r = await review.runReview({ cwd: dir, sid, mode: 'stop', config: {}, spawnImpl: () => { spawnCalls++; return '{}'; } });
     assert.equal(r.findings_added, 0);
     assert.equal(spawnCalls, 0);
   } finally { cleanup(sid); fs.rmSync(dir, { recursive: true, force: true }); }

package/np-tools.cjs

@@ -108,6 +108,7 @@ const topLevelCommands = {
   'loop-stuck':          require('./bin/np-tools/loop-stuck.cjs'),
   'loop-metrics':       require('./bin/np-tools/loop-metrics.cjs'),
   'spawn-headless':     require('./bin/np-tools/spawn-headless.cjs'),
+  'spawn-offhost':      require('./bin/np-tools/spawn-offhost.cjs'),
   'security':           require('./bin/np-tools/security.cjs'),
   'learning-log':      require('./bin/np-tools/learning-log.cjs'),
   'learning-match':    require('./bin/np-tools/learning-match.cjs'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nubos-pilot",
-  "version": "1.2.3",
+  "version": "1.3.0",
   "description": "Self-hosted AI pilot for any codebase. Researcher and critic agents plan, execute and verify each change.",
   "homepage": "https://pilot.nubos.cloud",
   "repository": {

package/templates/claude/payload/hooks/np-learnings-hook.cjs

@@ -37,6 +37,7 @@ function readStdin() {
 }
 
 (async () => {
+  if (process.env.NUBOS_PILOT_HEADLESS === '1') { process.exit(0); return; }
   const verb = process.argv[2];
   if (!ALLOWED_VERBS.has(verb)) { process.exit(0); return; }
   const npTools = resolveNpTools();

package/templates/claude/payload/hooks/np-security-hook.cjs

@@ -31,6 +31,7 @@ function readStdin() {
 }
 
 (async () => {
+  if (process.env.NUBOS_PILOT_HEADLESS === '1') { process.exit(0); return; }
   const verb = process.argv[2];
   if (!ALLOWED_VERBS.has(verb)) { process.exit(0); return; }
   const npTools = resolveNpTools();

package/workflows/add-tests.md

@@ -47,6 +47,47 @@ Once the UAT file is emitted and the smoke-run is green, the orchestrator spawns
 - No `test.skip(...)` without a corresponding Fail / Defer marker.
 - No vacuous assertions.
 
+Off-host dispatch (ADR-0021): if `np-critic` routes to an `openai-compat` provider, run the single review read-only via `spawn-offhost` instead of a native Agent spawn. The off-host critic CANNOT write to `$TMPDIR` (off-host Write is cwd-confined), so it emits the findings object `{ "critic":"critic", "findings":[…] }` as its FINAL MESSAGE; the orchestrator writes that to the critic-report path only after asserting the `critic` axis ∈ {critic,style,tests,acceptance} — any other value is silently dropped by `mergeCriticOutputs` (project_np_critic_field_schema_bug), so fail loud instead.
+
+```bash
+LANG_DIRECTIVE=$(node .nubos-pilot/bin/np-tools.cjs lang-directive)
+mkdir -p "${TMPDIR:-/tmp}/nubos-pilot/critic-reports"
+CRITIC_REPORT_PATH="${TMPDIR:-/tmp}/nubos-pilot/critic-reports/critic-addtests-${PHASE}.json"
+UAT_FILE=$(echo "$INIT" | node -e "process.stdin.on('data', d => console.log(JSON.parse(d).target_path))")
+VERIFICATION_FILE=$(echo "$INIT" | node -e "process.stdin.on('data', d => console.log(JSON.parse(d).verification_path))")
+CRITIC_KIND=$(node .nubos-pilot/bin/np-tools.cjs resolve-model np-critic --json 2>/dev/null \
+  | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{try{console.log(JSON.parse(s).kind||"native")}catch{console.log("native")}})')
+if [ "$CRITIC_KIND" = "openai-compat" ]; then
+  # Render the tests-axis-weighted critic prompt (UAT file + VERIFICATION.md as
+  # files_to_read) PLUS the emit-as-final-message instruction PLUS $LANG_DIRECTIVE
+  # into a TMPDIR file, then spawn read-only.
+  ADDTESTS_CRITIC_PROMPT="${TMPDIR:-/tmp}/np-offhost-addtests-critic-${PHASE}.md"
+  cat > "$ADDTESTS_CRITIC_PROMPT" <<EOF
+You are np-critic reviewing a UAT regression suite (tests-axis weighted).
+
+files_to_read:
+- ${UAT_FILE}
+- ${VERIFICATION_FILE}
+
+Verify, weighting the tests-axis (verify-mismatch, missing-test, weak-assertion, silenced-failure):
+- Every Pass-case in VERIFICATION.md has a corresponding test in the UAT file.
+- Every test name describes observable behaviour.
+- No test.skip(...) without a corresponding Fail / Defer marker.
+- No vacuous assertions.
+
+Emit ONLY the findings JSON object { "critic":"critic", "findings":[…] } as your final message.
+
+${LANG_DIRECTIVE}
+EOF
+  OFFHOST_CRITIC_OUT=$(node .nubos-pilot/bin/np-tools.cjs spawn-offhost \
+    --agent np-critic --task-file "$ADDTESTS_CRITIC_PROMPT" --read-only)
+  echo "$OFFHOST_CRITIC_OUT" | CRITIC_REPORT_PATH="$CRITIC_REPORT_PATH" node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{let env,f;try{env=JSON.parse(s);f=JSON.parse(env.content)}catch{console.error("off-host critic: final message is not the findings JSON object");process.exit(1)}var SUP=["critic","style","tests","acceptance"];if(!f||typeof f!=="object"||SUP.indexOf(f.critic)<0){console.error("off-host critic: `critic` must be one of "+SUP.join("/")+" — any other value is silently dropped by mergeCriticOutputs (project_np_critic_field_schema_bug)");process.exit(1)}require("fs").writeFileSync(process.env.CRITIC_REPORT_PATH,JSON.stringify(f))})' || exit 1
+else
+  # → native Agent spawn of np-critic writes $CRITIC_REPORT_PATH (the existing path).
+  true
+fi
+```
+
 Findings of category `missing-test`, `weak-assertion`, `silenced-failure`, or `verify-mismatch` route per `lib/nubosloop.cjs::routeFindings`. A single Build-Fixer-style round on `init add-tests` closes the loop. Beyond one round the workflow exits non-zero and the user resolves manually.
 
 This is intentionally a one-pass adversarial review (not the full Critic-Schwarm) — the UAT-emitter is mechanical and only one axis (test quality) needs adversarial coverage.

package/workflows/architect-phase.md

@@ -70,10 +70,14 @@ When the user invokes `/np:architect-phase <N> --research` (or when `swarm.resea
 
 The architect then consumes the consensus-merged `RESEARCH.md` instead of a single-spawn output. ADR-0011 details the merge rules and the `<consensus_meta>` audit block.
 
+**Off-host (ADR-0021):** the Schwarm reuses the exact off-host `np-researcher` mechanism documented in `/np:research-phase` — detect `resolve-model np-researcher --kind`; when `openai-compat`, run the `k` spawns via `spawn-offhost --agent np-researcher --task-id "${MILESTONE_ID}-S000-T0000" --no-audit` (synthetic milestone-level canonical task-id for the Rule-9 ledger) and stamp one `loop-audit-tool-use` per spawn. **Offline only** — the off-host toolset has no `WebFetch`/`context7`, so route `np-researcher` native for online research.
+
 ## Adversarial Loop (1 round)
 
 After the architect emits `M<NNN>-ARCHITECTURE.md`, the orchestrator spawns ONE `np-critic` instance with the architecture file + `M<NNN>-CONTEXT.md` as inputs. The critic verifies that every locked decision in CONTEXT has a corresponding architecture entry and that no `Deferred` items leaked into the architecture. Findings of category `unmet-criterion`, `locked-decision-violation`, or `information-missing` route per `lib/nubosloop.cjs::routeFindings`. A single Build-Fixer-style round on the architect closes the loop. Beyond one round the workflow exits with `stuck` and the user resolves manually — architecture decisions don't merit unbounded looping.
 
+**Off-host (ADR-0021):** when `np-critic` routes to an `openai-compat` provider (`resolve-model np-critic --kind`), run it `--read-only` via `spawn-offhost --agent np-critic` exactly as the `/np:execute-phase` off-host critic — the critic emits its `{ "critic":"critic", "findings":[…] }` object as the final message (off-host Write is cwd-confined, cannot reach `$TMPDIR`), and the orchestrator persists it only after asserting `critic ∈ {critic,style,tests,acceptance}` (else fail loud — `project_np_critic_field_schema_bug`).
+
 ## Skills (Nubos library)
 
 Nubos ships a design-time skill library under `.claude/skills/np-*/` (present only on Claude Code). These are the **quality bar for the architecture decisions you are about to commit** — each skill's "Verification bar" is the standard each ADR-style decision is held to. Before spawning `np-architect`, classify the milestone (read `M<NNN>-CONTEXT.md` + `M<NNN>-RESEARCH.md`) and inject the matching skill triggers into the architect's spawn prompt. Skills **stack** — include every row the milestone matches (cap at the most relevant ~4 if more match; always keep the security row when it applies).
@@ -113,6 +117,21 @@ If zero skills match, omit the skill-directive line — do not invent skills.
 Der Agent ist read-only auf Source — er schreibt EINE Datei:
 `.nubos-pilot/milestones/M<NNN>/M<NNN>-ARCHITECTURE.md`.
 
+**Off-host (ADR-0021):** when `np-architect` routes to an `openai-compat` provider, run it via `spawn-offhost` instead of the host spawn. `np-architect` is NOT Rule-9-audited and writes only the one `M<NNN>-ARCHITECTURE.md` artefact under `.nubos-pilot/` (inside the repo cwd — never live code), so it runs off-host with the default cwd (Read/Grep/Glob over the repo + Write confined to cwd), **no `--allow-bash`, no worktree**. It writes the file exactly as the native architect; no emit-and-persist contract is needed.
+
+```bash
+ARCHITECT_KIND=$(node .nubos-pilot/bin/np-tools.cjs resolve-model np-architect --json 2>/dev/null \
+  | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{try{console.log(JSON.parse(s).kind||"native")}catch{console.log("native")}})')
+if [ "$ARCHITECT_KIND" = "openai-compat" ]; then
+  ARCHITECT_PROMPT="${TMPDIR:-/tmp}/np-offhost-architect-M<NNN>.md"
+  # … render the SAME files_to_read block + Milestone/Task + (matched) skill
+  #   directive above, PLUS $LANG_DIRECTIVE, into "$ARCHITECT_PROMPT" …
+  node .nubos-pilot/bin/np-tools.cjs spawn-offhost \
+    --agent np-architect --task-file "$ARCHITECT_PROMPT" --phase "M<NNN>" >/dev/null
+fi
+# else → native host spawn per the block above.
+```
+
 ## Post
 
 Wenn der Agent `## CONTEXT CONFLICT` emittiert statt der Datei:

package/workflows/discuss-phase.md

@@ -372,6 +372,7 @@ CONTEXT.md now captures the decisions. Success Criteria in `roadmap.yaml` are st
 ```bash
 SC_START=$(node .nubos-pilot/bin/np-tools.cjs metrics start-timestamp)
 SC_MODEL=$(node .nubos-pilot/bin/np-tools.cjs resolve-model np-sc-extractor --profile balanced)
+SC_KIND=$(node .nubos-pilot/bin/np-tools.cjs resolve-model np-sc-extractor --kind 2>/dev/null || echo native)
 
 REQS_PATH=".nubos-pilot/REQUIREMENTS.md"
 
@@ -393,17 +394,35 @@ EXISTING_SC_JSON=$(node .nubos-pilot/bin/np-tools.cjs phase-meta "$PHASE" --fiel
 # call `node .nubos-pilot/bin/np-tools.cjs update-phase-meta $PHASE --stdin`
 # with {"success_criteria": [{id:"SC-N", text:"..."}, ...]} on its stdin,
 # and print a one-line summary.
-# Guard: the SC_COUNT check below (lines 399-403) hard-aborts if the spawn
-# returns zero criteria.
+# Guard: the SC_COUNT check below hard-aborts if the spawn returns zero criteria.
+# Off-host (ADR-0021): when np-sc-extractor routes to an openai-compat provider,
+# run it via spawn-offhost (below) INSTEAD of the Agent tool.
 # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-SC_END=$(node .nubos-pilot/bin/np-tools.cjs metrics end-timestamp)
-node .nubos-pilot/bin/np-tools.cjs metrics record \
-  --agent np-sc-extractor --tier haiku --resolved-model "$SC_MODEL" \
-  --phase "$PHASE" --plan "${MILESTONE_ID}-sc" --task "${MILESTONE_ID}-sc-extract" \
-  --started "$SC_START" --ended "$SC_END" \
-  --tokens-in "${TOKENS_IN:-0}" --tokens-out "${TOKENS_OUT:-0}" \
-  --retry-count 0 --status ok --runtime "$RUNTIME"
+if [ "$SC_KIND" = "openai-compat" ]; then
+  # np-sc-extractor is NOT Rule-9-audited and writes ONLY roadmap.yaml under
+  # .nubos-pilot/ (inside the repo cwd — NOT live code), so it runs off-host
+  # with the default cwd (repo root): Read/Grep/Glob over the repo + Write
+  # confined to cwd. NO --allow-bash, NO worktree (no live-code blast radius
+  # to isolate). It persists success_criteria into roadmap.yaml exactly as the
+  # native extractor does — no emit-and-persist contract needed.
+  # spawn-offhost records the metrics row itself.
+  SC_PROMPT="${TMPDIR:-/tmp}/np-offhost-sc-extractor-${MILESTONE_ID}.md"
+  # … render the SAME prompt the ACTION CONTRACT above describes (milestone,
+  #   milestone_id, milestone_dir, context_path, requirements_path,
+  #   existing_success_criteria) PLUS $LANG_DIRECTIVE into "$SC_PROMPT" …
+  node .nubos-pilot/bin/np-tools.cjs spawn-offhost \
+    --agent np-sc-extractor --task-file "$SC_PROMPT" \
+    --phase "$PHASE" >/dev/null
+else
+  # → execute the Agent call per ACTION CONTRACT above (native host spawn), then:
+  SC_END=$(node .nubos-pilot/bin/np-tools.cjs metrics end-timestamp)
+  node .nubos-pilot/bin/np-tools.cjs metrics record \
+    --agent np-sc-extractor --tier haiku --resolved-model "$SC_MODEL" \
+    --phase "$PHASE" --plan "${MILESTONE_ID}-sc" --task "${MILESTONE_ID}-sc-extract" \
+    --started "$SC_START" --ended "$SC_END" \
+    --tokens-in "${TOKENS_IN:-0}" --tokens-out "${TOKENS_OUT:-0}" \
+    --retry-count 0 --status ok --runtime "$RUNTIME"
+fi
 ```
 
 After the spawn, sanity-check that `success_criteria` is non-empty:

package/workflows/execute-phase.md

@@ -168,7 +168,7 @@ Every task runs through the **Nubosloop** (ADR-0010, `lib/nubosloop.cjs`) — pr
 
 1. **Pre-flight cache lookup** (Round 1 only) — `loop-run-round --phase preflight --query "$TASK_QUERY"`. A hit at similarity ≥ `swarm.research.threshold` and `occurrence ≥ swarm.research.minOccurrence` short-circuits the Researcher-Schwarm; the cached pattern enters the Executor prompt with provenance `[CACHED]`. Soft cache failures (adapter-unknown) downgrade to a miss with `cache_miss_reason` populated; hard failures (corrupt store, version mismatch) propagate.
 2. **Researcher-Schwarm (on cache miss, or on `next_action=researcher` re-route)** — orchestrator spawns `swarm.research.k=3` independent `np-researcher` agents IN PARALLEL (single message, three Agent blocks) and merges their outputs through `lib/researcher-swarm.cjs::mergeConsensus` (Mehrheit / Union / Schnittmenge). The merged consensus enters the Executor prompt with provenance.
-3. **Executor (R1) or Build-Fixer (R≥2)** — single LLM spawn. Round 1 spawns `agents/np-executor.md`. Round ≥ 2 spawns `agents/np-build-fixer.md` with prior critic findings + verify output appended. Edits ONLY paths in `files_modified` (D-04 — no scope expansion). Does NOT call `commit-task`.
+3. **Executor (R1) or Build-Fixer (R≥2)** — single LLM spawn. Round 1 spawns `agents/np-executor.md`. Round ≥ 2 spawns `agents/np-build-fixer.md` with prior critic findings + verify output appended. Edits ONLY paths in `files_modified` (D-04 — no scope expansion). Does NOT call `commit-task`. **Off-host (ADR-0021):** when the executor agent routes to an `openai-compat` provider (`agent_routing`), the spawn runs through `spawn-offhost` inside a forced slice worktree instead of the host Agent tool — see the off-host branch in the spawn block below. It satisfies Rule 9 via an injected native `knowledge-search` tool, and the orchestrator runs the same Step-4 audit stamp.
 4. **Mechanical Checks (orchestrator, NOT the agent)** — run task's `<verify>` command + stack linters (`phpstan`, `pint`, `tsc`, `eslint`); capture exit code + output to `$VERIFY_LOG`. Then `loop-audit-tool-use "$TASK_ID" --agent "$EXECUTOR_AGENT" --tool-use-log <json>` confirms the spawn invoked a knowledge-search tool ≥ 1× (Rule 9). The audited agent satisfies Rule 9 by running `node np-tools.cjs knowledge-search "<query>" --task "$TASK_ID"` via Bash, then stamping the exact string `knowledge-search` in `--tool-use-log`. The full accepted set is the `SEARCH_TOOLS` constant in `lib/nubosloop.cjs`; that constant is the single source of truth — do not re-enumerate it here. Audit findings get round-stamped and feed `loop-evaluate` alongside critic findings. Then call `loop-run-round --phase post-executor --verify-exit-code "$VERIFY_EXIT" --verify-output-path "$VERIFY_LOG"`. On verify-red the verb returns `next_action: spawn-build-fixer` — skip critics, advance to next round directly.
 5. **Critic (verify-green only)** — one Critic agent spawns: `agents/np-critic.md` (sonnet). It writes the full findings JSON to `$CRITIC_REPORT_PATH` and emits a small verdict envelope as its final message (ADR-0010 §L5 Verdict-Only Contract, 2026-05-05). Single-critic revision per §Trust Layer 2026-05-05 — the prior 3-critic schwarm collapsed because three parallel spawns added latency without proportional finding-quality gains; the Verdict-Only Contract on top reduces per-round main-context tokens by an order of magnitude (verbatim findings reports were the dominant Nubosloop cost-driver).
 6. **Route** — `loop-run-round --phase post-critics --critic-outputs-path "$CRITIC_REPORT_PATH"` (or legacy `--critic-outputs "$CRITIC_JSON"` when the Verdict-Only Contract is unavailable) returns `next_action ∈ {commit, executor, researcher, askuser, plan-checker, stuck}`:
@@ -359,7 +359,40 @@ for WAVE_INDEX in 0 1 2 ...; do
       if { [ "$ROUND" -eq 1 ] && [ "$CACHE_HIT" != "true" ]; } || [ "$NEXT_ACTION" = "researcher" ]; then
         SPAWN_SPECS=$(echo "$PREFLIGHT" | node -e \
           'process.stdin.on("data",d=>{const j=JSON.parse(d);process.stdout.write(JSON.stringify((j.swarm&&j.swarm.spawn_specs)||[]))})')
-        # → execute groups (1) + (2) per ACTION CONTRACT above, then:
+        # Off-host researcher swarm (ADR-0021): if np-researcher routes to an
+        # openai-compat provider, run $SWARM_K read-only spawns via spawn-offhost.
+        # np-researcher is Rule-9-audited → --task-id injects knowledge-search;
+        # read-only ⇒ no worktree needed. Each spawn MUST emit the per-spawn
+        # consensus JSON { decisions[], risks[], patterns[], open_questions[],
+        # sources[] } that researcher-merge consumes (NOT the researcher-output
+        # markdown artifact — that schema is for M<NNN>-RESEARCH.md, a different
+        # contract). A spawn whose output is not that JSON is substituted with an
+        # empty {} so researcher-merge degrades gracefully instead of aborting the
+        # wave (exit 4). --no-audit defers the Rule-9 stamp to the orchestrator's
+        # group-(2) loop-audit-tool-use (one per spawn) so the post-researcher
+        # SKIP-GUARD is satisfied exactly as for native spawns.
+        RESEARCHER_KIND=$(node .nubos-pilot/bin/np-tools.cjs resolve-model np-researcher --json 2>/dev/null \
+          | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{try{console.log(JSON.parse(s).kind||"native")}catch{console.log("native")}})')
+        if [ "$RESEARCHER_KIND" = "openai-compat" ]; then
+          SWARM_K=$(echo "$PREFLIGHT" | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const j=JSON.parse(s);console.log((j.swarm&&j.swarm.k)||3)})')
+          SPAWN_OUT_PATHS=()
+          i=0
+          while [ "$i" -lt "$SWARM_K" ]; do
+            OUT_PATH="${TMPDIR:-/tmp}/np-spawn-${TASK_ID}-r${ROUND}-${i}.json"
+            R_PROMPT="${TMPDIR:-/tmp}/np-offhost-researcher-${TASK_ID}-r${ROUND}-${i}.md"
+            # … render researcher prompt i (task_query verbatim + seed_delta[i] + files_to_read) …
+            R_OUT=$(node .nubos-pilot/bin/np-tools.cjs spawn-offhost \
+              --agent np-researcher --task-file "$R_PROMPT" --task-id "$TASK_ID" \
+              --read-only --no-audit ${SLICE_CWD:+--cwd "$SLICE_CWD"})
+            echo "$R_OUT" | OUT_PATH="$OUT_PATH" node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{let c="";try{c=JSON.parse(s).content||""}catch{}var ok=false;try{JSON.parse(c);ok=true}catch{}if(!ok){process.stderr.write("off-host researcher: spawn output is not the {decisions,risks,patterns,open_questions,sources} JSON researcher-merge expects — substituting empty consensus for this spawn\n");c="{}"}require("fs").writeFileSync(process.env.OUT_PATH,c)})'
+            R_LOG=$(echo "$R_OUT" | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{try{console.log(JSON.stringify((JSON.parse(s).toolLog||[]).map(t=>t.name)))}catch{console.log("[]")}})')
+            node .nubos-pilot/bin/np-tools.cjs loop-audit-tool-use "$TASK_ID" --agent np-researcher --tool-use-log "$R_LOG"
+            SPAWN_OUT_PATHS+=("$OUT_PATH")
+            i=$((i+1))
+          done
+        else
+          true  # → execute groups (1) + (2) per ACTION CONTRACT above (native Agent spawns).
+        fi
         CONSENSUS_PATTERN=$(node .nubos-pilot/bin/researcher-merge.cjs \
           "${SPAWN_OUT_PATHS[@]}")
         node .nubos-pilot/bin/np-tools.cjs loop-run-round "$TASK_ID" --phase post-researcher
@@ -420,7 +453,43 @@ for WAVE_INDEX in 0 1 2 ...; do
       else
         EXECUTOR_MODEL=$(node .nubos-pilot/bin/np-tools.cjs resolve-model "$EXECUTOR_AGENT" --profile frontier)
       fi
-      # → execute group (1) per ACTION CONTRACT above, then:
+
+      # ━━━ Off-host executor (ADR-0021) — config-driven via agent_routing ━━━
+      # If $EXECUTOR_AGENT routes to an openai-compat provider, run it through
+      # the nubos-pilot dispatch loop (spawn-offhost) instead of the host Agent
+      # tool. Off-host REQUIRES worktree isolation: the existing per-wave worktree
+      # (created at §Worktree-Isolation above) confines model-driven Write/Edit/
+      # Bash, and the slice-end ff-merge is what lands the work on the parent
+      # branch. The worktree lives under .nubos-pilot/worktrees/, so checkpoint /
+      # search-evidence / metrics still resolve to the project root — only file
+      # ops are confined. We do NOT force a worktree out of band: doing so would
+      # bypass the merge-back gate (commits stranded) and the orchestrator's
+      # cwd=worktree convention (commit-task would find nothing). The orchestrator
+      # runs the canonical Step-4 loop-audit-tool-use with the returned tool-log,
+      # so spawn-offhost is called --no-audit to avoid double-stamping the round.
+      EXECUTOR_KIND=$(node .nubos-pilot/bin/np-tools.cjs resolve-model "$EXECUTOR_AGENT" --json 2>/dev/null \
+        | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{try{console.log(JSON.parse(s).kind||"native")}catch{console.log("native")}})')
+      if [ "$EXECUTOR_KIND" = "openai-compat" ]; then
+        if [ "$WORKTREE_ISOLATION" != "true" ] || [ -z "$SLICE_CWD" ] || [ "$SLICE_CWD" = "." ]; then
+          echo "[np:execute-phase] off-host executor ($EXECUTOR_AGENT) requires workflow.worktree_isolation=true so model-driven edits are confined and ff-merged back. Enable it (config-set workflow.worktree_isolation true) and re-run." >&2
+          exit 1
+        fi
+        # Write the SAME rendered executor prompt you would have handed the Agent
+        # tool (task plan + slice context + consensus + success criteria +
+        # language directive + skill block) to this file:
+        OFFHOST_PROMPT="${TMPDIR:-/tmp}/np-offhost-${TASK_ID}-r${ROUND}.md"
+        # … render prompt to "$OFFHOST_PROMPT" …
+        OFFHOST_OUT=$(node .nubos-pilot/bin/np-tools.cjs spawn-offhost \
+          --agent "$EXECUTOR_AGENT" --task-file "$OFFHOST_PROMPT" \
+          --task-id "$TASK_ID" --cwd "$SLICE_CWD" --allow-bash --no-audit)
+        # Harvest the tool-name log for the Layer-C audit stamp (Step 4).
+        EXECUTOR_TOOL_LOG=$(echo "$OFFHOST_OUT" | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{try{console.log(JSON.stringify((JSON.parse(s).toolLog||[]).map(t=>t.name)))}catch{console.log("[]")}})')
+      else
+        # → execute group (1) per ACTION CONTRACT above (native host Agent spawn);
+        # EXECUTOR_TOOL_LOG is harvested from the spawn's tool_use stream.
+        true
+      fi
+      # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
       node .nubos-pilot/bin/np-tools.cjs checkpoint transition "$TASK_ID" verifying
 
@@ -510,7 +579,27 @@ for WAVE_INDEX in 0 1 2 ...; do
       # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
       mkdir -p "${TMPDIR:-/tmp}/nubos-pilot/critic-reports"
       CRITIC_REPORT_PATH="${TMPDIR:-/tmp}/nubos-pilot/critic-reports/critic-${TASK_ID}-r${ROUND}.json"
-      # → execute group (2) per ACTION CONTRACT above, then:
+      # Off-host critic (ADR-0021): if np-critic routes to an openai-compat
+      # provider, run it read-only via spawn-offhost. It CANNOT write to $TMPDIR
+      # (off-host Write is cwd-confined), so it emits the findings object
+      # { "critic":"critic", "findings":[…], "criteria"?:[…] } as its FINAL
+      # MESSAGE; the orchestrator writes that to $CRITIC_REPORT_PATH only after
+      # asserting the `critic` axis ∈ {critic,style,tests,acceptance} — any other
+      # value is silently dropped by mergeCriticOutputs
+      # (project_np_critic_field_schema_bug), so fail loud instead.
+      CRITIC_KIND=$(node .nubos-pilot/bin/np-tools.cjs resolve-model np-critic --json 2>/dev/null \
+        | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{try{console.log(JSON.parse(s).kind||"native")}catch{console.log("native")}})')
+      if [ "$CRITIC_KIND" = "openai-compat" ]; then
+        OFFHOST_CRITIC_PROMPT="${TMPDIR:-/tmp}/np-offhost-critic-${TASK_ID}-r${ROUND}.md"
+        # … render the critic prompt (same files_to_read as group (2)) PLUS:
+        #   "Emit ONLY the findings JSON object as your final message." …
+        OFFHOST_CRITIC_OUT=$(node .nubos-pilot/bin/np-tools.cjs spawn-offhost \
+          --agent np-critic --task-file "$OFFHOST_CRITIC_PROMPT" --read-only ${SLICE_CWD:+--cwd "$SLICE_CWD"})
+        echo "$OFFHOST_CRITIC_OUT" | CRITIC_REPORT_PATH="$CRITIC_REPORT_PATH" node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{let env,f;try{env=JSON.parse(s);f=JSON.parse(env.content)}catch{console.error("off-host critic: final message is not the findings JSON object");process.exit(1)}var SUP=["critic","style","tests","acceptance"];if(!f||typeof f!=="object"||SUP.indexOf(f.critic)<0){console.error("off-host critic: `critic` must be one of "+SUP.join("/")+" — any other value is silently dropped by mergeCriticOutputs (project_np_critic_field_schema_bug)");process.exit(1)}require("fs").writeFileSync(process.env.CRITIC_REPORT_PATH,JSON.stringify(f))})' || exit 1
+      else
+        # → execute group (2) per ACTION CONTRACT above (native Agent spawn writes $CRITIC_REPORT_PATH).
+        true
+      fi
       node .nubos-pilot/bin/np-tools.cjs loop-audit-tool-use "$TASK_ID" --agent np-critic --tool-use-log '[]'
       POST_CRIT=$(node .nubos-pilot/bin/np-tools.cjs loop-run-round "$TASK_ID" \
         --phase post-critics --critic-outputs-path "$CRITIC_REPORT_PATH")