monkeybot 3.7.0__tar.gz → 3.8.0__tar.gz

monkeybot-3.8.0/.cursor/skills/mb-retro/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: mb-retro
+description: >-
+  Review one MonkeyBot session transcript and propose environment fixes
+  (checks, verifier criteria, AGENT.md pointers, tool access). Use ONLY when
+  the user explicitly asks for /mb-retro, a MonkeyBot retro, or to review a
+  MonkeyBot transcript for why the agent struggled. Do not run during ordinary
+  coding, and do not edit anything until the user picks a candidate.
+disable-model-invocation: true
+---
+
+# mb-retro
+
+Look at one MonkeyBot session and propose changes to the agent's environment so the next run goes better. Propose only. Edit nothing until the user picks a candidate.
+
+This is the MonkeyBot form of a session retro. It does not review the code the session produced. If the user wants a verdict on a diff, that is a code review, not this skill.
+
+## Input
+
+A session id, a session directory, or a `transcript.ndjson` path. Transcripts live under `{workspace}/.monkeybot/transcripts/` and exist only when `runtime.transcript_enabled` is true in `monkeybot.yaml`.
+
+From the monkeybot repo:
+
+```bash
+uv run monkeybot trace list --cwd <agent-root>
+uv run monkeybot trace digest <session-id-or-path> --cwd <agent-root>
+```
+
+If the user does not name a session, run `trace list` and suggest the session with the highest `score`. Say which one you are using. Do not retro every session.
+
+## Read
+
+1. Run `uv run monkeybot trace digest <id>`. That output is already resolved. Do not hand-expand `text_seq`, `result_seq`, `schema_seq`, `content_seq`, or `base_seq` diffs.
+2. Open one record only when the digest line is not enough: `uv run monkeybot trace digest <id> --seq N`. Repeat `--seq` for a few records, not the whole file.
+3. Subagent work is inlined under the `task` call that started it, from `{session}/subagents/`. Runs the digest cannot tie to a call appear under `Unlinked subagent runs`. If a line says `no child transcript`, say so and do not invent what the child did.
+4. A `--seq` record with `text_error: diff_mismatch` was written by an older harness whose prompt diff cannot be rebuilt. Do not quote its text.
+
+A smooth digest (score 0, short timeline, no interventions) has little to teach. Say that and stop.
+
+## Find struggle moments
+
+Every candidate must cite one or more `@seq` lines from this digest. Discard any candidate you cannot point at a specific moment. Do not fill categories with generic advice.
+
+Look for:
+
+- Tool errors, especially the same `error_kind` more than once
+- `HarnessIntervention` (`doom_loop`, `truncated_batch`, `empty_completion`, `post_tool_empty`, `background_jobs_nudge`, `compaction_fallback`, `max_turns`, `verifier_replan`)
+- Steers, verifier verdicts, empty assistant replies, context summaries
+- Slow tools and repeated identical calls
+- A long search before a fact that a pointer would have named
+- A subagent that struggled while the parent looked fine
+
+## Classify
+
+Put each moment in one category. The category decides where the fix goes.
+
+| What went wrong | Propose |
+| --- | --- |
+| Slow to find a fact | A navigation pointer in the agent's `AGENT.md`, a skill description, or a memory entry |
+| A mechanical mistake | An inspector or `PRE_TOOL` hook, tighter tool-schema validation, `permissions.yaml` or a path grant, or a guard threshold |
+| A judgement-call miss | A verifier criterion. The verifier is the reviewer. |
+| Bloated `AGENT.md` or harness prompt (`src/monkeybot/core/prompts/harness_prompt.py`) | Move the steering into an on-demand skill, or delete the no-op lines |
+| An expensive tool call | Trim tool output, spill it to a file, or load tools progressively |
+| Missing information or access | An MCP server, a tool, or wider permissions |
+| The agent behaved reasonably and the harness misbehaved | A code fix plus a regression test in `tests/`, or an eval scenario in `evals/scenarios/` |
+
+## Rules
+
+- A mechanical problem gets a check that can fail, never a sentence in a steering file.
+- `AGENT.md` gets navigation pointers only. Do not add new standing rules there, and do not add them to a root `AGENTS.md` or `CLAUDE.md`.
+- If a check already exists but is not wired up, the fix is to wire it, not to write a second one.
+- A missing guardrail (no test or eval covers this failure) is its own finding.
+- Rank by severity for the next session, not by how loud the log line was. A quiet expensive miss can outrank a noisy cheap one. Say that the order is a draft.
+- Do not propose deleting lint rules, hooks, or CI jobs from other sessions. This skill sees one transcript.
+
+## Output
+
+Ranked candidates, most severe first. For each one:
+
+1. **Moment** — quote the digest lines and their `@seq` numbers.
+2. **Category** — one row from the table.
+3. **Target** — the exact file or config key.
+4. **Change** — the proposed check, pointer, criterion, or deletion, in a few lines. Not a patch yet.
+
+Then stop and ask which candidates to apply. Do not edit files, install hooks, or change `monkeybot.yaml` before that.

