instar 1.3.28 → 1.3.30

package/upgrades/1.3.29.md

@@ -0,0 +1,42 @@
+# Instar Upgrade Guide — NEXT
+
+<!-- bump: minor -->
+
+## What Changed
+
+**New building block: agent-to-agent Telegram comms primitive (core logic).** This is the
+first piece of a robust, reusable way for two Instar agents to talk over Telegram *knowingly*
+— every agent-to-agent message carries a visible marker
+(`[a2a:from=… to=… role=… id=… corr=… ts=… v=1]`) so the receiving side can tell it's from
+another agent and apply anti-loop machinery, rather than treating it like a human user
+message. This increment ships the pure, security-critical core: the strict marker
+parser/formatter, the recipient routing decision (with the full drop matrix — malformed,
+replay-window, user-spoof, wrong-recipient, unknown-sender, duplicate, and per-source role
+admission), and the cycle-detection key. It ships **dark** — nothing wires it yet (the
+TelegramAdapter integration and the first consumer, the mentor, land in follow-up PRs).
+
+## What to Tell Your User
+
+- Nothing changes in how your agent behaves today — this is groundwork. It's the foundation
+  for agents being able to message each other over Telegram safely (with built-in defenses
+  so they can't spoof each other or get stuck in a reply loop), which a later update will
+  switch on for the mentor feature.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| `AgentTelegramComms` primitive (core) | Internal `parseMarker` / `formatMarker` / `decideRoute` / `CycleDetector` in `src/messaging/AgentTelegramComms.ts` — pure logic, I/O injected; not wired yet |
+
+## Evidence
+
+**Net-new feature, not a bug fix** — a new pure-logic module that nothing imports yet
+(ships dark). Proven by 20 unit tests covering every branch of the security-critical logic:
+marker parse/format (valid; no-marker vs malformed incl. missing `corr`/`ts`, charset
+violation, no separator; round-trip); the full routing matrix (route + fall-through + every
+drop reason, including the **user-spoof defense** — a human typing a marker-shaped string is
+dropped even when from/id match an allowlisted bot — and **per-source role acceptance** — a
+known role from the wrong source is dropped); and cycle-detection (key never collapses,
+trips within window, no false collision). `tsc --noEmit` clean. The integration + e2e tiers
+(real TelegramAdapter wiring, the bidirectional contract test, the supervised live cycle)
+land with the follow-up PRs per the spec's staged plan.

package/upgrades/1.3.30.md

@@ -0,0 +1,35 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: minor -->
+
+## What Changed
+
+Adds the **Process Health dashboard tab** — a calm, human-readable window into the Failure-Learning Loop (spec `docs/specs/PROCESS-HEALTH-DASHBOARD-TAB-SPEC.md`, converged v4, approved). Until now the loop's findings were API-only (reachable via `/failures*` curl); this tab surfaces them in the dashboard you actually look at.
+
+The tab opens with one plain-English headline ("Watching — N issues recorded"), then surfaced patterns as readable cards (awareness-only — never auto-acted-on), recent captures as plain sentences, and a maturation track with a "← you're here" marker. The dense aggregate counts live in a collapsed "Detail" drawer at the bottom. When the Failure-Learning Loop is off, the tab shows a friendly "not turned on yet" message rather than an error.
+
+UX is the centerpiece, not an afterthought: measurable type bars (headline ≥24px, section headers ≥20px, body ≥17px, line-height 1.5–1.6, zero monospace) are enforced by tests, and a glance check asserts the visible text never reads like a debug log. Every dynamic value (commit messages, agent diagnoses, the classifier's output) flows through a single sanitize-and-cap helper before the DOM — textContent-only writes, NFKC fold, control/bidi/chrome-glyph strip, grapheme-safe length caps, and a same-origin `safeUrl` — so untrusted upstream text can't inject markup, fake-authority glyphs, or invisible/right-to-left trickery. The redaction contract (`detail.full` never crosses the wire) is verified end-to-end against a live HTTP server.
+
+Server-side this adds ETag/304 diff-aware polling on `/failures*`, a `before=` keyset-pagination parameter (rejects a non-ISO value with 400), and a `rollout` block on `/failures/analysis` (the maturation stage the tab draws). No behavioral change when the loop is disabled — every route still 503s and the tab renders its disabled copy.
+
+## What to Tell Your User
+
+- There's a new **Process Health** tab in your dashboard. It's a calm, plain-English view of what the failure-watching system is noticing — big readable type, short sentences, no wall of logs.
+- Think of it like a dashboard light in a car, not the mechanic's diagnostic printout: one line tells you whether anything needs a look; the raw numbers are tucked away in a drawer you only open if you want them.
+- If the failure-watching system isn't switched on for an agent, the tab just says so politely instead of looking broken.
+- Nothing to run and nothing to babysit — it refreshes itself quietly while the tab is open and pauses when it isn't.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Process Health dashboard tab | Open the "Process Health" tab in the dashboard (give the user the dashboard URL + PIN) |
+| Diff-aware polling (ETag/304) | Automatic — `GET /failures*` now return an `ETag`; a matching `If-None-Match` gets a 304 |
+| Keyset pagination | `GET /failures?before=<ISO-ts>&limit=N` and `GET /failures/insights?before=<ISO-ts>&limit=N` |
+| Rollout-stage readout | `GET /failures/analysis` now includes `rollout: { stage, enabled, insightTelegramEscalation }` |
+
+## Evidence
+
+- **3-tier + jsdom tests, all green:** unit (sanitize/safeUrl/wording + renderers against a real jsdom DOM + ledger pagination), integration (the polling controller — XSS negative, layout-bomb, out-of-order race, visibility-gating, staleness hard-fail AND the 304-pinned-headline case, 304 backoff/recovery, diff-aware zero-mutation; plus the route ETag/304/`before=`/rollout behaviors), and an E2E lifecycle test that boots a real HTTP server and drives the shipped controller through a jsdom-mounted tab with the feature ON and OFF.
+- **Safety verified, not asserted:** the XSS negative fixture feeds `<img onerror>`/`<script>`/`<svg onload>` through the full controller path and asserts zero live elements + no canary fired; the E2E seeds a failure whose `detail.full` is a secret path and confirms it never appears in the rendered DOM.
+- **Migration parity:** the CLAUDE.md "Process Health (Dashboard Tab)" section ships to existing agents via `PostUpdateMigrator.migrateClaudeMd`, and a shadow-capability marker carries it to Codex/Gemini agents — both enforced by the Feature Delivery Completeness test.

package/upgrades/side-effects/agent-telegram-comms-primitive.md

@@ -0,0 +1,75 @@
+# Side-Effects Review — Agent-to-Agent Telegram comms primitive (core logic, PR 1)
+
+**Spec:** `docs/specs/MENTOR-LIVE-READINESS-SPEC.md` §Fix 2a (converged, approved by Justin
+2026-05-27). Convergence report: `docs/specs/reports/mentor-live-readiness-convergence.md`.
+**Change:** New module `src/messaging/AgentTelegramComms.ts` — the PURE, security-critical
+core of the agent-to-agent Telegram comms primitive: strict marker parse/format, the
+recipient routing matrix (every drop branch), and cycle-detection. I/O (the actual Telegram
+send, audit ledgers, processed-id store) is **injected**, so this PR is pure logic + tests;
+the TelegramAdapter wiring + ledger persistence is PR 2, the mentor consumer is PR 3.
+**Files:** `src/messaging/AgentTelegramComms.ts` (new), `tests/unit/messaging/AgentTelegramComms.test.ts` (new).
+**Ships dark:** nothing imports the module yet except its test — zero runtime behavior change.
+
+## Principle check (Phase 1)
+
+Decision point? Yes — this is the recipient admission/routing decision (`decideRoute`) and
+the anti-loop cycle key. It is built as PURE functions returning a decision the caller acts
+on; the blocking authority (drop vs route) is explicit + exhaustively tested. No existing
+gate is loosened (nothing wired yet).
+
+## The seven questions
+
+1. **Over-block.** `decideRoute` drops on every ambiguous/unrecognized shape (malformed,
+   stale, spoofed, wrong-recipient, unknown-version, unknown-sender, duplicate,
+   role-not-allowed). Correct posture for a security boundary — a marker-shaped string is
+   guilty until allowlisted. The only fall-through is a genuine no-marker (normal user msg).
+2. **Under-block.** The spoof defense (`!senderIsBot && senderChatId===undefined` → drop)
+   is the round-2 adversarial F1 closure — a human typing a marker can NEVER reach a
+   role-handler, even if from/id match. Tested explicitly. `corr`/`ts` are required in the
+   parser so neither the cycle key nor the replay window can be bypassed by omission.
+3. **Level-of-abstraction fit.** Pure logic separated from I/O — the security decisions are
+   unit-testable in isolation (20 tests, every branch). I/O injection deferred to PR 2.
+4. **Signal vs authority.** `decideRoute` IS the authority (drop/route); it returns a typed
+   decision + audit reason for every branch (no silent drops — caller writes the audit row).
+5. **Interactions.** Module is dark (imported only by its test). No interaction with the
+   running system yet. PR 2 wires it into TelegramAdapter (multi-instance + handler-chain);
+   PR 3 wires the mentor consumer. Each subsequent PR re-runs the gate against the same spec.
+6. **External surfaces.** None in this PR (no routes, no config consumed yet). The marker
+   format is the wire contract for PR 2/3 + Codey's side; `A2A_VERSION` is exported for
+   version pinning.
+7. **Rollback cost.** Trivial — revert removes an unused module. No data, no migration.
+
+## Build-time refinements beyond the spec text
+
+- The spec mentioned `state/a2a-*.jsonl` (append-only JSONL audit) + a processed-id JSON
+  store. Convention note (MessageProcessingLedger header: "NOT a new ad-hoc JSON file") —
+  PR 2 will implement the processed-id store on the SQLite path (matching
+  PendingRelayStore/CommitmentTracker) rather than a JSON file; the append-only audit
+  ledgers stay JSONL (Codey designed the audit-row schema as JSONL, and append-only JSONL
+  is the right shape for a forensic trail). Flagged here so PR 2's choice is intentional.
+- `senderBotId` resolution (`sender_chat.id ?? from.id`) + `senderIsBot` are passed in by
+  the caller (PR 2 resolves them from the Telegram update, after the Message type is
+  extended to expose `is_bot`/`sender_chat`). The pure core only consumes them.
+
+## Testing
+
+- 20 unit tests (`tests/unit/messaging/AgentTelegramComms.test.ts`), all passing:
+  - **Marker parse/format**: valid parse; no-marker (fall-through) vs malformed (drop) —
+    incl. missing `corr`, missing `ts`, charset violation, no blank-line separator;
+    format↔parse round-trip; format rejects charset-violating fields.
+  - **Routing matrix**: route success; fall-through; and every drop branch — malformed,
+    stale/future (replay), **user-spoof** (human-typed marker dropped even when from/id
+    match), group bot-as-channel accept, wrong-recipient, unsupported-version, unknown
+    sender, bot-id mismatch, duplicate, **role-not-allowed-from-source** (notify from echo
+    dropped even though notify is a known role), unknown-role.
+  - **Cycle-detection**: key never collapses (corr always present); trips within window,
+    clears after; no collision on different corr.
+- tsc --noEmit clean.
+- PR 2/3 add the integration + e2e tiers (TelegramAdapter wiring, mentor consumer, the
+  bidirectional contract test, the supervised live cycle).
+
+## Migration parity
+
+None for this PR — a new unwired module. No agent-installed file changes, no config, no
+routes. PR 2/3 carry the config defaults + migration (file-outbox retirement, dead-config
+removal) per the spec's §Migration parity.

package/upgrades/side-effects/process-health-dashboard-tab.md

@@ -0,0 +1,59 @@
+# Side-Effects Review — Process Health dashboard tab
+
+**Version / slug:** `process-health-dashboard-tab`
+**Date:** 2026-05-27
+**Author:** echo
+**Spec:** `docs/specs/PROCESS-HEALTH-DASHBOARD-TAB-SPEC.md` (v4, converged, approved: true)
+
+## Summary of the change
+
+Adds a read-only dashboard tab that renders the Failure-Learning Loop's data (captures, surfaced patterns, rollout stage) as a calm, plain-English surface. Until now those data were API-only (`/failures*`); this makes them visible in the dashboard. The feature ships with the loop's existing on/off flag — when the loop is disabled every `/failures*` route 503s and the tab renders a friendly disabled state.
+
+**Files changed (source):**
+- `dashboard/process-health.js` (NEW, ~504 lines) — browser-native ESM module: pure renderers + the polling controller, both exported for tests. The load-bearing safety contract lives here (`sanitizeForDisplay`, `safeUrl`, `isMixedScript`, friendly-wording maps).
+- `dashboard/index.html` — the tab button, panel markup, calm CSS (measurable type bars, no monospace), tab registration, and the lazy-import lifecycle wiring (start on activate / stop on hide).
+- `src/server/routes.ts` — ETag/304 on `/failures` + `/failures/insights`, `before=` ISO-validation (400 on garbage), and the `rollout` block assembled in `/failures/analysis` (stage derived from the two `failureLearning` flags).
+- `src/monitoring/FailureLedger.ts` — `ListFilter.beforeMs`/`limit`, a new `InsightListFilter` (50-default / 1000-max), a `listInsights` query-builder rewrite (where[]+LIMIT), and a `discovered_at` index for keyset pagination.
+- `src/scaffold/templates.ts` — the "Process Health (Dashboard Tab)" CLAUDE.md section for new agents (Agent Awareness Standard).
+- `src/core/PostUpdateMigrator.ts` — `migrateClaudeMd` backfill of that section for existing agents + a `migrateFrameworkShadowCapabilities` marker so Codex/Gemini agents learn it (Migration Parity Standard).
+
+**Files changed (tests):**
+- `tests/unit/process-health-render.test.ts` (NEW) — sanitize/safeUrl/wording + renderers against jsdom + CSS type-bar assertions.
+- `tests/integration/process-health-tab.test.ts` (NEW) — the polling controller's full §4.3 surface (XSS, layout-bomb, race, visibility-gating, staleness hard-fail + 304-pinned, backoff, diff-aware) + the glance no-debug-vocabulary check.
+- `tests/e2e/process-health-tab-lifecycle.test.ts` (NEW) — real HTTP server + jsdom-mounted tab, feature ON and OFF; detail.full-never-leaks verified end-to-end.
+- `tests/integration/failure-routes.test.ts` — ETag/304, `before=` 400, rollout-stage derivation.
+- `tests/unit/FailureLedger.test.ts` — before=/limit pagination + insight clamp.
+- `tests/unit/PostUpdateMigrator-processHealth.test.ts` (NEW) — runtime migration + idempotency.
+- `tests/unit/feature-delivery-completeness.test.ts` — registered Process Health in `featureSections`; incidentally fixed a pre-existing untracked section (`Cross-Machine Seamlessness`).
+
+**Files changed (dependency):** `package.json` / `package-lock.json` — added `jsdom` as a devDependency (the spec's chosen DOM test harness; no runtime dependency added).
+
+**Files changed (release):** `upgrades/NEXT.md` (NEW) — the upgrade-guide leg, `bump: minor`.
+
+## Decision-point inventory
+
+- **New runtime dependency?** No. `jsdom` is devDependencies only; the tab ships as browser-native ESM with no build step and no new server-side package.
+- **New auth surface?** No. The tab is served behind the existing dashboard PIN; it adds no endpoint that wasn't already auth-gated.
+- **Untrusted-data rendering** (commit messages, agent diagnoses, classifier output): **render, but only via the sanitize-and-cap helper** — textContent-only DOM writes, NFKC fold, control/bidi/chrome-glyph strip, grapheme-safe caps, same-origin `safeUrl`. Patterns cards are awareness-only with renderer-owned framing and NO action authority.
+- **Behavior when loop disabled:** unchanged — routes still 503, tab renders pinned disabled copy (no config-key string, no monospace), never an error.
+
+## Side-effects analysis
+
+- **Behavioral:** Additive. The new route behaviors (ETag/304, `before=`) are backward-compatible — a client that ignores ETags gets a normal 200; omitting `before=` is unchanged. The `rollout` block is a new field on an existing response, not a breaking change.
+- **Architectural:** The tab is one self-contained module, not a refactor of the dashboard SPA (explicitly out of scope per spec §10). `listInsights` moved from a ternary to the same where[]+LIMIT builder `list()` already uses — same shape, lower divergence.
+- **Security:** The primary surface is rendering untrusted upstream prose on a read tab. Mitigated by the single sanitize path + textContent-only + element-ban (verified by the XSS negative fixture firing no canary and producing zero live elements). The `detail.full` redaction contract is depended upon and verified end-to-end (a seeded secret path never appears in the DOM). Accepted residual: a low-severity social-engineering surface inherent to showing untrusted text — any future *actionable* treatment is gated behind the deferred `InsightRecord.provenance` contract (spec §10).
+- **Migration parity:** Covered all three legs — templates.ts (new agents), PostUpdateMigrator (existing agents + shadow markers for Codex/Gemini), and NEXT.md (upgrade guide). Enforced by the Feature Delivery Completeness test.
+- **Performance:** ETag/304 + diff-aware rendering means identical ticks do zero DOM mutations and 304s skip body transfer; 304-backoff widens the poll to 5 min after 5 idle ticks. The new `discovered_at` index supports keyset pagination without a full scan.
+- **Reversibility:** Fully reversible by reverting the commit. The feature is gated OFF by default via the existing `failureLearning.enabled` flag — no agent sees the tab change behavior until the loop is enabled, and even then it is a read surface.
+
+## Deferred (tracked, not silently dropped)
+
+- **LLM text-smoke (spec §6.4b):** implemented the *deterministic* glance gate (no-debug-vocabulary + plain-state assertion across all 3 fixtures), which is structurally stronger than an LLM judgment for this property and runs in CI. The soft LLM-judgment variant (a Haiku call over the text projection) is deferred as a manual reviewer-attested pre-flight rather than a forever-skipped CI harness — consistent with §6.4a's "honestly labeled soft" framing.
+- **Visual dashboard polish / extra ingestion sources:** already tracked as fast-follows on the initiative board (spec §10).
+
+## Evidence pointers
+
+- Typecheck: `tsc --noEmit` — 0 errors.
+- CI-mirror smoke suite (`npm run test:smoke`): **149 files, 3553 tests passed, 0 failed**.
+- New tests run green in isolation: unit render (27), controller integration (12), failure-routes (11), FailureLedger (11), migrator (2), E2E lifecycle (4).
+- Safety verified not asserted: XSS fixture fires no canary + 0 live elements; E2E confirms a seeded `detail.full` secret path is absent from the rendered DOM.

package/upgrades/side-effects/release-readiness-visibility-pr1.md

@@ -0,0 +1,26 @@
+# Side-Effects Review — Release-Readiness Visibility, PR-1 (`analyze-release.js --ref`)
+
+**Spec:** docs/specs/RELEASE-READINESS-VISIBILITY-SPEC.md (converged + approved 2026-05-27)
+**Scope of this PR:** the prerequisite-only change — add a `--ref=<rev>` flag to `scripts/analyze-release.js` and thread it through the git-range queries. No sentinel, no job, no routes (those are PR-2/PR-3). Plus the approved spec docs + convergence report + a unit test.
+
+## What changed
+
+- `scripts/analyze-release.js`: new `REF` constant parsed from `--ref=<rev>` / `--ref <rev>` (default `HEAD`). Threaded into `getLastReleaseTag`, `getCommitsSinceTag`, `getDiffStat`, `getChangedFiles`, `getFileDiff` — every place that previously hardcoded `HEAD`.
+- `tests/unit/analyze-release-ref-flag.test.ts`: 4 subprocess tests against a deterministic git fixture (default ≡ HEAD; `--ref=HEAD` ≡ default; `--ref=<earlier commit>` changes the analyzed tip — different nearest tag + commit count; space form ≡ equals form).
+- Spec + ELI16 + convergence report (docs only).
+
+## Side-effects analysis
+
+**Over/under-reach.** The change is additive and opt-in. `REF` defaults to `'HEAD'`, so every existing caller — most importantly the `prepublishOnly` chain (`npm run check:release` → `analyze-release.js`, which never passes `--ref`) — produces byte-identical behavior to before. There is no path where omitting the flag changes output. Verified by the `--ref=HEAD ≡ default` test.
+
+**Level-of-abstraction fit.** The ref is a module-level constant rather than a threaded parameter, matching the script's existing shape (`getLastReleaseTag()` already took no args and implicitly used HEAD). This keeps the diff minimal and the helpers' signatures unchanged for the four that already took `tag`.
+
+**Signal vs authority.** N/A for this PR — `analyze-release.js` is a read-only analyzer (it only reads git and prints a report). It gates nothing. The flag does not grant or remove any blocking authority. The downstream consumer that WILL use `--ref=FETCH_HEAD` (Layer B's readiness sentinel) is signal-only and ships in PR-2.
+
+**Interactions.** The only consumer touched today is the prepublish chain, which is unaffected (default HEAD). `check-upgrade-guide.js` is not touched. The `--ref` flag is forward-looking: PR-2's readiness job will invoke `--ref=FETCH_HEAD` after a bounded fetch of canonical main. Per §10 sequencing, PR-2 does not merge until this PR is on main, enforced by a required-status CI check that asserts `--ref=<known SHA>` differs from `--ref=HEAD` (i.e. the flag is genuinely threaded, not silently ignored).
+
+**Input safety.** `REF` flows only into `git` argv arrays via the existing `gitRead` helper (`execFileSync`, no shell) — no shell-injection surface. A bogus ref makes the underlying `git` call fail and the existing `try/catch` returns the empty/initial-commit fallback, exactly as today for a tagless repo.
+
+**Rollback cost.** Trivial — reverting this commit restores the hardcoded `HEAD`. No state, no config, no migration introduced by PR-1. The unit test reverts with it.
+
+**Testing.** Unit tier covered (4 tests, green). Integration/E2E tiers are not applicable to PR-1 in isolation (no routes/jobs yet) and land with PR-2, which adds the `GET /release-readiness` route + the "feature is alive" E2E that exercises the full readiness pipeline including the `--ref` path.