instar 1.0.13 → 1.1.1

package/upgrades/side-effects/feat-fix-parent-framework-intercept.md

@@ -0,0 +1,59 @@
+# Side-effects review — parent --framework intercept hotfix
+
+Per L6. Seven dimensions.
+
+## 1. Over-block / under-block
+
+Before (post-PR 3+4): UNDER — the flag silently fell back to claude-code
+on every subcommand invocation; the install/wizard arc didn't actually
+work for Codex. After: precisely correct. Subcommands receive the flag.
+
+## 2. Level-of-abstraction fit
+
+Fix sits exactly where the bug was — the program-level option definition
+in `cli.ts`. Removed cleanly; a comment-at-call-site explains the
+removal so a future editor doesn't reintroduce it.
+
+## 3. Signal vs Authority compliance
+
+No new authority. The bug was that Commander's program-level option
+parsing was treated as an authoritative consumer of subcommand args.
+Removing the program-level definition leaves subcommand parsers as the
+sole authority for their own flags — which is the correct mental model.
+
+## 4. Interactions with adjacent systems
+
+- **PR 3+4 (`instar setup --framework`)** — fix consistent with how
+  `setup` already worked. `instar setup --framework codex-cli` was always
+  going to be the correct invocation; the bug just made `instar` (no
+  subcommand) intercept the flag and also broke `instar init`.
+- **PR 1 (`instar init --framework`)** — now actually works on the CLI
+  path, not just when initProject is called directly. The PR 2 unit
+  tests still pass (they bypass the CLI layer); the smoke test is now
+  also green.
+
+## 5. Rollback cost
+
+Trivial. One option declaration removed plus a comment. `git revert`
+reintroduces the bug — but the comment-at-call-site would also revert,
+which is the safety net.
+
+## 6. Backwards compatibility / drift surface
+
+Fully backward-compatible. Users who already used `instar init
+--framework codex-cli` had a broken result before; now they get the
+correct codex-only install. Users who used the bareword `instar` with no
+flags see no change. Users who used `instar --framework codex-cli`
+(passing the flag before any subcommand) — that invocation never
+actually worked because there's no `--framework` on the bareword now,
+and even before this fix, bareword wouldn't have reached init/setup
+with the flag.
+
+## 7. Authorization / Trust posture
+
+No new authority. No privilege change. No new resources accessed.
+
+## Outcome
+
+Ship. One-line code fix verified by smoke test on this machine. Closes
+the install/wizard portability arc functionally.

package/upgrades/side-effects/feat-install-claude-gating.md

@@ -0,0 +1,67 @@
+# Side-effects review — Codex-only init zero .claude/ (PR 2 of 4)
+
+Per L6. Seven dimensions.
+
+## 1. Over-block / under-block
+
+Before: UNDER — `--framework codex-cli` was expressed but ignored; all
+`.claude/` writes fired anyway. After: precisely gated. Default (no flag,
+or `claude-code`, or `both`) is byte-identical to v1.0.15. Only an explicit
+codex-only choice changes anything.
+
+## 2. Level-of-abstraction fit
+
+`claudeEnabled` is derived once per init function (or per refresh helper)
+from the canonical `enabledFrameworks` value. The pure
+`resolveEnabledFrameworks(choice)` helper (PR 1) is the single resolver
+for flag-provided values; `refreshHooksAndSettings` and `refreshScripts`
+read the persisted config directly with the same default semantics. No
+brittle inline re-derivation.
+
+## 3. Signal vs Authority compliance
+
+The flag (PR 1) and the persisted `enabledFrameworks` are the SIGNAL of
+operator intent. Each init/refresh function's local `claudeEnabled`
+variable is the single AUTHORITY for that function's gating. No leak of
+the framework concept into the installer functions themselves
+(`installClaudeSettings`, `installSmartFetch`, etc.) — they remain
+unchanged.
+
+## 4. Interactions with adjacent systems
+
+- **PR 1 (`--framework` flag)** — built on top. PR 2 makes the flag's
+  persisted value actually do something at install/refresh time.
+- **`PostUpdateMigrator.getEnabledFrameworks()`** (v1.0.11) — uses the
+  same default semantics. The two readers are consistent.
+- **`IdentityRenderer.renderNonClaudeIdentityShadows`** — unchanged, still
+  runs unconditionally for AGENTS.md/GEMINI.md.
+- **`installHooks(stateDir)`** — unchanged; it writes to `.instar/hooks/`,
+  framework-neutral.
+- **`migrateScripts` in PostUpdateMigrator** — already framework-aware for
+  the relay script (Gap 4 / v1.0.10). The `.claude/scripts/` writes in
+  `refreshScripts` are now consistently gated.
+
+## 5. Rollback cost
+
+Low. Five gates in init.ts (all near-identical `if (claudeEnabled)` wraps)
++ one new test file. `git revert` restores prior behavior. Existing
+configs with or without `enabledFrameworks` continue to be readable by
+older versions.
+
+## 6. Backwards compatibility / drift surface
+
+Fully backward-compatible. Default behavior preserved. Drift surface:
+none new — five gate sites read from the same persisted field with the
+same default.
+
+## 7. Authorization / Trust posture
+
+No new authority. The gates only *prevent* writes for codex-only installs;
+they never grant new writes. Unreadable config defaults to `['claude-code']`
+(status quo). Cannot escalate, cannot read additional resources.
+
+## Outcome
+
+Ship. Operator-scoped, default-safe, fully tested (the codex-only zero-
+`.claude/` guarantee is pinned by an isolated-fs end-to-end test). PR 2 of
+4 of the install/wizard portability series.

