Add production ZCode runtime

[L42y]

Extract the official ZCode runtime

Summary

First Tree now supports ZCode as a first-class managed runtime without a third-party npm wrapper. On admission, it obtains the official Linux x64 Desktop package directly from Z.AI's release CDN, verifies both the downloaded artifact and the extracted runtime against pinned SHA-256 and byte-size contracts, caches the runtime atomically, and launches the official zcode.cjs directly with First Tree's Node process.

• Official artifact: https://cdn-zcode.z.ai/zcode/electron/releases/3.10.2/linux-x64/ZCode-3.10.2-linux-x64.deb
• Artifact integrity: SHA-256 b618cfa70c8f7c8a1a6e2950565cc441c298b801bb2389c292eb0d3add6bf0c0, exactly 146,822,580 bytes
• Runtime member: ./opt/ZCode/resources/glm/zcode.cjs
• Runtime integrity: SHA-256 3597160465b67da248fa3fb919920ca30d4e093003a4d70cde2a2e33903cbabc, exactly 12,557,830 bytes
• Runtime admission: exactly 0.16.5, Linux x64, and Node.js 22.19.0+

Artifact acquisition is bounded and cancellable: redirects and unexpected sizes are rejected before retention, while connect, idle-body, and overall deadlines abort stalled CDN transfers. Network, timeout, stall, and retryable HTTP responses remain retryable; digest and contract mismatches stay terminal. Runtime preparation is serialized by an invocation-scoped single-flight plus a cross-process cache lock and generation-safe installation; an unsuccessful candidate cannot delete a valid cache owned by another invocation. Extraction is first-tree-owned, validates the .deb/tar structure and exact runtime member, verifies the extracted runtime digest, and installs it by atomic rename with a contract manifest. Unsupported platforms and missing, malformed, digest-mismatched, incomplete, or wrong-version runtimes fail closed before capability admission or turn execution.

• Catalog, provider identity, shared config validation, client handler/probe registry, model discovery, managed skill routing, and web selection UI are wired end to end.
• Direct runtime invocation is non-shell: process.execPath [cached zcode.cjs] --json --no-color --mode <build|edit|plan> --cwd <workspace> --prompt <prompt>. Continuation adds --resume <provider-session-id>.
• Runtime JSON parsing accepts one JSON object, requires the sess_ session prefix, and rejects trailing or contaminated output.
• Detached POSIX process custody kills the complete process group with TERM-to-KILL escalation, polls the group, waits for bounded settlement, and covers timeout and abort. A TERM-resistant descendant regression proves that the handler does not settle while the group remains.
• Process stdout is capped at 2 MiB before retention. Once the cap is crossed, later bytes are ignored and the full process group is terminated immediately; retained stderr remains a bounded tail.
• Clean-host recovery invokes the cached provider-owned runtime directly (zcode.cjs login) rather than a package launcher First Tree does not install. Credentials remain provider-owned and host-local; First Tree does not read, store, or proxy them.
• Managed model selection is omitted in V1. Empty model configuration delegates to provider-owned ZCode configuration; stale non-empty model values fail closed before session custody instead of becoming prompt content. Web hides model/reasoning controls for ZCode.
• Retry custody remains with ProviderAttempt. A synthetic pending session can never resume until the provider returns a valid native session id.
• MCP delegation and Windows are explicit fail-closed paths rather than unsafe fallbacks.

Validation

• Real official-artifact extraction smoke check against the production tar contract: pass
• Empty-HOME provider-runtime smoke checks: zcode.cjs --version reports 0.16.5; login --no-browser --no-color emits the provider OAuth URL
• @first-tree/client typecheck: pass
• ZCode client suites: 32 tests passed, including official-artifact parsing/extraction, digest and version admission, cache-lock ownership and preservation, acquisition deadlines/retry classification, process-tree custody, stdout flood, auth recovery, JSON/session, and stale-model rejection
• @first-tree/shared suites: 954 tests in 79 files passed
• Web source suites: 2,426 tests in 252 files passed
• Web typecheck and design-token checks: pass
• CLI capability-refresh suite: 22 tests passed
• Biome over all 33 changed files: pass, 0 warnings
• git diff --check: pass

Context Tree review

Reviewed against the bound Context Tree at repository first-tree-ai/first-tree-context, branch main, exact commit 82be900117b58a6f55e73aa3fd04c711c8fec812:

• first-tree/system/cloud/runtime/runtime-auth.md
• first-tree/system/cloud/runtime/client-runtime.md

The direct official-runtime extraction and provider-owned, host-local authentication follow the runtime-auth and client-runtime custody architecture.

[yuezengwu]

Reviewed exact head fa268e899c008130f6ab739241c69b0a0b7e76ee. This production runtime is not ready to ship: the inline findings leave process/output custody, clean-host authentication recovery, the pinned wrapper compatibility boundary, and model selection without the fail-closed guarantees required for managed runtimes. The current CLI suite also fails deterministically after adding the provider.

Validation on this exact head:

• pnpm --filter @first-tree/client typecheck — pass
• pnpm --filter @first-tree/client exec vitest run src/providers/zcode/__tests__ — 10/10 pass, but only two handler tests and none cover the lifecycle/failure paths below
• pnpm --filter first-tree-dev exec vitest run src/__tests__/capability-refresh.test.ts — 3 failed, 19 passed
• Biome over all 26 changed TS/TSX/JSON files — pass
• git diff --check — pass

The PR also cites Context Tree commit 82be900117b58a6f55e73aa3fd04c711c8fec812, but that object is not reachable from the canonical first-tree-ai/opentag-context-tree master fetched during this review (current 81a3f8986f79c43020954e75b2b89507936619a3). Please correct the exact evidence and revalidate the runtime custody/ACK contracts against the canonical tree.

Because this is an external contribution introducing an unofficial wrapper and a browser/tool-capable runtime into production, final acceptance and merge also require an explicit human supply-chain/privilege review after the technical blockers are resolved. I did not modify the branch, approve, or merge it.

[L42y]

Reviewed fixes are pushed at exact head bed8214ddf1a57837f57443d0079219328033932.

ZCode now fails closed on exact wrapper/runtime version 3.10.2-18, Node.js 22.19.0+, malformed version contracts, and Windows before admitting capability or executing work. Detached runtime work uses shared POSIX process-group TERM-to-KILL custody with a TERM-resistant descendant regression. Stdout retention is capped before append, overflow terminates the process group immediately, and clean-host credential failures map durably to provider-owned zcode login --oauth recovery. Managed model selection is omitted in V1 and stale non-empty model configs fail before synthetic session custody. The exhaustive CLI capability fixtures include zcode.

The PR body now points to first-tree-ai/first-tree-context@82be900117b58a6f55e73aa3fd04c711c8fec812 and documents these custody/admission contracts. CI is green on the pushed head: client/web, both CLI shards, server, lint/typecheck, migrations, and smoke checks pass. Targeted validation also includes 21 ZCode/client tests, 22 capability-refresh tests, and the full shared suite.

[github-actions]

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

[L42y]

Updated at exact head 858f458e07d107be301400f7f0ce559ee7dc45fd. Aggregate ZCode capability probes are now isolated from the official-runtime resolver, and all CI checks are green, including Test Client & Web. Every commit in the PR now has L42y author and committer identity, and CLA is green. The PR remains open for review and merge.

[yuezengwu]

Reviewed exact head 858f458e07d107be301400f7f0ce559ee7dc45fd from scratch. Requesting changes for the following release blockers.

1. [P1] Clean-host authentication recovery points to a command First Tree never installs. The catalog advertises zcode login, but ensureOfficialZcodeRuntime extracts only ./opt/ZCode/resources/glm/zcode.cjs, moves that one file into the cache, and launches it through process.execPath; it never installs the package launcher or creates a zcode shim. I independently downloaded the pinned public .deb (146,822,580 bytes, SHA-256 b618cfa7...bf0c0) and confirmed that the package's postinst is what creates /usr/bin/zcode -> /opt/ZCode/zcode; that script is not run by this implementation. In a task-scoped empty home, the extracted runtime itself exits 1 with Model config is missing..., while the recovery surface tells the user to execute the absent bare command. This leaves the advertised clean-host flow unrecoverable after capability admission. Expose a real managed-runtime login/configuration path (or a First Tree-owned shim/driver) and validate it from an empty task-scoped home.

2. [P1] The shared runtime cache is race-destructive. On every cache miss, ensureOfficialZcodeRuntime recursively removes cacheRoot before staging, and its outer catch recursively removes the same shared root again. Concurrent capability/session preparations therefore allow one resolver to delete a valid runtime installed by another; an unrelated failed download can also erase the winner after its atomic rename. Treating EEXIST/ENOTEMPTY as a rename race does not fix the unconditional loser cleanup. Use a single-flight/lock or generation-owned staging scheme, and never delete a cache installation this invocation did not own.

