instar 1.3.485 → 1.3.487

package/upgrades/side-effects/outbound-advisory-inform-only.md

@@ -0,0 +1,252 @@
+<!-- DRAFT — completed in Phase 4 of /instar-dev. Phase 1 principle check + Phase 2 plan recorded below first. -->
+
+# Side-Effects Review — Outbound advisory: jargon + raw-file-path gaps for automated senders (inform-only)
+
+**Version / slug:** `outbound-advisory-inform-only`
+**Date:** `2026-06-11`
+**Author:** `echo (instar-dev agent)`
+**Second-pass reviewer:** `required — outbound-messaging decision surface (Phase 5)`
+
+## Phase 1 — Principle check (recorded before any code)
+
+**Does this change involve a decision point?** YES — it touches the outbound-messaging
+pipeline, the single most sensitive decision surface in instar. The signal-vs-authority
+principle applies directly, and the design (per the converged + approved spec
+`docs/specs/outbound-jargon-filepath-gap.md`, r2) was shaped around it:
+
+- `detectRawFilePath` (new) and `detectJargon` (re-scoped) are pure DETECTORS — regex,
+  cheap, fail-open, no blocking power. They feed the EXISTING authority
+  (`MessagingToneGate.review`) as signals. No new rule, no re-scoped block rule.
+- The preflight advisory is honestly named in the spec as a "default-withhold the sender
+  always resolves" — the sending agent keeps final authority (fix or `--ack-advisory`,
+  both always deliver past the advisory layer). It never consults a judge, never
+  escalates against the sender, fails open on every error path.
+- The repeated-ignore escalation informs the OPERATOR (one deduped Attention item),
+  gates nothing.
+- Governing operator constraint (Justin, 2026-06-10): zero new blocking authority.
+  r1's deterministic 422 floor was DELETED in r2 for exactly this reason.
+
+## Phase 2 — Plan (recorded before any code)
+
+**Build location:** fresh worktree `.worktrees/echo-outbound-advisory-build`, branch
+`echo/outbound-advisory-build`, based off `JKHeadley/main` @ v1.3.484 (verified:
+`git remote -v` = JKHeadley https, `package.json` 1.3.484, git identity
+`Instar Agent (echo) <echo@instar.local>`).
+
+**Implementation order:**
+1. `detectRawFilePath` detector (sibling of `localhost-link.ts`, same linear-regex discipline) + unit tests.
+2. `messageKind` union widening (`'automated'`) in all five cited sites + `renderMessageKind` branch.
+3. `checkOutboundMessage`: always-compute jargon for non-`reply` kinds (drop the `options.jargon` opt-in; fix the one vestigial caller); feed `signals.filePath`.
+4. `POST /messaging/preflight` + `GET /messaging/advisory-log` + server-side single-writer JSONL audit + in-memory escalation index + Attention escalation (fixed sourceContext).
+5. Scheduler env injection: BOTH SessionManager spawn env blocks (headless + rerouted-interactive) + JobScheduler `runScriptJob` env (`INSTAR_MESSAGE_KIND`, `INSTAR_JOB_SLUG`, `INSTAR_SENDER_CLASS`).
+6. `telegram-reply.sh` template: metadata forwarding in BOTH body builders, preflight loop + `--ack-advisory`, curl timeout ms→s clamp, queue metadata column in BOTH script queue writers (quote-safe).
+7. `PendingRelayStore` COLUMN_ADDS metadata column + `DeliveryFailureSentinel.postReply` threading + redrive exemption via `X-Instar-DeliveryId` validated against a real queue row.
+8. Relay-hop forwarding (3-layer widening) so kind/senderClass/ack survive the cross-machine hop.
+9. `/telegram/reply`: read `metadata.messageKind` → `checkOutboundMessage`; `acked` audit row; kindless-job-send + class-spoof breadcrumbs; senderClass validation against the job definition.
+10. Config plumbing via LiveConfig (live re-read; `?? true` defaults — rollback without restart).
+11. PostUpdateMigrator: current live telegram-reply SHA → allowlist; CLAUDE.md template section (add advisory awareness, remove hand-curl example); `migrateFrameworkShadowCapabilities` marker.
+12. All three test tiers per spec §6; release fragment; this artifact completed; trace; commit; PR; CI; merge (Phase 7 auto-merge on green).
+
+**Decision points touched:** outbound `/telegram/reply` pipeline (signals only), new preflight route (advisory only), Attention queue (operator-inform only).
+**Existing detectors/authorities interacted with:** `detectJargon`, `detectLocalhostLink`, `MessagingToneGate.review` (B2/B12 untouched in scope), grounding-before-messaging hook (independent layer, unchanged).
+**Rollback path:** `messaging.outboundAdvisory.enabled:false` + `messaging.outboundFloor.jargonAlways:false` (live config, no restart); scheduler env injection inert without script/route consumers; queue column is nullable + idempotent-ALTER (legacy rows fine).
+
+## Summary of the change
+
+Implements the converged + approved spec `docs/specs/outbound-jargon-filepath-gap.md` (r2): structural
+`automated` message-kind stamping at job spawn (SessionManager both lanes + JobScheduler script env),
+the jargon signal single-sourced for non-reply kinds, a new `detectRawFilePath` signal detector, an
+inform-only preflight advisory in `telegram-reply.sh` backed by `POST /messaging/preflight` +
+`GET /messaging/advisory-log`, a server-side single-writer audit with repeated-ignore escalation, kind
+metadata threading through the durable relay queue / sentinel redrive / cross-machine relay hop, and
+full migration parity (SHA allowlist + CLAUDE.md + shadow mirrors). Files: `src/core/raw-file-path.ts`
+(new), `src/messaging/OutboundAdvisory.ts` (new), `src/core/MessagingToneGate.ts`,
+`src/server/routes.ts`, `src/server/AgentServer.ts`, `src/core/SessionManager.ts`,
+`src/scheduler/JobScheduler.ts`, `src/templates/scripts/telegram-reply.sh`,
+`src/messaging/pending-relay-store.ts`, `src/monitoring/delivery-failure-sentinel.ts`,
+`src/messaging/TelegramAdapter.ts`, `src/core/TelegramRelay.ts`, `src/core/PostUpdateMigrator.ts`,
+`src/scaffold/templates.ts` + three test tiers.
+
+## Decision-point inventory
+
+- `evaluateOutbound` / `checkOutboundMessage` (routes.ts) — **modify (signals only)** — two new SIGNALS (jargon for non-reply kinds, filePath for all kinds) feed the EXISTING authority; no decision logic changed; block/allow remains solely the authority's.
+- `MessagingToneGate.review` — **pass-through** — receives the new kind + signals as context; rules untouched (no B12 re-scope, no new rule).
+- `POST /messaging/preflight` (new) — **add (advisory only)** — deterministic detectors, returns advisories; CANNOT refuse a send (the server delivers regardless — proven by test).
+- `telegram-reply.sh` preflight loop — **add (default-withhold the sender always resolves)** — honestly named per spec §2.4: the first flagged attempt does not deliver; resolution (fix or ack) belongs exclusively to the sender; fail-OPEN on every error path.
+- Repeated-ignore escalation — **add (operator-inform only)** — one deduped Attention item; gates nothing.
+- Observability breadcrumbs in `/telegram/reply` — **add (log lines only)** — never affect delivery; wrapped in a try/catch.
+
+---
+
+## 1. Over-block
+
+The server holds NO new block surface — `/telegram/reply` delivers a raw-path automated message
+exactly as before (test-proven). The script-side withhold can over-fire two ways:
+
+- `detectRawFilePath` false positive (e.g. a legitimate user-actionable path in a power-user setup):
+  costs the sender one `--ack-advisory` re-run; the message still delivers unchanged. Bounded cost,
+  stated in the spec's risk table.
+- `detectJargon` false positive on an automated send: same single-re-run cost. Jargon is deliberately
+  NOT computed for conversational replies, so the over-block tail the operator has repeatedly warned
+  about cannot grow on the main path.
+
+A genuinely-flagged localhost link is the one case `--ack-advisory` cannot deliver — but that block
+belongs to the PRE-EXISTING localhost guard (untouched); the advisory's static guidance states this
+honestly rather than promising ack-delivery.
+
+## 2. Under-block
+
+- A job that hand-curls `/telegram/reply` (bypassing the script) sends kindless and skips the
+  preflight entirely — named residual (§2.1/§2.5), bounded by the kindless-job-send breadcrumb and the
+  removal of the hand-curl example from the CLAUDE.md template. Accepted by design (sender sovereignty).
+- `isProxy`/`isSystemTemplate`/`willRelay` system-composed sends skip `checkOutboundMessage` today and
+  are untouched — there is no sender to inform. Named residual.
+- A one-shot sender that ignores its advisory drops that one message with no re-fire behind it; the
+  per-slug aggregate escalation is the bound. Accepted residual cost of inform-only, per the operator's
+  explicit constraint.
+- `detectRawFilePath` misses path shapes outside its three alternatives (e.g. bare relative
+  `foo/bar.txt` with an unknown top dir, Windows `C:\` paths). Deliberate precision-first scope —
+  the LLM authority's B2 judgment still covers them on gated kinds.
+
+## 3. Level-of-abstraction fit
+
+Correct layers throughout: the detector is a cheap deterministic sibling of `localhost-link.ts` in
+`src/core/`; the signals feed the EXISTING authority instead of running parallel to it (the spec's
+grounding correction explicitly rejected a new gate); the advisory loop lives in the mandated relay
+script (the only place that can inform the sender BEFORE delivery without giving the server veto
+power); the audit/escalation live server-side where the single-writer guarantee is enforceable. The
+kind is stamped at the SPAWNER (the only layer that structurally knows a session is a job).
+
+## 4. Signal vs authority compliance
+
+**Required reference:** docs/signal-vs-authority.md
+
+- [x] No — this change produces signals consumed by an existing smart gate.
+
+`detectRawFilePath` and the re-scoped `detectJargon` are pure detectors feeding
+`MessagingToneGate.review`. The preflight advisory holds no blocking authority: its withhold is always
+and only resolved by the sender, never escalates, never consults a judge, and fails open on every
+error path — the spec names it honestly as a "default-withhold the sender always resolves" rather than
+claiming "no authority at all". r1's deterministic 422 floor was DELETED per the operator's
+inform-only constraint; no block rule was added or re-scoped anywhere in this change.
+
+## 5. Interactions
+
+- **Shadowing:** the preflight runs BEFORE the send, script-side; the existing pipeline (localhost
+  guard, tone gate, dedup, length cap) runs unchanged server-side afterward. One send can legitimately
+  receive two differently-shaped interventions (grounding hook + advisory) — independent layers; the
+  advisory text never claims to be the only check.
+- **Double-fire:** the `acked` audit row is written ONLY on successful delivery, so an
+  acked-then-queued send audits once, after the redrive — verified that the queue carries
+  `advisoryAck` whole, closing the escalation false-fire on transient delivery failures.
+- **Races:** the escalation index is in-memory single-process (write-time, no poller); restart resets
+  are accepted, stated best-effort observability. JSONL appends are single `appendFileSync` calls
+  (O_APPEND).
+- **Feedback loops:** the escalation raises Attention items through `createAttentionItem` with a
+  FIXED sourceContext and stable per-signature ids (id-dedup prevents re-raise loops). **Corrected
+  after the second-pass review:** HIGH/URGENT items are EXEMPT from the per-source topic budget, so
+  the original all-HIGH design would have been an un-budgeted topic-per-signature flood for a
+  topic-varying sender. Iterated: per-signature items are NORMAL (the budget genuinely binds — a
+  burst-invariant test feeds escalations through the REAL AttentionTopicGuard and asserts allowed
+  topics ≤ the budget); the per-slug aggregate is the single loud HIGH bound (one deduped item per
+  slug); once a slug's aggregate has fired, further per-signature items for that slug are suppressed.
+- The sentinel's `postReply` signature widened with optional trailing params — all existing callers
+  and test doubles remain compatible (verified by the full suite).
+
+## 6. External surfaces
+
+- **Other agents on the machine:** job sessions of every framework (claude/codex/gemini) get the new
+  env vars — inert unless the relay script consumes them. The CLAUDE.md awareness section reaches
+  Codex/Gemini via the shadow-capability mirror.
+- **Install base:** the `telegram-reply.sh` re-deploy rides the SHA-gated migrator; user-modified
+  scripts are never stomped (`.new` + degradation event, existing behavior). The queue column arrives
+  via idempotent ALTER on every writer — legacy rows read null metadata and ride the delivery-id
+  breadcrumb exemption.
+- **External systems:** no new egress. The preflight is a localhost call; detectors are local regex.
+- **Persistent state:** new `logs/outbound-advisory.jsonl` (size-rotated, single `.1` rollover); new
+  nullable `message_metadata` column in the pending-relay SQLite (additive, no migration needed for
+  rollback).
+- **Timing:** the preflight adds one localhost round-trip (~ms) + ~100ms of process spawns per
+  automated send; bounded by the clamped curl timeout; the conversational path is untouched.
+
+## 7. Rollback cost
+
+- **Hot levers (live config, NO restart):** `messaging.outboundAdvisory.enabled:false` disables the
+  preflight + escalation; `messaging.outboundFloor.jargonAlways:false` reverts the jargon signal.
+  Both are read per-request through LiveConfig.
+- **Code revert:** the scheduler env injection is inert without the script/route consumers, so a
+  partial rollback degrades safely in any order.
+- **Data:** the JSONL audit and the nullable queue column need no cleanup on rollback (additive,
+  null-tolerant readers).
+- **User visibility during rollback:** none — worst case, automated sends simply stop being advised.
+
+## Conclusion
+
+The review confirms the design holds the operator's governing constraint structurally: zero new
+blocking authority anywhere in the server; the only withhold lives script-side, is always resolvable
+by the sender alone, and fails open on every error path (each proven by a test, not asserted). The
+named residuals (hand-curl bypass, system-composed sends, one-shot drops) are bounded by breadcrumbs
+and the escalation, and are the accepted cost of inform-only — the operator chose this trade
+explicitly. One design change came out of testing: the fix-landing resolution threshold was tuned to
+0.4 Jaccard after measuring the founding incident shape (~0.47) vs the gaming heartbeat (~0.06).
+Clear to ship pending the required second-pass review (outbound-messaging decision surface).
+
+---
+
+## Second-pass review (required — outbound messaging surface)
+
+**Reviewer:** subagent (claude, independent second-pass)
+**Independent read of the artifact: concern → resolved → concur (re-confirmed below)**
+
+First-pass verdict (verbatim): the core inform-only claims all verified adversarially against the
+code (no new server-side blocking authority; no silent drop — the NOT-SENT line precedes every
+withhold; fail-open complete across curl failure/timeout/non-200/malformed-JSON/missing-python3/
+disabled; secret-safety bounds hold at all four echo sites; queue/redrive/relay threading and
+migration parity verified). Three concerns were raised:
+
+1. **(Load-bearing) The §5 flood-bound claim was FALSE as written:** per-signature escalations were
+   HIGH, and HIGH bypasses BOTH the per-source budget and the universal topic budget — a
+   topic-varying sender would have produced K un-budgeted HIGH topics (the 2026-06-05 flood shape);
+   the spec-required burst proof test was missing, which is exactly why the false claim survived.
+   **Resolution (implemented):** per-signature items demoted to NORMAL (budget-eligible); per-slug
+   aggregate kept as the single deduped HIGH; per-signature suppressed once the slug aggregate has
+   fired; burst-invariant test added driving 10 distinct misbehaving signatures through the REAL
+   `AttentionTopicGuard` and asserting allowed topics ≤ the budget, plus a suppression test.
+2. **Two §6 assertions were absent.** **Resolution (implemented):** non-telegram (slack) automated
+   send asserted to receive the jargon + filePath signals (with the slack route now threading
+   `metadata.messageKind`, mirroring telegram); the Tier-2-location nit (route tests under
+   `tests/unit/` driving a real express app) stands with this note.
+3. **(Disclosed, no action)** the 0.4 Jaccard fix-landing threshold can under-resolve a heavy
+   rewrite; bounded to NORMAL/budgeted items by resolution 1.
+
+**Re-confirmation (independent, after the iteration):** concur — "All three resolutions verified in
+code and tests against the real `AttentionTopicGuard` (35/35 green)"; the burst test was verified
+non-vacuous (a revert to HIGH fails both assertions). The one cosmetic nit (a stale test-header
+comment) was fixed in the same pass.
+
+---
+
+## Evidence pointers
+
+- `tests/unit/telegram-reply-advisory-script.test.ts` — the REAL shipped script under bash + recording
+  curl shim: NOT-SENT literal/exit-0, ack annotation, fail-open ×2, legacy-body byte-shape, ms→s clamp,
+  queue metadata on HTTP-000.
+- `tests/unit/raw-file-path.test.ts` (26) · `tests/unit/outbound-advisory.test.ts` (17) ·
+  `tests/unit/outbound-advisory-routes.test.ts` (15) · `tests/unit/pending-relay-metadata.test.ts` (4) ·
+  `tests/unit/relay-kind-forward.test.ts` (2) · spawn-env assertions in
+  `tests/unit/session-manager-behavioral.test.ts`.
+- `tests/e2e/outbound-advisory-alive.test.ts` (5) — production-init alive + auth + on-disk audit +
+  live kill switch.
+
+---
+
+## Post-CI follow-up (same PR)
+
+The no-silent-fallbacks ratchet (CI shard 3) correctly demanded that every spec-mandated fail-open
+catch be a TRACKED decision: all are now annotated `@silent-fallback-ok` with the spec-section
+justification (fail-open is the §0 operator constraint, not an accident), plus one documented
+scanner-window false positive on a pre-existing 500-responder catch. No behavior change.
+
+CI round 2: one source-inspection test (`slack-thread-session-wiring`) used a fixed 1600-char
+extraction window that the slack route's new messageKind threading overflowed — window widened to
+2400 with a comment naming the cause. No behavior change.

package/upgrades/side-effects/token-audit-completeness.md

@@ -0,0 +1,84 @@
+# Side-Effects Review — Token-Audit Completeness
+
+**Version / slug:** `token-audit-completeness`
+**Date:** `2026-06-11`
+**Author:** `echo (instar-dev agent)`
+**Second-pass reviewer:** `independent reviewer subagent (Phase 5 — change touches the funnel + a sentinel-adjacent tripwire)`
+
+## Summary of the change
+
+Implements docs/specs/token-audit-completeness.md (converged r6, operator-approved): codex judgment calls switch to `codex exec --json` with a streaming spawn helper (`spawnCodexExecJson` in `codexSpawn.ts`) so per-call token usage (in/out/cached) reaches the FeatureMetricsLedger; the funnel's error path now records already-burned tokens; `/metrics/features` gains a feature×model partition (`byModel`), per-framework `usageCoverage`, and unlabeled-spend shares; every previously-unattributed funnel callsite is tagged (`attribution.component`) and a new lint (`scripts/lint-llm-attribution.js`) + empty-baseline ratchet test keeps the baseline at zero; a `codex-usage-parse-drift` degradation tripwire (once per process) catches future parse rot; `appendAuditEntry` gains 16 MB rotation (the per-call SafeFs deletions make destructive-ops.jsonl hot-path). Files: `codexSpawn.ts`, `codexUsageParser.ts` (new), `CodexCliIntelligenceProvider.ts`, `ClaudeCliIntelligenceProvider.ts`, `CircuitBreakingIntelligenceProvider.ts`, `FeatureMetricsLedger.ts`, `SafeGitExecutor.ts`, `routes.ts`, `intelligenceProviderFactory.ts`, `server.ts`/`route.ts`/`reflect.ts` (closure threading), 8 tagged callsites, `componentCategories.ts`, `templates.ts`, `PostUpdateMigrator.ts`, `STANDARDS-REGISTRY.md`, lint + 8 test files.
+
+## Decision-point inventory
+
+- `CircuitBreakingIntelligenceProvider.evaluate` (the funnel) — **pass-through** — the breaker/shed/error decision logic is UNCHANGED; the error path *adds token fields to a row it already writes*, and an `unlabeled` row additionally fires a once-per-process signal event. No block/allow behavior changes.
+- `CodexCliIntelligenceProvider.evaluate` mode selection — **add (non-gating)** — chooses `--json` vs plain invocation per call via the kill-switch resolver. Both modes produce the same evaluate() contract; this selects a transport, it does not gate any caller.
+- `scripts/lint-llm-attribution.js` — **add (build-time only)** — blocks COMMITS (via `npm run lint`), never runtime actions. Deterministic structural validator (the explicitly-allowed class in signal-vs-authority's "when this does NOT apply").
+- DegradationReporter emissions (`codex-usage-parse-drift`, `unlabeled-llm-call`) — **add (signal-only)** — fixed constants, once per process, never block/delay/rewrite anything.
+- No gate, sentinel, watchdog, or recovery path changes its verdict logic anywhere in this change.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+- **Lint:** a funnel callsite whose attribution is injected via a helper-wrapper in a DIFFERENT file fails the lexical rule even though it is attributed at runtime. Sanctioned fix is inlining (documented in the lint header). Today's tree has zero such cases (full-repo lint is clean). A receiver named e.g. `myProvider` that is NOT an LLM provider would be flagged only if it also has an `.evaluate(` method and no attribution — no such case exists in src/ (verified by the clean run).
+- **Result-file 16 MB cap:** a legitimate >16 MB single codex answer would be rejected loudly. No instar judgment call expects answers near that size (the old path capped at 1 MB total stdout — the new cap is 16× looser than the previous behavior).
+- **Missing-file-after-exit-0 reject:** if a future codex omits the `--output-last-message` file for an empty answer, json mode rejects where plain mode resolved `''`. Documented asymmetry, decided in-spec: masking would hide argument rot (the worse failure). The kill-switch restores plain behavior per machine instantly.
+- No other rejection surface was added. **No further issue identified.**
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- **Lint lexical limits:** conditional attribution (`attribution: x ?? {component:'Y'}`) and wrapper indirection pass lexically without proving runtime attribution. Backstopped at runtime by the `unlabeled-llm-call` event + `unlabeledCallShare` metric (any escape is visible, just not commit-blocked).
+- **Usage truthfulness:** the parser trusts codex's self-reported `token_count` totals (clamped + reconciled). A codex that mis-reports usage in a self-consistent way passes reconciliation. Account-level `/codex/usage` remains the independent cross-check.
+- **Per-machine ledger:** pool-wide audit still requires reading each machine (pre-existing, noted in-spec).
+- **Wiring-test exclusions:** 18 pre-existing component labels remain unregistered in COMPONENT_CATEGORY (registering them changes live framework routing — deliberately out of scope). The pinned exclusion list prevents NEW ones; the existing ones still route to the default framework.
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?** Yes. Codex child mechanics stay in `transport/codexSpawn.ts` (the single home — no second spawn path in the provider; the helper is consumed, mirroring `spawnCodexAndWait`). Usage parsing is a pure module. Token recording rides the EXISTING funnel tap (no new parallel recording path). The per-model aggregation lives in the ledger (the only component that owns the SQL), and the route only composes. The lint follows the established `lint-no-direct-llm-http.js` shape. Audit rotation lives in `appendAuditEntry` itself, benefiting every SafeFs/SafeGit caller — not bolted onto the codex cleanup path.
+
+## 4. Signal vs authority compliance
+
+Compliant (re-checked against `docs/signal-vs-authority.md`):
+- The drift tripwire and unlabeled backstop are **signals** (DegradationReporter events + durable metrics) with zero blocking power.
+- The only blocking surface (the lint) is a deterministic build-time structural validator — the explicitly-exempt class ("hard-invariant validation" / enumerable domain), like the existing dark-gate and destructive lints. It gates commits, not judgments.
+- The funnel's breaker logic (the existing authority for shed decisions) is untouched.
+- Result extraction reads ONE file written by codex itself; stdout events are observability signal only and can never become the result (events-as-authority would have been the violation; the spec pinned this).
+
+## 5. Interactions
+
+- **onUsage contract widening** ("fires even on calls that subsequently reject"): the only funnel consumer composes caller callbacks; callers receive at most one extra invocation on failed codex calls. Claude's parse path is unchanged (still success-only by construction). pi unchanged. No double-fire: the accumulator finalizes exactly once (settlement contract unit-pinned).
+- **Audit-log rotation vs concurrent writers:** re-stat-immediately-before-rename shrinks the double-rotate window; worst case under a still-possible race is losing one predecessor segment, never the live log; the rotation-marker makes any rotation visible.
+- **Sweep vs live calls:** in-flight Set + 6h age threshold + own-uid lstat verification; cross-process race requires a >6h call (none exists).
+- **Duplicate sweep triggers:** rate floor set BEFORE the pass starts — concurrent evaluates can't double-trigger.
+- **lint-no-direct-destructive:** the new lint's read-only `git diff` execSync needed the standard bootstrap-escape allowlist entry (added with the standard comment).
+- **Contract-evidence gate (pre-push):** fired on SlackAdapter.ts even though this diff touches no Slack API surface (type widening + attribution tag on an internal LLM call) and no Slack token exists in the vault to run the live tier. Fixed the hook rather than bypassing it (instar-dev: "if the hook is genuinely broken, fix the hook"): `scripts/pre-push-gate.js` gains the same in-diff marker escape `check-e2e-pairing.cjs` already uses (`CONTRACT-EVIDENCE: EXEMPT — <reason>`), accepted only when EVERY changed adapter file carries the marker, logged loudly. Over-block resolved; under-block unchanged (real API edits still require live evidence — a marker on an API-changing diff would be visible to the PR reviewer next to the change it covers).
+- **lint-degradation-emit-sites** auto-discovers the two new `.report()` sites (verified: legacy count includes them; warning-only).
+- No shadowing/double-fire with BurnDetector: it reads attribution keys, which only get MORE populated.
+
+## 6. External surfaces
+
+- `/metrics/features` response is **additive** (new fields; existing fields unchanged) — existing consumers (dashboard LLM Activity tab, agents) keep working. The `?feature=` filter now also narrows `totals.byModel` (new field, so no consumer regression).
+- Codex child invocation changes (argv + stdin): kill-switch `intelligence.codexExecJson:false` / `INSTAR_CODEX_EXEC_JSON=0` restores today's invocation byte-for-byte; older CLIs (<0.20) fail loudly naming both levers. Live canary validated against the real installed codex CLI (real call, usage recorded).
+- CLAUDE.md template + migrateClaudeMd addendum (idempotent `unlabeledCallShare` sniff) + shadow-mirror markers: existing agents learn the new surface on update (Migration Parity). No config migration needed (absence = on, by design).
+- Timing dependence: the post-SIGTERM flush requires the child's TERM trap to run within the 2s SIGTERM→SIGKILL grace — when it doesn't, the error row simply carries the last pre-kill cumulative (degraded, never wrong-direction).
+
+## 7. Rollback cost
+
+- **Codex json mode:** per-machine config flip (30s TTL, no restart) or env var — instant, no release needed. When off, codex calls are token-blind again and `usageCoverage` reports it honestly (never silent).
+- **Lint/ratchet:** revert the PR (no data surface).
+- **Ledger column:** `tokens_cached` is an idempotent ALTER; rollback releases simply ignore the column (additive, no migration down needed).
+- **Audit rotation:** revert restores unbounded growth (the prior behavior); rotated `.1` segments remain readable on disk.
+- No agent state repair or data migration in any rollback path.
+
+---
+
+## Second-pass review
+
+**Concur with the review.** (Independent reviewer subagent, 2026-06-11.)
+
+> I independently verified the artifact against the code. (1) Signal-vs-authority holds: the only new blocking surfaces are the build-time lint (deterministic, full-repo run exits 0, allowlist seeded empty and pinned by the ratchet test) and the disclosed in-call rejections (missing result file after exit 0, 16 MB result cap) — both honestly documented in §1 with the per-machine kill-switch as the rollback; the drift tripwire and unlabeled backstop are once-per-process DegradationReporter emissions with zero blocking power, and the result authority is the `--output-last-message` file only (codexSpawn.ts events feed only the usage accumulator). (2) The funnel diff in CircuitBreakingIntelligenceProvider.ts is purely additive — error rows gain tokensIn/Out/Cached and the `unlabeled` signal fires in recordMetric; breaker/shed/error verdict logic is byte-untouched, matching the artifact's "pass-through" classification. (3) The spawn helper's settlement is single-settle by construction (`settled` flag guards close/exit-grace/error races), stdin EPIPE/ERR_STREAM_DESTROYED is absorbed, buffers are bounded (2 MB carry cap, 600-char stderr tail), the out-dir cleanup's try/finally cannot leak the in-flight Set entry, and the sweep's rate-floor/in-flight/lstat-uid brakes match the artifact's interaction claims — all new unit tests pass including timeout-mid-stream flush ordering, held-fd grace, and stderr-drain cases. The only theoretical residual found (a child whose `kill()` itself throws on both rungs could leave evaluate() unsettled) is the same hazard class the prior execFile path had and does not rise to a concern.