@timurproko/a1 0.1.8-dev.50ebb19 → 0.1.8-dev.512

package/docs/architecture/response-copy-delivery.md

@@ -0,0 +1,85 @@
+# Clipboard copy and paste delivery
+
+## Compatibility map and baseline
+
+Accepted change: `fix-response-copy-freeze`, specification PRs #359 and #365. Initial expanded implementation base: `71e97ab6`; the review checkpoint is rebased onto `26b51b0b`, retaining the accepted timestamp, rendering, and truthful right-edge selection changes.
+
+- Bare A1 response selection: `SessionViewportController.handlePreInput` -> `TranscriptViewport.selectedText` -> selection clear/render request -> shell OSC 52 -> runtime's underlying terminal writer. The prompt native clipboard queue is not on this route.
+- Prompt copy/cut, workflow `/copy`, tree copy, and A1-owned paste: one owned write coordinator with literal prompt/workflow payloads and transaction-specific predecessor capture. A paste admitted during a pending write observes that write's result; an independent paste after a settled failure performs a fresh read. Preserve prompt-selection precedence, `/copy`, and terminal-provided paste.
+- Standalone paste: ordinary editor reservation -> clipboard acquisition -> text/path classification or existing image preparation -> replacement of that reservation. Native reads, format detection and command fallbacks run in a child, not the UI. Text/path classification uses a worker within that child; a blocked probe falls back to the same acquired text after one second and cannot strand the UI. Image preparation reuses the existing image worker within the killable child and preserves all image limits.
+- Terminal-provided paste: small non-path text has a fixed synchronous bound (at most 1,000 source code units); larger or path-shaped content uses the same isolated preparation policy, without a redundant native read. The owned framer keeps only a delimiter-sized lookbehind and bounded body fragments rather than repeatedly joining a growing body.
+- Modal/replacement input: the current base permits owned transcript selection behind a modal outside its painted bounds. Preserve that accepted routing rather than restoring the older blanket overlay bypass. `/copy` and Ctrl+C without transcript selection retain their existing command/cancellation handlers.
+- `keep-streaming-ui-responsive-during-selection` owns general selection/wheel/preparation optimization. This change owns selected-range extraction, copy-clearing damage, delivery and its lifecycle. Shared row caches and input coordination remain authoritative.
+- Pinned `a1 pi`, upstream components, installed dependencies, and terminal-owned selection remain unchanged controls.
+
+A generated probe on Windows Node 24.16.0 copied the same eight-character range from 100 and 100,000 rows. Before remediation, selected-text extraction read 101 and 100,001 source rows respectively (about 0.16 and 20.00 ms in that instrumented run). Proxy access counting exaggerates absolute timings; row counts establish the unnecessary whole-history slice. These measurements do **not** reproduce or establish the cause of the user's whole-UI freeze. Clipboard contention, terminal/version, freeze duration, and whether only physical painting stops remain unconfirmed. No clipboard payload or private session content is captured in evidence.
+
+## Lifetimes, limits, and recovery
+
+- Copy: 5-second admission deadline, one executing request and one newest pending request, at most 16 MiB UTF-8 text. Source snapshots retain only selected rows, capped at 65,536 rows and 32 Mi UTF-16 code units; they do not keep an obsolete whole-transcript graph.
+- Paste: eight distinct admitted requests, a 5-second acquisition budget including the captured write wait, and a 15-second deadline through insertion. A canceled executor counts against capacity until its stop fence. Image conversion has one process-wide slot. Copy supersession is deliberately not used for paste edits.
+- Text transfer: 16 MiB UTF-8 cap; IPC fragments are at most 16,384 code units and preserve surrogate pairs. The receiver acknowledges each fragment. Prepared large text is stored behind the existing compact chip rather than inserted as millions of editor characters. Existing source-image, pixel, encoded-output and attachment-count limits remain unchanged.
+- Clipboard executors have a 250 ms stop grace. A helper that has already reported a complete prepared result and lingers past that grace is reaped, not canceled: it is still terminated, but its prepared text is delivered exactly rather than replaced with an empty payload. Only an explicit cancellation, a protocol violation, or an incomplete byte count discards prepared text. POSIX command fallbacks share the paste helper's isolated process group; strict command reads use a forceful kill signal. Unconfirmed executor termination retains its capacity instead of allowing unbounded replacements or late A1-controlled writes. No helper inherits the UI terminal or places clipboard payloads in argv, temporary files, or logs.
+- Local copy prefers native delivery outside the terminal. OSC 52 uses the existing writer only on a non-blocking supported output route and is capped at a complete 64 KiB control, or a lower advertised limit. Submission is not clipboard acknowledgment. Remote/multiplexed sessions never silently read or write a different host's clipboard. Native Ctrl+V acquisition is unavailable when only the remote terminal owns the desired clipboard; normal terminal-provided paste remains supported.
+- URL-chip decoration: at most 65,536 UTF-8 bytes of added OSC 8 metadata per editor render pass across rows and repeated occurrences, including opening/closing pairs and cleanup closes. Targets that do not fit are omitted whole before control construction; a UTF-16 length precheck avoids scanning huge backing values. The budget resets each pass. Full chip data, atomic editing and exact copy/history/submission expansion remain intact; ordinary in-budget links retain their targets. Terminal automatic URL recognition is separate from explicit metadata.
+- Path-list presentation: the isolated classifier budgets 4,096 UTF-16 units per paste for existing individual tags plus 20 suffix-reserve units per occurrence. Over-budget lists use one existing text-paste chip backed by all classified full paths concatenated in order, including repetitions, without extra separators or re-normalization. No individual members are adopted into the UI before compaction. Small lists retain their file/folder/image-file chips; failed/timed-out classification retains the existing original-text fallback. Existing draft/history chips and the synchronous compatibility classifier are unchanged.
+- Reservations protect later typing, distinct paste order, selection replacement and undo/redo. Cancellation retires the reservation from history snapshots. Provisional chip ownership prevents failed/canceled pastes retaining unused backing data or deleting a chip reused by another successful paste.
+
+## Optional local diagnostics
+
+Set `A1_CLIPBOARD_DIAGNOSTICS` to an existing-parent local file path to capture metadata in bare A1. It is disabled by default and ignored by comparison/settings-free compositions. Records include copy/paste phases, runtime receipt/composition/write phases, and a 100 ms heartbeat. At most 128 scalar-only rows and one newest pending asynchronous disk snapshot are retained. No copied/pasted text, paths, image data, encoded payloads, raw errors, or extra fields from event objects are serialized. Disk errors remain silent and disk completion is never awaited by input or teardown.
+
+First-use keyboard routing emits `shortcut-received`, `shortcut-matched`, and `shortcut-admitted` under one negative request identifier. A standard Ctrl+V record with only `shortcut-received` identifies a key that reached the custom viewport but did not match; all three together with a positive `admitted`/`acquiring` request identify successful synchronous reservation and asynchronous acquisition. Editor right-click emits `pointer-admitted`; terminal-owned bracketed input emits `framing` plus truthful inline `inserting`/`settled` phases, or the positive isolated-preparation phases, without keyboard or native-acquisition routing. This lets an exact-candidate run identify the route and last completed boundary without capturing the clipboard value.
+
+Diagnostic accounting includes the transient incoming copy before its older pending predecessor is superseded (eight pastes plus three transient copy records). Paste-helper exit no longer prematurely clears insertion accounting: request cleanup is recorded after the insertion lifetime. Literal workflow copies do not invent transcript selection-clear events. Composition tests verify explicit/environment opt-in, comparison/settings-free exclusion, destination precedence, and disposal even when construction or shell teardown fails. Request identifiers are local to their source; runtime identifiers are input revisions, while negative identifiers cover first-use routing and terminal framing observations. `pendingBytes` is observed payload/source accounting, not native heap measurement.
+
+A healthy heartbeat with stalled visible painting differs from a blocked application event loop. These diagnostics support attribution but do not themselves establish the user's physical-terminal root cause. The baseline's main-thread path classifier and write/paste barriers are investigated independently of OSC 52.
+
+## URL presentation evidence and approved refinement
+
+Before the approved refinement, a source made from `https://example.com/` plus `16 * 1024 * 1024 - 64` ASCII characters was within the text limit and produced a 46-character editor chip, but its full OSC 8 target produced a 16,777,367-byte terminal write. The earlier regular-expression tokenization overflowed its stack; linear tokenization removed that crash but a subsequent headless run still measured a 305 ms maximum application timer gap. The 4 MiB control measured a 78 ms gap and a 4,194,519-byte write. These observations do not identify the user's physical freeze or measure terminal painting.
+
+With PR #385 open, the user explicitly approved revising its specs and implementation to preserve full URLs and chips while omitting oversized explicit hyperlink metadata. `EditorHyperlinkBudget` now enforces the per-pass limit before OSC construction, including repeated occurrences, multibyte targets, and row cleanup. The former observational-only probe now asserts bounded output, exact expanded submission/history, following typing, and no duplicate native read for bracketed paste; unit tests also check exact copy expansion and rejection without whole-target byte counting.
+
+One augmented synthetic run, including content checks and following typing, recorded 6,563 maximum terminal-write bytes for each near-limit route, with roughly 48 ms native / 55 ms bracketed maximum timer gaps and 632 / 647 ms overall test-observed insertion/check time. This is not an identical timing workload to the earlier probe, a physical latency distribution, or by itself evidence for task 5.3's entire large-text/path/image matrix. Deterministic metadata/output limits gate the regression; broader integrated evidence is recorded below, and physical acceptance is still required.
+
+## Generated baseline and lifecycle evidence
+
+The generated baseline covers 10 and 1,000 historical response blocks, idle and streaming, copy-only, standalone external-value paste-only, and copy/paste overlap. Each case runs once in a fresh shell and twice subsequently (36 samples). Helpers still start per request; warm-shell is not a claim of native-helper reuse. Copy uses the production isolated preparer with an injected clipboard sink; paste uses a supplied external-value reader and production isolated preparation. Neither is a physical clipboard or terminal measurement. Records separate input progress, copy phases, paste predecessor/acquisition/classification/insertion phases, composition/write counts, and timer progress, without payloads.
+
+One focused run observed the following ranges across 12 samples per operation:
+
+| Operation | Following-input handling (ms) | Completion/check time (ms) | Maximum timer gap per sample (ms) |
+| --- | --- | --- | --- |
+| Copy | 5.5–18.0 | 245.1–258.6 | 16.4–20.2 |
+| Independent paste | 4.1–8.3 | 311.8–346.6 | 16.9–21.3 |
+| Combined | 5.4–13.1 | 544.7–601.0 | 16.3–20.4 |
+
+Generated 2 MiB single-line, 100,000-line text, and 1,024-square image controls retained compact presentation and exact text/valid image semantics, with maximum write sizes of 6,563 bytes and timer gaps of approximately 17/18/27 ms in that run. These timings are observations, not shared-CI wall-clock gates or physical input-to-paint distributions.
+
+Lifecycle evidence covers 12 sequential real-helper copy/paste cycles, excess-admission rejection and full eight-helper capacity recovery after cancellation, and eight image helpers sharing exactly one conversion slot. Every observed child exited/disconnected and used ignored terminal descriptors. A reentrant acquisition-cancellation test found and fixed a conversion grant after cancellation. Session-shell tests preserve newer selections and drafts after late copy/text/image completion and verify alternate-screen restoration/no subsequent writes on disposal. Markdown render-call counters remain unchanged during copy-clear, typing, and wheel work on settled content. Cold emitted-helper/package tests remain separate from these source-helper tests.
+
+## Approved compact path-list refinement
+
+Indexed atomic segmentation uses the existing grapheme segmenter's boundary lookup rather than enumerating all discarded chip-interior graphemes. Equivalence tests cover Unicode boundaries and the existing iterable fallback; a structural test requires exactly two boundary lookups per chip rather than full enumeration. No pinned-source file or installed dependency is modified.
+
+A 12,000 short-name path-list observation improved from roughly 208 ms to 109 ms maximum timer gap. However, 6,000 paths with 160-character filename stems still produced 1,014,006 editor characters from 1,409,999 input bytes and a roughly 1,387 ms timer gap. Exact expanded paths were retained and writes remained small, but that application-side presentation work was unacceptable.
+
+The user approved the compact-path-list spec/code refinement in #385. `path-chip-presentation.ts` now shares tag formatting with adoption and selects a compact existing text-paste representation in the isolated preparer. The same 6,000-path source now produces 30 editor characters (including following typing), with approximately 18.3/18.5 ms observed timer gaps for native/bracketed routes in one focused run. A near-16 MiB path candidate (16,777,119 source bytes) exercised the one-second safe classification fallback, retaining all original text behind a 29-character presentation; observed gaps were about 16.8/20.7 ms. All four maximum writes were 6,563 bytes. These augmented workloads are synthetic observations, not physical acceptance.
+
+The former observational path probes now gate compact representation, exact expanded content, following typing, undo/redo, no duplicate native read, and bounded terminal output. Unit tests cover exact budget boundaries, Unicode/duplicates, shared file/folder/image-file framing, stopping tag construction at the allowance, exact literal path expansion for copy/history/submission, no provisional member chips, and stale-result cancellation. Emitted-helper tests prove compaction before UI transfer and that an invalid suffix falls back to the whole original text rather than a classified prefix.
+
+## Integrated automated matrix
+
+The refinement checkpoint passed 597 tests across 24 focused suites plus 35 clipboard/image/preparation/package tests (632 total across 27 suites), with build and typecheck. Coverage supporting tasks 5.3, 5.8, and 6.1 includes:
+
+- Selected-range/transport/coordinator tests: small and large exact payloads, Unicode, bounded source/encoding work, copy supersession, stalls/deadlines, backpressure, destination selection, late-side-effect fences, and cleanup.
+- Paste executor/client, chip lifecycle, and image tests: standalone sources, 16 MiB boundary/rejection, actual blocked probes/native work/command descendants, format/read/preparation failures, recovery, reserved ordering, cancellation/undo, image safety limits and serialized conversion.
+- Shell/editor/controller and diagnostics tests: copy-only/paste-only/combined cold/warm idle/streaming histories, native/bracketed text/URL/path/image presentation, following input/scroll/output, overlay ownership, comparison compatibility, bounded metadata/privacy, and session teardown.
+- Cold emitted helper/image-worker and package-inventory tests: production helper resolution, native fixture read/write, compact and invalid-prefix path lists, images, and included runtime modules. No installed dependency or pinned source is patched.
+
+This completes the integrated automated work, not supported-route physical certification. Required CI must run on the new candidate; tasks 4.3 and 7 remain dependent on actual terminal/clipboard evidence and explicit acceptance.
+
+## Acceptance
+
+Physical acceptance is pending. Automated scheduling and terminal replay cannot certify physical clipboard responsiveness. Test the exact candidate with repeated response Ctrl+C, independent Ctrl+V using content copied outside A1, and combined copy/paste, while idle and streaming. Check copied values in another application and pasted values in the prompt. Record terminal/version, topology, geometry, cold/warm behavior, subsequent-input latency and animation separately from clipboard completion latency. No Esc or other recovery action counts as a fix. Any repeated freeze fails acceptance; native Linux clipboard persistence and remote terminal behavior also require applicable physical evidence rather than inference from mocked transport tests.

