Luigit
repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

extensions/strata/SPEC.md

Raw
Rendered preview

Strata

Scope

A standalone Pi extension opens a local browser workspace for semantic review of local Git changes. Normal reviews require no forge account or SaaS dependency and never mutate code. Optional forge review may switch the checkout only after explicit confirmation and safety checks. The Pi model explains and organizes; deterministic code owns the diff, anchors, coverage, and review state.

Contract

  • /strata reviews tracked staged and unstaged changes against HEAD.
  • /strata --staged reviews the index against HEAD.
  • /strata --base REF reviews merge-base(REF, HEAD) through HEAD.
  • /strata cancel cancels generation and closes the workspace.
  • Argument completion exposes the supported options and cancel.
  • Git absence produces a startup warning through native PATH detection, not a subprocess.
  • Entry registration is thin; imports, Git collection, and model calls occur only on demand.
  • Existing browser review patterns from retired diff-review inform localhost lifecycle, authentication, and feedback, without restoring its obsolete state or package layout.

Snapshot and coverage

Capture an immutable diff with resolved base/head IDs and a content-derived snapshot ID. Assign deterministic hunk IDs in code. Handle text changes, deletions, additions, renames, and metadata-only changes. List untracked, binary, and protected files as omitted with reasons, never silently hide them. Never run Git external diffs or text conversion filters. Retain Git capture resource limits and never silently truncate. Model inputs use lossless XML: group consecutive hunks by file and retain original unified-diff text, deriving line numbers from hunk headers. XML entities preserve delimiters and whitespace; snapshots with XML-forbidden characters use explicit JSON-string encoding inside XML. Do not impose an arbitrary model-input byte ceiling or equate Pi's configured context budget with the provider's maximum. Provider context failures remain visible; response, question, and HTTP request limits remain enforced. The model returns only summaries, cohort/layer structure, hunk references, and optional simple flow diagrams. Validation requires every captured hunk exactly once, no unknown references, unique layer IDs, bounded text, and no extra keys. The original diff is never rewritten by the model.

Pi widget

Use one persistent, compact widget above the editor instead of Strata footer status and routine URL notifications. Use Pi theme colors and the verified Nerd Font layers-triple icon, U+F0F58. At ordinary terminal widths, use two lines: identity/state and essential review counts, followed by the clickable local review address and a contextual action hint. Keep the authenticated URL intact in the terminal hyperlink while displaying its short loopback address. Show source, reviewed/total hunks, layer count, and comment count when available, dropping secondary details before state or access on narrow terminals. Reflect actual collecting, planning, ready, answering, refreshing, stale, feedback-sent, error, and closed states. Update progress from browser draft saves and clear obsolete counts on snapshot replacement. A normal close leaves a closed/reopen indication; reload and session shutdown remove the widget and prevent late asynchronous updates from restoring it. Errors remain visible without hiding the active review link. Do not add polling, startup subprocesses, a separate dashboard, or new keyboard shortcuts. Expose the review URL and actionable failures through RPC notifications and no-turn custom message events in no-UI modes.

Browser

Code is the primary surface, with independently toggleable layer navigation and a single right drawer. Compact, accessible panel toggles sit at the far left and right of the top bar. Details, Ask, and Feedback share the drawer as separate tabs, not stacked panels. Closing a panel returns its width to the code; narrow layouts must preserve access to every control. Hunk summaries remain in the code view; detailed explanation and optional dependency order remain in Details. Expose all-changes navigation, coverage counts, omitted paths, reviewed progress, and snapshot state. Changing the visible hunk synchronizes its explanation. Support keyboard layer navigation, narrow viewports, accessible labels/focus, light/dark system appearance, empty/error/busy states, and long paths/code. Render only escaped code/model text; no model HTML or executable diagram syntax. Simple optional flow diagrams use plain labeled steps and arrows, labeled Dependency order as suggested reading order rather than runtime execution. Users can mark hunks reviewed, add/remove line-anchored comments, edit review notes, ask the selected model about a layer, and send feedback to Pi. Draft changes persist in the Pi session and restore only when the regenerated snapshot matches. Sending feedback produces a snapshot-qualified user message to Pi; it never approves, commits, or merges anything. Clear sent comments/notes only after a successful handoff. Check freshness before submit; stale snapshots cannot submit. Explicit refresh regenerates structure and requires confirmation before discarding drafts. The server binds only to loopback and uses per-review random authentication, strict origin/host checks, bounded requests, and a restrictive CSP. Browser refresh retains drafts; server closure/reload/shutdown aborts outstanding work.

