@hanzlaa/rcode 4.4.4 → 4.6.0

package/rcode/data/intent-table.json

@@ -1,87 +1,87 @@
 [
   {
     "intent": "new-project",
-    "keywords": ["set up a new project", "initialize a new project", "start a new project", "create a new project"],
+    "keywords": ["set up a new project", "initialize a new project", "start a new project", "create a new project", "naya project shuru karo", "naya project banao", "مشروع جديد", "ابدأ مشروع جديد"],
     "command": "/rcode-new-project"
   },
   {
     "intent": "map-codebase",
-    "keywords": ["map the codebase", "map this codebase", "analyze the codebase", "analyse the codebase", "map existing codebase"],
+    "keywords": ["map the codebase", "map this codebase", "analyze the codebase", "analyse the codebase", "map existing codebase", "codebase samjhao", "code ka structure dikhao", "حلل الكود", "افهم هيكل المشروع"],
     "command": "/rcode-map-codebase"
   },
   {
     "intent": "debug",
-    "keywords": ["bug", "getting an error", "throwing an error", "error in the", "fix the error", "debug this", "crash", "failure", "broken", "not working", "fails", "exception", "traceback"],
+    "keywords": ["bug", "getting an error", "throwing an error", "error in the", "fix the error", "debug this", "crash", "failure", "broken", "not working", "fails", "exception", "traceback", "kharab", "masla", "ye kaam nahi kar raha", "yeh kaam nahi kar raha", "error a raha hai", "theek karo", "khud se crash", "خطأ", "مشكلة", "لا يعمل", "أصلح الخطأ", "تعطل البرنامج"],
     "command": "/rcode-debug"
   },
   {
-    "intent": "audit-karpathy",
-    "keywords": ["audit", "review changes", "check my diff", "karpathy", "too complex", "complexity", "code review"],
-    "command": "/rcode-review --karpathy"
+    "intent": "karpathy-audit",
+    "keywords": ["review changes", "check my diff", "karpathy", "too complex", "complexity", "diff check karo", "پیچیدہ کوڈ", "تحقق من التغييرات"],
+    "command": "/rcode-karpathy-audit"
   },
   {
     "intent": "lazy",
-    "keywords": ["be lazy", "lazy mode", "simplest solution", "yagni", "over-engineered", "over-engineering", "kam code likho"],
+    "keywords": ["be lazy", "lazy mode", "simplest solution", "yagni", "over-engineered", "over-engineering", "kam code likho", "asaan tareeqa", "سهل الحل", "أبسط طريقة"],
     "command": "/rcode-lazy"
   },
   {
     "intent": "checkpoint",
-    "keywords": ["checkpoint", "explain this diff", "human review", "walk through the change", "walk through this change"],
+    "keywords": ["checkpoint", "explain this diff", "human review", "walk through the change", "walk through this change", "diff samjhao", "اشرح هذا التغيير"],
     "command": "/rcode-checkpoint-preview"
   },
   {
     "intent": "brainstorm",
-    "keywords": ["brainstorm", "generate ideas", "explore options", "what could we do", "ideate", "ideas for"],
+    "keywords": ["brainstorm", "generate ideas", "explore options", "what could we do", "ideate", "ideas for", "ideas do", "hum kya kar sakte hain", "أفكار", "ما الذي يمكننا فعله"],
     "command": "/rcode-brainstorm"
   },
   {
     "intent": "explore",
-    "keywords": ["explore", "research phase", "do some research", "comparing", "investigate", "look into", "understand how"],
+    "keywords": ["explore", "research phase", "do some research", "comparing", "investigate", "look into", "understand how", "research karo", "pata karo", "ابحث عن", "قارن بين"],
     "command": "/rcode-research-phase"
   },
   {
     "intent": "discuss",
-    "keywords": ["which one", "better ux", "how should", "still have confusion", "conflicting", "discuss the scope", "design this", "architect this"],
+    "keywords": ["which one", "better ux", "how should", "still have confusion", "conflicting", "discuss the scope", "design this", "architect this", "confusion hai", "kaunsa behtar hai", "أيهما أفضل", "لست متأكداً"],
     "command": "/rcode-discuss-phase"
   },
   {
     "intent": "add-phase",
-    "keywords": ["refactor", "migration", "multi-file", "system redesign", "multi file", "large refactor", "architectural", "integration", "integrate"],
+    "keywords": ["refactor", "migration", "multi-file", "system redesign", "multi file", "large refactor", "architectural", "integration", "integrate", "poora refactor karo", "migration karna hai", "إعادة هيكلة", "ترحيل النظام"],
     "command": "/rcode-add-phase"
   },
   {
     "intent": "sprint-planning",
-    "keywords": ["sprint planning", "plan the sprint", "next sprint", "what's in this sprint"],
+    "keywords": ["sprint planning", "plan the sprint", "next sprint", "what's in this sprint", "sprint plan karo", "تخطيط السبرنت"],
     "command": "/rcode-sprint-planning"
   },
   {
     "intent": "execute-sprint",
-    "keywords": ["run the sprint", "start sprint", "execute sprint", "work on sprint"],
+    "keywords": ["run the sprint", "start sprint", "execute sprint", "work on sprint", "sprint chalao", "sprint shuru karo", "نفذ السبرنت", "ابدأ السبرنت"],
     "command": "/rcode-execute-sprint"
   },
   {
     "intent": "plan",
-    "keywords": ["let's plan", "plan phase", "plan this", "let me plan", "planning phase", "create a plan", "please plan", "plan and think", "scope this", "scope the feature"],
+    "keywords": ["let's plan", "plan phase", "plan this", "let me plan", "planning phase", "create a plan", "please plan", "plan and think", "scope this", "scope the feature", "plan banao", "isko plan karo", "خطط لهذا", "أنشئ خطة"],
     "command": "/rcode-plan"
   },
   {
     "intent": "new-milestone",
-    "keywords": ["create milestones", "plan milestones", "create roadmap", "break project into milestones", "new milestone", "what milestones"],
+    "keywords": ["create milestones", "plan milestones", "create roadmap", "break project into milestones", "new milestone", "what milestones", "milestones banao", "خطة الطريق", "مراحل المشروع"],
     "command": "/rcode-new-milestone"
   },
   {
     "intent": "epics-stories",
-    "keywords": ["create epics", "user stories", "create stories", "epics and stories", "break into epics"],
+    "keywords": ["create epics", "user stories", "create stories", "epics and stories", "break into epics", "stories banao", "قصص المستخدم", "أنشئ ملاحم"],
     "command": "/rcode-create-epics-and-stories"
   },
   {
     "intent": "feature-drift",
-    "keywords": ["out of date", "out-of-date", "verify docs", "audit feature docs", "fill out existing", "prd drift", "docs vs code"],
+    "keywords": ["out of date", "out-of-date", "verify docs", "audit feature docs", "fill out existing", "prd drift", "docs vs code", "docs purane hain", "الوثائق قديمة", "تحقق من التوثيق"],
     "command": "/rcode-feature-drift"
   },
   {
     "intent": "audit",
-    "keywords": ["re-audit", "extend the audit", "fill out the", "expand the", "re audit"],
+    "keywords": ["re-audit", "extend the audit", "fill out the", "expand the", "re audit", "audit", "code review", "dobara audit karo", "audit karo", "code review karo", "دقق الكود", "مراجعة الكود", "راجع التغييرات"],
     "command": "/rcode-audit"
   }
 ]

