@tpsdev-ai/flair 0.51.2 → 0.52.0

package/dist/resources/Memory.js

@@ -1,19 +1,25 @@
 import { databases } from "harper";
 import { patchRecord, withDetachedTxn } from "./table-helpers.js";
 import { isAdmin, resolveAgentAuth } from "./agent-auth.js";
+import { guardAuthorityFields } from "./authority-field-guard.js";
+import { isForbiddenOwnerMutation } from "./record-owner-guard.js";
+import { guardOwnerFieldImmutable } from "./owner-field-guard.js";
 import { localInstanceId } from "./instance-identity.js";
 import { getEmbedding, getModelId } from "./embeddings-provider.js";
+import { isEmbeddingSpaceUniform, noteWriteStamp } from "./embedding-space-guard.js";
 import { scanFields, isStrictMode } from "./content-safety.js";
 import { invalidEntitiesResponse } from "./entity-vocab.js";
 import { checkRateLimit, rateLimitResponse } from "./rate-limiter.js";
 import { assertValidVisibility, assertVisibilityAllowedForDurability } from "./memory-visibility.js";
 import { assertValidDurability } from "./memory-durability.js";
+import { enforceSkillDurability, rejectSkillWritePath, skillEmbedText, skillScanGate } from "./skill-write.js";
 import { DEDUP_COSINE_THRESHOLD_DEFAULT, DEDUP_LEXICAL_THRESHOLD_DEFAULT, DEDUP_MIN_CONTENT_LENGTH, computeMatchConfidence, cosineSimilarity, isConservativeMatch, } from "./dedup.js";
 import { buildProvenance, makeAuthGate, makeReadScope, makeByIdReadGate, makeScopedSearch, resolveAuthGate, stampAttribution, FORBIDDEN, UNAUTH, } from "./record-type-kit.js";
 import { RECORD_TYPES } from "./record-types.js";
 import { attachTrust } from "./trust-block.js";
 import { recordCitations } from "./usage-recording.js";
 import { noteMemoryUpsert, noteMemoryDelete } from "./bm25-index-service.js";
