Merge pull request 'fix(gateway): gate FederationModule on tier === 'federated' (#1138 )' (#1140 ) from fix/1138-conditional-federation into next

test(gateway): raise module-graph import timeout for CI load robustness (#1138 )
fix(gateway): restore daemon config discovery (#1138 )
2026-08-10 07:09:51 +00:00 · 2026-08-10 01:34:24 -05:00 · 2026-08-10 00:31:58 -05:00 · 2026-08-09 23:54:53 -05:00 · 2026-08-09 23:11:09 -05:00 · 2026-08-09 22:21:17 -05:00
48 changed files with 5105 additions and 284 deletions
@@ -48,7 +48,7 @@ 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)

@@ -200,7 +200,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

@@ -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,
+  );
+});
@@ -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: [
@@ -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],
@@ -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();
@@ -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,
+  );
+});
@@ -1,18 +1,5 @@
 #!/usr/bin/env node
-import { config } from 'dotenv';
-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 './env.js';
 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) {
@@ -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,
+    });
+  });
+});
@@ -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: {
-      name: string;
-      description?: string;
-      teamId?: string;
-      repoUrl?: string;
-    },
-  ) {
+    @Body() dto: CreateWorkspaceDto,
+  ): Promise<BootstrapProjectResult> {
    return this.bootstrap.bootstrap({
-      name: body.name,
-      description: body.description,
+      name: dto.name,
+      description: dto.description,
      userId: user.id,
-      teamId: body.teamId,
-      repoUrl: body.repoUrl,
+      teamId: dto.teamId,
+      repoUrl: dto.repoUrl,
    });
  }
 }
@@ -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;
+}
@@ -1,11 +1,33 @@
-import { describe, it, expect, beforeEach } from 'vitest';
-import { WorkspaceService } from './workspace.service.js';
+import { BadRequestException } from '@nestjs/common';
+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),
+      );
+    });
+  });
 });
@@ -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) {
-      // Clone existing repo
-      await execFileAsync('git', ['clone', repoUrl, '.'], { cwd: workspacePath });
+    if (repoUrl !== undefined) {
+      // Clone existing repo. Defense in depth keeps dangerous local helpers
+      // 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
@@ -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>
@@ -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"
  }
 }
@@ -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 callbackURL = searchParams.get('callbackURL') ?? '/chat';
+  const requestedCallbackURL = searchParams.get('callbackURL');
+  const [providerName, setProviderName] = useState<string | null>(null);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
-    const currentProvider = provider;
+    let cancelled = false;

-    if (!currentProvider) {
+    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;
        }

