instar 1.3.209 → 1.3.211

package/upgrades/1.3.211.md

@@ -0,0 +1,63 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The autonomous-mode stop hook was being registered in `settings.json` at
+`.instar/hooks/instar/autonomous-stop-hook.sh` — a path where the hook is **never
+deployed**. The hook ships only in the skill directory
+(`.claude/skills/autonomous/hooks/autonomous-stop-hook.sh`). So on every `Stop`
+event the hook command hit a missing file, failed silently, and the autonomous
+loop never re-injected the task list. The session stayed alive but stopped
+self-continuing between turns — it only advanced when the user sent a message.
+
+Three coordinated fixes:
+
+1. **`.claude/skills/autonomous/SKILL.md` (Step 2a)** now registers the deployed
+   skill path and self-heals: it strips any prior (including wrong-path)
+   autonomous stop-hook entry and writes exactly one correct-path entry.
+2. **`PostUpdateMigrator.ensureAutonomousStopHook()`** gained a repair pass that
+   rewrites any existing wrong-path registration in `settings.json` to the skill
+   path. Without it, the "already registered?" presence check treated the
+   wrong-path entry as present and never corrected it — so existing agents would
+   stay broken forever.
+3. **`PostUpdateMigrator.migrateAutonomousStopHookTopicKeyed()`** re-deploys the
+   fixed `SKILL.md` to existing agents, gated on a marker unique to the corrected
+   prompt (stock prompts upgrade; customized prompts are left untouched).
+
+## What to Tell Your User
+
+If you ran an autonomous session and noticed it went quiet between turns —
+continuing only when you messaged it, rather than driving itself forward — this
+fixes the cause. The loop's re-engagement step was pointed at a file that was
+never installed, so it silently did nothing each time the session tried to
+continue. After this update the autonomous loop re-engages on its own as
+intended, and any agent that already had the broken registration is repaired
+automatically on update. No action is needed on your side.
+
+## Summary of New Capabilities
+
+- Autonomous sessions reliably self-continue between turns (the stop hook now
+  resolves to a file that actually exists).
+- Existing agents with the broken registration are healed in place on update —
+  both the `settings.json` entry and the deployed skill prompt.
+- The skill registration is now self-healing: activating autonomous mode always
+  ends with exactly one correct-path stop-hook entry, regardless of prior state.
+
+## Evidence
+
+- New unit suite `tests/unit/PostUpdateMigrator-autonomousHookPath.test.ts`
+  (9 tests): wrong-path → repaired; no duplicate added; siblings untouched;
+  already-correct → no-op; missing → registered; idempotent; SKILL.md content
+  asserts the corrected path + marker; topic-keyed migration re-deploys a stock
+  SKILL.md and skips a customized one.
+- Empirical check of the SKILL.md Step 2a snippet against a settings file
+  carrying the wrong-path entry plus sibling hooks: the wrong entry is rewritten
+  to `bash ${CLAUDE_PROJECT_DIR}/.claude/skills/autonomous/hooks/autonomous-stop-hook.sh`,
+  siblings are preserved, and a second run is a no-op (idempotent).
+- Existing autonomous/migration suites stay green
+  (`autonomous-skill-deployment`, `PostUpdateMigrator-buildStopHook`,
+  `autonomous-stop-hook-notify`, `installCodexHooks`, `emit-session-clock` —
+  50 tests). `tsc --noEmit` clean.

package/upgrades/side-effects/autonomous-stop-hook-path-fix.md

