@timurproko/a1 0.1.0 → 0.1.1-dev.10

package/docs/architecture/boundaries.md

@@ -1,37 +1,43 @@
 # Architecture boundaries
 
-## Terminal ownership
+## Terminal and launch-instance ownership
 
-The current interactive path is:
+Every interactive command uses this profile-neutral lifecycle path:
 
 ```text
 mutable a1 entry
   -> verified immutable release
-  -> foreground lease and broker
-  -> child with inherited physical terminal handles
+  -> 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
 ```
 
-After handoff, AddOne does not read ordinary terminal input, parse child output, render cells, infer frames, synthesize terminal responses, or emit display control. The child and physical terminal own terminal behavior. AddOne owns validated launch intent, one exclusive foreground lease, native process identity, lifecycle outcome, and bounded cleanup.
+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.
 
-Transparent mode has no AddOne-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.
+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.
+
+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.
 
 ## Current module responsibilities
 
-- `domain`: dependency-free transparent launch, process identity, lifecycle, and lease contracts.
+- `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.
 - `workspace-contracts`: dependency-free multi-agent identity, capability, command/event/snapshot, terminal window/tab/pane/session topology, terminal-host, and recovery contracts.
 - `structured-agent-runtime`: planned typed event/command/snapshot runtime. It must not infer semantics from terminal text, own pseudoterminals, or reconstruct screens.
 - `native-host-protocol`: bounded typed local boundary for terminal-host identity, topology revisions, lifecycle, and recovery. Terminal bytes, per-event child input, and rendered cells are forbidden across it.
-- `protocol`: additive control handshake, bounded line framing, request identity, snapshots, command results, and foreground-lease messages. Terminal bytes and reconstructed display state are forbidden.
-- `storage`: SQLite migrations, old-generation reconciliation, and exclusive foreground-lease persistence. Historical schema tables remain readable for installed-state compatibility but do not authorize legacy product behavior.
-- `supervisor`: endpoint identity, cohort ownership, foreground leases, and release shutdown coordination. It owns no terminal surface.
-- `transparent`: generic command resolution, foreground broker, and native attached launchers.
-- release/update/bootstrap: package-derived immutable release identity, cohort selection, durable update transactions, rollback, and dependency-light command entry.
+- `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.
+- 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 repository has no production 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 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.
 
 `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.
 
@@ -39,8 +45,20 @@ The repository has no production PTY or terminal-emulator dependency. Reintroduc
 
 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.
 
+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.
+
 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 2×2 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 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.
 
 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.
+
+## The rules every surface follows
+
+How A1 builds what a reader sees — deriving a vendor engine's data rather than
+transcribing it, failing the build by name when a vendor change has not been
+absorbed, keeping vendor knowledge behind the vendor boundary, composing screens
+from shared components, showing state rather than narrating it, taking colour
+from declared theme roles, and answering both dispatch and description from one
+declaration — is stated once in the `owned-ux-architecture` capability rather
+than restated per feature.

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

@@ -0,0 +1,26 @@
+# Process guardian provenance
+
+A1 launch-instance containment uses a standalone native executable named `process-guardian`. The approved implementation is a separate Rust crate at `native/process-guardian`; it is not a Node-API addon and does not reuse or resume the held composed terminal-host implementation.
+
+## Boundary
+
+The executable owns platform process containment and launches one immutable `a1-ui` runtime with inherited terminal handles. It does not create a PTY, read ordinary terminal input, capture or parse runtime output, render, or relay terminal bytes. Its private parent/child coordination is restricted to bounded lifecycle and identity data.
+
+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.
+
+## Artifact contract
+
+Release builds place the exact executable at:
+
+```text
+dist/native/win32-x64/process-guardian.exe
+dist/native/linux-x64/process-guardian
+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.
+
+## Licensing
+
+The guardian is A1-owned MIT-licensed source. Its Windows API binding is `windows-sys`, dual-licensed MIT or Apache-2.0 by its upstream project. Exact transitive notices are generated from the locked release dependency graph.

