instar 1.3.1201 → 1.3.1202

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-08-25T23:10:03.683Z",
-  "instarVersion": "1.3.1201",
+  "generatedAt": "2026-08-25T23:24:38.827Z",
+  "instarVersion": "1.3.1202",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {
@@ -778,7 +778,7 @@
       "type": "cli-command",
       "domain": "setup",
       "sourcePath": "src/cli.ts",
-      "contentHash": "3dfaa8d2178096f872f81fd270169cdc15e253ed9de28b994359268815ded5fa",
+      "contentHash": "0982533d99db0f9f2ddf7bfba23f59b5a30627b7c4b15601e5ebebca2294f855",
       "since": "2025-01-01"
     },
     "cli:setup": {
@@ -786,7 +786,7 @@
       "type": "cli-command",
       "domain": "setup",
       "sourcePath": "src/cli.ts",
-      "contentHash": "3dfaa8d2178096f872f81fd270169cdc15e253ed9de28b994359268815ded5fa",
+      "contentHash": "0982533d99db0f9f2ddf7bfba23f59b5a30627b7c4b15601e5ebebca2294f855",
       "since": "2025-01-01"
     },
     "cli:add": {
@@ -794,7 +794,7 @@
       "type": "cli-command",
       "domain": "setup",
       "sourcePath": "src/cli.ts",
-      "contentHash": "3dfaa8d2178096f872f81fd270169cdc15e253ed9de28b994359268815ded5fa",
+      "contentHash": "0982533d99db0f9f2ddf7bfba23f59b5a30627b7c4b15601e5ebebca2294f855",
       "since": "2025-01-01"
     },
     "cli:backup": {
@@ -802,7 +802,7 @@
       "type": "cli-command",
       "domain": "operations",
       "sourcePath": "src/cli.ts",
-      "contentHash": "3dfaa8d2178096f872f81fd270169cdc15e253ed9de28b994359268815ded5fa",
+      "contentHash": "0982533d99db0f9f2ddf7bfba23f59b5a30627b7c4b15601e5ebebca2294f855",
       "since": "2025-01-01"
     },
     "cli:git": {
@@ -810,7 +810,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "3dfaa8d2178096f872f81fd270169cdc15e253ed9de28b994359268815ded5fa",
+      "contentHash": "0982533d99db0f9f2ddf7bfba23f59b5a30627b7c4b15601e5ebebca2294f855",
       "since": "2025-01-01"
     },
     "cli:memory": {
@@ -818,7 +818,7 @@
       "type": "cli-command",
       "domain": "memory",
       "sourcePath": "src/cli.ts",
-      "contentHash": "3dfaa8d2178096f872f81fd270169cdc15e253ed9de28b994359268815ded5fa",
+      "contentHash": "0982533d99db0f9f2ddf7bfba23f59b5a30627b7c4b15601e5ebebca2294f855",
       "since": "2025-01-01"
     },
     "cli:knowledge": {
@@ -826,7 +826,7 @@
       "type": "cli-command",
       "domain": "memory",
       "sourcePath": "src/cli.ts",
-      "contentHash": "3dfaa8d2178096f872f81fd270169cdc15e253ed9de28b994359268815ded5fa",
+      "contentHash": "0982533d99db0f9f2ddf7bfba23f59b5a30627b7c4b15601e5ebebca2294f855",
       "since": "2025-01-01"
     },
     "cli:semantic": {
@@ -834,7 +834,7 @@
       "type": "cli-command",
       "domain": "memory",
       "sourcePath": "src/cli.ts",
-      "contentHash": "3dfaa8d2178096f872f81fd270169cdc15e253ed9de28b994359268815ded5fa",
+      "contentHash": "0982533d99db0f9f2ddf7bfba23f59b5a30627b7c4b15601e5ebebca2294f855",
       "since": "2025-01-01"
     },
     "cli:intent": {
@@ -842,7 +842,7 @@
       "type": "cli-command",
       "domain": "intent",
       "sourcePath": "src/cli.ts",
-      "contentHash": "3dfaa8d2178096f872f81fd270169cdc15e253ed9de28b994359268815ded5fa",
+      "contentHash": "0982533d99db0f9f2ddf7bfba23f59b5a30627b7c4b15601e5ebebca2294f855",
       "since": "2025-01-01"
     },
     "cli:feedback": {
@@ -850,7 +850,7 @@
       "type": "cli-command",
       "domain": "feedback",
       "sourcePath": "src/cli.ts",
-      "contentHash": "3dfaa8d2178096f872f81fd270169cdc15e253ed9de28b994359268815ded5fa",
+      "contentHash": "0982533d99db0f9f2ddf7bfba23f59b5a30627b7c4b15601e5ebebca2294f855",
       "since": "2025-01-01"
     },
     "cli:server": {
@@ -858,7 +858,7 @@
       "type": "cli-command",
       "domain": "server",
       "sourcePath": "src/cli.ts",
-      "contentHash": "3dfaa8d2178096f872f81fd270169cdc15e253ed9de28b994359268815ded5fa",
+      "contentHash": "0982533d99db0f9f2ddf7bfba23f59b5a30627b7c4b15601e5ebebca2294f855",
       "since": "2025-01-01"
     },
     "cli:status": {
@@ -866,7 +866,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "3dfaa8d2178096f872f81fd270169cdc15e253ed9de28b994359268815ded5fa",
+      "contentHash": "0982533d99db0f9f2ddf7bfba23f59b5a30627b7c4b15601e5ebebca2294f855",
       "since": "2025-01-01"
     },
     "cli:user": {
@@ -874,7 +874,7 @@
       "type": "cli-command",
       "domain": "users",
       "sourcePath": "src/cli.ts",
-      "contentHash": "3dfaa8d2178096f872f81fd270169cdc15e253ed9de28b994359268815ded5fa",
+      "contentHash": "0982533d99db0f9f2ddf7bfba23f59b5a30627b7c4b15601e5ebebca2294f855",
       "since": "2025-01-01"
     },
     "cli:relationship": {
@@ -882,7 +882,7 @@
       "type": "cli-command",
       "domain": "relationships",
       "sourcePath": "src/cli.ts",
-      "contentHash": "3dfaa8d2178096f872f81fd270169cdc15e253ed9de28b994359268815ded5fa",
+      "contentHash": "0982533d99db0f9f2ddf7bfba23f59b5a30627b7c4b15601e5ebebca2294f855",
       "since": "2025-01-01"
     },
     "cli:job": {
@@ -890,7 +890,7 @@
       "type": "cli-command",
       "domain": "scheduling",
       "sourcePath": "src/cli.ts",
-      "contentHash": "3dfaa8d2178096f872f81fd270169cdc15e253ed9de28b994359268815ded5fa",
+      "contentHash": "0982533d99db0f9f2ddf7bfba23f59b5a30627b7c4b15601e5ebebca2294f855",
       "since": "2025-01-01"
     },
     "cli:lifeline": {
@@ -898,7 +898,7 @@
       "type": "cli-command",
       "domain": "communication",
       "sourcePath": "src/cli.ts",
-      "contentHash": "3dfaa8d2178096f872f81fd270169cdc15e253ed9de28b994359268815ded5fa",
+      "contentHash": "0982533d99db0f9f2ddf7bfba23f59b5a30627b7c4b15601e5ebebca2294f855",
       "since": "2025-01-01"
     },
     "cli:list": {
@@ -906,7 +906,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "3dfaa8d2178096f872f81fd270169cdc15e253ed9de28b994359268815ded5fa",
+      "contentHash": "0982533d99db0f9f2ddf7bfba23f59b5a30627b7c4b15601e5ebebca2294f855",
       "since": "2025-01-01"
     },
     "cli:autostart": {
@@ -914,7 +914,7 @@
       "type": "cli-command",
       "domain": "operations",
       "sourcePath": "src/cli.ts",
-      "contentHash": "3dfaa8d2178096f872f81fd270169cdc15e253ed9de28b994359268815ded5fa",
+      "contentHash": "0982533d99db0f9f2ddf7bfba23f59b5a30627b7c4b15601e5ebebca2294f855",
       "since": "2025-01-01"
     },
     "cli:migrate": {
@@ -922,7 +922,7 @@
       "type": "cli-command",
       "domain": "updates",
       "sourcePath": "src/cli.ts",
-      "contentHash": "3dfaa8d2178096f872f81fd270169cdc15e253ed9de28b994359268815ded5fa",
+      "contentHash": "0982533d99db0f9f2ddf7bfba23f59b5a30627b7c4b15601e5ebebca2294f855",
       "since": "2025-01-01"
     },
     "cli:machines": {
@@ -930,7 +930,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "3dfaa8d2178096f872f81fd270169cdc15e253ed9de28b994359268815ded5fa",
+      "contentHash": "0982533d99db0f9f2ddf7bfba23f59b5a30627b7c4b15601e5ebebca2294f855",
       "since": "2025-01-01"
     },
     "cli:whoami": {
@@ -938,7 +938,7 @@
       "type": "cli-command",
       "domain": "identity",
       "sourcePath": "src/cli.ts",
-      "contentHash": "3dfaa8d2178096f872f81fd270169cdc15e253ed9de28b994359268815ded5fa",
+      "contentHash": "0982533d99db0f9f2ddf7bfba23f59b5a30627b7c4b15601e5ebebca2294f855",
       "since": "2025-01-01"
     },
     "cli:pair": {
@@ -946,7 +946,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "3dfaa8d2178096f872f81fd270169cdc15e253ed9de28b994359268815ded5fa",
+      "contentHash": "0982533d99db0f9f2ddf7bfba23f59b5a30627b7c4b15601e5ebebca2294f855",
       "since": "2025-01-01"
     },
     "cli:join": {
@@ -954,7 +954,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "3dfaa8d2178096f872f81fd270169cdc15e253ed9de28b994359268815ded5fa",
+      "contentHash": "0982533d99db0f9f2ddf7bfba23f59b5a30627b7c4b15601e5ebebca2294f855",
       "since": "2025-01-01"
     },
     "cli:wakeup": {
@@ -962,7 +962,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "3dfaa8d2178096f872f81fd270169cdc15e253ed9de28b994359268815ded5fa",
+      "contentHash": "0982533d99db0f9f2ddf7bfba23f59b5a30627b7c4b15601e5ebebca2294f855",
       "since": "2025-01-01"
     },
     "cli:leave": {
@@ -970,7 +970,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "3dfaa8d2178096f872f81fd270169cdc15e253ed9de28b994359268815ded5fa",
+      "contentHash": "0982533d99db0f9f2ddf7bfba23f59b5a30627b7c4b15601e5ebebca2294f855",
       "since": "2025-01-01"
     },
     "cli:doctor": {
@@ -978,7 +978,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "3dfaa8d2178096f872f81fd270169cdc15e253ed9de28b994359268815ded5fa",
+      "contentHash": "0982533d99db0f9f2ddf7bfba23f59b5a30627b7c4b15601e5ebebca2294f855",
       "since": "2025-01-01"
     },
     "cli:review": {
@@ -986,7 +986,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "3dfaa8d2178096f872f81fd270169cdc15e253ed9de28b994359268815ded5fa",
+      "contentHash": "0982533d99db0f9f2ddf7bfba23f59b5a30627b7c4b15601e5ebebca2294f855",
       "since": "2025-01-01"
     },
     "cli:nuke": {
@@ -994,7 +994,7 @@
       "type": "cli-command",
       "domain": "operations",
       "sourcePath": "src/cli.ts",
-      "contentHash": "3dfaa8d2178096f872f81fd270169cdc15e253ed9de28b994359268815ded5fa",
+      "contentHash": "0982533d99db0f9f2ddf7bfba23f59b5a30627b7c4b15601e5ebebca2294f855",
       "since": "2025-01-01"
     },
     "cli:playbook": {
@@ -1002,7 +1002,7 @@
       "type": "cli-command",
       "domain": "context",
       "sourcePath": "src/cli.ts",
-      "contentHash": "3dfaa8d2178096f872f81fd270169cdc15e253ed9de28b994359268815ded5fa",
+      "contentHash": "0982533d99db0f9f2ddf7bfba23f59b5a30627b7c4b15601e5ebebca2294f855",
       "since": "2025-01-01"
     },
     "cli:dev-preflight": {
@@ -1010,7 +1010,7 @@
       "type": "cli-command",
       "domain": "development",
       "sourcePath": "src/cli.ts",
-      "contentHash": "3dfaa8d2178096f872f81fd270169cdc15e253ed9de28b994359268815ded5fa",
+      "contentHash": "0982533d99db0f9f2ddf7bfba23f59b5a30627b7c4b15601e5ebebca2294f855",
       "since": "2025-01-01"
     },
     "cli:dev-ci-failures": {
@@ -1018,7 +1018,7 @@
       "type": "cli-command",
       "domain": "development",
       "sourcePath": "src/cli.ts",
-      "contentHash": "3dfaa8d2178096f872f81fd270169cdc15e253ed9de28b994359268815ded5fa",
+      "contentHash": "0982533d99db0f9f2ddf7bfba23f59b5a30627b7c4b15601e5ebebca2294f855",
       "since": "2025-01-01"
     },
     "cli:dev-profile-node": {
@@ -1026,7 +1026,7 @@
       "type": "cli-command",
       "domain": "development",
       "sourcePath": "src/cli.ts",
-      "contentHash": "3dfaa8d2178096f872f81fd270169cdc15e253ed9de28b994359268815ded5fa",
+      "contentHash": "0982533d99db0f9f2ddf7bfba23f59b5a30627b7c4b15601e5ebebca2294f855",
       "since": "2025-01-01"
     },
     "template:build-stop-hook.sh": {

package/src/data/standards-guard-index.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "generatedFrom": "source-tree",
   "registrySha256": "8e6606a6722433c5ffc15b3870402283c5406083a14cdbd0e18e735731e2aae2",
-  "packageVersion": "1.3.1201",
+  "packageVersion": "1.3.1202",
   "guards": [
     {
       "ref": "docs/audits/phase-b/f10-triage.md",

package/src/data/standards-guard-index.meta.json

@@ -1,5 +1,5 @@
 {
-  "sha256": "7cc7eace9958f0daae3b9c37eadf2541b2b5a6bd3b16bf0f7f1cf281a86dadca",
+  "sha256": "83f0ffdca366864eaa3886d09c6b1061f7b2b4af5ff2226359aeab20bba7fcd9",
   "registrySha256": "8e6606a6722433c5ffc15b3870402283c5406083a14cdbd0e18e735731e2aae2",
-  "packageVersion": "1.3.1201"
+  "packageVersion": "1.3.1202"
 }

package/src/data/standards-registry.meta.json

@@ -2,5 +2,5 @@
   "sha256": "8e6606a6722433c5ffc15b3870402283c5406083a14cdbd0e18e735731e2aae2",
   "articleCount": 90,
   "generatedFrom": "docs/STANDARDS-REGISTRY.md",
-  "packageVersion": "1.3.1201"
+  "packageVersion": "1.3.1202"
 }

package/upgrades/1.3.1202.md

@@ -0,0 +1,72 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+`instar autostart install` on Linux wrote a systemd **user** service, enabled it, started it, and
+reported *"Your agent will start automatically when you log in."* Every one of those steps genuinely
+succeeded — and the sentence was true in a way that meant **never** on a machine nobody logs into.
+
+A per-user systemd service only runs while that user holds a login session. It does **not** start at
+boot unless **lingering** is enabled for the account, and nothing enabled it or said so. On a headless
+host the agent came up when someone connected over SSH and died the moment they disconnected.
+
+`installLinuxSystemdService` now calls a new `ensureLinuxLingering()` after enabling the unit. It
+reads the current linger state, attempts `loginctl enable-linger <user>` when it is off, and then
+**re-reads the state to verify the effect** rather than trusting the exit code — a command that
+returns success while changing nothing is reported as not done, because that is the exact defect
+class being fixed. The outcome reaches the CLI, which prints what actually happened:
+
+- **starts at boot** — lingering is on, with nobody logged in.
+- **starts at login, NOT at boot** — the attempt was refused (it usually needs root). The message says
+  plainly that on an unattended machine this means never, and names the exact one-line fix.
+- **starts at login; boot behaviour undetermined** — no `loginctl` on this system (a container, a
+  non-systemd distro). No fix instruction is printed, because it would not work there.
+
+There is deliberately **no `sudo` attempt**. A setup step that silently escalates privilege takes an
+authority the operator did not grant it; naming the command keeps that decision with the human. The
+install still returns success in every case — a login-only service is a working install, it is just
+not the thing the old message claimed.
+
+macOS is untouched, and Windows already returns false.
+
+## What to Tell Your User
+
+If you run instar on Linux, "auto-start installed" has not meant "starts when the machine boots" — it
+meant "starts when you log in", and on a machine you never log into that is never. That is why an
+agent on a headless Linux box could come up when you connected and vanish when you disconnected.
+
+Instar now turns on the missing setting where it can, and where it cannot (it usually needs
+administrator rights) it tells you so plainly and gives you the one command to run. Nothing changes
+on macOS.
+
+## Summary of New Capabilities
+
+No new capabilities. A Linux auto-start install now completes the step it was missing, and reports
+which of "starts at boot" or "starts at login only" is actually true.
+
+## Evidence
+
+Found on the first headless Linux host — WSL2 / Ubuntu 26.04. The reproduction is the contradiction
+itself: `instar autostart install` reported success and `systemctl --user is-enabled` returned
+`enabled`, while `loginctl show-user echo -p Linger` returned `Linger=no` — an enabled service that
+would never start at boot.
+
+Both live paths were exercised against a real `loginctl` on that host: an account with lingering on
+returns `enabled-already`, and an unknown account returns `unavailable` rather than being
+misreported as "off". That second case also surfaced a smaller leak now fixed — `loginctl` writes
+`Failed to look up user <x>` to stderr, which was reaching the operator's terminal on a path the
+code handles cleanly; stderr is now piped.
+
+12 unit tests. Both parse directions; the unanswerable case kept distinct from "no" (they need
+different answers, and merging them would print a fix instruction that cannot work where it does not
+apply); the already-on path asserting the privileged command is **not** re-run; verification-over-exit
+-code, where a fake enable that exits 0 and changes nothing yields `needs-privilege`; a polkit
+refusal; a blind-enable guard asserting the command is never run when the state is unreadable; and
+four message assertions — including a regression guard that the old unconditional sentence is never
+rendered for an outcome that does not deserve it.
+
+The two failure paths are covered by injected dependencies rather than by breaking a live machine's
+configuration, which is stated here rather than implied.

package/upgrades/linux-autostart-lingering.eli16.md

@@ -0,0 +1,45 @@
+# "Starts automatically" didn't mean at boot on Linux — Plain-English Overview
+
+> The one-line version: on Linux, instar set itself to start automatically and then told you it would start when you log in — which on a machine nobody logs into means never; this turns on the missing setting, checks it actually worked, and says which of the two is really true.
+
+## The problem in one breath
+
+`instar autostart install` on Linux writes a correct startup service, switches it on, starts it, and reports "your agent will start automatically when you log in." That sentence is true and useless: on Linux a per-user service only runs while that user has a login session open, and it does not start when the machine boots unless a separate setting is turned on. It wasn't. On a headless machine the agent came up when someone connected over SSH and died the moment they disconnected.
+
+## What already exists
+
+- **`instar autostart install`** — sets your agent to start on its own, so you don't have to launch it by hand after a restart.
+- **The macOS path** — writes a login item. Works, and has always worked, because on a Mac somebody is logged in.
+- **The Linux path** — writes a systemd user service, enables it, and starts it. Every one of those steps genuinely succeeds. The gap is the step nobody wrote.
+
+## What this adds
+
+After enabling the service on Linux, instar now also tries to turn on "lingering" — the setting that lets your account's services keep running when you're not logged in, which is what makes them start at boot. Then it checks whether that actually worked, and prints the truth accordingly rather than an unconditional promise.
+
+- If lingering is on, it says the agent will start when the machine boots with nobody logged in.
+- If turning it on was refused (it usually needs administrator rights), it says plainly that the agent starts at login but **not** at boot, that on an unattended machine this means never, and gives you the exact one-line command to fix it.
+- If the system can't answer the question at all — a container, or a Linux without this component — it says the agent starts at login and that boot behaviour couldn't be determined, rather than guessing.
+
+## The new pieces
+
+- **A lingering check** — asks the system whether your account's services survive logout. It deliberately distinguishes "no" from "couldn't ask", because those need different answers and merging them would print a fix instruction that cannot work where it doesn't apply.
+- **A lingering enabler** — tries to turn it on, then *re-reads the state to confirm it took effect*. It does not trust the command's exit code, because a step reporting success while producing no effect is the exact defect being fixed here.
+- **An honest message** — one sentence per real outcome, replacing one sentence used for all of them.
+
+## The safeguards
+
+**It never escalates privilege behind your back.** Turning on lingering usually requires administrator rights. Instar tries the plain command; if the system refuses, it tells you the command to run rather than quietly reaching for `sudo`. A setup step that silently escalates is worse than one that asks.
+
+**It cannot claim success it didn't achieve.** The outcome is established by reading the state back afterwards, not by the command exiting cleanly. A command that returns success and changes nothing is reported as "not done", which is the honest answer and the one that gets the agent actually running.
+
+**It doesn't make the install fail.** A service that works at login is still a working install — it's just not the thing the old message claimed. The install still succeeds; only the description of what you got becomes accurate.
+
+**macOS is untouched.** Not a line of the Mac path changes, and lingering is a Linux-only concept.
+
+## What ships when
+
+One change, one PR: the lingering attempt, the verification, the honest message, and twelve tests — including a regression guard asserting the old unconditional sentence is never printed for an outcome that doesn't deserve it.
+
+## What you actually need to decide
+
+Whether instar should attempt to enable lingering during a Linux auto-start install and report which of "starts at boot" or "starts at login only" is actually true — rather than always claiming the second — yes or no.

package/upgrades/side-effects/linux-autostart-lingering.md

@@ -0,0 +1,144 @@
+# Side-Effects Review — Linux auto-start lingering (boot vs login)
+
+**Version / slug:** `linux-autostart-lingering`
+**Date:** `2026-08-25`
+**Author:** `Echo`
+**Second-pass reviewer:** `not run — see the Second-pass section`
+
+## Summary of the change
+
+`instar autostart install` on Linux writes a systemd **user** service, enables it, starts it, and the CLI reports *"Your agent will start automatically when you log in."* A per-user systemd service only runs while that user holds a login session, and does not start at boot unless **lingering** is enabled for the account. It was not, and nothing said so — on a headless host the agent came up on SSH connect and died on disconnect.
+
+This change: after enabling the unit, `installLinuxSystemdService` calls a new `ensureLinuxLingering()`, which reads the current linger state, attempts `loginctl enable-linger <user>` when it is off, and then **re-reads the state to verify the effect** rather than trusting the exit code. The outcome (`enabled-already` / `enabled-now` / `needs-privilege` / `unavailable`) is carried to the CLI, which prints a message matching what actually happened instead of one sentence for all cases.
+
+Files touched: `src/commands/setup.ts` (`readLingerState`, `ensureLinuxLingering`, `describeLingerOutcome`, `currentSystemdUser`, outcome carrier; one call added inside `installLinuxSystemdService`), `src/cli.ts` (the `autostart install` report), `tests/unit/linux-autostart-lingering.test.ts` (+12 tests).
+
+## Decision-point inventory
+
+- `installLinuxSystemdService` — **modify** — one added call after the existing enable/start. Its boolean contract is unchanged; a login-only service is still a successful install.
+- `autostart install` CLI output — **modify** — the success message becomes outcome-dependent. The failure branch is untouched.
+- `installAutoStart` — **pass-through** — signature and boolean semantics unchanged (four callers depend on it: `cli.ts`, `PostUpdateMigrator`, `TelegramLifeline`, and the migrator's boot-wrapper regeneration). The outcome travels via a module-level carrier read with `takeLastLingerOutcome()`, deliberately so those callers need no change.
+
+---
+
+## 1. Over-block
+
+No block/allow surface — over-block not applicable. Nothing is refused, gated, or filtered; the change adds one system call and changes what a message says.
+
+---
+
+## 2. Under-block
+
+No block/allow surface — under-block not applicable. The nearest analogue is what the change still cannot fix, stated plainly:
+
+- **A refusal is reported, not resolved.** When polkit denies `enable-linger` (the common case when not root), the agent still starts only at login until the operator runs the named command. This is deliberate — see §4.
+- **`unavailable` is genuinely unknown, not assumed good.** A container without `loginctl` gets "couldn't be determined", and no fix instruction is printed, because the instruction would not work there.
+- **Nothing re-checks later.** If lingering is turned off after install, nothing notices. Out of scope for an install-time step; the guard-posture surfaces are where a standing check would belong.
+
+---
+
+## 3. Level-of-abstraction fit
+
+Correct layer: the defect is that the Linux install path performs an incomplete install, so the missing step belongs in the Linux install path. No new layer, no new caller, no new subsystem.
+
+The CLI split is deliberate. Reporting is the CLI's job and the install function's job is to install — so the install function establishes the fact and the CLI renders it. Folding lingering into `installAutoStart`'s boolean was rejected: a login-only service is a working install, and returning `false` for it would make `PostUpdateMigrator` log a spurious error and could make a migration look failed when it succeeded.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — this change has no block/allow surface.
+
+It performs one idempotent system configuration step and reports the result. It holds no authority over any agent behaviour and gates nothing.
+
+The one authority-adjacent decision is what it does **not** do: there is no `sudo` attempt. A setup step that silently escalates privilege takes an authority the operator did not grant it; naming the command instead keeps the decision with the human. That is a deliberate design choice, not an omission.
+
+---
+
+## 4b. Judgment-point check (Judgment Within Floors standard)
+
+No new static heuristic at a competing-signals decision point. The domain is enumerable and binary: lingering is on, off, or unreadable. There are no competing live signals to weigh — one query, one answer, and the "unreadable" case is carried explicitly rather than collapsed into either verdict.
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** none. The call runs after the existing `daemon-reload` / `enable` / `start` sequence and changes none of them.
+- **Double-fire:** `enable-linger` is idempotent, and the `enabled-already` branch skips the call entirely, so a repeat install runs no privileged command needlessly. `PostUpdateMigrator` regenerates auto-start on update and will therefore re-check lingering on every update — a read, then a no-op.
+- **Races:** none introduced. Two concurrent installs would both read, possibly both enable (idempotent), and both verify.
+- **Feedback loops:** none.
+- **Carrier lifetime:** `takeLastLingerOutcome()` clears on read, so a later caller cannot pick up a stale outcome from an earlier install. Null on macOS and before any install, where the CLI falls back to the original message.
+- **PostUpdateMigrator:** calls `installAutoStart` but not the carrier, so it is unaffected and prints nothing new. Intentional — an update is not the moment to surface an install-time instruction.
+
+---
+
+## 6. External surfaces
+
+- **Other agents on the same machine:** `enable-linger` is per-user, so enabling it for the account running instar affects every service that account owns. On a dedicated agent account this is the intent; on a shared login it means that user's other services also survive logout. Worth naming, but it is the setting the operator would run by hand anyway.
+- **Install base:** Linux only. macOS is untouched and Windows already returns false.
+- **External systems:** none.
+- **Persistent state:** `enable-linger` writes `/var/lib/systemd/linger/<user>`, owned by systemd. Removing it is `loginctl disable-linger <user>`.
+- **Timing:** one or two bounded `loginctl` calls (5s timeout) at install time only. Not on any hot path.
+- **Operator surface (Mobile-Complete Operator Actions):** the change adds no operator-facing *action*. It changes an existing CLI message and, in the refusal case, hands the operator a one-line command — which is the correct surface, because the action requires root on that machine's shell and no dashboard control could perform it. No PIN-gated or approval-class route is added.
+
+---
+
+## 6b. Operator-surface quality (Operator-Surface Quality standard)
+
+No operator surface — not applicable. No dashboard renderer, approval page, or grant/revoke/secret-drop form is touched. (`src/cli.ts` is a terminal message, not a dashboard surface.)
+
+---
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**Machine-local BY DESIGN.** Lingering is a property of one account on one machine's init system; whether machine A's agent survives logout says nothing about machine B, and each machine installs its own auto-start. Replicating it would be meaningless.
+
+- **User-facing notices:** none — the change emits no Telegram/Slack/attention output. It prints to the terminal of the person running the command. One-voice gating not applicable.
+- **Durable state:** none instar-owned. The systemd linger marker is machine-local by definition and cannot strand on topic transfer.
+- **Generated URLs:** none.
+
+---
+
+## 8. Rollback cost
+
+- **Hot-fix release:** revert both files, ship as a patch. Pure code.
+- **Data migration:** none instar-owned. Any `linger` markers already set stay set — which is the desired state anyway, and is reversible with `loginctl disable-linger <user>`.
+- **Agent state repair:** none. Reverting restores the previous message; already-installed services keep working exactly as they do now.
+- **User visibility:** the message reverts to the old unconditional sentence. No functional regression.
+
+---
+
+## Conclusion
+
+The review produced one design change: the outcome travels to the CLI through a read-and-clear carrier rather than by widening `installAutoStart`'s return type. Widening it would have touched four callers, and `PostUpdateMigrator` treats `false` as an error — so a login-only-but-working install would have started logging spurious migration failures. The carrier keeps the blast radius to the two files that actually care.
+
+The second design point worth recording is the refusal to call `sudo`. It makes the fix incomplete in the common non-root case, and that is the right trade: a setup step that silently escalates privilege is a worse defect than the one being fixed.
+
+Verification is honest about its own limits: the `enabled-already` and `unavailable` paths were exercised against a real `loginctl` on the Linux host, and the two failure paths (`needs-privilege` via refusal, and via a command that exits 0 while changing nothing) are covered by injected dependencies rather than by breaking a live machine's configuration.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** none — not spawned.
+**Independent read of the artifact: NOT PERFORMED.**
+
+Recorded rather than glossed. This change is not in the Phase-5 trigger list — no messaging block/allow, no session lifecycle, no coherence/idempotency/trust surface, and nothing named sentinel/guard/gate/watchdog. It is an install-time configuration step with no authority over agent behaviour.
+
+A reviewer subagent was additionally not available: a standing operator instruction in the authoring session forbids delegating to subagents unless explicitly asked. The PR is the review surface. If an independent read is wanted before merge, it can be run on request.
+
+---
+
+## Evidence pointers
+
+- Live reproduction (WSL2 / Ubuntu 26.04, headless): `instar autostart install` reported success and `systemctl --user is-enabled` returned `enabled`, while `loginctl show-user echo -p Linger` returned `Linger=no` — an enabled service that would not start at boot.
+- 12 unit tests. Both parse directions; the unanswerable case kept distinct from "no"; the no-op-when-already-on path asserting the privileged command is *not* re-run; verification-over-exit-code (a fake enable that exits 0 and changes nothing yields `needs-privilege`); a polkit refusal; the blind-enable guard (`unavailable` never runs the command); and four message assertions including a regression guard that the old unconditional sentence is never rendered for a non-booting outcome.
+- The fix was authored on macOS and the live linger paths were exercised on the Linux host that exposed the defect.
+
+---
+
+## Class-Closure Declaration (display-only mirror)
+
+No agent-authored-artifact defect — not applicable. The defect is in hand-written TypeScript, not an LLM prompt, hook, config, skill, or standards text. No self-triggered controller is added or modified: the change adds no loop, monitor, sentinel, reaper, scheduler, or recovery path — it is a one-shot install-time step with no timer and no re-drive.