ralph-lisa-loop 0.3.9 → 0.3.11

package/dist/commands.js

@@ -38,6 +38,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateSessionName = generateSessionName;
+exports.runGate = runGate;
 exports.cmdInit = cmdInit;
 exports.cmdWhoseTurn = cmdWhoseTurn;
 exports.cmdSubmitRalph = cmdSubmitRalph;
@@ -46,16 +47,24 @@ exports.cmdStatus = cmdStatus;
 exports.cmdRead = cmdRead;
 exports.cmdRecap = cmdRecap;
 exports.cmdStep = cmdStep;
+exports.parseSubtasks = parseSubtasks;
+exports.cmdSubtask = cmdSubtask;
 exports.cmdHistory = cmdHistory;
 exports.cmdArchive = cmdArchive;
 exports.cmdClean = cmdClean;
+exports.cmdStop = cmdStop;
 exports.cmdUpdateTask = cmdUpdateTask;
+exports.cmdForceTurn = cmdForceTurn;
+exports.executeForceTurn = executeForceTurn;
 exports.cmdUninit = cmdUninit;
 exports.cmdInitProject = cmdInitProject;
 exports.cmdStart = cmdStart;
 exports.cmdAuto = cmdAuto;
 exports.cmdPolicy = cmdPolicy;
 exports.cmdLogs = cmdLogs;
+exports.cmdRemote = cmdRemote;
+exports.cmdStateDir = cmdStateDir;
+exports.cmdAddContext = cmdAddContext;
 exports.cmdDoctor = cmdDoctor;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
@@ -128,6 +137,60 @@ function getFilesChanged() {
         return [];
     }
 }
+/**
+ * V4-01: Ralph Auto Gate — run test/lint commands before CODE/FIX submission.
+ * Config via env vars only (config file deferred to future version):
+ *   RL_RALPH_GATE=true          — enable gate (default: false)
+ *   RL_GATE_COMMANDS=cmd1|cmd2  — pipe-separated commands
+ *   RL_GATE_MODE=warn|block     — warn (default) or block on failure
+ * Gate results are NOT written to work.md (prevents Lisa anchoring).
+ */
+function runGate(tag) {
+    if (tag !== "CODE" && tag !== "FIX")
+        return;
+    if (process.env.RL_RALPH_GATE !== "true")
+        return;
+    const commands = (process.env.RL_GATE_COMMANDS || "").split("|").filter(Boolean);
+    if (commands.length === 0)
+        return;
+    const mode = process.env.RL_GATE_MODE === "block" ? "block" : "warn";
+    const failures = [];
+    console.log("Running gate checks...");
+    for (const cmd of commands) {
+        try {
+            (0, node_child_process_1.execSync)(cmd, { stdio: "pipe", timeout: 120000 });
+            console.log(`  PASS  ${cmd}`);
+        }
+        catch (e) {
+            const stderr = e.stderr ? e.stderr.toString().trim().split("\n").slice(-3).join("\n") : "exit code " + e.status;
+            failures.push({ cmd, error: stderr });
+            console.log(`  FAIL  ${cmd}`);
+        }
+    }
+    if (failures.length === 0) {
+        console.log("Gate: all checks passed.");
+        console.log("");
+        return;
+    }
+    console.log("");
+    console.log(line());
+    if (mode === "block") {
+        console.error("Gate BLOCKED submission:");
+        for (const f of failures) {
+            console.error(`  - ${f.cmd}: ${f.error}`);
+        }
+        console.error(line());
+        process.exit(1);
+    }
+    else {
+        console.log("Gate warnings (submission proceeds):");
+        for (const f of failures) {
+            console.log(`  - ${f.cmd}: ${f.error}`);
+        }
+        console.log(line());
+        console.log("");
+    }
+}
 // ─── init ────────────────────────────────────────
 function cmdInit(args) {
     const task = args.join(" ");
@@ -203,11 +266,42 @@ function cmdSubmitRalph(args) {
         console.error(line());
         process.exit(1);
     }
+    // NEEDS_WORK response enforcement (Proposal §3.2)
+    const dir = (0, state_js_1.stateDir)();
+    const reviewContent = (0, state_js_1.readFile)(path.join(dir, "review.md"));
+    const lastLisaTag = extractLastTag(reviewContent);
+    const { getPolicyMode } = require("./policy.js");
+    const nwMode = getPolicyMode();
+    if (nwMode !== "off") {
+        const nwViolations = (0, policy_js_1.checkNeedsWorkResponse)(tag, lastLisaTag);
+        if (nwViolations.length > 0) {
+            if (nwMode === "block") {
+                console.error(line());
+                console.error("Submission BLOCKED — must respond to NEEDS_WORK:");
+                for (const v of nwViolations) {
+                    console.error(`  - ${v.message}`);
+                }
+                console.error(line());
+                process.exit(1);
+            }
+            else {
+                console.log(line());
+                console.log("Warning — submitting after NEEDS_WORK without addressing it:");
+                for (const v of nwViolations) {
+                    console.log(`  - ${v.message}`);
+                }
+                console.log(line());
+                console.log("");
+            }
+            violations.push(...nwViolations);
+        }
+    }
+    // V4-01: Auto gate — run test/lint before CODE/FIX submission
+    runGate(tag);
     const round = (0, state_js_1.getRound)();
     const step = (0, state_js_1.getStep)();
     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"));
@@ -221,8 +315,21 @@ function cmdSubmitRalph(args) {
             filesChangedSection = `**Files Changed**:\n${files.map((f) => `- ${f}`).join("\n")}\n\n`;
         }
     }
+    // Auto-inject context.md so Lisa sees runtime directives (Proposal §3.5)
+    let contextSection = "";
+    const contextPath = path.join(dir, "context.md");
+    if (fs.existsSync(contextPath)) {
+        const ctxContent = (0, state_js_1.readFile)(contextPath);
+        if (ctxContent && !ctxContent.includes("(visible to Lisa).\n\n\n")) {
+            // Only inject if context has actual entries (not just the header)
+            const ctxLines = ctxContent.split("\n").filter((l) => l.startsWith("- ["));
+            if (ctxLines.length > 0) {
+                contextSection = `**Context**: ${ctxLines.join("; ")}\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`);
+    (0, state_js_1.writeFile)(path.join(dir, "work.md"), `# Ralph Work\n\n## [${tag}] Round ${round} | Step: ${step}\n${taskLine}${contextSection}**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)`
@@ -230,6 +337,26 @@ function cmdSubmitRalph(args) {
     (0, state_js_1.appendHistory)("Ralph", historyContent);
     (0, state_js_1.updateLastAction)("Ralph", content);
     (0, state_js_1.setTurn)("lisa");
+    // CONSENSUS actions (Proposal §3.7 + §3.6)
+    if (tag === "CONSENSUS") {
+        // Clean .dual-agent/tests/ on Ralph CONSENSUS (covers single-round closure:
+        // Lisa [PASS] + Ralph [CONSENSUS] — Lisa never submits [CONSENSUS] in this path)
+        const testsDir = path.join(dir, "tests");
+        if (fs.existsSync(testsDir)) {
+            fs.rmSync(testsDir, { recursive: true, force: true });
+            console.log("Cleaned .dual-agent/tests/ (topic closed)");
+        }
+        // Subtask reminder (explicit, not auto-mark)
+        const taskContent = (0, state_js_1.readFile)(path.join(dir, "task.md"));
+        const incomplete = parseSubtasks(taskContent).filter((s) => !s.done);
+        if (incomplete.length > 0) {
+            console.log("");
+            console.log("Hint: If a subtask was completed, run: ralph-lisa subtask done <N>");
+            for (const s of incomplete) {
+                console.log(`  - [ ] #${s.index} ${s.text}`);
+            }
+        }
+    }
     console.log(line());
     if (violations.length > 0) {
         console.log(`Submitted OK (with warnings): [${tag}] ${summary}`);
@@ -315,6 +442,41 @@ function cmdSubmitLisa(args) {
     (0, state_js_1.appendHistory)("Lisa", historyContent);
     (0, state_js_1.updateLastAction)("Lisa", content);
     (0, state_js_1.setTurn)("ralph");
+    // Deadlock counter: track consecutive NEEDS_WORK rounds (Proposal §3.2)
+    const nwCountPath = path.join(dir, "needs_work_count.txt");
+    if (tag === "NEEDS_WORK") {
+        const currentCount = parseInt((0, state_js_1.readFile)(nwCountPath) || "0", 10);
+        const newCount = currentCount + 1;
+        (0, state_js_1.writeFile)(nwCountPath, String(newCount));
+        if (newCount >= 5) {
+            // Trigger deadlock — write flag for watcher to detect
+            const deadlockPath = path.join(dir, "deadlock.txt");
+            (0, state_js_1.writeFile)(deadlockPath, `DEADLOCK at round ${round}: ${newCount} consecutive NEEDS_WORK rounds\nTimestamp: ${ts}\nAction: Watcher will pause. User intervention required.`);
+            console.log("");
+            console.log(line("!", 40));
+            console.log(`DEADLOCK: ${newCount} consecutive NEEDS_WORK rounds.`);
+            console.log("Watcher will pause for user intervention.");
+            console.log("To resolve: ralph-lisa scope-update or ralph-lisa force-turn");
+            console.log(line("!", 40));
+        }
+    }
+    else {
+        // Reset counter on non-NEEDS_WORK review
+        (0, state_js_1.writeFile)(nwCountPath, "0");
+        const deadlockPath = path.join(dir, "deadlock.txt");
+        try {
+            fs.unlinkSync(deadlockPath);
+        }
+        catch { }
+    }
+    // Clean .dual-agent/tests/ on CONSENSUS (Proposal §3.6 — evidence preserved until closure)
+    if (tag === "CONSENSUS") {
+        const testsDir = path.join(dir, "tests");
+        if (fs.existsSync(testsDir)) {
+            fs.rmSync(testsDir, { recursive: true, force: true });
+            console.log("Cleaned .dual-agent/tests/ (topic closed)");
+        }
+    }
     // Increment round
     const nextRound = (parseInt(round, 10) || 0) + 1;
     (0, state_js_1.setRound)(nextRound);
@@ -508,21 +670,32 @@ function extractLastTag(fileContent) {
 // ─── step ────────────────────────────────────────
 function cmdStep(args) {
     (0, state_js_1.checkSession)();
-    // Parse --force flag
+    // Parse flags
     const forceIdx = args.indexOf("--force");
     const force = forceIdx !== -1;
-    const filteredArgs = force
-        ? args.filter((_, i) => i !== forceIdx)
-        : args;
+    const taskIdx = args.indexOf("--task");
+    let taskDesc = "";
+    const skipIndices = new Set();
+    if (forceIdx !== -1)
+        skipIndices.add(forceIdx);
+    if (taskIdx !== -1) {
+        skipIndices.add(taskIdx);
+        if (taskIdx + 1 < args.length) {
+            taskDesc = args[taskIdx + 1];
+            skipIndices.add(taskIdx + 1);
+        }
+    }
+    const filteredArgs = args.filter((_, i) => !skipIndices.has(i));
     const stepName = filteredArgs.join(" ");
     if (!stepName) {
         console.error('Usage: ralph-lisa step "step name"');
+        console.error('       ralph-lisa step "step name" --task "first task"');
         console.error("       ralph-lisa step --force \"step name\"  (skip consensus check)");
         process.exit(1);
     }
+    const dir = (0, state_js_1.stateDir)();
     // Check consensus before allowing step transition
     if (!force) {
-        const dir = (0, state_js_1.stateDir)();
         const workContent = (0, state_js_1.readFile)(path.join(dir, "work.md"));
         const reviewContent = (0, state_js_1.readFile)(path.join(dir, "review.md"));
         const workTag = extractLastTag(workContent);
@@ -539,14 +712,135 @@ function cmdStep(args) {
             console.error('Use --force to skip this check: ralph-lisa step --force "step name"');
             process.exit(1);
         }
+        // Check subtask completion before step transition (Proposal §3.4)
+        const taskContent = (0, state_js_1.readFile)(path.join(dir, "task.md"));
+        const incomplete = parseSubtasks(taskContent).filter((s) => !s.done);
+        if (incomplete.length > 0) {
+            console.error("Error: Incomplete subtasks remain. Cannot proceed to next step.");
+            for (const s of incomplete) {
+                console.error(`  - [ ] #${s.index} ${s.text}`);
+            }
+            console.error("");
+            console.error("Complete all subtasks first, or use --force to skip this check.");
+            process.exit(1);
+        }
     }
     (0, state_js_1.setStep)(stepName);
     (0, state_js_1.setRound)(1);
-    const dir = (0, state_js_1.stateDir)();
+    (0, state_js_1.setTurn)("ralph");
+    // Reset work/review to prevent stale consensus tags from carrying over
+    (0, state_js_1.writeFile)(path.join(dir, "work.md"), "# Ralph Work\n\n(Waiting for Ralph to submit)\n");
+    (0, state_js_1.writeFile)(path.join(dir, "review.md"), "# Lisa Review\n\n(Waiting for Lisa to respond)\n");
     const ts = (0, state_js_1.timestamp)();
+    // Initialize task.md for new step (Proposal §3.3 + §3.4)
+    let taskContent = `# ${stepName}\n\n## Subtasks\n`;
+    if (taskDesc) {
+        taskContent += `- [ ] #1 ${taskDesc}\n`;
+    }
+    taskContent += `\n---\nCreated: ${ts}\n`;
+    (0, state_js_1.writeFile)(path.join(dir, "task.md"), taskContent);
     const entry = `\n---\n\n# Step: ${stepName}\n\nStarted: ${ts}\n\n`;
     fs.appendFileSync(path.join(dir, "history.md"), entry, "utf-8");
     console.log(`Entered step: ${stepName} (round reset to 1)`);
+    if (taskDesc) {
+        console.log(`  Subtask #1: ${taskDesc}`);
+    }
+}
+function parseSubtasks(taskContent) {
+    const subtasks = [];
+    const lines = taskContent.split("\n");
+    for (const line of lines) {
+        const doneMatch = line.match(/^- \[x\] #(\d+)\s+(.*)/i);
+        if (doneMatch) {
+            subtasks.push({ index: parseInt(doneMatch[1], 10), text: doneMatch[2], done: true, line });
+            continue;
+        }
+        const todoMatch = line.match(/^- \[ \] #(\d+)\s+(.*)/);
+        if (todoMatch) {
+            subtasks.push({ index: parseInt(todoMatch[1], 10), text: todoMatch[2], done: false, line });
+        }
+    }
+    return subtasks;
+}
+// ─── subtask ─────────────────────────────────────
+function cmdSubtask(args) {
+    (0, state_js_1.checkSession)();
+    const subcmd = args[0] || "";
+    const rest = args.slice(1);
+    switch (subcmd) {
+        case "add": {
+            const desc = rest.join(" ");
+            if (!desc) {
+                console.error('Usage: ralph-lisa subtask add "task description"');
+                process.exit(1);
+            }
+            const dir = (0, state_js_1.stateDir)();
+            const taskPath = path.join(dir, "task.md");
+            const content = (0, state_js_1.readFile)(taskPath);
+            const existing = parseSubtasks(content);
+            const nextIndex = existing.length > 0 ? Math.max(...existing.map((s) => s.index)) + 1 : 1;
+            const newLine = `- [ ] #${nextIndex} ${desc}`;
+            // Insert before the --- separator if present, otherwise append
+            const lines = content.split("\n");
+            const sepIdx = lines.findIndex((l) => l.startsWith("---"));
+            if (sepIdx !== -1) {
+                lines.splice(sepIdx, 0, newLine);
+            }
+            else {
+                lines.push(newLine);
+            }
+            (0, state_js_1.writeFile)(taskPath, lines.join("\n"));
+            console.log(`Added subtask #${nextIndex}: ${desc}`);
+            break;
+        }
+        case "done": {
+            const num = parseInt(rest[0], 10);
+            if (isNaN(num)) {
+                console.error("Usage: ralph-lisa subtask done <number>");
+                process.exit(1);
+            }
+            const dir = (0, state_js_1.stateDir)();
+            const taskPath = path.join(dir, "task.md");
+            const content = (0, state_js_1.readFile)(taskPath);
+            const subtasks = parseSubtasks(content);
+            const target = subtasks.find((s) => s.index === num);
+            if (!target) {
+                console.error(`Error: Subtask #${num} not found.`);
+                process.exit(1);
+            }
+            if (target.done) {
+                console.log(`Subtask #${num} already completed.`);
+                break;
+            }
+            const updated = content.replace(target.line, target.line.replace("- [ ]", "- [x]"));
+            (0, state_js_1.writeFile)(taskPath, updated);
+            (0, state_js_1.appendHistory)("System", `[SUBTASK] Completed #${num}: ${target.text}`);
+            console.log(`Completed subtask #${num}: ${target.text}`);
+            break;
+        }
+        case "list": {
+            const dir = (0, state_js_1.stateDir)();
+            const content = (0, state_js_1.readFile)(path.join(dir, "task.md"));
+            const subtasks = parseSubtasks(content);
+            if (subtasks.length === 0) {
+                console.log("No subtasks defined.");
+                break;
+            }
+            for (const s of subtasks) {
+                const mark = s.done ? "x" : " ";
+                console.log(`  [${mark}] #${s.index} ${s.text}`);
+            }
+            const done = subtasks.filter((s) => s.done).length;
+            console.log(`\n${done}/${subtasks.length} completed`);
+            break;
+        }
+        default:
+            console.error("Usage: ralph-lisa subtask <add|done|list> [args]");
+            console.error('  subtask add "description"   Add a new subtask');
+            console.error("  subtask done <number>       Mark subtask as complete");
+            console.error("  subtask list                List all subtasks");
+            process.exit(1);
+    }
 }
 // ─── history ─────────────────────────────────────
 function cmdHistory() {
@@ -576,12 +870,214 @@ function cmdClean() {
         console.log("Session cleaned");
     }
 }
-// ─── update-task ─────────────────────────────────
+// ─── stop ─────────────────────────────────────────
+/**
+ * Check if a PID belongs to our watcher/wrapper process by matching
+ * the exact watcher script path in the process args.
+ */
+function isOurProcess(pid, dir) {
+    const watcherScriptPath = path.join(dir, "watcher.sh");
+    try {
+        const args = (0, node_child_process_1.execSync)(`ps -p ${pid} -o args= 2>/dev/null || true`)
+            .toString()
+            .trim();
+        return args !== "" && args.includes(watcherScriptPath);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Send a signal to a PID after verifying it belongs to our project.
+ * Returns true if signal was sent, false if skipped.
+ */
+function signalOurProcess(pid, dir, signal, label) {
+    if (!isOurProcess(pid, dir)) {
+        console.log(`  ${label}: PID ${pid} is not ours (stale PID file), skipping signal`);
+        return false;
+    }
+    try {
+        process.kill(Number(pid), signal);
+        console.log(`  ${label}: sent ${signal} to PID ${pid}`);
+        return true;
+    }
+    catch {
+        console.log(`  ${label}: PID ${pid} already dead`);
+        return false;
+    }
+}
+/**
+ * Clean stale PID files and orphaned state files.
+ */
+function cleanStaleFiles(dir) {
+    const staleFiles = [
+        "watcher.pid",
+        "watcher_wrapper.pid",
+        "deadlock.txt",
+        ".checkpoint_ack",
+        "control.txt",
+        ".turn_changed",
+    ];
+    for (const f of staleFiles) {
+        const fp = path.join(dir, f);
+        try {
+            fs.unlinkSync(fp);
+        }
+        catch {
+            // file didn't exist
+        }
+    }
+}
+function cmdStop(args) {
+    const force = args.includes("--force");
+    const noArchive = args.includes("--no-archive");
+    const projectDir = process.cwd();
+    const dir = (0, state_js_1.stateDir)(projectDir);
+    const sessionName = generateSessionName(projectDir);
+    console.log(line());
+    console.log(force ? "Stopping (force)..." : "Stopping gracefully...");
+    console.log(line());
+    // Read PIDs before any action
+    const wrapperPidFile = path.join(dir, "watcher_wrapper.pid");
+    const watcherPidFile = path.join(dir, "watcher.pid");
+    const wrapperPid = fs.existsSync(wrapperPidFile)
+        ? (0, state_js_1.readFile)(wrapperPidFile).trim()
+        : "";
+    const watcherPid = fs.existsSync(watcherPidFile)
+        ? (0, state_js_1.readFile)(watcherPidFile).trim()
+        : "";
+    if (force) {
+        // -- Force stop: SIGKILL everything --
+        if (wrapperPid) {
+            signalOurProcess(wrapperPid, dir, "SIGKILL", "Wrapper");
+        }
+        if (watcherPid && isOurProcess(watcherPid, dir)) {
+            // Only collect children after confirming ownership to avoid
+            // killing children of an unrelated process (PID reuse safety)
+            let childPids = [];
+            try {
+                childPids = (0, node_child_process_1.execSync)(`pgrep -P ${watcherPid} 2>/dev/null || true`)
+                    .toString()
+                    .trim()
+                    .split("\n")
+                    .filter(Boolean);
+            }
+            catch {
+                // no children
+            }
+            signalOurProcess(watcherPid, dir, "SIGKILL", "Watcher");
+            for (const cpid of childPids) {
+                try {
+                    process.kill(Number(cpid), "SIGKILL");
+                    console.log(`  Accelerator child: killed PID ${cpid}`);
+                }
+                catch {
+                    // already dead
+                }
+            }
+        }
+        else if (watcherPid) {
+            console.log(`  Watcher: PID ${watcherPid} is not ours (stale PID file), skipping signal`);
+        }
+    }
+    else {
+        // -- Graceful stop: SIGTERM + wait --
+        // 1. Stop wrapper first (prevent watcher restart)
+        if (wrapperPid) {
+            signalOurProcess(wrapperPid, dir, "SIGTERM", "Wrapper");
+        }
+        // 2. Stop watcher (triggers cleanup trap)
+        // Signal graceful stop so watcher clears .watcher_state (step39)
+        (0, state_js_1.writeFile)(path.join(dir, ".graceful_stop"), "1");
+        if (watcherPid) {
+            signalOurProcess(watcherPid, dir, "SIGTERM", "Watcher");
+            // Wait for watcher to clean up (up to 5s)
+            const deadline = Date.now() + 5000;
+            while (Date.now() < deadline && fs.existsSync(watcherPidFile)) {
+                (0, node_child_process_1.execSync)("sleep 0.5");
+            }
+            if (fs.existsSync(watcherPidFile)) {
+                console.log("  Watcher did not exit cleanly, forcing...");
+                signalOurProcess(watcherPid, dir, "SIGKILL", "Watcher (force)");
+            }
+        }
+        // 3. Send /exit to agent panes
+        try {
+            (0, node_child_process_1.execSync)(`tmux has-session -t "${sessionName}" 2>/dev/null`);
+            for (const pane of ["0.0", "0.1"]) {
+                try {
+                    (0, node_child_process_1.execSync)(`tmux send-keys -t "${sessionName}:${pane}" "/exit" Enter 2>/dev/null`);
+                    console.log(`  Sent /exit to pane ${pane}`);
+                }
+                catch {
+                    // pane doesn't exist
+                }
+            }
+            // Wait for agents to exit (up to 10s)
+            // Check pane process count rather than session existence,
+            // since session stays alive until we explicitly kill it.
+            const agentDeadline = Date.now() + 10000;
+            while (Date.now() < agentDeadline) {
+                try {
+                    // List pane PIDs — if only shells remain (no claude/codex), agents exited
+                    const paneProcs = (0, node_child_process_1.execSync)(`tmux list-panes -t "${sessionName}" -F "#{pane_pid}" 2>/dev/null || true`).toString().trim();
+                    if (!paneProcs)
+                        break;
+                    // Check if any pane still has agent child processes
+                    const pids = paneProcs.split("\n").filter(Boolean);
+                    let agentRunning = false;
+                    for (const pp of pids) {
+                        const children = (0, node_child_process_1.execSync)(`pgrep -P ${pp} 2>/dev/null || true`).toString().trim();
+                        if (children) {
+                            agentRunning = true;
+                            break;
+                        }
+                    }
+                    if (!agentRunning)
+                        break;
+                    (0, node_child_process_1.execSync)("sleep 1");
+                }
+                catch {
+                    break;
+                }
+            }
+        }
+        catch {
+            // session doesn't exist
+        }
+    }
+    // Kill tmux session if still alive
+    try {
+        (0, node_child_process_1.execSync)(`tmux kill-session -t "${sessionName}" 2>/dev/null`);
+        console.log(`  Killed tmux session: ${sessionName}`);
+    }
+    catch {
+        console.log(`  No tmux session: ${sessionName}`);
+    }
+    // Clean state files
+    cleanStaleFiles(dir);
+    console.log("  Cleaned state files");
+    // Archive
+    if (!noArchive) {
+        try {
+            const archiveName = `stop-${new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19)}`;
+            cmdArchive([archiveName]);
+        }
+        catch {
+            console.log("  Archive skipped (no session data)");
+        }
+    }
+    console.log(line());
+    console.log("Stopped.");
+    console.log(line());
+}
+// ─── scope-update / 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"');
+        console.error('Usage: ralph-lisa scope-update "new scope description"');
+        console.error('       ralph-lisa update-task "new scope description"  (alias)');
         process.exit(1);
     }
     const dir = (0, state_js_1.stateDir)();
@@ -589,8 +1085,66 @@ function cmdUpdateTask(args) {
     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})`);
+    // Log scope change to history (Proposal §3.1)
+    (0, state_js_1.appendHistory)("System", `[SCOPE] Task scope updated: ${newTask}`);
+    (0, state_js_1.updateLastAction)("System", `[SCOPE] ${newTask}`);
+    // Clear deadlock flag — scope change resolves deadlocks (Proposal §3.2)
+    const deadlockPath = path.join(dir, "deadlock.txt");
+    try {
+        fs.unlinkSync(deadlockPath);
+    }
+    catch { }
+    const nwCountPath = path.join(dir, "needs_work_count.txt");
+    (0, state_js_1.writeFile)(nwCountPath, "0");
+    console.log(`Scope updated: ${newTask}`);
+    console.log(`(Appended to ${taskPath}, logged to history.md)`);
+}
+// ─── force-turn ─────────────────────────────────
+function cmdForceTurn(args, confirmed = false) {
+    (0, state_js_1.checkSession)();
+    const agent = args[0];
+    if (agent !== "ralph" && agent !== "lisa") {
+        console.error("Usage: ralph-lisa force-turn <ralph|lisa>");
+        process.exit(1);
+    }
+    const dir = (0, state_js_1.stateDir)();
+    // Block in full-auto mode (watcher running = auto mode)
+    const watcherPid = path.join(dir, "watcher.pid");
+    if (fs.existsSync(watcherPid)) {
+        const pid = (0, state_js_1.readFile)(watcherPid).trim();
+        try {
+            process.kill(Number(pid), 0); // check if alive
+            console.error("Error: force-turn is disabled in auto mode (watcher is running).");
+            console.error("Stop auto mode first, or manually edit turn.txt.");
+            process.exit(1);
+        }
+        catch {
+            // watcher not running, PID stale — allow
+        }
+    }
+    if (!confirmed) {
+        const readline = require("node:readline");
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        rl.question(`Force turn to ${agent}? This skips normal review flow. (y/N) `, (answer) => {
+            rl.close();
+            if (answer.trim().toLowerCase() === "y") {
+                executeForceTurn(agent, dir);
+            }
+            else {
+                console.log("Aborted.");
+            }
+        });
+        return;
+    }
+    executeForceTurn(agent, dir);
+}
+function executeForceTurn(agent, dir) {
+    (0, state_js_1.setTurn)(agent);
+    const ts = (0, state_js_1.timestamp)();
+    (0, state_js_1.appendHistory)("System", `[FORCE] Turn manually assigned to ${agent} by user`);
+    (0, state_js_1.updateLastAction)("System", `[FORCE] Turn assigned to ${agent}`);
+    console.log(`Turn forced to: ${agent}`);
+    console.log("(Logged to history.md)");
 }
 // ─── uninit ──────────────────────────────────────
 const MARKER = "RALPH-LISA-LOOP";
@@ -760,14 +1314,21 @@ function cmdInitProject(args) {
     }
     // Find templates directory (shipped inside npm package)
     const templatesDir = findTemplatesDir();
-    // 1. Append Ralph role to CLAUDE.md
+    // 1. Append/update Ralph role in CLAUDE.md
     const claudeMd = path.join(resolvedDir, "CLAUDE.md");
+    const ralphRole = (0, state_js_1.readFile)(path.join(templatesDir, "roles", "ralph.md"));
     if (fs.existsSync(claudeMd) && (0, state_js_1.readFile)(claudeMd).includes(MARKER)) {
-        console.log("[Claude] Ralph role already in CLAUDE.md, skipping...");
+        // Marker present — we own this content, update to latest template
+        console.log("[Claude] Updating Ralph role in CLAUDE.md...");
+        const existing = fs.readFileSync(claudeMd, "utf-8");
+        const markerTag = `<!-- ${MARKER} -->`;
+        const markerIdx = existing.indexOf(markerTag);
+        const before = markerIdx > 0 ? existing.slice(0, markerIdx) : "";
+        fs.writeFileSync(claudeMd, before + ralphRole, "utf-8");
+        console.log("[Claude] Updated.");
     }
     else {
         console.log("[Claude] Appending Ralph role to CLAUDE.md...");
-        const ralphRole = (0, state_js_1.readFile)(path.join(templatesDir, "roles", "ralph.md"));
         if (fs.existsSync(claudeMd)) {
             fs.appendFileSync(claudeMd, "\n\n", "utf-8");
         }
@@ -776,12 +1337,19 @@ function cmdInitProject(args) {
     }
     // 2. Create/update CODEX.md with Lisa role
     const codexMd = path.join(resolvedDir, "CODEX.md");
+    const lisaRole = (0, state_js_1.readFile)(path.join(templatesDir, "roles", "lisa.md"));
     if (fs.existsSync(codexMd) && (0, state_js_1.readFile)(codexMd).includes(MARKER)) {
-        console.log("[Codex] Lisa role already in CODEX.md, skipping...");
+        // Marker present — we own this content, update to latest template
+        console.log("[Codex] Updating Lisa role in CODEX.md...");
+        const existing = fs.readFileSync(codexMd, "utf-8");
+        const markerTag = `<!-- ${MARKER} -->`;
+        const markerIdx = existing.indexOf(markerTag);
+        const before = markerIdx > 0 ? existing.slice(0, markerIdx) : "";
+        fs.writeFileSync(codexMd, before + lisaRole, "utf-8");
+        console.log("[Codex] Updated.");
     }
     else {
         console.log("[Codex] Creating CODEX.md with Lisa role...");
-        const lisaRole = (0, state_js_1.readFile)(path.join(templatesDir, "roles", "lisa.md"));
         if (fs.existsSync(codexMd)) {
             fs.appendFileSync(codexMd, "\n\n", "utf-8");
         }
@@ -1037,6 +1605,52 @@ function cmdAuto(args) {
         console.log("Mode: FULL AUTO (no permission prompts)");
     console.log("");
     const { execSync } = require("node:child_process");
+    // Check if initialized (full init has CLAUDE.md marker, minimal has .dual-agent/)
+    const claudeMd = path.join(projectDir, "CLAUDE.md");
+    const hasFullInit = fs.existsSync(claudeMd) && (0, state_js_1.readFile)(claudeMd).includes(MARKER);
+    const hasSession = fs.existsSync(path.join(projectDir, state_js_1.STATE_DIR));
+    if (!hasFullInit && !hasSession) {
+        console.error("Error: Not initialized. Run 'ralph-lisa init' first.");
+        process.exit(1);
+    }
+    const sessionName = generateSessionName(projectDir);
+    const dir = (0, state_js_1.stateDir)(projectDir);
+    fs.mkdirSync(dir, { recursive: true });
+    // Stale detection: check for leftover PID files from a previous run.
+    // Runs before prerequisite checks so stale state is always cleaned,
+    // even in environments without tmux/claude/codex.
+    for (const pidFileName of ["watcher.pid", "watcher_wrapper.pid"]) {
+        const pidFile = path.join(dir, pidFileName);
+        if (fs.existsSync(pidFile)) {
+            const pid = (0, state_js_1.readFile)(pidFile).trim();
+            if (pid) {
+                if (isOurProcess(pid, dir)) {
+                    console.error(`Error: ${pidFileName.replace(".pid", "")} is still running (PID ${pid}).`);
+                    console.error("Run 'ralph-lisa stop' first.");
+                    process.exit(1);
+                }
+                else {
+                    // PID is dead or belongs to another process — stale file
+                    console.log(`Warning: Stale ${pidFileName} found (PID ${pid} is not ours). Cleaning up.`);
+                    try {
+                        fs.unlinkSync(pidFile);
+                    }
+                    catch { }
+                }
+            }
+        }
+    }
+    // Clean orphaned state files from stale runs
+    for (const staleFile of ["deadlock.txt", ".checkpoint_ack", "control.txt"]) {
+        const fp = path.join(dir, staleFile);
+        if (fs.existsSync(fp)) {
+            console.log(`Warning: Cleaning stale ${staleFile}`);
+            try {
+                fs.unlinkSync(fp);
+            }
+            catch { }
+        }
+    }
     // Check prerequisites
     try {
         execSync("which tmux", { stdio: "pipe" });
@@ -1081,23 +1695,22 @@ function cmdAuto(args) {
             console.log("");
         }
     }
-    // Check if initialized (full init has CLAUDE.md marker, minimal has .dual-agent/)
-    const claudeMd = path.join(projectDir, "CLAUDE.md");
-    const hasFullInit = fs.existsSync(claudeMd) && (0, state_js_1.readFile)(claudeMd).includes(MARKER);
-    const hasSession = fs.existsSync(path.join(projectDir, state_js_1.STATE_DIR));
-    if (!hasFullInit && !hasSession) {
-        console.error("Error: Not initialized. Run 'ralph-lisa init' first.");
-        process.exit(1);
-    }
     // Initialize task
     if (task) {
         console.log(`Task: ${task}`);
         cmdInit(task.split(" "));
         console.log("");
     }
-    const sessionName = generateSessionName(projectDir);
-    const dir = (0, state_js_1.stateDir)(projectDir);
-    fs.mkdirSync(dir, { recursive: true });
+    // Check if tmux session already exists
+    try {
+        execSync(`tmux has-session -t "${sessionName}" 2>/dev/null`);
+        console.error(`Error: tmux session "${sessionName}" already exists.`);
+        console.error("Run 'ralph-lisa stop' first.");
+        process.exit(1);
+    }
+    catch {
+        // session doesn't exist — good
+    }
     // Archive pane logs from previous runs (for transcript preservation)
     const logsDir = path.join(dir, "logs");
     fs.mkdirSync(logsDir, { recursive: true });
@@ -1122,28 +1735,44 @@ function cmdAuto(args) {
     // Create watcher script
     const watcherScript = path.join(dir, "watcher.sh");
     let watcherContent = `#!/bin/bash
-# Turn watcher v3 - fire-and-forget agent triggering
+# Turn watcher v4 - round-based change detection + persistent state
 # Architecture: polling main loop + optional event acceleration
-# v3: Removed output stability wait + delivery verification (RLL-001)
+# v4: Round-based detection fixes double-flip deadlock (step39)
 
 STATE_DIR=".dual-agent"
 SESSION="${sessionName}"
 SCRIPT_PATH="\$(cd "\$(dirname "\$0")" && pwd)/watcher.sh"
 SEEN_TURN=""
 ACKED_TURN=""
+SEEN_ROUND=""
+ACKED_ROUND=""
 FAIL_COUNT=0
 ACCEL_PID=""
 LAST_ACK_TIME=0
+DELIVERY_PENDING=0
+PENDING_TARGET=""
+CONSENSUS_AT_ROUND=""
+WATCHER_STATE_FILE="\${STATE_DIR}/.watcher_state"
 CHECKPOINT_ROUNDS=\${RL_CHECKPOINT_ROUNDS:-0}
 CHECKPOINT_REMIND_TIME=0
+DEADLOCK_REMIND_TIME=0
 CLEANUP_DONE=0
 
+# Per-turn escalation state (step38: anti-flooding + stuck-agent detection)
+NOTIFY_SENT_AT=0        # epoch when first notification was sent this turn
+REMINDER_LEVEL=0        # 0=initial, 1=REMINDER sent, 2=slash sent, 3=user notified
+CURRENT_TURN_HASH=""    # hash of turn.txt content for change detection
+
 PANE0_LOG="\${STATE_DIR}/pane0.log"
 PANE1_LOG="\${STATE_DIR}/pane1.log"
 PID_FILE="\${STATE_DIR}/watcher.pid"
 
 # Interactive prompt patterns (do NOT send "go" if matched)
-INTERACTIVE_RE='[Pp]assword[: ]|[Pp]assphrase|[Uu]sername[: ]|[Tt]oken[: ]|[Ll]ogin[: ]|\\(y/[Nn]\\)|\\(Y/[Nn]\\)|\\[y/[Nn]\\]|\\[Y/[Nn]\\]|Are you sure|Continue\\?|[Pp]ress [Ee]nter|MFA|2FA|one-time|OTP'
+# Covers: passwords, confirmations, Claude Code permission prompts, Codex approval prompts
+# NOTE: patterns must be specific enough to avoid false positives in normal agent output
+#   BAD:  [Aa]pprove  — matches "I approve this approach" in agent output
+#   GOOD: Allow once  — only matches literal permission button text
+INTERACTIVE_RE='[Pp]assword[: ]|[Pp]assphrase|[Uu]sername[: ]|[Tt]oken[: ]|[Ll]ogin[: ]|\\(y/[Nn]\\)|\\(Y/[Nn]\\)|\\[y/[Nn]\\]|\\[Y/[Nn]\\]|Are you sure|Continue\\?|[Pp]ress [Ee]nter|MFA|2FA|one-time|OTP|Do you want to proceed|[Gg]rant .* access|[Aa]llow .* to run|[Aa]llow .* to edit|Allow once|Allow always|Deny once|Deny always|allow_once|allow_always|reject_once|reject_always|[Yy]es.*[Nn]o.*[Aa]lways'
 
 # Pause state per pane: 0=active, consecutive hit count
 PANE0_PROMPT_HITS=0
@@ -1169,6 +1798,42 @@ fi
 
 echo \$\$ > "\$PID_FILE"
 
+# ─── State persistence (step39) ─────────────────
+
+save_watcher_state() {
+  cat > "\$WATCHER_STATE_FILE" <<WSTATE
+SEEN_TURN=\$SEEN_TURN
+ACKED_TURN=\$ACKED_TURN
+SEEN_ROUND=\$SEEN_ROUND
+ACKED_ROUND=\$ACKED_ROUND
+DELIVERY_PENDING=\$DELIVERY_PENDING
+PENDING_TARGET=\$PENDING_TARGET
+WSTATE
+}
+
+restore_watcher_state() {
+  if [[ -f "\$WATCHER_STATE_FILE" ]]; then
+    echo "[Watcher] Restoring state from \$WATCHER_STATE_FILE"
+    source "\$WATCHER_STATE_FILE"
+    echo "[Watcher] Restored: SEEN_ROUND=\$SEEN_ROUND ACKED_ROUND=\$ACKED_ROUND DELIVERY_PENDING=\$DELIVERY_PENDING"
+    if (( DELIVERY_PENDING )) && [[ -n "\$PENDING_TARGET" ]]; then
+      echo "[Watcher] Replaying pending delivery for \$PENDING_TARGET"
+      if trigger_agent "\$PENDING_TARGET"; then
+        DELIVERY_PENDING=0
+        PENDING_TARGET=""
+        LAST_ACK_TIME=\$(date +%s)
+        save_watcher_state
+        echo "[Watcher] Pending delivery replayed successfully"
+      else
+        echo "[Watcher] Pending delivery replay failed, will retry"
+      fi
+    fi
+  fi
+}
+
+# Clean only transient files on startup (NOT .watcher_state — that's for crash recovery)
+rm -f "\${STATE_DIR}/.checkpoint_ack" "\${STATE_DIR}/deadlock.txt" "\${STATE_DIR}/control.txt" "\${STATE_DIR}/.graceful_stop"
+
 # ─── Cleanup trap ────────────────────────────────
 
 cleanup() {
@@ -1184,6 +1849,15 @@ cleanup() {
   fi
   # Clean up PID and flag files
   rm -f "\$PID_FILE" "\${STATE_DIR}/.turn_changed"
+  # Only remove .watcher_state on graceful stop (step39)
+  # .graceful_stop is written by 'ralph-lisa stop' before SIGTERM
+  # Crash/unexpected exits preserve .watcher_state so wrapper restart can replay pending deliveries
+  if [[ -f "\${STATE_DIR}/.graceful_stop" ]]; then
+    rm -f "\$WATCHER_STATE_FILE" "\${STATE_DIR}/.graceful_stop"
+    echo "[Watcher] Graceful stop — watcher state cleared"
+  else
+    echo "[Watcher] Unexpected exit — watcher state preserved for crash recovery"
+  fi
   # Archive pane logs (not delete) so transcripts are preserved
   local logs_dir="\${STATE_DIR}/logs"
   mkdir -p "\$logs_dir"
@@ -1315,9 +1989,28 @@ send_go_to_pane() {
     return 1
   fi
 
-  # 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)
+  # 3. Wait for agent to be idle (output stable for 5s)
+  #    Prevents injecting text while agent is mid-response
+  local stable_wait=0
+  while (( stable_wait < 30 )); do
+    if check_output_stable "\$log_file" 5; then
+      break
+    fi
+    echo "[Watcher] Waiting for \$agent_name to finish output..."
+    sleep 3
+    stable_wait=\$((stable_wait + 3))
+  done
+  if (( stable_wait >= 30 )); then
+    echo "[Watcher] \$agent_name still producing output after 30s, sending anyway"
+  fi
+
+  # 4. Re-check interactive prompt (may have appeared while waiting)
+  if check_for_interactive_prompt "\$pane"; then
+    echo "[Watcher] Skipping \$agent_name - interactive prompt appeared during wait"
+    return 1
+  fi
+
+  # 5. Send trigger message + Enter with retry
   local detect_marker="\${go_msg:0:20}"
   while (( attempt < max_retries )); do
     tmux send-keys -t "\${SESSION}:\${pane}" -l "\$go_msg" 2>/dev/null || true
@@ -1344,8 +2037,29 @@ send_go_to_pane() {
     return 1
   fi
 
-  echo "[Watcher] OK: Message sent to \$agent_name (fire-and-forget)"
-  return 0
+  # 6. Post-send verification: wait up to 20s for agent to start responding
+  #    Record size AFTER send+retry completes (not before), so we only measure
+  #    the agent's actual response, not the injected text appearing in the pane.
+  local post_send_baseline=0
+  if [[ -f "\$log_file" ]]; then
+    post_send_baseline=\$(wc -c < "\$log_file" 2>/dev/null | tr -d ' ')
+  fi
+  local verify_wait=0
+  while (( verify_wait < 20 )); do
+    sleep 4
+    verify_wait=\$((verify_wait + 4))
+    if [[ -f "\$log_file" ]]; then
+      local cur_size
+      cur_size=\$(wc -c < "\$log_file" 2>/dev/null | tr -d ' ')
+      if (( cur_size > post_send_baseline + 100 )); then
+        echo "[Watcher] OK: \$agent_name responded (output grew +\$((cur_size - post_send_baseline)) bytes)"
+        return 0
+      fi
+    fi
+  done
+
+  echo "[Watcher] WARN: \$agent_name did not produce output after send — may not have received message"
+  return 1
 }
 
 # ─── trigger_agent ───────────────────────────────
@@ -1433,6 +2147,32 @@ trigger_agent() {
   return 1
 }
 
+# ─── consensus detection (step38: suppress notifications after consensus) ────
+
+# Returns 0 if consensus reached (suppress notifications), 1 otherwise
+check_consensus_reached() {
+  local work_file="\${STATE_DIR}/work.md"
+  local review_file="\${STATE_DIR}/review.md"
+
+  if [[ ! -f "\$work_file" ]] || [[ ! -f "\$review_file" ]]; then
+    return 1
+  fi
+
+  # Extract last tag from canonical header: ## [TAG] Round N | Step: ...
+  # Use sed (POSIX-compatible) instead of grep -oP (Perl, not available on macOS)
+  local work_tag review_tag
+  work_tag=\$(grep '^## \\[' "\$work_file" | grep '] Round [0-9]' | sed 's/^## \\[\\([A-Z_]*\\)\\].*/\\1/' | tail -1)
+  review_tag=\$(grep '^## \\[' "\$review_file" | grep '] Round [0-9]' | sed 's/^## \\[\\([A-Z_]*\\)\\].*/\\1/' | tail -1)
+
+  # Consensus combos: CONSENSUS+CONSENSUS, CONSENSUS+PASS, PASS+CONSENSUS
+  if [[ "\$work_tag" == "CONSENSUS" && "\$review_tag" == "CONSENSUS" ]] ||
+     [[ "\$work_tag" == "CONSENSUS" && "\$review_tag" == "PASS" ]] ||
+     [[ "\$work_tag" == "PASS" && "\$review_tag" == "CONSENSUS" ]]; then
+    return 0
+  fi
+  return 1
+}
+
 # ─── check_and_trigger (state machine) ───────────
 
 check_and_trigger() {
@@ -1445,27 +2185,118 @@ check_and_trigger() {
   truncate_log_if_needed "0.0" "\$PANE0_LOG"
   truncate_log_if_needed "0.1" "\$PANE1_LOG"
 
+  # Control file polling (Proposal §3.11): process commands from control.txt
+  if [[ -f "\$STATE_DIR/control.txt" ]]; then
+    local ctrl_cmd
+    ctrl_cmd=\$(cat "\$STATE_DIR/control.txt" 2>/dev/null)
+    rm -f "\$STATE_DIR/control.txt"
+    if [[ -n "\$ctrl_cmd" ]]; then
+      echo "[Watcher] Control command: \$ctrl_cmd"
+      case "\$ctrl_cmd" in
+        pause)
+          echo "[Watcher] PAUSED by control file. Write 'resume' to control.txt to continue."
+          while true; do
+            sleep 2
+            if [[ -f "\$STATE_DIR/control.txt" ]]; then
+              local resume_cmd
+              resume_cmd=\$(cat "\$STATE_DIR/control.txt" 2>/dev/null)
+              rm -f "\$STATE_DIR/control.txt"
+              if [[ "\$resume_cmd" == "resume" ]]; then
+                echo "[Watcher] RESUMED by control file."
+                # Reset escalation state so we restart from L0 (step38)
+                NOTIFY_SENT_AT=0
+                REMINDER_LEVEL=0
+                break
+              else
+                echo "[Watcher] Ignoring '\$resume_cmd' while paused (only 'resume' accepted)"
+              fi
+            fi
+          done
+          ;;
+        resume)
+          echo "[Watcher] Already running — resume ignored."
+          ;;
+        "msg ralph "*)
+          local ralph_msg="\${ctrl_cmd#msg ralph }"
+          echo "[Watcher] Sending message to Ralph: \$ralph_msg"
+          send_go_to_pane "0.0" "Ralph" "\$PANE0_LOG" "\$ralph_msg"
+          ;;
+        "msg lisa "*)
+          local lisa_msg="\${ctrl_cmd#msg lisa }"
+          echo "[Watcher] Sending message to Lisa: \$lisa_msg"
+          send_go_to_pane "0.1" "Lisa" "\$PANE1_LOG" "\$lisa_msg"
+          ;;
+        "scope-update "*)
+          local new_scope="\${ctrl_cmd#scope-update }"
+          echo "[Watcher] Updating scope: \$new_scope"
+          ralph-lisa scope-update "\$new_scope" 2>&1 || true
+          ;;
+        *)
+          echo "[Watcher] Unknown control command: \$ctrl_cmd"
+          ;;
+      esac
+    fi
+  fi
+
+  # Deadlock detection (Proposal §3.2): pause if deadlock.txt exists
+  if [[ -f "\$STATE_DIR/deadlock.txt" ]]; then
+    local now_epoch
+    now_epoch=\$(date +%s)
+    if (( DEADLOCK_REMIND_TIME == 0 )) || (( now_epoch - DEADLOCK_REMIND_TIME >= 30 )); then
+      echo "[Watcher] DEADLOCK detected — pausing. See: \$STATE_DIR/deadlock.txt"
+      echo "[Watcher] To resolve: ralph-lisa scope-update or ralph-lisa force-turn"
+      echo "[Watcher] Or remove: rm \$STATE_DIR/deadlock.txt"
+      DEADLOCK_REMIND_TIME=\$now_epoch
+    fi
+    return
+  fi
+
   if [[ -f "\$STATE_DIR/turn.txt" ]]; then
     CURRENT_TURN=\$(cat "\$STATE_DIR/turn.txt" 2>/dev/null || echo "")
+    CURRENT_ROUND=\$(cat "\$STATE_DIR/round.txt" 2>/dev/null || echo "0")
 
-    # 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"
+    # Detect new round (step39: round-based detection fixes double-flip deadlock)
+    # Round is monotonically increasing, so A→B→A during delivery is always detected.
+    local round_changed=0
+    if [[ -n "\$CURRENT_ROUND" && "\$CURRENT_ROUND" != "\$SEEN_ROUND" ]]; then
+      round_changed=1
+      echo "[Watcher] Round changed: \$SEEN_ROUND -> \$CURRENT_ROUND (turn: \$SEEN_TURN -> \$CURRENT_TURN)"
       SEEN_TURN="\$CURRENT_TURN"
+      SEEN_ROUND="\$CURRENT_ROUND"
       FAIL_COUNT=0
       LAST_ACK_TIME=0
+      # Reset per-turn escalation state (step38)
+      NOTIFY_SENT_AT=0
+      REMINDER_LEVEL=0
+
+      # Mark delivery pending (step39: decouple ack from delivery)
+      DELIVERY_PENDING=1
+      PENDING_TARGET="\$CURRENT_TURN"
+      save_watcher_state
 
       # Write round separator to pane logs for transcript tracking
       local round_ts
       round_ts=\$(date "+%Y-%m-%d %H:%M:%S")
-      local round_marker="\\n\\n===== [Turn -> \$CURRENT_TURN] \$round_ts =====\\n\\n"
+      local round_marker="\\n\\n===== [Round \$CURRENT_ROUND -> \$CURRENT_TURN] \$round_ts =====\\n\\n"
       echo -e "\$round_marker" >> "\$PANE0_LOG" 2>/dev/null || true
       echo -e "\$round_marker" >> "\$PANE1_LOG" 2>/dev/null || true
+    elif [[ -n "\$CURRENT_TURN" && "\$CURRENT_TURN" != "\$SEEN_TURN" ]]; then
+      # Fallback: turn changed without round change (e.g., force-turn)
+      echo "[Watcher] Turn changed (no round change): \$SEEN_TURN -> \$CURRENT_TURN"
+      SEEN_TURN="\$CURRENT_TURN"
+      FAIL_COUNT=0
+      LAST_ACK_TIME=0
+      NOTIFY_SENT_AT=0
+      REMINDER_LEVEL=0
+      DELIVERY_PENDING=1
+      PENDING_TARGET="\$CURRENT_TURN"
+      save_watcher_state
+      round_changed=1
     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
+    # ONLY applies when round has NOT changed — new rounds always deliver immediately (step39)
+    if (( !round_changed && LAST_ACK_TIME > 0 )); then
       local now_epoch
       now_epoch=\$(date +%s)
       local elapsed=\$(( now_epoch - LAST_ACK_TIME ))
@@ -1474,6 +2305,21 @@ check_and_trigger() {
       fi
     fi
 
+    # Consensus suppression (step38): suppress notifications when consensus reached
+    # step39: only suppress if round hasn't changed since consensus was detected
+    if check_consensus_reached; then
+      if [[ "\$CONSENSUS_AT_ROUND" == "" ]]; then
+        CONSENSUS_AT_ROUND="\$CURRENT_ROUND"
+      fi
+      if [[ "\$CURRENT_ROUND" == "\$CONSENSUS_AT_ROUND" ]]; then
+        return
+      fi
+      # Round changed since consensus — clear suppression, deliver normally
+      CONSENSUS_AT_ROUND=""
+    else
+      CONSENSUS_AT_ROUND=""
+    fi
+
     # Checkpoint: pause for user review at configured round intervals
     if (( CHECKPOINT_ROUNDS > 0 )); then
       local round
@@ -1500,8 +2346,8 @@ check_and_trigger() {
       fi
     fi
 
-    # Need to deliver? (seen but not yet acked)
-    if [[ -n "\$SEEN_TURN" && "\$SEEN_TURN" != "\$ACKED_TURN" ]]; then
+    # Need to deliver? (step39: round-based + DELIVERY_PENDING)
+    if (( DELIVERY_PENDING )) || [[ -n "\$SEEN_ROUND" && "\$SEEN_ROUND" != "\$ACKED_ROUND" ]]; then
       # Backoff on repeated failures
       if (( FAIL_COUNT >= 30 )); then
         echo "[Watcher] ALERT: \$FAIL_COUNT consecutive failures. Manual intervention needed."
@@ -1511,29 +2357,90 @@ check_and_trigger() {
         sleep 30
       fi
 
-      if trigger_agent "\$SEEN_TURN"; then
+      local deliver_target="\${PENDING_TARGET:-\$SEEN_TURN}"
+      if trigger_agent "\$deliver_target"; then
         ACKED_TURN="\$SEEN_TURN"
+        ACKED_ROUND="\$SEEN_ROUND"
+        DELIVERY_PENDING=0
+        PENDING_TARGET=""
         FAIL_COUNT=0
         LAST_ACK_TIME=\$(date +%s)
-        echo "[Watcher] Turn acknowledged: \$SEEN_TURN (cooldown 30s)"
+        NOTIFY_SENT_AT=\$(date +%s)
+        REMINDER_LEVEL=0
+        save_watcher_state
+        echo "[Watcher] Round \$SEEN_ROUND acknowledged: \$SEEN_TURN (cooldown 30s)"
       else
         FAIL_COUNT=\$((FAIL_COUNT + 1))
         echo "[Watcher] Trigger failed (fail_count=\$FAIL_COUNT), will retry next cycle"
       fi
+
+    # Escalation (step38): agent was notified but turn hasn't changed
+    elif [[ -n "\$SEEN_TURN" && "\$SEEN_ROUND" == "\$ACKED_ROUND" && "\$NOTIFY_SENT_AT" -gt 0 ]]; then
+      local now_epoch elapsed
+      now_epoch=\$(date +%s)
+      elapsed=\$(( now_epoch - NOTIFY_SENT_AT ))
+
+      # Determine target pane for escalation
+      local target_pane target_name target_log
+      if [[ "\$SEEN_TURN" == "ralph" ]]; then
+        target_pane="0.0"; target_name="Ralph"; target_log="\$PANE0_LOG"
+      else
+        target_pane="0.1"; target_name="Lisa"; target_log="\$PANE1_LOG"
+      fi
+
+      # Check for context limit in pane output (unrecoverable — notify user immediately)
+      local pane_tail
+      pane_tail=\$(tmux capture-pane -t "\${SESSION}:\${target_pane}" -p 2>/dev/null | tail -10)
+      if echo "\$pane_tail" | grep -qiE "context limit|conversation too long|token limit|context window"; then
+        if (( REMINDER_LEVEL < 3 )); then
+          echo "[Watcher] CONTEXT LIMIT detected for \$target_name. Manual intervention required."
+          echo "[Watcher] Restart the agent session to continue."
+          REMINDER_LEVEL=3
+        fi
+
+      # Time-based escalation: each level checked independently by elapsed time.
+      # If L1/L2 delivery fails, time still advances, so L3 is always reachable.
+
+      # Level 3: notify user after 10 minutes — always reachable regardless of L1/L2 success
+      elif (( elapsed >= 600 && REMINDER_LEVEL < 3 )); then
+        echo "[Watcher] STUCK: \$target_name has not responded for \${elapsed}s. Manual intervention needed."
+        REMINDER_LEVEL=3
+
+      # Level 2: slash command after 5 minutes, with prompt guard
+      elif (( elapsed >= 300 && REMINDER_LEVEL < 2 )); then
+        if ! check_for_interactive_prompt "\$target_pane"; then
+          echo "[Watcher] Escalation L2: Sending /check-turn to \$target_name (no response for \${elapsed}s)"
+          if send_go_to_pane "\$target_pane" "\$target_name" "\$target_log" "/check-turn"; then
+            REMINDER_LEVEL=2
+          fi
+        else
+          echo "[Watcher] Escalation L2: Skipped — interactive prompt detected for \$target_name"
+        fi
+
+      # Level 1: REMINDER after 2 minutes
+      elif (( elapsed >= 120 && REMINDER_LEVEL < 1 )); then
+        echo "[Watcher] Escalation L1: Sending REMINDER to \$target_name (no response for \${elapsed}s)"
+        if send_go_to_pane "\$target_pane" "\$target_name" "\$target_log" "REMINDER: It is your turn. Please check turn and continue working."; then
+          REMINDER_LEVEL=1
+        fi
+      fi
     fi
   fi
 }
 
 # ─── Main ────────────────────────────────────────
 
-echo "[Watcher] Starting v3... (Ctrl+C to stop)"
-echo "[Watcher] Monitoring \$STATE_DIR/turn.txt"
+echo "[Watcher] Starting v4... (Ctrl+C to stop)"
+echo "[Watcher] Monitoring \$STATE_DIR/turn.txt + round.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: \$\$"
 
+# Restore state from crash (step39)
+restore_watcher_state
+
 sleep 5
 check_and_trigger
 
@@ -1578,6 +2485,9 @@ done
     execSync(`tmux kill-session -t "${sessionName}" 2>/dev/null || true`);
     // Pane 0: Ralph (left), Pane 1: Lisa (right)
     execSync(`tmux new-session -d -s "${sessionName}" -n "main" -c "${projectDir}"`);
+    // Set authoritative state directory in tmux env (Proposal §3.10)
+    // Both agents resolve to this regardless of their working directory
+    execSync(`tmux set-environment -t "${sessionName}" RL_STATE_DIR "${dir}"`);
     execSync(`tmux split-window -h -t "${sessionName}" -c "${projectDir}"`);
     // Pane 0 = Ralph (left), Pane 1 = Lisa (right)
     execSync(`tmux send-keys -t "${sessionName}:0.0" "echo '=== Ralph (Claude Code) ===' && ${claudeCmd}" Enter`);
@@ -1713,7 +2623,7 @@ function cmdPolicyCheckConsensus() {
 }
 /**
  * Comprehensive check for proceeding to the next step:
- * 1. Both agents have submitted [CONSENSUS]
+ * 1. Consensus reached: [CONSENSUS]+[CONSENSUS], [CONSENSUS]+[PASS], or [PASS]+[CONSENSUS]
  * 2. Ralph's submission passes policy checks
  * 3. Lisa's submission passes policy checks
  */
@@ -1727,12 +2637,13 @@ function cmdPolicyCheckNextStep() {
     const workTag = workContent ? (0, state_js_1.extractTag)(workContent) : "";
     const reviewTag = reviewContent ? (0, state_js_1.extractTag)(reviewContent) : "";
     const allIssues = [];
-    // 1. Consensus check
-    if (workTag !== "CONSENSUS") {
-        allIssues.push(`Ralph's latest is [${workTag || "none"}], not [CONSENSUS].`);
-    }
-    if (reviewTag !== "CONSENSUS") {
-        allIssues.push(`Lisa's latest is [${reviewTag || "none"}], not [CONSENSUS].`);
+    // 1. Consensus check — mirrors cmdStep() logic: accept CONSENSUS+CONSENSUS,
+    // CONSENSUS+PASS, or PASS+CONSENSUS combinations
+    const consensusReached = (workTag === "CONSENSUS" && reviewTag === "CONSENSUS") ||
+        (workTag === "CONSENSUS" && reviewTag === "PASS") ||
+        (workTag === "PASS" && reviewTag === "CONSENSUS");
+    if (!consensusReached) {
+        allIssues.push(`Consensus not reached: Ralph=[${workTag || "none"}], Lisa=[${reviewTag || "none"}]. Need [CONSENSUS]+[CONSENSUS] or [PASS]+[CONSENSUS] combination.`);
     }
     // 2. Policy checks on latest submissions (if content exists)
     if (workContent && workTag) {
@@ -1746,7 +2657,7 @@ function cmdPolicyCheckNextStep() {
             allIssues.push(`Lisa: ${v.message}`);
     }
     if (allIssues.length === 0) {
-        console.log("Ready to proceed: consensus reached and all checks pass.");
+        console.log("Ready to proceed: consensus reached ([CONSENSUS]/[PASS] combination) and all checks pass.");
         return;
     }
     console.error("Not ready to proceed:");
@@ -1848,6 +2759,255 @@ function cmdLogs(args) {
     console.log("  ralph-lisa logs cat           View live pane logs");
     console.log("  ralph-lisa logs cat <file>    View specific log file");
 }
+// ─── remote (ttyd) ──────────────────────────────
+/**
+ * Check if a PID belongs to a ttyd process to avoid killing unrelated processes.
+ */
+function isTtydProcess(pid) {
+    try {
+        // Check if process is alive first
+        process.kill(pid, 0);
+        // Verify it's actually ttyd by checking command line
+        const cmdline = (0, node_child_process_1.execSync)(`ps -p ${pid} -o comm=`, { encoding: "utf-8", stdio: "pipe" }).trim();
+        return cmdline.includes("ttyd");
+    }
+    catch {
+        return false;
+    }
+}
+function cmdRemote(args) {
+    (0, state_js_1.checkSession)();
+    const dir = (0, state_js_1.stateDir)();
+    const pidFile = path.join(dir, "ttyd.pid");
+    // --stop / stop: kill existing ttyd
+    if (args.includes("--stop") || args.includes("stop")) {
+        if (!fs.existsSync(pidFile)) {
+            console.log("No ttyd server running.");
+            return;
+        }
+        const pid = Number((0, state_js_1.readFile)(pidFile));
+        if (isTtydProcess(pid)) {
+            process.kill(pid, "SIGTERM");
+            console.log(`Stopped ttyd (PID ${pid}).`);
+        }
+        else {
+            console.log(`Stale PID ${pid} (not a ttyd process). Cleaning up.`);
+        }
+        try {
+            fs.unlinkSync(pidFile);
+        }
+        catch { }
+        // Clean up the dedicated remote tmux session
+        try {
+            (0, node_child_process_1.execSync)("tmux list-sessions -F '#{session_name}'", { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] })
+                .trim().split("\n")
+                .filter((s) => s.endsWith("-remote"))
+                .forEach((s) => { try {
+                (0, node_child_process_1.execSync)(`tmux kill-session -t ${s}`, { stdio: "pipe" });
+            }
+            catch { } });
+        }
+        catch { }
+        return;
+    }
+    // Check ttyd installed
+    try {
+        (0, node_child_process_1.execSync)("which ttyd", { stdio: "pipe" });
+    }
+    catch {
+        console.error("Error: ttyd not found.");
+        console.error("Install: brew install ttyd (macOS) / apt install ttyd (Linux)");
+        console.error("Or visit: https://github.com/tsl0922/ttyd");
+        process.exit(1);
+    }
+    // Find tmux session: explicit arg > auto-detect > list available
+    const knownFlags = ["--port", "--auth", "--stop"];
+    const reservedWords = ["stop"];
+    const explicitSession = args.find((a) => !a.startsWith("--") && !reservedWords.includes(a) && !knownFlags.includes(args[args.indexOf(a) - 1]));
+    // Resolve session: explicit arg > auto-detect from cwd > single running rll-* session
+    let rllSessions = [];
+    try {
+        rllSessions = (0, node_child_process_1.execSync)("tmux list-sessions -F '#{session_name}'", {
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+        })
+            .trim()
+            .split("\n")
+            .filter((s) => s.startsWith("rll-") && !/-\d+$/.test(s));
+    }
+    catch { }
+    let sessionName;
+    if (explicitSession) {
+        sessionName = explicitSession;
+    }
+    else {
+        // Try auto-detect from project dir
+        const projectRoot = (0, state_js_1.findProjectRoot)() || process.cwd();
+        const detected = generateSessionName(projectRoot);
+        if (rllSessions.includes(detected)) {
+            sessionName = detected;
+        }
+        else if (rllSessions.length === 1) {
+            // Only one rll-* session running — use it
+            sessionName = rllSessions[0];
+        }
+        else {
+            sessionName = detected; // will fail below with helpful hint
+        }
+    }
+    try {
+        (0, node_child_process_1.execSync)(`tmux has-session -t ${sessionName}`, { stdio: "pipe" });
+    }
+    catch {
+        let hint = "";
+        if (rllSessions.length > 0) {
+            hint = `\nAvailable sessions:\n${rllSessions.map((s) => `  ${s}`).join("\n")}\n\nUsage: ralph-lisa remote <session-name>`;
+        }
+        console.error(`Error: tmux session '${sessionName}' not found.${hint}`);
+        if (!hint)
+            console.error("Start a session first: ralph-lisa auto \"task\"");
+        process.exit(1);
+    }
+    // Parse options
+    let port = 7681;
+    let authFlag = "";
+    const portIdx = args.indexOf("--port");
+    if (portIdx !== -1 && args[portIdx + 1]) {
+        port = Number(args[portIdx + 1]);
+        if (isNaN(port) || port < 1 || port > 65535) {
+            console.error("Error: --port must be a valid port number (1-65535).");
+            process.exit(1);
+        }
+    }
+    const authIdx = args.indexOf("--auth");
+    if (authIdx !== -1 && args[authIdx + 1]) {
+        authFlag = `-c ${args[authIdx + 1]}`;
+    }
+    // Kill existing ttyd if running
+    if (fs.existsSync(pidFile)) {
+        const oldPid = Number((0, state_js_1.readFile)(pidFile));
+        if (isTtydProcess(oldPid)) {
+            try {
+                process.kill(oldPid, "SIGTERM");
+            }
+            catch { }
+        }
+        try {
+            fs.unlinkSync(pidFile);
+        }
+        catch { }
+    }
+    // Create a dedicated grouped session for ttyd so browser clients
+    // get their own tmux client (independent input/scroll from Mac).
+    // Re-use the same grouped session across browser refreshes.
+    const remoteSession = `${sessionName}-remote`;
+    try {
+        (0, node_child_process_1.execSync)(`tmux has-session -t ${remoteSession}`, { stdio: "pipe" });
+    }
+    catch {
+        (0, node_child_process_1.execSync)(`tmux new-session -d -s ${remoteSession} -t ${sessionName}`, { stdio: "pipe" });
+    }
+    // Launch ttyd — attach to the dedicated remote session
+    const { spawn } = require("node:child_process");
+    const ttydArgs = ["-p", String(port)];
+    if (authFlag) {
+        const [user, pass] = args[authIdx + 1].split(":");
+        ttydArgs.push("-c", `${user}:${pass}`);
+    }
+    ttydArgs.push("tmux", "attach", "-t", remoteSession);
+    const child = spawn("ttyd", ttydArgs, {
+        detached: true,
+        stdio: "ignore",
+    });
+    child.unref();
+    (0, state_js_1.writeFile)(pidFile, String(child.pid));
+    // Detect LAN IP
+    let lanIp = "localhost";
+    try {
+        const os = require("node:os");
+        const nets = os.networkInterfaces();
+        for (const name of Object.keys(nets)) {
+            for (const net of nets[name]) {
+                if (net.family === "IPv4" && !net.internal) {
+                    lanIp = net.address;
+                    break;
+                }
+            }
+            if (lanIp !== "localhost")
+                break;
+        }
+    }
+    catch { }
+    console.log(line());
+    console.log("ttyd server started");
+    console.log(line());
+    console.log("");
+    console.log(`  Local:   http://localhost:${port}`);
+    console.log(`  Network: http://${lanIp}:${port}`);
+    console.log("");
+    console.log(`  Session: ${sessionName}`);
+    console.log(`  PID:     ${child.pid}`);
+    if (authFlag) {
+        console.log("  Auth:    enabled");
+    }
+    else {
+        console.log("  Auth:    none (use --auth user:pass for LAN access)");
+    }
+    console.log("");
+    console.log("Stop with: ralph-lisa remote --stop");
+    console.log(line());
+}
+// ─── state-dir ───────────────────────────────────
+function cmdStateDir(args) {
+    const setPath = args[0];
+    if (setPath) {
+        // Set mode: write to tmux env if in tmux, otherwise show instructions
+        const resolvedPath = path.resolve(setPath);
+        if (process.env.TMUX) {
+            try {
+                (0, node_child_process_1.execSync)(`tmux set-environment RL_STATE_DIR "${resolvedPath}"`, { stdio: "pipe" });
+                console.log(`State dir set (tmux env): ${resolvedPath}`);
+            }
+            catch {
+                console.error("Error: Failed to set tmux environment variable.");
+                process.exit(1);
+            }
+        }
+        else {
+            console.log(`Not in tmux session. Set manually:`);
+            console.log(`  export RL_STATE_DIR="${resolvedPath}"`);
+        }
+        return;
+    }
+    // Show mode: display all sources + active
+    const tmuxDir = (0, state_js_1.getTmuxStateDir)();
+    const envDir = process.env.RL_STATE_DIR || null;
+    const root = (0, state_js_1.findProjectRoot)();
+    const autoDir = root ? path.join(root, state_js_1.STATE_DIR) : path.join(process.cwd(), state_js_1.STATE_DIR);
+    const resolved = (0, state_js_1.resolveStateDir)();
+    console.log(`tmux env:    ${tmuxDir || "(not set)"}`);
+    console.log(`shell env:   ${envDir || "(not set)"}`);
+    console.log(`auto-detect: ${autoDir}`);
+    console.log(`→ using:     ${resolved.dir}   [${resolved.source}]`);
+}
+// ─── add-context ─────────────────────────────────
+function cmdAddContext(args) {
+    (0, state_js_1.checkSession)();
+    const text = args.join(" ");
+    if (!text) {
+        console.error('Usage: ralph-lisa add-context "user directive or context note"');
+        process.exit(1);
+    }
+    const dir = (0, state_js_1.stateDir)();
+    const contextPath = path.join(dir, "context.md");
+    const ts = (0, state_js_1.timestamp)();
+    if (!fs.existsSync(contextPath)) {
+        (0, state_js_1.writeFile)(contextPath, `# Context Notes\n\nRuntime directives from Ralph (visible to Lisa).\n\n`);
+    }
+    fs.appendFileSync(contextPath, `- [${ts}] ${text}\n`, "utf-8");
+    console.log(`Context added: ${text}`);
+    console.log(`(Written to ${contextPath})`);
+}
 // ─── doctor ──────────────────────────────────────
 function cmdDoctor(args) {
     const strict = args.includes("--strict");
@@ -1892,6 +3052,13 @@ function cmdDoctor(args) {
             required: false,
             installHint: "apt install inotify-tools (Linux)",
         },
+        {
+            name: "ttyd (remote access)",
+            cmd: "which ttyd",
+            versionCmd: "ttyd --version",
+            required: false,
+            installHint: "brew install ttyd (macOS) / apt install ttyd (Linux)",
+        },
     ];
     for (const check of checks) {
         try {