opencode-swarm 7.180.1 → 7.181.0

package/dist/services/harness-optimizer/comparative.d.ts

@@ -0,0 +1,81 @@
+export type ComparativeArmKey = 'baseline' | 'ablation' | 'simple-agent';
+export declare const COMPARATIVE_ARM_KEYS: readonly ComparativeArmKey[];
+export interface ComparativeTaskDescriptor {
+    id: string;
+    instruction: string;
+}
+export type ComparativeExecutorStatus = 'completed' | 'transient_error' | 'failed';
+export interface ComparativeExecutorResult {
+    status: ComparativeExecutorStatus;
+    text: string;
+    tokens?: {
+        input?: number;
+        cache?: number;
+        output?: number;
+    };
+    /** Host-reported USD cost of this invocation, when supplied. */
+    costUsd?: number;
+}
+export type ComparativeExecutor = (invocation: {
+    cwd: string;
+    /** Protocol arm, or the round-role labels baseline/candidate on substrate rounds. */
+    arm: ComparativeArmKey | 'candidate';
+    taskId: string;
+    /** Host context passthrough (optional; populated on substrate-driven rounds). */
+    instruction?: string;
+    payload?: string;
+    seed?: string;
+    abortSignal?: AbortSignal;
+    projectRoot?: string;
+}) => Promise<ComparativeExecutorResult> | ComparativeExecutorResult;
+export interface ComparativeArmResult {
+    arm: ComparativeArmKey;
+    taskPopulationHash: string;
+    /** Denominator: every task in the population was attempted. */
+    n: number;
+    completed: number;
+    failed: number;
+    transientFailures: number;
+    streamDigest: string;
+    outcomes: Array<{
+        taskId: string;
+        status: ComparativeExecutorStatus;
+    }>;
+}
+export interface ComparativeProtocolResult {
+    arms: Record<ComparativeArmKey, ComparativeArmResult>;
+    taskPopulationHash: string;
+}
+export declare class StreamSnapshotDuplicateError extends Error {
+    readonly code = "STREAM_SNAPSHOT_DUPLICATE";
+    constructor(digest: string);
+}
+export declare function computeTaskPopulationHash(tasks: readonly ComparativeTaskDescriptor[]): string;
+export declare function computeArmStreamDigest(args: {
+    arm: ComparativeArmKey;
+    seed: string;
+    tasks: readonly ComparativeTaskDescriptor[];
+}): string;
+/**
+ * Run the three comparative arms. Each arm executes the full task
+ * population inside its own disposable git worktree (never the running
+ * checkout), with the working-tree fingerprint verified unchanged by
+ * withDisposableWorktree. Failed arms stay in the result with their
+ * outcomes — negative results are evidence, not noise.
+ */
+export declare function runComparativeProtocol(args: {
+    projectRoot: string;
+    tasks: ComparativeTaskDescriptor[];
+    seed: string;
+    executor: ComparativeExecutor;
+    /** Previously-recorded digests for this task population; a repeat rejects. */
+    previousStreamDigests?: string[];
+    /**
+     * Arm toggles (harness_opt.run_ablation_arm / run_simple_agent_arm).
+     * The baseline arm always runs; unlisted arms are skipped and absent
+     * from the result. Defaults to all three arms.
+     */
+    runAblationArm?: boolean;
+    runSimpleAgentArm?: boolean;
+    abortSignal?: AbortSignal;
+}): Promise<ComparativeProtocolResult>;

package/dist/services/harness-optimizer/controller.d.ts

