instar 1.2.30 → 1.2.32

package/upgrades/side-effects/feat-periodic-sentinel-scan.md

@@ -0,0 +1,65 @@
+# Side-Effects Review — feat(memory): periodic SessionActivitySentinel scan
+
+**Branch:** `echo/phase-0b-periodic-scan`
+**Origin:** Phase 0b of the topic-intent-layer thread (Telegram 9976). Last foundation piece before Phase 1.
+
+## Summary
+
+Wires the periodic `SessionActivitySentinel.scan()` (every 30 min default) as a `setInterval` in `server.ts`, gated to the awake machine. Previously the sentinel only fired on `sessionComplete`, so long-running sessions never got mid-flight digestion and the Phase 0d entity extraction never ran for them.
+
+## Files touched
+
+- `src/core/types.ts` — added optional `MonitoringConfig.episodicSentinel` ({ enabled?, scanIntervalMinutes? }).
+- `src/monitoring/SessionActivitySentinel.ts` — added pure helper `resolveSentinelScanIntervalMs`.
+- `src/commands/server.ts` — wired the periodic scan interval after the sessionComplete handler; imports the new helper.
+- `tests/unit/sentinel-scan-interval.test.ts` — 6 tests on the resolver.
+- `docs/specs/periodic-sentinel-scan.md` + `.eli16.md` — spec + ELI16.
+- `upgrades/NEXT.md` — release note.
+
+## Over-block check
+
+The scan only runs when `resolveSentinelScanIntervalMs` returns non-null (enabled !== false) AND (no coordinator OR the machine is awake). It does NOT run on standby machines. It does NOT add an immediate startup scan (first fire is one interval out), so restart loops don't trigger repeated digestion. No new behaviour in the disabled path — `enabled: false` returns null and no interval is created.
+
+## Under-block check
+
+Could a long session still be missed? Only if: the periodic scan is disabled by config AND the session never reaches sessionComplete. That's an explicit operator opt-out, not a silent gap. The default (on, 30 min) covers the case the spec targets.
+
+scan() itself enforces dormant-skip and minimum-activity internally, so an idle session that the timer visits costs nothing — no over-digestion of quiet sessions.
+
+## Level-of-abstraction fit
+
+The interval policy (default, floor, disabled) is a pure function on the sentinel module — testable in isolation, no server bootstrap needed. The actual `setInterval` lives in server.ts next to the existing sessionComplete wire and the other periodic timers (relayPrune, resumeHeartbeat), matching the established in-process-timer pattern. The sentinel class is unchanged — it already had scan(); we just call it on a cadence.
+
+## Signal-vs-authority compliance
+
+Not a gate — this is a scheduler wire, not a filter. The closest principle is the awake-machine gating: the coordinator (authority on which machine is active) decides whether this machine scans. The timer defers to `coordinator.isAwake` rather than making its own liveness call.
+
+## Interactions
+
+- **sessionComplete synthesis**: unchanged. The periodic scan and the completion synthesis are independent; scan()'s idempotency (hash-keyed digests) means a periodic scan immediately before sessionComplete won't double-digest the same activity window.
+- **scan() idempotency / dormant-skip / min-activity**: relied upon, unchanged. These guards are what make a 30-min cadence safe.
+- **SemanticMemory entity extraction (Phase 0d)**: this scan is what drives it mid-session. The two compose: scan → digestUnit → materializeEntities. No new coupling; the periodic scan just calls the same digestActivity path the sessionComplete handler already used.
+- **Multi-machine coordinator**: awake-gating added; mirrors `config.scheduler.enabled && coordinator.isAwake`. Standby machines skip.
+- **Scheduler / jobs.json**: untouched. This is an in-process timer, not a cron job, so it doesn't interact with quota-tracked job scheduling. (Note: the LLM spend of periodic digestion is NOT currently quota-gated the way scheduled jobs are — see follow-up.)
+
+## Telemetry / observability
+
+- A `console.log` fires on startup naming the cadence ("periodic scan every 30min").
+- Each scan that creates digests logs the count.
+- Failures log via console.error, never throw.
+- `SemanticMemory.stats()` entity/edge growth is the downstream signal that the pipeline is working end-to-end.
+
+## Rollback
+
+Single-commit revert removes the interval, the config field, and the helper. Reverts to sessionComplete-only — the pre-change behaviour. No data/config migration (the field is optional and absent by default).
+
+## Cross-framework portability (v1.0+)
+
+Framework-agnostic: the scan reads tmux capture + Telegram JSONL and digests via `sharedIntelligence`. No INSTAR_FRAMEWORK branching. Same cadence on Claude and Codex.
+
+## Follow-ups (tracked, not orphaned)
+
+1. **Quota-awareness for periodic digestion LLM spend.** Scheduled jobs route through QuotaTracker; this in-process timer does not. On a quota-constrained agent, periodic digestion competes with foreground work for the same budget. A future enhancement could check `quotaTracker.canRunJob` before each scan. Lower priority — digestion uses the cheap `fast` tier and dormant-skip keeps volume low.
+2. **Live runtime verification.** The spec's acceptance includes a manual live check (set 5-min cadence, send messages, confirm a digest appears mid-session). Requires a live multi-message session; noted for the next live-agent session.
+
+Both tracked as initiatives, intentionally out of scope here.

package/upgrades/side-effects/framework-spawn-portability.md

