monkeybot 3.12.0__tar.gz → 3.13.0__tar.gz

{monkeybot-3.12.0 → monkeybot-3.13.0}/CHANGELOG.md

@@ -6,6 +6,22 @@ the project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [core v3.13.0] - 2026-11-01
+
+### Added
+
+- `task` accepts `background: true`. The child keeps running after the turn ends. `await_task` and `kill_task` read or stop it. A finished child wakes the parent with a `[harness]` follow-up while the session is idle. `MONKEYBOT_TASK_QUEUE` and the subagent worker pool are removed.
+- `write_file`, `replace_in_file`, and `apply_patch` emit a `FileChange` and keep a before/after snapshot under `.monkeybot/changes/{session}` so a client can review the diff and undo. Undo refuses a file that changed since the edit or a snapshot that was too large to keep, and the next turn is told which paths were restored.
+
+### Changed
+
+- Tool input and output, tool errors, completions, and turn I/O are no longer clipped at 8 KB in traces or at 4 KB in the SQLite trace DB. Each attribute is capped at 1 MiB instead. The history prompt stays at 8 KB. Full tool I/O now reaches OTLP backends, so redact at the collector. The SQLite DB no longer stores the `langfuse.*` mirror keys. The OTLP and SQLite exporters send 8 spans per request (override OTLP with a positive integer `OTEL_BSP_MAX_EXPORT_BATCH_SIZE`; any other value keeps 8).
+
+### Fixed
+
+- A UI-only row between a tool call and its result no longer makes the provider see two results for that call. Bedrock rejected the turn when the counts did not match. Stored history is unchanged.
+- `list_skills` advertises the workspace `skills/` mount instead of the host skills directory. `run_command` paths under `skills/` stay inside that root, so opening a skill file no longer asks for approval.
+
 ## [core v3.12.0] - 2026-10-29
 
 ### Added

{monkeybot-3.12.0 → monkeybot-3.13.0}/CONTRIBUTING.md

