From 33b8bd530901088864e6577e8306edfe7eb45bf4 Mon Sep 17 00:00:00 2001 From: Kaden McKeen Date: Sat, 9 May 2026 21:16:55 -0400 Subject: [PATCH] docs: warn about read_cell stale-output lag in jupyter-mcp guidance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit read_cell / read_notebook return the notebook's cached output, which lags live kernel state after execute_cell — execution counts and stdout may still reflect the prior run. Surfaces a footgun an agent will otherwise hit when using read_cell to "verify" an execution; the fix is to trust execute_cell's return value instead. Discovered while smoke-testing the aexp install --with-jupyter integration in a downstream consumer (electricrag). Pairs naturally with the existing notebook_run-all-cells warning — both are "tool exists but has a footgun" notes in the same family. Co-Authored-By: Claude Opus 4.7 (1M context) --- src/aexp/vendor/limina/AGENTS.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/aexp/vendor/limina/AGENTS.md b/src/aexp/vendor/limina/AGENTS.md index e78d733..4143c72 100644 --- a/src/aexp/vendor/limina/AGENTS.md +++ b/src/aexp/vendor/limina/AGENTS.md @@ -174,6 +174,11 @@ tools over git-based round-trips for notebook work: - **DO NOT** use `notebook_run-all-cells` — exposed but currently returns 404 (asymmetric upstream bug). Loop `execute_cell` over indices for multi-cell runs. +- **`read_cell` / `read_notebook` outputs lag live state.** After an + `execute_cell`, the cached output (and execution count) returned by + `read_cell` may still reflect the *prior* run. Trust `execute_cell`'s + return value to verify the most-recent execution; don't round-trip + through `read_cell` to check. - For full setup details, troubleshooting, and the investigation log, see `docs/setup/jupyter-mcp.md`.