@tpsdev-ai/flair 0.46.0 → 0.47.0

package/dist/resources/MemoryBootstrap.js

@@ -78,7 +78,19 @@ import { estimateTokens } from "./token-estimate.js";
  *   { context, sections, tokenEstimate, maxTokens, memoriesIncluded, memoriesAvailable,
  *     memoriesTruncated, teammateFindingsIncluded, teammateFindingsTruncated,
  *     teammateFindingsMatched, agentId, scope, soul, memories, predicted,
- *     teammateFindings, events[, currentTaskHint][, predictedHint] }
+ *     teammateFindings, events, soulTokens, memoryTokens, trustTokens,
+ *     eventsTokens, scaffoldTokens[, currentTaskHint][, predictedHint] }
+ *
+ *   TOKEN LEDGER (flair#1270): the counters decompose `tokenEstimate` from the
+ *   payload alone —
+ *     tokenEstimate ≈ scaffoldTokens + soulTokens + memoryTokens + trustTokens
+ *                     + eventsTokens
+ *   Each figure is measured from what SHIPS (never derived as a residual), so
+ *   a section that ships uncounted content breaks the identity visibly instead
+ *   of hiding in an unexplained gap. See the ledger block in the response tail
+ *   for each counter's definition and the documented ≈ tolerance (the #1207
+ *   prose-vs-structured measurement decoupling on the connector path; the
+ *   structured mirror on the prose path).
  *   The self-describing keys (flair#1182 part 1) — `agentId` (resolved caller),
  *   `scope` (read model applied to the caller), `soul`/`memories`/`predicted`
  *   (the caller's OWN records as structured containers), and `currentTaskHint`
@@ -419,6 +431,14 @@ export class BootstrapMemories extends Resource {
         // read below). Declared out here so it is in scope for the response body even
         // if the events read (in a try/catch) yields nothing.
         const includedEvents = [];
+        // flair#1298 — count of events that ENTERED the admission loop (relevant to
+        // the caller, inside the lookback window, survived dedup + the no-op
+        // filter) but were skipped by the budget gate (`cost > tokenBudget`).
+        // Feeds the budget-truncated branch of eventsHint, mirroring
+        // teammateFindingsTruncated. Deliberately counts ONLY admitted-then-
+        // skipped events — never a gap derived from some larger tally, which
+        // could imply the existence of rows the caller was not allowed to see.
+        let eventsBudgetTruncated = 0;
         const leanMemory = (m, section) => ({
             id: m.id,
             content: m.content,
@@ -1316,8 +1336,13 @@ export class BootstrapMemories extends Resource {
                 // /mcp path; the prose line is a subset of it). This is the #1199 fix:
                 // events are content and must be budgeted like content.
                 const cost = estimateTokens(JSON.stringify(structured));
-                if (cost > tokenBudget)
+                // flair#1298 — an event that reached admission but does not fit the
+                // remaining budget is TRUNCATED, not irrelevant; count it so eventsHint
+                // can say so instead of claiming "empty by design" (#1182 contract).
+                if (cost > tokenBudget) {
+                    eventsBudgetTruncated++;
                     continue;
+                }
                 const elapsed = Date.now() - new Date(evt.createdAt).getTime();
                 const mins = Math.floor(elapsed / 60_000);
                 const relTime = mins < 60 ? `${mins}min ago` : `${Math.floor(mins / 60)}h ago`;
@@ -1350,6 +1375,17 @@ export class BootstrapMemories extends Resource {
         // teammate finding is EITHER included OR budget-truncated, so this equals their sum.
         // Reporting it anchors `teammateFindingsTruncated` as "relevant-but-no-budget"
         // rather than an unexplained large number beside a small `included`.
+        //
+        // flair#1290 — INFORMATIONAL-DERIVED, not an independent measurement: this
+        // is computed FROM the two counters it anchors, so `included + truncated
+        // == matched` holds by construction and can never fail. It stays on the
+        // response as a legibility anchor, but it must never serve as the
+        // `available` side of a countCoherence-style invariant — that entry
+        // asserted X <= X, permanently green, and was removed from the bootstrap
+        // contract's invariant array (see resources/mcp-tools.ts; an invariant
+        // that cannot fail is decorative). An independently-measured pre-admission
+        // pool tally was considered and ruled out (K&S on #1290): a new counter
+        // that would itself need an invariant, for marginal gain.
         const teammateFindingsMatched = teammateFindingsIncluded + teammateFindingsTruncated;
         // --- Build context string ---
         const parts = [];
@@ -1408,6 +1444,34 @@ export class BootstrapMemories extends Resource {
                 : `Structured payload in soul/memories/predicted/teammateFindings `
                     + `(${memoriesIncluded} own + ${teammateFindingsIncluded} teammate memories, `
                     + `${sections.soul.length} soul entries). Pass includeContext:true for the assembled prose context.`);
+        // ── The payload token LEDGER (flair#1270) ────────────────────────────────
+        //
+        // IDENTITY (documented here because the counters are declared here; the
+        // identity lives in the RESPONSE SCHEMA, not tests-only — a test-only
+        // counter doesn't prevent silent regression, per Kern's #1270 ruling):
+        //
+        //   tokenEstimate ≈ scaffoldTokens + soulTokens + memoryTokens
+        //                   + trustTokens + eventsTokens
+        //
+        // Every token-charged content class has a named counter, so a consumer can
+        // decompose `tokenEstimate` FROM THE PAYLOAD ALONE and any future section
+        // that ships uncounted content shows up as a residual the reported figures
+        // don't explain — the ~1178-token "uncounted" gap the nairmy field rounds
+        // decomposed on 0.44.11/0.44.13 (trust blocks charged at admission since
+        // #1240, but absent from the reported counters) is structurally impossible
+        // to reintroduce silently.
+        //
+        // The ≈ gap on the connector path (includeContext=false) is the documented
+        // measurement/budgeting decoupling (#1207): soulTokens/memoryTokens count
+        // the rendered PROSE lines while the containers ship the heavier
+        // STRUCTURED objects (per-item id/timestamps/keys + JSON string escaping),
+        // so the sum runs BELOW tokenEstimate by that bounded per-item overhead —
+        // never above it (beyond per-line ceil rounding). On the prose path
+        // (includeContext=true) the payload additionally carries the full prose
+        // `context` beside the structured mirror, so the gap legitimately widens by
+        // that mirror — the same documented overage as the CAP CONTRACT above.
+        // None of these counters is a residual: each is measured from what ships,
+        // so the identity CAN fail — that is the point.
         const soulTokens = sections.soul.reduce((sum, line) => sum + estimateTokens(line), 0);
         // #1199 — memory-line token spend (informational breakdown), independent of
         // the reserve/soul now sharing the budget. Sum of the rendered memory lines.
@@ -1415,6 +1479,18 @@ export class BootstrapMemories extends Resource {
             ...sections.permanent, ...sections.recent, ...sections.predicted,
             ...sections.relevant, ...sections.teammate,
         ].reduce((sum, line) => sum + estimateTokens(line), 0);
+        // flair#1270 — the trust array's token spend: Σ estimateTokens(JSON) over
+        // the SHIPPED trust entries. Same builder (buildTrustEntry) and same
+        // formula as the per-entry `trustCost` the five admission sites charged
+        // (#1240), so the reported figure and the admission charge cannot drift.
+        // Always present; 0 when includeTrust is off (the counter convention:
+        // "empty" is reported, never absent).
+        const trustTokens = includedTrustMemories.reduce((sum, entry) => sum + estimateTokens(JSON.stringify(entry)), 0);
+        // flair#1270 — the events container's token spend: Σ estimateTokens(JSON)
+        // over the SHIPPED structured events — exactly the per-event cost the
+        // events admission loop charged (#1199). Same reporting hole-class as
+        // trust: charged content with no counter would be invisible in the ledger.
+        const eventsTokens = includedEvents.reduce((sum, evt) => sum + estimateTokens(JSON.stringify(evt)), 0);
         // flair#744 slice 1 — opt-in per-memory trust block. Bootstrap renders
         // memories as text lines rather than result objects, so the block is
         // surfaced as a `trust` array of self-contained entries (each carries its
@@ -1481,12 +1557,19 @@ export class BootstrapMemories extends Resource {
         // 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.
+        // events: [] — name WHICH empty this is (flair#1298, mirroring the
+        // teammateFindingsHint branches below): relevant-but-budget-truncated
+        // (events cleared the lookback window and every relevance filter but none
+        // fit the remaining token budget — saying "by design" there is exactly the
+        // false reassurance the #1182 hint contract forbids), or genuinely no
+        // relevant event in the window 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."
+            ? (eventsBudgetTruncated > 0
+                ? `No org events fit the token budget: ${eventsBudgetTruncated} relevant event(s) cleared the `
+                    + "lookback window but were budget-truncated. Raise maxTokens to include them."
+                : "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 no cross-agent record entered
@@ -1549,6 +1632,11 @@ export class BootstrapMemories extends Resource {
             },
             soulTokens,
             memoryTokens,
+            // flair#1270 — the remaining ledger terms (see the IDENTITY block above,
+            // where these counters are computed): trust and events content, so every
+            // token-charged content class is decomposable from the payload alone.
+            trustTokens,
+            eventsTokens,
             // flair#1199 — the content-selection budget this response was built
             // against (echoed so a connector can relate tokenEstimate to the budget it
             // asked for — and so the conformance tokenEstimate<=maxTokens invariant is
@@ -1598,6 +1686,29 @@ export class BootstrapMemories extends Resource {
         // 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`.
+        // flair#1270 — scaffoldTokens: the fixed structural frame, measured
+        // DIRECTLY (never derived as tokenEstimate-minus-the-other-counters — a
+        // residual would silently absorb any future uncounted content, defeating
+        // the ledger's whole purpose). Measured as the serialized body with every
+        // CONTENT container emptied: what remains is exactly the module-doc's
+        // "fixed JSON scaffolding" — container keys/braces, the counters, the
+        // sections map, scope, hints. Cheap: one JSON.stringify of a small object.
+        // The spread-then-override keeps key order identical to the delivered
+        // body, so a consumer can reconstruct this figure exactly from the
+        // payload: empty the same content fields, drop scaffoldTokens /
+        // tokenEstimate / the wrapper-injected flairVersion (all appended AFTER
+        // this measurement), and re-run the same estimator.
+        const scaffoldSkeleton = {
+            ...responseBody,
+            context: "",
+            soul: {},
+            memories: [],
+            predicted: [],
+            teammateFindings: [],
+            events: [],
+            ...(trust ? { trust: [] } : {}),
+        };
+        responseBody.scaffoldTokens = estimateTokens(JSON.stringify(scaffoldSkeleton));
         const tokenEstimate = estimateTokens(JSON.stringify(responseBody));
         return { ...responseBody, tokenEstimate };
     }

package/dist/resources/MemoryReflect.js

@@ -12,7 +12,9 @@
  *   scope        string   — "recent" | "tagged" | "all" (default: "recent")
  *   since        string?  — ISO timestamp lower bound (default: 24h ago)
  *   maxMemories  number?  — cap (default: 50)
- *   focus        string?  — "lessons_learned" | "patterns" | "decisions" | "errors" (default: "lessons_learned")
+ *   focus        string?  — "lessons_learned" | "patterns" | "decisions" | "errors" | "continuity"
+ *                            (default: "lessons_learned"; a continuity-tag run — scope="tagged" with an
+ *                            adk:continuity:* tag — always uses "continuity", flair#1257 slice 3)
  *   tag          string?  — required when scope="tagged"
  *   execute      boolean? — default false. When true, distill server-side and
  *                            stage MemoryCandidate rows instead of returning a prompt.
@@ -27,6 +29,8 @@
  *   candidates  MemoryCandidate[] — staged rows (rationalePrompt omitted — see below)
  *   count       number
  *   model       string            — resolved model id (see generatedBy note below)
+ *   droppedStaleIntent number?    — continuity runs only (flair#1257 slice 3): candidates
+ *                                    dropped by the stale-intent post-filter
  *
  * The pure logic behind execute mode (prompt building, actor resolution,
  * generate+validate+retry, dedup) lives in ./memory-reflect-lib.ts — see that
@@ -40,7 +44,7 @@ import { Resource, databases, models, logger } from "harper";
 import { randomBytes } from "node:crypto";
 import { isAdmin, allowVerified } from "./agent-auth.js";
 import { patchRecordSilent } from "./table-helpers.js";
-import { buildReflectionPrompt, buildExecutePrompt, resolveReflectActor, generateCandidates, dedupeCandidates, memoryMatchesReflectScope, buildStagedCandidateRow, } from "./memory-reflect-lib.js";
+import { buildReflectionPrompt, buildExecutePrompt, resolveReflectActor, generateCandidates, dedupeCandidates, memoryMatchesReflectScope, buildStagedCandidateRow, isContinuityScopeTag, filterStaleSessionIntentCandidates, resolveCandidateVisibilityRuling, DEFAULT_STALE_INTENT_HORIZON_MS, } from "./memory-reflect-lib.js";
 export class ReflectMemories extends Resource {
     // Self-authorize via the Ed25519 agent verify (auth reshape removes the gate's
     // admin elevation). Any verified agent may reflect; the isAdmin checks in post()
@@ -67,6 +71,7 @@ export class ReflectMemories extends Resource {
         }
         const agentId = actorResolution.agentId;
         const sinceDate = since ? new Date(since) : new Date(Date.now() - 24 * 3600_000);
+        const gatherNow = new Date();
         const memories = [];
         for await (const record of databases.flair.Memory.search()) {
             if (record.agentId !== agentId)
@@ -75,6 +80,14 @@ export class ReflectMemories extends Resource {
                 continue;
             if (record.durability === "permanent")
                 continue; // permanent memories don't need reflection
+            // flair#1257 slice 3: never gather a TTL-expired row. The reap
+            // (MemoryMaintenance) is asynchronous, so an ephemeral row whose
+            // expiresAt is past can still be in storage — distilling it would
+            // resurrect exactly what the TTL killed (same rule the continuity
+            // resume path applies on read, packages/flair-mcp/src/continuity.ts
+            // isLive; scenario S4: expired rows are excluded even before the reap).
+            if (typeof record.expiresAt === "string" && record.expiresAt !== "" && new Date(record.expiresAt) <= gatherNow)
+                continue;
             // Scope selection — the cross-user-bleed boundary (#1205b-1). See
             // memoryMatchesReflectScope's doc: scope:"tagged" admits ONLY the one
             // adk:<app>:<user> tag's memories, so a candidate distilled here can
@@ -111,7 +124,31 @@ export class ReflectMemories extends Resource {
             };
         }
         // ── execute mode (spec §3A) ─────────────────────────────────────────────
-        const executePrompt = buildExecutePrompt({ agentId, focus, scope, sinceISO: sinceDate.toISOString(), memories: promptInputs });
+        // flair#1257 slice 3 — continuity-journal runs. A scope:"tagged" run whose
+        // tag is a continuity session tag (`adk:continuity:<sessionId>`) gets the
+        // continuity guard set: the continuity focus prompt (the stale-intent
+        // prompt rule is a Kern-ruled guard, so it is UNCONDITIONAL for continuity
+        // runs — a caller-supplied focus cannot switch it off), the visibility
+        // ruling contract in the prompt, and the stale-intent post-filter below.
+        const isContinuityRun = scope === "tagged" && isContinuityScopeTag(tag);
+        const effectiveFocus = isContinuityRun ? "continuity" : focus;
+        // Session age = the NEWEST gathered entry's createdAt (memories are sorted
+        // ascending above). Staleness horizon: default 72h, FLAIR_REM_STALE_INTENT_HOURS.
+        const sessionNewestCreatedAt = memories.length > 0 ? memories[memories.length - 1].createdAt : undefined;
+        const staleHorizonHours = Number(process.env.FLAIR_REM_STALE_INTENT_HOURS);
+        const staleHorizonMs = Number.isFinite(staleHorizonHours) && staleHorizonHours > 0
+            ? staleHorizonHours * 3600_000
+            : DEFAULT_STALE_INTENT_HORIZON_MS;
+        const executeNow = new Date();
+        const sessionStale = !sessionNewestCreatedAt || executeNow.getTime() - new Date(sessionNewestCreatedAt).getTime() > staleHorizonMs;
+        const executePrompt = buildExecutePrompt({
+            agentId,
+            focus: effectiveFocus,
+            scope,
+            sinceISO: sinceDate.toISOString(),
+            memories: promptInputs,
+            ...(isContinuityRun ? { continuity: { sessionStale } } : {}),
+        });
         const gatheredMemoryIds = new Set(promptInputs.map((m) => m.id));
         const configuredModel = process.env.FLAIR_REM_MODEL || undefined;
         const outcome = await generateCandidates({
@@ -130,6 +167,21 @@ export class ReflectMemories extends Resource {
         if (outcome.usedJsonFallback) {
             logger.warn?.(`MemoryReflect: json-fallback path active for agent ${agentId} (schema-mode output failed validation)`);
         }
+        // flair#1257 slice 3 — the stale-intent POST-FILTER (the testable second
+        // layer of the two-layer guard; the prompt rule above is the primary).
+        // Runs AFTER validation (a drop is a policy skip, never a batch failure)
+        // and BEFORE dedup/staging. Only continuity runs are filtered — for every
+        // other run this is a straight pass-through.
+        const staleIntentResult = isContinuityRun
+            ? filterStaleSessionIntentCandidates(outcome.candidates, {
+                sessionNewestCreatedAt,
+                now: executeNow,
+                horizonMs: staleHorizonMs,
+            })
+            : { kept: outcome.candidates, droppedStaleIntent: [] };
+        if (staleIntentResult.droppedStaleIntent.length > 0) {
+            logger.warn?.(`MemoryReflect: stale-intent filter dropped ${staleIntentResult.droppedStaleIntent.length} candidate(s) for agent ${agentId} (stale continuity session)`);
+        }
         // Dedup against this agent's existing pending candidates (spec §3A item 4).
         const existingPendingClaims = [];
         for await (const c of databases.flair.MemoryCandidate.search({})) {
@@ -139,7 +191,7 @@ export class ReflectMemories extends Resource {
                 continue;
             existingPendingClaims.push(c.claim);
         }
-        const toStage = dedupeCandidates(outcome.candidates, existingPendingClaims);
+        const toStage = dedupeCandidates(staleIntentResult.kept, existingPendingClaims);
         // generatedBy: GenerateResult in the pinned harper 5.1.17 has
         // no model/backend-id field (content/finishReason/usage/toolCalls/trace
         // only) — the "from the generate result if available" branch is
@@ -163,6 +215,12 @@ export class ReflectMemories extends Resource {
                 generatedAt,
                 scope,
                 tag,
+                // flair#1257 slice 3: record an AFFIRMATIVE shared ruling (with its
+                // team-relevance justification) on the candidate — continuity runs
+                // only. resolveCandidateVisibilityRuling returns null for anything
+                // less than shared+justified, and null stamps nothing: the promoted
+                // row then defaults private (Sherlock's default-private-unless).
+                visibilityRuling: isContinuityRun ? resolveCandidateVisibilityRuling(c) : null,
             });
             await databases.flair.MemoryCandidate.put(row);
             staged.push(row);
@@ -173,6 +231,13 @@ export class ReflectMemories extends Resource {
         // candidate would just repeat the same large string N times. Matches
         // `flair rem candidates`' own listing, which doesn't surface it either.
         const responseCandidates = staged.map(({ rationalePrompt, ...rest }) => rest);
-        return { candidates: responseCandidates, count: responseCandidates.length, model: resolvedModel };
+        return {
+            candidates: responseCandidates,
+            count: responseCandidates.length,
+            model: resolvedModel,
+            // flair#1257 slice 3: continuity-run observability — how many candidates
+            // the stale-intent post-filter dropped (0 for non-continuity runs).
+            ...(isContinuityRun ? { droppedStaleIntent: staleIntentResult.droppedStaleIntent.length } : {}),
+        };
     }
 }

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

@@ -123,6 +123,52 @@ export function decideAutoPromote(candidate) {
 export function isMachineReviewerId(id) {
     return typeof id === "string" && id.startsWith(MACHINE_REVIEWER_PREFIX);
 }
+// ─── Promoted-row visibility (flair#1257 slice 3 — default-private-unless) ────
+// Continuity-journal scope tag prefix. Canonical string duplicated in
+// resources/memory-reflect-lib.ts (CONTINUITY_SCOPE_TAG_PREFIX), packages/
+// flair-mcp/src/continuity.ts (the writer) and src/rem/runner.ts — kept in
+// sync by the shared canonical string across the npm-packaging boundaries
+// (same discipline as MACHINE_REVIEWER_* above).
+export const CONTINUITY_SCOPE_TAG_PREFIX = "adk:continuity:";
+/** True iff `tag` is a continuity-journal scope tag (non-empty sessionId
+ *  component — the bare prefix is not a session). */
+export function isContinuityScopeTag(tag) {
+    return typeof tag === "string" && tag.length > CONTINUITY_SCOPE_TAG_PREFIX.length && tag.startsWith(CONTINUITY_SCOPE_TAG_PREFIX);
+}
+/**
+ * Decide a promoted Memory row's visibility (Sherlock's ruling, flair#1257
+ * slice 3): **default-private-unless**. Promotion is a visibility ESCALATION
+ * from the most sensitive tier (the sources are ephemeral+private journal
+ * rows, or standard+private session episodes), so the DEFAULT — including
+ * every uncertainty fallback — is "private". "shared" is returned ONLY when
+ * ALL of:
+ *
+ *   1. the candidate is CONTINUITY-scoped (scopeTag `adk:continuity:*`).
+ *      ADK per-user candidates (`adk:<app>:<user>`) are ALWAYS private —
+ *      their per-user isolation is client-side tag re-verification that
+ *      other agents don't run, so a shared ADK promotion leaks a user's
+ *      distilled private data org-wide (the #1205b-2 safety argument). No
+ *      ruling can override that; and
+ *   2. the distiller AFFIRMATIVELY ruled "shared" (visibilityRuling —
+ *      stamped at staging only when the model emitted an explicit shared
+ *      ruling, resources/memory-reflect-lib.ts); and
+ *   3. a non-empty team-relevance justification is recorded on the candidate
+ *      (visibilityRationale). A shared ruling without its justification is
+ *      not affirmative — it decays to private, fail-closed.
+ *
+ * So a shared promoted row always traces to a recorded justification on its
+ * candidate — never to a default, never silently.
+ */
+export function decidePromotedVisibility(candidate) {
+    if (!isContinuityScopeTag(candidate.scopeTag))
+        return "private";
+    if (candidate.visibilityRuling !== "shared")
+        return "private";
+    const rationale = typeof candidate.visibilityRationale === "string" ? candidate.visibilityRationale.trim() : "";
+    if (rationale.length === 0)
+        return "private";
+    return "shared";
+}
 /**
  * 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

package/dist/resources/build-info.js

@@ -0,0 +1,50 @@
+/**
+ * build-info.ts — read back the build-identity stamp the build wrote
+ * (flair#1076; the stamp itself is written by scripts/write-build-info.mjs
+ * at the end of both `build` and `build:cli`).
+ *
+ * WHY THE PATH IS MODULE-RELATIVE. The point of the stamp (Kern's ruling on
+ * #1076) is that the RUNNING server reports its own build identity — a
+ * file-only check proves the artifact on disk, not what the server loaded
+ * (the 0.25.0 stale-dist incident class). Compiled, this module executes as
+ * `dist/resources/build-info.js`, so `../build-info.json` is the stamp
+ * emitted by the very build whose modules Harper loaded (config.yaml's
+ * `jsResource: dist/resources/*.js`) — the same "resolve relative to THIS
+ * running module" idiom as resolveVersion() in resources/version.ts.
+ *
+ * When this module runs from SOURCE (a bun test importing resources/*.ts
+ * directly), `../build-info.json` is the repo root, where no stamp exists —
+ * the resolver returns null and callers fall back honestly (version from
+ * package.json, buildCommit served as null). A source run has no build, so
+ * it HAS no build identity; reaching over into dist/ would report someone
+ * else's.
+ *
+ * Read per call, not cached: identical lifecycle to resolveVersion()'s
+ * package.json read, and /Health stays a truthful view of the file rather
+ * than of whichever request happened to arrive first.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+export function resolveBuildInfo() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const stampPath = join(here, "..", "build-info.json");
+        if (!existsSync(stampPath))
+            return null;
+        const raw = JSON.parse(readFileSync(stampPath, "utf-8"));
+        if (!raw || typeof raw !== "object")
+            return null;
+        // Per-field validation, not a whole-object trust: a malformed stamp
+        // degrades field-by-field to null rather than inventing values.
+        return {
+            version: typeof raw.version === "string" && raw.version.length > 0 ? raw.version : null,
+            commit: typeof raw.commit === "string" && /^[0-9a-f]{40}$/.test(raw.commit) ? raw.commit : null,
+            builtAt: typeof raw.builtAt === "string" ? raw.builtAt : null,
+            builder: typeof raw.builder === "string" ? raw.builder : null,
+        };
+    }
+    catch {
+        return null; // unreadable/corrupt stamp — same honest fallback as absent
+    }
+}

package/dist/resources/entity-vocab.js

@@ -107,6 +107,23 @@ export function isValidEntity(entity) {
         return false;
     return VALUE_VALIDATORS[parsed.type](parsed.value);
 }
+/**
+ * Canonical "what does well-formed look like" hint for invalid_entity /
+ * invalid_entities rejections (flair#1288, nightly-canary finding 5): every
+ * rejection of an entity string must name the `type:value` format AND
+ * enumerate the closed type set — errors must enable a response. Built from
+ * ENTITY_TYPES so the enumeration can never drift from the vocabulary it
+ * describes.
+ *
+ * The CLI ships an inlined copy of this module for its client-side pre-check
+ * (src/lib/entity-vocab-cli.ts — cross-boundary imports from src/ into
+ * resources/ don't survive npm packaging; same reason src/cli.ts inlines the
+ * federation crypto helpers). test/unit/cli-entities-option.test.ts pins the
+ * two implementations together, this hint string included.
+ */
+export function entityFormatHint() {
+    return `entities are 'type:value' vocabulary strings (e.g. 'repo:owner/name'); valid types: ${ENTITY_TYPES.join(", ")}`;
+}
 /**
  * Validate an `entities` field value (expected: string[] | undefined | null).
  * `undefined`/`null` is treated as valid — the field is additive/optional,
@@ -135,5 +152,12 @@ export function invalidEntitiesResponse(entities) {
     const result = validateEntities(entities);
     if (result.valid)
         return null;
-    return new Response(JSON.stringify({ error: "invalid_entities", invalid: result.invalid }), { status: 400, headers: { "Content-Type": "application/json" } });
+    // `message` is additive (flair#1288) — `error` and `invalid` keep their
+    // exact shapes for existing consumers; the new field makes the rejection
+    // actionable on its own (names the format, enumerates the valid types).
+    return new Response(JSON.stringify({
+        error: "invalid_entities",
+        invalid: result.invalid,
+        message: `invalid entities: ${result.invalid.join(", ")} — ${entityFormatHint()}`,
+    }), { status: 400, headers: { "Content-Type": "application/json" } });
 }

package/dist/resources/health.js

@@ -4,6 +4,7 @@ import { homedir, platform } from "node:os";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { allowVerified, resolveAgentAuth } from "./agent-auth.js";
+import { resolveBuildInfo } from "./build-info.js";
 import { getMigrationStatusSnapshot } from "./migrations/status.js";
 import { resolveMigrationDataDirForRead } from "./migrations/data-dir.js";
 import { REM_DEDUP_STATS_PATH } from "./dedup-cluster.js";
@@ -85,7 +86,21 @@ export class Health extends Resource {
         // PUBLICLY over Fabric, the public surface must omit this field (the
         // richer, auth-gated /HealthDetail already carried version pre-existing —
         // this only adds it to the anonymous endpoint too).
-        return { ok: true, version: resolveVersion() };
+        //
+        // flair#1076: both values come from dist/build-info.json — the stamp the
+        // build wrote next to the modules Harper actually loaded — so /Health
+        // reports the identity of the SERVED code, not of whatever package.json
+        // sits on disk (the 0.25.0 stale-dist incident class; Kern's ruling).
+        // `version` falls back to the package.json resolver only when no stamp
+        // exists (source runs, pre-#1076 dists). `buildCommit` is ALWAYS present:
+        // a 40-hex sha when the build ran in a git work tree, an honest null
+        // otherwise (tarball builds) — never omitted, never fabricated (Sherlock).
+        const build = resolveBuildInfo();
+        return {
+            ok: true,
+            version: build?.version ?? resolveVersion(),
+            buildCommit: build?.commit ?? null,
+        };
     }
 }
 /**
@@ -682,10 +697,15 @@ export class HealthDetail extends Resource {
         // ── Warnings ──
         stats.warnings = warnings;
         // ── Process info ──
-        // version: the RUNNING process's own package.json — used by `flair
-        // upgrade`'s post-restart verification (flair#635) to prove the new
-        // code is actually serving, not just installed on disk.
-        stats.version = resolveVersion();
+        // version: the RUNNING process's own build stamp (dist/build-info.json,
+        // flair#1076) — used by `flair upgrade`'s post-restart verification
+        // (flair#635) to prove the new code is actually serving, not just
+        // installed on disk. Falls back to the package.json resolver when no
+        // stamp exists; buildCommit mirrors /Health's field (always present,
+        // null when built outside a git work tree).
+        const build = resolveBuildInfo();
+        stats.version = build?.version ?? resolveVersion();
+        stats.buildCommit = build?.commit ?? null;
         stats.pid = process.pid;
         stats.uptimeSeconds = Math.floor(process.uptime());
         return stats;

package/dist/resources/mcp-tools.js

@@ -788,6 +788,11 @@ export const TOOLS = {
                 "sections", "tokenEstimate", "maxTokens", "memoriesIncluded", "memoriesAvailable",
                 "memoriesTruncated", "teammateFindingsIncluded", "teammateFindingsTruncated",
                 "teammateFindingsMatched", "context", "flairVersion",
+                // flair#1270 — the payload token LEDGER: every token-charged content
+                // class has a counter, so tokenEstimate ≈ scaffoldTokens + soulTokens +
+                // memoryTokens + trustTokens + eventsTokens decomposes from the payload
+                // alone (see the identity block in MemoryBootstrap's response tail).
+                "soulTokens", "memoryTokens", "trustTokens", "eventsTokens", "scaffoldTokens",
             ],
             fieldTypes: {
                 agentId: "string", soul: "object", memories: "array", predicted: "array",
@@ -796,6 +801,8 @@ export const TOOLS = {
                 memoriesAvailable: "number", memoriesTruncated: "number",
                 teammateFindingsIncluded: "number", teammateFindingsTruncated: "number",
                 teammateFindingsMatched: "number", context: "string", flairVersion: "string",
+                soulTokens: "number", memoryTokens: "number", trustTokens: "number",
+                eventsTokens: "number", scaffoldTokens: "number",
             },
             invariants: {
                 // count == delivered — the historical count/charge/deliver drift.
@@ -822,12 +829,55 @@ export const TOOLS = {
                 // tolerance covers the fixed JSON scaffolding + the #1207 prose-vs-
                 // structured charge gap; uncounted content does not fit under it.
                 budgetCap: { estimate: "tokenEstimate", budget: "maxTokens", tolerance: 0.25 },
-                // #1207 — count arithmetic: included + truncated <= available, for own
-                // memories AND teammate findings (each a disjoint split of its pool).
+                // flair#1290 step 4 — the #1270 token-ledger identity, enforced:
+                // tokenEstimate ≈ scaffold + soul + memory + trust + events, two-sided
+                // (constants sized in bootstrap-token-ledger-1270.test.ts, which reads
+                // them from HERE — one identity, one tolerance definition). The upper
+                // bound is waived when the request opted into the prose mirror
+                // (includeContext), which legitimately widens the gap by design.
+                tokenDecomposition: {
+                    total: "tokenEstimate",
+                    terms: ["scaffoldTokens", "soulTokens", "memoryTokens", "trustTokens", "eventsTokens"],
+                    perItemContainers: ["memories", "predicted", "teammateFindings"],
+                    perItemGap: 60,
+                    fixedSlack: 150,
+                    roundingSlack: 48,
+                    proseMirrorArg: "includeContext",
+                },
+                // #1207 — count arithmetic: included + truncated <= available. The
+                // own-memory triple CAN fail: memoriesAvailable comes from an
+                // independent count query, so a double-counted memory breaks it.
                 countCoherence: [
                     { included: "memoriesIncluded", truncated: "memoriesTruncated", available: "memoriesAvailable" },
-                    { included: "teammateFindingsIncluded", truncated: "teammateFindingsTruncated", available: "teammateFindingsMatched" },
+                    // flair#1290 — the teammate triple ({ teammateFindingsIncluded,
+                    // teammateFindingsTruncated, teammateFindingsMatched }) is
+                    // deliberately NOT here. teammateFindingsMatched is DEFINED as
+                    // included + truncated (informational-derived — see the note at its
+                    // definition in resources/MemoryBootstrap.ts), so the entry asserted
+                    // X <= X: permanently green by construction. An invariant that
+                    // cannot fail is decorative, and a decorative entry in this array
+                    // misrepresents the coverage the suite provides. K&S ruling on
+                    // #1290: drop it rather than adding an independently-measured pool
+                    // tally (a new counter that would itself need an invariant); the
+                    // trust path's real protections are budgetCap plus the own-memory
+                    // triple above, now exercised under includeTrust:true.
+                ],
+                // flair#1290 — populated-or-hint (#1182's 0.44.11 rule, previously
+                // asserted nowhere): every structured container that ships empty
+                // carries its "why" hint, and no hint ships beside a populated
+                // container. Conditions per the hintWhenEmpty type doc — predictedHint
+                // additionally requires subjects to have been requested;
+                // currentTaskHint keys off the request, not a container.
+                hintWhenEmpty: [
+                    { hint: "eventsHint", container: "events" },
+                    { hint: "teammateFindingsHint", container: "teammateFindings" },
+                    { hint: "predictedHint", container: "predicted", requiresNonEmptyArrayArg: "subjects" },
+                    { hint: "currentTaskHint", presentWhenStringArgBlank: "currentTask" },
                 ],
+                // flair#1290 — nothing the wrapper's own classifier calls a zero-row
+                // no-op ships as an event (#1200 render filter as a semantic class,
+                // not hardcoded fixture strings).
+                noOpEventsSuppressed: { container: "events" },
                 // #1199 — prose is a pointer at the default, not a second copy.
                 proseContextIsPointerAtDefault: { field: "context" },
                 // shape of the structured containers a connector reads; #1188 leak bites on memories.