@timurproko/a1 0.1.1-dev.5 → 0.1.1-dev.7

package/docs/ci-release-runbook.md

@@ -1,63 +1,59 @@
 # CI and release operations
 
-This runbook is the operational source for scoped development validation, immutable npm candidates, stable certification, and branch enforcement. GitHub Actions is the only automation platform.
+GitHub Actions is the only automation platform. Two required checks protect the branches:
 
-## Stable status names
-
-Repository rules use job display names, not internal job keys. Keep these names stable:
-
-| Protected flow | Required check | Producer |
+| Branch | Required check | Produced by |
 | --- | --- | --- |
-| Pull request into `develop` | `Development validation required` | `.github/workflows/ci.yml` |
-| Accepted `develop` commit | `Development validation required` | `.github/workflows/ci.yml` push run |
-| Promotion into `master` | `Stable candidate required` | `.github/workflows/certify-stable.yml` |
+| `develop` | `Development validation required` | `.github/workflows/ci.yml` |
+| `master` | `Stable candidate required` | `.github/workflows/certify-stable.yml` |
 
-Matrix and tier job names are implementation details. Change a required name only by updating the reviewable ruleset definition, its governance tests, this runbook, and the live ruleset together.
+These are job display names. If you rename one, update the ruleset definition, this runbook, and the live ruleset together.
 
-## Advisory rollout and widening validation
+## How much validation runs when
 
-New or materially changed selection rules run in advisory mode before their check becomes required. Compare at least one feature-only change and one cross-cutting change with a complete run. A selection miss is a policy defect: widen `config/validation-impact.json`, add a regression test, and rerun complete validation before enabling enforcement.
+| Change | Validation |
+| --- | --- |
+| Docs or specs only | OpenSpec strict lint, nothing else |
+| Any code PR into `develop` | Fast tier: typecheck, architecture checks, unit/contract tests |
+| Preview candidate (`next`) | Fast tier + package gates: content, clean install, dependency policy |
+| Stable candidate (`latest`) | Complete suite on Windows, Linux, and macOS + physical evidence |
 
-The selector can only widen validation. To override an affected plan, dispatch **Development validation** at the exact `develop` ref with `full: true`. This selects `full-release`; it cannot suppress mandatory tiers. Dispatch **Full regression** for the complete non-physical package and clean-install path. Scheduled Full regression is also the backstop for impact-map mistakes.
+Need more coverage for a risky preview? Dispatch the candidate with `full: true`, or run the **Full regression** workflow on demand.
 
-When selection is uncertain, deleted, renamed, unmapped, or based on an unavailable Git range, it must fail closed to full validation. Do not bypass this fallback with labels or edited workflow inputs.
+## Publish a preview to npm `next`
 
-## Preview candidate and `next` publication
+1. Make sure `Development validation required` is green on the `develop` tip.
+2. Dispatch **Build npm next candidate** with the exact commit and `confirm_candidate=build-uncertified-next-candidate`.
+3. Check the resulting `candidate-evidence.json`: gates passed, package integrity matches.
+4. Approve the `npm-next` environment and dispatch **Publish npm next** with the candidate run id.
 
-1. Confirm `Development validation required` is green for the exact `develop` tip.
-2. Dispatch **Build npm next candidate** on `develop` with the exact source commit, a trusted ancestor base commit, and `confirm_candidate=build-uncertified-next-candidate`. Use `full: true` whenever ordinary affected coverage is not sufficient for the release decision.
-3. Review `candidate-evidence.json`, selected scopes, gate outcomes, package integrity, and source tree. The candidate remains explicitly stable-ineligible.
-4. Approve the protected `npm-next` environment and dispatch **Publish npm next** with the successful candidate run id and `confirm_next=publish-certified-next`.
-5. The publisher downloads and verifies the certified tarball, then publishes those bytes without checkout, installation, build, or tests. Verify its registry digest and `next` tag result.
+The publisher uploads the exact validated tarball — it never rebuilds. Candidates expire after 14 days; an expired or mismatched artifact means building a new candidate, not patching the old one.
 
-Preview candidates expire after 14 days. An expired, missing, failed, or mismatched artifact is never reconstructed in the publisher. Build and certify a new candidate.
+## Publish a stable release to npm `latest`
 
-## Stable candidate, physical evidence, and `latest` publication
+1. Commit the final version to `develop` (clean tree, version not yet on the registry).
+2. Dispatch **Build stable candidate** — it packs once and validates the same bytes on all three platforms.
+3. Dispatch **Certify stable physical platforms** on the dedicated isolated workers (they set `PHYSICAL_WORKER_ISOLATED=true` and run under the `stable-physical` environment). Never run physical host probes on a developer workstation.
+4. Dispatch **Certify stable candidate** with both run ids. `Stable candidate required` passes only when every verdict binds the same commit, version, and digest.
+5. Merge that exact commit to `master`, tag it `v<version>`, and dispatch **Publish npm stable**, then approve `npm-stable`.
 