package/docs/architecture/project-structure.md

@@ -74,8 +74,8 @@ Build output belongs in ignored `dist/`; release/test evidence belongs in ignore
 
 ## Terminal capability boundary
 
-Transparent terminal attachment owns one foreground child and no AddOne surface. It cannot retain inactive terminal state or switch among arbitrary interactive CLIs inside AddOne. 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.
+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.
 
-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. AddOne'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.
+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.
 
 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.

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

@@ -32,7 +32,7 @@ Every asynchronous consumer must implement a finite queue or window. Backpressur
 |---|---|---|
 | Workspace metadata | IDs, names, lifecycle, capability versions, topology revisions, recovery references | May persist in the control store |
 | Structured payloads | Messages, tool calls, snapshots, attachments | Bound and process; persist only under a future typed retention policy |
-| Terminal content | PTY bytes, scrollback, selection, rendered cells | Never persist in AddOne's control store or diagnostics |
+| Terminal content | PTY bytes, scrollback, selection, rendered cells | Never persist in A1's control store or diagnostics |
 | Host topology metadata | Window/tab/pane/session IDs, layout shape, dimensions, revision | May persist; not terminal content |
 | Native proof evidence | Artifact hashes, source revisions, workloads, latency/resource measurements, paint diagnostics | May persist in versioned evidence files without terminal content |
 | Environment values | `PATH`, profile overrides, arbitrary launch environment | Do not persist; treat as potentially sensitive |

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

@@ -1,6 +1,6 @@
 # In-terminal 2×2 proof gate
 
-The composed-terminal proof is a stop/go gate. AddOne must not merge or productize composed terminal panes until the exact in-terminal spike artifact passes both technical and physical acceptance.
+The composed-terminal proof is a stop/go gate. A1 must not merge or productize composed terminal panes until the exact in-terminal spike artifact passes both technical and physical acceptance.
 
 ## Go criteria
 
@@ -8,7 +8,7 @@ A `go` decision requires all of the following:
 
 1. Every mandatory workload in the terminal-host evidence schema passes.
 2. The proof runs inside an existing terminal without creating a desktop window.
-3. The exact artifact is tied to pinned AddOne and terminal-component revisions.
+3. The exact artifact is tied to pinned A1 and terminal-component revisions.
 4. Automated evidence came from an isolated worker.
 5. The physical verdict is `accepted` through user-controlled manual validation or an attested isolated disposable worker.
 6. Input-to-process p95 latency is at most 16 ms.

package/docs/architecture/terminal-host-provenance.md

@@ -10,7 +10,7 @@ The composed-terminal proof uses a small console-hosted stack. It runs inside th
 | `portable-pty` | version `0.9.0` | ConPTY/Unix PTY and process ownership | MIT |
 | Crossterm | version `0.29.0` | Outer-terminal raw mode and host input events | MIT-compatible candidate; notice must be vendored before packaging |
 
-A buffered AddOne-owned frame composer is the initial presentation layer. Ratatui is an optional evaluation candidate only if the narrow composer increases rendering risk; it is not selected by default.
+A buffered A1-owned frame composer is the initial presentation layer. Ratatui is an optional evaluation candidate only if the narrow composer increases rendering risk; it is not selected by default.
 
 ## Explicitly excluded
 
@@ -44,7 +44,7 @@ Do not patch terminal semantics to support a specific CLI. Report unsupported ge
 
 The console proof requires:
 
-- Rust/Cargo for the AddOne terminal host;
+- Rust/Cargo for the A1 terminal host;
 - Zig `0.15.x` with patch `>= 0.15.2` to build `libghostty-vt`;
 - the platform C/C++ build toolchain required by Rust and the PTY/input crates (Visual Studio 2022 Build Tools/MSVC on Windows);
 - Windows 10/11 x64 or ARM64 for the first proof;
