@distributionos/cli 0.1.17 → 0.1.19

package/README.md

@@ -22,8 +22,12 @@ distributionos setup --app <appId> --apply
 distributionos login --app <appId>
 distributionos verify --app <appId> --url <liveUrl> [--content-id <id>]
 distributionos report-implementation --app <appId> --artifact <artifactId> [--url <liveUrl>]
+distributionos start-work --app <appId> [--task-type <type>] [--artifact <artifactId>] [--dedup-key <key>]
+distributionos complete-work --app <appId> --work-session <id> --status <status> --summary <text> [--url <liveUrl>] [--file <path>] [--pr-url <url>]
 ```
 
+`start-work` and `complete-work` are compact fallbacks for agents or terminals that cannot call the MCP `start_agent_work` / `complete_agent_work` tools directly. Use one work session per meaningful task, not per prompt.
+
 ## Safety
 
 - Uses DistributionOS MCP OAuth as the happy path.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@distributionos/cli",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "DistributionOS repo setup CLI for agent onboarding and first-party analytics.",
   "homepage": "https://distributionos.dev",
   "repository": {

package/src/api.js

@@ -252,6 +252,65 @@ export async function reportImplementation(input) {
   return body?.data ?? body;
 }
 
+export async function startAgentWork(input) {
+  const token = await resolveAuthToken({
+    env: input.env,
+    apiBase: input.apiBase ?? DEFAULT_API_BASE,
+    appId: input.appId,
+    fetchImpl: input.fetch,
+  });
+  if (!token) {
+    throw new Error('No stored OAuth token or env token was available.');
+  }
+
+  const apiBase = normalizeApiBase(input.apiBase ?? DEFAULT_API_BASE);
+  const response = await input.fetch(`${apiBase}/api/v1/apps/${encodeURIComponent(input.appId)}/agent-work`, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${token.value}`,
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+    },
+    body: JSON.stringify(input.payload),
+  });
+  const body = await response.json().catch(() => null);
+  if (!response.ok || body?.success === false) {
+    throw new Error(body?.error || `Agent work start failed with HTTP ${response.status}`);
+  }
+  return body?.data ?? body;
+}
+
+export async function completeAgentWork(input) {
+  const token = await resolveAuthToken({
+    env: input.env,
+    apiBase: input.apiBase ?? DEFAULT_API_BASE,
+    appId: input.appId,
+    fetchImpl: input.fetch,
+  });
+  if (!token) {
+    throw new Error('No stored OAuth token or env token was available.');
+  }
+  if (!input.workSessionId) {
+    throw new Error('workSessionId is required.');
+  }
+
+  const apiBase = normalizeApiBase(input.apiBase ?? DEFAULT_API_BASE);
+  const response = await input.fetch(`${apiBase}/api/v1/apps/${encodeURIComponent(input.appId)}/agent-work/${encodeURIComponent(input.workSessionId)}/complete`, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${token.value}`,
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+    },
+    body: JSON.stringify(input.payload),
+  });
+  const body = await response.json().catch(() => null);
+  if (!response.ok || body?.success === false) {
+    throw new Error(body?.error || `Agent work closeout failed with HTTP ${response.status}`);
+  }
+  return body?.data ?? body;
+}
+
 async function fetchJson({ fetchImpl, apiBase, token, path }) {
   if (typeof fetchImpl !== 'function') {
     throw new Error('fetch is unavailable in this Node runtime');

package/src/bootstrap.js

@@ -22,9 +22,11 @@ export function buildLocalBootstrapBlock(version = CURRENT_BOOTSTRAP_VERSION, ap
     `<!-- DISTRIBUTIONOS:START version=${version}${appIdAttribute} -->`,
     '## DistributionOS Agent Sync',
     '',
-    'This repo is linked to DistributionOS.',
-    '',
-    'Hard preflight: before editing files, creating assets, generating images, creating HyperFrames launch/demo videos, or changing copy for SEO, blog, launch, content, visual asset, competitor, social, email, or growth work, fetch the current instructions from DistributionOS:',
+    'This repo is linked to DistributionOS.',
+    '',
+    'Session preflight: when starting a fresh agent chat in this repo, call check_distributionos_connection first, then fetch the current instructions below. If DistributionOS returns setupUpdate or setupUpdateGuidance with a status other than current or not_installed, tell the user the repo has a setup update available, show the review command, and run the apply command only after the user approves.',
+    '',
+    'Hard preflight: before editing files, creating assets, generating images, creating HyperFrames launch/demo videos, or changing copy for SEO, blog, launch, content, visual asset, competitor, social, email, or growth work, fetch the current instructions from DistributionOS:',
     '',
     instructionCall,
     '',

package/src/cli.js

@@ -1,10 +1,15 @@
-import { spawn } from 'node:child_process';
-import { CLI_LOCAL_VERSION, DEFAULT_API_BASE } from './constants.js';
+import { spawn } from 'node:child_process';
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { CLI_LOCAL_VERSION, DEFAULT_API_BASE } from './constants.js';
 import {
   ensureAnalyticsSite,
+  completeAgentWork,
   reportSetupInstallation,
   reportImplementation,
   resolveAuthToken,
+  startAgentWork,
   verifyAnalyticsInstall,
 } from './api.js';
 import { loginWithOAuth } from './oauth.js';
@@ -12,11 +17,11 @@ import { createSetupPlan, formatPlanText } from './plan.js';
 import { applySetupPlan } from './mutate.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']);
+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;
@@ -129,24 +134,92 @@ export async function runCli(argv, runtime) {
     }
   }
 
+  if (args.command === 'start-work') {
+    if (!args.appId) {
+      stderr.write('Missing required --app <appId>.\n\n');
+      stderr.write(helpText());
+      return 1;
+    }
+
+    const authReady = await ensureCliAuth({ args, runtime, stderr });
+    if (!authReady) return 1;
+
+    try {
+      const result = await startAgentWork({
+        appId: args.appId,
+        apiBase: args.apiBase ?? DEFAULT_API_BASE,
+        env: runtime.env,
+        fetch: runtime.fetch,
+        payload: buildStartWorkPayload(args),
+      });
+      stdout.write(args.json ? `${JSON.stringify(result, null, 2)}\n` : formatStartWorkResult(result));
+      return 0;
+    } catch (error) {
+      stderr.write(`${error instanceof Error ? error.message : 'Agent work start failed'}\n`);
+      return 1;
+    }
+  }
+
+  if (args.command === 'complete-work') {
+    if (!args.appId) {
+      stderr.write('Missing required --app <appId>.\n\n');
+      stderr.write(helpText());
+      return 1;
+    }
+    if (!args.workSessionId) {
+      stderr.write('Missing required --work-session <workSessionId>.\n\n');
+      stderr.write(helpText());
+      return 1;
+    }
+    if (!args.status) {
+      stderr.write('Missing required --status <completed|shipped|reported|blocked|skipped|no_op|failed>.\n\n');
+      stderr.write(helpText());
+      return 1;
+    }
+    if (args.status !== 'no_op' && !args.summary) {
+      stderr.write('Missing required --summary <text> unless --status no_op is used.\n\n');
+      stderr.write(helpText());
+      return 1;
+    }
+
+    const authReady = await ensureCliAuth({ args, runtime, stderr });
+    if (!authReady) return 1;
+
+    try {
+      const result = await completeAgentWork({
+        appId: args.appId,
+        workSessionId: args.workSessionId,
+        apiBase: args.apiBase ?? DEFAULT_API_BASE,
+        env: runtime.env,
+        fetch: runtime.fetch,
+        payload: buildCompleteWorkPayload(args),
+      });
+      stdout.write(args.json ? `${JSON.stringify(result, null, 2)}\n` : formatCompleteWorkResult(result));
+      return 0;
+    } catch (error) {
+      stderr.write(`${error instanceof Error ? error.message : 'Agent work closeout failed'}\n`);
+      return 1;
+    }
+  }
+
   if (args.command !== 'setup') {
     stderr.write(`Unknown command: ${args.command}\n\n`);
     stderr.write(helpText());
     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;
+  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({
@@ -247,12 +320,12 @@ export async function runCli(argv, runtime) {
       phase: 'apply_completed',
       details: {
         changes,
-        validation,
-        inspection,
-        requiresAgentRestart: Boolean(agentSetup.requiresAgentRestart) ||
-          changes.some((change) => (change.type === 'mcp' || change.type === 'codex-mcp') && change.changed),
-      },
-    });
+        validation,
+        inspection,
+        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,
@@ -354,17 +427,32 @@ export function parseArgs(rawArgs) {
     skipAnalytics: false,
     skipValidate: false,
     noOpen: false,
-    noLogin: false,
-    skipSetupReport: false,
-    skipAgentSetup: false,
-    yes: false,
-    agent: null,
-    url: null,
+    noLogin: false,
+    skipSetupReport: false,
+    skipAgentSetup: false,
+    yes: false,
+    agent: null,
+    url: null,
     contentId: null,
     contractVersion: null,
     artifactId: null,
+    sourceArtifactId: null,
+    workSessionId: null,
+    taskType: null,
+    dedupKey: null,
     status: null,
     summary: null,
+    commitSha: null,
+    prUrl: null,
+    deploymentUrl: null,
+    deploymentId: null,
+    implementedType: null,
+    changedFiles: [],
+    changedRoutes: [],
+    liveUrls: [],
+    unknowns: [],
+    risks: [],
+    nextSteps: [],
     analyticsOptOutReason: null,
     help: false,
     version: false,
@@ -391,13 +479,13 @@ export function parseArgs(rawArgs) {
     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 === '--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 === '--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;
@@ -414,10 +502,41 @@ export function parseArgs(rawArgs) {
     else if (arg.startsWith('--contract-version=')) parsed.contractVersion = arg.slice('--contract-version='.length);
     else if (arg === '--artifact') parsed.artifactId = args[++index] ?? null;
     else if (arg.startsWith('--artifact=')) parsed.artifactId = arg.slice('--artifact='.length);
+    else if (arg === '--source-artifact') parsed.sourceArtifactId = args[++index] ?? null;
+    else if (arg.startsWith('--source-artifact=')) parsed.sourceArtifactId = arg.slice('--source-artifact='.length);
+    else if (arg === '--work-session' || arg === '--session') parsed.workSessionId = args[++index] ?? null;
+    else if (arg.startsWith('--work-session=')) parsed.workSessionId = arg.slice('--work-session='.length);
+    else if (arg.startsWith('--session=')) parsed.workSessionId = arg.slice('--session='.length);
+    else if (arg === '--task-type') parsed.taskType = args[++index] ?? null;
+    else if (arg.startsWith('--task-type=')) parsed.taskType = arg.slice('--task-type='.length);
+    else if (arg === '--dedup-key') parsed.dedupKey = args[++index] ?? null;
+    else if (arg.startsWith('--dedup-key=')) parsed.dedupKey = arg.slice('--dedup-key='.length);
     else if (arg === '--status') parsed.status = args[++index] ?? null;
     else if (arg.startsWith('--status=')) parsed.status = arg.slice('--status='.length);
     else if (arg === '--summary') parsed.summary = args[++index] ?? null;
     else if (arg.startsWith('--summary=')) parsed.summary = arg.slice('--summary='.length);
+    else if (arg === '--commit') parsed.commitSha = args[++index] ?? null;
+    else if (arg.startsWith('--commit=')) parsed.commitSha = arg.slice('--commit='.length);
+    else if (arg === '--pr-url') parsed.prUrl = args[++index] ?? null;
+    else if (arg.startsWith('--pr-url=')) parsed.prUrl = arg.slice('--pr-url='.length);
+    else if (arg === '--deployment-url') parsed.deploymentUrl = args[++index] ?? null;
+    else if (arg.startsWith('--deployment-url=')) parsed.deploymentUrl = arg.slice('--deployment-url='.length);
+    else if (arg === '--deployment-id') parsed.deploymentId = args[++index] ?? null;
+    else if (arg.startsWith('--deployment-id=')) parsed.deploymentId = arg.slice('--deployment-id='.length);
+    else if (arg === '--implemented-type') parsed.implementedType = args[++index] ?? null;
+    else if (arg.startsWith('--implemented-type=')) parsed.implementedType = arg.slice('--implemented-type='.length);
+    else if (arg === '--file') parsed.changedFiles.push(args[++index] ?? '');
+    else if (arg.startsWith('--file=')) parsed.changedFiles.push(arg.slice('--file='.length));
+    else if (arg === '--route') parsed.changedRoutes.push(args[++index] ?? '');
+    else if (arg.startsWith('--route=')) parsed.changedRoutes.push(arg.slice('--route='.length));
+    else if (arg === '--live-url') parsed.liveUrls.push(args[++index] ?? '');
+    else if (arg.startsWith('--live-url=')) parsed.liveUrls.push(arg.slice('--live-url='.length));
+    else if (arg === '--unknown') parsed.unknowns.push(args[++index] ?? '');
+    else if (arg.startsWith('--unknown=')) parsed.unknowns.push(arg.slice('--unknown='.length));
+    else if (arg === '--risk') parsed.risks.push(args[++index] ?? '');
+    else if (arg.startsWith('--risk=')) parsed.risks.push(arg.slice('--risk='.length));
+    else if (arg === '--next-step') parsed.nextSteps.push(args[++index] ?? '');
+    else if (arg.startsWith('--next-step=')) parsed.nextSteps.push(arg.slice('--next-step='.length));
     else if (arg === '--analytics-opt-out') parsed.analyticsOptOutReason = args[++index] ?? null;
     else if (arg.startsWith('--analytics-opt-out=')) parsed.analyticsOptOutReason = arg.slice('--analytics-opt-out='.length);
     else throw new Error(`Unknown argument: ${arg}`);
@@ -426,178 +545,286 @@ export function parseArgs(rawArgs) {
   return parsed;
 }
 
-function helpText() {
-  return [
-    'DistributionOS CLI',
-    '',
-    'Usage:',
-    '  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]',
+function helpText() {
+  return [
+    'DistributionOS CLI',
+    '',
+    'Usage:',
+    '  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>]',
+    '  distributionos start-work --app <appId> [--task-type <type>] [--artifact <artifactId>] [--dedup-key <key>] [--summary <text>]',
+    '  distributionos complete-work --app <appId> --work-session <id> --status <status> --summary <text> [--url <liveUrl>] [--file <path>] [--pr-url <url>]',
     '',
-    '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.',
+    '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, uses the Codex Desktop CLI when available, and runs MCP login before repo setup.',
+    'If the repo has existing uncommitted changes, commit/stash first or use --allow-dirty when you recognize them.',
     '',
     'Authentication:',
     '  Happy path uses DistributionOS MCP OAuth and stores app-scoped credentials outside the repo.',
     '  DISTRIBUTIONOS_API_KEY, DOS_API_KEY, or DISTRIBUTIONOS_TOKEN are advanced fallbacks.',
     '  Tokens are never printed or written to committed files.',
     '',
-  ].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 };
-}
+  ].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 codexCommand = resolveCodexCommand(runtime);
+  stdout.write(`- Using ${codexCommand.label}.\n`);
+  const getResult = await runCodexCommand(runtime, codexCommand, ['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}`,
+        `Codex CLI used: ${codexCommand.command}`,
+        'Remove the old distributionos MCP server from Codex, 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, codexCommand, ['mcp', 'add', DISTRIBUTIONOS_MCP_NAME, '--url', DISTRIBUTIONOS_MCP_URL], { stream: true });
+    if (!addResult.ok) {
+      stderr.write(formatCodexCommandFailure('Codex MCP add', addResult, codexCommand));
+      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, codexCommand, ['mcp', 'login', DISTRIBUTIONOS_MCP_NAME], { stream: true });
+  if (!loginResult.ok) {
+    stderr.write(formatCodexCommandFailure('Codex MCP login', loginResult, codexCommand));
+    return { ok: false, requiresAgentRestart: true };
+  }
+  const listResult = await runCodexCommand(runtime, codexCommand, ['mcp', 'list']);
+  if (!listResult.ok) {
+    stderr.write(formatCodexCommandFailure('Codex MCP verification', listResult, codexCommand));
+    return { ok: false, requiresAgentRestart: true };
+  }
+  if (!codexMcpListShowsDistributionOs(listResult.stdout)) {
+    stderr.write([
+      'Codex MCP login finished, but this Codex runtime does not list DistributionOS yet.',
+      `Codex CLI used: ${codexCommand.command}`,
+      'Fully quit and reopen Codex Desktop, then rerun the Codex setup message from the app repo.',
+      '',
+    ].join('\n'));
+    return { ok: false, requiresAgentRestart: true };
+  }
+  if (codexMcpListShowsDistributionOsNotLoggedIn(listResult.stdout)) {
+    stderr.write([
+      'Codex MCP login finished, but this Codex runtime still reports DistributionOS as Not logged in.',
+      `Codex CLI used: ${codexCommand.command}`,
+      'Rerun the Codex setup message and approve the current browser sign-in while the command is waiting.',
+      '',
+    ].join('\n'));
+    return { ok: false, requiresAgentRestart: true };
+  }
+  stdout.write('- Codex MCP OAuth step completed and verified.\n\n');
+  return { ok: true, requiresAgentRestart: true };
+}
+
+function formatCodexCommandFailure(label, result, codexCommand) {
+  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}` : '',
+    codexCommand?.command ? `Codex CLI used: ${codexCommand.command}` : '',
+    'Rerun the Codex setup message, approve the browser sign-in, and wait for the command to say the Codex MCP OAuth step completed and verified.',
+    '',
+  ].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)
+  );
+}
+
+function resolveCodexCommand(runtime) {
+  const env = runtime?.env ?? process.env;
+  const configured = typeof env.CODEX_CLI_PATH === 'string' ? env.CODEX_CLI_PATH.trim() : '';
+  if (configured) {
+    return { command: configured, label: `Codex CLI at ${configured}` };
+  }
+
+  const desktopCommand = findCodexDesktopCommand(runtime);
+  if (desktopCommand) {
+    return { command: desktopCommand, label: `Codex Desktop CLI at ${desktopCommand}` };
+  }
+
+  return { command: 'codex', label: 'Codex CLI from PATH' };
+}
+
+function findCodexDesktopCommand(runtime) {
+  if (Array.isArray(runtime?.codexCommandCandidates)) {
+    return runtime.codexCommandCandidates.find((candidate) => typeof candidate === 'string' && candidate.trim()) ?? null;
+  }
+
+  const env = runtime?.env ?? process.env;
+  const homeDir = typeof env.USERPROFILE === 'string' && env.USERPROFILE
+    ? env.USERPROFILE
+    : os.homedir();
+  const localAppData = typeof env.LOCALAPPDATA === 'string' && env.LOCALAPPDATA
+    ? env.LOCALAPPDATA
+    : path.join(homeDir, 'AppData', 'Local');
+  const codexBinRoot = path.join(localAppData, 'OpenAI', 'Codex', 'bin');
+  const executableName = process.platform === 'win32' ? 'codex.exe' : 'codex';
+  const candidates = [];
+
+  const directCandidate = path.join(codexBinRoot, executableName);
+  if (existsSync(directCandidate)) {
+    candidates.push(directCandidate);
+  }
+
+  try {
+    for (const entry of readdirSync(codexBinRoot, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const candidate = path.join(codexBinRoot, entry.name, executableName);
+      if (existsSync(candidate)) {
+        candidates.push(candidate);
+      }
+    }
+  } catch {
+    return candidates[0] ?? null;
+  }
+
+  candidates.sort((left, right) => fileModifiedAt(right) - fileModifiedAt(left));
+  return candidates[0] ?? null;
+}
+
+function fileModifiedAt(filePath) {
+  try {
+    return statSync(filePath).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+
+function codexMcpListShowsDistributionOs(output) {
+  return Boolean(findCodexMcpListDistributionOsLine(output));
+}
+
+function codexMcpListShowsDistributionOsNotLoggedIn(output) {
+  const line = findCodexMcpListDistributionOsLine(output);
+  return Boolean(line && /not\s+logged\s+in/i.test(line));
+}
+
+function findCodexMcpListDistributionOsLine(output) {
+  return String(output)
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .find((line) => /\bdistributionos\b/i.test(line)) ?? null;
+}
+
+async function runCodexCommand(runtime, codexCommand, args, options = {}) {
+  return runExternalCommand(runtime, codexCommand.command, 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') {
+    if (path.isAbsolute(command) && /\.(exe|com)$/i.test(command)) {
+      return { command, args };
+    }
+    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({
@@ -655,6 +882,54 @@ function buildImplementationReportPayload(args) {
   };
 }
 
+function buildStartWorkPayload(args) {
+  return {
+    taskType: args.taskType ?? 'general_distribution',
+    source: 'cli',
+    sourceTool: 'distributionos-cli',
+    ...(args.summary ? { userRequest: args.summary } : {}),
+    ...(args.artifactId ? { sourceArtifactId: args.artifactId } : {}),
+    ...(args.sourceArtifactId ? { sourceArtifactId: args.sourceArtifactId } : {}),
+    ...(args.dedupKey ? { dedupKey: args.dedupKey } : {}),
+    metadata: {
+      startedBy: 'distributionos-cli',
+    },
+  };
+}
+
+function buildCompleteWorkPayload(args) {
+  const liveUrls = [...args.liveUrls];
+  if (args.url) liveUrls.unshift(args.url);
+  return {
+    workSessionId: args.workSessionId,
+    status: args.status,
+    ...(args.summary ? { summary: args.summary } : {}),
+    changedFiles: compactArray(args.changedFiles),
+    changedRoutes: compactArray(args.changedRoutes),
+    liveUrls: compactArray(liveUrls),
+    ...(args.commitSha ? { commitSha: args.commitSha } : {}),
+    ...(args.prUrl ? { prUrl: args.prUrl } : {}),
+    ...(args.deploymentUrl ? { deploymentUrl: args.deploymentUrl } : {}),
+    ...(args.deploymentId ? { deploymentId: args.deploymentId } : {}),
+    ...(args.sourceArtifactId ? { sourceArtifactId: args.sourceArtifactId } : {}),
+    ...(args.artifactId ? { artifactId: args.artifactId } : {}),
+    ...(args.implementedType ? { implementedType: args.implementedType } : {}),
+    ...(args.url ? { publishedUrl: args.url } : {}),
+    ...(args.contentId ? { analyticsIds: { dosContentId: args.contentId } } : {}),
+    ...(args.analyticsOptOutReason ? { analyticsOptOutReason: args.analyticsOptOutReason } : {}),
+    unknowns: compactArray(args.unknowns),
+    risks: compactArray(args.risks),
+    nextSteps: compactArray(args.nextSteps),
+    metadata: {
+      reportedBy: 'distributionos-cli',
+    },
+  };
+}
+
+function compactArray(values) {
+  return values.map((value) => String(value ?? '').trim()).filter(Boolean);
+}
+
 function formatVerifyResult(result) {
   const lines = [
     'DistributionOS analytics verification',
@@ -676,6 +951,39 @@ function formatVerifyResult(result) {
   return `${lines.join('\n')}\n`;
 }
 
+function formatStartWorkResult(result) {
+  const session = result.session ?? result;
+  const closeout = result.closeout ?? {};
+  const lines = [
+    'DistributionOS agent work started',
+    `- Work session: ${session.id ?? closeout.workSessionId ?? 'created'}`,
+    `- Task type: ${session.taskType ?? closeout.taskType ?? 'general_distribution'}`,
+  ];
+  if (result.reused) {
+    lines.push('- Reused existing open session for this dedup key.');
+  }
+  if (closeout.instruction) {
+    lines.push('- Closeout: call complete-work or complete_agent_work once when this meaningful task is done.');
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+function formatCompleteWorkResult(result) {
+  const session = result.session ?? result;
+  const lines = [
+    'DistributionOS agent work closeout',
+    `- Status: ${session.status ?? result.status ?? 'closed'}`,
+    `- Work session: ${session.id ?? result.workSessionId ?? 'updated'}`,
+  ];
+  if (Array.isArray(result.routed) && result.routed.length > 0) {
+    lines.push(`- Routed: ${result.routed.join(', ')}`);
+  }
+  if (result.idempotent) {
+    lines.push('- Duplicate closeout ignored; the session was already closed.');
+  }
+  return `${lines.join('\n')}\n`;
+}
+
 function formatReportResult(result) {
   const artifact = result.artifact ?? result;
   const lines = [
@@ -751,7 +1059,8 @@ function formatApplyResult(plan, changes, initialization, validation, inspection
     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.',
+      '- Codex users: if you used the Codex setup option, the CLI already ran MCP add/login against the Codex runtime and verified it did not report DistributionOS as Not logged in.',
+      '- 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.',

package/src/constants.js

@@ -6,9 +6,9 @@ export const CLI_PACKAGE_NAME = '@distributionos/cli';
 export const CLI_LOCAL_VERSION = typeof cliPackageJson.version === 'string' ? cliPackageJson.version : '0.0.0-local';
 export const DEFAULT_API_BASE = 'https://distributionos.dev';
 export const MCP_SERVER_URL = 'https://distributionos.dev/api/mcp';
-export const CURRENT_BOOTSTRAP_VERSION = '2026.06.27';
-export const CURRENT_ANALYTICS_CONTRACT_VERSION = '2026.06.20';
-export const CURRENT_SETUP_CONTRACT_VERSION = '2026.07.01';
+export const CURRENT_BOOTSTRAP_VERSION = '2026.07.04.1';
+export const CURRENT_ANALYTICS_CONTRACT_VERSION = '2026.06.20';
+export const CURRENT_SETUP_CONTRACT_VERSION = '2026.07.04.1';
 
 export const TOKEN_ENV_NAMES = [
   'DISTRIBUTIONOS_API_KEY',

package/src/setup-report.js

@@ -16,6 +16,7 @@ const ANALYTICS_BLOCK_RE =
 
 export async function buildSetupReport(plan, phase = 'plan', details = {}) {
   const detectedCapabilities = new Set([
+    'agent.workSessionCloseout',
     'analytics.verificationReady',
     'setup.reporting',
   ]);
@@ -143,10 +144,16 @@ export function formatSetupReportSummary(setupReport) {
   if (!localSetup) {
     lines.push('- Server report: pending');
     return lines;
-  }
-
-  lines.push(`- Server status: ${localSetup.status}`);
-  lines.push(`- Missing capabilities: ${formatList(localSetup.missingCapabilities)}`);
+  }
+
+  lines.push(`- Server status: ${localSetup.status}`);
+  if (localSetup.recommendedCliVersion) {
+    lines.push(`- Recommended CLI: ${localSetup.recommendedCliVersion}`);
+  }
+  if (localSetup.latestContractVersion) {
+    lines.push(`- Current setup contract: ${localSetup.latestContractVersion}`);
+  }
+  lines.push(`- Missing capabilities: ${formatList(localSetup.missingCapabilities)}`);
   if (localSetup.status !== 'current') {
     lines.push(`- Review command: ${localSetup.updateCommand}`);
     lines.push(`- Apply command: ${localSetup.applyCommand}`);