fix(ci): make queue guard purpose-sensitive (#1148)

Co-Authored-By: Claude Haiku 4.5 <[email protected]>

AGENTS.md

@@ -11,48 +11,87 @@
 
 ## Project Context
 
-Mosaic Stack is a self-hosted, multi-user AI agent platform. TypeScript monorepo with NestJS gateway, Next.js web dashboard, Pi SDK agent runtime, and plugin architecture for Discord/Telegram.
+Mosaic Stack is a self-hosted, multi-user AI agent platform. It is a TypeScript monorepo with a NestJS gateway, Next.js dashboard, Pi SDK agent runtime, and Discord/Telegram plugin architecture.
 
-## Package Map
+### Stack
 
-| Package            | Purpose                         | Key Dependencies                 |
+- **API:** NestJS with Fastify (`apps/gateway`)
-| ------------------ | ------------------------------- | -------------------------------- |
+- **Web:** Next.js 16 with React 19 (`apps/web`)
-| `apps/gateway`     | NestJS API + WebSocket hub      | Fastify, Socket.IO, Pi SDK, OTEL |
+- **ORM and database:** Drizzle ORM, PostgreSQL 17, and pgvector (`packages/db`)
-| `apps/web`         | Next.js dashboard               | React 19, Tailwind               |
+- **Authentication:** BetterAuth (`packages/auth`)
-| `packages/types`   | Shared TypeScript contracts     | class-validator                  |
+- **Agent runtime:** Pi SDK (`apps/gateway`, `packages/mosaic`)
-| `packages/db`      | Drizzle ORM schema + migrations | drizzle-orm, postgres            |
+- **Queue:** Valkey 8 (`packages/queue`)
-| `packages/auth`    | BetterAuth configuration        | better-auth, @mosaicstack/db     |
+- **Build:** pnpm workspaces and Turborepo
-| `packages/brain`   | Data layer (PG-backed)          | @mosaicstack/db                  |
+- **CI:** Woodpecker CI
-| `packages/queue`   | Valkey task queue + MCP         | ioredis                          |
+- **Observability:** OpenTelemetry and Jaeger
-| `packages/coord`   | Mission coordination            | @mosaicstack/queue               |
-| `packages/mosaic`  | Unified `mosaic` CLI + TUI      | Ink, Pi SDK, commander           |
-| `plugins/discord`  | Discord channel plugin          | discord.js                       |
-| `plugins/telegram` | Telegram channel plugin         | Telegraf                         |
 
-## Architecture Rules
+### Package Map
 
-1. Gateway is the single API surface — all clients connect through it
+| Package            | Purpose                       | Key Dependencies                 |
-2. Pi SDK is ESM-only — gateway and CLI must use ESM
+| ------------------ | ----------------------------- | -------------------------------- |
-3. Socket.IO typed events defined in `@mosaicstack/types` enforce compile-time contracts
+| `apps/gateway`     | NestJS API + WebSocket hub    | Fastify, Socket.IO, Pi SDK, OTEL |
-4. OTEL auto-instrumentation loads before NestJS bootstrap
+| `apps/web`         | Next.js dashboard             | React 19, Tailwind               |
-5. BetterAuth manages auth tables; schema defined in `@mosaicstack/db`
+| `packages/types`   | Shared TypeScript contracts   | class-validator                  |
-6. Docker Compose provides PG (5433), Valkey (6380), OTEL Collector (4317/4318), Jaeger (16686)
+| `packages/db`      | Drizzle schema and migrations | drizzle-orm, postgres            |
-7. Explicit `@Inject()` decorators required in NestJS (tsx/esbuild doesn't emit decorator metadata)
+| `packages/auth`    | BetterAuth configuration      | better-auth, @mosaicstack/db     |
+| `packages/brain`   | Structured data layer         | @mosaicstack/db                  |
+| `packages/queue`   | Valkey task queue and MCP     | ioredis                          |
+| `packages/coord`   | Mission coordination          | @mosaicstack/queue               |
+| `packages/mosaic`  | Unified `mosaic` CLI and TUI  | Ink, Pi SDK, commander           |
+| `plugins/discord`  | Discord channel plugin        | discord.js                       |
+| `plugins/telegram` | Telegram channel plugin       | Telegraf                         |
+
+## Architecture and Code Conventions
+
+1. Gateway is the single API surface; all clients connect through it.
+2. Pi SDK is ESM-only; gateway and CLI code must remain ESM.
+3. Use `"type": "module"`, NodeNext module resolution, and `.js` extensions in imports.
+4. Keep typed Socket.IO events in `@mosaicstack/types` to enforce client/server contracts.
+5. Import OTEL tracing before NestJS bootstrap (`import './tracing.js'`).
+6. Use explicit `@Inject()` decorators in NestJS because tsx/esbuild does not emit decorator metadata.
+7. Keep DTOs in `*.dto.ts` files at module boundaries.
+8. BetterAuth owns authentication tables; their schema is defined in `@mosaicstack/db`.
+9. Create a task-specific scratchpad for non-trivial work.
 
 ## Development Workflow
 
+Requirements: Node.js 20+, pnpm 10.6.2, and Docker Compose when optional local services are needed.
+
 ```bash
-docker compose up -d          # Infrastructure
+pnpm install --frozen-lockfile
-pnpm install                  # Dependencies
+pnpm preflight
-pnpm typecheck && pnpm lint && pnpm format:check  # Quality gates
+
+# Optional local queue service only; do not start the full Compose stack.
+docker compose up -d valkey
 ```
 
-## Repo-Specific Notes
+The pre-push hook requires:
 
-- DTOs in `*.dto.ts` files at module boundaries
+```bash
-- ESM everywhere (`"type": "module"`, `.js` extensions in imports)
+pnpm preflight && pnpm typecheck && pnpm lint && pnpm format:check
-- NodeNext module resolution in all tsconfigs
+```
-- Scratchpads are mandatory for non-trivial tasks
+
+Software delivery also requires the applicable tests. Common repository commands are:
+
+```bash
+pnpm typecheck     # TypeScript checks across the workspace
+pnpm lint          # ESLint across the workspace
+pnpm test          # Checkout tests and package Vitest suites
+pnpm format:check  # Prettier check
+pnpm build         # Build all packages and applications
+```
+
+## Database and Local Runtime Safety
+
+- Current local data-layer work uses in-process PGlite; leave `DATABASE_URL` unset.
+- PostgreSQL execution is held until KBN-101-00, KBN-101-03, and KBN-101-05 land.
+- Do not invoke a migration runner, initialization SQL, or the Compose PostgreSQL service from this checkout.
+- Do not start Gateway/Web or run root `pnpm dev` as a local PGlite route. The current dotenv loader can inherit a daemon PostgreSQL DSN; KBN-101-02 must make that path fail closed first.
+- Migration artifact generation is offline and does not authorize PostgreSQL access:
+
+```bash
+pnpm --filter @mosaicstack/db db:generate
+```
 
 ## docs/TASKS.md — Schema (CANONICAL)
 

CLAUDE.md

@@ -1,46 +1,5 @@
-# CLAUDE.md — Mosaic Stack
+# Claude Compatibility Pointer
 
-## Project
+@AGENTS.md
 
-Self-hosted, multi-user AI agent platform. TypeScript monorepo.
+Do not add project guidance here. Keep `AGENTS.md` authoritative so every agent runtime receives the same instructions.
-
-## Stack
-
-- **API**: NestJS + Fastify adapter (`apps/gateway`)
-- **Web**: Next.js 16 + React 19 (`apps/web`)
-- **ORM**: Drizzle ORM + PostgreSQL 17 + pgvector (`packages/db`)
-- **Auth**: BetterAuth (`packages/auth`)
-- **Agent**: Pi SDK (`packages/agent`, `packages/mosaic`)
-- **Queue**: Valkey 8 (`packages/queue`)
-- **Build**: pnpm workspaces + Turborepo
-- **CI**: Woodpecker CI
-- **Observability**: OpenTelemetry → Jaeger
-
-## Commands
-
-```bash
-pnpm typecheck        # TypeScript check (all packages)
-pnpm lint             # ESLint (all packages)
-pnpm format:check     # Prettier check
-pnpm test             # Vitest (all packages)
-pnpm build            # Build all packages
-
-# Database
-pnpm --filter @mosaicstack/db db:generate  # Offline migration artifact generation only
-# PostgreSQL execution is held until KBN-101-00/-03/-05 land. Do not invoke a runner,
-# init SQL, or Compose PostgreSQL service from this checkout.
-
-# Dev: local PGlite data-layer work needs no PostgreSQL. Optional local queue service only:
-docker compose up -d valkey
-# Do not start Gateway/Web or root pnpm dev as a local PGlite route: the current unguarded dotenv
-# loader can inherit a daemon PostgreSQL DSN. KBN-101-02 must make that state fail closed first.
-```
-
-## Conventions
-
-- ESM everywhere (`"type": "module"`, `.js` extensions in imports)
-- NodeNext module resolution
-- Explicit `@Inject()` decorators in NestJS (tsx/esbuild doesn't support emitDecoratorMetadata)
-- DTOs in `*.dto.ts` files at module boundaries
-- OTEL tracing imported before NestJS bootstrap (`import './tracing.js'`)
-- All three gates must pass before push: typecheck, lint, format:check

README.md

@@ -48,9 +48,13 @@ mosaic wizard        # Full guided setup (gateway install → verify)
 
 ### Requirements
 
-- Node.js ≥ 22
+- Node.js ≥ 20
 - npm (for global @mosaicstack/mosaic install)
-- One or more runtimes: [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://github.com/openai/codex), [OpenCode](https://opencode.ai), or [Pi](https://github.com/mariozechner/pi-coding-agent)
+- One or more runtimes:
+  - [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
+  - [Codex](https://github.com/openai/codex)
+  - [OpenCode](https://opencode.ai)
+  - [Pi](https://pi.dev)
 
 ## Usage
 
@@ -200,7 +204,7 @@ Consent state is persisted in config. Remote upload is a no-op until you run `mo
 
 ### Prerequisites
 
-- Node.js ≥ 22
+- Node.js ≥ 20
 - pnpm 10.6+
 - Docker & Docker Compose
 

apps/gateway/src/app.module.spec.ts

@@ -0,0 +1,624 @@
+import 'reflect-metadata';
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import * as nodeOs from 'node:os';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import * as nodeUrl from 'node:url';
+import { MODULE_METADATA } from '@nestjs/common/constants.js';
+import { describe, expect, it, vi } from 'vitest';
+import type { MosaicConfig } from '@mosaicstack/config';
+
+interface ComposedModuleGraph {
+  imports: readonly unknown[];
+  federationModule: unknown;
+  bootLogLines: readonly string[];
+  mosaicConfig: MosaicConfig;
+  resolvedConfigPath: string;
+}
+
+type StorageTier = 'local' | 'standalone' | 'federated';
+
+interface ModuleGraphFixture {
+  tempRoot: string;
+  anchor: string;
+  homePath: string;
+  cwdPath: string;
+  monorepoRootEnvPath: string;
+  gatewayLocalEnvPath: string;
+  daemonEnvPath: string;
+  monorepoRootConfigPath: string;
+  gatewayLocalConfigPath: string;
+}
+
+interface ModuleGraphFixtureOptions {
+  rootEnvMode?: 'present' | 'absent';
+  rootTier?: StorageTier;
+  rootEnvContents?: string;
+  redactionMarker?: string;
+  gatewayLocalTier?: StorageTier;
+  gatewayLocalEnvContents?: string;
+  daemonEnvContents?: string;
+  inheritedTier?: StorageTier;
+  expectedProcessTier?: string;
+  setup?: (fixture: ModuleGraphFixture) => Promise<void>;
+}
+
+// Each case uses vi.resetModules() and re-imports the full gateway graph for distinct ambient FS/env; CI needs headroom, while this still guards genuine hangs.
+const MODULE_IMPORT_TIMEOUT_MS = 120_000;
+const MONOREPO_ROOT_DOTENV_LABEL = 'monorepo-root .env';
+const DAEMON_DOTENV_LABEL = 'daemon .env';
+
+function configJson(tier: StorageTier): string {
+  if (tier === 'local') {
+    return JSON.stringify({
+      tier,
+      storage: { type: 'pglite', dataDir: '.mosaic/storage-pglite' },
+      queue: { type: 'local', dataDir: '.mosaic/queue' },
+      memory: { type: 'keyword' },
+    });
+  }
+
+  return JSON.stringify({
+    tier,
+    storage: { type: 'postgres', url: 'postgresql://fixture.invalid/mosaic' },
+    queue: { type: 'bullmq' },
+    memory: { type: tier === 'federated' ? 'pgvector' : 'keyword' },
+  });
+}
+
+function snapshotProcessEnv(): Record<string, string | undefined> {
+  return { ...process.env };
+}
+
+function restoreProcessEnv(snapshot: Record<string, string | undefined>): void {
+  for (const key of Object.keys(process.env)) {
+    if (!(key in snapshot)) {
+      delete process.env[key];
+    }
+  }
+
+  for (const [key, value] of Object.entries(snapshot)) {
+    if (value === undefined) {
+      delete process.env[key];
+      continue;
+    }
+
+    process.env[key] = value;
+  }
+}
+
+function expectPathUnderTempRoot(path: string, tempRoot: string): void {
+  const relativePath = relative(tempRoot, path);
+  expect(relativePath === '' || (!relativePath.startsWith('..') && !isAbsolute(relativePath))).toBe(
+    true,
+  );
+}
+
+async function writeFixture(path: string, contents: string, tempRoot: string): Promise<void> {
+  expectPathUnderTempRoot(path, tempRoot);
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, contents, 'utf8');
+}
+
+interface ConfigModuleProvider {
+  provide: string;
+  useFactory: () => MosaicConfig;
+}
+
+function isConfigModuleProvider(value: unknown): value is ConfigModuleProvider {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+
+  if (!('provide' in value) || typeof value.provide !== 'string') {
+    return false;
+  }
+
+  return 'useFactory' in value && typeof value.useFactory === 'function';
+}
+
+function singleBootLogLine(bootLogLines: readonly string[]): string {
+  expect(bootLogLines).toHaveLength(1);
+  const [bootLogLine] = bootLogLines;
+  if (bootLogLine === undefined) {
+    throw new Error('Expected a single boot log line');
+  }
+
+  return bootLogLine;
+}
+
+function expectBootLogLine(
+  bootLogLines: readonly string[],
+  tier: StorageTier,
+  source: string,
+): void {
+  const bootLogLine = singleBootLogLine(bootLogLines);
+
+  expect(bootLogLine).toContain(`storage tier=${tier}`);
+  expect(bootLogLine).toContain(`source=${source}`);
+}
+
+async function loadModuleGraphFromDotenv(
+  options: ModuleGraphFixtureOptions,
+): Promise<ComposedModuleGraph> {
+  const originalEnv = snapshotProcessEnv();
+  const tempRoot = await mkdtemp(join(nodeOs.tmpdir(), 'mosaic-gateway-module-'));
+  let consoleInfoSpy: ReturnType<typeof vi.spyOn> | undefined;
+  let cwdSpy: ReturnType<typeof vi.spyOn> | undefined;
+
+  try {
+    const anchor = join(tempRoot, 'anchored', 'apps', 'gateway', 'src');
+    const homePath = join(tempRoot, 'home');
+    const cwdPath = join(tempRoot, 'ambient', 'parent', 'cwd');
+    const fixture: ModuleGraphFixture = {
+      tempRoot,
+      anchor,
+      homePath,
+      cwdPath,
+      monorepoRootEnvPath: resolve(anchor, '../../..', '.env'),
+      gatewayLocalEnvPath: resolve(anchor, '..', '.env'),
+      daemonEnvPath: join(homePath, '.config', 'mosaic', 'gateway', '.env'),
+      monorepoRootConfigPath: resolve(anchor, '../../..', 'mosaic.config.json'),
+      gatewayLocalConfigPath: resolve(anchor, '..', 'mosaic.config.json'),
+    };
+    consoleInfoSpy = vi.spyOn(console, 'info').mockImplementation((): void => undefined);
+
+    for (const path of Object.values(fixture)) {
+      expectPathUnderTempRoot(path, tempRoot);
+    }
+
+    await mkdir(anchor, { recursive: true });
+    await mkdir(cwdPath, { recursive: true });
+
+    if ((options.rootEnvMode ?? 'present') === 'absent') {
+      if (
+        options.rootEnvContents !== undefined ||
+        options.rootTier !== undefined ||
+        options.redactionMarker !== undefined
+      ) {
+        throw new Error('Expected no root env fixture values when rootEnvMode is absent');
+      }
+    } else {
+      if (options.rootEnvContents === undefined && options.rootTier === undefined) {
+        throw new Error('Expected rootTier or rootEnvContents');
+      }
+
+      const rootFixture = options.rootEnvContents ?? `MOSAIC_STORAGE_TIER=${options.rootTier}\n`;
+      const rootFixtureWithMarker = options.redactionMarker
+        ? `${rootFixture}BETTER_AUTH_SECRET=${options.redactionMarker}\n`
+        : rootFixture;
+      await writeFixture(fixture.monorepoRootEnvPath, rootFixtureWithMarker, tempRoot);
+    }
+
+    if (options.daemonEnvContents !== undefined) {
+      await writeFixture(fixture.daemonEnvPath, options.daemonEnvContents, tempRoot);
+    }
+
+    if (options.gatewayLocalEnvContents !== undefined) {
+      await writeFixture(fixture.gatewayLocalEnvPath, options.gatewayLocalEnvContents, tempRoot);
+    } else if (options.gatewayLocalTier !== undefined) {
+      await writeFixture(
+        fixture.gatewayLocalEnvPath,
+        `MOSAIC_STORAGE_TIER=${options.gatewayLocalTier}\n`,
+        tempRoot,
+      );
+    }
+
+    process.env['HOME'] = homePath;
+    delete process.env['MOSAIC_STORAGE_TIER'];
+    delete process.env['DATABASE_URL'];
+    delete process.env['VALKEY_URL'];
+    delete process.env['MOSAIC_GATEWAY_HOME'];
+
+    await options.setup?.(fixture);
+
+    if (options.inheritedTier !== undefined) {
+      process.env['MOSAIC_STORAGE_TIER'] = options.inheritedTier;
+    }
+
+    vi.resetModules();
+    vi.doMock('node:os', () => ({ ...nodeOs, homedir: (): string => homePath }));
+    vi.doMock('node:url', () => ({
+      ...nodeUrl,
+      fileURLToPath: (url: string | URL): string => {
+        const actualPath = nodeUrl.fileURLToPath(url);
+        if (
+          actualPath.endsWith('/apps/gateway/src/env.ts') ||
+          actualPath.endsWith('/apps/gateway/src/env.js')
+        ) {
+          return join(anchor, 'env.ts');
+        }
+        return actualPath;
+      },
+    }));
+    cwdSpy = vi.spyOn(process, 'cwd').mockReturnValue(cwdPath);
+
+    if (options.inheritedTier === undefined) {
+      expect(process.env['MOSAIC_STORAGE_TIER']).toBeUndefined();
+    } else {
+      expect(process.env['MOSAIC_STORAGE_TIER']).toBe(options.inheritedTier);
+    }
+
+    const envModule = await import('./env.js');
+    expect(process.env['MOSAIC_STORAGE_TIER']).toBe(
+      options.expectedProcessTier ?? options.rootTier,
+    );
+
+    const { AppModule } = await import('./app.module.js');
+    const { FederationModule } = await import('./federation/federation.module.js');
+    const imports: unknown = Reflect.getMetadata(MODULE_METADATA.IMPORTS, AppModule);
+
+    if (!Array.isArray(imports)) {
+      throw new Error('AppModule imports metadata is not an array');
+    }
+
+    const { ConfigModule, MOSAIC_CONFIG } = await import('./config/config.module.js');
+    const providers: unknown = Reflect.getMetadata(MODULE_METADATA.PROVIDERS, ConfigModule);
+
+    if (!Array.isArray(providers)) {
+      throw new Error('ConfigModule providers metadata is not an array');
+    }
+
+    const configProvider = providers
+      .filter(isConfigModuleProvider)
+      .find((provider: ConfigModuleProvider): boolean => provider.provide === MOSAIC_CONFIG);
+
+    if (!configProvider) {
+      throw new Error('MOSAIC_CONFIG provider factory not found');
+    }
+
+    return {
+      imports,
+      federationModule: FederationModule,
+      bootLogLines: consoleInfoSpy.mock.calls.map((args: readonly unknown[]): string =>
+        args.map((value: unknown): string => String(value)).join(' '),
+      ),
+      mosaicConfig: configProvider.useFactory(),
+      resolvedConfigPath: envModule.resolveGatewayConfigPath(),
+    };
+  } finally {
+    cwdSpy?.mockRestore();
+    vi.doUnmock('node:url');
+    vi.doUnmock('node:os');
+    vi.resetModules();
+    consoleInfoSpy?.mockRestore();
+    restoreProcessEnv(originalEnv);
+    await rm(tempRoot, { recursive: true, force: true });
+  }
+}
+
+describe('AppModule federation gating', (): void => {
+  it('loads dotenv before tracing and AppModule evaluation', async (): Promise<void> => {
+    const mainSource = await readFile(new URL('./main.ts', import.meta.url), 'utf8');
+    const envImportIndex = mainSource.indexOf("import './env.js';");
+    const tracingImportIndex = mainSource.indexOf("import './tracing.js';");
+    const appModuleImportIndex = mainSource.indexOf("import { AppModule } from './app.module.js';");
+
+    expect(envImportIndex).toBeGreaterThan(-1);
+    expect(envImportIndex).toBeLessThan(tracingImportIndex);
+    expect(envImportIndex).toBeLessThan(appModuleImportIndex);
+  });
+
+  it(
+    'ignores ambient cwd/.env and cwd/../.env files',
+    async (): Promise<void> => {
+      const graph = await loadModuleGraphFromDotenv({
+        rootTier: 'local',
+        setup: async (fixture: ModuleGraphFixture): Promise<void> => {
+          await writeFixture(
+            join(fixture.cwdPath, '.env'),
+            'MOSAIC_STORAGE_TIER=federated\n',
+            fixture.tempRoot,
+          );
+          await writeFixture(
+            resolve(fixture.cwdPath, '..', '.env'),
+            'MOSAIC_STORAGE_TIER=federated\n',
+            fixture.tempRoot,
+          );
+        },
+      });
+
+      expect(graph.imports).not.toContain(graph.federationModule);
+      expectBootLogLine(graph.bootLogLines, 'local', MONOREPO_ROOT_DOTENV_LABEL);
+    },
+    MODULE_IMPORT_TIMEOUT_MS,
+  );
+
+  it(
+    'ignores an ambient cwd/mosaic.config.json federated config',
+    async (): Promise<void> => {
+      const graph = await loadModuleGraphFromDotenv({
+        rootTier: 'local',
+        setup: async (fixture: ModuleGraphFixture): Promise<void> => {
+          await writeFixture(
+            join(fixture.cwdPath, 'mosaic.config.json'),
+            configJson('federated'),
+            fixture.tempRoot,
+          );
+        },
+      });
+
+      expect(graph.imports).not.toContain(graph.federationModule);
+      expectBootLogLine(graph.bootLogLines, 'local', MONOREPO_ROOT_DOTENV_LABEL);
+    },
+    MODULE_IMPORT_TIMEOUT_MS,
+  );
+
+  it(
+    'ignores an ambient cwd/../../mosaic.config.json federated config',
+    async (): Promise<void> => {
+      const graph = await loadModuleGraphFromDotenv({
+        rootTier: 'local',
+        setup: async (fixture: ModuleGraphFixture): Promise<void> => {
+          await writeFixture(
+            resolve(fixture.cwdPath, '../..', 'mosaic.config.json'),
+            configJson('federated'),
+            fixture.tempRoot,
+          );
+        },
+      });
+
+      expect(graph.imports).not.toContain(graph.federationModule);
+      expectBootLogLine(graph.bootLogLines, 'local', MONOREPO_ROOT_DOTENV_LABEL);
+    },
+    MODULE_IMPORT_TIMEOUT_MS,
+  );
+
+  it(
+    'anchored gateway-local config wins monorepo-root config and registers FederationModule',
+    async (): Promise<void> => {
+      let gatewayLocalConfigPath = '';
+      const graph = await loadModuleGraphFromDotenv({
+        rootTier: 'local',
+        setup: async (fixture: ModuleGraphFixture): Promise<void> => {
+          gatewayLocalConfigPath = fixture.gatewayLocalConfigPath;
+          await writeFixture(
+            fixture.gatewayLocalConfigPath,
+            configJson('federated'),
+            fixture.tempRoot,
+          );
+          await writeFixture(fixture.monorepoRootConfigPath, configJson('local'), fixture.tempRoot);
+        },
+      });
+
+      expect(graph.resolvedConfigPath).toBe(gatewayLocalConfigPath);
+      expect(graph.mosaicConfig.tier).toBe('federated');
+      expect(graph.imports).toContain(graph.federationModule);
+      expectBootLogLine(graph.bootLogLines, 'federated', 'mosaic.config.json');
+    },
+    MODULE_IMPORT_TIMEOUT_MS,
+  );
+
+  it(
+    'resolves the daemon-installed GATEWAY_HOME/mosaic.config.json ahead of gateway-local and monorepo-root configs',
+    async (): Promise<void> => {
+      let daemonConfigPath = '';
+      const graph = await loadModuleGraphFromDotenv({
+        rootEnvMode: 'absent',
+        setup: async (fixture: ModuleGraphFixture): Promise<void> => {
+          const externalGatewayHome = join(fixture.tempRoot, 'external-gateway-home');
+          daemonConfigPath = join(externalGatewayHome, 'mosaic.config.json');
+          await writeFixture(daemonConfigPath, configJson('federated'), fixture.tempRoot);
+          await writeFixture(
+            fixture.gatewayLocalConfigPath,
+            configJson('standalone'),
+            fixture.tempRoot,
+          );
+          await writeFixture(fixture.monorepoRootConfigPath, configJson('local'), fixture.tempRoot);
+          process.env['MOSAIC_GATEWAY_HOME'] = externalGatewayHome;
+          process.env['DATABASE_URL'] = 'postgresql://fixture.invalid/mosaic';
+        },
+      });
+
+      expect(graph.resolvedConfigPath).toBe(daemonConfigPath);
+      expect(graph.mosaicConfig.tier).toBe('federated');
+      expect(graph.imports).toContain(graph.federationModule);
+      expectBootLogLine(graph.bootLogLines, 'federated', 'mosaic.config.json');
+    },
+    MODULE_IMPORT_TIMEOUT_MS,
+  );
+
+  it(
+    'logs mosaic.config.json when anchored config and env tiers are both federated',
+    async (): Promise<void> => {
+      const graph = await loadModuleGraphFromDotenv({
+        rootTier: 'federated',
+        setup: async (fixture: ModuleGraphFixture): Promise<void> => {
+          await writeFixture(
+            fixture.monorepoRootConfigPath,
+            configJson('federated'),
+            fixture.tempRoot,
+          );
+        },
+      });
+
+      expect(graph.imports).toContain(graph.federationModule);
+      expectBootLogLine(graph.bootLogLines, 'federated', 'mosaic.config.json');
+    },
+    MODULE_IMPORT_TIMEOUT_MS,
+  );
+
+  it(
+    'logs standalone from a monorepo-root .env DATABASE_URL fallback',
+    async (): Promise<void> => {
+      const graph = await loadModuleGraphFromDotenv({
+        rootEnvContents: 'DATABASE_URL=fixture-database-url\n',
+      });
+
+      expect(graph.imports).not.toContain(graph.federationModule);
+      expectBootLogLine(graph.bootLogLines, 'standalone', MONOREPO_ROOT_DOTENV_LABEL);
+    },
+    MODULE_IMPORT_TIMEOUT_MS,
+  );
+
+  it(
+    'attributes an invalid monorepo-root dotenv tier to the default',
+    async (): Promise<void> => {
+      const graph = await loadModuleGraphFromDotenv({
+        rootEnvContents: 'MOSAIC_STORAGE_TIER=invalid\n',
+        expectedProcessTier: 'invalid',
+      });
+
+      expect(graph.imports).not.toContain(graph.federationModule);
+      expectBootLogLine(graph.bootLogLines, 'local', 'default');
+    },
+    MODULE_IMPORT_TIMEOUT_MS,
+  );
+
+  it(
+    'attributes DATABASE_URL fallback to daemon .env ahead of inherited local tier',
+    async (): Promise<void> => {
+      const graph = await loadModuleGraphFromDotenv({
+        rootEnvMode: 'absent',
+        daemonEnvContents: 'DATABASE_URL=fixture-database-url\n',
+        inheritedTier: 'local',
+        expectedProcessTier: 'local',
+      });
+
+      expect(graph.imports).not.toContain(graph.federationModule);
+      expectBootLogLine(graph.bootLogLines, 'standalone', DAEMON_DOTENV_LABEL);
+    },
+    MODULE_IMPORT_TIMEOUT_MS,
+  );
+
+  it(
+    'daemon .env wins over monorepo-root and gateway-local tier values',
+    async (): Promise<void> => {
+      const graph = await loadModuleGraphFromDotenv({
+        rootTier: 'local',
+        gatewayLocalTier: 'federated',
+        daemonEnvContents: 'MOSAIC_STORAGE_TIER=standalone\n',
+        expectedProcessTier: 'standalone',
+      });
+
+      expect(graph.imports).not.toContain(graph.federationModule);
+      expectBootLogLine(graph.bootLogLines, 'standalone', DAEMON_DOTENV_LABEL);
+    },
+    MODULE_IMPORT_TIMEOUT_MS,
+  );
+
+  it(
+    'inherits process.env.MOSAIC_STORAGE_TIER over daemon, monorepo-root, and gateway-local dotenv values',
+    async (): Promise<void> => {
+      const graph = await loadModuleGraphFromDotenv({
+        rootTier: 'local',
+        gatewayLocalTier: 'federated',
+        daemonEnvContents: 'MOSAIC_STORAGE_TIER=federated\n',
+        inheritedTier: 'standalone',
+        expectedProcessTier: 'standalone',
+      });
+
+      expect(graph.imports).not.toContain(graph.federationModule);
+      expectBootLogLine(graph.bootLogLines, 'standalone', 'process environment');
+    },
+    MODULE_IMPORT_TIMEOUT_MS,
+  );
+
+  it(
+    'gateway-local .env configures the tier and source when the monorepo-root .env is absent',
+    async (): Promise<void> => {
+      const graph = await loadModuleGraphFromDotenv({
+        rootEnvMode: 'absent',
+        gatewayLocalTier: 'federated',
+        expectedProcessTier: 'federated',
+      });
+
+      expect(graph.imports).toContain(graph.federationModule);
+      expectBootLogLine(graph.bootLogLines, 'federated', 'gateway-local .env');
+    },
+    MODULE_IMPORT_TIMEOUT_MS,
+  );
+
+  it(
+    'monorepo-root .env wins over gateway-local tier values',
+    async (): Promise<void> => {
+      const graph = await loadModuleGraphFromDotenv({
+        rootTier: 'standalone',
+        gatewayLocalTier: 'federated',
+      });
+
+      expect(graph.imports).not.toContain(graph.federationModule);
+      expectBootLogLine(graph.bootLogLines, 'standalone', MONOREPO_ROOT_DOTENV_LABEL);
+    },
+    MODULE_IMPORT_TIMEOUT_MS,
+  );
+
+  it.each(['local', 'standalone'] as const)(
+    'does not register FederationModule for the %s tier',
+    async (tier): Promise<void> => {
+      const graph = await loadModuleGraphFromDotenv({ rootTier: tier });
+
+      expect(graph.imports).not.toContain(graph.federationModule);
+      expectBootLogLine(graph.bootLogLines, tier, MONOREPO_ROOT_DOTENV_LABEL);
+    },
+    MODULE_IMPORT_TIMEOUT_MS,
+  );
+
+  it(
+    'registers FederationModule when federated tier is supplied by the anchored monorepo root .env',
+    async (): Promise<void> => {
+      const redactionMarker = 'redaction-fixture-marker';
+      const graph = await loadModuleGraphFromDotenv({
+        rootTier: 'federated',
+        redactionMarker,
+      });
+
+      expect(graph.imports).toContain(graph.federationModule);
+      expectBootLogLine(graph.bootLogLines, 'federated', MONOREPO_ROOT_DOTENV_LABEL);
+      expect(singleBootLogLine(graph.bootLogLines)).not.toContain(redactionMarker);
+    },
+    MODULE_IMPORT_TIMEOUT_MS,
+  );
+
+  it(
+    'MOSAIC_CONFIG provider ignores an ambient cwd/mosaic.config.json config',
+    async (): Promise<void> => {
+      const graph = await loadModuleGraphFromDotenv({
+        rootTier: 'local',
+        setup: async (fixture: ModuleGraphFixture): Promise<void> => {
+          await writeFixture(
+            join(fixture.cwdPath, 'mosaic.config.json'),
+            JSON.stringify({
+              tier: 'federated',
+              storage: {
+                type: 'postgres',
+                url: 'postgresql://ambient-attacker.invalid/mosaic',
+                enableVector: true,
+              },
+              queue: { type: 'bullmq' },
+              memory: { type: 'pgvector' },
+            }),
+            fixture.tempRoot,
+          );
+        },
+      });
+
+      expect(graph.mosaicConfig.tier).toBe('local');
+      expect(graph.mosaicConfig.storage).not.toEqual(
+        expect.objectContaining({ url: 'postgresql://ambient-attacker.invalid/mosaic' }),
+      );
+    },
+    MODULE_IMPORT_TIMEOUT_MS,
+  );
+
+  it(
+    'MOSAIC_CONFIG provider resolves from the anchored monorepo-root mosaic.config.json',
+    async (): Promise<void> => {
+      const graph = await loadModuleGraphFromDotenv({
+        rootTier: 'local',
+        setup: async (fixture: ModuleGraphFixture): Promise<void> => {
+          await writeFixture(
+            fixture.monorepoRootConfigPath,
+            configJson('federated'),
+            fixture.tempRoot,
+          );
+        },
+      });
+
+      expect(graph.mosaicConfig.tier).toBe('federated');
+      expect(graph.mosaicConfig.storage).toEqual(
+        expect.objectContaining({ url: 'postgresql://fixture.invalid/mosaic' }),
+      );
+    },
+    MODULE_IMPORT_TIMEOUT_MS,
+  );
+});

apps/gateway/src/app.module.ts

@@ -26,6 +26,16 @@ import { WorkspaceModule } from './workspace/workspace.module.js';
 import { QueueModule } from './queue/queue.module.js';
 import { FederationModule } from './federation/federation.module.js';
 import { ThrottlerGuard, ThrottlerModule } from '@nestjs/throttler';
+import { loadConfig } from '@mosaicstack/config';
+import { resolveGatewayConfigPath } from './env.js';
+
+// Federation (step-ca client, enrollment, federation verbs) is only wired for
+// tier 'federated' — CaService hard-requires STEP_CA_* at construction, which
+// must not gate standalone/local boots (docker-compose.federated.yml: the
+// federation profile "must not start in non-federated dev"). The gateway
+// entrypoint loads env.ts before evaluating this module so dotenv-backed tier
+// configuration is visible here.
+const federationEnabled = loadConfig(resolveGatewayConfigPath()).tier === 'federated';
 
 @Module({
   imports: [
@@ -53,7 +63,7 @@ import { ThrottlerGuard, ThrottlerModule } from '@nestjs/throttler';
     QueueModule,
     ReloadModule,
     WorkspaceModule,
-    FederationModule,
+    ...(federationEnabled ? [FederationModule] : []),
   ],
   controllers: [HealthController],
   providers: [

apps/gateway/src/config/config.module.ts

@@ -1,5 +1,6 @@
 import { Global, Module } from '@nestjs/common';
 import { loadConfig, type MosaicConfig } from '@mosaicstack/config';
+import { resolveGatewayConfigPath } from '../env.js';
 
 export const MOSAIC_CONFIG = 'MOSAIC_CONFIG';
 
@@ -8,7 +9,7 @@ export const MOSAIC_CONFIG = 'MOSAIC_CONFIG';
   providers: [
     {
       provide: MOSAIC_CONFIG,
-      useFactory: (): MosaicConfig => loadConfig(),
+      useFactory: (): MosaicConfig => loadConfig(resolveGatewayConfigPath()),
     },
   ],
   exports: [MOSAIC_CONFIG],

apps/gateway/src/env.ts

@@ -0,0 +1,133 @@
+import { config } from 'dotenv';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { detectFromEnv, loadConfig } from '@mosaicstack/config';
+
+type TierSource =
+  | 'process environment'
+  | 'daemon .env'
+  | 'monorepo-root .env'
+  | 'gateway-local .env'
+  | 'default';
+
+type BootSource = TierSource | 'mosaic.config.json';
+
+export interface GatewayDotenvPaths {
+  daemonEnv: string;
+  monorepoRootEnv: string;
+  gatewayLocalEnv: string;
+}
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+export function resolveGatewayDotenvPaths(
+  anchor: string = here,
+  homeBase: string = homedir(),
+): GatewayDotenvPaths {
+  return {
+    daemonEnv: join(homeBase, '.config', 'mosaic', 'gateway', '.env'),
+    monorepoRootEnv: resolve(anchor, '../../..', '.env'),
+    gatewayLocalEnv: resolve(anchor, '..', '.env'),
+  };
+}
+
+export function resolveGatewayConfigPath(anchor: string = here): string {
+  // GATEWAY_HOME is daemon-created 0700; its env override adds no authority because env can set MOSAIC_STORAGE_TIER.
+  const gatewayHome = resolve(
+    process.env['MOSAIC_GATEWAY_HOME'] ?? join(homedir(), '.config', 'mosaic', 'gateway'),
+  );
+  const daemonConfig = join(gatewayHome, 'mosaic.config.json');
+  const gatewayLocalConfig = resolve(anchor, '..', 'mosaic.config.json');
+  const monorepoRootConfig = resolve(anchor, '../../..', 'mosaic.config.json');
+
+  if (existsSync(daemonConfig)) {
+    return daemonConfig;
+  }
+  if (existsSync(gatewayLocalConfig)) {
+    return gatewayLocalConfig;
+  }
+  if (existsSync(monorepoRootConfig)) {
+    return monorepoRootConfig;
+  }
+
+  return monorepoRootConfig;
+}
+
+export function loadGatewayEnv(anchor: string = here, homeBase: string = homedir()): void {
+  const { daemonEnv, monorepoRootEnv, gatewayLocalEnv } = resolveGatewayDotenvPaths(
+    anchor,
+    homeBase,
+  );
+  const inheritedTier = process.env['MOSAIC_STORAGE_TIER'];
+  let tierSource: TierSource = inheritedTier === undefined ? 'default' : 'process environment';
+  const inheritedDatabaseUrl = process.env['DATABASE_URL'];
+  let databaseUrlSource: TierSource =
+    inheritedDatabaseUrl === undefined ? 'default' : 'process environment';
+
+  function loadAnchoredDotenv(
+    path: string,
+    sourceLabel: Exclude<TierSource, 'process environment' | 'default'>,
+  ): void {
+    if (!existsSync(path)) {
+      return;
+    }
+
+    const beforeTier = process.env['MOSAIC_STORAGE_TIER'];
+    const beforeDatabaseUrl = process.env['DATABASE_URL'];
+    config({ path, quiet: true });
+
+    if (
+      beforeTier === undefined &&
+      process.env['MOSAIC_STORAGE_TIER'] !== undefined &&
+      tierSource === 'default'
+    ) {
+      tierSource = sourceLabel;
+    }
+
+    if (
+      beforeDatabaseUrl === undefined &&
+      process.env['DATABASE_URL'] !== undefined &&
+      databaseUrlSource === 'default'
+    ) {
+      databaseUrlSource = sourceLabel;
+    }
+  }
+
+  // Load .env from daemon config dir (global install / daemon mode) first.
+  // It takes precedence over file-based local-dev configuration.
+  loadAnchoredDotenv(daemonEnv, 'daemon .env');
+
+  // Load .env from the anchored monorepo root, then fill any remaining values
+  // from apps/gateway/.env when present.
+  loadAnchoredDotenv(monorepoRootEnv, 'monorepo-root .env');
+  loadAnchoredDotenv(gatewayLocalEnv, 'gateway-local .env');
+
+  const envOnlyTier = detectFromEnv().tier;
+  const configPath = resolveGatewayConfigPath(anchor);
+  const anchoredConfigExists = existsSync(configPath);
+  const resolvedTier = loadConfig(configPath).tier;
+  const configuredTier = process.env['MOSAIC_STORAGE_TIER'];
+  const databaseUrlDeterminesTier = envOnlyTier === 'standalone' && configuredTier !== 'standalone';
+  const recognizedTierDeterminesTier =
+    (configuredTier === 'federated' ||
+      configuredTier === 'standalone' ||
+      configuredTier === 'local') &&
+    configuredTier === envOnlyTier;
+
+  let source: BootSource;
+  if (anchoredConfigExists) {
+    source = 'mosaic.config.json';
+  } else if (databaseUrlDeterminesTier && databaseUrlSource !== 'default') {
+    source = databaseUrlSource;
+  } else if (recognizedTierDeterminesTier && tierSource !== 'default') {
+    source = tierSource;
+  } else {
+    source = 'default';
+  }
+
+  console.info(`[gateway env] storage tier=${resolvedTier} source=${source}`);
+}
+
+loadGatewayEnv();

apps/gateway/src/main.spec.ts

@@ -0,0 +1,164 @@
+import 'reflect-metadata';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import * as nodeOs from 'node:os';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import * as nodeUrl from 'node:url';
+import type { MosaicConfig } from '@mosaicstack/config';
+import type * as MosaicStorage from '@mosaicstack/storage';
+import { describe, expect, it, vi, type MockInstance } from 'vitest';
+
+// Each case uses vi.resetModules() and re-imports the full gateway graph for distinct ambient FS/env; CI needs headroom, while this still guards genuine hangs.
+const MODULE_IMPORT_TIMEOUT_MS = 120_000;
+
+function snapshotProcessEnv(): Record<string, string | undefined> {
+  return { ...process.env };
+}
+
+function restoreProcessEnv(snapshot: Record<string, string | undefined>): void {
+  for (const key of Object.keys(process.env)) {
+    if (!(key in snapshot)) {
+      delete process.env[key];
+    }
+  }
+
+  for (const [key, value] of Object.entries(snapshot)) {
+    if (value === undefined) {
+      delete process.env[key];
+      continue;
+    }
+
+    process.env[key] = value;
+  }
+}
+
+function expectPathUnderTempRoot(path: string, tempRoot: string): void {
+  const relativePath = relative(tempRoot, path);
+  expect(relativePath === '' || (!relativePath.startsWith('..') && !isAbsolute(relativePath))).toBe(
+    true,
+  );
+}
+
+async function writeFixture(path: string, contents: string, tempRoot: string): Promise<void> {
+  expectPathUnderTempRoot(path, tempRoot);
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, contents, 'utf8');
+}
+
+interface BootstrapPreflightResult {
+  capturedConfig: MosaicConfig | undefined;
+}
+
+async function runBootstrapPreflight(
+  anchoredConfigContents: string,
+  ambientConfigContents: string,
+): Promise<BootstrapPreflightResult> {
+  const originalEnv = snapshotProcessEnv();
+  const tempRoot = await mkdtemp(join(nodeOs.tmpdir(), 'mosaic-gateway-main-preflight-'));
+  let cwdSpy: ReturnType<typeof vi.spyOn> | undefined;
+  let exitSpy: MockInstance<typeof process.exit> | undefined;
+  let consoleInfoSpy: ReturnType<typeof vi.spyOn> | undefined;
+  let capturedConfig: MosaicConfig | undefined;
+
+  try {
+    const anchor = join(tempRoot, 'anchored', 'apps', 'gateway', 'src');
+    const homePath = join(tempRoot, 'home');
+    const cwdPath = join(tempRoot, 'ambient', 'cwd');
+    const monorepoRootConfigPath = resolve(anchor, '../../..', 'mosaic.config.json');
+
+    await mkdir(anchor, { recursive: true });
+    await mkdir(cwdPath, { recursive: true });
+
+    await writeFixture(monorepoRootConfigPath, anchoredConfigContents, tempRoot);
+    await writeFixture(join(cwdPath, 'mosaic.config.json'), ambientConfigContents, tempRoot);
+
+    process.env['HOME'] = homePath;
+    process.env['BETTER_AUTH_SECRET'] = 'fixture-secret';
+    delete process.env['MOSAIC_STORAGE_TIER'];
+    delete process.env['DATABASE_URL'];
+    delete process.env['VALKEY_URL'];
+
+    consoleInfoSpy = vi.spyOn(console, 'info').mockImplementation((): void => undefined);
+    const exitMock = vi.fn<typeof process.exit>();
+    exitSpy = vi.spyOn(process, 'exit').mockImplementation(exitMock);
+
+    vi.resetModules();
+    vi.doMock('node:os', () => ({ ...nodeOs, homedir: (): string => homePath }));
+    vi.doMock('node:url', () => ({
+      ...nodeUrl,
+      fileURLToPath: (url: string | URL): string => {
+        const actualPath = nodeUrl.fileURLToPath(url);
+        if (
+          actualPath.endsWith('/apps/gateway/src/env.ts') ||
+          actualPath.endsWith('/apps/gateway/src/env.js')
+        ) {
+          return join(anchor, 'env.ts');
+        }
+        return actualPath;
+      },
+    }));
+    cwdSpy = vi.spyOn(process, 'cwd').mockReturnValue(cwdPath);
+    vi.doMock('./tracing.js', () => ({}));
+
+    const preflightSentinel = new Error('preflight-capture-sentinel');
+    vi.doMock('@mosaicstack/storage', async () => {
+      const actual = await vi.importActual<typeof MosaicStorage>('@mosaicstack/storage');
+      return {
+        ...actual,
+        detectAndAssertTier: vi.fn((config: MosaicConfig): Promise<void> => {
+          capturedConfig = config;
+          throw preflightSentinel;
+        }),
+      };
+    });
+
+    await import('./main.js');
+    await vi.waitFor((): void => {
+      expect(exitSpy).toHaveBeenCalled();
+    });
+
+    return { capturedConfig };
+  } finally {
+    cwdSpy?.mockRestore();
+    exitSpy?.mockRestore();
+    consoleInfoSpy?.mockRestore();
+    vi.doUnmock('@mosaicstack/storage');
+    vi.doUnmock('./tracing.js');
+    vi.doUnmock('node:url');
+    vi.doUnmock('node:os');
+    vi.resetModules();
+    restoreProcessEnv(originalEnv);
+    await rm(tempRoot, { recursive: true, force: true });
+  }
+}
+
+describe('main bootstrap preflight config anchoring', (): void => {
+  it(
+    'passes the anchored monorepo-root config to detectAndAssertTier, not an ambient cwd config',
+    async (): Promise<void> => {
+      const anchoredConfig = JSON.stringify({
+        tier: 'local',
+        storage: { type: 'pglite', dataDir: '.mosaic/storage-pglite' },
+        queue: { type: 'local', dataDir: '.mosaic/queue' },
+        memory: { type: 'keyword' },
+      });
+      const ambientConfig = JSON.stringify({
+        tier: 'federated',
+        storage: {
+          type: 'postgres',
+          url: 'postgresql://ambient-attacker.invalid/mosaic',
+          enableVector: true,
+        },
+        queue: { type: 'bullmq' },
+        memory: { type: 'pgvector' },
+      });
+
+      const { capturedConfig } = await runBootstrapPreflight(anchoredConfig, ambientConfig);
+
+      expect(capturedConfig?.tier).toBe('local');
+      expect(capturedConfig?.storage).not.toEqual(
+        expect.objectContaining({ url: 'postgresql://ambient-attacker.invalid/mosaic' }),
+      );
+    },
+    MODULE_IMPORT_TIMEOUT_MS,
+  );
+});

apps/gateway/src/main.ts

@@ -1,18 +1,5 @@
 #!/usr/bin/env node
-import { config } from 'dotenv';
+import './env.js';
-import { existsSync } from 'node:fs';
-import { resolve, join } from 'node:path';
-import { homedir } from 'node:os';
-
-// Load .env from daemon config dir (global install / daemon mode).
-// Loaded first so monorepo .env can override for local dev.
-const daemonEnv = join(homedir(), '.config', 'mosaic', 'gateway', '.env');
-if (existsSync(daemonEnv)) config({ path: daemonEnv });
-
-// Load .env from monorepo root (cwd is apps/gateway when run via pnpm filter)
-config({ path: resolve(process.cwd(), '../../.env') });
-config(); // Also load apps/gateway/.env if present (overrides)
-
 import './tracing.js';
 import 'reflect-metadata';
 import { NestFactory } from '@nestjs/core';
@@ -26,6 +13,7 @@ import { mountAuthHandler } from './auth/auth.controller.js';
 import { mountMcpHandler } from './mcp/mcp.controller.js';
 import { McpService } from './mcp/mcp.service.js';
 import { detectAndAssertTier, TierDetectionError } from '@mosaicstack/storage';
+import { resolveGatewayConfigPath } from './env.js';
 
 async function bootstrap(): Promise<void> {
   const logger = new Logger('Bootstrap');
@@ -37,7 +25,7 @@ async function bootstrap(): Promise<void> {
   // Pre-flight: assert all external services required by the configured tier
   // are reachable. Runs before NestFactory.create() so failures are visible
   // immediately with actionable remediation hints.
-  const mosaicConfig = loadConfig();
+  const mosaicConfig = loadConfig(resolveGatewayConfigPath());
   try {
     await detectAndAssertTier(mosaicConfig);
   } catch (err) {

apps/gateway/src/workspace/workspace.controller.spec.ts

@@ -0,0 +1,104 @@
+import 'reflect-metadata';
+import {
+  type CanActivate,
+  type ExecutionContext,
+  type INestApplication,
+  ValidationPipe,
+} from '@nestjs/common';
+import { FastifyAdapter, type NestFastifyApplication } from '@nestjs/platform-fastify';
+import { Test } from '@nestjs/testing';
+import request from 'supertest';
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { AuthGuard } from '../auth/auth.guard.js';
+import { ProjectBootstrapService } from './project-bootstrap.service.js';
+import { WorkspaceController } from './workspace.controller.js';
+
+const bootstrapMock = vi.fn(() =>
+  Promise.resolve({
+    projectId: 'project-1',
+    workspacePath: '/opt/mosaic/.workspaces/users/user-1/project-1',
+  }),
+);
+
+const authGuard: CanActivate = {
+  canActivate(context: ExecutionContext): boolean {
+    const requestContext = context.switchToHttp().getRequest<{ user?: { id: string } }>();
+    requestContext.user = { id: 'user-1' };
+    return true;
+  },
+};
+
+describe('POST /api/workspaces repoUrl validation', () => {
+  let app: INestApplication;
+
+  beforeAll(async () => {
+    const moduleRef = await Test.createTestingModule({
+      controllers: [WorkspaceController],
+      providers: [
+        {
+          provide: ProjectBootstrapService,
+          useValue: { bootstrap: bootstrapMock },
+        },
+      ],
+    })
+      .overrideGuard(AuthGuard)
+      .useValue(authGuard)
+      .compile();
+
+    app = moduleRef.createNestApplication<NestFastifyApplication>(new FastifyAdapter());
+    app.useGlobalPipes(
+      new ValidationPipe({
+        whitelist: true,
+        forbidNonWhitelisted: true,
+        transform: true,
+      }),
+    );
+    await app.init();
+    await app.getHttpAdapter().getInstance().ready();
+  });
+
+  beforeEach(() => {
+    bootstrapMock.mockClear();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  it.each([
+    ['a leading-dash value', '--upload-pack=sh -c id'],
+    ['an ext remote helper', 'ext::sh -c id'],
+    ['a file URL', 'file:///tmp/repository'],
+    ['an unparseable value', 'not a url'],
+    ['an SSH shorthand', '[email protected]:acme/repository.git'],
+    ['a scheme without //', 'https:example.com/acme/repository.git'],
+    ['a hostless git URL', 'git:///tmp/repository'],
+  ])('returns 400 for %s', async (_description, repoUrl) => {
+    const response = await request(app.getHttpServer())
+      .post('/api/workspaces')
+      .send({ name: 'Example', repoUrl })
+      .set('Content-Type', 'application/json');
+
+    expect(response.status).toBe(400);
+    expect(bootstrapMock).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ['a plain HTTPS repository URL', 'https://example.com/acme/repository.git'],
+    ['a git protocol repository URL', 'git://example.com/acme/repository.git'],
+  ])('accepts %s', async (_description, repoUrl) => {
+    const response = await request(app.getHttpServer())
+      .post('/api/workspaces')
+      .send({ name: 'Example', repoUrl })
+      .set('Content-Type', 'application/json');
+
+    expect(response.status).toBe(201);
+    expect(bootstrapMock).toHaveBeenCalledWith({
+      name: 'Example',
+      description: undefined,
+      userId: 'user-1',
+      teamId: undefined,
+      repoUrl,
+    });
+  });
+});

apps/gateway/src/workspace/workspace.controller.ts

@@ -1,7 +1,11 @@
 import { Body, Controller, Post, UseGuards } from '@nestjs/common';
 import { AuthGuard } from '../auth/auth.guard.js';
 import { CurrentUser } from '../auth/current-user.decorator.js';
-import { ProjectBootstrapService } from './project-bootstrap.service.js';
+import {
+  ProjectBootstrapService,
+  type BootstrapProjectResult,
+} from './project-bootstrap.service.js';
+import { CreateWorkspaceDto } from './workspace.dto.js';
 
 @Controller('api/workspaces')
 @UseGuards(AuthGuard)
@@ -11,20 +15,14 @@ export class WorkspaceController {
   @Post()
   async create(
     @CurrentUser() user: { id: string },
-    @Body()
+    @Body() dto: CreateWorkspaceDto,
-    body: {
+  ): Promise<BootstrapProjectResult> {
-      name: string;
-      description?: string;
-      teamId?: string;
-      repoUrl?: string;
-    },
-  ) {
     return this.bootstrap.bootstrap({
-      name: body.name,
+      name: dto.name,
-      description: body.description,
+      description: dto.description,
       userId: user.id,
-      teamId: body.teamId,
+      teamId: dto.teamId,
-      repoUrl: body.repoUrl,
+      repoUrl: dto.repoUrl,
     });
   }
 }

apps/gateway/src/workspace/workspace.dto.ts

@@ -0,0 +1,33 @@
+import { IsOptional, IsString, IsUrl, Matches, MaxLength } from 'class-validator';
+
+export class CreateWorkspaceDto {
+  @IsString()
+  @MaxLength(255)
+  name!: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(10_000)
+  description?: string;
+
+  @IsOptional()
+  @IsString()
+  teamId?: string;
+
+  @IsOptional()
+  @IsString()
+  @Matches(/^(?:https|git):\/\//i, {
+    message: 'repoUrl must be a valid https:// or git:// URL',
+  })
+  @IsUrl(
+    {
+      protocols: ['https', 'git'],
+      require_host: true,
+      require_protocol: true,
+      require_tld: false,
+      require_valid_protocol: true,
+    },
+    { message: 'repoUrl must be a valid https:// or git:// URL' },
+  )
+  repoUrl?: string;
+}

apps/gateway/src/workspace/workspace.service.spec.ts

@@ -1,11 +1,33 @@
-import { describe, it, expect, beforeEach } from 'vitest';
+import { BadRequestException } from '@nestjs/common';
-import { WorkspaceService } from './workspace.service.js';
+import fs from 'node:fs/promises';
+import os from 'node:os';
 import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { WorkspaceService } from './workspace.service.js';
+
+type ExecFileMock = (
+  command: string,
+  args: readonly string[],
+  options: { cwd: string },
+  callback: (error: Error | null, stdout: string, stderr: string) => void,
+) => void;
+
+const { execFileMock } = vi.hoisted(() => ({
+  execFileMock: vi.fn<ExecFileMock>(),
+}));
+
+vi.mock('node:child_process', () => ({
+  execFile: execFileMock,
+}));
 
 describe('WorkspaceService', () => {
   let service: WorkspaceService;
 
   beforeEach(() => {
+    execFileMock.mockReset();
+    execFileMock.mockImplementation((_command, _args, _options, callback) => {
+      callback(null, '', '');
+    });
     service = new WorkspaceService();
   });
 
@@ -76,4 +98,69 @@ describe('WorkspaceService', () => {
       }
     });
   });
+
+  describe('create', () => {
+    const project = {
+      id: 'project-1',
+      ownerType: 'user',
+      userId: 'user-1',
+      teamId: null,
+    } as const;
+
+    let originalRoot: string | undefined;
+    let temporaryRoot: string;
+
+    beforeEach(async () => {
+      originalRoot = process.env['MOSAIC_ROOT'];
+      temporaryRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'mosaic-workspace-'));
+      process.env['MOSAIC_ROOT'] = temporaryRoot;
+      service = new WorkspaceService();
+    });
+
+    afterEach(async () => {
+      if (originalRoot === undefined) {
+        delete process.env['MOSAIC_ROOT'];
+      } else {
+        process.env['MOSAIC_ROOT'] = originalRoot;
+      }
+      await fs.rm(temporaryRoot, { recursive: true, force: true });
+    });
+
+    it.each([
+      ['a leading-dash URL', '--upload-pack=sh -c id'],
+      ['an ext remote helper', 'ext::sh -c id'],
+      ['a file URL', 'file:///tmp/repository'],
+      ['an unparseable value', 'not a url'],
+      ['an SSH shorthand', '[email protected]:acme/repository.git'],
+      ['a scheme without //', 'https:example.com/acme/repository.git'],
+      ['a hostless git URL', 'git:///tmp/repository'],
+    ])('rejects %s before invoking git', async (_description, repoUrl) => {
+      await expect(service.create(project, repoUrl)).rejects.toBeInstanceOf(BadRequestException);
+      expect(execFileMock).not.toHaveBeenCalled();
+    });
+
+    it.each([
+      ['an HTTPS URL', 'https://example.com/acme/repository.git'],
+      ['a git protocol URL', 'git://example.com/acme/repository.git'],
+    ])('accepts %s and invokes hardened git clone arguments', async (_description, repoUrl) => {
+      const workspacePath = await service.create(project, repoUrl);
+
+      expect(execFileMock).toHaveBeenCalledOnce();
+      expect(execFileMock).toHaveBeenCalledWith(
+        'git',
+        [
+          '-c',
+          'protocol.ext.allow=never',
+          '-c',
+          'protocol.file.allow=never',
+          'clone',
+          '--',
+          repoUrl,
+          '.',
+        ],
+        { cwd: workspacePath },
+        expect.any(Function),
+      );
+    });
+  });
 });

apps/gateway/src/workspace/workspace.service.ts

@@ -1,10 +1,30 @@
-import { Injectable, Logger } from '@nestjs/common';
+import { BadRequestException, Injectable, Logger } from '@nestjs/common';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 
 const execFileAsync = promisify(execFile);
+const allowedRepositoryProtocols = new Set(['https:', 'git:']);
+const repositoryUrlPrefixPattern = /^(?:https|git):\/\//i;
+const repositoryUrlError = 'repoUrl must be a valid https:// or git:// URL';
+
+function assertAllowedRepositoryUrl(repoUrl: string): void {
+  if (repoUrl.startsWith('-') || !repositoryUrlPrefixPattern.test(repoUrl)) {
+    throw new BadRequestException(repositoryUrlError);
+  }
+
+  let parsedUrl: URL;
+  try {
+    parsedUrl = new URL(repoUrl);
+  } catch {
+    throw new BadRequestException(repositoryUrlError);
+  }
+
+  if (!allowedRepositoryProtocols.has(parsedUrl.protocol) || parsedUrl.hostname.length === 0) {
+    throw new BadRequestException(repositoryUrlError);
+  }
+}
 
 export interface WorkspaceProject {
   id: string;
@@ -39,14 +59,32 @@ export class WorkspaceService {
    * If repoUrl is provided, clone instead of init.
    */
   async create(project: WorkspaceProject, repoUrl?: string): Promise<string> {
+    if (repoUrl !== undefined) {
+      assertAllowedRepositoryUrl(repoUrl);
+    }
+
     const workspacePath = this.resolvePath(project);
 
     // Create directory
     await fs.mkdir(workspacePath, { recursive: true });
 
-    if (repoUrl) {
+    if (repoUrl !== undefined) {
-      // Clone existing repo
+      // Clone existing repo. Defense in depth keeps dangerous local helpers
-      await execFileAsync('git', ['clone', repoUrl, '.'], { cwd: workspacePath });
+      // disabled and terminates option parsing before positional arguments.
+      await execFileAsync(
+        'git',
+        [
+          '-c',
+          'protocol.ext.allow=never',
+          '-c',
+          'protocol.file.allow=never',
+          'clone',
+          '--',
+          repoUrl,
+          '.',
+        ],
+        { cwd: workspacePath },
+      );
       this.logger.log(`Cloned ${repoUrl} into workspace ${workspacePath}`);
     } else {
       // Init new git repo

apps/web/index.html

@@ -0,0 +1,30 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Mosaic</title>
+    <meta name="description" content="Mosaic Stack Dashboard" />
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      rel="stylesheet"
+      href="https://fonts.googleapis.com/css2?family=Outfit:wght@300;400;500;600;700&family=Fira+Code:wght@400;500&display=swap"
+    />
+    <script>
+      // set data-theme before first paint so the stored theme never flashes
+      (function () {
+        try {
+          var theme = window.localStorage.getItem('mosaic-theme') || 'dark';
+          document.documentElement.setAttribute('data-theme', theme === 'light' ? 'light' : 'dark');
+        } catch (error) {
+          document.documentElement.setAttribute('data-theme', 'dark');
+        }
+      })();
+    </script>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

apps/web/package.json

@@ -4,7 +4,9 @@
   "private": true,
   "scripts": {
     "build": "node ../../scripts/build-web.mjs",
+    "build:vite": "vite build",
     "dev": "next dev",
+    "dev:vite": "vite",
     "lint": "eslint src",
     "typecheck": "tsc --noEmit",
     "test": "vitest run --passWithNoTests",
@@ -19,6 +21,7 @@
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "react-markdown": "^10.1.0",
+    "react-router-dom": "^7.18.2",
     "socket.io-client": "^4.8.0",
     "tailwind-merge": "^3.5.0"
   },
@@ -28,9 +31,11 @@
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^6.0.5",
     "jsdom": "^29.0.0",
     "tailwindcss": "^4.0.0",
     "typescript": "^5.8.0",
-    "vitest": "^2.0.0"
+    "vite": "^8.2.1",
+    "vitest": "^3.2.7"
   }
 }

apps/web/src/app/auth/provider/[provider]/page.tsx

@@ -3,41 +3,56 @@
 import Link from 'next/link';
 import { useEffect, useState } from 'react';
 import { useParams, useSearchParams } from 'next/navigation';
+import { api } from '@/lib/api';
+import { resolveAuthCallbackURL } from '@/lib/auth-redirect';
 import { signIn } from '@/lib/auth-client';
-import { getSsoProvider } from '@/lib/sso-providers';
+import type { SsoProviderDiscovery } from '@/lib/sso';
 
 export default function AuthProviderRedirectPage(): React.ReactElement {
   const params = useParams<{ provider: string }>();
   const searchParams = useSearchParams();
   const providerId = typeof params.provider === 'string' ? params.provider : '';
-  const provider = getSsoProvider(providerId);
+  const requestedCallbackURL = searchParams.get('callbackURL');
-  const callbackURL = searchParams.get('callbackURL') ?? '/chat';
+  const [providerName, setProviderName] = useState<string | null>(null);
   const [error, setError] = useState<string | null>(null);
 
   useEffect(() => {
-    const currentProvider = provider;
-
-    if (!currentProvider) {
-      setError('Unknown SSO provider.');
-      return;
-    }
-
-    if (!currentProvider.enabled) {
-      setError(`${currentProvider.buttonLabel} is not enabled in this deployment.`);
-      return;
-    }
-
-    const activeProvider = currentProvider;
     let cancelled = false;
 
     async function redirectToProvider(): Promise<void> {
-      const result = await signIn.oauth2({
+      try {
-        providerId: activeProvider.id,
+        const callbackURL = resolveAuthCallbackURL(requestedCallbackURL, window.location.origin);
-        callbackURL,
+        const providers = await api<SsoProviderDiscovery[]>('/api/sso/providers');
-      });
+        if (cancelled) return;
 
-      if (!cancelled && result?.error) {
+        const provider = providers.find((candidate) => candidate.id === providerId);
-        setError(result.error.message ?? `${activeProvider.buttonLabel} sign in failed.`);
+        if (!provider) {
+          setError('Unknown SSO provider.');
+          return;
+        }
+
+        setProviderName(provider.name);
+        if (!provider.configured) {
+          setError(`${provider.name} is not enabled in this deployment.`);
+          return;
+        }
+        if (provider.loginMode !== 'oidc') {
+          setError(`${provider.name} is not available for OIDC sign in.`);
+          return;
+        }
+
+        const result = await signIn.oauth2({
+          providerId: provider.id,
+          callbackURL,
+        });
+
+        if (!cancelled && result?.error) {
+          setError(result.error.message ?? `${provider.name} sign in failed.`);
+        }
+      } catch (caught: unknown) {
+        if (!cancelled) {
+          setError(caught instanceof Error ? caught.message : 'Unable to start single sign-on.');
+        }
       }
     }
 
@@ -46,19 +61,22 @@ export default function AuthProviderRedirectPage(): React.ReactElement {
     return () => {
       cancelled = true;
     };
-  }, [callbackURL, provider]);
+  }, [providerId, requestedCallbackURL]);
 
   return (
     <div className="mx-auto flex min-h-[50vh] max-w-md flex-col justify-center">
       <h1 className="text-2xl font-semibold text-text-primary">Single sign-on</h1>
       <p className="mt-2 text-sm text-text-secondary">
-        {provider
+        {providerName
-          ? `Redirecting you to ${provider.buttonLabel.replace('Continue with ', '')}...`
+          ? `Redirecting you to ${providerName}...`
           : 'Preparing your sign-in request...'}
       </p>
 
       {error ? (
-        <div className="mt-6 rounded-lg border border-error/30 bg-error/10 px-4 py-3 text-sm text-error">
+        <div
+          role="alert"
+          className="mt-6 rounded-lg border border-error/30 bg-error/10 px-4 py-3 text-sm text-error"
+        >
           <p>{error}</p>
           <Link
             href="/login"

apps/web/src/lib/api.spec.ts

@@ -0,0 +1,57 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { api } from './api';
+
+describe('api', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it('fetches the supplied relative path with credentials and a JSON body', async () => {
+    const fetchMock = vi.fn<typeof fetch>();
+    fetchMock.mockResolvedValue(
+      new Response(JSON.stringify({ ok: true }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      }),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    await expect(
+      api<{ ok: boolean }>('/api/projects', {
+        method: 'POST',
+        body: { name: 'Mosaic' },
+      }),
+    ).resolves.toEqual({ ok: true });
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    expect(fetchMock).toHaveBeenCalledWith(
+      '/api/projects',
+      expect.objectContaining({
+        method: 'POST',
+        credentials: 'include',
+        body: JSON.stringify({ name: 'Mosaic' }),
+        headers: expect.objectContaining({
+          Accept: 'application/json',
+          'Content-Type': 'application/json',
+        }),
+      }),
+    );
+  });
+
+  it('throws the gateway JSON error with its statusCode', async () => {
+    const fetchMock = vi.fn<typeof fetch>();
+    fetchMock.mockResolvedValue(
+      new Response(JSON.stringify({ statusCode: 403, message: 'Forbidden' }), {
+        status: 403,
+        headers: { 'Content-Type': 'application/json' },
+      }),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    await expect(api('/api/admin/users')).rejects.toMatchObject({
+      name: 'Error',
+      message: 'Forbidden',
+      statusCode: 403,
+    });
+  });
+});

apps/web/src/lib/api.ts

@@ -1,5 +1,3 @@
-const GATEWAY_URL = process.env['NEXT_PUBLIC_GATEWAY_URL'] ?? 'http://localhost:14242';
-
 export interface ApiRequestInit extends Omit<RequestInit, 'body'> {
   body?: unknown;
 }
@@ -25,7 +23,7 @@ export async function api<T>(path: string, init?: ApiRequestInit): Promise<T> {
     headers['Content-Type'] = 'application/json';
   }
 
-  const res = await fetch(`${GATEWAY_URL}${path}`, {
+  const res = await fetch(path, {
     credentials: 'include',
     ...rest,
     headers,

apps/web/src/lib/auth-client.spec.ts

@@ -0,0 +1,29 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+describe('auth client origin contract', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.resetModules();
+  });
+
+  it('uses the same-origin BetterAuth mount at /api/auth', async () => {
+    const fetchMock = vi.fn<typeof fetch>();
+    fetchMock.mockResolvedValue(
+      new Response(JSON.stringify({ session: null, user: null }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      }),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    const { authClient } = await import('./auth-client');
+    await authClient.getSession();
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    const firstCall = fetchMock.mock.calls.at(0);
+    expect(firstCall).toBeDefined();
+    const requestURL = new URL(String(firstCall?.[0]), window.location.origin);
+    expect(requestURL.origin).toBe(window.location.origin);
+    expect(requestURL.pathname).toBe('/api/auth/get-session');
+  });
+});

apps/web/src/lib/auth-client.ts

@@ -1,8 +1,9 @@
 import { createAuthClient } from 'better-auth/react';
 import { adminClient, genericOAuthClient } from 'better-auth/client/plugins';
 
+// The gateway and BetterAuth client both use /api/auth. Omitting baseURL keeps
+// every browser request on the current origin in development and production.
 export const authClient = createAuthClient({
-  baseURL: process.env['NEXT_PUBLIC_GATEWAY_URL'] ?? 'http://localhost:14242',
   plugins: [adminClient(), genericOAuthClient()],
 });
 

apps/web/src/lib/auth-redirect.spec.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+import { resolveAuthCallbackURL } from './auth-redirect';
+
+const CURRENT_ORIGIN = 'https://mosaic.example';
+
+describe('resolveAuthCallbackURL', () => {
+  it('preserves a canonical same-origin path with search and hash', () => {
+    expect(resolveAuthCallbackURL('/projects?view=active#current', CURRENT_ORIGIN)).toBe(
+      '/projects?view=active#current',
+    );
+  });
+
+  it.each([
+    null,
+    'chat',
+    '//evil.example',
+    '/..//evil.com',
+    '/..//evil.com/x',
+    '/./..//evil.com',
+    '/../..//evil.com',
+    '/foo/..//evil.com',
+    '/\\evil.example',
+    '/\n//evil.example',
+    '/\r//evil.example',
+    '/\t//evil.example',
+    'https://evil.example/phish',
+  ])('falls back to chat for an unsafe callback target %#', (candidate) => {
+    expect(resolveAuthCallbackURL(candidate, CURRENT_ORIGIN)).toBe('/chat');
+  });
+});

apps/web/src/lib/auth-redirect.ts

@@ -0,0 +1,23 @@
+const DEFAULT_AUTH_CALLBACK_URL = '/chat';
+
+/**
+ * Return a canonical same-origin path for post-auth navigation.
+ *
+ * Parsing before comparing origins rejects protocol-relative URLs, backslash
+ * variants, and control characters that the WHATWG parser normalizes away.
+ */
+export function resolveAuthCallbackURL(candidate: string | null, currentOrigin: string): string {
+  if (!candidate?.startsWith('/')) return DEFAULT_AUTH_CALLBACK_URL;
+
+  try {
+    const expectedOrigin = new URL(currentOrigin).origin;
+    const resolved = new URL(candidate, expectedOrigin);
+    if (resolved.origin !== expectedOrigin || resolved.pathname.startsWith('//')) {
+      return DEFAULT_AUTH_CALLBACK_URL;
+    }
+
+    return `${resolved.pathname}${resolved.search}${resolved.hash}`;
+  } catch {
+    return DEFAULT_AUTH_CALLBACK_URL;
+  }
+}

apps/web/src/lib/socket.spec.ts

@@ -0,0 +1,52 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const { ioMock } = vi.hoisted(() => ({
+  ioMock: vi.fn(),
+}));
+
+vi.mock('socket.io-client', () => ({
+  io: ioMock,
+}));
+
+import { destroySocket, getSocket } from './socket';
+
+describe('chat socket', () => {
+  let disconnectHandler: (() => void) | undefined;
+
+  beforeEach(() => {
+    disconnectHandler = undefined;
+    ioMock.mockReset();
+
+    const mockSocket = {
+      on: vi.fn((event: string, handler: () => void) => {
+        if (event === 'disconnect') disconnectHandler = handler;
+        return mockSocket;
+      }),
+      offAny: vi.fn(() => mockSocket),
+      disconnect: vi.fn(() => mockSocket),
+    };
+
+    ioMock.mockReturnValue(mockSocket);
+  });
+
+  afterEach(() => {
+    destroySocket();
+  });
+
+  it('creates one same-origin /chat namespace socket until it disconnects', () => {
+    const first = getSocket();
+    const second = getSocket();
+
+    expect(first).toBe(second);
+    expect(ioMock).toHaveBeenCalledOnce();
+    expect(ioMock).toHaveBeenCalledWith('/chat', {
+      withCredentials: true,
+      autoConnect: false,
+      transports: ['websocket', 'polling'],
+    });
+
+    disconnectHandler?.();
+    getSocket();
+    expect(ioMock).toHaveBeenCalledTimes(2);
+  });
+});

apps/web/src/lib/socket.ts

@@ -1,12 +1,10 @@
 import { io, type Socket } from 'socket.io-client';
 
-const GATEWAY_URL = process.env['NEXT_PUBLIC_GATEWAY_URL'] ?? 'http://localhost:14242';
-
 let socket: Socket | null = null;
 
 export function getSocket(): Socket {
   if (!socket) {
-    socket = io(`${GATEWAY_URL}/chat`, {
+    socket = io('/chat', {
       withCredentials: true,
       autoConnect: false,
       transports: ['websocket', 'polling'],

apps/web/src/lib/sso-providers.test.ts

@@ -1,48 +0,0 @@
-import { afterEach, describe, expect, it, vi } from 'vitest';
-import { getEnabledSsoProviders, getSsoProvider } from './sso-providers';
-
-describe('sso-providers', () => {
-  afterEach(() => {
-    vi.unstubAllEnvs();
-  });
-
-  it('returns the enabled providers in login button order', () => {
-    vi.stubEnv('NEXT_PUBLIC_WORKOS_ENABLED', 'true');
-    vi.stubEnv('NEXT_PUBLIC_KEYCLOAK_ENABLED', 'true');
-
-    expect(getEnabledSsoProviders()).toEqual([
-      {
-        id: 'workos',
-        buttonLabel: 'Continue with WorkOS',
-        description: 'Enterprise SSO via WorkOS',
-        enabled: true,
-        href: '/auth/provider/workos',
-      },
-      {
-        id: 'keycloak',
-        buttonLabel: 'Continue with Keycloak',
-        description: 'Enterprise SSO via Keycloak',
-        enabled: true,
-        href: '/auth/provider/keycloak',
-      },
-    ]);
-  });
-
-  it('marks disabled providers without exposing them in the enabled list', () => {
-    vi.stubEnv('NEXT_PUBLIC_WORKOS_ENABLED', 'true');
-    vi.stubEnv('NEXT_PUBLIC_KEYCLOAK_ENABLED', 'false');
-
-    expect(getEnabledSsoProviders().map((provider) => provider.id)).toEqual(['workos']);
-    expect(getSsoProvider('keycloak')).toEqual({
-      id: 'keycloak',
-      buttonLabel: 'Continue with Keycloak',
-      description: 'Enterprise SSO via Keycloak',
-      enabled: false,
-      href: '/auth/provider/keycloak',
-    });
-  });
-
-  it('returns null for unknown providers', () => {
-    expect(getSsoProvider('authentik')).toBeNull();
-  });
-});

apps/web/src/lib/sso-providers.ts

@@ -1,53 +0,0 @@
-export type SsoProviderId = 'workos' | 'keycloak';
-
-export interface SsoProvider {
-  id: SsoProviderId;
-  buttonLabel: string;
-  description: string;
-  enabled: boolean;
-  href: string;
-}
-
-const PROVIDER_METADATA: Record<SsoProviderId, Omit<SsoProvider, 'enabled' | 'href'>> = {
-  workos: {
-    id: 'workos',
-    buttonLabel: 'Continue with WorkOS',
-    description: 'Enterprise SSO via WorkOS',
-  },
-  keycloak: {
-    id: 'keycloak',
-    buttonLabel: 'Continue with Keycloak',
-    description: 'Enterprise SSO via Keycloak',
-  },
-};
-
-export function getEnabledSsoProviders(): SsoProvider[] {
-  return (Object.keys(PROVIDER_METADATA) as SsoProviderId[])
-    .map((providerId) => getSsoProvider(providerId))
-    .filter((provider): provider is SsoProvider => provider?.enabled === true);
-}
-
-export function getSsoProvider(providerId: string): SsoProvider | null {
-  if (!isSsoProviderId(providerId)) {
-    return null;
-  }
-
-  return {
-    ...PROVIDER_METADATA[providerId],
-    enabled: isSsoProviderEnabled(providerId),
-    href: `/auth/provider/${providerId}`,
-  };
-}
-
-function isSsoProviderId(value: string): value is SsoProviderId {
-  return value === 'workos' || value === 'keycloak';
-}
-
-function isSsoProviderEnabled(providerId: SsoProviderId): boolean {
-  switch (providerId) {
-    case 'workos':
-      return process.env['NEXT_PUBLIC_WORKOS_ENABLED'] === 'true';
-    case 'keycloak':
-      return process.env['NEXT_PUBLIC_KEYCLOAK_ENABLED'] === 'true';
-  }
-}

apps/web/src/main.tsx

@@ -0,0 +1,19 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { RouterProvider } from 'react-router-dom';
+import { ThemeProvider } from '@/providers/theme-provider';
+import { createAppRouter } from '@/routes';
+import '@/app/globals.css';
+
+const container = document.getElementById('root');
+if (!container) {
+  throw new Error('missing #root element');
+}
+
+createRoot(container).render(
+  <StrictMode>
+    <ThemeProvider>
+      <RouterProvider router={createAppRouter()} />
+    </ThemeProvider>
+  </StrictMode>,
+);

apps/web/src/routes.tsx

@@ -0,0 +1,49 @@
+import type { ReactElement } from 'react';
+import { createBrowserRouter, Navigate, Outlet, type RouteObject } from 'react-router-dom';
+import { LoginPage } from '@/spa/pages/login';
+import { RegisterPage } from '@/spa/pages/register';
+import { SsoCallbackPage } from '@/spa/pages/sso-callback';
+import { AuthGuard, GuestGuard } from '@/spa/guards';
+import { Placeholder } from '@/spa/placeholder';
+
+function GuestLayout(): ReactElement {
+  return (
+    <div className="flex min-h-screen items-center justify-center bg-surface-bg px-4 py-8">
+      <div className="w-full max-w-md rounded-xl border border-surface-border bg-surface-card p-8 shadow-lg">
+        <Outlet />
+      </div>
+    </div>
+  );
+}
+
+export const routes: RouteObject[] = [
+  {
+    element: <GuestGuard />,
+    children: [
+      {
+        element: <GuestLayout />,
+        children: [
+          { path: '/login', element: <LoginPage /> },
+          { path: '/register', element: <RegisterPage /> },
+          { path: '/auth/provider/:provider', element: <SsoCallbackPage /> },
+        ],
+      },
+    ],
+  },
+  {
+    element: <AuthGuard />,
+    children: [
+      { path: '/', element: <Navigate to="/chat" replace /> },
+      { path: '/chat', element: <Placeholder title="Chat" /> },
+      { path: '/projects', element: <Placeholder title="Projects" /> },
+      { path: '/projects/:id', element: <Placeholder title="Project" /> },
+      { path: '/tasks', element: <Placeholder title="Tasks" /> },
+      { path: '/settings', element: <Placeholder title="Settings" /> },
+      { path: '/admin', element: <Placeholder title="Admin" /> },
+    ],
+  },
+];
+
+export function createAppRouter(): ReturnType<typeof createBrowserRouter> {
+  return createBrowserRouter(routes);
+}

apps/web/src/spa/guards.spec.tsx

@@ -0,0 +1,135 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { createMemoryRouter, RouterProvider, type RouteObject } from 'react-router-dom';
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
+
+const { useSessionMock } = vi.hoisted(() => ({
+  useSessionMock: vi.fn(),
+}));
+
+vi.mock('@/lib/auth-client', () => ({
+  useSession: useSessionMock,
+}));
+
+import { AuthGuard, GuestGuard } from './guards';
+
+interface RenderedRouter {
+  container: HTMLDivElement;
+  router: ReturnType<typeof createMemoryRouter>;
+}
+
+const mountedRoots: Root[] = [];
+
+beforeAll(() => {
+  Object.defineProperty(globalThis, 'IS_REACT_ACT_ENVIRONMENT', {
+    configurable: true,
+    value: true,
+  });
+});
+
+afterAll(() => {
+  Reflect.deleteProperty(globalThis, 'IS_REACT_ACT_ENVIRONMENT');
+});
+
+async function renderRouter(
+  routeObjects: RouteObject[],
+  initialEntry: string,
+): Promise<RenderedRouter> {
+  const container = document.createElement('div');
+  document.body.append(container);
+  const router = createMemoryRouter(routeObjects, { initialEntries: [initialEntry] });
+  const root = createRoot(container);
+  mountedRoots.push(root);
+
+  await act(async () => {
+    root.render(<RouterProvider router={router} />);
+  });
+
+  return { container, router };
+}
+
+afterEach(async () => {
+  for (const root of mountedRoots.splice(0)) {
+    await act(async () => {
+      root.unmount();
+    });
+  }
+  document.body.replaceChildren();
+  useSessionMock.mockReset();
+});
+
+const guestRoutes: RouteObject[] = [
+  {
+    path: '/login',
+    element: <GuestGuard />,
+    children: [{ index: true, element: <p>Guest page</p> }],
+  },
+  { path: '/chat', element: <p>Chat page</p> },
+];
+
+const authenticatedRoutes: RouteObject[] = [
+  {
+    path: '/chat',
+    element: <AuthGuard />,
+    children: [{ index: true, element: <p>Private page</p> }],
+  },
+  { path: '/login', element: <p>Login page</p> },
+];
+
+describe('GuestGuard', () => {
+  it('renders the guest outlet while session lookup is pending', async () => {
+    useSessionMock.mockReturnValue({ data: null, isPending: true });
+
+    const view = await renderRouter(guestRoutes, '/login');
+
+    expect(view.container.textContent).toContain('Guest page');
+    expect(view.router.state.location.pathname).toBe('/login');
+  });
+
+  it('renders the guest outlet when no session exists', async () => {
+    useSessionMock.mockReturnValue({ data: null, isPending: false });
+
+    const view = await renderRouter(guestRoutes, '/login');
+
+    expect(view.container.textContent).toContain('Guest page');
+    expect(view.router.state.location.pathname).toBe('/login');
+  });
+
+  it('redirects an authenticated session to chat', async () => {
+    useSessionMock.mockReturnValue({ data: { user: { id: 'user-1' } }, isPending: false });
+
+    const view = await renderRouter(guestRoutes, '/login');
+
+    expect(view.container.textContent).toContain('Chat page');
+    expect(view.router.state.location.pathname).toBe('/chat');
+  });
+});
+
+describe('AuthGuard', () => {
+  it('renders the existing loading treatment while session lookup is pending', async () => {
+    useSessionMock.mockReturnValue({ data: null, isPending: true });
+
+    const view = await renderRouter(authenticatedRoutes, '/chat');
+
+    expect(view.container.textContent).toContain('Loading...');
+    expect(view.router.state.location.pathname).toBe('/chat');
+  });
+
+  it('redirects an unauthenticated visitor to login', async () => {
+    useSessionMock.mockReturnValue({ data: null, isPending: false });
+
+    const view = await renderRouter(authenticatedRoutes, '/chat');
+
+    expect(view.container.textContent).toContain('Login page');
+    expect(view.router.state.location.pathname).toBe('/login');
+  });
+
+  it('renders the authenticated outlet when a session exists', async () => {
+    useSessionMock.mockReturnValue({ data: { user: { id: 'user-1' } }, isPending: false });
+
+    const view = await renderRouter(authenticatedRoutes, '/chat');
+
+    expect(view.container.textContent).toContain('Private page');
+    expect(view.router.state.location.pathname).toBe('/chat');
+  });
+});

apps/web/src/spa/guards.tsx

@@ -0,0 +1,23 @@
+import type { ReactElement } from 'react';
+import { Navigate, Outlet } from 'react-router-dom';
+import { useSession } from '@/lib/auth-client';
+
+export function GuestGuard(): ReactElement {
+  const { data: session } = useSession();
+
+  return session ? <Navigate to="/chat" replace /> : <Outlet />;
+}
+
+export function AuthGuard(): ReactElement {
+  const { data: session, isPending } = useSession();
+
+  if (isPending) {
+    return (
+      <div className="flex min-h-screen items-center justify-center">
+        <div className="text-sm text-text-muted">Loading...</div>
+      </div>
+    );
+  }
+
+  return session ? <Outlet /> : <Navigate to="/login" replace />;
+}

apps/web/src/spa/pages/login.tsx

@@ -0,0 +1,152 @@
+import { useEffect, useState, type FormEvent, type ReactElement } from 'react';
+import { Link, useNavigate } from 'react-router-dom';
+import { SsoProviderButtons } from '@/components/auth/sso-provider-buttons';
+import { api } from '@/lib/api';
+import { authClient, signIn } from '@/lib/auth-client';
+import type { SsoProviderDiscovery } from '@/lib/sso';
+
+export function LoginPage(): ReactElement {
+  const navigate = useNavigate();
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [ssoProviders, setSsoProviders] = useState<SsoProviderDiscovery[]>([]);
+  const [ssoLoadingProviderId, setSsoLoadingProviderId] = useState<
+    SsoProviderDiscovery['id'] | null
+  >(null);
+
+  useEffect(() => {
+    let active = true;
+
+    void api<SsoProviderDiscovery[]>('/api/sso/providers').then(
+      (providers) => {
+        if (active) setSsoProviders(providers.filter((provider) => provider.configured));
+      },
+      () => {
+        if (active) setSsoProviders([]);
+      },
+    );
+
+    return () => {
+      active = false;
+    };
+  }, []);
+
+  async function handleSubmit(event: FormEvent<HTMLFormElement>): Promise<void> {
+    event.preventDefault();
+    setError(null);
+    setLoading(true);
+
+    const form = new FormData(event.currentTarget);
+    const email = String(form.get('email') ?? '');
+    const password = String(form.get('password') ?? '');
+
+    try {
+      const result = await signIn.email({ email, password });
+
+      if (result.error) {
+        setError(result.error.message ?? 'Sign in failed');
+        return;
+      }
+
+      navigate('/chat', { replace: true });
+    } catch (caught: unknown) {
+      setError(caught instanceof Error ? caught.message : 'Sign in failed');
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  async function handleSsoSignIn(providerId: SsoProviderDiscovery['id']): Promise<void> {
+    setError(null);
+    setSsoLoadingProviderId(providerId);
+
+    try {
+      const result = await authClient.signIn.oauth2({
+        providerId,
+        callbackURL: '/chat',
+        newUserCallbackURL: '/chat',
+      });
+
+      if (result.error) {
+        setError(result.error.message ?? `Sign in with ${providerId} failed`);
+        setSsoLoadingProviderId(null);
+      }
+    } catch (caught: unknown) {
+      setError(caught instanceof Error ? caught.message : `Sign in with ${providerId} failed`);
+      setSsoLoadingProviderId(null);
+    }
+  }
+
+  return (
+    <div>
+      <h1 className="text-2xl font-semibold">Sign in</h1>
+      <p className="mt-1 text-sm text-text-secondary">Sign in to your Mosaic account</p>
+
+      {error ? (
+        <div
+          role="alert"
+          className="mt-4 rounded-lg border border-error/30 bg-error/10 px-4 py-3 text-sm text-error"
+        >
+          {error}
+        </div>
+      ) : null}
+
+      <form className="mt-6 space-y-4" onSubmit={handleSubmit}>
+        <div>
+          <label htmlFor="email" className="block text-sm font-medium text-text-secondary">
+            Email
+          </label>
+          <input
+            id="email"
+            name="email"
+            type="email"
+            autoComplete="email"
+            required
+            disabled={loading}
+            className="mt-1 block w-full rounded-lg border border-surface-border bg-surface-elevated px-3 py-2 text-sm text-text-primary placeholder:text-text-muted focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500 disabled:opacity-50"
+            placeholder="[email protected]"
+          />
+        </div>
+
+        <div>
+          <label htmlFor="password" className="block text-sm font-medium text-text-secondary">
+            Password
+          </label>
+          <input
+            id="password"
+            name="password"
+            type="password"
+            autoComplete="current-password"
+            required
+            disabled={loading}
+            className="mt-1 block w-full rounded-lg border border-surface-border bg-surface-elevated px-3 py-2 text-sm text-text-primary placeholder:text-text-muted focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500 disabled:opacity-50"
+            placeholder="••••••••"
+          />
+        </div>
+
+        <button
+          type="submit"
+          disabled={loading}
+          className="w-full rounded-lg bg-blue-600 px-4 py-2.5 text-sm font-medium text-white transition-colors hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 focus:ring-offset-surface-card disabled:opacity-50"
+        >
+          {loading ? 'Signing in...' : 'Sign in'}
+        </button>
+      </form>
+
+      <SsoProviderButtons
+        providers={ssoProviders}
+        loadingProviderId={ssoLoadingProviderId}
+        onOidcSignIn={(providerId) => {
+          void handleSsoSignIn(providerId);
+        }}
+      />
+
+      <p className="mt-4 text-center text-sm text-text-muted">
+        Don&apos;t have an account?{' '}
+        <Link to="/register" className="text-blue-400 hover:text-blue-300">
+          Sign up
+        </Link>
+      </p>
+    </div>
+  );
+}

apps/web/src/spa/pages/register.tsx

@@ -0,0 +1,116 @@
+import { useState, type FormEvent, type ReactElement } from 'react';
+import { Link, useNavigate } from 'react-router-dom';
+import { signUp } from '@/lib/auth-client';
+
+export function RegisterPage(): ReactElement {
+  const navigate = useNavigate();
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState(false);
+
+  async function handleSubmit(event: FormEvent<HTMLFormElement>): Promise<void> {
+    event.preventDefault();
+    setError(null);
+    setLoading(true);
+
+    const form = new FormData(event.currentTarget);
+    const name = String(form.get('name') ?? '');
+    const email = String(form.get('email') ?? '');
+    const password = String(form.get('password') ?? '');
+
+    try {
+      const result = await signUp.email({ name, email, password });
+
+      if (result.error) {
+        setError(result.error.message ?? 'Registration failed');
+        return;
+      }
+
+      navigate('/chat', { replace: true });
+    } catch (caught: unknown) {
+      setError(caught instanceof Error ? caught.message : 'Registration failed');
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  return (
+    <div>
+      <h1 className="text-2xl font-semibold">Create account</h1>
+      <p className="mt-1 text-sm text-text-secondary">Get started with Mosaic</p>
+
+      {error ? (
+        <div
+          role="alert"
+          className="mt-4 rounded-lg border border-error/30 bg-error/10 px-4 py-3 text-sm text-error"
+        >
+          {error}
+        </div>
+      ) : null}
+
+      <form className="mt-6 space-y-4" onSubmit={handleSubmit}>
+        <div>
+          <label htmlFor="name" className="block text-sm font-medium text-text-secondary">
+            Name
+          </label>
+          <input
+            id="name"
+            name="name"
+            type="text"
+            autoComplete="name"
+            required
+            disabled={loading}
+            className="mt-1 block w-full rounded-lg border border-surface-border bg-surface-elevated px-3 py-2 text-sm text-text-primary placeholder:text-text-muted focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500 disabled:opacity-50"
+            placeholder="Your name"
+          />
+        </div>
+
+        <div>
+          <label htmlFor="email" className="block text-sm font-medium text-text-secondary">
+            Email
+          </label>
+          <input
+            id="email"
+            name="email"
+            type="email"
+            autoComplete="email"
+            required
+            disabled={loading}
+            className="mt-1 block w-full rounded-lg border border-surface-border bg-surface-elevated px-3 py-2 text-sm text-text-primary placeholder:text-text-muted focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500 disabled:opacity-50"
+            placeholder="[email protected]"
+          />
+        </div>
+
+        <div>
+          <label htmlFor="password" className="block text-sm font-medium text-text-secondary">
+            Password
+          </label>
+          <input
+            id="password"
+            name="password"
+            type="password"
+            autoComplete="new-password"
+            required
+            disabled={loading}
+            className="mt-1 block w-full rounded-lg border border-surface-border bg-surface-elevated px-3 py-2 text-sm text-text-primary placeholder:text-text-muted focus:border-blue-500 focus:outline-none focus:ring-1 focus:ring-blue-500 disabled:opacity-50"
+            placeholder="••••••••"
+          />
+        </div>
+
+        <button
+          type="submit"
+          disabled={loading}
+          className="w-full rounded-lg bg-blue-600 px-4 py-2.5 text-sm font-medium text-white transition-colors hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 focus:ring-offset-surface-card disabled:opacity-50"
+        >
+          {loading ? 'Creating account...' : 'Create account'}
+        </button>
+      </form>
+
+      <p className="mt-4 text-center text-sm text-text-muted">
+        Already have an account?{' '}
+        <Link to="/login" className="text-blue-400 hover:text-blue-300">
+          Sign in
+        </Link>
+      </p>
+    </div>
+  );
+}

apps/web/src/spa/pages/sso-callback.spec.tsx

@@ -0,0 +1,90 @@
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { createMemoryRouter, RouterProvider } from 'react-router-dom';
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const { apiMock, oauth2Mock } = vi.hoisted(() => ({
+  apiMock: vi.fn(),
+  oauth2Mock: vi.fn(),
+}));
+
+vi.mock('@/lib/api', () => ({
+  api: apiMock,
+}));
+
+vi.mock('@/lib/auth-client', () => ({
+  signIn: { oauth2: oauth2Mock },
+}));
+
+import { SsoCallbackPage } from './sso-callback';
+
+const mountedRoots: Root[] = [];
+
+beforeAll(() => {
+  Object.defineProperty(globalThis, 'IS_REACT_ACT_ENVIRONMENT', {
+    configurable: true,
+    value: true,
+  });
+});
+
+beforeEach(() => {
+  apiMock.mockResolvedValue([
+    {
+      id: 'authentik',
+      name: 'Authentik',
+      protocols: ['oidc'],
+      configured: true,
+      loginMode: 'oidc',
+      callbackPath: '/api/auth/oauth2/callback/authentik',
+      teamSync: { enabled: false, claim: null },
+      samlFallback: { configured: false, loginUrl: null },
+      warnings: [],
+    },
+  ]);
+  oauth2Mock.mockResolvedValue({ data: null, error: null });
+});
+
+afterEach(async () => {
+  for (const root of mountedRoots.splice(0)) {
+    await act(async () => {
+      root.unmount();
+    });
+  }
+  document.body.replaceChildren();
+  apiMock.mockReset();
+  oauth2Mock.mockReset();
+});
+
+afterAll(() => {
+  Reflect.deleteProperty(globalThis, 'IS_REACT_ACT_ENVIRONMENT');
+});
+
+describe('SsoCallbackPage', () => {
+  it('rejects a control-character callback that normalizes to an external origin', async () => {
+    const router = createMemoryRouter(
+      [
+        {
+          path: '/auth/provider/:provider',
+          element: <SsoCallbackPage />,
+        },
+      ],
+      {
+        initialEntries: ['/auth/provider/authentik?callbackURL=%2F%0A%2F%2Fevil.example'],
+      },
+    );
+    const container = document.createElement('div');
+    document.body.append(container);
+    const root = createRoot(container);
+    mountedRoots.push(root);
+
+    await act(async () => {
+      root.render(<RouterProvider router={router} />);
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    });
+
+    expect(oauth2Mock).toHaveBeenCalledWith({
+      providerId: 'authentik',
+      callbackURL: '/chat',
+    });
+  });
+});

apps/web/src/spa/pages/sso-callback.tsx

@@ -0,0 +1,91 @@
+import { useEffect, useState, type ReactElement } from 'react';
+import { Link, useParams, useSearchParams } from 'react-router-dom';
+import { api } from '@/lib/api';
+import { resolveAuthCallbackURL } from '@/lib/auth-redirect';
+import { signIn } from '@/lib/auth-client';
+import type { SsoProviderDiscovery } from '@/lib/sso';
+
+export function SsoCallbackPage(): ReactElement {
+  const { provider: providerId = '' } = useParams<'provider'>();
+  const [searchParams] = useSearchParams();
+  const requestedCallbackURL = searchParams.get('callbackURL');
+  const [providerName, setProviderName] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    async function redirectToProvider(): Promise<void> {
+      try {
+        const callbackURL = resolveAuthCallbackURL(requestedCallbackURL, window.location.origin);
+        const providers = await api<SsoProviderDiscovery[]>('/api/sso/providers');
+        if (cancelled) return;
+
+        const provider = providers.find((candidate) => candidate.id === providerId);
+        if (!provider) {
+          setError('Unknown SSO provider.');
+          return;
+        }
+
+        setProviderName(provider.name);
+        if (!provider.configured) {
+          setError(`${provider.name} is not enabled in this deployment.`);
+          return;
+        }
+        if (provider.loginMode !== 'oidc') {
+          setError(`${provider.name} is not available for OIDC sign in.`);
+          return;
+        }
+
+        const result = await signIn.oauth2({
+          providerId: provider.id,
+          callbackURL,
+        });
+
+        if (!cancelled && result?.error) {
+          setError(result.error.message ?? `${provider.name} sign in failed.`);
+        }
+      } catch (caught: unknown) {
+        if (!cancelled) {
+          setError(caught instanceof Error ? caught.message : 'Unable to start single sign-on.');
+        }
+      }
+    }
+
+    void redirectToProvider();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [providerId, requestedCallbackURL]);
+
+  return (
+    <div className="mx-auto flex min-h-[50vh] max-w-md flex-col justify-center">
+      <h1 className="text-2xl font-semibold text-text-primary">Single sign-on</h1>
+      <p className="mt-2 text-sm text-text-secondary">
+        {providerName
+          ? `Redirecting you to ${providerName}...`
+          : 'Preparing your sign-in request...'}
+      </p>
+
+      {error ? (
+        <div
+          role="alert"
+          className="mt-6 rounded-lg border border-error/30 bg-error/10 px-4 py-3 text-sm text-error"
+        >
+          <p>{error}</p>
+          <Link
+            to="/login"
+            className="mt-3 inline-block font-medium text-blue-400 hover:text-blue-300"
+          >
+            Return to login
+          </Link>
+        </div>
+      ) : (
+        <div className="mt-6 rounded-lg border border-surface-border bg-surface-elevated px-4 py-3 text-sm text-text-secondary">
+          If the redirect does not start automatically, return to the login page and try again.
+        </div>
+      )}
+    </div>
+  );
+}

apps/web/src/spa/placeholder.tsx

@@ -0,0 +1,9 @@
+import type { ReactElement } from 'react';
+
+export function Placeholder({ title }: { title: string }): ReactElement {
+  return (
+    <main className="flex min-h-screen items-center justify-center">
+      <h1 className="text-xl font-medium">{title}</h1>
+    </main>
+  );
+}

apps/web/src/spa/routes.spec.tsx

@@ -0,0 +1,58 @@
+import { isValidElement } from 'react';
+import { describe, expect, it } from 'vitest';
+import type { RouteObject } from 'react-router-dom';
+import { routes } from '@/routes';
+import { Placeholder } from '@/spa/placeholder';
+
+function collectPaths(routeObjects: RouteObject[]): string[] {
+  return routeObjects.flatMap((route) => [
+    ...(route.path ? [route.path] : []),
+    ...(route.children ? collectPaths(route.children) : []),
+  ]);
+}
+
+function findRoute(routeObjects: RouteObject[], path: string): RouteObject | undefined {
+  for (const route of routeObjects) {
+    if (route.path === path) return route;
+    const nested = route.children ? findRoute(route.children, path) : undefined;
+    if (nested) return nested;
+  }
+  return undefined;
+}
+
+describe('SPA route table', () => {
+  it('covers every v1 parity route from the Phase P RFC', () => {
+    expect(collectPaths(routes).sort()).toEqual(
+      [
+        '/',
+        '/admin',
+        '/auth/provider/:provider',
+        '/chat',
+        '/login',
+        '/projects',
+        '/projects/:id',
+        '/register',
+        '/settings',
+        '/tasks',
+      ].sort(),
+    );
+  });
+
+  it('separates guest and authenticated route groups', () => {
+    const guestPaths = collectPaths(routes.at(0)?.children ?? []);
+    const authPaths = collectPaths(routes.at(1)?.children ?? []);
+    expect(guestPaths).toContain('/login');
+    expect(guestPaths).not.toContain('/chat');
+    expect(authPaths).toContain('/chat');
+  });
+
+  it.each(['/login', '/register', '/auth/provider/:provider'])(
+    'renders a real guest page instead of the P1 placeholder at %s',
+    (path) => {
+      const element = findRoute(routes, path)?.element;
+      expect(isValidElement(element)).toBe(true);
+      if (!isValidElement(element)) throw new Error(`Missing route element for ${path}`);
+      expect(element.type).not.toBe(Placeholder);
+    },
+  );
+});

apps/web/src/test/setup.spec.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest';
+
+describe('Vitest abort-controller realm', () => {
+  it('provides a global signal accepted by Node native Request', () => {
+    const controller = new AbortController();
+    const request = new Request('https://mosaic.invalid/navigation', {
+      signal: controller.signal,
+    });
+
+    expect(request.signal).toBeInstanceOf(AbortSignal);
+    controller.abort();
+    expect(request.signal.aborted).toBe(true);
+  });
+});

apps/web/src/test/setup.ts

@@ -0,0 +1,23 @@
+import { transferableAbortController } from 'node:util';
+
+// jsdom installs realm-local abort constructors while Node's undici Request
+// remains native. React Router passes a global AbortSignal to Request, so both
+// constructors must come from Node's native realm during tests.
+const nativeController = transferableAbortController();
+const nativeAbortController = nativeController.constructor;
+const nativeAbortSignal = nativeController.signal.constructor;
+
+for (const target of [globalThis, window]) {
+  Object.defineProperties(target, {
+    AbortController: {
+      configurable: true,
+      writable: true,
+      value: nativeAbortController,
+    },
+    AbortSignal: {
+      configurable: true,
+      writable: true,
+      value: nativeAbortSignal,
+    },
+  });
+}

apps/web/vite.config.ts

@@ -0,0 +1,24 @@
+import { fileURLToPath } from 'node:url';
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
+
+// The proxy exists only in dev; in production the SPA is same-origin with the gateway
+// (served by it under Candidate A, or behind one FQDN under Candidate B) and every
+// request uses a relative path, so no origin may ever be configured here or in src/.
+const gatewayTarget = 'http://localhost:14242';
+
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: {
+      '@': fileURLToPath(new URL('./src', import.meta.url)),
+    },
+  },
+  server: {
+    port: 3100,
+    proxy: {
+      '/api': gatewayTarget,
+      '/socket.io': { target: gatewayTarget, ws: true },
+    },
+  },
+});

apps/web/vitest.config.ts

@@ -1,9 +1,21 @@
+import { fileURLToPath } from 'node:url';
 import { defineConfig } from 'vitest/config';
 
 export default defineConfig({
+  resolve: {
+    alias: {
+      '@': fileURLToPath(new URL('./src', import.meta.url)),
+    },
+  },
+  // tsconfig uses "jsx": "preserve" for Next; tests need esbuild to compile it
+  esbuild: {
+    jsx: 'automatic',
+  },
   test: {
     globals: true,
     environment: 'jsdom',
+    setupFiles: ['./src/test/setup.ts'],
+    isolate: true,
     exclude: ['e2e/**', 'node_modules/**'],
   },
 });

docker/gateway.Dockerfile

@@ -10,6 +10,8 @@ COPY pnpm-workspace.yaml pnpm-lock.yaml package.json ./
 COPY apps/gateway/package.json ./apps/gateway/
 COPY packages/ ./packages/
 COPY plugins/ ./plugins/
+# the root prepare script runs scripts/install-hooks.mjs on install
+COPY scripts/ ./scripts/
 RUN pnpm install --frozen-lockfile
 COPY . .
 # Build gateway and all of its workspace dependencies via turbo dependency graph
@@ -21,11 +23,22 @@ RUN pnpm --filter @mosaicstack/gateway --prod deploy --legacy /deploy
 FROM base AS runner
 WORKDIR /app
 ENV NODE_ENV=production
+# WorkspaceService shells out to git at runtime and roots workspaces at
+# $MOSAIC_ROOT/.workspaces (apps/gateway/src/workspace/workspace.service.ts);
+# mount a volume over /opt/mosaic to persist workspaces across container restarts.
+# Intentionally unpinned: Alpine's signed repository is the trust anchor; pinning
+# git was declined so routine base-image security updates remain maintainable.
+RUN apk add --no-cache git \
+  && mkdir -p /opt/mosaic/.workspaces \
+  && chown -R node:node /opt/mosaic /app
+ENV MOSAIC_ROOT=/opt/mosaic
 # Use the pnpm deploy output — resolves all deps into a flat, self-contained node_modules
-COPY --from=builder /deploy/node_modules ./node_modules
+COPY --chown=node:node --from=builder /deploy/node_modules ./node_modules
-COPY --from=builder /deploy/package.json ./package.json
+COPY --chown=node:node --from=builder /deploy/package.json ./package.json
 # dist is declared in package.json "files" so pnpm deploy copies it into /deploy;
 # copy from builder explicitly as belt-and-suspenders
-COPY --from=builder /app/apps/gateway/dist ./dist
+COPY --chown=node:node --from=builder /app/apps/gateway/dist ./dist
-EXPOSE 4000
+# gateway defaults to port 14242 (apps/gateway/src/main.ts)
+EXPOSE 14242
+USER node
 CMD ["node", "dist/main.js"]

docker/web.Dockerfile

@@ -8,9 +8,11 @@ WORKDIR /app
 COPY pnpm-workspace.yaml pnpm-lock.yaml package.json ./
 COPY apps/web/package.json ./apps/web/
 COPY packages/ ./packages/
+# the root prepare script runs scripts/install-hooks.mjs on install
+COPY scripts/ ./scripts/
 RUN pnpm install --frozen-lockfile
 COPY . .
-RUN pnpm --filter @mosaic/web build
+RUN pnpm --filter @mosaicstack/web build
 
 FROM base AS runner
 WORKDIR /app

docs/plans/2026-08-10-ci-queue-purpose-design.md

@@ -0,0 +1,33 @@
+# CI Queue Guard Purpose Semantics
+
+- **Issue:** #1146
+- **Target branch:** `next`
+
+## Problem
+
+`ci-queue-wait.sh` treats any result other than terminal success as asserted non-readiness. That is correct for merge readiness, but incorrect for the pre-push queue guard: a terminal failure or an empty status set means no pipeline is queued or running, so the queue is clear.
+
+## Design
+
+Make final-state handling purpose-sensitive while preserving the existing provider and payload safeguards:
+
+- `--purpose push`
+  - wait while state is `pending`;
+  - return success for `terminal-success`, `terminal-failure`, and `no-status`;
+  - continue rejecting `malformed`, `unknown`, and unrecognized states.
+- `--purpose merge`
+  - return success only for `terminal-success`;
+  - continue rejecting `terminal-failure`, `no-status`, malformed, unknown, and unrecognized states.
+- `--require-status` remains authoritative: `no-status` fails for either purpose when it is supplied.
+
+Diagnostics will explicitly distinguish a queue-clear push result from successful CI so callers cannot mistake an old failure for a green pipeline.
+
+## Testing
+
+Extend the process-level tri-state regression harness with separate push and merge assertions:
+
+1. Push passes for terminal success, terminal failure, and no status.
+2. Push still fails for pending, malformed, and unknown states.
+3. `--require-status` makes push/no-status fail.
+4. Merge behavior remains fail-closed except for terminal success.
+5. Existing provider-unavailable audit behavior remains unchanged.

docs/plans/2026-08-10-ci-queue-purpose-implementation.md

@@ -0,0 +1,208 @@
+# CI Queue Guard Purpose Semantics Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Make the pre-push CI queue guard pass when no pipeline is queued or running while preserving fail-closed merge readiness.
+
+**Architecture:** Keep provider lookup and tri-state classification unchanged. Make only the final state dispatch purpose-sensitive: push treats valid non-pending states as queue-clear, while merge continues to require terminal success. Preserve `--require-status`, malformed-payload rejection, unknown-state rejection, and audited provider-unavailable behavior.
+
+**Tech Stack:** Bash, process-level shell regression harnesses, Gitea/GitHub status APIs.
+
+---
+
+### Task 1: Freeze Purpose-Specific State Semantics
+
+**Files:**
+
+- Modify: `packages/mosaic/framework/tools/git/test-ci-queue-wait-tristate.sh`
+- Test: `packages/mosaic/framework/tools/git/test-ci-queue-wait-tristate.sh`
+
+**Step 1: Add failing push assertions**
+
+Change push expectations so `terminal-failure` and `no-status` require exit 0 plus an explicit `queue-clear` diagnostic. Add a `--require-status` assertion that keeps push/no-status non-zero.
+
+**Step 2: Add failing merge assertions**
+
+Invoke the same harness with `MOSAIC_TEST_PURPOSE=merge` and assert terminal failure and no status remain non-zero while terminal success remains zero.
+
+**Step 3: Add unknown-state coverage**
+
+Add a stub payload with a syntactically valid but unsupported status value and assert both purposes reject it.
+
+**Step 4: Run the focused test and verify RED**
+
+Run:
+
+```bash
+bash packages/mosaic/framework/tools/git/test-ci-queue-wait-tristate.sh
+```
+
+Expected: failures showing push terminal-failure and no-status returned exit 3 instead of exit 0 or lacked `queue-clear` diagnostics.
+
+**Step 5: Commit the failing tests**
+
+```bash
+git add packages/mosaic/framework/tools/git/test-ci-queue-wait-tristate.sh
+git commit -m "test(ci): define purpose-aware queue readiness"
+```
+
+### Task 2: Implement Purpose-Sensitive Final-State Dispatch
+
+**Files:**
+
+- Modify: `packages/mosaic/framework/tools/git/ci-queue-wait.sh:458-481`
+- Test: `packages/mosaic/framework/tools/git/test-ci-queue-wait-tristate.sh`
+- Test: `packages/mosaic/framework/tools/git/test-ci-queue-wait-github-checks.sh`
+
+**Step 1: Implement push queue-clear behavior**
+
+For `no-status`, retain the existing `--require-status` failure. Otherwise, return success for push with an explicit diagnostic such as:
+
+```text
+[ci-queue-wait] queue-clear state=no-status purpose=push branch=<branch>; no queued or running CI.
+```
+
+For `terminal-failure`, return success only for push with the same queue-clear wording. Merge must continue returning asserted non-readiness.
+
+**Step 2: Preserve malformed and unknown rejection**
+
+Keep `malformed`, `unknown`, and unrecognized states non-zero for both purposes.
+
+**Step 3: Run focused tests and verify GREEN**
+
+Run:
+
+```bash
+bash packages/mosaic/framework/tools/git/test-ci-queue-wait-tristate.sh
+bash packages/mosaic/framework/tools/git/test-ci-queue-wait-github-checks.sh
+```
+
+Expected: both scripts exit 0 and report their regression suites passed.
+
+**Step 4: Commit implementation**
+
+```bash
+git add packages/mosaic/framework/tools/git/ci-queue-wait.sh
+git commit -m "fix(ci): separate push queue clearance from merge readiness"
+```
+
+### Task 3: Verify, Review, and Document Evidence
+
+**Files:**
+
+- Modify: `docs/scratchpads/1146-ci-queue-purpose.md`
+
+**Step 1: Run shell syntax and focused regressions**
+
+```bash
+bash -n packages/mosaic/framework/tools/git/ci-queue-wait.sh
+bash -n packages/mosaic/framework/tools/git/test-ci-queue-wait-tristate.sh
+bash packages/mosaic/framework/tools/git/test-ci-queue-wait-tristate.sh
+bash packages/mosaic/framework/tools/git/test-ci-queue-wait-github-checks.sh
+```
+
+**Step 2: Run repository quality gates**
+
+```bash
+pnpm preflight
+pnpm typecheck
+pnpm lint
+pnpm test
+pnpm format:check
+```
+
+Expected: every command exits 0.
+
+**Step 3: Obtain independent review**
+
+Request review of the exact branch head. Remediate all blocking findings and rerun focused and baseline gates.
+
+**Step 4: Record evidence and commit**
+
+Update the scratchpad with test output, review result, and residual risk, then commit it:
+
+```bash
+git add docs/scratchpads/1146-ci-queue-purpose.md
+git commit -m "docs(ci): record queue guard verification"
+```
+
+### Task 4: Keep the Merge Wrapper Aligned with the `next` Lane
+
+**Files:**
+
+- Modify: `packages/mosaic/framework/tools/git/pr-merge.sh:97-101`
+- Test: `packages/mosaic/framework/tools/git/test-pr-merge-head-pin.sh`
+
+**Step 1: Write the failing regression**
+
+Run the exact-head merge regression with its Gitea fixture targeting `next` and confirm the current wrapper rejects it because it only permits `main`.
+
+**Step 2: Allow only documented integration targets**
+
+Permit `main` and `next`; reject every other target. Do not alter exact-head pinning, queue-guard invocation, provider selection, or merge method enforcement.
+
+**Step 3: Run focused merge regressions**
+
+```bash
+bash packages/mosaic/framework/tools/git/test-pr-merge-head-pin.sh
+bash packages/mosaic/framework/tools/git/test-pr-merge-queue-branch.sh
+bash packages/mosaic/framework/tools/git/test-pr-merge-gitea-empty-uid.sh
+```
+
+Expected: all pass, including a Gitea merge fixture targeting `next`.
+
+**Step 4: Commit**
+
+```bash
+git add packages/mosaic/framework/tools/git/pr-merge.sh packages/mosaic/framework/tools/git/test-pr-merge-head-pin.sh
+git commit -m "fix(ci): allow reviewed merges into next"
+```
+
+### Task 5: Activate and Deliver Through `next`
+
+**Files:**
+
+- Installed output: `~/.config/mosaic/tools/git/ci-queue-wait.sh`
+
+**Step 1: Activate through the canonical installer**
+
+From the reviewed worktree, run the framework installer in sync-only keep mode so operator files remain protected:
+
+```bash
+MOSAIC_SYNC_ONLY=1 MOSAIC_INSTALL_MODE=keep MOSAIC_SKIP_SKILLS_SYNC=1 \
+  bash packages/mosaic/framework/install.sh
+```
+
+**Step 2: Verify installed/source parity**
+
+```bash
+cmp -s \
+  packages/mosaic/framework/tools/git/ci-queue-wait.sh \
+  ~/.config/mosaic/tools/git/ci-queue-wait.sh
+```
+
+Expected: exit 0.
+
+**Step 3: Run mandatory pre-push queue guard**
+
+```bash
+~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push -B fix/1146-ci-queue-purpose
+```
+
+Expected: branch-absent or queue-clear success.
+
+**Step 4: Push and open a PR against `next`**
+
+```bash
+git push -u origin fix/1146-ci-queue-purpose
+~/.config/mosaic/tools/git/pr-create.sh \
+  -t "fix(ci): make queue guard purpose-sensitive" \
+  -b "Closes #1146" \
+  -B next \
+  -H fix/1146-ci-queue-purpose \
+  -i 1146
+```
+
+**Step 5: Complete reviewed integration**
+
+Wait for exact-head terminal-green CI, obtain the required review, merge via the Mosaic wrapper, verify merged CI, and close #1146. Do not bypass any gate.

docs/scratchpads/1146-ci-queue-purpose.md

@@ -0,0 +1,65 @@
+# #1146 — CI Queue Guard Purpose Semantics
+
+## Objective
+
+Make the pre-push queue guard wait for queued/running CI without requiring the previous remote head to have successful CI. Preserve fail-closed merge readiness.
+
+## Scope
+
+- `packages/mosaic/framework/tools/git/ci-queue-wait.sh`
+- focused queue-guard regression tests
+- design and scratchpad documentation
+- local framework activation required before the fixed guard can authorize this branch's push
+
+## Plan
+
+1. Freeze purpose-specific behavior in failing process-level tests.
+2. Implement the smallest state-dispatch change.
+3. Run focused shell tests and repository quality gates.
+4. Obtain independent review and remediate findings.
+5. Install the reviewed framework source locally, run the mandatory pre-push queue guard, and push.
+6. Open a PR against `next`, verify terminal-green CI, and close #1146 after merge.
+
+## Budget
+
+- ASSUMPTION: no explicit token cap was provided.
+- Working estimate: 12K tokens.
+- Scope reduction: change only final-state dispatch and focused tests; do not redesign provider adapters.
+
+## Progress
+
+- Confirmed source and installed guards are byte-identical.
+- Reproduced `terminal-failure` blocking `--purpose push`.
+- Root cause: final-state dispatch requires terminal success for both push and merge.
+- Design approved: push is queue-clear on valid non-pending states; merge remains fail-closed.
+
+## Tests
+
+- RED confirmed before implementation: the focused tri-state harness reported push `terminal-failure` and `no-status` as `ASSERTED_NOT_READY`.
+- GREEN: `bash packages/mosaic/framework/tools/git/test-ci-queue-wait-tristate.sh` — all outcome classes passed.
+- GREEN: `bash packages/mosaic/framework/tools/git/test-ci-queue-wait-github-checks.sh` — 6/6 purpose-aware cases passed.
+- GREEN: `bash -n` passed for the changed guard and both focused harnesses.
+- GREEN: `pnpm preflight`, `pnpm typecheck`, and `pnpm lint` passed.
+- `pnpm test` ran 45/46 workspace test tasks successfully, but the pre-existing Gateway `cross-user-isolation.test.ts` failed during cleanup with PostgreSQL error `28P01` (local `mosaic` password authentication failure). The changed Mosaic framework test task passed within that run.
+- GREEN: focused queue and merge shell regressions passed after the wrapper change.
+- GREEN: isolated Mosaic Vitest run passed (81 files, 1,514 tests).
+- The normal parallel Mosaic Vitest run has an environment-sensitive pre-existing failure in `install-ordering-guard.spec.ts`: the real activation probe changes between two calls while other suites run concurrently. Running the same spec alone and the complete Vitest suite with one fork passes.
+- The framework shell suite's pre-existing `version_coupling_unittest.py` also fails locally because the newly installed `mosaic` is now on PATH despite the test injecting a nonexistent PATH; CI's clean image does not have this global CLI. All changed queue/merge harnesses pass.
+- GREEN: `pnpm format:check` passed.
+- Note: an additional ad hoc Prettier command was not applicable to shell files because Prettier has no shell parser; the repository-wide format check passed using its configured file globs.
+
+## Review
+
+- Independent Codex review of the six-file diff: approved, confidence 0.84, zero blockers/should-fix/suggestions.
+- Review confirmed push queue-clear behavior, merge fail-closed behavior, and `--require-status` coverage.
+
+## Risks and Blockers
+
+- Canonical framework activation completed with `MOSAIC_SYNC_ONLY=1 MOSAIC_INSTALL_MODE=keep MOSAIC_SKIP_SKILLS_SYNC=1 bash packages/mosaic/framework/install.sh`.
+- Source and installed queue guards are byte-identical (`cmp` and SHA-256 parity passed).
+- The installed pre-push guard now passes for the not-yet-remote feature branch with `queue clear`.
+- The required merge wrapper then exposed a second bootstrap defect: `pr-merge.sh` hardcoded `main`, contradicting the documented PR-based `next` integration lane. Tracked as #1149 and fixed in the same delivery branch with a regression fixture targeting `next`.
+- Activation emitted the existing manifest-safety warning that six `fleet/run/*.hb*` operator files were touched then restored; no data loss was observed, but this remains a pre-existing framework-manifest defect to report separately.
+- The first activation attempt timed out after 600 seconds while copying the 113K-file operator snapshot; the bounded 1,800-second retry completed successfully. It left a partial durable snapshot from the interrupted attempt in the normal backup directory; the completed snapshot is the newer `pre-update-20260810T195317Z` entry.
+- Full baseline test completion is blocked by the unrelated local PostgreSQL authentication/cleanup failure described above; CI has its own disposable PostgreSQL service.
+- Existing `.mosaic/orchestrator/*` working-tree changes are unrelated and must remain unstaged.

docs/scratchpads/webui-fleet-bridge-plan.md

@@ -0,0 +1,114 @@
+# WebUI Fleet Bridge Planning Scratchpad
+
+**Mode:** Task 0 docs-only decision PR authorized; Task 1 and all executable/runtime work remain blocked.
+**Owner:** Velma
+**Opened:** 2026-08-09
+**Scope:** One enrolled Agent Host launching one native `mosaic claude` OAuth session and streaming it into `apps/web` through `apps/gateway`.
+
+## Objective
+
+Turn the approved direction in `jarvis-brain/docs/scratchpads/MOSAIC-WEBUI-FLEET-BRIDGE.md` into a test-first implementation plan while preserving Fred's harness-home/launcher contract and Scooby's greenfield safety findings.
+
+## Source reconciliation
+
+- Current `origin/main`: `b0f7d26dd9c14d91eaaefc35d6c9fd6618a0bd92`.
+- Current `origin/next`: `4df478cdd150fdf8d52ea109f02ade5d85017acd`.
+- Branches currently diverge (`main` has 11 unique commits; `next` has 13). `next` contains local-tier Redis fix #689; `main` contains later fleet/shell fixes.
+- Fred's three-root harness-home design and promotion stack are not yet fully present on either baseline.
+- Therefore neither current SHA is an acceptable implementation pin. Code may begin only from a Fred-certified reconciled SHA containing the required launcher/home contract and safe Gateway startup prerequisites.
+- The deployed `mosaic.woltje.com` v0.0.20 UI remains reference-only.
+
+## Verified seams
+
+- Current browser chat uses an in-process Pi SDK session.
+- `AgentRuntimeProvider` supports list/tree/stream/send/attach/detach/terminate, but not create/start.
+- `InteractionController` enrolls an already-existing runtime session; it cannot launch one.
+- Hermes is the only runtime provider registered in Gateway.
+- Tmux streaming is explicitly unsupported and remains out of scope.
+- `mosaic claude` is the authoritative launcher and accepts Claude's machine-facing stream-json flags.
+- Installed discovery version: Claude Code 2.1.226. Target Distrobox version must be independently pinned and certified.
+
+## Non-negotiable dependencies
+
+1. Fred approves the machine-facing launcher/seat-home contract before code.
+2. No WebUI/Gateway direct read of lease broker state, daemon socket, or state files (F-V3).
+3. No provider OAuth token leaves the Agent Host.
+4. No local Gateway/Web startup around the KBN/database hold.
+5. Greenfield work runs in a Debian Distrobox with an isolated home.
+6. The initial plan PR targets `next`; Fred binds D1–D15 on its exact head before issue/PRD/tracker completion or implementation work.
+
+## Reproducible evidence
+
+Run from a clean Stack clone:
+
+```bash
+git fetch origin main next
+git rev-parse origin/main origin/next
+git rev-list --left-right --count origin/main...origin/next
+rg -n "interface AgentRuntimeProvider|createSession|streamEvents|terminate" \
+  packages/types/src/agent packages/agent/src apps/gateway/src/agent
+rg -n "AgentService\.prompt|interaction_sessions|createRuntimeTerminationApproval" \
+  apps/gateway/src packages/db/src/schema.ts
+```
+
+Primary inspected source seams:
+
+- `packages/types/src/agent/agent-runtime-provider.ts`
+- `packages/agent/src/{runtime-provider-registry,hermes-runtime-provider,matrix-native-runtime-provider,tmux-fleet-runtime-provider}.ts`
+- `apps/gateway/src/agent/{runtime-provider-registry.service,interaction.controller,durable-session.repository,durable-session.service}.ts`
+- `apps/gateway/src/chat/chat.gateway.ts`
+- `packages/mosaic/src/commands/{launch,interaction}.ts`
+- `packages/mosaic/src/fleet/generated-env-boundary.ts`
+- `packages/db/src/schema.ts`
+- `apps/web/src/app/(dashboard)/chat/page.tsx`
+
+Planning-only investigation transcripts are local and intentionally uncommitted:
+
+- `/tmp/velma-plan-stack-surface.txt`
+- `/tmp/velma-plan-structure.txt`
+- `/tmp/velma-plan-scooby.txt`
+- `/tmp/velma-plan-runtime-contract.txt`
+
+## Source findings that constrain the design
+
+- `interaction_sessions.id` is the stable primary key; there are no create/policy/enrollment/state columns.
+- `interaction_outbox` has a unique `(session_id, idempotency_key)` index and only `pending | processing | delivered`.
+- Baseline `DurableSessionRepository.create()` can replace provider/runtime identity for the same owner; M1 must remove that implicit mutation.
+- Baseline termination approval is Redis-backed and currently consumes separately from PostgreSQL; M1 therefore needs durable authorization acceptance before destructive token deletion/dispatch.
+- Existing interaction HTTP base is `/api/interaction/:agentName`; the plan extends it rather than inventing a second route family.
+- Baseline `launch.ts`/lease launcher still use ambient lookup/literal interpreters. Section 4.1 is non-binding consumer input to Fred's W-F design; W-F's final resolved-launch contract must exist in the certified base before Velma can certify it.
+- Root `pnpm test` is not KBN-safe: it includes PGlite migration and framework-shell/lease-broker suites.
+
+## Independent draft review
+
+Seven adversarial review rounds found and drove explicit fixes for:
+
+- a candidate resolved-seat consumer descriptor and threat model, now explicitly non-binding input to Fred's W-F-owned launcher design;
+- one active launch per stable conversation, exact pending/failed encodings, durable pre-dispatch reservation, CAS activation, and crash lookup without a migration;
+- generation-bound enrollment, command/event revalidation, `SIGHUP` config epochs, and stale-epoch rejection;
+- Redis/PostgreSQL exact-stop crash safety via non-destructive verify, durable authorization acceptance, atomic claim/`GETDEL`, and same-operation status reconciliation;
+- sequence gaps/reorder limits, deterministic UUIDv5 completion, and Gateway restart fail-closed behavior;
+- shared streaming redaction before host ring/transport and again before Gateway persistence/browser;
+- D2/D12-selected path-free provenance and a separate safe browser DTO—never raw or hashed path strings;
+- exact F-V3 boundary: bridge has no broker API, while Fred's sealed launcher may enforce broker policy internally;
+- migration-free focused tests in Tasks 1–8, with live OAuth, repository transaction, Gateway/Web, and Playwright restricted to the Fred/Scooby-certified Task 9 path;
+- candidate private/public commitment and artifact-binding mechanisms that W-F may accept, simplify, replace, or defer;
+- JCS event-digest recomputation and equal/different duplicate handling in both accepted and future-buffer states;
+- a safe browser presentation DTO for host/workspace/seat/persona labels, readiness, and connection state;
+- explicit `OnApplicationBootstrap` create/stop recovery enumeration with no auto-launch;
+- all POSIX/Windows/UNC/file/tilde path classes in the streaming redactor and definitive failed-stop response semantics;
+- the full 14-column canonical task schema, fake-only Task 5 repository tests, migration-free certified Task 9 DB test, server-owned operation correlations/routes, and exact merged-SHA smoke;
+- per-commit independent review, queue guards, exact-head PR review, squash merge, exact merged-next SHA/CI wait, worktree-bound smoke, issue-state readback, and reviewed tracker-closure PR with its own merged-next CI;
+- a private DB URL loader captured/exported per session without recording or echoing the credential;
+- an attached Task 9 implementation branch, provider-filtered exact issue-state readback, and machine-verified smoke JSON binding source/worktree/deployed SHA;
+- a capped, duplicate-key-rejecting, exact-key/type smoke schema so report extensions or JSON boolean/float coercion cannot smuggle data or fake child-count evidence.
+
+The plan remains deliberately **decision-PR-ready, not implementation-ready**. Fred authorized only Task 0's initial two-document PR on `next`. He must still return every Section 2 value, replace all `[FRED-GATE]` entries, certify storage/startup, and provide the W-F-dependent `IMPLEMENTATION_BASE_SHA` before Task 0 closes or Task 1 starts.
+
+## Current status
+
+- Gitea principal verified as `velma`; helper and API wrapper resolution are fail-closed and correct.
+- Fred authorized the initial Task 0 docs-only PR in `comms/20260809T094952Z__from-fred__ec0e85.md` and confirmed its `next` lane/W-F descriptor corrections in `comms/20260809T095437Z__from-fred__4ee79d.md`.
+- Provisional decisions: D1/D8/D9/D10/D13/D14 approved; D4 tool labels exactly `{Read, Grep, Glob}`; D5/D12 provisional; D11 remains a single-operator seam; D2/D3/D6/D7 and `IMPLEMENTATION_BASE_SHA` are `BLOCKED-ON-W-F`.
+- Awaiting exact plan-PR-head review and Fred's complete D1–D15 binding contract.
+- No source code, database, deployment, or live runtime changes made.

docs/scratchpads/webui-p2-data-auth.md

@@ -0,0 +1,172 @@
+# WebUI Phase P — P2 Data + Auth Scratchpad
+
+**Task ID:** WEBUI-P2
+**Tracking ref:** stacked on PR #1143 (`feat/webui-p1-vite-skeleton`); no separate issue specified in the author brief
+**Branch:** `feat/webui-p2-data-auth`
+**Started:** 2026-08-09
+**Role:** P2 author worker (must not modify `docs/TASKS.md`)
+
+## Original tasking
+
+> Read `/home/jwoltje/briefs/P2-brief.md` and execute it fully in `/home/jwoltje/src/stack-p1` on branch `feat/webui-p2-data-auth`. Run every listed verification gate, commit locally only, and do not push.
+
+Container path mapping:
+
+- Brief: `/home/jwoltje/distrobox-homes/mosaic-dev/briefs/P2-brief.md`
+- Repo: `/home/jwoltje/distrobox-homes/mosaic-dev/src/stack-p1`
+
+## Objective
+
+Make the P1 Vite SPA authenticate against the Mosaic Gateway by same-origin relative paths, replace guest-route placeholders with real login/register/SSO callback pages, and enforce guest/authenticated route guards without modifying the parallel Next app tree except for unavoidable shared-library import fixes.
+
+## Scope and invariants
+
+- All SPA HTTP and Socket.IO access remains origin-relative (`/api/...`, `/api/auth/...`, `/chat`).
+- No `NEXT_PUBLIC_*`, `VITE_*` origin setting, or hard-coded `http://localhost:14242` under `apps/web/src/`.
+- Verify the Gateway BetterAuth mount path from source before choosing auth-client configuration.
+- Delete the legacy static SSO-provider discovery module and test; runtime `/api/sso/providers` is canonical.
+- Preserve the Next build while adding React Router guest pages and session guards.
+- Never push; stage named files only; do not touch the modified `.mosaic/orchestrator/session.lock`.
+
+## Plan
+
+1. Inspect P1 SPA structure, shared libraries, legacy Next auth pages/components, Gateway auth mount, and current test setup.
+2. Add/adjust tests first for relative API behavior, auth-client origin configuration, relative Socket.IO singleton behavior, and all guard session states; run focused tests and capture expected RED failures.
+3. Implement shared-library relative networking and remove the legacy SSO-provider module/imports.
+4. Port login, register, and provider callback pages to React Router and wire routes.
+5. Implement session-aware guest/auth guards and satisfy focused tests.
+6. Run focused tests, all brief verification gates, invariant searches, and an independent code/security review; remediate and re-run affected gates.
+7. Update this scratchpad with evidence, stage named files only, and commit locally.
+
+## Testing strategy
+
+- TDD is required because this increment changes authentication/session behavior.
+- Primary situational evidence: jsdom router guard state tests plus guest-page/auth-flow contract tests already present or added as needed.
+- Baseline gates: web tests, Vite build, Next build, typecheck, lint, and root format check exactly as listed in the brief.
+- Browser automation is not required by the brief for P2; if used, it will be headless only.
+
+## Budget
+
+No explicit user token cap was provided. Working soft cap: **30K tokens**, derived from a multi-file auth/frontend increment with tests, dual builds, review, and remediation. Keep implementation within the brief; no unrelated refactors or dependencies.
+
+## Progress / evidence
+
+- [x] Loaded mission protocol, active MVP manifest/scratchpad, top-level tasks, PRD, relevant frontend/auth/testing/type/review guides, and matching skills.
+- [x] Resolved host paths to the Distrobox-mapped repo and brief.
+- [x] Confirmed branch `feat/webui-p2-data-auth`, stacked at P1 commit `068d0f9b`.
+- [x] Source and Gateway mount inspection complete.
+- [x] RED tests observed.
+- [x] Implementation complete.
+- [x] Independent review complete and findings remediated.
+- [x] Verification gates complete.
+- [x] Local implementation commit created: `46d68e1f`.
+
+### Source decisions
+
+- Gateway source mounts BetterAuth at `/api/auth/` in `apps/gateway/src/auth/auth.controller.ts`; `packages/auth/src/auth.ts` configures `basePath: '/api/auth'`.
+- BetterAuth 1.5.5 defaults its browser client to `/api/auth` when `baseURL` is omitted. `src/lib/auth-client.ts` therefore omits `baseURL`, preserving same-origin behavior without encoding any gateway origin.
+- The only `src/app/` edit is the transitional Next provider redirect page. Deleting `src/lib/sso-providers.ts` required that mechanical consumer migration; it now uses the same runtime `/api/sso/providers` discovery and callback sanitizer as the SPA.
+- GuestGuard pending behavior intentionally follows the approved brief: if no session object exists (including pending), render `<Outlet />`; only a present session redirects to `/chat`. AuthGuard alone renders the specified pending treatment.
+
+### TDD evidence
+
+- Initial focused run: 9 expected failures, proving absolute API/auth/socket origins, P1 guest placeholders, and missing guard redirects/loading behavior.
+- After implementation: focused contract suite 15/15 passed.
+- Security remediation RED: `%2F%0A%2F%2Fevil.example` reached `signIn.oauth2` as an external-normalizing callback target before the fix.
+- Security remediation GREEN: shared `resolveAuthCallbackURL` unit suite 9/9 plus SPA callback regression 1/1 passed; both SPA and Next consumers use the shared helper.
+
+### Independent review
+
+- Primary Codex wrappers could not run because `jq` is absent; direct Codex fallback then failed authentication with HTTP 401. No review result was claimed from those attempts.
+- Independent Claude Sonnet code review found no implementation-scope blocker, one pending-state UX suggestion, and one pre-existing `api.ts` type-assertion suggestion. The pending-state suggestion was rejected because it contradicts the brief's explicit GuestGuard contract; the API cleanup is outside P2's preserve-contract scope.
+- Independent Claude Sonnet security review found a high-severity control-character open redirect in the callback prefix check shared by the newly ported SPA logic and transitional Next consumer.
+- Remediation centralized WHATWG URL parsing plus exact current-origin comparison in `src/lib/auth-redirect.ts`, returns only path/search/hash, and added the RED-first regression above.
+- Fresh code re-review: `approve`, 0 blockers, 0 should-fix findings.
+- Fresh security re-review: `low`, 0 critical/high/medium/low findings.
+
+### Documentation checklist disposition
+
+- `docs/PRD.md` exists and P2 aligns to FR-8 / AC-7 authentication requirements.
+- No Gateway endpoint, DTO, permission, or API schema changed; existing `/api/auth/*` and `/api/sso/providers` contracts are consumed unchanged, so OpenAPI/API-index updates are not applicable.
+- Route paths were already present in the P1 route table; P2 replaces placeholders without changing site-map navigation, so `docs/SITEMAP.md` is unchanged.
+- User/admin auth behavior is parity with the still-live Next implementation, not a new workflow. Implementation decisions, failure behavior, testing, and migration compatibility are documented here; no publishing action is in scope.
+- Documentation remains in-repo; no generated publishing output was created.
+
+### Final verification evidence
+
+Run fresh after remediation from the locations required by the brief:
+
+- `apps/web: pnpm test` — PASS: `Test Files 9 passed (9)`; `Tests 27 passed (27)`.
+- `apps/web: pnpm build:vite` — PASS: `✓ 113 modules transformed`; `✓ built in 565ms`.
+- `apps/web: pnpm build` — PASS: `✓ Compiled successfully in 4.6s`; 10/10 static pages generated; dynamic provider/project routes retained.
+- `apps/web: pnpm typecheck` — PASS: `tsc --noEmit` exited 0.
+- `apps/web: pnpm lint` — PASS: `eslint src` exited 0.
+- Root `pnpm format:check` — PASS: `All matched files use Prettier code style!`.
+- Invariant scan — PASS: no `NEXT_PUBLIC_*`, `VITE_*`, `GATEWAY_URL`, `http://localhost:14242`, or `sso-providers` references under `apps/web/src`.
+- `git diff --check` — PASS.
+- All six required gates above were repeated successfully after implementation commit `46d68e1f`, proving the exact committed source tree.
+
+## Risks / blockers
+
+- `.mosaic/orchestrator/session.lock` is modified by the active harness and must remain unstaged.
+- P2 changes shared `src/lib/` modules consumed by both Vite and Next, so the Next build is a required compatibility gate.
+
+## Remediation 1 — independent Node 26 verification failure
+
+**Correction received:** 2026-08-09
+
+The orchestrator rejected the P2 verification claim after an independent run under Node 26.4.0 produced 2 failed redirect tests and 2 unhandled errors. React Router passed jsdom's realm-local `AbortSignal` to Node 26's native undici `Request`, which rejects non-native signals. Production guard behavior is correct and must not change.
+
+### Remediation constraints
+
+- Preserve both redirect assertions and all `guards.tsx` behavior; no skips, weakening, or test deletion.
+- Add the smallest Vitest environment repair so global `AbortController` / `AbortSignal` are constructors accepted by native undici `Request`.
+- Run all six required gates, commit named files locally without pushing, leave `.mosaic/orchestrator/session.lock` untouched, then run `apps/web: pnpm test` as the final worktree action.
+- Completion requires zero failed tests, zero test errors, and zero unhandled rejections.
+
+### Remediation plan
+
+1. Reproduce under Node 26.4.0 if an ephemeral matching runtime is available.
+2. Add a Vitest `setupFiles` module deriving Node-native abort constructors from `node:util` and register it in `apps/web/vitest.config.ts`.
+3. Add a direct regression assertion that a global controller's signal is accepted by native `Request`, while retaining the existing redirect behavior tests unchanged.
+4. Run focused Node 22 and Node 26 tests, independent review, all required gates, and local commit(s).
+5. After every edit/commit/status check is complete, run `pnpm test` from `apps/web` as the last command.
+
+### Remediation implementation and evidence
+
+- Reproduced under ephemeral Node `v26.4.0`: `Test Files 1 failed (1)`, `Tests 2 failed | 4 passed (6)`, `Errors 2 errors`, with the exact undici `AbortSignal` realm rejection from the remediation brief.
+- Added `apps/web/src/test/setup.ts`, registered through `vitest.config.ts#setupFiles`. It derives Node-native abort constructors from the built-in `node:util.transferableAbortController()` and aligns both `globalThis` and jsdom `window`; it does not replace `Request`, `Response`, or `fetch`.
+- Explicitly pinned Vitest `isolate: true` so the test-only global constructors cannot leak between test-file environments.
+- Added `src/test/setup.spec.ts`, which proves a global controller signal is accepted by Node's native `Request` and that abort propagation remains functional.
+- Existing `guards.spec.tsx` and production `guards.tsx` remain unchanged.
+- Focused Node 26.4.0 remediation run: `Test Files 2 passed (2)` and `Tests 7 passed (7)`, with zero errors/unhandled rejections.
+- Preliminary full Node 26.4.0 run: `Test Files 9 passed (9)` and `Tests 27 passed (27)`, with zero errors/unhandled rejections before the direct setup regression was added.
+- No dependency was added; `node:util` is a Node built-in.
+
+### Remediation independent review
+
+- First code review: approve, 0 blockers, 0 should-fix; suggested a direct Request regression and version-neutral comment.
+- First security/integrity review: low risk; suggested pinning test isolation explicitly.
+- All suggestions were applied.
+- Fresh code re-review: approve, 0 blockers, 0 should-fix, no findings.
+- Fresh security/integrity re-review: low risk, 0 findings.
+
+### Remediation pre-commit gate evidence
+
+- Node 26.4.0 `pnpm test`: `Test Files 10 passed (10)`; `Tests 28 passed (28)`; zero errors and zero unhandled rejections.
+- `pnpm typecheck`: `tsc --noEmit` exited 0.
+- `pnpm build:vite`: `✓ 113 modules transformed`; `✓ built in 960ms`.
+- `pnpm build` (Next): `✓ Compiled successfully in 4.8s`; static pages generated 10/10.
+- `pnpm lint`: `eslint src` exited 0.
+- Root `pnpm format:check`: `All matched files use Prettier code style!`.
+- Final post-commit non-test gates and final-action Node 26 `pnpm test` remain required before reporting completion.
+
+### Remediation committed verification
+
+- Implementation commit: `e16c08aa` (`test(web): align jsdom abort signals with Node`).
+- Post-commit `pnpm typecheck`: `tsc --noEmit` exited 0.
+- Post-commit `pnpm build:vite`: `✓ 113 modules transformed`; `✓ built in 323ms`.
+- Post-commit `pnpm build` (Next): `✓ Compiled successfully in 4.6s`; static pages generated 10/10.
+- Post-commit `pnpm lint`: `eslint src` exited 0.
+- Post-commit root `pnpm format:check`: `All matched files use Prettier code style!`.
+- Final Node 26 `pnpm test` will be the last worktree action and its verbatim output will be reported to the orchestrator.

packages/mosaic/framework/tools/git/ci-queue-wait.sh

@@ -465,12 +465,24 @@ while true; do
         no-status)
             if [[ "$REQUIRE_STATUS" -eq 1 ]]; then
                 echo "Error: ASSERTED_NOT_READY state=no-status; --require-status was set for ${BRANCH}." >&2
-            else
+                exit 3
-                echo "Error: ASSERTED_NOT_READY state=no-status purpose=${PURPOSE} branch=${BRANCH}." >&2
             fi
+            if [[ "$PURPOSE" == "push" ]]; then
+                echo "[ci-queue-wait] queue-clear state=no-status purpose=push branch=${BRANCH}; no queued or running CI."
+                exit 0
+            fi
+            echo "Error: ASSERTED_NOT_READY state=no-status purpose=${PURPOSE} branch=${BRANCH}." >&2
             exit 3
             ;;
-        terminal-failure|malformed|unknown)
+        terminal-failure)
+            if [[ "$PURPOSE" == "push" ]]; then
+                echo "[ci-queue-wait] queue-clear state=terminal-failure purpose=push branch=${BRANCH}; no queued or running CI."
+                exit 0
+            fi
+            echo "Error: ASSERTED_NOT_READY state=terminal-failure purpose=${PURPOSE} branch=${BRANCH}." >&2
+            exit 3
+            ;;
+        malformed|unknown)
             echo "Error: ASSERTED_NOT_READY state=${STATE} purpose=${PURPOSE} branch=${BRANCH}." >&2
             exit 3
             ;;

packages/mosaic/framework/tools/git/pr-merge.sh

@@ -94,8 +94,8 @@ BASE_BRANCH="$(printf '%s' "$PR_METADATA" | python3 -c 'import json, sys; print(
 HEAD_BRANCH="$(printf '%s' "$PR_METADATA" | python3 -c 'import json, sys; print((json.load(sys.stdin).get("headRefName") or "").strip())')"
 HEAD_SHA="$(printf '%s' "$PR_METADATA" | python3 -c 'import json, sys; print((json.load(sys.stdin).get("headRefOid") or "").strip())')"
 HEAD_REPO="$(printf '%s' "$PR_METADATA" | python3 -c 'import json, sys; value=json.load(sys.stdin).get("headRepository") or ""; print((value.get("nameWithOwner") or value.get("full_name") or "") if isinstance(value, dict) else str(value).strip())')"
-if [[ "$BASE_BRANCH" != "main" ]]; then
+if [[ "$BASE_BRANCH" != "main" && "$BASE_BRANCH" != "next" ]]; then
-    echo "Error: Mosaic policy allows merges only for PRs targeting 'main' (found '$BASE_BRANCH')." >&2
+    echo "Error: Mosaic policy allows merges only for PRs targeting 'main' or 'next' (found '$BASE_BRANCH')." >&2
     exit 1
 fi
 

packages/mosaic/framework/tools/git/test-ci-queue-wait-github-checks.sh

@@ -43,22 +43,22 @@ SH
 chmod +x "$STUB_DIR/gh"
 
 run_guard() {
-    local mode="$1"
+    local mode="$1" purpose="${2:-push}"
     (
         cd "$REPO_DIR" || exit
         export PATH="$STUB_DIR:$PATH"
         export MOSAIC_GH_CHECK_MODE="$mode"
         export MOSAIC_GH_CALL_LOG="$WORK_DIR/gh-calls.log"
         export MOSAIC_CI_QUEUE_AUDIT_LOG="$WORK_DIR/audit.jsonl"
-        "$SCRIPT_DIR/ci-queue-wait.sh" --purpose push -t 0 -i 0
+        "$SCRIPT_DIR/ci-queue-wait.sh" --purpose "$purpose" -t 0 -i 0
     )
 }
 
 failures=0
 assert_case() {
-    local mode="$1" expected_rc="$2" expected_state="$3" output rc
+    local mode="$1" expected_rc="$2" expected_state="$3" purpose="${4:-push}" output rc
     set +e
-    output=$(run_guard "$mode" 2>&1)
+    output=$(run_guard "$mode" "$purpose" 2>&1)
     rc=$?
     set -e
     if [[ "$expected_rc" == zero && "$rc" -ne 0 ]]; then
@@ -79,10 +79,12 @@ set -e
 : > "$WORK_DIR/gh-calls.log"
 assert_case success zero terminal-success
 assert_case pending nonzero pending
-assert_case failure nonzero terminal-failure
+assert_case failure zero terminal-failure
-assert_case late-failure nonzero terminal-failure
+assert_case late-failure zero terminal-failure
+assert_case failure nonzero terminal-failure merge
+assert_case late-failure nonzero terminal-failure merge
 
-if [[ $(grep -c 'check-runs?per_page=100&filter=latest' "$WORK_DIR/gh-calls.log") -lt 4 ]]; then
+if [[ $(grep -c 'check-runs?per_page=100&filter=latest' "$WORK_DIR/gh-calls.log") -lt 6 ]]; then
     echo "FAIL: expected every case to query all Checks API pages" >&2
     failures=$((failures + 1))
 fi
@@ -92,4 +94,4 @@ if [[ "$failures" -ne 0 ]]; then
     exit 1
 fi
 
-echo "GitHub check-runs regression passed (4/4 cases, including later-page failure)"
+echo "GitHub check-runs regression passed (6/6 purpose-aware cases, including later-page failure)"

packages/mosaic/framework/tools/git/test-ci-queue-wait-tristate.sh

@@ -53,6 +53,7 @@ case "$url" in
             malformed) printf '%s' 'not-json' ;;
             malformed-statuses-type) printf '%s' '{"state":"success","statuses":"corrupt"}' ;;
             malformed-status-entry) printf '%s' '{"state":"success","statuses":[null]}' ;;
+            unknown) printf '%s' '{"state":"success","statuses":[{"status":"cancelled"}]}' ;;
             large-success)
                 python3 -c 'import json; print(json.dumps({"state":"success", "statuses":[{"status":"success"}], "padding":"x" * (160 * 1024)}), end="")'
                 ;;
@@ -128,18 +129,27 @@ run_assertion() {
 
 set -e
 : > "$WORK_DIR/urls.log"
-run_assertion success zero success 'state=terminal-success'
+# Push readiness is queue clearance, not proof that prior CI succeeded.
-run_assertion pending nonzero pending 'ASSERTED_NOT_READY'
+run_assertion push-success zero success 'state=terminal-success'
-run_assertion failure nonzero failure 'ASSERTED_NOT_READY'
+run_assertion push-pending nonzero pending 'ASSERTED_NOT_READY'
-run_assertion no-status nonzero no-status 'ASSERTED_NOT_READY'
+run_assertion push-failure zero failure 'queue-clear state=terminal-failure purpose=push'
-run_assertion aggregate-success-no-status nonzero aggregate-success-no-status 'ASSERTED_NOT_READY'
+run_assertion push-no-status zero no-status 'queue-clear state=no-status purpose=push'
-run_assertion malformed nonzero malformed 'ASSERTED_NOT_READY'
+run_assertion push-aggregate-success-no-status zero aggregate-success-no-status 'queue-clear state=no-status purpose=push'
-run_assertion malformed-statuses-type nonzero malformed-statuses-type 'ASSERTED_NOT_READY'
+run_assertion push-require-status nonzero no-status 'ASSERTED_NOT_READY state=no-status' --require-status
-run_assertion malformed-status-entry nonzero malformed-status-entry 'ASSERTED_NOT_READY'
+run_assertion push-malformed nonzero malformed 'ASSERTED_NOT_READY'
-run_assertion large-payload not126 large-success 'state=terminal-success'
+run_assertion push-malformed-statuses-type nonzero malformed-statuses-type 'ASSERTED_NOT_READY'
+run_assertion push-malformed-status-entry nonzero malformed-status-entry 'ASSERTED_NOT_READY'
+run_assertion push-unknown nonzero unknown 'ASSERTED_NOT_READY'
+run_assertion push-large-payload not126 large-success 'state=terminal-success'
 run_assertion credential-unresolvable zero credential-unresolvable 'CANNOT_ASSERT'
 run_assertion provider-unreachable zero unreachable 'CANNOT_ASSERT'
 
+# Merge readiness remains fail-closed and requires exact-head terminal success.
+MOSAIC_TEST_PURPOSE=merge run_assertion merge-success zero success 'state=terminal-success'
+MOSAIC_TEST_PURPOSE=merge run_assertion merge-failure nonzero failure 'ASSERTED_NOT_READY state=terminal-failure'
+MOSAIC_TEST_PURPOSE=merge run_assertion merge-no-status nonzero no-status 'ASSERTED_NOT_READY state=no-status'
+MOSAIC_TEST_PURPOSE=merge run_assertion merge-unknown nonzero unknown 'ASSERTED_NOT_READY state=unknown'
+
 if [[ ! -s "$AUDIT_LOG" ]] || ! grep -q '"outcome":"CANNOT_ASSERT"' "$AUDIT_LOG"; then
     echo "FAIL provider-unreachable-audit: expected durable CANNOT_ASSERT JSONL record" >&2
     failures=$((failures + 1))

packages/mosaic/framework/tools/git/test-pr-merge-head-pin.sh

@@ -17,9 +17,10 @@ make_fixture() {
     cp "$SCRIPT_DIR/detect-platform.sh" "$tools/detect-platform.sh"
     git -C "$root/repo" init -q
     git -C "$root/repo" remote add origin "$remote"
+    local base_branch="${3:-main}"
     cat > "$tools/pr-metadata.sh" <<SH
 #!/usr/bin/env bash
-printf '%s\n' '{"baseRefName":"main","headRefName":"fix/pinned","headRefOid":"$SHA","headRepository":"contributor/widgets-fork"}'
+printf '%s\n' '{"baseRefName":"$base_branch","headRefName":"fix/pinned","headRefOid":"$SHA","headRepository":"contributor/widgets-fork"}'
 SH
     cat > "$tools/ci-queue-wait.sh" <<'SH'
 #!/usr/bin/env bash
@@ -29,8 +30,8 @@ SH
 }
 
 rm -rf "$WORK_DIR"
-make_fixture gitea https://git.example.test/acme/widgets.git
+make_fixture gitea https://git.example.test/acme/widgets.git next
-make_fixture github https://github.com/acme/widgets.git
+make_fixture github https://github.com/acme/widgets.git main
 
 cat > "$WORK_DIR/gitea/curl" <<'SH'
 #!/usr/bin/env bash

scripts/install-hooks.mjs

@@ -75,6 +75,16 @@ export async function installHooks({
 } = {}) {
   if (disabled) return;
 
+  try {
+    await execFileAsync('git', ['--version']);
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      console.warn('git not found; skipping hook installation');
+      return;
+    }
+    throw error;
+  }
+
   const huskyDir = path.join(root, '.husky');
   const active = path.join(huskyDir, '_');
   const nonce = `${Date.now()}-${process.pid}`;

tools/install-next-lane.test.sh

@@ -12,23 +12,6 @@ MOSAIC_HOME="$TMP/mosaic"
 STATE="$TMP/state"
 LOG="$TMP/npm.log"
 mkdir -p "$FAKE_BIN" "$HOME_DIR" "$STATE"
-REAL_NODE="$(command -v node)"
-export MOSAIC_TEST_REAL_NODE="$REAL_NODE"
-
-cat > "$FAKE_BIN/node" <<'FAKE_NODE'
-#!/usr/bin/env bash
-set -euo pipefail
-if [[ "$*" == *'process.versions.node.split'* ]]; then
-  printf '%s' "${MOSAIC_TEST_NODE_MAJOR:-22}"
-  exit 0
-fi
-if [[ "${1:-}" == "--version" ]]; then
-  printf 'v%s.0.0\n' "${MOSAIC_TEST_NODE_MAJOR:-22}"
-  exit 0
-fi
-exec "${MOSAIC_TEST_REAL_NODE:?}" "$@"
-FAKE_NODE
-chmod +x "$FAKE_BIN/node"
 
 cat > "$FAKE_BIN/npm" <<'FAKE_NPM'
 #!/usr/bin/env bash
@@ -152,20 +135,6 @@ reset_state() {
   rm -f "$STATE"/*
 }
 
-reset_state
-echo "[test] --next rejects Node 20 before any install action"
-if OUTPUT="$(
-  HOME="$HOME_DIR" MOSAIC_HOME="$MOSAIC_HOME" MOSAIC_PREFIX="$PREFIX" MOSAIC_NO_COLOR=1 \
-  MOSAIC_TEST_NPM_LOG="$LOG" MOSAIC_TEST_STATE="$STATE" MOSAIC_TEST_REAL_NODE="$REAL_NODE" \
-  MOSAIC_TEST_NODE_MAJOR=20 PATH="$FAKE_BIN:$PATH" \
-  bash "$ROOT/tools/install.sh" --cli --next --yes --no-auto-launch 2>&1
-)"; then
-  echo "expected Node 20 next-lane install to fail" >&2
-  exit 1
-fi
-grep -qF 'Node.js >= 22 required for the --next lane' <<<"$OUTPUT"
-[[ ! -s "$LOG" ]] || { echo "Node 20 gate ran npm actions" >&2; exit 1; }
-
 reset_state
 echo "[test] --next fast path pins resolved package versions"
 OUTPUT="$(

tools/install.sh

@@ -526,10 +526,6 @@ if [[ "$NODE_MAJOR" -lt 20 ]]; then
   fail "Node.js >= 20 required (found v$(node --version))"
   exit 1
 fi
-if [[ "$FLAG_NEXT" == "true" && "$NODE_MAJOR" -lt 22 ]]; then
-  fail "Node.js >= 22 required for the --next lane (found v$(node --version))"
-  exit 1
-fi
 
 echo ""
 echo "${BOLD}Mosaic Stack Installer${RESET}"