feat(context-tree): adopt the external context-tree CLI behind context_tree.repository

[ggordonhall]

Bundles @first-tree-ai/context-tree ^0.1.12 and uses context_tree.repository to select external Context Tree skills for Claude and Codex. Other providers retain First Tree’s skills. Login installs the external skills, creates an accessible CLI shim, and connects existing workspaces.

Installation and rollback respect ownership. Login skips a host’s entire installation if any packaged-name skill is unowned or edited, reports the preserved paths, and continues with other hosts. Disabling external mode removes only recorded First Tree-created directories that still match the packaged payload. Independent official installs, customizations, and legacy copies without ownership evidence remain intact. The dependency’s transitive postinstall creates no home skills.

Repository inputs normalize to the dependency’s OWNER/REPO contract. Doctor reports invalid settings. Connections and managed trees survive rollback; only a First Tree-marked CLI shim is removed.

Codex workspace-only HOME isolation remains a documented limitation: login’s host-home connection is not visible in that environment. A cross-surface QA case is included at packages/qa/cases/cross-surface/external-context-tree-adoption.md; live provider QA has not been run.

Validation: pnpm check, pnpm typecheck, and 68 focused CLI tests pass for the latest fix, including repeated-login preservation for both independent and First Tree-owned customized skills. The full monorepo suite passed on the preceding revision using Node 24 and en_US.UTF-8; it was not rerun for this localized follow-up. No model-backed evals were run.

[github-actions]

All contributors are covered by the First Tree CLA.
_{Posted by the CLA Assistant Lite bot.}

[yuezengwu]

Reviewing exact head f2c44d594d0d1151f39052312333ffe0123a56dd.

The targeted tests and typecheck are green, but focused packaging/runtime QA found three release-blocking integration failures that the unit coverage does not exercise:

1. [P1] Adding the dependency activates unusable external Skills even when external mode is unset. @first-tree-ai/context-tree has a global-install postinstall. A scratch npm install --global of a parent package with this dependency (the same lifecycle shape as a global First Tree install) copied all six context-tree-* Skills into both ~/.claude/skills and ~/.codex/skills with no context_tree.repository configured. At the same time, npm exposed the dependency bin only at the parent's nested node_modules/.bin/context-tree; there was no context-tree in the global prefix bin. Every installed Skill starts by running context-tree ..., so the default/unset path both makes the two Skill families live and leaves the new one unable to execute. The ensureContextTreeSkills() config gate cannot prevent a dependency lifecycle script that already ran during package installation.

2. [P1] A connection made by login is invisible inside the Codex runtime. In a scratch home, connect first-tree-ai/opentag-context-tree --project-path <workspace> created <host-home>/.context-tree/connections.json, and resolve with that host HOME succeeded. Re-running the same packaged CLI with First Tree's real Codex app-server environment shape (HOME=<workspace>, CODEX_HOME=<host-home>/.codex, as built in workspace-sandbox.ts) returned NO_CONNECTION. The external CLI derives all state from os.homedir(), so login and the agent do not share the same state root; the advertised pre-link is ineffective and setup would start creating a second state root under the workspace.

3. [P1] External mode removes the working First Tree Skills for providers the external installer does not support. The bundled CLI's install --host all supports only claude and codex. With only .cursor / .grok / .kimi host directories present, its real JSON result was installed: [] and only claude / codex skips. However activeCoreSkillNames("external") removes Read/Write/Seed for every First Tree runtime provider, and the new test even exercises cursor while asserting only that the old Skills are absent. Cursor, Grok, Kimi, OpenCode, Amp, DeepSeek, and Pi can therefore receive a briefing that directs them to context-tree-read while no such discoverable Skill exists.

There is also a validation mismatch: First Tree accepts values such as owner/.. under its current OWNER/REPO regex, while the bundled CLI rejects them as not an explicit GitHub repository identity. Since the config value alone switches the runtime to external mode, this can stand down the working Skills for a repository the integration can never connect.

Validation completed: git diff --check; pnpm check (exit 0; existing warnings only); pnpm typecheck (9/9); targeted Shared 4/4, Client 70/70, and CLI 22/22 tests. Focused CLI QA also confirmed symlinked project paths and shell-like repository inputs fail closed without writes. Please add packaging/runtime-boundary coverage: an actual globally installed First Tree artifact, the effective provider environment, and at least one non-Claude/Codex provider.

[ggordonhall]

Thanks — this was a good catch on all three. I verified each against source before acting. Two are fixed, one is scoped and documented, and the validation nit turned out to be a real read-path bug rather than a cosmetic one.

Pushed as 653bbf204.

P1 #1 — fixed, and it was worse than filed