package/docs/architecture/terminal-host-proof-gate.md

@@ -29,4 +29,4 @@ Any failed, missing, incomplete, contradictory, physically unverified, or thresh
 - stops composed-terminal work instead of starting a custom rendering/input remediation loop;
 - prevents investment in a postponed desktop-native application shell.
 
-The executable decision is `evaluateNativeSpikeGate` in `src/foundation/native-host-protocol/proof-gate.ts`. The current acceptance record is `openspec/changes/evolve-bare-a1-into-multi-agent-workspace/evidence/terminal-spike-acceptance-record.json`; it remains pending until task 5.6 records a physical verdict for exact artifact bytes.
+The executable decision was `evaluateNativeSpikeGate` in `src/foundation/native-host-protocol/proof-gate.ts`, preserved on the `archive/multi-agent-workspace` branch while the multi-agent plan is on hold. The current acceptance record is `openspec/changes/evolve-bare-a1-into-multi-agent-workspace/evidence/terminal-spike-acceptance-record.json`; it remains pending until task 5.6 records a physical verdict for exact artifact bytes.

package/docs/architecture/terminal-host-spike-evidence.md

@@ -34,6 +34,6 @@ Paint diagnostics require requested, presented, coalesced, and missed frame coun
 - `overall: accepted` requires technical acceptance and a physical verdict accepted through `manual` or `isolated-worker` evidence.
 - Active-workstation automation makes the evidence invalid.
 - Evidence must not contain terminal output, child input streams, rendered cells, cell grids, framebuffers, screen buffers, or raw terminal payloads.
