@timurproko/a1 0.1.8-dev.820b4a4 → 0.1.8-dev.99e912e

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,16 @@ 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
 ```
 
+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 — you never need to
+know which version it went out under. A commit that was never published is refused
+rather than guessed at. A full preview version works in the same place, so a string
+pasted back from `a1 version` is understood too.
+
 ### Stable — npm `latest`
 
 One command, from a clean `develop` that matches its remote:
@@ -86,7 +93,7 @@ It lands the version on `develop` through a pull request that merges itself.
 **Landing it is what publishes** — the workflow builds, validates the packed release
 on Windows, Linux, and macOS, publishes to npm `latest` with provenance, and only
 then writes the `v<version>` tag and records the GitHub Release. The command waits
-for that to succeed, then lands the next `-dev.0` version so previews resume
+for that to succeed, then opens the next `-dev` line so previews resume
 immediately.
 
 ```sh

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-24T06:21:14.306Z",
+  "builtAt": "2026-08-24T07:36:29.445Z",
   "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-24T06:21:16.988Z",
+  "builtAt": "2026-08-24T07:36:31.707Z",
   "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-24T06:21:59.348Z",
+  "builtAt": "2026-08-24T07:36:58.529Z",
   "artifact": {
     "filename": "process-guardian.exe",
-    "sha256": "a6130ee1d6a5008de29c91aba4ed592381aa9e192faa27a4b7d07b817555fbac",
+    "sha256": "c8491147088aa02f51443ecef1aa9f9e36914f9c899e221668bb3a36d9140941",
     "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/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

@@ -221,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;
@@ -249,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 (${UPDATE_CHANNEL_LABELS[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)
@@ -346,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}.\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.8-dev.820b4a4",
+  "version": "0.1.8-dev.99e912e",
   "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;

package/dist/src/foundation/release/development-preview-release.js

@@ -1,114 +0,0 @@
-import { compare, inc, prerelease, valid } from "semver";
-import { PRODUCT_IDENTITY } from "../../product-identity.js";
-export const PREVIEW_RELEASE_SCHEMA = PRODUCT_IDENTITY.evidence.previewReleaseSchema;
-export function createUncertifiedDevelopmentPreviewEvidence(input) {
-    const prereleaseParts = prerelease(input.version);
-    if (valid(input.version) === null || prereleaseParts?.[0] !== "dev") {
-        throw new Error(`uncertified preview requires a development prerelease: ${input.version}`);
-    }
-    return {
-        schema: PREVIEW_RELEASE_SCHEMA,
-        channel: "next",
-        certificationStatus: "uncertified-development-preview",
-        terminalCapability: "owned-ui",
-        manualAcceptance: "accepted",
-        physicalHostCertification: "deferred",
-        crossPlatformCertification: "deferred",
-        stableReleaseEligible: false,
-        ...input,
-    };
-}
-export function requireManuallyAcceptedDevelopmentPreview(version, acceptedVersion) {
-    const acceptedPrerelease = prerelease(acceptedVersion);
-    if (valid(acceptedVersion) === null || acceptedPrerelease?.[0] !== "dev") {
-        throw new Error(`invalid manually accepted development preview: ${acceptedVersion}`);
-    }
-    if (version !== acceptedVersion) {
-        throw new Error(`development preview ${version} has no exact manual acceptance; accepted version is ${acceptedVersion}`);
-    }
-}
-export function selectDevelopmentPreviewCandidate(currentVersion, publishedVersions) {
-    if (valid(currentVersion) === null)
-        throw new Error(`invalid current package version: ${currentVersion}`);
-    const published = publishedVersions.map(version => {
-        if (valid(version) === null)
-            throw new Error(`invalid published package version: ${version}`);
-        return version;
-    });
-    const publishedSet = new Set(published);
-    const highestPublished = published.reduce((highest, version) => highest === null || compare(version, highest) > 0 ? version : highest, null);
-    const currentPrerelease = prerelease(currentVersion);
-    const currentIsUnpublishedLeadingDev = currentPrerelease?.[0] === "dev"
-        && !publishedSet.has(currentVersion)
-        && (highestPublished === null || compare(currentVersion, highestPublished) > 0);
-    if (currentIsUnpublishedLeadingDev)
-        return { version: currentVersion, requiresVersionCommit: false };
-    const base = highestPublished === null || compare(currentVersion, highestPublished) > 0
-        ? currentVersion
-        : highestPublished;
-    const basePrerelease = prerelease(base);
-    let candidate = basePrerelease?.[0] === "dev"
-        ? inc(base, "prerelease", "dev")
-        : inc(base, "prepatch", "dev");
-    if (candidate === null)
-        throw new Error(`could not increment development preview from ${base}`);
-    while (publishedSet.has(candidate)) {
-        candidate = inc(candidate, "prerelease", "dev");
-        if (candidate === null)
-            throw new Error(`could not increment development preview from ${base}`);
-    }
-    return { version: candidate, requiresVersionCommit: candidate !== currentVersion };
-}
-/**
- * Treats npm's process result as provisional: browser-auth completion can fail
- * after the immutable upload succeeds. Registry identity remains authoritative.
- */
-export async function publishDevelopmentPreviewWithRecovery(publish, verify) {
-    let publishError = null;
-    try {
-        await publish();
-    }
-    catch (error) {
-        publishError = error;
-    }
-    try {
-        await verify();
-        return { published: true, recoveredPublishError: publishError };
-    }
-    catch (verificationError) {
-        if (publishError !== null)
-            throw new AggregateError([publishError, verificationError], "npm publish failed and the exact version could not be verified in the registry");
-        throw verificationError;
-    }
-}
-export async function verifyDevelopmentPreviewRegistry(version, observe, repairNextTag, options = {}) {
-    const attempts = options.attempts ?? 12;
-    const delayMs = options.delayMs ?? 2_000;
-    const delay = options.delay ?? (async (milliseconds) => await new Promise(resolvePromise => setTimeout(resolvePromise, milliseconds)));
-    if (!Number.isInteger(attempts) || attempts < 1)
-        throw new Error(`invalid registry verification attempts: ${attempts}`);
-    let repaired = false;
-    let last = { published: false, nextVersion: null };
-    for (let attempt = 1; attempt <= attempts; attempt += 1) {
-        last = await observe();
-        if (last.published && last.nextVersion === version)
-            return;
-        if (last.published && !repaired) {
-            await repairNextTag();
-            repaired = true;
-        }
-        if (attempt < attempts)
-            await delay(delayMs);
-    }
-    if (!last.published)
-        throw new Error(`npm registry did not expose published version ${version} after ${attempts} attempts`);
-    throw new Error(`npm next resolved ${last.nextVersion ?? "nothing"}; expected ${version} after ${attempts} attempts`);
-}
-export function developmentPreviewTarballName(packageName, version) {
-    if (valid(version) === null)
-        throw new Error(`invalid development preview version: ${version}`);
-    const unscopedName = packageName.startsWith("@") ? packageName.slice(1).replace("/", "-") : packageName;
-    if (!/^[a-z0-9._-]+$/i.test(unscopedName))
-        throw new Error(`invalid package name: ${packageName}`);
-    return `${unscopedName}-${version}.tgz`;
-}