@timurproko/a1 0.1.7 → 0.1.8-dev.b449b5c

package/README.md

@@ -12,7 +12,7 @@ npm install --global @timurproko/a1@latest
 a1              # A1-owned UI and profile: ~/.a1/agent
 a1 version      # show Installed, Release (latest), and Next versions
 a1 update       # update to npm latest
-a1 update:next  # update to npm next
+a1 update:next  # update to npm next (or a1 update:<commit> for a specific preview)
 ```
 
 Prerelease builds — what `a1 update:next` installs — add two development profiles
@@ -68,9 +68,15 @@ time and never committed, so previews cost no commits and need no command, and a
 installed preview says exactly which source produced it.
 
 ```sh
-a1 update:next   # install the newest preview
+a1 update:next          # install the newest preview
+a1 update:7eabe9e       # install the preview built from that commit
+a1 update:0.1.8-dev.7eabe9e   # or name the version outright
 ```
 
+Naming a commit is what the version suffix is for: read it off `a1 version`, a
+pull request, or a commit list, and install exactly that build. A commit that was
+never published is refused rather than guessed at.
+
 ### Stable — npm `latest`
 
 One command, from a clean `develop` that matches its remote:

package/bin/cli.js

@@ -22,9 +22,9 @@ process.exitCode = await dispatchCli(process.argv.slice(2), {
     const { runVersionStats } = await import("../dist/src/cli/index.js");
     return await runVersionStats({ packageRoot: fileURLToPath(packageRoot) });
   },
-  update: async channel => {
+  update: async (channel, target) => {
     const { runSelfUpdate } = await import("../dist/src/foundation/release/index.js");
-    return await runSelfUpdate({ packageRoot: fileURLToPath(packageRoot), channel });
+    return await runSelfUpdate({ packageRoot: fileURLToPath(packageRoot), channel, ...(target === undefined ? {} : { target }) });
   },
   packages: async request => {
     const [{ runPackageCommand }, { createPiPackagesPort }] = await Promise.all([

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

@@ -5,7 +5,7 @@
   "platform": "darwin",
   "architecture": "arm64",
   "capability": "unsupported",
-  "builtAt": "2026-08-24T05:41:42.321Z",
+  "builtAt": "2026-08-24T06:35:58.522Z",
   "artifact": {
     "filename": "process-guardian",
     "sha256": "7524bf568992517f50ed53196c861c5edeba0d7275633bb4735ab45bd5963a28",

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

@@ -5,7 +5,7 @@
   "platform": "linux",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-08-24T05:41:49.189Z",
+  "builtAt": "2026-08-24T06:35:49.229Z",
   "artifact": {
     "filename": "process-guardian",
     "sha256": "29e22fe29de2828982bc67ef418c4adcaab1490281477b7bea592ec6fe621bcd",

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

@@ -5,10 +5,10 @@
   "platform": "win32",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-08-24T05:42:24.069Z",
+  "builtAt": "2026-08-24T06:36:28.685Z",
   "artifact": {
     "filename": "process-guardian.exe",
-    "sha256": "c0b203cd361d080f7e5a2e108d7c090a5ef94ab466631e1e01b6af93cd7ab226",
+    "sha256": "1d535ec647852d21736769e0d418b80f9a99d02a9721609a13f251300986b9b9",
     "size": 172544
   },
   "provenance": {

package/dist/src/cli/dispatch.d.ts

@@ -5,7 +5,7 @@ export type UpdateChannel = "stable" | "next";
 export interface CliHandlers {
     readonly launch: (intent: InteractiveLaunchIntent) => Promise<number>;
     readonly version: () => Promise<number>;
-    readonly update: (channel: UpdateChannel) => Promise<number>;
+    readonly update: (channel: UpdateChannel, target?: string) => Promise<number>;
     readonly packages: (request: PackageCommandRequest) => Promise<number>;
 }
 export interface CliOutput {
@@ -21,6 +21,7 @@ export type CliCommand = {
 } | {
     readonly kind: "update";
     readonly channel: UpdateChannel;
+    readonly target?: string;
 } | {
     readonly kind: "packages";
     readonly request: PackageCommandRequest;

package/dist/src/cli/dispatch.js

@@ -7,6 +7,7 @@ export function cliUsage(capabilities) {
         "version",
         "update [self|<source>|--extensions|--models]",
         "update:next",
+        "update:<commit>",
         "install <source>",
         "remove <source>",
         "list",
@@ -25,7 +26,7 @@ export async function dispatchCli(arguments_, handlers, output, capabilities) {
         return await handlers.version();
     if (command.kind === "packages")
         return await handlers.packages(command.request);
-    return await handlers.update(command.channel);
+    return await handlers.update(command.channel, command.target);
 }
 export function parseCliCommand(arguments_, capabilities) {
     if (arguments_.length === 0)
@@ -36,8 +37,8 @@ export function parseCliCommand(arguments_, capabilities) {
     }
     if (command === "version")
         return withoutArguments(rest, { kind: "version" });
-    if (command === "update:next")
-        return withoutArguments(rest, { kind: "update", channel: "next" });
+    if (command !== undefined && command.startsWith("update:"))
+        return parseColonUpdate(command.slice("update:".length), rest);
     if (command === "update")
         return parseUpdate(rest);
     if (command === "install" || command === "remove" || command === "uninstall") {
@@ -51,6 +52,24 @@ export function parseCliCommand(arguments_, capabilities) {
         return { kind: "error", message: `Bare ${PRODUCT_TEXT.commandName} is the ${PRODUCT_TEXT.displayName} agent experience; there is no agent subcommand.` };
     return { kind: "error", message: PRODUCT_TEXT.diagnostic(`received an unknown command: ${command ?? ""}`) };
 }
+/**
+ * What follows the colon says which build to move to. `next` is the newest
+ * preview; anything else names one outright, by the commit it was built from or by
+ * its full version — a preview is published as `<version>-dev.<commit>`, so the
+ * commit alone is enough to find it.
+ */
+function parseColonUpdate(suffix, rest) {
+    if (rest.length > 0)
+        return { kind: "error", message: PRODUCT_TEXT.diagnostic("update takes what to move to after the colon, and nothing else.") };
+    if (suffix === "next")
+        return { kind: "update", channel: "next" };
+    if (suffix.length === 0)
+        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`update: needs a preview after the colon, as in ${PRODUCT_TEXT.commandName} update:next.`) };
+    if (!/^[0-9a-z][0-9a-z.+-]*$/i.test(suffix)) {
+        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`received an unusable preview: ${suffix}`) };
+    }
+    return { kind: "update", channel: "next", target: suffix };
+}
 /**
  * `update` carries both meanings pinned Pi gives it: itself by default, and the
  * profile's packages when a target says so. Pi is refused as a target because A1

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,56 @@ 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)
+        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 +299,14 @@ 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;
+    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 +395,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

package/package.json

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