@timurproko/a1 0.1.8-dev.3b54f21 → 0.1.8-dev.407

package/dist/{src/foundation/owned-ui-settings → ui/settings}/store.d.ts

@@ -13,6 +13,7 @@ export interface OwnedUiSettingsWriteOutcome {
     /** Present when the write failed; the caller must not report the change as saved. */
     readonly failure: string | null;
 }
+/** Resolves and atomically persists one profile's owned settings without discarding unknown keys. */
 export declare class OwnedUiSettingsStore {
     #private;
     constructor(options: OwnedUiSettingsStoreOptions);

package/dist/{src/foundation/owned-ui-settings → ui/settings}/store.js

@@ -5,6 +5,7 @@ import { OWNED_UI_SETTINGS_MIGRATIONS } from "./migrations.js";
 import { documentFrom, parseOwnedUiSettingsDocument, resolveOwnedUiSettings, } from "./resolution.js";
 const PROFILE_ID_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
 const MAX_DOCUMENT_BYTES = 256 * 1024;
+/** Resolves and atomically persists one profile's owned settings without discarding unknown keys. */
 export class OwnedUiSettingsStore {
     #file;
     #declarations;
@@ -76,7 +77,7 @@ export class OwnedUiSettingsStore {
                 rmSync(temporary, { force: true });
             }
             catch {
-                // A leftover temporary file is inert: read() only ever opens the target path.
+                // Security: a leftover temporary file is inert: read() only ever opens the target path.
             }
             return { stored: false, failure: `${this.#file} could not be written: ${describe(error)}` };
         }

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
 
@@ -28,22 +28,26 @@ Transparent mode has no A1-authoritative terminal surface, internal pane, virtua
 - `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, authenticated launch-instance commands, typed stop intent, snapshots, and command results.
+- `launch`: resolves the effective profile home and the history-specific data root. Composition uses its public path resolver to select `~/.a1/data` for history unless `A1_DATA_DIR` is explicit; global control/release/runtime/cache paths stay unchanged.
+- `prompt-history`: narrowly typed user-input retention in separate profile-owned databases under `~/.a1/data/history` (or `<A1_DATA_DIR>/history`), with bounded worker queues and no supervisor/control-store payloads. It receives a resolved root rather than importing launch-feature internals; it never probes, imports, or deletes the former platform-default history. The editor's owned history state machine remains inside the Pi component boundary; the session UI only coordinates snapshots and classified submissions.
+- `prompt-suggestions`: opt-in bounded diagnostic snapshots of neutral suggestion lifecycle metadata. Composition supplies an explicit local destination; this feature never imports Pi, generates suggestions, stores conversation text, or owns the editor. See [prompt suggestion diagnostics](prompt-suggestions.md).
 - `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.
+- `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. After an unsuccessful bare-A1 child exit, the bootstrap restores owned terminal modes; neither guardian emits terminal controls.
+- `terminal-cleanup`: bounded, idempotent emergency restoration and fatal-exit diagnostics for an explicitly owned terminal. It does not inspect commands, relay terminal input/output, or emulate terminal state. The owned UI installs its fatal boundary before terminal activation; packaged bootstrap and checkout launch provide the surviving-owner fallback. Fatal records retain at most ten 16 KiB records with trusted classifications and code locations, never prompts, attachments, raw input, credentials, or arbitrary exception messages.
 
 ## Dependency direction
 
 Terminal boundaries are application-agnostic. They may not select behavior from executable names, arguments, CLI-specific environment variables, or visible text. Production code may not import private Pi distribution APIs or use a Pi-specific terminal workaround.
 
-The 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/history-editor-provenance.md

@@ -0,0 +1,100 @@
+# History editor source boundary
+
+The history-enabled default editor is derived from Pi 0.84.2 at commit
+`914cf1472e715297caa30db4b9535d534a9eb718`, repository
+<https://github.com/earendil-works/pi>. The approved scope is
+`openspec/changes/add-persistent-prompt-history/design.md`, decision 2a.
+
+## Source and import inventory
+
+The owning directory is `src/integrations/pi/components/upstream/history/`.
+
+| Owned unit | Upstream source under `packages/tui/src/` | Retained behavior |
+|---|---|---|
+| `editor-core.ts` | `components/editor.ts` | Editor state machine, layout, history boundaries, paste backing, autocomplete, undo integration |
+| `kill-ring.ts` | `kill-ring.ts` | Kill/yank accumulation and rotation |
+| `undo-stack.ts` | `undo-stack.ts` | Clone-on-push undo storage |
+| `word-navigation.ts` | `word-navigation.ts` | Word/atomic-segment navigation |
+| `text-helpers.ts` | selected declarations in `utils.ts` | Shared local segmenters, CJK break classification, punctuation/whitespace predicates only |
+| `printable-key.ts` | selected declarations in `keys.ts` | Pure modifyOtherKeys printable helper and modifier constants; delegates Kitty decoding to the public export |
+
+All reusable terminal APIs come from `#pi-tui`: keybinding state, `matchesKey`,
+`decodeKittyPrintable`, `CURSOR_MARKER`, width/slicing, `SelectList`, and public
+component/autocomplete types. No terminal runtime, parser stack, terminal
+renderer, package loader, or dependency copy is introduced. The terminal-package
+alias and exported constructors remain unchanged.
+
+`node scripts/pi/extract-history-editor-source.mjs` resolves the terminal package
+from pinned Pi's entry and extracts references and hashes into the ignored
+`.artifacts/history-editor-upstream/` directory. It never overwrites owned code.
+The source ledger records upstream and owned destination hashes. Source maps are
+used only by provenance tooling, not by the shipped runtime. Changed source must
+be explicitly reconciled, not automatically adopted in an engine upgrade.
+
+## Owned changes and collaborator boundaries
+
+The core uses public imports, a distinct `HistoryEditorCore` class, and strict
+TypeScript declaration adjustments. Persistent history is opt-in: its typed
+snapshot installation and observation methods preserve input and undo state,
+freeze an active browse cycle, and change caret placement only in that mode.
+The editor renders position/overflow in its existing border. The position label
+uses an injected neutral status-text style (`dim`), while the surrounding rules
+retain the active input-border color, as clarified during manual review. The approved
+`show-autocomplete-above-prompt` review refinement omits the literal `History` title:
+`─── 1/100 ─…` keeps the same four-cell inset, count calculation, dim color, optional
+scroll-overflow suffix, and clipping. Core and shell regressions verify numbering,
+100-entry recall, draft restoration, and the absence of the title. Recall temporarily
+separates the draft's live paste backing from recalled literal text, restoring it
+on return; ordinary pinned mode remains source-equivalent.
+
+The integration inventory is:
+
+- `shell-editor-autocomplete.ts`: choose the default editor through a typed
+  component interface, never cast the owned core to the concrete Pi editor.
+- `upstream/components/owned-editor.ts`: retain its pinned-based comparison and
+  disabled-history route; share app actions and owned prefix/suggestion behavior
+  through typed composition for the history-enabled route.
+- `owned-editor-ux.ts`: selection, atomic segmentation, visual-line geometry,
+  provisional paste completion, and undo repair need a typed owned collaborator
+  boundary. Existing compatibility access on the pinned route is not permission
+  for new private access on the owned core.
+- `shell-extension-ui.ts`: public text, shortcut, autocomplete, and factory
+  behavior remain extension-owned. A custom editor is not patched for recall.
+- `session-shell-root.ts` and `session-shell.ts`: deliver semantic snapshot and
+  submission events; they must not own a second history index, mutable draft,
+  undo stack, or rendered-border parser.
+
+`test/integrations/pi/components/history-editor-core.test.ts` independently runs
+real pinned and owned editors against the same input tapes, comparing rows,
+text/expanded text, cursor, autocomplete, and submissions. Separate fixtures
+cover v2 directional placement and numbering, deferred snapshots, draft/undo
+restoration, and literal paste-marker collisions. This is editor-core evidence,
+not acceptance of the complete persistent-history feature.
+
+## License
+
+Upstream license at the recorded commit:
+
+```text
+MIT License
+
+Copyright (c) 2025 Mario Zechner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

package/docs/architecture/internal-naming.md

@@ -0,0 +1,91 @@
+# Internal naming and private launch context
+
+Internal code names contain no case-insensitive `a1` substring. This includes constants, variables, parameters, functions, methods, classes, types, private fields, aliases, and quoted/constant-computed member names. Branding remains at supported external boundaries: the `a1` command, public package identity, user-visible text, user directories, public settings, and declared serialized fields.
+
+## Required PR validation
+
+The required **Internal naming validation** job scans complete added, modified, copied, and renamed-to files at the exact PR head against the complete merge-base diff. It does not inspect only changed lines. Policy, exception, ownership, parser-dependency, and selection changes require a full audit and inspector regression tests. A stale, missing, failed, or unexpectedly skipped required result blocks the aggregate development check.
+
+The nightly release workflow runs `full-release`, including `naming-full`, against the entire tracked codebase at its selected source commit. It does not use PR changed-file selection, including when it verifies an already-published immutable package. Naming failure fails platform validation and blocks publication. `naming-selection.test.ts` locks down this nightly wiring and checks that unchanged source is audited.
+
+- Full local audit: `npm run check:names` (tracked files, including staged new files).
+- Exact selected PR audit: `npm run check:names:changed` after producing `.artifacts/validation/impact.json`.
+- Evidence: `.artifacts/validation/naming.json`, uploaded as `development-naming-validation`.
+- Parser fixtures: `test/repository-governance/naming-inspection.test.ts`.
+- Git selection fixtures: `test/repository-governance/naming-selection.test.ts`.
+
+TypeScript/JavaScript and Python use syntax trees. Rust uses a token-aware scanner. Workflow environment maps, embedded Node scripts, JSON environment definitions, and supported shell assignments are inspected. Dependencies, immutable vendor files, generated output, and other worktrees are excluded; owned test helpers and locally adapted source ports are not. Unsupported owned inputs fail explicitly. Python inspection uses a bundled development-only grammar, not an installed Python interpreter.
+
+The exact externally branded key/member authority is `config/internal-naming-policy.json`. It records each setting's owner, evidence, exposure, and value semantics. Arbitrary uppercase properties are not public environment settings. No compatibility-alias exposure category is allowed. Test snippets and negative-test input data are not declarations or supported aliases.
+
+## Environment ownership inventory
+
+### Supported branded external settings
+
+| Keys | Producer / consumer and exposure |
+| --- | --- |
+| `A1_CONFIG_DIR`, `A1_DATA_DIR`, `A1_RUNTIME_DIR`, `A1_DATABASE_PATH`, `A1_ENDPOINT` | User/shell configuration consumed by `src/foundation/lifecycle/paths.ts`; documented public overrides, unchanged. |
+| `A1_PROFILE_HOME` | Caller-supplied profile-home override consumed by `src/features/launch/profile-paths.ts`; exact existing exposure-review entry. |
+| `A1_STARTUP_TRACE` | Caller-supplied diagnostic path and trace context in `src/foundation/startup/startup-runtime.ts`; exact existing exposure-review entry. |
+| `A1_DEV_INSTANCE_ID`, `A1_DEV_ROOT` | Caller-supplied development overrides consumed by `src/features/launch/development-launch.ts`; exact existing exposure-review entries. |
+| `A1_PROCESS_GUARDIAN_PATH` | Explicit executable override in `src/foundation/process-containment/native-guardian-containment.ts`, also configured by CI; exact existing exposure-review entry. |
+| `A1_PROBE_TRACE` | Opt-in diagnostics read by native terminal-host code; exact existing exposure-review entry. |
+| `A1_BUILD_VERBOSE`, `A1_DEV_SHELL` | Developer invocation controls in the build helper and development launcher; exact existing exposure-review entries. |
+| `A1_PANE_ID`, `A1_TERMINAL_SESSION_ID` | Produced by `native/terminal-host/src/workspace.rs` and exported to launched programs; external integration names, unchanged. |
+
+Pending review preserves a possible external interface, not an obsolete private alias. Once a setting is established as private, it cannot keep its branded spelling through that category.
+
+### Current private settings
+
+| Keys | Producer / consumer and value semantics |
+| --- | --- |
+| `LAUNCH_CONTEXT_RELEASE_ROOT`, `LAUNCH_CONTEXT_RELEASE_ID`, `LAUNCH_CONTEXT_RELEASE_DIGEST`, `LAUNCH_CONTEXT_RELEASE_LAYERS` | Release bootstrap writes the selected verified immutable identity; supervision, guardian, and startup/cache readers consume it. Layers are comma-separated and can be empty. |
+| `LAUNCH_CONTEXT_PROFILE` | Bootstrap or the development launcher writes the selected `a1`/`pi` profile; guardian and UI entries consume it. |
+| `LAUNCH_CONTEXT_WARMUP` | Release warmup writes exactly `1`; the private warmup entry requires it together with release context. |
+| `RELEASE_CLEANUP_HOLDS`, `RELEASE_CLEANUP_RUN_ID` | Cleanup scheduler/worker handoff in `src/foundation/release/release-gc.ts`; serialized holds and a worker run identity. |
+| `SOURCE_LEDGER_PATH`, `SOURCE_LEDGER_SCAN_ROOT`, `SOURCE_LEDGER_PORT_ROOT` | Source-ledger governance fixture overrides; produced by its tests and consumed by `check-pinned-pi-source-ledger.mjs`. |
+| `RELEASE_RUNNER_LABEL` | Release/full-regression workflows supply certification-runner provenance to `run-release-gates.mjs`. |
+| `TERMINAL_FIXTURE_INPUT`, `TERMINAL_FIXTURE_TOKEN` | Native terminal probe producer/consumer in `native/terminal-host/src/main.rs`; expected input and fixture token. |
+| `DOCS_AUTO_MERGE_POLL_ATTEMPTS`, `DOCS_AUTO_MERGE_POLL_MS` | Documentation automation polling controls, produced by governance tests and consumed by `manage-documentation-auto-merge.mjs`. |
+| `VALIDATION_JOB_STARTED_MS`, `RENDERING_JOB_STARTED_MS` | CI timing handoffs within `.github/workflows/ci.yml`; epoch milliseconds. |
+| `RUN_PROCESS_CONTAINMENT_INTEGRATION` | CI enables the real containment fixture with exactly `1`; platform containment tests consume it. |
+| `PACKAGE_MESSAGE_SCENARIO` | Package-message worker parent/child JSON scenario handoff. |
+| `RECOVERY_TEST_CANCEL_AFTER`, `RECOVERY_TEST_REMOVAL_MARKER` | Recovery test parent/fake-npm handoff; mutation index and disposable sentinel path. |
+
+The private launch contract is `neutral-launch-v1`, declared by the package's `privateLaunchContract` metadata and bound into immutable release identity. It is validated before activation or execution. There is one reader/writer and no mapping from obsolete private names.
+
+### Existing neutral automation and third-party boundaries
+
+These names are already neutral; their definitions and consumers remain the authority for their existing behavior:
+
+- Development aggregate: `CHANGES_RESULT`, `DOCS_RESULT`, `DOCUMENTATION_RESULT`, `DOCUMENTATION_REQUIRED`, `VALIDATE_RESULT`, `CONTAINMENT_RESULT`, `STARTUP_RESULT`, `RENDERING_RESULT`, `RENDERING_TIER`, `DOCS_ONLY`, `VERSION_ONLY`, `OPENSPEC_TOUCHED`, `SELECTED_HEAD`, `EXPECTED_HEAD`, `EVENT_BASE_SHA`, `EVENT_HEAD_SHA`. The workflow produces these and `require-development-validation.mjs` or the selector consumes them.
+- Naming aggregate: `NAMING_RESULT`, `NAMING_REQUIRED`, `NAMING_HEAD`, produced by CI and consumed by the same required aggregate.
+- Validation: `VALIDATION_BUILD_READY`, `VALIDATION_CANDIDATE_TARBALL`, `VALIDATION_DOCUMENTATION_FULL_READY`, `VALIDATION_SELECTION_JSON`, `STARTUP_PERFORMANCE_RESULT`, owned by validation orchestration and exact-package fixtures.
+- Publication workflow-local handoffs: `BUILD`, `EVENT_NAME`, `EXISTS`, `EXPECTED_INTEGRITY`, `EXPECTED_REGISTRY_INTEGRITY`, `EXPECTED_REGISTRY_SHASUM`, `EXPECTED_SHASUM`, `MODE`, `PACKAGE`, `PLAN`, `PUBLISH`, `PULLS_PATH`, `PULL_REQUEST`, `REGISTRY_TARBALL`, `RELEASE_CHANNEL`, `RELEASE_VERSION`, `REQUESTED_CHANNEL`, `REQUESTED_SHA`, `SOURCE_SHA`, `VALIDATE`, `VERSION`, `WORK`, defined and consumed in `.github/workflows/release.yml`.
+- Isolated fixture controls: `PROMPT_SUGGESTION_AGENT_DIR`, `RUN_PROMPT_SUGGESTION_PROVIDER_TEST`, `TEST_SUPERVISOR_SECRET`, owned by their specific provider/supervisor tests.
+- Host/tool integration: `CARGO`, `ZIG`, `PATH`, `HOME`, `USERPROFILE`, `APPDATA`, `LOCALAPPDATA`, XDG directory variables, `TERM`, `COLORTERM`, `TERM_PROGRAM`, `WT_SESSION`, `EXEPATH`, `MINGW_PREFIX`, `MSYSTEM`, and third-party `PI_*`, `GITHUB_*`, `GH_TOKEN`, and npm variables. Their external spellings and caller values are not private product naming targets. The forwarding of an arbitrary user's environment is distinct from defining an owned setting.
+
+### Removed or reclassified registry entries
+
+The old environment registry included `fixture` and `inputAcknowledgement`, but their values describe native probe stdout markers, not environment settings. Their existing external wire spellings stay in that protocol, not in the public environment registry.
+
+`certificationTarball`, `internalPackaging`, `nativePi`, `piParityIntentionalMutation`, `protocolVersion`, `structuredFlowLimits`, `terminalArgumentsJson`, and `terminalExecutable` had no active runtime consumer in the reviewed tree. They are removed from the current environment authority, not renamed into new settings. Rejection patterns and immutable historical evidence remain factual.
+
+## Negotiated handoff and protected state
+
+An update is performed by the release that is already installed, so the contract is negotiated rather than cut over. `neutral-launch-v1` is the only contract this build **writes** for its own releases, and the superseded `A1_RELEASE_*`/`A1_IMMUTABLE_WARMUP` keys are still **read** when an older launcher starts this build, and still **written** when this build starts a retained release that declares no contract. An installation therefore stays launchable across the cutover in both directions, and no user is asked to stop processes and reinstall by hand.
+
+Metadata that predates contract declaration is stale, never fatal. A pre-cutover active record does not stop a launch: it is ignored, the installed payload is materialized, and ordinary cohort selection activates it. A launch that cannot take the installed payload at all — an installation being replaced right now — starts the retained active release instead of failing, and leaves activation to the next launch. What still requires `neutral-launch-v1` outright is narrow and never blocks a launch: the installed package's own manifest must declare it, and an update recovery capsule is never translated.
+
+`test/foundation/release/update-predecessor.integration.test.ts` is the gate for this. It installs each of the most recent published releases and drives the candidate through **that release's own** materialization and warmup, because a fixture built from the candidate would only prove the candidate agrees with itself. No reset or migration runs automatically. If disposable state blocks installation, inspect its resolved paths and obtain separate approval before removal.
+
+| State | Treatment |
+| --- | --- |
+| `<configDir>` and its settings | Preserve. |
+| `~/.a1/agent`, credentials, extensions, and session files | Preserve. |
+| Prompt-history databases under the selected data/history owner | Preserve; this change does not relocate history. |
+| `<dataDir>/releases`, release references/certification records, `<dataDir>/update-recovery`, update journal | Disposable runtime/release candidates only; inspect exact paths and live ownership before any separately approved manual reset. |
+| `<runtimeDir>` endpoints, locks, and worker records | Reset candidates only after all affected processes stop and their precise scope is confirmed. |
+| The whole `<dataDir>` or `<configDir>` | Never delete as a shortcut: disposable and user data can share these roots. |
+
+`test/foundation/launch-context/cutover.test.ts` places protected settings/session/history sentinels next to incompatible runtime fixtures and verifies failed admission does not change them. No test or implementation command uses actual user data as its cleanup fixture.

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,53 @@
 # 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
+    prompt-history/                profile-isolated prompt retention and bounded SQLite worker lifecycle
+    prompt-suggestions/            opt-in bounded metadata capture and local diagnostic snapshots
+    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 +55,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 +68,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.