@timurproko/a1 0.1.8-dev.3b54f21 → 0.1.8-dev.402

package/bin/sync-pi-tui-proxy.js

@@ -0,0 +1,97 @@
+/**
+ * Point the `#pi-tui` proxy at the copy pinned Pi actually resolves.
+ *
+ * The proxy (bin/pi-tui.js) re-exports one static path, but npm does not
+ * materialize one layout: `npm ci` against A1's lockfile keeps pinned Pi's
+ * shrinkwrapped nested pi-tui copy, while a global `npm install -g` of the
+ * published tarball hoists pi-tui to A1's node_modules root and materializes
+ * no nested copy at all. A static path can only name one of those layouts —
+ * whichever the other layout lacks, the proxy's import fails at launch and
+ * extension UI never renders.
+ *
+ * This script runs on postinstall, asks Node what pinned Pi resolves
+ * `@earendil-works/pi-tui` to — the copy Pi's extension loader hands to
+ * extensions — and rewrites the proxy's single re-export (and its declaration
+ * twin) to that file. Whatever tree npm built, the proxy names the module Pi
+ * uses, so A1's renderer and Pi's extensions share one class identity.
+ *
+ * It never fails an install: a tree in which pinned Pi or its pi-tui cannot
+ * be resolved is reported on stderr and left untouched, and launch's
+ * module-identity check names the same condition to the user.
+ *
+ * This lives in bin/ (shipped, plain JS) because it inspects and names
+ * dependency resolution, which the Pi API boundary policy rightly forbids
+ * ordinary production code from touching.
+ */
+import { readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { resolvePinnedPiTui } from "./module-identity.js";
+
+const RE_EXPORT_LINE = /^export \* from "[^"]+";$/m;
+
+/**
+ * Rewrite the proxy pair under packageRoot/bin to re-export the pi-tui module
+ * pinned Pi resolves. Returns a discriminated outcome; never throws.
+ */
+export function syncPiTuiProxy(packageRoot) {
+  // Platform: resolvePinnedPiTui answers with a canonical real path, so the directory the
+  // relative specifier is computed from must be canonical too (Windows short
+  // names, symlinked installs).
+  const canonicalRoot = canonical(packageRoot);
+  let target;
+  try {
+    target = resolvePinnedPiTui(canonicalRoot);
+  } catch (error) {
+    return { kind: "unresolved", message: error instanceof Error ? error.message : String(error) };
+  }
+
+  const binDirectory = join(canonicalRoot, "bin");
+  const runtimeSpecifier = relativeSpecifier(binDirectory, target);
+  const declarationSpecifier = runtimeSpecifier.replace(/\.js$/, ".d.ts").replace(/\.d\.d\.ts$/, ".d.ts");
+  const changed = [];
+  for (const [file, specifier] of [
+    ["pi-tui.js", runtimeSpecifier],
+    ["pi-tui.d.ts", declarationSpecifier],
+  ]) {
+    if (rewriteReExport(join(binDirectory, file), specifier)) changed.push(file);
+  }
+  return { kind: "synced", target, changed };
+}
+
+function canonical(path) {
+  try {
+    return realpathSync.native(path);
+  } catch {
+    return path;
+  }
+}
+
+function relativeSpecifier(fromDirectory, toFile) {
+  const specifier = relative(fromDirectory, toFile).split("\\").join("/");
+  return specifier.startsWith(".") ? specifier : `./${specifier}`;
+}
+
+/** Replace the file's single re-export line; returns whether the file changed. */
+function rewriteReExport(file, specifier) {
+  let source;
+  try {
+    source = readFileSync(file, "utf8");
+  } catch {
+    return false;
+  }
+  const line = `export * from "${specifier}";`;
+  if (source.includes(line) || !RE_EXPORT_LINE.test(source)) return false;
+  writeFileSync(file, source.replace(RE_EXPORT_LINE, line));
+  return true;
+}
+
+const invokedDirectly = process.argv[1] !== undefined
+  && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (invokedDirectly) {
+  const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+  const outcome = syncPiTuiProxy(packageRoot);
+  if (outcome.kind === "unresolved") {
+    process.stderr.write(`a1: could not point #pi-tui at pinned Pi's copy (${outcome.message}); extension UI may not render.\n`);
+  }
+}

