@timurproko/a1 0.1.0

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

@@ -0,0 +1,69 @@
+# 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.
+
+## 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-compatible candidate; notice must be vendored before packaging |
+
+A buffered AddOne-owned frame composer is the initial presentation layer. Ratatui is an optional evaluation candidate only if the narrow composer increases rendering risk; it is not selected by default.
+
+## 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 AddOne 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;
+- 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;
+- AddOne 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.

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

@@ -0,0 +1,39 @@
+# In-terminal 2×2 spike evidence
+
+The spike must produce machine-readable evidence with schema `addone-native-host-spike-evidence-v1`. Evidence is valid only when it names the exact artifact, hashes, pinned source commits, isolated worker environment, all mandatory workloads, measurements, paint diagnostics, resources, and physical/manual verdict. The artifact is a console terminal host that runs inside an existing terminal and does not open a desktop window.
+
+## 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 is `assertNativeSpikeEvidence` in `src/foundation/native-host-protocol/evidence.ts`.
+
+A failed or incomplete proof stops composed-terminal integration and must not be waived to merge.

package/docs/architecture/toolchain.md

@@ -0,0 +1,66 @@
+# Toolchain and release contract
+
+Exact package versions are recorded in `package-lock.json`.
+
+## Runtime and build
+
+| Component | Contract |
+|---|---|
+| Node.js | `>=22.19.0 <25` |
+| Package manager | npm 11, lockfile v3 |
+| Language | TypeScript, strict native ESM, `NodeNext`, ES2023 |
+| Control storage | Built-in `node:sqlite` `DatabaseSync`, WAL mode |
+| Process/version helpers | `cross-spawn`, `semver` |
+| Tests | Vitest |
+
+The repository has one root package manifest, lockfile, dependency tree, TypeScript configuration, and test configuration. Feature folders must not introduce nested package installations or generated runtime state.
+
+## Platform policy
+
+Transparent launch uses inherited native terminal/process facilities on Windows, Linux, and macOS. The architecture is platform-neutral, but stable parity/support claims are platform-specific and require deferred physical certification against exact package bytes. An uncertified `next` preview is not evidence of stable cross-platform support.
+
+Physical desktop automation is absent from the active repository baseline. Any future implementation must run only on dedicated disposable workers or VMs with exclusive interactive desktops and exact process ownership.
+
+## Package contents
+
+The published package contains:
+
+- the sole public `a1` command;
+- the internal supervisor entry;
+- immutable release/bootstrap, lifecycle, protocol, storage, update, and transparent-launch modules;
+- 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.
+
+## Gates
+
+```sh
+npm run build
+npm run typecheck
+npm run check:architecture
+npm run check:deprecated
+npm test
+npm run test:release
+```
+
+`check:deprecated` verifies the complete lockfile graph against registry metadata. The release gate exercises durable stable/preview update transitions and writes an ignored machine-readable verdict under `artifacts/release-verdicts/`.
+
+## Preview publication
+
+A preview candidate must use a unique `-dev.N` version and exact manually accepted bytes. Publication packs once, binds evidence to source commit/version/integrity, runs applicable non-desktop gates, publishes under npm `next`, and verifies registry identity. It must keep `latest` unchanged and record physical/cross-platform certification as deferred.
+
+The GitHub trusted-publishing workflow is `.github/workflows/publish-next.yml`. Stable publication remains a separate release process from a clean tagged `master` commit after all mandatory platform gates pass.
+
+## AddOne state paths
+
+These paths are AddOne control and release state, not Pi profile roots. All are overrideable for hermetic tests.
+
+| Purpose | Override | Windows default | Unix default |
+|---|---|---|---|
+| Config | `ADDONE_CONFIG_DIR` | `%APPDATA%\\AddOne` | `$XDG_CONFIG_HOME/addone` or `~/.config/addone` |
+| Durable data | `ADDONE_DATA_DIR` | `%LOCALAPPDATA%\\AddOne` | `$XDG_DATA_HOME/addone` or `~/.local/share/addone` |
+| Runtime | `ADDONE_RUNTIME_DIR` | `%LOCALAPPDATA%\\AddOne\\runtime` | `$XDG_RUNTIME_DIR/addone` or `<data>/runtime` |
+| Database | `ADDONE_DATABASE_PATH` | `<data>/control.sqlite3` | `<data>/control.sqlite3` |
+| Endpoint | `ADDONE_ENDPOINT` | runtime-scoped named pipe | `<runtime>/supervisor.sock` |
+
+The launch-profile feature separately owns Pi roots: `~/.a1/agent`, ordinary `~/.pi/agent`, and `~/.a1/sandbox`.

package/docs/features/launch-profiles.md

