instar 1.3.359 → 1.3.361

package/upgrades/projects-mergebranch-resolve.eli16.md

@@ -0,0 +1,11 @@
+# Projects "merged" check now works on dev-agent homes too
+
+Tonight's #866 fix wired the GitHub-PR verification into the projects pipeline's "building → merged" step — and it works: it resolves the PR, confirms it merged, gets the merge commit. But the very next check then failed on a dev-agent machine: the validator confirms the merge commit is actually on the main branch by checking "origin/main". On a normal install that's right. On a developer agent's home checkout, though, "origin" points at the agent's personal FORK, while the real merges land on the UPSTREAM repo under a differently-named remote. So origin/main never contains the commit, and every attempt to record a step as merged failed with "commit not reachable from origin/main" — even though the PR genuinely merged.
+
+This is a sibling of the same class as #866: code that assumed the common-case environment and broke on the dev-agent's fork-origin layout. I hit it the moment #866's fix let me get that far — trying to mark this very initiative's own rounds merged.
+
+The fix: instead of hardcoding "origin/main", the route now asks GitHub which repo it's actually talking to (the same repo the PR-view reads), finds the LOCAL remote whose URL points at that repo, and checks "<that-remote>/main". On a normal install that resolves right back to origin/main (unchanged behavior); on a fork-origin agent home it correctly resolves to the upstream remote where the merges live. Both lookups are read-only (a GitHub repo-view and a git remote listing).
+
+With this, the projects pipeline can finally record merged steps on the machines we actually develop on — which is the whole point of being able to track an initiative through to "merged."
+
+_Follow-up note: on any lookup error the resolver simply uses the standard default — by design, not as a failure._

package/upgrades/side-effects/lifecycle-narration-silencing.md

@@ -0,0 +1,29 @@
+# Side Effects — lifecycle-narration-silencing
+
+## Files touched
+
+- `src/monitoring/SessionRecovery.ts` — `RecoveryResult` gains optional `deferred?: boolean`; the four work-check deferral returns (stall / context_exhaustion / crash / error_loop) now set `deferred: true`. No behavior change inside SessionRecovery itself (same returns, one new field).
+- `src/monitoring/SessionMonitor.ts` — context-exhaustion path: (a) a deferred recovery is now SILENT to the user (log + new `monitor:recovery-deferred` event only); (b) genuine-failure notification dedups per session instance via a new `ctxNotifiedSessions` map (topicId → sessionName), cleared on successful recovery. New event added to `SessionMonitorEvents`.
+- `.claude/skills/autonomous/hooks/autonomous-stop-hook.sh` — the restart-resume note is no longer delivered to the user topic (marker `RESTART_NOTE_SILENT`); the RECOVERY_AUDIT JSONL write and stderr log remain. `deliver_recovery_note()` retained for future user-actionable notes.
+- `src/core/PostUpdateMigrator.ts` — stop-hook migration marker bumped `CLOCK_SEG` → `RESTART_NOTE_SILENT` so existing agents receive the silenced hook (customized hooks still untouched).
+- `docs/STANDARDS-REGISTRY.md` — Near-Silent Notifications sharpened with the self-lifecycle clause + the 2026-06-06 earned-from instance (no new article; extension of the existing one, per no-bloat).
+
+## Behavioral side effects
+
+1. **Users stop receiving** "Session hit conversation too long…" messages when the session is actually alive (recovery deferred). This was 29+ false death reports in one day. A genuinely dead, unrecoverable session still notifies — once per death, not once per cooldown window.
+2. **Users stop receiving** "my session restarted mid-run… no action needed" notes entirely. The durable record moves to `*-recovery-audit.jsonl` + stderr only.
+3. **Fewer triage/respawn confusions:** sessions falsely marked `dead` by the monitor (snap.status) on deferrals stay in their true state.
+4. **Migration:** every existing agent's stop-hook is overwritten at next migration run (marker bump); agents with customized hooks are skipped (existing fingerprint guard).
+
+## Risks / blast radius
+
+- If `hasActiveProcesses` ever returns a false positive (claims children for a dead session), the deferral-silence would suppress a legitimate death notice. Mitigation: that read already gated the kill itself (a false positive there already deferred recovery before this PR); the per-episode dedup map also resets on session-name change, so a respawned session's real death still announces.
+- The `ctxNotifiedSessions` map is in-memory; a server restart clears it, so one duplicate death notice is possible across a restart. Accepted: bounded to one per restart, vs. unbounded repeats before.
+- Stop-hook silencing removes the only push signal that a respawn happened; operators who relied on it must use the recovery-audit JSONL (documented in the eli16 + fragment).
+
+## Tests
+
+- `tests/unit/SessionRecovery.test.ts` — deferral carries `deferred: true` + does not kill; genuine recovery carries no `deferred` (2 new).
+- `tests/unit/SessionMonitor.test.ts` — deferred → no sendToTopic + `monitor:recovery-deferred` emitted; genuine failure notifies once per session instance across cooldown windows; successful recovery clears the episode (3 new).
+- `tests/unit/autonomous-stop-hook-notify.test.ts` — marker assertion updated to `RESTART_NOTE_SILENT`; new test asserts the restart-resume block keeps the audit write but has no user delivery and the old note text is gone.
+- Existing suites: `autonomous-stop-hook-topic-keyed` (audit semantics) and `autonomous-restart-resume-lifecycle` e2e (audit count) pass unchanged — the audit behavior they assert is preserved.

