ralph-lisa-loop 0.3.0 → 0.3.8

package/README.md

@@ -144,6 +144,27 @@ Policy rules:
 - Ralph's [RESEARCH] must have substantive content
 - Lisa's [PASS]/[NEEDS_WORK] must include at least 1 reason
 
+### Mid-Session Task Update
+Change direction without restarting:
+```bash
+ralph-lisa update-task "switch to REST instead of GraphQL"
+```
+Appends to task.md (preserving history). Task context is auto-injected into work.md submissions and watcher trigger messages so both agents always see the current goal.
+
+### Round 1 Mandatory Plan
+Ralph's first submission must be `[PLAN]` — gives Lisa a chance to verify task understanding before coding begins.
+
+### Goal Guardian
+Lisa reads task.md before every review and checks for direction drift. Catching misalignment early is prioritized over code-level review.
+
+### Watcher v3
+- **Fire-and-forget triggering**: Removed output stability wait and delivery verification for faster turn transitions
+- **30s cooldown**: Prevents re-triggering during normal work
+- **Checkpoint system**: Set `RL_CHECKPOINT_ROUNDS=N` to pause for human review every N rounds
+- **Auto-restart**: Watcher automatically restarts on crash (session-guarded)
+- **Configurable log threshold**: `RL_LOG_MAX_MB` (default 5, min 1) with proportional tail retention
+- **Heartbeat file**: `.dual-agent/.watcher_heartbeat` for external liveness checks
+
 ### Deadlock Escape
 After 5 rounds without consensus: `[OVERRIDE]` (proceed anyway) or `[HANDOFF]` (escalate to human).
 
@@ -172,6 +193,7 @@ ralph-lisa history                       # Full history
 
 # Flow control
 ralph-lisa step "phase-name"             # Enter new phase
+ralph-lisa update-task "new direction"   # Update task direction mid-session
 ralph-lisa archive [name]                # Archive session
 ralph-lisa clean                         # Clean session
 
@@ -199,6 +221,7 @@ your-project/
 │   └── skills/            # Codex skills
 └── .dual-agent/           # Session state
     ├── turn.txt           # Current turn
+    ├── task.md            # Task goal (updated via update-task)
     ├── work.md            # Ralph's submissions
     ├── review.md          # Lisa's submissions
     └── history.md         # Full history
