@first-tree-ai/context-tree 0.1.5 → 0.1.7-alpha.202609010710

package/docs/specification.md

@@ -1,146 +1,160 @@
-# Context Tree Format Specification
-
-## Repository and root
-
-A shared Context Tree lives in a `github.com` repository identified as
-`OWNER/REPO`. GitHub commit SHAs identify exact shared snapshots. The package
-still operates on local clones and worktrees because validation and editing are
-filesystem operations.
-
-The tree root is a real directory containing a regular, non-symlink `NODE.md`.
-That root node is both the tree manifest and the repository-wide context node.
-It must contain non-empty prose and schema-version-1 frontmatter:
-
-```yaml
----
-schemaVersion: 1
-title: "Service Context"
-description: "Durable decisions shared across service domains."
----
+# Context Tree lifecycle specification
+
+## Scope
+
+The package exposes setup as an orchestration skill over five concrete user
+intentions: create, connect, read, write, and publish. Supporting commands
+(`resolve`, `sync`, `list`, `prepare-write`, `finish-write`, `verify`, and
+`policy`) are plugin and integration plumbing. Every JSON contract is strict
+and uses `schemaVersion: 1`.
+
+## Shared invariants
+
+- Every core Git and GitHub subprocess uses one injectable runner. Errors redact
+  credential-bearing URLs, authorization values, and common GitHub token forms.
+- Repository arguments are validated `OWNER/REPO` identities. Credential-bearing
+  repository URLs are rejected and never logged.
+- A Git project canonicalizes to the exact current checkout root. Separate
+  clones and worktrees remain separate projects.
+- A non-Git project connection matches only its exact canonical directory.
+- Tree validation rejects symlink components, requires an exact clean Git root,
+  parses the root node, and requires full tree verification to succeed. An
+  unclean checkout is `DIRTY_TREE` and failed verification is `INVALID_TREE`;
+  neither is reported as a stale connection.
+- Stored `local` or `github` state remains that kind after connection; every
+  selected managed checkout is classified from a safe origin before storage.
+- Duplicate records for one project produce `CORRUPT_CONNECTION`.
+- Connections are persisted by an atomic replacement with mode `0600`. No
+  locking or schema migration is provided.
+
+## Result contracts
+
+```ts
+type Create = {
+  created: boolean; title: string; treePath: string; branch: string;
+  commitSha: string; schemaVersion: 1;
+};
+
+type Tree =
+  | { kind: "local"; path: string }
+  | { kind: "github"; path: string; repository: string };
+
+type Connection = { tree: Tree; schemaVersion: 1 };
+type ManagedTreeListing = {
+  schemaVersion: 1;
+  trees: Array<{ name: string; tree: Tree }>;
+};
+type Sync = { tree: Tree; branch: string; sha: string; schemaVersion: 1 };
+type Prepare = { worktreePath: string; schemaVersion: 1 };
+type Finish = { branch: string; sha: string; schemaVersion: 1 };
+type Publish = {
+  repository: string; url: string; branch: string; sha: string;
+  schemaVersion: 1;
+};
 ```
 
-Root-only `schemaVersion` is required and is not valid on domain nodes or
-Markdown leaves. A legacy `SCOPE.md` has no special meaning and is validated as
-an ordinary leaf.
-
-## Nodes and content classes
-
-The root requires the manifest fields above in `NODE.md`. Every semantic
-directory contains `NODE.md`, including `members/` and each member directory.
-Nodes and leaves require a non-empty `title`. Optional
-`description` is non-empty prose, and optional `soft_links` contains
-tree-root-relative Markdown files or node directories.
-
-- `normal`: root and durable domain decisions.
-- `member`: member-oriented context beneath `members/`.
-- `repo-infra`: dot paths, generated output, root `scripts/`, instructions, build, and CI files.
-
-`raw-context/` has no reserved meaning and follows ordinary node rules.
-Symlinks fail closed: they may not escape the tree, cross content-class
-boundaries, or stand in for domain directories. Repository infrastructure is
-excluded from semantic validation and reads.
-
-## Memory model
-
-The Context Tree itself is shared memory. Repository-wide memory belongs in the
-root `NODE.md`; domain memory belongs in the corresponding domain node or leaf.
-There is no reserved shared-memory directory or second store alongside the
-canonical domain tree. Add and split shared memory with the ordinary node
-policy.
-
-An agent's optional private memory lives at `members/<agent_slug>/memory.md`.
-The `members/` directory, agent directory, and memory file are all optional;
-when present, each directory requires its ordinary `NODE.md` index. Skills use
-`agent_slug` to avoid unrelated member content by default. Scaffolding does not
-create empty private memory files.
-
-Domain scope controls read relevance, not authorization. Shared tree memory is
-commonly readable but writes still require authorization from the user or host
-and follow the GitHub workflow. Member boundaries are relevance guidance only:
-the library and CLI apply no member-level access restriction, and the format
-claims no directory-level confidentiality.
-
-## Public contracts
-
-CLI JSON uses `schemaVersion: 1`. Version 1 was redefined before deployment;
-owner-bearing contracts have no compatibility layer. Exported strict Zod
-schemas are the source of truth for library and CLI wire contracts. Unknown
-output properties are rejected. Successful command results and runtime or
-argument failures emit one JSON object on stdout; help and version output remain
-plain text. An invalid `verify` report is still emitted and the command exits
-with status 1.
-
-`policy` returns `content` and `schemaVersion`. `read` returns the root, target,
-schema version, a selected node with its complete parsed frontmatter and body,
-and sorted immediate child summaries. `verify` returns
-the root, schema version, validity, findings, and content-class counts. None
-includes a tree digest or per-entry digest. The Git commit SHA is recorded by
-the surrounding host Git workflow rather than computed by the core.
-
-`link` and `resolve` return a strict link result containing the
-project identity and tree `OWNER/REPO` plus a canonical absolute, single-line
-checkout path. Link
-failures distinguish `NO_LINK`, `AMBIGUOUS_LINK`,
-`CORRUPT_LINK`, and `STALE_LINK` from other CLI failures.
-
-## Lifecycle
-
-Scaffolding creates exactly four files: root `NODE.md`, root `AGENTS.md`, root
-`CLAUDE.md`, and `.github/workflows/validate-context-tree.yml`. `AGENTS.md`
-explains the tree's purpose, structure, authority, and write discipline to
-agents entering the repository. `CLAUDE.md` is a relative symlink to `AGENTS.md`
-so both instruction filenames expose the same packaged guidance. The workflow
-is pinned to the package version that generated it. Init takes canonical `OWNER/REPO` and an
-optional absent or empty destination. It requires Git, runs ordinary `git init`, and uses the
-unborn branch selected by Git's effective `init.defaultBranch` configuration or
-compiled fallback. The generated workflow filters pushes to that exact branch.
-The local tree title and default destination name come from `REPO`. Init
-configures a credential-free `https://github.com/OWNER/REPO.git` origin. Init
-records an unambiguous current project link only in the machine-local links
-file and never embeds the source-project association in the tree.
-The core and CLI perform no authenticated GitHub operations.
-
-Internal links live at `~/.context-tree/connections.json`. A link
-maps a normalized Git project origin or a real non-Git directory to canonical
-tree `OWNER/REPO` and checkout path. Git lookup also confirms that the project
-origin matches the local record; non-Git lookup includes descendants.
-Zero or multiple matches fail, and a project cannot link to different tree
-repositories. Explicit linking requires a clean exact Git root, safe GitHub
-origin, and complete tree verification. Init may
-automatically link only its exact new uncommitted scaffold. Resolve rejects symlinked,
-dirty, moved, mismatched-origin, and invalid-root candidates, but parses only
-root `NODE.md` rather than scanning all semantic content. Full verification is
-the responsibility of read and write after refresh.
-
-A moved checkout produces `STALE_LINK`; explicit linking may replace its
-path only after verifying the same stored tree repository and proving the prior
-path absent, no longer an exact checkout, or occupied by another repository. A
-second live checkout cannot replace the stored path, even when the stored
-checkout is dirty. Relinking the same canonical path is idempotent.
-
-Link setup selects or clones a verified checkout and writes only the local link
-record. It never mutates or publishes the Context Tree repository.
-
-Reads and writes take only `agent_slug`, sourced from authoritative task role
-instructions. They resolve the current project, then discover the live default
-branch using `git ls-remote --symref origin HEAD`; branches are never configured
-or cached. The exact clean, non-symlink Git root and its credential-free GitHub
-`origin` remain the authorization boundary. Resolution selects a candidate and
-does not replace full semantic verification. Reads refresh fast-forward-only,
-validate, and report the commit SHA; authorized stale reads stay read-only.
-
-The package root exports `linkProject`, `resolveLink`,
-`readContextTreePolicy`, `readTree`, `scaffoldTree`, and `verifyTree`.
-Project identification, URL normalization, and the links-file storage
-schema are internal. Public strict CLI result schemas remain available from
-the schemas entrypoint.
-
-Writes fetch the discovered default branch through that checkout and edit an
-isolated worktree. One source comes from task context, not an invocation
-argument, and scopes one write and commit. The base and result must validate;
-publication first uses a non-force direct push to the discovered default branch.
-Concurrent updates are rebased, resolved from authorized evidence, and verified
-again with bounded retries. Explicit direct-push denial or exhausted retries
-uses a latest-base, conflict-free task-branch PR fallback that remains open.
-Invalid bases permit only explicitly requested validator-scoped repair, and the
-workflow never merges.
+Errors use `{ ok: false, error: { code, message }, schemaVersion: 1 }`.
+Lifecycle-specific codes are `NO_CONNECTION`, `CORRUPT_CONNECTION`,
+`STALE_CONNECTION`, `DIRTY_TREE`, `INVALID_TREE`, `WRITE_OUTDATED`,
+`GITHUB_AUTH`, `REPOSITORY_EXISTS`, and `PUBLISH_INCOMPLETE`. Other failures
+use `CONTEXT_TREE_FAILED`.
+
+## Creation and connection
+
+`create` derives `<normalized-project-directory>-context-tree` from the
+canonical project root. It scaffolds and commits the tree in the flat managed
+namespace before atomically connecting it. Repetition is idempotent only when
+the project is still connected to that tree. An occupied name otherwise fails
+with guidance to use `connect <name>`, and a project already connected to a
+different tree fails rather than being silently repointed. Files created by a
+failed create are removed; a destination that existed before the invocation is
+never removed.
+
+`connect <name>` performs an exact managed-directory lookup. `connect
+OWNER/REPO` reuses a matching checkout or clones it under the lowercased
+repository name. Every selection is validated and safely classified as local
+or GitHub state. Local-tree, repository, and unsafe-origin name collisions fail
+before the project connection changes. Explicit connection switches are
+automatic. Only a directory created by a failed clone is removed.
+
+`connect --tree-path <path>` attaches an exact, clean, fully valid Git root
+with no symlink components in place and never copies, moves, or deletes it.
+Trees without an origin classify as local state; credential-free GitHub
+origins classify as GitHub state; all other origins are rejected. Stored-
+connection validation accepts verified external paths while name-based
+discovery remains restricted to the managed namespace. `list` reports valid,
+clean managed trees as `{ schemaVersion: 1, trees: [{ name, tree }] }`; a
+missing managed directory is an empty list and is never created by listing.
+
+## Synchronization and reading
+
+Local synchronization makes no network call and reports the checked-out branch
+and exact `HEAD`. GitHub synchronization performs exactly one
+`git pull --ff-only origin <checked-out-branch>`, revalidates, then reports its
+exact SHA. It does not discover or enforce the remote default branch and does
+not report an `updated` flag.
+
+`read` returns a selected node and only its immediate indexed children. Callers
+navigate narrowly from indexes rather than scanning the semantic tree.
+
+## Writing
+
+`prepare-write` synchronizes and creates a random `context-tree/write/*` branch
+in an isolated worktree at the synchronized SHA. It returns only the worktree
+path and schema version; no token, registry, manifest, lock, or preparation
+record exists.
+
+`finish-write` requires that the supplied path is a real non-symlink directory,
+belongs to the connected tree's Git common directory, uses the reserved branch
+prefix, contains pending changes, and verifies as a complete Context Tree.
+Calling it authorizes all pending changes. It stages everything and creates one
+commit with `commit.gpgsign=false` while retaining the host Git identity.
+
+For local state it attempts one fast-forward merge into the connected checkout's
+current branch. For GitHub state it attempts one non-force push to that branch.
+Success removes the worktree and task branch. A non-fast-forward failure emits
+`WRITE_OUTDATED` and preserves both. There is no rebase, race loop, semantic
+conflict result, pull-request fallback, or abandoned-worktree cleanup.
+
+The write skill may prepare fresh and reapply the intended semantic change
+once after `WRITE_OUTDATED`. A second outdated result is reported to the user.
+
+## Publication
+
+`publish` requires stored local state, a clean valid tree, and no existing
+`origin`. By default it combines the authenticated GitHub login with the
+managed tree name; an explicit validated `OWNER/REPO` may override it.
+It runs one `gh repo create --private --source <tree> --remote origin --push`.
+
+After success, the connection is atomically updated to GitHub state. Clear
+authentication failures produce `GITHUB_AUTH`; clear name collisions produce
+`REPOSITORY_EXISTS`; uncertain or partial outcomes produce
+`PUBLISH_INCOMPLETE`. Publication does not inspect, adopt, repair, retry, or
+delete partial GitHub state. The GitHub operation and local connection update are not
+atomic.
+
+## Setup orchestration
+
+`context-tree-setup` is an orchestration skill over the five concrete
+workflows. It stops when the project is already connected; otherwise it asks
+whether to create a new tree or connect an existing one and delegates to the
+chosen workflow. Connect targets include listed managed names when any exist,
+plus GitHub `OWNER/REPO` and exact disk paths; without managed trees only
+GitHub and disk-path targets are offered. It never publishes without explicit
+user confirmation. `context-tree-read` and `context-tree-write` invoke setup
+when they receive `NO_CONNECTION`, then retry the operation once.
+
+## Hook and skills
+
+The session hook resolves the host-supplied `cwd` rather than its own process
+directory, and is silent without a valid connection, including unconnected
+sessions and payloads with no `cwd`; setup routing happens in the read and
+write skills, never in the hook. With a connection, it reports only
+`Context Tree connected at <path>`.
+
+Skills invoke the packaged CLI directly as
+`node "<skill-directory>/scripts/context-tree.mjs"` after checking `--version`.
+They rely on the packaged CLI and do not prescribe raw Git/GitHub operations.
+
+The skill inventory is setup, create, connect, read, write, and publish;
+setup orchestrates the five concrete workflows.

