instar 1.3.175 → 1.3.177

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.175",
+  "version": "1.3.177",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-31T19:05:35.298Z",
-  "instarVersion": "1.3.175",
+  "generatedAt": "2026-05-31T20:20:49.223Z",
+  "instarVersion": "1.3.177",
   "entryCount": 193,
   "entries": {
     "hook:session-start": {
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "e4c4130d4cb388133d46289aa411dc649732cbbf6591d00bb4dd7d135f8acc61",
+      "contentHash": "6785feccb0b5dab73704c9002fb025222445da09255a2d124978b6a395c65c3d",
       "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": "e4c4130d4cb388133d46289aa411dc649732cbbf6591d00bb4dd7d135f8acc61",
+      "contentHash": "6785feccb0b5dab73704c9002fb025222445da09255a2d124978b6a395c65c3d",
       "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": "e4c4130d4cb388133d46289aa411dc649732cbbf6591d00bb4dd7d135f8acc61",
+      "contentHash": "6785feccb0b5dab73704c9002fb025222445da09255a2d124978b6a395c65c3d",
       "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": "e4c4130d4cb388133d46289aa411dc649732cbbf6591d00bb4dd7d135f8acc61",
+      "contentHash": "6785feccb0b5dab73704c9002fb025222445da09255a2d124978b6a395c65c3d",
       "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": "e4c4130d4cb388133d46289aa411dc649732cbbf6591d00bb4dd7d135f8acc61",
+      "contentHash": "6785feccb0b5dab73704c9002fb025222445da09255a2d124978b6a395c65c3d",
       "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": "e4c4130d4cb388133d46289aa411dc649732cbbf6591d00bb4dd7d135f8acc61",
+      "contentHash": "6785feccb0b5dab73704c9002fb025222445da09255a2d124978b6a395c65c3d",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -65,7 +65,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "e4c4130d4cb388133d46289aa411dc649732cbbf6591d00bb4dd7d135f8acc61",
+      "contentHash": "6785feccb0b5dab73704c9002fb025222445da09255a2d124978b6a395c65c3d",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -74,7 +74,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "e4c4130d4cb388133d46289aa411dc649732cbbf6591d00bb4dd7d135f8acc61",
+      "contentHash": "6785feccb0b5dab73704c9002fb025222445da09255a2d124978b6a395c65c3d",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-collector": {
@@ -83,7 +83,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "e4c4130d4cb388133d46289aa411dc649732cbbf6591d00bb4dd7d135f8acc61",
+      "contentHash": "6785feccb0b5dab73704c9002fb025222445da09255a2d124978b6a395c65c3d",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -92,7 +92,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "e4c4130d4cb388133d46289aa411dc649732cbbf6591d00bb4dd7d135f8acc61",
+      "contentHash": "6785feccb0b5dab73704c9002fb025222445da09255a2d124978b6a395c65c3d",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -101,7 +101,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "e4c4130d4cb388133d46289aa411dc649732cbbf6591d00bb4dd7d135f8acc61",
+      "contentHash": "6785feccb0b5dab73704c9002fb025222445da09255a2d124978b6a395c65c3d",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -110,7 +110,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "e4c4130d4cb388133d46289aa411dc649732cbbf6591d00bb4dd7d135f8acc61",
+      "contentHash": "6785feccb0b5dab73704c9002fb025222445da09255a2d124978b6a395c65c3d",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -119,7 +119,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "e4c4130d4cb388133d46289aa411dc649732cbbf6591d00bb4dd7d135f8acc61",
+      "contentHash": "6785feccb0b5dab73704c9002fb025222445da09255a2d124978b6a395c65c3d",
       "since": "2025-01-01"
     },
     "hook:stop-gate-router": {
@@ -128,7 +128,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/stop-gate-router.js",
-      "contentHash": "e4c4130d4cb388133d46289aa411dc649732cbbf6591d00bb4dd7d135f8acc61",
+      "contentHash": "6785feccb0b5dab73704c9002fb025222445da09255a2d124978b6a395c65c3d",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -137,7 +137,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "e4c4130d4cb388133d46289aa411dc649732cbbf6591d00bb4dd7d135f8acc61",
+      "contentHash": "6785feccb0b5dab73704c9002fb025222445da09255a2d124978b6a395c65c3d",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1489,7 +1489,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "e4c4130d4cb388133d46289aa411dc649732cbbf6591d00bb4dd7d135f8acc61",
+      "contentHash": "6785feccb0b5dab73704c9002fb025222445da09255a2d124978b6a395c65c3d",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

package/upgrades/1.3.176.md

@@ -0,0 +1,97 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+**The stop gate now catches the "I'll do it now" silent stall — even in shadow
+mode.** A recurring failure: an agent's final message tells the user it is about
+to act this turn ("I'll build that now", "starting now", "Next phase: ship the
+fix") and then the turn simply ends, leaving the user staring at silence after
+being told work was continuing.
+
+The existing `stop-gate-router.js` hook delegated the continue/stop decision to
+the server-side Unjustified Stop Gate, which only blocks in `enforce` mode — but
+the gate ships in `shadow` (telemetry-only) mode on most agents, so the exact
+moment a stall happened, nothing intervened.
+
+This adds a small, always-on guard at the top of the hook. When the final message
+states an imminent this-turn action together with an imminence marker (now / right
+now / this turn / next phase / on it), the hook blocks once and re-feeds the
+agent: either actually do the work, or send the user one honest sentence that it
+is stopping and why. The guard is mode-independent (works even when the gate is in
+shadow mode or the server is unreachable) and fires at most once — the existing
+loop guard prevents any continuation trap. "Report-back-later" intent (no
+imminence marker) is not caught; that stays with the commitment tracker.
+
+The Framework-Onboarding Mentor System's "lessons for the next framework"
+playbook now actually populates. Generalizable framework issues (the portable
+lessons — `framework-limitation` and `instar-integration-gap`) are promoted from
+`none` to `candidate` the moment they're terminally resolved (fixed or won't-fix),
+which is the auto-suggestion step the spec (§13.6) defined but that had never been
+implemented. A one-time, idempotent backfill on ledger startup seeds lessons that
+were resolved before this existed. Without this, the onboarding playbook returned
+an empty list even with a full ledger of hard-won lessons — they were logged but
+never reached the next framework's onboarding.
+
+The `candidate → extracted` step (canonizing a lesson into the reusable onboarding
+checklist) is unchanged: it still requires a non-Echo attestation, so an agent
+cannot canonize its own lessons.
+
+## What to Tell Your User
+
+Nothing to configure. Your agent can no longer tell you "I'll do that now" and
+then quietly stop without doing it — if it tries, it gets nudged once to either
+actually do the work or tell you plainly that it is stopping and why. The result
+is fewer confusing silences after an agent says it is continuing.
+
+Nothing required — this is internal mentor-system robustness. If asked: the
+lessons learned onboarding one agent framework now actually carry forward to the
+next one, instead of sitting unused in the ledger.
+
+## Summary of New Capabilities
+
+- Local, mode-independent stated-continuation guard in the stop-gate-router hook
+  (`PostUpdateMigrator.getStopGateRouterHook()`); deploys to every agent on update
+  via the always-overwrite built-in hook path.
+
+- `GET /framework-issues/playbook?targetFramework=X` now returns the generalizable,
+  terminally-resolved lessons from prior frameworks (previously always empty because
+  nothing ever moved an issue off `playbook_status='none'`).
+- `FrameworkIssueLedger.backfillPlaybookCandidates()` seeds pre-existing eligible
+  lessons; runs automatically and idempotently on ledger construction.
+
+## Evidence
+
+Reproduction (live, topic 13481, 2026-05-31): the agent posted "I'm going to
+build that now ... then deploy and finish the round-trip proof" at 16:56 UTC,
+then ended the turn and went silent for ~90 minutes without starting the work.
+Operator response: "your session has stalled again ... this is incoherent."
+
+Root cause observed: a direct probe of the running gate returned
+GET /internal/stop-gate/hot-path -> {"mode":"shadow",...}. In shadow mode the
+stop-gate-router records telemetry but never blocks, so the stall passed through
+unchallenged — the safety net was off at the exact moment it was needed.
+
+Before: rendering the prior hook and feeding it the exact stall message
+("Next phase: build the reverse reply-relay, then ship the fix") exits 0 — the
+agent is allowed to stop silently.
+
+After: the same rendered hook fed the same message exits 2 and writes
+{"decision":"block", reason:"STOP-GATE (stated-continuation): ..."}, regardless
+of the server's shadow/enforce mode and even with no server reachable. A benign
+completion ("Done — all tests passed ...") still exits 0, and stop_hook_active=true
+exits 0 (loop guard intact). Confirmed by executing the rendered hook as a
+subprocess against each payload (tests/unit/stop-gate-stated-continuation.test.ts,
+5/5 green).
+
+- Root cause: §13.6's `none→candidate` auto-suggestion was specified but never
+  implemented — the only writer of `candidate` was the manual promote route, so a
+  live ledger with 18 generalizable codex lessons (11 terminal) served `playbook: []`.
+- Fix: deterministic auto-bump in `updateIssue` on terminal resolution + an
+  idempotent constructor backfill; the `candidate→extracted` non-Echo attestation
+  guard is untouched.
+- Tests: +10 unit, +1 integration end-to-end; 192 ledger/mentor/route/E2E tests pass.
+  `npm run lint` clean.
+- Spec: docs/specs/PLAYBOOK-CANDIDATE-AUTOSEED-SPEC.md (+ ELI16 companion).

package/upgrades/1.3.177.md

@@ -0,0 +1,70 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+**A conversation moved to a second machine can now reply to you.** When you move
+a conversation to another machine (e.g. "move this to the Mac Mini"), that machine
+serves the session but deliberately holds NO Telegram bot token — only one machine
+may hold it, or Telegram throws a 409 poller conflict. The reply path already had
+the fix for this: a tokenless standby relays its reply through the token-owning
+machine (bug #7, `outboundRelay`).
+
+But the "am I tokenless?" check was `!this.config.token`. On a standby the bot
+token is *externalized* and arrives unresolved as a placeholder object
+(`{ secret: true }`), not `null` — and an object is truthy, so the check concluded
+"I have a token", skipped the relay, and attempted a doomed direct API call with
+the placeholder. The moved session's reply returned 200 internally but never
+reached Telegram.
+
+The fix treats only a non-empty STRING as a usable bot token. The placeholder,
+`null`, `undefined`, and `''` all now correctly mean "no usable token" → relay
+through the token-owning machine. Token-holding machines (the normal case) are
+completely unaffected — they still send directly.
+
+## What to Tell Your User
+
+Nothing to configure. If you run on more than one machine and move a conversation
+to another one, that machine can now actually reply to you — previously a moved
+session would go silent because its reply couldn't reach Telegram.
+
+## Summary of New Capabilities
+
+- `TelegramAdapter.sendToTopic` correctly detects a tokenless pool standby when
+  the bot token is an unresolved (non-string) externalized placeholder, and routes
+  the reply through `outboundRelay` instead of a doomed direct send.
+
+## Evidence
+
+**Reproduction (live, topic 8882, 2026-05-31 16:46 UTC):** POSTed a reply to the
+Mac Mini standby's `/telegram/reply/8882`. Response was `{"ok":true}` (HTTP 200)
+but the message never appeared in Telegram; the mini's `logs/server.log` showed NO
+outbound-relay attempt and the laptop showed NO inbound relay. The mini's
+`.instar/config.json` carried `botToken: { secret: true }` (externalized, never
+resolved on the tokenless standby).
+
+**Observed before/after (the relay decision, run in dev against the real
+placeholder value):**
+
+```
+token value: {"secret":true}
+BEFORE (!token):       HAS-TOKEN -> direct API send (DOOMED: placeholder is not a real token)
+AFTER (typeof string): TOKENLESS -> relay (FIXED)
+real string AFTER:     HAS-TOKEN -> direct API send (unchanged)
+```
+
+The truthy placeholder object flips the decision from "doomed direct send" to
+"relay" — exactly the path the moved session needed. A real string token is
+unchanged (still direct), so token-holding machines see no behavior change.
+
+**Behavioral test:** `tests/unit/telegram-tokenless-relay.test.ts` constructs a
+real `TelegramAdapter` with the `{ secret: true }` placeholder + spy `outboundRelay`
++ spy `fetch`, calls the REAL `sendToTopic`, and observes `outboundRelay` invoked
+once with `fetch` never called (before this fix that path called `fetch` with the
+bad token). 3/3 green.
+
+**Live round-trip confirmation:** the full "move via Telegram → mini serves →
+reply lands in 8882" round trip is confirmed against the deployed release on the
+two-machine setup.

package/upgrades/side-effects/stop-gate-stated-continuation.md

@@ -0,0 +1,41 @@
+# Side effects — stated-continuation stop guard
+
+## What changes at runtime
+
+The built-in `stop-gate-router.js` Stop hook gains a local, mode-independent
+guard. On every Stop, if the agent's final message states an imminent this-turn
+action ("I'll build X now", "starting now", "next phase: ...", "on it ... now")
+the hook returns `{decision:'block'}` (exit 2) ONCE, re-feeding the agent to
+either do the work or tell the user plainly it is stopping and why.
+
+## Who is affected
+
+- **Every Instar agent on update.** Built-in `instar/` hooks are always
+  overwritten on migration, so the guard deploys automatically — no opt-in,
+  no per-agent migration. New agents get it via `init`.
+
+## Behavioral side effects (intended)
+
+- An agent that ends a turn right after saying "I'll do X now" will be blocked
+  once and pushed to either act or send an explicit stop message. This is the
+  intended fix; it converts silent stalls into either real work or an honest
+  "I'm stopping because…" message.
+- Borderline matches (e.g. a summary heading "Next phase: …") cost exactly one
+  extra nudge and force an explicit sign-off — acceptable and desirable.
+
+## What is NOT affected
+
+- The server-side Unjustified Stop Gate, its mode (shadow/enforce), its telemetry,
+  and its circuit breaker are all untouched.
+- The autonomous-stop-hook and hook-event-reporter Stop hooks are untouched.
+- The loop-prevention contract is preserved: the existing `stop_hook_active` guard
+  still short-circuits on the re-fire, so the guard fires at most once per stop —
+  no infinite continuation loop is possible.
+- "Report-back-later" / scheduled commitments (no imminence marker) are NOT
+  caught — those remain the commitment tracker's domain.
+
+## Rollback
+
+Revert the `getStopGateRouterHook()` change; the next migration overwrites the
+installed hook back to the prior content. No state, config, or schema changes are
+involved.

package/upgrades/side-effects/tokenless-standby-relay-token-check.md

@@ -0,0 +1,33 @@
+# Side effects — tokenless-standby relay token check
+
+## What this changes at runtime
+
+`TelegramAdapter.sendToTopic` now decides "tokenless → relay" by checking that
+the bot token is a non-empty STRING, instead of the old truthy check
+(`!this.config.token`). The change is confined to the relay-vs-direct branch.
+
+## Who is affected
+
+- **Token-holding adapters (the normal case — laptop, single-machine agents):**
+  NO behavior change. Their `config.token` is a real string, so
+  `hasUsableBotToken` is `true` and they continue to send directly via the
+  Telegram API exactly as before. Verified by the "sends DIRECTLY" unit test.
+- **Tokenless pool standbys (a moved session on a machine without the token):**
+  Their externalized token (`{ secret: true }` / `null`) is now correctly seen
+  as "no usable token", so their replies route through `outboundRelay` to the
+  lease holder instead of silently failing a direct send.
+
+## Blast radius
+
+- Single file (`src/messaging/TelegramAdapter.ts`), one branch condition.
+- No config keys added or changed. No migration required (the change is in
+  compiled source, not in any agent-installed file/hook/skill).
+- The relay target (`outboundRelay`, wired in `server.ts`) is unchanged.
+
+## Failure modes considered
+
+- If a standby has no usable token AND `outboundRelay` is not wired, behavior is
+  unchanged from before (it falls through to the direct-send branch and fails the
+  same way) — no new failure introduced.
+- The relay still surfaces a hard error if the lease holder is unreachable
+  (`telegram outbound relay failed`), so a lost reply is loud, not silent.

package/upgrades/1.3.175.md

@@ -1,46 +0,0 @@
-# Upgrade Guide — vNEXT
-
-<!-- assembled-by: assemble-next-md -->
-<!-- bump: patch -->
-
-## What Changed
-
-The Framework-Onboarding Mentor System's "lessons for the next framework"
-playbook now actually populates. Generalizable framework issues (the portable
-lessons — `framework-limitation` and `instar-integration-gap`) are promoted from
-`none` to `candidate` the moment they're terminally resolved (fixed or won't-fix),
-which is the auto-suggestion step the spec (§13.6) defined but that had never been
-implemented. A one-time, idempotent backfill on ledger startup seeds lessons that
-were resolved before this existed. Without this, the onboarding playbook returned
-an empty list even with a full ledger of hard-won lessons — they were logged but
-never reached the next framework's onboarding.
-
-The `candidate → extracted` step (canonizing a lesson into the reusable onboarding
-checklist) is unchanged: it still requires a non-Echo attestation, so an agent
-cannot canonize its own lessons.
-
-## What to Tell Your User
-
-Nothing required — this is internal mentor-system robustness. If asked: the
-lessons learned onboarding one agent framework now actually carry forward to the
-next one, instead of sitting unused in the ledger.
-
-## Summary of New Capabilities
-
-- `GET /framework-issues/playbook?targetFramework=X` now returns the generalizable,
-  terminally-resolved lessons from prior frameworks (previously always empty because
-  nothing ever moved an issue off `playbook_status='none'`).
-- `FrameworkIssueLedger.backfillPlaybookCandidates()` seeds pre-existing eligible
-  lessons; runs automatically and idempotently on ledger construction.
-
-## Evidence
-
-- Root cause: §13.6's `none→candidate` auto-suggestion was specified but never
-  implemented — the only writer of `candidate` was the manual promote route, so a
-  live ledger with 18 generalizable codex lessons (11 terminal) served `playbook: []`.
-- Fix: deterministic auto-bump in `updateIssue` on terminal resolution + an
-  idempotent constructor backfill; the `candidate→extracted` non-Echo attestation
-  guard is untouched.
-- Tests: +10 unit, +1 integration end-to-end; 192 ledger/mentor/route/E2E tests pass.
-  `npm run lint` clean.
-- Spec: docs/specs/PLAYBOOK-CANDIDATE-AUTOSEED-SPEC.md (+ ELI16 companion).