-1. Commit the final non-prerelease version to `develop`. Confirm it is clean, registry-unpublished, and `v<package-version>` is the intended tag.
-2. Dispatch **Build stable candidate** on that exact `develop` commit with `confirm_candidate=build-stable-candidate`. It packs once on Windows and fans the same verified digest to Windows, Linux, and macOS complete automated validation and clean installation.
-3. Review the `Stable automated candidate` artifact. It is not stable-eligible; physical evidence is still required.
-4. On dedicated isolated workers only, dispatch **Certify stable physical platforms** for the same source and automated-candidate run with `confirm_isolated=run-isolated-physical-certification`. Workers must carry `self-hosted`, `a1-physical`, and platform-specific labels, set `PHYSICAL_WORKER_ISOLATED=true`, and be protected by the `stable-physical` environment. Never run physical host probes on a developer workstation or ordinary hosted runner.
-5. Dispatch **Certify stable candidate** with the successful automated and physical run ids and `confirm_certification=certify-stable-candidate`. `Stable candidate required` passes only when all three automated and all three isolated physical verdicts bind the same commit, tree, version, integrity, and shasum.
-6. Promote that exact commit to `master` without source or package changes and create `v<version>` at the same commit. The protected `master` rule requires the existing `Stable candidate required` check on that commit.
-7. Dispatch **Publish npm stable** on the tag with the certification run id and `confirm_stable=publish-certified-stable-latest`, then approve `npm-stable`. It requires the current `master` and tag to equal the certified source, confirms the version is unpublished, publishes the exact tarball to `latest` with provenance, and verifies registry bytes.
+Stable artifacts expire after 30 days. The same rule as previews applies: publication still requires exact certified bytes. Never upload locally rebuilt bytes, and never route around certification by rebuilding inside a publisher.
 
-Stable automated and physical candidate artifacts expire after 30 days. Publication evidence is retained for 90 days. Artifact expiry requires a new pack and complete recertification; it does not permit repacking during publication.
+## When something fails
 
-## Failure recovery
+- **PR validation fails:** fix the code and push. Do not mark a failed tier optional.
+- **Candidate validation fails:** discard the candidate and build a new one after the fix.
+- **Physical worker fails:** fix or replace the worker, then rerun the full physical evidence for the candidate.
+- **Publisher fails before npm accepted the bytes:** diagnose and retry with the same candidate while it is unexpired and the version is still unpublished.
+- **Publisher is uncertain after npm accepted the bytes:** stop. Check the registry for the version, tag, and digest. Repair a dist-tag only as a separate reviewed operation — never republish.
 
-- **Development failure:** inspect impact and outcome artifacts. Fix the source or mapping and rerun. Do not mark a failed tier optional.
-- **Candidate validation failure:** discard the candidate. Any source change, package change, or uncertain evidence requires a new candidate run.
-- **Physical failure:** quarantine the worker result, fix or replace the isolated worker, and rerun all evidence needed for one exact package. A hosted matrix cannot substitute for physical evidence.
-- **Approval or artifact expiry:** create and certify a new candidate. Never upload locally rebuilt bytes.
-- **Publisher failure before npm accepts bytes:** retain the candidate and diagnose identity, permissions, registry, or provenance. Retry only with the same candidate run if the registry still proves the version unpublished and the artifact has not expired.
-- **Publisher uncertainty after npm accepts bytes:** do not republish or rebuild. Query the registry for version, dist-tag, integrity, and shasum; repair a dist-tag only through a separately reviewed registry operation.
-- **Partial stable certification:** stable eligibility remains false. Missing, duplicated, failed, non-isolated, or mismatched platform evidence fails closed.
+## Why the rulesets look the way they do
 
-## Enforcement rollout and rollback
+One person maintains this repository, and GitHub does not let a PR author approve their own PR. Requiring even one approval would therefore deadlock the authorized solo-maintainer path — no PR could ever merge. So both rulesets require a pull request, a green required check, and resolved review threads, but set required approving reviews to zero.
 
-Ruleset mutation is a separate administrative operation. First run `node scripts/check-github-rulesets.mjs` in report mode and review the proposed diff. Apply only after workflows exist on the default branch, representative advisory runs pass, and a maintainer explicitly confirms the exact ruleset change. Capture the post-apply repository API response as evidence.
+- `develop` does not require the branch to be up to date: once a PR is approved and green, it merges even if unrelated work landed first — no re-validation loop.
+- `master` does require it: a stable promotion always validates the exact final state.
 
-If a required check is operationally broken, prefer correcting the workflow. Emergency rollback may disable only the affected required context after restoring the previous blocking validation path and recording maintainer approval. Never weaken force-push/deletion protection to release. Never route around certification by rebuilding inside a publisher.
+If a second maintainer joins, raise the approval count. Do not add a direct-push bypass as a shortcut, and never weaken the force-push or deletion protection.
 
-After rollback, publication still requires exact certified bytes. A failed or unavailable candidate workflow means release waits for a new candidate; it does not authorize an ad hoc npm upload.
+Ruleset mutation is a separate administrative operation: run `node scripts/check-github-rulesets.mjs` to see the diff, and apply only when a maintainer explicitly confirms with `--apply --confirm apply-a1-ci-rulesets`.

package/docs/features/launch-profiles.md

@@ -43,7 +43,13 @@ Run Pi’s normal `/login` independently in each profile that needs stored authe
 
 Bare `a1` runs the A1-owned full-viewport TUI over public Pi engine, component, and terminal APIs. A1 owns composition, input routing, modal focus, selection behavior, scrolling, and restoration without inserting a PTY or terminal-byte relay. Its default presentation is pinned to vanilla Pi parity; structured tabs and A1-specific visual customization are not enabled.
 
-`a1 pi` and `a1 sandbox` retain transparent direct attachment. In those profiles, one untouched Pi process and the physical terminal own rendering, input, selection, clipboard, scrollback, and terminal modes; A1 owns foreground lease and lifecycle only.
+`a1 pi` and `a1 sandbox` retain transparent direct attachment. In those profiles, untouched Pi and the physical terminal own rendering, input, selection, clipboard, scrollback, and terminal modes; A1 owns only per-invocation process containment and lifecycle evidence.
+
+## Concurrent instance lifecycle
+
+Every `a1`, `a1 pi`, and `a1 sandbox` invocation receives a unique non-detachable launch instance. There is no product-wide foreground slot: the same profile or any mixture of profiles may run concurrently in separate terminals. Profile files remain shared according to the selected profile root, while process ownership, lifecycle outcome, and cleanup remain scoped to the command that launched them.
+
+Normal root exit, terminal closure, guardian failure, and verified update shutdown all close the instance's remaining process tree within bounded graceful and forced deadlines. Closing one instance never closes another. A control supervisor may remain idle afterward, but closed instances leave no UI, Pi, extension daemon, agent worker, tool, or descendant process. Ordinary recovery never asks users to kill a PID or delete the control database.
 
 ## Recovery and comparison
 

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

@@ -0,0 +1,66 @@
+# Launch-instance exact-artifact acceptance
+
+Run this checklist only against a packaged candidate on a user-controlled terminal or isolated disposable Windows worker. Do not automate launching, focusing, driving, or closing terminal windows on an active workstation.
+
+## Artifact identity
+
+Record before testing:
+
+```text
+A1 release ID:
+A1 package version:
+Source commit:
+Candidate tarball SHA-256/integrity:
+Process guardian target: win32-x64
+Process guardian crate version:
+Process guardian protocol version:
+Process guardian SHA-256:
+Process guardian signature/attestation status:
+Machine/Windows/terminal versions:
+Tester or worker attestation:
+```
+
+The process guardian values must match `dist/native/win32-x64/manifest.json` inside the exact installed candidate. Stop if the file is missing, mismatched, altered, or reports an unsupported capability.
+
+## Concurrent launch matrix
+
+Open four independent terminal tabs and launch:
+
+```text
+Terminal 1: a1
+Terminal 2: a1
+Terminal 3: a1 pi
+Terminal 4: a1 sandbox
+```
+
+Confirm all four become usable without a global foreground-lease error. Record each launch-instance ID from supervisor metadata and verify all four IDs are distinct.
+
+## Isolated closure
+
+1. Exit Terminal 3 normally. Confirm only its vanilla Pi tree exits; Terminals 1, 2, and 4 remain usable.
+2. Close the Terminal 4 tab/window without exiting Pi first. Confirm its sandbox Pi, extension daemons, agent workers, tools, and descendants disappear within the bounded deadline while both bare-A1 terminals remain usable.
+3. Exit Terminal 1 normally after causing a fixture extension to create a child and grandchild. Confirm the complete tree disappears and Terminal 2 remains usable.
+4. Force the Terminal 2 launch guardian to fail on the isolated worker. Confirm Job Object kill-on-close removes its root and descendants and leaves unrelated fixture processes alive.
+
+Record root, child, and grandchild native identities before each close and the observed terminal outcome afterward. Do not substitute manual PID termination for a failed cleanup.
+
+## Stale-state recovery
+
+Using isolated control directories, install a version-4 fixture database containing one requested or active legacy foreground lease whose former PID is dead. Run `a1 sandbox` once. Confirm that the same invocation migrates the row to historical interrupted state and launches normally without restarting the supervisor, deleting state, or discovering a PID.
+
+Repeat with an ownership-uncertain fixture process. Confirm a new independent launch still starts and the uncertain unrelated process is not terminated.
+
+## Update fan-out
+
+With at least three mixed-profile instances active, run the candidate's update-shutdown fixture. Confirm every instance receives one stop intent, each complete process tree closes, and cohort replacement occurs only after all verified terminal outcomes. A delayed or uncertain instance must prevent unsafe replacement without causing another instance to be reported idle prematurely.
+
+## Verdict
+
+Record one of:
+
+```text
+ACCEPTED — exact package and guardian digests above passed every scenario
+REJECTED — include failed step, observed process identities, outcomes, and diagnostics
+```
+
+Acceptance applies only to the exact package and process-guardian bytes recorded above. It does not certify macOS, Linux, composed terminals, detached agents, or an operating-system security sandbox.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timurproko/a1",
-  "version": "0.1.1-dev.5",
+  "version": "0.1.1-dev.7",
   "description": "Standalone terminal workspace for supervised native and managed agents",
   "type": "module",
   "packageManager": "npm@11.13.0",
