@hicaru/pi-rlm 0.1.7 → 0.1.8

package/src/prompts/phases.ts

@@ -0,0 +1,125 @@
+/**
+ * Per-phase guidance for the gated RLM pipeline.
+ * Injected at each phase boundary; the only channel between phases is durable
+ * artifacts under .rlm/artifacts/.
+ */
+import type { PhaseRecord } from "../core/gates.ts";
+import type { Phase } from "../core/pipeline.ts";
+
+const CLARIFY_GUIDANCE = Object.freeze([
+  "## Clarify phase (intake interview)",
+  "Interview the user until the task is understood. The engine COUNTS ask_user_question",
+  "rounds it services — you cannot advance without having actually asked at least once.",
+  "",
+  "1. Intent first: ask ONE open-ended intent question (what problem, who hits it, what",
+  "   success looks like). Options are answer *shapes* (e.g. end user / maintainer / operator);",
+  "   do NOT mark a Recommended option. The automatic Other / free-text path carries the real framing.",
+  "   Up to 2 more intent rounds if the answer still cannot scope a narrow probe; then proceed",
+  "   with what you have.",
+  "2. Probe before asking more: ground follow-ups in the REPL (deterministic search over",
+  "   context, a few llm_query reads) so questions cite real code as file:line.",
+  "3. Confirm inferences, don't record them: batch inferred decisions into one call —",
+  "   \"From the code I inferred <behavior> (file:line). Keep or change?\" The user's answer",
+  "   is the Decision, not your inference.",
+  "4. Scope / shape / detail rounds, one at a time: recommended option first; architecture",
+  "   (shape) options must state the tradeoff (\"optimizes X, costs Y\") — never one option",
+  "   masquerading as a choice; 2–4 independent detail questions may batch in one call.",
+  "5. Classify answers: Decision → record; Correction → re-probe that seam, re-ask dependents;",
+  "   Defer → ## Open Questions.",
+  "6. Terminate on depth, not politeness: stop when every raised branch has a Decision or a",
+  "   Deferral and ## Problem & Intent holds the user's own words verbatim. Do not pad the",
+  "   interview; do not ask a final \"looks good?\" rubber-stamp.",
+  "7. Then save_artifact(\"clarification\", content) with frontmatter:",
+  "     status: ready",
+  "     decisions_count: N",
+  "     open_questions_count: M",
+  "   and body sections:",
+  "     ## Problem & Intent  (user's words VERBATIM)",
+  "     ## Decisions         (one '- ' bullet per decision)",
+  "     ## Open Questions    (one '- ' bullet per deferral; may be empty with count 0)",
+  "     ## Non-Goals",
+  '   Then advance_phase("research", summary).',
+].join("\n"));
+
+const RESEARCH_GUIDANCE = Object.freeze([
+  "## Research phase",
+  "Read the clarifications artifact (if present) and honor recorded Decisions; do not silently",
+  "resolve Open Questions.",
+  "Probe the repository, delegate long reads via `llm_query_batched` / `llm_query_chunked`.",
+  "Every factual claim about the code MUST be cited as `path/file.ext:LINE` (or `LINE-LINE`).",
+  "The engine VERIFIES citations against the working tree — unbacked citations reject advance.",
+  "When research is complete, write ONE research document and call:",
+  '  `save_artifact("research", content)`  # frontmatter must include `status: ready`',
+  '  `advance_phase("blueprint", summary)`',
+  "Do not implement code in this phase.",
+].join("\n"));
+
+const BLUEPRINT_GUIDANCE = Object.freeze([
+  "## Blueprint phase",
+  "Read the clarifications artifact (if present) and plan only within recorded Decisions;",
+  "Open Questions that would block the design must be re-asked via ask_user_question, not assumed.",
+  'Produce ONE plan document and save it with `save_artifact("plan", content)`.',
+  "The ENGINE derive-checks the document — these are hard gates, not suggestions:",
+  "- frontmatter: `status: ready`, `phase_count: N`, `phases: [{n: 1, title: ...}, ...]`",
+  "- `phases:` / `phase_count` MUST match the `## Phase N:` body headings exactly (fenced examples ignored)",
+  "- every `file:line` citation MUST resolve against the working tree at this revision",
+  "Each `## Phase N: <title>` section contains:",
+  "- `### Changes Required` — per file: path + exact intended change (code from research)",
+  "- `### Success Criteria` — `#### Automated Verification:` (runnable commands) and",
+  "  `#### Manual Verification:` checklists",
+  "Phases are executed by ISOLATED workers, one at a time, in order: each phase must be",
+  "independently implementable, leave the tree working, and never share a file with a",
+  "later phase unless that phase only EDITS what an earlier phase CREATED.",
+  'When ready: `advance_phase("implement", summary)` — the engine runs implement fanout itself.',
+].join("\n"));
+
+const IMPLEMENT_GUIDANCE = Object.freeze([
+  "## Implement phase",
+  "The engine drives serial child-RLM workers over each plan phase — you do not implement",
+  "here. If you were re-entered into implement unexpectedly, call",
+  '`advance_phase("validate")` only after the fanout has already completed.',
+].join("\n"));
+
+const VALIDATE_GUIDANCE = Object.freeze([
+  "## Validate phase",
+  "Read the goal artifact (verbatim brief), the clarifications artifact (recorded Decisions),",
+  "and the plan. Check each phase's Success Criteria against the working tree.",
+  "Exclude paths listed in the baseline JSON (pre-existing dirt).",
+  "Open Questions are not silently resolved — a blocking one surfaces via ask_user_question.",
+  "Write ONE validation document via `save_artifact(\"validation\", content)` with frontmatter:",
+  "- `status: ready`",
+  "- `blockers_count: <int ≥ 0>`  # MEASURED — routing key; not prose",
+  "- `verdict: pass | fail`  # pass requires blockers_count === 0",
+  "Each blocker needs a resolvable `file:line` citation.",
+  "Then finalize: `answer[\"content\"] = <report>; answer[\"ready\"] = True`.",
+  "If `blockers_count > 0`, the engine re-enters blueprint (bounded by maxBackwardJumps).",
+].join("\n"));
+
+const GUIDANCE: Readonly<Record<Phase, string>> = Object.freeze({
+  clarify: CLARIFY_GUIDANCE,
+  research: RESEARCH_GUIDANCE,
+  blueprint: BLUEPRINT_GUIDANCE,
+  implement: IMPLEMENT_GUIDANCE,
+  validate: VALIDATE_GUIDANCE,
+});
+
+export function phaseGuidance(phase: Phase): string {
+  return GUIDANCE[phase];
+}
+
+/** Single-phase implement prompt for an isolated child RLM (serial fanout unit). */
+export function buildImplementPhasePrompt(planPath: string, r: PhaseRecord): string {
+  return [
+    `Implement ONLY Phase ${r.n} (${r.title}) of the plan at ${planPath} (${r.index + 1}/${r.total}).`,
+    `Read the plan from the REPL (open("${planPath}").read()).`,
+    "Hard rules (you are one unit of a sequenced run):",
+    "- CRITICAL: `context` is a STALE snapshot from run start. Always `open(path).read()` any file",
+    "  you will edit BEFORE computing stage_edit anchors — earlier phases may have already changed them.",
+    "- Touch ONLY the files this phase's ### Changes Required lists.",
+    "- Earlier phases have already landed; a missing prerequisite file is a HARD ERROR —",
+    "  finalize with 'Error: prerequisite missing: <path>' instead of creating it.",
+    "- Stage every change via stage_edit(path, old_text, new_text); never defer your own edits.",
+    "- Run only THIS phase's '#### Automated Verification:' commands; whole-plan checks are validate's job.",
+    `Finalize with a short summary of what landed for Phase ${r.n}.`,
+  ].join("\n");
+}

