opencode-swarm 7.116.0 → 7.117.0

package/dist/cli/{index-cnrhj56z.js → index-xdsd2hma.js}

@@ -12,10 +12,7 @@ import {
 import {
   readSwarmFileAsync,
   validateSwarmPath
-} from "./index-wh8949ef.js";
-import {
-  readCachedParsedFile
-} from "./index-jtqkh8jf.js";
+} from "./index-kzj3fp7c.js";
 import {
   criticalWarn,
   error,
@@ -27,10 +24,10 @@ import {
   readTaskEvidence,
   readTaskEvidenceRaw,
   sanitizeTaskId
-} from "./index-81vzywh3.js";
+} from "./index-abjjn4yh.js";
 import {
   atomicWriteFile
-} from "./index-bbsaxnj5.js";
+} from "./index-0pfqcjp6.js";
 import {
   ZodError,
   exports_external
@@ -38,6 +35,9 @@ import {
 import {
   withEvidenceLock
 } from "./index-42cx6g2h.js";
+import {
+  readCachedParsedFile
+} from "./index-fsrp8wp3.js";
 import {
   emit
 } from "./index-q2rrv0cy.js";

package/dist/cli/index.js

@@ -7,7 +7,7 @@ import {
   getPluginLockFilePaths,
   package_default,
   resolveCommand
-} from "./index-me46ffm2.js";
+} from "./index-vkdr12ek.js";
 import"./index-nprawcc0.js";
 import"./index-8j5d3ytd.js";
 import"./index-c8s9a3zh.js";
@@ -15,32 +15,32 @@ import"./index-m7hc7nn7.js";
 import {
   DEFAULT_AGENT_CONFIGS
 } from "./index-nvc0nsvg.js";
-import"./index-cnrhj56z.js";
+import"./index-xdsd2hma.js";
 import"./index-scww5b77.js";
 import"./index-4905hd2m.js";
-import"./index-a6f8b0vn.js";
-import"./index-s385axt1.js";
-import"./index-jyetmzcn.js";
-import"./index-8bvh0qfa.js";
-import"./index-3yh67t1h.js";
-import"./index-k5ey429j.js";
+import"./index-5bcrp3bc.js";
+import"./index-hskmya46.js";
+import"./index-c9m5skgs.js";
+import"./index-af94ke83.js";
+import"./index-dc3j6jmk.js";
+import"./index-aws8yhwq.js";
 import"./index-bfwt3abw.js";
-import"./index-qgeeyy75.js";
+import"./index-4f4zv8pb.js";
 import"./index-vxv732ex.js";
 import"./index-8fwhhayc.js";
 import"./index-q1exe2b3.js";
 import"./index-n6fa2hhk.js";
 import"./index-rdwfqhp7.js";
-import"./index-wh8949ef.js";
-import"./index-jtqkh8jf.js";
+import"./index-kzj3fp7c.js";
 import"./index-5e4e2hvv.js";
 import"./index-p0arc26j.js";
 import"./index-zgwm4ryv.js";
 import"./index-dqh3zhhc.js";
-import"./index-81vzywh3.js";
-import"./index-bbsaxnj5.js";
+import"./index-abjjn4yh.js";
+import"./index-0pfqcjp6.js";
 import"./index-293f68mj.js";
 import"./index-42cx6g2h.js";
+import"./index-fsrp8wp3.js";
 import"./index-q2rrv0cy.js";
 import"./index-vvk2g744.js";
 import"./index-qe3v54nb.js";

package/dist/cli/{knowledge-escalator-0bq62d34.js → knowledge-escalator-bmk725p4.js}

@@ -8,15 +8,15 @@ import {
   maybeEscalateOnViolation,
   maybeQuarantineOnContradiction,
   readRecentEscalations
-} from "./index-8bvh0qfa.js";
-import"./index-3yh67t1h.js";
-import"./index-k5ey429j.js";
+} from "./index-af94ke83.js";
+import"./index-dc3j6jmk.js";
+import"./index-aws8yhwq.js";
 import"./index-bfwt3abw.js";
-import"./index-qgeeyy75.js";
-import"./index-jtqkh8jf.js";
+import"./index-4f4zv8pb.js";
 import"./index-zgwm4ryv.js";
-import"./index-bbsaxnj5.js";
+import"./index-0pfqcjp6.js";
 import"./index-42cx6g2h.js";
+import"./index-fsrp8wp3.js";
 import"./index-q2rrv0cy.js";
 import"./index-vvk2g744.js";
 import"./index-qe3v54nb.js";

package/dist/cli/{knowledge-events-cwwky393.js → knowledge-events-px14n75v.js}

@@ -25,11 +25,12 @@ import {
   resolveKnowledgeCounterBaselinePath,
   resolveKnowledgeEventsPath,
   resolveLegacyApplicationLogPath
-} from "./index-3yh67t1h.js";
-import"./index-qgeeyy75.js";
+} from "./index-dc3j6jmk.js";
+import"./index-4f4zv8pb.js";
 import"./index-zgwm4ryv.js";
-import"./index-bbsaxnj5.js";
+import"./index-0pfqcjp6.js";
 import"./index-42cx6g2h.js";
+import"./index-fsrp8wp3.js";
 import"./index-q2rrv0cy.js";
 import"./index-vvk2g744.js";
 import"./index-qe3v54nb.js";

package/dist/cli/{knowledge-store-q8x4h82m.js → knowledge-store-z9znvtn2.js}

@@ -34,13 +34,13 @@ import {
   transactFile,
   transactKnowledge,
   wordBigrams
-} from "./index-k5ey429j.js";
+} from "./index-aws8yhwq.js";
 import"./index-bfwt3abw.js";
-import"./index-qgeeyy75.js";
-import"./index-jtqkh8jf.js";
+import"./index-4f4zv8pb.js";
 import"./index-zgwm4ryv.js";
-import"./index-bbsaxnj5.js";
+import"./index-0pfqcjp6.js";
 import"./index-42cx6g2h.js";
+import"./index-fsrp8wp3.js";
 import"./index-q2rrv0cy.js";
 import"./index-vvk2g744.js";
 import"./index-qe3v54nb.js";

package/dist/cli/{knowledge-validator-zr0djm02.js → knowledge-validator-7r5t821g.js}

@@ -23,14 +23,14 @@ import {
   validateLesson,
   validateSkillCandidatePath,
   validateSkillPath
-} from "./index-jyetmzcn.js";
-import"./index-k5ey429j.js";
+} from "./index-c9m5skgs.js";
+import"./index-aws8yhwq.js";
 import"./index-bfwt3abw.js";
-import"./index-qgeeyy75.js";
-import"./index-jtqkh8jf.js";
+import"./index-4f4zv8pb.js";
 import"./index-zgwm4ryv.js";
-import"./index-bbsaxnj5.js";
+import"./index-0pfqcjp6.js";
 import"./index-42cx6g2h.js";
+import"./index-fsrp8wp3.js";
 import"./index-q2rrv0cy.js";
 import"./index-vvk2g744.js";
 import"./index-qe3v54nb.js";

package/dist/cli/{pending-delegations-rr9x47rd.js → pending-delegations-9cn17983.js}

