@timurproko/a1 0.2.6 → 0.2.7-dev.1222

package/docs/architecture/response-copy-delivery.md

@@ -19,7 +19,7 @@ A generated probe on Windows Node 24.16.0 copied the same eight-character range
 - Copy: 5-second admission deadline, one executing request and one newest pending request, at most 16 MiB UTF-8 text. Source snapshots retain only selected rows, capped at 65,536 rows and 32 Mi UTF-16 code units; they do not keep an obsolete whole-transcript graph.
 - Paste: eight distinct admitted requests, a 5-second acquisition budget including the captured write wait, and a 15-second deadline through insertion. A canceled executor counts against capacity until its stop fence. Image conversion has one process-wide slot. Copy supersession is deliberately not used for paste edits.
 - Text transfer: 16 MiB UTF-8 cap; IPC fragments are at most 16,384 code units and preserve surrogate pairs. The receiver acknowledges each fragment. Prepared large text is stored behind the existing compact chip rather than inserted as millions of editor characters. Existing source-image, pixel, encoded-output and attachment-count limits remain unchanged.
-- Clipboard executors have a 250 ms stop grace. A helper that has already reported a complete prepared result and lingers past that grace is reaped, not canceled: it is still terminated, but its prepared text is delivered exactly rather than replaced with an empty payload. Only an explicit cancellation, a protocol violation, or an incomplete byte count discards prepared text. POSIX command fallbacks share the paste helper's isolated process group; strict command reads use a forceful kill signal. Unconfirmed executor termination retains its capacity instead of allowing unbounded replacements or late A1-controlled writes. No helper inherits the UI terminal or places clipboard payloads in argv, temporary files, or logs.
+- Clipboard executors have a 250 ms stop grace. A helper that has already reported a complete prepared result and lingers past that grace is reaped, not canceled: it is still terminated, but its prepared text is delivered exactly rather than replaced with an empty payload. Only an explicit cancellation, a protocol violation, or an incomplete byte count discards prepared text. POSIX command fallbacks share the paste helper's isolated process group; strict command reads use a forceful kill signal. Native POSIX copy writers (`wl-copy`, `xclip`, `pbcopy`) start detached in their own process group, as in pinned Pi 1.4, so a writer that daemonizes to keep serving the clipboard is not stopped when Ctrl+Z suspends A1. Unconfirmed executor termination retains its capacity instead of allowing unbounded replacements or late A1-controlled writes. No helper inherits the UI terminal or places clipboard payloads in argv, temporary files, or logs.
 - Local copy prefers native delivery outside the terminal. OSC 52 uses the existing writer only on a non-blocking supported output route and is capped at a complete 64 KiB control, or a lower advertised limit. Submission is not clipboard acknowledgment. Remote/multiplexed sessions never silently read or write a different host's clipboard. Native Ctrl+V acquisition is unavailable when only the remote terminal owns the desired clipboard; normal terminal-provided paste remains supported.
 - URL-chip decoration: at most 65,536 UTF-8 bytes of added OSC 8 metadata per editor render pass across rows and repeated occurrences, including opening/closing pairs and cleanup closes. Targets that do not fit are omitted whole before control construction; a UTF-16 length precheck avoids scanning huge backing values. The budget resets each pass. Full chip data, atomic editing and exact copy/history/submission expansion remain intact; ordinary in-budget links retain their targets. Terminal automatic URL recognition is separate from explicit metadata.
 - Path-list presentation: the isolated classifier budgets 4,096 UTF-16 units per paste for existing individual tags plus 20 suffix-reserve units per occurrence. Over-budget lists use one existing text-paste chip backed by all classified full paths concatenated in order, including repetitions, without extra separators or re-normalization. No individual members are adopted into the UI before compaction. Small lists retain their file/folder/image-file chips; failed/timed-out classification retains the existing original-text fallback. Existing draft/history chips and the synchronous compatibility classifier are unchanged.

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

@@ -2,6 +2,8 @@
 
 The composed-terminal proof is a stop/go gate. A1 must not merge or productize composed terminal panes until the exact in-terminal spike artifact passes both technical and physical acceptance.
 
+This gate applies to split-pane composition only. The single-pane resident-tab path does not reuse or reinterpret its pending evidence; each resident milestone is certified independently by the staged requirements and platform evidence in [`resident-tabs.md`](resident-tabs.md).
+
 ## Go criteria
 
 A `go` decision requires all of the following:

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

@@ -1,6 +1,6 @@
 # Terminal-host provenance
 
-The composed-terminal proof uses a small console-hosted stack. It runs inside the user's existing terminal and does not create a separate desktop window.
+The resident terminal host uses a small console-hosted stack. Its native implementation ships as the Node-API 9 addon `terminal-host.node`; the release's fixed `dist/foundation/resident-tabs/host-entry.js` loads that addon and dispatches the server, holder, attach, probe, maintenance, and internal roles inside the hosting Node runtime. It runs inside the user's existing terminal and does not create a separate desktop window. No terminal-host executable is built or shipped, and the same addon exports the in-process session-writer lock.
 
 ## Selected source components
 
@@ -8,7 +8,13 @@ The composed-terminal proof uses a small console-hosted stack. It runs inside th
 |---|---|---|---|
 | `libghostty-vt` | `ghostty-org/ghostty` commit `c5a21edfcbc2d5b46540ad91b7980aca31f5f1f3` | Terminal parsing, retained state, and input semantics | MIT |
 | `portable-pty` | version `0.9.0` | ConPTY/Unix PTY and process ownership | MIT |
-| Crossterm | version `0.29.0` | Outer-terminal raw mode and host input events | MIT-compatible candidate; notice must be vendored before packaging |
+| Crossterm | version `0.29.0` | Outer-terminal raw mode and host input events | MIT; license text ships in the generated notices |
+
+`libghostty-vt` is built with `-Dsimd=true`, which statically links simdutf `9.0.0` (Apache-2.0 OR MIT, vendored in the libghostty tree) and Highway at commit `66486a10623fa0d72fe91260f96c892e41aceb06` (Apache-2.0 OR BSD-3-Clause, fetched by the pinned Zig build). Their license texts are kept under `native/terminal-host/vendor/third-party-licenses/` with digests recorded in `config/terminal-host-provenance.json`, beside the upstream napi-rs license that the published `napi` and `napi-sys` crates omit.
+
+## Release notices
+
+`scripts/release/generate-terminal-host-notices.mjs` writes `terminal-host-THIRD-PARTY-NOTICES.txt` beside each release addon. It walks the locked Cargo graph for the build target (normal dependencies, including the Node-API glue; proc-macro crates and their subtrees never reach the addon), adds the Zig-linked components, and fails on a license expression outside MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC, Unicode-3.0, or Zlib (the `LLVM-exception` addendum is accepted), on a crate without license text, or on a pinned text whose digest changed.
 
 A buffered A1-owned frame composer is the initial presentation layer. Ratatui is an optional evaluation candidate only if the narrow composer increases rendering risk; it is not selected by default.
 
@@ -46,8 +52,8 @@ The console proof requires:
 
 - Rust/Cargo for the A1 terminal host;
 - Zig `0.15.x` with patch `>= 0.15.2` to build `libghostty-vt`;
