@timurproko/a1 0.1.8-dev.21b95d6 → 0.1.8-dev.226

package/README.md

@@ -6,111 +6,151 @@
 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)
-a1 update --models      # refresh A1's model catalogs
+# 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`.
+
 ## 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 pi install npm:pi-mcp-adapter   # install a package into ~/.a1/agent
-a1 pi remove npm:pi-mcp-adapter    # remove it again (alias: a1 pi uninstall)
-a1 pi list                         # list packages installed for a1
+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 of them
+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. Extension configuration is
-isolated too: for example, MCP configuration for bare `a1` belongs under
-`~/.a1/agent` (or the project), so `~/.pi/agent/mcp.json` is not read. Run
-`/mcp setup` inside bare `a1` to configure it; the MCP footer status appears
-when that A1 configuration contains a server.
+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.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
 ```
 
-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.
+The command lands the version on `develop` through a self-merging pull request,
+dispatches publication for that exact 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 the GitHub Release. `master`
+fast-forwards to the released commit, so it always points at what npm `latest`
+serves. A failed release leaves nothing behind: no tag, no GitHub Release, no
+moved branch.
 
-`docs/ci-release-runbook.md` has the full picture, including what happens when a
-publish fails partway.
+`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,8 +1,11 @@
 #!/usr/bin/env node
 
+const startup = await import("../dist/foundation/startup/index.js");
+startup.enableEnvironmentCompileCache(process.env);
+await startup.markStartupPhase(process.env, "guardian-start");
 const { fileURLToPath } = await import("node:url");
 const { resolve } = await import("node:path");
-const { runLaunchGuardian } = await import("../dist/src/foundation/launch-guardian/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";

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,5 +1,5 @@
 #!/usr/bin/env node
-import { runSupervisor } from "../dist/src/foundation/supervision/index.js";
+import { runSupervisor } from "../dist/foundation/supervision/index.js";
 
 runSupervisor().catch(error => {
   console.error(error instanceof Error ? error.stack ?? error.message : String(error));

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`);
+  }
+}