opencode-swarm 7.88.4 → 7.89.0

package/dist/cli/{index-e8pk68cc.js → index-axwxkbdd.js}

@@ -14,51 +14,194 @@ import {
 
 // src/hooks/knowledge-store.ts
 var import_proper_lockfile = __toESM(require_proper_lockfile(), 1);
-import { existsSync } from "fs";
+import { existsSync as existsSync2 } from "fs";
 import { appendFile, mkdir, readFile } from "fs/promises";
+import * as os2 from "os";
+import * as path2 from "path";
+
+// src/hooks/knowledge-link.ts
+import { existsSync, mkdirSync, readFileSync, rmSync } from "fs";
 import * as os from "os";
 import * as path from "path";
-var KNOWLEDGE_JSONL_CACHE_NAMESPACE = "knowledge-jsonl:normalized:v1";
-function getPlatformConfigDir() {
+var LINK_POINTER_FILENAME = "link.json";
+var MAX_LINK_ID_LENGTH = 64;
+var WINDOWS_RESERVED_NAMES = new Set([
+  "con",
+  "prn",
+  "aux",
+  "nul",
+  "com0",
+  "com1",
+  "com2",
+  "com3",
+  "com4",
+  "com5",
+  "com6",
+  "com7",
+  "com8",
+  "com9",
+  "lpt0",
+  "lpt1",
+  "lpt2",
+  "lpt3",
+  "lpt4",
+  "lpt5",
+  "lpt6",
+  "lpt7",
+  "lpt8",
+  "lpt9"
+]);
+var CACHE_TTL_MS = 2000;
+var MAX_CACHE_ENTRIES = 500;
+function resolveDataDir() {
   const platform = process.platform;
   const home = process.env.HOME || os.homedir();
   if (platform === "win32") {
-    return path.join(process.env.LOCALAPPDATA || path.join(home, "AppData", "Local"), "opencode-swarm", "config");
+    return path.join(process.env.LOCALAPPDATA || path.join(home, "AppData", "Local"), "opencode-swarm", "Data");
   } else if (platform === "darwin") {
     return path.join(home, "Library", "Application Support", "opencode-swarm");
+  }
+  return path.join(process.env.XDG_DATA_HOME || path.join(home, ".local", "share"), "opencode-swarm");
+}
+function resolveLinkBaseDir() {
+  return path.join(resolveDataDir(), "links");
+}
+function resolveLinkDir(linkId) {
+  return path.join(resolveLinkBaseDir(), linkId);
+}
+function sanitizeLinkId(name) {
+  if (typeof name !== "string")
+    return null;
+  const cleaned = name.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/-+/g, "-").replace(/^[-.]+|[-.]+$/g, "").slice(0, MAX_LINK_ID_LENGTH).replace(/[-.]+$/g, "");
+  if (cleaned.length === 0)
+    return null;
+  const base = cleaned.split(".")[0];
+  if (WINDOWS_RESERVED_NAMES.has(base))
+    return null;
+  return cleaned;
+}
+function resolveLinkPointerPath(directory) {
+  return path.join(directory, ".swarm", LINK_POINTER_FILENAME);
+}
+function readLinkPointer(directory) {
+  const pointerPath = resolveLinkPointerPath(directory);
+  if (!existsSync(pointerPath))
+    return null;
+  try {
+    const raw = JSON.parse(readFileSync(pointerPath, "utf-8"));
+    if (!raw || typeof raw !== "object")
+      return null;
+    const obj = raw;
+    const linkId = obj.linkId;
+    if (typeof linkId !== "string" || linkId.length === 0)
+      return null;
+    const safeId = sanitizeLinkId(linkId);
+    if (!safeId)
+      return null;
+    return {
+      version: 1,
+      linkId: safeId,
+      name: typeof obj.name === "string" ? obj.name : undefined,
+      createdAt: typeof obj.createdAt === "string" ? obj.createdAt : new Date(0).toISOString(),
+      source: obj.source === "auto" ? "auto" : "manual"
+    };
+  } catch {
+    return null;
+  }
+}
+async function writeLinkPointer(directory, pointer) {
+  const swarmDir = path.join(directory, ".swarm");
+  mkdirSync(swarmDir, { recursive: true });
+  const pointerPath = resolveLinkPointerPath(directory);
+  await atomicWriteFile(pointerPath, JSON.stringify(pointer, null, 2));
+  invalidateKnowledgeStoreDirCache(directory);
+}
+async function removeLinkPointer(directory) {
+  const pointerPath = resolveLinkPointerPath(directory);
+  try {
+    rmSync(pointerPath, { force: true });
+  } finally {
+    invalidateKnowledgeStoreDirCache(directory);
+  }
+}
+var _resolutionCache = new Map;
+function resolveKnowledgeStoreDir(directory) {
+  const localSwarm = path.join(directory, ".swarm");
+  const now = Date.now();
+  const cached = _resolutionCache.get(directory);
+  if (cached && now < cached.expires) {
+    return cached.linkDir ?? localSwarm;
+  }
+  let linkDir = null;
+  try {
+    const pointer = readLinkPointer(directory);
+    if (pointer) {
+      linkDir = path.resolve(resolveLinkDir(pointer.linkId));
+    }
+  } catch {
+    linkDir = null;
+  }
+  if (!_resolutionCache.has(directory) && _resolutionCache.size >= MAX_CACHE_ENTRIES) {
+    const oldest = _resolutionCache.keys().next().value;
+    if (oldest !== undefined)
+      _resolutionCache.delete(oldest);
+  }
+  _resolutionCache.set(directory, { linkDir, expires: now + CACHE_TTL_MS });
+  return linkDir ?? localSwarm;
+}
+function invalidateKnowledgeStoreDirCache(directory) {
+  if (directory === undefined) {
+    _resolutionCache.clear();
+    return;
+  }
+  _resolutionCache.delete(directory);
+}
+function isLinked(directory) {
+  return readLinkPointer(directory) !== null;
+}
+
+// src/hooks/knowledge-store.ts
+var KNOWLEDGE_JSONL_CACHE_NAMESPACE = "knowledge-jsonl:normalized:v1";
+function getPlatformConfigDir() {
+  const platform = process.platform;
+  const home = process.env.HOME || os2.homedir();
+  if (platform === "win32") {
+    return path2.join(process.env.LOCALAPPDATA || path2.join(home, "AppData", "Local"), "opencode-swarm", "config");
+  } else if (platform === "darwin") {
+    return path2.join(home, "Library", "Application Support", "opencode-swarm");
   } else {
-    return path.join(process.env.XDG_CONFIG_HOME || path.join(home, ".config"), "opencode-swarm");
+    return path2.join(process.env.XDG_CONFIG_HOME || path2.join(home, ".config"), "opencode-swarm");
   }
 }
 function resolveSwarmKnowledgePath(directory) {
-  return path.join(directory, ".swarm", "knowledge.jsonl");
+  return path2.join(resolveKnowledgeStoreDir(directory), "knowledge.jsonl");
 }
 function resolveSwarmRejectedPath(directory) {
-  return path.join(directory, ".swarm", "knowledge-rejected.jsonl");
+  return path2.join(resolveKnowledgeStoreDir(directory), "knowledge-rejected.jsonl");
 }
 function resolveSwarmRetractionsPath(directory) {
-  return path.join(directory, ".swarm", "knowledge-retractions.jsonl");
+  return path2.join(resolveKnowledgeStoreDir(directory), "knowledge-retractions.jsonl");
 }
 function resolveHiveKnowledgePath() {
   const platform = process.platform;
-  const home = process.env.HOME || os.homedir();
+  const home = process.env.HOME || os2.homedir();
   let dataDir;
   if (platform === "win32") {
-    dataDir = path.join(process.env.LOCALAPPDATA || path.join(home, "AppData", "Local"), "opencode-swarm", "Data");
+    dataDir = path2.join(process.env.LOCALAPPDATA || path2.join(home, "AppData", "Local"), "opencode-swarm", "Data");
   } else if (platform === "darwin") {
-    dataDir = path.join(home, "Library", "Application Support", "opencode-swarm");
+    dataDir = path2.join(home, "Library", "Application Support", "opencode-swarm");
   } else {
-    dataDir = path.join(process.env.XDG_DATA_HOME || path.join(home, ".local", "share"), "opencode-swarm");
+    dataDir = path2.join(process.env.XDG_DATA_HOME || path2.join(home, ".local", "share"), "opencode-swarm");
   }
-  return path.join(dataDir, "shared-learnings.jsonl");
+  return path2.join(dataDir, "shared-learnings.jsonl");
 }
 function resolveHiveRejectedPath() {
   const hivePath = resolveHiveKnowledgePath();
-  return path.join(path.dirname(hivePath), "shared-learnings-rejected.jsonl");
+  return path2.join(path2.dirname(hivePath), "shared-learnings-rejected.jsonl");
 }
 function resolveHiveEventsPath() {
   const hivePath = resolveHiveKnowledgePath();
-  return path.join(path.dirname(hivePath), "shared-knowledge-events.jsonl");
+  return path2.join(path2.dirname(hivePath), "shared-knowledge-events.jsonl");
 }
 function parseKnowledgeContent(content, max) {
   const results = [];
@@ -78,16 +221,16 @@ function parseKnowledgeContent(content, max) {
   return results;
 }
 async function readKnowledge(filePath, maxEntries) {
-  const resolvedPath = path.resolve(filePath);
+  const resolvedPath = path2.resolve(filePath);
   const cap = maxEntries !== undefined && maxEntries > 0 ? maxEntries : undefined;
   if (cap !== undefined) {
-    if (!existsSync(resolvedPath))
+    if (!existsSync2(resolvedPath))
       return [];
     const content = await readFile(resolvedPath, "utf-8");
     return parseKnowledgeContent(content, cap);
   }
   const entries = await readCachedParsedFile(resolvedPath, KNOWLEDGE_JSONL_CACHE_NAMESPACE, async () => {
-    if (!existsSync(resolvedPath))
+    if (!existsSync2(resolvedPath))
       return null;
     return await readFile(resolvedPath, "utf-8");
   }, (content) => parseKnowledgeContent(content, Infinity));
@@ -169,7 +312,7 @@ async function appendRetractionRecord(directory, record) {
   await appendKnowledge(resolveSwarmRetractionsPath(directory), record);
 }
 async function appendKnowledge(filePath, entry) {
-  const dir = path.dirname(filePath);
+  const dir = path2.dirname(filePath);
   await mkdir(dir, { recursive: true });
   let release = null;
   try {
@@ -188,7 +331,7 @@ async function appendKnowledge(filePath, entry) {
   }
 }
 async function rewriteKnowledge(filePath, entries) {
-  const dir = path.dirname(filePath);
+  const dir = path2.dirname(filePath);
   await mkdir(dir, { recursive: true });
   let release = null;
   try {
@@ -209,7 +352,7 @@ async function rewriteKnowledge(filePath, entries) {
   }
 }
 async function transactFile(filePath, read, write, mutate) {
-  const dir = path.dirname(filePath);
+  const dir = path2.dirname(filePath);
   try {
     await mkdir(dir, { recursive: true });
   } catch {
@@ -474,7 +617,7 @@ async function applyConfidenceDeltas(filePath, deltas) {
   }
   let release = null;
   try {
-    const dir = path.dirname(filePath);
+    const dir = path2.dirname(filePath);
     await mkdir(dir, { recursive: true });
     release = await import_proper_lockfile.default.lock(dir, {
       retries: { retries: 5, minTimeout: 100, maxTimeout: 500 },
@@ -537,4 +680,4 @@ var _internals = {
   bumpKnowledgeConfidenceBatch
 };
 
-export { getPlatformConfigDir, resolveSwarmKnowledgePath, resolveSwarmRejectedPath, resolveSwarmRetractionsPath, resolveHiveKnowledgePath, resolveHiveRejectedPath, resolveHiveEventsPath, readKnowledge, normalizeEntry, readRejectedLessons, readRetractionRecords, appendRetractionRecord, appendKnowledge, rewriteKnowledge, transactFile, transactKnowledge, appendKnowledgeWithCapEnforcement, enforceKnowledgeCap, sweepAgedEntries, sweepStaleTodos, appendRejectedLesson, normalize, wordBigrams, jaccardBigram, findNearDuplicate, computeConfidence, OUTCOME_SIGNAL_SMOOTHING, computeOutcomeSignal, inferTags, bumpKnowledgeConfidenceBatch, _internals };
+export { resolveLinkDir, sanitizeLinkId, readLinkPointer, writeLinkPointer, removeLinkPointer, resolveKnowledgeStoreDir, isLinked, getPlatformConfigDir, resolveSwarmKnowledgePath, resolveSwarmRejectedPath, resolveSwarmRetractionsPath, resolveHiveKnowledgePath, resolveHiveRejectedPath, resolveHiveEventsPath, readKnowledge, normalizeEntry, readRejectedLessons, readRetractionRecords, appendRetractionRecord, appendKnowledge, rewriteKnowledge, transactFile, transactKnowledge, appendKnowledgeWithCapEnforcement, enforceKnowledgeCap, sweepAgedEntries, sweepStaleTodos, appendRejectedLesson, normalize, wordBigrams, jaccardBigram, findNearDuplicate, computeConfidence, OUTCOME_SIGNAL_SMOOTHING, computeOutcomeSignal, inferTags, bumpKnowledgeConfidenceBatch, _internals };

package/dist/cli/{index-5p1gvn98.js → index-dprk5c5f.js}

@@ -1,7 +1,7 @@
 // @bun
 import {
   handleGuardrailExplain
-} from "./index-d4hpgf63.js";
+} from "./index-6k31ysgd.js";
 import {
   handleGuardrailLog
 } from "./index-gg589mfw.js";
@@ -51,6 +51,7 @@ import {
   handleKnowledgeRetryHardeningCommand,
   handleKnowledgeUnactionableCommand,
   handleLearningCommand,
+  handleLinkCommand,
   handleMemoryCommand,
   handleMemoryExportCommand,
   handleMemoryImportCommand,
@@ -73,14 +74,15 @@ import {
   handleStatusCommand,
   handleSyncPlanCommand,
   handleTurboCommand,
+  handleUnlinkCommand,
   handleWriteRetroCommand,
   normalizeSwarmCommandInput,
   resolveCommand
-} from "./index-hs2knbfq.js";
+} from "./index-9w07ye9b.js";
 import"./index-6tnmt41c.js";
 import"./index-bm4f0nme.js";
-import"./index-rh53rrpt.js";
-import"./index-e8pk68cc.js";
+import"./index-1ccnwh54.js";
+import"./index-axwxkbdd.js";
 import"./index-bywt2171.js";
 import {
   AGENT_TOOL_MAP,
@@ -337,6 +339,7 @@ export {
   resolveCommand,
   normalizeSwarmCommandInput,
   handleWriteRetroCommand,
+  handleUnlinkCommand,
   handleTurboCommand,
   handleSyncPlanCommand,
   handleStatusCommand,
@@ -359,6 +362,7 @@ export {
   handleMemoryImportCommand,
   handleMemoryExportCommand,
   handleMemoryCommand,
+  handleLinkCommand,
   handleLearningCommand,
   handleKnowledgeUnactionableCommand,
   handleKnowledgeRetryHardeningCommand,

package/dist/cli/index.js

@@ -7,11 +7,11 @@ import {
   getPluginLockFilePaths,
   package_default,
   resolveCommand
-} from "./index-hs2knbfq.js";
+} from "./index-9w07ye9b.js";
 import"./index-6tnmt41c.js";
 import"./index-bm4f0nme.js";
-import"./index-rh53rrpt.js";
-import"./index-e8pk68cc.js";
+import"./index-1ccnwh54.js";
+import"./index-axwxkbdd.js";
 import"./index-bywt2171.js";
 import {
   DEFAULT_AGENT_CONFIGS

package/dist/cli/{knowledge-store-n4x6zyk7.js → knowledge-store-gsy6p46z.js}

@@ -31,7 +31,7 @@ import {
   transactFile,
   transactKnowledge,
   wordBigrams
-} from "./index-e8pk68cc.js";
+} from "./index-axwxkbdd.js";
 import"./index-fjwwrwr5.js";
 import"./index-jtqkh8jf.js";
 import"./index-bcp79s17.js";

package/dist/cli/{skill-generator-s0spm65v.js → skill-generator-1hzfyhth.js}

@@ -22,8 +22,8 @@ import {
   retireSkill,
   sanitizeSlug,
   selectCandidateEntries
-} from "./index-rh53rrpt.js";
-import"./index-e8pk68cc.js";
+} from "./index-1ccnwh54.js";
+import"./index-axwxkbdd.js";
 import"./index-fjwwrwr5.js";
 import"./index-jtqkh8jf.js";
 import"./index-zgwm4ryv.js";

package/dist/commands/index.d.ts

@@ -32,6 +32,7 @@ export { handleHandoffCommand } from './handoff';
 export { handleHistoryCommand } from './history';
 export { handleKnowledgeListCommand, handleKnowledgeMigrateCommand, handleKnowledgeQuarantineCommand, handleKnowledgeRestoreCommand, handleKnowledgeRetryHardeningCommand, handleKnowledgeUnactionableCommand, } from './knowledge';
 export { handleLearningCommand } from './learning';
+export { handleLinkCommand } from './link';
 export { handleMemoryCommand, handleMemoryExportCommand, handleMemoryImportCommand, handleMemoryMigrateCommand, handleMemoryStatusCommand, } from './memory';
 export { handlePlanCommand } from './plan';
 export { handlePreflightCommand } from './preflight';
@@ -51,6 +52,7 @@ export { handleStatusCommand } from './status';
 export { handleSyncPlanCommand } from './sync-plan';
 export { classifySwarmCommandChatFallbackUse, classifySwarmCommandToolUse, SWARM_COMMAND_TOOL_ALLOWLIST, SWARM_COMMAND_TOOL_COMMANDS, } from './tool-policy.js';
 export { handleTurboCommand } from './turbo';
+export { handleUnlinkCommand } from './unlink';
 export { handleWriteRetroCommand } from './write-retro';
 export declare function buildHelpText(): string;
 /**

package/dist/commands/link.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Handles the `/swarm link` command.
+ *
+ * Ties this worktree's swarm knowledge store to a shared "link" store so that
+ * several swarms working on the same project (typically separate git worktrees)
+ * — or on deliberately "similar" projects — pool their lessons instead of each
+ * keeping an isolated `.swarm/knowledge.jsonl`.
+ *
+ * Usage:
+ * - /swarm link                — link using the project hash (ties all worktrees
+ *                                of the same repo to one shared store).
+ * - /swarm link <name>         — link using an explicit shared name (use the same
+ *                                name in each worktree/repo to tie them together).
+ * - /swarm link status         — show the current link state for this worktree.
+ *
+ * On link, this worktree's existing local lessons are merged (deduplicated) into
+ * the shared store so nothing already learned is lost.
+ */
+export declare function handleLinkCommand(directory: string, args: string[]): Promise<string>;

package/dist/commands/registry.d.ts

@@ -609,6 +609,29 @@ export declare const COMMAND_REGISTRY: {
         readonly category: "config";
         readonly toolPolicy: "none";
     };
+    readonly link: {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Tie this worktree to a shared swarm knowledge store [name]";
+        readonly details: "Links the current worktree to a shared knowledge store so multiple swarms working on the same project (e.g. separate git worktrees) pool their lessons instead of each keeping an isolated .swarm/knowledge.jsonl. With no name, ties all worktrees of the same repo via the project hash; with a name, ties any worktrees/repos that use the same name. Existing local lessons are merged (deduped) into the shared store. Use `/swarm link status` to inspect.";
+        readonly args: "[<name> | status]";
+        readonly category: "utility";
+        readonly toolPolicy: "none";
+    };
+    readonly 'link status': {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Show whether this worktree shares knowledge via a link";
+        readonly subcommandOf: "link";
+        readonly category: "utility";
+        readonly toolPolicy: "none";
+    };
+    readonly unlink: {
+        readonly handler: (ctx: CommandContext) => Promise<string>;
+        readonly description: "Stop sharing swarm knowledge for this worktree [--no-copy]";
+        readonly details: "Unlinks the current worktree from its shared knowledge store and returns it to a local .swarm/knowledge.jsonl. By default the shared lessons are copied back into the local store (deduped) so nothing is lost; pass --no-copy to skip the copy-back.";
+        readonly args: "[--no-copy]";
+        readonly category: "utility";
+        readonly toolPolicy: "none";
+    };
     readonly promote: {
         readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Manually promote lesson to hive knowledge";

package/dist/commands/unlink.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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.
+ *
+ * Usage:
+ * - /swarm unlink              — unlink and copy shared lessons back to local.
+ * - /swarm unlink --no-copy    — unlink without copying shared lessons back.
+ */
+export declare function handleUnlinkCommand(directory: string, args: string[]): Promise<string>;

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

@@ -146,12 +146,12 @@ export type KnowledgeEventInput = KnowledgeEvent extends infer T ? T extends Kno
 } : never : never;
 /** Receipt event verbs that reference a single knowledge_id. */
 export declare const RECEIPT_EVENT_TYPES: ReadonlySet<string>;
-/** Returns `.swarm/knowledge-events.jsonl` for the given project directory. */
+/** Returns the knowledge-events.jsonl path (link-aware via resolveKnowledgeStoreDir). */
 export declare function resolveKnowledgeEventsPath(directory: string): string;
-/** Returns `.swarm/knowledge-counter-baseline.json` for folded event counters. */
+/** Returns the knowledge-counter-baseline.json path (link-aware). */
 export declare function resolveKnowledgeCounterBaselinePath(directory: string): string;
 export declare function resolveHiveEventsPath(): string;
-/** Returns `.swarm/knowledge-application.jsonl` for legacy v2 audit records. */
+/** 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. */
 export declare function newTraceId(): string;

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

@@ -0,0 +1,82 @@
+/**
+ * Knowledge "link" resolution for the opencode-swarm knowledge system.
+ *
+ * Problem: the swarm knowledge tier is rooted at `<directory>/.swarm/`, where
+ * `directory` is `ctx.directory`. When several swarms run in separate git
+ * worktrees of the same repository, each worktree has its own `.swarm/` and
+ * therefore its own isolated knowledge store — lessons one swarm learns are
+ * invisible to the others. The hive tier is the opposite extreme: global to
+ * EVERY project on the machine.
+ *
+ * A "link" ties multiple worktrees (or several deliberately "similar" repos)
+ * to one shared knowledge store that sits between the per-worktree swarm tier
+ * and the global hive tier. Membership is declared by an opt-in pointer file at
+ * `<directory>/.swarm/link.json`. When that pointer is active, the swarm
+ * knowledge *family* (store, events, rejected, retractions, counters,
+ * quarantine, unactionable) redirects from `<directory>/.swarm` to a shared
+ * link directory in the platform data dir — co-located with the hive store.
+ *
+ * Intentionally NOT redirected (stays per-worktree): `.knowledge-shown.json`
+ * (phase-keyed, session-local outcome bookkeeping), `plan.json`, evidence, and
+ * session state. Only id-keyed / append-only knowledge data is pooled.
+ *
+ * This module is self-contained (node builtins + the atomic-write helper only)
+ * so it can be imported by knowledge-store.ts, knowledge-events.ts, and
+ * knowledge-validator.ts without coupling to the heavily test-mocked store
+ * module and without import cycles.
+ */
+/** On-disk pointer at `<directory>/.swarm/link.json`. */
+export interface LinkPointer {
+    version: 1;
+    /** 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. */
+    name?: string;
+    /** ISO 8601 creation timestamp. */
+    createdAt: string;
+    /** How the link was established. */
+    source: 'manual' | 'auto';
+}
+export declare const LINK_POINTER_FILENAME = "link.json";
+/** Root directory under which all shared link stores live: `<dataDir>/links`. */
+export declare function resolveLinkBaseDir(): string;
+/** Directory of the shared knowledge family for a given link id. */
+export declare function resolveLinkDir(linkId: string): string;
+/**
+ * Coerce an arbitrary user-supplied name into a single, path-safe directory
+ * segment. Returns null when nothing usable remains (caller falls back to the
+ * 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. */
+export declare function readLinkPointer(directory: string): LinkPointer | null;
+/** Write the link pointer atomically and invalidate the resolution cache. */
+export declare function writeLinkPointer(directory: string, pointer: LinkPointer): Promise<void>;
+/** Remove the link pointer (idempotent) and invalidate the resolution cache. */
+export declare function removeLinkPointer(directory: string): Promise<void>;
+/**
+ * Resolve the directory that holds the swarm knowledge family for `directory`.
+ *
+ * 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.
+ *
+ * NOTE: when unlinked, the return value is byte-identical to the legacy
+ * `path.join(directory, '.swarm')`, so existing callers/tests are unaffected.
+ */
+export declare function resolveKnowledgeStoreDir(directory: string): string;
+/** Drop cached resolution(s). Pass a directory to invalidate one, omit for all. */
+export declare function invalidateKnowledgeStoreDirCache(directory?: string): void;
+/** True when the worktree currently redirects to a shared link store. */
+export declare function isLinked(directory: string): boolean;
+export declare const _internals: {
+    resolveKnowledgeStoreDir: typeof resolveKnowledgeStoreDir;
+    readLinkPointer: typeof readLinkPointer;
+    writeLinkPointer: typeof writeLinkPointer;
+    removeLinkPointer: typeof removeLinkPointer;
+    invalidateKnowledgeStoreDirCache: typeof invalidateKnowledgeStoreDirCache;
+    resolveLinkDir: typeof resolveLinkDir;
+    resolveLinkBaseDir: typeof resolveLinkBaseDir;
+    sanitizeLinkId: typeof sanitizeLinkId;
+};

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

@@ -68,7 +68,7 @@ export interface ActionabilityResult {
  * quarantined rather than activated.
  */
 export declare function validateActionability(entry: Pick<KnowledgeEntryBase, 'forbidden_actions' | 'required_actions' | 'verification_checks' | 'verification_predicate' | 'applies_to_tools' | 'applies_to_agents'>): ActionabilityResult;
-/** Returns `.swarm/knowledge-unactionable.jsonl` for the given directory. */
+/** Returns the knowledge-unactionable.jsonl path for the given directory (link-aware). */
 export declare function resolveUnactionablePath(directory: string): string;
 /** One quarantined-unactionable record. */
 export interface UnactionableRecord extends KnowledgeEntryBase {