-- the platform C/C++ build toolchain required by Rust and the PTY/input crates (Visual Studio 2022 Build Tools/MSVC on Windows);
-- Windows 10/11 x64 or ARM64 for the first proof;
+- the platform C/C++ build toolchain required by Rust and the PTY/input crates (Visual Studio 2022 Build Tools/MSVC on Windows, the runner image's Xcode Clang on macOS, GCC on Linux);
+- release builds on `windows-2025`, `ubuntu-24.04`, and `macos-15` (arm64, which also cross-compiles the x64 artifact with `--target x86_64-apple-darwin`);
 - an existing terminal emulator for manual validation;
 - an isolated disposable worker for automated physical validation.
 
@@ -67,3 +73,9 @@ Every spike or production host artifact must record:
 - evidence workload schema version and physical/manual verdict reference.
 
 Unverified, mismatched, or unsigned/unattested artifacts are not eligible for composed-terminal integration.
+
+## Release artifact
+
+`npm run build:terminal-host` (`scripts/development/build-terminal-host.mjs`) builds the library once with `cargo build --release --locked --lib --features node-addon`, copies the cdylib as `terminal-host.node`, loads the addon in Node, and checks its `version()` report: protocol, generation, crate version, pinned `libghostty-vt` commit, and the absence of `fault-injection` and `resident-fixtures`. Release and native validation runners invoke it with their pinned Zig toolchain. The normal developer `npm run build` invokes the same release-profile builder for the current platform; on Windows it links a manifest-verified terminal library exported by trusted CI and records the repository-pinned Zig producer version without invoking Zig on the workstation. The macOS x64 cross build may use the recorded Mach-O architecture check when the arm64 runner cannot load the addon.
+
+The generated `terminal-host.manifest.json` uses schema `a1-terminal-host-artifact-v2` and records `kind: "node-addon"`, Node-API 9, the addon's SHA-256 and size, the release-relative role-entry digest, the notices digest, target triple, Rust and Zig versions, and `Cargo.lock` digest. The role entry passes only the fixed role grammar and records `{ executable: process.execPath, entry, artifact: addonPath }` once in the addon; the explicit loaded artifact identity makes release-hold reporting independent of development environment propagation. Detached and WMI resident starts use the recorded Node-and-entry command and never resolve an A1-built executable. The publication `package` job refuses to pack unless every platform's process-guardian and terminal-host addons match their manifests, and A1 verifies the addon, entry, and notices before loading the host.

package/docs/architecture/tool-image-presentation.md

@@ -16,7 +16,7 @@ The source unit is from MIT-licensed repository <https://github.com/earendil-wor
 
 One conversion is active per mounted tool. The waiting set is the newest current source set, not an unbounded queue of superseded snapshots. Hidden images and non-Kitty protocols do not start conversions. Work removed before codec entry is skipped. A public codec call already in progress cannot be cancelled; its eventual result is discarded if the source or mount is obsolete. This limitation is explicit, not claimed as cancellable worker execution.
 
-Pending Kitty conversion has a visible `[Image converting: ...]` marker. Failure, rejection, or oversized converted bytes produces `[Image unavailable: ...]`, without exposing codec diagnostics or changing the operation outcome. Converted pixels never replace the original payload passed to extension renderers. PNG and iTerm presentation use the actual public `Image` component. Hidden and no-image-capability text presentation matches pinned Pi.
+Pending Kitty conversion has a visible `[Image converting: ...]` marker. Failure, rejection, or oversized converted bytes produces `[Image unavailable: ...]`, without exposing codec diagnostics or changing the operation outcome. Converted pixels never replace the original payload passed to extension renderers. PNG and iTerm presentation use the actual public `Image` component. Explicitly hidden images retain pinned textual indicators. When image display is enabled but the terminal advertises no image protocol, bare A1 omits the non-actionable attachment fallback from user and tool transcript content; attachment bytes, metadata, model delivery, the explicit `a1 pi` route, and extension-owned image components remain unchanged.
 
 Rebuild/disposal releases image ownership and invalidates the previous mount. Reentrant renderer invalidation is suppressed during synchronous reconstruction; valid asynchronous callbacks still request the existing scheduler and update presentation revision, not semantic revision.
 
@@ -31,6 +31,7 @@ This correction does not introduce an ANSI parser, change link detection, relax
 - `transcript-image-conversion.test.ts`: independent pinned stale-cache baseline, JPEG replacement, PNG replacement, hidden/non-Kitty parity, failed-conversion fallback and real scheduled Kitty publication at unchanged semantic revision.
 - `tool-image-presentation.test.ts`: current-source sharing, one active conversion, superseded bursts, removed/disposed callbacks, hidden/iTerm work avoidance, rejection and size fallback without retry loops.
 - `tool-shell-parity.test.ts`: independent actual pinned read/bash/edit/write/grep/find/ls and generic rendering at widths 40/80/192, partial/final/error states, expansion, binary text, and extension default/self shells with original inputs and stable renderer state.
+- `shell-components.test.ts`: unsupported user and tool transcript images produce no fallback row or spacer, while explicit hiding and capable-terminal unavailable diagnostics remain visible.
 - Existing attachment-ownership, payload-limit, content-retention and shell tests remain non-regression gates. The wrapped-URL counterexample remains explicitly unresolved under issue #353.
 
 These are automated content and ownership checks, not Windows Terminal visual acceptance. The broader change stays open until scheduled-producer evidence, required CI, and exact-candidate user review satisfy its remaining tasks.

package/docs/architecture/toolchain.md

@@ -26,19 +26,21 @@ Physical desktop automation is absent from the active repository baseline. Any f
 The published package contains:
 
 - the sole public `a1` command;
-- the internal supervisor entry;
-- immutable release/bootstrap, lifecycle, protocol, storage, update, owned-UI, and Pi-adapter modules;
+- the internal supervisor, launch-guardian, exit-watcher, and fixed terminal-host role entries;
+- immutable release/bootstrap, lifecycle, protocol, storage, update, owned-UI, and Pi-adapter modules, plus `process-guardian.node` and `terminal-host.node` for every supported target with manifests and terminal-host notices;
 - current user and architecture documentation.
 
-It contains no PTY, terminal emulator, browser/desktop GUI, custom renderer, input translator, physical automation driver, or generated runtime data.
+It contains no executable built from A1 sources, separate session-lock addon, browser/desktop GUI, physical automation driver, or generated runtime data. PTY ownership, terminal emulation, composition, and input translation exist only inside the terminal-host addon; the JavaScript product path does not relay terminal bytes.
 
-## Native launch containment
+## Native addon layer
 
-`npm run doctor` reports this contract against the current machine—Node range, npm major, git, the GitHub CLI, Rust/Cargo, and whether `node_modules` matches the lockfile—and names the install command for anything missing. `npm run build` runs the same check as its first step, so an unmet prerequisite fails by name rather than inside a module resolver or Cargo. Unmet tool prerequisites block; a Node or npm version outside the declared contract is reported as an advisory without failing the build.
+`npm run doctor` reports this contract against the current machine—Node range, npm major, git, the GitHub CLI, Rust/Cargo, Windows Microsoft C++ readiness where applicable, and whether `node_modules` matches the lockfile—and names the explicit setup action for anything missing. `npm run build` resolves the same native environment and runs the check before cleaning or compiling, so an unmet prerequisite fails by name rather than inside a module resolver, Cargo, or the linker. Unmet tool prerequisites block; a Node or npm version outside the declared contract is reported as an advisory without failing the build.
 
-Source builds require Rust/Cargo 1.85 or newer. `npm run build` compiles the standalone `native/process-guardian` crate for the host platform, places it under `dist/native/<platform>-<architecture>/`, and writes an integrity manifest. Preview and stable candidate workflows build platform artifacts on isolated Windows, Linux, and macOS runners and assemble them before packing. macOS remains explicitly unsupported until its exact containment adapter is certified; the package must fail before runtime startup rather than use PID-only cleanup.
+Source builds require Rust/Cargo 1.85 or newer; `rust-toolchain.toml` pins the exact version CI and publication install through `scripts/development/prepare-ci-rust.sh`, and rustup selects that version for Cargo commands inside the repository, installing it on first use. On Windows, the resolver honors explicit `CARGO` and `RUSTC` executables, then the launching `PATH`, then `%USERPROFILE%\.cargo\bin`; the fallback changes only build-child state. Windows native linking also requires Visual Studio or Visual Studio Build Tools with the Desktop development with C++ workload, MSVC x64/x86 tools, and a Windows SDK. Visual Studio Code is not a compiler prerequisite. An already valid developer environment is retained; otherwise the resolver uses the installed stable Visual Studio locator and `vcvars64.bat`, verifies that `cl.exe` and Microsoft's `link.exe` come from the selected VC tools, and passes the captured environment only to child processes. This prevents Git Bash's GNU `link.exe` from shadowing MSVC without changing persistent `PATH`. A1 never installs these tools, elevates privileges, or accepts licenses automatically. The Zig cache (`mlugg/setup-zig`, one entry per workflow and platform per run, bounded to 512 MiB) stays enabled: measured on 2026-10-16, a cold Zig build of `libghostty-vt` added about 40 to 60 seconds to a terminal-host test build (Linux 2m21s cold against 1m20s warm, Windows 2m05s against 1m26s), which the cache saves on every warm run.
 
-The process guardian inherits terminal handles but transports no terminal bytes. See [`process-guardian-provenance.md`](process-guardian-provenance.md).
+`npm run build` compiles `native/process-guardian` as the host platform's Node-API 9 addon, places `process-guardian.node` under `dist/native/<platform>-<architecture>/`, loads it to observe its version identity, and writes the v2 integrity manifest. It also builds the current platform's release-profile `terminal-host.node`, whose v2 manifest binds the addon, `dist/foundation/resident-tabs/host-entry.js`, and notices, so the ordinary `npm run build && ./scripts/dev` handoff exercises resident tabs without deployment. On Windows the normal build reuses a compatible ignored terminal-library cache or downloads the newest compatible library from the current branch or a successful CI run belonging to a pull request already merged into `develop`, then links it under the crate's manifest verification; it never silently invokes the quarantined Zig package fetch. An unavailable or mismatched prerequisite fails the build instead of leaving a nominally successful single-agent-only tree. The npm `prepare` lifecycle and validation preflight use the explicit core build because selected native lanes assemble and certify terminal hosts separately.
+
+Preview and stable candidate workflows build the addons on isolated Windows, Linux, and macOS arm64 runners, cross-compile the macOS x64 addons on the arm64 runner with `--target x86_64-apple-darwin`, and assemble all targets before packing. Those release runners retain their explicit `npm run build:terminal-host` step and pinned Zig input rather than consuming a workstation cache. Cross-compiled artifacts record a Mach-O architecture check when they cannot be loaded on the producing runner. Supported native code is always loaded by Node; an absent, incompatible, or unsupported addon fails before runtime startup rather than falling back to PID-only cleanup. The process-guardian addon inherits terminal handles but transports no terminal bytes. Its separate Node-hosted exit watcher restores terminal state after guardian failure, subject to the documented node-wide-kill gap. See [`process-guardian-provenance.md`](process-guardian-provenance.md), [`terminal-host-provenance.md`](terminal-host-provenance.md), and [`resident-tabs.md`](resident-tabs.md).
 
 ## Gates
 
@@ -71,7 +73,7 @@ This optional, mutating presentation-maintenance workflow regenerates component
 
 `node scripts/pi/sync-pi-inventories.mjs` re-resolves `modal-surface-inventory.json`, `presenter-ownership-inventory.json`, and `pinned-pi-interactive-baseline.json` against the installed Pi packages: anchors that still match stay, anchors that match only ignoring whitespace are rewritten, anchors that match nowhere mark their entry `orphaned`, behavior line ranges that lost their anchors move to their symbols' span, hashes and manifests are regenerated, and interactive components the modal graph has never recorded are reported as unmapped. `--check` reports without writing; `--commit <sha>` records a new version's upstream commit; `--report <path>` writes the resolution report.
 
-`node scripts/pi/propose-pi-upgrade.mjs [--version <v>] [--commit <sha>] [--skip <v>...] [--refresh] [--output <dir>]` proposes a Pi upgrade in the working tree: it captures the old upstream sources, pins both packages at the target (by default the newest published version newer than the pin that is not skipped; `--version` ignores skips), evaluates the candidate through `pi-candidate-evaluator.mjs` and keeps the complete compile output in the artifact (summarized per file in the body), installs and builds, three-way merges each vendored copy under `src/integrations/pi/components/upstream/` whose ledger record says `upgradeStrategy: three-way` (`git merge-file --diff3` of the A1 copy, the old upstream, and the new upstream; conflict markers stay in the file as review items) and, for a `keep-owned` copy, leaves the file alone and writes the upstream delta to `kept/<record>.diff` in the artifact, regenerates the ledger and headers, re-resolves the inventories, refreshes the public API baseline (listing removed or changed exports with their A1 consumers as adoption items) and the feature adoption matrix (listing new upstream rows as pending), re-pins the startup graph, refreshes parity evidence, runs the type, architecture, engine-conformance, and parity gates, scaffolds `openspec/changes/pi-upgrade-<version>/` with the pin moved in the requirement that names it (only when the change directory is absent), and writes `report.json` and the pull-request `body.md`. A failed step is recorded and the run continues; while conflict markers remain in any copy, the gates that compile the tree (`startup-graph`, `parity`, `typecheck`, `architecture`, `parity-suites`) are recorded as `blocked` by those copies instead of running to fail, and the isolated evaluation and engine conformance still report the candidate's verdicts. `--refresh` re-runs the derived steps and gates on the checked-out proposal branch without bumping, evaluating, installing, or merging, comparing against the pin of `--base` (`origin/develop`). `.github/workflows/pi-upstream-sync.yml` runs it nightly and opens or refreshes the draft pull request `chore/pi-<version>` with the App identity: the body's report lives between `<!-- pi-upgrade-report -->` markers and only that part is rewritten on a re-run (`scripts/pi/refresh-pi-upgrade-body.mjs`), and a branch that carries commits the bot did not author is never pushed to; the fresh report is posted as a comment instead. Closing a proposal with the `pi-upgrade-skipped` label skips its version; `PI_UPGRADE_FREEZE_UNTIL` silences the schedule until a date. A human resolves the review items and merges. The pinned identity every check compares itself to comes from `scripts/governance/pinned-pi-identity.mjs`: versions from the dependency authority, the commit from `pinned-pi-interactive-baseline.json`.
+`node scripts/pi/propose-pi-upgrade.mjs [--version <v>] [--commit <sha>] [--skip <v>...] [--refresh] [--output <dir>]` proposes a Pi upgrade in the working tree: it captures the old upstream sources, pins both packages at the target (by default the newest published version newer than the pin that is not skipped; `--version` ignores skips), evaluates the candidate through `pi-candidate-evaluator.mjs` and keeps the complete compile output in the artifact (summarized per file in the sync report), installs and builds, three-way merges each vendored copy under `src/integrations/pi/components/upstream/` whose ledger record says `upgradeStrategy: three-way` (`git merge-file --diff3` of the A1 copy, the old upstream, and the new upstream; conflict markers stay in the file as review items) and, for a `keep-owned` copy, leaves the file alone and writes the upstream delta to `kept/<record>.diff` in the artifact, regenerates the ledger and headers, re-resolves the inventories, refreshes the public API baseline (listing removed or changed exports with their A1 consumers as adoption items) and the feature adoption matrix (listing new upstream rows as pending), re-pins the startup graph, refreshes parity evidence, runs the type, architecture, engine-conformance, and parity gates, scaffolds `openspec/changes/pi-upgrade-<version>/` with the pin moved in the requirement that names it (only when the change directory is absent), and writes `report.json`, the pull-request `body.md` in the ordinary delivery layout with its generated implementation and acceptance outcomes, and the sync report `comment.md` carrying the version delta, changelog excerpt, verdicts, and review items. A failed step is recorded and the run continues; while conflict markers remain in any copy, the gates that compile the tree (`startup-graph`, `parity`, `typecheck`, `architecture`, `parity-suites`) are recorded as `blocked` by those copies instead of running to fail, and the isolated evaluation and engine conformance still report the candidate's verdicts. `--refresh` re-runs the derived steps and gates on the checked-out proposal branch without bumping, evaluating, installing, or merging, comparing against the pin of `--base` (`origin/develop`). `.github/workflows/pi-upstream-sync.yml` runs it nightly and opens the draft pull request `chore/pi-<version>` with the App identity and posts the sync report comment; every later run posts another comment and never edits the body, whose outcomes the reviewer checks, and a branch that carries commits the bot did not author is never pushed to. Closing a proposal with the `pi-upgrade-skipped` label skips its version; `PI_UPGRADE_FREEZE_UNTIL` silences the schedule until a date. A human resolves the review items and merges. The pinned identity every check compares itself to comes from `scripts/governance/pinned-pi-identity.mjs`: versions from the dependency authority, the commit from `pinned-pi-interactive-baseline.json`.
 
 `node scripts/pi/update-pinned-pi-public-api.mjs [--check] [--packages-root <node_modules>] [--output <path>]` records `config/baselines/pinned-pi-public-api.json`, the package-root export surface of both pinned packages read from their declaration entries with the TypeScript compiler API: each export's kind, the hash of its normalized declaration, and the A1 modules under `src/` whose imports name it, directly or through a barrel such as `startup-public.ts`. The baseline is tooling evidence read by path, never a production import. `node scripts/pi/update-pi-feature-adoption-matrix.mjs [--check] [--packages-root <node_modules>] [--report <path>]` records `config/baselines/pi-feature-adoption-matrix.json`: one row per advertised and hidden command, TUI and app keybinding, session event, settings callback, presented setting, and stateful component from the interactive baseline's manifests and the engine's settings source, plus one row per changelog "New Features" entry newer than the matrix's `changelogSince`, each carrying A1's disposition: `pinned` (reused as is), `owned` (the behavior id and the test that proves it), `diverged` (the approved deviation id), `declined` (a reason), or `pending` (what the refresher writes for a new row). The refresher rewrites the upstream side only and marks a row upstream dropped `retired`; `test/repository-governance/pi-feature-adoption-matrix.test.ts` fails on a pending row, on missing evidence, and on a row whose feature upstream no longer presents unless it is retired. `node scripts/pi/update-startup-graph-baseline.mjs [--check]` re-pins the file and byte totals in `config/startup-graph-baseline.json` from the measured startup reachability and the manifest the last build wrote; optional modules and pinned dynamic imports stay reviewed.
 
@@ -81,7 +83,7 @@ Presentation acceptance is the reader comparing `a1 pi` with pinned Pi. `node sc
 
 ## Publication
 
-One reusable workflow publishes both npm channels: `.github/workflows/publish.yml`. Pushes do not publish. Nightly development verification runs at `03:17 UTC`; `npm run develop` dispatches the development wrapper for a numbered preview. `npm run release -- patch` generates a source-bound draft GitHub Release with a Pi-style version/date heading and categorized change sections, starts `.github/workflows/release-candidate.yml` to run the complete stable suite on that source, prints the run link, waits for it, and prints the draft editing link once only after it passes. Choosing native **Publish release** on the draft is the only stable npm trigger: GitHub creates the tag at the bound source, and the `release.published` workflow calls the default-branch publisher, which derives the authorized human actor, source, Release identity, normalized body, and digest, and requires the successful candidate run for that source and version. A preview is stamped as `-dev.<merged pull-request number>` and uses npm `next` only as an internal dist-tag. New candidates pack the application and dependency-free installer once each—including committed release history plus the approved current note snapshot—and validate their exact bytes on Windows, Linux, and macOS; after the click the published note is repacked and the exact-package gates run on the final bytes. A repeated nightly verifies both immutable registry tarballs. After npm verification, publication uploads the asset and fast-forwards `master`, then App-authenticated automation proposes one exact reopening PR, which documentation auto-merge re-verifies and merges after required CI, storing both next `-dev` versions and the note. A failure before either package reaches npm returns the Release to draft and deletes its unconsumed tag, the only tag deletion the release-automation App may perform; after npm, the same run's failed jobs are rerun. Tags are never moved or reused. All npm publication uses provenance from the `npm-publish` environment, a preview never changes `latest`, and one global non-cancelling concurrency group serializes the final registry check.
+One reusable workflow publishes both npm channels: `.github/workflows/publish.yml`. Pushes do not publish. Nightly development verification runs at `03:17 UTC`; `npm run develop` dispatches the development wrapper for a numbered preview. `npm run release -- patch` generates a source-bound draft GitHub Release with a Pi-style version/date heading and categorized change sections, starts `.github/workflows/release-candidate.yml` to run the complete stable suite on that source, prints the run link, waits for it, and prints the draft editing link once only after it passes. Choosing native **Publish release** on the draft is the only stable npm trigger: GitHub creates the tag at the bound source, and the `release.published` workflow calls the default-branch publisher, which derives the authorized human actor, source, Release identity, normalized body, and digest, and requires the successful candidate run for that source and version. A preview is stamped as `-dev.<first-parent commit count of the develop source>`, so later merges always sort above earlier ones, records the merged pull request and source commit as `publication` manifest metadata, and uses npm `next` only as an internal dist-tag. New candidates pack the application and dependency-free installer once each—including committed release history plus the approved current note snapshot—and validate their exact bytes on Windows, Linux, and macOS; after the click the published note is repacked and the exact-package gates run on the final bytes. A repeated nightly verifies both immutable registry tarballs. After npm verification, publication uploads the asset and fast-forwards `master`, then App-authenticated automation proposes one exact reopening PR, which documentation auto-merge re-verifies and merges after required CI, storing both next `-dev` versions and the note. A failure before either package reaches npm returns the Release to draft and deletes its unconsumed tag, the only tag deletion the release-automation App may perform; after npm, the same run's failed jobs are rerun. Tags are never moved or reused. All npm publication uses provenance from the `npm-publish` environment, a preview never changes `latest`, and one global non-cancelling concurrency group serializes the final registry check.
 
 `docs/ci-release-runbook.md` is the operational reference.
 

package/docs/ci-release-runbook.md

@@ -88,8 +88,8 @@ effect of stable publication, not a trigger.
 | Native **Publish release** on the prepared draft | GitHub creates the source-bound tag; `.github/workflows/release.yml` requires the successful candidate run, adopts the package pair it validated (replacing only the packaged release-note resource when the note was edited), proves npm trust, publishes both packages to npm `latest`, and proposes one reopening-and-note PR that auto-merges after required CI; a failure before npm returns the Release to draft |
 | `.github/workflows/release-tag-cleanup.yml` | When a stable Release is deleted, or on dispatch with a version (`gh workflow run release-tag-cleanup.yml -f version=X.Y.Z`): the release-automation App deletes the leftover `vX.Y.Z` tag only while no Release uses it and npm serves neither package; a published version's tag is permanent |
 | `.github/workflows/full-regression.yml` | Additional on-demand complete regression without publication authority |
-| `.github/workflows/pi-upstream-sync.yml` | Nightly at `03:23 UTC`: when npm publishes a newer Pi than the pin that no closed proposal skipped, proposes the upgrade as a draft pull request with the vendored copies that follow upstream merged, the kept copies reported with their upstream delta, the ledger, headers, inventories, public API and feature baselines, startup graph, and parity evidence regenerated, and every gate verdict (passed, failed, or blocked by conflict markers) and review item in the body; never merges and never replaces a proposal a human has continued |
-| `.github/workflows/nightly-regression-triage.yml` | After every completed `Full regression` run on `develop` or scheduled `Publish` validation: judges the startup budget across the three most recent runs and, after a failure or a persistent overrun, opens `fix/nightly-regression-<date>` as a draft pull request carrying the failed commands per lane, their tests, a bounded log excerpt, the `develop` commits since the last green run, and an OpenSpec fix scaffold, or refreshes the open candidate with the same failed scope set; re-runs nothing, never writes `develop`, never merges |
+| `.github/workflows/pi-upstream-sync.yml` | Nightly at `03:23 UTC`: when npm publishes a newer Pi than the pin that no closed proposal skipped, proposes the upgrade as a draft pull request with the vendored copies that follow upstream merged, the kept copies reported with their upstream delta, the ledger, headers, inventories, public API and feature baselines, startup graph, and parity evidence regenerated, and the body in the ordinary delivery layout with its four implementation outcomes and one acceptance outcome generated, and posts a sync report comment carrying the version delta, changelog excerpt, every gate verdict (passed, failed, or blocked by conflict markers), and review item; every later run posts another comment and never edits the body; never merges and never replaces a proposal a human has continued |
+| `.github/workflows/nightly-regression-triage.yml` | After every completed `Full regression` run on `develop` or scheduled `Publish` validation: judges the startup budget across the three most recent runs and, after a failure or a persistent overrun, opens `fix/nightly-regression-<date>` as a draft pull request in the ordinary delivery layout with its two implementation outcomes and one acceptance outcome generated, posts a triage comment carrying the failed commands per lane, their tests, a bounded log excerpt, and the `develop` commits since the last green run, and commits an OpenSpec fix scaffold, or refreshes the open candidate with the same failed scope set through another comment and design record; re-runs nothing, never writes `develop`, never merges |
 
 ## Impact-aware development validation
 
@@ -193,7 +193,7 @@ validation; malformed, mixed, renamed, stale, or unavailable inputs fail closed.
 A legitimate generated baseline update remains outside the allowlist and follows the
 manually accepted mixed/code path.
 
-A new implementation-bound specification starts as OpenSpec-only artifacts in one normally named draft PR. Explicit approval to implement continues in that same worktree, branch, history, and PR; the plan does not merge first. Approved refinements reconcile planning before code. After implementation, add one to ten plain implementation-specific bullets under `## Acceptance` and mark the PR ready; the trusted `OpenSpec finalization` workflow conservatively synchronizes deltas, stages the dated archive plus conditional acceptance manifest, and commits them to the same branch, and exact-head CI validates that head. Auto-merge remains disabled: an authorized maintainer's manual merge accepts the listed scenarios and atomically integrates implementation, specs, and archive. No acceptance or archive follow-up PR is created. Closing an unmerged draft integrates nothing; cleanup still needs separate approval. See [delivery and archive handoff](openspec-archive-automation.md) for commands and legacy compatibility.
+A new implementation-bound specification starts as OpenSpec-only artifacts in one normally named draft PR. Explicit approval to implement continues in that same worktree, branch, history, and PR; the plan does not merge first. Approved refinements reconcile planning before code. After implementation, add one to ten plain implementation-specific bullets under `## Acceptance` and mark the PR ready; the trusted `OpenSpec finalization` workflow conservatively synchronizes deltas, stages the dated archive plus conditional acceptance manifest, and commits them to the same branch, and exact-head CI validates that head. Automation-owned auto-merge remains disabled: an authorized maintainer's direct merge, personal exact-head auto-merge arm, or explicit request for the active agent to expected-head squash-merge the currently eligible candidate accepts the listed scenarios and atomically integrates implementation, specs, and archive. No acceptance or archive follow-up PR is created. Closing an unmerged draft integrates nothing; cleanup still needs separate approval. See [delivery and archive handoff](openspec-archive-automation.md) for commands and legacy compatibility.
 
 ## Numbered development previews
 
@@ -206,8 +206,15 @@ npm run develop
 
 The command fetches authoritative `origin/develop`, resolves the unique merged pull
 request associated with that exact commit through GitHub, and derives
-`<major.minor.patch>-dev.<pull-request number>`. Thus GitHub's `develop (#107)`
-source produces `0.1.8-dev.107`. It first checks npm; if the immutable version
+`<major.minor.patch>-dev.<count>`, where the count is the first-parent commit count of
+that commit. Pull request numbers follow opening order, not merge order, so a version
+built from them could sort below an install from an earlier merge; the count rises with
+every merge, so a later publication always sorts above an earlier one. The merged pull
+request and the source commit are recorded in both published manifests as
+`publication.pullRequest` and `publication.source`, which `a1 version` shows as
+`0.2.7-dev.1218 (#828)` and `a1 update --develop 828` resolves. Previews published
+before this change keep their `-dev.<pull-request>` versions and stay selectable by that
+number. It first checks npm; if the immutable version
 already exists for both the application and installer packages it reports that
 version without dispatching package work. If either immutable artifact is missing,
 it dispatches GitHub Actions, waits, and verifies both published versions. It never
@@ -358,7 +365,7 @@ Rules that do not bend:
 
 - **PR validation fails:** fix the code and push; do not mark a failed PR-cadence tier optional. If real predecessor history is needed, run Full regression rather than changing the exhaustive result into PR success.
 - **Nightly startup budget overruns:** a single overrun on Full regression or nightly publication is a warning in the run summary, not a failure; the triage judges the key across the three most recent `develop` runs and opens a `package-startup` candidate only when all three overran. Stable candidate validation still fails on one overrun; rerun it with the measured phases in hand.
-- **Nightly regression fails:** the triage workflow opens or refreshes a draft `fix/nightly-regression-<date>` pull request whose body and change carry the evidence and whose `regression-provenance.json` binds the source run; start the fix there. A failed Full regression source created by `openspec-ci` selects PR-attached Full regression, while a Publish-only failure or successful-run persistent overrun retains ordinary PR validation. Reproduce from the listed tests or commands on the failed lane and fix without weakening assertions, budgets, timeouts, or coverage. Record focused implementation evidence and pre-finalization observations in the change, then require `Development validation required` and, when selected, PR-attached Full regression on the finalized exact head. Put final run/head/selection in Actions and handoff rather than making another evidence-recording commit. Standalone dispatch remains diagnostic; numbered-package nightly recovery is independent. A day whose failed scope set differs from every open candidate opens a new one. A Full regression dispatched on a candidate's own branch is that candidate's proof but never selected PR authority; its failures never open another candidate. A failure with no candidate means the triage workflow itself failed; read its run summary and dispatch it with the failed run id and `dry_run` off.
+- **Nightly regression fails:** the triage workflow opens or refreshes a draft `fix/nightly-regression-<date>` pull request whose triage comment and change carry the evidence and whose `regression-provenance.json` binds the source run; start the fix there. Its body is the ordinary delivery layout with the two implementation outcomes, the acceptance outcome, and the triage key already generated: check each outcome as it completes, never rewrite the generated items, and let trusted readiness promote the all-checked draft like any other. A failed Full regression source created by `openspec-ci` selects PR-attached Full regression, while a Publish-only failure or successful-run persistent overrun retains ordinary PR validation. Reproduce from the listed tests or commands on the failed lane and fix without weakening assertions, budgets, timeouts, or coverage. Record focused implementation evidence and pre-finalization observations in the change, then require `Development validation required` and, when selected, PR-attached Full regression on the finalized exact head. Put final run/head/selection in Actions and handoff rather than making another evidence-recording commit. Standalone dispatch remains diagnostic; numbered-package nightly recovery is independent. A day whose failed scope set differs from every open candidate opens a new one. A Full regression dispatched on a candidate's own branch is that candidate's proof but never selected PR authority; its failures never open another candidate. A failure with no candidate means the triage workflow itself failed; read its run summary and dispatch it with the failed run id and `dry_run` off.
 - **Nightly exhaustive predecessor validation fails:** treat the focused PR result as insufficient, keep publication blocked, and repair the incompatibility without reducing predecessor count, timeouts, or exact-package isolation.
 - **Documentation auto-merge fails:** leave the pull request open, inspect its exact
   changed-file classification, docs-sensitive inventory, and workflow permissions,
@@ -372,7 +379,7 @@ Rules that do not bend:
   with another token.
 - **Repository governance drifts:** run the read-only checker, review every reported
   path, and use the confirmed apply mode only for an accepted mutable policy change.
-- **A Pi upgrade proposal needs a re-run:** the sync never force-pushes over `chore/pi-<version>` once it carries a commit the bot did not author; a scheduled re-run posts its fresh verdicts as a comment headed with the version and date and rewrites only the report between the `<!-- pi-upgrade-report -->` markers of the description. To re-run the derived steps and gates on the reviewer's head, dispatch the workflow with `refresh` and the `version`; it checks out the proposal branch, skips bump, evaluation, install, and merge, and reports without pushing. A branch whose commits are all the bot's is recreated from `develop` as before.
+- **A Pi upgrade proposal needs a re-run:** the sync never force-pushes over `chore/pi-<version>` once it carries a commit the bot did not author; a scheduled re-run posts its fresh verdicts as another sync report comment headed with the version and date and never edits the description. The description is the ordinary delivery layout: check each generated implementation outcome as its work completes, including one the report shows nothing for, never rewrite the generated items, and let trusted readiness promote the all-checked draft like any other. To re-run the derived steps and gates on the reviewer's head, dispatch the workflow with `refresh` and the `version`; it checks out the proposal branch, skips bump, evaluation, install, and merge, and reports without pushing. A branch whose commits are all the bot's is recreated from `develop` as before.
 - **A Pi version should not be adopted:** close its proposal pull request with the `pi-upgrade-skipped` label (declared in `config/github-repository-governance.json`) and say why in the closing comment; the next run proposes the newest unskipped version newer than the pin, or nothing, and names the skipped versions in its log. A proposal closed without the label is proposed again the next night. Dispatching the workflow with a `version` ignores skips, which is how a skipped version is reconsidered. To silence the schedule through a release window, set the repository variable `PI_UPGRADE_FREEZE_UNTIL` to a date (`2026-10-01`); scheduled runs exit before proposing until it passes, manual dispatches still run.
 - **Nightly documentation review fails:** inspect the reported paths and rules, identify the introducing merge from the nightly interval, and repair the invariant before unrelated work proceeds.
 - **Development publication fails:** inspect both package versions and digests, fix the cause, and rerun `npm run develop`; an npm version that already exists is verified and never overwritten.

package/docs/features/launch-profiles.md

@@ -4,13 +4,16 @@
 
 | Command | Purpose | Pi user profile |
 |---|---|---|
-| `a1` | Fresh A1-owned Pi-compatible UI session | `~/.a1/agent` |
+| `a1` | A1 | `~/.a1/agent` |
 | `a1 --session <path\|id>` | Resume a persisted A1 session | `~/.a1/agent` (or explicitly selected storage) |
-| `a1 pi` | Pi-compatible comparison surface using the ordinary Pi profile | ordinary `~/.pi/agent` |
+| `a1 solo` | A1 direct single-agent mode | `~/.a1/agent` |
+| `a1 pi` | Pi-compatible direct comparison surface using the ordinary Pi profile | ordinary `~/.pi/agent` |
+
+`a1 solo` is available in release and prerelease builds. It starts A1 in single agent mode, is argument-free, and omits both the tab strip and the Tabs settings section.
 
 `a1 pi` is a development instrument for comparing A1 against pinned Pi. Prerelease builds — what `a1 update --develop` or `a1 update --develop <number>` installs — expose it. A release build does not recognize the launch form. Repository development can run the comparison directly with `npm start:pi`.
 
-There is no `a1 agent` command. The former `a1 ui` subcommand is removed. Unsupported commands return quietly without selecting another runtime. Bare `a1` is the owned agent product surface and remains the entry point when multi-agent UX is introduced.
+There is no `a1 agent` command. The former `a1 ui` subcommand is removed. Unsupported commands return quietly without selecting another runtime. Bare `a1` is the normal A1 product surface.
 
 ## First launch
 
@@ -42,7 +45,7 @@ a1 --session-dir '/path/to/session store' --session <id>
 
 `--session` also accepts a `.jsonl` file path; `--session-dir` may come before or after it. Explicit storage overrides `PI_CODING_AGENT_SESSION_DIR`, which overrides default storage. IDs are searched in the current project before other projects within the A1 store. A cross-project ID match asks before creating a fork with a new identity; an explicit file resumes directly using its stored working directory. Missing or invalid targets fail rather than create an empty replacement.
 
-Resume uses the shipped Pi's public restoration behavior, including the compaction format it writes. It sends no model prompt by itself and does not recover, convert, or modify an unrelated conversation. Bare `a1` remains a fresh launch. Pi picker/continue CLI aliases and `a1 pi --session` are not supported by this repair; in-UI `/resume` is unchanged.
+Resume uses the shipped Pi's public restoration behavior, including the compaction format it writes. It sends no model prompt by itself and does not recover, convert, or modify an unrelated conversation. The selected session opens in a new A1 tab or focuses the tab already holding it. Pi picker/continue CLI aliases, `a1 solo --session`, and `a1 pi --session` are not supported; in-UI `/resume` is unchanged.
 
 Regression evidence creates disposable sessions through Pi 0.84.2, then executes the emitted command through the packed public entry, bootstrap, guardian, and owned UI. Default/custom storage, Windows Git Bash quoting, supervisor restart, failure cleanup, and simultaneous distinct selections are covered in `test/foundation/release/session-resume.integration.test.ts`. CI runs it in the resource-sensitive `package-smoke` scope, not the fast remainder. Unsupported synthetic retained-tail certification is separate deferred work.
 
@@ -52,14 +55,14 @@ Regression evidence creates disposable sessions through Pi 0.84.2, then executes
 
 ## Terminal behavior
 
-Both launch forms run the A1-owned full-viewport TUI over pinned Pi engine, component, and terminal APIs. A1 owns composition, input routing, modal focus, selection behavior, scrolling, and restoration without inserting a PTY or terminal-byte relay. Bare `a1` enables A1-owned screens; `a1 pi` uses the same pipeline with those screens withheld.
+All interactive launch forms run the A1-owned full-viewport TUI over pinned Pi engine, component, and terminal APIs. Bare `a1` attaches to the native resident host; each tab runs the owned UI in a holder-owned pseudoterminal, while Node never relays or renders terminal bytes. `a1 solo` uses the direct owned path without resident infrastructure. `a1 pi` uses that same direct pipeline with A1-specific screens withheld.
 
 ## Concurrent instance lifecycle
 
-Every invocation receives a unique non-detachable launch instance. There is no product-wide foreground slot: the same profile or both profiles may run concurrently in separate terminals. Profile files remain shared according to the selected profile root, while process ownership, lifecycle outcome, and cleanup remain scoped to the command that launched them.
+Each `a1 solo` or `a1 pi` invocation receives a unique non-detachable launch instance. Normal A1 clients instead attach to the profile's tab set, which can be viewed from concurrent terminals with explicit input-controller transfer. Profile files remain shared according to the selected profile root.
 
-Normal root exit, terminal closure, guardian failure, and verified update shutdown all close the instance's remaining process tree within bounded graceful and forced deadlines. Closing one instance never closes another. A control supervisor may remain idle afterward, but closed instances leave no UI, Pi, extension daemon, agent worker, tool, or descendant process.
+Normal exit or terminal closure tears down a solo/comparison launch instance within bounded graceful and forced deadlines. Closing or detaching a normal A1 client leaves its tabs running; a tab and its process tree stop only when the user explicitly closes that tab.
 
 ## Recovery and comparison
 
-If bare `a1` cannot start or a UI workflow diverges, run `a1 pi` from the same working directory and compare the behavior. Profile data is intentionally separate, so authentication or settings may need to be configured independently. Use `a1 --version` to record the installed A1 release before reporting a difference.
+If A1's normal mode cannot start, bare `a1` falls back to the direct path with one notice. To start single agent mode explicitly, run `a1 solo` from the same working directory. To compare against the pinned Pi profile, run `a1 pi`; its profile data is intentionally separate, so authentication or settings may need independent configuration. Use `a1 --version` to record the installed A1 release before reporting a difference.

package/docs/features/prompt-history.md

@@ -1,7 +1,8 @@
 # Persistent prompt history
 
-Bare A1 recalls recent prompts across sessions and projects within the same A1
-profile. It is input recall, not conversation recovery or agent memory. The Pi
+Bare A1 recalls recent prompts within each agent session, including when that
+session resumes. The optional Shared scope recalls prompts across agent sessions
+and projects in the same A1 profile. It is input recall, not conversation recovery or agent memory. The Pi
 comparison (`a1 pi`) retains its ordinary current-session history.
 
 ## Recall
@@ -36,16 +37,21 @@ imported automatically.
 
 | Platform | Default durable location |
 |---|---|
-| Windows | `%USERPROFILE%/.a1/data/history/<profile-id>.sqlite3` |
-| Linux and macOS | `~/.a1/data/history/<profile-id>.sqlite3` |
-| Explicit override | `<A1_DATA_DIR>/history/<profile-id>.sqlite3` |
+| Windows | `%USERPROFILE%/.a1/data/history/<history-id>.sqlite3` |
+| Linux and macOS | `~/.a1/data/history/<history-id>.sqlite3` |
+| Explicit override | `<A1_DATA_DIR>/history/<history-id>.sqlite3` |
 
 The default uses A1's effective profile home: `A1_PROFILE_HOME` when set, otherwise
 the operating-system home. A custom agent-profile directory changes the history
 identity, not this default root. `A1_DATA_DIR` takes precedence for storage;
 `XDG_DATA_HOME` does not redirect default history. Control metadata, settings,
 agent resources, releases, logs, runtime files, and caches keep their existing
-locations.
+locations. For repository-local `./scripts/dev` launches, history uses a stable
+checkout-wide data root so two independent solo instances share the selected
+Shared database, while control and runtime data remain isolated per launch.
+The development-only `A1_DEV_HISTORY_DATA_DIR` selects that root; an explicit
+`A1_DATA_DIR` still overrides its launcher default. Existing histories in old
+per-instance development roots are not moved or combined.
 
 **The home-based default starts fresh.** Previous versions used
 `%LOCALAPPDATA%/a1/history` on Windows, or `$XDG_DATA_HOME/a1/history` /
@@ -53,12 +59,15 @@ locations.
 fall back to those stores. Explicit `A1_DATA_DIR` selections still work normally.
 Old and new releases using different roots do not synchronize history.
 
-The profile filename is `a1-` followed by a SHA-256 digest of a versioned tuple
-containing the launch kind and normalized effective agent-profile path. It is
-independent of project, session, checkout, and release. Windows ordinary case and
-separator variants normalize together. Different profile roots use different
-files. Moving a profile, unresolved symlink aliases, or selecting a different
-data root can select a different history; A1 never silently merges or imports it.
+In Shared mode the filename is the original `a1-` SHA-256 profile identity,
+independent of project, session, checkout, and release. In Unique mode (the
+default), a domain-separated digest also includes the stable conversation session
+ID; two solo launches or resident tabs therefore use different databases and
+image sidecars. Resuming the same session reuses its store; starting or forking a
+session selects a different one. Windows ordinary case and separator variants
+normalize together. Moving a profile, unresolved symlink aliases, or selecting a
+different data root can select a different history; A1 never silently merges or
+imports it.
 
 The database is separate from `control.sqlite3`, agent resources, and disposable
 caches. Upgrades, ordinary npm uninstall/reinstall, release rollback, cache cleanup,
@@ -79,11 +88,19 @@ must not appear in history diagnostics or test evidence.
 The History section in `/settings` provides:
 
 - **Persistent history:** on by default; applies on the next start. Off disables
-  storage and cross-session recall for subsequent launches, not current-session
+  storage and durable recall for subsequent launches, not current-session
   recovery. Existing enabled instances keep running until closed.
+- **History scope:** Unique (default) keeps each agent session's durable prompts
+  separate across solo launches and resident tabs. Shared restores the former
+  profile-wide store. Switching applies to running agents, including other solo
+  processes and resident tabs, when their shared settings update arrives. New
+  prompts use the newly selected store; already-submitted writes finish in their
+  original store. Switching never transfers or deletes records, and it preserves
+  unsent drafts. Existing profiles without this setting default to Unique, so
+  old Shared entries remain intact but do not appear until Shared is selected.
 - **History limit:** 10-100 in increments of 10, default 100; applies when a new
-  enabled instance starts. All writers then use that profile store's updated
-  retention limit. Raising the limit cannot restore pruned entries.
+  enabled instance starts. All writers using that selected store then use its
+  updated retention limit. Raising the limit cannot restore pruned entries.
 
 The settings use A1's existing settings document, not Pi's settings or a separate
 history configuration file. Disabling persistence does not delete saved data;
@@ -134,14 +151,18 @@ placed beside history. For a history-only review, `NODE_DISABLE_COMPILE_CACHE=1`
 also avoids creating compile-cache files under that explicitly overridden root.
 The focused path/composition tests cover normal no-override selection. Test:
 
-1. Submit two text prompts and one repeated prompt; start `/new`, then restart.
-   The latest unique prompts remain recallable.
+1. Submit two text prompts and one repeated prompt; resume the same session
+   after restart and check those prompts remain recallable. Start `/new` and
+   confirm its durable history is separate.
 2. Browse multiline input with a draft present. Check v2 caret placement,
    newest/oldest numbering, and draft restoration.
-3. Submit from a second instance while the first browses. The first selection
-   stays fixed; the update appears on a later safe browse cycle.
+3. Submit from a second instance while the first browses. Under Unique, the
+   first sees no cross-agent update. Switch to Shared without restarting; once
+   both agents apply the setting, the second instance's new prompt appears in
+   the first agent's shared history. Switching back restores each Unique store.
 4. Recall pasted text after restart; image tokens must not promise reattachment.
-5. Save both History settings, restart, and verify effective values and opt-out.
+5. Save History scope and verify its immediate effective value. Restart only
+   for changes to Persistent history or History limit.
 6. Use a second isolated effective profile and verify no sharing. Run
    `./scripts/dev pi` and verify its ordinary history/editor remain unchanged.
 

package/docs/manual-resident-tabs-acceptance.md

@@ -0,0 +1,51 @@
+# Resident tabs physical acceptance
+
+This checklist certifies resident tabs on one platform against one published candidate package. Automated suites (simulation, crash points, fuzzing, the `resident-chaos` group, and exact-package tests) are required first; this checklist covers what only a real terminal, a real remote session, and a real operating system can show.
+
+## Rules
+
+- Install the exact published candidate with `a1 update --develop <version>` and record its version and the SHA-256 of `dist/native/<platform>-<arch>/terminal-host[.exe]` from its `terminal-host.manifest.json`.
+- Run on a manual operator machine or an isolated disposable worker. Physical automation never runs on an active workstation.
+- Each platform is certified independently: Windows x64, Linux x64, macOS arm64, and macOS x64. Evidence is never copied from another platform or another package.
+- Record every item as `pass`, `fail`, or `pending`. A platform is `CI-verified` while any item is `pending` or `fail`, and `certified` only when every item passes.
+- Do not paste prompts, terminal content, session files, or credentials into a record. Describe what was observed.
+
+## Checklist
+
+| # | Item | How to check | Expected |
+|---|---|---|---|
+| 1 | Terminal close mid-turn | Start a long streaming turn in a tab, close the terminal window. Reopen a terminal and run `a1`. | The turn kept running; the tab reattaches with its retained output and the turn's result. |
+| 2 | SSH or remote-session loss | Over SSH (or the platform's remote session), start a streaming turn, then drop the connection without exiting. Reconnect and run `a1`. | Same as item 1; no tab restarted. |
+| 3 | Forced attach-client kill | Kill the attach client process from another terminal while a turn streams. | The tab keeps running; the outer terminal is restored (cursor, modes, screen); `a1` reattaches. |
+| 4 | Reattach fidelity | After items 1–3, compare the reattached screen with what the tab showed. | Scrollback, colors, wide characters, and cursor position match; nothing is replayed twice. |
+| 5 | Input and render smoothness | Type quickly, paste a large block, resize repeatedly, and run a high-rate output command. | No lost or duplicated input, no stalls, no torn frames. |
+| 6 | Extension text UI | Open an extension that draws its own text UI inside a tab. | It renders and accepts input as in `a1 solo`. |
+| 7 | Two clients and controller transfer | Attach the same tab from two terminals and type in each in turn. | Control moves to the terminal that typed; each input is attributed to one client; nothing interleaves. |
+| 8 | Server, holder, and child failure | Kill the resident server, then one holder, then one tab's A1 process, using pids from `a1 tabs host status` and `a1 tabs`. | The server is replaced without losing tabs; the holder and the A1 process restart into the session; `a1 tabs host status` counts each recovery. |
+| 9 | Sensitive-data separation | Run `a1 tabs doctor` after items 1–8 and inspect the bundle. | Logs, crash records, status, and redacted registry only; no prompts, terminal content, journals, drafts, last screens, stderr, or credentials. |
+| 10 | Conflict-safe direct rollback | With tabs running, run `a1 solo` on a session a live tab holds, then `a1 tabs host stop`. | `a1 solo` refuses or forks the held session and never writes it; `a1 tabs host stop` stops every tab and the host. |
+| 11 | Logout (Linux) | On a `systemd` session with `KillUserProcesses=yes`, log out with tabs running, log back in, run `a1`. | Tabs end at logout as documented; previous sessions stay resumable; nothing is corrupted. |
+
+## Record template
+
+Each platform record lives at `docs/architecture/evidence/resident-tabs/<platform>.md`.
+
+```markdown
+# Resident tabs acceptance: <platform>
+
+State: CI-verified | certified
+
+| Field | Value |
+|---|---|
+| Package version | |
+| terminal-host SHA-256 | |
+| OS build | |
+| Terminal | |
+| Operator or worker | |
+| Date | |
+
+| # | Item | Verdict | Notes |
+|---|---|---|---|
+| 1 | Terminal close mid-turn | pending | |
+...
+```