instar 1.3.129 → 1.3.131

package/upgrades/1.3.130.md

@@ -0,0 +1,74 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+**The SessionReaper now reaps under CPU pressure, not only memory — and keeps a
+silent, reviewable record of every decision it makes.**
+
+The idle-session reaper used to compute its pressure tier purely from free
+memory. But on a busy multi-agent box the real squeeze is almost always CPU, not
+RAM (free memory can look fine while the load average is well past the core
+count). So an idle session could sit holding CPU baseline indefinitely and the
+reaper, watching only memory, would never wake up.
+
+Pressure is now the WORST of two signals: memory (free %) and CPU (1-minute load
+average ÷ core count). A CPU-bound box raises the tier even when memory is fine,
+so genuinely-idle sessions become eligible under load — while the reaper's
+positive-idle proof, hysteresis, confirmation window, rate limits, and grace
+period are all unchanged, so it still never reaps a working session. The two CPU
+thresholds are configurable; sensible defaults ship (moderate at 1.0 load per
+core, critical at 1.5), and a transient build spike won't trigger a reaping spree
+because the existing 3-observation confirmation smooths it.
+
+Second, the reaper now writes a dedicated decision audit trail. Previously its
+structured events were mixed into the shared sentinel log and only covered the
+reap path — there was no record of the routine keep decisions, so "what is the
+reaper considering, and why?" had no grounded answer. It now logs every keep/kill
+decision change (on transition, not every tick, so a multi-day kept session logs
+once) plus the reap-path events, each stamped with the pressure tier that drove
+it, to a dedicated file readable through a new read-only endpoint.
+
+## What to Tell Your User
+
+Nothing to configure. Your idle-session cleanup is now aware of CPU load, not
+just memory — so on a busy machine it can finally relieve pressure that free
+memory alone would have hidden. It is still just as careful: it never touches a
+session that might be working. You can also now ask me what the cleanup is
+considering and why it kept or shut down any session — there is a quiet,
+inspectable decision log behind it. None of this sends you notifications; it is
+all there for when you want to look.
+
+## Summary of New Capabilities
+
+- Reaper pressure is CPU-aware: tier is the worst of memory (free %) and CPU
+  (1-min load ÷ cores), via the new pure `computePressure()` classifier.
+- Two new tunable thresholds: `cpuModerateLoadPerCore` (default 1.0) and
+  `cpuCriticalLoadPerCore` (default 1.5) under `monitoring.sessionReaper`.
+  Existing agents receive them automatically via the canonical config defaults.
+- `GET /sessions/reaper`'s `pressure.inputs` now exposes `freePct`,
+  `loadPerCore`, and the `memTier`/`cpuTier` breakdown.
+- New read-only endpoint `GET /sessions/reaper/audit?limit=N` returns the tail
+  of the dedicated decision trail at `logs/reaper-audit.jsonl`.
+- A `decision` audit row is written on first sight and on every (verdict,
+  keptBy) change — transition-only, so no per-tick log spam. Silent: no Telegram,
+  no attention items.
+
+## Evidence
+
+- `tests/unit/session-reaper-pressure-audit.test.ts` — new: `computePressure`
+  (memory-only when cores unknown, CPU-raises-tier, worst-of combos, custom
+  thresholds, non-finite load ignored); the `reaperAuditSink`/`readReaperAudit`
+  round-trip (bounded tail, `[]` when absent); and the transition-only decision
+  audit (logs on first sight + on change, not when unchanged).
+- `tests/integration/session-reaper-routes.test.ts` — new: `GET
+  /sessions/reaper/audit` returns 200 with the tail, honors `?limit`, and `[]`
+  when no trail exists.
+- `tests/e2e/session-reaper-lifecycle.test.ts` — new Phase-1 "feature alive"
+  test: the audit route returns 200 (not 503) through the real AgentServer
+  plumbing and reads a written row back.
+- `tests/unit/feature-delivery-completeness.test.ts` + `capabilities-discoverability.test.ts`
+  green: migrator parity (new `migrateClaudeMd` section), config parity, and
+  route classification all satisfied.
+- Full `npm run lint` + the reaper test tiers pass.

