@kbediako/codex-orchestrator 0.1.37 → 0.2.0

package/dist/orchestrator/src/cli/run/manifest.js

@@ -1,18 +1,26 @@
 import { randomBytes } from 'node:crypto';
 import { access, lstat, mkdir, readdir, readFile, realpath, symlink, writeFile } from 'node:fs/promises';
-import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import process from 'node:process';
 import { writeJsonAtomic } from '../utils/fs.js';
 import { slugify } from '../utils/strings.js';
 import { isoTimestamp } from '../utils/time.js';
 import { loadInstructionSet } from '../../../../packages/orchestrator/src/instructions/loader.js';
 import { resolveRunPaths, relativeToRepo } from './runPaths.js';
+import { materializeRunSource0, refreshRunMemoryObservability } from './source0.js';
+import { normalizeWorkspacePath } from './workspacePath.js';
 import { ExperienceStore } from '../../persistence/ExperienceStore.js';
 import { formatExperienceInjections } from '../exec/experience.js';
 import { sanitizeRunId } from '../../persistence/sanitizeRunId.js';
+import { PROVIDER_CONTROL_HOST_RUN_ID_ENV, PROVIDER_CONTROL_HOST_TASK_ID_ENV, PROVIDER_LAUNCH_SOURCE_CONTROL_HOST, PROVIDER_LAUNCH_SOURCE_ENV } from '../../../../scripts/lib/provider-run-contract.js';
 const HEARTBEAT_INTERVAL_SECONDS = 5;
 const HEARTBEAT_STALE_AFTER_SECONDS = 30;
 const MAX_ERROR_DETAIL_CHARS = 8 * 1024;
 const DEFAULT_MIN_EXPERIENCE_REWARD = 0.1;
