Skip to content

Commit 9600cdf

Browse files
committed
refactor(tui): delete the disk-reading session code (ADR1 PR 3)
The pager no longer reads session files. The last change (PR 2) resolves --continue, --resume and --session-id through the agent, so the old readers have no caller left. This change deletes them and adds a gate that keeps them out. Deleted, in the production code of pi-pager and pi-pager-bin: - session_startup.rs: materialize_startup and its helpers (the latest session, the id, the title and the session-id checks on disk, and the remote-restore branch). - cli.rs and pi-pager-bin main.rs: the pin of the resume target and the saved sandbox profile. A resumed session takes the sandbox as a new session does (plan decision 2). - session_title_resolve.rs: the match against the old summaries. select_by_title stays. - effects/helpers.rs, effects/mod.rs, dispatch/session/load.rs: the first-prompt reader (chat_history.jsonl) and the local-session checks before a load. - agent_view/plan.rs: the plan.md read of the plan preview (plan decision 7). - line_viewer.rs open_markdown(path) and test_util.rs GrokHomeFixture: no caller is left. Added: - gates.session_disk_reads (scripts/tui_baseline.py and .toml): production code of both crates must not call the readers of the session store or name the sessions directory. The scanner finds 18 hits on main, 17 after PR 2, and 0 here. It runs in `gates`, in `check` and in pytest. - 6 pytest cases for the gate. 27 tests go with the deleted code (26 passed, 1 ignored): pi-pager 5,675 -> 5,649. The embedded user guide (17-sessions.md) and CHANGELOG.md say what changed for the user.
1 parent 506769b commit 9600cdf

18 files changed

Lines changed: 377 additions & 1835 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
1010
### Changed
1111

1212
- **`zypi --continue`, `--resume` and `--session-id` ask the agent which session is meant (TUI)**: `zypi` used to look for the session in the session files of the old Rust agent. The Python agent writes another layout, so `--resume <title>` found no session, an unknown id failed only after the UI had started, a used `--session-id` left the UI open with `Session creation failed: Invalid params`, and `--continue` took the session that was created last (the first of the **Known issues** of 0.5.0). Now `zypi` starts the agent first and then asks it over ACP, with `session/list` (page after page) and `session/load`. It reads no session file for this. A session that does not exist ends the run before the event loop starts: the terminal is restored, the agent is stopped, the message is printed, and the exit status is 1. **Behaviour changes**: `--continue` and `--resume` without a value take the session of this directory with the latest activity (the time of its last write), not the one that was created last. `--resume <id>` finds the id in every directory and loads the session in the directory it belongs to. `--resume <title>` matches the title, which is the first message of the session, among the sessions of this directory, without regard to letter case and to spaces at the ends; two sessions with the same title are an error that lists their ids and last activity. `--session-id <id>` reads every page of the session list and refuses an id that any session has (`Session ID <id> is already in use.`, exit status 1); that costs one pass through the list (`scripts/session_list_bench.py` prints it as `walk all`), and an agent that offers no `session/list` skips the check and refuses a used id itself. The lookup stops after 30 s, the limit of the connect (`GROK_CONNECT_UI_TIMEOUT_SECS`). **Not solved**: the agent writes the file of a session when the session is created, so a run in which nobody typed a message leaves a session with the title `(no messages)`, and `--continue` takes it when it is the latest. The fix is in the Python agent (write the file at the first message). Tests: 25 unit tests of the lookup against a scripted agent, 4 of the time limit and of a cancel, 3 end-to-end tests against the real agent, and `scripts/tui_pty/resume_matrix.py --strict` (13 of 13 pass; cases 5 and 11 were known gaps, and case 8 now needs exit status 1).
13+
- **A resumed session no longer takes the sandbox profile it was created with (TUI)**: the old Rust agent saved the sandbox profile in the files of a session. `zypi --continue` and `--resume` read it back before the sandbox was applied, so a resumed session kept its sandbox, and `--sandbox X` on a session that was saved with `Y` was refused (`cannot resume this session under sandbox profile ...`). The Python agent never saved a profile, so for its sessions nothing changes. The profile now comes from `--sandbox`, from `GROK_SANDBOX` and from the configuration, as it does for a new session. The code that read it is gone (decision 2 of the plan).
14+
15+
### Removed
16+
17+
- **The code in the TUI that read session files**: `materialize_startup` and its helpers, the pin of `--resume <title>` before the sandbox (`pin_local_resume_target`), the saved sandbox profile (`SandboxStartup`, `saved_resume_profile`), the check that a `--session-id` is free before `session/new`, the first-prompt fallback of the resume picker (it read `chat_history.jsonl`), the check of the session files in the picker's load, and the read of `<home>/sessions/.../plan.md` for the plan preview. `scripts/tui_baseline.py gates` has a new gate (`gates.session_disk_reads`): it fails when production code in `pi-pager` or `pi-pager-bin` calls the readers of the session store again.
1318