package/bin/ui.js

@@ -1,30 +1,71 @@
 #!/usr/bin/env node
 
-const { assertSinglePiTuiModuleAtLaunch } = await import("./module-identity.js");
-const { fileURLToPath } = await import("node:url");
+const startup = await import("../dist/foundation/startup/index.js");
+startup.enableEnvironmentCompileCache(process.env);
+const { readLaunchContext } = await import("../dist/foundation/launch-context/index.js");
+const launchContext = readLaunchContext(process.env, "profile");
+const profile = launchContext.launchProfile;
+const { installFatalExit } = await import("../dist/foundation/terminal-cleanup/index.js");
+const { resolveProductPaths } = await import("../dist/foundation/lifecycle/index.js");
+const { join } = await import("node:path");
+let runningApplication;
+const fatal = profile === "a1" ? installFatalExit({
+  directory: join(resolveProductPaths().runtimeDir, "crashes"),
+  releaseId: launchContext.releaseId,
+  dispose: () => runningApplication?.dispose(),
+}) : undefined;
+// 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 },
+  { fileURLToPath },
+  { runSelectedInteractiveRuntime },
+  { parseSessionSelection },
+  { createConsoleProjectTrustPrompt },
+  { createConsoleSessionForkPrompt },
+  { runOwnedUi },
+  { composeOwnedUi },
+] = await modules;
 
-// 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/src/features/launch/index.js");
-
-runSelectedInteractiveRuntime(process.env.A1_LAUNCH_PROFILE ?? "a1", {
-  ownedUi: async (profileId, ownedSurfaces) => {
-    const [{ runOwnedUi }, { composeOwnedUi }] = await Promise.all([
-      import("../dist/src/features/owned-ui/index.js"),
-      import("../dist/src/composition/index.js"),
-    ]);
-    const { application, settings } = await composeOwnedUi({ cwd: process.cwd(), profileId, ownedSurfaces });
-    return await runOwnedUi({ application, ...(settings === null ? {} : { settings }) });
-  },
+const sessionSelection = parseSessionSelection(process.argv.slice(2));
+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 }),
+      });
+      runningApplication = application;
+      return await runOwnedUi({ application, ...(settings === null ? {} : { settings }) });
+    },
+  });
 }).then(
-  code => { process.exitCode = code; },
+  code => { fatal?.remove(); process.exitCode = code; },
   error => {
-    console.error(error instanceof Error ? error.stack ?? error.message : String(error));
-    process.exitCode = 1;
+    if (fatal && error?.name !== "PiSessionSelectionError") { fatal.fail(error); return; }
+    fatal?.remove();
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = error?.name === "PiSessionSelectionError" ? error.exitCode : 1;
   },
 );

package/bin/update-recovery.js