package/upgrades/side-effects/feat-install-framework-flag.md

@@ -0,0 +1,65 @@
+# Side-effects review — install --framework flag (PR 1 of 4)
+
+Per L6. Seven dimensions.
+
+## 1. Over-block / under-block
+
+Before: UNDER — no UI for framework choice; even with all downstream
+machinery in place (PostUpdateMigrator, ParitySentinel, IdentityRenderer)
+the install always produced Claude-shaped scaffolding. After: no
+over-block. Default (no flag) is `['claude-code']` — byte-identical
+to today's behavior. Only an explicit `--framework codex-cli` or `both`
+changes the persisted config.
+
+## 2. Level-of-abstraction fit
+
+CLI option lives in `cli.ts`. The flag value resolution is a pure helper
+(`resolveEnabledFrameworks`) — testable in isolation, no side effects.
+Config-write integration is at the three init paths' existing config
+object literals. Correct altitude — option parsing at CLI boundary,
+business logic in pure function, persistence at the existing write sites.
+
+## 3. Signal vs Authority compliance
+
+The `--framework` flag is the SIGNAL of operator intent.
+`resolveEnabledFrameworks()` is the single AUTHORITY for the persisted
+shape. PostUpdateMigrator's `getEnabledFrameworks()` (added v1.0.11)
+is the single reader. No brittle inline duplication.
+
+## 4. Interactions with adjacent systems
+
+- **`PostUpdateMigrator.getEnabledFrameworks()`** (v1.0.11) already
+  reads this field with the same default. Now the field actually gets
+  written at install time. Consistent.
+- **`FrameworkParitySentinel`** has its own `enabledFrameworks` config
+  (different object); names intentionally mirror, no shared mutable
+  state, no coupling introduced.
+- **PRs 2-4** depend on this field being written; this PR makes them
+  possible without itself changing any gating.
+- **Existing Claude-only installs** are unaffected (default `['claude-code']`
+  preserves all current writes).
+
+## 5. Rollback cost
+
+Low. One CLI option add + one type field + one helper + three identical
+config-literal additions + one test file. `git revert` restores prior
+behavior; existing configs that have `enabledFrameworks` are still
+readable by older versions (the field is optional everywhere).
+
+## 6. Backwards compatibility / drift surface
+
+Fully backward-compatible: the flag is optional; the helper defaults
+to historical behavior. Configs created without the flag have no
+`enabledFrameworks` field; PostUpdateMigrator's helper already defaults
+to `['claude-code']` when the field is unset. Drift surface: none — one
+helper, one config field, three call sites using identical syntax.
+
+## 7. Authorization / Trust posture
+
+No new authority. The flag only changes what's persisted at install
+time. Cannot escalate privileges, cannot read additional resources.
+Invalid flag values exit with error at parse time.
+
+## Outcome
+
+Ship. Foundation for PRs 2-4. Default-safe, drift-reducing, tested.

