instar 0.28.102 → 0.28.103

package/upgrades/side-effects/f5-trust-elevation-source.md

@@ -0,0 +1,258 @@
+# Side-Effects Review — F-5: TrustElevationSource + AutonomyProfileLevel wiring
+
+**Version / slug:** `f5-trust-elevation-source`
+**Date:** `2026-05-13`
+**Author:** `echo`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+Tier-2 foundation module from the Self-Healing Remediator v2 spec (per
+`docs/specs/SELF-HEALING-REMEDIATOR-V2-SPEC.md` "Trust elevation policy"
+section + amendments A11, A22, A25, A41, A53, A57, A59). Three new modules
+under `src/remediation/`:
+
+- `src/remediation/TrustElevationSource.ts` — authoritative gate for
+  runbook lifecycle transitions. Implements the asymmetric trust-elevation
+  table from the spec: pessimistic-quarantine always-allowed, collaborative
+  trust minimum for upward transitions, 48h fresh-trace + 1-week history
+  for registered→live, two-distinct-kind-channel rule for essential
+  un-quarantine (A53), and source-only transitions for
+  proposal→registered, live→deprecated, deprecated→removed.
+- `src/remediation/channels/TelegramApprovalChannel.ts` — F-5 stub
+  implementation of `TrustedApprovalChannel`. Exposes the shape the real
+  Telegram-countersignature verification (A41) will plug into, with a
+  deterministic seeded-map for test fixtures.
+- `src/remediation/channels/CliApprovalChannel.ts` — F-5 stub
+  implementation of `TrustedApprovalChannel` for the
+  `instar doctor confirm-unquarantine` signed-CLI second-factor path
+  (A53 option 1). Same seeded-map shape.
+
+This PR ships the policy module ONLY. No surface (dispatcher F-8,
+un-quarantine endpoint A25, dashboard toggle) wires into the source in
+this PR. F-5 is consumed by F-8's runbook-lifecycle wiring and by the
+Tier-2 `POST /remediation/unquarantine/:runbookId` endpoint in
+subsequent PRs.
+
+The change is foundational infrastructure: it adds capability surface, it
+does not remove or replace any existing decision point.
+
+## Decision-point inventory
+
+- `TrustElevationSource.canTransition()` — **add** — gates whether a
+  runbook lifecycle transition is permitted given (a) the current
+  autonomy profile, (b) supplied dry-run context, (c) approvals collected
+  via configured channels. Returns `{allowed, reason}`; never mutates
+  registry state.
+- `TrustElevationSource.requireSecondChannel()` — **add** — gates whether
+  the configured channels are sufficient for an essential-runbook
+  un-quarantine (A53's "real second factor" rule, distinct-kind).
+- `TelegramApprovalChannel.verifyApproval()` — **add** — stub: returns
+  approval for seeded entries only. Real Telegram countersignature
+  verification (A41) is a Tier-2 follow-up.
+- `CliApprovalChannel.verifyApproval()` — **add** — stub: returns
+  confirmation for seeded entries only. Real `instar doctor
+  confirm-unquarantine` signed-CLI integration is a Tier-2 follow-up.
+
+All decision points operate on caller-supplied policy inputs
+(autonomy profile, dry-run trace age + history span, essential bit,
+channel approvals). They do not contain content classification,
+heuristics, or "guess intent from text" logic.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+- `canTransition('proposal-to-registered', ...)` ALWAYS refuses. By
+  design — the spec deliberately offers no programmatic path. A human
+  must run a `/instar-dev` commit + spec-converge approval. The source
+  cannot become a backdoor.
+- `canTransition('live-to-deprecated' | 'deprecated-to-removed', ...)`
+  ALWAYS refuses. Same reason: source change only.
+- `registered-to-live` refuses without `dryRunTraceAge` /
+  `dryRunHistoryDays`. The dispatcher is expected to supply both from
+  the audit projection (F-4); a caller that omits them is a programmer
+  error. Refusing with an explicit `missing-...` reason is preferable to
+  silently approving.
+- Below-`collaborative` profile refuses ALL upward transitions even
+  when channels approve. Spec-mandated. The profile is the user-set
+  policy on how much authority the agent gets; it sits ABOVE channel
+  approvals. A user explicitly setting `cautious` SHOULD see the
+  agent refuse to un-quarantine even if approval comes through.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- **Stub channels are not real.** F-5 ships the abstraction with
+  deterministic seeded-map verification. The real verification (A41
+  Telegram-countersignature with proposalId-binding + user_id principal +
+  message-id watermark; A53 CLI signing key) lives in the channel
+  implementations that ship later. A misconfigured agent that wires a
+  stub into production would silently approve nothing; the dispatcher
+  surfaces this as `no-matching-...-countersignature` audit-logged refusal.
+- **Channel-kind collision.** The A53 "different-kind" rule keys on the
+  channel's `kind` string. Two implementations using the same `kind`
+  (e.g., two different Telegram bots) would falsely satisfy the
+  two-channel rule if the source counted instances. The implementation
+  counts distinct `kind` strings, so this is closed at the source. But
+  a channel-implementer that picks a clashing `kind` would create a
+  silent collapse — channel-implementer review is the mitigation.
+- **Replay across transitions.** F-5 forwards the channel's `messageId`
+  unchanged. The channel implementation MUST enforce the A41 watermark
+  `(proposalId, messageId)` tuple; F-5 does not duplicate that check.
+  This is the right layer — the source decides "did enough channels
+  approve" given verified results; the channel decides "is this
+  approval real and non-replayed."
+- **Race between concurrent un-quarantine attempts.** F-5 evaluates
+  channel approvals in `Promise.all`. Two concurrent dispatcher calls
+  for the same runbook would each issue a separate `verifyApproval`. The
+  channel implementation's watermark catches replay; the dispatcher's
+  per-runbook lock (F-4 `MachineLock`) prevents two un-quarantines from
+  taking effect. F-5 trusts those upstream gates.
+- **Trust-profile race.** If `AutonomyProfileManager.setProfile()` flips
+  during a `canTransition` call, the source captured `profile` in the
+  constructor. The dispatcher is expected to construct a fresh
+  `TrustElevationSource` per dispatch (or re-read profile from the
+  manager). F-5 does not subscribe to profile changes.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. F-5 is a **policy** module:
+
+- It decides "is this transition permitted right now given my
+  inputs"; it does not mutate state, dispatch runbooks, write
+  registry, or talk to the network.
+- The dispatcher (F-8) and the un-quarantine endpoint (A25) are the
+  enforcement points: they call `canTransition`, get a verdict, and
+  either proceed or audit-log + refuse.
+- The channels are **mechanism**: they verify cryptographic /
+  protocol-specific approval proofs and return a boolean.
+
+Three-layer split (mechanism → policy → enforcement) is the spec-
+mandated layering. F-5 sits in the middle layer alone — channels and
+enforcement live elsewhere.
+
+The `AutonomyProfileLevel` type is re-exported from
+`src/core/types.ts` (canonical owner). F-5 does not duplicate or
+redefine the type; it imports the same enum the rest of the codebase
+uses via `AutonomyProfileManager`.
+
+---
+
+## 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] Yes — but the logic is a smart gate operating on cryptographic /
+  policy primitives.
+- [ ] ⚠️ Yes, with brittle logic — STOP.
+
+The "blocks" in this change are:
+
+1. Profile-level comparison against a numeric ordering (`cautious=0,
+   supervised=1, collaborative=2, autonomous=3`). Deterministic.
+2. Trace-age numeric comparison against `FRESH_TRACE_MAX_AGE_MS`.
+   Deterministic.
+3. History-span numeric comparison against `MIN_DRY_RUN_HISTORY_DAYS`.
+   Deterministic.
+4. Channel-approval boolean count + distinct-kind set size.
+   Deterministic, sourced from channel verifications.
+5. Transition enum exhaustive switch. Deterministic.
+
+None of these are "string match on free-text"-class brittle filters.
+The signal-vs-authority anti-pattern is heuristic detectors holding
+blocking power; F-5's gates are policy primitives operating on
+authoritative inputs. The smart gate (the dispatcher / un-quarantine
+endpoint) is the consumer that decides *whether to attempt* a
+transition; F-5 only encodes the trust-elevation table.
+
+The CHANNEL implementations are where signal-vs-authority matters most.
+F-5's stubs are deterministic seeded-map lookups; the real Telegram /
+CLI channels MUST enforce cryptographic verification (HMAC, signature,
+watermark) — not string match on user reply text. The
+`TrustedApprovalChannel` interface returns a `principalUserId` so the
+A41 user_id-principal binding is preserved end-to-end.
+
+---
+
+## 5. Interactions
+
+**Does this interact with existing checks, recovery paths, or
+infrastructure?**
+
+- **Shadowing:** `src/core/TrustElevationTracker.ts` exists already.
+  Despite the similar name, that module tracks dashboard-driven trust
+  elevation events at the autonomy-profile layer. F-5 is the
+  remediator-specific runbook-lifecycle policy module. They share the
+  `AutonomyProfileLevel` type but no decision-point overlap; the
+  tracker is the SOURCE of the profile that F-5 READS.
+- **Race with adjacent cleanup:** None. F-5 has no on-disk state, no
+  background timers, no event listeners. Its only mutable state is the
+  channel list captured at construction.
+- **Double-fire:** `canTransition` is pure with respect to F-5 state
+  (no caching, no memo). Channels are responsible for their own
+  idempotency / replay defence. The dispatcher's `MachineLock`
+  serialises actual state mutations.
+- **Interaction with AutonomyProfileManager.** F-5 captures the
+  profile at construction. The dispatcher SHOULD construct a fresh
+  `TrustElevationSource` per dispatch (or re-derive). This is
+  documented in the module header.
+
+---
+
+## 6. External surfaces
+
+**Does this change anything visible to other agents, other users,
+other systems?**
+
+- No on-disk state. F-5 is in-memory only.
+- No HTTP routes. The A25 `POST /remediation/unquarantine/:runbookId`
+  endpoint that consumes F-5 ships in a follow-up PR.
+- No Telegram surfaces. The Telegram channel implementation is a stub;
+  the real Telegram-countersignature wiring ships in a follow-up.
+- No dashboard tabs.
+- New public types: `RunbookTransition`, `TrustedApprovalChannel`,
+  `TrustedApprovalVerifyInput`, `TrustedApprovalVerifyResult`,
+  `CanTransitionContext`, `CanTransitionResult`,
+  `TrustElevationSourceOpts`. All under `src/remediation/`.
+- New configuration surface: `remediation.approvalChannel.primary`
+  (per A59) is NOT yet read by F-5; the channel array is supplied
+  explicitly by the constructing caller. Config wiring lives at the
+  point of dispatcher construction, in a follow-up PR.
+
+---
+
+## 7. Rollback cost
+
+**If this turns out wrong in production, what's the back-out?**
+
+Trivially low. No consumers of these modules ship in this PR — the
+exported symbols are new and not yet imported anywhere in `src/`. A
+`git revert` removes them with zero state-migration cost. No on-disk
+files are created.
+
+If a future consumer-PR exposes a bug in the policy logic, the back-out
+path is "revert the consumer PR" — F-5 in isolation has no runtime
+effect.
+
+---
+
+## Reviewer concurrence (Phase 5)
+
+Not required. This change touches no block/allow surface for messaging,
+no session lifecycle, no coherence/sentinel/gate authority. It is
+foundational policy infrastructure with no live consumers in this PR.
+The dispatcher (F-8 Tier-2) and the un-quarantine endpoint (A25
+follow-up) are the enforcement points; their PRs will require their own
+side-effects reviews when wiring lands.

package/upgrades/side-effects/f6-supervisor-handshake.md

@@ -0,0 +1,234 @@
+# Side-Effects Review — F-6 ServerSupervisor handshake
+
+**Version / slug:** `f6-supervisor-handshake`
+**Date:** 2026-05-13
+**Author:** echo (instar-developing agent)
+**Second-pass reviewer:** not required
+
+## Summary of the change
+
+Extends `src/lifeline/ServerSupervisor.ts` with the Remediator ↔ Supervisor
+handshake described in `docs/specs/SELF-HEALING-REMEDIATOR-V2-SPEC.md`
+(§A15 partial-upgrade rule, carried forward from v1 §Supervisor
+coordination) and `docs/specs/SELF-HEALING-REMEDIATOR-V3-CONSOLIDATED-SPEC.md`
+(§3 state-file taxonomy: `supervisor-handshake.json`, HMAC-extended
+`restart-requested.json`; §9 Tier-2 sequencing). Adds:
+
+- `ServerSupervisor.HANDSHAKE_PROTOCOL_VERSION = 1` (static).
+- `RestartRequestedPayload`, `RestartRequestedReply`, `RegisteredRemediator`
+  public types.
+- `ServerSupervisor.registerRemediator(remediator)` — writes
+  `<stateDir>/state/supervisor-handshake.json` (`{version,
+  supervisorBuildId, writtenAt}`).
+- `ServerSupervisor.handleRestartRequested(payload)` — verifies HMAC,
+  handshake-version, staleness (5-minute window), and blastRadius
+  (`process | machine` only — `fleet` is refused for Tier-2). On accept,
+  tracks the request and initiates a `performGracefulRestart` cycle.
+- `notifyPendingRemediatorRequestsOnHealthy()` — fires
+  `remediator.onRestartComplete({requestId})` once the next healthy tick
+  lands after a serverRestarting → healthy transition.
+- `canonicalRestartRequestedBody(payload)` exported helper —
+  deterministic byte serialization used as HMAC input on both sides.
+
+The existing `private preflightSelfHeal()` is unchanged; W-2 will wrap
+it. The existing `restart-requested.json` flag path is unchanged (the
+in-process handshake is the canonical F-6 surface; the file-based flag
+remains for AutoUpdater and is co-owned per v3 §3).
+
+Files touched: `src/lifeline/ServerSupervisor.ts`,
+`tests/unit/ServerSupervisor-handshake.test.ts` (new, 9 tests),
+`upgrades/NEXT.md`, this artifact.
+
+## Decision-point inventory
+
+- `handleRestartRequested` — **add** — verifies signed restart requests.
+  This holds blocking authority: a rejection refuses to restart the
+  server. Each rejection branch is a deterministic check on
+  cryptographic state (HMAC, monotonic clock, declared protocol
+  version, declared blast radius), NOT a heuristic message classifier.
+  See section 4 for signal-vs-authority analysis.
+- `registerRemediator` — **add** — idempotent registration; no
+  authority. Side-effects writes `supervisor-handshake.json`.
+- `notifyPendingRemediatorRequestsOnHealthy` — **add** — fires
+  callbacks. Idempotent (entries deleted after first call). No
+  authority.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+- `blastRadius: 'fleet'` is rejected. Tier-2's ServerSupervisor only
+  handles `process` and `machine` restarts. A fleet-wide restart is the
+  coordination-protocol surface's responsibility, not the supervisor's.
+  Refusal is by design and matches v3 §9 Tier-3 deferral; Remediator
+  must not issue fleet-scope restart-requested in Tier-2 anyway.
+- Clock skew > 5 minutes (in either direction) rejects valid requests.
+  This is the documented staleness window per the F-6 spec; widening it
+  would weaken replay defense. Operators with persistent clock skew
+  receive `stale: ageMs=…` in the reject reason; the Remediator
+  surfaces this in audit + alerts via the higher-level dispatch path.
+- Handshake version mismatch is exact-equality only. A future v2
+  protocol must be negotiated by bumping `HANDSHAKE_PROTOCOL_VERSION`
+  on both sides; legacy Remediators speaking v1 will be rejected. This
+  is the A15 contract — partial-upgrade DoS is prevented by refusing,
+  not by best-effort interpolation.
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- The `monotonicTs` field is informational; the HMAC covers it but the
+  supervisor does NOT enforce monotonic ordering across requests. A
+  per-Remediator monotonic counter would close the residual replay
+  window inside the 5-minute staleness budget. F-8 (rest) owns the
+  per-surface monotonic counter (A42); F-6 deliberately punts.
+- The supervisor accepts only the registered Remediator's leaf key. If
+  the Remediator's RemediationKeyVault is rotated mid-flight, an
+  in-flight request signed with the old leaf will fail HMAC
+  verification. This is expected — the overlap window is owned at the
+  vault rotation layer (per F-1's `rotateContext` contract).
+- `RegisteredRemediator.getCapabilityLeafKey()` is called per
+  verification — the supervisor does not cache. This is intentional
+  (lets the Remediator rotate without re-registration) but pushes a
+  small constant cost onto each call. Negligible at expected throughput
+  (≤ 1 restart-requested per process per ~24h per A7 cross-process cap).
+- File-based `restart-requested.json` path is unchanged in this PR.
+  Adding HMAC to the file shape is described in v3 §9 ("HMAC required on
+  ANY plannedRestart:true post-F-6"); the in-process handshake is the
+  Tier-2 canonical surface and file-shape HMAC migration tracks under
+  the AutoUpdater path, not F-6 proper. NEXT.md documents the gap.
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. F-6 lives in `src/lifeline/ServerSupervisor.ts` because the
+supervisor is the only authority that can request a tmux-session
+restart safely. The handshake protocol surface is a thin layer on top
+of the supervisor's existing `performGracefulRestart()`; it does NOT
+re-implement restart logic, doesn't reach into runbook internals, and
+doesn't speak any domain vocabulary above
+`{requestId, runbookId, attemptId, blastRadius}`.
+
+The `canonicalRestartRequestedBody()` exported helper deliberately
+lives at the bottom of the same file so the wire format has one
+canonical owner — both the supervisor's verify path and the
+Remediator's sign path (in F-8 rest) call the same function. Cross-file
+divergence is the most common HMAC-protocol bug; co-locating prevents
+it.
+
+## 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?**
+
+- [ ] No — this change produces a signal consumed by an existing smart gate.
+- [ ] No — this change has no block/allow surface.
+- [x] Yes — but the logic is a smart gate with full conversational context.
+- [ ] Yes, with brittle logic — STOP.
+
+`handleRestartRequested` is a blocking gate. Each rejection condition
+is a deterministic check on cryptographic + structural state, not a
+heuristic message classifier:
+
+1. HMAC verification via `crypto.timingSafeEqual` — pure crypto.
+2. Handshake-version equality — integer compare.
+3. `requestedAt` staleness — wall-clock arithmetic on a signed field.
+4. `blastRadius` allowlist — string-set membership on a signed field.
+5. Required-field shape check — typeof guards.
+
+Every gated field is HMAC-covered by `canonicalRestartRequestedBody()`,
+so an attacker who shifts any field invalidates the signature. The
+gate has the FULL context needed to decide — the canonical body IS the
+context — and the decision is reproducible. This matches the
+"signal-vs-authority" contract: the gate that holds blocking authority
+has the full structured payload, not a free-text excerpt.
+
+## 5. Interactions
+
+**Does this interact with existing checks, recovery paths, or infrastructure?**
+
+- **`performGracefulRestart`:** `handleRestartRequested` calls the
+  existing method on accept. Maintenance wait is pre-set so existing
+  `handleUnhealthy`/serverDown suppression behaves as it does for
+  AutoUpdater-driven restarts.
+- **`restart-requested.json` file path:** Untouched. Both the file path
+  (AutoUpdater) and the in-process path (Remediator) trigger the same
+  `performGracefulRestart`. The two paths are independent and cannot
+  race destructively — `performGracefulRestart` is idempotent at the
+  tmux-session level.
+- **Pending-request notification:** Wired into the existing healthy-
+  tick branch of the health check loop. Idempotent (clears the map
+  after firing). If `onRestartComplete` throws, the supervisor logs and
+  continues — a faulty Remediator callback cannot wedge the supervisor.
+- **`debug-restart-request.json`:** Unrelated path; doctor-session
+  HMAC uses a different secret (`setDoctorSessionSecret`) and a
+  different file. No interaction.
+- **State-file: `supervisor-handshake.json`:** Newly written by
+  `registerRemediator` + `setSupervisorBuildId`. Per v3 §3 it is NOT
+  backed up and NOT git-synced. The path matches v3 §3 verbatim.
+- **`RemediationKeyVault` (F-1):** F-6 takes the leaf key from the
+  registered Remediator via callback, NOT directly from the vault.
+  This keeps the supervisor decoupled from F-1's API surface; the
+  Remediator (which owns the vault lifecycle) injects the key. If F-1
+  rotates the context, the next registration / next call sees the new
+  key.
+
+## 6. External surfaces
+
+**Does this change anything visible to other agents, other users, other systems?**
+
+- **State file:** `<stateDir>/state/supervisor-handshake.json` (new).
+  JSON `{version, supervisorBuildId, writtenAt}`. World-readable by
+  default (same as sibling files in the same dir). No secrets in the
+  body.
+- **Public types:** `RestartRequestedPayload`,
+  `RestartRequestedReply`, `RegisteredRemediator`,
+  `canonicalRestartRequestedBody()` exported from
+  `src/lifeline/ServerSupervisor.ts`. These are stable API surfaces
+  that F-8-rest will consume; bump `HANDSHAKE_PROTOCOL_VERSION` on any
+  wire-format change.
+- **Events:** No new EventEmitter events. The existing
+  `serverRestarting` event still fires from `performGracefulRestart`.
+  `onRestartComplete` is delivered via callback, not event, because it
+  is a per-request notification with a `requestId` correlator (events
+  fan out; callbacks correlate).
+- **No telegram, slack, or external API calls** added.
+
+## 7. Rollback cost
+
+**If this turns out wrong in production, what's the back-out?**
+
+`git revert` on the F-6 PR removes the surface. No data migration:
+
+- `supervisor-handshake.json` is regenerated on next registration; if
+  no consumer registers (post-revert state), the file is stale but inert.
+- No keychain or vault state is touched. F-1 vault is untouched.
+- No restart-requested.json or other state-file shape changes (file
+  shape additions are deferred to a follow-up per §2 above).
+- The F-6 surface is currently uncalled in production code (no
+  Remediator instance calls `registerRemediator` on main yet). Revert
+  is safe at any point before the wrapper-PR series ships.
+
+The A15 7-day age rule is what bounds the rollback risk for downstream
+wrappers: a wrapper that depends on F-6 must wait until F-6 has been
+on main + auto-updated for 7 days before merging, so a revert window
+of < 7 days has zero downstream consumers to break.
+
+---
+
+## Spec anchor
+
+This change implements:
+- **v2 §A15** (partial-upgrade window — supervisor handshake lag rule),
+- **v2 carried-forward §Supervisor coordination** (HMAC-signed
+  restart-requested),
+- **v2 §A20** (key segregation — the supervisor verifies HMACs against
+  the capability-context leaf, not the legacy `~/.instar/agent.key`),
+- **v3 §3** (state-file taxonomy — `supervisor-handshake.json`,
+  `restart-requested.json` co-ownership),
+- **v3 §9** (Tier-2 sequencing — F-6 unblocks W-2..W-4 after the 7-day
+  age requirement).

package/upgrades/side-effects/f7-post-update-migrator-atomic-step.md

@@ -0,0 +1,129 @@
+# Side-Effects Review — F-7: PostUpdateMigrator atomic-step + announceOnce primitives (Tier-2)
+
+**Version / slug:** `f7-post-update-migrator-atomic-step`
+**Date:** `2026-05-13`
+**Author:** `echo`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+Ships F-7 from the Self-Healing Remediator v2 spec (`docs/specs/SELF-HEALING-REMEDIATOR-V2-SPEC.md` §R1 Upgrade invariants + §A35 backup/sync wiring + §A50 hook-shape corrections + §A57 Tier-2 phase manifest).
+
+Two new primitives plus the A35 hook-shape changes:
+
+1. **`MigratorStepEngine`** — atomic, idempotent, run-once-per-version migration steps. Steps are registered by name + version. The engine writes a ledger at `<stateDir>/migrator-steps-completed.json` keyed by `<version>:<step-name>`. A step failure records `outcome: 'failed'` and does NOT roll back prior steps or block subsequent steps — each step is self-contained.
+
+2. **`AnnouncementManager`** — `announceOnce(id, message, channel)` primitive. Emits a message exactly once per id, then never again. Ledger at `<stateDir>/announcements-shown.json`. Used for surfacing migration completions and structural-change notices without spamming the user across restarts.
+
+3. **A35 hook-shape — `GitStateManager.DEFAULT_GITIGNORE` extension.** Const literal now contains five remediation runtime path globs (`remediation/system-reviewer-state-*.json`, `remediation/inbox-*.jsonl`, `remediation/audit-projection-*.jsonl`, `remediation/cross-process-attempts-*.jsonl`, `remediation/llm-raw-*.jsonl`). Exported as `REMEDIATION_GITIGNORE_ENTRIES` for the F-7 atomic step to use as the source-of-truth list.
+
+4. **A35 hook-shape — `BackupManager` exclusion list with feature-flag gate.** New const `REMEDIATION_EXCLUDED_PATH_PREFIXES` (exported) — the five remediation path prefixes. New optional constructor arg `isRemediationEnabled?: () => boolean` parallels the existing `isIntegratedBeingEnabled` gate. When the gate is ON, the prefixes drop any user-added `includeFiles` entry that begins with a remediation prefix. When OFF (or absent), the prefixes are inactive — strictly additive, no back-compat break.
+
+Files touched:
+- `src/core/MigratorStepEngine.ts` (add)
+- `src/core/PostUpdateMigrator.ts` (modify — add `registerStep` + `runPendingSteps` + lazy engine field; existing constructor + all 15 existing migration methods unchanged)
+- `src/core/GitStateManager.ts` (modify — extend `DEFAULT_GITIGNORE` const literal; export `REMEDIATION_GITIGNORE_ENTRIES`)
+- `src/core/BackupManager.ts` (modify — add `REMEDIATION_EXCLUDED_PATH_PREFIXES` const + export; add 5th optional constructor arg `isRemediationEnabled`; gate logic in `resolveIncludedFiles`)
+- `tests/unit/PostUpdateMigrator-atomicStep.test.ts` (add — 8 cases)
+- `tests/unit/AnnouncementManager.test.ts` (add — 5 cases)
+- `tests/unit/PostUpdateMigrator-a35-remediationPaths.test.ts` (add — 5 cases)
+- `upgrades/NEXT.md` (modify — preserves all existing entries; adds A35 + announceOnce entries)
+
+## Decision-point inventory
+
+- `PostUpdateMigrator.registerStep()` — **add** — delegates to lazy `MigratorStepEngine`. Existing 15 `migrate*` methods + `migrate()` orchestrator untouched.
+- `PostUpdateMigrator.runPendingSteps()` — **add** — async; returns `{ steps: [{name, outcome, details}] }`. Never throws.
+- `MigratorStepEngine.registerStep()` — rejects duplicate names, missing version/run.
+- `MigratorStepEngine.runPendingSteps()` — three skip reasons: `already-recorded:<outcome>`, `future-version:<step.version> > <toVersion>`, and explicit `'skipped'` from the step itself. Failed steps record `outcome: 'failed'` and DO NOT retry (operator must clear the ledger entry to retry — surfaces the failure in the report).
+- `MigratorStepEngine.writeLedger()` — atomic temp-file → fsync → rename, `0600` perms.
+- `AnnouncementManager.announceOnce()` — three-input validation (id, message, channel); records BEFORE sink-invoke so a flaky sink cannot cause duplicate emission. Sink throws are swallowed (ledger entry stands).
+- `GitStateManager.DEFAULT_GITIGNORE` const literal — **modify** — append remediation block. Backwards-compatible: previously private const is now exported (no internal call sites broken).
+- `BackupManager` constructor — **modify** — append 5th optional argument. All four existing call sites pass ≤4 args and continue to work.
+- `BackupManager.resolveIncludedFiles()` — **modify** — adds gated exclusion loop. When gate is OFF (the default — every existing caller), behavior is identical to pre-PR.
+
+No new HTTP routes. No new daemon processes. No new file types beyond two JSON ledgers in `<stateDir>`.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+- **A future-version step is silently skipped.** Intended. The ledger is NOT written when the step's version > `toVersion`, so the next upgrade boundary that crosses the threshold runs the step.
+- **A failed step is NOT auto-retried on the next `runPendingSteps()` invocation.** This could be seen as over-blocking — a transient failure (disk full, network blip) gets recorded as `failed` and stays that way. Trade-off accepted because the alternative (unbounded retry on every update) lets a broken step DoS every release. Operator-facing mitigation: the failed entry surfaces in the migration report; clearing the ledger key allows retry.
+- **The `BackupManager` remediation-prefix gate, when ON, drops includeFiles entries whose paths begin with a remediation prefix.** A user who manually adds `.instar/remediation/system-reviewer-state-mine.json` to `config.backup.includeFiles` will see it silently dropped. Mitigated by: (a) the gate defaults to OFF until remediation is enabled; (b) the prefixes are documented in code + spec; (c) this is the explicit spec requirement (A14 "Backed up? no" rows).
+
+No unintended over-blocks.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- **No cross-machine coordination of step execution.** Two machines updating to the same version in parallel each run their own steps independently. The ledger is per-machine. This is the correct model for per-machine state (gitignore lives in `<stateDir>/.gitignore` which is per-machine via the `.instar` git repo), but a future cross-machine migration would need additional coordination.
+- **Step `run()` is not deadline-enforced.** A hung step could block subsequent steps. The engine relies on step authors to be well-behaved. Real-world steps are file I/O against `<stateDir>` and complete in <50ms; a step that calls external APIs should add its own timeout. Worst case: the migrator hangs, the next update boundary sees the same situation; the user can `kill` the process and the ledger remains consistent.
+- **The `announceOnce` sink does not retry.** If a sink fails (e.g. Telegram offline), the announcement is recorded as shown but never delivered. This is the deliberate signal-vs-authority separation: the brittle sink layer does not have authority over the ledger. A future enhancement could add a separate delivery queue; F-7 keeps the primitive minimal.
+- **Ledger corruption is treated as empty.** If `migrator-steps-completed.json` becomes corrupt (truncated, bad JSON), the engine falls back to an empty ledger. This is intentional — the alternative (refuse to migrate) would be worse. Cost: a corrupt ledger causes one round of step re-runs; each step is idempotent by spec.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. The two primitives sit at the `src/core/` layer — the same layer as `PostUpdateMigrator`, `GitStateManager`, `BackupManager`. They compose on top of `node:fs` only; no dependency on the Remediator (Tier-2 surfaces will register their own steps via `migrator.registerStep(...)` after import). The A35 const-literal extensions sit where the const lives — `GitStateManager` for the gitignore, `BackupManager` for the exclusion prefixes. No new plugin/register API was introduced per A50's explicit ruling.
+
+The `PostUpdateMigrator` class is the right owner for the public-facing `registerStep`/`runPendingSteps` methods even though the engine logic lives in `MigratorStepEngine` — the existing class is already the documented entry point for "thing that runs on update boundary". Tier-2/Tier-3 surfaces (S-2, S-3) will reach for `PostUpdateMigrator` first.
+
+---
+
+## 4. Signal-vs-authority compliance
+
+The brittle/low-context layers (file I/O ledger reads, sink invocations) are signal layers. The higher-context layer (the `runPendingSteps` orchestrator) is the authority. Specifically:
+
+- A corrupt ledger does NOT block migration — the ledger is treated as a signal ("here's what we believe happened"), and the engine recovers by treating it as empty. Authority over "should this step run" lives in the in-memory step list + the version comparison.
+- A failing sink does NOT block `announceOnce` from recording the announcement — sink delivery is signal; the ledger record is authority over "have we already attempted to surface this".
+- A failing step does NOT block other steps — the per-step try/catch isolates signals; the engine retains authority over the run sequence.
+
+This matches the §A50 / signal-vs-authority principle in MEMORY.md.
+
+---
+
+## 5. Interactions with existing surfaces
+
+- **`PostUpdateMigrator.migrate()` is untouched.** Existing callers (`src/update/UpdateService.ts`, `src/commands/init.ts`, etc.) continue to work — they call `migrate()` and never touch the new methods.
+- **`GitStateManager.init()`** — writes `DEFAULT_GITIGNORE` only when no `.gitignore` exists. Existing repos with `.gitignore` already on disk are unaffected. New repos get the remediation entries pre-included.
+- **`BackupManager` callers** — 14 existing call sites pass at most 4 constructor args. The new 5th arg is optional + defaults to no-op behavior. Verified by running the full `backup-manager.test.ts` (44 cases) and `BackupManager-sharedState.test.ts` (3 cases) — all pass unchanged.
+- **`upgrades/NEXT.md`** — only appended to (preserving the W-1, F-8, F-3, F-4, F-1..F-2 entries already on main).
+
+---
+
+## 6. Rollback cost
+
+Low. The two new modules (`MigratorStepEngine.ts`, the new methods on `PostUpdateMigrator.ts`) are dormant unless something calls `registerStep` — and nothing calls it in this PR. Tier-2 surfaces will be the first consumers. Reverting requires:
+
+1. `git revert` the PR. No data migration. No format changes. Existing `migrate()` behavior is untouched.
+2. If any agent has already created `migrator-steps-completed.json` or `announcements-shown.json` files, they become unused leftovers — no harm. They can be deleted at leisure.
+
+The A35 const-literal changes are inline edits to existing files; revert restores the prior literal. The `BackupManager`'s 5th constructor arg is optional and unused by every current caller, so removing it has zero blast radius.
+
+---
+
+## Tests
+
+- `tests/unit/PostUpdateMigrator-atomicStep.test.ts` — 8 cases covering: step runs once and records completion; step is skipped on subsequent runs; failed step records failure and doesn't block other steps; future-version step skipped without ledger entry; state persists across instances; semver compare correctness.
+- `tests/unit/AnnouncementManager.test.ts` — 5 cases covering: first-true / subsequent-false; independent ids; persistence across instances; sink-throw does not cause re-emission; input validation.
+- `tests/unit/PostUpdateMigrator-a35-remediationPaths.test.ts` — 5 cases covering: `DEFAULT_GITIGNORE` contains all five remediation entries; `REMEDIATION_EXCLUDED_PATH_PREFIXES` exported correctly; gate ON drops remediation entries; gate OFF preserves them; absent callback = back-compat (gate OFF).
+
+All 18 new tests pass. All 76 pre-existing `PostUpdateMigrator-*` tests pass unchanged. All 47 `BackupManager*` tests pass unchanged. TypeScript clean (`tsc --noEmit`).
+
+---
+
+## Gate trace
+
+- side-effects review: this document
+- NEXT.md: amended, preserving every prior entry
+- spec citation: `docs/specs/SELF-HEALING-REMEDIATOR-V2-SPEC.md` §R1 + §A35 + §A50 + §A57
+- worktree: `/tmp/instar-f7-post-update-migrator` (branch `f7-post-update-migrator`)
+- no bypass; no `--no-verify`