@distributionos/cli 0.1.15 → 0.1.17

package/src/cli.js

@@ -1,17 +1,22 @@
+import { spawn } from 'node:child_process';
 import { CLI_LOCAL_VERSION, DEFAULT_API_BASE } from './constants.js';
-import {
-  ensureAnalyticsSite,
-  reportSetupInstallation,
-  reportImplementation,
-  resolveAuthToken,
-  verifyAnalyticsInstall,
-} from './api.js';
+import {
+  ensureAnalyticsSite,
+  reportSetupInstallation,
+  reportImplementation,
+  resolveAuthToken,
+  verifyAnalyticsInstall,
+} from './api.js';
 import { loginWithOAuth } from './oauth.js';
 import { createSetupPlan, formatPlanText } from './plan.js';
 import { applySetupPlan } from './mutate.js';
-import { submitInitialization } from './initialization.js';
-import { compareValidationResults, inspectInstallArtifacts, runValidationPlan } from './validation.js';
+import { submitInitialization } from './initialization.js';
+import { compareValidationResults, inspectInstallArtifacts, runValidationPlan } from './validation.js';
 import { buildSetupReport } from './setup-report.js';
+
+const DISTRIBUTIONOS_MCP_URL = 'https://distributionos.dev/api/mcp';
+const DISTRIBUTIONOS_MCP_NAME = 'distributionos';
+const AGENT_CHOICES = new Set(['codex', 'claude', 'terminal', 'other']);
 
 export async function runCli(argv, runtime) {
   const stdout = runtime.stdout;
@@ -130,32 +135,35 @@ export async function runCli(argv, runtime) {
     return 1;
   }
 
-  if (!args.appId) {
-    stderr.write('Missing required --app <appId>.\n\n');
-    stderr.write(helpText());
-    return 1;
-  }
-
-  if (!args.noFetch) {
-    const authReady = await ensureCliAuth({ args, runtime, stderr });
-    if (!authReady) return 1;
+  if (!args.appId) {
+    stderr.write('Missing required --app <appId>.\n\n');
+    stderr.write(helpText());
+    return 1;
+  }
+
+  const agentSetup = await ensureRequestedAgentSetup({ args, runtime, stdout, stderr });
+  if (!agentSetup.ok) return 1;
+
+  if (!args.noFetch) {
+    const authReady = await ensureCliAuth({ args, runtime, stderr });
+    if (!authReady) return 1;
   }
 
-  let plan = await createSetupPlan({
-    appId: args.appId,
-    cwd: args.cwd ?? runtime.cwd,
-    apiBase: args.apiBase ?? DEFAULT_API_BASE,
+  let plan = await createSetupPlan({
+    appId: args.appId,
+    cwd: args.cwd ?? runtime.cwd,
+    apiBase: args.apiBase ?? DEFAULT_API_BASE,
     env: runtime.env,
     fetch: runtime.fetch,
-    noFetch: args.noFetch,
-    apply: args.apply,
-  });
-  plan.setupReport = await submitSetupReportSafely({
-    args,
-    runtime,
-    plan,
-    phase: 'plan',
-  });
+    noFetch: args.noFetch,
+    apply: args.apply,
+  });
+  plan.setupReport = await submitSetupReportSafely({
+    args,
+    runtime,
+    plan,
+    phase: 'plan',
+  });
 
   if (!args.apply && !args.yes) {
     stdout.write(args.json ? `${JSON.stringify(plan, null, 2)}\n` : formatPlanText(plan));
@@ -165,19 +173,19 @@ export async function runCli(argv, runtime) {
     args.apply = true;
   }
 
-  if (args.yes) {
-    args.apply = true;
-  }
-
-  if (args.apply && hasRemoteAccessBlock(plan)) {
-    stderr.write(formatRemoteAccessBlock(plan));
-    return 1;
-  }
-
-  if (args.apply && plan.repo.git.dirty && !args.allowDirty) {
-    stderr.write('Refusing to apply changes to a dirty worktree. Commit/stash changes or pass --allow-dirty.\n');
-    return 1;
-  }
+  if (args.yes) {
+    args.apply = true;
+  }
+
+  if (args.apply && hasRemoteAccessBlock(plan)) {
+    stderr.write(formatRemoteAccessBlock(plan));
+    return 1;
+  }
+
+  if (args.apply && plan.repo.git.dirty && !args.allowDirty) {
+    stderr.write('Refusing to apply changes to a dirty worktree. Commit/stash changes or pass --allow-dirty.\n');
+    return 1;
+  }
 
   if (args.apply && !args.skipAnalytics) {
     const ensured = await ensureAnalyticsSite({
@@ -193,21 +201,21 @@ export async function runCli(argv, runtime) {
     }
   }
 
-  plan = await createSetupPlan({
-    appId: args.appId,
-    cwd: args.cwd ?? runtime.cwd,
-    apiBase: args.apiBase ?? DEFAULT_API_BASE,
+  plan = await createSetupPlan({
+    appId: args.appId,
+    cwd: args.cwd ?? runtime.cwd,
+    apiBase: args.apiBase ?? DEFAULT_API_BASE,
     env: runtime.env,
     fetch: runtime.fetch,
-    noFetch: args.noFetch,
-    apply: args.apply,
-  });
-  plan.setupReport = await submitSetupReportSafely({
-    args,
-    runtime,
-    plan,
-    phase: args.apply ? 'apply_started' : 'plan',
-  });
+    noFetch: args.noFetch,
+    apply: args.apply,
+  });
+  plan.setupReport = await submitSetupReportSafely({
+    args,
+    runtime,
+    plan,
+    phase: args.apply ? 'apply_started' : 'plan',
+  });
 
   if (!args.apply) {
     stdout.write(args.json ? `${JSON.stringify(plan, null, 2)}\n` : formatPlanText(plan));
@@ -219,119 +227,120 @@ export async function runCli(argv, runtime) {
     const changes = await applySetupPlan(plan, {
       allowDirty: args.allowDirty,
       skipAnalytics: args.skipAnalytics,
-    });
-    const postValidation = args.skipValidate ? [] : await runValidationPlan(plan);
-    const validation = compareValidationResults(baselineValidation, postValidation);
-    const inspection = args.skipAnalytics ? [] : await inspectInstallArtifacts(plan);
-    const completedPlan = await createSetupPlan({
-      appId: args.appId,
-      cwd: args.cwd ?? runtime.cwd,
-      apiBase: args.apiBase ?? DEFAULT_API_BASE,
-      env: runtime.env,
-      fetch: runtime.fetch,
-      noFetch: args.noFetch,
-      apply: true,
-    });
-    completedPlan.setupReport = await submitSetupReportSafely({
-      args,
-      runtime,
-      plan: completedPlan,
-      phase: 'apply_completed',
-      details: {
-        changes,
+    });
+    const postValidation = args.skipValidate ? [] : await runValidationPlan(plan);
+    const validation = compareValidationResults(baselineValidation, postValidation);
+    const inspection = args.skipAnalytics ? [] : await inspectInstallArtifacts(plan);
+    const completedPlan = await createSetupPlan({
+      appId: args.appId,
+      cwd: args.cwd ?? runtime.cwd,
+      apiBase: args.apiBase ?? DEFAULT_API_BASE,
+      env: runtime.env,
+      fetch: runtime.fetch,
+      noFetch: args.noFetch,
+      apply: true,
+    });
+    completedPlan.setupReport = await submitSetupReportSafely({
+      args,
+      runtime,
+      plan: completedPlan,
+      phase: 'apply_completed',
+      details: {
+        changes,
         validation,
         inspection,
-        requiresAgentRestart: changes.some((change) => change.type === 'mcp' && change.changed),
+        requiresAgentRestart: Boolean(agentSetup.requiresAgentRestart) ||
+          changes.some((change) => (change.type === 'mcp' || change.type === 'codex-mcp') && change.changed),
       },
     });
-    const token = await resolveAuthToken({
-      env: runtime.env,
-      apiBase: args.apiBase ?? DEFAULT_API_BASE,
-      appId: args.appId,
-      fetchImpl: runtime.fetch,
+    const token = await resolveAuthToken({
+      env: runtime.env,
+      apiBase: args.apiBase ?? DEFAULT_API_BASE,
+      appId: args.appId,
+      fetchImpl: runtime.fetch,
     });
-    const initialization = token
-      ? await submitInitialization({
-        plan: completedPlan,
-        token: token.value,
-        apiBase: args.apiBase ?? DEFAULT_API_BASE,
-        fetchImpl: runtime.fetch,
-        domain: args.domain,
-      })
-      : null;
-
-    stdout.write(args.json
-      ? `${JSON.stringify({ plan: completedPlan, changes, initialization, validation, inspection }, null, 2)}\n`
-      : formatApplyResult(completedPlan, changes, initialization, validation, inspection, args.skipValidate, args.apiBase ?? DEFAULT_API_BASE));
+    const initialization = token
+      ? await submitInitialization({
+        plan: completedPlan,
+        token: token.value,
+        apiBase: args.apiBase ?? DEFAULT_API_BASE,
+        fetchImpl: runtime.fetch,
+        domain: args.domain,
+      })
+      : null;
+
+    stdout.write(args.json
+      ? `${JSON.stringify({ plan: completedPlan, changes, initialization, validation, inspection }, null, 2)}\n`
+      : formatApplyResult(completedPlan, changes, initialization, validation, inspection, args.skipValidate, args.apiBase ?? DEFAULT_API_BASE));
     return hasBlockingApplyFailure(validation, inspection) ? 1 : 0;
-  } catch (error) {
-    await submitSetupReportSafely({
-      args,
-      runtime,
-      plan,
-      phase: 'apply_failed',
-      details: {
-        applyResult: {
-          validation: [{
-            name: 'apply',
-            status: 'failed',
-          }],
-        },
-      },
-    });
-    stderr.write(`${error instanceof Error ? error.message : 'Setup apply failed'}\n`);
-    return 1;
-  }
-}
-
-async function submitSetupReportSafely({ args, runtime, plan, phase, details = {} }) {
-  if (args.noFetch || args.skipSetupReport) {
-    return null;
-  }
-
-  try {
-    const report = await buildSetupReport(plan, phase, details);
-    const result = await reportSetupInstallation({
-      appId: args.appId,
-      apiBase: args.apiBase ?? DEFAULT_API_BASE,
-      env: runtime.env,
-      fetch: runtime.fetch,
-      report,
-    });
-    return {
-      status: 'submitted',
-      phase,
-      result,
-    };
-  } catch (error) {
-    return {
-      status: 'failed',
-      phase,
-      error: error instanceof Error ? error.message : 'Setup report failed',
-    };
-  }
-}
-
-function hasBlockingApplyFailure(validation, inspection) {
-  return validation.some((result) => result.introducedFailure) ||
-    inspection.some((result) => result.status === 'failed');
-}
-
-function hasRemoteAccessBlock(plan) {
-  return plan.remote?.access?.reason === 'subscription_required';
-}
-
-function formatRemoteAccessBlock(plan) {
-  const billingUrl = plan.remote?.access?.billingUrl ?? `${plan.apiBase ?? DEFAULT_API_BASE}/dashboard/account/billing`;
-  return [
-    'DistributionOS setup requires an active Builder or Distributor subscription before applying changes.',
-    `Manage billing: ${billingUrl}`,
-    'No files were changed.',
-    '',
-  ].join('\n');
-}
-
-export function parseArgs(rawArgs) {
+  } catch (error) {
+    await submitSetupReportSafely({
+      args,
+      runtime,
+      plan,
+      phase: 'apply_failed',
+      details: {
+        applyResult: {
+          validation: [{
+            name: 'apply',
+            status: 'failed',
+          }],
+        },
+      },
+    });
+    stderr.write(`${error instanceof Error ? error.message : 'Setup apply failed'}\n`);
+    return 1;
+  }
+}
+
+async function submitSetupReportSafely({ args, runtime, plan, phase, details = {} }) {
+  if (args.noFetch || args.skipSetupReport) {
+    return null;
+  }
+
+  try {
+    const report = await buildSetupReport(plan, phase, details);
+    const result = await reportSetupInstallation({
+      appId: args.appId,
+      apiBase: args.apiBase ?? DEFAULT_API_BASE,
+      env: runtime.env,
+      fetch: runtime.fetch,
+      report,
+    });
+    return {
+      status: 'submitted',
+      phase,
+      result,
+    };
+  } catch (error) {
+    return {
+      status: 'failed',
+      phase,
+      error: error instanceof Error ? error.message : 'Setup report failed',
+    };
+  }
+}
+
+function hasBlockingApplyFailure(validation, inspection) {
+  return validation.some((result) => result.introducedFailure) ||
+    inspection.some((result) => result.status === 'failed');
+}
+
+function hasRemoteAccessBlock(plan) {
+  return plan.remote?.access?.reason === 'subscription_required';
+}
+
+function formatRemoteAccessBlock(plan) {
+  const billingUrl = plan.remote?.access?.billingUrl ?? `${plan.apiBase ?? DEFAULT_API_BASE}/dashboard/account/billing`;
+  return [
+    'DistributionOS setup requires an active Builder or Distributor subscription before applying changes.',
+    `Manage billing: ${billingUrl}`,
+    'No files were changed.',
+    '',
+  ].join('\n');
+}
+
+export function parseArgs(rawArgs) {
   const parsed = {
     command: null,
     appId: null,
@@ -343,12 +352,14 @@ export function parseArgs(rawArgs) {
     apply: false,
     allowDirty: false,
     skipAnalytics: false,
-    skipValidate: false,
-    noOpen: false,
+    skipValidate: false,
+    noOpen: false,
     noLogin: false,
     skipSetupReport: false,
+    skipAgentSetup: false,
     yes: false,
-    url: null,
+    agent: null,
+    url: null,
     contentId: null,
     contractVersion: null,
     artifactId: null,
@@ -379,11 +390,14 @@ export function parseArgs(rawArgs) {
     else if (arg === '--apply') parsed.apply = true;
     else if (arg === '--allow-dirty') parsed.allowDirty = true;
     else if (arg === '--skip-analytics') parsed.skipAnalytics = true;
-    else if (arg === '--skip-validate') parsed.skipValidate = true;
+    else if (arg === '--skip-validate') parsed.skipValidate = true;
     else if (arg === '--no-open') parsed.noOpen = true;
     else if (arg === '--no-login') parsed.noLogin = true;
     else if (arg === '--skip-setup-report') parsed.skipSetupReport = true;
+    else if (arg === '--skip-agent-setup') parsed.skipAgentSetup = true;
     else if (arg === '--yes' || arg === '-y') parsed.yes = true;
+    else if (arg === '--agent') parsed.agent = parseAgent(args[++index] ?? null);
+    else if (arg.startsWith('--agent=')) parsed.agent = parseAgent(arg.slice('--agent='.length));
     else if (arg === '--app') parsed.appId = args[++index] ?? null;
     else if (arg.startsWith('--app=')) parsed.appId = arg.slice('--app='.length);
     else if (arg === '--cwd') parsed.cwd = args[++index] ?? null;
@@ -412,18 +426,19 @@ export function parseArgs(rawArgs) {
   return parsed;
 }
 
-function helpText() {
-  return [
-    'DistributionOS CLI',
-    '',
+function helpText() {
+  return [
+    'DistributionOS CLI',
+    '',
     'Usage:',
-    '  distributionos setup --app <appId> [--api-base <url>] [--cwd <path>] [--json] [--no-fetch]',
-    '  distributionos setup --app <appId> --apply [--domain <domain>] [--allow-dirty] [--skip-setup-report]',
+    '  distributionos setup --app <appId> [--agent codex|claude|terminal|other] [--api-base <url>] [--cwd <path>] [--json] [--no-fetch]',
+    '  distributionos setup --app <appId> --apply [--agent codex|claude|terminal|other] [--domain <domain>] [--allow-dirty] [--skip-agent-setup] [--skip-setup-report]',
     '  distributionos login --app <appId> [--api-base <url>]',
     '  distributionos verify --app <appId> --url <liveUrl> [--content-id <id>]',
     '  distributionos report-implementation --app <appId> --artifact <artifactId> [--url <liveUrl>] [--summary <text>]',
     '',
     'Default mode reviews the setup plan without changing files. Run again with --apply after the plan looks right.',
+    'For Codex, --agent codex registers the DistributionOS MCP server and runs codex mcp login before repo setup.',
     'If the repo has existing uncommitted changes, commit/stash first or use --allow-dirty when you recognize them.',
     '',
     'Authentication:',
@@ -431,8 +446,158 @@ function helpText() {
     '  DISTRIBUTIONOS_API_KEY, DOS_API_KEY, or DISTRIBUTIONOS_TOKEN are advanced fallbacks.',
     '  Tokens are never printed or written to committed files.',
     '',
-  ].join('\n');
-}
+  ].join('\n');
+}
+
+function parseAgent(value) {
+  const normalized = typeof value === 'string' ? value.trim().toLowerCase() : '';
+  if (!AGENT_CHOICES.has(normalized)) {
+    throw new Error('Invalid --agent value. Use codex, claude, terminal, or other.');
+  }
+  return normalized;
+}
+
+async function ensureRequestedAgentSetup({ args, runtime, stdout, stderr }) {
+  if (args.skipAgentSetup || args.agent !== 'codex') {
+    return { ok: true, requiresAgentRestart: false };
+  }
+
+  stdout.write('Codex MCP setup\n');
+  const getResult = await runCodexCommand(runtime, ['mcp', 'get', DISTRIBUTIONOS_MCP_NAME]);
+  if (getResult.ok) {
+    if (!getResult.stdout.includes(DISTRIBUTIONOS_MCP_URL)) {
+      stderr.write([
+        'Codex already has a distributionos MCP server, but it does not point to the expected DistributionOS URL.',
+        `Expected: ${DISTRIBUTIONOS_MCP_URL}`,
+        'Run `codex mcp remove distributionos`, then rerun this setup command.',
+        '',
+      ].join('\n'));
+      return { ok: false, requiresAgentRestart: false };
+    }
+    stdout.write('- DistributionOS MCP server is already registered in Codex.\n');
+  } else if (isCommandMissing(getResult.error)) {
+    stderr.write([
+      'Codex CLI was not found, so DistributionOS cannot connect Codex automatically.',
+      'Open this repo in Codex Desktop or install the Codex CLI, then rerun setup.',
+      '',
+    ].join('\n'));
+    return { ok: false, requiresAgentRestart: false };
+  } else {
+    stdout.write('- Adding DistributionOS MCP server to Codex.\n');
+    const addResult = await runCodexCommand(runtime, ['mcp', 'add', DISTRIBUTIONOS_MCP_NAME, '--url', DISTRIBUTIONOS_MCP_URL], { stream: true });
+    if (!addResult.ok) {
+      stderr.write(formatCodexCommandFailure('codex mcp add distributionos', addResult));
+      return { ok: false, requiresAgentRestart: false };
+    }
+  }
+
+  stdout.write('- Starting Codex MCP OAuth. Approve the browser sign-in if Codex asks.\n');
+  const loginResult = await runCodexCommand(runtime, ['mcp', 'login', DISTRIBUTIONOS_MCP_NAME], { stream: true });
+  if (!loginResult.ok) {
+    stderr.write(formatCodexCommandFailure('codex mcp login distributionos', loginResult));
+    return { ok: false, requiresAgentRestart: true };
+  }
+  stdout.write('- Codex MCP OAuth step completed.\n\n');
+  return { ok: true, requiresAgentRestart: true };
+}
+
+function formatCodexCommandFailure(label, result) {
+  const output = oneLine(result.stderr || result.stdout || result.error?.message || '');
+  return [
+    `${label} did not complete, so Codex cannot use DistributionOS tools yet.`,
+    output ? `Last output: ${output}` : '',
+    'Run the command above manually, approve the browser sign-in, then rerun DistributionOS setup.',
+    '',
+  ].filter(Boolean).join('\n');
+}
+
+function isCommandMissing(error) {
+  const message = error?.message ?? '';
+  const stderr = error?.stderr ?? '';
+  return (
+    error?.code === 'ENOENT' ||
+    error?.code === 'EPERM' ||
+    /spawn\s+(ENOENT|EPERM)/i.test(message) ||
+    /not recognized as an internal/i.test(message) ||
+    /not recognized as an internal/i.test(stderr)
+  );
+}
+
+async function runCodexCommand(runtime, args, options = {}) {
+  return runExternalCommand(runtime, 'codex', args, options);
+}
+
+async function runExternalCommand(runtime, command, args, options = {}) {
+  if (typeof runtime.execFile === 'function') {
+    try {
+      const result = await runtime.execFile(command, args, options);
+      return {
+        ok: true,
+        stdout: result?.stdout ?? '',
+        stderr: result?.stderr ?? '',
+      };
+    } catch (error) {
+      return {
+        ok: false,
+        stdout: error?.stdout ?? '',
+        stderr: error?.stderr ?? '',
+        error,
+      };
+    }
+  }
+
+  const resolved = resolveCommand(command, args, runtime);
+  return new Promise((resolve) => {
+    let stdoutText = '';
+    let stderrText = '';
+    let child;
+    try {
+      child = spawn(resolved.command, resolved.args, {
+        cwd: runtime.cwd,
+        env: runtime.env,
+        windowsHide: true,
+        stdio: ['inherit', 'pipe', 'pipe'],
+      });
+    } catch (error) {
+      resolve({ ok: false, stdout: '', stderr: '', error });
+      return;
+    }
+
+    child.stdout?.on('data', (chunk) => {
+      const text = String(chunk);
+      stdoutText += text;
+      if (options.stream) runtime.stdout?.write(text);
+    });
+    child.stderr?.on('data', (chunk) => {
+      const text = String(chunk);
+      stderrText += text;
+      if (options.stream) runtime.stderr?.write(text);
+    });
+    child.on('error', (error) => {
+      resolve({ ok: false, stdout: stdoutText, stderr: stderrText, error });
+    });
+    child.on('close', (code) => {
+      const ok = code === 0;
+      resolve({
+        ok,
+        stdout: stdoutText,
+        stderr: stderrText,
+        error: ok ? null : Object.assign(new Error(`${command} exited with code ${code}`), { code }),
+      });
+    });
+  });
+}
+
+function resolveCommand(command, args, runtime) {
+  const platform = runtime.platform ?? process.platform;
+  if (platform === 'win32') {
+    return {
+      command: runtime.env?.ComSpec ?? process.env.ComSpec ?? 'cmd.exe',
+      args: ['/d', '/s', '/c', command, ...args],
+    };
+  }
+  return { command, args };
+}
 
 async function ensureCliAuth({ args, runtime, stderr }) {
   const existingToken = await resolveAuthToken({
@@ -528,13 +693,13 @@ function formatReportResult(result) {
   return `${lines.join('\n')}\n`;
 }
 
-function formatApplyResult(plan, changes, initialization, validation, inspection, skipValidate, apiBase = DEFAULT_API_BASE) {
-  const reviewUrl = initialization?.reviewUrl
-    ? absoluteDistributionOsUrl(initialization.reviewUrl, apiBase)
-    : null;
-  const lines = [
-    formatPlanText({ ...plan, mode: 'apply' }).trimEnd(),
-    '',
+function formatApplyResult(plan, changes, initialization, validation, inspection, skipValidate, apiBase = DEFAULT_API_BASE) {
+  const reviewUrl = initialization?.reviewUrl
+    ? absoluteDistributionOsUrl(initialization.reviewUrl, apiBase)
+    : null;
+  const lines = [
+    formatPlanText({ ...plan, mode: 'apply' }).trimEnd(),
+    '',
     'Applied changes',
   ];
 
@@ -548,9 +713,9 @@ function formatApplyResult(plan, changes, initialization, validation, inspection
     }
   }
 
-  lines.push(reviewUrl
-    ? `- Initialization submitted. Review URL: ${reviewUrl}`
-    : '- Initialization was not submitted because no auth token was available.');
+  lines.push(reviewUrl
+    ? `- Initialization submitted. Review URL: ${reviewUrl}`
+    : '- Initialization was not submitted because no auth token was available.');
 
   lines.push('', 'Validation');
   if (skipValidate) {
@@ -579,37 +744,39 @@ function formatApplyResult(plan, changes, initialization, validation, inspection
     for (const result of inspection) {
       lines.push(`- ${result.name}: ${result.status} - ${result.message}`);
     }
-  }
-  lines.push('- Nothing was committed, pushed, or deployed.');
-  lines.push('', 'Next step');
-  if (reviewUrl) {
-    lines.push(
-      '- Open this DistributionOS review page now:',
-      `  ${reviewUrl}`,
-      '- If .mcp.json was created or updated, restart or reconnect your agent session so it can load the DistributionOS MCP server.',
-      '- On the review page, copy the tool-list prompt first so your agent can show whether DistributionOS MCP loaded.',
-      '- If your agent only sees DistributionOS authentication tools, copy the auth prompt from the review page and complete OAuth before continuing.',
-      '- Then copy the verification prompt from the review page and ask your agent to call check_distributionos_connection, get_agent_instructions, and get_analytics_summary.',
-      '- DistributionOS will wait for a successful app-scoped MCP call before you continue to Brain Doc review.',
-      '- After review, come back to this repo and inspect git diff before committing, pushing, or deploying.',
-    );
-  } else {
-    lines.push(
-      '- Reconnect DistributionOS OAuth or provide an app-scoped token, then rerun setup so initialization can be submitted.',
-      '- No DistributionOS review page is ready yet.',
-    );
-  }
-  return `${lines.join('\n')}\n`;
-}
-
-function oneLine(value) {
-  return String(value).split(/\r?\n/).filter(Boolean).slice(-1)[0]?.slice(0, 240) ?? '';
-}
-
-function absoluteDistributionOsUrl(pathOrUrl, apiBase) {
-  try {
-    return new URL(pathOrUrl, apiBase || DEFAULT_API_BASE).toString();
-  } catch {
-    return String(pathOrUrl);
-  }
-}
+  }
+  lines.push('- Nothing was committed, pushed, or deployed.');
+  lines.push('', 'Next step');
+  if (reviewUrl) {
+    lines.push(
+      '- Open this DistributionOS review page now:',
+      `  ${reviewUrl}`,
+      '- Codex users: make sure `codex mcp add distributionos --url https://distributionos.dev/api/mcp` and `codex mcp login distributionos` have run, then fully quit and reopen Codex Desktop before checking the connection.',
+      '- Claude Code users: if .mcp.json was created or updated, restart or reconnect Claude Code and approve the project MCP server if asked.',
+      '- Other MCP-aware agents: reconnect the agent from this repo so it can load the DistributionOS MCP server.',
+      '- On the review page, copy the connection check prompt into the fresh/reconnected agent chat.',
+      '- If your agent only sees DistributionOS authentication tools, copy the auth prompt from the review page and complete OAuth before continuing.',
+      '- Then copy the verification prompt from the review page and ask your agent to call check_distributionos_connection, get_agent_instructions, and get_analytics_summary.',
+      '- DistributionOS will wait for a successful app-scoped MCP call before you continue to Brain Doc review.',
+      '- After review, come back to this repo and inspect git diff before committing, pushing, or deploying.',
+    );
+  } else {
+    lines.push(
+      '- Reconnect DistributionOS OAuth or provide an app-scoped token, then rerun setup so initialization can be submitted.',
+      '- No DistributionOS review page is ready yet.',
+    );
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+function oneLine(value) {
+  return String(value).split(/\r?\n/).filter(Boolean).slice(-1)[0]?.slice(0, 240) ?? '';
+}
+
+function absoluteDistributionOsUrl(pathOrUrl, apiBase) {
+  try {
+    return new URL(pathOrUrl, apiBase || DEFAULT_API_BASE).toString();
+  } catch {
+    return String(pathOrUrl);
+  }
+}