@timurproko/a1 0.1.8-dev.235df0e → 0.1.8-dev.260

package/docs/architecture/boundaries.md

@@ -9,15 +9,15 @@ mutable a1 entry
   -> verified immutable release
   -> Node launch guardian and authenticated launch-instance registration
   -> native process guardian and per-instance containment
-  -> a1-ui runtime selection
-  -> owned UI or transparent Pi with inherited physical terminal handles
+  -> profile-aware owned-UI 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`, `a1 pi`, and `a1 sandbox` 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.
+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. Bare `a1` retains its owned UI authority. In explicit Pi profiles, Pi and the physical terminal retain direct terminal behavior. The private guardian boundary carries only bounded identity, readiness, stop, and outcome data.
+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.
 
-Transparent mode has no A1-authoritative terminal surface, internal pane, virtual scrollback, inactive resident tab, or visual reconnection. A future feature that requires those properties must introduce and certify a separate composed-terminal authority; it must not weaken or silently intercept transparent mode.
+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
 
@@ -30,20 +30,20 @@ Transparent mode has no A1-authoritative terminal surface, internal pane, virtua
 - `protocol`: additive control handshake, bounded line framing, authenticated launch-instance commands, typed stop intent, snapshots, and command results.
 - `storage`: SQLite migrations, prior-boot reconciliation, and plural launch-instance persistence. Legacy foreground rows are historical migration input and never authorize current ownership.
 - `supervisor`: endpoint identity, plural cohort ownership, per-instance reconciliation, and aggregate release shutdown coordination. It owns no terminal surface.
-- `transparent-terminal`: generic command resolution and direct inherited-handle child waiting below the outer launch guardian; it owns no supervisor lease.
+- `pi-engine-adapter`, `pi-component-adapter`, `pi-tui-runtime-adapter`, and `pi-session-ui-integration`: isolate pinned Pi engine and presentation knowledge behind neutral contracts; product features do not import them directly. The session UI 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 Pi session UI.
 - release/update/bootstrap: package-derived immutable release identity, process-guardian integrity, cohort selection, durable update transactions, rollback, and dependency-light command entry.
 
 ## 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 transparent 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 enter transparent mode. 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 native boundary and is independent from the held composed terminal host.
 
-`scripts/check-architecture.mjs` enforces the structural parts of these boundaries. Cross-cutting rationale belongs here; implementation history belongs in Git and archived OpenSpec changes.
+`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.
 
 ## Planned multi-agent boundaries
 
-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. Explicit launch profiles and transparent fallback may not import, initialize, launch, or connect to composed terminal-host infrastructure.
+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.
 
 Default future agents and composed hosts are children of the originating bare-`a1` launch instance and terminate when it closes. A process that survives command closure requires a separately approved explicit resident capability; durable identity or state recovery never implies an implicitly surviving process.
 

package/docs/architecture/code-documentation.md