-- The evidence validator is `assertNativeSpikeEvidence` in `src/foundation/native-host-protocol/evidence.ts`.
+- The evidence validator was `assertNativeSpikeEvidence` in `src/foundation/native-host-protocol/evidence.ts`, preserved on the `archive/multi-agent-workspace` branch while the multi-agent plan is on hold.
 
 A failed or incomplete proof stops composed-terminal integration and must not be waived to merge.

package/docs/architecture/tool-image-presentation.md

@@ -0,0 +1,62 @@
+# Owned tool image presentation
+
+## Why this source adaptation exists
+
+The accepted `preserve-agent-content-rendering` design permits a minimal attributed content adaptation when the pinned public component cannot preserve supported behavior. The user explicitly approved this image-lifecycle adaptation after its failing baseline.
+
+Pi 0.84.2's `ToolExecutionComponent` stores converted images by array index. Replacing a JPEG with another JPEG or a PNG can therefore display the previous pixels. Conversion failure has no visible fallback under Kitty. Its public API exposes neither conversion-cache reset nor mount disposal. Reconstructing the entire component on each attachment change would discard extension renderer state and asynchronous previews.
+
+`src/integrations/pi/components/upstream/components/tool-execution.ts` retains that tool shell's composition, lifecycle, fallback, expansion and extension context. Actual built-in renderers still come from the public `create*ToolDefinition` factories; custom renderers receive the original content, MIME types, bytes, details, arguments, state and previous components. The owned shell never edits installed Pi, accesses private fields, patches prototypes, upgrades dependencies, or modifies the explicit Pi comparison route.
+
+The source unit is from MIT-licensed repository <https://github.com/earendil-works/pi>, commit `914cf1472e715297caa30db4b9535d534a9eb718`, path `packages/coding-agent/src/modes/interactive/components/tool-execution.ts`. The source-map hash and local port hash are recorded in `config/baselines/pinned-pi-source-port-ledger.json`. Its small generic-output helper follows `core/tools/render-utils.ts::getTextOutput` and `utils/shell.ts::sanitizeBinaryOutput` from the same package; Node's public `stripVTControlCharacters` replaces the private ANSI helper. The public definition factories replace the private `createAllToolDefinitions` lookup. Public theme and TUI imports are mapped to the existing owned boundaries. No tool filesystem implementation or renderer layout is copied.
+
+## Image ownership and bounded work
+
+`ToolImagePresentation` owns only current image presentation. It shares immutable source strings rather than copying or hashing accumulated image data per chunk. Equal current sources share a conversion entry; entries disappear when their source is removed. The existing admission limits remain 16 references and 20 MiB per image; derived PNGs also receive the per-image limit before retention.
+
+One conversion is active per mounted tool. The waiting set is the newest current source set, not an unbounded queue of superseded snapshots. Hidden images and non-Kitty protocols do not start conversions. Work removed before codec entry is skipped. A public codec call already in progress cannot be cancelled; its eventual result is discarded if the source or mount is obsolete. This limitation is explicit, not claimed as cancellable worker execution.
+
+Pending Kitty conversion has a visible `[Image converting: ...]` marker. Failure, rejection, or oversized converted bytes produces `[Image unavailable: ...]`, without exposing codec diagnostics or changing the operation outcome. Converted pixels never replace the original payload passed to extension renderers. PNG and iTerm presentation use the actual public `Image` component. Hidden and no-image-capability text presentation matches pinned Pi.
+
+Rebuild/disposal releases image ownership and invalidates the previous mount. Reentrant renderer invalidation is suppressed during synchronous reconstruction; valid asynchronous callbacks still request the existing scheduler and update presentation revision, not semantic revision.
+
+## Terminal row boundaries
+
+Kitty APC payloads are zero-column opaque controls, not displayable base64 text. Neutral width/truncation/copy handling preserves or excludes the complete control as appropriate. Rail overlays preserve each image transfer once rather than replaying it as an SGR style. The runtime width guard excludes complete Kitty payloads but still checks all ordinary columns around them; it does not exempt an arbitrary image-bearing row from width validation.
+
+This correction does not introduce an ANSI parser, change link detection, relax text width limits, or change terminal erase policy. Image placement, scaling and clipping remain subject to the existing public Image and viewport visibility policies; physical partially clipped-image behavior is not established by a component byte comparison.
+
+## Evidence
+
+- `transcript-image-conversion.test.ts`: independent pinned stale-cache baseline, JPEG replacement, PNG replacement, hidden/non-Kitty parity, failed-conversion fallback and real scheduled Kitty publication at unchanged semantic revision.
+- `tool-image-presentation.test.ts`: current-source sharing, one active conversion, superseded bursts, removed/disposed callbacks, hidden/iTerm work avoidance, rejection and size fallback without retry loops.
+- `tool-shell-parity.test.ts`: independent actual pinned read/bash/edit/write/grep/find/ls and generic rendering at widths 40/80/192, partial/final/error states, expansion, binary text, and extension default/self shells with original inputs and stable renderer state.
+- Existing attachment-ownership, payload-limit, content-retention and shell tests remain non-regression gates. The wrapped-URL counterexample remains explicitly unresolved under issue #353.
+
+These are automated content and ownership checks, not Windows Terminal visual acceptance. The broader change stays open until scheduled-producer evidence, required CI, and exact-candidate user review satisfy its remaining tasks.
+
+## Upstream license notice
+
+```text
+MIT License
+
+Copyright (c) 2025 Mario Zechner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

package/docs/architecture/toolchain.md

@@ -17,7 +17,7 @@ The repository has one root package manifest, lockfile, dependency tree, TypeScr
 
 ## Platform policy
 
-Transparent launch uses inherited native terminal/process facilities on Windows, Linux, and macOS. The architecture is platform-neutral, but stable parity/support claims are platform-specific and require deferred physical certification against exact package bytes. An uncertified `next` preview is not evidence of stable cross-platform support.
+The owned rendering pipeline uses the containing terminal on Windows, Linux, and macOS. The architecture is platform-neutral, but stable presentation/support claims are platform-specific and require deferred physical certification against exact package bytes. An uncertified development preview is not evidence of stable cross-platform support.
 
 Physical desktop automation is absent from the active repository baseline. Any future implementation must run only on dedicated disposable workers or VMs with exclusive interactive desktops and exact process ownership.
 
@@ -27,7 +27,7 @@ The published package contains:
 
 - the sole public `a1` command;
 - the internal supervisor entry;
-- immutable release/bootstrap, lifecycle, protocol, storage, update, and transparent-launch modules;
+- immutable release/bootstrap, lifecycle, protocol, storage, update, owned-UI, and Pi-adapter modules;
 - current user and architecture documentation.
 
 It contains no PTY, terminal emulator, browser/desktop GUI, custom renderer, input translator, physical automation driver, or generated runtime data.
@@ -49,7 +49,7 @@ npm test
 npm run test:release
 ```
 