@@ -58,7 +58,7 @@ No GUI SDK, OpenGL runtime, Win32 window pipeline, Metal, GTK, or AppKit runtime
 Every spike or production host artifact must record:
 
 - artifact path, SHA-256, size, signature status, and build timestamp;
-- AddOne source commit and protocol version;
+- A1 source commit and protocol version;
 - `libghostty-vt`, PTY, input, and renderer component identities;
 - retained/adapted component manifest;
 - compiler/toolchain versions and target triple;

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

@@ -1,6 +1,6 @@
 # In-terminal 2×2 spike evidence
 
-The spike must produce machine-readable evidence with schema `addone-native-host-spike-evidence-v1`. Evidence is valid only when it names the exact artifact, hashes, pinned source commits, isolated worker environment, all mandatory workloads, measurements, paint diagnostics, resources, and physical/manual verdict. The artifact is a console terminal host that runs inside an existing terminal and does not open a desktop window.
+The spike must produce machine-readable evidence with schema `a1-native-host-spike-evidence-v1`. Evidence is valid only when it names the exact artifact, hashes, pinned source commits, isolated worker environment, all mandatory workloads, measurements, paint diagnostics, resources, and physical/manual verdict. The artifact is a console terminal host that runs inside an existing terminal and does not open a desktop window.
 
 ## Mandatory workloads
 

package/docs/architecture/toolchain.md

@@ -32,6 +32,12 @@ The published package contains:
 
 It contains no PTY, terminal emulator, browser/desktop GUI, custom renderer, input translator, physical automation driver, or generated runtime data.
 
+## Native launch containment
+
+Source builds require Rust/Cargo 1.85 or newer. `npm run build` compiles the standalone `native/process-guardian` crate for the host platform, places it under `dist/native/<platform>-<architecture>/`, and writes an integrity manifest. Preview and stable candidate workflows build platform artifacts on isolated Windows, Linux, and macOS runners and assemble them before packing. macOS remains explicitly unsupported until its exact containment adapter is certified; the package must fail before runtime startup rather than use PID-only cleanup.
+
+The process guardian inherits terminal handles but transports no terminal bytes. See [`process-guardian-provenance.md`](process-guardian-provenance.md).
+
 ## Gates
 
 ```sh
@@ -45,22 +51,48 @@ 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/`.
 
