instar 1.3.466 → 1.3.468

package/upgrades/1.3.467.md

@@ -0,0 +1,80 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Fixes the 2026-06-09 incident where subscription-pool **pinning** and **account
+swap** relaunched interactive sessions into pool-account config homes that were
+enrolled via headless `claude auth login` — homes with valid OAuth tokens but
+WITHOUT the interactive first-launch onboarding flags. Every relaunched session
+wedged on Claude Code's onboarding screens (OAuth-authorize browser-tab spam +
+the Bypass-Permissions accept screen); ~8 live sessions froze at once until the
+operator logged in manually.
+
+New util `ensureInteractiveReady(configHome)` idempotently seeds the three
+local trust-acknowledgement flags (`hasCompletedOnboarding`,
+`bypassPermissionsModeAccepted`, `hasTrustDialogAccepted`) in
+`<configHome>/.claude.json`, preserving every other key and **never touching
+`oauthAccount`/tokens** (an unparseable file is refused, not rewritten; writes
+are atomic). It is fail-safe by contract — a launch can never crash on it.
+
+Called everywhere a session can enter a pool home, so the wedge is impossible
+by construction:
+
+1. **Enrollment** — `EnrollmentWizard.complete()` seeds a freshly-enrolled
+   claude-code home immediately.
+2. **Pinned launches** — both SessionManager pin lanes (headless +
+   interactive-reroute) and the interactive account-swap lane seed before
+   setting `CLAUDE_CONFIG_DIR`.
+3. **Swaps** — `SessionRefresh` seeds the target home BEFORE the kill+respawn.
+4. **Existing homes** — a `PostUpdateMigrator` sweep seeds every claude-code
+   pool account's existing home once on update (stale entries skipped, never
+   created).
+
+## What to Tell Your User
+
+If I run on a pool of Claude accounts, moving my sessions between accounts
+(when one hits its weekly limit) used to be able to freeze them on Claude's
+"first launch" welcome screens — the account was logged in, but nobody had
+ever clicked through the one-time setup dialogs for that account's config
+folder. That's fixed at every layer now: new accounts are made
+interactive-ready the moment they're enrolled, every launch double-checks, and
+existing accounts get fixed automatically on this update. Account swaps should
+now be invisible — same conversation, different account, no frozen sessions
+and no browser-tab spam.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Pool config homes are onboarding-safe by construction (enrollment + every pinned/swapped launch) | automatic — no config |
+| Existing pool homes seeded once on update | automatic — PostUpdateMigrator sweep |
+| `ensureInteractiveReady(configHome)` util for any future launch lane | `src/core/ensureInteractiveReady.ts` |
+
+## Evidence
+
+Live state at the incident (this machine): `sagemind-justin` and `sagemind-dawn`
+homes were fully headless (no flags), `justin-gmail` had onboarded=true but
+bypass=false — exactly the homes whose sessions wedged; the two complete homes'
+sessions were unaffected. The OAuth tokens were present in every case.
+
+After the change:
+- `tests/unit/ensure-interactive-ready.test.ts` — 14 cases: missing-file
+  create, partial merge, flag-false reseed, idempotency (mtime-stable second
+  call), oauthAccount/token preservation, tilde expansion, unparseable/
+  non-object refusal with bytes preserved, unreadable fail-safe,
+  requireExistingHome both sides.
+- `tests/unit/PostUpdateMigrator-subscriptionPoolInteractiveReady.test.ts` — 8
+  cases incl. one-bad-home-never-aborts-the-sweep and full-migrate() wiring.
+- `tests/unit/SessionRefresh.test.ts` — flags land BEFORE the respawner fires
+  (ordering pinned), fresh swaps too, no-swap untouched, fail-safe.
+- `tests/integration/subscription-pin-sessions.test.ts` — both launch lanes
+  land the flags on disk through the real SessionManager.
+- `tests/integration/subscription-enrollment-interactive-ready.test.ts` +
+  `tests/e2e/subscription-enrollment-lifecycle.test.ts` — full HTTP
+  enroll→complete leaves the home interactive-ready, credentials
+  byte-identical.
+- `npm run lint` (tsc + all custom lints) clean; subscription/quota regression
+  suites green.

