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

package/README.md

@@ -10,13 +10,14 @@ npm install --global @timurproko/a1@latest
 
 ```sh
 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 (or a1 update:<commit> for a specific preview)
+a1 version              # show Installed, Release, and Develop versions
+a1 update               # update to the current release
+a1 update:develop       # update to the current development preview
+a1 update:107           # install numbered development preview 107
 a1 update --models      # refresh A1's model catalogs
 ```
 
-Prerelease builds — what `a1 update:next` installs — add two development profiles
+Prerelease builds — what `a1 update:develop` installs — add two development profiles
 for comparing against pinned Pi and for experimenting against an isolated profile.
 A release build does not carry them.
 
@@ -63,24 +64,30 @@ npm run test:full       # complete non-physical suite
 Two channels, both published by CI from the exact bytes it validated. Nothing is
 ever published from a workstation.
 
-### Previews — npm `next`
+### Development previews
 
-Automatic. Every push to `develop` publishes one, versioned
-`<major.minor.patch>-dev.<short commit>` — the base from whatever `package.json`
-declares, the suffix naming the commit it was built from. It is stamped at publish
-time and never committed, so previews cost no commits and need no command, and an
-installed preview says exactly which source produced it.
+Ordinary pushes to `develop` do not publish. The nightly run at `03:17 UTC` always
+performs complete verification of current `origin/develop`; it publishes only when
+that source's preview is absent. A maintainer can request the same authoritative
+GitHub Actions path and wait for its result:
 
 ```sh
-a1 update:next      # install the newest preview
-a1 update:7eabe9e   # install the preview built from that commit
+npm run develop
 ```
 
-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.
+A preview is `<major.minor.patch>-dev.<pull-request number>`, stamped only into the
+package. For example, the source GitHub presents as `develop (#107)` produces
+`0.1.8-dev.107`. Repeating a request for immutable version 107 succeeds without
+building or publishing again.
+
+```sh
+a1 update:develop       # install the current development preview
+a1 update:107           # install preview 107
+a1 update:0.1.8-dev.107 # install that exact full preview version
+```
+
+The published version list is authoritative: an unpublished number is refused
+rather than guessed. npm's `next` dist-tag remains an internal registry detail.
 
 ### Stable — npm `latest`
 
@@ -93,12 +100,11 @@ npm run release -- major     # 0.1.1        -> 1.0.0
 npm run release -- 0.4.0     # an exact version
 ```
 
-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 opens the next `-dev` line so previews resume
-immediately.
+It lands the version on `develop` through a pull request that merges itself, then
+explicitly dispatches publication for that exact commit. GitHub Actions 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 success before opening the next `-dev` line.
 
 ```sh
 a1 update        # install the newest stable release

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

@@ -5,7 +5,7 @@
   "platform": "darwin",
   "architecture": "arm64",
   "capability": "unsupported",
-  "builtAt": "2026-08-25T08:02:28.988Z",
+  "builtAt": "2026-08-25T09:42:56.359Z",
   "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-25T08:02:31.153Z",
+  "builtAt": "2026-08-25T09:43:23.793Z",
   "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-25T08:02:58.479Z",
+  "builtAt": "2026-08-25T09:44:35.937Z",
   "artifact": {
     "filename": "process-guardian.exe",
-    "sha256": "fdbde2408643ffb897f5107d96ed40e8c8467505ef7daa64f86f9c2497c304ca",
+    "sha256": "0e2919843f1cdc824ce48203dace68df43f8ebb4b24b190ff7baf6c13d4846b1",
     "size": 172544
   },
   "provenance": {

package/dist/src/cli/dispatch.js

@@ -6,8 +6,8 @@ export function cliUsage(capabilities) {
         ...(capabilities.developmentProfiles ? ["pi", "sandbox"] : []),
         "version",
         "update [self|--models]",
-        "update:next",
-        "update:<commit>",
+        "update:develop",
+        "update:<number>",
         "pi install <source>",
         "pi remove <source>",
         "pi list",
@@ -58,20 +58,22 @@ export function parseCliCommand(arguments_, capabilities) {
     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.
+ * What follows the colon says which development build to move to. `develop`
+ * selects the channel head; a positive decimal or a full numbered preview names
+ * one immutable publication.
  */
 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")
+    if (suffix === "next") {
+        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`renamed its development channel; run ${PRODUCT_TEXT.commandName} update:develop.`) };
+    }
+    if (suffix === "develop")
         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: "error", message: PRODUCT_TEXT.diagnostic(`update: needs a preview after the colon, as in ${PRODUCT_TEXT.commandName} update:develop.`) };
