@timurproko/a1 0.2.7-dev.1285 → 0.2.7-dev.1286

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

@@ -1,7 +1,7 @@
 export { certifyMaterializedRelease, recordParentCertifiedRelease, releaseEnvironment, runBootstrap, } from "./bootstrap.js";
 export type { BootstrapOptions } from "./bootstrap.js";
 export { selectOrdinaryLaunchReleaseId } from "./ordinary-launch-selection.js";
-export { ReleaseStateStore, RELEASE_STATE_SCHEMA, RELEASE_RETENTION_MS, emptyState, planProtectedReleases, withinRetention } from "./release-state.js";
+export { ReleaseStateStore, ReleaseStateNewerError, isReleaseStateNewerError, RELEASE_STATE_SCHEMA, RELEASE_STATE_LEVEL, RELEASE_RETENTION_MS, emptyState, planProtectedReleases, withinRetention } from "./release-state.js";
 export type { ActiveReleaseTransactionReference, ReleaseState, OrphanReleaseDisposition, ProtectedReleaseInputs, ProtectedReleasePlan, ReleaseApproval, ReleaseCleanupDiagnostic, ReleaseCleanupDisposition, ReleaseCleanupStage, ReleaseCleanupState, ReleaseCleanupWorkerRun, ReleaseCleanupWorkerStatus, ReleaseCleanupWorkerSummary, ReleaseRecord, ReleaseReferences, ReleaseRetentionReconciliation, } from "./release-state.js";
 export { DEPENDENCY_LAYER_MANIFEST, DEPENDENCY_LAYER_SCHEMA, RUNTIME_PAYLOAD_INVENTORY, dependencyLayerCertificationPath, dependencyReference, generateDependencyRuntimePayload, legacyDependencyLayerCertificationPath, materializeDependencyLayer, readCertifiedDependencyLayer, selectDependencyRuntimePayload, selectPublishedDependencyRuntimePayload, verifyDependencyLayer, } from "./dependency-layer.js";
 export type { DependencyLayerIdentity, DependencyLayerOperationEvent, DependencyLayerReference, GeneratedRuntimePayload, MaterializeDependencyLayerOptions, MaterializedDependencyLayer, PublishedRuntimeFileClassification, PublishedRuntimePayload, ReadCertifiedDependencyLayerOptions, RuntimePayloadExclusion, RuntimePayloadInventory, SelectedRuntimePayload, } from "./dependency-layer.js";

package/dist/foundation/release/index.js

@@ -1,6 +1,6 @@
 export { certifyMaterializedRelease, recordParentCertifiedRelease, releaseEnvironment, runBootstrap, } from "./bootstrap.js";
 export { selectOrdinaryLaunchReleaseId } from "./ordinary-launch-selection.js";
-export { ReleaseStateStore, RELEASE_STATE_SCHEMA, RELEASE_RETENTION_MS, emptyState, planProtectedReleases, withinRetention } from "./release-state.js";
+export { ReleaseStateStore, ReleaseStateNewerError, isReleaseStateNewerError, RELEASE_STATE_SCHEMA, RELEASE_STATE_LEVEL, RELEASE_RETENTION_MS, emptyState, planProtectedReleases, withinRetention } from "./release-state.js";
 export { DEPENDENCY_LAYER_MANIFEST, DEPENDENCY_LAYER_SCHEMA, RUNTIME_PAYLOAD_INVENTORY, dependencyLayerCertificationPath, dependencyReference, generateDependencyRuntimePayload, legacyDependencyLayerCertificationPath, materializeDependencyLayer, readCertifiedDependencyLayer, selectDependencyRuntimePayload, selectPublishedDependencyRuntimePayload, verifyDependencyLayer, } from "./dependency-layer.js";
 export { processIsAlive } from "./process-liveness.js";
 export { PRODUCT_PACKAGE_NAME, createReleaseIdentity, deriveReleaseIdentity, digestManifestFiles, discoverReleasePayload, packageRootFromModule, releaseFileIdentity, resolveWithin, } from "./release.js";

package/dist/foundation/release/release-gc.js