package/rcode/skills/agents/mariam-marketing/SKILL.md

@@ -88,6 +88,7 @@ Five named heuristics. Cite by name when reasoning:
 - **Never claim market readiness from < 4 disconfirmable signals.** Three customers is a focus group at best.
 - **Never write a launch plan** without a 90-day proof point AND the kill criterion.
 - **Never speculate on market data without WebSearch.** "unknown — would need 1 hour of research" is a valid answer.
+- **Grounding rule (mandatory):** any pricing, fee, rate, market-size, or regulation claim MUST be verified with WebSearch/WebFetch in-session, or explicitly tagged `[unverified — training data]`.
 - **Never write PRDs / user stories / architecture decisions.** Stay in the GTM lane.
 - Brand consistency over clever campaigns
 

package/rcode/skills/agents/sadiq-analyst/SKILL.md

@@ -84,6 +84,7 @@ State the rule by name when refusing.
 - **Never accept urgency manufactured by sales pressure** without independent market signal. Get the LOI in writing first.
 - **Never make a strategic call under context-switch pressure.** If the user is tired or mid-fire, defer. Bad strategy at midnight is worse than no strategy.
 - **Never write code, PRDs, or research reports.** Strategy directors set bets and kill switches; that's the deliverable.
+- **Grounding rule (mandatory):** any pricing, fee, rate, market-size, or regulation claim MUST be verified with WebSearch/WebFetch in-session, or explicitly tagged `[unverified — training data]`.
 
 ## In Round 2 (council follow-ups)
 