1419
## [0.5.0] - 2026-10-13
1520

‎scripts/tests/test_tui_baseline.py‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -180,6 +180,102 @@ def test_the_residue_ceilings_hold_in_this_tree():
180180
assert not over, f"lines now vs ceiling in scripts/tui_baseline.toml: {over}"
181181

182182

183+
# ---- session disk-read gate (ADR1) ------------------------------------------------------------
184+
185+
186+
def _crate(tmp_path: Path, files: dict[str, str]) -> Path:
187+
"""A fake `tui/` with one crate `codegen/pi-pager`; returns the `tui` directory."""
188+
src = tmp_path / "tui" / "crates" / "codegen" / "pi-pager" / "src"
189+
for name, text in files.items():
190+
path = src / name
191+
path.parent.mkdir(parents=True, exist_ok=True)
192+
path.write_text(text, encoding="utf-8")
193+
return tmp_path / "tui"
194+
195+
196+
def _scan(tui: Path, patterns=("list_summaries", 'join("sessions")')) -> list[str]:
197+
return tb.scan_session_disk_reads(tui, ["codegen/pi-pager"], list(patterns))
198+
199+
200+
def test_session_disk_read_scan_reports_production_code_with_path_and_line(tmp_path):
201+
reads = (
202+
'fn a() {\n let rows = list_summaries(cwd).await;\n let d = h.join("sessions");\n}\n'
203+
)
204+
tui = _crate(tmp_path, {"app/a.rs": reads, "app/clean.rs": "fn b() {}\n"})
205+
hits = _scan(tui)
206+
assert hits == [
207+
"crates/codegen/pi-pager/src/app/a.rs:2: let rows = list_summaries(cwd).await;",
208+
'crates/codegen/pi-pager/src/app/a.rs:3: let d = h.join("sessions");',
209+
]
210+
assert tb.scan_session_disk_reads(tui, ["codegen/pi-pager"], []) == []
211+
212+
213+
@pytest.mark.parametrize(
214+
"name",
215+
[
216+
"app/dispatch/tests/mod.rs",
217+
"app/effects/tests.rs",
218+
"app/session_resolve_tests.rs",
219+
"test_util.rs",
220+
"app/agent_view/test_fixtures.rs",
221+
],
222+
)
223+
def test_session_disk_read_scan_skips_test_files(tmp_path, name):
224+
tui = _crate(tmp_path, {name: "fn t() { list_summaries(); }\n"})
225+
assert _scan(tui) == []
226+
227+
228+
def test_session_disk_read_scan_skips_comments_and_inline_test_modules(tmp_path):
229+
text = (
230+
"// list_summaries used to be called here\n"
231+
'/// Reads `join("sessions")`, formerly.\n'
232+
"fn live() {}\n"
233+
"#[cfg(test)]\n"
234+
"#[allow(dead_code)]\n"
235+
"pub(crate) mod tests {\n"
236+
" fn t() {\n"
237+
" list_summaries();\n"
238+
" }\n"
239+
"}\n"
240+
"fn after_the_tests() {\n"
241+
" list_summaries();\n"
242+
"}\n"
243+
)
244+
tui = _crate(tmp_path, {"a.rs": text})
245+
assert _scan(tui) == ["crates/codegen/pi-pager/src/a.rs:12: list_summaries();"]
246+
247+
248+
def test_a_cfg_test_on_a_single_item_does_not_hide_the_code_after_it(tmp_path):
249+
"""`plan.rs` has `#[cfg(test)] use ...;` at the top; the read at line 35 must still show."""
250+
text = (
251+
"#[cfg(test)]\n"
252+
"use super::test_fixtures;\n"
253+
'#[cfg(test)]\n#[path = "a_tests.rs"]\nmod tests;\n'
254+
"fn read() {\n"
255+
" list_summaries();\n"
256+
"}\n"
257+
)
258+
tui = _crate(tmp_path, {"a.rs": text})
259+
assert _scan(tui) == ["crates/codegen/pi-pager/src/a.rs:7: list_summaries();"]
260+
261+
262+
def test_manifest_session_disk_read_gate_is_well_formed():
263+
gate = _manifest()["gates"]["session_disk_reads"]
264+
assert gate["crates"] and gate["patterns"]
265+
for crate in gate["crates"]:
266+
assert (REPO_ROOT / "tui" / "crates" / crate / "src").is_dir(), crate
267+
assert all(isinstance(p, str) and p for p in gate["patterns"])
268+
# The pure title helpers stay allowed: a bare `session::persistence` would forbid them.
269+
assert "session::persistence" not in gate["patterns"]
270+
271+
272+
def test_no_pager_code_reads_session_files_in_this_tree():
273+
"""The same gate as `tui_baseline.py gates`, so the Python CI job also sees a regression."""
274+
gate = _manifest()["gates"]["session_disk_reads"]
275+
hits = tb.scan_session_disk_reads(REPO_ROOT / "tui", gate["crates"], gate["patterns"])
276+
assert not hits, "the pager reads session files again (ADR1): " + "; ".join(hits[:5])
277+
278+
183279
# ---- suite evaluation -------------------------------------------------------------------------
184280