@@ -0,0 +1,92 @@
+# Side-effects review — framework-spawn portability (codex agents spawn Codex)
+
+**Scope**: A Codex-only agent ("codey") spawned a Claude Code session when
+messaged on Telegram. Two compounding bugs: (1) `spawnInteractiveSession`
+hardcoded `'claude-code'` and never read config/env; (2) the runtime's
+`resolveConfiguredFramework` read `sessions.framework` + `INSTAR_FRAMEWORK`,
+neither of which the wizard sets — the wizard persists `enabledFrameworks`.
+So the runtime always resolved claude-code for wizard-installed Codex agents.
+
+**Files touched**:
+- `src/core/types.ts` — add optional `framework?: 'claude-code' | 'codex-cli'`
+  to `SessionManagerConfig` (the resolved runtime framework).
+- `src/core/Config.ts` — `resolveConfiguredFramework` takes a third arg
+  `enabledFrameworks`; new precedence configValue → env → enabledFrameworks[0]
+  → 'claude-code'; explicit `claude`/`claude-code` env branch added; `loadConfig`
+  passes `fileConfig.enabledFrameworks` and stores the result on
+  `sessions.framework` (the SessionManagerConfig field).
+- `src/core/SessionManager.ts` — `spawnInteractiveSession` replaces the
+  hardcoded default with `resolveInteractiveFramework({ perCall, configFramework:
+  this.config.framework, envFramework })`; `spawnSession` changes
+  `configFramework: undefined` → `this.config.framework`.
+- `tests/unit/framework-spawn-portability.test.ts` — 10 tests: precedence of
+  resolveConfiguredFramework (incl. enabledFrameworks fallback + explicit-claude
+  env), source-grep that both spawn paths read config.framework, and Config.load
+  wiring (enabledFrameworks → config.framework).
+
+**Under-block**: None. The fix makes a previously-ignored config field
+authoritative. There is no path where a framework that *should* spawn is now
+suppressed — per-call override and explicit config/env all still win.
+
+**Over-block**: None. A codex-cli agent will now correctly REFUSE to silently
+fall back to Claude. If a caller genuinely wants a one-off Claude session on a
+Codex agent, the per-call `options.framework` override still does that — it sits
+at the top of the precedence chain. So the "block" here is exactly the intended
+behavior (honor the install choice), with a documented escape hatch.
+
+**Level-of-abstraction fit**: Framework resolution stays in one place
+(`resolveConfiguredFramework` / `resolveInteractiveFramework`). The spawn paths
+do not re-implement precedence; they pass their three inputs and take the
+answer. `enabledFrameworks` (install choice) is reduced to a single resolved
+`config.framework` at load time, so SessionManager never has to know about the
+array shape. Correct layering: array-of-enabled is an install concept; the
+runtime sees one resolved framework.
+
+**Signal vs authority**: Compliant. `enabledFrameworks`, env, and per-call
+options are all SIGNALS fed into the resolver. The resolver
+(`resolveConfiguredFramework`) is the single AUTHORITY that picks one framework.
+No spawn-path makes its own framework decision anymore — both defer to the
+resolved value.
+
+**Interactions**:
+- `spawnSession` (scheduled jobs) and `spawnInteractiveSession` (messages) now
+  resolve identically. Before, only spawnSession read env; the interactive path
+  was the one that hit the bug. They are now symmetric.
+- `frameworkBinaryPaths[framework] ?? claudePath` fallback is unchanged — if a
+  codex-cli framework has no binary path mapped, it still falls back to
+  claudePath. That fallback is a *binary-path* concern, separate from framework
+  *selection*; out of scope here. For correctly-installed Codex agents the codex
+  binary path is populated by `detectCodexPath()` in loadConfig.
+- No change to `checkFrameworkPrerequisite` or the parity sentinel — they read
+  `enabledFrameworks` directly and are unaffected by the new derived field.
+
+**External surfaces**: None. No new API endpoint, no new config field the user
+writes (the new `framework` is derived, not user-authored), no CLI change. The
+`enabledFrameworks` field already existed and was already written by the wizard.
+
+**Migration / existing agents**: No migration needed. The fix is a config-LOAD
+derivation. Deployed Codex agents already have `enabledFrameworks: ['codex-cli']`
+on disk (their install wrote it). The moment they update and the server reloads
+config, `config.framework` resolves to codex-cli and both spawn paths honor it.
+Verified by the Config.load wiring test.
+
+**Rollback cost**: Trivial. Revert three source files + the test. The derived
+field is optional; nothing persists it to disk, so a revert leaves no orphaned
+state.
+
+**Tests**: 10/10 new tests pass; 11/11 existing `frameworkPrerequisite.test.ts`
+pass (no regression in the shared resolver). `npx tsc --noEmit` clean.
+`npm run lint` clean.
+
+**Decision-point inventory**:
+1. Derive `config.framework` at load (vs. teach every spawn path to read
+   `enabledFrameworks` itself) — single resolution point, single authority,
+   keeps SessionManager ignorant of the array shape. Chosen.
+2. `enabledFrameworks[0]` slots BELOW env (vs. above) — an explicit
+   `INSTAR_FRAMEWORK` env at boot is a deliberate per-boot override and should
+   beat the persisted install default. Matches the existing env-over-default
+   intent.
+3. No init-time write of `sessions.framework` (vs. backfilling it) — the
+   load-time derivation already fixes existing agents with zero migration; a
+   redundant on-disk write is deferred as unnecessary (noted out-of-scope in the
+   spec).