+## Pi maintenance workflows
+
+Engine compatibility and presentation synchronization are intentionally separate:
+
+```sh
+npm run test:pi-engine-conformance
+```
+
+This mandatory candidate workflow checks documented package-root exports and the owned engine integration. It does not read private interactive source, compare source maps, regenerate UI fixtures, or require presentation provenance to match a candidate package.
+
+```sh
+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.
+
 ## Preview publication
 
 A preview candidate must use a unique `-dev.N` version and exact manually accepted bytes. Publication packs once, binds evidence to source commit/version/integrity, runs applicable non-desktop gates, publishes under npm `next`, and verifies registry identity. It must keep `latest` unchanged and record physical/cross-platform certification as deferred.
 
-The GitHub trusted-publishing workflow is `.github/workflows/publish-next.yml`. Stable publication remains a separate release process from a clean tagged `master` commit after all mandatory platform gates pass.
+The GitHub trusted-publishing workflow is `.github/workflows/npm-publish.yml`. Stable publication remains a separate release process from a clean tagged `master` commit after all mandatory platform gates pass.
 
-## AddOne state paths
+## A1 state paths
 
-These paths are AddOne control and release state, not Pi profile roots. All are overrideable for hermetic tests.
+These paths are A1 control and release state, not Pi profile roots. All are overrideable for hermetic tests.
 
 | Purpose | Override | Windows default | Unix default |
 |---|---|---|---|
-| Config | `ADDONE_CONFIG_DIR` | `%APPDATA%\\AddOne` | `$XDG_CONFIG_HOME/addone` or `~/.config/addone` |
-| Durable data | `ADDONE_DATA_DIR` | `%LOCALAPPDATA%\\AddOne` | `$XDG_DATA_HOME/addone` or `~/.local/share/addone` |
-| Runtime | `ADDONE_RUNTIME_DIR` | `%LOCALAPPDATA%\\AddOne\\runtime` | `$XDG_RUNTIME_DIR/addone` or `<data>/runtime` |
-| Database | `ADDONE_DATABASE_PATH` | `<data>/control.sqlite3` | `<data>/control.sqlite3` |
-| Endpoint | `ADDONE_ENDPOINT` | runtime-scoped named pipe | `<runtime>/supervisor.sock` |
+| 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` |
+
+### Identity hard cut and cleanup
+
+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.
+
+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`.

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

@@ -0,0 +1,50 @@
+# A1 UI reference provenance
+
+The A1 UI component layer is ported from an existing A1-authored reference implementation
+rather than reinvented. Rebuilding a screen from screenshots reproduces its shape but not its
+decisions, and the decisions are where the work is: column arithmetic, sticky-header
+reservation, block-jump targets, span overlay under styling, and pointer hit regions.
+
+This file records what came from where, so a divergence can be judged against its source
+instead of argued from memory. It is the same discipline as
+[`terminal-host-provenance.md`](terminal-host-provenance.md), applied to UI source.
+
+## Source
+
+A1 UI reference implementation, local working copy. The reference is a Pi extension built on
+its own `core` facade layer; A1 is a product, so the port adapts imports and keeps behavior.
+
+## Ported units
+
+| 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/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/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. |
+
+## 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. |
+
+## 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.
+- **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.
+
+## Keeping this honest
+
+When a ported unit is changed, either change it to match the reference or record here why it
+diverges. An undocumented divergence is the thing this file exists to prevent.

package/docs/ci-release-runbook.md

@@ -0,0 +1,67 @@
+# CI and release operations
+
+GitHub Actions is the only automation platform. Two required checks protect the branches:
+
+| Branch | Required check | Produced by |
+| --- | --- | --- |
+| `develop` | `Development validation required` | `.github/workflows/ci.yml` |
+| `master` | `Stable candidate required` | `.github/workflows/certify-stable.yml` |
+
+These are job display names. If you rename one, update the ruleset definition, this runbook, and the live ruleset together.
+
+## How much validation runs when
+
+| Change | Validation |
+| --- | --- |
+| Docs or specs only | OpenSpec strict lint, nothing else |
+| Any code PR into `develop` | Fast tier: typecheck, architecture checks, unit/contract tests |
+| Preview candidate (`next`) | Fast tier + package gates: content, clean install, dependency policy |
+| Stable candidate (`latest`) | Complete suite on Windows, Linux, and macOS + physical evidence |
+
+Need more coverage for a risky preview? Dispatch the candidate with `full: true`, or run the **Full regression** workflow on demand.
+
+## Publish a preview to npm `next`
+
+One command from a clean `develop` checkout runs the whole chain — candidate build, publish, registry verification:
+
+```sh
+npm run release:next
+```
+
+It dispatches the same trusted workflows below and never publishes local bytes. The manual steps remain the reference path:
+
+1. Make sure `Development validation required` is green on the `develop` tip.
+2. Dispatch **Build npm next candidate** with the exact commit and `confirm_candidate=build-uncertified-next-candidate`.
+3. Check the resulting `candidate-evidence.json`: gates passed, package integrity matches.
+4. Approve the `npm-publish` environment and dispatch **Publish npm next** with the candidate run id.
+
+The publisher uploads the exact validated tarball — it never rebuilds. Candidates expire after 14 days; an expired or mismatched artifact means building a new candidate, not patching the old one.
+
+## Publish a stable release to npm `latest`
+
+1. Commit the final version to `develop` (clean tree, version not yet on the registry).
+2. Dispatch **Build stable candidate** — it packs once and validates the same bytes on all three platforms.
+3. Dispatch **Certify stable physical platforms** on the dedicated isolated workers (they set `PHYSICAL_WORKER_ISOLATED=true` and run under the `stable-physical` environment). Never run physical host probes on a developer workstation.
+4. Dispatch **Certify stable candidate** with both run ids. `Stable candidate required` passes only when every verdict binds the same commit, version, and digest.
+5. Merge that exact commit to `master`, tag it `v<version>`, and dispatch **Publish npm stable**, then approve `npm-publish`.
+
+Stable artifacts expire after 30 days. The same rule as previews applies: publication still requires exact certified bytes. Never upload locally rebuilt bytes, and never route around certification by rebuilding inside a publisher.
+
+## When something fails
+
+- **PR validation fails:** fix the code and push. Do not mark a failed tier optional.
+- **Candidate validation fails:** discard the candidate and build a new one after the fix.
+- **Physical worker fails:** fix or replace the worker, then rerun the full physical evidence for the candidate.
+- **Publisher fails before npm accepted the bytes:** diagnose and retry with the same candidate while it is unexpired and the version is still unpublished.
+- **Publisher is uncertain after npm accepted the bytes:** stop. Check the registry for the version, tag, and digest. Repair a dist-tag only as a separate reviewed operation — never republish.
+
+## Why the rulesets look the way they do
+
+One person maintains this repository, and GitHub does not let a PR author approve their own PR. Requiring even one approval would therefore deadlock the authorized solo-maintainer path — no PR could ever merge. So both rulesets require a pull request, a green required check, and resolved review threads, but set required approving reviews to zero.
+
+- `develop` does not require the branch to be up to date: once a PR is approved and green, it merges even if unrelated work landed first — no re-validation loop.
+- `master` does require it: a stable promotion always validates the exact final state.
+
+If a second maintainer joins, raise the approval count. Do not add a direct-push bypass as a shortcut, and never weaken the force-push or deletion protection.
+
+Ruleset mutation is a separate administrative operation: run `node scripts/check-github-rulesets.mjs` to see the diff, and apply only when a maintainer explicitly confirms with `--apply --confirm apply-a1-ci-rulesets`.

package/docs/features/launch-profiles.md

@@ -4,7 +4,7 @@
 
 | Command | Purpose | Pi user profile |
 |---|---|---|
-| `a1` | AddOne-owned Pi-compatible UI | `~/.a1/agent` |
+| `a1` | A1-owned Pi-compatible UI | `~/.a1/agent` |
 | `a1 pi` | Untouched vanilla Pi fallback and comparison oracle | ordinary `~/.pi/agent` |
 | `a1 sandbox` | Unchanged isolated vanilla Pi profile for experiments | `~/.a1/sandbox` |
 
@@ -12,7 +12,7 @@ There is no `a1 agent` command. The former `a1 ui` subcommand is removed. Bare `
 
 ## First launch
 
