instar 1.3.154 → 1.3.156

package/upgrades/1.3.155.md

@@ -0,0 +1,26 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+**A stored preference that gets violated now becomes a learning signal (dark).** This extends the Correction & Preference Learning Sentinel. A learned preference — for example, "don't defer work to a fresh session" or "never ask the user to edit files" — can now carry an optional self-violation pattern. When the agent emits an outbound message that contradicts such a preference, that is recorded as a self-violation in the correction ledger, which reinforces the preference's recurrence so it surfaces more prominently the next session.
+
+It is signal-only: the detector observes the finalized outbound message and records — it can never block, delay, or rewrite a message. It is fail-open (any detector error silently no-ops and delivery is unaffected) and dark (gated behind both the master correction-learning flag and a new self-violation sub-flag). A preference without a self-violation pattern is never checked, so existing preference files are fully backward compatible.
+
+## What to Tell Your User
+
+The correction-learning system can now notice when the agent's own outgoing message contradicts a preference it has already learned about how you like to work, and quietly use that as a signal to remember the preference more strongly next time. It only ever observes and records — it never blocks, delays, or changes a message — and it stays off until explicitly turned on.
+
+## Summary of New Capabilities
+
+- New `src/monitoring/SelfViolationDetector.ts` — pure, deterministic `detectSelfViolation`; precision-biased (a lone weak keyword never fires), never throws.
+- `PreferencesManager` preference records gain an optional `violationPattern` (regex or keyword grammar); fully backward compatible.
+- Observe-only outbound hook in `checkOutboundMessage` records self-violations to the `CorrectionLedger`; structurally independent of the tone-gate verdict and of the message itself.
+- New `monitoring.correctionLearning.selfViolationSignal` config flag (default false).
+
+## Evidence
+
+- `SelfViolationDetector` unit (17), self-violation wiring-integrity (5, asserts the outbound message passes through byte-for-byte unchanged and the detector fail-opens), integration (5), and E2E lifecycle (3) — all passed.
+- `npm run build` / `npm run lint` / `docs-coverage` clean.

package/upgrades/1.3.156.md

@@ -0,0 +1,24 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What to Tell Your User
+
+If you set an overnight restart window, your agent no longer sits on a downloaded update all day when nothing is going on. It updates right away while idle, and still waits for the window whenever you actually have work in progress — so updates land sooner without ever interrupting you.
+
+## Summary of New Capabilities
+
+- The restart-window gate now consults a pure, side-effect-free session probe before deferring: idle (no active sessions) restarts immediately outside the window; active sessions defer to the window as before. The deferral record now also names the blocking sessions instead of leaving them blank.
+
+## Evidence
+
+- Unit (UpdateGate): the new idle probe returns active session names, ignores idle background jobs, and — critically — does NOT start the deferral clock or set warning state (proven by a purity test); its classification is asserted identical to the restart gate so the two can never drift.
+- Unit (restart-window): outside the window with an active session still defers; outside the window while idle restarts immediately. Both decision-boundary sides covered.
+- The existing restart gate logic is byte-for-byte unchanged (extracted into a shared classifier); the cascade-dampener integration tests stay green.
+
+## What Changed — Idle agents apply update-restarts immediately instead of waiting for the restart window
+
+Agents can set a restart window (e.g. 02:00–05:00) so update-restarts only happen overnight and never interrupt active work. But the window was applied unconditionally: even when the agent was completely idle — no active session, nothing to protect — a downloaded update would sit unapplied for hours until the window opened. The agent ran a stale version all day for no reason.
+
+Now the window only holds a restart when there is active work to protect. If the agent is idle when an update lands outside the window, it restarts right away (an idle restart is invisible — it is exactly what already happens for idle agents inside the window). The moment any session is active, the window is honored exactly as before and the restart waits.

package/upgrades/side-effects/correction-self-violation-signal.md

