instar 1.1.0 → 1.1.2

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.

package/upgrades/side-effects/native-heal-degradation-bridge.md

@@ -0,0 +1,206 @@
+# Side-Effects Review — Native-Module Heal → DegradationReporter bridge
+
+**Version / slug:** `native-heal-degradation-bridge`
+**Date:** `2026-05-20`
+**Author:** Echo (instar developer agent)
+**Second-pass reviewer:** voluntary independent audit run despite the
+change not falling under the mandatory-review categories — the bridge
+emits into the outbound-messaging path (via DegradationReporter), which
+is adjacent enough to warrant a second opinion.
+
+**Second-pass result:** *Concur with the review.* Reviewer independently
+verified:
+- `listeners` Set is effectively process-global (healer is a module-level
+  singleton); per-bridge `Set` dedupe is the right second layer for
+  future per-module retries.
+- F-8 Remediator `invokeFromRemediator` and legacy `openWithHeal` both
+  route through `logHealEvent` and share the `healAttempted` one-shot
+  guard, so no double-fire is possible today.
+- Listener-error swallow is bounded to the observability-consumer call
+  site and does not hide heal exceptions (those remain thrown by
+  `healBetterSqlite3Sync`).
+- Tests 7–9 exercise the real production listener-dispatch path via
+  `healBetterSqlite3Sync` with a mocked install-prefix resolver; tests
+  1–6 use a synthetic fanout helper appropriate for unit-isolating the
+  bridge translation logic.
+- Forward-looking note (not blocking): if per-module heal retries are
+  added later, success events should clear the dedupe entry and emit a
+  "recovered" degradation so a retry-success-after-failure sequence
+  doesn't leave the user with a stale failure alert. Today's one-shot
+  semantics make this impossible to hit, so the bridge is correct as
+  written; the comment in the bridge already anticipates the future
+  surface.
+
+## Summary of the change
+
+`NativeModuleHealer` already writes `HealEvent`s to
+`<stateDir>/native-module-heals.jsonl` and `console.error`s on failure. Its
+own jsdoc names `DegradationReporter` as a consumer ("consumed by health
+checks and DegradationReporter") but no consumer was ever wired. This PR
+fills the gap with the minimum surface area required:
+
+1. `NativeModuleHealer.onHealEvent(listener)` — public listener
+   registration on the existing singleton. Listener fires after every
+   persisted `HealEvent` (success and failure). Returns an unsubscribe
+   function. Listener errors are swallowed inside the dispatch loop so
+   observability cannot break the heal path itself.
+2. `src/monitoring/NativeHealDegradationBridge.ts` — new ~70-line module.
+   Subscribes to the healer; on a failure event, calls
+   `DegradationReporter.report(...)` with a component-specific impact
+   line. Successful heals are silent on purpose (the feature recovered,
+   no user action required). Dedupes per component within the process
+   life so a future heal-retry surface cannot spam the alert path.
+3. `AgentServer` — one new import + one new call (`bridgeNativeHealToDegradation()`)
+   placed immediately after the existing `NativeModuleHealer.configure(...)`
+   line, inside the same `if (options.config.stateDir)` block.
+
+Files touched:
+- `src/memory/NativeModuleHealer.ts` — adds `HealEventListener` export,
+  `listeners` Set, `onHealEvent()` method, listener-clear in
+  `resetForTesting()`, listener-dispatch in `logHealEvent()`.
+- `src/monitoring/NativeHealDegradationBridge.ts` — new module.
+- `src/server/AgentServer.ts` — one import + one call.
+- `tests/unit/NativeHealDegradationBridge.test.ts` — 9 new tests covering
+  failure→report, success-silent, per-component dedupe, unknown-component
+  fallback impact, missing-field reason fallback, unsubscribe, real
+  listener dispatch through `healBetterSqlite3Sync` with a mocked install
+  prefix, listener-error isolation, and listener cleanup.
+- `upgrades/NEXT.md` — entry, evidence paragraph, user message, two
+  capability-table rows.
+
+## Decision-point inventory
+
+- `NativeModuleHealer.logHealEvent` (deterministic authority over heal
+  persistence) — **extend** — adds a listener-dispatch step after the
+  existing jsonl write. Listener errors are swallowed; the heal contract
+  is unchanged.
+- `AgentServer` startup (composition root) — **extend** — adds a single
+  subscriber registration call. No new state.
+- `DegradationReporter.report` — **consume only**, no surface change.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+None. No new gating, no new filtering, no rejection logic. The bridge
+adds a degradation event on heal *failure* and stays silent on heal
+*success*. Successful heals continue to behave identically to today
+(the feature opens, the user sees nothing).
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- **CLI commands that hit the healer outside the server process.** A
+  user running `instar memory ...` against an ABI-mismatched
+  better-sqlite3 will get the existing `console.error` and a thrown error
+  but no Telegram alert — `AgentServer` is the only registration site.
+  This is the same scope as the existing DegradationReporter wiring
+  (CLI commands never had the Telegram alert path anyway). The CLI user
+  sees the error on stdout, which is the appropriate surface for a
+  foreground command.
+- **Multiple AgentServer instantiations in one process.** Each
+  `bridgeNativeHealToDegradation()` call adds a new listener with a
+  fresh dedupe Set. In production AgentServer is a singleton; in tests
+  callers pass an explicit reporter. Not a real risk; documented as a
+  YAGNI in the bridge module.
+- **Build manifest / pre-load drift detection.** Out of scope — covered
+  in topic 11013's earlier design proposal as a separate (lower
+  priority) item. The heal works without it.
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. The healer is the existing authority over native-module rebuilds
+and the canonical producer of `HealEvent`s. DegradationReporter is the
+existing authority over "feature-fallback → user-visible alert."
+Bridging them in a third file keeps each side single-responsibility:
+the healer doesn't import the reporter (no `src/memory/*` →
+`src/monitoring/*` coupling beyond the bridge), the reporter doesn't
+know about the healer at all, and the bridge is a pure subscriber that
+can be unit-tested with a synthesized `HealEvent`.
+
+`AgentServer` is the correct composition root for the registration —
+it's where `NativeModuleHealer.configure(...)` already happens, so the
+two lines stay co-located.
+
+## 4. Signal vs authority compliance
+
+**Reference:** the principle in MEMORY.md (`feedback_signal_vs_authority`):
+"Brittle/low-context filters detect and emit signals. Only a higher-level
+intelligent gate with full context has blocking authority."
+
+- The **healer** is the deterministic authority over native-module
+  rebuilds. Unchanged.
+- The **bridge** is a pure signal transducer — `HealEvent` (signal) →
+  `DegradationEvent` (signal). It has no blocking authority, no decision
+  surface, no LLM call.
+- `DegradationReporter` is the higher-level alert authority. Its
+  existing dispatch logic (Remediator routing, tone-gate, alert
+  cooldown) is unchanged. The bridge is just a new emitter feeding the
+  same authority.
+
+## 5. Interactions / cross-component effects
+
+- **Existing W-1 Remediator path.** When `NativeModuleHealer.invokeFromRemediator(ctx)`
+  is the entry point, it still calls `healBetterSqlite3Sync` →
+  `logHealEvent` → listener dispatch. The bridge fires once for the
+  same component just as it does for the legacy `openWithHeal` path —
+  per-component dedupe absorbs both paths. No double-alert risk.
+- **DegradationReporter remediator-routing.** Reports flow through
+  `_normalize()` like any other legacy `.report(...)` call. They will be
+  tagged `provenance: 'free-text'` and (per §A6) won't match any runbook
+  prefilter — they route to `no-matching-runbook` and feed
+  NovelFailureReviewer's clustering pipeline, which is appropriate for
+  "the W-1 heal couldn't repair its own target" alerts.
+- **Telegram tone-gate.** Goes through the existing pipeline; the
+  default safe fallback template applies if the candidate text is
+  rejected.
+- **Persistence.** `degradations.json` (existing) gains entries for
+  heal failures. Bounded to last 100 events per existing rotation.
+
+## 6. Rollback cost
+
+Trivial. Revert is 5 file edits (3 modifications + 2 deletions). No
+schema, no config, no migration, no on-disk format change. The
+`native-module-heals.jsonl` log and `console.error` path are unchanged,
+so observability survives a revert.
+
+## 7. Migration parity check
+
+Not applicable. The change is server-internal. No agent-installed file
+changes (no `.claude/settings.json`, no `.instar/config.json`, no
+CLAUDE.md template, no hook scripts, no built-in skills) — existing
+agents pick this up automatically when they restart against the new
+`instar` binary, which is the normal update path. The Migration Parity
+Standard's enumerated trigger list does not include `src/server/*`.
+
+## 8. Test integrity
+
+Per the Testing Integrity Standard (`docs/specs/TESTING-INTEGRITY-SPEC.md`):
+
+- **Tier 1 (unit).** 9 tests in
+  `tests/unit/NativeHealDegradationBridge.test.ts` — listener-dispatch,
+  failure-reports / success-silent / per-component-dedupe / unknown-component-fallback /
+  missing-field reason / unsubscribe; plus three on
+  `NativeModuleHealer.onHealEvent` exercising the real
+  `healBetterSqlite3Sync` early-exit path with a mocked install-prefix
+  resolver (listener invocation, listener-error isolation, unsubscribe).
+- **Tier 2 (integration).** Not added — the bridge is a process-internal
+  subscriber with no HTTP surface. The existing
+  `tests/integration/degradation-reporter-*` suites continue to cover
+  the reporter's HTTP-visible behavior; this PR adds one more emitter
+  to that same path, no new routes.
+- **Tier 3 (E2E lifecycle).** Not added — the wiring lives inside the
+  same `if (options.config.stateDir)` block that already conditions
+  `NativeModuleHealer.configure(...)` and `TokenLedger` construction
+  (which both have Tier-3 coverage). Adding a parallel boot-time
+  bridge-presence test would only restate that block's existing E2E
+  guarantee.
+
+Pre-existing related suites (`NativeModuleHealer.test.ts` 17 tests,
+`NativeModuleHealer-invokeFromRemediator.test.ts`, `degradation-reporter*`
+22 tests) pass unchanged after this PR.