@timurproko/a1 0.1.8-dev.49ff83a → 0.1.8-dev.508

package/README.md

@@ -6,107 +6,210 @@
 npm install --global @timurproko/a1@latest
 ```
 
-## Commands
+Any channel can also be installed or updated directly with npm, without the
+`a1 update` commands:
 
 ```sh
-a1              # A1-owned UI and profile: ~/.a1/agent
-a1 version      # show Installed, Release (latest), and Next versions
-a1 update       # update to npm latest
-a1 update:next  # update to npm next (or a1 update:<commit> for a specific preview)
+# dev channel (next tag)
+npm install -g @timurproko/a1@next
+
+# stable release
+npm install -g @timurproko/a1@latest
+
+# exact version
+npm install -g @timurproko/a1@0.1.8-dev.107
+```
+
+## Use
+
+```sh
+a1                                      # launch A1 (profile: ~/.a1/agent)
+a1 --help                               # show all commands (short form: a1 -h)
+a1 --version                            # show the version (short form: a1 -v)
+a1 update                               # install the newest stable release
+a1 update --develop                     # install the current development preview
+a1 update --develop 107                 # install numbered preview 107
+a1 update --develop 0.1.8-dev.107       # install that exact preview
+a1 update --models                      # refresh A1's model catalogs
 ```
 
-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.
+Stable builds print only their installed version. Development builds also show the
+current development and stable channel versions.
+
+Development previews add the Pi comparison profile; release builds do not carry it.
 
 ```sh
-a1 pi           # untouched vanilla Pi oracle: ~/.pi/agent
-a1 sandbox      # unchanged isolated vanilla Pi profile: ~/.a1/sandbox
+a1 pi                                   # vanilla Pi oracle: ~/.pi/agent
 ```
 
+Unsupported commands exit quietly without launching anything. The removed
+`update:<preview>` forms are not aliases; use `update --develop`.
+
+## Agent input
+
+The agent prompt and Settings search share one input component: neutral white
+bars and an undimmed arrow matching submitted prompts. Thinking-level color is
+shown on the level name in the status bar, not on the input bars.
+
+In bare A1, **Ctrl+L cycles the thinking level**. **Shift+Tab is unassigned** and
+performs no agent-input action, including while a suggestion is visible. Model
+selection has **no default shortcut**; use `/model`. Explicit keybinding overrides
+remain configurable, and `/hotkeys` shows the resolved bindings. The `a1 pi`
+comparison profile keeps its original presentation and shortcuts.
+
+## Prompt suggestions
+
+Bare A1's `/settings` → Agent → Prompt suggestions controls faint next-prompt
+predictions. It is enabled by default and uses one additional background request
+with the selected model for eligible turns. Disabling it takes effect immediately.
+Tab accepts a suggestion as editable text; Enter submits it afterward. The setting
+remains stored in A1's profile, and `a1 pi` is unchanged.
+
+Suggestions use the selected model's lowest supported reasoning effort without
+changing your main thinking level. Clear next actions such as `archive it` are
+preferred when consistent with your intent; genuinely unclear cases can remain
+empty. [Private diagnostic capture](docs/architecture/prompt-suggestions.md)
+explains how to distinguish skipped, empty, rejected, and timed-out suggestions.
+
+## Quitting
+
+`/quit`, `Ctrl+C` twice, and `Ctrl+D` on an empty prompt end a bare A1 session.
+The last screen dissolves on the alternate screen, the terminal is restored once,
+and only the dim `To resume this session:` hint is printed; the conversation is
+not echoed into your scrollback. `/settings` → Quit chooses the effect (`fall`,
+`dissolve`, `starburst`, `waves`, or `off`) and its duration (300–2000 ms). The
+`a1 pi` comparison profile keeps Pi's `fullscreenExitOutput` behavior.
+
+## Prompt history
+
+Bare A1 recalls recent unique prompts across sessions with Up/Down. History is
+stored in a separate profile-local SQLite database at
+`~/.a1/data/history/<profile-id>.sqlite3`, or under `<A1_DATA_DIR>/history` when
+explicitly overridden. Other application data stays in its existing location.
+`/settings` → History controls persistence and the 10-100-entry limit (default
+100), effective on next start. The new default starts fresh: old platform history
+is neither imported nor automatically deleted. Ordinary upgrades and npm
+uninstall/reinstall preserve saved history. History is unencrypted user text;
+images are not reattached. See
+[prompt history](docs/features/prompt-history.md) for privacy, storage, and removal.
+
 ## 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.
+Pi extension packages install into A1's own profile (`~/.a1/agent`), so bare `a1`
+loads them and `a1 pi` does 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
+a1 pi install npm:pi-mcp-adapter   # install a package
+a1 pi remove npm:pi-mcp-adapter    # remove it (alias: a1 pi uninstall)
+a1 pi list                         # list installed packages
+a1 pi update --extensions          # update every installed package
+a1 pi update npm:pi-mcp-adapter    # update one
+a1 pi update --models              # refresh A1's model catalogs
 ```
 