@@ -0,0 +1,133 @@
+# Side-Effects Review — Correction & Preference Learning: Self-Violation Signal
+
+**Version / slug:** `correction-self-violation-signal`
+**Date:** `2026-05-31`
+**Author:** `echo`
+**Second-pass reviewer:** `not required — observe-only + dark by default; the detector holds no blocking authority and cannot alter/delay/block any outbound message`
+
+## Summary of the change
+
+Extends the shipped Correction & Preference Learning Sentinel so a stored-but-violated
+preference becomes a learning signal instead of evaporating. A learned preference can
+carry an OPTIONAL `violationPattern` (regex or keyword set). When the agent sends an
+outbound message that contradicts that pattern, the contradiction is recorded as a
+self-violation in the `CorrectionLedger` (a recurrence-reinforcing `user-preference`
+occurrence keyed on the violated lesson), so the preference's salience grows for the
+next session-start injection.
+
+Files: new `src/monitoring/SelfViolationDetector.ts` (pure `detectSelfViolation`);
+`src/core/PreferencesManager.ts` (+optional `violationPattern` on `PreferenceEntry`
+and `RecordPreferencePayload`, persisted/round-tripped, upsert-preserving); the
+outbound seam in `src/server/routes.ts` (a new OBSERVE-ONLY `observeSelfViolation`
+fire-and-forget branch inside `checkOutboundMessage`, structurally independent of the
+tone-gate verdict); config `monitoring.correctionLearning.selfViolationSignal`
+(types.ts + ConfigDefaults.ts); Agent-Awareness (templates.ts) + Migration-Parity
+backfill (PostUpdateMigrator migrateClaudeMd).
+
+## Decision-point inventory
+
+- `detectSelfViolation(text, prefs)` (new) — add — pure, deterministic, returns the
+  list of violated preferences. No authority; precision-biased (lone weak match never
+  fires); never throws.
+- `observeSelfViolation` seam branch (new) — add — records a matched violation to the
+  ledger + an audit line. Fire-and-forget VOID; cannot influence delivery.
+- `PreferenceEntry.violationPattern` (new optional field) — add — absent ≡ never
+  checked (back-compat).
+- Tone-gate / `checkOutboundMessage` block-decision — UNCHANGED — the observe branch
+  runs before the gate-availability early-return and never feeds the gate or the
+  return value.
+
+---
+
+## 1. Over-block
+
+Not applicable. The feature has NO block/allow surface. The observe branch runs as a
+fire-and-forget `void observeSelfViolation(...).catch(...)` that is structurally
+incapable of returning a block verdict, throwing into the delivery frame, or mutating
+the message. The wiring-integrity + E2E tests assert the message is delivered
+byte-for-byte unchanged whether or not a violation is detected.
+
+## 2. Under-block
+
+There is nothing to under-block — the feature never blocks. The "miss" direction
+(a real self-violation going unrecorded) is the deliberately-chosen safe direction:
+precision over recall. A lone/weak keyword never fires, an unparseable pattern is a
+no-check, and a preference without a `violationPattern` is skipped. A false
+self-violation that nags is the bad direction, so the matcher is conservative. A
+missed recording costs only a slightly weaker recurrence signal next session.
+
+## 3. Level-of-abstraction fit
+
+Correct. The detector is a pure, exhaustively-tested function (mirrors the
+deterministic `scrubSecrets` / Layer-0 classifier discipline of the same sentinel).
+The recording reuses the shipped `CorrectionLedger.record()` dedupe-upsert and its
+`toApiView()` raw-text-stripping discipline; the occurrence is a `user-preference`
+record at the code-determined `LEARNING_DETERMINISTIC_THRESHOLD` so it feeds the
+existing 3-pronged recurrence gate exactly like any other distilled correction. No
+new persistence layer, no new gate, no new authority.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] Yes — this change produces a SIGNAL (a ledger occurrence + an audit line) and
+  holds ZERO authority over any message. The user's explicit hard rule ("we've been
+  bitten by guards that block messages having too much power") is honored structurally:
+  the observe call is a separate VOID branch that runs regardless of the
+  `MessagingToneGate`'s verdict and never influences it. The single authority for
+  outbound delivery remains the `MessagingToneGate` (rules B1–B17), entirely unchanged.
+
+## 5. Interactions
+
+- **Shadowing:** none. The observe branch is additive at the top of
+  `checkOutboundMessage`; it does not read or alter the signals, the gate result, or
+  the 422 path. With the tone gate null, the observe branch still runs (it precedes
+  the gate-availability early-return) and the message still passes through.
+- **Double-fire:** the ledger dedupe-upserts on `kind:normalizedLearningHash`, so
+  repeated self-violations of the same preference collapse to ONE record with an
+  incrementing `occurrenceCount` (asserted by the integration test) — never a pile.
+- **Races:** the observe call is fire-and-forget and lazy-imports its modules; the
+  ledger is the shipped WAL SQLite store (single-writer-safe, fail-open on any error).
+  Two concurrent sends recording the same preference are both safely upserted.
+- **Feedback loops:** none. The detector reads `.instar/preferences.json` (written by
+  `recordPreference`) and writes the ledger; it never writes preferences, so it cannot
+  amplify its own pattern. The CorrectionAnalyzer that consumes the ledger is
+  off-hot-path (weekly cron) and only ROUTES via the existing by-construction
+  authority-bounded driver.
+
+## 6. External surfaces
+
+- **Other agents / install base:** pure additive source + a default-OFF config
+  sub-flag (auto-applied via ConfigDefaults; code reads `cl?.selfViolationSignal !==
+  true` so an agent whose config lacks the field behaves identically — OFF). The
+  optional `violationPattern` is fully back-compatible: shipped `.instar/preferences.json`
+  files have no such field and are simply never self-violation-checked (unit-tested
+  with a legacy-shaped file). Agent-Awareness + Migration-Parity are handled
+  (templates.ts bullet for new agents; idempotent content-sniffed migrateClaudeMd
+  backfill for existing agents).
+- **External systems:** none. The detector is local + deterministic; no LLM call, no
+  network. (Distinct from the capture/distill loop, which is a separate, already-shipped
+  surface.)
+- **Persistent state:** existing `correction-ledger.db` only (one extra occurrence
+  row per matched violation, bounded by the shipped per-key occurrence cap). Plus a
+  best-effort `[self-violation]` stderr audit line. No new files.
+- **Timing:** none. No timers; the observe call is one bounded synchronous detect plus
+  one ledger write, off the delivery path.
+
+## 7. Rollback cost
+
+Pure additive code + a default-off config sub-flag. Revert the commits → the detector,
+the seam branch, the schema field, the config flag, and the awareness text disappear;
+nothing else changes. Any ledger occurrences already recorded are inert and indexed
+exactly like every other correction record (no schema change to the ledger). No
+migration, no state repair, no user-visible behavior change (it never acted on a
+message).
+
+## Conclusion
+
+This review confirmed the change is observe-only: a tested, precision-biased,
+never-throwing decision function plus a fire-and-forget recording branch that is
+structurally incapable of blocking, delaying, or altering any outbound message. It
+ships dark behind both `correctionLearning.enabled` and the new `selfViolationSignal`
+sub-flag, is fully back-compatible with existing preference files, and reuses the
+shipped ledger's privacy + dedupe discipline. Clear to ship.

