@kbediako/codex-orchestrator 0.1.22 → 0.1.24

package/README.md

@@ -130,6 +130,11 @@ flowchart TB
 
 ## Skills (bundled)
 
+Recommended one-shot bootstrap (skills + delegation + DevTools wiring):
+```bash
+codex-orchestrator setup --yes
+```
+
 The release ships skills under `skills/` for downstream packaging. If you already have global skills installed, treat those as the primary reference and use bundled skills as the shipped fallback. Install bundled skills into `$CODEX_HOME/skills`:
 ```bash
 codex-orchestrator skills install
@@ -142,6 +147,7 @@ Options:
 
 Bundled skills (may vary by release):
 - `collab-subagents-first`
+- `chrome-devtools`
 - `delegation-usage`
 - `standalone-review`
 - `docs-first`
@@ -152,11 +158,21 @@ Bundled skills (may vary by release):
 
 ## DevTools readiness
 
-Check DevTools readiness (skill + MCP config):
+Check readiness (deps + capability wiring):
 ```bash
 codex-orchestrator doctor --format json
 ```
 
+Auto-fix wiring (delegation + DevTools):
+```bash
+codex-orchestrator doctor --apply --yes
+```
+
+Usage snapshot (scans local `.runs/`):
+```bash
+codex-orchestrator doctor --usage
+```
+
 Print DevTools MCP setup guidance:
 ```bash
 codex-orchestrator devtools setup
@@ -168,9 +184,11 @@ codex-orchestrator devtools setup
 - `codex-orchestrator plan <pipeline>` — preview pipeline stages.
 - `codex-orchestrator exec <cmd>` — run a one-off command with the exec runtime.
 - `codex-orchestrator init codex` — install starter templates (`mcp-client.json`, `AGENTS.md`) into a repo.
+- `codex-orchestrator setup --yes` — install bundled skills and configure delegation + DevTools wiring.
 - `codex-orchestrator init codex --codex-cli --yes --codex-source <path>` — optionally provision a CO-managed Codex CLI binary (build-from-source default; set `CODEX_CLI_SOURCE` to avoid passing `--codex-source` every time).
 - `codex-orchestrator init codex --codex-cli --yes --codex-download-url <url> --codex-download-sha256 <sha>` — opt-in to a prebuilt Codex CLI download.
 - `codex-orchestrator codex setup` — plan/apply a CO-managed Codex CLI install (optional managed/pinned path; use `--download-url` + `--download-sha256` for prebuilts).
+- `codex-orchestrator delegation setup --yes` — configure delegation MCP server wiring.
 - `codex-orchestrator self-check --format json` — JSON health payload.
 - `codex-orchestrator mcp serve` — Codex MCP stdio server.
 

package/dist/bin/codex-orchestrator.js

@@ -14,9 +14,11 @@ import { evaluateInteractiveGate } from '../orchestrator/src/cli/utils/interacti
 import { buildSelfCheckResult } from '../orchestrator/src/cli/selfCheck.js';
 import { initCodexTemplates, formatInitSummary } from '../orchestrator/src/cli/init.js';
 import { runDoctor, formatDoctorSummary } from '../orchestrator/src/cli/doctor.js';
+import { formatDoctorUsageSummary, runDoctorUsage } from '../orchestrator/src/cli/doctorUsage.js';
 import { formatDevtoolsSetupSummary, runDevtoolsSetup } from '../orchestrator/src/cli/devtoolsSetup.js';
 import { formatCodexCliSetupSummary, runCodexCliSetup } from '../orchestrator/src/cli/codexCliSetup.js';
-import { formatSkillsInstallSummary, installSkills } from '../orchestrator/src/cli/skills.js';
+import { formatDelegationSetupSummary, runDelegationSetup } from '../orchestrator/src/cli/delegationSetup.js';
+import { formatSkillsInstallSummary, installSkills, listBundledSkills } from '../orchestrator/src/cli/skills.js';
 import { loadPackageInfo } from '../orchestrator/src/cli/utils/packageInfo.js';
 import { slugify } from '../orchestrator/src/cli/utils/strings.js';
 import { serveMcp } from '../orchestrator/src/cli/mcp.js';
