opencode-swarm 7.141.2 → 7.142.0

package/dist/knowledge/hive-quarantine.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Human-only exact-ID quarantine for the machine-global hive knowledge store (issue #2033).
+ *
+ * Problem: the hive store (`shared-learnings.jsonl`, resolved by
+ * `src/knowledge/hive-paths.ts`) has been polluted by leaked test fixtures, and no safe
+ * remediation existed: `quarantineEntry` is swarm-tier only, `knowledge_archive` refuses
+ * hive-tier quarantine, and bulk text scrubbing would destroy legitimate lessons (a real
+ * store may legitimately contain test-like text). Parent #1823: never bulk delete.
+ *
+ * This module implements the adjudicated exact-ID flow:
+ *   preview   — read-only snapshot of exact candidate IDs, per-entry hashes/provenance, a
+ *               store fingerprint, and a confirmation token bound to preview + store +
+ *               plugin version (TTL-bounded) AND HMAC-signed with a per-install secret
+ *               (not derivable from store contents — PR #2200 review CC-1).
+ *   commit    — a validated backup + manifest written and hash-verified BEFORE any
+ *               mutation (outside the hive lock, keeping the locked closure fast per
+ *               hive-transaction's contract), then ONE `transactHiveStore` transaction
+ *               that re-verifies the live file hash against the backup under lock (any
+ *               drift — including duplicate-id ambiguity — aborts with no mutation;
+ *               clean aborts clean up the orphaned backup dir), quarantines EXACTLY the
+ *               selected IDs with audit + sidecar records staged under the lock, and
+ *               verifies counts afterwards with an HONEST auto-restore report (a failed
+ *               restore is never claimed as success).
+ *   rollback  — idempotent restore of the EXACT original line bytes from the manifest's
+ *               backup, aborting on collision (an id re-promoted with different content).
+ *               Backup lookup resolves symlinks/reparse points on BOTH sides — a lexical
+ *               prefix compare alone is dead code against a planted link (review CC-4).
+ *
+ * Selection is EXACT-ID only: no text, substring, "test-looking phrase", cohort, age, or
+ * blacklist matching exists anywhere in this module, and there is no bulk operation.
+ *
+ * Byte-fidelity note: restored ids are written through the transaction's
+ * `rawLineOverrides` channel as the EXACT original line bytes, and every restore is
+ * verified against the manifest's `raw_line_sha256` (hex sha256 of the line bytes
+ * INCLUDING the trailing newline) before success is reported. Two standing-transaction
+ * disclosures apply to everything EXCEPT the selected ids: unselected entries may be
+ * re-serialized by the normalize-on-read pipeline, and unparseable (corrupt) lines are
+ * DROPPED by any commit rewrite — they survive only in the hash-verified backup copy,
+ * from which they can be recovered manually.
+ *
+ * The module holds no module-level mutable state (invariant 8) and performs no work on
+ * the plugin-init path (invariant 1) — it is loaded only by the human-only
+ * `knowledge hive-quarantine` command dispatch.
+ */
+import { chmod, copyFile, mkdir, readdir, readFile, realpath, rm, stat, writeFile } from 'node:fs/promises';
+import { transactHiveStore } from '../hooks/hive-transaction.js';
+import { emit } from '../telemetry.js';
+import { resolveHiveDataDir, resolveHiveKnowledgePath } from './hive-paths.js';
+/** Confirmation token TTL (freshness window). */
+export declare const HIVE_QUARANTINE_TOKEN_TTL_MS: number;
+/** Upper bound of exact IDs per operation (tokens embed per-id hashes). */
+export declare const MAX_IDS_PER_OPERATION = 200;
+/** Quarantine sidecar living beside the store in the hive data dir. */
+export declare const HIVE_QUARANTINE_SIDECAR = "shared-learnings-quarantined.jsonl";
+/** Backup directory root inside the hive data dir. */
+export declare const HIVE_QUARANTINE_BACKUP_DIR = "quarantine-backups";
+export type HiveQuarantineAbortCode = 'invalid_ids' | 'id_not_found' | 'duplicate_id' | 'duplicate_id_in_store' | 'too_many_ids' | 'invalid_token' | 'token_expired' | 'store_drift' | 'id_changed' | 'id_missing' | 'version_changed' | 'backup_failed' | 'backup_corrupt' | 'backup_not_found' | 'rollback_collision' | 'ambiguous_backup' | 'transaction_failed';
+export interface HiveQuarantinePreviewRecord {
+    id: string;
+    tier: string;
+    status: string;
+    confidence: number;
+    category: string;
+    source_project?: string;
+    lineage_actor?: string;
+    created_at: string;
+    updated_at: string;
+    content_hash?: string;
+    raw_line_sha256: string;
+}
+export interface HiveQuarantinePreview {
+    records: HiveQuarantinePreviewRecord[];
+    store_entry_count: number;
+    store_file_sha256: string;
+    plugin_version: string;
+    issued_at: string;
+    expires_at: string;
+    token: string;
+}
+export interface HiveQuarantineCommitResult {
+    quarantinedIds: string[];
+    storeEntriesBefore: number;
+    storeEntriesAfter: number;
+    backupDir: string;
+    backupBytes: number;
+    verified: boolean;
+}
+export interface HiveQuarantineRollbackResult {
+    restoredIds: string[];
+    alreadyPresentIds: string[];
+    storeEntriesAfter: number;
+    verified: boolean;
+}
+type Abort = {
+    ok: false;
+    code: HiveQuarantineAbortCode;
+    error: string;
+};
+/**
+ * Canonical JSON: `JSON.stringify` with recursively sorted object keys. Used for BOTH the
+ * preview token construction and the under-lock reconstruction so key order can never
+ * produce a false drift signal.
+ */
+export declare function canonicalJson(value: unknown): string;
+declare function readQuarantineSecret(): Promise<string>;
+/**
+ * Read-only preview of exact candidate IDs. Errors list missing ids; selection never
+ * falls back to prefix or text matching.
+ */
+export declare function previewHiveQuarantine(ids: string[]): Promise<{
+    ok: true;
+    preview: HiveQuarantinePreview;
+} | Abort>;
+export declare function commitHiveQuarantine(input: {
+    token: string;
+    reason?: string;
+}): Promise<{
+    ok: true;
+    result: HiveQuarantineCommitResult;
+} | Abort>;
+/**
+ * Idempotent rollback: restores the EXACT original line bytes for the manifest's ids.
+ * Ids already present with identical bytes are skipped (safe replay); an id present with
+ * DIFFERENT bytes aborts the whole operation with no mutation (collision).
+ */
+export declare function rollbackHiveQuarantine(input: {
+    ref: string;
+}): Promise<{
+    ok: true;
+    result: HiveQuarantineRollbackResult;
+} | Abort>;
+/** Read-only listing of quarantine backups (for the `status` subcommand). */
+export declare function listHiveQuarantineBackups(): Promise<{
+    token12: string;
+    committed_at: string;
+    idCount: number;
+    reason: string;
+}[]>;
+/** Test-only DI seam (AGENTS.md invariant 7). */
+export declare const _internals: {
+    emit: typeof emit;
+    readFile: typeof readFile;
+    writeFile: typeof writeFile;
+    copyFile: typeof copyFile;
+    mkdir: typeof mkdir;
+    stat: typeof stat;
+    readdir: typeof readdir;
+    resolveHiveDataDir: typeof resolveHiveDataDir;
+    resolveHiveKnowledgePath: typeof resolveHiveKnowledgePath;
+    transactHiveStore: typeof transactHiveStore;
+    realpath: typeof realpath;
+    rm: typeof rm;
+    chmod: typeof chmod;
+    readQuarantineSecret: typeof readQuarantineSecret;
+};
+export {};

package/dist/observability/catalog.d.ts

@@ -1,7 +1,7 @@
 /**
  * The event catalog (issue #2029).
  *
- * Exactly 41 entries, matching the `TelemetryEvent` union at
+ * Exactly 42 entries, matching the `TelemetryEvent` union at
  * `src/telemetry.ts:15-91`. Thirty-eight predate the #2029 contract; the 39th is
  * `agent_conflict_detected` (previously emitted through a force-cast past the
  * type system), and the 40th is `close_archive_result` (issue #2030 — the
@@ -62,7 +62,7 @@ export interface CatalogEntry {
     /**
      * Whether an event of this kind must carry `trace.parentSpanId`.
      *
-     * `false` for all 41 entries today, and that is a truthful statement about
+     * `false` for all 42 entries today, and that is a truthful statement about
      * the current system rather than a placeholder: no producer supplies a
      * parent span, so `createObservation` never sets one. Setting this to `true`
      * for a kind whose producer cannot supply a parent would make every

package/dist/telemetry.d.ts

@@ -26,7 +26,7 @@ export type TelemetryEvent = 'session_started' | 'session_ended' | 'agent_activa
  * `prm_hard_stop` TRIGGER emitted by `src/prm/escalation.ts`. A trigger with
  * no matching delivery means the containment never reached the agent.
  */
- | 'prm_hard_stop_delivered' | 'agent_conflict_detected' | 'close_archive_result' | 'knowledge_receipt_transition';
+ | 'prm_hard_stop_delivered' | 'agent_conflict_detected' | 'close_archive_result' | 'knowledge_receipt_transition' | 'knowledge_maintenance';
 /** Stable classification for how a reviewer-gate decision was established. */
 export type ReviewerGateEvidenceKind = 'genuine' | 'fallback' | 'data_quality' | 'block';
 /**

package/package.json

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