@dotdrelle/wiki-manager 0.14.10 → 0.14.12

package/src/core/startupCheck.js

@@ -2,17 +2,88 @@ import { execFile } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { promisify } from 'node:util';
-import { parseComposePsJson } from './compose.js';
+import { activeCacertPath, cacertEnv } from './cacert.js';
+import { COMPOSE_SERVICES, parseComposePsJson, serviceStates } from './compose.js';
+import { buildMcpStatus, discoverMcpTools } from './mcp.js';
 import { listWikircProfiles, loadWikircProfile, summarizeWikircConfig } from './wikirc.js';
 import { listWorkspaces, managerRoot, workspacesDir } from './workspaces.js';
 
 const execFileAsync = promisify(execFile);
+const DEFAULT_CONNECTIVITY_URL = 'https://registry.npmjs.org/-/ping';
 
-async function checkAgents() {
+function commandError(err) {
+  return String(err?.stderr ?? err?.stdout ?? err?.message ?? err ?? 'unknown error').trim();
+}
+
+function dockerFailure(err) {
+  if (err?.code === 'ENOENT') return { ok: false, context: { dockerMissing: true } };
+  const detail = commandError(err);
+  const unavailable = /Cannot connect to the Docker daemon|Is the docker daemon running|docker daemon|connection refused/i.test(detail);
+  return {
+    ok: false,
+    context: unavailable
+      ? { dockerUnavailable: true, dockerError: detail }
+      : { dockerUnavailable: true, dockerError: detail || 'Docker availability check failed.' },
+  };
+}
+
+export async function checkDockerAvailability({ exec = execFileAsync } = {}) {
+  try {
+    const { stdout } = await exec('docker', ['info', '--format', '{{json .ServerVersion}}'], {
+      cwd: managerRoot(),
+      env: process.env,
+      timeout: 5000,
+      maxBuffer: 1024 * 1024,
+    });
+    return { ok: true, detail: String(stdout ?? '').trim().replace(/^"|"$/g, '') || 'available' };
+  } catch (err) {
+    return dockerFailure(err);
+  }
+}
+
+export async function checkInternetConnectivity({
+  exec = execFileAsync,
+  url = process.env.WIKI_MANAGER_CONNECTIVITY_URL ?? DEFAULT_CONNECTIVITY_URL,
+  timeoutMs = 7000,
+} = {}) {
+  const cacertPath = activeCacertPath();
+  const proxyUrl = process.env.HTTPS_PROXY ?? process.env.HTTP_PROXY ?? null;
+  const proxyEnabled = process.env.NODE_USE_ENV_PROXY === '1';
+  if (cacertPath && !existsSync(cacertPath)) {
+    return {
+      ok: false,
+      context: { url, error: `CA certificate not found: ${cacertPath}`, cacertPath, proxyUrl, proxyEnabled },
+    };
+  }
+  const node = process.versions.bun ? (process.env.WIKI_MANAGER_NODE_BIN ?? 'node') : process.execPath;
+  const script = [
+    'const controller = new AbortController();',
+    `const timer = setTimeout(() => controller.abort(), ${Math.max(1000, Number(timeoutMs) || 7000)});`,
+    "try { const response = await fetch(process.argv[1], { method: 'GET', signal: controller.signal }); if (!response.ok) throw new Error('HTTP ' + response.status); } finally { clearTimeout(timer); }",
+  ].join(' ');
+  try {
+    await exec(node, ['--input-type=module', '-e', script, url], {
+      cwd: managerRoot(),
+      // Run in a fresh Node process so both environment-proxy support and a
+      // custom CA are applied at process startup, just like the runtime.
+      env: { ...process.env, ...cacertEnv(cacertPath) },
+      timeout: Math.max(2000, Number(timeoutMs) + 1000),
+      maxBuffer: 1024 * 1024,
+    });
+    return { ok: true, detail: url, context: { url, cacertPath, proxyUrl, proxyEnabled } };
+  } catch (err) {
+    return {
+      ok: false,
+      context: { url, error: commandError(err) || 'Internet connectivity check failed.', cacertPath, proxyUrl, proxyEnabled },
+    };
+  }
+}
+
+async function checkAgents({ exec = execFileAsync } = {}) {
   const composeFile = join(managerRoot(), 'agents.docker-compose.yml');
   if (!existsSync(composeFile)) return null;
   try {
-    const { stdout } = await execFileAsync('docker', [
+    const { stdout } = await exec('docker', [
       'compose',
       '--project-directory',
       managerRoot(),
@@ -115,16 +186,278 @@ function checkWikirc(workspace) {
   }
 }
 
-export async function runChecks() {
-  const workspaces = listWorkspaces();
-  const agents = await checkAgents();
+function startupSession(workspace) {
+  const session = {
+    workspace: workspace.name,
+    workspacePath: workspace.workspacePath,
+    workspaceEnvFile: workspace.envFile,
+    workspaceEnv: workspace.env,
+    wikirc: null,
+    wikircConfig: null,
+  };
+  try {
+    const loaded = loadWikircProfile(workspace.workspacePath, 'default');
+    session.wikirc = {
+      profile: loaded.profile.name,
+      fileName: loaded.profile.fileName,
+      path: loaded.profile.path,
+    };
+    session.wikircConfig = loaded.config;
+  } catch { /* configuration gap is reported separately */ }
+  return session;
+}
+
+export async function checkWorkspaceContainers(workspace) {
+  try {
+    const states = await serviceStates(startupSession(workspace));
+    const unavailable = COMPOSE_SERVICES.filter((name) => !states[name]?.running);
+    return {
+      ok: unavailable.length === 0,
+      pending: unavailable.length > 0,
+      detail: unavailable.length === 0 ? `${COMPOSE_SERVICES.length} running` : `To start: ${unavailable.join(', ')}`,
+      context: { states, unavailable, command: `wiki-workspace up ${workspace.name}` },
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      pending: true,
+      detail: 'Workspace containers remain to be started',
+      context: { error: commandError(err), command: `wiki-workspace up ${workspace.name}` },
+    };
+  }
+}
+
+function isLocalEndpoint(url) {
+  try {
+    const host = new URL(url).hostname.toLowerCase();
+    return host === 'localhost' || host === '127.0.0.1' || host === '::1' || host === 'host.docker.internal';
+  } catch {
+    return false;
+  }
+}
+
+function mcpFailureKind(value) {
+  if (value.status === 'missing') return 'configuration';
+  const message = String(value.toolError ?? '');
+  if (/\b(401|403|unauthorized|forbidden)\b/i.test(message)) return 'authentication';
+  if (/initialize|json|protocol|parse|session id/i.test(message)) return 'protocol';
+  if (/fetch failed|ECONNREFUSED|ENOTFOUND|timeout|aborted|socket/i.test(message)) return 'unreachable';
+  return 'unavailable';
+}
+
+export async function checkMcpConnections(workspace, {
+  internetAvailable = true,
+  buildStatus = buildMcpStatus,
+  discover = discoverMcpTools,
+} = {}) {
+  let configured;
+  try {
+    configured = buildStatus(startupSession(workspace));
+  } catch (err) {
+    return {
+      ok: false,
+      detail: 'MCP configuration invalid',
+      context: { error: commandError(err), endpoints: [] },
+    };
+  }
+  const skipped = {};
+  const candidates = {};
+  for (const [name, endpoint] of Object.entries(configured)) {
+    if (!internetAvailable && endpoint.external && !isLocalEndpoint(endpoint.url)) {
+      skipped[name] = { ...endpoint, tools: [], toolError: 'Skipped: Internet unavailable', preflightSkipped: true };
+    } else {
+      candidates[name] = endpoint;
+    }
+  }
+  let discovered;
+  try {
+    discovered = await discover(candidates);
+  } catch (err) {
+    return {
+      ok: false,
+      detail: 'MCP handshake failed',
+      context: { error: commandError(err), endpoints: [] },
+    };
+  }
+  const endpoints = { ...discovered, ...skipped };
+  const details = Object.entries(endpoints).map(([name, value]) => ({
+    name,
+    status: value.preflightSkipped ? 'skipped' : value.status === 'connected' ? 'connected' : 'failed',
+    tools: Array.isArray(value.tools) ? value.tools.length : 0,
+    reason: value.preflightSkipped ? 'internet unavailable' : value.status === 'connected' ? null : mcpFailureKind(value),
+    error: value.toolError ?? value.detail ?? null,
+  }));
+  const connected = details.filter((item) => item.status === 'connected');
+  const failed = details.filter((item) => item.status === 'failed');
+  const skippedCount = details.filter((item) => item.status === 'skipped').length;
+  return {
+    ok: failed.length === 0,
+    pending: failed.length > 0 || skippedCount > 0,
+    detail: `${connected.length} connected${failed.length ? `, ${failed.length} pending` : ''}${skippedCount ? `, ${skippedCount} waiting for Internet` : ''}`,
+    context: { endpoints: details, command: '/mcp status' },
+  };
+}
+
+function preflightStatus(gaps, checks) {
+  const setupRequired = gaps.some((gap) => gap.kind === 'workspace' || gap.kind === 'llm');
+  if (setupRequired) return 'setup_required';
+  return checks.every((check) => check.ok || check.skipped) ? 'ready' : 'degraded';
+}
+
+function compactNames(names, limit = 6) {
+  const visible = names.slice(0, limit);
+  return `${visible.join(', ')}${names.length > limit ? ` +${names.length - limit} more` : ''}`;
+}
+
+function compactContainerSummary(results, pending) {
+  if (pending.length === 0) {
+    return `${results.length}/${results.length} workspaces running: ${compactNames(results.map((item) => item.workspace.name))}`;
+  }
+  const groups = new Map();
+  for (const item of pending) {
+    const services = item.result.context?.unavailable?.length
+      ? item.result.context.unavailable.join(', ')
+      : 'services';
+    const names = groups.get(services) ?? [];
+    names.push(item.workspace.name);
+    groups.set(services, names);
+  }
+  const grouped = [...groups.entries()].slice(0, 3).map(([services, names]) =>
+    `${compactNames(names, 4)} — services: ${services}`);
+  const hiddenGroups = groups.size > 3 ? `; +${groups.size - 3} service group(s)` : '';
+  return `${pending.length}/${results.length} workspaces to start: ${grouped.join('; ')}${hiddenGroups}`;
+}
+
+export async function runChecks({
+  dockerCheck = checkDockerAvailability,
+  internetCheck = checkInternetConnectivity,
+  agentsCheck = checkAgents,
+  workspaceContainersCheck = checkWorkspaceContainers,
+  mcpCheck = checkMcpConnections,
+  onCheck = () => {},
+} = {}) {
+  // Keep infrastructure checks first and sequential: the order is part of the
+  // startup contract and makes proxy/CA diagnostics understandable.
+  const docker = await dockerCheck();
+  onCheck({ kind: 'docker', ...docker });
+  const internet = await internetCheck();
+  onCheck({ kind: 'internet', ...internet });
+
+  const workspaces = [...listWorkspaces()].sort((a, b) => a.name.localeCompare(b.name));
+  const agents = docker.ok ? await agentsCheck() : null;
   const gaps = [];
+  if (!docker.ok) gaps.push({ kind: 'agents', context: docker.context ?? { dockerUnavailable: true } });
+  if (!internet.ok) gaps.push({ kind: 'network', context: internet.context ?? {} });
   if (agents) gaps.push(agents);
+  onCheck({
+    kind: 'agents',
+    ok: docker.ok && !agents,
+    skipped: !docker.ok,
+    pending: !docker.ok || Boolean(agents),
+    detail: !docker.ok
+      ? 'Waiting for Docker'
+      : agents?.context?.downServices?.length
+        ? `To start: ${agents.context.downServices.join(', ')}`
+        : 'Running',
+    context: { ...(agents?.context ?? {}), command: 'wiki-workspace agents up' },
+  });
   const workspaceGap = checkWorkspace(workspaces);
   if (workspaceGap) {
     gaps.push(workspaceGap);
+    onCheck({ kind: 'workspace', ok: false, detail: 'No valid workspace initialization' });
+    onCheck({ kind: 'containers', ok: false, skipped: true, pending: true, detail: 'Waiting for workspace initialization' });
+    onCheck({ kind: 'mcp', ok: false, skipped: true, pending: true, detail: 'Waiting for workspace initialization' });
     return gaps;
   }
-  gaps.push(...checkWikirc(workspaces[0] ?? null));
+  const workspaceChecks = workspaces.map((workspace) => ({ workspace, gaps: checkWikirc(workspace) }));
+  const wikircGaps = workspaceChecks.flatMap((item) => item.gaps);
+  const invalidWorkspaces = workspaceChecks
+    .filter((item) => item.gaps.some((gap) => gap.kind === 'llm'))
+    .map((item) => item.workspace.name);
+  gaps.push(...wikircGaps);
+  onCheck({
+    kind: 'workspace',
+    ok: invalidWorkspaces.length === 0,
+    pending: invalidWorkspaces.length > 0,
+    detail: `${workspaces.length} registered: ${compactNames(workspaces.map((workspace) => workspace.name))}${invalidWorkspaces.length ? ` — configuration pending: ${compactNames(invalidWorkspaces)}` : ''}`,
+    context: { workspaces: workspaces.map((workspace) => workspace.name), invalidWorkspaces },
+  });
+  if (!docker.ok) {
+    onCheck({
+      kind: 'containers',
+      ok: false,
+      skipped: true,
+      pending: true,
+      detail: `Waiting for Docker — ${workspaces.length} workspace(s) to check`,
+      context: { command: `wiki-workspace up ${workspaces[0].name}` },
+    });
+  } else {
+    const results = await Promise.all(workspaces.map(async (workspace) => ({
+      workspace,
+      result: await workspaceContainersCheck(workspace),
+    })));
+    const pending = results.filter((item) => !item.result.ok);
+    onCheck({
+      kind: 'containers',
+      ok: pending.length === 0,
+      pending: pending.length > 0,
+      detail: compactContainerSummary(results, pending),
+      context: {
+        workspaces: results.map((item) => ({ name: item.workspace.name, ...item.result })),
+        unavailable: pending.flatMap((item) => item.result.context?.unavailable ?? []),
+        command: pending[0]?.result.context?.command ?? `wiki-workspace up ${pending[0]?.workspace.name ?? workspaces[0].name}`,
+      },
+    });
+  }
+  // MCP endpoints are independent connections. Keep probing them even when
+  // Docker is down: a remote or host-native MCP may still be healthy, while
+  // local container-backed endpoints will report their own reachability.
+  const mcpResults = await Promise.all(workspaces.map(async (workspace) => ({
+    workspace,
+    result: await mcpCheck(workspace, { internetAvailable: internet.ok }),
+  })));
+  const mcpPending = mcpResults.filter((item) => !item.result.ok);
+  const endpointChecks = mcpResults.flatMap((item) =>
+    (item.result.context?.endpoints ?? []).map((endpoint) => ({ workspace: item.workspace.name, ...endpoint })));
+  const connectedEndpoints = endpointChecks.filter((endpoint) => endpoint.status === 'connected').length;
+  const pendingEndpoints = endpointChecks.filter((endpoint) => endpoint.status === 'failed').length;
+  const skippedEndpoints = endpointChecks.filter((endpoint) => endpoint.status === 'skipped').length;
+  onCheck({
+    kind: 'mcp',
+    ok: mcpPending.length === 0,
+    pending: mcpPending.length > 0 || skippedEndpoints > 0,
+    detail: `${workspaces.length} workspace(s) checked — ${connectedEndpoints} connected${pendingEndpoints ? `, ${pendingEndpoints} pending` : ''}${skippedEndpoints ? `, ${skippedEndpoints} waiting for Internet` : ''}`,
+    context: {
+      endpoints: endpointChecks,
+      command: `/use ${mcpPending[0]?.workspace.name ?? workspaces[0].name}, then /mcp status`,
+    },
+  });
   return gaps;
 }
+
+export async function runPreflightChecks(options = {}) {
+  const checks = [];
+  const externalOnCheck = options.onCheck;
+  const gaps = await runChecks({
+    ...options,
+    onCheck: (check) => {
+      checks.push(check);
+      externalOnCheck?.(check);
+    },
+  });
+  return { gaps, checks, status: preflightStatus(gaps, checks) };
+}
+
+export function withRuntimePreflight(preflight, runtime) {
+  const runtimeCheck = runtime?.url
+    ? { kind: 'runtime', ok: true, detail: runtime.started ? 'Started' : 'Connected' }
+    : { kind: 'runtime', ok: false, detail: runtime?.error ?? 'Unavailable' };
+  const checks = [...(preflight?.checks ?? []).filter((check) => check.kind !== 'runtime'), runtimeCheck];
+  return {
+    ...(preflight ?? { gaps: [] }),
+    checks,
+    status: preflight?.status === 'setup_required'
+      ? 'setup_required'
+      : checks.every((check) => check.ok || check.skipped) ? 'ready' : 'degraded',
+  };
+}

package/src/core/startupCheck.test.js

@@ -4,7 +4,7 @@ import { mkdtemp } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import test from 'node:test';
-import { runChecks } from './startupCheck.js';
+import { checkInternetConnectivity, checkMcpConnections, runChecks, runPreflightChecks, withRuntimePreflight } from './startupCheck.js';
 
 async function withWorkspace(wikircLines, fn) {
   const root = await mkdtemp(join(tmpdir(), 'wiki-manager-startup-check-'));
@@ -44,7 +44,13 @@ test('runChecks treats default LLM config without baseUrl as incomplete', async
     '  vector:',
     '    enabled: true',
   ], async () => {
-    const gaps = await runChecks();
+    const gaps = await runChecks({
+      dockerCheck: async () => ({ ok: true }),
+      internetCheck: async () => ({ ok: true }),
+      agentsCheck: async () => null,
+      workspaceContainersCheck: async () => ({ ok: true, detail: 'running' }),
+      mcpCheck: async () => ({ ok: true, detail: 'connected' }),
+    });
     assert.equal(hasGap(gaps, 'llm'), true);
   });
 });
@@ -60,7 +66,188 @@ test('runChecks treats default LLM config with provider, baseUrl, apiKey and mod
     '  vector:',
     '    enabled: true',
   ], async () => {
-    const gaps = await runChecks();
+    const gaps = await runChecks({
+      dockerCheck: async () => ({ ok: true }),
+      internetCheck: async () => ({ ok: true }),
+      agentsCheck: async () => null,
+      workspaceContainersCheck: async () => ({ ok: true, detail: 'running' }),
+      mcpCheck: async () => ({ ok: true, detail: 'connected' }),
+    });
     assert.equal(hasGap(gaps, 'llm'), false);
   });
 });
+
+test('runChecks reports and probes every registered workspace', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'wiki-manager-multi-startup-'));
+  const registryRoot = join(root, 'registry');
+  for (const name of ['alpha', 'beta']) {
+    const registryPath = join(registryRoot, name);
+    const workspacePath = join(root, name);
+    mkdirSync(registryPath, { recursive: true });
+    mkdirSync(workspacePath, { recursive: true });
+    writeFileSync(join(registryPath, '.env'), `WORKSPACE_NAME=${name}\nWIKI_WORKSPACE_PATH=${workspacePath}\n`, 'utf8');
+    writeFileSync(join(workspacePath, '.wikirc.yaml'), [
+      'llm:',
+      '  provider: openai-compatible',
+      '  baseUrl: http://localhost:8000/v1',
+      '  apiKey: key',
+      '  model: chat-model',
+      '',
+    ].join('\n'), 'utf8');
+  }
+  const previousDir = process.env.WIKI_WORKSPACES_DIR;
+  process.env.WIKI_WORKSPACES_DIR = registryRoot;
+  try {
+    const containerCalls = [];
+    const mcpCalls = [];
+    const reports = [];
+    await runChecks({
+      dockerCheck: async () => ({ ok: true }),
+      internetCheck: async () => ({ ok: true }),
+      agentsCheck: async () => null,
+      workspaceContainersCheck: async (workspace) => {
+        containerCalls.push(workspace.name);
+        return {
+          ok: false,
+          pending: true,
+          detail: 'to start',
+          context: { unavailable: ['serve', 'mcp-http', 'production-mcp'], command: `wiki-workspace up ${workspace.name}` },
+        };
+      },
+      mcpCheck: async (workspace) => {
+        mcpCalls.push(workspace.name);
+        return { ok: true, detail: 'connected', context: { endpoints: [{ name: 'wiki', status: 'connected' }] } };
+      },
+      onCheck: (check) => reports.push(check),
+    });
+    assert.deepEqual(containerCalls, ['alpha', 'beta']);
+    assert.deepEqual(mcpCalls, ['alpha', 'beta']);
+    const workspaceReport = reports.find((check) => check.kind === 'workspace');
+    assert.equal(workspaceReport.detail, '2 registered: alpha, beta');
+    assert.equal(
+      reports.find((check) => check.kind === 'containers').detail,
+      '2/2 workspaces to start: alpha, beta — services: serve, mcp-http, production-mcp',
+    );
+    assert.match(reports.find((check) => check.kind === 'mcp').detail, /2 workspace\(s\) checked/);
+  } finally {
+    if (previousDir === undefined) delete process.env.WIKI_WORKSPACES_DIR;
+    else process.env.WIKI_WORKSPACES_DIR = previousDir;
+  }
+});
+
+test('runChecks executes Docker before Internet and reports both failures in order', async () => {
+  const calls = [];
+  const reports = [];
+  const gaps = await runChecks({
+    dockerCheck: async () => { calls.push('docker'); return { ok: false, context: { dockerUnavailable: true } }; },
+    internetCheck: async () => { calls.push('internet'); return { ok: false, context: { error: 'offline' } }; },
+    agentsCheck: async () => { calls.push('agents'); return null; },
+    onCheck: (check) => reports.push(check.kind),
+  });
+  assert.deepEqual(calls, ['docker', 'internet']);
+  assert.deepEqual(reports.slice(0, 3), ['docker', 'internet', 'agents']);
+  assert.deepEqual(gaps.slice(0, 2).map((gap) => gap.kind), ['agents', 'network']);
+});
+
+test('MCP preflight distinguishes authentication failure and skips remote endpoints while offline', async () => {
+  const workspace = { name: 'demo', workspacePath: '/tmp/demo', envFile: '/tmp/demo.env', env: {} };
+  const result = await checkMcpConnections(workspace, {
+    internetAvailable: false,
+    buildStatus: () => ({
+      local: { status: 'configured', url: 'http://127.0.0.1:3333/mcp' },
+      remote: { status: 'configured', url: 'https://mcp.example.test', external: true },
+    }),
+    discover: async (endpoints) => ({
+      local: { ...endpoints.local, status: 'configured', tools: [], toolError: '401 Unauthorized' },
+    }),
+  });
+  assert.equal(result.ok, false);
+  assert.deepEqual(result.context.endpoints.map(({ name, status, reason }) => ({ name, status, reason })), [
+    { name: 'local', status: 'failed', reason: 'authentication' },
+    { name: 'remote', status: 'skipped', reason: 'internet unavailable' },
+  ]);
+});
+
+test('MCP preflight reports invalid endpoint configuration without aborting startup', async () => {
+  const result = await checkMcpConnections({ name: 'demo', workspacePath: '/tmp/demo', env: {} }, {
+    buildStatus: () => { throw new Error('Unexpected token in mcp.endpoints.json'); },
+  });
+  assert.equal(result.ok, false);
+  assert.equal(result.detail, 'MCP configuration invalid');
+  assert.match(result.context.error, /mcp\.endpoints\.json/);
+});
+
+test('preflight status is setup_required without a valid workspace and runtime failure only degrades', async () => {
+  const previousDir = process.env.WIKI_WORKSPACES_DIR;
+  const root = await mkdtemp(join(tmpdir(), 'wiki-manager-empty-startup-'));
+  process.env.WIKI_WORKSPACES_DIR = root;
+  try {
+    const preflight = await runPreflightChecks({
+      dockerCheck: async () => ({ ok: true }),
+      internetCheck: async () => ({ ok: true }),
+      agentsCheck: async () => null,
+    });
+    assert.equal(preflight.status, 'setup_required');
+    assert.equal(withRuntimePreflight(preflight, { error: 'offline' }).status, 'setup_required');
+    const ready = { gaps: [], status: 'ready', checks: [{ kind: 'docker', ok: true }] };
+    assert.equal(withRuntimePreflight(ready, { error: 'offline' }).status, 'degraded');
+  } finally {
+    if (previousDir === undefined) delete process.env.WIKI_WORKSPACES_DIR;
+    else process.env.WIKI_WORKSPACES_DIR = previousDir;
+  }
+});
+
+test('runChecks presents Internet failure before stopped agents after Docker succeeds', async () => {
+  const gaps = await runChecks({
+    dockerCheck: async () => ({ ok: true }),
+    internetCheck: async () => ({ ok: false, context: { error: 'offline' } }),
+    agentsCheck: async () => ({ kind: 'agents', context: { downServices: ['documents'] } }),
+    workspaceContainersCheck: async () => ({ ok: false, detail: 'stopped' }),
+    mcpCheck: async () => ({ ok: false, detail: 'unavailable' }),
+  });
+  assert.deepEqual(gaps.slice(0, 2).map((gap) => gap.kind), ['network', 'agents']);
+});
+
+test('runChecks still probes MCP endpoints when Docker is unavailable', async () => {
+  await withWorkspace([
+    'llm:',
+    '  provider: openai-compatible',
+    '  baseUrl: http://localhost:8000/v1',
+    '  apiKey: key',
+    '  model: chat-model',
+  ], async () => {
+    const calls = [];
+    await runChecks({
+      dockerCheck: async () => ({ ok: false, context: { dockerUnavailable: true } }),
+      internetCheck: async () => ({ ok: true }),
+      agentsCheck: async () => { calls.push('agents'); return null; },
+      workspaceContainersCheck: async () => { calls.push('containers'); return { ok: true }; },
+      mcpCheck: async () => { calls.push('mcp'); return { ok: true, detail: 'remote connected' }; },
+    });
+    assert.deepEqual(calls, ['mcp']);
+  });
+});
+
+test('checkInternetConnectivity uses a fresh Node process with proxy and CA environment', async () => {
+  const calls = [];
+  const previousProxy = process.env.HTTPS_PROXY;
+  const previousProxyFlag = process.env.NODE_USE_ENV_PROXY;
+  process.env.HTTPS_PROXY = 'http://proxy.test:8080';
+  process.env.NODE_USE_ENV_PROXY = '1';
+  try {
+    const result = await checkInternetConnectivity({
+      url: 'https://connectivity.test/ping',
+      exec: async (...args) => { calls.push(args); return { stdout: '' }; },
+    });
+    assert.equal(result.ok, true);
+    assert.equal(calls.length, 1);
+    assert.equal(calls[0][1].at(-1), 'https://connectivity.test/ping');
+    assert.equal(calls[0][2].env.HTTPS_PROXY, 'http://proxy.test:8080');
+    assert.equal(result.context.proxyEnabled, true);
+  } finally {
+    if (previousProxy === undefined) delete process.env.HTTPS_PROXY;
+    else process.env.HTTPS_PROXY = previousProxy;
+    if (previousProxyFlag === undefined) delete process.env.NODE_USE_ENV_PROXY;
+    else process.env.NODE_USE_ENV_PROXY = previousProxyFlag;
+  }
+});