-For AddOne-owned profiles, AddOne creates only the selected profile root and empty `extensions`, `skills`, `prompts`, and `themes` directories. Existing content is preserved. AddOne does not copy, link, merge, or delete settings, credentials, sessions, packages, trust decisions, or resources from another profile.
+For A1-owned profiles, A1 creates only the selected profile root and empty `extensions`, `skills`, `prompts`, and `themes` directories. Existing content is preserved. A1 does not copy, link, merge, or delete settings, credentials, sessions, packages, trust decisions, or resources from another profile.
 
 Pi owns files within the selected root. Common locations are:
 
@@ -31,7 +31,7 @@ Run Pi’s normal `/login` independently in each profile that needs stored authe
 
 ## Vanilla Pi
 
-`a1 pi` bypasses the AddOne-owned UI and launches the untouched pinned Pi CLI. It also removes AddOne’s Pi configuration-root override, so Pi uses its normal `~/.pi/agent` settings, authentication, sessions, resources, packages, and trust decisions. This is both the comparison oracle and the recovery fallback when diagnosing the owned UI.
+`a1 pi` bypasses the A1-owned UI and launches the untouched pinned Pi CLI. It also removes A1’s Pi configuration-root override, so Pi uses its normal `~/.pi/agent` settings, authentication, sessions, resources, packages, and trust decisions. This is both the comparison oracle and the recovery fallback when diagnosing the owned UI.
 
 ## Sandbox profile
 
