instar 1.3.304 → 1.3.306

package/upgrades/side-effects/sentinel-pause-length-guard.md

@@ -0,0 +1,43 @@
+# Side-Effects Review — MessageSentinel: long-message pause downgrade
+
+**Version / slug:** `sentinel-pause-length-guard`
+**Date:** `2026-06-05`
+**Author:** `instar-echo`
+
+## Summary
+
+New `downgradeLongPause()` applied to the LLM layer's result in `classify()`: a 'pause' classification on a message longer than `MAX_PAUSE_DIRECTIVE_WORDS` (25) becomes `normal`/pass-through, logged, with the original reason preserved inside the downgrade reason. Emergency-stop, redirect, and all short-message behavior unchanged.
+
+## Decision-point inventory
+
+- `MAX_PAUSE_DIRECTIVE_WORDS` — added (25) — a genuine natural-language pause directive is well under this; the two live victims were ~200 words.
+- `downgradeLongPause()` — added — pure function of (classification, message); only transforms `pause`.
+- `classify()` LLM branch — modified — result passes through the guard. Fast path untouched (its 4-word gate already excludes long messages from patterns; slash commands are exact-match short).
+- The forward-route intercept, pause action semantics, stats recording — untouched (stats record the post-downgrade category, which is the truthful one).
+
+## Direction of failure
+
+- Old failure: a long task message classified 'pause' was CONSUMED — session paused, content destroyed, no trace in any queue/ledger (the delivery stack's only loss path with zero record).
+- New behavior: long messages always deliver; only short messages can pause.
+- Conservative failure direction: content is preserved. The worst new case is a user writing a >25-word pause request that now passes through as conversation — the session still RECEIVES it and can comply conversationally; nothing is destroyed. Compare old worst case: silent destruction of instructions.
+
+## Side-effects checklist
+
+1. **Over-deliver (missed pause):** a verbose pause directive (>25 words) no longer auto-pauses. Mitigations already in place: the message is delivered (the agent reads "please pause" and can stop itself), and /pause + short forms still work. Pause is politeness, not safety — the safety category (emergency-stop) is untouched.
+2. **Under-deliver:** none — no path consumes more than before.
+3. **Asymmetry justification:** emergency-stop on a long message remains possible by design (the prompt's own safety-first rule: better to stop unnecessarily than continue destructively). Length-gating it would trade safety for content; not taken.
+4. **Level-of-abstraction fit:** the guard lives in MessageSentinel (the classifier), not the forward route (the consumer) — every consumer of classify() (route intercept, TelegramAdapter.processUpdate, /sentinel/classify API) gets the same corrected verdict; no consumer-side divergence.
+5. **Signal vs authority:** the LLM keeps proposing; the structural gate bounds its authority over the destructive action. Exactly the signal-vs-authority pattern.
+6. **External surfaces:** `/sentinel/classify` responses for long pause-ish messages change category to `normal` with an explanatory reason — truthful, observable, and carried in `/metrics/features` stats as the post-guard category.
+7. **Rollback cost:** revert the commit; no state, config, or migration.
+
+## Scope not taken
+
+- No change to emergency-stop classification (deliberate, documented asymmetry).
+- No configurability of the 25-word ceiling (constant; make it config only if a real false-negative shows up).
+- No retroactive recovery of the two eaten messages (both manually resent during diagnosis).
+- No prompt changes (the prompt's guidance stays as a first line; the guard is the backstop).
+
+## Rollback
+
+Revert the commit. Long messages classified 'pause' are consumed again.

package/upgrades/side-effects/template-agent-id-header.md

@@ -0,0 +1,48 @@
+# Side-Effects Review — Template Agent-ID Header
+
+**Version / slug:** `template-agent-id-header`
+**Date:** `2026-06-05`
+**Author:** `instar-codey`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+This change updates the fleet-installed local API client surface so bearer-authenticated template calls also send `X-Instar-AgentId`. It adds `INSTAR_AGENT_ID` env propagation from `Config` -> `JobScheduler` and `SessionManager`, updates built-in job templates, hook/script templates, and selected migrator inline hook content, and adds a template scanner regression test.
+
+## Decision-point inventory
+
+No new decision point is added. Existing server auth remains the authority for missing/mismatched agent-id headers. This change only updates clients/templates to provide identity to that existing authority.
+
+## 1. Over-block
+
+No block/allow surface is added. A malformed or missing `projectName` could make a template send an empty or wrong `X-Instar-AgentId`, which the existing server auth would reject. The normal paths use `config.projectName`, and direct-run fallbacks read the same field.
+
+## 2. Under-block
+
+This does not remove the server's bearer-only compatibility window. A custom user-authored curl outside shipped templates can still be bearer-only and receive the deprecation warning until the server policy changes.
+
+## 3. Level-of-abstraction fit
+
+The fix sits at the client/template layer. The server already owns auth authority and should not be weakened to hide template warnings. Scheduler/session env propagation is the right shared primitive for jobs and hooks.
+
+## 4. Signal vs authority compliance
+
+Required reference: `docs/signal-vs-authority.md`
+
+No brittle blocking authority is introduced. The change feeds identity into the existing deterministic auth authority; it does not add a new detector or gate.
+
+## 5. Interactions
+
+The scheduler now injects `INSTAR_AGENT_ID` alongside `INSTAR_AUTH_TOKEN` for gate and script job shells. `SessionManager` injects the same variable for spawned sessions, so hook and prompt-job examples have it. Fleet watchdog peer requests read the peer project name and bind the peer token to the peer identity.
+
+## 6. External surfaces
+
+Installed agents get quieter logs and future-compatible local API calls after template refresh/migration. No public API response shapes change. No persistent state is written.
+
+## 7. Rollback cost
+
+Rollback is a source/template revert and patch release. Existing agents would fall back to the current accepted-but-deprecated bearer-only behavior until a corrected template ships.
+
+## Conclusion
+
+Clear to ship as Tier 1. The change aligns installed templates with the existing auth contract and pins the class with a scanner test.