@ai-dev-methodologies/rlp-desk 0.11.0 → 0.12.0

package/install.sh

@@ -12,10 +12,24 @@ set -euo pipefail
 # Safe to run multiple times (idempotent).
 # =============================================================================
 
-REPO_URL="https://raw.githubusercontent.com/ai-dev-methodologies/rlp-desk/main"
+# v5.7 §4.4: REPO_URL overridable for offline/local testing (test fixture).
+REPO_URL="${REPO_URL:-https://raw.githubusercontent.com/ai-dev-methodologies/rlp-desk/main}"
 CLAUDE_DIR="$HOME/.claude"
 COMMANDS_DIR="$CLAUDE_DIR/commands"
 DESK_DIR="$CLAUDE_DIR/ralph-desk"
+NODE_DIR="$DESK_DIR/node"
+
+# v5.7 §4.4 / Q3: Node ≥16 preflight (matches scripts/postinstall.js policy).
+if command -v node &>/dev/null; then
+  NODE_MAJOR=$(node -p "process.versions.node.split('.')[0]" 2>/dev/null || echo 0)
+  if [[ "$NODE_MAJOR" -lt 16 ]]; then
+    echo "  [warn] Node.js >= 16 required for the Node leader (--mode tmux flywheel/SV)."
+    echo "         Found Node $NODE_MAJOR. Continuing zsh install; --mode tmux features will be unavailable."
+  fi
+else
+  echo "  [warn] node not found in PATH. Node leader features (--flywheel, --with-self-verification in tmux) unavailable."
+  echo "         Install Node.js >= 16: https://nodejs.org/"
+fi
 
 echo ""
 echo "  RLP Desk Installer"
@@ -25,30 +39,89 @@ echo ""
 # Create directories
 mkdir -p "$COMMANDS_DIR"
 mkdir -p "$DESK_DIR"
-mkdir -p "$DESK_DIR/docs/internal"
-mkdir -p "$DESK_DIR/docs/blueprints"
+mkdir -p "$DESK_DIR/docs/rlp-desk/internal"
+mkdir -p "$DESK_DIR/docs/rlp-desk/blueprints"
+mkdir -p "$DESK_DIR/docs/rlp-desk/plans"
+mkdir -p "$NODE_DIR"
+
+# v5.7 §4.10 helpers — chmod-before-curl (unlock prior install) + chmod a-w
+# (lock down). Hard-fail per Architect (no `2>/dev/null || true` swallowing).
+unlock_target() {
+  local target="$1"
+  if [[ -e "$target" ]]; then
+    chmod u+w "$target" || {
+      echo "  [install] FATAL: cannot unlock existing $target. Filesystem may be read-only."
+      exit 1
+    }
+  fi
+}
+lock_target() {
+  local target="$1"
+  if ! chmod a-w "$target" 2>/dev/null; then
+    echo "  [install] WARNING: chmod a-w failed on $target. Filesystem may not honor POSIX mode bits (WSL1/NTFS); cross-session edit protection unavailable."
+  fi
+}
+fetch() {
+  local url="$1" target="$2"
+  unlock_target "$target"
+  curl -fsSL "$url" -o "$target" || {
+    echo "  [install] FATAL: download failed for $url"
+    exit 1
+  }
+  lock_target "$target"
+}
 
 # Runtime files
 echo "  Downloading runtime files..."
-curl -sSL "$REPO_URL/src/commands/rlp-desk.md" -o "$COMMANDS_DIR/rlp-desk.md"
-curl -sSL "$REPO_URL/src/scripts/init_ralph_desk.zsh" -o "$DESK_DIR/init_ralph_desk.zsh"
-curl -sSL "$REPO_URL/src/scripts/run_ralph_desk.zsh" -o "$DESK_DIR/run_ralph_desk.zsh"
-curl -sSL "$REPO_URL/src/scripts/lib_ralph_desk.zsh" -o "$DESK_DIR/lib_ralph_desk.zsh"
-curl -sSL "$REPO_URL/src/governance.md" -o "$DESK_DIR/governance.md"
-curl -sSL "$REPO_URL/src/model-upgrade-table.md" -o "$DESK_DIR/model-upgrade-table.md"
-chmod +x "$DESK_DIR/init_ralph_desk.zsh" "$DESK_DIR/run_ralph_desk.zsh" "$DESK_DIR/lib_ralph_desk.zsh"
+fetch "$REPO_URL/src/commands/rlp-desk.md" "$COMMANDS_DIR/rlp-desk.md"
+fetch "$REPO_URL/src/scripts/init_ralph_desk.zsh" "$DESK_DIR/init_ralph_desk.zsh"
+fetch "$REPO_URL/src/scripts/run_ralph_desk.zsh" "$DESK_DIR/run_ralph_desk.zsh"
+fetch "$REPO_URL/src/scripts/lib_ralph_desk.zsh" "$DESK_DIR/lib_ralph_desk.zsh"
+fetch "$REPO_URL/src/governance.md" "$DESK_DIR/governance.md"
+fetch "$REPO_URL/src/model-upgrade-table.md" "$DESK_DIR/model-upgrade-table.md"
+
+# v5.7 §4.4 — Node leader files (manifest-driven, prevents drift).
+echo "  Downloading Node leader runtime via MANIFEST.txt..."
+MANIFEST_TMP=$(mktemp)
+unlock_target "$NODE_DIR/MANIFEST.txt"
+curl -fsSL "$REPO_URL/src/node/MANIFEST.txt" -o "$MANIFEST_TMP" || {
+  echo "  [install] WARNING: src/node/MANIFEST.txt unavailable. Node leader features will be missing."
+  echo "             Update install.sh from a 0.12.0+ source if upgrading."
+  MANIFEST_TMP=""
+}
+if [[ -n "$MANIFEST_TMP" && -s "$MANIFEST_TMP" ]]; then
+  cp "$MANIFEST_TMP" "$NODE_DIR/MANIFEST.txt"
+  while IFS= read -r relpath; do
+    [[ -z "$relpath" ]] && continue
+    target="$NODE_DIR/$relpath"
+    mkdir -p "$(dirname "$target")"
+    fetch "$REPO_URL/src/node/$relpath" "$target"
+  done < "$MANIFEST_TMP"
+  lock_target "$NODE_DIR/MANIFEST.txt"
+  rm -f "$MANIFEST_TMP"
+fi
+
+# Note: chmod +x is NOT needed — runtime files are invoked via `zsh script.zsh`
+# or `node script.mjs`, never directly. lock_target above already chmod a-w'd
+# them; an explicit chmod +x would re-add write to other.
 