package/upgrades/1.3.468.md

@@ -0,0 +1,25 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+Introduces the **Cartographer doc-tree** — the substrate of the cartographer-conformance project. A new `CartographerTree` core module builds a hierarchical semantic map of the codebase: one node per directory and source file, each carrying a plain-English summary and a git-object-id fingerprint. Staleness is derived from a single batched `git ls-tree` (not a per-node git spawn), so the tree can report exactly which summaries have drifted from the code they describe — at near-zero cost.
+
+Four read-only routes are added, all behind a dark-by-default `cartographer.enabled` gate (the feature is inert — routes 503 — until explicitly turned on): GET /cartographer/tree, /cartographer/node, /cartographer/stale, and /cartographer/health. Node-store filenames are collision-free sha256 slugs; the path lookup validates against traversal. The shared directory skip-set was extracted from ProjectMapper into a single skipDirs module that both now import. Destructive filesystem pruning of stale node files is funneled through SafeFsExecutor.
+
+This is spec #1 of a multi-round project; later rounds add summary authoring, a freshness sweep, and conformance auditing. It changes no existing behavior — a fresh agent gets the feature off.
+
+## What to Tell Your User
+
+- **A living map of your codebase (groundwork)**: "I'm building a self-maintaining map of this project — a tree of plain-English summaries, one per folder and file, that can tell when a summary has fallen behind the code it describes. This first piece is the foundation, and it's turned off by default for now. I'll let you know when the rest is ready to switch on."
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| Codebase doc-tree map | GET /cartographer/tree (opt-in; off by default) |
+| Per-node summary lookup | GET /cartographer/node?path=… |
+| Stale-summary detection | GET /cartographer/stale |
+| Feature health / liveness | GET /cartographer/health |

package/upgrades/side-effects/cartographer-doc-tree-schema.md