-`check:deprecated` verifies the complete lockfile graph against registry metadata. The release gate exercises durable stable/preview update transitions and writes an ignored machine-readable verdict under `artifacts/release-verdicts/`.
+`check:deprecated` verifies the complete lockfile graph against registry metadata. The release gate exercises durable stable/development update transitions and writes an ignored machine-readable verdict under `.artifacts/release-verdicts/`.
 
 ## Pi maintenance workflows
 
@@ -67,11 +67,19 @@ npm run sync:pi-ui
 
 This optional, mutating presentation-maintenance workflow regenerates component and event-frame parity evidence when maintainers deliberately adopt upstream UI changes. Review generated diffs, attribution, and source-ledger records before committing them. It is never an engine candidate acceptance gate and is not run by `check`, `prepack`, or release publication.
 
-Presentation acceptance is the reader comparing `a1 pi` with pinned Pi. `node scripts/check-pinned-pi-source-ledger.mjs` validates accepted provenance; its `--engine-only` mode validates the ownership partition without comparing private upstream source.
+`node scripts/pi/sync-pi-inventories.mjs` re-resolves `modal-surface-inventory.json`, `presenter-ownership-inventory.json`, and `pinned-pi-interactive-baseline.json` against the installed Pi packages: anchors that still match stay, anchors that match only ignoring whitespace are rewritten, anchors that match nowhere mark their entry `orphaned`, behavior line ranges that lost their anchors move to their symbols' span, hashes and manifests are regenerated, and interactive components the modal graph has never recorded are reported as unmapped. `--check` reports without writing; `--commit <sha>` records a new version's upstream commit; `--report <path>` writes the resolution report.
+
+`node scripts/pi/propose-pi-upgrade.mjs [--version <v>] [--commit <sha>] [--skip <v>...] [--refresh] [--output <dir>]` proposes a Pi upgrade in the working tree: it captures the old upstream sources, pins both packages at the target (by default the newest published version newer than the pin that is not skipped; `--version` ignores skips), evaluates the candidate through `pi-candidate-evaluator.mjs` and keeps the complete compile output in the artifact (summarized per file in the body), installs and builds, three-way merges each vendored copy under `src/integrations/pi/components/upstream/` whose ledger record says `upgradeStrategy: three-way` (`git merge-file --diff3` of the A1 copy, the old upstream, and the new upstream; conflict markers stay in the file as review items) and, for a `keep-owned` copy, leaves the file alone and writes the upstream delta to `kept/<record>.diff` in the artifact, regenerates the ledger and headers, re-resolves the inventories, refreshes the public API baseline (listing removed or changed exports with their A1 consumers as adoption items) and the feature adoption matrix (listing new upstream rows as pending), re-pins the startup graph, refreshes parity evidence, runs the type, architecture, engine-conformance, and parity gates, scaffolds `openspec/changes/pi-upgrade-<version>/` with the pin moved in the requirement that names it (only when the change directory is absent), and writes `report.json` and the pull-request `body.md`. A failed step is recorded and the run continues; while conflict markers remain in any copy, the gates that compile the tree (`startup-graph`, `parity`, `typecheck`, `architecture`, `parity-suites`) are recorded as `blocked` by those copies instead of running to fail, and the isolated evaluation and engine conformance still report the candidate's verdicts. `--refresh` re-runs the derived steps and gates on the checked-out proposal branch without bumping, evaluating, installing, or merging, comparing against the pin of `--base` (`origin/develop`). `.github/workflows/pi-upstream-sync.yml` runs it nightly and opens or refreshes the draft pull request `chore/pi-<version>` with the App identity: the body's report lives between `<!-- pi-upgrade-report -->` markers and only that part is rewritten on a re-run (`scripts/pi/refresh-pi-upgrade-body.mjs`), and a branch that carries commits the bot did not author is never pushed to; the fresh report is posted as a comment instead. Closing a proposal with the `pi-upgrade-skipped` label skips its version; `PI_UPGRADE_FREEZE_UNTIL` silences the schedule until a date. A human resolves the review items and merges. The pinned identity every check compares itself to comes from `scripts/governance/pinned-pi-identity.mjs`: versions from the dependency authority, the commit from `pinned-pi-interactive-baseline.json`.
+
+`node scripts/pi/update-pinned-pi-public-api.mjs [--check] [--packages-root <node_modules>] [--output <path>]` records `config/baselines/pinned-pi-public-api.json`, the package-root export surface of both pinned packages read from their declaration entries with the TypeScript compiler API: each export's kind, the hash of its normalized declaration, and the A1 modules under `src/` whose imports name it, directly or through a barrel such as `startup-public.ts`. The baseline is tooling evidence read by path, never a production import. `node scripts/pi/update-pi-feature-adoption-matrix.mjs [--check] [--packages-root <node_modules>] [--report <path>]` records `config/baselines/pi-feature-adoption-matrix.json`: one row per advertised and hidden command, TUI and app keybinding, session event, settings callback, presented setting, and stateful component from the interactive baseline's manifests and the engine's settings source, plus one row per changelog "New Features" entry newer than the matrix's `changelogSince`, each carrying A1's disposition: `pinned` (reused as is), `owned` (the behavior id and the test that proves it), `diverged` (the approved deviation id), `declined` (a reason), or `pending` (what the refresher writes for a new row). The refresher rewrites the upstream side only and marks a row upstream dropped `retired`; `test/repository-governance/pi-feature-adoption-matrix.test.ts` fails on a pending row, on missing evidence, and on a row whose feature upstream no longer presents unless it is retired. `node scripts/pi/update-startup-graph-baseline.mjs [--check]` re-pins the file and byte totals in `config/startup-graph-baseline.json` from the measured startup reachability and the manifest the last build wrote; optional modules and pinned dynamic imports stay reviewed.
+
+Presentation acceptance is the reader comparing `a1 pi` with pinned Pi. `node scripts/governance/check-pinned-pi-source-ledger.mjs` validates accepted provenance; its `--engine-only` mode validates the ownership partition without comparing private upstream source.
+
+`node scripts/pi/update-pinned-pi-source-ledger.mjs` regenerates `config/baselines/pinned-pi-source-port-ledger.json` from the installed packages' source maps. Upstream identity (hashes, line counts, source-map paths) comes from the packages; the reviewed fields of an existing record (classification, destination, status, modifications, deviations, tests, tasks, and `upgradeStrategy`: `three-way` for a copy that follows upstream, `keep-owned` for one A1 keeps on purpose and the upgrade never merges) are kept from the ledger, so reclassifying or deleting a port is a ledger edit, never a script edit. It also rewrites the provenance header at the top of every owned copy under `src/integrations/pi/components/upstream/` from the record (upstream package, version, commit, path, modifications, and deviation ids) before recording the copy's hash; the ledger check requires that header verbatim. `--check` reports header or ledger drift without writing.
 
 ## Publication
 
