@poetic-ai/poetic 1.42.0

package/README.md

@@ -0,0 +1,474 @@
+# Poetic
+
+Poetic is a TypeScript CLI for running AI coding work through multiple local
+providers, comparing their results, and keeping the winning implementation
+grounded in tests and repository policy.
+
+[![Version](https://img.shields.io/badge/version-v1.42-blue.svg)](package.json)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+## What It Does
+
+Poetic helps with coding tasks that benefit from orchestration rather than a
+single model response:
+
+- Run one provider or several competing provider variants.
+- Compare conservative, hybrid, and innovative approaches.
+- Use an AI judge to evaluate and synthesize variants.
+- Track cost, telemetry, and validation results locally.
+- Coordinate project work through backlog, sprint, and task workflows.
+
+The actively maintained provider path is local CLI execution. Historical cloud
+execution code and telemetry fields remain for compatibility, but new workflows
+should prefer local provider modes.
+
+## Security Model At A Glance
+
+Poetic runs local provider CLIs and asks them to edit your checkout. Treat those
+providers as code-executing tools that can read repository files and any other
+broadly-readable files their own runtime can access.
+
+On macOS, Poetic wraps provider CLI processes in the native Seatbelt sandbox by
+default. The sandbox is a write and persistence boundary: it restricts writes to
+the worktree, temp/cache locations, and selected provider state directories, and
+it blocks known sensitive credential paths. It is not a confidentiality boundary
+or a network egress filter. Provider CLIs still have outbound network access and
+can read files that are not explicitly denied.
+
+Write-capable provider automation requires an accepted sandbox/policy boundary.
+On macOS that is still Seatbelt, or an attested container / inherited outer;
+missing those still fails closed. On Linux, host class is the write policy (not
+a Seatbelt sandbox): isolated VM/container/cloud/CI hosts just work; Linux
+desktops warn and require `poetic sandbox trust linux --ack-desktop` or a TTY
+prompt. Never a Linux platform ban. Missing desktop consent fails this run with
+`linux_desktop_consent_required`. WSL is treated as a desktop. Install,
+readiness, orientation, telemetry, and other read-only CLI commands remain
+available without that consent. See
+[docs/reference/SECURITY.md](./docs/reference/SECURITY.md#runtime-security-boundaries).
+
+That boundary does not cover project verification. Poetic's verification steps
+run your target repository's own test, build, lint, and typecheck commands as
+ordinary child processes with your full OS privileges. Wherever a boundary is
+active it confines provider execution only, never these commands. Code reached
+that way can write anywhere your user account can. Realistic exposure paths are a compromised dependency pulled into
+the target project, or agent-authored or prompt-injected code that reaches a
+verification script; neither requires a hostile third-party contribution. The
+command allowlist constrains the command string (`npm test` is accepted), not
+what the invoked script then does. Running Poetic against an unfamiliar
+repository means running that repository's code on your machine. See
+[Project Verification Executes Target-Repository Code](./docs/reference/SECURITY.md#project-verification-executes-target-repository-code).
+
+## Quick Start
+
+Requires Node.js 24.x on macOS or Linux. Native Windows is not supported; use
+WSL2. WSL is treated as a Linux desktop. Install and read-only CLI commands
+work on Linux without extra setup. Write-capable provider automation on Linux
+uses host class (isolated hosts just work; desktops warn and require consent);
+macOS still requires Seatbelt or an attested container (see
+[Security Model At A Glance](#security-model-at-a-glance)). See
+[INSTALL.md](INSTALL.md) for the full prerequisite list.
+
+Install the exact release from npm:
+
+```bash
+npm install -g @poetic-ai/poetic@1.42.0
+```
+
+The repository is private until the open-source switch, so authenticated users
+can run the tagged installer through GitHub CLI:
+
+```bash
+gh api -H 'Accept: application/vnd.github.raw+json' \
+  'repos/ebrindley/Poetic/contents/install.sh?ref=v1.42.0' \
+  | bash -s -- --version 1.42.0 --strict
+```
+
+After the repository becomes public, the floating one-liner is:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/ebrindley/Poetic/main/install.sh | bash
+```
+
+Contributors can build from the public source repository as described in
+[INSTALL.md](INSTALL.md).
+
+Verify the install:
+
+```bash
+poetic provider list
+poetic doctor --all
+```
+
+### For Interactive Use
+
+Run provider setup first, then initialize the git repository you want Poetic
+to change:
+
+```bash
+poetic provider setup --first-run
+cd /path/to/target-git-repo
+poetic init
+poetic doctor
+```
+
+`poetic init` is the full project scaffold. `poetic init quickstart` is an
+optional readiness and safe-branch helper. `poetic init --safe-branch` creates
+a safe branch then initializes; legacy `poetic quickstart` remains a hidden
+compatibility path through 1.42.x.
+
+### For Agents and Scripts
+
+Read compact project context instead of loading README or the full command
+reference:
+
+```bash
+poetic context --json
+```
+
+For the primary validated path, authenticate Claude or Codex first.
+Provider release tiers are tracked in
+[docs/reference/PROVIDER_RELEASE_TIERS.md](./docs/reference/PROVIDER_RELEASE_TIERS.md):
+Claude and Codex are primary validated; Grok, Cursor, OpenCode, Antigravity,
+and Pi are supported validated; Gemini, Kiro, and Copilot are experimental.
+
+```bash
+poetic provider setup --providers claude,codex
+claude auth login
+codex login
+poetic provider list
+```
+
+In an interactive terminal, running `poetic` with no arguments opens the local
+dashboard. In CI, pipes, and other non-interactive shells, bare `poetic` prints
+lightweight help instead.
+
+### First success
+
+Start with `poetic provider setup --first-run`, then in the project repository
+run `poetic init` and `poetic doctor`. Work from that target repository,
+not a nested checkout. Use a safe branch (`run/*` is fine) rather than `main`.
+`poetic init quickstart` remains an optional branch helper.
+Prefer `poetic run` for straightforward single-provider execution. Use
+`poetic run competition` when you want judge scores/rationale (single-variant
+graded evaluation) or multi-variant comparative selection. The example selects
+Claude explicitly; Codex is the peer primary path when it is the ready local
+CLI. The configured runtime default remains whatever
+`poetic config resolved --summary --json` reports for your project.
+
+```bash
+# In your project repo (not on main)
+poetic init
+poetic doctor
+# Optional branch helper:
+poetic init quickstart "my task" --branch --branch-name run/my-task
+
+# Preferred default: straightforward single-provider execution
+poetic run "Your concrete task here"
+# Delivery caveat: changes may stay in an isolated worktree or patch under .poetic/
+
+# When you want judge scores/rationale (AI judging is the default)
+poetic run competition "Your concrete task here" --variant claude:conservative
+# Note the competition ID, then apply on a fix/* / docs/* / test/* branch:
+poetic init quickstart "apply my task" --branch --branch-name fix/my-task
+poetic run competition apply <competition-id>
+
+git status   # inspect repo-root changes when apply (or in-place) delivery landed
+poetic provider list   # confirm provider readiness
+```
+
+**Verify:** `poetic provider list` reports at least one ready provider. After a
+successful `compete apply` (or an in-place run), `git status` shows the expected
+files in the repo root. Direct `run` and judged `compete` remain **Beta** until
+post-apply verification, judgeWinner/deliveryArtifact identity, and the end-to-end
+judged apply path are validated.
+
+See [docs/getting-started/QUICK_START.md](./docs/getting-started/QUICK_START.md)
+for the full walkthrough. The supported surface contract is in
+[docs/RELEASE_VERIFICATION.md](https://github.com/ebrindley/Poetic/blob/main/docs/RELEASE_VERIFICATION.md#supported-surface-contract).
+
+### Source install details
+
+Poetic is MIT-licensed open-source software. The public source repository is
+available for source builds under the [MIT License](./LICENSE); clone, build,
+and local link steps are in [INSTALL.md](INSTALL.md). For the installer script,
+upgrades, and CI options, see [INSTALL.md](INSTALL.md).
+
+Additional checks for a source setup:
+
+```bash
+poetic d               # short alias for `poetic doctor`
+```
+
+**Power-user pattern: executor + reviewer.** Beyond the default execute path,
+Poetic can pair a fast executor with an independent, cross-vendor AI code
+reviewer on every dispatched task (executor -> reviewer -> gate -> verify),
+configured via `roles.*`. This is an advanced, instrumented pattern.
+
+### Beta limitations
+
+- Prefer `poetic run` for straightforward single-provider work. By default it
+  uses isolated worktrees and may leave patch artifacts under `.poetic/` rather
+  than editing your repo root. Use `poetic run competition` when you want judge
+  scores/rationale or multi-variant comparison.
+- Single-variant `poetic run competition` with the default AI judge is graded
+  evaluation (scores and rationale). Multi-variant judged `run competition` is
+  comparative selection. Do not pass `--judge ai` unless you are overriding a
+  non-default judge choice — AI judging is already the default.
+- Analysis-classified tasks auto-use Fusion peer synthesis. Pass `--judge ai`
+  explicitly when you want graded judge feedback instead of Fusion.
+- `--judge off` with one variant is ungraded execution through competition
+  infrastructure. With multiple variants it is manual comparison with no
+  automatic winner (inspect, then `poetic run competition apply <id> --variant <name>`).
+- `poetic plan approve --to-sprint --no-apply` still runs Flywheel (results
+  stay on the review branch); it is not the same as
+  `build "<intent>" --planned --no-apply`, which stops after planning without
+  sprint or workflow execution.
+- Apply-mode pipeline commands (`run competition`, `build --planned`,
+  `sprint run`, `run`) are blocked on `main` unless you pass `--allow-main`.
+  Prefer a `run/*` execution branch, and harvest competition results onto
+  `fix/*`, `docs/*`, or `test/*` with `poetic run competition apply`.
+- Validation-only checks from protected branches should use
+  `poetic run competition --validation-run ...`; product fixes still need a
+  separate `fix/*`, `docs/*`, or `test/*` apply branch.
+- Cleanup commands default to dry-run. Inspect with `poetic cleanup doctor`,
+  `poetic cleanup worktrees`, or `poetic cleanup preview` before adding
+  `--execute`.
+
+## Provider Setup
+
+Poetic delegates to provider CLIs that you install and authenticate separately.
+Claude and Codex are the primary validated providers for the public release.
+Grok, Cursor, and OpenCode are supported validated providers. Antigravity and
+Pi are also supported validated; Gemini, Kiro, and Copilot are experimental.
+That release status does not override configured defaults: use
+`poetic config resolved --summary --json`
+to inspect the active execution and judge defaults. Use `poetic provider setup` for
+guided setup, or configure only the providers you want:
+
+```bash
+poetic provider setup --providers claude,codex
+```
+
+Common provider commands:
+
+| Provider    | Setup                                                                  |
+| ----------- | ---------------------------------------------------------------------- |
+| Claude      | `claude auth login`                                                    |
+| Codex       | `npm install -g @openai/codex && codex login`                          |
+| Grok        | `POETIC_ALLOW_CURL_BASH=1 poetic provider setup --providers grok`, then `grok login --device-auth` (or `grok login` / `grok`); optional `XAI_API_KEY` for CI/headless |
+| Cursor      | `POETIC_ALLOW_CURL_BASH=1 poetic provider setup --providers cursor`             |
+| Gemini      | `npm install -g @google/gemini-cli`, then `gemini` or `GOOGLE_API_KEY` |
+| Copilot CLI | Run `copilot` once to complete device auth                             |
+| OpenCode    | `curl -fsSL https://opencode.ai/install \| bash`, then `opencode auth login` |
+
+See [docs/PROVIDER_SETUP.md](./docs/PROVIDER_SETUP.md) for full provider notes.
+
+## Core Commands
+
+Beta (default path) — capture, orient, execute:
+
+```bash
+poetic plan backlog add "Add logging to the auth service"
+poetic plan next
+poetic run task --backlog-item <id>     # or: poetic run competition --backlog-item <id>
+```
+
+`poetic plan next` reads from `backlog/`. Add items with `poetic plan backlog add`, then
+`poetic plan next` surfaces actionable work. Use `poetic plan backlog show <id>` to
+inspect, `poetic plan backlog refine <id>` to fill out incomplete specs.
+
+Concrete-task and intent-based execution, then graded/comparative
+`run competition` when needed:
+
+```bash
+poetic init quickstart "my task" --branch --branch-name run/my-task
+poetic run "Add logging to the auth service"
+poetic build "Improve the authentication flow"
+poetic build "Redesign authentication across services" --planned
+# Optional: graded evaluation or multi-variant comparison (AI judge default)
+poetic run competition "Add logging to the auth service" --variant claude:conservative
+poetic init quickstart "apply my task" --branch --branch-name fix/my-task
+poetic run competition apply <competition-id>
+```
+
+Operator and power commands (sprint lifecycle, plan approval, sprint run): see
+[docs/SPRINT_PLANNING_GUIDE.md](https://github.com/ebrindley/Poetic/blob/main/docs/SPRINT_PLANNING_GUIDE.md).
+
+```bash
+# Operator examples
+poetic plan backlog execute <id>
+poetic plan sprint create --name "Sprint 1" --start 2026-01-01 --end 2026-01-14
+poetic plan sprint close <sprint-id>
+
+# Power / internal example
+poetic plan sprint run
+```
+
+## Choosing Providers
+
+| Scenario                          | Good fit                                                |
+| --------------------------------- | ------------------------------------------------------- |
+| Straightforward single-provider   | Claude or Codex via `poetic run` (worktree/patch caveat) |
+| Graded evaluation (scores/rationale) | Single-variant `poetic run competition` (AI judge default) |
+| Comparative selection             | Multi-variant `poetic run competition` with default AI judging |
+| Supported validated providers     | Grok, Cursor, OpenCode, Antigravity, Pi when local CLIs are ready |
+| Experimental providers            | Gemini, Kiro, Copilot after local setup and readiness checks |
+| Fast local suggestions            | Copilot CLI or Claude when local CLIs are ready         |
+| Cost-sensitive work               | `poetic run --optimize cost`                            |
+| Local-only workflows              | Local CLI providers                                     |
+
+Provider names are literal. `opencode` is not `gemini`; `codex` is not
+`copilot`.
+
+## Project Workflows
+
+Poetic can manage work queues and execution state:
+
+```bash
+poetic plan next
+poetic plan task list
+poetic plan sprint status
+poetic run --backlog-item <id>
+```
+
+Managed directories such as `backlog/`, `sprint/`, and `task/` are meant to be
+changed through the CLI rather than by hand.
+
+## Telemetry And Cost
+
+Telemetry is stored locally in SQLite under `.poetic/telemetry/db/`.
+Project state and JSONL logs live under `.poetic/telemetry/` unless global
+telemetry or `POETIC_TELEMETRY_DB` changes the location.
+
+```bash
+poetic telemetry leaderboard
+poetic telemetry prompts
+poetic cost status
+poetic cost compare anthropic:<model> google:<model>
+```
+
+Poetic can store prompts, prompt hashes and lengths, repository paths, changed
+file paths, provider/model/strategy metadata, output and error tails,
+validation command output tails, token counts, cost snapshots, and retention
+metadata. Defaults from `src/telemetry/retention-config.ts` keep JSONL logs and
+signal files for 90 days, soft-prune SQLite rows after 180 days, use a 90-day
+warning prune threshold, keep backups for 30 days plus 3 monthly archives, cap
+telemetry backups at 1 GiB, and keep cleanup logs for 7 days. See
+[docs/reference/TELEMETRY_PRIVACY.md](https://github.com/ebrindley/Poetic/blob/main/docs/reference/TELEMETRY_PRIVACY.md)
+for disable, cleanup, and deletion commands.
+
+Cost telemetry is informational by default. Poetic records, displays, predicts,
+and recommends cost improvements, but it does not automatically switch providers,
+skip work, or enforce cost caps. Cost data may inform explicit user choices, but
+Poetic does not enforce spend limits by default.
+
+## Validation
+
+For local development:
+
+```bash
+npm run test:smoke
+npm run typecheck
+npm run check:esm
+```
+
+For release packaging:
+
+```bash
+npm pack --dry-run
+```
+
+The npm package exposes `poetic` through `dist/entry.js`; local source builds
+install a Node 24 launcher into `~/.local/bin` (override with `POETIC_BIN_DIR`)
+through `scripts/build-poetic.sh`, without registering the package in npm's
+global prefix.
+
+Node 24 is pinned in two tool-specific files: CI reads `.node-version`, while
+local development, preinstall checks, and source builds read `.nvmrc`. Keep the
+two values aligned with `package.json#engines`.
+
+## Repository layout
+
+The published npm package ships from an allowlist (`package.json#files`): compiled
+`dist/`, schemas, templates, provider configs, and selected docs. Most of the
+repository is development-only and never reaches an installed copy.
+
+| Path | Ships in package? | Purpose |
+|---|---|---|
+| `src/` | As compiled `dist/` | Product source |
+| `tests/` | No | Test suite |
+| `scripts/` | Only 6 install/lifecycle scripts (`sync.sh`, `preinstall-node-check.mjs`, `assert-node-runtime.mjs`, `preflight-native.mjs`, `setup-git-hooks.mjs`, `write-node-launcher.sh`) | Dev/ops utilities (`scripts/AGENTS.md`) |
+| `docs/` | Selected files only | Documentation |
+
+When browsing the repo, treat `scripts/` as engineering support, not runtime surface
+area. Benchmark suite runners and the `benchmark:` compete route have been removed from
+Poetic; portable CLI comparison harnesses live outside this repository when needed.
+For the class-level component map (judges, orchestrators, executors, provider adapters)
+see [docs/reference/COMPONENT_TAXONOMY.md](https://github.com/ebrindley/Poetic/blob/main/docs/reference/COMPONENT_TAXONOMY.md).
+
+## Documentation
+
+| Document                                                           | Audience | Purpose                           |
+| ------------------------------------------------------------------ | -------- | --------------------------------- |
+| [docs/getting-started/QUICK_START.md](./docs/getting-started/QUICK_START.md) | New user | Setup and getting started         |
+| [docs/CLI_REFERENCE.md](./docs/CLI_REFERENCE.md)                   | Operator | Command reference                 |
+| [docs/PROVIDER_SETUP.md](./docs/PROVIDER_SETUP.md)                 | New user | Provider authentication and setup |
+| [docs/AI_JUDGE.md](https://github.com/ebrindley/Poetic/blob/main/docs/AI_JUDGE.md)                             | Operator | Judge behavior and analysis mode  |
+| [docs/TELEMETRY_STATE.md](https://github.com/ebrindley/Poetic/blob/main/docs/TELEMETRY_STATE.md)               | Operator | Telemetry state files             |
+| [docs/INSTRUCTION_ARCHITECTURE.md](https://github.com/ebrindley/Poetic/blob/main/docs/INSTRUCTION_ARCHITECTURE.md) | Contributor | Instruction architecture overview |
+| [docs/PARALLEL_EXECUTION.md](https://github.com/ebrindley/Poetic/blob/main/docs/PARALLEL_EXECUTION.md)         | Operator | Parallel execution guide          |
+
+## Project Status
+
+Poetic ships as v1.42. The npm package version is `1.42.0`.
+
+The public release is **conditionally ready** for readiness, orientation, and stable
+telemetry. Prefer `poetic run` for straightforward single-provider execution;
+use judged `poetic run competition` for graded evaluation or comparative
+selection. Direct `run` and judged `run competition` are **Beta** — not an
+A-grade claim — until post-apply verification, judgeWinner/deliveryArtifact
+identity, and the end-to-end judged apply path are validated. See the full
+release contract in
+[docs/RELEASE_VERIFICATION.md](https://github.com/ebrindley/Poetic/blob/main/docs/RELEASE_VERIFICATION.md#supported-surface-contract)
+and tier labels in [docs/CLI_REFERENCE.md](./docs/CLI_REFERENCE.md#support-tiers-and-release-contract)
+(aligned with `poetic --help`).
+
+| Area                                                           | Tier / status                                                                                |
+| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `poetic run` (straightforward single-provider)                 | **Beta** (isolated worktree / patch delivery caveat)                                         |
+| Single-variant judged `run competition` (graded evaluation)    | **Beta** (AI judge default; apply with `run competition apply`)                              |
+| Multi-variant judged `run competition` (comparative selection) | **Beta** (AI judge default selects a winner when judging succeeds)                           |
+| `--judge off` (single or multi)                                | **Beta** (ungraded competition infra / manual comparison; no automatic winner when multi)    |
+| Readiness (`provider list`, `doctor`) and orientation (`next`) | **Dependable**                                                                               |
+| Telemetry and cost tracking                                    | **Dependable** (stable)                                                                      |
+| Core orchestration (`fast`, `best`, `cheap`)                   | Beta                                                                                         |
+| `poetic build` (intent execution, including `--planned`)       | **Beta** canonical intent front door                                                         |
+| Configured default provider / judge                            | Resolved from project config; currently expected to be Claude unless product defaults change |
+| Providers: Claude, Codex                                       | Primary validated                                                                            |
+| Providers: Grok, Cursor, OpenCode, Antigravity, Pi             | Supported validated                                                                          |
+| Providers: Gemini, Copilot CLI, Kiro                           | Experimental                                                                                 |
+| GLM models                                                     | Available through OpenCode, not a standalone provider                                        |
+| AI Judge and synthesis                                         | Beta; heuristic fallback validated, clean judge success depends on configured judge provider |
+| Sprint, backlog operator CLI                                   | Advanced (under `plan …`)                                                                      |
+| `plan approve`, `planning-checkpoint`, `plan sprint run`, `run flywheel` | Internal; pre-release for first users                                      |
+| `poetic swarm`, multi-agent judge, cherry-pick synthesis       | Experimental                                                                                 |
+| Cloud execution paths                                          | Legacy compatibility                                                                         |
+
+## Contributing
+
+Bug reports and feature requests are welcome through
+[GitHub Issues](https://github.com/ebrindley/Poetic/issues). Open-ended
+questions should go to
+[GitHub Discussions](https://github.com/ebrindley/Poetic/discussions) once
+Discussions are enabled.
+
+External pull requests are not currently accepted. See
+[CONTRIBUTING.md](./CONTRIBUTING.md) for the maintenance policy.
+
+For security issues, use GitHub private security advisories and see
+[docs/reference/SECURITY.md](./docs/reference/SECURITY.md#reporting-vulnerabilities).
+Do not file vulnerabilities as public issues.
+
+## License
+
+Poetic is licensed under the MIT License. See [LICENSE](./LICENSE).

package/dist/BasicOptimizationCompetitionRunner-5H5TBYO4.js

@@ -0,0 +1,153 @@
+import "./chunk-PZ5AY32C.js";
+
+// src/core/optimization/runners/BasicOptimizationCompetitionRunner.ts
+import crypto from "crypto";
+function summarizeBasicResult(result) {
+  const variants = result.variants ?? [];
+  const total = variants.length;
+  if (total === 0) {
+    return {
+      status: "failed",
+      successRate: 0,
+      avgCompleteness: 0,
+      avgDuration: 0,
+      winnerName: null
+    };
+  }
+  const successes = variants.filter((v) => v.success === true).length;
+  const successRate = successes / total;
+  const avgCompleteness = variants.reduce(
+    (acc, v) => acc + (typeof v.completeness === "number" ? v.completeness : 0),
+    0
+  ) / total;
+  const avgDuration = variants.reduce((acc, v) => acc + (typeof v.duration === "number" ? v.duration : 0), 0) / total;
+  const winnerName = result.winner ? `${result.winner.provider}${result.winner.model ? `:${result.winner.model}` : ""}` : null;
+  return {
+    status: successes > 0 ? "completed" : "failed",
+    successRate,
+    avgCompleteness,
+    avgDuration,
+    winnerName
+  };
+}
+var BasicOptimizationCompetitionRunner = class {
+  runBasicCompetition;
+  variants;
+  verbose;
+  workerCwd;
+  constructor(options) {
+    this.runBasicCompetition = options.runBasicCompetition;
+    this.variants = options.variants ?? [];
+    this.verbose = options.verbose ?? false;
+    this.workerCwd = options.workerCwd;
+  }
+  async run(context) {
+    const errors = [];
+    const warnings = [];
+    let candidatesCompleted = 0;
+    const candidates = context.candidates ?? [];
+    const candidatesAttempted = candidates.length;
+    for (const candidate of candidates) {
+      try {
+        const outcome = await this.runOneCandidate(context, candidate, warnings);
+        if (outcome.status === "completed") {
+          candidatesCompleted += 1;
+        } else {
+          errors.push(`candidate ${candidate.id}: all variants failed`);
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        errors.push(`candidate ${candidate.id}: ${message}`);
+      }
+    }
+    const allAttemptedCandidatesFailed = candidatesAttempted > 0 && candidatesCompleted === 0 && errors.length > 0;
+    return {
+      status: allAttemptedCandidatesFailed ? "failed" : "completed",
+      candidatesAttempted,
+      candidatesCompleted,
+      errors,
+      warnings
+    };
+  }
+  async runOneCandidate(context, candidate, warnings) {
+    const taskId = `${context.cycleId}_${candidate.id}`;
+    const promptContent = candidate.content;
+    const executionId = deterministicExecutionId(context.cycleId, candidate.id);
+    const tracker = context.executionTracker;
+    if (this.variants.length === 0) {
+      throw new Error("No optimization competition providers configured");
+    }
+    const existingExecution = tracker.getExecution(executionId);
+    if (existingExecution?.status === "completed") {
+      return {
+        status: "completed",
+        successRate: existingExecution.successRate ?? 0,
+        avgCompleteness: existingExecution.avgCompleteness ?? 0,
+        avgDuration: existingExecution.avgDuration ?? 0,
+        winnerName: existingExecution.winningVariantId ?? null
+      };
+    }
+    if (existingExecution?.status === "failed") {
+      throw new Error(`existing execution ${executionId} already failed`);
+    }
+    if (existingExecution?.status === "running") {
+      throw new Error(`existing execution ${executionId} is already running`);
+    }
+    const execution = await tracker.startExecution({
+      id: executionId,
+      promptId: context.promptId,
+      versionId: candidate.id,
+      executionMode: "compete",
+      variantCount: this.variants.length
+    });
+    let competitionResult;
+    try {
+      competitionResult = await this.runBasicCompetition(taskId, promptContent, this.variants, {
+        verbose: this.verbose,
+        workerCwd: this.workerCwd,
+        // Optimization consumes only variants/winner metrics; skip synthesis.
+        synthesize: false
+      });
+    } catch (error) {
+      await tracker.completeExecution(execution.id, { status: "failed" });
+      throw error;
+    }
+    const summary = summarizeBasicResult(competitionResult);
+    for (const variant of competitionResult.variants ?? []) {
+      try {
+        await tracker.recordVariant({
+          executionId: execution.id,
+          variantName: `${variant.provider}${variant.model ? `:${variant.model}` : ""}`,
+          provider: variant.provider,
+          model: variant.model,
+          success: variant.success === true,
+          completeness: variant.completeness,
+          durationSeconds: variant.duration,
+          isWinner: !!competitionResult.winner && variant.provider === competitionResult.winner.provider && (variant.model ?? null) === (competitionResult.winner.model ?? null)
+        });
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const variantName = `${variant.provider}${variant.model ? `:${variant.model}` : ""}`;
+        warnings.push(
+          `candidate ${candidate.id}: failed to record variant ${variantName}: ${message}`
+        );
+      }
+    }
+    await tracker.completeExecution(execution.id, {
+      status: summary.status,
+      winningVariantId: summary.winnerName ?? void 0,
+      successRate: summary.successRate,
+      avgCompleteness: summary.avgCompleteness,
+      avgDuration: summary.avgDuration
+    });
+    return summary;
+  }
+};
+function deterministicExecutionId(cycleId, candidateVersionId) {
+  const digest = crypto.createHash("sha256").update(`${cycleId}:${candidateVersionId}`).digest("hex").slice(0, 24);
+  return `opt_exec_${digest}`;
+}
+export {
+  BasicOptimizationCompetitionRunner
+};
+//# sourceMappingURL=BasicOptimizationCompetitionRunner-5H5TBYO4.js.map

package/dist/ExecutionTracker-UVONC4C6.js

@@ -0,0 +1,16 @@
+import {
+  ExecutionTracker
+} from "./chunk-U45RTRGY.js";
+import "./chunk-QVZMFDYG.js";
+import "./chunk-S54MKU6V.js";
+import "./chunk-UI2F6DJ5.js";
+import "./chunk-L7JZLXQL.js";
+import "./chunk-IZYIQQ7X.js";
+import "./chunk-EJGCZGUF.js";
+import "./chunk-LPITVM7M.js";
+import "./chunk-5DLKYTQX.js";
+import "./chunk-PZ5AY32C.js";
+export {
+  ExecutionTracker
+};
+//# sourceMappingURL=ExecutionTracker-UVONC4C6.js.map

package/dist/OptimizationConfig-7DFY2TST.js

@@ -0,0 +1,17 @@
+import {
+  OptimizationConfigManager
+} from "./chunk-7FMJVYBS.js";
+import "./chunk-QVZMFDYG.js";
+import "./chunk-S54MKU6V.js";
+import "./chunk-2VSQMRCB.js";
+import "./chunk-UI2F6DJ5.js";
+import "./chunk-L7JZLXQL.js";
+import "./chunk-IZYIQQ7X.js";
+import "./chunk-EJGCZGUF.js";
+import "./chunk-LPITVM7M.js";
+import "./chunk-5DLKYTQX.js";
+import "./chunk-PZ5AY32C.js";
+export {
+  OptimizationConfigManager
+};
+//# sourceMappingURL=OptimizationConfig-7DFY2TST.js.map