instar 1.3.534 → 1.3.536

package/scripts/lint-no-unfunneled-credential-write.js

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+/**
+ * lint-no-unfunneled-credential-write.js — refuses a raw write to the Claude Code
+ * credential store outside the serialization funnel (Step 4b of live credential
+ * re-pointing, spec §2.2).
+ *
+ * Why this exists: every in-process write to a config home's `Claude Code-credentials`
+ * keychain entry MUST go through `CredentialWriteFunnel.withSlotLock(slot, …)` (via
+ * `refreshClaudeToken`, `writeCredentialsSerialized`, or the Step-5 swap executor) so a
+ * refresh write can never interleave with a swap on the SAME slot and strand a rotated
+ * token. A callsite that writes the credential store directly — `defaultCredentialStore.write`,
+ * `provider.writeCredentials(...)`, or a hand-rolled `security add-generic-password` to the
+ * `Claude Code-credentials` service — bypasses that lock and re-opens the clobber race.
+ * This mirrors the SafeGitExecutor / SafeFsExecutor single-funnel precedent.
+ *
+ * Rule: outside the closed allowlist below, no source file may contain:
+ *   - a `defaultCredentialStore.write(` call,
+ *   - a qualified `.writeCredentials(` call (i.e. `someProvider.writeCredentials(...)` —
+ *     the bare method DEFINITION `writeCredentials(creds…)` has no leading dot and is fine),
+ *   - a raw `add-generic-password` invocation in a file that targets the
+ *     `Claude Code-credentials` service (scoped by the literal service string so the OTHER
+ *     keychain vaults — WorktreeKeyVault / SecretStore / GlobalSecretStore / RemediationKeyVault,
+ *     each a DISTINCT service — never false-positive).
+ *
+ * Comment-only mentions are NOT a bypass and are ignored.
+ *
+ * Exit codes: 0 — clean; 1 — at least one violation.
+ *
+ * Usage:
+ *   node scripts/lint-no-unfunneled-credential-write.js            # full repo
+ *   node scripts/lint-no-unfunneled-credential-write.js --staged   # staged files
+ *   node scripts/lint-no-unfunneled-credential-write.js <file…>    # explicit files (tests)
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const ROOT = path.resolve(path.dirname(__filename), '..');
+
+// ── Allowlist (closed). Each entry is a file that OWNS a credential-write primitive
+//    and routes it through the funnel internally (or the lint itself). Adding an entry
+//    requires review of WHY the callsite cannot route through `withSlotLock`. ──────
+const ALLOWLIST = new Set([
+  // THE funnel — the per-slot lock lives here.
+  'src/core/CredentialWriteFunnel.ts',
+  // Owns `defaultCredentialStore.write` + the raw keychain write; `refreshClaudeToken`
+  // wraps it in `funnel.withSlotLock(configHome, …)`.
+  'src/core/OAuthRefresher.ts',
+  // Owns `KeychainCredentialProvider.writeCredentials` (the raw `security -i` write) +
+  // the sanctioned `writeCredentialsSerialized` funnel chokepoint that wraps it.
+  'src/monitoring/CredentialProvider.ts',
+  // Step 5 (spec section 2.3). Owns the async execFile add-generic-password keychain write
+  // primitive (defaultKeychainExec) used for slot + staging writes. Every credential write the
+  // executor performs runs INSIDE funnel.withSingleMover then funnel.withSlotLocks([A,B], ...) —
+  // the staged exchange takes the single-mover mutex AND both slot locks before any write, so a
+  // swap write can never interleave with a refresh/switch on the same slot. Funnel-routing is at
+  // the call layer (the primitive must NOT self-lock under the slot locks). Sanctioned route.
+  'src/core/CredentialSwapExecutor.ts',
+  // This lint file names the patterns it greps for.
+  'scripts/lint-no-unfunneled-credential-write.js',
+]);
+
+const SCAN_DIRS = ['src', 'scripts', 'templates'];
+const EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.mjs', '.cjs', '.sh']);
+
+// The keychain service the funnel guards. Scopes the raw `add-generic-password` rule so the
+// other (distinct-service) keychain vaults never trip it.
+const GUARDED_SERVICE = 'Claude Code-credentials';
+
+const PATTERNS = [
+  {
+    re: /defaultCredentialStore\.write\s*\(/,
+    msg: 'direct defaultCredentialStore.write — route through CredentialWriteFunnel.withSlotLock (see refreshClaudeToken)',
+  },
+  {
+    re: /\.writeCredentials\s*\(/,
+    msg: 'direct provider.writeCredentials(...) — route through writeCredentialsSerialized (CredentialProvider.ts)',
+  },
+];
+
+// A raw keychain write is flagged ONLY in a file that also references the guarded service —
+// so WorktreeKeyVault / SecretStore / GlobalSecretStore / RemediationKeyVault (distinct
+// services) are never false-positived.
+const RAW_KEYCHAIN_WRITE = /add-generic-password/;
+
+function isCommentLine(line) {
+  const t = line.trim();
+  return t.startsWith('//') || t.startsWith('*') || t.startsWith('/*') || t.startsWith('#');
+}
+
+function listFiles() {
+  if (process.argv.includes('--staged')) {
+    const out = execSync('git diff --cached --name-only', { cwd: ROOT, encoding: 'utf-8' });
+    return out.split('\n').filter(Boolean);
+  }
+  const explicit = process.argv.slice(2).filter((a) => !a.startsWith('--'));
+  if (explicit.length) return explicit;
+
+  const files = [];
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (e.name === 'node_modules' || e.name === '.git' || e.name === 'dist') continue;
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) walk(full);
+      else if (EXTENSIONS.has(path.extname(e.name))) files.push(path.relative(ROOT, full));
+    }
+  };
+  for (const d of SCAN_DIRS) walk(path.join(ROOT, d));
+  return files;
+}
+
+let violations = 0;
+for (const rel of listFiles()) {
+  const normalized = rel.split(path.sep).join('/');
+  if (ALLOWLIST.has(normalized)) continue;
+  if (!EXTENSIONS.has(path.extname(normalized))) continue;
+  const full = path.isAbsolute(rel) ? rel : path.join(ROOT, normalized);
+  let content;
+  try {
+    content = fs.readFileSync(full, 'utf-8');
+  } catch {
+    continue;
+  }
+  const fileTargetsGuardedService = content.includes(GUARDED_SERVICE);
+  const lines = content.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (isCommentLine(line)) continue;
+    for (const { re, msg } of PATTERNS) {
+      if (re.test(line)) {
+        console.error(`${normalized}:${i + 1} — ${msg}`);
+        violations++;
+      }
+    }
+    if (fileTargetsGuardedService && RAW_KEYCHAIN_WRITE.test(line)) {
+      console.error(
+        `${normalized}:${i + 1} — raw 'add-generic-password' to the ${GUARDED_SERVICE} service outside ` +
+        `the funnel. Route the write through CredentialWriteFunnel.withSlotLock, or add an allowlist entry ` +
+        `here with a justification.`,
+      );
+      violations++;
+    }
+  }
+}
+
+if (violations > 0) {
+  console.error(
+    `\nlint-no-unfunneled-credential-write: ${violations} violation(s). Every Claude credential write ` +
+    `must go through CredentialWriteFunnel.withSlotLock (spec §2.2).`,
+  );
+  process.exit(1);
+}
+console.log('lint-no-unfunneled-credential-write: clean');

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-13T18:31:24.275Z",
-  "instarVersion": "1.3.534",
+  "generatedAt": "2026-06-13T19:24:03.890Z",
+  "instarVersion": "1.3.536",
   "entryCount": 201,
   "entries": {
     "hook:session-start": {

package/upgrades/{1.3.534.md → 1.3.535.md}

@@ -5,6 +5,16 @@
 
 ## What Changed
 
+Step 4b of the live-credential-repointing build (Subscription & Auth Standard), shipping **dark**. Every in-process write to the `Claude Code-credentials` keychain store now routes through the Step-4a `CredentialWriteFunnel`'s per-slot lock, so two writers to the same config home serialize instead of interleaving:
+
+- `OAuthRefresher.refreshClaudeToken` wraps its token write in `withSlotLock(credentialSlotKey(configHome), …)`. A lock-acquire timeout returns a new typed reason `write-skipped` — the OAuth exchange already succeeded and the existing valid credential is left untouched.
+- `QuotaPoller.pollAccount` maps `write-skipped` to "no snapshot this cycle, retry next tick" — explicitly NOT `needs-reauth`. A momentarily-busy lock can no longer cry-wolf a healthy login into a re-auth prompt.
+- `CredentialProvider` adds `writeCredentialsSerialized`, the one sanctioned chokepoint that serializes a provider write; `AccountSwitcher` now uses it (a busy lock returns a non-destructive "store busy, try again").
+- A new lint, `lint-no-unfunneled-credential-write.js` (wired into `npm run lint`), forbids any future unfunneled write to the Claude credential store — the structural guarantee that no new code path can bypass the lock. It is file-scoped to the guarded service, so the other keychain vaults are never false-flagged.
+- `credentialSlotKey` canonicalizes the lock key so a refresh and a switch on the same home always share one lock regardless of path spelling.
+
+The credential-repointing feature gate is untouched and remains off + dry-run. With no swap running (always, while dark), the funnel adds only per-slot ordering and a bounded skip-retry under contention — behaviorally identical to before.
+
 The session reaper's shared guard (`ReapGuard`) had two halves that disagreed about a *stale* open commitment. The KILL decision (`evaluate()`) already treats a commitment as abandoned after 8h of topic silence and lets the idle session be reaped. But the RESUME-eligibility decision (`workEvidence()`) counted **any** open commitment as proof of interrupted work — with no staleness gate. So an idle session was killed (commitment stale ⇒ reap) and immediately revived (commitment exists ⇒ resume-eligible), in an endless loop.
 
 This patch applies the **same 8h staleness gate** to the resume-eligibility probe that the kill decision already uses, so the two halves agree: a stale commitment neither keeps a session alive nor revives it, and a fresh one keeps the session alive so it never needs reviving. Strictly safer — it can only ever revive *less*, never more. Genuine interrupted work (a live build, an active sub-agent, a pending injection, a running process) is untouched.
@@ -22,18 +32,30 @@ A precise per-trigger hint label (carrying the actual originating trigger rather
 
 ## What to Tell Your User
 
+Nothing changes for you right now — this is internal plumbing for the upcoming restartless subscription rebalancing, and it is shipping switched off. When that feature is eventually turned on, it will be able to move an account's login between config slots without ever interrupting a session; this step lays the safety groundwork so two background credential operations can never step on each other and accidentally knock a healthy login into a "please log in again" state. You don't need to do anything, and you won't see any difference until the feature is explicitly enabled.
+
 Sessions that finished their work but still had an old, untouched promise on the books were being killed and revived over and over. That loop is fixed. You'll see fewer "🪦 your session was shut down — a restart is queued" notices on topics where nothing was actually unfinished. Promises still get followed up on by the commitment system — that part is unchanged.
 
 When you run me on more than one machine and move a heavy-work conversation from one to another, the bigger model it was using no longer silently disappears the moment the conversation resumes on the new machine. The new machine asks itself whether that conversation should be on the bigger model and re-runs its own cost checks first — quota, budget, anti-flapping, how many big-model sessions it is already running. Only if all of those pass does it put the resumed conversation back on the bigger model. If they do not, or if you pinned that topic to never escalate, it simply runs on the normal model. So the bigger-model state follows your moved conversation, but it is always re-priced against the machine it lands on, never smuggled across to dodge a budget. This ships off by default and does nothing at all on a single machine.
 
 ## Summary of New Capabilities
 
+| Capability | How to Use |
+|-----------|-----------|
+| Serialized credential writes (per-slot lock) | Automatic (internal) — every Claude credential write is now ordered through one funnel |
+| Busy-lock safety on token refresh | Automatic — a contended refresh retries next cycle instead of triggering needs-reauth |
+| Unfunneled-write lint guard | Automatic at build time (`npm run lint`) |
+
 No new capability — this is a bugfix. It removes a spurious session kill→revive loop driven by stale (long-untouched) open commitments by aligning the reaper guard's resume-eligibility decision with its existing kill-decision staleness rule.
 
 `models.tierEscalation.ridesTopic` (default false) — when on (under `tierEscalation.enabled`), a topic moved via `POST /pool/transfer` while escalated carries its escalation trigger as an ephemeral hint, and the destination re-admits the resumed session through its own EscalationGovernor cost guards. New exported `EscalationHintStore` (the ephemeral per-topic hint carrier). No new HTTP route; rides the existing `/pool/transfer` + `topic-profile-pull` surfaces.
 
 ## Evidence
 
+- 15 new unit tests (`credential-write-routing.test.ts`, `lint-no-unfunneled-credential-write.test.ts`) plus all 193 pre-existing credential/oauth/quota/account-switcher tests green (208 total). The routing tests prove end-to-end that a busy lock yields `write-skipped` → no-snapshot and does NOT mark `needs-reauth`, with a CONTRAST test proving a genuine `exchange-failed` still does.
+- `npx tsc --noEmit` clean; full `npm run lint` chain clean (including the new lint and the destructive-tool lint with the new script allowlisted).
+- Independent second-pass reviewer subagent: **CONCUR** — traced the token-refresh hot path, confirmed no regression, no lock-wedge, no double-lock, and a sound lint on both axes; the one non-blocking concern (lock-key string fragility) was fixed inline via `credentialSlotKey`.
+
 - Live `logs/reap-log.jsonl` (2026-06-13): **13** age-limit reaps with `midWork=true`, every one carrying solely `workEvidence=[open-commitment]`, across 6 topics — and corresponding repeated `reason=age-limit` respawn entries in the resume queue (several doubled per topic). The loop, captured.
 - Root cause confirmed in source: `ReapGuard.evaluate()` gates the open-commitment KEEP on `recentUserMessage(topicId, staleCommitmentWindowMs)`; `ReapGuard.workEvidence()` did not.
 - New regression tests in `tests/unit/work-evidence.test.ts`: a stale commitment emits no `open-commitment` evidence (and `isMidWork`→false); a fresh one still does; an explicit `evaluate()`/`workEvidence()` consistency assertion; and the `protectOpenCommitments:false` boundary. All 22 work-evidence + 19 reap-guard unit tests green; 164 related reap/resume tests green; `tsc --noEmit` clean.

package/upgrades/1.3.536.md

@@ -0,0 +1,34 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The staged-exchange primitive (spec §2.3) that MOVES an account's OAuth credential between two config-home "slots" without restarting the sessions reading them. The sessions switch token sources on their next API call (the Claude client re-reads its credential store), so no restart, no aborted turns.
+
+- **Exchange, never copy** — `swap(slotA, slotB)` exchanges the two slots' credentials so exactly one account-lineage lives in each readable config home (the one-home-per-credential invariant holds by construction).
+- **Preconditions before any path expansion** — both slots must be EXACT members of the location ledger's enumerated slot set before any home-expansion/keychain call, so a `../`/`~`/absolute traversal value can never reach a keychain service (validated against the ledger, not the filesystem); a quarantined or no-refresh-token slot is refused.
+- **Source-slot CAS (§2.3.1a)** — immediately before each destructive write the slot is re-read; a same-tenant newer blob (the Claude client's own rotated copy) is ADOPTED, a different-tenant blob is a clobber-race that ABORTS the swap, and a changed blob the oracle cannot confirm ABORTS — never a silent overwrite.
+- **Crash-proof staging** — blob A is COPIED into a disjoint `instar-credential-swap-staging-*` keychain namespace and `begin` is journaled BEFORE the first destructive write, so a crash before the exchange unwinds to a true no-op and a crash mid-exchange recovers from the retained escrow.
+- **Identity-verified, repair-safe** — after the exchange each slot is verified on its ACCOUNT IDENTITY via the profile-endpoint oracle. A confirmed match commits; a mismatch with a reachable oracle gets ONE repair-from-staging then re-verify; an UNAVAILABLE oracle is quarantine-never-repair (an outage never triggers a destructive repair). The executor never commits a slot it cannot identity-confirm.
+- **Commit, then delayed re-verify** — the ledger is updated with staging RETAINED, then ~90s later both slots are re-verified before staging is deleted and the journal closed (the heal source for a client write-back that lands in the in-flight window).
+- **Bounded everywhere** — all `security` keychain calls are async with a 10s timeout (never sync, which could wedge the event loop); every swap runs under the single-mover mutex + both slot locks (the Step-4b funnel); boot recovery acquires the single-mover mutex and the balancer's first pass is gated on a recovery barrier WITH a hang-timeout (a wedged recovery can't freeze the system).
+- **Dark** — gated by the existing `subscriptionPool.credentialRepointing` flag (`enabled:false` + `dryRun:true`). With the feature off (the fleet + dev default) the executor is a strict no-op; with dry-run on it runs the full decision loop and audits the would-swap with zero writes. Going live needs a deliberate two-flag flip.
+
+The HTTP route + census re-routing that wire this into the running system are Steps 6 and 7 (a later increment); this ships the swap primitive plus its three test tiers.
+
+## What to Tell Your User
+
+This is internal plumbing that ships turned off, so day to day nothing changes for you. What it builds toward: when I hold more than one of your subscription accounts, I can move which account a running session is using WITHOUT restarting that session — today moving an account means killing and respawning the session, which loses in-flight work and re-pays the warm-up cost. The new mechanism swaps the credential under the hood and the session just picks up the new account on its next request. It is built to be safe under failure: it never leaves a session pointed at an account it could not positively confirm, it survives a crash mid-swap without losing a login, and it can never run two swaps at once on the same machine. It is off by default and does nothing until it is deliberately turned on after a review window.
+
+## Summary of New Capabilities
+
+New exported `CredentialSwapExecutor` (src/core/CredentialSwapExecutor.ts) — the spec §2.3 staged-exchange primitive of live credential re-pointing. Gated by the existing `subscriptionPool.credentialRepointing` flag; no new config flag, no new HTTP route (routes are a later step). Consumes the merged Step 2/3/4 primitives (location ledger, identity oracle, write funnel).
+
+## Evidence
+
+- `tests/unit/credential-swap-executor.test.ts` (20) — dark/dryRun inertness; preconditions (non-member/quarantined/no-refresh-token rejection, zero writes); the happy exchange (keychain-first, identity-verified, one-lineage-per-home, staging retained then deleted at step 6); clobber-race (different-tenant abort, same-tenant-newer adopt); identity verify/repair/quarantine (mismatch repair-then-commit; oracle-unavailable quarantine-never-repair); THE blocker lens (no committed-unverified write); permutation-property (2 and 5 concurrent swaps serialize, exactly one exchange); crash-at-every-boundary (budgets 0/1/2 + hang-timeout barrier quarantining before lift); orphan-staging sweep predicate; token-material scrub.
+- `tests/integration/credential-swap-executor-host.test.ts` (2) — the executor composed as its host will (REAL CredentialIdentityOracle profile-endpoint + REAL pool-mapping + REAL ledger + REAL funnel): oracle ALLOW yields commit; oracle UNAVAILABLE (5xx) at verify yields quarantine + attention.
+- `tests/e2e/credential-swap-executor-dark-ship-lifecycle.test.ts` (3) — Phase-1 dark-ship inertness on the production config path: a DEV and a fleet agent's real ConfigDefaults gate the executor to a strict no-op; recovery on the dark config is still crash-safe.
+- tsc clean; full `npm run lint` clean; dark-gate unchanged; docs-coverage green (CredentialSwapExecutor documented in architecture/under-the-hood.md).

package/upgrades/side-effects/live-credential-repointing-increment-a-funnel-routing.md

@@ -0,0 +1,86 @@
+# Side-Effects Review — Live credential re-pointing (Increment A, Step 4b: route writers through the funnel + forbidding lint)
+
+**Version / slug:** `live-credential-repointing-increment-a-funnel-routing`
+**Date:** `2026-06-13`
+**Author:** `echo`
+**Second-pass reviewer:** `required` (touches the live token-refresh hot path — see §5/§7; result appended below)
+
+## Summary of the change
+
+Routes every in-process write to the `Claude Code-credentials` keychain store through the Step-4a `CredentialWriteFunnel` (spec §2.2), and adds the forbidding lint that makes the routing structural:
+
+- **`OAuthRefresher.refreshClaudeToken`** — its single `store.write` is now wrapped in `funnel.withSlotLock(configHome, …)`. A lock-acquire timeout returns the NEW typed reason `write-skipped` (the exchange already succeeded; the existing, still-valid credential is untouched). `RefreshDeps.funnel` is injectable, defaulting to the process-wide `credentialWriteFunnel` singleton.
+- **`QuotaPoller.pollAccount`** — maps `write-skipped` to "no snapshot this cycle, retry next tick", explicitly NOT `markNeedsReauth`. A busy lock can never cry-wolf a healthy login into needs-reauth.
+- **`CredentialProvider`** — adds `writeCredentialsSerialized(provider, slot, creds, funnel?)`, the sanctioned chokepoint that wraps `provider.writeCredentials` in `withSlotLock`. `KeychainCredentialProvider.writeCredentials` (the raw `security -i` write) is unchanged — it is a primitive; callers serialize.
+- **`AccountSwitcher.switchAccount`** — now writes via `writeCredentialsSerialized(...)`; a busy lock returns a non-destructive "store busy, try again", never a corrupting half-write.
+- **`scripts/lint-no-unfunneled-credential-write.js`** (+ wired into `npm run lint`, allowlisted in `lint-no-direct-destructive.js`) — forbids, outside the closed allowlist (the funnel + the two primitive owners + the lint itself): `defaultCredentialStore.write(`, a qualified `.writeCredentials(`, and a raw `add-generic-password` in a file that targets the `Claude Code-credentials` service (file-scoped so the OTHER vaults — WorktreeKeyVault / SecretStore / GlobalSecretStore / RemediationKeyVault, each a distinct service — never false-positive).
+- Tests: `credential-write-routing.test.ts` (7) + `lint-no-unfunneled-credential-write.test.ts` (8).
+
+Ships DARK: the credential-repointing feature gate is untouched and stays off+dry-run. The funnel is pure in-process serialization with NO behavioral change when no swap is running (which is always, while dark) — it only adds per-slot ordering and a bounded skip-and-retry under contention.
+
+## Decision-point inventory
+
+- `refreshClaudeToken` write → `withSlotLock` — **modify** — serialize the refresh write; contention → `write-skipped` (retry), never corruption.
+- `QuotaPoller` `write-skipped` mapping — **add** — a busy lock is NOT a dead login; no `needs-reauth`.
+- `writeCredentialsSerialized` — **add** — the one sanctioned provider-write chokepoint.
+- `lint-no-unfunneled-credential-write` — **add** — structural enforcement that no future writer bypasses the funnel. Signal-only (a build-time lint), no runtime authority.
+
+---
+
+## 1. Over-block
+
+The only new "refusal" is a try-lock-timeout SKIP, which is the §2.2 bounded-wait contract, not a content decision. A legitimate refresh write that loses the 15s race for its slot is reported `write-skipped` and retried next poll cycle — it is never dropped or failed. A legitimate account-switch write that loses the race gets a "store busy, try again" and the operator retries. Neither rejects a valid input; both defer it by one cycle. Because the feature ships dark (no swaps run), the only lock holders are these writes themselves (sub-millisecond `security` calls), so contention — and therefore any skip — is effectively unreachable until Step 5 introduces a longer-held swap lock.
+
+---
+
+## 2. Under-block
+
+The funnel can only serialize a writer that routes through it. That is exactly what the new lint enforces: the real tree is now lint-clean, and any future callsite that hand-rolls a `Claude Code-credentials` write (raw `security`, `defaultCredentialStore.write`, or `provider.writeCredentials`) outside the allowlist fails the build. The lint is line-scoped and skips comments (a documentation mention is not a bypass) and file-scoped to the guarded service (the four sibling keychain vaults are out of scope by construction, verified: none contains the `Claude Code-credentials` literal). Residual not covered: a brand-new keychain service string for Claude credentials would not be caught by the service-literal scope — acceptable, because the service name is a fixed Anthropic-client constant (`claudeCredentialService`), not something a new writer invents.
+
+---
+
+## 3. Level-of-abstraction fit
+
+Correct layer. The wrapping lives in the two files that OWN the write primitives (`OAuthRefresher`, `CredentialProvider`) — the SafeGit/SafeFs precedent of "the primitive's owner is the funnel-internal site, everything else routes through a named method." The QuotaPoller maps the new reason at the exact point it already classifies refresh outcomes. The lint mirrors `lint-no-unfunneled-topic-creation` / `-headless-launch` precisely (closed allowlist, comment-skipping, `--staged` bootstrap). No higher layer should own this — credential writes are a `src/core`/`src/monitoring` concern.
+
+---
+
+## 4. Signal vs authority compliance
+
+Compliant. The funnel is mechanism (a per-slot mutex with a bounded outcome), not authority over agent behavior — it makes no allow/deny decision about content, only about lock availability, deterministically. The QuotaPoller mapping REMOVES a false-authority failure mode (a transient lock contention was never a real `needs-reauth`, and now can't masquerade as one). The lint is a build-time signal with zero runtime authority. No brittle check gains blocking authority over messaging, dispatch, or sessions.
+
+---
+
+## 5. Interactions
+
+- **Hot path — token refresh:** the load-bearing interaction. `refreshClaudeToken` keeps every session's access token fresh; the only change to it is that its write is serialized. The existing 17 oauth-refresher + quota-poller + credential tests (193 → all green) prove the default-singleton path is behaviorally identical to today (a free lock ⇒ `ran:true` ⇒ same write, same result). The single NEW path is `ran:false` ⇒ `write-skipped` ⇒ QuotaPoller returns no-snapshot — covered by a dedicated test plus the CONTRAST test proving `exchange-failed` still marks `needs-reauth`.
+- **No double-lock / deadlock:** the primitives (`store.write`, `provider.writeCredentials`) do NOT self-lock; callers lock once. `writeCredentialsSerialized` is the only locker for the provider path, so AccountSwitcher → serialized → provider.write is a single lock acquisition. Verified by the per-slot-isolation test (a busy slot does not block a different slot).
+- **Shared singleton:** refresh, switch, and (Step 5) swap all use `credentialWriteFunnel`, so a refresh and a switch on the SAME slot genuinely serialize. Slot keys are the expanded config home; the default slot is `expandHome('~/.claude')` on both paths so they share one lock.
+
+---
+
+## 6. External surfaces
+
+No new routes, no network, no notices. The only externally observable change is benign: an account-switch that hits a busy lock returns a clearer "store busy, try again" message instead of proceeding, and a refresh that hits a busy lock logs one warn line and skips a single poll cycle. Token values are never logged (the skip reason and warn line are credential-free). Nothing changes for other agents/users/machines.
+
+---
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**Machine-local BY DESIGN.** Credential writes target THIS machine's keychain, so the serialization that protects them is inherently per-process/per-machine — there is no shared state to replicate. The funnel singleton serializes writers WITHIN one process; cross-machine coordination of a credential move (a topic transfer mid-swap) is the existing handoff guard's responsibility, composed-with in Step 5, not this lock's. A second machine refreshing its OWN keychain copy of the same account is independent by construction (each machine has its own login lineage) — the spec's one-home-per-credential invariant is about config homes on a single machine, enforced by the ledger (Step 2), not by this lock.
+
+---
+
+## 8. Rollback cost
+
+Low. Plain `git revert` of this commit restores the direct writes; no migration, no persisted state, no schema. The funnel singleton and primitive remain (shipped in Step 4a) but go unused. Because the feature is dark and the change is behaviorally identical under no-contention, a revert is invisible to production. The lint removal is a one-line edit to `npm run lint` if ever needed.
+
+---
+
+## Second-pass review
+
+_Appended by the dedicated independent reviewer subagent (Phase 5), 2026-06-13._
+
+**VERDICT: CONCUR.** The reviewer independently traced every hot-path concern and confirmed: tests 15/15 green; no hot-path regression (the `write-skipped` path returns no-snapshot and never `markNeedsReauth` — verified end-to-end through `QuotaPoller.pollAccount`); no lock-wedge (acquisition is bounded; `mine` releases only after the real prior holder settles; every `fn` here is a synchronous `security`/fs call); no double-lock/deadlock (neither primitive self-locks; `writeCredentialsSerialized` is the sole locker on the provider path); the lint is sound on both axes (regex matches qualified calls but not the method definition / interface / `writeCredentialsSerialized`; the raw-keychain rule is file-scoped to the guarded service so the four sibling vaults never false-positive); behaviorally inert when dark.
+
+**One non-blocking concern raised → FIXED in this commit (not deferred).** The reviewer noted the per-slot lock key was string-identity-fragile: a default account enrolled non-canonically (`~/.claude/` with a trailing slash, or a differently-spelled path) could key the refresh write and the switch write to *different* locks for the *same* keychain entry, letting them race. Resolution: added `credentialSlotKey(configHome) = path.resolve(expandHome(configHome))` in `OAuthRefresher.ts` and routed all three lock keys through it (`refreshClaudeToken`, `DEFAULT_CREDENTIAL_SLOT`, `writeCredentialsSerialized`), so the shared-resource→lock-key mapping is canonical rather than dependent on operator spelling. This strictly improves on today's behavior (which has no funnel at all) and removes the latent footgun before Step 5's longer-held swap lock can expose it.

package/upgrades/side-effects/ws52-step5-swap-executor.md

@@ -0,0 +1,64 @@
+# Side-Effects Review — WS5.2 Step 5: CredentialSwapExecutor (staged-exchange swap primitive)
+
+**Spec:** docs/specs/live-credential-repointing-rebalancer.md §2.3 (converged 5 rounds 50→0, `approved:true` — operator pre-approval, Justin topic 13481). **Parent:** Cross-Machine Coherence — One Agent, Robust Under Degraded Conditions.
+**Ships DARK** behind the EXISTING `subscriptionPool.credentialRepointing` flag (`enabled:false` + `dryRun:true`, a `DARK_GATE_EXCLUSIONS` `destructive` entry shipped by Step 4b). Going live needs a deliberate two-flag flip. No new config flag, no new dark-gate line.
+**Files:** src/core/CredentialSwapExecutor.ts (new), scripts/lint-no-unfunneled-credential-write.js (allowlist + header), tests/unit/lint-no-unfunneled-credential-write.test.ts (allowlist ratchet), tests/unit/credential-swap-executor.test.ts (new), tests/integration/credential-swap-executor-host.test.ts (new), tests/e2e/credential-swap-executor-dark-ship-lifecycle.test.ts (new), site/src/content/docs/architecture/under-the-hood.md (awareness).
+
+## What changed
+
+1. **CredentialSwapExecutor.ts (new):** the §2.3 staged-exchange primitive. `swap(slotA, slotB)` EXCHANGES (never copies) the two slots' OAuth credentials so the sessions reading them switch token sources on their next API call (E3) with zero restart. The full §2.3 sequence: preconditions (EXACT ledger membership BEFORE any path expansion → traversal can't reach a keychain service) → §2.3.1a source-slot CAS re-read (adopt a same-tenant newer blob, ABORT a different-tenant clobber-race) → staging escrow COPY into a disjoint `instar-credential-swap-staging-*` namespace + journal `begin` → exchange (keychain-first, config-second) → verify on ACCOUNT IDENTITY via the injected oracle resolver (match→commit, mismatch→one repair-from-staging→re-verify, **unavailable→QUARANTINE-NEVER-REPAIR**) → commit with staging RETAINED → delayed ~90s re-verify → delete staging + journal `done`. Consumes the merged primitives: `CredentialWriteFunnel.withSingleMover`+`withSlotLocks`, `CredentialLocationLedger` (membership/journal/quarantine/recordAssignment), and an injected `ResolveSlotIdentity` (composed by the host from `CredentialIdentityOracle`+pool).
+2. **Async keychain exec surface (`KeychainCredentialExec` + `defaultKeychainExec`):** ALL `security` calls go through async `execFile` + a 10s timeout — NEVER `execFileSync` (a locked-keychain ACL prompt would wedge the event loop). Injectable so tests run zero-keychain. The default impl derives the slot service via the imported `claudeCredentialService(slot)`; the literal `'Claude Code-credentials'` never appears in the executor source.
+3. **Boot recovery (`recover()`):** acquires the single-mover mutex (a recovery WRITE must not race a boot balancer pass on the ledger), resolves every in-flight journal row by re-reading live identity (adopt-on-newer, never a blind staging overwrite), and lifts a **recovery-complete barrier** so the balancer's first pass can run. The barrier carries a bounded HANG-TIMEOUT: a wedged recovery write quarantines its slots BEFORE the lift, so the post-lift balancer structurally cannot select a wedged slot. Recovery completion is INDEPENDENT of dryRun (an already-begun exchange is finished for crash-safety even on the dark config).
+4. **`sweepOrphanStaging()`:** the §2.3 step-2 orphan predicate — a staging entry is protected by ANY non-`done` swap journal row (begin/exchanged/verified all keep their staging as the step-6 heal source); only a `done` row (or no row) makes staging an orphan. Avoids both the lost-source bug (deleting a committed row's heal source) and the orphan-leak.
+5. **Single audit + scrub chokepoint:** every audited step routes through one `audit()` funnel that scrubs token material (`sk-ant-…` runs → `redactToken`) before it reaches any persisted/served/notified surface (§2.9). Quarantines raise ONE HIGH attention item (the blast-radius surface).
+6. **lint allowlist (Step 4b ratchet):** `src/core/CredentialSwapExecutor.ts` added to the `lint-no-unfunneled-credential-write.js` closed allowlist (named in the header as the sanctioned Step-5 funnel route — its raw `add-generic-password` keychain write runs INSIDE `funnel.withSingleMover → withSlotLocks`, so the funnel-routing is at the call layer; the primitive must not self-lock under the slot locks). The self-test that asserts the closed allowlist set was updated to include the 5th entry.
+7. **Awareness:** a `CredentialSwapExecutor` subsection in `architecture/under-the-hood.md` (Core Infrastructure) — 2 mentions, satisfies docs-coverage for the new exported class.
+
+## Blast radius
+
+- **The path is config-gated to a strict no-op while dark.** `swap()` returns `disabled` (zero keychain writes, zero ledger mutation) the instant `enabled` is false — the fleet + dev default. `dryRun:true` runs the full decision loop (preconditions + CAS) and audits the WOULD-swap but performs ZERO writes (returns `dry-run` before the staging step). Proven by the E2E dark-ship test (DEV and fleet config) + the unit dark/dryRun tests + the dark-gate test (16/16, unchanged).
+- **No new flag, no new dark-gate line.** The executor reuses the Step-4b `subscriptionPool.credentialRepointing` flag already in `DARK_GATE_EXCLUSIONS`/`ConfigDefaults`, so the cartographer dark-gate line-map did not shift (no recompute needed; `lint-dev-agent-dark-gate.js` clean, the dark-gate test green as-is).
+- **No unverified live commit.** A slot the oracle cannot identity-confirm (mismatch-unrepairable OR oracle-unavailable) is quarantined + surfaced; `swap()` returns `quarantined` BEFORE `recordAssignment` — the ledger never records a clean assignment for an unverified slot. Proven by THE blocker lens test.
+- **No unfunneled credential write.** Every keychain credential write is inside `withSingleMover → withSlotLocks` (the Step-4b funnel guards a swap against a concurrent refresh/switch on the same slot). `lint-no-unfunneled-credential-write` clean.
+- **Per-machine local, no cross-machine egress (Phase C).** The swap moves a credential between config slots on ONE machine; it carries no LAN/broadcast assumption and adds no cross-machine traffic. An N-machine pool runs one single-mover mutex + recovery barrier PER machine; each machine's executor is independent and bounded — the fleet never has two movers on the same home.
+
+## Risk + mitigation
+
+- **Risk:** a concurrent Claude-client keychain write on the source slot strands a rotated lineage (the §0.c residual instar cannot lock). **Mitigation:** §2.3.1a source-slot CAS re-reads each slot immediately before the destructive write; a same-tenant newer blob is ADOPTED (carry the client's rotated copy), a different-tenant blob ABORTS the swap (clobber-race), an unconfirmable changed blob ABORTS (never overwrite what we can't identity-verify). The window is narrowed (final-re-read→write), not closed against an external writer — the §2.3.6 delayed re-verify + the §2.4 audit catch the honest residual. Proven by the clobber-race adopt/abort tests.
+- **Risk:** a crash mid-exchange destroys a blob or strands staging. **Mitigation:** staging is a COPY (slot A untouched until step 3 → crash-before-step-3 unwinds to a no-op); `begin` is journaled before the first destructive write; staging is RETAINED through step 6 (the heal source); recovery resolves every in-flight row by live identity (adopt-on-newer, never blind). Proven by the crash-at-every-boundary tests (budgets 0/1/2) + the orphan-sweep predicate test.
+- **Risk:** an oracle outage during verify triggers a destructive repair-storm against healthy blobs. **Mitigation:** oracle-UNAVAILABLE is read as "unverified", NEVER as "mismatch" — it quarantines (never repairs); repair is reserved for a CONFIRMED mismatch with a reachable oracle. Proven by the quarantine-never-repair test + the host-wired REAL-oracle 5xx test.
+- **Risk:** a wedged recovery write (keychain ACL prompt) freezes the balancer forever. **Mitigation:** the recovery barrier carries a bounded hang-timeout that quarantines the unresolved slots THEN lifts (the per-write 10s execFile timeout is what releases the held lock). Proven by the hang-timeout barrier test.
+- **Risk:** a token byte leaks into a log/attention/reason string. **Mitigation:** single `audit()`/scrub chokepoint redacts every `sk-ant-…` run before any surface; quarantine reasons + oracle error strings pass through `scrub()`. Proven by the token-scrub test (an adversarial token-bearing oracle reason is redacted).
+- **Risk:** two swaps interleave and corrupt a slot. **Mitigation:** the single-mover mutex admits exactly one swap; the loser is a transient `skipped` (retry), never a partial write. Proven by the permutation-property tests (2 and 5 concurrent swaps → exactly one exchange).
+
+## Migration parity
+
+- **No migration needed.** No new config flag (reuses the Step-4b `credentialRepointing` block already in `ConfigDefaults` + `DARK_GATE_EXCLUSIONS`), no new hook, no CLAUDE.md template section (this ships dark + internal; the awareness note lives in the docs site, not the agent template — so no `templates.ts`/`migrateClaudeMd` touch, no `featureSections`/shadow-marker entry). The executor is a new module consumed by the Step-6/7 host wiring (a later increment); nothing on the production path constructs it live yet.
+
+## Dark-gate line-map
+
+- UNCHANGED. No new `enabled:` literal was added to `ConfigDefaults.ts` — the executor is gated by the existing `subscriptionPool.credentialRepointing.enabled` line (shipped by Step 4b). The dark-gate attributor reads `ConfigDefaults.ts` `enabled:` lines only; none shifted. Verified: `node scripts/lint-dev-agent-dark-gate.js` → clean; `tests/unit/credential-repointing-dark-gate.test.ts` → green; the dark-gate ground-truth test → unchanged.
+
+## Rollback
+
+- The feature is already dark (`enabled:false` + `dryRun:true`) — the executor is inert. To fully revert Step 5: remove `src/core/CredentialSwapExecutor.ts` + its three test files, revert the lint allowlist entry + its self-test edit, and drop the `under-the-hood.md` subsection. Dark + additive throughout; no consumer on the production path depends on it yet.
+
+## Tests
+
+- `tests/unit/credential-swap-executor.test.ts` (20) — dark/dryRun inertness; preconditions (non-member/quarantined/no-refresh-token rejection, zero writes); the happy exchange (keychain-first, identity-verified, §0.d one-lineage-per-home, staging retained→step-6 delete); **clobber-race** (different-tenant→abort, same-tenant-newer→adopt); **identity verify/repair/quarantine** (mismatch→one-repair→commit; oracle-unavailable→quarantine-never-repair); **THE blocker lens** (no committed-unverified write); **permutation-property** (2 + 5 concurrent swaps serialize, exactly one exchange); **crash-at-every-boundary** (budgets 0/1/2 + hang-timeout barrier with pre-lift quarantine); orphan-staging sweep predicate; token-scrub.
+- `tests/integration/credential-swap-executor-host.test.ts` (2) — the executor composed exactly as the Step-7 host will (REAL `CredentialIdentityOracle` profile-endpoint + REAL pool-mapping + REAL ledger + REAL funnel): oracle ALLOW → commit; oracle UNAVAILABLE (5xx) at verify → QUARANTINE + attention.
+- `tests/e2e/credential-swap-executor-dark-ship-lifecycle.test.ts` (3) — Phase-1 dark-ship inertness on the PRODUCTION config path: a DEV and a fleet agent's real ConfigDefaults gate the executor to a strict no-op (zero writes, ledger untouched, byte-identical blobs); recovery on the dark config is still crash-safe (an already-begun exchange finishes regardless of dryRun).
+- Full unit suite green (zero regressions); `npm run lint` clean (tsc + all structural lints).
+
+## Phase C answer (operator clarity)
+
+The swap is **per-machine local** — it moves a credential between config slots on ONE machine and adds no cross-machine egress / no LAN/broadcast assumption. An N-machine pool runs its single-mover mutex + recovery barrier independently per machine, so the fleet never has two movers on the same home; each machine's executor is bounded by its own mutex.
+
+## 4-lens adversarial verdict
+
+- **Unverified-write bypass (THE blocker):** PASS — no path commits a slot the oracle cannot identity-confirm; an unconfirmable slot is quarantined and `swap()` returns before `recordAssignment`. Test: "no committed-unverified write".
+- **Clobber-race / source-slot CAS:** PASS — a concurrent client write is adopted (same tenant) or aborts (different tenant / unconfirmable), never silently overwritten. Tests: clobber-race adopt/abort.
+- **Crash-boundary coherence:** PASS — journal begin/done + retained staging + adopt-on-newer recovery leave no lost-lineage state. Tests: crash budgets 0/1/2 + hang-timeout barrier.
+- **Dark-ship inertness:** PASS — flag off → strict no-op; reuses the existing dark-gate exclusion (no line shift). Tests: E2E dark-ship (dev+fleet) + dark-gate.
+
+<!-- tracked: 20905 -->