fix(devices): explain missing npm during tool updates - #27084

Approvability

Verdict: Approved at 80f509a

Macroscope's review found this PR approvable — Device-tool updates now explain when neither npm nor pnpm is available and provide recovery instructions. Installation behavior remains unchanged, and displayed errors continue to avoid raw process output.

^{You can add or adjust custom eligibility rules. Learn more.}

No actionable comments were generated in the recent review.

Merge Risk: Minimal · up to 39415

Settings will now explain how to install Node.js with npm and restart T3 Code when the package manager is missing. Other update failures behave as before. No merge-blocking risk was found. The current-head UI and Windows flows were not exercised.

Pre-merge checks: 4

Check name	Status	Explanation
Title check		The title "fix(devices): explain missing npm during tool updates" matches the main change. The PR classifies a missing npm/pnpm failure as package_manager_missing and adds a user-facing message that e…
Description check		The description follows the repository template. It gives the problem, the change, a scope statement that links issue #17431 and explains the small bug-fix exception, and a detailed verification secti…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Title check

Explanation

The title "fix(devices): explain missing npm during tool updates" matches the main change. The PR classifies a missing npm/pnpm failure as package_manager_missing and adds a user-facing message that explains how to install Node.js with npm. The title is concise, follows conventional commit style, and names the affected area.

Full details: Description check

Explanation

The description follows the repository template. It gives the problem, the change, a scope statement that links issue #17431 and explains the small bug-fix exception, and a detailed verification section with commands, results, and unverified areas (Windows, SSH, integrated UI). The template's conventional-commit guidance is followed by the title. The description also includes the model and harness attribution the template asks for. The description is mostly complete and clear.

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Recent review info

Run configuration

• Source mode: Auto
• Repository: pingdotgg/t3code
• Branch: main
• File: .coderabbit.config.ts
• Commit: 820f620
• Layers: Repository TS config
• Review profile: CHILL
• Plan: Advanced
• Run ID: 190c6747-d7a7-490d-bc54-7916ba390167

Commits

Reviewing files that changed from the base of the PR and between 92b65eb and 394157b.

Files selected for processing: 3

• apps/server/src/device/DeviceService.test.ts
• apps/server/src/device/DeviceService.ts
• packages/contracts/src/device.ts

Files skipped from review as they are similar to previous changes: 1

• packages/contracts/src/device.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

Confirming this on Windows, as a real-world repro of the exact path this PR fixes.

Environment: Windows 11 Pro 24H2 (10.0.26100), T3 Code Nightly desktop app 0.1.6-nightly.20261029.3892, the same commit this PR is based on (08a463e). There was no system Node.js; t3 ran on its bundled runtime, so neither npm nor pnpm was on PATH.

Repro: Settings → Devices → Device hub (Required 0.19.0-canary-20261023-1357114, Installed: None) → Update. The same happens for Agent device (0.21.31).

UI shows: Device update device tool failed: The device command failed.

server.trace.ndjson shows the npm → pnpm fallback from DeviceToolchain.ts running out of options:

DeviceToolchainInstallError: Installing expo-device-hub failed while running npm install.
  ProcessSpawnError: Failed to spawn process 'pnpm'
    PlatformError: NotFound: ChildProcess.spawn (pnpm --package=npm@11 dlx npm install --prefix <home>\.t3\tools\expo-device-hub\.staging-… --no-fund --no-audit [email protected])
      Error: spawn pnpm ENOENT

Workaround confirmed: installing Node.js LTS (winget install OpenJS.NodeJS.LTS, giving npm 11.20.0) and fully restarting T3 Code fixed it. Both tools then installed on the first click, and npm resolved through npm.cmd with no problems. So the recovery advice this PR adds ("install Node.js with npm and make it available to the T3 server") is correct on Windows too. It might be worth saying explicitly that the app has to be fully restarted (including the tray) after installing Node, because a running server keeps its old PATH.

Investigated with Claude Code (Claude Opus 5.5) via t3 triage.

Tested this PR on Windows (Win 11 24H2, 80f509a, Node 26.12.1 through vp):

• vp test run src/device/DeviceToolchain.test.ts src/device/DeviceService.test.ts (from apps/server): 46 passed.
• Real ProcessRunner, not a stub: I ran ensureDeviceHub / ensureAgentDevice with NodeServices.layer + ProcessRunner.layer, and with PATH limited to %SystemRoot%\system32;%SystemRoot%;%SystemRoot%\System32\Wbem. Both tools fail with reason: "package_manager_missing". The cause chain is ProcessSpawnError → PlatformError(NotFound), so Windows command resolution produces the NotFound shape this PR depends on. No .staging-* dirs are left behind.
• Control: the same check on base 08a463e gives reason: undefined and "The device command failed.", which matches what I saw in the desktop app.
• UI: vp run dev with a throwaway --home-dir. A Node preload removed the PATH entries containing npm/pnpm from the server process only. In Settings → Devices, clicking Update on both Device hub and Agent device shows "Device update device tool failed: Neither npm nor pnpm was found on this host. Install Node.js with npm on this host, make npm available to the T3 server, then retry." The server trace has the same spawn pnpm ENOENT chain as my real desktop failure.

