instar 1.3.766 → 1.3.768

package/upgrades/1.3.768.md

@@ -0,0 +1,38 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Fixed the outbound-advisory off-switch, which was silently broken on every real install. The preflight
+route read `messaging.outboundAdvisory.enabled`, but on a real install `messaging` is a JSON **array**
+of adapter configs, so that path resolves `undefined` → the `true` default → the documented off-switch
+(`messaging.outboundAdvisory.enabled: false`) had **no effect** (an operator could not disable the
+advisory). This is the un-DISABLABLE sibling of the PR #1379 un-ENABLABLE bug. The off-switch and tune
+knobs now read from a reachable **top-level `outboundAdvisory`** block (the legacy nested key is
+honored as a back-compat fallback). Existing agents' docs are corrected via a CLAUDE.md migration.
+
+## What to Tell Your User
+
+Nothing proactive — this is an internal fix. If a user ever asks why turning off the automated-message
+advisory did nothing, the answer is that the off-switch was written in a spot the program could not
+read; it now lives at a reachable top-level setting and genuinely works. The advisory is inform-only
+and unchanged otherwise; this only makes its off button work.
+
+## Summary of New Capabilities
+
+- The outbound advisory is now genuinely **disablable** via top-level `outboundAdvisory.enabled: false`.
+- Its tuning knobs (escalation thresholds, the time-claim dev-gate) read from the same reachable
+  top-level block.
+- Legacy object-shaped `messaging.outboundAdvisory` config keeps working (fallback).
+- Existing agents' CLAUDE.md off-switch line is auto-corrected to the reachable key on update.
+
+## Evidence
+
+- `tests/unit/outbound-advisory-config-shape.test.ts` — real LiveConfig + a real array-shaped config:
+  the top-level off-switch disables the advisory (impossible before the fix), default-on when unset,
+  object-shape back-compat.
+- Existing `outbound-advisory-routes` / `outbound-advisory` / `telegram-reply-advisory-script` tests
+  (58) stay green; `tsc` clean; `lint-no-unreachable-messaging-gate` clean.
+- Sibling audit that surfaced it: `docs/investigations/messaging-config-unreachable-audit-2026-07-04.md`.

package/upgrades/side-effects/outbound-advisory-offswitch-config-shape.eli16.md

