opencode-swarm 7.62.0 → 7.63.0

package/dist/services/directive-predicate-runner.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Directive verification predicate runner (Swarm Learning System, Change 2 /
+ * Task 2.2).
+ *
+ * Executes a small, fail-closed predicate DSL attached to a knowledge directive
+ * (`verification_predicate`). Handlers:
+ *
+ *   grep:<regex>:<path-glob>   PASS when ripgrep finds zero matches in the glob.
+ *                              (A "forbidden pattern" predicate: absence = pass.)
+ *   tool:<argv>                PASS when the command exits 0. Shell-free (argv
+ *                              array), binary must be on a conservative allowlist.
+ *   file_not_modified:<path>   PASS when <path> is unchanged in the working tree.
+ *   file_modified:<path>       PASS when <path> is changed in the working tree.
+ *
+ * Security posture (the adversarial contract):
+ *   - No shell, ever. Commands run via argv arrays (`bunSpawn`), so shell
+ *     metacharacters (; | && $() ` > <) are inert literals.
+ *   - Path/glob arguments are validated to stay inside the working directory:
+ *     null bytes, absolute paths, and `..` traversal are rejected.
+ *   - `tool:` binaries are restricted to a conservative read-only allowlist;
+ *     code interpreters (node/bun/python/deno/npx) are intentionally excluded.
+ *   - Hard 15s timeout; the child is killed on timeout.
+ *   - Fail-closed: any parse error, unknown handler, disallowed path, or
+ *     unexpected state returns `result:'error'` (never silently `pass`).
+ *
+ * Residual risk: true network isolation is not available in this runtime. The
+ * mitigation is the absence of network-capable binaries from the allowlist plus
+ * the hard timeout. Build tools that can run arbitrary scripts (cargo/go) are
+ * NOT on the allowlist for this reason.
+ */
+export type PredicateResult = 'pass' | 'fail' | 'error';
+export interface PredicateOutcome {
+    result: PredicateResult;
+    detail: string;
+}
+/** Hard wall-clock cap for any single predicate execution. */
+export declare const PREDICATE_TIMEOUT_MS = 15000;
+/**
+ * Conservative allowlist of `tool:` binaries. Read-only verification/lint tools
+ * only. Code interpreters and arbitrary build runners are deliberately excluded
+ * because they can execute attacker-influenced code or reach the network.
+ */
+export declare const TOOL_BINARY_ALLOWLIST: ReadonlySet<string>;
+/**
+ * Validate that a repo-relative path/glob stays inside `directory`. Returns the
+ * trimmed value on success or null when it is unsafe. Globs (`*`, `**`, `?`,
+ * `{}`) are permitted; traversal and absolute paths are not.
+ */
+export declare function validateRepoRelativeGlob(directory: string, value: string): string | null;
+interface RunResult {
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+}
+/** Run an argv array, shell-free, with a hard timeout. Never throws.
+ *  AGENTS.md invariant 3: stdin is 'ignore' (a never-closed stdin pipe can
+ *  block the child from exiting under Bun on Windows) and the child is
+ *  best-effort killed in `finally` so no code path leaks a process. */
+export declare function runArgv(argv: string[], cwd: string): Promise<RunResult>;
+/**
+ * Run a single verification predicate. Fail-closed: any parse error, unknown
+ * handler, or unexpected state returns `result:'error'`. Never throws.
+ */
+export declare function runDirectivePredicate(predicate: string, directory: string): Promise<PredicateOutcome>;
+export declare const _internals: {
+    validateRepoRelativeGlob: typeof validateRepoRelativeGlob;
+    runArgv: typeof runArgv;
+    runDirectivePredicate: typeof runDirectivePredicate;
+    TOOL_BINARY_ALLOWLIST: ReadonlySet<string>;
+};
+export {};

package/dist/services/knowledge-diagnostics.d.ts

@@ -27,6 +27,25 @@ export interface KnowledgeDebugMeta {
     event_count: number;
     retrieval_events_7d: number;
     cache_status: 'fresh' | 'stale' | 'unknown';
+    /**
+     * Learning-loop telemetry (Changes 1–6). Surfaces the health of the
+     * self-improvement pipeline: directives awaiting curation, reflection
+     * candidates not yet folded in, learned synonyms, and enforcement posture.
+     */
+    learning: {
+        /** Lessons withheld from the active store pending actionability (Change 4). */
+        unactionable_queue_depth: number;
+        /** Micro-reflection insight candidates not yet consumed by the curator (Change 6). */
+        insight_candidates_pending: number;
+        /** Learned tag co-occurrence synonym pairs on disk (Change 5). */
+        synonym_pairs: number;
+        /** Active directives in `enforce` posture (Change 3). */
+        enforced_directives: number;
+        /** Active directives that have been auto-escalated at least once (Change 3). */
+        escalated_directives: number;
+        /** Knowledge-event volume bucketed by type (applied/ignored/violated/...). */
+        events_by_type: Record<string, number>;
+    };
 }
 /**
  * Compute the debug-metadata block for the knowledge system. Best-effort: never

package/dist/services/skill-improver.d.ts

@@ -62,6 +62,17 @@ export interface SkillImproveResult {
         sourceKnowledgeIds: string[];
     }>;
     model?: string;
+    /** Change 4 (Task 4.3): outcome of the unactionable-knowledge hardening pass. */
+    unactionableHardening?: {
+        hardened: number;
+        retired: number;
+        remaining: number;
+    };
+    /** Change 6 (Task 5.3): macro trajectory-motif proposals written this run. */
+    macroMotifs?: {
+        motifs: number;
+        proposalsWritten: number;
+    };
 }
 interface InventorySnapshot {
     knowledge: {

package/dist/services/status-service.d.ts

@@ -1,4 +1,5 @@
 import type { AgentDefinition } from '../agents';
+import { type RecentEscalation } from '../hooks/knowledge-escalator';
 import { hasActiveFullAuto, hasActiveLeanTurbo } from '../state';
 import { loadLeanTurboRunState } from '../turbo/lean/state';
 /**
@@ -54,6 +55,8 @@ export interface StatusData {
     specStaleStoredHash?: string;
     /** Current spec.md hash on disk (null when spec.md is missing) */
     specStaleCurrentHash?: string | null;
+    /** Directives auto-escalated in the last 7 days (Change 3). */
+    recentEscalations?: RecentEscalation[];
 }
 /**
  * Get status data from the swarm directory.

package/dist/services/synonym-map.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Tag co-occurrence synonym map (Change 5 / Task 6.2).
+ *
+ * Retrieval is brittle when a query phrases a concept differently from the
+ * stored directive ("module mocks" vs "dependency seams"). Rather than ship a
+ * hand-curated thesaurus or a new NLP dependency, we learn synonyms from the
+ * corpus itself: tokens that repeatedly co-occur across an entry's
+ * triggers / tags / applies_to_tools / applies_to_agents are treated as
+ * related. A pair seen at or above `synonym_min_cooccurrence` distinct entries
+ * becomes a synonym edge that retrieval can expand a query along.
+ *
+ * State file: `.swarm/synonym-map.json` (validated through validateSwarmPath).
+ *
+ * SECURITY: the map is derived from on-disk knowledge entries, which can be
+ * attacker-influenced (auto-enrichment, hive imports). Every token is
+ * sanitised against control characters and length-bounded BEFORE it ever
+ * reaches the map, and the map is hard-capped (`synonym_map_max_pairs`,
+ * LRU-evicted by recency) so a flood of junk pairs cannot grow it without
+ * bound. Expansion is therefore bounded and cannot inject paths, regex
+ * metacharacters with effect, or arbitrarily long strings into the scorer.
+ */
+export declare const SYNONYM_MAP_FILENAME = "synonym-map.json";
+/** A single learned co-occurrence edge between two distinct tokens. */
+export interface SynonymPair {
+    /** Lexicographically-first member (sanitised). */
+    a: string;
+    /** Lexicographically-second member (sanitised). */
+    b: string;
+    /** Number of distinct entries in which both tokens co-occurred. */
+    count: number;
+    /** Monotonic recency marker (for LRU eviction). Higher = more recent. */
+    seq: number;
+}
+/** On-disk shape of `.swarm/synonym-map.json`. */
+export interface SynonymMap {
+    version: 1;
+    /** Monotonic counter; the next recorded/touched pair takes `seq = ++cursor`. */
+    cursor: number;
+    /** Keyed by `pairKey(a, b)`. */
+    pairs: Record<string, SynonymPair>;
+}
+export declare function emptySynonymMap(): SynonymMap;
+export declare function resolveSynonymMapPath(directory: string): string;
+/**
+ * Normalise a candidate token to its canonical synonym-map form, or return
+ * `null` if it is unusable. Strips control characters (poisoning defence),
+ * lowercases, collapses internal whitespace to single spaces, trims, and
+ * enforces a length bound. Non-string input yields `null`.
+ */
+export declare function sanitizeToken(raw: unknown): string | null;
+export declare function pairKey(a: string, b: string): string;
+/** A subset of KnowledgeEntry fields relevant to synonym learning. */
+export interface SynonymSourceEntry {
+    triggers?: string[];
+    tags?: string[];
+    applies_to_tools?: string[];
+    applies_to_agents?: string[];
+}
+/**
+ * Collect the sanitised, de-duplicated token set that represents one entry for
+ * co-occurrence learning. Draws from the entry's triggers, tags,
+ * applies_to_tools, and applies_to_agents.
+ */
+export declare function tokensForEntry(entry: SynonymSourceEntry): string[];
+/**
+ * Evict the least-recently-touched pairs until `map.pairs` is within
+ * `maxPairs`. Mutates `map` in place. Eviction order is by ascending `seq`
+ * (oldest first); ties broken by key for determinism.
+ */
+declare function evictToCap(map: SynonymMap, maxPairs: number): void;
+/**
+ * Pure: fold one entry's token set into the map, incrementing the co-occurrence
+ * count of every distinct token pair and refreshing its recency. Applies the
+ * LRU cap afterward. Returns the same `map` reference (mutated) for chaining.
+ *
+ * Each entry contributes at most +1 to any given pair (the token set is already
+ * de-duplicated), so a single entry repeating a tag cannot inflate a pair.
+ */
+export declare function recordEntryCooccurrences(map: SynonymMap, entry: SynonymSourceEntry, maxPairs?: number): SynonymMap;
+/**
+ * Pure: rebuild the synonym map from scratch over a list of entries. Used by the
+ * curator after phase_complete so the map reflects the current corpus rather
+ * than drifting monotonically. Returns a fresh map.
+ */
+export declare function buildSynonymMap(entries: SynonymSourceEntry[], maxPairs?: number): SynonymMap;
+/**
+ * Pure: derive an undirected adjacency index of synonyms from the map, keeping
+ * only pairs whose count is at or above `minCooccurrence`. Returns a Map from
+ * each token to the set of its synonym tokens.
+ */
+export declare function buildSynonymIndex(map: SynonymMap, minCooccurrence?: number): Map<string, Set<string>>;
+/**
+ * Pure: expand a list of query tokens with their learned synonyms. Input tokens
+ * are sanitised first so the caller can pass raw query terms. Returns only the
+ * NEW synonym tokens (never the originals), de-duplicated, with a per-token cap
+ * so one over-connected token cannot dominate the candidate pool. Synonyms are
+ * emitted in sorted order and sliced — recency is deliberately ignored so the
+ * result is deterministic regardless of insertion order.
+ */
+export declare function expandTokens(index: Map<string, Set<string>>, queryTokens: string[], maxPerToken?: number): string[];
+declare function isSynonymPair(value: unknown): value is SynonymPair;
+/**
+ * Coerce arbitrary parsed JSON into a valid SynonymMap, dropping any malformed
+ * or unsafe pairs. Re-sanitises every token and re-derives the canonical key so
+ * a tampered file (control chars, mismatched key) cannot smuggle a poisoned
+ * token into retrieval. Enforces the same `maxPairs` LRU cap on READ that the
+ * write path enforces, so a tampered file with a huge pair count cannot make
+ * every retrieval pay an unbounded coerce/index cost. Returns a fresh empty map
+ * on any structural failure.
+ */
+export declare function coerceSynonymMap(parsed: unknown, maxPairs?: number): SynonymMap;
+/**
+ * Read and validate the synonym map. Returns an empty map if absent/invalid.
+ * Bounded: a file larger than the `maxPairs`-derived byte ceiling is ignored
+ * WITHOUT being parsed, so a tampered/oversized map cannot blow up memory or CPU
+ * on the retrieval hot path. `maxPairs` is also enforced as an LRU cap on the
+ * coerced result.
+ */
+export declare function readSynonymMap(directory: string, maxPairs?: number): Promise<SynonymMap>;
+declare function writeSynonymMapAtomic(filePath: string, map: SynonymMap): Promise<void>;
+/**
+ * Atomically rebuild the synonym map from the supplied entries under a
+ * directory lock and persist it. Returns the written map. Intended to be called
+ * by the curator after phase_complete. Bounded by `maxPairs`.
+ */
+export declare function rebuildSynonymMap(directory: string, entries: SynonymSourceEntry[], maxPairs?: number): Promise<SynonymMap>;
+export declare const _internals: {
+    MAX_TOKEN_LENGTH: number;
+    DEFAULT_MAX_PAIRS: number;
+    DEFAULT_MIN_COOCCURRENCE: number;
+    DEFAULT_MAX_EXPANSIONS_PER_TOKEN: number;
+    evictToCap: typeof evictToCap;
+    isSynonymPair: typeof isSynonymPair;
+    writeSynonymMapAtomic: typeof writeSynonymMapAtomic;
+};
+export {};

package/dist/services/trajectory-cluster.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Macro-reflector trajectory clustering (Swarm Learning System, Change 6 /
+ * Task 5.3).
+ *
+ * On the skill-improver's scheduled (quota-gated) cadence, scan the last N task
+ * trajectories (`.swarm/evidence/<taskId>/trajectory.jsonl`), cluster repeated
+ * FAILURE motifs by a (tool, kind) signature, and emit one skill PROPOSAL per
+ * recurring motif to `.swarm/skills/proposals/`. Each proposal carries full
+ * provenance: a draft SKILL.md body, the cluster of source task ids (and any
+ * source knowledge ids), a verification predicate, and `applies_to_agents`.
+ *
+ * Read-only over the knowledge store; writes only proposal markdown (never
+ * active skills). Fail-open.
+ */
+/** Trajectories scanned per macro pass (the plan's N=200 window). */
+export declare const MACRO_TRAJECTORY_WINDOW = 200;
+/** A motif must recur across at least this many distinct tasks to propose. */
+export declare const MOTIF_MIN_TASKS = 2;
+export interface FailureMotif {
+    signature: string;
+    tool: string;
+    kind: string;
+    agent: string;
+    taskIds: string[];
+    sampleVerdicts: string[];
+}
+/**
+ * Cluster failure motifs across the recent trajectory window. Returns motifs
+ * that recur across >= MOTIF_MIN_TASKS distinct tasks, most-frequent first.
+ */
+export declare function gatherFailureMotifs(directory: string, opts?: {
+    window?: number;
+    minTasks?: number;
+}): Promise<FailureMotif[]>;
+/** Render a draft SKILL.md proposal body for a motif (with full provenance). */
+export declare function buildMotifProposal(motif: FailureMotif): string;
+export interface MotifProposalResult {
+    motifs: number;
+    proposalsWritten: string[];
+}
+/**
+ * Run the macro motif pass and write one proposal per recurring motif. Returns
+ * the written proposal paths. Fail-open; never throws.
+ */
+export declare function writeMotifProposals(directory: string, opts?: {
+    window?: number;
+    minTasks?: number;
+    maxProposals?: number;
+}): Promise<MotifProposalResult>;

package/dist/services/unactionable-hardening.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Unactionable-knowledge hardening loop (Swarm Learning System, Change 4 /
+ * Task 4.3).
+ *
+ * Consumes `.swarm/knowledge-unactionable.jsonl` (entries quarantined by the
+ * Layer-5 actionability gate) during the skill-improver macro loop. For each
+ * queued entry it attempts to produce a hardened version with predicates +
+ * scope tags via the same quota-gated v3 enrichment used by the curator
+ * (Task 4.2). Entries that pass Layer 5 after hardening move from quarantined
+ * to the active store as candidates; entries that fail are marked
+ * `retire_candidate:true` (left in the queue for human review / eventual
+ * retirement). Already-marked retire candidates are never re-processed.
+ *
+ * Quota: every LLM attempt goes through `enrichLessonToV3`, which reserves one
+ * skill-improver quota slot per call — the loop can never exceed the shared
+ * daily budget. A per-run batch cap bounds worst-case cost further.
+ */
+import type { CuratorLLMDelegate } from '../hooks/curator.js';
+import { type EnrichmentQuotaOptions } from '../hooks/knowledge-curator.js';
+import { type UnactionableRecord } from '../hooks/knowledge-validator.js';
+/** Max queue entries processed per improver run (bounds LLM cost per run). */
+export declare const HARDENING_BATCH_LIMIT = 5;
+/** Queue record shape with the retire flag added by this loop. */
+export interface HardenableRecord extends UnactionableRecord {
+    retire_candidate?: boolean;
+}
+export interface HardeningResult {
+    /** Entries promoted from the queue to the active store. */
+    hardened: number;
+    /** Entries newly marked retire_candidate (hardening failed). */
+    retired: number;
+    /** Entries left in the queue (including pre-existing retire candidates). */
+    remaining: number;
+}
+/**
+ * Run one hardening pass. Never throws; on any error the queue is left as-is
+ * and zeros are reported. No-op (besides counting) when no delegate is
+ * available — without an LLM there is no hardening attempt, and auto-retiring
+ * without an attempt would be wrong.
+ */
+export declare function hardenUnactionableEntries(params: {
+    directory: string;
+    llmDelegate?: CuratorLLMDelegate;
+    quota?: EnrichmentQuotaOptions;
+    batchLimit?: number;
+    dedupThreshold?: number;
+}): Promise<HardeningResult>;

package/dist/state.d.ts

@@ -334,6 +334,23 @@ export declare const swarmState: {
  * Reset all state to initial values - useful for testing
  */
 export declare function resetSwarmState(): void;
+/**
+ * Reset swarm state while preserving the 7 module-scoped singletons that are
+ * populated once at plugin init and must survive a /swarm close + re-init
+ * within the same process lifetime.
+ *
+ * The preserved fields are:
+ * - opencodeClient (SDK client for curator/full-auto delegation)
+ * - fullAutoEnabledInConfig (config flag read at init)
+ * - curatorInitAgentNames, curatorPhaseAgentNames (curator registry)
+ * - skillImproverAgentNames, specWriterAgentNames (skill/spec registry)
+ * - generatedAgentNames (full-auto delegation guard registry)
+ *
+ * Implementation: save all 7 to locals, call resetSwarmState(), restore all 7.
+ * Synchronous (matches resetSwarmState contract). Errors from resetSwarmState
+ * propagate to caller (no try/catch wrapper).
+ */
+export declare function resetSwarmStatePreservingSingletons(): void;
 /**
  * Start a new agent session with initialized guardrail state.
  * Also removes any stale sessions older than staleDurationMs.

package/dist/tools/phase-complete.d.ts

@@ -13,6 +13,16 @@ export interface PhaseCompleteArgs {
     summary?: string;
     /** Session ID to track state (optional, defaults to current session context) */
     sessionID?: string;
+    /**
+     * Architect-only (Change 2, Task 2.4): explicitly accept these unresolved
+     * critical directive IDs. Requires acceptViolationsJustification. Each
+     * accepted id is logged as an `override` knowledge event.
+     */
+    acceptViolations?: string[];
+    /** Written justification required to use acceptViolations. */
+    acceptViolationsJustification?: string;
+    /** Calling agent identity (from tool ctx) — gates the override to the architect. */
+    callerAgent?: string;
 }
 export declare const MAX_OUTPUT_BYTES = 512000;
 /**

package/package.json

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