@timurproko/a1 0.1.8-dev.151 → 0.1.8-dev.157

package/README.md

@@ -23,20 +23,28 @@ npm install -g @timurproko/a1@0.1.8-dev.107
 ## Use
 
 ```sh
-a1                      # launch A1 (profile: ~/.a1/agent)
-a1 version              # show Current, Develop, and Release versions
-a1 update               # install the newest stable release
-a1 update:develop       # install the current development preview
-a1 update:107           # install numbered preview 107
-a1 update --models      # refresh A1's model catalogs
+a1                                      # launch A1 (profile: ~/.a1/agent)
+a1 --help                               # show all commands (short form: a1 -h)
+a1 --version                            # show the version (short form: a1 -v)
+a1 update                               # install the newest stable release
+a1 update --develop                     # install the current development preview
+a1 update --develop 107                 # install numbered preview 107
+a1 update --develop 0.1.8-dev.107       # install that exact preview
+a1 update --models                      # refresh A1's model catalogs
 ```
 
+Stable builds print only their installed version. Development builds also show the
+current development and stable channel versions.
+
 Development previews add the Pi comparison profile; release builds do not carry it.
 
 ```sh
-a1 pi           # vanilla Pi oracle: ~/.pi/agent
+a1 pi                                   # vanilla Pi oracle: ~/.pi/agent
 ```
 
+Unsupported commands exit quietly without launching anything. The removed
+`update:<preview>` forms are not aliases; use `update --develop`.
+
 ## Extensions
 
 Pi extension packages install into A1's own profile (`~/.a1/agent`), so bare `a1`
@@ -49,8 +57,12 @@ a1 pi remove npm:pi-mcp-adapter    # remove it (alias: a1 pi uninstall)
 a1 pi list                         # list installed packages
 a1 pi update --extensions          # update every installed package
 a1 pi update npm:pi-mcp-adapter    # update one
+a1 pi update --models              # refresh A1's model catalogs
 ```
 
+A1 pins the Pi runtime carried by each release, so Pi self-update forms are refused.
+Update A1 itself with `a1 update` or `a1 update --develop`.
+
 A running session picks up a newly installed package after a restart.
 Configuration is isolated the same way: bare `a1` reads `~/.a1/agent` (or the
 project), never `~/.pi/agent`. Configure MCP with `/mcp setup` inside bare `a1`.
@@ -88,8 +100,8 @@ npm run develop             # request the preview publish run and wait for it
 Install:
 
 ```sh
