@0xmaxma/claude-gateway 1.7.8 → 1.7.10

package/dist/agent/knowledge/shared-promote.js

@@ -1,29 +1,262 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeIntoNote = mergeIntoNote;
+exports.writeCapped = writeCapped;
+exports.isIndexPointerOnly = isIndexPointerOnly;
+exports.isInstructionShapedName = isInstructionShapedName;
+exports.deriveNameFromContent = deriveNameFromContent;
 exports.makeSharedPromoter = makeSharedPromoter;
-const crypto_1 = require("crypto");
 const shared_writer_1 = require("./shared-writer");
+const shared_dedup_1 = require("./shared-dedup");
+const shared_staleness_1 = require("./shared-staleness");
 const config_1 = require("./config");
+/**
+ * Merge a newly-promoted fact into a note's existing content, rather than
+ * blindly overwriting it. Deterministic append (no extra LLM call — dreaming
+ * already spent its budget proposing the fact); a no-op if the addition is
+ * already present verbatim. `relatedNames` (issue #386 part B) adds
+ * `[[wikilink]]`s to OTHER near-duplicate notes found alongside the merge
+ * target, so the existing (previously unpopulated) `/knowledge/graph`
+ * dashboard gets real edges — `wiki.ts` already resolves `[[links]]` into
+ * graph edges, no parser change needed.
+ */
+function mergeIntoNote(existing, addition, relatedNames = []) {
+    const trimmedAddition = addition.trim();
+    // Only link what is not linked yet: a recurring fact that merges into the same
+    // note night after night would otherwise stack a duplicate `Related:` line on
+    // every pass (issue #398 review).
+    const missing = relatedNames.filter((n) => !existing.includes(`[[${n}]]`));
+    const links = missing.length ? `\n\nRelated: ${missing.map((n) => `[[${n}]]`).join(' ')}` : '';
+    if (!existing.trim())
+        return `${trimmedAddition}${links}`;
+    // Already recorded verbatim: there is nothing to append — but the note must
+    // still gain edges it is missing, or a fact that recurs under a name it
+    // already occupies stays a disconnected node forever (issue #398 review).
+    if (existing.includes(trimmedAddition))
+        return links ? `${existing.trim()}${links}` : existing;
+    return `${existing.trim()}\n\n${trimmedAddition}${links}`;
+}
+/**
+ * Write only if the result stays within the same size cap the manual
+ * `memory_shared_create`/`_update` tools enforce. Unlike those tools, dreaming
+ * has no one to show a "content too large" error to — a note a recurring topic
+ * keeps merging into over months has no natural stopping point otherwise, so
+ * once a merge would cross the cap the note is left as-is (best-effort: a
+ * skipped promotion never fails the local dream, same as any other error here).
+ */
+function writeCapped(cfg, name, content, relatedNames = []) {
+    const body = relatedNames.length ? mergeIntoNote('', content, relatedNames) : content;
+    if (body.length > shared_writer_1.MAX_SHARED_NOTE_SIZE)
+        return false;
+    (0, shared_writer_1.writeSharedNote)(cfg, name, body);
+    return true;
+}
+// ── What may be promoted, and under what name (issue #398) ─────────────────
+/** A `MEMORY.md` index bullet: `- [label](target.md) — hook`. */
+const INDEX_POINTER_LINE_RE = /^\s*[-*]\s*\[[^\]]*\]\([^)]*\)\s*(?:[-–—:].*)?$/;
+/**
+ * True when the content is nothing but `MEMORY.md` index pointers.
+ *
+ * The memory-tiering convention writes a fact to its own file AND a one-line
+ * pointer into the `MEMORY.md` index. Both land as durable `add`s, so both used
+ * to be promoted — and the pointer's links resolve only inside the promoting
+ * agent's own workspace, making it dead weight in a shared vault (issue #398:
+ * 30 of 40 live notes were pointer-only, with all 32 link targets dangling).
+ *
+ * The trailing hook text is deliberately NOT rescued into a note of its own: an
+ * index hook is written to be read next to the file it points at, so promoting
+ * it alone would put a decontextualized fragment in front of every other agent.
+ * A dream that proposes the fact itself as prose still promotes normally — only
+ * navigation scaffolding is dropped.
+ */
+function isIndexPointerOnly(content) {
+    const lines = content
+        .split('\n')
+        .map((l) => l.trim())
+        .filter(Boolean);
+    if (lines.length === 0)
+        return false;
+    return lines.every((l) => INDEX_POINTER_LINE_RE.test(l));
+}
+/** Leading verbs that make a `reason` an edit instruction rather than a topic. */
+const INSTRUCTION_VERB_RE = /^(insert|append|prepend|add|put|place|move|update|replace|remove|delete|keep|group)\b/i;
+/** Anchors an edit instruction points AT — a position or a file, not a subject. */
+const EDIT_ANCHOR_RE = /\b(before|after|above|below|between|index|section|\.md)\b/i;
+/**
+ * True when a note name reads as an instruction for editing a file rather than
+ * as the name of a fact ("insert after cron config, before the pty_shell
+ * section"). `reason` is prompted as free-form justification (`reviewer.ts`) but
+ * issue #386 repurposed it as the shared note's identity, so such strings became
+ * note names that no future occurrence of the same fact can ever match.
+ *
+ * Two signals are required — an imperative edit verb AND a positional/file
+ * anchor — because either alone is common in legitimate names ("Add-on billing
+ * is per seat", "the section header is user-visible").
+ */
+function isInstructionShapedName(name) {
+    return INSTRUCTION_VERB_RE.test(name.trim()) && EDIT_ANCHOR_RE.test(name);
+}
+/**
+ * A note name derived from the fact itself — the fallback when the proposal has
+ * no `topic` and its `reason` reads as an editing instruction.
+ *
+ * Dropping such a promotion outright (the first cut of issue #398) silently lost
+ * genuine facts whose reason merely happened to start with an edit verb, e.g.
+ * "Update the deploy section after the API change". Naming from the content
+ * keeps the fact; only content with nothing nameable in it is given up on.
+ */
+function deriveNameFromContent(content) {
+    const firstSentence = content
+        .replace(/^[\s>*-]+/, '')
+        .replace(/`+/g, '')
+        .split(/(?<=[.!?])\s|\n/)[0]
+        ?.trim();
+    if (!firstSentence)
+        return undefined;
+    const name = firstSentence.slice(0, 80).trim();
+    // Needs real topic words, not just scaffolding, to be a usable identity.
+    return (0, shared_dedup_1.significantTokens)(name).size >= 3 ? name : undefined;
+}
 /**
  * Build the per-agent→shared promotion function used after the dreaming applier
  * writes an `add` to local memory (K3↔K4). Returns `undefined` when the shared
  * KB is disabled or in `propose` (dry-run) mode — callers then skip promotion.
  *
- * A durable add is written to the shared vault under a **content-hashed**
- * filename so two proposals whose reasons slug to the same name (or a recurring
- * nightly reason) can't silently overwrite each other, and identical content
- * maps to the same file (idempotent). Extracted here so both the nightly
- * auto-applier (src/index.ts) and the manual dashboard accept endpoint share one
- * implementation.
+ * Note identity is the proposal's `reason` (issue #386) — the SAME freeform
+ * namespace `memory_shared_create`/`_update` use, not a content hash. A
+ * content-hashed name (the pre-#386 scheme) meant the same recurring fact,
+ * reworded slightly by the reviewer each night, hashed differently and was
+ * written as a brand-new note every time — this is what created the
+ * near-duplicate pileup #386 reports. Naming by `reason` instead means the
+ * same recurring fact maps to the same note name across nights, landing as an
+ * update. A `reason` that doesn't collide by name is also checked against the
+ * shared vault's near-dup search before creating, and merged into the closest
+ * match instead of creating a disconnected duplicate when one is found.
+ *
+ * Concurrency note: the name-collision check, read, and write below are not one
+ * atomic operation, so two agents dreaming at the same moment and promoting
+ * under the exact same `reason` can race — `shared-writer.ts` already documents
+ * that same-file races resolve to last-write-wins, never corruption, and other
+ * read-modify-write callers (e.g. `memory_shared_update`) have this same
+ * property. Naming by `reason` instead of a content hash makes same-name
+ * collisions between different agents more likely than the pre-#386 scheme, but
+ * it's the same accepted tradeoff, not a new class of risk.
  */
-function makeSharedPromoter(agentId, agentCfg, globalCfg) {
+function makeSharedPromoter(
+// No longer used for NAMING — issue #386 moved note identity off the agent id,
+// and issue #398 moved it to the proposal's `topic` slug (falling back to
+// `reason`, then to the fact itself), so a recurring fact maps to the same
+// shared note whichever agent dreamed it. Still carried because every declined
+// promotion is logged with the agent that proposed it.
+agentId, agentCfg, globalCfg, 
+// Promotion can decline for several reasons and used to do so in total silence,
+// which made "why did the shared vault stop growing?" undiagnosable from the
+// outside (issue #398 review). Optional so existing call sites keep working.
+logger) {
     const sharedCfg = (0, config_1.resolveSharedConfig)(agentCfg, globalCfg);
     if (!sharedCfg.enabled || sharedCfg.mode !== 'auto')
         return undefined;
+    const skip = (why, data = {}) => {
+        logger?.info('shared promotion skipped', { agentId, why, ...data });
+    };
     return (p) => {
-        const content = p.content ?? '';
-        const hash = (0, crypto_1.createHash)('sha256').update(content).digest('hex').slice(0, 8);
-        (0, shared_writer_1.writeSharedNote)(sharedCfg, `${agentId}-${p.reason}-${hash}`, content);
+        const content = (p.content ?? '').trim();
+        if (!content)
+            return;
+        // An index pointer is a per-agent navigation aid, not a shareable fact: its
+        // links resolve only inside the promoting agent's own workspace.
+        if (isIndexPointerOnly(content)) {
+            skip('index-pointer-only', { reason: p.reason });
+            return;
+        }
+        // Identity, best first: an explicit `topic` slug (mirroring the episodic
+        // contract), then the free-form `reason`, then the fact itself. A reason that
+        // reads as an editing instruction would produce a note name no later
+        // occurrence of the same fact could match, so it is passed over — but the
+        // fact is still promoted under a content-derived name.
+        const explicit = (p.topic ?? '').trim();
+        const reason = p.reason.trim();
+        const name = explicit ||
+            (reason && !isInstructionShapedName(reason) ? reason : deriveNameFromContent(content));
+        if (!name) {
+            skip('no-usable-name', { reason: p.reason });
+            return;
+        }
+        try {
+            // A `stale__` twin of THIS name means the GC retired this fact and it has
+            // now recurred — the recurrence itself is the promote-back signal. Resolved
+            // BEFORE the update/create split because both paths put a live file back at
+            // `name`, and once that file exists the GC's own restore refuses forever
+            // (`moveNoteFromStale` bails on `sharedNoteExists`). A twin left behind is
+            // not inert: retired notes stay indexed and searchable by design (#392), so
+            // the same fact would answer every query twice, permanently (issue #398
+            // review — the create path handled this, the update path did not).
+            const staleTwin = `${shared_staleness_1.STALE_NOTE_PREFIX}${name}`;
+            const retired = (0, shared_writer_1.sharedNoteExists)(sharedCfg, staleTwin)
+                ? ((0, shared_writer_1.readSharedNote)(sharedCfg, staleTwin) ?? '').replace(/^<!--[\s\S]*?-->\s*/, '').trim()
+                : '';
+            // Only drop the twin once its content is safely in the live note: a write
+            // refused by the size cap must leave the retired copy where it is.
+            const dropTwinIfWritten = (written) => {
+                if (written && retired)
+                    (0, shared_writer_1.deleteSharedNoteFile)(sharedCfg, staleTwin);
+            };
+            // Same name recurred: this IS the same fact — update it, never duplicate.
+            if ((0, shared_writer_1.sharedNoteExists)(sharedCfg, name)) {
+                const existing = (0, shared_writer_1.readSharedNote)(sharedCfg, name) ?? '';
+                const withRetired = retired ? mergeIntoNote(existing, retired) : existing;
+                const written = writeCapped(sharedCfg, name, mergeIntoNote(withRetired, content));
+                if (!written)
+                    skip('note-size-cap', { reason: p.reason, note: name });
+                dropTwinIfWritten(written);
+                return;
+            }
+            // New name, but the content may already live in another note. FTS is
+            // recall only; `filterNearDuplicates` is the precision bar that decides
+            // whether an UNATTENDED merge is justified. Below the bar the fact gets
+            // its own note — two notes are recoverable, two unrelated facts fused
+            // into one are not (issue #398).
+            //
+            // Retired (`stale__*`) notes are excluded as targets: they are indexed
+            // like any other file, and merging a fresh fact into one would write it
+            // straight into the set the GC has already moved out of the active vault.
+            const seed = (0, shared_dedup_1.buildSeedText)(name, content);
+            const candidates = (0, shared_dedup_1.findSimilarSharedNotes)(sharedCfg, seed, 3).filter((c) => !c.name.startsWith(shared_staleness_1.STALE_NOTE_PREFIX));
+            // Score against each candidate's FULL body, not the matched chunk: a long
+            // note that a recurring topic has merged into spreads the seed across
+            // chunks and would score far below its real containment.
+            const bodyOf = (c) => (0, shared_writer_1.readSharedNote)(sharedCfg, c.name) ?? '';
+            const mergeable = (0, shared_dedup_1.filterNearDuplicates)(seed, candidates, undefined, bodyOf);
+            // Wikilinks clear a LOWER bar than merges: a link is an additive "these
+            // are related" claim, while a merge asserts they are the same fact and
+            // destroys the distinction. Computed for BOTH outcomes — a new note that
+            // has related neighbours must still carry its edges, or the graph gains a
+            // disconnected node exactly in the 0.25–0.5 band (issue #398 review).
+            const linkable = (0, shared_dedup_1.filterNearDuplicates)(seed, candidates, shared_dedup_1.MIN_RELATED_CONTAINMENT, bodyOf);
+            if (mergeable.length > 0) {
+                const primary = mergeable[0];
+                const related = linkable.filter((c) => c.name !== primary.name);
+                const existing = (0, shared_writer_1.readSharedNote)(sharedCfg, primary.name) ?? '';
+                if (!writeCapped(sharedCfg, primary.name, mergeIntoNote(existing, content, related.map((r) => r.name)))) {
+                    skip('note-size-cap', { reason: p.reason, note: primary.name });
+                }
+                return;
+            }
+            // Creating fresh. Folding a retired twin back in here also stops two files
+            // from sharing one `entry_hash`, whose single lifecycle row's `path` would
+            // otherwise flip between them on every index pass.
+            const body = retired ? mergeIntoNote(retired, content) : content;
+            const written = writeCapped(sharedCfg, name, body, linkable.map((r) => r.name));
+            if (!written)
+                skip('note-size-cap', { reason: p.reason, note: name });
+            dropTwinIfWritten(written);
+        }
+        catch (err) {
+            // Best-effort — a promotion failure never affects the local dream. It must
+            // not be invisible either: a vault that silently stops growing was the
+            // undiagnosable failure issue #398 set out to close.
+            skip('write-failed', { reason: p.reason, error: err?.message });
+        }
     };
 }
 //# sourceMappingURL=shared-promote.js.map

package/dist/agent/knowledge/shared-promote.js.map

@@ -1 +1 @@
-{"version":3,"file":"shared-promote.js","sourceRoot":"","sources":["../../../src/agent/knowledge/shared-promote.ts"],"names":[],"mappings":";;AAiBA,gDAYC;AA7BD,mCAAoC;AACpC,mDAAkD;AAClD,qCAA+C;AAG/C;;;;;;;;;;;GAWG;AACH,SAAgB,kBAAkB,CAChC,OAAe,EACf,QAA2C,EAC3C,SAA4C;IAE5C,MAAM,SAAS,GAAG,IAAA,4BAAmB,EAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IAC3D,IAAI,CAAC,SAAS,CAAC,OAAO,IAAI,SAAS,CAAC,IAAI,KAAK,MAAM;QAAE,OAAO,SAAS,CAAC;IACtE,OAAO,CAAC,CAAuC,EAAE,EAAE;QACjD,MAAM,OAAO,GAAG,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC;QAChC,MAAM,IAAI,GAAG,IAAA,mBAAU,EAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAC5E,IAAA,+BAAe,EAAC,SAAS,EAAE,GAAG,OAAO,IAAI,CAAC,CAAC,MAAM,IAAI,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC;IACxE,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"shared-promote.js","sourceRoot":"","sources":["../../../src/agent/knowledge/shared-promote.ts"],"names":[],"mappings":"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"}

package/dist/agent/knowledge/shared-staleness.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Shared-KB staleness GC (issue #392 part D) — the shared-vault twin of
+ * `dreaming/staleness.ts`'s nightly per-agent GC, extending the SAME
+ * `kb_entry_lifecycle` soft-invalidate model to the shared KB, which had none
+ * at all (the shared vault's `kb_entry_lifecycle` table existed but was never
+ * populated — `indexer.ts` only computed entry blocks for `source: 'memory'`).
+ *
+ * The unit of identity here is the WHOLE NOTE (`wholeNoteEntryBlock`), not a
+ * bullet, so "moving a block" means moving the whole note. A stale note's
+ * content is written byte-identical (so its entry_hash — and thus the
+ * promote-back feedback loop — survives the move) to a `stale__<name>`
+ * sibling note, then the original file is deleted; a note retrieved AFTER
+ * being staled is moved back to its original name. This mirrors the personal
+ * archive's "decluttering by physical relocation" without merging multiple
+ * notes' content together (which would break entry-hash stability).
+ *
+ * Explicit `supersedes #N`-by-reference detection stays personal-only (issue
+ * #392 scope note): shared notes have no visible numeric id, and round 1's
+ * write-time merge/near-dup already provides de-facto content supersession.
+ * Only TTL/retrieval-based soft-invalidation applies here.
+ */
+import { ArchiveDB } from './archive-db';
+import type { ResolvedKnowledgeSharedCfg } from './types';
+import type { ResolvedStalenessCfg } from '../dreaming/types';
+/** Prefix a staled note's file is moved under (issue #392 part D). */
+export declare const STALE_NOTE_PREFIX = "stale__";
+export interface SharedStalenessResult {
+    invalidated: number;
+    promoted: number;
+    skippedMoves: number;
+    foldedLogRows: number;
+}
+/**
+ * Retire a live note: write its content byte-identical (after `comment`, which
+ * `wholeNoteEntryBlock` skips when hashing) to `stale__<name>`, then delete the
+ * original. Exported so both the TTL-based GC below and the reflection pass
+ * (issue #392 part C, merging a note into a cluster's canonical note) share one
+ * "move a note out of the active set" primitive. Returns false if the note is
+ * missing/empty.
+ */
+export declare function retireSharedNote(cfg: ResolvedKnowledgeSharedCfg, name: string, comment: string): boolean;
+/**
+ * Run the shared-KB staleness GC. Never throws; on any error the vault is left
+ * as-is. Deterministic given `opts.now`. Mirrors `runStalenessGc`'s shape.
+ */
+export declare function runSharedStalenessGc(cfg: ResolvedKnowledgeSharedCfg, staleCfg: ResolvedStalenessCfg, opts?: {
+    now?: number;
+    reindex?: (cfg: ResolvedKnowledgeSharedCfg) => void;
+    openDb?: (cfg: ResolvedKnowledgeSharedCfg) => ArchiveDB;
+}): SharedStalenessResult;
+//# sourceMappingURL=shared-staleness.d.ts.map

package/dist/agent/knowledge/shared-staleness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-staleness.d.ts","sourceRoot":"","sources":["../../../src/agent/knowledge/shared-staleness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,SAAS,EAAqB,MAAM,cAAc,CAAC;AAM5D,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,SAAS,CAAC;AAC1D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAE9D,sEAAsE;AACtE,eAAO,MAAM,iBAAiB,YAAY,CAAC;AAE3C,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;CACvB;AASD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,0BAA0B,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAaxG;AAmCD;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,0BAA0B,EAC/B,QAAQ,EAAE,oBAAoB,EAC9B,IAAI,CAAC,EAAE;IACL,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,0BAA0B,KAAK,IAAI,CAAC;IACpD,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,0BAA0B,KAAK,SAAS,CAAC;CACzD,GACA,qBAAqB,CA2CvB"}

package/dist/agent/knowledge/shared-staleness.js

@@ -0,0 +1,149 @@
+"use strict";
+/**
+ * Shared-KB staleness GC (issue #392 part D) — the shared-vault twin of
+ * `dreaming/staleness.ts`'s nightly per-agent GC, extending the SAME
+ * `kb_entry_lifecycle` soft-invalidate model to the shared KB, which had none
+ * at all (the shared vault's `kb_entry_lifecycle` table existed but was never
+ * populated — `indexer.ts` only computed entry blocks for `source: 'memory'`).
+ *
+ * The unit of identity here is the WHOLE NOTE (`wholeNoteEntryBlock`), not a
+ * bullet, so "moving a block" means moving the whole note. A stale note's
+ * content is written byte-identical (so its entry_hash — and thus the
+ * promote-back feedback loop — survives the move) to a `stale__<name>`
+ * sibling note, then the original file is deleted; a note retrieved AFTER
+ * being staled is moved back to its original name. This mirrors the personal
+ * archive's "decluttering by physical relocation" without merging multiple
+ * notes' content together (which would break entry-hash stability).
+ *
+ * Explicit `supersedes #N`-by-reference detection stays personal-only (issue
+ * #392 scope note): shared notes have no visible numeric id, and round 1's
+ * write-time merge/near-dup already provides de-facto content supersession.
+ * Only TTL/retrieval-based soft-invalidation applies here.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STALE_NOTE_PREFIX = void 0;
+exports.retireSharedNote = retireSharedNote;
+exports.runSharedStalenessGc = runSharedStalenessGc;
+const archive_db_1 = require("./archive-db");
+const staleness_1 = require("../dreaming/staleness");
+const indexer_1 = require("./indexer");
+const lifecycle_1 = require("./lifecycle");
+const shared_writer_1 = require("./shared-writer");
+const config_1 = require("./config");
+/** Prefix a staled note's file is moved under (issue #392 part D). */
+exports.STALE_NOTE_PREFIX = 'stale__';
+const ZERO = { invalidated: 0, promoted: 0, skippedMoves: 0, foldedLogRows: 0 };
+/** The note "name" (pre-slug) a lifecycle row's stored path corresponds to. */
+function nameFromPath(relPath) {
+    return relPath.replace(/\.md$/i, '');
+}
+/**
+ * Retire a live note: write its content byte-identical (after `comment`, which
+ * `wholeNoteEntryBlock` skips when hashing) to `stale__<name>`, then delete the
+ * original. Exported so both the TTL-based GC below and the reflection pass
+ * (issue #392 part C, merging a note into a cluster's canonical note) share one
+ * "move a note out of the active set" primitive. Returns false if the note is
+ * missing/empty.
+ */
+function retireSharedNote(cfg, name, comment) {
+    const content = (0, shared_writer_1.readSharedNote)(cfg, name);
+    if (!content || !content.trim())
+        return false;
+    const block = (0, lifecycle_1.wholeNoteEntryBlock)(content)[0];
+    if (!block)
+        return false;
+    const staleName = `${exports.STALE_NOTE_PREFIX}${name}`;
+    (0, shared_writer_1.writeSharedNote)(cfg, staleName, `${comment}\n${block.text}`);
+    if ((0, shared_writer_1.deleteSharedNoteFile)(cfg, name))
+        return true;
+    // A failed delete must not leave a new stale duplicate behind or let callers
+    // stamp this active note invalid. Best-effort rollback preserves the invariant
+    // that a successful retirement has exactly one physical representation.
+    (0, shared_writer_1.deleteSharedNoteFile)(cfg, staleName);
+    return false;
+}
+/**
+ * Move a live note to `stale__<name>`, preserving its content byte-identical
+ * (after a leading `<!-- staled ... -->` marker line, which `wholeNoteEntryBlock`
+ * skips when hashing) so the entry_hash — and therefore the promote-back
+ * feedback loop — survives the move. Returns false (skip, don't stamp invalid)
+ * if the note is missing/empty or the content no longer matches the block that
+ * was scored (moved/edited concurrently).
+ */
+function moveNoteToStale(cfg, r, comment) {
+    const name = nameFromPath(r.path);
+    const content = (0, shared_writer_1.readSharedNote)(cfg, name);
+    if (!content)
+        return false;
+    const block = (0, lifecycle_1.wholeNoteEntryBlock)(content)[0];
+    if (!block || block.entryHash !== r.entryHash)
+        return false; // content changed since scoring
+    return retireSharedNote(cfg, name, comment);
+}
+/** Move a staled note back to its original name (issue #392 promote-back). */
+function moveNoteFromStale(cfg, r, comment) {
+    const staleName = nameFromPath(r.path); // r.path is the stale__<name> source path
+    const content = (0, shared_writer_1.readSharedNote)(cfg, staleName);
+    if (!content)
+        return false;
+    const block = (0, lifecycle_1.wholeNoteEntryBlock)(content)[0];
+    if (!block || block.entryHash !== r.entryHash)
+        return false;
+    const originalName = staleName.startsWith(exports.STALE_NOTE_PREFIX) ? staleName.slice(exports.STALE_NOTE_PREFIX.length) : staleName;
+    // Don't clobber a brand-new note that was created at the original name while
+    // this one sat staled — leave it staled rather than lose the newer note.
+    if ((0, shared_writer_1.sharedNoteExists)(cfg, originalName))
+        return false;
+    (0, shared_writer_1.writeSharedNote)(cfg, originalName, `${comment}\n${block.text}`);
+    (0, shared_writer_1.deleteSharedNoteFile)(cfg, staleName);
+    return true;
+}
+/**
+ * Run the shared-KB staleness GC. Never throws; on any error the vault is left
+ * as-is. Deterministic given `opts.now`. Mirrors `runStalenessGc`'s shape.
+ */
+function runSharedStalenessGc(cfg, staleCfg, opts) {
+    if (!staleCfg.enabled)
+        return { ...ZERO };
+    const now = opts?.now ?? Date.now();
+    const reindex = opts?.reindex ?? ((c) => void (0, indexer_1.indexSharedArchive)(c));
+    const openDb = opts?.openDb ?? ((c) => archive_db_1.ArchiveDB.forPath((0, config_1.sharedDbPath)(c)));
+    const result = { ...ZERO };
+    try {
+        // Ensure lifecycle rows exist for the current notes (first_seen etc).
+        reindex(cfg);
+        const db = openDb(cfg);
+        if (staleCfg.recordRetrievals)
+            result.foldedLogRows = db.aggregateRetrievalLog();
+        // Every shared note is lifecycle-eligible (no evergreen/pinned distinction).
+        const { invalidate, promote } = (0, staleness_1.decideStaleness)(db.listLifecycle(), staleCfg, now, () => true);
+        const date = new Date(now).toISOString().slice(0, 10);
+        for (const r of invalidate) {
+            const comment = `<!-- staled ${date} (aged out, ${r.retrievalCount} retrievals) -->`;
+            if (moveNoteToStale(cfg, r, comment)) {
+                db.stampInvalid(r.entryHash, now);
+                result.invalidated++;
+            }
+            else {
+                result.skippedMoves++;
+            }
+        }
+        for (const r of promote) {
+            const comment = `<!-- restored ${date} (retrieved after invalidation) -->`;
+            if (moveNoteFromStale(cfg, r, comment)) {
+                db.stampInvalid(r.entryHash, null);
+                result.promoted++;
+            }
+            else {
+                result.skippedMoves++;
+            }
+        }
+        if (result.invalidated + result.promoted > 0)
+            reindex(cfg);
+    }
+    catch {
+        /* best-effort — leave the vault untouched on any error */
+    }
+    return result;
+}
+//# sourceMappingURL=shared-staleness.js.map

package/dist/agent/knowledge/shared-staleness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-staleness.js","sourceRoot":"","sources":["../../../src/agent/knowledge/shared-staleness.ts"],"names":[],"mappings":"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"}

package/dist/agent/knowledge/shared-writer.d.ts

@@ -14,6 +14,25 @@
  * escape the notes dir.
  */
 import type { ResolvedKnowledgeSharedCfg } from './types';
+/**
+ * Same cap the Bun-side MCP tools enforce on `memory_shared_create`/`_update`
+ * (`MAX_SHARED_NOTE_SIZE` in `mcp/tools/memory/module.ts`) — kept as an
+ * independent constant here since the two processes don't share imports
+ * (see the cross-runtime note in `shared-dedup.ts`). Keep both values in sync.
+ */
+export declare const MAX_SHARED_NOTE_SIZE: number;
+/** Whether a note already exists at this name (post-`sharedNoteFilename` slugification). */
+export declare function sharedNoteExists(cfg: ResolvedKnowledgeSharedCfg, name: string): boolean;
+/** Full content of a shared note, or null if it does not exist / is unreadable. */
+export declare function readSharedNote(cfg: ResolvedKnowledgeSharedCfg, name: string): string | null;
+/**
+ * Delete a shared note's file (issue #392 part D — the staleness GC moves a
+ * note's content elsewhere, then removes the original). Returns true if a file
+ * was actually removed, false if it didn't exist. Best-effort: any other error
+ * (permissions, race) is swallowed and reported as false, mirroring the rest of
+ * this module's "never throws into the caller's control flow" stance.
+ */
+export declare function deleteSharedNoteFile(cfg: ResolvedKnowledgeSharedCfg, name: string): boolean;
 /** Reduce an arbitrary name to one safe `*.md` path segment (no traversal). */
 export declare function sharedNoteFilename(name: string): string;
 /**

package/dist/agent/knowledge/shared-writer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shared-writer.d.ts","sourceRoot":"","sources":["../../../src/agent/knowledge/shared-writer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,SAAS,CAAC;AAM1D,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQvD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,0BAA0B,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAqBtG"}
+{"version":3,"file":"shared-writer.d.ts","sourceRoot":"","sources":["../../../src/agent/knowledge/shared-writer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,SAAS,CAAC;AAE1D;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,QAAa,CAAC;AAE/C,4FAA4F;AAC5F,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,0BAA0B,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEvF;AAED,mFAAmF;AACnF,wBAAgB,cAAc,CAAC,GAAG,EAAE,0BAA0B,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAO3F;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,0BAA0B,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAQ3F;AAMD,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQvD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,0BAA0B,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAqBtG"}

package/dist/agent/knowledge/shared-writer.js

@@ -48,11 +48,53 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_SHARED_NOTE_SIZE = void 0;
+exports.sharedNoteExists = sharedNoteExists;
+exports.readSharedNote = readSharedNote;
+exports.deleteSharedNoteFile = deleteSharedNoteFile;
 exports.sharedNoteFilename = sharedNoteFilename;
 exports.writeSharedNote = writeSharedNote;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const config_1 = require("./config");
+/**
+ * Same cap the Bun-side MCP tools enforce on `memory_shared_create`/`_update`
+ * (`MAX_SHARED_NOTE_SIZE` in `mcp/tools/memory/module.ts`) — kept as an
+ * independent constant here since the two processes don't share imports
+ * (see the cross-runtime note in `shared-dedup.ts`). Keep both values in sync.
+ */
+exports.MAX_SHARED_NOTE_SIZE = 100 * 1024;
+/** Whether a note already exists at this name (post-`sharedNoteFilename` slugification). */
+function sharedNoteExists(cfg, name) {
+    return fs.existsSync(path.join((0, config_1.sharedNotesDir)(cfg), sharedNoteFilename(name)));
+}
+/** Full content of a shared note, or null if it does not exist / is unreadable. */
+function readSharedNote(cfg, name) {
+    const target = path.join((0, config_1.sharedNotesDir)(cfg), sharedNoteFilename(name));
+    try {
+        return fs.readFileSync(target, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Delete a shared note's file (issue #392 part D — the staleness GC moves a
+ * note's content elsewhere, then removes the original). Returns true if a file
+ * was actually removed, false if it didn't exist. Best-effort: any other error
+ * (permissions, race) is swallowed and reported as false, mirroring the rest of
+ * this module's "never throws into the caller's control flow" stance.
+ */
+function deleteSharedNoteFile(cfg, name) {
+    const target = path.join((0, config_1.sharedNotesDir)(cfg), sharedNoteFilename(name));
+    try {
+        fs.unlinkSync(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 // Monotonic per-process counter so concurrent writes within one process still get
 // distinct temp names (combined with pid for cross-process uniqueness).
 let tmpCounter = 0;

package/dist/agent/knowledge/shared-writer.js.map

@@ -1 +1 @@
-{"version":3,"file":"shared-writer.js","sourceRoot":"","sources":["../../../src/agent/knowledge/shared-writer.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAYH,gDAQC;AAMD,0CAqBC;AA7CD,uCAAyB;AACzB,2CAA6B;AAC7B,qCAA0C;AAG1C,kFAAkF;AAClF,wEAAwE;AACxE,IAAI,UAAU,GAAG,CAAC,CAAC;AAEnB,+EAA+E;AAC/E,SAAgB,kBAAkB,CAAC,IAAY;IAC7C,MAAM,IAAI,GAAG,IAAI;SACd,WAAW,EAAE;SACb,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC;SACrB,OAAO,CAAC,gBAAgB,EAAE,GAAG,CAAC;SAC9B,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC;SAC7B,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACjB,OAAO,GAAG,IAAI,IAAI,MAAM,KAAK,CAAC;AAChC,CAAC;AAED;;;GAGG;AACH,SAAgB,eAAe,CAAC,GAA+B,EAAE,IAAY,EAAE,OAAe;IAC5F,MAAM,GAAG,GAAG,IAAA,uBAAc,EAAC,GAAG,CAAC,CAAC;IAChC,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACvC,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC;IACxD,6EAA6E;IAC7E,gFAAgF;IAChF,iFAAiF;IACjF,8EAA8E;IAC9E,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,OAAO,CAAC,GAAG,IAAI,CAAC,UAAU,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC;IACpH,IAAI,CAAC;QACH,EAAE,CAAC,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;QACvC,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,iBAAiB;IAC/C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC;YACH,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAClC,CAAC;QAAC,MAAM,CAAC;YACP,yBAAyB;QAC3B,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"shared-writer.js","sourceRoot":"","sources":["../../../src/agent/knowledge/shared-writer.ts"],"names":[],"mappings":"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"}