@@ -0,0 +1,126 @@
+import type { ComparativeExecutor, ComparativeTaskDescriptor } from './comparative.js';
+export type HarnessOptSplit = 'train' | 'validation' | 'test';
+/**
+ * Stop reasons the round controller can actually produce. Every member has
+ * a producing code path (pinned by tests/unit/harness-opt/stop-reasons.test.ts
+ * and the controller suite); conditions that surface as typed ERRORS rather
+ * than stop results (held-out consumption, frozen-content mismatch, stream
+ * snapshot duplication, replay mismatch) are intentionally NOT members —
+ * they propagate as their substrate/module errors.
+ */
+export declare const HARNESS_OPT_STOP_REASONS: readonly ["completed", "inconclusive", "transient_retry_budget_exhausted", "round_budget_exhausted", "wall_clock_budget_exhausted", "spend_budget_exhausted", "stopped_by_operator"];
+export type HarnessOptStopReason = (typeof HARNESS_OPT_STOP_REASONS)[number];
+export interface HarnessOptRoundResult {
+    stopReason: HarnessOptStopReason;
+    transientRetries: number;
+    roundId: string;
+    roundCounter: number;
+    saltedSeed: string;
+    taskSetHash: string;
+    decision: {
+        status: string;
+        decisionId: string;
+    };
+}
+export declare class FrozenTaskSetMismatchError extends Error {
+    readonly code = "FROZEN_CONTENT_MISMATCH";
+    constructor(key: string);
+}
+/**
+ * Content-freeze the task set BEFORE any round. Re-freezing the same
+ * {split, seed} key with mutated task content is rejected (typed
+ * FROZEN_CONTENT_MISMATCH); identical content is idempotent. The frozen
+ * input lives content-addressed under .swarm/evolution/harness-opt/ and
+ * the substrate's immutable admission backs the freeze for non-train
+ * splits.
+ */
+export declare function freezeHarnessOptTaskSet(args: {
+    projectRoot: string;
+    tasks: ComparativeTaskDescriptor[];
+    split: HarnessOptSplit;
+    seed: string;
+}): Promise<{
+    ok: true;
+    contentHash: string;
+} | {
+    ok: false;
+    code: 'FROZEN_CONTENT_MISMATCH';
+    reason: string;
+}>;
+/**
+ * Execute ONE governed optimization round. The per-round seed salt
+ * `${seed}#roundNNNNNN` guarantees a fresh substrate runId per round, so
+ * the SUBSTRATE's claimHeldOutTest is what surfaces
+ * TestAlreadyConsumedError on a second held-out round over the same
+ * frozen task set — the controller never masks consumption with its own
+ * counter.
+ */
+export declare function runHarnessOptRound(args: {
+    projectRoot: string;
+    tasks: ComparativeTaskDescriptor[];
+    split: HarnessOptSplit;
+    seed: string;
+    maxTransientRetries?: number;
+    /** Hard wall-clock budget for the round, in milliseconds. */
+    maxWallClockMs?: number;
+    /** Soft spend budget for the round, in USD. */
+    maxSpendUsd?: number;
+    executor: ComparativeExecutor;
+    abortSignal?: AbortSignal;
+}): Promise<HarnessOptRoundResult>;
+export interface PilotGraduationRecord {
+    v: 1;
+    recordId: string;
+    eligible: boolean;
+    evaluatedAt: string;
+    criteria: {
+        lowerCiThreshold: number;
+    };
+    evidence: {
+        improvementLowerCi: number;
+        protectedRegressions: string[];
+    };
+}
+/**
+ * Evaluate pilot graduation against the predeclared criteria. The evidence
+ * — including failing (negative) evidence — is retained verbatim in the
+ * durable record. Default flipping stays owned by #2504; this surface only
+ * reports eligibility.
+ */
+export declare function evaluatePilotGraduation(args: {
+    projectRoot: string;
+    criteria: {
+        lowerCiThreshold: number;
+    };
+    evidence: {
+        improvementLowerCi: number;
+        protectedRegressions: string[];
+    };
+}): Promise<{
+    eligible: boolean;
+    recordId: string;
+}>;
+export declare function loadPilotGraduationRecord(projectRoot: string, recordId: string): PilotGraduationRecord | null;
+/** Human-only operator stop: halts further rounds until explicitly resumed
+ * via resumeHarnessOptLoop (harness-opt stop --resume). */
+export declare function stopHarnessOptLoop(args: {
+    projectRoot: string;
+    reason: string;
+}): Promise<{
+    stopped: true;
+    reason: string;
+}>;
+/** Human-only operator resume: clears an operator stop so rounds run again. */
+export declare function resumeHarnessOptLoop(args: {
+    projectRoot: string;
+}): Promise<{
+    resumed: boolean;
+    previousReason: string | null;
+}>;
+export interface HarnessOptStatus {
+    roundCounter: number;
+    stopped: boolean;
+    stopReason: string | null;
+    frozenTaskSets: number;
+}
+export declare function harnessOptStatus(projectRoot: string): HarnessOptStatus;

