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

package/docs/features/prompt-history.md

@@ -0,0 +1,149 @@
+# 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
+comparison (`a1 pi`) retains its ordinary current-session history.
+
+## Recall
+
+Use Up/Down at the editor's normal history boundaries. Up enters older prompts
+with the caret at the end; Down enters newer prompts at the beginning. Moving
+past the newest restores your draft, including its cursor and live pasted text.
+Multiline cursor movement and autocomplete keep their existing priority.
+
+The existing editor border shows `History 100/100` for the newest of 100 entries
+and `History 1/100` for the oldest. The label uses the status bar's neutral grey
+(`dim` theme role), independently of the thinking/bash colors on the input bars. Repeated prompts move forward instead of
+creating duplicates. Other instances refresh in the background; the selected
+history and its count stay fixed until you leave that browse cycle. An
+extension-provided custom editor keeps its own behavior; the default editor is
+resynchronized when restored.
+
+Ordinary prompts, steering, follow-ups, queued inputs, nonempty bash commands,
+and user-entered skill/template/extension prompt routes are eligible. Opening
+settings or session/workflow screens does not add history. Loading a transcript,
+retrying a dispatch internally, draining a queue, or displaying a suggestion does
+not create another entry. An explicit user submission is retained even if the
+provider later rejects it or the turn is interrupted.
+
+Text pastes, URL targets, and file paths remain reusable after restart. History
+keeps the user invocation before template/extension expansion, not the expanded
+request. Image-bearing prompts retain only their text; images are not reattached.
+Image-only prompts do not create saved entries. No v2, Pi, or Claude history is
+imported automatically.
+
+## Storage and privacy
+
+| 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` |
+
+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.
+
+**The home-based default starts fresh.** Previous versions used
+`%LOCALAPPDATA%/a1/history` on Windows, or `$XDG_DATA_HOME/a1/history` /
+`~/.local/share/a1/history` on Unix. A1 does not probe, import, merge, delete, or
+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.
+
+The database is separate from `control.sqlite3`, agent resources, and disposable
+caches. Upgrades, ordinary npm uninstall/reinstall, release rollback, cache cleanup,
+and conversation deletion do not clear it. Reusing saved history requires the
+same profile and history root; explicitly deleting user data still removes it.
+SQLite may keep `-wal` and `-shm` sidecars beside the database.
+
+**History is unencrypted potentially sensitive user text.** Owner permissions
+are restricted where supported; Windows uses inherited ACLs at the selected
+history directory. Review parent-directory permissions if you customize your home
+or override root. These protections do not make it safe to submit secrets.
+Credential files, image data, arbitrary environment values, assistant/tool output, and terminal
+streams are not copied into this store. Prompt content and private provenance
+must not appear in history diagnostics or test evidence.
+
+## Settings and limits
+
+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
+  recovery. Existing enabled instances keep running until closed.
+- **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.
+
+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;
+re-enabling makes compatible retained entries available again.
+
+Additional bounds protect memory and disk:
+
+- At most 1 MiB UTF-8 per persisted prompt, never silently truncated.
+- At most 8 MiB retained canonical text, evicting oldest entries even below the
+  configured count.
+- At most 32 queued/in-flight writes and 8 MiB queued text per instance.
+- Provenance: up to 8 KiB cwd and 256 bytes session identity; oversized optional
+  provenance is omitted.
+- Short off-thread transactions, a one-second lock retry window, and coalesced
+  refresh with at most one read in flight.
+- SQLite page/journal limits and a 64 MiB database/sidecar maintenance threshold;
+  text limits exclude transient SQLite overhead.
+
+Persistence failure leaves prompt execution and local recall usable. A corrupt,
+wrong-profile, or newer-schema database is preserved, not silently recreated.
+A committed entry survives restart. A hard kill before asynchronous commit can
+lose the newest queued entries. Graceful exit attempts to drain writes within
+two seconds and reports an incomplete flush without preventing exit.
+
+## Remove saved history
+
+First close **every instance using the selected profile**. Then remove only that
+profile's `.sqlite3` file and its matching `-wal` and `-shm` sidecars, if present.
+Do not delete an open database, the whole `.a1` directory, or the whole
+application-data root. Disabling the setting alone is not an erase operation.
+There is no interactive clear/export command in this release.
+
+Removing a former default store is likewise a one-time manual cleanup, not an
+application feature. Wait until you have switched to the new version and closed
+all instances using the old store; an older running version can otherwise keep
+using or recreate it. Remove only the identified old profile database and matching
+sidecars, not other profiles or either application's caches.
+
+## Manual acceptance
+
+Build the checkout, then launch it through `./scripts/dev`. Use an isolated
+`A1_DATA_DIR` for disposable history checks; keep that same directory on each
+restart and in both concurrent terminals. The development launcher always sets
+an isolated `A1_DATA_DIR`; to try the home-based location in that launcher,
+explicitly select `A1_DATA_DIR=<effective-home>/.a1/data` and keep
+`A1_DATABASE_PATH` in a separate disposable directory so control metadata is not
+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.
+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.
+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.
+6. Use a second isolated effective profile and verify no sharing. Run
+   `./scripts/dev pi` and verify its ordinary history/editor remain unchanged.
+
+Source ownership and differential editor evidence are described in
+[history-editor-provenance.md](../architecture/history-editor-provenance.md).

package/docs/local-worktree-cleanup.md

@@ -0,0 +1,128 @@
+# Local worktree cleanup after automatic archival
+
+Local cleanup completes the delivery order in [the archive runbook](openspec-archive-automation.md): implementation merge, verified manual acceptance-record **merge**, automatic OpenSpec archive **merge**, remote topic-ref deletion, then safe local cleanup. GitHub Actions never reaches into a developer machine. This command neither publishes archives nor merges PRs or deletes remote refs.
+
+The implementation is repository tooling, not part of the installed A1 product. It requires Node, Git, and GitHub read access. No product build, dependency installation, interactive UI, or OS-service provisioning is needed. It supports this repository's `origin` on github.com, via HTTPS or SSH.
+
+## Preview first
+
+From a checkout containing the reviewed tooling:
+
+```bash
+node scripts/governance/local-worktree-cleanup.mjs preview --repo D:/Git/a1
+node scripts/governance/local-worktree-cleanup.mjs status --repo D:/Git/a1
+```
+
+`--repo` is the **primary** worktree, not a task worktree. Preview reads live evidence but changes no worktrees, refs, ownership state, or retry checkpoints. Status is local-only. Existing folders are reported `unmanaged` and are never adopted by their name, missing upstream, or ancestry. Neither command enables cleanup.
+
+Remote reads use `GH_TOKEN`/`GITHUB_TOKEN`, otherwise existing `gh auth token --hostname github.com` authentication. Do not put tokens in command arguments, source files, reports, or PR comments. Missing/expired private-repository authentication blocks evidence checks.
+
+## Explicit local enablement
+
+Only after the maintainer authorizes activation, use the reviewed tool in the primary/stable checkout outside `.worktrees/`:
+
+```bash
+node scripts/governance/local-worktree-cleanup.mjs enable --repo D:/Git/a1
+node scripts/governance/local-worktree-cleanup.mjs once --repo D:/Git/a1
+```
+
+`enable` only records permission; it does not start a process or remove anything. `once` evaluates at most one bounded pass. Mutation commands `once` and `watch` refuse tooling loaded from inside the target repository's removable root. For pre-merge isolated tests, the test repository is a separate disposable temporary repository, not the working repository itself.
+
+For eventual cleanup after asynchronous archive integration, run watch mode in a separate terminal or an explicitly managed local process:
+
+```bash
+node scripts/governance/local-worktree-cleanup.mjs watch --repo D:/Git/a1
+```
+
+It runs one immediate pass and retries at five-minute intervals, with rate-limit backoff and no overlapping mutations. Each pass is bounded to 100 registration evaluations, 500 remote requests, and 60 seconds; individual subprocess/remote calls have a 10-second deadline. Local content traversal is additionally bounded to 20,000 entries; insufficient inspection never grants deletion authority. Reports identify incomplete coverage. A durable round-robin cursor lets later pending candidates run on subsequent passes.
+
+When the process is stopped or the machine is offline, GitHub cannot remove local folders. The next enabled invocation rechecks the queue and live evidence. No implicit service, scheduled task, or A1/Pi startup hook is installed.
+
+## Register and release only work you own
+
+Keep an owner token private for the delivery session. For example, in Git Bash:
+
+```bash
+export LOCAL_CLEANUP_OWNER_TOKEN="$(node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("hex"))')"
+```
+
+Register after the draft PR number is known, using actual PR numbers and canonical paths. The following example deliberately requires replacing `123` and `example-task`:
+
+```bash
+node scripts/governance/local-worktree-cleanup.mjs register --repo D:/Git/a1 --path D:/Git/a1/.worktrees/example-task --change example-change --source-pr 123 --candidate-pr 123 --role implementation
+```
+
+Registration binds the repository, exact directory/filesystem identity, candidate PR, HEAD/ref, role, and generation. It returns an ID and generation, not the owner token. The worktree stays `owned`: registration alone never authorizes removal. Supported roles:
+
+- `implementation`: exact merged implementation PR head; candidate PR equals source PR.
+- `acceptance`: exact verified implementation merge commit; candidate PR equals source PR.
+- `archive`: exact merged generated archive PR head; candidate PR is the archive PR and source PR is the implementation PR.
+
+A CI/base/older-ancestor checkout does not qualify automatically. No local archive checkout is required when the archive was generated entirely on GitHub. Legacy version-1 implementation linkage remains supported, but individually reviewing and registering a legacy checkout is explicit adoption, not a bulk sweep.
+
+The disposable ignored-path allowlist defaults to **empty**. Only append flags such as `--disposable node_modules --disposable dist` when those exact generated directories may be discarded. This is not permission to discard tracked, staged, or untracked changes. Unknown ignored data, nested repositories/submodules, links, and special files remain blockers. Declaring a generated directory does not bypass safety or traversal bounds.
+
+Before handing a completed checkout to cleanup, stop its development processes, leave its directory, and release it using the returned ID and current generation:
+
+```bash
+node scripts/governance/local-worktree-cleanup.mjs release --repo D:/Git/a1 --id REGISTRATION_ID --generation CURRENT_GENERATION
+```
+
+Release verifies ownership and the original directory, records the owner's current final HEAD/ref, and returns a new generation. It does not declare acceptance or archival. The worker still verifies the actual merged implementation, exact legacy-comment or human-manually-merged acceptance receipt, automatic archive markers/merge/CI, current `develop` archive contents, and live absence of implementation, acceptance, and archive topic refs. An acceptance merge alone remains ineligible. A bot/automatic/merge-queue acceptance, stale record, missing acceptance-head CI, or unmatched archived receipt blocks cleanup. It will not remove an open or closed-unmerged PR's worktree.
+
+After release, request a pass from the stable checkout if cleanup is enabled. A running watcher will also pick it up. Never release another session's worktree or use a clean status/dead PID as a substitute for ownership.
+
+## Resume or recover ownership
+
+Before resuming a released worktree, acquire it:
+
+```bash
+node scripts/governance/local-worktree-cleanup.mjs claim --repo D:/Git/a1 --id REGISTRATION_ID --generation CURRENT_GENERATION
+```
+
+Use a private token for the new session. Claim, release, and cleanup share a per-repository lock. A successful claim prevents deletion until the new owner releases it. A deleting or completed candidate cannot be claimed. A path reused after completed cleanup requires a new explicit `register` operation.
+
+A session crash does not release ownership. After separately confirming that the owner and all related processes have stopped, an explicit recovery claims it for review:
+
+```bash
+node scripts/governance/local-worktree-cleanup.mjs recover --repo D:/Git/a1 --id REGISTRATION_ID --generation CURRENT_GENERATION --confirm-stopped
+```
+
+Recovery never releases or deletes. The generation must still match. A Git worktree lock remains a veto. A leftover `mutation.lock` from a crashed cleanup process also remains a veto: stop all cleanup/claim processes, inspect the lock and `state.json`, and obtain explicit approval before manually removing that identified lock. There is no automatic stale-lock eviction or PID-based deletion.
+
+## Outcomes and interruption handling
+
+State, journals, stop controls, and execution reports live in `<git-common-dir>/local-worktree-cleanup/`, outside removable checkouts. `status` omits owner-token hashes. Reports contain identities, local blockers, performed steps, and coverage, never file contents or credentials. Completed reports are retained for 30 days subject to a 10 MiB cap; unresolved queue/journal records are not evicted.
+
+- `eligible`: preview passed the gates; nothing was removed.
+- `pending`: archive/ref prerequisites have not finished.
+- `blocked`: ownership, content, path, provenance, authentication, or identity needs attention.
+- `unmanaged`: no local registration; no automatic adoption.
+- `removed`: worktree and eligible local-ref operations were verified.
+- `already-absent`: a completed journal's path/ref are still absent.
+- `partial`: a destructive step began but all cleanup could not be verified.
+- `deferred`: a bounded pass or concurrent mutation owner prevented evaluation.
+
+Non-force Git removal is the only worktree deletion operation. Local topic-ref deletion then compares the exact old SHA and refuses refs checked out elsewhere. `develop`, primary/current directories, changed heads, and active sessions are protected. Normal removal retires its own Git worktree registration; unrelated stale/missing registrations are never globally pruned.
+
+Windows file locks can leave a directory after Git removes part of a worktree. `partial` retains that residue and its journal; there is no `rm -rf`, force discard, or automatic directory-repair fallback. Stop the locking process and review the exact residual data before separately authorized manual repair. A recreated path is not the old checkout. If a prior run fully removed the worktree and only ref cleanup remains, a subsequent enabled pass rechecks evidence and safely resumes the branch-only step.
+
+Ownership is cooperative: managed sessions must claim before use. It cannot police arbitrary external editors. Remote ref checks and local deletion also are not one distributed transaction; refs are read immediately before destructive steps, and uncertain identities always block.
+
+## Disable and test
+
+Stop watch with Ctrl+C, or request immediate stop authority from another terminal:
+
+```bash
+node scripts/governance/local-worktree-cleanup.mjs disable --repo D:/Git/a1
+```
+
+Disable writes a stop sentinel without waiting for a busy mutation lock. The worker checks it before each destructive step; an already executing Git operation cannot be undone. No later deletion starts while disabled. State and partial journals remain available for review and future explicit enablement.
+
+Dependency-free focused fixtures (temporary repositories only, no live PR mutation or watcher activation):
+
+```bash
+node --test test/repository-governance/local-cleanup.node.mjs test/repository-governance/local-cleanup-evidence.node.mjs test/repository-governance/local-cleanup-watch.node.mjs
+```
+
+The Vitest bridge includes these fixtures in ordinary fast CI, whose runner is Windows. On Windows the suite exercises an actual exclusive file handle and a junction; a non-Windows run explicitly skips the Windows-only handle case rather than claiming it passed. Required current-head CI and a separately authorized live archive lifecycle remain necessary before acceptance; fixtures and preview do not replace those gates.

package/docs/manual-code-streaming-cleanup.md

@@ -0,0 +1,88 @@
+# Bounded code-streaming and hyperlink cleanup review
+
+This candidate finishes the hyperlink portion of `eliminate-code-block-streaming-flicker`
+(specification PR #318), following the partial implementation in #321. It is a prerequisite
+for `keep-streaming-ui-responsive-during-selection` (#325), not that larger change's completed
+selection/wheel performance fix.
+
+## What changed
+
+- Candidate-looking text (paths, dotted identifiers) no longer vetoes a proven followed shift.
+  Real OSC 8 links, unsafe escapes, images, overlays, and selections retain their conservative
+  movement rules.
+- Ordinary streamed text changes no longer request hyperlink cleanup.
+- Pointer transitions identify the former hovered row. Editor link deletion and discarded
+  presentation state retain explicit cleanup requests, including when replacement content
+  has no links. Unscoped cleanup considers every previously linked row; a missing pointer
+  report is not treated as proof that no host decoration exists.
+- Cleanup paints affected and changed rows without manufacturing an erase-display. After
+  unknown paint or lost geometry, it waits for a complete safe frame instead of guessing.
+- Same-geometry forced frames preserve current cells without repainting unchanged rows.
+  Structural entry, resize, and unsafe-protocol fallbacks are still conservative.
+
+## Automated evidence
+
+`test/fixtures/rendering/baseline-code-streaming.json` is the pre-production-change capture
+from `6c5af810`, repeated twice with no production diff. Its synthetic content and cell hashes
+contain no private session input. The fixture predates the added dual-synchronization summary
+field; it remains a historical baseline rather than a regenerated candidate result.
+
+| Bare-A1 fullscreen workload | Baseline post-startup clears | Candidate post-startup clears |
+| --- | ---: | ---: |
+| Streamed fenced code | 3 | 0 |
+| Path-bearing prose | 3 | 0 |
+| Tall live tail | 0 | 0 |
+
+The deterministic producers use a shared scripted clock so cold imports do not advance spinner
+or presentation timers unpredictably. Independent comparison processes remain outside the owned
+damage adapter. Current budgets also fail candidate-only fallback, repaint of settled rows,
+stale final content, or divergent final cells with synchronization honored versus ignored.
+The dual-model replay reuses producer bytes rather than launching duplicate producers.
+
+Generate current evidence (non-interactive; writes only the named report):
+
+```sh
+cd D:/Git/a1/.worktrees/finish-bounded-link-cleanup && node --import tsx scripts/pi/report-code-streaming.ts --phase current --repeat 2 --output .artifacts/rendering/code-streaming-current.json
+```
+
+The baseline mode rejects dirty production sources. Do not replace the committed baseline with
+post-fix results. Repeated reports compare cells, row damage, decisions, and budgets, not elapsed
+machine timings. This is a paint regression check, not a CPU or input-latency benchmark.
+
+## Physical Windows Terminal review
+
+Use the candidate branch `fix/bounded-hyperlink-cleanup` and record its exact `git rev-parse HEAD`.
+Build and start the owned UI through the color-preserving shell entry:
+
+```sh
+cd D:/Git/a1/.worktrees/finish-bounded-link-cleanup && npm run build && ./scripts/dev
+```
+
+1. Ask the agent, without writing files, to produce a long fenced TypeScript example containing
+   `obj.method`, `package.json`, and `./src/index.ts`, followed by a short explanation and a real
+   Markdown hyperlink. Check that ordinary code/path streaming no longer blanks the screen.
+2. Hover a real hyperlink, then scroll it away without moving the pointer. Repeat with a
+   terminal-detected URL and file-like text inside code. Try both short and wrapped links,
+   duplicate targets, blank rows replacing links, and a smaller terminal.
+3. Move off a hovered link, select linked text, wheel/auto-scroll during selection, release,
+   and copy. Check exact copied text, normal link colors/activation, and no leftover solid
+   underlines on unrelated text, padding, or controls.
+4. Paste a URL chip into the editor and delete it. Open and close a covering overlay, and resize
+   while a link is visible. Check that obsolete targets/underlines are removed and restored
+   links have their correct targets.
+5. Verify that the dock stays intact and terminal mouse/cursor behavior is restored on exit.
+
+Use the same geometry for the independent comparison profile:
+
+```sh
+cd D:/Git/a1/.worktrees/finish-bounded-link-cleanup && npm run build && ./scripts/dev pi
+```
+
+Record terminal/version, geometry, synchronized-update support, explicit versus auto-detected
+link case, commit, and pass/fail. Test both before and after any pointer report: lack of a report
+must not be interpreted as evidence of an absent pointer.
+
+**Known gaps:** native Windows Terminal hover rasterization cannot be certified by headless cell
+replay. Visual acceptance and merge authorization are pending. The broader selection/wheel
+scheduling and collapsed-tool preparation optimizations have not been implemented in this PR.
+Do not merge on automated results alone; a ghost-underline or flicker regression blocks acceptance.

package/docs/manual-ghost-link-baseline.md

@@ -0,0 +1,89 @@
+# Ghost hyperlink underline baseline
+
+## Status and scope
+
+This is the diagnostic stage of `fix-ghost-link-underlines`, accepted in specification PR #237. It does **not** repair production rendering or claim the screenshot's root cause is proven.
+
+Two executable regressions reproduce the code gaps: the damage adapter removes a requested full clear when the last visible link disappears; the viewport controller does not request cleanup when a hovered link changes bounds on the same row with the same target. Both were run as ordinary tests and failed at those exact assertions, with the other 22 controller/adapter tests passing. During baseline review they use Vitest's `it.fails`, not a skip: the known failure must still occur, and an unexpected pass fails the suite. The repair must remove those markers in tasks 2.2 and 3.2.
+
+The standalone protocol fixture drives the **real A1 damage adapter** with the pinned complete-row write grammar. It does not launch A1, Pi, or an agent and does not simulate their complete rendering/input pipeline. In particular it cannot establish shell overlay, selection, or streaming acceptance. It separates emitted-byte evidence from the host's native-hover decoration so those later tests do not mistake a passing controller assertion for a fixed visual bug.
+
+## Confirmed physical baseline
+
+The user reports that in **mode 2 (auto-detected)**, wheel scrolling moves the hovered link upward while its underline remains under the stationary pointer briefly, then disappears. That transient trail is a failure, not successful cleanup.
+
+The clean `f3613bb` run at 123 columns by 29 rows (`run-smbQ70/trace.jsonl`) records `ghost: true` in auto-detected mode after a downward wheel scroll at scroll position 9. The immediately preceding frame, 214, contains no explicit OSC 8 target opens, and the adapter reports `suppressed-redundant-clear`; its forwarded write has no full-screen clear. This confirms an auto-detection reproduction but does not prove that restoring the clear will fix it. The recorded one-shot `f` comparisons were in explicit mode, with no observation establishing their effect on the auto-detected case. Terminal version and the precise host detection setting remain unrecorded.
+
+The persistent-clear comparison below avoids asking the user to press `f` before the short-lived artifact disappears. It changes the diagnostic write path only; production behavior and terminal settings remain unchanged. The user reports that **CLEAR:ON helps** for the confirmed mode-2 case. This supports preserving the complete clear in the production repair, but does not by itself prove the artifact is completely absent in the built A1 candidate.
+
+The test host is Windows Terminal `1.24.2607.10001`, determined from the running executable after the comparison. Its settings file contains no explicit global, profile-default, or per-profile `experimental.detectURLs` override; therefore the effective host default applies. The fixture geometry was 123 by 29. Explicit-mode reproduction remains unconfirmed and is recorded as unknown rather than assumed clean.
+
+## Run in Windows Terminal / Git Bash
+
+From the implementation checkout, with dependencies installed:
+
+```sh
+./scripts/pi/reproduce-ghost-link-underlines
+```
+
+This shell entry preserves VT color. It uses `tsx` directly, so no application build is needed for this standalone probe. It is not a substitute for the eventual built-candidate `./scripts/dev` acceptance run.
+
+Optional host facts can be recorded explicitly; use the actual version from Windows Terminal's About page and the actual automatic URL-detection setting, without changing either:
+
+```sh
+./scripts/pi/reproduce-ghost-link-underlines --terminal-version YOUR_VERSION --url-detection enabled
+```
+
+Missing facts are recorded as `unknown`, not inferred. Use a terminal wide enough to display the controls (192 columns by 54 rows is a useful comparison geometry).
+
+## Persistent clear comparison for the confirmed auto-detection case
+
+```sh
+./scripts/pi/reproduce-ghost-link-underlines --auto --preserve-clears
+```
+
+This starts directly in mode 2 with **CLEAR:ON**. Every frame, including every wheel-scroll frame, sends the requested complete synchronized clear-and-repaint directly to the terminal. It is a labelled control experiment, not an implemented A1 fix.
+
+Hover a link and scroll with the wheel while keeping the pointer stationary. Record **y** if any underline trail remains, even if it disappears shortly afterward; record **n** only if this case stays clean. Press **p** to switch to **CLEAR:OFF**, restore the same content position with **r**, and compare the same gesture through the existing adapter. **p** persists across subsequent scrolls, mode changes, and resets. The status row always shows its state. Press **q** to exit.
+
+Trace format 2 records `preserveClears` and actual `bypass` state separately on frames and observations. If the trail survives CLEAR:ON, merely preserving the full clear is insufficient for this reproduced host behavior; further diagnosis is required before choosing the production cleanup strategy.
+
+## Observe and record
+
+1. Press **1** for explicit OSC 8 links. Hover the long label, a file label, or a wrapped URL. Keep the pointer stationary and press **x** to replace the content with blank green rows. Also inspect those former cells by hovering them again.
+2. Press **y** if a ghost underline is visible or **n** if the current case is clean. These keys record a **human** observation of the preceding action; capture a screenshot before pressing them because feedback itself repaints.
+3. If a ghost is visible, press **f**. This sends the complete clear directly to the terminal, bypassing the optimizer for this one control experiment. Record **y** or **n** again. The trace labels bypass writes so they cannot be mistaken for production output.
+4. Press **r** to restore the current mode. Hover the long label at its left side and press **b** to shorten/reposition it. Record the result. This visual fixture does not exercise the controller's hover-key logic; the controller regression covers that independently.
+5. Restore with **r** and use the wheel or **j/k** to scroll while the pointer remains stationary. Scroll until all links are above the screen, then hover plain text and blank rows. Record the result, including cases that do **not** reproduce.
+6. Press **2** for the same labels without explicit OSC 8 targets; repeat blanking, scrolling, and the forced-clear comparison. Whether these labels become links is controlled by Windows Terminal's own detection. The file-like tool rows are deliberately not wrapped in OSC 8 in either mode.
+7. Press **q** or Ctrl+C to restore the terminal. Report the terminal version, automatic URL-detection setting, observations, and screenshot if the symptom occurs.
+
+The fixture does not implement link activation. The host may still handle its normal hyperlink gestures; the explicit file target is this checkout's `package.json`, and web targets use the reserved `example.invalid` domain.
+
+## Built A1 candidate
+
+The implementation branch `fix/ghost-link-underlines` now carries the production repair. Build it, launch the color-preserving repository entry, produce output containing web URLs, file paths, and linked file labels, and test all of the following while leaving the pointer stationary over a link:
+
+- wheel-scroll the link upward and downward;
+- use Home/End, Shift+Up/Down, the scrollbar, and followed streaming output;
+- resize or reflow the terminal so the link changes row or width;
+- select linked content, edge-auto-scroll, release, and copy;
+- let linked content leave the viewport and hover the resulting plain and blank cells.
+
+Expected: the underline moves with current link cells and never remains under the pointer, even briefly; current links remain clickable and retain their colors; copied text is unchanged; no blank intermediate screen is visible. The implementation limits complete cleanup frames to transitions involving visible explicit or conservative host-detected link candidates. Stable dock typing and motion within one unchanged link retain bounded differential paint.
+
+Known gaps before acceptance: the exact built candidate still needs physical Windows Terminal review; explicit-mode baseline behavior was not confirmed; required code CI has not yet been recorded; and user acceptance remains open.
+
+## Evidence and limitations
+
+Each run creates its own ignored `.artifacts/ghost-link-baseline/run-*/trace.jsonl`. It records checkout commit and dirty status, supplied host facts, geometry, requested writes, actual forwarded writes, adapter decisions, probe input, and explicit human observations. It captures only the synthetic fixture, not an agent conversation. Review local file targets before sharing the trace.
+
+For noninteractive protocol evidence:
+
+```sh
+./scripts/pi/reproduce-ghost-link-underlines --capture
+```
+
+Capture mode always records `physical-result: not-observed`. Final text, closed OSC 8 sequences, and a preserved clear cannot prove that Windows Terminal discarded its hover overlay. A clean probe also does not disprove the original A1 screenshot: the complete UI pipeline still needs review.
+
+Baseline task 1.2 remains incomplete: the mode-2 failure, host facts, and a helpful persistent-clear comparison are recorded, but explicit-mode and fully-clean control outcomes have not been confirmed. The remaining production repair and exact-candidate acceptance tasks remain open. If the preserved-clear control still ghosts, that is evidence to investigate before assuming clear preservation alone is sufficient.

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

@@ -4,63 +4,40 @@ Run this checklist only against a packaged candidate on a user-controlled termin
 
 ## Artifact identity
 
-Record before testing:
-
-```text
-A1 release ID:
-A1 package version:
-Source commit:
-Candidate tarball SHA-256/integrity:
-Process guardian target: win32-x64
-Process guardian crate version:
-Process guardian protocol version:
-Process guardian SHA-256:
-Process guardian signature/attestation status:
-Machine/Windows/terminal versions:
-Tester or worker attestation:
-```
-
-The process guardian values must match `dist/native/win32-x64/manifest.json` inside the exact installed candidate. Stop if the file is missing, mismatched, altered, or reports an unsupported capability.
+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 and launch:
+Open four independent terminal tabs:
 
 ```text
 Terminal 1: a1
 Terminal 2: a1
 Terminal 3: a1 pi
