opencode-swarm 7.116.1 → 7.118.0

package/dist/commands/unlink.d.ts

@@ -2,12 +2,19 @@
  * Handles the `/swarm unlink` command.
  *
  * Stops sharing this worktree's swarm knowledge with its link store and returns
- * it to a local `.swarm/knowledge.jsonl`. By default the shared lessons are
- * copied back into the local store (deduplicated) so the worktree keeps the
- * pooled knowledge it had access to; pass `--no-copy` to skip the copy-back.
+ * it to a local `.swarm/knowledge.jsonl`. By default the shared knowledge
+ * *family* (store, events, rejected, retractions, counters, quarantine,
+ * unactionable, application-legacy) is copied back into the local store per the
+ * family manifest so the worktree keeps the pooled knowledge it had access to;
+ * pass `--no-copy` to skip the copy-back.
+ *
+ * The copy-back is transactional (issue #1846): it reads the shared family
+ * under the shared-store lock and writes the local family atomically, so a
+ * concurrent append in a peer worktree cannot be lost. The shared cohort is
+ * never deleted or truncated.
  *
  * Usage:
- * - /swarm unlink              — unlink and copy shared lessons back to local.
- * - /swarm unlink --no-copy    — unlink without copying shared lessons back.
+ * - /swarm unlink              — unlink and copy the shared family back to local.
+ * - /swarm unlink --no-copy    — unlink without copying the shared family back.
  */
 export declare function handleUnlinkCommand(directory: string, args: string[]): Promise<string>;

package/dist/config/schema.d.ts

@@ -420,9 +420,9 @@ export declare const LintConfigSchema: z.ZodObject<{
         fix: "fix";
     }>>;
     linter: z.ZodDefault<z.ZodEnum<{
+        auto: "auto";
         biome: "biome";
         eslint: "eslint";
-        auto: "auto";
     }>>;
     patterns: z.ZodDefault<z.ZodArray<z.ZodString>>;
     exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
@@ -630,6 +630,8 @@ export declare const KnowledgeConfigSchema: z.ZodObject<{
     contradiction_quarantine_window_days: z.ZodDefault<z.ZodNumber>;
     promoted_demotion_min_negative_phases: z.ZodDefault<z.ZodNumber>;
     promoted_demotion_signal_threshold: z.ZodDefault<z.ZodNumber>;
+    promotion_min_terminal_applications: z.ZodDefault<z.ZodNumber>;
+    promotion_min_distinct_cohorts: z.ZodDefault<z.ZodNumber>;
     realtime_learning_nudge: z.ZodDefault<z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         first_after_tool_calls: z.ZodDefault<z.ZodNumber>;
@@ -1068,8 +1070,8 @@ export declare const ParallelizationConfigSchema: z.ZodObject<{
 export type ParallelizationConfig = z.infer<typeof ParallelizationConfigSchema>;
 export declare const WorktreeIsolationConfigSchema: z.ZodObject<{
     policy: z.ZodDefault<z.ZodEnum<{
-        disabled: "disabled";
         auto: "auto";
+        disabled: "disabled";
         required: "required";
     }>>;
     merge_strategy: z.ZodDefault<z.ZodEnum<{
@@ -1852,9 +1854,9 @@ export declare const PluginConfigSchema: z.ZodObject<{
             fix: "fix";
         }>>;
         linter: z.ZodDefault<z.ZodEnum<{
+            auto: "auto";
             biome: "biome";
             eslint: "eslint";
-            auto: "auto";
         }>>;
         patterns: z.ZodDefault<z.ZodArray<z.ZodString>>;
         exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
@@ -1940,6 +1942,8 @@ export declare const PluginConfigSchema: z.ZodObject<{
         contradiction_quarantine_window_days: z.ZodDefault<z.ZodNumber>;
         promoted_demotion_min_negative_phases: z.ZodDefault<z.ZodNumber>;
         promoted_demotion_signal_threshold: z.ZodDefault<z.ZodNumber>;
+        promotion_min_terminal_applications: z.ZodDefault<z.ZodNumber>;
+        promotion_min_distinct_cohorts: z.ZodDefault<z.ZodNumber>;
         realtime_learning_nudge: z.ZodDefault<z.ZodObject<{
             enabled: z.ZodDefault<z.ZodBoolean>;
             first_after_tool_calls: z.ZodDefault<z.ZodNumber>;
@@ -2255,8 +2259,8 @@ export declare const PluginConfigSchema: z.ZodObject<{
     }, z.core.$strip>>;
     worktree: z.ZodOptional<z.ZodObject<{
         policy: z.ZodDefault<z.ZodEnum<{
-            disabled: "disabled";
             auto: "auto";
+            disabled: "disabled";
             required: "required";
         }>>;
         merge_strategy: z.ZodDefault<z.ZodEnum<{

package/dist/hooks/curator-postmortem.d.ts

@@ -136,7 +136,7 @@ export declare const _internals: {
         applied: number;
         skipped: number;
     }>;
-    checkHivePromotions: (entries: SwarmKnowledgeEntry[], knowledgeConfig: KnowledgeConfig) => Promise<import("./hive-promoter.js").HivePromotionSummary>;
+    checkHivePromotions: (entries: SwarmKnowledgeEntry[], knowledgeConfig: KnowledgeConfig, directory: string) => Promise<import("./hive-promoter.js").HivePromotionSummary>;
     applyProposalTriage: (directory: string, triage: ParsedPostMortemActions["queueTriage"]) => Promise<{
         approved: string[];
         rejected: string[];

package/dist/hooks/hive-policy.d.ts

@@ -0,0 +1,81 @@
+/**
+ * One promotion policy evaluator used by automatic promotion AND the manual
+ * `/swarm promote` command (issue #1847 §4).
+ *
+ * Previously, automatic promotion went through `isHiveEligible` (3 routes:
+ * hive_eligible+3 phases / hive-fast-track tag / age) while manual promotion
+ * (`promoteToHive` / `promoteFromSwarm`) bypassed policy entirely — an exact
+ * entry id was effectively authorization to skip the gate, with no durable
+ * override record. This module is the single policy function both paths share.
+ *
+ * Manual promotion that fails the policy MUST either be blocked, or proceed
+ * only with an explicit `--force` override that records a durable, audited
+ * override (actor, reason, source revision, failed gates). An exact entry id
+ * alone is NEVER authorization to bypass policy.
+ *
+ * Conservative application evidence (#1847 §2, AC5/AC6): the
+ * `validated_terminal_applications` gate counts ONLY validated terminal receipts
+ * tied to a real retrieval trace + result membership. Legacy records carry no
+ * evidence and receive NO synthetic credit. Until #1849 produces real receipts,
+ * the configured thresholds default to 0, so the gate is satisfied by absence
+ * (it neither credits nor blocks) and current behavior is preserved. Operators
+ * raise the thresholds to activate application-evidence gating.
+ *
+ * This module performs NO I/O and holds NO module-level mutable state
+ * (invariant 8). It is NOT imported on the plugin-init path (invariant 1).
+ */
+import type { KnowledgeConfig, PromotionEvidenceRecord, SwarmKnowledgeEntry } from './knowledge-types.js';
+/** A single named policy gate and whether it passed. */
+export interface PromotionPolicyGate {
+    name: string;
+    passed: boolean;
+    detail: string;
+}
+export interface PromotionPolicyInput {
+    entry: SwarmKnowledgeEntry;
+    config: KnowledgeConfig;
+    /**
+     * Validated terminal-application evidence for this entry's lesson
+     * (near-duplicate-clustered). Empty for legacy/no-evidence records. The
+     * promoter loads this OUTSIDE the hive transaction and passes it in.
+     */
+    evidence: PromotionEvidenceRecord[];
+}
+export interface PromotionPolicyDecision {
+    eligible: boolean;
+    /** Every gate and whether it passed — surfaced in diagnostics + override audit. */
+    gates: PromotionPolicyGate[];
+    /** Human-readable summary of the deciding gate. */
+    reason: string;
+}
+/**
+ * Evaluate the one promotion policy. Used by auto promotion and manual promote.
+ * Returns the full gates list so diagnostics can explain each failed condition
+ * (AC: "Promotion diagnostics explain eligibility failures and lineage").
+ */
+export declare function evaluatePromotionPolicy(input: PromotionPolicyInput): PromotionPolicyDecision;
+/**
+ * The three historical eligibility routes, preserved verbatim from the
+ * pre-#1847 `isHiveEligible`. Exposed so `isHiveEligible` can delegate to it
+ * (M1 fix — keeps the public export + its test consumers working) and so the
+ * policy gate above can report which route satisfied it.
+ */
+export declare function describeEligibilityRoute(entry: SwarmKnowledgeEntry, autoPromoteDays: number): {
+    passed: boolean;
+    detail: string;
+};
+/** Names of override-audit fields the promoter fills when a manual --force fires. */
+export interface OverrideAuditDetail {
+    actor: 'manual-override';
+    reason: string;
+    failedGates: PromotionPolicyGate[];
+    entryId: string;
+    lesson: string;
+}
+/**
+ * Build the failed-gates summary for a manual override, given a decision that
+ * was NOT eligible. Used by the promoter to populate `lineage.override_failed_gates`.
+ */
+export declare function failedGateNames(decision: PromotionPolicyDecision): string[];
+/** Count distinct canonical cohorts among promotion evidence (for diagnostics). */
+export declare function countDistinctEvidenceCohorts(evidence: PromotionEvidenceRecord[]): number;

package/dist/hooks/hive-promoter.d.ts

@@ -1,59 +1,178 @@
-/** Hive promoter hook for opencode-swarm v6.17 two-tier knowledge system. */
+/**
+ * Hive promoter for opencode-swarm v6.17 two-tier knowledge system.
+ *
+ * #1847 (transactional hive promotion): every hive write is routed through ONE
+ * global cross-process transaction (`transactHiveStore` in `./hive-transaction`).
+ * The transaction holds the hive directory lock across read → normalize →
+ * eligibility → canonical-cohort counting → dedup/merge → append/update →
+ * source confirmation → cap → staged audit → atomic persist. No caller reads
+ * the hive, makes a promotion decision, and later calls a separate unlocked
+ * write API.
+ *
+ * Canonical project identity (#1846): cross-project confirmations key on the
+ * canonical `cohort_id` from `resolveCohortId`, not the worktree `project_name`.
+ * Sibling worktrees and remote aliases of one repository count as one project.
+ *
+ * Lineage (#1847 §3): promoted entries retain source entry id, source cohort,
+ * promotion event id, and actor. Manual promotion that fails policy proceeds
+ * only with an explicit `--force` override that records a durable audit entry;
+ * an exact entry id alone is never authorization to bypass policy.
+ *
+ * This module is NOT imported on the plugin-init path (invariant 1): promotion
+ * runs only on the lazy `/swarm promote`, close, curate, and postmortem paths.
+ */
+import { resolveCohortId } from '../knowledge/cohort-identity.js';
 import { appendCuratorRecommendation, readCuratorSummary } from './curator.js';
-import type { KnowledgeConfig, SwarmKnowledgeEntry } from './knowledge-types.js';
-/** Hive promotion summary for curator state */
+import { transactHiveStore } from './hive-transaction.js';
+import type { KnowledgeConfig, ProjectConfirmationRecord, PromotionEvidenceRecord, SwarmKnowledgeEntry } from './knowledge-types.js';
+import { validateLesson } from './knowledge-validator.js';
+/** Hive promotion summary for curator state. */
 export interface HivePromotionSummary {
     timestamp: string;
     new_promotions: number;
     encounters_incremented: number;
     advancements: number;
     total_hive_entries: number;
+    /** #1847: per-entry policy diagnostics for operator visibility. */
+    diagnostics?: string[];
 }
 /**
- * Check whether a swarm knowledge entry is eligible for hive promotion.
- * Three routes to eligibility:
- *   Route 1: hive_eligible flag + 3+ distinct phases
- *   Route 2: 'hive-fast-track' tag
- *   Route 3: age exceeds auto_promote_days threshold
- *
- * @param entry - The swarm knowledge entry to check
- * @param autoPromoteDays - Number of days before age-based promotion kicks in
- * @returns true if the entry is eligible for hive promotion
+ * Check whether a swarm entry is eligible for hive promotion via the historical
+ * 3 routes. Kept as a thin wrapper delegating to the canonical policy route
+ * description (M1 fix, #1847) so existing test consumers
+ * (`hive-promoter-inactive.test.ts`, `close.test.ts` mock) keep working.
+ *
+ * This is ONE of the gates inside {@link evaluatePromotionPolicy}; it is not
+ * the whole policy. New callers should use `evaluatePromotionPolicy`.
  */
 export declare function isHiveEligible(entry: SwarmKnowledgeEntry, autoPromoteDays: number): boolean;
 /**
- * Main promotion logic: checks swarm entries and promotes eligible ones to hive.
- * Also updates existing hive entries with new project confirmations.
- * Returns a summary of the promotion activity for curator state.
+ * Count distinct projects/cohort identities in a hive entry's confirmed_by.
  *
- * @note The 'hive-fast-track' tag is treated as privileged — it bypasses the
- *   3-phase confirmation requirement. It should only be set by authorized tooling
- *   (inferTags() never produces it automatically).
+ * #1847: dedup by canonical `cohort_id` (sibling worktrees + remote aliases of
+ * one repo count as one project). Legacy records written before #1847 lack
+ * `cohort_id`; for those, fall back to `project_name` — but two records sharing
+ * a `cohort_id` are NEVER counted as distinct. This means AC3 ("sibling
+ * worktrees count as one project") is enforced for confirmations written from
+ * this PR forward; legacy confirmations remain `project_name`-keyed and are NOT
+ * retroactively re-counted (consistent with the no-broad-rewrite non-goal).
  */
-export declare function checkHivePromotions(swarmEntries: SwarmKnowledgeEntry[], config: KnowledgeConfig): Promise<HivePromotionSummary>;
+export declare function countDistinctProjects(confirmedBy: ProjectConfirmationRecord[]): number;
+/**
+ * Main promotion logic: checks swarm entries and promotes eligible ones to hive
+ * inside ONE cross-process transaction. Also updates existing hive entries with
+ * new canonical-cohort confirmations. Returns a summary for curator state.
+ *
+ * `directory` is required (#1847) to resolve the canonical cohort identity
+ * (#1846) for cross-project distinctness.
+ *
+ * @note The 'hive-fast-track' tag is privileged — it bypasses the 3-phase
+ *   confirmation requirement inside the eligibility_route gate. It should only
+ *   be set by authorized tooling (inferTags() never produces it automatically).
+ */
+export declare function checkHivePromotions(swarmEntries: SwarmKnowledgeEntry[], config: KnowledgeConfig, directory: string): Promise<HivePromotionSummary>;
 export declare const _internals: {
     readSwarmEntries: (directory: string) => Promise<SwarmKnowledgeEntry[]>;
     checkHivePromotions: typeof checkHivePromotions;
     readCuratorSummary: typeof readCuratorSummary;
     appendCuratorRecommendation: typeof appendCuratorRecommendation;
+    resolveCohortId: typeof resolveCohortId;
+    transactHiveStore: typeof transactHiveStore;
+    validateLesson: typeof validateLesson;
+    /** Loads validated terminal-application evidence per swarm entry id. Empty
+     *  until #1849 produces real receipts (conservative: no synthetic credit). */
+    loadPromotionEvidence: (_swarmEntries: SwarmKnowledgeEntry[]) => Promise<Record<string, PromotionEvidenceRecord[]>>;
+    /** Loads the default KnowledgeConfig (schema defaults) for manual promotion
+     *  paths when the command did not load one. */
+    loadDefaultKnowledgeConfig: () => {
+        enabled: boolean;
+        swarm_max_entries: number;
+        hive_max_entries: number;
+        auto_promote_days: number;
+        max_inject_count: number;
+        delegate_max_inject_count: number;
+        inject_char_budget: number;
+        max_lesson_display_chars: number;
+        dedup_threshold: number;
+        scope_filter: string[];
+        hive_enabled: boolean;
+        rejected_max_entries: number;
+        validation_enabled: boolean;
+        evergreen_confidence: number;
+        evergreen_utility: number;
+        low_utility_threshold: number;
+        min_retrievals_for_utility: number;
+        schema_version: number;
+        directive_min_confidence: number;
+        same_project_weight: number;
+        cross_project_weight: number;
+        min_encounter_score: number;
+        initial_encounter_score: number;
+        encounter_increment: number;
+        max_encounter_score: number;
+        default_max_phases: number;
+        todo_max_phases: number;
+        sweep_enabled: boolean;
+        confidence_floor_action: "none" | "demote" | "quarantine";
+        confidence_floor_min_outcomes: number;
+        confidence_floor_signal_threshold: number;
+        contradiction_threshold_action: "quarantine" | "tag_only";
+        contradiction_quarantine_threshold: number;
+        contradiction_quarantine_window_days: number;
+        promoted_demotion_min_negative_phases: number;
+        promoted_demotion_signal_threshold: number;
+        promotion_min_terminal_applications: number;
+        promotion_min_distinct_cohorts: number;
+        realtime_learning_nudge: {
+            enabled: boolean;
+            first_after_tool_calls: number;
+            repeat_after_tool_calls: number;
+        };
+        enrichment: {
+            max_calls_per_day: number;
+            quota_window: "utc" | "local";
+            batch_size?: number | undefined;
+        };
+        context_budget_threshold?: number | undefined;
+        retrieval?: {
+            mmr_lambda: number;
+            cold_start_bonus: number;
+            cold_start_max_age_phases: number;
+            synonym_min_cooccurrence: number;
+            synonym_map_max_pairs: number;
+        } | undefined;
+    };
 };
 /**
  * Create a hook that promotes swarm entries to the hive.
  * The hook fires unconditionally - the caller decides when to invoke it.
  */
 export declare function createHivePromoterHook(directory: string, config: KnowledgeConfig): (input: unknown, output: unknown) => Promise<void>;
+/** Options for manual promotion (override semantics, #1847 §4). */
+export interface ManualPromotionOptions {
+    force?: boolean;
+    reason?: string;
+}
 /**
  * Promote a lesson directly to the hive (manual promotion).
- * @param directory - Project directory
- * @param lesson - The lesson text to promote
- * @param category - Optional category (defaults to 'process')
- * @returns Confirmation message
+ *
+ * Runs the one policy evaluator. On a policy FAIL:
+ *   - without `force` → returns a diagnostic string listing the failed gates
+ *     (does NOT promote);
+ *   - with `force` + `reason` → promotes and writes a durable override audit
+ *     record (actor='manual-override', failed gates recorded) inside the
+ *     transaction.
+ * On a policy PASS → promotes with actor='manual'.
+ *
+ * An exact entry id / direct text alone is NEVER authorization to bypass policy.
  */
-export declare function promoteToHive(directory: string, lesson: string, category?: string): Promise<string>;
+export declare function promoteToHive(directory: string, lesson: string, category?: string, options?: ManualPromotionOptions, config?: KnowledgeConfig): Promise<string>;
 /**
  * Promote a lesson from swarm knowledge to hive.
- * @param directory - Project directory
- * @param lessonId - The ID of the lesson to promote from swarm
- * @returns Confirmation message
+ *
+ * Snapshots the swarm read OUTSIDE the hive transaction (the swarm store is
+ * read-only here — no two-phase locking needed). Then runs the one policy
+ * evaluator + override semantics inside the hive transaction.
  */
-export declare function promoteFromSwarm(directory: string, lessonId: string): Promise<string>;
+export declare function promoteFromSwarm(directory: string, lessonId: string, options?: ManualPromotionOptions, config?: KnowledgeConfig): Promise<string>;
+export { resolveHiveKnowledgePath } from './knowledge-store.js';

package/dist/hooks/hive-transaction.d.ts

@@ -0,0 +1,113 @@
+/**
+ * One global, cross-process transaction primitive for hive storage (issue #1847 §1).
+ *
+ * Problem: hive promotion previously performed read → N× append → batch rewrite
+ * → cap enforcement as FOUR separate directory-lock acquisitions, with unlocked
+ * read/validate/dedup windows between them. Because the hive store
+ * (`shared-learnings.jsonl`) is a shared, cross-project, cross-process file,
+ * two opencode-swarm sessions could each read the same snapshot and one's
+ * rewrite silently dropped the other's entries (TOCTOU lost update — #1604).
+ *
+ * This module routes every hive writer through ONE critical section that spans,
+ * under a single directory lock:
+ *   1. read + mixed-schema normalize;
+ *   2. the caller's mutate (eligibility, canonical project counting, dedup,
+ *      merge decision, append/update, source confirmation);
+ *   3. validate-before-commit;
+ *   4. priority-aware cap enforcement (in the same closure, not a separate call);
+ *   5. staged audit/reject appends (raw, under the held lock — never via
+ *      `appendHiveKnowledgeEvent`, which would re-enter the directory lock and
+ *      deadlock — see the curator precedent at `curator.ts:1966-1969`);
+ *   6. atomic persistence (temp + rename).
+ *
+ * Lock contract (AGENTS.md invariants 3, 8): `stale: 5000` to MATCH every other
+ * hive writer (`appendKnowledge`, `rewriteKnowledge`, `transactKnowledge`,
+ * `knowledge-application.ts`, `knowledge-escalator.ts`). proper-lockfile's stale
+ * mechanism is preemptive — a process that cannot acquire the lock and sees its
+ * mtime older than its OWN stale threshold force-breaks it. Using a longer stale
+ * here would let a concurrent 5s writer break this transaction mid-flight and
+ * tear the file, which is exactly the bug this PR fixes. The held closure is
+ * kept fast (in-memory mutate + one atomic write + raw appends) so 5s is never
+ * exceeded; all heavy work (git cohort resolution, evidence rollup, near-
+ * duplicate precompute) runs OUTSIDE the lock and is passed in via HiveTxContext.
+ *
+ * This module holds NO module-level mutable state (invariant 8) and is NOT
+ * imported on the plugin-init path (invariant 1).
+ */
+import * as path from 'node:path';
+import lockfile from 'proper-lockfile';
+import { atomicWriteFile } from '../evidence/task-file.js';
+import { resolveHiveDataDir, resolveHiveEventsPath, resolveHiveKnowledgePath, resolveHiveRejectedPath } from '../knowledge/hive-paths.js';
+import { readKnowledge, selectKnowledgeCapSurvivors } from './knowledge-store.js';
+import type { HiveKnowledgeEntry, RejectedLesson } from './knowledge-types.js';
+/**
+ * Context handed to a hive mutation closure. All expensive pre-work (cohort
+ * resolution, evidence loading, near-duplicate indexing) is performed by the
+ * caller OUTSIDE the lock and injected here so the held closure stays fast.
+ */
+export interface HiveTxContext {
+    /** Current hive entries (read + normalized under the lock). */
+    entries: HiveKnowledgeEntry[];
+}
+/** A pre-serialized knowledge-event line to append to the hive audit log. */
+export interface HiveAuditEntry {
+    line: string;
+}
+/** The result a mutation closure returns. */
+export type HiveMutationOutcome<T> = {
+    kind: 'commit';
+    entries: HiveKnowledgeEntry[];
+    /** Hive cap to enforce inside the same closure (omit for no cap). */
+    maxEntries?: number;
+    /** Rejected lessons to append to the hive rejected log under the lock. */
+    rejects?: RejectedLesson[];
+    /** Audit lines to append to the hive events log under the lock. */
+    audit?: HiveAuditEntry[];
+    /** Caller return value surfaced back through HiveTransactionResult. */
+    return: T;
+} | {
+    kind: 'noop';
+    return: T;
+};
+export interface HiveTransactionResult<T> {
+    /** True iff the hive file was rewritten within the transaction. */
+    committed: boolean;
+    /**
+     * The caller's return value. Present when `committed` is true OR the mutate
+     * closure returned a `noop` outcome. Undefined on lock-acquire / mkdir /
+     * validation-before-commit failure (F-004/PRR-1): callers MUST check
+     * `committed` (or `return !== undefined`) before dereferencing it.
+     */
+    return: T | undefined;
+    /** Human-readable diagnostics (lock timeout, validation failure, etc.). */
+    diagnostics: string[];
+}
+/**
+ * Run `mutate` against the hive store inside one cross-process transaction.
+ *
+ * On lock-acquire failure or validation failure the prior hive file is left
+ * intact (the atomic write is not performed) and `committed` is false; the
+ * function never hangs. `mutate` receives the current (normalized) entries and
+ * returns either a `commit` (new entries + optional cap/rejects/audit) or a
+ * `noop`.
+ */
+export declare function transactHiveStore<T>(mutate: (ctx: HiveTxContext) => Promise<HiveMutationOutcome<T>> | HiveMutationOutcome<T>): Promise<HiveTransactionResult<T>>;
+/** Path to the hive events log (re-exported for callers building audit lines). */
+export { resolveHiveEventsPath };
+export declare const HIVE_TXN_LOCK_STALE_MS = 5000;
+/**
+ * Test-only DI seam (AGENTS.md invariant 7). Tests inject a fake lockfile /
+ * readers / writers rather than `mock.module`-ing the consumers, which leaks
+ * across test files in Bun's shared runner.
+ */
+export declare const _internals: {
+    lockfile: typeof lockfile;
+    readKnowledge: typeof readKnowledge;
+    atomicWriteFile: typeof atomicWriteFile;
+    selectKnowledgeCapSurvivors: typeof selectKnowledgeCapSurvivors;
+    resolveHiveDataDir: typeof resolveHiveDataDir;
+    resolveHiveKnowledgePath: typeof resolveHiveKnowledgePath;
+    resolveHiveRejectedPath: typeof resolveHiveRejectedPath;
+    resolveHiveEventsPath: typeof resolveHiveEventsPath;
+    path: typeof path;
+};

package/dist/hooks/knowledge-events.d.ts

@@ -19,6 +19,7 @@
  *   `directory` argument injected by `createSwarmTool` / hook constructors — never
  *   from the process working directory.
  */
+import { resolveHiveEventsPath as resolveHiveEventsPathImpl } from '../knowledge/hive-paths.js';
 import type { ConfidenceFloorOptions } from './knowledge-store.js';
 import type { KnowledgeApplicationRecord, RetrievalOutcome } from './knowledge-types.js';
 /** Current event-log record schema version. Bump when the on-disk shape changes. */
@@ -182,7 +183,7 @@ export declare const RECEIPT_EVENT_TYPES: ReadonlySet<string>;
 export declare function resolveKnowledgeEventsPath(directory: string): string;
 /** Returns the knowledge-counter-baseline.json path (link-aware). */
 export declare function resolveKnowledgeCounterBaselinePath(directory: string): string;
-export declare function resolveHiveEventsPath(): string;
+export declare const resolveHiveEventsPath: typeof resolveHiveEventsPathImpl;
 /** Returns the knowledge-application.jsonl path for legacy v2 audit records (link-aware). */
 export declare function resolveLegacyApplicationLogPath(directory: string): string;
 /** Generate a fresh trace id. One per retrieval; receipts reference it. */
@@ -267,6 +268,7 @@ export interface CounterRollup {
 }
 /** Cap on retained per-entry violation timestamps. */
 export declare const MAX_VIOLATION_TIMESTAMPS = 10;
+declare function mergeRollupInto(target: CounterRollup, source: CounterRollup): void;
 declare function readCounterBaseline(directory: string): Promise<Map<string, CounterRollup>>;
 /**
  * Recompute per-entry counters deterministically from the immutable event log,
@@ -362,5 +364,6 @@ export declare const _internals: {
     appendHiveKnowledgeEvent: typeof appendHiveKnowledgeEvent;
     recordHiveKnowledgeEvent: typeof recordHiveKnowledgeEvent;
     readHiveKnowledgeEvents: typeof readHiveKnowledgeEvents;
+    mergeRollupInto: typeof mergeRollupInto;
 };
 export {};

package/dist/hooks/knowledge-link.d.ts

@@ -27,7 +27,8 @@
  */
 /** On-disk pointer at `<directory>/.swarm/link.json`. */
 export interface LinkPointer {
-    version: 1;
+    /** Pointer schema version. v1 pointers stay valid; v2 carries cohort metadata. */
+    version: 1 | 2;
     /** Path-safe identifier of the shared store (projectHash or sanitized name). */
     linkId: string;
     /** Human-friendly name when the link was created from an explicit name. */
@@ -36,6 +37,16 @@ export interface LinkPointer {
     createdAt: string;
     /** How the link was established. */
     source: 'manual' | 'auto';
+    /** Canonical cohort id from `resolveCohortId` (issue #1846). */
+    cohortId?: string;
+    /** How the cohort id was derived. */
+    identitySource?: 'remote' | 'git-common-dir' | 'path';
+    /** True when the cohort id is machine-local (git-common-dir/path fallback). */
+    degraded?: boolean;
+    /** Deterministic hash of cohort-relevant config (issue #1846 §4). */
+    configFingerprint?: string;
+    /** Monotonic generation counter, bumped on each link/unlink. Aids cache invalidation. */
+    generation?: number;
 }
 export interface LinkedLocalKnowledgeStatus {
     linked: boolean;
@@ -55,7 +66,13 @@ export declare function resolveLinkDir(linkId: string): string;
  * project hash). Lowercased for case-insensitive stability across worktrees.
  */
 export declare function sanitizeLinkId(name: string): string | null;
-/** Read and validate the link pointer for a worktree. Null if absent/invalid. */
+/**
+ * Read and validate the link pointer for a worktree. Null if absent/invalid.
+ *
+ * Schema-version aware (issue #1846): reads `version` from disk rather than
+ * hard-stamping `1`, validates it is a known version, and preserves v2 cohort
+ * metadata fields when present. Unknown fields are ignored (forward-compat).
+ */
 export declare function readLinkPointer(directory: string): LinkPointer | null;
 export declare function getLinkedLocalKnowledgeStatus(directory: string): LinkedLocalKnowledgeStatus;
 /** Write the link pointer atomically and invalidate the resolution cache. */
@@ -67,8 +84,18 @@ export declare function removeLinkPointer(directory: string): Promise<void>;
  *
  * Returns the shared link directory when an active pointer is present, otherwise
  * the local `<directory>/.swarm`. Fail-open: any read/parse error degrades to the
- * local directory, so a corrupt pointer never strands knowledge. Synchronous and
- * cached so the hot retrieval path pays at most one tiny file read per TTL window.
+ * local directory, so a corrupt pointer never strands knowledge. Synchronous
+ * and cached; on a cache hit a cheap `stat` of the pointer file revalidates
+ * cross-process changes so the hot retrieval path stays fast while still
+ * observing link/unlink without waiting for the TTL to expire.
+ *
+ * Cross-process revalidation (issue #1846 §2): on a cache hit we additionally
+ * `stat` the pointer file and compare `mtimeMs:ctimeMs:size` to the cached
+ * fingerprint. A change (another process wrote/removed the pointer) invalidates
+ * the entry, so a stale process observes link/unlink without waiting for the
+ * TTL to expire. The TTL remains a backstop. The per-call `stat` is negligible
+ * (the pointer is tiny and almost never changes) and is the cost of correct
+ * cross-process link/unlink observation.
  *
  * NOTE: when unlinked, the return value is byte-identical to the legacy
  * `path.join(directory, '.swarm')`, so existing callers/tests are unaffected.

package/dist/hooks/knowledge-store.d.ts

@@ -1,12 +1,14 @@
 /** Core storage layer for the opencode-swarm v6.17 two-tier knowledge system. */
+import { resolveHiveDataDir, resolveHiveEventsPath as resolveHiveEventsPathImpl, resolveHiveKnowledgePath as resolveHiveKnowledgePathImpl, resolveHiveRejectedPath as resolveHiveRejectedPathImpl } from '../knowledge/hive-paths.js';
 import type { KnowledgeEntryBase, RejectedLesson, RetrievalOutcome } from './knowledge-types.js';
 export declare function getPlatformConfigDir(): string;
 export declare function resolveSwarmKnowledgePath(directory: string): string;
 export declare function resolveSwarmRejectedPath(directory: string): string;
 export declare function resolveSwarmRetractionsPath(directory: string): string;
-export declare function resolveHiveKnowledgePath(): string;
-export declare function resolveHiveRejectedPath(): string;
-export declare function resolveHiveEventsPath(): string;
+export declare const resolveHiveKnowledgePath: typeof resolveHiveKnowledgePathImpl;
+export declare const resolveHiveRejectedPath: typeof resolveHiveRejectedPathImpl;
+export declare const resolveHiveEventsPath: typeof resolveHiveEventsPathImpl;
+export { resolveHiveDataDir };
 declare function parseKnowledgeContent<T>(content: string, max: number): T[];
 export declare function readKnowledge<T>(filePath: string, maxEntries?: number): Promise<T[]>;
 export declare function normalizeEntry<T>(raw: T): T;
@@ -29,7 +31,7 @@ export declare function transactKnowledge<T>(filePath: string, mutate: (entries:
 export declare function getArchivedKnowledgeIds(directory: string): Promise<Set<string>>;
 export declare function appendKnowledgeWithCapEnforcement<T>(filePath: string, entry: T, maxEntries: number): Promise<boolean>;
 export declare function enforceKnowledgeCap<T>(filePath: string, maxEntries: number): Promise<void>;
-declare function selectKnowledgeCapSurvivors<T>(entries: T[], maxEntries: number): T[];
+export declare function selectKnowledgeCapSurvivors<T>(entries: T[], maxEntries: number): T[];
 export interface SweepResult {
     scanned: number;
     aged: number;
@@ -136,4 +138,3 @@ export declare const _internals: {
     bumpKnowledgeConfidenceBatch: typeof bumpKnowledgeConfidenceBatch;
     getArchivedKnowledgeIds: typeof getArchivedKnowledgeIds;
 };
-export {};