package/dist/services/harness-optimizer/execution.d.ts

@@ -0,0 +1,68 @@
+import { type ComparativeExecutor, type ComparativeTaskDescriptor } from './comparative.js';
+export interface HarnessOptTaskSetDescriptor {
+    split: 'train' | 'validation' | 'test';
+    seed: string;
+    tasks: ComparativeTaskDescriptor[];
+}
+export interface TokenUsage {
+    tokens_input: number | 'unknown';
+    tokens_cache: number | 'unknown';
+    tokens_output: number | 'unknown';
+}
+export declare function harnessOptTaskSetRoot(projectRoot: string, taskSetHash: string): string;
+/**
+ * Materialize the task-set input root (content-addressed by the task
+ * population hash). Existing materialization is left untouched — the
+ * content hash pins it; a mutation is detected by re-hashing before use.
+ */
+export declare function materializeHarnessOptInput(args: {
+    projectRoot: string;
+    descriptor: HarnessOptTaskSetDescriptor;
+}): {
+    inputRoot: string;
+    taskSetHash: string;
+};
+export declare class HarnessOptInputTamperedError extends Error {
+    readonly code = "HARNESS_OPT_INPUT_TAMPERED";
+    constructor(taskSetHash: string);
+}
+/**
+ * Verify the MATERIALIZED ON-DISK input still matches its content-addressed
+ * hash: re-reads every task instruction from the content-addressed input
+ * root and recomputes the task-population hash from the bytes on disk. A
+ * tampered materialization fails typed. (Issue #2503 integrity check.)
+ */
+export declare function verifyHarnessOptInput(args: {
+    inputRoot: string;
+    taskIds: readonly string[];
+    taskSetHash: string;
+}): boolean;
+export interface SubstrateExecutionResult {
+    runStatus: string;
+    decisionStatus: string;
+    decisionId: string;
+    /** Host-reported USD spend accumulated across executor invocations. */
+    reportedSpendUsd: number;
+    outcomes: Array<{
+        candidateId: string;
+        outcome: string;
+    }>;
+    tokens: TokenUsage;
+}
+/**
+ * Execute one governed evaluation round through the production substrate.
+ * The simplified executor runs inside the substrate's disposable worktree
+ * (isolatedRoot — never the running checkout) and token usage reported by
+ * the host executor is captured; missing host data stays 'unknown'.
+ */
+export declare function runSubstrateEvaluation(args: {
+    projectRoot: string;
+    inputRoot: string;
+    descriptor: HarnessOptTaskSetDescriptor;
+    seed: string;
+    decidedAt: string;
+    maxTransientRetries?: number;
+    maxSpendUsd?: number;
+    executor: ComparativeExecutor;
+    abortSignal?: AbortSignal;
+}): Promise<SubstrateExecutionResult>;

package/dist/services/harness-optimizer/index.d.ts

@@ -0,0 +1,10 @@
+export type { ComparativeArmKey, ComparativeArmResult, ComparativeExecutor, ComparativeExecutorResult, ComparativeProtocolResult, ComparativeTaskDescriptor, } from './comparative.js';
+export { COMPARATIVE_ARM_KEYS, computeArmStreamDigest, computeTaskPopulationHash, runComparativeProtocol, StreamSnapshotDuplicateError, } from './comparative.js';
+export type { HarnessOptRoundResult, HarnessOptSplit, HarnessOptStatus, PilotGraduationRecord, } from './controller.js';
+export { evaluatePilotGraduation, FrozenTaskSetMismatchError, freezeHarnessOptTaskSet, harnessOptStatus, loadPilotGraduationRecord, runHarnessOptRound, stopHarnessOptLoop, } from './controller.js';
+export type { HarnessOptLineageRecord } from './lineage.js';
+export { computeCandidateConfigDigest, computePromptSelectionDigest, listHarnessOptLineage, ReplayDecisionMismatchError, recordHarnessOptRound, replayHarnessOptLineage, } from './lineage.js';
+export type { ComparativeManifestV1, ManifestValidationFailureCode, ManifestValidationResult, } from './manifest.js';
+export { validateComparativeManifest } from './manifest.js';
+export type { OracleArmInput, OracleVerdict, TokenCount } from './oracle.js';
+export { evaluateIndependentOracle } from './oracle.js';