I didn't run the Electron desktop build of this branch. The web UI ran against a native Windows server; the desktop app renders the same Settings code.

Tested with Claude Code (Claude Opus 5.5).

takeover update, 2026-11-11: pushed 92b65eb6ae333ad731b367a74653245f848945d4 to the existing contributor branch without force. merged current main without rebasing and resolved the toolchain conflict by keeping main's internal npm_not_found reason and mapping it to this PR's public package_manager_missing recovery message. this preserves the device-boot error and pnpm fallback. the diff against main is four files. both independent read-only reviewers approved this head. GitHub reports MERGEABLE.

verification is blocked: the task-owned Blacksmith workflow ended in startup_failure before creating jobs, so dependency setup and vp run check:changed could not execute. the new PR CI run 43098238606 reports action_required with no jobs or logs. no checks were bypassed. current-head runtime/UI verification remains unverified; the evidence below belongs to earlier heads. no merge was performed.

takeover update, 2026-11-03

head 25e3490fd8751bb8c76f63577febd085bf8fce6d: merged main without rebasing, preserving both the existing missing-manager cases and main's secret-resolver dependency. addressed the review finding by telling users to fully restart T3 Code, including its tray app, or the T3 server after installing npm. only the recovery text and its existing assertion changed after the merge; the pr remains five files.

blacksmith vp run check:changed github/main passed format, lint, knip, graphql, typecheck, and all 66 selected tests. both independent reviewers approved this head. ci reports 28 successful checks with none pending or failing; github reports a clean merge. the review thread is resolved. no merge was performed.

verified the error in the real web client against an isolated linux server with npm and pnpm unavailable through its PATH. the update button displayed the full restart instruction. these matching captures show the text before and after the fix. the before capture temporarily used the earlier text; the committed source is restored and clean.

native clients, windows/macOS, remote hosts, and successful installation were not rerun on the final head. earlier-head evidence follows.

Verified in a real dev environment

verified unchanged head 80f509a27fd1a8d1f00b35c57f1816201f5a2360 on a disposable linux boat vm, using real vp run dev servers, repo playwright, and /usr/bin/google-chrome. main and the pr ran sequentially.

• reproduced on github/main (32ecd71726) in a separate worktree: settings → devices → device hub → update showed only "the device command failed."
• on the pr, made npm and pnpm genuinely unavailable by temporarily moving their executables out of the server path. clicking update for both device hub and agent device displayed the full missing-manager explanation and node/npm recovery instructions. no process mocks or intercepted responses.
• "check versions" remained usable after failure. no staging directories remained.
• restored npm/pnpm and retried both updates through settings. the hub installed 0.19.0-canary-20261023-1357114; agent device installed 0.21.31. installed matched required and both update buttons disappeared.
• added a project pointing at a real git checkout through the app, selected codex gpt-6.1-sol, and completed a real provider turn through the composer and server.
• blacksmith: vp test run apps/server/src/device/DeviceToolchain.test.ts apps/server/src/device/DeviceService.test.ts: 46 passed. existing ci reports 30 successful checks, zero pending or failing. no code changes were needed.

runtime transcript

Not verified

native ios/android clients, the electron shell, macos/windows, and ssh host updates were not available in this linux verification. successful pnpm fallback and live permission-denied/nonzero-install failures were not exercised; the focused tests cover their classification. no simulator or native device session was started. check:changed was not rerun because no source changed.

while preparing this comment, a shell quoting error accidentally launched a local test command. that command failed during runner setup; it changed no source files. the independent blacksmith run above passed all 46 tests.

Evidence

Open Settings → Devices with npm/pnpm unavailable and both device tools uninstalled. Click Not installed → Update for Hub, reopen Devices, then repeat for agent-device. Environment on both sides: Linux, Chromium, 1280×800, light theme, fresh database and synthetic project.

Proven: both tools show the generic failure on base and actionable npm guidance on head.

	Before	After
Commit	820f620e3d	394157b264
Hub
agent-device
Recording	Before interaction	After interaction

Scenario source · Fixture instructions · Namespace wrapper · Runner fixture patch