@shapeshift-labs/frontier-swarm-codex

v0.5.117

Published

2 days ago

Node Codex CLI runner adapter for Frontier swarm plans with resource allocation.

0High
0Medium
0Low

shapeshift-labs

frontier swarm codex agents cli worktree evidence

@shapeshift-labs/frontier-swarm-codex

Node Codex CLI runner adapter for Frontier swarm plans.

frontier-swarm-codex executes @shapeshift-labs/frontier-swarm plans with the Codex CLI. It owns Node process spawning, prompt rendering, worktree/snapshot workspace setup, command shaping, JSONL output capture, last-message capture, optional verification commands, changed-path ownership checks, and swarm result/proof artifacts.

The default swarm compute profile records gpt-5.5 with model_reasoning_effort="xhigh" for planning. The Codex CLI invocation defaults to the local Codex config instead of forwarding planned model flags, because model availability and accepted flag values vary by Codex binary and account. Pass --model ..., --model-policy plan, or modelPolicy: 'plan' when a runner should force the planned profile. The pure frontier-swarm package stays runtime-neutral.

Related Packages

The published Frontier package family is generated from one shared package catalog so READMEs stay in sync across packages:

@shapeshift-labs/frontier: Core JSON diff/apply, compact patch tuples, JSON Pointer, equality, clone, validation, Unicode helpers, and tiny dependency-free runtime budget/scheduler primitives.
@shapeshift-labs/frontier-query: Shared query-key, selector path, condition, entity identity, and table-shape primitives.
@shapeshift-labs/frontier-codec: Patch serialization, binary frames, canonical JSON, and patch-history codecs.
@shapeshift-labs/frontier-engine: Stateful planned diff engine, adaptive profiles, schema plans, and engine-level history helpers.
@shapeshift-labs/frontier-state: Patch-routed app-state subscriptions, owned commits, maintained views, and path mapping.
@shapeshift-labs/frontier-dataflow: Serializable incremental dataflow and materialized-view graphs for Frontier apps, including selectors, dependency DAGs, filters, joins, aggregations, stale paths, recompute budgets, output patches, provenance records, and proof of why derived views changed.
@shapeshift-labs/frontier-state-cache: Normalized query-result cache with entity/query watchers, persistence, change logs, optimistic layers, scheduled persistence, and mutation bridge.
@shapeshift-labs/frontier-state-cache-idb: IndexedDB persistence adapter for Frontier state-cache snapshots and durable change logs.
@shapeshift-labs/frontier-state-cache-file: Structured file persistence adapter for Frontier state-cache snapshots and change logs.
@shapeshift-labs/frontier-state-cache-sql: SQL persistence adapter for Frontier state-cache snapshots and change logs.
@shapeshift-labs/frontier-schema: JSON Schema validation, Frontier profile generation, CloudEvent envelopes, and query/table schema helpers.
@shapeshift-labs/frontier-migrations: Boundary-first data migrations, import normalization, plugin/API version mapping, versioned envelopes, graph diagnostics, patch path rewrites, dry-run reports, and current-shape rehydration.
@shapeshift-labs/frontier-event-log: Bounded event logs, replay cursors, consumer acknowledgements, keyed compaction, checkpoints, and Frontier patch event records.
@shapeshift-labs/frontier-inspect: Cross-package inspection/evidence bundles, registry graph snapshots, feature/resource impact reports, timeline/event normalization, redaction, JSONL import/export, and AI-readable app feature maps.
@shapeshift-labs/frontier-scheduler: Deterministic work scheduling, lanes, cancellation, backpressure, frame policies, replay snapshots, and work graphs.
@shapeshift-labs/frontier-logging: Opt-in structured logging, browser telemetry, scheduled sinks, file sinks, exporters, benchmark traces, and Frontier patch/update summaries.
@shapeshift-labs/frontier-mutation: Explicit mutation and selector plans compiled to Frontier patches or CRDT operations.
@shapeshift-labs/frontier-effects: Serializable effect descriptors and resource graphs for Frontier apps, including fetch, storage, timers, navigation, workers, clipboard, broadcast, WebSocket, stream, policy metadata, runtime records, redaction, JSONL, proof helpers, and registry graph output.
@shapeshift-labs/frontier-auth: Frontier-native auth contracts for providers, sessions, profile completeness, route and resource gates, account-linking policy, token issue/verify plans, runtime grants, audit events, registry graphs, lint resources, and auth evidence without owning app secrets, crypto, storage, or provider SDKs.
@shapeshift-labs/frontier-policy: Serializable policy and capability decisions for Frontier apps, effects, views, sync, routes, traces, and AI tools.
@shapeshift-labs/frontier-flags: Patchable policy-aware feature flag state for Frontier apps, including targeting, deterministic rollouts, experiment variants, kill switches, exposure records, audit logs, and replay evidence.
@shapeshift-labs/frontier-tools: Serializable app action/tool manifests for AI-operable Frontier apps, including availability, validation, dry-run plans, patch previews, effect/tool constraints, execution records, rollback links, and registry graph output.
@shapeshift-labs/frontier-sandbox: Runtime-agnostic sandbox contracts for Frontier patch-producing actions, including manifests, declared reads/writes/capabilities, host-validated patch/effect/event/log results, dynamic source modules, source event replay, and structural runtime adapters.
@shapeshift-labs/frontier-sandbox-quickjs: QuickJS/WebAssembly runtime adapter for Frontier sandbox actions, including invocation/runtime isolation modes, deadline and memory limits, dynamic source execution, and patch/effect result normalization.
@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: 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: 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: Hierarchical swarm plans, lanes, compute profiles, ownership policy, semantic ownership regions, task queues, event streams, run records, merge bundles, merge indexes, queue overlays, merge admission, coordinator dashboards, changed-path checks, and proof artifacts for Frontier agent work.
@shapeshift-labs/frontier-lang-kernel: Runtime-neutral semantic source graph, type/lattice/extern declarations, patch bundles, replay, hashing, evidence records, and merge-admission kernel for Frontier Lang.
@shapeshift-labs/frontier-lang-parser: Dependency-light Frontier Lang parser for modules, entities, state, actions, effects, types, externs, targets, and lattice declarations.
@shapeshift-labs/frontier-lang-checker: Checker and diagnostics for Frontier Lang semantic documents, including type symbols, effects, regions, lattice laws, CRDT metadata, and patch evidence.
@shapeshift-labs/frontier-lang-typescript: TypeScript projection adapter for Frontier Lang semantic documents, including type/entity/state/action/extern declarations and CRDT lattice descriptors.
@shapeshift-labs/frontier-lang-javascript: JavaScript projection adapter for Frontier Lang semantic documents, including ESM action stubs and schema/lattice descriptors.
@shapeshift-labs/frontier-lang-rust: Rust projection adapter for Frontier Lang semantic documents, including structs, aliases, and action stubs.
@shapeshift-labs/frontier-lang-python: Python projection adapter for Frontier Lang semantic documents, including dataclasses, typed patch records, and action stubs.
@shapeshift-labs/frontier-lang-c: C header projection adapter for Frontier Lang semantic documents, including structs and action prototypes.
@shapeshift-labs/frontier-lang-compiler: Compiler facade for Frontier Lang source documents, including parse, check, hash, diagnostics, universal AST envelopes, proof/paradigm semantic summaries, projection to TypeScript, JavaScript, Rust, Python, and C, and native source-import adapters for semantic merge evidence.
@shapeshift-labs/frontier-lang-swift: Swift source-language importer package for Frontier Lang semantic documents, including package-level metadata, SwiftSyntax adapter helpers, native import results, and semantic sidecar generation for SwiftSyntax/SwiftParser-shaped syntax trees.
@shapeshift-labs/frontier-lang-kotlin: Kotlin PSI source-language importer package for Frontier Lang semantic documents, including package-level metadata, Kotlin PSI adapter helpers, native import results, and semantic sidecar generation for Kotlin PSI/KtFile-shaped syntax trees.
@shapeshift-labs/frontier-lang-java: Java source-language importer package for Frontier Lang semantic documents, including package-level metadata, Java AST adapter helpers, native import results, and semantic sidecar generation for javac/JDT/JavaParser-shaped ASTs.
@shapeshift-labs/frontier-lang-go: Go source-language importer package for Frontier Lang semantic documents, including package-level metadata, Go AST adapter helpers, native import results, and semantic sidecar generation for go/ast File or Package trees.
@shapeshift-labs/frontier-lang-csharp: C# Roslyn source-language importer package for Frontier Lang semantic documents, including package-level metadata, Roslyn adapter helpers, native import results, and semantic sidecar generation for SyntaxTree/SyntaxNode-shaped ASTs.
@shapeshift-labs/frontier-lang-clang: Clang AST source-language importer package for Frontier Lang semantic documents, including package-level metadata, Clang AST JSON adapter helpers, native import results, and semantic sidecar generation for C/C++ translation units.
@shapeshift-labs/frontier-lang-cli: Command line interface for parsing, checking, hashing, emitting, native source import/projection, semantic slicing, and corpus roundtrip evidence for Frontier Lang projects.
@shapeshift-labs/frontier-lang: Umbrella package for Frontier Lang kernel, parser, checker, compiler facade, universal AST helpers, projection adapters, and source-language importer adapters.
@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: 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: Patch-native rate limit buckets for Frontier KV, including fixed windows, sliding windows, token buckets, deterministic refill, consume evidence, and reset records.
@shapeshift-labs/frontier-kv-file: Node file persistence adapter for Frontier KV snapshots and append-only JSONL event logs, including atomic writes, compaction, replay loading, and adapter evidence.
@shapeshift-labs/frontier-kv-idb: IndexedDB persistence adapter for Frontier KV snapshots and event logs, with structural IDB interfaces, upgrade planning, compact event storage, and replay loading.
@shapeshift-labs/frontier-kv-redis: Redis-compatible command planning and structural client adapter for Frontier KV operations, including key mapping, TTL commands, optimistic CAS scripts, and replay evidence without bundling Redis drivers.
@shapeshift-labs/frontier-kv-server: Small Node HTTP server adapter for Frontier KV, including request planning, JSON endpoints for get/set/delete/scan/batch, optional rate-limit hooks, and replayable response evidence.
@shapeshift-labs/frontier-assets: Serializable asset and content provenance graphs for Frontier apps, including source files, generated variants, thumbnails, LOD chunks, shader/material dependencies, transforms, hashes, owners, runtime consumers, review plans, registry graph output, and impact queries.
@shapeshift-labs/frontier-blueprint: Serializable Blueprint/Prefab flyweight templates for Frontier apps, including parameterized instantiation, deterministic ID/path remapping, compact overrides, variants, effective-state materialization, scene/state patch emission, dependency metadata, and registry graph output.
@shapeshift-labs/frontier-triggers: Capability-gated event trigger registry, scoped event envelopes, listener/reaction rules, structured rejection, deterministic event-to-action scheduling, replay/provenance records, and registry graph output.
@shapeshift-labs/frontier-virtual: DOM-neutral virtualization, layout providers, range materialization, grids, spatial/frustum indexes, patch invalidation, camera anchors, and serializable layout state.
@shapeshift-labs/frontier-table: Renderer-neutral data grid and table primitives for Frontier apps, including stable row identity, sorting, filtering, selection, virtual ranges, patch-driven edits, cache/dataflow descriptors, and CRDT-compatible row and cell operation frames.
@shapeshift-labs/frontier-scene: Patch-native 2D/3D scene graph, transform propagation, bounds queries, virtual/culling adapters, spatial invalidation, and camera/frustum materialization.
@shapeshift-labs/frontier-pathfinding: Patch-native grid pathfinding, typed-array A*/Dijkstra search, flow fields, connected components, line-of-sight smoothing, dirty-cell invalidation, and scheduler-friendly path jobs.
@shapeshift-labs/frontier-lod: Patch-native level-of-detail and significance selection for rendering and computation workloads, compact typed hot paths, multi-observer selection, budget degradation, materialization frames, and scheduler work plans.
@shapeshift-labs/frontier-route: DOM-neutral app/game route resources, route and scene manifests, match/resolve/transition planning, dependency metadata, sessions, registry graph output, and impact queries.
@shapeshift-labs/frontier-trace: Serializable traces, spans, events, causal links, W3C trace context helpers, timeline/resource/path queries, critical-path analysis, registry graph output, JSONL/proof helpers, Chrome trace export, and redaction for app-wide feature observability.
@shapeshift-labs/frontier-manifest: Build/static feature manifests for owners, routes, actions, states, migrations, tests, source files, assets, resources, tasks, dependency metadata, registry graph output, feature maps, JSONL export, and impact queries.
@shapeshift-labs/frontier-view: Renderer-neutral view manifests, type defaults, validation frames, action bindings, visual channels, virtual/LOD hints, and data-to-representation mapping for Frontier apps.
@shapeshift-labs/frontier-icons: Renderer-neutral icon records, icon sets, lookup aliases, SVG frames, string rendering, and registry evidence for Frontier apps.
@shapeshift-labs/frontier-design: Renderer-neutral design-system tokens, semantic roles, recipes, target style frames, CSS variable output, and registry graph evidence for Frontier apps.
@shapeshift-labs/frontier-canvas: Renderer-neutral infinite canvas surfaces for Frontier apps, including camera and viewport math, pan/zoom plans, grid materialization, snapping, hit testing, selection handles, extensible tool dispatch, frame records, registry graph output, and impact/proof helpers.
@shapeshift-labs/frontier-canvas-tools: Renderer-neutral editor tools, state machines, transform handles, permissions, async records, and AI action bridges for Frontier canvas surfaces.
@shapeshift-labs/frontier-dnd: Renderer-neutral drag-and-drop sessions, sensor descriptors, collision ranking, drop planning, reorder patches, state partitioning, and registry evidence for Frontier apps.
@shapeshift-labs/frontier-dom: Patch-native DOM and host renderer bindings, manifest hydration, JSX runtime/compiler helpers, SSR, devtools, and logging bridges.
@shapeshift-labs/frontier-playwright: Playwright/headless automation probes for Frontier state, DOM, devtools, marks, and timeline queries.
@shapeshift-labs/frontier-test: Serializable test/spec evidence manifests for Frontier apps, including fixtures, commands, expected patches/effects/routes/policies, coverage declarations, run plans, run records, report adapters, replay proofs, fuzzers, benchmarks, registry graph output, and impact queries.
@shapeshift-labs/frontier-fixtures: Deterministic fixture and scenario generation for Frontier apps, including schema-valid sample state, related entity collections, actor personas, route states, replay-verified patch streams, event records, JSONL bundles, and evidence summaries.
@shapeshift-labs/frontier-component-preview: Frontier-native component preview books, generated preview manifests, stateful variants, Vite virtual modules, standalone browser preview shells, inspector bridges, and preview harness evidence for Frontier apps.
@shapeshift-labs/frontier-documentation: Frontier-native documentation manifests, generated documentation books, package/API/source discovery, Vite virtual modules, standalone browser docs shells, inspector bridges, search indexes, and documentation harness evidence for Frontier apps and packages.
@shapeshift-labs/frontier-ast-walk: Dependency-light source graph, import/export/declaration/call analysis, Frontier package-use discovery, and business-logic placement findings for Frontier tools, apps, docs, fuzzers, benchmarks, and agent evidence.
@shapeshift-labs/frontier-history: Serializable temporal explanation and causality records for Frontier apps, including field-change explanations, action/workflow/policy/effect/trace/test provenance, audit windows, undo planning, registry/provenance graph output, JSONL replay bundles, and proof hashes.
@shapeshift-labs/frontier-application: Serializable whole-application graph and impact queries for Frontier apps, including features, owners, packages, routes, views, actions, mutations, state paths, effects, workers, assets, tests, traces, policies, workflows, migrations, benchmarks, registry graph output, feature maps, JSONL bundles, and proof hashes.
@shapeshift-labs/frontier-linter: Serializable Frontier lint rules, diagnostics, fixes, reports, and fast rule execution for package catalogs, registry graphs, application maps, manifests, traces, policies, workflows, workers, assets, tests, benchmarks, and source snippets.
@shapeshift-labs/frontier-framework: High-level app framework package for Frontier applications, including configuration, CLI scaffolding, Vite builds, monorepo layout, TSX route builds, split frontend/backend deploy artifacts, backend-neutral Fetch handler and sync transport contracts, runtime data-source migrations, devtools, harness gates, agent MCP/tool manifests, CI evidence gates, workflow manifests, SARIF/linter output, replay scripts, and evidence manifest output.
@shapeshift-labs/frontier-crdt: Native CRDT documents, update tooling, awareness, branches, conflict introspection, version frames, and undo.
@shapeshift-labs/frontier-crdt-sync: CRDT sync endpoints, repo/storage/provider contracts, scheduled sync work, document URLs, local networks, model checking, forensics, and text binding contracts.
@shapeshift-labs/frontier-crdt-websocket: WebSocket client/server transports for Frontier CRDT sync providers.
@shapeshift-labs/frontier-react: React external-store hooks and adapters for Frontier state, cache, and CRDT surfaces.
@shapeshift-labs/frontier-richtext: Rich text Delta normalization/application, marks, embeds, ranges, and cursor/selection transforms for local editor integrations.
@shapeshift-labs/frontier-realtime: Shared realtime command, tick, snapshot, prediction, reconciliation, interpolation, rollback, message, and delta primitives.
@shapeshift-labs/frontier-realtime-server: Authoritative realtime room, tick, command validation, rate-limit, session, and snapshot-history runtime.
@shapeshift-labs/frontier-realtime-websocket: WebSocket client, wire, and Node room-server transport for Frontier realtime.
@shapeshift-labs/frontier-game: Game-facing entity, component, player, room, ownership, spatial interest, rollback, physics, and replication helpers above realtime.
@shapeshift-labs/loom: Repo-level semantic collaboration CLI for .loom workspaces, including init, scan, status, graph snapshots, projection plans, Frontier Lang delegation, Frontier Swarm delegation, and Frontier Framework delegation.

