instar 1.3.210 → 1.3.212

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/1.3.212.md

@@ -0,0 +1,65 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+A codex conversational session can wedge: the server is healthy and messages are
+delivered, but the session sits paused with an injected message stuck at the
+prompt, never draining into a turn. `StuckInputSentinel` already detects this
+(marker-based), but its recovery topped out at keypresses — which, live, weren't
+enough; the session needed a full server restart + queue replay, performed by
+hand. This adds an **escalating self-recovery** so a codex session heals itself
+with no external nudge.
+
+The hard part is a process boundary: the detector (`StuckInputSentinel`) runs in
+the server process, but the restart authority (`ServerSupervisor` + queue replay)
+runs in the lifeline process. So the fix is split cleanly:
+
+- **`SessionRecoveryChannel`** — a cross-process request/ack channel. The server
+  emits recovery requests (sole writer of the request file); the lifeline writes
+  acks (sole writer of the ack file) — single-writer-per-file, atomic, so the two
+  processes never race.
+- **Sentinel escalation** — after the keypress ladder exhausts but the marker is
+  still stuck, the sentinel requests a tier-C recovery, polls the ack, verifies,
+  and bounds the wait (no restart loop).
+- **`SessionRecoveryConsumer`** (lifeline) — reads tier-C requests and performs
+  `performGracefulRestart` + `replayQueue`, dry-run-first, guarded by a **durable**
+  cooldown (a server restart wipes the sentinel's in-memory bound, so the loop
+  guard has to survive the restart).
+
+Ships **dark** behind `monitoring.codexWedgeRecovery` (default off; `dryRun:true`
+first). With no config it is byte-for-byte the legacy behavior.
+
+## What to Tell Your User
+
+When one of my codex-driven sessions gets stuck — paused with a message that never
+turns into a reply — I can now work myself loose without anyone stepping in:
+first by nudging the prompt, and if that is not enough, by cleanly restarting my
+own server and replaying the queued message. It is turned off by default and ships
+in a watch-only dry-run mode first, with a built-in cooldown so it can never get
+into a restart loop. You decide when to turn it on.
+
+## Summary of New Capabilities
+
+- A codex session that wedges (input delivered, not draining) can self-recover by
+  escalating from keypresses to a server restart + queue replay — no external agent.
+- The escalation is bounded and has a durable cross-restart cooldown, so a wedge
+  that a restart can't fix can never cause a restart loop.
+- Ships dark + dry-run on the Graduated-Feature-Rollout track
+  (`monitoring.codexWedgeRecovery`); absence of config = off, so no migration is
+  needed and existing agents are unaffected until explicitly enabled.
+
+## Evidence
+
+- 78 tests across 3 tiers: unit (`SessionRecoveryChannel` 15, `StuckInputSentinel`
+  escalation 7, `SessionRecoveryConsumer` 8, plus the existing stuck-input suites)
+  + integration (`tests/integration/codex-wedge-recovery.test.ts` 3 — the full
+  sentinel→channel→consumer→ack→sentinel loop through the real channel, live +
+  dry-run + dark-disabled paths).
+- `tsc --noEmit` clean; `pnpm build` clean.
+- Dark-by-default verified: with no config, the sentinel never escalates and the
+  lifeline never starts the consumer (asserted in unit + integration).
+- Spec: `docs/specs/CODEX-SESSION-WEDGE-SELF-RECOVERY.md` (grounded gap-analysis +
+  cross-process design + the durable-cooldown finding + the increment plan).

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/codex-wedge-self-recovery.md

