Publish installed engine CLIs on the user's PATH

[ckelseynv]

Changelog title

Installed engines can be added to your PATH

Changelog body

• Installing Ollama or LM Studio through PAIR now asks whether to put its command-line tool on your PATH, so ollama or lms works in a new terminal without extra setup. First-run setup asks once for every engine you selected, and the terminal interface asks the same question.
• Uninstalling an engine that PAIR added to your PATH offers to remove that entry too. PAIR only ever removes entries it added, and leaves your own PATH entries and shell configuration untouched. Uninstalling PAIR together with its data (on Linux, apt purge) releases any entries its engines still own.

Bumps

• services: minor
• nvpair-cluster-manager: none
• nvpair-engine-manager: minor
• nvpair-errors: none
• nvpair-job-scheduler: none
• nvpair-manual-nodes: none
• nvpair-node-info: none
• nvpair-node-scanner: none
• nvpair-node-settings: none
• nvpair-proxy: none
• nvpair-tui: minor
• nvpair-ui-broker: none
• nvpair-workload-manager: none

Summary

When PAIR installs Ollama or LM Studio, it can add that engine's command-line
directory to the installing user's persistent PATH on that device, and gives
back only what it recorded once the engine or the application is removed. Open
a new terminal after either operation.

Local installs only. An install driven by a cluster peer deliberately skips the
PATH step, because rewriting the login shell of whoever is sitting at the target
node is not a paired peer's decision.

The user decides

Every PATH change needs the user's consent, carried as path on
engine:install and engine:uninstall. A missing or false path never touches
PATH, so a client that does not ask the user changes nothing. On uninstall the
answer has three values: true removes the entries, false keeps them and
hands them to the user, and a missing path (the client did not ask) keeps
them and PAIR's claim, so a stale or unasking client can never strand an entry
with no record that could remove it. EngineStatus gains path_managed, true
while the record holds an entry PAIR actually wrote, so a client asks about
removal only when there is something to remove. It is emitted after every PATH
step and served to peers as false.

• Desktop install: a yes/no modal before any local install — the engine
  card, the node list's install chip, and Retry on a failed install. No still
  installs; dismissing the modal cancels. Remote installs never ask, since they
  never change PATH.
• First-run wizard: one modal names every selected engine, and the single
  answer applies to all of them.
• Desktop uninstall: the existing confirmation gains "Also remove
  from my PATH", checked by default, shown only when path_managed is true.
• Update: reads path_managed fresh from engine:status and carries that
  answer through its uninstall and reinstall without asking again.
• Retry from the error banner: asks the same questions; the uninstall
  checkbox starts unchecked, since the failed attempt may have kept the entry.
• TUI: i asks (y/n, esc cancels); u asks only when PAIR owns an entry,
  and otherwise sends no answer.

A declined install still records that PAIR ran the installer, so a later
consented install can re-adopt an engine whose vendor owns its location; a
peer's remote install records the same flag and never publishes. An install
over an engine already on disk records nothing without consent, and a declined
install keeps any claim already on record. A declined uninstall leaves the
entries in place and deletes the record, so they become the user's and the
application uninstaller no longer touches them. A consented uninstall always
deletes the record, including one holding only the installed flag.

path_managed is read from the ownership record on each status snapshot rather
than cached: nvpair-tui runs its own engine-manager against the same records,
so a cached answer would go stale the moment the other one changed them. The
read takes no lock; on Windows, a record rename that races it is retried
briefly instead of failing on the sharing violation.

Ownership is the whole design

Nothing else can identify what PAIR put on a user's PATH, so an ownership record
is written outside the engine directory and before the PATH is touched. That
ordering makes a crash mid-update retryable, and it means an uninstall deletes
exactly what PAIR added. Existing entries, user-edited shell snippets, and
engines the user installed themselves are all preserved, because an entry PAIR
cannot prove it wrote is an entry it must not remove.

The record also notes that PAIR ran the installer, which is a longer-lived fact
than any individual PATH entry. It is what lets a reinstall re-adopt an engine
whose vendor owns its location — LM Studio writes ~/.lmstudio, so the path
alone is no evidence of who put it there. A record that exists but cannot be
parsed fails an uninstall rather than reporting a clean one, since the
alternative is claiming the entries were released while stranding them.

Platform behavior

