v1.68.3.0 fix(pairing): re-pair to narrow revokes the old grant on the spot

POST /pair minted a new setup key but never touched the agent's live
session, so re-pairing --client X --restrict read while X was connected (or
whose 5-min key expired unexchanged) left the original full-access session,
eval included, alive up to 24h.

A reducing re-pair (fewer scopes, tighter domains, lower rate, stricter tab
policy) now revokes the live session and releases its tabs before minting
the new key (grantReducesAccess + revokeClientFully; superseded in the
response). Non-reducing re-pairs keep the session and only drop stale PENDING
setup keys, so a broaden/refresh never strands a working agent and a
narrowing re-pair issued before the agent connects can't leave the old broad
key exchangeable. Revoke happens before mint (revokeToken deletes all of a
client's tokens). CLI prints a version-skew-safe supersede notice and warns
when a re-pair-shaped call omits --client. Docs + CHANGELOG + VERSION.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

browse/test/pair-agent-e2e.test.ts

@@ -318,6 +318,61 @@ describe('pair-agent flow end-to-end (HTTP only, no ngrok)', () => {
     expect(body.error).not.toBe('Invalid request body');
   });
 
+  // ─── D1: a reducing re-pair supersedes the prior grant immediately ────
+
+  const pairAs = async (body: any) => (await (await fetch(`${daemon.baseUrl}/pair`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${daemon.token}` },
+    body: JSON.stringify(body),
+  })).json()) as any;
+  const connectKey = async (setup_key: string) => {
+    const r = await fetch(`${daemon.baseUrl}/connect`, {
+      method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ setup_key }),
+    });
+    return { status: r.status, body: await r.json().catch(() => ({})) as any };
+  };
+  const statusWith = (token: string) => fetch(`${daemon.baseUrl}/command`, {
+    method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+    body: JSON.stringify({ command: 'status', args: [] }),
+  });
+
+  test('reducing re-pair revokes the prior session immediately, without exchanging the new key', async () => {
+    const { setup_key: k1 } = await pairAs({ clientId: 'reduce-me' });      // broad
+    const { body: c1 } = await connectKey(k1);
+    const s1 = c1.token as string;
+    expect((await statusWith(s1)).status).not.toBe(401);                    // works
+    // Narrow WITHOUT exchanging the new key — this is the whole bug.
+    const rp = await pairAs({ clientId: 'reduce-me', scopes: ['read'] });
+    expect(rp.superseded?.tokens_deleted).toBeGreaterThanOrEqual(1);
+    expect((await statusWith(s1)).status).toBe(401);                        // old session revoked
+    // The new narrow key still works and yields the reduced scope.
+    const c2 = await connectKey(rp.setup_key);
+    expect(c2.status).toBe(200);
+    expect(c2.body.scopes).toEqual(['read']);
+    expect((await statusWith(c2.body.token)).status).not.toBe(401);
+  });
+
+  test('reducing re-pair BEFORE connect kills the stale broad setup key; only the narrow key works', async () => {
+    const { setup_key: broad } = await pairAs({ clientId: 'shadow' });      // never connected
+    const rp = await pairAs({ clientId: 'shadow', scopes: ['read'] });      // narrowing re-pair
+    expect(rp.superseded).toBeUndefined();                                  // no live session existed
+    expect((await connectKey(broad)).status).toBe(401);                     // stale broad key dead
+    const c = await connectKey(rp.setup_key);
+    expect(c.status).toBe(200);
+    expect(c.body.scopes).toEqual(['read']);                               // narrow key survives
+  });
+
+  test('broadening re-pair does NOT revoke the working session (no outage)', async () => {
+    const first = await pairAs({ clientId: 'broaden', scopes: ['read'] });
+    expect(first.superseded).toBeUndefined();                              // first pair supersedes nothing
+    const { body: c } = await connectKey(first.setup_key);
+    const s = c.token as string;
+    expect((await statusWith(s)).status).not.toBe(401);
+    const rp = await pairAs({ clientId: 'broaden', scopes: ['read', 'write'] }); // broaden
+    expect(rp.superseded).toBeUndefined();                                 // session not superseded
+    expect((await statusWith(s)).status).not.toBe(401);                    // still working
+  });
+
   // ─── D3: DELETE /token releases tabs unconditionally; 404 only when empty ─
 
   test('DELETE /token returns tabs_released and 404 only when nothing to revoke or release', async () => {

browse/test/token-registry.test.ts

@@ -7,6 +7,8 @@ import {
   serializeRegistry, restoreRegistry, checkConnectRateLimit,
   SCOPE_READ, SCOPE_WRITE, SCOPE_ADMIN, SCOPE_CONTROL, SCOPE_META,
   DEFAULT_PAIR_SCOPES, InvalidScopeError, ReservedClientIdError,
+  revokeSetupKeys, getClientSession, grantReducesAccess,
+  type TokenInfo, type ResolvedGrant,
   __resetRegistry,
 } from '../src/token-registry';
 
@@ -40,6 +42,16 @@ describe('token-registry', () => {
       expect(key.clientId.startsWith('remote-')).toBe(true);
     });
 
+    it('revokeSetupKeys drops only PENDING keys, keeping the spent key and the session', () => {
+      const k1 = createSetupKey({ clientId: 'x' });   // pending
+      exchangeSetupKey(k1.token);                      // k1 now spent + a session exists
+      createSetupKey({ clientId: 'x' });               // pending k2
+      expect(revokeSetupKeys('x')).toBe(1);            // only the pending k2
+      expect(getClientSession('x')).not.toBeNull();    // session kept
+      // The spent key survives for idempotent re-exchange (#2646).
+      expect(exchangeSetupKey(k1.token)).not.toBeNull();
+    });
+
     it('restoreRegistry skips a persisted "root" entry instead of injecting a bypass token', () => {
       restoreRegistry({ agents: {
         root: { token: 'gsk_sess_evil', type: 'session', scopes: ['read', 'write', 'admin', 'meta', 'control'], tabPolicy: 'shared', rateLimit: 0, expiresAt: null, createdAt: new Date().toISOString() } as any,
@@ -52,6 +64,49 @@ describe('token-registry', () => {
     });
   });
 
+  // D1: drives the /pair supersede decision. Direction matters — dropping an
+  // allowlisted domain is the reduction, not adding one; 0 = unlimited rate.
+  describe('grantReducesAccess (D1)', () => {
+    const prior = (o: Partial<TokenInfo> = {}): TokenInfo => ({
+      token: 't', clientId: 'c', type: 'session',
+      scopes: ['read', 'write', 'admin', 'meta'], tabPolicy: 'own-only',
+      rateLimit: 10, expiresAt: null, createdAt: '', commandCount: 0, ...o,
+    });
+    const grant = (o: Partial<ResolvedGrant> = {}): ResolvedGrant => ({
+      scopes: ['read', 'write', 'admin', 'meta'], rateLimit: 10, tabPolicy: 'own-only', ...o,
+    });
+
+    it('scopes: drop → reduce; add/equal → not; dropping control → reduce', () => {
+      expect(grantReducesAccess(prior({ scopes: ['read', 'write', 'admin', 'meta'] }), grant({ scopes: ['read'] }))).toBe(true);
+      expect(grantReducesAccess(prior({ scopes: ['read'] }), grant({ scopes: ['read', 'write'] }))).toBe(false);
+      expect(grantReducesAccess(prior({ scopes: ['read'] }), grant({ scopes: ['read'] }))).toBe(false);
+      expect(grantReducesAccess(prior({ scopes: ['read', 'control'] }), grant({ scopes: ['read'] }))).toBe(true);
+    });
+
+    it('domains: drop → reduce; add/equal → not; unrestricted→restricted → reduce; glob narrowing → reduce', () => {
+      expect(grantReducesAccess(prior({ domains: ['a.com', 'b.com'] }), grant({ domains: ['a.com'] }))).toBe(true);
+      expect(grantReducesAccess(prior({ domains: ['a.com'] }), grant({ domains: ['a.com', 'b.com'] }))).toBe(false);
+      expect(grantReducesAccess(prior({ domains: ['a.com'] }), grant({ domains: ['a.com'] }))).toBe(false);
+      expect(grantReducesAccess(prior({ domains: undefined }), grant({ domains: ['a.com'] }))).toBe(true);
+      expect(grantReducesAccess(prior({ domains: ['a.com'] }), grant({ domains: undefined }))).toBe(false);
+      expect(grantReducesAccess(prior({ domains: ['*.example.com'] }), grant({ domains: ['*.com'] }))).toBe(false); // widen
+      expect(grantReducesAccess(prior({ domains: ['*.com'] }), grant({ domains: ['*.example.com'] }))).toBe(true);  // narrow
+    });
+
+    it('rate (0 = unlimited): unlimited→capped → reduce; lower cap → reduce; higher/equal → not', () => {
+      expect(grantReducesAccess(prior({ rateLimit: 0 }), grant({ rateLimit: 10 }))).toBe(true);
+      expect(grantReducesAccess(prior({ rateLimit: 10 }), grant({ rateLimit: 5 }))).toBe(true);
+      expect(grantReducesAccess(prior({ rateLimit: 5 }), grant({ rateLimit: 10 }))).toBe(false);
+      expect(grantReducesAccess(prior({ rateLimit: 10 }), grant({ rateLimit: 10 }))).toBe(false);
+      expect(grantReducesAccess(prior({ rateLimit: 10 }), grant({ rateLimit: 0 }))).toBe(false); // → unlimited = broaden
+    });
+
+    it('tabPolicy: shared → own-only → reduce; the reverse → not', () => {
+      expect(grantReducesAccess(prior({ tabPolicy: 'shared' }), grant({ tabPolicy: 'own-only' }))).toBe(true);
+      expect(grantReducesAccess(prior({ tabPolicy: 'own-only' }), grant({ tabPolicy: 'shared' }))).toBe(false);
+    });
+  });
+
   describe('root token', () => {
     it('identifies root token correctly', () => {
       expect(isRootToken('root-token-for-tests')).toBe(true);