package/src/prompts/system.ts

@@ -20,6 +20,7 @@ export interface SystemPromptOptions {
   readonly todo?: boolean;
   readonly pipeline?: boolean;
   readonly maxPromptChars?: number;
+  readonly libraryLoader?: boolean;
 }
 
 export type ContextKind = "files" | "text";
@@ -76,7 +77,14 @@ function howToRunCode(): string {
   ].join(" ");
 }
 
-function replGlossary(kind: ContextKind, recursion: boolean, askUserQuestion: boolean, todo: boolean, pipeline: boolean): string {
+function replGlossary(
+  kind: ContextKind,
+  recursion: boolean,
+  askUserQuestion: boolean,
+  todo: boolean,
+  pipeline: boolean,
+  libraryLoader: boolean,
+): string {
   const lines = ["Available in the REPL:"];
   if (kind === "text") {
     lines.push(
@@ -116,8 +124,9 @@ function replGlossary(kind: ContextKind, recursion: boolean, askUserQuestion: bo
       "- `ask_user_question(questions: list[dict]) -> list[dict]`: pause and present the user",
       "  with 1-4 structured questions. Each question: {question, header, options: [{label, description}],",
       "  multiSelect?}. Returns list of {question, selected: [label], custom?}.",
-      "  Use when you have 2-4 concrete options from your analysis and need a decision before proceeding.",
-      "  DO NOT ask open-ended chat questions — use concrete options grounded in code/data.",
+      "  Default: use concrete options grounded in code/data (2–4 choices, Recommended first when ranking).",
+      "  Exception — clarify-phase intent rounds: lead with an open-ended intent question whose options",
+      "  are answer *shapes* (not a Recommended pick); free-text / Other carries the real framing.",
       "  Only valid at root depth; returns an error inside rlm_query sub-calls.",
     );
   }
@@ -130,6 +139,17 @@ function replGlossary(kind: ContextKind, recursion: boolean, askUserQuestion: bo
       "  Use to plan multi-step work before starting, then mark tasks as you complete them.",
     );
   }
+  if (libraryLoader) {
+    lines.push(
+      "- `load_library(source: str) -> dict`: load an EXTERNAL library, source tree, or document into a",
+      "  NEW `context_N` REPL variable. `source` may be a local directory (repomix-packed to the same",
+      "  list[dict] shape as `context`), a single file path (loaded as a plain str), or an https/git@ URL",
+      "  (shallow-cloned, then packed). Returns {\"index\": N, \"var\": \"context_N\", \"files\", \"chars\"}",
+      "  on success or an \"Error: ...\" string. Use it when the task requires learning an external lib's",
+      "  API, structure, or docs that are not in `context`; then chunk `context_N` to sub-LLMs exactly like",
+      "  `context`. Do not re-load a source that is already in a slot.",
+    );
+  }
   if (recursion) {
     lines.push(
       "- `rlm_query(prompt, model=None)` / `rlm_query_batched(prompts, model=None)`: recursive RLM",
@@ -148,9 +168,16 @@ function replGlossary(kind: ContextKind, recursion: boolean, askUserQuestion: bo
   }
   if (pipeline) {
     lines.push(
-      "- `advance_phase(phase: str, summary=None) -> str`: transition the root RLM pipeline to the next phase.",
-      "  Valid phases in order: 'research' → 'blueprint' → 'implement' → 'validate'. You must advance forward",
-      "  one phase at a time. Only callable at the root depth; returns an error in sub-RLM contexts.",
+      "- `save_artifact(kind: str, content: str) -> str`: persist a stage artifact under `.rlm/artifacts/`.",
+      "  Kinds: `'clarification'` | `'research'` | `'plan'` | `'validation'`. Must match the current phase.",
+      "  Frontmatter must eventually include `status: ready` before `advance_phase` will accept the transition.",
+      "- `advance_phase(phase: str, summary=None) -> str`: transition to the next pipeline phase.",
+      "  Order: 'clarify' → 'research' → 'blueprint' → 'implement' → 'validate' (one step at a time;",
+      "  clarify is skipped when ask_user_question is disabled).",
+      "  **advance_phase is validated by the engine** — it measures the latest saved artifact",
+      "  (status, structure, citations, blockers_count; clarify also requires ≥1 ask_user_question round).",
+      "  A rejected transition returns the gate error for you to fix; the phase does NOT advance.",
+      "  Only callable at root depth.",
     );
   }
   lines.push(
@@ -197,7 +224,10 @@ export function buildRlmSystemPrompt(meta: PromptMeta, opts: SystemPromptOptions
     "",
     howToRunCode(),
     "",
-    replGlossary(kind, recursion, opts.askUserQuestion ?? false, opts.todo ?? false, opts.pipeline ?? false),
+    replGlossary(
+      kind, recursion, opts.askUserQuestion ?? false, opts.todo ?? false,
+      opts.pipeline ?? false, opts.libraryLoader ?? false,
+    ),
     "",
     "REPL stdout over ~800 characters is truncated to a short excerpt — large results stay in your",
     "REPL variables as buffers. Re-print only the slice you need (e.g. `print(result[:500])`); never",
@@ -232,6 +262,7 @@ function nativeReplGlossary(): string {
     "- `rlm_query_batched(prompts, model=None) -> list[str]` — concurrent recursive RLM calls.",
     "",
     "- `todo(action, **kwargs) -> str` — manage a task list. Actions: create, update, list, get, delete, clear. Statuses: pending → in_progress → completed.",
+    "- `load_library(source)` → `context_N` (external).",
     "- `SHOW_VARS() -> str` — list all variables currently in the REPL.",
     "- `stage_edit(path, old_text, new_text) -> str`: stages an edit and returns an edit ID; apply IDs with `apply_edits`.",
     "- `answer`: dict `{\"content\": \"\", \"ready\": False}`. Setting `answer[\"ready\"] = True` delivers it to the user; do not restate it.",

package/src/prompts/user.ts

@@ -3,16 +3,24 @@
  * Native mode does not use these — pi's own loop supplies the turns.
  */
 
-export function buildTurnPrompt(iteration: number, maxIterations: number, gateMessage?: string): string {
+export function buildTurnPrompt(
+  iteration: number,
+  maxIterations: number,
+  gateMessage?: string,
+  phaseGuidanceText?: string,
+): string {
+  const parts: string[] = [];
+  if (phaseGuidanceText) parts.push(phaseGuidanceText);
+  if (gateMessage) parts.push(gateMessage);
+  const prefix = parts.length > 0 ? `${parts.join("\n\n")}\n\n` : "";
   const body = `Turn ${iteration + 1}/${maxIterations}:`;
-  const gate = gateMessage ? `\n${gateMessage}\n\n` : "";
   if (iteration === 0) {
     return (
       "You have not interacted with the REPL or seen your context yet. Look at the context first; " +
-      `do not provide a final answer yet.\n\n${gate}${body}`
+      `do not provide a final answer yet.\n\n${prefix}${body}`
     );
   }
-  return `${gate}${body}`;
+  return `${prefix}${body}`;
 }
 
 /** Asked once when the engine runs out of turns without a submitted answer. */

package/src/sandbox/protocol.ts

@@ -21,6 +21,12 @@ export interface LlmReply {
   readonly response?: string;
   readonly responses?: readonly string[];
   readonly answers?: readonly AskAnswer[];
+  /** load_library reply: temp file with the packed payload + assigned slot. */
+  readonly path?: string;
+  readonly json?: boolean;
+  readonly index?: number;
+  readonly files?: number;
+  readonly chars?: number;
   readonly error?: string;
 }
 
@@ -62,8 +68,10 @@ export type InterruptKind =
   | "rlm_query"
   | "rlm_query_batched"
   | "advance_phase"
+  | "save_artifact"
   | "ask_user_question"
-  | "todo";
+  | "todo"
+  | "load_library";
 
 export interface AskOption {
   readonly label: string;
@@ -111,6 +119,12 @@ interface AdvancePhaseInterrupt extends InterruptBase {
   readonly summary?: string;
 }
 
+interface SaveArtifactInterrupt extends InterruptBase {
+  readonly type: "save_artifact";
+  readonly artifactKind?: string;
+  readonly content?: string;
+}
+
 export interface AskUserQuestionInterrupt extends InterruptBase {
   readonly type: "ask_user_question";
   readonly questions: readonly AskQuestion[];
@@ -132,13 +146,20 @@ export interface TodoInterrupt extends InterruptBase {
   readonly includeDeleted?: boolean;
 }
 
+export interface LoadLibraryInterrupt extends InterruptBase {
+  readonly type: "load_library";
+  readonly source?: string;
+}
+
 /** A mid-exec sub-LLM/tool request from the worker. */
 export type WorkerInterrupt =
   | PromptInterrupt
   | BatchedPromptInterrupt
   | AdvancePhaseInterrupt
+  | SaveArtifactInterrupt
   | AskUserQuestionInterrupt
-  | TodoInterrupt;
+  | TodoInterrupt
+  | LoadLibraryInterrupt;
 
 export type WorkerMessage = WorkerResponse | WorkerInterrupt;
 
@@ -148,8 +169,10 @@ export const INTERRUPT_KINDS = Object.freeze(new Set<InterruptKind>([
   "rlm_query",
   "rlm_query_batched",
   "advance_phase",
+  "save_artifact",
   "ask_user_question",
   "todo",
+  "load_library",
 ]));
 
 function isRecord(value: unknown): value is Record<string, unknown> {

package/src/sandbox/sandbox.ts

@@ -26,6 +26,14 @@ import {
 } from "./protocol.ts";
 import { formatError } from "../util/errors.ts";
 
+/** Result of a host-side library pack requested by `load_library`. */
+export interface LibraryLoadResult {
+  readonly payload: unknown;     // string (single file) or ContextFile[] (packed dir/repo)
+  readonly index: number;        // slot assigned by the host
+  readonly files?: number;
+  readonly chars: number;
+}
+
 /** Handlers the bridge installs to service sub-LLM interrupts. Return the reply payload. */
 export interface SubLlmHandlers {
   llmQuery(prompt: string, model: string | null, depth: number): Promise<string>;
@@ -33,8 +41,10 @@ export interface SubLlmHandlers {
   rlmQuery(prompt: string, model: string | null, depth: number): Promise<string>;
   rlmQueryBatched(prompts: readonly string[], model: string | null, depth: number): Promise<string[]>;
   advancePhase(phase: string, summary: string | undefined, depth: number): Promise<string>;
+  saveArtifact(kind: string, content: string, depth: number): Promise<string>;
   askUserQuestion(questions: readonly AskQuestion[], depth: number): Promise<AskAnswer[]>;
   todo(action: string, params: Record<string, unknown>, depth: number): Promise<string>;
+  loadLibrary(source: string, depth: number): Promise<LibraryLoadResult>;
 }
 
 export interface SandboxOptions {
@@ -76,12 +86,14 @@ const REJECT: SubLlmHandlers = {
   rlmQuery: async () => formatError("sub-LLM bridge not configured"),
   rlmQueryBatched: async (p) => p.map(() => formatError("sub-LLM bridge not configured")),
   advancePhase: async () => formatError("phase advancement not available"),
+  saveArtifact: async () => formatError("save_artifact not available"),
   askUserQuestion: async (questions) => questions.map((q) => ({
     question: q.question,
     selected: [],
     custom: formatError("ask_user_question not configured"),
   })),
   todo: async () => formatError("todo not configured"),
+  loadLibrary: async () => { throw new Error("load_library not configured"); },
 };
 
 /** Distributive omit so each union member keeps its own fields (plain Omit collapses to shared keys). */
@@ -285,6 +297,15 @@ export class PythonSandbox {
     }
   }
 
+  /**
+   * Refresh the parent-side request watchdog for every pending request.
+   * Used during long mid-exec work (e.g. serial implement fanout) that does not
+   * produce additional worker interrupts on this sandbox.
+   */
+  refreshWatchdog(): void {
+    this.touchPending();
+  }
+
   private send(msg: ParentMessage): void {
     this.proc.stdin.write(`${JSON.stringify(msg)}\n`);
   }
@@ -346,6 +367,9 @@ export class PythonSandbox {
       } else if (msg.type === "advance_phase") {
         const response = await h.advancePhase(msg.phase ?? "", msg.summary, d);
         this.reply(msg.rid, { response });
+      } else if (msg.type === "save_artifact") {
+        const response = await h.saveArtifact(msg.artifactKind ?? "", msg.content ?? "", d);
+        this.reply(msg.rid, { response });
       } else if (msg.type === "ask_user_question") {
         const answers = await h.askUserQuestion(msg.questions ?? [], d);
         this.reply(msg.rid, { answers });
@@ -355,13 +379,30 @@ export class PythonSandbox {
         );
         const response = await h.todo(msg.action ?? "list", params, d);
         this.reply(msg.rid, { response });
+      } else if (msg.type === "load_library") {
+        const lib = await h.loadLibrary(msg.source ?? "", d);
+        const isJson = typeof lib.payload !== "string";
+        const path = await this.writeContextFile(lib.payload, isJson);
+        // Worker reads then unlinks (worker._load_library). Host must not unlink here —
+        // if the worker is SIGKILLed before os.remove, the temp file leaks in tmpdir (acceptable).
+        this.reply(msg.rid, { path, json: isJson, index: lib.index, files: lib.files, chars: lib.chars });
       }
     } catch (err) {
       this.reply(msg.rid, { error: err instanceof Error ? err.message : String(err) });
     }
   }
 
-  private reply(rid: string, body: { response?: string; responses?: string[]; answers?: AskAnswer[]; error?: string }): void {
+  private reply(rid: string, body: {
+    response?: string;
+    responses?: string[];
+    answers?: AskAnswer[];
+    path?: string;
+    json?: boolean;
+    index?: number;
+    files?: number;
+    chars?: number;
+    error?: string;
+  }): void {
     if (!this.disposed) this.send({ type: "llm_reply", rid, ...body });
   }
 

package/src/sandbox/worker.py

@@ -7,9 +7,9 @@ This is NOT a security sandbox: __import__ and open are available, so code can i
 Protocol (parent -> worker):  {"id","type":"exec"|"load_context"|"shutdown", ...}
 Protocol (worker -> parent):  {"id","ok",...result}            # response to a request
                               {"type":"llm_query"|"llm_query_batched"|"rlm_query"|...
-                               "advance_phase"|"ask_user_question"|"todo","rid",...}
+                               "advance_phase"|"save_artifact"|"ask_user_question"|"todo","rid",...}
                                                                 # mid-exec helper request
-When sandbox code calls llm_query/rlm_query/advance_phase/ask_user_question/todo, the worker writes a request line
+When sandbox code calls llm_query/rlm_query/advance_phase/save_artifact/ask_user_question/todo, the worker writes a request line
 and BLOCKS reading stdin until the matching {"type":"llm_reply","rid",...} arrives. The parent
 services the request in-process (it holds API keys).
 """
@@ -66,9 +66,9 @@ RESERVED = frozenset(
     {
         "llm_query", "llm_query_batched", "llm_query_chunked",
         "rlm_query", "rlm_query_batched",
-        "advance_phase",
+        "advance_phase", "save_artifact",
         "ask_user_question", "todo",
-        "stage_edit",
+        "stage_edit", "load_library",
         "SHOW_VARS", "answer", "context",
     }
 )
@@ -148,9 +148,11 @@ class Worker:
         ns["rlm_query"] = self._rlm_query
         ns["rlm_query_batched"] = self._rlm_query_batched
         ns["advance_phase"] = self._advance_phase
+        ns["save_artifact"] = self._save_artifact
         ns["ask_user_question"] = self._ask_user_question
         ns["todo"] = self._todo
         ns["stage_edit"] = self._stage_edit
+        ns["load_library"] = self._load_library
         ns["SHOW_VARS"] = self._show_vars
         if not isinstance(ns.get("answer"), _AnswerDict):
             cur = ns.get("answer")
@@ -331,11 +333,30 @@ class Worker:
         self._staged_edits.append({"id": edit_id, "path": path, "oldText": old_text, "newText": new_text})
         return edit_id
 
+    def _load_library(self, source: str) -> dict[str, Any] | str:
+        """Ask the host to pack an external dir/file/git-URL and load it as a new context slot."""
+        r = self._rpc("load_library", {"source": str(source)})
+        if r.get("error"):
+            return f"Error: {r['error']}"
+        path = r.get("path")
+        if not isinstance(path, str):
+            return "Error: malformed load_library reply (no path)"
+        try:
+            idx = self.load_context(path, r.get("index"), bool(r.get("json")))
+        finally:
+            try:
+                os.remove(path)  # worker owns temp-file cleanup (host does NOT unlink)
+            except OSError:
+                pass
+        return {"index": idx, "var": f"context_{idx}",
+                "files": r.get("files"), "chars": r.get("chars")}
+
     def _advance_phase(self, phase: str, summary: str | None = None) -> str:
         """Transition the root RLM pipeline to a new phase.
 
         Only callable at depth 0. The parent handler validates the transition
-        against the phase state machine (research → blueprint → implement → validate).
+        against the phase state machine (research → blueprint → implement → validate)
+        and runs deterministic artifact gates before accepting the transition.
         Returns a short confirmation, or an `Error: …` string the model can act on.
         """
         if self.depth > 0:
@@ -348,6 +369,22 @@ class Worker:
             return response
         return response if isinstance(response, str) else "ok"
 
+    def _save_artifact(self, kind: str, content: str) -> str:
+        """Persist a stage artifact (research/plan/validation) under .rlm/artifacts/.
+
+        Only callable at depth 0. The engine gates advance_phase against the latest
+        saved artifact for the current stage.
+        """
+        if self.depth > 0:
+            return "Error: save_artifact is only available at the root RLM depth"
+        r = self._rpc("save_artifact", {"artifactKind": str(kind), "content": str(content)})
+        if r.get("error"):
+            return f"Error: {r['error']}"
+        response = r.get("response", "ok")
+        if isinstance(response, str) and response.startswith("Error:"):
+            return response
+        return response if isinstance(response, str) else "ok"
+
     def _rlm_query_batched(self, prompts, model: str | None = None) -> list[str]:
         prompts = [str(p) for p in prompts]
         if not prompts:

package/src/state/index.ts

@@ -18,6 +18,7 @@ export type {
 } from "./rows.ts";
 export { STATE_SCHEMA_VERSION, isHeader, isTurn, isCompaction, isPhase, isTodo, isTerminal, isRow } from "./rows.ts";
 export { appendRow, appendTodoRow, pruneRuns, writeContextSidecar } from "./writes.ts";
-export { readRows, readHeader, readContextSidecar, listRunIds, resolveRunId } from "./reads.ts";
+export { readRows, readHeader, readContextSidecar, readLibrarySidecars, listRunIds, resolveRunId } from "./reads.ts";
+export type { LibrarySlot } from "./reads.ts";
 export { reconstructRlmState } from "./resume.ts";
 export type { PhaseRecon, ReconstructResult } from "./resume.ts";

package/src/state/paths.ts

@@ -32,8 +32,10 @@ export const runDir = (cwd: string, dir: string, runId: string): string => join(
 
 export const trailPath = (cwd: string, dir: string, runId: string): string => join(runDir(cwd, dir, runId), "trail.jsonl");
 
-export const contextPath = (cwd: string, dir: string, runId: string, json: boolean): string =>
-  join(runDir(cwd, dir, runId), json ? "context.json" : "context.txt");
+export const contextPath = (cwd: string, dir: string, runId: string, json: boolean, index = 0): string =>
+  join(runDir(cwd, dir, runId), index === 0
+    ? (json ? "context.json" : "context.txt")
+    : `context.${index}.${json ? "json" : "txt"}`);
 
 /** R-C1: per-turn snapshot files — `sandbox-<turn>.pkl` so resume can fall back to a prior turn if the latest rename failed. */
 export function snapshotPath(cwd: string, dir: string, runId: string, turn?: number): string {

package/src/state/reads.ts

@@ -6,8 +6,9 @@
  * by the slug (ISO-like timestamps are self-sorting).
  */
 
-import { open, readFile } from "node:fs/promises";
-import { runsDir, trailPath, contextPath } from "./paths.ts";
+import { open, readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { runsDir, runDir, trailPath, contextPath } from "./paths.ts";
 import { isHeader, isRow, type RunHeader, type Row } from "./rows.ts";
 import { errorMessage, failSoft, listDirectoriesSorted, pathExists, warn } from "./internal.ts";
 
@@ -83,6 +84,34 @@ export async function readContextSidecar(cwd: string, dir: string, runId: string
   }
 }
 
+const LIBRARY_SIDECAR = /^context\.(\d+)\.(json|txt)$/;
+
+export interface LibrarySlot {
+  readonly index: number;
+  readonly payload: unknown;
+}
+
+/** Fail-soft lister for load_library resume sidecars (`context.<index>.json|txt`). */
+export async function readLibrarySidecars(cwd: string, dir: string, runId: string): Promise<LibrarySlot[]> {
+  const entries = await failSoft(() => readdir(runDir(cwd, dir, runId)), [] as string[]);
+  const slots: LibrarySlot[] = [];
+  for (const name of entries) {
+    const m = LIBRARY_SIDECAR.exec(name);
+    if (!m) continue;
+    const index = Number(m[1]);
+    const json = m[2] === "json";
+    const content = await failSoft(
+      () => readFile(join(runDir(cwd, dir, runId), name), "utf-8"),
+      undefined as string | undefined,
+    );
+    if (content === undefined) continue;
+    try {
+      slots.push({ index, payload: json ? JSON.parse(content) as unknown : content });
+    } catch (e) { warn(e); }
+  }
+  return slots.sort((a, b) => a.index - b.index);
+}
+
 /** Enumerate run-ids by directory listing; newest first (slug sorts chronologically). */
 export async function listRunIds(cwd: string, dir: string): Promise<string[]> {
   return await failSoft(() => listDirectoriesSorted(runsDir(cwd, dir)), [], { warn: false });

package/src/state/resume.ts

@@ -32,6 +32,9 @@ export interface PhaseRecon {
   readonly current: string;
   readonly advancedAt: number;
   readonly summary?: string;
+  /** Repo-relative artifact paths keyed by the phase that produced them. */
+  readonly artifacts?: Readonly<Partial<Record<string, string>>>;
+  readonly backwardJumps?: number;
 }
 
 export type ReconstructResult =
@@ -107,6 +110,8 @@ export async function reconstructRlmState(
   const todoRows: { action: string; params: Record<string, unknown>; result: string }[] = [];
   let terminated = false;
   let phase: PhaseRecon | undefined;
+  // Accumulate artifact paths keyed by the producing phase (artifactPhase on the row).
+  const artifactsAcc: Record<string, string> = {};
 
   for (const row of rows) {
     if (isHeader(row)) continue;
@@ -139,7 +144,20 @@ export async function reconstructRlmState(
       continue;
     }
     if (isPhase(row)) {
-      phase = { current: row.phase, advancedAt: row.turn - 1, summary: row.summary };
+      if (row.artifactPath !== undefined && row.artifactPhase !== undefined) {
+        artifactsAcc[row.artifactPhase] = row.artifactPath;
+      }
+      // On loop-back to blueprint, drop stale plan so resume cannot re-gate with it.
+      if (row.phase === "blueprint" && row.backwardJumps !== undefined && row.backwardJumps > 0) {
+        delete artifactsAcc.blueprint;
+      }
+      phase = {
+        current: row.phase,
+        advancedAt: row.turn - 1,
+        summary: row.summary,
+        artifacts: Object.keys(artifactsAcc).length > 0 ? { ...artifactsAcc } : undefined,
+        backwardJumps: row.backwardJumps,
+      };
       continue;
     }
     if (isTodo(row)) {

package/src/state/rows.ts

@@ -88,6 +88,12 @@ export interface PhaseRow {
   readonly ts: string;
   readonly phase: string;
   readonly summary?: string;
+  /** Optional fields (no schema-version break — isPhase guard unchanged). */
+  readonly artifactPath?: string;
+  /** Phase that produced `artifactPath` (not inferred from order — loop-back safe). */
+  readonly artifactPhase?: string;
+  readonly blockersCount?: number;
+  readonly backwardJumps?: number;
 }
 
 export type Row = RunHeader | TurnRow | CompactionRow | TodoRow | TerminalRow | PhaseRow;

package/src/state/writes.ts

@@ -32,11 +32,13 @@ export async function appendTodoRow(cwd: string, dir: string, runId: string, row
   return await appendRow(cwd, dir, runId, { kind: "todo", ...row });
 }
 
-/** Persist the original context ONCE at run start so resume can reload it. */
-export async function writeContextSidecar(cwd: string, dir: string, runId: string, context: unknown, json: boolean): Promise<boolean> {
+/** Persist a context payload for resume. Slot 0 = repo context; index ≥ 1 = load_library slots. */
+export async function writeContextSidecar(
+  cwd: string, dir: string, runId: string, context: unknown, json: boolean, index = 0,
+): Promise<boolean> {
   return await failSoft(async () => {
     await mkdir(runDir(cwd, dir, runId), { recursive: true });
-    await writeFile(contextPath(cwd, dir, runId, json), json ? JSON.stringify(context) : String(context), "utf-8");
+    await writeFile(contextPath(cwd, dir, runId, json, index), json ? JSON.stringify(context) : String(context), "utf-8");
     return true;
   }, false);
 }