185281

‎scripts/tui_baseline.py‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -233,6 +233,80 @@ def count_residue(root: Path, phrases: Sequence[str]) -> dict[str, int]:
233233
return counts
234234

235235

236+
TEST_FILE_STEMS = frozenset({"tests", "test_util", "test_fixtures"})
237+
TEST_MODULE_OPEN_RE = re.compile(r"^(?:pub(?:\([^)]*\))?\s+)?mod\s+\w+\s*\{$")
238+
239+
240+
def is_test_source(relative: Path) -> bool:
241+
"""Whether a Rust file holds test code only, judged by its path inside the crate's `src`.
242+
243+
Test files are named `tests.rs`, `*_tests.rs`, `test_util.rs` or `test_fixtures.rs`, or live in
244+
a directory called `tests`.
245+
"""
246+
return (
247+
relative.stem in TEST_FILE_STEMS
248+
or relative.stem.endswith("_tests")
249+
or "tests" in relative.parts[:-1]
250+
)
251+
252+
253+
def production_lines(text: str) -> Iterator[tuple[int, str]]:
254+
"""`(line number, stripped line)` for the lines of a Rust file that are not test or comment.
255+
256+
Left out: comment lines, and an inline test module (`#[cfg(test)]`, optionally more attributes,
257+
then `mod name {`) up to its closing brace in column 0. A `#[cfg(test)]` on anything else is
258+
not special: a `use` or a one-line `mod tests;` declaration holds no code to hide, and
259+
skipping to the end of the file would hide the code that follows.
260+
"""
261+
pending_cfg_test = False
262+
in_test_module = False
263+
for number, line in enumerate(text.splitlines(), 1):
264+
stripped = line.strip()
265+
if in_test_module:
266+
in_test_module = line.rstrip() != "}"
267+
continue
268+
if stripped == "#[cfg(test)]":
269+
pending_cfg_test = True
270+
continue
271+
if pending_cfg_test:
272+
if stripped.startswith("#["):
273+
continue
274+
pending_cfg_test = False
275+
if TEST_MODULE_OPEN_RE.match(stripped):
276+
in_test_module = True
277+
continue
278+
if stripped.startswith("//"):
279+
continue
280+
yield number, stripped
281+
282+
283+
def scan_session_disk_reads(
284+
tui_dir: Path, crates: Sequence[str], patterns: Sequence[str]
285+
) -> list[str]:
286+
"""`path:line: text` for every line of production code in `crates` that reads session files.
287+
288+
`crates` are paths under `tui/crates` (`codegen/pi-pager`). Only `src` is read: integration
289+
tests live next to it. A pattern is a plain substring.
290+
"""
291+
if not patterns:
292+
return []
293+
pattern = re.compile("|".join(re.escape(p) for p in patterns))
294+
hits: list[str] = []
295+
for crate in crates:
296+
src = tui_dir / "crates" / crate / "src"
297+
for path in sorted(src.rglob("*.rs")):
298+
if is_test_source(path.relative_to(src)):
299+
continue
300+
text = path.read_text(encoding="utf-8", errors="replace")
301+
if not pattern.search(text):
302+
continue
303+
for number, stripped in production_lines(text):
304+
if pattern.search(stripped):
305+
where = path.relative_to(tui_dir).as_posix()
306+
hits.append(f"{where}:{number}: {stripped[:120]}")
307+
return hits
308+
309+
236310
def evaluate_suite(
237311
suite: dict[str, Any],
238312
totals: SuiteTotals,
@@ -468,6 +542,20 @@ def run_gates(manifest: dict[str, Any], tui_dir: Path) -> tuple[list[Check], dic
468542
)
469543
)
470544