@@ -0,0 +1,77 @@
+# Code documentation
+
+A1 treats source documentation as a contract, not as a coverage target. Names, types, and decomposition explain ordinary behavior. Comments remain only where removing them would hide a public responsibility, invariant, rationale, security property, platform constraint, compatibility boundary, protocol rule, concurrency rule, performance decision, or provenance fact.
+
+## Public class contracts
+
+Every first-party TypeScript class exposed through a production owner's public entry has exactly one JSDoc description at its declaration. The description states what the class owns and includes its material lifecycle or safety boundary when one exists.
+
+Do not add JSDoc solely because a function, type, constructor, property, or method is exported. Do not document a class by repeating its name or listing its methods. Private and protected members never use JSDoc.
+
+```ts
+/** Persists complete workspace views and recovery references through the control-store boundary. */
+export class WorkspaceStore {
+```
+
+## Implementation comments
+
+A retained implementation comment starts with the reason it exists:
+
+| Intent | Use |
+| --- | --- |
+| `Invariant:` | State or ordering that every implementation path must preserve |
+| `Rationale:` | A non-obvious choice among plausible alternatives |
+| `Security:` | Trust, ownership, cleanup, disclosure, or failure-safety boundary |
+| `Platform:` | Operating-system, terminal, filesystem, or toolchain behavior |
+| `Compatibility:` | Behavior intentionally matching or accepting another version or surface |
+| `Protocol:` | Wire, framing, input, encoding, or externally defined semantic rule |
+| `Concurrency:` | Race, serialization, cancellation, or event-loop ordering |
+| `Performance:` | Bounded work, caching, coalescing, or resource decision |
+| `Provenance:` | Source, generated authority, or adaptation origin |
+
+```ts
+// Security: an uncertain process identity never authorizes termination.
+// Platform: Windows Terminal encodes Ctrl+Backspace as a raw backspace byte.
+// Performance: finalized blocks cache by revision and width; live blocks always render.
+```
+
+A continuation line does not repeat the label. If no intent applies, remove the comment and make the code explain itself.
+
+## Forbidden forms
+
+The repository gate rejects:
+
+- missing or multiple contracts on owner-public first-party classes;
+- `<summary>` and `@summary` tags;
+- boilerplate class descriptions and method inventories;
+- JSDoc on private or protected members;
+- uncategorized implementation comments;
+- obvious commented-out code or control-flow narration;
+- `TODO` or `FIXME` without an issue number, issue URL, or tracker identifier;
+- `@ts-ignore` and suppression directives without a reason;
+- an unclassified tracked code path or synchronized source without provenance.
+
+Follow-up and suppression forms include their authority inline:
+
+```ts
+// TODO(#321): remove the compatibility path after the pinned upgrade.
+// @ts-expect-error -- the shipped JavaScript module has no declaration file
+```
+
+## Source roles
+
+The full style policy applies to first-party production TypeScript and to applicable comments in first-party tests, tooling, and native source. Native source does not receive TypeScript declaration requirements.
+
+Synchronized Pi source, native vendor trees, generated source, build output, and runtime artifacts are not rewritten to match first-party style. Their exclusion comes from the repository source-role classifier, not from a list of accepted violations. Synchronized source must remain covered by its source ledger or explicit provenance header.
+
+## Validation
+
+Run the focused check with:
+
+```sh
+npm run check:code-documentation
+```
+
+The check scans the complete tracked baseline and reports stable rule identifiers with path, line, column, and declaration symbol when available. It has no accepted-violation count or grandfather file. Fast pull-request validation runs the check, and full release validation inherits it through the fast tier.
+
+Focused governance tests use valid and invalid virtual sources to preserve each rule independently from the clean repository-baseline assertion. The gate validates deterministic structure and high-confidence anti-patterns; review remains responsible for the factual accuracy of retained prose.

package/docs/architecture/process-guardian-provenance.md

@@ -8,6 +8,8 @@ The executable owns platform process containment and launches one immutable `a1-
 
 On Windows it uses `windows-sys 0.61.2` to create a Job Object, enables `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE`, assigns the runtime before resuming it, denies silent breakaway by never enabling breakaway limits, monitors the verified Node parent process, and terminates remaining job members after root or parent exit.
 
+On Linux and macOS it creates a dedicated POSIX process group before exec, transfers foreground-terminal ownership only when a terminal is present, monitors the verified parent, applies bounded TERM/KILL cleanup to that group, and restores the prior foreground group. Linux derives process start identity from procfs. macOS derives it from the native `proc_pidinfo(PROC_PIDTBSDINFO)` start timestamp; PID liveness alone is never treated as identity.
+
 ## Artifact contract
 
 Release builds place the exact executable at:
@@ -19,7 +21,7 @@ dist/native/darwin-x64/process-guardian
 dist/native/darwin-arm64/process-guardian
 ```
 
-Each supported artifact must be named in the release integrity manifest with target triple, crate version, guardian protocol version, SHA-256, byte size, build provenance, and signature/attestation status. A missing, altered, incompatible, or wrong-platform artifact is a concise unsupported-containment launch error; A1 never silently falls back to PID-only cleanup.
+Each supported artifact must be named in the release integrity manifest with target triple, crate version, guardian protocol version, SHA-256, byte size, build provenance, and signature/attestation status. The build marks a platform supported only after its native containment integration runs on that platform. A missing, altered, incompatible, unsupported, or wrong-platform artifact is a concise containment launch error; A1 never silently falls back to PID-only cleanup.
 
 ## Licensing
 

package/docs/architecture/project-structure.md

@@ -1,30 +1,51 @@
 # Project structure
 
