@hicaru/pi-rlm 0.2.0 → 0.2.2

package/README.md

@@ -58,7 +58,10 @@ sub-LLM calls, hence the name.
 
 - A **root orchestrator** model drives a **persistent Python REPL** turn-by-turn.
 - Long-context work is **delegated** to cheap worker models via `llm_query` / `llm_query_batched`.
-- Hard sub-problems **recurse** into child RLMs via `rlm_query` (depth-capped).
+- Hard sub-problems **recurse** into child RLMs via `rlm_query` (depth-capped). A child inherits
+  its parent's `context` — the repository plus every library loaded with `load_library()` — so it
+  runs the same retrieval primitives over the same paths. Inheritance costs no extra tokens: the
+  content lives in the sandbox, and only a size line reaches the model.
 - Everything runs **in-process** — the only external process is one local `python3` worker.
 
 > This is a Pi-plugin reimplementation of the RLM method (see the [RLM paper](https://arxiv.org/abs/2512.24601)).
@@ -94,9 +97,6 @@ sub-LLM calls, hence the name.
 | `/rlm` | `Ctrl+Shift+R` | Toggle persistent RLM mode (route plain prompts through the RLM engine) |
 | `/rlm-stop` | | Abort an in-progress run |
 | `/rlm-config` | | Pick smart + worker models and tune run settings |
-| `/rlm-resume` | | Resume an interrupted run (default `@latest`) |
-| `/rlm-runs` | | List recent runs |
-| `/rlm-help` | | Show the startup guide & cheatsheet |
 
 While a run is active, a **live tree** shows the root orchestrator and every sub-LLM /
 recursive child with status, model, cost, tokens, and duration. The final answer is posted
@@ -113,13 +113,9 @@ These functions are injected into the model's Python namespace inside the REPL:
 | `llm_query` | `(prompt, model=None) -> str` | One-shot sub-LLM call (worker model) |
 | `llm_query_batched` | `(prompts, model=None) -> list[str]` | Concurrent sub-LLM calls (pool-bounded) |
 | `llm_query_chunked` | `(text, prompt, model=None) -> list[str]` | Split large text into cap-sized chunks and fan out via sub-LLMs |
-| `rlm_query` | `(prompt, model=None) -> str` | Recursive child RLM with its own sandbox (depth-capped) |
-| `rlm_query_batched` | `(prompts, model=None) -> list[str]` | Concurrent recursive child RLMs |
-| `todo` | `(action, **kwargs) -> str` | Task list: `create`/`update`/`list`/`get`/`delete`/`clear` |
-| `ask_user_question` | `(questions) -> list[dict]` | Ask the user structured questions (depth 0 only) |
+| `rlm_query` | `(prompt, model=None, paths=None) -> str` | Recursive child RLM with its own sandbox (depth-capped). Inherits your `context`; `paths` narrows it by prefix |
+| `rlm_query_batched` | `(prompts, model=None, paths=None) -> list[str]` | Concurrent recursive child RLMs, sharing one `paths` slice |
 | `load_library` | `(source) -> dict \| str` | Append an external dir, file, or git URL into `context` under `lib/<id>/` |
-| `save_artifact` | `(kind, content) -> str` | Persist a stage artifact (`clarification` / `research` / `plan` / `validation`) under `.rlm/artifacts/` (root depth only). Returns preflight gate critique. |
-| `advance_phase` | `(phase, summary=None) -> str` | Advance one step in order `clarify → research → blueprint → validate` (clarify skipped when `askUserQuestion` is off). **Engine-gated** on the latest artifact + interview rounds. Rejected transitions return the gate error. |
 | `SHOW_VARS` | `() -> str` | List currently defined variables & their types |
 | `answer` | `dict` | Set `answer["content"]=...; answer["ready"]=True` to finalize |
 
@@ -139,21 +135,7 @@ lib = [f for f in context if f["path"].startswith(info["path_prefix"])]
 
 There is no `context_1` / `context_2` — only `context`. Paths are namespaced so multiple
 libraries do not collide. Toggle via `/rlm-config` → **Library loader** (`libraryLoader`,
-default on). On headless runs with persistence, each load writes a resume sidecar
-(`context.<N>.json`) that is **merged back into `context`** on resume.
-
-### Artifact-gated pipeline (opt-in via `pipeline: true`)
-
-When enabled at root depth:
-
-1. **Goal capture** — the brief is written verbatim to `.rlm/artifacts/goal/goal-<ts>.md` with a pre-run dirty-tree baseline.
-2. **Stages** — `clarify → research → blueprint → validate` (**read-only** — produces a validated plan; does not write code). Each produces a durable markdown artifact with frontmatter contracts; chat history is **reset** at every phase boundary (artifacts are the only channel; REPL vars persist).
-3. **Clarify (intake)** — interviews the user via `ask_user_question` (intent first, then evidence-confirmed decisions). Writes `.rlm/artifacts/clarifications/*` with `decisions_count` / `open_questions_count`. Engine gate: **≥1 serviced ask round** + artifact contract. When **`askUserQuestion` is off**, clarify is skipped and the run starts at research.
-4. **Gates (TypeScript, never LLM judgment)** — `status: ready`; clarify structure; plan `phases:` ≡ fence-aware `## Phase N:` headings; every `file:line` citation resolves; validate carries `blockers_count` + `verdict`. Preflight critique runs on every `save_artifact`.
-5. **Validate** — adversarial plan review against the tree (not a post-implementation diff check). Final answer is the validated plan.
-6. **Corrective loop** — `blockers_count > 0` re-enters blueprint (superseded plan kept for context), bounded by `maxBackwardJumps` (default 2).
-
-Native RLM mode authors file changes with Pi's native `edit` / `write` tools. Sub-LLMs extract and locate; they never ship code.
+default on). A library loaded at any point is inherited by every child spawned afterwards.
 
 ## Settings (`/rlm-config`)
 
@@ -164,26 +146,21 @@ Native RLM mode authors file changes with Pi's native `edit` / `write` tools. Su
 | Max recursion depth | `4` | `rlm_query` past this degrades to plain `llm_query` |
 | Max iterations | `30` | root REPL turns before RLM asks for a final answer |
 | REPL block timeout (s) | `120` | wall-clock limit for one Python REPL block (SIGALRM) |
-| Max concurrent sub-calls | `4` | concurrency pool size for `*_batched` |
-| Budget ceiling (USD) | none | total spend cap for the whole recursive tree |
+| Max concurrent sub-calls | `16` | concurrency pool size for `*_batched` |
+| Max concurrent children | `6` | concurrent `rlm_query` child engines per depth |
 | Wall-clock ceiling (min) | none | total runtime cap for the whole recursive tree |
 | Token ceiling | none | total input+output token cap for the whole recursive tree |
 | Max consecutive errors | `5` | stop after N consecutive failing turns (none = off) |
 | Orchestrator addendum | on | divide-and-conquer guidance in the root system prompt |
-| Phase pipeline | off | artifact-gated clarify→research→blueprint→validate (read-only plan pipeline) |
-| Max validate→blueprint loops | `2` | bounded corrective re-entries when validation reports blockers |
-| Ask user question | on | when pipeline is on, enables clarify intake; when off, pipeline starts at research |
 | Trajectory compaction | on (0.65) | summarize old turns when history nears the context window |
 | Root model output cap (tok) | `16384` | max output tokens per root-model turn |
 | Sandbox init timeout | `30000` ms | how long to wait for the Python worker to start |
-| `askUserQuestion` | on | expose `ask_user_question()` to the model |
-| `todo` | on | expose `todo()` to the model |
 | Library loader | on | expose `load_library()` for external dirs/files/git repos |
 
 > **Concurrency note:** each `rlm_query` child spawns its own `python3` worker (~50–150 ms
-> cold start). Worst-case concurrent interpreters ≈ `maxConcurrentSubcalls`^(depth−1); at
-> defaults (depth 4, conc 4) that's 4³ = 64 in the pathological case. Budget and error
-> caps (above) bound total spend regardless of fan-out.
+> cold start). Children are bounded separately (`maxConcurrentChildren`, default 6) because
+> each holds a full Python process and its own copy of the inherited context. Error and
+> wall-clock caps (above) still bound a runaway tree.
 
 ## Security
 