-    if (!currentProvider.enabled) {
-      setError(`${currentProvider.buttonLabel} is not enabled in this deployment.`);
+        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 activeProvider = currentProvider;
-    let cancelled = false;
-
-    async function redirectToProvider(): Promise<void> {
        const result = await signIn.oauth2({
-        providerId: activeProvider.id,
+          providerId: provider.id,
          callbackURL,
        });

        if (!cancelled && result?.error) {
-        setError(result.error.message ?? `${activeProvider.buttonLabel} sign in failed.`);
+          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
-          ? `Redirecting you to ${provider.buttonLabel.replace('Continue with ', '')}...`
+        {providerName
+          ? `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"
@@ -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,
+    });
+  });
+});
@@ -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,
@@ -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');
+  });
+});
@@ -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()],
 });

@@ -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');
+  });
+});
@@ -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;
+  }
+}
@@ -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);
+  });
+});
@@ -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'],
@@ -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();
-  });
-});
@@ -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';
-  }
-}
@@ -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>,
+);
@@ -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);
+}
@@ -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');
+  });
+});
@@ -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 />;
+}
@@ -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>
+  );
+}
@@ -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>
+  );
+}
@@ -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',
+    });
+  });
+});
@@ -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>
+  );
+}
@@ -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>
+  );
+}
@@ -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);
+    },
+  );
+});
@@ -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);
+  });
+});
@@ -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,
+    },
+  });
+}
@@ -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 },
+    },
+  },
+});
@@ -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/**'],
  },
 });
@@ -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 --from=builder /deploy/package.json ./package.json
+COPY --chown=node:node --from=builder /deploy/node_modules ./node_modules
+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
-EXPOSE 4000
+COPY --chown=node:node --from=builder /app/apps/gateway/dist ./dist
+# gateway defaults to port 14242 (apps/gateway/src/main.ts)
+EXPOSE 14242
+USER node
 CMD ["node", "dist/main.js"]
@@ -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
@@ -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.
@@ -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.
@@ -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}`;
@@ -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="$(
@@ -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}"
Author	SHA1	Message	Date
shaggy	8c27024d0e	Merge pull request 'fix(gateway): gate FederationModule on tier === 'federated' (#1138 )' (#1140 ) from fix/1138-conditional-federation into next ci/woodpecker/push/publish Pipeline failed Details	2026-08-10 07:09:51 +00:00
shaggy (mosaic-dev box)	406e40584d	test(gateway): raise module-graph import timeout for CI load robustness (#1138 ) ci/woodpecker/pr/ci Pipeline was successful Details	2026-08-10 01:34:24 -05:00
shaggy (mosaic-dev box)	677aeb0c93	fix(gateway): restore daemon config discovery (#1138 ) ci/woodpecker/pr/ci Pipeline failed Details	2026-08-10 00:31:58 -05:00
shaggy (mosaic-dev box)andClaude Haiku 4.5	bd0ef2ab25	fix(gateway): anchor remaining config loads (#1138 ) Co-Authored-By: Claude Haiku 4.5 <[email protected]>	2026-08-09 23:54:53 -05:00
shaggy (mosaic-dev box)	2d5a8c81ec	fix(gateway): anchor config discovery and isolate env tests (#1138 )	2026-08-09 23:11:09 -05:00
shaggy (mosaic-dev box)	884d527cc8	fix(gateway): anchor dotenv discovery to module (#1138 )	2026-08-09 22:21:17 -05:00
shaggy	87daa12976	Merge pull request 'P2 — web SPA data layer + same-origin auth' (#1144 ) from feat/webui-p2-data-auth into next ci/woodpecker/push/publish Pipeline failed Details	2026-08-10 01:52:01 +00:00
shaggy (mosaic-dev box)	b82a51da80	fix(gateway): load dotenv before federation tier gate (#1138 )	2026-08-09 20:50:37 -05:00
shaggy (mosaic-dev box)	90cf286a09	fix(web): reject protocol-relative auth callbacks ci/woodpecker/pr/ci Pipeline was successful Details	2026-08-09 20:43:27 -05:00
shaggy (mosaic-dev box)	0aef432052	docs(scratchpad): record P2 remediation evidence	2026-08-09 20:21:53 -05:00
shaggy	41a16cc916	Merge pull request 'fix(docker): gateway image — git in runner, MOSAIC_ROOT workspace dir, scripts/ in builder, EXPOSE 14242' (#1142 ) from fix/gateway-runner-image into next ci/woodpecker/push/publish Pipeline failed Details	2026-08-10 01:21:30 +00:00
shaggy (mosaic-dev box)	e16c08aa9f	test(web): align jsdom abort signals with Node	2026-08-09 20:20:30 -05:00
shaggy (mosaic-dev box)	a34e92cf39	fix(gateway): harden workspace repository cloning ci/woodpecker/pr/ci Pipeline was successful Details	2026-08-09 20:12:39 -05:00
shaggy (mosaic-dev box)	a4861c221f	docs(scratchpad): record WebUI P2 verification	2026-08-09 20:02:22 -05:00
shaggy (mosaic-dev box)	46d68e1ff4	feat(web): add same-origin SPA authentication	2026-08-09 20:00:22 -05:00
shaggy	c3496334a5	Merge pull request 'feat(web): P1 — Vite + React Router skeleton beside Next (Phase P RFC, increment 1/6)' (#1143 ) from feat/webui-p1-vite-skeleton into next ci/woodpecker/push/publish Pipeline failed Details	2026-08-10 00:51:02 +00:00
shaggy	6f29d00149	Merge pull request 'fix: break-C — install-hooks no-ops without git; web image builds @mosaicstack/web' (#1141 ) from fix/break-c-hooks-and-web-image into next ci/woodpecker/push/publish Pipeline was canceled Details	2026-08-10 00:50:19 +00:00
shaggy (mosaic-dev box)andClaude Fable 5	068d0f9b1c	feat(web): P1 Vite skeleton beside Next — entry, router, guards, vitest 3 ci/woodpecker/pr/ci Pipeline was successful Details First increment of the approved Phase P RFC (webui-mission). Adds a Vite + React Router SPA scaffold coexisting with the Next app: index.html with the theme anti-flash script, src/main.tsx entry, the v1 parity route table under Guest/Auth guard shells, and a dev proxy (/api, /socket.io ws) to the gateway on 14242 so the SPA is same-origin in dev. vitest bumped to v3 (vite 8 pairing); existing specs pass unchanged. Next remains the served app until the P5 cutover. Co-Authored-By: Claude Fable 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01ESFAnh2t9HmLwng8oW95St	2026-08-09 19:02:55 -05:00
shaggy (mosaic-dev box)andClaude Fable 5	13cd673d50	fix(docker): gateway runner needs git + MOSAIC_ROOT workspace dir; EXPOSE actual port 14242 ci/woodpecker/pr/ci Pipeline was successful Details WorkspaceService shells out to git at runtime and roots workspaces at $MOSAIC_ROOT/.workspaces — the runner image had no git binary and no workspace directory. EXPOSE said 4000 but main.ts defaults to 14242. Co-Authored-By: Claude Fable 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01ESFAnh2t9HmLwng8oW95St	2026-08-09 18:03:42 -05:00
shaggy (mosaic-dev box)andClaude Fable 5	620cc608e0	fix(docker): copy scripts/ into web builder — prepare runs install-hooks.mjs on install ci/woodpecker/pr/ci Pipeline was successful Details The layer-cached install copies only manifests and packages/, so the root prepare script could not be found and pnpm install exited 1 before the git-absent guard could even run. Co-Authored-By: Claude Fable 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01ESFAnh2t9HmLwng8oW95St	2026-08-09 18:03:18 -05:00
shaggy (mosaic-dev box)andClaude Fable 5	91e692e3e7	fix: break-C — install-hooks no-ops without git; web image builds @mosaicstack/web ci/woodpecker/pr/ci Pipeline was canceled Details install-hooks.mjs hard-failed (exit 1) in environments without a git binary — e.g. the docker image builds, which have no git and no repo. Hook installation is meaningless there; skip with a warning instead. docker/web.Dockerfile filtered @mosaic/web, but the package is named @mosaicstack/web, so the image build compiled nothing. Co-Authored-By: Claude Fable 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01ESFAnh2t9HmLwng8oW95St	2026-08-09 17:58:13 -05:00
shaggy (mosaic-dev box)	b4753a75cd	fix(gateway): gate FederationModule on tier federated (#1138 ) ci/woodpecker/pr/ci Pipeline was successful Details CaService hard-requires STEP_CA_URL/provisioner config at construction, so an unconditional FederationModule import makes every standalone/local boot die at DI time. Gate the module on loadConfig().tier === federated, matching the documented intent of the federation compose profile (must not start in non-federated dev). Verified in mosaic-dev box: standalone tier boots to "Gateway listening on port 14242" with bootstrap/socket.io/auth surfaces responding; federated tier path unchanged.	2026-08-09 17:26:28 -05:00
velmaandmos-dt-0	24bbd40dc7	docs: WebUI fleet Claude bridge — Task 0 decision plan (#1131 ) ci/woodpecker/push/publish Pipeline failed Details Docs-only plan PR. FRED_APPROVED_REF=0629361ca39a4dd7fb3e575d11c64bea9e545dae (review 147). Merged by fred (orchestrator) via API: pr-merge.sh policy predates the next lane (main-only hardcode) — wrapper fix tracked separately. Co-authored-by: Velma <[email protected]>	2026-08-09 10:28:41 +00:00