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

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 `@earendil-works/pi-tui` (one copy per process, chosen by the `bin/module-resolver.js` hook): 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,93 @@
+# 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.
+
+Activation after the global installation is handed over the same way. The package manifest declares `updateActivationContracts` (`activate-v1`) and ships `bin/activate.js`; an updater that serves a declared contract starts that entry with the data directory and the target version and relays its line-delimited progress events (`materializing`, `phase`, `warmup`, `completed`, `failed`) into its own journal and progress bar, while the entry materializes, certifies, warms, and supervises the tree it ships in with that tree's own code. The updater resolves nothing inside the installed tree but `package.json` and that entry; `test/repository-governance/update-activation-contract.test.ts` pins this. A tree that declares no contract the updater serves is activated in-process with the layout it had, which keeps an updater older than the contract and a downgrade to an older preview working.
+
+`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,52 @@
 # 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
+  app/
+    session-shell/                 the owned session shell: composes features, UI components, and the Pi adapters into the interactive session
   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
+  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
+  integrations/
+    pi/
+      components/                  pinned Pi component and theme adaptation
+      engine/                      pinned Pi engine, settings, resource, package, and workflow 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
+    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
+    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`, which lists its named exports; `export *` is rejected there so a public contract is readable in one place. 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`. Two exceptions exist: `src/composition` is the dependency-injection root and may reach past any public entry, and a module on the eager startup path may import a leaf of a provider whose public entry is a prohibited startup entry (`PROHIBITED_STARTUP_ENTRIES` in `startup-graph-policy.mjs`), because loading that barrel would pull the provider's whole graph into startup. `product-identity` is the sole 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.
+Three layer boundaries hold regardless of the DAG: `src/contracts/*` import nothing outside their own contract; `src/ui/components` imports only contracts; only `src/integrations/pi/*` and the shipped `bin/` entries import the pinned Pi packages. The session shell under `src/app` is the application layer: it may import the contracts, the UI foundations, the three Pi adapters, and the feature owners, and only composition imports it.
+
+`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 +54,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 +67,54 @@ Tests mirror their production owner:
 ```text
 test/
   cli/
+  composition/
   features/<name>/
+  contracts/<name>/
+  app/session-shell/
   foundation/<name>/
+  integrations/pi/<name>/
+  product-identity/
   repository-governance/
+  ui/<name>/
 ```
 
-Use `.test.ts` for deterministic owner-level contracts. Use `.integration.test.ts` when the contract crosses real process, filesystem, registry, or release boundaries. Prefer the smallest independent boundary that proves the observable result; do not duplicate a stronger test or preserve historical bug-story names after the cause has a current invariant.
+Use `.test.ts` for deterministic owner-level contracts. Use `.integration.test.ts` when the contract crosses real process, filesystem, registry, package, or release boundaries. A test of a foundation implementation belongs to that foundation owner's test root; a feature test may exercise the same public entry only when it proves feature-level composition.
 
-Physical desktop automation is not an ordinary integration test. It requires a separately authorized certification change and isolated disposable infrastructure.
+Prefer the smallest independent boundary that proves the observable result. Do not duplicate a stronger test or preserve historical bug-story names after the cause has a current invariant. Physical desktop automation is not an ordinary integration test; it requires separately authorized certification and isolated disposable infrastructure.
 
 ## Repository authority
 
 The repository has one root `package.json`, `package-lock.json`, TypeScript configuration, Vitest configuration, and dependency installation. Nested manifests, lockfiles, `node_modules`, vendored package caches, logs, sessions, browser profiles, generated output, and runtime state are forbidden under production and feature trees.
 
-Build output belongs in ignored `dist/`; release/test evidence belongs in ignored `artifacts/`. Package contents are selected by the root manifest. Native proof code lives under `native/terminal-host/`; its Cargo build output and vendored Zig build output are ignored, and it remains a console terminal host rather than a desktop application.
+Build output mirrors the production namespaces directly under ignored `dist/`, without an intermediate `src/` directory; release and test evidence belongs in ignored `.artifacts/`; temporary agent work belongs in ignored `.worktrees/` and `.builds/`. Repository tooling is grouped under `scripts/governance`, `scripts/release`, `scripts/pi`, and `scripts/development`; the few root scripts are standalone maintenance or build commands. Package contents are selected by the root manifest. The Rust process guardian and console terminal-host proof live under `native/`; Cargo output is ignored. Third-party terminal parser sources are isolated under `native/terminal-host/vendor/` and are not owned application modules.
+
+## Development worktrees
+
+Every task worktree must be created at `{working-dir}/.worktrees/<task-id>`, where `{working-dir}` is the agent session's initial working directory. The `.worktrees` directory is inside that working directory, not beside it. For working directory `D:/Git/a1`, `D:/Git/a1/.worktrees/<task-id>` is correct and `D:/Git/a1-<task-id>` is forbidden.
+
+From the initial working directory, create and address a task worktree explicitly:
+
+```sh
+git fetch origin develop
+git worktree add --detach .worktrees/<task-id> origin/develop
+git -C .worktrees/<task-id> status
+```
+
+The primary worktree stays on `develop` for integration and must not be used for task edits. Do not edit, move, or remove another session's worktree.
 
 ## Documentation and comments
 
 - README explains installation, commands, and current limitations.
 - `docs/architecture` explains cross-cutting ownership and irreversible constraints.
-- `docs/architecture/resource-and-data-policy.md` defines bounded queues, data classes, redaction, terminal-content non-persistence, and proof acceptance rules.
-- `docs/architecture/terminal-host-provenance.md` records pinned terminal-component revisions, retained components, patch policy, and artifact provenance requirements.
-- `docs/architecture/terminal-host-spike-evidence.md` defines the mandatory in-terminal 2×2 proof workloads, measurements, and acceptance invariants.
-- `docs/architecture/terminal-host-proof-gate.md` defines the non-waivable stop/go acceptance policy and current pending record.
-- `docs/features` explains maintained user-facing feature behavior.
+- `docs/features` explains maintained user-facing behavior.
+- Operational and manual procedures live in focused runbooks under `docs`.
 - OpenSpec and Git carry planning and implementation history.
-- Source comments explain only non-obvious rationale, safety/security invariants, platform constraints, or public semantic contracts. Names, types, and decomposition explain normal control flow.
+- Source documentation follows the focused [code-documentation policy](code-documentation.md): owner-public class contracts are consistent, retained implementation comments state their intent, and names, types, and decomposition explain ordinary control flow.
 
 ## Terminal capability boundary
 
-Transparent terminal attachment owns one foreground child and no A1 surface. It cannot retain inactive terminal state or switch among arbitrary interactive CLIs inside A1. Bare-`a1` multi-agent UX may use structured/RPC surfaces without terminal emulation, but arbitrary-CLI tabs require a separate composed-terminal capability with PTY, authoritative terminal state, rendering, input routing, inactive-surface lifecycle, reconnection, and cross-platform certification. That future capability must not silently intercept or replace the transparent path. Explicit launch profiles and transparent fallback must not import, initialize, launch, or connect to composed terminal-host infrastructure.
+Both interactive profiles use the owned rendering pipeline. Bare `a1` exposes A1-owned surfaces; `a1 pi` withholds those surfaces while using Pi's ordinary profile root. The retired transparent attachment owner is not part of the production tree or dependency map.
 
-Composed terminals use a console terminal host that runs inside the user's existing terminal. The host owns pseudoterminal bytes, retained terminal state, keyboard/text/mouse/IME encoding, frame scheduling, and presentation to the containing terminal. A1's JavaScript control plane may exchange typed identity, topology revision, capability, lifecycle, status, and recovery messages only; it must not relay terminal output, per-event child input, or rendered cells. A desktop-native window, GPU renderer, Ghostty GUI runtime, Winghostty Win32 runtime, Metal, GTK, and AppKit are postponed and are not required for the in-terminal product.
+The current JavaScript control plane does not provide arbitrary-CLI tabs. Such tabs require the separately bounded console terminal host to own PTYs, authoritative terminal state, rendering, input routing, inactive-surface lifecycle, and reconnection. JavaScript may exchange typed identity, topology revision, capability, lifecycle, status, and recovery messages only; it must not relay terminal output, per-event child input, or rendered cells.
 
-A tab owns a revisioned split tree. Each leaf pane references one PTY-backed terminal session. Structured/RPC agents remain semantically separate and may not derive state from ANSI text, terminal timing, or screen content. Native source ownership lives outside `src/` when introduced; packaged host selection is governed by release/package owners. Existing architecture tests reject terminal-host hot-path bytes in JavaScript protocol code, terminal inference in structured runtime code, composed imports from explicit launch modes, and replacement lightweight terminal parsers/renderers.
+Structured agents remain semantically separate and use typed events, commands, snapshots, cancellation, and recovery evidence. They must not derive state from ANSI text, terminal timing, or screen content. Native source ownership remains outside `src/`; packaged host selection is governed by release/package owners. Architecture tests reject terminal-host hot-path bytes in JavaScript protocols, terminal inference in structured runtimes, and replacement lightweight terminal parsers or renderers.

package/docs/architecture/prompt-suggestions.md

@@ -0,0 +1,68 @@
+# Prompt suggestion reliability
+
+Bare A1 predicts a short next user input with one isolated request using the selected model. A clear offered action consistent with recent user intent, such as `archive it` after accepted merged work, is preferred over abstaining merely because optional testing was also offered. Required validation, conflicting intent, and unresolved choices still allow no suggestion. There is no quoted-text extraction fallback.
+
+## Request and editor boundaries
+
+The adapter resolves the lowest supported effort from the selected session model's available thinking levels, without changing the main thinking setting. Non-reasoning models omit reasoning controls; supported `off` also omits the optional reasoning argument, matching the model runtime's ordinary completion contract. Other supported efforts are supplied explicitly. Missing capabilities produce `unavailable`, not a guessed provider option. Provider mapping/clamping remains owned by the pinned model runtime; the diagnostic policy describes the applied request option, not inferred server-side computation.
+
+The controller retains the 15-second deadline, does not retry or switch models, and retires a timeout before aborting. A provider that ignores abort cannot revive retired text. A timely candidate remains private until matching settlement. Ghost text is not editor content, approval, or a submission: Tab accepts it into the editor, and Enter must be pressed separately to submit it. Typing, session/model replacement, continuation, or disabling suggestions invalidates unaccepted work. `a1 pi` does not install this feature.
+
+## Opt-in local diagnostics
+
+Set `A1_SUGGESTION_DIAGNOSTICS` to a **dedicated writable file** when launching bare A1. It is an explicit snapshot destination, not a log directory. The parent directory must already exist. The selected file is overwritten with the latest bounded snapshot; never select a session, source, credential, or other valuable file. Do not share one destination between running processes.
+
+For a repository checkout in Git Bash:
+
+```sh
+npm run build && A1_SUGGESTION_DIAGNOSTICS="$PWD/.artifacts/suggestion-diagnostics.json" ./scripts/dev
+```
+
+Create `.artifacts` first if it does not exist. For an installed release, use the same environment assignment before `a1`. The variable follows the ordinary launch environment; it adds no interactive flag, setting, footer row, or transcript message. SDK composition can supply `suggestionDiagnosticsPath` explicitly. Comparison or settings-free compositions ignore both paths.
+
+While that session is running, inspect the selected JSON file using a local editor or:
+
+```sh
+node -e 'const fs=require("node:fs"); console.table(JSON.parse(fs.readFileSync(process.argv[1],"utf8")).records)' .artifacts/suggestion-diagnostics.json
+```
+
+The `prompt-suggestion-diagnostics-v1` snapshot contains at most 128 metadata records and 64 KiB. Capture is off by default. Records include process-local session/run/response/request numbers, bounded provider/model identifiers, applied reasoning policy, elapsed milliseconds, event, and optional reason. They exclude conversation/candidate text, tool data, raw errors, credentials, and session/worktree paths. There is no upload. Older records are evicted, so a retained terminal event can outlive its evicted start event. `request: 0` means no request was started for that decision.
+
+| Event | Meaning |
+| --- | --- |
+| `skipped` | No request started; inspect `reason`. |
+| `started` | One generator request was initiated; reasoning may be `unavailable` for an injected generator without policy metadata. |
+| `displayed` | A current candidate was shown after settlement. |
+| `empty` | The provider returned no text; this does not reveal the model's private reason for abstaining. |
+| `rejected` | Returned content violated the candidate contract, contained tool calls, was truncated, or had invalid formatting/voice. |
+| `provider-failure` | Provider error/rejection; raw error details are intentionally omitted. |
+| `unavailable` | Model/runtime/capabilities or request identity were unavailable at the generator boundary. |
+| `timeout` | The controller's 15-second deadline expired. |
+| `cancelled` | Work was invalidated or aborted, including typing or continuation. |
+| `stale-result` | A result or settlement identity did not match its request. |
+| `presentation-blocked` | A valid candidate could not be shown; inspect `reason`. |
+| `late-result-discarded` | A retired request eventually resolved/rejected; this is not a second terminal outcome or request. |
+
+Eligibility/presentation reasons include `disabled`, `disposed`, `early-conversation`, `no-model`, `failed-response`, `incomplete-response`, `tool-continuation`, `replacement-input`, `modal`, `draft`, `not-ready`, `not-focused`, `autocomplete`, `prompt-mode`, and `stale-identity`. `ineligible` and `presentation-unavailable` cover injected ports without finer metadata. A missing suggestion alone is never evidence of timeout or intentional model abstention.
+
+Writes are asynchronous and coalesced: at most one write and one pending latest snapshot. Sink failures do not affect generation, input, or rendering and do not appear in the UI. An unwritable destination may therefore produce no file; check the destination locally rather than diagnosing the model from that absence. Disposal clears in-memory capture and pending writes; a write already in progress can finish. Exported local files remain until you remove them.
+
+To disable capture, omit/unset `A1_SUGGESTION_DIAGNOSTICS` before the next launch and remove the dedicated snapshot if no longer needed. This does not disable suggestions; `/settings` -> Agent -> Prompt suggestions controls generation independently.
+
+## Verification and evidence limits
+
+The focused tests cover the synthetic archive offer and required-testing/unresolved-choice counterexamples, unchanged primary thinking, typed outcomes, timeout/cancellation races, editor acceptance, and local privacy/bounds:
+
+```sh
+npx vitest run test/app/session-shell/prompt-suggestion-controller.test.ts test/integrations/pi/engine/adapter.test.ts test/features/prompt-suggestions/diagnostics.test.ts test/contracts/owned-ui/contracts.test.ts test/app/session-shell/session-shell.test.ts
+```
+
+A separate opt-in probe uses the profile's saved model/authentication with a scratch cwd, in-memory sessions/settings, disabled extensions/skills/prompts, and no tools. It performs five original-policy predictions, five revised-policy predictions, and one required-testing counterexample. This makes **11 provider requests** and can consume quota. Run only with explicit authorization:
+
+```sh
+RUN_PROMPT_SUGGESTION_PROVIDER_TEST=1 PROMPT_SUGGESTION_AGENT_DIR="C:/path/to/agent-profile" npx vitest run test/integrations/pi/engine/prompt-suggestion-provider.integration.test.ts
+```
+
+The probe reports outcome/latency summaries and archival-candidate counts, not raw text. It requires at least one revised archival continuation and rejects an archival continuation in the required-testing case. Five samples are a smoke comparison, not a statistical reliability guarantee. Missing credentials, model availability, or a successful real archival prediction leave provider acceptance pending; fake tests do not prove model quality.
+
+For manual review, use a harmless synthetic conversation with two assistant responses: establish that an imaginary change was tested, accepted, and merged, then ask for a closeout offer containing `Say archive it` with optional extra testing. Do not ask the agent to perform real archival to test ghost text. Keep main thinking high and the editor untouched while waiting, inspect the outcome snapshot, check Tab/Enter separately, and repeat with typing cancellation and suggestions disabled. Verify required testing is not treated as optional. Real latency, model abstention, and existing context-reconstruction limitations can still leave the editor empty.

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

@@ -31,7 +31,8 @@ Every asynchronous consumer must implement a finite queue or window. Backpressur
 | Class | Examples | Storage policy |
 |---|---|---|
 | 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 |
+| Structured payloads | Messages, tool calls, snapshots, attachments | Bound and process; arbitrary payload persistence remains unsupported |
+| User-authored prompt recall | Canonical interactive input and bounded provenance | May persist only through the profile-isolated prompt-history policy below, never in the control store |
 | 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 |
@@ -42,11 +43,36 @@ Every asynchronous consumer must implement a finite queue or window. Backpressur
 
 Sanitization must classify before logging or storing. Unknown or untyped values are potentially sensitive by default and must not be persisted. Terminal bytes must never be written to logs as a debugging shortcut.
 
+## Typed prompt-history retention
+
+The `prompt-history` feature owns only reusable interactive user input, not
+structured-message archives. It stores one independent profile database under
+`<effective-home>/.a1/data/history`, or `<A1_DATA_DIR>/history` when explicitly
+overridden, never agent resources or cache/release directories. The default home
+follows launch-profile resolution, including `A1_PROFILE_HOME`; other product
+data paths are unchanged. Text is unencrypted and potentially sensitive. Retain up to 100 unique entries (configured
+10-100), at most 1 MiB per entry and 8 MiB total canonical text. Background queues
+are limited to 32 writes/8 MiB per instance; reads are coalesced, lock retries are
+bounded to one second off-thread, and graceful shutdown drains for at most two
+seconds. SQLite page/journal limits and a 64 MiB maintenance threshold bound
+physical growth separately from text retention.
+
+Only typed canonical text, submission identity, recency/timestamp, input kind,
+and bounded cwd/session provenance are allowed. No image bytes, transformed
+agent prompts, environment/credential copies, tool results, terminal streams, or
+private input in diagnostics are permitted. Disabling persistence is next-start
+and does not erase data or stop other live instances. Upgrades, ordinary npm
+uninstall/reinstall, and cache/release cleanup must not touch history. The new
+default starts fresh without probing, importing, or deleting the old platform
+store. Any old-store removal is a separate manual operation after its users have
+stopped, not startup or cleanup behavior. See [prompt history](../features/prompt-history.md) for
+retention, failure semantics, profile identity, and stopped-instance removal.
+
 ## Required architectural outcomes
 
 - Structured/RPC semantics must not be inferred from ANSI text, terminal timing, or visual content.
 - Native-host protocol code must not carry PTY bytes, per-event child input, rendered cells, cell grids, framebuffers, or screen buffers.
-- `a1 pi` and `a1 sandbox` must not import, initialize, launch, or connect to composed terminal-host infrastructure.
+- `a1 pi` must not import, initialize, launch, or connect to composed terminal-host infrastructure.
 - Transparent direct attachment must remain independent of composed infrastructure and must not relay terminal data.
 - Recovery records store identity and bounded references, not terminal streams, authentication material, or arbitrary environment values.
 - A failed in-terminal 2×2 proof cannot be waived to merge composed infrastructure.