@startsimpli/integrations 0.2.27 → 0.2.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/integrations",
-  "version": "0.2.27",
+  "version": "0.2.29",
   "description": "Provider-agnostic types, API clients, hooks, and UI primitives for email + calendar integrations across StartSimpli apps.",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/__tests__/connect-claude.test.tsx

@@ -0,0 +1,143 @@
+/**
+ * The "connect an MCP client" composer (bd startsim-62dca).
+ *
+ * THE ASSERTION THIS FILE EXISTS FOR is `never mints without a click`. Every
+ * other surface in this package reads; this one ISSUES A CREDENTIAL that reads a
+ * workspace as a human, lasts weeks, and cannot be withdrawn before it expires
+ * (startsim-ja8mt). A mint fired from an effect, a retry, or a re-render would
+ * scatter live bearers nobody asked for and nobody can cancel — and it would do
+ * it silently, because each one succeeds. So the number of POSTs is asserted,
+ * not assumed.
+ *
+ * The rest pins the four disclosures the bead requires. They are not decoration:
+ * a screen that renders a copy button without them is lying by omission about
+ * what the user is about to hand over.
+ */
+import { describe, expect, it, vi } from 'vitest';
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+import { ConnectClaudePage } from '../components/pages/ConnectClaudePage';
+import type { McpTokensApi } from '../api/mcp-tokens';
+
+const MINTED = {
+  token: 'eyJhbGciOiJSUzI1NiJ9.PAYLOAD.SIG',
+  token_type: 'Bearer',
+  foundry: 'tandem',
+  audience: 'tenant:tandem',
+  acting_as: { org_id: 'tandem', role: 'owner', email: 'qa-tandem@startsimpli.com' },
+  jti: 'abc123',
+  issued_at: '2026-08-27T00:00:00Z',
+  expires_at: '2026-09-26T00:00:00Z',
+  mcp_url: 'https://tandem.ai.startsimpli.com/api/v1/mcp/',
+  claude_code_command:
+    'claude mcp add --transport http tandem https://tandem.ai.startsimpli.com/api/v1/mcp/ --header "Authorization: Bearer eyJ…"',
+  notice: 'Shown once — store it like a password. It cannot be revoked before it expires.',
+};
+
+function stubApi(overrides: Partial<McpTokensApi> = {}): McpTokensApi {
+  return {
+    list: vi.fn().mockResolvedValue({
+      foundries: [
+        { slug: 'tandem', name: 'Tandem', audience: 'tenant:tandem', mcp_url: MINTED.mcp_url, state: 'live' },
+      ],
+      default_ttl_days: 30,
+      max_ttl_days: 90,
+    }),
+    mint: vi.fn().mockResolvedValue(MINTED),
+    ...overrides,
+  };
+}
+
+describe('ConnectClaudePage', () => {
+  it('NEVER mints without a click', async () => {
+    const api = stubApi();
+    render(<ConnectClaudePage api={api} />);
+    await waitFor(() => expect(api.list).toHaveBeenCalled());
+    // Give any stray effect a chance to fire before asserting the absence.
+    await new Promise((r) => setTimeout(r, 25));
+    expect(api.mint).not.toHaveBeenCalled();
+  });
+
+  it('mints exactly once per click, never once per render', async () => {
+    const api = stubApi();
+    const { rerender } = render(<ConnectClaudePage api={api} />);
+    await screen.findByRole('button', { name: /create connection token/i });
+    await userEvent.click(screen.getByRole('button', { name: /create connection token/i }));
+    await screen.findByText(/copy it now/i);
+    rerender(<ConnectClaudePage api={api} />);
+    expect(api.mint).toHaveBeenCalledTimes(1);
+  });
+
+  it('warns about the consequences BEFORE the token exists', async () => {
+    // A warning that only appears next to the credential is one nobody can act
+    // on — by then it has been issued and cannot be taken back.
+    render(<ConnectClaudePage api={stubApi()} />);
+    const note = await screen.findByRole('note');
+    expect(note.textContent).toMatch(/as\s+you/i);
+    expect(note.textContent).toMatch(/cannot be cancelled before it expires/i);
+    expect(note.textContent).toMatch(/shown once/i);
+    // ...and specifically that losing the seat does not switch it off.
+    expect(note.textContent).toMatch(/does not switch this one off/i);
+  });
+
+  it('shows WHOSE data the token reads, from the server, not the browser', async () => {
+    render(<ConnectClaudePage api={stubApi()} />);
+    await userEvent.click(await screen.findByRole('button', { name: /create connection token/i }));
+    // Scoped to the identity card, because the slug legitimately appears in
+    // several places on this page (the command, the URL) and a bare text query
+    // would pass on any of them rather than on the one that states WHOSE.
+    const identity = (await screen.findByText(/This connection reads/i))
+      .closest('div') as HTMLElement;
+    expect(identity.textContent).toMatch(/qa-tandem@startsimpli\.com/);
+    expect(identity.textContent).toMatch(/owner/);
+    expect(identity.textContent).toMatch(/tandem/);
+  });
+
+  it('shows when it expires as a date, not an ISO string', async () => {
+    render(<ConnectClaudePage api={stubApi()} />);
+    await userEvent.click(await screen.findByRole('button', { name: /create connection token/i }));
+    const expiry = await screen.findByText(/Expires/);
+    expect(expiry.textContent).not.toMatch(/2026-09-26T00:00:00Z/);
+    expect(expiry.textContent).toMatch(/2026/);
+  });
+
+  it('renders the command the SERVER composed, not one it builds itself', async () => {
+    // The tenant's own record knows its host; a vanity domain would break a
+    // pattern assembled in the browser.
+    render(<ConnectClaudePage api={stubApi()} />);
+    await userEvent.click(await screen.findByRole('button', { name: /create connection token/i }));
+    expect(await screen.findByText(/claude mcp add --transport http tandem/)).toBeTruthy();
+  });
+
+  it('surfaces a refused mint as the reason, not as an outage', async () => {
+    // The listing is advisory; central decides membership independently, so a
+    // 403 here is an ordinary answer the user has to be able to read.
+    const api = stubApi({ mint: vi.fn().mockRejectedValue(new Error('You do not have an active seat in `tandem`')) });
+    render(<ConnectClaudePage api={api} />);
+    await userEvent.click(await screen.findByRole('button', { name: /create connection token/i }));
+    const alert = await screen.findByRole('alert');
+    expect(alert.textContent).toMatch(/active seat/i);
+    expect(screen.queryByText(/copy it now/i)).toBeNull();
+  });
+
+  it('says so plainly when the account is in no workspace', async () => {
+    const api = stubApi({
+      list: vi.fn().mockResolvedValue({ foundries: [], default_ttl_days: 30, max_ttl_days: 90 }),
+    });
+    render(<ConnectClaudePage api={api} />);
+    expect(await screen.findByText(/not a member of any workspace/i)).toBeTruthy();
+    expect(screen.queryByRole('button', { name: /create connection token/i })).toBeNull();
+  });
+
+  it('names no foundry, vendor or product of its own', async () => {
+    // Everything specific must arrive as DATA. Rendering an empty list must not
+    // leak a hardcoded example workspace into the page.
+    const api = stubApi({
+      list: vi.fn().mockResolvedValue({ foundries: [], default_ttl_days: 30, max_ttl_days: 90 }),
+    });
+    const { container } = render(<ConnectClaudePage api={api} />);
+    await screen.findByText(/not a member of any workspace/i);
+    expect(container.textContent).not.toMatch(/tandem|mcr|marketing-agents/i);
+  });
+});

