@ai-dev-methodologies/rlp-desk 0.15.3 → 0.15.5

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

@@ -1,184 +0,0 @@
-# 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

@@ -1,234 +0,0 @@
-# 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/pr-e-phase-c1-blocked-recovery-hygiene-v0.md

@@ -1,233 +0,0 @@
-# PR-E: Phase C1 — Blocked Sentinel Recovery Hygiene (Planner v0)
-
-> **Plan reference**: `docs/plans/v0.15-stabilization-plan.md` §5 Phase C
-> **Continuation of**: PR-A (Bug #10 phase=verify recovery, commit `95c0d4e`)
-> **Stop rule**: codex critic APPROVE (P0+P1=0) before merge
-> **Critic instruction**: approve unless P0 or P1 found
-
----
-
-## 1. Problem
-
-After PR-A landed (`phase=verify` recovery honored), the next recovery surface is **operator-cleared BLOCKED**.
-
-Today, when operator clears `<slug>-blocked.md` to recover (the documented manual recovery for some BLOCKED reasons), `status.json` retains:
-- `phase: "blocked"` (stale)
-- `consecutive_failures` and `consecutive_blocks` counters at their pre-BLOCKED values
-- `last_block_reason` populated
-
-On leader relaunch:
-1. `readCurrentState` (`src/node/runner/campaign-main-loop.mjs:364`) preserves all of these
-2. Main loop iterates, tries to dispatch worker
-3. If worker fails for any reason, `consecutive_failures` increments from its stale base
-4. Circuit breaker may trip immediately even though operator's intent was "fresh start"
-5. Result: campaign re-BLOCKs on first failure, operator's recovery effort wasted
-
-This is the same class as Bug #10 (PR-A): operator's recovery intent silently discarded because leader doesn't recognize the recovery surface.
-
----
-
-## 2. Principles (3)
-
-1. **Operator's recovery intent is the source of truth.** When BLOCKED sentinel is gone but status.json still says blocked + counters stale, the operator clearly meant to reset state. Leader must recognize and honor.
-2. **Recovery validation must be strict (mirror PR-A).** Auto-honoring without checks risks accidental honor of crashed-mid-write states. PR-A's 5-check pattern applied to the blocked-recovery context.
-3. **Defensive default — fall through, don't break.** If validation fails, log the reason and proceed with current behavior (no auto-reset). Recovery feature can never make existing flows worse.
-
-## 3. Decision drivers (top 3)
-
-| # | Driver | Why |
-|---|---|---|
-| D1 | **Operator recovery completeness** | PR-A covered phase=verify; phase=blocked is the most-common operator recovery (clear sentinel → relaunch). Closing this gap completes the pair. |
-| D2 | **Mirror PR-A pattern** | Same shape (entry-time validate + flag + audit log) reduces cognitive load for future readers. Both Node + zsh same way. |
-| D3 | **Counter reset honesty** | Operator clearing the sentinel implies intent to retry from clean state. Stale counters silently re-BLOCK = surprise. |
-
----
-
-## 4. Viable options
-
-### Option A — Entry-time blocked-recovery branch (mirror of PR-A) **[recommended]**
-
-After `readCurrentState`, before main loop, add a second recovery branch:
-- IF `state.phase === 'blocked'` AND blocked sentinel does NOT exist (operator cleared) AND counters are non-zero → **operator-cleared recovery detected**
-- Validate (5 checks, see §7)
-- On pass: reset phase to 'worker', reset counters to 0, log audit line
-- On fail: fall through (current behavior — campaign continues with stale state, may immediately re-BLOCK)
-
-Pros: surgical (single branch, ~30 LOC each side), pattern matches PR-A exactly, defensive default.
-Cons: adds another entry-time check (small overhead).
-
-### Option B — Reset on every relaunch unless explicit "preserve counters" flag
-
-Always reset counters when relaunching with no BLOCKED sentinel. Add `--preserve-counters` flag for users who want stale-counter behavior.
-
-Pros: simpler logic.
-Cons: changes existing behavior for users who didn't experience this issue. Breaks back-compat for anyone relying on counter persistence across relaunches.
-
-→ **Rejected**: violates principle 3 (defensive default).
-
-### Option C — Document operator workaround instead of code change
-
-Add cookbook entry: "after clearing blocked sentinel, also `jq` zero out counters in status.json".
-
-Pros: zero code change.
-Cons: pushes burden to operator. Same class of failure as Bug #10's pre-PR-A state — the leader should recognize recovery, not require operator jq pipelines.
-
-→ **Rejected**: violates principle 1.
-
-**Recommendation: A.**
-
----
-
-## 5. Scope
-
-### P0 — must land
-
-1. **Node leader entry-time blocked-recovery branch** (`src/node/runner/campaign-main-loop.mjs`):
-   - New helper `_validateBlockedRecovery({ paths, state })` — returns `{ ok: bool, reason: string }`. 5 checks (§7).
-   - Branch after readCurrentState (around line 1392, where PR-A branch sits) — if `phase === 'blocked'` and validator passes, reset phase + counters + log.
-
-2. **zsh runner mirror** (`src/scripts/run_ralph_desk.zsh`):
-   - Mirror helper `_validate_blocked_recovery` in `lib_ralph_desk.zsh`
-   - Mirror entry-time branch (similar location to PR-A's site at `:3047-3071` range)
-
-### P1 — must land
-
-3. **Tests**:
-   - `tests/node/test-blocked-recovery-hygiene.test.mjs` (NEW, 5 ACs):
-     - AC-BR1: phase=blocked + sentinel absent + counters non-zero + valid → reset + dispatch worker normally
-     - AC-BR2: phase=blocked + sentinel PRESENT → don't auto-recover, throw "Run clean first" (existing behavior preserved)
-     - AC-BR3: phase=blocked + sentinel absent + counters all zero → fall through (nothing to reset)
-     - AC-BR4: phase=verify + sentinel absent → defer to PR-A's branch (no double-handling)
-     - AC-BR5: phase=blocked + sentinel absent + last_block_reason indicates non-recoverable category (`mission_abort`) → fall through, log "non-recoverable category, manual review needed"
-   - `tests/test-blocked-recovery-zsh.sh` (NEW, 5 helper-level scenarios mirroring AC-BR1..5)
-
-### P2 — nice-to-have (deferred)
-
-- Cookbook entry in `docs/rlp-desk/getting-started.md` documenting the recovery flow now that leader honors it
-- Telemetry analytics — track how often operator-cleared recovery is detected (signal of campaign reliability)
-
----
-
-## 6. Files to modify
-
-| File | Change | Risk |
-|---|---|---|
-| `src/node/runner/campaign-main-loop.mjs` | `_validateBlockedRecovery` helper + entry-time branch | LOW (pattern proven by PR-A) |
-| `src/scripts/lib_ralph_desk.zsh` | `_validate_blocked_recovery` helper | LOW |
-| `src/scripts/run_ralph_desk.zsh` | Entry-time branch (near `:3047-3071` range) | LOW |
-| `tests/node/test-blocked-recovery-hygiene.test.mjs` (NEW) | 5 ACs | LOW |
-| `tests/test-blocked-recovery-zsh.sh` (NEW) | 5 zsh scenarios | LOW |
-
-Total: 3 modified + 2 new = 5 files. Smaller surface than PR-A.
-
----
-
-## 7. Validator: 4 checks (`_validateBlockedRecovery`) — Codex-revised v2
-
-Codex critic P1-1 finding: v1's Check 4 depended on `last_block_reason` field but **no code path persists that field to status.json**. Both Node `_emitBlockedSentinel` and zsh `write_blocked_sentinel` skip it. So the v1 validator would never block auto-recovery for mission_abort/repeat_axis — exactly the safety case it was designed for.
-
-**v2 fix**: detect non-recoverable categories from the **`<slug>-blocked.json` sidecar** (which `_emitBlockedSentinel` DOES write at L942-965, with `reason_category` + `recoverable` fields), not from status.json. The sidecar persists even when operator manually `rm <slug>-blocked.md` — they don't usually delete the sidecar.
-
-Returns `{ ok: bool, reason: string }`:
-
-1. `state.phase === 'blocked'` (precondition)
-2. Blocked sentinel `<slug>-blocked.md` does NOT exist (operator cleared)
-3. At least one of: `consecutive_failures > 0`, `consecutive_blocks > 0` (something to reset; if all counters zero, fall through — nothing to recover from)
-4. **Sidecar safety check**: if `<slug>-blocked.json` exists AND parses AND has `recoverable: false` → fall through with audit log "non-recoverable category <reason_category> from sidecar". If sidecar absent (e.g. user ran full `clean`) OR sidecar `recoverable: true` → proceed with auto-recovery. Mirrors `_classifyBlock` `recoverable` invariant; no new status field needed.
-
-(Check 5 from v0 — 30-day staleness — DROPPED. Architect-flagged as arbitrary.)
-
-On pass: caller resets `state.phase = 'worker'`, `state.consecutive_failures = 0`, `state.consecutive_blocks = 0`. Sidecar (if exists) is RENAMED to `<slug>-blocked.json.recovered-<iso>` for audit trail rather than deleted, so operator can inspect what was recovered from. Then logs:
-
-```
-[recovery] Operator-cleared BLOCKED detected (was: <last_block_reason>). Resetting counters and resuming as worker. iter=N us_id=<current_us>
-```
-
-On fail: log `[recovery] phase=blocked ignored: <reason>` and fall through to existing behavior.
-
----
-
-## 8. Pre-mortem (3 scenarios)
-
-### S1 — Auto-recovery hides genuine problem
-Campaign keeps BLOCKING because of a real architectural issue. Operator clears sentinel each time. Auto-recovery resets counters → CB never trips → infinite loop of fail+clear.
-
-**Mitigation**: operator-cleared recovery is exactly that — operator chose to retry. If they keep clearing without fixing, the bug pattern is operator behavior, not leader's. Counters resetting is correct; CB still trips on the freshly-accumulated counters from current session. Leader doesn't enable infinite loops, operator does.
-
-**Residual risk**: low. If operator wants CB to persist across relaunches, they can leave the sentinel and use `clean` workflow instead.
-
-### S2 — Mid-write status.json read produces inconsistent state
-A previous leader instance crashed mid-`writeStatus`. Relaunch reads partial JSON.
-
-**Mitigation (corrected per Codex critic P2 backlog)**: `writeStatus` uses `writeJson` → `fs.writeFile` directly (NOT atomic rename). Partial writes are theoretically possible. If JSON is malformed, `readJsonIfExists` THROWS (not returns null) — leader fails fast at startup with parse error, surfacing the corruption to operator. Auto-recovery never proceeds because leader doesn't even reach the validator. This is acceptable: corrupted status.json is operator-visible immediately, not silently recovered. P2 backlog item: consider migrating writeStatus to atomic rename for crash safety, but that's a separate PR.
-
-### S3 — Race: operator clears sentinel while leader is starting
-Operator deletes blocked.md just as leader's `await exists(paths.blockedSentinel)` runs. Two outcomes:
-- Sentinel exists during check → existing "Run clean first" error throws (existing behavior, unchanged)
-- Sentinel missing during check → enters validator → if checks pass, recovery proceeds
-
-**Mitigation**: this is a benign race. Both outcomes are valid (operator either succeeded in clearing or didn't). No corruption possible.
-
----
-
-## 9. Test plan
-
-### Unit (Node)
-
-`tests/node/test-blocked-recovery-hygiene.test.mjs`:
-
-Each AC sets up a fixture (status.json + memos/) per its scenario, runs the leader to first dispatch decision, asserts on dispatch behavior + log content.
-
-- AC-BR1 happy: setup phase=blocked, sentinel absent, consecutive_failures=3 → assert leader dispatches worker (not throw), assert state.consecutive_failures === 0 in next status write, assert audit log line matches
-- AC-BR2 sentinel present: setup phase=blocked, sentinel exists → assert leader throws "Run clean first" (existing behavior preserved)
-- AC-BR3 nothing to reset: phase=blocked, sentinel absent, all counters zero, last_block_reason empty → assert fall-through (no log line, no reset, normal worker dispatch)
-- AC-BR4 phase=verify defers: phase=verify, sentinel absent → assert PR-A logic runs (no blocked recovery handling)
-- AC-BR5 non-recoverable category: phase=blocked, sentinel absent, last_block_reason='mission_abort' → assert fall-through with log "non-recoverable category"
-
-### Integration (zsh)
-
-`tests/test-blocked-recovery-zsh.sh` (helper-level, mirrors `test-bug10-zsh-relaunch-hygiene.sh`):
-
-- Scenario BR-Z1: all 5 checks pass → `_validate_blocked_recovery` returns 0
-- Scenarios BR-Z2..BR-Z5: each check fails → returns 1 with reason matching expected substring
-
-### Regression
-
-- Full Node suite: 334/334 must remain green
-- Bug #10 PR-A tests (test-relaunch-phase-verify-hygiene.test.mjs) must remain green
-- Bug #7 zsh regression must remain green
-
----
-
-## 10. Verification end-to-end
-
-1. `node --test tests/node/test-blocked-recovery-hygiene.test.mjs` → 5/5 PASS
-2. `bash tests/test-blocked-recovery-zsh.sh` → 5/5 PASS
-3. Full Node suite + Bug #7 regression unchanged green
-4. **`zsh tests/sv-gate-fast.sh` PASS** (governance §1g pre-merge gate, Codex critic P1-2)
-5. Manual sandbox: deliberately BLOCKED campaign → operator clears blocked.md → relaunch → leader logs `[recovery] Operator-cleared BLOCKED detected`, counters reset, worker dispatches, campaign continues. Repeat with `recoverable: false` sidecar → leader logs fall-through, no auto-recovery.
-6. **AC-BR5 fixture must use real `_emitBlockedSentinel` flow** (Codex critic P1-1) — write a sentinel via the actual code path, then test recovery against it. Not hand-authored status.json.
-
-**Release (NOT part of this PR's verification — per Codex critic P1-2 + CLAUDE.md absolute rules)**: any version bump, GitHub release, or npm publish is a SEPARATE user-approved action that follows merge. This PR's verification ends at items 1-6 above. Release decisions are not auto-flow.
-
----
-
-## 11. ADR (preview)
-
-- **Decision**: extend PR-A's recovery-hygiene pattern to `phase=blocked` operator-cleared scenario
-- **Drivers**: D1 operator-recovery completeness, D2 mirror PR-A pattern, D3 counter reset honesty
-- **Alternatives considered**: B (always reset, breaks back-compat), C (doc-only, pushes burden to operator)
-- **Why chosen**: A surgical, pattern-proven, defensive default, completes Phase C1 without scope creep
-- **Consequences**: operator-cleared BLOCKED relaunches now work as intended; no need for jq counter-reset cookbook; logs add `[recovery]` lines visible via `/rlp-desk logs`
-- **Follow-ups**: Phase C2 (mid-iter crash recovery), Phase C3 (cross-mission queue recovery), Phase C4 (cookbook entry)
-
----
-
-## 12. Round-by-round resolution log
-
-| Round | Reviewer | Verdict | Findings |
-|---|---|---|---|
-| 0 | — | Planner v0 | initial draft |
-| 1 | Architect (Claude inline) | ITERATE | 5 edits applied → v1: drop 30-day, add previous_block_reason, expand Check 4 prose, branch ordering, _skipNextWorkerDispatch comment |
-| 2 | Codex Critic | ITERATE — 0 P0, 2 P1 | P1-1: Check 4 redesigned to use `<slug>-blocked.json` sidecar `recoverable` field (status.json never persists `last_block_reason`). P1-2: §10.5 release auto-flow removed; SV gate + user approval explicit. P2: S2 mitigation prose corrected (writeJson is not atomic rename; readJsonIfExists throws not returns null). All applied → v2 (current). |
-| 3 | Codex Critic | **APPROVE** — 0 P0, 0 P1 | P1-1/P1-2 both closed. §7 sidecar-based gate validated. §10 sv-gate + user-approved release confirmed. **Loop terminated. Implementation can proceed.** |