Skip to content

fix(desktop): localmodels dev40, launch recovery, stop the gateway on quit, setup reasons by code (0.1.4) - #244

Merged
oldwinter53 merged 9 commits into
mainfrom
oldwinter/014-desktop
Nov 19, 2026
Merged

oldwinter53 merged 9 commits into
mainfrom
oldwinter/014-desktop

Conversation

@oldwinter53

@oldwinter53 oldwinter53 commented Nov 19, 2026 •

Copy link
Copy Markdown

Desktop install and launch for 0.1.4. This PR consolidates #236, #238 and #235, which touch the same files (apps/desktop/src/main/local-server.ts, the installer contract and its generated types), replayed on the newest main with authorship and messages kept, one commit per concern:

Commits From Concern
fix(desktop): update localmodels to 0.1.0.dev40 #236 (B) localmodels dev40 pin
end the services a failed install attempt leaves behind, apply the approved local model plan again when the stack is not ready #236 (C2) failed-install cleanup, launch recovery
stop the local models and their gateway on quit, uninstall and setup, never report a daemon log record as the Computer's exit reason, name the path and the reason when a Windows private path check fails, unpack this app's source package again when its folder is damaged, adopt macOS services 0.1.2 recorded with a localized start time #238 (F) stop the gateway on quit and uninstall, process hygiene
fix(desktop): word localmodels setup reasons by code in the setup window #235 (E1) setup window reason copy

The three branches replayed onto main with no conflicts. Contracts were regenerated and are unchanged (pnpm contracts:verify passes).

User message → provider_ready path: untouched. No commit adds a network round trip or file walk there (details per part below).