@@ -0,0 +1,156 @@
+# Side-Effects Review — Autonomous loop re-engagement fix (stop-hook registration path)
+
+**Version / slug:** `autonomous-stop-hook-path-fix`
+**Date:** `2026-06-03`
+**Author:** `Echo`
+**Second-pass reviewer:** `Echo (self, single-pass — Tier-1 fix)`
+
+## Summary of the change
+
+The autonomous-mode stop hook is what re-injects the task list on every `Stop`
+event so an autonomous session keeps working between turns. It was registered in
+`settings.json` at `.instar/hooks/instar/autonomous-stop-hook.sh`, but the hook
+is only ever deployed to the skill dir (`.claude/skills/autonomous/hooks/`). The
+registered path therefore pointed at a non-existent file: every `Stop` failed
+silently and the loop never re-engaged. Files touched:
+`.claude/skills/autonomous/SKILL.md` (Step 2a registration snippet),
+`src/core/PostUpdateMigrator.ts` (`ensureAutonomousStopHook` repair pass +
+`migrateAutonomousStopHookTopicKeyed` SKILL.md re-deploy), and a new unit suite.
+The decision surface is purely *which file path is written into the Stop-hook
+registration* — there is no message block/allow logic.
+
+## Decision-point inventory
+
+- `SKILL.md Step 2a registration` — modify — registers the deployed skill path
+  (was the never-deployed `.instar/hooks/instar/` path) and self-heals stale entries.
+- `PostUpdateMigrator.ensureAutonomousStopHook` — modify — adds a repair pass that
+  rewrites wrong-path entries before the existing presence check.
+- `PostUpdateMigrator.migrateAutonomousStopHookTopicKeyed` — modify — adds SKILL.md
+  to the marker-gated re-deploy list so existing agents receive the fixed prompt.
+- No message-gating / block-allow decision point is touched.
+
+---
+
+## 1. Over-block
+
+No block/allow surface — over-block not applicable. The change only corrects a
+filesystem path string in a hook registration; it never rejects any input.
+
+---
+
+## 2. Under-block
+
+No block/allow surface — under-block not applicable. One adjacent correctness
+note: the repair targets specifically the `.instar/hooks/instar/autonomous-stop-hook.sh`
+wrong path. If a future custom registration used some *third* wrong path, the
+repair would not catch it — but that path was never shipped by instar, so there
+is nothing in the install base to miss. The registration helper still adds a
+correct entry if none exists at all.
+
+---
+
+## 3. Level-of-abstraction fit
+
+Correct layer. This is a deterministic settings/file-path migration — exactly the
+class `PostUpdateMigrator` owns (Migration Parity Standard). The SKILL.md snippet
+is the install/activation-time registrar; the migrator is the in-place repair for
+already-deployed agents. No reasoning/LLM layer is involved or appropriate: the
+correct path is a fixed, known string, so a structural fix is the right tool (and
+matches the sibling `build-stop-hook.sh` path-repair precedent).
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — this change has no block/allow surface.
+
+It rewrites a hook-registration path in `settings.json`; it holds no message or
+operation authority. The autonomous stop hook itself (unchanged here) remains the
+authority for whether a session continues, and it is session-id-gated.
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** The repair pass runs *before* the existing `hasAutonomousHook`
+  presence check inside `ensureAutonomousStopHook`. This is intentional and is the
+  core of the fix: previously the presence check matched the wrong-path entry and
+  short-circuited the correct registration, so the wrong path was permanent. After
+  repair, the entry already holds the correct path, so the presence check finds it
+  and adds no duplicate (verified by the "no duplicate" test).
+- **Double-fire:** Two registrars exist — the SKILL.md Step 2a (activation-time,
+  dynamic add/remove) and `ensureAutonomousStopHook` (update-time, permanent). Both
+  now converge on the *same* command string, so they can no longer disagree or
+  produce two divergent entries. The SKILL.md snippet strips-then-appends, and the
+  migrator's presence check prevents duplicates; combined they always yield exactly
+  one correct entry (verified).
+- **Races:** No shared concurrent state. `settings.json` is edited by the same
+  single-writer migration path as every other hook registration.
+- **Feedback loops:** None. A one-time path correction; the corrected entry is a
+  fixed string, so subsequent passes are no-ops (idempotency verified).
+
+---
+
+## 6. External surfaces
+
+- **Other agents on the machine:** none — per-project `settings.json` only.
+- **Install base:** existing agents are healed on next update (the intended
+  surface). The `migrateAutonomousStopHookTopicKeyed` re-deploy is marker-gated and
+  fingerprint-guarded, so a customized `SKILL.md` (missing the stock
+  `ALL_TASKS_COMPLETE` fingerprint) is left untouched — verified by test.
+- **External systems (Telegram/Slack/GitHub/Cloudflare):** none.
+- **Persistent state:** `.claude/settings.json` and the deployed `SKILL.md`. The
+  edit is convergent (always lands on the one correct entry), so re-running is safe.
+- **Timing/runtime:** none — the migration is synchronous on the existing update path.
+
+---
+
+## 7. Rollback cost
+
+Pure code + template change. Back-out is `git revert` + ship the next patch. There
+is one consideration: this migration *writes a corrected entry* into existing
+agents' `settings.json`. A revert would stop applying the correction but would NOT
+re-break already-corrected agents (the correct path resolves to a real file, so a
+reverted build leaves them working). No data migration, no agent reset, no
+user-visible regression during the rollback window. Worst case of the fix itself
+being wrong: an agent ends up with a Stop-hook entry pointing at the skill path —
+which is exactly where the file lives — so the failure mode of the fix is "it
+works".
+
+---
+
+## Conclusion
+
+The review produced no design changes. The fix is a narrow, deterministic path
+correction with a self-healing registrar and an in-place repair migration that
+satisfies the Migration Parity Standard for both the `settings.json` entry and the
+deployed skill prompt. The only decision surface is a fixed path string, the
+repair is idempotent and convergent, and the customized-prompt guard is preserved.
+Clear to ship.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** Echo (self) — Tier-1 fix, single-pass per the tiered process.
+**Independent read of the artifact: concur**
+
+The change has no message-gating surface, the repair-before-presence-check
+ordering is the load-bearing correctness point and is tested, and the Migration
+Parity obligations (settings repair + marker-gated SKILL.md re-deploy + customized
+guard) are all covered. No concerns.
+
+---
+
+## Evidence pointers
+
+- `tests/unit/PostUpdateMigrator-autonomousHookPath.test.ts` — 9 tests (repair,
+  no-duplicate, sibling-preservation, no-op-when-correct, register-when-missing,
+  idempotency, SKILL.md content marker, topic-keyed re-deploy + customized-skip).
+- Empirical SKILL.md snippet run against a wrong-path settings fixture: wrong entry
+  rewritten to the skill path, siblings preserved, second run idempotent.
+- Regression: `autonomous-skill-deployment`, `PostUpdateMigrator-buildStopHook`,
+  `autonomous-stop-hook-notify`, `installCodexHooks`, `emit-session-clock` — 50
+  tests green. `tsc --noEmit` clean.