@@ -4,7 +4,7 @@ Thanks for helping improve monkeybot. Report bugs and doc gaps via [issues](http
 
 ## Developing the harness
 
-Clone only if you are changing monkeybot itself (end users should use `uv tool install monkeybot-cli` — see the [README](README.md)):
+Clone only if you are changing monkeybot itself (end users should install with the Pillow override — see the [README](README.md)):
 
 ```bash
 git clone https://github.com/human-plus-machine/monkeybot.git

{monkeybot-3.12.0 → monkeybot-3.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: monkeybot
-Version: 3.12.0
+Version: 3.13.0
 Summary: monkeybot agent harness — FastAPI SSE gateway, owned loop, SQLite, and MCP.
 License: MIT
 License-File: LICENSE
@@ -120,7 +120,11 @@ Docs and examples are **GCP-first** (Vertex, GCS, Cloud Run); AWS paths ship in
 Install [uv](https://docs.astral.sh/uv/), then:
 
 ```bash
-uv tool install monkeybot-cli
+# browser-harness pins Pillow 12. Core 3.12 needs Pillow 13, and
+# `uv tool install` ignores the package override unless this file is passed.
+# Without it the resolver stays on core 3.10.0.
+printf 'pillow>=13\n' > /tmp/monkeybot-overrides.txt
+uv tool install --overrides /tmp/monkeybot-overrides.txt monkeybot-cli
 
 monkeybot new --dest ./my-agent --provider openai --yes
 cd my-agent
@@ -130,7 +134,7 @@ monkeybot doctor
 monkeybot chat
 ```
 
-Upgrade the CLI with `uv tool upgrade monkeybot-cli`. Full walkthrough: **[Getting Started](docs/getting-started.md)**.
+Upgrade the CLI with the same override: `uv tool install --reinstall --overrides /tmp/monkeybot-overrides.txt monkeybot-cli`. Full walkthrough: **[Getting Started](docs/getting-started.md)**.
 
 ## What you get
 

{monkeybot-3.12.0 → monkeybot-3.13.0}/README.md

@@ -23,7 +23,11 @@ Docs and examples are **GCP-first** (Vertex, GCS, Cloud Run); AWS paths ship in
 Install [uv](https://docs.astral.sh/uv/), then:
 
 ```bash
-uv tool install monkeybot-cli
+# browser-harness pins Pillow 12. Core 3.12 needs Pillow 13, and
+# `uv tool install` ignores the package override unless this file is passed.
+# Without it the resolver stays on core 3.10.0.
+printf 'pillow>=13\n' > /tmp/monkeybot-overrides.txt
+uv tool install --overrides /tmp/monkeybot-overrides.txt monkeybot-cli
 
 monkeybot new --dest ./my-agent --provider openai --yes
 cd my-agent
@@ -33,7 +37,7 @@ monkeybot doctor
 monkeybot chat
 ```
 
-Upgrade the CLI with `uv tool upgrade monkeybot-cli`. Full walkthrough: **[Getting Started](docs/getting-started.md)**.
+Upgrade the CLI with the same override: `uv tool install --reinstall --overrides /tmp/monkeybot-overrides.txt monkeybot-cli`. Full walkthrough: **[Getting Started](docs/getting-started.md)**.
 
 ## What you get
 

{monkeybot-3.12.0 → monkeybot-3.13.0}/cli/skills/monkeybot/SKILL.md

@@ -31,11 +31,15 @@ Tell the user what you're installing and why. On macOS/Linux you can run these y
 ### 2. Install the global CLI
 
 ```bash
-uv tool install monkeybot-cli
+# browser-harness pins Pillow 12. Core 3.12 needs Pillow 13, and
+# `uv tool install` ignores the package override unless this file is passed.
+# Without it the resolver stays on core 3.10.0.
+printf 'pillow>=13\n' > /tmp/monkeybot-overrides.txt
+uv tool install --overrides /tmp/monkeybot-overrides.txt monkeybot-cli
 monkeybot --help
 ```
 
-Upgrade later with `uv tool upgrade monkeybot-cli`.
+Upgrade later with `uv tool install --reinstall --overrides /tmp/monkeybot-overrides.txt monkeybot-cli`.
 
 **Do not** tell day-1 users to clone `human-plus-machine/monkeybot` unless they are contributing to the harness itself (see Contributing below).
 
@@ -47,7 +51,7 @@ If the user arrived via skills.sh:
 npx skills add human-plus-machine/monkeybot --skill monkeybot
 ```
 
-…they have **this skill only**. Walk them through Tier 0: install `uv` → `uv tool install monkeybot-cli` → verify `monkeybot --help`. Then continue to Tier 1.
+…they have **this skill only**. Walk them through Tier 0: install `uv` → `uv tool install --overrides /tmp/monkeybot-overrides.txt monkeybot-cli` (write `pillow>=13` into that file first) → verify `monkeybot --help`. Then continue to Tier 1.
 
 ## How config works (tell the user this first)
 
@@ -115,7 +119,7 @@ uv sync
 | `ollama-local` | None required — `OLLAMA_BASE_URL` (default `http://localhost:11434`). Requests send `keep_alive` 24h so prefix KV cache survives idle. | `monkeybot[ollama]` |
 | `ollama` | Legacy auto-route (key + blank URL = cloud; explicit URL wins) | `monkeybot[ollama]` |
 
-**Agent-first dependencies.** The CLI is thin — it does **not** install provider/storage extras globally. `monkeybot new` scaffolds a `pyproject.toml` with the selected provider (and any `--with` extras). Run plain `uv sync` in the agent directory. `monkeybot run` / `chat` spawn the gateway from that project's interpreter (`.venv/bin/python`, else `uv run python`), and `doctor` checks extras in that same interpreter. For a config-only tree (just `monkeybot_config/`, no `pyproject.toml`) the gateway uses the CLI's interpreter when it already has MonkeyBot 3.x (and MemPalace if memory is on). If memory is enabled and that interpreter cannot import MemPalace, `run` / `chat` provision a cached CLI-managed venv under `~/.cache/monkeybot/runtimes/` holding `monkeybot[memory]` pinned to the running core (never rewrites a `pyproject.toml`). `doctor` reuses that cache when it is already present. Otherwise extras must be installed in the CLI env (`uv tool install --with 'monkeybot[<extra>]' monkeybot-cli`).
+**Agent-first dependencies.** The CLI is thin — it does **not** install provider/storage extras globally. `monkeybot new` scaffolds a `pyproject.toml` with the selected provider (and any `--with` extras). Run plain `uv sync` in the agent directory. `monkeybot run` / `chat` spawn the gateway from that project's interpreter (`.venv/bin/python`, else `uv run python`), and `doctor` checks extras in that same interpreter. For a config-only tree (just `monkeybot_config/`, no `pyproject.toml`) the gateway uses the CLI's interpreter when it already has MonkeyBot 3.x (and MemPalace if memory is on). If memory is enabled and that interpreter cannot import MemPalace, `run` / `chat` provision a cached CLI-managed venv under `~/.cache/monkeybot/runtimes/` holding `monkeybot[memory]` pinned to the running core (never rewrites a `pyproject.toml`). `doctor` reuses that cache when it is already present. Otherwise extras must be installed in the CLI env (`uv tool install --reinstall --overrides /tmp/monkeybot-overrides.txt --with 'monkeybot[<extra>]' monkeybot-cli`, with `pillow>=13` in that file). A bare `uv tool install` resolves core 3.10.0.
 
 `doctor` is the source of truth for credentials and extras — when in doubt, run it and read the `remediation` field (add `monkeybot[<extra>]` to agent deps + `uv sync`).
 

{monkeybot-3.12.0 → monkeybot-3.13.0}/cli/src/monkeybot_cli/chat_session.py

@@ -241,6 +241,8 @@ class ChatSessionController:
         self._reconnecting = False
         self._last_event_id: int | None = None
         self._abandoned: deque[str] = deque(maxlen=64)
+        self._deferred: list[Any] = []
+        self._idle_task: asyncio.Task[None] | None = None
         self._turn_abort = asyncio.Event()
         self._active_request_id: str | None = None
         self._hitl_future: asyncio.Future[HitlAnswer] | None = None
@@ -292,6 +294,7 @@ class ChatSessionController:
         self._reconnecting = False
         self._last_event_id = None
         self._stream_task = asyncio.create_task(self._consume_stream())
+        self._start_idle_watch()
         self._emit("session_ready", session_id=self.session_id)
         self._emit("connection_state", state="connected")
         await self._emit_transcript_backfill()
@@ -504,6 +507,14 @@ class ChatSessionController:
             return
 
         request_id = str(uuid.uuid4())
+        if self._active_request_id is not None:
+            self._emit("session_busy")
+            return
+        await self._stop_idle_watch()
+        if self._active_request_id is not None:
+            self._emit("session_busy")
+            self._start_idle_watch()
+            return
         self._active_request_id = request_id
         self._last_cancel_ok = None
         self._turn_abort.clear()
@@ -513,15 +524,23 @@ class ChatSessionController:
                 json={"request_id": request_id, "message": message},
             )
             if reply.status_code == 409:
+                self._active_request_id = None
                 self._emit("session_busy")
+                self._start_idle_watch()
                 return
             reply.raise_for_status()
         except httpx.HTTPError as exc:
+            self._active_request_id = None
             self._emit("error", message=format_http_error("Reply", exc))
+            self._start_idle_watch()
             return
 
         self._emit("turn_started", request_id=request_id)
-        await self._run_turn(request_id)
+        try:
+            await self._run_turn(request_id)
+        finally:
+            if self._active_request_id is None and not self._closed:
+                self._start_idle_watch()
 
     async def _dequeue_payload(self) -> str | None | Literal[False]:
         """Return payload, None for stream end, False on poll timeout."""
@@ -544,9 +563,13 @@ class ChatSessionController:
             self._warn(f"skipping unparseable event: {exc}")
             return None
 
-    async def _run_turn(self, request_id: str) -> None:
+    async def _run_turn(self, request_id: str, *, prelude: list[Any] | None = None) -> None:
         assert self._client is not None and self.session_id is not None
         state = _TurnState()
+        for evt in prelude or []:
+            if state.done or self._turn_abort.is_set():
+                break
+            await self._dispatch_turn_event(evt, request_id, state)
         while not state.done and not self._turn_abort.is_set():
             payload = await self._dequeue_payload()
             if payload is False:
@@ -577,6 +600,71 @@ class ChatSessionController:
         if not self._stream_alive and not self._reconnecting:
             self._emit("stream_ended")
 
+    def _start_idle_watch(self) -> None:
+        """Render turns the gateway starts while the prompt is idle."""
+        if self._closed or self._active_request_id is not None:
+            return
+        task = self._idle_task
+        if task is not None and not task.done():
+            return
+        self._idle_task = asyncio.create_task(self._watch_idle(), name="chat-idle-watch")
+
+    async def _stop_idle_watch(self) -> None:
+        task = self._idle_task
+        if task is None or task.done():
+            self._idle_task = None
+            return
+        if self._active_request_id is not None:
+            return
+        task.cancel()
+        with contextlib.suppress(asyncio.CancelledError):
+            await task
+        self._idle_task = None
+
+    async def _watch_idle(self) -> None:
+        """Show a background-subagent wake (or any other turn) the user did not send."""
+        try:
+            while not self._closed and self._active_request_id is None:
+                await self._play_deferred()
+                if self._closed or self._active_request_id is not None:
+                    return
+                payload = await self._dequeue_payload()
+                if payload is False:
+                    continue
+                if payload is None:
+                    return
+                if self._active_request_id is not None:
+                    self._event_queue.put_nowait(payload)
+                    return
+                evt = self._decode_event(payload)
+                if evt is None:
+                    continue
+                rid = getattr(evt, "request_id", "") or ""
+                if not rid or rid in self._abandoned:
+                    continue
+                self._deferred.append(evt)
+        except asyncio.CancelledError:
+            raise
+
+    async def _play_deferred(self) -> None:
+        while self._deferred and not self._closed and self._active_request_id is None:
+            first = self._deferred.pop(0)
+            rid = getattr(first, "request_id", "") or ""
+            if not rid or rid in self._abandoned:
+                continue
+            batch = [first]
+            rest: list[Any] = []
+            for evt in self._deferred:
+                if getattr(evt, "request_id", "") == rid:
+                    batch.append(evt)
+                else:
+                    rest.append(evt)
+            self._deferred = rest
+            self._active_request_id = rid
+            self._turn_abort.clear()
+            self._emit("turn_started", request_id=rid)
+            await self._run_turn(rid, prelude=batch)
+
     async def _dispatch_turn_event(self, evt: Any, request_id: str, state: _TurnState) -> None:
         evt_rid = getattr(evt, "request_id", "") or ""
 