package/upgrades/side-effects/projects-mergebranch-resolve.md

@@ -0,0 +1,53 @@
+# Side-Effects Review — projects merge-base branch resolution (#866 sibling)
+
+**Version / slug:** `projects-mergebranch-resolve`
+**Date:** `2026-06-06`
+**Author:** `echo`
+**Second-pass reviewer:** `not required — small read-only environment fix + unit coverage`
+
+## Summary of the change
+
+After #866 wired ghPrView, the `building → merged` gate's NEXT check —
+`gitMergeBaseIsAncestor(oid, 'origin/main')` — failed on fork-origin dev-agent
+homes: `origin` is the agent's fork (instar-echo) while merges land on the
+upstream remote (JKHeadley/instar), so origin/main never contains the merge
+commit (MERGE_COMMIT_UNREACHABLE). Fix: `StageTransitionValidator` reads the
+branch from a new `ctx.mergeBaseBranch` (default `origin/main`, behavior
+preserved); the route computes it via `resolveCanonicalMainRef()` — asks gh
+which repo it resolves for the cwd, maps that to the local remote whose URL
+matches, returns `<remote>/main`, falling back to `origin/main`.
+
+## Decision-point inventory
+- `building → merged` merge-base check — was hardcoded `origin/main`, now uses the resolved canonical-main ref. The check's logic is unchanged; only the ref it compares against is now environment-correct.
+
+## 1. Over-block
+Before: fork-origin homes 100% over-blocked (every merged transition rejected though the PR merged). After: rejects only when the commit truly isn't on the canonical main. Strict improvement. Canonical-origin installs unchanged (resolves to origin/main).
+
+## 2. Under-block
+If gh/remote resolution misfires it falls back to `origin/main` (the prior behavior) — never a more-permissive ref, so no new under-block. The resolved remote must actually contain the commit or the gate still rejects.
+
+## 3. Level-of-abstraction fit
+Validator stays pure (takes the branch as input); the environment resolution lives in the route (where gh/git + cwd are). Right seam — mirrors how #866 injected the helpers.
+
+## 4. Signal vs authority compliance
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+- [x] No — the gate remains a real check (commit reachability on canonical main); this only supplies the correct ref.
+
+## 5. Interactions
+- `resolveCanonicalMainRef` is read-only: `gh repo view` (gh, not funnel-gated) + `git remote -v` via SafeGitExecutor.readSync (`remote` is a READONLY_GIT_VERB, shape-checked list/get-url only).
+- Any failure → fallback `origin/main`; never throws into the route.
+- No interaction with the other advance edges (outline→spec, etc.) — only the merged edge reads mergeBaseBranch.
+
+## 6. External surfaces
+- Spawns `gh repo view` + `git remote -v` against the project target repo when a merged transition is attempted. No persistent state, no messaging, no fleet surface.
+
+## 7. Rollback cost
+Pure code revert + patch. No state.
+
+## Conclusion
+Completes the #866 chain: the projects pipeline can now record merged steps on dev-agent homes (fork-origin) as well as canonical-origin installs. Clear to ship.
+
+## Evidence pointers
+- `tests/unit/StageTransitionValidator.test.ts` — new cases: helper called with the configured `mergeBaseBranch` (not origin/main); unreachable error names the configured branch. 28 validator tests + 45 projects-api green; tsc + destructive-lint clean.
+
+_Follow-up: the resolver catch carries an `@silent-fallback-ok` note — falling back to the `origin/main` default is the conservative behavior this resolver refines, not a swallowed error._