package/hooks/session-start.mjs

@@ -28,37 +28,28 @@ if (input.hook_event_name !== "SessionStart" && input.hook_event_name !== "Subag
 const pluginRoot = process.env.PLUGIN_ROOT ?? process.env.CLAUDE_PLUGIN_ROOT;
 const packagedCli = pluginRoot === undefined ? undefined : join(pluginRoot, "dist", "cli", "index.mjs");
 if (packagedCli === undefined || !existsSync(packagedCli)) {
-  process.stdout.write(JSON.stringify({ systemMessage: "Context Tree setup warning: packaged CLI is unavailable." }));
   process.exit(0);
 }
 const resolved = spawnSync(process.execPath, [packagedCli, "resolve", "--project-path", input.cwd], {
   encoding: "utf8",
   stdio: ["ignore", "pipe", "ignore"],
 });
+if (resolved.status !== 0) process.exit(0);
+
 let payload;
 try {
   payload = JSON.parse(resolved.stdout);
 } catch {
-  process.stdout.write(JSON.stringify({ systemMessage: "Context Tree setup warning: packaged CLI is unavailable." }));
-  process.exit(0);
-}
-
-if (resolved.status !== 0) {
-  const code = payload?.error?.code;
-  if (code === "NO_LINK") process.exit(0);
-  if (["AMBIGUOUS_LINK", "CORRUPT_LINK", "STALE_LINK"].includes(code)) {
-    process.stdout.write(JSON.stringify({ systemMessage: `Context Tree setup warning: ${payload.error.message}` }));
-  }
   process.exit(0);
 }
 
-const tree = payload?.link?.tree;
-if (typeof tree?.path !== "string" || typeof tree?.repository !== "string") process.exit(0);
+const tree = payload?.tree;
+if (typeof tree?.path !== "string") process.exit(0);
 process.stdout.write(
   JSON.stringify({
     hookSpecificOutput: {
+      additionalContext: `Context Tree connected at ${tree.path}`,
       hookEventName: input.hook_event_name,
-      additionalContext: `Context Tree ${tree.repository} is linked at ${tree.path}. Use the Context Tree skills for task-relevant durable context.`,
     },
   }),
 );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@first-tree-ai/context-tree",
-  "version": "0.1.5",
+  "version": "0.1.7-alpha.202609010710",
   "description": "Context Tree plugin for Codex and Claude Code, with a CLI for shell automation.",
   "type": "module",
   "license": "Apache-2.0",

package/policy/context-tree-policy.md

@@ -144,15 +144,13 @@ decision, not normal tree content. Keep tree prose current-state: no timeline,
 provenance, PR references, or implementation detail. `context-tree verify` must
 pass before any tree commit.
 
-Authorization comes from the user or host and is enforced through the GitHub
-workflow. Every write uses a freshly fetched exact supplied default branch in
-an isolated clean worktree and changes only necessary non-symlink Markdown.
-After verification and repository checks, publish the commit directly to that
-branch with a non-force push. Resolve concurrent updates by rebasing unpublished
-work onto the latest default branch, resolving evidence-determined conflicts,
-and verifying the complete result again. If direct publication is denied or
-bounded race retries are exhausted, open a conflict-free, non-force fallback PR
-against the supplied default branch and leave it open. Keep each source-backed
-write and commit scoped to one source artifact. An invalid base blocks semantic
-changes; only an explicit repair request may produce a repair-only write and
-commit limited to validator findings.
+Authorization comes from the user or host. Every write synchronizes the connected
+tree's checked-out branch and uses an isolated clean worktree at that exact
+commit. Invocation of the finishing operation authorizes all pending changes in
+that worktree. The lifecycle verifies, commits, and attempts one fast-forward
+merge or one non-force push. If the destination advanced, preserve the outdated
+worktree, prepare from current state, and reapply the intended semantic change
+once. Do not rebase, loop, push manually, or open a fallback pull request. Keep
+each source-backed write and commit scoped to one source artifact. An invalid
+base blocks semantic changes; only an explicit repair request may produce a
+repair-only write and commit limited to validator findings.

package/skills/context-tree-connect/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: context-tree-connect
+description: Connect the current project to an existing Context Tree by managed name, GitHub OWNER/REPO, or exact disk path. Use when the tree already exists; context-tree-setup delegates here once the user has chosen a target.
+license: Apache-2.0
+compatibility: Requires Node.js 22.13+ and the context-tree CLI JSON schema version 1.
+metadata:
+  author: first-tree-ai
+  version: "0.1.7-alpha.202609010710"
+---
+
+# Context Tree Connect
+
+Resolve `<skill-directory>` to this skill's directory and run
+`node "<skill-directory>/scripts/context-tree.mjs" --version` once per session.
+If the packaged CLI is unavailable, stop and ask the user to reinstall or
+update the plugin.
+
+Connect exactly one target supplied by the user:
+
+- A managed tree name or GitHub `OWNER/REPO`:
+  `node "<skill-directory>/scripts/context-tree.mjs" connect "<name-or-OWNER/REPO>"`.
+- An exact path to an existing Context Tree checkout:
+  `node "<skill-directory>/scripts/context-tree.mjs" connect --tree-path "<path>"`.
+  That checkout is attached where it already lives and is never copied, moved,
+  or deleted.
+
+Never accept a repository URL, and never infer, guess, or search the filesystem
+for a target yourself; pass through only what the user typed or confirmed. An
+explicit connect switches the project's connection. Report whether the
+connected tree is local or GitHub-backed, with its canonical path.
+
+If connection reports `INVALID_TREE` or `DIRTY_TREE`, report the failure and
+stop. The tree must be repaired or committed at its own location before it can
+be connected.

package/skills/context-tree-connect/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Context Tree Connect"
+  short_description: "Connect a project to an existing tree"
+  default_prompt: "Use $context-tree-connect with a managed name, OWNER/REPO, or exact disk path."

package/skills/context-tree-create/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: context-tree-create
+description: Create and connect a new managed local Context Tree for the current project. Use when the user wants a brand-new tree; context-tree-setup delegates here after confirming the project has none.
+license: Apache-2.0
+compatibility: Requires Node.js 22.13+ and the context-tree CLI JSON schema version 1.
+metadata:
+  author: first-tree-ai
+  version: "0.1.7-alpha.202609010710"
+---
+
+# Context Tree Create
+
+Resolve `<skill-directory>` to this skill's directory and run
+`node "<skill-directory>/scripts/context-tree.mjs" --version` once per session.
+If the packaged CLI is unavailable, stop and ask the user to reinstall or
+update the plugin.
+
+Run `node "<skill-directory>/scripts/context-tree.mjs" create`. Report whether
+the managed tree was created or already existed, together with its name, path,
+and exact commit SHA.
+
+The managed name is derived from the project directory's name. If that name is
+already taken, or the project is already connected to a different tree, report
+the `connect` command the error supplies and stop. Do not replace or remove the
+existing managed tree or connection.
+
+After the tree is created or reused, run
+`node "<skill-directory>/scripts/context-tree.mjs" resolve`. When the tree is
+local, ask the user whether to publish it as a private GitHub repository. An
+explicit prior request to publish counts as confirmation; otherwise a "no"
+leaves the tree local, and a "yes" delegates to `$context-tree-publish`. Never
+publish without that confirmation.

package/skills/context-tree-create/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Context Tree Create"
+  short_description: "Create managed durable project context"
+  default_prompt: "Use $context-tree-create to start a new tree for this project."

package/skills/context-tree-publish/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: context-tree-publish
+description: Publish the current project's local Context Tree as a new private GitHub repository. Use only when the user explicitly asks to publish or share the tree.
+license: Apache-2.0
+compatibility: Requires Node.js 22.13+ and the context-tree CLI JSON schema version 1.
+metadata:
+  author: first-tree-ai
+  version: "0.1.7-alpha.202609010710"
+---
+
+# Context Tree Publish
+
+Resolve `<skill-directory>` to this skill's directory and run
+`node "<skill-directory>/scripts/context-tree.mjs" --version` once per session.
+If the packaged CLI is unavailable, stop and ask the user to reinstall or
+update the plugin.
+
+Run `node "<skill-directory>/scripts/context-tree.mjs" publish`. When the user
+explicitly supplies an alternative, append the validated `OWNER/REPO` argument.
+Never accept a repository URL.
+
+Publication creates one new private repository, and the local connection update
+that follows is not part of the same atomic step. If it reports
+`PUBLISH_INCOMPLETE`, do not inspect, adopt, repair, retry, or delete partial
+state; report the uncertain outcome. If it reports `INVALID_TREE`, run `verify`
+and report its findings.

package/skills/context-tree-publish/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Context Tree Publish"
+  short_description: "Publish durable context privately"
+  default_prompt: "Use $context-tree-publish to share this project's tree privately."

package/skills/context-tree-publish/scripts/context-tree.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { lstatSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PACKAGE_NAME = "@first-tree-ai/context-tree";
+const REINSTALL_MESSAGE = "Context Tree packaged CLI is unavailable. Reinstall or update the Context Tree plugin.";
+
+function packagedCli() {
+  try {
+    const packageRoot = realpathSync(resolve(dirname(fileURLToPath(import.meta.url)), "../../.."));
+    const packageJson = resolve(packageRoot, "package.json");
+    const cli = resolve(packageRoot, "dist/cli/index.mjs");
+    if (lstatSync(packageJson).isSymbolicLink() || !lstatSync(packageJson).isFile()) return undefined;
+    if (JSON.parse(readFileSync(packageJson, "utf8")).name !== PACKAGE_NAME) return undefined;
+    if (lstatSync(cli).isSymbolicLink() || !lstatSync(cli).isFile()) return undefined;
+    const realCli = realpathSync(cli);
+    const containedPath = relative(packageRoot, realCli);
+    return containedPath !== "" && !containedPath.startsWith("..") && !isAbsolute(containedPath) ? realCli : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function forward(result) {
+  if (result.error !== undefined) {
+    process.stderr.write(`${REINSTALL_MESSAGE}\n`);
+    process.exit(1);
+  }
+  if (result.signal !== null) process.kill(process.pid, result.signal);
+  process.exit(result.status ?? 1);
+}
+
+const cli = packagedCli();
+if (cli === undefined) {
+  process.stderr.write(`${REINSTALL_MESSAGE}\n`);
+  process.exit(1);
+}
+forward(spawnSync(process.execPath, [cli, ...process.argv.slice(2)], { stdio: "inherit" }));