@@ -589,8 +677,9 @@ class ChatSessionController:
                 self._emit("thinking", text="thinking…")
             return
 
-        if evt_rid != request_id:
-            self._maybe_thinking_trace(evt, request_id)
+        if evt_rid and evt_rid != request_id:
+            if evt_rid not in self._abandoned:
+                self._deferred.append(evt)
             return
 
         if isinstance(evt, GroundingEvent):
@@ -885,6 +974,7 @@ class ChatSessionController:
         if self._active_request_id is not None:
             self._abandoned.append(self._active_request_id)
         self._active_request_id = None
+        await self._stop_idle_watch()
 
         if self._stream_task is not None:
             self._stream_task.cancel()
@@ -913,6 +1003,7 @@ class ChatSessionController:
         await self._teardown_stream()
         await self._create_session()
         self._stream_task = asyncio.create_task(self._consume_stream())
+        self._start_idle_watch()
         self._emit("session_ready", session_id=self.session_id)
         self._emit("connection_state", state="connected")
 
@@ -926,6 +1017,7 @@ class ChatSessionController:
         await self._teardown_stream()
         await self._attach_or_create_session(sid)
         self._stream_task = asyncio.create_task(self._consume_stream())
+        self._start_idle_watch()
         self._emit("session_ready", session_id=self.session_id)
         self._emit("connection_state", state="connected")
         await self._emit_transcript_backfill()
@@ -942,6 +1034,11 @@ class ChatSessionController:
         if self._closed:
             return
         self._closed = True
+        if self._idle_task is not None:
+            self._idle_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError, asyncio.TimeoutError, TimeoutError):
+                await asyncio.wait_for(self._idle_task, timeout=0.5)
+            self._idle_task = None
         if self._stream_task is not None:
             self._stream_task.cancel()
             with contextlib.suppress(asyncio.CancelledError, asyncio.TimeoutError, TimeoutError):

{monkeybot-3.12.0 → monkeybot-3.13.0}/cli/src/monkeybot_cli/commands/doctor.py

@@ -70,6 +70,16 @@ def _agent_defines_project_extra(agent_root: Path, extra: str) -> bool:
     return isinstance(optional, dict) and extra in optional
 
 
+def _cli_overrides_file() -> Path:
+    """Pillow floor shipped next to this package.
+
+    ``uv tool install`` does not read ``[tool.uv] override-dependencies``.
+    browser-harness pins Pillow 12, so a bare install resolves core 3.10
+    instead of a core that requires Pillow 13.
+    """
+    return Path(__file__).resolve().parents[1] / "overrides.txt"
+
+
 def _extra_remediation(extra: str, agent_root: Path, runtime) -> str:
     """Remediation text pointing at the agent project, not the CLI env."""
     if runtime.source in {"cli", MANAGED_RUNTIME_SOURCE}:
@@ -78,9 +88,11 @@ def _extra_remediation(extra: str, agent_root: Path, runtime) -> str:
             if runtime.source == MANAGED_RUNTIME_SOURCE
             else ""
         )
+        overrides = _cli_overrides_file()
         return (
             "Config-only tree: install in the CLI env — "
-            f"uv tool install --with 'monkeybot[{extra}]' monkeybot-cli"
+            f"uv tool install --reinstall --overrides {overrides} "
+            f"--with 'monkeybot[{extra}]' monkeybot-cli"
             f"{refresh}"
         )
     if _agent_defines_project_extra(agent_root, extra):

