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

package/README.md

@@ -6,107 +6,201 @@
 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.
+
+## 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,56 @@
 #!/usr/bin/env node
 
+const commandStartedAtMs = performance.timeOrigin + performance.now();
 const packageRoot = new URL("..", import.meta.url);
+const startup = await import("../dist/foundation/startup/index.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 import("../dist/cli/index.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 }, { healModuleIdentityAtLaunch, releaseCopyIsLaunchable }] = await Promise.all([
+      import("../dist/features/launch/index.js"),
+      import("../dist/foundation/release/index.js"),
+      import("./module-identity.js"),
     ]);
+    // Compatibility: self-heal the installed tree before the release store copies it: npm 12
+    // blocks install scripts by default, so the postinstall that normally
+    // repairs module identity may never have run (see bin/module-identity.js).
+    const packageRootPath = fileURLToPath(packageRoot);
+    await healModuleIdentityAtLaunch(packageRootPath, message => process.stderr.write(message));
     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/index.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/index.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"),
+      import("../dist/cli/index.js"),
+      import("../dist/integrations/pi/engine/index.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,25 @@
 #!/usr/bin/env node
 
-const { fileURLToPath } = await import("node:url");
+const startup = await import("../dist/foundation/startup/index.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/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";
+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;
 
-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/module-identity.js

@@ -14,18 +14,20 @@
  * 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.
+ * subpath import `#pi-tui`, resolving to bin/pi-tui.js — a proxy that
+ * re-exports pinned Pi's nested copy. The hop through the proxy is load-bearing:
+ * Node rejects package-imports targets containing a `node_modules` path segment
+ * (Invalid Package Target) and silently falls through to any fallback, which is
+ * exactly how an earlier alias that named the nested path directly reintroduced
+ * the split while appearing to declare the opposite. A plain import specifier
+ * inside a module carries no such restriction.
  *
- * 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.
+ * What remains here is the check that it worked. The alias is resolved by
+ * asking Node itself — never by reimplementing resolution, which is how the
+ * earlier check reported "unified" for a target Node had rejected — and the
+ * proxy hop is followed to the module it re-exports. When that disagrees with
+ * what pinned Pi resolves, launch says so, 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
@@ -39,32 +41,41 @@ import { pathToFileURL } from "node:url";
 /**
  * What A1's own modules resolve `#pi-tui` to, as a real path.
  *
- * The alias is read from the manifest and its entries tried in order, which is
- * what Node does for a subpath import: a relative target is a file within the
- * package, and a bare one goes through ordinary resolution. Asking Node
- * directly is not an option here — `import.meta.resolve` ignores the parent it
- * is given unless an experimental flag is set, so it would always answer for
- * the running process rather than for the installation being inspected.
+ * Node answers for the alias itself (require.resolve honors package imports for
+ * the package the parent belongs to). When the answer is A1's proxy file, the
+ * module it re-exports is what A1 actually renders with, so the proxy's one
+ * static `export * from` specifier is followed to its target.
  */
 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;
-    }
+  const requireFromRoot = createRequire(pathToFileURL(join(packageRoot, "package.json")).href);
+  let resolved;
+  try {
+    resolved = requireFromRoot.resolve("#pi-tui");
+  } catch (error) {
+    throw new Error(`#pi-tui does not resolve: ${message(error)}`);
   }
-  throw new Error(`no #pi-tui target resolves: ${targets.join(", ")}`);
+  return canonical(followProxyReExport(resolved));
+}
+
+/**
+ * Follow A1's proxy hop: one relative `export * from "..."` per file, at most
+ * one hop. A resolution that is not the proxy (or any file without such a
+ * re-export) is returned as-is.
+ */
+function followProxyReExport(resolvedPath) {
+  let source;
+  try {
+    source = readFileSync(resolvedPath, "utf8");
+  } catch {
+    return resolvedPath;
+  }
+  const reExport = source.match(/^export \* from "(\.\.?\/[^"]+)";?$/m);
+  if (!reExport) return resolvedPath;
+  const target = join(dirname(resolvedPath), reExport[1]);
+  if (!existsSync(target)) {
+    throw new Error(`#pi-tui proxy ${resolvedPath} re-exports a missing file: ${target}`);
+  }
+  return target;
 }
 
 /**
@@ -76,7 +87,7 @@ function resolveOwnPiTui(packageRoot) {
  * no CommonJS condition, so an ordinary require cannot name it. From there a
  * require resolves pi-tui, which publishes no `exports` map at all.
  */
