instar 1.3.31 → 1.3.33

package/upgrades/1.3.33.md

@@ -0,0 +1,36 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+**Notify-on-stop, Layer B.** When the Unjustified Stop Gate judges a stop unjustified-but-unblockable (`continue` in shadow mode — the gate wants to keep going but shadow can't block, so the session silently stalls) or ambiguous (`escalate`), and the stopping session is **unattended** (an autonomous run), the user now gets one coalesced plain-English heads-up ("a background run stopped mid-task — want me to pick it back up?"). Previously the gate saw these and could do nothing the user could observe.
+
+Tightly bounded to stay near-silent: only those two genuinely-stuck decision classes, only unattended sessions, at most once per session per 30 minutes, coalesced onto the single system (lifeline) topic. Routine turn-ends, blocked-and-continued stops, and transient fail-opens stay silent. Default ON (Justin's explicit "tell me why it stopped"); disable with `monitoring.notifyOnStop.enabled=false`. Pairs with Layer A (autonomous-run terminal-exit notices).
+
+**Feedback Factory Migration — dry-run/compare machinery.** Next increment of the migration (spec `docs/specs/feedback-factory-migration.md`, approved). Ships the safety harness that lets the ported Instar processor run safely against Portal's live database during the cutover — without ever being able to change it. Three new internal modules under `src/feedback-factory/`:
+
+- **`store/ReadOnlyShadowStore.ts`** — a read-only wrapper around the feedback data layer. Reads pass through; every write throws. The structural guarantee that the dry-run can never mutate the curated bug history (Portal stays the sole writer through cutover).
+- **`processor/parity.ts`** — the comparator for the three order-independent invariants the migration spec pins: per-cluster fingerprint, terminal status, and recurrence count. Recomputing fingerprints over the live clusters and diffing them is the highest-signal check — it catches any Python↔TypeScript divergence on real production titles.
+- **`dryrun/dryRunCompare.ts`** — the runner: reads the clusters, compares the invariants, writes a JSONL audit trail, and returns a verdict. `divergent === true` is the signal that blocks cutover.
+
+Still internal building blocks — not yet wired into any route or job, so no behavioral change. The live database adapter behind the read-only seam lands once Dawn hands off the read credentials.
+
+## What to Tell Your User
+
+- If one of my background runs stalls mid-task when it shouldn't have, you now get a single heads-up — even when the watchdog can't restart it itself.
+- On the feedback system: this is the safety harness for moving it in-house. It lets me run my new version *alongside* Dawn's, reading the same live data, and prove they make identical decisions — while making it physically impossible for my version to touch the real records. The comparison is built to ignore harmless ordering differences and only flag *real* disagreements.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Unjustified mid-task stalls on unattended sessions surface one coalesced Telegram | Automatic (default on); `monitoring.notifyOnStop.enabled=false` to disable |
+| Read-only shadow store (write-guard) | Internal `src/feedback-factory/store/ReadOnlyShadowStore.ts` — wraps any `FeedbackStore`; writes throw |
+| Parity invariant comparator | Internal `src/feedback-factory/processor/parity.ts` — `compareInvariants()` |
+| Dry-run/compare runner | Internal `src/feedback-factory/dryrun/dryRunCompare.ts` — `runDryRunCompare(source, opts)` → verdict + JSONL |
+
+## Evidence
+
+- **Notify-on-stop Layer B:** `src/monitoring/StopNotifier.ts` (decision matrix + attended-gate + dedup); wired via `src/server/routes.ts`, `src/commands/server.ts`, `src/server/AgentServer.ts`. Config: `monitoring.notifyOnStop` in `src/core/types.ts`. Tests: `tests/unit/StopNotifier.test.ts` (21) + `tests/unit/stop-notifier-wiring.test.ts` (6). Spec: `docs/specs/NOTIFY-ON-STOP-SPEC.md`. Side-effects: `upgrades/side-effects/notify-on-stop-layer-b.md`.
+- **Feedback-factory dry-run:** 21 new unit tests across the three modules, all green; full feedback-factory unit dir 128/128 green; `tsc --noEmit` clean. Both-sides-of-boundary: every read delegates AND every write throws (with the offending method name); the comparator asserts no-divergence on matching data plus a real divergence for each invariant; the runner covers the clean path, a divergent corpus, the JSONL audit trail, return-only mode, and the never-mutates-the-source guarantee. Faithful to the reference: per-cluster fingerprint is derived exactly as the Python's `cmd_backfill_fingerprints` (`computeFingerprint(cluster.type, cluster.title)`). Side-effects: `upgrades/side-effects/feedback-factory-dryrun.md`.

package/upgrades/side-effects/existing-agent-pretooluse-hook-parity.md

@@ -0,0 +1,39 @@
+# Side-Effects Review — Existing-Agent PreToolUse Hook Parity
+
+**Spec:** docs/specs/EXISTING-AGENT-PRETOOLUSE-HOOK-PARITY-SPEC.md (approved: true, internal-adversarial review 2026-05-27)
+
+Closes the dark-guardrail migration gap: `init.ts` wired a full instar Bash PreToolUse hook set for NEW agents, but `PostUpdateMigrator.migrateSettings` only ensured slopcheck-guard + the MCP gate for EXISTING agents — so `deferral-detector.js` (the false-blocker pre-filter; this is Task 3 of the silent-stalls postmortem), `grounding-before-messaging.sh`, `external-communication-guard.js`, and `post-action-reflection.js` shipped to disk on every existing agent but were never switched on in settings. Same failure class as the 2026-05-27 silent-stall incident (looks installed, does nothing).
+
+## What changed
+- `src/core/instarSettingsHooks.ts` — NEW. Single source of truth for the canonical instar `Bash` and `mcp__.*` PreToolUse hook ENTRIES (`INSTAR_BASH_PRETOOLUSE_HOOKS`, `INSTAR_MCP_PRETOOLUSE_HOOKS`), a `instarHookFilename()` helper, and the idempotent `ensureInstarBashPreToolUseHooks()`.
+- `src/commands/init.ts` — refactored the inline `instarBashHooks` / `instarMcpHooks` literals to consume the shared constants (fresh copies via `.map(h => ({...h}))`). Behavior-preserving: byte-identical settings output for new agents (verified by the existing `hook-installation.test.ts`, all green).
+- `src/core/PostUpdateMigrator.ts` — `migrateSettings` now calls `ensureInstarBashPreToolUseHooks(preToolUse)` before the slopcheck block; appends only missing canonical hooks, idempotently, reporting each as a `dark-guardrail wiring` upgrade.
+- Tests: `tests/unit/instar-settings-hooks.test.ts` (16) + `tests/unit/PostUpdateMigrator-pretooluse-parity.test.ts` (3).
+
+## Over-block / under-block
+- UNDER: a custom hook with the same script filename would be treated as "present" and not re-added. Acceptable — that's the intent (don't duplicate). Custom hooks under `.claude/hooks/custom/` have different filenames, so they're never matched/displaced.
+- OVER: none. The function only APPENDS missing canonical hooks; it never reorders or removes existing entries, and it touches only the `Bash` matcher. Slopcheck-guard and all non-Bash matchers are untouched.
+
+## Signal vs authority
+N/A for blocking — this wires guardrail hooks into settings. Within the false-blocker design, `deferral-detector` is the SIGNAL (non-blocking checklist injection); `MessagingToneGate` B17 is the AUTHORITY (already live). This change lights up the signal layer on existing agents; it adds no new blocking authority.
+
+## Idempotency / migration parity
+- IS a migration-parity fix. New-agent path (init.ts) and existing-agent path (migrateSettings) now consume the SAME constant — drift is impossible by construction; an anti-drift unit test locks the canonical filename set.
+- `ensureInstarBashPreToolUseHooks` is idempotent (filename-substring presence check, robust to `${CLAUDE_PROJECT_DIR}` vs absolute path); re-runs are no-ops (verified).
+- No config or CLAUDE.md change. No new hook scripts (all four already ship + are ESM-safe).
+
+## Interactions
+- Runs before the existing slopcheck ensure-block; since it creates the `Bash` matcher when absent, slopcheck's "no Bash matcher" branch becomes a no-op while its "add slopcheck" branch still fires. Both end states verified together in the parity test.
+- Codex hooks (`installCodexHooks.ts`, `.*` matcher) are a separate path, intentionally not governed by this module.
+
+## Rollback
+Revert the migrator call + the init refactor + delete the shared module (3 files) and the 2 test files. Worst case: existing agents return to the dark-guardrail state.
+
+## Tests
+- `tests/unit/instar-settings-hooks.test.ts` (16) — anti-drift contract, filename extraction, add/idempotent/preserve/no-matcher/no-dup/fresh-copy, init-imports-the-constant.
+- `tests/unit/PostUpdateMigrator-pretooluse-parity.test.ts` (3) — real `migrateSettings` against a stale agent home: wires the four, idempotent, reports each.
+- Regression-safety: `hook-installation.test.ts`, `installCodexHooks.test.ts`, `codexHookContractCanary.test.ts`, `autonomous-skill-deployment.test.ts`, `capabilities-discoverability.test.ts` all green post-refactor.
+
+## NOT in this commit (tracked)
+- Notify-on-stop (Task 2 — separate PR/spec).
+- Self-propagation harness (Task 4).

package/upgrades/side-effects/feedback-factory-dryrun.md

@@ -0,0 +1,93 @@
+# Side-effects review — feedback-factory dry-run/compare + ReadOnlyShadowStore
+
+Spec: `docs/specs/feedback-factory-migration.md` (converged v2, approved 2026-05-26).
+Increment: the Phase-1/3 dry-run/compare machinery — `ReadOnlyShadowStore` (write-guard),
+`parity.ts` (invariant comparator), `dryRunCompare.ts` (runner + `ParitySource` seam).
+Purely additive: three new `src/feedback-factory/` files + three new unit test files; zero
+edits to existing code.
+
+## What this ships
+
+The mechanism that lets the ported Instar processor run **read-only against Portal's live
+canonical DB** and have its decisions compared to Portal's, with Portal remaining the sole
+writer through cutover (the one-shared-DB precondition that prevents split-brain). Three
+order-independent invariants per spec §2.3:
+
+1. **Fingerprint (per cluster)** — `computeFingerprint(cluster.type, cluster.title)` recomputed
+   over Portal's live clusters and diffed against the stored value. Pure, no replay, fully
+   order-independent. The highest-signal gate (catches byte-level Python↔JS divergence on real
+   production titles). Faithful to the reference's `cmd_backfill_fingerprints` (:256).
+2. **Terminal status** — keyed by fingerprint, not raw slug clusterId.
+3. **Recurrence/cycling count** — keyed by fingerprint.
+
+`result.divergent === true` is the structural signal that blocks Phase 4 cutover.
+
+## Over-block / under-block
+
+- **ReadOnlyShadowStore**: deliberately over-strict on writes — every one of the 6 mutating
+  methods throws. This is the correct direction: the failure we are guarding against
+  (corrupting Portal's curated bug history) is catastrophic and irreversible, while a false
+  block is a loud, immediate, recoverable error at the seam. No under-block path exists: there
+  is no method that silently no-ops a write.
+- **Fingerprint comparator**: skips clusters with no stored fingerprint (pre-backfill rows) —
+  prevents the false positive of flagging "divergence" against an empty string. It does NOT
+  skip any cluster that *has* a fingerprint, so it cannot under-block a real divergence.
+- **Outcome comparator (status/recurrence)**: treats a fingerprint present on only one side as
+  a divergence (`missing-instar` / `missing-portal`) rather than ignoring it — chosen to
+  surface grouping disagreements rather than hide them. This is the conservative (over-surface)
+  direction, appropriate for a cutover gate.
+
+## Level-of-abstraction fit
+
+- The comparator is **pure** (no I/O) and lives beside the other pure processor logic in
+  `processor/`. The runner owns the I/O (read source + JSONL append) and lives in a new
+  `dryrun/` directory — matching the existing separation (pure decision logic vs. composition).
+- `ParitySource` is the single read-only seam. The Prisma-over-Postgres adapter is the only
+  production implementation and is intentionally NOT built here (credentials-gated — see
+  Deferrals). The interface is the contract Dawn confirmed her adapter slots into.
+- `ReadOnlyShadowStore` wraps the existing `FeedbackStore` interface rather than inventing a
+  new one — it is a faithful decorator, so any present or future `FeedbackStore` consumer can
+  be made read-only without changes.
+
+## Signal-vs-authority compliance
+
+This increment is **signal-only**, not authority. It produces a verdict (`divergent`) and a
+JSONL audit trail; it takes no action — no cutover, no migration, no messaging, no mutation.
+The authority to advance Phase 4 remains with the operator + Dawn's line-by-line review. This
+matches the Instar separation: a brittle/automated comparator detects and emits; a
+higher-context human/gate decides. The runner cannot itself flip any switch.
+
+## Interactions
+
+- **Portal's canonical DB**: read-only by construction (ShadowStore guard + read-only
+  `ParitySource`). The runner only ever reads + appends to a *local* JSONL log. No write path
+  to Portal exists in this code.
+- **The ported processor (`process.ts` → `processUnprocessed`)**: the runner does NOT call it
+  (it would write). The comparator uses only the pure functions. The ShadowStore guard is the
+  backstop if a future caller wires `processUnprocessed` against a shadow store by mistake —
+  it throws at the first write instead of corrupting data.
+- **Existing feedback-factory tests**: unaffected (additive change; full unit dir green —
+  128 tests including the 21 new).
+- **No config, hook, route, template, or migration surface is touched** — so no Migration
+  Parity / Agent Awareness obligation is triggered by *this* increment (those land with the
+  receiver/dispatch wiring + observability increments, which DO touch routes/templates).
+
+## Rollback cost
+
+Trivial and isolated. Three new `src/` files + three new test files, no edits elsewhere,
+nothing wired into server startup or routes yet. Reverting the commit removes the files with
+zero downstream impact — nothing imports them in production paths. No data migration, no
+state, no deployed surface.
+
+## Deferrals
+
+- The **Prisma-over-Postgres `ParitySource` adapter** is not built in this increment.
+  Reason: it requires Dawn's read-only Postgres credentials + `prisma db pull` against the live
+  schema (a genuine external dependency, not avoidable work). The `ParitySource` interface +
+  `InMemoryParitySource` make the runner fully buildable and testable now; the live adapter
+  slots in behind the interface the moment credentials land. <!-- tracked: topic-12476 -->
+- **Auto-derivation of Instar's status/recurrence outcomes (invariants 2 & 3) from a
+  point-in-time read** is not built. Reason: a faithful replay needs window-START cluster state,
+  which a current-state read cannot supply; the outcomes must come from a snapshot / full-history
+  export. The comparator + runner accept those outcome lists as inputs today, so the path is
+  complete pending the data source. <!-- tracked: topic-12476 -->

package/upgrades/side-effects/notify-on-stop-layer-b.md

@@ -0,0 +1,34 @@
+# Side-Effects Review — Notify-on-Stop, Layer B (gate-fed unjustified-stall notice)
+
+**Spec:** docs/specs/NOTIFY-ON-STOP-SPEC.md (approved: true) — Layer B of two. Layer A (autonomous-run-ended notice) shipped in a prior PR.
+
+When the UnjustifiedStopGate (shadow/enforce) classifies a stop as unjustified-but-unblockable (`continue` in `shadow` — the gate wants to continue but shadow can't block, so the session silently stalls) or ambiguous (`escalate`), an UNATTENDED session can go quiet mid-task and the user never hears about it. Layer B turns those specific classifications into ONE coalesced heads-up.
+
+## What changed
+- `src/monitoring/StopNotifier.ts` (new) — thin DECISION layer: `isNotifyWorthyStop` (shadow+continue OR escalate; everything else silent) + attended-gate (unattended/autonomous only, default) + per-session dedup (30-min cooldown) + master enable (default ON). Delivery is delegated to an injected `escalate` sink.
+- `src/commands/server.ts` — constructs a dedicated `SentinelNotifier` (telegramEscalation **on** — distinct from the housekeeping sentinel notifier, which stays default-off) reusing the lifeline-topic `sendConsolidated` transport + a JSONL log; wraps it in a `StopNotifier`. Null when telegram isn't wired or config disables it.
+- `src/server/routes.ts` — the `/internal/stop-gate/evaluate` route computes `autonomousActive` (via `getHotPathState`) and, after the authority decision, calls `ctx.stopNotifier?.maybeNotify({ sessionId, mode, decision, autonomousActive })`. Fire-and-forget; never affects the gate decision or the HTTP response.
+- `src/server/AgentServer.ts` — accepts + forwards `stopNotifier` to the routes ctx.
+- `src/core/types.ts` — `monitoring.notifyOnStop?: { enabled?, unattendedOnly?, cooldownMs? }`.
+- Tests: `StopNotifier.test.ts` (21 — both sides of every decision boundary, attended-gate, dedup window/expiry/per-session, master gate, throwing-sink safety) + `stop-notifier-wiring.test.ts` (6 — route→notifier→sink→server→AgentServer chain, guards the PR#334 dead-code failure mode).
+
+## Signal vs authority
+The Stop-hook router is a dumb thin client; the decision to ALARM the user lives server-side in StopNotifier, where the gate decision + attended-state + dedup ledger all exist. StopNotifier adds NO blocking authority — it's a delivery decision only. It never changes the gate's `decision`.
+
+## Near-silent compliance
+Default-on is the deliberate exception Justin explicitly asked for ("tell me why it stopped"), and it is tightly bounded: only two genuinely-stuck decision classes, only unattended sessions, at most once per session per 30 min, coalesced into one message on the single lifeline topic. Routine turn-ends (`allow`), blocked-and-continued (`continue` in enforce), continue-ceiling (`force_allow`), and fail-open are all silent. A single config flag (`monitoring.notifyOnStop.enabled=false`) kills it with no redeploy.
+
+## Over/under-notify
+- OVER: a shadow-mode `continue` could occasionally be a gate misjudgment (the CONTINUE_CEILING exists because the authority can be wrong). Mitigated by attended-gate + 30-min dedup; the alternative (a silent autonomous stall) is exactly what Justin wants eliminated.
+- UNDER: when the gate is `off` (no evaluate call) there's no Layer B notice — but Layer A still covers autonomous terminal exits, and the gate runs in `shadow` on real agents.
+
+## Migration parity
+Default-on works WITHOUT any config key present (`enabled !== false` ⇒ true when undefined), so existing agents get it on update to this version with no migrateConfig step. The wiring is server-side; no agent-installed-file change.
+
+## Rollback
+`monitoring.notifyOnStop.enabled=false` (instant, no redeploy) or revert the 6 files + 2 tests.
+
+## Tests / verification
+- Tier 1 unit: StopNotifier.test.ts (decision matrix both sides + gates).
+- Wiring-integrity: stop-notifier-wiring.test.ts (no dead code).
+- Tier 3 live: test-as-self before merge — drive a synthetic shadow+continue on an autonomous session through the real route and confirm the lifeline-topic heads-up fires once (and a routine `allow` stays silent).