+import { applyHitStats, clearHitStats, overlayHitStatsResult } from "./hit-tracking.js";
 /**
  * flair#744 slice 1 — read the opt-in `includeTrust` flag for a by-id get.
  * Two entry shapes: an in-process caller (resources/mcp-tools.ts's memory_get)
@@ -112,6 +118,16 @@ const memoryAuthGate = makeAuthGate();
 async function findConservativeDedupMatch(ctx, agentId, contentText, embedding, cosineThreshold, lexicalThreshold) {
     if (!agentId || !embedding || embedding.length === 0)
         return null;
+    // ── Vector-space uniformity guard (embedding-space-guard slice 1) ──────────
+    // When the corpus is not uniform in the current embedding space, the cosine
+    // compare below would cross vector spaces (Harper zero-pads / returns a
+    // garbage score). No-op the dedup cosine leg — treat as no-match — through
+    // the SAME single chokepoint the recall leg (SemanticSearch) consults.
+    // ADVISORY ONLY: the write always proceeds (runDedupGate already computed and
+    // stamped a fresh CURRENT-space embedding); this only skips a comparison that
+    // can't be trusted while spaces are mixed. Never suppresses a write.
+    if (!(await isEmbeddingSpaceUniform()))
+        return null;
     try {
         const query = {
             sort: { attribute: "embedding", target: embedding, distance: "cosine" },
@@ -119,7 +135,11 @@ async function findConservativeDedupMatch(ctx, agentId, contentText, embedding,
                 { attribute: "agentId", comparator: "equals", value: agentId },
                 { attribute: "archived", comparator: "not_equal", value: true },
             ],
-            select: ["id", "content", "$distance"],
+            // flair#1546 dedup footnote: `trigger`/`tags` widen the candidate
+            // projection so the LEXICAL leg can compare trigger-vs-trigger for skill
+            // rows (see the computeMatchConfidence call below). Non-skill candidates
+            // are unaffected — skillEmbedText falls back to `content`.
+            select: ["id", "content", "trigger", "tags", "$distance"],
             limit: 1,
         };
         let top = null;
@@ -188,7 +208,15 @@ async function findConservativeDedupMatch(ctx, agentId, contentText, embedding,
             const candidateEmbedding = Array.isArray(fullCandidate?.embedding) ? fullCandidate.embedding : [];
             cosine = cosineSimilarity(embedding, candidateEmbedding);
         }
-        const confidence = computeMatchConfidence(contentText, top.content, cosine);
+        // flair#1546 dedup footnote (Kern, non-blocking): the lexical leg must
+        // compare the SAME text the vector represents on BOTH sides. `contentText`
+        // is already skillEmbedText(new) (the trigger for a skill write); the
+        // candidate side must match — skillEmbedText(top) returns the candidate's
+        // `trigger` when it is a skill row, its `content` otherwise. Pre-fix this
+        // crossed the new row's trigger against the candidate's stored `content`
+        // (trigger-vs-content), under-flagging near-duplicate skill triggers.
+        const candidateLexText = skillEmbedText(top);
+        const confidence = computeMatchConfidence(contentText, candidateLexText, cosine);
         if (!isConservativeMatch(confidence.cosine, confidence.lexical, cosineThreshold, lexicalThreshold)) {
             return null;
         }
@@ -216,7 +244,13 @@ async function runDedupGate(ctx, content) {
     delete content.dedup;
     delete content.dedupThreshold;
     delete content.lexicalThreshold;
-    if (typeof content.content !== "string" || content.content.length < DEDUP_MIN_CONTENT_LENGTH) {
+    // flair#1542: skill-tagged rows embed from `trigger`, not `content` — the
+    // dedup gate must compare the SAME text the stored vector represents, or a
+    // skill's dedup cosine would cross the trigger-space vector against
+    // content-space candidates. Non-skill rows are byte-identical (skillEmbedText
+    // returns `content`).
+    const embedText = skillEmbedText(content);
+    if (typeof embedText !== "string" || embedText.length < DEDUP_MIN_CONTENT_LENGTH) {
         return null;
     }
     // flair#504 Phase 2: 'document' — this embedding IS the stored vector (the
@@ -241,7 +275,7 @@ async function runDedupGate(ctx, content) {
     let embedding = Array.isArray(content.embedding) ? content.embedding : null;
     if (!embedding) {
         try {
-            embedding = await getEmbedding(content.content, "document");
+            embedding = await getEmbedding(embedText, "document");
         }
         catch {
             embedding = null;
@@ -253,7 +287,7 @@ async function runDedupGate(ctx, content) {
     }
     if (!embedding)
         return null;
-    return findConservativeDedupMatch(ctx, content.agentId, content.content, embedding, cosineThreshold, lexicalThreshold);
+    return findConservativeDedupMatch(ctx, content.agentId, embedText, embedding, cosineThreshold, lexicalThreshold);
 }
 /** Build the final write response: always `written: true`, always includes
  *  `id`, `visibility`, and layers the dedup collision signal on top when
@@ -482,7 +516,7 @@ export class Memory extends databases.flair.Memory {
      * allowCreate/allowUpdate/allowDelete are deliberately NOT added here:
      * post()/put()/delete() already self-enforce per-agent ownership inline
      * (resolveAgentAuth + explicit agentId checks in post()/put(), and the
-     * isAdmin durability check in delete()). Adding allow* on top of that,
+     * stored-owner check in delete()). Adding allow* on top of that,
      * unverified, risks regressing owner writes/deletes on a P0 security fix
      * that is scoped to the read leak — left as-is on purpose.
      */
@@ -523,7 +557,9 @@ export class Memory extends databases.flair.Memory {
         // returned untouched (attachTrust returns the same reference) ⇒
         // byte-identical to pre-slice-1.
         if (result && typeof result === "object" && !(result instanceof Response) && typeof result.agentId === "string") {
-            return attachTrust(result, wantsTrust(target, opts));
+            const ctx = this.getContext?.();
+            const withHits = await applyHitStats(result, ctx);
+            return attachTrust(withHits, wantsTrust(target, opts));
         }
         return result;
     }