{monkeybot-3.12.0 → monkeybot-3.13.0}/cli/src/monkeybot_cli/scaffold_defaults/image-generator/SKILL.md

@@ -39,7 +39,7 @@ workspace-relative.
 }
 ```
 
-Replace `<skills_path>` with the absolute `skills_path` returned by `list_skills`.
+Replace `<skills_path>` with the `skills_path` returned by `list_skills` (`skills`).
 
 Supported `--aspect-ratio` values: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`.
 

{monkeybot-3.12.0 → monkeybot-3.13.0}/cli/tests/test_chat_session.py

@@ -448,3 +448,27 @@ def test_close_deletes_session_and_captures_report_dir() -> None:
         assert client.delete.await_count == 1
 
     asyncio.run(_run())
+
+
+def test_idle_watch_shows_a_turn_the_user_did_not_send() -> None:
+    async def _run() -> None:
+        events: list[ChatUiEvent] = []
+        controller = ChatSessionController(base="http://localhost:8080", emit=events.append)
+        controller.session_id = "s"
+        controller._client = object()  # type: ignore[assignment]
+        controller._event_queue.put_nowait(
+            '{"type":"AssistantDelta","request_id":"wake-1","delta":"survey"}'
+        )
+        controller._event_queue.put_nowait('{"type":"TurnComplete","request_id":"wake-1"}')
+        controller._start_idle_watch()
+        for _ in range(40):
+            if any(event.kind == "turn_complete" for event in events):
+                break
+            await asyncio.sleep(0.05)
+        await controller._stop_idle_watch()
+        deltas = [event.payload.get("delta") for event in events if event.kind == "assistant_delta"]
+        assert deltas == ["survey"]
+        assert any(event.kind == "turn_complete" for event in events)
+        assert any(event.kind == "turn_started" for event in events)
+
+    asyncio.run(_run())

{monkeybot-3.12.0 → monkeybot-3.13.0}/cli/tests/test_doctor.py

@@ -46,14 +46,18 @@ def test_extra_remediation_keeps_extra_for_project_optionals(tmp_path: Path) ->
 def test_extra_remediation_config_only_cli_env(tmp_path: Path) -> None:
     runtime = SimpleNamespace(source="cli")
     text = _extra_remediation("bedrock", tmp_path, runtime)
-    assert "uv tool install --with 'monkeybot[bedrock]' monkeybot-cli" in text
+    assert "--overrides " in text
+    assert "overrides.txt" in text
+    assert "--with 'monkeybot[bedrock]' monkeybot-cli" in text
     assert "refresh the managed runtime" not in text
 
 
 def test_extra_remediation_config_only_managed_runtime(tmp_path: Path) -> None:
     runtime = SimpleNamespace(source="cli-managed")
     text = _extra_remediation("openai", tmp_path, runtime)
-    assert "uv tool install --with 'monkeybot[openai]' monkeybot-cli" in text
+    assert "--overrides " in text
+    assert "overrides.txt" in text
+    assert "--with 'monkeybot[openai]' monkeybot-cli" in text
     assert "refresh the managed runtime" in text
 
 

{monkeybot-3.12.0 → monkeybot-3.13.0}/docs/cloud-deployment-design.md

@@ -87,10 +87,6 @@ managed `DB_URL` and `MEMORY_STORAGE_URI` for state that must survive recycling.
 
 When several gateway or worker processes share one `DB_URL`, conversation isolation is by `thread_id`; subagent run isolation is by `run_id`.
 