package/src/core/wikiWorkspace.test.js

@@ -22,3 +22,12 @@ test('wiki-workspace checks runtime pid command before killing', async () => {
   assert.match(script, /if ! runtime_pid_matches; then\n        printf 'refusing to stop pid/);
   assert.match(script, /kill "\$\(cat "\$pid_file"\)"/);
 });
+
+test('wiki-workspace regenerates CA compose overrides instead of retaining removed services', async () => {
+  const script = await readFile(new URL('../../wiki-workspace', import.meta.url), 'utf8');
+
+  assert.doesNotMatch(script, /if \[\[ ! -f "\$override_path" \]\]; then/);
+  assert.match(script, /local tmp_override="\$override_path\.tmp\.\$\$"/);
+  assert.match(script, /mv "\$tmp_override" "\$override_path"/);
+  assert.match(script, /Changes are overwritten on the next compose command/);
+});

package/src/runtime/lifecycle.js

@@ -83,7 +83,7 @@ export async function ensureRuntime({
     if (!forceRestart && !stale && actualCacertPath === expectedCacertPath) {
       return { url, started: false, health: existing, token: auth.token, tokenPath: auth.tokenPath };
     }
-    if (stale) console.error('runtime: source changed since start — restarting for fresh code.');
+    if (stale) console.log('\x1b[32mruntime: source changed since start — restarting for fresh code.\x1b[0m');
     await postRuntimeShutdown({ url, token: auth.token });
     await waitForRuntimeShutdown(url, auth.token, 2500);
   }

package/src/shell/SetupWizard.tsx

@@ -4,6 +4,7 @@ import { join } from 'node:path';
 import { useKeyboard, usePaste } from '@opentui/solid';
 import { createEffect, createMemo, createSignal, For, Show } from 'solid-js';
 import { fallbackModels, normalizeProvider } from '../core/modelFetch.js';
+import { checkInternetConnectivity } from '../core/startupCheck.js';
 import {
   createNewWorkspace,
   deleteWorkspaceAndFiles,
@@ -17,7 +18,7 @@ import {
 import { listWorkspaces, workspacesDir } from '../core/workspaces.js';
 import { loadWikircProfile } from '../core/wikirc.js';
 
-type Gap = { kind: 'agents' | 'workspace' | 'llm' | 'vector'; context?: Record<string, any> };
+type Gap = { kind: 'agents' | 'network' | 'workspace' | 'llm' | 'vector'; context?: Record<string, any> };
 type Mode = 'startup' | 'setup';
 type Step =
   | { kind: 'menu'; title: string; items: Array<{ label: string; value: string; muted?: boolean }> }
@@ -195,6 +196,20 @@ export function SetupWizard(props: {
         noLabel: 'Skip',
       };
     }
+    if (currentRoute === 'network') {
+      const context = currentGap()?.context ?? {};
+      const transport = context.proxyUrl
+        ? `Proxy: ${context.proxyEnabled ? context.proxyUrl : `${context.proxyUrl} (NODE_USE_ENV_PROXY is not enabled)`}`
+        : 'Proxy: direct connection';
+      const certificate = context.cacertPath ? `CA: ${context.cacertPath}` : 'CA: system trust store';
+      return {
+        kind: 'confirm',
+        title: 'Internet connectivity',
+        message: `Could not reach ${context.url ?? 'the connectivity endpoint'}.\n${transport}\n${certificate}\n${context.error ?? ''}`.trim(),
+        yesLabel: 'Retry',
+        noLabel: 'Skip',
+      };
+    }
     if (currentRoute === 'workspace-confirm') {
       return { kind: 'confirm', title: 'Workspace', message: 'No workspace configured.', yesLabel: 'Create', noLabel: 'Skip' };
     }
@@ -337,6 +352,7 @@ export function SetupWizard(props: {
   function startupRoute(gap?: Gap) {
     if (!gap) return 'done';
     if (gap.kind === 'agents') return 'agents';
+    if (gap.kind === 'network') return 'network';
     if (gap.kind === 'workspace') return 'workspace-confirm';
     if (gap.kind === 'llm') return 'llm-provider';
     if (gap.kind === 'vector') return 'vector-confirm';
@@ -527,6 +543,14 @@ export function SetupWizard(props: {
       });
       return;
     }
+    if (currentRoute === 'network') {
+      await runAction(async () => {
+        const result = await checkInternetConnectivity();
+        if (!result.ok) throw new Error(result.context?.error ?? 'Internet connectivity check failed.');
+        nextStartup('Internet connectivity verified');
+      });
+      return;
+    }
     if (currentRoute === 'workspace-confirm') return navigate('workspace-name');
     if (currentRoute === 'vector-rerank') return navigate('vector-rerank-model');
     if (currentRoute === 'vector-confirm') {