@@ -0,0 +1,162 @@
+# Side-Effects Review — Codex session-wedge self-recovery
+
+**Version / slug:** `codex-wedge-self-recovery`
+**Date:** `2026-06-03`
+**Author:** `Echo`
+**Second-pass reviewer:** `Echo (self) — Tier-2, single-pass under standing preapproval; ships dark`
+
+## Summary of the change
+
+Adds an escalating self-recovery for wedged codex sessions (input delivered but
+not draining). The detector (`StuckInputSentinel`, server process) escalates past
+the keypress ladder by requesting a tier-C recovery — a server restart + queue
+replay — which is executed by a new lifeline-process consumer
+(`SessionRecoveryConsumer`), because `ServerSupervisor` lives in the lifeline. The
+two processes communicate through a new on-disk `SessionRecoveryChannel`
+(single-writer-per-file request + ack + cooldown). Files: `SessionRecoveryChannel.ts`
+(new), `SessionRecoveryConsumer.ts` (new), `StuckInputSentinel.ts` (escalation state
+machine + recovered-request cleanup), `types.ts` (config shape), `server.ts` +
+`TelegramLifeline.ts` (wiring). Highest-blast-radius decision point: **whether to
+restart the agent server.** Ships dark (`monitoring.codexWedgeRecovery`, default
+off + dryRun).
+
+## Decision-point inventory
+
+- `StuckInputSentinel exhausted-record path` — modify — after the keypress ladder,
+  escalate (request tier C) instead of stopping, when enabled.
+- `SessionRecoveryConsumer.handle` — add — decides whether to restart the server
+  for a given request (cooldown + dedup + dry-run gates).
+- `monitoring.codexWedgeRecovery` config gate — add — master enable + dryRun +
+  cooldown + timeout. Default off.
+- No message block/allow decision point is touched.
+
+---
+
+## 1. Over-block
+
+No message block/allow surface — over-block not applicable. The closest analogue
+is "would it restart a server it shouldn't?" Guards against that: it only fires
+when (a) the config is enabled, (b) a codex marker is stuck past the keypress
+ladder (≥ minTicks + maxAttempts keypresses all failed), and (c) the durable
+cooldown is clear. In dry-run (the shipping default) it never restarts at all.
+
+---
+
+## 2. Under-block
+
+No message block/allow surface. Failure-to-recover modes it still misses: a wedge
+whose pane signature the marker-based detector doesn't recognize won't escalate
+(out of scope — detection is unchanged); a wedge that a server restart genuinely
+can't fix will restart once, hit the cooldown, ack failed, and stop (by design —
+bounded, not infinite). Tier B (a gentler server-side message re-inject before the
+restart) is a documented planned refinement, not in this cut.
+
+---
+
+## 3. Level-of-abstraction fit
+
+Correct layering, and it was the central design question. Detection is a low-level
+signal in the server; the restart is a high-level authority in the lifeline. They
+are split across the real process boundary via the channel rather than forcing the
+sentinel to reach across it. Reuses existing primitives (`fireStuckInputRecovery`,
+`ServerSupervisor.performGracefulRestart`, `replayQueue`) instead of reimplementing
+them.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — this change has no message block/allow surface.
+
+This is the textbook Signal-vs-Authority split: the sentinel emits a SIGNAL (a
+recovery request); the lifeline holds the AUTHORITY to act on it (or decline, via
+cooldown/dry-run). The sentinel never restarts anything; the consumer is the only
+actor, and it is gated.
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** The escalation hangs off the END of the existing keypress ladder —
+  it only runs after `attempts >= maxAttempts`, so it never shadows the keypress
+  recovery (that still runs first, unchanged). The lifeline consumer runs on its own
+  15s interval alongside the existing replay + restart-signal intervals; it acts
+  only on tier-C requests, so it can't interfere with version-skew restart signals
+  (different file, different tier).
+- **Double-fire:** The consumer dedups on `(sessionId, attemptId)` (terminal ack →
+  skip) and records the restart durably BEFORE acting, so a crash mid-restart still
+  counts against the cooldown. The sentinel won't emit a second request while one is
+  in flight (idempotent by attemptId).
+- **Races:** Single-writer-per-file (server owns request + cooldown-trigger via the
+  sentinel's clears; lifeline owns ack + cooldown record) — no cross-process write
+  contention. Atomic writes via SafeFsExecutor.
+- **Feedback loops:** THE risk for this feature — a tier-C restart wipes the
+  sentinel's in-memory escalation bound, so a still-stuck session could re-detect →
+  re-restart forever. Closed by the DURABLE cooldown the lifeline checks before every
+  restart (the sentinel's in-memory bound is no longer load-bearing across restarts).
+  Unit-tested explicitly (cooldown blocks the second restart; allows it after the
+  window).
+
+---
+
+## 6. External surfaces
+
+- **Other agents / users:** none — per-agent state files + per-agent processes.
+- **External systems:** none (Telegram/Slack/GitHub untouched). The server restart
+  is the agent restarting itself — the same action the auto-updater + `/lifeline
+  restart` already perform; it briefly drops the local API/dashboard while the
+  server bounces (seconds), then queue replay re-delivers. This only happens when
+  the feature is enabled AND not in dry-run.
+- **Persistent state:** three new small JSON files under `state/`
+  (`session-recovery-requested/acked/cooldown.json`). Inert when the feature is off.
+- **Timing:** the consumer ticks every 15s only when enabled.
+
+---
+
+## 7. Rollback cost
+
+Pure code + new files; the feature is dark by default. Back-out is `git revert` +
+ship the next patch — nothing to undo on existing agents because nothing runs
+until `monitoring.codexWedgeRecovery.enabled` is set (which no agent has). The new
+state files are only written when enabled and are inert otherwise. No data
+migration, no user-visible regression. Disabling live is a config flip (set
+`enabled:false` or `dryRun:true`).
+
+---
+
+## Conclusion
+
+The review's central concern — the restart-loop feedback path — was found DURING
+the build (a tier-C restart wipes the in-memory bound) and closed with a durable
+cooldown, which is the load-bearing safety mechanism and is unit-tested. The
+feature ships dark + dry-run on the Graduated-Feature-Rollout track, with the only
+high-blast-radius action (server restart) gated four ways (config enabled, not
+dry-run, past the keypress ladder, cooldown clear) and bounded. Clear to ship as a
+dark feature for review; enabling (dry-run → live) is a deliberate, reversible
+config decision for the operator.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** Echo (self) — Tier-2, ships dark; recommend a dry-run soak before live.
+**Independent read of the artifact: concur**
+
+The Signal-vs-Authority split is clean, the restart-loop guard is durable and
+tested, dark-by-default is verified in both unit and integration tiers, and the
+rollback cost is a revert. One flagged follow-up (not blocking): add tier B (a
+server-side message re-inject) as a gentler step before the restart, to reduce how
+often tier C fires once this soaks.
+
+---
+
+## Evidence pointers
+
+- `tests/unit/SessionRecoveryChannel.test.ts` (15), `tests/unit/StuckInputSentinel-escalation.test.ts` (7),
+  `tests/unit/SessionRecoveryConsumer.test.ts` (8), `tests/integration/codex-wedge-recovery.test.ts` (3),
+  plus existing stuck-input suites — 78 total green.
+- `docs/specs/CODEX-SESSION-WEDGE-SELF-RECOVERY.md` — design, cross-process
+  constraint, durable-cooldown finding, increment plan.
+- `tsc --noEmit` + `pnpm build` clean.