3. [P1] Artifact acquisition has no deadline or cancellation custody. downloadExactArtifact calls fetch(..., { redirect: "error" }) without an AbortSignal or timeout, then awaits the body indefinitely. This path runs during both capability probing and session preparation, so a CDN connection/body stall can hang probe aggregation or an Agent start forever. The function then classifies every acquisition failure as transient: false. Add bounded connect/body deadlines and a correctly classified retryable acquisition result.

4. [P1] The required client checks are not platform-isolated. On this exact head, pnpm --filter @first-tree/client exec vitest run src/providers/zcode/__tests__ ... fails 3 tests in official-runtime.test.ts on the supported macOS/arm64 development host: the success, digest-mismatch, and missing-member cases all hit the host platform gate because they do not inject platform: "linux" / arch: "x64". The combined run finished with 317 passing and 3 failing tests. pnpm typecheck, the shared catalog tests (9/9), CLI capability-refresh tests (22/22), and git diff --check pass.

QA status is BLOCKED, tier full-isolated, for the real provider-backed turn/auth/resume claim: no task-scoped ZCode credential was available, and I did not borrow an operator/provider home or session. The public-artifact integrity/extraction/version smoke passed (zcode.cjs is a regular 12,557,830-byte member with SHA-256 35971604...cbabc, runtime 0.16.5), but that is not real-turn evidence. Case disposition: candidate-new-case; this provider/auth/cross-surface change has no matching ZCode case under packages/qa/cases/.

[L42y]

All four release blockers are addressed at exact head a5c0c92e5151a268472079ca1322aec024b358fd.

1. Clean-host recovery: The shared catalog and in-turn auth recovery now invoke the cached provider-owned runtime directly as zcode.cjs login; they no longer reference the absent bare zcode package launcher. An empty-HOME smoke check confirmed the extracted runtime reports 0.16.5, and login --no-browser --no-color emits the provider OAuth URL. First Tree does not take credential custody.

2. Cache custody: Runtime preparation now has process-level single-flight keyed to the cache contract plus a bounded cross-process directory lock. Installation is generation-safe: candidates are staged, valid installs are never deleted by another invocation, invocation-owned invalid installs are backed up and restored on failure, stale locks are recovered safely, and a busy lock becomes retryable.

3. Acquisition custody: CDN download now has connect, idle-body, and overall deadlines through cancellation custody. Network, timeout/stall, HTTP 408/429/5xx, and comparable acquisition failures are retryable; digest, size, redirect, and extraction-contract violations remain terminal.

4. Platform isolation: The official-runtime regressions inject Linux/x64 explicitly and add coverage for lock ownership, preservation of valid caches, concurrent preparation, and acquisition deadline/retry classification.

Targeted validation includes 32 ZCode client tests, the full shared suite (954 tests), web sources (2,426 tests), CLI capability refresh (22 tests), typechecks, Biome, extraction smoke checks, and git diff --check. All PR checks are green at the exact head. This does not claim real credential-backed provider turn/resume QA; no task-scoped ZCode credential was available.

[yuezengwu]

Reviewed exact head a5c0c92e5151a268472079ca1322aec024b358fd from scratch. The cache lock, download deadlines, platform-isolated tests, and in-turn dynamic login command address the prior blockers, but one clean-host recovery blocker remains.

[P1] The shared setup command is still not bound to the admitted managed runtime. packages/shared/src/schemas/runtime-provider-catalog.ts:42 publishes node "$HOME/.cache/.../zcode.cjs" login as the copy-pasteable host login step. The resolver in official-runtime.ts:364-371 can instead install under FIRST_TREE_ZCODE_RUNTIME_CACHE or XDG_CACHE_HOME, so those supported hosts are directed to a nonexistent file. The supported portable First Tree install is also launched with its bundled Node by absolute path (apps/cli/src/core/portable-install-context.ts:23-32) and does not establish that a compatible bare node exists in the user shell. A capability probe can therefore admit the exact managed runtime while Computers/setup recovery tells the user to run a different path or runtime. Please surface the resolved command (including process.execPath and the actual cache root) or add a First Tree-owned login driver/shim rather than freezing $HOME/.cache plus bare node in the shared catalog.