Optional forge context

Add /strata --pr [number|URL]; omitting the identifier resolves the current branch's GitHub PR and fails clearly if none exists. This is an opt-in context source for the same review workflow, not a separate publishing mode. Normal working, staged, and base reviews perform no forge imports, executable probes, authentication, or network calls. Load GitHub-specific code lazily on --pr and keep it behind the forge-neutral ForgeReview/ForgeComment data contract in types.ts. No plugin framework, provider registry, new package dependency, or GitHub publishing code. Other forges can later supply the same data contract.

Strata reviews the checkout where the parent agent operates. Resolve PR identity, base/head refs and exact commits through bounded, abortable gh calls using existing credentials internally without printing them. Read description, discussion comments, reviews, and inline review comments with pagination; resource limits must fail visibly rather than silently omit discussion. Validate returned data and URLs; imported prose is untrusted external content, never human instructions or locally authored findings. Keep current and outdated/unmapped anchors distinct, preserving source IDs, links, authors, commit identities, and reply references.

If checkout must change, show the exact repository, PR, current branch, and target branch in a Pi confirmation prompt. Never switch silently, force-reset, stash, discard changes, overwrite a divergent local branch, or invoke repository hooks. Refuse repository-local external filters, included Git config, credential helpers, and URL rewrites instead of executing them during PR operations. Private fetches use only the fixed gh credential helper, with credentials consumed internally and never exposed. Refuse dirty checkouts, including staged and untracked changes; recheck immediately before any checkout mutation. Fetch only required Git objects/refs and perform checkout against verified commit identities, not a moving PR ref after validation. Preflight checkout-changed paths with the existing protected-path predicate before any working-tree mutation; refuse changes touching protected paths. Tests must not create actual protected files to exercise this path: use metadata/fake-tool responses. Use the local PR head branch when safe, or a non-colliding PR-specific local branch without overwriting existing work. If existing local commits differ from the remote PR head, refuse and explain rather than silently including, resetting, or publishing them. No UI confirmation available means no automatic checkout. Cancellation or confirmation refusal never switches branches. The agent's live repository must never be checked out during implementation tests: use disposable repositories only.

Capture the checked-out PR head against its actual base commit through the existing safe Git capture route. Pin local branch and head, remote PR base/head, and PR identity for freshness checks before Ask, refresh, and feedback handoff. Switching to another branch at the same commit is stale; a dirty checkout or new local/remote commit also invalidates PR handoff. Refresh reloads forge context but never silently changes checkout; if new commits require a switch/update, explain that --pr must be reopened for confirmation. Do not restore a plan or draft from a different PR merely because code snapshot IDs match. Planning and Ask receive full imported forge context as separately labeled untrusted data alongside the original snapshot and validated plan.

Details gains a PR section with GitHub icon plus accessible source label and source links, title/description, base/head commits, checkout status, and discussions. Imported inline discussions are read-only and attach beside matching captured path/side/line anchors only when the forge reports a current mapping for the pinned PR snapshot. A discussion's original authored commit may precede the current PR head; preserve that identity without incorrectly marking its current mapping outdated. The snapshot base is the merge base, not necessarily the PR base-branch tip. Outdated or unmapped discussion remains labeled in Details, never guessed onto a line. Omitted remains reserved for files excluded from the diff, not checkout/PR metadata. Preserve the agreed keyboard navigation, focus, contextual guides, mobile layout, and native controls.

Feedback uses the latest reviewed snapshot and carries forge repository/PR identity, URL, local branch, exact base/head commits, source discussion references, and only the human's newly authored findings/notes as findings. Normal agent follow-up may inspect and edit the checked-out branch, just as ordinary Strata feedback does. Publishing comments is the agent's job through its existing tools, only after user approval and rechecking remote commits/anchors. Submitting feedback to Pi is not permission to publish to the forge.