-Terminal 4: a1 sandbox
+Terminal 4: a1 pi
 ```
 
-Confirm all four become usable without a global foreground-lease error. Record each launch-instance ID from supervisor metadata and verify all four IDs are distinct.
+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 vanilla Pi tree exits; Terminals 1, 2, and 4 remain usable.
-2. Close the Terminal 4 tab/window without exiting Pi first. Confirm its sandbox Pi, extension daemons, agent workers, tools, and descendants disappear within the bounded deadline while both bare-A1 terminals remain usable.
-3. Exit Terminal 1 normally 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 Job Object kill-on-close removes its root and descendants and leaves unrelated fixture processes alive.
+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 a failed cleanup.
+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 `a1 sandbox` once. Confirm that the same invocation migrates the row to historical interrupted state and launches normally without restarting the supervisor, deleting state, or discovering a PID.
+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. A delayed or uncertain instance must prevent unsafe replacement without causing another instance to be reported idle prematurely.
+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 one of:
-
-```text
-ACCEPTED — exact package and guardian digests above passed every scenario
-REJECTED — include failed step, observed process identities, outcomes, and diagnostics
-```
-
-Acceptance applies only to the exact package and process-guardian bytes recorded above. It does not certify macOS, Linux, composed terminals, detached agents, or an operating-system security sandbox.
+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-owned-ui-checkpoint.md

@@ -0,0 +1,78 @@
+# Manual owned-UI 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
+
+For a checkout smoke test in Git Bash, build once and launch with `./scripts/dev` or `./scripts/dev pi`. Do not invoke `node scripts/development/dev-launch.mjs` or `node scripts/development/start-local.mjs` directly: that bypasses the color-preserving shell `exec` shape and can collapse the pinned 24-bit palette to Git Bash's 16 terminal colors. Run `node scripts/check-terminal-colour.mjs` first when color fidelity is in doubt; the first color block must differ from the terminal-palette cyan block.
+
+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-owned-ui
+npm install --prefix .artifacts/manual-owned-ui/install --ignore-scripts .artifacts/manual-owned-ui/<exact-tarball>.tgz
+```
+
+Use isolated A1 control state:
+
+```powershell
+$manualRoot = (Resolve-Path ".artifacts/manual-owned-ui").Path
+$env:A1_CONFIG_DIR = "$manualRoot\state\config"
+$env:A1_DATA_DIR = "$manualRoot\state\data"
+$env:A1_RUNTIME_DIR = "$manualRoot\state\runtime"
+$env:A1_DATABASE_PATH = "$manualRoot\state\data\control.sqlite3"
+```
+
+Run each installed launch form yourself:
+
+```powershell
+& ".artifacts/manual-owned-ui/install/node_modules/.bin/a1.cmd"
+& ".artifacts/manual-owned-ui/install/node_modules/.bin/a1.cmd" pi
+```
+
+Both commands use the same A1-owned rendering and input pipeline. Bare `a1` enables A1-owned screens. `a1 pi` withholds those screens and reads the ordinary Pi profile. Confirm that files created through `/settings`, `/login`, sessions, and resource directories remain under the selected profile root.
+
+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 A1 with `a1 pi`
+
+Use the same terminal, working directory, dimensions, environment, and equivalent profile resources. Bare A1 and the comparison profile 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 delay or dropped or duplicated characters.
+- [ ] Ctrl+C, Ctrl+P, arrows, paste, focus, dialogs, mouse, and wheel behave correctly.
+- [ ] Selection, copy, clipboard, scrollback, and resize behave correctly.
+- [ ] Normal and error exits return a usable parent prompt.
+- [ ] Parent typing, cursor movement, Backspace, Delete, and submission work after exit.
+
+### Setting-controlled visual matrix
+
+Use equivalent values in bare A1 and the Pi comparison profile. Exercise both a wide frame and a narrow frame that forces wrapping/clipping.
+
+- [ ] `/settings`: selected cursor, label and value accent; unselected values muted; descriptions and hints dim; search uses `> ` with inverse cursor; scalar menus, numeric controls, warning-parts dialog, deferred notice, failed write, section spacing, clipping, and hidden-entry absence match their pinned semantic roles.
+- [ ] Transcript: toggle images and image width, thinking level/visibility, Mermaid mode, output padding, cache notices, warnings, auto-compaction, queue modes, command autocomplete, provider timeout/retry/error, and changelog collapse. Existing and streaming blocks must re-render without focus, selection, scroll, or queued-work loss.
+- [ ] Trust startup: from an undecided project, compare selected Trust/Do not trust rows, arrow navigation, Enter, Escape/Ctrl+C, clearing, cursor state, and restoration. No project extension/theme/prompt/skill may run before selection, and a fail-closed diagnostic must appear once on the restored parent rather than above a blank fullscreen frame.
+- [ ] Terminal lifecycle: toggle hardware cursor, clear-on-shrink, and terminal progress; resize smaller/larger; open/close selectors; select and copy transcript text; verify no duplicate rows, stale OSC progress, leaked mouse mode, misplaced cursor, or broken parent input.
+- [ ] Images: in Kitty or iTerm2 verify inline width and clipping; in Windows Terminal verify the textual fallback and absence of image protocol bytes without hiding `showImages`.
+- [ ] Fullscreen exit `transcript`: verify the parent is restored before styled user, assistant Markdown, thinking, tool, notice, warning, error, and spacing rows are printed. No overlay, draft, animation, scrollbar, or inline-image payload may appear.
+- [ ] Fullscreen exit `resume-hint`: verify only dim `To resume this session:` plus `a1 --session <compact-id>` is printed for the default directory. A custom directory must place quoted `--session-dir <dir>` before `--session`; the raw default `.jsonl` path must never print.
+
+Record acceptance with:
+
+```text
+A1 commit/tarball:
+Pi package: @earendil-works/pi-coding-agent 0.84.2
+OS/version:
+Terminal/version:
+Terminal dimensions (wide/narrow):
+Image protocol result:
+Settings values exercised:
+Outcome and any declared substitutions:
+```
+
+Report failures with bare-versus-comparison behavior, platform and terminal versions, exact command, dimensions, settings values, reproducibility, and optional manually captured evidence.
+
+For recovery, use `a1 pi`; do not use the removed `a1 ui` command. Manual acceptance can authorize an exact uncertified development preview after non-desktop gates pass. It does not certify stable presentation parity or platform support.