@timurproko/a1 0.2.7-dev.1249 → 0.2.7-dev.1255

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

@@ -1,34 +0,0 @@
-# In-terminal 2×2 proof gate
-
-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:
-
-1. Every mandatory workload in the terminal-host evidence schema passes.
-2. The proof runs inside an existing terminal without creating a desktop window.
-3. The exact artifact is tied to pinned A1 and terminal-component revisions.
-4. Automated evidence came from an isolated worker.
-5. The physical verdict is `accepted` through user-controlled manual validation or an attested isolated disposable worker.
-6. Input-to-process p95 latency is at most 16 ms.
-7. Output-to-present p95 latency is at most 33 ms.
-8. Missed frames are zero.
-9. Resize paint gaps are zero.
-10. No active-workstation terminal automation occurred.
-11. The recorded evidence schema validates without contradictory summaries.
-
-## Stop criteria
-
-Any failed, missing, incomplete, contradictory, physically unverified, or threshold-exceeding result is `stop`. A `stop` result:
-
-- forbids production composed-terminal integration;
-- forbids milestone merge for composed-terminal work;
-- cannot be waived by changing thresholds after evidence collection;
-- preserves structured-agent and transparent-mode work as independently usable;
-- stops composed-terminal work instead of starting a custom rendering/input remediation loop;
-- prevents investment in a postponed desktop-native application shell.
-
-The executable decision was `evaluateNativeSpikeGate` in `src/foundation/native-host-protocol/proof-gate.ts`, preserved in `develop` history at commit `243eb7a7`. The acceptance record is `docs/architecture/evidence/terminal-host-spike/terminal-spike-acceptance-record.json`. It stays pending: the owning plan was retired on 2026-10-10 without a physical verdict, and `add-persistent-multi-agent-tabs` defines its own certification rather than reusing this gate.

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

