@timurproko/a1 0.1.1-dev.9 → 0.1.5-dev.11

package/dist/src/foundation/pi-engine-adapter/adapter.js

@@ -4,7 +4,7 @@ import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { promisify } from "node:util";
 import { PRODUCT_IDENTITY } from "../../product-identity.js";
-import { copyToClipboard, getAgentDir, ProjectTrustStore, SessionManager, } from "@earendil-works/pi-coding-agent";
+import { copyToClipboard, DefaultPackageManager, getAgentDir, ProjectTrustStore, SessionManager, } from "@earendil-works/pi-coding-agent";
 import { OWNED_UI_EXTENSION_CONTRACT_VERSION, OWNED_UI_EXTENSION_RENDER_CALLBACKS, OWNED_UI_EXTENSION_UI_CALLBACKS, OWNED_UI_EXTENSION_UI_PROPERTIES, assertOwnedUiCommand, assertOwnedUiExtensionUiPort, assertOwnedUiSnapshot, } from "../owned-ui-contracts/index.js";
 import { PINNED_PI_SETTINGS_CALLBACKS, PINNED_PI_WORKFLOW_COMMAND_NAMES, } from "./workflows.js";
 import { createPiRuntimeIntegration } from "./runtime-integration.js";
@@ -19,6 +19,7 @@ const DEFAULT_SURFACE = {
 };
 export class PiEngineAdapter {
     #runtimeFactory;
+    #checkPackageUpdates;
     #cwd;
     #agentDir;
     #sessionId;
@@ -73,6 +74,10 @@ export class PiEngineAdapter {
         this.#agentDir = options.agentDir ?? getAgentDir();
         this.#sessionId = options.sessionId ?? "owned-session-1";
         this.#runtimeFactory = options.createRuntime ?? createDefaultPiRuntime;
+        this.#checkPackageUpdates = options.checkPackageUpdates
+            ?? (options.createRuntime
+                ? async () => []
+                : settingsManager => checkDefaultPiPackageUpdates(this.#cwd, this.#agentDir, settingsManager));
         this.#workflowHost = options.workflowHost ?? defaultWorkflowHost();
         this.#availableThemes = options.availableThemes ?? null;
         this.#workflowInteraction = { prompt: async () => null, notify() { } };
@@ -122,8 +127,25 @@ export class PiEngineAdapter {
         this.#editor = { ...this.#editor, submitEnabled: true };
         this.#emitEvent({ type: "session-lifecycle", lifecycle: "ready", reason: null });
         this.#emitView();
+        void this.#announcePackageUpdates(runtime.services.settingsManager);
         return this.view();
     }
+    async #announcePackageUpdates(settingsManager) {
+        if (process.env.PI_OFFLINE)
+            return;
+        let updates;
+        try {
+            updates = await this.#checkPackageUpdates(settingsManager);
+        }
+        catch {
+            return;
+        }
+        if (this.#disposed || updates.length === 0)
+            return;
+        const packages = updates.map(name => `- ${name}`).join("\n");
+        this.#addDiagnostic("info", "package-updates", `Package updates are available. Run pi update --extensions\nPackages:\n${packages}`, true);
+        this.#emitView();
+    }
     onEvent(listener) {
         this.#listeners.add(listener);
         listener(this.#event({ type: "session-view", view: this.view() }));
@@ -1876,6 +1898,11 @@ export async function createPiEngineAdapter(options = {}) {
 async function createDefaultPiRuntime(input) {
     return createPiRuntimeIntegration({ cwd: input.cwd, agentDir: input.agentDir });
 }
+async function checkDefaultPiPackageUpdates(cwd, agentDir, settingsManager) {
+    const packageManager = new DefaultPackageManager({ cwd, agentDir, settingsManager });
+    const updates = await packageManager.checkForAvailableUpdates();
+    return updates.map(update => update.displayName);
+}
 function pinnedSessionInfoPresentation(value, sessionName, entries, modelRuntime) {
     const stats = isRecord(value) ? value : {};
     const tokens = dynamicObject(stats, "tokens");

package/dist/src/foundation/pi-engine-adapter/index.d.ts

@@ -4,6 +4,7 @@ export * from "./runtime-integration.js";
 export * from "./session-integration.js";
 export * from "./model-auth-integration.js";
 export * from "./settings-integration.js";
+export * from "./package-integration.js";
 export * from "./resource-extension-integration.js";
 export * from "./workflow-controllers.js";
 export * from "./workflows.js";

package/dist/src/foundation/pi-engine-adapter/index.js

@@ -4,6 +4,7 @@ export * from "./runtime-integration.js";
 export * from "./session-integration.js";
 export * from "./model-auth-integration.js";
 export * from "./settings-integration.js";
+export * from "./package-integration.js";
 export * from "./resource-extension-integration.js";
 export * from "./workflow-controllers.js";
 export * from "./workflows.js";

package/dist/src/foundation/pi-engine-adapter/package-integration.d.ts

@@ -0,0 +1,13 @@
+import { type AgentPackagesPort, type AgentPackagesPortInput } from "../agent-engine-contracts/index.js";
+/**
+ * Pinned Pi's package manager already takes the profile root as an argument, so
+ * this binds it to the root A1 chose rather than to whatever the configuration-root
+ * environment variable happens to say. Pi's own package command handler is not used:
+ * it prints Pi's command names and ends the process, and both of those belong to
+ * whichever A1 command is running.
+ *
+ * The settings manager is created with project trust withheld, which is what keeps
+ * every operation to the user scope of the selected profile — a project-local
+ * `packages` list is never read, so it can never be written either.
+ */
+export declare function createPiPackagesPort(input: AgentPackagesPortInput): AgentPackagesPort;

package/dist/src/foundation/pi-engine-adapter/package-integration.js

@@ -0,0 +1,112 @@
+import { join } from "node:path";
+import { DefaultPackageManager, ModelRuntime, SettingsManager } from "@earendil-works/pi-coding-agent";
+import { agentPackageOutcome, } from "../agent-engine-contracts/index.js";
+const MODEL_REFRESH_TIMEOUT_MS = 15_000;
+/**
+ * Pinned Pi's package manager already takes the profile root as an argument, so
+ * this binds it to the root A1 chose rather than to whatever the configuration-root
+ * environment variable happens to say. Pi's own package command handler is not used:
+ * it prints Pi's command names and ends the process, and both of those belong to
+ * whichever A1 command is running.
+ *
+ * The settings manager is created with project trust withheld, which is what keeps
+ * every operation to the user scope of the selected profile — a project-local
+ * `packages` list is never read, so it can never be written either.
+ */
+export function createPiPackagesPort(input) {
+    const { profileRoot, cwd } = input;
+    const settingsManager = SettingsManager.create(cwd, profileRoot, { projectTrusted: false });
+    const packageManager = new DefaultPackageManager({ cwd, agentDir: profileRoot, settingsManager });
+    packageManager.setProgressCallback(event => {
+        if (event.type !== "start" || !event.message)
+            return;
+        input.onProgress?.({ operation: operationFor(event.action), message: event.message });
+    });
+    const configured = () => packageManager.listConfiguredPackages()
+        .filter(entry => entry.scope === "user")
+        .map(entry => Object.freeze({
+        source: entry.source,
+        installedPath: entry.installedPath ?? null,
+        filtered: entry.filtered,
+    }));
+    const isConfigured = (source) => configured().some(entry => entry.source === source || entry.source.startsWith(`${source}@`));
+    return Object.freeze({
+        capabilities: Object.freeze({ install: true, remove: true, update: true, refreshModels: true }),
+        profileRoot,
+        async list() {
+            return await attempt("list", null, async () => agentPackageOutcome("list", "completed", null, null, configured()));
+        },
+        async install(source) {
+            return await attempt("install", source, async () => {
+                await packageManager.installAndPersist(source);
+                return agentPackageOutcome("install", "completed", null, source, configured());
+            });
+        },
+        async remove(source) {
+            return await attempt("remove", source, async () => {
+                const removed = await packageManager.removeAndPersist(source);
+                if (!removed)
+                    return agentPackageOutcome("remove", "not-found", null, source);
+                return agentPackageOutcome("remove", "completed", null, source, configured());
+            });
+        },
+        async update(source) {
+            return await attempt("update", source ?? null, async () => {
+                // Asking first keeps "that package is not installed here" a structural
+                // answer rather than a string a caller would have to recognize.
+                if (source !== undefined && !isConfigured(source))
+                    return agentPackageOutcome("update", "not-found", null, source);
+                await packageManager.update(source);
+                return agentPackageOutcome("update", "completed", null, source ?? null, configured());
+            });
+        },
+        async refreshModels() {
+            return await attempt("refresh-models", null, async () => {
+                await refreshModelCatalogs(profileRoot);
+                return agentPackageOutcome("refresh-models", "completed");
+            });
+        },
+    });
+}
+async function attempt(operation, source, run) {
+    try {
+        return await run();
+    }
+    catch (error) {
+        return agentPackageOutcome(operation, "failed", describe(error), source);
+    }
+}
+async function refreshModelCatalogs(profileRoot) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), MODEL_REFRESH_TIMEOUT_MS);
+    try {
+        const modelRuntime = await ModelRuntime.create({
+            authPath: join(profileRoot, "auth.json"),
+            modelsPath: join(profileRoot, "models.json"),
+            allowModelNetwork: false,
+            signal: controller.signal,
+        });
+        const result = await modelRuntime.refresh({ allowNetwork: true, force: true, signal: controller.signal });
+        if (result.aborted)
+            throw new Error(`model catalog refresh timed out after ${MODEL_REFRESH_TIMEOUT_MS}ms`);
+        if (result.errors.size > 0) {
+            throw new Error(Array.from(result.errors, ([provider, error]) => `${provider}: ${error.message}`).join("; "));
+        }
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function operationFor(action) {
+    if (action === "install")
+        return "install";
+    if (action === "remove")
+        return "remove";
+    return "update";
+}
+function describe(error) {
+    const message = (error instanceof Error ? error.message : String(error)).replace(/\s+/g, " ").trim();
+    if (message.length === 0)
+        return "unknown package failure";
+    return message.length > 600 ? `${message.slice(0, 597)}...` : message;
+}

package/dist/src/foundation/pi-engine-adapter/runtime-integration.d.ts

@@ -1,4 +1,4 @@
-import { type AgentSession, type AgentSessionRuntime } from "@earendil-works/pi-coding-agent";
+import { type AgentSession, type AgentSessionRuntime, type AgentSessionServices, type ScopedModel } from "@earendil-works/pi-coding-agent";
 export interface PiRuntimeIntegrationOptions {
     readonly cwd: string;
     readonly agentDir: string;
@@ -10,9 +10,26 @@ export type PiSessionReplacement = {
     readonly kind: "resume";
     readonly sessionPath: string;
 };
+interface ConfiguredModelScope {
+    readonly scopedModels: readonly ScopedModel[];
+    readonly model: ScopedModel["model"] | undefined;
+    readonly thinkingLevel: ScopedModel["thinkingLevel"];
+    readonly diagnostics: readonly {
+        type: "info" | "warning" | "error";
+        message: string;
+    }[];
+}
+/**
+ * Mirrors pinned Pi's CLI startup: resolve the `models` patterns from settings
+ * into a scoped model list, keep the resolver's warnings (e.g. "No models match
+ * pattern ..."), and pick the same initial model pinned Pi would pick — the
+ * saved default when it is in scope, otherwise the first scoped model.
+ */
+export declare function resolveConfiguredModelScope(services: Pick<AgentSessionServices, "settingsManager" | "modelRuntime">): Promise<ConfiguredModelScope>;
 export declare function createPiRuntimeIntegration(options: PiRuntimeIntegrationOptions): Promise<AgentSessionRuntime>;
 export declare function bindPiRuntimeSession(runtime: AgentSessionRuntime, rebind: (session: AgentSession) => Promise<void>): () => void;
 export declare function replacePiRuntimeSession(runtime: AgentSessionRuntime, replacement: PiSessionReplacement): Promise<{
     readonly cancelled: boolean;
 }>;
 export declare function disposePiRuntimeIntegration(runtime: AgentSessionRuntime): Promise<void>;
+export {};

package/dist/src/foundation/pi-engine-adapter/runtime-integration.js

@@ -1,14 +1,49 @@
-import { createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, SessionManager, } from "@earendil-works/pi-coding-agent";
+import { createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, resolveModelScopeWithDiagnostics, SessionManager, } from "@earendil-works/pi-coding-agent";
+/**
+ * Mirrors pinned Pi's CLI startup: resolve the `models` patterns from settings
+ * into a scoped model list, keep the resolver's warnings (e.g. "No models match
+ * pattern ..."), and pick the same initial model pinned Pi would pick — the
+ * saved default when it is in scope, otherwise the first scoped model.
+ */
+export async function resolveConfiguredModelScope(services) {
+    const patterns = services.settingsManager.getEnabledModels();
+    if (!patterns || patterns.length === 0) {
+        return { scopedModels: [], model: undefined, thinkingLevel: undefined, diagnostics: [] };
+    }
+    const { scopedModels, diagnostics } = await resolveModelScopeWithDiagnostics([...patterns], services.modelRuntime, { signal: AbortSignal.timeout(15_000) });
+    let selected;
+    if (scopedModels.length > 0) {
+        const savedProvider = services.settingsManager.getDefaultProvider();
+        const savedModelId = services.settingsManager.getDefaultModel();
+        const savedModel = savedProvider && savedModelId
+            ? services.modelRuntime.getModel(savedProvider, savedModelId)
+            : undefined;
+        selected = (savedModel
+            ? scopedModels.find(scoped => scoped.model.provider === savedModel.provider && scoped.model.id === savedModel.id)
+            : undefined) ?? scopedModels[0];
+    }
+    return {
+        scopedModels,
+        model: selected?.model,
+        thinkingLevel: selected?.thinkingLevel,
+        diagnostics: diagnostics.map(diagnostic => ({ type: diagnostic.type, message: diagnostic.message })),
+    };
+}
 export async function createPiRuntimeIntegration(options) {
     const sessionManager = SessionManager.create(options.cwd, options.sessionDir ?? process.env.PI_CODING_AGENT_SESSION_DIR);
     const createRuntime = async ({ cwd, sessionManager: targetSessionManager, sessionStartEvent, }) => {
         const services = await createAgentSessionServices({ cwd, agentDir: options.agentDir });
+        const modelScope = await resolveConfiguredModelScope(services);
+        const hasExistingSession = targetSessionManager.buildSessionContext().messages.length > 0;
         const created = await createAgentSessionFromServices({
             services,
             sessionManager: targetSessionManager,
             ...(sessionStartEvent ? { sessionStartEvent } : {}),
+            ...(modelScope.model && !hasExistingSession ? { model: modelScope.model } : {}),
+            ...(modelScope.thinkingLevel && !hasExistingSession ? { thinkingLevel: modelScope.thinkingLevel } : {}),
+            ...(modelScope.scopedModels.length > 0 ? { scopedModels: [...modelScope.scopedModels] } : {}),
         });
-        return { ...created, services, diagnostics: services.diagnostics };
+        return { ...created, services, diagnostics: [...modelScope.diagnostics] };
     };
     return createAgentSessionRuntime(createRuntime, {
         cwd: options.cwd,

package/dist/src/foundation/pi-owned-ui-integration/session-shell.js

@@ -1,6 +1,6 @@
 import { MOUSE_TRACKING_OFF, MOUSE_TRACKING_ON, parseMouseInput } from "../ui-components/index.js";
 import { PINNED_PI_HIDDEN_COMMAND_NAMES, PINNED_PI_WORKFLOW_COMMAND_NAMES, } from "../pi-engine-adapter/index.js";
-import { createPiExtensionUiBridge, createPiQueuedInputStatus, createPiShellArmin, createPiShellAuthProviderSelector, createPiShellChangelog, createPiShellDaxnuts, createPiShellDialog, createPiShellEarendilAnnouncement, createPiShellEditor, createPiShellExtensionSelector, createPiShellFooter, createPiShellHeader, createPiShellHotkeys, createPiShellLoadedResources, createPiShellLoginDialog, createPiShellModelSelector, createPiShellOperationLoader, createPiShellReloadBox, createPiShellScopedModelsSelector, createPiShellSelector, createPiShellSessionInfo, createPiShellSessionSelector, createPiShellSettingsSelector, createPiShellStatus, createPiShellTranscriptComponent, createPiShellTreeSelector, createPiShellTrustSelector, createPiShellUserMessageSelector, piTheme, renderPiShellStatusText, renderPiShellTranscriptBlock, } from "../pi-component-adapter/index.js";
+import { createPiExtensionUiBridge, createPiQueuedInputStatus, createPiShellArmin, createPiShellAuthProviderSelector, createPiShellChangelog, createPiShellDaxnuts, createPiShellDialog, createPiShellEarendilAnnouncement, createPiShellEditor, createPiShellExtensionSelector, createPiShellFooter, createPiShellHeader, createPiShellHotkeys, createPiShellLoadedResources, createPiShellLoginDialog, createPiShellModelSelector, createPiShellOperationLoader, createPiShellReloadBox, createPiShellScopedModelsSelector, createPiShellSelector, createPiShellSessionInfo, createPiShellSessionSelector, createPiShellSettingsSelector, createPiShellStatus, createPiShellTranscriptComponent, createPiShellTreeSelector, createPiShellTrustSelector, createPiShellUserMessageSelector, piTheme, renderPiShellPackageUpdateNotice, renderPiShellStartupDiagnostic, renderPiShellStatusText, renderPiShellTranscriptBlock, } from "../pi-component-adapter/index.js";
 import { PiTuiRuntimeAdapter, } from "../pi-tui-runtime-adapter/index.js";
 export class OwnedUiSessionShellRoot {
     editor;
@@ -136,7 +136,17 @@ export class OwnedUiSessionShellRoot {
                 return ["", ...rows];
             return rows;
         });
-        const diagnosticRows = this.#view.diagnostics.slice(-3).flatMap(diagnostic => renderPiShellTranscriptBlock({
+        const diagnostics = this.#view.diagnostics;
+        const startupRows = diagnostics
+            .filter(diagnostic => diagnostic.code === "engine-startup")
+            .flatMap(diagnostic => renderPiShellStartupDiagnostic(diagnostic, width));
+        const packageUpdateRows = diagnostics
+            .filter(diagnostic => diagnostic.code === "package-updates")
+            .flatMap(diagnostic => renderPiShellPackageUpdateNotice(diagnostic.message.split("\n").filter(line => line.startsWith("- ")).map(line => line.slice(2)), width));
+        const diagnosticRows = diagnostics
+            .filter(diagnostic => diagnostic.code !== "engine-startup" && diagnostic.code !== "package-updates")
+            .slice(-3)
+            .flatMap(diagnostic => renderPiShellTranscriptBlock({
             id: `diagnostic-${diagnostic.sequence}`,
             kind: diagnostic.severity === "error" ? "error" : "system",
             status: "finalized",
@@ -149,9 +159,11 @@ export class OwnedUiSessionShellRoot {
         if (resourceRows.at(-1) === "")
             resourceRows.pop();
         return [
+            ...startupRows,
             ...(this.#extensionHeader ?? this.header).render(width),
             ...resourceRows,
             ...transcript,
+            ...packageUpdateRows,
             ...diagnosticRows,
         ];
     }

package/dist/src/foundation/pi-tui-runtime-adapter/adapter.js

@@ -1,4 +1,4 @@
-import { HStack, ProcessTerminal, ScrollView, TuiAltScreen, TuiMainScreen, VStack, visibleWidth, } from "@earendil-works/pi-tui";
+import { HStack, ProcessTerminal, ScrollView, TuiAltScreen, TuiMainScreen, VStack, visibleWidth, } from "#pi-tui";
 export class PiTuiRuntimeError extends Error {
     stage;
     constructor(stage, cause) {

package/dist/src/foundation/release/release.js

@@ -139,11 +139,24 @@ async function findInstalledDependency(root, requesterRoot, name) {
     let directory = requesterRoot;
     while (true) {
         const candidate = resolve(directory, "node_modules", name);
-        const fromRoot = relative(root, candidate);
-        if (fromRoot !== ".." && !fromRoot.startsWith(`..${sep}`) && !isAbsolute(fromRoot)) {
+        if (await isContained(root, candidate)) {
             const metadata = await lstat(candidate).catch(() => null);
             if (metadata?.isDirectory() && !metadata.isSymbolicLink())
                 return candidate;
+            // A linked dependency directory is how this installation unifies a module
+            // that would otherwise be present twice, and the link is made by A1 itself
+            // at install and at every launch. Follow it to the directory it names and
+            // collect from there, so the payload still reads only real files — but
+            // only when the target is inside this installation, so a link can never
+            // pull bytes in from somewhere else.
+            if (metadata?.isSymbolicLink()) {
+                const target = await realpath(candidate).catch(() => null);
+                if (target !== null && await isContained(root, target)) {
+                    const targetMetadata = await lstat(target).catch(() => null);
+                    if (targetMetadata?.isDirectory())
+                        return target;
+                }
+            }
         }
         if (directory === root)
             return null;
@@ -153,6 +166,17 @@ async function findInstalledDependency(root, requesterRoot, name) {
         directory = parent;
     }
 }
+/** True when `path` sits inside `root`, comparing what each one actually resolves to. */
+async function isContained(root, path) {
+    const within = (from, to) => {
+        const value = relative(from, to);
+        return value !== ".." && !value.startsWith(`..${sep}`) && !isAbsolute(value);
+    };
+    if (within(root, path))
+        return true;
+    const canonicalRoot = await realpath(root).catch(() => null);
+    return canonicalRoot !== null && within(canonicalRoot, path);
+}
 function dependencyNames(value) {
     if (value === undefined)
         return [];

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

@@ -39,17 +39,27 @@ export interface SelfUpdateOptions {
     runner?: UpdateProcessRunner;
     lifecycle?: UpdateLifecycleCoordinator;
     transactionStore?: UpdateTransactionJournal;
+    progress?: boolean;
     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 interface UpdateLifecycleCoordinator {
     targetIsActive(targetVersion: string): Promise<boolean>;
     shutdownVerifiedOwners(targetVersion: string): Promise<{
         priorActiveVersion: string | null;
     }>;
     verifyPackageUnlocked(packageRoot: string): Promise<void>;
-    activateInstalled(packageRoot: string, targetVersion: string, phase: (phase: UpdateActivationPhase) => Promise<void>): Promise<void>;
+    activateInstalled(packageRoot: string, targetVersion: string, phase: (phase: UpdateActivationPhase) => Promise<void>, onMaterializing?: (progress: UpdateMaterializationProgress) => void): Promise<void>;
 }
 export interface UpdateTransactionJournal {
     readonly path: string;

package/dist/src/foundation/release/update.js

@@ -105,8 +105,21 @@ export function createUpdateLifecycleCoordinator(environment = process.env, file
                 throw new Error(PRODUCT_TEXT.diagnostic(`package remains locked after verified shutdown: ${errorMessage(error)}`));
             }
         },
-        async activateInstalled(packageRoot, targetVersion, phase) {
-            const candidate = await materializeRelease(packageRoot, paths.dataDir);
+        async activateInstalled(packageRoot, targetVersion, phase, onMaterializing) {
+            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")
+                        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);
@@ -121,6 +134,81 @@ export function createUpdateLifecycleCoordinator(environment = process.env, file
         },
     };
 }
+const PROGRESS_BAR_WIDTH = 39;
+const PROGRESS_TICK_MS = 200;
+/**
+ * Copying the release owns 78–92 and is reported file by file, so the bar crosses
+ * that span with the work rather than parking at its start. What follows is short,
+ * which is why the remaining milestones sit close together.
+ */
+const MATERIALIZE_PROGRESS = Object.freeze({ from: 78, to: 92 });
+const ACTIVATION_PROGRESS = {
+    materialized: { at: 92, creepTo: 94 },
+    certified: { at: 94, creepTo: 96 },
+    "active-reference-committed": { at: 96, creepTo: 99 },
+};
+function renderProgressBar(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}%`;
+}
+function createUpdateProgress(output, enabled) {
+    let visible = false;
+    let current = 0;
+    let shown = -1;
+    let timer = null;
+    const draw = () => {
+        const rounded = Math.round(current);
+        if (rounded === shown)
+            return;
+        shown = rounded;
+        visible = true;
+        output.stdout(`\r${renderProgressBar(rounded)}`);
+    };
+    const stopCreep = () => {
+        if (timer !== null) {
+            clearInterval(timer);
+            timer = null;
+        }
+    };
+    return {
+        set(percent, creepTo = percent) {
+            if (!enabled)
+                return;
+            stopCreep();
+            current = Math.max(current, percent);
+            shown = -1;
+            draw();
+            if (creepTo <= current)
+                return;
+            // Creep asymptotically toward (but never reach) the next milestone so
+            // long opaque phases such as npm install still show visible motion. The
+            // ceiling stays a whole point below the milestone: settling on `creepTo`
+            // itself would render as that milestone and make arriving at it invisible,
+            // which is what a stalled bar looks like.
+            timer = setInterval(() => {
+                current = Math.min(creepTo - 1, current + (creepTo - current) * 0.04);
+                draw();
+            }, PROGRESS_TICK_MS);
+            timer.unref?.();
+        },
+        finish() {
+            stopCreep();
+            if (!visible)
+                return;
+            output.stdout(`\r${renderProgressBar(100)}\n`);
+            visible = false;
+        },
+        clear() {
+            stopCreep();
+            if (!visible)
+                return;
+            output.stdout(`\r${" ".repeat(PROGRESS_BAR_WIDTH + 6)}\r`);
+            visible = false;
+            shown = -1;
+        },
+    };
+}
 export async function runSelfUpdate(options) {
     const fileSystem = options.fileSystem ?? defaultFileSystem;
     const output = options.output ?? defaultOutput;
@@ -157,7 +245,8 @@ export async function runSelfUpdate(options) {
         output.stderr(`${PRODUCT_TEXT.diagnostic(`received a malformed ${distTag} version from npm: ${JSON.stringify(targetLookup.result.stdout.trim())}.`)}\n`);
         return 1;
     }
-    output.stdout(`${PRODUCT_TEXT.diagnostic(`update (${channel}): ${runningVersion} → ${targetVersion}.`)}\n`);
+    output.stdout(`${PRODUCT_TEXT.commandName} update (${channel}): ${runningVersion} → ${targetVersion}.\n`);
+    const progress = createUpdateProgress(output, options.progress ?? (options.output === undefined && process.stdout.isTTY === true));
     const rootLookup = await measure("global-root", async () => await runNpm(runner, ["root", "--global"], true, output, "resolve npm's global package root"));
     if (rootLookup.result === null)
         return rootLookup.exitCode;
@@ -190,9 +279,11 @@ export async function runSelfUpdate(options) {
                 await transactionStore.finish("completed");
             }
             await transactionStore.clearCompleted();
-            output.stdout(`${PRODUCT_TEXT.diagnostic("is already current and active for this channel; no installation was changed.")}\n`);
+            output.stdout(`${PRODUCT_TEXT.commandName} is up to date — no update needed.\n`);
             return 0;
         }
+        // The bar first appears here so a no-change run never flashes it.
+        progress.set(3, 15);
         const cohortState = await new CohortStateStore(paths.dataDir).read();
         transaction = await transactionStore.begin({
             channel,
@@ -207,6 +298,7 @@ export async function runSelfUpdate(options) {
             });
             transaction = await transactionStore.advance("ownership-released");
         }
+        progress.set(15, 70);
         if (phaseBefore(transaction.phase, "package-installed")) {
             const installation = await measure("npm-install", async () => await runNpm(runner, ["install", "--global", "--loglevel=error", "--no-fund", "--no-audit", `${PRODUCT_PACKAGE}@${targetVersion}`], true, output, "start the global npm installation", false));
             if (installation.result === null)
@@ -218,15 +310,22 @@ export async function runSelfUpdate(options) {
             }
             transaction = await transactionStore.advance("package-installed");
         }
+        progress.set(70, 75);
         // Ownership can be reacquired after an interrupted installation (for
         // example, if bare A1 is launched before the update is resumed). Recheck
         // immediately before activation so recovery cannot start a second cohort.
         await measure("ownership-release", async () => { await lifecycle.shutdownVerifiedOwners(targetVersion); });
+        progress.set(75, MATERIALIZE_PROGRESS.from);
         let activationPhaseStartedAt = now();
         await lifecycle.activateInstalled(packageRoot, targetVersion, async (phase) => {
             options.onPhaseTiming?.({ phase, durationMs: Math.max(0, now() - activationPhaseStartedAt) });
             transaction = await transactionStore.advance(phase);
+            progress.set(ACTIVATION_PROGRESS[phase].at, ACTIVATION_PROGRESS[phase].creepTo);
             activationPhaseStartedAt = now();
+        }, ({ completed, total }) => {
+            const span = MATERIALIZE_PROGRESS.to - MATERIALIZE_PROGRESS.from;
+            const done = total > 0 ? Math.min(1, completed / total) : 0;
+            progress.set(MATERIALIZE_PROGRESS.from + span * done);
         });
         options.onPhaseTiming?.({ phase: "supervisor-verified", durationMs: Math.max(0, now() - activationPhaseStartedAt) });
         const transactionStartedAt = now();
@@ -234,10 +333,12 @@ export async function runSelfUpdate(options) {
         await transactionStore.finish("completed");
         await transactionStore.clearCompleted();
         options.onPhaseTiming?.({ phase: "transaction-complete", durationMs: Math.max(0, now() - transactionStartedAt) });
-        output.stdout(`${PRODUCT_TEXT.diagnostic(`updated successfully: ${targetVersion} (${channel}).`)}\n`);
+        progress.finish();
+        output.stdout(`${PRODUCT_TEXT.commandName} updated successfully: ${targetVersion} (${channel}).\n`);
         return 0;
     }
     catch (error) {
+        progress.clear();
         const message = errorMessage(error);
         const rollback = options.lifecycle
             ? "previous test lifecycle retained"

package/docs/architecture/toolchain.md

@@ -69,11 +69,11 @@ This optional, mutating presentation-maintenance workflow regenerates component
 
 Presentation acceptance is the reader comparing `a1 pi` with pinned Pi. `node scripts/check-pinned-pi-source-ledger.mjs` validates accepted provenance; its `--engine-only` mode validates the ownership partition without comparing private upstream source.
 
-## Preview publication
+## Publication
 
-A preview candidate must use a unique `-dev.N` version and exact manually accepted bytes. Publication packs once, binds evidence to source commit/version/integrity, runs applicable non-desktop gates, publishes under npm `next`, and verifies registry identity. It must keep `latest` unchanged and record physical/cross-platform certification as deferred.
+One workflow publishes both channels: `.github/workflows/release.yml`, triggered by every push to `develop`. What the pushed commit declares decides the channel: a prerelease version publishes a preview under npm `next` at a unique `-dev.N` version stamped at publish time, and a stable version publishes under npm `latest`. Both pack once, validate those exact bytes on Windows, Linux, and macOS, and publish with provenance from the `npm-publish` environment. The publisher never rebuilds, a preview never changes `latest`, and the release tag, GitHub Release, and `master` are written only after the registry has the package.
 
-The GitHub trusted-publishing workflow is `.github/workflows/npm-publish.yml`. Stable publication remains a separate release process from a clean tagged `master` commit after all mandatory platform gates pass.
+`docs/ci-release-runbook.md` is the operational reference.
 
 ## A1 state paths