package/dist/services/harness-optimizer/lineage.d.ts

@@ -0,0 +1,70 @@
+import type { ComparativeTaskDescriptor } from './comparative.js';
+import type { TokenUsage } from './execution.js';
+export interface HarnessOptLineageRecord {
+    v: 1;
+    roundId: string;
+    /** Identical to roundId: one identity string, no derived second id. */
+    replayLineageId: string;
+    recordedAt: string;
+    split: 'train' | 'validation' | 'test';
+    baseSeed: string;
+    saltedSeed: string;
+    roundCounter: number;
+    taskSetHash: string;
+    candidateConfigDigest: string;
+    promptSelectionDigest: string;
+    tokens_input: number | 'unknown';
+    tokens_cache: number | 'unknown';
+    tokens_output: number | 'unknown';
+    artifactOutcome: string;
+    oracle: {
+        verdict: string;
+        reasons: string[];
+    };
+    decision: {
+        status: string;
+        decisionId: string;
+    };
+    execution: {
+        decidedAt: string;
+        maxTransientRetries?: number;
+        tasks: ComparativeTaskDescriptor[];
+    };
+}
+export declare class ReplayDecisionMismatchError extends Error {
+    readonly code = "REPLAY_DECISION_MISMATCH";
+    constructor(recorded: string, replayed: string);
+}
+export declare function recordHarnessOptRound(args: {
+    projectRoot: string;
+    record: HarnessOptLineageRecord;
+}): Promise<void>;
+export declare function listHarnessOptLineage(projectRoot: string): HarnessOptLineageRecord[];
+export declare function loadHarnessOptLineageRecord(args: {
+    projectRoot: string;
+    roundId: string;
+}): HarnessOptLineageRecord | null;
+export declare function computeCandidateConfigDigest(args: {
+    saltedSeed: string;
+    split: string;
+    maxTransientRetries?: number;
+}): string;
+export declare function computePromptSelectionDigest(tasks: readonly ComparativeTaskDescriptor[]): string;
+/**
+ * Replay a recorded round. The recorded fully-salted seed and decidedAt are
+ * re-used WITHOUT reading or advancing the round counter, so the substrate
+ * derives the identical runId and returns the immutable cached run. The
+ * replay executor throws if ever invoked — a replay must hit the cached
+ * record, never re-spend execution. Any decision mismatch (a tampered or
+ * stale record) fails typed.
+ */
+export declare function replayHarnessOptLineage(args: {
+    projectRoot: string;
+    lineageId: string;
+}): Promise<{
+    decision: {
+        status: string;
+        decisionId: string;
+    };
+}>;
+export type { TokenUsage };

