opencode-ralph-rlm 0.1.11 → 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.",
@@ -23522,7 +23529,22 @@ var DEFAULT_TEMPLATES = {
     "- 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."
+    "- Stop the loop explicitly with ralph_end_supervision() when the user is done or verification passed.",
+    "",
+    "Onboarding checklist (supervisor):",
+    "- If setup is incomplete, run ralph_doctor(autofix=true).",
+    "- If PLAN.md is missing or weak, run ralph_quickstart_wizard(...) or ralph_bootstrap_plan(...) + ralph_validate_plan().",
+    "- Start supervision with ralph_create_supervisor_session(start_loop=true) unless autoStartOnMainIdle is enabled.",
+    "- Use ralph_supervision_status() to confirm current attempt and active sessions.",
+    "",
+    "Protocol files (purpose):",
+    "- PLAN.md: goals, milestones, definition of done (authoritative).",
+    "- RLM_INSTRUCTIONS.md: inner loop operating manual (authoritative, updated between attempts).",
+    "- CURRENT_STATE.md: scratch for the current attempt only.",
+    "- PREVIOUS_STATE.md: snapshot of last attempt's scratch.",
+    "- NOTES_AND_LEARNINGS.md: durable learnings across attempts.",
+    "- CONVERSATION.md / SUPERVISOR_LOG.md: status feed and timeline for the supervisor.",
+    "- CONTEXT_FOR_RLM.md: large reference; workers must use rlm_grep/rlm_slice."
   ].join(`
 `),
   systemPromptAppend: "",
@@ -23536,7 +23558,12 @@ var DEFAULT_TEMPLATES = {
     "- NOTES_AND_LEARNINGS.md          \u2014 append-only durable learnings",
     "- CONVERSATION.md                 \u2014 append-only supervisor-visible status feed",
     "- CONTEXT_FOR_RLM.md              \u2014 large reference; access via rlm_grep + rlm_slice",
-    "- .opencode/agents/<name>/        \u2014 sub-agent state directories"
+    "- .opencode/agents/<name>/        \u2014 sub-agent state directories",
+    "",
+    "## Loop control",
+    "- ralph_create_supervisor_session(start_loop=true) to start",
+    "- ralph_pause_supervision() / ralph_resume_supervision() to pause/resume",
+    "- ralph_end_supervision() to stop and clean up"
   ].join(`
 `),
   continuePrompt: [
@@ -23680,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:",
@@ -23700,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.",
@@ -23708,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(`
 `)
 };
@@ -24238,6 +24269,27 @@ var RalphRLM = async ({ client, $, worktree }) => {
       }).catch(() => {});
     }
   };
+  const sendPromptWithFallback = async (sessionId, text, label, originSessionId) => {
+    try {
+      await client.session.promptAsync({
+        path: { id: sessionId },
+        body: { parts: [{ type: "text", text }] }
+      });
+      return true;
+    } catch (err) {
+      await notifySupervisor("supervisor", `${label} promptAsync failed: ${err instanceof Error ? err.message : String(err)}`, "warning", true, originSessionId);
+    }
+    try {
+      await client.session.prompt({
+        path: { id: sessionId },
+        body: { parts: [{ type: "text", text }] }
+      });
+      return true;
+    } catch (err) {
+      await notifySupervisor("supervisor", `${label} prompt fallback failed: ${err instanceof Error ? err.message : String(err)}`, "error", true, originSessionId);
+      return false;
+    }
+  };
   const detectProjectDefaults = (root) => exports_Effect.gen(function* () {
     const j = (f) => NodePath.join(root, f);
     const hasBunLock = (yield* fileExists(j("bun.lockb"))) || (yield* fileExists(j("bun.lock")));
@@ -25134,6 +25186,10 @@ No pending questions found.`));
       supervisor.activeReviewerSessionId = undefined;
       supervisor.activeReviewerOutputPath = undefined;
       await persistReviewerState();
+      if (supervisor.ralphHandoffTimer) {
+        clearTimeout(supervisor.ralphHandoffTimer);
+        supervisor.ralphHandoffTimer = undefined;
+      }
       if (args2.clear_binding === true) {
         supervisor.sessionId = undefined;
       }
@@ -25575,7 +25631,8 @@ Set a new goal and run again.
     const st = sessionMap.get(sessionId);
     sessionMap.delete(sessionId);
     let didUpdate = false;
-    if (supervisor.currentRalphSessionId === sessionId) {
+    const clearedRalph = supervisor.currentRalphSessionId === sessionId;
+    if (clearedRalph) {
       supervisor.currentRalphSessionId = undefined;
       didUpdate = true;
     }
@@ -25591,6 +25648,10 @@ Set a new goal and run again.
       didUpdate = true;
       await persistReviewerState();
     }
+    if (supervisor.ralphHandoffTimer && clearedRalph) {
+      clearTimeout(supervisor.ralphHandoffTimer);
+      supervisor.ralphHandoffTimer = undefined;
+    }
     if (didUpdate && st) {
       await notifySupervisor(`${st.role}/attempt-${st.attempt}`, `${st.role} session ended (${reason}).`, "info", true, sessionId);
     }
@@ -25651,10 +25712,18 @@ ${interpolate(templates.continuePrompt, { attempt: String(attemptN), verdict })}
       attempt: String(attempt),
       nextAttempt: String(attempt + 1)
     });
-    await client.session.promptAsync({
-      path: { id: workerId },
-      body: { parts: [{ type: "text", text: promptText }] }
-    }).catch(() => {});
+    const promptOk = await sendPromptWithFallback(workerId, promptText, `Worker prompt (attempt ${attempt})`, workerId);
+    if (!promptOk) {
+      mutateSession(workerId, (s) => {
+        s.reportedStatus = "error";
+        s.reportedStatusNote = "Worker prompt failed";
+      });
+      supervisor.currentWorkerSessionId = undefined;
+      await client.session.abort({ path: { id: workerId } }).catch(() => {});
+      await notifySupervisor(`worker/attempt-${attempt}`, "Worker prompt failed; supervision paused. Retry with ralph_create_supervisor_session(restart_if_done=true).", "error", true);
+      supervisor.paused = true;
+      throw new Error("Worker prompt failed");
+    }
     await notifySupervisor(`supervisor/attempt-${attempt}`, `Spawned worker session ${workerId}.`, "info", true);
     return workerId;
   };
@@ -25667,10 +25736,16 @@ ${interpolate(templates.continuePrompt, { attempt: String(attemptN), verdict })}
     if (st.workerSpawned) {
       throw new Error("ralph_spawn_worker() has already been called for this attempt.");
     }
+    if (supervisor.ralphHandoffTimer) {
+      clearTimeout(supervisor.ralphHandoffTimer);
+      supervisor.ralphHandoffTimer = undefined;
+    }
+    const workerId = await spawnRlmWorker(st.attempt);
     mutateSession(sessionID, (s) => {
       s.workerSpawned = true;
     });
-    const workerId = await spawnRlmWorker(st.attempt);
+    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);
   };
@@ -25679,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) => {
@@ -25688,10 +25767,39 @@ ${interpolate(templates.continuePrompt, { attempt: String(attemptN), verdict })}
       attempt: String(attempt),
       nextAttempt: String(attempt + 1)
     });
-    await client.session.promptAsync({
-      path: { id: ralphId },
-      body: { parts: [{ type: "text", text: promptText }] }
-    }).catch(() => {});
+    const promptOk = await sendPromptWithFallback(ralphId, promptText, `Strategist prompt (attempt ${attempt})`, ralphId);
+    if (!promptOk) {
+      supervisor.currentRalphSessionId = undefined;
+      await client.session.abort({ path: { id: ralphId } }).catch(() => {});
+      await notifySupervisor(`supervisor/attempt-${attempt}`, "Strategist prompt failed; supervision paused. Retry with ralph_create_supervisor_session(restart_if_done=true).", "error", true);
+      supervisor.paused = true;
+      return;
+    }
+    if (supervisor.ralphHandoffTimer) {
+      clearTimeout(supervisor.ralphHandoffTimer);
+    }
+    const cfg = await run(getConfig());
+    const timeoutMs = Math.max(cfg.strategistHandoffMinutes, 1) * 60000;
+    supervisor.ralphHandoffTimer = setTimeout(async () => {
+      if (supervisor.done || supervisor.paused)
+        return;
+      if (supervisor.currentRalphSessionId !== ralphId)
+        return;
+      const st = sessionMap.get(ralphId);
+      if (st?.workerSpawned)
+        return;
+      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);
   };
   const handleWorkerIdle = async (workerSessionId) => {
@@ -25821,7 +25929,7 @@ ${interpolate(templates.continuePrompt, { attempt: String(attemptN), verdict })}
     },
     "experimental.chat.system.transform": async (input, output) => {
       output.system = output.system ?? [];
-      const sessionID = input.sessionID ?? input.session_id;
+      const sessionID = input.sessionID ?? input.session_id ?? input.session?.id;
       const role = sessionMap.get(sessionID ?? "")?.role;
       const base = role === "worker" || role === "subagent" ? templates.workerSystemPrompt : role === "ralph" ? templates.ralphSessionSystemPrompt : templates.systemPrompt;
       const full = templates.systemPromptAppend ? `${base}

package/package.json

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