@@ -3,7 +3,7 @@ import { spawnReleaseEntry } from "./release-use.js";
 import { lstat, mkdir, open, readFile, readdir, realpath, rename, rm, stat } from "node:fs/promises";
 import { dirname, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { ReleaseStateStore, releaseUseIsLive, } from "./release-state.js";
+import { ReleaseStateStore, releaseUseIsLive, isReleaseStateNewerError, } from "./release-state.js";
 import { resolveProductPaths } from "../lifecycle/index.js";
 import { RELEASE_MANIFEST_FILENAME } from "./release-store.js";
 import { DEPENDENCY_LAYER_MANIFEST, readCertifiedDependencyLayer } from "./dependency-layer.js";
@@ -130,6 +130,16 @@ export async function runBoundedReleaseCleanup(dataDir, paths, options = {}) {
  * potentially slow recursive deletion. A later launch/update resumes work if spawning fails.
  */
 export async function scheduleReleaseCleanup(dataDir, paths, options = {}) {
+    try {
+        await scheduleOwnedReleaseCleanup(dataDir, paths, options);
+    }
+    catch (error) {
+        // Compatibility: a newer release owns state this code may not write; its own maintenance cleans up.
+        if (!isReleaseStateNewerError(error))
+            throw error;
+    }
+}
+async function scheduleOwnedReleaseCleanup(dataDir, paths, options) {
     const { store } = await prepareReleaseCleanup(dataDir, paths, options);
     const runId = randomUUID();
     await store.recordCleanupWorkerScheduled(runId);
@@ -152,6 +162,17 @@ export async function scheduleReleaseCleanup(dataDir, paths, options = {}) {
 }
 /** Entry used by the private cleanup executable shipped in every immutable release. */
 export async function runReleaseCleanupWorker(environment = process.env, workerOptions = {}) {
+    try {
+        return await runOwnedReleaseCleanupWorker(environment, workerOptions);
+    }
+    catch (error) {
+        // Compatibility: a worker started by an older release stands down once a newer release owns the state.
+        if (!isReleaseStateNewerError(error))
+            throw error;
+        return { planned: 0, attempted: 0, completed: 0, remaining: 0, durationMs: 0 };
+    }
+}
+async function runOwnedReleaseCleanupWorker(environment, workerOptions) {
     const paths = resolveProductPaths(environment);
     const store = new ReleaseStateStore(paths.dataDir);
     const runId = environment[WORKER_RUN_ID_ENV] ?? randomUUID();

package/dist/foundation/release/release-state.d.ts

@@ -1,5 +1,17 @@
 import type { MaterializedRelease } from "./release-store.js";
+/**
+ * Protocol: the control-state family identifier. It is frozen: changing it locks every
+ * already-published release out of the state, which is what broke the 1276 → 1285 update.
+ * Evolve the format through {@link RELEASE_STATE_LEVEL} instead.
+ */
 export declare const RELEASE_STATE_SCHEMA: string;
+/**
+ * Protocol: the compatibility level this code reads and writes. State records the lowest
+ * level that may read it and the lowest that may write it; additive fields raise neither,
+ * because older code preserves fields it does not know. Raise `read` only when older code would
+ * misread the state, and `write` only when older writes would corrupt it.
+ */
+export declare const RELEASE_STATE_LEVEL = 1;
 /** Minimum age retention; live, uncertain, and legacy ownership independently overrides age. */
 export declare const RELEASE_RETENTION_MS: number;
 export type ReleaseApproval = "candidate" | "approved" | "rejected";
@@ -81,6 +93,27 @@ export interface ReleaseState {
     readonly references: ReleaseReferences;
     readonly cleanup: ReleaseCleanupState;
     readonly uses?: Readonly<Record<string, ReleaseUseClaim>>;
+    /** Lowest compatibility levels that may read and write this state; absent means level 1. */
+    readonly format?: ReleaseStateFormat;
+}
+export interface ReleaseStateFormat {
+    readonly read: number;
+    readonly write: number;
+}
+/**
+ * State written by a newer release that this code may not read or write. Callers doing
+ * housekeeping treat it as "a newer release owns this state" and skip their work.
+ */
+export declare class ReleaseStateNewerError extends Error {
+    readonly access: "read" | "write";
+    readonly required: number;
+    constructor(access: "read" | "write", required: number);
+}
+export declare function isReleaseStateNewerError(error: unknown): error is ReleaseStateNewerError;
+export interface ReleaseStateStoreOptions {
+    /** Replaces the atomic rename; tests inject transient sharing failures. */
+    readonly rename?: (from: string, to: string) => Promise<void>;
+    readonly platform?: NodeJS.Platform;
 }
 export interface ProtectedReleaseInputs {
     /** Releases the reconciling command itself runs from; they are never collected under it. */
@@ -121,8 +154,10 @@ export declare function planProtectedReleases(state: ReleaseState, inputs?: Prot
 export declare function withinRetention(release: ReleaseRecord, now: number, retentionMs?: number): boolean;
 /** Serializes validated release-state revisions under a lock and commits each update atomically. */
 export declare class ReleaseStateStore {
+    #private;
     readonly path: string;
-    constructor(dataDir: string);
+    constructor(dataDir: string, options?: ReleaseStateStoreOptions);
+    private renameWithRetry;
     read(): Promise<ReleaseState>;
     update(operation: (current: ReleaseState) => ReleaseState | Promise<ReleaseState>): Promise<ReleaseState>;
     recordCandidate(release: MaterializedRelease): Promise<ReleaseState>;

package/dist/foundation/release/release-state.js

@@ -1,12 +1,45 @@
 import { randomUUID } from "node:crypto";
-import { mkdir, open, readFile, rename, rm } from "node:fs/promises";
+import { mkdir, open, readdir, readFile, rename, rm } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { selectOrdinaryLaunchReleaseId } from "./ordinary-launch-selection.js";
 import { PRODUCT_IDENTITY } from "../../product-identity.js";
+/**
+ * Protocol: the control-state family identifier. It is frozen: changing it locks every
+ * already-published release out of the state, which is what broke the 1276 → 1285 update.
+ * Evolve the format through {@link RELEASE_STATE_LEVEL} instead.
+ */
 export const RELEASE_STATE_SCHEMA = PRODUCT_IDENTITY.protocol.releaseCohortSchema;
+/** Compatibility: earlier family identifier, normalized on read. */
+const LEGACY_RELEASE_STATE_SCHEMA = "a1-release-cohort-v1";
+/**
+ * Protocol: the compatibility level this code reads and writes. State records the lowest
+ * level that may read it and the lowest that may write it; additive fields raise neither,
+ * because older code preserves fields it does not know. Raise `read` only when older code would
+ * misread the state, and `write` only when older writes would corrupt it.
+ */
+export const RELEASE_STATE_LEVEL = 1;
+const RELEASE_STATE_TEMPORARY_PATTERN = /^release-state\.json\.(\d+)\.[0-9a-f-]{36}\.tmp$/;
+const RENAME_RETRY_MS = 2_000;
 const RELEASE_ID_PATTERN = /^[0-9A-Za-z.+_-]+-[a-f0-9]{20}$/;
 /** Minimum age retention; live, uncertain, and legacy ownership independently overrides age. */
 export const RELEASE_RETENTION_MS = 7 * 24 * 60 * 60 * 1_000;
+/**
+ * State written by a newer release that this code may not read or write. Callers doing
+ * housekeeping treat it as "a newer release owns this state" and skip their work.
+ */
+export class ReleaseStateNewerError extends Error {
+    access;
+    required;
+    constructor(access, required) {
+        super(`release state requires ${access} level ${required}; this release supports level ${RELEASE_STATE_LEVEL}. A newer release owns it`);
+        this.name = "ReleaseStateNewerError";
+        this.access = access;
+        this.required = required;
+    }
+}
+export function isReleaseStateNewerError(error) {
+    return error instanceof ReleaseStateNewerError;
+}
 /**
  * Age-based retention. A release stays while a selector names it (active, its rollback, or a
  * candidate still being certified), while an unfinished update may return to it, while the
@@ -56,12 +89,37 @@ export function withinRetention(release, now, retentionMs = RELEASE_RETENTION_MS
 /** Serializes validated release-state revisions under a lock and commits each update atomically. */
 export class ReleaseStateStore {
     path;
-    constructor(dataDir) {
+    #rename;
+    #platform;
+    constructor(dataDir, options = {}) {
         this.path = resolve(dataDir, "release-state.json");
+        this.#rename = options.rename ?? rename;
+        this.#platform = options.platform ?? process.platform;
+    }
+    async renameWithRetry(temporary) {
+        const deadline = Date.now() + RENAME_RETRY_MS;
+        for (let delay = 10;; delay = Math.min(delay * 2, 200)) {
+            try {
+                await this.#rename(temporary, this.path);
+                return;
+            }
+            catch (error) {
+                const code = error instanceof Error && "code" in error ? error.code : undefined;
+                // Platform: Windows refuses to replace a file another process has open for reading.
+                // Readers hold it only briefly, so the replacement is retried rather than lost.
+                const transient = this.#platform === "win32" && (code === "EPERM" || code === "EACCES" || code === "EBUSY");
+                if (!transient || Date.now() >= deadline)
+                    throw error;
+                await new Promise(resolvePromise => setTimeout(resolvePromise, delay));
+            }
+        }
     }
     async read() {
         try {
             const state = normalizeState(JSON.parse(await readFile(this.path, "utf8")));
+            const format = stateFormat(state);
+            if (format.read > RELEASE_STATE_LEVEL)
+                throw new ReleaseStateNewerError("read", format.read);
             validateState(state);
             return state;
         }
@@ -77,19 +135,30 @@ export class ReleaseStateStore {
         const lock = await acquireLock(lockPath);
         try {
             const current = await this.read();
+            const format = stateFormat(current);
+            if (format.write > RELEASE_STATE_LEVEL)
+                throw new ReleaseStateNewerError("write", format.write);
             const next = await operation(current);
             validateTransition(current, next);
-            const committed = { ...next, revision: current.revision + 1 };
+            // Invariant: levels only rise; an older writer never weakens what a newer one required.
+            const committed = { ...next, revision: current.revision + 1, format };
             const temporary = `${this.path}.${process.pid}.${randomUUID()}.tmp`;
             const file = await open(temporary, "wx", 0o600);
             try {
-                await file.writeFile(JSON.stringify(committed, null, 2));
-                await file.sync();
+                try {
+                    await file.writeFile(JSON.stringify(committed, null, 2));
+                    await file.sync();
+                }
+                finally {
+                    await file.close();
+                }
+                await this.renameWithRetry(temporary);
             }
-            finally {
-                await file.close();
+            catch (error) {
+                await rm(temporary, { force: true }).catch(() => undefined);
+                throw error;
             }
-            await rename(temporary, this.path);
+            await reclaimOrphanedTemporaries(dirname(this.path));
             return committed;
         }
         finally {
@@ -425,6 +494,43 @@ async function reclaimAbandonedLock(path) {
         await rm(gate, { recursive: true, force: true });
     }
 }
+function stateFormat(state) {
+    const format = state?.format;
+    if (format === undefined)
+        return { read: RELEASE_STATE_LEVEL, write: RELEASE_STATE_LEVEL };
+    const { read, write } = (format ?? {});
+    if (!Number.isSafeInteger(read) || !Number.isSafeInteger(write) || read < 1 || write < 1) {
+        throw new Error("invalid release state format");
+    }
+    return { read: read, write: write };
+}
+/**
+ * A write that died between creating and renaming its temporary file leaves it behind.
+ * Only files whose writer process is gone are removed; a running writer's file is never touched.
+ */
+async function reclaimOrphanedTemporaries(directory) {
+    const names = await readdir(directory).catch(() => []);
+    for (const name of names) {
+        const match = RELEASE_STATE_TEMPORARY_PATTERN.exec(name);
+        if (!match)
+            continue;
+        const pid = Number(match[1]);
+        if (pid === process.pid || processIsAlive(pid))
+            continue;
+        await rm(resolve(directory, name), { force: true }).catch(() => undefined);
+    }
+}
+function processIsAlive(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return true;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return !(error instanceof Error && "code" in error && error.code === "ESRCH");
+    }
+}
 function normalizeState(value) {
     if (!value || typeof value !== "object")
         return value;
@@ -435,7 +541,7 @@ function normalizeState(value) {
     return {
         ...state,
         // Compatibility: one-way control-state upgrade fences pre-claim cleanup workers; session files are untouched.
-        ...(state.schema === "a1-release-cohort-v1" ? { schema: RELEASE_STATE_SCHEMA } : {}),
+        ...(state.schema === LEGACY_RELEASE_STATE_SCHEMA ? { schema: RELEASE_STATE_SCHEMA } : {}),
         cleanup: cleanup
             ? { ...cleanup, workerRuns: cleanup.workerRuns ?? [] }
             : { pending: {}, diagnostics: [], workerRuns: [] },

package/dist/foundation/release/release-use.js

@@ -3,7 +3,7 @@ import { realpath } from "node:fs/promises";
 import { spawn } from "node:child_process";
 import { basename, dirname, resolve } from "node:path";
 import { resolveProductPaths } from "../lifecycle/index.js";
-import { ReleaseStateStore, releaseUseIsLive } from "./release-state.js";
+import { ReleaseStateStore, isReleaseStateNewerError, releaseUseIsLive } from "./release-state.js";
 /** Mutable installed entries are not GC-managed; immutable helper processes need their own claim. */
 async function claimReleaseEntry(entry, environment) {
     const dataDir = resolveProductPaths(environment).dataDir;
@@ -11,7 +11,16 @@ async function claimReleaseEntry(entry, environment) {
     const storeRoot = await realpath(resolve(dataDir, "releases")).catch(() => undefined);
     if (dirname(root) !== storeRoot)
         return undefined;
-    return acquireReleaseUse(dataDir, basename(root));
+    try {
+        return await acquireReleaseUse(dataDir, basename(root));
+    }
+    catch (error) {
+        // Compatibility: a newer release owns state this code may not write. It retains releases it
+        // cannot prove unused, so the launch proceeds without a claim rather than failing.
+        if (isReleaseStateNewerError(error))
+            return undefined;
+        throw error;
+    }
 }
 export async function spawnReleaseEntry(entry, args, options) {
     const use = await claimReleaseEntry(entry, options.env ?? process.env);
@@ -59,11 +68,18 @@ export async function acquireReleaseUse(dataDir, releaseId) {
         async release() {
             if (released)
                 return;
-            await store.update(state => {
-                const uses = { ...state.uses };
-                delete uses[token];
-                return { ...state, uses };
-            });
+            try {
+                await store.update(state => {
+                    const uses = { ...state.uses };
+                    delete uses[token];
+                    return { ...state, uses };
+                });
+            }
+            catch (error) {
+                // Compatibility: once a newer release owns the state, it settles this claim by process liveness.
+                if (!isReleaseStateNewerError(error))
+                    throw error;
+            }
             released = true;
         },
     };

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

@@ -1,3 +1,4 @@
+import { type ProductPaths } from "../lifecycle/index.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
@@ -69,4 +70,5 @@ export declare function delegateActivation(request: UpdateActivationRequest, cal
  */
 export declare function runActivationEntry(argv: readonly string[], entryUrl: string, io?: {
     write(line: string): void;
-}, environment?: NodeJS.ProcessEnv): Promise<number>;
+    diagnostic?(line: string): void;
+}, environment?: NodeJS.ProcessEnv, maintenance?: (dataDir: string, paths: ProductPaths) => Promise<void>): Promise<number>;

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

@@ -6,6 +6,7 @@ import { PRODUCT_TEXT } from "../../product-identity.js";
 import { certifyMaterializedRelease } from "./bootstrap.js";
 import { ReleaseStateStore } from "./release-state.js";
 import { resolveProductPaths } from "../lifecycle/index.js";
+import { scheduleReleaseCleanup } from "./release-gc.js";
 import { materializeRelease } from "./release-store.js";
 import { warmMaterializedRelease } from "./warmup.js";
 import { errorMessage } from "./managed-path.js";
@@ -113,6 +114,9 @@ export async function delegateActivation(request, callbacks) {
         for (const event of events) {
             relay = relay.then(async () => {
                 const parsed = parseActivationEvent(event);
+                // Compatibility: a newer tree may report events this updater does not know; they carry no verdict.
+                if (parsed === "unknown")
+                    return;
                 if (!parsed) {
                     failure ??= new Error(`unrecognized activation event ${JSON.stringify(event).slice(0, 200)}`);
                     return;
@@ -146,14 +150,19 @@ export async function delegateActivation(request, callbacks) {
  * 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) {
+export async function runActivationEntry(argv, entryUrl, io = {
+    write: line => process.stdout.write(line),
+    diagnostic: line => process.stderr.write(line),
+}, environment = process.env, maintenance = scheduleReleaseCleanup) {
     const emit = (event) => io.write(`${JSON.stringify(event)}\n`);
     try {
         const arguments_ = parseEntryArguments(argv);
         const packageRoot = resolve(fileURLToPath(new URL("..", entryUrl)));
+        const paths = resolveProductPaths(environment);
+        const dataDir = arguments_.dataDir ?? paths.dataDir;
         await activateInstalledRelease({
             packageRoot,
-            dataDir: arguments_.dataDir ?? resolveProductPaths(environment).dataDir,
+            dataDir,
             targetVersion: arguments_.targetVersion,
             environment,
         }, {
@@ -161,6 +170,12 @@ export async function runActivationEntry(argv, entryUrl, io = { write: line => p
             onMaterializing: progress => emit({ event: "materializing", ...progress }),
             onWarmup: state => emit({ event: "warmup", state }),
         });
+        // Invariant: the release that now owns the control state performs its own maintenance. The
+        // updater that started this entry may be older and must not interpret state this code wrote.
+        // The activation is committed, so a maintenance failure is a diagnostic, never a verdict.
+        await maintenance(dataDir, { ...paths, dataDir }).catch((error) => {
+            io.diagnostic?.(`release maintenance after activation failed: ${errorMessage(error)}\n`);
+        });
         emit({ event: "completed" });
         return 0;
     }
@@ -197,7 +212,9 @@ function parseActivationEvent(value) {
         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;
+            if (record.phase === "materialized" || record.phase === "certified" || record.phase === "active-reference-committed")
+                return { event: "phase", phase: record.phase };
+            return typeof record.phase === "string" && record.phase.length > 0 ? "unknown" : null;
         case "warmup":
             return record.state === "started" || record.state === "completed" ? { event: "warmup", state: record.state } : null;
         case "completed":
@@ -205,7 +222,7 @@ function parseActivationEvent(value) {
         case "failed":
             return typeof record.message === "string" ? { event: "failed", message: record.message } : null;
         default:
-            return null;
+            return typeof record.event === "string" && record.event.length > 0 ? "unknown" : null;
     }
 }
 function summarize(text) {

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

@@ -87,8 +87,10 @@ export type { UpdateActivationPhase, UpdateMaterializationProgress } from "./upd
 export interface UpdateLifecycleCoordinator {
     targetIsActive(targetVersion: string): Promise<boolean>;
     verifyPackageUnlocked(packageRoot: string): Promise<void>;
-    activateInstalled(packageRoot: string, targetVersion: string, phase: (phase: UpdateActivationPhase) => Promise<void>, onMaterializing?: (progress: UpdateMaterializationProgress) => void, onWarmup?: (state: "started" | "completed") => void): Promise<void>;
+    activateInstalled(packageRoot: string, targetVersion: string, phase: (phase: UpdateActivationPhase) => Promise<void>, onMaterializing?: (progress: UpdateMaterializationProgress) => void, onWarmup?: (state: "started" | "completed") => void): Promise<UpdateActivationMode | void>;
 }
+/** Whether the installed tree activated itself (and owns its maintenance) or this updater activated it. */
+export type UpdateActivationMode = "delegated" | "in-process";
 export interface UpdateTransactionJournal {
     readonly path: string;
     read(): Promise<UpdateTransaction | null>;

package/dist/foundation/release/update.js

@@ -136,10 +136,12 @@ export function createUpdateLifecycleCoordinator(environment = process.env, file
             // 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))
+            if (contracts.includes(UPDATE_ACTIVATION_CONTRACT)) {
                 await delegateActivation(request, callbacks);
-            else
-                await activateInstalledRelease(request, callbacks);
+                return "delegated";
+            }
+            await activateInstalledRelease(request, callbacks);
+            return "in-process";
         },
     };
 }
@@ -416,13 +418,22 @@ async function withUpdateExecutionLease(input, options, output, installer, opera
         // back to the release that ran before it, so this request proceeds as an ordinary update of its
         // own target instead of reporting a dead attempt as in progress.
         const interrupted = lease.owner.targetVersion;
-        const rollback = await installer.rollback(lease.transaction.priorActiveReleaseId)
-            .catch(error => `rollback failed: ${errorMessage(error)}`);
         const store = new UpdateTransactionStore(input.dataDir);
-        await store.finish("rolled-back", `interrupted ${interrupted} update settled by ${input.targetVersion}; ${rollback}`);
-        await store.clearCompleted().catch(() => undefined);
-        await reclaimDeadLease(input.dataDir, lease.owner);
-        output.stdout(`${PRODUCT_TEXT.commandName} rolled back the interrupted ${interrupted} update: ${rollback}\n`);
+        if (lease.transaction.phase === "active-reference-committed") {
+            // Invariant: the interrupted update already committed its target; agents may run it, so it stays.
+            await store.finish("completed", `interrupted ${interrupted} update was already active; settled by ${input.targetVersion}`);
+            await store.clearCompleted().catch(() => undefined);
+            await reclaimDeadLease(input.dataDir, lease.owner);
+            output.stdout(`${PRODUCT_TEXT.commandName} settled the interrupted ${interrupted} update, which was already active\n`);
+        }
+        else {
+            const rollback = await installer.rollback(lease.transaction.priorActiveReleaseId)
+                .catch(error => `rollback failed: ${errorMessage(error)}`);
+            await store.finish("rolled-back", `interrupted ${interrupted} update settled by ${input.targetVersion}; ${rollback}`);
+            await store.clearCompleted().catch(() => undefined);
+            await reclaimDeadLease(input.dataDir, lease.owner);
+            output.stdout(`${PRODUCT_TEXT.commandName} rolled back the interrupted ${interrupted} update: ${rollback}\n`);
+        }
         lease = await acquireUpdateExecutionLease(input);
     }
     if (lease.status !== "acquired") {
@@ -533,7 +544,9 @@ async function runUpdateTransaction(plan) {
     const { packageRoot, npmCliRoot } = plan.installation;
     const run = { transaction: await transactionStore.read() };
     try {
-        if ((!run.transaction || run.transaction.status === "completed") && await lifecycle.targetIsActive(targetVersion)) {
+        // Rationale: a settled transaction, even one reported as failed after its commit, leaves nothing
+        // to install when its target is already active; reinstalling the same release would only churn.
+        if ((!run.transaction || run.transaction.status !== "active") && await lifecycle.targetIsActive(targetVersion)) {
             await installer.maintenance();
             await transactionStore.clearCompleted();
             output.stdout(`${PRODUCT_TEXT.commandName} is up to date — no update needed.\n`);
@@ -610,7 +623,7 @@ async function replaceUpdatePackage(plan, run, protection, npmCli) {
 }
 /** Activate the installed package, commit maintenance, and only then report success. */
 async function activateUpdate(plan, run) {
-    const { output, progress, transactionStore, now, onPhaseTiming, paths } = plan;
+    const { progress, transactionStore, now, onPhaseTiming } = plan;
     progress.set(70, MATERIALIZE_PROGRESS.from);
     let activationPhaseStartedAt = now();
     const recordActivationPhase = async (phase) => {
@@ -619,7 +632,7 @@ async function activateUpdate(plan, run) {
         progress.set(ACTIVATION_PROGRESS[phase].at, ACTIVATION_PROGRESS[phase].creepTo);
         activationPhaseStartedAt = now();
     };
-    await plan.lifecycle.activateInstalled(plan.installation.packageRoot, plan.targetVersion, recordActivationPhase, ({ completed, total }) => progress.set(MATERIALIZE_PROGRESS.from
+    const activation = await plan.lifecycle.activateInstalled(plan.installation.packageRoot, plan.targetVersion, recordActivationPhase, ({ completed, total }) => progress.set(MATERIALIZE_PROGRESS.from
         + (MATERIALIZE_PROGRESS.to - MATERIALIZE_PROGRESS.from) * (total > 0 ? Math.min(1, completed / total) : 0)), state => {
         if (state === "started") {
             activationPhaseStartedAt = now();
@@ -632,19 +645,39 @@ async function activateUpdate(plan, run) {
         }
     });
     const transactionStartedAt = now();
-    const transaction = run.transaction;
-    if (transaction?.recovery?.capsulePath)
-        await removeUpdateRecoveryCapsule(paths.dataDir, transaction.transactionId);
-    // Invariant: successful output follows the durable cleanup disposition. Slow recursive
-    // removal belongs to the detached worker started by this maintenance coordinator.
-    await plan.installer.maintenance();
+    const warnings = [];
+    // Invariant: a delegated tree owns the control state it just wrote and has already scheduled its
+    // own maintenance; this updater may be older and must not interpret that state. An in-process
+    // activation ran this updater's own code, so the updater remains the owner of its maintenance.
+    if (activation !== "delegated") {
+        // Rationale: the activation is committed, so cleanup trouble is retried later, never a failure.
+        await plan.installer.maintenance().catch(error => { warnings.push(`release cleanup will retry: ${errorMessage(error)}`); });
+    }
+    await completeCommittedUpdate(plan, run.transaction, warnings);
+    onPhaseTiming?.({ phase: "transaction-complete", durationMs: Math.max(0, now() - transactionStartedAt) });
+    return 0;
+}
+/**
+ * The active reference names the target, so the update has happened. Everything here is
+ * best-effort bookkeeping: it may warn, but it never fails the update and never rolls back.
+ */
+async function completeCommittedUpdate(plan, transaction, warnings) {
+    const { output, progress, transactionStore, paths } = plan;
+    if (transaction?.recovery?.capsulePath) {
+        await removeUpdateRecoveryCapsule(paths.dataDir, transaction.transactionId)
+            .catch(error => { warnings.push(`recovery evidence will be removed later: ${errorMessage(error)}`); });
+    }
     // Concurrency: this is the launch cutover. No failure-prone update work follows success.
-    await transactionStore.finish("completed");
+    await transactionStore.finish("completed", warnings.length === 0 ? null : warnings.join("; ").slice(0, 2_000))
+        .catch(error => { warnings.push(`update journal could not be settled: ${errorMessage(error)}`); });
     await Promise.all([transactionStore.clearCompleted(), invalidateReleaseCheckCache(paths.configDir)]).catch(() => undefined);
-    onPhaseTiming?.({ phase: "transaction-complete", durationMs: Math.max(0, now() - transactionStartedAt) });
     progress.finish();
     output.stdout(`${PRODUCT_TEXT.commandName} updated successfully to ${plan.targetVersion}\n`);
-    return 0;
+    for (const warning of warnings)
+        output.stderr(`${PRODUCT_TEXT.diagnostic(`warning: ${singleLine(warning)}`)}\n`);
+}
+function singleLine(text) {
+    return text.replace(/[\r\n]+/gu, " ").slice(0, 400);
 }
 async function settleUpdateFailure(plan, transaction, error) {
     const { output, transactionStore } = plan;
@@ -654,6 +687,12 @@ async function settleUpdateFailure(plan, transaction, error) {
         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;
     }
+    if (transaction?.status === "active" && transaction.phase === "active-reference-committed") {
+        // Invariant: once the active reference names the target, running agents may already use it.
+        // Rolling back would move the reference under them, so a later failure only warns.
+        await completeCommittedUpdate(plan, transaction, [`post-activation step failed: ${message}`]);
+        return 0;
+    }
     const rollback = await plan.installer.rollback(transaction?.priorActiveReleaseId ?? null)
         .catch(rollbackError => `rollback failed: ${errorMessage(rollbackError)}`);
     if (transaction)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timurproko/a1",
-  "version": "0.2.7-dev.1285",
+  "version": "0.2.7-dev.1286",
   "description": "Standalone single-agent terminal UI on pinned Pi",
   "type": "module",
   "privateLaunchContract": "neutral-launch-v1",
@@ -113,7 +113,7 @@
     "@mariozechner/clipboard": "^0.3.9"
   },
   "publication": {
-    "source": "70c8ebe762cd38cfbdc1f87fe82e674b236671c3",
-    "pullRequest": 912
+    "source": "81969ce6924469b3081347067fd0d0190359b132",
+    "pullRequest": 913
   }
 }