@@ -41,10 +41,16 @@ Run Pi’s normal `/login` independently in each profile that needs stored authe
 
 ## Terminal behavior
 
-Bare `a1` runs the AddOne-owned full-viewport TUI over public Pi engine, component, and terminal APIs. AddOne owns composition, input routing, modal focus, selection behavior, scrolling, and restoration without inserting a PTY or terminal-byte relay. Its default presentation is pinned to vanilla Pi parity; structured tabs and AddOne-specific visual customization are not enabled.
+Bare `a1` runs the A1-owned full-viewport TUI over public Pi engine, component, and terminal APIs. A1 owns composition, input routing, modal focus, selection behavior, scrolling, and restoration without inserting a PTY or terminal-byte relay. Its default presentation is pinned to vanilla Pi parity; structured tabs and A1-specific visual customization are not enabled.
 
-`a1 pi` and `a1 sandbox` retain transparent direct attachment. In those profiles, one untouched Pi process and the physical terminal own rendering, input, selection, clipboard, scrollback, and terminal modes; AddOne owns foreground lease and lifecycle only.
+`a1 pi` and `a1 sandbox` retain transparent direct attachment. In those profiles, untouched Pi and the physical terminal own rendering, input, selection, clipboard, scrollback, and terminal modes; A1 owns only per-invocation process containment and lifecycle evidence.
+
+## Concurrent instance lifecycle
+
+Every `a1`, `a1 pi`, and `a1 sandbox` invocation receives a unique non-detachable launch instance. There is no product-wide foreground slot: the same profile or any mixture of profiles may run concurrently in separate terminals. Profile files remain shared according to the selected profile root, while process ownership, lifecycle outcome, and cleanup remain scoped to the command that launched them.
+
+Normal root exit, terminal closure, guardian failure, and verified update shutdown all close the instance's remaining process tree within bounded graceful and forced deadlines. Closing one instance never closes another. A control supervisor may remain idle afterward, but closed instances leave no UI, Pi, extension daemon, agent worker, tool, or descendant process. Ordinary recovery never asks users to kill a PID or delete the control database.
 
 ## Recovery and comparison
 
-If bare `a1` cannot start or a UI workflow diverges, run `a1 pi` from the same working directory and compare the behavior. Profile data is intentionally separate, so authentication or settings may need to be configured independently. Use `a1 version` to record the installed AddOne release before reporting a difference. `a1 sandbox` is for isolated profile experiments, not recovery from the owned UI and not a security boundary.
+If bare `a1` cannot start or a UI workflow diverges, run `a1 pi` from the same working directory and compare the behavior. Profile data is intentionally separate, so authentication or settings may need to be configured independently. Use `a1 version` to record the installed A1 release before reporting a difference. `a1 sandbox` is for isolated profile experiments, not recovery from the owned UI and not a security boundary.

package/docs/manual-launch-instance-acceptance.md

