instar 1.3.660 → 1.3.661

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.660",
+  "version": "1.3.661",
   "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-06-25T07:17:11.166Z",
-  "instarVersion": "1.3.660",
+  "generatedAt": "2026-06-25T07:21:02.386Z",
+  "instarVersion": "1.3.661",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

package/upgrades/{1.3.660.md → 1.3.661.md}

@@ -5,6 +5,26 @@
 
 ## What Changed
 
+Adds a new constitutional standard, **"Verify the State, Not Its Symbol"**, to
+`docs/STANDARDS-REGISTRY.md` (Substrate family), and registers it as **P20** in
+`docs/INSTAR-DESIGN-PRINCIPLES-AND-LESSONS.md` so the `/spec-converge` lessons-aware
+reviewer fires on every future spec. Lesson L5 is re-pointed to P20 as its parent.
+
+The standard names a class of blind spot that has bitten the fleet repeatedly under
+different disguises: a detector, gate, verifier, or sentinel that trusts a *symbol*
+of a state (a string on a pane, a marker, the presence or absence of a proxy signal)
+instead of confirming the *state itself* — in both directions, where the presence of
+a symbol is taken as the condition being true and the absence of a signal is taken as
+the condition being true. When the evidence needed to decide is unavailable, the result
+is **unknown**, and unknown must fail toward the least-harmful action for that specific
+detector — which is not always "closed".
+
+Documentation-only: this change adds no runtime, gate, or `src` surface. The companion
+fix for the crystallizing instance (the RateLimitSentinel false-positive) is specified
+and review-converged in `docs/specs/ratelimit-sentinel-false-positive-hardening.md`,
+which this change also lands so the standard's enforcement-first citation resolves to a
+real file; the implementation of that fix ships as a separate, tracked follow-on PR.
+
 Fixed the "session paused" hang: an autonomous session would freeze indefinitely the first time a helper sub-agent (spawned via the Task/Agent tool) ran a shell command. Root cause: a sub-agent does NOT inherit the parent session's `--dangerously-skip-permissions` MODE — confirmed against Claude Code docs, it inherits only the permission RULES from `.claude/settings.json`. With no allow-rules configured, the sub-agent's first `Bash` call surfaced the interactive "This command requires approval" dialog, and in an unattended run there was no human to answer it, so the session sat modal-blocked forever (indistinguishable from "paused"). It affected the whole fleet because every agent shipped with an empty permissions block.
 
 `PostUpdateMigrator.ensurePermissionAllowRules()` now runs inside `migrateSettings()` and adds a `permissions.allow` list for the built-in tools a sub-agent uses (`Bash`, `Read`, `Edit`, `Write`, `Glob`, `Grep`, `Task`, `NotebookEdit`, `WebFetch`, `WebSearch`, `TodoWrite`). Sub-agents inherit permission rules, so the allow-rule is the structural lever that reliably applies — unlike the existing `PermissionRequest` auto-approve hook, which does not reliably fire for sub-agent calls. The migration is idempotent (adds only missing tool names), never touches the operator's `deny`/`ask` lists, and deliberately excludes MCP tools (`mcp__*`) so external/network operations keep their external-operation-gate approval posture. Because it rides `migrateSettings()`, every existing agent picks it up on its next update and every new agent gets it at init (Migration Parity).
@@ -13,14 +33,37 @@ Safety is unchanged: the allow-rules only skip the duplicative human-in-the-loop
 
 ## What to Tell Your User
 
+- **A new "verify the real state, not a sign of it" rule**: "I added a standard to how I'm
+  built so that my own watchers can't cry wolf at a word on the screen, or go silent because
+  they looked for proof in the wrong place. From now on, anything I build that watches for a
+  problem has to confirm the problem is really happening before it acts — and when it genuinely
+  can't tell, it errs toward the quiet, least-harmful choice instead of the loudest one. This
+  came straight out of the false 'you're throttled' alarms you saw tonight."
+
 If your agent ever seemed to "pause" mid-task during an unattended/autonomous run — silently stuck and only resuming when you messaged it — this is a common cause: a helper it spawned hit an approval prompt nobody was there to answer. After this update (and a session restart so the new settings load), helper tasks no longer stall on those prompts, so autonomous runs keep moving. Your safety guards are unchanged — every command still passes the same pre-action checks; the only thing removed is the approval pop-up that had no one to answer it.
 
 ## Summary of New Capabilities
 
+| Capability | How to Use |
+|-----------|-----------|
+| "Verify the State, Not Its Symbol" standard (P20) | automatic — the `/spec-converge` lessons-aware reviewer now flags any future spec whose detector fires on a single uncorroborated symbol, reads a self-writable channel, or treats absence as the bad state |
+
 - `PostUpdateMigrator.ensurePermissionAllowRules()` — adds inherited `permissions.allow` rules for sub-agent built-in tools to every agent's `.claude/settings.json` via the migration path (new agents at init, existing agents on update). Idempotent, non-clobbering of operator `deny`/`ask`, and scoped to local tools (MCP stays gated by the external-operation-gate).
 
 ## Evidence
 