Integration checks on this branch (BASE=origin/main, GOROOT/GOBIN unset):

  • make check-repository-gate: passes.
  • make check: check-repository, check-docs, check-contracts, check-voice-runtime, check-teamhub-cli, check-installer, check-desktop, check-scripts-fast and check-web pass. check-packages (native-process.test.ts, 30 s timeout) and check-node-services (document-normalizer-watch.test.ts, 5 s timeout) timed out under host load average ~180; rerun on their own, check-node-services passes. check-packages failed once more in native-process.test.ts ("cleans the launched owned group when identity persistence fails", whose code path this PR does not change; fix: pin localmodels 0.1.0.dev40, recover a not-ready local model launch, clean up failed installs #236 saw the same flake under load); that test passed 6 of 6 isolated runs here, and CI's check (packages) passes. check-computer passes except TestManagedToolsUpdateKeepsResidentDaemonPID, which fails the same way on an unmodified main on this host (it needs the bundled Node 26.5 layout).

Part 1: localmodels dev40, launch recovery, failed-install cleanup (from #236)

Summary

0.1.4 group B and C2 from the fix list: pin localmodels 0.1.0.dev40, recover a launch whose local model stack is not ready, and clean up after a failed install attempt so Try Again works without killing processes by hand (P1-10, P1-8, #173).

B: localmodels 0.1.0.dev40 (d71eb825)

  • Pins 0.1.0.dev40 (source a4de3e35) in apps/desktop/distribution/{darwin-arm64,linux-x64,win32-x64}.json, and in scripts/installs/stack.sh and stack.ps1, copied byte for byte from the published launchers. Also updates the README run-without-cloning URLs and syncs the scripts/install pins with sync-install-stack-pin.mjs.
  • I downloaded and checked each archive myself against release.json: darwin-arm64 14953559 B 648e8909…, linux-x64 20790291 B a8e176fa…, win32-x64 23191788 B de073060…, stack.sh 15225 B f4bc0795…, stack.ps1 32584 B 04fff205….
  • What dev40 changes for Linger: setup binding reports pi-extensions-unavailable, and stack apply replaces a jiti-less Pi. Harness apply now exits 1 with RUNTIME_ACTION_FAILED or RUNTIME_EXTENSIONS_FAILED. A plan with an unusable SIMPLEX_PI_PATH, or a Windows runtime root longer than about 90 characters without LongPathsEnabled, is refused at plan time. Stack down also stops the library Bifrost.

C2: launch recovery (P1-10, 7ffa735c)

Root cause: prepareLocalModels only observed the saved binding. When the binding was not ready it returned LOCAL_MODELS_RECOVERY_REQUIRED with "Review an updated plan". The start-failure page has no way to do that, so Try Again failed the same way and Set Up Again was the only exit. On dev40, a 0.1.3 machine with a jiti-less Pi reports pi-extensions-unavailable and lands on the same dead end.

  • packages/local-installation/src/local-models.ts: when a binding saved for the approved plan is not ready, and the saved plan inputs (planId, GPU sharing, no decision model) still match the current choices, the approved plan is applied again with stack apply --approve <planId>. The result is bound only once setup binding verifies it. This covers every binding reason, pi-extensions-unavailable included. Only a plan the person approved is ever applied: changed inputs still need a new review, and a missing or damaged inputs file never authorizes an apply. The binding's reason codes go out in details.reasons and to the installer log.
  • apps/desktop/src/main/local-server.ts (#runResume): the start-failure text puts the first known binding reason code in Linger's own words, for example "The local model's Pi can't load extensions, which every Linger run needs." Then, keyed by details.code, it names an action that works. For LOCAL_MODELS_RECOVERY_REQUIRED that is Try Again, which now applies the approved plan again, or Set Up Again. For LOCAL_MODELS_APPROVAL_REQUIRED it is Set Up Again. All of this is driven by codes; nothing matches on prose.
  • packages/local-installation/src/managed-runtimes.ts and dependencies.ts: localmodels harness errors now become structured failures.
    • A RUNTIME_ACTION_FAILED from harness plan becomes RUNTIME_PLAN_REFUSED (unusable SIMPLEX_PI_PATH, or a Windows runtime root too long for Pi).
    • RUNTIME_ACTION_FAILED and RUNTIME_EXTENSIONS_FAILED from apply keep their own codes. They used to be folded into LOCALMODELS_RUNTIME_UNAVAILABLE.
    • apps/linger-installer/src/server/jobs.ts puts these codes on the failed job's errorCode instead of INSTALL_FAILED.
  • Known limit: dev40 gives the Windows long-path refusal no code of its own, only RUNTIME_ACTION_FAILED at plan time. Linger therefore reports it as RUNTIME_PLAN_REFUSED and shows the upstream cause text, which names the root length and long paths. Telling it apart from other plan refusals needs a distinct code from localmodels. Linger does not copy the 90-character budget or the registry check.

C2: failed-install cleanup (P1-8 / #173, 03945dbf)

Root cause: when startNativeProcess could not prove the new supervisor's lease identity (on 0.1.3 this was the localized ps lstart), its cleanup also found nothing by lease. The supervisor and PostgreSQL kept running with no record, and every Try Again then hit postmaster.pid already exists or "identity could not be verified".

  • packages/local-installation/src/native-process.ts, failed start: when the lease cannot be proved, the start now ends the process group of the supervisor it spawned and has not reaped yet. That PID cannot belong to another program.
  • reclaimNativeOrphans on macOS and Linux: it now also ends a supervisor whose command line names a job file in this instance's process directory under a lease no record holds, once that process's environment proves the lease. Windows already did this. The services step runs it before PostgreSQL starts, so a state left by 0.1.3 heals on the next attempt.
  • The POSIX stop of one lease is split out of stopNativeProcess so both paths share it.
  • Not changed: the installer manager (installer.js) still stays up for its idle timeout after a failed job. It does not block Try Again, which reuses that manager.

Docs

apps/desktop/AGENTS.md, apps/linger-installer/AGENTS.md and packages/local-installation/AGENTS.md are updated for the resume re-apply, the reason and action copy, the runtime error codes, and the POSIX reclaim.

Critical path

Nothing here touches the user message → provider_ready path. The extra work runs only while installing or resuming: one stack apply when the stack is not ready, and one process listing of this user's processes before services start.

Tests (each written first, failing before the fix)

  • local-models.test.ts: a not-ready binding (deployment-unavailable, pi-extensions-unavailable) applies the approved plan again and binds. A stack still not ready asks for recovery and keeps the earlier binding and its reasons. A failed re-apply reports the upstream cause. Changed GPU sharing never re-applies.
  • managed-runtimes.test.ts and dependencies.test.ts: plan refusal maps to RUNTIME_PLAN_REFUSED (Windows long-root text); apply keeps RUNTIME_ACTION_FAILED and RUNTIME_EXTENSIONS_FAILED.
  • jobs.test.ts: the runtime cause becomes the failed job's errorCode.
  • local-server.test.ts: the resume failure names the action for each code and words pi-extensions-unavailable.
  • native-process-unverified.test.ts (new) uses real processes. When every identity check fails, the start still ends the supervisor and the service.
  • native-process.test.ts uses real processes. A service whose record was lost is reclaimed, and a recorded one is untouched.
  • make check BASE=origin/main: repository, docs, packages, teamhub-cli, installer, desktop, scripts-fast and web all pass. make check-repository-gate BASE=origin/main passes.
  • One flake: native-process.test.ts ("cleans the launched owned group when identity persistence fails", which this PR does not touch) timed out twice while the host load average was 47–70. It passed 3 of 3 standalone runs and the make check-packages rerun.

Real-machine checks for the 0.1.4 RC round (not run here)

  • macOS (macmini, zh-CN, 24 GB): Quick Install Pi + local model, then stop the stack (stack down, or kill the llama server), quit, and launch. It should start because the resume applies the approved plan again. Also try Unload, then upgrade 0.1.3 → 0.1.4.
  • macOS: kill the installer job during the services step (or force a PostgreSQL start failure), then Try Again. It should succeed without a manual kill, and no stray native-process-worker.mjs or postgres -D … should remain from the first attempt.
  • Linux (local-118 harness): upgrade a 0.1.3 Quick Install whose Pi has no jiti. The resume should log pi-extensions-unavailable, stack apply should replace Pi, and a Pi chat with the computer tools should work.
  • Linux: Customize > Pi with a bad SIMPLEX_PI_PATH should fail with errorCode RUNTIME_PLAN_REFUSED and show the upstream cause.
  • Windows (homewin): Customize > Pi into a custom location with a runtime root over 90 characters and long paths off. It should be refused up front (RUNTIME_PLAN_REFUSED, text naming the root length), not fail mid-install.
  • Any platform: make a resume fail with the stack still not ready (for example, a port held). The start-failure page should show the reason sentence plus "Try Again … or Set Up Again …", and Try Again should work once the cause is gone.

Overlaps

#213 and #224 edit the same apps/desktop/distribution/*.json lines, so they rebase over one URL/sha change. This PR does not touch local-server.ts sections they edit beyond #runResume.

Part 2: stop the local models on quit, uninstall and setup; process hygiene (from #238)

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.

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.

Part 3: setup window reasons worded by code (from #235)

Summary

0.1.4 E1 (FIXLIST P2-5 Linger part, P2-8, P2-14 Linger part, P2-22): the setup window now puts every localmodels setup inspect reason into its own English words, chosen by reason code. It never shows the tool's message.

  • Root cause (P2-5). setup.html printed models.reasons[0].message as is, for example "GPU service owners unknown; explicit sharing cannot skip the unknown-service check". It also hid the Local model card whenever no model was offered. The installer's setup report carried reasons as bare code strings plus a parallel reasonMessages array, so the counts that localmodels 0.1.0.dev40 adds (gpuIndex, freeBytes, requiredBytes) could not reach the page.
  • Contract (linger-installer SetupReport.localModels.reasons): each reason is now {code, message, gpuIndex?, freeBytes?, requiredBytes?}. reasonMessages is gone. The schema calls message diagnostic text for logs that is never shown or matched on. setup-plan.ts keeps only valid non-negative counts. It also drops the unused assertLocalModelsEligible, the only other reader of the messages.
  • Desktop main (local-server.ts): the page state gets {code, gpuIndex?, freeBytes?, requiredBytes?} only. The tool's words go to the local_server.inspected log.
  • Setup page copy, by code:
    • gpu-memory-required: "Other programs are using GPU 1's memory (3.0 GB free, 9.0 GB needed). Close programs that use the GPU, such as games, video or other AI apps." The held card reads "On hold: GPU 1 has 3.0 GB free, needs 9.0 GB".
    • free-memory-required: the RAM figures come from the reason. A tool without them falls back to stack.memory.
    • gpu-sharing-required, plan-unavailable (held: another AI app holds the memory; otherwise no model fits), facts-unavailable, unsupported-platform, and the dev39 code gpu-ownership-unknown (still mapped because main pins dev39). Any other code gets a generic sentence.
  • Local model card (P2-5): under Customize, once the check ends the card stays visible. It is disabled and reads "Not available on this computer" with the reason, instead of being hidden.
  • P2-8: "menu bar" now shows only on macOS. Windows and Linux say "system tray".
  • P2-14 (Linger part): the card's memory figure is the whole stack's budget, so it now reads "12 GB memory with its services". That makes clear why it is larger than the model-only figure on the Local models page. The recommendation policy itself is GitLab chore: rename Simplex and Co-Workspace identifiers to Linger #17.
  • P2-22: no code change. Commit 5f945e0 (in 0.1.3) added white-space: nowrap and a wrapping action row. I rendered offline.html in Chromium in the failed state at 1280×820:
    • Before that commit, Try Again wrapped and was clipped (scrollHeight 43 in a 36 px button), matching the verify-mac screenshot.
    • Now it fits on one line (scrollHeight 36) and the action row wraps instead.

Not in this PR, per the coordinator's split:

  • pi-extensions-unavailable, a setup binding reason, is handled with the launch-failure page by BC2, which owns local-models.ts:404-417.
  • GATEWAY_HOME_NOT_PRIVATE, a library error cause on the Local models page, goes to E2.
  • The dev40 pin bump also goes to BC2.

gpu-sharing-required cannot appear in setup today, because the desktop's check always passes --share-gpu (DEFAULT_GPU_SHARING). It is mapped anyway.

Critical path: no network round trip or file walk is added on the user message → provider_ready path. The change only touches the setup check's output parsing and page copy.

Tests

Each new or changed test failed before its fix:

  • packages/local-installation/src/setup-plan.test.ts: structured reasons with counts; invalid counts dropped.
  • apps/desktop/src/main/local-server.test.ts: the page state holds codes and counts only, and the log keeps the tool's words.
  • apps/desktop/src/shell/setup-page.test.ts:
    • GPU and RAM counts.
    • Copy for every code, with a check that the tool's message never shows on the page.
    • The disabled card with its reason.
    • "with its services".
    • menu bar or system tray per platform.

Fast checks:

  • make check BASE=origin/main passed check-repository, check-docs, check-contracts, check-teamhub-cli and check-voice-runtime in the parallel run.
  • The following lanes failed in the parallel run and passed when re-run one at a time with mise shims off PATH: check-packages, check-scripts-fast, check-web and check-node-services (load timeouts, plus install.test.ts under a fake HOME). check-installer, check-desktop and check-computer passed in that one-at-a-time run.
  • make check-repository-gate BASE=origin/main passed.

Real-machine checks for the 0.1.4 RC round

Run these with the dev40 pin from this PR:

  • Windows (homewin, display GPU in use by dwm and browsers): the Quick Install line and Customize > Local model show the page's words, never the tool's message. With dev40, gpu-memory-required names GPU 0 with its free and needed memory, and the card stays visible and disabled with the reason. Permissions says "system tray".
  • macOS (macmini, 24 GB): fill memory as in SET-06. The line shows "Other programs are using the memory it needs (X free, Y needed)", the held card shows the same figures, and Check again clears it. Customize shows "… memory with its services". The start-failure page shows Try Again on one line.
  • Linux (shared GPU host): the reason is worded, never printed raw. Permissions says "system tray".

🤖 Generated with Claude Code

oldwinter90 and others added 9 commits November 19, 2026 10:51
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>
The setup window printed the localmodels tool's reason message verbatim
and hid the Local model card when no model was offered. The installer's
setup report now carries each reason as {code, message, gpuIndex?,
freeBytes?, requiredBytes?}; the desktop passes the code and counts to the
page and keeps the tool's words in its log. The page words every code
(gpu-memory-required and free-memory-required with free against needed
memory, gpu-sharing-required, plan-unavailable, facts-unavailable,
unsupported-platform, and dev39's gpu-ownership-unknown), keeps the card
visible and disabled with the reason, names the system tray off macOS and
labels the card's memory as the whole stack's.

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 293f593d; 9 commits, 48 files reviewed at 8bb56061. Helper skills loaded: coderbook. ponytail-review and karpathy-guidelines were not loaded; their checklists (bugs, risk, scale, tests, performance, simplification; surgical changes) were applied from the review instructions. Ran in a separate session.

Findings

P2

apps/linger-installer/src/server/stop.ts:79: the quit-time local model stop is not serialized with the next launch's prepareLocalModels

LocalServerModule.stop("quit") (apps/desktop/src/main/local-server.ts:519, :530) starts --stop-local-models detached and does not wait for it. The stop runs library status, library unload per model, and stack down, which the PR's own Linux run timed at 5.5 s. stopDesktopLocalModels → stopLocalmodels takes no Linger-side lock. prepareLocalModels runs under withInstanceLock on <home>/runtime/localmodels (packages/local-installation/src/local-models.ts:283).

Failure scenario: the person quits and reopens Linger within a few seconds. The launch's resume calls setup binding, which still sees the stack ready (local-models.ts:450), so the resume returns without re-applying. The detached stop then reaches stack down and stops the gateway and engine. Linger stays up with the local model stack down until the next restart, and the first Pi run fails. The localmodels stack lock only orders the two stack commands. It doesn't stop the resume from trusting a "ready" result that the pending stack down is about to undo.

Fix: make stopDesktopLocalModels (or the stopModels call for each home) hold the same withInstanceLock({ root: <home>/runtime/localmodels }) that prepareLocalModels uses. A resume that starts during the stop then waits for it, sees the stack not ready, and re-applies the approved plan through the new path. A test with two overlapping calls would cover it.

P3

apps/desktop/src/shell/setup.html:2607 / apps/desktop/AGENTS.md:162: stale justification for the gpu-ownership-unknown copy

The setup-page commit maps gpu-ownership-unknown "because main pins dev39". This PR's first commit pins 0.1.0.dev40, so that reason no longer holds once the branch lands. If dev40 no longer reports the code, delete the case, its two tests in setup-page.test.ts and the AGENTS.md sentence (deletion pass). If dev40 still reports it, reword the AGENTS.md line so it doesn't tie the code to dev39.

Verified as fine

  • Resume re-apply (local-models.ts): it re-applies only when the saved binding's planId matches the fresh plan, plan-inputs.json matches (planId, shareGpu, decision === false), and localModelsReplan is not set. Changed inputs and a damaged inputs file still return LOCAL_MODELS_RECOVERY_REQUIRED. Reason codes are filtered by pattern before they go out in details.reasons. The upstream message is appended only to display text.
  • Start-failure copy (#runResume): the action is chosen by details.code through Object.hasOwn on fixed tables, and the reason sentence by its reason code. Nothing matches on prose.
  • Failed-start cleanup (endUnreapedGroup): it runs only on POSIX, after the lease loop, for the child this call spawned and has not reaped. Its PID and process group can't have been reused. SIGKILL and ESRCH are handled, and the group loop is bounded.
  • POSIX reclaimUnrecordedLeases: a process is ended only when it is this user's process, names native-process-worker.mjs with a job file under this instance's native/processes/, uses a known service name, holds a lease no record holds, and observed(pid, lease) proves that lease from its environment. stopNativeProcess still removes the record only after a successful stop. The stopLease split preserves the old NATIVE_PROCESS_REPLACED behavior.
  • macOS 0.1.2 birth adoption: the record is rewritten only when the lease is proved live and the inherited-locale lstart equals the recorded birth exactly. Otherwise the record is left as it was.
  • Runtime error codes: RUNTIME_ACTION_FAILED at plan time becomes RUNTIME_PLAN_REFUSED. Apply keeps its codes. jobs.ts sets errorCode only for failed jobs. runtimeFailureCode replaces the duplicated inline checks.
  • stopLocalmodels: every step runs even after an earlier one fails. Model IDs from library status are validated before they become argv. Failures are reported by error code. keepController skips only foundations stop.
  • Quit wiring: replacing from the uninstaller or setup --quit maps to "update", so a quit stop never races their --stop. The stop runs only when local-server.json names an installation. The log file is opened with mode 0600.
  • Daemon exit reason: Go log records are skipped. The panic: / fatal error: line wins over the trace that follows it.
  • Windows private path: only ^[A-Z][A-Z_]+$ codes leave PowerShell, and only codes in the known list are printed. Anything else becomes UNCHECKED.
  • Damaged source folder: validateSourceRepository is checked before reuse, and a damaged folder is removed and unpacked again.
  • Installer contract: reasons is now an array of objects and reasonMessages is gone. contracts/generated matches the regenerated output (check (contracts) passed). The only consumers are the desktop (same release) and installer tests. assertLocalModelsEligible had no other callers.
  • Docs: apps/desktop, apps/linger-installer and packages/local-installation AGENTS.md are updated. No user message → provider_ready path is touched.

Process notes

  • The PR body still has an unfilled RERUN_RESULT placeholder in "Integration checks on this branch". It claims the check-packages and check-node-services reruns but gives no result. CI's check (packages) passed. CI ran no node-services check, and this PR doesn't touch that app.
  • Merge state is BLOCKED, waiting on required review. No merge commits or fixup commits.

CI

All reported checks pass: contracts, desktop, installer, packages, teamhub-cli, web plus web tests 1–3, web-static, repository-gate and CodeQL. check (computer-go) and check (teamhub) were skipped because neither is touched. CI doesn't run the real-process tests that need specific platforms (windows-private.native.test.ts runs only on Windows, and the macOS-only legacy-birth path needs a real 0.1.2 record). I ran no tests myself; the findings above come from reading the code.

Automated review by Claude Code


Automated review of 8bb5606 by Claude Code.

@oldwinter53
oldwinter53 disabled auto-merge November 19, 2026 03:14
@oldwinter53
oldwinter53 added this pull request to the merge queue Nov 19, 2026
Merged via the queue into main with commit 71b4243 Nov 19, 2026
16 checks passed
@oldwinter53
oldwinter53 deleted the oldwinter/014-desktop branch November 19, 2026 03:16
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