@@ -550,7 +586,7 @@ export class Memory extends databases.flair.Memory {
         if (gate.kind === "denied")
             return gate.response;
         if (gate.kind === "unfiltered")
-            return super.search(query);
+            return overlayHitStatsResult(super.search(query), ctx);
         // Non-admin agent: scope to own (any visibility) + granted owners' SHARED
         // memories only (Layer 1 private-exclusion). Centralized in
         // memoryReadScope (record-type-kit.ts's makeReadScope(), parameterized
@@ -562,9 +598,12 @@ export class Memory extends databases.flair.Memory {
         // makeScopedSearch (record-type-kit.ts) — same correct composition
         // MemoryCandidate.search() already applies — so a caller-supplied
         // `operator: "or"` cannot boolean-inject past the owner scope.
-        return memoryScopedSearch(gate.agentId, query, (q) => withDetachedTxn(ctx, () => super.search(q)));
+        return overlayHitStatsResult(memoryScopedSearch(gate.agentId, query, (q) => withDetachedTxn(ctx, () => super.search(q))), ctx);
     }
     async post(content, context) {
+        const authorityDenial = await guardAuthorityFields(() => super.get(), content, "Memory");
+        if (authorityDenial)
+            return authorityDenial;
         // Rate limiting — use authenticated agent ID, not client-supplied body field
         const ctx = this.getContext?.();
         const authenticatedAgent = ctx?.request?.tpsAgent;
@@ -619,6 +658,18 @@ export class Memory extends databases.flair.Memory {
             }
         }
         content.durability ||= "standard";
+        // ── flair#1542: skills are forced durability=persistent ──
+        // A skill-tagged write must never be reaped by the 30-day reaper (the
+        // "standard" default) nor expire (ephemeral/session). enforceSkillDurability
+        // rejects ephemeral/session outright and forces every other value to
+        // "persistent" — placed AFTER the default so it sees the effective tier,
+        // and BEFORE the visibility default below so a skill lands on the
+        // persistent→shared branch, not the standard→private one.
+        {
+            const skillDurabilityDenial = enforceSkillDurability(content);
+            if (skillDurabilityDenial)
+                return skillDurabilityDenial;
+        }
         // ── flair#1336: honor a caller-supplied createdAt (parity with put()) ──
         // put() — the other HTTP-reachable create path — has always preserved the
         // caller's createdAt (`content.createdAt ?? now`), and adk-flair's
@@ -637,8 +688,8 @@ export class Memory extends databases.flair.Memory {
         content.updatedAt = nowIso;
         content.archived = content.archived ?? false;
         // ─── Default visibility (durability-keyed) — Layer 1, part A ────────────
-        // post() only ever creates a NEW record — patchRecord/supersede-close/
-        // retrievalCount bumps all route through put() instead (see put()'s
+        // post() only ever creates a NEW record — patchRecord/supersede-close
+        // route through put() instead (see put()'s
         // pre-existing-record guard below), so there is no "don't overwrite an
         // existing record's visibility" concern here. Explicit visibility on the
         // write ALWAYS overrides; only stamp the default when the caller left it
@@ -730,6 +781,16 @@ export class Memory extends databases.flair.Memory {
                 content._safetyFlags = safety.flags;
             }
         }
+        // ── flair#1542: SkillScan gate BEFORE the embed ──
+        // Every skill-tagged write is statically scanned (shell/network/fs/env/
+        // encoding/unicode) BEFORE any embedding is computed, so a rejected write
+        // pays no embed. Fail-closed on high/critical; allow-with-flag on medium.
+        // Non-skill writes are a no-op (skillScanGate returns null).
+        {
+            const skillScanDenial = skillScanGate(content);
+            if (skillScanDenial)
+                return skillScanDenial;
+        }
         // Server-side conservative-duplicate gate (memory-integrity fix). A
         // supersede write is an intentional version-link, not an ambiguous "is
         // this a duplicate of something else" situation — bypass the gate for it
@@ -747,9 +808,11 @@ export class Memory extends databases.flair.Memory {
         // Generate embedding from content text (no-op if the dedup gate above
         // already computed one for this content). flair#504 Phase 2: 'document'
         // — see runDedupGate's comment above for why all three Memory doc sites
-        // must move together.
-        if (content.content && !content.embedding) {
-            const vec = await getEmbedding(content.content, "document");
+        // must move together. flair#1542: skill-tagged rows embed from `trigger`
+        // (skillEmbedText), not `content`.
+        const embedText = skillEmbedText(content);
+        if (embedText && !content.embedding) {
+            const vec = await getEmbedding(embedText, "document");
             if (vec) {
                 content.embedding = vec;
                 content.embeddingModel = getModelId();
@@ -776,6 +839,11 @@ export class Memory extends databases.flair.Memory {
         // synchronous hook is what makes a store immediately searchable rather
         // than searchable-after-the-feed-turns.
         noteMemoryUpsert(content);
+        // embedding-space-guard slice 1: keep the write-maintained latch current —
+        // a persisted FOREIGN stamp (federation / replication / an explicit-stamp
+        // write) trips the gate; a normal local write stamps the current id and
+        // never does.
+        noteWriteStamp(content?.embeddingModel);
         // ── THEN close the superseded record ────────────────────────────────────
         // Write-new-BEFORE-close-old: the previous order (close-old via a fire-
         // and-forget `.catch(()=>{})` BEFORE the new write) could tombstone the
@@ -799,7 +867,43 @@ export class Memory extends databases.flair.Memory {
         }
         return buildWriteResponse(content, result, dedupMatch);
     }
+    // PATCH routes past put(), so agentId immutability is enforced on both verbs
+    // via the one shared delegate. (Admin/internal — including the _reindex
+    // path in put() — pass through the delegate untouched.)
+    async patch(content, query) {
+        const authorityDenial = await guardAuthorityFields(() => super.get(), content, "Memory");
+        if (authorityDenial)
+            return authorityDenial;
+        const denial = await guardOwnerFieldImmutable(this, () => super.get(), content, "agentId");
+        if (denial)
+            return denial;
+        // ── flair#1542 + residual (Kern #1543 review 5135715289): reject skill patches ──
+        // patch() routes past put() (and thus past the SkillScan gate + forced
+        // durability), so a skill write on this verb would land unscanned. There are
+        // TWO ways a patch is a skill write, and the mint-time check saw only the first:
+        //   1. the PATCH BODY carries the skill tag — rejectSkillWritePath(content).
+        //   2. the STORED record is ALREADY a skill, and the body mutates `content`
+        //      (or anything else) WITHOUT re-declaring the tag. isSkillWrite(body) is
+        //      then false, so the pre-residual check let the edit land — a skill's
+        //      procedure could be rewritten with NO SkillScan (the residual). Fold
+        //      the existing record into the check: a patch to a row whose STORED tags
+        //      include `skill` is rejected the same as a mint-time skill write.
+        // Skills are written via skill_store (→ Memory.post) or Memory.put; no
+        // memory_patch tool exists and no internal path patches a skill row (hit-
+        // tracking goes through table.put, not this override), so rejecting is safe.
+        const existingForSkill = (await Promise.resolve(super.get()).catch(() => null));
+        const skillDenial = rejectSkillWritePath(content) ?? rejectSkillWritePath(existingForSkill);
+        if (skillDenial)
+            return skillDenial;
+        return super.patch(content, query);
+    }
     async put(content) {
+        const authorityDenial = await guardAuthorityFields(() => super.get(), content, "Memory");
+        if (authorityDenial)
+            return authorityDenial;
+        const __ownerDenial = await guardOwnerFieldImmutable(this, () => super.get(), content, "agentId");
+        if (__ownerDenial)
+            return __ownerDenial;
         // Reindex migration bypass: admin-only escape hatch used by the
         // MemoryReindex admin endpoint to re-PUT each existing record byte-for-byte
         // (no updatedAt bump, no embedding regen, no safety rescan) so Harper
@@ -819,6 +923,7 @@ export class Memory extends databases.flair.Memory {
             delete content._reindex;
             const reindexed = await super.put(content);
             noteMemoryUpsert(content);
+            noteWriteStamp(content?.embeddingModel); // embedding-space-guard slice 1 (see post())
             return reindexed;
         }
         // Create/update ownership (same rule as post): a non-admin agent may only
@@ -858,6 +963,16 @@ export class Memory extends databases.flair.Memory {
                 return new Response(JSON.stringify({ error: "invalid_durability", message: durabilityError }), { status: 400, headers: { "content-type": "application/json" } });
             }
         }
+        // ── flair#1542: skills are forced durability=persistent (mirrors post()) ──
+        // put() stamps no durability default (updates carry the pre-existing tier),
+        // so this runs on the raw write value: a skill-tagged write with an explicit
+        // ephemeral/session tier is rejected, and every other value (including an
+        // absent one) is forced to "persistent" so the reaper never archives a skill.
+        {
+            const skillDurabilityDenial = enforceSkillDurability(content);
+            if (skillDurabilityDenial)
+                return skillDurabilityDenial;
+        }
         const now = new Date().toISOString();
         content.updatedAt = now;
         // Set defaults that post() sets — put() is also used for new records via CLI
@@ -869,7 +984,7 @@ export class Memory extends databases.flair.Memory {
         // untouched). See the dedup-gate block further down for why an existing
         // id skips the gate; the SAME "does a record already exist" check gates
         // the visibility default (Layer 1 part A): patchRecord/supersede-
-        // close/retrievalCount bumps all route through put() with a MERGED
+        // close all route through put() with a MERGED
         // `{...existing, ...patch}` payload, and must never have their stored
         // visibility overwritten by a default recomputed from that merged content
         // — only a genuinely NEW id gets the default stamped.
@@ -973,6 +1088,15 @@ export class Memory extends databases.flair.Memory {
                 content._safetyFlags = null;
             }
         }
+        // ── flair#1542: SkillScan gate BEFORE the embed (mirrors post()) ──
+        // Every skill-tagged write is statically scanned before any embedding is
+        // computed, so a rejected write pays no embed. Fail-closed on high/critical;
+        // allow-with-flag on medium. Non-skill writes are a no-op.
+        {
+            const skillScanDenial = skillScanGate(content);
+            if (skillScanDenial)
+                return skillScanDenial;
+        }
         // Server-side conservative-duplicate gate (memory-integrity fix). PUT is
         // an upsert: only run the gate for a FRESH create (target id does not yet
         // exist) that is NOT a supersede-link write. An update of an EXISTING id
@@ -1004,9 +1128,11 @@ export class Memory extends databases.flair.Memory {
         // already computed one for this content). flair#504 Phase 2: 'document'
         // — this is also the regen branch `flair reembed` triggers (clears
         // embedding/embeddingModel then hits this put()), so it's what actually
-        // re-embeds a stale row WITH the prefix once stage 2 runs.
-        if (content.content && !content.embedding) {
-            const vec = await getEmbedding(content.content, "document");
+        // re-embeds a stale row WITH the prefix once stage 2 runs. flair#1542:
+        // skill-tagged rows embed from `trigger` (skillEmbedText), not `content`.
+        const embedText = skillEmbedText(content);
+        if (embedText && !content.embedding) {
+            const vec = await getEmbedding(embedText, "document");
             if (vec) {
                 content.embedding = vec;
                 content.embeddingModel = getModelId();
@@ -1017,24 +1143,6 @@ export class Memory extends databases.flair.Memory {
             content.archivedAt = now;
             // archivedBy should be set by the caller (CLI stamps req.tpsAgent via query param)
         }
-        // If approving promotion, record timestamp
-        if (content.promotionStatus === "approved" && !content.promotedAt) {
-            content.promotedAt = now;
-        }
-        // Upgrade to permanent when approved — the LEGACY in-place approval flow
-        // (an admin marks an EXISTING row approved without naming a tier; the
-        // auth-middleware admin-gates setting promotionStatus over HTTP). An
-        // explicit durability on the SAME write now wins (flair#1257 slice 3):
-        // the candidate-promotion paths (#1205b-2 /AutoPromoteCandidates and the
-        // human `flair rem promote`) write NEW rows carrying promotionStatus:
-        // "approved" purely as an audit stamp ALONGSIDE an explicit durability:
-        // "persistent" — the unconditional coercion here silently lifted every
-        // promoted claim into the never-reaped permanent tier while every audit
-        // surface (CLI output, specs, review rulings) said persistent. A write
-        // that names its tier keeps it; only a tier-less approval still upgrades.
-        if (content.promotionStatus === "approved" && (content.durability === undefined || content.durability === null)) {
-            content.durability = "permanent";
-        }
         // Write-time provenance stamp (memory-provenance slice 1) — see
         // buildProvenance's doc above post(). Applies to every put() (fresh
         // create AND update/patch) — never gated on preExisting, so an update
@@ -1057,6 +1165,7 @@ export class Memory extends databases.flair.Memory {
         const result = await super.put(content);
         // flair#1357 — read-your-write for the lexical leg (see post()).
         noteMemoryUpsert(content);
+        noteWriteStamp(content?.embeddingModel); // embedding-space-guard slice 1 (see post())
         // ── THEN close the superseded record (see post()) ───────────────────────
         await closeSupersededIfNeeded(ctx, content, "put");
         // flair#744 slice A: citation-on-write — POST-COMMIT, fully
@@ -1072,34 +1181,23 @@ export class Memory extends databases.flair.Memory {
         return buildWriteResponse(content, result, dedupMatch);
     }
     async delete(id) {
-        // Use super.get(id), NOT this.get(id): the new get() override above 404s
-        // (a truthy Response) for a non-owner/non-granted id, which would
-        // otherwise short-circuit the `record.durability === "permanent"` check
-        // below (a Response has no .durability) and silently bypass the
-        // admin-only permanent-delete guard for cross-agent deletes. This keeps
-        // delete()'s own pre-existing ownership/admin logic exactly as it was
-        // before the read-gate fix — the read-scoping override must not leak
-        // into delete()'s internal record lookup.
+        const auth = await resolveAgentAuth(this.getContext?.());
+        if (auth.kind === "anonymous")
+            return UNAUTH();
+        // Read stored ownership, not the read-scoped get() response. Enforce here
+        // as well as middleware so MCP/in-process callers have the same policy.
         const record = await super.get(id);
-        if (!record) {
-            const gone = await super.delete(id);
-            noteMemoryDelete(id);
-            return gone;
-        }
-        if (record.durability === "permanent") {
-            // Middleware already guards this for non-admins, but belt-and-suspenders
-            const ctx = this.getContext?.();
-            const request = ctx?.request ?? ctx;
-            const actorId = request?.tpsAgent;
-            if (actorId && !(await isAdmin(actorId))) {
-                return new Response(JSON.stringify({ error: "permanent_memory_cannot_be_deleted_by_non_admin" }), {
-                    status: 403,
-                    headers: { "Content-Type": "application/json" },
-                });
-            }
+        if (auth.kind === "agent" && !auth.isAdmin &&
+            isForbiddenOwnerMutation(record, RECORD_TYPES.Memory.ownerField, auth.agentId)) {
+            return FORBIDDEN("forbidden: cannot delete memory owned by another agent");
         }
+        // Durability controls retention, not the owner's authority to delete.
         const deleted = await super.delete(id);
         noteMemoryDelete(id);
+        const deletedId = typeof id === "string" ? id : record?.id;
+        if (typeof deletedId === "string" && deletedId.length > 0) {
+            await clearHitStats(deletedId, this.getContext?.()).catch(() => { });
+        }
         return deleted;
     }
 }

package/dist/resources/MemoryBootstrap.js

@@ -79,7 +79,7 @@ import { estimateTokens } from "./token-estimate.js";
  *     memoriesTruncated, teammateFindingsIncluded, teammateFindingsTruncated,
  *     teammateFindingsMatched, agentId, scope, soul, memories, predicted,
  *     teammateFindings, events, soulTokens, memoryTokens, trustTokens,
- *     eventsTokens, scaffoldTokens[, currentTaskHint][, predictedHint] }
+ *     eventsTokens, scaffoldTokens[, currentTaskHint][, taskRetrievalHint][, predictedHint] }
  *
  *   TOKEN LEDGER (flair#1270): the counters decompose `tokenEstimate` from the
  *   payload alone —
@@ -282,7 +282,7 @@ export class BootstrapMemories extends Resource {
         return allowVerified(this.getContext?.());
     }
     async post(data, _context) {
-        const { agentId: bodyAgentId, currentTask, maxTokens = 4000, includeSoul = true, since, channel, // e.g., "discord", "tps-mail", "claude-code"
+        const { agentId: bodyAgentId, currentTask: rawCurrentTask, maxTokens = 4000, includeSoul = true, since, channel, // e.g., "discord", "tps-mail", "claude-code"
         surface, // e.g., "tps-build", "tps-review", "cli-session"
         subjects, // e.g., ["flair", "auth"] — entities to preload context for
         includeTrust = false, // flair#744 slice 1 — opt-in per-memory trust block
@@ -306,6 +306,7 @@ export class BootstrapMemories extends Resource {
         // bodies twice. When false, `context` is a compact structural pointer (no
         // bodies), so nothing crosses the wire twice on that path.
         includeContext = true, } = data || {};
+        const currentTask = typeof rawCurrentTask === "string" ? rawCurrentTask.trim() : "";
         // Authenticated identity lives on getContext().request — `this.request` is
         // NOT populated on Harper v5 Resources. Reading it returned undefined and
         // the scope check was silently bypassed, letting a non-admin agent read
@@ -685,7 +686,14 @@ export class BootstrapMemories extends Resource {
         // any memory cover your current task", not the whole session load). Stays
         // null when there's no currentTask / no embedding ⇒ never abstains.
         let taskBestSimilarity = null;
-        // --- 2. Permanent memories (always included, highest priority) ---
+        // Protect task recall from pinned/recent admission. Soul keeps its existing
+        // priority; unused task space is returned to permanent memories below.
+        const taskReserve = currentTask
+            ? Math.max(0, Math.min(tokenBudget, Math.floor(maxTokens * 0.3)))
+            : 0;
+        tokenBudget -= taskReserve;
+        let taskRetrievalHint;
+        // --- 2. Permanent memories ---
         // Own-scoped pushdown: `agentId==self` + `durability==permanent`, both
         // @indexed (a seek, not a scan) — strictly narrower than the prior
         // load-then-filter (own records are always visible to their own agent
@@ -731,7 +739,7 @@ export class BootstrapMemories extends Resource {
             if (m.supersedes)
                 permanentSupersededIds.add(m.supersedes);
         const permanent = permanentRows.filter((m) => !permanentSupersededIds.has(m.id));
-        for (const m of permanent) {
+        const admitPermanent = (m) => {
             const line = formatMemory(m, agentId);
             const struct = leanMemory(m, "permanent");
             // #1199 (0.44.11) — charge what SHIPS (structured on the /mcp path, prose
@@ -754,7 +762,9 @@ export class BootstrapMemories extends Resource {
             else {
                 truncatedOwnIds.add(m.id); // #1207 — budget-skip, deduped against inclusions at the end
             }
-        }
+        };
+        for (const m of permanent)
+            admitPermanent(m);
         // --- 3. Recent memories (adaptive window) ---
         // Own-scoped, non-permanent, bounded + createdAt-desc pushdown (agentId
         // and durability are both @indexed) — replaces the org-wide load's
@@ -925,7 +935,10 @@ export class BootstrapMemories extends Resource {
         // cross-agent hits.
         const semanticTeammateMatches = [];
         // --- 4. Task-relevant memories (semantic search) ---
-        if (currentTask && tokenBudget > 200) {
+        tokenBudget += taskReserve;
+        if (currentTask && tokenBudget <= 0)
+            taskRetrievalHint = "Task retrieval skipped: no content budget remains.";
+        if (currentTask && tokenBudget > 0) {
             let queryEmbedding = null;
             try {
                 // flair#504 Phase 2: 'query' — currentTask is the bootstrap's
@@ -933,6 +946,8 @@ export class BootstrapMemories extends Resource {
                 queryEmbedding = await getEmbedding(currentTask, "query");
             }
             catch { }
+            if (!queryEmbedding)
+                taskRetrievalHint = "Task retrieval skipped: query embedding unavailable.";
             if (queryEmbedding) {
                 // flair#1207 — exclude own memories ALREADY placed via the authoritative
                 // set (permanent + recent + predicted actually admitted). The old set was
@@ -1033,6 +1048,8 @@ export class BootstrapMemories extends Resource {
                 // (+ legacy keyword bump) per #985/#1267 — for display/reporting;
                 // ORDER and score can legitimately disagree (a BM25 rank-1 rescue
                 // outranks higher-cosine bland hits, which is the recall win).
+                if (candidates.length === 0)
+                    taskRetrievalHint = "Task retrieval found no visible active candidates.";
                 const scored = candidates
                     .filter((m) => !includedIds.has(m.id))
                     .map((m) => ({ memory: m, score: m._score }));
@@ -1130,6 +1147,15 @@ export class BootstrapMemories extends Resource {
                 }
             }
         }
+        if (currentTask) {
+            if (!taskRetrievalHint && sections.relevant.length + sections.teammate.length === 0) {
+                taskRetrievalHint = "Task candidates were already included or did not fit the remaining content budget.";
+            }
+            for (const m of permanent) {
+                if (!includedOwnIds.has(m.id))
+                    admitPermanent(m);
+            }
+        }
         // --- 4c. Collision surfacing (flair#681 — "others in the room") ---
         // Joins two independently-scoped surfaces into a single ranked list:
         //   - Entity overlap (WorkspaceState + OrgEvent): exact vocabulary-string
@@ -1157,21 +1183,30 @@ export class BootstrapMemories extends Resource {
                 ? data.entities.filter((e) => isValidEntity(e))
                 : [];
             if (callerEntities.length === 0) {
-                const ownRows = withDetachedTxn(ctx, () => databases.flair.WorkspaceState.search({
-                    conditions: [{ attribute: "agentId", comparator: "equals", value: agentId }],
-                    select: ["entities", "timestamp"],
-                }));
-                let latestEntities = [];
-                let latestTs = "";
-                for await (const row of ownRows) {
-                    if (!Array.isArray(row.entities) || row.entities.length === 0)
-                        continue;
-                    if ((row.timestamp || "") > latestTs) {
-                        latestTs = row.timestamp || "";
-                        latestEntities = row.entities;
+                // Try the indexed collision window before older workspace history;
+                // empty rows must not hide an older entity-bearing row.
+                // Only fall back to older history when the recent window has none.
+                const workspaceSince = new Date(Date.now() - COLLISION_WINDOW_DAYS * 24 * 3600_000).toISOString();
+                for (const comparator of ["greater_than_equal", "less_than"]) {
+                    const ownRows = withDetachedTxn(ctx, () => databases.flair.WorkspaceState.search({
+                        conditions: [
+                            { attribute: "agentId", comparator: "equals", value: agentId },
+                            { attribute: "timestamp", comparator, value: workspaceSince },
+                        ],
+                        select: ["entities", "timestamp"],
+                    }));
+                    let latestTs = "";
+                    for await (const row of ownRows) {
+                        if (!Array.isArray(row.entities) || row.entities.length === 0)
+                            continue;
+                        if ((row.timestamp || "") > latestTs) {
+                            latestTs = row.timestamp || "";
+                            callerEntities = row.entities;
+                        }
                     }
+                    if (callerEntities.length > 0)
+                        break;
                 }
-                callerEntities = latestEntities;
             }
             const entityMatches = [];
             if (callerEntities.length > 0) {
@@ -1265,7 +1300,14 @@ export class BootstrapMemories extends Resource {
                 : new Date(Date.now() - 24 * 3600_000);
             const eventSinceStr = eventSince.toISOString();
             const eventResults = [];
-            for await (const event of databases.flair.OrgEvent.search()) {
+            // Seek the indexed lookback window before materializing events. Keep detail
+            // for no-op suppression/dedup even when the response omits it. No limit here:
+            // expiry, targeting, dedup and budget admission must run before the cap.
+            const recentEvents = withDetachedTxn(ctx, () => databases.flair.OrgEvent.search({
+                conditions: [{ attribute: "createdAt", comparator: "greater_than_equal", value: eventSinceStr }],
+                select: ["id", "kind", "summary", "detail", "targetIds", "createdAt", "expiresAt", "scope"],
+            }));
+            for await (const event of recentEvents) {
                 if (!event.createdAt || event.createdAt < eventSinceStr)
                     continue;
                 if (event.expiresAt && new Date(event.expiresAt) < new Date())
@@ -1599,6 +1641,7 @@ export class BootstrapMemories extends Resource {
             // own soul/memories/predicted as structured containers (empty `{}`/`[]`,
             // never absent, so "empty" is distinguishable from "unsupported").
             agentId,
+            ...(taskRetrievalHint ? { taskRetrievalHint } : {}),
             scope: scopeInfo,
             soul: soulMap,
             memories: includedOwnMemories,

package/dist/resources/MemoryCandidate.js

@@ -1,5 +1,6 @@
 import { databases } from "harper";
 import { resolveAgentAuth } from "./agent-auth.js";
+import { guardOwnerFieldImmutable } from "./owner-field-guard.js";
 import { makeAuthGate, makeReadScope, makeByIdReadGate, resolveAuthGate, stampAttribution, FORBIDDEN, UNAUTH, } from "./record-type-kit.js";
 import { RECORD_TYPES } from "./record-types.js";
 // Parameterized from RECORD_TYPES.MemoryCandidate (record-types slice 2,
@@ -134,7 +135,18 @@ export class MemoryCandidate extends databases.flair.MemoryCandidate {
      * agent's candidate) but never stamps one in — the promote/reject flow
      * always carries the original agentId forward untouched.
      */
+    // PATCH routes past put(), so agentId immutability is enforced on both verbs
+    // via the one shared delegate.
+    async patch(content, query) {
+        const denial = await guardOwnerFieldImmutable(this, () => super.get(), content, "agentId");
+        if (denial)
+            return denial;
+        return super.patch(content, query);
+    }
     async put(content) {
+        const __ownerDenial = await guardOwnerFieldImmutable(this, () => super.get(), content, "agentId");
+        if (__ownerDenial)
+            return __ownerDenial;
         const ctx = this.getContext?.();
         const auth = await resolveAgentAuth(ctx);
         if (auth.kind === "anonymous")

package/dist/resources/MemoryConsolidate.js

@@ -18,6 +18,7 @@
 import { Resource, databases } from "harper";
 import { isAdmin, allowVerified } from "./agent-auth.js";
 import { evaluate, parseDuration } from "./memory-consolidate-lib.js";
+import { applyHitStats } from "./hit-tracking.js";
 export class ConsolidateMemories extends Resource {
     // Self-authorize via the Ed25519 agent verify (auth reshape removes the gate's
     // admin elevation). Any verified agent may consolidate; the isAdmin checks in
@@ -56,7 +57,7 @@ export class ConsolidateMemories extends Resource {
                 continue;
             if (scope === "standard" && record.durability !== "standard")
                 continue;
-            const candidate = evaluate(record, now, olderThanMs);
+            const candidate = evaluate(await applyHitStats(record, ctx), now, olderThanMs);
             candidates.push(candidate);
             if (candidates.length >= limit * 3)
                 break; // over-fetch to sort