@timurproko/a1 0.1.8-dev.332 → 0.1.8-dev.368

package/dist/features/prompt-history/store.d.ts

@@ -8,7 +8,7 @@ export declare class PromptHistoryStore {
     #private;
     readonly path: string;
     readonly profileId: string;
-    constructor(path: string, profileId: string, limit: number);
+    constructor(path: string, profileId: string, limit: number, imagesDir?: string);
     record(input: PromptHistorySubmission): void;
     snapshot(): PromptHistorySnapshot;
     close(): void;

package/dist/features/prompt-history/store.js

@@ -3,6 +3,7 @@ import { chmodSync, closeSync, lstatSync, mkdirSync, openSync, statSync } from "
 import { dirname } from "node:path";
 import { PRODUCT_IDENTITY } from "../../product-identity.js";
 import { assertPromptHistorySubmission, PROMPT_HISTORY_MAX_ENTRY_BYTES, PROMPT_HISTORY_MAX_TEXT_BYTES } from "../../contracts/owned-ui/index.js";
+import { collectImageChipIdentifiers, PromptImageSidecar } from "./image-sidecar.js";
 export class HistoryStorageError extends Error {
     code;
     certainty;
@@ -17,11 +18,13 @@ export class PromptHistoryStore {
     path;
     profileId;
     #database;
-    constructor(path, profileId, limit) {
+    #sidecar;
+    constructor(path, profileId, limit, imagesDir) {
         this.path = path;
         this.profileId = profileId;
         if (!Number.isInteger(limit) || limit < 10 || limit > 100 || limit % 10 !== 0)
             throw new HistoryStorageError("schema");
+        this.#sidecar = imagesDir === undefined ? undefined : new PromptImageSidecar(imagesDir);
         mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
         if (lstatSync(dirname(path)).isSymbolicLink())
             throw new HistoryStorageError("unavailable");
@@ -67,6 +70,10 @@ export class PromptHistoryStore {
             this.#database.close();
             throw error;
         }
+        // Rationale: opportunistically reclaim any sidecar whose row was pruned in a prior process
+        // crash or by another concurrent opener. Bounded by the number of files on disk minus the
+        // surviving reference set; failures are swallowed to preserve honest history behavior.
+        this.#sweepOrphanedSidecars();
     }
     record(input) {
         assertPromptHistorySubmission(input);
@@ -133,11 +140,48 @@ export class PromptHistoryStore {
     #prune(limit) {
         const rows = this.#database.prepare("SELECT sequence,bytes FROM prompts ORDER BY sequence DESC").all();
         let bytes = 0;
+        const dropped = [];
         for (const [index, row] of rows.entries()) {
             bytes += Number(row.bytes);
             if (index >= limit || bytes > PROMPT_HISTORY_MAX_TEXT_BYTES)
-                this.#database.prepare("DELETE FROM prompts WHERE sequence=?").run(row.sequence);
+                dropped.push(row.sequence);
         }
+        if (dropped.length === 0)
+            return;
+        // Invariant: sidecar reap uses text still referenced by SURVIVING rows so a row still
+        // referencing an id shared with a pruned row keeps the file. Collect surviving ids before
+        // deleting so a concurrent snapshot cannot see a live row whose sidecar is already gone.
+        const droppedTexts = dropped.map(sequence => this.#database.prepare("SELECT text FROM prompts WHERE sequence=?").get(sequence)?.text).filter((value) => typeof value === "string");
+        for (const sequence of dropped)
+            this.#database.prepare("DELETE FROM prompts WHERE sequence=?").run(sequence);
+        if (this.#sidecar === undefined)
+            return;
+        const survivingIds = this.#collectReferencedIdentifiers();
+        for (const text of droppedTexts) {
+            for (const id of collectImageChipIdentifiers(text)) {
+                if (!survivingIds.has(id))
+                    this.#sidecar.unlink(id);
+            }
+        }
+    }
+    #collectReferencedIdentifiers() {
+        const identifiers = new Set();
+        const rows = this.#database.prepare("SELECT text FROM prompts").all();
+        for (const row of rows) {
+            if (typeof row.text !== "string")
+                continue;
+            for (const id of collectImageChipIdentifiers(row.text))
+                identifiers.add(id);
+        }
+        return identifiers;
+    }
+    #sweepOrphanedSidecars() {
+        if (this.#sidecar === undefined)
+            return;
+        try {
+            this.#sidecar.sweep(this.#collectReferencedIdentifiers());
+        }
+        catch { /* Rationale: sidecar sweep never blocks history readiness. */ }
     }
     #checkSize(maintain = false) {
         let size = 0;

package/dist/features/prompt-history/worker.js

@@ -6,7 +6,7 @@ if (port !== null) {
     let store;
     let chain = Promise.resolve();
     const options = workerData;
-    const open = retry(() => { store = new PromptHistoryStore(options.path, options.profileId, options.limit); });
+    const open = retry(() => { store = new PromptHistoryStore(options.path, options.profileId, options.limit, options.imagesDir); });
     void open.then(() => port.postMessage({ id: 0, ok: true }), error => port.postMessage({ id: 0, ok: false, code: classifyHistoryError(error) }));
     port.on("message", (request) => {
         chain = chain.then(async () => {

package/dist/features/prompt-suggestions/diagnostics.d.ts

@@ -0,0 +1,18 @@
+import { type SuggestionDiagnosticObserver, type SuggestionDiagnosticRecord } from "../../contracts/owned-ui/index.js";
+export interface SuggestionDiagnosticCaptureOptions {
+    readonly enabled?: boolean;
+    /** Explicit local destination, or an injected sink for deterministic I/O tests. */
+    readonly destination?: string;
+    readonly writeSnapshot?: (snapshot: string) => Promise<void>;
+}
+/** Bounded metadata snapshots; one in-flight write and one replaceable latest snapshot. */
+export declare class SuggestionDiagnosticCapture implements SuggestionDiagnosticObserver {
+    #private;
+    readonly options: SuggestionDiagnosticCaptureOptions;
+    constructor(options?: SuggestionDiagnosticCaptureOptions);
+    record(record: SuggestionDiagnosticRecord): void;
+    snapshot(): readonly SuggestionDiagnosticRecord[];
+    /** Explicit evidence boundary, never awaited by input or rendering. */
+    flush(): Promise<void>;
+    dispose(): void;
+}

package/dist/features/prompt-suggestions/diagnostics.js

@@ -0,0 +1,82 @@
+import { writeFile } from "node:fs/promises";
+import { SUGGESTION_DECISION_REASONS, SUGGESTION_DIAGNOSTIC_EVENTS, } from "../../contracts/owned-ui/index.js";
+/** Bounded metadata snapshots; one in-flight write and one replaceable latest snapshot. */
+export class SuggestionDiagnosticCapture {
+    options;
+    #records = [];
+    #pending;
+    #writing;
+    #disposed = false;
+    #write;
+    constructor(options = {}) {
+        this.options = options;
+        this.#write = options.writeSnapshot ?? (options.destination === undefined ? undefined
+            : snapshot => writeFile(options.destination, snapshot, { encoding: "utf8", mode: 0o600 }));
+    }
+    record(record) {
+        if (!this.options.enabled || this.#disposed)
+            return;
+        const safe = sanitize(record);
+        if (safe === null)
+            return;
+        this.#records.push(safe);
+        if (this.#records.length > 128)
+            this.#records.shift();
+        let snapshot = this.#serialize();
+        while (Buffer.byteLength(snapshot, "utf8") > 65_536) {
+            this.#records.shift();
+            snapshot = this.#serialize();
+        }
+        if (this.#write) {
+            this.#pending = snapshot;
+            this.#pump();
+        }
+    }
+    snapshot() { return this.#records.map(record => ({ ...record })); }
+    /** Explicit evidence boundary, never awaited by input or rendering. */
+    async flush() {
+        while (this.#writing)
+            await this.#writing;
+    }
+    dispose() {
+        this.#disposed = true;
+        this.#records = [];
+        this.#pending = undefined;
+    }
+    #serialize() { return JSON.stringify({ schema: "prompt-suggestion-diagnostics-v1", records: this.#records }); }
+    #pump() {
+        if (this.#writing || this.#pending === undefined || !this.#write || this.#disposed)
+            return;
+        const snapshot = this.#pending;
+        this.#pending = undefined;
+        this.#writing = Promise.resolve().then(() => this.#write(snapshot)).catch(() => {
+            // Security: do not retain or display raw filesystem/provider errors.
+        }).finally(() => {
+            this.#writing = undefined;
+            this.#pump();
+        });
+    }
+}
+function sanitize(record) {
+    if (!SUGGESTION_DIAGNOSTIC_EVENTS.includes(record.event))
+        return null;
+    const reasoning = ["ordinary", "off", "minimal", "low", "medium", "high", "xhigh", "max", "unavailable"].includes(record.reasoning)
+        ? record.reasoning : "unavailable";
+    const reason = record.reason !== undefined && SUGGESTION_DECISION_REASONS.includes(record.reason) ? record.reason : undefined;
+    // Security: explicit projection prevents arbitrary extra fields, including raw error payloads, from escaping.
+    return {
+        event: record.event, ...(reason === undefined ? {} : { reason }),
+        session: boundedNumber(record.session), run: boundedNumber(record.run), response: boundedNumber(record.response),
+        request: boundedNumber(record.request), provider: identifier(record.provider), model: identifier(record.model),
+        reasoning, elapsedMs: boundedNumber(record.elapsedMs),
+    };
+}
+function boundedNumber(value) {
+    return Number.isFinite(value) ? Math.min(Number.MAX_SAFE_INTEGER, Math.max(0, Math.floor(value))) : 0;
+}
+function identifier(value) {
+    // Security: identifiers are metadata, not display names or arbitrary JSON. Reject controls/path-shaped values.
+    if (typeof value !== "string" || /[\p{C}\\\s]/u.test(value) || value.includes(":") || value.startsWith("/"))
+        return "redacted";
+    return value.slice(0, 64);
+}

package/dist/features/prompt-suggestions/index.d.ts

@@ -0,0 +1 @@
+export * from "./diagnostics.js";

package/dist/features/prompt-suggestions/index.js

@@ -0,0 +1 @@
+export * from "./diagnostics.js";

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

@@ -35,6 +35,8 @@ export interface SupervisorStartupAttempt extends SupervisorStartupAttemptIdenti
         readonly signal: NodeJS.Signals | null;
     }>;
 }
+/** Reuse a verified owner, or join the winner if another launch starts the same cohort first. */
+export declare function ensureSupervisor(release: MaterializedRelease, environment: NodeJS.ProcessEnv): Promise<void>;
 export declare function startSupervisor(release: MaterializedRelease, environment: NodeJS.ProcessEnv): Promise<SupervisorStartupAttempt>;
 /**
  * Hand a release the key set its own build reads. A retained pre-cutover release is

package/dist/foundation/release/bootstrap.js

@@ -10,6 +10,8 @@ import { assertLaunchProfileId, createSupervisorStartupAttempt, readSupervisorSt
 import { encodeFrame, LineFrameDecoder } from "../protocol/index.js";
 import { cleanupProvenIdleOwner, processIsAlive } from "./process-cleanup.js";
 import { sweepDeadEndpoints } from "./endpoints.js";
+import { UpdateTransactionStore } from "./update-transaction.js";
+import { selectUpdateLaunchRelease } from "./update-launch.js";
 import { consumeMaterializationProof, materializeRelease, readCertifiedReleaseManifest, readMaterializedRelease, resolveReleaseEntryPoint, verifyMaterializedRelease } from "./release-store.js";
 import { scheduleReleaseCleanup } from "./release-gc.js";
 import { createRestartSeal, readRestartCertifiedRelease, releaseCertificationDocument } from "./restart-certification.js";
@@ -29,6 +31,21 @@ export async function runBootstrap(options) {
     await mkdir(paths.runtimeDir, { recursive: true, mode: 0o700 });
     const stateStore = new CohortStateStore(paths.dataDir);
     let state = await stateStore.read();
+    const launchDuringUpdate = async () => {
+        // Concurrency: read the journal before touching npm's mutable tree, including package.json.
+        const transaction = await new UpdateTransactionStore(paths.dataDir).read();
+        if (!transaction || transaction.status === "completed")
+            return null;
+        const prior = selectUpdateLaunchRelease(await stateStore.read(), transaction);
+        if (!prior)
+            return null;
+        const retained = await readCertifiedReleaseManifest(prior, resolve(paths.dataDir, "releases"));
+        await ensureSupervisor(retained, environment);
+        return await launchUi(retained, environment, sessionArgs);
+    };
+    const duringUpdate = await launchDuringUpdate();
+    if (duringUpdate !== null)
+        return duringUpdate;
     // Invariant: records left by cohorts whose processes are gone say nothing about ownership, and there
     // can now be several of them. Clearing them first keeps the decision below about what is
     // actually running.
@@ -80,10 +97,8 @@ export async function runBootstrap(options) {
                 return verified;
             });
             await markStartupPhase(environment, "durable-validation-complete");
-            const retainedPaths = resolveCohortEndpoint(paths, retained.releaseId, environment);
             await markStartupPhase(environment, "replacement-supervisor-start");
-            const startup = await startSupervisor(retained, environment);
-            await waitForVerifiedEndpoint(retainedPaths.endpointMetadataPath, retained, 8_000, startup);
+            await ensureSupervisor(retained, environment);
             await markStartupPhase(environment, "replacement-supervisor-ready");
             return await launchUi(retained, environment, sessionArgs);
         }
@@ -102,6 +117,10 @@ export async function runBootstrap(options) {
             throw error;
         return fallback;
     }
+    // Concurrency: an update may have begun while this launch was reading the installed payload.
+    const afterMaterialization = await launchDuringUpdate();
+    if (afterMaterialization !== null)
+        return afterMaterialization;
     await stateStore.recordCandidate(candidate);
     state = await stateStore.read();
     if (!state.references.active) {
@@ -192,8 +211,7 @@ export async function runBootstrap(options) {
     else {
         selected = await readMaterializedRelease(decision.releaseRoot);
     }
-    const startup = await startSupervisor(selected, environment);
-    await waitForVerifiedEndpoint(resolveCohortEndpoint(paths, selected.releaseId, environment).endpointMetadataPath, selected, 8_000, startup);
+    await ensureSupervisor(selected, environment);
     return await launchUi(selected, environment, sessionArgs);
 }
 /**
@@ -209,14 +227,7 @@ async function launchRetainedActive(state, paths, environment, sessionArgs, outp
         return null;
     try {
         const retained = await readCertifiedReleaseManifest(active, resolve(paths.dataDir, "releases"));
-        const retainedPaths = resolveCohortEndpoint(paths, retained.releaseId, environment);
-        const endpoint = await readEndpointMetadata(retainedPaths.endpointMetadataPath);
-        if (!endpoint || await probeOwnership(endpoint) !== "live-verified") {
-            if (endpoint)
-                await removeEndpointArtifacts(retainedPaths.endpointMetadataPath, retainedPaths.endpoint);
-            const startup = await startSupervisor(retained, environment);
-            await waitForVerifiedEndpoint(retainedPaths.endpointMetadataPath, retained, 8_000, startup);
-        }
+        await ensureSupervisor(retained, environment);
         output.write(`${PRODUCT_TEXT.diagnostic(`installation is being replaced; starting the retained release ${retained.packageVersion}`)}\n`);
         return await launchUi(retained, environment, sessionArgs);
     }
@@ -246,6 +257,25 @@ export async function recordParentCertifiedRelease(release, dataDir) {
     await chmod(path, 0o400);
     return path;
 }
+/** Reuse a verified owner, or join the winner if another launch starts the same cohort first. */
+export async function ensureSupervisor(release, environment) {
+    const paths = resolveCohortEndpoint(resolveProductPaths(environment), release.releaseId, environment);
+    const metadata = await readEndpointMetadata(paths.endpointMetadataPath);
+    if (metadata) {
+        const probe = await probeOwnership(metadata);
+        if (probe !== "dead") {
+            if (probe === "live-verified" && endpointMatchesRelease(metadata, release))
+                return;
+            throw new Error(PRODUCT_TEXT.diagnostic(`refused duplicate supervisor startup: existing ownership is ${probe}`));
+        }
+    }
+    const startup = await startSupervisor(release, environment);
+    await waitForVerifiedEndpoint(paths.endpointMetadataPath, release, 8_000, startup);
+}
+function endpointMatchesRelease(metadata, release) {
+    return metadata.releaseId === release.releaseId && metadata.releaseRoot === release.releaseRoot
+        && metadata.contentDigest === release.contentDigest;
+}
 export async function startSupervisor(release, environment) {
     const entry = await resolveReleaseEntryPoint(release, "bin/supervisor.js");
     const paths = resolveProductPaths(environment);
@@ -296,10 +326,11 @@ export function releaseEnvironment(environment, release, profile) {
 export async function waitForVerifiedEndpoint(path, release, timeoutMs, startup) {
     const deadline = Date.now() + timeoutMs;
     let childOutcome = null;
+    let collision = null;
     void startup?.childOutcome.then(outcome => { childOutcome = outcome; });
     while (Date.now() < deadline) {
         const metadata = await readEndpointMetadata(path);
-        if (metadata && metadata.releaseId === release.releaseId && await probeOwnership(metadata) === "live-verified") {
+        if (metadata && endpointMatchesRelease(metadata, release) && await probeOwnership(metadata) === "live-verified") {
             if (startup)
                 await rm(startup.resultPath, { force: true });
             return;
@@ -307,15 +338,21 @@ export async function waitForVerifiedEndpoint(path, release, timeoutMs, startup)
         if (startup) {
             const result = await readSupervisorStartupResult(startup.resultPath, startup.attemptId, startup.releaseId);
             if (result?.outcome === "failure") {
-                throw Object.assign(new Error(PRODUCT_TEXT.diagnostic(`supervisor startup failed at ${result.stage}: ${result.message}`)), {
+                const error = Object.assign(new Error(PRODUCT_TEXT.diagnostic(`supervisor startup failed at ${result.stage}: ${result.message}`)), {
                     code: result.code ?? "SUPERVISOR_STARTUP_FAILED",
                 });
+                if (result.code !== "EADDRINUSE")
+                    throw error;
+                // Concurrency: the winning process may not have published its authenticated metadata yet.
+                collision = error;
             }
         }
-        if (childOutcome)
+        if (childOutcome && !collision)
             throw new Error(PRODUCT_TEXT.diagnostic(`supervisor exited before readiness: ${JSON.stringify(childOutcome)}`));
         await new Promise(resolvePromise => setTimeout(resolvePromise, 40));
     }
+    if (collision)
+        throw collision;
     throw new Error(PRODUCT_TEXT.diagnostic(`supervisor did not publish verified endpoint metadata within ${timeoutMs}ms`));
 }
 export async function readEndpointMetadata(path) {
@@ -410,8 +447,7 @@ async function activatePendingAfterBlockerExit(candidate, stateStore, paths, env
         return;
     await removeEndpointArtifacts(paths.endpointMetadataPath, paths.endpoint);
     await stateStore.activate(candidate.releaseId);
-    const startup = await startSupervisor(candidate, environment);
-    await waitForVerifiedEndpoint(resolveCohortEndpoint(paths, candidate.releaseId, environment).endpointMetadataPath, candidate, 8_000, startup);
+    await ensureSupervisor(candidate, environment);
 }
 export async function releaseVerifiedIdleOwner(metadata, dataDir, operations = {}) {
     try {

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

@@ -10,6 +10,7 @@ export * from "./release-store.js";
 export * from "./restart-certification.js";
 export * from "./stable-release.js";
 export * from "./update.js";
+export * from "./update-launch.js";
 export * from "./update-recovery.js";
 export * from "./update-transaction.js";
 export * from "./warmup.js";

package/dist/foundation/release/index.js

@@ -10,6 +10,7 @@ export * from "./release-store.js";
 export * from "./restart-certification.js";
 export * from "./stable-release.js";
 export * from "./update.js";
+export * from "./update-launch.js";
 export * from "./update-recovery.js";
 export * from "./update-transaction.js";
 export * from "./warmup.js";

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

@@ -0,0 +1,6 @@
+import type { CohortState, ReleaseRecord } from "./cohort-state.js";
+import type { UpdateTransaction } from "./update-transaction.js";
+/** Keep interactive launches on the last successful release until the update commits success. */
+export declare function selectUpdateLaunchRelease(state: CohortState, transaction: UpdateTransaction | null): ReleaseRecord | null;
+/** Pause cohort retirement during preparation; afterward only the successful launch release admits new sessions. */
+export declare function selectSupervisorLaunchReleaseId(state: CohortState, transaction: UpdateTransaction | null): string | null;

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

@@ -0,0 +1,17 @@
+/** Keep interactive launches on the last successful release until the update commits success. */
+export function selectUpdateLaunchRelease(state, transaction) {
+    if (transaction === null || transaction.status === "completed")
+        return null;
+    const prior = transaction.priorActiveReleaseId === null ? undefined : state.releases[transaction.priorActiveReleaseId];
+    if (!prior || prior.approval !== "approved") {
+        throw new Error("unfinished update has no verified previous release available for launch; resume the update");
+    }
+    return prior;
+}
+/** Pause cohort retirement during preparation; afterward only the successful launch release admits new sessions. */
+export function selectSupervisorLaunchReleaseId(state, transaction) {
+    // Concurrency: both the previous cohort and the warming candidate must remain available until cutover.
+    if (transaction?.status === "active")
+        return null;
+    return selectUpdateLaunchRelease(state, transaction)?.releaseId ?? state.references.active;
+}

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

@@ -112,5 +112,7 @@ export type UpdateOwnershipAction = "clean-dead-record" | "leave-running" | "end
  */
 export declare function planUpdateOwnership(ownership: "live-verified" | "dead", runsFromRetainedRelease: boolean): UpdateOwnershipAction;
 export declare function createUpdateLifecycleCoordinator(environment?: NodeJS.ProcessEnv, fileSystem?: UpdateFileSystem, output?: UpdateOutput): UpdateLifecycleCoordinator;
+/** Renders the terminal-only update meter; the visual preview shares this exact frame. */
+export declare function renderUpdateProgressBar(percent: number): string;
 export declare function runSelfUpdate(options: SelfUpdateOptions): Promise<number>;
 export declare function assertUpdatePerformanceBudget(evidence: UpdatePerformanceEvidence, maximumPostNpmDurationMs?: number): void;

package/dist/foundation/release/update.js

@@ -5,7 +5,7 @@ import { isAbsolute, relative, resolve, sep } from "node:path";
 import crossSpawn from "cross-spawn";
 import { valid as validSemver } from "semver";
 import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
-import { certifyMaterializedRelease, probeOwnership, readEndpointMetadata, removeEndpointArtifacts, startSupervisor, waitForProcessExit, waitForVerifiedEndpoint, } from "./bootstrap.js";
+import { certifyMaterializedRelease, probeOwnership, readEndpointMetadata, removeEndpointArtifacts, ensureSupervisor, waitForProcessExit, } from "./bootstrap.js";
 import { resolveCohortEndpoint, resolveProductPaths } from "../lifecycle/index.js";
 import { encodeFrame, LineFrameDecoder } from "../protocol/index.js";
 import { CohortStateStore } from "./cohort-state.js";
@@ -163,17 +163,17 @@ export function createUpdateLifecycleCoordinator(environment = process.env, file
             const diagnostics = await certifyMaterializedRelease(candidate, paths.dataDir);
             await stateStore.approve(candidate.releaseId, diagnostics);
             await phase("certified");
-            await stateStore.activate(candidate.releaseId);
-            await phase("active-reference-committed");
             onWarmup?.("started");
             await warmMaterializedRelease(candidate, environment);
             onWarmup?.("completed");
-            const startup = await startSupervisor(candidate, environment);
-            await waitForVerifiedEndpoint(resolveCohortEndpoint(paths, candidate.releaseId, environment).endpointMetadataPath, candidate, 8_000, startup);
+            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 PROGRESS_BAR_WIDTH = 39;
+const PROGRESS_BAR_WIDTH = 40;
 const PROGRESS_TICK_MS = 200;
 /**
  * Copying the release owns 78–92 and is reported file by file, so the bar crosses
@@ -186,10 +186,15 @@ const ACTIVATION_PROGRESS = {
     certified: { at: 94, creepTo: 96 },
     "active-reference-committed": { at: 96, creepTo: 99 },
 };
-function renderProgressBar(percent) {
+/** Renders the terminal-only update meter; the visual preview shares this exact frame. */
+export function renderUpdateProgressBar(percent) {
     const bounded = Math.min(100, Math.max(0, Math.round(percent)));
     const filled = Math.round((bounded / 100) * PROGRESS_BAR_WIDTH);
-    return `${"█".repeat(filled)}${"░".repeat(PROGRESS_BAR_WIDTH - filled)} ${bounded}%`;
+    // Rationale: a gray line, a darker gray track, and one space before the percentage.
+    // Explicit RGB keeps both grays neutral even when the terminal remaps its ANSI palette.
+    const gray = "\u001b[38;2;128;128;128m";
+    const track = "\u001b[38;2;102;102;102m";
+    return `${gray}${"━".repeat(filled)}${track}${"─".repeat(PROGRESS_BAR_WIDTH - filled)}${gray} ${bounded}%\u001b[39m`;
 }
 function createUpdateProgress(output, enabled) {
     let visible = false;
@@ -202,7 +207,7 @@ function createUpdateProgress(output, enabled) {
             return;
         shown = rounded;
         visible = true;
-        output.stdout(`\r${renderProgressBar(rounded)}`);
+        output.stdout(`\r${renderUpdateProgressBar(rounded)}`);
     };
     const stopCreep = () => {
         if (timer !== null) {
@@ -375,11 +380,7 @@ export async function runSelfUpdate(options) {
         : async () => await scheduleReleaseCleanup(paths.dataDir, paths));
     let transaction = await transactionStore.read();
     try {
-        if (await lifecycle.targetIsActive(targetVersion)) {
-            if (transaction?.status === "active") {
-                await transactionStore.advance("supervisor-verified");
-                await transactionStore.finish("completed");
-            }
+        if ((!transaction || transaction.status === "completed") && await lifecycle.targetIsActive(targetVersion)) {
             await maintenance();
             await transactionStore.clearCompleted();
             output.stdout(`${PRODUCT_TEXT.commandName} is up to date — no update needed.\n`);
@@ -510,13 +511,14 @@ export async function runSelfUpdate(options) {
         options.onPhaseTiming?.({ phase: "supervisor-verified", durationMs: Math.max(0, now() - activationPhaseStartedAt) });
         const transactionStartedAt = now();
         await transactionStore.advance("supervisor-verified");
-        await transactionStore.finish("completed");
         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 maintenance();
-        await transactionStore.clearCompleted();
+        // Concurrency: this is the launch cutover. No failure-prone update work follows success.
+        await transactionStore.finish("completed");
+        await transactionStore.clearCompleted().catch(() => undefined);
         options.onPhaseTiming?.({ phase: "transaction-complete", durationMs: Math.max(0, now() - transactionStartedAt) });
         progress.finish();
         output.stdout(`${PRODUCT_TEXT.commandName} updated successfully: ${targetVersion}\n`);
@@ -609,11 +611,8 @@ async function rollbackPriorCohort(dataDir, environment, priorReleaseId) {
             throw new Error(`prior release ${priorReleaseId} is not the recorded rollback cohort`);
     }
     const release = await readMaterializedRelease(prior.releaseRoot);
-    const paths = resolveProductPaths(environment);
-    // Invariant: rollback re-points the active reference and starts the prior cohort on its own endpoint;
-    // a cohort that survived the update keeps serving the work it already had.
-    const startup = await startSupervisor(release, environment);
-    await waitForVerifiedEndpoint(resolveCohortEndpoint(paths, release.releaseId, environment).endpointMetadataPath, release, 8_000, startup);
+    // Invariant: rollback reuses a surviving prior cohort rather than racing its occupied endpoint.
+    await ensureSupervisor(release, environment);
     return "rolled back";
 }
 function phaseBefore(current, target) {

package/dist/foundation/supervision/main.js

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { appendFileSync, mkdirSync } from "node:fs";
 import { resolve } from "node:path";
-import { assertImmutableExecutionRoot, CohortStateStore, readCertifiedReleaseManifest, recordParentCertifiedRelease } from "../release/index.js";
+import { assertImmutableExecutionRoot, CohortStateStore, readCertifiedReleaseManifest, recordParentCertifiedRelease, selectSupervisorLaunchReleaseId, UpdateTransactionStore } from "../release/index.js";
 import { publishSupervisorStartupResult, supervisorStartupFailure, supervisorStartupReady, supervisorStartupResultPath } from "../lifecycle/index.js";
 import { ControlStore } from "../storage/index.js";
 import { resolveCohortEndpoint, resolveProductPaths } from "./paths.js";
@@ -38,7 +38,10 @@ export async function runSupervisor(arguments_ = []) {
         const bootNonce = randomUUID();
         const store = new ControlStore(paths.databasePath, bootNonce);
         const cohortState = new CohortStateStore(paths.dataDir);
-        server = new SupervisorServer(store, paths, release, bootNonce, undefined, undefined, undefined, async () => (await cohortState.read()).references.active);
+        server = new SupervisorServer(store, paths, release, bootNonce, undefined, undefined, undefined, async () => {
+            const transaction = await new UpdateTransactionStore(paths.dataDir).read();
+            return selectSupervisorLaunchReleaseId(await cohortState.read(), transaction);
+        });
         stage = "endpoint-listen";
         await server.listen();
         if (resultPath && attemptId)