fix(cli): j5 follows the server after an in-app update

[Jacksondr5]

Stack 2/5. Depends on #414.

Problem

Only j5 update repointed ~/.local/bin/j5. An update from the app left the command on the old version. On the dogfood box the service ran 0.0.47 while j5 --version printed 0.0.44, so agents called a CLI three versions behind their server. Closes #398.

What changed

• When it repoints: right after a background-service server finishes the launcher handshake (prepareTrial), it repoints the installer's link at its own executable. That point is reached by:

  • a trial that just committed;
  • the previous version restarting after a rollback;
  • every ordinary service restart.

  So the link always names the version the service runs, and existing installs fix themselves on their next update.

• Reuse: it uses upstream's repointLauncher and launcherOwnsVersionsDir unchanged. It only touches the installer's default link, ~/.local/bin/j5, and only when that link already points into this home's runtime. The service's environment never carries a custom T3CODE_INSTALL_BIN_DIR, so a link placed elsewhere is left alone.

• Unchanged: foreground servers and the desktop app never repoint; j5 update already does for CLI installs.

How it was checked. I built this branch's executable and ran it under the real __service-launcher in a scratch home. It moved a stale ~/.local/bin/j5 from versions/0.0.46/t3 to its own versions/0.0.47/j5.

Upstream impact

• Code: apps/server/src/serverRuntimeStartup.ts gets a three-line hook after launcher.prepareTrial, calling J5-owned apps/server/src/j5/cli/launcherLink.ts.
• Records: FORK.md case 51, with a file-table row. Register entry D28 is extended (upstream has the same gap with t3; give-back candidate for Upstream give-back backlog (hold until V2 merges upstream) #276).

Checklist

• One concern: the description has no "also"
• Tests cover the changed behavior: launcherLink.test.ts (a stale link moves to the running version; a server outside the home's runtime leaves it alone)
• UI changes: none
• Upstream-owned files: each one is recorded in FORK.md (case text and file-table row)
• Upstream product: Jackson approved the design on The j5 command stays on the old version after an in-app update #398, register entry D28
• Surfaces: background service on macOS and Linux; foreground, desktop, and Windows deliberately untouched
• Docs: no user-doc change needed; the register entry covers it

Built by Claude Opus 5.5 (1M context) in Claude Code.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • On supported systems, a managed background server can update the default j5 command link to point to the version it is running, when the link already targets the managed runtime. This can keep the command aligned after an update or restart.
  • Windows, foreground servers, desktop environments, unmanaged installations, and links outside the managed runtime are not affected. Errors are logged and do not interrupt server startup.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
j5-code	Ready	Preview	Oct 4, 2026 10:31pm UTC

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

🧰 Additional context used

📚 Code guidelines (2)

AGENTS.md — auto-discovered
docs/j5/process/docs.md — auto-discovered

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: Jacksondr5/j5code/.coderabbit.yaml
• Review profile: CHILL
• Plan: Essentials
• Run ID: f1484465-3aed-49a4-b238-4d21fed561bf

📥 Commits

Reviewing files that changed from the base of the PR and between f65d007 and cf64133.

📒 Files selected for processing (2)

• FORK.md
• docs/j5/product/upstream.md

🚧 Files skipped from review as they are similar to previous changes (1)

• FORK.md

Included review availability: This review used your included allowance. 0 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 2 reviews per hour.

---

📝 Walkthrough

Walkthrough

Managed startup now attempts to repoint the default ~/.local/bin/j5 link to the running executable when the launcher is managed and the executable belongs to the home runtime. Tests cover eligible and ineligible executables. Documentation records the behavior and its scope.

Changes

Managed CLI launcher link

Layer / File(s)	Summary
Check and repoint the CLI launcher apps/server/src/j5/cli/launcherLink.ts, apps/server/src/j5/cli/launcherLink.test.ts	Adds repointCliLauncherToSelf, which checks executable status, platform, launcher ownership of the runtime directory, and HOME before calling repointLauncher. Tests cover an executable inside the home runtime and one outside it.
Invoke repointing during managed startup apps/server/src/serverRuntimeStartup.ts, FORK.md, docs/j5/product/upstream.md	After launcher.prepareTrial, managed startup attempts to repoint the link using serverConfig.baseDir. It logs and ignores failures. The fork inventory and product record document the behavior and its scope.

Priority: ➖ Normal

Estimated code review effort: 2 (Simple) | ~15 minutes

Change: Bug fix · Severity of issue fixed: Medium

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: the CLI follows the server version after an in-app update.
Description check	✅ Passed	The description covers the problem, implementation, upstream impact, testing, and checklist. It also names the relevant issue and decision record.
Linked Issues check	✅ Passed	Issue #398 requires the CLI link to follow the running server after an update or rollback, without user action. The startup hook runs after launcher.prepareTrial for a managed service and points `~/…
Out of Scope Changes check	✅ Passed	The launcher helper and tests support issue #398. FORK.md records the upstream-owned startup hook, and the upstream register records the integration behavior and its service-status consequence. The …
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 3…

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

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

---

_{Comment @coderabbitai help to get the list of available commands.}

[Jacksondr5]

Review panel (Opus 5.5 code review, Astra live test). One finding on this PR, verified by the builder and fixed in 9151e02:

• Dead branch (should-fix, Opus). The T3CODE_INSTALL_BIN_DIR branch in launcherLink.ts could never take effect: only the service's server repoints, and its unit never sets that variable. The docs nonetheless told people a custom link was covered. The helper now looks only at ~/.local/bin/j5, and the JSDoc, FORK.md case 51 and D25 say so.

Astra confirmed live, under the real __service-launcher:

• a stale link moved to the running j5;
• a link pointing elsewhere was left alone.

[Jacksondr5]

Review panel, second pass (Opus 5.5, Astra). One consequence to record, done in 1bbf438:

• j5 service status asks for a repair after an update from the app (Opus, from the code, not run). Once j5 follows the server, it notices that the unit still names the launcher the service was installed with, and reports the service as needing j5 service install. That's accurate, and upstream's status logic is unchanged; before this PR the stale CLI said "newer than this CLI" instead. An agent that follows the suggestion restarts its own server. Recorded in FORK.md case 51 and D25.

Astra confirmed the repoint live again, including repairing a link it had deliberately made stale.