package/upgrades/side-effects/iris-audit-token-accounting.md

@@ -0,0 +1,125 @@
+# Side-Effects Review — Iris-audit token usage accounting (PR B: item 1)
+
+**Version / slug:** `iris-audit-token-accounting`
+**Date:** `2026-06-02`
+**Author:** `echo`
+**Second-pass reviewer:** `convergence reviewers (shared spec) — concur`
+
+## Summary of the change
+
+PR B of the Iris-audit spec (`docs/specs/iris-audit-session-observability.md`), item
+1: make `/metrics/features` report real per-feature token usage instead of always 0.
+`ClaudeCliIntelligenceProvider` switches `claude -p` from `--output-format text` to
+`json` and parses the result object for the answer (`.result`) and `usage`; a new
+additive optional `onUsage` callback on `IntelligenceOptions` surfaces the token
+counts. `CircuitBreakingIntelligenceProvider` (the universal LLM funnel) passes an
+`onUsage` that captures usage and forwards `tokensIn/tokensOut` into the existing
+`FeatureMetricsLedger` tap. Files: `src/core/types.ts`, `src/core/
+ClaudeCliIntelligenceProvider.ts`, `src/core/CircuitBreakingIntelligenceProvider.ts`,
+plus tests. The decision points touched are observability-only — no gate changes.
+
+## Decision-point inventory
+
+- `IntelligenceOptions.onUsage` (types.ts) — **add** — optional callback; no decision
+  logic.
+- `ClaudeCliIntelligenceProvider.evaluate` output parsing (ClaudeCliIntelligence
+  Provider.ts) — **modify** — text→json + `parseJsonResult`; affects the return-value
+  extraction for EVERY Claude-backed LLM call, but the returned text is unchanged.
+- `CircuitBreakingIntelligenceProvider` metrics tap (CircuitBreakingIntelligence
+  Provider.ts) — **modify** — now forwards token counts; observability only.
+
+## 1. Over-block
+
+No block/allow surface — over-block not applicable. This is pure observability
+plumbing; nothing is rejected.
+
+## 2. Under-block
+
+No block/allow surface — under-block not applicable. (If usage is ever absent or
+unparseable, the only effect is that a call's token cost is omitted — recorded as the
+pre-existing 0/null — never a wrong block.)
+
+## 3. Level-of-abstraction fit
+
+Right layer. Token usage originates in the provider that runs the CLI
+(`ClaudeCliIntelligenceProvider`) — the only place it exists — and is surfaced via the
+same `IntelligenceOptions` contract every provider already takes. The funnel
+(`CircuitBreakingIntelligenceProvider`) is the established single chokepoint that
+already records the per-feature metric; threading tokens through it instruments ALL
+LLM features at once (Structure > Willpower) rather than each call site. The ledger is
+reused unchanged (it already had token columns waiting for data).
+
+## 4. Signal vs authority compliance
+
+**Required reference:** docs/signal-vs-authority.md
+
+- [x] No — this change has no block/allow surface (it is observability: a signal
+  producer feeding the metrics ledger).
+
+The metrics ledger is a read-only signal surface (`/metrics/features`); it never gates.
+Token accounting strictly adds data; it holds no authority.
+
+## 5. Interactions
+
+- **Shadowing:** none — parsing happens inside `evaluate`'s existing resolve path; no
+  new check before/after another.
+- **Double-fire:** `onUsage` fires at most once per successful call (only when usage
+  is present with non-zero tokens); the funnel composes with (does not clobber) any
+  caller-supplied `onUsage`.
+- **Races:** none — synchronous parse within the call's own callback.
+- **Feedback loops:** none — recorded metrics are read-only; nothing consumes them to
+  re-drive an LLM call.
+
+## 6. External surfaces
+
+- **The claude CLI invocation changes** from `--output-format text` to `json`. This is
+  the load-bearing risk: the return value is now extracted from `.result`. Mitigation:
+  `parseJsonResult` is defensive — non-JSON or missing `.result` falls back to the raw
+  trimmed stdout (the prior behavior), so a malformed/partial response degrades to
+  "answer without token accounting," never a crash or a JSON blob leaking to callers.
+  The empirical CLI shape was verified live (`{ result, usage:{ input_tokens,
+  cache_creation_input_tokens, cache_read_input_tokens, output_tokens } }`).
+- **Rate-limit detection unaffected:** the circuit breaker's classifier reads
+  `stderr`, not stdout — the format switch does not touch it (verified in the provider;
+  the error path is unchanged).
+- **Other agents / install base:** ships fleet-wide via update; every LLM-backed
+  feature's calls now carry token counts into `/metrics/features`. No behavior change
+  to what those features decide — only the cost telemetry becomes real.
+- **Persistent state:** writes to the existing `FeatureMetricsLedger` SQLite token
+  columns (previously always null); no schema change (columns already existed).
+
+## 7. Rollback cost
+
+- **Hot-fix release:** pure code revert shipped as the next patch (revert the three
+  core files). No persistent-state migration — the ledger columns simply return to
+  null. No agent-state repair, no user-visible regression.
+- The only externally-observable change is `claude -p --output-format json`; reverting
+  restores `text`. Because `parseJsonResult` already tolerates non-JSON, even a partial
+  rollout (some agents on json, some on text) is safe.
+
+## Conclusion
+
+The review produced no design changes — the change is additive, observability-only, and
+defensively parsed. The single real risk (the CLI output-format switch) is contained by
+the raw-stdout fallback and verified against the live CLI shape. Clear to ship. This is
+the sibling of PR A under the same converged + approved spec.
+
+## Second-pass review (if required)
+
+**Reviewer:** the 3 spec convergence reviewers (shared spec) — concur on item 1's
+design (additive onUsage side-channel, no evaluate() return-type change). The one
+open question they raised — does onUsage fire on cache-only reads — is resolved here:
+`parseJsonResult` sums cache_read/cache_creation INTO tokensIn (they are real input
+cost) and fires whenever any count is non-zero, so cache-dominated calls are counted,
+not dropped.
+
+## Evidence pointers
+
+- `tests/unit/ClaudeCliIntelligenceProvider-jsonParse.test.ts` — parser contract
+  (extract .result, sum input components, defensive fallbacks, onUsage firing rules).
+- `tests/unit/CircuitBreaking-feature-metrics-tap.test.ts` — funnel forwards tokens to
+  the recorder, composes with caller onUsage, omits when absent, and sums into the real
+  ledger rollup (tokensIn/tokensOut no longer 0).
+- Live CLI shape verified: `claude -p --model haiku --output-format json` →
+  `{ result:"ok", usage:{ input_tokens:10, output_tokens:41, ... } }`.
+- `tsc --noEmit` clean.