@ai-dev-methodologies/rlp-desk 0.14.6 → 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/polished-gliding-toucan.md

@@ -0,0 +1,234 @@
+# Bug Report #7 — Post-Sentinel Process Race Fix
+
+## Context
+
+BOS 사용자가 19th launch에서 측정한 race window:
+- iter-1 verifier가 verdict detect 후 **1m 43s** 뒤 `verify-verdict.json` 재수정 (file mtime 증거)
+- iter-1 verifier post-verdict 후속 활동 **2m 1s**
+- iter-1 verifier ↔ iter-2 worker 동시 작업 약 **2분**
+
+Bug report:
+`/Users/kyjin/dev/doul/bos/docs/exec-plans/active/2026-05-06-rlp-desk-bug-report-7-post-sentinel-process-race.md`
+
+### Root cause
+
+Leader는 `iter-signal.json` / `verify-verdict.json` 발견 즉시 다음 iter로 진입하지만, 그 sentinel을 쓴 Worker/Verifier process(claude/codex TUI)는 **명시적으로 종료되지 않는다**. tmux pane은 살아 있고 TUI는 idle prompt로 회귀 후 자체 self-review를 수행 → sentinel 재수정·working tree 오염·토큰 낭비.
+
+### 모드 영향 범위 (중요)
+
+`--mode tmux`(zsh runner)와 `--mode agent`(Node leader) **둘 다 영향**. Node leader도 `defaultSendKeys`/`defaultCreatePane`(`src/node/tmux/pane-manager.mjs`)을 통해 실제 tmux pane 위에서 worker/verifier를 실행한다 (`src/node/runner/campaign-main-loop.mjs:1077-1080`, `1116-1133`). Agent 모드 면역이라는 초기 가설은 부정확.
+
+### 비대칭 (현 상태)
+
+| 경로 | Worker 후처리 | Verifier 후처리 |
+|---|---|---|
+| Node leader | 없음 | 없음 |
+| zsh runner | 다음 iter 시작 시 cleanup (`run_ralph_desk.zsh:2948-2956`) — race window 5s+ | dispatch 직전 cleanup (`3160-3180`) — 같은 iter 내에선 보호되나 final iter 종료 후 또는 cross-iter race는 불보호 |
+
+---
+
+## Approach (Fix-Q + Fix-R, 최소 surgical 조합)
+
+| Fix | 효과 | 채택 |
+|---|---|---|
+| **Q** Sentinel detect 즉시 producing pane에 Ctrl+C → process 종료 | race를 ~1초 안에 직접 차단 | **YES (primary)** |
+| **R** Sentinel 파일 chmod 0444로 재수정 차단 | Q가 늦거나 fail해도 mtime 동결 | **YES (defense-in-depth)** |
+| S Pane lifecycle 전면 리팩토링 | 효과는 있으나 surface가 너무 큼. 기존 prep cleanup (zsh 2948-2956)으로 부분 커버됨. Karpathy "surgical changes" 원칙 위반 | NO |
+| T post-sentinel 30s 안전망 timeout | Q가 fail-open이고 다음 iter prep cleanup이 backup이라 중복 | NO |
+
+근거:
+- Q는 producer를 ~1초 내 죽여서 root cause 차단. 기존 패턴 정확히 미러 (zsh `run_ralph_desk.zsh:2384-2397`, Ctrl+C 더블 송신 + `wait_for_pane_ready`).
+- R은 chmod 실패에 관대(EPERM/ENOTSUP 무시 — `scripts/postinstall.js:104` `tryLockFile` 선례). WSL1/NTFS/tmpfs 등 chmod no-op 환경에서도 graceful degradation.
+- S/T 제거로 review surface 최소화.
+
+---
+
+## Concrete code changes
+
+### Node leader
+
+#### 1. `src/node/tmux/pane-manager.mjs` — helper 추가 (line 77 뒤)
+
+신규 export:
+- `sendRawKey(paneId, key)` — `runTmux(['send-keys', '-t', paneId, key])`. `sendKeys`(`-l --` literal text)와 분리: C-c 같은 raw key용.
+- `killPaneProcess(paneId, { sendRawKey, waitForExit, gracePeriodMs=800, exitTimeoutMs=5000, log })`:
+  1. `sendRawKey('C-c')` → `await sleep(gracePeriodMs)` → `sendRawKey('C-c')` (double press, zsh `375-376` 미러).
+  2. `await waitForExit(paneId, { timeoutMs: exitTimeoutMs }).catch(log)` — fail-open.
+  3. raw key 송신 자체의 TmuxError도 catch+log (이미 죽은 pane에 안전).
+
+기존 `waitForProcessExit` (line 55) 그대로 재사용.
+
+#### 2. `src/node/shared/fs.mjs` — helper 추가 (line 61 뒤)
+
+- `lockSentinelFile(filePath, { log })` — `fs.chmod(filePath, 0o444)`, error 시 한 번만 경고 로그. `tryLockFile`(`scripts/postinstall.js:104`) 선례 미러.
+- `unlockSentinelFile(filePath)` — `fs.chmod(filePath, 0o644)`, 실패 무시. iter cleanup 직전에 호출.
+
+#### 3. `src/node/runner/campaign-main-loop.mjs` — wire + call sites
+
+DI 슬롯 추가 (line 1077-1080):
+```
+const sendRawKey = options.sendRawKey ?? defaultSendRawKey;
+const waitForProcessExit = options.waitForProcessExit ?? defaultWaitForProcessExit;
+const killPaneProcess = options.killPaneProcess ?? defaultKillPaneProcess;
+const lockSentinel = options.lockSentinelFile ?? lockSentinelFile;
+```
+
+내부 wrapper:
+```
+async function reapProducer(paneId, sentinelFile) {
+  await killPaneProcess(paneId, { sendRawKey, waitForExit: waitForProcessExit, log: console.error });
+  if (sentinelFile) await lockSentinel(sentinelFile, { log: console.error });
+}
+```
+
+호출 사이트 (성공 + `validateArtifact` 통과 직후):
+
+| Site | Line | 호출 |
+|---|---|---|
+| Flywheel poll | 1267-1277 다음 (1285 앞) | `reapProducer(state.flywheel_pane_id ?? state.verifier_pane_id, paths.flywheelSignalFile)` |
+| Guard poll | 1305-1315 다음 (1323 앞) | `reapProducer(guardPaneId, paths.flywheelGuardVerdictFile)` |
+| Worker poll | 1422-1432 다음 (1456 앞) | `reapProducer(state.worker_pane_id, paths.signalFile)` |
+| Verifier poll | 1489-1513 다음 (1522 앞) | `reapProducer(state.verifier_pane_id, paths.verdictFile)` |
+| Final per-US verifier (`runFinalSequentialVerify`) | 890-894 다음 (896 앞) | `reapProducer(verifierPaneId, paths.verdictFile)` — `runFinalSequentialVerify` 시그니처에 `reapProducer` 추가 + 호출처(1185-1194) 전달 |
+
+iter cleanup unlock — `fs.unlink(...)` 호출 직전 `unlockSentinelFile` 호출:
+- L1291 (`flywheelSignalFile`)
+- L1328 (`flywheelGuardVerdictFile`)
+- 루프 상단 (1145 직후) — Worker `signalFile` / Verifier `verdictFile` 방어적 unlock (다음 iter producer가 atomic rename으로 덮어쓸 때 대비)
+
+### zsh runner
+
+#### 4. `src/scripts/lib_ralph_desk.zsh` — helper 추가 (`atomic_write` 다음, line 245 뒤)
+
+```
+_kill_pane_process() {
+  local pane_id="$1" role="${2:-producer}"
+  log_debug "[bug7] kill_pane_process pane=$pane_id role=$role"
+  tmux send-keys -t "$pane_id" C-c 2>/dev/null
+  sleep 0.5
+  tmux send-keys -t "$pane_id" C-c 2>/dev/null
+  sleep 1
+  wait_for_pane_ready "$pane_id" 5 2>/dev/null || true
+}
+
+_lock_sentinel() {
+  local file="$1"
+  [[ -f "$file" ]] || return 0
+  chmod 0444 "$file" 2>/dev/null || true
+}
+
+_unlock_sentinel() {
+  local file="$1"
+  [[ -f "$file" ]] || return 0
+  chmod 0644 "$file" 2>/dev/null || true
+}
+```
+
+#### 5. `src/scripts/run_ralph_desk.zsh` — call sites
+
+| Site | Line | 호출 |
+|---|---|---|
+| Worker poll 성공 직후 | 3003 (`worker_poll_done=1` 분기 안, `log_debug` 다음) | `_kill_pane_process "$WORKER_PANE" "worker"; _lock_sentinel "$SIGNAL_FILE"` |
+| Verifier poll 성공 직후 (main path) | 3202 통과 후, 3215 앞 (`ITER_VERIFIER_END`) | `_kill_pane_process "$VERIFIER_PANE" "verifier"; _lock_sentinel "$VERDICT_FILE"` |
+| Final-verify per-US (`run_sequential_final_verify`) | 2524 통과 후, 다음 iter 진입 전 | `_kill_pane_process "$VERIFIER_PANE" "verifier-final"; _lock_sentinel "$VERDICT_FILE"` |
+| Codex grace path | `dispatch_verifier_per_us` (2420 그레이스 종료 직후, 2471 `cp` 앞) | `_kill_pane_process "$VERIFIER_PANE" "verifier-${suffix}"; _lock_sentinel "$VERDICT_FILE"` |
+| Consensus path | `run_consensus_verification` 내 각 `poll_for_signal` 성공 직후 | 동일 패턴 |
+
+prep cleanup unlock — line 2948-2956 cleanup 직전:
+```
+_unlock_sentinel "$SIGNAL_FILE"; _unlock_sentinel "$VERDICT_FILE"
+rm -f "$SIGNAL_FILE" "$DONE_CLAIM_FILE" "$VERDICT_FILE" 2>/dev/null
+```
+
+---
+
+## Files to modify
+
+| 파일 | 변경 |
+|---|---|
+| `src/node/tmux/pane-manager.mjs` | `sendRawKey`, `killPaneProcess` export 추가 |
+| `src/node/shared/fs.mjs` | `lockSentinelFile`, `unlockSentinelFile` export 추가 |
+| `src/node/runner/campaign-main-loop.mjs` | DI + `reapProducer` + 5개 call site + iter cleanup unlock |
+| `src/scripts/lib_ralph_desk.zsh` | `_kill_pane_process`, `_lock_sentinel`, `_unlock_sentinel` 추가 |
+| `src/scripts/run_ralph_desk.zsh` | 4-5개 call site + prep cleanup unlock |
+| `tests/node/us006-campaign-main-loop.test.mjs` | `createTmuxFakes()`에 `killPaneProcess`/`lockSentinelFile` 레코더 추가 + Bug-7 테스트 3건 |
+| `tests/node/test-kill-pane-process.test.mjs` | NEW — helper 단위 테스트 |
+| `tests/node/test-lock-sentinel-file.test.mjs` | NEW — chmod 단위 테스트 |
+| `tests/test-bug7-post-sentinel-race.sh` | NEW — 실제 tmux 통합 테스트 (Bug #6 패턴 미러) |
+
+배포는 단일 PR (helper는 call site 없으면 no-op이라 review surface 작음).
+
+---
+
+## Reused functions (참조)
+
+- Node: `pane-manager.mjs:50` `sendKeys`, `pane-manager.mjs:55` `waitForProcessExit` (5s timeout, shell 감지)
+- Node: `shared/fs.mjs:6-23` `writeFileAtomic`, `42-61` `writeSentinelExclusive`
+- Node: `scripts/postinstall.js:104` `tryLockFile` (chmod 0o444 선례)
+- zsh: `lib_ralph_desk.zsh:240-245` `atomic_write`, `1075-1137` `wait_for_pane_ready`
+- zsh: `run_ralph_desk.zsh:2384-2397` 검증된 verifier-cleanup 패턴 (Ctrl+C + /exit + wait), `375-376/529-530` 더블 Ctrl+C 패턴
+
+---
+
+## Testing strategy
+
+### 단위 테스트 (Node)
+
+`tests/node/test-kill-pane-process.test.mjs` (NEW):
+- AC1 정상: C-c → sleep → C-c → waitForExit 순서 (fake recorder 검증).
+- AC2 fail-open: `waitForExit` 가 TmuxError throw 시 helper resolve.
+- AC3 dead-pane: `sendRawKey` throw 시 resolve.
+- AC4 grace: gracePeriodMs 준수 (fake clock 또는 tolerance 검증).
+
+`tests/node/test-lock-sentinel-file.test.mjs` (NEW):
+- AC1: lock 후 mode `& 0o222 === 0` (chmod 무시 FS는 skip).
+- AC2: 존재하지 않는 path에 lock — throw 안 함.
+- AC3: unlock 후 writable.
+
+### 통합 테스트 (Node)
+
+`tests/node/us006-campaign-main-loop.test.mjs` 확장:
+1. **Bug-7-A**: Worker pollForSignal 성공 → next dispatchVerifier 전에 `killPaneProcess('%worker')` + `lockSentinelFile(signalFile)` 호출 순서 검증.
+2. **Bug-7-B**: Verifier verdict pass 후 next iter dispatchWorker 전에 `killPaneProcess('%verifier')` + `lockSentinelFile(verdictFile)`.
+3. **Bug-7-C**: `killPaneProcess`가 throw해도 run() 정상 완료.
+
+`createTmuxFakes()`(line 83)에 fake `killPaneProcess`/`lockSentinelFile` 레코더 추가 (기존 30+ 테스트 호환 보장).
+
+### 통합 테스트 (zsh)
+
+`tests/test-bug7-post-sentinel-race.sh` (NEW, `test-bug6-worker-idle-false-positive.sh` 패턴 미러):
+- Scenario 1: tmux 세션에 `sleep 600` 띄우고 `_kill_pane_process` 호출 → 2s 안에 `pane_current_command`가 zsh/bash로 회귀.
+- Scenario 2: `_lock_sentinel` → mode 0444 검증 → `_unlock_sentinel` → writable → `rm -f` 성공.
+- Scenario 3 (REAL_E2E gated): 1-iter 캠페인 + stub claude(sentinel write 후 sleep 120) → 10s 후 verdict file mtime delta == 0.
+
+### Self-Verification 시나리오 (CLAUDE.md gate, 3건 필수)
+
+`src/scripts/run_ralph_desk.zsh` 수정 — MEDIUM-HIGH risk:
+- **LOW**: helper 단위 테스트 + 기존 Node/zsh 회귀 테스트 통과.
+- **MEDIUM**: 1-iter 실제 캠페인. Worker → Verifier 전이 시점에 `pane_current_command` 캡처, 2s 내 shell 회귀 검증. Verdict file mtime 동결 검증.
+- **CRITICAL**: 2-iter 캠페인 (verify→fail→verify→pass). iter-N+1 worker dispatch가 iter-N verifier `pane_current_command == zsh` 확인 후에만 발생 — 타임스탬프 로그 캡처. `--mode agent`와 `--mode tmux` 둘 다 실행.
+
+---
+
+## Verification end-to-end
+
+1. **단위**: `node --test tests/node/test-kill-pane-process.test.mjs tests/node/test-lock-sentinel-file.test.mjs` 통과.
+2. **통합 (Node)**: `node --test tests/node/us006-campaign-main-loop.test.mjs` 통과 — call order 단언이 회귀 가드.
+3. **라이브 tmux**: `_kill_pane_process` 호출 후 2s 내 `tmux display-message -p '#{pane_current_command}' -t $pane`가 `zsh`/`bash` 반환.
+4. **mtime 동결**: `stat -f %m verify-verdict.json`을 detect 시점과 +10s 시점에 측정해 delta == 0. Bug report의 1m43s 증거를 직접 반박.
+5. **Pane 출력**: `tmux capture-pane -p` 결과에 `Worked for Xm Ys` / `esc to interrupt` 신규 표식 없음.
+6. **두 모드**: 스모크 테스트를 `--mode tmux`(zsh runner)와 `--mode agent`(Node leader) 각각 실행 — 둘 다 4초 내 shell 회귀 검증.
+7. **재현 시나리오**: 19th launch와 동일 조건(claude opus 1m worker + gpt-5.5:high codex verifier)으로 캠페인 1회 실행 후 leader log + file mtime 비교 — race 0.
+
+---
+
+## Risk / mitigation
+
+| Risk | 가능성 | 완화 |
+|---|---|---|
+| C-c가 producer artifact 쓰기 중간 인터럽트 | LOW — sentinel은 detect 시점에 이미 디스크에 존재 | `MalformedArtifactError` 경로가 partial write 처리 |
+| chmod 0444가 다음 iter cleanup의 `unlink` 차단 | LOW | `_unlock_sentinel` / `unlockSentinelFile`이 unlink 직전 실행. 대부분 Unix FS는 dir-perms 기준이라 0444 파일도 unlink 가능 |
+| Producer가 atomic rename으로 sentinel 재기록 (chmod 우회) | POSSIBLE | Q(kill)이 ~1s 내 producer 죽이므로 rewrite window가 2분 → 1초로 축소. 게다가 leader는 이미 in-band로 sentinel 소비 |
+| `killPaneProcess`가 죽은 pane에 throw | POSSIBLE | helper 내부 catch + 단위 테스트 AC2/AC3로 회귀 가드 |
+| chmod 0444 silent no-op (WSL1/NTFS/tmpfs) | OBSERVED (postinstall.js 선례) | 한 번만 경고 로그. Q(kill)이 primary defense라 graceful degradation |
+| 기존 us006 테스트 회귀 | MEDIUM | `createTmuxFakes()`에 fake helper 레코더 추가 — 기존 호출자는 자동 주입 받음 |

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/docs/rlp-desk/signal-protocol.md

@@ -0,0 +1,93 @@
+# Signal Protocol — current contract + alternatives
+
+**Spec version:** `signal-protocol-v1`
+**Source consensus:** ralplan iter 6 — Architect synthesis, Critic codex APPROVED (P0=0, P1=0)
+**Audience:** maintainers evaluating whether to adopt mailbox-dir, daemon, or in-process IPC alternatives.
+
+---
+
+## 1. Current Contract
+
+rlp-desk routes Worker → Verifier handoff through a **single sentinel file per role per iteration**. The contract has four invariants:
+
+1. **Sentinel = artifact.** Every transition step (`verify`, `verdict`, `flywheel`, `flywheel-guard`) is encoded as a JSON file at a deterministic path under `.rlp-desk/memos/`. The Leader polls the path with `fs.access` + atomic JSON-parse; any partial write is rejected (`jq -e .` gate, see `tests/test-bug7-poll-partial-write.sh`).
+2. **`reapProducer` = lifecycle.** Once the Leader accepts a sentinel (validateArtifact passes), it MUST kill the producing TUI pane and chmod-lock the file. Skipping the reap leaves a self-reviewing claude/codex pane that overwrites the artifact mid-poll (Bug #7).
+3. **Strict ordering: detect → reap → wait shell → next dispatch.** The Leader does NOT dispatch the next role (Verifier after Worker, next-iter Worker after Verifier) until the producing pane's `pane_current_command` has returned to `zsh|bash|sh`. AC-H1 of PR-0b-narrow strengthens this with `waitForProcessExit`.
+4. **First-writer-wins for terminal sentinels.** `blocked.md` and `complete.md` are written via `O_EXCL` (`writeSentinelExclusive`); concurrent error paths cannot trample the canonical exit reason.
+
+The same contract is implemented twice (`src/node/runner/campaign-main-loop.mjs` for `--mode agent`, `src/scripts/run_ralph_desk.zsh` for `--mode tmux`) with bit-for-bit parity on `(reason_text, reason_category, failure_category)` — verified by `tests/test-bug8-refuse-synthesis.sh` Scenario 4.
+
+---
+
+## 2. omc-teams Comparison (mailbox dir, daemon-backed CLI)
+
+[omc-teams](https://github.com/oh-my-claudecode) delivers multi-agent coordination over a **daemon-backed CLI** (`omc team api ...`). Producers append to a per-team mailbox directory; consumers tail it. The reliability contract is enforced by the daemon process, not by file polling.
+
+**What omc-teams gives you:**
+
+- Crash-safe append-only message log (no truncated JSON window).
+- Per-team subscription with backpressure.
+- Cross-process delivery guarantees (daemon survives subprocess restart).
+
+**What's load-bearing in the reliability gain — and what's not:**
+
+The reliability gain is the **daemon**, not the mailbox dir. A bare file-mailbox (without daemon) inherits the same partial-write and self-review failure modes that rlp-desk's sentinel path already guards against, plus a new failure mode: a Worker prompt that misbehaves and dumps multiple JSON files into the mailbox (no single-writer invariant). Architect findings recorded in ralplan iter 6:
+
+> Mailbox-dir without a daemon = same polling reliability as the sentinel approach + worker-prompt failure-mode increase. Adopting it as an intermediate step is strictly worse than the current contract.
+
+So if rlp-desk wants the actual omc-teams reliability profile, it must adopt the **daemon**, not just the directory layout. That is the `Track B` work, not a sentinel rewrite.
+
+---
+
+## 3. claude code `/team` Comparison (in-process TeamCreate + SendMessage)
+
+The Claude Code SDK exposes `TeamCreate` + `SendMessage` for in-process subagent coordination. This is fundamentally different:
+
+| Property | rlp-desk sentinel | claude `/team` |
+|---|---|---|
+| Process model | Standalone tmux runner | Single-process subagent tree |
+| IPC channel | Filesystem | In-memory message bus |
+| Failure mode | Pane death, partial write | Subagent throw |
+| Lifetime | Survives leader exit | Dies with parent |
+
+`/team` is **not applicable** to a standalone tmux runner. rlp-desk explicitly supports the use case where the Leader can crash, the user can detach the tmux session, and a fresh Leader process can resume against the on-disk sentinel state. `/team` cannot be paused, snapshotted, or resumed across processes — by design.
+
+---
+
+## 4. Why rlp-desk does NOT adopt mailbox-dir
+
+Architect/Critic codex consensus iter 6 rejected swapping the sentinel contract for a mailbox-dir for three concrete reasons:
+
+1. **No reliability gain without the daemon.** Section 2 above. The daemon is the load-bearing piece; the directory is a side-effect of the daemon's protocol.
+2. **Increased Worker-prompt failure surface.** Today the Worker is held to a single-writer contract: it MUST write `iter-signal.json` exactly once. A mailbox flips this to "append any number of messages and the daemon picks the latest" — a much weaker prompt-side invariant that empirically breaks under the kind of multi-pass self-review failures that Bug #7 was created to fix.
+3. **Migration cost without commensurate benefit.** Two implementations (Node + zsh), Self-Verification Gate matrix (LOW/MEDIUM/CRITICAL × `--mode tmux/agent`), backwards compatibility for in-flight campaigns, and downstream wrapper tools (analytics, blueprints, Test Spec) all assume the sentinel contract. Replacing it is a multi-PR migration with no incremental win until the daemon ships.
+
+The bug-fix track (Bug #6 worker-dead, Bug #7 post-sentinel-race, Bug #8 refuse-synthesize) closes the actual reliability gaps inside the sentinel contract and is strictly cheaper than the mailbox migration.
+
+---
+
+## 5. Track B Roadmap — daemon-backed `rlp-desk team api`
+
+When the project is ready to adopt the omc-teams reliability profile, the migration looks like this:
+
+**Track B — Phase 1 (PoC, separate ralplan):**
+- New CLI: `rlp-desk team api start|stop|status|send|recv`
+- Daemon process (`rlp-desk-teamd`) owns a per-campaign mailbox under `~/.rlp-desk/team/{slug}/`.
+- Leader and Workers route through the CLI; no direct file polling.
+- File-system fallback retained for the migration window — daemon down ⇒ degrade to sentinel mode.
+
+**Track B — Phase 2 (cutover):**
+- Sentinel reads behind a feature flag (`RLP_TEAM_API=1`).
+- Self-Verification Gate matrix extended: each scenario runs once per backend (sentinel + team-api).
+- Wrapper tools (analytics, blueprints) updated to consume the new event stream.
+
+**Track B — Phase 3 (deprecation):**
+- Sentinel path removed from runtime once team-api has burned in for ≥1 release.
+- Documentation rolled forward; `signal-protocol-v1` archived.
+
+Dependencies:
+- Daemon implementation (~600 LoC Node, drawing on Bun's IPC primitives or plain `node:net`).
+- Integration test harness for daemon crash recovery.
+- Self-Verification Gate parity matrix (Node × zsh × team-api).
+
+This track is **explicitly out of scope** for the Bug #6/#7/#8 plan v6. It is captured here so future maintainers do not interpret "rlp-desk does not use a mailbox" as an oversight — it is a deliberate architectural decision with a known successor path.

package/install.sh

@@ -115,6 +115,8 @@ fetch "$REPO_URL/docs/rlp-desk/getting-started.md" "$DESK_DIR/docs/rlp-desk/gett
 fetch "$REPO_URL/docs/rlp-desk/protocol-reference.md" "$DESK_DIR/docs/rlp-desk/protocol-reference.md"
 fetch "$REPO_URL/docs/rlp-desk/TODO-verification-next.md" "$DESK_DIR/docs/rlp-desk/TODO-verification-next.md"
 fetch "$REPO_URL/docs/rlp-desk/multi-mission-orchestration.md" "$DESK_DIR/docs/rlp-desk/multi-mission-orchestration.md"
+# Plan v6 PR-0a: signal protocol documentation
+fetch "$REPO_URL/docs/rlp-desk/signal-protocol.md" "$DESK_DIR/docs/rlp-desk/signal-protocol.md"
 # Dev meta docs (v5.7 §4.15: under docs/rlp-desk/ to avoid mixing with user docs)
 fetch "$REPO_URL/docs/rlp-desk/internal/verification-policy-gap-analysis.md" "$DESK_DIR/docs/rlp-desk/internal/verification-policy-gap-analysis.md"
 fetch "$REPO_URL/docs/rlp-desk/internal/verification-strategy-research.md" "$DESK_DIR/docs/rlp-desk/internal/verification-strategy-research.md"