-# Reference docs
+# Reference docs (v5.7 §4.4 follow-up: same fetch() helper handles unlock+lock
+# so reference-doc upgrade-over-installed-and-locked file does not silently fail).
 echo "  Downloading reference docs..."
-curl -sSL "$REPO_URL/README.md" -o "$DESK_DIR/README.md"
-curl -sSL "$REPO_URL/install.sh" -o "$DESK_DIR/install.sh"
-curl -sSL "$REPO_URL/docs/architecture.md" -o "$DESK_DIR/docs/architecture.md"
-curl -sSL "$REPO_URL/docs/getting-started.md" -o "$DESK_DIR/docs/getting-started.md"
-curl -sSL "$REPO_URL/docs/protocol-reference.md" -o "$DESK_DIR/docs/protocol-reference.md"
-curl -sSL "$REPO_URL/docs/TODO-verification-next.md" -o "$DESK_DIR/docs/TODO-verification-next.md"
-curl -sSL "$REPO_URL/docs/internal/verification-policy-gap-analysis.md" -o "$DESK_DIR/docs/internal/verification-policy-gap-analysis.md"
-curl -sSL "$REPO_URL/docs/internal/verification-strategy-research.md" -o "$DESK_DIR/docs/internal/verification-strategy-research.md"
-curl -sSL "$REPO_URL/docs/blueprints/blueprint-v0.4-evolution.md" -o "$DESK_DIR/docs/blueprints/blueprint-v0.4-evolution.md"
+fetch "$REPO_URL/README.md" "$DESK_DIR/README.md"
+fetch "$REPO_URL/install.sh" "$DESK_DIR/install.sh"
+fetch "$REPO_URL/docs/rlp-desk/architecture.md" "$DESK_DIR/docs/rlp-desk/architecture.md"
+fetch "$REPO_URL/docs/rlp-desk/getting-started.md" "$DESK_DIR/docs/rlp-desk/getting-started.md"
+fetch "$REPO_URL/docs/rlp-desk/protocol-reference.md" "$DESK_DIR/docs/rlp-desk/protocol-reference.md"
+fetch "$REPO_URL/docs/rlp-desk/TODO-verification-next.md" "$DESK_DIR/docs/rlp-desk/TODO-verification-next.md"
+fetch "$REPO_URL/docs/rlp-desk/multi-mission-orchestration.md" "$DESK_DIR/docs/rlp-desk/multi-mission-orchestration.md"
+# Dev meta docs (v5.7 §4.15: under docs/rlp-desk/ to avoid mixing with user docs)
+fetch "$REPO_URL/docs/rlp-desk/internal/verification-policy-gap-analysis.md" "$DESK_DIR/docs/rlp-desk/internal/verification-policy-gap-analysis.md"
+fetch "$REPO_URL/docs/rlp-desk/internal/verification-strategy-research.md" "$DESK_DIR/docs/rlp-desk/internal/verification-strategy-research.md"
+fetch "$REPO_URL/docs/rlp-desk/blueprints/blueprint-flywheel-enhancement.md" "$DESK_DIR/docs/rlp-desk/blueprints/blueprint-flywheel-enhancement.md"
+fetch "$REPO_URL/docs/rlp-desk/blueprints/blueprint-pivot-step.md" "$DESK_DIR/docs/rlp-desk/blueprints/blueprint-pivot-step.md"
+fetch "$REPO_URL/docs/rlp-desk/blueprints/plan-flywheel-enhancement.md" "$DESK_DIR/docs/rlp-desk/blueprints/plan-flywheel-enhancement.md"
+fetch "$REPO_URL/docs/rlp-desk/blueprints/sv-architecture-rethink.md" "$DESK_DIR/docs/rlp-desk/blueprints/sv-architecture-rethink.md"
 
 # Check tmux availability
 if ! command -v tmux &>/dev/null; then

package/package.json