+    if (!/^[1-9]\d*$/.test(suffix) && !/^\d+\.\d+\.\d+-dev\.[1-9]\d*$/.test(suffix)) {
+        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`received an unusable numbered preview: ${suffix}`) };
     }
     return { kind: "update", channel: "next", target: suffix };
 }
@@ -94,8 +96,8 @@ function parseUpdate(rest) {
             message: PRODUCT_TEXT.diagnostic(`pins the Pi version it was certified against; run ${PRODUCT_TEXT.commandName} update to move ${PRODUCT_TEXT.displayName} itself.`),
         };
     }
-    if (target === "next" || target === "stable") {
-        const form = target === "next" ? `${PRODUCT_TEXT.commandName} update:next` : `${PRODUCT_TEXT.commandName} update`;
+    if (target === "next" || target === "develop" || target === "stable") {
+        const form = target === "stable" ? `${PRODUCT_TEXT.commandName} update` : `${PRODUCT_TEXT.commandName} update:develop`;
         return { kind: "error", message: PRODUCT_TEXT.diagnostic(`selects a release channel with a colon; run ${form}.`) };
     }
     if (target === "--models")

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

@@ -11,6 +11,12 @@ export interface PackageCommandRequest {
     readonly verb: PackageCommandVerb;
     readonly source: string | null;
 }
+export interface PackageCommandStyle {
+    readonly dim: (message: string) => string;
+    readonly bold: (message: string) => string;
+    readonly green: (message: string) => string;
+    readonly red: (message: string) => string;
+}
 export interface PackageCommandEnvironment {
     readonly createPort: (input: AgentPackagesPortInput) => AgentPackagesPort;
     readonly cwd?: string;
@@ -18,6 +24,8 @@ export interface PackageCommandEnvironment {
     readonly stdout?: (message: string) => void;
     readonly stderr?: (message: string) => void;
     readonly initializeProfile?: typeof initializeProductProfile;
+    /** Defaults to Chalk's terminal-aware styles; injectable for transcript tests. */
+    readonly style?: PackageCommandStyle;
 }
 export declare function runPackageCommand(request: PackageCommandRequest, environment: PackageCommandEnvironment): Promise<number>;
-export declare function renderPackageOutcome(outcome: AgentPackageOutcome, profileRoot: string): string;
+export declare function renderPackageOutcome(outcome: AgentPackageOutcome, profileRoot: string, style?: PackageCommandStyle): string;

package/dist/src/cli/packages.js

@@ -1,3 +1,4 @@
+import chalk from "chalk";
 import { configurationRootForProfile, initializeProductProfile, resolveLaunchProfilePaths } from "../features/launch/index.js";
 import { PRODUCT_TEXT } from "../product-identity.js";
 export async function runPackageCommand(request, environment) {
@@ -5,6 +6,7 @@ export async function runPackageCommand(request, environment) {
     const stderr = environment.stderr ?? (message => process.stderr.write(message));
     const cwd = environment.cwd ?? process.cwd();
     const processEnvironment = environment.environment ?? process.env;
+    const style = environment.style ?? chalk;
     const paths = resolveLaunchProfilePaths({ environment: processEnvironment });
     const profileRoot = configurationRootForProfile("a1", paths);
     if (profileRoot === null)
@@ -19,10 +21,10 @@ export async function runPackageCommand(request, environment) {
     const port = environment.createPort({
         profileRoot,
         cwd,
-        onProgress: progress => stdout(`${progress.message}\n`),
+        onProgress: progress => stdout(`${style.dim(progress.message)}\n`),
     });
     const outcome = await runVerb(port, request);
-    const rendered = renderPackageOutcome(outcome, profileRoot);
+    const rendered = renderPackageOutcome(outcome, profileRoot, style);
     (outcome.status === "completed" ? stdout : stderr)(rendered);
     return outcome.status === "completed" ? 0 : 1;
 }
@@ -37,38 +39,40 @@ async function runVerb(port, request) {
         throw new Error(PRODUCT_TEXT.diagnostic(`requires a source for ${request.verb}`));
     return request.verb === "install" ? await port.install(request.source) : await port.remove(request.source);
 }
-export function renderPackageOutcome(outcome, profileRoot) {
-    const name = PRODUCT_TEXT.displayName;
+export function renderPackageOutcome(outcome, profileRoot, style = chalk) {
+    // Model refresh remains an A1 top-level command. The `a1 pi` compatibility
+    // transcript applies to package operations only.
+    if (outcome.operation === "refresh-models") {
+        if (outcome.status === "failed") {
+            return `${PRODUCT_TEXT.diagnostic(`could not ${describeOperation(outcome.operation)}: ${outcome.detail ?? "unknown failure"}`)}\n`;
+        }
+        return `${PRODUCT_TEXT.displayName} refreshed the model catalogs in ${profileRoot}.\n`;
+    }
     if (outcome.status === "failed") {
-        return `${PRODUCT_TEXT.diagnostic(`could not ${describeOperation(outcome.operation)}: ${outcome.detail ?? "unknown failure"}`)}\n`;
+        return `${style.red(`Error: ${outcome.detail ?? "Unknown package command error"}`)}\n`;
     }
     if (outcome.status === "not-found") {
-        return `${PRODUCT_TEXT.diagnostic(`found no package matching ${outcome.source ?? "that source"} in ${profileRoot}.`)}\n`;
+        return `${style.red(`No matching package found for ${outcome.source ?? "that source"}`)}\n`;
     }
     switch (outcome.operation) {
         case "install":
-            return `${name} installed ${outcome.source} into ${profileRoot}.\n`
-                + `Restart ${PRODUCT_TEXT.commandName} for a running session to load it.\n`;
+            return `${style.green(`Installed ${outcome.source}`)}\n`;
         case "remove":
-            return `${name} removed ${outcome.source} from ${profileRoot}.\n`;
+            return `${style.green(`Removed ${outcome.source}`)}\n`;
         case "update":
-            return outcome.source === null
-                ? `${name} updated the packages in ${profileRoot}.\n`
-                : `${name} updated ${outcome.source}.\n`;
-        case "refresh-models":
-            return `${name} refreshed the model catalogs in ${profileRoot}.\n`;
+            return `${style.green(outcome.source === null ? "Updated packages" : `Updated ${outcome.source}`)}\n`;
         case "list":
-            return renderPackageList(outcome, profileRoot);
+            return renderPackageList(outcome, style);
     }
 }
-function renderPackageList(outcome, profileRoot) {
+function renderPackageList(outcome, style) {
     if (outcome.packages.length === 0)
-        return `${PRODUCT_TEXT.displayName} has no packages installed in ${profileRoot}.\n`;
-    const lines = [`Packages installed for ${PRODUCT_TEXT.commandName} in ${profileRoot}:`];
+        return `${style.dim("No packages installed.")}\n`;
+    const lines = [style.bold("User packages:")];
     for (const entry of outcome.packages) {
-        lines.push(`  ${entry.source}${entry.filtered ? " (partly enabled)" : ""}`);
+        lines.push(`  ${entry.source}${entry.filtered ? " (filtered)" : ""}`);
         if (entry.installedPath !== null)
-            lines.push(`    ${entry.installedPath}`);
+            lines.push(style.dim(`    ${entry.installedPath}`));
     }
     return `${lines.join("\n")}\n`;
 }

package/dist/src/cli/version-stats.js

@@ -21,7 +21,7 @@ export async function runVersionStats(options) {
         return 1;
     }
     const remote = await queryDistTags(runner);
-    output.stdout(`Installed: ${installed}\nRelease:   ${remote.release ?? "unavailable"}\nNext:      ${remote.next ?? "unavailable"}\n`);
+    output.stdout(`Installed: ${installed}\nRelease:   ${remote.release ?? "unavailable"}\nDevelop:   ${remote.develop ?? "unavailable"}\n`);
     if (remote.error)
         output.stderr(`${PRODUCT_TEXT.diagnostic(`could not resolve npm dist-tags: ${remote.error}`)}\n`);
     return 0;
@@ -42,15 +42,15 @@ async function queryDistTags(runner) {
             throw new TypeError("npm returned a non-object dist-tags value");
         const tags = metadata;
         const release = parseVersion(tags.latest, "npm latest");
-        const next = tags.next === undefined ? null : parseVersion(tags.next, "npm next");
-        return { release, next, error: null };
+        const develop = tags.next === undefined ? null : parseVersion(tags.next, "npm development channel");
+        return { release, develop, error: null };
     }
     catch (error) {
         return unavailable(message(error));
     }
 }
 function unavailable(error) {
-    return { release: null, next: null, error };
+    return { release: null, develop: null, error };
 }
 function createVersionProcessRunner() {
     return async (command, arguments_) => await new Promise((resolvePromise, rejectPromise) => {

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

@@ -1476,14 +1476,16 @@ export class PiEngineAdapter {
                 this.#upsertMessageBlock(event.message, "live");
                 return;
             case "message_update": {
-                const block = this.#upsertMessageBlock(event.message, "live");
-                if (block && isRecord(event.assistantMessageEvent) && typeof event.assistantMessageEvent.delta === "string") {
-                    this.#upsertTranscriptBlock({
-                        ...block,
-                        text: block.text.endsWith(event.assistantMessageEvent.delta)
-                            ? block.text
-                            : `${block.text}${event.assistantMessageEvent.delta}`,
-                    });
+                const delta = isRecord(event.assistantMessageEvent) && typeof event.assistantMessageEvent.delta === "string"
+                    ? event.assistantMessageEvent.delta
+                    : undefined;
+                // The delta is folded in before the block is stored, so a chunk is one update to
+                // one block rather than a store without the delta followed by a store with it.
+                const blocks = this.#messageBlocks(event.message, "live", this.#transcript.length);
+                for (const [index, block] of blocks.entries()) {
+                    this.#upsertTranscriptBlock(index === 0 && delta !== undefined && !block.text.endsWith(delta)
+                        ? { ...block, text: `${block.text}${delta}` }
+                        : block);
                 }
                 return;
             }
@@ -1638,7 +1640,13 @@ export class PiEngineAdapter {
                 }
             }
         }
-        this.#setTranscript(blocks);
+        // An authoritative rebuild restates most of what is already there. Reusing the block
+        // that already says it keeps its revision, and with it the rows the shell rendered for
+        // it — otherwise every turn that ends re-renders the whole session.
+        this.#setTranscript(blocks.map(block => {
+            const existing = this.#transcriptBlock(block.id);
+            return existing !== undefined && sameBlockContent(existing, block) ? existing : block;
+        }));
     }
     #upsertMessageBlock(message, status) {
         const blocks = this.#messageBlocks(message, status, this.#transcript.length);
@@ -1815,8 +1823,14 @@ export class PiEngineAdapter {
     }
     #upsertTranscriptBlock(block) {
         const index = this.#transcriptIndex.get(block.id);
-        if (index !== undefined)
+        if (index !== undefined) {
+            const existing = this.#transcript[index];
+            // Nothing to tell the shell about a block that repeats itself, and keeping the
+            // revision keeps the rows it already rendered.
+            if (existing !== undefined && sameBlockContent(existing, block))
+                return;
             this.#transcript[index] = block;
+        }
         else {
             this.#transcriptIndex.set(block.id, this.#transcript.length);
             this.#transcript.push(block);
@@ -2388,6 +2402,36 @@ function compactResourceLabel(path) {
     const segments = path.replaceAll("\\", "/").split("/").filter(Boolean);
     return segments.at(-1) ?? path;
 }
+/**
+ * Whether two blocks say the same thing. A block that says what it already said is not a
+ * new revision: the shell renders a block once per revision, so bumping one it did not
+ * need re-renders it for nothing.
+ */
+function sameBlockContent(left, right) {
+    return left.kind === right.kind
+        && left.status === right.status
+        && left.title === right.title
+        && left.text === right.text
+        && sameValue(left.payload, right.payload);
+}
+function sameValue(left, right) {
+    if (left === right)
+        return true;
+    if (typeof left !== typeof right || left === null || right === null)
+        return false;
+    if (Array.isArray(left) || Array.isArray(right)) {
+        if (!Array.isArray(left) || !Array.isArray(right) || left.length !== right.length)
+            return false;
+        return left.every((value, index) => sameValue(value, right[index]));
+    }
+    if (typeof left !== "object")
+        return false;
+    const leftKeys = Object.keys(left);
+    const rightRecord = right;
+    if (leftKeys.length !== Object.keys(rightRecord).length)
+        return false;
+    return leftKeys.every(key => Object.hasOwn(rightRecord, key) && sameValue(left[key], rightRecord[key]));
+}
 function textFromContent(content) {
     if (typeof content === "string")
         return content;

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

@@ -39,6 +39,12 @@ export declare class OwnedUiSessionShellRoot implements PiTuiComponentPort {
         readonly onDequeue?: () => void;
     }, startup?: PiShellHeaderOptions, agentDir?: string, extensionRenderers?: PiShellExtensionRendererResolver);
     update(view: OwnedUiSessionViewModel): void;
+    /**
+     * Applies one block: its component is created or updated in place and the order grows
+     * only when the block is new. A streamed chunk costs one component update rather than a
+     * walk of the whole transcript.
+     */
+    applyTranscriptBlock(block: OwnedUiSessionViewModel["transcript"][number]): void;
     render(width: number): readonly string[];
     layoutRoot(): PiTuiLayoutNode;
     transcriptComponent(id: string): PiShellTranscriptComponentPort | undefined;

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

@@ -71,6 +71,25 @@ export class OwnedUiSessionShellRoot {
         this.editor.setThinkingLevel(view.thinkingLevel);
         this.invalidate();
     }
+    /**
+     * Applies one block: its component is created or updated in place and the order grows
+     * only when the block is new. A streamed chunk costs one component update rather than a
+     * walk of the whole transcript.
+     */
+    applyTranscriptBlock(block) {
+        this.#blocksById.set(block.id, block);
+        const component = this.#transcript.get(block.id);
+        if (component === undefined) {
+            const created = createPiShellTranscriptComponent(block, this.#cwd, this.#extensionRenderers);
+            created.setExpanded(this.#toolsExpanded);
+            this.#transcript.set(block.id, created);
+            this.#transcriptOrder.push(block.id);
+        }
+        else if (component.revision !== block.revision) {
+            component.update(block);
+        }
+        this.invalidate();
+    }
     render(width) {
         const queued = this.#view.editor.queuedSubmissions.length === 0 ? [] : this.#queued.render(width);
         return [
@@ -794,9 +813,12 @@ export class OwnedUiSessionShell {
         });
         this.root.editor.setAutocompleteCommands(this.backend.workflowAutocompleteCommands());
         this.#unsubscribe = this.backend.onEvent(event => {
-            // 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();
+            // A streamed chunk names one block, and touching only that block is what keeps the
+            // cost of a chunk the same in a long session as in a new one. Everything else
+            // resynchronizes the view, which is cheap next to re-reading the transcript.
+            const view = event.type === "transcript-block" && this.#sessionGeneration === this.backend.sessionGeneration
+                ? this.#syncBlock(event.block)
+                : this.#syncView();
             if (view.lifecycle === "ready" && this.#compactionQueue.length > 0)
                 void this.#flushCompactionQueue();
             if (event.type === "session-lifecycle" && event.lifecycle === "stopped")
@@ -1415,6 +1437,18 @@ export class OwnedUiSessionShell {
         this.#extensionBridge.dispose();
         await this.runtime.dispose();
     }
+    /**
+     * Applies one transcript block without re-reading the session. The listeners still hear
+     * the view they would have heard, so nothing downstream can tell the difference.
+     */
+    #syncBlock(block) {
+        this.root.applyTranscriptBlock(block);
+        this.runtime.requestRender();
+        const view = this.view();
+        for (const listener of this.#listeners)
+            listener(view);
+        return view;
+    }
     #syncView() {
         const view = this.view();
         if (this.backend.sessionGeneration !== this.#sessionGeneration) {

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

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

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

@@ -20,7 +20,7 @@ const UPDATE_DIST_TAGS = { stable: "latest", next: "next" };
  * 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 UPDATE_CHANNEL_LABELS = { stable: "release", next: "develop" };
 const defaultFileSystem = {
     async readFile(path) { return await readFile(path, "utf8"); },
     realpath,
@@ -223,12 +223,13 @@ 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`);
+    const publicChannel = distTag === "next" ? "development" : "release";
+    const lookup = await runNpm(runner, ["view", `${PRODUCT_PACKAGE}@${distTag}`, "version"], true, output, `query the npm ${publicChannel} 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`);
+        output.stderr(`${PRODUCT_TEXT.diagnostic(`received a malformed ${publicChannel} channel version from npm: ${JSON.stringify(lookup.result.stdout.trim())}.`)}\n`);
         return { version: null, exitCode: 1 };
     }
     return { version, exitCode: 0 };
@@ -236,14 +237,10 @@ async function resolveChannelHead(runner, distTag, output) {
 /**
  * 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.
+ * A preview is published as `<version>-dev.<pull-request-number>`, so its decimal
+ * development number is enough to identify it. A full version is accepted too.
+ * The published list remains authoritative: nothing is constructed from the
+ * installed package's base version.
  */
 async function resolveRequestedPreview(runner, requested, output) {
     const lookup = await runNpm(runner, ["view", PRODUCT_PACKAGE, "versions", "--json"], true, output, "list the published versions");
@@ -261,8 +258,7 @@ async function resolveRequestedPreview(runner, requested, output) {
     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.
+        // different command with a different meaning.
         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 };

package/docs/architecture/toolchain.md

@@ -71,7 +71,7 @@ Presentation acceptance is the reader comparing `a1 pi` with pinned Pi. `node sc
 
 ## Publication
 
-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 `-dev.<short commit>` 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.
+One workflow publishes both channels: `.github/workflows/release.yml`. Pushes do not publish. Nightly development verification runs at `03:17 UTC`; `npm run develop` explicitly requests a numbered preview and `npm run release` explicitly requests stable publication after its version pull request merges. A preview is stamped as `-dev.<merged pull-request number>` and uses npm `next` only as an internal dist-tag. New candidates pack once and are validated on Windows, Linux, and macOS; a repeated nightly verifies the exact immutable registry tarball. All publication uses provenance from the `npm-publish` environment, a preview never changes `latest`, and the stable tag, GitHub Release, and `master` are written only after npm has the package. One global non-cancelling concurrency group serializes the final registry check.
 
 `docs/ci-release-runbook.md` is the operational reference.
 

package/docs/ci-release-runbook.md

@@ -5,107 +5,104 @@ GitHub Actions is the only automation platform. Three refs are protected:
 | Ref | Protection | Produced by |
 | --- | --- | --- |
 | `develop` | `Development validation required` on every pull request | `.github/workflows/ci.yml` |
-| `master` | cannot be deleted or force-updated | ruleset only |
-| `refs/tags/v*` | cannot be deleted or moved | ruleset only |
+| `master` | cannot be deleted or force-updated | stable publication |
+| `refs/tags/v*` | cannot be deleted or moved | stable publication |
 
-Publishing is one workflow, `.github/workflows/release.yml`, triggered by pushes
-rather than dispatched by hand.
+`.github/workflows/release.yml` is the only publisher. A push publishes neither
+channel. The workflow starts at `03:17 UTC` for nightly development verification,
+or by explicit dispatch from `npm run develop` or `npm run release`.
 
-`develop` is where work lands. `master` records what the npm `latest` tag serves:
-the release fast-forwards it to the commit it published, and nothing else ever
-writes it. There is no promotion to arrange and nothing to keep in sync — `master`
-is an effect of publishing, not a step before it.
+`develop` is where work lands. `master` records what npm `latest` serves and is an
+effect of stable publication, not a trigger.
 
-## How much validation runs when
+## Validation by trigger
 
-| Change | Validation |
+| Trigger | Validation and outcome |
 | --- | --- |
-| Docs or specs only | OpenSpec strict lint, nothing else |
-| Any code PR into `develop` | Fast tier: typecheck, architecture checks, unit/contract tests |
-| Preview publish (`next`) | Fast tier + package gates on Windows, Linux, and macOS |
-| Stable publish (`latest`) | Complete suite on Windows, Linux, and macOS |
+| Pull request into `develop` | Fast required validation; docs/spec-only changes use strict OpenSpec validation |
+| `npm run develop` | Preview package gates on Windows, Linux, and macOS; an existing numbered preview is an early successful no-op |
+| Nightly at `03:17 UTC` | Complete non-physical suite on Windows, Linux, and macOS, every night |
+| `npm run release -- ...` | Complete exact-byte stable gates, then npm `latest`, tag, GitHub Release, and `master` |
+| `.github/workflows/full-regression.yml` | Additional on-demand complete regression without publication authority |
 
-Need more coverage for something risky? Run the **Full regression** workflow on
-demand.
+## Numbered development previews
 
-## Previews publish themselves
+A merge or push to `develop` does not publish by itself. To request a deliberate
+preview from any authorized checkout:
 
-Every push to `develop` publishes a preview to the npm `next` tag. Nothing to
-dispatch and nothing to approve.
+```sh
+npm run develop
+```
+
+The command fetches authoritative `origin/develop`, resolves the unique merged pull
+request associated with that exact commit through GitHub, and derives
+`<major.minor.patch>-dev.<pull-request number>`. Thus GitHub's `develop (#107)`
+source produces `0.1.8-dev.107`. It first checks npm; if the immutable version
+already exists it reports that version without dispatching package work. Otherwise
+it dispatches GitHub Actions, waits, and reports the published version. It never
+builds or uploads npm bytes from the workstation.
+
+Nightly resolves the same current `origin/develop` source. It always runs complete
+verification even if source has not changed. For a new number it packs once and
+runs the suite against that final-version tarball before publication. For an
+existing number it downloads the exact npm tarball and runs package/update gates
+against those registry bytes; publication is then a successful no-op.
+
+Manual and nightly runs share one non-cancelling concurrency group. Their final
+registry check is serialized, so overlapping requests can produce only one publish
+and one successful existing-version no-op. A development publication moves npm's
+internal `next` dist-tag and never moves `latest`.
+
+Users install previews with public `develop` terminology:
 
-The version is stamped at publish time — `<major.minor.patch>-dev.<short commit>`,
-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. 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.
+```sh
+a1 update:develop       # current development channel
+a1 update:107           # numbered preview
+a1 update:0.1.8-dev.107 # exact full preview version
+```
 
-One consequence worth knowing: a push that would republish an existing version
-fails early, before anything is packed.
+`a1 update:next` is removed and redirects to `a1 update:develop` without registry
+or runtime work.
 
 ## Cutting a stable release
 
-One command, from a clean `develop` that matches its remote:
+From a clean `develop` matching its remote:
 
 ```sh
 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` 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
-declaring a stable version and runs its stable form: build the process guardian on
-all three platforms, pack once, run the complete suite against those exact bytes on
-all three platforms, publish to npm `latest` with provenance from the
-`npm-publish` environment, and only then write the tag `vx.y.z`, record the GitHub
-Release, and fast-forward `master`.
+The command lands `x.y.z` through its version pull request, explicitly dispatches
+stable publication for that exact current `origin/develop` commit, and waits. Only
+after success does it land `x.y.(z+1)-dev`.
 
-That order is the point. A release that fails leaves no tag, no release, and no
-moved branch — only a red run. Nothing ever advertises a version that does not
-exist on the registry.
+Stable publication builds the process guardian on all supported platforms, packs
+once, runs the complete suite against those exact bytes on Windows, Linux, and
+macOS, publishes to npm `latest` with provenance from the `npm-publish`
+environment, and then writes `vx.y.z`, records the GitHub Release, and fast-forwards
+`master`. A push of the stable version does not publish it.
 
 Rules that do not bend:
 
-- **Never upload locally rebuilt bytes.** The publisher uploads the artifact the
-  validation ran against, and re-checks its digest before and after.
-- **Never route around validation by rebuilding inside a publisher.** The publish
-  job has no checkout of dependencies, no build, and no pack step.
-- **Never move a release tag.** A wrong tag is superseded by the next version, not
-  repointed. The tag is written by the publication itself, so it exists only for
-  versions that shipped.
+- **Never upload locally rebuilt bytes.** The publisher uploads the artifact the validation ran against and checks its digest before and after.
+- **Never route around validation by rebuilding inside a publisher.** The publish job receives the packed artifact and does not install dependencies, build, or pack.
+- **Never move a release tag.** A wrong tag is superseded by the next version, not repointed.
 
 ## When something fails
 
-- **PR validation fails:** fix the code and push. Do not mark a failed tier optional.
-- **Preview publish fails:** fix and push again; the next push publishes the next
-  run number. Nothing needs cleaning up.
-- **Stable publish fails:** nothing was recorded — no tag, no release, no moved
-  branch. Fix the cause and release the next version. The failed version number is
-  spent, because `develop` has already moved past it.
-- **Stable publish is uncertain after npm accepted the bytes:** stop. Check the
-  registry for the version, tag, and digest. Repair a dist-tag only as a separate
-  reviewed operation — never republish.
-
-## Why the ruleset looks the way it does
-
-One person maintains this repository, and GitHub does not let a PR author approve
-their own PR. Requiring even one approval would deadlock the authorized
-solo-maintainer path — no PR could ever merge. So the `develop` ruleset requires a
-pull request, a green required check, and resolved review threads, but sets required
-approving reviews to zero. It does not require the branch to be up to date: once a
-PR is green it merges even if unrelated work landed first, with no re-validation
-loop.
-
-The `master` and tag rulesets carry no checks at all. Both only ever receive a commit
-that has already been validated and published, so what matters about them is that
-neither can be rewritten. Requiring a pull request on `master` would stop the release
-from recording itself there.
-
-Do not add a direct-push bypass as a shortcut, and never weaken the force-push or
-deletion protection. Ruleset mutation is a separate administrative operation: run
-`node scripts/check-github-rulesets.mjs` to see the diff, and apply only when a
-maintainer explicitly confirms with `--apply --confirm apply-a1-ci-rulesets`.
+- **PR validation fails:** fix the code and push; do not mark a failed tier optional.
+- **Development publication fails:** fix the cause and rerun `npm run develop`; an npm version that already exists is never overwritten.
+- **Stable publication fails before npm accepts bytes:** no tag, release, or moved branch exists. Fix the cause and release the next version.
+- **Stable publication is uncertain after npm accepted bytes:** stop and inspect registry version, digest, tag, and release. Never republish immutable bytes.
+
+## Branch protection rationale
+
+One person maintains this repository, and a PR author cannot approve their own PR.
+The `develop` ruleset therefore requires a pull request, a green required check,
+and resolved review threads, but zero approving reviews. `master` and release tags
+are written only after publication and are protected from force-push, movement, and
+deletion.
+
+Do not add direct-push bypasses. Ruleset mutation remains a separate administrative
+operation: inspect with `node scripts/check-github-rulesets.mjs`, and apply only
+with explicit maintainer confirmation.

package/docs/features/launch-profiles.md

@@ -8,7 +8,7 @@
 | `a1 pi` | Untouched vanilla Pi fallback and comparison oracle | ordinary `~/.pi/agent` |
 | `a1 sandbox` | Unchanged isolated vanilla Pi profile for experiments | `~/.a1/sandbox` |
 
-`a1 pi` and `a1 sandbox` are development instruments: one compares A1 against pinned Pi, the other tries resources against an isolated profile. Prerelease builds — what `a1 update:next` installs — expose them. A release build does not, and does not recognize the words: what it exposes is bare `a1` plus the maintenance and package commands. Working in this repository is unaffected, because `npm start:pi` and `npm run start:sandbox` prepare the profile and launch directly rather than through the command line.
+`a1 pi` and `a1 sandbox` are development instruments: one compares A1 against pinned Pi, the other tries resources against an isolated profile. Prerelease builds — what `a1 update:develop` or `a1 update:<number>` installs — expose them. A release build does not, and does not recognize the words: what it exposes is bare `a1` plus the maintenance and package commands. Working in this repository is unaffected, because `npm start:pi` and `npm run start:sandbox` prepare the profile and launch directly rather than through the command line.
 
 There is no `a1 agent` command. The former `a1 ui` subcommand is removed. Bare `a1` is the owned agent product surface and remains the entry point when multi-agent UX is introduced.
 

package/docs/manual-transparent-checkpoint.md

@@ -50,4 +50,4 @@ Report failures with direct-versus-A1 behavior, platform/terminal versions, exac
 
 For recovery, use `a1 pi`; do not use the removed `a1 ui` command. `a1 sandbox` remains profile isolation rather than a security boundary.
 
-Manual acceptance can authorize an exact uncertified npm `next` preview after non-desktop gates pass. It does not certify stable terminal parity or platform support.
+Manual acceptance can authorize an exact uncertified development preview after non-desktop gates pass. It does not certify stable terminal parity or platform support.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timurproko/a1",
-  "version": "0.1.8-dev.0b6d8cc",
+  "version": "0.1.8-dev.112",
   "description": "Standalone terminal workspace for supervised native and managed agents",
   "type": "module",
   "packageManager": "npm@11.13.0",
@@ -33,6 +33,7 @@
     "check:deprecated": "node scripts/check-deprecated-dependencies.mjs",
     "branches:prune": "node scripts/prune-merged-branches.mjs",
     "check": "npm run test:fast",
+    "develop": "node scripts/develop.mjs",
     "release": "node scripts/release.mjs",
     "test": "npm run test:fast",
     "test:fast": "node scripts/run-validation-tier.mjs typecheck fast",
@@ -57,6 +58,7 @@
   "dependencies": {
     "@earendil-works/pi-coding-agent": "0.84.2",
     "@earendil-works/pi-tui": "0.84.2",
+    "chalk": "5.6.2",
     "cross-spawn": "7.0.6",
     "grok-mermaid": "0.2.2",
     "semver": "7.8.5"