-Every production module has one named owner. The executable owner map and allowed dependencies live in `scripts/project-structure-policy.mjs`; this document explains the conventions behind it.
+Every production module has one named owner. The executable owner map and allowed dependencies live in `scripts/governance/project-structure-policy.mjs`; this document explains the conventions behind it. `npm run check:architecture` rejects production files without an owner, cross-owner private imports, and declared owners whose source root, public entry, or test root is missing.
 
 ## Production owners
 
 ```text
 src/
-  cli/                         public command helpers and dispatch
+  product-identity.ts              centralized externally visible product identity
+  product-identity.json
+  cli/                             public command parsing, capabilities, packages, and version reporting
+  composition/                     process-level wiring of neutral contracts to concrete adapters
   features/
-    launch/                    product launch profiles and profile settings
-    workspace/                 multi-agent workspace presentation, reducer state, and persistence orchestration
+    launch/                        launch profiles, profile paths, and runtime selection
+    owned-ui/                      owned screens, settings application, diagnostics, and runtime lifecycle
+    workspace/                     multi-agent presentation, reducer state, routing, and persistence orchestration
+  contracts/
+    agent-engine/                  dependency-free agent engine, session, package, and capability ports
+    owned-ui/                      dependency-free owned-session and extension UI contracts
+    presentation/                  dependency-free component, terminal, and runtime ports
+    workspace/                     dependency-free workspace, topology, host, and recovery contracts
+  integrations/
+    pi/
+      components/                  pinned Pi component and theme adaptation
+      engine/                      pinned Pi engine, settings, resource, package, and workflow integration
+      session-ui/                  Pi-backed session shell and A1 viewport integration
+      tui-runtime/                 neutral presentation runtime over pinned Pi TUI
   foundation/
-    lifecycle/                 dependency-free launch/lifecycle contracts and paths
-    protocol/                  control framing and client contracts
-    release/                   immutable releases, cohorts, update, rollback, cleanup
-    storage/                   control-store persistence
-    structured-agent-runtime/  structured/RPC handshake, event, command, and recovery semantics
-    native-host-protocol/      bounded terminal-host identity, topology, lifecycle, and proof protocol
-    supervision/               endpoint and foreground-lease ownership
-    workspace-contracts/       dependency-free workspace, adapter, topology, host, and recovery contracts
-    transparent-terminal/      exact command resolution and native attachment
+    launch-guardian/               authenticated launch-instance coordination
+    lifecycle/                     dependency-free launch, process identity, and path contracts
+    native-host-protocol/          bounded terminal-host identity, topology, lifecycle, and proof protocol
+    process-containment/           verified native containment and process inspection
+    protocol/                      authenticated control framing and client contracts
+    release/                       immutable releases, update, rollback, cohorts, and cleanup
+    storage/                       control-store persistence
+    structured-agent-runtime/      structured handshake, event, command, backpressure, and recovery semantics
+    supervision/                   endpoint, launch-instance, and release-cohort ownership
+  ui/
+    apps/                          application registry and host lifecycle
+    components/                    vendor-neutral terminal UI primitives
+    settings/                      owned settings declarations, resolution, migration, and persistence
 ```
 
-Each owner exposes `index.ts`. Imports within one owner may use private files. Imports crossing owners must use the provider's `index.ts` and follow the declared dependency DAG. Foundation modules never import product features.
+Each directory owner exposes `index.ts`. Imports within one owner may use private files. Imports crossing owners must use the provider's public entry and follow the dependency DAG declared by `PROJECT_OWNERS`. `product-identity` is the sole current exception to the directory-entry convention because its public entry is `src/product-identity.ts`.
 
-`src/cli` is a thin public entry layer. Product policy belongs in a named feature. Shared code moves to foundation only when it is product-agnostic, has a precise contract, and has more than one real consumer. Do not create `core`, `common`, `utils`, or `misc` dumping grounds.
+`src/cli` contains command policy but delegates runtime work. `src/composition` is the concrete dependency-injection boundary: it may know both neutral contracts and Pi implementations, while product features receive vendor-neutral ports. Foundation modules never import product features. Pi package knowledge remains inside the Pi adapter owners.
+
+Shared code moves to foundation only when it is product-agnostic, has a precise contract, and has more than one real consumer. Do not create `core`, `common`, `utils`, or `misc` dumping grounds.
 
 ## Feature ownership
 
@@ -32,11 +53,11 @@ A feature owns:
 
 - its production behavior under `src/features/<name>`;
 - its public contract in `index.ts`;
-- its settings schema/defaults and path policy;
+- its settings schema, defaults, and path policy when applicable;
 - its tests under `test/features/<name>`;
-- user-facing feature documentation under `docs/features/<name>.md` when the behavior needs more than README coverage.
+- user-facing documentation under `docs/features/<name>.md` when README coverage is insufficient.
 
-Settings files are not mandatory for every feature. Add one only when the feature owns mutable policy. User settings, credentials, sessions, caches, downloaded packages, logs, and generated files never live in source folders.
+Settings files are not mandatory for every feature. User settings, credentials, sessions, caches, downloaded packages, logs, and generated files never live in source folders.
 
 ## Test ownership
 