@@ -1,8 +1,7 @@
 // @bun
 import {
   validateSwarmPath
-} from "./index-wh8949ef.js";
-import"./index-jtqkh8jf.js";
+} from "./index-kzj3fp7c.js";
 import"./index-5e4e2hvv.js";
 import"./index-p0arc26j.js";
 import {
@@ -15,6 +14,7 @@ import {
 import {
   withEvidenceLock
 } from "./index-42cx6g2h.js";
+import"./index-fsrp8wp3.js";
 import"./index-q2rrv0cy.js";
 import"./index-vvk2g744.js";
 import"./index-qe3v54nb.js";

package/dist/cli/{pr-subscriptions-cny2jz2d.js → pr-subscriptions-8a6jwek2.js}

@@ -9,14 +9,14 @@ import {
   sweepStale,
   unsubscribe,
   updateSnapshot
-} from "./index-a6f8b0vn.js";
-import"./index-wh8949ef.js";
-import"./index-jtqkh8jf.js";
+} from "./index-5bcrp3bc.js";
+import"./index-kzj3fp7c.js";
 import"./index-5e4e2hvv.js";
 import"./index-p0arc26j.js";
 import"./index-zgwm4ryv.js";
 import"./index-293f68mj.js";
 import"./index-42cx6g2h.js";
+import"./index-fsrp8wp3.js";
 import"./index-q2rrv0cy.js";
 import"./index-vvk2g744.js";
 import"./index-qe3v54nb.js";

package/dist/cli/{skill-generator-mz267btk.js → skill-generator-4d3w8sqt.js}

@@ -33,16 +33,16 @@ import {
   sanitizeSlug,
   selectCandidateEntries,
   writeEvalStub
-} from "./index-s385axt1.js";
-import"./index-jyetmzcn.js";
-import"./index-3yh67t1h.js";
-import"./index-k5ey429j.js";
+} from "./index-hskmya46.js";
+import"./index-c9m5skgs.js";
+import"./index-dc3j6jmk.js";
+import"./index-aws8yhwq.js";
 import"./index-bfwt3abw.js";
-import"./index-qgeeyy75.js";
-import"./index-jtqkh8jf.js";
+import"./index-4f4zv8pb.js";
 import"./index-zgwm4ryv.js";
-import"./index-bbsaxnj5.js";
+import"./index-0pfqcjp6.js";
 import"./index-42cx6g2h.js";
+import"./index-fsrp8wp3.js";
 import"./index-q2rrv0cy.js";
 import"./index-vvk2g744.js";
 import"./index-qe3v54nb.js";

package/dist/commands/close.d.ts

@@ -156,6 +156,17 @@ export declare function runCleanStage(ctx: CloseStageContext): Promise<CleanStag
  * the close summary. All warnings are pushed into ctx.warnings.
  */
 export declare function runAlignStage(ctx: CloseStageContext): Promise<GitAlignResult>;
+/**
+ * Builds the `/swarm finalize --dry-run` report. Purely READ-ONLY: inspects the
+ * plan and the filesystem and describes what a real finalize WOULD do, without
+ * acquiring the finalize lock, creating an archive bundle, deleting any file,
+ * running git, or tearing down session state. (#1692)
+ *
+ * The archive-first guard means the clean stage only removes files it first
+ * archived successfully; this report approximates that by listing existing
+ * clean-set members as "would remove" and notes the approximation.
+ */
+export declare function runFinalizeDryRun(directory: string, swarmDir: string, planData: PlanData, planExists: boolean): Promise<string>;
 /**
  * Handles /swarm close command - performs full terminal session finalization:
  * 0. Guarantee: mark all incomplete phases/tasks as closed
@@ -198,6 +209,7 @@ export declare const _internals: {
     runArchiveEvidenceRetention: typeof runArchiveEvidenceRetention;
     runCleanStage: typeof runCleanStage;
     runAlignStage: typeof runAlignStage;
+    runFinalizeDryRun: typeof runFinalizeDryRun;
     archiveEvidence: typeof archiveEvidence;
     closePlanTerminalState: typeof closePlanTerminalState;
     endAgentSession: typeof endAgentSession;

package/dist/commands/link.d.ts

@@ -7,13 +7,16 @@
  * 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                — link using the canonical cohort id (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.
+ * On link, this worktree's existing local knowledge *family* (store, events,
+ * rejected, retractions, counters, quarantine, unactionable, application-legacy)
+ * is migrated into the shared store per the family manifest, with each member
+ * merged according to its strategy (issue #1846). The pointer is flipped only
+ * after the migration commits.
  */
 export declare function handleLinkCommand(directory: string, args: string[]): Promise<string>;

package/dist/commands/registry.d.ts

