@hicaru/pi-rlm 0.2.2 → 0.3.1

package/src/sandbox/interrupts.ts

@@ -10,21 +10,27 @@ import type { WorkerInterrupt } from "./protocol.ts";
 import { writeContextTempFile } from "./context-file.ts";
 import { errorMessage, formatError } from "../util/errors.ts";
 
-/** Result of a host-side library pack requested by `load_library`. */
-export interface LibraryLoadResult {
-  readonly payload: unknown;     // always ContextFile[] under lib/<id>/
+/** Result of a host-side pack requested by `add_context`. */
+export interface AddContextResult {
+  readonly payload: unknown;     // always ContextFile[] under ctx/<id>/ (or un-prefixed for cwd)
   readonly files?: number;
   readonly chars: number;
   readonly sourceId: string;
   readonly pathPrefix: string;
-  /** Host already has this library — no pack, empty payload. */
+  /** Host already has this source — no pack, empty payload. */
   readonly alreadyLoaded?: boolean;
+  /** Document-type files in the payload (fresh + cache hits). */
+  readonly documents?: number;
+  /** Documents freshly converted this call (cache hits excluded). */
+  readonly converted?: number;
+  /** Paths skipped during packing (model-facing). */
+  readonly skipped?: readonly { readonly path: string; readonly reason: string }[];
 }
 
 /**
  * Per-interrupt routing context for the sub-LLM handlers.
  *
- * Only the four sub-call kinds can be spawned, so only they carry it; load_library is
+ * Only the four sub-call kinds can be spawned, so only they carry it; add_context is
  * always synchronous within one exec.
  */
 export interface SubcallOpts {
@@ -43,7 +49,7 @@ export interface SubLlmHandlers {
   llmQueryBatched(prompts: readonly string[], model: string | null, depth: number, opts: SubcallOpts): Promise<string[]>;
   rlmQuery(prompt: string, model: string | null, depth: number, opts: SubcallOpts): Promise<string>;
   rlmQueryBatched(prompts: readonly string[], model: string | null, depth: number, opts: SubcallOpts): Promise<string[]>;
-  loadLibrary(source: string, depth: number): Promise<LibraryLoadResult>;
+  addContext(source: string, depth: number): Promise<AddContextResult>;
 }
 
 /** Narrow an unknown JSON value to a frozen string array. Non-strings and blanks are dropped. */
@@ -65,7 +71,7 @@ export const REJECT: SubLlmHandlers = {
   llmQueryBatched: async (p) => p.map(() => formatError("sub-LLM bridge not configured")),
   rlmQuery: async () => formatError("sub-LLM bridge not configured"),
   rlmQueryBatched: async (p) => p.map(() => formatError("sub-LLM bridge not configured")),
-  loadLibrary: async () => { throw new Error("load_library not configured"); },
+  addContext: async () => { throw new Error("add_context not configured"); },
 };
 
 /** Body of a reply frame — the union of every handler's payload shape. */
@@ -79,6 +85,9 @@ export interface ReplyBody {
   source_id?: string;
   path_prefix?: string;
   already_loaded?: boolean;
+  documents?: number;
+  converted?: number;
+  skipped?: readonly { readonly path: string; readonly reason: string }[];
   error?: string;
 }
 
@@ -114,8 +123,8 @@ export async function serviceInterrupt(
     } else if (msg.type === "rlm_query_batched") {
       const responses = await h.rlmQueryBatched(msg.prompts ?? [], msg.model ?? null, d, opts);
       reply(msg.rid, { responses });
-    } else if (msg.type === "load_library") {
-      const lib = await h.loadLibrary(msg.source ?? "", d);
+    } else if (msg.type === "add_context") {
+      const lib = await h.addContext(msg.source ?? "", d);
       if (lib.alreadyLoaded) {
         // No temp file — worker short-circuits on already_loaded.
         reply(msg.rid, {
@@ -124,10 +133,13 @@ export async function serviceInterrupt(
           chars: lib.chars,
           source_id: lib.sourceId,
           path_prefix: lib.pathPrefix,
+          documents: lib.documents ?? 0,
+          converted: lib.converted ?? 0,
+          skipped: lib.skipped,
         });
       } else {
         const { path, json: isJson } = await writeContextTempFile(lib.payload);
-        // Worker reads then unlinks (worker._load_library). Host must not unlink here —
+        // Worker reads then unlinks (worker._add_context). Host must not unlink here —
         // if the worker is SIGKILLed before os.remove, the temp file leaks in tmpdir (acceptable).
         reply(msg.rid, {
           path,
@@ -136,6 +148,9 @@ export async function serviceInterrupt(
           chars: lib.chars,
           source_id: lib.sourceId,
           path_prefix: lib.pathPrefix,
+          documents: lib.documents ?? 0,
+          converted: lib.converted ?? 0,
+          skipped: lib.skipped,
         });
       }
     }

package/src/sandbox/protocol.ts

@@ -18,15 +18,21 @@ export interface LlmReply {
   readonly rid: string;
   readonly response?: string;
   readonly responses?: readonly string[];
-  /** load_library reply: temp file with the packed payload (+ namespace metadata). */
+  /** add_context reply: temp file with the packed payload (+ namespace metadata). */
   readonly path?: string;
   readonly json?: boolean;
   readonly files?: number;
   readonly chars?: number;
   readonly source_id?: string;
   readonly path_prefix?: string;
-  /** Host-side idempotency: library already loaded — no path payload. */
+  /** Host-side idempotency: source already loaded — no path payload. */
   readonly already_loaded?: boolean;
+  /** Document-type files in the payload (fresh + cache hits). */
+  readonly documents?: number;
+  /** Documents freshly converted this call (cache hits excluded). */
+  readonly converted?: number;
+  /** Paths skipped during packing (binary, no-converter, …). */
+  readonly skipped?: readonly { readonly path: string; readonly reason: string }[];
   readonly error?: string;
 }
 
@@ -56,7 +62,7 @@ export type InterruptKind =
   | "llm_query_batched"
   | "rlm_query"
   | "rlm_query_batched"
-  | "load_library";
+  | "add_context";
 
 interface InterruptBase {
   readonly rid: string;
@@ -88,8 +94,8 @@ interface BatchedPromptInterrupt extends InterruptBase {
   readonly paths?: readonly string[];
 }
 
-export interface LoadLibraryInterrupt extends InterruptBase {
-  readonly type: "load_library";
+export interface AddContextInterrupt extends InterruptBase {
+  readonly type: "add_context";
   readonly source?: string;
 }
 
@@ -97,7 +103,7 @@ export interface LoadLibraryInterrupt extends InterruptBase {
 export type WorkerInterrupt =
   | PromptInterrupt
   | BatchedPromptInterrupt
-  | LoadLibraryInterrupt;
+  | AddContextInterrupt;
 
 export type WorkerMessage = WorkerResponse | WorkerInterrupt;
 
@@ -106,7 +112,7 @@ export const INTERRUPT_KINDS = Object.freeze(new Set<InterruptKind>([
   "llm_query_batched",
   "rlm_query",
   "rlm_query_batched",
-  "load_library",
+  "add_context",
 ]));
 
 function isRecord(value: unknown): value is Record<string, unknown> {

package/src/sandbox/py/guards.py

@@ -19,6 +19,13 @@ import sys
 from contextlib import contextmanager
 from typing import Any
 
+from hostio import pin_stdio_utf8
+
+# Pin UTF-8 before anything reads or writes a frame. On Windows these three default to the
+# locale encoding (cp1252), while the JSONL protocol Node speaks is UTF-8 both ways — see
+# issue #7. reconfigure() mutates in place, so the REAL_* captures below are the same objects.
+pin_stdio_utf8()
+
 # Capture the REAL stdio before exec() redirects sys.stdout/sys.stderr into buffers.
 # All protocol writes must go to the real stdout even while user code's prints are captured.
 REAL_STDOUT = sys.stdout
@@ -86,7 +93,7 @@ RESERVED = frozenset(
         "spawn", "rlm_await", "rlm_await_all",
         "map_files", "llm_map_reduce",
         "search", "grep_context", "outline",
-        "load_library",
+        "add_context",
         "SHOW_VARS", "answer", "context",
     }
 )

package/src/sandbox/py/hostio.py

@@ -0,0 +1,57 @@
+"""Host↔worker transport, pinned to UTF-8.
+
+Every byte the host hands this worker is UTF-8: the context temp files come from Node's
+FileHandle.write(string) (default utf8, see sandbox/context-file.ts) and the JSONL frames come
+off a pipe Node writes the same way. Python does NOT match that — text I/O defaults to the
+locale encoding, which is cp1252 on a Western Windows install. That mismatch is issue #7: a
+packed repo holding any non-ASCII byte raised UnicodeDecodeError before the REPL ever ran.
+
+Encoding is therefore never left to the locale here. Interpreter-wide UTF-8 mode (-X utf8=1,
+set by the host in sandbox.ts) covers model-written open(); these two functions cover the
+scaffold's own I/O, and they win outright — PYTHONIOENCODING overrides -X utf8=1, and
+reconfigure() overrides PYTHONIOENCODING.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import sys
+from typing import Any
+
+ENCODING = "utf-8"
+
+
+def read_host_payload(path: str, is_json: bool) -> Any:
+    """Read a payload the host serialized to a temp file.
+
+    Strict on decode errors by design. The host always writes UTF-8, so a failure here is a
+    transport bug, not bad input — and errors="replace" would hand the model silently
+    mojibake'd source code instead of surfacing the problem.
+
+    The explicit encoding= is intentionally redundant with -X utf8=1 under a normal spawn:
+    UTF-8 mode already makes the default encoding UTF-8. It still matters so a standalone
+    import of this module (or a worker started without -X utf8=1) cannot silently reintroduce
+    issue #7. phase-encoding.ts check 6 (AST / EncodingWarning) is the only automated guard
+    that encoding= is present — do not drop either side of that net.
+    """
+    with io.open(path, "r", encoding=ENCODING) as f:
+        return json.load(f) if is_json else f.read()
+
+
+def pin_stdio_utf8() -> None:
+    """Force the three real streams to UTF-8, whatever the locale or PYTHONIOENCODING says.
+
+    The write side uses surrogatepass, not strict: model code can synthesize a lone surrogate
+    (a bad decode, a truncated pair), and json.dumps(ensure_ascii=False) would then raise
+    inside _send — killing the worker on a request it had already completed. The read side
+    uses replace so a corrupt frame comes back as a "bad json" error response instead of an
+    exception that escapes main()'s loop and takes the worker down (fail-soft I/O, AGENTS.md).
+    """
+    for stream, errors in (
+        (sys.stdin, "replace"),
+        (sys.stdout, "surrogatepass"),
+        (sys.stderr, "surrogatepass"),
+    ):
+        if isinstance(stream, io.TextIOWrapper):  # not a TextIOWrapper under some test harnesses
+            stream.reconfigure(encoding=ENCODING, errors=errors)

package/src/sandbox/py/retrieval.py

@@ -46,7 +46,7 @@ def _chunk_text(text: str, chunk_chars: int) -> list[str]:
 
 
 _INDEX_WINDOW_LINES = 40       # a window is the retrieval unit: big enough to carry meaning
-_INDEX_MAX_WINDOWS = 20_000    # ceiling so a huge load_library() cannot exhaust worker memory
+_INDEX_MAX_WINDOWS = 20_000    # ceiling so a huge add_context() cannot exhaust worker memory
 _SNIPPET_CHARS = 400
 _GREP_HARD_CAP = 200           # absolute ceiling on returned grep hits, whatever k asks for
 _BM25_K1 = 1.2

package/src/sandbox/py/tasks.py

@@ -41,14 +41,27 @@ def _reduce_batch(n: int):
     return reduce
 
 
-def _reduce_chunked(sizes: list[int]):
-    """Concatenate several llm_query_batched replies back into one flat chunk list."""
+def _reduce_chunked(sizes: list[int], drop_empty: bool = True):
+    """Concatenate several llm_query_batched replies back into one flat chunk list.
+
+    drop_empty=True (llm_query_chunked): filter "" replies so results never degrade
+    to blank entries; the flattened list may then be shorter than the chunk count,
+    so callers must consume answers in order and never index-match a chunk to a slot.
+    drop_empty=False (map_files): keep "" placeholders because _reduce_map_files
+    regroups by position — dropping an empty reply there would shift every later
+    slice and merge file contents into the wrong paths.
+    """
     per = [_reduce_batch(n) for n in sizes]
 
     def reduce(replies: list[dict[str, Any]]) -> list[str]:
+        if len(replies) != len(per):
+            return [f"Error: chunk reply count mismatch ({len(replies)} != {len(per)})"] * sum(sizes)
         out: list[str] = []
         for red, rep in zip(per, replies):
-            out.extend(red([rep]))
+            if drop_empty:
+                out.extend(x for x in red([rep]) if x)
+            else:
+                out.extend(red([rep]))
         return out
     return reduce
 
@@ -59,7 +72,7 @@ def _reduce_map_files(sizes: list[int], spans: list[tuple[str, int]]):
     A file larger than the per-prompt budget contributed several requests; its answers rejoin
     in order, which is what makes map_files a {path: answer} dict rather than a flat list.
     """
-    flatten = _reduce_chunked(sizes)
+    flatten = _reduce_chunked(sizes, drop_empty=False)
 
     def reduce(replies: list[dict[str, Any]]) -> dict[str, str]:
         responses = flatten(replies)

package/src/sandbox/py/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"|
-                               "rlm_query_batched"|"load_library","rid",...}
+                               "rlm_query_batched"|"add_context","rid",...}
                                                                 # mid-exec helper request
-When sandbox code calls llm_query/rlm_query/load_library, the worker writes a
+When sandbox code calls llm_query/rlm_query/add_context, 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).
 
@@ -44,6 +44,7 @@ from guards import (
     REAL_STDERR as _REAL_STDERR,
     REAL_STDIN as _REAL_STDIN,
 )
+from hostio import read_host_payload
 from retrieval import (
     _Bm25Index,
     _chunk_text,
@@ -113,7 +114,7 @@ class Worker:
         builtins = _SAFE_BUILTINS.copy()
         builtins["open"] = open
         self.ns = {"__builtins__": builtins, "__name__": "__main__"}
-        self._context_payload: Any | None = None  # pristine restore for the single `context` var
+        self._context_payload: Any = []  # empty list — the only starting value that needs no bootstrap branch
         self._nudged: set[str] = set()
         self._index: _Bm25Index | None = None
         self._index_stamp: tuple[int, int] | None = None  # (id(context), len(context))
@@ -144,7 +145,7 @@ class Worker:
             ns["answers"] = {}
         if not isinstance(ns.get("plan"), dict):
             ns["plan"] = {}
-        ns["load_library"] = self._load_library
+        ns["add_context"] = self._add_context
         ns["SHOW_VARS"] = self._show_vars
         if not isinstance(ns.get("answer"), _AnswerDict):
             cur = ns.get("answer")
@@ -157,9 +158,8 @@ class Worker:
             ns["answer"] = ans
         # Single context variable (RLM paper: the context lives in the environment and
         # the model may transform it in place). Re-inject only if the model deleted the
-        # name entirely; mutations and re-binds persist within the run.
-        if self._context_payload is not None:
-            ns.setdefault("context", self._context_payload)
+        # name entirely; mutations and re-binds persist within the run. Always a list.
+        ns.setdefault("context", self._context_payload)
         # Scrub any legacy context_N names so the model never sees multi-slot APIs.
         for k in list(ns.keys()):
             if k != "context" and _CONTEXT_NAME.match(k):
@@ -412,7 +412,7 @@ class Worker:
         """Build the BM25 index on first use; rebuild when `context` was replaced or resized.
 
         Identity+length is a cheap stamp that catches the two ways context actually changes:
-        load_library() extending the list, and the model re-binding the name. In-place edits
+        add_context() extending the list, and the model re-binding the name. In-place edits
         that preserve length are not detected — documented, and rare in practice.
         """
         ctx = self.ns.get("context")
@@ -556,23 +556,24 @@ class Worker:
     def _rlm_query(self, prompt: str, model: str | None = None, paths=None) -> str:
         return self._await_task(self._start_rlm_query(prompt, model, paths))
 
-    def _load_library(self, source: str) -> dict[str, Any] | str:
+    def _add_context(self, source: str) -> dict[str, Any] | str:
         """Pack an external dir/file/git-URL on the host and append it into `context`.
 
-        Paths are namespaced under lib/<source_id>/ (host). Content is always in the
+        Paths are namespaced under ctx/<source_id>/ (host). Content is always in the
         single `context` list — never a new context_N variable.
         Host-side idempotency may return already_loaded without a payload path.
+        Documents (PDF/DOCX/…) are converted to Markdown on the host.
         """
-        r = self._rpc("load_library", {"source": str(source)})
+        r = self._rpc("add_context", {"source": str(source)})
         if r.get("error"):
             return f"Error: {r['error']}"
         if r.get("already_loaded"):
-            source_id = r.get("source_id") if isinstance(r.get("source_id"), str) else "lib"
-            path_prefix = r.get("path_prefix") if isinstance(r.get("path_prefix"), str) else f"lib/{source_id}/"
+            source_id = r.get("source_id") if isinstance(r.get("source_id"), str) else "ctx"
+            path_prefix = r.get("path_prefix") if isinstance(r.get("path_prefix"), str) else f"ctx/{source_id}/"
             ctx = self.ns.get("context")
             ctx_len = len(ctx) if isinstance(ctx, list) else 0
             print(
-                f"[rlm] load_library: already loaded {source_id} "
+                f"[rlm] add_context: already loaded {source_id} "
                 f"(paths under {path_prefix}, context len={ctx_len})"
             )
             return {
@@ -583,69 +584,85 @@ class Worker:
                 "chars": r.get("chars"),
                 "context_len": ctx_len,
                 "already_loaded": True,
+                "documents": 0,
+                "converted": 0,
+                "skipped": [],
             }
         path = r.get("path")
         if not isinstance(path, str):
-            return "Error: malformed load_library reply (no path)"
+            return "Error: malformed add_context reply (no path)"
         try:
-            with io.open(path, "r") as f:
-                payload = json.load(f) if r.get("json") else f.read()
+            payload = read_host_payload(path, bool(r.get("json")))
         finally:
             try:
                 os.remove(path)  # worker owns temp-file cleanup (host does NOT unlink)
             except OSError:
                 pass
-        return self._append_library(str(source), payload, r)
+        return self._append_context(str(source), payload, r)
 
-    def _append_library(self, source: str, payload: Any, meta: dict[str, Any]) -> dict[str, Any] | str:
-        """Append host-packed library files into `context` (idempotent by path prefix).
+    def _append_context(self, source: str, payload: Any, meta: dict[str, Any]) -> dict[str, Any] | str:
+        """Append host-packed files into `context` (idempotent by path prefix).
 
         The two refusals below are pre-flighted host-side by LIST_CONTEXT_REQUIRED /
-        NO_FILES_PRODUCED in src/bridge/library.ts, so the host never commits a
+        NO_FILES_PRODUCED in src/bridge/add-context.ts, so the host never commits a
         loaded-prefix for an append that fails here. Reaching either one means host and worker
         disagree about `context`; keep the wording identical to its twin.
         """
         ctx = self.ns.get("context")
         if not isinstance(ctx, list):
             kind = type(ctx).__name__ if ctx is not None else "None"
-            return f"Error: load_library requires list context (file bundle); got {kind}"
+            return f"Error: add_context requires list context (file bundle); got {kind}"
 
         source_id = meta.get("source_id")
         if not isinstance(source_id, str) or not source_id:
-            source_id = "lib"
+            source_id = "ctx"
         path_prefix = meta.get("path_prefix")
-        if not isinstance(path_prefix, str) or not path_prefix:
-            path_prefix = f"lib/{source_id}/"
-
-        # Idempotent: already present if any path uses this library prefix.
-        for item in ctx:
-            if isinstance(item, dict) and str(item.get("path", "")).startswith(path_prefix):
-                print(
-                    f"[rlm] load_library: already loaded {source_id} "
-                    f"(paths under {path_prefix}, context len={len(ctx)})"
-                )
-                return {
-                    "source": source,
-                    "source_id": source_id,
-                    "path_prefix": path_prefix,
-                    "files": 0,
-                    "chars": meta.get("chars"),
-                    "context_len": len(ctx),
-                    "already_loaded": True,
-                }
-
-        files = self._library_file_entries(payload, path_prefix)
+        if not isinstance(path_prefix, str):
+            path_prefix = f"ctx/{source_id}/"
+        # Empty path_prefix is valid (cwd seed) but add_context always sends a non-empty ctx/ prefix.
+        # Guard startsWith on empty prefix: "anything".startswith("") is always True.
+        check_prefix = path_prefix if path_prefix != "" else None
+
+        # Idempotent: already present if any path uses this prefix.
+        if check_prefix is not None:
+            for item in ctx:
+                if isinstance(item, dict) and str(item.get("path", "")).startswith(check_prefix):
+                    print(
+                        f"[rlm] add_context: already loaded {source_id} "
+                        f"(paths under {path_prefix}, context len={len(ctx)})"
+                    )
+                    return {
+                        "source": source,
+                        "source_id": source_id,
+                        "path_prefix": path_prefix,
+                        "files": 0,
+                        "chars": meta.get("chars"),
+                        "context_len": len(ctx),
+                        "already_loaded": True,
+                        "documents": 0,
+                        "converted": 0,
+                        "skipped": [],
+                    }
+
+        files = self._context_file_entries(payload, path_prefix)
         if not files:
-            return "Error: load_library produced no files"
+            return "Error: add_context produced no files"
 
         ctx.extend(files)
         # Keep restore payload in sync with the live list.
         self._context_payload = ctx
         self.ns["context"] = ctx
 
+        documents = meta.get("documents") if isinstance(meta.get("documents"), int) else 0
+        converted = meta.get("converted") if isinstance(meta.get("converted"), int) else 0
+        skipped = meta.get("skipped") if isinstance(meta.get("skipped"), list) else []
+        skip_n = len(skipped)
+        extra = ""
+        if documents or converted or skip_n:
+            extra = f"; documents={documents}, converted={converted}, skipped={skip_n}"
         print(
-            f"[rlm] load_library: +{len(files)} files into context "
-            f"(len={len(ctx)}); paths under {path_prefix}"
+            f"[rlm] add_context: +{len(files)} files into context "
+            f"(len={len(ctx)}); paths under {path_prefix}{extra}"
         )
         return {
             "source": source,
@@ -655,14 +672,17 @@ class Worker:
             "chars": meta.get("chars"),
             "context_len": len(ctx),
             "already_loaded": False,
+            "documents": documents,
+            "converted": converted,
+            "skipped": skipped,
         }
 
     @staticmethod
-    def _library_file_entries(payload: Any, path_prefix: str) -> list[dict[str, Any]]:
+    def _context_file_entries(payload: Any, path_prefix: str) -> list[dict[str, Any]]:
         """Normalize host payload to list[dict]. Host already namespaces; string is fallback."""
         if isinstance(payload, str):
             return [{
-                "path": f"{path_prefix}content",
+                "path": f"{path_prefix}content" if path_prefix else "content",
                 "content": payload,
                 "tokens": max(1, (len(payload) + 3) // 4),
             }]
@@ -684,10 +704,9 @@ class Worker:
         """Load the packed world into the single REPL variable `context`.
 
         `index` is accepted for protocol compatibility but ignored — there is only
-        one context slot. Libraries are merged on the host (or via load_library).
+        one context slot. Sources are merged on the host (or via add_context).
         """
-        with open(path, "r") as f:
-            payload = json.load(f) if is_json else f.read()
+        payload = read_host_payload(path, bool(is_json))
         self._context_payload = payload
         self.ns["context"] = payload
         # Drop legacy multi-slot names if present.

package/src/sandbox/sandbox-manager.ts

@@ -6,7 +6,7 @@
 
 import { PythonSandbox, type SubLlmHandlers } from "./sandbox.ts";
 import type { ReplResult } from "./protocol.ts";
-import { mergeLibraryIntoContext } from "../context/library-context.ts";
+import { mergeIntoContext } from "../context/merge.ts";
 
 /** Static configuration for sandbox creation — set once, reused across getOrCreate calls. */
 export interface SandboxManagerConfig {
@@ -28,23 +28,26 @@ export class SandboxManager {
   /** Serialized execution queue — concurrent repl() calls wait for predecessor. */
   private execQueue: Promise<void> = Promise.resolve();
   private pendingExecCount = 0;
-  /** Context payload to load on first sandbox creation. Set externally before getOrCreate. */
-  contextPayload: unknown = null;
+  /**
+   * Context payload to load on first sandbox creation. Starts as an empty list — context is
+   * empty by default; the first repl() seeds the cwd when autoSeedCwd is on.
+   */
+  contextPayload: unknown = [];
   /** True once contextPayload has been loaded into the sandbox (prevents reload + race fix). */
   private contextLoaded = false;
 
   constructor(private readonly config: SandboxManagerConfig) {}
 
   /**
-   * Append a library payload to the context this manager replays on death-recreate.
+   * Append a source payload to the context this manager replays on death-recreate.
    *
-   * The live worker has ALREADY appended it in-process (worker.py `_append_library`), so this
+   * The live worker has ALREADY appended it in-process (worker.py `_append_context`), so this
    * deliberately does not reload — it only keeps the host's replay copy truthful. Without it a
-   * recreate silently rolls the sandbox back to a repo-only context, and any child inheriting
-   * this payload would never see the library. Dedups by `lib/<id>/` prefix.
+   * recreate silently rolls the sandbox back to a pre-append context, and any child inheriting
+   * this payload would never see the source. Dedups by `ctx/<id>/` prefix.
    */
-  appendLibrary(payload: unknown): void {
-    this.contextPayload = mergeLibraryIntoContext(this.contextPayload, payload);
+  appendContext(payload: unknown): void {
+    this.contextPayload = mergeIntoContext(this.contextPayload, payload);
   }
 
   /**
@@ -52,15 +55,14 @@ export class SandboxManager {
    * given handlers. Subsequent calls return the existing sandbox immediately.
    * Deduplicates concurrent calls via initPromise.
    *
-   * If contextPayload is set, it is loaded before the sandbox is returned.
+   * If contextPayload is defined, it is loaded before the sandbox is returned.
    */
   async getOrCreate(handlers: Partial<SubLlmHandlers>): Promise<PythonSandbox> {
     if (this.disposed) throw new Error("SandboxManager disposed");
     if (this.sandbox) {
-      // RACE FIX: contextPayload may arrive after the sandbox was created (the
-      // "context" event's async packRepository resolves after the first repl() call).
-      // Load it into the live sandbox now if still pending.
-      if (this.contextPayload !== null && !this.contextLoaded) {
+      // RACE FIX: contextPayload may arrive after the sandbox was created (lazy seed
+      // resolves after the first getOrCreate). Load it into the live sandbox now if pending.
+      if (this.contextPayload !== undefined && !this.contextLoaded) {
         await this.sandbox.loadContext(this.contextPayload);
         this.contextLoaded = true;
       }
@@ -79,8 +81,8 @@ export class SandboxManager {
       awaitTimeoutS: this.config.awaitTimeoutS,
       handlers,
     }).then(async (s) => {
-      // Load context on first creation if available.
-      if (this.contextPayload !== null) {
+      // Load context on first creation if available (empty list is a valid starting value).
+      if (this.contextPayload !== undefined) {
         await s.loadContext(this.contextPayload);
         this.contextLoaded = true;
       }

package/src/sandbox/sandbox.ts

@@ -24,7 +24,7 @@ import { pinContext, type PinnedContext } from "./context-file.ts";
 import { REJECT, serviceInterrupt, type ReplyBody, type SubLlmHandlers } from "./interrupts.ts";
 import { trace, traceEnabled } from "../util/trace.ts";
 
-export type { LibraryLoadResult, SubcallOpts, SubLlmHandlers } from "./interrupts.ts";
+export type { AddContextResult, SubcallOpts, SubLlmHandlers } from "./interrupts.ts";
 
 export interface SandboxOptions {
   /** Sandbox recursion depth label (passed to the worker, used in interrupt routing). */
@@ -111,6 +111,11 @@ export class PythonSandbox {
     this.initTimeoutMs = opts.initTimeoutMs ?? 30_000;
     const python = opts.python ?? "python3";
     const workerArgs = [
+      // -X utf8=1: the scaffold states its own encoding explicitly (py/hostio.py), but MODEL
+      // code gets a real open() — guards.py exposes it deliberately — and on Windows that
+      // would default to cp1252 (issue #7). UTF-8 mode covers the whole interpreter; the
+      // scaffold's explicit encoding= still wins where PYTHONIOENCODING would override this.
+      "-X", "utf8=1",
       "-u", WORKER_PATH,
       "--depth", String(opts.depth ?? 1),
       "--timeout", String(opts.execTimeoutS ?? 600),
@@ -124,7 +129,9 @@ export class PythonSandbox {
     this.proc = spawn(
       python,
       workerArgs,
-      { stdio: ["pipe", "pipe", "pipe"], env: sanitizedEnv() },
+      // windowsHide: without it each sandbox flashes a console window on Windows (pi sets
+      // this on every spawn — bash.ts / shell.ts). Same Windows surface as issue #7.
+      { stdio: ["pipe", "pipe", "pipe"], env: sanitizedEnv(), windowsHide: true },
     ) as ChildProcessWithoutNullStreams;
 
     this.proc.stdout.setEncoding("utf8");