@@ -0,0 +1,66 @@
+# Launch-instance exact-artifact acceptance
+
+Run this checklist only against a packaged candidate on a user-controlled terminal or isolated disposable Windows worker. Do not automate launching, focusing, driving, or closing terminal windows on an active workstation.
+
+## Artifact identity
+
+Record before testing:
+
+```text
+A1 release ID:
+A1 package version:
+Source commit:
+Candidate tarball SHA-256/integrity:
+Process guardian target: win32-x64
+Process guardian crate version:
+Process guardian protocol version:
+Process guardian SHA-256:
+Process guardian signature/attestation status:
+Machine/Windows/terminal versions:
+Tester or worker attestation:
+```
+
+The process guardian values must match `dist/native/win32-x64/manifest.json` inside the exact installed candidate. Stop if the file is missing, mismatched, altered, or reports an unsupported capability.
+
+## Concurrent launch matrix
+
+Open four independent terminal tabs and launch:
+
+```text
+Terminal 1: a1
+Terminal 2: a1
+Terminal 3: a1 pi
+Terminal 4: a1 sandbox
+```
+
+Confirm all four become usable without a global foreground-lease error. Record each launch-instance ID from supervisor metadata and verify all four IDs are distinct.
+
+## Isolated closure
+
+1. Exit Terminal 3 normally. Confirm only its vanilla Pi tree exits; Terminals 1, 2, and 4 remain usable.
+2. Close the Terminal 4 tab/window without exiting Pi first. Confirm its sandbox Pi, extension daemons, agent workers, tools, and descendants disappear within the bounded deadline while both bare-A1 terminals remain usable.
+3. Exit Terminal 1 normally after causing a fixture extension to create a child and grandchild. Confirm the complete tree disappears and Terminal 2 remains usable.
+4. Force the Terminal 2 launch guardian to fail on the isolated worker. Confirm Job Object kill-on-close removes its root and descendants and leaves unrelated fixture processes alive.
+
+Record root, child, and grandchild native identities before each close and the observed terminal outcome afterward. Do not substitute manual PID termination for a failed cleanup.
+
+## Stale-state recovery
+
+Using isolated control directories, install a version-4 fixture database containing one requested or active legacy foreground lease whose former PID is dead. Run `a1 sandbox` once. Confirm that the same invocation migrates the row to historical interrupted state and launches normally without restarting the supervisor, deleting state, or discovering a PID.
+
+Repeat with an ownership-uncertain fixture process. Confirm a new independent launch still starts and the uncertain unrelated process is not terminated.
+
+## Update fan-out
+
+With at least three mixed-profile instances active, run the candidate's update-shutdown fixture. Confirm every instance receives one stop intent, each complete process tree closes, and cohort replacement occurs only after all verified terminal outcomes. A delayed or uncertain instance must prevent unsafe replacement without causing another instance to be reported idle prematurely.
+
+## Verdict
+
+Record one of:
+
+```text
+ACCEPTED — exact package and guardian digests above passed every scenario
+REJECTED — include failed step, observed process identities, outcomes, and diagnostics
+```
+
+Acceptance applies only to the exact package and process-guardian bytes recorded above. It does not certify macOS, Linux, composed terminals, detached agents, or an operating-system security sandbox.

package/docs/manual-pi-boundary-candidate.md