-a1 update:107               # install preview 107
-a1 update:0.1.8-dev.107     # install that exact full preview version
+a1 update --develop 107                 # install preview 107
+a1 update --develop 0.1.8-dev.107       # install that exact full preview version
 ```
 
 ### Stable

package/bin/cli.js

@@ -45,5 +45,6 @@ process.exitCode = await dispatchCli(process.argv.slice(2), {
     return await runPackageCommand(request, { createPort: createPiPackagesPort });
   },
 }, {
+  stdout: message => process.stdout.write(message),
   stderr: message => process.stderr.write(message),
 }, capabilities);

package/dist/cli/dispatch.d.ts

@@ -9,11 +9,17 @@ export interface CliHandlers {
     readonly packages: (request: PackageCommandRequest) => Promise<number>;
 }
 export interface CliOutput {
+    readonly stdout: (message: string) => void;
     readonly stderr: (message: string) => void;
 }
 export declare function cliUsage(capabilities: CliCapabilities): string;
+export declare function cliHelp(capabilities: CliCapabilities): string;
 export declare function dispatchCli(arguments_: readonly string[], handlers: CliHandlers, output: CliOutput, capabilities: CliCapabilities): Promise<number>;
 export type CliCommand = {
+    readonly kind: "noop";
+} | {
+    readonly kind: "help";
+} | {
     readonly kind: "launch";
     readonly profileId: LaunchProfileId;
 } | {

package/dist/cli/dispatch.js

@@ -4,21 +4,60 @@ export function cliUsage(capabilities) {
     return PRODUCT_TEXT.usage([
         "",
         ...(capabilities.developmentComparison ? ["pi"] : []),
-        "version",
-        "update [self|--models]",
-        "update:develop",
-        "update:<number>",
+        "--help",
+        "-h",
+        "--version",
+        "-v",
+        "update",
+        "update --develop [preview-or-version]",
+        "update --models",
         "pi install <source>",
         "pi remove <source>",
+        "pi uninstall <source>",
         "pi list",
-        "pi update [--extensions|<source>]",
+        "pi update --extensions",
+        "pi update --models",
+        "pi update <source>",
     ]);
 }
+export function cliHelp(capabilities) {
+    const command = PRODUCT_TEXT.commandName;
+    return [
+        "Common:",
+        `  ${command}`,
+        ...(capabilities.developmentComparison ? [`  ${command} pi`] : []),
+        `  ${command} --help`,
+        `  ${command} -h`,
+        `  ${command} --version`,
+        `  ${command} -v`,
+        "",
+        "Update:",
+        `  ${command} update`,
+        `  ${command} update --develop [preview-or-version]`,
+        `  ${command} update --models`,
+        "",
+        "Pi-compatible packages:",
+        `  ${command} pi install <source>`,
+        `  ${command} pi remove <source>`,
+        `  ${command} pi uninstall <source>`,
+        `  ${command} pi list`,
+        `  ${command} pi update --extensions`,
+        `  ${command} pi update --models`,
+        `  ${command} pi update <source>`,
+        "",
+    ].join("\n");
+}
 const PROFILE_WORDS = new Set(["pi"]);
 export async function dispatchCli(arguments_, handlers, output, capabilities) {
     const command = parseCliCommand(arguments_, capabilities);
+    if (command.kind === "noop")
+        return 0;
+    if (command.kind === "help") {
+        output.stdout(cliHelp(capabilities));
+        return 0;
+    }
     if (command.kind === "error") {
-        output.stderr(`${command.message}\n${cliUsage(capabilities)}\n`);
+        output.stderr(`${command.message}\n`);
         return 2;
     }
     if (command.kind === "launch")
@@ -33,76 +72,63 @@ export function parseCliCommand(arguments_, capabilities) {
     if (arguments_.length === 0)
         return { kind: "launch", profileId: "a1" };
     const [command, ...rest] = arguments_;
+    if (command === "--help" || command === "-h")
+        return withoutArguments(rest, { kind: "help" });
+    if (command === "--version" || command === "-v")
+        return withoutArguments(rest, { kind: "version" });
     if (command === "pi") {
         if (rest.length > 0)
             return parsePiPackageCommand(rest);
-        if (capabilities.developmentComparison)
-            return { kind: "launch", profileId: "pi" };
+        return capabilities.developmentComparison ? { kind: "launch", profileId: "pi" } : { kind: "noop" };
     }
-    if (command === "version")
-        return withoutArguments(rest, { kind: "version" });
-    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" || command === "list") {
-        return packageNamespaceRejection(command, rest.join(" ") || undefined);
-    }
-    if (command === "ui")
-        return { kind: "error", message: `The ui subcommand was removed; run bare ${PRODUCT_TEXT.commandName} for the owned UI.` };
-    if (command === "agent")
-        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 ?? ""}`) };
+    if (command?.startsWith("update:"))
+        return { kind: "noop" };
+    // Unsupported and reserved command spaces are deliberately quiet. Help is
+    // explicit, and a typo must never start an interactive or maintenance path.
+    return { kind: "noop" };
 }
 /**
- * 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") {
-        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: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 };
-}
-/**
- * Top-level `update` owns A1 itself and A1's model catalogs. Extension package
- * maintenance lives under the `pi` compatibility namespace, while updating the
- * pinned Pi runtime remains impossible.
+ * Stable update is the empty form. `--develop` selects the moving development
+ * head or one immutable numbered preview, while model refresh remains a separate
+ * operation that cannot be combined with either update channel.
  */
 function parseUpdate(rest) {
     if (rest.length === 0)
         return { kind: "update", channel: "stable" };
-    if (rest.length > 1)
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic("update accepts one target.") };
-    const [target] = rest;
-    if (target === "self")
-        return { kind: "update", channel: "stable" };
-    if (target === "pi") {
-        return {
-            kind: "error",
-            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 === "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}.`) };
+    const [selector, ...values] = rest;
+    // Removed compatibility notation is unsupported rather than deprecated.
+    if (selector === "self")
+        return { kind: "noop" };
+    if (selector === "--develop") {
+        if (values.length === 0)
+            return { kind: "update", channel: "next" };
+        if (values.length > 1)
+            return updateGrammarError("--develop accepts at most one preview number or version.");
+        const [target] = values;
+        if (target === undefined || !isDevelopmentTarget(target)) {
+            return updateGrammarError(`--develop received an unusable preview: ${target ?? ""}`);
+        }
+        return { kind: "update", channel: "next", target };
     }
-    if (target === "--models")
+    if (selector === "--models") {
+        if (values.length > 0)
+            return updateGrammarError("--models cannot be combined with another update selector.");
         return { kind: "packages", request: { verb: "refresh-models", source: null } };
-    if (target === "--extensions" || (target !== undefined && !target.startsWith("-"))) {
-        return packageNamespaceRejection("update", target === "--extensions" ? "--extensions" : target);
     }
-    return unknownOption(target ?? "", "update");
+    if (selector === "pi")
+        return pinnedPiUpdateError();
+    if (selector !== undefined && selector.startsWith("-"))
+        return unknownOption(selector, "update");
+    // Positional update targets are reserved for a future A1-native plugin model.
+    return { kind: "noop" };
+}
+function isDevelopmentTarget(target) {
+    return /^[1-9]\d*$/.test(target) || /^\d+\.\d+\.\d+-dev\.[1-9]\d*$/.test(target);
+}
+function updateGrammarError(detail) {
+    return { kind: "error", message: PRODUCT_TEXT.diagnostic(`could not parse update: ${detail}`) };
 }
 function parsePiPackageCommand(arguments_) {
     const [verb, ...rest] = arguments_;
@@ -113,30 +139,40 @@ function parsePiPackageCommand(arguments_) {
         return withoutArguments(rest, { kind: "packages", request: { verb: "list", source: null } });
     if (verb === "update")
         return parsePiPackageUpdate(rest);
-    return { kind: "error", message: PRODUCT_TEXT.diagnostic(`received an unknown pi package command: ${verb ?? ""}`) };
+    return { kind: "noop" };
 }
 function parsePiPackageUpdate(rest) {
-    if (rest.length === 0) {
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`pi update needs --extensions or a package source.`) };
-    }
+    if (rest.length === 0)
+        return pinnedPiUpdateError();
     if (rest.length > 1)
         return { kind: "error", message: PRODUCT_TEXT.diagnostic("pi update accepts one target.") };
     const [target] = rest;
     if (target === "--extensions")
         return { kind: "packages", request: { verb: "update", source: null } };
-    if (target === "--models") {
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`refreshes its model catalogs at the top level; run ${PRODUCT_TEXT.commandName} update --models.`) };
-    }
+    if (target === "--models")
+        return { kind: "packages", request: { verb: "refresh-models", source: null } };
+    if (target === "--self" || target === "--all" || target === "self" || target === "pi")
+        return pinnedPiUpdateError();
     if (target === undefined || target.startsWith("-"))
         return unknownOption(target ?? "", "pi update");
