[immakermatty]

Why

Decisions of the Principal on 2026-09-28: there is one updater, lazurio update; the operator of an Environment may update Lazurio without a rollout, on a hosted Machine as well; a rollout may still raise a Machine that fell behind, because operators sometimes forget to update; nothing ever lowers a version. Until now the generated manual of hosted Machines forbade lazurio update, and nothing created the standard command ~/.local/bin/lazurio that root decision 0161 names. The pilot of 0.1.7 on a work VM confirmed it on 2026-09-28: lazurio is not on the operator's PATH there.

What changes

A. lazurio install creates ~/.local/bin/lazurio, a link to the selector of the install base, placed by an atomic rename.

At ~/.local/bin/lazurio	Result	Written
nothing	created	yes
link to this selector	present	no
link to the selector of a Lazurio install base (another base, or one that is gone)	replaced	yes
dangling link of any other shape	conflict	never
~/.local or ~/.local/bin is a link or not a directory	conflict (parent)	never; nothing is written through it
regular file, link to anything else, directory	conflict	never; install still succeeds and says what to do
cannot be written	failed	no; install still succeeds

Shell profiles are never edited. Whether ~/.local/bin is on PATH and whether another program named lazurio resolves first is reported with both paths, not changed.

B. The generated manual allows lazurio update on hosted Machines (Czech and English). The operator owns the version; an agent runs the update on the operator's instruction; update status is free to use; the provider's pin is a minimum. Template revision base-instructions-8 → 9 (8 shipped in v0.1.7). A test checks for every preset and both languages that no output forbids the update.

C. "Folder refresh needed". When the product renders a newer template revision than the Folder records, lazurio update, lazurio update status and the update section of the Launchpad say so with the exact command. Read-only: no automatic refresh, no button.

D. F17 addendum and the contract for the Machines role in docs/machine-handover.md: install when absent, raise when below the pin, never lower, never run lazurio update, verify the PATH entry from install --json.

What does not change

• No new rollback machinery; update rollback stays as it is.
• Machines itself and the root decision register are not edited here; root 0161 is amended by its own pull request.
• No Windows work.

Known gaps, stated plainly

1. install of the same version does not repair a dangling selector or a damaged active executable.
2. The first update from v0.1.7 or older runs the old updater, which does not report the refresh; update status of the new version does.
3. On a workstation without a service unit, lazurio update needs --folder to know the Folder.
4. No warning on a shared Team Environment that an update affects every operator there.

Verification

bun run check on this head, run independently by the delegating agent: see the comment below. No test touches the real home directory.

Refs #50

🤖 Generated with Claude Code

[immakermatty]

Independent bun run check on 1d7287d (macOS arm64): 724 pass, 4 skip (systemd tests), 0 fail; public guard PASS; standalone smoke PASS.

[agentrozjedemeai]

Exact-head review of 1d7287d — CHANGES_REQUESTED.

1. [P1] src/update/path-entry.ts:146-161: refuse symlinked ancestors before touching the standard entry. lstat(path) follows symlinks in ~/.local / ~/.local/bin, and ensureDirectory accepts EEXIST without checking that the existing component is a real directory. Reproduced with a temporary HOME whose .local/bin is a symlink to another directory: ensurePathEntry returned created and wrote lazurio in that other directory. If that directory already holds a replaceable link, the rename can replace it there too. This escapes the promised ~/.local/bin custody boundary. Check each existing parent with lstat (and fail/report rather than following a symlink); add a regression with symlinked bin/.local.

2. [P1] src/update/path-entry.ts:73-78: a dangling symlink is not proof of Lazurio ownership. Reproduced with ~/.local/bin/lazurio -> <missing foreign-tool>: the function returned replaced and changed that link to the Lazurio selector. A broken link can be someone else's intentionally installed entry; it may point to a temporarily unmounted target. This contradicts the requirement not to replace entries that are not Lazurio's. Keep a foreign dangling link as conflict, or accept only a verifiably Lazurio-owned selector shape/path. Update the documented blanket 'dangling link' replacement rule and test the foreign case.

The existing focused suite passed locally after bun install --frozen-lockfile: 56 passed, 0 failed across path-entry, Folder-refresh, generated-manual and offline-install tests. Both required exact-head checks, check (macos-14) and check (ubuntu-24.04), are green. The Czech/English update instructions are aligned in the inspected generated templates; the offline install below-floor and high-water gates are intact. These two filesystem-custody findings block approval despite green checks. No merge requested.

[agentrozjedemeai]

@immakermatty Exact-head re-review of 6bcf037 — APPROVED. The two previously blocking findings are fixed: ~/.local and ~/.local/bin are lstat-checked as plain directories before creating/replacing the PATH entry, and a foreign dangling link stays untouched while only a Lazurio-selector-shaped missing-base link can be replaced. The linked-parent and three foreign-dangling regression cases pass. Independent disposable-clone validation: focused tests 58 pass, 0 fail; bun run check 726 pass, 4 skip, 0 fail, plus lint, typecheck, check:public, build:proof and smoke:proof; git diff --check passes on the frozen PR diff. Both exact-head required checks, check (macos-14) and check (ubuntu-24.04), are SUCCESS; no unresolved review threads. No merge performed.