@@ -0,0 +1,50 @@
+# Launch profiles
+
+`a1` is the sole installed command name.
+
+| Command | Purpose | Pi user profile |
+|---|---|---|
+| `a1` | AddOne-owned Pi-compatible UI | `~/.a1/agent` |
+| `a1 pi` | Untouched vanilla Pi fallback and comparison oracle | ordinary `~/.pi/agent` |
+| `a1 sandbox` | Unchanged isolated vanilla Pi profile for experiments | `~/.a1/sandbox` |
+
+There is no `a1 agent` command. The former `a1 ui` subcommand is removed. Bare `a1` is the owned agent product surface and remains the entry point when multi-agent UX is introduced.
+
+## First launch
+
+For AddOne-owned profiles, AddOne creates only the selected profile root and empty `extensions`, `skills`, `prompts`, and `themes` directories. Existing content is preserved. AddOne does not copy, link, merge, or delete settings, credentials, sessions, packages, trust decisions, or resources from another profile.
+
+Pi owns files within the selected root. Common locations are:
+
+```text
+settings.json
+trust.json
+sessions/
+extensions/
+skills/
+prompts/
+themes/
+npm/
+```
+
+Run Pi’s normal `/login` independently in each profile that needs stored authentication. Provider credentials supplied through supported environment variables remain available to Pi, but profile authentication files never fall back to another root automatically.
+
+## Vanilla Pi
+
+`a1 pi` bypasses the AddOne-owned UI and launches the untouched pinned Pi CLI. It also removes AddOne’s Pi configuration-root override, so Pi uses its normal `~/.pi/agent` settings, authentication, sessions, resources, packages, and trust decisions. This is both the comparison oracle and the recovery fallback when diagnosing the owned UI.
+
+## Sandbox profile
+
+`a1 sandbox` remains a direct vanilla Pi launch. It uses `~/.a1/sandbox` and starts Pi with its supported one-run `--no-approve` trust override. Project-local executable settings and resources are ignored for that run; sandbox-owned resources still load from the selected user profile.
+
+“Sandbox” means Pi profile and executable-resource isolation. It is **not** an operating-system security boundary. It does not restrict filesystem access, processes, network access, environment credentials, shell tools, or commands executed by Pi.
+
+## Terminal behavior
+
+Bare `a1` runs the AddOne-owned full-viewport TUI over public Pi engine, component, and terminal APIs. AddOne owns composition, input routing, modal focus, selection behavior, scrolling, and restoration without inserting a PTY or terminal-byte relay. Its default presentation is pinned to vanilla Pi parity; structured tabs and AddOne-specific visual customization are not enabled.
+
+`a1 pi` and `a1 sandbox` retain transparent direct attachment. In those profiles, one untouched Pi process and the physical terminal own rendering, input, selection, clipboard, scrollback, and terminal modes; AddOne owns foreground lease and lifecycle only.
+
+## Recovery and comparison
+
+If bare `a1` cannot start or a UI workflow diverges, run `a1 pi` from the same working directory and compare the behavior. Profile data is intentionally separate, so authentication or settings may need to be configured independently. Use `a1 version` to record the installed AddOne release before reporting a difference. `a1 sandbox` is for isolated profile experiments, not recovery from the owned UI and not a security boundary.

package/docs/manual-transparent-checkpoint.md