@@ -63,6 +65,9 @@ async function main() {
             case 'init':
                 await handleInit(args);
                 break;
+            case 'setup':
+                await handleSetup(args);
+                break;
             case 'doctor':
                 await handleDoctor(args);
                 break;
@@ -85,6 +90,9 @@ async function main() {
             case 'delegation-server':
                 await handleDelegationServer(args);
                 break;
+            case 'delegation':
+                await handleDelegation(args);
+                break;
             case 'version':
                 printVersion();
                 break;
@@ -332,6 +340,16 @@ async function handleRlm(orchestrator, rawArgs) {
     process.env.MCP_RUNNER_TASK_ID = taskId;
     applyRlmEnvOverrides(flags, goal);
     console.log(`Task: ${taskId}`);
+    const collabUserChoice = flags['collab'] !== undefined || process.env.RLM_SYMBOLIC_COLLAB !== undefined;
+    if (!collabUserChoice) {
+        const doctor = runDoctor();
+        if (doctor.collab.status === 'ok') {
+            console.log('Tip: collab is enabled. Try: codex-orchestrator rlm --collab auto \"<goal>\"');
+        }
+        else if (doctor.collab.status === 'disabled') {
+            console.log('Tip: collab is available but disabled. Enable with: codex features enable collab');
+        }
+    }
     let startResult = null;
     await withRunUi(flags, 'text', async (runEvents) => {
         startResult = await orchestrator.start({
@@ -541,16 +559,192 @@ async function handleInit(rawArgs) {
         }
     }
 }
+async function handleSetup(rawArgs) {
+    const { positionals, flags } = parseArgs(rawArgs);
+    if (isHelpRequest(positionals, flags)) {
+        console.log(`Usage: codex-orchestrator setup [--yes] [--format json]
+
+One-shot bootstrap for downstream users. Installs bundled skills and configures
+delegation + DevTools MCP wiring.
+
+Options:
+  --yes                 Apply setup (otherwise plan only).
+  --repo <path>         Repo root for delegation wiring (default cwd).
+  --format json         Emit machine-readable output (dry-run only).
+`);
+        return;
+    }
+    const format = flags['format'] === 'json' ? 'json' : 'text';
+    const apply = Boolean(flags['yes']);
+    if (format === 'json' && apply) {
+        throw new Error('setup does not support --format json with --yes.');
+    }
+    const repoFlag = readStringFlag(flags, 'repo');
+    const repoRoot = repoFlag ?? process.cwd();
+    const repoFlagValue = repoFlag ? (/\s/u.test(repoFlag) ? JSON.stringify(repoFlag) : repoFlag) : null;
+    const delegationRepoArg = repoFlagValue ? ` --repo ${repoFlagValue}` : '';
+    const bundledSkills = await listBundledSkills();
+    if (bundledSkills.length === 0) {
+        throw new Error('No bundled skills detected; cannot run setup.');
+    }
+    const forceSkills = bundledSkills.filter((skill) => skill !== 'chrome-devtools');
+    if (!apply) {
+        const forceOnly = forceSkills.join(',');
+        const forceCommand = forceOnly ? `codex-orchestrator skills install --force --only ${forceOnly}` : null;
+        const devtoolsCommand = bundledSkills.includes('chrome-devtools')
+            ? 'codex-orchestrator skills install --only chrome-devtools'
+            : null;
+        const delegation = await runDelegationSetup({ repoRoot });
+        const devtools = await runDevtoolsSetup();
+        const payload = {
+            status: 'planned',
+            steps: {
+                skills: {
+                    commandLines: [forceCommand, devtoolsCommand].filter((entry) => Boolean(entry)),
+                    note: 'Installs bundled skills into $CODEX_HOME/skills (setup avoids overwriting chrome-devtools when already present).'
+                },
+                delegation,
+                devtools
+            }
+        };
+        if (format === 'json') {
+            console.log(JSON.stringify(payload, null, 2));
+            return;
+        }
+        console.log('Setup plan:');
+        console.log('- Skills:');
+        for (const commandLine of payload.steps.skills.commandLines) {
+            console.log(`  - ${commandLine}`);
+        }
+        console.log(`- Delegation: codex-orchestrator delegation setup --yes${delegationRepoArg}`);
+        console.log('- DevTools: codex-orchestrator devtools setup --yes');
+        console.log('Run with --yes to apply this setup.');
+        return;
+    }
+    const primarySkills = forceSkills.length > 0 ? await installSkills({ force: true, only: forceSkills }) : null;
+    const devtoolsSkill = bundledSkills.includes('chrome-devtools')
+        ? await installSkills({ force: false, only: ['chrome-devtools'] })
+        : null;
+    const skills = primarySkills && devtoolsSkill
+        ? {
+            sourceRoot: primarySkills.sourceRoot,
+            targetRoot: primarySkills.targetRoot,
+            skills: [...new Set([...primarySkills.skills, ...devtoolsSkill.skills])],
+            written: [...primarySkills.written, ...devtoolsSkill.written],
+            skipped: [...primarySkills.skipped, ...devtoolsSkill.skipped]
+        }
+        : devtoolsSkill ?? primarySkills;
+    if (!skills) {
+        throw new Error('No bundled skills detected; cannot run setup.');
+    }
+    const delegation = await runDelegationSetup({ apply: true, repoRoot });
+    const devtools = await runDevtoolsSetup({ apply: true });
+    for (const line of formatSkillsInstallSummary(skills)) {
+        console.log(line);
+    }
+    for (const line of formatDelegationSetupSummary(delegation)) {
+        console.log(line);
+    }
+    for (const line of formatDevtoolsSetupSummary(devtools)) {
+        console.log(line);
+    }
+    console.log('Next: codex-orchestrator doctor --usage');
+}
 async function handleDoctor(rawArgs) {
     const { flags } = parseArgs(rawArgs);
     const format = flags['format'] === 'json' ? 'json' : 'text';
-    const result = runDoctor();
+    const includeUsage = Boolean(flags['usage']);
+    const wantsApply = Boolean(flags['apply']);
+    const apply = Boolean(flags['yes']);
+    if (wantsApply && format === 'json') {
+        throw new Error('doctor --apply does not support --format json.');
+    }
+    const windowDaysRaw = readStringFlag(flags, 'window-days');
+    let windowDays = undefined;
+    if (windowDaysRaw) {
+        if (!/^\d+$/u.test(windowDaysRaw)) {
+            throw new Error(`Invalid --window-days value '${windowDaysRaw}'. Expected a positive integer.`);
+        }
+        const parsed = Number(windowDaysRaw);
+        if (!Number.isInteger(parsed) || parsed <= 0) {
+            throw new Error(`Invalid --window-days value '${windowDaysRaw}'. Expected a positive integer.`);
+        }
+        windowDays = parsed;
+    }
+    const taskFilter = readStringFlag(flags, 'task') ?? null;
+    const doctorResult = runDoctor();
+    const usageResult = includeUsage ? await runDoctorUsage({ windowDays, taskFilter }) : null;
     if (format === 'json') {
-        console.log(JSON.stringify(result, null, 2));
+        if (usageResult) {
+            console.log(JSON.stringify({ ...doctorResult, usage: usageResult }, null, 2));
+            return;
+        }
+        console.log(JSON.stringify(doctorResult, null, 2));
         return;
     }
-    const summary = formatDoctorSummary(result);
-    for (const line of summary) {
+    for (const line of formatDoctorSummary(doctorResult)) {
+        console.log(line);
+    }
+    if (usageResult) {
+        for (const line of formatDoctorUsageSummary(usageResult)) {
+            console.log(line);
+        }
+    }
+    if (!wantsApply) {
+        return;
+    }
+    const repoRoot = process.cwd();
+    const delegationPlan = await runDelegationSetup({ repoRoot });
+    const devtoolsPlan = await runDevtoolsSetup();
+    const needsDelegation = !delegationPlan.readiness.configured;
+    const needsDevtoolsSkill = devtoolsPlan.readiness.skill.status !== 'ok';
+    const devtoolsConfigStatus = devtoolsPlan.readiness.config.status;
+    const needsDevtoolsConfig = devtoolsConfigStatus === 'missing';
+    const hasInvalidDevtoolsConfig = devtoolsConfigStatus === 'invalid';
+    if (!needsDelegation && !needsDevtoolsSkill && !needsDevtoolsConfig && !hasInvalidDevtoolsConfig) {
+        console.log('Doctor apply: nothing to do.');
+        return;
+    }
+    console.log('Doctor apply plan:');
+    if (needsDevtoolsSkill) {
+        console.log('- Install skill: chrome-devtools (codex-orchestrator skills install --only chrome-devtools)');
+    }
+    if (hasInvalidDevtoolsConfig) {
+        console.log(`- DevTools MCP config is invalid: ${devtoolsPlan.readiness.config.path} (fix config.toml then rerun doctor --apply)`);
+    }
+    if (needsDevtoolsConfig) {
+        console.log('- Configure DevTools MCP: codex-orchestrator devtools setup --yes');
+    }
+    if (needsDelegation) {
+        console.log('- Configure delegation MCP: codex-orchestrator delegation setup --yes');
+    }
+    if (!apply) {
+        console.log('Run with --apply --yes to apply these fixes.');
+        return;
+    }
+    if (needsDevtoolsSkill) {
+        const skills = await installSkills({ only: ['chrome-devtools'] });
+        for (const line of formatSkillsInstallSummary(skills)) {
+            console.log(line);
+        }
+    }
+    if (needsDelegation) {
+        const delegation = await runDelegationSetup({ apply: true, repoRoot });
+        for (const line of formatDelegationSetupSummary(delegation)) {
+            console.log(line);
+        }
+    }
+    if (hasInvalidDevtoolsConfig) {
+        console.log(`DevTools setup: skipped (config.toml is invalid: ${devtoolsPlan.readiness.config.path}). Fix it and rerun doctor --apply --yes.`);
+    }
+    else if (needsDevtoolsConfig) {
+        const devtools = await runDevtoolsSetup({ apply: true });
+        for (const line of formatDevtoolsSetupSummary(devtools)) {
+            console.log(line);
+        }
+    }
+    const doctorAfter = runDoctor();
+    for (const line of formatDoctorSummary(doctorAfter)) {
         console.log(line);
     }
 }
@@ -578,6 +772,30 @@ async function handleDevtools(rawArgs) {
         console.log(line);
     }
 }
+async function handleDelegation(rawArgs) {
+    const { positionals, flags } = parseArgs(rawArgs);
+    const subcommand = positionals.shift();
+    if (!subcommand) {
+        throw new Error('delegation requires a subcommand (setup).');
+    }
+    if (subcommand !== 'setup') {
+        throw new Error(`Unknown delegation subcommand: ${subcommand}`);
+    }
+    const format = flags['format'] === 'json' ? 'json' : 'text';
+    const apply = Boolean(flags['yes']);
+    if (format === 'json' && apply) {
+        throw new Error('delegation setup does not support --format json with --yes.');
+    }
+    const repoRoot = readStringFlag(flags, 'repo') ?? process.cwd();
+    const result = await runDelegationSetup({ apply, repoRoot });
+    if (format === 'json') {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    for (const line of formatDelegationSetupSummary(result)) {
+        console.log(line);
+    }
+}
 async function handleCodex(rawArgs) {
     const { positionals, flags } = parseArgs(rawArgs);
     const subcommand = positionals.shift();
@@ -961,7 +1179,17 @@ Commands:
     --codex-download-sha256 <sha>  Expected SHA256 for the prebuilt download.
     --codex-force          Overwrite existing CO-managed codex binary.
     --yes                  Apply codex CLI setup (otherwise plan only).
-  doctor [--format json]
+  setup [--yes] [--format json]
+    --yes                 Apply setup (otherwise plan only).
+    --repo <path>         Repo root for delegation wiring (default cwd).
+    --format json         Emit machine-readable output (dry-run only).
+  doctor [--format json] [--usage] [--window-days <n>] [--task <id>] [--apply]
+    --usage               Include a local usage snapshot (scans .runs/).
+    --window-days <n>     Window for --usage (default 30).
+    --task <id>           Limit --usage scan to a specific task directory.
+    --apply               Plan/apply quick fixes for DevTools + delegation wiring (use with --yes).
+    --yes                 Apply fixes when --apply is set.
+    --format json         Emit machine-readable output (not supported with --apply).
   codex setup
     --source <path>        Build from local Codex repo (or git URL).
     --ref <ref>            Git ref (branch/tag/sha) when building from repo.
@@ -973,6 +1201,10 @@ Commands:
   devtools setup          Print DevTools MCP setup instructions.
     --yes                 Apply setup by running "codex mcp add ...".
     --format json         Emit machine-readable output (dry-run only).
+  delegation setup        Configure delegation MCP server wiring.
+    --repo <path>         Repo root for delegation server (default cwd).
+    --yes                 Apply setup by running "codex mcp add ...".
+    --format json         Emit machine-readable output (dry-run only).
   skills install          Install bundled skills into $CODEX_HOME/skills.
     --force               Overwrite existing skill files.
     --only <skills>       Install only selected skills (comma-separated).

package/dist/orchestrator/src/cli/delegationSetup.js

@@ -0,0 +1,239 @@
+import { spawn, spawnSync } from 'node:child_process';
+import process from 'node:process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { resolveCodexCliBin } from './utils/codexCli.js';
+import { resolveCodexHome } from './utils/codexPaths.js';
+export async function runDelegationSetup(options = {}) {
+    const env = options.env ?? process.env;
+    const repoRoot = options.repoRoot ?? process.cwd();
+    const codexBin = resolveCodexCliBin(env);
+    const codexHome = resolveCodexHome(env);
+    const configPath = join(codexHome, 'config.toml');
+    const plan = {
+        codexBin,
+        codexHome,
+        repoRoot,
+        commandLine: `"${codexBin}" mcp add delegation -- codex-orchestrator delegate-server`
+    };
+    const probe = inspectDelegationReadiness({ codexBin, configPath, repoRoot, env });
+    const readiness = { configured: probe.configured, configPath };
+    if (!options.apply) {
+        return { status: 'planned', plan, readiness };
+    }
+    if (probe.configured) {
+        return { status: 'skipped', reason: probe.reason ?? 'Delegation MCP is already configured.', plan, readiness };
+    }
+    await applyDelegationSetup({ codexBin, removeExisting: probe.removeExisting, envVars: probe.envVars }, env);
+    const configuredAfter = inspectDelegationReadiness({ codexBin, configPath, repoRoot, env }).configured;
+    return {
+        status: 'applied',
+        reason: probe.reason,
+        plan,
+        readiness: { ...readiness, configured: configuredAfter }
+    };
+}
+export function formatDelegationSetupSummary(result) {
+    const lines = [];
+    lines.push(`Delegation setup: ${result.status}`);
+    if (result.reason) {
+        lines.push(`Note: ${result.reason}`);
+    }
+    lines.push(`- Codex home: ${result.plan.codexHome}`);
+    lines.push(`- Config: ${result.readiness.configured ? 'ok' : 'missing'} (${result.readiness.configPath})`);
+    lines.push(`- Command: ${result.plan.commandLine}`);
+    if (result.status === 'planned') {
+        lines.push('Run with --yes to apply this setup.');
+    }
+    return lines;
+}
+function inspectDelegationReadiness(options) {
+    const requestedRepo = resolve(options.repoRoot);
+    const existing = readDelegationMcpServer(options.codexBin, options.env);
+    if (existing) {
+        const envVars = existing.envVars;
+        const isDelegationServer = existing.args.includes('delegate-server') || existing.args.includes('delegation-server');
+        if (!isDelegationServer) {
+            return {
+                configured: false,
+                removeExisting: true,
+                envVars,
+                reason: 'Existing delegation MCP entry does not point to codex-orchestrator delegate-server; reconfiguring.'
+            };
+        }
+        if (existing.pinnedRepo) {
+            const pinnedRepo = resolve(existing.pinnedRepo);
+            if (pinnedRepo !== requestedRepo) {
+                return {
+                    configured: false,
+                    removeExisting: true,
+                    envVars,
+                    reason: `Existing delegation MCP entry is pinned to ${existing.pinnedRepo}; reconfiguring.`
+                };
+            }
+            return {
+                configured: true,
+                removeExisting: false,
+                envVars,
+                reason: `Delegation MCP is already configured (pinned to ${existing.pinnedRepo}).`
+            };
+        }
+        return {
+            configured: true,
+            removeExisting: false,
+            envVars,
+            reason: 'Delegation MCP is already configured.'
+        };
+    }
+    // Fall back to directly scanning config.toml when the Codex CLI probe is unavailable.
+    const configured = isDelegationConfiguredFallback(options.configPath);
+    return { configured, removeExisting: false, envVars: {} };
+}
+function applyDelegationSetup(plan, env) {
+    const envFlags = [];
+    for (const [key, value] of Object.entries(plan.envVars ?? {})) {
+        envFlags.push('--env', `${key}=${value}`);
+    }
+    return new Promise((resolve, reject) => {
+        const runAdd = () => {
+            const child = spawn(plan.codexBin, ['mcp', 'add', 'delegation', ...envFlags, '--', 'codex-orchestrator', 'delegate-server'], { stdio: 'inherit', env });
+            child.once('error', (error) => reject(error instanceof Error ? error : new Error(String(error))));
+            child.once('exit', (code) => {
+                if (code === 0) {
+                    resolve();
+                }
+                else {
+                    reject(new Error(`codex mcp add exited with code ${code ?? 'unknown'}`));
+                }
+            });
+        };
+        if (!plan.removeExisting) {
+            runAdd();
+            return;
+        }
+        const child = spawn(plan.codexBin, ['mcp', 'remove', 'delegation'], { stdio: 'inherit', env });
+        child.once('error', (error) => reject(error instanceof Error ? error : new Error(String(error))));
+        child.once('exit', (code) => {
+            if (code === 0) {
+                runAdd();
+            }
+            else {
+                reject(new Error(`codex mcp remove exited with code ${code ?? 'unknown'}`));
+            }
+        });
+    });
+}
+function readDelegationMcpServer(codexBin, env) {
+    const result = spawnSync(codexBin, ['mcp', 'get', 'delegation', '--json'], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: 5000,
+        env
+    });
+    if (result.error || result.status !== 0) {
+        return null;
+    }
+    const stdout = String(result.stdout ?? '').trim();
+    if (!stdout) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(stdout);
+        const transport = parsed.transport;
+        const args = Array.isArray(transport?.args)
+            ? transport.args.filter((value) => typeof value === 'string')
+            : [];
+        const envVars = {};
+        const envRecord = transport?.env;
+        if (envRecord && typeof envRecord === 'object' && !Array.isArray(envRecord)) {
+            for (const [key, value] of Object.entries(envRecord)) {
+                if (typeof value === 'string') {
+                    envVars[key] = value;
+                }
+            }
+        }
+        const pinnedRepo = readPinnedRepo(args);
+        return { args, pinnedRepo, envVars };
+    }
+    catch {
+        return null;
+    }
+}
+function readPinnedRepo(args) {
+    const index = args.indexOf('--repo');
+    if (index === -1) {
+        return null;
+    }
+    const candidate = args[index + 1];
+    return typeof candidate === 'string' && candidate.trim().length > 0 ? candidate.trim() : null;
+}
+function isDelegationConfiguredFallback(configPath) {
+    if (!existsSync(configPath)) {
+        return false;
+    }
+    try {
+        // Keep parsing loose; we only need to know whether a delegation entry exists.
+        const raw = readFileSync(configPath, 'utf8');
+        return hasMcpServerEntry(raw, 'delegation');
+    }
+    catch {
+        return false;
+    }
+}
+function hasMcpServerEntry(raw, serverName) {
+    const lines = raw.split('\n');
+    let currentTable = null;
+    for (const line of lines) {
+        const trimmed = stripTomlComment(line).trim();
+        if (!trimmed) {
+            continue;
+        }
+        const tableMatch = trimmed.match(/^\[(.+)\]$/u);
+        if (tableMatch) {
+            currentTable = tableMatch[1]?.trim() ?? null;
+            if (currentTable === `mcp_servers.${serverName}` ||
+                currentTable === `mcp_servers."${serverName}"` ||
+                currentTable === `mcp_servers.'${serverName}'`) {
+                return true;
+            }
+            continue;
+        }
+        if (trimmed.startsWith('mcp_servers.')) {
+            if (trimmed.startsWith(`mcp_servers."${serverName}".`)) {
+                return true;
+            }
+            if (trimmed.startsWith(`mcp_servers.'${serverName}'.`)) {
+                return true;
+            }
+            if (trimmed.startsWith(`mcp_servers.${serverName}.`)) {
+                return true;
+            }
+            if (trimmed.startsWith(`mcp_servers."${serverName}"=`)) {
+                return true;
+            }
+            if (trimmed.startsWith(`mcp_servers.'${serverName}'=`)) {
+                return true;
+            }
+            if (trimmed.startsWith(`mcp_servers.${serverName}=`)) {
+                return true;
+            }
+        }
+        if (currentTable === 'mcp_servers') {
+            const entryPattern = new RegExp(`^"?${escapeRegExp(serverName)}"?\\s*=`, 'u');
+            if (entryPattern.test(trimmed)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+function stripTomlComment(line) {
+    const index = line.indexOf('#');
+    if (index === -1) {
+        return line;
+    }
+    return line.slice(0, index);
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/orchestrator/src/cli/devtoolsSetup.js

@@ -20,7 +20,8 @@ export async function runDevtoolsSetup(options = {}) {
         throw new Error(`Cannot apply DevTools setup because config.toml is invalid: ${readiness.config.path}`);
     }
     await applyDevtoolsSetup(plan, env);
-    return { status: 'applied', plan, readiness };
+    const readinessAfter = resolveDevtoolsReadiness(env);
+    return { status: 'applied', plan, readiness: readinessAfter };
 }
 export function formatDevtoolsSetupSummary(result) {
     const lines = [];

package/dist/orchestrator/src/cli/doctor.js

@@ -51,6 +51,7 @@ export function runDoctor(cwd = process.cwd()) {
             install: readiness.config.status === 'ok'
                 ? undefined
                 : [
+                    'Quick fix: codex-orchestrator doctor --apply --yes',
                     'Run: codex-orchestrator devtools setup',
                     `Run: ${setupPlan.commandLine}`,
                     `Config path: ${setupPlan.configPath}`,
@@ -115,7 +116,9 @@ export function runDoctor(cwd = process.cwd()) {
             status: delegationStatus,
             config: delegationConfig,
             enablement: [
-                `Run: codex mcp add delegation -- codex-orchestrator delegate-server --repo ${cwd}`,
+                'Quick fix: codex-orchestrator doctor --apply --yes',
+                'Run: codex-orchestrator delegation setup --yes',
+                'Or manually: codex mcp add delegation -- codex-orchestrator delegate-server',
                 "Enable for a run with: codex -c 'mcp_servers.delegation.enabled=true' ...",
                 'See: codex-orchestrator init codex'
             ]

package/dist/orchestrator/src/cli/doctorUsage.js

@@ -0,0 +1,210 @@
+import { readFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import process from 'node:process';
+import { collectManifests, findSubagentManifests, parseRunIdTimestamp, resolveEnvironmentPaths } from '../../../scripts/lib/run-manifests.js';
+import { normalizeTaskKey as normalizeTaskKeyAny } from '../../../scripts/lib/docs-helpers.js';
+const normalizeTaskKey = normalizeTaskKeyAny;
+export async function runDoctorUsage(options = {}) {
+    const windowDays = clampInt(options.windowDays ?? 30, 1, 3650);
+    const cutoffMs = Date.now() - windowDays * 24 * 60 * 60 * 1000;
+    const cutoffIso = new Date(cutoffMs).toISOString();
+    const env = resolveEnvironmentPaths();
+    const manifestPaths = await collectManifests(env.runsRoot, options.taskFilter ?? undefined);
+    const seenRunIds = new Set();
+    const pipelines = new Map();
+    const cloudByStatus = {};
+    const statusCounts = { total: 0, succeeded: 0, failed: 0, cancelled: 0, other: 0 };
+    let cloudRuns = 0;
+    let rlmRuns = 0;
+    let collabRunsWithToolCalls = 0;
+    let collabTotalToolCalls = 0;
+    const collabCaptureDisabled = String(process.env.CODEX_ORCHESTRATOR_COLLAB_MAX_EVENTS ?? '').trim() === '0';
+    const activeIndexTasks = new Set();
+    const taskKeys = readTaskIndexKeys(env.repoRoot);
+    for (const manifestPath of manifestPaths) {
+        const runIdFromPath = extractRunIdFromManifestPath(manifestPath);
+        if (!runIdFromPath) {
+            continue;
+        }
+        if (seenRunIds.has(runIdFromPath)) {
+            continue;
+        }
+        const timestamp = parseRunIdTimestamp(runIdFromPath);
+        if (timestamp && timestamp.getTime() < cutoffMs) {
+            continue;
+        }
+        let manifest;
+        try {
+            const raw = await readFile(manifestPath, 'utf8');
+            manifest = JSON.parse(raw);
+        }
+        catch {
+            continue;
+        }
+        const runId = typeof manifest.run_id === 'string' && manifest.run_id ? manifest.run_id : runIdFromPath;
+        if (seenRunIds.has(runId)) {
+            continue;
+        }
+        seenRunIds.add(runId);
+        const startedAtMs = Date.parse(manifest.started_at ?? '') || timestamp?.getTime() || 0;
+        if (!startedAtMs || startedAtMs < cutoffMs) {
+            continue;
+        }
+        statusCounts.total += 1;
+        if (manifest.status === 'succeeded') {
+            statusCounts.succeeded += 1;
+        }
+        else if (manifest.status === 'failed') {
+            statusCounts.failed += 1;
+        }
+        else if (manifest.status === 'cancelled') {
+            statusCounts.cancelled += 1;
+        }
+        else {
+            statusCounts.other += 1;
+        }
+        const pipelineId = typeof manifest.pipeline_id === 'string' && manifest.pipeline_id ? manifest.pipeline_id : 'unknown';
+        pipelines.set(pipelineId, (pipelines.get(pipelineId) ?? 0) + 1);
+        if (pipelineId === 'rlm') {
+            rlmRuns += 1;
+        }
+        if (manifest.cloud_execution) {
+            cloudRuns += 1;
+            const status = (manifest.cloud_execution.status ?? 'unknown').trim() || 'unknown';
+            cloudByStatus[status] = (cloudByStatus[status] ?? 0) + 1;
+        }
+        if (Array.isArray(manifest.collab_tool_calls) && manifest.collab_tool_calls.length > 0) {
+            collabRunsWithToolCalls += 1;
+            collabTotalToolCalls += manifest.collab_tool_calls.length;
+        }
+        if (taskKeys.has(manifest.task_id)) {
+            activeIndexTasks.add(manifest.task_id);
+        }
+    }
+    const pipelineTop = [...pipelines.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 10)
+        .map(([id, runs]) => ({ id, runs }));
+    const delegationErrors = [];
+    let activeWithSubagents = 0;
+    let totalSubagentManifests = 0;
+    const activeTasks = [...activeIndexTasks];
+    const subagentResults = await Promise.all(activeTasks.map(async (taskId) => {
+        const result = await findSubagentManifests(env.runsRoot, taskId);
+        if (result.error) {
+            delegationErrors.push(result.error);
+        }
+        return { taskId, found: result.found };
+    }));
+    for (const item of subagentResults) {
+        totalSubagentManifests += item.found.length;
+        if (item.found.length > 0) {
+            activeWithSubagents += 1;
+        }
+    }
+    return {
+        window_days: windowDays,
+        cutoff_iso: cutoffIso,
+        runs: statusCounts,
+        cloud: {
+            runs: cloudRuns,
+            by_status: cloudByStatus
+        },
+        rlm: {
+            runs: rlmRuns
+        },
+        collab: {
+            runs_with_tool_calls: collabRunsWithToolCalls,
+            total_tool_calls: collabTotalToolCalls,
+            capture_disabled: collabCaptureDisabled
+        },
+        delegation: {
+            active_top_level_tasks: activeTasks.length,
+            active_with_subagents: activeWithSubagents,
+            total_subagent_manifests: totalSubagentManifests,
+            errors: delegationErrors
+        },
+        pipelines: {
+            total: pipelines.size,
+            top: pipelineTop
+        }
+    };
+}
+export function formatDoctorUsageSummary(result) {
+    const lines = [];
+    lines.push(`Usage (last ${result.window_days}d, cutoff ${result.cutoff_iso})`);
+    lines.push(`  - runs: ${result.runs.total} (ok=${result.runs.succeeded}, failed=${result.runs.failed}, cancelled=${result.runs.cancelled}, other=${result.runs.other})`);
+    lines.push(`  - cloud: ${result.cloud.runs} (${formatPercent(result.cloud.runs, result.runs.total)})${formatCloudStatuses(result.cloud.by_status)}`);
+    lines.push(`  - rlm: ${result.rlm.runs} (${formatPercent(result.rlm.runs, result.runs.total)})`);
+    const collabSuffix = result.collab.capture_disabled ? ' (capture disabled)' : '';
+    lines.push(`  - collab: ${result.collab.runs_with_tool_calls} (${formatPercent(result.collab.runs_with_tool_calls, result.runs.total)})${collabSuffix}`);
+    if (result.delegation.active_top_level_tasks > 0) {
+        lines.push(`  - delegation: ${result.delegation.active_with_subagents}/${result.delegation.active_top_level_tasks} top-level tasks have subagent manifests`);
+    }
+    else {
+        lines.push('  - delegation: no top-level tasks detected in tasks/index.json for this window');
+    }
+    if (result.pipelines.top.length > 0) {
+        lines.push('Top pipelines:');
+        for (const entry of result.pipelines.top) {
+            lines.push(`  - ${entry.id}: ${entry.runs}`);
+        }
+    }
+    if (result.delegation.errors.length > 0) {
+        lines.push('Delegation scan warnings:');
+        for (const warning of result.delegation.errors.slice(0, 3)) {
+            lines.push(`  - ${warning}`);
+        }
+    }
+    return lines;
+}
+function extractRunIdFromManifestPath(manifestPath) {
+    if (!manifestPath) {
+        return null;
+    }
+    // .../<run-id>/manifest.json
+    const dir = manifestPath.endsWith('manifest.json') ? basename(dirname(manifestPath)) : null;
+    return dir && dir !== '..' ? dir : null;
+}
+function clampInt(value, min, max) {
+    const rounded = Math.floor(value);
+    if (!Number.isFinite(rounded)) {
+        return min;
+    }
+    return Math.max(min, Math.min(max, rounded));
+}
+function formatPercent(numerator, denominator) {
+    if (!denominator) {
+        return '0%';
+    }
+    const pct = (numerator / denominator) * 100;
+    return `${Math.round(pct * 10) / 10}%`;
+}
+function formatCloudStatuses(byStatus) {
+    const entries = Object.entries(byStatus);
+    if (entries.length === 0) {
+        return '';
+    }
+    entries.sort((a, b) => b[1] - a[1]);
+    const top = entries
+        .slice(0, 3)
+        .map(([status, count]) => `${status}=${count}`)
+        .join(', ');
+    return ` [${top}]`;
+}
+function readTaskIndexKeys(repoRoot) {
+    const indexPath = join(repoRoot, 'tasks', 'index.json');
+    try {
+        const raw = readFileSync(indexPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        const items = Array.isArray(parsed?.items) ? parsed.items : [];
+        const keys = items
+            .map((item) => normalizeTaskKey(item))
+            .filter((key) => typeof key === 'string' && key.length > 0);
+        return new Set(keys);
+    }
+    catch {
+        return new Set();
+    }
+}

package/dist/orchestrator/src/cli/init.js

@@ -61,7 +61,7 @@ export function formatInitSummary(result, cwd) {
         lines.push('No files written.');
     }
     lines.push('Next steps (recommended):');
-    lines.push(`  - codex mcp add delegation -- codex-orchestrator delegate-server --repo ${cwd}`);
+    lines.push('  - codex-orchestrator setup --yes  # installs bundled skills + configures delegation/devtools wiring');
     lines.push('  - codex-orchestrator codex setup  # optional: managed/pinned Codex CLI (stock CLI works by default)');
     return lines;
 }

package/dist/orchestrator/src/cli/skills.js

@@ -36,6 +36,12 @@ export async function installSkills(options = {}) {
         skills: selectedSkills
     };
 }
+export async function listBundledSkills() {
+    const pkgRoot = findPackageRoot();
+    const sourceRoot = join(pkgRoot, 'skills');
+    await assertDirectory(sourceRoot);
+    return await listSkillNames(sourceRoot);
+}
 export function formatSkillsInstallSummary(result, cwd = process.cwd()) {
     const lines = [];
     lines.push(`Skills source: ${result.sourceRoot}`);

package/docs/README.md

@@ -101,8 +101,10 @@ Use `npx @kbediako/codex-orchestrator resume --run <run-id>` to continue interru
 ## Companion Package Commands
 - `codex-orchestrator mcp serve [--repo <path>] [--dry-run] [-- <extra args>]`: launch the MCP stdio server (delegates to `codex mcp-server`; stdout guard keeps protocol-only output, logs to stderr).
 - `codex-orchestrator init codex [--cwd <path>] [--force]`: copy starter templates into a repo (includes `mcp-client.json` and `AGENTS.md`; no overwrite unless `--force`).
-- `codex-orchestrator doctor [--format json]`: check optional tooling dependencies plus collab/cloud/delegation readiness and print enablement commands.
+- `codex-orchestrator setup [--yes]`: one-shot bootstrap for downstream users (installs bundled skills and configures delegation + DevTools wiring).
+- `codex-orchestrator doctor [--format json] [--usage] [--apply]`: check optional tooling dependencies plus collab/cloud/delegation readiness and print enablement commands. `--usage` appends a local usage snapshot (scans `.runs/`). `--apply` plans/applies quick fixes (use with `--yes`).
 - `codex-orchestrator devtools setup [--yes]`: print DevTools MCP setup instructions (`--yes` applies `codex mcp add ...`).
+- `codex-orchestrator delegation setup [--yes]`: configure delegation MCP wiring (`--yes` applies `codex mcp add ...`).
 - `codex-orchestrator skills install [--force] [--only <skills>] [--codex-home <path>]`: install bundled skills into `$CODEX_HOME/skills` (global skills remain the primary reference when installed).
 - `codex-orchestrator self-check --format json`: emit a safe JSON health payload for smoke tests.
 - `codex-orchestrator --version`: print the package version.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kbediako/codex-orchestrator",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "license": "MIT",
   "repository": {
     "type": "git",

package/skills/chrome-devtools/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: chrome-devtools
+description: Control and inspect Chrome via the Chrome DevTools MCP server (navigate, interact, screenshots, console, network, perf).
+allowed-tools: mcp__chrome-devtools__*
+---
+
+# Chrome DevTools (MCP)
+
+Use this skill when you need browser-grounded evidence (UI screenshots, console errors, network failures, perf traces) or when a task requires real page interaction.
+
+## Preflight
+
+- Ensure the MCP server is configured: `codex-orchestrator devtools setup --yes`.
+- If tools are missing in the current run, enable the server and restart the run:
+  - `codex -c 'mcp_servers.chrome-devtools.enabled=true' ...`
+
+## Default Workflow
+
+1. Open a new page and navigate to the target URL.
+2. Wait for the page to be stable (avoid racing async renders).
+3. Interact with the UI (click/fill/press) to reproduce the behavior.
+4. Collect evidence:
+   - Screenshot(s) for visual state
+   - Console messages for runtime errors
+   - Network requests for failed/slow calls
+5. Close pages when finished.
+
+## Evidence Discipline
+
+- Always capture at least one screenshot when validating UI behavior.
+- When debugging, always include:
+  - `list_console_messages`
+  - `list_network_requests` (and fetch details for failures)
+

package/skills/delegation-usage/DELEGATION_GUIDE.md

@@ -63,7 +63,7 @@ Fix by re-registering the server with a TOML-quoted override:
 codex mcp remove delegation
 codex mcp add delegation \
   --env 'CODEX_MCP_CONFIG_OVERRIDES=delegate.mode="full"' \
-  -- codex-orchestrator delegate-server --repo /path/to/repo
+  -- codex-orchestrator delegate-server
 ```
 
 ## Server mode vs child mode (don’t mix them up)
@@ -98,7 +98,7 @@ If you want deeper recursion or longer wall-clock time for delegated runs, set R
 ```bash
 codex mcp add delegation \
   --env 'CODEX_MCP_CONFIG_OVERRIDES=rlm.max_subcall_depth=8;rlm.wall_clock_timeout_ms=14400000' \
-  -- codex-orchestrator delegate-server --repo /path/to/repo
+  -- codex-orchestrator delegate-server
 ```
 
 For the `rlm` pipeline specifically, use:

package/skills/delegation-usage/SKILL.md

@@ -35,16 +35,16 @@ codex exec \
 ```
 
 Optional (only if you need it):
-- Add `--repo /path/to/repo` to the MCP args when registering the server or when you need repo-scoped config.
+- Add `--repo /path/to/repo` only when you want to pin the server to a repo even if Codex is launched outside that repo (default uses cwd).
 - Add `-c 'features.skills=false'` for a minimal, deterministic background run.
 - Add `-c 'delegate.mode=question_only'` when the child only needs `delegate.question.*` (and optional `delegate.status`).
 - Add `-c 'delegate.mode=full'` when the child needs `delegate.spawn/pause/cancel` (nested delegation / run control).
 - If the task needs external docs or APIs, enable only the relevant MCP server for that environment.
 - If `delegate.spawn` is missing, re-register the MCP server with full mode (server config controls tool surface):
   - `codex mcp remove delegation`
-  - `codex mcp add delegation --env 'CODEX_MCP_CONFIG_OVERRIDES=delegate.mode="full"' -- codex-orchestrator delegate-server --repo /path/to/repo`
+  - `codex mcp add delegation --env 'CODEX_MCP_CONFIG_OVERRIDES=delegate.mode="full"' -- codex-orchestrator delegate-server`
 - To raise RLM budgets for delegated runs, re-register with an override (TOML-quoted):
-  - `codex mcp add delegation --env 'CODEX_MCP_CONFIG_OVERRIDES=rlm.max_subcall_depth=8;rlm.wall_clock_timeout_ms=14400000' -- codex-orchestrator delegate-server --repo /path/to/repo`
+  - `codex mcp add delegation --env 'CODEX_MCP_CONFIG_OVERRIDES=rlm.max_subcall_depth=8;rlm.wall_clock_timeout_ms=14400000' -- codex-orchestrator delegate-server`
 
 For deeper background patterns and troubleshooting, see `DELEGATION_GUIDE.md`.
 For runner + delegation coordination (short `--task` flow), see `docs/delegation-runner-workflow.md`.
@@ -64,8 +64,12 @@ For runner + delegation coordination (short `--task` flow), see `docs/delegation
 ### 0) One-time setup (register the MCP server)
 
 - Register the delegation server once:
+  - Preferred: `codex-orchestrator setup --yes`
+    - One-shot bootstrap (installs bundled skills + configures delegation/DevTools wiring).
+  - `codex-orchestrator delegation setup --yes`
+    - Delegation-only setup (wraps `codex mcp add delegation ...` and keeps wiring discoverable via `codex-orchestrator doctor`).
   - `codex mcp add delegation -- codex-orchestrator delegate-server`
-  - Optional (recommended for repo-scoped config): append `--repo /path/to/repo` to the args.
+  - Optional: append `--repo /path/to/repo` to pin the server to one repo (not recommended if you work across repos).
   - `delegate-server` is the canonical name; `delegation-server` is supported as an alias.
 - Per-run `-c 'mcp_servers.delegation.enabled=true'` only works **after** registration.
 - If `delegate.*` tools are missing mid-task, start a new run with: