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

package/CHANGELOG.md

@@ -0,0 +1,82 @@
+# Changelog
+
+All notable changes to `@ai-dev-methodologies/rlp-desk` are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to [Semantic Versioning](https://semver.org/).
+
+For pre-v0.15.4 versions, refer to `git log` and individual GitHub release notes.
+
+## [Unreleased]
+
+### Planned (not yet shipped)
+- v0.15.5 candidate: flip `RLP_LIFECYCLE_METRICS=1` default to ON (gated on 3 consecutive nightly real-LLM SV passes per `docs/plans/v0.15.4-release-runbook.md` §7.5.2).
+- Post-v0.15.6: remove `RLP_LIFECYCLE_METRICS` flag entirely (per plan v3 ADR follow-ups).
+- Phase D.1 (handoff documents) + Phase D.2 (per-stage agent role specialization) — both deferred per `docs/plans/v0.15.4-release-runbook.md` §7.6.
+
+## [0.15.4] — 2026-05-08 (pending release)
+
+Phase B: tmux/process lifecycle hardening + observability + real-LLM SV strengthening. 4 sequential PRs (B1, B2-FIX, B4, B3) merged to main, plus pre-release audit fix branch addressing 16 findings (3 CRITICAL, 6 HIGH, 5 MEDIUM, 2 LOW).
+
+### Added
+- `RLP_LIFECYCLE_METRICS=1` env flag enables structured tmux/process lifecycle telemetry. Five metrics emitted per iteration:
+  - `iter_signal_write_to_read_ms` — Worker FS write → leader poll resolve
+  - `verdict_write_to_read_ms` — Verifier FS write → leader poll resolve
+  - `pane_eof_to_cleanup_ms` — kill-start → `killPaneProcess` return
+  - `pane_reap_latency_ms` — done-claim observe → pane shell-idle
+  - `sentinel_lock_to_unlock_ms` — per-type, lock vs unlock pair
+  - Default OFF; zero overhead when unset.
+  - Lands in `debug.log` (LIFECYCLE category) and batched per iter into `campaign.jsonl.lifecycle_metrics`.
+- `RLP_DESK_NODE_PATH` env override for SV scenarios. Lets the operator point bug-05 / bug-07 at a source-tree leader (`<repo>/src/node/run.mjs`) for pre-merge AC3.1a sampling.
+- `B3_STAGE2_BLOCKING=1` env flag. Promotes B3 Stage 2 lifecycle-band assertions from non-blocking (informational) to release-blocking. Operator opts in after a 3-night PASS streak per release runbook §7.5.2.
+- `docs/rlp-desk/failure-modes.md` — FMEA-style consolidated failure modes atlas (origin: omc-team Gotchas pattern). 14 entries across 6 categories.
+
+### Fixed
+- Bug #5/7 done-claim race window (PR-B2-FIX). Worker pane is now reaped (`_kill_pane_process`) and `done-claim.json` sentinel locked (`chmod 0o444`) at the moment leader observes done-claim. Previously the pane lingered 30-120s post-write and could revise the artifact.
+  - Four substrate sites fixed: `run_ralph_desk.zsh` codex-exit synth path / A4 fallback inline path / post iter-signal reaper, `campaign-main-loop.mjs` Node leader worker reap.
+- B3 Stage 2 jq false-PASS (audit C1). Pre-compute entry count via `jq flatten | length`; SKIP when zero entries instead of falsely matching `max=0` against the band.
+- B3 scenarios circular pre-merge gate (audit C2). bug-05 / bug-07 honor `RLP_DESK_NODE_PATH`; pre-merge AC3.1a sample is now achievable.
+- A2 dry-run placement (audit C3). Runbook splits into A2 (pre-bump: tolerate EPUBLISHCONFLICT, verify auth + tarball) and A2' (post-bump: strict exit-0 dry-run).
+- A5 trigger-file oracle anchor (audit H1). Uses runtime-derived commit SHA of the prior version-bump commit, not a non-existent `vX.Y.Z` git tag.
+- markLockStart timestamp inversion (audit H3). Moved BEFORE `lockSentinel` chmod in reapProducer so `sentinel_lock_to_unlock_ms` covers full lock duration including chmod execution.
+
+### Strengthened
+- Real-LLM SV scenarios bug-05 (worker-dead-on-reuse) and bug-07 (post-sentinel-race) now run two-stage assertions when invoked with `RLP_LIFECYCLE_METRICS=1`:
+  - Stage 1 (presence): `lifecycle_metrics` field non-null in `campaign.jsonl`.
+  - Stage 2 (value): observed metrics within tolerance bands. Default NON-BLOCKING; flip to BLOCKING via `B3_STAGE2_BLOCKING=1`.
+- bug-06 retains structural-only check ($0 cost; deterministic injection deferred to PR-B5 per ADR follow-ups).
+- New unit tests:
+  - `tests/node/test-sentinel-reaper-invariant.test.mjs` — 6 invariant cases including B2-FIX primary target (case 5: done-claim ALIVE pane → reap).
+  - `tests/node/test-lifecycle-metrics.test.mjs` — 10 LifecycleMetricsCollector cases.
+  - `tests/node/test-campaign-jsonl-shape.test.mjs` — 4 shape contract cases (flag-on/off + sentinel context).
+  - `tests/node/test-b3-band-revalidation.test.mjs` — 17 cases for revalidation harness pure helpers (audit L2).
+  - `tests/node/us006-campaign-main-loop.test.mjs` — Bug-7-C-negative case added (audit M1).
+  - `tests/test_b2fix_sentinel_lock.sh` — 9 zsh PART-A code-pattern + PART-B helper-behavior assertions.
+- sv-gate-fast: 48 → 71 (+23 guards across B2-FIX, B4, B3, audit fixes).
+- Node test suite: 339 → 377 (+38 cases).
+
+### Documentation
+- `docs/plans/v0.15-phase-b-lifecycle-audit.md` — B1 lifecycle audit (sentinel write-attribution, B4 metric proposal, ASCII diagrams). §4.5 appended with empirical revalidation update (audit H4).
+- `docs/plans/v0.15-phase-b-plan-v3.md` — APPROVED ralplan plan v3 (Planner→Architect→Critic).
+- `docs/plans/v0.15-phase-b3-revalidation-findings.md` — pre-merge band revalidation findings (synthetic vs empirical drift, refit table).
+- `docs/plans/v0.15.4-pre-release-audit.md` — operator audit found 16 issues + 4 false positives. §9 per-finding fix status added.
+- `docs/plans/v0.15.4-release-runbook.md` — release runbook with 7-phase pipeline (4 user gates), nightly schedule (§7.5), deferred follow-ups (§7.6 Phase D), failure-mode summary (§8).
+
+### Internal (packaging)
+- npm tarball no longer ships internal planning documents (`docs/plans/`). User-facing reference docs at `docs/rlp-desk/` continue to ship unchanged. `package.json` `files` glob narrowed from `"docs/"` to `"docs/rlp-desk/"`. Saves ~280KB per install.
+
+### Migration notes
+- No breaking changes. Existing 0.15.3 installations should upgrade smoothly via `npm install -g @ai-dev-methodologies/rlp-desk@0.15.4`. The postinstall script unlocks 0o444-protected files before overwriting (per CLAUDE.md upgrade-path EACCES guard).
+- New `RLP_LIFECYCLE_METRICS` env flag defaults OFF — no behavior change for existing pipelines.
+- Real-LLM SV scenarios accept new `RLP_DESK_NODE_PATH` env override but default to installed leader (backwards-compatible).
+
+## [0.15.3] — earlier release
+
+See git log: `git log e0efaba` (chore: bump version to 0.15.3) for the 0.15.3 history.
+
+## Older versions
+
+For changelog-style notes prior to 0.15.4, refer to:
+- `git log <version-bump-commit>` for each `chore: bump version to X.Y.Z` commit
+- GitHub Releases at https://github.com/ai-dev-methodologies/rlp-desk/releases
+- `docs/plans/v0.15-stabilization-plan.md` for v0.15.x stabilization track context
+
+[Unreleased]: https://github.com/ai-dev-methodologies/rlp-desk/compare/v0.15.4...HEAD
+[0.15.4]: https://github.com/ai-dev-methodologies/rlp-desk/compare/v0.15.3...v0.15.4

package/README.md

@@ -524,12 +524,42 @@ mkdir my-calc && cd my-calc
 /rlp-desk run loop-test
 ```
 
+## Lifecycle Observability (v0.15.4+)
+
+Set `RLP_LIFECYCLE_METRICS=1` before invoking the runner to enable structured tmux/process lifecycle telemetry. Default: OFF (zero overhead when unset).
+
+```bash
+RLP_LIFECYCLE_METRICS=1 node ~/.claude/ralph-desk/node/run.mjs run my-slug --mode tmux
+```
+
+When enabled, five metrics are emitted per iteration:
+
+| Metric | Meaning |
+|---|---|
+| `iter_signal_write_to_read_ms` | Worker FS write → leader poll resolve |
+| `verdict_write_to_read_ms` | Verifier FS write → leader poll resolve |
+| `pane_eof_to_cleanup_ms` | Kill-start → `killPaneProcess` return |
+| `pane_reap_latency_ms` | done-claim observe → pane shell-idle |
+| `sentinel_lock_to_unlock_ms` | per sentinel type, lock vs unlock pair |
+
+**Where they land:**
+- `debug.log` — `[LIFECYCLE]` tagged lines (per emission)
+- `campaign.jsonl` — batched `lifecycle_metrics` object per iteration record (canonical authoritative source)
+
+**When to enable:**
+- Investigating tmux race windows or leader-poll latency
+- Pre-merge real-LLM SV scenarios (`bug-05` / `bug-07` two-stage assertions consume this telemetry)
+- Long-running campaigns where lifecycle SLO tracking matters
+
+**See also:** `docs/rlp-desk/failure-modes.md` for known race patterns the metrics catch.
+
 ## Documentation
 
-- [Architecture](docs/architecture.md) — Design philosophy, Agent() and tmux execution modes
-- [Getting Started](docs/getting-started.md) — Step-by-step tutorial with the calculator example
-- [Protocol Reference](docs/protocol-reference.md) — Full protocol specification
-- [Future Plans](docs/TODO-verification-next.md) — P3 items and upcoming features
+- [Architecture](docs/rlp-desk/architecture.md) — Design philosophy, Agent() and tmux execution modes
+- [Getting Started](docs/rlp-desk/getting-started.md) — Step-by-step tutorial with the calculator example
+- [Protocol Reference](docs/rlp-desk/protocol-reference.md) — Full protocol specification
+- [Failure Modes Atlas](docs/rlp-desk/failure-modes.md) — known failure patterns + recovery procedures
+- [Future Plans](docs/rlp-desk/TODO-verification-next.md) — P3 items and upcoming features
 
 ## Contributing
 

package/docs/rlp-desk/failure-modes.md

@@ -0,0 +1,191 @@
+# rlp-desk Failure Modes Atlas
+
+> Origin: 2026-05-08 (audit B-NEW-1, derived from omc-team's "Gotchas" pattern). Single canonical reference for known failure modes across the rlp-desk substrate. Each entry is FMEA-style: cause → symptom → detection → recovery.
+
+This atlas consolidates Bug #5/6/7/8/10 + lifecycle race + sentinel contention failure patterns. New failure modes are added here once verified, with a back-link to the originating bug report or audit doc.
+
+---
+
+## §1 — Subprocess lifecycle (tmux + Worker/Verifier panes)
+
+### F1.1 — Worker pane idle false-positive (Bug #6)
+| Field | Value |
+|---|---|
+| Symptom | Leader marks worker as "no progress" while iter-signal.json was already written |
+| Root cause | Worker TUI returns to idle prompt after writing sentinel; capture-pane shows stasis byte-equality without observing the FS write |
+| Detection | `tests/test-bug6-worker-idle-false-positive.sh`; `_worker_pane_has_signal` short-circuit in `check_no_progress` |
+| Recovery | Existing fix-M short-circuits BLOCKED escalation when iter-signal.json is present. No operator action required |
+| Reference | `src/scripts/run_ralph_desk.zsh` `_worker_pane_has_signal` helper |
+
+### F1.2 — Post-sentinel pane race (Bug #7)
+| Field | Value |
+|---|---|
+| Symptom | Verify-verdict.json mtime drifts 30-120s after leader observes it; iter-N+1 worker dispatched while iter-N verifier's pane is still alive |
+| Root cause | Without explicit teardown, claude/codex TUI continues self-reviewing after sentinel write |
+| Detection | `tests/sv-real-llm/scenarios/bug-07-post-sentinel-race.test.sh` (real-LLM), `tests/node/test-sentinel-reaper-invariant.test.mjs` (unit) |
+| Recovery | `_kill_pane_process` (Bug #7 Fix-Q) at zsh `lib_ralph_desk.zsh:257-272` and Node `pane-manager.mjs:91-116`. `_lock_sentinel` (Fix-R) freezes the file mtime |
+| Reference | Bug #7 PR-A; v0.15.4 PR-B2-FIX extends to done-claim sentinel |
+
+### F1.3 — done-claim race (v0.15.4 PR-B2-FIX target)
+| Field | Value |
+|---|---|
+| Symptom | Worker writes done-claim.json then idles 30-120s before iter-signal.json. Worker may revise done-claim mid-flight; A4 fallback synthesizes signal from a stale done-claim |
+| Root cause | Original Bug #7 Fix-Q only reaped at iter-signal observation. Done-claim was unguarded |
+| Detection | `tests/node/test-sentinel-reaper-invariant.test.mjs` case 5 (done-claim ALIVE pane → kill) |
+| Recovery | `_kill_pane_process` + `_lock_sentinel "$DONE_CLAIM_FILE"` at 4 substrate sites (3 zsh + 1 Node). See `docs/plans/v0.15-phase-b-plan-v3.md` §B2-FIX |
+| Reference | v0.15.4 commit `2b5af6c`; audit `docs/plans/v0.15.4-pre-release-audit.md` §1 C2 |
+
+### F1.4 — Worker dead on reuse (Bug #5)
+| Field | Value |
+|---|---|
+| Symptom | At iter-N+1 entry, leader dispatches into a previously-killed worker pane; tmux returns "can't find pane" |
+| Root cause | `_r12_check_lifecycle` not enforced strictly enough between iters |
+| Detection | `tests/sv-real-llm/scenarios/bug-05-worker-dead-on-reuse.test.sh`; `[r12]` log markers |
+| Recovery | R12 lifecycle monitor at iter-entry: detect dead pane within 5s budget → either replace pane OR write BLOCKED with infra_failure (no silent advance) |
+| Reference | Bug #5 BOS 2026-05-05 |
+
+### F1.5 — Worker incomplete with leader fallback (Bug #8)
+| Field | Value |
+|---|---|
+| Symptom | Codex worker exits without writing iter-signal.json; leader synthesizes one from done-claim, but tree may be dirty |
+| Root cause | Pre-Bug-#8: leader synthesized verify signal whenever done-claim existed, regardless of git state. Caused false PASSes when worker bailed mid-write |
+| Detection | `_bug8_check_synth_allowed` 3-gate (done-claim present + git OK + tree clean); 4 BLOCK_TAGS variants |
+| Recovery | Refuse synthesis on Gate 1/2/3 fail; write BLOCKED sentinel with appropriate failure_category (infra_failure / metric_failure) |
+| Reference | Bug #8 PR-B; src/scripts/run_ralph_desk.zsh L644-695 |
+
+### F1.6 — Operator-recovery artifact mismatch (Bug #10)
+| Field | Value |
+|---|---|
+| Symptom | Operator manually clears BLOCKED sentinel + writes iter-signal/done-claim, but artifacts mismatch status.json or have stale mtime |
+| Root cause | No validation pass when leader resumes from operator-cleared BLOCKED state |
+| Detection | `_validate_operator_recovery_artifacts` 5-gate (file exists, parses, us_id matches, iteration matches, mtime > prompt mtime); `tests/node/test-blocked-recovery-hygiene.test.mjs` |
+| Recovery | Pre-resume validator returns 0 only when all 5 gates pass; sets `RECOVERY_FAIL_REASON` for caller logging on failure |
+| Reference | PR-A Bug #10; lib_ralph_desk.zsh L298-380 |
+
+---
+
+## §2 — Sentinel file contention
+
+### F2.1 — Concurrent write-during-read window
+| Field | Value |
+|---|---|
+| Symptom | Leader's `jq` parse on iter-signal.json fails with "unexpected EOF" when polled mid-write |
+| Root cause | Worker writes sentinel non-atomically; leader's poll catches a partial state |
+| Detection | "JSON not yet valid — continue polling" log entry; `tests/node/test-sentinel-exclusive.mjs` |
+| Recovery | `writeSentinelExclusive` uses O_EXCL; `_lock_sentinel` chmod 0o444 prevents post-observe rewrite; jq -e parse retried on next poll tick |
+| Reference | v5.7 §4.24 file-guarantee contract; sv-gate-fast §4.24 checks |
+
+### F2.2 — Locked sentinel blocks next iter's writer
+| Field | Value |
+|---|---|
+| Symptom | Iter-N+1 worker EACCES on iter-signal.json write because iter-N lock (chmod 0o444) was never released |
+| Root cause | `_unlock_sentinel` not invoked at iter-start |
+| Detection | "Permission denied" in worker stderr; `lib_ralph_desk.zsh` lifecycle test |
+| Recovery | `unlockSentinelFile(paths.signalFile)` + `unlockSentinelFile(paths.verdictFile)` called defensively at every iter start (campaign-main-loop.mjs L1552-1555) |
+| Reference | v5.7 §4.25; campaign-main-loop.mjs unlockSentinelFile call sites |
+
+### F2.3 — Locked file orphans across upgrades
+| Field | Value |
+|---|---|
+| Symptom | npm install of new rlp-desk version EACCES on previously-locked installed files |
+| Root cause | Installed files chmod 0o444 from prior version; postinstall.js attempts straight overwrite |
+| Detection | "EACCES: permission denied" during `npm install` |
+| Recovery | `scripts/postinstall.js:163-167` walks installed dir, chmod 0o644 BEFORE copy; user-facing fallback documented in S1 runbook (`npm uninstall -g` first) |
+| Reference | scripts/postinstall.js unlock-walk; v0.15.4 S1 rollback runbook |
+
+---
+
+## §3 — Telemetry & observability (v0.15.4+)
+
+### F3.1 — lifecycle_metrics field absent (B4 telemetry regression)
+| Field | Value |
+|---|---|
+| Symptom | `campaign.jsonl.lifecycle_metrics` is null even when `RLP_LIFECYCLE_METRICS=1` |
+| Root cause | `LifecycleMetricsCollector` instantiated with wrong env (e.g. options.env shadows process.env) |
+| Detection | `tests/node/test-campaign-jsonl-shape.test.mjs` AC4.3 (flag-set populated case); B3 Stage 1 presence assertion |
+| Recovery | Inject explicit collector via `options.lifecycleMetrics`, OR set `env: { RLP_LIFECYCLE_METRICS: '1' }` in run() options |
+| Reference | v0.15.4 PR-B4 + audit fix C2 |
+
+### F3.2 — Stage 2 false-PASS on absent metric
+| Field | Value |
+|---|---|
+| Symptom | B3 Stage 2 assertion PASSes on band check even when telemetry never emitted |
+| Root cause | jq query collapsed `null|empty` to `max=0`; band check `0 ≤ band` always true |
+| Detection | `tests/node/test-b3-band-revalidation.test.mjs` percentile + bucket cases |
+| Recovery | Pre-compute `entry_count` via flatten\|length; SKIP when 0; only run band check on non-empty data |
+| Reference | v0.15.4 audit C1 fix; commit `21e12ed` |
+
+### F3.3 — sentinel_lock_to_unlock_ms unmeasurable for done-claim
+| Field | Value |
+|---|---|
+| Symptom | Metric never emits for done-claim sentinel even though lock IS applied |
+| Root cause | Production happy-path never calls `unlockSentinelFile(doneClaimFile)`; only signalFile + verdictFile are unlocked at iter start |
+| Detection | Inspection: `lifecycle_metrics.sentinel_lock_to_unlock_ms` array contains iter-signal.json + verify-verdict.json entries but never done-claim.json |
+| Recovery | Documented in `lifecycle-metrics.mjs` markLockStart() — done-claim intentionally excluded from this metric. Future: emit at lib_ralph_desk.zsh:602 archival site if needed |
+| Reference | v0.15.4 audit H2; commit `feb1701` |
+
+### F3.4 — Synthetic baseline drift from production
+| Field | Value |
+|---|---|
+| Symptom | B1 §4.2 synthetic numbers differ from B3 empirical p95 by >25% |
+| Root cause | Synthetic anchored to zsh leader's POLL_INTERVAL=5s; production scenarios run via Node leader (100ms poll). Different leader, different floor |
+| Detection | `tests/sv-real-llm/lib/b3-band-revalidation.mjs` runs 5-iter sandbox + compares |
+| Recovery | Refit `B3_BAND_*_MS` constants in `tests/sv-real-llm/lib/b3-lifecycle-assertions.sh`. See revalidation findings doc |
+| Reference | v0.15.4 audit H4; revalidation doc `docs/plans/v0.15-phase-b3-revalidation-findings.md` |
+
+---
+
+## §4 — Release / packaging
+
+### F4.1 — A2 dry-run before version bump
+| Field | Value |
+|---|---|
+| Symptom | `npm publish --dry-run` exits non-zero with EPUBLISHCONFLICT |
+| Root cause | Plan v6 placed A2 in preflight before Step 2 (version bump). With package.json still at prior version, dry-run targets registry-existing version |
+| Detection | First-time observed in 2026-05-07 release attempt; documented as plan defect |
+| Recovery | Split into A2 (pre-bump: tolerate EPUBLISHCONFLICT exit; verify tarball assembled) + A2' (post-bump: strict exit-0 dry-run) |
+| Reference | v0.15.4 audit C3; runbook §1 + §2 step 2.5 |
+
+### F4.2 — Internal docs leak in npm tarball
+| Field | Value |
+|---|---|
+| Symptom | npm-published tarball ships `docs/plans/*` (internal audit + planning) totaling ~280KB |
+| Root cause | package.json `files` glob entry `"docs/"` was overly broad |
+| Detection | `npm pack --dry-run \| grep "docs/plans"` (M5 verification command) |
+| Recovery | Narrow glob to `"docs/rlp-desk/"`. postinstall.js syncs only from `docs/rlp-desk/`, so this is safe |
+| Reference | v0.15.4 audit M5; commit `d26421e` |
+
+---
+
+## §5 — Add new entries
+
+When a new failure mode is identified:
+1. Pick the smallest existing §N category that fits (or §6 if none)
+2. Use the same field schema (Symptom / Root cause / Detection / Recovery / Reference)
+3. Cross-link to the originating bug doc, audit, or test
+4. Optional: add a sv-gate-fast grep guard to enforce the recovery contract
+
+When a failure mode is permanently retired:
+1. Move to §7 "Retired" (do NOT delete — historical reference)
+2. Note retirement reason (e.g., "design changed in v0.16; replaced by ...")
+
+---
+
+## §6 — Open issues (no recovery yet)
+
+### F6.1 — us006 real-tmux boundary test flakiness
+| Field | Value |
+|---|---|
+| Symptom | `tests/node/us006-campaign-main-loop.test.mjs` AC6.1 boundary case (real tmux session w/ 4 panes) intermittently fails 2-5 of 377 Node suite tests on first run; passes cleanly on retry |
+| Root cause | Real tmux session creation + pane process spawn race: `tmux send-keys` may fire before pane's shell is fully ready, causing `can't find pane` warnings (which are non-fatal but timing-sensitive assertions occasionally trip) |
+| Detection | Observed 2026-05-07 + 2026-05-08 in v0.15.4 release pipeline preflight; first-run fail-count varies 2-5 of 377 |
+| Recovery | Runbook §2 S2 retry-once policy: re-run `npm run test:node`. Second run consistently 377/377 PASS |
+| Reference | v0.15.4 release pipeline observation; runbook §7.5.3 Stage 2 INFO-band-exceeded path is unrelated but uses same retry-once mental model |
+
+**Why "open"**: the flake is in the test, not in production code. Adding retry-once to npm test:node script would mask actual regressions. Better fix: redesign the AC6.1 boundary test to use `wait-for-pane-ready` synchronization before sending keys. Deferred to a future v0.15.x patch — not release-blocking.
+
+---
+
+## §7 — Retired
+
+(none as of 2026-05-08)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-dev-methodologies/rlp-desk",
-  "version": "0.15.3",
+  "version": "0.15.4",
   "description": "Fresh-context iterative loops for Claude Code — autonomous task completion with independent verification",
   "scripts": {
     "postinstall": "node scripts/postinstall.js",
@@ -19,10 +19,11 @@
     "src/governance.md",
     "src/model-upgrade-table.md",
     "scripts/",
-    "docs/",
+    "docs/rlp-desk/",
     "examples/",
     "install.sh",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "keywords": [

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

@@ -32,6 +32,8 @@ import {
   generateSVReport,
   prepareCampaignAnalytics,
 } from '../reporting/campaign-reporting.mjs';
+import { LifecycleMetricsCollector } from '../util/lifecycle-metrics.mjs';
+import { makeDebugLogger } from '../util/debug-log.mjs';
 import {
   createPane as defaultCreatePane,
   killPaneProcess as defaultKillPaneProcess,
@@ -133,6 +135,10 @@ function buildPaths(rootDir, slug, env = process.env) {
     flywheelGuardPromptFile: path.join(deskRoot, 'prompts', `${slug}.flywheel-guard.prompt.md`),
     flywheelGuardVerdictFile: path.join(deskRoot, 'memos', `${slug}-flywheel-guard-verdict.json`),
     laneAuditFile: path.join(campaignLogDir, 'lane-audit.json'),
+    // v0.15.4 PR-B4: structured debug.log. log_lifecycle_metric (zsh) and
+    // LifecycleMetricsCollector (Node) both emit here when
+    // RLP_LIFECYCLE_METRICS=1.
+    debugLogFile: path.join(campaignLogDir, 'debug.log'),
 };
 }
 
@@ -555,7 +561,11 @@ async function _archiveRecoveredSidecar(paths) {
   }
 }
 
-async function appendIterationAnalytics(paths, state, usId, verdict, options) {
+async function appendIterationAnalytics(paths, state, usId, verdict, options, lifecycleMetrics = null) {
+  // v0.15.4 PR-B4: lifecycle_metrics field — null when flag unset (collector
+  // returns null), object grouped by metric name when flag set. Test:
+  // tests/node/test-campaign-jsonl-shape.mjs.
+  const lifecycleSnapshot = lifecycleMetrics ? lifecycleMetrics.flush() : null;
   await appendCampaignAnalytics(paths.analyticsFile, {
     iter: state.iteration,
     us_id: usId,
@@ -564,6 +574,7 @@ async function appendIterationAnalytics(paths, state, usId, verdict, options) {
     verdict,
     duration: 0,
     timestamp: toIso(resolveNow(options.now)),
+    lifecycle_metrics: lifecycleSnapshot,
   });
 }
 
@@ -1170,7 +1181,7 @@ async function runFinalSequentialVerify({
     });
 
     if (typeof reapProducer === 'function') {
-      await reapProducer(verifierPaneId, paths.verdictFile);
+      await reapProducer(verifierPaneId, paths.verdictFile, 'verify-verdict');
     }
 
     if (verdict.verdict !== 'pass') {
@@ -1368,8 +1379,20 @@ async function _runCampaignBody(slug, options, paths, rootDir) {
   const killPaneProcess = options.killPaneProcess ?? defaultKillPaneProcess;
   const lockSentinel = options.lockSentinelFile ?? defaultLockSentinelFile;
   const stampAckField = options.stampAckField ?? defaultStampAckField;
-  const reapProducer = async (paneId, sentinelFile) => {
+  // v0.15.4 PR-B4: lifecycle observability collector. Tests inject
+  // options.lifecycleMetrics for shape-contract verification; production
+  // path constructs from process.env (RLP_LIFECYCLE_METRICS=1 enables).
+  const debugLogger = makeDebugLogger(paths.debugLogFile);
+  const lifecycleMetrics = options.lifecycleMetrics ?? new LifecycleMetricsCollector({
+    env: options.env ?? process.env,
+    debugLog: (cat, fields) => debugLogger(cat, fields),
+  });
+  const reapProducer = async (paneId, sentinelFile, sentinelType = null) => {
     if (!paneId) return;
+    // v0.15.4 PR-B4: pane_eof_to_cleanup_ms = wallclock from kill-start to
+    // killPaneProcess return. pane_reap_latency_ms tracks the same window
+    // when the trigger was a sentinel observation (i.e. sentinelType set).
+    const reapStart = Date.now();
     await killPaneProcess(paneId, {
       sendRawKey,
       waitForExit: waitForProcessExit,
@@ -1384,7 +1407,22 @@ async function _runCampaignBody(slug, options, paths, rootDir) {
     } catch (err) {
       console.error(`[handshake] waitForProcessExit failed on ${paneId} (${err?.message ?? err}); continuing`);
     }
+    const reapMs = Date.now() - reapStart;
+    lifecycleMetrics.record('pane_eof_to_cleanup_ms', reapMs, { pane_id: paneId });
+    if (sentinelType) {
+      lifecycleMetrics.record('pane_reap_latency_ms', reapMs, {
+        pane_id: paneId,
+        sentinel_type: sentinelType,
+      });
+    }
     if (sentinelFile) {
+      // v0.15.4 audit H3 fix: markLockStart BEFORE lockSentinel so the
+      // sentinel_lock_to_unlock_ms metric covers the full lock duration
+      // including chmod 0o444 execution time. Previous code recorded
+      // post-chmod timestamp — sub-ms skew but semantically inverted.
+      // v0.15.4 PR-B4: open lock-to-unlock pair tracking. markUnlock fires
+      // at unlockSentinelFile call sites or end-of-iter for never-unlocked.
+      lifecycleMetrics.markLockStart(path.basename(sentinelFile));
       await lockSentinel(sentinelFile, { log: (msg) => console.error(msg) });
       // PR-0b-narrow AC-H2: stamp the leader_ack audit field. Best-effort,
       // does not block subsequent dispatch.
@@ -1516,13 +1554,15 @@ async function _runCampaignBody(slug, options, paths, rootDir) {
     // iteration must not block the next producer's atomic-rename write.
     // Idempotent: missing-file calls are no-ops.
     await unlockSentinelFile(paths.signalFile);
+    lifecycleMetrics.markUnlock(path.basename(paths.signalFile), { iter: state.iteration });
     await unlockSentinelFile(paths.verdictFile);
+    lifecycleMetrics.markUnlock(path.basename(paths.verdictFile), { iter: state.iteration });
     // Audit drift from the prior iteration before doing anything new.
     const _laneSnapshotAfter = await _snapshotLaneMtimes(paths);
     const _laneViolations = await _checkLaneViolations(paths, _laneSnapshot, _laneSnapshotAfter, state, options);
     if (_laneViolations) {
       for (const v of _laneViolations) {
-        await appendIterationAnalytics(paths, state, state.current_us ?? 'ALL', 'lane_violation_warning', { ...options, lane_violation: v });
+        await appendIterationAnalytics(paths, state, state.current_us ?? 'ALL', 'lane_violation_warning', { ...options, lane_violation: v }, lifecycleMetrics);
       }
       if (options.laneStrict) {
         // Strict mode: escalate to BLOCKED with downgrade
@@ -1658,7 +1698,7 @@ async function _runCampaignBody(slug, options, paths, rootDir) {
       }
 
       // Bug #7 Fix-Q/R: reap flywheel pane before consuming the signal.
-      await reapProducer(state.flywheel_pane_id ?? state.verifier_pane_id, paths.flywheelSignalFile);
+      await reapProducer(state.flywheel_pane_id ?? state.verifier_pane_id, paths.flywheelSignalFile, 'flywheel-signal');
 
       state.last_flywheel_decision = flywheelSignal.decision;
       // P0-A multi-mission orchestration: optionally captured from flywheel signal.
@@ -1701,7 +1741,7 @@ async function _runCampaignBody(slug, options, paths, rootDir) {
         }
 
         // Bug #7 Fix-Q/R: reap guard pane before mutating state.
-        await reapProducer(guardPaneId, paths.flywheelGuardVerdictFile);
+        await reapProducer(guardPaneId, paths.flywheelGuardVerdictFile, 'flywheel-guard-verdict');
 
         if (!state.flywheel_guard_count[state.current_us]) {
           state.flywheel_guard_count[state.current_us] = 0;
@@ -1887,10 +1927,35 @@ async function _runCampaignBody(slug, options, paths, rootDir) {
       }
     }
 
+    // v0.15.4 PR-B4: iter_signal_write_to_read_ms = wallclock from worker FS
+    // write to leader poll resolve. Sentinel mtime is the producer-side anchor;
+    // Date.now() is the leader-side anchor. Best-effort stat — if the file
+    // already lacks read perms (race vs prior lock), fall back to skip.
+    try {
+      const sigStat = fsSync.statSync(paths.signalFile);
+      lifecycleMetrics.record('iter_signal_write_to_read_ms', Date.now() - sigStat.mtimeMs, {
+        iter: state.iteration,
+        us_id: state.current_us,
+      });
+    } catch { /* fail-open: skip on stat error */ }
     // Bug #7 Fix-Q/R: reap the worker pane the instant we accept the signal so
     // claude/codex cannot self-review and rewrite iter-signal.json. Runs even
     // for the codex-fallback synthesized signal (no-op on a dead pane).