Package source repositories:

Install

npm install @shapeshift-labs/frontier-swarm-codex

CLI

frontier-swarm-codex plan \
  --manifest inkwell/agent-ownership.json \
  --tasks inkwell/parity-work-queue.json \
  --outDir agent-runs/codex-swarm/plan

frontier-swarm-codex run \
  --manifest inkwell/agent-ownership.json \
  --tasks inkwell/parity-work-queue.json \
  --max-concurrency 4 \
  --workspace copy \
  --include AGENTS.md,package.json,inkwell \
  --exclude node_modules,dist,agent-runs \
  --link-path packages \
  --link-node-modules true \
  --semantic-import \
  --sandbox workspace-write

frontier-swarm doctor \
  --semantic-import \
  --out agent-runs/codex-swarm/dependency-health.json

frontier-swarm resume \
  --run agent-runs/codex-swarm/run-1 \
  --outDir agent-runs/codex-swarm/run-1-resume \
  --max-concurrency 4

frontier-swarm stop --run agent-runs/codex-swarm/run-1

frontier-swarm collect \
  --run agent-runs/codex-swarm/run-1 \
  --outDir agent-runs/codex-swarm/run-1/collected \
  --branch-prefix codex/swarm-slice

frontier-swarm repair-links \
  --root . \
  --package-root packages \
  --package-root .. \
  --scope @shapeshift-labs \
  --exclude-package @shapeshift-labs/frontier-swarm,@shapeshift-labs/frontier-swarm-codex,@shapeshift-labs/frontier-lang \
  --write

API

import {
  createCodexSwarmPlan,
  runCodexSwarm
} from '@shapeshift-labs/frontier-swarm-codex';

const plan = createCodexSwarmPlan({ manifest, tasks });

await runCodexSwarm(plan, {
  outDir: 'agent-runs/codex-swarm/run-1',
  maxConcurrency: 4,
  modelPolicy: 'config-default',
  workspace: {
    mode: 'copy',
    root: '../agent-workspaces',
    includes: ['AGENTS.md', 'package.json', 'snes'],
    excludes: ['node_modules', 'dist', 'agent-runs', 'snes/test/roms'],
    linkPaths: ['packages'],
    linkNodeModules: true,
    replace: true
  }
});

App-specific adapters should keep orchestration inside this package and use hooks for local policy. prepareJobWorkspace can link generated package artifacts or shared fixtures, renderJobPrompt can append product-specific migration rules, changedPathFilter can hide runner-owned symlinks from ownership checks, and onJobStarted/onJobFinished/onSwarmFinished can mirror lifecycle records into project-specific JSONL streams.

Use modelPolicy: 'config-default' for portable swarms that should respect each machine's Codex config. Use modelPolicy: 'plan' only when the installed Codex CLI and account are known to accept the planned model IDs. approval: 'full-auto' and --approval-policy full-auto are normalized to the current --ask-for-approval never spelling.

