@ai-dev-methodologies/rlp-desk 0.15.0 → 0.15.1

package/docs/plans/native-agent-revert.md

@@ -0,0 +1,184 @@
+# Native Agent() Revert Plan (P0+P1)
+
+6-round ralplan consensus 결과. Goal: slash command(`src/commands/rlp-desk.md`)가 진짜 leader가 되어 Claude Code Agent() 호출 + Bash codex exec로 worker/verifier를 spawn하는 v0.13.x 이전 방식으로 회귀. `--mode tmux`(zsh runner) 경로 미변경.
+
+## Scope
+
+- **P0**: Bug #7 fix 단독 commit + 명시적 invariant ADR
+- **P1**: slash command native prose 회복 + `--mode native` 도입 + Node CLI `--mode agent` deprecation banner
+- **Out-of-scope**: P2 (Node CLI default flip, `--mode agent` hard-error), P3 (Node leader 삭제 ~4.5k LOC + repo-wide ghost-removal gate). 19th launch 종료 후 별도 PR.
+
+## Principles
+
+1. Naming truth: `--mode agent`라는 flag 하나가 두 곳에서 다른 의미를 가지는 상태 해소.
+2. Single leader per mode.
+3. Surgical revert: tmux 경로 + 19th launch 영향 0.
+4. Bug #7 fix preservation: zsh side에 invariant 보존됨을 ADR로 명시.
+5. Reversibility: silent reclaim 없음. `--mode agent` (Node CLI)는 호환 유지하면서 deprecation warning만.
+
+## P0 — Bug #7 fix commit + Invariant ADR
+
+### a. Bug #7 fix commit
+- 현재 working tree (5 src + 4 untracked tests + 1 plan markdown) 단독 commit
+- Local sync는 이미 완료(`~/.claude/ralph-desk/` chmod 0o444 + banner)
+
+### b. ADR `docs/adr/0001-bug7-invariant-zsh-only-by-structural-necessity.md`
+
+명시적 scope:
+- Bug #7 invariant는 **slash-command Native Agent() / Bash codex exec path**에 한정해 **zsh runner side에 enforce**된다.
+- Native Agent() path는 short-lived per-call subagent — long-lived TUI process가 없어 동일 race를 가지지 않는다.
+- Node CLI `--mode agent`(Node leader, deprecated alpha)는 long-lived tmux pane을 사용 → 동일 race 보유. P3에서 삭제될 때까지 별도 reaper/lock 코드(`src/node/runner/campaign-main-loop.mjs:1091`, `:1577`, `src/node/tmux/pane-manager.mjs`, `src/node/shared/fs.mjs`) 유지.
+- zsh side invariant 인용 (codex critic verified file:line):
+  - `src/scripts/lib_ralph_desk.zsh:248` — helpers (`_kill_pane_process`, `_lock_sentinel`, `_unlock_sentinel`)
+  - `src/scripts/run_ralph_desk.zsh:2179` — partial-write `jq -e .` validity gate
+  - `src/scripts/run_ralph_desk.zsh:2484` — verifier reap+lock (per-US main path)
+  - `src/scripts/run_ralph_desk.zsh:2551` — final-verify per-US reap+lock
+  - `src/scripts/run_ralph_desk.zsh:2969` — prep cleanup unlock
+  - `src/scripts/run_ralph_desk.zsh:3036` — worker reap+lock
+  - `src/scripts/run_ralph_desk.zsh:3247` — verifier reap+lock (consensus)
+
+### c. re-sync
+- `node scripts/postinstall.js`
+- banner-aware diff: src ⇆ `~/.claude/ralph-desk/`
+
+### Acceptance
+- AC0.1 `git log -1`이 Bug #7 fix
+- AC0.2 ADR file 존재 + 위 7 file:line 인용 + scope 명문
+- AC0.3 `bash tests/test-bug7-post-sentinel-race.sh` + `bash tests/test-bug7-poll-partial-write.sh` 통과
+- AC0.4 Node 315/315 통과
+- AC0.5 banner-aware diff src ⇆ install 일치
+
+## P1 — Slash native prose + `--mode native` + Node CLI deprecation
+
+### a. `src/commands/rlp-desk.md` audit list (전체)
+
+| Line | 현재 | 변경 후 |
+|---|---|---|
+| 192 | init이 emit하는 첫 "/rlp-desk run" Full options reference 블록의 `--mode agent\|tmux` | `--mode native\|tmux (default: native)` (recommended example는 `--mode tmux` 유지) |
+| 227 | 두 번째 init emission | 동일 처리 |
+| 255 | Options block: `- \`--mode agent\|tmux\` (default: \`agent\`)` | `- \`--mode native\|tmux\` (default: \`native\`)` (정확 라인 형태) |
+| 287 | Mode Selection: "If absent or `agent`, use the Agent() path below" | 두 축 명문화: `--mode native` (default, slash native Agent() leader) / `--mode tmux` (zsh runner). Legacy `--mode agent` deprecation+redirect prose. Direct Node CLI `node run.mjs --mode agent`는 deprecated alpha — 별도 paragraph |
+| 334 | tmux fallback "suggest `--mode agent`" | "suggest `--mode native`" |
+| 342 | "SV/flywheel은 `--mode agent`에서 지원" | "SV/flywheel은 현재 Node-leader `--mode agent` (deprecated alpha, direct Node CLI)에서만 구현. Native Agent() path(`--mode native`)는 SV/flywheel 미구현 — post-P3 작업" |
+| 343 | Tmux IMPORTANT RULES "always invokes node ..." | `--mode tmux` 한정으로 scope |
+| 360-410 | "Why Agent mode is structurally immune" + "PLATFORM CONSTRAINT" 분산 | 단일 박스 `### Native Agent() Safety Contract`로 verbatim 흡수. 4 sentinel: turn-keepalive, no `subagent_type`, `mode="bypassPermissions"` mandatory, long-running→tmux |
+| 448, 460 | claude/codex worker dispatch code | 변경 없음 (이미 native wired) |
+| 778 | "agent=LLM leader, tmux=shell leader" help | "native=Native Agent() leader (slash), tmux=zsh leader (production). Legacy `agent` redirects to `native`. Direct Node CLI `--mode agent`는 deprecated alpha — Direct Node CLI invocation 섹션 참조" |
+| 784 | run 예시 fallback에 `--mode agent` | `--mode native` |
+| 802 | "Agent Mode (default: --mode agent)" 헤딩 | "Native Agent() Mode (default: --mode native)" |
+
+### b. `src/node/run.mjs`
+
+- 신규 `--mode native` 핸들러:
+  - stderr: `ERROR: --mode native is slash-command-only. The Node CLI does not implement it. Use \`/rlp-desk run --mode native\` from a Claude Code session, or use \`--mode {tmux,agent}\` for direct CLI invocation.`
+  - exit 2
+- `--mode agent` (Node CLI, line 366-374) deprecation banner 강화:
+  ```
+  WARNING: --mode agent (Node-leader alpha) is deprecated.
+  This is the direct Node-CLI alpha path — UNRELATED to the slash command's
+  Native Agent() path (`/rlp-desk run --mode native`).
+  For production tmux orchestration use `--mode tmux`.
+  For Claude Code Native Agent() campaigns use `/rlp-desk run --mode native`
+  from a Claude Code session.
+  This mode will hard-error in the next major release.
+  ```
+  - default 동작 unchanged (silent reclaim NO; backward compat)
+  - `--allow-deprecated` flag 도입 X (P3에서 삭제할 ghost flag 회피)
+  - wrapper가 silence 원하면 `2>/dev/null`
+
+### c. Tests
+
+#### us008 신규 3 cases
+1. `node run.mjs run demo --mode native` → exit 2 + stderr ERROR 메시지
+2. `node run.mjs run demo --mode agent` → stderr deprecation banner + exit 0 (default 동작 유지)
+3. `node run.mjs run demo --mode tmux` 회귀 unchanged
+
+#### SV grep/awk guards (`tests/sv-gate-bug7-mode-prose.sh` 신규 또는 sv-gate-fast.sh 병합)
+
+```bash
+# 1. count-aware: --mode native 최소 5회 등장
+[ "$(grep -c '\-\-mode native' src/commands/rlp-desk.md)" -ge 5 ] || { echo "FAIL: --mode native must appear ≥5 times"; exit 1; }
+
+# 2. block-aware safety contract
+WINDOW=$(awk '/^### Native Agent\(\) Safety Contract/,/^### /' src/commands/rlp-desk.md)
+echo "$WINDOW" | grep -q 'Turn-keepalive: every status report uses' || { echo "FAIL: turn-keepalive sentinel"; exit 1; }
+echo "$WINDOW" | grep -q 'no `subagent_type` parameter' || { echo "FAIL: no-subagent_type sentinel"; exit 1; }
+echo "$WINDOW" | grep -q 'mode="bypassPermissions" mandatory' || { echo "FAIL: bypassPermissions sentinel"; exit 1; }
+echo "$WINDOW" | grep -qi 'long-running.*tmux' || { echo "FAIL: long-running tmux recommendation"; exit 1; }
+
+# 3. dispatch snippet preservation (AC1.5a static)
+awk '/^If claude engine \(default\):/,/^If codex engine:/' src/commands/rlp-desk.md > /tmp/_disp_claude
+grep -q 'Agent(' /tmp/_disp_claude || { echo "FAIL: claude dispatch missing Agent("; exit 1; }
+grep -q 'mode="bypassPermissions"' /tmp/_disp_claude || { echo "FAIL: claude dispatch missing bypassPermissions"; exit 1; }
+awk '/^If codex engine:/,/^\*\*⑥\*\*|^### /' src/commands/rlp-desk.md > /tmp/_disp_codex
+grep -q 'Bash("codex exec' /tmp/_disp_codex || { echo "FAIL: codex dispatch missing Bash codex exec"; exit 1; }
+
+# 4. Options block exact match
+WINDOW=$(awk '/^Options \(parse from/,/^- `--worker-model/' src/commands/rlp-desk.md)
+echo "$WINDOW" | grep -qE '^\- `--mode native\|tmux` \(default: `native`\)$' || { echo "FAIL: Options block --mode line not exact"; exit 1; }
+echo "$WINDOW" | grep -qE '\-\-mode .*agent' && { echo "FAIL: stale 'agent' in Options block --mode line"; exit 1; }
+
+# 5. Tmux IMPORTANT RULES contradiction removed
+! awk '/^\*\*IMPORTANT RULES:\*\*/,/^####/' src/commands/rlp-desk.md | grep -q "always invokes node" || { echo "FAIL: stale 'always invokes node'"; exit 1; }
+
+# 6. Legacy redirect prose present
+grep -q 'Legacy.*\-\-mode agent.*redirect' src/commands/rlp-desk.md || { echo "FAIL: deprecation prose missing"; exit 1; }
+```
+
+#### AC1.5b: manual transcript artifact
+
+`docs/verifications/p1-native-mode-transcript.md` (git-tracked):
+
+1. P1 land 후 Claude Code session에서 `/rlp-desk run sample --mode native` 1 iteration 실행
+2. 전체 transcript 캡처 — 다음 관측 포함:
+   - `Agent(model=…, mode="bypassPermissions", …)` worker dispatch 라인
+   - status report가 `Bash("echo '...'")` 로 wrap
+   - `subagent_type=` 미사용
+3. Reviewer가 `## Reviewer Sign-off` 섹션에 이름 + 날짜 기재
+4. CI guard: 파일 존재 + signoff 비-placeholder 검증 (`grep -E "^- Name: \S+"`, `grep -E "^- Date: [0-9]{4}-[0-9]{2}-[0-9]{2}"`)
+
+### d. Re-sync
+- `node scripts/postinstall.js`
+- banner-aware diff for `src/commands/rlp-desk.md` ⇆ `~/.claude/commands/rlp-desk.md`, `src/node/run.mjs` ⇆ `~/.claude/ralph-desk/node/run.mjs`
+
+### Acceptance
+- AC1.1 6 grep/awk guards all return 0
+- AC1.2 us008 신규 3 cases all green
+- AC1.3 us008/us006 기존 회귀 0
+- AC1.4 banner-aware diff src ⇆ install 일치
+- AC1.5a 정적 dispatch grep (#3) 통과
+- AC1.5b transcript artifact + signoff non-placeholder
+
+## Out-of-scope (deferred PR list)
+
+- **P2**: `src/node/run.mjs:16` default `'agent'` → `'tmux'` flip + `--mode agent` (Node CLI) hard-error. 19th launch 종료 후, 외부 wrapper 영향 평가 후 별도 PR.
+- **P3**: Node leader 삭제 (`src/node/runner/campaign-main-loop.mjs`, `src/node/tmux/`, `src/node/polling/` 등 ~4.5k LOC) + Bug-7 Node 통합 테스트 폐기 + repo-wide ghost-removal gate (`rg -n "Node leader\|node-leader\|--mode agent" src docs scripts tests` = 의도된 hits만). P2 후.
+- **`--mode agent` reclaim to Native Agent()**: P3 이후 next major version에서만. 이번 PR에선 silent reclaim 없음.
+
+## Pre-mortem
+
+1. **`--mode agent` 호출자가 native와 alpha 의미를 헷갈린다** — slash command에서 호출 시 deprecation+redirect로 native path 진행. 외부 shell wrapper에서 `node run.mjs run X --mode agent` 호출 시 deprecation banner + 기존 Node leader path. 두 경로 모두 메시지로 명시.
+2. **Native Agent() turn-end가 사용자를 괴롭힌다** — Safety Contract 박스의 turn-keepalive 명문화로 mitigate. 그래도 100%는 아니므로 docs는 long-running = `--mode tmux` 강력 권고.
+3. **외부 wrapper가 `--mode agent` (Node CLI) 의존** — 동작 unchanged + deprecation banner만. P3에서야 hard-error. wrapper는 그동안 마이그레이션.
+
+## Verification end-to-end (P0+P1 land 후)
+
+1. `git log --oneline HEAD~3..HEAD` — Bug #7 + ADR + P1 commits
+2. `node --test 'tests/node/*.test.mjs' 'tests/node/*.mjs'` — 315+3 = 318 통과
+3. `bash tests/test-bug7-post-sentinel-race.sh` + `bash tests/test-bug7-poll-partial-write.sh` 통과
+4. `bash tests/sv-gate-bug7-mode-prose.sh` (또는 sv-gate-fast.sh) — 6 grep/awk guards 0
+5. banner-aware diff src ⇆ `~/.claude/`
+6. AC1.5b: 사용자가 Claude Code session에서 `/rlp-desk run sample --mode native` 실행 후 transcript 검토 + signoff
+
+## Round-by-round resolution table
+
+| Round | Verdict | Findings closed |
+|---|---|---|
+| 1 (Architect) | shift to A-strict | option A → A-strict |
+| 2 (Critic codex) | ITERATE 7 | entrypoint, default flip, ADR scope, naming, reclaim, AC, re-sync |
+| 3 (Architect) | ITERATE 2 | synonym ghost, allow-deprecated ghost |
+| 4 (Critic codex) | ITERATE 4 | init blocks (192/227), fallback (334/342), grep guards, ADR scope |
+| 5 (Critic codex) | ITERATE 3 | label expansion (778/802), exact options match, AC1.5 runnable |
+| 6 (Critic codex) | ITERATE 3 (1 actionable, 2 cross-check false-positives) | signoff non-placeholder check |
+
+Net: 모든 v0-v5 actionable findings closed. Round 6 finding 3 (signoff non-placeholder)은 v7에 이미 반영됨 (AC1.5b CI guard 4번째 항목). Round 6 finding 1/2는 v6 base에 이미 포함된 사항 — critic의 cross-check 누락.

package/docs/plans/strategic-review/rlp-desk-strategic-review.md

@@ -0,0 +1,125 @@
+# rlp-desk 전략 재평가 — autoplan 입력
+
+> **목표**: rlp-desk를 계속 발전시킬지(patch/redesign), 폐기 후 재구성할지(rebuild), 기존 도구로 pivot할지 결정.
+> **핵심 KPI**: blueprint 처음 → 끝 자율 완료. 사람 개입 최소.
+> **현재 상태**: 6주간 10개 bug, 매주 1-2개 신규 발견, manual recovery마저 broken (#10).
+
+---
+
+## 1. Vision (BOS dev 합의, 2026 초)
+
+1. ralph-loop를 **fresh-context**로 매번 시작 (컨텍스트 오염 없음)
+2. idea → plan distillation
+3. PRD 정형화
+4. Worker/Verifier 사이클로 반복 개선
+5. **완전 자율화** — 사람 개입 최소
+
+→ 5번이 단일 success criterion. 1-4는 5번을 달성하기 위한 메커니즘.
+
+---
+
+## 2. Reality — 6주간 측정된 사실
+
+### Bug 발생 패턴
+
+| # | 일자 | 카테고리 | 회수 가능 | 다음 fix가 노출한 다음 bug |
+|---|---|---|---|---|
+| #1 | 2026-05-01 | LLM-runtime (`.claude/` self-modification gate) | partial — codex worker로 우회 | #2 (tmux session) |
+| #2 | 2026-05-01 | tmux session lifecycle | yes | #3 |
+| #3 | 2026-05-04 | verifier no-progress | yes | #4 (regression of #3) |
+| #4 | 2026-05-05 | #3 regression | partial | #5 |
+| #5 | 2026-05-05 | worker dead on reuse (pane lifecycle) | yes | #6 |
+| #6 | 2026-05-06 | claude worker idle false-positive | yes | #7 |
+| #7 | 2026-05-06 | post-sentinel process race (1m43s drift) | yes | #8 + #10 |
+| #8 | 2026-05-06 | worker incomplete + leader A4 fallback | partial | #10 |
+| #9 | (별도) | verified_us 영속성 (status.json) | yes | — |
+| #10 | 2026-05-07 | leader ignores phase=verify on relaunch — **회수마저 깨짐** | NO (이게 회수 메커니즘) | ? |
+
+**Pattern observed:**
+- 매주 1-2개 신규 bug
+- 절반은 **이전 fix가 노출**한 새 failure mode (regression style)
+- Bug #10이 가장 심각 — 회수 메커니즘 자체가 broken → BLOCKED 시 operator의 manual recovery가 무효화
+
+### Bug 카테고리 분류
+
+| 카테고리 | Bug | 비중 | architectural 필연성? |
+|---|---|---|---|
+| (a) tmux/process lifecycle race | #2, #5, #6, #7 | 40% | **YES** — tmux pane lifecycle은 claude/codex TUI lifecycle과 분리됨. race window가 본질적 |
+| (b) artifact contract / schema | #3, #4, #8, #9 | 40% | partial — schema가 더 strict하면 줄어들지만 LLM이 schema 어기는 빈도가 본질적 |
+| (c) LLM-runtime constraint | #1 | 10% | **YES** — Claude Code의 `.claude/` self-modification gate는 외부 변수 |
+| (d) recovery hygiene | #10 | 10% | accidental — fix 가능 |
+
+→ **80%가 architectural inevitability** (a + c). schema strict + retry는 (b)를 줄이지만 LLM 비결정성이 한계.
+
+### SV gate 한계
+
+- 모든 sv-self-verify-*.sh가 **Worker/Verifier metaphor만 사용** → 실제 LLM agent run 없음
+- grep + unit test + regression의 5-category labeling
+- → 10개 bug가 SV gate 통과 후 production에서 발견됐다는 사실 = **framework이 production failure mode를 cover 못 함**
+- Production failure mode는 **LLM/tmux/network/timing 비결정성** — unit test로 잡을 수 없는 영역
+
+### In-flight 미완 branch
+
+- `feat/native-agent-revert`: P0(Bug #7 fix) + P1(slash native prose 회복) — 미완. Plan: 5 round ralplan 합의됨, codex critic APPROVED
+- `feat/bug10-relaunch-hygiene`: PR-A commit 95c0d4e + SV gate 추가 — 방금 완료, push 안 됨
+
+→ 두 branch 모두 land 안 됨 = 새 bug 발견 시 기존 fix가 무력화될 위험
+
+---
+
+## 3. 4가지 옵션
+
+### Option A — Continue patching (현재 path)
+PR-A (Bug #10) → PR-B (bundler) → PR-C (patterns) → 다음 bug → 반복.
+
+### Option B — Fundamental redesign (vision 유지, architecture 재설계)
+**핵심 변경**: tmux pane orchestration 폐기 → Claude Code Native Agent() / subprocess 직접 dispatch. Sentinel file → in-memory channel. 두 변경으로 (a) 카테고리 80%가 제거.
+
+### Option C — Scrap and rebuild (vision 일부 수정)
+6주 코드 폐기. Vision 5번 (완전 자율화)은 유지하되 1번(fresh-context)은 task-isolated subprocess로 재정의. ralph-loop 자체 폐기 가능 — 그냥 plan→worker→verify 사이클로 단순화.
+
+### Option D — Pivot to existing tool
+- ralph plugin (cradle): 가벼움, 기능 부족
+- omc (oh-my-claudecode): /ralph + /ralplan + /omc-teams + /autopilot — 이미 multi-model orchestration 있음
+- superpowers: subagent-driven-development, executing-plans, brainstorming — plan→exec 사이클은 이미 있음
+- claude-devfleet: dmux 기반, multi-agent
+
+---
+
+## 4. 평가 항목 (각 옵션마다)
+
+| 항목 | 정의 | 이유 |
+|---|---|---|
+| Vision 보존도 | 5개 vision 중 살아남는 개수 | "완전 자율화" 달성 가능성 |
+| Time-to-first-successful-blueprint | 처음으로 blueprint를 끝까지 자율 완료하는 데 걸리는 시간 | **단일 핵심 KPI** |
+| Sunk cost write-off % | 폐기되는 코드/SV 비율 | 결정의 reversibility |
+| Bug regression 위험 | 새 시스템에서 #1-#10 같은 bug가 다시 나올 확률 | "다음 6주에 또 10개?" |
+| Personal capacity ROI | 1주 투자 시 deliverable | sustainability |
+
+---
+
+## 5. In-flight branch 처리 결정
+
+이 평가가 끝난 후 결정:
+- `feat/native-agent-revert`: land / abandon / re-scope?
+- `feat/bug10-relaunch-hygiene`: 이미 commit 95c0d4e, push할까 hold할까?
+
+선택 옵션이 무엇이든 두 branch는 처리 필요.
+
+---
+
+## 6. 제약
+
+- BOS dev가 실제 캠페인을 돌려야 함 → short-term (1-2주) patching 불가피
+- rlp-desk는 npm published — breaking change는 user-facing (semver 고려)
+- 분석은 advisory only — 실제 코드 수정/commit/push는 사용자 승인 별도
+
+---
+
+## 7. autoplan에 요구 — 이 문서를 입력으로
+
+CEO 관점: rlp-desk가 푸는 문제가 옳은가? 다른 도구로 같은 가치를 이미 얻을 수 있나?
+Eng 관점: 6주간의 architectural pattern을 보면 (a) 80% 카테고리가 patching으로 해결될까? 아니면 redesign이 필연인가?
+DX 관점: rlp-desk는 dev tool — operator(BOS dev)가 매번 30분씩 hand-write recovery를 해야 한다는 사실이 DX failure인가?
+
+각 phase에서 dual voices (Codex + Claude subagent) 실행, consensus table 생성, 4 options steelman.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-dev-methodologies/rlp-desk",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "description": "Fresh-context iterative loops for Claude Code — autonomous task completion with independent verification",
   "scripts": {
     "postinstall": "node scripts/postinstall.js",

package/src/commands/rlp-desk.md

@@ -189,7 +189,7 @@ Tell the user:
    /rlp-desk run <actual-slug> --debug
 
    # Full options reference:
-   #   --mode agent|tmux                      (default: agent)
+   #   --mode native|tmux                     (default: native; legacy `agent` redirects to native)
    #   --worker-model MODEL                   haiku|sonnet|opus or gpt-5.5:high|spark:high (default: haiku)
    #   --lock-worker-model                    disable auto model upgrade
    #   --verifier-model MODEL                 per-US verifier (default: sonnet)
@@ -217,14 +217,14 @@ Tell the user:
    # ★ Recommended: tmux mode + claude-only (real-time visibility):
    /rlp-desk run <actual-slug> --mode tmux --debug
 
-   # Agent mode:
-   /rlp-desk run <actual-slug> --debug
+   # Native Agent() mode (slash leader, short / interactive campaigns):
+   /rlp-desk run <actual-slug> --mode native --debug
 
    # Install codex for cost savings + cross-engine blind-spot coverage:
    npm install -g @openai/codex
 
    # Full options reference:
-   #   --mode agent|tmux                      (default: agent)
+   #   --mode native|tmux                     (default: native; legacy `agent` redirects to native)
    #   --worker-model MODEL                   haiku|sonnet|opus (default: haiku)
    #   --lock-worker-model                    disable auto model upgrade
    #   --verifier-model MODEL                 per-US verifier (default: sonnet)
@@ -252,7 +252,7 @@ Tell the user:
 **YOU are the leader. Do NOT delegate leadership.**
 
 Options (parse from `$ARGUMENTS`):
-- `--mode agent|tmux` (default: `agent`) — execution mode
+- `--mode native|tmux` (default: `native`) — execution mode. `native` = slash command is the leader, calls `Agent(...)` (claude) and `Bash("codex exec ...")` (codex). `tmux` = slash command spawns the zsh runner via `node run.mjs --mode tmux`. Legacy `--mode agent` typed against the slash command emits a deprecation notice and redirects to `--mode native` (NOT to be confused with `node run.mjs --mode agent`, which is the deprecated Node-leader alpha — see "Direct Node CLI invocation" below).
 - `--worker-model MODEL` (default: `haiku`) — Worker model. Format: `model` = claude engine, `model:reasoning` = codex engine. Examples: `haiku`, `sonnet`, `opus`, `spark:high`, `gpt-5.5:high`. Parsed by `parse_model_flag()` which auto-splits engine/model/reasoning.
 - `--lock-worker-model` — disable automatic model upgrade on failure. Worker stays on the specified model regardless of consecutive failures.
 - `--verifier-model MODEL` (default: `sonnet`) — per-US verification model. Campaign-fixed (no progressive upgrade). Lighter than final verifier.
@@ -284,20 +284,26 @@ Cross-project aggregation: scan `~/.claude/ralph-desk/analytics/` and read each
 
 ### Mode Selection
 
-Parse the `--mode` flag. If absent or `agent`, use the Agent() path below. If `tmux`, use the Tmux path.
+Parse the `--mode` flag. Slash command canonical labels:
+
+- `--mode native` (default): **Native Agent() path** below. The slash command IS the leader. It calls `Agent(description=…, model=<m>, mode="bypassPermissions", prompt=…)` for claude workers/verifiers and `Bash("codex exec --model <m> --reasoning-effort <r> <prompt>")` for codex workers/verifiers.
+- `--mode tmux`: **zsh runner path** below. The slash command shells out to `node ~/.claude/ralph-desk/node/run.mjs run --mode tmux …` which spawns `run_ralph_desk.zsh` as a subprocess.
 
-> **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.
+Legacy `--mode agent` typed against this slash command emits a deprecation notice and redirects to `--mode native`. **Do NOT confuse `/rlp-desk run --mode agent`** (slash command, redirects to Native Agent()) **with** `node run.mjs run --mode agent` (deprecated Node-leader alpha, direct CLI invocation, unrelated code path — see "Direct Node CLI invocation" below).
+
+> **Stability tiers:**
+> - `--mode tmux` is the **stable, production** path. The slash command spawns
+>   the Node leader, which spawns `run_ralph_desk.zsh` — the zsh 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 native` is **for short / interactive campaigns**. Native Agent()
+>   has no timeout API (platform constraint). Long-running autonomous campaigns
+>   SHOULD use `--mode tmux`.
 
 #### Tmux Mode (`--mode tmux`)
 
-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`):
+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 currently require the deprecated Node-leader direct-CLI path `node run.mjs --mode agent` (see "Direct Node CLI invocation" below). Native Agent() port is a post-Node-leader-retirement task):
 
 1. **Validate scaffold** — same as Agent() mode: check `.rlp-desk/prompts/<slug>.worker.prompt.md` etc.
 2. **Check sentinels** — same as Agent() mode.
@@ -331,7 +337,7 @@ node ~/.claude/ralph-desk/node/run.mjs run '<slug>' \
 
 **Env-var translation (v5.7 §4.1)**: the slash command historically built `LANE_MODE=strict zsh ...` and `TEST_DENSITY_MODE=strict zsh ...` from CLI flags. The Node leader uses CLI flags instead — translate `--lane-strict` and `--test-density-strict` into the corresponding flags. Direct env-var users (running zsh directly) are unaffected.
 
-6. **If the Node leader exits with error** — report the error to the user and STOP. Do NOT attempt to work around it. Do NOT create tmux sessions yourself. Do NOT re-launch in a different way. Tell the user what went wrong and suggest `--mode agent` as alternative.
+6. **If the Node leader exits with error** — report the error to the user and STOP. Do NOT attempt to work around it. Do NOT create tmux sessions yourself. Do NOT re-launch in a different way. Tell the user what went wrong and suggest `--mode native` (slash command Native Agent() path) as alternative.
 7. **If successful** — tell the user the tmux session has been started. The Node leader takes over as the deterministic Leader. No Agent() calls are made in tmux mode.
 
 **IMPORTANT RULES:**
@@ -339,35 +345,36 @@ 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`.
-- 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.
+- 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 today, use the deprecated Node-leader direct-CLI path `node run.mjs --mode agent` (see "Direct Node CLI invocation" below). The slash command's Native Agent() (`--mode native`) does not yet implement SV/flywheel — port is a post-Node-leader-retirement task.
+- **For `--mode tmux` only**: the slash command 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. **For `--mode native`**, the slash command does NOT invoke the Node CLI — it acts as the leader itself; see Native Agent() Mode section below.
 
 **tmux UX model (5 items):**
 - The session returns immediately after launch (`run_in_background: true`) so the command returns control to the parent CLI.
 - Worker/Verifier panes remain visible to the user during execution.
 - Users check progress with the **status command**: `/rlp-desk status <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 — **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(...,
-mode="bypassPermissions", ...)`. The subagent runs non-interactively under
-the platform's bypass — it has no tmux pane, no TUI surface, and cannot
-surface a `[y/N]` prompt to the parent Leader. The auto-dismiss /
-prompt-stall / no-progress timeouts in `run_ralph_desk.zsh` (v5.7 §4.13.b /
-§4.16 / §4.17) are therefore tmux-only by design. **Tradeoff**: because
-`Agent()` has no timeout API, agent-mode iterations are not bounded — if
-the platform's `bypassPermissions` ever fails to suppress an interactive
-prompt at the SDK level, the call hangs indefinitely with no rlp-desk-side
-watchdog. Use `--mode tmux` if you need bounded execution time.
+- Native Agent() mode remains unchanged, and no tmux-specific behavior is mixed into it.
+
+#### Native Agent() Mode (`--mode native` or default)
+
+The slash command IS the leader. Workers/Verifiers are spawned via `Agent(model=…, mode="bypassPermissions", prompt=…)` (claude) or `Bash("codex exec --model <m> --reasoning-effort <r> <prompt>")` (codex).
+
+### Native Agent() Safety Contract
+
+This contract MUST be observed in every iteration of the leader loop below. Future PRs deleting any of these guarantees break the slash command's behavior.
+
+1. **Turn-keepalive**: every status report uses `Bash("echo '...'")` to emit messages. NEVER output plain text without an accompanying tool call. Plain text = turn ends = loop stops. (Mitigation for commit `29fd29b` platform constraint, permanent.)
+2. **no `subagent_type` parameter**: the `Agent(...)` call form is exactly `Agent(description=…, model=<m>, mode="bypassPermissions", prompt=…)`. Do NOT pass `subagent_type`. (Mitigation for commit `920a31c`: `subagent_type="executor"` overrode `bypassPermissions` and surfaced a permission popup; permanent.)
+3. **`mode="bypassPermissions"` mandatory**: every claude `Agent()` worker/verifier dispatch must include `mode="bypassPermissions"`.
+4. **Long-running campaigns: prefer `--mode tmux`** for production. Native Agent() has no timeout API (platform constraint) — if `bypassPermissions` fails to suppress an interactive prompt at the SDK level, the call hangs indefinitely with no rlp-desk-side watchdog.
+
+**Why Native Agent() is structurally immune to Bug 4/5 (mid-execution prompt hang & A4 premature dispatch)**: Worker/Verifier run non-interactively under the platform's bypass — they have no tmux pane, no TUI surface, and cannot surface a `[y/N]` prompt to the parent Leader. The auto-dismiss / prompt-stall / no-progress timeouts in `run_ralph_desk.zsh` (v5.7 §4.13.b / §4.16 / §4.17) are therefore tmux-only by design.
+
+**Tradeoff**: because `Agent()` has no timeout API, Native Agent() iterations are not bounded — if the platform's `bypassPermissions` ever fails to suppress an interactive prompt at the SDK level, the call hangs indefinitely with no rlp-desk-side watchdog. Use `--mode tmux` if you need bounded execution time.
+
+#### Direct Node CLI invocation (`node run.mjs run <slug> --mode agent` — deprecated alpha)
+
+Direct invocation of `node ~/.claude/ralph-desk/node/run.mjs run <slug> --mode agent` is **the deprecated Node-leader alpha path**. This is unrelated to the slash command's Native Agent() path above — different code, different leader, different lifecycle. The Node leader currently retains SV/flywheel implementations not yet ported to Native Agent(). The Node CLI emits a deprecation banner on this mode and is scheduled for hard-error in the next major release. For production tmux orchestration, use `--mode tmux`. For Claude Code Native Agent() campaigns, use `/rlp-desk run <slug> --mode native` from a Claude Code session.
 
 ### Preparation
 1. Validate scaffold: `.rlp-desk/prompts/<slug>.worker.prompt.md` etc.
@@ -775,13 +782,13 @@ Example:
 ```
 /rlp-desk brainstorm <description>          Plan before init (interactive)
 /rlp-desk init  <slug> [objective]          Create project scaffold
-/rlp-desk run   <slug> [options]            Run loop (agent=LLM leader, tmux=shell leader)
+/rlp-desk run   <slug> [options]            Run loop (native=Native Agent() leader (slash), tmux=zsh leader (production); legacy `agent` redirects to `native` — direct Node CLI `--mode agent` is deprecated alpha)
 /rlp-desk status <slug>                     Show loop status
 /rlp-desk logs  <slug> [N]                  Show iteration log
 /rlp-desk clean <slug> [--kill-session]     Reset for re-run (--kill-session kills tmux)
 
 Run options:
-  --mode agent|tmux                    Execution mode (default: agent)
+  --mode native|tmux                   Execution mode (default: native)
   --worker-model MODEL                 Worker model: haiku|sonnet|opus or gpt-5.5:high|spark:high (default: haiku)
   --lock-worker-model                  Disable auto model upgrade on failure
   --verifier-model MODEL               per-US verifier (default: sonnet)
@@ -799,15 +806,18 @@ Run options:
 
 ## Architecture
 
-### Agent Mode (default: `--mode agent`)
+### Native Agent() Mode (default: `--mode native`)
 ```
-[This session = LEADER (LLM)]
+[This session = LEADER (LLM, slash command itself)]
         │
-  Agent()├──▶ [Worker: executor (fresh context)]
+  Agent()├──▶ [Worker: claude subagent (fresh context, mode="bypassPermissions")]
         │     └── reads desk files, implements, updates memory
         │
-  Agent()└──▶ [Verifier: executor (fresh context)]
-              └── reads done-claim, runs checks, writes verdict
+  Agent()└──▶ [Verifier: claude subagent (fresh context, mode="bypassPermissions")]
+        │     └── reads done-claim, runs checks, writes verdict
+        │
+  Bash() ───▶ [Worker/Verifier: codex CLI subprocess]
+              └── `codex exec --model <m> --reasoning-effort <r> <prompt>`
 ```
 
 ### Tmux Mode (`--mode tmux`)

package/src/node/run.mjs

@@ -48,14 +48,14 @@ function buildHelpText() {
     'Commands:',
     '  brainstorm <description>     Plan before init (not implemented in the Node rewrite yet)',
     '  init <slug> [objective]      Create project scaffold',
-    '  run <slug> [options]         Run loop (agent=LLM leader, tmux=shell leader)',
+    '  run <slug> [options]         Run loop (tmux=zsh leader [production], agent=Node leader [deprecated alpha], native=slash-only error)',
     '  status <slug>                Show loop status',
     '  logs <slug> [N]              Show iteration log (not implemented in the Node rewrite yet)',
     '  clean <slug> [--kill-session] Reset for re-run (not implemented in the Node rewrite yet)',
     '  resume <slug>                Resume loop (not implemented in the Node rewrite yet)',
     '',
     'Run Options:',
-    '  --mode agent|tmux',
+    '  --mode tmux|agent|native       (CLI: tmux=production, agent=deprecated, native=errors with redirect to slash command)',
     '  --worker-model MODEL',
     '  --lock-worker-model',
     '  --verifier-model MODEL',
@@ -358,10 +358,32 @@ async function runRunCommand(args, deps) {
     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.
+  // P1.b (native-agent-revert plan v7): --mode native is slash-command-only.
+  // The Node CLI does not implement Native Agent() — that path lives in
+  // src/commands/rlp-desk.md and runs in a Claude Code session. Surface a
+  // hard error here so direct CLI invocation does not silently fall through
+  // to the deprecated Node-leader path.
+  if (options.mode === 'native') {
+    write(
+      deps.stderr,
+      'ERROR: --mode native is slash-command-only. The Node CLI does not implement it.',
+    );
+    write(
+      deps.stderr,
+      'Use `/rlp-desk run <slug> --mode native` from a Claude Code session,',
+    );
+    write(
+      deps.stderr,
+      'or use `--mode tmux` (production) / `--mode agent` (deprecated alpha) for direct CLI invocation.',
+    );
+    return 2;
+  }
+
+  // P1.b: --mode agent (Node-leader alpha) is deprecated. The slash command's
+  // Native Agent() path (`/rlp-desk run --mode native`) is unrelated — different
+  // code, different leader. We keep the Node-leader behavior unchanged for
+  // backward compatibility but surface a strong deprecation banner so wrappers
+  // can migrate before the next major release hard-errors this mode.
   if (
     options.mode === 'agent'
     && !process.env.RLP_DESK_QUIET_WARNINGS
@@ -369,7 +391,23 @@ async function runRunCommand(args, deps) {
   ) {
     write(
       deps.stderr,
-      'WARNING: --mode agent is alpha. For production tmux orchestration, prefer --mode tmux (zsh-backed, stable).',
+      'WARNING: --mode agent (Node-leader alpha) is deprecated.',
+    );
+    write(
+      deps.stderr,
+      'This is the direct Node-CLI alpha path — UNRELATED to the slash command Native Agent() path (`/rlp-desk run --mode native`).',
+    );
+    write(
+      deps.stderr,
+      'For production tmux orchestration, use `--mode tmux`.',
+    );
+    write(
+      deps.stderr,
+      'For Claude Code Native Agent() campaigns, use `/rlp-desk run --mode native` from a Claude Code session.',
+    );
+    write(
+      deps.stderr,
+      'This mode will hard-error in the next major release.',
     );
   }