-    await reapProducer(state.worker_pane_id, paths.signalFile);
+    await reapProducer(state.worker_pane_id, paths.signalFile, 'iter-signal');
+    // v0.15.4 PR-B2-FIX: same worker pass produced done-claim. The pane is
+    // already reaped above; lock done-claim so the iter-NNN-done-claim archive
+    // and any post-iter Bug #8 gate read a snapshot the worker can no longer
+    // revise. Symmetric with the zsh lock-on-iter-signal contract at
+    // run_ralph_desk.zsh:3197. Best-effort: missing-file is fail-open.
+    //
+    // v0.15.4 audit H2 fix: NO markLockStart for done-claim. In production
+    // happy path done-claim is locked-but-never-unlocked (only signalFile +
+    // verdictFile receive iter-start unlockSentinelFile at L1552-1555), so
+    // markUnlock would never fire and the metric would silently never emit.
+    // done-claim is intentionally excluded from sentinel_lock_to_unlock_ms;
+    // the lib_ralph_desk.zsh:602 archival step is the practical lock-end
+    // event but is not currently instrumented (deferred — not B4 scope).
+    await lockSentinel(paths.doneClaimFile, { log: (msg) => console.error(msg) });
 
     // US-019 R7 P1-G: verify_partial malformed downgrade.
     // verify_partial requires verified_acs[] to be a non-empty array. Otherwise the verifier