-One workflow publishes both channels: `.github/workflows/release.yml`, triggered by every push to `develop`. What the pushed commit declares decides the channel: a prerelease version publishes a preview under npm `next` at a `-dev.<short commit>` version stamped at publish time, and a stable version publishes under npm `latest`. Both pack once, validate those exact bytes on Windows, Linux, and macOS, and publish with provenance from the `npm-publish` environment. The publisher never rebuilds, a preview never changes `latest`, and the release tag, GitHub Release, and `master` are written only after the registry has the package.
+One workflow publishes both channels: `.github/workflows/release.yml`. Pushes do not publish. Nightly development verification runs at `03:17 UTC`; `npm run develop` explicitly requests a numbered preview and `npm run release -- patch` explicitly requests stable publication after its version pull request is manually merged; it promotes a development version to its stable core. The following development-version pull request also requires manual merge. A preview is stamped as `-dev.<merged pull-request number>` and uses npm `next` only as an internal dist-tag. New candidates pack once and are validated on Windows, Linux, and macOS; a repeated nightly verifies the exact immutable registry tarball. All publication uses provenance from the `npm-publish` environment, a preview never changes `latest`, and the stable tag, GitHub Release, and `master` are written only after npm has the package. One global non-cancelling concurrency group serializes the final registry check.
 
 `docs/ci-release-runbook.md` is the operational reference.
 
