instar 1.3.466 → 1.3.467

package/dist/core/ensureInteractiveReady.d.ts

@@ -0,0 +1,58 @@
+/**
+ * ensureInteractiveReady — onboarding-safe config homes for the subscription
+ * pool (2026-06-09 incident, topic 20905).
+ *
+ * Pool-account config homes are created via `claude auth login`, which stores
+ * OAuth tokens but is HEADLESS-ONLY: it never sets the interactive first-launch
+ * onboarding flags. Relaunching an INTERACTIVE Claude Code session into such a
+ * home (session pinning, proactive/reactive account swap) re-runs first-launch
+ * onboarding — the OAuth-authorize URL + the "Bypass Permissions mode" accept
+ * screen — and the session wedges. The tokens were present; the onboarding
+ * FLAGS were the missing piece (~8 live sessions wedged, browser-tab spam,
+ * a manual operator login to recover).
+ *
+ * This util makes pin/swap onboarding-safe by construction: idempotently seed
+ * the three local trust-acknowledgement flags in `<configHome>/.claude.json`,
+ * preserving every other key byte-for-byte.
+ *
+ * Structural invariants:
+ *   - NEVER touches `oauthAccount` or any token/credential field — only the
+ *     three onboarding flags are ever written, onto the parsed existing object.
+ *   - NEVER rewrites a file it cannot parse — an unparseable `.claude.json`
+ *     may still hold the account's credentials in a salvageable form, so we
+ *     refuse and report rather than clobber.
+ *   - Fail-safe: never throws into the caller. A launch must not crash on
+ *     this; the worst case is the pre-fix behavior (onboarding wedge), not a
+ *     dead spawn path. All failures return `{ patched: false, reason }`.
+ *   - Idempotent + cheap (one stat/read; a write only when a flag is missing),
+ *     so calling it defensively on every pinned/swapped launch is fine.
+ */
+/**
+ * The interactive first-launch flags `claude auth login` (headless) never
+ * sets. All three are LOCAL trust acknowledgements — seeding them to `true`
+ * asserts nothing about credentials, only that first-launch onboarding and
+ * the bypass-permissions/trust dialogs are accepted for this home.
+ */
+export declare const INTERACTIVE_ONBOARDING_FLAGS: readonly ["hasCompletedOnboarding", "bypassPermissionsModeAccepted", "hasTrustDialogAccepted"];
+export interface EnsureInteractiveReadyResult {
+    /** True when this call wrote one or more missing flags. */
+    patched: boolean;
+    /** Why nothing was written (or which flags were seeded when patched). */
+    reason: string;
+}
+export interface EnsureInteractiveReadyOptions {
+    /**
+     * When true, a config home whose directory does not exist is left alone
+     * (`patched: false`) instead of being created. Used by the one-time
+     * migration sweep so a stale pool entry never litters $HOME with empty
+     * credential-less homes; launch paths keep the default (create/merge —
+     * the account was just selected, so its home is expected to exist).
+     */
+    requireExistingHome?: boolean;
+}
+/**
+ * Idempotently mark `<configHome>/.claude.json` interactive-ready. Returns
+ * `{ patched: true }` only when a missing flag was actually written.
+ */
+export declare function ensureInteractiveReady(configHome: string, opts?: EnsureInteractiveReadyOptions): EnsureInteractiveReadyResult;
+//# sourceMappingURL=ensureInteractiveReady.d.ts.map

package/dist/core/ensureInteractiveReady.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensureInteractiveReady.d.ts","sourceRoot":"","sources":["../../src/core/ensureInteractiveReady.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAKH;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,gGAI/B,CAAC;AAEX,MAAM,WAAW,4BAA4B;IAC3C,2DAA2D;IAC3D,OAAO,EAAE,OAAO,CAAC;IACjB,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,6BAA6B;IAC5C;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAMD;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,MAAM,EAClB,IAAI,CAAC,EAAE,6BAA6B,GACnC,4BAA4B,CA+D9B"}

package/dist/core/ensureInteractiveReady.js

@@ -0,0 +1,114 @@
+/**
+ * ensureInteractiveReady — onboarding-safe config homes for the subscription
+ * pool (2026-06-09 incident, topic 20905).
+ *
+ * Pool-account config homes are created via `claude auth login`, which stores
+ * OAuth tokens but is HEADLESS-ONLY: it never sets the interactive first-launch
+ * onboarding flags. Relaunching an INTERACTIVE Claude Code session into such a
+ * home (session pinning, proactive/reactive account swap) re-runs first-launch
+ * onboarding — the OAuth-authorize URL + the "Bypass Permissions mode" accept
+ * screen — and the session wedges. The tokens were present; the onboarding
+ * FLAGS were the missing piece (~8 live sessions wedged, browser-tab spam,
+ * a manual operator login to recover).
+ *
+ * This util makes pin/swap onboarding-safe by construction: idempotently seed
+ * the three local trust-acknowledgement flags in `<configHome>/.claude.json`,
+ * preserving every other key byte-for-byte.
+ *
+ * Structural invariants:
+ *   - NEVER touches `oauthAccount` or any token/credential field — only the
+ *     three onboarding flags are ever written, onto the parsed existing object.
+ *   - NEVER rewrites a file it cannot parse — an unparseable `.claude.json`
+ *     may still hold the account's credentials in a salvageable form, so we
+ *     refuse and report rather than clobber.
+ *   - Fail-safe: never throws into the caller. A launch must not crash on
+ *     this; the worst case is the pre-fix behavior (onboarding wedge), not a
+ *     dead spawn path. All failures return `{ patched: false, reason }`.
+ *   - Idempotent + cheap (one stat/read; a write only when a flag is missing),
+ *     so calling it defensively on every pinned/swapped launch is fine.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * The interactive first-launch flags `claude auth login` (headless) never
+ * sets. All three are LOCAL trust acknowledgements — seeding them to `true`
+ * asserts nothing about credentials, only that first-launch onboarding and
+ * the bypass-permissions/trust dialogs are accepted for this home.
+ */
+export const INTERACTIVE_ONBOARDING_FLAGS = [
+    'hasCompletedOnboarding',
+    'bypassPermissionsModeAccepted',
+    'hasTrustDialogAccepted',
+];
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Idempotently mark `<configHome>/.claude.json` interactive-ready. Returns
+ * `{ patched: true }` only when a missing flag was actually written.
+ */
+export function ensureInteractiveReady(configHome, opts) {
+    try {
+        const trimmed = (configHome ?? '').trim();
+        if (!trimmed)
+            return { patched: false, reason: 'empty configHome' };
+        // Expand a `~` prefix the same way the swap-continuity path does — pool
+        // entries are operator-entered and may be tilde-relative.
+        const home = trimmed.startsWith('~')
+            ? path.join(process.env.HOME ?? '', trimmed.slice(1))
+            : trimmed;
+        const filePath = path.join(home, '.claude.json');
+        if (opts?.requireExistingHome && !fs.existsSync(home)) {
+            return { patched: false, reason: `config home ${home} does not exist` };
+        }
+        let existing = {};
+        if (fs.existsSync(filePath)) {
+            let raw;
+            try {
+                raw = fs.readFileSync(filePath, 'utf-8');
+            }
+            catch (err) {
+                return { patched: false, reason: `unreadable ${filePath}: ${errMsg(err)}` };
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch (err) {
+                // Refuse to rewrite what we can't parse — the file may still hold the
+                // account's oauthAccount/credentials in a recoverable form.
+                return {
+                    patched: false,
+                    reason: `unparseable ${filePath} — refusing to rewrite: ${errMsg(err)}`,
+                };
+            }
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                return {
+                    patched: false,
+                    reason: `${filePath} is not a JSON object — refusing to rewrite`,
+                };
+            }
+            existing = parsed;
+        }
+        const missing = INTERACTIVE_ONBOARDING_FLAGS.filter((f) => existing[f] !== true);
+        if (missing.length === 0) {
+            return { patched: false, reason: 'already interactive-ready' };
+        }
+        for (const f of missing)
+            existing[f] = true;
+        // Atomic tmp+rename write (the repo's durable-registry idiom) so a crash
+        // mid-write can never leave a half-written `.claude.json` — that file
+        // also carries the account's oauthAccount, which we must never corrupt.
+        fs.mkdirSync(home, { recursive: true });
+        const tmpPath = `${filePath}.${process.pid}.interactive-ready.tmp`;
+        fs.writeFileSync(tmpPath, JSON.stringify(existing, null, 2) + '\n');
+        fs.renameSync(tmpPath, filePath);
+        return { patched: true, reason: `seeded ${missing.join(', ')}` };
+    }
+    catch (err) {
+        // @silent-fallback-ok: fail-safe by contract — a launch path must never
+        // crash on readiness seeding; the caller logs the reason.
+        return { patched: false, reason: `ensureInteractiveReady failed: ${errMsg(err)}` };
+    }
+}
+//# sourceMappingURL=ensureInteractiveReady.js.map