+Earned from a live recurrence, not a hypothetical. On 2026-06-24 (topic 16566) the
+RateLimitSentinel fired "this turn died on an API error" because the literal words
+`API Error:` were on the session pane — placed there by the session *investigating* API
+errors, with nothing actually failed — then cried wolf for ~11 minutes because its recovery
+verifier looked for the session transcript in one Claude account home while the session ran
+under another, reading absence-of-file as "never recovered". The detector that diagnosed the
+bug was, live, tripped by the bug. The same class had recurred 4+ times before under different
+disguises (2026-06-06 stale-transcript-pointer crying-wolf, the AUP-rejection wedge, the origin
+of lesson L5), each patched point-wise without ever naming the class — the registry's promotion
+signal. The companion code fix's reproduction + before/after is carried in its own spec and
+follow-on PR; this PR is documentation-only and changes no runtime behavior to reproduce.
+
 - **Reproduction (2026-06-24):** an unattended autonomous run sat silent for ~68 min; a screenshot showed the session modal-blocked on a sub-agent's `Bash` "This command requires approval" dialog. Confirmed the same class on a second agent (AI Guy). Settings inspection showed the `permissions` block was entirely absent (no allow-rules for sub-agents to inherit).
 - **Mechanism confirmed:** Claude Code docs — sub-agents inherit permission RULES but not the permission MODE; PreToolUse hooks run BEFORE permission-rule evaluation and a hook exiting 2 blocks the call even for an allowed tool (so allow-rules cannot weaken the guards).
 - **Tests:** `tests/unit/PostUpdateMigrator-permissionAllowRules.test.ts` — 6 tests: adds all sub-agent tools when absent; includes Bash; does NOT blanket-allow MCP; preserves operator allow entries with no duplicates; never touches deny/ask; idempotent on second pass. All passing. Adjacent `PostUpdateMigrator-cleanupPeriodDays.test.ts` (same migrateSettings path) still green. `npm run build` green.

package/upgrades/side-effects/blindspot-class-symbol-vs-state.md

@@ -0,0 +1,41 @@
+# Side-Effects Review — Verify the State, Not Its Symbol (constitution amendment)
+
+**Change:** Documentation-only. Adds the constitutional standard "Verify the State, Not Its
+Symbol" to `docs/STANDARDS-REGISTRY.md` (Substrate section), registers it as **P20** in
+`docs/INSTAR-DESIGN-PRINCIPLES-AND-LESSONS.md` (the surface the `/spec-converge` lessons-aware
+reviewer loads), re-points L5 to P20 as its parent, updates the Part-4 reviewer range to P1-P20,
+and lands the supporting analysis spec + ELI16. **No runtime/`src` surface.** Operator-ratified
+(Justin, topic 16566, 2026-06-24) after independent verification that it is a real gap.
+
+1. **Over-block** — None. No code path, gate, or filter changes; nothing new can reject input.
+   The only behavioral effect is additive: the spec-converge reviewer gains one more lens (P20)
+   to flag a future spec — advisory findings, never a hard block of runtime behavior.
+2. **Under-block** — The standard is enforced today only via the lessons-aware reviewer (advisory)
+   + the companion code fix (the crystallizing instance). The `no-uncorroborated-symbol-fire` CI
+   ratchet that would mechanically catch *new* violating callsites is named as the next enforcement
+   surface, not yet built — so a brittle detector added between now and that ratchet relies on the
+   reviewer catching it. Stated honestly in the standard's "Applied through", not hidden.
+3. **Level-of-abstraction fit** — Correct layer. It is a Substrate (model-level truth) standard, a
+   parent of the existing L5 lesson and the AUP-wedge note; placed beside its siblings
+   (No Silent Degradation, Distrust Temporary Success) and registered in the same P-catalog the
+   reviewer already consumes. No new abstraction invented.
+4. **Signal vs authority (P2)** — Compliant and explicitly differentiated: the standard's text
+   states it is *orthogonal* to Signal-vs-Authority (which governs who may BLOCK) — it governs the
+   *evidentiary correctness* a detector must have whether it is a signal-emitter or a gate. The
+   amendment itself holds no authority; it is documentation feeding an advisory reviewer.
+5. **Interactions** — Touches the shared P-catalog: P18/P19 already existed, so the new entry is
+   **P20** (verified free) and the Part-4 range bumped P1-P19 → P1-P20. L5 gains a parent pointer.
+   No collision with the unrelated registry "No Unbounded Loops" P19 reference (left intact). No
+   migration surface (these docs are not agent-installed files; Migration Parity N/A).
+6. **External surfaces** — None. Internal developer-facing docs only; no user/agent/API surface,
+   no template (`generateClaudeMd`) change, no config, no hook.
+7. **Multi-machine posture** — N/A (documentation). The standard it describes is, for detectors,
+   machine-local-by-design (each machine verifies its own sessions) — captured in the companion
+   fix's own side-effects review, not here.
+8. **Rollback cost** — Trivial: revert the doc commit. No data, no state, no deployed behavior to
+   unwind. The companion code fix ships and rolls back independently on its own branch.
+
+**Second-pass review:** Not required — documentation-only, no block/allow decision, no session
+lifecycle, no gate/sentinel/watchdog code. (The companion CODE fix
+`ratelimit-sentinel-false-positive-hardening`, which DOES touch sentinels, carries its own
+mandatory Phase-5 second-pass on its own branch.)