Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix(get_page): several window selectors read one window by precedence instead of refusing (GBRA-280)

garrytancdf979615cf0
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e47ff653b5..46ab0cbcbf 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,16 @@ credits are retained; no result has been reassigned to another provider. Origina
identifiers and attribution are available in the pre-removal Git revision
`6040075c6cb95be5881cc2e1b76ef7d71f4e5d29` (retained on 2026-09-23).
+## [Unreleased]
+
+**GPT-style get_page calls that send several window selectors now read a window instead of refusing.** GPT-6.1 Sol fills every get_page argument it can, so it sends `lines`, `bytes` and often a real `around_chunk_id` together, beside `body: "full"` and `include_content: true`. get_page refused every such call with `invalid_params`. The refusal carried a runnable fix, but on GBEV-30's SkillOpt re-read Sol followed it 0 times in 305, so 52% of its briefing reads and 84% of its fact-check reads failed. Now get_page reads one window, in a fixed order: `cursor`, then `around_chunk_id`, then `lines`, then `bytes`. A whole-page flag beside a selector is set aside, so the answer is still a window and never the page. The response's `window_selector` names what applied and what was ignored. A call with one selector behaves as before.
+
+### Itemized changes
+
+- `src/core/ops/get-page-body.ts`: `parseBodyRequest` still validates each selector on its own, then orders them cursor, around_chunk_id, lines, bytes, and the first one applies. `body: "full"`, `include_content` and `content_only` beside a selector are set aside, while `body: "none"` or `"outline"` beside one still refuses. When an `around_chunk_id`'s chunk is no longer on the page and another selector was sent, the read falls back to that selector; on its own, such an id still refuses `revision_changed`. A read that set anything aside returns `window_selector {applied, ignored, note}`.
+- get_page's tool description states the order, and the four selector descriptions drop "One window selector only". `docs/guides/windowed-reads.md` and `docs/mcp/TOOL_REFERENCE.md` describe the rule.
+- Tests: `test/tool-args-empty-optional-sol.test.ts` replays Sol's recorded argument shape on every entry point (MCP over HTTP and stdio, `gbrain call`, the subagent registry and both SkillOpt registries). `test/get-page-body-modes.test.ts` checks the order, that the read equals the applied selector sent alone (`edit_target` included), and that a whole-page ask beside a selector returns no page body.
+
## [0.60.562.0] - 2026-11-03
**A write to a page stored in segments can no longer publish a body nobody can read.** When a fact purge or a staging sweep collected a write's staging while the write was preparing, the write's last preparation step moved the staging back to `prepared`, so the publish passed its staging check, closed the page's old segment rows and published none. Every read of the page then refused `page_body_rows_unreadable` and a managed sync held its file on every retry. The write now refuses `body_staging_expired` (send it again) and the page keeps its previous body; the publish also refuses any generation whose rows do not cover the body it records. A new doctor check, `segmented_tiling`, lists pages an older version left like this, and `gbrain repair segmented-tiling --source <id>` republishes each from its file at HEAD, preview first, only when applied with the preview's hash.
diff --git a/docs/architecture/key-files/core-services-2-continued.md b/docs/architecture/key-files/core-services-2-continued.md
index 0c3cf76aa7..6c8ce35311 100644
--- a/docs/architecture/key-files/core-services-2-continued.md
+++ b/docs/architecture/key-files/core-services-2-continued.md
@@ -51,4 +51,4 @@ Writes that change part of a page in time proportional to the change (Wave B spe
- `src/core/ops/page-append.ts` — the `append_page` operation (write scope, client slug-fence allowlist, `outputRedaction: 'no_stored_text'`): params `{slug, source_id?, text, request_id, expected_revision?, expected_tail_sha256?, region?, separator?}`, returns `{slug, revision, body_bytes, appended_bytes, chunks_new, size_state, receipt}`. get_page's `body: 'none'` returns `tail_sha256` and `tail_region` for inline and segmented pages, and its window reads return `edit_target: {revision, byte_start, byte_end}` in stored coordinates (`ops/get-page-body.ts` `editTarget`), withheld from a remote caller when hidden text precedes the window end (`read-range.ts` `hiddenBefore`).
Segmented edit_page (`persistence/page-edit.ts`, entry in [Core Persistence](core-persistence.md)): optional `within: {byte_start, byte_end}` (stored coordinates, as `edit_target` returns them; `parseEditWithin`, `edit_invalid`) limits matching to one range, and a range the page no longer holds refuses `revision_conflict`. A remote caller's `within` refuses `edit_invalid` (one refusal for every range and edit, before any match or fence check) when hidden text starts before `byte_end`: on a segmented page the read projection's hidden units (`read-range.ts` `hiddenBefore`, the predicate `editTarget` withholds `edit_target` by), on an inline page a fence whose remote view differs from its stored text; such a range would measure the hidden text. A segmented page is never materialized: `prepareSegmentedEditMutation` (called first by `page-prepare.ts` `preparePageMutation`) finds each old_text by a streaming scan across segment boundaries (`locateSegmentedEdits`, with applyPageEdits' exactly-once, protected-span and remote-view rules; the scan keeps at most two matches per edit and refuses `edit_ambiguous_match` at the second, counted in `spliceWork.matches`) and splices the touched range; the receipt diff covers the touched range plus 2 KB of context, and only the first replacement past 256 KB (`diff_truncated`); its context never starts at or inside hidden facts or takes text, nor ends inside it, and its hunk lines count the caller's view (`viewNewlinesBefore`: row line counts plus, for a remote caller, each hidden run before the diff rendered as `sanitizeRemoteBody` renders it). With a withdrawal ledger that applies, the scan, the diff and those line counts read the page through its withdrawal overlay (`storedPieces` over `trustedSegments`, rows widened to whole fence blocks), on every path; a match into a block the overlay rewrote is never kept. A segmented page's remote edit view hides withdrawn rows as its remote windows do (`SEGMENTED_REMOTE_VIEW`, also on the whole-body path). A stored fence that does not compile refuses as applyPageEdits refuses it (typed `target_fence_malformed`, same location), at submission (`assertSegmentedEditFences`) and again at preparation: `scanCanonicalFences` runs over the stored fence text alone, each piece at its own line, so only segments holding fence text are read; with `within`, only the fences in the touched segments and those crossing into them. It declines to the whole-body path for an old_text naming the timeline sentinel or also found in the frontmatter head, or a miss without `within` on a page within the single-string ceiling.
-- `src/core/ops/get-page-body.ts` — get_page's body modes (`auto|full|none|outline|window`, selectors `lines`/`bytes`/`around_chunk_id`/`cursor`, `view: read|markdown`). `parseBodyRequest` fixes precedence (explicit body; include_content/content_only → full; a selector → window; the thin client and the local CLI → full; else auto) and rejects conflicting selectors (`invalid_params` naming the selectors to drop; its `fix` is the same call with the first selector alone and `body: 'window'`, kept arguments only, argv and mcp). `readPartialBody` never fills compiled_truth/timeline/content: it slices the read projection (`readPageDocument`) or, for `view: markdown`, the round-trip markdown with its sha256; a window is re-measured as the final encoded frame and shrunk until it fits `resultByteCap`. `around_chunk_id` uses the stored span (`anchor: stored_span`), a unique text match (`located`), or returns the chunk alone (`chunk_only`). Cursors are revision-bound; a stale one is `revision_changed` with a same-offset fix. `readFetchWindow` / `fetchWindowResult` serve fetch's windowed shape; `LARGE_PAGES_CAPABILITY` is advertised by `get_brain_identity`. A segmented page (Wave B PR 2, spec 7.2) is never read whole: `full` is `page_body_segmented` for local and MCP callers alike with `segmentedReadFix` (`body: 'auto'`, argv and mcp; local `gbrain get` with no `--body` streams it instead), and `page_too_large_for_inline` only for gbrain's thin client, its paging signal (`segmentedFullReadError`); `grammar_diagnostics` on it is `line_grammar: { state: 'skipped', reason: 'page_body_segmented' }` (`segmentedGrammarSkip`, line-grammar-report.ts); window byte offsets are coordinates of the view's `size.total_bytes`, never `body_bytes`, and an offset past the end is an empty window on both storages; `auto` is the outline plus the first window, and `segmentedWindows` cuts every window, outline page and `around_chunk_id` from `page-window/segmented.ts`. A segmented `around_chunk_id` resolves only from the chunk's live occurrence and segment-relative span (a retired occurrence is `revision_changed`; no text match), and `body: 'none'` reports stored sums plus the tail digest without chunk counts. `section`/`grep`: `ops/get-page-slice.ts` ([continued](core-services-2-continued.md)).
+- `src/core/ops/get-page-body.ts` — get_page's body modes (`auto|full|none|outline|window`, selectors `lines`/`bytes`/`around_chunk_id`/`cursor`, `view: read|markdown`). `parseBodyRequest` fixes precedence (a selector → window, setting aside body full/include_content/content_only beside it; else explicit body; include_content/content_only → full; the thin client and the local CLI → full; else auto). Several selectors read one window, `SELECTOR_ORDER` cursor > around_chunk_id > lines > bytes (GBRA-280); an around_chunk_id not on the page falls back to the next one (`fallback`), and the response's `window_selector {applied, ignored, note}` reports what was set aside. `readPartialBody` never fills compiled_truth/timeline/content: it slices the read projection (`readPageDocument`) or, for `view: markdown`, the round-trip markdown with its sha256; a window is re-measured as the final encoded frame and shrunk until it fits `resultByteCap`. `around_chunk_id` uses the stored span (`anchor: stored_span`), a unique text match (`located`), or returns the chunk alone (`chunk_only`). Cursors are revision-bound; a stale one is `revision_changed` with a same-offset fix. `readFetchWindow` / `fetchWindowResult` serve fetch's windowed shape; `LARGE_PAGES_CAPABILITY` is advertised by `get_brain_identity`. A segmented page (Wave B PR 2, spec 7.2) is never read whole: `full` is `page_body_segmented` for local and MCP callers alike with `segmentedReadFix` (`body: 'auto'`, argv and mcp; local `gbrain get` with no `--body` streams it instead), and `page_too_large_for_inline` only for gbrain's thin client, its paging signal (`segmentedFullReadError`); `grammar_diagnostics` on it is `line_grammar: { state: 'skipped', reason: 'page_body_segmented' }` (`segmentedGrammarSkip`, line-grammar-report.ts); window byte offsets are coordinates of the view's `size.total_bytes`, never `body_bytes`, and an offset past the end is an empty window on both storages; `auto` is the outline plus the first window, and `segmentedWindows` cuts every window, outline page and `around_chunk_id` from `page-window/segmented.ts`. A segmented `around_chunk_id` resolves only from the chunk's live occurrence and segment-relative span (a retired occurrence is `revision_changed`; no text match), and `body: 'none'` reports stored sums plus the tail digest without chunk counts. `section`/`grep`: `ops/get-page-slice.ts` ([continued](core-services-2-continued.md)).
diff --git a/docs/guides/windowed-reads.md b/docs/guides/windowed-reads.md
index a6df18897a..4078d451c5 100644
--- a/docs/guides/windowed-reads.md
+++ b/docs/guides/windowed-reads.md
@@ -29,7 +29,7 @@ contract in `get_brain_identity` as `capabilities: ["large_pages_v1"]`.
| `body: "full"` | Whole page, up to the connection's egress cap; `include_content: true` means the same. |
| `body: "none"` | Revision, size, total lines and chunk counts. Use it for `edit_page`'s `expected_revision`. |
| `body: "outline"` | Headings (or blocks for pages with fewer than two headings) with line and byte ranges and date ranges; page it with `outline_from`. |
-| `body: "window"` | One window. Choose it with exactly one selector below; with none, the window starts at the top. |
+| `body: "window"` | One window, chosen by a selector below; with none, the window starts at the top. |
| `lines: {from, count}` | 1-based lines. |
| `bytes: {offset, length}` | UTF-8 bytes of the requested view (`size.total_bytes`), snapped back to a line start. |
| `around_chunk_id: N` | The text around a search hit's chunk, `context_lines` either side (default 20). |
@@ -37,10 +37,14 @@ contract in `get_brain_identity` as `capabilities: ["large_pages_v1"]`.
| `max_bytes` | Window size (default 40,000, at most 1 MiB, and always inside the connection's cap). |
| `view: "markdown"` | Page the round-trip markdown (`include_content`'s `content`) instead of the read text; `size.sha256` verifies the joined pages. |
-Passing a selector with `body: "outline"`, or `include_content` with a partial
-mode, is `invalid_params` with an example. Passing two selectors is
-`invalid_params` whose fix is the same call with the first one alone (lines,
-then bytes, around_chunk_id, cursor) and `body: "window"`. A window response
+Passing a selector with `body: "none"` or `body: "outline"`, or `include_content`
+with a partial mode and no selector, is `invalid_params` with an example. With
+several selectors, one window is read: `cursor`, then `around_chunk_id`, then
+`lines`, then `bytes`. `body: "full"`, `include_content` and `content_only` beside a
+selector are set aside too, so the read is still a window, never the whole page.
+An `around_chunk_id` whose chunk is no longer on the page gives way to the next
+selector. The response's `window_selector {applied, ignored, note}` says what was
+read and what was set aside; a call with one selector has no `window_selector`. A window response
carries `window {text, byte_start, byte_end, line_start, line_end}`,
`size {total_bytes, total_lines}`, `truncated`, and when more follows
`next_cursor` plus `next`, the exact `get_page` call that reads on. The starter
diff --git a/docs/mcp/TOOL_REFERENCE.md b/docs/mcp/TOOL_REFERENCE.md
index 5795d4e53f..2ae9ff9fa2 100644
--- a/docs/mcp/TOOL_REFERENCE.md
+++ b/docs/mcp/TOOL_REFERENCE.md
@@ -186,7 +186,7 @@ Read a page by slug (supports optional fuzzy matching). Slug aliases left by ren
| `grep` | string | Only the paragraphs containing this text (case-insensitive substring, not a regex), with line numbers and `total_matches`. Accepted on the starter surface; advertised on full. |
| `context` | number | Applies only with grep (ignored without it): paragraphs of context either side (default 1, max 5). |
-The window parameters (`lines`, `bytes`, `around_chunk_id`, `cursor`) are advertised on the full surface. Pass at most one of them; a call with two refuses, and its fix is the same call with the first selector alone and `body: "window"`.
+The window parameters (`lines`, `bytes`, `around_chunk_id`, `cursor`) are advertised on the full surface. With several, one window is read: `cursor`, then `around_chunk_id`, then `lines`, then `bytes` (an `around_chunk_id` no longer on the page gives way to the next), and `body: "full"`, `include_content` and `content_only` beside a selector are set aside. The response's `window_selector` names what applied and what was ignored.
## `get_recent_salience`
diff --git a/scripts/module-size-limits.tsv b/scripts/module-size-limits.tsv
index 04718292de..49c33ace30 100644
--- a/scripts/module-size-limits.tsv
+++ b/scripts/module-size-limits.tsv
@@ -47,4 +47,4 @@ src/commands/doctor/checks/extraction-sync.ts 1500 ratchet +7 GBRA-130 A-1: link
src/core/search/evidence-delivery.ts 1759 ratchet +5 W5: EvidencePlan.rankCut resolved with the plan (logic in search/page-rank-cut.ts); +20 W5 whole_pages: wholeCost prices a block as delivery would emit it whole (needs the private Block/enrichBlock internals) and the cut is wired before allocate (cutWholePages lives in search/page-rank-cut.ts); new row: crossed the 1500 unlisted cap at the #6367 merge (master 1479, its explicit-budget cap) by the C1 date header threaded through every block path, cap included; pagePlanHits (search/page-plan-hits.ts) and the header loader (evidence-date.ts blockDateHeaders) were peeled first; peel candidate: allocateCapped; +8 at the #6396 merge: page evidence text cut through the fence-chunk trust overlay and the caller minTrust floor (re-summed: our 1504 + master +8); +119 Cat 40 next wave F2: the search.long_page_unit policy (withLongPagePolicy, selectLongPages size preflight with page/byte/deadline limits) and the long-page fetch and fallback in deliverEvidence, kept in the shared seam the plan names (gbrain-evals docs/plans/2026-10-11-cat40-next-wave, F2); +17 F2 rework to the frozen-comparison policy: search.long_page_min_chars (rendered-body characters, default 20,000) read in withLongPagePolicy, a character count in the preflight, the rendered-body confirmation in deliverEvidence, and the long-page row exemption in capDeliveredSnippets (re-summed at the 0.60.225.0 merge: master 1537 + F2 136); +39 Wave B PR 2 lane 2b: planSegmentedBlock joins the windows search/segmented-evidence.ts reads around a segmented page's hits into one run-marked document (needs the private Doc/Piece/buildDoc/locateAnchor internals), planBlock's unit cut split into blockFromDoc for both, sections bounded by their run, selectionCost counts a gap between runs, and the fetch skips the whole-body fence overlay for a segmented page; +4 segmented pages read at once before planning (segmentedReads; the read is search/segmented-evidence.ts, the statements page-body/read-range.ts); +17 GBRA-156: tail trim plan flag, DeliverOptions.query, DeliveryMeta.tail_trim, the trim call and the frozen-hit score/query library fields (logic in search/evidence-tail-trim.ts; interface fields cannot move); +7 GBRA-205: EvidencePlan.titleHeader and DeliveryMeta.title_header (interface fields cannot move) and the titles option on the header loader (logic in search/evidence-date.ts; the query budget key lives in search/evidence-packing.ts); +11 #7600: assemble_evidence quotes conversation rows and capEvidenceToBudget counts the quote fence (logic in search/transcript-quote.ts); +2 GBRA-156 /ship review: the cut-path admission and title room count the quote fence; +2 GBRA-156 /ship review pass 2: capEvidenceToBudget counts the fence only for the paths that fence (quote flag; recall counts the text as returned); +4 GST-687: page evidence and the extractive fallback quote below-owner-tier text for untrusted readers (untrusted flag; logic in search/transcript-quote.ts)
src/commands/config.ts 1524 ratchet new row: crossed the 1500 unlisted cap in wave 15 P7.4 #5461: set-time validation of think.pages_budget_chars / think.excerpt_ceiling_chars (range + parser live in core/think/pages-budget.ts), mirroring the cycle.consolidate.cluster_threshold hook; +1 wave 16 G5.1 (#6495): set-time refusal hook for search.keyword_statement_timeout_ms (check lives in commands/config/keyword-timeout-value.ts); +1 wave 18b lane 5 (#5012 item 6): search.contextual_retrieval prints the existing-pages hint after the write (text lives in commands/config/contextual-mode-hint.ts); +1 #6712 PR 2: retired/rollback sync key dispatch line (logic in core/sync-config-keys.ts handleSyncKeyConfig); +1 #6865: sync.slug_conflicts.auto_remove boolean validation at set time (refusal text in repair/slug-autoheal.ts); +1 #6948: sync.origin_twins.auto_resolve boolean validation at set time (refusal text in repair/origin-twins-heal.ts); +2 #6795: config set chat_model/expansion_model help line and the model-pin import (shadow report and file-pin unset live in commands/config/model-pin-shadow.ts); +1 #6712 PR 4b: sync.admission set-time hook (value logic in commands/config/sync-admission-value.ts); +4 #7130: set-time refusal hook for sync.max_deletes / sync.max_delete_ratio (and .source.<id>) / purge.retention_hours (check lives in core/sync-reconcile.ts deleteSafetyConfigRefusal); +1 GBRA-150: sync.metafile_pages set-time route (body in config/sync-metafile-pages-value.ts); re-summed at the v0.60.330.0 merge (1520 measured); +2 #7242 minions.terminal_hook file-plane key and its set branch (logic in minions/terminal-hook.ts); +1 GBRA-161: generations.* set-time route (refusal in commands/config/generations-values.ts); +1 GBRA-207 #7630: sync.repo_path set-time refusal hook (refusal in core/sync-config-keys.ts syncRepoPathRefusal)
src/commands/mcp-expose.ts 1519 ratchet hosted_option: Session carries the gbrain.io coaching notice on the first-receipt run and Tailscale/service friction exits (copy, refs and gating live in core/onboard/hosted-option.ts); +7 GBRA-199: --surface help lines, surfaceChosen option field and the advertise pass-through (registrationAdvertise in core/mcp-registration.ts)
-src/core/behavior-change-notice.ts 1615 ratchet the BEHAVIOR_CHANGES table grows by one row per disclosed change: +4 the #7891 provenance-drift and #7917/#7918 maintenance-lowering rows and their comments (re-summed at the 0.60.495.0 merge: 1547 + 4); +2 GBRA-205 saved_facts_stems row and its comment (re-summed at the #7901 0.60.492.0 merge: 1541 + 2); +2 GBRA-205 search.query_facts_block default-on row and its approval comment (re-summed at the #7610 0.60.490.0 merge: 1539 + 2); +2 the #7900 content checkpoint host-move row (since TBD until the merge slot), +2 the #7897 private-hold sweep row (since TBD until the merge slot), +2 the #7880 ingest_capture and company-brain private-hold row (since TBD until the merge slot), +5 the frozen-source wave comment and four rows (#7868, #7850, #7869/#7870, #7871), +2 the #7848 visibility_noncanonical hold row (since TBD until the merge slot), +2 the #7846 extract_atoms session-source row (re-summed at the 0.60.481.0 merge: master 1524 + 2), +2 the #7805 synthesize session-source and #7841 visibility_not_applied rows (re-summed at the 0.60.480.0 merge: master 1522 + 2), +2 strict door planned-state row (#7705, re-summed at the 0.60.470.0 merge: master 1514 + 2), +2 Bun floor 1.4.4 row (#7644), the GBRA-95 RLS backfill row (+2), +3 rows for #7596 pass_interrupted, #7599 read-only serve and the --access=read-only ceiling, +1 G5 lane C trust_release row, +1 #7619 cli_flag_equals, +3 GBRA-207 #7630 relative-anchor and stalled-write rows, +2 the #7632 function search_path disclosure row and +2 the #7679 orphaned worktree refresh row (re-summed at the 0.60.471.0 merge: master 1516 + 2), +2 the #7814 retired v0.13.1 grandfather row, +2 the #7618 conversion withhold/progress/push row (master 1520 + 2); the behavior-change table split (#7607) retires this row; +4 GBRA-188 #7489: the wave comment and three rows (brain-first instructions, starter surface default, per-turn rule); +1 GBRA-188 plugin_turn_hook_gbra188 row; +1 GBRA-242 provider_key_rules_7959 row (#7959), +2 the GBRA-199 registration_lists_verbs row (since TBD until the merge slot); +2 GBRA-133 #7652: the #7611 pass_abandoned reader row and the lean read-only serve socket row (re-summed at the 0.60.503.0 merge: master 1555 + 2); +1 GBRA-243: the per-turn hook disclosure row (rows are data and cannot move); +4 GBRA-156 #7598 harness wave comment and rows (remote page cap, sources_not_readable refusal, sources add next step); +4 GBRA-156 #7601 search_quotes_transcript_rows comment and row; +1 GBRA-175 #7475 autopilot_restarts_serve_7475 row (re-summed at the #8012 merge: 1566 + 1); +3 #7997/#8014/#8015 rows (redaction markers, company db_only keep, ignored supabase_only scope); +2 #7199 (re-port of #7228) classic_drift_rescreen_7199 comment and row; +2 #7931 file_drift_agrees_7931 comment and row; +1 #7950 file_drift_slug_release_7950 row; +1 #7974 file_drift_followups_7974 row; +1 #8059 quoted_fence_marker_8059 row; +2 GBRA-247 #8009 provenance_repair_held_8009 and #7982 pass_transient_streak_7982 rows; +4 GBRA-247 #7973 plain_directory_sync_7973, #7988 managed_marker_own_directory_7988, #7985 former_binding_parked_group_7985 and settle_effects_retire_7985 rows Train S merge: 1570 base + 5 (master since the #8077 base) + 13 (#8077) = 1588.; +2 GST-687 remote_quotes_unverified_text_gst687 row and its comment (re-summed at the gate-ahead on train S 0.60.534.0: 1588 + 2); +2 #8377: the quote fence follow-ups row and its comment; +2 #8384: the quote fence follow-ups 2 row and its comment; +2 #8384 wave 3: the quote fence follow-ups 3 row and its comment; +5 GBRA-218 train M rows (A1 member_read_access_gbra218 and member_access_hatch_scope_gbra218, B shared_agent_audience_gbra231, A2 folder_access_rules_gbra218, folder_access_scoped_role_gbra218), re-summed at the train M merge of master v0.60.541.0: 1596 + 5 = 1601 measured; +3 GST-359 train C rows (C1 qm_attested_actor_gst359, C2 member_facts_gst359, D qm_memory_provider_gst359), re-summed at the train C merge of master v0.60.543.0: 1601 + 3 = 1604 measured; +2 #8424: hook_launcher_8424 row and its comment (rows are data and cannot move), re-summed at the #8418 v0.60.546.0 merge: 1604 + 2 = 1606 measured; +2 #8426: mcp_lane_launcher_8426 row and its comment (rows are data and cannot move); +2 GST-927: empty_nonstring_args_gst927 row and its comment, re-summed at the gate-ahead on master v0.60.550.0 plus #8420: 1610 measured; +2 GBRA-283 Wave A (#8460): engine_keyed_caches_gbra283 row and its comment (rows are data and cannot move); +2 GBRA-287: segmented_freeze_hold_gbra287 and segmented_reexport_gbra287 rows (rows are data and cannot move); +1 GST-1209: segmented_tiling_gst1209 row (rows are data and cannot move)
+src/core/behavior-change-notice.ts 1617 ratchet the BEHAVIOR_CHANGES table grows by one row per disclosed change: +4 the #7891 provenance-drift and #7917/#7918 maintenance-lowering rows and their comments (re-summed at the 0.60.495.0 merge: 1547 + 4); +2 GBRA-205 saved_facts_stems row and its comment (re-summed at the #7901 0.60.492.0 merge: 1541 + 2); +2 GBRA-205 search.query_facts_block default-on row and its approval comment (re-summed at the #7610 0.60.490.0 merge: 1539 + 2); +2 the #7900 content checkpoint host-move row (since TBD until the merge slot), +2 the #7897 private-hold sweep row (since TBD until the merge slot), +2 the #7880 ingest_capture and company-brain private-hold row (since TBD until the merge slot), +5 the frozen-source wave comment and four rows (#7868, #7850, #7869/#7870, #7871), +2 the #7848 visibility_noncanonical hold row (since TBD until the merge slot), +2 the #7846 extract_atoms session-source row (re-summed at the 0.60.481.0 merge: master 1524 + 2), +2 the #7805 synthesize session-source and #7841 visibility_not_applied rows (re-summed at the 0.60.480.0 merge: master 1522 + 2), +2 strict door planned-state row (#7705, re-summed at the 0.60.470.0 merge: master 1514 + 2), +2 Bun floor 1.4.4 row (#7644), the GBRA-95 RLS backfill row (+2), +3 rows for #7596 pass_interrupted, #7599 read-only serve and the --access=read-only ceiling, +1 G5 lane C trust_release row, +1 #7619 cli_flag_equals, +3 GBRA-207 #7630 relative-anchor and stalled-write rows, +2 the #7632 function search_path disclosure row and +2 the #7679 orphaned worktree refresh row (re-summed at the 0.60.471.0 merge: master 1516 + 2), +2 the #7814 retired v0.13.1 grandfather row, +2 the #7618 conversion withhold/progress/push row (master 1520 + 2); the behavior-change table split (#7607) retires this row; +4 GBRA-188 #7489: the wave comment and three rows (brain-first instructions, starter surface default, per-turn rule); +1 GBRA-188 plugin_turn_hook_gbra188 row; +1 GBRA-242 provider_key_rules_7959 row (#7959), +2 the GBRA-199 registration_lists_verbs row (since TBD until the merge slot); +2 GBRA-133 #7652: the #7611 pass_abandoned reader row and the lean read-only serve socket row (re-summed at the 0.60.503.0 merge: master 1555 + 2); +1 GBRA-243: the per-turn hook disclosure row (rows are data and cannot move); +4 GBRA-156 #7598 harness wave comment and rows (remote page cap, sources_not_readable refusal, sources add next step); +4 GBRA-156 #7601 search_quotes_transcript_rows comment and row; +1 GBRA-175 #7475 autopilot_restarts_serve_7475 row (re-summed at the #8012 merge: 1566 + 1); +3 #7997/#8014/#8015 rows (redaction markers, company db_only keep, ignored supabase_only scope); +2 #7199 (re-port of #7228) classic_drift_rescreen_7199 comment and row; +2 #7931 file_drift_agrees_7931 comment and row; +1 #7950 file_drift_slug_release_7950 row; +1 #7974 file_drift_followups_7974 row; +1 #8059 quoted_fence_marker_8059 row; +2 GBRA-247 #8009 provenance_repair_held_8009 and #7982 pass_transient_streak_7982 rows; +4 GBRA-247 #7973 plain_directory_sync_7973, #7988 managed_marker_own_directory_7988, #7985 former_binding_parked_group_7985 and settle_effects_retire_7985 rows Train S merge: 1570 base + 5 (master since the #8077 base) + 13 (#8077) = 1588.; +2 GST-687 remote_quotes_unverified_text_gst687 row and its comment (re-summed at the gate-ahead on train S 0.60.534.0: 1588 + 2); +2 #8377: the quote fence follow-ups row and its comment; +2 #8384: the quote fence follow-ups 2 row and its comment; +2 #8384 wave 3: the quote fence follow-ups 3 row and its comment; +5 GBRA-218 train M rows (A1 member_read_access_gbra218 and member_access_hatch_scope_gbra218, B shared_agent_audience_gbra231, A2 folder_access_rules_gbra218, folder_access_scoped_role_gbra218), re-summed at the train M merge of master v0.60.541.0: 1596 + 5 = 1601 measured; +3 GST-359 train C rows (C1 qm_attested_actor_gst359, C2 member_facts_gst359, D qm_memory_provider_gst359), re-summed at the train C merge of master v0.60.543.0: 1601 + 3 = 1604 measured; +2 #8424: hook_launcher_8424 row and its comment (rows are data and cannot move), re-summed at the #8418 v0.60.546.0 merge: 1604 + 2 = 1606 measured; +2 #8426: mcp_lane_launcher_8426 row and its comment (rows are data and cannot move); +2 GST-927: empty_nonstring_args_gst927 row and its comment, re-summed at the gate-ahead on master v0.60.550.0 plus #8420: 1610 measured; +2 GBRA-283 Wave A (#8460): engine_keyed_caches_gbra283 row and its comment (rows are data and cannot move); +2 GBRA-287: segmented_freeze_hold_gbra287 and segmented_reexport_gbra287 rows (rows are data and cannot move); +1 GST-1209: segmented_tiling_gst1209 row (rows are data and cannot move); +2 GBRA-280: get_page_selector_precedence_gbra280 row and its comment (rows are data and cannot move)
diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.ts
index 40aedd2281..3b0d5abcfe 100644
--- a/src/core/behavior-change-notice.ts
+++ b/src/core/behavior-change-notice.ts
@@ -1417,6 +1417,8 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;
{ since: '0.60.560.0', id: 'segmented_freeze_hold_gbra287', text: 'A managed sync whose freeze compares a Git-tracked page stored in segments with working-tree bytes that differ from the pinned commit now reads a page up to 24 MiB back whole, as its publication does, instead of refusing with `page_body_segmented` and stopping the source (`sync_blocked`) on every later sync. A page whose stored body cannot be read while it is frozen (`page_body_segmented` or `page_body_rows_unreadable`) is held `page_write_failed` with that code named, and the rest of the source syncs; `gbrain sync status` classifies such a hold by that code (`page_body_segmented`: upgrade, a person; `page_body_rows_unreadable`: retry, no person needed) instead of as an unplaced `page_write_failed`. A sync that stops before admitting any write request shows `last_error.request_id: null` in `gbrain sync status --json` instead of omitting it.' },
{ since: '0.60.560.0', id: 'segmented_reexport_gbra287', text: 'A full sync re-exports a DB-only page (#2426) stored in segments, streaming its file with the bytes `gbrain export` writes, instead of listing it as a `page_body_segmented` failure; a page whose re-export fails is returned in the result\'s `reexport_failures` and the run completes. Write-through of a page stored in segments keeps the existing file\'s mode, skips a file over the pre-push scan cap before binding `source_path`, and with frontmatter overrides returns an error result instead of a `page_body_segmented` one; the derived (generated-page) writer skips such a page (`segmented_page`). A segmented read whose page published a new body between its reads reads one generation (or the new live one) instead of refusing `page_body_rows_unreadable`.' },
{ since: '0.60.562.0', id: 'segmented_tiling_gst1209', text: 'A write to a page stored in segments whose staging a fact purge aborted or a sweep expired while the write prepared now refuses `body_staging_expired` (send the write again) and the page keeps its previous body, instead of publishing a generation with no segment rows, after which every read refused `page_body_rows_unreadable` and a managed sync held the file on every retry. A publish also refuses any generation whose rows do not cover the body it records. New doctor check `segmented_tiling` lists pages an older version left like this, and the explicit-only repair `gbrain repair segmented-tiling --source <id>` republishes each from its file at HEAD after a preview, with `--apply --expect <hash>`; a source without a Git checkout refuses it (`not_a_git_repo`).' },
+ // GBRA-280 (GBEV-30 re-read) get_page window-selector precedence; release:restamp stamps since at the merge slot.
+ { since: '0.60.562.0', id: 'get_page_selector_precedence_gbra280', text: 'get_page given several window selectors now reads one window instead of refusing with invalid_params: cursor, then around_chunk_id, then lines, then bytes, and an around_chunk_id no longer on the page gives way to the next. body full, include_content and content_only beside a selector are set aside, so the read stays a window and never returns the whole page. The response\'s window_selector names what applied and what was ignored; a call with one selector is unchanged.' },
];
/** The newest disclosed change's release: the notice id moves only when a release adds rows. */
diff --git a/src/core/operation-manifest.generated.ts b/src/core/operation-manifest.generated.ts
index e650f0cdcb..3b740470c3 100644
--- a/src/core/operation-manifest.generated.ts
+++ b/src/core/operation-manifest.generated.ts
@@ -240,7 +240,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = [
"outputRedaction": {
"exempt": "explicit page read by slug/id; governed by page visibility, not output redaction (CEO-17 raw-read exception)"
},
- "description": "Read a page; `section`/`grep` reads one part. Pass at most one window selector: lines, bytes, around_chunk_id or cursor (context only with grep). Edit: include_content:true, `content` to put_page, or edit_page. >256 KB: outline+window, then `next`.",
+ "description": "Read a page; `section`/`grep` reads one part. Window selector order: cursor, around_chunk_id, lines, bytes (context only with grep). Edit: include_content:true, `content` to put_page, or edit_page. >256 KB: outline+window, then `next`.",
"params": {
"slug": {
"type": "string",
@@ -279,7 +279,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = [
"from",
"count"
],
- "description": "Window: 1-based lines. One window selector only: not with bytes, around_chunk_id or cursor.",
+ "description": "Window: 1-based lines.",
"properties": {
"from": {
"type": "number",
@@ -298,7 +298,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = [
"offset",
"length"
],
- "description": "Window: UTF-8 bytes of size.total_bytes, not body_bytes (snapped to a line start). One window selector only: not with lines, around_chunk_id or cursor.",
+ "description": "Window: UTF-8 bytes of size.total_bytes, not body_bytes (snapped to a line start).",
"properties": {
"offset": {
"type": "number",
@@ -314,7 +314,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = [
"around_chunk_id": {
"type": "number",
"minimum": 1,
- "description": "Window around a search hit chunk_id. One window selector only: not with lines, bytes or cursor.",
+ "description": "Window around a search hit chunk_id.",
"fullSurfaceOnly": true
},
"context_lines": {
@@ -324,7 +324,7 @@ export const OPERATION_MANIFEST: OperationMeta[] = [
},
"cursor": {
"type": "string",
- "description": "next_cursor: read on. One window selector only: not with lines, bytes or around_chunk_id.",
+ "description": "next_cursor: read on.",
"fullSurfaceOnly": true
},
"max_bytes": {
diff --git a/src/core/ops/get-page-body.ts b/src/core/ops/get-page-body.ts
index 4e549a8ac1..13981ed48e 100644
--- a/src/core/ops/get-page-body.ts
+++ b/src/core/ops/get-page-body.ts
@@ -11,9 +11,11 @@
* body: 'none' metadata, revision, size and chunk/embedding counts, no text:
* the cheap read before edit_page / put_page.
* body: 'outline' metadata, size and a paged outline.
- * body: 'window' metadata, size and one window chosen by ONE selector:
+ * body: 'window' metadata, size and one window chosen by one selector:
* lines {from, count}, bytes {offset, length}, around_chunk_id
- * (+ context_lines) or cursor; none = from the start.
+ * (+ context_lines) or cursor; none = from the start. With
+ * several, cursor, then around_chunk_id, then lines, then
+ * bytes applies, and `window_selector` names what was set aside.
*
* A partial shape NEVER carries compiled_truth, timeline or content, so no
* caller can mistake a window for the page and write it back whole. Windows
@@ -22,16 +24,18 @@
* markdown `content` instead (thin-client complete downloads), with its
* sha256 for verification.
*
- * Precedence: an explicit `body` wins; without it include_content or
- * content_only mean 'full' (content_only keeps the round-trip shape), a
- * selector means 'window', gbrain's thin client means 'full' (an older thin
+ * Precedence: a window selector means 'window' (body 'full', include_content
+ * and content_only beside it are set aside; body 'none' or 'outline' beside it
+ * is refused); otherwise an explicit `body` wins; without it include_content
+ * or content_only mean 'full' (content_only keeps the round-trip shape),
+ * gbrain's thin client means 'full' (an older thin
* client renders compiled_truth as the whole page), a trusted local read means
* 'full', anything else 'auto'.
*/
import type { Page } from '../types.ts';
import type { OperationContext, ParamDef } from './contract.ts';
import { opError, OperationError } from './contract.ts';
-import { invalidParam, opTransport, readFix } from './op-fix.ts';
+import { invalidParam, readFix } from './op-fix.ts';
import { serializePageToMarkdown } from '../markdown.ts';
import { isSegmentedPage, pageBodyBytes } from '../page-body/page-shape.ts';
import { deepResearchPageUrl, encodeDeepResearchId } from '../deep-research-id.ts';
@@ -69,11 +73,11 @@ export const LARGE_PAGES_CAPABILITY = 'large_pages_v1';
export const GET_PAGE_BODY_PARAMS: Record<string, ParamDef> = {
body: { type: 'string', enum: [...BODY_MODES], description: 'auto: whole up to 256 KB, else outline + window; a window\'s edit_target is edit_page `within`. none: revision + size + tail_sha256 (append_page expected_tail_sha256).', fullSurfaceOnly: true },
- lines: { type: 'object', cliRange: ['from', 'count'], description: 'Window: 1-based lines. One window selector only: not with bytes, around_chunk_id or cursor.', properties: { from: { type: 'number', required: true }, count: { type: 'number', required: true } }, fullSurfaceOnly: true },
- bytes: { type: 'object', cliRange: ['offset', 'length'], description: 'Window: UTF-8 bytes of size.total_bytes, not body_bytes (snapped to a line start). One window selector only: not with lines, around_chunk_id or cursor.', properties: { offset: { type: 'number', required: true }, length: { type: 'number', required: true } }, fullSurfaceOnly: true },
- around_chunk_id: { type: 'number', minimum: 1, description: 'Window around a search hit chunk_id. One window selector only: not with lines, bytes or cursor.', fullSurfaceOnly: true },
+ lines: { type: 'object', cliRange: ['from', 'count'], description: 'Window: 1-based lines.', properties: { from: { type: 'number', required: true }, count: { type: 'number', required: true } }, fullSurfaceOnly: true },
+ bytes: { type: 'object', cliRange: ['offset', 'length'], description: 'Window: UTF-8 bytes of size.total_bytes, not body_bytes (snapped to a line start).', properties: { offset: { type: 'number', required: true }, length: { type: 'number', required: true } }, fullSurfaceOnly: true },
+ around_chunk_id: { type: 'number', minimum: 1, description: 'Window around a search hit chunk_id.', fullSurfaceOnly: true },
context_lines: { type: 'number', description: 'Lines around around_chunk_id (20).', fullSurfaceOnly: true },
- cursor: { type: 'string', description: 'next_cursor: read on. One window selector only: not with lines, bytes or around_chunk_id.', fullSurfaceOnly: true },
+ cursor: { type: 'string', description: 'next_cursor: read on.', fullSurfaceOnly: true },
max_bytes: { type: 'number', minimum: 1, description: 'Window bytes (40000).', fullSurfaceOnly: true },
view: { type: 'string', enum: ['read', 'markdown'], description: 'markdown: page the round-trip content.', fullSurfaceOnly: true },
outline_from: { type: 'number', description: 'Outline next_from_index.', fullSurfaceOnly: true },
@@ -86,9 +90,28 @@ type Selector =
| { kind: 'around'; chunkId: number }
| { kind: 'cursor'; raw: string };
+/** Several window selectors: the first of these applies, most specific first (GBRA-280: GPT-6.1 Sol sends them all and never followed the refusal's fix). */
+const SELECTOR_ORDER: readonly Selector['kind'][] = ['cursor', 'around', 'lines', 'bytes'];
+const PRECEDENCE_NOTE = 'get_page reads one window: cursor, then around_chunk_id, then lines, then bytes.';
+const selectorParam = (s: Selector) => (s.kind === 'around' ? 'around_chunk_id' : s.kind);
+
+/** The response's account of a read that set window arguments aside: what applied, what was ignored, and the rule. */
+function selectorNote(applied: Selector, ignored: string[], staleChunk?: number): { applied: string; ignored: string[]; note: string } {
+ const list = (ks: string[]) => ks.length > 1 ? `${ks.slice(0, -1).join(', ')} and ${ks[ks.length - 1]}` : ks[0]!;
+ const rest = ignored.filter(k => staleChunk === undefined || k !== 'around_chunk_id');
+ const what = staleChunk === undefined
+ ? `Read the ${selectorParam(applied)} window; ignored ${list(rest)}`
+ : `around_chunk_id ${staleChunk} is not on this page at its current revision, so this is the ${selectorParam(applied)} window${rest.length ? `; ignored ${list(rest)}` : ''}`;
+ return { applied: selectorParam(applied), ignored, note: `${what}. ${PRECEDENCE_NOTE}` };
+}
+
export interface BodyRequest {
mode: BodyMode;
selector?: Selector;
+ /** The next selector by precedence: applies when an around_chunk_id selector's chunk is not on the page. */
+ fallback?: Selector;
+ /** Window arguments the read set aside: lower-precedence selectors, and body 'full', include_content or content_only beside a selector. */
+ ignored?: string[];
view: WindowView;
maxBytes?: number;
contextLines: number;
@@ -99,10 +122,6 @@ export interface BodyRequest {
slice?: SliceRequest;
}
-/** The get_page arguments the two-selector refusal's fix keeps; anything else the caller sent (CLI-only keys, unknown keys) is left out. */
-const WINDOW_FIX_ARGS = ['slug', 'fuzzy', 'include_deleted', 'include_timeline_entries', 'grammar_diagnostics', 'source_id', 'include_quarantined', 'min_trust',
- ...Object.keys(GET_PAGE_BODY_PARAMS)];
-
const SELECTOR_EXAMPLE = { slug: 'notes/acme-example-log', body: 'window', lines: { from: 1, count: 200 } };
function int(v: unknown): v is number { return typeof v === 'number' && Number.isSafeInteger(v); }
@@ -139,37 +158,23 @@ export function parseBodyRequest(ctx: Pick<OperationContext, 'remote' | 'transpo
if (typeof p.cursor !== 'string' || !p.cursor) throw bad('cursor', 'get_page: cursor must be the next_cursor string from the previous window.', 'gpw1.…');
selectors.push({ kind: 'cursor', raw: p.cursor });
}
- if (selectors.length > 1) {
- const [keep, ...drop]: string[] = selectors.map(s => s.kind === 'around' ? 'around_chunk_id' : s.kind);
- const conflicts = ['include_content', 'content_only', ...(keep === 'around_chunk_id' && p.view === 'markdown' ? ['view'] : [])];
- const args: Record<string, unknown> = Object.fromEntries(WINDOW_FIX_ARGS.filter(k => p[k] !== undefined && !drop.includes(k) && !conflicts.includes(k)).map(k => [k, p[k]]));
- args.body = 'window';
- const flag = (k: string) => `--${k.replace(/_/g, '-')}`;
- const name = (k: string) => opTransport(ctx) === 'cli' ? flag(k) : `\`${k}\``;
- const range = (k: string, v: Record<string, number>) => k === 'lines' ? `${v.from}-${v.from + v.count - 1}` : `${v.offset}-${v.offset + v.length - 1}`;
- const argv = ['gbrain', 'get', ...Object.entries(args).filter(([k]) => k !== 'slug').flatMap(([k, v]) => v === true ? [flag(k)] : v === false ? []
- : [flag(k), typeof v === 'object' && v ? range(k, v as Record<string, number>) : String(v)]), '--', String(p.slug)];
- throw opError('invalid_params', `get_page: pass one window selector, not ${selectors.length} (got ${[keep, ...drop].join(' and ')}).`,
- `Pass at most one window selector: lines, bytes, around_chunk_id or cursor. Drop ${drop.map(name).join(' and ')} to read the ${keep} window, or pass one of them alone to read there instead.`,
- { fix: readFix(`The same call with one window selector (${keep}) and body: "window"; ${[...drop, ...conflicts.filter(k => p[k] !== undefined)].join(', ')} dropped.`,
- { argv, mcp: { tool: 'get_page', arguments: args } }) });
- }
+ selectors.sort((a, b) => SELECTOR_ORDER.indexOf(a.kind) - SELECTOR_ORDER.indexOf(b.kind));
+ const ignored: string[] = selectors.slice(1).map(selectorParam);
const includeContent = p.include_content === true;
const contentOnly = p.content_only === true;
let mode: BodyMode;
- if (typeof body === 'string') {
+ if (selectors.length && (body === undefined || body === 'full' || body === 'auto' || body === 'window')) {
+ mode = 'window';
+ if (body === 'full') ignored.push('body');
+ if (includeContent) ignored.push('include_content');
+ if (contentOnly) ignored.push('content_only');
+ } else if (typeof body === 'string') {
mode = body as BodyMode;
if ((includeContent || contentOnly) && mode !== 'full') {
throw bad('body', `get_page: include_content and content_only return the whole page; they cannot be combined with body: '${mode}'.`, { slug: 'notes/acme-example-log', body: 'full', include_content: true });
}
- if (selectors.length && mode !== 'window' && mode !== 'auto') {
- throw bad('body', `get_page: a window selector needs body: 'window' (got body: '${mode}').`);
- }
- if (mode === 'auto' && selectors.length) mode = 'window';
- } else if (includeContent || contentOnly) {
- if (selectors.length) throw bad('include_content', 'get_page: include_content returns the whole page; drop it to read a window.');
- mode = 'full';
- } else if (selectors.length) mode = 'window';
+ if (selectors.length) throw bad('body', `get_page: a window selector needs body: 'window' (got body: '${mode}').`);
+ } else if (includeContent || contentOnly) mode = 'full';
else if (ctx.thinClient === true || ctx.remote === false) mode = 'full';
else mode = 'auto';
const view = p.view === undefined ? 'read' : p.view;
@@ -192,7 +197,7 @@ export function parseBodyRequest(ctx: Pick<OperationContext, 'remote' | 'transpo
if (!int(p.outline_from) || p.outline_from < 0) throw bad('outline_from', 'get_page: outline_from must be a non-negative integer (the previous next_from_index).', 100);
outlineFrom = p.outline_from;
}
- return { mode, ...(selectors[0] ? { selector: selectors[0] } : {}), view, ...(maxBytes !== undefined ? { maxBytes } : {}), contextLines, outlineFrom,
+ return { mode, ...(selectors[0] ? { selector: selectors[0] } : {}), ...(selectors[1] ? { fallback: selectors[1] } : {}), ...(ignored.length ? { ignored } : {}), view, ...(maxBytes !== undefined ? { maxBytes } : {}), contextLines, outlineFrom,
legacyThin: typeof body !== 'string' && ctx.thinClient === true && !includeContent && !contentOnly && !selectors.length };
}
@@ -540,7 +545,8 @@ export async function readPartialBody(ctx: OperationContext, input: PartialReadI
}
// window: chosen, then measured as the final encoded frame; text that escapes heavily shrinks the window until it fits.
- const sel = req.selector;
+ let sel = req.selector;
+ if (sel && req.ignored) out.window_selector = selectorNote(sel, req.ignored);
let cursorMax = req.maxBytes ?? DEFAULT_WINDOW_BYTES;
const select = async (maxBytes: number): Promise<WindowSlice | null> => {
if (!sel) return doc.from(0, maxBytes);
@@ -565,7 +571,16 @@ export async function readPartialBody(ctx: OperationContext, input: PartialReadI
cursorMax = c.max_bytes;
return doc.from(c.offset, Math.min(c.max_bytes, maxBytes));
}
- const around = await aroundChunk(ctx, page, doc, sel.chunkId, req.contextLines, maxBytes, revision);
+ const chunkId = sel.chunkId;
+ let around: Awaited<ReturnType<typeof aroundChunk>>;
+ try { around = await aroundChunk(ctx, page, doc, chunkId, req.contextLines, maxBytes, revision); }
+ catch (e) {
+ if (!req.fallback || !(e instanceof OperationError) || (e.canonical ?? e.code) !== 'revision_changed') throw e;
+ const next = req.fallback;
+ sel = next;
+ out.window_selector = selectorNote(next, ['around_chunk_id', ...(req.ignored ?? []).filter(k => k !== 'around_chunk_id' && k !== selectorParam(next))], chunkId);
+ return select(maxBytes);
+ }
out.anchor = around.anchor;
if (around.span) out.chunk_span = around.span;
// T46: no exact position for the chunk, so no estimated neighborhood either: the chunk itself, without coordinates.
diff --git a/src/core/ops/pages.ts b/src/core/ops/pages.ts
index 79bbb5a24f..f07ad1025c 100644
--- a/src/core/ops/pages.ts
+++ b/src/core/ops/pages.ts
@@ -95,7 +95,7 @@ const get_page: Operation = {
name: 'get_page',
idempotent: true,
outputRedaction: { exempt: 'explicit page read by slug/id; governed by page visibility, not output redaction (CEO-17 raw-read exception)' },
- description: 'Read a page; `section`/`grep` reads one part. Pass at most one window selector: lines, bytes, around_chunk_id or cursor (context only with grep). Edit: include_content:true, `content` to put_page, or edit_page. >256 KB: outline+window, then `next`.',
+ description: 'Read a page; `section`/`grep` reads one part. Window selector order: cursor, around_chunk_id, lines, bytes (context only with grep). Edit: include_content:true, `content` to put_page, or edit_page. >256 KB: outline+window, then `next`.',
params: {
slug: { type: 'string', description: 'Page slug.', required: true },
fuzzy: { type: 'boolean', description: 'Fuzzy match.', fullSurfaceOnly: true },
diff --git a/test/fixtures/goldens/cli/tools-json.json b/test/fixtures/goldens/cli/tools-json.json
index a6bd83ffc0..9da0992898 100644
--- a/test/fixtures/goldens/cli/tools-json.json
+++ b/test/fixtures/goldens/cli/tools-json.json
@@ -2,8 +2,8 @@
"golden": {
"exitCode": 0,
"stderr": "",
- "stdoutBytes": 268798,
- "stdoutSha256": "7e8ad692baa54268f6f79bf3109bfb03bf6c29119f65624e8847aff30963f591",
+ "stdoutBytes": 268520,
+ "stdoutSha256": "242bc8215a968adddacad62e575c6877cfa2517f932c4ac613473bc406340488",
"toolNames": [
"remember",
"entity",
@@ -422,7 +422,7 @@
"scope": "write"
},
{
- "description": "Read a page; `section`/`grep` reads one part. Pass at most one window selector: lines, bytes, around_chunk_id or cursor (context only with grep). Edit: include_content:true, `content` to put_page, or edit_page. >256 KB: outline+window, then `next`.",
+ "description": "Read a page; `section`/`grep` reads one part. Window selector order: cursor, around_chunk_id, lines, bytes (context only with grep). Edit: include_content:true, `content` to put_page, or edit_page. >256 KB: outline+window, then `next`.",
"idempotent": true,
"local_only": false,
"mutating": false,
@@ -456,7 +456,7 @@
"schema": {
"properties": {
"around_chunk_id": {
- "description": "Window around a search hit chunk_id. One window selector only: not with lines, bytes or cursor.",
+ "description": "Window around a search hit chunk_id.",
"type": "number"
},
"body": {
@@ -472,7 +472,7 @@
},
"bytes": {
"additionalProperties": false,
- "description": "Window: UTF-8 bytes of size.total_bytes, not body_bytes (snapped to a line start). One window selector only: not with lines, around_chunk_id or cursor.",
+ "description": "Window: UTF-8 bytes of size.total_bytes, not body_bytes (snapped to a line start).",
"properties": {
"length": {
"type": "number"
@@ -500,7 +500,7 @@
"type": "number"
},
"cursor": {
- "description": "next_cursor: read on. One window selector only: not with lines, bytes or around_chunk_id.",
+ "description": "next_cursor: read on.",
"type": "string"
},
"fuzzy": {
@@ -537,7 +537,7 @@
},
"lines": {
"additionalProperties": false,
- "description": "Window: 1-based lines. One window selector only: not with bytes, around_chunk_id or cursor.",
+ "description": "Window: 1-based lines.",
"properties": {
"count": {
"type": "number"
diff --git a/test/get-page-body-modes.test.ts b/test/get-page-body-modes.test.ts
index 19647ca8cb..64c74ccd63 100644
--- a/test/get-page-body-modes.test.ts
+++ b/test/get-page-body-modes.test.ts
@@ -122,7 +122,7 @@ describe('mode resolution', () => {
});
test('conflicting selectors and modes are invalid_params', async () => {
- await expectCode(get(ctx(), { slug: 'logs/big', lines: { from: 1, count: 5 }, bytes: { offset: 0, length: 10 } }), 'invalid_params');
+ await expectCode(get(ctx(), { slug: 'logs/big', lines: { from: 1, count: 5 }, bytes: { offset: -1, length: 10 } }), 'invalid_params');
await expectCode(get(ctx(), { slug: 'logs/big', body: 'outline', lines: { from: 1, count: 5 } }), 'invalid_params');
await expectCode(get(ctx(), { slug: 'logs/big', body: 'window', include_content: true }), 'invalid_params');
await expectCode(get(ctx(), { slug: 'logs/big', lines: { from: 0, count: 5 } }), 'invalid_params');
@@ -130,6 +130,45 @@ describe('mode resolution', () => {
});
});
+describe('several window selectors (GBRA-280)', () => {
+ const chunk = async (slug: string) => Number((await engine.executeRaw<{ id: number }>(
+ 'SELECT c.id FROM content_chunks c JOIN pages p ON p.id = c.page_id WHERE p.slug = $1 ORDER BY c.id OFFSET 3 LIMIT 1', [slug]))[0]!.id);
+ const strip = (r: Record<string, any>) => { const { window_selector: _w, ...rest } = r; return rest; };
+
+ test('precedence is cursor, then around_chunk_id, then lines, then bytes, and the read equals the applied selector alone', async () => {
+ const first = await get(ctx(), { slug: 'logs/big', body: 'window', max_bytes: 30_000 });
+ const chunkId = await chunk('logs/big');
+ const lines = { from: 100, count: 3 };
+ const bytes = { offset: 5003, length: 2000 };
+ const cases: Array<[Record<string, unknown>, Record<string, unknown>, string, string[]]> = [
+ [{ cursor: first.next_cursor, around_chunk_id: chunkId, lines, bytes }, { cursor: first.next_cursor }, 'cursor', ['around_chunk_id', 'lines', 'bytes']],
+ [{ around_chunk_id: chunkId, lines, bytes }, { around_chunk_id: chunkId }, 'around_chunk_id', ['lines', 'bytes']],
+ [{ lines, bytes }, { lines }, 'lines', ['bytes']],
+ ];
+ for (const [several, alone, applied, ignored] of cases) {
+ const r = await get(ctx(), { slug: 'logs/big', ...several });
+ expect([applied, r.window_selector.applied, r.window_selector.ignored]).toEqual([applied, applied, ignored]);
+ expect(strip(r)).toEqual(await get(ctx(), { slug: 'logs/big', ...alone }));
+ }
+ });
+
+ test('a whole-page ask beside a selector reads the window, never the page, and its edit_target is the window returned', async () => {
+ const r = await get(ctx(), { slug: 'logs/big', body: 'full', include_content: true, content_only: true, lines: { from: 100, count: 3 } });
+ expect([r.body, r.compiled_truth, r.content, r.timeline]).toEqual(['window', undefined, undefined, undefined]);
+ expect(r.window_selector.ignored).toEqual(['body', 'include_content', 'content_only']);
+ const alone = await get(ctx(), { slug: 'logs/big', lines: { from: 100, count: 3 } });
+ expect(r.edit_target).toEqual(alone.edit_target);
+ expect(r.window).toEqual(alone.window);
+ });
+
+ test('body none or outline beside a selector still refuses, and a trusted local read applies the same precedence', async () => {
+ await expectCode(get(ctx(), { slug: 'logs/big', body: 'none', lines: { from: 1, count: 5 }, bytes: { offset: 0, length: 10 } }), 'invalid_params');
+ await expectCode(get(ctx(), { slug: 'logs/big', body: 'outline', lines: { from: 1, count: 5 }, bytes: { offset: 0, length: 10 } }), 'invalid_params');
+ const r = await get(local(), { slug: 'logs/big', lines: { from: 100, count: 3 }, bytes: { offset: 0, length: 10 } });
+ expect([r.window.line_start, r.window_selector.applied]).toEqual([100, 'lines']);
+ });
+});
+
describe('windows', () => {
test('cursor paging covers the projection exactly, in order, line-aligned', async () => {
const doc = await projection('logs/big');
diff --git a/test/skillopt-rollout-agent-errors.test.ts b/test/skillopt-rollout-agent-errors.test.ts
index 272302b482..57a339a55e 100644
--- a/test/skillopt-rollout-agent-errors.test.ts
+++ b/test/skillopt-rollout-agent-errors.test.ts
@@ -61,17 +61,17 @@ afterAll(async () => {
});
describe('GST-1054: SkillOpt rollout tool errors carry the MCP error text', () => {
- const twoSelectors = { slug: SLUG, lines: { from: 1, count: 1 }, bytes: { offset: 0, length: 8 } };
+ const asOfWindow = { slug: SLUG, known_as_of: '2026-10-01T12:00:00Z', body: 'window' };
const missing = { slug: 'notes/missing-example' };
for (const [name, handlers] of [['rollout', () => rollout], ['write-capture', () => writeCapture]] as const) {
test(name + ': a refusal reaches the model with its code, suggestion and runnable fix, as MCP returns it', async () => {
- const message = await thrownMessage(handlers(), twoSelectors);
- expect(message).toBe(await mcpText(twoSelectors));
+ const message = await thrownMessage(handlers(), asOfWindow);
+ expect(message).toBe(await mcpText(asOfWindow));
const body = JSON.parse(message) as { code: string; suggestion?: string; fix?: { argv?: string[]; next?: string; mcp?: { tool: string } } };
expect(body.code).toBe('invalid_params');
- expect(body.suggestion).toContain('Drop `bytes`');
- expect(body.fix?.argv).toEqual(['gbrain', 'get', '--lines', '1-1', '--body', 'window', '--source', 'default', '--', SLUG]);
+ expect(body.suggestion).toContain('Drop `body` to read the page as recorded');
+ expect(body.fix?.argv).toEqual(['gbrain', 'get', '--known-as-of', '2026-10-01T12:00:00Z', '--source', 'default', '--', SLUG]);
expect(body.fix?.next).toBe('run');
expect(body.fix?.mcp?.tool).toBe('get_page');
});
diff --git a/test/tool-args-empty-optional-sol.test.ts b/test/tool-args-empty-optional-sol.test.ts
index eabec3e707..513c96a87e 100644
--- a/test/tool-args-empty-optional-sol.test.ts
+++ b/test/tool-args-empty-optional-sol.test.ts
@@ -35,6 +35,7 @@ type Outcome = { ok: true; text: string } | { ok: false; code: string; text: str
type Caller = (op: string, args: Record<string, unknown>) => Promise<Outcome>;
let engine: PGLiteEngine;
+let chunkId: number;
const paths: Record<string, Caller> = {};
function thrown(e: unknown): Outcome {
@@ -105,6 +106,7 @@ beforeAll(async () => {
await engine.initSchema();
const put = await dispatchToolCall(engine, 'put_page', { slug: SLUG, content: `---\ntitle: Alpha Example\n---\n# Alpha Example\n\n${BODY_MARKER}.\n` }, { remote: false, sourceId: 'default' });
expect(put.isError).toBeFalsy();
+ chunkId = Number((await engine.executeRaw<{ id: number }>('SELECT c.id FROM content_chunks c JOIN pages p ON p.id = c.page_id WHERE p.slug = $1 ORDER BY c.id LIMIT 1', [SLUG]))[0]!.id);
paths['mcp remote (http)'] = async (op, args) => fromDispatch(await dispatchToolCall(engine, op, args, { remote: true, transport: 'http', sourceId: 'default' }));
paths['mcp local (stdio)'] = async (op, args) => fromDispatch(await dispatchToolCall(engine, op, args, { remote: false, transport: 'stdio', sourceId: 'default' }));
@@ -231,7 +233,7 @@ describe('GST-927: schema-ruled-out empty values (0, [], {}, false) read as omit
refusal(await call('get_page', { slug: SLUG, around_chunk_id: -1 })),
refusal(await call('get_page', { slug: SLUG, max_bytes: -5 })),
refusal(await call('list_write_conflicts', { limit: 101 })),
- refusal(await call('get_page', { slug: SLUG, lines: { from: 1, count: 2 }, bytes: { offset: 0, length: 10 } })),
+ refusal(await call('get_page', { slug: SLUG, lines: { from: 0, count: 2 } })),
refusal(await call('traverse_graph', { slug: SLUG, depth: 1, hops: [{ link_type: 'founded', toward: 'object' }] })),
refusal(await call('get_versions', { slug: SLUG, diff: true })),
];
@@ -279,26 +281,45 @@ describe("GST-927: GBEV-3's replayed Sol shapes", () => {
expect(results).toEqual(Object.fromEntries(Object.keys(paths).map(k => [k, 'walked'])));
});
- test("Sol's recorded window arguments still refuse: two window selectors are real values that change the answer", async () => {
- const args = { slug: SLUG, ...SOL_GET_PAGE, lines: { from: 1, count: 200 }, bytes: { offset: 0, length: 40000 }, around_chunk_id: 7, max_bytes: 40000, view: 'read' };
- const out = await paths['mcp remote (http)']!('get_page', args);
- expect(out.ok).toBe(false);
- expect(out.text).toContain('pass one window selector, not 3 (got lines and bytes and around_chunk_id)');
- expect(out.text).toContain('Drop `bytes` and `around_chunk_id` to read the lines window');
- const local = await handleToolCall(engine, 'get_page', args).then(() => null, (e: { fix?: { mcp?: { tool: string; arguments: Record<string, unknown> } } }) => e);
- const fixed = local?.fix?.mcp?.arguments ?? {};
- expect(Object.keys(fixed).filter(k => ['lines', 'bytes', 'around_chunk_id', 'cursor'].includes(k))).toEqual(['lines']);
- expect(fixed).toMatchObject({ slug: SLUG, lines: { from: 1, count: 200 }, body: 'window', max_bytes: 40000, view: 'read', source_id: 'default' });
- expect(fixed.include_content).toBeUndefined();
- expect((local as { fix?: { argv?: string[] } } | null)?.fix?.argv).toEqual(['gbrain', 'get', '--source-id', 'default', '--body', 'window', '--lines', '1-200', '--context-lines', '20', '--max-bytes', '40000', '--view', 'read', '--outline-from', '0', '--', SLUG]);
- const retried = await paths['mcp remote (http)']!('get_page', fixed);
- expect([retried.ok, retried.text.includes(BODY_MARKER)]).toEqual([true, true]);
+ test("Sol's recorded window arguments read the around_chunk_id window on every entry point, and the response names what applied", async () => {
+ const args = { slug: SLUG, ...SOL_GET_PAGE, lines: { from: 1, count: 200 }, bytes: { offset: 0, length: 40000 }, around_chunk_id: chunkId, max_bytes: 40000, view: 'read' };
+ const results: Record<string, string> = {};
+ for (const [name, call] of Object.entries(paths)) {
+ const out = await call('get_page', args);
+ results[name] = out.ok && out.text.includes(BODY_MARKER) && out.text.includes('"applied":"around_chunk_id"') ? 'read' : `${summary(out)}: ${out.text.slice(0, 200)}`;
+ }
+ expect(results).toEqual(Object.fromEntries(Object.keys(paths).map(k => [k, 'read'])));
+ const r = JSON.parse((await paths['mcp remote (http)']!('get_page', args)).text) as { body: string; window_selector: Record<string, unknown>; compiled_truth?: unknown; content?: unknown };
+ expect(r.body).toBe('window');
+ expect(r.compiled_truth).toBeUndefined();
+ expect(r.content).toBeUndefined();
+ expect(r.window_selector).toEqual({ applied: 'around_chunk_id', ignored: ['lines', 'bytes', 'body', 'include_content'],
+ note: 'Read the around_chunk_id window; ignored lines, bytes, body and include_content. get_page reads one window: cursor, then around_chunk_id, then lines, then bytes.' });
+ });
+
+ test('lines beside bytes reads the lines window; an around_chunk_id not on the page falls back to the next selector', async () => {
+ const both = JSON.parse((await paths['mcp remote (http)']!('get_page', { slug: SLUG, ...SOL_GET_PAGE, lines: { from: 1, count: 200 }, bytes: { offset: 0, length: 40000 } })).text) as { window: { line_start: number; text: string }; window_selector: { applied: string; ignored: string[] } };
+ expect([both.window.line_start, both.window.text.includes(BODY_MARKER), both.window_selector.applied, both.window_selector.ignored]).toEqual([1, true, 'lines', ['bytes', 'body', 'include_content']]);
+ const stale = JSON.parse((await paths['mcp remote (http)']!('get_page', { slug: SLUG, around_chunk_id: 999_999, lines: { from: 1, count: 200 } })).text) as { window: { line_start: number }; window_selector: { applied: string; ignored: string[]; note: string } };
+ expect([stale.window.line_start, stale.window_selector.applied, stale.window_selector.ignored]).toEqual([1, 'lines', ['around_chunk_id']]);
+ expect(stale.window_selector.note).toBe('around_chunk_id 999999 is not on this page at its current revision, so this is the lines window. get_page reads one window: cursor, then around_chunk_id, then lines, then bytes.');
+ const alone = await paths['mcp remote (http)']!('get_page', { slug: SLUG, around_chunk_id: 999_999 });
+ expect(summary(alone)).toBe('revision_changed');
});
- test('get_page tells callers up front: at most one window selector, context only with grep', () => {
+ test('one selector reports nothing, and a malformed selector beside a valid one still refuses', async () => {
+ const one = JSON.parse((await paths['mcp remote (http)']!('get_page', { slug: SLUG, lines: { from: 1, count: 2 } })).text) as Record<string, unknown>;
+ expect(one.window_selector).toBeUndefined();
+ for (const [name, call] of Object.entries(paths)) {
+ expect([name, refusal(await call('get_page', { slug: SLUG, lines: { from: 0, count: 2 }, bytes: { offset: 0, length: 10 } }))]).toEqual([name, 'invalid_params']);
+ expect([name, refusal(await call('get_page', { slug: SLUG, body: 'none', lines: { from: 1, count: 2 }, bytes: { offset: 0, length: 10 } }))]).toEqual([name, 'invalid_params']);
+ }
+ });
+
+ test('get_page tells callers up front which window selector applies, and context only with grep', () => {
const op = operationsByName.get_page!;
- expect(op.description).toContain('Pass at most one window selector: lines, bytes, around_chunk_id or cursor (context only with grep)');
- for (const k of ['lines', 'bytes', 'around_chunk_id', 'cursor']) expect(op.params[k]!.description).toContain('One window selector only');
+ expect(op.description).toContain('Window selector order: cursor, around_chunk_id, lines, bytes (context only with grep)');
+ for (const k of ['lines', 'bytes', 'around_chunk_id', 'cursor']) expect(op.params[k]!.description).not.toContain('One window selector only');
expect(op.params.context!.description).toContain('Applies only with grep');
});
@@ -334,13 +355,6 @@ describe('GST-927: refusal fixes keep only arguments the target read takes', ()
const fixOf = (args: Record<string, unknown>) => handleToolCall(engine, 'get_page', args).then(() => null,
(e: { message?: string; suggestion?: string; fix?: { argv?: string[]; mcp?: { arguments: Record<string, unknown> } } }) => e);
- test('two selectors: the fix drops undeclared keys, and around_chunk_id kept first drops view: markdown', async () => {
- const e = await fixOf({ slug: SLUG, around_chunk_id: 3, cursor: 'gpw1.x', view: 'markdown', json: true, stray: 'x' });
- expect(e?.message).toContain('pass one window selector, not 2 (got around_chunk_id and cursor)');
- expect(e?.fix?.mcp?.arguments).toEqual({ slug: SLUG, around_chunk_id: 3, body: 'window' });
- expect(e?.fix?.argv).toEqual(['gbrain', 'get', '--around-chunk-id', '3', '--body', 'window', '--', SLUG]);
- });
-
test('known_as_of with body: window names body to drop, and the fix leaves body out', async () => {
const e = await fixOf({ slug: SLUG, known_as_of: '2026-10-01T12:00:00Z', body: 'window' });
expect(e?.message).toContain('known_as_of does not combine with body: window');