instar 1.3.260 → 1.3.262

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-05T00:51:15.949Z",
-  "instarVersion": "1.3.260",
+  "generatedAt": "2026-06-05T01:40:01.762Z",
+  "instarVersion": "1.3.262",
   "entryCount": 198,
   "entries": {
     "hook:session-start": {
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "b97e0a63b1003f867891c195c2df5968744f22b1437db56888305d053eee50fd",
+      "contentHash": "7b24d5f0ce709b9b960d78d17a92d2cb24ad6319175d2edd1e3ffef17f30ba80",
       "since": "2025-01-01"
     },
     "hook:dangerous-command-guard": {
@@ -20,7 +20,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/dangerous-command-guard.sh",
-      "contentHash": "b97e0a63b1003f867891c195c2df5968744f22b1437db56888305d053eee50fd",
+      "contentHash": "7b24d5f0ce709b9b960d78d17a92d2cb24ad6319175d2edd1e3ffef17f30ba80",
       "since": "2025-01-01"
     },
     "hook:grounding-before-messaging": {
@@ -29,7 +29,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/grounding-before-messaging.sh",
-      "contentHash": "b97e0a63b1003f867891c195c2df5968744f22b1437db56888305d053eee50fd",
+      "contentHash": "7b24d5f0ce709b9b960d78d17a92d2cb24ad6319175d2edd1e3ffef17f30ba80",
       "since": "2025-01-01"
     },
     "hook:compaction-recovery": {
@@ -38,7 +38,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/compaction-recovery.sh",
-      "contentHash": "b97e0a63b1003f867891c195c2df5968744f22b1437db56888305d053eee50fd",
+      "contentHash": "7b24d5f0ce709b9b960d78d17a92d2cb24ad6319175d2edd1e3ffef17f30ba80",
       "since": "2025-01-01"
     },
     "hook:external-operation-gate": {
@@ -47,7 +47,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-operation-gate.js",
-      "contentHash": "b97e0a63b1003f867891c195c2df5968744f22b1437db56888305d053eee50fd",
+      "contentHash": "7b24d5f0ce709b9b960d78d17a92d2cb24ad6319175d2edd1e3ffef17f30ba80",
       "since": "2025-01-01"
     },
     "hook:deferral-detector": {
@@ -56,7 +56,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/deferral-detector.js",
-      "contentHash": "b97e0a63b1003f867891c195c2df5968744f22b1437db56888305d053eee50fd",
+      "contentHash": "7b24d5f0ce709b9b960d78d17a92d2cb24ad6319175d2edd1e3ffef17f30ba80",
       "since": "2025-01-01"
     },
     "hook:self-stop-guard": {
@@ -65,7 +65,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/self-stop-guard.js",
-      "contentHash": "b97e0a63b1003f867891c195c2df5968744f22b1437db56888305d053eee50fd",
+      "contentHash": "7b24d5f0ce709b9b960d78d17a92d2cb24ad6319175d2edd1e3ffef17f30ba80",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -74,7 +74,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "b97e0a63b1003f867891c195c2df5968744f22b1437db56888305d053eee50fd",
+      "contentHash": "7b24d5f0ce709b9b960d78d17a92d2cb24ad6319175d2edd1e3ffef17f30ba80",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -83,7 +83,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "b97e0a63b1003f867891c195c2df5968744f22b1437db56888305d053eee50fd",
+      "contentHash": "7b24d5f0ce709b9b960d78d17a92d2cb24ad6319175d2edd1e3ffef17f30ba80",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-collector": {
@@ -92,7 +92,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "b97e0a63b1003f867891c195c2df5968744f22b1437db56888305d053eee50fd",
+      "contentHash": "7b24d5f0ce709b9b960d78d17a92d2cb24ad6319175d2edd1e3ffef17f30ba80",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -101,7 +101,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "b97e0a63b1003f867891c195c2df5968744f22b1437db56888305d053eee50fd",
+      "contentHash": "7b24d5f0ce709b9b960d78d17a92d2cb24ad6319175d2edd1e3ffef17f30ba80",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -110,7 +110,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "b97e0a63b1003f867891c195c2df5968744f22b1437db56888305d053eee50fd",
+      "contentHash": "7b24d5f0ce709b9b960d78d17a92d2cb24ad6319175d2edd1e3ffef17f30ba80",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -119,7 +119,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "b97e0a63b1003f867891c195c2df5968744f22b1437db56888305d053eee50fd",
+      "contentHash": "7b24d5f0ce709b9b960d78d17a92d2cb24ad6319175d2edd1e3ffef17f30ba80",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -128,7 +128,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "b97e0a63b1003f867891c195c2df5968744f22b1437db56888305d053eee50fd",
+      "contentHash": "7b24d5f0ce709b9b960d78d17a92d2cb24ad6319175d2edd1e3ffef17f30ba80",
       "since": "2025-01-01"
     },
     "hook:stop-gate-router": {
@@ -137,7 +137,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/stop-gate-router.js",
-      "contentHash": "b97e0a63b1003f867891c195c2df5968744f22b1437db56888305d053eee50fd",
+      "contentHash": "7b24d5f0ce709b9b960d78d17a92d2cb24ad6319175d2edd1e3ffef17f30ba80",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -146,7 +146,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "b97e0a63b1003f867891c195c2df5968744f22b1437db56888305d053eee50fd",
+      "contentHash": "7b24d5f0ce709b9b960d78d17a92d2cb24ad6319175d2edd1e3ffef17f30ba80",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1530,7 +1530,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "b97e0a63b1003f867891c195c2df5968744f22b1437db56888305d053eee50fd",
+      "contentHash": "7b24d5f0ce709b9b960d78d17a92d2cb24ad6319175d2edd1e3ffef17f30ba80",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

package/upgrades/1.3.261.md

@@ -0,0 +1,45 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+The stale-session watchdog no longer cries wolf on healthy long-running sessions. Two
+detection-accuracy fixes in StaleSessionBackstop:
+
+1. Operator-protected sessions (the reaper's protectedSessions) are never flagged as
+   stale — they're deliberately kept alive, so escalating them was a false alarm.
+2. Conversational/autonomous sessions get a far more forgiving no-progress window
+   (conversationalEscalateMinutes, default 180 min) than run-to-completion jobs (which
+   keep the strict 30-min window). A long autonomous session that legitimately idles
+   between turns or waits on a multi-minute tool call no longer trips the 30-minute
+   "looks stuck" threshold.
+
+This is the detection half of the Notification UX Coherence work; PR1 shipped the calm
+"🩺 Agent Health" lane (the delivery half). The fake-work guards (transcript tail-hash +
+cpu-seconds delta) are unchanged — genuine wedges are still caught; the backstop is still
+signal-only and never auto-kills.
+
+## What to Tell Your User
+
+Your agent will stop pinging you that a long-running session "looks stuck" when it's
+actually just working through a slow step or waiting between turns. Sessions you've
+marked as protected are never flagged at all, and ordinary long conversations get a much
+more patient window before the agent mentions anything. Genuinely-stuck work is still
+caught — just without the false alarms.
+
+## Summary of New Capabilities
+
+- StaleSessionBackstop exempts operator-protected sessions from stale escalation.
+- New monitoring.staleBackstop.conversationalEscalateMinutes (default 180): a forgiving
+  no-progress window for conversational/autonomous sessions, separate from the strict job
+  window (unverifiableEscalateMinutes, 30). Clamped to never be more aggressive than the
+  job window.
+
+## Evidence
+
+- Unit (tests/unit/stale-session-backstop.test.ts): a protected session is never
+  escalated even well past the window; the threshold split — a healthy long conversational
+  session at 35 min does NOT escalate while a wedged job at 35 min DOES.
+- 82 standards + backstop tests green; tsc clean; pre-push-gate clean.

package/upgrades/1.3.262.md

@@ -0,0 +1,23 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Documented the internal-only release-note lane in the bundled instar-dev skill and added a PostUpdateMigrator backfill so existing agents with stock deployed copies receive the same guidance after update.
+
+The new skill section explains the `<!-- internal-only -->` fragment marker, the ability to omit the two user-facing release-note sections, the assembler's all-internal-only auto-fill rule, and the pre-push gate that rejects the marker when runtime `src/*.ts` files changed.
+
+## What to Tell Your User
+
+Nothing changes in normal product behavior. This update improves the development workflow so agents know when the internal-only release-note lane is valid and existing agents receive that guidance automatically.
+
+## Summary of New Capabilities
+
+Existing agents with stock instar-dev skill installs now learn the internal-only release-note lane through the post-update migration path instead of waiting for a fresh install.
+
+## Evidence
+
+- Added a focused PostUpdateMigrator unit test covering update, idempotency, customized-skill preservation, and missing-skill no-op behavior.
+- Ran the existing build-location migration test and the new internal-only-lane migration test together: 8 tests passed.

package/upgrades/side-effects/instar-dev-internal-only-lane-docs.md

@@ -0,0 +1,103 @@
+# Side-Effects Review — instar-dev internal-only release-note lane docs
+
+**Version / slug:** `instar-dev-internal-only-lane-docs`
+**Date:** `2026-06-04`
+**Author:** `instar-codey`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+This change documents PR #765's internal-only release-note lane in the bundled `/instar-dev` skill and adds a PostUpdateMigrator backfill so existing deployed stock skill copies receive the same guidance.
+
+The skill text documents four operational facts grounded in #765: `<!-- internal-only -->` opts a fragment into the lane, the marker lets the fragment omit `What to Tell Your User` and `Summary of New Capabilities`, the shared assembler auto-fills those sections only when every contributing fragment is internal-only, and the pre-push gate rejects the marker when runtime `src/*.ts` files changed.
+
+## Decision-point inventory
+
+- `/instar-dev` skill text — modify — teaches agents when the internal-only lane is valid.
+- `PostUpdateMigrator` built-in skill migration — modify — copies the bundled stock skill into existing stock deployed copies when the new marker is missing.
+- Release gates — `hasInternalOnlyMarker` (`scripts/assemble-next-md.mjs`) hardened to match the marker only as a standalone directive line (see §8); pre-push behavior otherwise unchanged.
+
+---
+
+## 1. Over-block
+
+The migration may skip a deployed instar-dev skill that is structurally stock but lacks the conservative fingerprint (`# /instar-dev` and `### Phase 2 — Planning`). That is acceptable because the alternative is clobbering customized local workflows. Fresh installs still receive the bundled skill.
+
+---
+
+## 2. Under-block
+
+This does not enforce correct use of the internal-only marker beyond documenting the already-merged pre-push gate. An agent can still misunderstand the lane, but the guidance now lives in the skill at the point where agents prepare release fragments.
+
+---
+
+## 3. Level-of-abstraction fit
+
+The skill is the right documentation layer because `/instar-dev` owns the release-fragment workflow. PostUpdateMigrator is the right deployment layer because installed skills are untracked agent-local files; package updates alone do not rewrite existing copies.
+
+---
+
+## 4. Signal vs authority compliance
+
+- [x] No new authority is introduced.
+
+This PR changes documentation and migration parity only. The objective authority remains PR #765's existing pre-push gate, which checks the marker against the diff.
+
+---
+
+## 5. Interactions
+
+- **#760 migration:** This mirrors the existing build-location skill migration but uses a new marker phrase, so both migrations are independently idempotent.
+- **Fresh installs:** `installBuiltinSkills` gets the updated bundled skill directly.
+- **Existing installs:** PostUpdateMigrator rewrites only stock deployed copies missing the new phrase.
+- **Customized installs:** The conservative fingerprint check leaves them untouched.
+
+---
+
+## 6. External surfaces
+
+The visible surface is limited to development agents reading `/instar-dev`. End-user behavior does not change. Existing agents with stock skill installs will see the new guidance after update.
+
+---
+
+## 7. Rollback cost
+
+Rollback is a normal code revert. Agents that already received the updated skill keep a harmless documentation section until a later migration rewrites the file. There is no persistent database migration.
+
+---
+
+## Conclusion
+
+The change closes the deploy-awareness half of #765 without changing the ship-lane mechanism itself. The main risk is overwriting customized skills, and the migration avoids that by using the same conservative content-sniffing pattern as #760.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** not required
+**Independent read of the artifact:** not required
+
+This touches development-skill documentation and an idempotent post-update skill migration. It does not alter session lifecycle, messaging gates, sentinels, or runtime block/allow decisions.
+
+---
+
+## 8. Marker-detection hardening (surfaced while building this PR)
+
+Building this docs PR surfaced a false-positive in `hasInternalOnlyMarker`
+(`scripts/assemble-next-md.mjs`): the matcher used a whole-content regex, so a
+fragment that merely *documents* the `<!-- internal-only -->` marker in prose (as
+this PR's own release fragment does, quoting the literal marker in backticks) was
+misread as *using* the internal-only lane — and tripped its own §3c src-conflict
+gate (this PR touches `PostUpdateMigrator.ts`). Hardened the matcher to recognize
+the marker ONLY as a standalone directive line (like `<!-- bump: -->`), never an
+inline/backtick mention. Pure script + test change; no `src/` runtime surface.
+Behavior for genuine internal-only fragments (marker on its own line) is unchanged
+— all three prior `detects the marker` assertions stay green. Regression test
+added (`does NOT detect an inline/backtick mention…`).
+
+---
+
+## Evidence pointers
+
+- `npm test -- --run tests/unit/migrate-instar-dev-build-location.test.ts tests/unit/migrate-instar-dev-internal-only-lane.test.ts`
+- `npm test -- --run tests/unit/assemble-next-md.test.ts tests/unit/pre-push-gate.test.ts` (47 tests — marker false-positive regression)

package/upgrades/side-effects/stalebackstop-accuracy.md

@@ -0,0 +1,52 @@
+# Side-Effects Review — StaleBackstop detection accuracy (PR2 / D5)
+
+## What changed (mechanically)
+
+`StaleSessionBackstop` no longer cries wolf on healthy long-running sessions:
+1. **Protected sessions are never escalated.** New `isProtectedSession?(session)` dep
+   (wired in server.ts to the reaper's `getProtectedSessions()`, matched by tmux name
+   or session name). A protected session — one the operator deliberately keeps alive —
+   skips BOTH escalation paths (no-progress and long-indeterminate).
+2. **Conversational/autonomous sessions get a forgiving window.** New
+   `conversationalEscalateMinutes` option (default 180, clamped to ≥ the job window).
+   The no-progress threshold is now `session.jobSlug ? unverifiableEscalateMinutes (30)
+   : max(conversationalEscalateMinutes, unverifiableEscalateMinutes)`. A job runs to
+   completion (strict 30-min window); a conversational/autonomous session legitimately
+   idles between turns and while waiting on multi-minute tool calls, so it gets 180.
+
+## Blast radius
+
+- The fake-work guards (`hasForwardProgress`: tail-hash + cpu-seconds delta) are
+  UNTOUCHED — wedge detection is unchanged; this only widens the no-progress WINDOW for
+  conversational sessions and exempts protected ones.
+- A genuinely-wedged JOB still escalates at 30 min (unchanged).
+- A genuinely-wedged conversational session still escalates — just at 180 min, not 30.
+  Combined with PR1's calm lane, even that is a single calm heads-up, not topic-spam.
+- Config additive + defaulted; absent config → defaults apply (180 / protected-from-reaper).
+
+## Failure modes considered
+
+- **conversationalEscalateMinutes mis-set below the job window**: clamped up via
+  `max(...)` at the decision site, so it can never be MORE aggressive than the job window.
+- **isProtectedSession absent** (older wiring / tests): optional-chained → no session
+  treated as protected (prior behavior), never throws.
+- **Protected list by name vs id**: matched against both `tmuxSession` and `name`.
+
+## Non-goals
+
+- Does NOT change delivery (that's PR1's lane).
+- Does NOT auto-kill anything (the backstop remains signal-only).
+
+## Reversibility
+
+`monitoring.staleBackstop.conversationalEscalateMinutes: 30` restores the old uniform
+window; protection follows the existing `protectedSessions` list. Additive only.
+
+## Tests
+
+Unit (stale-session-backstop.test.ts): protected session never escalates; the
+conversational-vs-job threshold split (a healthy long conversational session at 35 min
+does NOT escalate while a wedged job DOES). Existing mechanism tests pinned to the 30-min
+window via `conversationalEscalateMinutes: M`. 82 standards + backstop tests green; tsc
+clean. (Also: bumped the no-silent-fallbacks baseline 458→459 for PR1's lane fallback, and
+tracked main's untacked `/secrets/sync-status` migrator section — both per Zero-Failure.)