@@ -220,6 +243,14 @@ For auto mode:
 - tmux (required)
 - fswatch (macOS) or inotify-tools (Linux) — optional, speeds up turn detection; falls back to polling without them
 
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `RL_POLICY_MODE` | `off` | Policy check mode: `off`, `warn`, `block` |
+| `RL_CHECKPOINT_ROUNDS` | `0` (disabled) | Pause for human review every N rounds |
+| `RL_LOG_MAX_MB` | `5` | Pane log truncation threshold in MB (min 1) |
+
 ## Ecosystem
 
 Part of the [TigerHill](https://github.com/Click-Intelligence-LLC/TigerHill) project family.

package/dist/cli.js

@@ -65,6 +65,9 @@ switch (cmd) {
     case "logs":
         (0, commands_js_1.cmdLogs)(rest);
         break;
+    case "update-task":
+        (0, commands_js_1.cmdUpdateTask)(rest);
+        break;
     case "help":
     case "--help":
     case "-h":
@@ -111,6 +114,7 @@ function showHelp() {
     console.log("");
     console.log("Flow Control:");
     console.log('  ralph-lisa step "name"              Enter new step');
+    console.log('  ralph-lisa update-task "desc"        Update task direction');
     console.log("  ralph-lisa archive [name]           Archive session");
     console.log("  ralph-lisa clean                    Clean session");
     console.log("");

package/dist/commands.d.ts

@@ -13,6 +13,7 @@ export declare function cmdStep(args: string[]): void;
 export declare function cmdHistory(): void;
 export declare function cmdArchive(args: string[]): void;
 export declare function cmdClean(): void;
+export declare function cmdUpdateTask(args: string[]): void;
 export declare function cmdUninit(): void;
 export declare function cmdInitProject(args: string[]): void;
 export declare function cmdStart(args: string[]): void;

package/dist/commands.js

@@ -48,6 +48,7 @@ exports.cmdStep = cmdStep;
 exports.cmdHistory = cmdHistory;
 exports.cmdArchive = cmdArchive;
 exports.cmdClean = cmdClean;
+exports.cmdUpdateTask = cmdUpdateTask;
 exports.cmdUninit = cmdUninit;
 exports.cmdInitProject = cmdInitProject;
 exports.cmdStart = cmdStart;
@@ -183,6 +184,11 @@ function cmdSubmitRalph(args) {
     const ts = (0, state_js_1.timestamp)();
     const summary = (0, state_js_1.extractSummary)(content);
     const dir = (0, state_js_1.stateDir)();
+    // Auto-inject task context so Lisa always sees the task goal
+    // Use last meaningful line (update-task appends new directions at the end)
+    const taskFile = (0, state_js_1.readFile)(path.join(dir, "task.md"));
+    const taskLines = taskFile.split("\n").filter((l) => l.trim() && !l.startsWith("#") && !l.startsWith("---") && !l.startsWith("Created:") && !l.startsWith("Updated:"));
+    const taskContext = taskLines[taskLines.length - 1] || "";
     // Auto-attach files_changed for CODE/FIX submissions
     let filesChangedSection = "";
     if (tag === "CODE" || tag === "FIX") {
@@ -191,7 +197,8 @@ function cmdSubmitRalph(args) {
             filesChangedSection = `**Files Changed**:\n${files.map((f) => `- ${f}`).join("\n")}\n\n`;
         }
     }
-    (0, state_js_1.writeFile)(path.join(dir, "work.md"), `# Ralph Work\n\n## [${tag}] Round ${round} | Step: ${step}\n**Updated**: ${ts}\n**Summary**: ${summary}\n${filesChangedSection ? "\n" + filesChangedSection : "\n"}${content}\n`);
+    const taskLine = taskContext ? `**Task**: ${taskContext}\n` : "";
+    (0, state_js_1.writeFile)(path.join(dir, "work.md"), `# Ralph Work\n\n## [${tag}] Round ${round} | Step: ${step}\n${taskLine}**Updated**: ${ts}\n**Summary**: ${summary}\n${filesChangedSection ? "\n" + filesChangedSection : "\n"}${content}\n`);
     // External sources (--file/--stdin) get compact history to reduce context bloat
     const historyContent = external
         ? `[${tag}] ${summary}\n\n(Full content in work.md)`
@@ -514,6 +521,22 @@ function cmdClean() {
         console.log("Session cleaned");
     }
 }
+// ─── update-task ─────────────────────────────────
+function cmdUpdateTask(args) {
+    (0, state_js_1.checkSession)();
+    const newTask = args.join(" ");
+    if (!newTask) {
+        console.error('Usage: ralph-lisa update-task "new task description"');
+        process.exit(1);
+    }
+    const dir = (0, state_js_1.stateDir)();
+    const taskPath = path.join(dir, "task.md");
+    const ts = (0, state_js_1.timestamp)();
+    // Append new direction with timestamp (preserves history)
+    fs.appendFileSync(taskPath, `\n---\nUpdated: ${ts}\n\n${newTask}\n`, "utf-8");
+    console.log(`Task updated: ${newTask}`);
+    console.log(`(Appended to ${taskPath})`);
+}
 // ─── uninit ──────────────────────────────────────
 const MARKER = "RALPH-LISA-LOOP";
 function cmdUninit() {
@@ -1044,8 +1067,9 @@ function cmdAuto(args) {
     // Create watcher script
     const watcherScript = path.join(dir, "watcher.sh");
     let watcherContent = `#!/bin/bash
-# Turn watcher v2 - reliable agent triggering with health checks
+# Turn watcher v3 - fire-and-forget agent triggering
 # Architecture: polling main loop + optional event acceleration
+# v3: Removed output stability wait + delivery verification (RLL-001)
 
 STATE_DIR=".dual-agent"
 SESSION="${sessionName}"
@@ -1054,6 +1078,10 @@ SEEN_TURN=""
 ACKED_TURN=""
 FAIL_COUNT=0
 ACCEL_PID=""
+LAST_ACK_TIME=0
+CHECKPOINT_ROUNDS=\${RL_CHECKPOINT_ROUNDS:-0}
+CHECKPOINT_REMIND_TIME=0
+CLEANUP_DONE=0
 
 PANE0_LOG="\${STATE_DIR}/pane0.log"
 PANE1_LOG="\${STATE_DIR}/pane1.log"
@@ -1089,6 +1117,8 @@ echo \$\$ > "\$PID_FILE"
 # ─── Cleanup trap ────────────────────────────────
 
 cleanup() {
+  if (( CLEANUP_DONE )); then return; fi
+  CLEANUP_DONE=1
   echo "[Watcher] Shutting down..."
   # Stop pipe-pane capture
   tmux pipe-pane -t "\${SESSION}:0.0" 2>/dev/null || true
@@ -1192,15 +1222,18 @@ check_for_interactive_prompt() {
 truncate_log_if_needed() {
   local pane="\$1"
   local log_file="\$2"
-  local max_bytes=1048576  # 1MB
+  local max_mb=\${RL_LOG_MAX_MB:-5}
+  if (( max_mb < 1 )); then max_mb=1; fi
+  local max_bytes=$(( max_mb * 1048576 ))
+  local tail_bytes=$(( max_mb * 102400 ))  # ~10% of max
 
   if [[ ! -f "\$log_file" ]]; then return; fi
   local size
   size=\$(wc -c < "\$log_file" 2>/dev/null | tr -d ' ')
   if (( size > max_bytes )); then
-    echo "[Watcher] Truncating \$log_file (\${size} bytes > 1MB)"
+    echo "[Watcher] Truncating \$log_file (\${size} bytes > \${max_mb}MB)"
     tmux pipe-pane -t "\${SESSION}:\${pane}" 2>/dev/null || true
-    tail -c 102400 "\$log_file" > "\${log_file}.tmp" && mv "\${log_file}.tmp" "\$log_file"
+    tail -c \$tail_bytes "\$log_file" > "\${log_file}.tmp" && mv "\${log_file}.tmp" "\$log_file"
     tmux pipe-pane -o -t "\${SESSION}:\${pane}" "cat >> \\"\$log_file\\"" 2>/dev/null || true
   fi
 }
@@ -1227,35 +1260,8 @@ send_go_to_pane() {
     return 1
   fi
 
-  # 3. Wait for output to stabilize (max 60s, then FAIL — not continue)
-  local wait_count=0
-  while ! check_output_stable "\$log_file" 5; do
-    wait_count=\$((wait_count + 1))
-    if (( wait_count > 30 )); then
-      echo "[Watcher] WARNING: \$agent_name output not stabilizing after 60s, returning failure"
-      return 1
-    fi
-    sleep 2
-  done
-
-  # 4. Double-confirm stability
-  sleep 2
-  if ! check_output_stable "\$log_file" 2; then
-    echo "[Watcher] \$agent_name output resumed during confirmation wait, returning failure"
-    return 1
-  fi
-
-  # 5. Re-check interactive prompt
-  if check_for_interactive_prompt "\$pane"; then
-    echo "[Watcher] Skipping \$agent_name - interactive prompt detected (post-wait)"
-    return 1
-  fi
-
-  # 6. Record log size before sending
-  local pre_size
-  pre_size=\$(wc -c < "\$log_file" 2>/dev/null | tr -d ' ' || echo 0)
-
-  # 7. Send trigger message + Enter with retry
+  # 3. Send trigger message + Enter with retry
+  # tmux send-keys is synchronous — no need to verify delivery via log growth
   # Use first 20 chars as detection marker (long messages wrap in narrow panes)
   local detect_marker="\${go_msg:0:20}"
   while (( attempt < max_retries )); do
@@ -1277,16 +1283,13 @@ send_go_to_pane() {
     fi
   done
 
-  # 8. Verify delivery: did log file grow?
-  sleep 5
-  local post_size
-  post_size=\$(wc -c < "\$log_file" 2>/dev/null | tr -d ' ' || echo 0)
-  if (( post_size <= pre_size )); then
-    echo "[Watcher] WARNING: No new output from \$agent_name after sending 'go'"
+  # Check if retries exhausted (message never submitted)
+  if (( attempt >= max_retries )); then
+    echo "[Watcher] FAILED: Could not deliver message to \$agent_name after \$max_retries retries"
     return 1
   fi
 
-  echo "[Watcher] OK: \$agent_name is working (output \$pre_size -> \$post_size)"
+  echo "[Watcher] OK: Message sent to \$agent_name (fire-and-forget)"
   return 0
 }
 
@@ -1294,6 +1297,15 @@ send_go_to_pane() {
 
 trigger_agent() {
   local turn="\$1"
+
+  # Read task context for trigger messages (last meaningful line = latest direction)
+  local task_ctx=""
+  if [[ -f "\$STATE_DIR/task.md" ]]; then
+    # Extract last meaningful line (skip header, separators, timestamps)
+    # Consistent with cmdSubmitRalph which also uses last meaningful line
+    task_ctx=\$(grep -v '^#\\|^---\\|^Created:\\|^Updated:\\|^$' "\$STATE_DIR/task.md" 2>/dev/null | tail -1)
+  fi
+
   if [[ "\$turn" == "ralph" ]]; then
     # Check pause state
     if (( PANE0_PAUSED )); then
@@ -1308,7 +1320,11 @@ trigger_agent() {
         return 1
       fi
     fi
-    local ralph_msg="Your turn. Lisa's feedback is ready — run: ralph-lisa read review.md"
+    local ralph_msg="Your turn."
+    if [[ -n "\$task_ctx" ]]; then
+      ralph_msg="Your turn. Task: \${task_ctx}."
+    fi
+    ralph_msg="\${ralph_msg} Lisa's feedback is ready — run: ralph-lisa read review.md"
     send_go_to_pane "0.0" "Ralph" "\$PANE0_LOG" "\$ralph_msg"
     local rc=\$?
     if (( rc != 0 )); then
@@ -1338,7 +1354,11 @@ trigger_agent() {
         return 1
       fi
     fi
-    local lisa_msg="Your turn. Ralph's work is ready — run: ralph-lisa read work.md"
+    local lisa_msg="Your turn."
+    if [[ -n "\$task_ctx" ]]; then
+      lisa_msg="Your turn. Task: \${task_ctx}."
+    fi
+    lisa_msg="\${lisa_msg} Ralph's work is ready — run: ralph-lisa read work.md"
     send_go_to_pane "0.1" "Lisa" "\$PANE1_LOG" "\$lisa_msg"
     local rc=\$?
     if (( rc != 0 )); then
@@ -1363,6 +1383,9 @@ trigger_agent() {
 check_and_trigger() {
   check_session_alive
 
+  # Heartbeat: write epoch so external tools can check watcher liveness
+  echo \$(date +%s) > "\${STATE_DIR}/.watcher_heartbeat"
+
   # Truncate logs if too large
   truncate_log_if_needed "0.0" "\$PANE0_LOG"
   truncate_log_if_needed "0.1" "\$PANE1_LOG"
@@ -1370,11 +1393,12 @@ check_and_trigger() {
   if [[ -f "\$STATE_DIR/turn.txt" ]]; then
     CURRENT_TURN=\$(cat "\$STATE_DIR/turn.txt" 2>/dev/null || echo "")
 
-    # Detect new turn change (reset fail count)
+    # Detect new turn change (reset fail count + cooldown)
     if [[ -n "\$CURRENT_TURN" && "\$CURRENT_TURN" != "\$SEEN_TURN" ]]; then
       echo "[Watcher] Turn changed: \$SEEN_TURN -> \$CURRENT_TURN"
       SEEN_TURN="\$CURRENT_TURN"
       FAIL_COUNT=0
+      LAST_ACK_TIME=0
 
       # Write round separator to pane logs for transcript tracking
       local round_ts
@@ -1384,6 +1408,43 @@ check_and_trigger() {
       echo -e "\$round_marker" >> "\$PANE1_LOG" 2>/dev/null || true
     fi
 
+    # Cooldown: skip delivery if last ack was < 30s ago (prevents re-triggering during normal work)
+    # Placed AFTER turn-change detection so new turns are never suppressed
+    if (( LAST_ACK_TIME > 0 )); then
+      local now_epoch
+      now_epoch=\$(date +%s)
+      local elapsed=\$(( now_epoch - LAST_ACK_TIME ))
+      if (( elapsed < 30 )); then
+        return
+      fi
+    fi
+
+    # Checkpoint: pause for user review at configured round intervals
+    if (( CHECKPOINT_ROUNDS > 0 )); then
+      local round
+      round=\$(cat "\$STATE_DIR/round.txt" 2>/dev/null || echo 1)
+      if (( round > 1 )) && (( (round - 1) % CHECKPOINT_ROUNDS == 0 )); then
+        # At checkpoint round — file is source of truth (crash-safe)
+        if [[ -f "\${STATE_DIR}/.checkpoint_ack" ]]; then
+          # Acked — proceed (keep file until round advances past checkpoint)
+          :
+        else
+          # Not acked — pause with periodic 30s reminder
+          local now_epoch
+          now_epoch=\$(date +%s)
+          if (( CHECKPOINT_REMIND_TIME == 0 )) || (( now_epoch - CHECKPOINT_REMIND_TIME >= 30 )); then
+            echo "[Watcher] CHECKPOINT: Round \$round. Review direction before continuing."
+            echo "[Watcher] To continue: touch \${STATE_DIR}/.checkpoint_ack"
+            CHECKPOINT_REMIND_TIME=\$now_epoch
+          fi
+          return
+        fi
+      else
+        # Not at checkpoint round — clean up stale ack from previous checkpoint
+        rm -f "\${STATE_DIR}/.checkpoint_ack"
+      fi
+    fi
+
     # Need to deliver? (seen but not yet acked)
     if [[ -n "\$SEEN_TURN" && "\$SEEN_TURN" != "\$ACKED_TURN" ]]; then
       # Backoff on repeated failures
@@ -1398,7 +1459,8 @@ check_and_trigger() {
       if trigger_agent "\$SEEN_TURN"; then
         ACKED_TURN="\$SEEN_TURN"
         FAIL_COUNT=0
-        echo "[Watcher] Turn acknowledged: \$SEEN_TURN"
+        LAST_ACK_TIME=\$(date +%s)
+        echo "[Watcher] Turn acknowledged: \$SEEN_TURN (cooldown 30s)"
       else
         FAIL_COUNT=\$((FAIL_COUNT + 1))
         echo "[Watcher] Trigger failed (fail_count=\$FAIL_COUNT), will retry next cycle"
@@ -1409,9 +1471,12 @@ check_and_trigger() {
 
 # ─── Main ────────────────────────────────────────
 
-echo "[Watcher] Starting v2... (Ctrl+C to stop)"
+echo "[Watcher] Starting v3... (Ctrl+C to stop)"
 echo "[Watcher] Monitoring \$STATE_DIR/turn.txt"
 echo "[Watcher] Pane logs: \$PANE0_LOG, \$PANE1_LOG"
+if (( CHECKPOINT_ROUNDS > 0 )); then
+  echo "[Watcher] Checkpoint every \$CHECKPOINT_ROUNDS rounds (RL_CHECKPOINT_ROUNDS)"
+fi
 echo "[Watcher] PID: \$\$"
 
 sleep 5
@@ -1463,9 +1528,31 @@ done
     execSync(`tmux send-keys -t "${sessionName}:0.0" "echo '=== Ralph (Claude Code) ===' && ${claudeCmd}" Enter`);
     execSync(`tmux send-keys -t "${sessionName}:0.1" "echo '=== Lisa (Codex) ===' && ${codexCmd}" Enter`);
     execSync(`tmux select-pane -t "${sessionName}:0.0"`);
-    // Watcher runs in background (logs to .dual-agent/watcher.log)
+    // Kill old wrapper process if present (prevents duplication on repeated cmdAuto)
+    const wrapperPidFile = path.join(dir, "watcher_wrapper.pid");
+    if (fs.existsSync(wrapperPidFile)) {
+        const oldWrapperPid = (0, state_js_1.readFile)(wrapperPidFile).trim();
+        if (oldWrapperPid) {
+            try {
+                // Validate process identity before killing (avoid PID reuse hazard)
+                const oldArgs = execSync(`ps -p ${oldWrapperPid} -o args= 2>/dev/null || true`).toString().trim();
+                if (oldArgs && oldArgs.includes("tmux has-session")) {
+                    execSync(`kill ${oldWrapperPid} 2>/dev/null || true`);
+                    try {
+                        execSync(`sleep 0.5`);
+                    }
+                    catch { /* ignore */ }
+                }
+            }
+            catch {
+                // ignore — process already dead or PID invalid
+            }
+        }
+        fs.unlinkSync(wrapperPidFile);
+    }
+    // Watcher runs in background with session-guarded restart loop
     const watcherLog = path.join(dir, "watcher.log");
-    execSync(`bash -c 'nohup "${watcherScript}" > "${watcherLog}" 2>&1 &'`);
+    execSync(`bash -c 'nohup bash -c '"'"'while tmux has-session -t "${sessionName}" 2>/dev/null; do bash "${watcherScript}"; EXIT_CODE=$?; if ! tmux has-session -t "${sessionName}" 2>/dev/null; then echo "[Watcher] Session gone, not restarting." >> "${watcherLog}"; break; fi; echo "[Watcher] Exited ($EXIT_CODE), restarting in 5s..." >> "${watcherLog}"; sleep 5; done'"'"' > "${watcherLog}" 2>&1 & echo $! > "${wrapperPidFile}"'`);
     console.log("");
     console.log(line());
     console.log("Auto Mode Started!");

package/dist/test/cli.test.js

@@ -592,3 +592,68 @@ function run(...args) {
         assert.ok(r.stdout.includes("[CODE]"));
     });
 });
+(0, node_test_1.describe)("CLI: update-task", () => {
+    (0, node_test_1.beforeEach)(() => {
+        fs.rmSync(TMP, { recursive: true, force: true });
+        fs.mkdirSync(TMP, { recursive: true });
+        run("init", "--minimal");
+    });
+    (0, node_test_1.afterEach)(() => {
+        fs.rmSync(TMP, { recursive: true, force: true });
+    });
+    (0, node_test_1.it)("creates task entry with timestamp", () => {
+        const r = run("update-task", "New direction for the project");
+        assert.strictEqual(r.exitCode, 0);
+        assert.ok(r.stdout.includes("Task updated"));
+        const task = fs.readFileSync(path.join(TMP, ".dual-agent", "task.md"), "utf-8");
+        assert.ok(task.includes("New direction for the project"));
+        assert.ok(task.includes("Updated:"));
+    });
+    (0, node_test_1.it)("preserves original task when updating", () => {
+        const task = fs.readFileSync(path.join(TMP, ".dual-agent", "task.md"), "utf-8");
+        const originalContent = task.trim();
+        run("update-task", "Changed direction");
+        const updated = fs.readFileSync(path.join(TMP, ".dual-agent", "task.md"), "utf-8");
+        // Original content still present
+        assert.ok(updated.includes("Waiting for task assignment"));
+        assert.ok(updated.includes("Changed direction"));
+    });
+    (0, node_test_1.it)("fails when no description given", () => {
+        const r = run("update-task");
+        assert.notStrictEqual(r.exitCode, 0);
+        assert.ok(r.stdout.includes("Usage"));
+    });
+});
+(0, node_test_1.describe)("CLI: task context in work.md", () => {
+    (0, node_test_1.beforeEach)(() => {
+        fs.rmSync(TMP, { recursive: true, force: true });
+        fs.mkdirSync(TMP, { recursive: true });
+        run("init", "--minimal");
+    });
+    (0, node_test_1.afterEach)(() => {
+        fs.rmSync(TMP, { recursive: true, force: true });
+    });
+    (0, node_test_1.it)("auto-injects Task field into work.md from task.md", () => {
+        // Update task to have a meaningful description
+        run("update-task", "Implement login feature");
+        run("submit-ralph", "[PLAN] My plan");
+        const work = fs.readFileSync(path.join(TMP, ".dual-agent", "work.md"), "utf-8");
+        assert.ok(work.includes("**Task**: Implement login feature"), "work.md should contain Task field");
+    });
+    (0, node_test_1.it)("work.md has no Task field when task.md has no meaningful content", () => {
+        // Default task.md has "Waiting for task assignment" — this IS meaningful content
+        run("submit-ralph", "[PLAN] My plan");
+        const work = fs.readFileSync(path.join(TMP, ".dual-agent", "work.md"), "utf-8");
+        // Should include the default task text
+        assert.ok(work.includes("**Task**:"), "work.md should have Task field even with default task");
+    });
+    (0, node_test_1.it)("uses latest task direction after multiple update-task calls", () => {
+        run("update-task", "First direction");
+        run("update-task", "Second direction");
+        run("update-task", "Final direction");
+        run("submit-ralph", "[PLAN] My plan");
+        const work = fs.readFileSync(path.join(TMP, ".dual-agent", "work.md"), "utf-8");
+        assert.ok(work.includes("**Task**: Final direction"), "work.md should use latest task direction");
+        assert.ok(!work.includes("**Task**: First direction"), "work.md should NOT use first task direction");
+    });
+});

package/dist/test/watcher.test.js

@@ -51,24 +51,34 @@ function newState() {
         seenTurn: "",
         ackedTurn: "",
         failCount: 0,
+        lastAckTime: 0,
         panePromptHits: 0,
         panePaused: false,
         panePauseSize: 0,
     };
 }
 /**
- * Simulate check_and_trigger logic (matches bash watcher v2).
+ * Simulate check_and_trigger logic (matches bash watcher v3).
  * Two-variable approach: seenTurn (observed) vs ackedTurn (delivered).
  * triggerResult: true = trigger succeeded, false = failed.
+ * nowTime: simulated current epoch time for cooldown testing.
  * Returns the action taken.
  */
-function checkAndTrigger(state, currentTurn, triggerResult) {
-    // Detect new turn change
+function checkAndTrigger(state, currentTurn, triggerResult, nowTime = 0) {
+    // 1. Detect new turn change (BEFORE cooldown — new turns are never suppressed)
     if (currentTurn && currentTurn !== state.seenTurn) {
         state.seenTurn = currentTurn;
         state.failCount = 0;
+        state.lastAckTime = 0; // Reset cooldown on new turn
     }
-    // Need to deliver? (seen but not acked)
+    // 2. Cooldown: skip delivery if last ack was < 30s ago
+    if (state.lastAckTime > 0 && nowTime > 0) {
+        const elapsed = nowTime - state.lastAckTime;
+        if (elapsed < 30) {
+            return "cooldown";
+        }
+    }
+    // 3. Need to deliver? (seen but not acked)
     if (state.seenTurn && state.seenTurn !== state.ackedTurn) {
         let mode = "retry";
         if (state.failCount >= 30) {
@@ -80,6 +90,7 @@ function checkAndTrigger(state, currentTurn, triggerResult) {
         if (triggerResult) {
             state.ackedTurn = state.seenTurn;
             state.failCount = 0;
+            state.lastAckTime = nowTime;
             return "ack";
         }
         else {
@@ -89,6 +100,27 @@ function checkAndTrigger(state, currentTurn, triggerResult) {
     }
     return "noop";
 }
+/**
+ * Simulate send_go_to_pane retry-exhaustion logic (v3).
+ * Returns true if message was delivered, false if retries exhausted.
+ */
+function simulateSendGo(agentAlive, interactivePrompt, enterRegistered, // per-attempt: did Enter register?
+maxRetries = 3) {
+    if (!agentAlive)
+        return false;
+    if (interactivePrompt)
+        return false;
+    let attempt = 0;
+    for (let i = 0; i < maxRetries; i++) {
+        if (enterRegistered[i] !== false) {
+            // Enter registered (message submitted)
+            return true;
+        }
+        attempt++;
+    }
+    // All retries exhausted — message never submitted
+    return attempt < maxRetries;
+}
 /**
  * Simulate interactive prompt pause/resume logic.
  * Returns whether send_go should proceed.
@@ -245,3 +277,344 @@ function handleInteractivePrompt(state, promptDetected, outputChanged, currentLo
         assert.strictEqual(s.panePromptHits, 0);
     });
 });
+(0, node_test_1.describe)("Watcher: send_go_to_pane retry exhaustion (RLL-001)", () => {
+    (0, node_test_1.it)("returns false when all retries fail (Enter never registers)", () => {
+        const result = simulateSendGo(true, false, [false, false, false]);
+        assert.strictEqual(result, false);
+    });
+    (0, node_test_1.it)("returns true when first attempt succeeds", () => {
+        const result = simulateSendGo(true, false, [true, false, false]);
+        assert.strictEqual(result, true);
+    });
+    (0, node_test_1.it)("returns true when second attempt succeeds", () => {
+        const result = simulateSendGo(true, false, [false, true, false]);
+        assert.strictEqual(result, true);
+    });
+    (0, node_test_1.it)("returns false when agent is dead", () => {
+        const result = simulateSendGo(false, false, [true, true, true]);
+        assert.strictEqual(result, false);
+    });
+    (0, node_test_1.it)("returns false when interactive prompt detected", () => {
+        const result = simulateSendGo(true, true, [true, true, true]);
+        assert.strictEqual(result, false);
+    });
+});
+(0, node_test_1.describe)("Watcher: cooldown does not block new turns (RLL-001)", () => {
+    (0, node_test_1.it)("cooldown suppresses re-delivery for same turn", () => {
+        const s = newState();
+        // Ack ralph at t=100
+        const action1 = checkAndTrigger(s, "ralph", true, 100);
+        assert.strictEqual(action1, "ack");
+        assert.strictEqual(s.lastAckTime, 100);
+        // Same turn at t=110 (within 30s) → cooldown kicks in before reaching noop
+        const action2 = checkAndTrigger(s, "ralph", true, 110);
+        assert.strictEqual(action2, "cooldown");
+    });
+    (0, node_test_1.it)("new turn within 30s is NOT suppressed by cooldown", () => {
+        const s = newState();
+        // Ack ralph at t=100
+        checkAndTrigger(s, "ralph", true, 100);
+        assert.strictEqual(s.lastAckTime, 100);
+        // New turn (lisa) at t=110 — within 30s of last ack
+        // Turn-change detection resets lastAckTime to 0, so cooldown does not apply
+        const action = checkAndTrigger(s, "lisa", true, 110);
+        assert.strictEqual(action, "ack");
+        assert.strictEqual(s.ackedTurn, "lisa");
+        assert.strictEqual(s.lastAckTime, 110);
+    });
+    (0, node_test_1.it)("cooldown expires after 30s for failed re-delivery", () => {
+        const s = newState();
+        // Ack ralph at t=100
+        checkAndTrigger(s, "ralph", true, 100);
+        // Force unacked state (simulate edge case: ack succeeded but need re-trigger)
+        s.ackedTurn = "";
+        // At t=110 (within 30s) → cooldown
+        const action1 = checkAndTrigger(s, "ralph", true, 110);
+        assert.strictEqual(action1, "cooldown");
+        // At t=135 (past 30s) → delivers
+        const action2 = checkAndTrigger(s, "ralph", true, 135);
+        assert.strictEqual(action2, "ack");
+    });
+});
+function newCheckpointState(rounds) {
+    return { checkpointRounds: rounds, remindTime: 0 };
+}
+/**
+ * Simulate checkpoint check in check_and_trigger (matches bash watcher v3).
+ * ackFilePresent: whether .checkpoint_ack file exists on disk.
+ * nowTime: simulated epoch time.
+ * Returns: "pause" (blocked, reminder emitted), "pause_silent" (blocked, no reminder yet),
+ *          "proceed" (acked or not a checkpoint round), "no_checkpoint" (disabled/not applicable),
+ *          "cleanup" (not at checkpoint round, stale ack file should be removed).
+ */
+function checkCheckpoint(state, round, ackFilePresent, nowTime) {
+    if (state.checkpointRounds <= 0)
+        return "no_checkpoint";
+    if (round <= 1)
+        return "no_checkpoint";
+    const isCheckpointRound = (round - 1) % state.checkpointRounds === 0;
+    if (isCheckpointRound) {
+        // At checkpoint round — file is source of truth (crash-safe)
+        if (ackFilePresent) {
+            // Acked — proceed (keep file until round advances)
+            return "proceed";
+        }
+        // Not acked — pause with periodic 30s reminder
+        if (state.remindTime === 0 || nowTime - state.remindTime >= 30) {
+            state.remindTime = nowTime;
+            return "pause"; // reminder emitted
+        }
+        return "pause_silent"; // blocked but no new reminder
+    }
+    // Not at checkpoint round — clean up stale ack if present
+    if (ackFilePresent)
+        return "cleanup";
+    return "no_checkpoint";
+}
+(0, node_test_1.describe)("Watcher: checkpoint round detection (RLL-003)", () => {
+    (0, node_test_1.it)("pauses at checkpoint round when not acked", () => {
+        const s = newCheckpointState(3);
+        // round=4 → (4-1)%3==0 → pause
+        assert.strictEqual(checkCheckpoint(s, 4, false, 100), "pause");
+    });
+    (0, node_test_1.it)("proceeds at checkpoint round when ack file present", () => {
+        const s = newCheckpointState(3);
+        assert.strictEqual(checkCheckpoint(s, 4, true, 100), "proceed");
+    });
+    (0, node_test_1.it)("does not checkpoint at non-checkpoint rounds", () => {
+        const s = newCheckpointState(3);
+        assert.strictEqual(checkCheckpoint(s, 2, false, 100), "no_checkpoint");
+        assert.strictEqual(checkCheckpoint(s, 3, false, 100), "no_checkpoint");
+        assert.strictEqual(checkCheckpoint(s, 5, false, 100), "no_checkpoint");
+    });
+    (0, node_test_1.it)("does not checkpoint at round 1", () => {
+        const s = newCheckpointState(3);
+        assert.strictEqual(checkCheckpoint(s, 1, false, 100), "no_checkpoint");
+    });
+    (0, node_test_1.it)("does not checkpoint when disabled (0)", () => {
+        const s = newCheckpointState(0);
+        assert.strictEqual(checkCheckpoint(s, 4, false, 100), "no_checkpoint");
+    });
+    (0, node_test_1.it)("checkpoints every N rounds correctly", () => {
+        const s = newCheckpointState(2);
+        // N=2: checkpoints at round 3, 5, 7...
+        assert.strictEqual(checkCheckpoint(s, 3, false, 100), "pause");
+        assert.strictEqual(checkCheckpoint(s, 5, false, 200), "pause");
+        assert.strictEqual(checkCheckpoint(s, 7, false, 300), "pause");
+        // Not at round 2, 4, 6
+        assert.strictEqual(checkCheckpoint(s, 2, false, 100), "no_checkpoint");
+        assert.strictEqual(checkCheckpoint(s, 4, false, 100), "no_checkpoint");
+        assert.strictEqual(checkCheckpoint(s, 6, false, 100), "no_checkpoint");
+    });
+});
+(0, node_test_1.describe)("Watcher: checkpoint reminder cadence (RLL-003)", () => {
+    (0, node_test_1.it)("emits reminder on first pause", () => {
+        const s = newCheckpointState(3);
+        assert.strictEqual(checkCheckpoint(s, 4, false, 100), "pause");
+        assert.strictEqual(s.remindTime, 100);
+    });
+    (0, node_test_1.it)("suppresses reminder within 30s", () => {
+        const s = newCheckpointState(3);
+        checkCheckpoint(s, 4, false, 100); // first reminder at t=100
+        assert.strictEqual(checkCheckpoint(s, 4, false, 110), "pause_silent"); // t=110 < 30s
+        assert.strictEqual(s.remindTime, 100); // unchanged
+    });
+    (0, node_test_1.it)("re-emits reminder after 30s", () => {
+        const s = newCheckpointState(3);
+        checkCheckpoint(s, 4, false, 100); // first at t=100
+        assert.strictEqual(checkCheckpoint(s, 4, false, 130), "pause"); // t=130 >= 30s
+        assert.strictEqual(s.remindTime, 130); // updated
+    });
+    (0, node_test_1.it)("re-emits multiple times at 30s intervals", () => {
+        const s = newCheckpointState(3);
+        assert.strictEqual(checkCheckpoint(s, 4, false, 100), "pause");
+        assert.strictEqual(checkCheckpoint(s, 4, false, 115), "pause_silent");
+        assert.strictEqual(checkCheckpoint(s, 4, false, 130), "pause");
+        assert.strictEqual(checkCheckpoint(s, 4, false, 145), "pause_silent");
+        assert.strictEqual(checkCheckpoint(s, 4, false, 160), "pause");
+    });
+});
+(0, node_test_1.describe)("Watcher: checkpoint ack lifecycle (RLL-003)", () => {
+    (0, node_test_1.it)("ack file persists — repeated checks at same round still proceed", () => {
+        const s = newCheckpointState(3);
+        // File present at round 4 — proceeds every time (file is NOT deleted)
+        assert.strictEqual(checkCheckpoint(s, 4, true, 100), "proceed");
+        assert.strictEqual(checkCheckpoint(s, 4, true, 110), "proceed");
+        assert.strictEqual(checkCheckpoint(s, 4, true, 200), "proceed");
+    });
+    (0, node_test_1.it)("ack file cleaned up when round advances past checkpoint", () => {
+        const s = newCheckpointState(3);
+        // Ack at checkpoint round 4
+        assert.strictEqual(checkCheckpoint(s, 4, true, 100), "proceed");
+        // Round advances to 5 (non-checkpoint) — stale ack triggers cleanup
+        assert.strictEqual(checkCheckpoint(s, 5, true, 200), "cleanup");
+        // After cleanup (file removed), normal no_checkpoint
+        assert.strictEqual(checkCheckpoint(s, 5, false, 200), "no_checkpoint");
+    });
+    (0, node_test_1.it)("next checkpoint round requires fresh ack", () => {
+        const s = newCheckpointState(3);
+        // Ack round 4, then round advances
+        assert.strictEqual(checkCheckpoint(s, 4, true, 100), "proceed");
+        // Next checkpoint: round 7 — no ack file → pauses
+        assert.strictEqual(checkCheckpoint(s, 7, false, 200), "pause");
+    });
+    (0, node_test_1.it)("watcher restart at same checkpoint round still proceeds if ack file exists", () => {
+        // Simulates crash+restart: in-memory state is fresh but file persists
+        const fresh = newCheckpointState(3);
+        // File still on disk from before crash — proceeds immediately
+        assert.strictEqual(checkCheckpoint(fresh, 4, true, 300), "proceed");
+    });
+});
+// ─── RLL-005: Watcher auto-restart simulations ──
+/**
+ * Simulate cleanup guard flag (RLL-005).
+ * Returns number of times cleanup body actually executed.
+ */
+function simulateCleanup(signals) {
+    let cleanupDone = 0;
+    let executions = 0;
+    for (let i = 0; i < signals; i++) {
+        if (cleanupDone)
+            continue;
+        cleanupDone = 1;
+        executions++;
+    }
+    return executions;
+}
+/**
+ * Simulate session-guarded restart loop (RLL-005).
+ * watcherExitCodes: sequence of exit codes from watcher runs.
+ * sessionAliveAfter: for each run index, whether tmux session is alive after exit.
+ * Returns number of watcher launches.
+ */
+function simulateRestartLoop(watcherExitCodes, sessionAliveAfter) {
+    let launches = 0;
+    for (let i = 0; i < watcherExitCodes.length; i++) {
+        // Loop condition: session must be alive to enter
+        if (i > 0 && !sessionAliveAfter[i - 1])
+            break;
+        launches++;
+        // After watcher exits, check session
+        if (!sessionAliveAfter[i])
+            break;
+    }
+    return launches;
+}
+(0, node_test_1.describe)("Watcher: cleanup guard flag (RLL-005)", () => {
+    (0, node_test_1.it)("executes cleanup exactly once on single signal", () => {
+        assert.strictEqual(simulateCleanup(1), 1);
+    });
+    (0, node_test_1.it)("executes cleanup exactly once on double signal", () => {
+        assert.strictEqual(simulateCleanup(2), 1);
+    });
+    (0, node_test_1.it)("executes cleanup exactly once on triple signal", () => {
+        assert.strictEqual(simulateCleanup(3), 1);
+    });
+});
+(0, node_test_1.describe)("Watcher: session-guarded restart loop (RLL-005)", () => {
+    (0, node_test_1.it)("restarts after crash when session is alive", () => {
+        // Watcher crashes (exit 1), session alive → restarts, then exits clean
+        const launches = simulateRestartLoop([1, 0], [true, true]);
+        assert.strictEqual(launches, 2);
+    });
+    (0, node_test_1.it)("does NOT restart when session is gone after exit", () => {
+        // Watcher exits, session gone → no restart
+        const launches = simulateRestartLoop([0, 0], [false, true]);
+        assert.strictEqual(launches, 1);
+    });
+    (0, node_test_1.it)("does NOT restart when session disappears mid-crash", () => {
+        // Watcher crashes (exit 1), session gone → no restart
+        const launches = simulateRestartLoop([1, 0], [false, true]);
+        assert.strictEqual(launches, 1);
+    });
+    (0, node_test_1.it)("handles multiple crashes before stable run", () => {
+        // 3 crashes then stable exit, session alive throughout
+        const launches = simulateRestartLoop([1, 1, 1, 0], [true, true, true, true]);
+        assert.strictEqual(launches, 4);
+    });
+    (0, node_test_1.it)("stops after session teardown mid-sequence", () => {
+        // 2 crashes (session alive), then session gone on 3rd exit
+        const launches = simulateRestartLoop([1, 1, 1], [true, true, false]);
+        assert.strictEqual(launches, 3);
+    });
+});
+/**
+ * Simulate wrapper singleton management with process-identity validation (RLL-005).
+ * processArgs: what `ps -p PID -o args=` returns for the old PID.
+ *   - null = process already dead (PID not running)
+ *   - string = process args (must contain "tmux has-session" to be a valid wrapper)
+ * Returns whether the old PID was killed.
+ */
+function simulateWrapperKill(oldPidExists, processArgs) {
+    if (!oldPidExists)
+        return "no_pid_file";
+    if (processArgs === null)
+        return "skipped_dead";
+    if (!processArgs.includes("tmux has-session"))
+        return "skipped_wrong_process";
+    return "killed";
+}
+(0, node_test_1.describe)("Watcher: wrapper singleton management (RLL-005)", () => {
+    (0, node_test_1.it)("kills old wrapper when process matches", () => {
+        assert.strictEqual(simulateWrapperKill(true, "bash -c while tmux has-session -t rll ..."), "killed");
+    });
+    (0, node_test_1.it)("skips kill when no PID file", () => {
+        assert.strictEqual(simulateWrapperKill(false, null), "no_pid_file");
+    });
+    (0, node_test_1.it)("skips kill when PID is dead (process not running)", () => {
+        assert.strictEqual(simulateWrapperKill(true, null), "skipped_dead");
+    });
+    (0, node_test_1.it)("skips kill when PID was reused by unrelated process", () => {
+        assert.strictEqual(simulateWrapperKill(true, "/usr/bin/python3 my_app.py"), "skipped_wrong_process");
+    });
+    (0, node_test_1.it)("skips kill when PID reused by similar but wrong command", () => {
+        assert.strictEqual(simulateWrapperKill(true, "bash -c some_other_script.sh"), "skipped_wrong_process");
+    });
+});
+// ─── RLL-006: Pane log threshold simulations ─────
+/**
+ * Simulate truncate_log_if_needed logic (RLL-006).
+ * Returns whether truncation would occur, and the computed thresholds.
+ */
+function shouldTruncate(fileSize, maxMb) {
+    if (maxMb < 1)
+        maxMb = 1; // floor guard
+    const maxBytes = maxMb * 1048576;
+    const tailBytes = maxMb * 102400; // ~10% of max
+    return { truncate: fileSize > maxBytes, maxBytes, tailBytes };
+}
+(0, node_test_1.describe)("Watcher: pane log threshold (RLL-006)", () => {
+    (0, node_test_1.it)("default 5MB threshold: no truncation under limit", () => {
+        const r = shouldTruncate(4 * 1048576, 5); // 4MB
+        assert.strictEqual(r.truncate, false);
+        assert.strictEqual(r.maxBytes, 5 * 1048576);
+    });
+    (0, node_test_1.it)("default 5MB threshold: truncates over limit", () => {
+        const r = shouldTruncate(6 * 1048576, 5); // 6MB
+        assert.strictEqual(r.truncate, true);
+        assert.strictEqual(r.tailBytes, 5 * 102400); // 500KB retention
+    });
+    (0, node_test_1.it)("custom 10MB threshold via RL_LOG_MAX_MB", () => {
+        const r = shouldTruncate(8 * 1048576, 10); // 8MB < 10MB
+        assert.strictEqual(r.truncate, false);
+        assert.strictEqual(r.maxBytes, 10 * 1048576);
+    });
+    (0, node_test_1.it)("custom 10MB threshold: truncates over limit", () => {
+        const r = shouldTruncate(11 * 1048576, 10); // 11MB > 10MB
+        assert.strictEqual(r.truncate, true);
+        assert.strictEqual(r.tailBytes, 10 * 102400); // 1000KB retention
+    });
+    (0, node_test_1.it)("tail retention scales with max_mb", () => {
+        assert.strictEqual(shouldTruncate(0, 1).tailBytes, 102400); // 1MB → 100KB
+        assert.strictEqual(shouldTruncate(0, 5).tailBytes, 512000); // 5MB → 500KB
+        assert.strictEqual(shouldTruncate(0, 10).tailBytes, 1024000); // 10MB → 1000KB
+    });
+    (0, node_test_1.it)("floor guard: zero/negative RL_LOG_MAX_MB clamps to 1MB", () => {
+        const r0 = shouldTruncate(2 * 1048576, 0); // 0 → clamped to 1
+        assert.strictEqual(r0.maxBytes, 1048576);
+        assert.strictEqual(r0.truncate, true); // 2MB > 1MB
+        const rNeg = shouldTruncate(500000, -3); // negative → clamped to 1
+        assert.strictEqual(rNeg.maxBytes, 1048576);
+        assert.strictEqual(rNeg.truncate, false); // 500KB < 1MB
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-lisa-loop",
-  "version": "0.3.0",
+  "version": "0.3.8",
   "description": "Turn-based dual-agent collaboration: Ralph codes, Lisa reviews, consensus required.",
   "bin": {
     "ralph-lisa": "dist/cli.js"