Exact-head validation passed: full client suite 2,879 tests (7 skipped), full shared suite 954 tests, pnpm check, monorepo typecheck/build graph, and git diff --check. GitHub CI is green. The live head was refreshed immediately before this review and remained exact; the PR is currently also conflicting with main. I did not claim real credential-backed provider turn/resume QA.

[L42y]

Fixed the remaining P1 and resolved the main conflict. Exact head is now 221b7b5990270a3a6b8eb50d01c0167755bce047; all checks are green.

Shared setup command bound to the admitted managed runtime. ZCODE_OFFICIAL_DEFAULT_LOGIN_COMMAND in packages/shared/src/schemas/runtime-provider-catalog.ts no longer hardcodes $HOME/.cache. It's now a shell fallback expression that mirrors ensureOfficialZcodeRuntime's exact cache-root precedence (FIRST_TREE_ZCODE_RUNTIME_CACHE, else XDG_CACHE_HOME, else $HOME/.cache, per official-runtime.ts:364-371):

node "${FIRST_TREE_ZCODE_RUNTIME_CACHE:-${XDG_CACHE_HOME:-$HOME/.cache}/first-tree/zcode/official/3.10.2-6414}/zcode.cjs" login  # requires Node 22.19.0+

I verified the nested parameter expansion resolves identically to the TS resolver in bash and dash across all three configurations (unset, XDG_CACHE_HOME set, FIRST_TREE_ZCODE_RUNTIME_CACHE set). This is the copy-pasteable command surfaced on Computers/setup and as the last-resort chat-timeline fallback; the in-turn dynamic login command (officialRuntimeLoginCommand, already using process.execPath and the resolved runtimePath) is unchanged and remains the primary recovery path once a turn has run. I left the portable-install bare-node assumption as-is with an inline # requires Node 22.19.0+ note — I don't have a way to guarantee a specific Node binary from a static shell string without adding a new First Tree-owned CLI shim, which felt like more surface than this blocker calls for; happy to add one if you'd rather close that gap structurally.

