instar 1.1.1 → 1.1.2

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-20T20:25:25.571Z",
-  "instarVersion": "1.1.1",
+  "generatedAt": "2026-05-20T22:26:32.053Z",
+  "instarVersion": "1.1.2",
   "entryCount": 190,
   "entries": {
     "hook:session-start": {
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "a5a854fd1aa35f15f48183ddf263d8a0cb2dc7f67e3c513a92b4acdc0c6d28f1",
+      "contentHash": "808fbff652a75bc43ece5a00aa1f6d2ab1753d085c7ca75b3b3db6cea63a39ee",
       "since": "2025-01-01"
     },
     "hook:dangerous-command-guard": {
@@ -20,7 +20,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/dangerous-command-guard.sh",
-      "contentHash": "a5a854fd1aa35f15f48183ddf263d8a0cb2dc7f67e3c513a92b4acdc0c6d28f1",
+      "contentHash": "808fbff652a75bc43ece5a00aa1f6d2ab1753d085c7ca75b3b3db6cea63a39ee",
       "since": "2025-01-01"
     },
     "hook:grounding-before-messaging": {
@@ -29,7 +29,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/grounding-before-messaging.sh",
-      "contentHash": "a5a854fd1aa35f15f48183ddf263d8a0cb2dc7f67e3c513a92b4acdc0c6d28f1",
+      "contentHash": "808fbff652a75bc43ece5a00aa1f6d2ab1753d085c7ca75b3b3db6cea63a39ee",
       "since": "2025-01-01"
     },
     "hook:compaction-recovery": {
@@ -38,7 +38,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/compaction-recovery.sh",
-      "contentHash": "a5a854fd1aa35f15f48183ddf263d8a0cb2dc7f67e3c513a92b4acdc0c6d28f1",
+      "contentHash": "808fbff652a75bc43ece5a00aa1f6d2ab1753d085c7ca75b3b3db6cea63a39ee",
       "since": "2025-01-01"
     },
     "hook:external-operation-gate": {
@@ -47,7 +47,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-operation-gate.js",
-      "contentHash": "a5a854fd1aa35f15f48183ddf263d8a0cb2dc7f67e3c513a92b4acdc0c6d28f1",
+      "contentHash": "808fbff652a75bc43ece5a00aa1f6d2ab1753d085c7ca75b3b3db6cea63a39ee",
       "since": "2025-01-01"
     },
     "hook:deferral-detector": {
@@ -56,7 +56,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/deferral-detector.js",
-      "contentHash": "a5a854fd1aa35f15f48183ddf263d8a0cb2dc7f67e3c513a92b4acdc0c6d28f1",
+      "contentHash": "808fbff652a75bc43ece5a00aa1f6d2ab1753d085c7ca75b3b3db6cea63a39ee",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -65,7 +65,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "a5a854fd1aa35f15f48183ddf263d8a0cb2dc7f67e3c513a92b4acdc0c6d28f1",
+      "contentHash": "808fbff652a75bc43ece5a00aa1f6d2ab1753d085c7ca75b3b3db6cea63a39ee",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -74,7 +74,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "a5a854fd1aa35f15f48183ddf263d8a0cb2dc7f67e3c513a92b4acdc0c6d28f1",
+      "contentHash": "808fbff652a75bc43ece5a00aa1f6d2ab1753d085c7ca75b3b3db6cea63a39ee",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-collector": {
@@ -83,7 +83,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "a5a854fd1aa35f15f48183ddf263d8a0cb2dc7f67e3c513a92b4acdc0c6d28f1",
+      "contentHash": "808fbff652a75bc43ece5a00aa1f6d2ab1753d085c7ca75b3b3db6cea63a39ee",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -92,7 +92,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "a5a854fd1aa35f15f48183ddf263d8a0cb2dc7f67e3c513a92b4acdc0c6d28f1",
+      "contentHash": "808fbff652a75bc43ece5a00aa1f6d2ab1753d085c7ca75b3b3db6cea63a39ee",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -101,7 +101,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "a5a854fd1aa35f15f48183ddf263d8a0cb2dc7f67e3c513a92b4acdc0c6d28f1",
+      "contentHash": "808fbff652a75bc43ece5a00aa1f6d2ab1753d085c7ca75b3b3db6cea63a39ee",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -110,7 +110,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "a5a854fd1aa35f15f48183ddf263d8a0cb2dc7f67e3c513a92b4acdc0c6d28f1",
+      "contentHash": "808fbff652a75bc43ece5a00aa1f6d2ab1753d085c7ca75b3b3db6cea63a39ee",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -119,7 +119,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "a5a854fd1aa35f15f48183ddf263d8a0cb2dc7f67e3c513a92b4acdc0c6d28f1",
+      "contentHash": "808fbff652a75bc43ece5a00aa1f6d2ab1753d085c7ca75b3b3db6cea63a39ee",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -128,7 +128,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "a5a854fd1aa35f15f48183ddf263d8a0cb2dc7f67e3c513a92b4acdc0c6d28f1",
+      "contentHash": "808fbff652a75bc43ece5a00aa1f6d2ab1753d085c7ca75b3b3db6cea63a39ee",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1464,7 +1464,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "a5a854fd1aa35f15f48183ddf263d8a0cb2dc7f67e3c513a92b4acdc0c6d28f1",
+      "contentHash": "808fbff652a75bc43ece5a00aa1f6d2ab1753d085c7ca75b3b3db6cea63a39ee",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {
@@ -1496,7 +1496,7 @@
       "type": "subsystem",
       "domain": "communication",
       "sourcePath": "src/lifeline/TelegramLifeline.ts",
-      "contentHash": "b0b8b55a3d7bbd1df0b66edf37010e33cff05df5fc35d3fd8047b0ef5f29b5fc",
+      "contentHash": "ad363d58349530646209a1ee6b97e0039449c70c6cf61c87d3c590c9e39d25e4",
       "since": "2025-01-01"
     },
     "subsystem:orphan-process-reaper": {

package/upgrades/1.1.2.md

@@ -0,0 +1,130 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+
+## What Changed
+
+**fix(boot-wrapper): plist↔wrapper extension drift no longer takes agents dark.**
+
+Three intertwined boot-time changes that together close a "agent goes
+silently dark and won't come back" failure mode observed in the field
+(Echo, 2026-05-20):
+
+1. **`installBootWrapper()` always writes `instar-boot.cjs`** (not `.js`),
+   regardless of the project's `package.json` `"type"` field. `.cjs`
+   forces CommonJS semantics in Node, so the wrapper's `require()` calls
+   work in both type=module and type=commonjs projects. Previously the
+   function picked an extension based on `package.json` AND deleted the
+   alt extension — so if a project gained `"type": "module"` after the
+   plist was generated (e.g., via a package upgrade), the next call to
+   `installBootWrapper` deleted the `.js` file the plist still pointed
+   at. launchd then exec'd a nonexistent file on every restart and none
+   of the downstream self-heal (`ServerSupervisor.preflightSelfHeal`,
+   `NativeModuleHealer`, `INSTAR_SUPERVISED` detection) ever ran because
+   the boot wrapper itself never loaded.
+
+2. **`TelegramLifeline.selfHealPlist` adds a wrapper-existence check.**
+   The existing three checks all passed when the plist referenced
+   `instar-boot.js` but the file was deleted (the plist content still
+   matched the legacy-detection patterns). A fourth check now extracts
+   the wrapper path from `ProgramArguments` and verifies the file
+   exists on disk; if not, the plist is regenerated immediately.
+   Defense-in-depth — the always-.cjs change above eliminates the
+   creation of this state going forward, but this check rescues any
+   already-existing drift before the next launchd restart hits the
+   bad path.
+
+3. **`WakeSocketServer.start()` recovers from EADDRINUSE.** The
+   pre-existing unlink-before-bind pass handled the common
+   "stale socket file from unclean exit" case but silently swallowed
+   unlink errors and offered no fallback if `listen()` itself fired
+   EADDRINUSE. On EADDRINUSE the server now probes the socket: if a
+   live peer answers, surface the error normally (don't clobber a real
+   second instance); if nothing answers, force-unlink and retry listen
+   once. Bounded retry — single attempt, no churn.
+
+4. **`PostUpdateMigrator.migrateBootWrapperToCjs`** — closes the gap
+   for in-the-wild agents whose launchd plists were generated before
+   this change with `instar-boot.js` in `ProgramArguments`. On darwin,
+   if the plist exists and references `instar-boot.js`, the migration
+   regenerates via `installAutoStart` so the plist now points at
+   `instar-boot.cjs`. Idempotent — re-runs that find a `.cjs`-referencing
+   plist are silent no-ops. The migration does NOT delete the legacy
+   `.js` file; rollback safety wins over file cleanup.
+
+Files touched (excluding tests / docs / upgrade notes):
+- `src/commands/setup.ts` — `installBootWrapper`, `ensureBootWrapper`
+- `src/commands/server.ts` — auto-start plist sanity check accepts `.cjs`
+- `src/lifeline/TelegramLifeline.ts` — selfHealPlist 4th check
+- `src/threadline/WakeSocketServer.ts` — EADDRINUSE recovery
+- `src/core/PostUpdateMigrator.ts` — `migrateBootWrapperToCjs`
+
+## Evidence
+
+**Repro of the original failure** (Echo, 2026-05-20, 10:25 PT):
+
+1. Echo's `package.json` has `"type": "module"` (instar's own package
+   has had this since v1.0.0).
+2. Earlier `installBootWrapper` calls picked `.cjs`, deleted `.js`, and
+   the plist was generated at that point referencing `.cjs`.
+3. A subsequent code path (`installBootWrapper` running while the boot
+   was actively crashing for a different reason — Node major-version
+   ABI break, since rolled back) wrote `.cjs` AGAIN and deleted any
+   `.js` that had been re-created by an even-older code path.
+4. The plist on disk still referenced `.cjs`, but ALSO any plist that
+   had been generated when echo's `package.json` was missing the
+   `type: module` declaration referenced `.js` — and the `.js` file
+   was gone.
+5. launchd's next restart exec'd the nonexistent path → process never
+   started → all downstream self-heal (`NativeModuleHealer.healBetterSqlite3`,
+   `ServerSupervisor.preflightSelfHeal`, bind-failure escalation)
+   silently never ran.
+6. Operator intervention (Dawn, manual plist edit) was required to
+   restore the agent.
+
+**Observed before:** `git log` shows multiple in-the-wild reports of
+launchd plists pointing at a deleted `instar-boot.js` after a project
+gained `"type": "module"`. The selfHealPlist check at
+`src/lifeline/TelegramLifeline.ts:2076` reads `content.includes('instar-boot.js')`,
+which returns `true` even after the file is deleted — so the existing
+checks all pass and no regen fires.
+
+**Observed after:**
+- New test `tests/unit/boot-wrapper-plist-coherence.test.ts` exercises
+  `installBootWrapper` with package.json `type: module`, type: commonjs,
+  and no package.json — all three write `instar-boot.cjs`. A test
+  explicitly plants a pre-existing `instar-boot.js` and verifies it is
+  NOT deleted by the new code path (rollback safety).
+- New test `tests/unit/PostUpdateMigrator-bootWrapperCjs.test.ts`
+  exercises the four migration branches (non-darwin skip, no plist
+  skip, already-.cjs idempotent skip, and the `.js → .cjs` detection +
+  regeneration path).
+- New test `tests/unit/wake-socket-server-stale-recovery.test.ts`
+  exercises the stale-socket cleanup path and asserts that a live peer
+  is NOT clobbered (the recovery surfaces EADDRINUSE in that case).
+- Existing test suites unchanged; `installBootWrapper` callers in
+  `installMacOSLaunchAgent` and `TelegramLifeline.selfHealPlist`
+  receive the new `.cjs` path through the unchanged `wrappers.js`
+  return field so no callsite needs adjustment.
+
+## What to Tell Your User
+
+- **Your agent stays online through package upgrades**: if I had an
+  internal package configuration change, my launchd entry point used
+  to risk getting renamed out from under itself. That whole class of
+  failure is closed off now — the boot file has a stable name that
+  works regardless of internal toggles.
+- **Stale socket files don't lock me out anymore**: if I exited
+  uncleanly and a leftover socket file blocked the next start, I now
+  detect that and clean it up safely, only after first checking that
+  nothing else is actually using it.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Plist↔wrapper coherence guarantee | automatic (no action required) |
+| selfHealPlist verifies wrapper-path-on-disk | automatic (runs in lifeline boot) |
+| WakeSocketServer EADDRINUSE recovery | automatic (runs in listener startup) |
+| PostUpdateMigrator regenerates `.js`-plists | automatic on next instar update |

package/upgrades/side-effects/boot-wrapper-plist-coherence.md

@@ -0,0 +1,176 @@
+# Side-Effects Review — Boot-Wrapper / Plist Coherence
+
+**Version / slug:** `boot-wrapper-plist-coherence`
+**Date:** `2026-05-20`
+**Author:** Echo (instar developer agent)
+**Trigger:** Field failure 2026-05-20, ~10:25 PT: instar agent "echo"
+went dark, required operator intervention (Dawn — manual plist edit) to
+recover. Root cause: launchd plist's `ProgramArguments` referenced
+`instar-boot.js` but that file had been deleted by `installBootWrapper`
+because `package.json` had gained `"type": "module"`.
+
+## Summary of the change
+
+Four interlocking edits that together eliminate the plist↔wrapper
+extension-drift failure class:
+
+1. **`installBootWrapper()` always writes `.cjs`.** No more reading
+   `package.json "type"` and switching extensions. No more deleting the
+   alt extension.
+2. **`ensureBootWrapper()` looks for `.cjs`.** The presence check used
+   to look for the type-dependent extension; now it always looks for
+   `.cjs`.
+3. **`TelegramLifeline.selfHealPlist` adds Check 4:** verify the wrapper
+   path referenced by the plist's `ProgramArguments` exists on disk. If
+   not, regenerate via `installAutoStart`. Defense-in-depth for any
+   already-drifted state.
+4. **`PostUpdateMigrator.migrateBootWrapperToCjs`** detects existing
+   `.js`-referencing plists and regenerates them to point at `.cjs` via
+   `installAutoStart`. Idempotent.
+5. **`WakeSocketServer.start()`** uses a probe-before-clobber pattern.
+   Previously: pre-bind unconditional `unlink`. New: listen first; on
+   EADDRINUSE, probe-connect to determine if the socket is live or
+   stale; only unlink+retry if confirmed stale. Prevents silently
+   stealing a path from a live peer.
+
+## Decision matrix
+
+### Over-block
+
+| Scenario | Outcome |
+|----------|---------|
+| Project has package.json `"type": "module"` | Always-`.cjs` is correct (no behavioral change vs. pre-existing `.cjs`-write path) |
+| Project has no package.json | Always-`.cjs` works (Node treats `.cjs` as CommonJS regardless of parent context) |
+| Project has package.json `"type": "commonjs"` | Always-`.cjs` works (CommonJS is the explicit context) |
+| Existing `.js` wrapper on disk | NOT touched (rollback-safe — old plists referencing `.js` keep working until migrator runs) |
+| Existing `.cjs` wrapper on disk | Overwritten with current content (preserves existing behavior) |
+
+No over-block. The `.cjs` extension is strictly broader than the previous `.js`+`.cjs` split.
+
+### Under-block
+
+| Scenario | Outcome |
+|----------|---------|
+| Plist references `.js`, no `.js` file on disk, no `.cjs` file on disk | Migrator regenerates; selfHealPlist Check 4 catches | 
+| Plist references `.cjs`, `.cjs` file deleted | selfHealPlist Check 4 catches (regenerates) |
+| Plist references `.js`, `.js` file present, `.cjs` file present | Migrator regenerates plist to `.cjs` (idempotent on re-run) |
+| Plist references `.js`, `.js` file present, `.cjs` file missing | Migrator regenerates plist (writes `.cjs` + updates plist) |
+
+No under-block.
+
+### Level of abstraction fit
+
+- The fix lives at the WRAPPER GENERATION + WRAPPER VERIFICATION layer,
+  which is the same layer where the bug originated. Not pushed up into
+  the Remediator (out of scope for this PR — Remediator is still under
+  Tier 2 rollout per the v3 spec) and not pushed down into launchd (no
+  way to influence launchd's interpretation of the plist).
+- `installBootWrapper`'s contract is unchanged from a caller's
+  perspective: it still returns `{ sh, js }`. The `js` field name is now
+  a slight misnomer (the file is `.cjs`) but every existing caller uses
+  it as an opaque path string, so no callsite changes.
+
+### Signal-vs-authority compliance
+
+| Component | Signal or Authority | Reason |
+|-----------|--------------------|--------|
+| `installBootWrapper` always-`.cjs` | Authority (writes files) | Deterministic, content-based decision. No judgment call. |
+| `ensureBootWrapper` `.cjs` lookup | Signal (returns boolean) | Caller decides what to do with "wrappers missing". |
+| `selfHealPlist` Check 4 | Authority (writes files via installAutoStart) | Existence check is deterministic. The regeneration is a documented recovery primitive. |
+| `migrateBootWrapperToCjs` | Authority (writes files via installAutoStart) | Detection is structural (plist content matches regex). Regeneration is the same primitive other migrations use. |
+| `WakeSocketServer` probe-then-recover | Signal-and-Authority hybrid | Probe is a signal (connect-or-not); the unlink+retry is bounded recovery (single retry, hard timeout). |
+
+Compliant. The new authorities are bounded recovery primitives, not
+judgmental gates. The new signals are deterministic structural checks.
+
+### Interactions with adjacent systems
+
+| System | Interaction | Risk |
+|--------|-------------|------|
+| `NativeModuleHealer` | None direct. NativeModuleHealer fires after boot wrapper loads; this fix ensures the boot wrapper CAN load. | Strictly improves NativeModuleHealer's blast radius. |
+| `ServerSupervisor.preflightSelfHeal` | None direct. Preflight runs after boot wrapper spawns the lifeline. | Same — strictly improves preflight's coverage. |
+| `detectLaunchdSupervised` | None. Runs inside the lifeline; the fix is upstream. | None. |
+| `INSTAR_SUPERVISED` plist env | Compatible — `installMacOSLaunchAgent` regenerates the full plist including this env var. | None. |
+| `RestartOrchestrator` | Same as above — fix is upstream. | None. |
+| `DegradationReporter` | None direct. Migrator failures land in `result.errors[]` which feed the migration report, not Degradation. Acceptable: migrator runs in a known supervised window, not in production hot paths. | None. |
+| `WakeSocketServer` listener daemon usage | The probe-before-clobber change only fires on EADDRINUSE. Normal startup path (no stale file) is unchanged. | Tested with planted-stale-file + live-peer scenarios. |
+| Existing `.js`-wrapper-using agents | Continue to work — `.js` file is NOT deleted; old plists still load; migrator regenerates plist on next update. | Backward compatible by design. |
+| Tests that simulate `instar-boot.js` (e2e/launchd-*) | These tests generate their OWN `.js` wrappers and do NOT go through `installBootWrapper`. Unchanged. | None — verified by reading the test files. |
+
+### Rollback cost
+
+- Pure code change. Revert is one git revert per affected file.
+- No persistent state changes that block rollback. The migrator runs
+  forward-only; rolling back leaves agents on `.cjs` plists (which work
+  fine) — the old `.js` files are still around if needed.
+- `WakeSocketServer` change: revert restores pre-bind-unlink behavior.
+  The live-peer-clobber behavior re-emerges but is rare in practice
+  (single-tenant agents on a machine).
+- Migrator runs idempotently — rolling back and re-deploying produces
+  the same end state.
+
+## Acceptance criteria
+
+1. **Repro of the Echo failure mode.**
+   - Test: `tests/unit/boot-wrapper-plist-coherence.test.ts > installBootWrapper — always writes .cjs > does NOT delete a pre-existing instar-boot.js (rollback safety)`
+   - Plants a pre-existing `instar-boot.js`, runs `installBootWrapper` with `package.json type=module`. Asserts the `.js` file still exists. Pre-change behavior: file deleted. Post-change: file preserved.
+
+2. **selfHealPlist catches drift.**
+   - Implicit in `TelegramLifeline.ts` source: `Check 4` extracts the wrapper path from `ProgramArguments` and verifies `fs.existsSync`. Covered by `Check 4` logic.
+
+3. **Migrator handles existing `.js`-referencing plists.**
+   - Test: `tests/unit/PostUpdateMigrator-bootWrapperCjs.test.ts > detects a plist that references instar-boot.js and attempts regeneration`
+   - Plants a plist referencing `instar-boot.js`. Runs the migrator. Asserts the migrator either succeeds (`upgraded`) or surfaces an error (`errors`) — both prove the detection-and-attempt path ran.
+
+4. **WakeSocketServer does NOT clobber live peers.**
+   - Test: `tests/unit/wake-socket-server-stale-recovery.test.ts > refuses to clobber a live peer (surfaces EADDRINUSE)`
+   - Binds a real `net.Server` to the socket path, then attempts to start a second `WakeSocketServer`. Asserts the second emits EADDRINUSE without taking the path away from the live peer.
+
+5. **WakeSocketServer recovers from stale socket.**
+   - Test: `tests/unit/wake-socket-server-stale-recovery.test.ts > cleans up a stale socket file on start (pre-bind unlink path)` and `> recovers from EADDRINUSE when no live peer is listening`
+   - Plants an empty file at the socket path, starts the server, asserts the listen succeeds.
+
+## Notes for second-pass reviewer
+
+- **Why always `.cjs` and not "always write both `.js` and `.cjs`?":**
+  Considered. Always-both would allow rollback to point at `.js` if
+  needed. Rejected because: (1) `.js` in a `type=module` project is a
+  broken artifact (Node can't load it as CJS); (2) the migrator
+  regenerates plists to `.cjs` automatically, so rollback isn't a
+  user-visible scenario; (3) keeping an unused broken file invites
+  confusion. The current code leaves `.js` files alone but doesn't
+  create new ones.
+
+- **Why not run the migrator on every lifeline boot instead of relying
+  on `PostUpdateMigrator`?** `selfHealPlist` already does the
+  equivalent on every lifeline boot — it's Check 4 of that function.
+  The migrator entry catches the case where the agent installs the new
+  instar version but hasn't yet booted the lifeline (e.g., the
+  postupdate migration runs first).
+
+- **Why probe-then-unlink instead of just `listen()`-then-error-bubble
+  on EADDRINUSE?** Without the recovery path, a stale socket file from
+  an unclean exit blocks startup forever until the operator manually
+  removes it. The probe-then-unlink preserves correctness (don't
+  clobber live peers) while restoring the auto-recovery the original
+  pre-bind-unlink path provided.
+
+- **Migrator side-effect on darwin only:** Linux systemd unit files
+  reference the bash wrapper (`instar-boot.sh`) which is unaffected
+  by this change. Non-darwin migrator path is a no-op skip.
+
+## Rollback playbook
+
+If this PR causes regressions:
+
+1. `git revert <pr-merge-sha>` on the canonical instar repo's `main`.
+2. Tag a patch release (e.g., `v1.1.2`) with the revert.
+3. `npx instar` auto-update propagates the revert to all in-the-wild
+   agents on next supervision cycle.
+4. Agents whose plists were already migrated to `.cjs` continue to
+   work — `installBootWrapper` post-revert writes `.cjs` for projects
+   with `type=module`, which matches what the migrated plists reference.
+5. Agents whose plists were NOT yet migrated (still on `.js`)
+   continue on `.js` — unchanged from pre-PR state.
+
+No persistent state cleanup required.