opencode-ralph-rlm 0.1.8 → 0.1.10

package/README.md

@@ -105,6 +105,13 @@ Each session role has a distinct purpose and **fresh context window**:
 | **ralph** | Per-attempt strategist | Fresh | Review failure, update PLAN.md / RLM_INSTRUCTIONS.md, call `ralph_spawn_worker()`. |
 | **worker** | Per-attempt coder | Fresh | `ralph_load_context()` → code → `ralph_verify()` → stop. |
 
+### Roles and responsibilities (quick map)
+
+- **Supervisor (main session):** orchestration and decisions only. Never edits files or runs code; uses `ralph_*` tools to control lifecycle.
+- **Ralph strategist:** updates plan/instructions and delegates to a worker. No direct implementation.
+- **RLM worker:** does the actual coding and verification for this attempt. One pass per session.
+- **Sub-agent:** narrow task helper; updates its own state files under `.opencode/agents/<name>/`.
+
 ### The state machine
 
 ```
@@ -221,7 +228,8 @@ Create `.opencode/ralph.json`. All fields are optional — the plugin runs with
 | `statusVerbosity` | `"normal"` | Supervisor status emission level: `minimal` (warnings/errors), `normal`, or `verbose`. |
 | `maxAttempts` | `20` | Hard stop after this many failed verify attempts. |
 | `heartbeatMinutes` | `15` | Warn if active strategist/worker has no progress for this many minutes. |
-| `verify.command` | — | Shell command to run as an array, e.g. `["bun", "run", "verify"]`. If omitted, verify always returns `unknown`. |
+| `verifyTimeoutMinutes` | `0` | Timeout for verify command in minutes. `0` disables timeouts. |
+| `verify.command` | - | Shell command to run as an array, e.g. `["bun", "run", "verify"]`. If omitted, verify always returns `unknown`. |
 | `verify.cwd` | `"."` | Working directory for the verify command, relative to the repo root. |
 | `gateDestructiveToolsUntilContextLoaded` | `true` | Block `write`, `edit`, `bash`, etc. until `ralph_load_context()` has been called in the current attempt. |
 | `maxRlmSliceLines` | `200` | Maximum lines a single `rlm_slice` call may return. |
@@ -439,6 +447,8 @@ Stop supervision for the current process. This prevents further auto-loop orches
 
 - Use this when you want to pause/stop Ralph from spawning more sessions.
 - Use this after verification passes and the user confirms they are done, or when the user asks to stop the loop.
+- Active child sessions are aborted and any running verify command is stopped.
+- Pass `delete_sessions: true` to delete child sessions after aborting them.
 - Resume later with `ralph_create_supervisor_session(restart_if_done=true)`.
 
 #### `ralph_supervision_status()`

package/dist/ralph-rlm.js

@@ -23417,6 +23417,7 @@ var RalphConfigSchema = exports_Schema.Struct({
   statusVerbosity: exports_Schema.optional(exports_Schema.Union(exports_Schema.Literal("minimal"), exports_Schema.Literal("normal"), exports_Schema.Literal("verbose"))),
   maxAttempts: exports_Schema.optional(exports_Schema.Number),
   heartbeatMinutes: exports_Schema.optional(exports_Schema.Number),
+  verifyTimeoutMinutes: exports_Schema.optional(exports_Schema.Number),
   verify: exports_Schema.optional(VerifyConfigSchema),
   gateDestructiveToolsUntilContextLoaded: exports_Schema.optional(exports_Schema.Boolean),
   maxRlmSliceLines: exports_Schema.optional(exports_Schema.Number),
@@ -23455,6 +23456,7 @@ var CONFIG_DEFAULTS = {
   statusVerbosity: "normal",
   maxAttempts: 20,
   heartbeatMinutes: 15,
+  verifyTimeoutMinutes: 0,
   gateDestructiveToolsUntilContextLoaded: true,
   maxRlmSliceLines: 200,
   requireGrepBeforeLargeSlice: true,
@@ -23480,6 +23482,7 @@ function resolveConfig(raw) {
     statusVerbosity: raw.statusVerbosity ?? CONFIG_DEFAULTS.statusVerbosity,
     maxAttempts: toBoundedInt(raw.maxAttempts, CONFIG_DEFAULTS.maxAttempts, 1, 500),
     heartbeatMinutes: toBoundedInt(raw.heartbeatMinutes, CONFIG_DEFAULTS.heartbeatMinutes, 1, 240),
+    verifyTimeoutMinutes: toBoundedInt(raw.verifyTimeoutMinutes, CONFIG_DEFAULTS.verifyTimeoutMinutes, 0, 240),
     ...verify !== undefined ? { verify } : {},
     gateDestructiveToolsUntilContextLoaded: raw.gateDestructiveToolsUntilContextLoaded ?? CONFIG_DEFAULTS.gateDestructiveToolsUntilContextLoaded,
     maxRlmSliceLines,
@@ -23502,6 +23505,8 @@ var DEFAULT_TEMPLATES = {
     "RALPH SUPERVISOR:",
     "- You are the Ralph supervisor. You orchestrate RLM worker sessions; you do NOT write code yourself.",
     "- When the user gives you a goal, describe the task briefly and stop \u2014 the plugin will spawn an RLM worker automatically.",
+    "- You are NOT the Ralph strategist and NOT the RLM worker. Those are separate sessions.",
+    "  Supervisor = orchestration + decisions; Ralph strategist = planning + delegation; RLM worker = implementation.",
     "- Workers are spawned per-attempt with a fresh context window. They load state from protocol files.",
     "- Protocol files (PLAN.md, RLM_INSTRUCTIONS.md, etc.) persist across all attempts \u2014 edit them to guide workers.",
     "- After each worker attempt the plugin runs verify and either finishes or spawns the next worker.",
@@ -23511,7 +23516,13 @@ var DEFAULT_TEMPLATES = {
     "  ralph_create_supervisor_session() to bind/start explicitly, ralph_pause_supervision()/ralph_resume_supervision() to control execution, and ralph_end_supervision() to stop.",
     "- End supervision when verification has passed and the user confirms they are done, or when the user explicitly asks to stop the loop.",
     "- Optional reviewer flow: worker marks readiness with ralph_request_review(); supervisor runs ralph_run_reviewer().",
-    "- Monitor progress in SUPERVISOR_LOG.md, CONVERSATION.md, or via toast notifications."
+    "- Monitor progress in SUPERVISOR_LOG.md, CONVERSATION.md, or via toast notifications.",
+    "",
+    "Big picture:",
+    "- The supervisor owns the lifecycle only. It never edits files or runs rlm_grep/rlm_slice.",
+    "- All implementation happens in RLM worker sessions spawned per attempt.",
+    "- Strategy changes must be written to PLAN.md / RLM_INSTRUCTIONS.md so each new worker sees them.",
+    "- Stop the loop explicitly with ralph_end_supervision() when the user is done or verification passed."
   ].join(`
 `),
   systemPromptAppend: "",
@@ -23562,7 +23573,11 @@ var DEFAULT_TEMPLATES = {
     "- Keep CURRENT_STATE.md updated as you work (objective, hypothesis, actions, evidence, result).",
     "- Write durable learnings to NOTES_AND_LEARNINGS.md (append-only).",
     '- When you have completed the goal, write your final answer under a "{{doneHeading}}" heading in CURRENT_STATE.md.',
-    "- Then output the exact phrase on its own line: {{doneSentinel}}"
+    "- Then output the exact phrase on its own line: {{doneSentinel}}",
+    "",
+    "Role boundaries:",
+    "- You are a child of the RLM worker. Do NOT act as the supervisor or Ralph strategist.",
+    "- Do NOT write outside your stateDir unless explicitly instructed by your parent session."
   ].join(`
 `),
   subagentDoneSentinel: "SUB_AGENT_DONE",
@@ -23580,6 +23595,7 @@ var DEFAULT_TEMPLATES = {
     "- Write durable learnings to NOTES_AND_LEARNINGS.md (append-only).",
     "- Report meaningful progress with ralph_report() so the supervisor can track attempts in SUPERVISOR_LOG.md and CONVERSATION.md.",
     "- Modify these instructions via ralph_update_rlm_instructions(patch, reason).",
+    "- You are NOT the supervisor and NOT the Ralph strategist. You implement code for this attempt only.",
     "",
     "## Skills / MCP Registry (editable)",
     "- (list tools, MCP servers, playbooks)",
@@ -23621,11 +23637,18 @@ var DEFAULT_TEMPLATES = {
     "- CONTEXT_FOR_RLM.md is large. Access via rlm_grep + rlm_slice only. Never full-dump it.",
     "- CURRENT_STATE.md is scratch for this attempt. Write your progress here.",
     "- NOTES_AND_LEARNINGS.md is append-only. Write durable insights here.",
+    "- You are the IMPLEMENTER for this attempt. Do the coding work; do NOT supervise or strategize beyond this attempt.",
     "- Send status updates with ralph_report() at start, after major milestones, and before ralph_verify().",
     "- Optionally call ralph_set_status(running|blocked|done|error, note) for explicit state handoff.",
     "- When satisfied with your changes, call ralph_verify() once, then STOP.",
     "  The Ralph supervisor evaluates the result and will spawn the next attempt if needed.",
-    "- Do NOT re-prompt yourself. One pass per session."
+    "- Do NOT re-prompt yourself. One pass per session.",
+    "",
+    "Lifecycle + communication:",
+    "- Start: ralph_load_context() \u2192 plan \u2192 ralph_report().",
+    "- Work: edit files, keep CURRENT_STATE.md updated.",
+    "- Finish: ralph_set_status('done', ...) \u2192 ralph_report() \u2192 ralph_verify() \u2192 STOP.",
+    "- Questions: use ralph_ask() only if you are blocked on a human decision."
   ].join(`
 `),
   workerPrompt: [
@@ -23635,22 +23658,34 @@ var DEFAULT_TEMPLATES = {
     "1. Call ralph_load_context() FIRST. It contains PLAN.md, RLM_INSTRUCTIONS.md, previous state, and all context.",
     "2. Read AGENT_CONTEXT_FOR_NEXT_RALPH.md for the verdict and next step from the previous attempt.",
     "3. Follow RLM_INSTRUCTIONS.md for project-specific playbooks.",
+    "3.5 You are the IMPLEMENTER for this attempt (not the supervisor or strategist).",
     "4. Immediately call ralph_report() with your plan for this attempt.",
     "5. Optionally call ralph_set_status('running', '...') once you've scoped the approach.",
     "6. Do the work. Write progress to CURRENT_STATE.md throughout and call ralph_report() at meaningful checkpoints.",
     "7. When done, call ralph_set_status('done', '...') and ralph_report() with outcome + remaining risks, then call ralph_verify().",
     "8. STOP \u2014 do not send further messages.",
-    "   The Ralph supervisor will handle the result and spawn attempt {{nextAttempt}} if needed."
+    "   The Ralph supervisor will handle the result and spawn attempt {{nextAttempt}} if needed.",
+    "",
+    "Tool meaning:",
+    "- ralph_report = visible progress in SUPERVISOR_LOG.md + CONVERSATION.md",
+    "- ralph_verify = run verify.command and end your attempt",
+    "- rlm_grep/rlm_slice = safe access to large reference files",
+    "- ralph_ask = ask the supervisor a blocking decision; you will wait for ralph_respond"
   ].join(`
 `),
   ralphSessionSystemPrompt: [
     "RALPH STRATEGIST SESSION:",
     "- You are Ralph, the strategic supervisor for one attempt.",
     "- You review failures, update plans and instructions, then delegate coding to an RLM worker.",
-    "- You do NOT write code yourself.",
+    "- You do NOT write code yourself; you are not the RLM worker.",
     "- After reviewing state and optionally updating PLAN.md / RLM_INSTRUCTIONS.md,",
     "  call ralph_spawn_worker() to hand off to the RLM worker for this attempt.",
-    "- Then STOP. The plugin verifies independently and will spawn the next Ralph session if needed."
+    "- Then STOP. The plugin verifies independently and will spawn the next Ralph session if needed.",
+    "",
+    "Role boundaries:",
+    "- Do not edit source code or run tests directly.",
+    "- Do update PLAN.md / RLM_INSTRUCTIONS.md if strategy needs adjustment.",
+    "- Your output should be: strategy summary + worker spawned."
   ].join(`
 `),
   ralphSessionPrompt: [
@@ -23660,6 +23695,7 @@ var DEFAULT_TEMPLATES = {
     "1. Call ralph_load_context() to review all protocol files.",
     "2. Read AGENT_CONTEXT_FOR_NEXT_RALPH.md \u2014 what failed last time and why.",
     "3. Review PLAN.md \u2014 is the goal still correct? Any constraints to add?",
+    "3.5 You are the STRATEGIST for this attempt (not the supervisor or implementer).",
     "4. Optionally call ralph_update_plan() or ralph_update_rlm_instructions() to improve",
     "   guidance for the next worker based on patterns in the failures.",
     "5. Optionally call ralph_set_status('running', 'strategy finalized').",
@@ -23667,7 +23703,12 @@ var DEFAULT_TEMPLATES = {
     "7. Call ralph_spawn_worker() to delegate the coding work to a fresh RLM worker.",
     "8. STOP \u2014 the plugin handles verification and will spawn attempt {{nextAttempt}} if needed.",
     "",
-    "You do not write code. Your value is strategic context adjustment between attempts."
+    "You do not write code. Your value is strategic context adjustment between attempts.",
+    "",
+    "Tool meaning:",
+    "- ralph_update_plan / ralph_update_rlm_instructions = durable strategy changes",
+    "- ralph_spawn_worker = handoff to implementation session",
+    "- ralph_report = visible summary for the supervisor"
   ].join(`
 `)
 };
@@ -23762,7 +23803,26 @@ var writePendingInput = async (root, data) => {
   await NodeFs.writeFile(p, JSON.stringify(data, null, 2), "utf8");
 };
 var sleep5 = (ms) => new Promise((r) => setTimeout(r, ms));
-async function runCommand(command, cwd) {
+var activeCommands = new Set;
+var stopCommand = (cmd, reason) => {
+  if (cmd.child.killed)
+    return;
+  cmd.timedOut = cmd.timedOut || reason === "timeout";
+  try {
+    cmd.child.kill();
+  } catch {}
+  cmd.killTimer = setTimeout(() => {
+    try {
+      cmd.child.kill("SIGKILL");
+    } catch {}
+  }, 2000);
+};
+var stopAllCommands = (reason) => {
+  for (const cmd of activeCommands) {
+    stopCommand(cmd, reason);
+  }
+};
+async function runCommand(command, cwd, options) {
   return await new Promise((resolve) => {
     const child = spawn(command[0] ?? "", command.slice(1), {
       cwd,
@@ -23772,6 +23832,18 @@ async function runCommand(command, cwd) {
     });
     let stdout = "";
     let stderr = "";
+    const entry = {
+      child,
+      label: options?.label ?? command.join(" "),
+      startedAt: Date.now(),
+      timedOut: false
+    };
+    activeCommands.add(entry);
+    if (options?.timeoutMs && options.timeoutMs > 0) {
+      entry.timeoutTimer = setTimeout(() => {
+        stopCommand(entry, "timeout");
+      }, options.timeoutMs);
+    }
     child.stdout?.on("data", (chunk3) => {
       stdout += String(chunk3);
     });
@@ -23779,11 +23851,23 @@ async function runCommand(command, cwd) {
       stderr += String(chunk3);
     });
     child.on("error", (err) => {
+      if (entry.timeoutTimer)
+        clearTimeout(entry.timeoutTimer);
+      if (entry.killTimer)
+        clearTimeout(entry.killTimer);
+      activeCommands.delete(entry);
       resolve({ ok: false, code: null, stdout, stderr: `${stderr}
 ${String(err)}`.trim() });
     });
     child.on("close", (code) => {
-      resolve({ ok: code === 0, code, stdout, stderr });
+      if (entry.timeoutTimer)
+        clearTimeout(entry.timeoutTimer);
+      if (entry.killTimer)
+        clearTimeout(entry.killTimer);
+      activeCommands.delete(entry);
+      const timeoutNote = entry.timedOut ? `
+[ralph] command timed out` : "";
+      resolve({ ok: code === 0 && !entry.timedOut, code, stdout, stderr: `${stderr}${timeoutNote}`.trim() });
     });
   });
 }
@@ -24295,9 +24379,11 @@ var RalphRLM = async ({ client, $, worktree }) => {
     }
     const verifyCmd = cfg.verify.command;
     const cwd = NodePath.join(root, cfg.verify.cwd ?? ".");
+    const timeoutMs = cfg.verifyTimeoutMinutes > 0 ? cfg.verifyTimeoutMinutes * 60000 : null;
     return yield* exports_Effect.tryPromise({
       try: async () => {
-        const result = await runCommand(verifyCmd, cwd);
+        const options = timeoutMs ? { timeoutMs, label: "verify" } : { label: "verify" };
+        const result = await runCommand(verifyCmd, cwd, options);
         if (result.ok) {
           return JSON.stringify({ verdict: "pass", output: result.stdout }, null, 2);
         }
@@ -25024,6 +25110,7 @@ No pending questions found.`));
     description: "Stop Ralph supervision for this process. Prevents further auto-loop orchestration until restarted.",
     args: {
       reason: tool.schema.string().optional().describe("Optional reason for ending supervision."),
+      delete_sessions: tool.schema.boolean().optional().describe("Also delete child sessions after aborting them (default false)."),
       clear_binding: tool.schema.boolean().optional().describe("Clear supervisor session binding after stop (default false).")
     },
     async execute(args2, ctx) {
@@ -25031,6 +25118,15 @@ No pending questions found.`));
       const reason = args2.reason?.trim();
       supervisor.done = true;
       supervisor.paused = true;
+      const sessionsToAbort = Array.from(sessionMap.keys());
+      for (const id of sessionsToAbort) {
+        await client.session.abort({ path: { id } }).catch(() => {});
+        if (args2.delete_sessions) {
+          await client.session.delete({ path: { id } }).catch(() => {});
+        }
+      }
+      stopAllCommands("supervision-ended");
+      sessionMap.clear();
       supervisor.currentRalphSessionId = undefined;
       supervisor.currentWorkerSessionId = undefined;
       supervisor.activeReviewerName = undefined;
@@ -25451,6 +25547,8 @@ Set a new goal and run again.
     }
   });
   const emitHeartbeatWarnings = async () => {
+    if (supervisor.done || supervisor.paused)
+      return;
     const cfg = await run(getConfig());
     const thresholdMs = cfg.heartbeatMinutes * 60000;
     const now2 = Date.now();
@@ -25473,6 +25571,30 @@ Set a new goal and run again.
     await maybeWarn(supervisor.currentRalphSessionId, "Strategist");
     await maybeWarn(supervisor.currentWorkerSessionId, "Worker");
   };
+  const clearSessionTracking = async (sessionId, reason) => {
+    const st = sessionMap.get(sessionId);
+    sessionMap.delete(sessionId);
+    let didUpdate = false;
+    if (supervisor.currentRalphSessionId === sessionId) {
+      supervisor.currentRalphSessionId = undefined;
+      didUpdate = true;
+    }
+    if (supervisor.currentWorkerSessionId === sessionId) {
+      supervisor.currentWorkerSessionId = undefined;
+      didUpdate = true;
+    }
+    if (supervisor.activeReviewerSessionId === sessionId) {
+      supervisor.activeReviewerSessionId = undefined;
+      supervisor.activeReviewerName = undefined;
+      supervisor.activeReviewerAttempt = undefined;
+      supervisor.activeReviewerOutputPath = undefined;
+      didUpdate = true;
+      await persistReviewerState();
+    }
+    if (didUpdate && st) {
+      await notifySupervisor(`${st.role}/attempt-${st.attempt}`, `${st.role} session ended (${reason}).`, "info", true, sessionId);
+    }
+  };
   const runAndParseVerify = async () => {
     const raw = await run(runVerify(worktree));
     try {
@@ -25740,7 +25862,13 @@ ${templates.systemPromptAppend}` : base;
           getSession(sessionID);
       }
       if (event?.type === "session.status" && sessionID) {
+        if (supervisor.done || supervisor.paused)
+          return;
         const state = sessionMap.get(sessionID);
+        if (state?.role === "worker" && supervisor.currentWorkerSessionId !== sessionID)
+          return;
+        if (state?.role === "ralph" && supervisor.currentRalphSessionId !== sessionID)
+          return;
         if (state) {
           mutateSession(sessionID, (s) => {
             s.lastProgressAt = Date.now();
@@ -25752,6 +25880,8 @@ ${templates.systemPromptAppend}` : base;
         }
       }
       if (event?.type === "session.idle" && sessionID) {
+        if (supervisor.done || supervisor.paused)
+          return;
         await emitHeartbeatWarnings().catch((err) => {
           appLog("error", "heartbeat warning error", { error: String(err) });
         });
@@ -25769,6 +25899,9 @@ ${templates.systemPromptAppend}` : base;
           });
         }
       }
+      if (sessionID && (event?.type === "session.closed" || event?.type === "session.ended" || event?.type === "session.deleted")) {
+        await clearSessionTracking(sessionID, event.type);
+      }
     }
   };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-ralph-rlm",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "OpenCode plugin: Ralph outer loop + RLM inner loop. Iterative AI development with file-first discipline and sub-agent support.",
   "type": "module",
   "main": "./dist/ralph-rlm.js",