@distributionos/cli 0.1.18 → 0.1.20

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.18",
+  "version": "0.1.20",
   "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

@@ -24,6 +24,10 @@ export function buildLocalBootstrapBlock(version = CURRENT_BOOTSTRAP_VERSION, ap
     '',
     '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, then call list_agent_alerts. 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.',
+    '',
+    'Startup alerts: after get_agent_instructions, call list_agent_alerts for this app. If alerts are returned, summarize them to the user before unrelated work. For SEO incidents, call get_seo_incident for full evidence before editing code, report each fix attempt with report_seo_incident_attempt, and verify with verify_seo_incident_fix.',
+    '',
     '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,13 +1,15 @@
-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 { 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';
@@ -132,6 +134,74 @@ 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());
@@ -366,8 +436,23 @@ export function parseArgs(rawArgs) {
     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,
@@ -417,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}`);
@@ -439,9 +555,11 @@ function helpText() {
     '  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, uses the Codex Desktop CLI when available, and runs MCP login before repo setup.',
+    '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:',
@@ -463,83 +581,83 @@ function parseAgent(value) {
 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('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.',
+  } 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');
-}
+  } 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 ?? '';
@@ -553,85 +671,85 @@ function isCommandMissing(error) {
   );
 }
 
-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);
-}
+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') {
@@ -694,15 +812,15 @@ async function runExternalCommand(runtime, command, args, options = {}) {
   });
 }
 
-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],
+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 };
@@ -764,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',
@@ -785,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 = [
@@ -858,11 +1057,11 @@ function formatApplyResult(plan, changes, initialization, validation, inspection
   lines.push('', 'Next step');
   if (reviewUrl) {
     lines.push(
-      '- Open this DistributionOS review page now:',
-      `  ${reviewUrl}`,
-      '- 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.',
+      '- Open this DistributionOS review page now:',
+      `  ${reviewUrl}`,
+      '- 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.',
       '- If your agent only sees DistributionOS authentication tools, copy the auth prompt from the review page and complete OAuth before continuing.',

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.09';
+export const CURRENT_ANALYTICS_CONTRACT_VERSION = '2026.06.20';
+export const CURRENT_SETUP_CONTRACT_VERSION = '2026.07.09';
 
 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',
   ]);
@@ -23,10 +24,13 @@ export async function buildSetupReport(plan, phase = 'plan', details = {}) {
   let blockedReason = null;
 
   const bootstrapVersion = detectBootstrapVersion(plan);
-  if (bootstrapVersion && plan.bootstrap.action === 'none') {
-    detectedCapabilities.add('agent.bootstrap');
-    detectedCapabilities.add('agent.liveInstructions');
-  }
+  if (bootstrapVersion && plan.bootstrap.action === 'none') {
+    detectedCapabilities.add('agent.bootstrap');
+    detectedCapabilities.add('agent.liveInstructions');
+    if (compareVersion(bootstrapVersion, '2026.07.09') >= 0) {
+      detectedCapabilities.add('agent.startupAlerts');
+    }
+  }
   managedFiles.push({
     path: plan.bootstrap.target,
     type: 'agent.bootstrap',
@@ -146,6 +150,12 @@ export function formatSetupReportSummary(setupReport) {
   }
 
   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}`);
@@ -157,13 +167,29 @@ export function formatSetupReportSummary(setupReport) {
   return lines;
 }
 
-function detectBootstrapVersion(plan) {
-  const current = (plan.repo.instructionFiles ?? []).find((file) => file.hasManagedDistributionOsBlock);
-  return current?.managedDistributionOsVersion ??
-    (plan.bootstrap.action === 'none' ? CURRENT_BOOTSTRAP_VERSION : null);
-}
-
-async function inspectAnalyticsInstall(plan) {
+function detectBootstrapVersion(plan) {
+  const current = (plan.repo.instructionFiles ?? []).find((file) => file.hasManagedDistributionOsBlock);
+  return current?.managedDistributionOsVersion ??
+    (plan.bootstrap.action === 'none' ? CURRENT_BOOTSTRAP_VERSION : null);
+}
+
+function compareVersion(left, right) {
+  const a = String(left ?? '').split(/[.-]/).map(toComparableNumber);
+  const b = String(right ?? '').split(/[.-]/).map(toComparableNumber);
+  const length = Math.max(a.length, b.length);
+  for (let index = 0; index < length; index += 1) {
+    const diff = (a[index] ?? 0) - (b[index] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+function toComparableNumber(value) {
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
+async function inspectAnalyticsInstall(plan) {
   const target = plan.analytics.layoutTarget;
   if (!target) {
     return {