@hanzlaa/rcode 4.12.0 → 4.13.0

package/rcode/workflows/plan-research-validation.md

@@ -70,10 +70,16 @@ Answer: "What do I need to know to PLAN this phase well?"
 <files_to_read>
 - {context_path} (USER DECISIONS from /rcode-discuss-phase)
 - {requirements_path} (Project requirements)
-- {state_path} (Project decisions and history)
 </files_to_read>
 
-${AGENT_SKILLS_RESEARCHER}
+<project_state_digest>
+{state_digest as JSON — current phase, recent decisions, open blockers. Slim
+extract of state.json (#948); do NOT separately Read .rcode/state.json — its
+full history (all phases, all sprints) is not needed here and costs 10-20K+
+tokens on a mature project.}
+</project_state_digest>
+
+{agent_skills.researcher}
 
 <additional_context>
 **Phase description:** {phase_description}

package/rcode/workflows/plan-spawn-planner.md

@@ -34,14 +34,20 @@ When `GAPS_MODE=true`, use the prompt below in place of the standard planner pro
 
 <files_to_read>
 - {VERIFICATION_FILE} (Authoritative verification report — source of truth for gaps)
-- {state_path} (Project State)
 - {roadmap_path} (Roadmap)
 - {requirements_path} (Requirements)
 - Existing plan files in this phase: {EXISTING_PLAN_FILES}
 - Existing summary files in this phase: {EXISTING_SUMMARY_FILES}
 </files_to_read>
 
-${AGENT_SKILLS_PLANNER}
+<project_state_digest>
+{state_digest as JSON — current phase, recent decisions, open blockers. Slim
+extract of state.json (#948); do NOT separately Read .rcode/state.json — its
+full history (all phases, all sprints) is not needed here and costs 10-20K+
+tokens on a mature project.}
+</project_state_digest>
+
+{agent_skills.planner}
 
 <gap_list>
 {Serialized GAP_LIST — for each gap include id, title, expected behavior, actual behavior, status (gap_found|partial), and source section.}
@@ -86,7 +92,6 @@ Default: `phase` (one SPRINT.md, up to 8 stories — see Scope-Driven Sizing in
 **Self-upgrade to `initiative` mid-decomposition** if, once you've read CONTEXT.md/ROADMAP.md and started breaking down the work, it splits into independent waves or work-streams (e.g. shared-primitive foundation → feature-local migrations → cleanup/tests) and total stories would exceed 8. When that happens, emit multiple SPRINT.md files (`{phase}-1-SPRINT.md`, `{phase}-2-SPRINT.md`, ...) in this same run instead of one oversized plan. Do not wait for rcode-sprint-checker's "scope exceeds context budget" rejection to force a resharding pass — that costs a full extra planner run. Decide the split now, while you're already looking at the file/story list.
 
 <files_to_read>
-- {state_path} (Project State)
 - {roadmap_path} (Roadmap)
 - {requirements_path} (Requirements)
 - {context_path} (USER DECISIONS from /rcode-discuss-phase — read `<decisions>` for locked choices AND `<code_context>` for existing code patterns, reusable assets, and architectural notes gathered during discuss-phase)
@@ -102,7 +107,14 @@ ${CONTEXT_WINDOW >= 500000 ? `
 ` : ''}
 </files_to_read>
 
-${AGENT_SKILLS_PLANNER}
+<project_state_digest>
+{state_digest as JSON — current phase, recent decisions, open blockers. Slim
+extract of state.json (#948); do NOT separately Read .rcode/state.json — its
+full history (all phases, all sprints) is not needed here and costs 10-20K+
+tokens on a mature project.}
+</project_state_digest>
+
+{agent_skills.planner}
 
 **Phase requirement IDs (every ID MUST appear in a plan's `requirements` field):** {phase_req_ids}
 
@@ -266,6 +278,21 @@ Every task MUST include these fields — they are NOT optional:
 4. **`<verify>`** — Shell commands that PROVE the `<done>` criteria are met. Run by executor after task completes and by verifier during post-execution check. The block MUST contain an `<automated>` child with the exact commands to run (Dimension 8 hard-blocks without it). Rules:
    - `<automated>` commands must exit 0 on success, non-zero on failure
    - Prefer `grep -q` for presence checks, `test -f` for file existence, project test runner for behavior
+   - **A task that adds or changes a guard test MUST prove the test fails on the
+     unfixed code first ("red first").** A guard test is any test whose job is to
+     make a class of mistake impossible: meta-tests, schema invariant tests,
+     forbidden-pattern scans, coverage/manifest tests, lint-rule tests. Write the
+     task so the `<action>` states the red step explicitly ("run the new test on
+     the current tree and record that it fails, then apply the fix") and the
+     `<verify><automated>` block asserts the green state. A guard test that has
+     never been observed red is indistinguishable from one that greps the wrong
+     path — that is exactly how a `route.ts`-only glob left every Server Action
+     unguarded for nine phases while CI stayed green the whole time.
+   - **Absence checks use `! grep -q PATTERN FILE`, never `grep -qv`.** `-v` inverts per-line
+     matching, so `grep -qv PATTERN FILE` exits 0 as soon as ANY line fails to match — i.e. it
+     passes on virtually every file, including one that contains the forbidden pattern. This is a
+     silently-always-green assertion, the worst possible verify command. Same for "file must not
+     exist": `! test -f path`.
    - Keep commands short and composable — one check per line
    - If test file doesn't exist yet (TDD tasks), write `<automated>MISSING</automated>` and add a Wave 0 task to create the test
    - Example structure:
@@ -323,6 +350,7 @@ Every task MUST include these fields — they are NOT optional:
 - [ ] Every task has `<files>` listing exact files this task will modify or create
 - [ ] Every task has `<evidence>` with grep/lines/creates codebase grounding per issue #649 — not a prose checklist tag (none exists in the real plan schema)
 - [ ] Every task has `<verify>` with an `<automated>` child containing at least one shell command (Dimension 8 blocker)
+- [ ] Every guard-test task states its red-first step in `<action>` (Dimension 8 blocker)
 - [ ] Every task has `<done>` with a single observable acceptance sentence (Dimension 2 requirement)
 - [ ] Every `<action>` contains concrete values (no "align X with Y" without specifying what)
 - [ ] Tasks extending existing code have `<interfaces>` with relevant signatures

package/rcode/workflows/plan.md

@@ -72,7 +72,35 @@ When `--from-stub` is passed:
 
 This mode exists to skip expensive re-derivation when a human or prior agent has already produced a planning skeleton.
 
-## 0. Project-Status Preflight
+## 0. You are Raees for this run (orchestrator contract)
+
+@.rcode/agents-rules/orchestrator/contract.md
+
+Planning is orchestration too: it spawns a researcher, a planner, a specialist
+panel, and a checker, and it decides what each one gets. Adopt the contract and
+hold it for the whole run.
+
+**Open with the orientation banner before the first subagent is spawned**, filled
+from the INIT JSON and the phase's artifacts — not from memory:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ rcode ► RAEES — {project}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Where you are   Phase {N} — {name} · {status} · {existing plans, if any}
+What I read     {ROADMAP, CONTEXT.md, RESEARCH.md — whichever you actually opened}
+What I'll do    {the agents this run will spawn, in order, each named}
+What I need     {CONTEXT.md gaps or decisions blocked on the user, or "nothing — starting now"}
+```
+
+**Raees does not write the plan.** `rcode-planner` writes SPRINT.md files; the
+panel reviews them; `rcode-sprint-checker` grades them. If you find yourself
+drafting tasks inline, the run has lost its orchestrator — spawn the planner
+instead. A SPRINT.md with no planner `Task()` behind it is the failure this rule
+exists to prevent (see step 8).
+
+## 0.5. Project-Status Preflight
 
 ```bash
 PROJECT_STATUS=$(node .rcode/bin/rcode-tools.cjs project-status 2>/dev/null || echo uninitialized)
@@ -124,11 +152,6 @@ Load all context in one call (paths only to minimize orchestrator context):
 ```bash
 INIT=$(node ".rcode/bin/rcode-tools.cjs" init sprint-plan "$PHASE" 2>/dev/null)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-AGENT_SKILLS_RESEARCHER=$(node ".rcode/bin/rcode-tools.cjs" agent-skills rcode-phase-researcher 2>/dev/null || echo "")
-AGENT_SKILLS_PLANNER=$(node ".rcode/bin/rcode-tools.cjs" agent-skills rcode-planner 2>/dev/null || echo "")
-AGENT_SKILLS_CHECKER=$(node ".rcode/bin/rcode-tools.cjs" agent-skills rcode-sprint-checker 2>/dev/null || echo "")
-CONTEXT_WINDOW=$(node ".rcode/bin/rcode-tools.cjs" config-get context_window 2>/dev/null)
-CONTEXT_WINDOW=${CONTEXT_WINDOW:-200000}  # config-get exits 0 with empty output when key absent; || fallback won't fire
 
 # Detect UI signals in phase goal + CONTEXT.md to decide whether to load ui-brand.md (254 lines)
 PHASE_GOAL_HAS_UI=$(grep -iEl "frontend|ui|component|design|style|brand" \
@@ -141,9 +164,11 @@ If `INIT` is empty, or `INIT.ok` is false or absent (null/undefined — `init sp
 Error: rcode-tools init failed. Verify .rcode/ is installed and state.json is valid.
 ```
 
+**#949 — no separate `agent-skills` / `config-get context_window` calls.** `init sprint-plan` already returns `agent_skills.researcher`, `agent_skills.planner`, `agent_skills.checker` (the same manifest rows the standalone `agent-skills <id>` command returns) and `context_window`, folded in to avoid 4 extra cold Node starts per plan run. Read `agent_skills.researcher` / `.planner` / `.checker` directly from `$INIT` wherever this doc previously referenced `$AGENT_SKILLS_RESEARCHER` / `$AGENT_SKILLS_PLANNER` / `$AGENT_SKILLS_CHECKER`. `CONTEXT_WINDOW` defaults to `200000` when `context_window` is null (config key absent).
+
 When `CONTEXT_WINDOW >= 500000`, the planner prompt includes prior phase CONTEXT.md files so cross-phase decisions are consistent (e.g., "use library X for all data fetching" from Phase 2 is visible to Phase 5's planner).
 
-Parse JSON for: `researcher_model`, `planner_model`, `checker_model`, `research_enabled`, `plan_checker_enabled`, `nyquist_validation_enabled`, `commit_docs`, `text_mode`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_reviews`, `has_plans`, `plan_count`, `phase_status`, `planning_exists`, `roadmap_exists`, `phase_req_ids`, `response_language`.
+Parse JSON for: `researcher_model`, `planner_model`, `checker_model`, `research_enabled`, `plan_checker_enabled`, `nyquist_validation_enabled`, `specialist_review_enabled`, `commit_docs`, `text_mode`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_reviews`, `has_plans`, `plan_count`, `phase_status`, `planning_exists`, `roadmap_exists`, `phase_req_ids`, `response_language`, `context_window`, `agent_skills`, `state_digest`.
 
 **If `response_language` is set:** Include `response_language: {value}` in all spawned subagent prompts so any user-facing output stays in the configured language.
 
@@ -153,7 +178,7 @@ Parse JSON for: `researcher_model`, `planner_model`, `checker_model`, `research_
 
 ## 2. Parse and Normalize Arguments
 
-Extract from $ARGUMENTS: phase number (integer or decimal like `2.1`), flags (`--research`, `--skip-research`, `--gaps`, `--skip-verify`, `--from-stub`, `--prd <filepath>`, `--reviews`, `--text`).
+Extract from $ARGUMENTS: phase number (integer or decimal like `2.1`), flags (`--research`, `--skip-research`, `--gaps`, `--skip-verify`, `--from-stub`, `--prd <filepath>`, `--reviews`, `--text`, `--no-panel`).
 
 Set `TEXT_MODE=true` if `--text` is present in $ARGUMENTS OR `text_mode` from init JSON is `true`. When `TEXT_MODE` is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for Claude Code remote sessions (`/rc` mode) where TUI menus don't work through the Claude App.
 
@@ -571,6 +596,108 @@ Use AskUserQuestion with these 3 options.
 **If "Proceed":** Return to planner with instruction to attempt all decisions at full fidelity, accepting more plans/tasks.
 **If "Prioritize":** Use AskUserQuestion (multiSelect) to let user pick which D-XX are "now" vs "later". Create CONTEXT.md for each sub-phase with the selected decisions.
 
+## 9.5. Specialist Review Panel (domain-routed)
+
+**Why this step exists.** Until now one generalist (`rcode-planner`) produced the
+entire plan and one generalist (`rcode-sprint-checker`) graded it against the
+phase goal. Nobody asked *"is this design wrong"* or *"what will this guard
+miss"*. Confirmed live on a real project: nine phases planned and shipped this
+way, and the first hour of specialist review found an inert RLS backstop, an
+authorization mutation with no relationship check, a core feature whose only
+importer was its own test, and real personal data committed to the repo. The
+sprint-checker missed all four because none of them is a goal-coverage question.
+
+**Skip only if:** `specialist_review_enabled` from the INIT JSON is `false`
+(set `workflow.specialist_review: false` in `.rcode/config.yaml`; absent key =
+enabled), or `--no-panel` was passed. In
+autonomous/yolo mode this step is **NOT skippable** — yolo removes the human
+mid-loop check, so plan-time review is the only review left.
+
+### 9.5a — Pick the panel
+
+**You route this, from context — not from a keyword table.** Read the evidence
+first, then decide:
+
+1. The plans' `<files>` fields — every path this phase will actually touch.
+2. Migrations, schema files, and config the plans create or alter.
+3. CONTEXT.md decisions (D-XX) and the phase goal.
+4. The installed roster and what each persona actually owns:
+   ```bash
+   node ".rcode/bin/rcode-tools.cjs" list-agents
+   ```
+
+Then pick the domain seats by asking, per candidate: *given these files and
+these decisions, does this persona's lens see something the others cannot?* If
+the answer is no, do not seat them.
+
+Run the keyword scorer as **one input, never the verdict**:
+
+```bash
+node ".rcode/bin/rcode-tools.cjs" select-panel \
+  "${PHASE_GOAL}. ${CONTEXT_DECISIONS_SUMMARY}" --explain
+```
+
+It is a weighted keyword table, so it routes on the words the phase text happens
+to use, not on what the phase touches — a phase full of `drizzle/*.sql` RLS
+policies that never writes the word "security" scores near zero for the security
+lens. That is the same enumerate-a-location shape this panel exists to hunt for,
+so treat a high score as corroboration and a zero score as no information.
+
+**When your reading and the scorer disagree, your reading wins — and you must
+say so in the panel report**: which persona you seated or dropped against the
+score, and the file or decision that made you do it. A routing override with no
+stated reason is indistinguishable from a coin flip.
+
+Panel composition:
+
+- **Always include `rcode-waleed`** (architecture lens) — the "is this design
+  wrong" seat. Every phase gets it.
+- **Always include `rcode-fatima`** (quality lens) — the "what will this guard
+  miss" seat. Every phase gets it.
+- **Plus 1-2 domain personas** chosen by the reading above. Seat a persona only
+  when you can name the file, migration, or decision that needs their lens. A
+  seat filled to reach a quota costs tokens and adds nothing.
+
+Cap the panel at 4. If nothing in the plans needs a third lens, the two standing
+seats ARE the panel — a correct outcome, not a failure to route.
+
+### 9.5b — Run the panel in parallel
+
+Spawn all panel members in a single message so they run concurrently. Each gets
+the same narrow contract:
+
+```
+You are reviewing SPRINT plans BEFORE execution, through your lens only.
+
+Read: {PHASE_DIR}/*-SPRINT.md, {PHASE_DIR}/CONTEXT.md, ROADMAP.md phase {N}.
+
+Return ONLY blocking issues — things that would make the executed phase wrong,
+unsafe, or unverifiable. Not style, not preferences, not "consider also".
+For each issue: what is wrong, the file:line or task id it lives in, and the
+specific change that fixes it.
+
+Two questions you MUST answer explicitly, even if the answer is "none":
+  1. Which task in this plan enumerates a LOCATION where it should derive from a
+     PROPERTY? (a glob, a single filename, one role, one directory) — that shape
+     is how a guard ends up green while pointing where the problem is not.
+  2. Which delivered module would have no production importer after this phase
+     executes — reachable only from its own test?
+
+If you have no blocking issues, return exactly: NO BLOCKING ISSUES.
+Do not restate the plan. Do not summarize. {response_language pass-through}
+```
+
+### 9.5c — Handle panel return
+
+- All members return `NO BLOCKING ISSUES` → proceed to step 10.
+- Any blocking issue → feed it into the **existing revision loop (step 12)**
+  alongside the checker's issues. Do not build a second revision mechanism.
+- Panel issues and checker issues are deduped by task id before re-spawning the
+  planner.
+
+Report to the user which agents sat on the panel and what each blocked on — a
+silent panel is indistinguishable from a skipped one.
+
 ## 10. Spawn rcode-sprint-checker Agent
 
 Display banner:
@@ -597,7 +724,7 @@ Checker prompt:
 - {research_path} (Technical Research — includes Validation Architecture)
 </files_to_read>
 
-${AGENT_SKILLS_CHECKER}
+{agent_skills.checker}
 
 **Phase requirement IDs (MUST ALL be covered):** {phase_req_ids}
 
@@ -721,7 +848,7 @@ Revision prompt:
 - {context_path} (USER DECISIONS from /rcode-discuss-phase)
 </files_to_read>
 
-${AGENT_SKILLS_PLANNER}
+{agent_skills.planner}
 
 **Checker issues:** {structured_issues_from_checker}
 </revision_context>
@@ -1029,6 +1156,7 @@ ${WINDOWS === 'true' ? '@.rcode/references/plan-windows-troubleshooting.md' : ''
 - [ ] Phase directory created if needed
 - [ ] CONTEXT.md loaded early (step 4) and passed to ALL agents
 - [ ] Research completed (unless --skip-research or --gaps or exists)
+- [ ] Specialist review panel spawned (Waleed + Fatima + domain agents) and its blocking issues fed into the revision loop, or `workflow.specialist_review: false` recorded
 - [ ] rcode-phase-researcher spawned with CONTEXT.md
 - [ ] Existing plans checked
 - [ ] rcode-planner spawned with CONTEXT.md + RESEARCH.md

package/rcode/workflows/pr-branch.md

@@ -114,6 +114,8 @@ Next steps:
   git push origin {PR_BRANCH}
   gh pr create --base {TARGET} --head {PR_BRANCH}
 
+  (PR title/body must follow @rcode/references/github-comment-style.md)
+
 Or use /rcode-ship to create the PR automatically.
 ```
 </step>

package/rcode/workflows/research-phase.md

@@ -42,11 +42,13 @@ If exists: Offer update/view/skip options.
 INIT=$(node ".rcode/bin/rcode-tools.cjs" init phase-op "${PHASE}" 2>/dev/null)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 # If INIT is empty or INIT.ok is false: print "Error: rcode-tools init failed." and exit.
-# Extract: phase_dir, padded_phase, phase_number, state_path, requirements_path, context_path, response_language
+# Extract: phase_dir, padded_phase, phase_number, requirements_path, context_path, response_language,
+# state_digest, agent_skills.researcher
 # If response_language is set, include "Respond in {value}." in all spawned subagent prompts.
-AGENT_SKILLS_RESEARCHER=$(node ".rcode/bin/rcode-tools.cjs" agent-skills rcode-phase-researcher 2>/dev/null || echo "")
 ```
 
+**#949 — no separate `agent-skills rcode-phase-researcher` call.** `init phase-op` already returns `agent_skills.researcher` (same manifest row), folded in to avoid a second cold Node start per research run.
+
 ## Step 4: Spawn Researcher
 
 ```
@@ -69,10 +71,16 @@ Downstream consumer: /rcode-plan reads {phase}-RESEARCH.md to structure sprints.
 <files_to_read>
 - {context_path} (USER DECISIONS from /rcode-discuss-phase)
 - {requirements_path} (Project requirements)
-- {state_path} (Project decisions and history)
 </files_to_read>
 
-${AGENT_SKILLS_RESEARCHER}
+<project_state_digest>
+{state_digest as JSON — current phase, recent decisions, open blockers. Slim
+extract of state.json (#948); do NOT separately Read .rcode/state.json — its
+full history (all phases, all sprints) is not needed here and costs 10-20K+
+tokens on a mature project.}
+</project_state_digest>
+
+{agent_skills.researcher}
 
 <additional_context>
 Phase description: {description}

package/rcode/workflows/ship.md

@@ -246,6 +246,10 @@ Omit this section entirely when VERIFICATION.md status is a clean `passed` with
 </step>
 
 <step name="create_pr">
+**Before creating the PR, apply `@rcode/references/github-comment-style.md` to `${PR_BODY}`** —
+no em-dashes, no gates/CI block, no git-process talk, no AI attribution. Run the
+self-check greps in that reference; they must print nothing.
+
 Create the PR using the generated body:
 
 ```bash

package/rcode/workflows/verify-phase.md

@@ -380,6 +380,43 @@ Fill template sections: frontmatter (phase/timestamp/status/score), goal achieve
 See .rcode/templates/verification-report.md for complete template.
 </step>
 
+<step name="falsification_pass">
+**MANDATORY when `$STATUS` is `passed`.** Run the falsification pass defined in
+`@.rcode/workflows/execute-verify-phase-goal.md` — a second agent, given the goal
+and the codebase but NOT the summaries or this report, whose only job is to
+refute the pass. Attack order: production reachability, guard shape, runtime
+truth, claim-without-evidence.
+
+- REFUTED → set `$STATUS=gaps_found`, append the finding to VERIFICATION.md's
+  gaps section, and skip the write-back below.
+- UPHELD → record `falsification: upheld` in VERIFICATION.md frontmatter.
+
+A `passed` VERIFICATION.md with no `falsification:` key is self-certified and
+must not be treated as verified by any downstream command.
+</step>
+
+<step name="write_back_state">
+**MANDATORY when status is `passed`. Verification is the terminal step of the
+plan → execute → verify loop, and a terminal step with no write-back leaves
+state.json permanently stale.** A phase can be verified green on disk while
+state.json still says `planned` — and because `state sync --from-disk` only
+advances status, nothing downstream ever corrects it. `/rcode-status` then
+reports 1/13 when the real number is 9/13.
+
+```bash
+if [ "$STATUS" = "passed" ]; then   # only reachable when falsification upheld
+  node ".rcode/bin/rcode-tools.cjs" phase complete "${PHASE_NUMBER}" 2>&1
+fi
+```
+
+Check the result. If it returns `ok: false` or a non-zero exit, say so in the
+report to the orchestrator — do NOT report the phase as verified-and-recorded
+when only the file was written. If the phase is not yet in `state.phases`, run
+`node ".rcode/bin/rcode-tools.cjs" state sync --from-disk` first, then retry.
+
+Do not run this for `gaps_found` or `human_needed` — those are not complete.
+</step>
+
 <step name="return_to_orchestrator">
 Return status (`passed` | `gaps_found` | `human_needed`), score (N/M must-haves), report path.
 
@@ -404,7 +441,10 @@ Orchestrator routes: `passed` → update_roadmap | `gaps_found` → create/execu
 - [ ] Overall status determined
 - [ ] Deferred items filtered against later milestone phases (if gaps found)
 - [ ] Fix plans generated (if gaps_found after filtering)
+- [ ] Falsification pass run and `falsification:` recorded whenever status is `passed`
+- [ ] Production reachability checked for every delivered non-UI module (importers classified production vs test; inline re-implementations named)
 - [ ] VERIFICATION.md created with complete report
+- [ ] Phase marked complete in state.json via `phase complete` when status is `passed` (write-back confirmed, not assumed)
 - [ ] Results returned to orchestrator
 </success_criteria>
 

package/server/dashboard.js

@@ -25,7 +25,7 @@ const path    = require('path');
 const fs      = require('fs');
 const os      = require('os');
 const crypto  = require('crypto');
-const { spawn } = require('child_process');
+const { fork } = require('child_process');
 
 // Client JS modules live here and are served verbatim at /js/<name>.js
 const CLIENT_DIR = path.join(__dirname, 'lib', 'html', 'client');
@@ -33,12 +33,17 @@ const CLIENT_DIR = path.join(__dirname, 'lib', 'html', 'client');
 const { scanState } = require('./lib/scanner');
 const { handleApiState, handleApiFiles, handleApiFile, handleApiHierarchy, handleApiMemory, handleApiAgents } = require('./lib/api');
 const { renderHtml } = require('./lib/html/shell');
+const { isViewOnly } = require('./lib/view-only');
 
 // ---------- Configuration ----------
 let PORT = parseInt(process.env.PORT || '7717', 10);
-// #969 — the orchestrator's actual port, injected into the client so it never
-// has to hardcode 7718. Defaults match orchestrator.js's own default.
-const ORCH_PORT = parseInt(process.env.ORCH_PORT || '7718', 10);
+// #1037 — the orchestrator's actual port is NOT known until the child process
+// reports back over IPC that it bound successfully (see spawnOrchestrator()).
+// null means "no orchestrator is currently running for this dashboard" — the
+// client must render orchestration as disabled rather than guess a port.
+// NEVER default this to a constant like 7718: that constant may be another
+// project's dashboard's orchestrator.
+let orchPort = null;
 const RCODE_DIR = process.env.RCODE_DIR || path.join(process.cwd(), '.rcode');
 const PROJECT_ROOT = path.dirname(RCODE_DIR);
 // Fallback root for agent prompts when rcode is installed as a package (not run
@@ -150,7 +155,7 @@ function handleRequest(req, res) {
       return;
     }
     res.writeHead(200, { 'Content-Type': 'application/json' });
-    res.end(JSON.stringify({ token: ORCH_TOKEN, orchPort: ORCH_PORT }));
+    res.end(JSON.stringify({ token: ORCH_TOKEN, orchPort, projectRoot: PROJECT_ROOT }));
     return;
   }
 
@@ -181,7 +186,12 @@ function handleRequest(req, res) {
 
   if (url === '/' || url === '/index.html') {
     const state = scanState(RCODE_DIR);
-    const html = renderHtml(state, ORCH_TOKEN, ORCH_PORT);
+    // #967 — hide Run/Stop/Clean affordances in view-only mode. This is a UI
+    // convenience only; the actual refusal happens server-side in
+    // orchestrator.js's POST /api/run handler regardless of this flag.
+    // #1037 — orchPort (not ORCH_PORT) so we never advertise an orchestrator
+    // this process did not spawn; null renders orchestration as disabled.
+    const html = renderHtml(state, ORCH_TOKEN, orchPort, PROJECT_ROOT, isViewOnly(PROJECT_ROOT));
     res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-cache' });
     res.end(html);
     return;
@@ -215,9 +225,14 @@ server.listen(PORT, '127.0.0.1', () => {
   console.log(`   Mode:          live (read + orchestration)`);
   console.log(`   Scanning:      ${RCODE_DIR}`);
   console.log(`   Refresh:       30s soft poll`);
-  console.log(`   Note:          port ${PORT + 1} is the internal orchestrator API — not for the browser`);
+  console.log(`   Note:          the orchestrator (internal API, not for the browser) starts scanning near port ${PORT + 1}`);
   console.log(`   Stop:          kill $(ss -ltnp 'sport = :${PORT}' | awk 'NR>1{match($6,/pid=([0-9]+)/,m); print m[1]}')`);
   console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`);
+  // #1037 — spawn the orchestrator only now that PORT has SETTLED (any
+  // EADDRINUSE retries above have already run their course by the time this
+  // 'listening' callback fires). Spawning it earlier would derive its port
+  // from a PORT value that might still change underneath it.
+  ensurePty(spawnOrchestrator);
 });
 
 // ── Ensure interactive-terminal native module is present ─────────
@@ -242,16 +257,32 @@ function ensurePty(done) {
   done();
 }
 
-// ── Auto-spawn orchestrator (port 7718) ──────────────────────────
+// ── Auto-spawn orchestrator ───────────────────────────────────────
+// #1037 — the orchestrator's port is derived from THIS dashboard's own final
+// bound PORT (never a hardcoded constant), and the orchestrator runs its own
+// free-port scan rather than exiting on the first conflict (see
+// orchestrator.js's listen/retry block). We fork() (not spawn()) so the child
+// gets an IPC channel: it reports back the port it actually bound once
+// listening succeeds, or an error if its scan is exhausted. Until that
+// message arrives, `orchPort` stays null and the dashboard advertises
+// orchestration as disabled — it must never guess a port it did not spawn.
 const ORCH_BIN = path.join(__dirname, 'orchestrator.js');
 let _orchProc = null;
 
 function spawnOrchestrator() {
+  orchPort = null;
   try {
-    _orchProc = spawn(process.execPath, [ORCH_BIN], {
+    _orchProc = fork(ORCH_BIN, [], {
       cwd: path.join(__dirname, '..'),
-      env: { ...process.env, ORCH_TOKEN, RCODE_DIR, PROJECT_ROOT, DASH_PORT: String(PORT) },
-      stdio: 'pipe',
+      env: {
+        ...process.env,
+        ORCH_TOKEN, RCODE_DIR, PROJECT_ROOT,
+        DASH_PORT: String(PORT),
+        // Respect an explicit user override; otherwise start the orchestrator's
+        // own scan right after this dashboard's actual port.
+        ORCH_PORT: process.env.ORCH_PORT || String(PORT + 1),
+      },
+      silent: true,
     });
     _orchProc.stdout.on('data', chunk => {
       const msg = chunk.toString().trim();
@@ -261,12 +292,23 @@ function spawnOrchestrator() {
       const msg = chunk.toString().trim();
       if (msg && !msg.includes('no stdin')) console.error('[orch]', msg);
     });
+    _orchProc.on('message', msg => {
+      if (!msg || typeof msg !== 'object') return;
+      if (msg.type === 'orch-ready' && Number.isInteger(msg.port)) {
+        orchPort = msg.port;
+        console.log(`[orch] orchestrator ready (port ${orchPort})`);
+      } else if (msg.type === 'orch-error') {
+        orchPort = null;
+        console.log(`[orch] orchestrator failed to bind (${msg.reason}) — orchestration disabled for this dashboard.`);
+      }
+    });
     _orchProc.on('exit', (code, signal) => {
       _orchProc = null;
+      orchPort = null; // never keep advertising a port nothing is listening on
       if (signal !== 'SIGTERM' && signal !== 'SIGINT') {
         if (code === 2) {
-          // Port-conflict exit — don't loop. Dashboard stays fully functional.
-          console.log(`[orch] orchestrator port already in use — not restarting. Set ORCH_PORT=<N> env var to use a different port. Dashboard is still functional.`);
+          // Port-conflict exit (scan exhausted) — don't loop. Dashboard stays functional.
+          console.log(`[orch] orchestrator could not find a free port — not restarting. Set ORCH_PORT=<N> env var to use a different range. Dashboard is still functional.`);
           return;
         }
         console.log(`[orch] exited (${code}) — restarting in 3s…`);
@@ -276,16 +318,14 @@ function spawnOrchestrator() {
     _orchProc.on('error', err => {
       console.error('[orch] spawn error:', err.message);
       _orchProc = null;
+      orchPort = null;
     });
-    console.log(`[orch] orchestrator started (port ${ORCH_PORT})`);
   } catch (err) {
     console.error('[orch] failed to start:', err.message);
+    orchPort = null;
   }
 }
 
-// Orchestrator spawns only once node-pty is settled (present or installed).
-ensurePty(spawnOrchestrator);
-
 // Graceful shutdown
 function shutdown() {
   if (_orchProc) { try { _orchProc.kill('SIGTERM'); } catch {} }

package/server/lib/html/client/components/OrchPanel.js

@@ -15,7 +15,7 @@
 
 import { html, useState, useEffect, useRef, useCallback } from '../preact.js';
 import { useStore, setState } from '../store.js';
-import { orchToken, stopSession, cleanSessions, orchWs } from '../orchestrator.js';
+import { orchToken, stopSession, cleanSessions, orchWs, isOrchAvailable, projectRoot } from '../orchestrator.js';
 import { showToast } from './shared.js';
 import { Icon } from '../icons-client.js';
 
@@ -105,9 +105,13 @@ export function OrchPanel() {
       showToast('No orchestrator token — restart the dashboard');
       return;
     }
+    if (!isOrchAvailable()) {
+      showToast('Orchestration is disabled — no orchestrator is running for this project');
+      return;
+    }
     const ws = new WebSocket(
       orchWs() + '/ws/' + encodeURIComponent(storyId) +
-      '?token=' + encodeURIComponent(tok)
+      '?token=' + encodeURIComponent(tok) + '&root=' + encodeURIComponent(projectRoot())
     );
     _streams[storyId] = ws;
 

package/server/lib/html/client/components/XtermPanel.js

@@ -25,7 +25,7 @@
 
 import { html, useEffect, useRef, useCallback } from '../preact.js';
 import { useStore, setState } from '../store.js';
-import { orchToken, stopSession, orchWs } from '../orchestrator.js';
+import { orchToken, stopSession, orchWs, isOrchAvailable, projectRoot } from '../orchestrator.js';
 
 // ── Internal state (module-scoped, one panel at a time) ──────────────────────
 // These are NOT component state because the xterm instance (and the story it
@@ -103,8 +103,13 @@ function connectWs(storyId) {
     if (_term) _term.writeln('\r\n\x1b[31m✗ No orchestrator token — restart the dashboard\x1b[0m');
     return;
   }
+  if (!isOrchAvailable()) {
+    if (_term) _term.writeln('\r\n\x1b[31m✗ Orchestration is disabled — no orchestrator is running for this project\x1b[0m');
+    return;
+  }
   setStatus('connecting');
-  const url = orchWs() + '/ws/' + encodeURIComponent(storyId) + '?token=' + encodeURIComponent(tok);
+  const url = orchWs() + '/ws/' + encodeURIComponent(storyId) +
+    '?token=' + encodeURIComponent(tok) + '&root=' + encodeURIComponent(projectRoot());
   const ws = new WebSocket(url);
   _termWs = ws;