Pass --semantic-import or semanticImport: true to write a semantic-imports.json sidecar for changed source files. The sidecar uses the optional @shapeshift-labs/frontier-lang dependency to import supported native sources into Frontier Lang universal ASTs, summarize source maps/losses/semantic indexes/dependency relations/universal AST layers/proof-spec records/paradigm semantics records, record native compile/projection readiness when available, and attach semantic merge-candidate metadata to each worker merge bundle. Use --semantic-import-include, --semantic-import-exclude, --semantic-import-max-files, and --semantic-import-max-bytes to keep the import pass scoped. In copied/snapshot workspaces, semantic import selects changed source paths plus concrete task source/target refs so a worker can still produce symbols, call/use dependency edges, ownership regions, universal AST layer quality, proof obligation status, paradigm/lowering hints, and patch hints when changed-path collection is filtered. It snapshots selected worker sources before execution as baseSource.source: "workspace-snapshot" and records current coordinator/git text as headSource, letting semantic edit scripts distinguish base text, worker text, and current head when classifying portable, already-applied, stale, and conflicting edits. When Lang exposes semantic edit projection, the sidecar also records whether projected source reproduced the worker file hash; missing, blocked, mismatched, or unknown projection checks downgrade auto-merge readiness. Include globs support ** and can match stripped copied-workspace suffixes, so a parent-root glob such as snes/packages/domain/src/**/*.js still matches a minimal workspace rooted at packages/domain or src. Use --semantic-import-expected when zero selected/imported files or zero universal AST layers should be called out in patch intent and collection dashboards. Patch intent, collected evidence, coordinator query, compact dashboard, and tournament query output include selected/eligible/imported/candidate counts, symbols, ownership regions, inferred lineage move/rename/delete counts when supplied by Lang or worker evidence, projection match/mismatch counts, quality warnings, expectedSatisfied, and expectedMissingReasonCodes so coordinators can sort empty or stale semantic sidecars without opening every worker directory.