@@ -0,0 +1,274 @@
+#!/usr/bin/env node
+
+// Security: this file intentionally depends only on Node built-ins: the updater copies it into a
+// transaction capsule before npm is allowed to rename or remove the installed package.
+import { spawn } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { chmod, lstat, mkdir, open, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SCHEMA = "a1-update-recovery-v1";
+const [, , mode, manifestPath, separator, ...forwarded] = process.argv;
+
+if ((mode !== "--worker" && mode !== "--launch") || !manifestPath || (mode === "--launch" && separator !== "--")) {
+  throw new Error("invalid A1 update recovery invocation");
+}
+
+const capsule = await readCapsule(manifestPath);
+if (mode === "--worker") {
+  await runWorker(capsule);
+} else {
+  process.exitCode = await runRecoveredCommand(capsule, forwarded);
+}
+
+async function runWorker(value) {
+  await rm(value.resultPath, { force: true });
+  await writeJson(value.ownerPath, {
+    schema: SCHEMA,
+    transactionId: value.transactionId,
+    pid: process.pid,
+    startIdentity: `${process.pid}:${Math.floor(Date.now() - process.uptime() * 1000)}`,
+    startedAt: new Date().toISOString(),
+  });
+  const heartbeat = setInterval(() => {
+    void writeJson(value.ownerPath, {
+      schema: SCHEMA,
+      transactionId: value.transactionId,
+      pid: process.pid,
+      startIdentity: `${process.pid}:${Math.floor(Date.now() - process.uptime() * 1000)}`,
+      heartbeatAt: new Date().toISOString(),
+    });
+  }, 500);
+  heartbeat.unref?.();
+  const child = spawn(process.execPath, [value.npmCli, ...value.npmArguments], {
+    detached: false,
+    windowsHide: true,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  const stdout = [];
+  const stderr = [];
+  child.stdout?.on("data", chunk => stdout.push(Buffer.from(chunk)));
+  child.stderr?.on("data", chunk => stderr.push(Buffer.from(chunk)));
+  let cancelled = false;
+  let forced = false;
+  let forceTimer = null;
+  const cancellationPoll = setInterval(async () => {
+    if (cancelled || !await exists(value.cancellationPath)) return;
+    cancelled = true;
+    child.kill("SIGTERM");
+    forceTimer = setTimeout(() => { forced = true; child.kill("SIGKILL"); }, 2_000);
+    forceTimer.unref?.();
+  }, 50);
+  cancellationPoll.unref?.();
+
+  let npmExitCode = null;
+  let spawnError = null;
+  try {
+    npmExitCode = await new Promise((resolvePromise, rejectPromise) => {
+      child.once("error", rejectPromise);
+      child.once("close", code => resolvePromise(code));
+    });
+  } catch (error) {
+    spawnError = error;
+  } finally {
+    clearInterval(cancellationPoll);
+    clearInterval(heartbeat);
+    if (forceTimer) clearTimeout(forceTimer);
+  }
+
+  const targetReady = await installedTargetIsCallable(value);
+  let launcherDisposition = "unavailable";
+  let outcome = "failed";
+  if (targetReady) {
+    launcherDisposition = "target";
+    outcome = "installed";
+  } else {
+    await writeRecoveryLaunchers(value);
+    if (await recoveryLaunchersAreCallable(value)) {
+      launcherDisposition = "recovery";
+      outcome = "recovery-launcher";
+    }
+  }
+  await writeJson(value.resultPath, {
+    schema: SCHEMA,
+    transactionId: value.transactionId,
+    outcome,
+    npmExitCode,
+    cancelled,
+    launcherDisposition,
+    stdout: bounded(Buffer.concat(stdout).toString("utf8")),
+    stderr: bounded(`${Buffer.concat(stderr).toString("utf8")}${spawnError ? `\n${String(spawnError)}` : ""}${forced ? "\nforced npm termination after cancellation" : ""}`.trim()),
+    completedAt: new Date().toISOString(),
+  });
+  if (launcherDisposition === "unavailable") process.exitCode = 1;
+}
+
+async function runRecoveredCommand(value, arguments_) {
+  let entry = await installedTargetEntry(value);
+  if (entry === null && arguments_[0] === "update") {
+    await rm(value.cancellationPath, { force: true });
+    await rm(value.resultPath, { force: true });
+    await rm(value.ownerPath, { force: true });
+    const worker = spawn(process.execPath, [fileURLToPath(import.meta.url), "--worker", manifestPath], {
+      detached: true,
+      windowsHide: true,
+      stdio: "ignore",
+    });
+    worker.unref();
+    const deadline = Date.now() + 15 * 60 * 1000;
+    const requestCancellation = signal => { void writeJson(value.cancellationPath, { schema: SCHEMA, transactionId: value.transactionId, signal, requestedAt: new Date().toISOString() }); };
+    const onSigint = () => requestCancellation("SIGINT");
+    const onSigterm = () => requestCancellation("SIGTERM");
+    process.on("SIGINT", onSigint);
+    process.on("SIGTERM", onSigterm);
+    try {
+      while (Date.now() < deadline && !await exists(value.resultPath)) await sleep(50);
+    } finally {
+      process.off("SIGINT", onSigint);
+      process.off("SIGTERM", onSigterm);
+    }
+    entry = await installedTargetEntry(value);
+  }
+  entry ??= resolve(value.priorReleaseRoot, "bin", "cli.js");
+  const child = spawn(process.execPath, [entry, ...arguments_], { stdio: "inherit", windowsHide: false });
+  return await new Promise(resolvePromise => {
+    child.once("error", error => { console.error(error instanceof Error ? error.message : String(error)); resolvePromise(1); });
+    child.once("close", code => resolvePromise(code ?? 1));
+  });
+}
+
+async function readCapsule(path) {
+  const value = JSON.parse(await readFile(path, "utf8"));
+  if (value.launchContract !== "neutral-launch-v1") throw new Error("Unsupported private recovery contract; stop existing processes and install directly with npm. Preserve settings, sessions, and history.");
+  if (value.schema !== SCHEMA || typeof value.transactionId !== "string" || typeof value.packageName !== "string"
+    || typeof value.packageName !== "string" || !value.packageName.includes("/") || typeof value.targetVersion !== "string" || typeof value.packageRoot !== "string" || typeof value.globalRoot !== "string"
+    || typeof value.launcherRoot !== "string" || !Array.isArray(value.launchers) || typeof value.priorReleaseId !== "string" || typeof value.priorReleaseRoot !== "string"
+    || !/^[a-f0-9]{64}$/.test(value.priorContentDigest) || typeof value.releaseManifestName !== "string"
+    || typeof value.recoveryEntry !== "string" || typeof value.recoveryEntryDigest !== "string" || value.nodeExecutable !== process.execPath || typeof value.npmCli !== "string"
+    || !Array.isArray(value.npmArguments) || typeof value.resultPath !== "string" || typeof value.cancellationPath !== "string") {
+    throw new Error("invalid A1 update recovery capsule");
+  }
+  const lexicalCapsuleRoot = dirname(resolve(path));
+  if (lexicalCapsuleRoot.split(sep).at(-1) !== value.transactionId) throw new Error("A1 update recovery transaction path is invalid");
+  const capsuleRoot = await realpath(lexicalCapsuleRoot);
+  const entry = await realpath(value.recoveryEntry);
+  assertDirectChild(capsuleRoot, entry);
+  if (!samePath(entry, resolve(capsuleRoot, "recovery.js"))) throw new Error("A1 update recovery entry path is invalid");
+  const digest = createHash("sha256").update(await readFile(entry)).digest("hex");
+  if (digest !== value.recoveryEntryDigest) throw new Error("A1 update recovery payload digest mismatch");
+  const globalRoot = await realpath(value.globalRoot);
+  const packageRoot = await realpath(value.packageRoot).catch(() => resolve(value.packageRoot));
+  const expectedPackage = resolve(globalRoot, ...value.packageName.split("/"));
+  if (!samePath(packageRoot, expectedPackage) || !containedBy(globalRoot, packageRoot)) throw new Error("A1 update recovery package root escapes npm global root");
+  const expectedNpmArguments = ["install", "--global", "--loglevel=error", "--no-fund", "--no-audit", `${value.packageName}@${value.targetVersion}`];
+  if (JSON.stringify(value.npmArguments) !== JSON.stringify(expectedNpmArguments)) throw new Error("A1 update recovery npm arguments are invalid");
+  const launcherRoot = resolve(value.launcherRoot);
+  const expectedLaunchers = process.platform === "win32"
+    ? [resolve(launcherRoot, "a1"), resolve(launcherRoot, "a1.cmd"), resolve(launcherRoot, "a1.ps1")]
+    : [resolve(launcherRoot, "a1")];
+  if (JSON.stringify(value.launchers.map(path => resolve(path))) !== JSON.stringify(expectedLaunchers)) throw new Error("A1 update recovery launcher set is invalid");
+  for (const launcher of value.launchers) assertDirectChild(launcherRoot, resolve(launcher));
+  const expectedSidecars = [resolve(lexicalCapsuleRoot, "cancel.json"), resolve(lexicalCapsuleRoot, "result.json"), resolve(lexicalCapsuleRoot, "owner.json")];
+  if (![value.cancellationPath, value.resultPath, value.ownerPath].every((candidate, index) => samePath(candidate, expectedSidecars[index]))) {
+    throw new Error("A1 update recovery sidecar paths are invalid");
+  }
+  const dataDir = dirname(dirname(capsuleRoot));
+  const releasesRoot = await realpath(resolve(dataDir, "releases"));
+  const priorReleaseRoot = await realpath(value.priorReleaseRoot);
+  assertDirectChild(releasesRoot, priorReleaseRoot);
+  if (priorReleaseRoot.split(sep).at(-1) !== value.priorReleaseId) throw new Error("A1 update recovery prior release identity is invalid");
+  const priorManifest = JSON.parse(await readFile(resolve(priorReleaseRoot, value.releaseManifestName), "utf8"));
+  if (priorManifest.launchContract !== "neutral-launch-v1") throw new Error("Unsupported prior private launch contract; manual cutover is required.");
+  if (priorManifest.releaseId !== value.priorReleaseId || priorManifest.contentDigest !== value.priorContentDigest) {
+    throw new Error("A1 update recovery prior release manifest is invalid");
+  }
+  const npmMetadata = await lstat(value.npmCli);
+  if (!npmMetadata.isFile() || npmMetadata.isSymbolicLink()) throw new Error("A1 update recovery npm entry is invalid");
+  return value;
+}
+
+async function installedTargetEntry(value) {
+  try {
+    const manifest = JSON.parse(await readFile(resolve(value.packageRoot, "package.json"), "utf8"));
+    const entry = resolve(value.packageRoot, "bin", "cli.js");
+    if (manifest.privateLaunchContract !== "neutral-launch-v1" || manifest.name !== value.packageName || manifest.version !== value.targetVersion || !(await lstat(entry)).isFile()) return null;
+    return entry;
+  } catch { return null; }
+}
+
+async function installedTargetIsCallable(value) {
+  if (await installedTargetEntry(value) === null) return false;
+  const token = `node_modules/${value.packageName}/bin/cli.js`;
+  for (const path of value.launchers) {
+    try {
+      const metadata = await lstat(path);
+      if (!metadata.isFile() || metadata.isSymbolicLink()) return false;
+      if (process.platform !== "win32" && (metadata.mode & 0o111) === 0) return false;
+      const normalized = (await readFile(path, "utf8")).replaceAll("\\", "/");
+      if (!normalized.includes(token)) return false;
+    } catch { return false; }
+  }
+  return true;
+}
+
+async function writeRecoveryLaunchers(value) {
+  const node = value.nodeExecutable ?? process.execPath;
+  const entry = value.recoveryEntry;
+  const manifest = manifestPath;
+  const shell = `#!/bin/sh\nexec ${shellQuote(node)} ${shellQuote(entry)} --launch ${shellQuote(manifest)} -- "$@"\n`;
+  const command = `@ECHO off\r\n"${node}" "${entry}" --launch "${manifest}" -- %*\r\n`;
+  const powershell = `& '${psQuote(node)}' '${psQuote(entry)}' --launch '${psQuote(manifest)}' -- $args\nexit $LASTEXITCODE\n`;
+  const content = process.platform === "win32" ? [shell, command, powershell] : [shell];
+  await mkdir(value.launcherRoot, { recursive: true });
+  for (let index = 0; index < value.launchers.length; index += 1) await atomicWrite(value.launchers[index], content[index], 0o755);
+}
+
+async function recoveryLaunchersAreCallable(value) {
+  for (const path of value.launchers) {
+    try {
+      const metadata = await lstat(path);
+      if (!metadata.isFile() || metadata.isSymbolicLink()) return false;
+      if (process.platform !== "win32" && (metadata.mode & 0o111) === 0) return false;
+      if (!(await readFile(path, "utf8")).includes(value.recoveryEntry)) return false;
+    } catch { return false; }
+  }
+  return true;
+}
+
+async function atomicWrite(path, content, mode) {
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  await writeFile(temporary, content, { mode });
+  await chmod(temporary, mode);
+  await rm(path, { force: true });
+  await rename(temporary, path);
+}
+
+async function writeJson(path, value) {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  const file = await open(temporary, "wx", 0o600);
+  try { await file.writeFile(JSON.stringify(value, null, 2)); await file.sync(); }
+  finally { await file.close(); }
+  await rm(path, { force: true });
+  await rename(temporary, path);
+}
+
+function samePath(left, right) {
+  return process.platform === "win32" ? resolve(left).toLowerCase() === resolve(right).toLowerCase() : resolve(left) === resolve(right);
+}
+function containedBy(parent, child) {
+  const fromParent = relative(parent, child);
+  return fromParent.length > 0 && fromParent !== ".." && !fromParent.startsWith(`..${sep}`) && !isAbsolute(fromParent);
+}
+function assertDirectChild(parent, child) {
+  const expectedParent = resolve(parent);
+  const actualParent = dirname(resolve(child));
+  const matches = process.platform === "win32" ? actualParent.toLowerCase() === expectedParent.toLowerCase() : actualParent === expectedParent;
+  if (!matches) throw new Error(`A1 update recovery path escapes its managed root: ${child}`);
+}
+function shellQuote(value) { return `'${String(value).replaceAll("'", `'"'"'`)}'`; }
+function psQuote(value) { return String(value).replaceAll("'", "''"); }
+function bounded(value) { return value.length <= 64 * 1024 ? value : value.slice(-64 * 1024); }
+async function exists(path) { return await lstat(path).then(() => true).catch(() => false); }
+async function sleep(ms) { await new Promise(resolvePromise => setTimeout(resolvePromise, ms)); }

package/bin/warmup.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+
+const startup = await import("../dist/foundation/startup/index.js");
+startup.assertImmutableWarmupEnvironment(process.env);
+startup.enableEnvironmentCompileCache(process.env);
+
+// 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 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/capabilities.d.ts

@@ -0,0 +1,6 @@
+/** The Pi comparison launch is a prerelease development instrument, not product. */
+export interface CliCapabilities {
+    readonly developmentComparison: boolean;
+}
+export declare function cliCapabilities(version: string): CliCapabilities;
+export declare function isPrereleaseVersion(version: string): boolean;

package/dist/{src/cli → cli}/capabilities.js

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

package/dist/{src/cli → 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>;
@@ -9,13 +10,26 @@ export interface CliHandlers {
     readonly packages: (request: PackageCommandRequest) => Promise<number>;
 }
 export interface CliOutput {
+    readonly stdout: (message: string) => void;
     readonly stderr: (message: string) => void;
 }
 export declare function cliUsage(capabilities: CliCapabilities): string;
+export declare function cliHelp(capabilities: CliCapabilities): string;
 export declare function dispatchCli(arguments_: readonly string[], handlers: CliHandlers, output: CliOutput, capabilities: CliCapabilities): Promise<number>;
 export type CliCommand = {
+    readonly kind: "noop";
+} | {
+    readonly kind: "help";
+} | {
+    readonly kind: "package-help";
+    readonly verb: PackageCliVerb;
+} | {
+    readonly kind: "package-error";
+    readonly diagnostic: PackageSyntaxDiagnostic;
+} | {
     readonly kind: "launch";
     readonly profileId: LaunchProfileId;
+    readonly sessionSelection?: SessionSelection;
 } | {
     readonly kind: "version";
 } | {