package/upgrades/side-effects/restart-when-idle.md

@@ -0,0 +1,51 @@
+# Side-effects — Restart-when-idle (restart-window idle bypass)
+
+## 1. What files/state does this touch at runtime?
+`AutoUpdater.gatedRestart()` and `UpdateGate`. No new files, no config keys, no schema, no
+persisted state added. The deferral record written on an *active* deferral now carries the actual
+blocking session names (previously `[]`) — same record, richer field.
+
+## 2. Does it change any functional behavior?
+- **Agents with NO restart window configured:** none. `isInRestartWindow()` returns true when no
+  window is set, so the window gate is never entered.
+- **Agents WITH a restart window, while ACTIVE (a healthy session running):** none — still defers
+  to the window exactly as before.
+- **Agents WITH a restart window, while IDLE (no active sessions):** an update that lands outside
+  the window now restarts immediately instead of waiting hours for the window. The restart is the
+  same idle silent-restart the in-window path already performs.
+
+## 3. What happens on failure / weird config?
+The probe is best-effort and read-only. If no `sessionManager` is wired, the window gate treats it
+as idle and falls through to the existing "no session manager → silent restart" path one block
+down (consistent semantics). `getBlockingSessions` returns `[]` for zero sessions. No throw path
+added.
+
+## 4. Migration parity — do existing agents get it?
+Yes, via the normal release — it is a **code-only** change compiled into `dist`. No
+`PostUpdateMigrator` pass is needed because no agent-installed file (hook/skill/config/CLAUDE.md
+template) changes. Existing agents pick it up when they update to this version.
+
+## 5. Could it spam / flood / burn resources?
+No. It adds one in-memory session classification (a list walk already done by `canRestart`) per
+restart attempt. No new timers, no new I/O, no new network calls. If anything it *reduces* work by
+skipping the deferral-timer scheduling on idle boxes.
+
+## 6. Rollback / off-switch?
+Revert the PR. The behavior is always-on (no flag) — idle restarts are inherently safe (they are
+what idle agents already get inside the window), so the change is strictly a latency improvement.
+A user who wants strict window-only behavior even while idle would need the reverted code; this is
+documented as a deliberate trade-off, not an oversight.
+
+## 7. Concurrency / ordering?
+None new. The idle probe (`getBlockingSessions`) is pure and side-effect-free — crucially it does
+NOT start or continue `UpdateGate`'s deferral clock or set warning flags (a dedicated purity unit
+test guards this). The real restart guard remains the `canRestart()` call at the session gate,
+which runs after the window gate; a session that becomes active between the two checks is caught
+there and deferred.
+
+## Blast radius
+Small + additive. One conditional at the window gate in `AutoUpdater.ts` + one pure method
+(`getBlockingSessions`) plus a behavior-preserving extraction (`classifyRunningSessions`) in
+`UpdateGate.ts`. The existing restart gate (`canRestart`) is byte-for-byte unchanged and its
+regression tests (cascade-dampener) stay green. Only affects agents that have a restart window
+configured AND are idle when an update lands outside it.