@timurproko/a1 0.1.8-dev.508 → 0.1.8-dev.512

package/bin/activate.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+// Protocol: the updater that installed this tree starts this entry with --data-dir and
+// --target-version and reads one JSON progress event per line. The tree activates itself
+// with its own release code, so the updater needs to know nothing else about its layout.
+const { runActivationEntry } = await import("../dist/foundation/release/update-activation.js");
+
+process.exitCode = await runActivationEntry(process.argv.slice(2), import.meta.url);

package/bin/sync-pi-tui-proxy.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+
+// Compatibility: updaters older than 0.1.8-dev.479 run this entry from the tree they just
+// installed to point a terminal-package proxy that no longer exists at that tree. Those
+// updaters treat a missing file as a failure worth a stack trace on the user's terminal,
+// so the entry stays, does nothing, and exits successfully. Newer updaters never run it.
+process.exitCode = 0;

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

@@ -22,6 +22,8 @@ export { STABLE_RELEASE_SCHEMA, createStableReleaseEvidence, verifyStableRegistr
 export type { StableRegistryState, StableRegistryVerificationOptions, StableReleaseEvidence, StableReleaseEvidenceInput } from "./stable-release.js";
 export { PRODUCT_PACKAGE, assertUpdatePerformanceBudget, createNpmProcessRunner, createUpdateLifecycleCoordinator, planUpdateOwnership, renderUpdateProgressBar, runSelfUpdate, } from "./update.js";
 export type { ProcessRequest, ProcessResult, SelfUpdateOptions, UpdateActivationPhase, UpdateChannel, UpdateFileSystem, UpdateLifecycleCoordinator, UpdateMaterializationProgress, UpdateMeasuredPhase, UpdateOutput, UpdateOwnershipAction, UpdatePackageReplacementInput, UpdatePerformanceEvidence, UpdatePhaseTimingEvent, UpdateProcessRunner, UpdateTransactionJournal, } from "./update.js";
+export { UPDATE_ACTIVATION_CONTRACT, UPDATE_ACTIVATION_ENTRY, UPDATE_ACTIVATION_MANIFEST_FIELD, activateInstalledRelease, delegateActivation, readActivationContracts, runActivationEntry, } from "./update-activation.js";
+export type { UpdateActivationCallbacks, UpdateActivationEvent, UpdateActivationRequest } from "./update-activation.js";
 export { selectSupervisorLaunchReleaseId, selectUpdateLaunchRelease } from "./update-launch.js";
 export { UPDATE_RECOVERY_SCHEMA, cleanupUpdateRecoveryCapsules, inspectUpdateLauncherSet, prepareUpdateRecoveryCapsule, readUpdateRecoveryCapsule, removeUpdateRecoveryCapsule, runProtectedPackageReplacement, updateLauncherPaths, } from "./update-recovery.js";
 export type { ProtectedPackageReplacementOptions, ProtectedPackageReplacementResult, UpdateRecoveryCapsule, UpdateRecoveryResult } from "./update-recovery.js";

package/dist/foundation/release/index.js

@@ -10,6 +10,7 @@ export { RELEASE_MANIFEST_FILENAME, assertImmutableExecutionRoot, consumeMateria
 export { createRestartSeal, readRestartCertifiedRelease, releaseCertificationDocument, restartSealDigest } from "./restart-certification.js";
 export { STABLE_RELEASE_SCHEMA, createStableReleaseEvidence, verifyStableRegistry } from "./stable-release.js";
 export { PRODUCT_PACKAGE, assertUpdatePerformanceBudget, createNpmProcessRunner, createUpdateLifecycleCoordinator, planUpdateOwnership, renderUpdateProgressBar, runSelfUpdate, } from "./update.js";
+export { UPDATE_ACTIVATION_CONTRACT, UPDATE_ACTIVATION_ENTRY, UPDATE_ACTIVATION_MANIFEST_FIELD, activateInstalledRelease, delegateActivation, readActivationContracts, runActivationEntry, } from "./update-activation.js";
 export { selectSupervisorLaunchReleaseId, selectUpdateLaunchRelease } from "./update-launch.js";
 export { UPDATE_RECOVERY_SCHEMA, cleanupUpdateRecoveryCapsules, inspectUpdateLauncherSet, prepareUpdateRecoveryCapsule, readUpdateRecoveryCapsule, removeUpdateRecoveryCapsule, runProtectedPackageReplacement, updateLauncherPaths, } from "./update-recovery.js";
 export { UPDATE_JOURNAL_SCHEMA, UpdateTransactionStore } from "./update-transaction.js";

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

@@ -0,0 +1,72 @@
+/**
+ * The one activation contract an installed tree can offer the updater that installed it.
+ * The updater knows nothing else about the tree: the manifest names the contracts the tree
+ * serves, and this entry drives its activation with the tree's own release code.
+ */
+export declare const UPDATE_ACTIVATION_CONTRACT = "activate-v1";
+export declare const UPDATE_ACTIVATION_ENTRY = "bin/activate.js";
+/** Manifest field listing the activation contracts an installed tree serves. */
+export declare const UPDATE_ACTIVATION_MANIFEST_FIELD = "updateActivationContracts";
+export type UpdateActivationPhase = "materialized" | "certified" | "active-reference-committed";
+/**
+ * Copying the release is the longest step with nothing to say for itself, so it
+ * reports the files it has written against the files it must write. A caller that
+ * shows progress can then move with the work instead of guessing at it.
+ */
+export interface UpdateMaterializationProgress {
+    readonly completed: number;
+    readonly total: number;
+}
+export interface UpdateActivationCallbacks {
+    readonly phase: (phase: UpdateActivationPhase) => Promise<void>;
+    readonly onMaterializing?: (progress: UpdateMaterializationProgress) => void;
+    readonly onWarmup?: (state: "started" | "completed") => void;
+}
+export interface UpdateActivationRequest {
+    readonly packageRoot: string;
+    readonly dataDir: string;
+    readonly targetVersion: string;
+    readonly environment: NodeJS.ProcessEnv;
+}
+/** One line of the activator's progress stream; `failed` carries the reason and ends it. */
+export type UpdateActivationEvent = {
+    readonly event: "materializing";
+    readonly completed: number;
+    readonly total: number;
+} | {
+    readonly event: "phase";
+    readonly phase: UpdateActivationPhase;
+} | {
+    readonly event: "warmup";
+    readonly state: "started" | "completed";
+} | {
+    readonly event: "completed";
+} | {
+    readonly event: "failed";
+    readonly message: string;
+};
+/**
+ * Activate the installed tree at `packageRoot` with this process's own release code:
+ * materialize it into the immutable store, certify, warm, verify supervision, and only
+ * then move the active reference. This is what the installed tree runs for itself through
+ * its activation entry, and what an updater runs in-process for a tree older than the contract.
+ */
+export declare function activateInstalledRelease(request: UpdateActivationRequest, callbacks: UpdateActivationCallbacks): Promise<void>;
+/**
+ * Which activation contracts the installed tree serves, read from its manifest. A tree
+ * without the field, or without a readable manifest, serves none and is activated in-process.
+ */
+export declare function readActivationContracts(packageRoot: string, read?: (path: string) => Promise<string>): Promise<readonly string[]>;
+/**
+ * Drive the installed tree's own activator and relay its progress. The updater passes
+ * the tree what the tree cannot know (the data directory, the target it must match) and
+ * learns from it only the phases it reached; every path inside the tree is the tree's business.
+ */
+export declare function delegateActivation(request: UpdateActivationRequest, callbacks: UpdateActivationCallbacks): Promise<void>;
+/**
+ * Body of the installed tree's activation entry: activate the tree this code ships in,
+ * writing one progress event per line so the updater that started it can follow along.
+ */
+export declare function runActivationEntry(argv: readonly string[], entryUrl: string, io?: {
+    write(line: string): void;
+}, environment?: NodeJS.ProcessEnv): Promise<number>;

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

@@ -0,0 +1,204 @@
+import { spawn } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { PRODUCT_TEXT } from "../../product-identity.js";
+import { certifyMaterializedRelease, ensureSupervisor } from "./bootstrap.js";
+import { CohortStateStore } from "./cohort-state.js";
+import { encodeFrame, LineFrameDecoder } from "../protocol/index.js";
+import { resolveProductPaths } from "../lifecycle/index.js";
+import { materializeRelease } from "./release-store.js";
+import { warmMaterializedRelease } from "./warmup.js";
+/**
+ * The one activation contract an installed tree can offer the updater that installed it.
+ * The updater knows nothing else about the tree: the manifest names the contracts the tree
+ * serves, and this entry drives its activation with the tree's own release code.
+ */
+export const UPDATE_ACTIVATION_CONTRACT = "activate-v1";
+export const UPDATE_ACTIVATION_ENTRY = "bin/activate.js";
+/** Manifest field listing the activation contracts an installed tree serves. */
+export const UPDATE_ACTIVATION_MANIFEST_FIELD = "updateActivationContracts";
+const ACTIVATION_DIAGNOSTIC_LIMIT = 2_000;
+/**
+ * Activate the installed tree at `packageRoot` with this process's own release code:
+ * materialize it into the immutable store, certify, warm, verify supervision, and only
+ * then move the active reference. This is what the installed tree runs for itself through
+ * its activation entry, and what an updater runs in-process for a tree older than the contract.
+ */
+export async function activateInstalledRelease(request, callbacks) {
+    const stateStore = new CohortStateStore(request.dataDir);
+    let total = 0;
+    let completed = 0;
+    const candidate = await materializeRelease(request.packageRoot, request.dataDir, {
+        onProgress: event => {
+            total = event.fileCount;
+            callbacks.onMaterializing?.({ completed, total });
+        },
+        onOperation: event => {
+            if (event.operation !== "candidate-write" && event.operation !== "layer-write")
+                return;
+            completed += 1;
+            callbacks.onMaterializing?.({ completed, total });
+        },
+    });
+    if (candidate.packageVersion !== request.targetVersion)
+        throw new Error(`installed ${PRODUCT_TEXT.displayName} version ${candidate.packageVersion} does not match target ${request.targetVersion}`);
+    await stateStore.recordCandidate(candidate);
+    await callbacks.phase("materialized");
+    const diagnostics = await certifyMaterializedRelease(candidate, request.dataDir);
+    await stateStore.approve(candidate.releaseId, diagnostics);
+    await callbacks.phase("certified");
+    callbacks.onWarmup?.("started");
+    await warmMaterializedRelease(candidate, request.environment);
+    callbacks.onWarmup?.("completed");
+    await ensureSupervisor(candidate, request.environment);
+    // Invariant: warmup and authenticated readiness precede changing the active reference.
+    await stateStore.activate(candidate.releaseId);
+    await callbacks.phase("active-reference-committed");
+}
+/**
+ * Which activation contracts the installed tree serves, read from its manifest. A tree
+ * without the field, or without a readable manifest, serves none and is activated in-process.
+ */
+export async function readActivationContracts(packageRoot, read = path => readFile(path, "utf8")) {
+    try {
+        const manifest = JSON.parse(await read(resolve(packageRoot, "package.json")));
+        const declared = manifest[UPDATE_ACTIVATION_MANIFEST_FIELD];
+        return Array.isArray(declared) ? declared.filter((value) => typeof value === "string") : [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Drive the installed tree's own activator and relay its progress. The updater passes
+ * the tree what the tree cannot know (the data directory, the target it must match) and
+ * learns from it only the phases it reached; every path inside the tree is the tree's business.
+ */
+export async function delegateActivation(request, callbacks) {
+    const entry = resolve(request.packageRoot, UPDATE_ACTIVATION_ENTRY);
+    const child = spawn(process.execPath, [entry, "--data-dir", request.dataDir, "--target-version", request.targetVersion], {
+        env: request.environment,
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
+    });
+    const decoder = new LineFrameDecoder();
+    let diagnostics = "";
+    let failure = null;
+    let completed = false;
+    // Concurrency: callbacks are awaited in order so a phase is journaled before the next one is read.
+    let relay = Promise.resolve();
+    child.stderr?.setEncoding("utf8");
+    child.stderr?.on("data", chunk => { diagnostics = `${diagnostics}${chunk}`.slice(-ACTIVATION_DIAGNOSTIC_LIMIT); });
+    child.stdout?.on("data", chunk => {
+        let events;
+        try {
+            events = decoder.push(chunk);
+        }
+        catch (error) {
+            failure ??= errorMessage(error);
+            return;
+        }
+        for (const event of events) {
+            relay = relay.then(async () => {
+                const parsed = parseActivationEvent(event);
+                if (!parsed) {
+                    failure ??= `unrecognized activation event ${JSON.stringify(event).slice(0, 200)}`;
+                    return;
+                }
+                if (parsed.event === "materializing")
+                    callbacks.onMaterializing?.({ completed: parsed.completed, total: parsed.total });
+                else if (parsed.event === "phase")
+                    await callbacks.phase(parsed.phase);
+                else if (parsed.event === "warmup")
+                    callbacks.onWarmup?.(parsed.state);
+                else if (parsed.event === "completed")
+                    completed = true;
+                else
+                    failure ??= parsed.message;
+            }).catch(error => { failure ??= errorMessage(error); });
+        }
+    });
+    const exit = await new Promise((resolvePromise, rejectPromise) => {
+        child.once("error", rejectPromise);
+        child.once("close", (code, signal) => resolvePromise({ code, signal }));
+    });
+    await relay;
+    if (failure)
+        throw new Error(failure);
+    if (exit.code !== 0 || !completed) {
+        const status = exit.code === null ? exit.signal ?? "unknown status" : `status ${exit.code}`;
+        throw new Error(`installed release activation exited with ${status}${summarize(diagnostics)}`);
+    }
+}
+/**
+ * Body of the installed tree's activation entry: activate the tree this code ships in,
+ * writing one progress event per line so the updater that started it can follow along.
+ */
+export async function runActivationEntry(argv, entryUrl, io = { write: line => process.stdout.write(line) }, environment = process.env) {
+    const emit = (event) => io.write(encodeFrame(event));
+    try {
+        const arguments_ = parseEntryArguments(argv);
+        const packageRoot = resolve(fileURLToPath(new URL("..", entryUrl)));
+        await activateInstalledRelease({
+            packageRoot,
+            dataDir: arguments_.dataDir ?? resolveProductPaths(environment).dataDir,
+            targetVersion: arguments_.targetVersion,
+            environment,
+        }, {
+            phase: async (phase) => emit({ event: "phase", phase }),
+            onMaterializing: progress => emit({ event: "materializing", ...progress }),
+            onWarmup: state => emit({ event: "warmup", state }),
+        });
+        emit({ event: "completed" });
+        return 0;
+    }
+    catch (error) {
+        emit({ event: "failed", message: errorMessage(error) });
+        return 1;
+    }
+}
+function parseEntryArguments(argv) {
+    let dataDir = null;
+    let targetVersion = null;
+    for (let index = 0; index < argv.length; index += 1) {
+        const value = argv[index + 1];
+        if (argv[index] === "--data-dir" && value !== undefined) {
+            dataDir = value;
+            index += 1;
+        }
+        else if (argv[index] === "--target-version" && value !== undefined) {
+            targetVersion = value;
+            index += 1;
+        }
+        else
+            throw new Error(`unexpected activation argument ${argv[index]}`);
+    }
+    if (targetVersion === null)
+        throw new Error("activation requires --target-version");
+    return { dataDir, targetVersion };
+}
+function parseActivationEvent(value) {
+    if (typeof value !== "object" || value === null || !("event" in value))
+        return null;
+    const record = value;
+    switch (record.event) {
+        case "materializing":
+            return typeof record.completed === "number" && typeof record.total === "number" ? { event: "materializing", completed: record.completed, total: record.total } : null;
+        case "phase":
+            return record.phase === "materialized" || record.phase === "certified" || record.phase === "active-reference-committed" ? { event: "phase", phase: record.phase } : null;
+        case "warmup":
+            return record.state === "started" || record.state === "completed" ? { event: "warmup", state: record.state } : null;
+        case "completed":
+            return { event: "completed" };
+        case "failed":
+            return typeof record.message === "string" ? { event: "failed", message: record.message } : null;
+        default:
+            return null;
+    }
+}
+function summarize(text) {
+    const lines = text.split(/\r?\n/).map(line => line.trim()).filter(line => line.length > 0);
+    return lines.length === 0 ? "" : `: ${lines.slice(0, 4).join(" | ")}`;
+}
+function errorMessage(error) { return error instanceof Error ? error.message : String(error); }

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

@@ -1,4 +1,5 @@
 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";
 export declare const PRODUCT_PACKAGE: string;
@@ -9,6 +10,7 @@ export interface ProcessRequest {
 export interface ProcessResult {
     code: number | null;
     stdout: string;
+    stderr?: string;
 }
 export type UpdateProcessRunner = (command: string, arguments_: readonly string[], request: ProcessRequest) => Promise<ProcessResult>;
 export interface UpdateFileSystem {
@@ -57,16 +59,7 @@ export interface SelfUpdateOptions {
     onPhaseTiming?: (event: UpdatePhaseTimingEvent) => void;
     now?: () => number;
 }
-export type UpdateActivationPhase = Extract<UpdateTransactionPhase, "materialized" | "certified" | "active-reference-committed">;
-/**
- * Copying the release is the longest step with nothing to say for itself, so it
- * reports the files it has written against the files it must write. A caller that
- * shows progress can then move with the work instead of guessing at it.
- */
-export interface UpdateMaterializationProgress {
-    readonly completed: number;
-    readonly total: number;
-}
+export type { UpdateActivationPhase, UpdateMaterializationProgress } from "./update-activation.js";
 export interface UpdateLifecycleCoordinator {
     targetIsActive(targetVersion: string): Promise<boolean>;
     shutdownVerifiedOwners(targetVersion: string): Promise<{
@@ -103,6 +96,8 @@ export interface UpdatePackageReplacementInput {
     readonly environment: NodeJS.ProcessEnv;
     readonly onRecoveryState: (state: UpdateRecoveryState) => Promise<void>;
 }
+/** Bound on the child diagnostics an update keeps: enough for npm's failure reason, never a log. */
+export declare const CHILD_DIAGNOSTIC_LIMIT = 8000;
 export declare function createNpmProcessRunner(platform?: NodeJS.Platform): UpdateProcessRunner;
 export type UpdateOwnershipAction = "clean-dead-record" | "leave-running" | "end-session";
 /**

package/dist/foundation/release/update.js

@@ -13,7 +13,7 @@ import { CohortStateStore } from "./cohort-state.js";
 import { cleanupVerifiedOwner, processIsAlive } from "./process-cleanup.js";
 import { materializeRelease, readMaterializedRelease } from "./release-store.js";
 import { scheduleReleaseCleanup } from "./release-gc.js";
-import { warmMaterializedRelease } from "./warmup.js";
+import { UPDATE_ACTIVATION_CONTRACT, activateInstalledRelease, delegateActivation, readActivationContracts, } from "./update-activation.js";
 import { UpdateTransactionStore } from "./update-transaction.js";
 import { removeUpdateRecoveryCapsule, runProtectedPackageReplacement } from "./update-recovery.js";
 export const PRODUCT_PACKAGE = PRODUCT_TEXT.packageName;
@@ -27,12 +27,19 @@ const defaultOutput = {
     stdout(message) { process.stdout.write(message); },
     stderr(message) { process.stderr.write(message); },
 };
+/** Bound on the child diagnostics an update keeps: enough for npm's failure reason, never a log. */
+export const CHILD_DIAGNOSTIC_LIMIT = 8_000;
 export function createNpmProcessRunner(platform = process.platform) {
     return async (command, arguments_, request) => await new Promise((resolvePromise, rejectPromise) => {
-        const stdio = request.captureStdout ? ["ignore", "pipe", "inherit"] : ["inherit", "inherit", "inherit"];
+        // Invariant: no child of the updater shares the terminal. The progress bar is the only
+        // live output; a child's own text is kept, bounded, and shown with a failure or not at all.
+        const stdio = ["ignore", request.captureStdout ? "pipe" : "ignore", "pipe"];
         const child = platform === "win32" ? crossSpawn(command, [...arguments_], { stdio }) : spawn(command, [...arguments_], { stdio });
         const stdout = [];
+        let stderr = "";
         child.stdout?.on("data", chunk => stdout.push(Buffer.from(chunk)));
+        child.stderr?.setEncoding("utf8");
+        child.stderr?.on("data", chunk => { stderr = `${stderr}${chunk}`.slice(-CHILD_DIAGNOSTIC_LIMIT); });
         let settled = false;
         child.once("error", error => { if (!settled) {
             settled = true;
@@ -40,7 +47,7 @@ export function createNpmProcessRunner(platform = process.platform) {
         } });
         child.once("close", code => { if (!settled) {
             settled = true;
-            resolvePromise({ code, stdout: Buffer.concat(stdout).toString("utf8") });
+            resolvePromise({ code, stdout: Buffer.concat(stdout).toString("utf8"), stderr });
         } });
     });
 }
@@ -143,34 +150,20 @@ export function createUpdateLifecycleCoordinator(environment = process.env, file
             }
         },
         async activateInstalled(packageRoot, targetVersion, phase, onMaterializing, onWarmup) {
-            let total = 0;
-            let completed = 0;
-            const candidate = await materializeRelease(packageRoot, paths.dataDir, {
-                onProgress: event => {
-                    total = event.fileCount;
-                    onMaterializing?.({ completed, total });
-                },
-                onOperation: event => {
-                    if (event.operation !== "candidate-write" && event.operation !== "layer-write")
-                        return;
-                    completed += 1;
-                    onMaterializing?.({ completed, total });
-                },
-            });
-            if (candidate.packageVersion !== targetVersion)
-                throw new Error(`installed ${PRODUCT_TEXT.displayName} version ${candidate.packageVersion} does not match target ${targetVersion}`);
-            await stateStore.recordCandidate(candidate);
-            await phase("materialized");
-            const diagnostics = await certifyMaterializedRelease(candidate, paths.dataDir);
-            await stateStore.approve(candidate.releaseId, diagnostics);
-            await phase("certified");
-            onWarmup?.("started");
-            await warmMaterializedRelease(candidate, environment);
-            onWarmup?.("completed");
-            await ensureSupervisor(candidate, environment);
-            // Invariant: warmup and authenticated readiness precede changing the active reference.
-            await stateStore.activate(candidate.releaseId);
-            await phase("active-reference-committed");
+            const request = { packageRoot, dataDir: paths.dataDir, targetVersion, environment };
+            const callbacks = {
+                phase,
+                ...(onMaterializing ? { onMaterializing } : {}),
+                ...(onWarmup ? { onWarmup } : {}),
+            };
+            // Compatibility: the tree npm just installed is newer than this updater, so its layout is
+            // its own to know. A tree that serves the contract activates itself with its own code;
+            // a tree from before the contract is activated here, with the layout it had then.
+            const contracts = await readActivationContracts(packageRoot, fileSystem.readFile);
+            if (contracts.includes(UPDATE_ACTIVATION_CONTRACT))
+                await delegateActivation(request, callbacks);
+            else
+                await activateInstalledRelease(request, callbacks);
         },
     };
 }
@@ -444,10 +437,10 @@ export async function runSelfUpdate(options) {
                             transaction = await transactionStore.setRecovery(recovery) ?? transaction;
                     },
                 }));
-                if (replacement.stdout.trim().length > 0 && replacement.outcome !== "installed")
-                    output.stderr(`${replacement.stdout.trimEnd()}\n`);
-                if (replacement.stderr.trim().length > 0)
-                    output.stderr(`${replacement.stderr.trimEnd()}\n`);
+                // Rationale: npm's own text explains a failed replacement and says nothing about a
+                // successful one, so it reaches the terminal only when the installation did not happen.
+                if (replacement.outcome !== "installed")
+                    reportChildDiagnostics(output, replacement);
                 if (replacement.outcome === "installed")
                     transaction = await transactionStore.advance("package-installed");
                 if (replacement.cancelled) {
@@ -464,8 +457,7 @@ export async function runSelfUpdate(options) {
                 if (installation.result === null)
                     throw new UpdateFailure(installation.exitCode, "npm process failed");
                 if (installation.result.code !== 0) {
-                    if (installation.result.stdout.trim().length > 0)
-                        output.stderr(`${installation.result.stdout.trimEnd()}\n`);
+                    reportChildDiagnostics(output, installation.result);
                     throw new UpdateFailure(unsuccessfulCode(installation.result.code), `npm exited with status ${formatExitCode(installation.result.code)}`);
                 }
                 transaction = await transactionStore.advance("package-installed");
@@ -581,11 +573,20 @@ async function runNpm(runner, arguments_, captureStdout, output, action, reportN
         return { result: null, exitCode: 1 };
     }
     if (result.code !== 0 && reportNonzero) {
-        output.stderr(`${PRODUCT_TEXT.diagnostic(`could not ${action}; npm exited with status ${formatExitCode(result.code)}. Review npm's diagnostics above.`)}\n`);
+        const explained = reportChildDiagnostics(output, result);
+        output.stderr(`${PRODUCT_TEXT.diagnostic(`could not ${action}; npm exited with status ${formatExitCode(result.code)}.${explained ? " Review npm's diagnostics above." : ""}`)}\n`);
         return { result: null, exitCode: unsuccessfulCode(result.code) };
     }
     return { result, exitCode: 0 };
 }
+/** Prints what a failed child said, bounded, and reports whether there was anything to print. */
+function reportChildDiagnostics(output, result) {
+    const text = [result.stdout, result.stderr ?? ""].map(part => part.trim()).filter(part => part.length > 0).join("\n").slice(-CHILD_DIAGNOSTIC_LIMIT);
+    if (text.length === 0)
+        return false;
+    output.stderr(`${text}\n`);
+    return true;
+}
 async function rollbackPriorCohort(dataDir, environment, priorReleaseId) {
     if (!priorReleaseId)
         return "no prior cohort was available for rollback";

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

@@ -5,7 +5,7 @@
   "platform": "darwin",
   "architecture": "arm64",
   "capability": "supported",
-  "builtAt": "2026-09-19T12:23:45.099Z",
+  "builtAt": "2026-09-19T13:30:30.983Z",
   "artifact": {
     "filename": "process-guardian",
     "sha256": "9db1726bbe3fc2e8292f2ead1e7e9d0fd4d7d0dc9217b372582bf354b0f565dc",

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

@@ -5,7 +5,7 @@
   "platform": "linux",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-09-19T12:23:39.291Z",
+  "builtAt": "2026-09-19T13:30:39.829Z",
   "artifact": {
     "filename": "process-guardian",
     "sha256": "d8cda6b0c7cb36c0cc41e90802aceebf6c02eaebbc08a83d7d963d2e918dbd7a",

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

@@ -5,10 +5,10 @@
   "platform": "win32",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-09-19T12:24:18.124Z",
+  "builtAt": "2026-09-19T13:31:06.678Z",
   "artifact": {
     "filename": "process-guardian.exe",
-    "sha256": "94769c4c9aeece0be7e6f54733782c37e18e780acabf7a4bcba6886e7f9b0b87",
+    "sha256": "39cc0b1caeb6d009b118f40db5a66aa58d84e7f6b33443e97670bd3708a83a0e",
     "size": 177664
   },
   "provenance": {

package/dist/runtime-payload-inventory.json

@@ -1,6 +1,7 @@
 {
   "schema": "a1-runtime-payload-v1",
   "entryPoints": [
+    "bin/activate.js",
     "bin/cli.js",
     "bin/guardian.js",
     "bin/supervisor.js",

package/docs/architecture/internal-naming.md

@@ -77,6 +77,8 @@ An update is performed by the release that is already installed, so the contract
 
 Metadata that predates contract declaration is stale, never fatal. A pre-cutover active record does not stop a launch: it is ignored, the installed payload is materialized, and ordinary cohort selection activates it. A launch that cannot take the installed payload at all — an installation being replaced right now — starts the retained active release instead of failing, and leaves activation to the next launch. What still requires `neutral-launch-v1` outright is narrow and never blocks a launch: the installed package's own manifest must declare it, and an update recovery capsule is never translated.
 
+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.
 
 | State | Treatment |

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@timurproko/a1",
-  "version": "0.1.8-dev.508",
+  "version": "0.1.8-dev.512",
   "description": "Standalone terminal workspace for supervised native and managed agents",
   "type": "module",
   "privateLaunchContract": "neutral-launch-v1",
+  "updateActivationContracts": [
+    "activate-v1"
+  ],
   "packageManager": "npm@11.13.0",
   "bin": {
     "a1": "bin/cli.js"