instar 1.3.41 → 1.3.43

package/upgrades/side-effects/mentor-retire-migrations.md

@@ -0,0 +1,73 @@
+# Side-Effects Review — mentor migrations (retire dead config + outbox) (PR 3c-3)
+
+**Spec:** `docs/specs/MENTOR-LIVE-READINESS-SPEC.md` §Migration parity (the
+"dailySpendCapUsd silent removal is a quiet config break" round-2 adversarial finding +
+the legacy file-outbox cleanup). PR 3 of the staged build, part c-3.
+**Change:** Two new `PostUpdateMigrator` methods that retire the artifacts of the
+file-based mentor delivery design Justin's substrate correction replaced. Both
+**idempotent** via the `_instar_migrations` marker. Registered in the main migration
+list right after `migrateLegacyMaxSessions`.
+**Files:** `src/core/PostUpdateMigrator.ts` (+2 methods + 2 registrations),
+`tests/unit/PostUpdateMigrator-mentor-retire.test.ts` (new, 7).
+
+## What changed
+
+1. **`migrateRetireDeadMentorConfig`** — removes `mentor.dailySpendCapUsd`:
+   - field absent → silent skip (mark set so we don't re-check).
+   - field present at the default `0.5` → silent delete (operator never changed it).
+   - field present at a NON-default value → delete + LOUD `result.upgraded` entry with
+     `REVIEW:` prefix explaining the field was decorative (never enforced — Echo runs on
+     a Claude subscription) and the future replacement is `mentor.stageBTokenCeiling`.
+     This is exactly the "non-silent removal" the spec's round-2 adversarial finding
+     required: don't repeat the silent-dead-config bug at migration time.
+2. **`migrateRetireMentorOutbox`** — removes `{stateDir}/mentor-outbox/` via
+   `SafeFsExecutor.safeRmSync`:
+   - present → recursive remove + record file-count in `result.upgraded`.
+   - absent → mark + skip (so subsequent runs are no-ops).
+   - failure → log to `result.errors` + do NOT mark (retry on next run).
+
+## The seven questions
+
+1. **Over-block.** N/A — both are removal-only migrations; nothing is over-blocked.
+2. **Under-block.** Both are idempotent via the `_instar_migrations` marker; corrupt or
+   missing config.json early-exits with a `result.errors`/`result.skipped` entry rather
+   than crashing the migration pass.
+3. **Level-of-abstraction fit.** Each method does ONE thing, modeled exactly on
+   `migrateLegacyMaxSessions` (the established pattern for value-patching migrations) +
+   uses `SafeFsExecutor.safeRmSync` for the destructive filesystem op (the project's
+   established funnel for that). No new infrastructure.
+4. **Signal vs authority.** N/A.
+5. **Interactions.** Both run during the normal `PostUpdateMigrator.migrate()` pass
+   (between `migrateLegacyMaxSessions` and `migratePrPipelineArtifacts`). They touch
+   `config.json` and `{stateDir}/mentor-outbox/` only — both project-owned paths. The
+   `_instar_migrations` marker pattern is unchanged. Existing tests for other
+   migrations are unaffected.
+6. **External surfaces.** None new. Both surface their actions via the standard
+   `result.upgraded` / `result.skipped` / `result.errors` arrays the migrator already
+   uses (visible in the post-update output the operator sees).
+7. **Rollback cost.** Trivial — revert removes the two methods + their registration.
+   The retired data is forward-only; restoring an old `dailySpendCapUsd` or an old
+   `mentor-outbox/` directory by hand is possible if absolutely needed (but unlikely —
+   neither was actually working).
+
+## Testing
+
+7 new unit tests, all green:
+- **dailySpendCapUsd retirement**: field-absent silent skip + marker; default `0.5`
+  silent delete + non-LOUD upgraded entry; **non-default value LOUD `REVIEW:` upgraded
+  entry** with the "decorative / never enforced / subscription / token-ceiling
+  replacement" explanation (proves the "non-silent removal" invariant); IDEMPOTENT
+  (second run is no-op skip).
+- **outbox retirement**: present-directory removed + file-count recorded; IDEMPOTENT
+  marker means subsequent runs skip; directory-absent handled gracefully (no error,
+  marker set).
+
+`tsc --noEmit` clean. Combined mentor-stack tests across the staged build (PRs 1, 2a,
+2b, 3a, 3b, 3c-1, 3c-2, 3c-3) = **57 tests, all green**.
+
+## Migration parity
+
+These ARE the migrations from the spec's §Migration parity. The new MentorConfig fields
+(`botToken`, `menteeBotId`, `menteeChatId`, `menteeTopicId`) added in PR 3c-1 are
+optional + default undefined, so no additive migration is needed for them — they appear
+only when the operator (or PR 3c-4's `/mentor/bot-setup` flow) sets them.

package/upgrades/side-effects/source-tree-guard-readsync-bypass.md

@@ -0,0 +1,34 @@
+# Side-Effects Review — SourceTreeGuard read-tier bypass (extend to readSync)
+
+**Driver:** dogfood follow-up to PR #450 (source-tree-guard-data-pull). The narrow `sourceTreeReadOk` opt was added to `execSync` + `spawn` to let `git fetch` work on the agent's own instar checkout. After deploying v1.3.38 to Echo, the next layer of the same gap surfaced: `readSync` also runs source-tree-checks ("defense-in-depth"), and the canonical-ref scan path uses readonly verbs (`rev-parse`, `ls-tree`, `show`, `log`, `merge-base`, `remote -v`) that all go through `readSync` → all blocked on the source tree.
+
+## What changed
+
+- **`src/core/SafeGitExecutor.ts`** —
+  - `readSync` now honors `opts.sourceTreeReadOk` the same way `execSync` / `spawn` do: when the opt is true AND the verb is in `SOURCE_TREE_READ_TIER_VERBS`, skip `runSourceTreeChecks`; audit the bypass with the `sourceTreeReadOk-bypass` reason.
+  - `SOURCE_TREE_READ_TIER_VERBS` extended from `['fetch']` to `['fetch', 'rev-parse', 'ls-tree', 'show', 'log', 'cat-file', 'merge-base', 'remote']`. Still a small closed enumeration; still requires a spec edit to grow. Every verb is read-tier: none mutate the working tree or committed refs.
+- **`src/monitoring/releaseReadinessWiring.ts`** — every `SafeGitExecutor.run` callsite passes `sourceTreeReadOk: true`: `resolveCanonicalRemote` (`remote -v`), `fetchCanonical` (`rev-parse FETCH_HEAD` — fetch already had it), `oldestUnreleasedCommit` (`log`), `isAncestor` (`merge-base --is-ancestor`).
+- **`src/core/featureRolloutScan.ts`** — every `SafeGitExecutor.run` callsite in the canonical scan path passes `sourceTreeReadOk: true`: `rev-parse FETCH_HEAD`, `ls-tree` (spec + trace enumeration), `show` (spec + trace blob reads). `fetch` already had it.
+
+## Side-effects analysis
+
+**Why this is safe.** Every verb in the (still-small, still-closed) `SOURCE_TREE_READ_TIER_VERBS` set is read-tier: it does NOT modify the working tree, any committed ref, or any source file. `fetch` writes only to `FETCH_HEAD` + objects (transient). `rev-parse`, `ls-tree`, `show`, `log`, `cat-file`, `merge-base`, `remote -v/-get-url` are pure-read. The bypass is opt-in per-call, audit-logged, and only effective inside the closed verb allowlist.
+
+**Why the previous fix wasn't enough.** PR-450 only added the bypass to `execSync` + `spawn`, on the assumption that readonly verbs went through `readSync` which "didn't run source-tree checks." That was wrong: `readSync` runs them as defense-in-depth (catches repo-local aliases that could rebind a "read-only" verb). Every readonly verb on the agent's source tree was therefore still being blocked. This PR closes the gap at the right layer.
+
+**Reach.** Two real-code callsites touched (the two new ones added by the spec: Layer B wiring + Layer C scanner). Every existing `SafeGitExecutor.readSync` caller that does NOT pass `sourceTreeReadOk: true` is byte-identically guarded by the prior behavior.
+
+**Rollback.** Reverting this PR re-blocks the canonical-ref readSync calls on source trees. Layer B's fail-loud path keeps signaling on the failure; Layer C's local-scan fallback keeps working. No broken state.
+
+## Testing
+
+`tests/unit/SafeGitExecutor-sourceTreeReadOk.test.ts` (7 tests, all green):
+- default: fetch on non-source-tree works
+- default: fetch on source-tree blocked
+- `sourceTreeReadOk: true` + fetch on source-tree passes
+- `sourceTreeReadOk: true` does NOT bypass non-allowlist verbs (e.g. `add`)
+- `SOURCE_TREE_READ_TIER_VERBS` is a closed read-tier set — no destructive write verbs (commit/push/reset/checkout/rebase/merge/clean/rm/branch/tag); size ≤ 10
+- **readSync path also honors `sourceTreeReadOk` — `rev-parse FETCH_HEAD` on a source tree passes**
+- **readSync path WITHOUT `sourceTreeReadOk` — `rev-parse FETCH_HEAD` on a source tree STILL blocked**
+
+Lint clean.