You filed the missing bin under "unusable when unset". It is also unusable when set, which makes it the most serious item in the review. Every installed Skill invokes bare context-tree; our own code resolves the bin through createRequire, but npm links only a top-level package's bin, never a transitive dependency's. The Agent's PATH is one we build ourselves from the channel CLI bin dir (agent-io.ts:126-134, workspace-sandbox.ts:347), which holds first-tree and not context-tree. So external mode never worked end-to-end in a packaged install.

login now writes a context-tree shim into that same directory. Two guards worth noting: a context-tree this CLI did not write is never overwritten and never removed on revert (a real npm i -g @first-tree-ai/context-tree lands its bin in exactly that directory and already satisfies the Skills), and an unwritable bin dir is reported with the remedy instead of failing the login.

P1 #3 — fixed

Confirmed: the bundled installer's host table contains exactly "claude" and "codex". effectiveContextSourceKind now narrows external to the supported providers, and projection, briefing, and admission all derive the kind through that one function — they have to agree, since admission compares the briefing byte-for-byte against the projection's active Skill set.

You were also right that the old test asserted too little. It exercised cursor while only checking the old Skills were absent, which is precisely the broken state. It now runs claude-code for the forwarding case and cursor for the fallback, asserting the full Skill set is retained.

The validation mismatch — fixed, and not cosmetic

I had this filed as cosmetic until I checked resolveConfigReadonly: it returns file values unvalidated, so the field's regex never applied on the read path at all. owner/.. would have switched the machine into external mode and stood down the working Skills. The pattern is now enforced in readContextTreeRepository itself, with the owner segment following GitHub's own rule.

P1 #2 — real mechanism, narrower blast radius; documented rather than fixed

env.HOME = realWorkspace appears only in buildWorkspaceOnlyEnvironment / buildWorkspaceOnlyAppServerEnvironment — Codex's opt-in workspace-only sandbox, gated by assertCodexWorkspaceOnlySupported. Claude does not rewrite HOME (claude/executable.ts:109 reads it), so a login-time connection is visible there. Since the first in-session context-tree-setup already handles NO_CONNECTION by design, I have documented this as a limitation of that one mode rather than reworking state-root resolution. Happy to treat it as blocking if you disagree on the scope.

On the packaging coverage request

I have not added a global-install CI matrix. Standing up a real globally installed artifact plus the effective provider environment is a fair ask for a release gate, but disproportionate for this MVP, and I would rather not add slow packaging infrastructure to land it. What I did add is narrow and fast: the shim landing in a scratch bin dir, the non-clobber guard, ledger-scoped removal (including the property that a Skill absent from the ledger survives), provider gating across all ten providers, and the regex table. Verification is pnpm check, pnpm typecheck 9/9, Shared 969/969, CLI green, Client 2853 passed with one pre-existing unrelated failure (login-shell-path.test.ts).

The end-to-end path this cannot cover — context-tree read from inside a live session, which is what actually proves the shim — is still unrun and flagged in the PR body as worth doing before merge.

One more note for the record, since it explains why this survived local testing: the machine I developed on has had a global @first-tree-ai/context-tree since 27 Aug, so context-tree was on PATH for reasons unrelated to the feature.

[yuezengwu]

Requesting changes on exact head 653bbf2048caaf4cd9f0338973025254b450e0c8.

Two release blockers remain in the new fix:

1. The default/unset path is still not reversible after a global First Tree install. The transitive dependency postinstall runs before first-tree login, installs all six context-tree-* Skills into both Claude and Codex, and creates no First Tree ledger. removeInstalledContextTreeSkills() deliberately removes nothing without that ledger, so an existing authenticated user who upgrades (or even reruns login with the key unset) keeps the unconfigured external Skills indefinitely. I reproduced the packaged postinstall in a scratch home: 6 Claude + 6 Codex Skills, ledgerExists: false. The new “removes nothing when there is no ledger” test confirms the cleanup cannot distinguish this dependency-owned state from a manual install. The unconditional dependency lifecycle side effect must be prevented or recorded at install time; a ledger created only after external mode is enabled cannot repair it.

2. CONTEXT_TREE_REPOSITORY_PATTERN still does not match the bundled CLI schema. First Tree accepts owner/-repo, owner/_repo, owner/.hidden, and owner/foo.git; the bundled context-tree connect rejects every one as not an explicit GitHub OWNER/REPO identity. These values still switch the runtime into external mode and can stand down the working Skills. Please use the same repository-name contract as the dependency (leading alphanumeric, max 100, and no .git suffix) and add the boundary cases.

The current exact-head GitHub CI also has deterministic integration failures that need reconciliation before merge: Client/Web fails because the shipped briefing now has four welcome rows while first-tree-welcome still requires exactly three, and Lint & Type Check fails because the current PR merge ref leaves the Antigravity SessionContext fixture missing a required field. The Server failure appears unrelated/flaky, but the two above are direct merge-state failures.