+const KNOWN_NON_GUARDRAIL_PIPELINE_IDS = new Set([
+    'provider-linear-worker',
+    'provider-linear-child-lane'
+]);
 function createDefaultRuntimeFallback() {
     return {
         occurred: false,
@@ -26,6 +34,22 @@ function createDefaultRuntimeFallback() {
 function runtimeProviderForMode(mode) {
     return mode === 'appserver' ? 'AppServerRuntimeProvider' : 'CliRuntimeProvider';
 }
+function resolveProviderControlHostLocatorFromEnv(env = process.env) {
+    const launchSource = normalizeOptionalString(env[PROVIDER_LAUNCH_SOURCE_ENV]);
+    const taskId = normalizeOptionalString(env[PROVIDER_CONTROL_HOST_TASK_ID_ENV]);
+    const runId = normalizeOptionalString(env[PROVIDER_CONTROL_HOST_RUN_ID_ENV]);
+    if (launchSource !== PROVIDER_LAUNCH_SOURCE_CONTROL_HOST || !taskId || !runId) {
+        return { launchSource: null, taskId: null, runId: null };
+    }
+    return { launchSource, taskId, runId };
+}
+function normalizeOptionalString(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
 export async function bootstrapManifest(runId, options) {
     const { env, pipeline, parentRunId = null, taskSlug, approvalPolicy = null } = options;
     const paths = resolveRunPaths(env, runId);
@@ -35,6 +59,7 @@ export async function bootstrapManifest(runId, options) {
     const now = isoTimestamp();
     const resumeToken = randomBytes(32).toString('hex');
     const commands = buildCommandEntries(pipeline);
+    const providerControlHostLocator = resolveProviderControlHostLocatorFromEnv();
     const manifest = {
         version: 1,
         task_id: env.taskId,
@@ -56,6 +81,14 @@ export async function bootstrapManifest(runId, options) {
         artifact_root: relativeToRepo(env, paths.runDir),
         compat_path: relative(env.repoRoot, dirname(paths.compatManifestPath)),
         log_path: relativeToRepo(env, paths.logPath),
+        issue_provider: options.issueProvider ?? null,
+        issue_id: options.issueId ?? null,
+        issue_identifier: options.issueIdentifier ?? null,
+        issue_updated_at: options.issueUpdatedAt ?? null,
+        workspace_path: normalizeWorkspacePath(env.repoRoot),
+        provider_launch_source: providerControlHostLocator.launchSource,
+        provider_control_host_task_id: providerControlHostLocator.taskId,
+        provider_control_host_run_id: providerControlHostLocator.runId,
         summary: null,
         metrics_recorded: false,
         resume_token: resumeToken,
@@ -69,7 +102,8 @@ export async function bootstrapManifest(runId, options) {
         instructions_hash: null,
         instructions_sources: [],
         prompt_packs: [],
-        guardrails_required: pipeline.guardrailsRequired !== false,
+        guardrails_required: resolveGuardrailsRequiredForPipeline(pipeline),
+        guardrails_required_source: resolveGuardrailsRequiredSourceForPipeline(pipeline),
         runtime_mode_requested: 'appserver',
         runtime_mode: 'appserver',
         runtime_provider: runtimeProviderForMode('appserver'),
@@ -93,32 +127,72 @@ export async function bootstrapManifest(runId, options) {
         runsDir: env.runsRoot,
         maxSummaryWords: instructions.experienceMaxWords
     });
-    const experienceSnippets = await Promise.all(instructions.promptPacks.map(async (pack) => {
+    const promptPackSelections = await Promise.all(instructions.promptPacks.map(async (pack, index) => {
+        const policy = toExperienceSelectionPolicy(pack.retrievalPolicy, resolveExperienceMinReward());
         if (!pack.experienceSlots) {
-            return [];
+            return {
+                policy,
+                experiences: [],
+                selection: null,
+                diagnosticsPath: null
+            };
         }
-        const minReward = resolveExperienceMinReward();
-        const records = await experienceStore.fetchTop({
+        const selection = await experienceStore.selectTop({
             domain: pack.domain,
             limit: pack.experienceSlots,
-            minReward,
-            taskId: env.taskId
+            taskId: env.taskId,
+            policy
         });
-        return formatExperienceInjections(records, pack.experienceSlots);
+        const diagnosticsPath = await writePromptPackRetrievalDiagnostics({
+            env,
+            paths,
+            packDomain: pack.domain,
+            packId: pack.id,
+            packIndex: index,
+            diagnostics: selection.diagnostics
+        });
+        return {
+            policy,
+            experiences: formatExperienceInjections(selection.records, pack.experienceSlots, selection.diagnostics),
+            selection,
+            diagnosticsPath
+        };
     }));
     manifest.instructions_hash = instructions.hash || null;
     manifest.instructions_sources = instructions.sources.map((source) => source.path);
     manifest.prompt_packs = instructions.promptPacks.map((pack, index) => {
-        const experiences = experienceSnippets[index] ?? [];
+        const selectionArtifact = promptPackSelections[index];
+        const experiences = selectionArtifact?.experiences ?? [];
         return {
             id: pack.id,
             domain: pack.domain,
             stamp: pack.stamp,
             experience_slots: pack.experienceSlots,
             sources: pack.sources.map((source) => source.path),
+            retrieval_policy: serializePromptPackRetrievalPolicy(selectionArtifact?.policy),
+            ...(selectionArtifact?.selection
+                ? {
+                    retrieval_selection: serializePromptPackRetrievalSelection(selectionArtifact.selection.diagnostics, selectionArtifact.diagnosticsPath)
+                }
+                : {}),
             ...(experiences.length > 0 ? { experiences } : {})
         };
     });
+    let inheritedSource0 = null;
+    if (parentRunId) {
+        try {
+            inheritedSource0 = await loadManifest(env, parentRunId);
+        }
+        catch {
+            inheritedSource0 = null;
+        }
+    }
+    manifest.memory = await materializeRunSource0({
+        env,
+        paths,
+        manifest,
+        inheritedFrom: inheritedSource0
+    });
     await writeJsonAtomic(paths.manifestPath, manifest);
     await writeFile(paths.resumeTokenPath, `${resumeToken}\n`, 'utf8');
     await writeFile(paths.heartbeatPath, `${now}\n`, 'utf8');
@@ -126,6 +200,10 @@ export async function bootstrapManifest(runId, options) {
     return { manifest, paths };
 }
 export async function saveManifest(paths, manifest) {
+    const pipelineId = normalizeOptionalString(manifest.pipeline_id);
+    if (pipelineId === 'provider-linear-worker') {
+        backfillProviderControlHostLocatorFromEnv(manifest);
+    }
     manifest.updated_at = isoTimestamp();
     await writeJsonAtomic(paths.manifestPath, manifest);
 }
@@ -140,6 +218,30 @@ export async function loadManifest(env, runId) {
     const paths = resolveRunPathsForManifestPath(resolvedEnv, runId, manifestPath);
     return { manifest, paths };
 }
+export function backfillProviderControlHostLocatorFromEnv(manifest, env = process.env, options = {}) {
+    const locator = resolveProviderControlHostLocatorFromEnv(env);
+    if (!locator.launchSource || !locator.taskId || !locator.runId) {
+        return false;
+    }
+    const manifestLaunchSource = normalizeOptionalString(manifest.provider_launch_source);
+    const manifestTaskId = normalizeOptionalString(manifest.provider_control_host_task_id);
+    const manifestRunId = normalizeOptionalString(manifest.provider_control_host_run_id);
+    if (!options.overwriteConflicts &&
+        ((manifestLaunchSource && manifestLaunchSource !== locator.launchSource) ||
+            (manifestTaskId && manifestTaskId !== locator.taskId) ||
+            (manifestRunId && manifestRunId !== locator.runId))) {
+        return false;
+    }
+    if (manifestLaunchSource === locator.launchSource &&
+        manifestTaskId === locator.taskId &&
+        manifestRunId === locator.runId) {
+        return false;
+    }
+    manifest.provider_launch_source = locator.launchSource;
+    manifest.provider_control_host_task_id = locator.taskId;
+    manifest.provider_control_host_run_id = locator.runId;
+    return true;
+}
 export function updateCommandStatus(manifest, commandIndex, changes) {
     const entry = manifest.commands[commandIndex];
     if (!entry) {
@@ -197,6 +299,63 @@ function resolveExperienceMinReward(env = process.env) {
     }
     return Math.max(0, parsed);
 }
+function toExperienceSelectionPolicy(policy, fallbackMinScore) {
+    return {
+        kind: 'competitive_scoring_v1',
+        minScore: policy.minScore ?? fallbackMinScore,
+        scoreWeights: {
+            gtScore: policy.scoreWeights.gtScore,
+            relativeRank: policy.scoreWeights.relativeRank
+        },
+        antiDominanceNormalization: {
+            enabled: policy.antiDominanceNormalization.enabled,
+            strength: policy.antiDominanceNormalization.strength,
+            sourceGrouping: policy.antiDominanceNormalization.sourceGrouping
+        }
+    };
+}
+function serializePromptPackRetrievalPolicy(policy) {
+    if (!policy) {
+        return undefined;
+    }
+    return {
+        kind: policy.kind,
+        min_score: policy.minScore,
+        score_weights: {
+            gt_score: policy.scoreWeights.gtScore,
+            relative_rank: policy.scoreWeights.relativeRank
+        },
+        anti_dominance_normalization: {
+            enabled: policy.antiDominanceNormalization.enabled,
+            strength: policy.antiDominanceNormalization.strength,
+            source_grouping: policy.antiDominanceNormalization.sourceGrouping
+        }
+    };
+}
+function serializePromptPackRetrievalSelection(diagnostics, diagnosticsPath) {
+    return {
+        candidate_count: diagnostics.candidate_count,
+        selected_count: diagnostics.selected_count,
+        diagnostics_path: diagnosticsPath,
+        selected_ids: diagnostics.selected_ids,
+        suppressed_source_keys: diagnostics.suppressed_source_keys,
+        selected: diagnostics.selected.map((entry) => ({
+            id: entry.id,
+            source_key: entry.source_key,
+            source_kind: entry.source_kind,
+            raw_score: entry.raw_score,
+            competitive_score: entry.competitive_score,
+            dominance_penalty: entry.dominance_penalty
+        }))
+    };
+}
+async function writePromptPackRetrievalDiagnostics(params) {
+    const diagnosticsDir = join(params.paths.runDir, 'prompt-packs');
+    await mkdir(diagnosticsDir, { recursive: true });
+    const filePath = join(diagnosticsDir, `${slugify(`${params.packDomain}-${params.packId}`)}-${String(params.packIndex + 1).padStart(2, '0')}-retrieval.json`);
+    await writeJsonAtomic(filePath, params.diagnostics);
+    return relativeToRepo(params.env, filePath);
+}
 export function updateHeartbeat(manifest) {
     manifest.heartbeat_at = isoTimestamp();
     if (manifest.status === 'in_progress') {
@@ -215,7 +374,9 @@ export function resetForResume(manifest) {
     manifest.cloud_fallback = null;
 }
 export function recordResumeEvent(manifest, event) {
-    manifest.resume_events.push({ ...event, timestamp: isoTimestamp() });
+    const recordedAt = isoTimestamp();
+    manifest.resume_events.push({ ...event, timestamp: recordedAt });
+    refreshRunMemoryObservability(manifest, recordedAt);
 }
 export function ensureGuardrailStatus(manifest) {
     if (manifest.guardrail_status) {
@@ -228,19 +389,74 @@ export function ensureGuardrailStatus(manifest) {
 export function buildGuardrailSummary(manifest) {
     return ensureGuardrailStatus(manifest).summary;
 }
+export function resolveGuardrailsRequiredForPipeline(pipeline) {
+    if (typeof pipeline.guardrailsRequired === 'boolean') {
+        return pipeline.guardrailsRequired;
+    }
+    return pipeline.stages.some((stage) => isGuardrailPipelineStage(stage));
+}
+export function resolveGuardrailsRequiredSourceForPipeline(pipeline) {
+    return typeof pipeline.guardrailsRequired === 'boolean' ? 'explicit' : 'stage_detection';
+}
+export function resolveGuardrailsRequiredSourceForManifest(manifest) {
+    return normalizeGuardrailsRequiredSource(manifest.guardrails_required_source);
+}
+export function resolveGuardrailsRequiredForManifest(manifest) {
+    const guardrailCommands = selectGuardrailCommands(manifest);
+    if (typeof manifest.guardrails_required === 'boolean') {
+        const source = resolveGuardrailsRequiredSourceForManifest(manifest);
+        if (manifest.guardrails_required &&
+            guardrailCommands.length === 0 &&
+            isKnownNonGuardrailPipelineManifest(manifest) &&
+            source === 'stage_detection') {
+            return false;
+        }
+        return manifest.guardrails_required;
+    }
+    return guardrailCommands.length > 0;
+}
+export function stripNonApplicableGuardrailSummaryLines(manifest, summary) {
+    const normalized = summary?.trim();
+    if (!normalized) {
+        return null;
+    }
+    const lines = normalized.split('\n');
+    const guardrailCommands = selectGuardrailCommands(manifest);
+    if (guardrailCommands.length > 0) {
+        return normalized;
+    }
+    const source = resolveGuardrailsRequiredSourceForManifest(manifest);
+    const canStripLegacyMixedSummary = source === 'stage_detection' &&
+        isKnownNonGuardrailPipelineManifest(manifest) &&
+        lines.some((line) => !isGuardrailSummaryOrRecommendationLine(line));
+    if (resolveGuardrailsRequiredForManifest(manifest) && !canStripLegacyMixedSummary) {
+        return normalized;
+    }
+    const filtered = lines
+        .filter((line) => {
+        return !isGuardrailSummaryOrRecommendationLine(line);
+    })
+        .join('\n')
+        .trim();
+    return filtered || null;
+}
 export function upsertGuardrailSummary(manifest) {
-    const summary = buildGuardrailSummary(manifest);
+    const guardrailStatus = ensureGuardrailStatus(manifest);
     const existing = manifest.summary ? manifest.summary.split('\n') : [];
-    const filtered = existing.filter((line) => !line.toLowerCase().startsWith('guardrails:'));
-    filtered.push(summary);
-    manifest.summary = filtered.join('\n').trim();
-    if (manifest.summary.length === 0) {
-        manifest.summary = summary;
+    const filtered = existing.filter((line) => !line.toLowerCase().startsWith('guardrails:') && !isGuardrailRecommendationLine(line));
+    if (!shouldEmitGuardrailSummary(manifest, guardrailStatus)) {
+        manifest.summary = filtered.join('\n').trim() || null;
+        return;
     }
+    if (guardrailStatus.recommendation) {
+        filtered.push(guardrailStatus.recommendation);
+    }
+    filtered.push(guardrailStatus.summary);
+    manifest.summary = filtered.join('\n').trim() || guardrailStatus.summary;
 }
 function computeGuardrailStatus(manifest) {
     const guardrailCommands = selectGuardrailCommands(manifest);
-    const guardrailsRequired = manifest.guardrails_required ?? true;
+    const guardrailsRequired = resolveGuardrailsRequiredForManifest(manifest);
     const counts = {
         total: guardrailCommands.length,
         succeeded: 0,
@@ -275,7 +491,7 @@ function computeGuardrailStatus(manifest) {
         recommendation =
             'Guardrail command failed; re-run "codex-orchestrator start diagnostics --approval-policy never --format json --no-interactive" to gather failure artifacts.';
     }
-    const summary = formatGuardrailSummary(counts);
+    const summary = formatGuardrailSummary(counts, guardrailsRequired);
     return {
         present,
         recommendation,
@@ -284,14 +500,12 @@ function computeGuardrailStatus(manifest) {
         counts
     };
 }
+export function countGuardrailCommands(manifest) {
+    return selectGuardrailCommands(manifest).length;
+}
 function selectGuardrailCommands(manifest) {
-    return manifest.commands.filter((entry) => {
-        const id = entry.id?.toLowerCase() ?? '';
-        const title = entry.title?.toLowerCase() ?? '';
-        const command = entry.command?.toLowerCase() ?? '';
-        const haystack = `${id} ${title} ${command}`;
-        return haystack.includes('spec-guard') || haystack.includes('specguardrunner');
-    });
+    const commands = Array.isArray(manifest.commands) ? manifest.commands : [];
+    return commands.filter((entry) => isGuardrailCommandEntry(entry));
 }
 function classifyGuardrailCommand(entry) {
     if (entry.status === 'failed') {
@@ -314,9 +528,17 @@ function isExplicitGuardrailSkip(summary) {
         normalized.includes('spec-guard skipped') ||
         normalized.includes('spec guard skipped'));
 }
-function formatGuardrailSummary(counts) {
+function shouldEmitGuardrailSummary(manifest, snapshot) {
+    if (snapshot.counts.total > 0) {
+        return true;
+    }
+    return resolveGuardrailsRequiredForManifest(manifest);
+}
+function formatGuardrailSummary(counts, guardrailsRequired) {
     if (counts.total === 0) {
-        return 'Guardrails: spec-guard command not found.';
+        return guardrailsRequired
+            ? 'Guardrails: spec-guard command not found.'
+            : 'Guardrails: spec-guard not configured for this pipeline.';
     }
     if (counts.failed > 0) {
         return `Guardrails: spec-guard failed (${counts.failed}/${counts.total} failed).`;
@@ -339,6 +561,40 @@ function formatGuardrailSummary(counts) {
     }
     return `Guardrails: spec-guard partial (${parts.join(', ')} of ${counts.total}).`;
 }
+function isGuardrailRecommendationLine(line) {
+    const trimmed = line.trim();
+    return (trimmed.startsWith('Guardrail command missing;') ||
+        trimmed.startsWith('Guardrail command failed;'));
+}
+function isGuardrailSummaryOrRecommendationLine(line) {
+    const trimmed = line.trim();
+    return trimmed.toLowerCase().startsWith('guardrails:') || isGuardrailRecommendationLine(trimmed);
+}
+function normalizeGuardrailsRequiredSource(value) {
+    return value === 'explicit' || value === 'stage_detection' ? value : null;
+}
+function isKnownNonGuardrailPipelineManifest(manifest) {
+    return (typeof manifest.pipeline_id === 'string' &&
+        KNOWN_NON_GUARDRAIL_PIPELINE_IDS.has(manifest.pipeline_id.trim().toLowerCase()));
+}
+function isGuardrailPipelineStage(stage) {
+    const command = stage.kind === 'command' ? stage.command : stage.pipeline;
+    return containsGuardrailNeedle(stage.id, stage.title, command);
+}
+function isGuardrailCommandEntry(entry) {
+    if (!entry || typeof entry !== 'object') {
+        return false;
+    }
+    const record = entry;
+    return containsGuardrailNeedle(record.id, record.title, record.command);
+}
+function containsGuardrailNeedle(...values) {
+    const haystack = values
+        .filter((value) => typeof value === 'string')
+        .join(' ')
+        .toLowerCase();
+    return haystack.includes('spec-guard') || haystack.includes('specguardrunner');
+}
 export function appendSummary(manifest, message) {
     if (!message) {
         return;
@@ -352,6 +608,12 @@ export function appendSummary(manifest, message) {
     }
     manifest.summary = `${manifest.summary}\n${message}`;
 }
+export function removeStageFailureSummary(manifest, stageTitle) {
+    removeSummaryLines(manifest, (line) => line.trim().startsWith(`Stage '${stageTitle}' failed with exit code `) && line.trim().endsWith('.'));
+}
+export function removeSubpipelineFailureSummary(manifest, pipelineId) {
+    removeSummaryLines(manifest, (line) => line.trim() === `Sub-pipeline '${pipelineId}' failed.`);
+}
 export function finalizeStatus(manifest, status, detail) {
     manifest.status = status;
     manifest.status_detail = detail ?? null;
@@ -395,18 +657,20 @@ async function createCompatibilityPointer(env, paths) {
         });
     }
 }
-async function resolveManifestPathForRunId(env, runId) {
-    const expectedPaths = resolveRunPaths(env, runId);
-    try {
-        await access(expectedPaths.manifestPath);
-        return expectedPaths.manifestPath;
-    }
-    catch (error) {
-        if (error.code !== 'ENOENT') {
-            throw error;
-        }
+function removeSummaryLines(manifest, predicate) {
+    if (!manifest.summary) {
+        return;
     }
+    const retainedLines = manifest.summary.split('\n').filter((line) => !predicate(line));
+    manifest.summary = retainedLines.join('\n').trim() || null;
+}
+async function resolveManifestPathForRunId(env, runId) {
     const safeRunId = sanitizeRunId(runId);
+    const expectedPaths = resolveRunPaths(env, safeRunId);
+    const expectedManifestPath = await validateRunManifestCandidate(expectedPaths.manifestPath, env.runsRoot, safeRunId);
+    if (expectedManifestPath) {
+        return expectedManifestPath;
+    }
     const localCompatResolved = await resolveLocalCompatManifestPath(env, safeRunId);
     if (localCompatResolved) {
         return localCompatResolved;
@@ -439,30 +703,13 @@ async function resolveLocalCompatManifestPath(env, safeRunId) {
         throw error;
     }
     if (stats.isSymbolicLink()) {
-        try {
-            return await realpath(localCompatManifestPath);
-        }
-        catch (error) {
-            if (error.code === 'ENOENT') {
-                return null;
-            }
-            throw error;
-        }
+        return await validateRunManifestCandidate(localCompatManifestPath, env.runsRoot, safeRunId);
     }
     const redirectPath = await resolveRedirectManifestPath(env, localCompatManifestPath);
     if (!redirectPath) {
         return null;
     }
-    try {
-        await access(redirectPath);
-        return redirectPath;
-    }
-    catch (error) {
-        if (error.code === 'ENOENT') {
-            return null;
-        }
-        throw error;
-    }
+    return await validateRunManifestCandidate(redirectPath, env.runsRoot, safeRunId);
 }
 async function resolveRedirectManifestPath(env, localCompatManifestPath) {
     let raw;
@@ -525,28 +772,118 @@ async function findManifestPathAcrossTasks(runsRoot, safeRunId) {
         }
         const taskRoot = join(runsRoot, entry.name);
         const cliManifestPath = join(taskRoot, 'cli', safeRunId, 'manifest.json');
-        try {
-            await access(cliManifestPath);
-            return cliManifestPath;
-        }
-        catch (error) {
-            if (error.code !== 'ENOENT') {
-                throw error;
-            }
+        const validatedCliManifest = await validateRunManifestCandidate(cliManifestPath, runsRoot, safeRunId);
+        if (validatedCliManifest) {
+            return validatedCliManifest;
         }
         const legacyManifestPath = join(taskRoot, safeRunId, 'manifest.json');
-        try {
-            await access(legacyManifestPath);
-            return legacyManifestPath;
-        }
-        catch (error) {
-            if (error.code !== 'ENOENT') {
-                throw error;
-            }
+        const validatedLegacyManifest = await validateRunManifestCandidate(legacyManifestPath, runsRoot, safeRunId);
+        if (validatedLegacyManifest) {
+            return validatedLegacyManifest;
         }
     }
     return null;
 }
+async function validateRunManifestCandidate(candidatePath, runsRoot, safeRunId) {
+    try {
+        await access(candidatePath);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return null;
+        }
+        throw error;
+    }
+    const canonicalPath = await canonicalizePath(candidatePath);
+    const canonicalRunsRoot = await canonicalizePath(runsRoot);
+    if (!(await isPathWithinRoots(canonicalPath, [canonicalRunsRoot]))) {
+        return null;
+    }
+    try {
+        assertRunManifestPath(canonicalPath, canonicalRunsRoot, 'manifest_path');
+    }
+    catch {
+        return null;
+    }
+    const runDir = dirname(canonicalPath);
+    if (basename(runDir) !== safeRunId) {
+        return null;
+    }
+    return canonicalPath;
+}
+function assertRunManifestPath(pathname, runsRoot, label) {
+    try {
+        assertCliRunManifestPath(pathname, runsRoot, label);
+        return;
+    }
+    catch {
+        assertLegacyRunManifestPath(pathname, runsRoot, label);
+    }
+}
+function assertCliRunManifestPath(pathname, runsRoot, label) {
+    if (basename(pathname) !== 'manifest.json') {
+        throw new Error(`${label} invalid`);
+    }
+    const runDir = dirname(pathname);
+    const cliDir = dirname(runDir);
+    if (basename(cliDir) !== 'cli') {
+        throw new Error(`${label} invalid`);
+    }
+    const taskDir = dirname(cliDir);
+    const runsDir = dirname(taskDir);
+    const normalizedRunsDir = normalizePath(resolve(runsDir));
+    const normalizedRunsRoot = normalizePath(resolve(runsRoot));
+    if (!basename(runDir) || !basename(taskDir) || normalizedRunsDir !== normalizedRunsRoot) {
+        throw new Error(`${label} invalid`);
+    }
+}
+function assertLegacyRunManifestPath(pathname, runsRoot, label) {
+    if (basename(pathname) !== 'manifest.json') {
+        throw new Error(`${label} invalid`);
+    }
+    const runDir = dirname(pathname);
+    const taskDir = dirname(runDir);
+    const runsDir = dirname(taskDir);
+    const normalizedRunsDir = normalizePath(resolve(runsDir));
+    const normalizedRunsRoot = normalizePath(resolve(runsRoot));
+    if (!basename(runDir) ||
+        !basename(taskDir) ||
+        basename(taskDir) === 'local-mcp' ||
+        normalizedRunsDir !== normalizedRunsRoot) {
+        throw new Error(`${label} invalid`);
+    }
+}
+async function isPathWithinRoots(pathname, roots) {
+    const normalizedPath = normalizePath(await canonicalizePath(pathname));
+    for (const root of roots) {
+        const normalizedRoot = normalizePath(await canonicalizePath(root));
+        if (normalizedRoot === normalizedPath) {
+            return true;
+        }
+        const relativePath = relative(normalizedRoot, normalizedPath);
+        if (!relativePath) {
+            return true;
+        }
+        if (isAbsolute(relativePath)) {
+            continue;
+        }
+        if (!relativePath.startsWith(`..${sep}`) && relativePath !== '..') {
+            return true;
+        }
+    }
+    return false;
+}
+async function canonicalizePath(pathname) {
+    try {
+        return await realpath(pathname);
+    }
+    catch {
+        return resolve(pathname);
+    }
+}
+function normalizePath(pathname) {
+    return process.platform === 'win32' ? pathname.toLowerCase() : pathname;
+}
 function resolveRunPathsForManifestPath(env, runId, manifestPath) {
     const resolved = resolveRunPaths(env, runId);
     if (resolved.manifestPath === manifestPath) {