-A running session loads a newly installed package after a restart. Pi's own
-profile at `~/.pi/agent` is managed by Pi itself.
+A1 pins the Pi runtime carried by each release, so Pi self-update forms are refused.
+Update A1 itself with `a1 update` or `a1 update --develop`.
+
+A running session picks up a newly installed package after a restart.
+Configuration is isolated the same way: bare `a1` reads `~/.a1/agent` (or the
+project), never `~/.pi/agent`. Configure MCP with `/mcp setup` inside bare `a1`.
 
 ## 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 `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 start               # build and launch a development `a1`
+npm run start:pi        # build and launch a development `a1 pi`
+npm run test:fast       # typecheck + fast suite (alias: npm test)
 npm run test:full       # complete non-physical suite
 ```
 
+Create every task worktree at `{working-dir}/.worktrees/<task-id>`, where
+`{working-dir}` is the session's initial working directory. For working directory
+`D:/Git/a1`, use `D:/Git/a1/.worktrees/<task-id>`—never a sibling such as
+`D:/Git/a1-<task-id>`. The primary worktree remains on `develop` for integration only.
+
+## Pull request integration
+
+Pull requests whose complete diff is only under `openspec/**`, under `docs/**`,
+exactly the root `README.md`, or a combination of those paths are automatically
+squash-merged after `Development validation required` succeeds. The automation
+reads the complete GitHub changed-file list, including both sides of renames, and
+runs only for trusted branches in this repository.
+
+Any other path makes the pull request code/operational. That includes source, tests,
+scripts, workflows, configuration, generated baselines, arbitrary root Markdown,
+and a mixed documentation-plus-code change. Those pull requests remain open after
+CI for local maintainer validation and explicit manual merge; automation disables
+auto-merge if it was armed. Documentation remains exempt from product builds and
+tests, but docs-sensitive generated governance and strict OpenSpec consistency are
+checked before integration.
+
+After any same-repository pull request into `develop` merges, trusted automation
+reconciles its remote topic branch. Human merges use the close-event workflow;
+documentation merges authored by `GITHUB_TOKEN` use a synchronous fallback because
+GitHub suppresses recursive workflow events. Both delete only an unprotected live
+ref that still equals the pull request's exact merged head SHA. Fork, advanced,
+reserved, protected, malformed, and unmerged refs are preserved and reported.
+
+Specification approval and implementation remain separate pull requests. An
+implementation starts from updated `origin/develop` only after its specification
+has merged and implementation was explicitly requested.
+
 ## Release
 
-Two channels, both published by CI from the exact bytes it validated. Nothing is
-ever published from a workstation.
+Two channels, both published by CI from the exact bytes it validated — never from
+a workstation.
 
-### Previews — npm `next`
+### Development previews
 
-Automatic. Every push to `develop` publishes one, versioned
-`<major.minor.patch>-dev.<short commit>` — the base from whatever `package.json`
-declares, the suffix naming the commit it was built from. It is stamped at publish
-time and never committed, so previews cost no commits and need no command, and an
-installed preview says exactly which source produced it.
+A preview is `<major.minor.patch>-dev.<pull-request number>`, e.g. `0.1.8-dev.107`.
+The nightly run (`03:17 UTC`) verifies current `origin/develop` and publishes only
+when that source's preview is absent. `npm run develop` requests the same GitHub
+Actions run and waits for it. The published version list is authoritative: an
+unpublished number is refused.
+
+Publish:
 
 ```sh
-a1 update:next      # install the newest preview
-a1 update:7eabe9e   # install the preview built from that commit
+npm run develop             # request the preview publish run and wait for it
 ```
 
-Naming a commit is what the version suffix is for: read it off `a1 version`, a
-pull request, or a commit list, and install exactly that build — you never need to
-know which version it went out under. A commit that was never published is refused
-rather than guessed at. A full preview version works in the same place, so a string
-pasted back from `a1 version` is understood too.
-
-### Stable — npm `latest`
-
-One command, from a clean `develop` that matches its remote:
+Install:
 
 ```sh
-npm run release -- patch     # 0.1.1        -> 0.1.2
-npm run release -- minor     # 0.1.1        -> 0.2.0
-npm run release -- major     # 0.1.1        -> 1.0.0
-npm run release -- 0.4.0     # an exact version
+a1 update --develop 107                 # install preview 107
+a1 update --develop 0.1.8-dev.107       # install that exact full preview version
 ```
 
-It lands the version on `develop` through a pull request that merges itself.
-**Landing it is what publishes** — the workflow builds, validates the packed release
-on Windows, Linux, and macOS, publishes to npm `latest` with provenance, and only
-then writes the `v<version>` tag and records the GitHub Release. The command waits
-for that to succeed, then opens the next `-dev` line so previews resume
-immediately.
+### Stable
 
 ```sh
-a1 update        # install the newest stable release
+npm run release -- patch     # 0.1.8-dev -> 0.1.8; already-stable 0.1.8 -> 0.1.9
+npm run release -- minor     # 0.1.8-dev -> 0.2.0
+npm run release -- major     # 0.1.8-dev -> 1.0.0
+npm run release -- 0.4.0     # an exact stable version
 ```
 
-After a stable publish, `master` fast-forwards to the released commit, so `master`
-always points at what npm `latest` serves while `develop` carries the work.
-
-A release that fails leaves nothing behind: no tag, no GitHub Release, no moved
-branch. Every version you can see somewhere is a version the registry actually
-serves. Release tags are protected from deletion and movement; a wrong tag is
-superseded by the next version, never repointed.
-
-`docs/ci-release-runbook.md` has the full picture, including what happens when a
-publish fails partway.
+Run from the repository root on a clean `develop` matching `origin/develop`.
+A target is required; bare `npm run release` displays usage and releases nothing.
+`patch` promotes the current prerelease rather than skipping its stable version.
+
+The command prepares a version-only PR in an isolated detached worktree, prints
+its URL, and waits for you to validate and **merge it manually**. Neither this PR
+nor the next-development PR is auto-merged, and green CI alone does not advance
+the release. After the stable PR merges, the command dispatches publication for
+that exact authoritative commit and waits for success. CI validates the packed
+release on Windows, Linux, and macOS, publishes to npm `latest` with provenance,
+then writes the `v<version>` tag and GitHub Release and fast-forwards `master`.
+
+Only after confirmed publication of `0.1.8` does the command prepare the separate
+`0.1.9-dev` PR. It reports development reopened only after you manually merge that
+PR too. Work added to your checkout during either wait is preserved, not reset.
+If publication fails or is uncertain, no reopening PR is prepared. If publication
+succeeded but reopening failed, inspect the reported phase and PR; do not republish
+the immutable stable version.
+
+`docs/ci-release-runbook.md` has the full picture.

package/bin/cli.js

@@ -1,38 +1,60 @@
 #!/usr/bin/env node
 
+const commandStartedAtMs = performance.timeOrigin + performance.now();
 const packageRoot = new URL("..", import.meta.url);
+// Invariant: one terminal module identity per process, decided before any A1 or Pi module loads.
+const [{ installPinnedPiTuiResolver }, { fileURLToPath: toPath }] = await Promise.all([import("./module-resolver.js"), import("node:url")]);
+installPinnedPiTuiResolver(toPath(packageRoot));
+const startup = await import("../dist/foundation/startup/startup-runtime.js");
+const startupProfile = process.argv[2] === "pi" ? "pi" : "a1";
+startup.initializeStartupTrace(process.env, startupProfile, commandStartedAtMs);
+startup.enableEnvironmentCompileCache(process.env);
+await startup.markStartupPhase(process.env, "command-invoked");
 const { fileURLToPath } = await import("node:url");
 const { readFile } = await import("node:fs/promises");
-const { cliCapabilities, dispatchCli } = await import("../dist/src/cli/index.js");
+const [{ cliCapabilities }, { dispatchCli }] = await Promise.all([
+  import("../dist/cli/capabilities.js"),
+  import("../dist/cli/dispatch.js"),
+]);
 
-// Which commands this build exposes follows from the build's own version, so a
+// Compatibility: 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 => {
-    const [{ prepareInteractiveLaunch }, { runBootstrap }] = await Promise.all([
-      import("../dist/src/features/launch/index.js"),
-      import("../dist/src/foundation/release/index.js"),
+    const [{ prepareInteractiveLaunch }, { runBootstrap }, { releaseCopyIsLaunchable }] = await Promise.all([
+      import("../dist/features/launch/prepare-launch.js"),
+      import("../dist/foundation/release/bootstrap.js"),
+      import("./module-identity.js"),
     ]);
+    const packageRootPath = fileURLToPath(packageRoot);
     const prepared = await prepareInteractiveLaunch(intent);
-    return await runBootstrap({ packageRoot: fileURLToPath(packageRoot), launchIntent: intent, environment: prepared.environment });
+    return await runBootstrap({
+      packageRoot: packageRootPath,
+      launchIntent: intent,
+      environment: prepared.environment,
+      releaseIsLaunchable: releaseCopyIsLaunchable,
+    });
   },
   version: async () => {
-    const { runVersionStats } = await import("../dist/src/cli/index.js");
+    const { runVersionStats } = await import("../dist/cli/version-stats.js");
     return await runVersionStats({ packageRoot: fileURLToPath(packageRoot) });
   },
   update: async (channel, target) => {
-    const { runSelfUpdate } = await import("../dist/src/foundation/release/index.js");
+    const { runSelfUpdate } = await import("../dist/foundation/release/update.js");
     return await runSelfUpdate({ packageRoot: fileURLToPath(packageRoot), channel, ...(target === undefined ? {} : { target }) });
   },
   packages: async request => {
-    const [{ runPackageCommand }, { createPiPackagesPort }] = await Promise.all([
-      import("../dist/src/cli/index.js"),
-      import("../dist/src/foundation/pi-engine-adapter/index.js"),
+    const [{ runPackageCommand }, identity] = await Promise.all([
+      import("../dist/cli/packages.js"),
+      import("./module-identity.js"),
     ]);
+    identity.configurePinnedPiPublicPackage(fileURLToPath(packageRoot));
+    const { createPiPackagesPort } = await import("../dist/integrations/pi/engine/package-integration.js");
     return await runPackageCommand(request, { createPort: createPiPackagesPort });
   },
 }, {
+  stdout: message => process.stdout.write(message),
   stderr: message => process.stderr.write(message),
 }, capabilities);

package/bin/guardian.js

@@ -1,19 +1,29 @@
 #!/usr/bin/env node
 
-const { fileURLToPath } = await import("node:url");
+const startup = await import("../dist/foundation/startup/startup-runtime.js");
+startup.enableEnvironmentCompileCache(process.env);
+await startup.markStartupPhase(process.env, "guardian-start");
 const { resolve } = await import("node:path");
-const { runLaunchGuardian } = await import("../dist/src/foundation/launch-guardian/index.js");
+const { parseSessionSelection } = await import("../dist/foundation/lifecycle/session-selection.js");
+const { runLaunchGuardian } = await import("../dist/foundation/launch-guardian/main.js");
 
-const releaseRoot = process.env.A1_RELEASE_ROOT ?? fileURLToPath(new URL("..", import.meta.url));
-const profileId = process.env.A1_LAUNCH_PROFILE ?? "a1";
+const { readLaunchContext } = await import("../dist/foundation/launch-context/index.js");
+const launchContext = readLaunchContext(process.env, "release");
+const releaseRoot = launchContext.releaseRoot;
+const profileId = readLaunchContext(process.env, "profile").launchProfile;
+// Invariant: the "release" and "profile" requirements above already refused an environment without
+// these values; the checks give the type checker the same certainty.
+if (releaseRoot === undefined || profileId === undefined) throw new Error("A1 launch context is incomplete");
 
-runLaunchGuardian({
+const sessionSelection = parseSessionSelection(process.argv.slice(2));
+Promise.resolve().then(() => runLaunchGuardian({
+  ...(sessionSelection === undefined ? {} : { sessionSelection }),
   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/module-identity.js

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