package/upgrades/1.3.131.md

@@ -0,0 +1,56 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+**Agent worktrees are now excluded from macOS Spotlight indexing — a top
+OS-level CPU drain on multi-worktree machines.**
+
+Each `instar worktree create` leaves a full source tree on disk under the agent's
+`.worktrees/` directory. macOS Spotlight (mds_stores) and mediaanalysisd treat
+every one of those trees as new content to index and re-index — and on a machine
+that has accumulated dozens of worktrees that becomes one of the single biggest
+CPU consumers on the box (measured: mediaanalysisd pulling ~80% CPU under a
+~120-worktree backlog), entirely separate from anything instar's own code is
+doing.
+
+instar now drops a single `.metadata_never_index` marker at the `.worktrees/`
+container root, which tells Spotlight to skip that whole subtree. New worktrees
+are covered automatically at creation time, and existing agents get the marker
+backfilled on update via a new migration. The marker lives at the container (not
+inside any worktree, so it adds no git noise), is honored recursively for every
+worktree beneath it, is harmless on non-macOS, and is idempotent.
+
+This is the first piece of the **OS resource hygiene** facet of the Responsible
+Resource Usage standard.
+
+## What to Tell Your User
+
+Nothing to configure. On a Mac, the throwaway worktrees instar creates for
+parallel development will no longer be re-indexed by Spotlight — which quietly
+removes a large chunk of background CPU load that had nothing to do with your
+agents actually working. If you have built up a lot of worktrees over time, you
+should feel this as lower idle CPU after the update settles.
+
+## Summary of New Capabilities
+
+- `instar worktree create` (and the convention wrapper's fallback path) drop a
+  `.metadata_never_index` marker at the `.worktrees/` container so Spotlight skips
+  indexing every worktree under it.
+- New exported helper `ensureWorktreeSpotlightExclusion(worktreesDir)` — idempotent,
+  best-effort, never throws, returns whether it created the marker.
+- New `PostUpdateMigrator.migrateWorktreeSpotlightExclusion` backfills the marker
+  into existing agents' `.worktrees/` on update.
+
+## Evidence
+
+- `tests/unit/worktree-spotlight-exclusion.test.ts` — new: the helper (creates the
+  marker, idempotent return, never throws on an unwritable path) and the migration
+  backfill (drops the marker into an existing `.worktrees/`, idempotent on re-run).
+- `tests/unit/InstarWorktreeManager.test.ts` + `migrateWorktreeConvention.test.ts`
+  still green (the `ensureWorktreesDir` hook + always-overwrite wrapper unchanged
+  in behavior).
+- Operationally verified live: dropping the marker on echo's real 121-worktree
+  `.worktrees/` directory; mediaanalysisd dropped from its earlier ~80% spike.
+- Full `npm run lint` clean.

package/upgrades/side-effects/sessionreaper-cpu-aware-and-decision-audit.md

@@ -0,0 +1,122 @@
+# Side-Effects Review — SessionReaper CPU-aware pressure + decision audit
+
+**Version / slug:** `sessionreaper-cpu-aware-and-decision-audit`
+**Date:** `2026-05-30`
+**Author:** `echo`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+The idle-session reaper's pressure tier was computed from free memory only. This
+change makes it the WORST of memory (free %) and CPU (1-min load ÷ cores) via a
+new pure `computePressure()` classifier, with two tunable thresholds
+(`cpuModerateLoadPerCore` 1.0 / `cpuCriticalLoadPerCore` 1.5) auto-migrated to
+existing agents. It also adds a silent decision audit: every keep/kill decision
+*change* + the reap-path events land in `logs/reaper-audit.jsonl`, served
+read-only at `GET /sessions/reaper/audit`.
+
+## Decision-point inventory
+
+- **Pressure tier computation** (existing decision, widened): now also keys on CPU
+  load. Gates *when* the reaper may consider acting.
+- **Decision audit emission** (new, zero-authority signal): writes an observability
+  row on `(verdict, keptBy)` transitions. No control-flow effect.
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+CPU-awareness can raise the tier from `normal` to `moderate`/`critical` during a
+load spike, making genuinely-idle sessions eligible sooner. It cannot cause a
+*working* session to be reaped: the kill path still requires the full positive-idle
+proof, transcript-stasis, render-stasis, 3-observation hysteresis over the
+confirmation window, the two-phase reap, and the per-tick/per-hour budget — all
+unchanged. A transient build spike is smoothed by the multi-observation
+requirement. Default thresholds (1.0/1.5 load-per-core) are deliberately at/above
+full subscription so "moderate" means genuinely oversubscribed.
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+`os.loadavg()` is a trailing 1-minute average, so a very brief CPU famine may not
+register, and a famine caused by non-session processes still only lets the reaper
+trim *idle* sessions (it cannot reduce the load of the busy processes themselves).
+This is acceptable — the reaper is one lever among several (load-shed, hosting
+migration, tool/agent sleep); it is not meant to be a complete CPU governor.
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. Pressure sensing belongs in the reaper's injected `pressure()` provider; the
+pure classifier lives next to the reaper and is unit-tested without `os`. The audit
+is a sink/reader pair beside the existing `fileAuditSink`, mirroring the
+`/sessions/reap-log` read-surface pattern. No business logic leaks into routes.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+**Does this change hold blocking authority with brittle logic?**
+
+No new blocking authority. The reaper remains the authority it already was; this
+change does not add a brittle check that gates behavior — it widens an existing,
+heavily-confirmed kill path's *eligibility window*, and every safety gate still has
+to clear independently. The decision audit is a pure signal producer (write-only
+observability) with zero authority. `computePressure` is total: unknown/non-finite
+CPU input degrades to the prior memory-only behavior rather than failing.
+
+## 5. Interactions
+
+**Does this interact with existing checks, recovery paths, or infrastructure?**
+
+- Reads the same `monitoring.sessionReaper` config block; two additive fields.
+- `reapNotify`, the reap-log (`/sessions/reap-log`), and the silently-stopped
+  sentinels are untouched; the new audit writes a SEPARATE file
+  (`reaper-audit.jsonl`), so nothing reading `sentinel-events.jsonl` is affected.
+  (Reaper events previously co-mingled there now route to the dedicated file —
+  reviewed: no consumer filters `sentinel-events.jsonl` for `kind:'session-reaper'`.)
+- Migration: canonical config defaults (`applyDefaults` deep-merge) + a
+  content-sniffed `migrateClaudeMd` section; both idempotent.
+
+## 6. External surfaces
+
+**Does this change anything visible outside the immediate code path?**
+
+One new read-only HTTP route (`GET /sessions/reaper/audit`, Bearer-auth, classified
+in the capabilities-discoverability lint). `GET /sessions/reaper`'s `pressure.inputs`
+gains `loadPerCore`/`memTier`/`cpuTier` fields (additive). One new on-disk file
+(`logs/reaper-audit.jsonl`). No Telegram, no attention items, no notifications.
+
+## 7. Rollback cost
+
+**If this turns out wrong in production, what's the back-out?**
+
+Cheap and layered. (a) Operationally, set the CPU thresholds absurdly high to
+neutralize CPU-awareness with no deploy; the audit is write-only and harmless to
+ignore. (b) A full revert of the PR restores the prior behavior exactly (the change
+is additive). No data migration, no schema change, no irreversible state.
+
+## Conclusion
+
+Low-risk, additive, reversible. The safety-critical "never reap a working session"
+contract is untouched; the change only widens *when* the existing gated path may
+act and adds zero-authority observability. Ships behind the reaper's existing
+OFF + dry-run default.
+
+## Second-pass review (if required)
+
+Not required — additive change, no new blocking authority, safety classifier
+untouched.
+
+## Evidence pointers
+
+- `tests/unit/session-reaper-pressure-audit.test.ts` — `computePressure` matrix,
+  transition-only decision audit, sink/reader round-trip.
+- `tests/integration/session-reaper-routes.test.ts` — `GET /sessions/reaper/audit`.
+- `tests/e2e/session-reaper-lifecycle.test.ts` — Phase-1 feature-alive for the
+  audit route through the real AgentServer.
+- `tests/unit/feature-delivery-completeness.test.ts` + capabilities-discoverability
+  lint — migration + route-classification parity.
+- `upgrades/NEXT.md` — upgrade guide.

package/upgrades/side-effects/worktree-spotlight-exclusion.md

@@ -0,0 +1,81 @@
+# Side-Effects Review — Worktree Spotlight exclusion
+
+**Version / slug:** `worktree-spotlight-exclusion`
+**Date:** `2026-05-30`
+**Author:** `echo`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+Drop a `.metadata_never_index` marker at the `.worktrees/` container root so macOS
+Spotlight/mediaanalysisd skip indexing every worktree beneath it. Covered at
+creation (`ensureWorktreesDir` → `ensureWorktreeSpotlightExclusion`, plus the
+convention wrapper's fallback path) and backfilled for existing agents via a new
+`PostUpdateMigrator.migrateWorktreeSpotlightExclusion`.
+
+## Decision-point inventory
+
+None. The change adds no decision logic — it writes one inert OS-hint file.
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject?** Nothing is rejected. The marker
+only affects Spotlight indexing of throwaway build trees; it does not change git,
+the worktree, the build, or any agent behavior. Source files inside worktrees are
+unaffected (the marker is at the container, not inside a worktree).
+
+## 2. Under-block
+
+**What does this still miss?** It does not reduce indexing of anything outside
+`.worktrees/` (by design), and it does not reclaim the worktrees themselves (the
+sibling reaper work). Spotlight may take time to honor a newly-dropped marker on an
+already-indexed tree, so the relief on existing backlogs is gradual, not instant.
+
+## 3. Level-of-abstraction fit
+
+**Right layer?** Yes. The marker-ensure lives in `ensureWorktreesDir`, the single
+chokepoint all CLI create paths run through, and the backfill lives beside the
+existing `migrateWorktreeConvention`. The exported helper keeps the rule in one
+place, reused by the migrator.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+No blocking authority added. The helper is best-effort and total: a write failure
+returns false and is swallowed (`@silent-fallback-ok`), never throwing and never
+blocking worktree creation or a migration pass.
+
+## 5. Interactions
+
+Reuses `resolveAgentHomeForWorktree` (same validation as `migrateWorktreeConvention`)
+so non-convention agents are skipped silently. The wrapper fallback change rides the
+existing always-overwrite of `instar-worktree-create.sh`. No interaction with the
+SessionReaper, sentinels, or recovery paths. Idempotent everywhere.
+
+## 6. External surfaces
+
+One new on-disk file per agent (`.worktrees/.metadata_never_index`, empty). No HTTP
+routes, no config, no notifications, no Telegram. Purely a filesystem hint to the OS.
+
+## 7. Rollback cost
+
+Trivial. Delete the marker to restore indexing; revert the PR to remove the
+create-path drop + migration. No state, no schema, no irreversible op.
+
+## Conclusion
+
+Lowest-risk possible change: additive, inert, idempotent, best-effort, reversible,
+no decision logic. Directly targets a measured top OS-level CPU drain (mediaanalysisd
+~80% under a ~120-worktree backlog). Operationally pre-validated by dropping the
+marker on echo's real `.worktrees/` (121 worktrees) live.
+
+## Second-pass review (if required)
+
+Not required — inert additive OS hint, no authority, no decision logic.
+
+## Evidence pointers
+
+- `tests/unit/worktree-spotlight-exclusion.test.ts` — helper + migration backfill.
+- `tests/unit/InstarWorktreeManager.test.ts`, `migrateWorktreeConvention.test.ts` — green.
+- `upgrades/NEXT.md` — upgrade guide.