@@ -1961,10 +2026,18 @@ async function _runCampaignBody(slug, options, paths, rootDir) {
       });
     }
 
+    // v0.15.4 PR-B4: verdict_write_to_read_ms parallel to iter_signal metric.
+    try {
+      const verdStat = fsSync.statSync(paths.verdictFile);
+      lifecycleMetrics.record('verdict_write_to_read_ms', Date.now() - verdStat.mtimeMs, {
+        iter: state.iteration,
+        us_id: state.current_us,
+      });
+    } catch { /* fail-open */ }
     // Bug #7 Fix-Q/R: reap verifier pane immediately after accepting the
     // verdict — without this the codex/claude TUI keeps running for ~2min and
     // can rewrite verify-verdict.json (mtime drift observed in 19th launch).
-    await reapProducer(state.verifier_pane_id, paths.verdictFile);
+    await reapProducer(state.verifier_pane_id, paths.verdictFile, 'verify-verdict');
 
     if (verdict.verdict === 'pass') {
       state.consecutive_failures = 0;
@@ -1973,7 +2046,7 @@ async function _runCampaignBody(slug, options, paths, rootDir) {
       }
       state.current_us = getNextUs(usList, state.verified_us, null);
       fixContractPath = null;
-      await appendIterationAnalytics(paths, state, usId, 'pass', options);
+      await appendIterationAnalytics(paths, state, usId, 'pass', options, lifecycleMetrics);
       await writeStatus(paths, state, options.onStatusChange, options.now);
 
       if (state.verified_us.length === usList.length) {
@@ -1989,7 +2062,7 @@ async function _runCampaignBody(slug, options, paths, rootDir) {
       const blockedReason = verdict.reason || verdict.summary || 'verifier-blocked';
       const blockedClassification = _classifyBlock('verifier', { verdict, state, slug });
       await writeSentinel(paths.blockedSentinel, 'blocked', usId, blockedReason, blockedClassification, paths);
-      await appendIterationAnalytics(paths, state, usId, 'blocked', options);
+      await appendIterationAnalytics(paths, state, usId, 'blocked', options, lifecycleMetrics);
       await writeStatus(paths, state, options.onStatusChange, options.now);
       let svSummary;
       if (options.withSelfVerification) {
@@ -2028,7 +2101,7 @@ async function _runCampaignBody(slug, options, paths, rootDir) {
     }
 
     state.consecutive_failures += 1;
-    await appendIterationAnalytics(paths, state, usId, 'fail', options);
+    await appendIterationAnalytics(paths, state, usId, 'fail', options, lifecycleMetrics);
     const upgradedModel = nextWorkerModel(options.workerModel ?? state.worker_model, state.consecutive_failures);
     if (upgradedModel === 'BLOCKED') {
       state.phase = 'blocked';

package/src/node/util/debug-log.mjs

@@ -6,15 +6,19 @@
 // SHOULD use debugLog() instead of console/manual writes.
 //
 // Categories (governance §1f traceability):
-// - GOV   : governance enforcement (IL, CB triggers, scope locks, verdicts)
-// - DECIDE: leader decisions (model selection, fix contracts, escalation)
-// - OPTION: configuration snapshot at loop start
-// - FLOW  : execution progress (worker/verifier dispatch, signal reads, transitions)
+// - GOV       : governance enforcement (IL, CB triggers, scope locks, verdicts)
+// - DECIDE    : leader decisions (model selection, fix contracts, escalation)
+// - OPTION    : configuration snapshot at loop start
+// - FLOW      : execution progress (worker/verifier dispatch, signal reads, transitions)
+// - LIFECYCLE : v0.15.4 PR-B4 — tmux/process lifecycle metrics gated on
+//               RLP_LIFECYCLE_METRICS=1. Emission rules: see plan v3 §B4
+//               Table (5 metrics). Helper is no-op when flag unset (verified
+//               by tests/node/test-campaign-jsonl-shape.mjs).
 
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
-const VALID_CATEGORIES = new Set(['GOV', 'DECIDE', 'OPTION', 'FLOW']);
+const VALID_CATEGORIES = new Set(['GOV', 'DECIDE', 'OPTION', 'FLOW', 'LIFECYCLE']);
 
 /**
  * Append a structured log line to debug.log. Format mirrors zsh log_debug:
@@ -22,7 +26,7 @@ const VALID_CATEGORIES = new Set(['GOV', 'DECIDE', 'OPTION', 'FLOW']);
  *
  * @param {Object} args
  * @param {string} args.debugLogPath — absolute path to debug.log
- * @param {'GOV'|'DECIDE'|'OPTION'|'FLOW'} args.category
+ * @param {'GOV'|'DECIDE'|'OPTION'|'FLOW'|'LIFECYCLE'} args.category
  * @param {Object<string,string|number|boolean>} args.fields — flat key/value
  *   pairs, serialized as `key=value`. Avoid nested objects; pre-stringify.
  * @returns {Promise<void>} — resolves even on filesystem errors (best-effort).