Verification includes native Git fixtures plus controlled fake gh binaries on PATH exercising the real adapter/extension path, not only mocked helpers. Cover normal no-gh behavior, explicit/current-branch PR resolution, pagination and malformed/unsafe data, missing tools/auth failures, cancellation, denied checkout, dirty/divergent/protected-change refusal, safe accepted checkout, fork PR identity, stale branch/head checks, latest-snapshot feedback, PR-scoped persistence, imported-context model input, and no forge writes. Browser E2E must cover optional PR UI, source attribution, exact and outdated anchors, inert hostile content/URLs, imported-versus-local feedback separation, keyboard access, and desktop/mobile appearance.

Browser keyboard review

Use the accepted contextual-keyboard design: remove the sidebar J/K badge, retain the existing three-pane workspace, and add a compact mode/cursor strip without replacing operation status or errors. Visibly distinguish the focused pane and focused diff line using more than color alone. Show shortcut hints beside the layer-review action and the focused hunk's review action, not beside every hunk. Show a pending sequence and its available continuations after Space, g, [, or ]; Escape cancels the sequence. The Space guide groups review, writing, and workspace actions; ? opens complete keyboard help. Native text entry hides navigation guidance and shows an Escape return hint. Help and confirmation dialogs remain keyboard-operable, dismissible, and focus-contained. Keep mouse controls and native Tab, Enter, Space, and form behavior available.