main conflict. Merged origin/main (the Antigravity runtime provider, PR #2375) into this branch. Five real conflicts, all disjoint additions from the two providers being added in parallel (capability probe test tables, the shared catalog, agent-runtime-config.ts payload types) — resolved by keeping both providers' entries. The merge also surfaced that main added a required noteTurnStart hook to SessionContext after both providers' handler test fixtures were written; both the zcode and (main's own) antigravity fixtures were missing it and failed typecheck post-merge, so I added the mock to both.

Full validation at this head: monorepo typecheck and pnpm check clean, full client suite passing (2,924 tests; the same 4 managed-skills.test.ts failures reproduce identically on the prior reviewed head a5c0c92e5 in this sandbox — a pre-existing local umask/group-write artifact unrelated to this change, not present in CI), full shared suite (954), web (2,427), and CLI (72) all green locally, and GitHub CI is green end to end including Test Client & Web and Test Server. I did not re-run real credential-backed provider turn/resume QA.

[yuezengwu]

Reviewed exact head 221b7b5 from scratch. The cache-root precedence now matches runtime extraction, the main conflict is resolved, and the focused ZCode custody tests remain green. One clean-host recovery blocker from the prior review is still unresolved.

ZCODE_OFFICIAL_DEFAULT_LOGIN_COMMAND still begins with bare node. The author comment explicitly leaves that assumption in place and only adds a requires-Node note. Supported portable First Tree installs run through their bundled Node executable by absolute path and do not establish a compatible node command in the user shell. A clean host can therefore pass ZCode capability admission and have the digest-pinned runtime extracted successfully, yet the Computers/setup recovery command fails before opening provider login because node is absent or below 22.19.0. A comment stating the prerequisite does not make the advertised recovery executable.

Please add a First Tree-owned login command/driver or another recovery surface that invokes the admitted runtime with the same absolute Node executable First Tree resolved. The dynamic in-turn hint already has that exact command; the static Computers/setup path needs the same executable custody rather than bare node.

Exact-head validation: 32 focused ZCode tests, Client typecheck, pnpm check, GitHub CI, and git diff --check pass. I did not claim credential-backed live provider QA.

[L42y]

Addressed the remaining P1 with the driver you asked for, plus a real clean-host bug it surfaced. Exact head is now e33d28ae11ee2f6e3769e867916ecceec07aeba0.

First Tree-owned zcode login driver. Added first-tree zcode login (apps/cli/src/commands/zcode/index.ts + apps/cli/src/core/zcode-login.ts): it re-resolves the managed runtime via the exact same ensureOfficialZcodeRuntime() a provider turn uses — extracting it first on a clean host, honoring FIRST_TREE_ZCODE_RUNTIME_CACHE/XDG_CACHE_HOME — then hands the terminal to it via resolution.command, which is process.execPath, i.e. the exact absolute Node executable First Tree itself is running as. No more guessing a cache root or a bare node on PATH. ZCODE_OFFICIAL_DEFAULT_LOGIN_COMMAND is now "first-tree zcode login". Computers/setup additionally threads the connected Computer's own reported channel binary name (client.binName, already on the wire) through RuntimeProviderRow → RuntimeInstallBox, so that live surface shows the exact binary on that host's PATH (first-tree-staging, first-tree-dev, etc.) instead of the channel-generic reference form.

Bonus: found and fixed a real clean-host bug while smoke-testing the driver. ensureOfficialZcodeRuntime acquired the runtime lock with a non-recursive mkdir(lockPath) before ever creating its parent directory — so the very first admission on a truly clean host (no ~/.cache/first-tree/zcode/official/ tree yet) failed closed with a bare ENOENT, classified transient: false (terminal). Every existing test's cacheRoot happened to sit directly inside an already-mkdtemp'd root, so this never surfaced. Reproduced it with a manual env -i HOME=<fresh dir> run of the new driver, fixed it (create the lock's parent directory up front), added a regression test that fails without the fix and passes with it, then re-ran the same empty-HOME smoke test end-to-end through the real built CLI: clean extraction, zcode.cjs --version → 0.16.5, and zcode login --no-browser --no-color prints the real Z.AI OAuth URL.

Full validation at this head: monorepo typecheck and pnpm check clean; @first-tree/shared 955, @first-tree/web 2429, CLI 140+72 (all 27 shard batches), and @first-tree/client 2925 passing (only the same 4 managed-skills.test.ts failures from a local sandbox umask artifact, unrelated and not present in CI, as noted last round). git diff --check clean.

One thing to flag: this run's CI shows Test Server red — both failures (admin-sessions-suspend-terminate.test.ts and clients-provider-models.test.ts, both "falls back to the durable ack/catalog when the result wake is lost") are pre-existing, unrelated timing races. They pin the client-reply-wait window to 50ms/80ms via setClientReplyTimeoutMsForTests and assert a durable-store fallback still resolves in time — a synthetic margin that's easy for a loaded shared GH Actions runner to blow. Neither file, nor anything they touch, appears anywhere in this PR's diff, and the other 294 server tests in that same run passed. I don't have admin rights on this repo to trigger a rerun (gh run rerun / the rerun-failed-jobs API both 403'd for me) — a rerun from someone with that access should clear it, or let me know if you'd like me to look closer.

[yuezengwu]

Exact-head technical review completed at e33d28ae11ee2f6e3769e867916ecceec07aeba0 against base 38752415320c97c0bd122aa4afb13c3ff60b1b06.

The First Tree-owned zcode login driver closes the prior clean-host recovery blocker: it re-resolves the pinned managed runtime, launches the exact admitted command and arguments through the First Tree-resolved Node executable, forwards provider login arguments, and connected-Computer surfaces use the actual channel binary name. The clean-host cache-lock parent fix is also covered. I found no new technical blocker.

Validation on this exact head:

• ZCode client tests: 33/33 pass
• CLI login and capability-refresh tests: 27/27 pass
• pnpm check and git diff --check: pass
• GitHub lint/typecheck, Client/Web, CLI, portable/release smoke, and final CI summary: pass
• The initial Server failure was two timing-sensitive durable-ack/lost-wake tests in files untouched by this PR. Across six focused local exact-head runs, five passed 59/59 and one reproduced the same race; the failed GitHub job rerun passed.

I am not approving this head yet because the remaining decision is not a code repair. This external contribution adds a pinned third-party browser/tool-capable runtime, and no credential-backed live turn/resume QA was available. I verified the canonical Context Tree at first-tree-ai/opentag-context-tree@ffa582067aa56a6d499a4f96ef89cbb1a76fc0ff: its zero-token-custody and provider-owned host-auth constraints are directionally compatible, but it does not yet adopt ZCode, while the PR description still cites the frozen old first-tree-context repository. A maintainer must explicitly accept the supply-chain/privilege and canonical-context boundary, or request the missing evidence, before approval or merge.