fix(installer): clearer pnpm/corepack errors + dev-aware --check

Review follow-ups on the --dev feature:
- Pin corepack to pnpm@10.6.2 (the repo packageManager) and surface
  corepack enable/prepare failures, with an actionable hard-fail when pnpm
  is still absent — the fresh-machine path no longer dies on a bare
  "command not found".
- `--check --dev` now reports the installed version instead of a
  misleading "Could not reach registry" warning (dev mode skips the
  registry lookup).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RMoEx7hfdFGjUiCHuN1RRi

apps/gateway/src/federation/client/__tests__/query-source.service.spec.ts

@@ -0,0 +1,255 @@
+import 'reflect-metadata';
+import { describe, expect, it, vi } from 'vitest';
+import type { Db } from '@mosaicstack/db';
+import type { FederationListResponse } from '@mosaicstack/types';
+import {
+  FederationClientError,
+  type FederationClientService,
+} from '../federation-client.service.js';
+import { type QuerySourceError, QuerySourceService } from '../query-source.service.js';
+
+interface TestRow {
+  id: string;
+  title: string;
+}
+
+interface PeerRow {
+  id: string;
+  commonName: string;
+  endpointUrl: string | null;
+  clientKeyPem: string | null;
+  state: 'active' | 'pending' | 'suspended' | 'revoked';
+}
+
+const LOCAL_ROWS: TestRow[] = [
+  { id: 'local-1', title: 'Local One' },
+  { id: 'local-2', title: 'Local Two' },
+];
+
+const PEER_A: PeerRow = {
+  id: 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa',
+  commonName: 'peer-a',
+  endpointUrl: 'https://peer-a.example.com',
+  clientKeyPem: 'sealed-key-a',
+  state: 'active',
+};
+
+const PEER_B: PeerRow = {
+  id: 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb',
+  commonName: 'peer-b',
+  endpointUrl: 'https://peer-b.example.com',
+  clientKeyPem: 'sealed-key-b',
+  state: 'active',
+};
+
+const PEER_LOCALHOST: PeerRow = {
+  id: 'cccccccc-cccc-cccc-cccc-cccccccccccc',
+  commonName: 'peer-localhost',
+  endpointUrl: 'https://localhost:3001',
+  clientKeyPem: 'sealed-key-c',
+  state: 'active',
+};
+
+function makeDb(activePeers: PeerRow[]): Db {
+  const orderBy = vi.fn().mockResolvedValue(activePeers);
+  const where = vi.fn().mockReturnValue({ orderBy });
+  const from = vi.fn().mockReturnValue({ where });
+  const select = vi.fn().mockReturnValue({ from });
+
+  return {
+    select,
+    insert: vi.fn(),
+    update: vi.fn(),
+    delete: vi.fn(),
+    transaction: vi.fn(),
+  } as unknown as Db;
+}
+
+function makeFederationClient(
+  list: (
+    peerId: string,
+    resource: string,
+    request: Record<string, unknown>,
+  ) => Promise<FederationListResponse<TestRow>>,
+): FederationClientService {
+  return {
+    list: list as unknown as FederationClientService['list'],
+  } as FederationClientService;
+}
+
+function makeLocalResponse(rows: TestRow[] = LOCAL_ROWS): Promise<FederationListResponse<TestRow>> {
+  return Promise.resolve({ items: rows });
+}
+
+describe('QuerySourceService', () => {
+  it('routes source="local" to the local executor and tags rows as local', async () => {
+    const list = vi.fn(async (): Promise<FederationListResponse<TestRow>> => ({ items: [] }));
+    const service = new QuerySourceService(makeDb([PEER_A]), makeFederationClient(list));
+
+    const result = await service.list<TestRow>({
+      source: 'local',
+      resource: 'tasks',
+      request: { cursor: 'ignored-for-local-test' },
+      local: () => makeLocalResponse(),
+    });
+
+    expect(result).toEqual({
+      items: [
+        { id: 'local-1', title: 'Local One', _source: 'local' },
+        { id: 'local-2', title: 'Local Two', _source: 'local' },
+      ],
+    });
+    expect(list).not.toHaveBeenCalled();
+  });
+
+  it('routes source="federated:<host>" to the matching active peer and tags rows with peer commonName', async () => {
+    const list = vi.fn(
+      async (): Promise<FederationListResponse<TestRow>> => ({
+        items: [{ id: 'remote-1', title: 'Remote One' }],
+      }),
+    );
+    const service = new QuerySourceService(makeDb([PEER_A, PEER_B]), makeFederationClient(list));
+
+    const result = await service.list<TestRow>({
+      source: 'federated:peer-b.example.com',
+      resource: 'tasks',
+      request: { status: 'open' },
+      local: () => makeLocalResponse(),
+    });
+
+    expect(result).toEqual({
+      items: [{ id: 'remote-1', title: 'Remote One', _source: 'peer-b' }],
+    });
+    expect(list).toHaveBeenCalledWith(PEER_B.id, 'tasks', { status: 'open' });
+  });
+
+  it('matches federated hosts by endpoint host including non-default port', async () => {
+    const list = vi.fn(
+      async (): Promise<FederationListResponse<TestRow>> => ({
+        items: [{ id: 'remote-port', title: 'Remote Port' }],
+      }),
+    );
+    const service = new QuerySourceService(makeDb([PEER_LOCALHOST]), makeFederationClient(list));
+
+    const result = await service.list<TestRow>({
+      source: 'federated:localhost:3001',
+      resource: 'tasks',
+      request: {},
+      local: () => makeLocalResponse(),
+    });
+
+    expect(result).toEqual({
+      items: [{ id: 'remote-port', title: 'Remote Port', _source: 'peer-localhost' }],
+    });
+    expect(list).toHaveBeenCalledWith(PEER_LOCALHOST.id, 'tasks', {});
+  });
+
+  it('fans out source="all" to local plus every active outbound peer in parallel and merges tagged rows', async () => {
+    const callOrder: string[] = [];
+    const list = vi.fn(async (peerId: string): Promise<FederationListResponse<TestRow>> => {
+      callOrder.push(`remote-start:${peerId}`);
+      await Promise.resolve();
+      return {
+        items: [{ id: `remote-${peerId.slice(0, 1)}`, title: `Remote ${peerId.slice(0, 1)}` }],
+      };
+    });
+    const service = new QuerySourceService(makeDb([PEER_A, PEER_B]), makeFederationClient(list));
+
+    const result = await service.list<TestRow>({
+      source: 'all',
+      resource: 'tasks',
+      request: { limit: 25 },
+      local: async () => {
+        callOrder.push('local-start');
+        await Promise.resolve();
+        return { items: [{ id: 'local-1', title: 'Local One' }] };
+      },
+    });
+
+    expect(result).toEqual({
+      items: [
+        { id: 'local-1', title: 'Local One', _source: 'local' },
+        { id: 'remote-a', title: 'Remote a', _source: 'peer-a' },
+        { id: 'remote-b', title: 'Remote b', _source: 'peer-b' },
+      ],
+    });
+    expect(list).toHaveBeenCalledTimes(2);
+    expect(callOrder).toEqual([
+      'local-start',
+      `remote-start:${PEER_A.id}`,
+      `remote-start:${PEER_B.id}`,
+    ]);
+  });
+
+  it('marks source="all" as partial and truncated when any subquery returns a cursor', async () => {
+    const list = vi.fn(
+      async (): Promise<FederationListResponse<TestRow>> => ({
+        items: [{ id: 'remote-a', title: 'Remote A' }],
+        nextCursor: 'remote-next',
+      }),
+    );
+    const service = new QuerySourceService(makeDb([PEER_A]), makeFederationClient(list));
+
+    const result = await service.list<TestRow>({
+      source: 'all',
+      resource: 'tasks',
+      request: {},
+      local: () => makeLocalResponse([{ id: 'local-1', title: 'Local One' }]),
+    });
+
+    expect(result).toEqual({
+      items: [
+        { id: 'local-1', title: 'Local One', _source: 'local' },
+        { id: 'remote-a', title: 'Remote A', _source: 'peer-a' },
+      ],
+      _partial: true,
+      _truncated: true,
+    });
+  });
+
+  it('returns _partial=true for source="all" when one peer fails without dropping successful sources', async () => {
+    const list = vi.fn(async (peerId: string): Promise<FederationListResponse<TestRow>> => {
+      if (peerId === PEER_B.id) {
+        throw new FederationClientError({
+          code: 'NETWORK',
+          message: 'peer unavailable',
+          peerId,
+        });
+      }
+      return { items: [{ id: 'remote-a', title: 'Remote A' }] };
+    });
+    const service = new QuerySourceService(makeDb([PEER_A, PEER_B]), makeFederationClient(list));
+
+    const result = await service.list<TestRow>({
+      source: 'all',
+      resource: 'tasks',
+      request: {},
+      local: () => makeLocalResponse([{ id: 'local-1', title: 'Local One' }]),
+    });
+
+    expect(result).toEqual({
+      items: [
+        { id: 'local-1', title: 'Local One', _source: 'local' },
+        { id: 'remote-a', title: 'Remote A', _source: 'peer-a' },
+      ],
+      _partial: true,
+    });
+  });
+
+  it('throws QuerySourceError when a federated host does not match an active outbound peer', async () => {
+    const list = vi.fn(async (): Promise<FederationListResponse<TestRow>> => ({ items: [] }));
+    const service = new QuerySourceService(makeDb([PEER_A]), makeFederationClient(list));
+
+    await expect(
+      service.list<TestRow>({
+        source: 'federated:missing.example.com',
+        resource: 'tasks',
+        request: {},
+        local: () => makeLocalResponse(),
+      }),
+    ).rejects.toMatchObject({
+      name: 'QuerySourceError',
+      code: 'PEER_NOT_FOUND',
+    } satisfies Partial<QuerySourceError>);
+  });
+});

