@kbediako/codex-orchestrator 0.2.0 → 0.2.1

package/README.md

@@ -1,121 +1,81 @@
 # Codex Orchestrator
 
-Codex Orchestrator is a CLI and runtime for Codex-driven pipelines, auditable manifests, delegation MCP workflows, and downstream repo bootstrapping.
+Codex Orchestrator (CO) is a CLI and runtime for Codex-driven pipelines, auditable manifests, delegation workflows, and downstream repo bootstrapping.
 
-## Release posture
+## Release Posture
 
-This README tracks the current `main` branch. When `main` moves ahead of the latest published package, published-package users should follow the README and docs that match the tag or release they actually installed instead of assuming every source-head guide below is already shipped.
+This README tracks the current `main` branch. Published-package users should follow the README and docs for the tag or release they installed.
 
-- Release-safe docs for the current published package: [latest GitHub release](https://github.com/Kbediako/CO/releases/latest)
-- If you are pinned to the older `v0.1.38` package, use the matching [README for `v0.1.38`](https://github.com/Kbediako/CO/blob/v0.1.38/README.md)
-- Source-head guidance in this checkout includes the marketplace/plugin flow below plus `docs/public/downstream-setup.md` and `docs/public/provider-onboarding.md`
+- Latest package docs: [GitHub releases](https://github.com/Kbediako/CO/releases/latest)
+- Older `v0.2.0` package docs: [README for `v0.2.0`](https://github.com/Kbediako/CO/blob/v0.2.0/README.md)
+- Detailed source-head docs: [docs/book/README.md](docs/book/README.md)
 
 ## Install
 
-npm remains the supported baseline because it is the simplest way to install the CO CLI.
-
 ```bash
 npm i -g @kbediako/codex-orchestrator
 codex-orchestrator --version
 ```
 
-Node.js `>=20` is required.
+Node.js `>=20` is required. npm remains the supported baseline install path.
 
-CO currently targets Codex CLI `0.123.0`; newer candidates stay evidence-gated in `docs/guides/codex-version-policy.md`.
-The source-head marketplace/plugin guidance keeps the CO-196 packaging boundary: npm remains the release-safe baseline, while Codex plugin marketplace registration is an additive path for newer Codex CLI command surfaces.
+## Current Posture
 
-### Source-head marketplace/plugin setup
+- Current CO-local Codex CLI `0.125.0` ChatGPT-auth/appserver posture
+- Current model posture: `gpt-5.5` / `xhigh` when available in ChatGPT-auth Codex sessions
+- Portable packaged/generated defaults keep `gpt-5.4` / `xhigh` as fallback values when `gpt-5.5`, API, or cloud portability is unavailable
+- Local default runtime: `appserver`
+- Unsupported combination: `executionMode=cloud` with explicit `runtimeMode=appserver`
 
-The marketplace/plugin flow below reflects the current source tree. Published-package users, especially anyone pinned to older tags such as `v0.1.38`, should keep following the matching tagged README or release docs instead of assuming the latest source-head marketplace surfaces are already shipped. Only use the marketplace/plugin steps below when you are on `main` or on a tag or release that already includes `plugins/codex-orchestrator` and the related public docs.
+The full version and model policy lives in [docs/guides/codex-version-policy.md](docs/guides/codex-version-policy.md).
 
-For newer Codex releases that expose `codex plugin marketplace`, CO also ships a repo marketplace entry plus plugin manifests under `plugins/codex-orchestrator`. You can add the packaged or repo-root marketplace source and install the plugin from Codex:
+## Quickstart
 
 ```bash
-codex plugin marketplace add "$(npm root -g)/@kbediako/codex-orchestrator"
+codex-orchestrator init codex --cwd /path/to/repo
+cd /path/to/repo
+codex-orchestrator setup --yes --repo /path/to/repo
+codex login
+codex-orchestrator flow --task <task-id>
+codex-orchestrator doctor --format json
 ```
 
-For a local checkout, add the repository root instead of the npm install directory. For a Git-backed install, pass a Git identifier or URL such as `owner/repo[@ref]`, an HTTPS Git URL, or an SSH Git URL. Those source-driven installs can include unreleased changes; pinning an older tag such as `v0.1.38` keeps you on the pre-marketplace behavior, so use the steps below only on `main` or on a newer ref that already contains the plugin manifests and public docs mentioned here. The marketplace entry points at the packaged `plugins/codex-orchestrator` directory, and the installed plugin uses a small `node` launcher to resolve the marketplace runtime root from `${CODEX_HOME:-~/.codex}/config.toml`: local-directory sources run from the recorded source path, while Git-backed sources run from Codex's installed checkout under `${CODEX_HOME:-~/.codex}/.tmp/marketplaces/codex-orchestrator`. That keeps the MCP registration path independent of a second `codex-orchestrator` PATH entry. If you move or replace a local-directory source, or remove Codex's installed marketplace checkout, re-run `codex plugin marketplace add ...` before using the plugin again. Then open `/plugins` in Codex, install `Codex Orchestrator`, and restart Codex if it does not pick up the plugin immediately. Use the plugin browser's uninstall action to remove the plugin, `codex plugin marketplace remove codex-orchestrator` to remove the marketplace registration, or set the plugin entry in `${CODEX_HOME:-~/.codex}/config.toml` to `enabled = false` to turn it off without uninstalling.
-
-## 2-minute quickstart (current `main`)
+Use `codex login --device-auth` when browser login is not available.
 
-1. Install the downstream repo templates:
-   ```bash
-   codex-orchestrator init codex --cwd /path/to/repo
-   ```
-2. Configure bundled skills plus delegation and DevTools wiring once per machine:
-   ```bash
-   codex-orchestrator setup --yes
-   ```
-3. Log in to Codex. If browser login is not available, use device auth:
-   ```bash
-   codex login
-   # Fallback
-   codex login --device-auth
-   ```
-4. Run the default docs-first flow inside your repo:
-   ```bash
-   codex-orchestrator flow --task <task-id>
-   ```
-5. Check local readiness:
-   ```bash
-   codex-orchestrator doctor --format json
-   ```
+## Plugin Install
 
-## Downstream setup
+The npm CLI install is the baseline. Codex plugin marketplace setup is additive for Codex releases that expose plugin flows. Current Codex CLI `0.125.0` keeps marketplace management under `codex plugin marketplace ...`:
 
-These guides are current source-head docs in this checkout. Readers pinned to older releases such as `v0.1.38` should treat them as source-head-only unless they are reading a matching newer tag or source ref that already includes these files.
+```bash
+# Codex 0.121.0 accepts either command.
+codex marketplace add "$(npm root -g)/@kbediako/codex-orchestrator"
 
-- [docs/public/downstream-setup.md](docs/public/downstream-setup.md): install, repo bootstrap, machine setup, and first-run flow
-- [docs/public/provider-onboarding.md](docs/public/provider-onboarding.md): Linear and Telegram onboarding, env vars, policy examples, readiness, and smoke flow
+# Codex 0.122.0+ uses the plugin command.
+codex plugin marketplace add "$(npm root -g)/@kbediako/codex-orchestrator"
+```
 
-`init codex` also seeds provider examples under `.codex/providers/` so fresh repos do not need to hand-author the first env and policy files from scratch.
+For local checkout installs, pass the repository root instead of the npm install directory. For Git-backed installs, pass `owner/repo[@ref]`, an HTTPS Git URL, or an SSH Git URL. Use `codex plugin marketplace upgrade codex-orchestrator` to refresh a Git-backed marketplace checkout and `codex plugin marketplace remove codex-orchestrator` to remove the marketplace registration. Then open `/plugins` in Codex, install `Codex Orchestrator`, and restart Codex if the plugin is not picked up immediately. More local checkout, Git-backed, and rollback details are in [docs/book/setup.md](docs/book/setup.md).
 
-## Common commands
+## Common Commands
 
 ```bash
 codex-orchestrator flow --task <task-id>
-codex-orchestrator review --task <task-id>
-codex-orchestrator doctor --usage --window-days 30
 codex-orchestrator start diagnostics --task <task-id> --format json
-codex-orchestrator co-status
-codex-orchestrator control-host supervise status --format json
+codex-orchestrator status --run <run-id> --watch --interval 10
+codex-orchestrator review
+codex-orchestrator linear issue-context --issue-id <linear-uuid>
 ```
 
-## Skills (bundled)
-
-Install bundled skills into `$CODEX_HOME/skills`:
+Run artifacts live under `.runs/<task-id>/` and summaries under `out/<task-id>/`.
 
-```bash
-codex-orchestrator skills install
-```
+## Downstream Setup
 
-Bundled skills:
-
-- `agent-first-adoption-steering`
-- `chrome-devtools`
-- `codex-orchestrator`
-- `collab-deliberation`
-- `collab-evals`
-- `collab-subagents-first`
-- `delegate-early`
-- `delegation-usage`
-- `docs-first`
-- `elegance-review`
-- `land`
-- `linear`
-- `long-poll-wait`
-- `release`
-- `standalone-review`
-
-## Public posture
-
-- Current Codex CLI target: `0.123.0`
-- Current model posture: `gpt-5.4`
-- `explorer_fast` remains the explicit `gpt-5.3-codex-spark` file/codebase search-only exception
-- Local default runtime: `appserver`
-- `executionMode=cloud` with explicit `runtimeMode=appserver` remains unsupported
+- [Book index](docs/book/README.md): setup, operations, skills, public posture, and CO-345 evidence notes
+- [Bundled skills](skills/README.md): shipped skill roster and install behavior
+- [Downstream setup](docs/public/downstream-setup.md): install, repo bootstrap, machine setup, and first run
+- [Provider onboarding](docs/public/provider-onboarding.md): Linear and provider-worker setup
+- [Docs index](docs/README.md): repo-local documentation map
 
 ## Contributing
 
-Contributor and repo-internal guidance lives in the source repository:
-[docs/README.md](https://github.com/Kbediako/CO/blob/main/docs/README.md).
+Contributor and repo-internal guidance lives in [docs/README.md](docs/README.md).

package/dist/bin/codex-orchestrator.js

@@ -1331,6 +1331,7 @@ Commands:
   codex defaults
     --yes                  Apply setup (otherwise dry-run plan only).
     --force                Allow overwriting existing role files in ~/.codex/agents.
+    --auth-scope <portable|chatgpt>  Select portable defaults or validated ChatGPT-auth gpt-5.5 defaults.
     --format json          Emit machine-readable output.
   devtools setup          Print DevTools MCP setup instructions.
     --yes                 Apply setup by running "codex mcp add ...".
@@ -1558,6 +1559,7 @@ Subcommands:
   defaults                 Plan/apply additive global Codex defaults in ~/.codex/config.toml.
     --yes                  Apply setup (otherwise dry-run plan only).
     --force                Overwrite existing role files in ~/.codex/agents.
+    --auth-scope <portable|chatgpt>  Select portable defaults or validated ChatGPT-auth gpt-5.5 defaults.
     --format json          Emit machine-readable output.
 `);
 }

package/dist/orchestrator/src/cli/adapters/CommandBuilder.js

@@ -5,11 +5,13 @@ export class CommandBuilder {
     }
     async build(input) {
         const result = await this.executePipeline(input);
+        const failure = resolveManifestFailure(result.manifest);
         return {
             subtaskId: input.target.id,
             artifacts: [
                 { path: result.manifestPath, description: 'CLI run manifest' },
                 { path: result.logPath, description: 'Runner log (ndjson)' },
+                ...collectCommandErrorArtifacts(result.manifest.commands),
                 ...(result.manifest.cloud_execution?.diff_path
                     ? [{ path: result.manifest.cloud_execution.diff_path, description: 'Cloud diff artifact' }]
                     : [])
@@ -18,6 +20,8 @@ export class CommandBuilder {
             runId: input.runId,
             success: result.success,
             notes: result.notes.join('\n') || undefined,
+            failureStage: failure.stage,
+            failureArtifactPath: failure.artifactPath,
             cloudExecution: result.manifest.cloud_execution
                 ? {
                     taskId: result.manifest.cloud_execution.task_id,
@@ -42,3 +46,49 @@ export class CommandBuilder {
         };
     }
 }
+function resolveManifestFailure(manifest) {
+    const statusDetailStage = extractStageFromStatusDetail(manifest.status_detail);
+    const cloudStage = extractCloudStageFromStatusDetail(manifest.status_detail);
+    const fallbackFailedCommand = statusDetailStage || hasStatusDetail(manifest.status_detail) ? null : firstFailedCommand(manifest.commands);
+    const cloudFailedStage = cloudStage && hasFailedCommand(manifest.commands, cloudStage) ? cloudStage : null;
+    const stage = statusDetailStage ?? cloudFailedStage ?? fallbackFailedCommand?.id ?? null;
+    const artifactPath = stage ? findFailedCommandErrorArtifact(manifest.commands, stage) : null;
+    return { stage, artifactPath };
+}
+function hasStatusDetail(statusDetail) {
+    return statusDetail != null && statusDetail.trim().length > 0;
+}
+function extractStageFromStatusDetail(statusDetail) {
+    const match = /^(?:stage|subpipeline):(.+):(?:failed|error)$/.exec(statusDetail ?? '');
+    return match?.[1] ?? null;
+}
+function extractCloudStageFromStatusDetail(statusDetail) {
+    const match = /^cloud:(.+):(?:failed|error)$/.exec(statusDetail ?? '');
+    return match?.[1] ?? null;
+}
+function firstFailedCommand(commands) {
+    return commands.find((command) => command.status === 'failed') ?? null;
+}
+function hasFailedCommand(commands, stage) {
+    return commands.some((command) => command.status === 'failed' && command.id === stage);
+}
+function findFailedCommandErrorArtifact(commands, stage) {
+    const matching = commands.find((command) => command.status === 'failed' && command.id === stage && command.error_file);
+    return matching?.error_file ?? null;
+}
+function collectCommandErrorArtifacts(commands) {
+    const seen = new Set();
+    const artifacts = [];
+    for (const command of commands) {
+        const errorFile = command.error_file;
+        if (!errorFile || seen.has(errorFile)) {
+            continue;
+        }
+        seen.add(errorFile);
+        artifacts.push({
+            path: errorFile,
+            description: `Command error artifact (${command.id})`
+        });
+    }
+    return artifacts;
+}

package/dist/orchestrator/src/cli/adapters/cloudFailureDiagnostics.js

@@ -60,6 +60,18 @@ const CLOUD_FAILURE_RULES = [
         ],
         guidance: 'Codex Cloud rejected this run; verify the configured cloud environment, branch, and account permission for cloud execution.'
     },
+    {
+        category: 'configuration',
+        diagnostic_category: 'environment_not_found',
+        patterns: ['environment_not_found', 'environment not found', 'is not visible to codex cloud'],
+        guidance: 'CODEX_CLOUD_ENV_ID is configured, but Codex Cloud could not resolve it. Fix the env id or choose an environment visible to this account.'
+    },
+    {
+        category: 'configuration',
+        diagnostic_category: 'environment_unavailable',
+        patterns: ['environment_unavailable', 'could not be verified by codex cloud'],
+        guidance: 'CODEX_CLOUD_ENV_ID is configured, but this account cannot use that environment right now. Verify visibility/permissions and retry.'
+    },
     {
         category: 'configuration',
         diagnostic_category: 'env_config',
@@ -135,6 +147,8 @@ const MACHINE_READABLE_CLOUD_DETAILS = new Set([
     'cloud_denial',
     'cloud_denied',
     'cloud_env_missing',
+    'environment_not_found',
+    'environment_unavailable',
     'cloud_execution_denied',
     'cloud_connector_auth_drift',
     'codex_cloud_env_id',
@@ -152,14 +166,100 @@ const MACHINE_READABLE_CLOUD_DETAILS = new Set([
     'rate_limited',
     'usage_limit_reached'
 ]);
-function matchCloudFailureRule(signal) {
+function isEnvironmentNotFoundSignal(signal) {
     const lowercase = signal.toLowerCase();
-    const normalized = normalizeCloudFailureSignal(signal);
-    return CLOUD_FAILURE_RULES.find((rule) => rule.patterns.some((pattern) => {
+    if (/\benvironment_not_found\b/u.test(lowercase)) {
+        return true;
+    }
+    if (!/\benvironment\s+(?:['"][^'"]+['"]|[^\s'"]+)\s+not\s+found\b/u.test(lowercase)) {
+        return false;
+    }
+    return (lowercase.includes('codex_cloud_env_id') ||
+        lowercase.includes('codex cloud env id') ||
+        lowercase.includes('is not visible to codex cloud') ||
+        lowercase.includes('could not be verified by codex cloud'));
+}
+function matchesCloudFailureRule(rule, lowercase, normalized) {
+    return rule.patterns.some((pattern) => {
         const normalizedPattern = normalizeCloudFailureSignal(pattern);
         return lowercase.includes(pattern) ||
             (normalizedPattern.length >= 4 && normalized.includes(normalizedPattern));
-    })) ?? null;
+    });
+}
+function findCloudFailureRule(diagnosticCategory) {
+    return CLOUD_FAILURE_RULES.find((rule) => rule.diagnostic_category === diagnosticCategory) ?? null;
+}
+function findMatchedCloudFailureRule(diagnosticCategory, signal) {
+    const rule = findCloudFailureRule(diagnosticCategory);
+    if (!rule) {
+        return null;
+    }
+    const lowercase = signal.toLowerCase();
+    const normalized = normalizeCloudFailureSignal(signal);
+    return matchesCloudFailureRule(rule, lowercase, normalized) ? rule : null;
+}
+function maskEnvConfigIdentifierValues(normalizedSignal) {
+    return normalizedSignal
+        .replace(/\bcodex_cloud_env_id\s+(?:['"][^'"]+['"]|[^\s'"]+)/gu, 'codex_cloud_env_id <env-id>')
+        .replace(/\bcodex cloud env id\s+(?:['"][^'"]+['"]|[^\s'"]+)/gu, 'codex cloud env id <env-id>')
+        .replace(/\benvironment\s+(?:['"][^'"]+['"]|[^\s'"]+)\s+not\s+found\b/gu, 'environment <env-id> not found');
+}
+function hasStrongConnectivityContext(signal) {
+    const normalized = maskEnvConfigIdentifierValues(signal.toLowerCase());
+    return (normalized.includes('enotfound') ||
+        normalized.includes('econn') ||
+        normalized.includes('bad gateway') ||
+        normalized.includes('service unavailable') ||
+        normalized.includes('gateway timeout') ||
+        /\bnetwork\W{0,24}(?:error|failure|unreachable|unavailable|timeout|timed out|connection|connectivity)\b/u.test(normalized) ||
+        /\b(?:request|connection|endpoint|gateway|upstream|service)\W{0,24}(?:timed out|timeout)\b/u.test(normalized) ||
+        /\b(?:timed out|timeout)\W{0,24}(?:(?:while\s+)?(?:contacting|connecting|reaching|calling|waiting)|request|connection|endpoint|gateway|upstream|service|after)\b/u.test(normalized) ||
+        /\b(?:http(?:\s+(?:status|response))?|status|response|upstream|gateway|error|failed|returned)\D{0,16}(?:502|503|504)\b/u.test(normalized) ||
+        /\b(?:502|503|504)\D{0,16}(?:bad gateway|service unavailable|gateway timeout)\b/u.test(normalized));
+}
+function matchCloudFailureRule(signal) {
+    const lowercase = signal.toLowerCase();
+    const normalized = normalizeCloudFailureSignal(signal);
+    const envConfigRule = findCloudFailureRule('env_config');
+    if (isEnvironmentNotFoundSignal(signal)) {
+        const specificRule = matchSpecificWrappedFailureRule(signal, lowercase, normalized);
+        if (specificRule) {
+            return specificRule;
+        }
+        return findCloudFailureRule('environment_not_found');
+    }
+    if (envConfigRule && matchesCloudFailureRule(envConfigRule, lowercase, normalized)) {
+        const specificRule = matchSpecificWrappedFailureRule(signal, lowercase, normalized);
+        if (specificRule) {
+            return specificRule;
+        }
+        const envUnavailableRule = findCloudFailureRule('environment_unavailable');
+        if (envUnavailableRule && matchesCloudFailureRule(envUnavailableRule, lowercase, normalized)) {
+            return envUnavailableRule;
+        }
+    }
+    return CLOUD_FAILURE_RULES.find((rule) => matchesCloudFailureRule(rule, lowercase, normalized)) ?? null;
+}
+function matchSpecificWrappedFailureRule(signal, lowercase, normalized) {
+    const maskedSignal = maskEnvConfigIdentifierValues(lowercase);
+    for (const diagnosticCategory of [
+        'cloud_connector_auth_drift',
+        'cloud_denial',
+        'auth_mismatch',
+        'quota_rate_limit'
+    ]) {
+        const rule = findMatchedCloudFailureRule(diagnosticCategory, maskedSignal);
+        if (rule) {
+            return rule;
+        }
+    }
+    const connectivityRule = findCloudFailureRule('network_connectivity');
+    if (connectivityRule &&
+        matchesCloudFailureRule(connectivityRule, lowercase, normalized) &&
+        hasStrongConnectivityContext(signal)) {
+        return connectivityRule;
+    }
+    return null;
 }
 function normalizeCloudFailureSignal(signal) {
     return signal
@@ -169,8 +269,11 @@ function normalizeCloudFailureSignal(signal) {
         .replace(/\s+/gu, ' ')
         .trim();
 }
+function normalizeMachineReadableCloudDetail(signal) {
+    return normalizeCloudFailureSignal(signal).replace(/\s+/gu, '_');
+}
 function isMachineReadableCloudDetail(signal) {
-    return MACHINE_READABLE_CLOUD_DETAILS.has(normalizeCloudFailureSignal(signal).replace(/\s+/gu, '_'));
+    return MACHINE_READABLE_CLOUD_DETAILS.has(normalizeMachineReadableCloudDetail(signal));
 }
 function buildCloudFailureDiagnosis(rule, signal) {
     return {
@@ -187,6 +290,15 @@ export function diagnoseCloudFailure(options) {
     if (options.statusDetail && isMachineReadableCloudDetail(options.statusDetail)) {
         const statusDetailRule = matchCloudFailureRule(options.statusDetail);
         if (statusDetailRule) {
+            if (normalizeMachineReadableCloudDetail(options.statusDetail) === 'environment_unavailable' &&
+                options.error) {
+                const errorRule = matchCloudFailureRule(options.error);
+                if (errorRule &&
+                    errorRule.diagnostic_category !== 'environment_unavailable' &&
+                    errorRule.diagnostic_category !== 'env_config') {
+                    return buildCloudFailureDiagnosis(errorRule, signal);
+                }
+            }
             return buildCloudFailureDiagnosis(statusDetailRule, signal);
         }
     }

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

@@ -275,9 +275,9 @@ function formatAttachRequestFailure(error, target, options = {}) {
     if (error instanceof CoStatusAttachRequestError) {
         if (error.kind === 'network') {
             if (options.endpointAlreadyRotated) {
-                return `${error.message}. The refreshed control-host endpoint is still unreachable; wait for the new host to come up or rerun co-status attach.`;
+                return `current-host-unhealthy: ${error.message}. The refreshed control-host endpoint is still unreachable; wait for the new host to come up or rerun co-status attach.`;
             }
-            return `stale endpoint after control-host restart; control-host unavailable; control_endpoint.json has not rotated to a reachable host. ${error.message}. Waiting for ${resolve(target.runDir, 'control_endpoint.json')} to rotate or rerun co-status attach.`;
+            return `current-host-unhealthy: control_endpoint.json; control-host unavailable; stale endpoint after control-host restart. control_endpoint.json has not rotated to a reachable host. ${error.message}. Waiting for ${resolve(target.runDir, 'control_endpoint.json')} to rotate or rerun co-status attach.`;
         }
         if (error.kind === 'timeout') {
             return `${error.message}. The control-host did not answer before the attach timeout; if restart is in progress, wait for endpoint rotation or rerun co-status attach.`;

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

@@ -14,6 +14,10 @@ const LOCAL_DEGRADED_FALLBACK_ALLOWED_VERDICTS = new Set([
     'degraded'
 ]);
 const LOCAL_DEGRADED_FALLBACK_ALLOWED_FINDING_CODES = new Set(['active_worker_proof_missing']);
+const CURRENT_HOST_UNHEALTHY_MARKER = 'current-host-unhealthy';
+const CURRENT_HOST_UNHEALTHY_STALE_ENDPOINT_FALLBACK = 'control-host unavailable; stale endpoint after control-host restart';
+const LEGACY_CURRENT_HOST_UNHEALTHY_STALE_ENDPOINT_FALLBACK = 'control-host unavailable; control_endpoint.json has not rotated to a reachable host';
+const CURRENT_HOST_UNHEALTHY_ROTATED_ENDPOINT_FALLBACK = 'refreshed control-host endpoint is still unreachable';
 export async function runCoStatusCliShell(params) {
     if (params.flags.help !== undefined) {
         params.printHelp();
@@ -69,7 +73,8 @@ function assertAttachCompatibleFlags(flags) {
     throw new Error(`co-status attaches to an existing control host and does not accept launch-only flags: ${renderedFlags}. Use \`control-host\` to start a control host with launch settings.`);
 }
 async function tryReadLocalDegradedUiDataset(input) {
-    if (!isUiRequestTimeoutError(input.error)) {
+    const degradedReason = resolveLocalDegradedReadReason(input.error);
+    if (!degradedReason) {
         return null;
     }
     const freshnessReport = await evaluateProviderControlHostFreshnessGauge({
@@ -88,12 +93,29 @@ async function tryReadLocalDegradedUiDataset(input) {
     }
     return {
         ...dataset,
-        degraded_read: buildDegradedReadPayload(input.target, freshnessReport)
+        degraded_read: buildDegradedReadPayload(input.target, freshnessReport, degradedReason)
     };
 }
-function isUiRequestTimeoutError(error) {
+function resolveLocalDegradedReadReason(error) {
     const message = error?.message ?? String(error);
-    return message.includes('control-host ui request timeout after');
+    if (message.includes('Re-resolving control_endpoint.json failed')) {
+        return null;
+    }
+    if (isCurrentHostUnhealthyErrorMessage(message)) {
+        return 'current_host_unhealthy';
+    }
+    if (message.includes('control-host ui request timeout after')) {
+        return 'ui_request_timeout';
+    }
+    return null;
+}
+function isCurrentHostUnhealthyErrorMessage(message) {
+    return [
+        CURRENT_HOST_UNHEALTHY_MARKER,
+        CURRENT_HOST_UNHEALTHY_STALE_ENDPOINT_FALLBACK,
+        LEGACY_CURRENT_HOST_UNHEALTHY_STALE_ENDPOINT_FALLBACK,
+        CURRENT_HOST_UNHEALTHY_ROTATED_ENDPOINT_FALLBACK
+    ].some((fragment) => message.includes(fragment));
 }
 function isEligibleLocalDegradedFallbackFreshnessReport(report) {
     if (LOCAL_DEGRADED_FALLBACK_ALLOWED_VERDICTS.has(report.verdict)) {
@@ -105,9 +127,9 @@ function isEligibleLocalDegradedFallbackFreshnessReport(report) {
     return (report.findings.length > 0 &&
         report.findings.every((finding) => LOCAL_DEGRADED_FALLBACK_ALLOWED_FINDING_CODES.has(finding.code)));
 }
-function buildDegradedReadPayload(target, report) {
+function buildDegradedReadPayload(target, report, reason) {
     return {
-        reason: 'ui_request_timeout',
+        reason,
         source: 'local_seeded_runtime',
         freshness_verdict: report.verdict,
         artifact_root: target.runDir,

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

@@ -1,6 +1,8 @@
 /* eslint-disable patterns/prefer-logger-over-console */
 import { formatCodexCliSetupSummary, runCodexCliSetup } from './codexCliSetup.js';
 import { formatCodexDefaultsSetupSummary, runCodexDefaultsSetup } from './codexDefaultsSetup.js';
+const LEGACY_CHATGPT_AUTH_TRUE_VALUES = new Set(['true', '1', 'yes', 'on', 'enabled']);
+const LEGACY_CHATGPT_AUTH_FALSE_VALUES = new Set(['false', '0', 'no', 'off', 'disabled']);
 const DEFAULT_DEPENDENCIES = {
     runCodexCliSetup,
     runCodexDefaultsSetup,
@@ -48,9 +50,11 @@ export async function runCodexCliShell(params, overrides = {}) {
         const format = resolveOutputFormat(params.flags);
         const apply = Boolean(params.flags['yes']);
         const force = Boolean(params.flags['force']);
+        const authScope = readAuthScopeFlag(params.flags);
         const result = await dependencies.runCodexDefaultsSetup({
             apply,
-            force
+            force,
+            authScope
         });
         if (format === 'json') {
             dependencies.log(JSON.stringify(result, null, 2));
@@ -70,3 +74,46 @@ function readStringFlag(flags, key) {
     const value = flags[key];
     return typeof value === 'string' ? value : undefined;
 }
+function readAuthScopeFlag(flags) {
+    const legacyChatGptAuth = readLegacyChatGptAuthFlag(flags);
+    if (!Object.prototype.hasOwnProperty.call(flags, 'auth-scope')) {
+        if (legacyChatGptAuth === true) {
+            return 'chatgpt';
+        }
+        if (legacyChatGptAuth === false) {
+            return 'portable';
+        }
+        return undefined;
+    }
+    const value = readStringFlag(flags, 'auth-scope');
+    if (value === undefined) {
+        throw new Error('Missing value for codex defaults auth scope: expected portable or chatgpt.');
+    }
+    if (legacyChatGptAuth === true && value !== 'chatgpt') {
+        throw new Error('Conflicting codex defaults auth scope: --chatgpt-auth requires --auth-scope chatgpt.');
+    }
+    if (legacyChatGptAuth === false && value !== 'portable') {
+        throw new Error('Conflicting codex defaults auth scope: --chatgpt-auth=false requires --auth-scope portable.');
+    }
+    if (value === 'portable' || value === 'chatgpt') {
+        return value;
+    }
+    throw new Error(`Invalid codex defaults auth scope: ${value}`);
+}
+function readLegacyChatGptAuthFlag(flags) {
+    if (!Object.prototype.hasOwnProperty.call(flags, 'chatgpt-auth')) {
+        return undefined;
+    }
+    const value = flags['chatgpt-auth'];
+    if (typeof value === 'boolean') {
+        return value;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (LEGACY_CHATGPT_AUTH_TRUE_VALUES.has(normalized)) {
+        return true;
+    }
+    if (LEGACY_CHATGPT_AUTH_FALSE_VALUES.has(normalized)) {
+        return false;
+    }
+    throw new Error(`Invalid codex defaults ChatGPT auth flag: --chatgpt-auth expected a boolean-like value, got ${value}.`);
+}