package/rcode/skills/agents/waleed-architect/SKILL.md

@@ -86,6 +86,7 @@ State the rule by name when refusing.
 - **Never propose "rewrite from scratch"** without a measurable pain point AND a parallel-run migration plan. Joel Spolsky test: if you can't write the migration plan in 200 words, the rewrite is wrong-shaped.
 - **Never recommend bleeding-edge tech** for systems with multi-year lifetime expectations. Beta dependencies are a Reversibility-test fail.
 - **Never write production code** in your responses. ADRs and decision matrices only. Code goes to Yousef / Hanzla / Omar / Haitham.
+- **Grounding rule (mandatory):** any pricing, fee, rate, market-size, or regulation claim MUST be verified with WebSearch/WebFetch in-session, or explicitly tagged `[unverified — training data]`.
 
 ## Capabilities
 

package/rcode/templates/memory/INDEX.md

@@ -1,6 +1,8 @@
 # Memory Bank — `{{PROJECT_NAME}}`
 
-> The Memory Bank is your project's persistent brain. AI agents read from here on every session. You write to it as work happens. Survives session resets, team changes, and AI memory limits.
+> The Memory Bank is your project's persistent brain. Full read/write access is on-demand: run `/rcode-memory-init` to scaffold it, `/rcode-memory-update` after work happens, `/rcode-memory-distill` to regenerate the compressed distillates, and `/rcode-memory-audit` to check it for staleness. Ambient injection also runs automatically (#958): the `session-start` hook emits its usual one-line phase-status primer from `.rcode/state.json`, then — when this directory exists and has content — a relevance-ranked selector (`rcode/bin/lib/memory-select.cjs`) scores every file here against the current phase, git branch, and recently touched files, and injects the top-scoring excerpts as `additionalContext` within a ~1500-token budget (override via `.rcode/config.yaml`'s `memory_inject_budget`). The `pre-compact` hook does the same with a smaller ~600-token budget as part of its survival context. This keeps agents grounded in relevant memory without a human having to run a `/rcode-memory-*` command first — full manual review is still the way to go deep.
+>
+> A `post-commit` hook runs a lightweight drift check after every commit (#958): it compares `project/stack.md` and `project/decisions.md` claims against the last 10 commits and the current working tree — removed/added dependencies, referenced files/dirs that no longer exist, and an `INDEX.md` older than 30 days. If it finds anything, it nudges you toward `/rcode-memory-update` once per session. Run `rcode-hooks drift` (or `node .rcode/bin/rcode-hooks.cjs drift` if the CLI isn't on your PATH) anytime for the full report.
 
 **Last updated:** {{INIT_DATE}}
 
@@ -27,6 +29,8 @@
 
 ## Token budget guide
 
+- **Ambient session-start injection** (~1.5K tokens, `memory_inject_budget`) — automatic, relevance-ranked, no command needed
+- **Ambient pre-compact injection** (~600 tokens) — automatic survival context alongside `HANDOFF.json`
 - **`INDEX.md` only** (~500 tokens) — quick orientation
 - **`INDEX.md` + `distillates/project.distillate.md`** (~5K tokens) — standard session start
 - **Full `project/` directory** (~10–15K tokens) — deep planning
@@ -39,6 +43,7 @@
 - **`incidents/known-issues.md`** — add when a workaround ships, remove when a real fix lands
 - **`distillates/`** — regenerate via `/rcode-memory-distill` when source files change
 - **Whole bank** — audit via `/rcode-memory-audit` at every milestone close
+- **Drift check** — runs automatically on every commit; run `rcode-hooks drift` manually anytime, or after a large dependency/refactor change
 
 ## Constraints
 

package/rcode/templates/settings-hooks.json

@@ -1,5 +1,5 @@
 {
-  "_comment": "pre-edit hook is currently advisory (logs warning, does not block). Full session-read tracking requires PostToolUse Read hook to write state file. Implemented in follow-up. prompt-router (UserPromptSubmit) is advisory — emits additionalContext to nudge toward the right rcode command; never blocks.",
+  "_comment": "pre-edit hook is currently advisory (logs warning, does not block). Full session-read tracking requires PostToolUse Read hook to write state file. Implemented in follow-up. prompt-router (UserPromptSubmit) is advisory — emits additionalContext to nudge toward the right rcode command; never blocks. session-start (SessionStart) emits a one-line project status primer at session open.",
   "hooks": {
     "PreToolUse": [
       {
@@ -85,6 +85,17 @@
           }
         ]
       }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .rcode/bin/rcode-hooks.cjs session-start"
+          }
+        ]
+      }
     ]
   }
 }