Windows persists through HKCU\Environment; the other platforms append a
self-identifying block to the login shell's profiles, resolving ZDOTDIR for
zsh users. Both run under a cross-process lock that covers the entire
read-modify-write rather than just the write, bounded with a timeout so a hung
peer cannot wedge the operation while the engine's own mutex is held. Both
publish through a temporary file and an atomic rename, with the file and its
directory flushed — a rename is atomic for a concurrent reader but says nothing
about bytes reaching stable storage.

A profile rewrite re-checks the file's size and modification time immediately
before the rename, so a concurrent editor's save is refused as retryable rather
than silently discarded. A symlinked profile is written through to its target
instead of being replaced by a regular file.

The platform uninstallers release the entries before deleting the data directory
that holds the records, only when they are deleting it, and keep that data when
the release fails, so a reinstall can finish the cleanup instead of leaving
entries nothing can identify. On Debian only postrm can tell purge from a
plain remove, but dpkg has deleted the package's files by then, so prerm keeps
a copy of nvpair-engine-manager under /var/lib/<package> for postrm's purge
to run. A plain apt remove keeps the engines and their PATH entries.

A manifest whose CLI resolves to a relative path is rejected with a warning
rather than anchored to the daemon's working directory, which would publish an
entry that means nothing. {install_dir} is resolved first, so a manifest
written against the documented placeholders works.

Adaptations to this tree

Two changes are not part of the feature and exist because this tree has moved
independently. Both are called out so they are reviewed as decisions rather than
skimmed as noise.

• runCommand takes a variadic environment, for install commands that declare
  overrides. The launch closure in lifecycle.go therefore accepts and ignores
  it: a launch carries its own environment separately, and the one call site
  passes none, so merging two sources there would be dead code pretending to be
  a feature.
• writeJSONAtomic keeps this tree's unique temporary filename and gains the
  file and directory flush the ownership records need. It states 0600
  explicitly rather than inheriting it from os.CreateTemp, because
  TestSettingsOverrideRestrictsExistingPermissions requires the write to
  restrict an already group-readable file, not merely avoid widening one. The
  temporary is also named after its target, since the same helper now writes
  port overrides, desired state, and PATH records.

Components audited

• Changed: nvpair-engine-manager (params, status field, consent gating),
  nvpair-tui (prompts), desktop bridge (empty-handlers.ts,
  modular-state.ts), shared types, renderer install/uninstall call sites.
• Unchanged, with evidence: nvpair-ui-broker relays engine:* params
  verbatim, and enginePortAssignmentRequest decodes only
  {engine, port, start}, so path — including its absence — passes through;
  its suite passes. The remote ec install path still never publishes, and its
  responses no longer carry path_managed.
• Excluded: the application uninstallers' --remove-user-path still releases
  every recorded entry without asking — the user already consented to those
  entries, and the uninstaller has no UI of its own.

Test plan

• Full nvpair-engine-manager Go suite passes on Linux as well as Windows.
  Running it on Linux was not optional: the permissions test above skips on
  Windows, and the first push of this branch failed on it.
  TestUninstallTerminatesRunningInstance fails in a container, but it does so
  identically on unmodified develop, so it is an environment artifact rather
  than a regression — it passes on the hosted runners.
• New consent coverage in install_path_test.go, run through the JSON-RPC
  front end: path:true publishes and reports path_managed; an omitted
  path installs without touching PATH; a declined install records only the
  installed flag and a later consented install publishes; a declined install
  over a present engine records nothing; uninstall with path:true removes the
  profile entry, with path:false keeps the entry and drops the record, and
  with no path keeps both, after which a consented uninstall still removes it.
  Also: path_managed needs an entry PAIR wrote, the last emitted state after
  uninstall and after adopting a present engine carries the final value, a
  consented uninstall drops an installed-only record, a remote install records
  only the flag, and neither peer response exposes path_managed.
• Windows: a record rename succeeds while another handle holds the file open.
• nvpair-tui tests: install waits for an answer, esc cancels, uninstall asks
  only when PAIR owns an entry, the params carry the answer, and an unasked op
  sends none.
