@timurproko/a1 0.2.3 → 0.2.4-dev.664

package/README.md

@@ -28,6 +28,14 @@ a1 update --develop 0.1.8-dev.107       # install that exact preview
 a1 update --models                      # refresh A1's model catalogs
 ```
 
+If `a1 update` from `0.2.2` reports that it could not resolve npm's JavaScript entry, use the official installer once:
+
+```sh
+npm x -y -- @timurproko/a1-install
+```
+
+It verifies the existing installation and delegates replacement to A1's cancellation-safe updater with npm's canonical execution context. Do not delete A1 data or overwrite the package with a raw global install. After the bridge, use ordinary `a1 update` commands again.
+
 On interactive startup A1 checks, at most once a day, whether a newer release exists on its own channel and shows an `Update Available` notice with the command to run. It never installs anything. Turn it off with the `Update check` setting (Generic section), or set `A1_SKIP_VERSION_CHECK=1`; it is also skipped when `PI_OFFLINE` or `CI` is set, or when output is not a terminal. The check reads the public npm registry, or `npm_config_registry` when set.
 
 ## Extensions

package/dist/foundation/release/update-recovery.d.ts

@@ -41,6 +41,8 @@ export interface ProtectedPackageReplacementOptions {
     readonly globalRoot: string;
     /** Root used only to locate the active npm implementation; installation remains pinned to globalRoot. */
     readonly npmCliRoot?: string;
+    /** Canonical entry established before update lifecycle mutation and revalidated when the capsule is committed. */
+    readonly npmCli?: string;
     readonly packageRoot: string;
     readonly transaction: UpdateTransaction;
     readonly priorRelease: {

package/dist/foundation/release/update-recovery.js

@@ -119,7 +119,9 @@ export async function prepareUpdateRecoveryCapsule(options) {
         const prefix = npmPrefixForGlobalRoot(canonicalGlobal, platform);
         const launcherRoot = platform === "win32" ? prefix : resolve(prefix, "bin");
         const npmCliRoot = await realpath(options.npmCliRoot ?? canonicalGlobal);
-        const npmCli = await resolveNpmCli(npmCliRoot, options.environment ?? process.env, platform);
+        const npmCli = options.npmCli === undefined
+            ? await resolveNpmCli(npmCliRoot, options.environment ?? process.env, platform)
+            : await requireCanonicalNpmCli(options.npmCli);
         const capsule = {
             schema: UPDATE_RECOVERY_SCHEMA,
             launchContract: PRIVATE_LAUNCH_CONTRACT,
@@ -300,7 +302,10 @@ async function spawnRecoveryWorker(entry, manifestPath, environment) {
     child.unref();
 }
 export async function resolveNpmCli(globalRoot, environment, platform = process.platform, nodeExecutable = process.execPath) {
-    const candidates = [environment.npm_execpath, resolve(globalRoot, "npm", "bin", "npm-cli.js")]
+    const declaredNpmEntry = platform === "win32"
+        ? windowsEnvironmentValue(environment, "npm_execpath")
+        : environment.npm_execpath;
+    const candidates = [declaredNpmEntry, resolve(globalRoot, "npm", "bin", "npm-cli.js")]
         .filter((value) => typeof value === "string" && value.length > 0);
     for (const candidate of candidates) {
         const canonical = await canonicalRegularFile(candidate);
@@ -342,12 +347,20 @@ async function windowsNpmCliFromPath(environment) {
     return null;
 }
 function windowsEnvironmentValue(environment, name) {
+    if (Object.hasOwn(environment, name))
+        return environment[name];
     const key = Object.keys(environment).find(candidate => candidate.toLowerCase() === name.toLowerCase());
     return key ? environment[key] : undefined;
 }
 function unquoteWindowsPathEntry(value) {
     return value.length >= 2 && value.startsWith('"') && value.endsWith('"') ? value.slice(1, -1) : value;
 }
+async function requireCanonicalNpmCli(path) {
+    const canonical = await canonicalRegularFile(path);
+    if (!canonical)
+        throw new Error("preflight npm JavaScript entry is no longer a regular file");
+    return canonical;
+}
 async function canonicalRegularFile(path) {
     const canonical = await realpath(path).catch(() => null);
     if (!canonical)

package/dist/foundation/release/update.d.ts

@@ -1,7 +1,7 @@
 import type { UpdateChannel } from "./types.js";
 import { type UpdateActivationPhase, type UpdateMaterializationProgress } from "./update-activation.js";
 import { type UpdateRecoveryState, type UpdateTransaction, type UpdateTransactionPhase } from "./update-transaction.js";
-import { type ProtectedPackageReplacementResult } from "./update-recovery.js";
+import { resolveNpmCli, type ProtectedPackageReplacementResult } from "./update-recovery.js";
 export declare const PRODUCT_PACKAGE: string;
 export type { UpdateChannel } from "./types.js";
 export interface ProcessRequest {
@@ -69,6 +69,8 @@ export interface SelfUpdateOptions {
     transactionStore?: UpdateTransactionJournal;
     /** Test seam for protected global package replacement. */
     packageReplacement?: (input: UpdatePackageReplacementInput) => Promise<ProtectedPackageReplacementResult>;
+    /** Test seam for proving replacement-authority preflight ordering. */
+    npmCliResolver?: typeof resolveNpmCli;
     /** Test or embedding seam for post-activation release maintenance. */
     maintenance?: () => Promise<void>;
     progress?: boolean;
@@ -102,6 +104,7 @@ export interface UpdatePackageReplacementInput {
     readonly dataDir: string;
     readonly globalRoot: string;
     readonly npmCliRoot: string;
+    readonly npmCli?: string;
     readonly packageRoot: string;
     readonly transaction: UpdateTransaction;
     readonly priorRelease: {

package/dist/foundation/release/update.js

@@ -16,7 +16,7 @@ import { materializeRelease, readMaterializedRelease } from "./release-store.js"
 import { scheduleReleaseCleanup } from "./release-gc.js";
 import { UPDATE_ACTIVATION_CONTRACT, activateInstalledRelease, delegateActivation, readActivationContracts, } from "./update-activation.js";
 import { UpdateTransactionStore } from "./update-transaction.js";
-import { npmPrefixForGlobalRoot, removeUpdateRecoveryCapsule, runProtectedPackageReplacement, updateLauncherPaths, updateNpmInstallArguments, } from "./update-recovery.js";
+import { npmPrefixForGlobalRoot, removeUpdateRecoveryCapsule, resolveNpmCli, runProtectedPackageReplacement, updateLauncherPaths, updateNpmInstallArguments, } from "./update-recovery.js";
 export const PRODUCT_PACKAGE = PRODUCT_TEXT.packageName;
 const UPDATE_DIST_TAGS = { stable: "latest", next: "next" };
 const defaultFileSystem = {
@@ -520,6 +520,7 @@ export async function runSelfUpdate(options) {
         ? async () => { }
         : async () => await scheduleReleaseCleanup(paths.dataDir, paths));
     let transaction = await transactionStore.read();
+    let npmCli;
     try {
         if ((!transaction || transaction.status === "completed") && await lifecycle.targetIsActive(targetVersion)) {
             await maintenance();
@@ -527,7 +528,17 @@ export async function runSelfUpdate(options) {
             output.stdout(`${PRODUCT_TEXT.commandName} is up to date — no update needed.\n`);
             return 0;
         }
-        // Rationale: the bar first appears here so a no-change run never flashes it.
+        const preflightRequired = options.npmCliResolver !== undefined
+            || options.packageReplacement === undefined && options.runner === undefined;
+        if (preflightRequired) {
+            try {
+                npmCli = await (options.npmCliResolver ?? resolveNpmCli)(npmCliRoot, environment);
+            }
+            catch (error) {
+                throw new UpdatePreflightFailure(errorMessage(error));
+            }
+        }
+        // Rationale: the bar first appears only after every non-mutating replacement prerequisite passes.
         progress.set(3, 15);
         const cohortStore = new CohortStateStore(paths.dataDir);
         let cohortState = await cohortStore.read();
@@ -573,6 +584,7 @@ export async function runSelfUpdate(options) {
                     dataDir: paths.dataDir,
                     globalRoot,
                     npmCliRoot,
+                    ...(npmCli === undefined ? {} : { npmCli }),
                     packageRoot,
                     transaction: replacementTransaction,
                     priorRelease,
@@ -655,6 +667,10 @@ export async function runSelfUpdate(options) {
     catch (error) {
         progress.clear();
         const message = errorMessage(error);
+        if (error instanceof UpdatePreflightFailure) {
+            output.stderr(`${PRODUCT_TEXT.diagnostic(`update could not start safely: ${message}. Nothing was changed. Retry with npm x -y -- ${PRODUCT_PACKAGE}-install`)}\n`);
+            return 1;
+        }
         const rollback = options.lifecycle
             ? "previous test lifecycle retained"
             : await rollbackPriorCohort(paths.dataDir, environment, transaction?.priorActiveReleaseId ?? null).catch(rollbackError => `rollback failed: ${errorMessage(rollbackError)}`);
@@ -760,6 +776,8 @@ class UpdateFailure extends Error {
     exitCode;
     constructor(exitCode, message) { super(message); this.exitCode = exitCode; }
 }
+class UpdatePreflightFailure extends Error {
+}
 async function canonicalImmutableRoot(dataDir, releaseRoot) {
     try {
         const [store, selected] = await Promise.all([realpath(resolve(dataDir, "releases")), realpath(releaseRoot)]);

package/dist/native/darwin-arm64/manifest.json

@@ -5,7 +5,7 @@
   "platform": "darwin",
   "architecture": "arm64",
   "capability": "supported",
-  "builtAt": "2026-10-03T06:54:00.608Z",
+  "builtAt": "2026-10-03T10:56:57.116Z",
   "artifact": {
     "filename": "process-guardian",
     "sha256": "d3979187180449cb181eb92c187d1c8d0bfc4b2ba442e2e0a7c32704ea7e9589",

package/dist/native/linux-x64/manifest.json

@@ -5,7 +5,7 @@
   "platform": "linux",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-10-03T06:53:59.023Z",
+  "builtAt": "2026-10-03T10:56:40.417Z",
   "artifact": {
     "filename": "process-guardian",
     "sha256": "a316d11a4aabe5aa88a360169206a87a11fe4b355e836b77cd8a7950279ab415",

package/dist/native/win32-x64/manifest.json

@@ -5,10 +5,10 @@
   "platform": "win32",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-10-03T06:54:43.872Z",
+  "builtAt": "2026-10-03T10:57:08.998Z",
   "artifact": {
     "filename": "process-guardian.exe",
-    "sha256": "b887732721bba6f0395e92c0a1ce9f59fe30fff50ce1d6d43b2a47a74f219cfe",
+    "sha256": "121e6f570287541ace2c806411da2ca836cb2acab9b1205054b0d68b809d363d",
     "size": 177152
   },
   "provenance": {

package/docs/architecture/internal-naming.md

@@ -80,7 +80,7 @@ Metadata that predates contract declaration is stale, never fatal. A pre-cutover
 
 Activation after the global installation is handed over the same way. The package manifest declares `updateActivationContracts` (`activate-v1`) and ships `bin/activate.js`; an updater that serves a declared contract starts that entry with the data directory and the target version and relays its line-delimited progress events (`materializing`, `phase`, `warmup`, `completed`, `failed`) into its own journal and progress bar, while the entry materializes, certifies, warms, and supervises the tree it ships in with that tree's own code. The updater resolves nothing inside the installed tree but `package.json` and that entry; `test/repository-governance/update-activation-contract.test.ts` pins this. A tree that declares no contract the updater serves is activated in-process with the layout it had, which keeps an updater older than the contract and a downgrade to an older preview working.
 
-`test/foundation/release/update-predecessor.integration.test.ts` is the gate for this. It installs each of the most recent published releases and drives the candidate through **that release's own** materialization and warmup, because a fixture built from the candidate would only prove the candidate agrees with itself. No reset or migration runs automatically. If disposable state blocks installation, inspect its resolved paths and obtain separate approval before removal.
+`test/foundation/release/update-predecessor.integration.test.ts` is the gate for this. It installs each of the most recent published releases and drives the candidate through **that release's own** materialization and warmup, because a fixture built from the candidate would only prove the candidate agrees with itself. On Windows it also drives the newest predecessor's protected package replacement from a user-style A1 prefix with npm beside a separate Node installation, then exercises the explicit `0.2.2` installer-context bridge. Candidate-only recovery success therefore cannot hide a target-side fix that its installed predecessor cannot reach. No reset or migration runs automatically. If disposable state blocks installation, inspect its resolved paths and obtain separate approval before removal.
 
 | State | Treatment |
 | --- | --- |

package/docs/ci-release-runbook.md

@@ -99,7 +99,7 @@ Ordinary type, architecture, unit/contract, and dist checks always run for code
 
 Integration owners declare one cadence in `config/integration-owners.json`. Impact mode selects affected `pull-request` owners: a changed production path selects its coarse owner, a changed test selects its owner, and a changed file under `test/support/` or `test/fixtures/` selects the owners of the retained tests that import it directly or through other support files (the selection lists those tests as its `shared-support` reason). A support file that no retained test imports, or a test tree the scanner cannot read, falls back to every owner the shared rule declares and records `shared-support-declared`; an invalidator, unknown operational path, or manual Development dispatch selects every `pull-request` owner. An implementation-bound PR body does not force conservative selection; it only removes the documentation-only and version-only shortcuts. The modular matrix itself is derived from the selection by `scripts/release/validation-matrix.mjs`, so inactive jobs are not scheduled at all rather than checking out and exiting early. `exhaustive` owners are never silently skipped or reported as passed: impact and aggregate evidence list them as cadence-deferred, and malformed cadence blocks selection. Full regression and nightly/stable release still execute both cadence classes. PR-attached Full regression is selected only when base policy verifies an `openspec-ci` App-authored candidate, its generated repair identity, and every qualifying failed Full regression source field in `regression-provenance.json` against GitHub's read-only workflow-run record. Release/publishing, shared-support, prerequisite, build, validation-authority, unknown-path, label, Publish-only repair, and successful-run persistent-overrun changes retain bounded ordinary validation. Planning-only generated repair drafts remain exempt; eligible implementation drafts receive native lane feedback without integration authority.
 
-The real three-release `update-predecessor` scenario is exhaustive because four fresh npm installations dominated recent PR critical paths, and `update-performance` is exhaustive because its assertion is wall-clock timing on a shared runner; the update path's deterministic contracts stay on pull requests through `pi-release-resume` and `package-contracts`. PR validation retains deterministic predecessor command, lifecycle, fault, fixture, materialization, warmup, package, and update contracts. This permits a real published-history incompatibility or update slowdown to reach `develop` before the next exhaustive run detects it. `.github/workflows/full-regression.yml` runs every night at `02:47 UTC` against the `develop` tip with every owner and enforced budgets, independent of publication, so such a regression shows as a failed Full regression run the next morning; nightly publication's own complete validation still blocks publication. For diagnosis on any other candidate, dispatch standalone Full regression; labels and high-risk release/update impact do not add it to PR checks or change owner cadence.
+The real three-release `update-predecessor` scenario is exhaustive because its fresh npm installations and private-prefix protected replacements dominate recent PR critical paths, and `update-performance` is exhaustive because its assertion is wall-clock timing on a shared runner. On Windows the predecessor owner requires the newest published updater to replace and activate the exact candidate with A1 under a user-style prefix and npm beside a separate Node installation; it separately proves the declared `0.2.2` official-installer context bridge without relabeling that immutable build as direct-update capable. The update path's deterministic contracts stay on pull requests through `pi-release-resume` and `package-contracts`, including preflight ordering, installer npm-context delegation, failure containment, lifecycle, recovery, materialization, warmup, package, and update behavior. This permits a real published-history incompatibility or update slowdown to reach `develop` before the next exhaustive run detects it, but nightly and stable publication remain blocked by the exhaustive predecessor outcome. `.github/workflows/full-regression.yml` runs every night at `02:47 UTC` against the `develop` tip with every owner and enforced budgets, independent of publication, so such a regression shows as a failed Full regression run the next morning; nightly publication's own complete validation still blocks publication. For diagnosis on any other candidate, dispatch standalone Full regression; labels and high-risk release/update impact do not add it to PR checks or change owner cadence.
 
 Development outcomes report each owner/scope invocation separately while sharing authenticated build/package preparation. The aggregate reports setup, scope, job, aggregate-processing, total runner, and runner-critical-path durations. The acceptance targets are at most eight minutes of runner critical path and five minutes for one PR-required scope; an over-target result remains unmet without retries, timeout increases, workload reduction, or mutable installation caches. Hosted queue time is reported separately when available and is not counted as test execution.
 
@@ -270,8 +270,14 @@ the version. The retired `--approve` form remains a mutation-free usage error.
    stops preparation), and maps every later first-parent commit through one merged
    GitHub pull request. It generates Pi-style Markdown beginning
    `## [version] - YYYY-MM-DD`, followed by applicable `### Breaking Changes`,
