Skip to content

fix: stop the local models on quit, uninstall and setup; process hygiene (0.1.4 F) - #238

Closed
oldwinter53 wants to merge 8 commits into
mainfrom
oldwinter/014-f
Closed

oldwinter53 wants to merge 8 commits into
mainfrom
oldwinter/014-f

Conversation

@oldwinter53

Copy link
Copy Markdown

0.1.4 fix list group F: process hygiene, and P2-6 (Linger part). When the person quits Linger, uninstalls it, or cleans up after a quit, the Bifrost gateway the localmodels model library started is stopped, and so are the engines of the models it loaded. Until now both kept running.

Depends on #236 (pins localmodels 0.1.0.dev40, and on a launch that finds the stack not ready, applies the approved plan again). This branch is based on oldwinter/014-bc2, so its first three commits are #236's. Review only the last five. Once #236 merges, this rebases to just those five.

What changes

Item Change Where
P2-6 The stop runs library status, then library unload <id> for every loaded model, then foundations stop (uninstall and setup only), then stack down. With dev40, stack down also stops the library's Bifrost. Every step runs even when an earlier one fails, and failures are reported by the library's error code. packages/local-installation/src/localmodels-tool.ts stopLocalmodels
P2-6 New installer mode --stop-local-models for a quit: it unloads the library's models and stops the stack in every installation home. The model controller keeps running, because the services that use it keep running too. apps/linger-installer/src/server/stop.ts stopDesktopLocalModels, src/main.ts
P2-6 When the person quits, LocalServer starts that mode detached (ELECTRON_RUN_AS_NODE), writes its output to <home>/installer/local-models-stop.log (already in the diagnostics zip), and does not wait for it. It runs only when local-server.json names an installation. It is skipped for updates, relaunches, and the --quit that setup or the uninstaller sends, because they run --stop right after and a second stack down would race theirs for the stack lock. apps/desktop/src/main/local-server.ts #stopLocalModels, index.ts
P2-17 The daemon exit reason is never one of the daemon's own log records (Go log prefix plus level). After a Go panic it is the panic: line. If no other line was printed, there is no reason and the failure shows the exit code. apps/desktop/src/main/computer-daemon.ts
P2-16 The Windows private-path check throws fixed reason codes, and only a code that matches the list is printed. The error now names the path and the reason (for example, "is owned by another account, such as Administrators after Linger ran as administrator") and carries code: WINDOWS_PRIVATE_PATH_UNSAFE with reason and path. packages/local-installation/src/windows-private.ts
P2-23 This app's own source folder counts as unpacked only when the installer's check accepts it. A damaged one is removed and unpacked again (local_server.source_damaged). apps/desktop/src/main/local-server.ts #ensureSource
P2-7 On macOS, a service record that 0.1.2 wrote with a localized lstart is converted once to the C-locale birth. The conversion happens only when ps in the installer's own locale prints exactly the recorded birth for the live group leader holding the lease. Otherwise the record stays as it is and proves nothing, as before. packages/local-installation/src/native-process.ts adoptLegacyDarwinBirth, native-process-identity.ts

