@timurproko/a1 0.1.8-dev.226 → 0.1.8-dev.259

package/bin/guardian.js

@@ -5,18 +5,20 @@ startup.enableEnvironmentCompileCache(process.env);
 await startup.markStartupPhase(process.env, "guardian-start");
 const { fileURLToPath } = await import("node:url");
 const { resolve } = await import("node:path");
+const { parseSessionSelection } = await import("../dist/foundation/lifecycle/index.js");
 const { runLaunchGuardian } = await import("../dist/foundation/launch-guardian/index.js");
 
 const releaseRoot = process.env.A1_RELEASE_ROOT ?? fileURLToPath(new URL("..", import.meta.url));
 const profileId = process.env.A1_LAUNCH_PROFILE ?? "a1";
 
-runLaunchGuardian({
+Promise.resolve().then(() => runLaunchGuardian({
+  sessionSelection: parseSessionSelection(process.argv.slice(2)),
   profileId,
   releaseRoot,
   uiEntry: resolve(releaseRoot, "bin", "ui.js"),
   environment: process.env,
   cwd: process.cwd(),
-}).then(
+})).then(
   code => { process.exitCode = code; },
   error => {
     console.error(error instanceof Error ? error.message : String(error));

package/bin/supervisor.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { runSupervisor } from "../dist/foundation/supervision/index.js";
 
-runSupervisor().catch(error => {
+runSupervisor(process.argv.slice(2)).catch(error => {
   console.error(error instanceof Error ? error.stack ?? error.message : String(error));
   process.exitCode = 1;
 });

package/bin/ui.js

@@ -2,48 +2,56 @@
 
 const startup = await import("../dist/foundation/startup/index.js");
 startup.enableEnvironmentCompileCache(process.env);
+// Performance: begin the exact launch graph together while the trace write is pending.
+// Direct owned-module entries avoid evaluating unrelated barrel exports before first paint.
+const modules = Promise.all([
+  import("./module-identity.js"),
+  import("node:url"),
+  import("../dist/features/launch/runtime-selection.js"),
+  import("../dist/foundation/lifecycle/session-selection.js"),
+  import("../dist/features/owned-ui/project-trust-prompt.js"),
+  import("../dist/features/owned-ui/session-fork-prompt.js"),
+  import("../dist/features/owned-ui/run.js"),
+  import("../dist/composition/owned-ui.js"),
+]);
 await startup.markStartupPhase(process.env, "ui-entry");
-const { assertSinglePiTuiModuleAtLaunch } = await import("./module-identity.js");
-const { fileURLToPath } = await import("node:url");
+const [
+  { assertSinglePiTuiModuleAtLaunch },
+  { fileURLToPath },
+  { runSelectedInteractiveRuntime },
+  { parseSessionSelection },
+  { createConsoleProjectTrustPrompt },
+  { createConsoleSessionForkPrompt },
+  { runOwnedUi },
+  { composeOwnedUi },
+] = await modules;
 
-// Compatibility: 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.
+// Compatibility: before the composition uses 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.
 assertSinglePiTuiModuleAtLaunch(fileURLToPath(new URL("..", import.meta.url)), message => process.stderr.write(message));
+await startup.markStartupPhase(process.env, "ui-modules-loaded");
 
-const { runSelectedInteractiveRuntime } = await import("../dist/features/launch/index.js");
-
-const launchArgs = process.argv.slice(2);
-let sessionPath;
-if (launchArgs.length > 0) {
-  if (launchArgs.length !== 2 || launchArgs[0] !== "--session" || launchArgs[1].trim().length === 0) {
-    throw new Error("Usage: a1 [--session <session-file>]");
-  }
-  sessionPath = launchArgs[1];
-}
-
-runSelectedInteractiveRuntime(process.env.A1_LAUNCH_PROFILE ?? "a1", {
-  ownedUi: async (profileId, ownedSurfaces) => {
-    const [{ createConsoleProjectTrustPrompt, runOwnedUi }, { composeOwnedUi }] = await Promise.all([
-      import("../dist/features/owned-ui/index.js"),
-      import("../dist/composition/index.js"),
-    ]);
-    await startup.markStartupPhase(process.env, "ui-modules-loaded");
-    const { application, settings } = await composeOwnedUi({
-      cwd: process.cwd(),
-      profileId,
-      ownedSurfaces,
-      projectTrustPrompt: createConsoleProjectTrustPrompt(),
-      ...(sessionPath === undefined ? {} : { sessionPath }),
-    });
-    return await runOwnedUi({ application, ...(settings === null ? {} : { settings }) });
-  },
+const sessionSelection = parseSessionSelection(process.argv.slice(2));
+const profile = process.env.A1_LAUNCH_PROFILE ?? "a1";
+Promise.resolve().then(() => {
+  if (sessionSelection && profile !== "a1") throw new Error("session selection requires the normal A1 profile");
+  return runSelectedInteractiveRuntime(profile, {
+    ownedUi: async (profileId, ownedSurfaces) => {
+      const { application, settings } = await composeOwnedUi({
+        cwd: process.cwd(),
+        profileId,
+        ownedSurfaces,
+        projectTrustPrompt: createConsoleProjectTrustPrompt(),
+        sessionForkPrompt: createConsoleSessionForkPrompt(),
+        ...(sessionSelection === undefined ? {} : { sessionSelection }),
+      });
+      return await runOwnedUi({ application, ...(settings === null ? {} : { settings }) });
+    },
+  });
 }).then(
   code => { process.exitCode = code; },
   error => {
-    console.error(error instanceof Error ? error.stack ?? error.message : String(error));
-    process.exitCode = 1;
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = error?.name === "PiSessionSelectionError" ? error.exitCode : 1;
   },
 );

package/bin/warmup.js

@@ -4,15 +4,24 @@ const startup = await import("../dist/foundation/startup/index.js");
 startup.assertImmutableWarmupEnvironment(process.env);
 startup.enableEnvironmentCompileCache(process.env);
 
-// Security: this entry imports but never composes, so it creates no terminal, profile/session
-// path, trust callback, executable resource loader, extension runner, or network client.
-const [composition, engine, components, runtime] = await Promise.all([
-  import("../dist/composition/index.js"),
-  import("../dist/integrations/pi/engine/index.js"),
-  import("../dist/integrations/pi/components/index.js"),
-  import("../dist/integrations/pi/tui-runtime/index.js"),
+// Security: this entry imports the exact interactive graph but never composes it, so it
+// creates no terminal, profile/session path, trust callback, executable resource loader,
+// extension runner, or network client.
+const [identity, launch, selection, trustPrompt, forkPrompt, run, composition] = await Promise.all([
+  import("./module-identity.js"),
+  import("../dist/features/launch/runtime-selection.js"),
+  import("../dist/foundation/lifecycle/session-selection.js"),
+  import("../dist/features/owned-ui/project-trust-prompt.js"),
+  import("../dist/features/owned-ui/session-fork-prompt.js"),
+  import("../dist/features/owned-ui/run.js"),
+  import("../dist/composition/owned-ui.js"),
 ]);
-if (typeof composition.composeOwnedUi !== "function" || typeof engine.createPiEngineAdapter !== "function"
-  || typeof components.applyConfiguredPiTheme !== "function" || typeof runtime.createPiTerminalBridge !== "function") {
+if (typeof identity.assertSinglePiTuiModuleAtLaunch !== "function"
+  || typeof launch.runSelectedInteractiveRuntime !== "function"
+  || typeof selection.parseSessionSelection !== "function"
+  || typeof trustPrompt.createConsoleProjectTrustPrompt !== "function"
+  || typeof forkPrompt.createConsoleSessionForkPrompt !== "function"
+  || typeof run.runOwnedUi !== "function"
+  || typeof composition.composeOwnedUi !== "function") {
   throw new Error("immutable startup graph is incomplete");
 }

package/dist/cli/dispatch.d.ts

@@ -1,6 +1,7 @@
-import { type InteractiveLaunchIntent, type LaunchProfileId } from "../features/launch/index.js";
+import { type InteractiveLaunchIntent, type LaunchProfileId, type SessionSelection } from "../features/launch/index.js";
 import type { CliCapabilities } from "./capabilities.js";
 import type { PackageCommandRequest } from "./packages.js";
+import { type PackageCliVerb, type PackageSyntaxDiagnostic } from "./package-messages.js";
 export type UpdateChannel = "stable" | "next";
 export interface CliHandlers {
     readonly launch: (intent: InteractiveLaunchIntent) => Promise<number>;
@@ -19,9 +20,16 @@ export type CliCommand = {
     readonly kind: "noop";
 } | {
     readonly kind: "help";
+} | {
+    readonly kind: "package-help";
+    readonly verb: PackageCliVerb;
+} | {
+    readonly kind: "package-error";
+    readonly diagnostic: PackageSyntaxDiagnostic;
 } | {
     readonly kind: "launch";
     readonly profileId: LaunchProfileId;
+    readonly sessionSelection?: SessionSelection;
 } | {
     readonly kind: "version";
 } | {

package/dist/cli/dispatch.js

@@ -1,8 +1,11 @@
-import { interactiveLaunchIntent } from "../features/launch/index.js";
+import { interactiveLaunchIntent, parseSessionSelection } from "../features/launch/index.js";
+import { packageCommandHelp, renderPackageSyntax } from "./package-messages.js";
 import { PRODUCT_TEXT } from "../product-identity.js";
 export function cliUsage(capabilities) {
     return PRODUCT_TEXT.usage([
         "",
+        "--session <path|id>",
+        "--session-dir <dir> --session <path|id>",
         ...(capabilities.developmentComparison ? ["pi"] : []),
         "--help",
         "-h",
@@ -25,6 +28,8 @@ export function cliHelp(capabilities) {
     return [
         "Common:",
         `  ${command}`,
+        `  ${command} --session <path|id>`,
+        `  ${command} --session-dir <dir> --session <path|id>`,
         ...(capabilities.developmentComparison ? [`  ${command} pi`] : []),
         `  ${command} --help`,
         `  ${command} -h`,
@@ -56,12 +61,20 @@ export async function dispatchCli(arguments_, handlers, output, capabilities) {
         output.stdout(cliHelp(capabilities));
         return 0;
     }
+    if (command.kind === "package-help") {
+        output.stdout(packageCommandHelp(command.verb));
+        return 0;
+    }
+    if (command.kind === "package-error") {
+        output.stderr(renderPackageSyntax(command.diagnostic));
+        return 2;
+    }
     if (command.kind === "error") {
         output.stderr(`${command.message}\n`);
         return 2;
     }
     if (command.kind === "launch")
-        return await handlers.launch(interactiveLaunchIntent(command.profileId));
+        return await handlers.launch(interactiveLaunchIntent(command.profileId, command.sessionSelection));
     if (command.kind === "version")
         return await handlers.version();
     if (command.kind === "packages")
@@ -72,6 +85,15 @@ export function parseCliCommand(arguments_, capabilities) {
     if (arguments_.length === 0)
         return { kind: "launch", profileId: "a1" };
     const [command, ...rest] = arguments_;
+    if (command === "--session" || command === "--session-dir") {
+        try {
+            const sessionSelection = parseSessionSelection(arguments_);
+            return { kind: "launch", profileId: "a1", ...(sessionSelection === undefined ? {} : { sessionSelection }) };
+        }
+        catch (error) {
+            return { kind: "error", message: PRODUCT_TEXT.diagnostic(`could not parse session launch: ${error instanceof Error ? error.message : String(error)}`) };
+        }
+    }
     if (command === "--help" || command === "-h")
         return withoutArguments(rest, { kind: "help" });
     if (command === "--version" || command === "-v")
@@ -132,11 +154,21 @@ function updateGrammarError(detail) {
 }
 function parsePiPackageCommand(arguments_) {
     const [verb, ...rest] = arguments_;
+    if ((verb === "install" || verb === "remove" || verb === "uninstall" || verb === "list" || verb === "update")
+        && rest.some(value => value === "--help" || value === "-h")) {
+        return { kind: "package-help", verb: verb === "uninstall" ? "remove" : verb };
+    }
     if (verb === "install" || verb === "remove" || verb === "uninstall") {
         return parseSourceCommand(verb === "install" ? "install" : "remove", rest);
     }
-    if (verb === "list")
-        return withoutArguments(rest, { kind: "packages", request: { verb: "list", source: null } });
+    if (verb === "list") {
+        const flag = rest.find(argument => argument.startsWith("-"));
+        if (flag !== undefined)
+            return packageOptionError(flag, "list");
+        if (rest[0] !== undefined)
+            return packageSyntax({ verb: "list", kind: "unexpected-argument", value: rest[0] });
+        return { kind: "packages", request: { verb: "list", source: null } };
+    }
     if (verb === "update")
         return parsePiPackageUpdate(rest);
     return { kind: "noop" };
@@ -144,8 +176,25 @@ function parsePiPackageCommand(arguments_) {
 function parsePiPackageUpdate(rest) {
     if (rest.length === 0)
         return pinnedPiUpdateError();
-    if (rest.length > 1)
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic("pi update accepts one target.") };
+    if (rest.length > 1) {
+        const unknown = rest.find(value => value.startsWith("-") && !["--extensions", "--models", "--self", "--all"].includes(value));
+        if (unknown !== undefined)
+            return packageOptionError(unknown, "update");
+        if (rest.includes("--self") || rest.includes("--all") || rest.includes("self") || rest.includes("pi"))
+            return pinnedPiUpdateError();
+        if (rest.every(value => value === rest[0]) && rest[0]?.startsWith("-")) {
+            return { kind: "error", message: PRODUCT_TEXT.diagnostic("pi update accepts one target.") };
+        }
+        const sources = rest.filter(value => !value.startsWith("-"));
+        if (sources[1] !== undefined)
+            return packageSyntax({ verb: "update", kind: "unexpected-argument", value: sources[1] });
+        const message = rest.includes("--models")
+            ? rest.includes("--extensions")
+                ? "--models cannot be combined with --self, --extensions, --all, or --extension"
+                : "--models cannot be combined with a positional source"
+            : "positional update targets cannot be combined with --self, --extensions, or --all";
+        return packageSyntax({ verb: "update", kind: "conflict", message });
+    }
     const [target] = rest;
     if (target === "--extensions")
         return { kind: "packages", request: { verb: "update", source: null } };
@@ -154,7 +203,7 @@ function parsePiPackageUpdate(rest) {
     if (target === "--self" || target === "--all" || target === "self" || target === "pi")
         return pinnedPiUpdateError();
     if (target === undefined || target.startsWith("-"))
-        return unknownOption(target ?? "", "pi update");
+        return packageOptionError(target ?? "", "update");
     return { kind: "packages", request: { verb: "update", source: target } };
 }
 function pinnedPiUpdateError() {
@@ -172,18 +221,28 @@ function pinnedPiUpdateError() {
 function parseSourceCommand(verb, rest) {
     const flag = rest.find(argument => argument.startsWith("-"));
     if (flag !== undefined)
-        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)
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`${verb} accepts one package source.`) };
-    const [source] = rest;
+        return packageOptionError(flag, verb);
+    const [source, extra] = rest;
+    if (extra !== undefined)
+        return packageSyntax({ verb, kind: "unexpected-argument", value: extra });
     if (source === undefined)
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`${verb} requires a package source.`) };
+        return packageSyntax({ verb, kind: "missing-source" });
     if (PROFILE_WORDS.has(source))
         return profileRejection(verb);
     return { kind: "packages", request: { verb, source } };
 }
+function packageSyntax(diagnostic) {
+    return { kind: "package-error", diagnostic };
+}
+function packageOptionError(option, verb) {
+    if (option.startsWith("--profile") || option === "-l" || option === "--local")
+        return profileRejection(verb);
+    // Compatibility: these recognized Pi flags remain outside A1's supported subset.
+    if (["--extension", "--approve", "--no-approve", "-a", "-na", "--force"].includes(option)) {
+        return unknownOption(option, `pi ${verb}`);
+    }
+    return packageSyntax({ verb, kind: "unknown-option", value: option });
+}
 function withoutArguments(rest, command) {
     if (rest.length === 0)
         return command;

package/dist/cli/package-messages.d.ts

@@ -0,0 +1,26 @@
+import chalk from "chalk";
+/** Supported subset of pinned Pi's package-manager CLI presentation. */
+export type PackageCliVerb = "install" | "remove" | "list" | "update";
+export type PackageSyntaxDiagnostic = {
+    readonly verb: PackageCliVerb;
+    readonly kind: "missing-source";
+} | {
+    readonly verb: PackageCliVerb;
+    readonly kind: "unknown-option";
+    readonly value: string;
+} | {
+    readonly verb: PackageCliVerb;
+    readonly kind: "unexpected-argument";
+    readonly value: string;
+} | {
+    readonly verb: "update";
+    readonly kind: "conflict";
+    readonly message: string;
+};
+type MessageStyle = Pick<typeof chalk, "red" | "dim" | "bold">;
+export declare function packageCommandUsage(verb: PackageCliVerb): string;
+/** Diagnostic facts stay unstyled until the terminal boundary decides color support. */
+export declare function renderPackageSyntax(diagnostic: PackageSyntaxDiagnostic, style?: MessageStyle): string;
+/** Pi's help layout, with unsupported options and examples deliberately absent. */
+export declare function packageCommandHelp(verb: PackageCliVerb, style?: MessageStyle): string;
+export {};

package/dist/cli/package-messages.js

@@ -0,0 +1,71 @@
+// Provenance: wording/layout adapted from Pi 0.84.2 packages/coding-agent/src/package-manager-cli.ts
+// at 914cf1472e715297caa30db4b9535d534a9eb718 (MIT); grammar is restricted to A1's supported subset.
+import chalk from "chalk";
+import { PRODUCT_TEXT } from "../product-identity.js";
+export function packageCommandUsage(verb) {
+    const command = `${PRODUCT_TEXT.commandName} pi ${verb}`;
+    if (verb === "install" || verb === "remove")
+        return `${command} <source>`;
+    if (verb === "update")
+        return `${command} [source|--extensions|--models]`;
+    return command;
+}
+/** Diagnostic facts stay unstyled until the terminal boundary decides color support. */
+export function renderPackageSyntax(diagnostic, style = chalk) {
+    const usage = packageCommandUsage(diagnostic.verb);
+    let message;
+    if (diagnostic.kind === "unknown-option") {
+        return `${style.red(`Unknown option ${diagnostic.value} for "${diagnostic.verb}".`)}\n`
+            + `${style.dim(`Use "${PRODUCT_TEXT.commandName} --help" or "${usage}".`)}\n`;
+    }
+    if (diagnostic.kind === "missing-source")
+        message = `Missing ${diagnostic.verb} source.`;
+    else if (diagnostic.kind === "unexpected-argument")
+        message = `Unexpected argument ${diagnostic.value}.`;
+    else
+        message = diagnostic.message;
+    return `${style.red(message)}\n${style.dim(`Usage: ${usage}`)}\n`;
+}
+/** Pi's help layout, with unsupported options and examples deliberately absent. */
+export function packageCommandHelp(verb, style = chalk) {
+    const command = `${PRODUCT_TEXT.commandName} pi`;
+    const header = `${style.bold("Usage:")}\n  ${packageCommandUsage(verb)}\n\n`;
+    switch (verb) {
+        case "install":
+            return header + `Install a package and add it to settings.
+
+Examples:
+  ${command} install npm:@foo/bar
+  ${command} install git:github.com/user/repo
+  ${command} install git:git@github.com:user/repo
+  ${command} install https://github.com/user/repo
+  ${command} install ssh://git@github.com/user/repo
+  ${command} install ./local/path
+
+`;
+        case "remove":
+            return header + `Remove a package and its source from settings.
+Alias: ${command} uninstall <source>
+
+Examples:
+  ${command} remove npm:@foo/bar
+  ${command} uninstall npm:@foo/bar
+
+`;
+        case "list":
+            return header + "List installed packages from user settings.\n\n";
+        case "update":
+            return header + `Update installed packages or model catalogs.
+
+Options:
+  --extensions            Update installed packages only
+  --models                Refresh model catalogs only
+
+Short forms:
+  ${command} update --extensions   Update installed packages only
+  ${command} update --models       Refresh model catalogs only
+  ${command} update <source>       Update one package
+
+`;
+    }
+}

package/dist/cli/packages.d.ts

@@ -16,6 +16,7 @@ export interface PackageCommandStyle {
     readonly bold: (message: string) => string;
     readonly green: (message: string) => string;
     readonly red: (message: string) => string;
+    readonly yellow: (message: string) => string;
 }
 export interface PackageCommandEnvironment {
     readonly createPort: (input: AgentPackagesPortInput) => AgentPackagesPort;
@@ -28,4 +29,4 @@ export interface PackageCommandEnvironment {
     readonly style?: PackageCommandStyle;
 }
 export declare function runPackageCommand(request: PackageCommandRequest, environment: PackageCommandEnvironment): Promise<number>;
-export declare function renderPackageOutcome(outcome: AgentPackageOutcome, profileRoot: string, style?: PackageCommandStyle): string;
+export declare function renderPackageOutcome(outcome: AgentPackageOutcome, style?: PackageCommandStyle): string;

package/dist/cli/packages.js

@@ -21,10 +21,15 @@ export async function runPackageCommand(request, environment) {
     const port = environment.createPort({
         profileRoot,
         cwd,
-        onProgress: progress => stdout(`${style.dim(progress.message)}\n`),
+        onProgress: progress => stdout(style.dim(`${progress.message}\n`)),
+        onDiagnostic: diagnostic => {
+            stderr(`${style.yellow(diagnostic.message)}\n`);
+            if (diagnostic.detail)
+                stderr(`${style.dim(diagnostic.detail)}\n`);
+        },
     });
     const outcome = await runVerb(port, request);
-    const rendered = renderPackageOutcome(outcome, profileRoot, style);
+    const rendered = renderPackageOutcome(outcome, style);
     (outcome.status === "completed" ? stdout : stderr)(rendered);
     return outcome.status === "completed" ? 0 : 1;
 }
@@ -39,22 +44,17 @@ async function runVerb(port, request) {
         throw new Error(PRODUCT_TEXT.diagnostic(`requires a source for ${request.verb}`));
     return request.verb === "install" ? await port.install(request.source) : await port.remove(request.source);
 }
-export function renderPackageOutcome(outcome, profileRoot, style = chalk) {
-    // Compatibility: model refresh remains an A1 top-level command. The `a1 pi` compatibility
-    // transcript applies to package operations only.
-    if (outcome.operation === "refresh-models") {
-        if (outcome.status === "failed") {
-            return `${PRODUCT_TEXT.diagnostic(`could not ${describeOperation(outcome.operation)}: ${outcome.detail ?? "unknown failure"}`)}\n`;
-        }
-        return `${PRODUCT_TEXT.displayName} refreshed the model catalogs in ${profileRoot}.\n`;
-    }
+export function renderPackageOutcome(outcome, style = chalk) {
     if (outcome.status === "failed") {
-        return `${style.red(`Error: ${outcome.detail ?? "Unknown package command error"}`)}\n`;
+        const fallback = outcome.operation === "refresh-models" ? "Unknown model catalog refresh error" : "Unknown package command error";
+        return `${style.red(`Error: ${outcome.detail ?? fallback}`)}\n`;
     }
     if (outcome.status === "not-found") {
         return `${style.red(`No matching package found for ${outcome.source ?? "that source"}`)}\n`;
     }
     switch (outcome.operation) {
+        case "refresh-models":
+            return `${style.green("Model catalogs refreshed")}\n`;
         case "install":
             return `${style.green(`Installed ${outcome.source}`)}\n`;
         case "remove":
@@ -76,13 +76,6 @@ function renderPackageList(outcome, style) {
     }
     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/composition/owned-ui.d.ts

@@ -1,12 +1,15 @@
-import { type PiEngineAdapter, type PiProjectTrustPreflightPrompt } from "../integrations/pi/engine/index.js";
+import { type SessionSelection } from "../foundation/lifecycle/index.js";
+import { type PiEngineAdapter, type PiProjectTrustPreflightPrompt, type PiSessionForkPrompt } from "../integrations/pi/engine/index.js";
 import { OwnedUiSettingsSession } from "../ui/settings/index.js";
 import type { OwnedUiApplicationPort, PresentationTerminalPort } from "../contracts/presentation/index.js";
 export interface OwnedUiCompositionOptions {
     readonly cwd?: string;
     readonly terminal?: PresentationTerminalPort;
     readonly createPiAdapter?: () => Promise<PiEngineAdapter>;
-    /** Exact persisted session selected by the narrow `--session` launch form. */
+    /** Explicit file selection retained for SDK callers. Public CLI uses sessionSelection. */
     readonly sessionPath?: string;
+    readonly sessionSelection?: SessionSelection;
+    readonly sessionForkPrompt?: PiSessionForkPrompt;
     /**
      * A1 profile whose settings this session reads and writes. Omitted keeps the
      * session settings-free, which is what the pinned comparison paths use.

package/dist/composition/owned-ui.js

@@ -17,6 +17,8 @@ export async function composeOwnedUi(options = {}) {
             availableThemes: () => getAvailablePiThemes().map(theme => theme.name),
             settingsProductMode: options.ownedSurfaces === "off" ? "comparison" : "bare",
             ...(options.sessionPath === undefined ? {} : { sessionPath: options.sessionPath }),
+            ...(options.sessionSelection === undefined ? {} : { sessionSelection: options.sessionSelection }),
+            ...(options.sessionForkPrompt === undefined ? {} : { sessionForkPrompt: options.sessionForkPrompt }),
             ...(options.projectTrustPrompt === undefined ? {} : { projectTrustPrompt: options.projectTrustPrompt }),
         });
     const ownedSurfaces = options.ownedSurfaces !== "off";
@@ -37,7 +39,7 @@ export async function composeOwnedUi(options = {}) {
     };
     const shell = new OwnedUiSessionShell({
         backend: adapter,
-        cwd,
+        cwd: adapter.cwd,
         ...(options.terminal === undefined ? {} : { terminal: createPiTerminalBridge(options.terminal) }),
         ...(routeHost === null ? {} : { routeHost }),
         ...(ownedSurfaces ? { sessionLayout: "custom-viewport" } : {}),

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

@@ -45,10 +45,16 @@ export interface AgentPackagesPort {
     update(source?: string): Promise<AgentPackageOutcome>;
     refreshModels(): Promise<AgentPackageOutcome>;
 }
+/** Recoverable operation diagnostics retain the engine's visible detail and order. */
+export interface AgentPackageDiagnostic {
+    readonly message: string;
+    readonly detail?: string;
+}
 export interface AgentPackagesPortInput {
     readonly profileRoot: string;
     readonly cwd: string;
     readonly onProgress?: (progress: AgentPackageProgress) => void;
+    readonly onDiagnostic?: (diagnostic: AgentPackageDiagnostic) => 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/features/launch/intent.d.ts

@@ -1,8 +1,10 @@
-import type { LaunchProfileId } from "../../foundation/lifecycle/index.js";
-export type { LaunchProfileId } from "../../foundation/lifecycle/index.js";
+import { type SessionSelection, type LaunchProfileId } from "../../foundation/lifecycle/index.js";
+export { parseSessionSelection } from "../../foundation/lifecycle/index.js";
+export type { LaunchProfileId, SessionSelection } from "../../foundation/lifecycle/index.js";
 export interface InteractiveLaunchIntent {
     readonly kind: "interactive";
     readonly profileId: LaunchProfileId;
+    readonly sessionSelection?: SessionSelection;
 }
 export type LaunchIntent = InteractiveLaunchIntent;
-export declare function interactiveLaunchIntent(profileId: LaunchProfileId): InteractiveLaunchIntent;
+export declare function interactiveLaunchIntent(profileId: LaunchProfileId, sessionSelection?: SessionSelection): InteractiveLaunchIntent;

package/dist/features/launch/intent.js

@@ -1,3 +1,8 @@
-export function interactiveLaunchIntent(profileId) {
-    return Object.freeze({ kind: "interactive", profileId });
+import { sessionSelectionArguments } from "../../foundation/lifecycle/index.js";
+export { parseSessionSelection } from "../../foundation/lifecycle/index.js";
+export function interactiveLaunchIntent(profileId, sessionSelection) {
+    if (sessionSelection !== undefined && profileId !== "a1")
+        throw new Error("session selection requires the normal A1 profile");
+    sessionSelectionArguments(sessionSelection);
+    return Object.freeze({ kind: "interactive", profileId, ...(sessionSelection === undefined ? {} : { sessionSelection }) });
 }

package/dist/features/owned-ui/index.d.ts

@@ -2,4 +2,5 @@ export * from "./customization.js";
 export * from "./diagnostics.js";
 export * from "./run.js";
 export * from "./project-trust-prompt.js";
+export * from "./session-fork-prompt.js";
 export * from "./settings-app.js";

package/dist/features/owned-ui/index.js

@@ -2,4 +2,5 @@ export * from "./customization.js";
 export * from "./diagnostics.js";
 export * from "./run.js";
 export * from "./project-trust-prompt.js";
+export * from "./session-fork-prompt.js";
 export * from "./settings-app.js";

package/dist/features/owned-ui/session-fork-prompt.d.ts

@@ -0,0 +1,8 @@
+import type { Readable, Writable } from "node:stream";
+/** Pre-resource, line-mode confirmation matching Pi's cross-project CLI fork decision. */
+export declare function createConsoleSessionForkPrompt(options?: {
+    readonly input?: Readable;
+    readonly output?: Writable;
+}): (request: {
+    readonly sourceCwd: string;
+}) => Promise<boolean>;