@timurproko/a1 0.1.7 → 0.1.8-dev.0b6d8cc

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, renderPiShellPackageUpdateNotice, renderPiShellStartupDiagnostic, 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, onPiThemeChange, piTheme, renderPiShellPackageUpdateNotice, renderPiShellStartupDiagnostic, renderPiShellStatusText, renderPiShellTranscriptBlock, } from "../pi-component-adapter/index.js";
 import { PiTuiRuntimeAdapter, } from "../pi-tui-runtime-adapter/index.js";
 export class OwnedUiSessionShellRoot {
     editor;
@@ -8,6 +8,9 @@ export class OwnedUiSessionShellRoot {
     resources;
     #cwd;
     #transcript = new Map();
+    #blocksById = new Map();
+    #renderedRows = new Map();
+    #themeUnsubscribe;
     #transcriptOrder = [];
     #view;
     #status;
@@ -54,6 +57,9 @@ export class OwnedUiSessionShellRoot {
                 this.editor.addToHistory(block.text);
         }
         this.#syncTranscript(view.transcript);
+        // Colours come from the active theme, so rendered rows outlive their revision only
+        // until the theme under them changes.
+        this.#themeUnsubscribe = onPiThemeChange(() => this.#renderedRows.clear());
     }
     update(view) {
         this.#view = view;
@@ -128,10 +134,10 @@ export class OwnedUiSessionShellRoot {
     }
     #renderDocument(width) {
         const transcript = this.#transcriptOrder.flatMap((id, index) => {
-            const block = this.#view.transcript.find(item => item.id === id);
+            const block = this.#blocksById.get(id);
             if (!this.#thinkingVisible && block?.kind === "thinking")
                 return [];
-            const rows = this.#transcript.get(id)?.render(width) ?? [];
+            const rows = this.#blockRows(id, block, width);
             if (index > 0 && block?.kind === "user")
                 return ["", ...rows];
             return rows;
@@ -167,6 +173,25 @@ export class OwnedUiSessionShellRoot {
             ...diagnosticRows,
         ];
     }
+    /**
+     * Rows for one transcript block. A finalized block renders once for a given revision
+     * and width and is reused after that, so a frame costs what changed rather than what
+     * the session has accumulated. A live block, and anything the shell drives itself, is
+     * rendered every time because its content is still moving.
+     */
+    #blockRows(id, block, width) {
+        const component = this.#transcript.get(id);
+        if (component === undefined)
+            return [];
+        if (block === undefined || block.status !== "finalized")
+            return component.render(width);
+        const cached = this.#renderedRows.get(id);
+        if (cached && cached.width === width && cached.revision === block.revision)
+            return cached.rows;
+        const rows = component.render(width);
+        this.#renderedRows.set(id, { width, revision: block.revision, rows });
+        return rows;
+    }
     transcriptComponent(id) {
         return this.#transcript.get(id);
     }
@@ -334,6 +359,8 @@ export class OwnedUiSessionShellRoot {
         this.#extensionWorkingMessage = undefined;
         this.#status.setWorkingOverride(undefined);
         this.#footer.update(this.#viewWithExtensionStatuses(this.#view));
+        // An extension renderer may have drawn transcript blocks that are now unrendered by it.
+        this.#renderedRows.clear();
         this.invalidate();
     }
     addExtensionNotification(message, type) {
@@ -384,11 +411,13 @@ export class OwnedUiSessionShellRoot {
         this.#inputSurface.setFocused?.(focused);
     }
     dispose() {
+        this.#themeUnsubscribe();
         this.header.dispose?.();
         this.resources.dispose?.();
         for (const component of this.#transcript.values())
             component.dispose?.();
         this.#transcript.clear();
+        this.#renderedRows.clear();
         if (this.#inputSurface !== this.editor)
             this.#inputSurface.dispose?.();
         this.#extensionHeader?.dispose?.();
@@ -402,12 +431,16 @@ export class OwnedUiSessionShellRoot {
         this.#queued.dispose?.();
     }
     #syncTranscript(blocks) {
+        this.#blocksById.clear();
+        for (const block of blocks)
+            this.#blocksById.set(block.id, block);
         const nextIds = new Set(blocks.map(block => block.id));
         for (const [id, component] of this.#transcript) {
             if (id.startsWith("workflow-status-") || nextIds.has(id))
                 continue;
             component.dispose?.();
             this.#transcript.delete(id);
+            this.#renderedRows.delete(id);
         }
         for (const block of blocks) {
             const component = this.#transcript.get(block.id);
@@ -431,8 +464,9 @@ export class OwnedUiSessionShellRoot {
             if (block !== undefined)
                 order.push(block.id);
         }
+        const placed = new Set(order);
         for (const statusId of statusIds) {
-            if (!order.includes(statusId))
+            if (!placed.has(statusId))
                 order.push(statusId);
         }
         this.#transcriptOrder = order;
@@ -498,6 +532,8 @@ export class OwnedUiSessionShellRoot {
         this.resources.setExpanded(expanded);
         for (const component of this.#transcript.values())
             component.setExpanded(expanded);
+        // Expansion changes what a block draws without changing its revision.
+        this.#renderedRows.clear();
         this.invalidate();
     }
 }
@@ -525,12 +561,14 @@ function shellResourceEntries(backend) {
         sourcePath: resource.sourcePath,
         diagnostic: resource.diagnostic,
     }));
-    for (const extension of backend.extensionResources()) {
-        if (extension.hidden)
-            continue;
+    const extensions = backend.extensionResources().filter(extension => !extension.hidden);
+    const loadedExtensions = extensions.filter(extension => extension.diagnostic === null);
+    const extensionLabels = compactExtensionLabels(loadedExtensions);
+    for (const extension of extensions) {
+        const labelIndex = loadedExtensions.indexOf(extension);
         resources.push({
             section: "Extensions",
-            label: compactResourceLabel(extension.sourcePath ?? extension.resolvedPath ?? "extension"),
+            label: extensionLabels[labelIndex] ?? compactResourceLabel(extension.sourcePath ?? extension.resolvedPath ?? "extension"),
             sourcePath: extension.sourcePath ?? extension.resolvedPath,
             diagnostic: extension.diagnostic,
         });
@@ -538,12 +576,129 @@ function shellResourceEntries(backend) {
     return resources;
 }
 function compactResourceLabel(path) {
-    const segments = path.replaceAll("\\", "/").split("/").filter(Boolean);
+    const segments = compactPathSegments(path);
     const leaf = segments.at(-1) ?? path;
     if ((leaf === "index.ts" || leaf === "index.js") && segments.length > 1)
         return segments.at(-2) ?? leaf;
     return leaf;
 }
+/**
+ * Pinned from InteractiveMode's compact extension-label helpers at Pi commit
+ * 914cf1472e715297caa30db4b9535d534a9eb718. The source metadata crosses an
+ * A1-owned boundary first; the owned shell never inspects Pi's private root.
+ */
+function compactExtensionLabels(extensions) {
+    const localExtensions = extensions
+        .filter(extension => !isPackageExtensionSource(extension.sourceInfo))
+        .map(extension => {
+        const path = extension.sourcePath ?? extension.resolvedPath ?? "extension";
+        const segments = compactPathSegments(path);
+        if (segments.length > 1 && (segments.at(-1) === "index.ts" || segments.at(-1) === "index.js"))
+            segments.pop();
+        return { extension, segments };
+    });
+    return extensions.map(extension => {
+        const resourcePath = extension.sourcePath ?? extension.resolvedPath ?? "extension";
+        if (isPackageExtensionSource(extension.sourceInfo)) {
+            return compactPackageExtensionLabel(resourcePath, extension.sourceInfo);
+        }
+        const localIndex = localExtensions.findIndex(item => item.extension === extension);
+        const segments = localExtensions[localIndex]?.segments;
+        if (!segments || segments.length === 0)
+            return compactResourceLabel(resourcePath);
+        for (let count = 1; count <= segments.length; count += 1) {
+            const candidate = segments.slice(-count).join("/");
+            if (localExtensions.every((item, itemIndex) => itemIndex === localIndex || item.segments.slice(-count).join("/") !== candidate)) {
+                return candidate;
+            }
+        }
+        return segments.join("/");
+    });
+}
+function compactPackageExtensionLabel(resourcePath, sourceInfo) {
+    const sourceLabel = compactPackageSourceLabel(sourceInfo.source);
+    if (!sourceLabel)
+        return compactResourceLabel(resourcePath);
+    const shortPath = shortPackagePath(resourcePath, sourceInfo).replaceAll("\\", "/");
+    const packagePath = shortPath.startsWith("extensions/") ? shortPath.slice("extensions/".length) : shortPath;
+    const slash = packagePath.lastIndexOf("/");
+    const fileName = slash < 0 ? packagePath : packagePath.slice(slash + 1);
+    const directory = slash < 0 ? "" : packagePath.slice(0, slash);
+    const extension = fileName.lastIndexOf(".");
+    const name = extension <= 0 ? fileName : fileName.slice(0, extension);
+    if (name === "index")
+        return !directory || directory === "." ? sourceLabel : `${sourceLabel}:${directory}`;
+    return `${sourceLabel}:${packagePath}`;
+}
+function compactPackageSourceLabel(source) {
+    if (source.startsWith("npm:"))
+        return source.slice("npm:".length) || source;
+    if (!source.startsWith("git:"))
+        return source;
+    const gitSource = source.slice("git:".length).trim();
+    let repositoryPath;
+    const scpLike = gitSource.match(/^git@[^:]+:(.+)$/);
+    if (scpLike?.[1]) {
+        repositoryPath = scpLike[1];
+    }
+    else if (/^[a-z]+:\/\//i.test(gitSource)) {
+        try {
+            repositoryPath = new URL(gitSource).pathname.replace(/^\/+/, "");
+        }
+        catch {
+            return source;
+        }
+    }
+    else {
+        const slash = gitSource.indexOf("/");
+        if (slash >= 0)
+            repositoryPath = gitSource.slice(slash + 1);
+    }
+    if (!repositoryPath)
+        return source;
+    const ref = repositoryPath.indexOf("@");
+    const withoutRef = ref < 0 ? repositoryPath : repositoryPath.slice(0, ref);
+    return withoutRef.replace(/\.git$/, "") || source;
+}
+function shortPackagePath(resourcePath, sourceInfo) {
+    const fullPath = normalizeResourcePath(resourcePath);
+    const baseDir = sourceInfo.baseDir === null ? undefined : normalizeResourcePath(sourceInfo.baseDir).replace(/\/$/, "");
+    if (baseDir) {
+        const npmRoot = baseDir.match(/^(.*\/node_modules)\/(@?[^/]+(?:\/[^/]+)?)$/);
+        if (npmRoot?.[1] && fullPath.startsWith(`${npmRoot[1]}/`))
+            return relativeResourcePath(baseDir, fullPath);
+        if (fullPath === baseDir)
+            return ".";
+        if (fullPath.startsWith(`${baseDir}/`))
+            return fullPath.slice(baseDir.length + 1);
+    }
+    const npmMatch = fullPath.match(/node_modules\/(@?[^/]+(?:\/[^/]+)?)\/(.*)/);
+    if (npmMatch?.[2] && sourceInfo.source.startsWith("npm:"))
+        return npmMatch[2];
+    const gitMatch = fullPath.match(/git\/[^/]+\/[^/]+\/(.*)/);
+    if (gitMatch?.[1] && sourceInfo.source.startsWith("git:"))
+        return gitMatch[1];
+    return resourcePath;
+}
+function relativeResourcePath(from, to) {
+    const fromSegments = from.split("/").filter(Boolean);
+    const toSegments = to.split("/").filter(Boolean);
+    let common = 0;
+    while (common < fromSegments.length && common < toSegments.length
+        && fromSegments[common]?.toLowerCase() === toSegments[common]?.toLowerCase())
+        common += 1;
+    return [...fromSegments.slice(common).map(() => ".."), ...toSegments.slice(common)].join("/") || ".";
+}
+function compactPathSegments(path) {
+    return normalizeResourcePath(path).split("/").filter(segment => segment.length > 0 && segment !== "~");
+}
+function normalizeResourcePath(path) {
+    return path.replaceAll("\\", "/");
+}
+function isPackageExtensionSource(sourceInfo) {
+    const source = sourceInfo?.source ?? "";
+    return source.startsWith("npm:") || source.startsWith("git:");
+}
 export class OwnedUiSessionShell {
     backend;
     root;
@@ -560,6 +715,7 @@ export class OwnedUiSessionShell {
     #sequence = 0;
     #started = false;
     #disposed = false;
+    #pointerReporting = false;
     #compactionQueue = [];
     #lastClearTime = 0;
     #activeLoginDialog;
@@ -638,8 +794,10 @@ export class OwnedUiSessionShell {
         });
         this.root.editor.setAutocompleteCommands(this.backend.workflowAutocompleteCommands());
         this.#unsubscribe = this.backend.onEvent(event => {
-            this.#syncView();
-            if (this.view().lifecycle === "ready" && this.#compactionQueue.length > 0)
+            // One view read per event: the model is built by the backend, and building it
+            // twice per streamed chunk is what made a long session cost more per chunk.
+            const view = this.#syncView();
+            if (view.lifecycle === "ready" && this.#compactionQueue.length > 0)
                 void this.#flushCompactionQueue();
             if (event.type === "session-lifecycle" && event.lifecycle === "stopped")
                 this.#resolveStopped?.();
@@ -1232,10 +1390,25 @@ export class OwnedUiSessionShell {
             this.root.appendDaxnuts();
         }
     }
+    /**
+     * Turns terminal pointer reporting on for a screen that reads the pointer, and off for
+     * every path that ends it. While it is on the terminal hands A1 the wheel and the
+     * button instead of scrolling and selecting itself, so leaving it on outlives the
+     * screen that wanted it and takes the terminal's own scrolling and selection with it.
+     */
+    #setPointerReporting(enabled) {
+        if (this.#pointerReporting === enabled)
+            return;
+        this.#pointerReporting = enabled;
+        if (!this.runtime.active)
+            return;
+        this.runtime.writeControl(enabled ? MOUSE_TRACKING_ON : MOUSE_TRACKING_OFF);
+    }
     async dispose() {
         if (this.#disposed)
             return;
         this.#disposed = true;
+        this.#setPointerReporting(false);
         this.#unsubscribe();
         this.#dialogHandle?.hide();
         await this.backend.unbindExtensionUi();
@@ -1248,6 +1421,8 @@ export class OwnedUiSessionShell {
             this.#sessionGeneration = this.backend.sessionGeneration;
             this.#activeLoginDialog = undefined;
             this.#extensionBridge.reset();
+            // A replaced session takes its screens with it, pointer reporting included.
+            this.#setPointerReporting(false);
             this.root.setInputSurface(null);
             this.root.resetExtensionUi();
             this.root.resetWorkflowPresentation();
@@ -1257,6 +1432,7 @@ export class OwnedUiSessionShell {
         this.runtime.requestRender();
         for (const listener of this.#listeners)
             listener(view);
+        return view;
     }
     #openOwnedRoute(route) {
         const surface = this.#routeHost?.open(route) ?? null;
@@ -1267,7 +1443,7 @@ export class OwnedUiSessionShell {
         this.#dialogHandle?.hide();
         // Any-event reporting: hover and drag are what the screen is driven by, and
         // it also stops the terminal treating a drag as a text selection.
-        this.runtime.writeControl(MOUSE_TRACKING_ON);
+        this.#setPointerReporting(true);
         // The interrupt chord is global, so it is watched on raw input rather than
         // through the overlay: the pinned shell handles that key before an overlay
         // ever sees it, which is why an owned screen must not rely on being asked.
@@ -1290,7 +1466,7 @@ export class OwnedUiSessionShell {
         });
         const closeSurface = () => {
             removeInterruptWatch();
-            this.runtime.writeControl(MOUSE_TRACKING_OFF);
+            this.#setPointerReporting(false);
             this.#dialogHandle?.hide();
             this.#dialogHandle = undefined;
             this.#dialogId = undefined;

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

@@ -1,7 +1,6 @@
 export * from "./bootstrap.js";
 export * from "./cohort-selection.js";
 export * from "./cohort-state.js";
-export * from "./development-preview-release.js";
 export * from "./process-cleanup.js";
 export * from "./release.js";
 export * from "./release-gc.js";

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

@@ -1,7 +1,6 @@
 export * from "./bootstrap.js";
 export * from "./cohort-selection.js";
 export * from "./cohort-state.js";
-export * from "./development-preview-release.js";
 export * from "./process-cleanup.js";
 export * from "./release.js";
 export * from "./release-gc.js";

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

@@ -33,6 +33,8 @@ export interface UpdatePerformanceEvidence {
 export interface SelfUpdateOptions {
     packageRoot: string;
     channel?: UpdateChannel;
+    /** A specific preview to install, named by its commit or its full version. */
+    target?: string;
     environment?: NodeJS.ProcessEnv;
     fileSystem?: UpdateFileSystem;
     output?: UpdateOutput;

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

@@ -14,6 +14,13 @@ import { materializeRelease, readMaterializedRelease } from "./release-store.js"
 import { UpdateTransactionStore } from "./update-transaction.js";
 export const PRODUCT_PACKAGE = PRODUCT_TEXT.packageName;
 const UPDATE_DIST_TAGS = { stable: "latest", next: "next" };
+/**
+ * What each channel is called when A1 says it out loud. The internal name stays
+ * `stable` because that is what the channel is, but what a reader is moving to is
+ * a release, and that is the word the repository, its tags, and its GitHub
+ * releases all use.
+ */
+const UPDATE_CHANNEL_LABELS = { stable: "release", next: "next" };
 const defaultFileSystem = {
     async readFile(path) { return await readFile(path, "utf8"); },
     realpath,
@@ -192,12 +199,17 @@ function createUpdateProgress(output, enabled) {
             }, PROGRESS_TICK_MS);
             timer.unref?.();
         },
+        // The bar exists to say the update is still moving. Once it has finished
+        // there is a better line to occupy that row — the one naming what is now
+        // installed — so the bar gives the row back rather than leaving a full
+        // meter above a message that already implies it.
         finish() {
             stopCreep();
             if (!visible)
                 return;
-            output.stdout(`\r${renderProgressBar(100)}\n`);
+            output.stdout(`\r${" ".repeat(PROGRESS_BAR_WIDTH + 6)}\r`);
             visible = false;
+            shown = -1;
         },
         clear() {
             stopCreep();
@@ -209,6 +221,64 @@ function createUpdateProgress(output, enabled) {
         },
     };
 }
+/** The newest version the channel points at, which is what an unqualified update takes. */
+async function resolveChannelHead(runner, distTag, output) {
+    const lookup = await runNpm(runner, ["view", `${PRODUCT_PACKAGE}@${distTag}`, "version"], true, output, `query the npm ${distTag} channel`);
+    if (lookup.result === null)
+        return { version: null, exitCode: lookup.exitCode };
+    const version = validSemver(lookup.result.stdout.trim());
+    if (version === null) {
+        output.stderr(`${PRODUCT_TEXT.diagnostic(`received a malformed ${distTag} version from npm: ${JSON.stringify(lookup.result.stdout.trim())}.`)}\n`);
+        return { version: null, exitCode: 1 };
+    }
+    return { version, exitCode: 0 };
+}
+/**
+ * Resolve a preview the caller named.
+ *
+ * A preview is published as `<version>-dev.<commit>`, so its commit is enough to
+ * say which one is wanted — the version in front of it is not something anyone
+ * should have to remember. A full version is accepted too, for anyone reading one
+ * back from `a1 version` or a changelog.
+ *
+ * The published list is the authority: naming a commit that was never published,
+ * or one published more than once under different versions, is an error rather
+ * than a guess.
+ */
+async function resolveRequestedPreview(runner, requested, output) {
+    const lookup = await runNpm(runner, ["view", PRODUCT_PACKAGE, "versions", "--json"], true, output, "list the published versions");
+    if (lookup.result === null)
+        return { version: null, exitCode: lookup.exitCode };
+    let published;
+    try {
+        published = JSON.parse(lookup.result.stdout.trim() || "[]");
+    }
+    catch {
+        output.stderr(`${PRODUCT_TEXT.diagnostic(`received a malformed version list from npm: ${JSON.stringify(lookup.result.stdout.trim())}.`)}\n`);
+        return { version: null, exitCode: 1 };
+    }
+    const versions = (Array.isArray(published) ? published : [published]).filter((value) => typeof value === "string");
+    const exact = versions.find(version => version === requested);
+    if (exact !== undefined) {
+        // Naming a release here would install it through the preview path, which is a
+        // different command with a different meaning. The commit form cannot express
+        // one, so only the fuller spelling of a preview reaches this.
+        if (!exact.includes("-dev.")) {
+            output.stderr(`${PRODUCT_TEXT.diagnostic(`${exact} is a release, not a preview; run ${PRODUCT_TEXT.commandName} update to move to the current release.`)}\n`);
+            return { version: null, exitCode: 1 };
+        }
+        return { version: exact, exitCode: 0 };
+    }
+    const matches = versions.filter(version => version.endsWith(`-dev.${requested}`));
+    if (matches.length === 1)
+        return { version: matches[0], exitCode: 0 };
+    if (matches.length > 1) {
+        output.stderr(`${PRODUCT_TEXT.diagnostic(`found more than one preview for ${requested}: ${matches.join(", ")}. Name the version instead.`)}\n`);
+        return { version: null, exitCode: 1 };
+    }
+    output.stderr(`${PRODUCT_TEXT.diagnostic(`published no preview for ${requested}.`)}\n`);
+    return { version: null, exitCode: 1 };
+}
 export async function runSelfUpdate(options) {
     const fileSystem = options.fileSystem ?? defaultFileSystem;
     const output = options.output ?? defaultOutput;
@@ -237,15 +307,16 @@ export async function runSelfUpdate(options) {
         output.stderr(`${PRODUCT_TEXT.diagnostic(`could not read its running package version: ${errorMessage(error)}`)}\n`);
         return 1;
     }
-    const targetLookup = await measure("target-resolution", async () => await runNpm(runner, ["view", `${PRODUCT_PACKAGE}@${distTag}`, "version"], true, output, `query the npm ${distTag} channel`));
-    if (targetLookup.result === null)
-        return targetLookup.exitCode;
-    const targetVersion = validSemver(targetLookup.result.stdout.trim());
-    if (targetVersion === null) {
-        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.commandName} update (${channel}): ${runningVersion} → ${targetVersion}.\n`);
+    const requested = options.target?.trim();
+    const resolved = await measure("target-resolution", async () => requested === undefined || requested.length === 0
+        ? await resolveChannelHead(runner, distTag, output)
+        : await resolveRequestedPreview(runner, requested, output));
+    if (resolved.version === null)
+        return resolved.exitCode;
+    const targetVersion = resolved.version;
+    // No full stop after a version: it already ends in a dot-separated identifier,
+    // and a trailing one reads as part of the version rather than as punctuation.
+    output.stdout(`${PRODUCT_TEXT.commandName} update (${UPDATE_CHANNEL_LABELS[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)
@@ -334,7 +405,7 @@ export async function runSelfUpdate(options) {
         await transactionStore.clearCompleted();
         options.onPhaseTiming?.({ phase: "transaction-complete", durationMs: Math.max(0, now() - transactionStartedAt) });
         progress.finish();
-        output.stdout(`${PRODUCT_TEXT.commandName} updated successfully: ${targetVersion} (${channel}).\n`);
+        output.stdout(`${PRODUCT_TEXT.commandName} updated successfully: ${targetVersion}\n`);
         return 0;
     }
     catch (error) {

package/docs/ci-release-runbook.md

@@ -37,7 +37,9 @@ The version is stamped at publish time — `<major.minor.patch>-dev.<short commi
 the base taken from whatever `package.json` declares and the suffix from the commit
 being published — and is never written back to the repository. An installed preview
 therefore names the exact source it came from, and rebuilding a commit produces the
-same version rather than a new one. `develop` therefore carries one open prerelease version between
+same version rather than a new one. That suffix is also how a specific preview is
+installed: `a1 update:<commit>` resolves it against the published list and
+refuses a commit that was never published. `develop` therefore carries one open prerelease version between
 releases, and no commit is ever spent on a preview.
 
 One consequence worth knowing: a push that would republish an existing version
@@ -52,7 +54,7 @@ npm run release -- patch     # or minor, major, or an exact x.y.z
 ```
 
 It lands `x.y.z` on `develop` through a pull request that merges itself, waits for
-that publication to succeed, and then lands `x.y.(z+1)-dev.0` so previews resume
+that publication to succeed, and then lands `x.y.(z+1)-dev` so previews resume
 immediately. It publishes nothing itself and creates no tag.
 
 Landing the stable version is what publishes. The same pipeline sees a commit

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timurproko/a1",
-  "version": "0.1.7",
+  "version": "0.1.8-dev.0b6d8cc",
   "description": "Standalone terminal workspace for supervised native and managed agents",
   "type": "module",
   "packageManager": "npm@11.13.0",

package/dist/src/foundation/release/development-preview-release.d.ts

@@ -1,49 +0,0 @@
-export declare const PREVIEW_RELEASE_SCHEMA: string;
-export interface DevelopmentPreviewCandidate {
-    readonly version: string;
-    readonly requiresVersionCommit: boolean;
-}
-export interface DevelopmentPreviewRegistryState {
-    readonly published: boolean;
-    readonly nextVersion: string | null;
-}
-export interface DevelopmentPreviewVerificationOptions {
-    readonly attempts?: number;
-    readonly delayMs?: number;
-    readonly delay?: (milliseconds: number) => Promise<void>;
-}
-export interface DevelopmentPreviewPublishResult {
-    readonly published: boolean;
-    readonly recoveredPublishError: unknown | null;
-}
-export interface UncertifiedDevelopmentPreviewEvidenceInput {
-    readonly packageName: string;
-    readonly version: string;
-    readonly commit: string;
-    readonly tarball: string;
-    readonly integrity: string;
-    readonly shasum: string;
-    readonly platform: NodeJS.Platform;
-    readonly architecture: string;
-    readonly recordedAt: string;
-}
-export interface UncertifiedDevelopmentPreviewEvidence extends UncertifiedDevelopmentPreviewEvidenceInput {
-    readonly schema: typeof PREVIEW_RELEASE_SCHEMA;
-    readonly channel: "next";
-    readonly certificationStatus: "uncertified-development-preview";
-    readonly terminalCapability: "owned-ui";
-    readonly manualAcceptance: "accepted";
-    readonly physicalHostCertification: "deferred";
-    readonly crossPlatformCertification: "deferred";
-    readonly stableReleaseEligible: false;
-}
-export declare function createUncertifiedDevelopmentPreviewEvidence(input: UncertifiedDevelopmentPreviewEvidenceInput): UncertifiedDevelopmentPreviewEvidence;
-export declare function requireManuallyAcceptedDevelopmentPreview(version: string, acceptedVersion: string): void;
-export declare function selectDevelopmentPreviewCandidate(currentVersion: string, publishedVersions: readonly string[]): DevelopmentPreviewCandidate;
-/**
- * Treats npm's process result as provisional: browser-auth completion can fail
- * after the immutable upload succeeds. Registry identity remains authoritative.
- */
-export declare function publishDevelopmentPreviewWithRecovery(publish: () => Promise<void>, verify: () => Promise<void>): Promise<DevelopmentPreviewPublishResult>;
-export declare function verifyDevelopmentPreviewRegistry(version: string, observe: () => Promise<DevelopmentPreviewRegistryState>, repairNextTag: () => Promise<void>, options?: DevelopmentPreviewVerificationOptions): Promise<void>;
-export declare function developmentPreviewTarballName(packageName: string, version: string): string;