Local validation on the detached head: targeted Shared/Client/CLI suites 42/42, repository typecheck 9/9, pnpm check exit 0 (existing warnings), and git diff --check pass. The packaged postinstall boundary probe and the real bundled CLI rejection probe produced the failures above.

[ggordonhall]

I have read the CLA Document and I hereby sign the CLA

[ggordonhall]

recheck

[yuezengwu]

Reviewed exact head 896d572cacbf8efd8057178a0cd6a6dd2a7be95c. Context baseline: first-tree-ai/opentag-context-tree@d0abc83bc2a07d7a0d4e393ec45a57d37feccd65.

[P1] An ordinary login with external mode never enabled deletes independently installed user Skills. At apps/cli/src/core/context-tree-cli.ts:377-382, an absent or unusable setting unconditionally reaches uninstall --host all (:319). The external CLI's prefix-based uninstall is not evidence that First Tree installed those directories or owns the user's edits.

I reproduced this against the bundled 0.1.9 CLI and the actual ensureContextTreeSkills() function in an isolated home: the only config was the server URL, no installation ledger existed, and external mode had never been enabled. A user-authored .claude/skills/context-tree-personal/SKILL.md and a customized, manually installed .codex/skills/context-tree-read/SKILL.md were both removed; .claude/skills/personal-helper/SKILL.md remained. The function returned status: removed. No real account home or login service was used.

Please make never-enabled/unconfigured operation a no-op for independently owned files, and restrict rollback to verifiably First Tree-installed, unmodified artifacts. Any migration that deliberately removes manual installations needs an explicit operator action/consent, not a successful login. The PR description and tests asserting prefix ownership do not establish that consent. Keep the no-ledger/manual-install case as a preservation regression test rather than asserting deletion.

The previous repository-validation finding is fixed. The leading punctuation and repeated-suffix cases are rejected, supported URL forms normalize to OWNER/REPO, and config tests pass. The 0.1.9 postinstall now also has a direct-global-install guard: I exercised its exact script in an npm-shaped nested dependency path with the global flag set; it printed the manual-install instruction and created no Skills. That guard does not justify the unconditional login cleanup above.

Current CI failure is separate and base-originated. Lint & Type Check checked merge commit 0be974c17f494f33030838a029a3ac9997e5c372 (parents 38752415320c97c0bd122aa4afb13c3ff60b1b06 and this PR head). The error is TS2322 at packages/client/src/providers/antigravity/__tests__/handler.test.ts:84: its SessionContext fixture lacks required noteTurnStart. Both that fixture and the defining runtime/handler.ts are identical between current main and the CI merge tree; the Antigravity test is absent from the PR head itself. This is not a Context Tree regression. It still needs a green merge check after the base-side fix; I did not rerun CI or modify either branch.

Fresh local validation on this head: diff-check and pnpm check pass; uncached CLI/dependency build 3/3 and monorepo typecheck 9/9 pass; shared config 35/35, CLI Context Tree/doctor/login 47/47, client source/briefing/preparation 89/89, and no-model welcome floor 21/21 pass. The deletion probe establishes the blocker despite those green assertions. No model-backed eval or full live-provider QA is claimed.

[yuezengwu]

Exact-head re-review of 550e86ebcb1b7a90ca333f025268d21883d17e09.

The new comparison preserves hand-authored prefix-sharing skills and edited packaged skills, but it does not establish who installed an unmodified official copy. The inline ownership finding remains blocking.

Independent reproduction on this head, with the actual pinned Context Tree 0.1.9 CLI and an isolated account/First Tree home/PATH:

1. Leave context_tree.repository unset and never invoke First Tree's external-mode installer.
2. Independently run the packaged context-tree install --host all as an operator; both host homes receive the six official skills.
3. Invoke the actual ensureContextTreeSkills() used by ordinary login.
4. Result: status=removed, all 12 independently installed official skill directories are removed. A separate hand-authored context-tree-personal control and a foreign global CLI binary are preserved.

Content identity is not installer provenance. This can still disable an independently managed Context Tree installation for other projects just by logging into First Tree. Please preserve/report unowned official copies unless the operator explicitly requests cleanup; remove only artifacts with First Tree ownership evidence. Any legacy orphan cleanup needs its own explicit scope rather than treating every identical official copy as an orphan. Add a regression case for this independent, unmodified official install, not only for edited copies.

Verification: git diff --check, pnpm check, uncached build (5 tasks), uncached typecheck (9 tasks), and 215 focused tests passed (CLI 70, client 89, shared 35, no-model skill floor 21). No branch changes were made; this is not a claim of full live/provider QA.