@@ -19,20 +19,17 @@
   },
   "scripts": {
     "clean": "node scripts/clean.mjs",
-    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "build": "npm run clean && tsc -p tsconfig.build.json && node scripts/build-process-guardian.mjs",
+    "build:process-guardian": "node scripts/build-process-guardian.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "check:architecture": "node scripts/check-architecture.mjs && node scripts/product-identifier-policy.mjs --check && node scripts/check-product-identity-boundaries.mjs && node scripts/check-package-identity.mjs && node scripts/check-pinned-pi-source-ledger.mjs && node scripts/check-terminal-host-provenance.mjs && node scripts/check-validation-governance.mjs",
+    "check:architecture": "node scripts/check-architecture.mjs && node scripts/product-identifier-policy.mjs --check && node scripts/check-product-identity-boundaries.mjs && node scripts/check-package-identity.mjs && node scripts/check-pinned-pi-source-ledger.mjs && node scripts/check-terminal-host-provenance.mjs",
     "check:customization-ready": "node scripts/check-owned-ui-customization-prerequisites.mjs",
     "check:deprecated": "node scripts/check-deprecated-dependencies.mjs",
     "branches:prune": "node scripts/prune-merged-branches.mjs",
-    "report:validation-inventory": "node scripts/report-validation-inventory.mjs",
-    "check": "npm run test:release",
-    "validate:agent": "npm run check",
+    "check": "npm run test:fast",
     "publish:next": "tsx scripts/publish-next.ts",
     "test": "npm run test:fast",
-    "test:fast": "node scripts/run-validation-tier.mjs invariants fast",
-    "test:unit": "node scripts/run-validation-tier.mjs fast",
-    "test:integration": "node scripts/run-validation-tier.mjs launch-integration pi-engine-conformance release-update structured-runtime-integration",
+    "test:fast": "node scripts/run-validation-tier.mjs typecheck fast",
     "test:scope": "node scripts/run-validation-tier.mjs",
     "test:full": "node scripts/run-validation-tier.mjs full-release",
     "test:release": "node scripts/run-release-gates.mjs",
@@ -40,14 +37,16 @@
     "test:pi-terminal-parity": "npm run build --silent && node scripts/run-pi-terminal-parity.mjs",
     "test:pi-engine-conformance": "vitest run test/foundation/pi-engine-adapter/conformance.test.ts test/foundation/pi-engine-adapter/runtime-integration.test.ts test/foundation/pi-engine-adapter/session-integration.test.ts",
     "report:pi-engine-conformance": "npm run build --silent && node scripts/run-pi-engine-conformance.mjs",
-    "sync:pi-ui": "npm run update:pi-component-parity && npm run update:pi-event-frame-parity",
+    "sync:pi-ui": "npm run update:pi-component-parity && npm run update:pi-event-frame-parity && npm run update:pi-settings-metadata",
     "update:pi-component-parity": "tsx scripts/update-pi-component-parity.ts",
     "update:pi-event-frame-parity": "tsx scripts/update-pi-event-frame-parity.ts",
     "proof:terminal-host": "node scripts/run-terminal-host.mjs",
     "start": "npm run build && node scripts/start-local.mjs",
     "prepack": "node scripts/prepack-gate.mjs",
-    "prepublishOnly": "npm run check",
-    "prepare": "npm run build"
+    "prepublishOnly": "npm run test:release",
+    "prepare": "npm run build",
+    "update:pi-settings-metadata": "node scripts/update-pi-settings-metadata.mjs",
+    "clean:worktrees": "node scripts/clean-worktrees.mjs"
   },
   "dependencies": {
     "@earendil-works/pi-coding-agent": "0.84.2",