@ai-dev-methodologies/rlp-desk 0.13.1 → 0.14.0

package/README.md

@@ -238,7 +238,7 @@ When all US pass individually, the final ALL verify runs **sequentially per-US**
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `--mode agent\|tmux` | agent | agent=LLM Leader, tmux=shell Leader |
+| `--mode agent\|tmux` | agent | tmux=zsh Leader (stable, production), agent=Node Leader (alpha) |
 | `--worker-model MODEL` | haiku | Worker model. `name`=claude, `name:reasoning`=codex |
 | `--lock-worker-model` | off | Disable auto model upgrade on failure |
 | `--verifier-model MODEL` | sonnet | per-US verification model (lighter) |
@@ -277,10 +277,17 @@ The brainstorm phase evaluates complexity (US count, file scope, logic, dependen
 
 RLP Desk supports two execution modes. Both honor the same governance protocol.
 
+> **v0.14.0 status:** `--mode tmux` (zsh-backed) is the **stable, production** path
+> with the full safety net (heartbeat, copy-mode guard, prompt-stall timeout,
+> no-progress detection, claude model upgrade chain). `--mode agent` is **alpha**
+> and ships without those features — the runner emits a stderr warning when
+> agent mode is invoked. For long campaigns and BOS-style autonomous loops,
+> use `--mode tmux`.
+
 ### Environment Compatibility
 
-| Environment | Agent Mode | Tmux Mode |
-|-------------|-----------|-----------|
+| Environment | Agent Mode (alpha) | Tmux Mode (stable) |
+|-------------|--------------------|--------------------|
 | Claude Code (any terminal) | **Works** | Requires tmux |
 | Inside tmux session | **Works** | **Works** — panes split in current window |
 | Outside tmux session | **Works** | **Rejected** — "start tmux first" |
@@ -289,9 +296,9 @@ RLP Desk supports two execution modes. Both honor the same governance protocol.
 
 | Need | Use |
 |------|-----|
-| Reliable autonomous loop (no interruption) | `--mode tmux` |
-| Interactive development, quick tasks | `--mode agent` (default) |
-| Long campaigns, CI, overnight runs | `--mode tmux` |
+| Production / autonomous campaigns | `--mode tmux` (stable) |
+| Long campaigns, CI, overnight runs | `--mode tmux` (stable) |
+| Quick interactive exploration inside Claude Code | `--mode agent` (alpha — Node-native) |
 
 ### Agent Mode (default) — "Smart Mode"
 

package/docs/plans/spicy-booping-galaxy.md

@@ -1,8 +1,181 @@
-# Plan — Claude worker `.claude/` sensitive prompt hang 수정
+# Plan — v0.14.0 Recovery: 원래 의도대로 동작 회복 (zsh primary for tmux)
+
+> **상위 우선순위 plan. 아래 v0.13.0 plan은 history reference로 보존.**
+> **Trigger**: 사용자 평가 — "rlp-desk가 못 쓸 폐급, 통제 불가능 수준". v0.13.0/v0.13.1 fix는 빙산 일각.
+> **Target version**: 0.14.0
+> **승인된 strategy**: 경로 A (zsh restoration as tmux primary; Node leader는 `--mode agent`만 담당)
+
+---
+
+## A. Context (v0.14.0)
+
+### 문제 진단
+
+2026-04-12 Node port 시점부터 v0.13.x까지, **Node leader가 zsh runner의 핵심 안전망 11개를 누락한 채 ship**. 사용자(BOS) 평가는 "통제 불가능". v0.13.0/v0.13.1 patch는 다음 2개만 해결:
+1. `.claude/` sensitive prompt hang
+2. detached session UX 회귀
+
+**여전히 누락된 것** (file:line 인용):
+| # | 기능 | zsh location | Node 상태 |
+|---|------|--------------|----------|
+| 1 | Copy-mode 가드 send-keys | `safe_send_keys` L976-1083 | 없음 (pane-manager.mjs:50-53 단순 send-keys) |
+| 2 | Heartbeat 주기적 쓰기 + staleness 감지 | L1735-1750, L1158 | 없음 |
+| 3 | No-progress 10분 byte-stasis 감지 | `check_no_progress` L2372-2420 | 없음 |
+| 4 | Prompt-stall 5분 timeout | `check_prompt_stall` L2298-2370 | 없음 |
+| 5 | Stale-context 3 consecutive unchanged iter | `check_stale_context` lib L1162-1179 | 없음 |
+| 6 | Claude 모델 upgrade chain (haiku→sonnet→opus) | `get_next_model` lib L136-155 | 없음 (codex chain만) |
+| 7 | LOCK_WORKER_MODEL flag 처리 | lib L197 | 없음 |
+| 8 | Codex update prompt auto-dismiss | L1007-1011 | 없음 |
+| 9 | Pane lifecycle cleanup | `cleanup_panes` L3310-3320 | 없음 (`_ensureTerminalSentinel` 부분만) |
+| 10 | 사용자 pane-kill graceful detection | L134-150 | 없음 |
+| 11 | Cleanup trap (C-c → /exit → kill-pane) | L1864-2014 | 부분만 |
+
+### 핵심 결정
+
+**zsh를 tmux mode primary path로 복원, Node leader는 `--mode agent`(LLM-driven orchestration) 단독 담당**.
+
+**근거**:
+- zsh runner는 v0.12.0 deprecation 전까지 6주+ production 검증.
+- Node port의 누락 11개를 모두 port = 5-7일 + 새 회귀 위험. zsh 복원 = 1-2일 + 검증된 코드.
+- Node leader는 LLM이 worker/verifier를 spawn하는 agent mode에 고유 가치 — tmux 기계적 orchestration은 zsh가 더 잘함.
+- 사용자 즉시 회복 우선.
+
+---
+
+## B. Approach (6 Phases)
+
+### Phase 1 — zsh deprecation 게이트 해제 (Day 1, 2시간)
+
+**파일**: `src/scripts/run_ralph_desk.zsh`
+- L69-90: `--flywheel`/`--with-self-verification`/`--flywheel-guard` hard-reject 블록 제거. zsh가 이 flag들을 다시 honor.
+- L91 "deprecated" 메시지 제거.
+- `RALPH_DESK_VERSION` 0.14.0으로 갱신.
+
+### Phase 2 — Node `--mode tmux` → zsh subprocess 라우팅 (Day 1, 4시간)
+
+**파일**: `src/node/run.mjs`
+- `parseRunOptions()` 후 `runRunCommand()` 진입에서 `mode === 'tmux'` 분기:
+  - `~/.claude/ralph-desk/run_ralph_desk.zsh` 경로 확인 (postinstall이 sync 보장).
+  - 모든 옵션을 env vars로 변환 (`LOOP_NAME`, `WORKER_MODEL`, `FLYWHEEL`, `FLYWHEEL_GUARD`, `WITH_SELF_VERIFICATION`, `MAX_ITER`, `ITER_TIMEOUT`, `CB_THRESHOLD`, `CONSENSUS_*`, `LOCK_WORKER_MODEL` 등).
+  - `child_process.spawn('zsh', [zshPath], { env, stdio: 'inherit' })`로 위임.
+  - exit code 그대로 propagate.
+- legacy detection (`detectLegacyDeskInRunMode`) 호출은 zsh spawn 전에 유지.
+- claude+tmux warning 유지 (zsh도 같은 worker engine 분기에서 적용).
+
+**파일**: `src/node/runner/campaign-main-loop.mjs`
+- `run()` 진입에서 `options.mode === 'tmux'`일 때 가드: `throw new Error('tmux mode is delegated to zsh — invoke via run.mjs router')`. dead-code 표시 + 회귀 방지.
+
+### Phase 3 — postinstall + install.sh가 zsh를 항상 sync (Day 1, 1시간)
+
+**파일**: `scripts/postinstall.js`
+- 현재 `legacyFiles` 배열로 zsh 3개 삭제 → **유지·sync로 변경**.
+- `runtimeSources`에 `src/scripts/{init,run,lib}_ralph_desk.zsh` → `~/.claude/ralph-desk/` 추가 (또는 `scripts/` 하위 — install.sh와 일관성 결정).
+- banner-aware sync.
+
+**파일**: `tests/node/us008-cli-entrypoint.test.mjs:47`
+- 기존 "removes legacy zsh scripts" 테스트 invert: zsh 3개가 install 후 존재 + spawnable 검증.
+
+### Phase 4 — Node `--mode agent` 라벨링 (Day 2, 2시간)
+
+**파일**: `src/node/run.mjs`, `src/commands/rlp-desk.md`, `README.md`
+- `--mode agent` 진입 시 stderr 경고: "agent mode is alpha — for production use --mode tmux".
+- README mode 표:
+  - `tmux` (stable, zsh-backed)
+  - `agent` (alpha, Node-native)
+- v0.13.0/0.13.1 fix(`.claude/` 마이그레이션, prompt-detector, claude+tmux warning)는 모두 agent mode에서 잔존 — Node 단독 가치 보존.
+
+### Phase 5 — 검증 시나리오 (Day 2-3, 1일)
+
+**Self-verification gate (`tests/sv-self-verify-0.14.sh`)** — v0.13 시나리오 + 신규:
+- L5.1 (CRITICAL) BOS 회귀: claude worker + tmux mode + 1 iter 완주 (실제 tmux session 생성, kill-session cleanup).
+- L5.2 (CRITICAL) zsh subprocess routing: `--mode tmux` 호출이 `child_process.spawn('zsh', ...)`로 위임됐는지 mock 검증.
+- L5.3 (CRITICAL) flag → env var conversion 단언 (모든 supported flag 1개씩).
+- L5.4 (MEDIUM) zsh deprecation 게이트 제거 검증 (L69-90).
+- L5.5 (MEDIUM) postinstall이 zsh 3개를 install (us008 invert).
+- L5.6 (MEDIUM) `--mode agent` warning 출력 검증.
+- L5.7 (UX) attached tmux 안에서 leader+worker+verifier panes 사용자 현재 window에 표시 (zsh L815-823 동작).
+
+### Phase 6 — Ship (Day 3)
+
+CLAUDE.md release workflow 그대로:
+1. self-verification gate 17/17 PASS.
+2. ralplan + codex review (기존 mandate).
+3. version bump 0.14.0.
+4. CHANGELOG: "Restore zsh as primary tmux runner. Node tmux delegates to validated zsh codepath. Node agent mode marked alpha."
+5. commit + push + gh release + npm publish.
+6. local sync banner-aware verify.
+
+---
+
+## C. v0.13.x에서 보존되는 것
+
+- `.claude/ralph-desk/` → `.rlp-desk/` 경로 마이그레이션 (init mode auto-mv, run mode 안내) — zsh도 v0.13.0에서 이미 반영됨.
+- `RLP_DESK_RUNTIME_DIR` env override.
+- prompt-detector + signal-poller permission_prompt 감지 — agent mode 전용.
+- BLOCK_TAGS.PERMISSION_PROMPT 상수.
+- claude+tmux warning (run.mjs 진입 시).
+
+---
+
+## D. v0.15.0+ 점진 port 백로그 (deferred)
+
+**P0 (2주 내, agent mode parity 위해)**:
+- heartbeat 메커니즘
+- copy-mode 가드 send-keys
+- prompt-stall 5분 timeout
+- no-progress 10분 byte-stasis
+
+**P1**:
+- stale-context 감지
+- claude 모델 upgrade chain (haiku→sonnet→opus)
+- LOCK_WORKER_MODEL flag
+
+**P2**:
+- codex update prompt auto-dismiss
+- pane lifecycle cleanup
+- user-kill graceful detection
+- cleanup trap full parity
+
+---
+
+## E. Critical Files
+
+```
+src/scripts/run_ralph_desk.zsh          # Phase 1 — deprecation 게이트 해제
+src/scripts/lib_ralph_desk.zsh          # 변경 없음 (zsh helpers 그대로)
+src/scripts/init_ralph_desk.zsh         # 변경 없음 (v0.13.0 마이그레이션 그대로)
+src/node/run.mjs                        # Phase 2 — tmux mode 라우터
+src/node/runner/campaign-main-loop.mjs  # Phase 2 — tmux mode 가드
+scripts/postinstall.js                  # Phase 3 — zsh sync 복원
+tests/node/us008-cli-entrypoint.test.mjs # Phase 3 — invert
+src/commands/rlp-desk.md                # Phase 4 — mode 표 갱신
+README.md                                # Phase 4 — stable/alpha 표시
+package.json                             # Phase 6 — 0.14.0
+tests/sv-self-verify-0.14.sh             # Phase 5 — 신규 SV gate
+```
+
+---
+
+## F. 검증 (E2E)
+
+1. **BOS 회귀 (CRITICAL)**: BOS 프로젝트 worktree에서 `node ~/.claude/ralph-desk/node/run.mjs run bos-phase-1 --mode tmux --worker-model sonnet --max-iter 1 --iter-timeout 600` → tmux session 생성, leader/worker/verifier panes 사용자 현재 window에 split, 1 iter sentinel write 성공, no permission prompt hang.
+2. **Local sync**: `npm install` 후 `~/.claude/ralph-desk/run_ralph_desk.zsh` 존재 + banner.
+3. **Backward compat**: v0.13.x mid-campaign 사용자 — `mv .claude/ralph-desk .rlp-desk` 안내 그대로.
+
+---
+
+## G. 기각된 대안
+
+- **B (Node 전면 port)**: 11 features × 평균 3시간 + parity 회귀테스트 = 5-7일 + 신규 버그 위험. v0.15.0+ 점진 port로 deferred.
+- **C (단독 라벨링)**: experimental 라벨만으로는 "통제 불가능" 즉시 해소 불가. 경로 A에 흡수.
+
+---
+
+# v0.13.0 (HISTORY) — Claude worker `.claude/` sensitive prompt hang 수정
 
 > **Source bug report**: `/Users/kyjin/dev/doul/bos/docs/exec-plans/active/2026-05-01-rlp-desk-bug-report.md`
 > **Severity**: HIGH — `--mode tmux` + `--worker-model sonnet/haiku/opus` 조합에서 모든 campaign blocking
-> **Target version**: 0.13.0 (breaking — project-local sentinel 경로 이동)
+> **Target version**: 0.13.0 (breaking — project-local sentinel 경로 이동) — **SHIPPED**, but coverage was a sliver of the real failure surface (see v0.14.0 plan above).
 
 ---
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ai-dev-methodologies/rlp-desk",
-  "version": "0.13.1",
-  "description": "Fresh-context iterative loops for Claude Code \u2014 autonomous task completion with independent verification",
+  "version": "0.14.0",
+  "description": "Fresh-context iterative loops for Claude Code — autonomous task completion with independent verification",
   "scripts": {
     "postinstall": "node scripts/postinstall.js",
     "uninstall": "node scripts/uninstall.js",
@@ -46,4 +46,4 @@
   "engines": {
     "node": ">=16"
   }
-}
+}

