@timurproko/a1 0.1.8-dev.332 → 0.1.8-dev.368

package/docs/ci-release-runbook.md

@@ -166,15 +166,40 @@ work.
 
 ## Cutting a stable release
 
-From a clean `develop` matching its remote:
+From the repository root on clean `develop` matching `origin/develop`:
 
 ```sh
-npm run release -- patch     # or minor, major, or an exact x.y.z
+npm run release -- patch     # 0.1.8-dev -> 0.1.8; already-stable 0.1.8 -> 0.1.9
+npm run release -- minor     # 0.1.8-dev -> 0.2.0
+npm run release -- major     # 0.1.8-dev -> 1.0.0
+npm run release -- 0.4.0     # exact stable target
 ```
 
-The command lands `x.y.z` through its version pull request, explicitly dispatches
-stable publication for that exact current `origin/develop` commit, and waits. Only
-after success does it land `x.y.(z+1)-dev`.
+A target is required: `npm run release` alone is a mutation-free usage error.
+`patch` preserves prerelease-aware semantics, including `0.1.8-dev.123 -> 0.1.8`.
+The command reports its source, stable target, and prospective reopening before
+preparing anything.
+
+1. The stable-version edit is committed in an owned detached worktree beneath
+   `.worktrees/`. Only this package's manifest and root lockfile version change.
+2. Follow the printed PR URL, wait for required CI, perform local validation, and
+   **merge manually after acceptance**. The helper does not merge PRs or enable
+   auto-merge. It polls for actual merge with a bounded 30-minute wait.
+3. The helper verifies the merged version and source SHA against authoritative
+   develop, then explicitly dispatches stable publication for that exact source.
+   A changed source is an error, not permission to substitute a newer commit.
+4. Only after verified publication of `0.1.8` does it prepare a separate PR for
+   `0.1.9-dev`. Validate and manually merge that PR as well. Until then the helper
+   reports development reopening as incomplete.
+
+Closed PRs, timeout, cancellation, and query failures retain identifiable phase
+work for inspection. Conflicting existing branches/PRs are not overwritten;
+matching pending PRs can be observed again without replacing them. Worktrees
+retained by an earlier attempt are not removed by a later invocation. Cleanup
+only removes clean, owned, confirmed-merged phase worktrees and unchanged remote
+phase branches. The caller is never hard-reset: a final fast-forward is attempted
+only when its branch, original HEAD, and cleanliness remain unchanged. Otherwise
+preserve local work and synchronize manually with the reported remote state.
 
 Stable publication builds the process guardian on all supported platforms, packs
 once, runs the complete suite against those exact bytes on Windows, Linux, and
@@ -200,8 +225,21 @@ Rules that do not bend:
   path, and use the confirmed apply mode only for an accepted mutable policy change.
 - **Nightly documentation review fails:** inspect the reported paths and rules, identify the introducing merge from the nightly interval, and repair the invariant before unrelated work proceeds.
 - **Development publication fails:** fix the cause and rerun `npm run develop`; an npm version that already exists is never overwritten.
-- **Stable publication fails before npm accepts bytes:** no tag, release, or moved branch exists. Fix the cause and release the next version.
-- **Stable publication is uncertain after npm accepted bytes:** stop and inspect registry version, digest, tag, and release. Never republish immutable bytes.
+- **Stable preparation stops before dispatch:** inspect the reported version PR/worktree. After preserving work, an exact matching pending PR can be observed again. If develop already declares the prepared stable version, use its exact target (for example `npm run release -- 0.1.8`) only after verifying that source's merged PR and confirming the registry/tag guards still permit it. Do not use `patch` from stable develop to retry the same version: that deliberately selects the next patch.
+- **Stable publication fails or is uncertain:** inspect the workflow, registry version/digest, tag, and release before choosing recovery. No reopening PR is prepared. Never republish immutable bytes or move a release tag.
+- **Stable publication succeeded but reopening stops:** the stable version is already published. Inspect and finish the reported next-development PR manually; do not repeat stable publication. If no reopening PR was created, prepare the next-development version through a separately validated manual PR after inspecting remote state.
+
+## Safe release-command validation
+
+Use the isolated harness rather than a live release to validate changes to this command:
+
+```sh
+npm exec --no -- vitest run test/repository-governance/release-target.test.ts test/repository-governance/release-command.test.ts --maxWorkers=1 --minWorkers=1
+```
+
+It uses disposable local Git repositories and fake GitHub, registry, and publication
+services. It does not publish a package or create production version PRs. A real
+release remains a separate deliberate operation.
 
 ## Branch protection rationale
 

package/docs/features/modal-content-interaction.md