-   `### New Features`, `### Added`, `### Changed`, and `### Fixed` sections, and
-   creates one source-bound **draft GitHub Release**. It then dispatches
+   `### New Features`, `### Added`, `### Changed`, and `### Fixed` sections. Explicit
+   breaking changes always remain visible. Ordinary non-breaking `chore` pull requests
+   and generated regression-triage repairs are omitted; a regression repair that proves
+   a user-facing defect must use its actual `fix(scope)` title before merge. Pi proposals
+   use `upgrade(pi)` and appear under Changed, while historical `chore(pi): upgrade`
+   titles remain compatible. A range containing only filtered maintenance says that it
+   has no user-facing changes. Preparation then creates one source-bound **draft GitHub
+   Release**. It dispatches
    `release-candidate.yml`, which stamps the stable version, packs both packages with
    the generated note, and runs the complete stable suite on Windows, Linux, and macOS
    without publishing. A running or successful validation of the same source and

package/docs/releases/0.2.3.md

@@ -1,22 +1,16 @@
 ## [0.2.3] - 2026-10-03
 
-### New Features
-
-- auto-merge the verified release reopening PR ([#651](https://github.com/timurproko/a1/pull/651))
-
 ### Changed
 
 - upgrade pinned Pi to 0.99.1 ([#642](https://github.com/timurproko/a1/pull/642))
-- match changelog link decoration ([#649](https://github.com/timurproko/a1/pull/649))
 - upgrade pinned Pi to 0.99.2 ([#652](https://github.com/timurproko/a1/pull/652))
+- match changelog link decoration ([#649](https://github.com/timurproko/a1/pull/649))
 - rename stable wrapper ([#655](https://github.com/timurproko/a1/pull/655))
 
 ### Fixed
 
-- reuse PR full-regression selection across failed-job reruns ([#650](https://github.com/timurproko/a1/pull/650))
 - restore documentation auto-merge ([#653](https://github.com/timurproko/a1/pull/653))
 - allow development publication startup ([#654](https://github.com/timurproko/a1/pull/654))
 - bound Windows backlog setup ([#656](https://github.com/timurproko/a1/pull/656))
 - resolve bundled npm entry ([#657](https://github.com/timurproko/a1/pull/657))
 - verify exact npm resources ([#659](https://github.com/timurproko/a1/pull/659))
-- repair the 2026-10-02 full regression failure ([#660](https://github.com/timurproko/a1/pull/660))

package/package.json

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