Deferred:

  • P2-3 (Linux: supervisors from the old app folder survive an upgrade). The fix means restarting adopted PostgreSQL and LiveKit whenever the supervisor's app folder changes. That interacts with the move-services-on-upgrade flow (fix(desktop,web): keep the old local services until a move restarts them; never serve a stale page after an upgrade #210) and needs a real 0.1.3 to 0.1.4 Linux upgrade test. The leftover 0.1.2 installer manager is a separate process kind. Too risky for 0.1.4.
  • P2-9 (children inherit the app's handles). Node cannot mark handles it inherited as close-on-exec. A fix needs a spawn trampoline per platform (close_range on Linux, a handle list on Windows) in front of every service start. Too risky for 0.1.4.
  • Not in this PR: a library model that is still loading at quit is not cancelled (library cancel), only loaded ones are unloaded.

User wait / critical path

This doesn't touch the user message → provider_ready path. A quit adds one detached process start and does not wait for it. The uninstall stop adds library status plus one library unload per loaded model (about 2–3 s in the runs below).

Verification

Tests were written first and failed before each fix: localmodels-tool.test.ts (4 failing), stop.test.ts, local-server.test.ts (quit stop, damaged source), computer-daemon.test.ts (3 failing: an INFO line after a kill, a log record after the error line, a panic trace), windows-private.test.ts (4 failing), and native-process-darwin-legacy.test.ts (adopt fails before the fix; the two negative cases keep the record).

  • make check BASE=origin/main: check-repository, check-docs, check-packages, check-teamhub-cli, check-installer, check-desktop, check-scripts-fast and check-web all pass.
  • make check-repository-gate BASE=origin/main: passes.
  • windows-private.native.test.ts now asserts the reasons for a junction, a junction ancestor and shared access. It runs only on Windows and was not run here.

Real machines (real processes)

Each run used the built installer.js with the dev40 pin from this branch's distribution/<target>.json, in an isolated home. The kit came from the real dev40 download. A model was loaded through the localmodels library in LOCALMODELS_DEBUG=simulate mode, which runs the real Bifrost binary (on an isolated free port) in front of a stub engine. That way no GPU was needed and nobody's running stack was touched.

Machine Before the stop After
Linux (local-118). Baseline: what the current uninstall runs (foundations stop then stack down, dev40) Bifrost + engine stack down reports "models the library loaded keep running without the gateway". The engine is left running.
Linux, --stop-local-models (quit) Bifrost + engine nothing left, exit 0 in 5.5 s
Linux, --instance desktop --stop (uninstall) Bifrost + engine nothing left, exit 0
macOS 27.2.1 (macmini, zh-CN), --stop-local-models on the pinned Node 26.5 Bifrost + engine nothing left, exit 0. The person's real 0.1.3 Bifrost and llama-server on the same Mac were left running, as intended.
Windows 11 (homewin), Medium IL, run on Linger.exe with ELECTRON_RUN_AS_NODE: --instance desktop --stop (uninstall), then load again and --stop-local-models (quit) bifrost-http.exe + engine, both times nothing left after each, exit 0

Not checked on a real machine:

  • The Electron side of the quit, i.e. that a packaged app's quit starts the detached stop. That needs an RC package. It is covered by local-server.test.ts, which spawns a real child process.
  • That the next launch after a quit brings the stack up through fix: pin localmodels 0.1.0.dev40, recover a not-ready local model launch, clean up failed installs #236's re-apply. That needs a real stack on a GPU or Apple silicon.
  • P2-16 with a real Administrators-owned file. On homewin, the ssh shell runs as the built-in Administrator and does not produce one.
  • P2-7 on a German-locale Mac running 0.1.2.

For the 0.1.4 RC pass:

  • macOS: Quick Install with a local model, Load a library model, quit from the tray. pgrep -fl "bifrost|llama-server" should then be empty. Relaunch: the stack comes back.
  • Windows: the same, then uninstall. No bifrost-http.exe should be left.
  • Linux: quit, then the 0.4 cleanup. The pkill bifrost / pkill llama-server lines in it should find nothing.

🤖 Generated with Claude Code

oldwinter90 and others added 8 commits November 19, 2026 02:53
0.1.0.dev40 replaces a Pi that cannot load extensions when the stack is
applied again, reports it in setup binding as pi-extensions-unavailable,
fails harness apply with RUNTIME_ACTION_FAILED or RUNTIME_EXTENSIONS_FAILED
instead of exiting 0 after an incomplete install, refuses an unusable
SIMPLEX_PI_PATH and a too-long Windows runtime root at plan time, reports
GPU and free-memory shortfalls with byte figures, and stops the library
Bifrost on stack down.

- Pin 0.1.0.dev40 in the three desktop distributions and in
  scripts/installs/stack.sh and stack.ps1, copied from the published
  launchers; the three tool archives and both launchers were checked
  against the release's SHA256 and size.
- Point the run-without-cloning URLs in scripts/installs/README.md at the
  pinned version, and sync the stack pins in scripts/install with
  scripts/sync-install-stack-pin.mjs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…aves behind

A start whose lease identity could not be proved left its supervisor and
service running with no record, so PostgreSQL kept postmaster.pid and every
Try Again failed until the processes were killed by hand.

- When a start fails before its record is kept and the lease cannot be
  proved, end the process group of the supervisor it spawned and has not
  reaped yet; that PID cannot belong to another program.
- On macOS and Linux, reclaimNativeOrphans now also ends a supervisor whose
  command line names a job file in the instance's process directory under a
  lease no record holds, once its environment proves the lease; the
  services step runs it before PostgreSQL starts, so a state an earlier
  release left heals on the next attempt.
- Split the POSIX stop of one lease out of stopNativeProcess to share it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…en the stack is not ready

A launch that found the local model stack not ready failed with
LOCAL_MODELS_RECOVERY_REQUIRED and asked to review an updated plan, which
the start failure page cannot do; Try Again failed the same way and Set Up
Again was the only way out. A 0.1.3 Pi installed without extension support
reports pi-extensions-unavailable from localmodels 0.1.0.dev40 the same way.

- When the saved binding for the approved plan is not ready and the saved
  plan inputs still match, apply that plan again and bind once it verifies;
  changed inputs still need a new review. The binding's reason codes go out
  in details.reasons and to the installer log.
- The desktop's start failure words the first known reason code and names
  the action that works for LOCAL_MODELS_RECOVERY_REQUIRED (Try Again) and
  LOCAL_MODELS_APPROVAL_REQUIRED (Set Up Again).
- Map localmodels harness errors to structured failures: a refused harness
  plan (unusable SIMPLEX_PI_PATH, a Windows runtime root too long for Pi
  without long paths) is RUNTIME_PLAN_REFUSED, and RUNTIME_ACTION_FAILED and
  RUNTIME_EXTENSIONS_FAILED keep their codes through dependency preparation
  and into the failed job's errorCode.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…all and setup

A Bifrost gateway the localmodels model library started, and the engines of
the models it loaded, survived a quit, an uninstall and a cleanup of the
Linger folders: the stop the uninstaller runs asked only for
`foundations stop` and `stack down`, which leaves library-loaded models
running, and a quit stopped nothing.

- stopLocalmodels first unloads every model `library status` reports
  loaded (`library unload <id> --base-dir <home models>`), then stops the
  controller and runs `stack down`, which with localmodels 0.1.0.dev40 also
  stops the library's Bifrost. Every step runs even when an earlier one
  fails; the error names each failed step by the library's error code.
- The installer's new `--stop-local-models` mode does the same in every
  installation home for a quit, keeping the model controller that the
  still-running services use.
- On a quit the person chose, LocalServer starts that mode detached under
  ELECTRON_RUN_AS_NODE with its output in <home>/installer/
  local-models-stop.log and does not wait. Updates, relaunches and the
  `--quit` of setup or the uninstaller skip it: they stop the models
  themselves right after, and a second `stack down` would race theirs for
  the stack lock. The next launch's resume applies the approved plan again.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… reason

computer_daemon.exited kept the daemon's last stderr line as its reason,
and the start failure showed it. After a kill or a crash that was usually a
log record from minutes earlier ("2026/11/17 20:29:38 INFO
runtime.diagnostic ...") or the last frame of a Go stack trace.

The reason is now the last line outside the daemon's log records, which
carry Go's log prefix and a level, and a Go runtime crash keeps its
panic or fatal error line. A daemon that printed nothing else has no
reason, and the failure falls back to its exit code.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…private path check fails

After Linger ran elevated once, files it wrote there (config.json,
native.env.*.tmp) belong to Administrators, and the next normal start
failed with "Windows private path validation failed" without naming the
file or the cause.

The ACL program now throws fixed UPPER_SNAKE reason codes and prints only
such a code when it fails, never a system message. The error names the
resolved path and words the reason, and carries code
WINDOWS_PRIVATE_PATH_UNSAFE with reason and path; an output that is not
one of the codes is UNCHECKED. The Windows-only native tests now assert
the reason for a junction, a junction ancestor and shared access.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…is damaged

Resume unpacks the source package when the recorded folder is not one the
installer accepts, but a folder with this package's hash and its marker
file counted as already unpacked even with package.json or other files
gone. Every start then failed with "Source checkout must be a Linger
checkout with scripts/source-native.mjs." and Try Again did the same.

The folder now counts as unpacked only when the installer's own check
accepts it; otherwise it is removed and the package unpacked again in its
place, logged as local_server.source_damaged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ocalized start time

Linger 0.1.2 recorded each macOS service's birth from ps lstart in the
locale it ran in. Since 0.1.3 every check reads lstart in the C locale, so
on a Mac with, for example, a German region format the services 0.1.2
left running never matched their records again, and the upgraded app
reported their identity as unverifiable until they ended.

A darwin record whose birth is not in the C-locale shape is now checked
once more with ps in the installer's own locale. When that prints the
recorded birth for the live group leader holding the record's lease, the
record takes the C-locale birth, once; otherwise it is left as it is and
proves nothing, as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@linger-review linger-review Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approve with nits (1 P2, 1 P3)

Scope: base main, merge base 080cbcf9; 8 commits / 39 files in range, focused on the last five (the first three are #236's, which is still open). Loaded ponytail-review (sections 1–3); coderbook and karpathy-guidelines were not loaded and their checks were applied from the review brief. Reviewed head 37e3f207 in a separate session.

Findings

P2

apps/desktop/src/main/local-server.ts:532 (#stopLocalModels): the detached quit stop is not coordinated with the next launch or with a running install job

  • On quit, a detached installer.js --stop-local-models runs library status, then a library unload for each loaded model (each with a 30 s timeout), then stack down. Nothing stops it from overlapping with the next launch.
  • Failure scenario: the person quits, then reopens Linger within a few seconds. #resume runs --resume. In prepareLocalModels (packages/local-installation/src/local-models.ts, the deployed branch), observe() still sees the binding as ready because the old stop has not reached stack down yet. The resume therefore returns without applying the plan. The old process then runs stack down, so the local models and the Bifrost gateway stay down for the whole session, with no error shown. The PR says the next launch "applies the approved plan again", but that only holds if the stop has already finished.
  • A second case: the installer manager keeps running a started job after the app quits (the comment in stop()). If that job is in stack apply when the person quits, the quit stop unloads models and runs stack down at the same time.
  • Fix: make the two exclusive. One option is a lock or marker file under <home>/installer that the stop holds and that --resume/apply waits on (or that the resume treats as "not ready, apply again"). Another is to skip the quit stop when the manager reports a running job. At the least, document the window as a known shortcut.

P3

packages/local-installation/src/windows-private.ts:107,121: exported error code and reason type have no consumer

  • WINDOWS_PRIVATE_PATH_UNSAFE, WindowsPrivateReason, and the code/reason/path fields set on the error are not read anywhere outside tests (git grep). Only the message text reaches the user.
  • Fix: keep the reason map private and throw a plain Error with the worded reason. Add the structured fields when a caller actually branches on them.

Verified as fine

  • stopLocalmodels: every step runs even after an earlier failure. An abort still throws. Model ids from library status are filtered with a strict pattern before they go to argv. A missing or invalid model list is reported, not ignored. keepController skips only foundations stop.
  • stopDesktopLocalModels reuses the extracted attempts helper, so there is no duplicate try/record loop. --stop-local-models is correctly excluded from the legacy migration and from the --source-repo requirement.
  • index.ts: a --quit from a second instance (setup or the uninstaller) maps to the "update" stop reason, so the quit stop does not race their --stop. Updates and relaunches skip it as well.
  • The log fd is opened 0o600 and closed after spawn. windowsHide, detached and unref are set. The stop is skipped when there is no local-server record or no installer script.
  • computer-daemon.ts: LOG_RECORD matches the daemon's default slog output (log LstdFlags prefix plus level). The daemon sets no other default handler. After a panic:/fatal error: line, the trace no longer overwrites the reason.
  • windows-private.ts: only an exact match against the known reason codes is printed, so no system message leaks. Unknown output maps to UNCHECKED.
  • #ensureSource: a damaged package folder is removed and extracted again. A valid one keeps the old fast path. Both callers (install and resume) benefit.
  • adoptLegacyDarwinBirth: it converts only when the C-locale identity is live (leader holding the lease) and inherited-locale ps prints exactly the recorded birth. The write is atomic and idempotent across concurrent readers. It only runs on darwin for records whose birth is not in C format.
  • Tests cover each item (unload loop, partial failures, quit spawn and skip reasons, damaged source, log or panic reason, Windows reason codes, legacy darwin adopt plus two negative cases). AGENTS.md files for desktop, installer and local-installation are updated.

Process notes

  • This PR is stacked on #236, which is still open. Merge #236 first, then rebase this branch down to its five commits.
  • No merge commits and no fixup commits in the range.

CI

Still running at review time: check (desktop), check (installer), check (packages), check (teamhub-cli), repository-gate, web-static, web tests. changes and CodeQL pass. Merge state is BLOCKED (checks pending, and #236 is a dependency). No tests were run locally; none were needed to confirm the findings, which come from the code.

Automated review by Claude Code


Automated review of 37e3f20 by Claude Code.

@oldwinter53

Copy link
Copy Markdown
Author

Consolidated into #244 with #235, #236 and #238 (same commits, replayed on the newest main; the body carries this PR's description, tests and real-machine checks). Please review there.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants