@shapeshift-labs/frontier-swarm 0.2.0 → 0.3.0

package/README.md

@@ -36,7 +36,7 @@ The published Frontier package family is generated from one shared package catal
 - [`@shapeshift-labs/frontier-workflow`](https://www.npmjs.com/package/@shapeshift-labs/frontier-workflow): Serializable durable workflow/process manifests for Frontier apps, including steps, waits, approvals, timers, retries, expected patches, compensation, records, timelines, and registry graph output.
 - [`@shapeshift-labs/frontier-worker`](https://www.npmjs.com/package/@shapeshift-labs/frontier-worker): Serializable worker and edge task descriptors for Frontier apps, including queues, idempotency keys, retry and timeout policy, declared reads/writes/effects, snapshots, patch outputs, produced assets, execution records, logs, trace links, proof hashes, dedupe indexes, and registry graph output.
 - [`@shapeshift-labs/frontier-queue`](https://www.npmjs.com/package/@shapeshift-labs/frontier-queue): Serializable durable queue state, leases, retries, dedupe keys, patch-carrying jobs, dead-letter records, replay evidence, and queue inspection for Frontier apps.
-- [`@shapeshift-labs/frontier-swarm-codex`](https://www.npmjs.com/package/@shapeshift-labs/frontier-swarm-codex): Node Codex CLI adapter for Frontier swarm plans, including prompt rendering, worktree and snapshot workspaces, Codex argument construction, JSONL capture, verification commands, and result artifacts.
+- [`@shapeshift-labs/frontier-swarm-codex`](https://www.npmjs.com/package/@shapeshift-labs/frontier-swarm-codex): Node Codex CLI adapter for Frontier swarm plans, including prompt rendering, worktree and snapshot workspaces, Codex argument compatibility, JSONL capture, verification commands, pid-backed stop, collect buckets, merge bundles, and result artifacts.
 - [`@shapeshift-labs/frontier-kv`](https://www.npmjs.com/package/@shapeshift-labs/frontier-kv): Serializable in-memory key/value state for Frontier apps, including TTL, versioned compare-and-set, batched patch mutations, scans, watchers, snapshots, JSONL event evidence, and replay verification.
 - [`@shapeshift-labs/frontier-kv-locks`](https://www.npmjs.com/package/@shapeshift-labs/frontier-kv-locks): Lease-style lock records on top of Frontier KV, including acquire, renew, release, fencing tokens, expiration, owner evidence, and replayable lock events.
 - [`@shapeshift-labs/frontier-kv-rate-limit`](https://www.npmjs.com/package/@shapeshift-labs/frontier-kv-rate-limit): Patch-native rate limit buckets for Frontier KV, including fixed windows, sliding windows, token buckets, deterministic refill, consume evidence, and reset records.
@@ -211,10 +211,13 @@ Large swarms need a control plane, not just a flat worker loop. `frontier-swarm`
 import {
   checkSwarmBudget,
   createSwarmArtifactIndex,
+  createSwarmEventStream,
   createSwarmLeases,
   createSwarmMergePlan,
+  createSwarmQueueSnapshot,
   createSwarmReviewPlan,
-  createSwarmSchedule
+  createSwarmSchedule,
+  routeSwarmEventToMailboxes
 } from '@shapeshift-labs/frontier-swarm';
 
 const schedule = createSwarmSchedule({
@@ -237,10 +240,16 @@ The scale APIs are runtime-neutral and serializable:
 - dependency DAGs are compiled into `plan.graph`,
 - `createSwarmSchedule` returns ready, blocked, running, completed, and failed jobs under lane/compute/contention limits,
 - `createSwarmLeases` gives workers expiring leases with fencing tokens,
+- lane/task `capabilities` and `resourceRequirements` can reserve browser work with lower concurrency, port pools, profile directories, and explicit capability checks,
+- `createSwarmQueueSnapshot` and run checkpoints give durable queue/run-store adapters a stable serialization shape,
+- `createSwarmEventStream` and `routeSwarmEventToMailboxes` route global, lane, task, and worker events into coordinator-facing JSONL streams,
 - `checkSwarmBudget` records token/cost/time/retry budget decisions,
 - `createSwarmArtifactIndex` groups evidence, timelines, logs, and produced files,
 - `createSwarmReviewPlan` samples or requires reviewer assignments,
 - `createSwarmMergePlan` blocks jobs with failed checks, required reviews, ownership violations, or conflicting changed paths,
+- job results include merge-readiness classification: `discovery-only`, `patch-candidate`, `verified-patch`, `rejected`, or `blocked`,
+- `ownershipRegions` allow hot files to be split into semantic regions such as `content.docs.*` or `adminSettings.quota.*`; merge conflict detection prefers changed regions when workers report them,
+- `createSwarmMergeBundle` builds a compact worker `merge.json` shape with touched owned files, patch path, evidence, verification, queue items satisfied, risk, and disposition,
 - `decomposeSwarmFeature` creates an initial task queue for feature work across lanes.
 
 ## Hierarchical Compute
@@ -260,11 +269,17 @@ That lets a parent swarm route implementation jobs to a deep model while evidenc
 - `defineSwarmManifest`, `createSwarmManifest`
 - `defineSwarmTasks`
 - `compileSwarm`, `validateSwarmManifest`
+- `createSwarmTaskSelection`
 - `createSwarmPlan`, `createSwarmRun`
 - `createSwarmSchedule`, `createSwarmLeases`
+- `createSwarmQueueSnapshot`, `createSwarmRunCheckpoint`
+- `createSwarmEventStream`, `createSwarmMailbox`, `routeSwarmEventToMailboxes`
 - `checkSwarmBudget`
 - `createSwarmArtifactIndex`
 - `createSwarmReviewPlan`, `createSwarmMergePlan`
+- `createSwarmMergeBundle`
+- `classifySwarmMergeReadiness`, `classifySwarmMergeDisposition`
+- `resolveSwarmChangedRegions`
 - `decomposeSwarmFeature`
 - `recordSwarmEvent`, `completeSwarmJob`
 - `resolveSwarmCompute`
@@ -280,7 +295,7 @@ Run the package-local benchmark:
 npm run bench
 ```
 
-The benchmark writes `benchmarks/results/frontier-swarm-package-bench-latest.json` when run from the monorepo. These are Frontier-only package measurements for plan creation, manifest validation, hierarchical compute resolution, ownership checks, run creation, JSONL, and proof hashing.
+The benchmark writes `benchmarks/results/frontier-swarm-package-bench-latest.json` when run from the monorepo. These are Frontier-only package measurements for plan creation, manifest validation, hierarchical compute resolution, ownership checks, scheduling/leases, queue snapshots, merge bundle creation, event routing, run checkpoints, JSONL, and proof hashing.
 
 ## Source Repository
 

package/benchmarks/package-bench.mjs

@@ -5,12 +5,19 @@ import { fileURLToPath } from 'node:url';
 import {
   checkSwarmOwnership,
   createSwarmManifest,
+  createSwarmEventStream,
+  createSwarmLeases,
+  createSwarmMergeBundle,
   createSwarmPlan,
   createSwarmProof,
+  createSwarmQueueSnapshot,
   createSwarmRun,
+  createSwarmRunCheckpoint,
+  createSwarmSchedule,
   decodeSwarmJsonl,
   defineSwarmTasks,
   encodeSwarmJsonl,
+  routeSwarmEventToMailboxes,
   resolveSwarmCompute,
   validateSwarmManifest
 } from '../dist/index.js';
@@ -31,6 +38,9 @@ let plan = createSwarmPlan(manifest, tasks, { limit: 64 });
 let run = createSwarmRun({ plan });
 let jsonl = encodeSwarmJsonl([plan, run]);
 let cursor = 0;
+let schedule = createSwarmSchedule({ plan, maxReadyJobs: 128 });
+let leases = createSwarmLeases({ schedule, workerId: 'bench-worker', now: 1000, leaseMs: 60000, count: 16 });
+let eventStream = createSwarmEventStream({ runId: 'bench', root: 'agent-runs/bench/streams', lanes: manifest.lanes });
 
 const rows = [
   measure('create-plan-' + taskCount, 8, () => {
@@ -49,7 +59,31 @@ const rows = [
     return jsonl.length;
   }),
   measure('jsonl-decode', 16, () => decodeSwarmJsonl(jsonl).length),
-  measure('proof', 16, () => createSwarmProof(plan).hash.length)
+  measure('proof', 16, () => createSwarmProof(plan).hash.length),
+  measure('schedule-lease-' + taskCount, 8, () => {
+    schedule = createSwarmSchedule({ plan, maxReadyJobs: 128, maxComputeConcurrency: { fast: 64, deep: 32 } });
+    leases = createSwarmLeases({ schedule, workerId: 'bench-worker', now: 1000 + cursor++, leaseMs: 60000, count: 16 });
+    return schedule.ready.length + leases.length;
+  }),
+  measure('queue-snapshot-' + taskCount, 8, () => {
+    const snapshot = createSwarmQueueSnapshot({ plan, run, leases, generatedAt: 2000 + cursor++ });
+    return snapshot.summary.jobCount + snapshot.summary.leaseCount;
+  }),
+  measure('run-checkpoint-' + taskCount, 16, () => createSwarmRunCheckpoint({ run, sequence: cursor++ }).hash.length),
+  measure('merge-bundle-' + taskCount, 32, () => createSwarmMergeBundle({
+    job: plan.jobs[cursor % plan.jobs.length],
+    result: {
+      jobId: plan.jobs[cursor++ % plan.jobs.length].id,
+      status: 'completed',
+      changedPaths: ['src/runtime/file.ts'],
+      verification: [{ status: 0 }]
+    },
+    patchPath: 'agent-runs/bench/changes.patch'
+  }).id.length),
+  measure('event-route-' + taskCount, 64, () => {
+    eventStream = createSwarmEventStream({ runId: 'bench', root: 'agent-runs/bench/streams', lanes: manifest.lanes });
+    return routeSwarmEventToMailboxes(eventStream, { type: 'agent.evidence', jobId: plan.jobs[cursor++ % plan.jobs.length].id, lane: 'runtime' }).length;
+  })
 ];
 
 const report = {

package/dist/index.d.ts

@@ -9,18 +9,28 @@ export declare const FRONTIER_SWARM_RUN_KIND = "frontier.swarm.run";
 export declare const FRONTIER_SWARM_RUN_VERSION = 1;
 export declare const FRONTIER_SWARM_EVENT_KIND = "frontier.swarm.event";
 export declare const FRONTIER_SWARM_EVENT_VERSION = 1;
+export declare const FRONTIER_SWARM_EVENT_STREAM_KIND = "frontier.swarm.event-stream";
+export declare const FRONTIER_SWARM_EVENT_STREAM_VERSION = 1;
+export declare const FRONTIER_SWARM_MAILBOX_KIND = "frontier.swarm.mailbox";
+export declare const FRONTIER_SWARM_MAILBOX_VERSION = 1;
 export declare const FRONTIER_SWARM_PROOF_KIND = "frontier.swarm.proof";
 export declare const FRONTIER_SWARM_PROOF_VERSION = 1;
 export declare const FRONTIER_SWARM_SCHEDULE_KIND = "frontier.swarm.schedule";
 export declare const FRONTIER_SWARM_SCHEDULE_VERSION = 1;
 export declare const FRONTIER_SWARM_LEASE_KIND = "frontier.swarm.lease";
 export declare const FRONTIER_SWARM_LEASE_VERSION = 1;
+export declare const FRONTIER_SWARM_QUEUE_SNAPSHOT_KIND = "frontier.swarm.queue-snapshot";
+export declare const FRONTIER_SWARM_QUEUE_SNAPSHOT_VERSION = 1;
+export declare const FRONTIER_SWARM_RUN_CHECKPOINT_KIND = "frontier.swarm.run-checkpoint";
+export declare const FRONTIER_SWARM_RUN_CHECKPOINT_VERSION = 1;
 export declare const FRONTIER_SWARM_ARTIFACT_INDEX_KIND = "frontier.swarm.artifact-index";
 export declare const FRONTIER_SWARM_ARTIFACT_INDEX_VERSION = 1;
 export declare const FRONTIER_SWARM_REVIEW_PLAN_KIND = "frontier.swarm.review-plan";
 export declare const FRONTIER_SWARM_REVIEW_PLAN_VERSION = 1;
 export declare const FRONTIER_SWARM_MERGE_PLAN_KIND = "frontier.swarm.merge-plan";
 export declare const FRONTIER_SWARM_MERGE_PLAN_VERSION = 1;
+export declare const FRONTIER_SWARM_MERGE_BUNDLE_KIND = "frontier.swarm.merge-bundle";
+export declare const FRONTIER_SWARM_MERGE_BUNDLE_VERSION = 1;
 export declare const FRONTIER_SWARM_DEFAULT_CODEX_COMPUTE_ID = "codex.gpt-5.5.xhigh";
 export declare const FRONTIER_SWARM_DEFAULT_MODEL = "gpt-5.5";
 export declare const FRONTIER_SWARM_DEFAULT_REASONING_EFFORT = "xhigh";
@@ -29,6 +39,9 @@ export type FrontierSwarmReasoningEffort = 'minimal' | 'low' | 'medium' | 'high'
 export type FrontierSwarmPolicyMode = 'advisory' | 'hard-file-ownership' | string;
 export type FrontierSwarmTaskStatus = 'open' | 'planned' | 'running' | 'blocked' | 'failed' | 'completed' | 'verified' | string;
 export type FrontierSwarmJobStatus = 'planned' | 'scheduled' | 'running' | 'blocked' | 'failed' | 'completed' | 'verified' | string;
+export type FrontierSwarmMergeReadiness = 'discovery-only' | 'patch-candidate' | 'verified-patch' | 'rejected' | 'blocked' | string;
+export type FrontierSwarmMergeDisposition = 'auto-mergeable' | 'needs-port' | 'discovery-only' | 'rejected' | 'blocked' | 'stale-against-head' | string;
+export type FrontierSwarmRiskLevel = 'low' | 'medium' | 'high' | 'unknown' | string;
 export interface FrontierSwarmComputeInput {
     id: string;
     kind?: FrontierSwarmComputeKind;
@@ -79,6 +92,25 @@ export interface FrontierSwarmLayer {
     tags: string[];
     metadata?: JsonObject;
 }
+export interface FrontierSwarmOwnershipRegionInput {
+    id: string;
+    title?: string;
+    description?: string;
+    globs?: readonly string[];
+    paths?: readonly string[];
+    selectors?: readonly string[];
+    owner?: string;
+    metadata?: unknown;
+}
+export interface FrontierSwarmOwnershipRegion {
+    id: string;
+    title: string;
+    description?: string;
+    globs: string[];
+    selectors: string[];
+    owner?: string;
+    metadata?: JsonObject;
+}
 export interface FrontierSwarmLaneInput {
     id: string;
     title?: string;
@@ -89,6 +121,9 @@ export interface FrontierSwarmLaneInput {
     allowedGlobs?: readonly string[];
     sharedReadOnly?: readonly string[];
     neverEdit?: readonly string[];
+    ownershipRegions?: readonly FrontierSwarmOwnershipRegionInput[];
+    capabilities?: readonly string[];
+    resourceRequirements?: FrontierSwarmResourceRequirementsInput;
     worktreePath?: string;
     evidencePrefix?: string;
     evidenceOutDirPrefix?: string;
@@ -107,6 +142,9 @@ export interface FrontierSwarmLane {
     allowedWrites: string[];
     sharedReadOnly: string[];
     neverEdit: string[];
+    ownershipRegions: FrontierSwarmOwnershipRegion[];
+    capabilities: string[];
+    resourceRequirements?: FrontierSwarmResourceRequirements;
     worktreePath?: string;
     evidencePrefix?: string;
     concurrencyKey: string;
@@ -131,6 +169,36 @@ export interface FrontierSwarmCommand {
     cwd?: string;
     metadata?: JsonObject;
 }
+export interface FrontierSwarmBrowserResourceInput {
+    required?: boolean;
+    portPool?: readonly (string | number)[];
+    profileDir?: string;
+    profileDirPrefix?: string;
+    maxConcurrency?: number;
+    headless?: boolean;
+    metadata?: unknown;
+}
+export interface FrontierSwarmBrowserResource {
+    required: boolean;
+    portPool: string[];
+    profileDir?: string;
+    profileDirPrefix?: string;
+    maxConcurrency?: number;
+    headless?: boolean;
+    metadata?: JsonObject;
+}
+export interface FrontierSwarmResourceRequirementsInput {
+    capabilities?: readonly string[];
+    resources?: Record<string, number>;
+    browser?: FrontierSwarmBrowserResourceInput;
+    metadata?: unknown;
+}
+export interface FrontierSwarmResourceRequirements {
+    capabilities: string[];
+    resources: Record<string, number>;
+    browser?: FrontierSwarmBrowserResource;
+    metadata?: JsonObject;
+}
 export interface FrontierSwarmPolicyInput {
     mode?: FrontierSwarmPolicyMode;
     defaultConcurrency?: number;
@@ -217,6 +285,11 @@ export interface FrontierSwarmTaskInput {
     targetRefs?: readonly string[];
     ownedFiles?: readonly string[];
     allowedWrites?: readonly string[];
+    ownershipRegions?: readonly FrontierSwarmOwnershipRegionInput[];
+    ownedRegions?: readonly string[];
+    changedRegions?: readonly string[];
+    capabilities?: readonly string[];
+    resourceRequirements?: FrontierSwarmResourceRequirementsInput;
     acceptance?: readonly string[];
     acceptanceChecks?: readonly ({
         id?: string;
@@ -249,6 +322,11 @@ export interface FrontierSwarmTask {
     sourceRefs: string[];
     targetRefs: string[];
     allowedWrites: string[];
+    ownershipRegions: FrontierSwarmOwnershipRegion[];
+    ownedRegions: string[];
+    changedRegions: string[];
+    capabilities: string[];
+    resourceRequirements?: FrontierSwarmResourceRequirements;
     acceptance: string[];
     verification: FrontierSwarmCommand[];
     evidenceCommand?: string;
@@ -286,6 +364,38 @@ export interface FrontierSwarmPlanFilter {
     limit?: number;
     compute?: string;
 }
+export interface FrontierSwarmSelectionPriorityInput {
+    statuses?: Record<string, number>;
+    workKinds?: Record<string, number>;
+    defaultStatusRank?: number;
+    defaultWorkKindRank?: number;
+    statusWeight?: number;
+    workKindWeight?: number;
+}
+export interface FrontierSwarmTaskSelectionInput extends FrontierSwarmPlanFilter {
+    workKinds?: readonly string[];
+    spreadLanes?: boolean;
+    includeOwnershipWarnings?: boolean;
+    assignSelectionPriority?: boolean;
+    priority?: FrontierSwarmSelectionPriorityInput;
+}
+export interface FrontierSwarmTaskSelectionEntry {
+    task: FrontierSwarmTask;
+    lane?: FrontierSwarmLane;
+    ownershipWarnings: string[];
+    selectionPriority: number;
+}
+export interface FrontierSwarmTaskSelectionSummary {
+    total: number;
+    byLane: Record<string, number>;
+    byWorkKind: Record<string, number>;
+    ownershipWarningCount: number;
+}
+export interface FrontierSwarmTaskSelection {
+    tasks: FrontierSwarmTask[];
+    entries: FrontierSwarmTaskSelectionEntry[];
+    summary: FrontierSwarmTaskSelectionSummary;
+}
 export interface FrontierSwarmPlanInput extends FrontierSwarmPlanFilter {
     id?: string;
     runId?: string;
@@ -330,6 +440,11 @@ export interface FrontierSwarmJob {
     allowedWrites: string[];
     sharedReadOnly: string[];
     neverEdit: string[];
+    ownershipRegions: FrontierSwarmOwnershipRegion[];
+    ownedRegions: string[];
+    changedRegions: string[];
+    capabilities: string[];
+    resourceRequirements?: FrontierSwarmResourceRequirements;
     worktreePath?: string;
     evidencePrefix?: string;
     concurrencyKey: string;
@@ -454,6 +569,8 @@ export interface FrontierSwarmScheduledJob {
     concurrencyKey: string;
     priority: number;
     dependsOn: string[];
+    capabilities: string[];
+    resourceRequirements?: FrontierSwarmResourceRequirements;
 }
 export interface FrontierSwarmBlockedJob extends FrontierSwarmScheduledJob {
     reasons: string[];
@@ -464,6 +581,8 @@ export interface FrontierSwarmRunningJob {
     lane: string;
     compute: string;
     concurrencyKey: string;
+    capabilities: string[];
+    resourceRequirements?: FrontierSwarmResourceRequirements;
 }
 export interface FrontierSwarmScheduleSummary {
     jobCount: number;
@@ -493,6 +612,110 @@ export interface FrontierSwarmLease {
     fencingToken: number;
     status: 'active' | 'expired' | 'released';
 }
+export type FrontierSwarmQueueJobStatus = 'ready' | 'leased' | 'running' | 'completed' | 'failed' | 'blocked' | 'retrying' | 'dead-letter' | string;
+export interface FrontierSwarmQueueJobInput {
+    jobId: string;
+    taskId?: string;
+    runId?: string;
+    status?: FrontierSwarmQueueJobStatus;
+    lane?: string;
+    compute?: string;
+    concurrencyKey?: string;
+    priority?: number;
+    attempts?: number;
+    maxAttempts?: number;
+    availableAt?: number;
+    lease?: FrontierSwarmLease;
+    lastError?: string;
+    metadata?: unknown;
+}
+export interface FrontierSwarmQueueJob {
+    jobId: string;
+    taskId?: string;
+    runId?: string;
+    status: FrontierSwarmQueueJobStatus;
+    lane?: string;
+    compute?: string;
+    concurrencyKey?: string;
+    priority: number;
+    attempts: number;
+    maxAttempts: number;
+    availableAt?: number;
+    lease?: FrontierSwarmLease;
+    lastError?: string;
+    metadata?: JsonObject;
+}
+export interface FrontierSwarmQueueSnapshotInput {
+    id?: string;
+    plan: FrontierSwarmPlan;
+    run?: FrontierSwarmRun;
+    jobs?: readonly FrontierSwarmQueueJobInput[];
+    leases?: readonly FrontierSwarmLease[];
+    generatedAt?: number;
+    metadata?: unknown;
+}
+export interface FrontierSwarmQueueSnapshot {
+    kind: typeof FRONTIER_SWARM_QUEUE_SNAPSHOT_KIND;
+    version: typeof FRONTIER_SWARM_QUEUE_SNAPSHOT_VERSION;
+    id: string;
+    planId: string;
+    runId: string;
+    generatedAt: number;
+    jobs: FrontierSwarmQueueJob[];
+    byStatus: Record<string, string[]>;
+    byLane: Record<string, string[]>;
+    leases: FrontierSwarmLease[];
+    metadata?: JsonObject;
+    summary: {
+        jobCount: number;
+        leaseCount: number;
+        readyCount: number;
+        leasedCount: number;
+        completedCount: number;
+        failedCount: number;
+        deadLetterCount: number;
+    };
+}
+export interface FrontierSwarmLeaseRenewalInput {
+    lease: FrontierSwarmLease;
+    now?: number;
+    leaseMs?: number;
+    status?: FrontierSwarmLease['status'];
+}
+export interface FrontierSwarmQueueAdapter {
+    snapshot(): FrontierSwarmQueueSnapshot | Promise<FrontierSwarmQueueSnapshot>;
+    enqueue?(snapshot: FrontierSwarmQueueSnapshot): FrontierSwarmQueueSnapshot | Promise<FrontierSwarmQueueSnapshot>;
+    lease?(input: FrontierSwarmLeaseInput): readonly FrontierSwarmLease[] | Promise<readonly FrontierSwarmLease[]>;
+    renew?(input: FrontierSwarmLeaseRenewalInput): FrontierSwarmLease | Promise<FrontierSwarmLease>;
+    complete?(result: FrontierSwarmJobResultInput): FrontierSwarmQueueSnapshot | Promise<FrontierSwarmQueueSnapshot>;
+}
+export interface FrontierSwarmRunCheckpointInput {
+    run: FrontierSwarmRun;
+    sequence?: number;
+    savedAt?: number;
+    metadata?: unknown;
+}
+export interface FrontierSwarmRunCheckpoint {
+    kind: typeof FRONTIER_SWARM_RUN_CHECKPOINT_KIND;
+    version: typeof FRONTIER_SWARM_RUN_CHECKPOINT_VERSION;
+    id: string;
+    runId: string;
+    planId: string;
+    sequence: number;
+    savedAt: number;
+    status: FrontierSwarmJobStatus;
+    eventCount: number;
+    resultCount: number;
+    hash: string;
+    metadata?: JsonObject;
+}
+export interface FrontierSwarmRunStoreAdapter {
+    loadRun(runId: string): FrontierSwarmRun | undefined | Promise<FrontierSwarmRun | undefined>;
+    saveRun(run: FrontierSwarmRun, checkpoint?: FrontierSwarmRunCheckpoint): void | Promise<void>;
+    appendEvents?(runId: string, events: readonly FrontierSwarmEventInput[]): void | Promise<void>;
+    appendResults?(runId: string, results: readonly FrontierSwarmJobResultInput[]): void | Promise<void>;
+    checkpoint?(run: FrontierSwarmRun): FrontierSwarmRunCheckpoint | Promise<FrontierSwarmRunCheckpoint>;
+}
 export interface FrontierSwarmArtifactInput {
     jobId: string;
     path: string;
@@ -634,16 +857,73 @@ export interface FrontierSwarmEvent {
     data?: JsonValue;
     metadata?: JsonObject;
 }
+export type FrontierSwarmMailboxScope = 'global' | 'lane' | 'job' | string;
+export interface FrontierSwarmMailboxInput {
+    id?: string;
+    runId?: string;
+    scope?: FrontierSwarmMailboxScope;
+    lane?: string;
+    jobId?: string;
+    path?: string;
+    eventTypes?: readonly string[];
+    appendOnly?: boolean;
+    metadata?: unknown;
+}
+export interface FrontierSwarmMailbox {
+    kind: typeof FRONTIER_SWARM_MAILBOX_KIND;
+    version: typeof FRONTIER_SWARM_MAILBOX_VERSION;
+    id: string;
+    runId?: string;
+    scope: FrontierSwarmMailboxScope;
+    lane?: string;
+    jobId?: string;
+    path?: string;
+    eventTypes: string[];
+    appendOnly: boolean;
+    metadata?: JsonObject;
+}
+export interface FrontierSwarmEventStreamInput {
+    id?: string;
+    runId?: string;
+    root?: string;
+    lanes?: readonly (string | FrontierSwarmLaneInput | FrontierSwarmLane)[];
+    eventTypes?: readonly string[];
+    appendOnly?: boolean;
+    metadata?: unknown;
+}
+export interface FrontierSwarmEventStream {
+    kind: typeof FRONTIER_SWARM_EVENT_STREAM_KIND;
+    version: typeof FRONTIER_SWARM_EVENT_STREAM_VERSION;
+    id: string;
+    runId?: string;
+    root?: string;
+    appendOnly: boolean;
+    global: FrontierSwarmMailbox;
+    lanes: Record<string, FrontierSwarmMailbox>;
+    eventTypes: string[];
+    metadata?: JsonObject;
+    summary: {
+        mailboxCount: number;
+        laneCount: number;
+        eventTypeCount: number;
+    };
+}
 export interface FrontierSwarmJobResultInput {
     jobId: string;
     status?: FrontierSwarmJobStatus;
+    mergeReadiness?: FrontierSwarmMergeReadiness;
     startedAt?: number;
     finishedAt?: number;
     exitCode?: number;
     signal?: string;
     changedPaths?: readonly string[];
+    changedRegions?: readonly string[];
     ownershipViolations?: readonly string[];
     evidencePaths?: readonly string[];
+    patchPath?: string;
+    queueItemIds?: readonly string[];
+    riskLevel?: FrontierSwarmRiskLevel;
+    mergeDisposition?: FrontierSwarmMergeDisposition;
     verification?: readonly FrontierSwarmVerificationResultInput[];
     lastMessage?: string;
     error?: unknown;
@@ -672,14 +952,20 @@ export interface FrontierSwarmVerificationResult {
 export interface FrontierSwarmJobResult {
     jobId: string;
     status: FrontierSwarmJobStatus;
+    mergeReadiness: FrontierSwarmMergeReadiness;
     startedAt?: number;
     finishedAt?: number;
     durationMs?: number;
     exitCode?: number;
     signal?: string;
     changedPaths: string[];
+    changedRegions: string[];
     ownershipViolations: string[];
     evidencePaths: string[];
+    patchPath?: string;
+    queueItemIds: string[];
+    riskLevel: FrontierSwarmRiskLevel;
+    mergeDisposition: FrontierSwarmMergeDisposition;
     verification: FrontierSwarmVerificationResult[];
     lastMessage?: string;
     error?: string;
@@ -691,6 +977,57 @@ export interface FrontierSwarmOwnershipReport {
     allowedWrites: string[];
     violations: string[];
 }
+export interface FrontierSwarmMergeBundleInput {
+    id?: string;
+    runId?: string;
+    planId?: string;
+    job?: FrontierSwarmJob;
+    result: FrontierSwarmJobResult | FrontierSwarmJobResultInput;
+    patchPath?: string;
+    patchHash?: string;
+    evidencePaths?: readonly string[];
+    queueItemIds?: readonly string[];
+    riskLevel?: FrontierSwarmRiskLevel;
+    disposition?: FrontierSwarmMergeDisposition;
+    staleAgainstHead?: boolean;
+    branchName?: string;
+    commit?: string;
+    metadata?: unknown;
+    generatedAt?: number;
+}
+export interface FrontierSwarmMergeBundle {
+    kind: typeof FRONTIER_SWARM_MERGE_BUNDLE_KIND;
+    version: typeof FRONTIER_SWARM_MERGE_BUNDLE_VERSION;
+    id: string;
+    runId?: string;
+    planId?: string;
+    jobId: string;
+    taskId?: string;
+    lane?: string;
+    title?: string;
+    generatedAt: number;
+    status: FrontierSwarmJobStatus;
+    mergeReadiness: FrontierSwarmMergeReadiness;
+    disposition: FrontierSwarmMergeDisposition;
+    riskLevel: FrontierSwarmRiskLevel;
+    autoMergeable: boolean;
+    changedPaths: string[];
+    changedRegions: string[];
+    ownedFilesTouched: string[];
+    allowedWrites: string[];
+    ownershipViolations: string[];
+    patchPath?: string;
+    patchHash?: string;
+    evidencePaths: string[];
+    commandsPassed: FrontierSwarmVerificationResult[];
+    commandsFailed: FrontierSwarmVerificationResult[];
+    queueItemIds: string[];
+    branchName?: string;
+    commit?: string;
+    staleAgainstHead: boolean;
+    reasons: string[];
+    metadata?: JsonObject;
+}
 export interface FrontierSwarmProof {
     kind: typeof FRONTIER_SWARM_PROOF_KIND;
     version: typeof FRONTIER_SWARM_PROOF_VERSION;
@@ -708,10 +1045,20 @@ export declare function defineSwarmTasks(input?: readonly FrontierSwarmTaskInput
 export declare function compileSwarm(input: FrontierSwarmManifest | FrontierSwarmManifestInput): FrontierSwarmCompiled;
 export declare function validateSwarmManifest(input: FrontierSwarmManifest | FrontierSwarmManifestInput): FrontierSwarmValidation;
 export declare function createSwarmPlan(manifestInput: FrontierSwarmManifest | FrontierSwarmManifestInput, taskInput: readonly FrontierSwarmTaskInput[] | FrontierSwarmTaskSetInput | readonly FrontierSwarmTask[], options?: FrontierSwarmPlanInput): FrontierSwarmPlan;
+export declare function createSwarmTaskSelection(manifestInput: FrontierSwarmManifest | FrontierSwarmManifestInput, taskInput: readonly FrontierSwarmTaskInput[] | FrontierSwarmTaskSetInput | readonly FrontierSwarmTask[], options?: FrontierSwarmTaskSelectionInput): FrontierSwarmTaskSelection;
 export declare function createSwarmRun(input: FrontierSwarmRunInput): FrontierSwarmRun;
 export declare function recordSwarmEvent(runInput: FrontierSwarmRun, eventInput: FrontierSwarmEventInput): FrontierSwarmRun;
+export declare function createSwarmMailbox(input?: FrontierSwarmMailboxInput): FrontierSwarmMailbox;
+export declare function createSwarmEventStream(input?: FrontierSwarmEventStreamInput): FrontierSwarmEventStream;
+export declare function routeSwarmEventToMailboxes(stream: FrontierSwarmEventStream, eventInput: FrontierSwarmEvent | FrontierSwarmEventInput): FrontierSwarmMailbox[];
 export declare function completeSwarmJob(runInput: FrontierSwarmRun, resultInput: FrontierSwarmJobResultInput): FrontierSwarmRun;
 export declare function checkSwarmOwnership(job: FrontierSwarmJob, changedPaths: readonly string[]): FrontierSwarmOwnershipReport;
+export declare function resolveSwarmChangedRegions(job: FrontierSwarmJob, changedPaths: readonly string[]): string[];
+export declare function classifySwarmMergeReadiness(result: FrontierSwarmJobResultInput | FrontierSwarmJobResult): FrontierSwarmMergeReadiness;
+export declare function classifySwarmMergeDisposition(result: FrontierSwarmJobResultInput | FrontierSwarmJobResult, input?: {
+    staleAgainstHead?: boolean;
+}): FrontierSwarmMergeDisposition;
+export declare function createSwarmMergeBundle(input: FrontierSwarmMergeBundleInput): FrontierSwarmMergeBundle;
 export declare function resolveSwarmCompute(manifestInput: FrontierSwarmManifest | FrontierSwarmManifestInput, taskInput: FrontierSwarmTask | FrontierSwarmTaskInput): FrontierSwarmCompute;
 export declare function createSwarmProof(input: FrontierSwarmManifest | FrontierSwarmPlan | FrontierSwarmRun, options?: {
     generatedAt?: number;
@@ -720,6 +1067,9 @@ export declare function createSwarmProof(input: FrontierSwarmManifest | Frontier
 }): FrontierSwarmProof;
 export declare function createSwarmSchedule(input: FrontierSwarmPlan | FrontierSwarmScheduleInput): FrontierSwarmSchedule;
 export declare function createSwarmLeases(input: FrontierSwarmLeaseInput): FrontierSwarmLease[];
+export declare function renewSwarmLease(input: FrontierSwarmLeaseRenewalInput): FrontierSwarmLease;
+export declare function createSwarmQueueSnapshot(input: FrontierSwarmQueueSnapshotInput): FrontierSwarmQueueSnapshot;
+export declare function createSwarmRunCheckpoint(input: FrontierSwarmRun | FrontierSwarmRunCheckpointInput): FrontierSwarmRunCheckpoint;
 export declare function checkSwarmBudget(job: FrontierSwarmJob, usageInput: FrontierSwarmUsageInput): FrontierSwarmBudgetDecision;
 export declare function createSwarmArtifactIndex(input: FrontierSwarmRun | {
     run?: FrontierSwarmRun;