The sidecar source records are intentionally tiny and stable:

{
  "path": "src/runtime/apply.ts",
  "baseSource": {
    "source": "workspace-snapshot",
    "path": "src/runtime/apply.ts",
    "sha256": "base-text-sha256",
    "text": "export function apply() { return 'old'; }"
  },
  "headSource": {
    "source": "coordinator-workspace",
    "path": "src/runtime/apply.ts",
    "sha256": "head-text-sha256",
    "text": "export function apply() { return 'current'; }"
  }
}

baseSource.source is usually workspace-snapshot for copied/snapshot workers and may be coordinator-workspace or git-head when the runner has a direct baseline. headSource.source is coordinator-workspace or git-head; it is omitted only when current head text is unavailable. Downstream tools should treat path, source, sha256, and text as the compatibility contract for semantic edit-script admission.

Every run writes dependency-health.json before launching workers unless dependencyHealth: false or --dependency-health=false is passed. The preflight checks the adapter-local package resolution path plus the caller root, verifies the installed @shapeshift-labs/frontier-swarm version, and fails fast when semantic import would resolve a stale or missing optional @shapeshift-labs/frontier-lang. Use frontier-swarm doctor --semantic-import to run the same check without starting workers. This catches nested optional dependency drift after npm updates before a swarm spends time producing empty semantic sidecars.

