instar 0.28.102 → 0.28.103

package/upgrades/side-effects/eli16-overview-required-gate.md

@@ -0,0 +1,77 @@
+# Side-Effects Review — ELI16 overview required for every approved spec
+
+**Version / slug:** `eli16-overview-required-gate`
+**Date:** 2026-05-13
+**Author:** echo
+**Second-pass reviewer:** not required (structural gate; deterministic; small surface)
+
+## Summary of the change
+
+Adds a third structural check to the `/instar-dev` precommit gate and to `/spec-converge`'s convergence-tag writer: every approved spec must ship with a plain-English ELI16 overview at `docs/specs/<slug>.eli16.md` (or a path declared via the spec's `eli16-overview:` frontmatter field). The overview must be at least 800 characters of trimmed content — stubs are refused. Files touched: `scripts/eli16-overview-check.mjs` (new shared module), `scripts/instar-dev-precommit.js`, `skills/spec-converge/scripts/write-convergence-tag.mjs`, `skills/instar-dev/SKILL.md`, `skills/spec-converge/SKILL.md`, `skills/instar-dev/templates/eli16-overview.md` (new template), `tests/unit/eli16-overview-check.test.ts` (new unit test).
+
+## Decision-point inventory
+
+- `scripts/instar-dev-precommit.js` Step 7 (new) — **add** — refuses a commit if the spec referenced by the trace has no ELI16 companion or the companion is a stub. Pure file-existence + length check; deterministic; no LLM judgment.
+- `skills/spec-converge/scripts/write-convergence-tag.mjs` (new pre-check) — **add** — refuses to stamp `review-convergence` on a spec without an ELI16 companion. Same deterministic check.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+- **Bootstrap exceptions remain intact.** The existing bootstrap-trigger logic for the precommit gate (which lets the gate's own first-ship pass) is upstream of the ELI16 check; bootstrap commits already exit before any spec-tag verification runs. So no over-block on bootstrap.
+- **Out-of-scope commits remain unaffected.** The ELI16 check runs only after `inScopeFiles.length > 0` and after the spec-tag verification, so docs-only or release-note commits never hit it.
+- **Existing approved specs with shipped work.** Forward-only — old specs whose work has already merged are not re-committed against, so the gate doesn't fire on them. If a contributor wants to amend an old spec post-ship, they'll need to add an ELI16; this is the intended behavior.
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- An ELI16 file that satisfies the length requirement but contains low-quality / jargon-heavy / non-ELI16 prose. The gate checks file existence and length, not reading-level. This is intentional: deterministic check, no LLM judgment in a precommit hook. Reading-level enforcement happens at the human-review step (the user reads the overview before applying `approved: true`).
+- An ELI16 file that's pure boilerplate copied from the template. The 800-char floor reduces this risk but doesn't eliminate it. Mitigation: the template's section headers are themselves substantive prompts requiring real content; copying without filling-in is hard to disguise at 800+ chars.
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer? Should a higher or lower layer own it? Does a smarter gate already exist?**
+
+Yes — this is at the same layer as the existing review-convergence and approved tag checks. Same deterministic-file-check shape, same precommit + convergence-write hook points, same shared concern (spec quality at handoff time). No smarter gate exists for "is the spec readable by the decider"; the existing gates verify that review *happened*, not that the spec is *legible*.
+
+## 4. Signal vs authority compliance
+
+**Does this hold blocking authority with brittle logic, or does it produce a signal?**
+
+Authoritative, deterministic, structural. The check is file-existence + content-length — both verifiable, both stable, no LLM/regex/parsing surprises. This is the canonical shape for blocking authority per `docs/signal-vs-authority.md`: structural gates are allowed to block; brittle/heuristic gates produce signals for a smarter gate.
+
+## 5. Interactions
+
+**Does it shadow another check, get shadowed, double-fire, race?**
+
+- **Order in precommit:** runs after spec-tag verification (`review-convergence`, `approved: true`). If either of those fails, the ELI16 check is never reached — single source of error at a time.
+- **Order in spec-converge:** runs BEFORE the convergence tag is written. Prevents the asymmetric state where a spec is tagged converged but has no overview.
+- **Duplicate check on commit:** both `write-convergence-tag.mjs` (at convergence time) and `instar-dev-precommit.js` (at commit time) verify the ELI16. This is intentional belt-and-suspenders — a spec that lost its ELI16 between convergence and commit (file deleted) is still caught at commit.
+- **No race conditions.** Both checks are synchronous read-only file checks.
+
+## 6. External surfaces
+
+**Does it change anything visible to other agents, other users, other systems?**
+
+- Other agents using `/instar-dev` against the instar repo will see the new check fire on any commit referencing a spec without an ELI16. Error message is explicit about how to fix (add a sibling file or declare via frontmatter).
+- Users handed a spec by an agent will receive an ELI16 overview by default — this is the user-visible improvement that motivated the gate. Topic 3079 (2026-05-13) was the trigger.
+- No timing dependencies, no conversation state, no runtime conditions. The check sees the filesystem at commit time, period.
+
+## 7. Rollback cost
+
+**If this turns out wrong in production, what's the back-out?**
+
+Single-line revert in each of two files: comment out the `checkEli16Overview` block in `scripts/instar-dev-precommit.js` (Step 7) and in `skills/spec-converge/scripts/write-convergence-tag.mjs` (pre-check). No data migration. No state mutation. No effect on already-tagged specs. The shared module `scripts/eli16-overview-check.mjs` becomes dead code until removed, but that's harmless. The template at `skills/instar-dev/templates/eli16-overview.md` remains as documentation. The next release picks up the revert automatically — no schema or wire-format change to coordinate.
+
+## Trust elevation
+
+Not applicable — no autonomy profile change, no new trust-level surface.
+
+## Side-effects on adjacent systems
+
+- `husky/pre-commit` calls `instar-dev-precommit.js`; no change to husky config.
+- The release-cut publish gate is unaffected: ELI16 enforcement is at commit-time, not at release-cut time. Spec authors get the error at the point of authorship, where it's fastest to fix.
+- Backup/sync: no new state files. The ELI16 companion is a regular spec sibling, gitignored or not per the repo's existing `.gitignore`.

package/upgrades/side-effects/f1-remediation-key-vault.md

@@ -0,0 +1,195 @@
+# Side-Effects Review — F-1 RemediationKeyVault
+
+**Version / slug:** `f1-remediation-key-vault`
+**Date:** 2026-05-13
+**Author:** echo (instar-developing agent)
+**Second-pass reviewer:** not required
+
+## Summary of the change
+
+This change adds `src/remediation/RemediationKeyVault.ts`, the Tier-1 cryptographic
+foundation for the Self-Healing Remediator (per `docs/specs/SELF-HEALING-REMEDIATOR-V2-SPEC.md`,
+amendments A20, A23, A39, A42, A51, A54, A58, A62). The module exposes a
+per-context, per-scope HKDF-SHA256 leaf-key derivation surface backed by a
+4-backend secret store (OS keychain → hardware enclave stub → cloud KMS stub →
+env-passphrase + AES-256-GCM flatfile). It also adds
+`tests/unit/RemediationKeyVault.test.ts` (20 tests).
+
+Files touched: `src/remediation/RemediationKeyVault.ts` (new),
+`tests/unit/RemediationKeyVault.test.ts` (new), `upgrades/NEXT.md` (release-note
+entry), this artifact.
+
+The module is **not yet consumed** by any runtime path. F-2+ wires the Remediator's
+dispatch, probe, in-flight, ledger, and audit surfaces to derive leaf keys via this
+vault. F-1 ships the foundation in isolation so it can be exercised in tests and
+reviewed against the spec before downstream consumers depend on it.
+
+## Decision-point inventory
+
+- `RemediationKeyVault.forStateDir / selectBackend` — **add** — selects which secret
+  backend (keychain / hardware-enclave / cloud-KMS / env-passphrase) the vault uses.
+  This is a configuration decision, not a security gate: it does not block any
+  inputs, it picks where keys live.
+- `loadOrInitKeychain / loadOrInitFlatFile` — **add** — fresh-install vs.
+  pre-existing-install branching. The fail-closed paths (partial-master,
+  install-nonce-missing-on-existing-install) refuse to start the vault, which is
+  authority. See section 4 for signal-vs-authority analysis.
+- `deriveLeafKey` — **add** — pure function over (master, nonce, info). No
+  decision-point surface; refuses only on `info.length > 1024` (Node HKDF cap).
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+- `RemediationKeyVault.forStateDir` with no keychain available and no env
+  passphrase configured throws `no-backend-available`. Legitimate but
+  mis-configured deployments (e.g., a fresh Docker container forgetting to set
+  `INSTAR_REMEDIATION_KEY_PASSPHRASE`) will fail to start. This is intentional
+  per A62 — the alternative is silently running with no secret store, which is
+  worse — but the error message must guide the operator. The error explicitly
+  names the missing requirement; downstream callers should surface this to the
+  operator via existing alert paths.
+
+- `partial master state` (some context masters exist, others don't) refuses to
+  load. This will only fire if a manual keychain edit deleted some entries, or
+  if a previous `rotateContext` crashed mid-write. Recovery is to delete the
+  remaining entries and let the loader mint a fresh install. F-2 should add an
+  `instar remediation reset` CLI; for F-1, the operator can use the `security`
+  CLI directly.
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- F-1's keychain ACL is the OS default ("any process owned by user"), NOT the
+  per-binary-path ACL described in A39. A39 specifies
+  `SecAccessCreateWithOwnerAndACL` scoped to the agent binary path; this requires
+  the macOS `Security.framework` native binding (not exposed via the `security`
+  CLI). F-1 ships the multi-backend abstraction; F-2 layers the scoped ACL on top
+  via a native module. Same-uid attacker can still read keychain entries on
+  macOS with the default ACL. Documented as a follow-up in NEXT.md.
+
+- The hardware-enclave and cloud-KMS backends are explicit stubs that return
+  `false` from their availability probes. They never fire in F-1; everyone runs
+  on keychain or env-passphrase. F-2+ implements detection + key wrapping for
+  TPM 2.0 and the three cloud providers.
+
+- The flatfile is named `<stateDir>/remediation-keys.age` for forward
+  compatibility, but uses Node's built-in AES-256-GCM (scrypt KDF), NOT the `age`
+  format. Operators expecting `age decrypt` to work on the file will be surprised.
+  The file's JSON payload self-identifies (`version: 1, kdf: 'scrypt'`); the
+  naming is documented in the source comment block.
+
+- The fresh-install branch mints the install nonce unconditionally when no
+  masters exist. A malicious deletion of all keychain entries would let an
+  attacker force the vault to mint a NEW install nonce, invalidating all
+  previously-signed tokens — but this is the documented A39/A51 recovery shape
+  (rotate-install-nonce CLI), not a vulnerability. Callers that need to detect
+  "this is supposed to be an existing install" pass `freshInstallGate: false`,
+  which refuses to mint.
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. This module is the cryptographic primitive layer — a pure HKDF derivation
+over a deterministic secret store. It has no awareness of Remediator concepts
+(runbooks, probes, surfaces). Higher-level F-PRs (F-2 capability-token issuer,
+F-3 probe registry, F-4 in-flight lockfile authority) compose this primitive
+into their own authority paths.
+
+The 4-backend abstraction deliberately reuses the pattern from
+`src/core/WorktreeKeyVault.ts` (per A39's prior-art note) rather than
+introducing a parallel secret-storage system. The two vaults share the
+keychain-CLI wrappers (`security` on macOS, `secret-tool` on Linux) and the
+flatfile + scrypt + AES-GCM pattern, but are otherwise independent — they store
+different key material under different keychain services
+(`instar.parallel-dev` vs `ai.instar.remediation`).
+
+## 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.
+- [x] No — this change has no block/allow surface.
+- [ ] Yes — but the logic is a smart gate with full conversational context.
+- [ ] Yes, with brittle logic — STOP.
+
+`RemediationKeyVault` is a cryptographic primitive. It does not classify
+messages, gate dispatch, or filter actions. The only "refusals" it makes are:
+
+1. Backend unavailable + no fallback configured → throw (operator-visible
+   configuration error, not a signal-vs-authority decision).
+2. Partial-master state → throw (state-integrity refusal; the keychain has been
+   tampered with or a write crashed mid-flight).
+3. Install-nonce missing on a pre-existing install → throw per A51 (this is the
+   "fail-closed" leg of the documented recovery shape).
+
+None of these are heuristic message classifiers; they are deterministic checks
+on persisted state. The signal-vs-authority principle applies to higher-level
+F-PRs that consume the derived leaf keys (capability-token verification,
+probe-event signature verification, etc.). Those are out of scope for F-1.
+
+## 5. Interactions
+
+**Does this interact with existing checks, recovery paths, or infrastructure?**
+
+- **Shadowing:** No existing path uses `ai.instar.remediation.*` keychain
+  entries; this is a fresh namespace. The vault is a peer of, not a successor
+  to, `WorktreeKeyVault`.
+- **Race with adjacent cleanup:** `rotateInstallNonce` overwrites the in-memory
+  nonce in place to keep references consistent. A concurrent
+  `deriveLeafKey` call mid-rotation will observe either the old or new nonce
+  (Node single-threaded JS — no torn reads on the Buffer copy). Downstream
+  callers needing strict ordering must serialize their rotation through a
+  promise lock at their level. F-2 owns this concern.
+- **Heartbeat / lifecycle interaction:** None. The vault does not own any
+  timers, intervals, or fs watchers.
+
+## 6. External surfaces
+
+**Does this change anything visible to other agents, other users, other systems?**
+
+- **Keychain entries added:** `ai.instar.remediation.install-nonce`,
+  `ai.instar.remediation.capability`, `ai.instar.remediation.probe`,
+  `ai.instar.remediation.inflight`, `ai.instar.remediation.ledger`,
+  `ai.instar.remediation.audit`. Six entries per machine. Users may see these
+  in `Keychain Access.app`. They are only created when a downstream consumer
+  (F-2+) instantiates the vault — F-1 alone does not seed them outside of test
+  runs (tests use the env-passphrase flatfile via `tmpdir`).
+- **Flatfile path:** `<stateDir>/remediation-keys.age` when env-passphrase mode
+  is active. `0600` permissions. The `.age` suffix is forward-compat naming;
+  the inner payload is Node-native AES-GCM.
+- **Env var:** `INSTAR_REMEDIATION_KEY_PASSPHRASE`. Read at vault load time.
+  Documented in the source.
+
+## 7. Rollback cost
+
+**If this turns out wrong in production, what's the back-out?**
+
+F-1 ships an unused module. No runtime path consumes it yet. Rollback is
+`git revert` on the F-1 PR, no data migration, no agent state repair. The six
+keychain entries (when minted by tests on a developer's machine) can be left
+in place; they are inert without a consumer.
+
+When F-2+ ships and consumers depend on the vault, rollback cost increases:
+in-flight tokens signed by the F-1 leaves become unverifiable, and rotation
+overlap windows owned by each surface absorb the disruption. F-1's rollback
+cost is bounded by "delete six keychain entries"; downstream F-PRs carry
+their own rollback artifacts.
+
+---
+
+## Spec anchor
+
+This change implements amendments **A20** (key segregation), **A23** (replay
+defense via the install-nonce in derivation), **A39** (per-runbook/per-surface
+leaf keys), **A42** (counter persistence is downstream — F-1 only provides the
+leaf-key surface used by the audit-token writer), **A51** (install nonce sealed
+in keychain, NOT a flatfile under the OS-keychain backend), **A54** (HKDF info
+field with fixed-length context tag + length-prefixed scopeId), **A58** (4-backend
+matrix), and **A62** (operating-state matrix for fail-closed behavior).

package/upgrades/side-effects/f2-redactor-errorcode-extractor.md

@@ -0,0 +1,130 @@
+# Side-Effects Review — F-2: Redactor + ErrorCodeExtractor
+
+**Version / slug:** `f2-redactor-errorcode-extractor`
+**Date:** `2026-05-13`
+**Author:** `echo`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+Adds two new foundation modules for the Self-Healing Remediator v2 (per spec §A1 Foundation manifest, F-2):
+
+- `src/monitoring/Redactor.ts` — centralized redaction pipeline that strips secrets, identifiers, and absolute paths from text before it crosses any persistence, alert, or LLM-prompt boundary. Default rules cover home-dir paths, bearer/Telegram tokens, emails, UUIDs, long hex, IPv4/IPv6, and ≥6-digit numeric IDs. Composable via `extraRules`.
+- `src/monitoring/ErrorCodeExtractor.ts` — extracts a canonical `errorCode` from one of four structured sources and stamps a `provenance` tag (`native-binding | probe-id | subsystem-explicit | free-text`). Implements §A6: the runbook registry validator can call `isAllowedForRunbookMatch` to refuse matchers that would consume free-text-provenance events.
+
+Tests: `tests/unit/Redactor.test.ts` (25 cases) + `tests/unit/ErrorCodeExtractor.test.ts` (21 cases). No consumer code yet — F-3 (DegradationReporter migration) and W-* runbook wrappers wire these up.
+
+Files touched:
+- `src/monitoring/Redactor.ts` (new)
+- `src/monitoring/ErrorCodeExtractor.ts` (new)
+- `tests/unit/Redactor.test.ts` (new)
+- `tests/unit/ErrorCodeExtractor.test.ts` (new)
+- `upgrades/NEXT.md` (entry append)
+
+## Decision-point inventory
+
+- `ErrorCodeExtractor.isAllowedForRunbookMatch` — **add** — gating predicate the registry-load-time validator (built in a later PR) calls to refuse matchers against free-text-provenance events. The predicate itself is pure and side-effect-free.
+- `Redactor.redact` / `Redactor.redactFields` — **add** — content transformation, no block/allow surface. Used by callers to sanitize before crossing trust boundaries.
+- `ErrorCodeExtractor.extract` priority ladder — **add** — chooses which input source becomes the `errorCode` for a NormalizedDegradationEvent. Unverified probe emissions are silently demoted (signal source is untrusted) rather than producing a probe-id provenance.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+- `Redactor.redact` may over-redact in two cases: (a) a legitimate ≥6-digit number (e.g. an HTTP status code referenced as a literal `200000`) collapses to `<NUM>` — acceptable because run-of-the-mill error text rarely contains literal big numbers, and false-positive redaction is preferable to leaking a real ID; (b) a real path on disk that happens to look like `/Users/<word>` always redacts, even when no user data is in it. Both are intentional: the redactor is the brittle low-level signal, not the smart authority — false positives are safe, false negatives are not.
+- `ErrorCodeExtractor.extract` does not "reject" any input — it always returns a result. The `isAllowedForRunbookMatch` predicate rejects free-text provenance, which is the entire point of §A6. No legitimate runbook should match on free-text by design (matchers must consume structured sources).
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- `Redactor` cannot redact what it doesn't pattern-match. Novel secret shapes (a new vendor's API-key format, an unusual UUID variant, base64-only tokens without a `Bearer` prefix) will pass through. Mitigation: `extraRules` lets callers extend per-surface; the F-3 DegradationReporter migration will set a baseline set of patterns; SystemReviewer corpus tests (later phases) catch drift.
+- `ErrorCodeExtractor` will return `provenance: 'free-text'` + `UNKNOWN_ERROR` for any novel failure shape. That's the intended steady state — A26 NovelFailureReviewer clusters these and proposes new runbooks via the /instar-dev path. The under-block here is not a bug; it's the trigger for SystemReviewer.
+- Probe-id provenance is gated on a caller-supplied `verifyProbeSignature` function. If a caller forgets to pass one, the probe emission silently demotes to lower-priority sources. This is fail-closed (an attacker can't shape errorCode by spoofing the probe path) but a caller could mistakenly believe probe emissions are honored when they aren't. F-3 / W-* PRs that wire this up will own the verifier.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+`Redactor` is a **low-level detector** — it produces sanitized text plus a count summary. It does NOT decide whether to alert, persist, or drop an event. That authority belongs to DegradationReporter (F-3) and downstream consumers. Correct level.
+
+`ErrorCodeExtractor` is also a **low-level extractor** — pure function over a structured input. It does NOT decide what to do with the extracted code. The `isAllowedForRunbookMatch` predicate is a signal the runbook registry validator (a smart authority, built in a later PR) calls — the extractor itself has no block/allow surface on the event path. Correct level.
+
+Neither module re-implements anything that exists today: there is no shared redactor in src/ to replace (the spec §A1 explicitly notes "v1 was never built"), and ErrorCodeExtractor is genuinely new.
+
+---
+
+## 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 produces a signal consumed by an existing smart gate.
+
+`Redactor` produces sanitized strings + a redaction summary — pure transformation, no block/allow. Callers (DegradationReporter F-3, runbook auditors, SystemReviewer) own any decisions.
+
+`ErrorCodeExtractor.extract` is pure extraction. `isAllowedForRunbookMatch` is a predicate the runbook **registry validator** (a smart authority with full context — sees the entire matcher definition, the event corpus, and the runbook lifecycle state) calls. The extractor publishes the signal (the provenance tag); the validator decides whether to load the runbook. This is exactly the signal-vs-authority split §A6 requires.
+
+---
+
+## 5. Interactions
+
+**Does this interact with existing checks, recovery paths, or infrastructure?**
+
+- **Shadowing:** none today — these modules have no callers in this PR. F-3 will wire `DegradationReporter` to use them; until then they're dead code, by spec design (foundation must land before any wrapper).
+- **Double-fire:** none — pure functions, no side effects.
+- **Races:** none — no shared mutable state. Each `Redactor` instance owns its rule list; `ErrorCodeExtractor` is static.
+- **Feedback loops:** none — these modules don't write to disk, network, or any other surface that could feed back.
+- **Adjacent cleanup:** the existing `DegradationReporter` (untouched in this PR per F-3 scope boundary) continues to produce its legacy `DegradationEvent` shape. F-3 will introduce the back-compat shim per §A33; until then there's zero behavioral change for any current degradation emit-site.
+
+---
+
+## 6. External surfaces
+
+**Does this change anything visible outside the immediate code path?**
+
+- **Other agents on the same machine:** no — no shared state.
+- **Other users of the install base:** no — modules are not wired into any runtime path in this PR. Behavior on `main` after merge is unchanged for end users.
+- **External systems:** no.
+- **Persistent state:** no — these modules don't read or write any file. (Future callers in F-3 will, but not these modules themselves.)
+- **Timing or runtime conditions:** no — pure synchronous functions, no clocks.
+- **API surface changes:** two new exported modules under `src/monitoring/`. They appear in the public surface of the package, but with no consumers in this PR, no migration risk.
+
+---
+
+## 7. Rollback cost
+
+**If this turns out wrong in production, what's the back-out?**
+
+- Pure code addition, no consumers. Revert = delete files + revert the NEXT.md entry. No persistent state, no user-visible regression during rollback window. No agent state repair needed.
+- If a default redaction rule produces a false positive that surprises a downstream caller in F-3+, the fix is to refine the regex in `Redactor.ts` and ship a patch. The redactor's API (the `RedactionRule` type + the `redact`/`redactFields` shape) is stable and the cost of a rule tweak is one PR.
+- If a free-text pattern in `ErrorCodeExtractor` produces a misclassification, downstream consumers see `provenance: 'free-text'` and the runbook registry refuses any matcher that would have fired on it. The misclassification surfaces as a clustering signal in SystemReviewer (a later phase), not as a misfired runbook. Fail-safe by design.
+
+---
+
+## Conclusion
+
+Pure-foundation PR with two new modules and 46 passing unit tests. No consumers wired in this PR (per spec §A1 ordering: F-2 must land before F-3, and F-3 owns the wiring). Signal-vs-authority compliance is straightforward — both modules are detectors/extractors with no blocking surface; the §A6 provenance gate is a signal consumed by a smart authority (the runbook registry validator) that will be built in a later PR.
+
+Clear to ship.
+
+---
+
+## Second-pass review (if required)
+
+Not required — this PR has no block/allow surface on outbound/inbound messaging, no session lifecycle touch, no context-exhaustion handling, no coherence/idempotency/trust gates, and is not a sentinel/guard/gate/watchdog.
+
+---
+
+## Evidence pointers
+
+- `npx vitest run tests/unit/Redactor.test.ts tests/unit/ErrorCodeExtractor.test.ts` → 46 passed, 0 failed (run during build).
+- `npx tsc --noEmit` → clean.
+- Spec section references: `docs/specs/SELF-HEALING-REMEDIATOR-V2-SPEC.md` §A1 (foundation manifest F-2 ordering), §A6 (errorCode provenance), §A26 (Redactor consumer in NovelFailureReviewer), §A33 (DegradationReporter migration — out of scope, for F-3).

package/upgrades/side-effects/f3-degradation-reporter-shim.md

@@ -0,0 +1,105 @@
+# Side-Effects Review — F-3: DegradationReporter normalization shim
+
+**Version / slug:** `f3-degradation-reporter-shim`
+**Date:** `2026-05-13`
+**Author:** `echo`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+Ships the F-3 milestone of the Self-Healing Remediator v2 foundation (per `docs/specs/SELF-HEALING-REMEDIATOR-V2-SPEC.md` §A5, §A33, §A50): an **additive, back-compat shim** on `DegradationReporter` that introduces the `NormalizedDegradationEvent` contract, a `reportStructured()` go-forward emit API, a `setRemediator()` hook for the future F-8 dispatcher, and a durable `RestartPending` queue at `<stateDir>/remediation/degradations-queue.jsonl` (1000 entries / 5 MiB cap, drop-and-counter on overflow). All ~103 existing legacy `.report(...)` callers continue to work unchanged; they are normalized internally to `provenance: 'free-text'` and (per §A6) cannot match any runbook prefilter — they will route to `no-matching-runbook` once F-8 ships.
+
+A new warning-only lint at `scripts/lint-degradation-emit-sites.js` catalogues every emit site (legacy vs structured) without blocking. F-8 may upgrade it to blocking once a deprecation timeline is agreed.
+
+Files touched:
+- `src/monitoring/DegradationReporter.ts` (modify — adds `NormalizedDegradationEvent`, `RemediatorLike`, `reportStructured()`, `setRemediator()`, `_normalize()`, `_setRestartPending()`, `_readRestartPendingQueue()`, `_getQueueDropCount()`, plus durable-queue plumbing)
+- `scripts/lint-degradation-emit-sites.js` (new — warning-only)
+- `tests/unit/degradation-reporter.test.ts` (extend — 9 new tests for the F-3 shim)
+- `upgrades/NEXT.md` (append F-3 entry)
+
+## Decision-point inventory
+
+- `DegradationReporter.report` — **modify** — legacy entry point. New behaviour: routes to Remediator (if wired) OR to RestartPending queue (if flag set) OR to legacy alert path (default). Backward-compat: when no Remediator and no RestartPending, behaviour is byte-identical to pre-F-3.
+- `DegradationReporter.reportStructured` — **add** — new emit API for go-forward callers. No legacy alert path — structured callers MUST wire a Remediator (F-8) or their events are recorded-only.
+- `DegradationReporter.setRemediator` — **add** — registration hook for the F-8 dispatcher. No consumer wired in this PR.
+- `DegradationReporter._setRestartPending` — **add** — supervisor-controlled flag that re-routes events to the durable queue. The flag itself is the authority; no brittle inference logic.
+- `DegradationReporter._normalize` — **add** — pure transform from legacy → normalized. Always tags `provenance: 'free-text'`. §A6 already forbids matchers against free-text-provenance events; no new authority is added by the normalization.
+- `scripts/lint-degradation-emit-sites.js` — **add** — warning-only catalogue. Exits 0 always.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+- The change has no block/allow surface on the emit path itself — legacy `.report()` still always succeeds in recording an event. The only "rejection" is the queue cap: events emitted during RestartPending past entry 1000 or byte 5 MiB are silently dropped and counted. That's per spec §A5 (drop-and-counter on overflow) and is by design: the alternative (unbounded queue growth during a long restart-pending window) is worse. Operators see the loss via `_getQueueDropCount()` and the sidecar file `degradations-queue.jsonl.drops.json`.
+- `reportStructured()` does NOT fall through to the legacy alert path. Structured callers without a wired Remediator will see their events recorded but not alerted. This is intentional per §A33: legacy alert side-channel is for legacy callers; structured callers belong to the Remediator path.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- Legacy callers continue to land at `no-matching-runbook` because their provenance is `free-text` — per §A6 this is the intended steady state, not a gap. The under-block here is exactly what NovelFailureReviewer (A26 — not in this PR) is designed to consume: cluster the unmatched events and propose new runbooks.
+- The `_normalize` errorCode extraction inherits the F-2 free-text regex set. Novel error-text shapes return `LEGACY_DEGRADATION` rather than a more specific code; NovelFailureReviewer (later PR) is the smart layer that proposes new runbooks for those.
+- RestartPending replay does NOT enforce the §A30 5-second wall-time cap or coalescing logic — that authority belongs to the F-8 Remediator dispatcher, which sees the replayed events one by one. F-3 only provides the durable surface.
+- The queue file is per-machine and not synced. If a machine restart-pending-windows and the agent's state-dir is on a different machine after rebalancing, the queue is lost. Acceptable: RestartPending is a process-lifetime concept tied to the lifeline supervisor that owns the file.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+`DegradationReporter` is the right layer for the shim. It's the single emit point for every degradation in the codebase; placing the normalize/dispatch wiring elsewhere would require touching all ~103 emit sites today instead of zero. The shim preserves the legacy emit API exactly and lets the migration be incremental — which is the precise intent of §A33 / §A50.
+
+The RestartPending queue lives inside `DegradationReporter` rather than a separate `RestartPendingQueue` module because (a) only this reporter feeds it, (b) the durability story is local to the reporter's stateDir, and (c) F-8 will own the higher-layer replay scheduler. Pulling it out to its own module now would over-fit; pulling it out later if F-8 needs cross-reporter queue management is a refactor with no behaviour change.
+
+The lint is at the right layer (a repo-level grep), produces a single warning-only signal, and explicitly defers authority to F-8 — that matches signal-vs-authority.
+
+---
+
+## 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 shim is a routing change, not a decision point. `_normalize()` is a pure transform. `setRemediator()` is a registration hook. `_setRestartPending()` is set by the lifeline supervisor (the higher-layer authority), not inferred by the reporter. The lint script is warning-only and exits 0 always. The §A6 free-text provenance contract IS an authority — refusing runbook matchers — but that authority lives in the runbook registry validator (F-8), not here. F-3 only stamps the provenance; F-8's smart gate enforces the refusal.
+
+---
+
+## 5. Interactions
+
+**Does this interact with existing checks, recovery paths, or infrastructure?**
+
+- **Shadowing:** The existing legacy alert path (`reportEvent`) still runs when no Remediator is wired. When a Remediator IS wired, the legacy alert path is BYPASSED for new events — that's the point of A33's "the legacy Telegram-alert path fires only on `no-matching-runbook`." F-3 wires the bypass; F-8 wires the round-trip back to `no-matching-runbook → legacy alert`.
+- **Self-heal interaction:** The existing `registerHealer` / `attemptSelfHeal` flow runs inside `reportEvent`. When a Remediator IS wired, healers are NOT invoked — the Remediator is expected to own the heal-or-alert decision. This is acceptable for the F-3 PR because no Remediator is wired today; healers continue to run on every emit. F-8's design must explicitly cover healer composition with runbooks (it does — A50 places healer-vs-runbook precedence on the Remediator side).
+- **Persistence:** The legacy `degradations.json` file continues to receive every event for the health-check API. The new queue file (`remediation/degradations-queue.jsonl`) is independent — events under RestartPending are recorded in both. No double-dispatch risk: queued events flow through replay → dispatch, never through the legacy alert path twice.
+- **Drop-counter sidecar:** `degradations-queue.jsonl.drops.json` is the only new file outside the reporter's `degradations.json`. Backup/sync rules (per A35): the queue lives under `.instar/remediation/` which F-7 will add to `BackupManager`'s exclusion list (per-machine). No backup-sync changes ship in this PR.
+
+---
+
+## 6. External surfaces
+
+**Does it change anything visible to other agents, other users, other systems?**
+
+- **Behavioural surface:** Zero change for current users. No Remediator is wired in F-3, so every legacy `.report()` call follows the same code path it did pre-F-3. No new files exist on disk until F-8 sets RestartPending, which it cannot yet.
+- **Type surface:** `NormalizedDegradationEvent` and `RemediatorLike` are exported from `src/monitoring/DegradationReporter.ts`. They are additive — existing consumers' imports remain valid. The exported `DegradationEvent` shape is unchanged.
+- **CLI / config / endpoint surface:** None changed.
+- **Tests:** 9 new unit tests under the existing file. No changes to existing tests.
+- **Lint behaviour:** The new lint script is not wired into any existing gate (pre-commit / pre-push / CI). It is a documented manual command per §A33: `node scripts/lint-degradation-emit-sites.js`. Adding it to CI is explicitly deferred to F-8.
+
+---
+
+## 7. Rollback cost
+
+**If this turns out wrong in production, what's the back-out?**
+
+- **Revert path:** This is a single-PR shim with no consumer (no Remediator wired anywhere). A `git revert <merge-commit>` followed by a patch release rolls back the entire change with no data migration. The `degradations.json` file (legacy) is untouched.
+- **Stuck-state risk:** If F-8 ships partial Remediator wiring and is reverted, any events accumulated in `<stateDir>/remediation/degradations-queue.jsonl` during a RestartPending window would be orphaned. Mitigation: F-3 has no way to set RestartPending (no caller wires it), so the queue file cannot be populated until F-8 ships. F-8's own rollback story must include a queue-drain step.
+- **Compat risk for downstream consumers:** Code outside this PR that imports `DegradationEvent` continues to compile unchanged. Code that imports the new `NormalizedDegradationEvent` would need to bridge to the legacy type — but no such code exists in this PR or on main today.
+- **Worst-case incident:** A bug in `_normalize` could break the legacy `.report()` path. The integration test for "with no remediator set, legacy alert path runs unchanged" catches the obvious regression; a more exotic bug (e.g. Redactor crash) would be caught by the existing legacy tests because `_normalize` is invoked in every `.report()` call. If it slipped through, the back-out is a one-line revert in the `report()` method to skip the normalize-and-route block.

package/upgrades/side-effects/f4-machine-locks-intent-journal-audit.md

@@ -0,0 +1,117 @@
+# Side-Effects Review — F-4: MachineLock + IntentJournal + audit infrastructure
+
+**Version / slug:** `f4-machine-locks-intent-journal-audit`
+**Date:** `2026-05-13`
+**Author:** `echo`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+Foundation Tier-1 primitives for the Self-Healing Remediator v2 spec. Four new modules under `src/remediation/`:
+
+- `src/remediation/MachineLock.ts` — In-flight HMAC-locked tuple coordination + heartbeat + SIGKILL-grace stale-reclamation.
+- `src/remediation/IntentJournal.ts` — Append-only intent declaration log.
+- `src/remediation/audit/AuditWriter.ts` — Verified audit-projection append path with token + watermark gating.
+- `src/remediation/audit/AuditProjection.ts` — Read view exposing `Map<runbookId, AuditEntry[]>`.
+
+This PR ships the primitives ONLY. No surface (memory-healer, supervisor preflight, delivery-retry, db-corruption) wires into them in this PR. The dispatcher (F-8), runbooks (W-*), and the primary-aggregator lease (A47, Tier-3 scope) consume these 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
+
+- `MachineLock.acquireInFlight()` — **add** — gates whether a tuple is currently being healed; rejects concurrent acquisition until stale (A63) or released.
+- `MachineLock.listInFlight()` — **add** — read primitive; filters out forged lockfiles via HMAC.
+- `AuditWriter.append()` — **add** — gates whether an audit entry is persisted to the projection vs. quarantined to `audit-rejected.jsonl` (token-verify + A42 watermark).
+
+All three decision points operate on cryptographic primitives (HMAC verify, monotonic watermark) provided by the caller. 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?**
+
+- `MachineLock.acquireInFlight()` rejects a second attempt against the same `tupleHash` while the first lock is active. This is the intended contract (A2 lock-bound co-existence) — a second concurrent attempt should be observed as `covered-by-inline` by the caller, not coalesce. Legitimate use is one-attempt-at-a-time per tuple; concurrent attempts are *exactly* what the lock exists to prevent.
+- `AuditWriter` rejects entries whose `auditToken` doesn't verify. By design — forging the token forges authority. Production callers obtain the token from `RemediationContext`, which is issued by the dispatcher at attempt-start.
+- `AuditWriter` rejects entries whose `timestamp < highWatermark` for the same `(subsystem, attemptId)` pair. A legitimate use case for backdated entries doesn't exist in this design — per-attempt audit is forward-monotonic. If a real backdated write becomes a requirement, the design pivots from "drop" to "queue-for-reconciliation"; that's a future amendment, not a bug in this PR.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- **Cross-machine collision on `tupleHash`.** The lock is per-machine. Two machines healing the same tuple are not coordinated by F-4. The cross-process attempt ledger (A7, F-2) and the primary-aggregator lease (A47, Tier-3) are the cross-machine coordinations; F-4 is intentionally scoped to single-machine in-flight.
+- **Forged-lock-with-correct-HMAC.** An attacker with the leaf key can forge a lockfile that passes verification. The mitigation lives in `RemediationKeyVault` (F-1): per-context, per-scope leaf-key derivation from OS-keychain-sealed master + install nonce (A20/A39/A51). F-4 trusts the caller-supplied verifier; key-management is F-1's job.
+- **Slow-but-alive surface vs. crashed surface.** A surface whose heartbeats are landing but whose work is genuinely stuck would NOT be reclaimed — the stale-reclamation logic deliberately requires BOTH grace clauses (A63). The Remediator-side deadline (A4, F-8) is the second line of defense; it's not F-4's concern.
+- **Audit-rejected flood from a compromised peer.** If a forger spams `append()` with bad tokens, `audit-rejected.jsonl` grows unbounded. A27/A49's rate-cap + first-5/last-5 forensic flood-summary handles this; that wraps the write path in F-2's `RemediationGc` rather than living inside `AuditWriter`. F-4 produces the durable forensic record; F-2 trims it.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. These are *primitives*. They expose:
+- A coordination primitive (`MachineLock`) — synchronous semantics, no policy.
+- A durable-witness primitive (`IntentJournal`) — append + read.
+- An authorisation primitive (`AuditWriter` + `AuditProjection`) — verify-and-persist, no semantic interpretation.
+
+Policy (when to acquire, when to declare, when to write) lives in the dispatcher (F-8). Key management lives in `RemediationKeyVault` (F-1). The split is the spec-mandated layering.
+
+No higher-level gate is being shadowed. The closest prior art (`CoordinationProtocol.ts`) operates over `AgentBus` for cross-machine work coordination — a different concern. F-4's spec-level decision (A56) defers reuse of `CoordinationProtocol`'s lease channel to the Tier-3 primary-aggregator PR; this PR introduces no parallel lease file.
+
+---
+
+## 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 produces a signal consumed by an existing smart gate.
+- [x] No — this change has no block/allow surface beyond crypto-verified primitives.
+- [ ] Yes — but the logic is a smart gate with full conversational context.
+- [ ] ⚠️ Yes, with brittle logic — STOP.
+
+The "blocks" in this change are HMAC verification and monotonic counter checks. Both are precise, deterministic primitives — not heuristic detectors. The signal-vs-authority principle is about brittle string-matching / pattern detectors holding blocking power; cryptographic verification is the canonical *correct* place to block. The blocking decisions here (forged token → rejected, stale lock → reclaim) are exactly the kind of authority that *should* be hard-coded.
+
+The smart gate (Remediator dispatcher in F-8) is the consumer that decides *whether to attempt* a heal given the lock state; F-4 only exposes the state.
+
+---
+
+## 5. Interactions
+
+**Does this interact with existing checks, recovery paths, or infrastructure?**
+
+- **Shadowing:** None. No existing audit path or lockfile primitive in `src/remediation/` (this is the first module in that directory). Prior art `src/core/CoordinationProtocol.ts` is for cross-machine work avoidance, not in-flight remediation tuples. Prior art `src/core/WorktreeKeyVault.ts` is a sibling of F-1's `RemediationKeyVault`; both share the keychain-fallback pattern but no decision-point overlap.
+- **Race with adjacent cleanup:** `MachineLock.reclaimStale` renames the lockfile into `orphaned/`. A racing `acquireInFlight` for the same tuple would see the rename happen first (the cache-divergence check stat()s before deciding); the post-reclaim acquire writes a fresh file. If the rename and the next acquire interleave on different machines, the per-machine state-dir scoping prevents cross-host interference. If they interleave on the SAME process via concurrent in-process callers, the second caller's `readVerifiedLock` returns `undefined` (cache invalidated, file just renamed) and falls through to the new-acquire path — both end up writing, the second `fs.renameSync` (atomicWriteLock's rename) is the final state. The atomic-rename guarantees one envelope ends up authoritative; the second caller's `attemptId` may "win" silently. Single-process concurrent acquisition of the same tuple is a contract violation, not a supported use case — the dispatcher serialises by tuple.
+- **Double-fire:** `release()` is idempotent (uses a local `released` flag + ENOENT-tolerant unlink). `heartbeat()` throws after release. `append()` is idempotent only in the sense that duplicate entries land twice; the in-memory tail cap absorbs the bloat. The dispatcher is responsible for at-most-once `append` per state-transition.
+
+---
+
+## 6. External surfaces
+
+**Does this change anything visible to other agents, other users, other systems?**
+
+- New directories on disk: `~/.instar/machine-locks/in-flight/`, `~/.instar/machine-locks/orphaned/`, `<stateDir>/remediation/`. All created lazily by the modules at first use.
+- New file types: `<tupleHash>.lock`, `intent-journal-<machineId>.jsonl`, `audit-projection-<machineId>.jsonl`, `audit-rejected.jsonl`.
+- Per A14, the `audit-projection-*.jsonl` and `intent-journal-*.jsonl` paths are per-machine, not git-synced, not backed up. F-7 (PostUpdateMigrator) adds the gitignore entries and the backup-exclusion config; this PR doesn't ship that wiring — the files simply won't exist yet on any installation that doesn't enable the Remediator surface.
+- No HTTP routes, no Telegram surfaces, no dashboard tabs, no config-flip entries.
+
+---
+
+## 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 — `MachineLock`, `IntentJournal`, `AuditWriter`, `AuditProjection` are new symbols not yet imported anywhere in `src/`. A `git revert` removes them with zero state-migration cost. The on-disk files (lock, journal, audit-projection) are not created until first call from a consumer; no installation that doesn't add F-1/F-8 will ever materialise them.
+
+If a future consumer-PR exposes a bug in one of these primitives, the back-out path is "revert the consumer PR" — these primitives don't run on their own.
+
+---
+
+## 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 infrastructure with no live consumers in this PR.