package/src/__tests__/corpus-source-strip.test.tsx

@@ -0,0 +1,243 @@
+/**
+ * THE LIBRARY'S SOURCE STRIP MUST LIST THE SOURCES A MEMBER ACTUALLY HAS
+ * (bd startsim-pg8na RED / startsim-bu04n GREEN).
+ *
+ * REPORTED ON THE LIVE TANDEM TENANT, 2026-08-26: the strip showed Granola
+ * ("Failing", 20 syncs in a row failed) and n8n, while the records listed below
+ * it were Fathom and Granola documents, and the member's own Fathom and Dropbox
+ * connections never appeared at all.
+ *
+ * WHERE THE ROWS COME FROM, which the original diagnosis got wrong and which
+ * decides what may be tested here. There is no tenant-local connections table.
+ * `tenant-starter/config/urls.py` routes `api/v1/connections/` to
+ * `ConnectionsView`, whose only job is to forward the caller's already-verified
+ * bearer to CENTRAL's `/api/v1/subtree/connections/` and return the page
+ * envelope untouched ("proxied from central so the call stays same-origin",
+ * bd startsim-768w.38.19). So `listSources()` is already reading central — it is
+ * reading central's SHARED-only surface, and the two facts line up exactly:
+ *
+ *     TENANT  GET /api/v1/connections/   -> granola, n8n
+ *     CENTRAL Connection rows for tandem -> dropbox(owner qosha),
+ *                                           fathom(owner qosha),
+ *                                           granola(SHARED), n8n(SHARED)
+ *
+ * `SubtreeConnectionsView` resolves through `Connection.objects.for_scope(...)`,
+ * which is `owner IS NULL`. Granola and n8n are not stale junk: they are the
+ * foundry's real shared connections, and Granola really is failing. The two
+ * missing cards are missing because the server was never asked for them.
+ *
+ * THE DIVISION OF LABOUR THIS FILE ASSUMES.
+ *
+ *   Server: a member's OWN rows reach this endpoint. That is a union of
+ *           `for_scope(orgs) | for_owner(orgs, request.user)` in central — the
+ *           remedy `SubtreeConnectionsView` names in its own source, bounded to
+ *           the requesting user so the disclosure bd startsim-768w.22.25.11
+ *           closed stays closed. It cannot be done from this package, and it
+ *           must not be done by merging in `/api/v1/connections/me/`: that
+ *           surface's serializer carries `last_checked_at` and NOTHING ELSE of
+ *           the three freshness facts (no `last_synced_at`, no
+ *           `last_attempt_at`, no `consecutive_failures` — see
+ *           `ConnectionSerializer.Meta.fields`), so every personal card built
+ *           from it would report a verified credential as delivered data. That
+ *           is precisely the lie bd startsim-1cow removed.
+ *
+ *   Client: what arrives is rendered honestly. A connection carries an owner or
+ *           it does not and the strip treats both alike; a connection the member
+ *           DISCONNECTED is not a source of the corpus and must stop appearing
+ *           as one.
+ *
+ * The second half is the part that fails today, and it is the "legacy ones
+ * masquerading as sources" the report describes: `disconnect()` deliberately
+ * keeps the card as `status: 'disabled'` ("DISCONNECT, not delete … the card
+ * survives as `disabled`, so the record that this vendor was connected is not
+ * thrown away"), and `listSources()` has no case for that status, so a vendor
+ * nobody is connected to any more falls through and renders next to the live
+ * ones. Not a denylist of connector keys — `status` is data the server writes.
+ */
+import { describe, expect, it } from 'vitest';
+import { render, screen, within } from '@testing-library/react';
+
+import { LibraryPage } from '../components/pages/LibraryPage';
+import { createCorpusApi } from '../corpus/client';
+import type { CorpusHttp } from '../corpus/client';
+import { FIXTURE_ORG } from '../corpus/fixtures';
+
+const SCOPE = { orgId: FIXTURE_ORG };
+const EMPTY_PAGE = { count: 0, next: null, previous: null, results: [] };
+
+const NOW = Date.now();
+const ago = (ms: number) => new Date(NOW - ms).toISOString();
+const AN_HOUR_AGO = ago(60 * 60_000);
+const TEN_MINUTES_AGO = ago(10 * 60_000);
+
+/** Every path this adapter asked for, so a widening read cannot pass unnoticed. */
+interface Recorder {
+  http: CorpusHttp;
+  calls: Array<{ path: string; params?: Record<string, unknown> }>;
+}
+
+/**
+ * The WIRE, not the contract — rows go in exactly as central serialises them.
+ * Same convention as `corpus-freshness.test.tsx`, for the same reason: a fixture
+ * must never be more generous than the server that feeds it.
+ */
+function recorderOver(rows: Array<Record<string, unknown>>): Recorder {
+  const calls: Array<{ path: string; params?: Record<string, unknown> }> = [];
+  return {
+    calls,
+    http: {
+      async get<T>(path: string, options?: { params?: Record<string, unknown> }): Promise<T> {
+        calls.push({ path, params: options?.params });
+        if (path.includes('connections')) {
+          return { count: rows.length, next: null, previous: null, results: rows } as T;
+        }
+        return EMPTY_PAGE as T;
+      },
+    },
+  };
+}
+
+function sourcesFrom(rows: Array<Record<string, unknown>>) {
+  const { http } = recorderOver(rows);
+  return createCorpusApi({ http, scope: SCOPE }).listSources();
+}
+
+/** The foundry's shared Granola: real, connected, and genuinely failing. */
+const SHARED_GRANOLA = {
+  id: 'shared-granola',
+  connector_key: 'granola',
+  connector_name: 'Granola',
+  status: 'connected',
+  check_error: '',
+  last_synced_at: null,
+  last_attempt_at: TEN_MINUTES_AGO,
+  last_checked_at: null,
+  consecutive_failures: 20,
+};
+
+/**
+ * The member's OWN Fathom, as central serialises an owned row once the subtree
+ * read includes them. `owner` is the only structural difference, and the strip
+ * must not care: whose account it is decides who may SEE the row, server-side.
+ */
+const MY_FATHOM = {
+  id: 'my-fathom',
+  connector_key: 'fathom',
+  connector_name: 'Fathom',
+  owner: 'qosha@debugg.ai',
+  status: 'connected',
+  check_error: '',
+  last_synced_at: AN_HOUR_AGO,
+  last_attempt_at: AN_HOUR_AGO,
+  last_checked_at: AN_HOUR_AGO,
+  consecutive_failures: 0,
+};
+
+/** A vendor the member has DISCONNECTED. The card survives; the source does not. */
+const DISCONNECTED_DROPBOX = {
+  id: 'old-dropbox',
+  connector_key: 'dropbox',
+  connector_name: 'Dropbox',
+  owner: 'qosha@debugg.ai',
+  status: 'disabled',
+  check_error: '',
+  last_synced_at: null,
+  last_attempt_at: null,
+  last_checked_at: null,
+  consecutive_failures: 0,
+};
+
+describe('listSources — a personal connection is a source like any other', () => {
+  it('lists the member’s own connection alongside the foundry’s shared ones', async () => {
+    const sources = await sourcesFrom([SHARED_GRANOLA, MY_FATHOM]);
+
+    expect(sources.map((source) => source.source).sort()).toEqual(['fathom', 'granola']);
+  });
+
+  it('keeps a personal connection’s freshness intact rather than flattening it', async () => {
+    const [fathom] = await sourcesFrom([MY_FATHOM]);
+
+    // The whole reason a merge from `/api/v1/connections/me/` is refused: that
+    // payload has no `last_synced_at` at all, so a card built from it could only
+    // ever say "nothing yet" over data that arrived an hour ago.
+    expect(fathom.lastSyncedAt).toBe(AN_HOUR_AGO);
+    expect(fathom.status).toBe('ok');
+    expect(fathom.label).toBe('Fathom');
+  });
+
+  it('reads one connections endpoint and does not widen the read to reach them', async () => {
+    // A single source of truth, stated as a test so a future "just also fetch
+    // everybody's" cannot be added quietly. The bound that actually keeps
+    // bd startsim-768w.22.25.11 closed is server-side; this pins that the client
+    // never asks for more than the member-scoped page it is handed.
+    const recorder = recorderOver([SHARED_GRANOLA, MY_FATHOM]);
+    await createCorpusApi({ http: recorder.http, scope: SCOPE }).listSources();
+
+    const connectionReads = recorder.calls.filter((call) => call.path.includes('connections'));
+    expect(connectionReads).toHaveLength(1);
+    expect(connectionReads[0].path).toBe('api/v1/connections');
+    // No owner, no user, no "all" — nothing that names a principal other than
+    // the bearer the proxy already forwarded.
+    expect(connectionReads[0].params ?? {}).toEqual({});
+  });
+});
+
+describe('listSources — a disconnected vendor is not a source', () => {
+  it('drops a connection the member has disconnected', async () => {
+    const sources = await sourcesFrom([SHARED_GRANOLA, MY_FATHOM, DISCONNECTED_DROPBOX]);
+
+    expect(sources.map((source) => source.source).sort()).toEqual(['fathom', 'granola']);
+    expect(sources.some((source) => source.source === 'dropbox')).toBe(false);
+  });
+
+  it('never renders a disconnected vendor as healthy', async () => {
+    const [source] = await sourcesFrom([DISCONNECTED_DROPBOX]);
+
+    // If it is listed at all it must not read as a working source. Today it
+    // falls through every branch and comes back `never` — "Connected, but
+    // nothing has arrived yet" about an account that is not connected.
+    expect(source).toBeUndefined();
+  });
+
+  it('keeps a broken-but-live connection, which is a different thing entirely', async () => {
+    // `needs_reauth` and `error` are still connected accounts with a credential
+    // on file and a member who can fix them. Only the lifecycle-ended row goes.
+    const sources = await sourcesFrom([
+      { ...MY_FATHOM, status: 'needs_reauth', check_error: 'The vendor rejected this key (401).' },
+      SHARED_GRANOLA,
+    ]);
+
+    expect(sources.map((source) => source.source).sort()).toEqual(['fathom', 'granola']);
+    expect(sources.find((source) => source.source === 'fathom')?.status).toBe('error');
+  });
+});
+
+describe('the Library strip, rendered', () => {
+  it('draws a card for the member’s own source and none for the disconnected one', async () => {
+    const { http } = recorderOver([SHARED_GRANOLA, MY_FATHOM, DISCONNECTED_DROPBOX]);
+    const api = createCorpusApi({ http, scope: SCOPE });
+
+    render(<LibraryPage api={api} scope={SCOPE} />);
+
+    // Scoped to the strip itself: `listSources` also feeds the source filter's
+    // options, so an unscoped query would match the same vendor twice and say
+    // nothing about which surface it appeared on.
+    const strip = within(await screen.findByRole('region', { name: 'Source freshness' }));
+    expect(strip.getByText('Fathom')).toBeInTheDocument();
+    expect(strip.getByText('Granola')).toBeInTheDocument();
+    expect(strip.queryByText('Dropbox')).not.toBeInTheDocument();
+  });
+
+  it('does not blame a disconnected vendor in the empty state', async () => {
+    // `EmptyState` names every source whose status is `error`. A vendor nobody
+    // is connected to must not be reported as "failing to sync" — the action
+    // that sentence asks for (go fix the connection) is the wrong action.
+    const { http } = recorderOver([DISCONNECTED_DROPBOX]);
+    const api = createCorpusApi({ http, scope: SCOPE });
+
+    render(<LibraryPage api={api} scope={SCOPE} />);
+
+    expect(await screen.findByText(/Nothing has been pulled in yet/i)).toBeInTheDocument();
+    expect(screen.queryByText(/Dropbox/)).not.toBeInTheDocument();
+  });
+});

