@tpsdev-ai/flair 0.44.10 → 0.44.12

package/dist/cli.js

@@ -7918,6 +7918,11 @@ remNightly
         if (row.candidates) {
             console.log(`Staged:     ${row.candidates.length} candidate${row.candidates.length === 1 ? "" : "s"}`);
         }
+        // row.autoPromoted populates when step 5b (#1205b-2 ADK auto-promote) ran
+        // this cycle — i.e. a non-dry-run cycle for an ADK agentId.
+        if (row.autoPromoted) {
+            console.log(`Auto-promoted: ${row.autoPromoted.promoted} to own memory (${row.autoPromoted.skipped} left pending)`);
+        }
         // row.dedup populates when step 6 (instance-wide dedup-cluster stat,
         // flair-quality Slice 1c) succeeded this cycle. Absent on dry-run skip
         // or a non-fatal failure (see Errors below — e.g. non-admin caller).

package/dist/rem/runner.js

@@ -86,6 +86,17 @@ export const DEFAULT_DISTILL_LOOKBACK_MS = 48 * 3600_000;
  * recorded in `errors` and picked up on subsequent cycles (they stay active).
  */
 export const DEFAULT_MAX_TAGS_PER_CYCLE = 200;
+/**
+ * Per-cycle ceiling on ADK candidate auto-promotions (#1205b-2). The nightly
+ * cycle sweeps this agent's pending, scopeTag-bearing candidates and promotes
+ * the eligible ones to own memory server-side (POST /AutoPromoteCandidates).
+ * This bounds the blast radius of one cycle (Kern's cost-ceiling note); the
+ * resource applies the same cap, and any overflow stays `pending` for a later
+ * cycle. Mirror of resources/auto-promote-lib.ts's DEFAULT_MAX_AUTO_PROMOTE_
+ * PER_CYCLE, duplicated across the npm-packaging boundary (src/ can't import
+ * resources/ — see src/cli.ts) and kept in sync by value.
+ */
+export const DEFAULT_MAX_AUTO_PROMOTE_PER_CYCLE = 200;
 function readPauseSentinel(path) {
     try {
         const contents = readFileSync(path, "utf-8");
@@ -351,6 +362,9 @@ export async function runNightlyCycle(opts) {
     // exactly as before. The single-node-runs-the-timer property is unchanged:
     // this all runs inside the one cycle on the one node.
     let candidates;
+    // #1205b-2: outcome of the post-distillation auto-promote step, assigned
+    // inside the !dryRun block below (only when this is an ADK agentId).
+    let autoPromoted;
     const collectStagedIds = (obj) => asArray(obj.candidates)
         .map((c) => (c && typeof c === "object" ? c.id : c))
         .filter((id) => typeof id === "string");
@@ -424,6 +438,35 @@ export async function runNightlyCycle(opts) {
                 errors.push(`distillation: ${describeApiError(err?.message ?? err)}`);
             }
         }
+        // ── Step 5b (#1205b-2): server-side ADK auto-promote ───────────────────────
+        // Only for an ADK agentId (active adk: tags this cycle) — a non-ADK agent
+        // has no scopeTag-bearing candidates, so there is nothing to auto-promote
+        // and no call is made. The SERVER enforces every security invariant
+        // (memory-only target, fail-closed tag lineage, content-safety, machine
+        // reviewerId) — the runner only TRIGGERS the sweep; it never itself decides
+        // where a claim lands. Non-fatal like distillation: a failure is recorded
+        // and the candidates stay pending (re-swept next cycle, or promotable by the
+        // human `rem promote` path). Bounded by the per-cycle cap.
+        if (activeAdkTags.length > 0) {
+            try {
+                const apRaw = await opts.apiCall("POST", "/AutoPromoteCandidates", {
+                    agentId: opts.agentId,
+                    limit: opts.maxAutoPromotePerCycle ?? DEFAULT_MAX_AUTO_PROMOTE_PER_CYCLE,
+                });
+                const obj = (apRaw && typeof apRaw === "object") ? apRaw : {};
+                if (obj.error) {
+                    errors.push(`auto-promote: ${describeApiError(obj.error)}`);
+                }
+                else {
+                    const promotedCount = typeof obj.count === "number" ? obj.count : asArray(obj.promoted).length;
+                    const skippedCount = asArray(obj.skipped).length;
+                    autoPromoted = { promoted: promotedCount, skipped: skippedCount };
+                }
+            }
+            catch (err) {
+                errors.push(`auto-promote: ${describeApiError(err?.message ?? err)}`);
+            }
+        }
     }
     // Step 6 (flair-quality Slice 1c): instance-wide dedup-cluster stat.
     // Distinct from every step above — NOT scoped to opts.agentId. Runs ONCE
@@ -481,6 +524,7 @@ export async function runNightlyCycle(opts) {
         archived,
         expired,
         candidates,
+        autoPromoted,
         dedup,
         durationMs: Date.now() - startedMs,
         errors,

package/dist/resources/AutoPromoteCandidates.js

@@ -0,0 +1,203 @@
+/**
+ * POST /AutoPromoteCandidates  (#1205b-2 — the UNATTENDED promotion path)
+ *
+ * Sweeps this agent's PENDING, ADK-sourced (scopeTag-bearing) MemoryCandidates
+ * and auto-promotes each eligible one to the agent's OWN persistent Memory — no
+ * human reviewer, replacing `flair rem promote` for this one narrow path. Wired
+ * into the nightly runner (src/rem/runner.ts) as a post-distillation step.
+ *
+ * This is the SERVER-SIDE trust-tier enforcement cli.ts noted as deferred. The
+ * whole reason it is a resource and not a CLI flag is Sherlock's req 1: the
+ * "never Soul" invariant must live where a compromised agent key cannot flip it.
+ *
+ *   Req 1 — memory-only, enforced HERE, structurally. There is NO soul code
+ *     path in this resource: the only write it can perform is a Memory write.
+ *     Soul is agentId-scoped and cannot carry a per-user `adk:<app>:<user>` tag,
+ *     so an ADK-sourced → Soul promotion is cross-user BY CONSTRUCTION. On top
+ *     of the structural absence, an explicit `target` in the request body that
+ *     is anything other than "memory" is REFUSED loudly (400) rather than
+ *     silently ignored — so a caller trying to flip the target gets a hard no.
+ *   Req 2 — fail-closed tag lineage: decideAutoPromote (auto-promote-lib.ts)
+ *     refuses any candidate without an authoritative `adk:` stamped scopeTag,
+ *     and the promoted Memory carries that scopeTag as its first tag.
+ *   Req 3 — content-safety: decideAutoPromote scans the claim strict (always
+ *     refuses a flag, independent of FLAIR_CONTENT_SAFETY), and the Memory.put()
+ *     override below scans again on the write (defense-in-depth).
+ *   Req 4 — machine reviewerId: the promoted Memory's `promotedBy` and the
+ *     candidate row's `reviewerId` both record machine:adk-auto-promote.
+ *
+ * Request:
+ *   agentId  string?  — whose candidates to sweep. A non-admin caller may only
+ *                       sweep its OWN (resolveReflectActor); admin may name any.
+ *   limit    number?  — per-call cap (default DEFAULT_MAX_AUTO_PROMOTE_PER_CYCLE).
+ *   target   string?  — MUST be absent or "memory". Any other value is refused
+ *                       (the hard-lock made explicit + testable).
+ *
+ * Response:
+ *   { agentId, promoted: string[], skipped: {id, reason}[], count, considered }
+ *
+ * Thin orchestrator over the pure, tested policy in ./auto-promote-lib.ts.
+ */
+import { Resource, databases, logger } from "harper";
+import { isAdmin, allowVerified } from "./agent-auth.js";
+import { resolveReflectActor } from "./memory-reflect-lib.js";
+import { agentContext } from "./in-process.js";
+import { decideAutoPromote, buildAutoPromotedTags, DEFAULT_MAX_AUTO_PROMOTE_PER_CYCLE, } from "./auto-promote-lib.js";
+export class AutoPromoteCandidates extends Resource {
+    // Any verified agent may trigger a sweep of ITS OWN candidates; the actor
+    // resolution in post() enforces the own-only scope. Same gate ReflectMemories
+    // uses (allowVerified — verified agents, admins, trusted internal calls).
+    async allowCreate() {
+        return allowVerified(this.getContext?.());
+    }
+    async post(data) {
+        const { agentId: bodyAgentId, limit, target } = data || {};
+        // ── Req 1: target hard-lock, made explicit ────────────────────────────────
+        // This resource NEVER writes Soul — there is no soul branch anywhere below.
+        // An explicit non-memory `target` in the body is refused loudly so a caller
+        // (or a compromised agent key) attempting to flip the target gets a hard no,
+        // not a silent memory write it did not ask for.
+        if (target !== undefined && target !== "memory") {
+            return new Response(JSON.stringify({
+                error: "auto_promote_target_locked",
+                message: "auto-promote is hard-locked to memory server-side; soul (or any non-memory target) is refused — an ADK-sourced promotion to Soul would leak across users",
+            }), { status: 400, headers: { "Content-Type": "application/json" } });
+        }
+        // ── Identity / actor resolution (own candidates only, unless admin) ────────
+        const ctx = this.getContext?.();
+        const request = ctx?.request ?? ctx;
+        const actorId = request?.tpsAgent;
+        const callerIsAdmin = request?.tpsAgentIsAdmin === true || (actorId ? await isAdmin(actorId) : false);
+        const actorResolution = resolveReflectActor({ bodyAgentId, actorId, callerIsAdmin });
+        if (actorResolution.error) {
+            return new Response(JSON.stringify(actorResolution.error.body), { status: actorResolution.error.status });
+        }
+        const agentId = actorResolution.agentId;
+        const cap = typeof limit === "number" && Number.isFinite(limit) && limit > 0
+            ? Math.floor(limit)
+            : DEFAULT_MAX_AUTO_PROMOTE_PER_CYCLE;
+        // ── Sweep this agent's pending candidates ──────────────────────────────────
+        // Owner-scoped in JS by `c.agentId !== agentId` (the raw table search is
+        // org-wide — same discipline ReflectMemories uses), so a non-admin actor can
+        // only ever sweep its own candidates: no cross-agent promotion, no oracle.
+        //
+        // decideAutoPromote (auto-promote-lib.ts) is the SINGLE fail-closed gate:
+        // it — not this loop — decides eligibility (ADK scope tag present + content
+        // safe). The `status !== "pending"` skip here is a pure enumeration
+        // optimization (don't build a skip record for every historical decided row);
+        // decideAutoPromote re-checks status authoritatively. The `cap` bounds the
+        // number PROMOTED (the expensive part — a Memory write + embedding each),
+        // Kern's cost ceiling; overflow stays pending for a later cycle.
+        const MemoryCls = (await import("./Memory.js")).Memory;
+        const promoted = [];
+        const skipped = [];
+        let considered = 0;
+        // Bounded enumeration (Sherlock non-blocking + Kern's cost ceiling): filter
+        // to THIS agent's PENDING candidates in the DB query so a large backlog of
+        // other-status / other-agent rows is never scanned each cycle. The JS
+        // agentId/status re-checks below stay as FAIL-CLOSED defense-in-depth — the
+        // owner-scope guarantee does not rely on the query alone.
+        const candidateQuery = {
+            operator: "and",
+            conditions: [
+                { attribute: "agentId", comparator: "equals", value: agentId },
+                { attribute: "status", comparator: "equals", value: "pending" },
+            ],
+        };
+        for await (const c of databases.flair.MemoryCandidate.search(candidateQuery)) {
+            if (!c || typeof c !== "object")
+                continue;
+            if (c.agentId !== agentId)
+                continue; // owner scope (no cross-agent) — defense-in-depth
+            if (c.status !== "pending")
+                continue; // defense-in-depth
+            considered++;
+            const decision = decideAutoPromote(c);
+            if (!decision.promote) {
+                skipped.push({ id: c.id, reason: decision.reason });
+                continue;
+            }
+            const decidedAt = new Date().toISOString();
+            const memId = `${agentId}-promoted-${Date.now()}-${promoted.length}`;
+            const memRow = {
+                id: memId,
+                agentId,
+                content: c.claim,
+                durability: "persistent",
+                // ── visibility: PRIVATE, explicit (Sherlock cross-agent leak fix) ──────
+                // MUST be set. Memory.put() defaults an unset visibility from durability
+                // (Memory.ts) and "persistent" defaults to "shared" — and "shared" is
+                // ORG-OPEN (memory-read-scope.ts): readable by EVERY verified agent on
+                // the instance. The source episodes are the user's PRIVATE session data
+                // (durability:"standard" → default private), and the per-user boundary
+                // is adk-flair's CLIENT-SIDE tag re-verification, which OTHER agents do
+                // NOT run. So a shared auto-promoted claim would leak a user's distilled
+                // private data to every agent on the box — unattended. "private" is
+                // owner-only, so the claim is reachable ONLY through the app agent's own
+                // tag-filtered search (which re-verifies the tag) and is invisible to
+                // every other agent. This keeps the blast radius inside the one agentId,
+                // which is the entire #1205 safety argument.
+                visibility: "private",
+                // scopeTag FIRST — the per-user access-control boundary (Req 2).
+                tags: buildAutoPromotedTags(c.id, decision.scopeTag),
+                derivedFrom: Array.isArray(c.sourceMemoryIds) ? c.sourceMemoryIds : [],
+                promotionStatus: "approved",
+                promotedAt: decidedAt,
+                // Req 4 — non-impersonating machine reviewerId.
+                promotedBy: decision.reviewerId,
+                createdAt: decidedAt,
+            };
+            // ── The write — MEMORY ONLY ────────────────────────────────────────────
+            // Static Cls.put(row, context) routes THROUGH Memory.put()'s override
+            // (Req 3 content-safety scan on the write + embedding + provenance +
+            // per-agent ownership), acting as the agent itself (agentContext). There
+            // is deliberately no Soul equivalent here (Req 1). decideAutoPromote has
+            // already refused any content-flagged claim strict, so a normal claim
+            // sails through; a Memory.put refusal (e.g. instance-wide strict mode) is
+            // treated as a skip and the candidate is left pending — never a lost claim.
+            let writeRes;
+            try {
+                writeRes = await MemoryCls.put(memRow, agentContext(agentId));
+            }
+            catch (err) {
+                logger.warn?.(`AutoPromoteCandidates: Memory write threw for candidate ${c.id}: ${err?.message ?? err}`);
+                skipped.push({ id: c.id, reason: "memory_write_error" });
+                continue;
+            }
+            if (writeRes instanceof Response && !writeRes.ok) {
+                skipped.push({ id: c.id, reason: `memory_write_rejected:${writeRes.status}` });
+                continue;
+            }
+            // ── Mark the candidate promoted (commit point) ─────────────────────────
+            // Ordered AFTER the Memory write, matching the human promote path: the
+            // safe failure state is a promoted Memory whose candidate is still pending
+            // (re-swept next cycle; the Memory dedup gate absorbs the duplicate),
+            // never a candidate marked promoted with no Memory behind it.
+            try {
+                await databases.flair.MemoryCandidate.put({
+                    ...c,
+                    status: "promoted",
+                    target: "memory",
+                    reviewerId: decision.reviewerId,
+                    reviewRationale: decision.rationale,
+                    decidedAt,
+                });
+            }
+            catch (err) {
+                logger.warn?.(`AutoPromoteCandidates: candidate row update failed for ${c.id} (Memory ${memId} written): ${err?.message ?? err}`);
+            }
+            promoted.push(memId);
+            // Cost ceiling (Kern): cap the number PROMOTED this cycle. Remaining
+            // eligible candidates stay pending and are swept on a later cycle.
+            if (promoted.length >= cap)
+                break;
+        }
+        return {
+            agentId,
+            promoted,
+            skipped,
+            count: promoted.length,
+            considered,
+        };
+    }
+}

package/dist/resources/Memory.js

@@ -7,6 +7,7 @@ import { scanFields, isStrictMode } from "./content-safety.js";
 import { invalidEntitiesResponse } from "./entity-vocab.js";
 import { checkRateLimit, rateLimitResponse } from "./rate-limiter.js";
 import { assertValidVisibility } from "./memory-visibility.js";
+import { assertValidDurability } from "./memory-durability.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";
@@ -599,6 +600,19 @@ export class Memory extends databases.flair.Memory {
         const usedMemoryIds = content?.usedMemoryIds;
         if (content && typeof content === "object")
             delete content.usedMemoryIds;
+        // ── flair#1238: refuse an unrecognised durability BEFORE defaulting ──
+        // defaultVisibilityForDurability treats any non-permanent/persistent string
+        // as the private branch, so an unknown durability via raw REST (or a future
+        // non-Python adapter) is silently accepted and lands on the narrower private
+        // branch by accident — fail-safe, but unvalidated by contract. Refusing at
+        // the schema boundary makes it safe by construction (mirrors the visibility
+        // guard below). Absent durability is accepted and defaulted to "standard".
+        {
+            const durabilityError = assertValidDurability(content.durability);
+            if (durabilityError) {
+                return new Response(JSON.stringify({ error: "invalid_durability", message: durabilityError }), { status: 400, headers: { "content-type": "application/json" } });
+            }
+        }
         content.durability ||= "standard";
         content.createdAt = new Date().toISOString();
         content.updatedAt = content.createdAt;
@@ -789,6 +803,17 @@ export class Memory extends databases.flair.Memory {
         const usedMemoryIds = content?.usedMemoryIds;
         if (content && typeof content === "object")
             delete content.usedMemoryIds;
+        // ── flair#1238: refuse an unrecognised durability (mirrors post()) ──
+        // put() is the other HTTP-reachable write path (fresh create via CLI, and
+        // the update/patch path). Same guard as post(): a present-but-unknown
+        // durability is refused with 400; absent is accepted (no default stamped
+        // here — put() leaves durability untouched for updates).
+        {
+            const durabilityError = assertValidDurability(content.durability);
+            if (durabilityError) {
+                return new Response(JSON.stringify({ error: "invalid_durability", message: durabilityError }), { status: 400, headers: { "content-type": "application/json" } });
+            }
+        }
         const now = new Date().toISOString();
         content.updatedAt = now;
         // Set defaults that post() sets — put() is also used for new records via CLI

package/dist/resources/MemoryBootstrap.js

@@ -94,20 +94,35 @@ import { estimateTokens } from "./token-estimate.js";
  *
  *   CAP CONTRACT: `maxTokens` is the HARD cap on CONTENT SELECTION — the shared
  *   `tokenBudget` starts at `maxTokens` and every admitted soul/memory/finding
- *   line AND every org event (flair#1199 — events are content too; before this
- *   they were assembled but NEVER charged, so a maxTokens=4000 request serialized
- *   at 6286) is gated against the remaining budget, so the sum of selected CONTENT
- *   never exceeds `maxTokens`. `tokenEstimate` HONESTLY reports the real serialized
- *   payload (`JSON.stringify(responseBody)`), which includes the FIXED structured-
- *   container JSON scaffolding (keys/braces, counters, the sections map) and so may
- *   exceed `maxTokens` slightly by that bounded overhead — measurement is decoupled
- *   from budgeting, but the overhead is now scaffolding ONLY, never uncounted
- *   content. The connector-conformance suite asserts tokenEstimate <= maxTokens
- *   within a small tolerance for that scaffolding. flair#1207: #1199 had ALSO
- *   folded a per-item structured overhead + a scaffolding reserve INTO the
- *   selection budget, which silently shrank recall below 0.44.6 for the same
- *   `maxTokens`; that per-item overhead is a reporting concern (already captured by
- *   `tokenEstimate`) and no longer shrinks the content budget.
+ *   AND every org event (flair#1199 — events are content too; before this they
+ *   were assembled but NEVER charged, so a maxTokens=4000 request serialized at
+ *   6286) is gated against the remaining budget, so the sum of selected CONTENT
+ *   never exceeds `maxTokens`. Each item is charged the cost of what it ACTUALLY
+ *   SHIPS on the requested surface (see contentCost): on the /mcp connector path
+ *   (includeContext=false) the prose `context` is a pointer, so only the
+ *   STRUCTURED container object ships and is charged; on the REST/CLI prose path
+ *   (includeContext=true) the prose IS the shipped surface and is charged (0.44.6
+ *   capacity — flair#1207). `tokenEstimate` HONESTLY reports the real serialized
+ *   payload (`JSON.stringify(responseBody)`). On the connector path — where the
+ *   selection charge and `tokenEstimate` measure the SAME structured bytes —
+ *   `tokenEstimate` exceeds `maxTokens` only by the FIXED JSON scaffolding
+ *   (keys/braces, counters, the sections map, hints); the connector-conformance
+ *   budgetCap asserts tokenEstimate <= maxTokens within a small tolerance for
+ *   exactly that scaffolding. On the prose path the payload ALSO carries the
+ *   structured mirror, so `tokenEstimate` may exceed `maxTokens` by that mirror —
+ *   that overage is honest measurement, and shrinking prose selection to hide it
+ *   is the flair#1207 regression (below). flair#1199 (0.44.11): charging the
+ *   PROSE line but shipping the heavier STRUCTURED object on the /mcp path let
+ *   teammate findings ride OUTSIDE the enforced budget (soulTokens 377 +
+ *   memoryTokens 3574 = 3951 prose, just under a 4000 cap, yet tokenEstimate 5337
+ *   = +33%; teammateFindingsIncluded crept 4→5) — fixed by charging structured
+ *   on the connector path. flair#1207: #1199 had ALSO folded a per-item
+ *   structured overhead + a scaffolding reserve INTO the selection budget, which
+ *   silently shrank recall below 0.44.6 for the same `maxTokens`; that flat
+ *   per-item overhead is a reporting concern (already captured by `tokenEstimate`)
+ *   and no longer shrinks the content budget — the 0.44.11 fix charges the
+ *   item's REAL shipped serialization, not a flat surcharge, and only on the path
+ *   where that serialization is the shipped surface.
  *
  *   COUNT CONTRACT (flair#1207): `memoriesIncluded + memoriesTruncated <=
  *   memoriesAvailable` — included and truncated are disjoint sets of UNIQUE own
@@ -122,6 +137,40 @@ import { estimateTokens } from "./token-estimate.js";
 // Collision surfacing (flair#681) tunables.
 const COLLISION_WINDOW_DAYS = 7;
 const MAX_COLLISION_ENTRIES = 10;
+// flair#1201/#1225 — trust-block sections that are a lifecycle-window LOAD, not
+// a retrieval surface. A trust entry from one of these carries `matchQuality:
+// null` (no relevance score to band), which is CORRECT (Kern's #1220 ruling),
+// never a scoring failure — see the `matchQualityNote` in the response tail.
+const LIFECYCLE_SECTIONS = new Set(["permanent", "recent", "predicted"]);
+// flair#1199 trust-admission — build the EXACT trust entry that ships for one
+// included memory (id + section + block + the conditional matchQualityNote), so
+// the admission loop can charge its REAL serialized cost at the same moment it
+// charges the content cost. Single source of truth: the response tail reuses
+// this same builder, so the charged size and the shipped size can never drift
+// (the #1226 "charge what ships" principle, extended to the per-item trust
+// block). The block is assembled purely for SIZING + the response — its content
+// never enters any authority/scope/attribution/dedup decision (the #735/#744
+// zero-authority invariant).
+//
+// flair#1225 — Kern ruled (on #1220) that a null `matchQuality` on an own-recent
+// (lifecycle) entry is CORRECT: lifecycle sections (permanent/recent/predicted)
+// are a window LOAD, not a retrieval surface, so there is no similarity to band
+// — the null means "not scored here", never a scoring failure on the caller's
+// own records (the #1201 misread: own-recent null beside a teammate band).
+// Behavior is unchanged (per Kern); the matchQualityNote only makes the null
+// self-describing in the payload — Fix 3's "any absent field says why" — so a
+// connector reads it right without knowing the #1201 contract.
+function buildTrustEntry(m, section) {
+    const block = buildTrustBlock(m);
+    const matchQualityNote = block.matchQuality === null
+        ? (LIFECYCLE_SECTIONS.has(section)
+            ? `matchQuality is null because '${section}' is a lifecycle-window section, not a retrieval `
+                + `surface — there is no relevance score to band. This is correct (per flair#1225), not a scoring failure.`
+            : "matchQuality is null because no semantic similarity was attached to this result "
+                + "(e.g. a by-id read or a keyword-only degraded match).")
+        : undefined;
+    return { id: m.id, section, ...block, ...(matchQualityNote ? { matchQualityNote } : {}) };
+}
 // flair#1199/#1206 — the default cap on how many org events bootstrap ships.
 // Overridable per-request via `maxEvents`. Event slots are scarce AND (as of
 // #1199) token-charged, so this bounds both the count and the spend; the shared
@@ -368,6 +417,34 @@ export class BootstrapMemories extends Resource {
             subject: m.subject ?? null,
             section,
         });
+        // flair#1199 (0.44.11) — the REAL cost an admitted content item adds to the
+        // serialized payload the caller RECEIVES, which is exactly what
+        // `tokenEstimate` measures. This is the fix for the teammate-findings
+        // budget blowout: the selector used to charge every memory/finding its
+        // PROSE line (`formatMemory`) but, on the /mcp connector path, ship the
+        // heavier STRUCTURED container object — and `tokenEstimate` measures the
+        // structured object. A teammate finding carries `id` + TWO ISO timestamps +
+        // `source` + `section` + JSON field names/quotes that the prose line does
+        // not, so the shipped object runs ~1.5–1.7× its prose line. Charging prose
+        // but shipping structured let several teammate findings ride OUTSIDE the
+        // enforced budget: a maxTokens=4000 bootstrap reported soulTokens 377 +
+        // memoryTokens 3574 = 3951 (prose, just under cap) yet serialized at 5337
+        // (+33%), and teammateFindingsIncluded crept 4→5. So charge what SHIPS:
+        //   - /mcp connector path (includeContext=false): the prose `context` is a
+        //     compact pointer (no bodies), so ONLY the structured container ships —
+        //     charge its serialized size. Now the sum of admitted content ≈
+        //     `tokenEstimate` minus the FIXED JSON scaffolding, so `tokenEstimate`
+        //     stays within maxTokens + the small scaffolding tolerance.
+        //   - REST/CLI prose path (includeContext=true): the prose IS the primary
+        //     shipped surface and flair#1207 deliberately fixed the selection budget
+        //     at 0.44.6 (prose) capacity — `tokenEstimate` is HONEST there and may
+        //     exceed maxTokens by the structured mirror it also ships. Charging
+        //     structured on THAT path would re-shrink prose recall below 0.44.6
+        //     (the exact #1207 regression). So keep charging prose on the prose
+        //     path. This is "fix the budget INPUT, not the cap": the figure the
+        //     selector tests against maxTokens is now the figure that becomes
+        //     `tokenEstimate` on each path.
+        const contentCost = (structured, proseLine) => includeContext ? estimateTokens(proseLine) : estimateTokens(JSON.stringify(structured));
         // --- 1. Soul records (budgeted — prioritized by key importance) ---
         // Soul is who you are, but we still need to respect token budgets.
         // Workspace files (SOUL.md, AGENTS.md) can be massive — they're already
@@ -617,13 +694,22 @@ export class BootstrapMemories extends Resource {
         const permanent = permanentRows.filter((m) => !permanentSupersededIds.has(m.id));
         for (const m of permanent) {
             const line = formatMemory(m, agentId);
-            const cost = estimateTokens(line); // #1207 — prose-line cost only; overhead is a reporting concern (tokenEstimate), not a selection constraint
-            if (cost <= tokenBudget) {
+            const struct = leanMemory(m, "permanent");
+            // #1199 (0.44.11) — charge what SHIPS (structured on the /mcp path, prose
+            // on the REST path); see contentCost. #1207 stays honored: on the prose
+            // path this is still the prose-line cost, so REST recall is unchanged.
+            const cost = contentCost(struct, line);
+            // flair#1199 trust-admission — charge the trust block's real serialized
+            // cost at the same moment as the content cost (per-item trust is CONTENT,
+            // not fixed scaffolding; see buildTrustEntry).
+            const trustEntry = includeTrust ? buildTrustEntry(m, "permanent") : null;
+            const trustCost = trustEntry ? estimateTokens(JSON.stringify(trustEntry)) : 0;
+            if (cost + trustCost <= tokenBudget) {
                 sections.permanent.push(line);
-                includedOwnMemories.push(leanMemory(m, "permanent"));
-                if (includeTrust)
-                    includedTrustMemories.push({ m, section: "permanent" });
-                tokenBudget -= cost;
+                includedOwnMemories.push(struct);
+                if (trustEntry)
+                    includedTrustMemories.push(trustEntry);
+                tokenBudget -= cost + trustCost;
                 includedOwnIds.add(m.id); // #1207 — count by unique own-memory id
             }
             else {
@@ -689,17 +775,22 @@ export class BootstrapMemories extends Resource {
         let recentSpent = 0;
         for (const m of recent) {
             const line = formatMemory(m, agentId);
-            const cost = estimateTokens(line); // #1207 — prose-line cost only; overhead is a reporting concern (tokenEstimate), not a selection constraint
-            if (recentSpent + cost > recentBudget) {
+            const struct = leanMemory(m, "recent");
+            const cost = contentCost(struct, line); // #1199 (0.44.11) — charge what ships; see contentCost
+            // flair#1199 trust-admission — charge the trust block's real serialized
+            // cost against BOTH the recent sub-budget and the shared tokenBudget.
+            const trustEntry = includeTrust ? buildTrustEntry(m, "recent") : null;
+            const trustCost = trustEntry ? estimateTokens(JSON.stringify(trustEntry)) : 0;
+            if (recentSpent + cost + trustCost > recentBudget) {
                 truncatedOwnIds.add(m.id); // #1207 — budget-skip; may still be admitted later via the task-relevant loop (deduped at the end)
                 continue;
             }
             sections.recent.push(line);
-            includedOwnMemories.push(leanMemory(m, "recent"));
-            if (includeTrust)
-                includedTrustMemories.push({ m, section: "recent" });
-            recentSpent += cost;
-            tokenBudget -= cost;
+            includedOwnMemories.push(struct);
+            if (trustEntry)
+                includedTrustMemories.push(trustEntry);
+            recentSpent += cost + trustCost;
+            tokenBudget -= cost + trustCost;
             includedOwnIds.add(m.id); // #1207 — count by unique own-memory id
         }
         // --- 3b. Subject-predicted context ---
@@ -732,17 +823,22 @@ export class BootstrapMemories extends Resource {
             let predictedSpent = 0;
             for (const m of subjectMemories) {
                 const line = formatMemory(m, agentId);
-                const cost = estimateTokens(line); // #1207 — prose-line cost only; overhead is a reporting concern (tokenEstimate), not a selection constraint
-                if (predictedSpent + cost > predictedBudget) {
+                const struct = leanMemory(m, "predicted");
+                const cost = contentCost(struct, line); // #1199 (0.44.11) — charge what ships; see contentCost
+                // flair#1199 trust-admission — charge the trust block's real serialized
+                // cost against BOTH the predicted sub-budget and the shared tokenBudget.
+                const trustEntry = includeTrust ? buildTrustEntry(m, "predicted") : null;
+                const trustCost = trustEntry ? estimateTokens(JSON.stringify(trustEntry)) : 0;
+                if (predictedSpent + cost + trustCost > predictedBudget) {
                     truncatedOwnIds.add(m.id); // #1207 — budget-skip (deduped against inclusions at the end)
                     continue;
                 }
                 sections.predicted.push(line);
-                includedPredicted.push(leanMemory(m, "predicted"));
-                if (includeTrust)
-                    includedTrustMemories.push({ m, section: "predicted" });
-                predictedSpent += cost;
-                tokenBudget -= cost;
+                includedPredicted.push(struct);
+                if (trustEntry)
+                    includedTrustMemories.push(trustEntry);
+                predictedSpent += cost + trustCost;
+                tokenBudget -= cost + trustCost;
                 includedOwnIds.add(m.id); // #1207 — count by unique own-memory id; also the task-relevant loop's exclusion set (no predicted→relevant double-admit)
             }
         }
@@ -908,8 +1004,36 @@ export class BootstrapMemories extends Resource {
                 // section double-spends.
                 for (const { memory: m } of scored) {
                     const line = formatMemory(m, agentId);
-                    const cost = estimateTokens(line); // #1207 — prose-line cost only; overhead is a reporting concern (tokenEstimate), not a selection constraint
-                    if (cost > tokenBudget) {
+                    // flair#1199 (0.44.11) — build the STRUCTURED container object BEFORE
+                    // the budget check so the finding is charged the cost of what actually
+                    // ships (structured on the /mcp path), not its cheaper prose line. A
+                    // teammate finding's structured object (id + two ISO timestamps +
+                    // source + section) runs well over its prose line, and it — not the
+                    // prose — is what `tokenEstimate` measures on the connector path. This
+                    // is the fix for the teammate-findings blowout: charging prose but
+                    // shipping structured let extra findings ride outside the enforced
+                    // budget (see contentCost). Cross-agent findings (`m._source` set)
+                    // ship in `teammateFindings`; own findings in `memories`.
+                    const struct = m._source
+                        ? {
+                            id: m.id,
+                            content: m.content,
+                            durability: m.durability ?? null,
+                            createdAt: m.createdAt ?? null,
+                            updatedAt: m.updatedAt ?? null,
+                            subject: m.subject ?? null,
+                            source: m._source,
+                            section: "teammate",
+                        }
+                        : leanMemory(m, "relevant");
+                    const cost = contentCost(struct, line);
+                    // flair#1199 trust-admission — charge the trust block's real serialized
+                    // cost at the same moment as the content cost. The section (teammate vs
+                    // relevant) is decided by `m._source`, so build the entry with the right
+                    // section before the budget check.
+                    const trustEntry = includeTrust ? buildTrustEntry(m, m._source ? "teammate" : "relevant") : null;
+                    const trustCost = trustEntry ? estimateTokens(JSON.stringify(trustEntry)) : 0;
+                    if (cost + trustCost > tokenBudget) {
                         // flair#1207 — a size-skip in the score-ordered task-relevant loop
                         // is no longer silent: record it on the denominator matching the
                         // record's origin (own → truncatedOwnIds, teammate → the separate
@@ -929,29 +1053,20 @@ export class BootstrapMemories extends Resource {
                         // off. Counted separately (teammateFindingsIncluded), NOT into
                         // memoriesIncluded — that different-denominator mix is what let
                         // included exceed available.
-                        includedTeammateFindings.push({
-                            id: m.id,
-                            content: m.content,
-                            durability: m.durability ?? null,
-                            createdAt: m.createdAt ?? null,
-                            updatedAt: m.updatedAt ?? null,
-                            subject: m.subject ?? null,
-                            source: m._source,
-                            section: "teammate",
-                        });
-                        if (includeTrust)
-                            includedTrustMemories.push({ m, section: "teammate" });
-                        tokenBudget -= cost;
+                        includedTeammateFindings.push(struct);
+                        if (trustEntry)
+                            includedTrustMemories.push(trustEntry);
+                        tokenBudget -= cost + trustCost;
                         teammateFindingsIncluded++;
                     }
                     else {
                         sections.relevant.push(line);
                         // flair#1182 — own task-relevant records join the `memories`
                         // container.
-                        includedOwnMemories.push(leanMemory(m, "relevant"));
-                        if (includeTrust)
-                            includedTrustMemories.push({ m, section: "relevant" });
-                        tokenBudget -= cost;
+                        includedOwnMemories.push(struct);
+                        if (trustEntry)
+                            includedTrustMemories.push(trustEntry);
+                        tokenBudget -= cost + trustCost;
                         includedOwnIds.add(m.id); // #1207 — count by unique own-memory id
                     }
                 }
@@ -1276,10 +1391,15 @@ export class BootstrapMemories extends Resource {
         // absent ⇒ the response is byte-identical to pre-slice-1. flair#1201 — each
         // entry carries its `section` so `matchQuality: null` on a lifecycle section
         // reads as "not a retrieval surface", not as a scoring failure on the
-        // caller's own records.
-        const trust = includeTrust
-            ? includedTrustMemories.map(({ m, section }) => ({ id: m.id, section, ...buildTrustBlock(m) }))
-            : undefined;
+        // caller's own records. flair#1225 (0.44.11) — the null on a lifecycle
+        // section is now SELF-EXPLAINING (matchQualityNote below), not just legible
+        // via `section`.
+        // flair#1199 trust-admission — the trust entries were built (and their real
+        // serialized cost charged) at admission time via buildTrustEntry, so the
+        // response tail just ships them as-is. The #1225 matchQualityNote logic now
+        // lives in buildTrustEntry (single source of truth — the charged size and
+        // the shipped size can never drift).
+        const trust = includeTrust ? includedTrustMemories : undefined;
         // flair#744 slice 2 — opt-in abstention verdict for the task-relevance
         // surface. Present ONLY when `abstain` is requested (byte-identical to
         // pre-slice-2 otherwise); scoped to whether any memory covered
@@ -1317,6 +1437,36 @@ export class BootstrapMemories extends Resource {
                 + `predicted surfaces your own non-permanent memories whose subject matches one of the provided `
                 + `subjects — it fills as you store memories tagged with these subjects.`
             : undefined;
+        // flair#1182 (0.44.11) — GENERALIZE the empty-container "say why" rule
+        // beyond predictedHint. `events: []` (deliberate no-op filtering) was
+        // byte-indistinguishable from the 0.44.8 silent-drop regression, where a
+        // container that SHOULD have had content shipped empty — a connector could
+        // only tell the difference by diffing against a previous payload. The rule
+        // (now applied consistently across the structured containers): any container
+        // that ships EMPTY carries a short hint naming WHY it is empty and what
+        // fills it, so "deliberately empty" is never confused with "silently
+        // dropped". Present ONLY when the container is empty (a populated container
+        // needs no hint), so a healthy payload is unchanged.
+        // events: [] — no org event in the lookback window was relevant to the
+        // caller after zero-row no-op auto-heal filtering (#1200). Present-but-empty
+        // by design, not a drop.
+        const eventsHint = includedEvents.length === 0
+            ? "No org events in the lookback window were relevant to you (org-wide, or targeted at you) "
+                + "after zero-row no-op auto-heal filtering. This container is present-but-empty by design, not dropped."
+            : undefined;
+        // teammateFindings: [] — name WHICH legitimate empty this is (no task → no
+        // retrieval; matched-but-budget-truncated; or nothing cleared the relevance
+        // floor), so it never reads as a silent drop.
+        const teammateFindingsHint = includedTeammateFindings.length === 0
+            ? (!taskProvided
+                ? "No teammateFindings: cross-agent findings are retrieved against your currentTask, and none was provided. "
+                    + "Pass currentTask to populate this."
+                : teammateFindingsTruncated > 0
+                    ? `No teammateFindings fit the token budget: ${teammateFindingsTruncated} relevant cross-agent finding(s) `
+                        + "cleared the relevance floor but were budget-truncated. Raise maxTokens to include them."
+                    : "No cross-agent (teammate) memory cleared the task-relevance floor for this currentTask. "
+                        + "This container is present-but-empty by design, not dropped.")
+            : undefined;
         const responseBody = {
             context,
             // flair#1182 (part 1) — always-present self-describing keys: who the
@@ -1341,6 +1491,11 @@ export class BootstrapMemories extends Resource {
             events: includedEvents,
             ...(currentTaskHint ? { currentTaskHint } : {}),
             ...(predictedHint ? { predictedHint } : {}),
+            // flair#1182 (0.44.11) — empty-container hints, present only when the
+            // container ships empty (see above), so a deliberately-empty container is
+            // never confused with a silent drop.
+            ...(eventsHint ? { eventsHint } : {}),
+            ...(teammateFindingsHint ? { teammateFindingsHint } : {}),
             ...(trust ? { trust } : {}),
             ...(abstention ? { abstention } : {}),
             sections: {
@@ -1392,16 +1547,20 @@ export class BootstrapMemories extends Resource {
         // the real serialized size. Every CONTENT section — soul, memories, findings,
         // AND events (flair#1199) — is now gated against the shared `maxTokens`
         // budget, so no section blows the budget with uncounted content the way the
-        // 0.44.9 events array did (maxTokens=4000 → 6286). tokenEstimate may still
-        // exceed `maxTokens` slightly, by the FIXED structural JSON scaffolding
-        // (container keys/braces, counters, sections map, char/4 rounding) — that is
-        // genuine payload the caller pays for, and it is small and bounded, NOT
-        // uncounted content. The connector-conformance suite asserts
-        // tokenEstimate <= maxTokens within a small tolerance for exactly that
-        // scaffolding. Do NOT "fix" a small over-maxTokens tokenEstimate by shrinking
-        // memory selection — that is the #1199→#1207 regression (it dropped relevant
-        // findings, charging a per-item overhead against the content budget). If the
-        // real payload consistently overruns for a use case, raise `maxTokens`.
+        // 0.44.9 events array did (maxTokens=4000 → 6286). flair#1199 (0.44.11): on
+        // the /mcp connector path each content item is charged its STRUCTURED shipped
+        // cost — the same bytes tokenEstimate measures — so tokenEstimate exceeds
+        // `maxTokens` only by the FIXED structural JSON scaffolding (container
+        // keys/braces, counters, sections map, hints, char/4 rounding): genuine
+        // payload the caller pays for, small and bounded, NOT uncounted content. The
+        // connector-conformance suite asserts tokenEstimate <= maxTokens within a
+        // small tolerance for exactly that scaffolding. On the PROSE path
+        // (includeContext=true) the payload ALSO carries the structured mirror, so
+        // tokenEstimate legitimately exceeds `maxTokens` by that mirror — do NOT
+        // "fix" THAT overrun by shrinking prose selection: that is the #1199→#1207
+        // regression (it dropped relevant findings, charging a flat per-item overhead
+        // against the content budget). If the real payload consistently overruns for
+        // a use case, raise `maxTokens`.
         const tokenEstimate = estimateTokens(JSON.stringify(responseBody));
         return { ...responseBody, tokenEstimate };
     }

package/dist/resources/auto-promote-lib.js

@@ -0,0 +1,137 @@
+// ─── ADK auto-promote — pure policy for /AutoPromoteCandidates (#1205b-2) ─────
+//
+// The UNATTENDED promotion path. After the tag-aware nightly cycle (#1205b-1)
+// stages per-user MemoryCandidates each carrying a `scopeTag`, this policy
+// decides whether an ADK-sourced candidate may be auto-promoted to the user's
+// OWN memory with NO human reviewer in the loop — replacing the human
+// `rem promote` for this one narrow path.
+//
+// Because there is no human to catch a mistake, every one of Sherlock's four
+// hard requirements is a load-bearing gate here (issue #1205 authz review):
+//
+//   Req 1 (memory-only, server-side): NOT decided here. The target is
+//     hard-locked to `memory` STRUCTURALLY in resources/AutoPromoteCandidates.ts
+//     — this lib has no notion of a target at all, so no value it returns can
+//     ever route a write to Soul. Keeping the target out of the policy object is
+//     the point: a policy field could be flipped; an absent one cannot.
+//
+//   Req 2 (tag lineage, FAIL-CLOSED): decideAutoPromote REFUSES any candidate
+//     whose stamped `scopeTag` is absent/empty or not an `adk:` scope tag. A
+//     tagless promoted claim lands in the SHARED agentId namespace and becomes
+//     retrievable by every other user of the app (cross-user leak) — so a
+//     missing scope tag is a hard STOP, never a benign "promote untagged". The
+//     stamped scopeTag (resources/memory-reflect-lib.ts buildStagedCandidateRow)
+//     is AUTHORITATIVE and consumed directly — we never re-read source memories
+//     (the seam #1205b-1 closed).
+//
+//   Req 3 (content-safety, STRICT for the unattended path): the human gate was
+//     also a content-safety gate. decideAutoPromote scans the claim through the
+//     SAME scanFields path Memory.ts uses (content-safety.ts) and, unlike
+//     Memory.ts's write scan, ALWAYS refuses a flagged claim regardless of
+//     FLAIR_CONTENT_SAFETY — an unattended write must not silently promote a
+//     prompt-injection payload merely because the instance runs in `warn` mode.
+//
+//   Req 4 (non-impersonating machine reviewerId): a promoted claim records
+//     MACHINE_REVIEWER_ADK_AUTO_PROMOTE in the reserved `machine:` namespace, so
+//     audit/attribution can never mistake an automated decision for a human or
+//     agent reviewer.
+//
+// Pure and Harper-free (its only import, content-safety.ts, is pure regex), so
+// the whole fail-closed/strict-safety decision is unit-testable directly with no
+// Harper process — the same split resources/memory-reflect-lib.ts uses.
+import { scanFields } from "./content-safety.js";
+// ─── ADK scope tag (the per-user access-control boundary) ────────────────────
+// adk-flair collapses (app, user) → ONE Flair agentId, separating users ONLY by
+// a compound tag `adk:<app>:<user>`. That tag IS the access-control boundary, so
+// an auto-promoted claim that does not carry it is a cross-user leak.
+export const ADK_SCOPE_TAG_PREFIX = "adk:";
+// ─── Machine reviewer namespace (Sherlock req 4) ─────────────────────────────
+// A promotion records a reviewerId that feeds audit/attribution
+// (schemas/memory.graphql). An automated path must record one that can NEVER be
+// mistaken for a human/agent reviewer. Reserved `machine:` namespace; canonical
+// id for this consumer is machine:adk-auto-promote.
+//
+// NOTE ON DUPLICATION: src/cli.ts declares its own copies of these constants
+// (and validateHumanReviewerId, which refuses the reserved namespace on the
+// HUMAN promote path). The two live on opposite sides of the npm-packaging
+// boundary — src/ ships as the CLI bundle, resources/ ships as the Harper
+// component, and cli.ts's own header notes imports across that boundary "don't
+// survive npm packaging". They are kept in sync by the shared canonical string;
+// there is no runtime path that imports one into the other.
+export const MACHINE_REVIEWER_PREFIX = "machine:";
+export const MACHINE_REVIEWER_ADK_AUTO_PROMOTE = "machine:adk-auto-promote";
+/** Standard, honest rationale recorded on every auto-promoted claim + its
+ *  candidate row, so the audit trail states plainly that no human reviewed it. */
+export const AUTO_PROMOTE_RATIONALE = "auto-promoted from ADK session distillation (#1205) — unattended, own-memory only, scope-tag verified, content-safety scanned; no human reviewer";
+/**
+ * Per-call ceiling on auto-promotions (Kern's cost-ceiling note). Auto-promote
+ * runs once per nightly cycle, not on every write, and each promotion is a
+ * bounded DB write (plus at most one embedding compute on the Memory.put path),
+ * so this caps the blast radius of a single cycle rather than throttling a hot
+ * path. Overflow stays `pending` and is swept on subsequent cycles.
+ */
+export const DEFAULT_MAX_AUTO_PROMOTE_PER_CYCLE = 200;
+/**
+ * Decide whether an ADK-sourced candidate may be auto-promoted to own memory.
+ *
+ * FAIL-CLOSED throughout: any condition that cannot be positively confirmed
+ * results in `{ promote: false }` (the candidate is left pending for the human
+ * `rem promote` path), never a promotion. This function decides ONLY whether to
+ * promote and with what per-user scope tag / reviewer — never WHERE (the target
+ * is memory-only and enforced structurally by the resource; see this file's
+ * header, Req 1).
+ */
+export function decideAutoPromote(candidate) {
+    // Idempotency (Kern 2d): only ever act on a still-pending candidate. A
+    // re-run after a crash re-enumerates and skips anything already promoted.
+    if (candidate.status !== "pending") {
+        return { promote: false, reason: "not_pending" };
+    }
+    // Req 2 — tag lineage, FAIL CLOSED. Consume the stamped scopeTag directly
+    // (authoritative; never re-read sources). Absent, empty, or non-`adk:` ⇒
+    // refuse: a tagless claim in the shared agentId namespace is a cross-user
+    // leak, and auto-promote is ONLY for ADK-sourced (scopeTag-bearing)
+    // candidates — a non-ADK candidate still requires human `rem promote`.
+    const scopeTag = candidate.scopeTag;
+    if (typeof scopeTag !== "string" || !scopeTag.startsWith(ADK_SCOPE_TAG_PREFIX)) {
+        return { promote: false, reason: "no_adk_scope_tag" };
+    }
+    const claim = candidate.claim;
+    if (typeof claim !== "string" || claim.trim().length === 0) {
+        return { promote: false, reason: "empty_claim" };
+    }
+    // Req 3 — content-safety, STRICT for the unattended path. Same scanFields the
+    // Memory write path uses (content-safety.ts), but here a flag is ALWAYS a
+    // refusal, independent of FLAIR_CONTENT_SAFETY: an unattended promotion must
+    // never let a prompt-injection payload through merely because the instance is
+    // in `warn` mode. (The Memory.put() write scan still runs on top of this as
+    // defense-in-depth.)
+    const safety = scanFields({ content: claim }, ["content"]);
+    if (!safety.safe) {
+        return { promote: false, reason: `content_safety:${safety.flags.join(",")}` };
+    }
+    return {
+        promote: true,
+        scopeTag,
+        reviewerId: MACHINE_REVIEWER_ADK_AUTO_PROMOTE,
+        rationale: AUTO_PROMOTE_RATIONALE,
+    };
+}
+/** True iff `id` is in the reserved machine-reviewer namespace (an automated
+ *  path, never a human/agent reviewer). Mirror of src/cli.ts isMachineReviewerId
+ *  on the resources side of the packaging boundary. */
+export function isMachineReviewerId(id) {
+    return typeof id === "string" && id.startsWith(MACHINE_REVIEWER_PREFIX);
+}
+/**
+ * The tag set for an auto-promoted Memory. The per-user `scopeTag` MUST come
+ * first and is load-bearing — it is the access-control boundary that keeps the
+ * promoted claim visible only to its own user's tag filter. `auto-promoted`
+ * marks the whole class as machine-written so every auto-promoted claim is
+ * identifiable and bulk-removable if the policy is ever rolled back (Kern 2b);
+ * `nightly-rem-promoted` matches the human promote path; `from:<id>` preserves
+ * candidate lineage.
+ */
+export function buildAutoPromotedTags(candidateId, scopeTag) {
+    return [scopeTag, "nightly-rem-promoted", "auto-promoted", `from:${candidateId}`];
+}

package/dist/resources/memory-durability.js

@@ -0,0 +1,40 @@
+/**
+ * ─── The single "is this a valid durability" writer-intent guard ────────────
+ *
+ * Mirror of resources/memory-visibility.ts's assertValidVisibility, for the
+ * durability enum. Same asymmetry, same reason:
+ *
+ *   - READING an unknown durability must be permissive. A row written before a
+ *     tier existed (or by a non-Python adapter) may hold anything, and the read
+ *     side must keep resolving it exactly as before — defaultVisibilityForDurability
+ *     treats any non-permanent/persistent string as the private branch, and that
+ *     fail-safe must not change.
+ *   - WRITING an unknown durability must be refused. Today an unknown value via
+ *     raw REST (or a future non-Python adapter) is silently accepted and lands on
+ *     the narrower private branch by accident — fail-safe, but unvalidated by
+ *     contract. Refusing at the schema boundary makes it safe by construction and
+ *     makes adk-flair's "validated server-side" claim true as written (flair#1238,
+ *     from Sherlock's #1237 review).
+ *
+ * Deliberately has ZERO imports — same load-bearing reason as memory-visibility.ts:
+ * this module is a pure function + constant that any caller can import without
+ * dragging in "harper".
+ */
+/** The only values a WRITER may supply. */
+export const WRITABLE_DURABILITIES = ["permanent", "persistent", "standard", "ephemeral"];
+/**
+ * Reject a durability a writer supplied that is not one of the four valid values.
+ * Returns an error message, or null when the value is acceptable.
+ *
+ * `undefined`/`null` are accepted: omitting the field is how a caller asks for
+ * the default ("standard"), and that is a documented, intentional path.
+ */
+export function assertValidDurability(durability) {
+    if (durability === undefined || durability === null)
+        return null;
+    if (typeof durability === "string" && WRITABLE_DURABILITIES.includes(durability)) {
+        return null;
+    }
+    return (`durability must be ${WRITABLE_DURABILITIES.map((v) => `"${v}"`).join(" or ")} ` +
+        `(got: ${JSON.stringify(durability)}). Omit it to use the default "standard".`);
+}

package/docs/mcp-clients.md

@@ -240,6 +240,14 @@ Writes are scoped per-agent (your `FLAIR_AGENT_ID`) and enforced by Flair's serv
 
 Which memories are non-private is decided at write time, and the default is not "shared". `memory_store` defaults `durability` to `standard`, and the server derives visibility from durability — `permanent`/`persistent` → `shared`, `standard`/`ephemeral` → `private` — so **a bare `memory_store` call writes an owner-only memory that no other agent can read.** Pass `visibility: "shared"` (or `"private"`, to be explicit) to say what you mean; the tool reports the visibility the write actually landed on so an agent can confirm it rather than assume.
 
+### Reading the `bootstrap` payload
+
+`bootstrap` returns the canonical structured containers — `soul`, `memories`, `predicted`, `teammateFindings`, `events` — plus counts and a `tokenEstimate`. The containers are **always present** (empty `[]`/`{}` when there's nothing), so an empty container is distinguishable from an unsupported one.
+
+**Empty containers say why they're empty (flair#1182).** When a structured container ships empty, the payload carries a short hint naming the reason and what fills it — `eventsHint`, `teammateFindingsHint`, `predictedHint`. This is present *only* when the container is empty, so a deliberately-empty container is never confused with a silent drop (a connector never has to diff against a previous payload to tell the two apart).
+
+**`matchQuality` is null on lifecycle sections — by design (flair#1225).** With `includeTrust: true`, each included memory carries a per-memory trust block, section-tagged, whose `matchQuality` is a `strong`/`moderate`/`breadcrumb` confidence band. On the **lifecycle sections** (`permanent`, `recent`, `predicted`) `matchQuality` is `null`: those are a lifecycle-window *load*, not a retrieval surface, so there is no relevance score to band. This is **correct, not a scoring failure** — an own-recent `null` next to a teammate's band does not mean your own records "scored worse". A retrieval band is only meaningful on the retrieval sections (`relevant`, `teammate`). The entry's `section` field makes this legible, and a `matchQualityNote` on any null entry states the reason inline.
+
 ---
 
 ## Configuration reference

package/docs/rem.md

@@ -1,6 +1,6 @@
 # REM — reflection, distillation, and review
 
-REM (Reflect · Extract · Merge) is Flair's memory-curation cycle: it reads an agent's recent memories, distills them into candidate insights, and stages those candidates for explicit human/agent review — nothing is ever auto-promoted. `flair rem rapid` runs it on demand; `flair rem nightly enable` runs it on a schedule. See [`docs/notes/rem-ux.md`](notes/rem-ux.md) for the full trigger model, locality guarantees, and the review-loop UX this page's commands feed into.
+REM (Reflect · Extract · Merge) is Flair's memory-curation cycle: it reads an agent's recent memories, distills them into candidate insights, and stages those candidates for explicit human/agent review — nothing is auto-promoted except the narrow ADK per-user path (see [Auto-promote](#auto-promote-adk-only)). `flair rem rapid` runs it on demand; `flair rem nightly enable` runs it on a schedule. See [`docs/notes/rem-ux.md`](notes/rem-ux.md) for the full trigger model, locality guarantees, and the review-loop UX this page's commands feed into.
 
 > **⚠️ Prerequisite: a configured generative backend.** All REM commands (`rapid`, `nightly`, `candidates`, `promote`, `reject`) require Harper's `models.generate()` to be wired — without it, REM calls fail with `Reflection error: No generative backend configured`. Set up a backend first (see [Configuration](#configuration) below) before running any REM command. The fastest path is Ollama with a non-thinking model, which needs zero credentials and keeps all traffic local.
 
@@ -59,10 +59,21 @@ Snapshot locality follows from this: a nightly cycle's pre-run snapshot (`~/.fla
 - **Interactive (`flair rem rapid`):** one bounded, synchronous distillation call — gather cap 50 memories, bounded output tokens, seconds not minutes. Executes by default, staging candidates and printing a summary; `--prompt-only` returns the reflection prompt instead, for the bring-your-own-model handoff.
 - **Nightly (`flair rem nightly enable` / `run-once`):** fully detached — the scheduler runs the full cycle (snapshot → maintenance → distillation), candidates land as pending rows, and an audit row lands in `~/.flair/logs/rem-nightly.jsonl`. The operator reviews in the morning via `flair rem candidates`.
 
-Either path, the review loop is the same: `flair rem candidates` lists pending rows, `flair rem promote <id> --rationale "<why>"` / `flair rem reject <id> --reason "<why>"` decide them. Nothing self-promotes — see [`docs/notes/rem-ux.md`](notes/rem-ux.md) for why that gate is load-bearing and how the surface is expected to evolve.
+Either path, the review loop is the same: `flair rem candidates` lists pending rows, `flair rem promote <id> --rationale "<why>"` / `flair rem reject <id> --reason "<why>"` decide them. Nothing self-promotes except the narrow ADK per-user path ([Auto-promote](#auto-promote-adk-only)) — see [`docs/notes/rem-ux.md`](notes/rem-ux.md) for why that gate is load-bearing and how the surface is expected to evolve.
 
 ### ADK agents — per-user (per-tag) distillation
 
 adk-flair collapses every `(app, user)` into **one** Flair agentId, separating users only by a per-user tag `adk:<app>:<user>`. Distilling such an agentId with the default `scope:"recent"` would mix every user's sessions into shared claims — cross-user bleed. The nightly cycle therefore detects the agent's active `adk:<app>:<user>` tags (from the memories it already loads for the snapshot, with a recency cutoff that skips idle users and is scoped to the agent's own records) and runs distillation **once per tag** under `scope:"tagged"`, so each user's candidates come only from that user's own sessions. Agents with no `adk:` tags distill agentId-wide exactly as before.
 
 A candidate distilled under a tag records that tag in its `scopeTag` field. `flair rem promote` reads `scopeTag` as the authoritative per-user lineage tag and propagates it onto the promoted memory — so the promoted claim stays in that user's retrieval scope even if the source episodes are later archived or deleted. The single-node timer rule above is unchanged; the per-tag loop runs inside the one cycle on the one node. The non-thinking-model requirement (above) still holds — the per-tag path calls the same `models.generate()` route.
+
+#### Auto-promote (ADK only)
+
+For ADK agents, the nightly cycle **auto-promotes** these `scopeTag`-bearing candidates to the user's own persistent memory immediately after distillation — the one place REM does not wait for a human `rem promote`. The safety argument is blast-radius, not identity: the claim is distilled from a user's own sessions into that same user's own tag scope, so no cross-agent or Soul trust boundary is crossed. The promotion is enforced entirely server-side (`POST /AutoPromoteCandidates`), never by a CLI flag a compromised agent key could flip, and holds four invariants:
+
+- **Memory only, never Soul.** The target is hard-locked to `memory`; there is no Soul code path (Soul is agentId-scoped and cannot carry a per-user tag, so an ADK-sourced Soul promotion would be cross-user by construction).
+- **Fail-closed tag lineage.** A candidate is promoted only if it carries an authoritative `adk:<app>:<user>` scope tag, which the promoted memory then carries. The promoted memory is written `visibility:"private"` (owner-only) — not the org-open `shared` default a `persistent` write would otherwise get — so it is reachable only through the app agent's own tag-filtered search (which re-verifies the tag), invisible both to another user's tag filter and to every other agent on the instance. A candidate whose scope tag is absent or blank is left pending, never promoted tagless into the shared agentId namespace.
+- **Content-safety, strict.** The claim is scanned for prompt injection and refused on a flag regardless of `FLAIR_CONTENT_SAFETY` — an unattended write does not fall back to warn-and-tag.
+- **Non-impersonating reviewer.** The promoted memory and its candidate record `machine:adk-auto-promote`, never a value mistakable for a human or agent reviewer.
+
+Anything ineligible (no scope tag, flagged content, already decided) is left pending for the human `rem promote` path. The step is bounded per cycle and non-fatal; `flair rem nightly run-once` reports the count auto-promoted. **Non-ADK candidates never auto-promote** — the human review gate below is unchanged for them.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.44.10",
+  "version": "0.44.12",
   "packageManager": "bun@1.3.10",
   "description": "Identity, memory, and soul for AI agents. Cryptographic identity (Ed25519), semantic memory with local embeddings, and persistent personality — all in a single process.",
   "type": "module",