@@ -45,37 +66,53 @@ Tests mirror their production owner:
 ```text
 test/
   cli/
+  composition/
   features/<name>/
+  contracts/<name>/
   foundation/<name>/
+  integrations/pi/<name>/
+  product-identity/
   repository-governance/
+  ui/<name>/
 ```
 
-Use `.test.ts` for deterministic owner-level contracts. Use `.integration.test.ts` when the contract crosses real process, filesystem, registry, or release boundaries. Prefer the smallest independent boundary that proves the observable result; do not duplicate a stronger test or preserve historical bug-story names after the cause has a current invariant.
+Use `.test.ts` for deterministic owner-level contracts. Use `.integration.test.ts` when the contract crosses real process, filesystem, registry, package, or release boundaries. A test of a foundation implementation belongs to that foundation owner's test root; a feature test may exercise the same public entry only when it proves feature-level composition.
 
-Physical desktop automation is not an ordinary integration test. It requires a separately authorized certification change and isolated disposable infrastructure.
+Prefer the smallest independent boundary that proves the observable result. Do not duplicate a stronger test or preserve historical bug-story names after the cause has a current invariant. Physical desktop automation is not an ordinary integration test; it requires separately authorized certification and isolated disposable infrastructure.
 
 ## Repository authority
 
 The repository has one root `package.json`, `package-lock.json`, TypeScript configuration, Vitest configuration, and dependency installation. Nested manifests, lockfiles, `node_modules`, vendored package caches, logs, sessions, browser profiles, generated output, and runtime state are forbidden under production and feature trees.
 
-Build output belongs in ignored `dist/`; release/test evidence belongs in ignored `artifacts/`. Package contents are selected by the root manifest. Native proof code lives under `native/terminal-host/`; its Cargo build output and vendored Zig build output are ignored, and it remains a console terminal host rather than a desktop application.
+Build output mirrors the production namespaces directly under ignored `dist/`, without an intermediate `src/` directory; release and test evidence belongs in ignored `.artifacts/`; temporary agent work belongs in ignored `.worktrees/` and `.builds/`. Repository tooling is grouped under `scripts/governance`, `scripts/release`, `scripts/pi`, and `scripts/development`; the few root scripts are standalone maintenance or build commands. Package contents are selected by the root manifest. The Rust process guardian and console terminal-host proof live under `native/`; Cargo output is ignored. Third-party terminal parser sources are isolated under `native/terminal-host/vendor/` and are not owned application modules.
+
+## Development worktrees
+
+Every task worktree must be created at `{working-dir}/.worktrees/<task-id>`, where `{working-dir}` is the agent session's initial working directory. The `.worktrees` directory is inside that working directory, not beside it. For working directory `D:/Git/a1`, `D:/Git/a1/.worktrees/<task-id>` is correct and `D:/Git/a1-<task-id>` is forbidden.
+
+From the initial working directory, create and address a task worktree explicitly:
+
+```sh
+git fetch origin develop
+git worktree add --detach .worktrees/<task-id> origin/develop
+git -C .worktrees/<task-id> status
+```
+
+The primary worktree stays on `develop` for integration and must not be used for task edits. Do not edit, move, or remove another session's worktree.
 
 ## Documentation and comments
 
 - README explains installation, commands, and current limitations.
 - `docs/architecture` explains cross-cutting ownership and irreversible constraints.
-- `docs/architecture/resource-and-data-policy.md` defines bounded queues, data classes, redaction, terminal-content non-persistence, and proof acceptance rules.
-- `docs/architecture/terminal-host-provenance.md` records pinned terminal-component revisions, retained components, patch policy, and artifact provenance requirements.
-- `docs/architecture/terminal-host-spike-evidence.md` defines the mandatory in-terminal 2×2 proof workloads, measurements, and acceptance invariants.
-- `docs/architecture/terminal-host-proof-gate.md` defines the non-waivable stop/go acceptance policy and current pending record.
-- `docs/features` explains maintained user-facing feature behavior.
+- `docs/features` explains maintained user-facing behavior.
+- Operational and manual procedures live in focused runbooks under `docs`.
 - OpenSpec and Git carry planning and implementation history.
-- Source comments explain only non-obvious rationale, safety/security invariants, platform constraints, or public semantic contracts. Names, types, and decomposition explain normal control flow.
+- Source documentation follows the focused [code-documentation policy](code-documentation.md): owner-public class contracts are consistent, retained implementation comments state their intent, and names, types, and decomposition explain ordinary control flow.
 
 ## Terminal capability boundary
 