Use frontier-swarm resume --run <prior-run-dir> when a run was stopped or partially completed. The command reads the prior swarm-plan.json, swarm-results.json, merge bundles, evidence summaries, patch intent, log summaries, and last-message.md files, writes a resume-overlay.json, and classifies jobs as completed, failed, blocked, evidence-only, or rerun-needed. Completed and evidence-only jobs are skipped by default, while failed, blocked, and rerun-needed jobs are relaunched unless filtered by the include flags. Each resumed worker prompt starts with the prior evidence paths and status so the worker can continue from the partial handoff instead of rediscovering the same facts. Programmatic callers can use createCodexResumeOverlay, createCodexResumePlan, renderCodexResumePromptPrefix, or resumeCodexSwarmRun.

Minimal Repro Workspaces

Large monorepos do not need one full git worktree per worker. The adapter supports four workspace modes:

current: run in the current checkout or lane worktree path.
git-worktree: create a detached git worktree for full-repo isolation.
copy: create a minimal copied workspace from declared includes, task files, sourceRefs, targetRefs, and task snapshotIncludes.
snapshot: same minimal-copy mechanics with snapshot-oriented naming for legacy SNES-style task manifests.

For copy and snapshot, the runner replaces generated workspaces by default so changed include sets and source files do not reuse stale minimal repros. It excludes heavy paths by default (.git, node_modules, dist, coverage, agent-runs, and build outputs) and passes --skip-git-repo-check to Codex. It snapshots the copied workspace before and after execution so changed-path ownership checks still work without git metadata. Runner-owned artifacts are recorded in workspace-proof.json and filtered out of ownership checks, which keeps parent dirty files and copied workspace logs from falsely failing useful workers. Each job also writes changes.patch when a patch can be derived and merge.json with the touched owned files, evidence paths, verification results, queue item IDs, risk, and merge disposition. Use linkPaths for heavy shared directories such as packages, corpora, fixtures, generated assets, or research checkouts that should not be duplicated. Task JSON may also declare snapshotIncludes, snapshotExcludes, snapshotArtifactIncludes, snapshotLinkPaths, requiredIncludes, and optionalIncludes.

Scalable Scheduling

runCodexSwarm uses @shapeshift-labs/frontier-swarm schedules and leases internally. Jobs become runnable only when their dependency DAG is satisfied, lane/compute/contention limits have capacity, and a lease can be issued for the local Codex worker. Browser lanes can declare capabilities, port pools, profile directory prefixes, and lower lane concurrency in the upstream swarm manifest. The adapter also derives deterministic evidence-lane resource hints from explicit lane ids, capabilities, and resource keys for browser, static-check, api-check, and fuzzer. Static-check lanes can use the wider --max-concurrency worker window, while browser, API-check, and fuzzer resources default to one-at-a-time quotas unless the manifest or resourceScheduling options provide a different quota. The adapter turns those declarations into a per-job resource allocation, writes resource-allocation.json, includes the allocation in the worker prompt and event stream, creates browser profile directories, and passes env vars such as FRONTIER_SWARM_CAPABILITIES, FRONTIER_SWARM_RESOURCE_ALLOCATION, PORT, FRONTIER_SWARM_BROWSER_PORT, and FRONTIER_SWARM_BROWSER_PROFILE_DIR into the Codex process. Pass --adaptive --adaptive-mode balanced to treat --max-concurrency as a ceiling while the runner derives lower effective caps from deterministic observations such as resource contention, failed evidence, stale patches, empty semantic sidecars, log noise, and discovery-only overproduction. The latest decision surface is written to adaptive-load.json.

Task JSON may declare dependsOn, concurrencyKey, budget, and review; the adapter carries those fields into the compiled plan and prompt.

After updating npm packages in a local multi-package checkout, use frontier-swarm repair-links to restore local workspace symlinks without replacing packages you intentionally want from npm. The command reads scoped dependencies from the target package.json, discovers matching local packages under one-level package roots, skips --exclude-package entries, and writes a JSON plan by default. Add --write to create or update symlinks. Existing real package directories are reported as conflicts unless --replace is passed, so npm-installed packages are preserved unless replacement is explicit.

