@shapeshift-labs/frontier-swarm-codex 0.2.0 → 0.4.0

package/dist/index.js

@@ -1,9 +1,22 @@
 import { spawn } from 'node:child_process';
 import fs from 'node:fs/promises';
+import os from 'node:os';
 import path from 'node:path';
-import { FRONTIER_SWARM_DEFAULT_MODEL, FRONTIER_SWARM_DEFAULT_REASONING_EFFORT, checkSwarmOwnership, completeSwarmJob, createSwarmLeases, createSwarmPlan, createSwarmProof, createSwarmRun, createSwarmSchedule, recordSwarmEvent } from '@shapeshift-labs/frontier-swarm';
+import { FRONTIER_SWARM_DEFAULT_MODEL, FRONTIER_SWARM_DEFAULT_REASONING_EFFORT, checkSwarmOwnership, completeSwarmJob, FRONTIER_SWARM_MERGE_BUNDLE_KIND, FRONTIER_SWARM_MERGE_BUNDLE_VERSION, createSwarmMergeBundle, createSwarmMergeIndex, createSwarmQueueOverlay, matchesGlob, 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;
+export const FRONTIER_SWARM_CODEX_APPLY_LEDGER_KIND = 'frontier.swarm-codex.apply-ledger';
+export const FRONTIER_SWARM_CODEX_APPLY_LEDGER_VERSION = 1;
+export const FRONTIER_SWARM_CODEX_PATCH_SCORE_KIND = 'frontier.swarm-codex.patch-score';
+export const FRONTIER_SWARM_CODEX_PATCH_SCORE_VERSION = 1;
 const DEFAULT_WORKSPACE_INCLUDES = ['AGENTS.md', 'package.json', 'package-lock.json', 'pnpm-lock.yaml', 'yarn.lock', 'config'];
 const DEFAULT_WORKSPACE_EXCLUDES = [
     '.git',
@@ -15,6 +28,7 @@ const DEFAULT_WORKSPACE_EXCLUDES = [
     'test/roms',
     'target'
 ];
+const pidManifestWriteQueues = new Map();
 export function createCodexSwarmPlan(input) {
     return createSwarmPlan(coerceCodexSwarmManifestInput(input.manifest), coerceCodexSwarmTasksInput(input.tasks), input.plan ?? {});
 }
@@ -78,11 +92,16 @@ export function coerceCodexSwarmTasksInput(value) {
             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 }
         };
@@ -92,26 +111,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 runScheduledJobPool(plan, Math.max(1, options.maxConcurrency ?? 1), (job, lease) => runCodexJob(job, options, outDir, lease));
+    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, lease) {
-    const paths = await createJobPaths(outDir, job);
+    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: [] }
@@ -125,12 +205,27 @@ export async function runCodexJob(job, options, outDir, lease) {
             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,
@@ -138,19 +233,34 @@ export async function runCodexJob(job, options, outDir, lease) {
         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,
         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 = normalizeCodexApprovalPolicy(input.approval);
     const args = [
+        ...(approval ? ['--ask-for-approval', approval] : []),
         'exec',
         '--cd',
         input.workspacePath,
@@ -160,12 +270,12 @@ export function buildCodexArgs(job, input) {
         sandbox,
         '--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}"`);
     if (shouldSkipGitRepoCheck(input))
         args.push('--skip-git-repo-check');
     for (const dir of input.addDirs ?? [])
@@ -178,6 +288,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',
@@ -237,6 +397,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(() => { }));
@@ -255,7 +424,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,
@@ -263,7 +432,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;
@@ -285,6 +458,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 });
@@ -314,6 +488,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
@@ -341,6 +519,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,
@@ -349,11 +537,562 @@ 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 absolute = path.resolve(file);
+    const previous = pidManifestWriteQueues.get(absolute) ?? Promise.resolve();
+    let next;
+    next = previous
+        .catch(() => { })
+        .then(() => appendCodexPidManifestUnlocked(absolute, entry, runId))
+        .finally(() => {
+        if (pidManifestWriteQueues.get(absolute) === next)
+            pidManifestWriteQueues.delete(absolute);
+    });
+    pidManifestWriteQueues.set(absolute, next);
+    return next;
+}
+async function appendCodexPidManifestUnlocked(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 writeJsonAtomic(file, { ...manifest, ...(runId ? { runId } : {}), entries });
+}
+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 collectedBundles = [];
+    const patchStatuses = {};
+    const mergePaths = (await findFilesByName(runDir, 'merge.json'))
+        .filter((mergePath) => !pathHasIgnoredSegment(path.relative(runDir, mergePath), [
+        'collected',
+        'patch-scores',
+        'ready-to-apply',
+        'needs-human-port',
+        'failed-evidence',
+        'stale-against-head'
+    ]));
+    const mergeRecordsByJob = new Map();
+    for (const mergePath of mergePaths.sort()) {
+        const bundle = normalizeCollectedMergeBundle(JSON.parse(await fs.readFile(mergePath, 'utf8')), mergePath);
+        const existing = mergeRecordsByJob.get(bundle.jobId);
+        const next = { mergePath, bundle };
+        if (!existing || mergeRecordScore(next) > mergeRecordScore(existing))
+            mergeRecordsByJob.set(bundle.jobId, next);
+    }
+    const mergeRecords = Array.from(mergeRecordsByJob.values()).sort((left, right) => left.bundle.jobId.localeCompare(right.bundle.jobId));
+    for (const { mergePath, bundle } of mergeRecords) {
+        const patchPath = resolveBundlePatchPath(bundle, mergePath);
+        const patchExists = !!patchPath && await pathExists(patchPath);
+        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
+        };
+        collectedBundles.push(nextBundle);
+        patchStatuses[nextBundle.jobId] = staleAgainstHead ? 'stale' : patchExists ? input.checkStale === false ? 'unknown' : 'applies' : 'missing';
+        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');
+        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 mergeIndex = createSwarmMergeIndex({
+        runId: path.basename(runDir),
+        bundles: collectedBundles,
+        patchStatuses
+    });
+    const queueOverlay = createSwarmQueueOverlay({
+        runId: path.basename(runDir),
+        bundles: collectedBundles
+    });
+    const summary = {
+        total: mergeRecords.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,
+        mergeIndex,
+        queueOverlay,
+        summary
+    };
+    await fs.mkdir(outDir, { recursive: true });
+    await fs.writeFile(path.join(outDir, 'collection.json'), JSON.stringify(result, null, 2) + '\n');
+    await fs.writeFile(path.join(outDir, 'merge-index.json'), JSON.stringify(mergeIndex, null, 2) + '\n');
+    await fs.writeFile(path.join(outDir, 'queue-overlay.json'), JSON.stringify(queueOverlay, null, 2) + '\n');
+    return result;
+}
+export async function applyCodexSwarmCollection(input) {
+    const generatedAt = Date.now();
+    const cwd = path.resolve(input.cwd ?? process.cwd());
+    const dryRun = input.dryRun ?? true;
+    if (!input.collection && !input.run)
+        throw new Error('apply requires --collection <dir> or --run <run-dir>');
+    const collectionDir = input.collection
+        ? path.resolve(cwd, input.collection)
+        : (await collectCodexSwarmRun({ run: String(input.run ?? ''), cwd, outDir: input.outDir })).outDir;
+    const outDir = path.resolve(cwd, input.outDir ?? path.join(collectionDir, 'apply-ledger'));
+    if (!dryRun && !input.allowDirty) {
+        const dirty = await gitDirty(cwd);
+        if (dirty.length)
+            throw new Error(`refusing to apply into dirty worktree; pass allowDirty to override (${dirty.slice(0, 8).join(', ')})`);
+    }
+    const bucket = input.bucket ?? 'ready-to-apply';
+    const roots = bucket === 'all'
+        ? ['ready-to-apply', 'needs-human-port', 'failed-evidence', 'stale-against-head'].map((entry) => path.join(collectionDir, entry))
+        : [path.join(collectionDir, bucket)];
+    const wanted = new Set(input.jobIds ?? []);
+    const mergePaths = (await Promise.all(roots.map((root) => findFilesByName(root, 'merge.json')))).flat().sort();
+    const entries = [];
+    for (const mergePath of mergePaths.slice(0, input.limit ? Math.max(0, Math.floor(input.limit)) : undefined)) {
+        const bundle = JSON.parse(await fs.readFile(mergePath, 'utf8'));
+        if (wanted.size && !wanted.has(bundle.jobId))
+            continue;
+        entries.push(await applyCodexMergeBundle({
+            cwd,
+            bundle,
+            mergePath,
+            dryRun,
+            commit: input.commit ?? false,
+            branchPrefix: input.branchPrefix
+        }));
+    }
+    const summary = {
+        total: entries.length,
+        checked: entries.filter((entry) => entry.status === 'checked').length,
+        applied: entries.filter((entry) => entry.status === 'applied').length,
+        committed: entries.filter((entry) => entry.status === 'committed').length,
+        skipped: entries.filter((entry) => entry.status === 'skipped').length,
+        failed: entries.filter((entry) => entry.status === 'failed').length
+    };
+    const result = {
+        kind: FRONTIER_SWARM_CODEX_APPLY_LEDGER_KIND,
+        version: FRONTIER_SWARM_CODEX_APPLY_LEDGER_VERSION,
+        ok: summary.failed === 0,
+        cwd,
+        collectionDir,
+        outDir,
+        generatedAt,
+        dryRun,
+        entries,
+        summary
+    };
+    await fs.mkdir(outDir, { recursive: true });
+    await fs.writeFile(path.join(outDir, 'apply-ledger.json'), JSON.stringify(result, null, 2) + '\n');
+    return result;
+}
+export async function scoreCodexSwarmPatches(input) {
+    const generatedAt = Date.now();
+    const cwd = path.resolve(input.cwd ?? process.cwd());
+    if (!input.collection && !input.run)
+        throw new Error('score requires --collection <dir> or --run <run-dir>');
+    const collectionDir = input.collection
+        ? path.resolve(cwd, input.collection)
+        : (await collectCodexSwarmRun({ run: String(input.run ?? ''), cwd, outDir: input.outDir })).outDir;
+    const outDir = path.resolve(cwd, input.outDir ?? path.join(collectionDir, 'patch-scores'));
+    const bucket = input.bucket ?? 'all';
+    const roots = bucket === 'all'
+        ? ['ready-to-apply', 'needs-human-port', 'failed-evidence', 'stale-against-head'].map((entry) => path.join(collectionDir, entry))
+        : [path.join(collectionDir, bucket)];
+    const wanted = new Set(input.jobIds ?? []);
+    const mergePaths = (await Promise.all(roots.map((root) => findFilesByName(root, 'merge.json')))).flat().sort();
+    const entries = [];
+    for (const mergePath of mergePaths.slice(0, input.limit ? Math.max(0, Math.floor(input.limit)) : undefined)) {
+        const bundle = JSON.parse(await fs.readFile(mergePath, 'utf8'));
+        if (wanted.size && !wanted.has(bundle.jobId))
+            continue;
+        entries.push(await scoreCodexMergeBundle({ cwd, mergePath, bundle, outDir, input }));
+    }
+    const statuses = ['accepted-clean', 'accepted-needs-port', 'conflict', 'test-fail', 'stale', 'evidence-only'];
+    const summary = Object.fromEntries(statuses.map((status) => [status, entries.filter((entry) => entry.status === status).length]));
+    const result = {
+        kind: FRONTIER_SWARM_CODEX_PATCH_SCORE_KIND,
+        version: FRONTIER_SWARM_CODEX_PATCH_SCORE_VERSION,
+        ok: entries.every((entry) => entry.status === 'accepted-clean' || entry.status === 'accepted-needs-port' || entry.status === 'evidence-only'),
+        cwd,
+        collectionDir,
+        outDir,
+        generatedAt,
+        entries: entries.sort((left, right) => right.score - left.score || left.jobId.localeCompare(right.jobId)),
+        summary: { ...summary, total: entries.length }
+    };
+    await fs.mkdir(outDir, { recursive: true });
+    await fs.writeFile(path.join(outDir, 'patch-score.json'), JSON.stringify(result, null, 2) + '\n');
+    return result;
+}
+async function applyCodexMergeBundle(input) {
+    const commands = [];
+    const patchPath = await resolveApplyPatchPath(input.bundle, input.mergePath);
+    const branchName = input.branchPrefix ? `${input.branchPrefix}/${slug(input.bundle.jobId)}` : input.bundle.branchName;
+    const base = {
+        jobId: input.bundle.jobId,
+        bundlePath: input.mergePath,
+        ...(patchPath ? { patchPath } : {}),
+        ...(branchName ? { branchName } : {}),
+        dryRun: input.dryRun,
+        commands
+    };
+    if (!patchPath) {
+        return {
+            ...base,
+            status: input.bundle.disposition === 'discovery-only' ? 'skipped' : 'failed',
+            error: 'missing patch'
+        };
+    }
+    const check = await runLoggedProcess('git', ['apply', '--check', patchPath], input.cwd);
+    commands.push(check);
+    if (check.status !== 0)
+        return { ...base, status: 'failed', error: 'git apply --check failed' };
+    if (input.dryRun)
+        return { ...base, status: 'checked' };
+    if (branchName) {
+        const branch = await runLoggedProcess('git', ['switch', '-c', branchName], input.cwd);
+        commands.push(branch);
+        if (branch.status !== 0)
+            return { ...base, status: 'failed', error: 'git switch -c failed' };
+    }
+    const apply = await runLoggedProcess('git', ['apply', patchPath], input.cwd);
+    commands.push(apply);
+    if (apply.status !== 0)
+        return { ...base, status: 'failed', error: 'git apply failed' };
+    if (!input.commit)
+        return { ...base, status: 'applied' };
+    const add = await runLoggedProcess('git', ['add', '--', ...input.bundle.changedPaths], input.cwd);
+    commands.push(add);
+    if (add.status !== 0)
+        return { ...base, status: 'failed', error: 'git add failed' };
+    const commit = await runLoggedProcess('git', ['commit', '-m', `Apply swarm bundle ${input.bundle.jobId}`], input.cwd);
+    commands.push(commit);
+    if (commit.status !== 0)
+        return { ...base, status: 'failed', error: 'git commit failed' };
+    const rev = await runLoggedProcess('git', ['rev-parse', 'HEAD'], input.cwd);
+    commands.push(rev);
+    return {
+        ...base,
+        status: 'committed',
+        commit: rev.stdoutTail[0]
+    };
+}
+async function scoreCodexMergeBundle(input) {
+    const commands = [];
+    const patchPath = await resolveApplyPatchPath(input.bundle, input.mergePath);
+    const base = {
+        jobId: input.bundle.jobId,
+        bundlePath: input.mergePath,
+        ...(patchPath ? { patchPath } : {}),
+        changedPaths: [...input.bundle.changedPaths],
+        commands
+    };
+    if (!patchPath || input.bundle.disposition === 'discovery-only' || input.bundle.changedPaths.length === 0) {
+        return { ...base, status: 'evidence-only', score: 20, reasons: ['no patch to apply'] };
+    }
+    if (input.bundle.staleAgainstHead || input.bundle.disposition === 'stale-against-head') {
+        return { ...base, status: 'stale', score: 0, reasons: ['stale-against-head'] };
+    }
+    const workspacePath = await createScoreWorkspace(input.cwd, input.bundle.jobId, input.input);
+    try {
+        const check = await runLoggedProcess('git', ['apply', '--check', patchPath], workspacePath);
+        commands.push(check);
+        if (check.status !== 0)
+            return { ...base, workspacePath, status: 'conflict', score: 0, reasons: ['git apply --check failed'] };
+        const apply = await runLoggedProcess('git', ['apply', patchPath], workspacePath);
+        commands.push(apply);
+        if (apply.status !== 0)
+            return { ...base, workspacePath, status: 'conflict', score: 0, reasons: ['git apply failed'] };
+        const gates = scoreCommands(input.bundle, input.input);
+        for (const gate of gates) {
+            const run = await runLoggedProcess(gate.command, gate.args, gate.cwd ? path.resolve(workspacePath, gate.cwd) : workspacePath);
+            commands.push(run);
+            if (run.status !== 0 && gate.required !== false) {
+                return { ...base, workspacePath, status: 'test-fail', score: 10, reasons: [`gate failed: ${gate.name}`] };
+            }
+        }
+        const clean = input.bundle.disposition === 'auto-mergeable' && input.bundle.autoMergeable;
+        return {
+            ...base,
+            workspacePath,
+            status: clean ? 'accepted-clean' : 'accepted-needs-port',
+            score: clean ? 100 : 70,
+            reasons: clean ? [] : ['patch applies but bundle is not auto-mergeable']
+        };
+    }
+    finally {
+        if (!input.input.keepWorkspaces)
+            await fs.rm(workspacePath, { recursive: true, force: true }).catch(() => { });
+    }
+}
+async function createScoreWorkspace(cwd, jobId, input) {
+    const workspacePath = await fs.mkdtemp(path.join(os.tmpdir(), `frontier-swarm-score-${slug(jobId)}-`));
+    const excludes = uniqueWorkspacePaths([
+        '.git',
+        'node_modules',
+        'dist',
+        'coverage',
+        'agent-runs',
+        '.frontier-framework',
+        ...(input.workspaceExcludes ?? [])
+    ]);
+    const includes = uniqueWorkspacePaths(input.workspaceIncludes ?? []);
+    if (includes.length) {
+        for (const include of includes)
+            await copyWorkspacePath(cwd, workspacePath, include, excludes);
+    }
+    else {
+        await fs.cp(cwd, workspacePath, {
+            recursive: true,
+            force: true,
+            filter: (source) => {
+                if (source === cwd)
+                    return true;
+                const relative = path.relative(cwd, source).replace(/\\/g, '/');
+                if (!relative)
+                    return true;
+                if (pathHasIgnoredSegment(relative, excludes))
+                    return false;
+                return !excludes.some((entry) => relative === entry || relative.startsWith(entry.replace(/\/$/, '') + '/'));
+            }
+        });
+    }
+    return workspacePath;
+}
+function scoreCommands(bundle, input) {
+    const focused = normalizeScoreCommands(input.focusedCommands ?? []);
+    const global = bundle.changedPaths.some((file) => (input.globalGlobs ?? []).some((glob) => matchesGlob(file, glob)))
+        ? normalizeScoreCommands(input.globalCommands ?? [])
+        : [];
+    return [...focused, ...global];
+}
+function normalizeScoreCommands(input) {
+    return input.map((entry) => {
+        if (typeof entry === 'string')
+            return { name: entry, command: 'sh', args: ['-c', entry], required: true };
+        return {
+            name: entry.name,
+            command: entry.command,
+            args: [...entry.args],
+            required: entry.required,
+            ...(entry.cwd ? { cwd: entry.cwd } : {}),
+            ...(entry.metadata ? { metadata: entry.metadata } : {})
+        };
+    }).filter((entry) => entry.command.length > 0);
+}
+async function resolveApplyPatchPath(bundle, mergePath) {
+    const sibling = path.join(path.dirname(mergePath), 'changes.patch');
+    if (await pathExists(sibling))
+        return sibling;
+    const patchPath = resolveBundlePatchPath(bundle, mergePath);
+    if (patchPath && await pathExists(patchPath))
+        return patchPath;
+    return undefined;
+}
+async function runLoggedProcess(command, args, cwd) {
+    const result = await runProcess(command, args, { cwd, allowFailure: true });
+    return {
+        command: [command, ...args],
+        status: result.status,
+        stdoutTail: tail(result.stdout),
+        stderrTail: tail(result.stderr)
+    };
+}
+async function writeJsonAtomic(file, value) {
+    const tmp = `${file}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`;
+    await fs.writeFile(tmp, JSON.stringify(value, null, 2) + '\n');
+    await fs.rename(tmp, file);
+}
+async function gitDirty(cwd) {
+    const result = await runProcess('git', ['status', '--porcelain'], { cwd, allowFailure: true });
+    if (result.status !== 0)
+        return [];
+    return result.stdout.split(/\r?\n/).filter(Boolean).map((line) => line.slice(3));
+}
 async function copyWorkspacePath(cwd, workspacePath, include, excludes) {
     const relative = normalizeWorkspacePath(include);
     if (!relative)
@@ -392,6 +1131,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 : {};
@@ -426,12 +1171,77 @@ 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;
+    if (pathHasIgnoredSegment(file, ['node_modules', 'dist', 'coverage', '.frontier-framework', 'agent-runs']))
+        return true;
+    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(/\/$/, '') + '/'));
+}
+function pathHasIgnoredSegment(file, segments) {
+    const parts = file.replace(/\\/g, '/').split('/').filter(Boolean);
+    return parts.some((part) => segments.includes(part));
 }
 async function snapshotWorkspaceFiles(root) {
     const snapshot = new Map();
@@ -625,6 +1435,122 @@ 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 normalizeCollectedMergeBundle(value, mergePath) {
+    const input = typeof value === 'object' && value !== null ? value : {};
+    const jobId = typeof input.jobId === 'string' && input.jobId ? input.jobId : path.basename(path.dirname(mergePath));
+    const changedPaths = stringArray(input.changedPaths);
+    const status = typeof input.status === 'string' ? input.status : 'completed';
+    const autoMergeable = Boolean(input.autoMergeable);
+    const disposition = typeof input.disposition === 'string'
+        ? input.disposition
+        : autoMergeable ? 'auto-mergeable' : status === 'failed' ? 'rejected' : 'needs-port';
+    return {
+        kind: typeof input.kind === 'string' ? input.kind : FRONTIER_SWARM_MERGE_BUNDLE_KIND,
+        version: typeof input.version === 'number' ? input.version : FRONTIER_SWARM_MERGE_BUNDLE_VERSION,
+        id: typeof input.id === 'string' && input.id ? input.id : `swarm-merge-bundle:${jobId}`,
+        ...(typeof input.runId === 'string' ? { runId: input.runId } : {}),
+        ...(typeof input.planId === 'string' ? { planId: input.planId } : {}),
+        jobId,
+        ...(typeof input.taskId === 'string' ? { taskId: input.taskId } : {}),
+        ...(typeof input.lane === 'string' ? { lane: input.lane } : {}),
+        ...(typeof input.title === 'string' ? { title: input.title } : {}),
+        generatedAt: typeof input.generatedAt === 'number' ? input.generatedAt : Date.now(),
+        status,
+        mergeReadiness: typeof input.mergeReadiness === 'string'
+            ? input.mergeReadiness
+            : changedPaths.length ? 'patch-candidate' : 'discovery-only',
+        disposition,
+        riskLevel: typeof input.riskLevel === 'string' ? input.riskLevel : 'unknown',
+        autoMergeable,
+        changedPaths,
+        changedRegions: stringArray(input.changedRegions),
+        ownedFilesTouched: stringArray(input.ownedFilesTouched),
+        allowedWrites: stringArray(input.allowedWrites),
+        ownershipViolations: stringArray(input.ownershipViolations),
+        ...(typeof input.patchPath === 'string' ? { patchPath: input.patchPath } : {}),
+        ...(typeof input.patchHash === 'string' ? { patchHash: input.patchHash } : {}),
+        evidencePaths: stringArray(input.evidencePaths),
+        commandsPassed: Array.isArray(input.commandsPassed) ? input.commandsPassed : [],
+        commandsFailed: Array.isArray(input.commandsFailed) ? input.commandsFailed : [],
+        queueItemIds: stringArray(input.queueItemIds),
+        ...(typeof input.branchName === 'string' ? { branchName: input.branchName } : {}),
+        ...(typeof input.commit === 'string' ? { commit: input.commit } : {}),
+        staleAgainstHead: Boolean(input.staleAgainstHead),
+        reasons: stringArray(input.reasons)
+    };
+}
+function mergeRecordScore(record) {
+    return (record.mergePath.includes('/evidence/') ? 100 : 0)
+        + record.bundle.changedPaths.length
+        + record.bundle.evidencePaths.length
+        + record.bundle.commandsPassed.length
+        + record.bundle.commandsFailed.length;
+}
+function stringArray(value) {
+    return Array.isArray(value) ? value.filter((entry) => typeof entry === 'string') : [];
+}
+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');
@@ -662,4 +1588,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