@shapeshift-labs/frontier-swarm-codex 0.1.1 → 0.3.0

package/dist/index.js

@@ -1,9 +1,17 @@
 import { spawn } from 'node:child_process';
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { FRONTIER_SWARM_DEFAULT_MODEL, FRONTIER_SWARM_DEFAULT_REASONING_EFFORT, checkSwarmOwnership, completeSwarmJob, createSwarmPlan, createSwarmProof, createSwarmRun, recordSwarmEvent } from '@shapeshift-labs/frontier-swarm';
+import { FRONTIER_SWARM_DEFAULT_MODEL, FRONTIER_SWARM_DEFAULT_REASONING_EFFORT, checkSwarmOwnership, completeSwarmJob, createSwarmMergeBundle, createSwarmEventStream, createSwarmLeases, createSwarmPlan, createSwarmProof, createSwarmRun, createSwarmSchedule, recordSwarmEvent, routeSwarmEventToMailboxes } from '@shapeshift-labs/frontier-swarm';
 export const FRONTIER_SWARM_CODEX_DEFAULT_MODEL = FRONTIER_SWARM_DEFAULT_MODEL;
 export const FRONTIER_SWARM_CODEX_DEFAULT_REASONING_EFFORT = FRONTIER_SWARM_DEFAULT_REASONING_EFFORT;
+export const FRONTIER_SWARM_CODEX_WORKSPACE_MANIFEST_KIND = 'frontier.swarm-codex.workspace-manifest';
+export const FRONTIER_SWARM_CODEX_WORKSPACE_MANIFEST_VERSION = 1;
+export const FRONTIER_SWARM_CODEX_WORKSPACE_PROOF_KIND = 'frontier.swarm-codex.workspace-proof';
+export const FRONTIER_SWARM_CODEX_WORKSPACE_PROOF_VERSION = 1;
+export const FRONTIER_SWARM_CODEX_PID_MANIFEST_KIND = 'frontier.swarm-codex.pid-manifest';
+export const FRONTIER_SWARM_CODEX_PID_MANIFEST_VERSION = 1;
+export const FRONTIER_SWARM_CODEX_COLLECTION_KIND = 'frontier.swarm-codex.collection';
+export const FRONTIER_SWARM_CODEX_COLLECTION_VERSION = 1;
 const DEFAULT_WORKSPACE_INCLUDES = ['AGENTS.md', 'package.json', 'package-lock.json', 'pnpm-lock.yaml', 'yarn.lock', 'config'];
 const DEFAULT_WORKSPACE_EXCLUDES = [
     '.git',
@@ -70,15 +78,24 @@ export function coerceCodexSwarmTasksInput(value) {
             lane: typeof task.lane === 'string' ? task.lane : undefined,
             layer: typeof task.layer === 'string' ? task.layer : undefined,
             compute: typeof task.compute === 'string' ? task.compute : undefined,
+            dependsOn: readStringArray(task.dependsOn),
+            concurrencyKey: typeof task.concurrencyKey === 'string' ? task.concurrencyKey : undefined,
+            budget: isObject(task.budget) ? task.budget : undefined,
+            review: isObject(task.review) ? task.review : undefined,
             priority: typeof task.priority === 'number' ? task.priority : undefined,
             sourceRefs: readStringArray(task.sourceRefs).concat(readStringArray(task.legacySourcePaths)),
             targetRefs: readStringArray(task.targetRefs).concat(readStringArray(task.ownedFiles), readStringArray(task.files)),
             allowedWrites: readStringArray(task.allowedWrites).concat(readStringArray(task.ownedFiles), readStringArray(task.files)),
+            ownershipRegions: Array.isArray(task.ownershipRegions) ? task.ownershipRegions : [],
+            ownedRegions: readStringArray(task.ownedRegions),
+            changedRegions: readStringArray(task.changedRegions),
             acceptance: readStringArray(task.acceptance),
             acceptanceChecks: Array.isArray(task.acceptanceChecks) ? task.acceptanceChecks : undefined,
             verification: Array.isArray(task.verification) ? task.verification : undefined,
             evidenceCommand: typeof task.evidenceCommand === 'string' ? task.evidenceCommand : undefined,
             shardCommand: typeof task.shardCommand === 'string' ? task.shardCommand : undefined,
+            capabilities: readStringArray(task.capabilities),
+            resourceRequirements: isObject(task.resourceRequirements) ? task.resourceRequirements : undefined,
             tags: readStringArray(task.tags),
             metadata: { source: task }
         };
@@ -88,26 +105,87 @@ export async function runCodexSwarm(plan, options) {
     const outDir = path.resolve(options.cwd ?? process.cwd(), options.outDir);
     await fs.mkdir(outDir, { recursive: true });
     await fs.writeFile(path.join(outDir, 'swarm-plan.json'), JSON.stringify(plan, null, 2) + '\n');
+    const eventStream = options.eventStream ?? createSwarmEventStream({
+        runId: plan.runId,
+        root: path.join(outDir, 'streams'),
+        lanes: Array.from(new Set(plan.jobs.map((job) => job.lane)))
+    });
+    await initFileSwarmEventStream(eventStream);
+    const pidManifestPath = path.resolve(options.cwd ?? process.cwd(), options.pidManifestPath ?? path.join(outDir, 'pids.json'));
+    await appendCodexPidManifest(pidManifestPath, { pid: process.pid, role: 'parent', runId: plan.runId, startedAt: Date.now() }, plan.runId);
     let run = createSwarmRun({ plan, status: 'running', startedAt: Date.now() });
-    run = recordSwarmEvent(run, { type: 'swarm.started', at: run.startedAt, data: { jobCount: plan.jobs.length } });
-    const results = await runJobPool(plan.jobs, Math.max(1, options.maxConcurrency ?? 1), (job) => runCodexJob(job, options, outDir));
+    const startedEvent = { type: 'swarm.started', runId: run.id, at: run.startedAt, data: { jobCount: plan.jobs.length } };
+    run = recordSwarmEvent(run, startedEvent);
+    await appendFileSwarmEvent(eventStream, startedEvent);
+    const runOptions = { ...options, eventStream, pidManifestPath };
+    const results = await runScheduledJobPool(plan, Math.max(1, options.maxConcurrency ?? 1), (job, lease) => runCodexJob(job, runOptions, outDir, lease));
+    for (const result of results) {
+        const job = plan.jobs.find((entry) => entry.id === result.jobId);
+        if (job) {
+            await options.onJobFinished?.({ job, result });
+            await appendFileSwarmEvent(eventStream, {
+                type: 'agent.finished',
+                runId: run.id,
+                jobId: job.id,
+                taskId: job.taskId,
+                lane: job.lane,
+                data: { status: result.status, mergeReadiness: result.mergeReadiness, changedPathCount: result.changedPaths?.length ?? 0 }
+            });
+        }
+    }
     for (const result of results)
         run = completeSwarmJob(run, result);
     const proof = createSwarmProof(run, { validation: plan.validation });
     const ok = run.summary.failedCount === 0 && run.summary.blockedCount === 0 && run.summary.ownershipViolationCount === 0;
+    await appendFileSwarmEvent(eventStream, {
+        type: 'swarm.finished',
+        runId: run.id,
+        data: { ok, summary: run.summary }
+    });
     await fs.writeFile(path.join(outDir, 'swarm-results.json'), JSON.stringify({ ok, outDir, run, proof }, null, 2) + '\n');
-    return { ok, outDir, plan, run, proof };
+    await writeSwarmCoordinatorSnapshot(options.coordinatorSnapshotPath ? path.resolve(options.cwd ?? process.cwd(), options.coordinatorSnapshotPath) : path.join(outDir, 'coordinator-dashboard.json'), {
+        ok,
+        outDir,
+        plan,
+        run,
+        proof,
+        eventStream,
+        pidManifestPath
+    });
+    const result = { ok, outDir, plan, run, proof };
+    await options.onSwarmFinished?.({ result });
+    return result;
 }
-export async function runCodexJob(job, options, outDir) {
-    const paths = await createJobPaths(outDir, job);
+export async function runCodexJob(job, options, outDir, lease) {
+    const paths = await createJobPaths(outDir, job, options);
     const workspace = await prepareCodexWorkspace(job, options);
     const workspacePlan = createCodexWorkspacePlan(job, options);
+    const hookInput = {
+        job,
+        cwd: options.cwd ?? process.cwd(),
+        outDir,
+        workspacePath: workspace,
+        workspacePlan,
+        paths
+    };
+    await options.prepareJobWorkspace?.(hookInput);
     const fileSnapshot = shouldSnapshotWorkspaceChanges(workspacePlan, options)
         ? await snapshotWorkspaceFiles(workspace)
         : undefined;
-    const prompt = renderCodexPrompt(job, { workspacePath: workspace, paths });
+    const basePrompt = renderCodexPrompt(job, { workspacePath: workspace, paths });
+    const prompt = options.renderJobPrompt
+        ? await options.renderJobPrompt({ ...hookInput, prompt: basePrompt })
+        : basePrompt;
     await fs.writeFile(paths.promptPath, prompt);
     const args = buildCodexArgs(job, { ...options, workspacePath: workspace, paths });
+    await options.onJobStarted?.({ ...hookInput, prompt, args });
+    await appendFileSwarmEvent(options.eventStream, {
+        type: 'agent.scheduled',
+        jobId: job.id,
+        taskId: job.taskId,
+        lane: job.lane,
+        data: { workspace: workspacePlan.path, capabilities: job.capabilities, resourceRequirements: job.resourceRequirements }
+    });
     const startedAt = Date.now();
     const execution = options.dryRun
         ? { exitCode: 0, changedPaths: [] }
@@ -121,12 +199,27 @@ export async function runCodexJob(job, options, outDir) {
             paths,
             timeoutMs: job.compute.timeoutMs ?? options.jobTimeoutMs ?? 7200000
         });
-    const changedPaths = execution.changedPaths ?? (options.collectGitStatus === false ? [] : await collectChangedPaths(workspace, fileSnapshot));
+    const collected = execution.changedPaths
+        ? filterWorkspaceChangedPaths(execution.changedPaths, workspacePlan)
+        : options.collectGitStatus === false
+            ? { changedPaths: [], ignoredChangedPaths: [] }
+            : await collectChangedPaths(workspace, fileSnapshot, workspacePlan);
+    const rawChangedPaths = collected.changedPaths;
+    const changedPaths = options.changedPathFilter ? [...options.changedPathFilter(rawChangedPaths, hookInput)] : rawChangedPaths;
+    const workspaceProof = await createSwarmWorkspaceProof(workspacePlan, { ignoredChangedPaths: collected.ignoredChangedPaths });
+    await fs.writeFile(paths.workspaceProofPath, JSON.stringify(workspaceProof, null, 2) + '\n');
     const ownership = checkSwarmOwnership(job, changedPaths);
     const verification = options.runVerification ? await runVerification(job.verification, workspace) : [];
     const failedVerification = verification.some((entry) => entry.required !== false && entry.status !== 0);
     const status = ownership.ok && execution.exitCode === 0 && !failedVerification ? 'completed' : 'failed';
-    return {
+    const patchPath = await writeCodexPatchFile({
+        workspace,
+        sourceRoot: path.resolve(options.cwd ?? process.cwd()),
+        paths,
+        workspacePlan,
+        changedPaths
+    });
+    const result = {
         jobId: job.id,
         status,
         startedAt,
@@ -134,18 +227,31 @@ export async function runCodexJob(job, options, outDir) {
         exitCode: execution.exitCode,
         signal: execution.signal,
         changedPaths,
+        changedRegions: job.changedRegions,
         ownershipViolations: ownership.violations,
-        evidencePaths: [paths.evidenceDir],
+        evidencePaths: [paths.evidenceDir, paths.workspaceProofPath, paths.mergeBundlePath, ...(patchPath ? [patchPath] : [])],
+        ...(patchPath ? { patchPath } : {}),
+        queueItemIds: [job.taskId],
         verification,
         lastMessage: execution.lastMessage,
-        error: execution.error
+        error: execution.error,
+        metadata: lease ? { leaseId: lease.id, leaseToken: lease.token, fencingToken: lease.fencingToken } : undefined
     };
+    const mergeBundle = createSwarmMergeBundle({
+        runId: options.eventStream?.runId,
+        job,
+        result,
+        ...(patchPath ? { patchPath } : {}),
+        evidencePaths: [paths.evidenceDir, paths.workspaceProofPath],
+        queueItemIds: [job.taskId]
+    });
+    await fs.writeFile(paths.mergeBundlePath, JSON.stringify(mergeBundle, null, 2) + '\n');
+    return result;
 }
 export function buildCodexArgs(job, input) {
-    const model = job.compute.model ?? input.model ?? FRONTIER_SWARM_CODEX_DEFAULT_MODEL;
-    const effort = job.compute.reasoningEffort ?? input.reasoningEffort ?? FRONTIER_SWARM_CODEX_DEFAULT_REASONING_EFFORT;
+    const model = resolveCodexModelFlag(job, input);
+    const effort = resolveCodexReasoningEffort(job, input);
     const sandbox = job.compute.sandbox ?? input.sandbox ?? 'workspace-write';
-    const approval = job.compute.approval ?? input.approval ?? 'never';
     const args = [
         'exec',
         '--cd',
@@ -154,16 +260,17 @@ export function buildCodexArgs(job, input) {
         path.resolve(input.cwd ?? process.cwd(), input.outDir),
         '--sandbox',
         sandbox,
-        '--ask-for-approval',
-        approval,
         '--json',
         '--output-last-message',
-        input.paths.lastMessagePath,
-        '--model',
-        model,
-        '-c',
-        `model_reasoning_effort="${effort}"`
+        input.paths.lastMessagePath
     ];
+    if (model)
+        args.push('--model', model);
+    if (effort)
+        args.push('-c', `model_reasoning_effort="${effort}"`);
+    const approval = normalizeCodexApprovalPolicy(input.approval);
+    if (approval)
+        args.push('--ask-for-approval', approval);
     if (shouldSkipGitRepoCheck(input))
         args.push('--skip-git-repo-check');
     for (const dir of input.addDirs ?? [])
@@ -176,6 +283,56 @@ export function buildCodexArgs(job, input) {
     args.push('-');
     return args;
 }
+export function normalizeCodexModelFlag(model) {
+    if (model === false || model == null)
+        return undefined;
+    const value = String(model).trim();
+    if (!value)
+        return undefined;
+    const normalized = value.toLowerCase();
+    if (normalized === 'auto' || normalized === 'default' || normalized === 'config' || normalized === 'config-default') {
+        return undefined;
+    }
+    return value;
+}
+export function normalizeCodexApprovalPolicy(approval) {
+    if (approval === false || approval == null)
+        return undefined;
+    const value = String(approval).trim().toLowerCase().replaceAll('_', '-');
+    if (!value || value === 'default' || value === 'config-default')
+        return undefined;
+    if (value === 'never' || value === 'none' || value === 'off' || value === 'false' || value === 'full-auto')
+        return 'never';
+    if (value === 'untrusted')
+        return 'untrusted';
+    if (value === 'on-failure')
+        return 'on-failure';
+    if (value === 'on-request' || value === 'request' || value === 'manual')
+        return 'on-request';
+    throw new Error(`unsupported Codex approval policy "${approval}"; expected untrusted, on-request, on-failure, never, full-auto, none, or default`);
+}
+function resolveCodexModelFlag(job, input) {
+    const explicit = normalizeCodexModelFlag(input.model);
+    if (explicit || input.model === false)
+        return explicit;
+    const policy = input.modelPolicy ?? (input.forwardPlanModel ? 'plan' : 'config-default');
+    if (policy === 'plan')
+        return normalizeCodexModelFlag(job.compute.model ?? FRONTIER_SWARM_CODEX_DEFAULT_MODEL);
+    return undefined;
+}
+function resolveCodexReasoningEffort(job, input) {
+    if (input.reasoningEffort === false)
+        return undefined;
+    if (typeof input.reasoningEffort === 'string') {
+        const explicit = input.reasoningEffort.trim();
+        return explicit && explicit !== 'default' && explicit !== 'config-default' ? explicit : undefined;
+    }
+    const policy = input.modelPolicy ?? (input.forwardPlanModel || input.forwardPlanReasoningEffort ? 'plan' : 'config-default');
+    if (policy !== 'plan')
+        return undefined;
+    const effort = job.compute.reasoningEffort ?? FRONTIER_SWARM_CODEX_DEFAULT_REASONING_EFFORT;
+    return effort ? String(effort).trim() : undefined;
+}
 export function renderCodexPrompt(job, input) {
     return [
         '# Frontier Swarm Codex Job',
@@ -202,6 +359,12 @@ export function renderCodexPrompt(job, input) {
         '',
         job.task.objective,
         '',
+        'Dependencies:',
+        ...bullets(job.dependsOn),
+        '',
+        'Budget:',
+        ...bullets(formatBudget(job)),
+        '',
         'Source refs:',
         ...bullets(job.task.sourceRefs),
         '',
@@ -229,6 +392,15 @@ export async function spawnCodexExecutor(input) {
     await fs.writeFile(input.paths.stderrPath, '');
     return new Promise((resolve) => {
         const child = spawn(input.codexPath, input.args, { cwd: input.cwd, stdio: ['pipe', 'pipe', 'pipe'] });
+        if (child.pid) {
+            appendCodexPidManifest(input.paths.pidManifestPath, {
+                pid: child.pid,
+                role: 'codex',
+                jobId: input.job.id,
+                startedAt: Date.now(),
+                command: [input.codexPath, ...input.args]
+            }).catch(() => { });
+        }
         const timer = setTimeout(() => child.kill('SIGTERM'), input.timeoutMs);
         child.stdout.on('data', (chunk) => fs.appendFile(input.paths.eventsPath, chunk).catch(() => { }));
         child.stderr.on('data', (chunk) => fs.appendFile(input.paths.stderrPath, chunk).catch(() => { }));
@@ -247,7 +419,7 @@ export async function spawnCodexExecutor(input) {
         });
     });
 }
-async function createJobPaths(outDir, job) {
+async function createJobPaths(outDir, job, options) {
     const jobDir = path.join(outDir, job.id);
     const paths = {
         jobDir,
@@ -255,7 +427,11 @@ async function createJobPaths(outDir, job) {
         eventsPath: path.join(jobDir, 'codex-events.jsonl'),
         stderrPath: path.join(jobDir, 'codex-stderr.log'),
         lastMessagePath: path.join(jobDir, 'last-message.md'),
-        evidenceDir: path.join(jobDir, 'evidence')
+        evidenceDir: path.join(jobDir, 'evidence'),
+        workspaceProofPath: path.join(jobDir, 'evidence', 'workspace-proof.json'),
+        patchPath: path.join(jobDir, 'evidence', 'changes.patch'),
+        mergeBundlePath: path.join(jobDir, 'evidence', 'merge.json'),
+        pidManifestPath: path.resolve(options.cwd ?? process.cwd(), options.pidManifestPath ?? path.join(outDir, 'pids.json'))
     };
     await fs.mkdir(paths.evidenceDir, { recursive: true });
     return paths;
@@ -277,6 +453,7 @@ export async function prepareCodexWorkspace(job, options) {
     if (await pathExists(plan.path)) {
         if (!plan.replace)
             return plan.path;
+        assertGeneratedWorkspacePath(plan);
         await fs.rm(plan.path, { recursive: true, force: true });
     }
     await fs.mkdir(plan.path, { recursive: true });
@@ -306,6 +483,10 @@ export function createCodexWorkspacePlan(job, options) {
             excludes: [],
             artifactIncludes: [],
             linkPaths: [],
+            requiredIncludes: [],
+            optionalIncludes: [],
+            strategy: workspace.strategy ?? 'fs-cp',
+            ...(workspace.guardRoot ? { guardRoot: path.resolve(cwd, workspace.guardRoot) } : {}),
             linkNodeModules: false,
             replace: false,
             skipGitRepoCheck: workspace.skipGitRepoCheck ?? false
@@ -333,6 +514,16 @@ export function createCodexWorkspacePlan(job, options) {
         ...readStringArray(rawTask.snapshotLinkPaths),
         ...readStringArray(rawTask.linkPaths)
     ]);
+    const requiredIncludes = uniqueWorkspacePaths([
+        ...readStringArray(workspace.requiredIncludes),
+        ...readStringArray(rawTask.requiredIncludes),
+        ...readStringArray(rawTask.snapshotRequiredIncludes)
+    ]);
+    const optionalIncludes = uniqueWorkspacePaths([
+        ...readStringArray(workspace.optionalIncludes),
+        ...readStringArray(rawTask.optionalIncludes),
+        ...readStringArray(rawTask.snapshotOptionalIncludes)
+    ]);
     return {
         mode,
         root,
@@ -341,11 +532,231 @@ export function createCodexWorkspacePlan(job, options) {
         excludes,
         artifactIncludes,
         linkPaths,
+        requiredIncludes,
+        optionalIncludes,
+        strategy: workspace.strategy ?? 'fs-cp',
+        guardRoot: path.resolve(cwd, workspace.guardRoot ?? workspace.root ?? path.join('agent-worktrees', 'frontier-swarm-codex')),
         linkNodeModules: workspace.linkNodeModules ?? (mode !== 'git-worktree'),
         replace: workspace.replace ?? false,
         skipGitRepoCheck: workspace.skipGitRepoCheck ?? (mode === 'copy' || mode === 'snapshot')
     };
 }
+export function createSwarmWorkspaceManifest(plan) {
+    return {
+        kind: FRONTIER_SWARM_CODEX_WORKSPACE_MANIFEST_KIND,
+        version: FRONTIER_SWARM_CODEX_WORKSPACE_MANIFEST_VERSION,
+        id: 'codex-workspace:' + stableHash([plan.mode, plan.root, plan.path, plan.includes, plan.linkPaths]),
+        mode: plan.mode,
+        root: plan.root,
+        path: plan.path,
+        includes: [...plan.includes],
+        excludes: [...plan.excludes],
+        artifactIncludes: [...plan.artifactIncludes],
+        linkPaths: [...plan.linkPaths],
+        requiredIncludes: [...plan.requiredIncludes],
+        optionalIncludes: [...plan.optionalIncludes],
+        strategy: plan.strategy,
+        ...(plan.guardRoot ? { guardRoot: plan.guardRoot } : {}),
+        linkNodeModules: plan.linkNodeModules,
+        skipGitRepoCheck: plan.skipGitRepoCheck
+    };
+}
+export async function createSwarmWorkspaceProof(plan, input = {}) {
+    const generatedAt = input.generatedAt ?? Date.now();
+    const manifest = createSwarmWorkspaceManifest(plan);
+    const copiedCandidates = uniqueWorkspacePaths([...plan.includes, ...plan.artifactIncludes, ...plan.requiredIncludes]);
+    const optionalCandidates = uniqueWorkspacePaths(plan.optionalIncludes);
+    const copiedPaths = [];
+    const missingRequired = [];
+    const missingOptional = [];
+    for (const include of copiedCandidates) {
+        if (await pathExists(path.join(plan.path, include)))
+            copiedPaths.push(include);
+        else if (plan.requiredIncludes.includes(include))
+            missingRequired.push(include);
+    }
+    for (const include of optionalCandidates) {
+        if (await pathExists(path.join(plan.path, include)))
+            copiedPaths.push(include);
+        else
+            missingOptional.push(include);
+    }
+    const linkedPaths = [];
+    for (const linkPath of uniqueWorkspacePaths([...plan.linkPaths, ...(plan.linkNodeModules ? ['node_modules'] : [])])) {
+        const stat = await fs.lstat(path.join(plan.path, linkPath)).catch(() => undefined);
+        if (stat?.isSymbolicLink())
+            linkedPaths.push(linkPath);
+    }
+    const ignoredChangedPaths = uniqueWorkspacePaths(input.ignoredChangedPaths ?? []);
+    return {
+        kind: FRONTIER_SWARM_CODEX_WORKSPACE_PROOF_KIND,
+        version: FRONTIER_SWARM_CODEX_WORKSPACE_PROOF_VERSION,
+        id: 'codex-workspace-proof:' + stableHash([manifest.id, copiedPaths, linkedPaths, missingRequired, missingOptional, generatedAt]),
+        generatedAt,
+        manifest,
+        copiedPaths: uniqueWorkspacePaths(copiedPaths),
+        linkedPaths,
+        missingRequired,
+        missingOptional,
+        ignoredChangedPaths,
+        summary: {
+            copiedCount: uniqueWorkspacePaths(copiedPaths).length,
+            linkedCount: linkedPaths.length,
+            missingRequiredCount: missingRequired.length,
+            missingOptionalCount: missingOptional.length,
+            ignoredChangedPathCount: ignoredChangedPaths.length
+        }
+    };
+}
+export async function initFileSwarmEventStream(stream) {
+    if (!stream)
+        return;
+    const mailboxes = [stream.global, ...Object.values(stream.lanes)];
+    await Promise.all(mailboxes.map(async (mailbox) => {
+        if (!mailbox.path)
+            return;
+        await fs.mkdir(path.dirname(mailbox.path), { recursive: true });
+        await fs.writeFile(mailbox.path, '');
+    }));
+}
+export async function appendFileSwarmEvent(stream, event) {
+    if (!stream)
+        return;
+    const line = JSON.stringify({ at: Date.now(), ...event }) + '\n';
+    const paths = routeSwarmEventToMailboxes(stream, event)
+        .map((mailbox) => mailbox.path)
+        .filter((mailboxPath) => !!mailboxPath);
+    await Promise.all(paths.map(async (mailboxPath) => {
+        await fs.mkdir(path.dirname(mailboxPath), { recursive: true });
+        await fs.appendFile(mailboxPath, line);
+    }));
+}
+export async function writeSwarmCoordinatorSnapshot(file, input) {
+    const byLane = input.run.jobs.reduce((acc, job) => {
+        const current = acc[job.lane] ?? { total: 0, completed: 0, failed: 0, blocked: 0 };
+        current.total += 1;
+        const result = input.run.results.find((entry) => entry.jobId === job.id);
+        if (result?.status === 'completed' || result?.status === 'verified')
+            current.completed += 1;
+        else if (result?.status === 'failed')
+            current.failed += 1;
+        else if (result?.status === 'blocked')
+            current.blocked += 1;
+        acc[job.lane] = current;
+        return acc;
+    }, {});
+    const mergeReadiness = input.run.results.reduce((acc, result) => {
+        acc[result.mergeReadiness] = (acc[result.mergeReadiness] ?? 0) + 1;
+        return acc;
+    }, {});
+    const dashboard = {
+        kind: 'frontier.swarm-codex.coordinator-dashboard',
+        version: 1,
+        generatedAt: new Date().toISOString(),
+        ok: input.ok,
+        outDir: input.outDir,
+        runId: input.run.id,
+        planId: input.plan.id,
+        summary: input.run.summary,
+        byLane,
+        mergeReadiness,
+        eventStream: input.eventStream ?? null,
+        pidManifestPath: input.pidManifestPath ?? null,
+        proof: input.proof
+    };
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file, JSON.stringify(dashboard, null, 2) + '\n');
+}
+export async function appendCodexPidManifest(file, entry, runId) {
+    const manifest = await readCodexPidManifest(file).catch(() => ({
+        kind: FRONTIER_SWARM_CODEX_PID_MANIFEST_KIND,
+        version: FRONTIER_SWARM_CODEX_PID_MANIFEST_VERSION,
+        ...(runId ? { runId } : {}),
+        entries: []
+    }));
+    const entries = manifest.entries.filter((existing) => existing.pid !== entry.pid || existing.jobId !== entry.jobId);
+    entries.push(entry);
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file, JSON.stringify({ ...manifest, ...(runId ? { runId } : {}), entries }, null, 2) + '\n');
+}
+export async function readCodexPidManifest(file) {
+    return JSON.parse(await fs.readFile(file, 'utf8'));
+}
+export async function stopCodexSwarmRun(input) {
+    const signal = input.signal ?? 'SIGTERM';
+    const pidManifestPath = await resolvePidManifestPath(input.run);
+    const manifest = await readCodexPidManifest(pidManifestPath);
+    const stopped = [];
+    const missing = [];
+    const errors = [];
+    for (const entry of manifest.entries.filter((item) => item.pid !== process.pid).sort((left, right) => right.startedAt - left.startedAt)) {
+        try {
+            process.kill(entry.pid, signal);
+            stopped.push(entry.pid);
+        }
+        catch (error) {
+            const code = typeof error === 'object' && error && 'code' in error ? String(error.code) : '';
+            if (code === 'ESRCH')
+                missing.push(entry.pid);
+            else
+                errors.push({ pid: entry.pid, error: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    return { ok: errors.length === 0, pidManifestPath, signal, stopped, missing, errors };
+}
+export async function collectCodexSwarmRun(input) {
+    const generatedAt = Date.now();
+    const cwd = path.resolve(input.cwd ?? process.cwd());
+    const runDir = await resolveRunDirectory(input.run);
+    const outDir = path.resolve(cwd, input.outDir ?? path.join(runDir, 'collected'));
+    const buckets = {
+        'ready-to-apply': [],
+        'needs-human-port': [],
+        'failed-evidence': [],
+        'stale-against-head': []
+    };
+    const mergePaths = await findFilesByName(runDir, 'merge.json');
+    for (const mergePath of mergePaths.sort()) {
+        const bundle = JSON.parse(await fs.readFile(mergePath, 'utf8'));
+        const staleAgainstHead = input.checkStale === false ? false : await bundlePatchIsStale(bundle, mergePath, cwd);
+        const bucket = classifyCodexCollectBucket(bundle, staleAgainstHead);
+        const branchName = input.branchPrefix ? `${input.branchPrefix}/${slug(bundle.jobId)}` : bundle.branchName;
+        const nextBundle = {
+            ...bundle,
+            ...(branchName ? { branchName } : {}),
+            staleAgainstHead: bundle.staleAgainstHead || staleAgainstHead,
+            disposition: staleAgainstHead ? 'stale-against-head' : bundle.disposition,
+            autoMergeable: bucket === 'ready-to-apply' && bundle.autoMergeable
+        };
+        const outputDir = path.join(outDir, bucket, slug(bundle.jobId));
+        await fs.mkdir(outputDir, { recursive: true });
+        await fs.writeFile(path.join(outputDir, 'merge.json'), JSON.stringify(nextBundle, null, 2) + '\n');
+        const patchPath = resolveBundlePatchPath(nextBundle, mergePath);
+        if (patchPath && await pathExists(patchPath))
+            await fs.copyFile(patchPath, path.join(outputDir, 'changes.patch')).catch(() => { });
+        buckets[bucket].push({ bucket, jobId: bundle.jobId, mergePath, outputDir, bundle: nextBundle });
+    }
+    const summary = {
+        total: mergePaths.length,
+        'ready-to-apply': buckets['ready-to-apply'].length,
+        'needs-human-port': buckets['needs-human-port'].length,
+        'failed-evidence': buckets['failed-evidence'].length,
+        'stale-against-head': buckets['stale-against-head'].length
+    };
+    const result = {
+        kind: FRONTIER_SWARM_CODEX_COLLECTION_KIND,
+        version: FRONTIER_SWARM_CODEX_COLLECTION_VERSION,
+        ok: summary['failed-evidence'] === 0 && summary['stale-against-head'] === 0,
+        runDir,
+        outDir,
+        generatedAt,
+        buckets,
+        summary
+    };
+    await fs.mkdir(outDir, { recursive: true });
+    await fs.writeFile(path.join(outDir, 'collection.json'), JSON.stringify(result, null, 2) + '\n');
+    return result;
+}
 async function copyWorkspacePath(cwd, workspacePath, include, excludes) {
     const relative = normalizeWorkspacePath(include);
     if (!relative)
@@ -384,6 +795,12 @@ function shouldSkipGitRepoCheck(input) {
         return workspace.skipGitRepoCheck;
     return workspace.mode === 'copy' || workspace.mode === 'snapshot';
 }
+function assertGeneratedWorkspacePath(plan) {
+    const relative = path.relative(plan.guardRoot ?? plan.root, plan.path);
+    if (relative.startsWith('..') || path.isAbsolute(relative) || relative === '') {
+        throw new Error(`Refusing to replace workspace outside generated root: ${plan.path}`);
+    }
+}
 function readRawTask(job) {
     const metadata = isObject(job.task.metadata) ? job.task.metadata : {};
     return isObject(metadata.source) ? metadata.source : {};
@@ -418,12 +835,71 @@ async function gitChangedPaths(cwd) {
         return value.includes(' -> ') ? value.split(' -> ') : [value];
     });
 }
-async function collectChangedPaths(cwd, baseline) {
-    const gitPaths = await gitChangedPaths(cwd);
-    if (gitPaths.length > 0 || !baseline)
-        return gitPaths;
+async function collectChangedPaths(cwd, baseline, plan) {
+    if (!baseline)
+        return filterWorkspaceChangedPaths(await gitChangedPaths(cwd), plan);
     const after = await snapshotWorkspaceFiles(cwd);
-    return diffWorkspaceFiles(baseline, after);
+    return filterWorkspaceChangedPaths(diffWorkspaceFiles(baseline, after), plan);
+}
+async function writeCodexPatchFile(input) {
+    await fs.mkdir(path.dirname(input.paths.patchPath), { recursive: true });
+    const changedPaths = uniqueWorkspacePaths(input.changedPaths);
+    if (changedPaths.length === 0) {
+        await fs.writeFile(input.paths.patchPath, '');
+        return undefined;
+    }
+    const diff = input.workspacePlan.mode === 'current' || input.workspacePlan.mode === 'git-worktree'
+        ? await gitDiffPatch(input.workspace, changedPaths)
+        : await noIndexWorkspacePatch(input.sourceRoot, input.workspace, changedPaths);
+    await fs.writeFile(input.paths.patchPath, diff);
+    return diff.trim().length ? input.paths.patchPath : undefined;
+}
+async function gitDiffPatch(workspace, changedPaths) {
+    const result = await runProcess('git', ['diff', '--', ...changedPaths], { cwd: workspace, allowFailure: true });
+    return result.stdout;
+}
+async function noIndexWorkspacePatch(sourceRoot, workspace, changedPaths) {
+    const chunks = [];
+    for (const file of changedPaths) {
+        const source = path.join(sourceRoot, file);
+        const target = path.join(workspace, file);
+        const sourceExists = await pathExists(source);
+        const targetExists = await pathExists(target);
+        if (!sourceExists && !targetExists)
+            continue;
+        const left = sourceExists ? source : '/dev/null';
+        const right = targetExists ? target : '/dev/null';
+        const result = await runProcess('git', ['diff', '--no-index', '--', left, right], { cwd: sourceRoot, allowFailure: true });
+        if (result.stdout.trim())
+            chunks.push(result.stdout);
+    }
+    return chunks.join('\n');
+}
+function filterWorkspaceChangedPaths(paths, plan) {
+    const changedPaths = [];
+    const ignoredChangedPaths = [];
+    for (const file of uniqueWorkspacePaths(paths)) {
+        if (isIgnoredWorkspaceChangedPath(file, plan))
+            ignoredChangedPaths.push(file);
+        else
+            changedPaths.push(file);
+    }
+    return { changedPaths, ignoredChangedPaths };
+}
+function isIgnoredWorkspaceChangedPath(file, plan) {
+    if (plan.mode !== 'copy' && plan.mode !== 'snapshot')
+        return false;
+    const ignored = [
+        ...plan.excludes,
+        ...plan.artifactIncludes,
+        ...plan.linkPaths,
+        ...(plan.linkNodeModules ? ['node_modules'] : []),
+        'agent-runs',
+        '.frontier-framework',
+        'dist',
+        'coverage'
+    ];
+    return ignored.some((entry) => file === entry || file.startsWith(entry.replace(/\/$/, '') + '/'));
 }
 async function snapshotWorkspaceFiles(root) {
     const snapshot = new Map();
@@ -488,6 +964,58 @@ async function runVerification(commands, cwd) {
     }
     return results;
 }
+async function runScheduledJobPool(plan, concurrency, worker) {
+    const results = [];
+    const active = new Map();
+    const leases = [];
+    const completed = new Set();
+    const resultByJob = new Map();
+    while (resultByJob.size < plan.jobs.length) {
+        const run = createSwarmRun({ plan, status: 'running', results });
+        run.jobs = run.jobs.map((job) => active.has(job.id) ? { ...job, status: 'running' } : job);
+        const schedule = createSwarmSchedule({
+            plan,
+            run,
+            maxReadyJobs: Math.max(0, concurrency - active.size)
+        });
+        const nextLeases = createSwarmLeases({
+            schedule,
+            workerId: 'frontier-swarm-codex',
+            count: Math.max(0, concurrency - active.size),
+            existingLeases: leases
+        });
+        for (const lease of nextLeases) {
+            const job = plan.jobs.find((entry) => entry.id === lease.jobId);
+            if (!job || active.has(job.id) || completed.has(job.id))
+                continue;
+            leases.push(lease);
+            active.set(job.id, worker(job, lease));
+        }
+        if (active.size === 0) {
+            for (const blocked of schedule.blocked) {
+                if (resultByJob.has(blocked.jobId))
+                    continue;
+                const result = {
+                    jobId: blocked.jobId,
+                    status: 'blocked',
+                    startedAt: Date.now(),
+                    finishedAt: Date.now(),
+                    error: blocked.reasons.join(', '),
+                    metadata: { waitingFor: blocked.waitingFor, reasons: blocked.reasons }
+                };
+                results.push(result);
+                resultByJob.set(result.jobId, result);
+            }
+            break;
+        }
+        const settled = await Promise.race(Array.from(active.entries()).map(async ([jobId, promise]) => ({ jobId, result: await promise })));
+        active.delete(settled.jobId);
+        completed.add(settled.jobId);
+        results.push(settled.result);
+        resultByJob.set(settled.jobId, settled.result);
+    }
+    return plan.jobs.map((job) => resultByJob.get(job.id)).filter((result) => !!result);
+}
 async function runJobPool(jobs, concurrency, worker) {
     const results = [];
     const pending = jobs.map((job, index) => ({ job, index }));
@@ -536,6 +1064,17 @@ function formatCommand(command) {
 function bullets(values) {
     return values.length ? values.map((value) => `- ${value}`) : ['- none'];
 }
+function formatBudget(job) {
+    if (!job.budget)
+        return ['none'];
+    return [
+        job.budget.maxCostUsd === undefined ? undefined : `maxCostUsd=${job.budget.maxCostUsd}`,
+        job.budget.maxInputTokens === undefined ? undefined : `maxInputTokens=${job.budget.maxInputTokens}`,
+        job.budget.maxOutputTokens === undefined ? undefined : `maxOutputTokens=${job.budget.maxOutputTokens}`,
+        job.budget.maxDurationMs === undefined ? undefined : `maxDurationMs=${job.budget.maxDurationMs}`,
+        `maxRetries=${job.budget.maxRetries}`
+    ].filter((value) => !!value);
+}
 function arrayOfObjects(value) {
     return Array.isArray(value) ? value.filter(isObject) : [];
 }
@@ -554,6 +1093,68 @@ async function pathExists(file) {
         return false;
     }
 }
+async function resolvePidManifestPath(runPath) {
+    const absolute = path.resolve(runPath);
+    const stat = await fs.lstat(absolute).catch(() => undefined);
+    if (stat?.isDirectory())
+        return path.join(absolute, 'pids.json');
+    if (path.basename(absolute) === 'swarm-results.json')
+        return path.join(path.dirname(absolute), 'pids.json');
+    return absolute;
+}
+async function resolveRunDirectory(runPath) {
+    const absolute = path.resolve(runPath);
+    const stat = await fs.lstat(absolute).catch(() => undefined);
+    if (stat?.isDirectory())
+        return absolute;
+    if (path.basename(absolute) === 'swarm-results.json' || path.basename(absolute) === 'pids.json')
+        return path.dirname(absolute);
+    return path.dirname(absolute);
+}
+async function findFilesByName(root, name) {
+    const out = [];
+    async function walk(current) {
+        const entries = await fs.readdir(current, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            const absolute = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name === 'collected' || entry.name === 'node_modules' || entry.name === '.git')
+                    continue;
+                await walk(absolute);
+            }
+            else if (entry.isFile() && entry.name === name) {
+                out.push(absolute);
+            }
+        }
+    }
+    await walk(root);
+    return out;
+}
+async function bundlePatchIsStale(bundle, mergePath, cwd) {
+    const patchPath = resolveBundlePatchPath(bundle, mergePath);
+    if (!patchPath || !await pathExists(patchPath))
+        return false;
+    const patch = await fs.readFile(patchPath, 'utf8').catch(() => '');
+    if (!patch.trim())
+        return false;
+    const result = await runProcess('git', ['apply', '--check', patchPath], { cwd, allowFailure: true });
+    return result.status !== 0;
+}
+function resolveBundlePatchPath(bundle, mergePath) {
+    if (!bundle.patchPath)
+        return undefined;
+    return path.isAbsolute(bundle.patchPath) ? bundle.patchPath : path.resolve(path.dirname(mergePath), bundle.patchPath);
+}
+function classifyCodexCollectBucket(bundle, staleAgainstHead) {
+    if (staleAgainstHead || bundle.staleAgainstHead || bundle.disposition === 'stale-against-head')
+        return 'stale-against-head';
+    if (bundle.disposition === 'rejected' || bundle.disposition === 'blocked' || bundle.commandsFailed.length > 0 || bundle.status === 'failed') {
+        return 'failed-evidence';
+    }
+    if (bundle.disposition === 'auto-mergeable' && bundle.autoMergeable)
+        return 'ready-to-apply';
+    return 'needs-human-port';
+}
 async function readOptionalText(file) {
     try {
         return await fs.readFile(file, 'utf8');
@@ -591,4 +1192,24 @@ async function runProcess(command, args, options) {
 function tail(text, maxLines = 24) {
     return text.trim().split(/\r?\n/).filter(Boolean).slice(-maxLines);
 }
+function stableHash(value) {
+    const text = stableStringify(value);
+    let hash = 2166136261;
+    for (let index = 0; index < text.length; index += 1) {
+        hash ^= text.charCodeAt(index);
+        hash = Math.imul(hash, 16777619);
+    }
+    return 'fnv1a32:' + (hash >>> 0).toString(16).padStart(8, '0');
+}
+function slug(value) {
+    return value.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'item';
+}
+function stableStringify(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return '[' + value.map(stableStringify).join(',') + ']';
+    const object = value;
+    return '{' + Object.keys(object).sort().map((key) => JSON.stringify(key) + ':' + stableStringify(object[key])).join(',') + '}';
+}
 //# sourceMappingURL=index.js.map