nubos-pilot 1.2.4 → 1.3.1

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")

package/workflows/plan-phase.md

@@ -241,17 +241,38 @@ for ITER in 1 2; do
   #   <prior_findings>$LAST_FINDINGS</prior_findings>  (path to verdict JSON, R≥2)
   #   <agent_skills>$AGENT_SKILLS_PLANNER</agent_skills>
   # Agent MUST: write/update slice plans inside $milestone_dir.
+  # Off-host (ADR-0021): when np-planner routes to an openai-compat provider
+  # (agent_routing), run it via spawn-offhost (below) INSTEAD of the Agent tool.
   # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   PLANNER_START=$(node .nubos-pilot/bin/np-tools.cjs metrics start-timestamp)
   PLANNER_MODEL=$(node .nubos-pilot/bin/np-tools.cjs resolve-model np-planner --profile frontier)
-  # → execute the Agent call per ACTION CONTRACT above, then:
-  PLANNER_END=$(node .nubos-pilot/bin/np-tools.cjs metrics end-timestamp)
-  node .nubos-pilot/bin/np-tools.cjs metrics record \
-    --agent np-planner --tier opus --resolved-model "$PLANNER_MODEL" \
-    --phase "$PHASE" --plan "${milestone_id}-plan" --task "${milestone_id}-planner-run" \
-    --started "$PLANNER_START" --ended "$PLANNER_END" \
-    --tokens-in "${TOKENS_IN:-0}" --tokens-out "${TOKENS_OUT:-0}" \
-    --retry-count 0 --status ok --runtime "$RUNTIME"
+  PLANNER_KIND=$(node .nubos-pilot/bin/np-tools.cjs resolve-model np-planner --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 [ "$PLANNER_KIND" = "openai-compat" ]; then
+    # np-planner is NOT Rule-9-audited and writes ONLY planning artefacts 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 whole repo + Write
+    # confined to cwd. NO --allow-bash and NO worktree (there is no live-code
+    # blast radius to isolate, unlike the executor). It writes slice plans into
+    # $milestone_dir exactly as the native planner does — no emit-and-persist
+    # contract needed. spawn-offhost records the metrics row itself.
+    PLANNER_PROMPT="${TMPDIR:-/tmp}/np-offhost-planner-${milestone_id}-i${ITER}.md"
+    # … render the SAME prompt the ACTION CONTRACT above describes (mode,
+    #   milestone, milestone_dir, goal, requirements, prior_findings,
+    #   agent_skills) PLUS $LANG_DIRECTIVE into "$PLANNER_PROMPT" …
+    node .nubos-pilot/bin/np-tools.cjs spawn-offhost \
+      --agent np-planner --task-file "$PLANNER_PROMPT" \
+      --phase "$PHASE" --plan "${milestone_id}-plan" >/dev/null
+  else
+    # → execute the Agent call per ACTION CONTRACT above (native host spawn), then:
+    PLANNER_END=$(node .nubos-pilot/bin/np-tools.cjs metrics end-timestamp)
+    node .nubos-pilot/bin/np-tools.cjs metrics record \
+      --agent np-planner --tier opus --resolved-model "$PLANNER_MODEL" \
+      --phase "$PHASE" --plan "${milestone_id}-plan" --task "${milestone_id}-planner-run" \
+      --started "$PLANNER_START" --ended "$PLANNER_END" \
+      --tokens-in "${TOKENS_IN:-0}" --tokens-out "${TOKENS_OUT:-0}" \
+      --retry-count 0 --status ok --runtime "$RUNTIME"
+  fi
 
   # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   # ACTION CONTRACT — Step 2b: Spawn np-plan-checker (immediately after 2a)
@@ -265,17 +286,37 @@ for ITER in 1 2; do
   # Agent MUST: read planner output (slice plans inside $milestone_dir),
   # write YAML verdict to $milestone_dir/.tmp-verdict-$ITER.yaml. Orchestrator
   # converts YAML → JSON at $VERDICT_JSON_PATH (next bash section).
+  # Off-host (ADR-0021): when np-plan-checker routes to an openai-compat provider,
+  # run it via spawn-offhost (below) INSTEAD of the Agent tool.
   # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   CHECKER_START=$(node .nubos-pilot/bin/np-tools.cjs metrics start-timestamp)
   CHECKER_MODEL=$(node .nubos-pilot/bin/np-tools.cjs resolve-model np-plan-checker --profile frontier)
-  # → execute the Agent call per ACTION CONTRACT above, then:
-  CHECKER_END=$(node .nubos-pilot/bin/np-tools.cjs metrics end-timestamp)
-  node .nubos-pilot/bin/np-tools.cjs metrics record \
-    --agent np-plan-checker --tier opus --resolved-model "$CHECKER_MODEL" \
-    --phase "$PHASE" --plan "${milestone_id}-plan" --task "${milestone_id}-planner-run" \
-    --started "$CHECKER_START" --ended "$CHECKER_END" \
-    --tokens-in "${TOKENS_IN:-0}" --tokens-out "${TOKENS_OUT:-0}" \
-    --retry-count 0 --status ok --runtime "$RUNTIME"
+  CHECKER_KIND=$(node .nubos-pilot/bin/np-tools.cjs resolve-model np-plan-checker --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 [ "$CHECKER_KIND" = "openai-compat" ]; then
+    # np-plan-checker is NOT Rule-9-audited and writes ONLY the verdict YAML under
+    # $milestone_dir (inside the repo cwd), 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 $milestone_dir/.tmp-verdict-$ITER.yaml exactly as the
+    # native checker does (the orchestrator's YAML→JSON step is unchanged).
+    # spawn-offhost records the metrics row itself.
+    CHECKER_PROMPT="${TMPDIR:-/tmp}/np-offhost-plan-checker-${milestone_id}-i${ITER}.md"
+    # … render the SAME prompt the ACTION CONTRACT above describes (milestone,
+    #   milestone_dir, agent_skills) PLUS $LANG_DIRECTIVE, and MUST state the exact
+    #   output path $milestone_dir/.tmp-verdict-$ITER.yaml, into "$CHECKER_PROMPT" …
+    node .nubos-pilot/bin/np-tools.cjs spawn-offhost \
+      --agent np-plan-checker --task-file "$CHECKER_PROMPT" \
+      --phase "$PHASE" --plan "${milestone_id}-plan" >/dev/null
+  else
+    # → execute the Agent call per ACTION CONTRACT above (native host spawn), then:
+    CHECKER_END=$(node .nubos-pilot/bin/np-tools.cjs metrics end-timestamp)
+    node .nubos-pilot/bin/np-tools.cjs metrics record \
+      --agent np-plan-checker --tier opus --resolved-model "$CHECKER_MODEL" \
+      --phase "$PHASE" --plan "${milestone_id}-plan" --task "${milestone_id}-planner-run" \
+      --started "$CHECKER_START" --ended "$CHECKER_END" \
+      --tokens-in "${TOKENS_IN:-0}" --tokens-out "${TOKENS_OUT:-0}" \
+      --retry-count 0 --status ok --runtime "$RUNTIME"
+  fi
 
   VERDICT_JSON_PATH="$milestone_dir/.tmp-verdict-$ITER.json"
   # (verdict JSON: {status: passed|issues_found, findings: [...] })

package/workflows/research-phase.md

@@ -253,8 +253,36 @@ omit the `model:` parameter at spawn (Phase 8 D-22 inherit-pattern).
 ```bash
 RESEARCHER_START=$(node .nubos-pilot/bin/np-tools.cjs metrics start-timestamp)
 RESEARCHER_MODEL=$(node .nubos-pilot/bin/np-tools.cjs resolve-model np-researcher --profile balanced)
+RESEARCHER_KIND=$(node .nubos-pilot/bin/np-tools.cjs resolve-model np-researcher --kind 2>/dev/null || echo native)
 ```
 
+**Off-host (ADR-0021):** when `np-researcher` routes to an `openai-compat` provider, run the `$SWARM_K` spawns via `spawn-offhost` instead of the abstract host spawn. Two specifics for this audited agent:
+
+- **Synthetic canonical task-id.** `np-researcher` is Rule-9-audited and `dispatchOffHost` requires a `M<NNN>-S<NNN>-T<NNNN>` id for the search-evidence ledger + audit. Research is milestone-level (no real slice/task), so mint the synthetic id `${MILESTONE_ID}-S000-T0000` (the `S000-T0000` suffix is the documented "milestone-level, no slice/task" convention). The injected native `knowledge-search` tool satisfies Rule 9; the orchestrator stamps one `loop-audit-tool-use` per spawn.
+- **Offline only.** The off-host toolset has **no `WebFetch`/`context7`** — an off-host researcher can only do `$MODE == offline` (knowledge-search) research. If `$MODE == online`, keep `np-researcher` native (or accept offline-only research for that spawn). This is a capability bound, surfaced loudly, not a silent degrade.
+
+Each spawn writes its own `$RESEARCH_DIR/spawn-<i>.md` (inside the repo cwd), so it runs write-enabled (NOT `--read-only`), no `--allow-bash`, no worktree.
+
+```bash
+if [ "$RESEARCHER_KIND" = "openai-compat" ]; then
+  OFFHOST_TASK_ID="${MILESTONE_ID}-S000-T0000"
+  i=0
+  while [ "$i" -lt "${SWARM_K:-3}" ]; do
+    R_PROMPT="${TMPDIR:-/tmp}/np-offhost-researcher-${MILESTONE_ID}-${i}.md"
+    # … render spawn-spec i (files_to_read + goal + requirements + seed_delta[i] +
+    #   $SPAWN_SCHEMA + the EXACT output path $RESEARCH_DIR/spawn-${i}.md) PLUS
+    #   $LANG_DIRECTIVE into "$R_PROMPT" …
+    R_OUT=$(node .nubos-pilot/bin/np-tools.cjs spawn-offhost \
+      --agent np-researcher --task-file "$R_PROMPT" --task-id "$OFFHOST_TASK_ID" --no-audit)
+    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 "$OFFHOST_TASK_ID" --agent np-researcher --tool-use-log "$R_LOG"
+    i=$((i+1))
+  done
+fi
+```
+
+When `$RESEARCHER_KIND = native`, use the abstract host spawn below (the Phase 8 runtime adapter binds it):
+
 ```text
 Spawn agent=np-researcher tier=sonnet model=$RESEARCHER_MODEL mode=$MODE phase=$PHASE context=$CONTEXT_PATH output=$RESEARCH_PATH
 ```
@@ -351,6 +379,23 @@ Spawn agent=np-researcher-reconciler tier=sonnet model=$RECONCILER_MODEL phase=$
   schema_prompt=$RECONCILER_SCHEMA
 ```
 
+**Off-host (ADR-0021):** when `np-researcher-reconciler` routes to an `openai-compat` provider, run it via `spawn-offhost` instead of the host spawn. The reconciler is NOT Rule-9-audited and writes only the single `$RESEARCH_PATH` (`M<NNN>-RESEARCH.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 spawn outputs + Write confined to cwd), **no `--allow-bash`, no worktree**. It writes `$RESEARCH_PATH` exactly as the native reconciler; no emit-and-persist contract is needed. spawn-offhost self-records.
+
+```bash
+RECONCILER_KIND=$(node .nubos-pilot/bin/np-tools.cjs resolve-model np-researcher-reconciler --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 [ "$RECONCILER_KIND" = "openai-compat" ]; then
+  RECONCILER_PROMPT="${TMPDIR:-/tmp}/np-offhost-reconciler-${MILESTONE_ID}.md"
+  # … render the SAME reconciler input (spawn_paths + merge_path + merged_json +
+  #   context_path + $RECONCILER_SCHEMA + the EXACT final_path=$RESEARCH_PATH) PLUS
+  #   $LANG_DIRECTIVE into "$RECONCILER_PROMPT" …
+  node .nubos-pilot/bin/np-tools.cjs spawn-offhost \
+    --agent np-researcher-reconciler --task-file "$RECONCILER_PROMPT" \
+    --phase "$PHASE" --plan "$PLAN_ID" --task "$TASK_ID" >/dev/null
+fi
+# else → native host spawn per the block above.
+```
+
 The reconciler classifies each consensus decision's reasoning-trace as `identical | overlapping | orthogonal | unknown` (groupthink detection), picks each contested decision with documented reason, and writes `$RESEARCH_PATH` with `agreement_score` and `contested_count` in frontmatter.
 
 ```bash

package/workflows/scan-codebase.md

@@ -106,9 +106,27 @@ is runtime-agnostic — pick whichever dispatch mechanism your host supports.
 
 ```bash
 PROSE_FILE=$(mktemp -t np-prose-XXXXXX.json)
-# Host dispatches agent with buildDocumenterPrompt(facts) and writes JSON
-# to $PROSE_FILE. Validate JSON before proceeding.
-python -c 'import json,sys; json.load(open(sys.argv[1]))' "$PROSE_FILE"
+# Off-host (ADR-0021): when np-codebase-documenter routes to an openai-compat
+# provider (agent_routing), run it via spawn-offhost INSTEAD of the native host
+# dispatch below.
+DOCUMENTER_KIND=$(node .nubos-pilot/bin/np-tools.cjs resolve-model np-codebase-documenter --kind 2>/dev/null || echo native)
+if [ "$DOCUMENTER_KIND" = "openai-compat" ]; then
+  # np-codebase-documenter is NOT Rule-9-audited and writes ONLY
+  # .nubos-pilot/codebase/ artefacts (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 and NO worktree (no live-code blast
+  # radius to isolate). The agent writes its module doc JSON itself, inside cwd.
+  DOC_PROMPT="${TMPDIR:-/tmp}/np-offhost-documenter-${MODULE_ID}.md"
+  # … render the SAME buildDocumenterPrompt(facts) prompt the native dispatch
+  #   below describes PLUS $LANG_DIRECTIVE into "$DOC_PROMPT" …
+  node .nubos-pilot/bin/np-tools.cjs spawn-offhost \
+    --agent np-codebase-documenter --task-file "$DOC_PROMPT" \
+    --phase scan >/dev/null
+else
+  # Host dispatches agent with buildDocumenterPrompt(facts) and writes JSON
+  # to $PROSE_FILE. Validate JSON before proceeding.
+  python -c 'import json,sys; json.load(open(sys.argv[1]))' "$PROSE_FILE"
+fi
 ```
 
 Batch pacing: the user opted into batches during Step 1. Between batches,

package/workflows/validate-phase.md

@@ -129,6 +129,8 @@ The auditor reads `REQUIREMENTS.md`, filters to the milestone's declared require
 ```bash
 START=$(node .nubos-pilot/bin/np-tools.cjs metrics start-timestamp)
 MODEL=$(node .nubos-pilot/bin/np-tools.cjs resolve-model np-nyquist-auditor --profile frontier)
+AUDITOR_KIND=$(node .nubos-pilot/bin/np-tools.cjs resolve-model np-nyquist-auditor --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")}})')
 
 # Build the read list from the init payload:
 SLICE_PLANS=$(find "$MILESTONE_DIR/slices" -maxdepth 2 -name 'S*-PLAN.md' 2>/dev/null)
@@ -136,19 +138,34 @@ SLICE_SUMMARIES=$(find "$MILESTONE_DIR/slices" -maxdepth 2 -name 'S*-SUMMARY.md'
 TASK_PLANS=$(find "$MILESTONE_DIR/slices" -path '*/tasks/*/T*-PLAN.md' 2>/dev/null)
 TASK_SUMMARIES=$(find "$MILESTONE_DIR/slices" -path '*/tasks/*/T*-SUMMARY.md' 2>/dev/null)
 
-# Spawn agent=np-nyquist-auditor model=$MODEL
-#   input: slice_plans, slice_summaries, task_plans, task_summaries, validation_path,
-#          template_path, requirements_path, milestone_dir, milestone, milestone_id
-#   output: $VALIDATION_PATH with per-requirement Nyquist scoring
-#           (COVERED / UNDER_SAMPLED / UNCOVERED), using templates/VALIDATION.md as skeleton.
-
-END=$(node .nubos-pilot/bin/np-tools.cjs metrics end-timestamp)
-node .nubos-pilot/bin/np-tools.cjs metrics record \
-  --agent np-nyquist-auditor --tier haiku --resolved-model "$MODEL" \
-  --phase "$PHASE" --plan "$PLAN_ID" --task "$TASK_ID" \
-  --started "$START" --ended "$END" \
-  --tokens-in "${TOKENS_IN:-0}" --tokens-out "${TOKENS_OUT:-0}" \
-  --retry-count 0 --status ok --runtime "$RUNTIME"
+if [ "$AUDITOR_KIND" = "openai-compat" ]; then
+  # Off-host (ADR-0021): np-nyquist-auditor is NOT Rule-9-audited and writes ONLY
+  # $VALIDATION_PATH (M<NNN>-VALIDATION.md) under .nubos-pilot/ (inside the repo
+  # cwd — NOT 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 from templates/VALIDATION.md exactly as the native auditor does (the
+  # orchestrator's output-lint check is unchanged). spawn-offhost self-records.
+  AUDITOR_PROMPT="${TMPDIR:-/tmp}/np-offhost-nyquist-${MILESTONE_ID}.md"
+  # … render the SAME auditor prompt (read list above + $VALIDATION_SCHEMA +
+  #   template_path + requirements_path + the EXACT output path $VALIDATION_PATH)
+  #   PLUS $LANG_DIRECTIVE into "$AUDITOR_PROMPT" …
+  node .nubos-pilot/bin/np-tools.cjs spawn-offhost \
+    --agent np-nyquist-auditor --task-file "$AUDITOR_PROMPT" \
+    --phase "$PHASE" --plan "$PLAN_ID" --task "$TASK_ID" >/dev/null
+else
+  # Spawn agent=np-nyquist-auditor model=$MODEL (native host spawn)
+  #   input: slice_plans, slice_summaries, task_plans, task_summaries, validation_path,
+  #          template_path, requirements_path, milestone_dir, milestone, milestone_id
+  #   output: $VALIDATION_PATH with per-requirement Nyquist scoring
+  #           (COVERED / UNDER_SAMPLED / UNCOVERED), using templates/VALIDATION.md as skeleton.
+  END=$(node .nubos-pilot/bin/np-tools.cjs metrics end-timestamp)
+  node .nubos-pilot/bin/np-tools.cjs metrics record \
+    --agent np-nyquist-auditor --tier haiku --resolved-model "$MODEL" \
+    --phase "$PHASE" --plan "$PLAN_ID" --task "$TASK_ID" \
+    --started "$START" --ended "$END" \
+    --tokens-in "${TOKENS_IN:-0}" --tokens-out "${TOKENS_OUT:-0}" \
+    --retry-count 0 --status ok --runtime "$RUNTIME"
+fi
 ```
 
 ## Validation Gate

package/workflows/verify-work.md

@@ -81,6 +81,23 @@ Spawn `agents/np-verifier.md` (tier: sonnet, READ-ONLY tools) with:
 
 The agent emits a structured verdict per SC: Pass | Fail | Needs-User-Confirm | Defer (never invents a SC, never edits source).
 
+**Off-host (ADR-0021):** when `np-verifier` routes to an `openai-compat` provider, run it via `spawn-offhost --read-only` instead of the host spawn. The verifier never edits source and **emits** its per-SC verdict as the final message — exactly the contract the native path already consumes — so it needs no worktree, no Bash, no Write. Pass `--output-schema verification` for the dispatch-level lint hook, then feed the returned `.content` (the emitted verdict) into the SAME Pass-1 `emit-draft` / Pass-2 `record-sc` persistence below; `VERIFICATION.md` is produced exactly as for the native agent.
+
+```bash
+VERIFIER_KIND=$(node .nubos-pilot/bin/np-tools.cjs resolve-model np-verifier --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 [ "$VERIFIER_KIND" = "openai-compat" ]; then
+  VERIFIER_PROMPT="${TMPDIR:-/tmp}/np-offhost-verifier-${MILESTONE_ID}.md"
+  # … render the SAME spawn prompt (files_to_read + success_criteria +
+  #   $VERIFICATION_SCHEMA) PLUS $LANG_DIRECTIVE into "$VERIFIER_PROMPT" …
+  VERIFIER_OUT=$(node .nubos-pilot/bin/np-tools.cjs spawn-offhost \
+    --agent np-verifier --task-file "$VERIFIER_PROMPT" --read-only \
+    --output-schema verification --phase "$PHASE")
+  # The emitted verdict is `.content` of $VERIFIER_OUT — it drives emit-draft / record-sc below.
+fi
+# else → native host spawn per the block above.
+```
+
 Persist the deterministic draft:
 
 ```bash