@@ -0,0 +1,33 @@
+# Manual Pi-boundary candidate checkpoint
+
+This checkpoint is user-controlled. Do not automate it on an active workstation, send synthetic desktop input, or claim a pass without a person completing the observations.
+
+## Prepare the exact local candidate
+
+From a clean checkout of the candidate commit:
+
+```powershell
+npm ci
+npm run check
+npm pack --ignore-scripts --pack-destination artifacts/manual-pi-boundary
+npm install --global --prefix artifacts/manual-pi-boundary/install artifacts/manual-pi-boundary/timurproko-a1-*.tgz --ignore-scripts
+$Candidate = Resolve-Path artifacts/manual-pi-boundary/install/a1.cmd
+```
+
+Use the exact generated filename if wildcard expansion is unavailable.
+
+## User-controlled checks
+
+1. **Bare owned UI:** run `& $Candidate`. Confirm startup, typing, submission, transcript streaming, selector focus, mouse/keyboard scrolling, and ordinary shutdown.
+2. **Extension surfaces:** in bare UI use `/reload`, then exercise configured extension notification, select, confirm, input, editor, replacement custom surface, and overlay custom surface. Confirm cancellation restores editor focus.
+3. **Vanilla oracle:** run `& $Candidate pi`. Confirm untouched Pi uses the ordinary `~/.pi/agent` profile and does not show owned-UI or workspace surfaces.
+4. **Isolated profile:** run `& $Candidate sandbox`. Confirm Pi uses `~/.a1/sandbox` and starts with project approval disabled for that run.
+5. **Resize and input:** while each mode is active, narrow and widen the terminal, enter Unicode and multiline text, use history/navigation keys, and scroll in both directions.
+6. **Shutdown:** exit normally, then repeat and use Ctrl+C during work. Confirm the parent prompt remains usable and no child remains attached.
+7. **Recovery:** after any owned-UI failure, run `& $Candidate pi`; confirm the vanilla oracle remains available. Restart bare UI and confirm its normal profile remains intact.
+
+Do not remove `~/.a1/agent`, `~/.pi/agent`, or `~/.a1/sandbox` during this checkpoint.
+
+## Verdict recording
+
+Before a person performs these commands, the verdict is **READY, MANUAL EXECUTION PENDING**. After execution, record candidate commit, tarball SHA-256, platform, terminal, each observation, and an explicit pass/fail. A preview publication may remain Windows-only and uncertified; this checkpoint does not establish stable cross-platform support.

package/docs/manual-terminal-colour-check.md

@@ -0,0 +1,55 @@
+# Terminal colour check
+
+## What can go wrong
+
+Every colour the interface draws is 24-bit: the pinned dark theme's accent is
+`#8abeb7`, its border `#5f87ff`, its headings `#f0c674`. On Windows, Node decides
+once at startup whether it may send those sequences to the terminal at all. It
+asks the console to enable virtual terminal processing; when that fails it renders
+ANSI itself, and its renderer knows only the sixteen SGR colours. Each 24-bit
+colour is then replaced by the terminal's nearest palette entry, so the whole
+interface shifts at once — accent to the terminal's cyan, headings to its yellow —
+while the application still writes exactly the bytes it always wrote.
+
+That decision is made per process, from the console handle the process was given,
+and every process it launches inherits the result. It is a property of how the
+session was started, not of what is drawn.
+
+## Launching so colour survives
+
+The installed command is an npm shim — a shell script that `exec`s Node — and that
+shape keeps 24-bit colour. So does `pi`, for the same reason.
+
+- Installed: `a1`, `a1 pi`
+- From a checkout: `scripts/dev` and `scripts/dev pi`
+
+`npm start` and `npm run start:pi` build first and then launch through the same
+entry, but a package manager on Windows hands the script to `cmd.exe`, which can
+leave the launch without a terminal on its input; the launcher says so and stops
+rather than opening a session that closes as it starts. Running `scripts/dev`
+from the shell is the direct path.
+
+A directly launched `node scripts/start-local.mjs` under Git Bash does not, and
+neither does a directly launched `node …/pi/dist/cli.js`: the collapse belongs to
+the launch, not to either application.
+
+## Checking a terminal
+
+```
+node scripts/check-terminal-colour.mjs
+```
+
+It prints the same colour as 24-bit, as a 256-colour index, and as the terminal's
+own palette entry. When the first block is indistinguishable from the third, this
+launch collapses colour and any comparison made in it is a comparison of two wrong
+screens.
+
+## What the gates hold
+
+- `test/features/launch/terminal-colour-fidelity.test.ts` holds the emitted bytes:
+  the pinned palette resolves to 24-bit sequences, a 256-colour terminal stays on
+  indices, and the launch chain keeps inheriting the terminal it was started from
+  rather than opening a console of its own.
+- The reader compares `a1 pi` with pinned Pi in the same terminal. Run the colour
+  check first: a launch that collapses colour makes both sessions equally wrong, so
+  they would agree with each other and disagree with what a user sees.