@ai-dev-methodologies/rlp-desk 0.11.1 → 0.13.0

package/src/node/runner/leader-registry.mjs

@@ -0,0 +1,100 @@
+// v5.7 §4.11.c — Leader-only cross-project campaign registry.
+//
+// Worker/Verifier/Flywheel/Guard prompts MUST NEVER reference this file. Only
+// the Leader (slash-command-tier process) appends one line per campaign-state-change.
+// /rlp-desk status (slug-less) reads this file and dereferences each project_root
+// to read that project's local analytics. Append-only — no in-place edits, no
+// compaction. Stale entries (project_root no longer exists) are tolerated by
+// the status reader.
+//
+// Path: ~/.claude/ralph-desk/registry.jsonl
+//
+// CI lint (v5.7 §4.11.c guardrail): run
+//   grep -rn 'registry\.jsonl' src/commands src/scripts src/node | grep -v Leader
+// must return empty (only Leader-tier code references this path).
+
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+const REGISTRY_PATH = path.join(os.homedir(), '.claude', 'ralph-desk', 'registry.jsonl');
+
+export function getRegistryPath() {
+  return REGISTRY_PATH;
+}
+
+/**
+ * Append a JSONL entry for a campaign state change. Idempotent on errors:
+ * silently swallow filesystem failures (registry is best-effort observability,
+ * not load-bearing). The Leader's `--add-dir "$HOME/.claude/ralph-desk"` permits
+ * the write without TUI prompts.
+ *
+ * @param {Object} entry — fields documented inline.
+ *   @param {string} entry.slug
+ *   @param {string} entry.projectRoot
+ *   @param {'running'|'complete'|'blocked'|'aborted'} entry.status
+ *   @param {string} [entry.workerModel]
+ *   @param {string} [entry.verifierModel]
+ *   @param {string} [entry.note]
+ */
+export async function appendRegistryEntry(entry) {
+  const line = JSON.stringify({
+    ts: new Date().toISOString(),
+    slug: entry.slug,
+    project_root: entry.projectRoot,
+    status: entry.status,
+    ...(entry.workerModel ? { worker_model: entry.workerModel } : {}),
+    ...(entry.verifierModel ? { verifier_model: entry.verifierModel } : {}),
+    ...(entry.note ? { note: entry.note } : {}),
+  }) + '\n';
+
+  try {
+    await fs.mkdir(path.dirname(REGISTRY_PATH), { recursive: true });
+    await fs.appendFile(REGISTRY_PATH, line, 'utf8');
+  } catch {
+    // Registry is best-effort. A failure here must NOT abort the campaign.
+    // The campaign's project-local analytics remain authoritative.
+  }
+}
+
+/**
+ * Read all registry entries. Each line is a JSON object; malformed lines are
+ * skipped. Returns most recent state per slug (last-write-wins on slug+project).
+ */
+export async function readRegistry() {
+  let raw;
+  try {
+    raw = await fs.readFile(REGISTRY_PATH, 'utf8');
+  } catch {
+    return [];
+  }
+  const entries = [];
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      entries.push(JSON.parse(line));
+    } catch {
+      // Skip malformed lines; do not abort.
+    }
+  }
+  return entries;
+}
+
+/**
+ * Dereference each entry's project_root and check whether it still exists.
+ * Used by /rlp-desk status to mark stale entries (worktree removed, etc.).
+ */
+export async function annotateStaleness(entries) {
+  const annotated = [];
+  for (const entry of entries) {
+    let stale = false;
+    try {
+      const stat = await fs.stat(entry.project_root);
+      if (!stat.isDirectory()) stale = true;
+    } catch {
+      stale = true;
+    }
+    annotated.push({ ...entry, stale });
+  }
+  return annotated;
+}

package/src/node/runner/prompt-detector.mjs

