@timurproko/a1 0.2.6-dev.736 → 0.2.7-dev.1221

package/docs/architecture/boundaries.md

@@ -7,23 +7,24 @@ Every interactive command uses this profile-neutral lifecycle path:
 ```text
 mutable a1 entry
   -> verified immutable release
-  -> Node launch guardian and authenticated launch-instance registration
-  -> native process guardian and per-instance containment
-  -> profile-aware owned-UI runtime selection
+  -> Node launch guardian loading the verified process-guardian addon
+  -> addon-held per-instance containment and profile-aware runtime selection
   -> owned Pi-backed composition, with A1 surfaces enabled only for bare a1
 ```
 
 Launch-instance ownership is plural. The supervisor tracks any number of independently authenticated `a1` and `a1 pi` instances and never uses one product-wide foreground mutex. Closing one instance closes only its verified process tree. Persisted rows alone do not prove liveness, and uncertainty never authorizes terminating an unrelated process.
 
-Neither guardian reads ordinary terminal input, parses or relays runtime output, renders cells, infers frames, synthesizes terminal responses, or emits display control. Both profiles use the same owned rendering and input pipeline. Bare `a1` exposes A1-owned surfaces; `a1 pi` withholds those surfaces and uses Pi's ordinary profile root. The private guardian boundary carries only bounded identity, readiness, stop, and outcome data.
+The launch guardian and process-guardian addon do not read ordinary terminal input, parse or relay runtime output, render cells, infer frames, or synthesize terminal responses. Their only terminal output is the bounded reset and sanitized armed exit notice after runtime failure. Both profiles use the same owned rendering and input pipeline. Bare `a1` exposes A1-owned surfaces; `a1 pi` withholds those surfaces and uses Pi's ordinary profile root. The containment boundary carries only bounded identity, readiness, stop, and outcome data.
+
+A detached Node exit watcher sits outside the launch guardian's containment. It waits for the guardian, performs bounded Unix process-group cleanup, and may deliver the same claimed exit notice. A kill aimed at every Node runtime also kills this watcher; the accepted loss of the notice and Unix fallback cleanup in that case is documented in [`process-guardian-provenance.md`](process-guardian-provenance.md), and A1 starts no native executable to close that gap.
 
 The owned Pi-backed surface is not an arbitrary-CLI terminal multiplexer. A feature that requires resident arbitrary CLI sessions, internal tabs, terminal-state reconnection, or A1-authoritative scrollback must introduce and certify the separate composed-terminal authority rather than reactivating the retired transparent attachment path.
 
 ## Current module responsibilities
 
 - `lifecycle`: dependency-free launch-instance, process identity, state transition, outcome, and control-command contracts.
-- `process-containment`: artifact verification, OS-verifiable process inspection, containment adapters, and bounded graceful/forced cleanup; it owns no terminal content.
-- `launch-guardian`: one profile-neutral instance coordinator above runtime selection.
+- `process-containment`: process-guardian addon loading and artifact verification, OS-verifiable process inspection, in-process containment adapters, and bounded graceful/forced cleanup; it owns no terminal content.
+- `launch-guardian`: one profile-neutral Node instance coordinator above runtime selection, plus the fixed Node exit-watcher entry used only for owner-death cleanup and the armed notice.
 - `protocol`: additive control handshake, bounded line framing, authenticated launch-instance commands, typed stop intent, snapshots, and command results.
 - `launch`: resolves the effective profile home and the history-specific data root. Composition uses its public path resolver to select `~/.a1/data` for history unless `A1_DATA_DIR` is explicit; global control/release/runtime/cache paths stay unchanged.
 - `prompt-history`: narrowly typed user-input retention in separate profile-owned databases under `~/.a1/data/history` (or `<A1_DATA_DIR>/history`), with bounded worker queues and no supervisor/control-store payloads. It receives a resolved root rather than importing launch-feature internals; it never probes, imports, or deletes the former platform-default history. The editor's owned history state machine remains inside the Pi component boundary; the session UI only coordinates snapshots and classified submissions.
@@ -32,17 +33,31 @@ The owned Pi-backed surface is not an arbitrary-CLI terminal multiplexer. A feat
 - `supervisor`: endpoint identity, plural cohort ownership, per-instance reconciliation, and aggregate release shutdown coordination. It owns no terminal surface.
 - `pi-engine-adapter`, `pi-component-adapter`, and `pi-tui-runtime-adapter`: isolate pinned Pi engine and presentation knowledge behind neutral contracts; product features do not import them directly. Inside the engine adapter, one process-level engine host owns what is process-wide (the HTTP dispatcher, the theme singletons, the one-time changelog and package-update announcements, the startup trace) and is the only place sessions are created, so every session id is unique per process.
 - `session-shell` (`src/app/session-shell`): the application layer that composes the feature owners, the UI foundations, and the three Pi adapters into the interactive session; only composition imports it. Its render root assembles semantic document and dock rows, while its focused viewport controller owns follow state, pointer routing, selection, and interaction timers. Owned-app route lifecycle belongs to the neutral `ui-apps` owner and is only hosted by the session shell.
