opencode-ralph-rlm 0.1.12 → 0.1.13

package/README.md

@@ -228,6 +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. |
+| `strategistHandoffMinutes` | `5` | Warn/retry if the strategist does not spawn a worker within this many minutes. |
+| `strategistHandoffMaxRetries` | `2` | Max retries to respawn strategist after a missed handoff. |
 | `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. |

package/dist/ralph-rlm.js

@@ -23417,6 +23417,8 @@ 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),
+  strategistHandoffMinutes: exports_Schema.optional(exports_Schema.Number),
+  strategistHandoffMaxRetries: 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),
@@ -23456,6 +23458,8 @@ var CONFIG_DEFAULTS = {
   statusVerbosity: "normal",
   maxAttempts: 20,
   heartbeatMinutes: 15,
+  strategistHandoffMinutes: 5,
+  strategistHandoffMaxRetries: 2,
   verifyTimeoutMinutes: 0,
   gateDestructiveToolsUntilContextLoaded: true,
   maxRlmSliceLines: 200,
@@ -23482,6 +23486,8 @@ 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),
+    strategistHandoffMinutes: toBoundedInt(raw.strategistHandoffMinutes, CONFIG_DEFAULTS.strategistHandoffMinutes, 1, 60),
+    strategistHandoffMaxRetries: toBoundedInt(raw.strategistHandoffMaxRetries, CONFIG_DEFAULTS.strategistHandoffMaxRetries, 0, 10),
     verifyTimeoutMinutes: toBoundedInt(raw.verifyTimeoutMinutes, CONFIG_DEFAULTS.verifyTimeoutMinutes, 0, 240),
     ...verify !== undefined ? { verify } : {},
     gateDestructiveToolsUntilContextLoaded: raw.gateDestructiveToolsUntilContextLoaded ?? CONFIG_DEFAULTS.gateDestructiveToolsUntilContextLoaded,
@@ -23514,6 +23520,7 @@ var DEFAULT_TEMPLATES = {
     "  When you receive one, call ralph_respond(id, answer) to unblock the session.",
     "- Use ralph_doctor() to check setup, ralph_bootstrap_plan() to generate PLAN/TODOS,",
     "  ralph_create_supervisor_session() to bind/start explicitly, ralph_pause_supervision()/ralph_resume_supervision() to control execution, and ralph_end_supervision() to stop.",
+    "- Only call loop-control tools (spawn, pause, resume, end) after the supervisor session is bound via ralph_create_supervisor_session().",
     "- 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.",
@@ -23700,6 +23707,7 @@ var DEFAULT_TEMPLATES = {
     "- 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.",
+    "- You MUST call ralph_spawn_worker() exactly once per attempt.",
     "- Then STOP. The plugin verifies independently and will spawn the next Ralph session if needed.",
     "",
     "Role boundaries:",
@@ -23720,7 +23728,7 @@ var DEFAULT_TEMPLATES = {
     "   guidance for the next worker based on patterns in the failures.",
     "5. Optionally call ralph_set_status('running', 'strategy finalized').",
     "6. Call ralph_report() summarizing strategy changes for this attempt.",
-    "7. Call ralph_spawn_worker() to delegate the coding work to a fresh RLM worker.",
+    "7. Call ralph_spawn_worker() to delegate the coding work to a fresh RLM worker (required).",
     "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.",
@@ -23728,7 +23736,10 @@ var DEFAULT_TEMPLATES = {
     "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"
+    "- ralph_report = visible summary for the supervisor",
+    "",
+    "Example flow:",
+    '- ralph_load_context() \u2192 ralph_report("Strategy: update PLAN.md with constraint X") \u2192 ralph_spawn_worker() \u2192 STOP'
   ].join(`
 `)
 };
@@ -25733,6 +25744,8 @@ ${interpolate(templates.continuePrompt, { attempt: String(attemptN), verdict })}
     mutateSession(sessionID, (s) => {
       s.workerSpawned = true;
     });
+    supervisor.ralphHandoffRetries = 0;
+    supervisor.ralphHandoffAttempt = st.attempt;
     await notifySupervisor(`ralph/attempt-${st.attempt}`, `Delegated coding to worker session ${workerId}.`, "info", true, sessionID);
     return JSON.stringify({ ok: true, workerSessionId: workerId, attempt: st.attempt }, null, 2);
   };
@@ -25741,6 +25754,10 @@ ${interpolate(templates.continuePrompt, { attempt: String(attemptN), verdict })}
       body: { title: `ralph-strategist-attempt-${attempt}` }
     });
     const ralphId = result.data?.id ?? `ralph-${Date.now()}`;
+    if (supervisor.ralphHandoffAttempt !== attempt) {
+      supervisor.ralphHandoffAttempt = attempt;
+      supervisor.ralphHandoffRetries = 0;
+    }
     supervisor.currentRalphSessionId = ralphId;
     sessionMap.set(ralphId, freshSession("ralph", attempt));
     mutateSession(ralphId, (s) => {
@@ -25762,7 +25779,7 @@ ${interpolate(templates.continuePrompt, { attempt: String(attemptN), verdict })}
       clearTimeout(supervisor.ralphHandoffTimer);
     }
     const cfg = await run(getConfig());
-    const timeoutMs = Math.max(cfg.heartbeatMinutes, 1) * 60000;
+    const timeoutMs = Math.max(cfg.strategistHandoffMinutes, 1) * 60000;
     supervisor.ralphHandoffTimer = setTimeout(async () => {
       if (supervisor.done || supervisor.paused)
         return;
@@ -25771,7 +25788,17 @@ ${interpolate(templates.continuePrompt, { attempt: String(attemptN), verdict })}
       const st = sessionMap.get(ralphId);
       if (st?.workerSpawned)
         return;
-      await notifySupervisor(`ralph/attempt-${attempt}`, "Strategist did not hand off to a worker within the heartbeat window. Re-check prompt delivery or restart supervision.", "warning", true, ralphId);
+      const retries = supervisor.ralphHandoffRetries ?? 0;
+      if (retries < cfg.strategistHandoffMaxRetries) {
+        supervisor.ralphHandoffRetries = retries + 1;
+        await notifySupervisor(`ralph/attempt-${attempt}`, `Strategist did not hand off; retrying strategist (${retries + 1}/${cfg.strategistHandoffMaxRetries}).`, "warning", true, ralphId);
+        supervisor.currentRalphSessionId = undefined;
+        await client.session.abort({ path: { id: ralphId } }).catch(() => {});
+        await spawnRalphSession(attempt);
+        return;
+      }
+      await notifySupervisor(`ralph/attempt-${attempt}`, "Strategist did not hand off after retries; supervision paused. Use ralph_create_supervisor_session(restart_if_done=true) to retry.", "error", true, ralphId);
+      supervisor.paused = true;
     }, timeoutMs);
     await notifySupervisor(`supervisor/attempt-${attempt}`, `Spawned Ralph strategist session ${ralphId}.`, "info", true);
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-ralph-rlm",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "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",