package/scripts/postinstall.js

@@ -19,6 +19,14 @@ const runtimeSources = [
   ["src/model-upgrade-table.md", path.join(deskDir, "model-upgrade-table.md")],
   ["README.md", path.join(deskDir, "README.md")],
   ["install.sh", path.join(deskDir, "install.sh")],
+  // v0.14.0: zsh runner is the canonical --mode tmux backend again.
+  // src/node/run.mjs spawns it as a subprocess for tmux mode invocations.
+  // injectBannerAndLock preserves the shebang and adds a `# DO NOT EDIT`
+  // line on line 2 so the verification scripts in CLAUDE.md still
+  // recognize the file as installed.
+  ["src/scripts/init_ralph_desk.zsh", path.join(deskDir, "init_ralph_desk.zsh")],
+  ["src/scripts/run_ralph_desk.zsh", path.join(deskDir, "run_ralph_desk.zsh")],
+  ["src/scripts/lib_ralph_desk.zsh", path.join(deskDir, "lib_ralph_desk.zsh")],
   // v5.7 §4.15: all rlp-desk docs (user-facing + dev meta) under docs/rlp-desk/.
   ["docs/rlp-desk/architecture.md", path.join(docsDir, "rlp-desk", "architecture.md")],
   ["docs/rlp-desk/getting-started.md", path.join(docsDir, "rlp-desk", "getting-started.md")],
@@ -26,11 +34,12 @@ const runtimeSources = [
   ["docs/rlp-desk/TODO-verification-next.md", path.join(docsDir, "rlp-desk", "TODO-verification-next.md")],
   ["docs/rlp-desk/multi-mission-orchestration.md", path.join(docsDir, "rlp-desk", "multi-mission-orchestration.md")],
 ];
-const legacyFiles = [
-  path.join(deskDir, "init_ralph_desk.zsh"),
-  path.join(deskDir, "run_ralph_desk.zsh"),
-  path.join(deskDir, "lib_ralph_desk.zsh"),
-];
+// v0.14.0: legacy-deletion list cleared. The Node-canonical era (v5.7+)
+// removed zsh after install; v0.14.0 reverts that — the zsh runner is the
+// production --mode tmux path. Keep the empty array so the surrounding loop
+// (`for (const legacyFile of legacyFiles)`) remains a no-op without churning
+// the call site.
+const legacyFiles = [];
 
 function getNodeVersion() {
   return process.env.RLP_DESK_NODE_VERSION_OVERRIDE || process.version;

package/scripts/uninstall.js

@@ -20,6 +20,11 @@ const files = [
   path.join(deskDir, "model-upgrade-table.md"),
   path.join(deskDir, "README.md"),
   path.join(deskDir, "install.sh"),
+  // v0.14.0: zsh tmux runner is part of the install set again — clean it up
+  // on uninstall so users do not end up with orphaned 0o444 files.
+  path.join(deskDir, "init_ralph_desk.zsh"),
+  path.join(deskDir, "run_ralph_desk.zsh"),
+  path.join(deskDir, "lib_ralph_desk.zsh"),
 ];
 
 for (const targetPath of files) {

package/src/commands/rlp-desk.md

@@ -278,9 +278,18 @@ Cross-project aggregation: scan `~/.claude/ralph-desk/analytics/` and read each
 
 Parse the `--mode` flag. If absent or `agent`, use the Agent() path below. If `tmux`, use the Tmux path.
 
+> **v0.14.0 stability tiers:**
+> - `--mode tmux` is the **stable, production** path. The Node leader (`run.mjs`)
+>   now routes tmux invocations to `~/.claude/ralph-desk/run_ralph_desk.zsh`
+>   as a subprocess — that runner has the full safety net (heartbeat,
+>   copy-mode guard, prompt-stall, no-progress detection, claude model
+>   upgrade chain). Recommend this for autonomous campaigns.
+> - `--mode agent` is **alpha** (Node-native LLM-driven Leader). The runner
+>   emits a stderr warning when this mode is invoked.
+
 #### Tmux Mode (`--mode tmux`)
 
-When `--mode tmux` is specified (v0.12.0+ — v5.7 §4.1 routes to Node leader for flywheel + SV support):
+When `--mode tmux` is specified (v0.14.0+: `run.mjs` accepts the same flags as before but spawns `run_ralph_desk.zsh` as a subprocess and inherits stdio. Flywheel and self-verification flags are not honored under tmux mode — they require `--mode agent`):
 
 1. **Validate scaffold** — same as Agent() mode: check `.rlp-desk/prompts/<slug>.worker.prompt.md` etc.
 2. **Check sentinels** — same as Agent() mode.
@@ -322,9 +331,8 @@ node ~/.claude/ralph-desk/node/run.mjs run '<slug>' \
 - MUST launch with `run_in_background: true` so `/rlp-desk` returns control immediately while preserving live tmux visibility.
 - Run-in-background is used so the shell can keep the command visible and keep the pane layout stable for status checks and completion flow.
 - Do NOT kill panes after completion. Panes stay alive for inspection. User cleans up with `/rlp-desk clean <slug> --kill-session`.
-- `--with-self-verification` is fully supported in tmux mode (v5.7 §4.7). The Node leader's `generateSVReport()` writes `self-verification-report.md` + `self-verification-data.json` under `<project>/.claude/ralph-desk/analytics/<slug>/` (project-local, v5.7 §4.11.b).
-- `--flywheel on-fail` and `--flywheel-guard on` are fully supported in tmux mode (v5.7 §4.1). The Node leader handles pane creation, sendKeys dispatch, signal polling, and Guard retry semantics identically to agent mode.
-- Legacy `zsh ~/.claude/ralph-desk/run_ralph_desk.zsh` (deprecated in 0.12.0) still runs for non-flywheel/non-SV invocations but emits a deprecation `[notice]`. Calling it with `FLYWHEEL` or `WITH_SELF_VERIFICATION` env vars exits 2 with a migration banner pointing to the Node leader.
+- v0.14.0: `--with-self-verification`, `--flywheel`, and `--flywheel-guard` are **not honored** under `--mode tmux` — the zsh runner has no SV/flywheel implementation. The Node leader emits a stderr WARNING listing the dropped flags. For SV/flywheel, use `--mode agent` (alpha).
+- The slash command always invokes `node ~/.claude/ralph-desk/node/run.mjs run --mode tmux ...`. Do NOT invoke `~/.claude/ralph-desk/run_ralph_desk.zsh` directly — the Node router resolves the runner path, runs legacy detection, and surfaces actionable errors when the runner is missing.
 
 **tmux UX model (5 items):**
 - The session returns immediately after launch (`run_in_background: true`) so the command returns control to the parent CLI.
@@ -333,7 +341,13 @@ node ~/.claude/ralph-desk/node/run.mjs run '<slug>' \
 - On completion, the command returns a completion notification before the loop ends.
 - Agent mode remains unchanged, and no tmux-specific behavior is mixed into Agent mode.
 
-#### Agent Mode (`--mode agent` or default)
+#### Agent Mode (`--mode agent` or default — **alpha**)
+
+> **v0.14.0:** Agent mode is the alpha LLM-driven path. The Node port shipped
+> without zsh-equivalent safety nets (heartbeat, copy-mode guard, prompt-stall
+> timeout, no-progress detection, claude model upgrade chain). The runner
+> emits a stderr WARNING when agent mode is invoked. For production
+> autonomous campaigns, prefer `--mode tmux`.
 
 **Why Agent mode is structurally immune to Bug 4/5 (mid-execution prompt hang
 & A4 premature dispatch):** Worker/Verifier are dispatched as `Agent(...,

package/src/node/run.mjs

@@ -1,9 +1,15 @@
+import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
+import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
 import { initCampaign } from './init/campaign-initializer.mjs';
 import { readStatus } from './reporting/campaign-reporting.mjs';
-import { run as runCampaignMain } from './runner/campaign-main-loop.mjs';
+import {
+  run as runCampaignMain,
+  detectLegacyDeskInRunMode,
+} from './runner/campaign-main-loop.mjs';
 import { isClaudeEngine } from './cli/command-builder.mjs';
 
 const RUN_DEFAULTS = {
@@ -211,6 +217,102 @@ async function runStatusCommand(args, deps) {
   return 0;
 }
 
+// v0.14.0: Default location of the zsh runner installed by postinstall.js
+// (Phase 3 of the v0.14.0 plan re-enables this sync). Overridable via
+// RLP_DESK_ZSH_RUNNER for development checkouts that point to src/scripts.
+function defaultZshRunnerPath() {
+  return (
+    process.env.RLP_DESK_ZSH_RUNNER
+    || path.join(os.homedir(), '.claude', 'ralph-desk', 'run_ralph_desk.zsh')
+  );
+}
+
+// v0.14.0: convert parsed CLI options to env vars consumed by run_ralph_desk.zsh.
+// Names mirror the variables declared in src/scripts/run_ralph_desk.zsh
+// (LOOP_NAME, ROOT, WORKER_MODEL, VERIFIER_MODEL, FINAL_VERIFIER_MODEL,
+// MAX_ITER, ITER_TIMEOUT, CB_THRESHOLD, VERIFY_MODE, CONSENSUS_MODE,
+// CONSENSUS_MODEL, FINAL_CONSENSUS_MODEL, LOCK_WORKER_MODEL, AUTONOMOUS_MODE,
+// LANE_MODE, TEST_DENSITY_MODE).
+function buildZshEnv(slug, options, parentEnv) {
+  return {
+    ...parentEnv,
+    LOOP_NAME: slug,
+    ROOT: options.rootDir,
+    WORKER_MODEL: options.workerModel,
+    VERIFIER_MODEL: options.verifierModel,
+    FINAL_VERIFIER_MODEL: options.finalVerifierModel,
+    MAX_ITER: String(options.maxIterations),
+    ITER_TIMEOUT: String(options.iterTimeout),
+    CB_THRESHOLD: String(options.cbThreshold),
+    VERIFY_MODE: options.verifyMode,
+    CONSENSUS_MODE: options.consensusMode,
+    CONSENSUS_MODEL: options.consensusModel,
+    FINAL_CONSENSUS_MODEL: options.finalConsensusModel,
+    LOCK_WORKER_MODEL: options.lockWorkerModel ? '1' : '0',
+    AUTONOMOUS_MODE: options.autonomous ? '1' : '0',
+    LANE_MODE: options.laneStrict ? 'strict' : 'warn',
+    TEST_DENSITY_MODE: options.testDensityStrict ? 'strict' : 'warn',
+  };
+}
+
+// v0.14.0: default tmux-mode delegate. Spawns the zsh runner inheriting stdio
+// so the operator sees pane orchestration in real time. Resolves with the
+// child exit code (or 1 on spawn error) to keep the caller deterministic.
+function defaultSpawnZsh(zshPath, env, cwd) {
+  return new Promise((resolve) => {
+    const child = spawn('zsh', [zshPath], { env, stdio: 'inherit', cwd });
+    child.on('error', (err) => {
+      process.stderr.write(`failed to spawn zsh runner: ${err.message}\n`);
+      resolve(1);
+    });
+    child.on('exit', (code, signal) => {
+      if (signal) {
+        resolve(128 + (typeof signal === 'string' ? 0 : signal));
+        return;
+      }
+      resolve(typeof code === 'number' ? code : 0);
+    });
+  });
+}
+
+async function runTmuxViaZsh(slug, options, deps) {
+  // v0.13.0 legacy detection still applies — the zsh runner shares the same
+  // .rlp-desk/ contract, so a stray .claude/ralph-desk/ left over from an
+  // older campaign must be migrated by the operator before we hand off.
+  const legacy = detectLegacyDeskInRunMode(options.rootDir, process.env);
+  if (legacy) {
+    write(deps.stderr, legacy.message);
+    return 1;
+  }
+
+  const zshPath = (deps.zshRunnerPath ?? defaultZshRunnerPath)();
+  if (!deps.fileExists(zshPath)) {
+    write(
+      deps.stderr,
+      `ERROR: zsh runner not found at ${zshPath}. Run \`npm install rlp-desk\` (or set RLP_DESK_ZSH_RUNNER) to sync.`,
+    );
+    return 1;
+  }
+
+  // Surface flags the zsh runner cannot honor. Flywheel and self-verification
+  // remain Node-leader features, available only in --mode agent. Warn loudly
+  // instead of silent no-op so the operator understands the trade-off.
+  const unsupported = [];
+  if (options.flywheel !== 'off') unsupported.push('--flywheel');
+  if (options.flywheelGuard !== 'off') unsupported.push('--flywheel-guard');
+  if (options.withSelfVerification) unsupported.push('--with-self-verification');
+  if (unsupported.length > 0) {
+    write(
+      deps.stderr,
+      `WARNING: ${unsupported.join(', ')} not honored in --mode tmux (zsh runner). Use --mode agent for those features.`,
+    );
+  }
+
+  const env = buildZshEnv(slug, options, process.env);
+  const spawnZsh = deps.spawnZsh ?? defaultSpawnZsh;
+  return spawnZsh(zshPath, env, options.rootDir);
+}
+
 async function runRunCommand(args, deps) {
   if (args.length === 0) {
     throw new Error('run requires a slug');
@@ -250,6 +352,27 @@ async function runRunCommand(args, deps) {
     );
   }
 
+  // v0.14.0: --mode tmux delegates to the zsh runner. Node leader keeps
+  // ownership of --mode agent only (LLM-driven orchestration).
+  if (options.mode === 'tmux') {
+    return runTmuxViaZsh(slug, options, deps);
+  }
+
+  // v0.14.0: agent mode is the alpha LLM-driven path. The Node port shipped
+  // without zsh-equivalent safety nets (heartbeat, copy-mode guard,
+  // prompt-stall timeout, no-progress detection, claude model upgrade chain).
+  // Surface that explicitly so production users pick --mode tmux instead.
+  if (
+    options.mode === 'agent'
+    && !process.env.RLP_DESK_QUIET_WARNINGS
+    && process.env.NODE_ENV !== 'test'
+  ) {
+    write(
+      deps.stderr,
+      'WARNING: --mode agent is alpha. For production tmux orchestration, prefer --mode tmux (zsh-backed, stable).',
+    );
+  }
+
   const result = await deps.runCampaign(slug, options);
   // governance §1f BLOCKED Surfacing: surface the blocked reason on stderr so
   // the operator (or wrapper script) does not have to grep memo files.
@@ -273,6 +396,13 @@ export async function main(argv = process.argv.slice(2), overrides = {}) {
     initCampaign: overrides.initCampaign ?? initCampaign,
     readStatus: overrides.readStatus ?? readStatus,
     runCampaign: overrides.runCampaign ?? runCampaignMain,
+    // v0.14.0: --mode tmux delegate. Tests inject `spawnZsh` to assert the
+    // env mapping without actually fork+exec'ing zsh. `fileExists` and
+    // `zshRunnerPath` are similarly injectable so a test can pretend the
+    // installed runner is or isn't present.
+    spawnZsh: overrides.spawnZsh,
+    zshRunnerPath: overrides.zshRunnerPath,
+    fileExists: overrides.fileExists ?? ((p) => fs.existsSync(p)),
   };
 
   try {

package/src/node/runner/campaign-main-loop.mjs

@@ -949,6 +949,12 @@ export function shouldRunGuard(flywheelGuard, state, usId) {
   return true;
 }
 
+// v0.14.0: production --mode tmux is routed to the zsh runner by
+// src/node/run.mjs (see runTmuxViaZsh). The Node leader below owns the
+// --mode agent (LLM-driven) flow. In-tree tests still exercise this path
+// with `mode: 'tmux'` as a label while injecting fake
+// createSession/sendKeys/pollForSignal — that is intentional and is NOT a
+// regression of the routing contract.
 export async function run(slug, options = {}) {
   const rootDir = path.resolve(options.rootDir ?? process.cwd());
   const env = options.env ?? process.env;