-- release/update/bootstrap: package-derived immutable release identity, process-guardian integrity, cohort selection, durable update transactions, rollback, and dependency-light command entry. After an unsuccessful bare-A1 child exit, the bootstrap restores owned terminal modes; neither guardian emits terminal controls.
+- release/update/bootstrap: package-derived immutable release identity, native-addon integrity, cohort selection, durable update transactions, rollback, and dependency-light command entry. Before certified fast-path reuse it checks every recorded product file is present; a missing or altered file is replaced only from the matching installed package when its size and digest reproduce the approved release, followed by full verification. Dependency layers keep their separate verification and repair policy. After an unsuccessful bare-A1 child exit, the launch owner or its Node watcher restores owned terminal modes and emits only the armed bounded notice.
 - `terminal-cleanup`: bounded, idempotent emergency restoration and fatal-exit diagnostics for an explicitly owned terminal. It does not inspect commands, relay terminal input/output, or emulate terminal state. The owned UI installs its fatal boundary before terminal activation; packaged bootstrap and checkout launch provide the surviving-owner fallback. Fatal records retain at most ten 16 KiB records with trusted classifications and code locations, never prompts, attachments, raw input, credentials, or arbitrary exception messages.
 
 ## Dependency direction
 
 Terminal boundaries are application-agnostic. They may not select behavior from executable names, arguments, CLI-specific environment variables, or visible text. Production code may not import private Pi distribution APIs or use a Pi-specific terminal workaround.
 
-The JavaScript product path has no PTY or terminal-emulator dependency. Reintroducing `node-pty`, xterm state, custom input encoders, mode/query trackers, cadence-derived frame inference, or renderer/projection code requires an approved capability change and cannot become a second terminal authority. The Rust process guardian is a lifecycle-only native boundary and is independent from the held composed terminal host.
+The JavaScript product path has no PTY or terminal-emulator dependency. Reintroducing `node-pty`, xterm state, custom input encoders, mode/query trackers, cadence-derived frame inference, or renderer/projection code requires an approved capability change and cannot become a second terminal authority. The Rust process guardian is a lifecycle-only Node-API addon loaded by the launch guardian and is independent from the terminal-host Node-API addon. No A1-built executable is part of the production process surface.
 
 `scripts/governance/check-architecture.mjs` enforces the structural parts of these boundaries. Cross-cutting rationale belongs here; implementation history belongs in Git and archived OpenSpec changes.
 
+## Session shell composition
+
+The session presenter (`src/app/session-shell/session-shell.ts`) coordinates; it does not own per-concern state. Each concern implements `SessionConcern` (`session-concern.ts`): it resets its own state in `onSessionReplaced` and releases it in `dispose`, and the presenter lists its concerns once, in reset order, in `#createConcerns`. New submission, routing, dialog, login, or resident-tab behavior goes into the concern that owns it, or a new concern added to that list. The render root (`session-shell-root.ts`) likewise picks one `ShellLayout` at construction and delegates transcript caching to `TranscriptDocument`, dock chrome to `DockChrome`, workflow output to `WorkflowOutput`, extension surfaces to `ExtensionSurface`, and the dock's input surface to `InputSurfaceSwitch`. The engine adapter serves the shell through the ports built in `src/integrations/pi/engine/ports.ts`, and the composition root delegates runtime claims, the startup release note, and the resident-tab bridge to their own modules under `src/composition/`.
+
+## Unit size ratchet
+
+Module boundaries do not stop one class or function inside a module from absorbing every feature. The architecture gate therefore measures every production TypeScript class under `src/` (methods and fields) and every TypeScript or Rust function under `src/` and `native/<crate>/src/` (inclusive lines), excluding vendored sources and Rust `#[cfg(test)]` code. A unit with more than 20 methods, 15 fields, or 100 function lines must be recorded in `config/baselines/size-ratchet.json`, and its recorded counts can only shrink:
+
+- A recorded count that grows fails the gate. Split the unit instead. If growth is truly unavoidable, raise the entry by hand in the same pull request and say why in its description, so the growth is reviewed rather than silent.
+- An unrecorded unit over a threshold fails the gate; split it before it lands.
+- A count that shrinks, or a unit that falls below every threshold, fails until `node scripts/governance/update-size-ratchet.mjs` lowers or removes the entry. That script never adds or raises an entry; `--check` reports without writing.
+
+The measurement in `scripts/governance/size-ratchet-policy.mjs` masks strings, comments, and regular expressions and counts braces, so it needs no build; a file whose braces do not balance is reported rather than mismeasured. Keys are `<path>::<Class>`, `<path>::<Class>.<method>`, or `<path>::<Type>::<fn>`, so moving or renaming a unit means moving its entry.
+
 ## Multi-session limits of the pinned engine
 
 The engine host removes A1's own obstacles to several Pi sessions in one process, but three remain in the pinned Pi SDK and must be planned around, not discovered:
@@ -53,7 +68,7 @@ The engine host removes A1's own obstacles to several Pi sessions in one process
 
 ## Planned multi-agent boundaries
 
