@ai-dev-methodologies/rlp-desk 0.15.6 → 0.17.0

package/CHANGELOG.md

@@ -11,6 +11,32 @@ For pre-v0.15.4 versions, refer to `git log` and individual GitHub release notes
 - 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.17.0] — 2026-06-19
+
+**BREAKING (ADR-001): `node run.mjs run <slug> --mode agent` (the deprecated Node-leader direct-CLI alpha) now hard-errors.** Per the schedule announced in 0.16.0, the `--mode agent` entry point exits 2 with a redirect, and the Node-CLI default mode flips from `agent` to `tmux` (the canonical production leader). The `src/node/**` engine modules are retained (they back the Native Agent() path and the test suite); only the direct-CLI `--mode agent` *dispatch entry* was removed. **Migration:** replace `node run.mjs run <slug> --mode agent` with `--mode tmux`. The slash command's `--mode native` default is unaffected.
+
+### Changed
+- `node run.mjs run <slug>` (no `--mode`) now defaults to `--mode tmux` and delegates to the zsh leader, instead of the deprecated Node leader.
+
+### Fixed
+- Four shipped files referenced `docs/multi-mission-orchestration.md`; corrected to the real shipped path `docs/rlp-desk/multi-mission-orchestration.md` (dead link on fresh installs). Added a docs-link-resolve test.
+- `uninstall` now removes the `UNLOCK.md` marker (and unlocks 0o444 files before unlink), so the `ralph-desk/` directory is fully removed.
+- The A4 fallback iteration-signal write now goes through the atomic `atomic_write` helper (temp+rename) instead of a raw redirect.
+
+### Changed (packaging)
+- The shipped `examples/calculator` scaffold moved from the legacy `.claude/ralph-desk/` path to `.rlp-desk/` (v0.13.0+ convention) and no longer ships generated runtime state.
+
+## [0.16.0] — 2026-06-18
+
+Leader consolidation (ADR-001): `--mode tmux` is now the canonical production leader, self-verification works on it, and the deprecated `--mode agent` Node-CLI path is on a dated removal schedule.
+
+### Added
+- **Self-verification now works under `--mode tmux`.** `--with-self-verification` previously required the deprecated `--mode agent` path; the report is now generated by a pure-filesystem post-pass that runs after the zsh leader exits (reading the campaign's done-claim/verdict artifacts), so the canonical production path gets SV reports without the `claude --print` no-TTY hang.
+
+### Deprecated
+- **`node run.mjs run <slug> --mode agent` (Node-leader CLI alpha) is on a dated removal schedule** (ADR-001): 0.16.x louder banner → **0.17.0 hard-error** (and the Node-CLI default flips to `tmux`) → 0.18.0 dispatch branch removed. The `src/node/**` engine modules are retained throughout. Migrate direct-CLI wrappers to `--mode tmux` (canonical). This does NOT affect the slash command's `--mode native` default.
+- **The flywheel (`--flywheel` / `--flywheel-guard`) is deprecated.** It was only ever implemented in the deprecated `--mode agent` Node path (never in the canonical zsh leader, despite a stale comment that claimed otherwise). Its only output, the advisory `next_mission_candidate` field, has no shipped runnable consumer. It will not be ported to the canonical leader; use a consumer-side wrapper for multi-mission chaining.
+
 ## [0.15.6] — 2026-06-18
 
 Patch: CI/test integrity, a codex command-builder security fix, and documentation reconciliation.

package/docs/rlp-desk/getting-started.md

@@ -83,7 +83,7 @@ This creates the scaffold:
 
 ## Step 5: Customize the PRD
 
-Edit `.rlp-desk/plans/prd-loop-test.md` to define your user stories and acceptance criteria. See [`examples/calculator/`](../examples/calculator/.claude/ralph-desk/plans/prd-loop-test.md) for a complete example.
+Edit `.rlp-desk/plans/prd-loop-test.md` to define your user stories and acceptance criteria. See [`examples/calculator/`](../examples/calculator/.rlp-desk/plans/prd-loop-test.md) for a complete example.
 
 Key sections:
 - **User Stories** with Given/When/Then acceptance criteria, Task Type, and Risk Level

package/docs/rlp-desk/protocol-reference.md

@@ -649,5 +649,5 @@ an optional `next_mission_candidate` field:
 
 The leader propagates the field into `status.json`
 (`status.next_mission_candidate`). Wrappers poll either source. See
-`docs/multi-mission-orchestration.md` for the consumer-side polling
+`docs/rlp-desk/multi-mission-orchestration.md` for the consumer-side polling
 pattern.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-dev-methodologies/rlp-desk",
-  "version": "0.15.6",
+  "version": "0.17.0",
   "description": "Fresh-context iterative loops for Claude Code — autonomous task completion with independent verification",
   "scripts": {
     "postinstall": "node scripts/postinstall.js",
@@ -23,10 +23,10 @@
     "scripts/",
     "docs/rlp-desk/*.md",
     "docs/rlp-desk/blueprints/",
-    "examples/calculator/.claude/ralph-desk/context/",
-    "examples/calculator/.claude/ralph-desk/memos/",
-    "examples/calculator/.claude/ralph-desk/plans/",
-    "examples/calculator/.claude/ralph-desk/prompts/",
+    "examples/calculator/.rlp-desk/context/",
+    "examples/calculator/.rlp-desk/memos/",
+    "examples/calculator/.rlp-desk/plans/",
+    "examples/calculator/.rlp-desk/prompts/",
     "install.sh",
     "README.md",
     "CHANGELOG.md",

package/scripts/uninstall.js

@@ -25,10 +25,22 @@ const files = [
   path.join(deskDir, "init_ralph_desk.zsh"),
   path.join(deskDir, "run_ralph_desk.zsh"),
   path.join(deskDir, "lib_ralph_desk.zsh"),
+  // PKG-6: postinstall writes the UNLOCK.md escape-hatch doc into deskDir. If we
+  // skip it here, the empty-dir rmdir below always sees one leftover file and the
+  // ralph-desk/ directory is never removed.
+  path.join(deskDir, "UNLOCK.md"),
 ];
 
 for (const targetPath of files) {
   try {
+    // Installed files are write-locked (chmod 0o444) per postinstall v5.7 §4.10.
+    // Restore write permission before unlink so removal is robust across
+    // filesystems (mirrors postinstall's unlock-before-remove).
+    try {
+      fs.chmodSync(targetPath, 0o644);
+    } catch (_) {
+      // File may be missing or already writable.
+    }
     fs.rmSync(targetPath, { recursive: true, force: true });
     console.log("  - " + targetPath);
   } catch (_) {

package/src/commands/rlp-desk.md

@@ -303,7 +303,7 @@ Legacy `--mode agent` typed against this slash command emits a deprecation notic
 
 #### Tmux Mode (`--mode tmux`)
 
-When `--mode tmux` is specified (v0.14.0+: `run.mjs` accepts the same flags as before but spawns `run_ralph_desk.zsh` as a subprocess and inherits stdio. Flywheel and self-verification flags are not honored under tmux mode — they currently require the deprecated Node-leader direct-CLI path `node run.mjs --mode agent` (see "Direct Node CLI invocation" below). Native Agent() port is a post-Node-leader-retirement task):
+When `--mode tmux` is specified (v0.14.0+: `run.mjs` accepts the same flags as before but spawns `run_ralph_desk.zsh` as a subprocess and inherits stdio. ARCH Wave C: `--with-self-verification` **is honored** under tmux mode via a Node post-pass that runs after the zsh leader exits (see §348). `--flywheel`/`--flywheel-guard` are deprecated (ADR-001) and remain unimplemented in the zsh leader):
 
 1. **Validate scaffold** — same as Agent() mode: check `.rlp-desk/prompts/<slug>.worker.prompt.md` etc.
 2. **Check sentinels** — same as Agent() mode.
@@ -345,7 +345,7 @@ node ~/.claude/ralph-desk/node/run.mjs run '<slug>' \
 - MUST launch with `run_in_background: true` so `/rlp-desk` returns control immediately while preserving live tmux visibility.
 - Run-in-background is used so the shell can keep the command visible and keep the pane layout stable for status checks and completion flow.
 - Do NOT kill panes after completion. Panes stay alive for inspection. User cleans up with `/rlp-desk clean <slug> --kill-session`.
-- v0.14.0: `--with-self-verification`, `--flywheel`, and `--flywheel-guard` are **not honored** under `--mode tmux` — the zsh runner has no SV/flywheel implementation. The Node leader emits a stderr WARNING listing the dropped flags. For SV/flywheel today, use the deprecated Node-leader direct-CLI path `node run.mjs --mode agent` (see "Direct Node CLI invocation" below). The slash command's Native Agent() (`--mode native`) does not yet implement SV/flywheel — port is a post-Node-leader-retirement task.
+- ARCH Wave C (ADR-001): `--with-self-verification` **is honored** under `--mode tmux`. The zsh leader cannot generate the SV report in-pane (`claude --print` hangs without a TTY — hence its `$TMUX` early-return), so `run.mjs` runs the **pure-filesystem** `generateSVReport` as a **post-pass after the zsh child exits**, reading the campaign's on-disk done-claim/verdict artifacts. `--flywheel` and `--flywheel-guard` are **deprecated** (ADR-001) and remain unimplemented in the zsh leader; the Node leader emits a stderr WARNING for those two only. The slash command's Native Agent() (`--mode native`) does not yet implement SV/flywheel.
 - **For `--mode tmux` only**: the slash command invokes `node ~/.claude/ralph-desk/node/run.mjs run --mode tmux ...`. Do NOT invoke `~/.claude/ralph-desk/run_ralph_desk.zsh` directly — the Node router resolves the runner path, runs legacy detection, and surfaces actionable errors when the runner is missing. **For `--mode native`**, the slash command does NOT invoke the Node CLI — it acts as the leader itself; see Native Agent() Mode section below.
 
 **tmux UX model (5 items):**
@@ -374,7 +374,17 @@ This contract MUST be observed in every iteration of the leader loop below. Futu
 
 #### Direct Node CLI invocation (`node run.mjs run <slug> --mode agent` — deprecated alpha)
 
-Direct invocation of `node ~/.claude/ralph-desk/node/run.mjs run <slug> --mode agent` is **the deprecated Node-leader alpha path**. This is unrelated to the slash command's Native Agent() path above — different code, different leader, different lifecycle. The Node leader currently retains SV/flywheel implementations not yet ported to Native Agent(). The Node CLI emits a deprecation banner on this mode and is scheduled for hard-error in the next major release. For production tmux orchestration, use `--mode tmux`. For Claude Code Native Agent() campaigns, use `/rlp-desk run <slug> --mode native` from a Claude Code session.
+Direct invocation of `node ~/.claude/ralph-desk/node/run.mjs run <slug> --mode agent` **hard-errors (exit 2) as of this release** (per [ADR-001](../../docs/plans/adr-001-leader-consolidation.md) §3) — it was the deprecated Node-leader alpha path, and the dated breaking change has now landed. Direct CLI invocation redirects to `--mode tmux` (production) / `--mode native` (slash), and the **Node-CLI default mode is now `tmux`**. This is unrelated to the slash command's legacy `--mode agent` → native redirect — different code, different leader, different lifecycle. The `src/node/**` engine modules (which still back the Native Agent() path and the test suite, and retain SV/flywheel implementations not yet ported to Native Agent()) are **retained** — only the direct-CLI `--mode agent` *entry point* hard-errors. For production tmux orchestration, use `--mode tmux` (the **canonical** leader). For Claude Code Native Agent() campaigns, use `/rlp-desk run <slug> --mode native` from a Claude Code session.
+
+**Deprecation schedule** (per [ADR-001](../../docs/plans/adr-001-leader-consolidation.md) §3 — applies to the Node-CLI `--mode agent` entry point ONLY; the `src/node/**` engine modules are retained throughout):
+
+| Version | Behavior of `node run.mjs run <slug> --mode agent` |
+|---------|-----------------------------------------------------|
+| 0.16.x  | runs, with a louder deprecation banner |
+| **0.17.0** | **hard-errors** (exit 2) with a redirect to `--mode tmux` / `--mode native`; the Node-CLI default also flips to `tmux` |
+| 0.18.0  | the `--mode agent` dispatch branch is removed (engine modules stay) |
+
+External wrappers calling `--mode agent` must migrate to `--mode tmux` by 0.17.0. This is a breaking CLI change for that entry point, announced in CHANGELOG at each step.
 
 ### Preparation
 1. Validate scaffold: `.rlp-desk/prompts/<slug>.worker.prompt.md` etc.

package/src/governance.md

@@ -584,7 +584,7 @@ for iteration in 1..max_iter:
   ⑥½ Flywheel direction review (when --flywheel on-fail and consecutive_failures > 0)
      - Dispatch Flywheel agent (fresh context, --flywheel-model)
      - Read flywheel-signal.json for direction decision (hold/pivot/reduce/expand)
-     - Optional `next_mission_candidate` field (string | null): when present, the leader propagates it to status.json so consumer wrappers can chain the next mission without code edits. See docs/multi-mission-orchestration.md.
+     - Optional `next_mission_candidate` field (string | null): when present, the leader propagates it to status.json so consumer wrappers can chain the next mission without code edits. See docs/rlp-desk/multi-mission-orchestration.md.
      - If --flywheel-guard on:
        - Dispatch Guard agent (fresh context, --flywheel-guard-model)
        - Read flywheel-guard-verdict.json:

package/src/node/run.mjs

@@ -5,7 +5,7 @@ import { spawn, spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
 import { initCampaign } from './init/campaign-initializer.mjs';
-import { readStatus } from './reporting/campaign-reporting.mjs';
+import { readStatus, generateSVReport } from './reporting/campaign-reporting.mjs';
 import {
   run as runCampaignMain,
   detectLegacyDeskInRunMode,
@@ -14,7 +14,11 @@ import {
 import { isClaudeEngine } from './cli/command-builder.mjs';
 
 const RUN_DEFAULTS = {
-  mode: 'agent',
+  // ARCH Wave D (ADR-001 §3): the Node-CLI default mode flips from the deprecated
+  // 'agent' (Node-leader alpha) to 'tmux' (the canonical production leader) at the
+  // same step that makes --mode agent hard-error. A bare `run <slug>` now delegates
+  // to the zsh runner, not the deprecated Node leader.
+  mode: 'tmux',
   workerModel: 'haiku',
   verifierModel: 'sonnet',
   finalVerifierModel: 'opus',
@@ -49,14 +53,14 @@ function buildHelpText() {
     'Commands:',
     '  brainstorm <description>     Plan before init (not implemented in the Node rewrite yet)',
     '  init <slug> [objective]      Create project scaffold',
-    '  run <slug> [options]         Run loop (tmux=zsh leader [production], agent=Node leader [deprecated alpha], native=slash-only error)',
+    '  run <slug> [options]         Run loop (tmux=zsh leader [production, default], agent=hard-errors per ADR-001, native=slash-only error)',
     '  status <slug>                Show loop status',
     '  logs <slug> [N]              Show iteration log (not implemented in the Node rewrite yet)',
     '  clean <slug> [--kill-session] Reset for re-run (removes sentinels + runtime/; preserves PRD/prompts/memory)',
     '  resume <slug>                Resume loop (not implemented in the Node rewrite yet)',
     '',
     'Run Options:',
-    '  --mode tmux|agent|native       (CLI: tmux=production, agent=deprecated, native=errors with redirect to slash command)',
+    '  --mode tmux|agent|native       (CLI: tmux=production [default], agent=hard-errors (ADR-001), native=errors with redirect to slash command)',
     '  --worker-model MODEL',
     '  --lock-worker-model',
     '  --verifier-model MODEL',
@@ -318,6 +322,10 @@ function buildZshEnv(slug, options, parentEnv) {
     AUTONOMOUS_MODE: options.autonomous ? '1' : '0',
     LANE_MODE: options.laneStrict ? 'strict' : 'warn',
     TEST_DENSITY_MODE: options.testDensityStrict ? 'strict' : 'warn',
+    // ARCH Wave C-SV: forwarded for traceability only. The zsh leader keeps its
+    // $TMUX early-return (no in-pane `claude --print`); the SV report itself is
+    // produced by the Node post-pass in runTmuxViaZsh after the zsh child exits.
+    WITH_SELF_VERIFICATION: options.withSelfVerification ? '1' : '0',
   };
 }
 
@@ -360,23 +368,47 @@ async function runTmuxViaZsh(slug, options, deps) {
     return 1;
   }
 
-  // Surface flags the zsh runner cannot honor. Flywheel and self-verification
-  // remain Node-leader features, available only in --mode agent. Warn loudly
-  // instead of silent no-op so the operator understands the trade-off.
+  // Surface flags the zsh runner cannot honor. ARCH Wave C: --with-self-verification
+  // IS now honored in tmux mode via a post-zsh-return pass (see below) — only the
+  // flywheel flags remain unsupported here. Warn loudly instead of silent no-op.
   const unsupported = [];
   if (options.flywheel !== 'off') unsupported.push('--flywheel');
   if (options.flywheelGuard !== 'off') unsupported.push('--flywheel-guard');
-  if (options.withSelfVerification) unsupported.push('--with-self-verification');
   if (unsupported.length > 0) {
     write(
       deps.stderr,
-      `WARNING: ${unsupported.join(', ')} not honored in --mode tmux (zsh runner). Use --mode agent for those features.`,
+      `WARNING: ${unsupported.join(', ')} not honored in --mode tmux (zsh runner). Flywheel is deprecated (ADR-001) and unimplemented in the canonical leader.`,
     );
   }
 
   const env = buildZshEnv(slug, options, process.env);
   const spawnZsh = deps.spawnZsh ?? defaultSpawnZsh;
-  return spawnZsh(zshPath, env, options.rootDir);
+  const exitCode = await spawnZsh(zshPath, env, options.rootDir);
+
+  // ARCH Wave C-SV: home self-verification onto --mode tmux. The zsh runner cannot
+  // produce the SV report itself (`claude --print` hangs without a TTY in a tmux
+  // pane — that is why lib_ralph_desk.zsh keeps its $TMUX early-return). Instead we
+  // run the Node PURE-FS generateSVReport as a post-pass AFTER the zsh child exits:
+  // real stdout, no pane, no TTY → no hang. It reads the campaign's on-disk
+  // iter-*-done-claim/verify-verdict artifacts the zsh leader already wrote.
+  if (options.withSelfVerification) {
+    try {
+      const paths = buildPaths(options.rootDir, slug);
+      const sv = await generateSVReport({
+        slug,
+        logsDir: paths.campaignLogDir,
+        prdFile: paths.prdFile,
+        testSpecFile: paths.testSpecFile,
+        analyticsFile: paths.analyticsFile,
+        outputDir: paths.analyticsDir,
+      });
+      write(deps.stdout, `\nSelf-verification report (tmux post-pass): ${sv.summary ?? 'generated'}`);
+    } catch (err) {
+      write(deps.stderr, `WARNING: self-verification post-pass failed: ${err.message}`);
+    }
+  }
+
+  return exitCode;
 }
 
 async function runRunCommand(args, deps) {
@@ -414,7 +446,7 @@ async function runRunCommand(args, deps) {
     );
     write(
       deps.stderr,
-      'If hang persists, switch to --worker-model gpt-5.5:high (codex) or --mode agent.',
+      'If hang persists, switch to --worker-model gpt-5.5:high (codex).',
     );
   }
 
@@ -440,50 +472,38 @@ async function runRunCommand(args, deps) {
     );
     write(
       deps.stderr,
-      'or use `--mode tmux` (production) / `--mode agent` (deprecated alpha) for direct CLI invocation.',
+      'or use `--mode tmux` (production) for direct CLI invocation. `--mode agent` hard-errors (ADR-001).',
     );
     return 2;
   }
 
-  // P1.b: --mode agent (Node-leader alpha) is deprecated. The slash command's
-  // Native Agent() path (`/rlp-desk run --mode native`) is unrelated — different
-  // code, different leader. We keep the Node-leader behavior unchanged for
-  // backward compatibility but surface a strong deprecation banner so wrappers
-  // can migrate before the next major release hard-errors this mode.
-  if (
-    options.mode === 'agent'
-    && !process.env.RLP_DESK_QUIET_WARNINGS
-    && process.env.NODE_ENV !== 'test'
-  ) {
+  // ARCH Wave D (ADR-001 §3): --mode agent (Node-leader direct-CLI alpha) HARD-ERRORS
+  // as of this release. It is the dated breaking change the deprecation banner
+  // announced — direct CLI invocation now exits 2 with a redirect to the canonical
+  // production leader (--mode tmux) or the slash-command Native Agent() path
+  // (--mode native). This is UNRELATED to the slash command's legacy `--mode agent`
+  // → native redirect (different code, different leader). The `src/node/**` engine
+  // modules (run()/runCampaign) are RETAINED — they remain the engine the Native
+  // Agent() path and the test suite build on; only this direct-CLI dispatch entry
+  // hard-errors. Mirror the --mode native slash-only exit-2 pattern above.
+  if (options.mode === 'agent') {
     write(
       deps.stderr,
-      'WARNING: --mode agent (Node-leader alpha) is deprecated.',
+      'ERROR: --mode agent (Node-leader direct-CLI alpha) is no longer supported (ADR-001).',
     );
     write(
       deps.stderr,
-      'This is the direct Node-CLI alpha path — UNRELATED to the slash command Native Agent() path (`/rlp-desk run --mode native`).',
+      'For production tmux orchestration, use `--mode tmux` (the canonical leader).',
     );
     write(
       deps.stderr,
-      'For production tmux orchestration, use `--mode tmux`.',
+      'For Claude Code Native Agent() campaigns, use `/rlp-desk run <slug> --mode native` from a Claude Code session.',
     );
     write(
       deps.stderr,
-      'For Claude Code Native Agent() campaigns, use `/rlp-desk run --mode native` from a Claude Code session.',
-    );
-    // 2026-05-07 (v0.15.2): rlp-desk is in active stabilization. Goal: reach
-    // omc /team/ralph/ralplan level of reliability while preserving
-    // rlp-desk's self-driving advantages (multi-engine consensus, multi-mission
-    // queue, BLOCK_TAGS taxonomy, structured SV reports). omc is the BENCHMARK,
-    // not a replacement. See docs/plans/v0.15-stabilization-plan.md.
-    write(
-      deps.stderr,
-      'SCHEDULED REMOVAL: --mode agent (Node CLI alpha) will be removed in a future major release. Date TBD until stabilization milestones complete.',
-    );
-    write(
-      deps.stderr,
-      'STABILIZATION IN PROGRESS: rlp-desk is hardening against the 10-bug regression pattern observed 2026-05-01..05-07. See docs/plans/v0.15-stabilization-plan.md.',
+      'The src/node/** engine modules are retained; only the direct-CLI --mode agent entry point was removed.',
     );
+    return 2;
   }
 
   const result = await deps.runCampaign(slug, options);

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

@@ -1715,7 +1715,7 @@ async function _runCampaignBody(slug, options, paths, rootDir) {
       // P0-A multi-mission orchestration: optionally captured from flywheel signal.
       // null when the flywheel did not suggest a next mission. Consumer wrappers
       // poll status.next_mission_candidate to chain missions without code edits.
-      // See docs/multi-mission-orchestration.md.
+      // See docs/rlp-desk/multi-mission-orchestration.md.
       state.next_mission_candidate = flywheelSignal.next_mission_candidate ?? null;
       // Bug #7 Fix-R cleanup: unlock before unlink so 0o444 doesn't block.
       await unlockSentinelFile(paths.flywheelSignalFile);

package/src/scripts/init_ralph_desk.zsh

@@ -761,7 +761,7 @@ Based on your decision, update campaign memory:
      current direction. The wrapper polls this field for autonomous
      multi-mission orchestration (rlp-desk does not auto-launch missions —
      the consumer wrapper owns that policy). Field is OPTIONAL; absence is
-     treated as null. See docs/multi-mission-orchestration.md for the
+     treated as null. See docs/rlp-desk/multi-mission-orchestration.md for the
      consumer-side polling pattern.
 FLYWHEEL_EOF
 

package/src/scripts/lib_ralph_desk.zsh

@@ -756,9 +756,18 @@ _lint_test_density() {
   us_list=$(grep -oE '^##[[:space:]]+US-[0-9]+' "$prd_file" 2>/dev/null | grep -oE 'US-[0-9]+' | sort -u)
   [[ -z "$us_list" ]] && return 0
 
-  local audit_dir="${LOGS_DIR:-/tmp}"
-  local audit_file="$audit_dir/test-density-audit.jsonl"
-  [[ -d "$audit_dir" ]] || audit_file="/tmp/test-density-audit.jsonl"
+  # ZSH-8: prefer the campaign LOGS_DIR. When it is unavailable, avoid a fixed,
+  # predictable /tmp name (insecure-temp: symlink/collision risk) by creating a
+  # unique temp file via mktemp; fall back to a PID-scoped name only if mktemp
+  # is missing.
+  local audit_dir="${LOGS_DIR:-}"
+  local audit_file
+  if [[ -n "$audit_dir" && -d "$audit_dir" ]]; then
+    audit_file="$audit_dir/test-density-audit.jsonl"
+  else
+    audit_file=$(mktemp "${TMPDIR:-/tmp}/test-density-audit.XXXXXX" 2>/dev/null) \
+      || audit_file="${TMPDIR:-/tmp}/test-density-audit.$$.jsonl"
+  fi
 
   local us
   for us in ${(f)us_list}; do

package/src/scripts/run_ralph_desk.zsh

@@ -67,8 +67,12 @@ SV_SKIPPED_REASON=""                                         # set when SV is di
 # no-progress, stale-context, claude model upgrade chain, etc.), so the
 # Node leader is now reserved for `--mode agent` (LLM-driven) only.
 # `--mode tmux` invocations from src/node/run.mjs delegate here as a
-# subprocess via env vars. zsh continues to honor FLYWHEEL,
-# FLYWHEEL_GUARD, WITH_SELF_VERIFICATION.
+# subprocess via env vars. ARCH Wave C / ADR-001: FLYWHEEL and FLYWHEEL_GUARD
+# are NOT implemented in the zsh leader (no dispatch site) and are deprecated —
+# do NOT claim otherwise. WITH_SELF_VERIFICATION is forwarded for traceability,
+# but the SV report is produced by the Node post-pass in run.mjs runTmuxViaZsh
+# after this script exits (this script keeps its $TMUX early-return to avoid the
+# `claude --print` no-TTY hang).
 AUTONOMOUS_MODE="${AUTONOMOUS_MODE:-0}"    # 1=don't stop on ambiguity, PRD is authoritative
 # P1-E Lane enforcement: WARN-only by default; --lane-strict opts into BLOCKED
 # escalation. governance §7¾. The opt-in defaults to "warn"; "strict" trips
@@ -2307,7 +2311,7 @@ poll_for_signal() {
             # done-claim and a fresh signal_file in that order.
             _kill_pane_process "$pane_id" "worker-a4"
             _lock_sentinel "$DONE_CLAIM_FILE"
-            echo '{"iteration":'"$ITERATION"',"status":"verify","us_id":"'"$dc_us_id"'","summary":"auto-generated by A4 fallback (done-claim + clean tree)","timestamp":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'"}' > "$signal_file"
+            echo '{"iteration":'"$ITERATION"',"status":"verify","us_id":"'"$dc_us_id"'","summary":"auto-generated by A4 fallback (done-claim + clean tree)","timestamp":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'"}' | atomic_write "$signal_file"
             _emit_a4_fallback_audit "$dc_us_id" "$ITERATION" "inline_polling_a4_clean"
             return 0
           else
@@ -2881,7 +2885,13 @@ main() {
       log_error "Another instance is already running (PID $lock_pid). Kill $lock_pid or rm $lockfile"
       exit 1
     fi
-    # Stale lock — overwrite
+    # Stale lock — overwrite.
+    # NOTE (ZSH-4, deferred): a fully race-safe stale-lock recovery is a separate
+    # distributed-lock redesign (codex review found subtle rm/create + mutex-leak
+    # races in patch attempts). This finding is LOW: the outer RUNNER_LOCKDIR mkdir
+    # lock (keyed on the same $ROOT) already serializes runners before this inner
+    # path is reached, so the inner race is unreachable in practice. Left at the
+    # tested baseline pending a dedicated redesign.
     log "Stale lock detected (PID ${lock_pid:-unknown} not running), recovering"
     echo $$ > "$lockfile"
     LOCKFILE_ACQUIRED=1