@@ -1,10 +1,16 @@
 {
   "name": "@ai-dev-methodologies/rlp-desk",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Fresh-context iterative loops for Claude Code — autonomous task completion with independent verification",
   "scripts": {
     "postinstall": "node scripts/postinstall.js",
-    "uninstall": "node scripts/uninstall.js"
+    "uninstall": "node scripts/uninstall.js",
+    "test:node": "node --test 'tests/node/*.mjs' 'tests/node/*.test.mjs'",
+    "test:zsh": "for f in tests/test_*.sh; do echo \"=== $f ===\"; zsh \"$f\" || exit 1; done",
+    "test:fast": "npm run test:node",
+    "test:full": "npm run test:fast && npm run test:zsh",
+    "sv-gate:fast": "zsh tests/sv-gate-fast.sh",
+    "sv-gate:full": "zsh tests/sv-gate-full.sh"
   },
   "files": [
     "src/commands/",

package/scripts/build-node-manifest.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+"use strict";
+
+// v5.7 §4.4 — generate src/node/MANIFEST.txt listing every Node runtime file.
+// install.sh reads this manifest line-by-line and curls each file. Without
+// this, the curl-pipe-shell install path has no Node leader (release-blocker).
+//
+// Run as `prepublishOnly` AND on every CI build to keep the manifest in sync.
+// CI drift check: `node scripts/build-node-manifest.js --check` returns
+// non-zero exit if the on-disk manifest does not match the regenerated form.
+
+const fs = require("fs");
+const path = require("path");
+
+const repoRoot = path.join(__dirname, "..");
+const nodeDir = path.join(repoRoot, "src", "node");
+const manifestPath = path.join(nodeDir, "MANIFEST.txt");
+
+function walk(dir, base) {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    const sourcePath = path.join(dir, entry.name);
+    const relPath = path.posix.join(base, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...walk(sourcePath, relPath));
+    } else if (entry.isFile() && entry.name.endsWith(".mjs")) {
+      files.push(relPath);
+    }
+  }
+  return files;
+}
+
+const generated = walk(nodeDir, "").join("\n") + "\n";
+
+const isCheck = process.argv.includes("--check");
+
+if (isCheck) {
+  const onDisk = fs.existsSync(manifestPath) ? fs.readFileSync(manifestPath, "utf8") : "";
+  if (onDisk !== generated) {
+    console.error("MANIFEST.txt drift detected. Run: node scripts/build-node-manifest.js");
+    console.error("--- ON-DISK ---");
+    console.error(onDisk);
+    console.error("--- GENERATED ---");
+    console.error(generated);
+    process.exit(1);
+  }
+  console.log("MANIFEST.txt in sync (" + generated.split("\n").filter(Boolean).length + " entries).");
+} else {
+  fs.writeFileSync(manifestPath, generated);
+  console.log("Wrote " + manifestPath + " (" + generated.split("\n").filter(Boolean).length + " entries).");
+}

package/scripts/postinstall.js