@@ -0,0 +1,37 @@
+# Transcript interaction with modals
+
+Bare A1 keeps the exposed transcript under its normal viewport controller while a modal is open. Scrolling, scrollbar settings, selection styling and boundaries, clipboard output, and speed are the same as without a modal. This is not a new selection implementation or a speed adjustment. The comparison `a1 pi` path is unchanged.
+
+Pointer ownership follows the painted region, not keyboard focus. Docked replacements publish their input bounds from shell layout. The runtime observes public overlay component renders in the protected composition hook, including runtime-created search overlays, and projects the pinned public layout options into terminal hit regions. Terminal-cell tests compare that projection with actual overlay paint across anchors, percentages, margins, clipping, stacking, and resize. No installed dependency or private renderer state is modified.
+
+A pointer gesture stays with its initiating surface through release. Geometry or ownership changes cancel the old viewport gesture, stop its timers, and consume the remaining gesture rather than delivering it to a newly revealed surface. Modal-covered cells do not accept new background gestures. Keyboard input remains with the focused modal, except that a nonempty A1 transcript selection owns its copy chord exactly once. There is no vanilla selection layer or vanilla copy notification for transcript gestures.
+
+## Host inventory
+
+The existing [modal transition inventory](../../config/baselines/modal-surface-inventory.json) remains the authority for specialized workflows. All its nodes cross one of these shared hosts; there is no command allowlist in pointer routing.
+
+| Inventory family | Shared host | Interaction evidence |
+| --- | --- | --- |
+| `editor.root` | Ordinary editor and viewport | Existing viewport/controller and shell regression cases |
+| `settings.*`, `models.*`, `trust.project` | Shell replacement input, including nested component states | Real settings/thinking, Model Configuration and model selection; generic replacement geometry and gesture tests |
+| `session.*`, `tree.*` | Shell replacement input and nested replacement/confirmation controllers | Real fork plus existing resume/tree/missing-directory lifecycle cases; shared replacement tests |
+| `auth.*` | Shell replacement input, including provider and nested prompts | Real login/logout plus existing OAuth/API-key/nested restoration cases; shared replacement tests |
+| `command.import-confirm`, `operation.*` | Shell replacement confirmation/loader | Existing confirmation/loader lifecycle cases; shared replacement tests |
+| `extension.select`, `extension.confirm`, `extension.input`, `extension.editor`, `extension.custom-editor`, `extension.custom-replacement` | Extension bridge to shell replacement input | Parameterized public extension UI tests, including an unlisted custom replacement |
+| `extension.overlay`, backend dialogs, owned route panels | Runtime overlay host | Unlisted extension overlay, partial/full-cover/stacked overlay paint and pointer tests |
+| Runtime transcript search | Public runtime overlay entry, not a shell command registration | Runtime-created search geometry/focus/restoration test |
+
+Focused files:
+
+- `test/integrations/pi/session-ui/session-viewport-controller.test.ts`: modal/no-modal selection/copy and render-cadence comparison, wheel/auto-scroll speed comparison, settings, boundary crossings, and gesture cancellation.
+- `test/integrations/pi/session-ui/session-shell.test.ts`: real workflows, extension-host families, ordered mixed/chunked input, nested settings, resize, streaming, copy notification exclusion, and modal-over-selection terminal paint.
+- `test/integrations/pi/tui-runtime/overlay-geometry.test.ts`: independent terminal-cell geometry and runtime search coverage.
+- `test/integrations/pi/tui-runtime/mouse-report-input.test.ts`: ordered report delivery, partial reports, and opaque pasted text.
+
+## Manual review
+
+Build the exact candidate, then launch it through `./scripts/dev` from its worktree in Windows Terminal/Git Bash. Use `/hotkeys` to populate a long transcript, then open `/scoped-models`. Compare scrolling and drag/word/line selection with the dialog closed and open. Try the rail, copy, and jump-to-bottom; the model dialog must not navigate or close as a side effect of transcript gestures. Copy must not show Pi's `Copied` notification.
+
+Repeat with `/model`, settings and a nested settings dialog, and extension-provided docked and floating surfaces. Check that typing, modal buttons and wheel handling, save, and cancel still work. Resize during a drag, close/reopen the modal, and repeat while output streams. A full-cover screen must not allow click-through into hidden transcript cells. `auto` scrollbar visibility remains activity-dependent; `hidden` remains hidden.
+
+User confirmation of the exact built candidate is still required before merging the code PR. The baseline's pre-existing selection boundaries and speed are intentionally preserved, as clarified by the user; this change does not attempt to reconcile older specification wording by changing those behaviors.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timurproko/a1",
-  "version": "0.1.8-dev.332",
+  "version": "0.1.8-dev.368",
   "description": "Standalone terminal workspace for supervised native and managed agents",
   "type": "module",
   "privateLaunchContract": "neutral-launch-v1",