opencode-swarm 7.181.1 → 7.181.3

package/dist/memory/index.d.ts

@@ -7,6 +7,7 @@ export type { MemoryGatewayOptions, ProposeMemoryInput, RecallMemoryInput, Recor
 export { createConfiguredMemoryProvider, createConfiguredMemoryProviderForRoot, createMemoryGateway, MemoryGateway, } from './gateway';
 export { type HeldoutRecallCorpusCase, type HeldoutRecallCorpusManifest, type LoadedHeldoutRecallScenario, loadHeldoutRecallEvaluationCorpus, loadHeldoutRecallEvaluationScenarios, validateHeldoutRecallCorpusManifest, } from './heldout-evaluation-corpus';
 export { createMemoryLifecycleHooks, type MemoryLifecycleHookOptions, type MemoryLifecycleHooks, } from './injector';
+export { DEFAULT_INSTRUCTION_PAIRING_TASKS, type InstructionPairingArmResult, type InstructionPairingDirectivePriority, type InstructionPairingOptions, type InstructionPairingPair, type InstructionPairingRecord, type InstructionPairingReport, type InstructionPairingTask, runInstructionSelectionPairing, } from './instruction-pairing';
 export { backupLegacyJsonl, getLegacyJsonlFileStatus, getLegacyOutcomeJsonlSignature, type JsonlBackupResult, type JsonlImportPayload, type JsonlInvalidRow, type JsonlMigrationReport, LEGACY_JSONL_MIGRATION_NAME, LEGACY_JSONL_MIGRATION_VERSION, LEGACY_JSONL_OUTCOME_META_KEY, readLegacyJsonl, readMigrationReport, resolveMemoryStorageDir, resolveSqliteDatabasePath, writeJsonlExport, writeMigrationReport, } from './jsonl-migration';
 export { LocalJsonlMemoryProvider } from './local-jsonl-provider';
 export { buildMemoryMaintenanceReport, type MemoryMaintenanceReport, type MemoryMaintenanceReportOptions, type MemoryRecallUsageByMemory, type MemoryRecallUsageByRole, type MemorySupersededChain, shouldCompactMemory, } from './maintenance';

package/dist/memory/instruction-pairing.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Paired cached-vs-uncached outcome evidence for instruction selection (#2672).
+ *
+ * Runs the REAL knowledge-injector hook (the plugin's instruction-selection and
+ * instruction-cache surface) over deterministic, offline fixture tasks and
+ * reports paired per-task outcomes: quality (which directive labels survive
+ * selection), latency per arm, cache reads, uncached cost, and the rendered
+ * prefix length at the host-renderable carrier boundary.
+ *
+ * Contract discipline (issue #2672):
+ * - Same task/model/budget on both arms; the uncached arm is the regeneration
+ *   reference and the cached arm replays byte-identical context on a warm
+ *   per-instance cache.
+ * - Negative results are RETAINED rows (`negative_result: true` when the
+ *   cached arm did not improve the paired quality outcome). On the offline
+ *   deterministic corpus both arms run the same selection algorithm over the
+ *   same records, so `quality_outcome` is 'identical' by design — the honest
+ *   "caching did not change instruction quality" negative result.
+ * - NO percentage or savings claim exists anywhere in the report: deltas are
+ *   absolute numbers and every quantity names its denominator in `measurement`.
+ * - `identity.instruction_set_digest` is the evidence handle a HarnessOpt
+ *   lineage record (#2503) can reference; this module never modifies the
+ *   harness-optimizer — #2503 remains the broad held-out comparison owner.
+ */
+export type InstructionPairingDirectivePriority = 'critical' | 'high' | 'medium' | 'low';
+export interface InstructionPairingRecord {
+    /**
+     * Stable identifier recovered from the rendered prefix. Constrained to
+     * `[A-Za-z0-9-]` (PRR-012): other characters still reach the fixture
+     * store verbatim but can never be matched back by the sentinel pattern,
+     * silently undercounting `quality.expected_hit_count` for that record.
+     */
+    label: string;
+    lesson: string;
+    directivePriority?: InstructionPairingDirectivePriority;
+    tags?: string[];
+}
+export interface InstructionPairingTask {
+    id: string;
+    lastUserMessage: string;
+    expectedLabels: string[];
+    records: InstructionPairingRecord[];
+}
+export interface InstructionPairingOptions {
+    /**
+     * Project directory context. Fixture stores live in disposable temp roots
+     * (never under the caller's `.swarm/`); when `writeReport` is set, the
+     * durable report artifact is written under this directory's
+     * `.swarm/memory/`.
+     */
+    directory: string;
+    /** Omitted falls back to the deterministic DEFAULT_INSTRUCTION_PAIRING_TASKS. */
+    tasks?: InstructionPairingTask[];
+    modelId?: string;
+    injectCharBudget?: number;
+    /** Explicit report destination; overrides the `writeReport` default path. */
+    reportPath?: string;
+    /** Write the report to `<directory>/.swarm/memory/instruction-pairing-report.json`. */
+    writeReport?: boolean;
+}
+export interface InstructionPairingArmResult {
+    latency_ms: number;
+    /** Injections served from the warm context cache in the measured invocation (0 or 1). */
+    cache_reads: number;
+    /** How cache_reads was determined ('events-file-delta' = observed, 'protocol-assumed' = identical-context replay). */
+    cache_reads_basis: string;
+    rendered_prefix_chars: number;
+    /** The paired uncached arm's regeneration latency, reported on both arms (paired attribution, absolute ms). */
+    uncached_cost: number;
+    quality: {
+        expected_hit_count: number;
+        expected_total: number;
+        selected_labels: string[];
+    };
+}
+export interface InstructionPairingPair {
+    task: {
+        id: string;
+    };
+    arm_cached: InstructionPairingArmResult;
+    arm_uncached: InstructionPairingArmResult;
+    quality_outcome: 'identical' | 'improved' | 'degraded';
+    negative_result: boolean;
+}
+export interface InstructionPairingReport {
+    schema_version: 1;
+    generated_at: string;
+    identity: {
+        task_set_id: string;
+        model_id: string;
+        budget_chars: number;
+        instruction_set_digest: string;
+    };
+    pairs: InstructionPairingPair[];
+    measurement: {
+        latency_denominator: string;
+        cost_denominator: string;
+        prefix_denominator: string;
+    };
+    negative_results_retained: boolean;
+    cache_invalidation: {
+        verified: boolean;
+        detail: string;
+    };
+}
+/** Deterministic offline corpus used when `options.tasks` is omitted. */
+export declare const DEFAULT_INSTRUCTION_PAIRING_TASKS: InstructionPairingTask[];
+/**
+ * Runs the paired cached-vs-uncached control over the task set and returns the
+ * report. Deterministic and offline (lexical store, hive disabled, real hook).
+ */
+export declare function runInstructionSelectionPairing(options: InstructionPairingOptions): Promise<InstructionPairingReport>;

package/dist/services/model-preflight.d.ts

@@ -1,18 +1,21 @@
 /**
- * Agent model-resolution preflight (issue #2271 bug 4).
+ * Agent model-resolution preflight (issue #2271 bug 4; issue #2680).
  *
- * Agent model strings (DEFAULT_MODELS plus user `agents.<role>.model`
- * overrides) are handed to the OpenCode host unvalidated. When one does not
- * resolve ("Model not found", "Forbidden"), dispatch-lanes classifies the
- * failure as permanent, the affected agent never runs, and the plan-critic
- * gate wedges into manual `approve_plan_critic` overrides because no APPROVED
- * verdict is ever produced.
+ * Agent model strings (DEFAULT_MODELS plus user `agents.<role>.model` /
+ * `swarms.<id>.agents.<role>.model` overrides) are handed to the OpenCode host
+ * unvalidated. When one does not resolve ("Model not found", "Forbidden"),
+ * dispatch-lanes classifies the failure as permanent, the affected agent never
+ * runs, and the plan-critic gate wedges into manual `approve_plan_critic`
+ * overrides because no APPROVED verdict is ever produced.
  *
- * This module validates configured model IDs against the live provider
- * catalog (`client.provider.list()`). Every check is FAIL-OPEN: if the catalog
- * is unreachable or malformed, results come back `unknown` and callers must
- * proceed — the preflight only acts on a POSITIVE confirmation that a model
- * does not resolve.
+ * This module validates the FINAL effective model selection for every ENABLED
+ * legacy and prefixed multi-swarm role (issue #2680) against the live provider
+ * catalog (`client.provider.list()`), reusing the exact-name resolution
+ * helpers from src/config/agent-model.ts. Every check is FAIL-OPEN: if the
+ * catalog is unreachable or malformed, results come back `unknown` and callers
+ * must proceed — the preflight only acts on a POSITIVE confirmation that a
+ * model does not resolve (or that no final selection exists at all, the
+ * catalog-independent `missing-selection` class).
  */
 import type { OpencodeClient } from '@opencode-ai/sdk';
 import type { PluginConfig } from '../config/schema.js';
@@ -21,12 +24,17 @@ export declare const PROVIDER_LIST_TIMEOUT_MS = 2000;
 export interface ConfiguredAgentModel {
     /** Agent role the model is configured for. */
     agent: string;
-    /** Full model id in `provider/model` form. */
+    /** Full model id in `provider/model` form. Empty when no final selection exists. */
     model: string;
     /** Where the value came from. */
     source: 'default' | 'override' | 'fallback';
+    /**
+     * Issue #2680: whether the entry's role is registered as a primary agent
+     * (OpenCode's UI owns its model selection) or a dispatchable subagent.
+     */
+    mode?: 'primary' | 'subagent';
 }
-export type ModelResolutionStatus = 'ok' | 'unresolved' | 'unknown';
+export type ModelResolutionStatus = 'ok' | 'unresolved' | 'unknown' | 'missing-selection' | 'host-controlled';
 export interface ModelResolution {
     agent: string;
     model: string;
@@ -34,6 +42,7 @@ export interface ModelResolution {
     status: ModelResolutionStatus;
     /** Human-readable explanation for non-ok statuses. */
     detail?: string;
+    mode?: ConfiguredAgentModel['mode'];
 }
 export interface ModelPreflightResult {
     /** False when the catalog could not be fetched — every entry is `unknown`. */
@@ -53,29 +62,102 @@ export declare function splitModelId(model: string): {
  * Collect every model id the swarm could dispatch with: DEFAULT_MODELS
  * entries, user agent overrides, and declared fallback_models. Overriding one
  * role replaces its default (mirrors getModelForAgent precedence).
+ *
+ * Superseded by collectEnabledAgentModels (issue #2680): this legacy view
+ * enumerates the top-level config plus a blanket DEFAULT_MODELS pass and
+ * cannot see multi-swarm per-swarm selections or enabled-role gating. Retained
+ * unchanged for API compatibility; runModelPreflight no longer consumes it.
  */
 export declare function collectConfiguredAgentModels(config?: PluginConfig): ConfiguredAgentModel[];
+/**
+ * Issue #2680: compute the generated agent names the plugin would register for
+ * this configuration — the "enabled role" domain the preflight must validate.
+ * Mirrors createAgents' generation rules (legacy single default swarm vs
+ * per-swarm prefixing; object-level top-level merge; disabled exclusion;
+ * feature-gated roles only while their flag is on). The live
+ * swarmState.generatedAgentNames registry stays authoritative when available;
+ * this computation is the config-only fallback (doctor, unit tests) and is
+ * drift-guarded by the parity test.
+ */
+export declare function enumerateEnabledAgentRoles(config?: PluginConfig): string[];
+/** Options for the enabled-role preflight (issue #2680). */
+export interface EnabledAgentPreflightOptions {
+    /**
+     * The live registry of generated agent names the host actually registered
+     * (swarmState.generatedAgentNames). Authoritative when provided; the
+     * config-only enumeration is the fallback.
+     */
+    generatedAgentNames?: readonly string[];
+    /**
+     * The registered agents map (name → { model, mode }) as produced by
+     * createAgents/getAgentConfigs. When provided, `mode` comes from it;
+     * otherwise primaries are derived via resolvePrimaryAgentNames.
+     */
+    registeredAgents?: Record<string, {
+        model?: unknown;
+        mode?: unknown;
+    }>;
+}
+/**
+ * Issue #2680: collect the FINAL effective model selection for every enabled
+ * legacy and prefixed multi-swarm role, plus each role's explicitly configured
+ * fallback entries. Final selections are computed with the shipped exact-name
+ * helpers (resolveRegisteredAgentModel / resolveConfiguredAgentModel) so
+ * defaults, swarm prefixes, and the object-level merge match dispatch reality.
+ *
+ * Outcome classes (see resolveAgainstCatalog):
+ * - an explicitly configured but blank model, or a registry name that resolves
+ *   to no target at all, yields an EMPTY model — the distinct
+ *   `missing-selection` class (never silently treated as a successful default);
+ * - primary roles are tagged `mode: 'primary'` → `host-controlled` (OpenCode's
+ *   UI owns their selection);
+ * - fallback entries appear only when explicitly configured and recorded —
+ *   never synthesized (curator roles inherit explorer's chain at runtime via
+ *   resolveFallbackModel; that inheritance is documented, not duplicated here).
+ */
+export declare function collectEnabledAgentModels(config?: PluginConfig, opts?: EnabledAgentPreflightOptions): ConfiguredAgentModel[];
 /** Provider catalog snapshot: provider id → set of model ids. */
 export type ProviderCatalog = Map<string, Set<string>>;
 /** Test/gate seam: drop the cached catalogs (used after config changes and denials). */
 export declare function invalidateProviderCatalogCache(): void;
+/**
+ * PR #2782 review PRR-001: neutralize control characters before interpolating
+ * config- or host-sourced strings (model ids, agent names, provider detail)
+ * into console.warn / thrown-Error text. Newlines forge multi-line
+ * plugin-looking output and ESC sequences drive the terminal; control runs
+ * collapse to a single space (same policy as the doctor's stripControlChars).
+ */
+export declare function sanitizePreflightText(value: string): string;
 /**
  * Fetch the provider catalog. Returns null when the catalog cannot be
  * obtained or parsed — callers fail open on null.
  */
 export declare function fetchProviderCatalog(client: OpencodeClient | null): Promise<ProviderCatalog | null>;
 /**
- * Validate collected models against a catalog. A model whose provider is
- * absent from the catalog, or whose provider exists but does not list the
- * model, is `unresolved` — but only when the catalog itself was successfully
- * fetched (callers must treat a null catalog as fail-open, never unresolved).
+ * Validate collected models against a catalog. Classification order (issue
+ * #2680): an EMPTY model is the catalog-independent `missing-selection` class;
+ * a primary role is `host-controlled` (OpenCode's UI owns its selection —
+ * never a preflight failure and never a consumer-default warning); otherwise
+ * the catalog decides — a model whose provider is absent from the catalog, or
+ * whose provider exists but does not list the model, is `unresolved` — but
+ * only when the catalog itself was successfully fetched (callers must treat a
+ * null catalog as fail-open, never unresolved).
  */
 export declare function resolveAgainstCatalog(models: ConfiguredAgentModel[], catalog: ProviderCatalog | null): ModelPreflightResult;
 /**
- * End-to-end preflight: collect configured models, fetch the catalog, and
- * resolve. Fail-open on every catalog error.
+ * Issue #2680: render the operator warning for a preflight result. Reports
+ * ONLY actionable classes (`unresolved`, `missing-selection`) — ok/unknown
+ * entries and host-controlled primaries stay silent, so disabled, optional,
+ * and merely-uninvoked roles never produce consumer-default noise. Returns
+ * null when there is nothing to report.
+ */
+export declare function formatModelPreflightWarning(result: ModelPreflightResult): string | null;
+/**
+ * End-to-end preflight: collect the FINAL effective selection for every
+ * enabled role (issue #2680), fetch the catalog, and resolve. Fail-open on
+ * every catalog error.
  */
-export declare function runModelPreflight(config: PluginConfig | undefined, client: OpencodeClient | null): Promise<ModelPreflightResult>;
+export declare function runModelPreflight(config: PluginConfig | undefined, client: OpencodeClient | null, opts?: EnabledAgentPreflightOptions): Promise<ModelPreflightResult>;
 /**
  * Resolves a single model id against the live catalog for gate preflights.
  * Returns 'unknown' whenever the catalog cannot be fetched — gates must only

package/dist/session/restart-reconciliation.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Owner-named restart reconciliation (issue #2668).
+ *
+ * At the rehydrate boundary, ephemeral execution authority expires by design
+ * (`delegationActive` and friends are reset in
+ * `TRANSIENT_SESSION_FIELDS`) — but the expiry must not be silent. When a
+ * serialized session arrives with in-flight authority, the boundary records a
+ * bounded, owner-named reconciliation outcome so an operator (and the
+ * resumed session) can tell "interrupted mid-execution, outcome UNKNOWN"
+ * from "was idle": absence must never read as success.
+ *
+ * Two surfaces, written together inside the rehydrate populate loop (after
+ * the transient reset, before the caller proceeds to the projection write):
+ *
+ * 1. The durable artifact `.swarm/session/restart-reconciliation.json` — a
+ *    bounded list (cap {@link MAX_RESTART_RECONCILIATION_ENTRIES}, FIFO
+ *    overflow) deduped by `(sessionId, taskId)` so a repeated restart
+ *    refreshes the entry instead of duplicating it.
+ * 2. A one-shot advisory string pushed into the rehydrated session's
+ *    `pendingAdvisoryMessages` (per-restart; the next rehydrate re-derives
+ *    it).
+ *
+ * The record deliberately COMPOSES the shipped recovery surfaces instead of
+ * duplicating them: guidance points operators at `/swarm recover` (stale
+ * coder-settlement WALs) and `/swarm status` (uncertain provider effects),
+ * and the #2665 `stale`/`ambiguous`/`live_wedge` classification for
+ * coder settlements remains owned by those stores.
+ */
+/** Relative to the project root's `.swarm/` directory. */
+export declare const RESTART_RECONCILIATION_FILE = "session/restart-reconciliation.json";
+export declare const MAX_RESTART_RECONCILIATION_ENTRIES = 50;
+export type RestartReconciliationClassification = 'interrupted';
+export interface RestartReconciliationEntry {
+    sessionId: string;
+    agentName: string;
+    /** The task the interrupted execution was driving ('(unknown)' when the snapshot carried none). */
+    taskId: string;
+    classification: RestartReconciliationClassification;
+    observedAt: string;
+    guidance: string;
+}
+export interface RestartReconciliationFile {
+    version: 1;
+    entries: RestartReconciliationEntry[];
+}
+export declare const RESTART_RECONCILIATION_GUIDANCE = "outcome UNKNOWN \u2014 do not assume success; inspect /swarm status for uncertain provider effects; /swarm recover settles stale coder-settlement WALs; a human must resolve external effects (pushed commits, published PRs) manually";
+/**
+ * Read the reconciliation artifact fail-closed: absent, corrupt, partial, or
+ * oversized files read as an empty list — the boundary then re-records what
+ * it observes and the artifact heals on the next append.
+ */
+export declare function readRestartReconciliation(directory: string): RestartReconciliationFile;
+/**
+ * Append (or refresh, keyed by `(sessionId, taskId)`) a reconciliation entry
+ * and persist the bounded list atomically. Fail-open: a write error is
+ * logged and swallowed — the reconciliation record must never fail the
+ * rehydrate that produces it.
+ */
+export declare function recordInterruptedExecution(directory: string, entry: {
+    sessionId: string;
+    agentName: string;
+    taskId: string;
+    observedAt?: string;
+    guidance?: string;
+}): Promise<RestartReconciliationEntry>;
+/**
+ * The one-shot session advisory naming the owner of the interrupted effect.
+ * Pushed into `pendingAdvisoryMessages` AFTER the transient-field reset so
+ * it survives the rehydrate that produced it.
+ */
+export declare function buildInterruptedAdvisoryDedupeKey(entry: Pick<RestartReconciliationEntry, 'sessionId' | 'taskId'>): string;
+export declare function buildInterruptedAdvisoryMessage(entry: Pick<RestartReconciliationEntry, 'sessionId' | 'agentName' | 'taskId'> & {
+    guidance?: string;
+}): string;

package/dist/state.d.ts

@@ -417,9 +417,12 @@ export interface AgentSessionState {
     autoProceedNudgeDone?: boolean;
     /** Session-level QA gate overrides layered on top of the spec-level profile.
      *  Overrides can only enable gates (true); false values are ignored by
-     *  getEffectiveGates. Cleared on session reset. Optional for backwards
-     *  compatibility with pre-existing session state fixtures; consumers
-     *  should read via `session.qaGateSessionOverrides ?? {}`. */
+     *  getEffectiveGates. Durable runtime policy (#2668): the authoritative copy
+     *  lives in the project DB (qa_gate_session_override), written durable-first
+     *  by `/swarm qa-gates override`, restored by rehydrateState, and deleted in
+     *  lockstep with the session (end/stale-eviction/reset). Optional for
+     *  backwards compatibility with pre-existing session state fixtures;
+     *  consumers should read via `session.qaGateSessionOverrides ?? {}`. */
     qaGateSessionOverrides?: Partial<QaGates>;
     /** Session-scoped Full Auto flag for autonomous multi-agent oversight */
     fullAutoMode: boolean;

package/dist/tools/get-qa-gate-profile.d.ts

@@ -3,12 +3,15 @@
  *
  * Read-only: uses plan.json identity when available or an explicit exact
  * swarm/title pair before plan creation, then looks up the profile in the
- * per-project DB. Returns the spec-level profile gates, lock state, and profile
- * hash. Callers layering session overrides should combine with
- * `getEffectiveGates` themselves — this tool intentionally returns the
- * persisted/locked spec-level view.
+ * per-project DB. Returns the spec-level profile gates, lock state, and
+ * profile hash, plus — when the caller carries a session context (#2668) —
+ * the session's ratchet-tighter overrides and the EFFECTIVE gates (profile
+ * merged with those overrides) so an agent can inspect the effective
+ * runtime policy after a restart. The live session's override cache is
+ * authoritative when present; the durable `qa_gate_session_override` row is
+ * the restart authority consulted when the live session is absent.
  */
-import type { tool } from '@opencode-ai/plugin';
+import type { ToolContext, tool } from '@opencode-ai/plugin';
 import { type QaGatePlanIdentityArgs } from './qa-gate-plan-identity.js';
 export type GetQaGateProfileArgs = QaGatePlanIdentityArgs;
 interface GetQaGateProfileResult {
@@ -25,7 +28,11 @@ interface GetQaGateProfileResult {
         created_at: string;
         profile_hash: string;
     };
+    /** Calling session's ratchet-tighter overrides (empty when no session context or none set). */
+    session_overrides?: Record<string, boolean>;
+    /** Effective gates: profile merged with the calling session's overrides (#2668). */
+    effective_gates?: Record<string, boolean>;
 }
-export declare function executeGetQaGateProfile(args: GetQaGateProfileArgs, directory: string): Promise<GetQaGateProfileResult>;
+export declare function executeGetQaGateProfile(args: GetQaGateProfileArgs, directory: string, ctx?: ToolContext): Promise<GetQaGateProfileResult>;
 export declare const get_qa_gate_profile: ReturnType<typeof tool>;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencode-swarm",
-	"version": "7.181.1",
+	"version": "7.181.3",
 	"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",