@@ -19,10 +19,12 @@ const runtimeSources = [
   ["src/model-upgrade-table.md", path.join(deskDir, "model-upgrade-table.md")],
   ["README.md", path.join(deskDir, "README.md")],
   ["install.sh", path.join(deskDir, "install.sh")],
-  ["docs/architecture.md", path.join(docsDir, "architecture.md")],
-  ["docs/getting-started.md", path.join(docsDir, "getting-started.md")],
-  ["docs/protocol-reference.md", path.join(docsDir, "protocol-reference.md")],
-  ["docs/TODO-verification-next.md", path.join(docsDir, "TODO-verification-next.md")],
+  // v5.7 §4.15: all rlp-desk docs (user-facing + dev meta) under docs/rlp-desk/.
+  ["docs/rlp-desk/architecture.md", path.join(docsDir, "rlp-desk", "architecture.md")],
+  ["docs/rlp-desk/getting-started.md", path.join(docsDir, "rlp-desk", "getting-started.md")],
+  ["docs/rlp-desk/protocol-reference.md", path.join(docsDir, "rlp-desk", "protocol-reference.md")],
+  ["docs/rlp-desk/TODO-verification-next.md", path.join(docsDir, "rlp-desk", "TODO-verification-next.md")],
+  ["docs/rlp-desk/multi-mission-orchestration.md", path.join(docsDir, "rlp-desk", "multi-mission-orchestration.md")],
 ];
 const legacyFiles = [
   path.join(deskDir, "init_ralph_desk.zsh"),
@@ -43,13 +45,117 @@ function ensureDir(dirPath) {
   fs.mkdirSync(dirPath, { recursive: true });
 }
 
+function unlockTree(targetPath) {
+  // v5.7 §4.10: walk and chmod u+w every entry so rmSync(recursive) does not
+  // ENOTEMPTY on a directory full of 0o444 children. Idempotent on missing paths.
+  // Security review v5.7 follow-up: lstatSync first; SKIP symlinks entirely so
+  // a hostile symlink (e.g., ~/.claude/ralph-desk/foo -> /etc/passwd) cannot
+  // be chmod'd via unlockTree's chmodSync (which follows symlinks).
+  if (!fs.existsSync(targetPath)) return;
+  const stat = fs.lstatSync(targetPath);
+  if (stat.isSymbolicLink()) {
+    // Don't chmod the symlink target. lchmod is unsupported on Linux; safest
+    // action is to leave symlinks alone — they're not part of our install set.
+    return;
+  }
+  try { fs.chmodSync(targetPath, stat.isDirectory() ? 0o755 : 0o644); } catch {}
+  if (stat.isDirectory()) {
+    for (const entry of fs.readdirSync(targetPath, { withFileTypes: true })) {
+      unlockTree(path.join(targetPath, entry.name));
+    }
+  }
+}
+
 function removePath(targetPath) {
+  // v5.7 §4.10: existing target tree may contain 0o444 files. Walk and unlock
+  // before rmSync so EACCES/ENOTEMPTY don't break the upgrade path.
+  unlockTree(targetPath);
   fs.rmSync(targetPath, { recursive: true, force: true });
 }
 
+// v5.7 §4.10: per-extension banner format. `# DO NOT EDIT` text leaks into
+// rendered Markdown, so .md uses HTML comment; .mjs/.js uses //; shell uses #.
+function bannerFor(extension, sourceRelativePath) {
+  const msg = `DO NOT EDIT — generated from ${sourceRelativePath}. Edit source and re-sync. See ~/.claude/ralph-desk/UNLOCK.md for debug unlock.`;
+  switch (extension) {
+    case ".md":
+      return `<!-- ${msg} -->\n`;
+    case ".mjs":
+    case ".js":
+      return `// ${msg}\n`;
+    case ".zsh":
+    case ".sh":
+      return `# ${msg}\n`;
+    default:
+      return null; // .json and unknown types: rely on chmod alone
+  }
+}
+
+let _chmodWarningEmitted = false;
+function tryLockFile(targetPath) {
+  // Best-effort write-protect. Some filesystems (WSL1/NTFS, tmpfs noexec, certain
+  // bind mounts) silently no-op chmod. R-V5-5: emit ONE warning per install run.
+  try {
+    fs.chmodSync(targetPath, 0o444);
+    const stat = fs.statSync(targetPath);
+    if ((stat.mode & 0o222) !== 0 && !_chmodWarningEmitted) {
+      console.log("  [install] WARNING: filesystem does not honor chmod a-w; cross-session edit protection unavailable.");
+      _chmodWarningEmitted = true;
+    }
+  } catch (err) {
+    if (!_chmodWarningEmitted) {
+      console.log("  [install] WARNING: chmod a-w failed (" + err.code + "); cross-session edit protection unavailable.");
+      _chmodWarningEmitted = true;
+    }
+  }
+}
+
+function injectBannerAndLock(targetPath, sourceRelativePath) {
+  const ext = path.extname(targetPath).toLowerCase();
+  const banner = bannerFor(ext, sourceRelativePath);
+  if (banner) {
+    const original = fs.readFileSync(targetPath);
+    // Idempotency guard (code-review v5.7 follow-up): the source file in the
+    // package tarball already contains an injected banner from a prior install
+    // ONLY if a developer ran sync from an installed copy back to the source —
+    // which is forbidden by CLAUDE.md. But re-running install over an existing
+    // installed file (e.g., npm i again) does NOT need re-injection because
+    // copyFileSync replaced the file with the source contents. The check below
+    // is defensive — only inject when the file does not already start with a
+    // DO NOT EDIT marker.
+    const head = original.subarray(0, 200).toString('utf8');
+    if (head.includes('DO NOT EDIT — generated from')) {
+      // Already banner-headed (rare: source somehow shipped with banner). Skip
+      // injection but still apply chmod for consistency.
+      tryLockFile(targetPath);
+      return;
+    }
+    // Shebang preservation: if first line starts with `#!`, banner goes on line 2.
+    if (original.length >= 2 && original[0] === 0x23 && original[1] === 0x21) {
+      const newlineIdx = original.indexOf(0x0a);
+      if (newlineIdx >= 0) {
+        const headBuf = original.subarray(0, newlineIdx + 1);
+        const tailBuf = original.subarray(newlineIdx + 1);
+        fs.writeFileSync(targetPath, Buffer.concat([headBuf, Buffer.from(banner), tailBuf]));
+      } else {
+        fs.writeFileSync(targetPath, Buffer.concat([original, Buffer.from("\n" + banner)]));
+      }
+    } else {
+      fs.writeFileSync(targetPath, Buffer.concat([Buffer.from(banner), original]));
+    }
+  }
+  tryLockFile(targetPath);
+}
+
 function copyFile(sourceRelativePath, targetPath) {
   ensureDir(path.dirname(targetPath));
+  // v5.7 §4.10: unlock target if it exists and is write-protected from a prior
+  // install (R-V5-1: copyFileSync over 0o444 fails EACCES on upgrade).
+  if (fs.existsSync(targetPath)) {
+    try { fs.chmodSync(targetPath, 0o644); } catch { /* may be already writable */ }
+  }
   fs.copyFileSync(path.join(pkgDir, sourceRelativePath), targetPath);
+  injectBannerAndLock(targetPath, sourceRelativePath);
   console.log("  + " + targetPath);
 }
 
@@ -69,31 +175,73 @@ function copyMarkdownDirectory(sourceRelativeDir, targetDir) {
     }
     if (entry.isFile() && entry.name.endsWith(".md")) {
       ensureDir(path.dirname(targetPath));
+      // v5.7 §4.10: unlock prior-install write-protected target before copy.
+      if (fs.existsSync(targetPath)) {
+        try { fs.chmodSync(targetPath, 0o644); } catch {}
+      }
       fs.copyFileSync(sourcePath, targetPath);
+      injectBannerAndLock(targetPath, path.join(sourceRelativeDir, entry.name));
       console.log("  + " + targetPath);
     }
   }
 }
 