@@ -0,0 +1,82 @@
+# Side-Effects Review — Cartographer Doc-Tree Schema (spec #1)
+
+**Version / slug:** `cartographer-doc-tree-schema`
+**Date:** `2026-06-09`
+**Author:** `echo`
+**Second-pass reviewer:** `external Gemini cross-model (convergence round 2) — no material findings`
+
+## Summary of the change
+
+Adds the substrate of the `cartographer-conformance` project: a new
+`CartographerTree` core module (hierarchical semantic doc-tree of the codebase,
+per-node git-object-id staleness derived from ONE batched `git ls-tree`), a shared
+`skipDirs.ts` (extracted from `ProjectMapper`, which now imports it), four
+read-only HTTP routes `GET /cartographer/{tree,node,stale,health}` gated behind a
+dark-by-default `cartographer.enabled` config, the config default + CLAUDE.md
+template/migration (Migration Parity + Agent Awareness), and 3-tier tests.
+
+## Decision-point inventory
+
+One gate: the routes return **503** when `cartographer.enabled` is false (or the
+context holds no tree). No block/allow logic beyond the enable gate and the
+`/cartographer/node?path=` validation (reject leading `/` or a `..` segment → 400).
+
+## 1. Over-block
+The `?path=` validation rejects only traversal-shaped inputs (`/`-prefixed or
+containing a `..` segment) and unknown nodes (404). Legitimate repo-relative paths
+pass. The leaf-selection default (source extensions, excluding `*.test.*`) omits
+non-source files from leaf nodes by design; directories always get a node, so no
+directory is "over-blocked" out of the map.
+
+## 2. Under-block
+Staleness compares committed git oids by default, so uncommitted working-tree
+edits are not flagged unless the opt-in dirty mode is used — intentional (committed
+state is deterministic across machines). Summaries are stored verbatim and
+semantically unverified; the map never asserts a summary is *true* — downstream
+specs (#3/#5) must re-ground against code. The map only covers what `scaffold()`
+walks (skip-set + maxDepth bounded).
+
+## 3. Level-of-abstraction fit
+Right layer. `CartographerTree` is a `src/core` data-structure module like
+`ProjectMapper`; routes mount via the existing `createRoutes` context pattern; the
+gate + instantiation live beside `projectMapper` in `server.ts`; the config default
+rides the existing `applyDefaults` migration path (no bespoke migrator). The
+skip-set is one shared export, not duplicated.
+
+## 4. Blast radius / reversibility
+Self-contained and dark by default — a fresh agent gets `cartographer.enabled:
+false`, so the feature is inert (routes 503) until explicitly enabled. The only
+change to existing code paths is `ProjectMapper` importing `DEFAULT_SKIP_DIRS` from
+the new shared module (identical set; covered by ProjectMapper's existing tests,
+which stay green). Removing the feature is deleting the module + routes; no schema
+migration to undo. State lives under `.instar/cartographer/` (gitignored).
+
+## 5. State / migration / multi-machine
+New runtime state dir `.instar/cartographer/` (per-machine, gitignored, never
+committed). Config default flows to existing agents via `migrateConfig` →
+`applyDefaults` (existence-checked, idempotent). CLAUDE.md awareness flows via a
+content-sniffed `migrateClaudeMd` block (idempotent). No cross-machine sync surface
+— the tree is a local derived index, regenerable by `scaffold()` on any machine.
+
+## 6. Security / abuse
+`?path=` never builds a filesystem path — it indexes the in-memory node store; the
+on-disk node filename is a sha256 slug, collision-free and not derived from request
+input. All git access is read-only via `SafeGitExecutor.readSync` (arg-form, no
+shell interpolation). Routes are Bearer-auth'd like all instar routes; writes have
+no open route (in-process only). Summaries served as JSON (consumers escape before
+any HTML render). `scaffold()` is bounded by maxDepth + a symlink-loop guard
+(visited realpaths) so a pathological repo cannot hang it. The one destructive fs
+path — pruning stale node files in `rewriteAll()` — is funneled through
+`SafeFsExecutor.safeUnlinkSync` (operation-tagged `cartographer-prune-stale-node`,
+source-tree-guarded with the agent-runtime-state carveout for `.instar/`), never a
+raw `fs.unlinkSync`, so the destructive-fs lint and audit trail both cover it.
+
+## 7. Observability / failure modes
+`GET /cartographer/health` exposes node/authored/stale counts (the Tier-3 "alive"
+surface). Absent git/HEAD degrades to "no current oids" → nodes read as
+`never-authored`/`path-gone` rather than crashing (try/caught, `@silent-fallback-ok`).
+`setSummary`'s node-then-index write is non-transactional: a crash between the two
+leaves the index one version behind that node — a benign lag, self-healed by the
+next `setSummary`/`scaffold`, never corruption. Tests cover all of: 14 unit + 8
+integration (route contract) + 2 e2e (alive lifecycle), all green; `tsc --noEmit`
+clean; ProjectMapper's existing tests stay green after the skip-set extraction.

package/upgrades/side-effects/onboarding-safe-pinswap.md

@@ -0,0 +1,49 @@
+# Side-Effects Review — onboarding-safe config homes for subscription pin/swap
+
+**Version / slug:** `onboarding-safe-pinswap`
+**Date:** `2026-06-09`
+**Author:** `echo (Fable 5 build session)`
+**Second-pass reviewer:** `self-review under the Tier-1 lite lane; every write path to .claude.json walked below`
+
+## Summary of the change
+
+2026-06-09 incident (topic 20905): pin/swap relaunched ~8 interactive sessions into pool-account config homes created by headless `claude auth login` — tokens present, interactive first-launch flags absent — so every one wedged on the onboarding screens. New util `ensureInteractiveReady(configHome)` idempotently seeds `hasCompletedOnboarding` / `bypassPermissionsModeAccepted` / `hasTrustDialogAccepted` in `<configHome>/.claude.json`, called at enrollment completion (EnrollmentWizard), defensively at every pinned/swapped launch (SessionManager headless-pin, interactive-reroute-pin, interactive configHome lanes; SessionRefresh before the swap respawn), and once for existing homes via a PostUpdateMigrator sweep.
+
+## Decision-point inventory
+
+- `src/core/ensureInteractiveReady.ts` — NEW — the only writer. Sets exactly the three flags; preserves every other key; refuses unparseable/non-object files (never clobbers a file that may hold salvageable credentials); atomic tmp+rename write; never throws (fail-safe contract); `requireExistingHome` gate for the migration sweep.
+- `SessionManager.ensurePinnedHomeInteractiveReady` — NEW private helper — log-and-continue on failure; called in the headless pin lane, the interactive-reroute pin lane, and `spawnInteractiveSession` when `options.configHome` is set (claude-code only).
+- `SessionRefresh.refreshSession` — seeds the target home whenever `accountSwap.configHome` is present (fresh and resume swaps both relaunch interactively), BEFORE the respawner fires.
+- `EnrollmentWizard.complete()` — seeds for claude-code logins with a configHome; injectable `ensureReady` seam (default = real util). A seeding failure never blocks completion.
+- `PostUpdateMigrator.migrateSubscriptionPoolInteractiveReady` — one-time sweep over `SubscriptionPool.list()` claude-code accounts; `requireExistingHome:true` so a stale registry entry never litters $HOME; per-home failures reported in `result.errors`, never abort the sweep.
+- `ProactiveSwapMonitor` — comment-only TODO for active-session-only gating (secondary incident finding, deferred to a follow-up).
+
+## Could this corrupt credentials? (the load-bearing question)
+
+The util never touches `oauthAccount` or any token field — it sets three booleans on the parsed object and writes the rest back. Unparseable or non-object files are REFUSED, not rewritten (bytes preserved exactly — pinned by unit tests). Writes are atomic (tmp+rename) so a crash mid-write cannot truncate `.claude.json`. The Monroe homes (`~/.claude`, `~/.claude-monroe`) are not in any subscription pool registry and no new code path enumerates $HOME — only registry/launch-provided configHome values are ever touched.
+
+## Could the seeding itself break a launch?
+
+No — fail-safe by contract: every failure lane returns `{patched:false, reason}`; callers log and proceed. Worst case is byte-identical to the pre-fix behavior (the onboarding wedge), never a dead spawn/refresh path. Pinned-spawn behavior when the resolver returns null, and refreshes without an account swap, are unchanged (covered by existing + new tests).
+
+## Framework generality
+
+Seeding is gated to claude-code everywhere: the SessionManager lanes only run for claude-code launches, EnrollmentWizard checks `login.framework === 'claude-code'`, and the migrator filters `framework === 'claude-code'`. codex-cli / gemini-cli / pi-cli homes are never touched — `.claude.json` onboarding flags are a Claude Code concept by construction.
+
+## Over-permit
+
+The three flags are local trust acknowledgements (the operator manually accepted the same dialogs during incident recovery — this reproduces that state for pool homes). `bypassPermissionsModeAccepted` does not ENABLE bypass mode; it records that the mode's accept-screen was answered, which is precisely what an unattended relaunch cannot do itself. No trust scope widens beyond what every pre-incident pool home already required to function.
+
+## Migration parity
+
+Handled IN this change: existing agents get the sweep via `PostUpdateMigrator.migrate()` on update; new enrollments are seeded at completion; every launch re-ensures defensively (triple coverage). No CLAUDE.md/template surface changes — the feature is structural (Structure > Willpower), not agent-invoked.
+
+## Token/cost impact
+
+None. One stat + one small JSON read per pinned/swapped launch (write only when flags are missing — i.e., at most once per home). No LLM calls, no new polling.
+
+## Test coverage
+
+- Unit: `tests/unit/ensure-interactive-ready.test.ts` (14 — both sides of every boundary), `PostUpdateMigrator-subscriptionPoolInteractiveReady.test.ts` (8), `SessionRefresh.test.ts` (+4 ordering/fail-safe), `enrollment-wizard.test.ts` (+4 seam/wiring).
+- Integration: `subscription-pin-sessions.test.ts` (+2 — both launch lanes land the flags on disk), `subscription-enrollment-interactive-ready.test.ts` (2 — full HTTP enroll→complete seeds flags, codex untouched).
+- E2E: `subscription-enrollment-lifecycle.test.ts` (+1 feature-alive — real server, headless-state home becomes interactive-ready with credentials byte-identical).