545+
disk_reads = gates.get("session_disk_reads", {})
546+
if disk_reads:
547+
hits = scan_session_disk_reads(tui_dir, disk_reads["crates"], disk_reads["patterns"])
548+
extra["session_disk_reads"] = len(hits)
549+
checks.append(
550+
Check(
551+
f"no session file reads in {', '.join(Path(c).name for c in disk_reads['crates'])}",
552+
"pass" if not hits else "fail",
553+
"no production code reads or locates session files"
554+
if not hits
555+
else "; ".join(hits[:5]),
556+
)
557+
)
558+
471559
for triple, ceiling in manifest["graph"].get("max_nodes", {}).items():
472560
proc = cargo(
473561
["tree", "--locked", "-p", package, "--target", triple, "--prefix", "none"], tui_dir

‎scripts/tui_baseline.toml‎

Lines changed: 28 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,26 @@ tracked_crates = [
3939
"leader" = 245
4040
"x.ai" = 304
4141

42+
# ADR1 (plan section 10.16): the pager asks the agent which sessions exist (`session/list`) and
43+
# reads no session files itself. Production code in these crates (paths under tui/crates) must
44+
# not call the readers of `pi-shell`'s session store, nor name the sessions directory. Skipped:
45+
# test files (`tests.rs`, `*_tests.rs`, `test_util.rs`, `tests/` directories), inline
46+
# `#[cfg(test)] mod ... {}` blocks, and comment lines. The patterns are plain substrings, and
47+
# `session::persistence` as a whole is not listed: `sanitize_and_cap_title` and
48+
# `is_forbidden_title_char` are pure string helpers that the pager uses on purpose.
49+
[gates.session_disk_reads]
50+
crates = ["codegen/pi-pager", "codegen/pi-pager-bin"]
51+
patterns = [
52+
"list_summaries",
53+
"resolve_local_session",
54+
"session_exists_for_cwd",
55+
"resumed_session_sandbox_profile",
56+
"local_summaries_for_cwd_sync",
57+
"session::storage",
58+
"persistence::session_dir",
59+
'join("sessions")',
60+
]
61+
4262
[graph]
4363
package = "pi-pager-bin"
4464

@@ -118,8 +138,14 @@ targets = [
118138
# 8,683 over the ten suites). Then -18 net for the embedded user guide (plan section 10.14): the
119139
# tutorial overlay (`views/tutorial.rs`, `tutorial_docs.rs`) and the tests of the upstream guide
120140
# are gone, and the seven zypi pages have two guard tests: 5,608 (one local run on Linux; 8,665
121-
# over the ten suites, the other nine unchanged).
122-
reference_passed = 5608
141+
# over the ten suites, the other nine unchanged). Then +35 from #18 (19 tests: `zypi export` asks
142+
# the agent) and #19 (16 tests: the status line), counted by CI at `1fa18cf` as 5,643 (8,700 over
143+
# the ten suites; this number was not changed then). Then +32 for resolving the start-up session
144+
# through `session/list` (plan section 10.16, ADR1 PR 2: 25 `session_resolve`, 4 `bounded_resolve`,
145+
# 3 `python_agent_e2e`): 5,675. Then -26 passed and -1 ignored with the code that read the session
146+
# files (ADR1 PR 3; 27 tests went with the code): 5,649 (one local run on Linux; 8,706 over the
147+
# ten suites, the other nine unchanged).
148+
reference_passed = 5649
123149
min_passed = 5300
124150

125151
# Lib tests only; they were outside the manifest until r8 (plan section 10.10: 1,092 passed,

‎tui/crates/codegen/pi-pager-bin/src/main.rs‎

Lines changed: 5 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -581,20 +581,11 @@ async fn async_main(args: PagerArgs) -> Result<()> {
581581
if let Some(Command::Wrap(ref wrap_args)) = args.command {
582582
return pi_pager::wrap_cmd::run(wrap_args);
583583
}
584-
args.pin_local_resume_target()?;
585-
let saved_profile = args.saved_resume_profile();
586-
let sandbox_profile_arg = match args.startup_sandbox_profile(saved_profile.as_deref()) {
587-
pi_pager::app::cli::SandboxStartup::Apply(profile) => profile,
588-
pi_pager::app::cli::SandboxStartup::Conflict { requested, saved } => {
589-
eprintln!(
590-
"error: cannot resume this session under sandbox profile '{requested}' — \
591-
it was created with '{saved}'. Omit --sandbox to resume with '{saved}', \
592-
or start a new session to use '{requested}'."
593-
);
594-
std::process::exit(1);
595-
}
596-
};
597-
pi_shell::config::apply_sandbox(None, sandbox_profile_arg.as_deref(), args.cwd.as_deref());
584+
// The sandbox profile comes from the flag (or the config / deployment requirement `apply_sandbox`
585+
// reads). A resumed session does not carry one: its transcript lives in the agent, which stores
586+
// no profile (ADR1: the pager reads no session files).
587+
let sandbox_profile_arg = args.sandbox.as_deref().filter(|profile| !profile.is_empty());
588+
pi_shell::config::apply_sandbox(None, sandbox_profile_arg, args.cwd.as_deref());
598589
let is_interactive = args.command.is_none()
599590
&& args.single.is_none()
600591
&& args.prompt_json.is_none()

‎tui/crates/codegen/pi-pager/docs/user-guide/17-sessions.md‎

Lines changed: 11 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -14,16 +14,23 @@ To see how much disk space the home directory uses, run `zypi du`.
1414
| --- | --- |
1515
| Start a new session | Run `/new` (alias `/clear`), or press `Ctrl+N` twice. |
1616
| Open the list of past sessions | Run `/resume`, or press `F3`. |
17-
| Continue the latest session of the current directory | Run `zypi -c`. |
18-
| Continue the latest session | Run `zypi --resume`. |
17+
| Continue the latest session of the current directory | Run `zypi -c` or `zypi --resume`. |
1918
| Continue a session by id or by title | Run `zypi --resume <id-or-title>`. |
2019
| Start a new session with an id that you choose | Run `zypi --session-id <uuid>`. |
2120

2221
The list of sessions shows the newest session first. The title of a session is its first message.
2322

24-
A title that you give to `--resume` matches the titles of the sessions of the current directory. The letter case does not matter. If more than one session has the same title, `zypi` can stop with an error. A value in the form of a UUID is always an id.
23+
When `zypi` starts, it asks the agent for the list of sessions. It does not read the session files. If the session that you name does not exist, `zypi` prints a message and stops with exit status 1. The terminal UI does not start.
2524

26-
A session id that you choose with `--session-id` must be a UUID. The id must not exist already. Do not use `--session-id` together with `--resume` or `-c`.
25+
The latest session is the session with the latest activity. This is the session that the agent wrote to last. It is not always the session that you created last.
26+
27+
An id that you give to `--resume` is found in every directory. The agent loads the session in the directory where the session started.
28+
29+
A title that you give to `--resume` matches the titles of the sessions of the current directory. The letter case does not matter. Spaces at the two ends of the title do not matter. If two sessions have the same title, `zypi` stops with an error. The error lists the ids and the time of the last activity of these sessions. Use `--resume <id>` then. A value in the form of a UUID is always an id.
30+
31+
A session id that you choose with `--session-id` must be a UUID. No session in any directory can have this id. To check this, `zypi` reads the whole list of sessions. If a session has the id, `zypi` prints `Session ID <id> is already in use.` and stops with exit status 1. Do not use `--session-id` together with `--resume` or `-c`.
32+
33+
The agent writes the file of a session when the session starts. A session in which you typed nothing has the title `(no messages)`. `zypi -c` takes such a session when it is the latest one.
2734

2835
## What a session keeps
2936

‎tui/crates/codegen/pi-pager/src/app/agent_view/mod.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1190,7 +1190,7 @@ pub struct AgentView {
11901190
/// (`TaskResult::SessionMetaFromDisk`). Drives the prompt-border inline
11911191
/// title and wins precedence for the OSC terminal title.
11921192
pub display_name: Option<String>,
1193-
/// Short title from shell `SessionSummaryGenerated` or `summary.json` on load/resume.
1193+
/// Short title from shell `SessionSummaryGenerated`.
11941194
/// Precedence in the dashboard title is below `display_name`, above first-prompt text.
11951195
pub generated_session_title: Option<String>,
11961196
/// Ultra-short summary of the most recent successful turn (shell

0 commit comments

Comments
 (0)