@@ -81,9 +89,9 @@ These paths are A1 control and release state, not Pi profile roots. All are over
 
 | Purpose | Override | Windows default | Unix default |
 |---|---|---|---|
-| Config | `A1_CONFIG_DIR` | `%APPDATA%\\A1` | `$XDG_CONFIG_HOME/a1` or `~/.config/a1` |
-| Durable data | `A1_DATA_DIR` | `%LOCALAPPDATA%\\A1` | `$XDG_DATA_HOME/a1` or `~/.local/share/a1` |
-| Runtime | `A1_RUNTIME_DIR` | `%LOCALAPPDATA%\\A1\\runtime` | `$XDG_RUNTIME_DIR/a1` or `<data>/runtime` |
+| Config | `A1_CONFIG_DIR` | `%APPDATA%\\a1` | `$XDG_CONFIG_HOME/a1` or `~/.config/a1` |
+| Control/release data | `A1_DATA_DIR` | `%LOCALAPPDATA%\\a1` | `$XDG_DATA_HOME/a1` or `~/.local/share/a1` |
+| Runtime | `A1_RUNTIME_DIR` | `%LOCALAPPDATA%\\a1\\runtime` | `$XDG_RUNTIME_DIR/a1` or `<data>/runtime` |
 | Database | `A1_DATABASE_PATH` | `<data>/control.sqlite3` | `<data>/control.sqlite3` |
 | Endpoint | `A1_ENDPOINT` | runtime-scoped `a1-*` named pipe | `<runtime>/supervisor.sock` |
 
@@ -91,8 +99,22 @@ These paths are A1 control and release state, not Pi profile roots. All are over
 
 A1 does not read or migrate legacy `ADDONE_*` variables, `AddOne`/`addone` control-state directories, release manifests, database schemas, endpoint records, or protocol frames. Remove obsolete control state only after stopping old processes: `%APPDATA%\\AddOne` and `%LOCALAPPDATA%\\AddOne` on Windows, or the former `addone` directories under XDG config, data, and runtime roots on Unix. This cleanup is manual and never imports data into A1.
 
-Do **not** remove `~/.a1/agent` or `~/.a1/sandbox`; those are current Pi profile roots and are intentionally preserved. `~/.pi/agent` remains the vanilla Pi profile.
+Do **not** remove `~/.a1/agent`; it is A1's current Pi profile root. `~/.pi/agent` remains the vanilla Pi profile.
 
 The obsolete npm package `@timurproko/addone` is deprecated with the registry message `This package is obsolete. Use @timurproko/a1 instead.` It is not a current identity, compatibility channel, or rollback source. Whole-package unpublication was rejected by npm policy; any later removal is owner-controlled registry administration and does not change the A1 runtime contract.
 
-The launch-profile feature separately owns Pi roots: `~/.a1/agent`, ordinary `~/.pi/agent`, and `~/.a1/sandbox`.
+The launch-profile feature separately owns A1's `~/.a1/agent` root and preserves ordinary Pi resolution through `~/.pi/agent`.
+
+## Internal naming validation
+
+The required PR naming job inspects complete new and changed source files. `npm run check:names` performs the full tracked audit, also required by nightly full-release validation. See [internal naming and clean cutover](internal-naming.md) for public/private environment ownership, required checks, and protected user data.
+
+### Prompt history
+
+Prompt history has a separate default: `<effective-home>/.a1/data/history/<profile-id>.sqlite3`
+on Windows, Linux, and macOS. The effective home follows launch-profile resolution
+(`A1_PROFILE_HOME` or the OS home), not `XDG_DATA_HOME`. An explicit `A1_DATA_DIR`
+continues to select `<A1_DATA_DIR>/history` as well as the control/release data root.
+The home-based history default does not relocate the paths above or the compile
+cache at `<data>/cache/compile`. See [prompt history](../features/prompt-history.md)
+for the deliberate fresh start without migration, privacy, and manual removal.

package/docs/architecture/ui-reference-provenance.md

@@ -19,30 +19,84 @@ its own `core` facade layer; A1 is a product, so the port adapts imports and kee
 | A1 module | Reference unit | Adaptation |
 | --- | --- | --- |
 | `ui-components/line-input.ts` — word motion and word delete | `core/panes/line-input.ts` | `wordLeft`/`wordRight` and their key bindings ported verbatim, including deciding a word delete before a plain one because a raw backspace byte is ctrl+backspace on Windows Terminal. |
-| `ui-components/spans.ts` — `overlaySpan` | `core/presentation/spans.ts` | Uses A1 `displayWidth`; hyperlink and style replay kept verbatim. |
+| `ui-components/spans.ts` — span painting | `core/presentation/spans.ts` | Uses A1 `displayWidth`; hyperlink/style replay and background-only selection painting preserve each source foreground plus bold, underline, links, and other attributes. |
+| `ui-components/text-selection.ts` | `core/panes/text-selection.ts` and `ui/agent-view/content-selection.ts` | Keeps LMB drag, double-click word, triple-click line, grapheme-aware extraction, and prompt decoration exclusion. Multiline selection uses native terminal geometry (first-row tail, complete middle rows, last-row head); triple-click paints the full row while copied text remains semantic content. |
 | `ui-components/scrollbar.ts` — geometry | `core/presentation/scrollbar.ts` — `scrollbarGeom` | Same formula; A1 names the fields and returns null rather than undefined. |
-| `ui-components/scrollbar.ts` — rails | `core/presentation/scrollbar.ts` — zone and hover state | Rail identity kept; A1 holds state in an instance rather than a module global. |
+| `ui-components/scrollbar.ts` — rails | `core/presentation/scrollbar.ts` — zone, policy, and hover/drag state | Rail identity, hover reservation, activity linger, visual weights, drag, and track paging kept; A1 holds state in an instance rather than a module global, while the session shell applies profile-local normal/fast/high wheel and selection-edge speed. |
+| `ui-components/submitted-prompt.ts` | `core/presentation/user-bar.ts` | Keeps the compact `❯ ` prefix, continuation indentation, timestamp reservation, and right alignment. A1 fixes the declared format to local 24-hour `HH:mm` and uses the engine's source timestamp. |
+| `ui-components/transcript-viewport.ts` | `ui/agent-view/render.ts`, `scroll.ts`, `state.ts`, and `feature.ts` | Keeps follow/detach transitions, the floating bottom control, semantic sticky prompt behavior, and the session rail's intentional one-row top inset. New-message counts follow the reference's exact completed-assistant-message boundary, exclude tool results, and reset when input or a fresh agent run resumes follow mode. `Working` stays pinned only while all content fits; on overflow it joins the scrollable document tail exactly like the reference. A1 receives owned rows, prompt anchors, and semantic lifecycle events instead of inspecting Pi children. |
 | `ui-components/list-block.ts` — block navigation | `settings/impl.ts` — `blockJumpTarget`, `blockRowSpan`, `bottomBlockTarget` | Row type generalized from settings rows to a grouped list; targets and edge behavior identical. |
 | `ui-components/list-block.ts` — sticky scroll | `settings/impl.ts` — `stickyHeaderGroup`, `topPaddingRows`, `visibleRowCountAt`, `clampScrollForView` | Same reservation arithmetic and two-pass reveal. |
 | `ui-components/mouse.ts` | `core/panes/sgr-mouse.ts` | Same SGR decoding and per-call regex reset; A1 emits its own event shape. |
 | `ui-components/mouse.ts` — tracking sequences | `core/host/pi/providers/host-bridge-surface.ts` | Mouse modes only. A1 does not take the alternate screen, because the Pi TUI owns the screen A1 renders through. |
-| `features/owned-ui/settings-app.ts` — layout | `settings/impl.ts` — `settingsValueColumn`, `renderFieldLine`, footer and search rendering | Setting discovery is A1's own section model; presentation follows the reference. |
+| `features/owned-ui/settings-app.ts` — section layout, pointer controls, and scrolling | `settings/impl.ts` — `settingsValueColumn`, block navigation, sticky sections, and pointer hit regions | Setting discovery is A1's own A1/Agent section model. Section navigation and pointer-only numeric controls follow the A1 reference; explicit `/` search, ruled shared input, shortcut-derived hints, hidden description rows, configured wheel cadence, a rail presented through the shared scrollbar settings, `Ctrl+Home`/`Ctrl+End` boundary jumps, and distinct floating scalar menus are reviewed owned interactions. |
 
 ## Ported from the pinned engine
 
 | A1 module | Pinned Pi source | Adaptation |
 | --- | --- | --- |
-| `pi-engine-adapter/settings-integration.ts` — `SETTING_LABELS` | pinned Pi settings selector | Labels and descriptions transcribed so an owned screen reads as the vanilla route words it. Ids are mapped from the selector kebab-case to the exposed camelCase keys. |
+| `src/cli/package-messages.ts`, `src/cli/packages.ts`, and `src/integrations/pi/engine/package-integration.ts` — package/model CLI messages | Pi 0.84.2 `packages/coding-agent/src/package-manager-cli.ts` and public `DefaultPackageManager` at commit `914cf1472e715297caa30db4b9535d534a9eb718` | Preserves terminal-aware Chalk success/error/progress styling, literal model-refresh messages, operational details, and user-settings warnings. Focused syntax/help substitutes the `a1 pi` namespace and supported grammar; A1 syntax exit status remains two. Profile isolation and independent-Pi-update rejection remain intentional. Independent CLI evidence: `test/cli/package-message-parity.test.ts` runs the untouched pinned CLI presenter in an isolated process with model-runtime test substitution, not A1-generated expected strings. This does not certify the still-pending interactive message outcomes. |
+| `pi-engine-adapter/adapter.ts`, `engine/workflows.ts`, and `session-shell/session-shell.ts` — interactive command outcomes | Pi 0.84.2 `modes/interactive/interactive-mode.ts`, `core/model-resolver.ts`, and `config.ts` at commit `914cf1472e715297caa30db4b9535d534a9eb718` | Preserves route-specific status/warning/error semantics, authentication partial-success sequences, stored-credential logout wording, fork/clone empty states, import context/recovery, share URL and failure/cancellation behavior, and post-login warning lifetime. A1 deliberately returns recoverable failed workflow results instead of adopting Pi's process-owning shutdown/exit for fatal `/new`, `/resume`, and `/import` outcomes. Focused outcome evidence is in `test/integrations/pi/engine/workflows.test.ts` and `test/app/session-shell/session-shell.test.ts`; terminal-cell geometry remains a separate milestone. |
+| `pi-engine-adapter/settings-bridge.ts` — presentation metadata | pinned Pi settings selector | Labels, descriptions, order, dialog parts, and bounds are extracted from the selector source at build time by `scripts/pi/build-pi-settings-metadata.mjs` into `dist/`, so an owned screen reads as the vanilla route words it. Ids are mapped from the selector kebab-case to the exposed camelCase keys. |
+| `pi-engine/session-integration.ts` and `pi-components/shell-footer-status.ts` — steering queue | pinned Pi interactive mode `onSubmit` and `updatePendingMessagesDisplay` | Steering/follow-up uses `prompt(..., { streamingBehavior })`, allowing Pi to emit the accepted user row, while remaining steering rows preserve Pi's opening spacer, dim `Steering:` labels, dequeue hint, and order before `Working`. |
+| `ui-components/list-view.ts`, `dialog-panel.ts`, `value-menu.ts`, and `features/owned-ui/settings-app.ts` — setting presentation | pinned Pi `SettingsSelectorComponent`, Pi TUI `SettingsList`, `SelectList`, and `Input` at `0.84.2` | Cursor and selected label accents, unselected muted values, the 30-column label cap, dialog styling, notices, and narrow-width geometry retain pinned semantics. Scalar-menu placement and input remain shared, while the muted, hover-brightened selected value, A1/Agent grouping, pointer steppers, explicit `/` search, ruled shared input, shortcut-derived status hints, suppressed selected descriptions, `scrollbarSpeed`-driven wheel movement, a list rail that follows `scrollbarAppearance` and `scrollbarStyle` with transcript-style hover and drag, `Ctrl+Home`/`Ctrl+End` boundary jumps, and the dark floating menu with lighter active row and effective-value check mark are declared product-owned differences. Independent row evidence: `test/features/owned-ui/pinned-settings-presentation-parity.test.ts`; owned interaction evidence: `test/features/owned-ui/settings-app.test.ts`, `test/ui/components/value-menu.test.ts`, and `test/composition/settings-route-host.test.ts`. |
+| `features/owned-ui/project-trust-prompt.ts` — pre-resource selector | pinned Pi `cli/startup-ui.ts`, `cli/project-trust.ts`, and `core/project-trust.ts` at commit `914cf1472e715297caa30db4b9535d534a9eb718` | Uses a fixed, dependency-bounded A1 startup selector rather than importing private CLI modules. It preserves selected-option accent, navigation/accept/reject/cancel semantics, fail-closed behavior, raw-mode restoration, clearing, cursor restoration, and parent-screen restoration before diagnostics. |
+| `session-shell/session-shell-root.ts` and `session-shell.ts` — fullscreen exit | pinned Pi `InteractiveMode.formatResumeCommand()` and shutdown output at commit `914cf1472e715297caa30db4b9535d534a9eb718` | Re-renders authoritative transcript components with semantic SGR intact, excludes inline-image control payloads and fullscreen-only chrome, restores the terminal first, then emits pinned dim `To resume this session:` wording with `a1`, compact session id, and conditional quoted `--session-dir`. |
+| `pi-tui-runtime/input-presentation-coordinator.ts` and custom-viewport dock reuse | pinned Pi TUI `TuiBase` input dispatch and immediate-render pending guard at `0.84.2` | Preserves each original terminal delivery and invokes the existing Pi handlers exactly once in order. Bare A1 alone drains finite-grammar text/edit/navigation bursts in one immediate event-loop opportunity so Pi's existing pending guard paints the newest state once; effectful, unknown, protocol, paste, and extension-owned input remains an immediate barrier. Geometry-stable dock frames reuse A1's established transcript viewport, while uncertain geometry and replacement-surface damage still fail closed. Independent evidence is under `test/support/input-responsiveness/`. |
+| `test/features/owned-ui/pi-raw-terminal-parity.ts` — parity normalization | pinned Pi public components/runtime at `0.84.2` | Only synchronized-output envelopes, absolute hyperlink targets, declared product/path substitutions, and nondeterministic timing may normalize. SGR roles/reset boundaries, rows, cursor operations, clearing, restoration, and write order remain authoritative; A1-generated JSON captures are diagnostics and cannot serve as pinned evidence. |
 
 ## Deliberate differences
 
-- **No alternate screen.** The reference owns its surface and can switch screens; A1 renders
-  through the pinned Pi TUI, so an owned screen is a full-viewport overlay instead.
+- **Above-prompt autocomplete.** The accepted `show-autocomplete-above-prompt` change
+  moves the existing default-editor completion block above the prompt in bare A1.
+  `src/integrations/pi/components/upstream/components/owned-editor.ts` exposes its
+  border-inclusive body height using the existing atomic-aware layout boundary;
+  `shell-editor-autocomplete.ts` moves rows only after prefix/selection decoration
+  and adds one top line using the editor's current border-color function.
+  The accepted refinement (#343) restores this line instead of panel shading.
+  The user-approved review refinement in #344 moves the existing trailing counter
+  into that line without parentheses, at the history-label inset and in the same dim
+  color. The select-list `scrollInfo` callback identifies its final counter row;
+  private selection state and rendered-frame parsing are not used. Counter meaning
+  and visibility remain unchanged, and candidate ANSI styling/padding stay intact. The line is
+  included in the body offset, disappears with the menu, and is non-text chrome.
+  Theme/mode/resize tests verify matching line color and width; terminal background
+  replay verifies the menu has no added shading.
+  The session shell uses the resulting body offset for pointer routing. Neither
+  editor implementation, history mode, menu sizing, completion state, nor installed
+  Pi package changes. `a1 pi` remains below-prompt and byte-identical to the independently
+  run pinned editor in `test/integrations/pi/components/pinned-editor-input-parity.test.ts`.
+  Placement and whole-menu ANSI evidence is in `editor-autocomplete-placement.test.ts`;
+  shell checkpoint replay covers final cells, cursor rows, resizing, detached/streaming
+  transcripts, widgets, pointer selection, and extension-editor restoration. Physical
+  acceptance of the exact build remains required before merging the implementation.
+- **Owned in-session routes are overlays.** The A1 UI reference owns its surface and can switch screens; A1 renders in-session owned routes through the pinned Pi TUI as full-viewport overlays. The pre-resource trust selector is separate and uses a bounded alternate startup surface solely so every completion path can restore the untouched parent terminal before engine activation or a fail-closed diagnostic.
 - **Colour is a port, not an import.** The reference takes a Pi `Theme` directly. A1 defines
   `UiTheme` so the component layer never imports a Pi adapter and can be rendered plainly in
   tests.
 - **Settings content.** The reference aggregates per-extension settings files; A1 has one
   section for its own settings and one for the agent's, read through the engine settings port.
+- **Settings scalar-menu contrast.** The shared menu keeps reviewed placement, clipping, and
+  input behavior, but A1 uses its prior dark floating panel, lighter white-text active row,
+  and independent effective-value check mark because physical review rejected a menu that
+  blended into the settings rows.
+- **Spinner-backed progress punctuation.** Bare A1 resolves built-in and extension working
+  labels through `ui-components/progress-status.ts`, injected by
+  `session-shell/session-shell-root.ts` into the shared `pi-components/shell-footer-status.ts`
+  spinner factory. The factory canonicalizes the visible progress marker once, to three ASCII
+  periods, without importing across the component-adapter boundary. Engine producers remain
+  semantic and the source-synchronized Pi status indicators, installed packages, `a1 pi`, and
+  vanilla Pi remain untouched.
+- **Keyboard presentation scheduling.** Pinned components, semantic key handling, and the
+  comparison profiles stay unchanged. Bare A1 adds one A1-owned event-loop-turn coordinator
+  before its fullscreen root and may omit only superseded visual states after every delivery
+  has already been applied in order. It does not debounce by wall clock, combine strings,
+  patch Pi TUI, or classify unknown extension/terminal data as safe.
+- **No viewport prototype or child-tree patches.** `ui/agent-view/user-prompt.ts` and the
+  private-child traversal in `ui/agent-view/render.ts` were analyzed only for behavior. The
+  destination renders source timestamps through an owned transcript adapter and derives sticky
+  anchors while assembling semantic transcript blocks; it never replaces a Pi prototype or
+  reads a Pi component's private children.
 
 ## Keeping this honest