apps/gateway/src/federation/client/index.ts

@@ -11,3 +11,13 @@ export {
   type FederationClientErrorCode,
   type FederationClientErrorOptions,
 } from './federation-client.service.js';
+export {
+  QuerySourceService,
+  QuerySourceError,
+  type QuerySource,
+  type QuerySourceErrorCode,
+  type QuerySourceErrorOptions,
+  type QuerySourceListOptions,
+  type QuerySourceListResponse,
+  type LocalListExecutor,
+} from './query-source.service.js';

apps/gateway/src/federation/client/query-source.service.ts

@@ -0,0 +1,261 @@
+/**
+ * QuerySourceService — gateway query source router (FED-M3-09).
+ *
+ * Accepts the federation query-layer `source` selector and routes list-style
+ * reads to local storage, one federated peer, or all active outbound peers.
+ *
+ * `source: "all"` is intentionally tolerant of per-peer failures: local data
+ * and successful peer responses are returned, and the envelope is marked
+ * `_partial: true`.  Local failures still reject because there is no safe local
+ * fallback and the gateway's own storage is expected to be authoritative.
+ */
+
+import { Inject, Injectable, Logger } from '@nestjs/common';
+import { and, eq, federationPeers, isNotNull, type Db } from '@mosaicstack/db';
+import {
+  SOURCE_LOCAL,
+  tagWithSource,
+  type FederationListResponse,
+  type SourceTag,
+} from '@mosaicstack/types';
+import { DB } from '../../database/database.module.js';
+import { FederationClientService } from './federation-client.service.js';
+
+export type QuerySource = 'local' | 'all' | `federated:${string}`;
+
+export type QuerySourceErrorCode = 'INVALID_SOURCE' | 'PEER_NOT_FOUND';
+
+export interface QuerySourceErrorOptions {
+  code: QuerySourceErrorCode;
+  message: string;
+  source: string;
+}
+
+export class QuerySourceError extends Error {
+  readonly code: QuerySourceErrorCode;
+  readonly source: string;
+
+  constructor(opts: QuerySourceErrorOptions) {
+    super(opts.message);
+    this.name = 'QuerySourceError';
+    this.code = opts.code;
+    this.source = opts.source;
+  }
+}
+
+export type LocalListExecutor<T extends object> = () => Promise<FederationListResponse<T> | T[]>;
+
+export interface QuerySourceListOptions<T extends object> {
+  source: QuerySource;
+  resource: string;
+  request?: Record<string, unknown>;
+  local: LocalListExecutor<T>;
+}
+
+export type QuerySourceListResponse<T extends object> = FederationListResponse<T & SourceTag>;
+
+interface OutboundPeer {
+  id: string;
+  commonName: string;
+  endpointUrl: string;
+}
+
+interface TaggedList<T extends object> {
+  items: Array<T & SourceTag>;
+  partial: boolean;
+  truncated: boolean;
+  nextCursor?: string;
+}
+
+@Injectable()
+export class QuerySourceService {
+  private readonly logger = new Logger(QuerySourceService.name);
+
+  constructor(
+    @Inject(DB) private readonly db: Db,
+    @Inject(FederationClientService) private readonly federationClient: FederationClientService,
+  ) {}
+
+  async list<T extends object>(
+    options: QuerySourceListOptions<T>,
+  ): Promise<QuerySourceListResponse<T>> {
+    const request = options.request ?? {};
+
+    if (options.source === 'local') {
+      const local = await this.runLocal(options.local);
+      return this.toResponse(this.tagList(local, SOURCE_LOCAL));
+    }
+
+    if (options.source === 'all') {
+      return this.listAll(options.resource, request, options.local);
+    }
+
+    if (options.source.startsWith('federated:')) {
+      const host = options.source.slice('federated:'.length).trim();
+      if (!host) {
+        throw new QuerySourceError({
+          code: 'INVALID_SOURCE',
+          message: 'Federated source must include a host after federated:',
+          source: options.source,
+        });
+      }
+
+      const peer = await this.findPeerByHost(host, options.source);
+      const remote = await this.federationClient.list<T>(peer.id, options.resource, request);
+      return this.toResponse(this.tagList(remote, peer.commonName));
+    }
+
+    throw new QuerySourceError({
+      code: 'INVALID_SOURCE',
+      message: `Unsupported query source: ${options.source}`,
+      source: options.source,
+    });
+  }
+
+  private async listAll<T extends object>(
+    resource: string,
+    request: Record<string, unknown>,
+    local: LocalListExecutor<T>,
+  ): Promise<QuerySourceListResponse<T>> {
+    const peers = await this.listActiveOutboundPeers();
+
+    const localPromise = this.runLocal(local).then((response) =>
+      this.tagList(response, SOURCE_LOCAL),
+    );
+    const remotePromises = peers.map(async (peer: OutboundPeer): Promise<TaggedList<T> | null> => {
+      try {
+        const response = await this.federationClient.list<T>(peer.id, resource, request);
+        return this.tagList(response, peer.commonName);
+      } catch (error: unknown) {
+        this.logger.warn(
+          `Federated query to peer ${peer.commonName} (${peer.id}) failed; returning partial all-source response: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        );
+        return null;
+      }
+    });
+
+    const [localResult, ...remoteResults] = await Promise.all([localPromise, ...remotePromises]);
+    const successfulRemoteResults = remoteResults.filter(
+      (result: TaggedList<T> | null): result is TaggedList<T> => result !== null,
+    );
+    const allResults = [localResult, ...successfulRemoteResults];
+    const peerFailure = successfulRemoteResults.length !== peers.length;
+
+    return this.mergeTaggedLists(allResults, peerFailure);
+  }
+
+  private async runLocal<T extends object>(
+    local: LocalListExecutor<T>,
+  ): Promise<FederationListResponse<T>> {
+    const response = await local();
+    if (Array.isArray(response)) {
+      return { items: response };
+    }
+    return response;
+  }
+
+  private tagList<T extends object>(
+    response: FederationListResponse<T>,
+    source: string,
+  ): TaggedList<T> {
+    return {
+      items: tagWithSource(response.items, source),
+      partial: response._partial === true,
+      truncated: response._truncated === true || response.nextCursor !== undefined,
+      nextCursor: response.nextCursor,
+    };
+  }
+
+  private mergeTaggedLists<T extends object>(
+    lists: Array<TaggedList<T>>,
+    peerFailure: boolean,
+  ): QuerySourceListResponse<T> {
+    const items = lists.flatMap((list: TaggedList<T>) => list.items);
+    const partial =
+      peerFailure ||
+      lists.some((list: TaggedList<T>) => list.partial || list.nextCursor !== undefined);
+    const truncated = lists.some((list: TaggedList<T>) => list.truncated);
+
+    const response: QuerySourceListResponse<T> = { items };
+    if (partial) {
+      response._partial = true;
+    }
+    if (truncated) {
+      response._truncated = true;
+    }
+    return response;
+  }
+
+  private toResponse<T extends object>(tagged: TaggedList<T>): QuerySourceListResponse<T> {
+    const response: QuerySourceListResponse<T> = {
+      items: tagged.items,
+    };
+    if (tagged.nextCursor !== undefined) {
+      response.nextCursor = tagged.nextCursor;
+    }
+    if (tagged.partial) {
+      response._partial = true;
+    }
+    if (tagged.truncated) {
+      response._truncated = true;
+    }
+    return response;
+  }
+
+  private async findPeerByHost(sourceHost: string, source: string): Promise<OutboundPeer> {
+    const host = normalizeHost(sourceHost);
+    const peers = await this.listActiveOutboundPeers();
+    const peer = peers.find((candidate: OutboundPeer) => {
+      const commonName = normalizeHost(candidate.commonName);
+      const endpointHosts = endpointHostKeys(candidate.endpointUrl).map((endpointHost: string) =>
+        normalizeHost(endpointHost),
+      );
+      return commonName === host || endpointHosts.includes(host);
+    });
+
+    if (!peer) {
+      throw new QuerySourceError({
+        code: 'PEER_NOT_FOUND',
+        message: `No active outbound federation peer matches source ${source}`,
+        source,
+      });
+    }
+
+    return peer;
+  }
+
+  private async listActiveOutboundPeers(): Promise<OutboundPeer[]> {
+    const rows = await this.db
+      .select({
+        id: federationPeers.id,
+        commonName: federationPeers.commonName,
+        endpointUrl: federationPeers.endpointUrl,
+      })
+      .from(federationPeers)
+      .where(
+        and(
+          eq(federationPeers.state, 'active'),
+          isNotNull(federationPeers.endpointUrl),
+          isNotNull(federationPeers.clientKeyPem),
+        ),
+      )
+      .orderBy(federationPeers.commonName);
+
+    return rows.filter((row): row is OutboundPeer => typeof row.endpointUrl === 'string');
+  }
+}
+
+function normalizeHost(host: string): string {
+  return host.trim().toLowerCase();
+}
+
+function endpointHostKeys(endpointUrl: string): string[] {
+  try {
+    const url = new URL(endpointUrl);
+    return Array.from(new Set([url.host, url.hostname].filter((host: string) => host.length > 0)));
+  } catch {
+    return [];
+  }
+}

apps/gateway/src/federation/federation.module.ts

@@ -6,7 +6,7 @@ import { EnrollmentService } from './enrollment.service.js';
 import { FederationController } from './federation.controller.js';
 import { CapabilitiesController } from './server/verbs/capabilities.controller.js';
 import { GrantsService } from './grants.service.js';
-import { FederationClientService } from './client/index.js';
+import { FederationClientService, QuerySourceService } from './client/index.js';
 import { FederationAuthGuard } from './server/index.js';
 
 @Module({
@@ -17,6 +17,7 @@ import { FederationAuthGuard } from './server/index.js';
     EnrollmentService,
     GrantsService,
     FederationClientService,
+    QuerySourceService,
     FederationAuthGuard,
   ],
   exports: [
@@ -24,6 +25,7 @@ import { FederationAuthGuard } from './server/index.js';
     EnrollmentService,
     GrantsService,
     FederationClientService,
+    QuerySourceService,
     FederationAuthGuard,
   ],
 })

docs/federation/TASKS.md

@@ -91,22 +91,22 @@ Goal: Two federated gateways exchange real data over mTLS. Inbound requests pass
 >
 > **Tracking issue:** #462.
 
-| id        | status      | description                                                                                                                                                                                                                                                                                            | issue | agent  | branch                               | depends_on       | estimate | notes                                                                                                                                                    |
-| --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | ------ | ------------------------------------ | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| FED-M3-01 | done        | `packages/types/src/federation/` — request/response DTOs for `list`, `get`, `capabilities` verbs. Wire-format zod schemas + inferred TS types. Includes `FederationRequest`, `FederationListResponse<T>`, `FederationGetResponse<T>`, `FederationCapabilitiesResponse`, error envelope, `_source` tag. | #462  | sonnet | feat/federation-m3-types             | —                | 4K       | Reusable from gateway server + client + harness. Pure types — no I/O, no NestJS.                                                                         |
-| FED-M3-02 | done        | `tools/federation-harness/` scaffold: `docker-compose.two-gateways.yml` (Server A + Server B + step-CA), `seed.ts` (provisions grants, peers, sample tasks/notes/credentials per scope variant), `harness.ts` helper (boots stack, returns typed clients). README documents harness use.               | #462  | sonnet | feat/federation-m3-harness           | DEPLOY-04 (soft) | 8K       | Falls back to local docker-compose if `mos-test-1/-2` not yet redeployed (DEPLOY chain blocked on IMG-FIX). Permanent test infra used by M3+.            |
-| FED-M3-03 | done        | `apps/gateway/src/federation/server/federation-auth.guard.ts` (NestJS guard). Validates inbound client cert from Fastify TLS context, extracts `grantId` + `subjectUserId` from custom OIDs, loads grant from DB, asserts `status='active'`, attaches `FederationContext` to request.                  | #462  | sonnet | feat/federation-m3-auth-guard        | M3-01            | 8K       | Reuses OID parsing logic mirrored from `ca.service.ts` post-issuance verification. 401 on malformed/missing OIDs; 403 on revoked/expired/missing grant.  |
-| FED-M3-04 | in-progress | `apps/gateway/src/federation/server/scope.service.ts`. Pipeline: (1) resource allowlist + excluded check, (2) native RBAC eval as `subjectUserId`, (3) scope filter intersection (`include_teams`, `include_personal`), (4) `max_rows_per_query` cap. Pure service — DB calls injected.                | #462  | sonnet | feat/federation-m3-scope-service     | M3-01            | 10K      | Hardest correctness target in M3. Reuses `parseFederationScope` (M2-03). Returns either `{ allowed: true, filter }` or structured deny reason for audit. |
-| FED-M3-05 | not-started | `apps/gateway/src/federation/server/verbs/list.controller.ts`. Wires AuthGuard → ScopeService → tasks/notes/memory query layer; applies row cap; tags rows with `_source`. Resource selector via path param.                                                                                           | #462  | sonnet | feat/federation-m3-verb-list         | M3-03, M3-04     | 6K       | Routes: `POST /api/federation/v1/list/:resource`. No body persistence. Audit write deferred to M4.                                                       |
-| FED-M3-06 | not-started | `apps/gateway/src/federation/server/verbs/get.controller.ts`. Single-resource fetch by id; same pipeline as list. 404 on not-found, 403 on RBAC/scope deny — both audited the same way.                                                                                                                | #462  | sonnet | feat/federation-m3-verb-get          | M3-03, M3-04     | 6K       | `POST /api/federation/v1/get/:resource/:id`. Mirrors list controller patterns.                                                                           |
-| FED-M3-07 | in-progress | `apps/gateway/src/federation/server/verbs/capabilities.controller.ts`. Read-only enumeration: returns `{ resources, excluded_resources, max_rows_per_query, supported_verbs }` derived from grant scope. Always allowed for an active grant — no RBAC eval.                                            | #462  | sonnet | feat/federation-m3-verb-capabilities | M3-03            | 4K       | `GET /api/federation/v1/capabilities`. Smallest verb; useful sanity check that mTLS + auth guard work end-to-end.                                        |
-| FED-M3-08 | done        | `apps/gateway/src/federation/client/federation-client.service.ts`. Outbound mTLS dialer: picks `(certPem, sealed clientKey)` from `federation_peers`, unwraps key, builds undici Agent with mTLS, calls peer verb, parses typed response, wraps non-2xx into `FederationClientError`.                  | #462  | sonnet | feat/federation-m3-client            | M3-01            | 8K       | Independent of server stream — can land in parallel with M3-03/04. Cert/key cached per-peer; flushed by future M5/M6 logic.                              |
-| FED-M3-09 | in-progress | `apps/gateway/src/federation/client/query-source.service.ts`. Accepts `source: "local" \| "federated:<host>" \| "all"` from gateway query layer; for `"all"` fans out to local + each peer in parallel; merges results; tags every row with `_source`.                                                 | #462  | sonnet | feat/federation-m3-query-source      | M3-08            | 8K       | Per-peer failure surfaces as `_partial: true` in response, not hard failure (sets up M5 offline UX). M5 adds caching + circuit breaker on top.           |
-| FED-M3-10 | not-started | Integration tests for MILESTONES.md M3 acceptance #6 (malformed OIDs → 401; valid cert + revoked grant → 403) and #7 (`max_rows_per_query` cap). Real PG, mocked TLS context (Fastify req shim).                                                                                                       | #462  | sonnet | feat/federation-m3-integration       | M3-05, M3-06     | 8K       | Vitest profile gated by `FEDERATED_INTEGRATION=1`. Single-gateway suite; no harness required.                                                            |
-| FED-M3-11 | not-started | E2E tests for MILESTONES.md M3 acceptance #1, #2, #3, #4, #5, #8, #9, #10 (8 cases). Uses harness from M3-02; two real gateways, real Step-CA, real mTLS. Each test asserts both happy-path response and audit/no-persist invariants.                                                                  | #462  | sonnet | feat/federation-m3-e2e               | M3-02, M3-09     | 12K      | Largest single task. Each acceptance gets its own `it(...)` for clear failure attribution.                                                               |
-| FED-M3-12 | not-started | Independent security review (sonnet, not author of M3-03/04/05/06/07/08/09): focus on cert-SAN spoofing, OID extraction edge cases, scope-bypass via filter manipulation, RBAC-bypass via subjectUser swap, response leakage when scope deny.                                                          | #462  | sonnet | feat/federation-m3-security-review   | M3-11            | 10K      | Two review rounds budgeted. PRD requires explicit test for every 401/403 path — review verifies coverage.                                                |
-| FED-M3-13 | not-started | Docs update: `docs/federation/SETUP.md` mTLS handshake section, new `docs/federation/HARNESS.md` for federation-harness usage, OID reference table in SETUP.md, scope enforcement pipeline diagram. Runbook still M7-deferred.                                                                         | #462  | haiku  | feat/federation-m3-docs              | M3-12            | 5K       | One ASCII diagram for the auth-guard → scope → RBAC pipeline; helps future reviewers reason about denial paths.                                          |
-| FED-M3-14 | not-started | PR aggregate close, CI green, merge to main, close #462. Release tag `fed-v0.3.0-m3`. Update mission manifest M3 row → done; M4 row → in-progress when work begins.                                                                                                                                    | #462  | sonnet | chore/federation-m3-close            | M3-13            | 3K       | Same close pattern as M1-12 / M2-13.                                                                                                                     |
+| id        | status      | description                                                                                                                                                                                                                                                                                            | issue | agent  | branch                               | depends_on                        | estimate | notes                                                                                                                                                    |
+| --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | ------ | ------------------------------------ | --------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| FED-M3-01 | done        | `packages/types/src/federation/` — request/response DTOs for `list`, `get`, `capabilities` verbs. Wire-format zod schemas + inferred TS types. Includes `FederationRequest`, `FederationListResponse<T>`, `FederationGetResponse<T>`, `FederationCapabilitiesResponse`, error envelope, `_source` tag. | #462  | sonnet | feat/federation-m3-types             | —                                 | 4K       | Reusable from gateway server + client + harness. Pure types — no I/O, no NestJS.                                                                         |
+| FED-M3-02 | done        | `tools/federation-harness/` scaffold: `docker-compose.two-gateways.yml` (Server A + Server B + step-CA), `seed.ts` (provisions grants, peers, sample tasks/notes/credentials per scope variant), `harness.ts` helper (boots stack, returns typed clients). README documents harness use.               | #462  | sonnet | feat/federation-m3-harness           | DEPLOY-04 (soft)                  | 8K       | Falls back to local docker-compose if `mos-test-1/-2` not yet redeployed (DEPLOY chain blocked on IMG-FIX). Permanent test infra used by M3+.            |
+| FED-M3-03 | done        | `apps/gateway/src/federation/server/federation-auth.guard.ts` (NestJS guard). Validates inbound client cert from Fastify TLS context, extracts `grantId` + `subjectUserId` from custom OIDs, loads grant from DB, asserts `status='active'`, attaches `FederationContext` to request.                  | #462  | sonnet | feat/federation-m3-auth-guard        | M3-01                             | 8K       | Reuses OID parsing logic mirrored from `ca.service.ts` post-issuance verification. 401 on malformed/missing OIDs; 403 on revoked/expired/missing grant.  |
+| FED-M3-04 | in-progress | `apps/gateway/src/federation/server/scope.service.ts`. Pipeline: (1) resource allowlist + excluded check, (2) native RBAC eval as `subjectUserId`, (3) scope filter intersection (`include_teams`, `include_personal`), (4) `max_rows_per_query` cap. Pure service — DB calls injected.                | #462  | sonnet | feat/federation-m3-scope-service     | M3-01                             | 10K      | Hardest correctness target in M3. Reuses `parseFederationScope` (M2-03). Returns either `{ allowed: true, filter }` or structured deny reason for audit. |
+| FED-M3-05 | in-progress | `apps/gateway/src/federation/server/verbs/list.controller.ts`. Wires AuthGuard → ScopeService → tasks/notes/memory query layer; applies row cap; tags rows with `_source`. Resource selector via path param.                                                                                           | #462  | sonnet | feat/federation-m3-verb-list         | M3-03, M3-04                      | 6K       | Routes: `POST /api/federation/v1/list/:resource`. No body persistence. Audit write deferred to M4.                                                       |
+| FED-M3-06 | not-started | `apps/gateway/src/federation/server/verbs/get.controller.ts`. Single-resource fetch by id; same pipeline as list. 404 on not-found, 403 on RBAC/scope deny — both audited the same way.                                                                                                                | #462  | sonnet | feat/federation-m3-verb-get          | M3-03, M3-04                      | 6K       | `POST /api/federation/v1/get/:resource/:id`. Mirrors list controller patterns.                                                                           |
+| FED-M3-07 | done        | `apps/gateway/src/federation/server/verbs/capabilities.controller.ts`. Read-only enumeration: returns `{ resources, excluded_resources, max_rows_per_query, supported_verbs }` derived from grant scope. Always allowed for an active grant — no RBAC eval.                                            | #462  | sonnet | feat/federation-m3-verb-capabilities | M3-03                             | 4K       | `GET /api/federation/v1/capabilities`. Smallest verb; useful sanity check that mTLS + auth guard work end-to-end.                                        |
+| FED-M3-08 | done        | `apps/gateway/src/federation/client/federation-client.service.ts`. Outbound mTLS dialer: picks `(certPem, sealed clientKey)` from `federation_peers`, unwraps key, builds undici Agent with mTLS, calls peer verb, parses typed response, wraps non-2xx into `FederationClientError`.                  | #462  | sonnet | feat/federation-m3-client            | M3-01                             | 8K       | Independent of server stream — can land in parallel with M3-03/04. Cert/key cached per-peer; flushed by future M5/M6 logic.                              |
+| FED-M3-09 | done        | `apps/gateway/src/federation/client/query-source.service.ts`. Accepts `source: "local" \| "federated:<host>" \| "all"` from gateway query layer; for `"all"` fans out to local + each peer in parallel; merges results; tags every row with `_source`.                                                 | #462  | sonnet | feat/federation-m3-query-source      | M3-08                             | 8K       | Per-peer failure surfaces as `_partial: true` in response, not hard failure (sets up M5 offline UX). M5 adds caching + circuit breaker on top.           |
+| FED-M3-10 | not-started | Integration tests for MILESTONES.md M3 acceptance #6 (malformed OIDs → 401; valid cert + revoked grant → 403) and #7 (`max_rows_per_query` cap). Real PG, mocked TLS context (Fastify req shim).                                                                                                       | #462  | sonnet | feat/federation-m3-integration       | M3-05, M3-06                      | 8K       | Vitest profile gated by `FEDERATED_INTEGRATION=1`. Single-gateway suite; no harness required.                                                            |
+| FED-M3-11 | not-started | E2E tests for MILESTONES.md M3 acceptance #1, #2, #3, #4, #5, #8, #9, #10 (8 cases). Uses harness from M3-02; two real gateways, real Step-CA, real mTLS. Each test asserts both happy-path response and audit/no-persist invariants.                                                                  | #462  | sonnet | feat/federation-m3-e2e               | M3-02, M3-04, M3-05, M3-06, M3-09 | 12K      | Largest single task. Each acceptance gets its own `it(...)` for clear failure attribution.                                                               |
+| FED-M3-12 | not-started | Independent security review (sonnet, not author of M3-03/04/05/06/07/08/09): focus on cert-SAN spoofing, OID extraction edge cases, scope-bypass via filter manipulation, RBAC-bypass via subjectUser swap, response leakage when scope deny.                                                          | #462  | sonnet | feat/federation-m3-security-review   | M3-11                             | 10K      | Two review rounds budgeted. PRD requires explicit test for every 401/403 path — review verifies coverage.                                                |
+| FED-M3-13 | not-started | Docs update: `docs/federation/SETUP.md` mTLS handshake section, new `docs/federation/HARNESS.md` for federation-harness usage, OID reference table in SETUP.md, scope enforcement pipeline diagram. Runbook still M7-deferred.                                                                         | #462  | haiku  | feat/federation-m3-docs              | M3-12                             | 5K       | One ASCII diagram for the auth-guard → scope → RBAC pipeline; helps future reviewers reason about denial paths.                                          |
+| FED-M3-14 | not-started | PR aggregate close, CI green, merge to main, close #462. Release tag `fed-v0.3.0-m3`. Update mission manifest M3 row → done; M4 row → in-progress when work begins.                                                                                                                                    | #462  | sonnet | chore/federation-m3-close            | M3-13                             | 3K       | Same close pattern as M1-12 / M2-13.                                                                                                                     |
 
 **M3 estimate:** ~100K tokens (vs MILESTONES.md 40K — same per-task breakdown pattern as M1/M2: tests, review, and docs split out from implementation cost). Largest milestone in the federation mission.
 
@@ -120,6 +120,8 @@ Goal: Two federated gateways exchange real data over mTLS. Inbound requests pass
 
 **Backlog sync — 2026-06-24 (orchestrator):** Status reconciled against `origin/main` (release 0.0.48). Landed on main: **FED-M3-01** (DTOs, PR #506), **FED-M3-02** (harness scaffold, PR #505), **FED-M3-03** (mTLS auth-guard, PR #509 — CRIT-1/2 + HIGH-1..4 remediated in-PR), **FED-M3-08** (outbound mTLS client, PR #508). With M3-01/03/08 merged, three cards became dependency-clear and were dispatched to the idle coder lane: **FED-M3-04** scope.service → coder0 (`feat/federation-m3-scope-service`); **FED-M3-09** query-source + **FED-M3-07** capabilities verb → coder1 (`feat/federation-m3-query-source` first). Reviewer warmed for the M3 trust-boundary PRs. Remaining blocked-by-DAG: M3-05/06 (await M3-04), M3-10 (await M3-05/06), M3-11 (await M3-09), M3-12→14 (tail). Deploy chain (DEPLOY-IMG-FIX → 03/04) still independent of M3 code — harness local docker-compose fallback covers M3-11.
 
+**Backlog sync #2 — 2026-06-24 (orchestrator):** **FED-M3-09** (query-source) merged via PR #673 and **FED-M3-07** (capabilities) merged via PR #674 — both squash-merged on independent agent review-of-record + green CI (formal Gitea approve unavailable under the shared service account; merge is not gated by the self-approve guard). **FED-M3-05** (list verb) dispatched to coder1 (based on the M3-04 branch, rebase onto main once #672 lands). **FED-M3-04** (scope.service, PR #672) is in review-changes (one include_personal no-leak test outstanding). **DAG fix:** corrected `FED-M3-11` depends_on from `M3-02, M3-09` → `M3-02, M3-04, M3-05, M3-06, M3-09` — the E2E acceptance cases (#1–#5, #8–#10) exercise list/get over mTLS, so the server verbs + scope service are hard prerequisites; the original edge set omitted them and caused a premature M3-11 dispatch. Note: M3 read-path invariant for M3-11 is **no-persist + existing enrollment audit only** — read-verb audit-log writes are deferred to M4 (see M3-05/06 notes), so M3-11 must not assert read-audit-log entries.
+
 ## Milestone 4 — search + audit + rate limit (FED-M4)
 
 _Deferred. Issue #463._

docs/scratchpads/672-fleet-personas-timeout.md

@@ -0,0 +1,25 @@
+# Scratchpad — fleet-personas spec timeout
+
+## Objective
+
+Raise the `@mosaicstack/mosaic` Vitest timeout to 30s at config level so filesystem-backed fleet drift-guard specs (`fleet-personas`, `fleet-profiles`, and siblings) stop false-reding under contended CI.
+
+## Plan
+
+1. Move timeout policy into `packages/mosaic/vitest.config.ts` with `testTimeout: 30_000`.
+2. Remove the narrower `fleet-personas.spec.ts` local override so PR #677 fixes the suite class, not one file.
+3. Run targeted fleet specs plus typecheck/lint/format gates.
+4. Commit, queue guard, push, PR update.
+
+## Evidence
+
+- `pnpm --filter @mosaicstack/mosaic test -- src/commands/fleet-personas.spec.ts` — pass (8 tests; initial narrow fix).
+- `pnpm typecheck` — pass (41 tasks; initial narrow fix).
+- `pnpm lint` — pass (23 tasks; initial narrow fix).
+- `pnpm format:check` — pass after formatting this scratchpad (initial narrow fix).
+- Package-wide timeout follow-up:
+  - `pnpm --filter @mosaicstack/mosaic test -- src/commands/fleet-personas.spec.ts src/commands/fleet-profiles.spec.ts` — pass (24 tests).
+  - `pnpm --filter @mosaicstack/mosaic test` — pass (44 files / 618 tests).
+  - `pnpm typecheck` — pass (41 tasks).
+  - `pnpm lint` — pass (23 tasks).
+  - `pnpm format:check` — pass.

docs/scratchpads/FED-M3-09-query-source.md

@@ -0,0 +1,67 @@
+# FED-M3-09 — Query Source Service Scratchpad
+
+## Objective
+
+Implement `apps/gateway/src/federation/client/query-source.service.ts` for `source: "local" | "federated:<host>" | "all"` routing.
+
+## Scope
+
+- Add QuerySourceService in gateway federation client layer.
+- Unit-test local-only, single federated peer, all-source fan-out/merge, and per-peer partial failures.
+- Keep `docs/federation/TASKS.md` read-only per project agent guidance.
+
+## Constraints / assumptions
+
+- Issue: #462.
+- Branch: `feat/federation-m3-query-source` from `origin/main` (`e0e7be70`).
+- ASSUMPTION: `federated:<host>` should match active outbound peers by `commonName` first and by `endpointUrl` host/hostname as compatibility fallback; source tags use `peer.commonName` per `@mosaicstack/types` source-tag docs.
+- ASSUMPTION: QuerySourceService provides list/fan-out behavior; get/source routing can be layered later because card acceptance says merge rows.
+- ASSUMPTION: `source: "all"` cannot safely return a single continuation cursor for multiple sub-sources; any subquery cursor marks the merged response `_partial: true` + `_truncated: true` while omitting `nextCursor`.
+- Budget: no explicit hard cap from orchestrator; working cap ~8K-12K tokens for card 1 implementation + tests + PR cycle.
+- OpenBrain unavailable: credential loader failed with missing `/home/jarvis/.config/mosaic/credentials.json`; not blocking code delivery.
+
+## Plan
+
+1. Review federation client/types/db patterns.
+2. Write unit tests for source behavior.
+3. Implement QuerySourceService and export/register it in FederationModule.
+4. Run scoped tests, typecheck, lint, format.
+5. Run codex uncommitted review and remediate.
+6. Commit, queue guard, push, PR via wrapper.
+
+## Progress
+
+- 2026-06-24: Intake complete; using isolated worktree to avoid dirty orchestrator files in original checkout.
+- 2026-06-24: Added QuerySourceService, module export, barrel export, and 7 unit tests.
+- 2026-06-24: First Codex review found pagination and port-host matching issues; both remediated with tests.
+
+## Tests run
+
+- `pnpm --filter @mosaicstack/gateway test -- query-source.service.spec.ts` — PASS (7 tests).
+- `pnpm --filter @mosaicstack/gateway typecheck` — PASS.
+- `pnpm --filter @mosaicstack/gateway lint` — PASS.
+- `pnpm format:check` — PASS.
+- `pnpm typecheck` — PASS (41/41 turbo tasks).
+- `pnpm lint` — PASS (23/23 turbo tasks).
+- `pnpm test` — FAIL in pre-existing/live-DB integration suite: `apps/gateway/src/__tests__/cross-user-isolation.test.ts` cleanup hit `relation "messages" does not exist` against local PostgreSQL. Changed QuerySource unit tests passed; failure is outside FED-M3-09 surface and appears tied to local DB schema state.
+
+## Review evidence
+
+- `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted` — first pass request-changes, 2 should-fix findings (all-source cursor handling; endpoint port host matching).
+- Remediation: `_partial` + `_truncated` when any all-source subquery has `nextCursor`; endpoint match accepts URL `host` and `hostname`; added tests for both.
+- `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted` — PASS/approve, no findings.
+- `~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted` — PASS, risk level none, no findings.
+
+## Risks / blockers
+
+- Federation query layer is not yet wired; service API needs to be stable and easy to compose.
+- Must avoid hard-failing `source: all` on remote peer failures.
+
+## Acceptance evidence mapping
+
+| Acceptance criterion                                                            | Evidence                                                                          |
+| ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| local source returns local rows tagged `_source: local`                         | `query-source.service.spec.ts` local test; scoped test PASS                       |
+| `federated:<host>` queries selected peer and tags rows with peer source         | `query-source.service.spec.ts` commonName/endpoint-host tests; scoped test PASS   |
+| `all` fans out local + active outbound peers in parallel and merges tagged rows | `query-source.service.spec.ts` all-source call-order/merge test; scoped test PASS |
+| per-peer failure on `all` returns `_partial: true`, not throw                   | `query-source.service.spec.ts` peer failure test; scoped test PASS                |

eslint.config.mjs

@@ -30,6 +30,7 @@ export default tseslint.config(
             'apps/gateway/vitest.config.ts',
             'packages/db/vitest.config.ts',
             'packages/storage/vitest.config.ts',
+            'packages/mosaic/vitest.config.ts',
             'packages/mosaic/__tests__/*.ts',
             'tools/federation-harness/*.ts',
           ],

packages/mosaic/vitest.config.ts

@@ -4,5 +4,6 @@ export default defineConfig({
   test: {
     globals: true,
     environment: 'node',
+    testTimeout: 30_000,
   },
 });

tools/install.sh

@@ -16,6 +16,10 @@
 #   --framework       Install/upgrade framework only (skip npm CLI)
 #   --cli             Install/upgrade npm CLI only (skip framework)
 #   --ref <branch>    Git ref for framework archive (default: main)
+#   --dev             Build CLI + gateway FROM SOURCE at --ref instead of the
+#                     registry @latest. Zero registry writes — packs local
+#                     tarballs and installs them globally. Use to test a branch
+#                     end-to-end before cutting a release.
 #   --yes             Accept all defaults; headless/non-interactive install
 #   --no-auto-launch  Skip automatic mosaic wizard + gateway install on first install
 #   --uninstall       Reverse the install: remove framework dir, CLI package, and npmrc line
@@ -27,6 +31,7 @@
 #   MOSAIC_PREFIX       — npm global prefix          (default: ~/.npm-global)
 #   MOSAIC_NO_COLOR     — disable colour             (set to 1)
 #   MOSAIC_REF          — git ref for framework      (default: main)
+#   MOSAIC_DEV          — equivalent to --dev         (set to 1)
 #   MOSAIC_ASSUME_YES   — equivalent to --yes        (set to 1)
 # ──────────────────────────────────────────────────────────────────────────────
 #
@@ -43,6 +48,7 @@ FLAG_CLI=true
 FLAG_NO_AUTO_LAUNCH=false
 FLAG_YES=false
 FLAG_UNINSTALL=false
+FLAG_DEV=false
 GIT_REF="${MOSAIC_REF:-main}"
 
 # MOSAIC_ASSUME_YES env var acts the same as --yes
@@ -50,12 +56,18 @@ if [[ "${MOSAIC_ASSUME_YES:-0}" == "1" ]]; then
   FLAG_YES=true
 fi
 
+# MOSAIC_DEV env var acts the same as --dev
+if [[ "${MOSAIC_DEV:-0}" == "1" ]]; then
+  FLAG_DEV=true
+fi
+
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --check)          FLAG_CHECK=true; shift ;;
     --framework)      FLAG_CLI=false; shift ;;
     --cli)            FLAG_FRAMEWORK=false; shift ;;
     --ref)            GIT_REF="${2:-main}"; shift 2 ;;
+    --dev)            FLAG_DEV=true; shift ;;
     --yes|-y)         FLAG_YES=true; shift ;;
     --no-auto-launch) FLAG_NO_AUTO_LAUNCH=true; shift ;;
     --uninstall)      FLAG_UNINSTALL=true; shift ;;
@@ -72,6 +84,17 @@ CLI_PKG="${SCOPE}/mosaic"
 REPO_BASE="https://git.mosaicstack.dev/mosaicstack/stack"
 ARCHIVE_URL="${REPO_BASE}/archive/${GIT_REF}.tar.gz"
 
+# In dev (build-from-source) mode the gateway is installed globally from a
+# locally-built tarball. Tell the wizard / gateway-config stage NOT to overwrite
+# it with the registry @latest build (honored by gatewayConfigStage).
+if [[ "$FLAG_DEV" == "true" ]]; then
+  export MOSAIC_GATEWAY_SKIP_NPM_INSTALL=1
+fi
+
+# Shared monorepo checkout (populated on demand by ensure_monorepo).
+WORK_DIR=""
+EXTRACTED_DIR=""
+
 # ─── uninstall path ───────────────────────────────────────────────────────────
 # Shell-level uninstall for when the CLI is broken or not available.
 # Handles: framework directory, npm CLI package, npmrc scope line.
@@ -239,6 +262,99 @@ framework_version() {
   fi
 }
 
+# Download + extract the monorepo archive at $GIT_REF exactly once per run.
+# Sets the script-level EXTRACTED_DIR to the repo root. Reused by both the
+# framework install (Part 1) and the dev build-from-source path (Part 2).
+ensure_monorepo() {
+  if [[ -n "$EXTRACTED_DIR" ]] && [[ -d "$EXTRACTED_DIR" ]]; then
+    return 0
+  fi
+
+  require_cmd tar
+
+  WORK_DIR="$(mktemp -d "${TMPDIR:-/tmp}/mosaic-install-XXXXXX")"
+  # shellcheck disable=SC2317
+  cleanup_work() { [[ -n "$WORK_DIR" ]] && rm -rf "$WORK_DIR"; }
+  trap cleanup_work EXIT
+
+  info "Downloading source from ${GIT_REF}…"
+  if command -v curl &>/dev/null; then
+    curl -fsSL "$ARCHIVE_URL" | tar xz -C "$WORK_DIR"
+  elif command -v wget &>/dev/null; then
+    wget -qO- "$ARCHIVE_URL" | tar xz -C "$WORK_DIR"
+  else
+    fail "curl or wget required to download source."
+    exit 1
+  fi
+
+  # Gitea archives extract to <repo-name>/ inside the work dir
+  EXTRACTED_DIR="$(find "$WORK_DIR" -maxdepth 1 -mindepth 1 -type d | head -1)"
+  if [[ -z "$EXTRACTED_DIR" ]] || [[ ! -d "$EXTRACTED_DIR" ]]; then
+    fail "Could not locate extracted source in archive."
+    ls -la "$WORK_DIR" >&2
+    exit 1
+  fi
+}
+
+# Build @mosaicstack/mosaic + @mosaicstack/gateway from source and install both
+# globally from locally-packed tarballs. ZERO registry writes. Workspace deps
+# (brain/config/db/…) are pulled from the registry at the versions pinned in
+# each package.json — `pnpm pack` rewrites `workspace:*` to those versions.
+install_cli_from_source() {
+  local src="$EXTRACTED_DIR"
+  local out_dir="$WORK_DIR/dist-tarballs"
+  mkdir -p "$out_dir"
+
+  # pnpm via corepack (ships with Node >= 16.9; required by Node >= 20 preflight).
+  # Pin to the repo's packageManager version so the build matches CI. Surface
+  # corepack failures so the fresh-machine case gives an actionable error
+  # instead of a bare "command not found".
+  if ! command -v pnpm &>/dev/null; then
+    info "Activating pnpm via corepack…"
+    corepack enable 2>&1 | sed 's/^/  /' || warn "corepack enable failed — pnpm may need manual install."
+    corepack prepare pnpm@10.6.2 --activate 2>&1 | sed 's/^/  /' \
+      || warn "corepack prepare failed — pnpm may need manual install."
+  fi
+  if ! command -v pnpm &>/dev/null; then
+    fail "pnpm not available after corepack activation."
+    echo "  Install pnpm manually (https://pnpm.io/installation) and re-run with --dev."
+    exit 1
+  fi
+
+  info "Installing workspace dependencies (pnpm install)…"
+  ( cd "$src" && pnpm install ) 2>&1 | sed 's/^/  /'
+
+  info "Building CLI + gateway from source…"
+  ( cd "$src" && pnpm --filter "@mosaicstack/mosaic..." --filter "@mosaicstack/gateway..." run build ) 2>&1 | sed 's/^/  /'
+
+  info "Packing local tarballs…"
+  ( cd "$src/packages/mosaic" && pnpm pack --pack-destination "$out_dir" ) 2>&1 | sed 's/^/  /'
+  ( cd "$src/apps/gateway"    && pnpm pack --pack-destination "$out_dir" ) 2>&1 | sed 's/^/  /'
+
+  local cli_tgz gw_tgz
+  cli_tgz="$(ls -1t "$out_dir"/mosaicstack-mosaic-*.tgz 2>/dev/null | head -1)"
+  gw_tgz="$(ls -1t "$out_dir"/mosaicstack-gateway-*.tgz 2>/dev/null | head -1)"
+
+  if [[ ! -f "$cli_tgz" ]]; then
+    fail "CLI tarball was not produced by pnpm pack."
+    exit 1
+  fi
+  if [[ ! -f "$gw_tgz" ]]; then
+    fail "Gateway tarball was not produced by pnpm pack."
+    exit 1
+  fi
+
+  # Gateway first so it is present globally before the CLI's wizard runs (which
+  # skips its own gateway install via MOSAIC_GATEWAY_SKIP_NPM_INSTALL=1).
+  info "Installing gateway from source tarball (global)…"
+  npm install -g "$gw_tgz" --prefix="$PREFIX" 2>&1 | sed 's/^/  /'
+
+  info "Installing CLI from source tarball (global)…"
+  npm install -g "$cli_tgz" --prefix="$PREFIX" 2>&1 | sed 's/^/  /'
+
+  ok "Installed from source: CLI $(installed_cli_version)"
+}
+
 # ─── preflight ────────────────────────────────────────────────────────────────
 
 require_cmd node
@@ -282,25 +398,8 @@ if [[ "$FLAG_FRAMEWORK" == "true" ]]; then
       warn "Framework not installed."
     fi
   else
-    # Download repo archive and extract framework
-    require_cmd tar
-
-    WORK_DIR="$(mktemp -d "${TMPDIR:-/tmp}/mosaic-install-XXXXXX")"
-    cleanup_work() { rm -rf "$WORK_DIR"; }
-    trap cleanup_work EXIT
-
-    info "Downloading framework from ${GIT_REF}…"
-    if command -v curl &>/dev/null; then
-      curl -fsSL "$ARCHIVE_URL" | tar xz -C "$WORK_DIR"
-    elif command -v wget &>/dev/null; then
-      wget -qO- "$ARCHIVE_URL" | tar xz -C "$WORK_DIR"
-    else
-      fail "curl or wget required to download framework."
-      exit 1
-    fi
-
-    # Gitea archives extract to <repo-name>/ inside the work dir
-    EXTRACTED_DIR="$(find "$WORK_DIR" -maxdepth 1 -mindepth 1 -type d | head -1)"
+    # Download repo archive and extract framework (shared with the dev build)
+    ensure_monorepo
     FRAMEWORK_SRC="$EXTRACTED_DIR/packages/mosaic/framework"
 
     if [[ ! -d "$FRAMEWORK_SRC" ]]; then
@@ -356,7 +455,11 @@ if [[ "$FLAG_CLI" == "true" ]]; then
   fi
 
   CURRENT="$(installed_cli_version)"
-  LATEST="$(latest_cli_version)"
+  if [[ "$FLAG_DEV" == "true" ]]; then
+    LATEST=""
+  else
+    LATEST="$(latest_cli_version)"
+  fi
 
   if [[ -n "$CURRENT" ]]; then
     dim "  Installed: ${CLI_PKG}@${CURRENT}"
@@ -364,7 +467,9 @@ if [[ "$FLAG_CLI" == "true" ]]; then
     dim "  Installed: (none)"
   fi
 
-  if [[ -n "$LATEST" ]]; then
+  if [[ "$FLAG_DEV" == "true" ]]; then
+    dim "  Source:    ${REPO_BASE} (ref: ${GIT_REF}, build-from-source)"
+  elif [[ -n "$LATEST" ]]; then
     dim "  Latest:    ${CLI_PKG}@${LATEST}"
   else
     dim "  Latest:    (registry unreachable)"
@@ -372,7 +477,9 @@ if [[ "$FLAG_CLI" == "true" ]]; then
   echo ""
 
   if [[ "$FLAG_CHECK" == "true" ]]; then
-    if [[ -z "$LATEST" ]]; then
+    if [[ "$FLAG_DEV" == "true" ]]; then
+      info "Dev mode: installed version is ${CURRENT:-(none)} (no registry comparison)."
+    elif [[ -z "$LATEST" ]]; then
       warn "Could not reach registry."
     elif [[ -z "$CURRENT" ]]; then
       warn "Not installed."
@@ -383,6 +490,16 @@ if [[ "$FLAG_CLI" == "true" ]]; then
     else
       ok "Up to date (or ahead of registry)."
     fi
+  elif [[ "$FLAG_DEV" == "true" ]]; then
+    info "Dev mode — building CLI + gateway from source at ref ${GIT_REF}…"
+    ensure_monorepo
+    install_cli_from_source
+
+    # PATH check for npm prefix
+    if [[ ":$PATH:" != *":$PREFIX/bin:"* ]]; then
+      warn "$PREFIX/bin is not on your PATH"
+      dim "  Add to your shell rc:  export PATH=\"$PREFIX/bin:\$PATH\""
+    fi
   else
     if [[ -z "$LATEST" ]]; then
       warn "Could not reach registry at $REGISTRY — skipping npm CLI."