package/src/api/index.ts

@@ -3,4 +3,7 @@ export * from './calendar';
 export * from './email';
 export * from './accounts';
 export * from './connections';
+// The MCP bearer mint (bd startsim-hj5zh / startsim-62dca). Central, not the
+// tenant — it rides the tenant's own /api/v1/auth/ proxy, see the module.
+export * from './mcp-tokens';
 export { setApiBase, getApiBase, setAuthTokenProvider } from './_fetch';

package/src/api/mcp-tokens.ts

@@ -0,0 +1,86 @@
+/**
+ * `/api/v1/auth/mcp-token/` — the long-lived bearer an MCP client holds for ONE
+ * foundry (bd startsim-hj5zh, surfaced by startsim-62dca).
+ *
+ * WHY THIS IS NOT A CONNECTION CLIENT even though it lives beside them. Every
+ * other client in this directory talks to the tenant or to the connectors API
+ * about a vendor account WE hold. This one talks to CENTRAL about a credential
+ * the user is about to hand to software we do not run. That inversion is the
+ * whole reason the composer over it is mostly warnings.
+ *
+ * IT MUST REACH CENTRAL, NOT THE TENANT. `request()` prefixes the configured
+ * base, and inside a tenant app that base points at the tenant's own same-origin
+ * proxy — which forwards `/api/v1/auth/*` to central (see the tenant nginx: the
+ * `/api/v1/auth/` location proxies to api.startsimpli.com, above the `/api/`
+ * location that would otherwise send it to the tenant's Django). So the ordinary
+ * base is correct here and no cross-origin call is made with a bearer on it.
+ * A client that hardcoded central's host would break that property.
+ *
+ * TWO VERBS, and the asymmetry is deliberate: `list` is safe to call on render,
+ * `mint` is not. Minting ISSUES A CREDENTIAL — it is not idempotent in any way a
+ * user cares about, because every call produces another bearer that stays valid
+ * until it expires and cannot be withdrawn (startsim-ja8mt). Nothing in this
+ * package may call `mint` from an effect.
+ */
+import { request } from './_fetch';
+
+/** A foundry the signed-in account may connect a client to. */
+export interface McpFoundry {
+  slug: string;
+  name: string;
+  audience: string;
+  mcp_url: string;
+  state: string;
+}
+
+export interface McpFoundryList {
+  foundries: McpFoundry[];
+  default_ttl_days: number;
+  max_ttl_days: number;
+}
+
+/**
+ * The mint's answer. `token` is present exactly once, in this response, and is
+ * never retrievable again — the server stores no copy it could hand back.
+ */
+export interface McpMintedToken {
+  token: string;
+  token_type: string;
+  foundry: string;
+  audience: string;
+  /**
+   * WHOSE data this reads. All three are DB-derived by central, never taken from
+   * the request, so this is the identity the tenant will actually act as — the
+   * thing a user has to see before pasting the token anywhere.
+   */
+  acting_as: { org_id: string | null; role: string | null; email: string | null };
+  jti: string | null;
+  issued_at: string;
+  expires_at: string;
+  mcp_url: string;
+  claude_code_command: string | null;
+  notice: string;
+}
+
+export interface McpTokensApi {
+  list(): Promise<McpFoundryList>;
+  mint(input: { foundry: string; ttl_days?: number }): Promise<McpMintedToken>;
+}
+
+const BASE = '/auth/mcp-token';
+
+export const mcpTokens: McpTokensApi = {
+  /**
+   * The foundries this account holds an active seat in. Advisory — central
+   * refuses the mint independently — so a slug that appears here can still be
+   * denied, and the composer has to render that denial rather than assume the
+   * list was authoritative.
+   */
+  list(): Promise<McpFoundryList> {
+    return request<McpFoundryList>(`${BASE}/`);
+  },
+
+  mint(input: { foundry: string; ttl_days?: number }): Promise<McpMintedToken> {
+    return request<McpMintedToken>(`${BASE}/`, { method: 'POST', body: input });
+  },
+};