-    if (PROFILE_WORDS.has(target))
-        return profileRejection("update");
     return { kind: "packages", request: { verb: "update", source: target } };
 }
+function pinnedPiUpdateError() {
+    return {
+        kind: "error",
+        message: [
+            PRODUCT_TEXT.diagnostic("pins its certified Pi runtime and cannot update it independently."),
+            "Use:",
+            `  ${PRODUCT_TEXT.commandName} update                    Update A1`,
+            `  ${PRODUCT_TEXT.commandName} pi update --extensions    Update Pi-compatible packages`,
+            `  ${PRODUCT_TEXT.commandName} pi update --models        Refresh model catalogs`,
+        ].join("\n"),
+    };
+}
 function parseSourceCommand(verb, rest) {
     const flag = rest.find(argument => argument.startsWith("-"));
     if (flag !== undefined)
-        return unknownOption(flag, verb);
+        return unknownOption(flag, `pi ${verb}`);
     if (rest.length === 0)
         return { kind: "error", message: PRODUCT_TEXT.diagnostic(`${verb} requires a package source.`) };
     if (rest.length > 1)
@@ -151,18 +187,8 @@ function parseSourceCommand(verb, rest) {
 function withoutArguments(rest, command) {
     if (rest.length === 0)
         return command;
-    const [argument] = rest;
-    if (argument !== undefined && (PROFILE_WORDS.has(argument) || argument.startsWith("--profile")))
-        return profileRejection("list");
     return { kind: "error", message: PRODUCT_TEXT.diagnostic("commands do not accept additional arguments.") };
 }
-function packageNamespaceRejection(verb, target) {
-    const suffix = target === undefined ? "" : ` ${target}`;
-    return {
-        kind: "error",
-        message: PRODUCT_TEXT.diagnostic(`manages extension packages under its pi namespace; run ${PRODUCT_TEXT.commandName} pi ${verb}${suffix}.`),
-    };
-}
 function profileRejection(verb) {
     return {
         kind: "error",

package/dist/cli/version-stats.js

@@ -2,7 +2,7 @@ import { spawn } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import crossSpawn from "cross-spawn";
-import { valid as validSemver } from "semver";
+import { prerelease, valid as validSemver } from "semver";
 import { PRODUCT_TEXT } from "../product-identity.js";
 const defaultOutput = {
     stdout(message) { process.stdout.write(message); },
@@ -20,6 +20,12 @@ export async function runVersionStats(options) {
         output.stderr(`${PRODUCT_TEXT.diagnostic(`could not read its installed version: ${message(error)}`)}\n`);
         return 1;
     }
+    // Match Pi's release behavior: stable builds print only their installed version.
+    // Development builds retain channel visibility for preview comparison and updates.
+    if (prerelease(installed) === null) {
+        output.stdout(`${installed}\n`);
+        return 0;
+    }
     const remote = await queryDistTags(runner, options.fetcher ?? defaultRegistryFetcher);
     output.stdout(`Current: ${installed}\nDevelop: ${remote.develop ?? "unavailable"}\nRelease: ${remote.release ?? "unavailable"}\n`);
     if (remote.error)

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

@@ -5,7 +5,7 @@
   "platform": "darwin",
   "architecture": "arm64",
   "capability": "unsupported",
-  "builtAt": "2026-08-28T10:16:08.776Z",
+  "builtAt": "2026-08-28T12:29:51.254Z",
   "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-28T10:16:08.593Z",
+  "builtAt": "2026-08-28T12:30:02.835Z",
   "artifact": {
     "filename": "process-guardian",
     "sha256": "ee8a00eaaf79c707459bbbfb52518e9739314967049fbe5fa625f36ce33db9ee",

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

@@ -5,10 +5,10 @@
   "platform": "win32",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-08-28T10:16:41.229Z",
+  "builtAt": "2026-08-28T12:30:44.840Z",
   "artifact": {
     "filename": "process-guardian.exe",
-    "sha256": "8daa77c737ea8f96eb022fce63a25a4fce3e5d15c409201712a7f36853c8e8e4",
+    "sha256": "ba7b712f918bc77cdf847bcb7b2473ded2aaf10b057bd12360ac3fa654b5f36c",
     "size": 177664
   },
   "provenance": {

package/dist/ui/components/text.js

@@ -7,6 +7,15 @@
 const ANSI_PATTERN = /\[[0-9;:?]*[ -/]*[@-~]|\][^]*(?:|\\)|[@-Z\\-_]/g;
 const SEGMENTER = new Intl.Segmenter(undefined, { granularity: "grapheme" });
 const WORD_SEGMENTER = new Intl.Segmenter(undefined, { granularity: "word" });
+/**
+ * Recommended-for-general-interchange emoji. Terminals give every one of these
+ * two columns wherever its code points sit, so the wide blocks in
+ * `codePointWidth` cannot carry the measurement alone: a lone U+26A1 or any
+ * U+FE0F presentation sequence escapes them and would measure one column short.
+ */
+const RGI_EMOJI_PATTERN = /^\p{RGI_Emoji}$/v;
+/** Columns a terminal advances for a tab, matching the host runtime. */
+const TAB_WIDTH = 3;
 /** Removes styling sequences so only visible characters remain. */
 export function stripAnsi(text) {
     return text.replace(ANSI_PATTERN, "");
@@ -50,13 +59,26 @@ function codePointWidth(codePoint) {
         return 2;
     if (codePoint >= 0x20000 && codePoint <= 0x3fffd)
         return 2;
-    // Control characters occupy nothing.
+    // A tab advances to the host runtime's stop; other control characters occupy nothing.
+    if (codePoint === 0x09)
+        return TAB_WIDTH;
     if (codePoint < 0x20 || (codePoint >= 0x7f && codePoint < 0xa0))
         return 0;
     return 1;
 }
-/** Width of one grapheme cluster: the widest code point it contains, marks excluded. */
+/** Cheap pre-filter: only clusters that could be emoji pay for the RGI test. */
+function couldBeEmoji(grapheme) {
+    const codePoint = grapheme.codePointAt(0) ?? 0;
+    return ((codePoint >= 0x1f000 && codePoint <= 0x1fbff) ||
+        (codePoint >= 0x2300 && codePoint <= 0x23ff) ||
+        (codePoint >= 0x2600 && codePoint <= 0x27bf) ||
+        (codePoint >= 0x2b00 && codePoint <= 0x2bff) ||
+        grapheme.length > 1);
+}
+/** Width of one grapheme cluster: two for emoji, else the widest code point it contains. */
 function graphemeWidth(grapheme) {
+    if (couldBeEmoji(grapheme) && RGI_EMOJI_PATTERN.test(grapheme))
+        return 2;
     let width = 0;
     for (const character of grapheme) {
         width = Math.max(width, codePointWidth(character.codePointAt(0) ?? 0));

package/docs/ci-release-runbook.md

@@ -56,13 +56,14 @@ internal `next` dist-tag and never moves `latest`.
 Users install previews with public `develop` terminology:
 
 ```sh
-a1 update:develop       # current development channel
-a1 update:107           # numbered preview
-a1 update:0.1.8-dev.107 # exact full preview version
+a1 update --develop                     # current development channel
+a1 update --develop 107                 # numbered preview
+a1 update --develop 0.1.8-dev.107       # exact full preview version
 ```
 
-`a1 update:next` is removed and redirects to `a1 update:develop` without registry
-or runtime work.
+The former `a1 update:<selector>` commands are removed without compatibility
+aliases or redirects. Unsupported forms exit quietly without registry or runtime
+work.
 
 ## Cutting a stable release
 

package/docs/features/launch-profiles.md

@@ -7,9 +7,9 @@
 | `a1` | A1-owned Pi-compatible UI | `~/.a1/agent` |
 | `a1 pi` | Pi-compatible comparison surface using the ordinary Pi profile | ordinary `~/.pi/agent` |
 
-`a1 pi` is a development instrument for comparing A1 against pinned Pi. Prerelease builds — what `a1 update:develop` or `a1 update:<number>` installs — expose it. A release build does not recognize the launch form. Repository development can run the comparison directly with `npm start:pi`.
+`a1 pi` is a development instrument for comparing A1 against pinned Pi. Prerelease builds — what `a1 update --develop` or `a1 update --develop <number>` installs — expose it. A release build does not recognize the launch form. Repository development can run the comparison directly with `npm start:pi`.
 
-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.
+There is no `a1 agent` command. The former `a1 ui` subcommand is removed. Unsupported commands return quietly without selecting another runtime. Bare `a1` is the owned agent product surface and remains the entry point when multi-agent UX is introduced.
 
 ## First launch
 
@@ -46,4 +46,4 @@ Normal root exit, terminal closure, guardian failure, and verified update shutdo
 
 ## Recovery and comparison
 
-If bare `a1` cannot start or a UI workflow diverges, run `a1 pi` from the same working directory and compare the behavior. Profile data is intentionally separate, so authentication or settings may need to be configured independently. Use `a1 version` to record the installed A1 release before reporting a difference.
+If bare `a1` cannot start or a UI workflow diverges, run `a1 pi` from the same working directory and compare the behavior. Profile data is intentionally separate, so authentication or settings may need to be configured independently. Use `a1 --version` to record the installed A1 release before reporting a difference.

package/package.json

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