package/rcode/workflows/council.md

@@ -240,6 +240,16 @@ Do NOT skip this step. A council that answers market questions from training dat
    Constraints: <regulatory, geographic, or operational limits>
 ```
 
+3. **MANDATORY ARTIFACT GATE — write the Research context block to disk before spawning any panelist.** This file is the enforcement mechanism: its existence on disk is what proves live research ran, not just prose claiming it did.
+
+```bash
+mkdir -p "{paths.sessions_dir}"
+RESEARCH_FILE="{paths.sessions_dir}/$(date +%Y%m%d-%H%M%S)-research.md"
+# Write the "Research context" block above (verbatim) to $RESEARCH_FILE
+```
+
+Do NOT proceed to Step 3 (panel selection) until `$RESEARCH_FILE` exists on disk with the Research context block written into it. Step 4 (spawn) and Step 5 (synthesis) both depend on this file existing.
+
 Also run the minimal codebase scan (config.yaml + README only) so subagents know the team's current capabilities:
 
 ```bash
@@ -282,6 +292,8 @@ Use the AskUserQuestion tool (not raw stdin) for the confirmation.
 
 For each agent id in `panel`, build this prompt. **Before embedding, sanitize the question:** strip any literal `Task(`, `Agent(`, `subagent_type=`, or `system:` tokens that could be misinterpreted as tool calls by the sub-agent (replace with `[filtered]`). This is a low-severity guard — the user already has full access, but it prevents accidental or malicious prompt confusion.
 
+**For research-typed questions (`market`/`discovery`/`greenfield`):** `{the summary block}` below MUST be the verbatim content of `$RESEARCH_FILE` written in Step 2's artifact gate — not a paraphrase, not a re-summary. Every panelist reads the same grounded facts.
+
 ```
 You are being spawned as part of a rcode council session.
 
@@ -289,7 +301,7 @@ You are being spawned as part of a rcode council session.
 {sanitized_question}
 
 ## Observed context
-{the summary block from Step 1 — codebase scan OR research context depending on question_type}
+{the summary block from Step 1 — codebase scan OR the verbatim $RESEARCH_FILE content for research-typed questions}
 
 ## Session metadata
 - Project: {config.project_name}
@@ -384,6 +396,14 @@ to resolve or strategic ambiguity to explore.
 
 ## Step 5 — Present responses
 
+**Grounding gate (research-typed questions only):** For `market`/`discovery`/`greenfield` questions, before printing anything else, verify `$RESEARCH_FILE` from Step 2 exists on disk (`test -f "$RESEARCH_FILE"`). If it is missing — the research pre-step was skipped or failed silently — open the verdict output (both compact and verbose modes) with this banner as the very first line, before the `COUNCIL VERDICT` header:
+
+```
+⚠ UNGROUNDED — answered from model knowledge, no live research ran
+```
+
+Do NOT silently proceed as if research happened. This banner is mandatory whenever the file is missing for a research-typed question; it is never shown for `codebase`/`frontend`/`backend`/etc. questions where no research file is expected.
+
 Before saving any artifact, print the panel output inline. Two modes:
 
 ### Default mode (compact summary)
@@ -417,6 +437,9 @@ Format:
 **Orchestrator note**
 {max 2 sentences — sharpest remaining disagreement OR clearest convergent action}
 
+**Data freshness**
+{N} claims live-verified (sources: {comma-separated source names/URLs}) / {M} claims from model knowledge
+
 📄 Full transcripts: {artifact path}
 ```
 
@@ -425,6 +448,7 @@ Rules for compact mode:
 - Convergence table: 2-5 rows, only axes where panelists take a stance. Cells ≤ 6 words.
 - Round 2 deltas: ≤ 15 words each. "Held position" is a valid delta.
 - No section headers beyond the four above. No numbered story breakdowns. No tables from panelists verbatim.