@@ -381,16 +381,16 @@ export declare const COMMAND_REGISTRY: {
     readonly finalize: {
         readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Use /swarm finalize to finalize the swarm project and archive evidence";
-        readonly details: "Idempotent 4-stage terminal finalization: (1) finalize writes retrospectives for in-progress phases, (2) archive creates timestamped bundle of swarm artifacts and evidence, (3) clean removes active-state files for a clean slate, (4) align performs aggressive git reset --hard to the default remote branch, discarding uncommitted changes and gitignored build artifacts (user-created untracked files are preserved); falls back to a cautious reset that preserves uncommitted changes when the aggressive path cannot proceed. WARNING: alignment discards local changes and gitignored files. Resets agent sessions and delegation chains. Reads .swarm/close-lessons.md for explicit lessons and runs curation. Use --skill-review to run the quota-bounded skill_improver in proposal mode.";
-        readonly args: "--prune-branches, --skill-review";
+        readonly details: "Idempotent 4-stage terminal finalization: (1) finalize writes retrospectives for in-progress phases, (2) archive creates timestamped bundle of swarm artifacts and evidence, (3) clean removes active-state files for a clean slate, (4) align performs aggressive git reset --hard to the default remote branch, discarding uncommitted changes and gitignored build artifacts (user-created untracked files are preserved); falls back to a cautious reset that preserves uncommitted changes when the aggressive path cannot proceed. WARNING: alignment discards local changes and gitignored files. Resets agent sessions and delegation chains. Reads .swarm/close-lessons.md for explicit lessons and runs curation. Use --skill-review to run the quota-bounded skill_improver in proposal mode. Use --dry-run to preview what finalize would archive, clean, and align without taking the lock or changing anything.";
+        readonly args: "--prune-branches, --skill-review, --dry-run";
         readonly category: "core";
         readonly toolPolicy: "none";
     };
     readonly close: {
         readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Use /swarm close (deprecated alias) to finalize and archive swarm state";
-        readonly details: "Deprecated alias for /swarm finalize. Preserved for backward compatibility.";
-        readonly args: "--prune-branches, --skill-review";
+        readonly details: "Deprecated alias for /swarm finalize. Preserved for backward compatibility. Supports the same flags, including --dry-run.";
+        readonly args: "--prune-branches, --skill-review, --dry-run";
         readonly category: "core";
         readonly aliasOf: "finalize";
         readonly deprecated: true;
@@ -698,7 +698,7 @@ export declare const COMMAND_REGISTRY: {
     readonly reset: {
         readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Clear swarm state files [--confirm]";
-        readonly details: "DELETES plan.md, context.md, and summaries/ directory from .swarm/. Stops background automation and clears in-memory queues. SAFETY: requires --confirm flag — without it, displays a warning and tips to export first.";
+        readonly details: "DELETES plan.md, context.md, and summaries/ directory from .swarm/. Stops background automation and clears in-memory queues. SAFETY: requires --confirm flag — without it, displays a warning and tips to export first. Before deleting, auto-backs up the state it removes to .swarm/reset-backups/<timestamp>/ (newest 5 kept) so it can be restored by copying the files back.";
         readonly args: "--confirm (required)";
         readonly category: "utility";
         readonly clashesWithNativeCcCommand: "/reset";
@@ -707,7 +707,7 @@ export declare const COMMAND_REGISTRY: {
     readonly 'reset-session': {
         readonly handler: (ctx: CommandContext) => Promise<string>;
         readonly description: "Clear session state while preserving plan, evidence, and knowledge";
-        readonly details: "Deletes only .swarm/session/state.json and any other session files. Clears in-memory agent sessions and delegation chains. Preserves plan, evidence, and knowledge for cross-session continuity.";
+        readonly details: "Deletes only .swarm/session/state.json and any other session files. Clears in-memory agent sessions and delegation chains. Preserves plan, evidence, and knowledge for cross-session continuity. Before deleting, auto-backs up the session files it removes to .swarm/reset-backups/<timestamp>/ (newest 5 kept).";
         readonly args: "";
         readonly category: "utility";
         readonly toolPolicy: "restricted";

package/dist/commands/reset-backup.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Result of an auto-backup taken before a destructive /swarm reset or
+ * /swarm reset-session. Fail-open by contract: any per-entry failure is
+ * recorded as a warning and never thrown.
+ */
+export interface ResetBackupResult {
+    /** Absolute path of the backup directory, or null if nothing was backed up. */
+    backupDir: string | null;
+    /** Relative names actually copied into the backup. */
+    copied: string[];
+    /** Non-fatal warnings (source unreadable, prune failure, etc.). */
+    warnings: string[];
+}
+/** How many backup directories to retain under .swarm/reset-backups/. */
+export declare const RESET_BACKUP_RETENTION = 5;
+/**
+ * Copy the swarm-state entries a reset is about to delete into a durable,
+ * timestamped directory under `.swarm/reset-backups/` BEFORE deletion, so the
+ * user can recover by copying the files back. The backup directory is not part
+ * of any reset deletion set, so it survives the reset.
+ *
+ * This deliberately does NOT use the git checkpoint tool: that tool excludes
+ * `.swarm/` (`git add ... :!.swarm/`) — i.e. it excludes exactly the state a
+ * reset destroys — and would commit unrelated working-tree changes to the
+ * user's branch. A direct file copy of the deleted state is the faithful,
+ * non-surprising backup. (#1692)
+ *
+ * @param directory  project root (contains `.swarm/`)
+ * @param kind       backup label prefix ('reset' | 'reset-session')
+ * @param relEntries entries relative to `.swarm/` to back up (files or dirs)
+ */
+export declare function backupSwarmStateBeforeReset(directory: string, kind: 'reset' | 'reset-session', relEntries: string[]): ResetBackupResult;

package/dist/commands/reset-session.d.ts

@@ -1,4 +1,5 @@
 import { type OrphanCleanupResult } from '../worktree/merge';
+import { type ResetBackupResult } from './reset-backup';
 /**
  * _internals DI seam for testing reset-session without spawning real git processes.
  * Production code calls `_internals.cleanupOrphanedBranches(...)` so tests can
@@ -7,6 +8,7 @@ import { type OrphanCleanupResult } from '../worktree/merge';
  */
 export declare const _internals: {
     cleanupOrphanedBranches: (directory: string, activeSessionIds: string[]) => Promise<OrphanCleanupResult>;
+    backupSwarmStateBeforeReset: (directory: string, kind: 'reset' | 'reset-session', relEntries: string[]) => ResetBackupResult;
 };
 /**
  * Handles the /swarm reset-session command.

package/dist/commands/reset.d.ts

@@ -1,3 +1,12 @@
+import { type ResetBackupResult } from './reset-backup';
+/**
+ * _internals DI seam so tests can stub the pre-deletion backup without touching
+ * the real filesystem-copy helper. Mutations are file-scoped and restorable in
+ * afterEach.
+ */
+export declare const _internals: {
+    backupSwarmStateBeforeReset: (directory: string, kind: 'reset' | 'reset-session', relEntries: string[]) => ResetBackupResult;
+};
 /**
  * Handles the /swarm reset command.
  * Clears all swarm state files from .swarm/ and project root.

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/evidence/task-file.d.ts

@@ -39,6 +39,13 @@ export declare const _internals: {
  * Atomic write: write to a unique temp file, then rename over the target.
  * The rename is atomic on POSIX and Windows, so readers never observe a torn
  * file. The temp file is cleaned up in `finally` (no-op once renamed away).
+ *
+ * Invalidates any swarm-artifact-cache entry for `targetPath` after a
+ * successful rename: the cache's stat-based staleness check can collide on a
+ * same-size rewrite that lands within one filesystem timestamp tick (issue
+ * #1729), which would otherwise let a read immediately following this write
+ * (e.g. a second locked transaction in the same logical operation) observe
+ * the pre-write content instead of what was just committed.
  */
 export declare function atomicWriteFile(targetPath: string, content: string): Promise<void>;
 /**

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

@@ -267,6 +267,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 +363,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.