@@ -0,0 +1,53 @@
+# Manual owned-UI and transparent fallback checkpoint
+
+This checkpoint is user-controlled. Tests and coding agents must not launch or focus a terminal, inject desktop input, resize windows, close applications, or clean up workstation processes.
+
+## Prepare an exact candidate
+
+From the candidate checkout, pack once and install that tarball into a disposable prefix:
+
+```powershell
+npm ci
+npm run build
+npm pack --ignore-scripts --pack-destination artifacts/manual-transparent
+npm install --prefix artifacts/manual-transparent/install --ignore-scripts artifacts/manual-transparent/<exact-tarball>.tgz
+```
+
+Use isolated AddOne control state:
+
+```powershell
+$manualRoot = (Resolve-Path "artifacts/manual-transparent").Path
+$env:ADDONE_CONFIG_DIR = "$manualRoot\state\config"
+$env:ADDONE_DATA_DIR = "$manualRoot\state\data"
+$env:ADDONE_RUNTIME_DIR = "$manualRoot\state\runtime"
+$env:ADDONE_DATABASE_PATH = "$manualRoot\state\data\control.sqlite3"
+```
+
+Run the installed candidate yourself:
+
+```powershell
+& "artifacts/manual-transparent/install/node_modules/.bin/addone.cmd"
+```
+
+Test each installed launch form separately: bare `a1` (the owned UI), `a1 pi` (the untouched comparison oracle), and `a1 sandbox` (the unchanged isolated vanilla profile). Confirm that files created through `/settings`, `/login`, sessions, and resource directories remain under the selected profile root. Generic transparent-fallback testing may set `ADDONE_TERMINAL_EXECUTABLE` and a JSON array in `ADDONE_TERMINAL_ARGUMENTS_JSON`.
+
+Physical automation is not part of this repository baseline. Future certification tooling may run only on dedicated disposable workers or VMs with exclusive test desktops, never on this workstation.
+
+## Compare bare AddOne with `a1 pi`
+
+Use the same terminal, working directory, dimensions, environment, and equivalent profile resources. Bare AddOne and the untouched oracle intentionally use separate profile roots.
+
+- [ ] Startup resources, logo, notices, spacing, editor, and footer match.
+- [ ] Text, Unicode, emoji, styles, cursor, and layout match.
+- [ ] Rapid typing has no visible AddOne delay or dropped/duplicated characters.
+- [ ] Ctrl+C, Ctrl+P, arrows, paste, focus, dialogs, mouse, and wheel match.
+- [ ] Selection, copy, clipboard, scrollback, and resize match.
+- [ ] Normal and error exits preserve child output and return a usable parent prompt.
+- [ ] Parent typing, cursor movement, Backspace, Delete, and submission work after exit.
+- [ ] A missing executable reports a concise spawn failure without affecting other applications.
+
+Report failures with direct-versus-AddOne behavior, platform/terminal versions, exact command, reproducibility, and optional manually captured evidence.
+
+For recovery, use `a1 pi`; do not use the removed `a1 ui` command. `a1 sandbox` remains profile isolation rather than a security boundary.
+
+Manual acceptance can authorize an exact uncertified npm `next` preview after non-desktop gates pass. It does not certify stable terminal parity or platform support.

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@timurproko/a1",
+  "version": "0.1.0",
+  "description": "Standalone terminal workspace for supervised native and managed agents",
+  "type": "module",
+  "packageManager": "npm@11.13.0",
+  "bin": {
+    "a1": "bin/addone.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "README.md",
+    "LICENSE",
+    "docs"
+  ],
+  "engines": {
+    "node": ">=22.19.0 <25"
+  },
+  "scripts": {
+    "clean": "node scripts/clean.mjs",
+    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "check:architecture": "node scripts/check-architecture.mjs && node scripts/check-package-identity.mjs && node scripts/check-pinned-pi-source-ledger.mjs && node scripts/check-terminal-host-provenance.mjs",
+    "check:customization-ready": "node scripts/check-owned-ui-customization-prerequisites.mjs",
+    "check:deprecated": "node scripts/check-deprecated-dependencies.mjs",
+    "check": "npm run typecheck && npm run check:architecture && npm run check:customization-ready && npm run check:deprecated && npm test && npm run test:release",
+    "validate:agent": "npm run check",
+    "publish:next": "tsx scripts/publish-next.ts",
+    "test": "vitest run",
+    "test:unit": "vitest run test/cli test/features test/foundation test/repository-governance --exclude '**/*.integration.test.ts'",
+    "test:integration": "vitest run test/foundation/release/update-transition.integration.test.ts test/features/launch/profile-isolation.integration.test.ts",
+    "test:release": "node scripts/run-release-gates.mjs",
+    "test:terminal-host": "node scripts/run-terminal-host-probe.mjs",
+    "test:pi-terminal-parity": "npm run build --silent && node scripts/run-pi-terminal-parity.mjs",
+    "update:pi-component-parity": "tsx scripts/update-pi-component-parity.ts",
+    "update:pi-event-frame-parity": "tsx scripts/update-pi-event-frame-parity.ts",
+    "proof:terminal-host": "node scripts/run-terminal-host.mjs",
+    "start": "npm run build && node scripts/start-local.mjs",
+    "prepack": "node scripts/prepack-gate.mjs",
+    "prepublishOnly": "npm run check",
+    "prepare": "npm run build"
+  },
+  "dependencies": {
+    "@earendil-works/pi-coding-agent": "0.84.2",
+    "@earendil-works/pi-tui": "0.84.2",
+    "cross-spawn": "7.0.6",
+    "grok-mermaid": "0.2.2",
+    "semver": "7.8.5"
+  },
+  "devDependencies": {
+    "@types/cross-spawn": "6.0.6",
+    "@types/node": "24.2.1",
+    "@types/semver": "7.8.0",
+    "@xterm/headless": "6.0.0",
+    "node-pty": "1.1.0",
+    "tsx": "4.20.3",
+    "typescript": "5.9.2",
+    "vitest": "3.2.7"
+  },
+  "keywords": [
+    "cli",
+    "tui",
+    "terminal",
+    "multiplexer",
+    "agents"
+  ],
+  "author": "Timur Prokopiev",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}