package/dist/services/harness-optimizer/manifest.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Frozen comparative-evaluation manifest (issue #2503).
+ *
+ * A comparative run MUST be governed by a manifest frozen BEFORE any
+ * optimization: a named previous stable release, the repaired unoptimized
+ * baseline reference, the frozen corpus/task population, exact PR revisions
+ * with defect/clean labels, excluded training cases, matched budgets,
+ * per-arm sample sizes, numeric acceptance thresholds, and metric
+ * definitions. The validator refuses empty required fields and improvement
+ * claims without a measured result — the issue's "no empty manifest fields
+ * or unmeasured improvement claims" contract.
+ */
+export type ManifestValidationFailureCode = 'MANIFEST_MALFORMED' | 'MANIFEST_FIELD_EMPTY' | 'CLAIM_UNMEASURED';
+export interface ComparativeManifestV1 {
+    releaseName: string;
+    repairedBaselineRef?: string;
+    corpus?: {
+        taskPopulationPointer: string;
+        excludedTrainingCases: Array<{
+            caseId: string;
+            reason: string;
+        }>;
+    };
+    prRevisions?: Array<{
+        revision: string;
+        label: 'defect' | 'clean';
+    }>;
+    matchedBudgets?: {
+        model: string;
+        provider: string;
+        tool: string;
+        timeBudgetMs?: number;
+    };
+    sampleSizes: {
+        baseline: number;
+        ablation: number;
+        'simple-agent': number;
+    };
+    thresholds: Record<string, number>;
+    metricDefinitions?: Array<{
+        metric: string;
+        definition: string;
+    }>;
+    defectLabels: string[];
+    cleanLabels: string[];
+    claims: Array<{
+        kind: 'improvement' | 'negative';
+        metric: string;
+        measuredResult?: Record<string, number>;
+    }>;
+}
+export type ManifestValidationResult = {
+    ok: true;
+    manifest: ComparativeManifestV1;
+} | {
+    ok: false;
+    code: ManifestValidationFailureCode;
+    reason: string;
+};
+/**
+ * Validate a frozen comparative manifest. Accepts only fully-populated
+ * manifests; every rejection names the offending field. Unknown/malformed
+ * input fails closed with MANIFEST_MALFORMED rather than being coerced.
+ */
+export declare function validateComparativeManifest(input: unknown): ManifestValidationResult;

package/dist/services/harness-optimizer/oracle.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Independent oracle for the governed HarnessOpt capstone (issue #2503).
+ *
+ * Scores accepted task outcomes, artifact validity, verification evidence,
+ * and completion quality SEPARATELY from the optimizer and from the task's
+ * own scorer (src/evaluation/runner.ts scoreExecution). The oracle is the
+ * acceptance backstop the issue demands: a candidate whose token count
+ * improves while accepted artifact quality or verification evidence falls
+ * MUST be rejected, with reasons naming each drop.
+ */
+export type TokenCount = number | 'unknown';
+export interface OracleArmInput {
+    /** Task-population denominator for the arm. */
+    n: number;
+    /** Count of accepted artifacts the arm produced. */
+    acceptedArtifacts: number;
+    /** Count of verification-evidence records backing those artifacts. */
+    verificationEvidence: number;
+    tokens: {
+        input: TokenCount;
+        cache: TokenCount;
+        output: TokenCount;
+    };
+}
+export interface OracleVerdict {
+    verdict: 'accept' | 'reject';
+    reasons: string[];
+}
+/**
+ * Compare a candidate arm against the baseline arm. Acceptance requires
+ * the candidate to be no worse on accepted artifacts, verification
+ * evidence, or (when both arms report tokens) token usage. Any quality or
+ * verification drop rejects the candidate regardless of token improvement.
+ * Token totals reported as 'unknown' by the host are treated as unknown,
+ * never zero, and therefore never counted as an improvement axis.
+ */
+export declare function evaluateIndependentOracle(args: {
+    baseline: OracleArmInput;
+    candidate: OracleArmInput;
+}): Promise<OracleVerdict>;

package/opencode-swarm.schema.json

@@ -3769,6 +3769,48 @@
       },
       "additionalProperties": false
     },
+    "harness_opt": {
+      "description": "Governed HarnessOpt optimization capstone (issue #2503). Disabled by default; /swarm harness-opt run requires enabled: true plus --confirm.",
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "default": false,
+          "type": "boolean"
+        },
+        "max_rounds": {
+          "default": 5,
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 50
+        },
+        "max_transient_retries": {
+          "default": 2,
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 10
+        },
+        "max_wall_clock_ms": {
+          "default": 3600000,
+          "type": "integer",
+          "minimum": 10000,
+          "maximum": 86400000
+        },
+        "max_spend_usd": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1000
+        },
+        "run_ablation_arm": {
+          "default": true,
+          "type": "boolean"
+        },
+        "run_simple_agent_arm": {
+          "default": true,
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false
+    },
     "spec_writer": {
       "description": "Spec writer agent (v2) — independent model for .swarm/spec.md authorship.",
       "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencode-swarm",
-	"version": "7.180.1",
+	"version": "7.181.0",
 	"description": "Architect-centric agentic swarm plugin for OpenCode - hub-and-spoke orchestration with SME consultation, code generation, and QA review",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",