package/dist/core/ensureInteractiveReady.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensureInteractiveReady.js","sourceRoot":"","sources":["../../src/core/ensureInteractiveReady.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.466",
+  "version": "1.3.467",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-10T07:16:04.116Z",
-  "instarVersion": "1.3.466",
+  "generatedAt": "2026-06-10T07:26:55.306Z",
+  "instarVersion": "1.3.467",
   "entryCount": 199,
   "entries": {
     "hook:session-start": {
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "04183b2ca81e6145da95d2263e3b8c7ef34ba1ac67ede4039840818d131092b2",
+      "contentHash": "9f5d958c0cc5a68d7c4d078e10441756637da7dca7139ed48c276079654a5a3e",
       "since": "2025-01-01"
     },
     "hook:dangerous-command-guard": {
@@ -20,7 +20,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/dangerous-command-guard.sh",
-      "contentHash": "04183b2ca81e6145da95d2263e3b8c7ef34ba1ac67ede4039840818d131092b2",
+      "contentHash": "9f5d958c0cc5a68d7c4d078e10441756637da7dca7139ed48c276079654a5a3e",
       "since": "2025-01-01"
     },
     "hook:grounding-before-messaging": {
@@ -29,7 +29,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/grounding-before-messaging.sh",
-      "contentHash": "04183b2ca81e6145da95d2263e3b8c7ef34ba1ac67ede4039840818d131092b2",
+      "contentHash": "9f5d958c0cc5a68d7c4d078e10441756637da7dca7139ed48c276079654a5a3e",
       "since": "2025-01-01"
     },
     "hook:compaction-recovery": {
@@ -38,7 +38,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/compaction-recovery.sh",
-      "contentHash": "04183b2ca81e6145da95d2263e3b8c7ef34ba1ac67ede4039840818d131092b2",
+      "contentHash": "9f5d958c0cc5a68d7c4d078e10441756637da7dca7139ed48c276079654a5a3e",
       "since": "2025-01-01"
     },
     "hook:external-operation-gate": {
@@ -47,7 +47,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-operation-gate.js",
-      "contentHash": "04183b2ca81e6145da95d2263e3b8c7ef34ba1ac67ede4039840818d131092b2",
+      "contentHash": "9f5d958c0cc5a68d7c4d078e10441756637da7dca7139ed48c276079654a5a3e",
       "since": "2025-01-01"
     },
     "hook:deferral-detector": {
@@ -56,7 +56,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/deferral-detector.js",
-      "contentHash": "04183b2ca81e6145da95d2263e3b8c7ef34ba1ac67ede4039840818d131092b2",
+      "contentHash": "9f5d958c0cc5a68d7c4d078e10441756637da7dca7139ed48c276079654a5a3e",
       "since": "2025-01-01"
     },
     "hook:self-stop-guard": {
@@ -65,7 +65,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/self-stop-guard.js",
-      "contentHash": "04183b2ca81e6145da95d2263e3b8c7ef34ba1ac67ede4039840818d131092b2",
+      "contentHash": "9f5d958c0cc5a68d7c4d078e10441756637da7dca7139ed48c276079654a5a3e",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -74,7 +74,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "04183b2ca81e6145da95d2263e3b8c7ef34ba1ac67ede4039840818d131092b2",
+      "contentHash": "9f5d958c0cc5a68d7c4d078e10441756637da7dca7139ed48c276079654a5a3e",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -83,7 +83,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "04183b2ca81e6145da95d2263e3b8c7ef34ba1ac67ede4039840818d131092b2",
+      "contentHash": "9f5d958c0cc5a68d7c4d078e10441756637da7dca7139ed48c276079654a5a3e",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-collector": {
@@ -92,7 +92,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "04183b2ca81e6145da95d2263e3b8c7ef34ba1ac67ede4039840818d131092b2",
+      "contentHash": "9f5d958c0cc5a68d7c4d078e10441756637da7dca7139ed48c276079654a5a3e",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -101,7 +101,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "04183b2ca81e6145da95d2263e3b8c7ef34ba1ac67ede4039840818d131092b2",
+      "contentHash": "9f5d958c0cc5a68d7c4d078e10441756637da7dca7139ed48c276079654a5a3e",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -110,7 +110,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "04183b2ca81e6145da95d2263e3b8c7ef34ba1ac67ede4039840818d131092b2",
+      "contentHash": "9f5d958c0cc5a68d7c4d078e10441756637da7dca7139ed48c276079654a5a3e",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -119,7 +119,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "04183b2ca81e6145da95d2263e3b8c7ef34ba1ac67ede4039840818d131092b2",
+      "contentHash": "9f5d958c0cc5a68d7c4d078e10441756637da7dca7139ed48c276079654a5a3e",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -128,7 +128,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "04183b2ca81e6145da95d2263e3b8c7ef34ba1ac67ede4039840818d131092b2",
+      "contentHash": "9f5d958c0cc5a68d7c4d078e10441756637da7dca7139ed48c276079654a5a3e",
       "since": "2025-01-01"
     },
     "hook:stop-gate-router": {
@@ -137,7 +137,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/stop-gate-router.js",
-      "contentHash": "04183b2ca81e6145da95d2263e3b8c7ef34ba1ac67ede4039840818d131092b2",
+      "contentHash": "9f5d958c0cc5a68d7c4d078e10441756637da7dca7139ed48c276079654a5a3e",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -146,7 +146,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "04183b2ca81e6145da95d2263e3b8c7ef34ba1ac67ede4039840818d131092b2",
+      "contentHash": "9f5d958c0cc5a68d7c4d078e10441756637da7dca7139ed48c276079654a5a3e",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1514,7 +1514,7 @@
       "type": "subsystem",
       "domain": "sessions",
       "sourcePath": "src/core/SessionManager.ts",
-      "contentHash": "1b58893e54317eed379d38d736a6c001ba407607c115d84a79795a5439a479f5",
+      "contentHash": "9e1bc7df09921b4ecdd6252c8616ac33b195380a678de7a4c1a616312ca3cae1",
       "since": "2025-01-01"
     },
     "subsystem:auto-updater": {
@@ -1538,7 +1538,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "04183b2ca81e6145da95d2263e3b8c7ef34ba1ac67ede4039840818d131092b2",
+      "contentHash": "9f5d958c0cc5a68d7c4d078e10441756637da7dca7139ed48c276079654a5a3e",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

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/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).