@timurproko/a1 0.2.6 → 0.2.7-dev.1221

package/docs/openspec-archive-automation.md

@@ -1,6 +1,6 @@
 # Atomic OpenSpec delivery and legacy archival
 
-New OpenSpec deliveries use one ordinary development pull request from draft planning through implementation, validation, acceptance, specification synchronization, and archival. An authorized maintainer chooses integration by manually merging the exact validated head or personally enabling GitHub native auto-merge for that unchanged head. Agents, Apps, bots, merge queue, and repository automation never arm or invoke implementation integration and never create a version-3 acceptance or archive follow-up PR.
+New OpenSpec deliveries use one ordinary development pull request from draft planning through implementation, validation, acceptance, specification synchronization, and archival. An authorized maintainer chooses integration by manually merging the exact validated head, personally enabling GitHub native auto-merge for that unchanged head, or explicitly asking the active agent to merge the identified currently eligible head. Agents never infer or independently choose integration; Apps, bots, merge queue, workflows, and repository automation receive no implementation authority, and no version-3 acceptance or archive follow-up PR is created.
 
 Unrelated standalone documentation remains separate: a non-draft unassociated PR changing only `openspec/**`, `docs/**`, and/or root `README.md` retains the existing CI-gated automatic route. A new active change, implementation association, malformed lifecycle data, or mixed path remains outside documentation-owned integration. Before finalization or without valid human provenance, any arm is disabled; a finalized version-3 human arm remains a separate maintainer-owned route.
 
@@ -8,18 +8,32 @@ Version-1 and version-2 deliveries and their existing comments, acceptance PRs,
 
 ## Version-3 lifecycle
 
-1. **Draft plan:** create one normally named branch/PR such as `feature/...`, `fix/...`, or `chore/...`. Start the body with `## Proposal`, use it for one or two sentences of intent, follow it with `## Implementation` for the concrete planned work, omit quoted phase lines and routine validation command lists, and keep machine linkage under final collapsed `Automation`. Keep it draft and include only planning artifacts until the maintainer approves the plan and explicitly requests implementation.
-2. **Same-PR implementation:** continue after explicit approval in the same worktree, branch, history, draft PR, and phase-free body. Reconcile approved refinements in proposal, design, deltas, and tasks before corresponding code edits.
-3. **Complete evidence:** finish implementation, required tests/evidence, substantive tasks, and explicit known-gap disposition. CI success is objective evidence, not acceptance.
-4. **Plain acceptance list:** keep the body phase-free and add final `## Acceptance` with one to ten concise implementation-specific behavior-and-result bullets. Do not use checkboxes, generic review/CI/approval/archive statements, URLs, mentions, or automated-test inventory.
-5. **Ready and automated finalization:** mark the PR ready. The trusted `OpenSpec finalization` workflow reconciles current `develop`, conservatively synchronizes all deltas, moves the active change into its dated archive, stages the conditional acceptance manifest, commits that to the same branch with the archive App identity, and writes the emitted paths into the body's implementation fence. Running the [finalization command](#finalization-command) locally first is optional and yields the same bytes.
+1. **Draft plan:** create one normally named branch/PR such as `feature/...`, `fix/...`, or `chore/...`. Start the body with `## Proposal`, use it for one or two sentences of intent, and follow it with one or more unchecked, outcome-sized task items under `## Implementation`, with no fixed maximum. Each item names a delivered code outcome. Omit generic process tasks; run, verify, validate, evidence, or manual-test items; quoted phase lines; and routine validation command lists, and keep machine linkage under final collapsed `Automation`. Keep it draft and include only planning artifacts until the maintainer approves the plan and explicitly requests implementation.
+2. **Same-PR implementation:** continue after explicit approval in the same worktree, branch, history, draft PR, and phase-free body. Check an Implementation item as soon as its associated code and tests are written and its detailed task bookkeeping is complete; an ordinary progress edit changes only `[ ]` to `[x]` and is not deferred until handoff. Adding, removing, reordering, or rewriting an item is a scope refinement requiring explicit approval and coherent planning updates, with affected scope left unchecked. Reconcile approved refinements before corresponding code edits.
+3. **Complete implementation:** finish the code and its tests, substantive tasks, and explicit known-gap disposition. CI runs those tests after readiness; its success is objective evidence, not acceptance, and GitHub check counts are not Implementation task progress. Manual validation is the maintainer's optional choice before integrating and never blocks a checkbox, finalization, or merge.
+4. **Plain acceptance list:** before checking the final item, keep the body phase-free and add final `## Acceptance` with one to ten concise implementation-specific behavior-and-result bullets. Do not use checkboxes, generic review/CI/approval/archive statements, angle-bracket placeholders or HTML, URLs, mentions, or automated-test inventory.
+5. **Automatic readiness and finalization:** reconcile and push current `origin/develop`, run the [delivery body check](#delivery-body-check) on the intended final body, then check the final item. That checkbox update completes the agent-owned implementation job; agents never mark implementation PRs ready themselves. Trusted automation revalidates the exact fully complete version-3 task-list snapshot and all pre-finalization inputs, marks the PR ready, and then conservatively synchronizes all deltas, moves the active change into its dated archive, stages the conditional acceptance manifest, commits that to the same branch with the archive App identity, and writes the emitted paths into the body's implementation fence. It never checks tasks or infers completion. Running the [finalization command](#finalization-command) locally first is optional and yields the same bytes.
 6. **Validate:** one normal exact-head workflow validates the finalized head: implementation, synchronized specs, archive, manifest, tasks/evidence, exact PR-body list, and every selected product/governance scope before emitting the stable protected aggregate. A new commit or acceptance-list change re-finalizes automatically when needed and requires full renewed validation; no lifecycle body edit or second workflow run is required.
-7. **Maintainer integration accepts:** after reviewing the finalized candidate, an authorized human either manually merges the exact validated head after the stable protected aggregate succeeds or personally enables GitHub native auto-merge for that unchanged head so protected integration waits for the aggregate. That human action means the listed scenarios are accepted. Agents, Apps, bots, merge queue, automation-owned implementation arms, and documentation integration remain forbidden. A changed head, acceptance list, or finalization invalidates the earlier arm and requires the maintainer to choose again.
+7. **Maintainer integration accepts:** after reviewing the finalized candidate, an authorized human manually merges the exact validated head, personally enables GitHub native auto-merge for that unchanged head, or explicitly asks the active agent to merge that identified head while it is currently eligible. The agent route re-reads authoritative state, requires the exact finalized head and acceptance list, current `develop`, successful `Development validation required`, positive mergeability, and the maintainer's authenticated human `User`, then issues one protected squash merge with expected-head enforcement. It never waits, arms auto-merge, retries later, uses automation credentials or merge queue, or bypasses protection. Each route means the listed scenarios are accepted. A candidate change invalidates the decision and requires the maintainer to choose again.
 8. **Verify and clean:** trusted post-merge policy derives `Archived` and reports `accepted-and-archived` from committed bytes and immutable GitHub provenance without editing the accepted PR body. It publishes no lifecycle branch or PR. Shared exact-head remote cleanup may delete the unchanged topic ref; local cleanup remains separately ownership-controlled: the agent parks the worktree with `handoff` at step 7, and the next session's `sweep` removes it once the merge, archive, and remote-ref evidence verify (see [local cleanup](local-worktree-cleanup.md)).
 
+### Maintainer-requested agent merge
+
+The permission is one-shot and candidate-bound. A same-session instruction such as “merge it” is sufficient only when the conversation identifies one handed-off PR and head unambiguously; implementation approval, green CI, an earlier request, or a standing preference is not merge authority. If the PR is not currently eligible, report the blocker and stop. Do not poll, watch, arm native auto-merge, or retain the instruction for later.
+
+Immediately before mutation, refresh the PR and authenticated principal. Require an open non-draft same-repository PR into `develop`, the requested exact finalized head and acceptance list, `MERGEABLE`/`CLEAN` state, successful `Development validation required` for that head, and a human `User` with write, maintain, or admin repository permission. Then use the ordinary protected route with no `--admin` or `--auto`:
+
+```bash
+gh pr merge <pr> --repo <owner>/<repository> --squash --match-head-commit <exact-head-sha>
+```
+
+GitHub branch protection remains authoritative. A refusal, changed head, advanced target, stale finalization, failed or pending check, ambiguous identity, or unavailable read ends the attempt and needs a fresh maintainer request. After success, use the ordinary read-only accepted/archive verification and cleanup path.
+
+The policy PR introducing this route must integrate through the previously deployed maintainer-owned route. Only a later candidate may use a requested agent merge after this policy is present on `develop`.
+
 ### Complete-regression evidence ordering
 
-PR-attached Full regression is selected only for a repair that the trusted triage created from a failed Full regression: base policy verifies the immutable `openspec-ci` App author, generated candidate identity, and `regression-provenance.json`. Human-authored lookalikes, publishing or validation-authority changes, labels, Publish-only repairs, and successful-run persistent-overrun candidates retain bounded ordinary validation. Generated repair drafts run no Development test suites, including after implementation begins. Finish substantive implementation tasks, focused local evidence, pre-finalization observations, and known-gap disposition before marking ready. The ready active head defers testing while trusted finalization publishes the candidate; the finalized head then receives all four native lanes as new full evidence, required by `Development validation required` alongside the existing gates.
+PR-attached Full regression is selected only for a repair that the trusted triage created from a failed Full regression: base policy verifies the immutable `openspec-ci` App author, generated candidate identity, and `regression-provenance.json`. Human-authored lookalikes, publishing or validation-authority changes, labels, Publish-only repairs, and successful-run persistent-overrun candidates retain bounded ordinary validation. Generated repair drafts run no Development test suites, including after implementation begins. Finish substantive implementation tasks, focused local evidence, pre-finalization observations, and known-gap disposition before checking the final Implementation item. The ready active head defers testing while trusted finalization publishes the candidate; the finalized head then receives all four native lanes as new full evidence, required by `Development validation required` alongside the existing gates.
 
 The final exact-head run is a handoff gate, not a task requiring a future run ID in committed `design.md`. Keep final head/run/selection identity in Actions outcomes and the maintainer handoff; do not invalidate successful evidence with an extra recording commit. Changed code, acceptance/body metadata, selection labels, or target baseline requires fresh evidence. A selected PR success removes the additional mandatory Full regression dispatch, but a standalone/manual run never substitutes for selected PR checks. Before deployment, existing separate-dispatch obligations remain. Neither PR validation nor manual regression proves numbered-package nightly publication recovery.
 
@@ -27,7 +41,7 @@ The implementation, synchronized canonical specs, conditional acceptance record,
 
 ## Draft PR body
 
-The first screen should separate purpose from delivery detail, not foreground CI mechanics. Distill `Proposal` into one or two sentences answering why the PR exists, then put two to five concrete points under `Implementation` answering what it will deliver:
+The first screen should separate purpose from delivery detail, not foreground CI mechanics. Distill `Proposal` into one or two sentences answering why the PR exists, then put one or more unchecked, implementation-specific outcomes under `Implementation`, with no fixed maximum. They are a coarse progress summary, not a copy of the detailed OpenSpec task ledger:
 
 ```markdown
 ## Proposal
@@ -36,9 +50,9 @@ Replace the multi-PR OpenSpec handoff with one manually merged development PR wh
 
 ## Implementation
 
-- Keep planning and implementation in the same draft PR.
-- Integrate implementation, synchronized specs, acceptance, and archive atomically.
-- Preserve standalone documentation auto-merge while forbidding automation-owned implementation auto-merge.
+- [ ] Keep planning and implementation in the same draft PR.
+- [ ] Integrate implementation, synchronized specs, acceptance, and archive atomically.
+- [ ] Preserve standalone documentation auto-merge while forbidding automation-owned implementation auto-merge.
 
 ## Automation
 
@@ -50,7 +64,7 @@ Replace the multi-PR OpenSpec handoff with one manually merged development PR wh
 </details>
 ```
 
-Do not add a quoted phase line or a routine `Validation` section listing commands to an initial draft. Actual validation results belong in CI and the eventual implementation handoff. Continue with the same phase-free body after approval. When implementation is complete and ready for required tests, use this visible order:
+Do not add a quoted phase line, generic CI/review/acceptance/merge/archive tasks, run/verify/validate/evidence/manual-test items, or a routine `Validation` section listing commands to an initial draft. Actual validation results belong in CI and the eventual implementation handoff. Continue with the same phase-free body after approval. Toggle only the exact marker when ordinary work completes; body history must not hide a scope change as progress. Historical version-3 bodies with only plain Implementation bullets remain readable, but new bodies use the task-list form. When implementation is complete and ready for required tests, use this visible order:
 
 ```markdown
 ## Proposal
@@ -59,7 +73,8 @@ Do not add a quoted phase line or a routine `Validation` section listing command
 
 ## Implementation
 
-<!-- concrete implementation bullets -->
+- [x] <!-- completed implementation outcome -->
+- [x] <!-- completed implementation outcome -->
 
 ## Acceptance
 
@@ -75,7 +90,7 @@ Do not add a quoted phase line or a routine `Validation` section listing command
 </details>
 ```
 
-Keep acceptance absent during proposal review so unfinished intent is not mistaken for final acceptance criteria. The finalization workflow rewrites only the implementation fence; keep the rest of the phase-free body unchanged through exact-head validation, maintainer review, and authorized integration. The same workflow run validates its finalized delivery record and applicable product/governance scopes before the stable protected aggregate succeeds. Do not add a lifecycle body edit or start a second validation run. After integration, trusted verification derives `Archived`; do not rewrite the accepted body.
+Keep acceptance absent during proposal review so unfinished intent is not mistaken for final acceptance criteria. Every Implementation item must be checked before ready/finalization; those markers report implementation progress and never human acceptance. The finalization workflow rewrites only the implementation fence; keep the rest of the phase-free body unchanged through exact-head validation, maintainer review, and authorized integration. The same workflow run validates its finalized delivery record and applicable product/governance scopes before the stable protected aggregate succeeds. Do not add a lifecycle body edit or start a second validation run. After integration, trusted verification derives `Archived`; do not rewrite the accepted body.
 
 ## Agent scratch files
 
@@ -140,13 +155,25 @@ Use plain bullets:
 - Finalized specs and archive match the implementation.
 ```
 
-The committed conditional manifest contains the same ordered text. Trusted policy validates membership but never checks or edits it and never claims that the scenarios passed. The authorized maintainer's manual merge or personal native auto-merge arm for the unchanged exact head is the acceptance decision; no acceptance comment, checkbox edit, review-approval requirement, JSON edit, acceptance PR, archive PR, or later command is needed.
+Each Implementation and Acceptance item is one line of 20 to 300 bytes. Draft promotion and the delivery body check reject an Implementation item that starts with `Manually`, `Validate`, `Verify`, `Confirm`, `Prove`, `Run`, or `Test`, mentions manual testing, records or captures evidence, or delivers work "with" coverage, evidence, or validation (`implementation-progress-validation`); merged bodies keep their earlier wording. It must not contain angle-bracket text such as `<job>` or other HTML, URLs, or `@` mentions, and Acceptance items must not be checkboxes. Write a concrete example instead of a placeholder, such as `Develop / Build process guardian`.
+
+### Delivery body check
+
+Before checking the final Implementation item, write the intended final body to an ignored artifact file and run the same body validators that trusted promotion uses:
+
+```bash
+node scripts/governance/check-delivery-body.mjs --body-file .artifacts/agent/pr-body.md --final
+```
+
+`--final` validates the body as if every Implementation item were checked, so it can run before the last marker changes. `--pr <n>` reads the current pull request body instead. A defect exits 1 and prints the same `draft-<code>` reason the finalization run would report. The check covers association, Implementation, layout, and Acceptance only; detailed tasks, evidence, and target state remain covered by the [finalization command](#finalization-command) inspection mode.
+
+The committed conditional manifest contains the same ordered text. Trusted policy validates membership but never checks or edits it and never claims that the scenarios passed. The authorized maintainer's direct merge, personal native auto-merge arm, or explicit request for the active agent to merge the unchanged currently eligible exact head is the acceptance decision; no acceptance comment, checkbox edit, review-approval requirement, JSON edit, acceptance PR, archive PR, or later command is needed.
 
 If the body list changes, candidate validation reruns and compares it with the committed manifest. If the head changes, all prior exact-head CI is stale. If only the body changes to disagree with the manifest, integration remains blocked until the list and committed candidate agree again. No lifecycle body edit is needed after green CI.
 
 ## Automated finalization
 
-The `OpenSpec finalization` workflow (`.github/workflows/openspec-finalization.yml`) runs on `pull_request_target` for `synchronize`, `ready_for_review`, `reopened`, and `edited` events of every non-draft PR targeting `develop`, one event at a time per PR. It checks out default-branch policy, installs the pinned tooling without hooks, and runs `scripts/governance/publish-openspec-finalization.mjs --pr <n>`; the PR head enters that process only as the `openspec/` tree the pinned OpenSpec engine reads. Drafts, closed, legacy, and unassociated PRs are skipped. For a version-3 candidate it reconciles the head to its finalized form:
+The `OpenSpec finalization` workflow (`.github/workflows/openspec-finalization.yml`) runs on `pull_request_target` for `opened`, `synchronize`, `ready_for_review`, `converted_to_draft`, `reopened`, and `edited` events targeting `develop`, one event at a time per PR. It checks out default-branch policy, installs the pinned tooling without hooks, and runs `scripts/governance/publish-openspec-finalization.mjs --pr <n>`; the PR head enters that process only as the `openspec/` tree the pinned OpenSpec engine reads. An all-checked version-3 task-list draft with valid Acceptance and complete detailed pre-finalization inputs is re-read as one exact snapshot and marked ready; no content is changed, and incomplete, malformed, legacy, unassociated, forked, or raced drafts remain draft with a stable reason. A draft with any unchecked item is skipped quietly. A finalized PR returned to draft is promoted again when its body still has every item checked, its fence names the exact head as finalized, and the tree holds exactly that archive with no active change; otherwise it stays draft with `draft-finalization-redraft-form`. A draft whose every task-list item is checked but whose promotion is refused for a body, task, evidence, or other content defect fails the run with an `OpenSpec finalization` error annotation naming the `draft-<code>` reason, so the stall shows as a red check instead of a green skip. Closed PRs are skipped. For a ready version-3 candidate the workflow reconciles the head to its finalized form:
 
 - **Active and current:** ordinary finalization with today's UTC date; one `docs(openspec): finalize <change>` commit.
 - **Finalized, valid, and current:** nothing is pushed; the run reports `already-finalized`.
@@ -155,7 +182,7 @@ The `OpenSpec finalization` workflow (`.github/workflows/openspec-finalization.y
 
 The commit is pushed with a lease on the head the run read, so a developer push in between makes the run report `retry` and the next event finishes the work. Only after the push does the workflow `PATCH` the body fence with `finalizedHead` equal to that exact commit, and only when both the body and PR head still match the operation's expected values. The guaranteed head-binding change triggers native `pull_request: edited` validation even when a re-finalization reuses the same archive paths. The workflow's own body edit triggers further runs that report `already-finalized`; an intermediate run with a missing or stale binding defers before product suites and emits no protected aggregate. Every pushed commit is either a merge of the exact `develop` tip or confined to the change's active path, its archive path, and its declared canonical specs.
 
-Because the branch gains commits from the archive App, pull before pushing. A rebase that drops them is harmless: the next push is reconciled from whatever the head contains. Do not revert a finalization commit to make a fix; push the fix and let the workflow re-finalize. When the workflow fails, its summary names the finalization code (`tasks-incomplete`, `acceptance-*`, `delivery-known-gaps`, `openspec-operation`, `finalization-merge-conflict`, ...), nothing is pushed, and `Finalized delivery validation` on the unfinalized head reports that automated finalization is pending.
+Because the branch gains commits from the archive App, pull before pushing. A rebase that drops them is harmless: the next push is reconciled from whatever the head contains. Do not revert a finalization commit to make a fix; push the fix and let the workflow re-finalize. When the workflow fails, its summary names the finalization code (`tasks-incomplete`, `implementation-progress-*`, `acceptance-*`, `delivery-known-gaps`, `openspec-operation`, `finalization-merge-conflict`, ...), nothing is pushed, and `Finalized delivery validation` on the unfinalized head reports that automated finalization is pending.
 
 A missing fence is not an ordinary ready PR when immutable base/head evidence shows that the candidate introduces or restores an active change, or mixes active-change edits with code or operational paths. Base-controlled readiness and finalization both fail with `missing-implementation-association`; deleting editable body metadata cannot bypass finalization. Existing active-change documentation-only revisions and ordinary code PRs without active delivery paths retain their established routes.
 
@@ -163,7 +190,7 @@ If an unassociated implementation has already integrated, do not edit its merged
 
 ## Finalization command
 
-The local command remains available for inspection or when a developer prefers to finalize before marking the PR ready; the workflow then verifies the head and pushes nothing. It has inspection mode by default and an explicit `--write` mode. It never commits, pushes, edits GitHub, marks a PR ready, or merges. Run from the linked worktree and use an ignored artifact body file so the operation can update exact version-3 paths without mutating remote PR state:
+The local command remains available for inspection or when a developer prefers to finalize before the automatic ready transition; the workflow then verifies the head and pushes nothing. It has inspection mode by default and an explicit `--write` mode. It never commits, pushes, edits GitHub, marks a PR ready, or merges. Run from the linked worktree and use an ignored artifact body file so the operation can update exact version-3 paths without mutating remote PR state:
 
 ```bash
 git fetch origin develop
@@ -201,7 +228,7 @@ Before a first finalization, canonical specs must still equal the selected targe
 
 ## Conditional acceptance and derived receipt
 
-`acceptance.md` truthfully says its verdict activates only when an authorized human manually merges the containing exact head after required current-head checks or personally arms native auto-merge for that unchanged head and GitHub integrates it after those checks. Its `openspec-delivery` block records stable pre-merge facts:
+`acceptance.md` truthfully says its verdict activates only when an authorized human directly merges the containing exact head after required current-head checks, explicitly asks the active agent to execute that protected exact-head merge while it is eligible, or personally arms native auto-merge for the unchanged head and GitHub integrates it after those checks. Its `openspec-delivery` block records stable pre-merge facts:
 
 - schema version, repository, change, and source PR;
 - archive and manifest paths and finalization date;
@@ -210,7 +237,7 @@ Before a first finalization, canonical specs must still equal the selected targe
 - archive, canonical-spec, task, and evidence digests; and
 - explicit known-gap dispositions.
 
-It does not predict source head, merge commit, merger, or merge time. The PR head contains the manifest, so required CI binds those bytes without a recursive self-hash. After merge, the shared reader combines the manifest with immutable GitHub source head, successful required run, authorized human actor and permission, integration route, merge commit/time, and `develop` ancestry. Direct manual integration requires no active automatic authority. Human-enabled native auto-merge additionally requires a matching final-head enable event and `auto_merge.enabled_by`, with no later candidate commit or disable event. Queue, App/Bot, automation-owned, stale, malformed, or differently authored authority remains invalid. A human enable followed by disable before a valid manual merge is an abandoned attempt, not contradictory provenance. That shared result is the durable version-3 receipt used by audit and cleanup.
+It does not predict source head, merge commit, merger, or merge time. The PR head contains the manifest, so required CI binds those bytes without a recursive self-hash. After merge, the shared reader combines the manifest with immutable GitHub source head, successful required run, authorized human actor and permission, integration route, merge commit/time, and `develop` ancestry. Direct integration, including an explicitly requested agent invocation through the maintainer's credential, requires no active automatic authority and retains the same authenticated-human merge provenance. Human-enabled native auto-merge additionally requires a matching final-head enable event and `auto_merge.enabled_by`, with no later candidate commit or disable event. Queue, App/Bot, automation-owned, stale, malformed, or differently authored authority remains invalid. A human enable followed by disable before a valid direct merge is an abandoned attempt, not contradictory provenance. That shared result is the durable version-3 receipt used by audit and cleanup.
 
 Unavailable, stale, automatic, unauthorized, conflicting, or contradictory provenance produces `invalid-provenance`/`blocked`, not acceptance. Post-merge code does not repair it by pushing `develop` or publishing another PR.
 
@@ -264,7 +291,7 @@ This bootstrap policy itself finishes under deployed version-2 authority. The fi
 - draft planning remaining unmerged;
 - explicit plan approval and same-PR implementation;
 - automated current-target finalization and exact-head CI;
-- authorized human integration, including manual merge and personally enabled exact-head native auto-merge, with plain acceptance scenarios;
+- authorized human integration, including direct merge, an explicit exact-head agent-merge request, and personally enabled exact-head native auto-merge, with plain acceptance scenarios;
 - integrated canonical specs/archive and no generated acceptance/archive PR;
 - read-only `accepted-and-archived` verification and exact-head branch cleanup;
 - stale head/body/base/arm, incomplete tasks/evidence, malformed manifest, and automated or unauthorized auto-merge refusal fixtures; and

package/docs/validation.md

@@ -6,11 +6,13 @@ Development validation computes one exact base/head selection with:
 npm run select:validation-impact -- --base <full-base-sha> --head <full-head-sha> --output .artifacts/validation/impact.json
 ```
 
-The versioned `config/validation-ownership.json` registry maps stable product and test path groups to a mandatory PR core, affected unit tests, resource-sensitive tests, and integration owners. The initial coarse owners are UI/rendering, launch/startup, release/package/update, Pi, native containment, image/history, governance, and shared product inputs. Each integration owner in `config/integration-owners.json` declares `pull-request` or `exhaustive` cadence. A changed pull-request test selects its owner; a changed exhaustive test selects focused deterministic contracts and records the exhaustive owner as cadence-deferred. Shared support selects every declared PR consumer and records affected exhaustive consumers; copies, renames, and deletions inspect both identities. Reasons and changed paths are recorded in `impact.json`.
+The versioned `config/validation-ownership.json` registry maps stable product and test path groups to a mandatory PR core, an explicit critical floor per owner, changed and bounded transitive consumers, resource-sensitive tests, and integration owners. The coarse owners are UI/rendering, launch/startup, release/package/update, Pi, native containment, image/history, governance, and shared product inputs. Each integration owner in `config/integration-owners.json` declares `pull-request`, `direct-impact`, or `exhaustive` cadence. A changed pull-request test selects its owner; a changed exhaustive test selects focused deterministic contracts and records the exhaustive owner as cadence-deferred. Shared support selects every declared PR consumer and records affected exhaustive consumers; copies, renames, and deletions inspect both identities. Reasons and changed paths are recorded in `impact.json`.
 
-Unknown operational inputs, unavailable comparison history, workflow/selector/suite/aggregate changes, and manual Development dispatch select every pull-request owner. Missing, malformed, or unknown cadence blocks instead of guessing. Documentation-only and version-only changes retain explicit exemptions. An implementation-bound association (an `openspec-implementation` link in the PR body) only disables those two exemptions: the PR core still runs, and owners are still selected by impact rather than forced to conservative coverage. Selection does not require whole-repository source parsing.
+Reviewed `refinements` can narrow a coarse owner's tests and integration links for known subareas: scrollbar/settings, clipboard/editor/repository commands, documentation/cleanup/delivery governance, and development-environment tooling. Each rule keeps an explicit minimum test set; a bounded relative-import graph across `test/`, `src/`, `scripts/`, and `bin/` adds at most 24 sorted transitive consumers per changed path, including consumers outside the coarse owner, and integration owners of those retained consumers. The graph is supplemental, not sole coverage authority. Unreviewed or absent source identities and an unavailable graph retain the coarse owner. Changed tests, shared support, and mixed source/support changes retain their coarse contracts; rename and deletion classification still includes both identities. Some UI changes deliberately select more tests than before because the graph exposes formerly missed shell consumers.
 
-The `changes` job then derives the modular job matrix from that same selection through `scripts/release/validation-matrix.mjs`, which declares every Development modular job and returns only the entries the selection activates; GitHub never schedules an inactive entry, so an ordinary PR does not spend runner minutes on jobs that would resolve to nothing. Each scheduled job still resolves its own owners from the uploaded impact artifact, and the aggregate still requires evidence for every selected owner, so an entry that should have run and did not fails the run.
+Unknown operational inputs, unavailable comparison history, workflow/selector/suite/aggregate changes, and manual Development dispatch select every coarse owner's critical floor and only integration owners with `pull-request` cadence. Direct-impact owners require a changed declared test, support, or production surface; exhaustive owners remain deferred. Missing, malformed, or unknown cadence blocks instead of guessing. Documentation-only and version-only changes retain explicit exemptions. An implementation-bound association (an `openspec-implementation` link in the PR body) only disables those two exemptions: the PR core still runs, and owners are still selected by impact rather than forced to conservative coverage. Selection does not require whole-repository source parsing.
+
+The `changes` job then derives the modular job matrix from that same selection through `scripts/release/validation-matrix.mjs`, which declares every Development modular job and returns only the entries the selection activates; GitHub never schedules an inactive entry, so an ordinary PR does not spend runner minutes on jobs that would resolve to nothing. The matrix uses fail-fast cancellation, so a decisive failure stops remaining cells while missing or cancelled selected evidence still blocks the aggregate. Each scheduled job still resolves its own owners from the uploaded impact artifact, and the aggregate still requires evidence for every selected owner, so an entry that should have run and did not fails the run.
 
 ## Commands and coverage levels
 
@@ -24,22 +26,60 @@ npm run test:full                  # complete deduplicated local composition
 npm run test:release               # release gates; publication authority is unchanged
 ```
 
+Before a push, run only quick targeted checks of what changed; CI after the pull request becomes ready is the validation authority:
+
+```bash
+npm run typecheck                          # type check
+npx vitest run <changed test files...>     # tests covering the changed code
+npx openspec validate <change> --strict    # the OpenSpec change
+```
+
+Do not run preflight, `test:fast`, `test:full`, `test:release`, or directory-wide test runs before pushing. They are for reproducing a failure CI reported, or when the maintainer asks. Preflight is the optional tool for reproducing a fast-gate failure:
+
+```bash
+npm run preflight                  # pull-request validation's fast gates on the committed head
+```
+
+Preflight selects the committed merge-base diff with `origin/develop` exactly as validation does (uncommitted paths are reported, not checked), writes it to `.artifacts/validation/local-impact.json`, and stops at the first failure. It runs the core job's install build and receipt, `typecheck`, `check:architecture`, changed-file code documentation, release documentation, changed-file naming, docs governance, strict OpenSpec validation with the workflow's pinned validator, the delivery-guidance test, and the core job's `pr-core-tests` and `pr-selected-tests` scopes. Each step invokes the script and arguments its workflow job runs, so a failure reports the same rule identifier and path. It never builds the native host, does not run resource-sensitive or integration owners, and CI remains the authority.
+
 `test:pr-core` is not a replacement for `test:fast`: CI combines it with directly changed and coarse-owner tests from the exact impact selection. Selected resource-sensitive tests run independently on an isolated Windows runner. Selected package, startup, rendering, Pi, compatibility, and platform owners also run independently after their actual prerequisites.
 
-Conservative Development retains every pull-request owner but does not schedule exhaustive owners. The complete regression implementation runs inside a PR only when base policy verifies an `openspec-ci` App-created repair, its generated candidate identity, and a failed Full regression source in `regression-provenance.json`. Publishing/prerequisite/validation-authority impact, shared inputs, unknown paths, labels, Publish-only repairs, and successful-run persistent-overrun candidates retain bounded ordinary validation. Planning-only generated repair drafts stay exempt; eligible implementation drafts get feedback without integration authority. The selected exact-head evidence must include Windows Node 22/24, Linux Node 24, and macOS Node 24. Full regression and nightly/stable release retain both cadence classes and the same coverage through the shared implementation. The real three-release `update-predecessor` exact-package oracle is exhaustive; deterministic predecessor command, fixture, materialization, warmup, package, and update contracts remain PR-eligible. Preview and release continue to consume exact candidate bytes under their channel-specific contracts. A standalone manual Full regression remains useful for diagnosis or an unselected candidate, but never replaces automatically selected current-PR evidence. The generated ownership ledger command is:
+Conservative Development retains every critical owner floor and the small set of `pull-request` integration owners, while scheduling only directly affected `direct-impact` owners and deferring all exhaustive owners. The complete regression implementation runs inside a PR only when base policy verifies an `openspec-ci` App-created repair, its generated candidate identity, and a failed Full regression source in `regression-provenance.json`. Publishing/prerequisite/validation-authority impact, shared inputs, unknown paths, labels, Publish-only repairs, and successful-run persistent-overrun candidates retain bounded ordinary validation. Planning-only generated repair drafts stay exempt; eligible implementation drafts get feedback without integration authority. The selected exact-head evidence must include Windows Node 22/24, Linux Node 24, and macOS Node 24. Full regression and nightly/stable release retain both cadence classes and the same coverage through the shared implementation. The real three-release `update-predecessor` exact-package oracle is exhaustive; deterministic predecessor command, fixture, materialization, warmup, package, and update contracts remain PR-eligible. Preview and release continue to consume exact candidate bytes under their channel-specific contracts. A standalone manual Full regression remains useful for diagnosis or an unselected candidate, but never replaces automatically selected current-PR evidence. The generated ownership ledger command is:
 
 ```bash
 node scripts/release/generate-validation-ownership-ledger.mjs --output .artifacts/validation/ownership-ledger.json
 ```
 
-The `terminal-host` owner is CI-only. A change under `native/terminal-host/` or to its run scripts selects the Windows x64 **Native terminal host (Windows)** job, which builds the crate with pinned Rust and Zig 0.15.2, runs `npm run test:terminal-host`, and uploads the debug executable. Local Windows builds fail in `build.rs` unless `TERMINAL_HOST_LOCAL_BUILD=1` is set, because Zig's package fetch unpacks test data that workstation antivirus quarantines along with the installed process guardian. See [`native/terminal-host/README.md`](../native/terminal-host/README.md).
+Containment-selected modular jobs build and test the debug `process-guardian.node` addon for their exact platform, export `A1_PROCESS_GUARDIAN_PATH` to that file, and run the launch-owner integration fixtures as Node processes. The tests exercise the real addon-held Windows job or Unix process group, addon-backed identity and terminal operations, and the Node exit watcher; no fixture invokes a process-guardian executable. The Windows startup lane keeps Defender real-time protection enabled while packaged startup loads the release addon.
+
+The `terminal-host` owner is CI-only. A change under `native/terminal-host/` or to its run scripts selects, per platform (Windows x64, Linux x64, macOS arm64), one **Native terminal host** job and three **Native terminal host tests** partition jobs. The partition jobs each build the test profile and run one third of the serialized `role_integration` suite (`run-terminal-host-probe.mjs --partition <i>/3`, partitioned by sorted test name read from the suite's source); the feature-gated `role-host` binary stands in only for the fixed role grammar inside Rust integration tests and is never packaged. The build-and-probe job runs `npm run test:terminal-host` with the role suite skipped (`TERMINAL_HOST_PARTITION=none`), building `terminal-host.node` with Rust, Node-API 9, and Zig 0.15.2 for the lane's exact target and baseline CPU model. It loads the addon for its version and non-interactive probes, verifies the shared session-writer lock export, and uploads the debug addon and frozen protocol manifest; Linux also runs bounded decoder fuzzing.
+
+The protected aggregate requires every partition of every selected platform, keyed by `partition` in the outcome authority and job envelope. Because the role suite no longer warms the resident launch paths in the build-and-probe job, its certification step runs one unmeasured `measure-resident-tabs.mjs` pass before the measured pass whose budgets are unchanged. Fidelity, latency, chaos, and certification start roles as `process.execPath dist/foundation/resident-tabs/host-entry.js` with `A1_TERMINAL_HOST_PATH` naming the addon. Windows cleanup identifies those Node-hosted residents by command line; it never kills every `node.exe` by image name. Locally, `npm run test:terminal-host` without a partition is unchanged and runs everything in one process. Local Windows builds fail in `build.rs` unless `TERMINAL_HOST_LOCAL_BUILD=1` is set, because Zig's package fetch unpacks test data that workstation antivirus quarantines. Native lanes also publish the terminal library they linked; a local build can link it instead of running Zig (see Local native iteration in [`architecture/resident-tabs.md`](architecture/resident-tabs.md)), which is development evidence only and never replaces selected CI. `TERMINAL_HOST_CONTRACTS_ONLY=1` is a library-only diagnostic and cannot substitute for selected CI. See [`native/terminal-host/README.md`](../native/terminal-host/README.md).
+
+## Coverage-preserving efficiency
+
+Complete regression selects the full rendering scope instead of also executing its superseded smoke files. Full captures call the same smoke assertions, including independent producer identity, readiness, semantic parity, synchronization, and bounded paint checks. Smoke-only corrupted-evidence controls live in an ordinary deterministic test. Scheduled content runs once in each gate through the same owned-versus-pinned helper. The retained full matrix has 11 streaming workloads across three producers and two modes, two scheduled-content workloads across two producers, and six input workloads batched across three producers: 73 matrix launches plus 10 protocol-failure launches. Standalone smoke retains 19 launches. Full regression avoids the additional 19 smoke launches; it does not remove a workload or platform lane.
+
+The coverage ledger test reconstructs every full-plan invocation and requires each retained file exactly once, except the two smoke files whose executed replacement contracts it names explicitly. Unit, shell integration, source/emitted entries, independent pinned parity, security/race controls, and runtime-specific tests are not interchangeable merely because they touch the same module.
+
+The package-command transcript fixture uses four file-owned producer processes (owned/pinned times color 0/1), rather than starting 22 equivalent loaders. Every request still runs the real command with its independent home/settings and fresh transcript; failed producers are never restarted. Fresh-home isolation and process disposal are tested. Cold-entry contracts elsewhere retain their cold process boundary. Git cleanup scenarios still initialize their own real repository/worktree, but write private Git configuration once instead of launching four config/remote commands. Release fixtures create baseline refs in one real atomic ref transaction. Setup remains inside the owning scenario and no mutable fixture repository is shared.
+
+Exact-package identity walks hash each payload as it is read, retain only file digests, and parse the manifest from that same walk. They keep the original digest contract, all pre/post consumer verifications, fresh prefixes, and separate shard installations. This removes duplicate manifest reads and full-payload buffering; it does not cache verification results or promise a material improvement to npm installation time.
+
+Generate a content-free per-file inventory and optional observed timing report from an existing Actions run and log:
+
+```bash
+node scripts/release/validation-cost-report.mjs --run .artifacts/agent/completed-run.json --log .artifacts/agent/job.log --output .artifacts/validation/cost-report.json
+```
+
+The run JSON is the output of `gh run view RUN --json jobs,headSha,createdAt,updatedAt`; the log is from that same run's chosen job. Omit both inputs for inventory only. Reports are observational, never validation receipts. They identify source drift, each retained file's coarse owner/execution class, job and step duration, total runner time, longest job, workflow elapsed time, and runner span. Queue and DAG critical-path timing remain unavailable rather than guessed. File timings preserve repeated observations; never add concurrent job/file durations and call the result elapsed savings. Compare comparable completed runs before claiming a hosted speedup. No passing outcomes, installed trees, or mutable fixture state may be cached by these optimizations.
 
 ## Windows Full regression shards
 
-Standalone and PR-attached Full regression run each Windows runtime (Node 22 and Node 24) as four hosted-runner shards derived from the one canonical `full-release` plan: `core` (command gates and the bounded-parallel ordinary remainder), `resource` (the serial resource-sensitive invocation with its unchanged explicit bound), `rendering` (the serial isolated rendering invocation), and `package` (packing, the shared exact-package installation, Defender-backed first-attempt startup before package contracts, package smoke, update timing, and the exhaustive published-predecessor invocation). Each shard checks out, installs, builds, and records its own build receipt; only the package shard packs and installs the candidate. Linux, macOS, local `npm run test:full`, and publication validation keep one sequential complete plan.
+Standalone and PR-attached Full regression run each Windows runtime (Node 22 and Node 24) as five hosted-runner shards derived from the one canonical `full-release` plan: `core` (command gates and the bounded-parallel ordinary remainder), `resource` (the serial resource-sensitive invocation with its unchanged explicit bound), `rendering` (the serial isolated rendering invocation), `package` (packing, its own exact-package installation, Defender-backed first-attempt startup before package contracts, package smoke, and update timing), and `predecessor` (packing, its own exact-package installation, and the exhaustive published-predecessor invocation, which took 11 to 12 minutes of the former package shard on Windows). Each shard checks out, installs, builds, and records its own build receipt; the package and predecessor shards each pack and install their own candidate, and no installed state crosses shards. Linux, macOS, local `npm run test:full`, and the sequential publication lanes keep one complete plan with one shared installation.
 
 ```
-node scripts/release/run-validation-tier.mjs --full-shard <core|resource|rendering|package> --result <path>
+node scripts/release/run-validation-tier.mjs --full-shard <core|resource|rendering|package|predecessor> --result <path>
 ```
 
 `partitionFullRegressionPlan` assigns every canonical command and Vitest invocation to exactly one shard and rejects unknown or duplicate work; the build is the only per-shard prerequisite. Each shard result carries its shard identity, assigned work, and the canonical-plan digest. A per-runtime collector job reconstructs one ordinary `a1-validation-outcomes-v1` result only when all four current-run shards for the exact source, runtime, run, attempt, and plan passed and each reported exactly its assigned work; the reconstructed result then binds the unchanged `windows-2025-node22` or `windows-2025-node24` lane, and the required aggregate still demands exactly four lanes. The collector's summary reports each shard's time and the elapsed span across overlapping shards. Nightly triage maps a failed shard's owners to the canonical Windows lane and names the shard job, and it rejects more than one startup evidence file for a lane.
@@ -106,10 +146,10 @@ Download these artifacts from the exact workflow run:
 
 For selected implementation candidates, record focused and pre-finalization full observations before finalization. Keep final head/run/selection identity in Actions and handoff rather than adding a post-success commit that invalidates that evidence. A successful selected PR run replaces an additional mandatory dispatch; standalone runs remain diagnostic, and numbered-package nightly recovery remains independent.
 
-Draft pull requests run no Development test suites. A ready version-3 PR whose body still identifies an active change defers testing and emits no protected aggregate while `OpenSpec finalization` publishes the candidate. A ready unassociated PR also fails closed when immutable base/head evidence shows that it introduces or restores active delivery content, or combines active-change edits with code or operational paths; it does not fall through to ordinary validation merely because its body fence is absent. Existing active-change documentation-only revisions and ordinary code PRs without active delivery paths retain their established routes. After finalization records the archive and acceptance manifest, the ordinary exact-head workflow runs selected product/governance lanes and `Finalized delivery validation` in parallel, then emits the stable protected `Development validation required` aggregate only when both authorities succeed. Green CI enables maintainer review and manual merge but does not claim human acceptance or merge automatically. The finalization fence update is the validation trigger, so no pre-finalization test run or later lifecycle body edit is required. Any subsequent eligible implementation commit changes the head and reruns applicable validation; any body change reruns readiness and finalized-record validation and must continue to match the committed manifest. Legacy acceptance-record-only PRs retain their separate trusted `Acceptance record validation` route. Queue availability remains explicitly unavailable inside a runner and is calculated from the Actions API during final run analysis rather than guessed.
+Draft pull requests run no Development test suites. A ready version-3 PR whose body still identifies an active change defers testing and emits no protected aggregate while `OpenSpec finalization` publishes the candidate. A ready unassociated PR also fails closed when immutable base/head evidence shows that it introduces or restores active delivery content, or combines active-change edits with code or operational paths; it does not fall through to ordinary validation merely because its body fence is absent. Existing active-change documentation-only revisions and ordinary code PRs without active delivery paths retain their established routes. After finalization records the archive and acceptance manifest, the ordinary exact-head workflow runs selected product/governance lanes and `Finalized delivery validation` in parallel, then emits the stable protected `Development validation required` aggregate only when both authorities succeed. Green CI enables maintainer review and an explicit integration decision but does not claim human acceptance or merge automatically. After green exact-head validation, the maintainer may directly merge, personally arm native auto-merge, or explicitly ask the active agent to perform one expected-head protected squash merge for that currently eligible candidate. The finalization fence update is the validation trigger, so no pre-finalization test run or later lifecycle body edit is required. Any subsequent eligible implementation commit changes the head and reruns applicable validation; any body change reruns readiness and finalized-record validation and must continue to match the committed manifest. Legacy acceptance-record-only PRs retain their separate trusted `Acceptance record validation` route. Queue availability remains explicitly unavailable inside a runner and is calculated from the Actions API during final run analysis rather than guessed.
 
 ## Rollback
 
 To disable selective execution without reducing PR coverage, use manual Development dispatch or force conservative ownership selection. To restore the historical predecessor oracle to every applicable PR, change its cadence from `exhaustive` to `pull-request`; do not delete it from Full/nightly/release. To disable prior-attempt reuse, require all accepted attempts to equal the aggregate attempt; this must not remove attempt-qualified artifacts or failure visibility. To disable prerequisite reuse, unset readiness/tarball variables and receipt paths so tier orchestration rebuilds and repacks.
 
-Rollback must retain every test, startup budget, zero automatic retry policy, platform/runtime lane, exact-package identity, resource isolation, complete fast/full/release compositions, and the single stable protected-branch aggregate.
+Rollback must retain complete Full/nightly/release test coverage, startup budgets, zero automatic retry policy, required release platform/runtime lanes, exact-package identity, resource isolation, and the single stable protected-branch aggregate. It must not restore owner-wide or unrelated exhaustive execution to ordinary pull requests.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timurproko/a1",
-  "version": "0.2.6",
+  "version": "0.2.7-dev.1221",
   "description": "Standalone terminal workspace for supervised native and managed agents",
   "type": "module",
   "privateLaunchContract": "neutral-launch-v1",
@@ -23,10 +23,14 @@
   },
   "scripts": {
     "clean": "node scripts/clean.mjs",
-    "build": "node scripts/development/check-environment.mjs && npm run clean && tsc -p tsconfig.build.json && node scripts/release/generate-release-notes-resource.mjs && node scripts/pi/build-pi-settings-metadata.mjs && node scripts/pi/build-startup-public.mjs && node scripts/development/build-process-guardian.mjs && node scripts/release/generate-runtime-payload-inventory.mjs",
+    "build": "node scripts/development/run-build.mjs",
+    "build:core": "node scripts/development/run-build.mjs --core",
+    "build:managed": "npm run clean && tsc -p tsconfig.build.json && node scripts/release/generate-release-notes-resource.mjs && node scripts/pi/build-pi-settings-metadata.mjs && node scripts/pi/build-startup-public.mjs && node scripts/development/build-process-guardian.mjs",
     "build:process-guardian": "node scripts/development/build-process-guardian.mjs",
+    "build:terminal-host": "node scripts/development/build-terminal-host.mjs",
     "typecheck": "tsgo -p tsconfig.json --noEmit && tsgo -p tsconfig.bin.json",
-    "check:architecture": "node scripts/governance/check-architecture.mjs && node scripts/governance/check-product-identity-boundaries.mjs && node scripts/governance/check-package-identity.mjs && node scripts/governance/check-pinned-pi-source-ledger.mjs && node scripts/governance/check-terminal-host-provenance.mjs",
+    "check:architecture": "node scripts/governance/check-architecture.mjs && node scripts/governance/check-session-writer-guard.mjs && node scripts/governance/check-product-identity-boundaries.mjs && node scripts/governance/check-package-identity.mjs && node scripts/governance/check-pinned-pi-source-ledger.mjs && node scripts/governance/check-terminal-host-provenance.mjs",
+    "preflight": "node scripts/development/run-preflight.mjs",
     "check:names": "node scripts/governance/product-identifier-policy.mjs --check",
     "check:names:changed": "node scripts/governance/product-identifier-policy.mjs --check --selection .artifacts/validation/impact.json",
     "check:code-documentation": "node scripts/governance/check-code-documentation.mjs --mode full",
@@ -49,6 +53,8 @@
     "test:full": "node scripts/release/run-validation-tier.mjs full-release",
     "test:release": "node scripts/release/run-release-gates.mjs",
     "test:terminal-host": "node scripts/development/run-terminal-host-probe.mjs",
+    "test:resident-parallel-progress": "node scripts/development/verify-resident-parallel-progress.mjs",
+    "test:resident-chaos": "node scripts/development/run-resident-chaos.mjs --build",
     "test:pi-engine-conformance": "vitest run test/integrations/pi/engine/conformance.test.ts test/integrations/pi/engine/runtime-integration.test.ts test/integrations/pi/engine/session-integration.test.ts",
     "report:pi-engine-conformance": "npm run build --silent && node scripts/pi/run-pi-engine-conformance.mjs",
     "report:rendering-stability": "tsx scripts/pi/report-rendering-stability.ts",
@@ -57,20 +63,22 @@
     "update:pi-component-parity": "tsx scripts/pi/update-pi-component-parity.ts",
     "update:pi-event-frame-parity": "tsx scripts/pi/update-pi-event-frame-parity.ts",
     "proof:terminal-host": "node scripts/development/run-terminal-host.mjs",
+    "proof:terminal-host:ci": "node scripts/development/certify-ci-terminal-host.mjs",
     "start": "npm run build && node scripts/development/dev-launch.mjs",
     "start:pi": "npm run build && node scripts/development/dev-launch.mjs pi",
     "prepack": "node scripts/release/validate-packaged-release-note.mjs && node scripts/release/prepack-gate.mjs",
     "prepublishOnly": "npm run test:release",
-    "prepare": "npm run build",
+    "prepare": "npm run build:core",
     "typecheck:bin": "tsgo -p tsconfig.bin.json"
   },
   "dependencies": {
-    "@earendil-works/pi-coding-agent": "1.1.0",
-    "@earendil-works/pi-tui": "1.1.0",
+    "@earendil-works/pi-coding-agent": "1.4.0",
+    "@earendil-works/pi-tui": "1.4.0",
     "@silvia-odwyer/photon-node": "0.3.4",
     "chalk": "5.6.2",
     "cross-spawn": "7.0.6",
     "grok-mermaid": "0.2.2",
+    "proper-lockfile": "4.1.2",
     "semver": "7.8.5",
     "undici": "8.9.0"
   },
@@ -79,6 +87,7 @@
     "@lezer/python": "1.1.19",
     "@types/cross-spawn": "6.0.6",
     "@types/node": "24.2.1",
+    "@types/proper-lockfile": "4.1.4",
     "@types/semver": "7.8.0",
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
     "@xterm/headless": "6.0.0",
@@ -107,5 +116,9 @@
   },
   "optionalDependencies": {
     "@mariozechner/clipboard": "^0.3.9"
+  },
+  "publication": {
+    "source": "81d81ade9416f501305300eafaafd2972b0efafb",
+    "pullRequest": 846
   }
 }

package/dist/foundation/process-containment/darwin-process-inspector.d.ts

@@ -1,5 +0,0 @@
-import { WindowsNativeProcessInspector, type InspectorCommandRunner } from "./windows-process-inspector.js";
-/** Verifies Darwin process identity through the bounded native guardian inspection command. */
-export declare class DarwinNativeProcessInspector extends WindowsNativeProcessInspector {
-    constructor(helperPath: string, runner?: InspectorCommandRunner);
-}

package/dist/foundation/process-containment/darwin-process-inspector.js

@@ -1,7 +0,0 @@
-import { WindowsNativeProcessInspector } from "./windows-process-inspector.js";
-/** Verifies Darwin process identity through the bounded native guardian inspection command. */
-export class DarwinNativeProcessInspector extends WindowsNativeProcessInspector {
-    constructor(helperPath, runner) {
-        super(helperPath, runner, "darwin-proc-start:");
-    }
-}

package/dist/foundation/process-containment/native-guardian-containment.js

@@ -1,152 +0,0 @@
-import { spawn } from "node:child_process";
-import { mkdir, readFile, rm } from "node:fs/promises";
-import { dirname, resolve } from "node:path";
-import { PRODUCT_IDENTITY } from "../../product-identity.js";
-/** Delegates one root runtime to the native guardian and exposes its verified containment identity. */
-export class NativeGuardianContainment {
-    #identity;
-    #helper = null;
-    #rootIdentity = null;
-    #outcome = null;
-    instanceId;
-    helperPath;
-    statusPath;
-    exitNoticePath;
-    constructor(instanceId, helperPath, statusPath, exitNoticePath = null) {
-        this.instanceId = instanceId;
-        this.helperPath = helperPath;
-        this.statusPath = statusPath;
-        this.exitNoticePath = exitNoticePath;
-        this.#identity = { provider: "native-guardian-pending", token: instanceId };
-    }
-    get identity() {
-        return this.#identity;
-    }
-    async spawn(executable, arguments_, options) {
-        if (this.#helper)
-            throw new Error("process containment already has a root runtime");
-        await mkdir(dirname(this.statusPath), { recursive: true, mode: 0o700 });
-        await rm(this.statusPath, { force: true });
-        if (this.exitNoticePath)
-            await rm(this.exitNoticePath, { force: true });
-        const helper = spawn(this.helperPath, [
-            "--parent-pid", String(process.pid),
-            "--instance", this.instanceId,
-            "--status-file", this.statusPath,
-            ...(this.exitNoticePath ? ["--exit-notice", this.exitNoticePath] : []),
-            "--", executable, ...arguments_,
-        ], {
-            cwd: options.cwd,
-            env: {
-                ...options.environment,
-                ...(options.terminalType ? { TERM: options.terminalType } : {}),
-                // Protocol: the runtime arms this notice and the guardian prints it if the runtime dies unclean.
-                ...(this.exitNoticePath ? { [PRODUCT_IDENTITY.environment.exitNoticePath]: this.exitNoticePath } : {}),
-            },
-            shell: false,
-            stdio: "inherit",
-            windowsHide: false,
-        });
-        this.#helper = helper;
-        this.#outcome = helperOutcome(helper);
-        const status = await waitForReadyStatus(this.statusPath, this.#outcome, 5_000);
-        this.#rootIdentity = { pid: status.pid, startIdentity: status.startIdentity };
-        this.#identity = { provider: status.containmentProvider, token: status.containmentToken };
-        return { identity: this.#rootIdentity, outcome: this.#outcome };
-    }
-    async contains(identity) {
-        return this.#rootIdentity !== null
-            && identity.pid === this.#rootIdentity.pid
-            && identity.startIdentity === this.#rootIdentity.startIdentity;
-    }
-    async stop(force) {
-        const root = this.#rootIdentity;
-        if (!root)
-            return;
-        try {
-            process.kill(root.pid, force ? "SIGKILL" : "SIGTERM");
-        }
-        catch { }
-    }
-    async waitForEmpty(timeoutMs) {
-        if (!this.#helper || this.#helper.exitCode !== null || this.#helper.signalCode !== null)
-            return true;
-        return await new Promise(resolvePromise => {
-            const timer = setTimeout(() => finish(false), timeoutMs);
-            timer.unref();
-            const finish = (empty) => {
-                clearTimeout(timer);
-                this.#helper?.off("close", onClose);
-                resolvePromise(empty);
-            };
-            const onClose = () => finish(true);
-            this.#helper?.once("close", onClose);
-        });
-    }
-    async close() {
-        const helper = this.#helper;
-        if (helper && helper.exitCode === null && helper.signalCode === null)
-            helper.kill("SIGKILL");
-        await this.waitForEmpty(1_500);
-        await rm(this.statusPath, { force: true });
-        if (this.exitNoticePath)
-            await rm(this.exitNoticePath, { force: true });
-    }
-}
-export function resolveProcessGuardianPath(releaseRoot, environment = process.env, platform = process.platform, architecture = process.arch) {
-    const override = environment[PRODUCT_IDENTITY.environment.processGuardianPath]?.trim();
-    if (override)
-        return resolve(override);
-    const executable = platform === "win32"
-        ? `${PRODUCT_IDENTITY.artifacts.processGuardianExecutable}.exe`
-        : PRODUCT_IDENTITY.artifacts.processGuardianExecutable;
-    return resolve(releaseRoot, "dist", "native", `${platform}-${architecture}`, executable);
-}
-function helperOutcome(helper) {
-    return new Promise(resolvePromise => {
-        let settled = false;
-        const settle = (outcome) => {
-            if (settled)
-                return;
-            settled = true;
-            resolvePromise(outcome);
-        };
-        helper.once("error", error => settle({ kind: "guardian-error", message: error.message, code: errorCode(error) }));
-        helper.once("close", (code, signal) => {
-            if (signal)
-                settle({ kind: "signaled", signal });
-            else
-                settle({ kind: "exited", exitCode: code ?? 1 });
-        });
-    });
-}
-async function waitForReadyStatus(path, outcome, timeoutMs) {
-    const deadline = Date.now() + timeoutMs;
-    let terminalOutcome = null;
-    void outcome.then(value => { terminalOutcome = value; });
-    while (Date.now() < deadline) {
-        try {
-            const value = JSON.parse(await readFile(path, "utf8"));
-            if (isReadyStatus(value))
-                return value;
-            throw new Error("process guardian published invalid ready status");
-        }
-        catch (error) {
-            if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
-                throw error;
-        }
-        if (terminalOutcome)
-            throw new Error(`process guardian exited before readiness: ${JSON.stringify(terminalOutcome)}`);
-        await new Promise(resolvePromise => setTimeout(resolvePromise, 20));
-    }
-    throw new Error(`process guardian did not publish readiness within ${timeoutMs}ms`);
-}
-function isReadyStatus(value) {
-    return Number.isSafeInteger(value.pid) && Number(value.pid) > 0
-        && typeof value.startIdentity === "string" && value.startIdentity.length > 0
-        && typeof value.containmentProvider === "string" && value.containmentProvider.length > 0
-        && typeof value.containmentToken === "string" && value.containmentToken.length > 0;
-}
-function errorCode(error) {
-    return "code" in error && typeof error.code === "string" ? error.code : null;
-}