Each run writes event streams under streams/, a coordinator-dashboard.json snapshot, pids.json, dependency-health.json, workspace proofs, patch files, merge bundles, per-job evidence/evidence.json, patch-intent.json, log-summary.json, and job results with merge-readiness classification. The normalized evidence file records changed paths, semantic regions, command pass/fail summaries, source citations, semantic sidecar stats, and ready-to-port patch hunk counts. patch-intent.json is the short review surface: what changed, why, risk, exact verification, semantic import quality, warnings, and whether the patch is safe to port manually. Raw Codex stdout/stderr capture is compacted by default; log-summary.json records original bytes, written bytes, and truncation counts, and --max-event-bytes / --max-stderr-bytes can tune the limits. discoverCodexHandoffArtifacts scans job directories for last-message.md, debug handoffs, replay logs, watchpoints, traces, diagnostics, logs, evidence JSON, and patches; runCodexJob adds those paths to result evidence and metadata.codexHandoffArtifacts so coordinator dashboards can link directly to replay/debug artifacts. frontier-swarm stop --run <run-dir> reads the pid manifest and terminates live worker processes without manually hunting process state.

frontier-swarm collect --run <run-dir> derives status from immutable worker overlays instead of asking workers to edit a central queue. It scans merge.json files and writes:

ready-to-apply/ for auto-mergeable verified slices,
needs-human-port/ for patch candidates and discovery-only results,
failed-evidence/ for failed workers, blockers, ownership violations, or failed required commands,
stale-against-head/ for patch bundles that no longer apply.

It also writes merge-index.json, queue-overlay.json, strategy-tournament.json, strategy-history.json, tournament-adaptive-feedback.json, evidence-index.json, merge-admission.json, coordinator-query.json, and compact-dashboard.json so coordinator dashboards can show changed paths, tests, semantic selected/eligible/imported/candidate counts, semantic dependency relations, semantic regions, lineage moves/renames/deletes, semantic edit-script portable/conflict/stale/admission counts, semantic edit projection match/mismatch counts, semantic edit admission decisions, universal AST layer quality, proof obligation status, quality warnings, source citations, risk, ready-to-port hunks, stale patches, duplicate surfaces, semantic import quality, evidence scores, pid liveness, conflicts, derived queue status, strategy payoff standings, tournament history, adaptive feedback, and ready merge pressure without scraping every worker directory. coordinator-query.json, compact-dashboard.json, and collected evidence.json expose semanticEditAdmission directly with status, clean eligibility, auto-merge candidacy, and reasons. Use frontier-swarm query --collection <dir> --symbol computeThing, --lineage, --semantic-edit-status conflict|portable|stale, --semantic-edit-admission auto-merge-candidate|needs-port|conflict|stale, --semantic-edit-projection projected|blocked|worker-match|worker-mismatch|worker-unknown, or --readiness ready-to-port|ready-to-apply|stale|discovery-only|blocked|evidence-only for compact coordinator views. Stale checks distinguish patches that fail only because the coordinator worktree is dirty from patches whose base hashes no longer match HEAD. Copied/no-index workspace patches with source-side absolute paths are normalized back to repo-relative paths when possible; patches without comparable base hashes are treated as needs-human-port, not stale. The optional --branch-prefix adds suggested tiny patch branch names to each collected bundle so accepted slices can become one small branch/commit per surface, evidence path, and queue status overlay.

Collection is also the archive boundary for large swarm runs. collect writes artifact-store/artifacts.jsonl, artifact-store/artifact-index.sqlite when the runtime provides node:sqlite, SQL export text, and content-addressed blobs under artifact-store/blobs/. Text-heavy artifacts such as JSON, JSONL, logs, patches, Markdown, and text files are compressed with zstd when available and gzip otherwise, while metadata records keep job id, kind, path, hash, compression, tags, and semantic summaries queryable. Full semantic-imports.json sidecars stay in compressed blobs; artifact metadata keeps a compact semanticCompactSummary with selected/imported counts, symbols, ownership regions, dependency counts, lineage, source/base/head hashes when available, semantic edit status, projection worker-match evidence, and admission fields so coordinators can query sidecars without opening huge JSON. frontier-swarm query can read the SQLite index directly, including --semantic-edit-status, --semantic-edit-admission, and --semantic-edit-projection filters, so archived collections remain searchable even after JSONL has been removed. After reviewing the dry run, use frontier-swarm cleanup --run <run-dir> --compact-artifacts --write to delete run-side artifact source files and disposable worker workspaces that already have a collected-and-indexed.json marker and preserved blobs. Pass --collection <dir> when collect --outDir wrote the archive outside the default run directory. Cleanup keeps failed or active work by default and reports exactly what would be deleted unless --write is passed.

