@kbediako/codex-orchestrator 0.2.0 → 0.2.1

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

@@ -6,6 +6,7 @@ import { release as osRelease } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { buildDevtoolsSetupPlan, DEVTOOLS_SKILL_NAME, resolveDevtoolsReadiness } from './utils/devtools.js';
 import { isManagedCodexCliEnabled, resolveCodexCliBin, resolveCodexCliReadiness } from './utils/codexCli.js';
+import { codexFeatureProbeDisablesMultiAgentV2, codexFeatureProbeRejectsAgentMaxThreads, readCodexFeatureProbe } from './utils/codexFeatures.js';
 import { resolveCodexHome } from './utils/codexPaths.js';
 import { resolveOptionalDependency } from './utils/optionalDeps.js';
 import { buildCloudPreflightAuthProvenance, buildCloudPreflightRequest, runCloudPreflight } from './utils/cloudPreflight.js';
@@ -13,7 +14,7 @@ import { classifyDelegationTransport, formatDelegateServerProcessSummary, inspec
 import { sanitizeProviderOverrideEnv } from './utils/providerOverrideEnv.js';
 import { hasLinearApiCredentials, hasLinearSourceBinding, resolveLinearSourceSetup } from './control/linearDispatchSource.js';
 import { normalizeDispatchSourceProvider } from './control/trackerDispatchPilot.js';
-import { BASELINE_AGENTS, BASELINE_MODEL, BASELINE_REVIEW_MODEL, BASELINE_REASONING_MINIMUM } from './codexDefaultsSetup.js';
+import { BASELINE_AGENTS, BASELINE_MODEL, BASELINE_REVIEW_MODEL, BASELINE_REASONING_MINIMUM, formatModelDefaultExpectation, isLocalModelOptIn } from './codexDefaultsSetup.js';
 import { CommandPlanner } from './adapters/CommandPlanner.js';
 import { PipelineResolver } from './services/pipelineResolver.js';
 import { isRepoConfigRequired } from './config/repoConfigPolicy.js';
@@ -29,6 +30,7 @@ const OPTIONAL_DEPENDENCIES = [
     { name: 'cheerio', install: 'npm install --save-dev cheerio' }
 ];
 const PROVIDER_ROOT_RELATIVE_PATH = '.codex/providers';
+const CODEX_DEBUG_MODELS_JSON_ENV = 'CODEX_ORCHESTRATOR_DEBUG_MODELS_JSON';
 export function runDoctor(cwd = process.cwd()) {
     const dependencies = OPTIONAL_DEPENDENCIES.map((entry) => {
         const resolved = resolveOptionalDependency(entry.name, cwd);
@@ -85,11 +87,12 @@ export function runDoctor(cwd = process.cwd()) {
     if (readiness.config.status !== 'ok') {
         missing.push(`${DEVTOOLS_SKILL_NAME}-config`);
     }
-    const codexDefaults = inspectCodexDefaultsAdvisory(process.env);
     const codexBin = resolveCodexCliBin(process.env);
     const managedOptIn = isManagedCodexCliEnabled(process.env);
     const managedCodex = resolveCodexCliReadiness(process.env);
-    const features = readCodexFeatureFlags(codexBin);
+    const featureProbe = readCodexFeatureProbe(codexBin, process.env);
+    const features = featureProbe.flags;
+    const codexDefaults = inspectCodexDefaultsAdvisory(process.env, codexBin, featureProbe);
     const collabFeatureKey = features === null
         ? null
         : Object.prototype.hasOwnProperty.call(features, 'multi_agent')
@@ -473,7 +476,15 @@ export function formatDoctorSummary(result) {
     lines.push(`  - model: ${result.codex_defaults.checks.model.status} (actual: ${result.codex_defaults.checks.model.actual ?? '<unset>'}, expected: ${result.codex_defaults.checks.model.expected})`);
     lines.push(`  - review_model: ${result.codex_defaults.checks.review_model.status} (actual: ${result.codex_defaults.checks.review_model.actual ?? '<unset>'}, expected: ${result.codex_defaults.checks.review_model.expected})`);
     lines.push(`  - model_reasoning_effort: ${result.codex_defaults.checks.model_reasoning_effort.status} (actual: ${result.codex_defaults.checks.model_reasoning_effort.actual ?? '<unset>'}, expected >= ${result.codex_defaults.checks.model_reasoning_effort.expected_minimum})`);
-    lines.push(`  - agents.max_threads: ${result.codex_defaults.checks.max_threads.status} (actual: ${result.codex_defaults.checks.max_threads.actual ?? '<unset>'}, expected >= ${result.codex_defaults.checks.max_threads.expected_minimum})`);
+    if (result.codex_defaults.checks.max_threads.status === 'skipped') {
+        lines.push(`  - agents.max_threads: skipped (actual: ${result.codex_defaults.checks.max_threads.actual ?? '<unset>'}; ${result.codex_defaults.checks.max_threads.detail ?? 'omitted by policy'})`);
+    }
+    else if (result.codex_defaults.checks.max_threads.detail) {
+        lines.push(`  - agents.max_threads: ${result.codex_defaults.checks.max_threads.status} (actual: ${result.codex_defaults.checks.max_threads.actual ?? '<unset>'}; ${result.codex_defaults.checks.max_threads.detail})`);
+    }
+    else {
+        lines.push(`  - agents.max_threads: ${result.codex_defaults.checks.max_threads.status} (actual: ${result.codex_defaults.checks.max_threads.actual ?? '<unset>'}, expected >= ${result.codex_defaults.checks.max_threads.expected_minimum})`);
+    }
     lines.push(`  - agents.max_depth: ${result.codex_defaults.checks.max_depth.status} (actual: ${result.codex_defaults.checks.max_depth.actual ?? '<unset>'}, expected >= ${result.codex_defaults.checks.max_depth.expected_minimum} when set; <unset> accepted)`);
     if (result.codex_defaults.legacy_max_spawn_depth?.present) {
         lines.push(`  - legacy agents.max_spawn_depth: ${result.codex_defaults.legacy_max_spawn_depth.status} (actual: ${result.codex_defaults.legacy_max_spawn_depth.actual ?? '<unset>'}; ${result.codex_defaults.legacy_max_spawn_depth.detail})`);
@@ -661,11 +672,15 @@ function inspectProviderReadiness(repoRoot, env = process.env) {
         ]
     };
 }
-function inspectCodexDefaultsAdvisory(env = process.env) {
+function inspectCodexDefaultsAdvisory(env = process.env, codexBin = resolveCodexCliBin(env), featureProbe = readCodexFeatureProbe(codexBin, env)) {
     const configPath = join(resolveCodexHome(env), 'config.toml');
     const checks = {
-        model: { status: 'advisory', expected: BASELINE_MODEL, actual: null },
-        review_model: { status: 'advisory', expected: BASELINE_REVIEW_MODEL, actual: null },
+        model: { status: 'advisory', expected: formatModelDefaultExpectation(BASELINE_MODEL), actual: null },
+        review_model: {
+            status: 'advisory',
+            expected: formatModelDefaultExpectation(BASELINE_REVIEW_MODEL),
+            actual: null
+        },
         model_reasoning_effort: { status: 'advisory', expected_minimum: BASELINE_REASONING_MINIMUM, actual: null },
         max_threads: { status: 'advisory', expected_minimum: BASELINE_AGENTS.max_threads, actual: null },
         max_depth: { status: 'advisory', expected_minimum: BASELINE_AGENTS.max_depth, actual: null }
@@ -673,10 +688,21 @@ function inspectCodexDefaultsAdvisory(env = process.env) {
     let legacyMaxSpawnDepth = null;
     const guidance = [
         'Run `codex-orchestrator codex defaults --yes` to apply additive baseline defaults.',
-        'Additive policy: unrelated config keys are preserved; existing role files stay untouched unless `--force` is set.',
+        'Additive policy: unrelated config keys are preserved; existing role files stay untouched unless `--force` is set or they exactly match a prior CO-managed model baseline.',
+        'When `features.multi_agent_v2=true`, omit `agents.max_threads`; Codex CLI 0.125+ rejects that key.',
         'Current CO baseline no longer seeds or expects `agents.max_spawn_depth`; keep it only as a legacy local override when an older parser/runtime still honors it.',
         'Leaving `agents.max_depth` unset remains accepted when local parser/runtime constraints require it.'
     ];
+    const featureProbeDisablesMultiAgentV2 = featureProbe ? codexFeatureProbeDisablesMultiAgentV2(featureProbe) : false;
+    const featureProbeIndicatesMultiAgentV2 = !featureProbeDisablesMultiAgentV2
+        && (featureProbe?.flags?.multi_agent_v2 === true
+            || (featureProbe ? codexFeatureProbeRejectsAgentMaxThreads(featureProbe) : false));
+    if (featureProbeIndicatesMultiAgentV2) {
+        checks.max_threads.status = 'skipped';
+        checks.max_threads.actual = null;
+        checks.max_threads.detail =
+            'features.multi_agent_v2=true; omit agents.max_threads because Codex CLI 0.125+ rejects it';
+    }
     if (!existsSync(configPath)) {
         return {
             status: 'advisory',
@@ -710,23 +736,55 @@ function inspectCodexDefaultsAdvisory(env = process.env) {
         };
     }
     const model = normalizeOptionalString(readStringValue(parsed.model));
-    checks.model.actual = model;
-    checks.model.status = model === BASELINE_MODEL ? 'ok' : 'advisory';
     const reviewModel = normalizeOptionalString(readStringValue(parsed.review_model));
+    const localModelCandidates = new Set([model, reviewModel].filter(isLocalModelOptIn));
+    const modelAccess = localModelCandidates.size === 0
+        ? {
+            status: 'unavailable',
+            models: new Set(),
+            detail: 'model access was not checked because no local ChatGPT-auth model is configured'
+        }
+        : inspectCodexModelAccess(codexBin, env);
+    const verifiedLocalModels = new Set([...localModelCandidates].filter((candidate) => modelAccess.status === 'ok' && modelAccess.models.has(candidate)));
+    const unverifiedLocalModels = [...localModelCandidates].filter((candidate) => !verifiedLocalModels.has(candidate));
+    for (const candidate of unverifiedLocalModels) {
+        guidance.push(`Configured local ChatGPT-auth model ${candidate} is not verified by \`codex debug models\`; rerun local access smoke or use the portable ${BASELINE_MODEL} fallback for this surface.`);
+    }
+    checks.model.actual = model;
+    checks.model.status =
+        model === BASELINE_MODEL || (isLocalModelOptIn(model) && verifiedLocalModels.has(model))
+            ? 'ok'
+            : 'advisory';
     checks.review_model.actual = reviewModel;
-    checks.review_model.status = reviewModel === BASELINE_REVIEW_MODEL ? 'ok' : 'advisory';
+    checks.review_model.status =
+        reviewModel === BASELINE_REVIEW_MODEL || (isLocalModelOptIn(reviewModel) && verifiedLocalModels.has(reviewModel))
+            ? 'ok'
+            : 'advisory';
     const reasoning = normalizeOptionalString(readStringValue(parsed.model_reasoning_effort));
     checks.model_reasoning_effort.actual = reasoning;
     checks.model_reasoning_effort.status = isReasoningAtLeastMinimum(reasoning, BASELINE_REASONING_MINIMUM)
         ? 'ok'
         : 'advisory';
     const agents = isRecord(parsed.agents) ? parsed.agents : {};
+    const multiAgentV2Enabled = featureProbeIndicatesMultiAgentV2
+        || (!featureProbeDisablesMultiAgentV2
+            && readBooleanValue(readRecordValue(parsed, 'features')?.multi_agent_v2) === true);
     const maxThreads = readNumberValue(agents.max_threads);
     const maxDepth = readNumberValue(agents.max_depth);
     const maxSpawnDepth = readNumberValue(agents.max_spawn_depth);
+    const hasMaxThreads = Object.prototype.hasOwnProperty.call(agents, 'max_threads');
     checks.max_threads.actual = maxThreads;
-    checks.max_threads.status =
-        typeof maxThreads === 'number' && maxThreads >= BASELINE_AGENTS.max_threads ? 'ok' : 'advisory';
+    if (multiAgentV2Enabled) {
+        checks.max_threads.status = hasMaxThreads ? 'advisory' : 'skipped';
+        checks.max_threads.detail =
+            hasMaxThreads
+                ? 'features.multi_agent_v2=true; remove agents.max_threads because Codex CLI 0.125+ rejects it'
+                : 'features.multi_agent_v2=true; omit agents.max_threads because Codex CLI 0.125+ rejects it';
+    }
+    else {
+        checks.max_threads.status =
+            typeof maxThreads === 'number' && maxThreads >= BASELINE_AGENTS.max_threads ? 'ok' : 'advisory';
+    }
     checks.max_depth.actual = maxDepth;
     checks.max_depth.status =
         maxDepth === null || (typeof maxDepth === 'number' && maxDepth >= BASELINE_AGENTS.max_depth) ? 'ok' : 'advisory';
@@ -741,7 +799,8 @@ function inspectCodexDefaultsAdvisory(env = process.env) {
                 : `older parser/runtime may still treat this as a hard cap below the CO baseline depth; raise it to >= ${BASELINE_AGENTS.max_depth} or remove it`
         };
     }
-    const allChecksOk = Object.values(checks).every((check) => check.status === 'ok')
+    const allChecksOk = Object.values(checks).every((check) => check.status === 'ok' || check.status === 'skipped')
+        && unverifiedLocalModels.length === 0
         && legacyMaxSpawnDepth?.status !== 'advisory';
     return {
         status: allChecksOk ? 'ok' : 'advisory',
@@ -751,6 +810,69 @@ function inspectCodexDefaultsAdvisory(env = process.env) {
         guidance
     };
 }
+function inspectCodexModelAccess(codexBin, env) {
+    const overrideJson = env[CODEX_DEBUG_MODELS_JSON_ENV];
+    if (typeof overrideJson === 'string' && overrideJson.trim().length > 0) {
+        return parseCodexDebugModels(overrideJson, `${CODEX_DEBUG_MODELS_JSON_ENV} override`);
+    }
+    const result = spawnSync(codexBin, ['debug', 'models'], {
+        encoding: 'utf8',
+        env,
+        timeout: 5000,
+        maxBuffer: 5 * 1024 * 1024
+    });
+    if (result.error) {
+        return {
+            status: 'unavailable',
+            models: new Set(),
+            detail: result.error.message
+        };
+    }
+    if (result.status !== 0) {
+        const stderr = typeof result.stderr === 'string' ? result.stderr.trim() : '';
+        return {
+            status: 'unavailable',
+            models: new Set(),
+            detail: stderr || `codex debug models exited ${result.status ?? 'without a status'}`
+        };
+    }
+    return parseCodexDebugModels(result.stdout, '`codex debug models`');
+}
+function parseCodexDebugModels(source, detailPrefix) {
+    if (typeof source !== 'string' || source.trim().length === 0) {
+        return {
+            status: 'unavailable',
+            models: new Set(),
+            detail: `${detailPrefix} produced no model catalog output`
+        };
+    }
+    try {
+        const parsed = JSON.parse(source);
+        const models = new Set();
+        const entries = isRecord(parsed) && Array.isArray(parsed.models) ? parsed.models : [];
+        for (const entry of entries) {
+            if (!isRecord(entry)) {
+                continue;
+            }
+            const slug = readStringValue(entry.slug);
+            if (slug) {
+                models.add(slug);
+            }
+        }
+        return {
+            status: models.size > 0 ? 'ok' : 'unavailable',
+            models,
+            detail: `${detailPrefix} reported ${models.size} model(s)`
+        };
+    }
+    catch (error) {
+        return {
+            status: 'unavailable',
+            models: new Set(),
+            detail: error instanceof Error ? error.message : String(error)
+        };
+    }
+}
 function getTomlParser() {
     if (tomlParser) {
         return tomlParser;
@@ -1077,6 +1199,12 @@ function buildCloudPreflightGuidance(issues) {
             case 'missing_environment':
                 guidance.push('Set CODEX_CLOUD_ENV_ID or provide target metadata.cloudEnvId.');
                 break;
+            case 'environment_not_found':
+                guidance.push('Set CODEX_CLOUD_ENV_ID to a Codex Cloud environment visible to the active account; run `codex cloud` to list available environments.');
+                break;
+            case 'environment_unavailable':
+                guidance.push('Verify the active Codex account/profile can read CODEX_CLOUD_ENV_ID before running required cloud canaries.');
+                break;
             case 'branch_missing':
                 guidance.push('Push the branch to origin or set CODEX_CLOUD_BRANCH to an existing remote branch.');
                 break;
@@ -1095,40 +1223,6 @@ function buildCloudPreflightGuidance(issues) {
     }
     return [...new Set(guidance)];
 }
-function readCodexFeatureFlags(codexBin) {
-    const result = spawnSync(codexBin, ['features', 'list'], {
-        encoding: 'utf8',
-        stdio: ['ignore', 'pipe', 'pipe'],
-        timeout: 5000
-    });
-    if (result.error || result.status !== 0) {
-        return null;
-    }
-    const stdout = String(result.stdout ?? '');
-    const flags = {};
-    for (const line of stdout.split(/\r?\n/u)) {
-        const trimmed = line.trim();
-        if (!trimmed) {
-            continue;
-        }
-        const tokens = trimmed.split(/\s+/u);
-        if (tokens.length < 2) {
-            continue;
-        }
-        const name = tokens[0] ?? '';
-        const enabledToken = tokens[tokens.length - 1] ?? '';
-        if (!name) {
-            continue;
-        }
-        if (enabledToken === 'true') {
-            flags[name] = true;
-        }
-        else if (enabledToken === 'false') {
-            flags[name] = false;
-        }
-    }
-    return flags;
-}
 function canRunCommand(command, args) {
     const result = spawnSync(command, args, {
         encoding: 'utf8',

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

@@ -1,12 +1,21 @@
-import { copyFile, mkdir, readdir, stat } from 'node:fs/promises';
+import { copyFile, mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import { dirname, join, relative } from 'node:path';
+import process from 'node:process';
+import { resolveCodexHome } from './utils/codexPaths.js';
+import { resolveCodexCliBin } from './utils/codexCli.js';
+import { codexFeatureProbeDisablesMultiAgentV2, codexFeatureProbeRejectsAgentMaxThreads, readCodexFeatureProbe } from './utils/codexFeatures.js';
 import { findPackageRoot } from './utils/packageInfo.js';
 const CODEX_TEMPLATE = 'codex';
 const CODEX_PIPELINE_CONFIG = 'codex.orchestrator.json';
+const CODEX_CONFIG_TEMPLATE = join('.codex', 'config.toml');
+const require = createRequire(import.meta.url);
+let tomlLibrary;
 export async function initCodexTemplates(options) {
     const root = findPackageRoot();
     const templateRoot = join(root, 'templates', options.template);
+    const env = options.env ?? process.env;
     const written = [];
     const skipped = [];
     await assertDirectory(templateRoot);
@@ -16,6 +25,10 @@ export async function initCodexTemplates(options) {
         skipped
     });
     if (options.template === CODEX_TEMPLATE) {
+        const configPath = join(options.cwd, CODEX_CONFIG_TEMPLATE);
+        if (written.includes(configPath) && await isMultiAgentV2Enabled(env)) {
+            await omitAgentMaxThreads(configPath);
+        }
         await copyTemplateFile(join(root, CODEX_PIPELINE_CONFIG), join(options.cwd, CODEX_PIPELINE_CONFIG), {
             force: options.force,
             written,
@@ -24,6 +37,86 @@ export async function initCodexTemplates(options) {
     }
     return { written, skipped, templateRoot };
 }
+async function isMultiAgentV2Enabled(env) {
+    const featureProbe = readCodexFeatureProbe(resolveCodexCliBin(env), env);
+    if (featureProbe.flags?.multi_agent_v2 === true) {
+        return true;
+    }
+    if (codexFeatureProbeDisablesMultiAgentV2(featureProbe)) {
+        return false;
+    }
+    if (codexFeatureProbeRejectsAgentMaxThreads(featureProbe)) {
+        return true;
+    }
+    const configPath = join(resolveCodexHome(env), 'config.toml');
+    if (!existsSync(configPath)) {
+        return false;
+    }
+    let raw;
+    try {
+        raw = await readFile(configPath, 'utf8');
+    }
+    catch {
+        return false;
+    }
+    let parsed;
+    try {
+        parsed = getTomlLibrary().parse(raw);
+    }
+    catch {
+        return false;
+    }
+    if (!isRecord(parsed) || !isRecord(parsed.features)) {
+        return false;
+    }
+    return parsed.features.multi_agent_v2 === true;
+}
+async function omitAgentMaxThreads(configPath) {
+    const raw = await readFile(configPath, 'utf8');
+    const { removed, text } = removeAgentMaxThreadsFromToml(raw);
+    if (!removed) {
+        return;
+    }
+    await writeFile(configPath, text, 'utf8');
+}
+function removeAgentMaxThreadsFromToml(raw) {
+    const lines = raw.split(/(?<=\n)/u);
+    let inAgentsTable = false;
+    let removed = false;
+    const kept = [];
+    for (const line of lines) {
+        const withoutEol = line.replace(/\r?\n$/u, '');
+        const trimmed = withoutEol.trim();
+        if (/^\[[^\]]+\]\s*(?:#.*)?$/u.test(trimmed)) {
+            inAgentsTable = /^\[agents\]\s*(?:#.*)?$/u.test(trimmed);
+        }
+        if (inAgentsTable && /^[ \t]*max_threads\s*=/u.test(withoutEol)) {
+            removed = true;
+            continue;
+        }
+        kept.push(line);
+    }
+    return { removed, text: kept.join('') };
+}
+function getTomlLibrary() {
+    if (tomlLibrary) {
+        return tomlLibrary;
+    }
+    if (tomlLibrary === null) {
+        throw new Error('Failed to load @iarna/toml.');
+    }
+    try {
+        tomlLibrary = require('@iarna/toml');
+        return tomlLibrary;
+    }
+    catch (error) {
+        tomlLibrary = null;
+        throw error;
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 async function assertDirectory(path) {
     const info = await stat(path).catch(() => null);
     if (!info || !info.isDirectory()) {

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

@@ -9,7 +9,7 @@ import { fileURLToPath } from 'node:url';
 import { logger } from '../logger.js';
 import { acquireLockWithRetry } from '../persistence/lockFile.js';
 import { writeAtomicFile } from '../utils/atomicWrite.js';
-import { buildEmptyProviderLinearWorkerTokenUsage, defaultExecRunner, parseProviderLinearWorkerJsonl } from './providerLinearWorkerRunner.js';
+import { buildEmptyProviderLinearWorkerTokenUsage, defaultExecRunner, parseProviderLinearWorkerJsonl, PROVIDER_LINEAR_CHILD_LANE_DIAGNOSTICS_FILENAME } from './providerLinearWorkerRunner.js';
 import { createRuntimeCodexCommandContext, formatRuntimeSelectionSummary, parseRuntimeMode, resolveRuntimeCodexCommand } from './runtime/index.js';
 import { buildRunMemoryPromptLines, selectRunMemoryForRole } from './run/runMemoryController.js';
 import { resolveProviderLinearChildLaneScopeContract } from './providerLinearChildLanePhaseContract.js';
@@ -22,6 +22,7 @@ const PROVIDER_LINEAR_CHILD_LANE_SCOPE_DRIFT_POLL_INTERVAL_MS = 250;
 const PROVIDER_LINEAR_CHILD_LANE_SESSION_LOG_DISCOVERY_WINDOW_MS = 10 * 60 * 1000;
 const PROVIDER_LINEAR_CHILD_LANE_SESSION_LOG_HEADER_BYTES = 256 * 1024;
 const PROVIDER_LINEAR_CHILD_LANE_SESSION_LOG_MTIME_SKEW_MS = 1000;
+const PROVIDER_LINEAR_CHILD_LANE_RUNNER_ENTRYPOINT = 'providerLinearChildLaneRunner';
 let tomlParser;
 const PROVIDER_LINEAR_CHILD_LANE_TRUSTED_PROJECT_CONFIG_LOCK_RETRY = {
     maxAttempts: 50,
@@ -1501,6 +1502,32 @@ function resolveProviderLinearChildLaneUnauthorizedCommitMessage(input) {
 async function writeChildLaneProof(runDir, proof) {
     await writeFile(join(runDir, PROVIDER_LINEAR_CHILD_LANE_PROOF_FILENAME), `${JSON.stringify(proof, null, 2)}\n`, 'utf8');
 }
+async function writeProviderLinearChildLaneDiagnostics(context, patch) {
+    const diagnosticsPath = join(context.runDir, PROVIDER_LINEAR_CHILD_LANE_DIAGNOSTICS_FILENAME);
+    try {
+        let existing = {};
+        try {
+            const parsed = JSON.parse(await readFile(diagnosticsPath, 'utf8'));
+            existing = isRecord(parsed) ? parsed : {};
+        }
+        catch {
+            existing = {};
+        }
+        await writeAtomicFile(diagnosticsPath, `${JSON.stringify({
+            ...existing,
+            issue_id: context.issueId,
+            issue_identifier: context.issueIdentifier,
+            task_id: context.taskId,
+            run_id: context.runId,
+            parent_run_id: context.parentRunId,
+            stream: context.stream,
+            ...patch
+        }, null, 2)}\n`, { ensureDir: true, encoding: 'utf8' });
+    }
+    catch (error) {
+        logger.warn(`[provider-linear-child-lane-diagnostics] failed to persist ${basename(diagnosticsPath)} at ${diagnosticsPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
 function buildFailedChildLaneProof(input) {
     return {
         issue_id: input.context.issueId,
@@ -1543,12 +1570,35 @@ export async function runProviderLinearChildLane(env = process.env, dependencyOv
         ...dependencyOverrides
     };
     const context = await loadProviderLinearChildLaneContext(env);
+    const runnerStartedAt = deps.now();
+    await writeProviderLinearChildLaneDiagnostics(context, {
+        provider_linear_child_lane_runner_entrypoint: PROVIDER_LINEAR_CHILD_LANE_RUNNER_ENTRYPOINT,
+        provider_linear_child_lane_runner_pid: process.pid,
+        provider_linear_child_lane_runner_started_at: runnerStartedAt,
+        provider_linear_child_lane_runtime_event: 'runner_started',
+        provider_linear_child_lane_runtime_event_at: runnerStartedAt
+    });
     const { laneWorkspacePath, laneBranch } = await prepareLaneWorkspace(context);
     const startingHeadSha = await readProviderLinearChildLaneHeadSha(laneWorkspacePath).catch(() => null);
     const startingReflogEntryCount = await countProviderLinearChildLaneReflogEntries(laneWorkspacePath).catch(() => 0);
     try {
         const runtimeContext = await resolveChildLaneRuntimeContext(env, laneWorkspacePath, context.runId);
         logger.info(`[provider-linear-child-lane-runtime] ${formatRuntimeSelectionSummary(runtimeContext.runtime)}`);
+        await writeProviderLinearChildLaneDiagnostics(context, {
+            provider_linear_child_lane_runtime_requested_mode: runtimeContext.runtime.requested_mode,
+            provider_linear_child_lane_runtime_selected_mode: runtimeContext.runtime.selected_mode,
+            provider_linear_child_lane_runtime_source: runtimeContext.runtime.source,
+            provider_linear_child_lane_runtime_provider: runtimeContext.runtime.provider,
+            provider_linear_child_lane_runtime_session_id: runtimeContext.runtime.runtime_session_id,
+            provider_linear_child_lane_runtime_fallback_occurred: runtimeContext.runtime.fallback.occurred,
+            provider_linear_child_lane_runtime_fallback_code: runtimeContext.runtime.fallback.code,
+            provider_linear_child_lane_runtime_fallback_reason: runtimeContext.runtime.fallback.reason,
+            provider_linear_child_lane_runtime_fallback_from_mode: runtimeContext.runtime.fallback.from_mode,
+            provider_linear_child_lane_runtime_fallback_to_mode: runtimeContext.runtime.fallback.to_mode,
+            provider_linear_child_lane_runtime_fallback_checked_at: runtimeContext.runtime.fallback.checked_at,
+            provider_linear_child_lane_runtime_event: 'runtime_selected',
+            provider_linear_child_lane_runtime_event_at: deps.now()
+        });
         const childEnv = { ...process.env, ...env, ...runtimeContext.env };
         childEnv.CODEX_NON_INTERACTIVE = '1';
         childEnv.CODEX_NO_INTERACTIVE = '1';
@@ -1594,6 +1644,14 @@ export async function runProviderLinearChildLane(env = process.env, dependencyOv
                 else {
                     if (startupRace.sessionLogPath) {
                         logger.info(`[provider-linear-child-lane-runtime] appserver startup observed via session log ${basename(startupRace.sessionLogPath)}`);
+                        const startupObservedAt = deps.now();
+                        await writeProviderLinearChildLaneDiagnostics(context, {
+                            provider_linear_child_lane_runtime_event: 'appserver_startup_observed',
+                            provider_linear_child_lane_runtime_event_at: startupObservedAt,
+                            provider_linear_child_lane_appserver_startup_observed: true,
+                            provider_linear_child_lane_appserver_startup_observed_at: startupObservedAt,
+                            provider_linear_child_lane_appserver_session_log: basename(startupRace.sessionLogPath)
+                        });
                     }
                     const execOrDriftRace = startupRace.sessionLogPath
                         ? await Promise.race([
@@ -1659,6 +1717,11 @@ export async function runProviderLinearChildLane(env = process.env, dependencyOv
         if (!execResult) {
             throw new Error('provider-linear-child-lane completed without an exec result');
         }
+        await writeProviderLinearChildLaneDiagnostics(context, {
+            provider_linear_child_lane_runtime_event: 'codex_exec_completed',
+            provider_linear_child_lane_runtime_event_at: deps.now(),
+            provider_linear_child_lane_exec_exit_code: execResult.exitCode
+        });
         const parsed = parseProviderLinearWorkerJsonl(execResult.stdout);
         const session = deriveLatestTurnSessionId({
             threadId: parsed.threadId,