{monkeybot-3.7.0 → monkeybot-3.8.0}/BACKLOG.md

@@ -35,7 +35,6 @@
 ### Infra
 - **Postgres as production default** — backend exists; gateway still defaults to SQLite; decide when/if this becomes the default.
 - **Firestore usage aggregation doesn't scale** — `FirestoreUsageStore.summary()`/`breakdown()` (agent-wide, no `thread_id`) stream the entire `turn_usage` collection into memory and aggregate in Python. Fine at small scale; revisit with a Firestore aggregation query or a scheduled rollup doc if `/usage` traffic or data volume grows.
-- **Knowledge ANN index (sqlite-vec)** — deliberately deferred. The numpy matrix cache in `sqlite_vector.py` holds through ~50–100k chunks and query cost is embed-API bound, not local ANN. Revisit only if measured ANN p95 exceeds ~20–50 ms or the resident matrix causes RAM pressure; the true scale escape hatch is `store.type: pgvector`, not `sqlite-vec` packaging.
 
 ### MCP
 - **MCP distro linkage** — confirm scaffolded `monkeybot.yaml` paths (`paths.mcp_config`, `paths.skills_path`) match deployment; smoke-test against real MCP servers beyond the bundled examples.

{monkeybot-3.7.0 → monkeybot-3.8.0}/CHANGELOG.md

@@ -6,6 +6,35 @@ the project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+### CLI
+
+### Added
+
+- `monkeybot trace list` and `monkeybot trace digest` turn a session transcript into a resolved timeline, with each subagent run shown under the `task` call that started it. In chat, `/export-trace` copies the whole session directory. The `mb-retro` skill proposes environment fixes from one hard session and does not edit anything until you pick a candidate.
+
+## [core v3.8.0] - 2026-10-07
+
+### Added
+
+- Stored chat history can branch. Rows keep a stable `row_id`. `POST /sessions/{id}/branches` edits, regenerates, rewinds, or restores from an anchor; truncate shortens the active thread in place; fork copies a prefix into a new session. A summarized prefix stays read-only unless the cut keeps that summary. Queued follow-ups drain onto the branch that becomes active. Goal ledger and tracker state carry across a rewrite. Older databases rebuild `session_branches` on startup, including Postgres.
+- Session transcripts record harness guard hits as `HarnessIntervention` (not sent on SSE) and write each subagent run under the parent session's `subagents/` directory when `runtime.transcript_enabled` is on.
+
+### Fixed
+
+- Transcript prompt diffs no longer drop changed lines that start with `--` or `++`, such as a removed `---` rule. Diffs already written that way are flagged as `text_error: diff_mismatch` when read instead of being rebuilt wrong.
+- A background `run_command` in the sandbox keeps running after launch returns.
+
+### Removed
+
+- The workspace knowledge index and the `search` tool. Agents explore the workspace with `grep` and `glob`, then `read_file`. Memory search, web search, and browser DOM indexing are unchanged.
+- The `knowledge-ast` and `knowledge-media` extras. Installs that still request them get an unknown-extra warning; drop them from agent deps.
+- `numpy` is no longer a core dependency.
+
+### Changed
+
+- A leftover `knowledge:` section in `monkeybot.yaml` is warned once and ignored. Old index files (`index.sqlite`, `.monkeybot/knowledge/`) are no longer read and can be deleted.
+- The `Evidence:` path guard moved to `core/hooks/evidence_guard.py` and is always registered by the gateway. Before, it ran only when `knowledge.enabled` was on.
+
 ## [core v3.7.0] - 2026-09-30
 
 ### Added

{monkeybot-3.7.0 → monkeybot-3.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: monkeybot
-Version: 3.7.0
+Version: 3.8.0
 Summary: monkeybot agent harness — FastAPI SSE gateway, owned loop, SQLite, and MCP.
 License: MIT
 License-File: LICENSE
@@ -10,7 +10,6 @@ Requires-Dist: fastapi>=0.115.0
 Requires-Dist: google-genai>=1.0.0
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: mcp<2,>=1.27.1
-Requires-Dist: numpy<2.5,>=1.26.0
 Requires-Dist: pillow>=10.0.0
 Requires-Dist: pydantic>=2.10.0
 Requires-Dist: python-dotenv>=1.0.0
@@ -48,11 +47,6 @@ Provides-Extra: huggingface
 Requires-Dist: openai>=1.0; extra == 'huggingface'
 Requires-Dist: pypdf>=6.14.2; extra == 'huggingface'
 Requires-Dist: tiktoken>=0.7.0; extra == 'huggingface'
-Provides-Extra: knowledge-ast
-Requires-Dist: tree-sitter-language-pack>=1.6; extra == 'knowledge-ast'
-Provides-Extra: knowledge-media
-Requires-Dist: pypdf>=6.14.2; extra == 'knowledge-media'
-Requires-Dist: python-docx>=1.1.0; extra == 'knowledge-media'
 Provides-Extra: memory
 Requires-Dist: mempalace<4,>=3.7.0; extra == 'memory'
 Provides-Extra: nvidia

{monkeybot-3.7.0 → monkeybot-3.8.0}/cli/src/monkeybot_cli/chat_tool_display.py

@@ -41,7 +41,7 @@ _EDIT_TOOLS = frozenset(
     {"write_file", "write", "edit_file", "apply_patch", "str_replace"}
 )
 _PATH_TOOLS = _READ_TOOLS | _EDIT_TOOLS
-_SEARCH_TOOLS = frozenset({"grep", "search", "web_search"})
+_SEARCH_TOOLS = frozenset({"grep", "web_search"})
 _HINT_KEYS = frozenset(
     {
         "argv",

{monkeybot-3.7.0 → monkeybot-3.8.0}/cli/src/monkeybot_cli/chat_tui.py

@@ -105,7 +105,7 @@ _SLASH_SPECS: tuple[tuple[str, str], ...] = (
     ("/timestamps", "Toggle turn timestamps"),
     ("/copy", "Copy last assistant reply"),
     ("/export", "Export transcript to a markdown file"),
-    ("/export-trace", "Export full debug trace (ndjson) for evals"),
+    ("/export-trace", "Export the debug trace directory (ndjson + subagents)"),
     ("/bye", "Exit chat"),
 )
 
@@ -1686,10 +1686,10 @@ class ChatApp(App[int]):
             )
             return
         ts = datetime.now().strftime("%Y%m%d_%H%M%S")
-        dest = self.agent_root / "data" / f"trace_export_{ts}.ndjson"
+        dest = self.agent_root / "data" / f"trace_export_{ts}"
         try:
             dest.parent.mkdir(parents=True, exist_ok=True)
-            shutil.copyfile(src, dest)
+            shutil.copytree(session_dir, dest)
         except OSError as exc:
             self._mount_system(f"Trace export failed: {exc}", error=True)
             return

monkeybot-3.8.0/cli/src/monkeybot_cli/commands/trace.py

@@ -0,0 +1,174 @@
+"""monkeybot trace — list and digest session transcripts."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from monkeybot.core.layout import resolve_workspace_root
+from monkeybot.core.persistence.transcript import (
+    TRANSCRIPT_FILENAME,
+    resolve_session_artifact_dir,
+)
+from monkeybot.core.persistence.transcript_reader import (
+    build_digest,
+    digest_to_json,
+    iter_session_dirs,
+    records_by_seq,
+    render_digest_markdown,
+    scan_session_signals,
+)
+
+from monkeybot_cli.config_resolve import resolve_agent_root, resolve_config
+
+
+def _workspace(args: argparse.Namespace) -> Path:
+    cwd = Path(args.cwd).expanduser().resolve() if args.cwd else None
+    config_path = resolve_config(args.config, cwd=cwd)
+    agent_root = resolve_agent_root(cwd=cwd, config_path=config_path)
+    return resolve_workspace_root(agent_root=agent_root, config_path=config_path)
+
+
+def _transcripts_root(workspace: Path) -> Path:
+    return workspace / ".monkeybot" / "transcripts"
+
+
+def _resolve_target(raw: str | None, workspace: Path) -> Path | None:
+    """Session directory from an id, a directory, or a transcript.ndjson path."""
+    if raw:
+        candidate = Path(raw).expanduser()
+        if candidate.is_file() and candidate.name == TRANSCRIPT_FILENAME:
+            return candidate.parent
+        if candidate.is_dir() and (candidate / TRANSCRIPT_FILENAME).is_file():
+            return candidate
+        session_dir = resolve_session_artifact_dir(workspace, raw)
+        if (session_dir / TRANSCRIPT_FILENAME).is_file():
+            return session_dir
+        return None
+    sessions = iter_session_dirs(_transcripts_root(workspace))
+    return sessions[0] if sessions else None
+
+
+def _print_list(workspace: Path, *, as_json: bool) -> int:
+    sessions = iter_session_dirs(_transcripts_root(workspace))
+    rows = []
+    for session_dir in sessions:
+        signals = scan_session_signals(session_dir)
+        rows.append(
+            {
+                "dir": session_dir.name,
+                "path": str(session_dir),
+                "score": signals.score(),
+                "errors": sum(signals.tool_errors.values()),
+                "interventions": sum(signals.interventions.values()),
+                "steers": signals.steers,
+                "verdicts": signals.verdicts,
+                "empty": signals.empty_assistant,
+                "summaries": signals.summaries,
+                "slow": len(signals.slow_tools),
+                "repeated": len(signals.repeated_calls),
+            }
+        )
+    if as_json:
+        print(json.dumps(rows, indent=2))
+        return 0
+    if not rows:
+        print(f"No transcripts under {_transcripts_root(workspace)}")
+        return 0
+    for row in rows:
+        print(
+            f"{row['dir']}  score={row['score']}  errors={row['errors']}  "
+            f"interventions={row['interventions']}  steers={row['steers']}  "
+            f"verdicts={row['verdicts']}  empty={row['empty']}  "
+            f"summaries={row['summaries']}  slow={row['slow']}  repeated={row['repeated']}"
+        )
+    return 0
+
+
+def _read_failure(exc: OSError) -> int:
+    print(f"Transcript read failed: {exc}", file=sys.stderr)
+    return 1
+
+
+def run_trace_list(args: argparse.Namespace) -> int:
+    try:
+        return _print_list(_workspace(args), as_json=bool(args.json))
+    except OSError as exc:
+        return _read_failure(exc)
+
+
+def run_trace_digest(args: argparse.Namespace) -> int:
+    workspace = _workspace(args)
+    try:
+        session_dir = _resolve_target(args.target, workspace)
+        if session_dir is None:
+            target = args.target or "(latest)"
+            print(f"No transcript found for {target}", file=sys.stderr)
+            return 1
+        seqs = args.seq or []
+        if seqs:
+            found = records_by_seq(session_dir, seqs)
+            missing = False
+            for seq in seqs:
+                record = found.get(seq)
+                if record is None:
+                    print(f"No record with seq {seq} in {session_dir}", file=sys.stderr)
+                    missing = True
+                    continue
+                print(json.dumps(record, ensure_ascii=False, indent=2, default=str))
+            return 1 if missing else 0
+        digest = build_digest(session_dir, full=bool(args.full))
+    except OSError as exc:
+        return _read_failure(exc)
+    if args.json:
+        print(json.dumps(digest_to_json(digest), ensure_ascii=False, indent=2, default=str))
+        return 0
+    print(render_digest_markdown(digest, max_chars=args.max_chars))
+    return 0
+
+
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    trace = subparsers.add_parser(
+        "trace",
+        help="List and digest session transcripts for debugging and retros",
+    )
+    sub = trace.add_subparsers(dest="trace_command", required=True)
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--cwd", help="Agent project root")
+    common.add_argument("--config", help="Path to monkeybot.yaml")
+
+    listing = sub.add_parser(
+        "list",
+        parents=[common],
+        help="List captured sessions, newest first",
+    )
+    listing.add_argument("--json", action="store_true", help="JSON output")
+    listing.set_defaults(func=run_trace_list)
+
+    digest = sub.add_parser(
+        "digest",
+        parents=[common],
+        help="Condensed timeline of one session",
+    )
+    digest.add_argument(
+        "target",
+        nargs="?",
+        help="Session id, session directory, or transcript.ndjson path (default: newest)",
+    )
+    digest.add_argument("--json", action="store_true", help="JSON output")
+    digest.add_argument("--full", action="store_true", help="Do not clip excerpts")
+    digest.add_argument(
+        "--max-chars",
+        type=int,
+        default=0,
+        help="Cap markdown length (0 = no cap)",
+    )
+    digest.add_argument(
+        "--seq",
+        type=int,
+        action="append",
+        help="Print one resolved record instead of the digest (repeatable)",
+    )
+    digest.set_defaults(func=run_trace_digest)

{monkeybot-3.7.0 → monkeybot-3.8.0}/cli/src/monkeybot_cli/main.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import argparse
 import sys
 
-from monkeybot_cli.commands import chat, doctor, loop, new, refresh, run_cmd, talk, validate
+from monkeybot_cli.commands import chat, doctor, loop, new, refresh, run_cmd, talk, trace, validate
 from monkeybot_cli.runtime_python import RuntimeUpgradeError, report_runtime_upgrade_error
 
 
@@ -24,6 +24,7 @@ def build_parser() -> argparse.ArgumentParser:
     chat.register(sub)
     talk.register(sub)
     loop.register(sub)
+    trace.register(sub)
     return parser
 
 

{monkeybot-3.7.0 → monkeybot-3.8.0}/cli/src/monkeybot_cli/providers.py

@@ -111,8 +111,6 @@ def extra_module(extra: str) -> str:
         "cli": "typer",
         "cli-realtime": "pyaudio",
         "evals": "deepeval",
-        "knowledge-ast": "tree_sitter_language_pack",
-        "knowledge-media": "pypdf",
     }
     return mapping.get(extra, extra)
 

{monkeybot-3.7.0 → monkeybot-3.8.0}/cli/src/monkeybot_cli/scaffold_defaults/monkeybot.example.yaml

@@ -147,33 +147,6 @@ emission:
   # (any value other than the terse-set means off).
   style: off
 
-# Unified knowledge layer: local FTS + ANN embeddings + note↔workspace links + search.
-# Embeddings stay off by default until configured.
-# Index path is always {root}/index.sqlite (not configurable).
-knowledge:
-  enabled: true
-  search:
-    default_limit: 10
-  indexer:
-    chunk_tokens: 700
-    chunk_overlap_ratio: 0.12
-  embeddings:
-    enabled: false
-    # provider: nvidia | openai | voyage | gemini | openai_compatible
-    # model / dimensions / base_url are optional — per-provider defaults apply.
-    provider: nvidia
-    # model: nvidia/nemotron-3-embed-1b          # openai → text-embedding-3-small
-    # dimensions: 1024                          # openai → 1536; voyage → 512; gemini → 768
-    # base_url: https://integrate.api.nvidia.com/v1
-    #   openai → https://api.openai.com/v1
-    #   voyage → https://api.voyageai.com/v1
-    #   openai_compatible → required (custom gateway)
-    batch_size: 32
-    # Auth env (by provider): NVIDIA_API_KEY | OPENAI_API_KEY | VOYAGE_API_KEY | GEMINI_API_KEY
-  store:
-    type: sqlite
-    path: .monkeybot/knowledge/vectors.sqlite
-
 subagents:
   timeout_sec: 600
   max_turns: 1000

{monkeybot-3.7.0 → monkeybot-3.8.0}/cli/tests/test_chat_tui.py

@@ -641,7 +641,7 @@ def test_slash_export_trace_no_session(tmp_path: Path) -> None:
         async with app.run_test() as pilot:
             app.query_one("#prompt", Composer).post_message(Composer.Submitted("/export-trace"))
             await pilot.pause()
-            assert not list((tmp_path / "data").glob("trace_export_*.ndjson"))
+            assert not list((tmp_path / "data").glob("trace_export_*"))
 
     asyncio.run(_run())
 
@@ -665,11 +665,20 @@ def test_slash_export_trace_copies_ndjson(tmp_path: Path) -> None:
             (session_dir / "transcript.ndjson").write_text(
                 '{"seq":1,"type":"SessionManifest"}\n', encoding="utf-8"
             )
+            child = session_dir / "subagents" / "child-1"
+            child.mkdir(parents=True)
+            (child / "transcript.ndjson").write_text(
+                '{"seq":1,"type":"UserMessage"}\n', encoding="utf-8"
+            )
             app.query_one("#prompt", Composer).post_message(Composer.Submitted("/export-trace"))
             await pilot.pause()
-            exports = list((tmp_path / "data").glob("trace_export_*.ndjson"))
+            exports = list((tmp_path / "data").glob("trace_export_*"))
             assert len(exports) == 1
-            assert exports[0].read_text(encoding="utf-8") == '{"seq":1,"type":"SessionManifest"}\n'
+            assert exports[0].is_dir()
+            assert (exports[0] / "transcript.ndjson").read_text(encoding="utf-8") == (
+                '{"seq":1,"type":"SessionManifest"}\n'
+            )
+            assert (exports[0] / "subagents" / "child-1" / "transcript.ndjson").is_file()
 
     asyncio.run(_run())
 

monkeybot-3.8.0/cli/tests/test_trace_cmd.py

@@ -0,0 +1,85 @@
+"""CLI coverage for `monkeybot trace list` and `digest`."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from monkeybot_cli.main import main
+
+
+def _session(tmp_path: Path) -> Path:
+    session = tmp_path / "workspace" / ".monkeybot" / "transcripts" / "20260101T000000Z_sess-1"
+    session.mkdir(parents=True)
+    records = [
+        {"type": "SessionManifest", "session_id": "sess-1", "model": "m"},
+        {"seq": 1, "type": "UserMessage", "content": "hello"},
+        {
+            "seq": 2,
+            "type": "HarnessIntervention",
+            "intervention": "doom_loop",
+            "detail": "stuck",
+            "inner_turn": 1,
+        },
+        {"seq": 3, "type": "ProviderResponse", "text": "recovered", "tool_requests": []},
+    ]
+    (session / "transcript.ndjson").write_text(
+        "".join(json.dumps(row) + "\n" for row in records),
+        encoding="utf-8",
+    )
+    return session
+
+
+def test_trace_list_digest_and_seq(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    _session(tmp_path)
+    assert main(["trace", "list", "--cwd", str(tmp_path)]) == 0
+    listed = capsys.readouterr().out
+    assert "sess-1" in listed
+    assert "interventions=1" in listed
+    assert "score=1" in listed
+
+    assert main(["trace", "digest", "sess-1", "--cwd", str(tmp_path)]) == 0
+    digest = capsys.readouterr().out
+    assert "@seq 2" in digest
+    assert "doom_loop" in digest
+    assert "recovered" in digest
+
+    assert main(["trace", "digest", "sess-1", "--cwd", str(tmp_path), "--seq", "2"]) == 0
+    record = json.loads(capsys.readouterr().out)
+    assert record["intervention"] == "doom_loop"
+    assert record["detail"] == "stuck"
+
+
+def test_trace_digest_missing_session(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    assert main(["trace", "digest", "missing", "--cwd", str(tmp_path)]) == 1
+    err = capsys.readouterr().err
+    assert "No transcript found" in err
+
+
+def test_trace_read_failure_exits_nonzero(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    session = _session(tmp_path)
+    ndjson = session / "transcript.ndjson"
+    ndjson.chmod(0)
+    try:
+        assert main(["trace", "digest", "sess-1", "--cwd", str(tmp_path)]) == 1
+        assert "Transcript read failed" in capsys.readouterr().err
+        assert main(["trace", "list", "--cwd", str(tmp_path)]) == 1
+        assert "Transcript read failed" in capsys.readouterr().err
+    finally:
+        ndjson.chmod(0o644)
+
+
+def test_trace_digest_unreadable_root_exits_nonzero(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    root = _session(tmp_path).parent
+    root.chmod(0)
+    try:
+        assert main(["trace", "digest", "--cwd", str(tmp_path)]) == 1
+        assert "Transcript read failed" in capsys.readouterr().err
+    finally:
+        root.chmod(0o755)