package/upgrades/side-effects/feat-portability-shadow-capabilities.md

@@ -0,0 +1,63 @@
+# Side-effects review — Shadow capability mirror (Gap 6)
+
+Per L6. Seven dimensions.
+
+## 1. Over-block / under-block
+
+Before: UNDER — Codex/Gemini agents lacked capability instructions. After:
+no over-block. Mirror runs only when a non-Claude shadow exists; appends
+only sections absent from the shadow; never modifies CLAUDE.md.
+
+## 2. Level-of-abstraction fit
+
+Sits alongside `migrateClaudeMd` in PostUpdateMigrator, runs immediately
+after it. Same altitude. Slices from the live CLAUDE.md rather than
+extracting section bodies into a shared array — a deliberate scope choice
+per the operator's "minimal shim" decision.
+
+## 3. Signal vs Authority compliance
+
+CLAUDE.md (just patched by `migrateClaudeMd`) is the AUTHORITY for section
+content; the marker list is the SIGNAL of which sections exist. The shim
+never invents content — it copies bytes from CLAUDE.md.
+
+## 4. Interactions with adjacent systems
+
+- **migrateClaudeMd** — untouched; runs first, the shim reads what it
+  produced.
+- **IdentityRenderer** (Gap 1) — untouched; runs at a different layer
+  (identity vs capability). The shim appends only capability sections, so
+  the AGENT.md-derived identity content at the top of AGENTS.md/GEMINI.md
+  is preserved (tested).
+- **migrateFrameworkShadowCapabilities ordering** — runs before
+  migrateScripts and others; section appending is pure file I/O on the
+  shadows and does not block downstream steps.
+- **Claude-only installs** — no shadow exists, no-op. Verified.
+
+## 5. Rollback cost
+
+Low. One new private method + one new call site + one new test. `git
+revert` restores prior behavior; on-disk shadows keep the appended
+sections (inert; they'd just look like extra documentation). No state
+migration.
+
+## 6. Backwards compatibility / drift surface
+
+Claude installs: byte-identical. Non-Claude shadows: strictly better (now
+have capability instructions). Drift surface: **reduced** — section
+bodies live in exactly one place (CLAUDE.md, written by migrateClaudeMd)
+and are sliced from there into shadows; there is no separate source array
+to drift.
+
+## 7. Authorization / Trust posture
+
+No new authority. Reads CLAUDE.md and the existing shadows the migrator
+already owns. Writes only when appending material that came from
+CLAUDE.md. Failure paths surface as captured errors in the MigrationResult,
+never throw out of migrate().
+
+## Outcome
+
+Ship. Operator-scoped, source-of-truth preserved (no duplicated section
+bodies), idempotent, identity-preserving, Claude-only-safe, six-case
+tested. Closes the v1.0.0 cross-framework portability audit at 6/6.

package/upgrades/side-effects/feat-setup-framework-flag.md

@@ -0,0 +1,65 @@
+# Side-effects review — instar setup --framework + wizard launch (PR 3+4)
+
+Per L6. Seven dimensions.
+
+## 1. Over-block / under-block
+
+Before: UNDER — `setup.ts` exited if Claude wasn't installed, even for
+Codex operators. After: precisely targeted. Default (no flag) is
+'claude-code', byte-identical to v1.0.16. Only an explicit
+`--framework codex-cli` changes detection and spawn behavior.
+
+## 2. Level-of-abstraction fit
+
+`runSetup({ framework? })` accepts the choice; `checkFrameworkPrerequisite`
+from `src/core/Config.ts` is the single AUTHORITY for "is the chosen
+runtime's binary installed?" — reused, not duplicated. Spawn shape is
+two parallel branches (Claude and Codex) sharing the same wizard prompt
+content. Correct altitude.
+
+## 3. Signal vs Authority compliance
+
+The `--framework` flag is the operator-intent SIGNAL. `checkFrameworkPrerequisite`
+is the single AUTHORITY for binary detection across the whole codebase
+(also used by Config.load runtime startup). No new brittle inline checks.
+
+## 4. Interactions with adjacent systems
+
+- **PR 1 + PR 2** — built on top. The flag now drives both install-time
+  scaffolding (PR 1+2) and wizard-time launch (PR 3+4) consistently.
+- **`detectClaudePath` / `detectCodexPath`** — both already exported from
+  `src/core/Config.ts`. Used here without modification.
+- **`checkFrameworkPrerequisite`** — existing function, used as-is.
+- **Wizard skill content** (`.claude/skills/setup-wizard/SKILL.md`,
+  `secret-setup/SKILL.md`) — unchanged. Both runtimes are pointed at the
+  same files.
+- **Playwright Telegram-setup flow** inside the wizard — unchanged. The
+  flow was already runtime-portable; this PR makes the entry path work
+  for Codex too.
+
+## 5. Rollback cost
+
+Low. One function-signature change, one detection swap, two spawn-arg
+branches, two CLI flag additions. `git revert` restores prior Claude-only
+behavior. Existing Claude users are unaffected even mid-rollback.
+
+## 6. Backwards compatibility / drift surface
+
+Fully backward-compatible. The optional `framework` parameter defaults
+to `'claude-code'`. The bareword `npx instar` and `instar setup` without
+the flag run exactly as v1.0.16 did. Drift surface: none — wizard
+content remains in one place.
+
+## 7. Authorization / Trust posture
+
+No new authority. The flag only changes which binary is spawned; both
+existing spawn paths use `--dangerously-skip-permissions` (Claude) or
+`--dangerously-bypass-approvals-and-sandbox` (Codex) — these are the same
+sandbox-bypass postures the runtime-spawn builders already use elsewhere
+in the codebase (`src/core/frameworkSessionLaunch.ts`). No new privilege.
+
+## Outcome
+
+Ship. Operator-scoped, default-safe, no Claude-user regression risk,
+the cohesive end-to-end Codex setup story finally works. End-to-end
+verification follows as the next task (smoke test on this machine).

package/upgrades/side-effects/lockdown-layer-2.md

@@ -0,0 +1,123 @@
+# Side-effects review — Deployment Lockdown Layer 2 (release-tier gate)
+
+Per L6. Seven dimensions.
+
+## 1. Over-block / under-block
+
+**Before.** UNDER: the publish workflow had no concept of a holding pattern.
+Any merge to main with a non-template NEXT.md auto-published. There was no
+expressible "no deploy" state in code — the operator could only say it in
+chat, and chat does not feed the workflow. This is the exact gap that allowed
+the 2026-05-19 misalignment (four v1.0.x PRs shipped as v0.28.x patches
+during a session marked "no deploy").
+
+**After.** No new over-block of routine maintenance: when an operator flips
+`.instar/release-tier.json` to `tier: patch`, behavior is byte-for-byte
+identical to v1.0.8's post-Layer-1 path. The new path is `tier: hold`, which
+is precisely the previously-unexpressible "no deploy" state, plus `tier:
+minor` and `tier: major`, which enforce that the package.json bump actually
+matches the declared tier rather than letting any leap silently ship.
+
+The single deliberate over-block is `tier: major`, which refuses publishes
+until Layer 5 (multi-signature) ships. This is intentional — the spec
+requires both `LOCAL.major > NPM.major` AND signature verification before a
+major publish. Shipping a major with only single-agent authority would
+defeat the purpose of the lockdown.
+
+## 2. Level-of-abstraction fit
+
+The resolution policy lives in `scripts/resolve-release-tier.mjs` — pure
+functions (`validateTierConfig`, `readTierConfig`, `resolveReleaseTier`)
+with a thin CLI shim. The workflow calls it and routes on the printed
+decision. Decision logic in testable code, orchestration in the workflow.
+No logic buried in inline bash.
+
+The committed `.instar/release-tier.json` file is the operator's authority;
+the script is the deterministic reader; the workflow is the consumer. Three
+roles, three files, no conflation.
+
+## 3. Signal vs Authority compliance
+
+`.instar/release-tier.json` is the AUTHORITATIVE declaration of the active
+release line. The script never blocks of its own initiative — it reads the
+operator's committed authority and reports the corresponding decision. The
+workflow honors that decision. This is signal-vs-authority done right: a
+deterministic reader translating a committed operator signal into a
+deterministic outcome.
+
+No new authority is created by this layer. The publish authority (NPM_TOKEN)
+is unchanged and still gated by branch protection + CI required checks. The
+gate runs strictly before any side-effectful step, so a `skip` decision
+prevents `npm publish`, `npm version`, the NEXT.md rename, and the
+release-commit push from running at all.
+
+## 4. Interactions with adjacent systems
+
+- **Layer 1 (`resolve-publish-version.mjs`).** Untouched. Layer 2 runs
+  BEFORE Layer 1 in the workflow: if the tier blocks, the version-bump step
+  never runs. If the tier allows, Layer 1 proceeds with its existing
+  package.json-as-authority logic.
+- **NEXT.md skip-gate.** Untouched. The existing template-detection logic
+  still runs first; Layer 2's gate is only consulted when NEXT.md has
+  content. Tier=hold + template NEXT.md = both gates skip (overdetermined,
+  safe).
+- **`check-upgrade-guide.js`.** Untouched. Only runs when both Layer 2 and
+  Layer 1 have allowed publish.
+- **Pre-push hook / Husky.** Untouched. This is build-time infra in a
+  workflow YAML, not in a code path the pre-push hook examines.
+- **Agent runtime.** No agent runtime code is modified. The lockdown is
+  infrastructure-only.
+
+## 5. Rollback cost
+
+Low. Four files:
+
+- `scripts/resolve-release-tier.mjs` (new)
+- `tests/unit/resolve-release-tier.test.ts` (new)
+- `.instar/release-tier.json` (new)
+- `.github/workflows/publish.yml` (one added step, four downstream `if:`
+  conditions extended)
+
+`git revert <merge-sha>` restores the pre-Layer-2 behavior. No state
+migration. No deployed-agent impact. If the workflow YAML edit ever needs
+to be undone without a revert, removing the `tier-gate` step and the four
+extended `if:` clauses restores the prior path.
+
+Operator can also unblock publishes immediately by changing
+`.instar/release-tier.json` from `hold` to `patch` — a one-line commit, no
+code changes required.
+
+## 6. Backwards compatibility / drift surface
+
+The script defaults to `tier: patch` (pre-Layer-2 behavior) when
+`.instar/release-tier.json` is absent. This means an older checkout, a
+cherry-pick to a branch without the file, or any environment that loses
+the file mid-flight degrades gracefully to the existing behavior — never
+to a blocked state.
+
+Drift surface: small. The tier file is the only new persistent input. It's
+JSON with four allowed values; the validator rejects anything else with a
+clear error. The `setAt` / `setBy` / `reason` fields are informational only
+and the script does not use them for decisions, so format drift on those
+fields is non-blocking.
+
+## 7. Authorization / Trust posture
+
+No new authority is granted. The script reads a committed file and prints
+a string. It cannot publish, cannot mutate state, cannot escalate. The
+operator's authority is expressed via a normal git commit to
+`.instar/release-tier.json` — reviewable, traceable, revertable, and
+governed by the same branch protection that protects every other code
+change.
+
+The "hold" default in this release means the lockdown's headline guarantee
+is engaged immediately on merge — no further auto-publish can occur until
+an operator deliberately changes the tier. This is the spec's
+operator-intent-first posture: opt out of hold rather than opt in.
+
+## Outcome
+
+Ship. Minimal, incident-driven, fully unit-tested. The committed `hold`
+tier delivers the headline "no chance of accidental major-feature
+deployment" guarantee immediately on merge. Routine maintenance resumes
+with a one-line tier change. Layers 3–7 ship as separate PRs.

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.