-function resolvePinnedPiTui(packageRoot) {
+export function resolvePinnedPiTui(packageRoot) {
   let directory = packageRoot;
   while (true) {
     const candidate = join(directory, "node_modules", "@earendil-works", "pi-coding-agent");
@@ -121,6 +132,29 @@ function message(error) {
   return error instanceof Error ? error.message : String(error);
 }
 
+/**
+ * Launch-entry self-heal: when A1 and pinned Pi disagree on the terminal
+ * module, rewrite the proxy to the copy Pi resolves before anything copies
+ * this tree. npm 12 blocks install scripts unless allowScripts covers the
+ * package, so the postinstall that normally rewrites the proxy may never
+ * have run and the installed tree may still carry the published placeholder
+ * path. Named neutrally so the launch entries that call it stay free of
+ * terminal implementation identifiers, as the bootstrap boundary requires.
+ */
+export async function healModuleIdentityAtLaunch(packageRoot, warn) {
+  if (inspectPiTuiModuleIdentity(packageRoot).kind === "unified") return;
+  const { syncPiTuiProxy } = await import("./sync-pi-tui-proxy.js");
+  const outcome = syncPiTuiProxy(packageRoot);
+  if (outcome.kind === "unresolved") {
+    warn(`a1: could not point the terminal module proxy at pinned Pi's copy (${outcome.message}); extension UI may not render.\n`);
+  }
+}
+
+/** Whether a materialized release copy resolves one terminal module for both A1 and Pi. */
+export function releaseCopyIsLaunchable(releaseRoot) {
+  return inspectPiTuiModuleIdentity(releaseRoot).kind === "unified";
+}
+
 /** Launch-entry wrapper: warn on stderr when the two sides disagree. */
 export function assertSinglePiTuiModuleAtLaunch(packageRoot, warn) {
   const outcome = inspectPiTuiModuleIdentity(packageRoot);

package/bin/pi-tui.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Types for the `#pi-tui` proxy (see ./pi-tui.js): the alias resolves to that
+ * file, so TypeScript reads this declaration and follows it to pinned Pi's
+ * nested pi-tui copy — the same module the proxy re-exports at runtime.
+ */
+export * from "../node_modules/@earendil-works/pi-coding-agent/node_modules/@earendil-works/pi-tui/dist/index.d.ts";

package/bin/pi-tui.js

@@ -0,0 +1,28 @@
+/**
+ * The one pi-tui module A1 uses: pinned Pi's own copy.
+ *
+ * A1's `#pi-tui` alias resolves here, and this file re-exports the copy nested
+ * inside pinned Pi — the same one Pi's extension loader hands to extensions, so
+ * prototype patches and `instanceof` checks land on the classes A1 renders with.
+ *
+ * The alias cannot name that copy directly: Node rejects any package-imports
+ * target containing a `node_modules` path segment (Invalid Package Target) and
+ * silently falls through to the next entry, which resolves the hoisted root
+ * copy and reintroduces the two-identity split this file exists to prevent. A
+ * plain import specifier in a module carries no such restriction, so the hop
+ * through this file is what makes the nested copy nameable from the manifest.
+ *
+ * npm does not materialize one layout: `npm ci` keeps pinned Pi's shrinkwrapped
+ * nested copy, while a global install hoists pi-tui to the root and produces no
+ * nested copy. bin/sync-pi-tui-proxy.js therefore rewrites this file's one
+ * re-export on postinstall to whatever pinned Pi resolves in the tree npm
+ * actually built; the path below is the dev-checkout (`npm ci`) shape. When the
+ * target is missing anyway, this import fails loudly at launch instead of
+ * silently rendering without extension chrome, and bin/module-identity.js
+ * reports the same condition before the composition loads.
+ *
+ * This lives in bin/ (shipped, plain JS) because it names a path inside
+ * node_modules, which the Pi API boundary policy rightly forbids ordinary
+ * production code from doing.
+ */
+export * from "../node_modules/@earendil-works/pi-coding-agent/node_modules/@earendil-works/pi-tui/dist/index.js";

package/bin/release-cleanup.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+const { runReleaseCleanupWorker } = await import("../dist/foundation/release/index.js");
+
+runReleaseCleanupWorker().catch(error => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});

package/bin/supervisor.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import { runSupervisor } from "../dist/src/foundation/supervision/index.js";
+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;
 });