@@ -0,0 +1,41 @@
+# ELI16 — the "off" button for the auto-message advisory didn't do anything
+
+## The story
+
+Instar has an "outbound advisory" — when a background job tries to send you a message, it first checks
+the text for raw file paths, dev jargon, or localhost links and, if it finds any, holds the message so
+the agent can fix it. It's on by default, and the docs told operators they could turn it off by
+setting a switch: `messaging.outboundAdvisory.enabled: false`.
+
+The problem: that switch never worked on a real setup. The config's "messaging" section is a **list**
+of chat platforms, not a labeled box — so a switch addressed as if it were a box *inside* that list
+can't be read. The program looked, found nothing, and used the default ("on"). So an operator who
+tried to turn the advisory off would find it stubbornly still on, with no error explaining why.
+
+This is the same shape of bug we fixed earlier for the promise follow-through feature (PR #1379). That
+one was worse — a feature you could never turn *on*. This one is milder — a feature you can't turn
+*off* — because it defaults to on, so it still works; you just can't disable it.
+
+## What this change does
+
+It moves the switch to a spot the program can actually read: a **top-level `outboundAdvisory`**
+setting, right next to the other real settings instead of buried in the platform list. Setting
+`outboundAdvisory.enabled: false` there now genuinely turns the advisory off. The old (broken) nested
+key is still honored where it *can* be read (for setups that use a box-shaped config), so nothing that
+worked before breaks. The docs are corrected to point at the new switch — both for new agents and, via
+a small automatic update, for agents that already have the old wording in their notes.
+
+## Why it's safe
+
+- The advisory is inform-only — it never blocks your messages — so there's no risk of it wrongly
+  rejecting anything. The only change is that its off-button now works.
+- Old configs keep working (the old key is a fallback), so it's backwards compatible.
+- It's a plain code + docs change; if it were ever wrong, the fix is a simple revert with no leftover
+  data to clean up.
+
+## How we know it works
+
+A new test sets up the config the **real** way — "messaging" as a list — flips the new top-level
+off-switch, and confirms the advisory reports itself disabled (which was impossible before the fix). It
+also checks the default-on behavior when the switch isn't set, and that the old box-shaped config still
+works. The 58 existing advisory tests all still pass.

package/upgrades/side-effects/outbound-advisory-offswitch-config-shape.md

@@ -0,0 +1,117 @@
+# Side-Effects Review — outbound-advisory off-switch reachable on array-shaped messaging
+
+**Version / slug:** `outbound-advisory-offswitch-config-shape`
+**Date:** `2026-07-04`
+**Author:** `Echo`
+**Second-pass reviewer:** `not required (Tier-1)`
+
+## Summary of the change
+
+The outbound-advisory preflight route read its off-switch (and tuning knobs) at
+`messaging.outboundAdvisory.*`. On a real install `messaging` is a JSON **array** of adapter configs,
+so that dot-path resolves `undefined` → the read's default. For the `enabled` read (default `true`)
+that meant the **documented off-switch (`messaging.outboundAdvisory.enabled: false`) had no effect —
+an operator could not disable the advisory** (the un-DISABLABLE sub-class of the PR #1379 bug). Fix:
+read from the reachable **top-level `outboundAdvisory`** block (canonical), honoring the legacy
+`messaging.outboundAdvisory` as a back-compat fallback. Applied to all four reads
+(`enabled`, `ignoreEscalationThreshold`, `ignoreEscalationSlugThreshold`, `timeClaim.enabled` dev-gate),
+the documented off-switch key in both templates, and an existing-agent CLAUDE.md doc migration.
+Files: `src/server/routes.ts`, `src/core/PostUpdateMigrator.ts`, `src/scaffold/templates.ts`, + test.
+
+## Decision-point inventory
+
+- `POST /messaging/preflight` `enabled` gate (`routes.ts`) — **modify** — top-level-first resolution.
+- `OutboundAdvisoryAudit` threshold reads (`routes.ts`) — **modify** — top-level-first.
+- `timeClaim.enabled` dev-gate value (`routes.ts`) — **pass-through** — sourced top-level-first;
+  `undefined → live-on-dev` semantics unchanged.
+- CLAUDE template off-switch text (both `PostUpdateMigrator` content + `scaffold/templates`) —
+  **modify** — documents the reachable top-level key.
+- `PostUpdateMigrator` TIME_CLAIM anchor marker — **modify** — matched on the stable `- Off-switch: \``
+  prefix so it still anchors regardless of which key the line carries.
+- New `migrateClaudeMd` swap — **add** — updates an existing agent's stale nested-key off-switch line.
+
+## 1. Over-block / 2. Under-block
+
+No block/allow surface change of consequence: the advisory is inform-only and never blocks a message.
+The only behavior change is that the **off-switch now actually works** — an operator who sets
+`outboundAdvisory.enabled: false` disables the advisory (previously impossible). Over-block N/A;
+under-block N/A.
+
+## 3. Level-of-abstraction fit
+
+Right layer — same top-level-first config-read pattern as PR #1379, applied at the read sites. No new
+authority, no new machinery.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — no runtime block/allow surface changes; the advisory remains inform-only. This restores a
+  broken operator control (an off-switch), it does not add gating authority.
+
+## 5. Interactions
+
+- **Shadowing:** none — top-level-first read is a superset of prior behavior; on object-messaging the
+  legacy fallback resolves identically.
+- **Double-fire / races / feedback loops:** none.
+- **Migration marker:** the TIME_CLAIM anchor now matches the stable `- Off-switch: \`` prefix, so it
+  still finds the off-switch line whether CLAUDE.md carries the old nested or the new top-level key —
+  verified the substring is present in both.
+
+## 6. External surfaces
+
+- **Install base / agents:** existing agents get the corrected off-switch DOC via the new
+  `migrateClaudeMd` swap (content-sniff, idempotent) on their next update; new agents via the
+  templates. The CODE fix ships with the server. No config migration needed to keep working (top-level
+  is additive; legacy still honored).
+- **Operator surface:** restores a documented operator control (the off-switch). No new UI/route.
+- **Persistent state / external systems:** none.
+
+## 6b. Operator-surface quality
+
+No dashboard/approval/form surface — not applicable (the off-switch is a config edit, now at a
+reachable key, documented for the operator).
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**machine-local BY DESIGN** — config (`.instar/config.json`) is per-machine; the advisory runs
+per-machine on the sending machine. This change only alters where in the local config the flag is
+read. No cross-machine state, notice, durable state, or URL.
+
+## 8. Rollback cost
+
+Pure code + doc change — revert the reads + template text + the one migration block. No persistent
+state; the top-level key is additive and the legacy fallback preserves prior behavior. Zero-cost
+back-out.
+
+## Conclusion
+
+Restores the outbound-advisory off-switch that was silently broken on every real (array-`messaging`)
+install — the un-DISABLABLE sibling of the PR #1379 un-ENABLABLE bug, found by the sibling audit
+(`docs/investigations/messaging-config-unreachable-audit-2026-07-04.md`). Code + docs + existing-agent
+migration + a real-LiveConfig array-shape test. Clear to ship.
+
+## Second-pass review (if required)
+
+**Reviewer:** not required (Tier-1)
+
+## Evidence pointers
+
+- `tests/unit/outbound-advisory-config-shape.test.ts` — real LiveConfig + real array-shaped config:
+  top-level off-switch disables (was impossible before the fix), default-on when unset, object-shape
+  back-compat.
+- Existing `outbound-advisory-routes` / `outbound-advisory` / `telegram-reply-advisory-script` tests
+  (58) stay green; `tsc` clean; `lint-no-unreachable-messaging-gate` clean.
+
+## Class-Closure Declaration (display-only mirror)
+
+- **`defectClass`** — `config-unreachable-on-shape` (the PR #1379 class; this is its un-DISABLABLE
+  default-ON sub-class).
+- **`closure`** — `gap` — the #1381 lint catches the default-OFF (un-enablable) sub-class; the
+  default-ON un-disablable sub-class (`.get('messaging.*.enabled', true)` with a documented off-switch)
+  is not reliably lint-detectable without false positives (documented in the #1381 side-effects
+  follow-ups). This fix ships the direct regression test + moves the config to the reachable
+  convention; the class-level guard for the un-disablable sub-class remains a tracked gap.
+- **`guardEvidence`** — n/a for `closure: gap`.
+- **`gap`** — tracked in `docs/investigations/messaging-config-unreachable-audit-2026-07-04.md`
+  (follow-up 2) + the #1381 side-effects artifact.

package/upgrades/side-effects/reviewer-door-rewiring-inc2.md

@@ -0,0 +1,110 @@
+# Side-Effects Review — Reviewer-Door Rewiring inc2 (per-family review timeout knob)
+
+**Version / slug:** `reviewer-door-rewiring-inc2`
+**Date:** `2026-07-04`
+**Author:** `echo (build hand)`
+**Tier:** `1`
+**Second-pass reviewer:** `not required (Tier-1: no default value changed, absent-config byte-identical, config-reversible, no durable state / external side-effects; PR is the review surface)`
+
+## Summary of the change
+
+inc2 of REVIEWER-DOOR-REWIRING adds the per-family reviewer-call timeout knob
+(`specConverge.reviewers.timeoutMs`, §3.2 / §7 / D6). It resolves a per-family
+timeout from the config knob and threads it through all three reviewer families'
+invocations (codex-cli, gemini-cli, claude-code). The knob accepts EITHER a single
+number (applies to all families) OR a `{ default, byFramework }` map (per-family
+override with a default fallback). Absent config resolves to today's exact 120s
+default (`REVIEW_TIMEOUT_MS`) for every family — fleet behavior byte-identical.
+Every resolved value is clamped to [30s, 900s]. inc2 ONLY adds the knob: it changes
+no family's default timeout value (the measure-first gemini 600s raise is inc3's
+dogfood decision, not built here).
+
+Files touched:
+
+- `src/core/crossModelReviewer.ts` — new `resolveReviewerTimeoutMs(config, frameworkId)`
+  resolver + `REVIEWER_TIMEOUT_MIN_MS` / `REVIEWER_TIMEOUT_MAX_MS` clamp constants + the
+  `timeoutMs` field on the `ReviewerConfig.specConverge.reviewers` type; `runCrossModelReview`
+  resolves the per-family timeout from the knob (`args.timeoutMs ?? resolveReviewerTimeoutMs(...)`).
+- `skills/spec-converge/scripts/cross-model-review.mjs` — the `--family` path resolves its
+  per-family timeout from the knob when no explicit `--timeout-ms` is passed.
+- `tests/unit/crossModelReviewer-per-family-timeout.test.ts` — new unit + wiring test file (16 tests).
+
+## Decision-point inventory
+
+- `specConverge.reviewers.timeoutMs` config field — **add** — a per-family knob (number OR map). Absent-safe.
+- `resolveReviewerTimeoutMs` — **add** — pure resolver (single-number / byFramework / default / absent) + clamp.
+- `REVIEWER_TIMEOUT_MIN_MS` / `REVIEWER_TIMEOUT_MAX_MS` — **add** — exported clamp bounds (30s / 900s).
+- `runCrossModelReview` timeout resolution — **modify** — resolves per detected `framework.id` (was a bare `?? REVIEW_TIMEOUT_MS`); an explicit caller value still wins.
+- `cross-model-review.mjs --family` timeout resolution — **modify** — resolves per `familyEntry.id`; explicit `--timeout-ms` still wins.
+- No block/allow gate, no HTTP route, no scheduler job, no watcher is introduced or modified.
+- No default timeout VALUE is changed.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+Nothing is rejected. The knob is purely additive and read per-invocation. A garbage
+value (NaN, a string, null, Infinity, a non-finite `default`/`byFramework`) falls back
+to the 120s default rather than throwing or producing a NaN timeout — the resolver is
+pure and never throws. A below-floor or above-ceiling value is clamped, not refused, so a
+misconfiguration still yields a working (bounded) timeout rather than a failed review.
+
+## 2. Under-block
+
+**What bad inputs does this change now allow through that it shouldn't?**
+
+The clamp bounds this precisely: a value below 30s cannot starve a reviewer into an
+instant timeout, and a value above 900s cannot create a 10-round × huge-timeout tail.
+The knob only sets a *time budget*; it grants no authority, changes no egress
+destination, and cannot alter the cross-model flag (that is `crossFamily` semantics from
+inc1, untouched here). An explicit `--timeout-ms` dev override still wins over the knob,
+preserving existing test/dev affordances.
+
+## 3. Blast radius
+
+**If this change is wrong, what breaks and how widely?**
+
+Bounded to the spec-converge external-reviewer call timeouts on a development agent. On
+the fleet the knob is absent, so behavior is byte-identical to today (120s per family) —
+a bug in the resolver could only surface where an operator has deliberately set the knob.
+Worst case of a resolver bug is a wrong (but clamped, 30–900s) timeout on a reviewer call,
+which degrades loudly as a timeout and never blocks convergence (Signal vs. Authority,
+§6). No durable state, no external side-effect, no data migration.
+
+## 4. Reversibility
+
+**How is this rolled back?**
+
+Delete the `specConverge.reviewers.timeoutMs` config value → the resolver returns the 120s
+default for every family. Or revert this PR (constants + resolver + two call-site edits +
+one test file). No persistence, no interface consumed downstream (the field is
+disclosure-free config read per invocation).
+
+## 5. Migration parity
+
+New config field `specConverge.reviewers.timeoutMs` — absent-safe by construction (no
+`migrateConfig` entry needed for fleet correctness; fleet-absence = today's behavior).
+`.instar/config.json` is machine-local (no config replication in instar), so setting the
+knob is a per-machine edit. No settings.json hooks, no CLAUDE.md template section (this is
+instar-developing-agent tooling, not an end-user capability).
+
+## 6. Framework generality
+
+The knob is threaded through the framework-agnostic reviewer registry: the same resolver
+is applied per `framework.id` for codex-cli, gemini-cli, and claude-code alike (and any
+future family added to `SUPPORTED_REVIEWER_FRAMEWORKS`). It routes through the reviewer
+abstraction rather than assuming any single framework; per-framework values are the whole
+point (gemini's reasoning-burn needs more headroom than codex's ~18.5s latency).
+
+## 7. Testing
+
+Unit + wiring (16 tests, `tests/unit/crossModelReviewer-per-family-timeout.test.ts`):
+single-number applies to all families; `byFramework` overrides per family with default
+fallback; **absent config → exactly 120s for every family (byte-identical)**; clamp
+(10s→30s, 2000s→900s, in-range passthrough, clamp within map/default); each family's
+invocation actually receives its resolved timeout through the driver (codex + gemini via
+forced detection, claude via the family entry) — per-family, not uniform; and an explicit
+caller timeout wins over the knob. Existing crossModelReviewer unit + integration suites
+re-run green (105 unit + 10 integration).