-For **queued subagent work** (`MONKEYBOT_TASK_QUEUE=1`), workers poll `pending_runs()` and `claim(run_id, worker_id)`. Stale claims use `MONKEYBOT_WORKER_STALE_CLAIM_MS` (default 10 minutes). See [Features — durable subagent runs](features.md#14-durable-subagent-runs-task-queue) for worker env vars.
-
-- **Production:** standalone `python -m monkeybot.subagents.worker` alongside the gateway (separate event loop; share state via `DB_URL`).
-- **Development only:** `MONKEYBOT_WORKER_POOL=1` co-locates a worker in the gateway process — do not use in production.
-- **SQLite:** single-process / local only. **Postgres / Firestore:** multi-process worker pools.
+Background subagents run inside the gateway process that owns the session. There is no separate worker pool and no `MONKEYBOT_TASK_QUEUE`. A `running` row carries this process's owner id and a lease. On startup, rows whose owner is a dead process on this host are marked failed. Another host's rows are left alone, so a session must stay pinned to one gateway. See [Features — durable subagent runs](features.md#13-durable-subagent-runs-runstore-lease).
 
 Handle `StorageBackend` open/close in every entry point (gateway lifespan, FaaS cold start, AgentCore handler).

{monkeybot-3.12.0 → monkeybot-3.13.0}/docs/deploy-pattern-d-realtime.md

@@ -99,7 +99,8 @@ Install the unified CLI (`monkeybot-cli` in `cli/`) plus harness extras for talk
 #   monkeybot[cli-realtime]   — audio talk (requires PortAudio)
 
 # Global CLI on PATH
-uv tool install monkeybot-cli
+printf 'pillow>=13\n' > /tmp/monkeybot-overrides.txt
+uv tool install --overrides /tmp/monkeybot-overrides.txt monkeybot-cli
 
 # Harness contributors only (editable checkout):
 #   uv sync --extra cli            # or cli-realtime

{monkeybot-3.12.0 → monkeybot-3.13.0}/docs/features.md

@@ -149,7 +149,7 @@ Each section follows: **Purpose** · **Key files** · **How it works** · **Depe
 - Consecutive `task` tools and consecutive `parallel_safe` tools in one batch run **in parallel** (capped; default 10); mutating / unmarked tools run as **serial chunks**.
 - One user `Message` per model tool-call turn — all `ToolResponse` blocks grouped together (required for Gemini replay).
 - Final assistant history write is backgrounded but **awaited at turn tail** before freeze/reset.
-- `transform_context()` (tool-integrity repair + UI-block strip) runs on every `history.load()` (in-memory only, never persisted); `convert_to_provider()` resolves attachments / pressure-shapes for the provider view.
+- `transform_context()` strips UI-only blocks, then repairs tool pairs, on every `history.load()` (in-memory only, never persisted); `convert_to_provider()` resolves attachments / pressure-shapes for the provider view.
 
 **Depends on:** Provider, HistoryStore, ToolExecutorPort, inspectors, optional hooks/curator/attachments.
 
@@ -164,7 +164,7 @@ Each section follows: **Purpose** · **Key files** · **How it works** · **Depe
 - **Settlement barrier:** `PRE_TOOL` is awaited before execute; fire-and-forget hooks are drained (bounded by `MONKEYBOT_HOOK_SETTLEMENT_TIMEOUT_S`, default 2s) before the next provider call and before `TurnComplete` (`run()` finally). Settlement does **not** wait on SSE client ACKs (avoids deadlock).
 - **Parallel-safe tools:** `ToolDef.parallel_safe=True` for read-only core tools (`read_file`, `glob`, `grep`, `search_memory`, `list_skills`, `loop_status`, `load_file`). Mutating tools (`write_file`, `replace_in_file`, `apply_patch`, …) stay serial. MCP tools default serial. Results always append in `call_id` order.
 - **Context Epoch:** At each safe provider-turn boundary the harness reconciles stable vs volatile system-context sources. The leading system message keeps an immutable epoch baseline (cache prefix). Volatile changes emit a chronological mid-conversation update (user-role, not persisted) and a `SystemContextUpdated` event. Compaction / stable-source change opens a new epoch (`ContextEpochStarted`).
-- **Message pipeline:** `history → transform_context() → convert_to_provider() → Provider.stream`. Transform repairs tool integrity and strips UI-only blocks; convert resolves attachments and applies pressure shaping without mutating persisted history.
+- **Message pipeline:** `history → transform_context() → convert_to_provider() → Provider.stream`. Transform strips UI-only blocks, then repairs tool pairs on that provider-shaped list; convert resolves attachments and applies pressure shaping without mutating persisted history.
 - **Streaming grammar (additive):** `AssistantTextStarted` / `AssistantTextEnded`, `ThinkingBlockStarted`, and `ToolInputDelta` supplement existing `AssistantDelta` / `ThinkingBlockDelta` / `ToolCallStarted`. Clients may ignore the new events.
 
 ---
@@ -294,6 +294,7 @@ Each section follows: **Purpose** · **Key files** · **How it works** · **Depe
 - `skills/...` paths resolve only below the read-only skills root; all other relative paths resolve only below `workspace_root`.
 - Writes, edits, and patches reject `skills/...`; real-path checks reject symlink escapes from either root.
 - `apply_patch` validates all hunks before writing; a mid-apply failure rolls back completed ops in reverse order.
+- `write_file`, `replace_in_file`, and `apply_patch` snapshot the before/after bytes under `.monkeybot/changes/{session}/` and emit `FileChange` (path, action, line stats; bodies stay off the wire). Undo restores the earliest pre-image in the selection. It refuses a file that no longer matches the recorded result, and a snapshot that was too large to keep. A parent session lists and deletes the `subagent:{session}:*` copies with its own.
 - Soft spill: large tool results always write the full payload to `.monkeybot/spill/{session_id}/` (and `.monkeybot/spill/subagent:{session_id}:*/` for task subagents) and keep a window-derived inline body in history when headroom allows; cleaned concurrently on session end. Budgets derive from `model.context_window` (no spill YAML/env knobs). Reported `read_file` line metadata is always truthful (`next_offset` when truncated).
 - `run_command` output over the spill threshold is never inlined as a raw-JSON prefix: the result stays valid JSON with `ok`, `exit_code`, `stdout_head`, `stdout_tail`, `stderr_tail`, `stdout_chars`/`stderr_chars` and `output_path` (full streams under `.monkeybot/spill/`). It is in `_SPILL_SKIP_TOOLS` because it self-spills.
 - `run_command` accepts `./…` and workspace-absolute path arguments (the agent's own tree); `../memory` and symlink escapes stay outside. `bash|sh|zsh -c "…"` scripts are split on shell operators and each command is checked against `deny_patterns` (anchored patterns like `^rm\s+-rf` used to miss them).
@@ -475,47 +476,41 @@ pricing:
 
 ### 12. Subagents (`task` tool)
 
-**Purpose:** Delegate work to isolated subprocess with same workspace/memory/MCP.
+**Purpose:** Delegate work to an isolated subprocess with the same workspace, memory, and MCP.
 
-**Key files:** `core/subagents/subagent_proto.py`, `subagent_worker.py`, `monkeybot.yaml` `subagents.personas`
+**Key files:** `core/subagents/subagent_proto.py`, `subagent_worker.py`, `core/subagents/supervisor.py`, `monkeybot.yaml` `subagents.personas`
 
 **How it works:**
 - Parent passes `subagent_type` to select a named persona from `monkeybot.yaml`.
-- Subagent uses separate `AGENT.md` per type.
-- Returns JSON (summary, errors, usage).
+- Omit `background` to wait for the result in this turn.
+- `background: true` returns immediately with `{status: "running", run_id, child_thread_id}`. The child keeps running after the turn ends. Read it back with `await_task`; stop it with `kill_task`.
+- A session may run `subagents.max_background` background children at once (default 4). Stop on a later turn does not kill them. Deleting the session does.
+- A child starts with the folders and commands this session has already approved. It cannot raise its own access prompt. Durable "Always allow" grants in `grants.json` still apply.
+- When a background child finishes while the session is idle, the harness starts one follow-up turn whose text begins with `[harness]`. That turn is not human intent and is not written to memory.
 
 **Invariants:**
 - No nested `task` inside subagents.
-- Max 10 parallel `task` calls per batch.
-- `subagents.max_turns` / `subagents.timeout_sec` YAML limits apply.
-- Parent reads child NDJSON with a raised StreamReader limit (`SUBAGENT_STDOUT_LINE_LIMIT`, 16 MiB) — not asyncio’s default 64 KiB — so large `SystemPromptSnapshot` lines do not fail with `Separator is not found, and chunk exceed the limit`.
-- Subagent workers redact `SystemPromptSnapshot.text` on the NDJSON pipe (parent drain ignores it; full index would otherwise inflate every inner-turn line).
+- Max 10 parallel blocking `task` calls per batch.
+- `subagents.max_turns` / `subagents.timeout_sec` YAML limits apply (timeout default 3600s).
+- Parent reads child NDJSON with a raised StreamReader limit (`SUBAGENT_STDOUT_LINE_LIMIT`, 16 MiB).
+- Subagent workers redact `SystemPromptSnapshot.text` on the NDJSON pipe.
 
 ---
 
-### 13. Durable subagent runs (task queue)
+### 13. Durable subagent runs (RunStore lease)
 
-**Purpose:** Optional async subagent execution via `RunStore`.
+**Purpose:** Remember background runs across turns and gateway restarts.
 
-**Key files:** `core/persistence/durable_runs.py`, `core/persistence/runs.py`, `subagents/worker/`
+**Key files:** `core/persistence/durable_runs.py`, `core/subagents/supervisor.py`
 
 **How it works:**
-- `MONKEYBOT_TASK_QUEUE=1` enqueues via `record_pending`; workers run `python -m monkeybot.subagents.worker`.
-- Requires `DB_URL` / storage — queue mode without storage raises at enqueue time.
-- Production: standalone `python -m monkeybot.subagents.worker`. Development only: `MONKEYBOT_WORKER_POOL=1` on the gateway (same event loop as SSE — do not use in production). See [Cloud deployment](cloud-deployment-design.md) for multi-process notes.
-
-**Worker tuning:**
-
-| Variable | Default | Purpose |
-|---|---|---|
-| `MONKEYBOT_WORKER_STALE_CLAIM_MS` | `600000` (10 min) | Reclaim `running` rows with no heartbeat after this window; another worker may re-execute the run |
-| `MONKEYBOT_WORKER_POLL_INTERVAL_S` | `2` | Poll interval for `pending_runs()` |
-| `MONKEYBOT_WORKER_CONCURRENCY` | `1` | Max concurrent claimed runs per worker |
-| `MONKEYBOT_WORKER_ID` | auto | Worker identity for claim attribution |
+- A background spawn writes a `running` row with `worker_id` (this process) and `claimed_at`. A heartbeat renews the lease (`subagents.lease_ms`, default 60s).
+- `await_task` reads the in-memory run, or the stored payload after a restart.
+- On startup, `running` rows owned by a dead process on this host are marked failed. A row owned by another host is left alone.
 
 **Invariants:**
-- No claim heartbeat yet — subagent runs longer than `MONKEYBOT_WORKER_STALE_CLAIM_MS` risk duplicate execution. Increase the limit for long LLM workloads or keep runs under the window.
-- Queue mode without storage raises at enqueue time.
+- There is no worker pool and no `MONKEYBOT_TASK_QUEUE`. A `running` result is not completion.
+- Without a storage backend, background runs live only in the gateway process.
 
 ---
 

{monkeybot-3.12.0 → monkeybot-3.13.0}/docs/getting-started.md

@@ -21,11 +21,15 @@ Session routes are **not** authenticated; do not expose the gateway to the publi
 
 ```bash
 curl -LsSf https://astral.sh/uv/install.sh | sh   # if needed
-uv tool install monkeybot-cli
+# browser-harness pins Pillow 12. Core 3.12 needs Pillow 13, and
+# `uv tool install` ignores the package override unless this file is passed.
+# Without it the resolver stays on core 3.10.0.
+printf 'pillow>=13\n' > /tmp/monkeybot-overrides.txt
+uv tool install --overrides /tmp/monkeybot-overrides.txt monkeybot-cli
 monkeybot --help
 ```
 
-Upgrade later with `uv tool upgrade monkeybot-cli`.
+Upgrade later with `uv tool install --reinstall --overrides /tmp/monkeybot-overrides.txt monkeybot-cli`.
 
 ---
 

{monkeybot-3.12.0 → monkeybot-3.13.0}/docs/observability-runbook.md

@@ -38,7 +38,8 @@ export OTEL_TRACES_SAMPLER_ARG=0.1
 
 ## PII and data minimization
 
-- Span attributes use `truncate()` (default 8 KiB) for user messages, tool I/O, and errors.
+- Tool input and output, tool errors, user messages, completions, and turn I/O are stored whole, capped at 1 MiB per attribute. The repeated history prompt (`gen_ai.prompt`) and other strings stay at 8 KiB.
+- OTLP exports have no value-level secret scan, so full tool I/O reaches the collector. Redact at the collector. The SQLite exporter scans values when Spaces is running.
 - Denylist blocks attribute keys containing `api_key`, `secret`, `password`, `token`, `authorization`, etc. (`gen_ai.*` usage keys are exempt).
 - Hook span events record **`tool.name` only** — never tool args or results.
 - Use **HTTPS** for `OTEL_EXPORTER_OTLP_ENDPOINT` in production.
@@ -48,6 +49,8 @@ export OTEL_TRACES_SAMPLER_ARG=0.1
 
 - Lower production volume with sampling (above).
 - Use an OpenTelemetry Collector for fan-out and optional filtering.
+- The OTLP exporter sends 8 spans per request (the SDK default is 512). A tool span copies each value three times, so input and output both near 1 MiB are about 6 MiB and eight of those stay under the SDK's 64 MiB `max_request_size` (measured before compression). A larger batch is dropped whole and logged. Set `OTEL_BSP_MAX_EXPORT_BATCH_SIZE` to a positive integer to override; any other value keeps 8. Set `OTEL_EXPORTER_OTLP_COMPRESSION=gzip` to help with a collector body limit. The SQLite exporter uses the same batch size.
+- The SQLite trace DB stores each I/O value up to three times per span (`attributes_json` under the tool and `*.value` keys, plus the `input_value` / `output_value` column) and never shrinks on its own. Lower `MONKEYBOT_TRACES_MAX_SPANS` or `MONKEYBOT_TRACES_RETENTION_DAYS` if it grows too large.
 - Tune backend retention (Phoenix / Langfuse) per your compliance budget.
 
 ## Troubleshooting