@timurproko/a1 0.1.1-dev.8 → 0.1.4

package/README.md

@@ -1,106 +1,104 @@
 # A1
 
-A1 is a terminal-native agent launcher for Windows, Linux, and macOS. Bare `a1` runs the A1-owned Pi-compatible UI, while explicit fallback profiles can launch untouched Pi directly. A1 also manages release selection, process ownership, and updates.
-
 ## Install
 
-Requirements:
-
-- Node.js 22.19 through 24.x
-- npm 11
-
-Published packages include the integrity-verified process guardian for supported platforms. Building A1 from source additionally requires Rust/Cargo 1.85 or newer.
-
 ```sh
 npm install --global @timurproko/a1@latest
 ```
 
-The package installs only the `a1` command.
-
 ## Commands
 
 ```sh
 a1              # A1-owned UI and profile: ~/.a1/agent
-a1 pi           # untouched vanilla Pi oracle: ~/.pi/agent
-a1 sandbox      # unchanged isolated vanilla Pi profile: ~/.a1/sandbox
 a1 version      # show Installed, Release (latest), and Next versions
 a1 update       # update to npm latest
 a1 update:next  # update to npm next
 ```
 
-Bare `a1` owns its Pi-compatible TUI composition and uses the public Pi engine, components, and terminal APIs. It does not insert a PTY or terminal-byte relay. Default visuals and workflows track the pinned vanilla Pi baseline; A1-specific visual customization and structured tabs remain disabled.
-
-`a1 pi` is the untouched upstream fallback and comparison oracle. Use it to distinguish A1-owned UI problems from upstream Pi, profile, provider, or terminal problems. The `a1 ui` subcommand was removed and is not a compatibility alias; run bare `a1` for the owned UI.
+Prerelease builds — what `a1 update:next` installs — add two development profiles
+for comparing against pinned Pi and for experimenting against an isolated profile.
+A release build does not carry them.
 
-`a1 sandbox` is unchanged: it launches vanilla Pi with isolated Pi configuration and resources. “Sandbox” does not mean operating-system, filesystem, process, network, or credential security isolation. See [`docs/features/launch-profiles.md`](docs/features/launch-profiles.md) for first-run directories, independent `/login`, trust behavior, extension placement, and recovery.
+```sh
+a1 pi           # untouched vanilla Pi oracle: ~/.pi/agent
+a1 sandbox      # unchanged isolated vanilla Pi profile: ~/.a1/sandbox
+```
 
-Every interactive command creates an independent, non-detachable launch instance. Any number of `a1`, `a1 pi`, and `a1 sandbox` commands may run in separate terminals at the same time. Closing one command closes only its owned UI/Pi process and all agents, extensions, tools, daemons, and descendants created by that invocation; it never requires finding PIDs, deleting control state, or restarting the supervisor. The idle supervisor may remain available for release coordination after all interactive instances close, but it owns no surviving instance runtime.
+## Extensions
 
-## Develop
+Pi extension packages install into A1's own profile, so bare `a1` loads them and
+`a1 pi` and `a1 sandbox` do not. Sources are Pi's: `npm:`, git, or a local path.
 
 ```sh
-npm ci
-npm run build
-npm start
+a1 install npm:pi-mcp-adapter   # install a package into ~/.a1/agent
+a1 remove npm:pi-mcp-adapter    # remove it again (alias: a1 uninstall)
+a1 list                         # list packages installed for a1
+a1 update --extensions          # update every installed package
+a1 update npm:pi-mcp-adapter    # update one of them
+a1 update --models              # refresh model catalogs
 ```
 
-`npm start` gives each invocation isolated A1 development state and an isolated development Pi profile. Use `npm start -- --print-environment` to inspect the selected paths without launching the UI.
-
-A1 control state uses `%APPDATA%\\A1` and `%LOCALAPPDATA%\\A1` on Windows, and the `a1` directory under XDG config/data/runtime roots on Unix. Override it only with declared `A1_*` variables such as `A1_CONFIG_DIR`, `A1_DATA_DIR`, `A1_RUNTIME_DIR`, `A1_DATABASE_PATH`, and `A1_ENDPOINT`. Pi profile roots remain `~/.a1/agent`, `~/.pi/agent`, and `~/.a1/sandbox`. This is a no-migration identity hard cut; see [`docs/architecture/toolchain.md`](docs/architecture/toolchain.md#identity-hard-cut-and-cleanup) before removing obsolete control state.
+A running session loads a newly installed package after a restart. Pi's own
+profile at `~/.pi/agent` is managed by Pi itself.
 
-### Worktree lifecycle
-
-The primary worktree stays on `develop` and is integration-only. Each task uses a detached worktree under the repository's ignored `.worktrees/` directory, based on current `origin/develop` unless another base is selected.
+## Develop
 
 ```sh
-git fetch origin --prune
-git worktree add --detach .worktrees/<task-id> origin/develop
-cd .worktrees/<task-id>
+npm ci                  # install exact locked dependencies
+npm run build           # compile TypeScript and the process guardian into dist
+npm start               # build and launch an isolated development `a1`
+npm run start:pi        # build and launch an isolated development `a1 pi`
+npm run start:sandbox   # build and launch an isolated development `a1 sandbox`
+npm run test:fast       # typecheck + fast suite, no build needed
+npm test                # same as test:fast
+npm run test:full       # complete non-physical suite
 ```
 
-Commit and validate coherent work there. Because `develop` is protected, push the detached commit to one temporary remote branch and merge one pull request for the requested change. After merge, update the primary worktree and remove the task worktree only when its commits are reachable from `develop`:
+## Release
 
-```sh
-git push origin HEAD:refs/heads/<task-id>
-gh pr create --base develop --head <task-id>
-# After the pull request is merged:
-cd <repository-root>
-git fetch origin --prune
-git merge --ff-only origin/develop
-git worktree remove .worktrees/<task-id>
-git worktree prune
-```
+Two channels, both published by CI from the exact bytes it validated. Nothing is
+ever published from a workstation.
 
-Manual acceptance does not leave a permanent validation checkout. Once acceptance is recorded, archive the completed OpenSpec change, integrate the archive commit into `develop`, then remove and prune every task or acceptance worktree retained for that change. Never remove a worktree before all of its implementation, acceptance, and archive commits are reachable from `develop`.
+### Previews — npm `next`
 
-Local package archives and ad hoc test builds belong under `.builds/`, never in the repository root. For manual package tests, use:
+Automatic. Every push to `develop` publishes one, versioned
+`<major.minor.patch>-dev.<run number>` from whatever `package.json` declares. The
+preview version is stamped at publish time and never committed, so previews cost no
+commits and need no command.
 
 ```sh
-mkdir -p .builds
-npm pack --ignore-scripts --pack-destination .builds
+a1 update:next   # install the newest preview
 ```
 
-Run the non-desktop gates with:
+### Stable — npm `latest`
+
+One command, from a clean `develop` that matches its remote:
 
 ```sh
-npm run typecheck
-npm run check:architecture
-npm run check:deprecated
-npm test
-npm run test:release
+npm run release -- patch     # 0.1.1        -> 0.1.2
+npm run release -- minor     # 0.1.1        -> 0.2.0
+npm run release -- major     # 0.1.1        -> 1.0.0
+npm run release -- 0.4.0     # an exact version
 ```
 
-Automated physical-terminal interaction must never run on an active workstation. Future physical certification may run only on dedicated disposable workers or VMs with exclusive test desktops.
-
-## Releases
+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
+immediately.
 
-An exact manually accepted `-dev.N` candidate may publish under npm tag `next` after applicable non-desktop gates pass. Such a preview is explicitly uncertified, cannot move `latest`, and cannot claim stable terminal parity or platform support. Stable claims require deferred physical and cross-platform certification against the exact package.
+```sh
+a1 update        # install the newest stable release
+```
 
-Trusted preview publication uses `.github/workflows/publish-next.yml` and npm provenance. Local release mechanics are documented in [`docs/architecture/toolchain.md`](docs/architecture/toolchain.md).
+After a stable publish, `master` fast-forwards to the released commit, so `master`
+always points at what npm `latest` serves while `develop` carries the work.
 
-## Architecture
+A release that fails leaves nothing behind: no tag, no GitHub Release, no moved
+branch. Every version you can see somewhere is a version the registry actually
+serves. Release tags are protected from deletion and movement; a wrong tag is
+superseded by the next version, never repointed.
 
-- [`docs/architecture/boundaries.md`](docs/architecture/boundaries.md)
-- [`docs/architecture/toolchain.md`](docs/architecture/toolchain.md)
-- [`docs/manual-transparent-checkpoint.md`](docs/manual-transparent-checkpoint.md)
-- [`docs/features/launch-profiles.md`](docs/features/launch-profiles.md)
+`docs/ci-release-runbook.md` has the full picture, including what happens when a
+publish fails partway.

package/bin/cli.js

@@ -2,7 +2,12 @@
 
 const packageRoot = new URL("..", import.meta.url);
 const { fileURLToPath } = await import("node:url");
-const { dispatchCli } = await import("../dist/src/cli/index.js");
+const { readFile } = await import("node:fs/promises");
+const { cliCapabilities, dispatchCli } = await import("../dist/src/cli/index.js");
+
+// Which commands this build exposes follows from the build's own version, so a
+// released a1 cannot be argued into offering the development profiles.
+const capabilities = cliCapabilities(JSON.parse(await readFile(new URL("package.json", packageRoot), "utf8")).version);
 
 process.exitCode = await dispatchCli(process.argv.slice(2), {
   launch: async intent => {
@@ -21,6 +26,13 @@ process.exitCode = await dispatchCli(process.argv.slice(2), {
     const { runSelfUpdate } = await import("../dist/src/foundation/release/index.js");
     return await runSelfUpdate({ packageRoot: fileURLToPath(packageRoot), channel });
   },
+  packages: async request => {
+    const [{ runPackageCommand }, { createPiPackagesPort }] = await Promise.all([
+      import("../dist/src/cli/index.js"),
+      import("../dist/src/foundation/pi-engine-adapter/index.js"),
+    ]);
+    return await runPackageCommand(request, { createPort: createPiPackagesPort });
+  },
 }, {
   stderr: message => process.stderr.write(message),
-});
+}, capabilities);

package/bin/module-identity.js

@@ -0,0 +1,132 @@
+/**
+ * One pi-tui module identity per process.
+ *
+ * npm materializes @earendil-works/pi-tui twice under A1's package root: once
+ * as A1's direct dependency at the node_modules root, and once nested inside
+ * @earendil-works/pi-coding-agent, whose published npm-shrinkwrap.json makes
+ * npm build its dependency tree exactly as shrinkwrapped instead of sharing a
+ * hoisted copy. Both are the same version; npm just cannot tell them apart.
+ *
+ * Two copies means two of every TUI class. Pinned Pi hands extensions the
+ * nested copy — its extension loader aliases the specifier to whatever it
+ * resolves from its own directory — so an extension's `instanceof` check and
+ * its prototype patches land on classes A1's renderer never uses. Extension
+ * chrome silently disappears and routed input dead-ends, with no error.
+ *
+ * A1 therefore does not import the specifier at all. Its package declares the
+ * subpath import `#pi-tui`, resolving to pinned Pi's copy first and to the
+ * hoisted one only when that is absent — which is exactly the case where there
+ * is one copy and both sides agree anyway. Every A1 module imports `#pi-tui`,
+ * so which copy A1 uses is stated in package.json and enforced by Node at
+ * resolution, rather than arranged by rewriting an installed tree.
+ *
+ * What remains here is the check that it worked. The alias names one path
+ * inside pinned Pi; if a future layout moved that copy, resolution would fall
+ * back to A1's own and the split would return — silently, which is what made
+ * this expensive the first time. So launch compares the two resolutions and
+ * says so when they differ, loudly and once, instead of leaving a user to
+ * discover it as missing extension UI.
+ *
+ * This lives in bin/ (shipped, plain JS) because it inspects dependency
+ * resolution, which the Pi API boundary policy rightly forbids ordinary
+ * production code from touching.
+ */
+import { createRequire } from "node:module";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+/**
+ * What A1's own modules resolve `#pi-tui` to, as a real path.
+ *
+ * The alias is read from the manifest and its entries tried in order, which is
+ * what Node does for a subpath import: a relative target is a file within the
+ * package, and a bare one goes through ordinary resolution. Asking Node
+ * directly is not an option here — `import.meta.resolve` ignores the parent it
+ * is given unless an experimental flag is set, so it would always answer for
+ * the running process rather than for the installation being inspected.
+ */
+function resolveOwnPiTui(packageRoot) {
+  const manifest = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+  const alias = manifest.imports?.["#pi-tui"];
+  const targets = Array.isArray(alias) ? alias : alias === undefined ? [] : [alias];
+  if (targets.length === 0) throw new Error("package.json declares no #pi-tui alias");
+  for (const target of targets) {
+    if (typeof target !== "string") continue;
+    if (target.startsWith("./") || target.startsWith("../")) {
+      const candidate = join(packageRoot, target);
+      if (existsSync(candidate)) return canonical(candidate);
+      continue;
+    }
+    try {
+      return canonical(createRequire(pathToFileURL(join(packageRoot, "package.json")).href).resolve(target));
+    } catch {
+      continue;
+    }
+  }
+  throw new Error(`no #pi-tui target resolves: ${targets.join(", ")}`);
+}
+
+/**
+ * What pinned Pi resolves the same specifier to, as a real path — asked from
+ * inside Pi's own directory, which is where Pi asks it.
+ *
+ * Pi's directory is located by walking node_modules outward, the way Node
+ * itself would, rather than by resolving Pi's entry: its `exports` map offers
+ * no CommonJS condition, so an ordinary require cannot name it. From there a
+ * require resolves pi-tui, which publishes no `exports` map at all.
+ */
+function resolvePinnedPiTui(packageRoot) {
+  let directory = packageRoot;
+  while (true) {
+    const candidate = join(directory, "node_modules", "@earendil-works", "pi-coding-agent");
+    if (existsSync(join(candidate, "package.json"))) {
+      return canonical(createRequire(pathToFileURL(join(candidate, "package.json")).href).resolve("@earendil-works/pi-tui"));
+    }
+    const parent = dirname(directory);
+    if (parent === directory) throw new Error("pinned Pi is not installed beneath this package root");
+    directory = parent;
+  }
+}
+
+function canonical(path) {
+  try {
+    return realpathSync.native(path);
+  } catch {
+    return path;
+  }
+}
+
+/**
+ * Report whether A1 and pinned Pi resolve pi-tui to the same file.
+ * Returns a discriminated outcome; never throws.
+ */
+export function inspectPiTuiModuleIdentity(packageRoot) {
+  let own;
+  let pinned;
+  try {
+    own = resolveOwnPiTui(packageRoot);
+  } catch (error) {
+    return { kind: "unresolved", side: "a1", message: message(error) };
+  }
+  try {
+    pinned = resolvePinnedPiTui(packageRoot);
+  } catch (error) {
+    return { kind: "unresolved", side: "pi", message: message(error) };
+  }
+  return own === pinned ? { kind: "unified", path: own } : { kind: "split", own, pinned };
+}
+
+function message(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** Launch-entry wrapper: warn on stderr when the two sides disagree. */
+export function assertSinglePiTuiModuleAtLaunch(packageRoot, warn) {
+  const outcome = inspectPiTuiModuleIdentity(packageRoot);
+  if (outcome.kind === "split") {
+    warn(`a1: pi-tui resolves to two different copies (${outcome.own} for a1, ${outcome.pinned} for Pi); extension UI may not render. The #pi-tui alias in a1's package.json no longer names Pi's copy.\n`);
+  } else if (outcome.kind === "unresolved") {
+    warn(`a1: could not resolve pi-tui from ${outcome.side === "a1" ? "a1" : "pinned Pi"} (${outcome.message}); extension UI may not render.\n`);
+  }
+}

package/bin/ui.js

@@ -1,5 +1,15 @@
 #!/usr/bin/env node
 
+const { assertSinglePiTuiModuleAtLaunch } = await import("./module-identity.js");
+const { fileURLToPath } = await import("node:url");
+
+// Before the composition loads pinned Pi's terminal stack: confirm A1 and Pi
+// resolve it to the same copy, so extensions and the owned UI share one module
+// identity (see bin/module-identity.js for the full story). Nothing is repaired
+// here — A1's package manifest decides which copy wins, and this only reports
+// when that stopped being true.
+assertSinglePiTuiModuleAtLaunch(fileURLToPath(new URL("..", import.meta.url)), message => process.stderr.write(message));
+
 const { runSelectedInteractiveRuntime } = await import("../dist/src/features/launch/index.js");
 
 runSelectedInteractiveRuntime(process.env.A1_LAUNCH_PROFILE ?? "a1", {

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

@@ -5,7 +5,7 @@
   "platform": "darwin",
   "architecture": "arm64",
   "capability": "unsupported",
-  "builtAt": "2026-08-22T17:52:01.473Z",
+  "builtAt": "2026-08-23T17:52:00.836Z",
   "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-22T17:52:01.995Z",
+  "builtAt": "2026-08-23T17:52:10.246Z",
   "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-22T17:52:47.054Z",
+  "builtAt": "2026-08-23T17:52:55.388Z",
   "artifact": {
     "filename": "process-guardian.exe",
-    "sha256": "ed14b51aeb577ecd86df4a8a9ca3ea33c27885da8d3d196b26b0d705d70a0b71",
+    "sha256": "b31ad029bb569cfcb1a33db24999a556b5e12c1ac63f792fc1c555e6850243e6",
     "size": 172544
   },
   "provenance": {

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

@@ -0,0 +1,15 @@
+/**
+ * `pi` and `sandbox` exist to compare A1 against pinned Pi and to try resources
+ * against an isolated profile. Both are development instruments rather than
+ * product, so a stable release does not carry them: what a released `a1` exposes
+ * is the product plus its maintenance and package commands.
+ *
+ * Which build this is comes from its own version. A prerelease version is a
+ * `next`-channel build, which is where that work happens; a release version is
+ * not. Nothing to configure, and no way for a released build to be talked into it.
+ */
+export interface CliCapabilities {
+    readonly developmentProfiles: boolean;
+}
+export declare function cliCapabilities(version: string): CliCapabilities;
+export declare function isPrereleaseVersion(version: string): boolean;

package/dist/src/cli/capabilities.js

@@ -0,0 +1,7 @@
+import { prerelease } from "semver";
+export function cliCapabilities(version) {
+    return Object.freeze({ developmentProfiles: isPrereleaseVersion(version) });
+}
+export function isPrereleaseVersion(version) {
+    return (prerelease(version)?.length ?? 0) > 0;
+}

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

@@ -1,15 +1,18 @@
 import { type InteractiveLaunchIntent, type LaunchProfileId } from "../features/launch/index.js";
+import type { CliCapabilities } from "./capabilities.js";
+import type { PackageCommandRequest } from "./packages.js";
 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 packages: (request: PackageCommandRequest) => Promise<number>;
 }
 export interface CliOutput {
     readonly stderr: (message: string) => void;
 }
-export declare const CLI_USAGE: string;
-export declare function dispatchCli(arguments_: readonly string[], handlers: CliHandlers, output: CliOutput): Promise<number>;
+export declare function cliUsage(capabilities: CliCapabilities): string;
+export declare function dispatchCli(arguments_: readonly string[], handlers: CliHandlers, output: CliOutput, capabilities: CliCapabilities): Promise<number>;
 export type CliCommand = {
     readonly kind: "launch";
     readonly profileId: LaunchProfileId;
@@ -18,8 +21,11 @@ export type CliCommand = {
 } | {
     readonly kind: "update";
     readonly channel: UpdateChannel;
+} | {
+    readonly kind: "packages";
+    readonly request: PackageCommandRequest;
 } | {
     readonly kind: "error";
     readonly message: string;
 };
-export declare function parseCliCommand(arguments_: readonly string[]): CliCommand;
+export declare function parseCliCommand(arguments_: readonly string[], capabilities: CliCapabilities): CliCommand;

package/dist/src/cli/dispatch.js

@@ -1,35 +1,123 @@
 import { interactiveLaunchIntent } from "../features/launch/index.js";
 import { PRODUCT_TEXT } from "../product-identity.js";
-export const CLI_USAGE = PRODUCT_TEXT.usage(["", "pi", "sandbox", "version", "update", "update:next"]);
-export async function dispatchCli(arguments_, handlers, output) {
-    const command = parseCliCommand(arguments_);
+export function cliUsage(capabilities) {
+    return PRODUCT_TEXT.usage([
+        "",
+        ...(capabilities.developmentProfiles ? ["pi", "sandbox"] : []),
+        "version",
+        "update [self|<source>|--extensions|--models]",
+        "update:next",
+        "install <source>",
+        "remove <source>",
+        "list",
+    ]);
+}
+const PROFILE_WORDS = new Set(["pi", "sandbox"]);
+export async function dispatchCli(arguments_, handlers, output, capabilities) {
+    const command = parseCliCommand(arguments_, capabilities);
     if (command.kind === "error") {
-        output.stderr(`${command.message}\n${CLI_USAGE}\n`);
+        output.stderr(`${command.message}\n${cliUsage(capabilities)}\n`);
         return 2;
     }
     if (command.kind === "launch")
         return await handlers.launch(interactiveLaunchIntent(command.profileId));
     if (command.kind === "version")
         return await handlers.version();
+    if (command.kind === "packages")
+        return await handlers.packages(command.request);
     return await handlers.update(command.channel);
 }
-export function parseCliCommand(arguments_) {
+export function parseCliCommand(arguments_, capabilities) {
     if (arguments_.length === 0)
         return { kind: "launch", profileId: "a1" };
-    if (arguments_.length > 1)
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic("commands do not accept additional arguments.") };
-    const [command] = arguments_;
-    if (command === "pi" || command === "sandbox")
-        return { kind: "launch", profileId: command };
-    if (command === "ui")
-        return { kind: "error", message: `The ui subcommand was removed; run bare ${PRODUCT_TEXT.commandName} for the owned UI.` };
+    const [command, ...rest] = arguments_;
+    if (capabilities.developmentProfiles && (command === "pi" || command === "sandbox")) {
+        return withoutArguments(rest, { kind: "launch", profileId: command });
+    }
     if (command === "version")
-        return { kind: "version" };
-    if (command === "update")
-        return { kind: "update", channel: "stable" };
+        return withoutArguments(rest, { kind: "version" });
     if (command === "update:next")
-        return { kind: "update", channel: "next" };
+        return withoutArguments(rest, { kind: "update", channel: "next" });
+    if (command === "update")
+        return parseUpdate(rest);
+    if (command === "install" || command === "remove" || command === "uninstall") {
+        return parseSourceCommand(command === "install" ? "install" : "remove", rest);
+    }
+    if (command === "list")
+        return withoutArguments(rest, { kind: "packages", request: { verb: "list", source: null } });
+    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 ?? ""}`) };
 }
+/**
+ * `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
+ * certifies each release against one pinned Pi, so moving Pi underneath it would
+ * invalidate what was certified.
+ */
+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.`),
+        };
+    }
+    // A release channel is spelled with the colon. Taking the bare word as a package
+    // source would turn a near miss into a confident search for a package nobody has.
+    if (target === "next" || target === "stable") {
+        const form = target === "next" ? `${PRODUCT_TEXT.commandName} update:next` : `${PRODUCT_TEXT.commandName} update`;
+        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`selects a release channel with a colon; run ${form}.`) };
+    }
+    if (target === "--extensions")
+        return { kind: "packages", request: { verb: "update", source: null } };
+    if (target === "--models")
+        return { kind: "packages", request: { verb: "refresh-models", source: null } };
+    if (target === undefined || target.startsWith("-"))
+        return unknownOption(target ?? "", "update");
+    if (PROFILE_WORDS.has(target))
+        return profileRejection("update");
+    return { kind: "packages", request: { verb: "update", source: target } };
+}
+function parseSourceCommand(verb, rest) {
+    const flag = rest.find(argument => argument.startsWith("-"));
+    if (flag !== undefined)
+        return unknownOption(flag, verb);
+    if (rest.length === 0)
+        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`${verb} requires a package source.`) };
+    if (rest.length > 1)
+        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`${verb} accepts one package source.`) };
+    const [source] = rest;
+    if (source === undefined)
+        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`${verb} requires a package source.`) };
+    if (PROFILE_WORDS.has(source))
+        return profileRejection(verb);
+    return { kind: "packages", request: { verb, source } };
+}
+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 profileRejection(verb) {
+    return {
+        kind: "error",
+        message: PRODUCT_TEXT.diagnostic(`manages packages in its own profile, so ${verb} takes no profile; Pi manages Pi's own profile.`),
+    };
+}
+function unknownOption(option, verb) {
+    if (option.startsWith("--profile"))
+        return profileRejection(verb);
+    return { kind: "error", message: PRODUCT_TEXT.diagnostic(`received an unknown option for ${verb}: ${option}`) };
+}

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

@@ -1,3 +1,5 @@
+export * from "./capabilities.js";
 export * from "./dispatch.js";
+export * from "./packages.js";
 export * from "./version.js";
 export * from "./version-stats.js";

package/dist/src/cli/index.js

@@ -1,3 +1,5 @@
+export * from "./capabilities.js";
 export * from "./dispatch.js";
+export * from "./packages.js";
 export * from "./version.js";
 export * from "./version-stats.js";

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

@@ -0,0 +1,23 @@
+import { initializeProductProfile } from "../features/launch/index.js";
+import type { AgentPackageOutcome, AgentPackagesPort, AgentPackagesPortInput } from "../foundation/agent-engine-contracts/index.js";
+/**
+ * Package commands manage A1's own profile and nothing else, so no request carries
+ * a profile: `update` with no source means every installed package, and refreshing
+ * model catalogs is its own verb rather than a flag the caller has to remember to
+ * check.
+ */
+export type PackageCommandVerb = "install" | "remove" | "list" | "update" | "refresh-models";
+export interface PackageCommandRequest {
+    readonly verb: PackageCommandVerb;
+    readonly source: string | null;
+}
+export interface PackageCommandEnvironment {
+    readonly createPort: (input: AgentPackagesPortInput) => AgentPackagesPort;
+    readonly cwd?: string;
+    readonly environment?: NodeJS.ProcessEnv;
+    readonly stdout?: (message: string) => void;
+    readonly stderr?: (message: string) => void;
+    readonly initializeProfile?: typeof initializeProductProfile;
+}
+export declare function runPackageCommand(request: PackageCommandRequest, environment: PackageCommandEnvironment): Promise<number>;
+export declare function renderPackageOutcome(outcome: AgentPackageOutcome, profileRoot: string): string;