+- **Data freshness footer is mandatory on every synthesis**, not just research-typed questions. Count claims across all panelist responses: a claim is "live-verified" if it cites a source found via WebSearch/WebFetch in this session (Step 2's research file, or a panelist's own in-session lookup); everything else — including anything tagged `[unverified — training data]` by a panelist — counts toward "from model knowledge". For non-research question types with no external claims, use `0 claims live-verified / 0 from model knowledge — no external claims made`.
 
 ### Verbose mode (`--verbose` flag or `output.verbose: true` in config)
 
@@ -449,6 +473,8 @@ Print Round 1 (and Round 2 if ran) verbatim in panel order. Do NOT summarize.
 
 ---
 **Orchestrator Note:** {max 3 sentences}
+
+**Data freshness:** {N} claims live-verified (sources) / {M} claims from model knowledge
 ```
 
 Before presenting, load the commit format reference:
@@ -575,6 +601,8 @@ node .rcode/bin/rcode-tools.cjs state record-session
 - [ ] Round 2 cross-talk executed (unless consensus or agent deferred)
 - [ ] Session artifact written to `.planning/council-sessions/council-{date}-{slug}.md`
 - [ ] State updated with session record and timestamp
+- [ ] For research-typed questions (`market`/`discovery`/`greenfield`): `$RESEARCH_FILE` written before spawn, or ⚠ UNGROUNDED banner shown
+- [ ] Data freshness footer included in synthesis output
 
 ## On Error
 

package/rcode/workflows/do.md

@@ -290,7 +290,7 @@ Evaluate `$QUESTION` against these routing rules. Apply the **first matching** r
 | A bug, error, crash, failure, or something broken | `/rcode-debug` | Needs systematic investigation |
 | Validate an idea, "working backwards", "press release", "PRFAQ", "is this worth building" | `/rcode-prfaq` | Stress-test concept before committing sprint capacity |
 | Brainstorm, generate ideas, "explore options", "what could we do" | `/rcode-brainstorm` | Structured ideation before planning |
-| Audit code quality, "review changes", "karpathy", "check my diff", "too complex" | `/rcode-review --karpathy` | 4-principle code audit against recent diff |
+| "karpathy", "review changes", "check my diff", "too complex" — 4-principle code audit against a diff | `/rcode-karpathy-audit` | Runs the karpathy-audit workflow directly (review.md has no `--karpathy` flag) |
 | Make it simpler, "be lazy", "lazy mode", "simplest solution", "yagni", "over-engineered", "kam code likho" | `/rcode-lazy` | Generative simplicity lens — YAGNI before code is written (rcode-trim removes bloat after the fact) |
 | Walk through a change, "checkpoint", "explain this diff", "human review" | `/rcode-checkpoint-preview` | Human-in-the-loop diff walkthrough |
 | Exploring, researching, comparing, or "how does X work" | `/rcode-research-phase` | Domain research before planning |
@@ -317,7 +317,7 @@ Evaluate `$QUESTION` against these routing rules. Apply the **first matching** r
 | Adding tests, "write tests", "test coverage" | `/rcode-add-tests` | Test generation |
 | Completing a milestone, shipping, releasing | `/rcode-complete-milestone` | Milestone lifecycle |
 | Drift / out-of-date / "verify docs vs code" / "audit feature docs" / "fill out existing PRD/epics/stories" | `/rcode-feature-drift` | Detects PRD↔epics↔stories↔code drift; --fix patches trivial items |
-| General audit / re-audit / extend / fill out / expand an existing artifact | `/rcode-audit` | Unified audit entry — picks artifact type and re-runs |
+| Bare "audit" / "code review" / re-audit / extend / fill out / expand an existing artifact | `/rcode-audit` | Unified audit entry — disambiguates plans/phase/milestone/UAT/code before dispatching |
 > **SEO route guard:** Skills in this block assume a project context exists (`.planning/PROJECT.md`). If absent, the `HAS_PRD` check in `<step name="check_project">` redirects to `/rcode-new-project`.
 
 | **— SEO / Content intent —** | | |

package/rcode/workflows/enable-hooks.md

@@ -1,7 +1,7 @@
 # Workflow: rcode-enable-hooks
 
 <purpose>
-Merge rcode opt-in hooks from settings-hooks.json into .claude/settings.json. Creates settings.json if missing. Enables all 9 guardrails: pre-edit (read-before-edit check), pre-workflow (command hint), post-commit (format validation), bash-guard (blocks dangerous commands), pre-compact (refreshes HANDOFF.json before context compaction), stop-verify (syntax-checks files changed during the response), cost-track (logs measured token usage to .rcode/telemetry/cost.jsonl), compact-nudge (advises /rcode-trim or /clear after many edits), and prompt-router (proactive nudge toward the right rcode command for long-term memory consistency).
+Merge rcode opt-in hooks from settings-hooks.json into .claude/settings.json. Creates settings.json if missing. Enables all 10 guardrails: pre-edit (read-before-edit check), pre-workflow (command hint), post-commit (format validation), bash-guard (blocks dangerous commands), pre-compact (refreshes HANDOFF.json before context compaction), stop-verify (syntax-checks files changed during the response), cost-track (logs measured token usage to .rcode/telemetry/cost.jsonl), compact-nudge (advises /rcode-trim or /clear after many edits), prompt-router (proactive nudge toward the right rcode command for long-term memory consistency), and session-start (SessionStart — one-line project status primer at session open).
 </purpose>
 
 
@@ -44,7 +44,7 @@ If `.claude/` directory does not exist, create it first.
 
 ## Step 3 — Merge hooks
 
-For each hook type (`PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`, `UserPromptSubmit`):
+For each hook type (`PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`, `UserPromptSubmit`, `SessionStart`):
 
 - If the hook type does not exist in the current settings.json, add it.
 - If it exists, append the new matchers and hook commands (avoid duplicates by checking for exact command matches).
@@ -87,6 +87,7 @@ Enabled guardrails:
   • cost-track: Logs measured token usage to .rcode/telemetry/cost.jsonl
   • compact-nudge: Advises /rcode-trim or /clear after many edits
   • prompt-router: Nudges toward the matching /rcode-* command and /rcode-memory-update so work lands in .rcode/state.json (toggle via prompt_nudge in .rcode/config.yaml: every|once-per-intent|when-stale|off)
+  • session-start: Greets the session with one-line phase status and suggested next command
 
 To disable, remove the hooks section from .claude/settings.json or edit .rcode/templates/settings-hooks.json and re-run.
 ```

