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

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,212 @@
+# Local worktree cleanup after verified delivery
+
+Local cleanup completes the delivery order in [the archive runbook](openspec-archive-automation.md). For version 3 that is one authorized manual implementation/acceptance/archive merge, read-only verification, remote topic-ref deletion, then safe local cleanup. Legacy versions still require their applicable acceptance-record and automatic archive merges. GitHub Actions never reaches into a developer machine. Local cleanup never publishes archives or merges PRs; `complete`, preview, and queue/watch do not delete remote refs, while explicitly confirmed closed-unmerged `discard` owns only its exact expected-SHA topic-ref deletion.
+
+The implementation is repository tooling, not part of the installed A1 product. It requires Node, Git, and GitHub read access; the explicit closed-unmerged discard operation additionally requires authenticated permission to delete its exact remote topic ref. 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.
+
+## Hand-off and sweep: the ordinary agent path
+
+The delivering agent's session usually ends before the maintainer merges, so cleanup is split into two commands that never need the same session. When the validated PR is handed to the maintainer, and again after any repair push, the owning agent parks the worktree from the primary checkout:
+
+```bash
+node scripts/governance/local-worktree-cleanup.mjs handoff   --repo D:/Git/a1   --path D:/Git/a1/.worktrees/example-task   --change example-change   --pr 123
+```
+
+`handoff` registers the exact worktree if it is not registered yet (or reclaims the existing released entry), records its current HEAD and branch, applies the central disposable policy, and releases it. It evaluates nothing, deletes nothing, and does not enable the queue. That release is the candidate-scoped cleanup authorization for this worktree and its topic ref, exercised only once the merge, archive, validation, and remote-ref gates verify later; it never becomes discard authority for a PR that is later closed unmerged. It is idempotent per worktree: repeating it updates the recorded head instead of adding a second registration. Tracked, staged, unstaged, or untracked content outside the disposable roots blocks with `worktree-content` and the affected paths, because such content means unpushed work; unknown ignored content is judged at removal time, as it is for `complete`. A primary, foreign, replaced, or branch-changed path blocks with a named reason. A worktree that a session registered with the low-level `register` command and still owns is released by `handoff` (or `complete`) when `LOCAL_CLEANUP_OWNER_TOKEN` holds that registration's token; without it both block with `owned-worktree`, and a separate `release` is needed.
+
+Every delivery session then starts, before it creates a worktree, with one bounded sweep from the primary checkout, and runs it again when it verifies or is told of a merge:
+
+```bash
+node scripts/governance/local-worktree-cleanup.mjs sweep --repo D:/Git/a1
+```
+
+`sweep` evaluates every released registration in one pass under the queue limits (100 registrations, 500 remote requests, a durable round-robin cursor) with a 180-second elapsed budget, since each merged candidate costs three evidence loads, and completes each candidate whose PR is verified merged using exactly the `complete` safeguards. It needs no `enable` and starts no process: its authority is each candidate's release. A candidate whose PR is open, draft, or not yet finalized reports `pending`; a candidate whose PR closed without merge reports `awaiting-discard` and is never touched; blockers report their exact reason. An old stop sentinel does not prevent a sweep, but `disable` run while a sweep is executing stops it before its next destructive step. If another session holds the mutation lock the sweep reports `mutation-busy` and the agent relays it as deferred rather than waiting. The JSON report carries a `lines` array with one relayable line per candidate and pruned branch, for example `#458 close-absent-and-skewed-cleanup: removed [worktree-removed, local-ref-removed]`. Pending or blocked results never delay the new delivery.
+
+### Nothing left to remove
+
+A released entry whose evidence can never verify (for example `delivery-content-drift` after a stale-base merge, or `source-association` for a PR without an `openspec-implementation` fence) would otherwise be re-verified and reported `blocked` on every sweep. When such an entry's worktree path is gone, Git holds no live row for it (its own dangling row is retired), and its local topic ref is absent, the sweep and `complete` ask GitHub only whether the pull request merged into `develop` in this repository and then mark the journal `done` with `retired-nothing-left` and the original evidence reason. Nothing is deleted; a present path, row, or ref keeps the entry blocked, an unmerged PR keeps it `pending` or `awaiting-discard`, a deferred failure such as `remote-budget` is never treated as unverifiable, and preview retires nothing. For an all-absent entry whose PR is not merged, the maintainer runs the explicit form, which reads nothing from GitHub and deletes nothing:
+
+```bash
+node scripts/governance/local-worktree-cleanup.mjs forget --repo D:/Git/a1 --id REGISTRATION_ID --confirm-nothing-left
+```
+
+`forget` refuses without the flag, for an owned or deleting entry, and while the path, a live Git row, or the ref still exists (`something-remains`). `status` shows both notes under `completion`.
+
+### Keep the base current before merge
+
+The `develop` ruleset requires the pull request head to be up to date with `develop`. When another delivery merges first, the PR shows `BEHIND`: merge `origin/develop` into the branch (or use "Update branch"), push, let the `OpenSpec finalization` workflow re-finalize with digests of the merged bytes, wait for validation, and hand off again. Merging a stale finalized head is what produced `delivery-content-drift` for #461; with the strict policy GitHub refuses that merge.
+
+### Accepted ancestry
+
+Since the `OpenSpec finalization` workflow pushes its commit onto the PR branch after the agent's last push, the registered head is normally one commit behind the merged head. Cleanup therefore accepts a registered head, live worktree HEAD, or local topic-ref tip that equals the merged PR head or is one of its ancestors on GitHub, verified with the compare API: every commit reachable from such a tip is reachable from a head the maintainer accepted, so nothing is lost. A tip that holds a commit outside the merged head, or a commit GitHub does not know, still blocks with `candidate-head-association`, `worktree-identity-changed`, or `local-ref-advanced`, and the branch attachment must still be the registered one. Ref deletion reads the tip immediately before deleting, requires it to be accepted, and uses it as the compare-and-delete expectation. Ancestry of `develop` is never used, because the repository squash-merges.
+
+### Merged branch pruning
+
+The sweep also prunes local topic branches that have no live registration, such as the branch left behind when a worktree was deleted by hand. A branch is deleted only when all of these hold: its name follows `type/short-description` and is not `develop` or another protected or reserved name; no worktree has it checked out; the same-repository pull-request lookup by that head ref name returns at least one PR merged into `develop` and no open PR; the tip equals or is an ancestor of the most recent such merged PR's head; and `origin` no longer has the ref. Deletion is compare-and-delete against the tip reread immediately before. Everything else is reported and kept with `branch-no-pull-request`, `branch-open-pull-request`, `branch-closed-pull-request`, `branch-unmerged-commits`, `branch-checked-out`, or `branch-remote-present`. Branch pruning never deletes remote refs, worktrees, or registrations, and a preview never prunes.
+
+## Standard completed-delivery command
+
+The exact-candidate form remains for a session that is still alive at merge time or wants to finish one candidate by name. After authorized merge, accepted/archive verification, and remote topic-ref removal, the owning agent runs one command from the primary checkout:
+
+```bash
+node scripts/governance/local-worktree-cleanup.mjs complete \
+  --repo D:/Git/a1 \
+  --path D:/Git/a1/.worktrees/example-task \
+  --change example-change \
+  --pr 123
+```
+
+`complete` is explicit cleanup authorization for that exact candidate. It creates and releases an exact registration when needed, applies the repository-owned generated-path policy, verifies live merge/archive/CI/ref evidence, evaluates only that candidate, uses journaled non-force Git removal, deletes only the unchanged local topic ref, and leaves persistent watcher authority unchanged. Repeating it reports the completed candidate as already absent. Existing conflicting ownership, identity drift, unavailable evidence, or unknown content remains blocking.
+
+The central disposable policy is `node_modules`, `dist`, `.builds`, `.artifacts`, `native/process-guardian/target`, and `native/terminal-host/target`. The `.artifacts` root is the repository's ignored generated-artifact root (finalization and validation reports, packed candidates, agent-written logs and diffs); the two native roots contain repository-generated Cargo output. Registrations that still name `.artifacts/openspec-archive` or `.artifacts/validation` stay valid and are widened to the root on the next `complete`. Each encountered path must be ignored and stay inside the exact worktree with no link, special file, or nested repository boundary. Authority is component-exact: near matches such as `.artifacts-user` or `artifacts`, arbitrary `target` directories, and sibling native projects remain blocking. Tracked/staged/unstaged/untracked content and every unknown ignored path still block. A tracked regular `.gitmodules` file alone is ordinary content; actual nested `.git` metadata, gitlinks, configured submodules, and submodule changes block. Ordinary content and these approved generated roots are traversed under separate finite entry allowances, so a normal dependency installation does not consume the ordinary source-tree allowance; both allowances retain the same deadline and content-boundary checks. Once those checks pass, cleanup deletes the declared disposable roots itself with a bounded retry for transient Windows sharing violations before handing the worktree to Git, so non-force Git removal only has to delete tracked content. A root that stays locked after the retry budget reports `blocked` with `disposable-path-locked` and the root's path; the worktree, its `.git` pointer, and its journal are untouched, so stop the process holding the handle and rerun the same command.
+
+Agents do not manually remove generated content, call `git worktree remove`, or delete the local branch after delivery. The JSON result is authoritative: report success only for `removed` or verified `already-absent`; otherwise retain the worktree and report the exact blocker. A handed-off entry whose worktree was deleted by hand completes through its journal, and its branch is deleted under the accepted-ancestry rule. Legacy roles can supply separate `--source-pr`, `--candidate-pr`, and `--role` values.
+
+## Explicit closed-unmerged discard
+
+Closing a PR does not itself authorize deletion. After the maintainer explicitly rejects one exact PR and separately confirms remote deletion, run the candidate-scoped command from the primary checkout:
+
+```bash
+node scripts/governance/local-worktree-cleanup.mjs discard \
+  --repo D:/Git/a1 \
+  --path D:/Git/a1/.worktrees/rejected-task \
+  --change rejected-change \
+  --pr 123 \
+  --confirm-closed-unmerged
+```
+
+`discard` requires the named PR to remain closed without merge, target `develop`, belong to this repository, and identify the exact registered worktree HEAD and branch. It first applies the same clean-content and generated-root inspection used by `complete`. It then verifies the remote topic branch is unprotected, non-reserved, and still equals the PR head; deletes only that ref with an expected-SHA lease; verifies remote absence; rechecks the local candidate; removes the worktree non-forcibly; and atomically deletes only the unchanged local branch.
+
+An open, merged, reopened, forked, protected, reserved, advanced, dirty, active, linked, nested, replaced, current, or unverifiable candidate remains blocking. Remote deletion followed by a Windows lock or later local blocker is reported as `partial`; the journal preserves the remaining worktree/local ref for the same exact confirmed command to inspect and resume. The command never scans by age or name, adopts another session's checkout, enables queue/watch, or turns PR close events into automatic discard authority.
+
+## 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; preview reports a folder that an execution pass would remove as an empty leftover with `empty-directory` (see below) but deletes nothing. 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 queue/watch enablement
+
+Neither `handoff`, `sweep`, nor the exact-candidate `complete` command enables the persistent queue; `sweep` scans released registrations under its own authority, while `once`/`watch` remain the separately enabled background route. Only after the maintainer separately authorizes queue/watch 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 ordinary entries plus 100,000 entries beneath exact approved generated roots; exhausting either allowance 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. This is the only version-3 role because the same PR contains implementation, acceptance manifest, synchronized specs, and archive.
+- `acceptance`: legacy exact verified implementation merge commit; candidate PR equals source PR.
+- `archive`: legacy 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. Version 3 has no local acceptance/archive checkout to register. No local archive checkout is required when a legacy archive was generated entirely on GitHub. Legacy version-1/version-2 linkage remains supported, but individually reviewing and registering a legacy checkout is explicit adoption, not a bulk sweep.
+
+Low-level `register` keeps an explicit disposable allowlist for legacy and diagnostic use. The standard `complete` command supplies the central repository policy automatically; agents do not choose flags for normal completed-delivery cleanup. Neither route permits discarding tracked, staged, unstaged, untracked, unknown ignored, linked, special, or actual nested repository/submodule content. Declaring or centrally recognizing a generated directory does not bypass ignored-path, identity, type, or traversal checks.
+
+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. For version 3 the worker verifies the exact authorized human manual source merge, required CI, conditional manifest, synchronized specs/archive on current `develop`, and absence of the source topic ref. For legacy versions it still verifies the exact comment or human-manually-merged acceptance receipt, generated archive marker/merge/CI, archive contents, and all applicable topic refs. A bot/automatic/merge-queue acceptance, stale record, missing required CI, unmatched archive, or open/closed-unmerged PR blocks cleanup.
+
+After a low-level release, request a pass from the stable checkout if queue cleanup is enabled. A running watcher will also pick it up. Normal completed delivery instead uses `complete`. 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 killed cleanup process is evicted only on proof: the holder writes its PID and refreshes a heartbeat in the lock every five seconds, and a later `handoff`, `sweep`, `complete`, `discard`, claim, or queue pass evicts the lock only when that heartbeat (or, for an old lock without one, the file's modification time) is more than two minutes old and the PID no longer exists. A live, unprobeable, or own PID keeps the lock, as does a fresh or unreadable-but-fresh file, and the operation reports `mutation-busy`. Each eviction is journaled as `lock-evicted-<time>-<id>.json` beside `state.json` with the evicted record; it releases no ownership and advances no journal step. A lock that stays `mutation-busy` therefore has a live holder: wait for it or stop that process first.
+
+## 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, or the handed-off PR is still open.
+- `awaiting-discard`: the handed-off PR closed without merge; only the explicit `discard` command may act.
+- `blocked`: ownership, content, path, provenance, authentication, or identity needs attention.
+- `unmanaged`: no local registration; no automatic adoption. Reason `empty-directory-recent` marks an all-empty folder still inside its ten-minute grace, and in preview `empty-directory` marks one an execution pass would remove.
+- `removed`: worktree and eligible local-ref operations were verified.
+- `already-absent`: a completed journal's path/ref are still absent.
+- `retired`: evidence was unverifiable but nothing remained to delete and the PR is merged; the journal is complete with `retired-nothing-left`.
+- `forgotten`: the maintainer explicitly closed an all-absent entry with `forget`.
+- `partial`: a destructive step began but all cleanup could not be verified; the same command resumes it.
+- `deferred`: a bounded pass or concurrent mutation owner prevented evaluation.
+
+Empty leftovers under `.worktrees/` are the one unregistered shape a pass removes. Git's own `worktree remove` deletes the checkout's files and then its administrative directory even when the final directory removal failed because a shell, editor, or indexer still held the folder open, so an empty top-level folder with no Git row, branch, or registration can outlive its worktree. Every execution pass (`sweep`, `complete`, `discard`, `once`, `watch`) scans the root and removes such a folder only when it is a real directory rather than a link, Git lists no worktree row for its path, its whole subtree holds nothing but directories (no file, link, special entry, or `.git` at any depth), and its modification time is at least ten minutes old so an in-progress `git worktree add` or removal is never raced. Removal is bottom-up with the non-recursive directory primitive only, which cannot delete a file that appeared after verification; it is reported `removed (empty-directory)` with step `empty-directory-removed` and named in the sweep lines. A folder still held open reports `blocked (empty-directory-locked)` and is retried on the next pass; anything containing content stays `unmanaged` and is never touched.
+
+Non-force Git removal is the only operation that deletes tracked content from an intact worktree. Local topic-ref deletion then compares the tip read immediately before, which must be the journaled head or an accepted ancestor of the merged head, 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.
+
+A released worktree whose directory was deleted by hand before cleanup ran is finished through its journal rather than failing on the missing directory: the same merge/archive evidence is verified, Git may hold no registration for the path or only this candidate's own dangling one, that registration is retired, the step is recorded as `worktree-already-absent`, and the unchanged local topic ref is deleted under the usual compare-and-delete rule. A `complete` invocation for an absent path that was never registered blocks with `worktree-absent-unregistered`, because there is no journaled head to compare the ref against.
+
+Post-merge provenance accepts a `merged` timeline event whose time is within five seconds of the pull request's `merged_at`; GitHub stamps the two from different services and has reported them one second apart. The single-event, human-actor, no-App, and same-commit checks are unchanged.
+
+Windows file locks can interrupt Git after it has already unlinked the `.git` pointer and part of the tree. That pass reports `partial` with `git-operation-failed` and keeps the journal at `remove-intent`; rerunning the same command resumes it. If the exact registered worktree is still intact, the retry re-inspects it and repeats non-force Git removal. Otherwise the retry verifies the residue: Git must no longer list the path as a valid worktree, the residue may contain no `.git` entry, link, special file, or nested repository, and every remaining regular file must either sit below a declared disposable root or match the exact tracked path and blob hash of the journaled head (`git hash-object` with the repository's filters). Only residue verified that way is removed, with the same bounded retry, after which this candidate's own dangling Git registration is retired and ref cleanup continues. A residue with any unknown, changed, or boundary-violating path reports `residual-content` and lists the offending paths for manual review; a residue that is still locked reports `residual-locked` and is retried on a later pass. `git worktree prune` is never run. A recreated or foreign worktree at the path reports `residual-or-reused-path` and needs a new registration. If a prior run fully removed the worktree and only ref cleanup remains, a subsequent 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. The handle fixture starts one throwaway `powershell.exe` when the file loads so the hosted runner's interpreter cold start overlaps the earlier tests instead of the fixture's timed hold; its bounds and release protocol are unchanged. 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.