CI is separately still red: Lint & Type Check reports the Antigravity SessionContext fixture missing noteTurnStart at packages/client/src/providers/antigravity/__tests__/handler.test.ts:84. The job checked out synthetic merge ede9539c9815c996defdb88d70e4dd0b30149b88, combining main 38752415320c97c0bd122aa4afb13c3ff60b1b06 with this PR head. The fixture blob is identical in that merge and its main parent (431c36a360b71d7cd93df362f97a7200b7cc476c) and is absent from the pure PR head. This is a main-side integration blocker, not a failure introduced by this two-file revision, and a green PR-head typecheck does not make the merge gate green.

Non-blocking documentation follow-up: the PR description and external-mode CLI reference still describe prefix-wide uninstall --host all, which no longer matches this implementation.

[yuezengwu]

[P1] Do not equate identical official payloads with First Tree ownership

An operator can independently install the official Context Tree 0.1.9 skills, never enable context_tree.repository, and then lose all six skills in both Claude and Codex homes on an ordinary First Tree login. I reproduced exactly that with the real package: this byte comparison succeeds for an independent official install, and the following rmSync removes all 12 directories. Preserving edited/prefix-only copies fixes part of the issue, but matching official bytes still proves payload identity, not that First Tree installed or owns the files. Require First Tree provenance or explicit cleanup consent; otherwise preserve/report the copies and test the independent unmodified-install case.

[yuezengwu]

Reviewed exact head 44925a1315dc7547d9769a253120c25a506bd48d against current main 09d7401034bb02dd688b69354c9dd2c569ae76d1 in a clean isolated worktree.

The previous cleanup blocker is fixed: the actual 0.1.12 installer plus this login helper preserves all 16 independently installed official Skill directories when external mode was never enabled, and after an enable/disable cycle. Managed rollback removes 15 unchanged directories while retaining an edited control.

One ownership/data-loss blocker remains on the enabled login path, documented inline: a repeated login overwrites customized content in a Skill that the new ledger explicitly does not own. The cleanup record prevents later deletion but does not protect the earlier installation step.

Fresh validation: diff-check, pnpm check (warnings only), uncached CLI/dependency build (3 tasks), uncached typecheck (9 tasks), and 219 focused tests pass (CLI 74, client 89, shared 35, no-model skill floor 21). Current CI is green and the current-base merge is clean. The independent repeated-login probe reproduces the content loss despite those checks. No source changes, full live/provider QA, model-backed eval, merge, or deployment were performed.

Non-blocking: please update the PR description, which still describes 0.1.9 and prefix-wide uninstall; the CLI reference now correctly describes ownership-scoped cleanup.

[yuezengwu]

[P1] Preserve unowned customized Skills before login-time installation

Every login with external mode enabled calls install --host all here. The pinned 0.1.12 installer recursively removes each existing packaged-name destination before copying its payload; the ownership set is not used to gate that replacement. I reproduced this with the actual helper and CLI in an isolated home: independently install the official Skills, enable external mode once (the ownership ledger correctly has zero paths), customize .claude/skills/context-tree-read/SKILL.md, then repeat the login helper with unchanged configuration. It returns installed and discards the custom content; later rollback even reports all 16 directories as preserved. Please preserve/report unowned or edited copies before this destructive install, or require an explicitly scoped replacement action, and add the repeated-login regression. No real account home or login service was used.

[yuezengwu]

Re-reviewed current head 4cee7742c7b2badee65dd5444be8181b196eea20 against main 09d7401034bb02dd688b69354c9dd2c569ae76d1. My previous request for changes is withdrawn; I found no remaining in-scope blocker.

The login-time replacement defect is fixed. With the actual bundled 0.1.12 CLI and ensureContextTreeSkills() in isolated homes, repeated enabled login preserved customized independent installations and customized First Tree-owned installations, including additional user files. A host containing just one unowned packaged-name Skill was skipped in its entirety, while the other host installed successfully. Ownership was recorded only for the eight newly created directories in that scenario, and rollback preserved the independent copy.

Fresh rollback probes also preserved all 16 independently installed official Skill directories and removed only the 15 unchanged managed directories when one managed Skill was customized. These checks cover both the original ownership/deletion finding and the repeated-login overwrite finding.

Validation at this head: pnpm check passed with 36 warnings and 22 informational diagnostics; uncached CLI dependency builds (3 tasks) and monorepo typecheck (9 tasks) passed. All 221 focused tests passed (CLI 76, Client 89, Shared 35, no-model floor 21), together with seven independent real-CLI/helper scenarios. The current head merges cleanly with the stated main revision. Current technical CI is green.

This is test-only review evidence. I did not run the full monorepo test suite, tests on the synthetic merge result, live provider sessions, or model-backed evals. The documented workspace-only Codex HOME limitation remains; the included cross-surface QA case describes the provider validation still needed before release.