package/src/components/index.ts

@@ -12,6 +12,10 @@ export * from './ReconsentPromptCard';
 // one level into each app.
 export * from './CredentialSchemaForm';
 export * from './pages/ConnectionsPage';
+// "Connect an MCP client" — a sibling composer, deliberately in the same place
+// as ConnectionsPage: from a user's point of view both are "connect a thing to
+// this workspace", even though this one hands a credential OUT (startsim-62dca).
+export * from './pages/ConnectClaudePage';
 export type {
   ConnectionsApi,
   ConnectorCatalogEntry,
@@ -32,20 +36,3 @@ export type {
 export * from './pages/LibraryPage';
 export * from './pages/AskPage';
 export * from './pages/TrackerPage';
-
-// The planning toolset (bd startsim-8l6ef): focuses, and the items filed under
-// them. `work-items` carries the pieces the tracker and the planner SHARE — the
-// row, the honesty banner, the overdue/changed predicates — so two views over
-// one list cannot drift into disagreeing about what they mean.
-export * from './pages/PlanningPage';
-export {
-  PRIORITY_LABELS,
-  UnfilteredNotice,
-  WORK_ITEM_DEFAULTS,
-  WorkItemRow,
-  changedSince,
-  compareForScreen,
-  isOverdue,
-  priorityLabel,
-} from './pages/work-items';
-export type { WorkItemSlot } from './pages/work-items';

package/src/components/pages/ConnectClaudePage.tsx

@@ -0,0 +1,270 @@
+/**
+ * CONNECT AN MCP CLIENT to this workspace, as one composer (bd startsim-62dca).
+ *
+ * `<ConnectClaudePage api={mcpTokens} />` is the whole integration. An app owns
+ * theme classNames and a ten-line wrapper — same shape as `ConnectionsPage`, and
+ * for the same reason: shipping primitives without the page-level composer just
+ * moves the duplication up one level.
+ *
+ * THIS SCREEN IS MOSTLY WARNINGS, AND THAT IS THE DESIGN. Every other surface in
+ * this package helps somebody connect a vendor account WE hold. This one issues
+ * a credential the user then pastes into software we do not run, which reads
+ * their workspace as them, lasts weeks, and — until bd startsim-ja8mt lands —
+ * CANNOT BE WITHDRAWN before it expires. Deactivating the member's seat stops
+ * the next mint, not this token. A screen that rendered a copy button and no
+ * consequences would be lying by omission, so the consequences are not tucked
+ * into a tooltip: they are on the page, next to the token, in the four places
+ * the bead names.
+ *
+ * NOTHING HERE NAMES A FOUNDRY, a vendor, or a client product beyond the command
+ * the server itself composed. The foundry list arrives as data from central, and
+ * `claude_code_command` is built server-side from the tenant's own record — so a
+ * foundry on a vanity domain gets its own host rather than a pattern this file
+ * guessed. An `if (slug === ...)` here would undo that.
+ *
+ * MINTING IS NEVER AUTOMATIC. `list()` runs on mount; `mint()` runs only from a
+ * click. Every call to it issues another unrevokable bearer, so a re-render, a
+ * retry, or a `useEffect` that "just refreshes" would quietly scatter live
+ * credentials. That is why the mint state machine below is explicit rather than
+ * a query hook.
+ */
+import * as React from 'react';
+
+import type { McpFoundry, McpMintedToken, McpTokensApi } from '../../api/mcp-tokens';
+
+type ClassNames = Partial<Record<
+  'root' | 'section' | 'heading' | 'card' | 'button' | 'muted' | 'error' | 'warning' | 'code', string
+>>;
+
+export interface ConnectClaudePageProps {
+  api: McpTokensApi;
+  classNames?: ClassNames;
+  /** Pre-select a foundry. Optional — with one seat the list is the answer. */
+  foundrySlug?: string;
+}
+
+const FALLBACK: Required<Pick<ClassNames,
+  'root' | 'section' | 'heading' | 'card' | 'button' | 'muted' | 'error' | 'warning' | 'code'>> = {
+  root: 'space-y-6',
+  section: 'space-y-3',
+  heading: 'text-lg font-semibold',
+  card: 'rounded-lg border p-4',
+  button: 'rounded-md border px-3 py-2 text-sm font-medium',
+  muted: 'text-sm opacity-70',
+  error: 'rounded-md border p-3 text-sm',
+  warning: 'rounded-md border p-3 text-sm',
+  code: 'block w-full overflow-x-auto rounded p-3 font-mono text-xs',
+};
+
+function cx(theme: ClassNames | undefined, key: keyof typeof FALLBACK): string {
+  return theme?.[key] ?? FALLBACK[key];
+}
+
+/** Local-date rendering, so "expires" is not an ISO string a person has to parse. */
+function readableDate(iso: string): string {
+  const d = new Date(iso);
+  return Number.isNaN(d.getTime()) ? iso : d.toLocaleDateString(undefined, {
+    year: 'numeric', month: 'long', day: 'numeric',
+  });
+}
+
+function daysUntil(iso: string): number | null {
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return null;
+  return Math.max(0, Math.round((d.getTime() - Date.now()) / 86_400_000));
+}
+
+export function ConnectClaudePage({ api, classNames, foundrySlug }: ConnectClaudePageProps) {
+  const [list, setList] = React.useState<{ foundries: McpFoundry[]; maxTtl: number; defaultTtl: number } | null>(null);
+  const [selected, setSelected] = React.useState<string>(foundrySlug ?? '');
+  const [ttlDays, setTtlDays] = React.useState<number | ''>('');
+  const [minted, setMinted] = React.useState<McpMintedToken | null>(null);
+  const [minting, setMinting] = React.useState(false);
+  const [error, setError] = React.useState<string>('');
+  const [copied, setCopied] = React.useState<'' | 'token' | 'command'>('');
+
+  React.useEffect(() => {
+    let live = true;
+    api.list().then(
+      (r) => {
+        if (!live) return;
+        setList({ foundries: r.foundries, maxTtl: r.max_ttl_days, defaultTtl: r.default_ttl_days });
+        setSelected((cur) => cur || (r.foundries.length === 1 ? r.foundries[0].slug : cur));
+      },
+      (e: unknown) => { if (live) setError(e instanceof Error ? e.message : String(e)); },
+    );
+    return () => { live = false; };
+  }, [api]);
+
+  async function doMint() {
+    if (!selected || minting) return;
+    setMinting(true);
+    setError('');
+    try {
+      // The ONLY call site. See the module docstring: nothing may mint from an
+      // effect, a retry, or a render.
+      const r = await api.mint({ foundry: selected, ...(ttlDays === '' ? {} : { ttl_days: ttlDays }) });
+      setMinted(r);
+    } catch (e: unknown) {
+      // A 403 here is the ordinary case, not an outage: the listing is advisory
+      // and central decides membership independently. Show what it said.
+      setError(e instanceof Error ? e.message : String(e));
+    } finally {
+      setMinting(false);
+    }
+  }
+
+  async function copy(text: string, which: 'token' | 'command') {
+    try {
+      await navigator.clipboard.writeText(text);
+      setCopied(which);
+      window.setTimeout(() => setCopied(''), 2000);
+    } catch {
+      // A denied clipboard permission must not read as a failed mint — the token
+      // is on screen and selectable either way.
+      setCopied('');
+    }
+  }
+
+  if (error && !list) {
+    return <div className={cx(classNames, 'error')} role="alert">{error}</div>;
+  }
+  if (!list) {
+    return <p className={cx(classNames, 'muted')}>Loading…</p>;
+  }
+  if (list.foundries.length === 0) {
+    return (
+      <div className={cx(classNames, 'card')}>
+        <p className={cx(classNames, 'muted')}>
+          You are not a member of any workspace that can be connected yet. Ask an
+          owner or admin to invite you, then come back.
+        </p>
+      </div>
+    );
+  }
+
+  const chosen = list.foundries.find((f) => f.slug === selected);
+
+  return (
+    <div className={cx(classNames, 'root')}>
+      {!minted && (
+        <section className={cx(classNames, 'section')}>
+          {list.foundries.length > 1 && (
+            <label className="block">
+              <span className={cx(classNames, 'heading')}>Which workspace?</span>
+              <select
+                className="mt-1 block w-full rounded-md border px-3 py-2"
+                value={selected}
+                onChange={(e) => setSelected(e.target.value)}
+              >
+                <option value="">Choose…</option>
+                {list.foundries.map((f) => (
+                  <option key={f.slug} value={f.slug}>{f.name}</option>
+                ))}
+              </select>
+            </label>
+          )}
+
+          <label className="block">
+            <span className={cx(classNames, 'heading')}>How long should it last?</span>
+            <input
+              type="number"
+              min={1}
+              max={list.maxTtl}
+              placeholder={`${list.defaultTtl} days`}
+              className="mt-1 block w-full rounded-md border px-3 py-2"
+              value={ttlDays}
+              onChange={(e) => setTtlDays(e.target.value === '' ? '' : Number(e.target.value))}
+            />
+            <span className={cx(classNames, 'muted')}>
+              Up to {list.maxTtl} days. Shorter is safer — this cannot be
+              cancelled early, so the expiry date is the only way it stops working.
+            </span>
+          </label>
+
+          {/* The consequences, BEFORE the button rather than after the token.
+              A warning that appears only once the credential exists is a warning
+              nobody can act on. */}
+          <div className={cx(classNames, 'warning')} role="note">
+            <strong>Before you create this:</strong> it reads this workspace <em>as
+            you</em> — whatever you can see, it can see. It is shown once and
+            cannot be retrieved again, and it <strong>cannot be cancelled before
+            it expires</strong>. Turning off your access to the workspace stops
+            new ones being made; it does not switch this one off.
+          </div>
+
+          <button
+            type="button"
+            className={cx(classNames, 'button')}
+            disabled={!selected || minting}
+            onClick={doMint}
+          >
+            {minting ? 'Creating…' : 'Create connection token'}
+          </button>
+
+          {error && <div className={cx(classNames, 'error')} role="alert">{error}</div>}
+        </section>
+      )}
+
+      {minted && (
+        <section className={cx(classNames, 'section')}>
+          <h2 className={cx(classNames, 'heading')}>Your token — copy it now</h2>
+
+          {/* WHOSE DATA, stated first. The mint derives these server-side from
+              the DB, so this is the identity the workspace will actually act as
+              — not what the browser asked for. */}
+          <div className={cx(classNames, 'card')}>
+            <p className={cx(classNames, 'muted')}>This connection reads</p>
+            <p>
+              <strong>{minted.foundry}</strong>
+              {minted.acting_as.email ? <> as <strong>{minted.acting_as.email}</strong></> : null}
+              {minted.acting_as.role ? <> ({minted.acting_as.role})</> : null}
+            </p>
+            <p className={cx(classNames, 'muted')}>
+              Expires {readableDate(minted.expires_at)}
+              {daysUntil(minted.expires_at) !== null ? ` — about ${daysUntil(minted.expires_at)} days` : ''}
+            </p>
+          </div>
+
+          <div className={cx(classNames, 'warning')} role="alert">
+            {minted.notice}
+          </div>
+
+          {minted.claude_code_command && (
+            <div className={cx(classNames, 'section')}>
+              <p className={cx(classNames, 'muted')}>Run this in your terminal:</p>
+              <code className={cx(classNames, 'code')}>{minted.claude_code_command}</code>
+              <button
+                type="button"
+                className={cx(classNames, 'button')}
+                onClick={() => copy(minted.claude_code_command as string, 'command')}
+              >
+                {copied === 'command' ? 'Copied' : 'Copy command'}
+              </button>
+            </div>
+          )}
+
+          <details>
+            <summary className={cx(classNames, 'muted')}>Just the token</summary>
+            <code className={cx(classNames, 'code')}>{minted.token}</code>
+            <button
+              type="button"
+              className={cx(classNames, 'button')}
+              onClick={() => copy(minted.token, 'token')}
+            >
+              {copied === 'token' ? 'Copied' : 'Copy token'}
+            </button>
+          </details>
+
+          <button
+            type="button"
+            className={cx(classNames, 'button')}
+            onClick={() => { setMinted(null); setCopied(''); }}
+          >
+            Done
+          </button>
+        </section>
+      )}
+    </div>
+  );
+}

package/src/corpus/client.ts

@@ -292,6 +292,42 @@ function at(value: unknown): string | null {
   return typeof value === 'string' && value.trim() ? value : null;
 }
 
+/**
+ * Connection lifecycle states in which the account is NO LONGER CONNECTED
+ * (bd startsim-bu04n).
+ *
+ * `Connection.Status` is `connected | needs_reauth | error | disabled`, and only
+ * the last one has ended: the member disconnected it. Central's member surface
+ * documents what that leaves behind — "DISCONNECT, not delete. One transaction
+ * stops the scheduled fetches, revokes every token issued for the account and
+ * deletes the stored credential; the card survives as `disabled`, so the record
+ * that this vendor was connected is not thrown away."
+ *
+ * The card surviving is right for the connections screen, where a member manages
+ * it and may reconnect. It is wrong for the Library's source strip, whose whole
+ * question is "where is my corpus coming from, and is it current". A vendor with
+ * no credential and no schedule is not coming from anywhere, and it used to fall
+ * through every branch below to `never` — "Connected, but nothing has arrived
+ * yet" printed about an account that is not connected.
+ *
+ * A STATUS, NOT A VENDOR. This reads the lifecycle field central writes, so a
+ * connector added tomorrow is handled with no code change here. A list of
+ * connector keys would be exactly the per-vendor branch the DB-driven catalog
+ * exists to prevent, and the reported symptom ("it shows old, disconnected
+ * ones") is precisely the symptom such a list would paper over.
+ *
+ * AN UNRECOGNISED STATUS IS KEPT, deliberately. `needs_reauth` and `error` are
+ * live accounts with a credential on file and a member who can fix them; the
+ * failure mode of hiding one of those — a real source silently absent from the
+ * strip — is worse than the failure mode of showing a status this build has not
+ * heard of yet. A new terminal state is added here on purpose, not by default.
+ */
+const RETIRED_CONNECTION_STATUSES: ReadonlySet<string> = new Set(['disabled']);
+
+function isALiveSource(connection: Record<string, unknown>): boolean {
+  return !RETIRED_CONNECTION_STATUSES.has(String(connection.status ?? ''));
+}
+
 /** Rows written in parallel. Small enough not to look like a burst to the tenant. */
 const WRITE_CONCURRENCY = 6;
 
@@ -501,14 +537,6 @@ export function createCorpusApi(
       };
     },
 
-    /**
-     * Freshness per SOURCE, assembled from the connections the tenant has.
-     *
-     * It reads the connections API rather than the documents, because "Dropbox
-     * has not synced since Tuesday" is a true and useful statement even when
-     * Dropbox has contributed zero documents — and a count derived from the
-     * corpus alone can never say it.
-     */
     /**
      * The tracking surface's read (bd startsim-768w.38.25).
      *
@@ -612,6 +640,41 @@ export function createCorpusApi(
       return durable as ExtractionRun;
     },
 
+    /**
+     * Freshness per SOURCE, assembled from the connections behind this workspace.
+     *
+     * It reads the connections API rather than the documents, because "Dropbox
+     * has not synced since Tuesday" is a true and useful statement even when
+     * Dropbox has contributed zero documents — and a count derived from the
+     * corpus alone can never say it.
+     *
+     * WHERE THE ROWS ACTUALLY COME FROM (bd startsim-bu04n), because the name of
+     * the default path invites the wrong guess. `api/v1/connections` on a tenant
+     * fork is NOT a tenant table: `tenant-starter`'s `ConnectionsView` forwards
+     * the caller's already-verified bearer to central's
+     * `/api/v1/subtree/connections/` and returns the page envelope untouched
+     * (bd startsim-768w.38.19). This read is a central read wearing a
+     * same-origin path, which is why every field below is central's.
+     *
+     * WHICH CONNECTIONS THAT SURFACE HANDS BACK is central's decision and not
+     * this adapter's. `SubtreeConnectionsView` resolves through
+     * `Connection.objects.for_scope(...)` — the foundry's SHARED rows — and a
+     * member's own vendor accounts join the page only when central unions
+     * `for_owner(orgs, request.user)` in, bounded to the requesting user. That
+     * bound is what keeps a colleague's personal connection off this strip
+     * (bd startsim-768w.22.25.11), and it is the reason this adapter must not
+     * reach for `/api/v1/connections/me/` to fill the gap itself: besides
+     * splitting the answer across two servers, that serializer carries
+     * `last_checked_at` and NONE of the other freshness facts, so every personal
+     * card built from it would report a verified credential as delivered data —
+     * exactly the lie bd startsim-1cow removed. Rows are read from one endpoint,
+     * as handed.
+     *
+     * `documentCount` is whatever the connections payload says and is therefore
+     * `0` today: no connections endpoint sends `document_count`, and a per-source
+     * count from the corpus needs the `?source=` filter bd startsim-768w.38.12
+     * is still open on. Tracked as bd startsim-o0o6o.1.
+     */
     async listSources(): Promise<SourceFreshness[]> {
       const [connectionPage, documentPage] = await Promise.all([
         http
@@ -625,7 +688,7 @@ export function createCorpusApi(
       void documentPage; // total count is per-source below; kept for the empty-corpus case
 
       const now = Date.now();
-      return (connectionPage.results ?? []).map((connection) => {
+      return (connectionPage.results ?? []).filter(isALiveSource).map((connection) => {
         const key = String(connection.connector_key ?? connection.connectorKey ?? 'unknown');
         // THREE FACTS, READ SEPARATELY (bd startsim-1cow). This was one `??`
         // chain ending in `last_checked_at`, and central's own view says of that