package/rcode/workflows/new-project-roadmap.md

@@ -302,12 +302,12 @@ Use AskUserQuestion:
 node .rcode/bin/rcode-tools.cjs generate-claude-md
 ```
 
-This ensures new projects get the default rcode workflow-enforcement guidance and current project context in `CLAUDE.md`.
+This ensures new projects get the default rcode workflow-enforcement guidance and current project context in `CLAUDE.md` and `AGENTS.md` (the cross-tool standard read by Codex, Cursor, Windsurf, Antigravity, and Gemini). `AGENTS.md` is only written when absent — an install-managed roster section is preserved.
 
 **Commit roadmap (after approval or auto mode):**
 
 ```bash
-node .rcode/bin/rcode-tools.cjs commit "docs: create roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md CLAUDE.md
+node .rcode/bin/rcode-tools.cjs commit "docs: create roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md CLAUDE.md AGENTS.md
 ```
 
 ## 9. Done

package/server/dashboard.js

@@ -36,6 +36,9 @@ const { renderHtml } = require('./lib/html/shell');
 
 // ---------- Configuration ----------
 const 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);
 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
@@ -147,7 +150,7 @@ function handleRequest(req, res) {
       return;
     }
     res.writeHead(200, { 'Content-Type': 'application/json' });
-    res.end(JSON.stringify({ token: ORCH_TOKEN }));
+    res.end(JSON.stringify({ token: ORCH_TOKEN, orchPort: ORCH_PORT }));
     return;
   }
 
@@ -178,7 +181,7 @@ function handleRequest(req, res) {
 
   if (url === '/' || url === '/index.html') {
     const state = scanState(RCODE_DIR);
-    const html = renderHtml(state, ORCH_TOKEN);
+    const html = renderHtml(state, ORCH_TOKEN, ORCH_PORT);
     res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-cache' });
     res.end(html);
     return;
@@ -257,7 +260,7 @@ function spawnOrchestrator() {
       console.error('[orch] spawn error:', err.message);
       _orchProc = null;
     });
-    console.log('[orch] orchestrator started (port 7718)');
+    console.log(`[orch] orchestrator started (port ${ORCH_PORT})`);
   } catch (err) {
     console.error('[orch] failed to start:', err.message);
   }

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

@@ -304,7 +304,7 @@ export function App() {
         />
       </div>
 
-      <${XtermPanel} />
+      <${XtermPanel} suspend=${view === 'orchestration'} />
       <${OrchPanel} />
       <${BlockedToasts} />
       <${RunnerPicker} />

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, ORCH_WS } from '../orchestrator.js';
+import { orchToken, stopSession, cleanSessions, orchWs } from '../orchestrator.js';
 import { showToast } from './shared.js';
 import { Icon } from '../icons-client.js';
 
@@ -106,7 +106,7 @@ export function OrchPanel() {
       return;
     }
     const ws = new WebSocket(
-      ORCH_WS + '/ws/' + encodeURIComponent(storyId) +
+      orchWs() + '/ws/' + encodeURIComponent(storyId) +
       '?token=' + encodeURIComponent(tok)
     );
     _streams[storyId] = ws;

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

@@ -9,18 +9,34 @@
  *
  * Store field: state.terminal = { open, storyId, title, minimized, fullscreen }
  * Setting state.terminal via orchestrator.js triggers this component.
+ *
+ * Two mount points, one singleton terminal:
+ *   - App.js mounts one instance as a floating overlay (backdrop + sliding
+ *     panel + minimized pill) on every view.
+ *   - OrchestrationView.js mounts a second instance with `docked=true` to
+ *     embed the SAME xterm.js Terminal inline in its right column.
+ * Only one instance may touch the DOM at a time — App.js passes
+ * `suspend=${view === 'orchestration'}` so its overlay instance goes fully
+ * inert (renders null, effects no-op) while Orchestration's docked instance
+ * is mounted. `ensureTerm()` reparents the shared xterm DOM node into
+ * whichever container asks for it, so the buffer/connection survive the
+ * hand-off in both directions.
  */
 
 import { html, useEffect, useRef, useCallback } from '../preact.js';
 import { useStore, setState } from '../store.js';
-import { orchToken, stopSession, ORCH_WS } from '../orchestrator.js';
+import { orchToken, stopSession, orchWs } from '../orchestrator.js';
 
 // ── Internal state (module-scoped, one panel at a time) ──────────────────────
-// These refs are NOT component state because the xterm instance must persist
-// across panel open/close cycles and Preact re-renders.
-let _term    = null;
-let _termFit = null;
-let _termWs  = null;
+// These are NOT component state because the xterm instance (and the story it
+// is currently connected to) must persist across panel open/close cycles,
+// Preact re-renders, and — now — across the two XtermPanel mount points
+// (floating overlay vs. docked). Component-local refs would not be shared
+// between those two instances.
+let _term          = null;
+let _termFit       = null;
+let _termWs        = null;
+let _currentStory  = null;
 
 function setStatus(dotStatus) {
   // Propagate connection status via a store signal so the pill/header can react
@@ -34,9 +50,23 @@ function _resize() {
   }
 }
 
-/** Build the xterm instance exactly once; attach to `containerEl`. */
+/**
+ * Build the xterm instance exactly once; attach to `containerEl`.
+ * If the instance already exists but lives under a DIFFERENT container
+ * (e.g. the overlay panel had it, and the docked panel is now asking), move
+ * its root DOM node into `containerEl` instead of no-oping. xterm.js's root
+ * element is a plain DOM node — reparenting it is safe and preserves the
+ * scrollback buffer and any live WebSocket connection.
+ */
 function ensureTerm(containerEl) {
-  if (_term || typeof Terminal === 'undefined') return;
+  if (_term) {
+    if (_term.element && _term.element.parentElement !== containerEl) {
+      containerEl.appendChild(_term.element);
+      if (_termFit) { try { _termFit.fit(); } catch (_e) {} }
+    }
+    return;
+  }
+  if (typeof Terminal === 'undefined') return;
   _term = new Terminal({
     theme: {
       background: '#0c0c0e', foreground: '#c9d1d9',
@@ -74,7 +104,7 @@ function connectWs(storyId) {
     return;
   }
   setStatus('connecting');
-  const url = ORCH_WS + '/ws/' + encodeURIComponent(storyId) + '?token=' + encodeURIComponent(tok);
+  const url = orchWs() + '/ws/' + encodeURIComponent(storyId) + '?token=' + encodeURIComponent(tok);
   const ws = new WebSocket(url);
   _termWs = ws;
 
@@ -98,10 +128,9 @@ function connectWs(storyId) {
 
 // ── Component ─────────────────────────────────────────────────────────────────
 
-export function XtermPanel() {
+export function XtermPanel({ docked = false, suspend = false } = {}) {
   const { terminal, termStatus } = useStore();
   const containerRef = useRef(null);
-  const currentStoryRef = useRef(null);
 
   const t = terminal || {};
   const open       = !!t.open;
@@ -110,28 +139,37 @@ export function XtermPanel() {
   const storyId    = t.storyId || '';
   const title      = t.title   || 'Terminal';
 
-  // Build xterm instance on first open; reconnect when storyId changes.
-  // The resize listener is registered here (not inside ensureTerm) so the
-  // cleanup return can mirror it on unmount.
+  // Build/attach the xterm instance on open; (re)connect only when the
+  // focused storyId actually changes. `_currentStory` is module-scoped (not
+  // a per-instance ref) so that handing the terminal off between the
+  // floating overlay and the docked panel — same storyId, different
+  // container — reparents via ensureTerm() without tearing down the
+  // connection or clearing the buffer. `suspend` is in the dep array so the
+  // OTHER (un-suspending) instance re-runs this effect and reclaims the
+  // terminal DOM node when the user navigates away from Orchestration.
   useEffect(() => {
-    if (!open || !containerRef.current) return;
+    if (suspend || !open || !containerRef.current) return;
     ensureTerm(containerRef.current);
-    if (_term) { _term.clear(); _resize(); }
-    if (storyId && storyId !== currentStoryRef.current) {
-      currentStoryRef.current = storyId;
+    const isNewSession = storyId && storyId !== _currentStory;
+    if (isNewSession) {
+      _currentStory = storyId;
+      if (_term) _term.clear();
       connectWs(storyId);
     }
+    _resize();
     window.addEventListener('resize', _resize);
     return () => window.removeEventListener('resize', _resize);
-  }, [open, storyId]);
+  }, [open, storyId, suspend]);
 
   // Resize when entering/leaving fullscreen or on open
   useEffect(() => {
-    if (open) { setTimeout(_resize, 50); }
-  }, [open, fullscreen]);
+    if (!suspend && open) { setTimeout(_resize, 50); }
+  }, [open, fullscreen, suspend]);
 
-  // Escape key closes
+  // Escape key closes (docked panel has no "close" concept — it just shows
+  // the empty state when store.terminal is cleared elsewhere)
   useEffect(() => {
+    if (suspend || docked) return;
     function onKey(e) {
       if (e.key === 'Escape' && open && !minimized) {
         setState({ terminal: { ...t, open: false } });
@@ -139,9 +177,11 @@ export function XtermPanel() {
     }
     window.addEventListener('keydown', onKey);
     return () => window.removeEventListener('keydown', onKey);
-  }, [open, minimized, t]);
+  }, [open, minimized, t, suspend, docked]);
 
   const dotCls = 'term-status-dot ' + (termStatus || '');
+  // Statuses that mean "output is actively streaming" for the docked live pulse.
+  const isLive = open && ['running', 'connecting', 'blocked', 'waiting'].includes(termStatus);
 
   // ── Actions ──
   const handleMinimize = useCallback(() => {
@@ -167,6 +207,41 @@ export function XtermPanel() {
     setTimeout(_resize, 50);
   }, [t, fullscreen]);
 
+  // Fully inert while the sibling instance owns the terminal DOM — no
+  // backdrop, no panel, no pill, nothing rendered at all.
+  if (suspend) return null;
+
+  // ── Docked render (Orchestration view's right column) ──
+  if (docked) {
+    return html`
+      <div class="orch-term-dock">
+        <div class="orch-term-dock-header">
+          <span class="orch-term-dot red"></span>
+          <span class="orch-term-dot amber"></span>
+          <span class="orch-term-dot green"></span>
+          <span class="orch-term-dock-label">xterm${open ? ' · ' + title : ''}</span>
+          ${isLive ? html`
+            <span class="orch-term-dock-live">
+              <span class="orch-term-dock-live-dot"></span>live
+            </span>
+          ` : null}
+          ${open ? html`
+            <button class="orch-term-dock-stop" onClick=${handleStop} title="End the agent session">Stop</button>
+          ` : null}
+        </div>
+        <div class="orch-term-dock-body">
+          ${open
+            ? html`<div ref=${containerRef} class="orch-term-dock-container"></div>`
+            : html`
+              <div class="orch-term-dock-empty">
+                No active execution. Select a command from the Runner picker to begin.
+              </div>
+            `}
+        </div>
+      </div>
+    `;
+  }
+
   // ── Pill (minimized state) ──
   const pill = html`
     <div