instar 1.3.201 → 1.3.202

package/upgrades/side-effects/evo003-revertdetector-git-arg.md

@@ -0,0 +1,106 @@
+# Side-Effects Review — RevertDetector invalid git arg (EVO-003)
+
+**Version / slug:** `evo003-revertdetector-git-arg`
+**Date:** `2026-06-02`
+**Author:** `Echo (Instar Agent)`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+`src/monitoring/RevertDetector.ts` builds a `git log` argv to find `Revert "..."` commits. That argv carried `--regexp-ignore-case=false`, which git rejects (`fatal: unrecognized argument` — git's `--grep` case flags take no `=value` form). The call therefore threw on every tick, was swallowed by the existing try/catch, and `scanForReverts` returned 0 — making revert detection a silent no-op on every install. The change deletes that one element (case-sensitive is git's `--grep` default, which is what we want) and adds a NOTE comment so it can't be reintroduced. `tests/unit/RevertDetector.test.ts` gains two regression tests: an argv-shape assertion (injected arg-recording git) and a real-git end-to-end test (real temp repo + real `git revert`). Files touched: `src/monitoring/RevertDetector.ts`, `tests/unit/RevertDetector.test.ts`.
+
+## Decision-point inventory
+
+This change touches no block/allow decision point. RevertDetector is an observer that opens forensic FailureLedger records; it never gates a message, job, or session.
+
+- `RevertDetector.scanForReverts git argv` — modify — drop the invalid `--regexp-ignore-case=false` element so the scan command is valid git.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+No block/allow surface — over-block not applicable. The only behavioral change is that the scan command now executes successfully instead of throwing. Match semantics are unchanged in intent: `--grep=^Revert` already matched case-sensitively (git's default), which is exactly what the broken `=false` flag was *trying* to express. So no commit that should have matched is now excluded, and none that shouldn't is now included.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+No block/allow surface — under-block not applicable. Scope note: detection keys on the conventional `Revert "<subject>"` message that `git revert` produces by default. A hand-crafted revert with a non-standard subject still won't be detected — but that is pre-existing behavior, unchanged by this fix and out of scope for EVO-003.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. RevertDetector is correctly a low-level detector that emits forensic records into the FailureLedger (a signal), not an authority. This change does not move it across that line — it only repairs the git invocation so the detector can run at all. No higher-level gate needs to consume this differently; the FailureLedger remains the consumer.
+
+---
+
+## 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.
+
+RevertDetector produces forensic FailureLedger entries (a signal). It holds no blocking authority. The fix is a pure correction of a malformed external-command argument; it neither adds nor removes any decision authority.
+
+---
+
+## 5. Interactions
+
+**Does this interact with existing checks, recovery paths, or infrastructure?**
+
+- **Shadowing:** None. The scan runs on RevertDetector's own tick and writes only to the FailureLedger. Before the fix it always threw → returned 0; after, it returns the real count. Nothing was relying on the always-throws behavior.
+- **Double-fire:** The forensic entry is opened via `resolveByCommit`/ledger logic that already de-dupes by commit. Turning detection on does not change that path; it just lets it receive real input for the first time. A given revert commit yields one record.
+- **Races:** The scan is lease-gated (`isLeaseHolder()` guard, unchanged), so only the awake machine scans. No new shared state is introduced.
+- **Feedback loops:** RevertDetector feeds the FailureLedger, which the failure-learning loop reads. This change makes that input non-empty for revert events for the first time. The volume is bounded by the scan window (recent commits only) and de-duped per commit, so no runaway loop is created.
+
+---
+
+## 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? Only positively: revert detection begins working fleet-wide on update — previously-silent reverts will now produce forensic FailureLedger records. No user-facing message or topic is generated by RevertDetector itself.
+- External systems? No. The change *reduces* the git command to a valid form; it issues no new external calls.
+- Persistent state? FailureLedger will, for the first time, gain `source: 'revert'` forensic entries on installs that have revert commits in their scan window. These are forensic (resolved) records, not open failures — they do not trigger escalation.
+- Timing/runtime: No new timers. Same tick cadence, same lease gate.
+
+---
+
+## 7. Rollback cost
+
+**If this turns out wrong in production, what's the back-out?**
+
+Pure code change — revert the commit and ship a patch. No data migration. The only persistent residue is new `source: 'revert'` forensic entries in the FailureLedger; these are benign resolved records and need no cleanup on rollback. No agent state repair, no user-visible regression during the rollback window.
+
+---
+
+## Conclusion
+
+This review found no block/allow surface and no risky interaction. The change is a one-line deletion of an invalid git argument that has silently disabled revert detection on every install, plus two regression tests (argv-shape + real-git end-to-end) that pin the fix. The net effect is that an existing, already-wired observer starts producing the forensic records it was always meant to produce. Clear to ship as a Tier-1 change.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** not required (Tier-1)
+**Independent read of the artifact: concur**
+
+---
+
+## Evidence pointers
+
+- `tests/unit/RevertDetector.test.ts` — 11/11 pass, including the two EVO-003 regression tests (argv-shape + real-git end-to-end).
+- `npx tsc --noEmit` — clean.
+- `pnpm lint` — clean (includes lint-no-direct-destructive: the real-git test uses `SafeGitExecutor`/`SafeFsExecutor`, not raw exec/rm).
+- `pnpm build` — clean (dist compiles).
+- Bug confirmation: `JKHeadley/main:src/monitoring/RevertDetector.ts:143` carries `--regexp-ignore-case=false`; git 2.39.5 rejects it with `fatal: unrecognized argument`.

package/upgrades/side-effects/git-less-lease-convergence.md

@@ -0,0 +1,31 @@
+# Side-effects review — git-less same-epoch lease convergence (#680 Problem A v3)
+
+**Spec:** `docs/specs/MULTI-MACHINE-LEASE-ROBUSTNESS-SPEC.md` §Problem A (converged 3 rounds, approved). The design failed verification twice (R1 zombie-holder, R2 headless-loser) before the v3 mechanism — this is why it shipped spec-first.
+
+**Change:** resolve a git-less `LocalLeaseStore` same-epoch leapfrog split-brain to a single holder. When the active pull (#668) observes a peer holding the SAME epoch as our self-issued lease, a deterministic tie-break (lower `machineId` wins) drives a one-shot resolution: the LOSER relinquishes, the WINNER advances once to N+1, the loser adopts N+1 via the existing strict-`>` tunnel fold.
+
+## What it touches (3 files, all on the lease path)
+- **`LocalLeaseStore.forceLocalExpiry()`** (NEW) — expires the persisted self-lease in place, KEEPING the committed epoch as the CAS/replay floor (clearing to 0 would let a replayed stale lease win). No-op if no local lease.
+- **`LeaseCoordinator`** — NEW `relinquish()` (clears `selfIssued` + calls `store.forceLocalExpiry?.()`), NEW `advanceEpochForContestedWin()` (one-time `buildAcquisition`→N+1 via the same casWrite/broadcast/sign path as a normal acquire; bypasses `canAcquire` deliberately — it IS the tie-resolution), + `forceLocalExpiry?()` added as an OPTIONAL method on the `LeaseStore` interface (GitLeaseStore does not implement it → no-op there).
+- **`MultiMachineCoordinator`** — NEW `contestedEpisode` state field + NEW `resolveContestedSplitBrain()` called from `tickLeasePull` after the existing detect-only `surfacePullDiscoveredSplitBrain()`. Tie-break → relinquish (loser) / advance (winner), latched one-shot per episode, K-cycle bounded escalation.
+
+## Side effects & blast radius
+- **Behavior change is confined to a genuine same-epoch contested tie** (two machines both holding epoch N over a git-less store — the post-teardown split-brain). The clean single-holder path, the partition path (checkForUnresolvableSplit), and the git-substrate path (GitLeaseStore) are UNTOUCHED. `forceLocalExpiry` is optional on the interface, so only the git-less store gains the behavior.
+- **The tie-break is deterministic + total-ordered** (lower machineId wins), so all machines compute the SAME winner with no coordination — exactly one relinquishes, exactly one advances. Transitive, so it generalizes to 3+ machines (tested-direction noted in the spec).
+- **One-shot latch per episode** (keyed on the epoch-independent {self,peer} pair) means the relinquish/advance fire ONCE, not every ~5s pull tick — a per-tick action would re-introduce the leapfrog this fixes. The episode clears on the falling edge (tie resolved).
+- **Winner-advance bypasses `canAcquire`** (direct `buildAcquisition`+casWrite). This is intentional: the winner must reach N+1 even while the loser's relinquished-but-floor-intact lease is observed. casWrite still enforces strict epoch advance (N+1 > committed N), so it cannot lower the epoch or forge.
+- **Relinquish → standby → read-only** is the path implicated in the #668 crash incident. #673 (on main) made the standby read-only write non-fatal; this change relies on that and on Problem B (closeAllSqlite) for a clean exit. Per the spec sequencing, B lands first.
+- **Adoption is via the EXISTING strict-`>` fold** — no new adoption write; the loser's `effectiveView()` folds the winner's N+1 (N+1 > N) and `currentHolder()` returns the winner. Verified empirically (the headless-loser guard).
+- **Escalation is observe-only**: a persistently-contested episode emits ONE deduped `splitBrainEscalation` event with a deterministic `demote <loser>` recommendation. It does not auto-act; a consumer routes it to Attention. Distinct from the partition escalation.
+- **No migration** — pure in-process lease logic; no config/route/schema change; reaches existing agents on normal update.
+
+## What could go wrong (and why it won't)
+- **Both advance (leapfrog)?** No — the tie-break gates advance to the winner only; the loser relinquishes. Both latched per-episode.
+- **Loser headless (R2's catch)?** No — the winner advancing to N+1 makes the loser's strict-`>` fold adopt it; `currentHolder()===winner`. Tested.
+- **Stale-lease replay after relinquish?** No — `forceLocalExpiry` keeps the epoch floor; a below-floor lease is rejected by CAS/acceptTunnelLease.
+- **Per-tick churn?** No — the one-shot latch.
+
+## Tests (all green; 9 new + 68 existing lease/MMC regressions)
+- Unit `tests/unit/LeaseCoordinator-convergence.test.ts` (6) — the EMPIRICAL convergence proof: two coordinators both at epoch N converge to a single holder at N+1, with the headless-loser guard (loser's `currentHolder()===winner`), order-independence, winner-advance-alone-adopts, relinquish/forceLocalExpiry primitives + epoch-floor retention.
+- Integration `tests/integration/lease-contested-resolution.test.ts` (3) — the orchestration on the real pull loop: WINNER advances once + latch (epoch stops climbing), LOSER relinquishes (standby), bounded K-cycle escalation (one deduped `demote <loser>`).
+- 68 existing lease/MMC tests unchanged-green; `npm run lint` + `tsc --noEmit` clean.

package/upgrades/side-effects/sqlite-close-on-exit-registry.md

@@ -0,0 +1,27 @@
+# Side-effects review — SQLite close-on-exit registry (#680 Problem B)
+
+**Spec:** `docs/specs/MULTI-MACHINE-LEASE-ROBUSTNESS-SPEC.md` §Problem B (converged 3 rounds, approved).
+**Change:** a central `SqliteRegistry` (`registerSqliteHandle` / `closeAllSqlite` / `__resetSqliteRegistryForTests`); all 15 long-lived better-sqlite3 stores register their handle after open; `server.ts` closes every registered handle LAST on both exit paths (graceful shutdown + uncaughtException), replacing the hand-maintained 2-store close-list.
+
+## What it touches
+- **New module** `src/core/SqliteRegistry.ts` — pure, process-global singleton. No I/O, no deps.
+- **15 store constructors** gain one `registerSqliteHandle(() => this.db?.close())` call after the db is open (StopGateDb, FeatureRegistry, PreferenceStore, SpawnLedger, RegistryStore, TokenLedger, CorrectionLedger, FailureLedger, FeatureMetricsLedger, FrameworkIssueLedger, TopicMemory, SemanticMemory, MessageProcessingLedger, pending-relay-store, iMessage NativeBackend). StopGateDb + PreferenceStore + SpawnLedger also unregister + (StopGateDb) gained a `_closed` idempotency guard.
+- **`src/commands/server.ts`** — `shutdown()` gained a re-entrancy guard and now calls `closeAllSqlite()` after `server.stop()` (was: explicit `topicMemory?.close()` + `semanticMemory?.close()` before `server.stop()`); the `uncaughtException` handler calls `closeAllSqlite()`.
+
+## Side effects & blast radius
+- **Behavior change at exit only.** No runtime/request-path behavior changes — registration is a no-op at steady state; the only new work happens during process teardown.
+- **Ordering moved:** SQLite now closes AFTER `server.stop()` (writers stopped first) instead of before. This is intentional and safer — no route can touch a closed handle because the HTTP server is already stopped. The sidecar flush (`sharedStateLedger.shutdown()`) still runs before the close so no write is lost.
+- **Double-close safety:** better-sqlite3 `.close()` throws on an already-closed handle. The registry guards this three ways — unregister-before-explicit-close, an at-most-once closed-set, and a per-handle try/catch in `closeAllSqlite()` — so a store explicitly closed at runtime and then drained at exit cannot crash teardown.
+- **Reopen safety:** TopicMemory + SemanticMemory reopen their handle on corruption recovery. The registered closeFn reads `this.db` live (not a captured ref), so the current handle is always the one closed.
+- **Registration leak risk:** registration is fire-and-forget for most stores. These 15 are process-lifetime singletons (registered once), so the registry does not grow unboundedly. A store instantiated many times would accumulate entries — not the case for any of the 15.
+- **Test isolation:** `__resetSqliteRegistryForTests()` clears BOTH the handle list and the closed-set (a half-reset would leak an "already closed" verdict between tests).
+
+## What could go wrong (and why it won't break prod)
+- If a store's closeFn threw, the old code would abort teardown — now each is wrapped best-effort, so one bad close cannot block the others (the whole point).
+- The re-entrancy guard on `shutdown()` means a SIGINT+SIGTERM race (or restartDetected racing a signal) runs the resume-UUID save + flush once, not twice.
+- No migration needed — ships in code, reaches existing agents on normal update. No config/route/schema change.
+
+## Tests (3 tiers, all green)
+- Unit `tests/unit/SqliteRegistry.test.ts` (6) — close-all, throwing-close-isolation, unregister, at-most-once, reset-clears-both.
+- Wiring `tests/unit/SqliteRegistry-wiring.test.ts` (5) — static allowlist completeness (every long-lived store registers; every open-callsite accounted) + functional registration-fires.
+- Lifecycle `tests/integration/sqlite-close-on-exit.test.ts` (7) — real better-sqlite3 handles actually close (`.open === false`); StopGateDb closed without throw; double-close safe; server.ts ordering (closeAllSqlite after server.stop; uncaughtException closes all; old 2-store list gone).

package/upgrades/side-effects/time-awareness-component4-reporting-nudge.md

@@ -0,0 +1,20 @@
+# Side-effects review — Time Awareness Component 4 (signal-only reporting nudge)
+
+**Spec:** `docs/specs/ROBUST-SESSION-TIME-AWARENESS-SPEC.md` §Component 4 (converged + approved, merged as #681; Component 4 was deferred to v1.1, tracked #682 — now built). **Tracks:** #682.
+
+**Change:** one new check (signal-only) appended to the pre-messaging `convergence-check.sh` gate (`src/templates/scripts/convergence-check.sh`). If an outbound message asserts the **session/run is done/over** (or "winding down" / "wrapping up the session/run") while a **live autonomous record** (`.instar/autonomous/*.local.md`, `active: true`) still has **>10% of its time-box remaining**, it emits a one-line SIGNAL to `logs/time-awareness-signals.jsonl` + stderr. This guards the exact wind-down-early incident class that started the time-tracking work.
+
+## What it touches
+- `src/templates/scripts/convergence-check.sh` ONLY (the pre-messaging quality gate, run by `grounding-before-messaging.sh`). One appended block + nothing else changed.
+- Reaches existing agents automatically: convergence-check.sh is **always-overwritten on migration** (`PostUpdateMigrator` line ~4122, "Convergence check — always overwrite") + installed by `init`. No new migration code needed. New agents get it via the same install path.
+
+## Side effects & blast radius (deliberately minimal — P2 Signal vs Authority)
+- **SIGNAL-ONLY: it NEVER blocks or rewrites the message.** The block does NOT touch `ISSUE_COUNT` or the exit code — the existing checks 1-8 and the gate's exit logic are untouched. A premature-completion assertion still SENDS; the operator just gets a side-channel signal. (Verified: exit 0 in all test scenarios, including when the signal fires.)
+- **Never quotes the agent's phrase.** The signal carries the computed fact (`≈NN% of the time-box remains`) only — never the "done/over" wording — so it can't be re-read as self-confirming evidence the run is finished (the adversarial-round-2 sink requirement).
+- **Signal sink = operator log + stderr, never the agent's injected context.** On exit 0 the grounding hook does not surface convergence-check output to the agent, so the signal does not pollute context. The JSONL log is the durable operator record.
+- **Targeted regex** (session/run/sprint-level completion + winding-down/wrapping-up-the-session) — chosen to avoid false-positives on subtask reports ("this PR's tasks are complete"). Even a false positive is low-cost (one log line; never blocks). Only fires when an `active: true` record with >10% remaining exists, so non-autonomous messaging is never touched.
+- **Portable date math** via the python3 already used by the script's URL-provenance check (no new dependency). Reads the record directly — no server call (the convergence-check host is pure-bash by design).
+- **Inline fallback NOT modified:** `getConvergenceCheckInline()` is a degraded "template-missing" safety net already divergent from the template (it lacks check 8 too); newer checks live in the template only by established pattern, and there is no template==inline drift test. The template is the canonical always-used source.
+
+## Tests (golden, 5; all green; 66 convergence-check tests total green — no regression)
+`tests/unit/convergence-check-time-awareness.test.ts` — runs the REAL template script: (1) done-assertion + >10% remaining → SIGNAL in log + stderr, computed %, no phrase-quote, exit 0 (not blocked); (2) no assertion → silent; (3) <10% remaining (genuine near-end wrap-up) → silent; (4) record not active → silent; (5) no record at all → silent. `bash -n` + `tsc` clean.