@@ -1,81 +0,0 @@
-# Terminal-host provenance
-
-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
-
-| Component | Source identity | Role | License |
-|---|---|---|---|
-| `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; 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.
-
-## Explicitly excluded
-
-The in-terminal proof does not use:
-
-- the Ghostty desktop application;
-- Winghostty's Win32 runtime;
-- OpenGL/WGL;
-- Metal;
-- GTK;
-- AppKit;
-- Herdr;
-- a Node terminal parser or renderer;
-- a new lightweight ANSI parser.
-
-A desktop-native application can be reconsidered only after the terminal-hosted product proves rendering and input quality.
-
-## Patch policy
-
-Retain upstream terminal behavior without local patches by default. Any behavioral patch must record:
-
-- source and target revisions;
-- reason;
-- regression tests;
-- upstream synchronization decision;
-- license impact.
-
-Do not patch terminal semantics to support a specific CLI. Report unsupported generic behavior through capability negotiation instead.
-
-## Build prerequisites
-
-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, 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.
-
-No GUI SDK, OpenGL runtime, Win32 window pipeline, Metal, GTK, or AppKit runtime is required for the in-terminal host.
-
-## Reproducible artifact manifest
-
-Every spike or production host artifact must record:
-
-- artifact path, SHA-256, size, signature status, and build timestamp;
-- A1 source commit and protocol version;
-- `libghostty-vt`, PTY, input, and renderer component identities;
-- retained/adapted component manifest;
-- compiler/toolchain versions and target triple;
-- license and notice hashes;
-- build command, dependency cache provenance, and clean-source-tree result;
-- 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/terminal-host-spike-evidence.md

@@ -1,39 +0,0 @@
-# In-terminal 2×2 spike evidence
-
-The spike must produce machine-readable evidence with schema `a1-native-host-spike-evidence-v1`. Evidence is valid only when it names the exact artifact, hashes, pinned source commits, isolated worker environment, all mandatory workloads, measurements, paint diagnostics, resources, and physical/manual verdict. The artifact is a console terminal host that runs inside an existing terminal and does not open a desktop window.
-
-## Mandatory workloads
-
-1. `four-concurrent-sessions` — one fullscreen surface, one tab, four independent terminal sessions.
-2. `input-routing` — rapid focus and key/text routing with no cross-pane delivery.
-3. `unicode-cursor-modes` — Unicode width, cursor, and mode behavior.
-4. `alternate-screen` — full-screen and alternate-screen programs.
-5. `paste` — bounded bracketed and plain paste behavior.
-6. `mouse` — pointer and wheel reporting within pane coordinates.
-7. `ime` — composition, preedit, commit, and cancellation where the outer terminal supports it.
-8. `live-resize` — active terminal resize and settle repaint.
-9. `dpi` — terminal font/content-scale changes represented to the host when supported.
-10. `high-rate-output` — simultaneous output in all four panes.
-11. `pane-abnormal-exit` — one pane fails while three remain isolated.
-12. `host-cleanup` — normal and abnormal host termination clean all owned resources and restore the outer terminal.
-
-## Measurements
-
-Latency summaries require minimum, p50, p95, maximum, and sample count:
-
-- `inputToProcessMs`: outer-terminal input acceptance to child process write.
-- `outputToPresentMs`: child output read to presented outer-terminal frame.
-
-Paint diagnostics require requested, presented, coalesced, and missed frame counts plus resize paint-gap count. Resource observations require maximum CPU and resident memory; GPU memory may be null because the console host does not require a GPU renderer.
-
-## Acceptance invariants
-
-- All workloads must pass for `technical: passed`.
-- Any failed workload forces `technical: failed`.
-- Any missing or `not-run` workload forces `technical: incomplete`.
-- `overall: accepted` requires technical acceptance and a physical verdict accepted through `manual` or `isolated-worker` evidence.
-- Active-workstation automation makes the evidence invalid.
-- Evidence must not contain terminal output, child input streams, rendered cells, cell grids, framebuffers, screen buffers, or raw terminal payloads.
-- The evidence validator was `assertNativeSpikeEvidence` in `src/foundation/native-host-protocol/evidence.ts`, preserved in `develop` history at commit `243eb7a7`. The plan that owned this spike was retired on 2026-10-10.
-
-A failed or incomplete proof stops composed-terminal integration and must not be waived to merge.

package/docs/launch-recovery.md

@@ -1,23 +0,0 @@
-# Startup recovery after process termination
-
-A1 reconciles recoverable runtime ownership automatically when the user starts it again after a process crash or forced termination. Users should not need to find PIDs, delete session or control databases, restart a supervisor, or reboot to clear a stale record.
-
-## Recovery boundary
-
-Supervisor metadata carries an additive native process-creation token. Endpoint handshakes still use the existing supervisor, boot, release, and opaque start-identity fields for compatibility; new supervisors use their native token in that start field as well. A failed probe is retried; native process inspection distinguishes a terminated process object or reused PID from the recorded owner. Older records remain readable: an absent process is reclaimable, while a live legacy PID is not treated as dead merely because its timestamp format differs. Windows and macOS native creation times strictly later than a legacy publication, with a one-second margin, can disprove that recorded ownership. Tick-only Linux legacy evidence remains conservative until absence or a matching handshake establishes the outcome.
-
-Endpoint retirement requires the same publication and a fresh dead-owner observation under a native file-descriptor gate. The gate is never deleted; the OS releases its lock on exit, including forced exit. Supervisor binding, Unix stale-socket removal, metadata publication, and closure use that gate. Losing startups cannot delete the winner's endpoint. A separate shared-database gate serializes boot reconciliation and publication across cohorts. Only the bound winner reconciles old rows, and recorded surviving cohort boots remain protected.
-
-Successful recovery is silent and continues the original profile, launch mode, and session selection. Saved sessions are not deleted or rewritten by endpoint recovery. Resident holders and their session-writer locks retain their independent ownership; restarting a supervisor is not permission to stop a resident tab or create a second session writer.
-
-## Exceptional failures
-
-An uninspectable or genuinely unresponsive live owner is preserved after bounded retries. Empty saved instance lists are not authority to terminate it. The command returns a short recovery message instead of an uncaught stack or the old internal uncertain-live-ownership paragraph. Missing native recovery support or inaccessible runtime storage remains an installation or permission failure, not proof that an owner is dead.
-
-A recovery attempt may replace one bounded `<endpoint-metadata>.recovery.json` summary containing only a reason, attempt count, and timestamp. It is diagnostic only, contains no session data or credentials, and never grants cleanup authority. The `.authority` gate files are also not user cleanup targets.
-
-This restores launch availability, not killed process memory. Killing every Node process also kills the terminal-restoration watcher; no alternative executable is started to evade that limitation. Real OS permission failures, damaged installations, and persistently live unresponsive services cannot be converted into safe success by ignoring ownership.
-
-## Regression boundaries
-
-The focused fixtures use isolated runtime/data roots and recorded fixture process identities. They cover supervisor, guardian, root-runtime, recovery-gate, PID-reuse, concurrent-startup, and Windows all-recorded-Node loss, plus native resident server/holder/tab loss in the resident lane. They never terminate processes by image name. Another managed runtime, a separate cohort, saved session bytes, and an unrelated sentinel process establish the preservation boundaries.

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

@@ -1,43 +0,0 @@
-# Launch-instance exact-artifact acceptance
-
-Run this checklist only against a packaged candidate on a user-controlled terminal or isolated disposable Windows worker. Do not automate launching, focusing, driving, or closing terminal windows on an active workstation.
-
-## Artifact identity
-
-Record the A1 release ID, package version, source commit, candidate integrity, process-guardian target/version/protocol/integrity, platform and terminal versions, and tester attestation. The guardian values must match `dist/native/win32-x64/manifest.json` inside the exact installed candidate.
-
-## Concurrent launch matrix
-
-Open four independent terminal tabs:
-
-```text
-Terminal 1: a1
-Terminal 2: a1
-Terminal 3: a1 pi
-Terminal 4: a1 pi
-```
-
-Confirm all four become usable without a global foreground-lease error and have distinct launch-instance IDs.
-
-## Isolated closure
-
-1. Exit Terminal 3 normally. Confirm only its Pi comparison tree exits.
-2. Close Terminal 4 without exiting first. Confirm its complete process tree disappears while both bare-A1 terminals remain usable.
-3. Exit Terminal 1 after causing a fixture extension to create a child and grandchild. Confirm the complete tree disappears and Terminal 2 remains usable.
-4. Force the Terminal 2 launch guardian to fail on the isolated worker. Confirm containment removes its root and descendants and leaves unrelated fixture processes alive.
-
-Record root, child, and grandchild native identities before each close and the observed terminal outcome afterward. Do not substitute manual PID termination for failed cleanup.
-
-## Stale-state recovery
-
-Using isolated control directories, install a version-4 fixture database containing one requested or active legacy foreground lease whose former PID is dead. Run bare `a1` and confirm the invocation migrates the row to historical interrupted state and launches normally.
-
-Repeat with an ownership-uncertain fixture process. Confirm a new independent launch still starts and the uncertain unrelated process is not terminated.
-
-## Update fan-out
-
-With at least three mixed-profile instances active, run the candidate's update-shutdown fixture. Confirm every instance receives one stop intent, each complete process tree closes, and cohort replacement occurs only after all verified terminal outcomes.
-
-## Verdict
-
-Record either exact-artifact acceptance or rejection with the failed step, process identities, outcomes, and diagnostics. Acceptance applies only to the recorded package and process-guardian bytes.

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

@@ -1,51 +0,0 @@
-# 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 | |
-...
-```