Keys Action
j / k Focus next / previous anchorable diff line; in side panes, scroll that pane
h / l Scroll the focused pane horizontally
Ctrl+d / Ctrl+u Scroll the focused pane half a page
gg / G First / last diff line, or top / bottom of the focused side pane
]c / [c Next / previous hunk in the selected scope
]l / [l Next / previous layer
]u / [u Next / previous unreviewed hunk in the selected scope
/, n / N Literal, case-insensitive search of visible diff lines; next / previous matching line
Space h / Space l Focus previous / next visible pane
gd / ga / gf Open Details / Ask / Feedback
Space r / Space R Toggle focused hunk / selected whole layer reviewed
Space c / Space a / Space n Comment on focused line / compose question / edit notes
Space b / Space d Toggle layer sidebar / drawer
Space s / Space f / Space q Confirm feedback submission / snapshot refresh / review closure
? / Escape Open help / dismiss current transient UI or return from text entry to diff navigation

Navigation stays within bounds without wrapping; search repeat wraps through matching lines. Hunk and line navigation must keep the target visible, synchronize Details and Ask focus, and resist scroll observers overriding an explicit jump inside a large hunk. Whole-layer review marks all member hunks, including already-reviewed members, in one existing draft-save operation; when all are reviewed, it unmarks them all. All changes is not a layer: disable the whole-layer action there rather than silently reviewing the entire snapshot. Keep other layers' review state, comments, notes, and scope drafts intact. Route mouse and keyboard review mutations through the same existing persistence and error handling. Refresh, submit, and close use one shared confirmation route per action for both mouse and keyboard, without duplicate prompts or bypassing stale/draft checks. Cancel confirmations without mutating data or sending requests. Ignore navigation/action keys during IME composition, in editable controls, or with unrelated modifiers; only Escape may return from text entry, and Shift+Enter retains its existing Ask submission behavior. Native control activation must not be consumed as a Space leader sequence. Busy, empty, stale, hidden-pane, and refreshed-snapshot states must not permit invalid actions or stale line references. Use bounded DOM work and existing browser primitives; no dependencies, editor framework, compatibility dispatch, or server API changes.

Ask

Ask receives the complete captured diff and review plan, the explicit selected scope, the focused hunk, and that scope's conversation history. Layer scope and hunk focus are distinct: scrolling changes focus, not the thread. All changes has its own review-wide thread and must never silently select the focused hunk's layer. Each layer has a separate thread; switching scope restores its messages and unsent question. The server owns completed conversation history for the lifetime of the review; browser reload restores it, while snapshot refresh clears it. A reply belongs to the scope and hunk captured when the question was sent, even if navigation changes before completion. The model may inspect live filesystem evidence using read, grep, and ls through Pi's model registry. Relative paths resolve from the reviewed repository; absolute paths may reach installed packages, node_modules, external documentation, and other non-protected files. These tools are not limited to tracked files or Git revisions. Live filesystem results are explicitly labeled as current evidence, not immutable snapshot content. Enforce protected-file checks before content access, including directory ancestors and resolved symlink targets; safe dependency symlinks remain usable. Do not expose Git internals as an alternate route to protected content. Bound each tool's reads, traversal, matches, and returned bytes; allow line pagination and targeted searches inside ignored dependency directories. Do not impose cumulative tool-call, round, or result-byte budgets on Ask. Continue until the model answers, the provider fails, or the request is cancelled; check cancellation before each model request and tool execution. Prefer existing native tool implementations where their boundaries can be enforced before content access. Do not grant shell or mutation tools. Tool and answer errors, resource limits, unavailable source, and stale snapshots remain visible rather than silently dropping context. The Ask transcript scrolls independently above a bottom composer. Shift+Enter sends; Enter inserts a newline; the Send button uses the same submission route. Show the thread scope and focused hunk beside the composer or transcript so context is explicit. Preserve typed text on failure and prevent duplicate submissions. Strata retains the model selected when the workspace opened for both planning and Ask.

Verification

Real Git fixtures cover each source, special paths, renames, binary/metadata changes, omitted paths, limits, and snapshot changes. Strict plan validation exercises complete coverage and malformed model output. Real Pi extension-runtime tests use a controlled registered provider and exercise command, persistence, cancellation, and feedback. HTTP tests exercise authentication, origin validation, input validation, stale-submit refusal, save/ask/refresh/submit/close, and cancellation. Chromium and Firefox E2E use the real server with deterministic model output to exercise navigation, explanation sync, flow rendering, drafts, chat, refresh, stale state, feedback, and responsive layout. Run extension-local lint/test/check and browser tests, then the repository CI gate. Current behavior is proved by fresh checks, not historical test claims.

# Strata

## Scope

A standalone Pi extension opens a local browser workspace for semantic review of local Git changes.
Normal reviews require no forge account or SaaS dependency and never mutate code.
Optional forge review may switch the checkout only after explicit confirmation and safety checks.
The Pi model explains and organizes; deterministic code owns the diff, anchors, coverage, and review state.

## Contract

- `/strata` reviews tracked staged and unstaged changes against HEAD.
- `/strata --staged` reviews the index against HEAD.
- `/strata --base REF` reviews merge-base(REF, HEAD) through HEAD.
- `/strata cancel` cancels generation and closes the workspace.
- Argument completion exposes the supported options and cancel.
- Git absence produces a startup warning through native PATH detection, not a subprocess.
- Entry registration is thin; imports, Git collection, and model calls occur only on demand.
- Existing browser review patterns from retired diff-review inform localhost lifecycle, authentication, and feedback, without restoring its obsolete state or package layout.

## Snapshot and coverage

Capture an immutable diff with resolved base/head IDs and a content-derived snapshot ID.
Assign deterministic hunk IDs in code.
Handle text changes, deletions, additions, renames, and metadata-only changes.
List untracked, binary, and protected files as omitted with reasons, never silently hide them.
Never run Git external diffs or text conversion filters.
Retain Git capture resource limits and never silently truncate.
Model inputs use lossless XML: group consecutive hunks by file and retain original unified-diff text, deriving line numbers from hunk headers.
XML entities preserve delimiters and whitespace; snapshots with XML-forbidden characters use explicit JSON-string encoding inside XML.
Do not impose an arbitrary model-input byte ceiling or equate Pi's configured context budget with the provider's maximum.
Provider context failures remain visible; response, question, and HTTP request limits remain enforced.
The model returns only summaries, cohort/layer structure, hunk references, and optional simple flow diagrams.
Validation requires every captured hunk exactly once, no unknown references, unique layer IDs, bounded text, and no extra keys.
The original diff is never rewritten by the model.

## Pi widget

Use one persistent, compact widget above the editor instead of Strata footer status and routine URL notifications.
Use Pi theme colors and the verified Nerd Font layers-triple icon, U+F0F58.
At ordinary terminal widths, use two lines: identity/state and essential review counts, followed by the clickable local review address and a contextual action hint.
Keep the authenticated URL intact in the terminal hyperlink while displaying its short loopback address.
Show source, reviewed/total hunks, layer count, and comment count when available, dropping secondary details before state or access on narrow terminals.
Reflect actual collecting, planning, ready, answering, refreshing, stale, feedback-sent, error, and closed states.
Update progress from browser draft saves and clear obsolete counts on snapshot replacement.
A normal close leaves a closed/reopen indication; reload and session shutdown remove the widget and prevent late asynchronous updates from restoring it.
Errors remain visible without hiding the active review link.
Do not add polling, startup subprocesses, a separate dashboard, or new keyboard shortcuts.
Expose the review URL and actionable failures through RPC notifications and no-turn custom message events in no-UI modes.

## Browser

Code is the primary surface, with independently toggleable layer navigation and a single right drawer.
Compact, accessible panel toggles sit at the far left and right of the top bar.
Details, Ask, and Feedback share the drawer as separate tabs, not stacked panels.
Closing a panel returns its width to the code; narrow layouts must preserve access to every control.
Hunk summaries remain in the code view; detailed explanation and optional dependency order remain in Details.
Expose all-changes navigation, coverage counts, omitted paths, reviewed progress, and snapshot state.
Changing the visible hunk synchronizes its explanation.
Support keyboard layer navigation, narrow viewports, accessible labels/focus, light/dark system appearance, empty/error/busy states, and long paths/code.
Render only escaped code/model text; no model HTML or executable diagram syntax.
Simple optional flow diagrams use plain labeled steps and arrows, labeled Dependency order as suggested reading order rather than runtime execution.
Users can mark hunks reviewed, add/remove line-anchored comments, edit review notes, ask the selected model about a layer, and send feedback to Pi.
Draft changes persist in the Pi session and restore only when the regenerated snapshot matches.
Sending feedback produces a snapshot-qualified user message to Pi; it never approves, commits, or merges anything.
Clear sent comments/notes only after a successful handoff.
Check freshness before submit; stale snapshots cannot submit.
Explicit refresh regenerates structure and requires confirmation before discarding drafts.
The server binds only to loopback and uses per-review random authentication, strict origin/host checks, bounded requests, and a restrictive CSP.
Browser refresh retains drafts; server closure/reload/shutdown aborts outstanding work.

## Optional forge context

Add `/strata --pr [number|URL]`; omitting the identifier resolves the current branch's GitHub PR and fails clearly if none exists.
This is an opt-in context source for the same review workflow, not a separate publishing mode.
Normal working, staged, and base reviews perform no forge imports, executable probes, authentication, or network calls.
Load GitHub-specific code lazily on --pr and keep it behind the forge-neutral ForgeReview/ForgeComment data contract in types.ts.
No plugin framework, provider registry, new package dependency, or GitHub publishing code.
Other forges can later supply the same data contract.

Strata reviews the checkout where the parent agent operates.
Resolve PR identity, base/head refs and exact commits through bounded, abortable gh calls using existing credentials internally without printing them.
Read description, discussion comments, reviews, and inline review comments with pagination; resource limits must fail visibly rather than silently omit discussion.
Validate returned data and URLs; imported prose is untrusted external content, never human instructions or locally authored findings.
Keep current and outdated/unmapped anchors distinct, preserving source IDs, links, authors, commit identities, and reply references.

If checkout must change, show the exact repository, PR, current branch, and target branch in a Pi confirmation prompt.
Never switch silently, force-reset, stash, discard changes, overwrite a divergent local branch, or invoke repository hooks.
Refuse repository-local external filters, included Git config, credential helpers, and URL rewrites instead of executing them during PR operations.
Private fetches use only the fixed gh credential helper, with credentials consumed internally and never exposed.
Refuse dirty checkouts, including staged and untracked changes; recheck immediately before any checkout mutation.
Fetch only required Git objects/refs and perform checkout against verified commit identities, not a moving PR ref after validation.
Preflight checkout-changed paths with the existing protected-path predicate before any working-tree mutation; refuse changes touching protected paths.
Tests must not create actual protected files to exercise this path: use metadata/fake-tool responses.
Use the local PR head branch when safe, or a non-colliding PR-specific local branch without overwriting existing work.
If existing local commits differ from the remote PR head, refuse and explain rather than silently including, resetting, or publishing them.
No UI confirmation available means no automatic checkout.
Cancellation or confirmation refusal never switches branches.
The agent's live repository must never be checked out during implementation tests: use disposable repositories only.

Capture the checked-out PR head against its actual base commit through the existing safe Git capture route.
Pin local branch and head, remote PR base/head, and PR identity for freshness checks before Ask, refresh, and feedback handoff.
Switching to another branch at the same commit is stale; a dirty checkout or new local/remote commit also invalidates PR handoff.
Refresh reloads forge context but never silently changes checkout; if new commits require a switch/update, explain that --pr must be reopened for confirmation.
Do not restore a plan or draft from a different PR merely because code snapshot IDs match.
Planning and Ask receive full imported forge context as separately labeled untrusted data alongside the original snapshot and validated plan.

Details gains a PR section with GitHub icon plus accessible source label and source links, title/description, base/head commits, checkout status, and discussions.
Imported inline discussions are read-only and attach beside matching captured path/side/line anchors only when the forge reports a current mapping for the pinned PR snapshot.
A discussion's original authored commit may precede the current PR head; preserve that identity without incorrectly marking its current mapping outdated.
The snapshot base is the merge base, not necessarily the PR base-branch tip.
Outdated or unmapped discussion remains labeled in Details, never guessed onto a line.
Omitted remains reserved for files excluded from the diff, not checkout/PR metadata.
Preserve the agreed keyboard navigation, focus, contextual guides, mobile layout, and native controls.

Feedback uses the latest reviewed snapshot and carries forge repository/PR identity, URL, local branch, exact base/head commits, source discussion references, and only the human's newly authored findings/notes as findings.
Normal agent follow-up may inspect and edit the checked-out branch, just as ordinary Strata feedback does.
Publishing comments is the agent's job through its existing tools, only after user approval and rechecking remote commits/anchors.
Submitting feedback to Pi is not permission to publish to the forge.

Verification includes native Git fixtures plus controlled fake gh binaries on PATH exercising the real adapter/extension path, not only mocked helpers.
Cover normal no-gh behavior, explicit/current-branch PR resolution, pagination and malformed/unsafe data, missing tools/auth failures, cancellation, denied checkout, dirty/divergent/protected-change refusal, safe accepted checkout, fork PR identity, stale branch/head checks, latest-snapshot feedback, PR-scoped persistence, imported-context model input, and no forge writes.
Browser E2E must cover optional PR UI, source attribution, exact and outdated anchors, inert hostile content/URLs, imported-versus-local feedback separation, keyboard access, and desktop/mobile appearance.

## Browser keyboard review

Use the accepted contextual-keyboard design: remove the sidebar J/K badge, retain the existing three-pane workspace, and add a compact mode/cursor strip without replacing operation status or errors.
Visibly distinguish the focused pane and focused diff line using more than color alone.
Show shortcut hints beside the layer-review action and the focused hunk's review action, not beside every hunk.
Show a pending sequence and its available continuations after Space, g, [, or ]; Escape cancels the sequence.
The Space guide groups review, writing, and workspace actions; ? opens complete keyboard help.
Native text entry hides navigation guidance and shows an Escape return hint.
Help and confirmation dialogs remain keyboard-operable, dismissible, and focus-contained.
Keep mouse controls and native Tab, Enter, Space, and form behavior available.

| Keys | Action |
| --- | --- |
| j / k | Focus next / previous anchorable diff line; in side panes, scroll that pane |
| h / l | Scroll the focused pane horizontally |
| Ctrl+d / Ctrl+u | Scroll the focused pane half a page |
| gg / G | First / last diff line, or top / bottom of the focused side pane |
| ]c / [c | Next / previous hunk in the selected scope |
| ]l / [l | Next / previous layer |
| ]u / [u | Next / previous unreviewed hunk in the selected scope |
| /, n / N | Literal, case-insensitive search of visible diff lines; next / previous matching line |
| Space h / Space l | Focus previous / next visible pane |
| gd / ga / gf | Open Details / Ask / Feedback |
| Space r / Space R | Toggle focused hunk / selected whole layer reviewed |
| Space c / Space a / Space n | Comment on focused line / compose question / edit notes |
| Space b / Space d | Toggle layer sidebar / drawer |
| Space s / Space f / Space q | Confirm feedback submission / snapshot refresh / review closure |
| ? / Escape | Open help / dismiss current transient UI or return from text entry to diff navigation |

Navigation stays within bounds without wrapping; search repeat wraps through matching lines.
Hunk and line navigation must keep the target visible, synchronize Details and Ask focus, and resist scroll observers overriding an explicit jump inside a large hunk.
Whole-layer review marks all member hunks, including already-reviewed members, in one existing draft-save operation; when all are reviewed, it unmarks them all.
All changes is not a layer: disable the whole-layer action there rather than silently reviewing the entire snapshot.
Keep other layers' review state, comments, notes, and scope drafts intact.
Route mouse and keyboard review mutations through the same existing persistence and error handling.
Refresh, submit, and close use one shared confirmation route per action for both mouse and keyboard, without duplicate prompts or bypassing stale/draft checks.
Cancel confirmations without mutating data or sending requests.
Ignore navigation/action keys during IME composition, in editable controls, or with unrelated modifiers; only Escape may return from text entry, and Shift+Enter retains its existing Ask submission behavior.
Native control activation must not be consumed as a Space leader sequence.
Busy, empty, stale, hidden-pane, and refreshed-snapshot states must not permit invalid actions or stale line references.
Use bounded DOM work and existing browser primitives; no dependencies, editor framework, compatibility dispatch, or server API changes.

## Ask

Ask receives the complete captured diff and review plan, the explicit selected scope, the focused hunk, and that scope's conversation history.
Layer scope and hunk focus are distinct: scrolling changes focus, not the thread.
All changes has its own review-wide thread and must never silently select the focused hunk's layer.
Each layer has a separate thread; switching scope restores its messages and unsent question.
The server owns completed conversation history for the lifetime of the review; browser reload restores it, while snapshot refresh clears it.
A reply belongs to the scope and hunk captured when the question was sent, even if navigation changes before completion.
The model may inspect live filesystem evidence using read, grep, and ls through Pi's model registry.
Relative paths resolve from the reviewed repository; absolute paths may reach installed packages, node_modules, external documentation, and other non-protected files.
These tools are not limited to tracked files or Git revisions.
Live filesystem results are explicitly labeled as current evidence, not immutable snapshot content.
Enforce protected-file checks before content access, including directory ancestors and resolved symlink targets; safe dependency symlinks remain usable.
Do not expose Git internals as an alternate route to protected content.
Bound each tool's reads, traversal, matches, and returned bytes; allow line pagination and targeted searches inside ignored dependency directories.
Do not impose cumulative tool-call, round, or result-byte budgets on Ask.
Continue until the model answers, the provider fails, or the request is cancelled; check cancellation before each model request and tool execution.
Prefer existing native tool implementations where their boundaries can be enforced before content access.
Do not grant shell or mutation tools.
Tool and answer errors, resource limits, unavailable source, and stale snapshots remain visible rather than silently dropping context.
The Ask transcript scrolls independently above a bottom composer.
Shift+Enter sends; Enter inserts a newline; the Send button uses the same submission route.
Show the thread scope and focused hunk beside the composer or transcript so context is explicit.
Preserve typed text on failure and prevent duplicate submissions.
Strata retains the model selected when the workspace opened for both planning and Ask.

## Verification

Real Git fixtures cover each source, special paths, renames, binary/metadata changes, omitted paths, limits, and snapshot changes.
Strict plan validation exercises complete coverage and malformed model output.
Real Pi extension-runtime tests use a controlled registered provider and exercise command, persistence, cancellation, and feedback.
HTTP tests exercise authentication, origin validation, input validation, stale-submit refusal, save/ask/refresh/submit/close, and cancellation.
Chromium and Firefox E2E use the real server with deterministic model output to exercise navigation, explanation sync, flow rendering, drafts, chat, refresh, stale state, feedback, and responsive layout.
Run extension-local lint/test/check and browser tests, then the repository CI gate.
Current behavior is proved by fresh checks, not historical test claims.