-function copyNodeRuntime(sourceDir, targetDir) {
+function copyNodeRuntime(sourceDir, targetDir, sourceRelativeBase) {
+  // removePath already handles 0o444 unlock per v5.7 §4.10.
   removePath(targetDir);
   ensureDir(targetDir);
+  const baseRel = sourceRelativeBase || "src/node";
 
   for (const entry of fs.readdirSync(sourceDir, { withFileTypes: true })) {
     const sourcePath = path.join(sourceDir, entry.name);
     const targetPath = path.join(targetDir, entry.name);
+    const childRel = path.join(baseRel, entry.name);
     if (entry.isDirectory()) {
-      copyNodeRuntime(sourcePath, targetPath);
+      copyNodeRuntime(sourcePath, targetPath, childRel);
       continue;
     }
     if (entry.isFile()) {
       ensureDir(path.dirname(targetPath));
       fs.copyFileSync(sourcePath, targetPath);
+      injectBannerAndLock(targetPath, childRel);
       console.log("  + " + targetPath);
     }
   }
 }
 
+// v5.7 §4.10: Documented escape hatch for debug sessions.
+function writeUnlockDoc() {
+  const unlockPath = path.join(deskDir, "UNLOCK.md");
+  const content = `# UNLOCK — Debug edit escape hatch
+
+Files in \`~/.claude/ralph-desk/\` and \`~/.claude/commands/rlp-desk.md\` are
+installed read-only (\`chmod a-w\`) so cross-session AI agents cannot silently
+corrupt them. Source of truth: the rlp-desk source repository.
+
+If you need to edit an installed file for **temporary debug** (e.g., add a
+\`set -x\` line, insert a \`print\` statement):
+
+\`\`\`bash
+chmod -R u+w ~/.claude/ralph-desk
+chmod u+w ~/.claude/commands/rlp-desk.md
+# ... edit, test, then revert ...
+\`\`\`
+
+To re-apply protection without a full reinstall, run npm install rlp-desk
+from the source repo or rerun \`scripts/postinstall.js\`.
+
+**For permanent fixes**, edit the source repo and re-publish — never edit
+installed files directly. The banner at the top of every installed file
+points back to its source path.
+`;
+  if (fs.existsSync(unlockPath)) {
+    try { fs.chmodSync(unlockPath, 0o644); } catch {}
+  }
+  fs.writeFileSync(unlockPath, content);
+  console.log("  + " + unlockPath);
+  // UNLOCK.md is itself NOT locked — users may want to add their own notes.
+}
+
 console.log("");
 console.log("  RLP Desk v" + pkg.version);
 console.log("  ================");
@@ -118,10 +266,16 @@ for (const [sourcePath, targetPath] of runtimeSources) {
   copyFile(sourcePath, targetPath);
 }
 
-copyMarkdownDirectory("docs/internal", path.join(docsDir, "internal"));
-copyMarkdownDirectory("docs/blueprints", path.join(docsDir, "blueprints"));
+// v5.7 §4.15: dev meta docs live under docs/rlp-desk/ to avoid mixing with
+// user-facing operational docs (per user feedback).
+copyMarkdownDirectory("docs/rlp-desk/internal", path.join(docsDir, "rlp-desk", "internal"));
+copyMarkdownDirectory("docs/rlp-desk/blueprints", path.join(docsDir, "rlp-desk", "blueprints"));
+copyMarkdownDirectory("docs/rlp-desk/plans", path.join(docsDir, "rlp-desk", "plans"));
 copyNodeRuntime(path.join(pkgDir, "src", "node"), nodeDir);
 
+// v5.7 §4.10: write the UNLOCK.md escape-hatch doc for debug sessions.
+writeUnlockDoc();
+
 console.log("");
 console.log("  Done! Open Claude Code and run:");
 console.log("    /rlp-desk brainstorm \"your task description\"");

package/src/commands/rlp-desk.md

@@ -280,40 +280,51 @@ Parse the `--mode` flag. If absent or `agent`, use the Agent() path below. If `t
 
 #### Tmux Mode (`--mode tmux`)
 
-When `--mode tmux` is specified:
+When `--mode tmux` is specified (v0.12.0+ — v5.7 §4.1 routes to Node leader for flywheel + SV support):
 
 1. **Validate scaffold** — same as Agent() mode: check `.claude/ralph-desk/prompts/<slug>.worker.prompt.md` etc.
 2. **Check sentinels** — same as Agent() mode.
-3. **Check prerequisites** — verify `tmux` and `jq` are installed. If not, report what is missing and stop.
-4. **Locate runner script** — find `run_ralph_desk.zsh` at `~/.claude/ralph-desk/run_ralph_desk.zsh`. If not found, tell the user to reinstall (`npm install` or `install.sh`).
-5. **Launch** — shell out to the runner script with env vars derived from flags:
+3. **Check prerequisites** — verify `tmux`, `jq`, and `node` (>= 16) are installed. If not, report what is missing and stop.
+4. **Locate Node leader** — find `~/.claude/ralph-desk/node/run.mjs`. If not found, tell the user to reinstall (`npm install` or `bash install.sh`).
+5. **Launch** — shell out to the Node leader. **All dynamic args (slug + model values) MUST be passed through shell single-quote escaping** (v5.7 §4.12 G11) so bracketed model ids like `claude-opus-4-7[1m]` survive zsh parsing:
+
 ```bash
-LOOP_NAME="<slug>" \
-ROOT="$PWD" \
-MAX_ITER=<--max-iter value> \
-WORKER_MODEL=<--worker-model value> \
-LOCK_WORKER_MODEL=<1 if --lock-worker-model, else 0> \
-VERIFIER_MODEL=<--verifier-model value, default: sonnet> \
-FINAL_VERIFIER_MODEL=<--final-verifier-model value, default: opus> \
-VERIFY_MODE=<--verify-mode value, default: per-us> \
-CONSENSUS_MODE=<--consensus value, default: off> \
-CONSENSUS_MODEL=<--consensus-model value, default: gpt-5.5:medium> \
-FINAL_CONSENSUS_MODEL=<--final-consensus-model value, default: gpt-5.5:high> \
-CB_THRESHOLD=<--cb-threshold value, default: 6> \
-ITER_TIMEOUT=<--iter-timeout value, default: 600> \
-DEBUG=<1 if --debug, else 0> \
-WITH_SELF_VERIFICATION=<1 if --with-self-verification, else 0> \
-  zsh ~/.claude/ralph-desk/run_ralph_desk.zsh
+node ~/.claude/ralph-desk/node/run.mjs run '<slug>' \
+  --mode tmux \
+  --max-iter <N> \
+  --worker-model '<value>' \
+  [--lock-worker-model] \
+  --verifier-model '<value>' \
+  --final-verifier-model '<value>' \
+  --consensus <off|all|final-only> \
+  --consensus-model '<value>' \
+  --final-consensus-model '<value>' \
+  --verify-mode <per-us|batch> \
+  --cb-threshold <N> \
+  --iter-timeout <N> \
+  [--debug] [--autonomous] \
+  [--lane-strict]              # was env LANE_MODE=strict \
+  [--test-density-strict]      # was env TEST_DENSITY_MODE=strict \
+  [--with-self-verification] \
+  [--flywheel on-fail --flywheel-model '<value>'] \
+  [--flywheel-guard on --flywheel-guard-model '<value>']
 ```
-6. **If the script exits with error (exit code 1)** — report the error to the user and STOP. Do NOT attempt to work around it. Do NOT create tmux sessions yourself. Do NOT re-launch the script in a different way. Just tell the user what went wrong and suggest using Agent mode instead.
-7. **If successful** — tell the user the tmux session has been started. The shell script takes over as the deterministic Leader. No Agent() calls are made in tmux mode.
+
+**Quoting contract (v5.7 §4.1)**: every `'<value>'` placeholder above must be replaced with the user's flag value wrapped in single quotes via the equivalent of `shellQuote(value)` — `"'" + value.replace(/'/g, "'\\''") + "'"` for POSIX correctness. The slug, all model values, and any future dynamic flag must follow this rule. A slug or model containing brackets / spaces / single quotes / dollar signs / backticks must NOT break the leader invocation.
+
+**Env-var translation (v5.7 §4.1)**: the slash command historically built `LANE_MODE=strict zsh ...` and `TEST_DENSITY_MODE=strict zsh ...` from CLI flags. The Node leader uses CLI flags instead — translate `--lane-strict` and `--test-density-strict` into the corresponding flags. Direct env-var users (running zsh directly) are unaffected.
+
+6. **If the Node leader exits with error** — report the error to the user and STOP. Do NOT attempt to work around it. Do NOT create tmux sessions yourself. Do NOT re-launch in a different way. Tell the user what went wrong and suggest `--mode agent` as alternative.
+7. **If successful** — tell the user the tmux session has been started. The Node leader takes over as the deterministic Leader. No Agent() calls are made in tmux mode.
 
 **IMPORTANT RULES:**
-- Tmux mode requires the user to already be inside a tmux session. If the runner script rejects because $TMUX is not set, do NOT try to create a tmux session yourself. Tell the user: "Start tmux first, then retry."
-- MUST launch the runner with `run_in_background: true` so `/rlp-desk` returns control immediately while preserving live tmux visibility.
+- Tmux mode requires the user to already be inside a tmux session. If the leader rejects because $TMUX is not set, do NOT try to create a tmux session yourself. Tell the user: "Start tmux first, then retry."
+- 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`.
-- `--with-self-verification` is accepted in tmux mode. After campaign completion, `run_ralph_desk.zsh` spawns `claude CLI` to generate the SV report from campaign artifacts (done-claims, verify-verdicts, campaign-report). SV reports are written to `~/.claude/ralph-desk/analytics/<slug>/`. Requires `claude` CLI available in PATH; if not found, an error is appended to the campaign report.
+- `--with-self-verification` is fully supported in tmux mode (v5.7 §4.7). The Node leader's `generateSVReport()` writes `self-verification-report.md` + `self-verification-data.json` under `<project>/.claude/ralph-desk/analytics/<slug>/` (project-local, v5.7 §4.11.b).
+- `--flywheel on-fail` and `--flywheel-guard on` are fully supported in tmux mode (v5.7 §4.1). The Node leader handles pane creation, sendKeys dispatch, signal polling, and Guard retry semantics identically to agent mode.
+- Legacy `zsh ~/.claude/ralph-desk/run_ralph_desk.zsh` (deprecated in 0.12.0) still runs for non-flywheel/non-SV invocations but emits a deprecation `[notice]`. Calling it with `FLYWHEEL` or `WITH_SELF_VERIFICATION` env vars exits 2 with a migration banner pointing to the Node leader.
 
 **tmux UX model (5 items):**
 - The session returns immediately after launch (`run_in_background: true`) so the command returns control to the parent CLI.
@@ -324,6 +335,18 @@ WITH_SELF_VERIFICATION=<1 if --with-self-verification, else 0> \
 
 #### Agent Mode (`--mode agent` or default)
 
+**Why Agent mode is structurally immune to Bug 4/5 (mid-execution prompt hang
+& A4 premature dispatch):** Worker/Verifier are dispatched as `Agent(...,
+mode="bypassPermissions", ...)`. The subagent runs non-interactively under
+the platform's bypass — it has no tmux pane, no TUI surface, and cannot
+surface a `[y/N]` prompt to the parent Leader. The auto-dismiss /
+prompt-stall / no-progress timeouts in `run_ralph_desk.zsh` (v5.7 §4.13.b /
+§4.16 / §4.17) are therefore tmux-only by design. **Tradeoff**: because
+`Agent()` has no timeout API, agent-mode iterations are not bounded — if
+the platform's `bypassPermissions` ever fails to suppress an interactive
+prompt at the SDK level, the call hangs indefinitely with no rlp-desk-side
+watchdog. Use `--mode tmux` if you need bounded execution time.
+
 ### Preparation
 1. Validate scaffold: `.claude/ralph-desk/prompts/<slug>.worker.prompt.md` etc.
 2. **Codex CLI pre-validation**: If `--consensus` is not `off` OR `--worker-model` uses codex format (contains `:`) OR `--verifier-model` / `--final-verifier-model` / `--consensus-model` / `--final-consensus-model` uses codex format, check that `codex` CLI exists in PATH. If codex CLI not found → STOP immediately, print install instructions (`npm install -g @openai/codex`), do not start the loop.

package/src/governance.md

@@ -297,13 +297,54 @@ BLOCKED writes a JSON sidecar (`<slug>-blocked.json`) alongside the markdown sen
 - English: `depends on US-`, `blocking US-`, `awaits US-`, `post-iter US-`, `requires US-N`, `cross-US`
 - Korean: `US-N 산출물`, `신규 US-`, `post-iter`
 
-**Write Order Contract (atomicity invariant)**:
-1. JSON sidecar written FIRST (`fs.writeFile` / `atomic_write`).
-2. markdown sentinel written SECOND.
-3. Invariant: **markdown exists ⇒ JSON exists** (writer enforces order).
-4. Wrappers SHOULD watch markdown sentinel, then read JSON sidecar. If JSON not yet visible (rare), retry up to 5 × 50ms before failing.
+**Write Order Contract (atomicity invariant)** — v5.7 §4.24 reversed:
+1. **markdown sentinel written FIRST** via `writeSentinelExclusive` (`fs.open(path, 'wx')` — O_EXCL first-writer-wins). The md acts as the race lock.
+2. **JSON sidecar written SECOND**, only by the winning writer.
+3. Invariant: **markdown exists ⇒ JSON exists** (winner writes both; losers see EEXIST and return without touching JSON, preserving the winner's content).
+4. Wrappers SHOULD watch markdown sentinel, then read JSON sidecar. If JSON not yet visible (rare ≤50ms), retry up to 5 × 50ms before failing.
 
-`atomic_write` provides per-file rename atomicity; cross-file ordering is enforced by the explicit two-call sequence.
+`writeSentinelExclusive` (in `src/node/shared/fs.mjs`) provides per-file first-writer-wins; cross-file ordering is enforced by the explicit md-then-JSON sequence inside `writeSentinel`.
+
+## 1g. Sentinel Guarantee Invariant (file-guarantee contract)
+
+**Every terminal exit of `runCampaign()` MUST leave exactly one sentinel on disk: `<slug>-blocked.md` XOR `<slug>-complete.md`.**
+
+This invariant is the foundation of the fresh-context architecture. If a campaign exits without any sentinel, future iterations cannot determine campaign state — Worker/Verifier are dispatched into a campaign whose history they cannot reconstruct.
+
+### Enforcement (3-layer defense)
+
+1. **Per-poll-site sentinel write** (`_handlePollFailure` helper at `src/node/runner/campaign-main-loop.mjs`). Every `pollForSignal` call site (Worker, VerifierPerUS, VerifierFinal, Flywheel, Guard) is wrapped in `try { … } catch (error) { return _handlePollFailure(error, { role, … }); }`. The helper classifies via `BLOCK_TAGS` typed enum, calls `writeSentinel` (idempotent via O_EXCL), and returns `{status:'blocked', …}` so the caller exits the loop cleanly.
+
+2. **Run-level try/finally backstop** (`_ensureTerminalSentinel`). After the campaign body executes, a `finally` block checks `exists(blockedSentinel) XOR exists(completeSentinel)`. If neither (paused state `continue` excepted), writes a synthetic BLOCKED `infra_failure/leader_exited_without_terminal_state` so even unhandled exceptions cannot escape silently.
+
+3. **Schema validator at READ boundary** (`validateArtifact`). After every `pollForSignal` returns parsed JSON, validates `(slug, iteration ≥ floor, signal_type matches read context, us_id ∈ usList ∪ {ALL})`. Throws `MalformedArtifactError({field, expected, got})` → caught by same `_handlePollFailure` → BLOCKED `contract_violation/malformed_artifact` (recoverable).
+
+### Per-role failure-category enum
+
+`_classifyBlock` (in `campaign-main-loop.mjs`) maps each `BLOCK_TAGS` value to one of the locked taxonomy categories:
+
+| Tag | reason_category | recoverable | Example trigger |
+|-----|----------------|-------------|-----------------|
+| `WORKER_EXITED` | `infra_failure` | false | Worker pane returned to shell without writing signal |
+| `VERIFIER_EXITED` | `infra_failure` | false | Per-US Verifier exited without writing verdict |
+| `FINAL_VERIFIER_EXITED` | `infra_failure` | false | Final ALL-verifier exited without writing verdict |
+| `FLYWHEEL_EXITED` | `infra_failure` | false | Flywheel pane crashed |
+| `GUARD_EXITED` | `infra_failure` | false | Guard pane crashed |
+| `PROMPT_BLOCKED` | `infra_failure` | false | Default-No prompt — auto-Enter would CANCEL |
+| `<role>_TIMEOUT` | `infra_failure` | false | pollForSignal timed out without exit detected |
+| `MALFORMED_ARTIFACT` | `contract_violation` | true | Worker/Verifier wrote schema-violating JSON |
+| `LEADER_EXITED_WITHOUT_TERMINAL_STATE` | `infra_failure` | false | Backstop fired (uncaught exception or paths outside controlled scope) |
+
+### Auditing
+
+Operators can verify the invariant for any campaign by running:
+
+```sh
+zsh tests/sv-gate-fast.sh   # 30s mechanical check (greps + units)
+zsh tests/sv-gate-full.sh   # 5min including REAL tmux + REAL campaign E2E
+```
+
+The fast gate fails immediately if any pollForSignal call site lacks a `_handlePollFailure` wiring or the writeSentinelExclusive primitive is bypassed.
 
 ## 2. Roles
 
@@ -553,6 +594,14 @@ for iteration in 1..max_iter:
          • fail + retries exhausted → BLOCKED
          • inconclusive → BLOCKED (escalate to user)
        - Guard count tracked per-US in status.json
+     - **Mode support (v0.12.0+, v5.7 §4.3)**: flywheel runs identically in
+       --mode agent and --mode tmux when routed through the Node leader
+       (`node ~/.claude/ralph-desk/node/run.mjs run --mode tmux`). The legacy
+       `run_ralph_desk.zsh` runner rejects --flywheel/--flywheel-guard with
+       exit 2 + migration banner; users must use the Node entry. Same applies
+       to --with-self-verification: SV report generation is supported in
+       tmux mode via the Node leader's generateSVReport() (no longer
+       agent-mode-only).
 
   ⑦ Execute Verifier (see §7a for per-US and §7b for consensus details)
      - Build prompt (scoped to us_id if per-us mode) → log
@@ -774,6 +823,19 @@ The base signal vocabulary (`continue | verify | blocked`) is binary at the iter
 
 The downgrade is intentionally recoverable: the malformed signal is a worker-side prompt regression, not an environment failure, and the operator can fix it in-place.
 
+## 7h. Tmux Session Lifecycle Resilience (US-024/025/026 R12+R13+R14 P0)
+
+Multi-mission queue/daemon (`RLP_BACKGROUND=1`) workflows can lose their tmux session between missions — terminal close, manual `tmux kill-session`, or tmux server restart all drop the session and every pane in it. Three independent guards now compose:
+
+### R12 — Pane lifecycle monitor (5s authoritative budget)
+`_verify_pane_alive` and `_verify_session_alive` (lib_ralph_desk.zsh) check `#{pane_dead}` and `tmux has-session`. The runner invokes `_r12_check_lifecycle` at three sites: (1) immediately after `create_session()`, (2) at the top of every iteration, (3) right after worker dispatch and before the wait-loop. The check polls 5 attempts with 1-second sleep (5-second hard budget). On expiry it writes a BLOCKED sentinel with `reason_category=infra_failure`, `recoverable=true`, `suggested_action=restart` and exits 1 — never an infinite loop.
+
+### R13 — Detached session protection (RLP_BACKGROUND only)
+When `tmux new-session -d` collides with an existing session and `RLP_BACKGROUND=1`, the runner appends `-bg-<epoch>-<pid>` to `SESSION_NAME` and runs a `tmux has-session` loop with random 4-digit suffixes until the name is unique. The new session also sets `destroy-unattached off` so the session survives every attached client disconnecting. **Limits**: this option is best-effort; it does NOT survive a manual `tmux kill-session` or a tmux server restart. R12 will detect those events at the next checkpoint.
+
+### R14 — Project-scoped runner lockfile (mkdir atomic)
+`RUNNER_LOCKFILE_PATH` keys on `ROOT_HASH` (`shasum || sha1sum || cksum` of the repo root), so two different projects can run runners in parallel while the same project root is single-runner. `RUNNER_LOCKDIR` (`${RUNNER_LOCKFILE_PATH}.d`) is acquired by `mkdir` for true filesystem-level atomicity — no check-then-write race. Stale pids (no longer responding to `kill -0`) are reaped automatically; live duplicates exit 1 with a recovery hint.
+
 ## 8. Circuit Breaker
 
 | Condition | Verdict |