@@ -0,0 +1,41 @@
+// v0.13.0: early-detect Claude Code permission prompts in worker stdout.
+// Pre-v0.13.0 the leader only noticed via 30-min pollForSignal timeout, which
+// hid the failure category. Now we surface BLOCKED with category=permission_prompt
+// within seconds so wrappers can react.
+
+const SIGNATURES = [
+  /Do you want to /,
+  /\u276F\s*1\.\s*Yes/,
+  /allow Claude to edit its own settings/,
+  /1\.\s*Yes(?:,?\s*and allow Claude)/,
+];
+
+export function detectPermissionPrompt(chunk) {
+  if (typeof chunk !== 'string' || chunk.length === 0) {
+    return false;
+  }
+
+  for (const pattern of SIGNATURES) {
+    if (pattern.test(chunk)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export const PERMISSION_PROMPT_CATEGORY = 'permission_prompt';
+
+export function buildPermissionPromptBlocked(slug, iteration, snippet) {
+  const trimmedSnippet = typeof snippet === 'string'
+    ? snippet.split(/\r?\n/).slice(0, 5).join('\n').slice(0, 600)
+    : '';
+  return {
+    slug,
+    iteration: iteration ?? 0,
+    reason_category: 'infra_failure',
+    failure_category: PERMISSION_PROMPT_CATEGORY,
+    recoverable: false,
+    suggested_action: 'switch_worker_to_codex_or_use_agent_mode',
+    evidence_snippet: trimmedSnippet,
+  };
+}

package/src/node/runner/prompt-dismisser.mjs

@@ -0,0 +1,200 @@
+// v5.7 §4.13.b — Mid-execution permission-prompt auto-dismiss (Bug 4 fix).
+//
+// claude CLI surfaces TUI-layer prompts ("Do you want to create...", "Do you trust...")
+// even with --dangerously-skip-permissions on certain Write paths. Without this
+// helper, Workers/Verifiers in tmux mode hang until idle-nudge timeout.
+//
+// Window-bounded match (codex Critic v5.7): require both a prompt phrase AND a
+// TUI affordance marker on the SAME, PREVIOUS, or NEXT line. Whole-capture dual
+// matching would let unrelated text trigger Enter (R-V5-9 false-positive).
+// Per-pane 3-second debounce prevents rapid double-Enter.
+
+// PROMPT_RE / AFFORDANCE_RE mirror src/scripts/run_ralph_desk.zsh `_PROMPT_RE`
+// and `_AFFORDANCE_RE` so the Node leader catches the same TUI prompts the zsh
+// runner does — including codex CLI variants (`Proceed?`, `Approve this`,
+// `Press y to`, `Choose an option`, `Select [`) AND claude v2.x's new trust
+// prompt format (Quick safety check / trust this folder / `❯1.Yes`).
+// If you change one regex, change the other and the corresponding tests.
+const PROMPT_RE =
+  /Do you (want to|trust)|Confirm execution|Are you sure|Continue\?|Proceed\?|Allow this|Approve this|Press y to|Choose an option|Select \[|Quick safety check|trust this (folder|directory)|Is this a project you/;
+// AFFORDANCE_RE: `(yes/no` (open form) covers prose default-No prompts;
+// `❯\s*\d+\.` covers numbered pickers with optional space after cursor (claude
+// v2.x narrow-pane wrap renders `❯1.` without space); `Enter to confirm`
+// matches the new trust-prompt footer; `1) Yes` / `Y)` / `press y to` cover
+// codex CLI selection menus.
+const AFFORDANCE_RE =
+  /\(y\/n\)|\[Y\/n\]|\[y\/N\]|\(yes\/no|❯\s*\d+\.|(?:^|\s)1\) (Yes|No)|(?:^|\s)[YyNn]\)|press (y|enter) to|Enter to confirm/;
+// v5.7 §4.17 (Node parity): default-No prompts must NOT auto-Enter — that
+// CANCELS the operation. Mirror zsh `_DEFAULT_NO_RE`. Bracket form is
+// case-sensitive (`[y/N]` only — `[Y/n]` is default-Yes); prose form is
+// case-insensitive via explicit char classes so we don't fall back to the `i`
+// regex flag (which would also match `[Y/n]`).
+const DEFAULT_NO_RE = /\[y\/N\]|\(yes\/no,\s*default\s+no\)|[Dd]efault[: ]+[Nn]o|^\s*N\)/;
+// v5.7 §4.18: "active task" markers (omc-team parity, tmux-session.ts:659).
+// Used to suppress unknown-prompt fast-fail when the Worker is busy producing
+// output that may legitimately contain "(y/n)"-shaped substrings.
+const ACTIVE_TASK_RE =
+  /esc to interrupt|background terminal running|^\s*[·✻]\s+[A-Za-z]+(\.{3}|…)/m;
+const DEBOUNCE_MS = 3000;
+
+const lastApprovalAt = new Map();
+
+export function _resetForTesting() {
+  lastApprovalAt.clear();
+}
+
+export async function autoDismissPrompts(paneId, deps) {
+  const {
+    sendKeys,
+    capturePane,
+    log = () => {},
+    now = Date.now,
+    onDefaultNoBlock,
+  } = deps;
+
+  const t = now();
+  const prev = lastApprovalAt.get(paneId);
+  if (prev !== undefined && t - prev < DEBOUNCE_MS) {
+    return false;
+  }
+
+  let capture;
+  try {
+    capture = await capturePane(paneId);
+  } catch {
+    return false;
+  }
+  if (!capture) {
+    return false;
+  }
+
+  // v5.7 §4.21 (E2E real-claude-CLI finding): claude v2.x trust prompt is
+  // multi-line and wraps narrowly, so line-adjacency PROMPT_RE+AFFORDANCE_RE
+  // misses it. Special-case the signature ("Quick safety check ... Enter to
+  // confirm" with `❯N.` numbered picker selecting Yes by default).
+  // This is a default-Yes prompt — pressing Enter approves trust.
+  // §4.21.b: tmux narrow-pane wrap breaks `Quick safety check` across
+  // lines (`Quick safety\n check`). Normalize whitespace before matching.
+  const normalizedCapture = capture.replace(/\s+/g, ' ');
+  if (
+    (/Quick safety check/.test(normalizedCapture) ||
+      /trust this (folder|directory)/.test(normalizedCapture)) &&
+    /Enter to confirm/.test(normalizedCapture) &&
+    /❯ ?\d+\. ?Yes/.test(normalizedCapture)
+  ) {
+    log({
+      category: 'FLOW',
+      event: 'claude_trust_prompt_auto_approved',
+      pane_id: paneId,
+    });
+    await sendKeys(paneId, 'Enter');
+    lastApprovalAt.set(paneId, t);
+    return true;
+  }
+  // Older claude trust prompt format ("Do you trust the contents of this
+  // directory?" + "Yes, continue / No, quit" — omc-team parity).
+  if (
+    /Do you trust the contents of this directory/.test(capture) &&
+    /Yes,\s*continue|Press enter to continue/.test(capture)
+  ) {
+    log({
+      category: 'FLOW',
+      event: 'claude_trust_prompt_auto_approved',
+      pane_id: paneId,
+    });
+    await sendKeys(paneId, 'Enter');
+    lastApprovalAt.set(paneId, t);
+    return true;
+  }
+
+  // v5.7 §4.23 (E2E real-claude-CLI finding): tmux narrow-pane wrap breaks
+  // multi-line prompts ("Do you want to\nmake this edit to\nprd-sum-fn.md?\n
+  // ❯ 1. Yes") so line-adjacency PROMPT+AFFORDANCE±1 misses them. Fix:
+  // examine the LAST 15 normalized lines (where the active prompt lives)
+  // as a single joined+whitespace-collapsed string. PROMPT_RE + AFFORDANCE
+  // both present → auto-Enter unless DEFAULT_NO_RE also present (BLOCK).
+  // §4.17.b is preserved: scan-all default-No protects against scrollback
+  // contamination (older [Y/n] alongside active [y/N]).
+  const lines = capture.split('\n');
+  const tailLines = lines.slice(-15);
+  const tailNormalized = tailLines.join(' ').replace(/\s+/g, ' ');
+
+  const promptVisible = PROMPT_RE.test(tailNormalized) && AFFORDANCE_RE.test(tailNormalized);
+  // Default-No: scan FULL capture (not just tail) so an older default-Yes
+  // bracket in scrollback can't override an active default-No. §4.17.b.
+  const defaultNoSeen = DEFAULT_NO_RE.test(capture);
+  const samplePattern = tailNormalized.slice(0, 120);
+
+  if (defaultNoSeen) {
+    log({
+      category: 'FLOW',
+      event: 'permission_prompt_default_no_blocked',
+      pane_id: paneId,
+    });
+    if (typeof onDefaultNoBlock === 'function') {
+      try {
+        onDefaultNoBlock({
+          paneId,
+          reason: `default-No prompt requires explicit human decision (sample: ${samplePattern})`,
+          category: 'infra_failure',
+        });
+      } catch {
+        // Caller errors must not propagate into the poll loop.
+      }
+    }
+    lastApprovalAt.set(paneId, t);
+    return false;
+  }
+
+  if (promptVisible) {
+    log({ category: 'FLOW', event: 'permission_prompt_auto_approved', pane_id: paneId });
+    await sendKeys(paneId, 'Enter');
+    lastApprovalAt.set(paneId, t);
+    return true;
+  }
+
+  // v5.7 §4.18: unknown-prompt fast-fail (E2E + omc benchmarking).
+  // If pane has an affordance bracket but no recognized PROMPT_RE phrasing,
+  // refuse to guess auto-Enter (could be wrong default) and BLOCK so the
+  // operator can extend PROMPT_RE — instead of waiting 10 min for freeze
+  // timeout. Skip if active-task markers are present (Worker is producing
+  // output and the affordance text is likely just transcript).
+  const captureHasActiveTask = ACTIVE_TASK_RE.test(capture);
+  if (captureHasActiveTask) {
+    return false;
+  }
+  // Only inspect the last 5 non-empty lines (where an idle prompt would sit).
+  const tail5Lines = lines.filter((l) => l.length > 0).slice(-5);
+  let suspectLine = '';
+  for (const line of tail5Lines) {
+    if (AFFORDANCE_RE.test(line)) {
+      suspectLine = line;
+      break;
+    }
+  }
+  if (suspectLine) {
+    const tailHasDefaultNo = tail5Lines.some((l) => DEFAULT_NO_RE.test(l));
+    log({
+      category: 'GOV',
+      event: 'unknown_prompt_detected',
+      pane_id: paneId,
+      default_no: tailHasDefaultNo,
+    });
+    if (typeof onDefaultNoBlock === 'function') {
+      try {
+        onDefaultNoBlock({
+          paneId,
+          reason: tailHasDefaultNo
+            ? `Pane shows a default-No affordance but the surrounding prompt phrasing is not in PROMPT_RE. Sample: ${suspectLine.slice(0, 120)}`
+            : `Pane shows a y/n affordance marker without a recognized prompt phrasing. Refusing to guess auto-Enter. Sample: ${suspectLine.slice(0, 120)}`,
+          category: 'infra_failure',
+        });
+      } catch {
+        // Caller errors must not propagate.
+      }
+    }
+    lastApprovalAt.set(paneId, t);
+    return false;
+  }
+  return false;
+}

package/src/node/shared/fs.mjs

@@ -21,3 +21,41 @@ export async function writeFileAtomic(targetPath, content) {
     throw error;
   }
 }
+
+// v5.7 §4.24 — first-writer-wins sentinel write (BLOCKED/COMPLETE).
+// Distinct from `writeFileAtomic` (last-writer-wins via rename): sentinels
+// must NOT be overwritten once any path has classified the campaign outcome.
+// Multiple race-prone error paths in `runCampaign()` (worker exit, verifier
+// timeout, malformed signal, leader crash backstop) can fire concurrently;
+// O_EXCL guarantees exactly one writes.
+//
+// IMPORTANT: this primitive intentionally does NOT call `ensureProjectPath`.
+// Sentinels are written under the CAMPAIGN root (e.g. `/tmp/user-project/.
+// claude/ralph-desk/memos/`), which is independent of the rlp-desk source
+// repo. Path validation is the caller's responsibility (run() resolves
+// rootDir from options.rootDir or process.cwd()).
+//
+// Returns:
+//   { wrote: true } — this caller wrote the sentinel
+//   { wrote: false, reason: 'already_exists' } — another path already wrote
+//   throws on filesystem errors other than EEXIST
+export async function writeSentinelExclusive(targetPath, content) {
+  const resolvedPath = path.resolve(targetPath);
+  const targetDirectory = path.dirname(resolvedPath);
+  await fs.mkdir(targetDirectory, { recursive: true });
+  let handle;
+  try {
+    handle = await fs.open(resolvedPath, 'wx');
+  } catch (error) {
+    if (error && error.code === 'EEXIST') {
+      return { wrote: false, reason: 'already_exists' };
+    }
+    throw error;
+  }
+  try {
+    await handle.writeFile(content);
+  } finally {
+    await handle.close();
+  }
+  return { wrote: true };
+}

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

@@ -0,0 +1,56 @@
+// v5.7 §4.6 — 4-category structured debug log (telemetry parity with zsh).
+//
+// zsh runner emits 67 lines tagged [GOV] / [DECIDE] / [OPTION] / [FLOW] to
+// debug.log; Node leader had zero. This helper provides the structured
+// emission API. Call sites are ported incrementally — every new code path
+// 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)
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const VALID_CATEGORIES = new Set(['GOV', 'DECIDE', 'OPTION', 'FLOW']);
+
+/**
+ * Append a structured log line to debug.log. Format mirrors zsh log_debug:
+ *   [YYYY-MM-DD HH:MM:SS] [CATEGORY] key=value key=value ...
+ *
+ * @param {Object} args
+ * @param {string} args.debugLogPath — absolute path to debug.log
+ * @param {'GOV'|'DECIDE'|'OPTION'|'FLOW'} 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).
+ */
+export async function debugLog({ debugLogPath, category, fields }) {
+  if (!debugLogPath || !VALID_CATEGORIES.has(category)) return;
+  const ts = new Date().toISOString().replace('T', ' ').slice(0, 19);
+  const flat = Object.entries(fields ?? {})
+    .map(([k, v]) => `${k}=${formatValue(v)}`)
+    .join(' ');
+  const line = `[${ts}] [${category}] ${flat}\n`;
+  try {
+    await fs.mkdir(path.dirname(debugLogPath), { recursive: true });
+    await fs.appendFile(debugLogPath, line, 'utf8');
+  } catch {
+    // Best-effort: never abort the campaign for a debug log write failure.
+  }
+}
+
+function formatValue(v) {
+  if (v === null || v === undefined) return 'null';
+  if (typeof v === 'string' && /[\s=]/.test(v)) return JSON.stringify(v);
+  return String(v);
+}
+
+/**
+ * Convenience: bind debugLogPath so callers get a per-campaign logger.
+ */
+export function makeDebugLogger(debugLogPath) {
+  return (category, fields) => debugLog({ debugLogPath, category, fields });
+}

package/src/node/util/desk-root.mjs

@@ -0,0 +1,24 @@
+import path from 'node:path';
+
+export const DEFAULT_DESK_REL = '.rlp-desk';
+export const LEGACY_DESK_REL = path.join('.claude', 'ralph-desk');
+
+export function resolveDeskRoot(rootDir, env = process.env) {
+  const override = (env && typeof env.RLP_DESK_RUNTIME_DIR === 'string') ? env.RLP_DESK_RUNTIME_DIR : '';
+  const trimmed = override.trim();
+
+  if (!trimmed) {
+    return path.join(rootDir, DEFAULT_DESK_REL);
+  }
+
+  if (path.isAbsolute(trimmed)) {
+    throw new Error('RLP_DESK_RUNTIME_DIR must be relative to project root, not absolute');
+  }
+
+  const segments = trimmed.split(/[\\/]/);
+  if (segments.includes('..')) {
+    throw new Error('RLP_DESK_RUNTIME_DIR must not contain parent traversal (..)');
+  }
+
+  return path.join(rootDir, trimmed);
+}

package/src/node/util/shell-quote.mjs

@@ -0,0 +1,12 @@
+// POSIX-safe single-quote escape for shell argument values.
+// Use when emitting commands as strings (claude/codex CLI invocations,
+// tmux send-keys payloads). Defends against brackets, spaces, single
+// quotes, and other shell metacharacters in model ids and slugs.
+//
+// Contract: shellQuote("opus") -> "'opus'"
+//           shellQuote("claude-opus-4-7[1m]") -> "'claude-opus-4-7[1m]'"
+//           shellQuote("model'with'quote") -> "'model'\\''with'\\''quote'"
+
+export function shellQuote(value) {
+  return "'" + String(value).replace(/'/g, "'\\''") + "'";
+}