package/README.ru.md

@@ -34,6 +34,9 @@
 - **Модель-оркестратор** управляет постоянным Python REPL пошагово.
 - Работа с длинным контекстом **делегируется** дешевым worker-моделям через `llm_query` / `llm_query_batched`.
 - Сложные подзадачи **рекурсивно** передаются в дочерние RLM через `rlm_query` (с ограничением глубины).
+  Дочерний RLM наследует `context` родителя — репозиторий и все библиотеки, загруженные через
+  `load_library()`, — и работает с теми же путями. Наследование не стоит дополнительных токенов:
+  содержимое живёт в песочнице, модель видит только строку с размером.
 - Все работает **in-process** — единственным внешним процессом является локальный worker `python3`.
 
 > This is a Pi-plugin reimplementation of the RLM method (see the [RLM paper](https://arxiv.org/abs/2512.24601)).
@@ -54,7 +57,7 @@ pi process (TypeScript)
 
 - **Никаких серверов, сокетов или Docker.** Единственным внешним процессом является локальная песочница `python3`. Когда код в песочнице вызывает `llm_query`, worker пишет запрос в stdout и блокируется на stdin; Pi обрабатывает его внутри своего процесса и записывает ответ обратно. **API-ключи провайдеров никогда не попадают в песочницу.**
 - Песочница предоставляет `context`, `llm_query`, `llm_query_batched`, `rlm_query`,
-  `rlm_query_batched`, `SHOW_VARS()`, `todo()`, `ask_user_question()` и словарь `answer`.
+  `rlm_query_batched`, `SHOW_VARS()`, `ask_user_question()` и словарь `answer`.
   Модель отправляет окончательный результат, устанавливая `answer["ready"] = True`.
 
 ## Установка
@@ -91,9 +94,6 @@ rm -rf ~/.pi/agent/extensions/rlm
 | `/rlm` | `Ctrl+Shift+R` | Переключить постоянный режим RLM (направлять обычные промпты через движок RLM) |
 | `/rlm-stop` | | Прервать текущий запуск |
 | `/rlm-config` | | Выбрать smart- и worker-модели и настроить параметры запуска |
-| `/rlm-resume` | | Возобновить прерванный запуск (по умолчанию `@latest`) |
-| `/rlm-runs` | | Список последних запусков |
-| `/rlm-help` | | Показать руководство по запуску и шпаргалку |
 
 Пока запуск активен, **живое дерево** отображает корневой оркестратор и каждый sub-LLM / рекурсивный дочерний элемент со статусом, моделью, стоимостью, токенами и длительностью. Окончательный ответ публикуется в чате в формате markdown; любые правки кода собираются в виде диффов и проверяются через всплывающее окно (если не включен `yolo`).
 
@@ -107,9 +107,8 @@ rm -rf ~/.pi/agent/extensions/rlm
 | `llm_query` | `(prompt, model=None) -> str` | Одноразовый вызов sub-LLM (worker-модель) |
 | `llm_query_batched` | `(prompts, model=None) -> list[str]` | Параллельные вызовы sub-LLM (с ограничением пула) |
 | `llm_query_chunked` | `(text, prompt, model=None) -> list[str]` | Дробит большой текст на части по лимиту и обрабатывает через sub-LLM |
-| `rlm_query` | `(prompt, model=None) -> str` | Рекурсивный дочерний RLM со своей песочницей (с ограничением глубины) |
-| `rlm_query_batched` | `(prompts, model=None) -> list[str]` | Параллельные рекурсивные дочерние RLM |
-| `todo` | `(action, **kwargs) -> str` | Список задач: `create`/`update`/`list`/`get`/`delete`/`clear` |
+| `rlm_query` | `(prompt, model=None, paths=None) -> str` | Рекурсивный дочерний RLM со своей песочницей (с ограничением глубины). Наследует ваш `context`; `paths` сужает его по префиксу |
+| `rlm_query_batched` | `(prompts, model=None, paths=None) -> list[str]` | Параллельные рекурсивные дочерние RLM с общим срезом `paths` |
 | `ask_user_question` | `(questions) -> list[dict]` | Задать пользователю структурированные вопросы (только на глубине 0) |
 | `SHOW_VARS` | `() -> str` | Список текущих переменных и их типов |
 | `answer` | `dict` | Установите `answer["content"]=...; answer["ready"]=True` для завершения |
@@ -130,13 +129,11 @@ rm -rf ~/.pi/agent/extensions/rlm
 | Trajectory compaction | вкл (0.85) | суммаризация истории при приближении к лимиту окна контекста |
 | `yolo` | выкл | применять предлагаемые правки немедленно, пропуская окно подтверждения |
 | `askUserQuestion` | вкл | предоставить доступ к `ask_user_question()` для модели |
-| `todo` | вкл | предоставить доступ к `todo()` для модели |
 
 > **Примечание по параллелизму:** каждый дочерний `rlm_query` запускает собственного worker `python3` (~50–150 мс «холодного старта»). В худшем случае количество параллельных интерпретаторов ≈ `maxConcurrentSubcalls`^(depth−1); при настройках по умолчанию (глубина 4, параллелизм 4) это 4³ = 64 в патологическом случае. Лимиты бюджета и ошибок (см. выше) ограничивают общие затраты независимо от степени разветвления.
 
 ## Логи запусков
 
-- **Логи запусков** (`runLog`): включены по умолчанию. Каждый запуск записывает след в формате JSONL в `.rlm/runs/` (по умолчанию) с ограничением `maxRuns` (50). Поддерживает **снимки** (`sandbox.pkl`) и **возобновление** прерванных запусков через `/rlm-resume`. Снимки защищены сессионным `nonce` для предотвращения повторов между сессиями.
 
 ## Безопасность
 
@@ -150,21 +147,19 @@ rm -rf ~/.pi/agent/extensions/rlm
 
 ```
 src/
-  sandbox/    worker.py + JSONL stdio driver (PythonSandbox) · protocol.ts · sandbox-manager.ts
-  bridge/     model.ts (одноразовое завершение) · llm-query.ts · rlm-query.ts (рекурсия)
-  core/       engine.ts (цикл) · iteration · limits · answer · compaction · pipeline · types
-  prompts/    системные промпты и промпты для каждого шага (перенесены из Python-референса)
-  text/       парсинг (repl-блоки) · токены · превью · правки
-  state/      чтения/записи · возобновление · пути · строки
-  tool/       repl-tool · rlm-events · агрегатор · предложение-правок · emitter-listener
-  config/     значения по умолчанию · настройки (сохранение и валидация rlm.json)
-  context/    упаковка репозитория на базе repomix + кеширование
-  ui/         виджет-дерева · статус · выбор-модели · панель-конфигурации · вступление · тема
+  sandbox/    py/ (worker.py · guards · retrieval · tasks) · sandbox.ts · interrupts · protocol · sandbox-manager · context-file
+  bridge/     model.ts (single completion) · subcall-handlers.ts (the one llm/rlm impl) · ask-user · library
+  core/       engine.ts (the loop) · iteration · limits · resource-limits · answer · compaction · history · types
+  prompts/    glossary (shared REPL vocabulary) · system (headless) · native · user
+  text/       parsing (repl blocks) · tokens · preview
+  tool/       repl-tool · repl-result · repl-render · rlm-tool · rlm-events · rlm-aggregator · subcall-store · background-tasks
+  config/     defaults · settings (rlm.json persistence + validation)
+  context/    repomix repository packing + library context merge
+  ui/         status · model-picker · config-panel · intro · theme
   commands/   rlm · rlm-config
-  mode/       rlm-mode (контроллер) · маршрутизатор-ввода
-  patch/      применение · всплывающее-окно · индекс
-  util/       ошибки · параллелизм
-test/         фазы 1–9 · native-smoke · native-mode · помощники
+  mode/       rlm-mode (controller) · worker-model (cheapest pick) · native-guards
+  util/       errors · concurrency · trace
+test/         phase suites · native-smoke · native-mode · helpers
 ```
 
 ## Тесты

package/README.zh-CN.md

@@ -33,7 +33,9 @@
 
 - **根编排器**模型逐轮驱动一个**持久化的 Python REPL**。
 - 长上下文工作通过 `llm_query` / `llm_query_batched` **委派**给廉价的工作模型。
-- 困难的子问题通过 `rlm_query` **递归**到子 RLM 中（设有深度限制）。
+- 困难的子问题通过 `rlm_query` **递归**到子 RLM 中（设有深度限制）。子 RLM 继承父级的 `context`
+  ——仓库以及通过 `load_library()` 加载的所有库——因此可以在相同的路径上使用相同的检索原语。
+  继承不消耗额外的 token：内容存放在沙箱中，模型只看到一行大小信息。
 - 所有内容均**在进程内**运行 —— 唯一的外部进程是一个本地的 `python3` worker。
 
 > 这是 RLM 方法的 Pi 插件重新实现（参见 [RLM 论文](https://arxiv.org/abs/2512.24601)）。
@@ -56,7 +58,7 @@ pi 进程 (TypeScript)
   当沙箱代码调用 `llm_query` 时，worker 在 stdout 上写入请求并在 stdin 上阻塞；
   Pi 在进程内提供服务并将回复写回。**供应商 API 密钥绝不会进入沙箱。**
 - 沙箱公开了 `context`, `llm_query`, `llm_query_batched`, `rlm_query`,
-  `rlm_query_batched`, `SHOW_VARS()`, `todo()`, `ask_user_question()` 以及一个 `answer` 字典。
+  `rlm_query_batched`, `SHOW_VARS()`, `ask_user_question()` 以及一个 `answer` 字典。
   模型通过设置 `answer["ready"] = True` 来提交最终结果。
 
 ## 安装
@@ -96,9 +98,6 @@ rm -rf ~/.pi/agent/extensions/rlm
 | `/rlm` | `Ctrl+Shift+R` | 切换持久化 RLM 模式 (通过 RLM 引擎路由普通提示词) |
 | `/rlm-stop` | | 终止正在运行的任务 |
 | `/rlm-config` | | 选择 smart + worker 模型并调整运行设置 |
-| `/rlm-resume` | | 恢复被中断的任务 (默认 `@latest`) |
-| `/rlm-runs` | | 列出最近的任务 |
-| `/rlm-help` | | 显示启动指南和速查表 |
 
 在任务激活期间，一个**实时树**会显示根编排器和每个子 LLM /
 递归子节点的状态、模型、成本、token 和持续时间。最终答案将以 markdown 形式发布
@@ -114,9 +113,8 @@ rm -rf ~/.pi/agent/extensions/rlm
 | `llm_query` | `(prompt, model=None) -> str` | 单次子 LLM 调用 (worker 模型) |
 | `llm_query_batched` | `(prompts, model=None) -> list[str]` | 并发子 LLM 调用 (池上限) |
 | `llm_query_chunked` | `(text, prompt, model=None) -> list[str]` | 将大文本拆分为不超过上限的块并通过子 LLM 处理 |
-| `rlm_query` | `(prompt, model=None) -> str` | 具有自有沙箱的递归子 RLM (设有深度限制) |
-| `rlm_query_batched` | `(prompts, model=None) -> list[str]` | 并发递归子 RLM |
-| `todo` | `(action, **kwargs) -> str` | 任务列表：`create`/`update`/`list`/`get`/`delete`/`clear` |
+| `rlm_query` | `(prompt, model=None, paths=None) -> str` | 具有自有沙箱的递归子 RLM (设有深度限制)。继承父级的 `context`；`paths` 按前缀缩小范围 |
+| `rlm_query_batched` | `(prompts, model=None, paths=None) -> list[str]` | 并发递归子 RLM，共享同一个 `paths` 切片 |
 | `ask_user_question` | `(questions) -> list[dict]` | 向用户提出结构化问题 (仅限深度 0) |
 | `SHOW_VARS` | `() -> str` | 列出当前定义的变量及其类型 |
 | `answer` | `dict` | 设置 `answer["content"]=...; answer["ready"]=True` 以结束 |
@@ -137,7 +135,6 @@ rm -rf ~/.pi/agent/extensions/rlm
 | Trajectory compaction | on (0.85) | 当历史记录接近上下文窗口时进行总结 |
 | `yolo` | off | 立即应用建议的修改，跳过审核弹出窗 |
 | `askUserQuestion` | on | 向模型公开 `ask_user_question()` |
-| `todo` | on | 向模型公开 `todo()` |
 
 > **并发注意：** 每个 `rlm_query` 子节点都会启动自己的 `python3` worker (冷启动约 50–150 毫秒)。
 > 最坏情况下的并发解释器数量 ≈ `maxConcurrentSubcalls`^(depth−1)；在
@@ -146,12 +143,6 @@ rm -rf ~/.pi/agent/extensions/rlm
 
 ## 运行日志
 
-- **运行日志** (`runLog`)：默认始终开启。每次运行将 JSONL 轨迹写入 `.rlm/runs/`
-  (默认)，上限为 `maxRuns` (50)。支持通过 `/rlm-resume` 进行**快照** (`sandbox.pkl`) 和**恢复**
-  被中断的任务。快照受每个会话的 `nonce` 保护，以防止跨会话重放。
-
-## 安全性
-
 - **密钥隔离**：供应商密钥仅存在于 TypeScript (`AuthStorage`) 中；沙箱
   接收提示词并返回文本 —— 绝不接触密钥。
 - **环境清理**：在 worker 启动前会剥离敏感环境变量 (API 密钥, token)。
@@ -170,21 +161,19 @@ rm -rf ~/.pi/agent/extensions/rlm
 
 ```
 src/
-  sandbox/    worker.py + JSONL stdio driver (PythonSandbox) · protocol.ts · sandbox-manager.ts
-  bridge/     model.ts (one-shot completion) · llm-query.ts · rlm-query.ts (recursion)
-  core/       engine.ts (the loop) · iteration · limits · answer · compaction · pipeline · types
-  prompts/    system + per-turn prompts (ported from the Python reference)
-  text/       parsing (repl blocks) · tokens · preview · edits
-  state/      reads/writes · resume · paths · rows
-  tool/       repl-tool · rlm-events · aggregator · propose-edits · emitter-listener
+  sandbox/    py/ (worker.py · guards · retrieval · tasks) · sandbox.ts · interrupts · protocol · sandbox-manager · context-file
+  bridge/     model.ts (single completion) · subcall-handlers.ts (the one llm/rlm impl) · ask-user · library
+  core/       engine.ts (the loop) · iteration · limits · resource-limits · answer · compaction · history · types
+  prompts/    glossary (shared REPL vocabulary) · system (headless) · native · user
+  text/       parsing (repl blocks) · tokens · preview
+  tool/       repl-tool · repl-result · repl-render · rlm-tool · rlm-events · rlm-aggregator · subcall-store · background-tasks
   config/     defaults · settings (rlm.json persistence + validation)
-  context/    repomix-based repository packing + caching
-  ui/         tree-widget · status · model-picker · config-panel · intro · theme
+  context/    repomix repository packing + library context merge
+  ui/         status · model-picker · config-panel · intro · theme
   commands/   rlm · rlm-config
-  mode/       rlm-mode (controller) · input-router
-  patch/      apply · popup · index
-  util/       errors · concurrency
-test/         phase1–phase9 · native-smoke · native-mode · helpers
+  mode/       rlm-mode (controller) · worker-model (cheapest pick) · native-guards
+  util/       errors · concurrency · trace
+test/         phase suites · native-smoke · native-mode · helpers
 ```
 
 ## 测试

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hicaru/pi-rlm",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "type": "module",
   "description": "Save 99% tokens, Recursive Language Model (RLM) for the Pi",
   "license": "MIT",

package/src/bridge/library.ts

@@ -1,13 +1,11 @@
 /**
  * Shared load_library handler for headless engine and native repl() mode.
  *
- * Host packs the source via resolveLibrarySource (namespaced under lib/<id>/),
- * assigns a resume-sidecar index, and returns the payload for the worker to
- * append into the single `context` list.
+ * Host packs the source via resolveLibrarySource (namespaced under lib/<id>/) and returns the
+ * payload for the worker to append into the single `context` list.
  *
- * Idempotency is host-side: re-loading a source that was already packed does
- * not consume an index, write a sidecar, or re-clone/pack. That keeps resume
- * trails free of duplicate library slots.
+ * Idempotency is host-side: re-loading a source that was already packed does not re-clone or
+ * re-pack, and the prefix set is the only state that decides it.
  *
  * Late-bound deps (getCwd / getEmitter) keep a single handler closure correct
  * across native repl() calls — getOrCreate only installs handlers at spawn.
@@ -31,33 +29,67 @@ export interface LibraryBridgeOpts {
   readonly getEmitter?: () => RlmEmitter | null | undefined;
   readonly parentId?: string;
   readonly signal?: AbortSignal;
-  /** First resume-sidecar index (slot 0 = repo). Resume passes 1 + max restored. */
-  readonly startIndex: number;
+  /** Prefixes already present in context — seeds host-side idempotency after a sandbox restart. */
+  readonly loadedPrefixes?: readonly string[];
   /**
-   * Prefixes already present in context (e.g. restored from sidecars).
-   * Seeded so re-load after resume is still a no-op without re-packing.
+   * The live context this sandbox holds. Read to refuse pre-flight exactly what the worker's
+   * `_append_library` would reject, before any prefix is committed.
    */
-  readonly loadedPrefixes?: readonly string[];
-  /** Post-load hook — the engine writes the resume sidecar here; native mode omits it. */
-  readonly onLoaded?: (index: number, payload: unknown) => void | Promise<void>;
+  readonly getContext?: () => unknown;
+  /**
+   * Post-load hook. The engine grows its live context here; native mode grows
+   * SandboxManager.contextPayload.
+   */
+  readonly onLoaded?: (payload: unknown) => void | Promise<void>;
 }
 
 export interface LibraryHandlerBundle {
   readonly handlers: Pick<SubLlmHandlers, "loadLibrary">;
-  /** Reset the sidecar index counter (call when the sandbox is discarded and will re-spawn). */
-  readonly reset: () => void;
+  /**
+   * Reset the loaded-prefix cache (call when the sandbox is
+   * discarded and will re-spawn).
+   *
+   * `keep` re-seeds the cache from the payload that will be replayed into the fresh worker.
+   * `loaded` is a CACHE of `libraryPrefixesIn(context)`, never independent state, so it may only
+   * be cleared by re-deriving it — clearing it outright would make the host re-clone and re-pack
+   * a library the recreated worker already holds.
+   */
+  readonly reset: (keep?: readonly string[]) => void;
   /** Prefixes loaded in this sandbox lifetime (for tests). */
   readonly loadedPrefixes: () => ReadonlySet<string>;
 }
 
+/**
+ * JS runtime kind → the Python type name worker.py reports, so both sides emit exactly one
+ * message for the same refusal. Covers every shape a context payload can take after JSON
+ * transport; anything else is a plain object, which `json.load` materializes as a dict.
+ */
+const PY_TYPE_NAME: Readonly<Record<string, string>> = Object.freeze({
+  string: "str", boolean: "bool", number: "int", bigint: "int", undefined: "None",
+});
+
+function pythonKindOf(value: unknown): string {
+  if (value === null) return "None"; // matches worker.py's `if ctx is not None else "None"`
+  return PY_TYPE_NAME[typeof value] ?? "dict";
+}
+
+/**
+ * Refusal messages shared with worker.py `_append_library`. The worker is the backstop; the host
+ * pre-flights the same two conditions so it never commits a prefix for an append that
+ * will be rejected. Keep the wording identical — a comment in worker.py points back here.
+ */
+const LIST_CONTEXT_REQUIRED = (kind: string): string =>
+  `load_library requires list context (file bundle); got ${kind}`;
+const NO_FILES_PRODUCED = "load_library produced no files";
+
 export function buildLibraryHandler(opts: LibraryBridgeOpts): LibraryHandlerBundle {
-  let nextIndex = opts.startIndex;
   /** Prefixes already loaded in this sandbox — mirrors the worker's context state. */
   const loaded = new Set<string>(opts.loadedPrefixes ?? []);
   return {
-    reset: () => {
-      nextIndex = opts.startIndex;
+    reset: (keep) => {
+      const seed = keep ?? opts.loadedPrefixes ?? [];
       loaded.clear();
+      for (const prefix of seed) loaded.add(prefix);
     },
     loadedPrefixes: () => loaded,
     handlers: {
@@ -74,6 +106,13 @@ export function buildLibraryHandler(opts: LibraryBridgeOpts): LibraryHandlerBund
           depth,
         });
         try {
+          // Pre-flight the worker's own refusal: a non-list context cannot be appended to, and
+          // committing a prefix for it would make the NEXT load lie with already_loaded.
+          const current = opts.getContext?.();
+          if (current !== undefined && !Array.isArray(current)) {
+            throw new Error(LIST_CONTEXT_REQUIRED(pythonKindOf(current)));
+          }
+
           // Cheap pre-check BEFORE cloning/packing: same namespace ⇒ nothing to do.
           const { sourceId: preId, pathPrefix: prefix } = libraryNamespace(source, cwd);
           if (loaded.has(prefix)) {
@@ -84,10 +123,8 @@ export function buildLibraryHandler(opts: LibraryBridgeOpts): LibraryHandlerBund
                 resultPreview: `already loaded (${prefix}*)`,
               });
             }
-            // No index consumed, no sidecar written — resume stays consistent.
             return {
               payload: Object.freeze([]),
-              index: -1,
               files: 0,
               chars: 0,
               sourceId: preId,
@@ -99,6 +136,8 @@ export function buildLibraryHandler(opts: LibraryBridgeOpts): LibraryHandlerBund
           const resolved = await resolveLibrarySource(source, cwd, opts.signal);
           if (!resolved.ok) throw new Error(resolved.error);
           const { payload, files, chars, sourceId, pathPrefix } = resolved.value;
+          // The worker's other refusal, pre-flighted for the same reason.
+          if (payload.length === 0) throw new Error(NO_FILES_PRODUCED);
 
           // Race: another concurrent load of the same prefix finished while we packed.
           if (loaded.has(pathPrefix)) {
@@ -111,7 +150,6 @@ export function buildLibraryHandler(opts: LibraryBridgeOpts): LibraryHandlerBund
             }
             return {
               payload: Object.freeze([]),
-              index: -1,
               files: 0,
               chars: 0,
               sourceId,
@@ -120,12 +158,10 @@ export function buildLibraryHandler(opts: LibraryBridgeOpts): LibraryHandlerBund
             };
           }
 
-          // Increment only after a successful sidecar write (or when no hook is set).
-          const index = nextIndex;
+          // Mark loaded only after the host has grown its own copy of the context.
           if (opts.onLoaded) {
-            await opts.onLoaded(index, payload);
+            await opts.onLoaded(payload);
           }
-          nextIndex = index + 1;
           loaded.add(pathPrefix);
 
           if (id) {
@@ -138,7 +174,6 @@ export function buildLibraryHandler(opts: LibraryBridgeOpts): LibraryHandlerBund
           }
           return {
             payload,
-            index,
             files,
             chars,
             sourceId,