@timurproko/a1 0.1.1-dev.11 → 0.1.1-dev.13

package/README.md

@@ -10,22 +10,48 @@ npm install --global @timurproko/a1@latest
 
 ```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
 ```
 
+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.
+
+```sh
+a1 pi           # untouched vanilla Pi oracle: ~/.pi/agent
+a1 sandbox      # unchanged isolated vanilla Pi profile: ~/.a1/sandbox
+```
+
+## Extensions
+
+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
+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
+```
+
+A running session loads a newly installed package after a restart. Pi's own
+profile at `~/.pi/agent` is managed by Pi itself.
+
 ## Develop
 
 ```sh
-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 instance
-npm run test:fast   # typecheck + fast suite, no build needed
-npm test            # same as test:fast
-npm run test:full   # complete non-physical suite
+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
 ```
 
 ## Release

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,75 @@
+/**
+ * One pi-tui module identity per process.
+ *
+ * npm can materialize @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's isolated dependency tree. A1's
+ * owned UI imports the root copy while pinned Pi's extension loader hands
+ * extensions the nested copy, so every TUI class exists twice: `instanceof`
+ * checks and prototype patches made by extensions land on classes the
+ * renderer never uses — extension chrome silently disappears and routed
+ * input dead-ends.
+ *
+ * Repair runs at launch, not at install: npm's `prepare` hook is skipped for
+ * registry installs, so an installed A1 must self-heal the same way a source
+ * checkout does. The root copy is replaced with a junction (Windows) or
+ * directory symlink to the nested copy so every loader resolves the same
+ * files and therefore the same module instances.
+ *
+ * This lives in bin/ (shipped, plain JS) rather than src/ deliberately: its
+ * whole job is repairing the node_modules layout, which the Pi API boundary
+ * policy rightly forbids ordinary production code from touching.
+ *
+ * The repair is idempotent and fail-open: a hoisted tree (single copy), an
+ * already-linked root, a version mismatch, or a filesystem that refuses the
+ * link all leave the tree as it was — launch proceeds with a warning rather
+ * than failing, because a degraded UI beats no UI.
+ */
+import { existsSync, lstatSync, readFileSync, renameSync, rmSync, symlinkSync } from "node:fs";
+import { join } from "node:path";
+
+function packageVersion(directory) {
+  return JSON.parse(readFileSync(join(directory, "package.json"), "utf8")).version;
+}
+
+/**
+ * Collapse a duplicated @earendil-works/pi-tui under `packageRoot` onto the
+ * copy pinned Pi resolves, so extensions and the owned UI share one module
+ * instance. Must run before anything in the process imports pi-tui.
+ * Returns a discriminated outcome; never throws.
+ */
+export function ensureSinglePiTuiModule(packageRoot) {
+  const rootCopy = join(packageRoot, "node_modules", "@earendil-works", "pi-tui");
+  const nestedCopy = join(
+    packageRoot,
+    "node_modules", "@earendil-works", "pi-coding-agent",
+    "node_modules", "@earendil-works", "pi-tui",
+  );
+  try {
+    if (!existsSync(nestedCopy)) return { kind: "single-copy" };
+    if (existsSync(rootCopy) && lstatSync(rootCopy).isSymbolicLink()) return { kind: "already-linked" };
+    if (existsSync(rootCopy)) {
+      const rootVersion = packageVersion(rootCopy);
+      const nestedVersion = packageVersion(nestedCopy);
+      if (rootVersion !== nestedVersion) return { kind: "version-mismatch", rootVersion, nestedVersion };
+      const retired = `${rootCopy}.duplicate`;
+      rmSync(retired, { recursive: true, force: true });
+      renameSync(rootCopy, retired);
+      rmSync(retired, { recursive: true, force: true });
+    }
+    symlinkSync(nestedCopy, rootCopy, "junction");
+    return { kind: "linked" };
+  } catch (error) {
+    return { kind: "failed", message: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+/** Launch-entry wrapper: repair, and warn on stderr when the tree stays split. */
+export function ensureSinglePiTuiModuleAtLaunch(packageRoot, warn) {
+  const outcome = ensureSinglePiTuiModule(packageRoot);
+  if (outcome.kind === "version-mismatch") {
+    warn(`a1: pi-tui is duplicated at incompatible versions (${outcome.rootVersion} vs ${outcome.nestedVersion}); extension UI may not render.\n`);
+  } else if (outcome.kind === "failed") {
+    warn(`a1: could not unify the duplicated pi-tui module (${outcome.message}); extension UI may not render.\n`);
+  }
+}

package/bin/ui.js

@@ -1,5 +1,13 @@
 #!/usr/bin/env node
 
+const { ensureSinglePiTuiModuleAtLaunch } = await import("./module-identity.js");
+const { fileURLToPath } = await import("node:url");
+
+// Before the composition loads pinned Pi's terminal stack: collapse npm's
+// duplicated copies of it so extensions and the owned UI share one module
+// identity (see bin/module-identity.js for the full story).
+ensureSinglePiTuiModuleAtLaunch(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-23T09:25:46.770Z",
+  "builtAt": "2026-08-23T14:26:10.351Z",
   "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-23T09:25:43.327Z",
+  "builtAt": "2026-08-23T14:26:49.615Z",
   "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-23T09:26:36.967Z",
+  "builtAt": "2026-08-23T14:26:50.453Z",
   "artifact": {
     "filename": "process-guardian.exe",
-    "sha256": "1fd994f340bfa8423eee47ab6b7c3a19a5b1a19dea88814af27d8a989cfa0da0",
+    "sha256": "1073746062839c69cc4de5df47cc2eecc9211f26e80518395b2987f958c86a02",
     "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;

package/dist/src/cli/packages.js

@@ -0,0 +1,84 @@
+import { configurationRootForProfile, initializeProductProfile, resolveLaunchProfilePaths } from "../features/launch/index.js";
+import { PRODUCT_TEXT } from "../product-identity.js";
+export async function runPackageCommand(request, environment) {
+    const stdout = environment.stdout ?? (message => process.stdout.write(message));
+    const stderr = environment.stderr ?? (message => process.stderr.write(message));
+    const cwd = environment.cwd ?? process.cwd();
+    const processEnvironment = environment.environment ?? process.env;
+    const paths = resolveLaunchProfilePaths({ environment: processEnvironment });
+    const profileRoot = configurationRootForProfile("a1", paths);
+    if (profileRoot === null)
+        throw new Error(PRODUCT_TEXT.diagnostic("has no profile root for package commands"));
+    try {
+        await (environment.initializeProfile ?? initializeProductProfile)(profileRoot);
+    }
+    catch (error) {
+        stderr(`${PRODUCT_TEXT.diagnostic(`could not prepare its profile at ${profileRoot}: ${message(error)}`)}\n`);
+        return 1;
+    }
+    const port = environment.createPort({
+        profileRoot,
+        cwd,
+        onProgress: progress => stdout(`${progress.message}\n`),
+    });
+    const outcome = await runVerb(port, request);
+    const rendered = renderPackageOutcome(outcome, profileRoot);
+    (outcome.status === "completed" ? stdout : stderr)(rendered);
+    return outcome.status === "completed" ? 0 : 1;
+}
+async function runVerb(port, request) {
+    if (request.verb === "list")
+        return await port.list();
+    if (request.verb === "refresh-models")
+        return await port.refreshModels();
+    if (request.verb === "update")
+        return await port.update(request.source ?? undefined);
+    if (request.source === null)
+        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;
+    if (outcome.status === "failed") {
+        return `${PRODUCT_TEXT.diagnostic(`could not ${describeOperation(outcome.operation)}: ${outcome.detail ?? "unknown failure"}`)}\n`;
+    }
+    if (outcome.status === "not-found") {
+        return `${PRODUCT_TEXT.diagnostic(`found no package matching ${outcome.source ?? "that source"} in ${profileRoot}.`)}\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`;
+        case "remove":
+            return `${name} removed ${outcome.source} from ${profileRoot}.\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`;
+        case "list":
+            return renderPackageList(outcome, profileRoot);
+    }
+}
+function renderPackageList(outcome, profileRoot) {
+    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}:`];
+    for (const entry of outcome.packages) {
+        lines.push(`  ${entry.source}${entry.filtered ? " (partly enabled)" : ""}`);
+        if (entry.installedPath !== null)
+            lines.push(`    ${entry.installedPath}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+function describeOperation(operation) {
+    if (operation === "refresh-models")
+        return "refresh the model catalogs";
+    if (operation === "list")
+        return "list installed packages";
+    return `${operation} the package`;
+}
+function message(error) {
+    return (error instanceof Error ? error.message : String(error)).replace(/\s+/g, " ").trim();
+}

package/dist/src/foundation/agent-engine-contracts/index.d.ts

@@ -2,6 +2,7 @@ export * from "./capability-ports.js";
 export * from "./domain.js";
 export * from "./domain-validation.js";
 export * from "./model.js";
+export * from "./package-ports.js";
 export * from "./ports.js";
 export * from "./validation.js";
 export * from "./serialization.js";

package/dist/src/foundation/agent-engine-contracts/index.js

@@ -2,6 +2,7 @@ export * from "./capability-ports.js";
 export * from "./domain.js";
 export * from "./domain-validation.js";
 export * from "./model.js";
+export * from "./package-ports.js";
 export * from "./ports.js";
 export * from "./validation.js";
 export * from "./serialization.js";

package/dist/src/foundation/agent-engine-contracts/package-ports.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Extension packages are managed outside any session: the command that installs
+ * one runs before the runtime exists, against a profile root chosen by the caller
+ * rather than by whatever session happens to be open. So this port stands apart
+ * from the session-scoped service ports and names only what a package operation
+ * needs — a root, a source, and an outcome a caller can render without knowing
+ * which engine performed it.
+ */
+export type AgentPackageOperation = "install" | "remove" | "update" | "refresh-models" | "list";
+/**
+ * Why an operation ended, kept separate from the prose so callers can branch on
+ * it. `not-found` is the one failure an engine can state structurally — the source
+ * is not configured in this profile — rather than only in a message.
+ */
+export type AgentPackageStatus = "completed" | "not-found" | "failed";
+export interface AgentPackageDescriptor {
+    readonly source: string;
+    readonly installedPath: string | null;
+    /** True when the profile enables only part of what the package provides. */
+    readonly filtered: boolean;
+}
+export interface AgentPackageOutcome {
+    readonly operation: AgentPackageOperation;
+    readonly status: AgentPackageStatus;
+    readonly source: string | null;
+    readonly packages: readonly AgentPackageDescriptor[];
+    readonly detail: string | null;
+}
+export interface AgentPackageProgress {
+    readonly operation: AgentPackageOperation;
+    readonly message: string;
+}
+export interface AgentPackagesPort {
+    readonly capabilities: {
+        readonly install: boolean;
+        readonly remove: boolean;
+        readonly update: boolean;
+        readonly refreshModels: boolean;
+    };
+    /** Absolute profile root every operation of this port acts on. */
+    readonly profileRoot: string;
+    list(): Promise<AgentPackageOutcome>;
+    install(source: string): Promise<AgentPackageOutcome>;
+    remove(source: string): Promise<AgentPackageOutcome>;
+    update(source?: string): Promise<AgentPackageOutcome>;
+    refreshModels(): Promise<AgentPackageOutcome>;
+}
+export interface AgentPackagesPortInput {
+    readonly profileRoot: string;
+    readonly cwd: string;
+    readonly onProgress?: (progress: AgentPackageProgress) => void;
+}
+export declare function assertAgentPackagesPort(port: AgentPackagesPort): void;
+export declare function agentPackageOutcome(operation: AgentPackageOperation, status: AgentPackageStatus, detail?: string | null, source?: string | null, packages?: readonly AgentPackageDescriptor[]): AgentPackageOutcome;

package/dist/src/foundation/agent-engine-contracts/package-ports.js

@@ -0,0 +1,31 @@
+/**
+ * Extension packages are managed outside any session: the command that installs
+ * one runs before the runtime exists, against a profile root chosen by the caller
+ * rather than by whatever session happens to be open. So this port stands apart
+ * from the session-scoped service ports and names only what a package operation
+ * needs — a root, a source, and an outcome a caller can render without knowing
+ * which engine performed it.
+ */
+export function assertAgentPackagesPort(port) {
+    if (typeof port?.capabilities !== "object" || port.capabilities === null)
+        throw new TypeError("packages port capabilities are required");
+    if (typeof port.profileRoot !== "string" || port.profileRoot.length === 0)
+        throw new TypeError("packages port requires an absolute profile root");
+    for (const operation of ["list", "install", "remove", "update", "refreshModels"]) {
+        if (typeof port[operation] !== "function")
+            throw new TypeError(`packages port requires ${operation}`);
+    }
+    for (const capability of ["install", "remove", "update", "refreshModels"]) {
+        if (typeof port.capabilities[capability] !== "boolean")
+            throw new TypeError(`packages capability ${capability} must be explicit`);
+    }
+}
+export function agentPackageOutcome(operation, status, detail, source, packages = []) {
+    return Object.freeze({
+        operation,
+        status,
+        source: source ?? null,
+        packages: Object.freeze([...packages]),
+        detail: detail ?? null,
+    });
+}

package/dist/src/foundation/pi-component-adapter/shell-presenters-transcript.d.ts

@@ -37,6 +37,21 @@ export declare function createPiShellChangelog(markdown: string): PiShellCompone
 export declare function createPiShellHotkeys(): PiShellComponentPort;
 export declare function createPiShellTranscriptComponent(initial: OwnedUiTranscriptBlock, cwd: string, extensions?: PiShellExtensionRendererResolver): PiShellTranscriptComponentPort;
 export declare function renderPiShellTranscriptBlock(block: OwnedUiTranscriptBlock, width: number, cwd: string): readonly string[];
+/**
+ * Pinned Pi's CLI prints startup diagnostics with `reportDiagnostics` before
+ * the banner: the whole line, prefix included, in chalk's basic ANSI severity
+ * colour — not the theme's tokens — with info lines dim and unprefixed.
+ */
+export declare function renderPiShellStartupDiagnostic(diagnostic: {
+    readonly severity: "info" | "warning" | "error";
+    readonly message: string;
+}, width: number): readonly string[];
+/**
+ * Pinned Pi's `showPackageUpdateNotification` banner: warning-coloured dynamic
+ * borders around a bold warning title, the muted update instruction with the
+ * accent command, and the package list.
+ */
+export declare function renderPiShellPackageUpdateNotice(packages: readonly string[], width: number): readonly string[];
 type PiAssistantMessage = NonNullable<ConstructorParameters<typeof AssistantMessageComponent>[0]>;
 export declare function validatedAssistantMessage(block: OwnedUiTranscriptBlock): PiAssistantMessage;
 export {};

package/dist/src/foundation/pi-component-adapter/shell-presenters-transcript.js

@@ -141,6 +141,39 @@ export function renderPiShellTranscriptBlock(block, width, cwd) {
     ensureTheme();
     return transcriptComponent(block, cwd, true).render(width);
 }
+/**
+ * Pinned Pi's CLI prints startup diagnostics with `reportDiagnostics` before
+ * the banner: the whole line, prefix included, in chalk's basic ANSI severity
+ * colour — not the theme's tokens — with info lines dim and unprefixed.
+ */
+export function renderPiShellStartupDiagnostic(diagnostic, width) {
+    ensureTheme();
+    const escape = String.fromCharCode(27);
+    const chalk = diagnostic.severity === "error"
+        ? { open: `${escape}[31m`, close: `${escape}[39m`, prefix: "Error: " }
+        : diagnostic.severity === "warning"
+            ? { open: `${escape}[33m`, close: `${escape}[39m`, prefix: "Warning: " }
+            : { open: `${escape}[2m`, close: `${escape}[22m`, prefix: "" };
+    return new Text(`${chalk.open}${chalk.prefix}${diagnostic.message}${chalk.close}`, 0, 0).render(width);
+}
+/**
+ * Pinned Pi's `showPackageUpdateNotification` banner: warning-coloured dynamic
+ * borders around a bold warning title, the muted update instruction with the
+ * accent command, and the package list.
+ */
+export function renderPiShellPackageUpdateNotice(packages, width) {
+    ensureTheme();
+    const theme = piTheme();
+    const container = new Container();
+    container.addChild(new Spacer(1));
+    container.addChild(new DynamicBorder(text => theme.fg("warning", text)));
+    container.addChild(new Text(`${theme.bold(theme.fg("warning", "Package Updates Available"))}\n`
+        + `${theme.fg("muted", "Package updates are available. Run ")}${theme.fg("accent", "pi update --extensions")}\n`
+        + `${theme.fg("muted", "Packages:")}\n`
+        + packages.map(name => `- ${name}`).join("\n"), 1, 0));
+    container.addChild(new DynamicBorder(text => theme.fg("warning", text)));
+    return container.render(width);
+}
 function transcriptComponent(block, cwd, expanded, extensions) {
     switch (block.kind) {
         case "user": {

package/dist/src/foundation/pi-engine-adapter/adapter.d.ts

@@ -1,4 +1,4 @@
-import { type AgentSessionRuntime, type SessionInfo } from "@earendil-works/pi-coding-agent";
+import { type AgentSessionRuntime, type AgentSessionServices, type SessionInfo } from "@earendil-works/pi-coding-agent";
 import { OWNED_UI_EXTENSION_CONTRACT_VERSION, OWNED_UI_EXTENSION_RENDER_CALLBACKS, OWNED_UI_EXTENSION_UI_CALLBACKS, OWNED_UI_EXTENSION_UI_PROPERTIES, type OwnedUiCommand, type OwnedUiCommandOutcome, type OwnedUiEvent, type OwnedUiSessionViewModel, type OwnedUiSnapshot } from "../owned-ui-contracts/index.js";
 import { type PiAuthenticationProviderOption, type PiBashWorkflowResult, type PiPinnedSettingsCallback, type PiPinnedSettingsSnapshot, type PiWorkflowAutocompleteCommand, type PiWorkflowHost, type PiWorkflowInteractionHost, type PiWorkflowOption, type PiWorkflowRequest, type PiWorkflowResult } from "./workflows.js";
 import type { AgentSettingsPort } from "../agent-engine-contracts/index.js";
@@ -51,6 +51,7 @@ export interface PiScopedModelsRefreshResult extends PiScopedModelsContext {
     readonly status: string;
     readonly statusKind: "success" | "warning";
 }
+type PiServicesApi = AgentSessionServices;
 export type PiEngineRuntimeFactory = (input: PiEngineRuntimeFactoryInput) => Promise<AgentSessionRuntime>;
 export interface OwnedPiResourceSummary {
     readonly kind: "skill" | "prompt-template" | "agent-context" | "system-prompt" | "theme";
@@ -90,6 +91,11 @@ export interface PiEngineAdapterOptions {
      * offering stay here.
      */
     readonly availableThemes?: () => readonly string[];
+    /**
+     * Startup extension-package update probe, mirroring pinned Pi's interactive
+     * mode. Returns display names of packages with updates available.
+     */
+    readonly checkPackageUpdates?: (settingsManager: PiServicesApi["settingsManager"]) => Promise<readonly string[]>;
 }
 export interface AdapterCommandResult {
     readonly outcome: OwnedUiCommandOutcome;
@@ -155,3 +161,4 @@ export declare class PiEngineAdapter {
     dispose(): Promise<void>;
 }
 export declare function createPiEngineAdapter(options?: PiEngineAdapterOptions): Promise<PiEngineAdapter>;
+export {};

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

@@ -4,7 +4,7 @@ import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { promisify } from "node:util";
 import { PRODUCT_IDENTITY } from "../../product-identity.js";
-import { copyToClipboard, getAgentDir, ProjectTrustStore, SessionManager, } from "@earendil-works/pi-coding-agent";
+import { copyToClipboard, DefaultPackageManager, getAgentDir, ProjectTrustStore, SessionManager, } from "@earendil-works/pi-coding-agent";
 import { OWNED_UI_EXTENSION_CONTRACT_VERSION, OWNED_UI_EXTENSION_RENDER_CALLBACKS, OWNED_UI_EXTENSION_UI_CALLBACKS, OWNED_UI_EXTENSION_UI_PROPERTIES, assertOwnedUiCommand, assertOwnedUiExtensionUiPort, assertOwnedUiSnapshot, } from "../owned-ui-contracts/index.js";
 import { PINNED_PI_SETTINGS_CALLBACKS, PINNED_PI_WORKFLOW_COMMAND_NAMES, } from "./workflows.js";
 import { createPiRuntimeIntegration } from "./runtime-integration.js";
@@ -19,6 +19,7 @@ const DEFAULT_SURFACE = {
 };
 export class PiEngineAdapter {
     #runtimeFactory;
+    #checkPackageUpdates;
     #cwd;
     #agentDir;
     #sessionId;
@@ -73,6 +74,10 @@ export class PiEngineAdapter {
         this.#agentDir = options.agentDir ?? getAgentDir();
         this.#sessionId = options.sessionId ?? "owned-session-1";
         this.#runtimeFactory = options.createRuntime ?? createDefaultPiRuntime;
+        this.#checkPackageUpdates = options.checkPackageUpdates
+            ?? (options.createRuntime
+                ? async () => []
+                : settingsManager => checkDefaultPiPackageUpdates(this.#cwd, this.#agentDir, settingsManager));
         this.#workflowHost = options.workflowHost ?? defaultWorkflowHost();
         this.#availableThemes = options.availableThemes ?? null;
         this.#workflowInteraction = { prompt: async () => null, notify() { } };
@@ -122,8 +127,25 @@ export class PiEngineAdapter {
         this.#editor = { ...this.#editor, submitEnabled: true };
         this.#emitEvent({ type: "session-lifecycle", lifecycle: "ready", reason: null });
         this.#emitView();
+        void this.#announcePackageUpdates(runtime.services.settingsManager);
         return this.view();
     }
+    async #announcePackageUpdates(settingsManager) {
+        if (process.env.PI_OFFLINE)
+            return;
+        let updates;
+        try {
+            updates = await this.#checkPackageUpdates(settingsManager);
+        }
+        catch {
+            return;
+        }
+        if (this.#disposed || updates.length === 0)
+            return;
+        const packages = updates.map(name => `- ${name}`).join("\n");
+        this.#addDiagnostic("info", "package-updates", `Package updates are available. Run pi update --extensions\nPackages:\n${packages}`, true);
+        this.#emitView();
+    }
     onEvent(listener) {
         this.#listeners.add(listener);
         listener(this.#event({ type: "session-view", view: this.view() }));
@@ -1876,6 +1898,11 @@ export async function createPiEngineAdapter(options = {}) {
 async function createDefaultPiRuntime(input) {
     return createPiRuntimeIntegration({ cwd: input.cwd, agentDir: input.agentDir });
 }
+async function checkDefaultPiPackageUpdates(cwd, agentDir, settingsManager) {
+    const packageManager = new DefaultPackageManager({ cwd, agentDir, settingsManager });
+    const updates = await packageManager.checkForAvailableUpdates();
+    return updates.map(update => update.displayName);
+}
 function pinnedSessionInfoPresentation(value, sessionName, entries, modelRuntime) {
     const stats = isRecord(value) ? value : {};
     const tokens = dynamicObject(stats, "tokens");

package/dist/src/foundation/pi-engine-adapter/index.d.ts

@@ -4,6 +4,7 @@ export * from "./runtime-integration.js";
 export * from "./session-integration.js";
 export * from "./model-auth-integration.js";
 export * from "./settings-integration.js";
+export * from "./package-integration.js";
 export * from "./resource-extension-integration.js";
 export * from "./workflow-controllers.js";
 export * from "./workflows.js";

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

@@ -4,6 +4,7 @@ export * from "./runtime-integration.js";
 export * from "./session-integration.js";
 export * from "./model-auth-integration.js";
 export * from "./settings-integration.js";
+export * from "./package-integration.js";
 export * from "./resource-extension-integration.js";
 export * from "./workflow-controllers.js";
 export * from "./workflows.js";

package/dist/src/foundation/pi-engine-adapter/package-integration.d.ts

@@ -0,0 +1,13 @@
+import { type AgentPackagesPort, type AgentPackagesPortInput } from "../agent-engine-contracts/index.js";
+/**
+ * Pinned Pi's package manager already takes the profile root as an argument, so
+ * this binds it to the root A1 chose rather than to whatever the configuration-root
+ * environment variable happens to say. Pi's own package command handler is not used:
+ * it prints Pi's command names and ends the process, and both of those belong to
+ * whichever A1 command is running.
+ *
+ * The settings manager is created with project trust withheld, which is what keeps
+ * every operation to the user scope of the selected profile — a project-local
+ * `packages` list is never read, so it can never be written either.
+ */
+export declare function createPiPackagesPort(input: AgentPackagesPortInput): AgentPackagesPort;

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

@@ -0,0 +1,112 @@
+import { join } from "node:path";
+import { DefaultPackageManager, ModelRuntime, SettingsManager } from "@earendil-works/pi-coding-agent";
+import { agentPackageOutcome, } from "../agent-engine-contracts/index.js";
+const MODEL_REFRESH_TIMEOUT_MS = 15_000;
+/**
+ * Pinned Pi's package manager already takes the profile root as an argument, so
+ * this binds it to the root A1 chose rather than to whatever the configuration-root
+ * environment variable happens to say. Pi's own package command handler is not used:
+ * it prints Pi's command names and ends the process, and both of those belong to
+ * whichever A1 command is running.
+ *
+ * The settings manager is created with project trust withheld, which is what keeps
+ * every operation to the user scope of the selected profile — a project-local
+ * `packages` list is never read, so it can never be written either.
+ */
+export function createPiPackagesPort(input) {
+    const { profileRoot, cwd } = input;
+    const settingsManager = SettingsManager.create(cwd, profileRoot, { projectTrusted: false });
+    const packageManager = new DefaultPackageManager({ cwd, agentDir: profileRoot, settingsManager });
+    packageManager.setProgressCallback(event => {
+        if (event.type !== "start" || !event.message)
+            return;
+        input.onProgress?.({ operation: operationFor(event.action), message: event.message });
+    });
+    const configured = () => packageManager.listConfiguredPackages()
+        .filter(entry => entry.scope === "user")
+        .map(entry => Object.freeze({
+        source: entry.source,
+        installedPath: entry.installedPath ?? null,
+        filtered: entry.filtered,
+    }));
+    const isConfigured = (source) => configured().some(entry => entry.source === source || entry.source.startsWith(`${source}@`));
+    return Object.freeze({
+        capabilities: Object.freeze({ install: true, remove: true, update: true, refreshModels: true }),
+        profileRoot,
+        async list() {
+            return await attempt("list", null, async () => agentPackageOutcome("list", "completed", null, null, configured()));
+        },
+        async install(source) {
+            return await attempt("install", source, async () => {
+                await packageManager.installAndPersist(source);
+                return agentPackageOutcome("install", "completed", null, source, configured());
+            });
+        },
+        async remove(source) {
+            return await attempt("remove", source, async () => {
+                const removed = await packageManager.removeAndPersist(source);
+                if (!removed)
+                    return agentPackageOutcome("remove", "not-found", null, source);
+                return agentPackageOutcome("remove", "completed", null, source, configured());
+            });
+        },
+        async update(source) {
+            return await attempt("update", source ?? null, async () => {
+                // Asking first keeps "that package is not installed here" a structural
+                // answer rather than a string a caller would have to recognize.
+                if (source !== undefined && !isConfigured(source))
+                    return agentPackageOutcome("update", "not-found", null, source);
+                await packageManager.update(source);
+                return agentPackageOutcome("update", "completed", null, source ?? null, configured());
+            });
+        },
+        async refreshModels() {
+            return await attempt("refresh-models", null, async () => {
+                await refreshModelCatalogs(profileRoot);
+                return agentPackageOutcome("refresh-models", "completed");
+            });
+        },
+    });
+}
+async function attempt(operation, source, run) {
+    try {
+        return await run();
+    }
+    catch (error) {
+        return agentPackageOutcome(operation, "failed", describe(error), source);
+    }
+}
+async function refreshModelCatalogs(profileRoot) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), MODEL_REFRESH_TIMEOUT_MS);
+    try {
+        const modelRuntime = await ModelRuntime.create({
+            authPath: join(profileRoot, "auth.json"),
+            modelsPath: join(profileRoot, "models.json"),
+            allowModelNetwork: false,
+            signal: controller.signal,
+        });
+        const result = await modelRuntime.refresh({ allowNetwork: true, force: true, signal: controller.signal });
+        if (result.aborted)
+            throw new Error(`model catalog refresh timed out after ${MODEL_REFRESH_TIMEOUT_MS}ms`);
+        if (result.errors.size > 0) {
+            throw new Error(Array.from(result.errors, ([provider, error]) => `${provider}: ${error.message}`).join("; "));
+        }
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function operationFor(action) {
+    if (action === "install")
+        return "install";
+    if (action === "remove")
+        return "remove";
+    return "update";
+}
+function describe(error) {
+    const message = (error instanceof Error ? error.message : String(error)).replace(/\s+/g, " ").trim();
+    if (message.length === 0)
+        return "unknown package failure";
+    return message.length > 600 ? `${message.slice(0, 597)}...` : message;
+}

package/dist/src/foundation/pi-engine-adapter/runtime-integration.d.ts

@@ -1,4 +1,4 @@
-import { type AgentSession, type AgentSessionRuntime } from "@earendil-works/pi-coding-agent";
+import { type AgentSession, type AgentSessionRuntime, type AgentSessionServices, type ScopedModel } from "@earendil-works/pi-coding-agent";
 export interface PiRuntimeIntegrationOptions {
     readonly cwd: string;
     readonly agentDir: string;
@@ -10,9 +10,26 @@ export type PiSessionReplacement = {
     readonly kind: "resume";
     readonly sessionPath: string;
 };
+interface ConfiguredModelScope {
+    readonly scopedModels: readonly ScopedModel[];
+    readonly model: ScopedModel["model"] | undefined;
+    readonly thinkingLevel: ScopedModel["thinkingLevel"];
+    readonly diagnostics: readonly {
+        type: "info" | "warning" | "error";
+        message: string;
+    }[];
+}
+/**
+ * Mirrors pinned Pi's CLI startup: resolve the `models` patterns from settings
+ * into a scoped model list, keep the resolver's warnings (e.g. "No models match
+ * pattern ..."), and pick the same initial model pinned Pi would pick — the
+ * saved default when it is in scope, otherwise the first scoped model.
+ */
+export declare function resolveConfiguredModelScope(services: Pick<AgentSessionServices, "settingsManager" | "modelRuntime">): Promise<ConfiguredModelScope>;
 export declare function createPiRuntimeIntegration(options: PiRuntimeIntegrationOptions): Promise<AgentSessionRuntime>;
 export declare function bindPiRuntimeSession(runtime: AgentSessionRuntime, rebind: (session: AgentSession) => Promise<void>): () => void;
 export declare function replacePiRuntimeSession(runtime: AgentSessionRuntime, replacement: PiSessionReplacement): Promise<{
     readonly cancelled: boolean;
 }>;
 export declare function disposePiRuntimeIntegration(runtime: AgentSessionRuntime): Promise<void>;
+export {};

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

@@ -1,14 +1,49 @@
-import { createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, SessionManager, } from "@earendil-works/pi-coding-agent";
+import { createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, resolveModelScopeWithDiagnostics, SessionManager, } from "@earendil-works/pi-coding-agent";
+/**
+ * Mirrors pinned Pi's CLI startup: resolve the `models` patterns from settings
+ * into a scoped model list, keep the resolver's warnings (e.g. "No models match
+ * pattern ..."), and pick the same initial model pinned Pi would pick — the
+ * saved default when it is in scope, otherwise the first scoped model.
+ */
+export async function resolveConfiguredModelScope(services) {
+    const patterns = services.settingsManager.getEnabledModels();
+    if (!patterns || patterns.length === 0) {
+        return { scopedModels: [], model: undefined, thinkingLevel: undefined, diagnostics: [] };
+    }
+    const { scopedModels, diagnostics } = await resolveModelScopeWithDiagnostics([...patterns], services.modelRuntime, { signal: AbortSignal.timeout(15_000) });
+    let selected;
+    if (scopedModels.length > 0) {
+        const savedProvider = services.settingsManager.getDefaultProvider();
+        const savedModelId = services.settingsManager.getDefaultModel();
+        const savedModel = savedProvider && savedModelId
+            ? services.modelRuntime.getModel(savedProvider, savedModelId)
+            : undefined;
+        selected = (savedModel
+            ? scopedModels.find(scoped => scoped.model.provider === savedModel.provider && scoped.model.id === savedModel.id)
+            : undefined) ?? scopedModels[0];
+    }
+    return {
+        scopedModels,
+        model: selected?.model,
+        thinkingLevel: selected?.thinkingLevel,
+        diagnostics: diagnostics.map(diagnostic => ({ type: diagnostic.type, message: diagnostic.message })),
+    };
+}
 export async function createPiRuntimeIntegration(options) {
     const sessionManager = SessionManager.create(options.cwd, options.sessionDir ?? process.env.PI_CODING_AGENT_SESSION_DIR);
     const createRuntime = async ({ cwd, sessionManager: targetSessionManager, sessionStartEvent, }) => {
         const services = await createAgentSessionServices({ cwd, agentDir: options.agentDir });
+        const modelScope = await resolveConfiguredModelScope(services);
+        const hasExistingSession = targetSessionManager.buildSessionContext().messages.length > 0;
         const created = await createAgentSessionFromServices({
             services,
             sessionManager: targetSessionManager,
             ...(sessionStartEvent ? { sessionStartEvent } : {}),
+            ...(modelScope.model && !hasExistingSession ? { model: modelScope.model } : {}),
+            ...(modelScope.thinkingLevel && !hasExistingSession ? { thinkingLevel: modelScope.thinkingLevel } : {}),
+            ...(modelScope.scopedModels.length > 0 ? { scopedModels: [...modelScope.scopedModels] } : {}),
         });
-        return { ...created, services, diagnostics: services.diagnostics };
+        return { ...created, services, diagnostics: [...modelScope.diagnostics] };
     };
     return createAgentSessionRuntime(createRuntime, {
         cwd: options.cwd,

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

@@ -1,6 +1,6 @@
 import { MOUSE_TRACKING_OFF, MOUSE_TRACKING_ON, parseMouseInput } from "../ui-components/index.js";
 import { PINNED_PI_HIDDEN_COMMAND_NAMES, PINNED_PI_WORKFLOW_COMMAND_NAMES, } from "../pi-engine-adapter/index.js";
-import { createPiExtensionUiBridge, createPiQueuedInputStatus, createPiShellArmin, createPiShellAuthProviderSelector, createPiShellChangelog, createPiShellDaxnuts, createPiShellDialog, createPiShellEarendilAnnouncement, createPiShellEditor, createPiShellExtensionSelector, createPiShellFooter, createPiShellHeader, createPiShellHotkeys, createPiShellLoadedResources, createPiShellLoginDialog, createPiShellModelSelector, createPiShellOperationLoader, createPiShellReloadBox, createPiShellScopedModelsSelector, createPiShellSelector, createPiShellSessionInfo, createPiShellSessionSelector, createPiShellSettingsSelector, createPiShellStatus, createPiShellTranscriptComponent, createPiShellTreeSelector, createPiShellTrustSelector, createPiShellUserMessageSelector, piTheme, renderPiShellStatusText, renderPiShellTranscriptBlock, } from "../pi-component-adapter/index.js";
+import { createPiExtensionUiBridge, createPiQueuedInputStatus, createPiShellArmin, createPiShellAuthProviderSelector, createPiShellChangelog, createPiShellDaxnuts, createPiShellDialog, createPiShellEarendilAnnouncement, createPiShellEditor, createPiShellExtensionSelector, createPiShellFooter, createPiShellHeader, createPiShellHotkeys, createPiShellLoadedResources, createPiShellLoginDialog, createPiShellModelSelector, createPiShellOperationLoader, createPiShellReloadBox, createPiShellScopedModelsSelector, createPiShellSelector, createPiShellSessionInfo, createPiShellSessionSelector, createPiShellSettingsSelector, createPiShellStatus, createPiShellTranscriptComponent, createPiShellTreeSelector, createPiShellTrustSelector, createPiShellUserMessageSelector, piTheme, renderPiShellPackageUpdateNotice, renderPiShellStartupDiagnostic, renderPiShellStatusText, renderPiShellTranscriptBlock, } from "../pi-component-adapter/index.js";
 import { PiTuiRuntimeAdapter, } from "../pi-tui-runtime-adapter/index.js";
 export class OwnedUiSessionShellRoot {
     editor;
@@ -136,7 +136,17 @@ export class OwnedUiSessionShellRoot {
                 return ["", ...rows];
             return rows;
         });
-        const diagnosticRows = this.#view.diagnostics.slice(-3).flatMap(diagnostic => renderPiShellTranscriptBlock({
+        const diagnostics = this.#view.diagnostics;
+        const startupRows = diagnostics
+            .filter(diagnostic => diagnostic.code === "engine-startup")
+            .flatMap(diagnostic => renderPiShellStartupDiagnostic(diagnostic, width));
+        const packageUpdateRows = diagnostics
+            .filter(diagnostic => diagnostic.code === "package-updates")
+            .flatMap(diagnostic => renderPiShellPackageUpdateNotice(diagnostic.message.split("\n").filter(line => line.startsWith("- ")).map(line => line.slice(2)), width));
+        const diagnosticRows = diagnostics
+            .filter(diagnostic => diagnostic.code !== "engine-startup" && diagnostic.code !== "package-updates")
+            .slice(-3)
+            .flatMap(diagnostic => renderPiShellTranscriptBlock({
             id: `diagnostic-${diagnostic.sequence}`,
             kind: diagnostic.severity === "error" ? "error" : "system",
             status: "finalized",
@@ -149,9 +159,11 @@ export class OwnedUiSessionShellRoot {
         if (resourceRows.at(-1) === "")
             resourceRows.pop();
         return [
+            ...startupRows,
             ...(this.#extensionHeader ?? this.header).render(width),
             ...resourceRows,
             ...transcript,
+            ...packageUpdateRows,
             ...diagnosticRows,
         ];
     }

package/docs/features/launch-profiles.md

@@ -8,6 +8,8 @@
 | `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.
+
 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.
 
 ## First launch

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timurproko/a1",
-  "version": "0.1.1-dev.11",
+  "version": "0.1.1-dev.13",
   "description": "Standalone terminal workspace for supervised native and managed agents",
   "type": "module",
   "packageManager": "npm@11.13.0",
@@ -46,7 +46,7 @@
     "start:sandbox": "npm run build && node scripts/dev-launch.mjs sandbox",
     "prepack": "node scripts/prepack-gate.mjs",
     "prepublishOnly": "npm run test:release",
-    "prepare": "npm run build",
+    "prepare": "node scripts/unify-pi-tui.mjs && npm run build",
     "update:pi-settings-metadata": "node scripts/update-pi-settings-metadata.mjs"
   },
   "dependencies": {