instar 1.3.319 → 1.3.321

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-05T20:42:29.342Z",
-  "instarVersion": "1.3.319",
+  "generatedAt": "2026-06-05T22:14:45.187Z",
+  "instarVersion": "1.3.321",
   "entryCount": 199,
   "entries": {
     "hook:session-start": {
@@ -778,7 +778,7 @@
       "type": "cli-command",
       "domain": "setup",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:setup": {
@@ -786,7 +786,7 @@
       "type": "cli-command",
       "domain": "setup",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:add": {
@@ -794,7 +794,7 @@
       "type": "cli-command",
       "domain": "setup",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:backup": {
@@ -802,7 +802,7 @@
       "type": "cli-command",
       "domain": "operations",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:git": {
@@ -810,7 +810,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:memory": {
@@ -818,7 +818,7 @@
       "type": "cli-command",
       "domain": "memory",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:knowledge": {
@@ -826,7 +826,7 @@
       "type": "cli-command",
       "domain": "memory",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:semantic": {
@@ -834,7 +834,7 @@
       "type": "cli-command",
       "domain": "memory",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:intent": {
@@ -842,7 +842,7 @@
       "type": "cli-command",
       "domain": "intent",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:feedback": {
@@ -850,7 +850,7 @@
       "type": "cli-command",
       "domain": "feedback",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:server": {
@@ -858,7 +858,7 @@
       "type": "cli-command",
       "domain": "server",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:status": {
@@ -866,7 +866,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:user": {
@@ -874,7 +874,7 @@
       "type": "cli-command",
       "domain": "users",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:relationship": {
@@ -882,7 +882,7 @@
       "type": "cli-command",
       "domain": "relationships",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:job": {
@@ -890,7 +890,7 @@
       "type": "cli-command",
       "domain": "scheduling",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:lifeline": {
@@ -898,7 +898,7 @@
       "type": "cli-command",
       "domain": "communication",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:list": {
@@ -906,7 +906,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:autostart": {
@@ -914,7 +914,7 @@
       "type": "cli-command",
       "domain": "operations",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:migrate": {
@@ -922,7 +922,7 @@
       "type": "cli-command",
       "domain": "updates",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:machines": {
@@ -930,7 +930,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:whoami": {
@@ -938,7 +938,7 @@
       "type": "cli-command",
       "domain": "identity",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:pair": {
@@ -946,7 +946,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:join": {
@@ -954,7 +954,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:wakeup": {
@@ -962,7 +962,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:leave": {
@@ -970,7 +970,7 @@
       "type": "cli-command",
       "domain": "coordination",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:doctor": {
@@ -978,7 +978,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:review": {
@@ -986,7 +986,7 @@
       "type": "cli-command",
       "domain": "monitoring",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:nuke": {
@@ -994,7 +994,7 @@
       "type": "cli-command",
       "domain": "operations",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:playbook": {
@@ -1002,7 +1002,7 @@
       "type": "cli-command",
       "domain": "context",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:dev-preflight": {
@@ -1010,7 +1010,7 @@
       "type": "cli-command",
       "domain": "development",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:dev-ci-failures": {
@@ -1018,7 +1018,7 @@
       "type": "cli-command",
       "domain": "development",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "cli:dev-profile-node": {
@@ -1026,7 +1026,7 @@
       "type": "cli-command",
       "domain": "development",
       "sourcePath": "src/cli.ts",
-      "contentHash": "e4f500dbdb5e986b90f211b0890134effbc477a7d123a2f9282c6082fa87ae66",
+      "contentHash": "189bf25909698ef7aeeaa7b59dc8b737096bcaa64ff32e693f63c4654c311032",
       "since": "2025-01-01"
     },
     "template:build-stop-hook.sh": {
@@ -1162,7 +1162,7 @@
       "type": "template",
       "domain": "operations",
       "sourcePath": "src/templates/scripts/instar-watchdog.sh",
-      "contentHash": "5bd48e727691adcb9e1aaee2d61af192f54ed6d1244ca1931422a5926c7d9d10",
+      "contentHash": "207d3cf08ac5bd1030dd35f6d30f472aef9c087e5635e23d92bd574d6291af6b",
       "since": "2025-01-01"
     },
     "template:instar-worktree-create.sh": {
@@ -1514,7 +1514,7 @@
       "type": "subsystem",
       "domain": "sessions",
       "sourcePath": "src/core/SessionManager.ts",
-      "contentHash": "a6cf21efd904fb1c7d274d03c92ef7c368f14de8471242905f9a78ad43da47d5",
+      "contentHash": "90f71f02aaeac3edcf5cd62d854b74e35ed77fd257e351d55f4391f9bb9cfa8b",
       "since": "2025-01-01"
     },
     "subsystem:auto-updater": {

package/src/templates/scripts/instar-watchdog.sh

@@ -468,7 +468,11 @@ probe_server_identity() {
   if [ -n "$auth_token" ]; then
     auth_args=(-H "Authorization: Bearer $auth_token" -H "X-Instar-AgentId: $agent_id")
   fi
-  resp=$(curl -sS --max-time 5 -w '\n%{http_code}' "${auth_args[@]}" "http://localhost:${port}/health" 2>/dev/null || echo $'\n000')
+  if [ -n "$auth_token" ]; then
+    resp=$(curl -sS --max-time 5 -w '\n%{http_code}' "${auth_args[@]}" "http://localhost:${port}/health" 2>/dev/null || echo $'\n000')
+  else
+    resp=$(curl -sS --max-time 5 -w '\n%{http_code}' "http://localhost:${port}/health" 2>/dev/null || echo $'\n000')
+  fi
   http_code=$(echo "$resp" | tail -n1)
   body=$(echo "$resp" | sed '$d')
 

package/upgrades/1.3.320.md

@@ -0,0 +1,20 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The SessionManager age-gate (the 5-second monitor tick) used to re-request a kill for an over-age, idle-at-prompt session on EVERY tick. When the §P2 KEEP-guard correctly vetoed that kill (the session had a recent user message, was topic-bound, or held an open commitment), the session survived — but the gate re-asked 5 seconds later, forever. On 2026-06-05 this produced 17,503 identical kill-request log lines for kept sessions plus the wasted CPU that read as "heavy load." A new pure, bounded `AgeKillBackoff` ledger makes the age-gate RESPECT the guard's verdict: after a veto it suppresses re-requests for `ageKillBackoffMinutes` (default 10) — ~6 asks/hour instead of 720 — collapsing to ONE informative log line. It changes only how OFTEN the age-gate asks, never WHICH sessions die: the KEEP-guard remains the sole authority, and a genuinely-abandoned session (no keep-reason) still dies on the first ask exactly as before.
+
+## What to Tell Your User
+
+Your long-lived working sessions no longer get hammered by a kill-request loop they always survive — the churn (and the log/CPU noise it caused) is gone, while nothing about which sessions actually get cleaned up has changed.
+
+## Summary of New Capabilities
+
+- Age-gate kill back-off: a vetoed kill is honored for a back-off window instead of being re-asked every tick. Tunable via `ageKillBackoffMinutes` in config (default 10; `0` restores the legacy every-tick behavior). Existing agents get the fix automatically on update — the default lives in code, no config migration required.
+
+## Evidence
+
+Live incident 2026-06-05: 17,503 identical "Requesting kill"/deferral lines for over-age sessions (this conversation's topic plus three other long-lived sessions), every one correctly vetoed by the KEEP-guard — wasted CPU that surfaced to the operator as "resource issues." Root cause: the age-gate at `SessionManager.monitorTick` re-requested a kill every 5s with no memory of the prior veto. Fix: `src/core/AgeKillBackoff.ts` (pure, injectable clock, bounded `maxTracked` memory, mirrors `AttentionTopicGuard`), wired into the age-gate to `recordVeto`/`recordKilled` and gate re-asks via `shouldRequest`. Spec `docs/specs/age-kill-backoff.md` (converged + approved). Tests: 11 green — 7 unit (incl. a 720→6 asks/hour regression pin) + 4 integration against the real SessionManager ledger; tsc clean.

package/upgrades/1.3.321.md

@@ -0,0 +1,25 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Instar now has a post-drive transcript auditor for operator-seat UX review. Given topic ids and a drive window, it reads the existing topic message history, classifies duplicate notices or deliveries, resend or retry asks, internal infrastructure noise, and content-free status updates, then files each finding into the framework issue ledger with a stable dedupe key.
+
+The framework issue ledger also now preserves related-spec citations when observations are recorded, so findings can keep their link to Observation Needs Structure and the UX-blindspot work instead of losing that context after the write.
+
+## What to Tell Your User
+
+I can now audit a supervised Telegram drive after it happens and turn visible friction into durable findings instead of leaving it buried in chat.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Post-drive transcript UX audit | Run the new developer audit command with topic ids and a time window. |
+| Framework issue citations | Automatic when an observation includes a parent-principle or related-spec citation. |
+
+## Evidence
+
+Live fixture verification used topics 2278 and 2271 for the 11:15-11:21 PDT window on 2026-06-05. Dry-run first reported one duplicate-delivery group and two content-free status-notice groups after the ACK false positive was removed. Filing mode then wrote three framework issue observations with stable dedupe keys; rerunning the command deduped them instead of creating duplicates. Targeted tests passed for 50 cases across the auditor and framework issue ledger suites, build passed, lint passed, and the Tier-1 dev gate accepted the ELI16 plus side-effects artifacts.

package/upgrades/side-effects/age-kill-backoff.md

@@ -0,0 +1,75 @@
+# Side-Effects Review — Age-Timeout Kill Back-off
+
+**Version / slug:** `age-kill-backoff`
+**Date:** `2026-06-05`
+**Author:** `Echo (instar-dev agent)`
+**Second-pass reviewer:** `independent reviewer subagent — CONCUR (with one non-blocking accuracy fix, since applied)`
+
+## Summary of the change
+
+The `SessionManager` age-gate (`monitorTick`, runs every 5s) used to re-request a kill for an over-age, idle-at-prompt session on every tick. When the §P2 KEEP-guard inside `terminateSession` vetoed the kill (returning `{ terminated:false, skipped:<reason> }` for a session with a recent user message / topic binding / open commitment), the session survived but the gate threw away that verdict and re-asked 5s later — forever (the 2026-06-05 17,503-line flood + wasted CPU read as "heavy load"). This change adds a pure, bounded back-off ledger (`src/core/AgeKillBackoff.ts`) and wires it into the age-gate (`src/core/SessionManager.ts`): after a veto, `recordVeto` suppresses re-requests for `ageKillBackoffMinutes` (default 10, new optional field on `SessionManagerConfig` in `src/core/types.ts`); `shouldRequest` gates the re-ask; `recordKilled` cleans up on an actual kill. Files touched: `AgeKillBackoff.ts` (new), `SessionManager.ts` (import + construct + gate the age-kill branch), `types.ts` (one optional config field). Decision point: the age-gate's kill-request *frequency* only — never the kill *decision* itself.
+
+## Decision-point inventory
+
+- `SessionManager.monitorTick age-gate` — **modify** — gates how OFTEN it re-requests a kill for a kept over-age session; does not change the kill predicate.
+- `§P2 KEEP-guard inside terminateSession` — **pass-through** — unchanged; remains the sole authority over WHICH sessions die. The back-off only consumes its verdict.
+- `AgeKillBackoff ledger` — **add** — a pure signal-suppressor (no kill authority of its own).
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+The only thing "suppressed" is a redundant *kill request* for a session the guard ALREADY decided to keep within the last `backoffMs`. It never suppresses a kill of a genuinely-reapable session: a session is only in back-off because its most recent kill request was vetoed (kept). The one edge worth naming: a session kept at T0 whose keep-reason lapses at T0+1min is not re-evaluated until the back-off window expires (≤10min) — so a now-abandoned session lingers at most ~10 extra minutes before its first re-ask. That is a delay in *cleanup of an idle session*, not an over-block of any live work, and it is bounded and reversible (`ageKillBackoffMinutes: 0` restores instant re-checks). Note a re-engaged session needs no special handling: its new injection makes it non-idle, so the age-gate takes its active-work branch (never the kill branch) — it is never age-killed while active regardless of the back-off window. (`reset()`/`clear()` exist as ledger-maintenance API exercised by the unit suite but are intentionally NOT wired into the injection/removal paths in this PR — they would be redundant given the active-work branch, and memory is already bounded by `maxTracked` eviction.)
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+It does not unify the two redundant mechanisms (the crude age-gate and the sophisticated `SessionReaper`) — that larger refactor is tracked separately (spec §Follow-up, topic-18423). It also does not change the age THRESHOLD (still `maxDurationMinutes + 20%`); a mis-tuned threshold would still mis-classify, just without the flood. Neither is a regression — both are pre-existing and out of this fix's stated scope. A `backoffMs` set absurdly high by an operator would delay legitimate cleanup of abandoned sessions, but the KEEP-guard still gates the eventual kill, so nothing dies wrongly.
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. It is a low-level, deterministic suppressor sitting at the exact layer that was generating the redundant requests (the age-gate inside `monitorTick`). It deliberately does NOT re-implement the reap decision — it consumes the existing authority's verdict. It mirrors the established `AttentionTopicGuard` pattern (pure logic, injectable clock, bounded memory) rather than inventing a new shape. The smarter authority (`terminateSession`/KEEP-guard) already exists and is FED by this, not duplicated.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** `docs/signal-vs-authority.md`
+
+- [x] No — this change produces a signal (a "stop asking for now" suppressor) consumed by / feeding the existing smart authority; it holds NO kill authority.
+
+The back-off ledger cannot kill anything. It can only make the age-gate *skip a redundant request*. The kill decision remains 100% with `terminateSession`'s KEEP-guard, which has the full multi-signal context. Brittle-detector-with-block-authority is explicitly avoided: the brittle part (an age timer) was ALREADY there; this change strictly *reduces* how often that brittle part speaks, and routes nothing past the smart authority.
+
+## 5. Interactions
+
+- **Shadowing:** The `!shouldRequest` branch falls through to the existing idle-detection block exactly as the prior code path did on a kept session — it does not shadow idle detection or any other monitor check. Verified in the diff: the new `else if` sits between the active-work branch and the kill branch and `continue`s to the same place.
+- **Double-fire:** No. Two paths exist (`terminated` → `recordKilled`; `!terminated` → `recordVeto`) and they are mutually exclusive on a single `terminateSession` result. No other component writes the ledger.
+- **Races:** The ledger is a plain in-process `Map` touched only from the single-threaded `monitorTick` loop (`shouldRequest`/`recordVeto`/`recordKilled`) — no cross-thread/async sharing, and no write from the injection path. Bounded by `maxTracked` (1024) with oldest-eviction, so it cannot grow unbounded even across thousands of session ids; a stale entry for a removed session id self-evicts and is harmless (that id never returns).
+- **Feedback loops:** None. Suppressing a request cannot change whether the guard would keep the session; it only changes cadence.
+
+## 6. External surfaces
+
+- **Other agents / users:** None directly. The behavior ships to every agent on update, but the only observable change is *fewer* log lines and *less* wasted CPU — strictly a reduction in noise. No API, message, or schema surface changes.
+- **External systems:** None (no Telegram/Slack/GitHub/Cloudflare interaction).
+- **Persistent state:** None. The ledger is in-memory only; nothing is written to disk, no migration, no new column.
+- **Logs (the intended visible change):** the per-tick "Requesting kill" flood for kept sessions collapses to ONE "over age but KEPT (reason); backing off re-checks" line per back-off window. Operators / log scrapers keying on the old high-volume line will see far fewer of them — a benign reduction.
+- **Timing:** Introduces a bounded ≤`backoffMs` delay before re-checking a kept-then-lapsed session (analyzed in §1).
+
+## 7. Rollback cost
+
+Pure in-process code change. Back-out = revert the commit and ship a patch, OR set `ageKillBackoffMinutes: 0` in config (instant per-agent disable, restoring exact legacy every-tick behavior with no restart-coupled migration). No persistent state to clean up, no agent-state repair, no user-visible regression during the rollback window (the only difference users could notice is the log flood returning).
+
+## Conclusion
+
+This review produced no design changes — the implementation already matched the converged spec's signal-not-authority shape. The review confirmed: (a) the KEEP-guard remains the sole kill authority (no over-block of live work; at most a bounded ≤10min delay in cleaning up a session whose keep-reason just lapsed), (b) no persistent state / external surface / race, and (c) a trivial dual rollback (revert or `ageKillBackoffMinutes:0`). Migration parity is met by the in-code default, consistent with the sibling `defaultMaxDurationMinutes` dial (neither is in `migrateConfig`). Because this touches session lifecycle (kill path), a Phase-5 second-pass reviewer audit is required before commit; this artifact awaits that concurrence.
+
+---
+
+## Phase 5 — Second-pass review (session-lifecycle change → required)
+
+An independent reviewer subagent audited the diff, spec, artifact, and both test files at line level, specifically probing whether the back-off could ever prevent a genuinely-abandoned session from being killed, ledger memory safety, veto/kill mutual-exclusion, the `!shouldRequest` fall-through, and migration safety.
+
+**Verdict: Concur with the review.** The core safety invariants hold under line-level inspection: `recordVeto` is only reachable when `terminateSession` returns `terminated:false`, so a no-keep-reason session is never backed off and dies on its first ask; the `!shouldRequest` branch falls through to the fully independent idle-detection / idle-zombie kill path, so a genuinely-abandoned backed-off session is still reaped; `recordVeto`/`recordKilled` are mutually exclusive on one result (no ledger corruption); the `Map` is bounded by `maxTracked` oldest-eviction; and the in-code default safely mirrors the sibling `defaultMaxDurationMinutes` with no migration needed. The change alters only the FREQUENCY of asking, never WHICH sessions die.
+
+**One non-blocking accuracy defect raised — and fixed:** the reviewer noted that the spec (Design step 3) and this artifact (§1/§5) originally claimed `reset()` was wired into the injection path and `clear()` on session removal, but neither is actually called in production (they are API exercised only by the unit suite). Practical impact was nil (a re-engaged session is already protected by the age-gate's active-work branch; memory is bounded by eviction), but the docs were inaccurate. Resolution: the spec and this artifact were corrected to state accurately that `reset()`/`clear()` are unwired maintenance API and that a re-engaged session is protected by the active-work branch — the implementation was left as-is (wiring `reset()` across the tmux→session.id key boundary would add risk for zero behavioral benefit, per the reviewer's own analysis). Spec and code now agree.

package/upgrades/side-effects/hermetic-unit-suite.md

@@ -0,0 +1,69 @@
+# Side-Effects Review — Hermetic local unit suite
+
+**Version / slug:** `hermetic-unit-suite`
+**Date:** `2026-06-05`
+**Author:** `instar-codey`
+**Second-pass reviewer:** `not required — Tier-1 patch; watchdog template path reviewed here`
+
+## Summary of the change
+
+This change makes local unit-suite evidence hermetic on a live-agent Node 25 developer box. It touches `src/templates/scripts/instar-watchdog.sh`, `tests/unit/Config.test.ts`, and `tests/unit/coherence-gate-escalation.test.ts`. The source change fixes the existing watchdog no-auth health probe so it calls curl without auth arguments when no auth token exists. The test changes pin framework-specific config fixtures and make package export checks static so full-suite load does not turn a valid export check into a timeout.
+
+## Decision-point inventory
+
+- `probe_server_identity` in `src/templates/scripts/instar-watchdog.sh` — modify — preserves the existing server identity decision, but corrects the no-auth request path so auth headers are only supplied when an auth token exists.
+- `Config.test.ts` fixture framework selection — modify — test-only fixture isolation; no production decision point.
+- `coherence-gate-escalation.test.ts` export verification — modify — test-only import strategy; no production decision point.
+
+## 1. Over-block
+
+No new block/allow surface is added. The watchdog already decided whether server identity was same-project, wrong-project, unreachable, or indeterminate; this patch only makes the unauthenticated curl invocation match the "no token" branch. There is no new legitimate input rejected by this change.
+
+## 2. Under-block
+
+This does not attempt to make every unit test hermetic in perpetuity. It fixes the local-red failures observed in this run: real-config/framework leakage, live tunnel leakage already addressed on current main, Node 25 native-module setup, the watchdog no-auth script bug, and the export-test timeout. Future tests can still leak live machine state if they read real config or network state without fixtures; that remains a suite hygiene class, not a new runtime gap introduced here.
+
+## 3. Level-of-abstraction fit
+
+The watchdog fix is at the right layer: the bug is in the shell template's curl argument construction, so the correction belongs in the shipped template rather than in the unit test. The config and export changes are correctly test-local: they do not ask production code to grow a seam just to satisfy this suite. Current main already provides the tunnel-provider and worktree cwd seams that absorbed the earlier tunnel/worktree local-reds, so this patch does not duplicate those abstractions.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — this change has no new block/allow surface.
+
+The watchdog path has existing operational authority to classify the server it probes, but this patch does not add a brittle new authority. It removes an accidental argument-shape dependency in the existing probe. The other two files are tests and have no runtime authority.
+
+## 5. Interactions
+
+- **Shadowing:** The watchdog no-auth branch now bypasses `auth_args` entirely when no token exists. It does not shadow the authenticated path; the authenticated path is unchanged.
+- **Double-fire:** No new timers, retries, or events are introduced.
+- **Races:** No persistent state or concurrent path changes are introduced. The generated `src/data/builtin-manifest.json` was primed locally by the manifest test and remains ignored.
+- **Feedback loops:** No release/update/job feedback loop changes.
+
+## 6. External surfaces
+
+Existing installed agents receive the corrected watchdog template when the template is shipped and applied. The visible behavior is narrower and intended: a no-auth probe should be genuinely no-auth. There is no database migration, ledger write, config-field change, public API change, or Telegram/Slack surface change. The local Node 25 dependency repair required `npm install --include=dev` on the dev box, but it did not modify `package.json` or `package-lock.json`.
+
+## 7. Rollback cost
+
+Rollback is a normal hot-fix revert. The source change is a shell-template branch, and the test changes are fixture/import isolation only. No persistent state is written, and no existing agent state needs repair. If the watchdog change were wrong, reverting it restores the prior curl invocation shape.
+
+## Conclusion
+
+The change is clear to ship as Tier 1. It fixes one real watchdog script bug and isolates two unit-suite failures without skipping tests, suppressing failures, or weakening assertions. The full unit-only run on the live-agent Node 25 box had one failure: a generated built-in manifest was stale because source was dirty; the manifest test regenerated that ignored file and its immediate rerun passed. Focused post-rebase validation passed on the edited/failure-class files.
+
+## Second-pass review (if required)
+
+**Reviewer:** not required for this Tier-1 patch.
+**Independent read of the artifact:** not run.
+
+The watchdog surface is documented above because it is the only runtime path touched. No new watchdog decision or recovery authority was added.
+
+## Evidence pointers
+
+- Full unit-only local run: 1,241/1,242 files passed; 23,548/23,549 tests passed. The only failure was `tests/unit/builtin-manifest.test.ts` because the generated ignored manifest was stale after source changes.
+- Targeted manifest rerun after local generation: `tests/unit/builtin-manifest.test.ts` passed, 9/9.
+- Focused post-rebase run: `AgentWorktreeDetector`, `Config`, `TunnelManager`, `watchdog-bind-probe`, `index-exports`, `coherence-gate-escalation`, and `builtin-manifest` passed, 124/124.
+- Claim-check: path advisory found merged PR #842 on the watchdog template and many keyword specs, with no open sibling claim requiring a different layer.

package/upgrades/side-effects/post-drive-transcript-audit.md

@@ -0,0 +1,64 @@
+# Side-Effects Review - post-drive transcript auditor
+
+**Version / slug:** `post-drive-transcript-audit`
+**Date:** `2026-06-05`
+**Author:** `instar-codey`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+This change adds a standalone post-drive transcript auditor and CLI command. It reads existing topic message history for specified topics and a time window, classifies operator-seat UX antipatterns, prints a structured report, and writes each finding to the existing framework issue ledger. It also fixes the ledger so a `relatedSpec` citation passed to the write path is persisted on new issues or backfilled on later matching observations.
+
+## Decision-point inventory
+
+- `classifyTranscriptUx` - add - deterministic signal classifier for transcript messages.
+- `runPostDriveTranscriptAudit` - add - decides whether to file each classified finding, with dry-run support.
+- Framework issue ledger `recordObservation` - modify - preserves related-spec citation metadata; no new authority or route.
+
+## 1. Over-block
+
+No block/allow surface - over-block is not applicable. The auditor can produce false-positive findings, but those are ledger signals for review, not user-message blocks.
+
+The main false-positive risk is classifying a legitimate short status message as content-free. The live fixture dry-run exposed this for normal acknowledgements, so the heuristic was narrowed to repeated/status chatter such as "actively working", "still working", or "no terminal output", and repeated identical notices are grouped.
+
+## 2. Under-block
+
+The auditor still misses UX issues that require deeper conversational interpretation. For example, it will not detect a polite but confusing request unless it contains resend/retry/re-paste language, and it will not detect subtle infrastructure leakage unless it uses the configured infrastructure terms. That is acceptable for this slice because the output is a structured starting signal, not a mentor judgment loop.
+
+The message-history route currently returns a bounded recent history. A large topic with more than the cap between the drive window and audit time could under-report old messages. The command makes the limit explicit and clamps it to the existing server cap; a future slice can add a broader archival reader if needed.
+
+## 3. Level-of-abstraction fit
+
+This is intentionally a low-level detector. It belongs after a drive, not in the live send path, because it is looking for transcript evidence to file. It does not duplicate the tone gate or messaging authority; it feeds the framework issue ledger with evidence pointers so later human or process review has a durable artifact.
+
+The ledger citation fix is at the right layer because the route already accepted `relatedSpec`; losing it inside the storage layer meant callers could do the right thing and still end up with a blind record.
+
+## 4. Signal vs authority compliance
+
+- [x] No - this change produces a signal consumed by an existing ledger.
+- [ ] No - this change has no block/allow surface.
+- [ ] Yes - but the logic is a smart gate with full conversational context.
+- [ ] Yes, with brittle logic - STOP.
+
+The classifier is deliberately brittle and therefore holds no authority. It cannot block, retry, resend, escalate, or alter a transcript. Its only side effect is filing reviewable observations with stable dedupe keys.
+
+## 5. Interactions
+
+- **Shadowing:** no live messaging check is shadowed. The command runs manually after the drive and reads existing history.
+- **Double-fire:** repeated runs file the same canonical issue because the dedupe key includes topic, window, category, and message evidence. The live fixture was run twice; the second write deduped.
+- **Races:** the only shared state is the framework issue ledger. The ledger already owns SQLite write serialization and episode dedupe.
+- **Feedback loops:** there is no mentor judgment loop. Findings do not automatically alter future classifications or message behavior.
+
+## 6. External surfaces
+
+The command reads local server topic history and writes to the local framework issue ledger. That creates persistent state: open framework issue rows and observations. The live fixture run filed three observations for topics 2278 and 2271 in the 11:15-11:21 PDT window. Because the running server still had the pre-fix ledger code loaded, those three rows were updated directly with the related-spec citation after the code fix; future runs through this PR path persist it normally.
+
+No Telegram messages are sent by the command. No GitHub, Cloudflare, or third-party systems are called. The CLI output can include short excerpts, so operators should treat reports as local/private unless deliberately published.
+
+## 7. Rollback cost
+
+Code rollback is a normal revert. The command is additive, and removing it does not affect live messaging. The ledger citation change is backward-compatible: it only fills an existing nullable column. If a filed observation is wrong, the durable record can be closed, marked fixed, or superseded through the existing ledger workflow; no schema rollback is needed.
+
+## Conclusion
+
+This slice is clear to ship as Tier 1. It adds a narrow, post-drive observation tool; keeps classification signal-only; files findings through the existing ledger; and fixes the storage bug that would otherwise erase the parent-principle citation required by the UX-blindspot work.