instar 0.28.102 → 0.28.104

package/upgrades/side-effects/openclaw-import-pre-compaction-flush.md

@@ -0,0 +1,85 @@
+# Side-Effects Review — Pre-Compaction Memory Flush
+
+Spec: `docs/specs/OPENCLAW-IMPORT-PRE-COMPACTION-FLUSH-SPEC.md`
+ELI16: `docs/specs/OPENCLAW-IMPORT-PRE-COMPACTION-FLUSH-SPEC.eli16.md`
+Driving approval: Telegram topic 9003, Justin, 2026-05-13.
+
+## What's IN
+
+1. New `src/core/PreCompactionFlush.ts` — pure class with `handle(payload)` method, fact parser, file writer, audit logger.
+2. New `tests/unit/PreCompactionFlush.test.ts` — 16 assertions covering all 9 outcomes + parsing variants + slug coercion + audit shape.
+3. Wired into `src/commands/server.ts` directly after the `compactionSentinel.report` PreCompact listener. Conditional on `config.preCompactionFlush.enabled === true`.
+4. Default config off (`enabled: false`). Operators flip to opt in.
+5. Audit log at `<projectDir>/.instar/audit/pre-compaction-flush.jsonl` for every fire.
+6. Per-fact memory files written under `<projectDir>/.instar/memory/learning_precompact_*.md`.
+7. MEMORY.md index entries under a `## Pre-Compaction Saves` section (best effort; only if MEMORY.md exists).
+
+## What's DEFERRED
+
+- **Per-model knob.** Could pin flush to Haiku-class or local Ollama independent of session's main model. Current design uses the shared intelligence provider (subscription default). Tracked as v2 enhancement; no demonstrated need today.
+- **Cross-session dedup.** Repeated flushes may write similar facts. Memory consumers tolerate near-duplicates on read; explicit dedup is v2.
+- **Option B (in-session silent turn).** Considered; rejected for v1 because user-visible outcome is identical and server-side is simpler/lower-risk. Recorded as possible v2 refinement.
+- **Migration to existing agents' settings.json.** Not needed — the change is server-side, hooked via the existing PreCompact event that all agents already report. New agents and existing agents benefit equally on the next instar update.
+
+## Over-block analysis
+
+The new behavior:
+- Writes at most 5 files per compaction event (each capped at ~700 bytes after frontmatter).
+- Appends one block of ≤5 lines to `MEMORY.md` per fire.
+- Sends a single LLM call per fire, prompt body capped at ~31 KB (30 KB transcript + ~1 KB instruction).
+
+No file ever gets overwritten — slugs include the flush timestamp, so collisions across two flushes within the same second produce two distinct files. No risk of clobbering existing memory entries.
+
+If the LLM goes haywire (returns 100 facts), `maxFactsPerFlush` caps the writes at 5. If a fact slug coerces to empty after sanitization, that fact is dropped (asserted in test).
+
+## Under-block analysis
+
+When the LLM returns `NONE` or `[]`, the flush exits at `no-facts`. This is the correct under-block — the prompt explicitly invites this response when nothing durable surfaces. No false-positive memory pollution.
+
+When the LLM returns garbage, the flush exits at `parse-failure` with the truncated response captured in audit. The user's MEMORY.md is not polluted.
+
+## Level-of-abstraction fit
+
+- **`PreCompactionFlush` is a single class.** All flush logic — transcript reading, prompt construction, parsing, file writes, audit — lives in one file. Testable in isolation.
+- **Wired into server.ts at the existing PreCompact event listener block.** ~22 lines of new wiring code, conditional on config. The class is loaded via dynamic `await import` so the cold-path cost is zero when disabled.
+- **No new HTTP endpoints, no new hook scripts.** The change rides on existing infrastructure (HookEventReceiver, hook-event-reporter.js, shared intelligence). One new listener, one new class.
+
+This is the minimal vertical that delivers the user-visible win. Anything larger would be premature.
+
+## Signal-vs-authority compliance
+
+The flush itself is an **authority** path (it writes durable files). Signal-vs-authority is preserved by:
+- The LLM is asked to make a *signal-quality* judgment (which facts are durable).
+- The class enforces **hard caps** as the **authority** layer (max facts, max length, slug coercion, write-or-audit). No LLM output ever bypasses the caps.
+- A bad LLM call can't damage the user's memory — only audit junk surfaces.
+
+## Interactions
+
+- **`CompactionSentinel`** (post-compaction recovery): unchanged. Both run on the same PreCompact event but in independent listeners. The Sentinel handles re-injection AFTER compaction; this class handles flush BEFORE compaction. They don't race because the Sentinel's work is keyed on a 10-second post-compaction delay (line 4477).
+- **`HookEventReceiver`**: emits PreCompact unchanged. New listener does not modify the event payload or the emitter's behaviour.
+- **`shared intelligence`** (PR #198 chokepoint): used per the subscription-by-default contract. If `sharedIntelligence` is null (e.g., CLI unavailable + no API opt-in), flush audits `no-intelligence` and exits.
+- **MEMORY.md**: appended under a dedicated `## Pre-Compaction Saves` heading. If that heading does not exist, it is created at the file tail. Pre-existing memory entries are untouched.
+- **`.instar/memory/` directory**: new files only; existing files untouched.
+- **`.instar/audit/`**: new jsonl file; existing audit files untouched.
+
+## Rollback cost
+
+- `config.preCompactionFlush.enabled: false` reverts to legacy behaviour. The class stays in the codebase but the listener is never registered.
+- Files already written to `.instar/memory/learning_precompact_*.md` are harmless markdown — they can be reviewed and deleted at the operator's discretion.
+- Audit jsonl can be moved aside or deleted at any time.
+- No schema migrations, no state mutations beyond memory files.
+
+## CI surface
+
+Touched:
+- `src/core/PreCompactionFlush.ts` — new file, fully covered by 16 unit tests.
+- `src/commands/server.ts` — 22 lines of new wiring inside the existing compaction block. The path is gated on config, so existing server-startup tests (which don't enable the new flag) exercise the gate-off branch.
+
+No CI workflow changes. No husky changes. No native module changes.
+
+## Open questions
+
+None. The design is fully constrained by:
+- OpenClaw's documented pattern (audit doc §3).
+- Justin's approval of "Option A — server-side, agent-noninterruptive."
+- Existing PR #198 safety-guard contract for the intelligence provider.

package/upgrades/side-effects/prompt-gate-no-prompt-cache.md

@@ -0,0 +1,258 @@
+# Side-Effects Review — PromptGate NO_PROMPT cache (token-burn fix)
+
+**Version / slug:** `prompt-gate-no-prompt-cache`
+**Date:** `2026-05-15`
+**Author:** Echo (instar developer agent)
+**Second-pass reviewer:** required (touches a monitoring sentinel decision point)
+
+## Summary of the change
+
+`src/monitoring/PromptGate.ts` — adds a bounded per-session NO_PROMPT
+classification cache to `InputDetector.llmDetect()`. Once the LLM has
+classified a specific terminal-output snapshot for a session as "not a
+blocking prompt," the same snapshot will short-circuit the LLM call instead
+of re-asking on every monitor tick. Cache is keyed on a SHA-256 fingerprint
+of the 20-line context the LLM actually sees, capped at 32 entries per session
+(FIFO eviction), cleared in `onInputSent()` and `cleanup()`.
+
+Files touched:
+- `src/monitoring/PromptGate.ts` — adds `noPromptCache` field, cache lookup
+  before LLM call, cache write on NO_PROMPT, clear in `onInputSent`/`cleanup`,
+  helper `recordNoPrompt()`.
+- `tests/unit/PromptGate.test.ts` — 7 new regression tests covering
+  idle-session short-circuit, per-session isolation, distinct-context still
+  calls LLM, `onInputSent` clears cache, `cleanup` clears cache, cache cap
+  bounded, positive detections are not cached.
+
+Decision points the change interacts with: only one — `InputDetector.llmDetect`,
+which uses Haiku to classify terminal output as a blocking prompt or not.
+The change is a memoization layer in front of that authority. The authority
+itself is untouched.
+
+## Decision-point inventory
+
+- `InputDetector.llmDetect` (LLM-backed authority that classifies terminal
+  output as blocking prompt vs. not) — **modify** — adds a memoization step
+  before the LLM call. The authority's verdicts are unchanged; we just stop
+  re-asking it the same question with the same input.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+The change cannot over-block prompt detection in the conventional sense
+(rejecting a legitimate user input). But it could *over-suppress* LLM
+re-classification, leading to a missed real prompt. Concrete failure mode:
+
+- A session's terminal output is classified NO_PROMPT for snapshot X.
+- Later, the agent prints a real blocking prompt, producing snapshot Y.
+- Snapshot Y is a *different* fingerprint (X ≠ Y) → cache misses → LLM is
+  called normally → real prompt detected.
+
+So the cache only suppresses LLM calls when the *exact same 20-line context*
+recurs. A real prompt would necessarily produce different output. No false
+suppression of real prompts is introduced.
+
+The one edge case worth naming: if the LLM made a wrong classification (false
+NO_PROMPT verdict on an actual prompt) and that *exact* output recurs, the
+cache amplifies the LLM error by preventing re-classification. Mitigation:
+the cache is bounded (32 entries) and cleared on `onInputSent()`, so the
+amplification window is short. Tradeoff is acceptable: a wrong LLM verdict
+gets re-asked at most 32 outputs later anyway, and the alternative was
+burning 3B tokens/day to repeatedly get the same wrong answer.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- **Subtle output noise that defeats fingerprinting.** A session showing a
+  spinner, timer, or animated counter will produce slightly different
+  fingerprints each tick. Each variant gets one LLM call before being cached.
+  Existing pre-filters (`/Scampering|Thinking|Reading \d+ file/i`) already
+  catch the most common animated-output cases. Residual noise from
+  not-yet-cataloged spinners would still call the LLM once per variant.
+- **Cache size cap (32).** A truly flapping session with > 32 distinct
+  recurring outputs would evict and re-classify. This is a deliberate
+  bounded-memory tradeoff; the cost is small (~32 SHA-256 calls per
+  flapping session per cycle) compared to the alternative of unbounded
+  growth. The existing 5-second outer cooldown still gates burst rates.
+
+Neither of these is a regression — both were always true. The fix is purely
+additive: same behavior on cache misses, suppressed re-classification on
+cache hits.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. This is a pure memoization at the same layer as the existing
+`llmRelayTimestamps` rate limiter. Both are private to `InputDetector` and
+gate the same LLM call. The cache is a *signal-level* optimization: it
+records which contexts have already been ruled out, so the authority
+(LLM) is not re-consulted unnecessarily. The authority (Haiku via
+`IntelligenceProvider.evaluate`) keeps full responsibility for the actual
+classification — the cache only suppresses redundant calls.
+
+No higher-level gate exists that this should feed instead. No lower-level
+primitive exists that already does this. The change sits in the natural home.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+**Does this change hold blocking authority with brittle logic?**
+
+- [x] No — this change has no block/allow surface.
+- [ ] No — this change produces a signal consumed by an existing smart gate.
+- [ ] Yes — but the logic is a smart gate with full conversational context.
+- [ ] ⚠️ Yes, with brittle logic.
+
+The cache does not make any classification decisions. It memoizes verdicts
+already produced by the LLM authority (`IntelligenceProvider.evaluate`). On
+a cache hit, the *previous LLM verdict* is what determines behavior —
+specifically, "the LLM said NO_PROMPT for this exact context, so we honor
+that verdict without re-asking." That is identical to what the LLM would
+return if re-asked on identical input (Haiku at temperature 0 with the same
+prompt is deterministic to within margin). No brittle logic gains blocking
+authority; the authority remains the LLM, the cache just records its prior
+output to avoid redundant calls.
+
+---
+
+## 5. Interactions
+
+**Does this interact with existing checks, recovery paths, or infrastructure?**
+
+- **Shadowing**: the cache check sits *after* the existing pre-filters (regex
+  rejects for status bar / "Thinking" / etc.) and *after* the existing
+  5-minute `llmRelayTimestamps` rate limiter. It runs *before* the LLM call.
+  If the existing rate limiter triggers, the cache is never consulted —
+  correct behavior, no shadowing.
+- **Double-fire**: the cache write happens once per LLM call (`recordNoPrompt`
+  is only invoked from the NO_PROMPT response path inside `llmDetect`, and
+  `pendingLlmDetection` prevents overlapping calls per session). No
+  double-fire surface.
+- **Races**: cache reads and writes happen on the same async path
+  (`llmDetect`). The `pendingLlmDetection` set already prevents concurrent
+  `llmDetect` calls per session. `onInputSent()`, `cleanup()`, and the LLM
+  response handler all touch `noPromptCache` from the same event loop. No
+  cross-thread / cross-process state — Node single-threaded, no race.
+- **Feedback loops**: the cache feeds back into its own check (cache hit →
+  skip LLM → no new cache entry). This is the desired loop — it converges,
+  not diverges. Counter-direction (real prompt appears → different
+  fingerprint → cache miss → LLM called → emit) is also stable.
+- **Adjacent cleanups**: `cleanup(sessionName)` already drops
+  `lastOutput`, `stableCount`, `emittedPrompts`, `lastEmissionTime`,
+  `llmRelayTimestamps`, `pendingLlmDetection`. We add `noPromptCache.delete`
+  to the same list. `onInputSent` similarly clears the cache so post-input
+  output gets re-classified.
+
+---
+
+## 6. External surfaces
+
+**Does this change anything visible outside the immediate code path?**
+
+- **Other agents on the same machine** — yes, indirectly: every instar agent
+  embeds the same `InputDetector`, so every agent's LLM burn rate for prompt
+  detection drops once the new code is installed. Behavior visible only as
+  reduced Haiku usage on the API side; no functional change in detection
+  behavior.
+- **Other users of the install base** — same: all agents inherit the fix
+  on upgrade. Strictly cost-positive.
+- **External systems** — Anthropic API usage drops materially. No format
+  change to any externally-visible message or event.
+- **Persistent state** — none. Cache is purely in-memory, lost on process
+  restart. No DB schema change, no file written, no migration.
+- **Timing / runtime conditions we don't fully control** — the cache assumes
+  Haiku's NO_PROMPT verdict on a specific input is stable enough to memoize.
+  At `temperature: 0` this is true to within stochastic noise; even if Haiku
+  flickered between NO_PROMPT and a positive response on the same input, the
+  cache would just lock in whichever came first for at most 32 outputs and
+  then evict. Acceptable.
+
+---
+
+## 7. Rollback cost
+
+**If this turns out wrong in production, what's the back-out?**
+
+- **Hot-fix release**: revert two files (`src/monitoring/PromptGate.ts`,
+  `tests/unit/PromptGate.test.ts`), ship a patch release. Estimated 10
+  minutes once issue is detected.
+- **Data migration**: none. No persistent state introduced.
+- **Agent state repair**: none. Cache is per-process, in-memory; restarting
+  the agent server drops it instantly.
+- **User visibility**: zero. The only user-visible behavior change is
+  reduced Telegram-relay duplicate-prompt spam, and the existing detection
+  behavior is preserved for first-time-seen outputs.
+
+Lowest possible rollback cost: pure code change, no migrations, no state.
+
+---
+
+## Conclusion
+
+The change is a bounded in-memory memoization layer in front of an LLM-backed
+authority. It introduces no new decision logic, no new blocking surface, no
+persistent state, and no external API changes. Worst-case failure mode is
+under-detection of a single class of recurring prompts (same exact 20-line
+output as a prior NO_PROMPT verdict), which is mitigated by `onInputSent`
+clearing the cache. The fix targets a specific, measured token-burn pattern
+(108k LLM calls / 3B tokens per 24h on this machine, 2026-05-15) caused by
+the existing 5-minute rate limit being incorrectly gated on emit. With the
+cache, idle sessions burn one LLM call per distinct output instead of one
+per monitor tick. Clear to ship pending second-pass concurrence.
+
+---
+
+## Second-pass review
+
+**Reviewer:** general-purpose subagent (Echo's review subagent)
+**Independent read of the artifact: concur**
+
+The cache is a textbook memoization layer in front of an LLM authority. On hit it short-circuits with the same behavior the LLM would have produced (`return` from NO_PROMPT branch); on miss it falls through to the unchanged authority. No new blocking surface, no decision logic, no persistent state. Signal-vs-authority compliance is clean. Worst-case under-suppression is bounded by a recurring-identical-context window of at most 32 outputs, after which FIFO eviction forces re-classification. Token spend in the degenerate >32-distinct-cyclic-context case is no worse than baseline.
+
+Minor notes (do not block ship, but worth tracking):
+
+- **In-flight `llmDetect` vs `onInputSent` race.** `onInputSent()` clears `noPromptCache` synchronously, but if an `llmDetect` is mid-flight for the same session (`pendingLlmDetection` set), its awaited `recordNoPrompt(...)` will land *after* the clear and repopulate the cache with a verdict computed against pre-input output. The stale entry only fires on a future byte-identical context (unlikely post-input) and would be evicted within 32 outputs or on the next `onInputSent`. Consider: capture a generation counter in `llmDetect` at start and skip `recordNoPrompt` if it doesn't match the current generation. Not urgent — failure mode is "one redundant cache entry," not "missed prompt."
+
+- **`startsWith('NO')` permissiveness amplified by cache.** Line 416 treats any LLM response starting with `NO` (e.g. "NOT SURE", "NOW WAITING") as NO_PROMPT and now caches it. Pre-cache this was a per-call leniency; post-cache it locks in for up to 32 cycles. Consider tightening to exact-match `NO_PROMPT` or `^NO_PROMPT\b`. Tracked as a hardening followup, not a blocker.
+
+- **Cleanup vs in-flight `llmDetect` (same race as above for terminated sessions).** `cleanup()` clears `pendingLlmDetection` and `noPromptCache`, but a mid-flight `llmDetect` whose `.finally()` has not yet run will still call `recordNoPrompt(sessionName, ...)`, creating a cache entry for a dead session. Pure memory leak (one entry per dead session per race window) until process restart. Bounded and minor.
+
+- **Test coverage gaps.** No regression test exists for: (a) the in-flight-vs-cleanup race, (b) the `startsWith('NO')` permissiveness path (e.g. asserting that `"NOT SURE"` is cached and impacts subsequent calls), (c) lack of interaction between `onPromptRejected` and `noPromptCache` (currently fine because rejection only applies to positive emits, but worth a defensive test if those branches ever cross). Add when the followups land.
+
+None of these break the ship criteria. The change is correct under the assumptions it states, and the failure modes I found degrade to at most "one extra LLM call" or "one stranded cache entry," never to a missed prompt. Clear to commit.
+
+**Author response to reviewer notes (addressed before commit):**
+
+- **In-flight race + `startsWith('NO')` permissiveness** — addressed in the
+  same commit. Added `cacheGeneration: Map<sessionName, number>` bumped by
+  `onInputSent()` and `cleanup()`. `llmDetect` captures the generation at
+  call start; `recordNoPrompt()` now drops the write if the generation has
+  advanced (covers both the input-during-flight and cleanup-during-flight
+  cases). Also tightened cache write to require strict `trimmed === 'NO_PROMPT'`;
+  the permissive `startsWith('NO')` branch still returns from `llmDetect` but
+  no longer memoizes, so a transient "NOT SURE" reply doesn't lock in.
+- **Test coverage** — two new tests added: one for the in-flight clear race
+  (asserts no cache entry after `onInputSent` mid-flight), one for permissive
+  non-strict-NO responses (asserts they are not cached). Total NO_PROMPT-cache
+  regression tests now 9; full PromptGate suite 42/42 passing.
+
+---
+
+## Evidence pointers
+
+- Original measurement (108,782 calls / 3.03B tokens / 24h):
+  `/private/tmp/claude-501/-Users-justin--instar-agents-echo/fb63ccb9-b8ab-4b63-8f49-55d3d6427255/tasks/bwgzdb1bf.output`
+- Unit-test verification: `npx vitest run tests/unit/PromptGate.test.ts`
+  → 40/40 passed, 7 new NO_PROMPT-cache regression tests included.

package/upgrades/side-effects/tier2-degradation-reporter-live-wire.md

@@ -0,0 +1,146 @@
+# Side-Effects Review — Tier-2 DegradationReporter live-mode wire-up
+
+**Version / slug:** `tier2-degradation-reporter-live-wire`
+**Date:** `2026-05-13`
+**Author:** `echo`
+**Second-pass reviewer:** `not required (gated behind opt-in config flag default-false; legacy alert path + in-line healers remain the safety net)`
+
+## Summary of the change
+
+Adds `src/remediation/RemediatorBootstrap.ts` — a single async entry point `bootstrapRemediator({ stateDir, machineId, ... })` that constructs the full Tier-2 dispatch graph: F-1 `RemediationKeyVault` (4-backend probe), F-4 `MachineLock` + `IntentJournal` + `AuditWriter`, F-5 `TrustElevationSource` (with Telegram + CLI approval channels), and the F-8 `Remediator` orchestrator. Registers the runbooks that exist on main today (W-1 `nodeAbiMismatchRunbook`, W-3 `messagingDeliveryFailedRunbook`); logs and skips W-2 supervisor-preflight and W-4 db-corruption wrappers that haven't merged yet. Returns `{disabled: true, reason: 'no-secret-backend'}` if the vault probe finds no backend.
+
+Modifies `src/commands/server.ts` to call `bootstrapRemediator()` IFF `config.remediator?.enabled === true` (defaults FALSE). On success, wires the Remediator into the existing `DegradationReporter` singleton via `setRemediator()`. On failure or disabled, logs a clear line and continues with the legacy alert path.
+
+Files touched:
+- `src/remediation/RemediatorBootstrap.ts` (new, 290 LOC)
+- `src/commands/server.ts` (boot-path wire-in, ~50 LOC inserted after `connectDownstream`)
+- `src/monitoring/DegradationReporter.ts` (1-line type widening: `RemediatorLike.dispatch` returns `Promise<unknown>` instead of `Promise<void>` so the real Remediator's `Promise<DispatchOutcome>` typechecks)
+- `tests/unit/RemediatorBootstrap.test.ts` (new, 12 tests)
+- `tests/integration/remediator-live-mode.test.ts` (new, 4 tests)
+- `upgrades/NEXT.md` (release note entry)
+
+Decision points the change interacts with:
+- `DegradationReporter.setRemediator()` — the F-3 hook designed for exactly this wire-in.
+- `Remediator.dispatch()` — authority for orchestrating remediation attempts. Not modified.
+- `Remediator.registerRunbook()` — registry-load-time validator (§A6 / §A36). Not modified; surfaced via bootstrap.
+
+## Decision-point inventory
+
+- `config.remediator.enabled` — **add** — structural opt-in flag (boolean) controlling whether the bootstrap runs at all. Operator authority, not a runtime judgment.
+- `DegradationReporter.setRemediator()` registration — **modify** — the F-3 hook was previously unused; this PR is its first real consumer. The setter itself is unchanged.
+- `Remediator` lifecycle (construction + supervisor registration) — **pass-through** — bootstrap composes existing primitives without altering their decision surfaces.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+No block/allow surface — over-block not applicable. The bootstrap is dependency injection. The only branch decisions it makes are:
+
+1. "Does the vault probe find a backend?" — if no, return `{disabled, reason: 'no-secret-backend'}`. This is the spec's prescribed fail-soft per §A62 (operating-state matrix → "OS Keychain Unavailable → try fallback"). Default behavior unchanged for the agent.
+2. "Did the operator opt in via `remediator.enabled`?" — if no, skip bootstrap entirely. This is the staged-rollout default per §A57.
+
+Neither branch rejects a legitimate degradation event. The legacy alert path remains the catch-all when the Remediator isn't wired.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+No block/allow surface — under-block not applicable in the sense of the principle. However, two structural under-block scenarios are intentional carve-outs:
+
+- **Operator-enabled live mode but vault throws on construction (not `no-backend-available`)**: the bootstrap re-throws, the server boot path's outer try/catch catches it and logs a red error line; legacy alert path stays active. The agent does NOT crash. This is intentional — silently downgrading the operator's explicit opt-in to legacy mode would mask a real configuration error.
+- **Runbook registry validation fails (W-1 ever ships a misshapen prefilter)**: bootstrap rethrows. The server boot path catches and logs. Legacy path remains active. The operator sees the failure on every restart until the wrapper PR is fixed.
+
+The legacy alert path + in-line healers (`NativeModuleHealer.openWithHeal`, `ServerSupervisor.preflightSelfHeal`) catch every degradation flow regardless of Remediator state.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+The bootstrap is dependency injection — its level is "the seam between server boot and remediation tree." It does NOT belong inside the Remediator (whose job is dispatch decisions), inside `DegradationReporter` (whose job is event normalization + alert routing), or inside any single F-* module (each owns one primitive). It lives at `src/remediation/RemediatorBootstrap.ts` precisely because it composes across all those modules and the lifeline. The location matches how the spec describes the wire-in (§A33 + §A57).
+
+The optional-runbook stubs (W-2/W-3/W-4) live inline as `tryLoadOptionalRunbook()` for now — when each wrapper PR lands, the stub gains a real import; the surrounding loop is identical. This is a transition-period pattern; once Tier-2 runbooks are all merged, the stubs collapse to direct imports.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+**Does this change hold blocking authority with brittle logic?**
+
+- [x] No — this change has no block/allow surface.
+
+The bootstrap injects dependencies into existing authorities (Remediator dispatches; TrustElevationSource decides transitions; AuditWriter verifies tokens). It does not add a new decision point.
+
+The `remediator.enabled` flag is operator authority via configuration — explicit human intent, expressed in `config.json`, not a runtime detector judging events. It is structurally identical to "should this server enable feature X" toggles already in `ProjectConfig` (e.g., `externalOperations`, `responseReview`, `inputGuard`).
+
+---
+
+## 5. Interactions
+
+**Does this interact with existing checks, recovery paths, or infrastructure?**
+
+- **Shadowing:** The `RemediatorLike.dispatch` widening in `DegradationReporter.ts` (`Promise<void>` → `Promise<unknown>`) is the only modification to existing decision surface. Behavior is identical — the reporter never inspected the dispatch result; the audit log is the canonical record. Widening the type surface does not change runtime semantics. Confirmed via re-run of all 24 `degradation-reporter.test.ts` cases.
+- **Double-fire:** When `remediator.enabled: true` AND a structured event arrives, the Remediator dispatches AND the legacy `reportEvent()` (feedback + Telegram alert) is skipped per existing F-3 contract — see DegradationReporter.report() L317-326. So no double-alert. The in-line healers in surfaces (NativeModuleHealer.openWithHeal etc.) are separate code paths that operate independently of the reporter and are unaffected.
+- **Races:** The bootstrap runs during server start, AFTER `degradationReporter.connectDownstream()`. By the time the first `report()` could fire from any subsystem, the Remediator is either wired or the flag is off. The only race is during the `await bootstrapRemediator()` window — if a feature starts and reports a degradation in those ~hundreds of milliseconds, the event flows through the legacy path. This is acceptable: the legacy path is the safety net.
+- **Feedback loops:** None. The Remediator's audit log is write-only from the reporter's POV; nothing routes audit entries back into `DegradationReporter.report()`.
+- **Lifeline coexistence:** `ServerSupervisor` lives in the lifeline process (TelegramLifeline.ts), not the server. The bootstrap accepts `serverSupervisor` as optional and leaves it unwired in the server-side bootstrap. F-6's handshake remains intact: the supervisor's `registerRemediator` handshake fires only when a Remediator is constructed inside the same process. A future PR can hoist Remediator construction into the lifeline if cross-process supervision is needed.
+
+---
+
+## 6. External surfaces
+
+**Does this change anything visible outside the immediate code path?**
+
+- **Other agents on the same machine?** No.
+- **Other users of the install base?** No behavioral change unless `remediator.enabled: true` is explicitly set in `config.json`. Default OFF = identical behavior to today.
+- **External systems (Telegram, Slack, GitHub, Cloudflare, etc.)?** The Remediator's `requestPlannedRestart` would talk to a supervisor, but no `requestPlannedRestart` call is made by W-1 today (it only rebuilds better-sqlite3 in-process). No external API change.
+- **Persistent state (databases, ledgers, memory files)?** When opted in, the bootstrap writes:
+  - `<stateDir>/machine-locks/in-flight/*` (existing F-4 directory; no schema change)
+  - `<stateDir>/remediation/intent-journal-<machineId>.jsonl` (existing F-4 file)
+  - `<stateDir>/remediation/audit-projection-<machineId>.jsonl` (existing F-4 file)
+  - `<stateDir>/remediation-keys.age` or keychain entries (existing F-1 store)
+  - All paths are in the F-7 gitignore allow-list (`REMEDIATION_GITIGNORE_ENTRIES`), so multi-machine sync won't carry them.
+- **Timing or runtime conditions we don't fully control?** The vault probe may hit OS keychain APIs (timing varies by host). Bootstrap is async and runs once at server start; failures don't crash the server.
+
+---
+
+## 7. Rollback cost
+
+**If this turns out wrong in production, what's the back-out?**
+
+- **Hot-fix release:** Revert the three-file change (Bootstrap module, server.ts insert, DegradationReporter type widening). Ship as next patch.
+- **Data migration:** None. Even if Remediator-written state exists on disk (audit-projection JSONL, etc.), those files are inert — nothing else in the agent reads them, and they're in the F-7 gitignore allow-list. Operator can `rm -rf .instar/remediation/` post-revert if desired.
+- **Agent state repair:** None. The `remediator.enabled` config field, if set, becomes a no-op after revert (unused config fields are ignored).
+- **User visibility:** Zero during rollback window. Default OFF means almost no installed agent is exposed to the bootstrap path today. The handful of operators who opted in see the legacy alert path return (which is what the rest of the install base sees).
+
+Rollback cost: very low.
+
+---
+
+## Conclusion
+
+This is the canonical Tier-2 live-mode flip PR per §A57. The structural opt-in (`remediator.enabled` default-false) means no agent's behavior changes on day one. Operators who explicitly opt in get the full F-1..F-8 dispatch graph wired into the existing F-3 reporter pipeline. The legacy alert path and in-line healers remain the safety net regardless of Remediator state.
+
+No new decision authority is added; no brittle blockers are introduced; the change is dependency injection at the seam between server boot and the remediation tree. Rollback is a three-file revert with no migration cost.
+
+---
+
+## Second-pass review
+
+Not required. The change introduces zero new block/allow decision logic — every check it touches is in pre-existing modules (Remediator, TrustElevationSource, AuditWriter) whose authority surfaces have already shipped through their own side-effects reviews. The only structural change is operator-authority opt-in flag default-false; that is configuration, not runtime judgment.
+
+---
+
+## Evidence pointers
+
+- Unit tests: `tests/unit/RemediatorBootstrap.test.ts` (12/12 passing).
+- Integration test: `tests/integration/remediator-live-mode.test.ts` (4/4 passing).
+- Regression: re-ran 97 tests across `Remediator`, `Remediator-enforcement`, `degradation-reporter`, `RemediationKeyVault`, `TrustElevationSource`, `MachineLock`, `AuditWriter`, `IntentJournal` — all green.
+- TypeScript: `tsc --noEmit` clean across the worktree.

package/upgrades/side-effects/token-ledger-native-heal.md

@@ -0,0 +1,136 @@
+# Side-Effects Review — Token Ledger Native-Module Heal
+
+**Version / slug:** `token-ledger-native-heal`
+**Date:** `2026-05-15`
+**Author:** Echo (instar developer agent)
+**Second-pass reviewer:** required (touches monitoring infrastructure + healer surface)
+
+## Summary of the change
+
+Adds a sync surface (`openWithHealSync<T>`) to `NativeModuleHealer` and wires `TokenLedger`'s constructor to use it. Restores `/tokens/*` endpoints on every active agent on this machine. Without this fix, a Node version upgrade after instar install silently breaks the token ledger forever.
+
+Files touched:
+- `src/memory/NativeModuleHealer.ts` — adds `openWithHealSync<T>(component, opener)` and `healBetterSqlite3Sync()`. Existing async `healBetterSqlite3()` is now a thin wrapper over the sync impl. No behavior change for existing async callers.
+- `src/monitoring/TokenLedger.ts` — replaces `new Database(opts.dbPath)` with `NativeModuleHealer.openWithHealSync('TokenLedger', () => new Database(opts.dbPath))`. Adds the import.
+- `src/server/AgentServer.ts` — adds `NativeModuleHealer.configure({ stateDir })` before TokenLedger construction so heal events log to the agent's state directory. Adds the import.
+- `tests/unit/NativeModuleHealer.test.ts` — adds 5 regression tests covering `openWithHealSync` success / non-mismatch passthrough / heal-failure / heal-then-retry / no-retry-after-prior-failure.
+- `tests/unit/token-ledger.test.ts` — adds 1 regression test pinning that the TokenLedger constructor routes the DB open through the healer.
+
+Decision points the change interacts with: only one — `NativeModuleHealer`. The fix extends its public surface with a sync variant. The healer remains the authority over native-module rebuilds; this PR just exposes that authority to sync call sites.
+
+## Decision-point inventory
+
+- `NativeModuleHealer.openWithHeal` (LLM-backed authority? no — deterministic authority over native-module rebuild) — **extend** — adds a sync surface variant. Decision logic identical to existing async path.
+- `TokenLedger.constructor → new Database` (low-level resource acquisition) — **modify** — routes the failure path through the existing healer authority instead of bubbling unhandled.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+No new block/allow surface. The change adds a heal-on-throw safety net to a code path that previously had no safety net. The only behavioral change is: where today a NODE_MODULE_VERSION mismatch produces `tokenLedger = null` forever, after this change the healer attempts a rebuild and retries the open. If the rebuild succeeds, the ledger opens normally; if it fails, the original mismatch error is rethrown with heal-context (same final state as today).
+
+No legitimate input shapes are newly rejected.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- **Rebuild fails repeatedly across process restarts.** The healer's once-per-process guard means each restart gets one rebuild attempt; if the rebuild keeps failing (e.g., disabled C compiler, no node-gyp), every server restart retries and burns ~30s. This is the existing healer behavior, not a regression — and it surfaces visibly via the heal log + `lastResult`.
+- **Other native modules.** The healer only knows about better-sqlite3. If a different native module (sqlite-vec, faiss-node, etc.) had a NODE_MODULE_VERSION mismatch, this PR wouldn't help. Out of scope.
+- **Concurrent heal storms.** PROP-399's W-1 extension (`invokeFromRemediator`) deals with multi-process storm coalescing; this PR uses the legacy in-line path which has no storm protection. Acceptable because TokenLedger init runs once per process inside the server constructor, before any other heal-capable component has a chance to race.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. The `NativeModuleHealer` is the existing canonical home for "rebuild a native module when it ABI-mismatches." Three other modules in tree already use its `openWithHeal()` async surface. Adding a sync mirror is the natural extension. The fix doesn't introduce a new layer; it consumes an existing one.
+
+`TokenLedger`'s constructor is where the better-sqlite3 open happens; that's where the heal call belongs. Moving it to AgentServer.start() would have made the constructor async (intrusive) without benefit — heal events still need a stateDir, which AgentServer.start() doesn't have any earlier than the constructor.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+**Does this change hold blocking authority with brittle logic?**
+
+- [x] No — this change has no block/allow surface.
+- [ ] No — this change produces a signal consumed by an existing smart gate.
+- [ ] Yes — but the logic is a smart gate with full conversational context.
+- [ ] ⚠️ Yes, with brittle logic.
+
+The new sync surface is a mechanical extension of an existing authority. It does not make any classification or judgment decisions. The healer's existing rebuild logic is the authority — sync vs async is only the consumer-side calling convention. No brittle logic, no new blocking surface.
+
+---
+
+## 5. Interactions
+
+**Does this interact with existing checks, recovery paths, or infrastructure?**
+
+- **Shadowing**: existing healer call sites (SemanticMemory/TopicMemory/MemoryIndex) still use async `openWithHeal`. The sync variant is opt-in per call site. No shadowing.
+- **Double-fire**: `healAttempted` (singleton state) is shared across sync + async paths — by design, so a once-per-process rebuild stays once-per-process even if both surfaces are used in the same process. The first caller wins; subsequent callers see "heal already attempted" and rethrow with hint. Correct behavior.
+- **Races**: the healer is a process singleton; all paths through it serialize on a single boolean. Node single-threaded, no race.
+- **Adjacent cleanups**: `resetForTesting()` clears `healAttempted` — verified to also reset for the new sync path (no separate sync state).
+- **AgentServer ordering**: `NativeModuleHealer.configure({ stateDir })` runs before `new TokenLedger(...)` in AgentServer.constructor. The configure call only sets a private field; it cannot fail.
+
+---
+
+## 6. External surfaces
+
+**Does this change anything visible outside the immediate code path?**
+
+- **Other agents on the same machine** — yes, in a positive way: every agent's TokenLedger init now heals through the rebuild path automatically. Visible to the operator as: `/tokens/summary` starts returning live data instead of `{"error":"token ledger unavailable"}` after the next agent upgrade.
+- **Other users of the install base** — same. Every instar agent benefits from the heal once it upgrades to this version.
+- **External systems** — npm gets one extra invocation (`npm rebuild better-sqlite3`) on each agent where the binding was previously mismatched. One-shot, ~30 seconds per agent, fully bounded by spawnSync timeout.
+- **Persistent state** — `<stateDir>/native-module-heals.jsonl` may gain entries (existing log path from PROP-399). No new state files. No schema migration.
+- **Timing / runtime conditions we don't fully control** — the rebuild requires npm + a working C compiler. On agents missing those (rare), the heal logs failure and the ledger remains null. Same final state as today.
+
+---
+
+## 7. Rollback cost
+
+**If this turns out wrong in production, what's the back-out?**
+
+- **Hot-fix release**: revert four files + their tests, ship a patch release. ~10 minutes once detected.
+- **Data migration**: none. No persistent state introduced.
+- **Agent state repair**: none. Any `native-module-heals.jsonl` entries from this PR are append-only observability, not load-bearing.
+- **User visibility**: zero. Worst-case rollback returns the ledger to its current "unavailable" state, which is the baseline today.
+
+Pure code change, no migrations, no state to roll back.
+
+---
+
+## Conclusion
+
+The change is the smallest possible adapter between an existing healer authority and the TokenLedger constructor that has been bypassing it. No new decision logic, no new blocking surface, no persistent state, no API contract change for existing callers. Worst-case rollback is a four-file revert at zero migration cost. The fix unblocks the observability that was meant to detect bleeding patterns automatically — without it, the next "bleeding out" scenario will again be invisible in the agent's own data. Clear to ship pending second-pass concurrence.
+
+---
+
+## Second-pass review
+
+**Reviewer:** general-purpose subagent (Echo's review subagent)
+**Independent read of the artifact: concur**
+
+The change is the minimal correct extension of the existing healer authority into the sync constructor of TokenLedger; the `healAttempted` singleton is shared across both surfaces by design (single-threaded Node + sync spawnSync means no interleave is possible), all 33 unit tests pass locally, AgentServer's outer try/catch preserves the exact same final state when the post-heal retry throws a different error (e.g., permission denied), and the only production call site of `new TokenLedger(...)` is AgentServer itself.
+
+Minor non-blocking notes:
+- `NativeModuleHealer.configure({ stateDir })` is last-write-wins; today only AgentServer calls it, so a future second caller with a different stateDir would silently redirect heal logs. Not a current bug — flag if another configure caller is ever added.
+- Test-mode constructions of `TokenLedger` (7 call sites in `tests/unit/token-ledger.test.ts`) skip the configure step and would log heal events to the os-tmp fallback if a real rebuild ever fired in tests. In practice the heal is fully mocked, so this never executes — but worth noting if integration tests start exercising the rebuild path for real.
+- Existing async tests spy on `healBetterSqlite3`; the sync path goes directly to `healBetterSqlite3Sync` and intentionally bypasses the wrapper. The two surfaces share state but not method identity — that's the right separation and the new test correctly mocks `healBetterSqlite3Sync` directly.
+
+---
+
+## Evidence pointers
+
+- Original failure log (server.log, accumulated over 28 restarts since 2026-05-13):
+  `[instar] token-ledger init failed (non-fatal): Error: The module ... was compiled against a different Node.js version using NODE_MODULE_VERSION ...`
+- `/tokens/summary` baseline on Echo before fix: `{"error":"token ledger unavailable"}`
+- Test verification: `npx vitest run tests/unit/NativeModuleHealer tests/unit/token-ledger.test.ts` → 49/49 passed (6 new regression tests included).
+- Acceptance: post-publish + post-upgrade, `/tokens/summary` returns a live JSON payload on Echo + at least one other agent.