• nvpair-ui-broker suite passes.
• go vet clean for linux, darwin, and windows; gofmt clean.
• New coverage for the layers this feature rests on, which previously had none:
  cross-handle lock exclusion and a bounded wait, a symlinked profile written
  through rather than replaced, the concurrent-edit refusal, and a ZDOTDIR
  parsing table including a trailing comment after an unquoted value and an
  unreadable .zshenv.
• Two regression tests were confirmed to fail against the previous behavior and
  pass after: republishing PATH for an engine living outside the install
  directory, and reporting failure for an unreadable ownership record.
• Desktop typecheck, lint, dead-code:check, test:unit, and
  service-contracts:check pass. New bridge tests cover the answer reaching
  engine:install / engine:uninstall, an unasked uninstall sending no
  answer, update carrying a freshly read path_managed through both steps, and
  path_managed projected onto the local status. services-api.md regenerated.
• SPDX headers pass.

Not covered by automation, and worth native verification before release:

• the consent and uninstall modals themselves (the desktop suite has no
  renderer test harness), including the nested prompt in the first-run wizard;
• real OS PATH changes, and the Windows registry functions (compiled but not
  executed by CI);
• the installer's uninstall branch, and the Debian prerm/postrm pair on a real
  apt remove and apt purge;
• live vendor installations.

Tests use temporary profiles, fake engines, and in-memory Windows PATH values
throughout, so no run can edit a developer's own account.

[kjlubick]

I'm not sure about the syncdir* and userpath* code. It's rather complicated and I got a bit lost going through it. I gave the rest of the spec and go code as good a review as I could.

[kjlubick]

IIUC, this only applies to ollama (and llama.cpp soon), right? services/nvpair-engine-manager/manifests/lmstudio.json has a "script + bash" install on Linux and similar for Windows. I think it might be better to make it more obvious with a [ollama only] or [lmstudio excluded].

[kjlubick]

Also, is there a reason we can't add lms.exe to the path anyway?

[kjlubick]

Also also, this bullet point is a bit of a run on with several em dashes. Let's break it up into more succinct sentences.

[kjlubick]

Can the edge cases go under a subheading?

[kjlubick]

What does "start?" do here? I don't seen any docs about it in this file.

[kjlubick]

"EngineStatus.path_managed is true only while the record holds an entry PAIR wrote — a Windows entry or a shell block — and is emitted after every PATH step; the control surface serves it to peers as false." confuses me. What is going on with path_managed?

[kjlubick]

This prose might be easier to understand as a flowchart

flowchart TD
    A["Engine uninstall requested"]
    B{"Engine removed or already absent?"}
    C{"Value of path parameter?"}
    D["Stop with an error<br/>Do not change PATH"]
    E["Leave PATH unchanged<br/>Delete receipt and give up PAIR ownership"]
    F{"Receipt readable or absent?"}
    G["Remove recorded entries if present<br/>Preserve user-edited shell blocks"]
    H{"Cleanup succeeded?"}
    I["Delete receipt"]
    J["Keep receipt<br/>Report an error and allow retry"]
    K["Leave PATH unchanged<br/>Keep PAIR ownership of claimed entries"]
    A --> B
    B -->|No| D
    B -->|Yes| C
    C -->|false - user said No| E
    C -->|true - user said Yes| F
    C -->|omitted - user was not asked| K
    F -->|No| J
    F -->|Yes| G
    G --> H
    H -->|No| J
    H -->|Yes| I

Loading

[kjlubick]

This is worded very strangely, as if it's the answer to the question (and I'm not sure what that question is)

[kjlubick]

Codex pointed this out:

before-remove.sh (line 43) ignores failure to save the executable. In after-remove.sh (line 69, keep_data starts at zero and changes only when an attempted cleanup returns an error. If the saved executable is absent, cleanup is skipped and the data directory is deleted anyway. PATH entries survive without their ownership records. This matters because dpkg removes package files before calling postrm.

[kjlubick]

Should we set PURGE_DATA back to 1 if this is false?

[kjlubick]

nit: I don't like switch/case when a simple if/else if would work

[kjlubick]

Do we need to try to get a file lock before we check for modification? Otherwise we might have a TOUTOC issue.

[kjlubick]

I don't think this follows https://zsh.sourceforge.io/Doc/Release/Shell-Grammar.html

For example
ZDOTDIR='$HOME/.config/zsh' should have $HOME remain literal but this expands it

[kjlubick]

Why do we need to do something complicated like that?