-The multi-agent workspace feature, its dependency-free contracts, the structured-agent runtime, and the Node side of the terminal-host protocol were removed from `develop` while the multi-agent plan is on hold; their last state is preserved on the `archive/multi-agent-workspace` branch. A future implementation starts from the current codebase rather than from that copy. The boundary rules below remain the design intent for that work.
+The multi-agent workspace feature, its dependency-free contracts, the structured-agent runtime, and the Node side of the terminal-host protocol were removed from `develop`; their last state is commit `243eb7a7` in `develop` history. That structured-workspace plan was retired on 2026-10-10 in favor of `add-persistent-multi-agent-tabs`, where every tab runs the complete A1 UI under the native terminal host. A future implementation starts from the current codebase rather than from that copy. The boundary rules below remain the design intent for that work.
 
 The workspace feature may depend on workspace contracts and the structured/terminal-host foundations. Those foundations may depend only on dependency-free workspace contracts, never on product features, launch profiles, or each other unless an approved capability adds the dependency. Launch profiles do not import, initialize, launch, or connect to composed terminal-host infrastructure.
 
@@ -61,7 +76,7 @@ Default future agents and composed hosts are children of the originating bare-`a
 
 The structured-agent runtime uses a versioned adapter hello and feature negotiation before readiness. Runtime state must use typed events, commands, snapshots, cancellation, and recovery evidence. It must not infer structured semantics from terminal text, terminal timing, or visual content and must not own pseudoterminals or renderer state.
 
-The terminal-host protocol boundary may carry only bounded typed control and semantic lifecycle messages. Pseudoterminal bytes, per-event child input, rendered cells, cell grids, framebuffers, and screen buffers are forbidden across it. Console host executables and packaging live outside the current JavaScript production owners and remain unavailable until the isolated in-terminal proof passes; replacing them with a lightweight custom parser/renderer is forbidden. A desktop-native window and GPU application shell are postponed and are not required for the terminal-hosted product.
+The JavaScript-to-native terminal-host boundary carries only the fixed role arguments, host command, return code, session-lock calls, and typed semantic bridge data. `host-entry.js` does not touch Node's stdin/stdout streams; pseudoterminal bytes, per-event child input, rendered cells, cell grids, framebuffers, and screen buffers remain inside the addon's native roles and their bounded native IPC. The verified addon and fixed entry are the packaged production host; no console host executable exists. Replacing libghostty-vt with a lightweight custom parser/renderer is forbidden. A desktop-native window and GPU application shell are postponed and are not required for the terminal-hosted product.
 
 Resource queues, retained state, evidence, logs, and diagnostics follow `docs/architecture/resource-and-data-policy.md`. Terminal content and authentication material are never control-store records. Unknown data is potentially sensitive by default and must be rejected or redacted before persistence.
 

package/docs/architecture/evidence/resident-tabs/linux-x64.md

@@ -0,0 +1,37 @@
+# Resident tabs acceptance: Linux x64
+
+State: CI-verified
+
+Physical acceptance against a published candidate package is pending; the operator runs [the checklist](../../../manual-resident-tabs-acceptance.md) and fills in this record. Until every item passes, resident tabs on this platform are CI-verified, not certified.
+
+| Field | Value |
+|---|---|
+| Package version | pending (first published candidate carrying the terminal host) |
+| terminal-host SHA-256 | pending (from that package's `terminal-host.manifest.json`) |
+| OS build | pending |
+| Terminal | pending |
+| Operator or worker | pending |
+| Date | pending |
+
+## Automated evidence
+
+- Pull-request `terminal-host` lane on `ubuntu-24.04`: native unit and role-integration suites, every named crash point recovering to a clean start, the 10,000-schedule simulation corpus, `a1 tabs` maintenance end to end, and the release build of the terminal host with its manifest, session lock, and notices.
+- Pull-request `resident-chaos` lane on `ubuntu-24.04`: bounded randomized kills of servers, holders, and agents against the release-built host, with no duplicate tabs or holders and no orphaned processes.
+- Publication `terminal_hosts` job on `ubuntu-24.04`: the release artifact is rebuilt, its `--version` identity checked, and packing refuses a missing or altered artifact.
+- Bounded fuzzing of every decoder and parser runs on this lane; it proves parser robustness, not platform behavior.
+
+## Physical verdicts
+
+| # | Item | Verdict | Notes |
+|---|---|---|---|
+| 1 | Terminal close mid-turn | pending |  |
+| 2 | SSH or remote-session loss | pending |  |
+| 3 | Forced attach-client kill | pending |  |
+| 4 | Reattach fidelity | pending |  |
+| 5 | Input and render smoothness | pending |  |
+| 6 | Extension text UI | pending |  |
+| 7 | Two clients and controller transfer | pending |  |
+| 8 | Server, holder, and child failure | pending |  |
+| 9 | Sensitive-data separation | pending |  |
+| 10 | Conflict-safe direct rollback | pending |  |
+| 11 | Logout (Linux) | pending |  |

package/docs/architecture/evidence/resident-tabs/macos-arm64.md

@@ -0,0 +1,36 @@
+# Resident tabs acceptance: macOS arm64
+
+State: CI-verified
+
+Physical acceptance against a published candidate package is pending; the operator runs [the checklist](../../../manual-resident-tabs-acceptance.md) and fills in this record. Until every item passes, resident tabs on this platform are CI-verified, not certified.
+
+| Field | Value |
+|---|---|
+| Package version | pending (first published candidate carrying the terminal host) |
+| terminal-host SHA-256 | pending (from that package's `terminal-host.manifest.json`) |
+| OS build | pending |
+| Terminal | pending |
+| Operator or worker | pending |
+| Date | pending |
+
+## Automated evidence
+
+- Pull-request `terminal-host` lane on `macos-15`: native unit and role-integration suites, every named crash point recovering to a clean start, the 10,000-schedule simulation corpus, `a1 tabs` maintenance end to end, and the release build of the terminal host with its manifest, session lock, and notices.
+- Pull-request `resident-chaos` lane on `macos-15`: bounded randomized kills of servers, holders, and agents against the release-built host, with no duplicate tabs or holders and no orphaned processes.
+- Publication `terminal_hosts` job on `macos-15`: the release artifact is rebuilt, its `--version` identity checked, and packing refuses a missing or altered artifact.
+
+## Physical verdicts
+
+| # | Item | Verdict | Notes |
+|---|---|---|---|
+| 1 | Terminal close mid-turn | pending |  |
+| 2 | SSH or remote-session loss | pending |  |
+| 3 | Forced attach-client kill | pending |  |
+| 4 | Reattach fidelity | pending |  |
+| 5 | Input and render smoothness | pending |  |
+| 6 | Extension text UI | pending |  |
+| 7 | Two clients and controller transfer | pending |  |
+| 8 | Server, holder, and child failure | pending |  |
+| 9 | Sensitive-data separation | pending |  |
+| 10 | Conflict-safe direct rollback | pending |  |
+| 11 | Logout (Linux) | not applicable | Linux-only item. |

package/docs/architecture/evidence/resident-tabs/macos-x64.md

@@ -0,0 +1,35 @@
+# Resident tabs acceptance: macOS x64
+
+State: CI-verified
+
+Physical acceptance against a published candidate package is pending; the operator runs [the checklist](../../../manual-resident-tabs-acceptance.md) and fills in this record. Until every item passes, resident tabs on this platform are CI-verified, not certified.
+
+| Field | Value |
+|---|---|
+| Package version | pending (first published candidate carrying the terminal host) |
+| terminal-host SHA-256 | pending (from that package's `terminal-host.manifest.json`) |
+| OS build | pending |
+| Terminal | pending |
+| Operator or worker | pending |
+| Date | pending |
+
+## Automated evidence
+
+- Publication `terminal_hosts` and `guardians` jobs on `macos-15` (arm64): the release terminal host and process guardian are cross-compiled for Intel macOS with `--target x86_64-apple-darwin`, the host's `--version` identity is checked through Rosetta 2 when the runner can execute it (otherwise the manifest records a Mach-O architecture check), and packing refuses a missing or altered artifact. Before 2026-10-16 the same builds ran natively on `macos-15-intel`.
+- Known gap: the pull-request `terminal-host` and `resident-chaos` suites run on macOS arm64 only, because modular validation outcomes are keyed by platform without architecture. Intel macOS has build and identity evidence but no automated behavior suite of its own.
+
+## Physical verdicts
+
+| # | Item | Verdict | Notes |
+|---|---|---|---|
+| 1 | Terminal close mid-turn | pending |  |
+| 2 | SSH or remote-session loss | pending |  |
+| 3 | Forced attach-client kill | pending |  |
+| 4 | Reattach fidelity | pending |  |
+| 5 | Input and render smoothness | pending |  |
+| 6 | Extension text UI | pending |  |
+| 7 | Two clients and controller transfer | pending |  |
+| 8 | Server, holder, and child failure | pending |  |
+| 9 | Sensitive-data separation | pending |  |
+| 10 | Conflict-safe direct rollback | pending |  |
+| 11 | Logout (Linux) | not applicable | Linux-only item. |

package/docs/architecture/evidence/resident-tabs/windows-x64.md

@@ -0,0 +1,36 @@
+# Resident tabs acceptance: Windows x64
+
+State: CI-verified
+
+Physical acceptance against a published candidate package is pending; the operator runs [the checklist](../../../manual-resident-tabs-acceptance.md) and fills in this record. Until every item passes, resident tabs on this platform are CI-verified, not certified.
+
+| Field | Value |
+|---|---|
+| Package version | pending (first published candidate carrying the terminal host) |
+| terminal-host SHA-256 | pending (from that package's `terminal-host.manifest.json`) |
+| OS build | pending |
+| Terminal | pending |
+| Operator or worker | pending |
+| Date | pending |
+
+## Automated evidence
+
+- Pull-request `terminal-host` lane on `windows-2025`: native unit and role-integration suites, every named crash point recovering to a clean start, the 10,000-schedule simulation corpus, `a1 tabs` maintenance end to end, and the release build of the terminal host with its manifest, session lock, and notices.
+- Pull-request `resident-chaos` lane on `windows-2025`: bounded randomized kills of servers, holders, and agents against the release-built host, with no duplicate tabs or holders and no orphaned processes.
+- Publication `terminal_hosts` job on `windows-2025`: the release artifact is rebuilt, its `--version` identity checked, and packing refuses a missing or altered artifact.
+
+## Physical verdicts
+
+| # | Item | Verdict | Notes |
+|---|---|---|---|
+| 1 | Terminal close mid-turn | pending | Milestone 2 passed this item against development build `09028be5` (run 38159593912); that evidence is for that build, not this package. |
+| 2 | SSH or remote-session loss | pending | Milestone 2 passed Windows OpenSSH loss against development build `09028be5`; it is not evidence for this package. |
+| 3 | Forced attach-client kill | pending |  |
+| 4 | Reattach fidelity | pending |  |
+| 5 | Input and render smoothness | pending |  |
+| 6 | Extension text UI | pending |  |
+| 7 | Two clients and controller transfer | pending |  |
+| 8 | Server, holder, and child failure | pending |  |
+| 9 | Sensitive-data separation | pending |  |
+| 10 | Conflict-safe direct rollback | pending |  |
+| 11 | Logout (Linux) | not applicable | Linux-only item. |

package/docs/architecture/evidence/terminal-host-spike/manual-one-pane-terminal-host.md

@@ -0,0 +1,70 @@
+# Manual one-pane terminal-host result
+
+## First manual artifact
+
+- Artifact: `native/terminal-host/target/debug/addone-terminal-host.exe`
+- SHA-256: `8d81db199687a9b8f195b4e40cb4b235de3ea00ffeb9cf55f9c64b1b3582cbba`
+- Size: 2,214,912 bytes
+- User-controlled run: one fullscreen `cmd.exe` pane inside Windows Terminal
+
+The user reported that typing commands, cursor movement, colors, Windows Terminal resize, and fast output worked correctly.
+
+The first artifact had one finding: `Ctrl+Shift+Q` did not exit.
+
+## Corrective artifact
+
+- Corrective artifact SHA-256: `1025a0823114477b7ab311ef55098647fc337b98a9194cf389fc124a047360bf`
+- Size: 2,227,712 bytes
+- Correction: accept `Ctrl+Q` or `Ctrl+Shift+Q`, including uppercase key delivery.
+- Correction: resolve Windows command shims through generic PATH/PATHEXT lookup; `pi` resolves to `C:\Users\tprokopiev\AppData\Roaming\npm\pi.cmd`.
+- Automated non-interactive result after correction: build, version/provenance, terminal model, PTY start, process exit, and cleanup passed.
+
+## Follow-up artifact
+
+- Artifact SHA-256: `b083af60eb8c4ca90438e4022c4e6d10b1410dda5554f554a8b814ba2cdee291`
+- Size: 2,238,464 bytes
+- Removed the host-owned quit shortcut so `Ctrl+Q` no longer intercepts input.
+- Added generic calling-shell ancestry detection; this Git Bash environment resolves to `C:\Program Files\Git\usr\bin\bash.exe --login -i`.
+- Disabled mouse capture by default so the outer terminal can provide native selection.
+- Added `Shift+PageUp`/`Shift+PageDown` and `Shift+Up`/`Shift+Down` host scrollback.
+- Non-interactive terminal model and PTY cleanup probes pass.
+
+## Theme-preservation artifact
+
+- Artifact SHA-256: `9989373d1ee28ac42bf7a6b1be02d68b92c23b71f14336db493a93d76df48198`
+- Size: 2,238,464 bytes
+- The frame composer now emits the outer terminal's default foreground/background for unstyled cells instead of forcing black.
+- The automated probe asserts the default-background sequence and passes.
+
+## Palette-preservation artifact
+
+- Artifact SHA-256: `203219f0ee79f3086467dccb5479b5749b09f8bac79623f84682545d374ba2f4`
+- Size: 2,238,976 bytes
+- Palette-indexed child colors are emitted as palette indexes (`38;5;n` / `48;5;n`) instead of being converted through Ghostty's default RGB palette.
+- The automated probe asserts default-background and palette-passthrough sequences and passes.
+
+## Scrollback artifact
+
+- Artifact SHA-256: `6280786d713abe37eb979e309d27b7ed1eb1f1e1e76e485b0bc5f9c357391ca6`
+- Size: 2,246,656 bytes
+- Mouse capture is enabled so wheel events reach the host; wheel and Shift+navigation scroll the retained terminal viewport.
+- Viewport changes mark the frame dirty before composition.
+- The non-interactive probe verifies retained scrollback, viewport movement, and repainted earlier content.
+- Use the outer terminal's modifier-based selection, usually Shift+drag in Windows Terminal, while pointer capture is active.
+
+## Selection and exit artifact
+
+- Artifact SHA-256: `fc6d9d1ecbaae4718b850a42b5e6868758d1f4c8c8e1a7645237115d1f1d883c`
+- Size: 2,266,624 bytes
+- Plain left-drag selects terminal content with one uniform white background and black foreground; release emits an OSC 52 clipboard write.
+- Double-click selects a word; triple-click selects a line.
+- Ctrl+C clears an active host selection before reaching the child; without selection, interrupt keys remain child-owned.
+- Mouse wheel scrolls the retained viewport. Home, End, PageUp, PageDown, and arrow keys remain child-owned; no host keyboard scroll binding is active.
+- PTY output-channel closure exits the host when the child session ends.
+- Non-interactive probes pass for terminal rendering, scrollback, selection, and PTY cleanup.
+
+Manual retest should verify plain drag selection, double/triple click, mouse wheel, and Ctrl+C selection clearing. No terminal was launched or driven by automation on the active workstation.
+
+## User acceptance
+
+The user manually confirmed that the vanilla-Pi terminal-host proof launches and works after the interaction corrections. The accepted one-pane pipeline includes theme/palette preservation, retained scrollback, mouse wheel scrolling, plain drag selection, word/line click selection, selection clearing with Ctrl+C, and child-owned interrupt behavior. Task 5.1 is accepted; the next gate is the 2×2 multi-pane proof.

package/docs/architecture/evidence/terminal-host-spike/manual-two-by-two-basic-terminal-host.md

@@ -0,0 +1,32 @@
+# Manual 2×2 terminal-host basic result
+
+## Exact artifact
+
+- Recorded at: `2026-08-14T16:13:20.217Z`
+- Source commit: `aeb7421ff5cc82bc5da04cfb0d356e8f8041b6cb`
+- Artifact: `native/terminal-host/target/debug/addone-terminal-host.exe`
+- SHA-256: `896e1b5d2e2730dfd8e591fe3bd565a2aa283fb3ec6f64e8345745c6afcf024d`
+- Size: 2,367,488 bytes
+- Invocation: user-controlled `npm run proof:terminal-host`
+- Surface: one existing outer terminal, one fixed tab, four independently PTY-backed Pi sessions
+
+## User-reported result
+
+The user manually confirmed all of the following against the exact artifact:
+
+- all four panes launched Pi;
+- the four-pane presentation worked without observed flicker;
+- pane focus and input routing worked;
+- changing or clicking the focused pane preserved content in every pane after the repaint correction.
+
+The user accepted this basic multi-pane proof result.
+
+## Explicit product disposition
+
+The fixed 2×2 grid and dashed pane outlines are disposable proof scaffolding, not an accepted production layout or UI design. This result proves the native multi-pane pipeline only. It does not approve carrying the fixed geometry, border treatment, or proof interaction model into the product.
+
+Production tabs and panes are expected later to use authoritative arbitrary layouts selected through the AddOne UI. The proof implementation may be removed or replaced after the exact-artifact 2×2 gate is finished; it must not become the default production workspace by inertia.
+
+## Gate scope
+
+This record does not complete the formal tasks 5.3–5.6 acceptance gate. High-rate output, broader terminal modes and interactions, resize/terminal-size measurements, resource observations, abnormal exits, isolated-worker requirements, and the final stop/go decision remain separately required. No automated physical terminal control was performed on the active workstation.

package/docs/architecture/evidence/terminal-host-spike/milestone-baseline.json

@@ -0,0 +1,115 @@
+{
+  "schema": "addone-multi-agent-milestone-baseline-v1",
+  "recordedAt": "2026-08-13T17:49:35.803Z",
+  "branch": "milestone/multi-agent-workspace",
+  "source": {
+    "commit": "8f4a45b907c8ccfca9b6fad52bd12c2bfe7b1172",
+    "tree": "f702a5cc6fba92a430d00634504039f0d8f4a304",
+    "developCommitAtBranchCreation": "8f4a45b907c8ccfca9b6fad52bd12c2bfe7b1172",
+    "originDevelopAtBranchCreation": "a526a63062b2f93db821c631548da885e20dc41d",
+    "tagAtCommit": null,
+    "cleanAtBranchCreation": true
+  },
+  "runtime": {
+    "platform": "win32",
+    "architecture": "x64",
+    "osRelease": "10.0.26200",
+    "node": "v24.16.0",
+    "npm": "11.13.0"
+  },
+  "package": {
+    "name": "@timurproko/addone",
+    "version": "0.1.5-dev.10",
+    "packageManager": "npm@11.13.0",
+    "nodeRange": ">=22.19.0 <25",
+    "lockfileVersion": 3,
+    "packageJsonSha256": "fb5966d03c9efb8d7aa726cc0582f34227aa525bf28baaa492c0a8af7fa0b617",
+    "packageLockSha256": "626b54ca5b5619c71a2dc7d667d49e4746bdea268be6fafa0635011f97824b80",
+    "localTarball": {
+      "filename": "timurproko-addone-0.1.5-dev.10.tgz",
+      "integrity": "sha512-7gLuq3Ec8uU76jXNWiBYUYMdK9O8roRROjs36xOnhJ+M9jboSRLdSBc0zQQXNqmsD6xa9b/87o/UqymmkbsFlg==",
+      "shasum": "370482e37ba171f7bd52f57eb6969c6c5940c2f4",
+      "sha256": "1046f005802bd1372ae232d5301d038511f7c9f072d1e0cb1a4ea1965b5f112f",
+      "size": 80121,
+      "unpackedSize": 370136,
+      "fileCount": 167,
+      "note": "Locally packed milestone source; it intentionally differs from the already-published dev.10 bytes because later documentation and update wording commits are present."
+    },
+    "registry": {
+      "latest": "0.1.4",
+      "next": "0.1.5-dev.10",
+      "nextIntegrity": "sha512-XjwhIsCbZjJbAwFQjWLnSsSS6Lb21Uls1MhkQUXOAiJh5Fg7IfQI4Ol4gMUGuzxSzOf38Cor+F+zB8nHLh79Dg==",
+      "nextShasum": "4af9a7697ad79209214889a8c56f3bb19228fb65"
+    }
+  },
+  "launchProfiles": {
+    "terminalCapability": "transparent",
+    "addone": {
+      "invocation": "a1",
+      "configurationRoot": "~/.a1/agent",
+      "projectTrust": "pi-default"
+    },
+    "pi": {
+      "invocation": "a1 pi",
+      "configurationRoot": "~/.pi/agent",
+      "environmentRule": "PI_CODING_AGENT_DIR removed",
+      "projectTrust": "pi-default"
+    },
+    "evidenceHashes": {
+      "documentationSha256": "0fcc0a7823dcdad2f00d6e2c82ba117d14b7cb2a2fcebfbb2615eafd94413003",
+      "contractsSha256": "bc63eeacdc65b89b0b4d84c2e25a4fb8f937d1864ab4275119a4a0aec707a38c",
+      "pathsSha256": "5a263fa07d3ccfd21a71721b43a99844d46f7cc15ed8f36caa556c1cc0cbbdfa",
+      "preparationSha256": "b5eb00f3c6ebbfda0dd9e8e793b6553b00720a4d24f24d5bcacf1d0f7183687d",
+      "isolationTestSha256": "9c72d63d2a4bcc143d73afbbe921821c3d813e10a4b0297288dff93bcb77d07e"
+    }
+  },
+  "gates": [
+    {
+      "command": "npm ci",
+      "passed": true,
+      "detail": "68 packages installed; 0 vulnerabilities"
+    },
+    {
+      "command": "npm run build",
+      "passed": true
+    },
+    {
+      "command": "npm run check",
+      "passed": true,
+      "detail": "typecheck, architecture, deprecated-dependency policy, 31 Vitest files/155 tests, and 1 release file/3 tests"
+    },
+    {
+      "command": "npm audit --audit-level=high --json",
+      "passed": true,
+      "detail": "0 vulnerabilities"
+    },
+    {
+      "command": "openspec validate --specs --strict --no-interactive",
+      "passed": true,
+      "detail": "7 main specifications"
+    },
+    {
+      "command": "openspec validate evolve-bare-a1-into-multi-agent-workspace --strict --no-interactive",
+      "passed": true
+    },
+    {
+      "command": "npm pack --ignore-scripts --json",
+      "passed": true,
+      "detail": "exact local tarball metadata and SHA-256 recorded"
+    }
+  ],
+  "releaseVerdict": {
+    "schema": "addone-development-preview-platform-verdict-v2",
+    "passed": true,
+    "certificationStatus": "uncertified-development-preview",
+    "terminalCapability": "transparent",
+    "physicalHostCertification": "deferred",
+    "crossPlatformCertification": "deferred",
+    "stableReleaseEligible": false
+  },
+  "desktopAutomation": "not-run",
+  "terminalApplicationsLaunched": false,
+  "physicalCertification": "deferred",
+  "stableReleaseEligible": false,
+  "passed": true
+}

package/docs/architecture/evidence/terminal-host-spike/owned-ui-foundation-prerequisite.json

@@ -0,0 +1,48 @@
+{
+  "schema": "addone-multi-agent-owned-ui-prerequisite-v1",
+  "milestone": "evolve-bare-a1-into-multi-agent-workspace",
+  "prerequisiteChange": "build-owned-pi-ui-foundation",
+  "recordedAt": "2026-08-17T12:31:58Z",
+  "result": "satisfied",
+  "acceptedBaselineCommit": "084d0fb7e4004bc4b83a0b28c8aaea736b558d44",
+  "hardenedFoundationCommit": "efb244472fa4e6499300533a3f535fe60ab7f948",
+  "publishedSourceCommit": "d407ed017a6f9216a9a0c62d85d7cd44803d4d2c",
+  "publication": {
+    "package": "@timurproko/addone@0.1.5-dev.11",
+    "tag": "next",
+    "workflowRun": "https://github.com/timurproko/addone/actions/runs/32030101549",
+    "integrity": "sha512-05GQdg7ZfvcEpI6wAvebyx/06JPnV5AUtSbptx7P3mzT28iU4yurP87uKIKsvpNwPzjMsr8k5RfiAeEyq/GfpQ==",
+    "latestPreserved": "0.1.4"
+  },
+  "acceptance": {
+    "sourcePortCoverage": "109 records and 29 behaviors; zero pending or stale entries",
+    "modalCoverage": "47 nodes, 111 transitions, and 36 settings instances",
+    "terminalParity": "54 checkpoints with zero differences",
+    "extensionBoundary": "validated public ExtensionUIContext translated through AddOne-owned contracts",
+    "zeroDebtGate": "passed",
+    "manualBaseAcceptance": "passed",
+    "prohibitedRuntimeOrPackagePatches": 0
+  },
+  "compositionBoundary": {
+    "ownedContractsComposableForStructuredTabs": true,
+    "terminalHostInitializationRequired": false,
+    "ptyCreationRequired": false,
+    "interactiveModeMutationRequired": false,
+    "deepPiImportsRequired": false
+  },
+  "milestoneAuthorization": {
+    "task5_4OwnedUiPrerequisite": "complete",
+    "structuredTabsMayBeginAtTask5_5": true,
+    "structuredTabsStartedByThisRecord": false,
+    "section6MayBegin": false,
+    "section6Blocker": "Section 6 additionally requires terminal-host proof acceptance; this record satisfies only the owned-UI prerequisite.",
+    "composedTerminalWorkAuthorized": false
+  },
+  "evidence": [
+    "evidence/owned-pi-ui-foundation/automated-evidence-7.35-zero-debt-final-gates.json",
+    "evidence/owned-pi-ui-foundation/zero-debt-architecture-audit.md",
+    "evidence/owned-pi-ui-foundation/manual-acceptance-pi-0.84.2-base-084d0fb.json",
+    "evidence/owned-pi-ui-foundation/owned-ui-shell-composability.json",
+    "evidence/owned-pi-ui-foundation/automated-evidence-8.5-next-publication.json"
+  ]
+}

package/docs/architecture/evidence/terminal-host-spike/terminal-host-provenance.json

@@ -0,0 +1,125 @@
+{
+  "schema": "a1-terminal-host-provenance-v1",
+  "recordedAt": "2026-08-20T09:25:48.307Z",
+  "change": "evolve-bare-a1-into-multi-agent-workspace",
+  "hostMode": "console-inside-existing-terminal",
+  "desktopApplicationRequired": false,
+  "sources": [
+    {
+      "name": "libghostty-vt",
+      "repository": "https://github.com/ghostty-org/ghostty",
+      "commit": "c5a21edfcbc2d5b46540ad91b7980aca31f5f1f3",
+      "committedAt": "2026-07-14T20:12:12-07:00",
+      "role": "terminal parsing, retained state, and input semantics",
+      "license": "MIT",
+      "licenseNotice": "Copyright (c) 2024 Mitchell Hashimoto, Ghostty contributors",
+      "licenseSha256": "3129de97bc7769d683e52ce02cb4eaecd2b0aab144b09d6325a1b135bdc87cc0",
+      "cleanSourceTree": true,
+      "licenseVerification": "verified-local-license-file"
+    },
+    {
+      "name": "portable-pty",
+      "version": "0.9.0",
+      "role": "ConPTY and Unix PTY/process ownership",
+      "license": "MIT",
+      "licenseNotice": "Copyright (c) 2018 Wez Furlong",
+      "licenseSha256": "c06f48b2acbbb4bb88345225c6d85264773528fe9fc99241cd255a7e32be632e",
+      "cleanSourceTree": true,
+      "licenseVerification": "verified-local-license-file"
+    },
+    {
+      "name": "crossterm",
+      "version": "0.29.0",
+      "registryChecksum": "d8b9f2e4c67f833b660cdb0a3523065869fb35570177239812ed4c905aeff87b",
+      "role": "outer-terminal raw mode and host input events",
+      "license": "MIT",
+      "cleanSourceTree": true,
+      "licenseVerification": "declared-license-recorded; license notice must be vendored before packaging"
+    }
+  ],
+  "rendererPolicy": {
+    "initial": "A1-owned buffered frame composer",
+    "ratatui": "optional evaluation candidate, not selected by default"
+  },
+  "excludedStacks": [
+    "Ghostty desktop application",
+    "Winghostty Win32 runtime",
+    "OpenGL/WGL",
+    "Metal",
+    "GTK",
+    "AppKit",
+    "Herdr",
+    "Node terminal parser",
+    "Node terminal renderer"
+  ],
+  "patchPolicy": {
+    "default": "retain upstream behavior without local patches",
+    "requiredPatchFields": [
+      "source revision",
+      "target revision",
+      "reason",
+      "tests",
+      "upstream synchronization decision",
+      "license impact"
+    ],
+    "behavioralTerminalPatchesRequireSeparateReview": true
+  },
+  "buildPrerequisites": {
+    "operatingSystems": [
+      "windows-10",
+      "windows-11"
+    ],
+    "architectures": [
+      "x64",
+      "arm64"
+    ],
+    "language": "Rust",
+    "zig": ">=0.15.2 <0.16",
+    "cToolchain": "Visual Studio 2022 Build Tools/MSVC on Windows",
+    "terminal": "user-owned terminal emulator",
+    "isolatedPhysicalWorkerRequired": true,
+    "guiSdkRequired": false,
+    "openGlRequired": false,
+    "win32WindowRuntimeRequired": false,
+    "localProbe": {
+      "rustAvailable": true,
+      "rustVersion": "1.97.1",
+      "zigAvailable": true,
+      "zigVersion": "0.15.2",
+      "requiredZigAvailable": true,
+      "nativeBuildAttempted": true,
+      "reason": "Rust 1.97.1 and Zig 0.15.2 are available; the clean console-host build and non-interactive probe pass."
+    }
+  },
+  "artifactManifestRequirements": [
+    "artifactPath",
+    "sha256",
+    "sizeBytes",
+    "signatureStatus",
+    "buildTimestamp",
+    "a1Commit",
+    "a1ProtocolVersion",
+    "libghosttyVtCommit",
+    "ptyComponentVersion",
+    "hostInputComponentVersion",
+    "rendererComponentIdentity",
+    "retainedComponents",
+    "adaptedComponents",
+    "compilerVersions",
+    "targetTriple",
+    "licenseHashes",
+    "buildCommand",
+    "dependencyCacheProvenance",
+    "cleanSourceTree",
+    "evidenceSchema",
+    "physicalVerdictReference"
+  ],
+  "checks": {
+    "license": "passed",
+    "provenance": "passed",
+    "sourceTreeHygiene": "passed",
+    "binaryBuild": "passed",
+    "physicalAutomation": "not-run"
+  },
+  "passed": true
+}