-Transparent terminal attachment owns one foreground child and no A1 surface. It cannot retain inactive terminal state or switch among arbitrary interactive CLIs inside A1. Bare-`a1` multi-agent UX may use structured/RPC surfaces without terminal emulation, but arbitrary-CLI tabs require a separate composed-terminal capability with PTY, authoritative terminal state, rendering, input routing, inactive-surface lifecycle, reconnection, and cross-platform certification. That future capability must not silently intercept or replace the transparent path. Explicit launch profiles and transparent fallback must not import, initialize, launch, or connect to composed terminal-host infrastructure.
+Both interactive profiles use the owned rendering pipeline. Bare `a1` exposes A1-owned surfaces; `a1 pi` withholds those surfaces while using Pi's ordinary profile root. The retired transparent attachment owner is not part of the production tree or dependency map.
 
-Composed terminals use a console terminal host that runs inside the user's existing terminal. The host owns pseudoterminal bytes, retained terminal state, keyboard/text/mouse/IME encoding, frame scheduling, and presentation to the containing terminal. A1's JavaScript control plane may exchange typed identity, topology revision, capability, lifecycle, status, and recovery messages only; it must not relay terminal output, per-event child input, or rendered cells. A desktop-native window, GPU renderer, Ghostty GUI runtime, Winghostty Win32 runtime, Metal, GTK, and AppKit are postponed and are not required for the in-terminal product.
+The current JavaScript control plane does not provide arbitrary-CLI tabs. Such tabs require the separately bounded console terminal host to own PTYs, authoritative terminal state, rendering, input routing, inactive-surface lifecycle, and reconnection. JavaScript may exchange typed identity, topology revision, capability, lifecycle, status, and recovery messages only; it must not relay terminal output, per-event child input, or rendered cells.
 
-A tab owns a revisioned split tree. Each leaf pane references one PTY-backed terminal session. Structured/RPC agents remain semantically separate and may not derive state from ANSI text, terminal timing, or screen content. Native source ownership lives outside `src/` when introduced; packaged host selection is governed by release/package owners. Existing architecture tests reject terminal-host hot-path bytes in JavaScript protocol code, terminal inference in structured runtime code, composed imports from explicit launch modes, and replacement lightweight terminal parsers/renderers.
+Structured agents remain semantically separate and use typed events, commands, snapshots, cancellation, and recovery evidence. They must not derive state from ANSI text, terminal timing, or screen content. Native source ownership remains outside `src/`; packaged host selection is governed by release/package owners. Architecture tests reject terminal-host hot-path bytes in JavaScript protocols, terminal inference in structured runtimes, and replacement lightweight terminal parsers or renderers.

package/docs/architecture/resource-and-data-policy.md

@@ -46,7 +46,7 @@ Sanitization must classify before logging or storing. Unknown or untyped values
 
 - Structured/RPC semantics must not be inferred from ANSI text, terminal timing, or visual content.
 - Native-host protocol code must not carry PTY bytes, per-event child input, rendered cells, cell grids, framebuffers, or screen buffers.
-- `a1 pi` and `a1 sandbox` must not import, initialize, launch, or connect to composed terminal-host infrastructure.
+- `a1 pi` must not import, initialize, launch, or connect to composed terminal-host infrastructure.
 - Transparent direct attachment must remain independent of composed infrastructure and must not relay terminal data.
 - Recovery records store identity and bounded references, not terminal streams, authentication material, or arbitrary environment values.
 - A failed in-terminal 2×2 proof cannot be waived to merge composed infrastructure.

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,11 @@ 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.
+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.
 
 ## 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` explicitly requests stable publication after its version pull request merges. 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 +81,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` |
+| 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` |
 | Database | `A1_DATABASE_PATH` | `<data>/control.sqlite3` | `<data>/control.sqlite3` |
 | Endpoint | `A1_ENDPOINT` | runtime-scoped `a1-*` named pipe | `<runtime>/supervisor.sock` |
 
@@ -91,8 +91,8 @@ 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`.

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

@@ -19,30 +19,61 @@ 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, and distinct floating scalar menus are reviewed owned interactions. |
 
 ## Ported from the pinned engine
 
 | A1 module | Pinned Pi source | Adaptation |
 | --- | --- | --- |
+| `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 `pi-session-ui/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/integrations/pi/session-ui/session-shell.test.ts`; terminal-cell geometry remains a separate milestone. |
 | `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. |
+| `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, selected label/value 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 A1/Agent grouping, pointer steppers, explicit `/` search, ruled shared input, shortcut-derived status hints, suppressed selected descriptions, `scrollbarSpeed`-driven wheel movement, 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. |
+| `pi-session-ui/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.
+- **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
+  `pi-session-ui/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