frontier-swarm tournament query --collection <collection-dir> reads strategy-tournament.json and emits filtered JSON views. When the collection also has compact-dashboard.json or coordinator-query.json, the query result includes a semanticImport block with aggregate quality plus per-job quality summaries. Use --view summary|standings|matches|full, --strategy, --game, --outcome, --tag, --min-score, --max-score, and --limit to narrow review. frontier-swarm tournament compare --baseline <file> --current <file> compares two tournaments, frontier-swarm tournament history --tournament <file> folds one or more tournaments into cross-run standings, and frontier-swarm tournament feedback --collection <dir> emits adaptive scheduler observations. Pass that feedback into a later run with --adaptive --adaptive-feedback <tournament-adaptive-feedback.json>.

frontier-swarm apply --collection <collection-dir> reviews the ready-to-apply/ bucket and writes apply-ledger.json. It defaults to --dry-run, which runs git apply --check without mutating the checkout. Non-dry-run apply refuses a dirty worktree unless --allow-dirty is passed, and can optionally create small branches with --branch-prefix and commits with --commit.

frontier-swarm score --collection <collection-dir> applies each collected bundle in a throwaway workspace and writes patch-score.json. Use --workspace-include / --workspace-exclude to keep score workspaces small, --focused-command for the gate that proves the slice, and --global-command with --global-glob for shared-code smoke/type/build gates. Scores are classified as accepted-clean, accepted-needs-port, conflict, test-fail, stale, or evidence-only, so the coordinator can review the best patch candidates before manually reading every bundle. When semantic import sidecars are present, the score entries include semanticEvidence with source-map mapping counts, semantic symbols, dependency relation counts/predicates, ownership regions, patch hints, lineage counts, semantic edit-script admission, semantic edit projection status, losses, readiness, proof obligation counts, failed/stale proof status, paradigm/lowering record counts, and an advisory score adjustment. Missing or empty semantic evidence downgrades otherwise clean source patches to accepted-needs-port instead of treating textual apply success as merge readiness; blocked or ambiguous lineage evidence, stale semantic edit anchors, conflicting semantic edit scripts, or blocked semantic edit projections also prevent an accepted-clean classification. If the collection has an apply-ledger/apply-ledger.json, scoring also emits calibration with landed job ids, predicted clean job ids, semantic auto-merge-candidate job ids, semantic candidate precision, false positives, and false negatives so tournament/adaptive scheduling can learn from actual merges.

Surface

createCodexSwarmPlan
coerceCodexSwarmManifestInput
coerceCodexSwarmTasksInput
createCodexWorkspacePlan
createSwarmWorkspaceManifest, createSwarmWorkspaceProof
prepareCodexWorkspace
runCodexSwarm
runCodexJob
discoverCodexHandoffArtifacts
createCodexResourceAllocation
buildCodexArgs
normalizeCodexModelFlag, normalizeCodexApprovalPolicy
initFileSwarmEventStream, appendFileSwarmEvent, writeSwarmCoordinatorSnapshot
appendCodexPidManifest, readCodexPidManifest, stopCodexSwarmRun
repairCodexWorkspacePackageLinks
checkCodexDependencyHealth, writeCodexDependencyHealthReport
createCodexResumeOverlay, createCodexResumePlan, resumeCodexSwarmRun
collectCodexSwarmRun
applyCodexSwarmCollection
scoreCodexSwarmPatches
queryCodexSwarmTournament
compareCodexSwarmTournaments
createCodexSwarmTournamentHistory
readCodexTournamentAdaptiveFeedback
renderCodexPrompt
spawnCodexExecutor
FRONTIER_SWARM_CODEX_SEMANTIC_IMPORT_KIND
FRONTIER_SWARM_CODEX_PATCH_INTENT_KIND
FRONTIER_SWARM_CODEX_COMPACT_DASHBOARD_KIND
FRONTIER_SWARM_CODEX_DEPENDENCY_HEALTH_KIND
FRONTIER_SWARM_CODEX_RESUME_OVERLAY_KIND

Benchmarks

Run the package-local benchmark:

npm run bench

The benchmark writes benchmarks/results/frontier-swarm-codex-package-bench-latest.json when run from the monorepo. These are Frontier-only package measurements for input coercion, Codex argument construction, model/approval compatibility normalization, workspace manifest creation, and prompt rendering.

Source Repository

This package is published from siliconjungle/-shapeshift-labs-frontier-swarm-codex.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@shapeshift-labs/frontier-swarm-codex

Related Packages

Install

CLI

API

Minimal Repro Workspaces

Scalable Scheduling

Surface

Benchmarks

Source Repository