crbro-memory 2.7.2 → 2.9.0

package/dist/server.js

@@ -36,8 +36,11 @@ const semantic_js_1 = require("./search/semantic.js");
 const budget_js_1 = require("./utils/budget.js");
 const secrets_js_1 = require("./engine/secrets.js");
 const backup_js_1 = require("./engine/backup.js");
+const modinstall_js_1 = require("./engine/modinstall.js");
 const triggers_js_1 = require("./engine/triggers.js");
 const ids_js_1 = require("./utils/ids.js");
+const shelf_js_1 = require("./engine/shelf.js");
+const source_js_1 = require("./engine/source.js");
 /** A neuron this size with no summary is worth two lines from whoever is closing the session. */
 const SUMMARY_NUDGE_MIN_ENTRIES = 25;
 /** Listings carry the day, not the millisecond: "2026-09-07" says what "2026-09-07T14:02:11.483Z" says, in a third of the tokens. Full stamps stay on single-entry reads. */
@@ -87,6 +90,35 @@ const THREE_STAGES = 'A new truth that REPLACES an old one → crbro_learn with
     'Something stopped being true, or was never true, and nothing replaces it → crbro_revise ' +
     '(kept in the file, gone from recall, reversible with status active). Something must not exist ' +
     'on disk at all — a credential, personal data, a whole neuron → crbro_forget (quarantine copy first).';
+/**
+ * What to do with a recall's possibly_stale block (shelf life), said once per
+ * answer at the START of `hint` (iteration 2, staleness.md §14): the order to
+ * check comes first, the follow-up writes after it. Each row carries its own
+ * next_step (where to look); this says what to do with the result.
+ */
+const STALE_HINT = 'possibly_stale holds last-known values that may have changed: do not answer with one as current. Check it first ' +
+    '(its next_step says where), then: still true → crbro_revise neuron=<neuron_id> status=verified facts=[entry_id] ' +
+    '(entries=[entry_id] for a decision or pattern); changed → crbro_learn the new value with supersedes=[entry_id]. ' +
+    'If you cannot check, say it may be out of date.';
+/**
+ * The per-row framing of a possibly_stale row (iteration 2). The stored line
+ * comes back as `last_known`, not as `matching_content`, behind a warning and
+ * a concrete next step: open what the line itself names, when it names a
+ * file, path or URL; otherwise look where that kind of value lives, and if
+ * that is not possible, say the value may be out of date.
+ */
+function staleFraming(text, s) {
+    const since = s.last_verified;
+    const warning = s.age_from
+        ? `last known value, not verified since ${since}: past its shelf life, may have changed`
+        : `last known value, unverified for ${s.age_days} days (since ${since}): may have changed`;
+    const named = (0, source_js_1.namedSources)(text);
+    const fallback = `If you cannot check, say this value is from ${since} and may be out of date; do not state it as current.`;
+    const next_step = named.length
+        ? `Before answering, open ${named.join(' / ')} (named in this entry) and answer with what it says now. ${fallback}`
+        : `Before answering, look for the current value where it lives: the project's files or config if you can read them, or the user. ${fallback}`;
+    return { warning, next_step };
+}
 /**
  * The version of CRBRO that is actually running. The manifest carries its own
  * version, but that one stamps the brain FORMAT and has not moved since 1.0.0
@@ -154,6 +186,7 @@ function createServer(shared) {
         instructions: 'CRBRO is this user\'s persistent memory, kept on their own machine. Start every conversation with crbro_boot: it loads what earlier sessions left — protocols to follow, open items, hot topics. ' +
             'Before answering OR ACTING ON anything about the user, their projects, preferences, decisions or past work, call crbro_recall: the answer is usually stored, and making them repeat it is the failure this memory exists to prevent. ' +
             'Recall even when you think you know. Only when the current message itself states the answer does it outrank memory: then use it — a recall that finds nothing does not make it unknown, and a stored value older than what the user just said is the one to update, not to repeat. ' +
+            'A row in a recall\'s possibly_stale is a last-known value that may have changed: before answering with it, check it where it lives (the file it names, the project\'s files or config, or the user) and answer from that; if you cannot check, say it may be out of date — never state it as current. Then crbro_revise status=verified or crbro_learn with supersedes. ' +
             'Acting includes touching one of their systems: before the first command that explores or changes a project of theirs, recall what is already known about it — a stored pattern or map usually holds the very procedure you were about to reconstruct by reading files, and reconstructing it is how you end up doing the steps in the wrong order. ' +
             'Questions about CRBRO itself (version, counts, whether semantic recall is on) are crbro_inspect view=status. Read one entry, not a whole neuron: view=neuron gives an index, entries=[ids] the text. ' +
             'Save with crbro_learn as you go, and close with crbro_consolidate before the conversation ends.',
@@ -212,6 +245,12 @@ function createServer(shared) {
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     }, async (args) => {
         try {
+            // The Claude Code mod (open items above the prompt): installed or
+            // refreshed on its own, once per process, on a short budget that
+            // never fails or holds up the boot. Started first so it runs beside
+            // the brain's own work; its notice is taken only once this boot has
+            // an answer to carry it, so a boot that fails does not lose it.
+            const modNotice = (0, modinstall_js_1.startModOnBoot)();
             const result = await brain.boot();
             // Initialize search engine
             await searchEngine.init();
@@ -333,6 +372,11 @@ function createServer(shared) {
                     'Semantic recall is not installed on this machine: run once npx crbro-memory init (about 500 MB). ' +
                         'Until then recall is keyword-only; keywords at save time still work.';
             }
+            // Said once, the boot after the mod was installed or updated: what
+            // changed on the user's machine and how to undo it.
+            const aviso = await modNotice();
+            if (aviso)
+                response.mod_notice = aviso;
             response.memory_discipline =
                 'Before crbro_learn, crbro_recall: what you are about to save may already exist — then pass ' +
                     'supersedes instead of adding a sibling (two versions of one fact compete on recall as equals). ' +
@@ -348,7 +392,10 @@ function createServer(shared) {
                     'deliberate deferral with its ceiling and revisit trigger. Credentials never go in the brain: ' +
                     'crbro_secret, then record only the NAME. Recall results carry confidence — "weak" means the match ' +
                     'covers little of the question, verify before relying on it — and when two facts disagree, prefer ' +
-                    'the more recent. Lifecycle: supersedes replaces, crbro_revise retires, crbro_forget removes what ' +
+                    'the more recent. possibly_stale in a recall = a last-known value that may have changed: check its ' +
+                    'source before answering with it, or say it may be out of date (then crbro_revise status=verified if it ' +
+                    'holds, crbro_learn supersedes if it changed). A value that can change (version, price, port, host, ' +
+                    'setting, who holds a role) should say where it came from — the file, key, URL or person. Lifecycle: supersedes replaces, crbro_revise retires, crbro_forget removes what ' +
                     'must not exist on disk — each tool describes its own stage. ' +
                     'Call crbro_consolidate before the conversation ends; it logs the session too.';
             // A mature brain outgrew the boot payload: on a 1,145-neuron brain it
@@ -358,7 +405,7 @@ function createServer(shared) {
             // start correctly are kept whole; what grows without bound is shortened
             // and says so, with the call that reads it in full.
             return jsonResult((0, budget_js_1.fitToBudget)(response, {
-                keep: ['protocol_enforcement', 'memory_discipline', 'retired_tools', 'pending_guidance', 'semantic_hint'],
+                keep: ['protocol_enforcement', 'memory_discipline', 'retired_tools', 'pending_guidance', 'semantic_hint', 'mod_notice'],
                 howToGetMore: 'Session summaries were shortened. Read one in full with crbro_inspect view=sessions.',
             }));
         }
@@ -460,6 +507,13 @@ function createServer(shared) {
                     last_consolidation: manifest.last_consolidation,
                     semantic: (0, semantic_js_1.semanticStatus)(),
                     hot_topics_recalculated: hot?.last_recalculated ?? null,
+                    // Shelf life: whether recall splits off possibly_stale, the windows
+                    // in days, and the day this brain started counting (legacy grace).
+                    staleness: {
+                        enabled: (0, shelf_js_1.stalenessEnabled)(),
+                        windows: (0, shelf_js_1.shelfWindows)(),
+                        since: manifest.staleness_since ? dia(manifest.staleness_since) : null,
+                    },
                 });
             }
             if (args.view === 'neuron') {
@@ -491,21 +545,38 @@ function createServer(shared) {
                 const offset = Math.max(args.offset ?? 0, 0);
                 const connections = await synapses.getConnections(neuron.id, args.min_strength);
                 const retired = (id) => neuron.entry_status?.[id]?.status;
+                // Shelf life: the same three facts recall shows, so the index of a
+                // neuron and a recall never disagree about what is old.
+                const vida = (0, shelf_js_1.stalenessContext)((await brain.getManifest()).staleness_since);
+                const rancio = (s) => (s?.stale ? { stale_days: s.age_days } : {});
                 const rows = [];
                 for (const f of neuron.facts || []) {
                     rows.push({ id: f.id || (0, hash_js_1.factId)(f.text), kind: 'fact', text: f.text, added: f.added || '',
                         status: f.status, confidence: f.confidence, keys: f.keys, revision_note: f.revision_note, revised: f.revised,
                         // Only when it says something: 1 is every fact's default (2.7).
-                        ...((f.confirmations ?? 1) > 1 ? { confirmations: f.confirmations } : {}) });
+                        ...((f.confirmations ?? 1) > 1 ? { confirmations: f.confirmations } : {}),
+                        ...(f.verified ? { verified: f.verified } : {}),
+                        ...(f.shelf_life ? { shelf_life: f.shelf_life } : {}),
+                        ...(vida && neuron.type !== 'protocol' ? rancio((0, shelf_js_1.factStaleness)(f, vida)) : {}) });
                 }
+                const entrada = (kind, text, id) => {
+                    const v = neuron.entry_verified?.[id];
+                    const retirada = !!neuron.entry_status?.[id];
+                    return {
+                        ...(v ? { verified: v } : {}),
+                        ...(vida && !retirada && neuron.type !== 'protocol' ? rancio((0, shelf_js_1.entryStaleness)(neuron, kind, text, vida)) : {}),
+                    };
+                };
                 for (const d of neuron.decisions || []) {
                     const id = d.id || (0, ops_js_1.entryId)(d.text);
-                    rows.push({ id, kind: 'decision', text: d.text, added: d.date || '', rationale: d.rationale, status: retired(id), revised: neuron.entry_status?.[id]?.revised, revision_note: neuron.entry_status?.[id]?.note });
+                    rows.push({ id, kind: 'decision', text: d.text, added: d.date || '', rationale: d.rationale, status: retired(id), revised: neuron.entry_status?.[id]?.revised, revision_note: neuron.entry_status?.[id]?.note,
+                        ...entrada('decision', d.text, (0, ops_js_1.entryId)(d.text)) });
                 }
                 const sidecar = (kind, list) => {
                     for (const t of list || []) {
                         const id = (0, ops_js_1.entryId)(t);
-                        rows.push({ id, kind, text: t, added: neuron.entry_dates?.[id] || '', status: retired(id), revised: neuron.entry_status?.[id]?.revised, revision_note: neuron.entry_status?.[id]?.note });
+                        rows.push({ id, kind, text: t, added: neuron.entry_dates?.[id] || '', status: retired(id), revised: neuron.entry_status?.[id]?.revised, revision_note: neuron.entry_status?.[id]?.note,
+                            ...entrada(kind, t, id) });
                     }
                 };
                 sidecar('pattern', neuron.patterns);
@@ -585,6 +656,9 @@ function createServer(shared) {
                         preview: r.text.length > PREVIEW ? `${r.text.slice(0, PREVIEW).trimEnd()}…` : r.text,
                         chars: r.text.length,
                         ...(r.confirmations ? { confirmations: r.confirmations } : {}),
+                        ...(r.verified ? { verified: dia(r.verified) } : {}),
+                        ...(r.shelf_life ? { shelf_life: r.shelf_life } : {}),
+                        ...(r.stale_days !== undefined ? { stale_days: r.stale_days } : {}),
                         ...(isRetired(r.status) ? { status: r.status, ...(r.revised ? { revised: dia(r.revised) } : {}), ...(r.revision_note ? { retired_note: r.revision_note } : {}) } : {}),
                     })),
                     entries_pagination: {
@@ -665,7 +739,7 @@ function createServer(shared) {
     // ═══════════════════════════════════════════════════════════════
     server.registerTool('crbro_learn', {
         title: 'Learn something',
-        description: 'Write: store a fact, decision, pattern, preference, error or debt on a topic; the neuron is created if missing (or pass neuron_id). Stage 1 of the lifecycle: a new truth that REPLACES an old one → crbro_learn with supersedes (one call does both); to retire with no replacement use crbro_revise; to delete from disk use crbro_forget. crbro_recall first — it may already exist. The same fact text again is not duplicated: keywords merge (or keywords_replace), a changed confidence applies (updated_in_place) and another session repeating it raises confirmations, returned; text matching a retired fact or entry is refused with skipped_retired. Decisions always append; preferences never leave this machine. Credentials are replaced with a marker and listed in redacted — crbro_secret them, record only the name. Returns neuron_id, action, superseded count, near_duplicates (stored anyway; retire the old telling), supersedes_unmatched (still live) and totals.',
+        description: 'Write: store a fact, decision, pattern, preference, error or debt on a topic; the neuron is created if missing (or pass neuron_id). A value that can change names its source (file, key, URL, person). Stage 1 of the lifecycle: a new truth that REPLACES an old one → crbro_learn with supersedes; retire with no replacement → crbro_revise; delete from disk → crbro_forget. crbro_recall first — it may already exist. The same fact text again is not duplicated: keywords merge, a changed confidence or shelf_life applies (updated_in_place), a bare repeat counts as re-verified and another session repeating it raises confirmations; text matching a retired entry is refused with skipped_retired. Decisions always append; preferences never leave this machine. Credentials become a marker listed in redacted: crbro_secret them, keep only the name. Returns neuron_id, action, the fact\'s shelf_life, near_duplicates (stored anyway; retire the old telling) and supersedes_unmatched (still live).',
         inputSchema: {
             // Optional since 2.0.3, and the reason is measured: the description
             // told callers that neuron_id "skips name matching entirely", the
@@ -676,7 +750,7 @@ function createServer(shared) {
             // message that says what to pass.
             topic: zod_1.z.string().optional().describe('Topic name, e.g. "OctoChat", "Firebase", "SEO Strategy". Required UNLESS you pass neuron_id, in which case the topic is taken from that neuron.'),
             type: zod_1.z.enum(['fact', 'decision', 'pattern', 'preference', 'error', 'debt']).describe('error = a mistake plus its correction, in one entry. debt = a deliberate deferral: what was NOT done on purpose, its ceiling, and the revisit condition, e.g. "DEFERRED: protecting the PDFs. CEILING: anyone can download them without signing up. REVISIT WHEN: the signup flow works."'),
-            content: zod_1.z.string().describe('The knowledge itself. Dense and self-contained: it is recalled without this conversation as context.'),
+            content: zod_1.z.string().describe('The knowledge itself. Dense and self-contained: it is recalled without this conversation as context. For a value that can change (a version, price, port, host, setting, who holds a role), say where it came from — the file, config key, URL or person — so a later check knows where to look.'),
             confidence: zod_1.z.number().min(0).max(1).optional().describe('0.0-1.0, default 1.0. Facts only. On an exact-duplicate active fact the stored confidence is updated to this value (updated_in_place:true).'),
             domain: zod_1.z.string().optional().describe('Domain, e.g. "proyectos-web". Applied when the neuron is created; on an existing neuron it only replaces the default "general" (crbro_revise domain replaces it unconditionally).'),
             rationale: zod_1.z.string().optional().describe('Why the decision was taken. Stored and indexed with it; ignored for other types.'),
@@ -684,6 +758,7 @@ function createServer(shared) {
             supersedes: zod_1.z.array(zod_1.z.string()).optional().describe('Facts this one replaces: their ids or exact text. They leave recall but stay in the file. Unmatched targets are reported and stay live.'),
             keywords: zod_1.z.array(zod_1.z.string()).optional().describe('Facts only, and expected on every fact: 2-5 words a future question may use that the text does not contain — synonyms, the other language, the generic name of the product named. Indexed with the fact, never shown; the largest measured lever on recall. Without them the fact is stored and the answer carries keywords_missing. The same text again with new keywords merges them.'),
             keywords_replace: zod_1.z.boolean().optional().describe('When the exact fact text already exists, replace its stored keywords with `keywords` instead of merging (default false). Teammates in a shared space only ever receive the union.'),
+            shelf_life: zod_1.z.enum(shelf_js_1.SHELF_LIVES).optional().describe('Facts only: how fast this value goes stale. volatile = versions, prices, ports, hosts, paths, config, who holds a role; durable = rarely moves; permanent = history that cannot change; normal otherwise. Omitted: inferred from the text, and returned.'),
         },
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
     }, async (args) => {
@@ -711,6 +786,7 @@ function createServer(shared) {
                 supersedes: args.supersedes,
                 keys: args.keywords,
                 keysReplace: args.keywords_replace,
+                shelfLife: args.type === 'fact' ? args.shelf_life : undefined,
             });
             // Indexing happens inside cortex.learn, through the indexer hook.
             if (result.action === 'skipped_retired' && result.skipped_retired) {
@@ -729,6 +805,13 @@ function createServer(shared) {
             if (!result.neuron) {
                 return textResult(`No neuron matched "${topic}" and none was created.`);
             }
+            // Lengthening an explicit shelf life does not hold on a shared neuron:
+            // the team merge keeps the most volatile value, and the older op is
+            // still in the append-only log, so the next sync brings it back.
+            const sharedIn = result.shelf_lengthened ? (await (0, space_js_1.sharedMap)(brain))[result.neuron.id] : undefined;
+            const shelfSharedWarning = sharedIn
+                ? `"${result.neuron.id}" is shared in space "${sharedIn}": a longer shelf_life is local only — the next sync restores the more volatile value from the shared log.`
+                : undefined;
             const keywordsMissing = args.type === 'fact' && result.action !== 'skipped' &&
                 !(args.keywords && args.keywords.some(k => typeof k === 'string' && k.trim().length > 0));
             return jsonResult({
@@ -772,6 +855,15 @@ function createServer(shared) {
                         'question may use that the text lacks (synonyms, the other language, the generic name of the product): ' +
                         'they merge into this fact instead of adding a new one.'
                     : undefined,
+                // Shelf life, facts only: the class that applies, and when it was not
+                // given, that it was inferred and by which rule, so a model that
+                // disagrees can say otherwise in the next call.
+                shelf_life: result.shelf?.shelf_life,
+                shelf_inferred: result.shelf?.inferred ? true : undefined,
+                shelf_reason: result.shelf?.inferred ? result.shelf.reason : undefined,
+                // The same line learned again, and nothing else: its shelf-life clock restarts now.
+                reconfirmed: result.reconfirmed || undefined,
+                shared_warning: shelfSharedWarning,
                 total_facts: result.neuron.facts.length,
                 total_decisions: result.neuron.decisions.length,
                 total_patterns: result.neuron.patterns.length,
@@ -794,13 +886,13 @@ function createServer(shared) {
     // ═══════════════════════════════════════════════════════════════
     server.registerTool('crbro_recall', {
         title: 'Recall',
-        description: 'Read-only search of everything saved in earlier sessions — facts, decisions, patterns, preferences, errors, debts and maps. Call it BEFORE answering anything about the user, their projects, preferences, decisions or past work: the answer is usually stored, and making them repeat it is the failure this memory exists to prevent. Also before crbro_learn, to supersede rather than duplicate. One result per neuron: the best matching entry with entry_id (read it whole: crbro_inspect view=neuron entries=[id]), matched_kind, matched_added, a confidence label (weak = little of the question covered; verify) and also_matched previews. Retired entries never surface. Lines not the user\'s own carry origin, also_matched too: team:<space> (team if unshared) with self-declared by, or miner. Five results by default; matched_neurons counts every hit. If nothing matches, retry with 2-4 phrasings in queries or fewer, rarer words. has_map:true: read the system map with crbro_map before touching that system.',
+        description: 'Read-only search of everything saved in earlier sessions — facts, decisions, patterns, preferences, errors, debts and maps. Call it BEFORE answering anything about the user, their projects, preferences, decisions or past work: the answer is usually stored, and making them repeat it is the failure this memory exists to prevent. One result per neuron: the best matching entry with entry_id (read it whole: crbro_inspect view=neuron entries=[id]), matched_kind, matched_added, a confidence label (weak = little of the question covered; verify) and also_matched previews. Lines not the user\'s own carry origin, also_matched too: team:<space> (team if unshared) with self-declared by, or miner. Rows past their shelf life move to possibly_stale as last_known with a next_step: check before answering with one, or say it may be out of date. If nothing matches, retry with 2-4 phrasings in queries or fewer, rarer words. has_map:true: read the system map with crbro_map before touching that system.',
         inputSchema: {
             query: zod_1.z.string().describe('What to look for, e.g. "Firebase authentication setup". Fewer, distinctive terms beat full sentences.'),
             queries: zod_1.z.array(zod_1.z.string()).optional().describe('Alternative phrasings of the same question, searched together with query and fused by rank. Use synonyms, the other language and the concrete product name; 2-4 is plenty.'),
             domain: zod_1.z.string().optional().describe('Only neurons in this domain (exact match, e.g. "proyectos-web"). Day logs have no domain: sessions_matched is listed regardless.'),
             limit: zod_1.z.number().int().positive().optional().describe('Max neurons returned (default 5, ranked; ask for more only when the top five did not answer).'),
-            since: zod_1.z.string().optional().describe('Only entries dated on or after this: a day ("2026-09-01") or a span back from today ("7d", "2w", "3m"). For "what changed lately" and to keep an old telling out. Undated entries cannot prove they are recent: they are left out and counted in undated_skipped.'),
+            since: zod_1.z.string().optional().describe('Only entries recorded on or after this: a day ("2026-09-01") or a span back from today ("7d", "2w", "3m"). For "what changed lately" and to keep an old telling out. A later verification does not make an old entry new. Undated entries cannot prove they are recent: they are left out and counted in undated_skipped.'),
             kind: zod_1.z.array(zod_1.z.enum(index_js_1.RECALL_KINDS)).optional().describe('Only these entry kinds, e.g. ["error"] for past mistakes before repeating one, ["decision"] for what was agreed and why, ["debt"] for what was deferred. Day logs are left out when set.'),
         },
         outputSchema: {
@@ -814,11 +906,18 @@ function createServer(shared) {
                 matched_terms: zod_1.z.number().optional(), query_terms: zod_1.z.number().optional(),
                 confidence: zod_1.z.enum(['strong', 'weak']).optional(),
                 entry_id: zod_1.z.string().optional(),
+                rank: zod_1.z.number().optional().describe('Position in the ranking, set when some row moved to possibly_stale'),
                 origin: zod_1.z.string().optional(), by: zod_1.z.string().optional(),
                 content_truncated: zod_1.z.boolean().optional(), content_chars: zod_1.z.number().optional(),
-                also_matched: zod_1.z.array(zod_1.z.object({ entry_id: zod_1.z.string().optional(), kind: zod_1.z.string(), added: zod_1.z.string(), preview: zod_1.z.string(), chars: zod_1.z.number(), origin: zod_1.z.string().optional(), by: zod_1.z.string().optional() }).loose()).optional(),
+                also_matched: zod_1.z.array(zod_1.z.object({ entry_id: zod_1.z.string().optional(), kind: zod_1.z.string(), added: zod_1.z.string(), preview: zod_1.z.string(), chars: zod_1.z.number(), origin: zod_1.z.string().optional(), by: zod_1.z.string().optional(), stale_days: zod_1.z.number().optional() }).loose()).optional(),
             }).loose()),
-            returned: zod_1.z.number().optional(),
+            stale_warning: zod_1.z.string().optional().describe('Set, first, when some row moved to possibly_stale: do not answer with those as current'),
+            possibly_stale: zod_1.z.array(zod_1.z.object({
+                warning: zod_1.z.string(), next_step: zod_1.z.string(), last_known: zod_1.z.string(), neuron_id: zod_1.z.string(),
+                age_days: zod_1.z.number(), last_verified: zod_1.z.string(), shelf_life: zod_1.z.string(), shelf_inferred: zod_1.z.boolean(),
+            }).loose()).optional().describe('Rows whose best entry is past its shelf life since last verified: warning, next_step (what to check before answering), the entry as last_known instead of matching_content, then the rest of a results row plus age_days, last_verified, shelf_life, shelf_inferred'),
+            possibly_stale_count: zod_1.z.number().optional(),
+            returned: zod_1.z.number().optional().describe('Rows that came back: results plus possibly_stale'),
             matched_neurons: zod_1.z.number().optional().describe('Neurons with any hit before limit; total_results is what came back'),
             has_more: zod_1.z.boolean().optional(),
             sessions_matched: zod_1.z.array(zod_1.z.object({}).loose()).optional(),
@@ -862,36 +961,94 @@ function createServer(shared) {
                     ...(r.also_matched ? { also_matched: r.also_matched.map(a => ({ ...a, added: dia(a.added) })) } : {}),
                 };
             });
-            const sobran = matched_neurons - results.length;
+            // Shelf life: partition, not penalty. The ranking above already chose
+            // these rows exactly as before; a row whose WINNING entry is past its
+            // shelf life since last verified moves whole to possibly_stale, in
+            // rank order. No backfill (the cost stays bounded by limit, and "what
+            // does memory say about X" never silently becomes a weaker line about
+            // something else), and never re-headed with an also_matched line.
+            // The internal `staleness` field leaves every row here.
+            const actuales = [];
+            const rancios = [];
+            // When anything moves, every row keeps its rank: results[0] is then
+            // not necessarily the best match, and the agent has to be able to see it.
+            const algunoRancio = rows.some(r => r.staleness?.stale);
+            let mejorMovido = false;
+            for (const [i, row] of rows.entries()) {
+                const { staleness, ...resto } = row;
+                if (algunoRancio)
+                    resto.rank = i + 1;
+                if (staleness?.stale) {
+                    if (i === 0)
+                        mejorMovido = true;
+                    // Iteration 2: the old line is not served as ordinary content. Its
+                    // warning and next step come first, then the line as last_known.
+                    const { matching_content, neuron_id, name, entry_id, rank, ...demas } = resto;
+                    rancios.push({
+                        ...staleFraming(matching_content, staleness),
+                        last_known: matching_content,
+                        neuron_id, name,
+                        ...(entry_id !== undefined ? { entry_id } : {}),
+                        ...(rank !== undefined ? { rank } : {}),
+                        ...demas,
+                        age_days: staleness.age_days,
+                        last_verified: staleness.last_verified,
+                        shelf_life: staleness.shelf_life,
+                        shelf_inferred: staleness.shelf_inferred,
+                        ...(staleness.age_from ? { age_counted_from: staleness.age_from } : {}),
+                    });
+                }
+                else {
+                    actuales.push(resto);
+                }
+            }
+            const servidos = actuales.length + rancios.length;
+            const sobran = matched_neurons - servidos;
+            // Iteration 2: when anything moved, the answer OPENS with a short
+            // warning, before query and results, so it is read before the rows.
+            const menorEdad = rancios.length ? Math.min(...rancios.map(r => r.age_days)) : 0;
+            const uno = rancios.length === 1;
+            const avisoRancio = rancios.length
+                ? (uno
+                    ? `1 matching row is in possibly_stale${mejorMovido ? ', the best match' : ''}: a last-known value, unchecked for ${menorEdad} days, that may have changed. Do not answer with it as current. Check it first (its next_step says where)`
+                    : `${rancios.length} matching rows are in possibly_stale${mejorMovido ? ', the best match among them' : ''}: last-known values, unchecked for ${menorEdad}+ days, that may have changed. Do not answer with one as current. Check it first (each row's next_step says where)`) +
+                    '; if you cannot, say it may be out of date, even in a short answer.'
+                : '';
             const payload = {
+                ...(avisoRancio ? { stale_warning: avisoRancio } : {}),
                 query: args.query,
-                // total_results is what came back (capped by limit); matched_neurons is
-                // how many neurons had a hit at all, so five never reads as "only five".
-                total_results: results.length,
-                returned: results.length,
+                // total_results is what came back as current (capped by limit);
+                // returned adds possibly_stale; matched_neurons is how many neurons
+                // had a hit at all, so five never reads as "only five".
+                total_results: actuales.length,
+                returned: servidos,
                 matched_neurons,
                 has_more: sobran > 0,
                 // The filter as it was understood ("30d" becomes a day), so a narrowed
                 // answer never reads as the whole brain.
                 ...(filtrado ? { filters: { ...(since ? { since } : {}), ...(kinds ? { kind: kinds } : {}) } } : {}),
                 ...(since ? { undated_skipped: sinFecha } : {}),
-                results: rows,
+                results: actuales,
+                ...(rancios.length ? { possibly_stale: rancios, possibly_stale_count: rancios.length } : {}),
                 // The diary, searched since 2.2: day logs whose summary mentions the
                 // question, in a list of their own so narrative never outranks a fact.
                 // sessions_total: how many days had a hit; three shown never reads as three.
                 ...(sessions.length ? { sessions_matched: sessions.map(s => ({ ...s, date: dia(s.date) })), sessions_total } : {}),
-                hint: (results.length === 0
-                    ? (sessions.length
-                        // A day mentions it and no fact does: point at the day, not at rephrasing.
-                        ? `No stored fact matched; ${sessions_total} day log${sessions_total === 1 ? '' : 's'} mention it (sessions_matched): read one whole with crbro_inspect view=sessions session=<session_id>. If it is a fact worth keeping, save it with crbro_learn.`
-                        : (filtrado
-                            ? 'Nothing matched inside the filter. Drop since/kind and ask again before concluding it is not stored.'
-                            : 'Nothing matched. Try fewer, more distinctive words - names, ids, filenames - rather than a full sentence.'))
-                    : 'weak: verify. Newer wins on conflict. entry_id → crbro_inspect view=neuron entries=[id]. has_map → crbro_map first.'
-                        + (sobran > 0 ? ` ${sobran} more neuron${sobran === 1 ? '' : 's'} matched: raise limit or narrow the query.` : '')
-                        + (cortados > 0 ? ' content_truncated → read the entry by entry_id.' : '')
-                        + (sessions.length ? ' sessions_matched: day logs that mention it; read one whole with crbro_inspect view=sessions session=<session_id>.' : ''))
-                    + (filtrado && results.length > 0 ? ' Filtered: entries outside since/kind were not searched.' : '')
+                hint: (rancios.length && !actuales.length ? 'Nothing current matched; the rows that did are in possibly_stale. '
+                    : mejorMovido ? 'The best match (rank 1) moved to possibly_stale; results holds lower-ranked rows that may be about something else. ' : '') +
+                    (rancios.length ? `${STALE_HINT} ` : '') +
+                    (servidos === 0
+                        ? (sessions.length
+                            // A day mentions it and no fact does: point at the day, not at rephrasing.
+                            ? `No stored fact matched; ${sessions_total} day log${sessions_total === 1 ? '' : 's'} mention it (sessions_matched): read one whole with crbro_inspect view=sessions session=<session_id>. If it is a fact worth keeping, save it with crbro_learn.`
+                            : (filtrado
+                                ? 'Nothing matched inside the filter. Drop since/kind and ask again before concluding it is not stored.'
+                                : 'Nothing matched. Try fewer, more distinctive words - names, ids, filenames - rather than a full sentence.'))
+                        : 'weak: verify. Newer wins on conflict. entry_id → crbro_inspect view=neuron entries=[id]. has_map → crbro_map first.'
+                            + (sobran > 0 ? ` ${sobran} more neuron${sobran === 1 ? '' : 's'} matched: raise limit or narrow the query.` : '')
+                            + (cortados > 0 ? ' content_truncated → read the entry by entry_id.' : '')
+                            + (sessions.length ? ' sessions_matched: day logs that mention it; read one whole with crbro_inspect view=sessions session=<session_id>.' : ''))
+                    + (filtrado && servidos > 0 ? ' Filtered: entries outside since/kind were not searched.' : '')
                     + (sinFecha > 0 ? ` ${sinFecha} matching entr${sinFecha === 1 ? 'y has' : 'ies have'} no date and were left out by since (crbro_maintenance backfill_dates dates the ones that state a day).` : '')
                     + (sessions_total > sessions.length ? ` ${sessions_total - sessions.length} more day${sessions_total - sessions.length === 1 ? '' : 's'} mention it: narrow the query.` : ''),
             };
@@ -916,9 +1073,9 @@ function createServer(shared) {
     const reviseSchema = zod_1.z.object({
         neuron: zod_1.z.string().describe('Neuron id or name holding what to revise, e.g. "project_octochat".'),
         facts: zod_1.z.array(zod_1.z.string()).optional().describe('Facts to move to `status`: their ids (from crbro_recall) or exact text (trimmed, case-insensitive). For superseded/retracted only active facts match; for active only retired ones do.'),
-        entries: zod_1.z.array(zod_1.z.string()).optional().describe('Exact texts of decisions, patterns, errors or debts to move to `status`. Retired entries stay in the file (entry_status) but leave recall like a superseded fact.'),
-        status: zod_1.z.enum(['superseded', 'retracted', 'active']).optional().describe('superseded = a newer truth exists (default); retracted = it was never true; active = reactivate a retired fact or entry. Reactivation is local: on a shared neuron the next sync re-applies the retirement (the response carries shared_warning).'),
-        note: zod_1.z.string().optional().describe('Why. Stored as revision_note on facts and entry_status.note on entries. The next reader will wonder.'),
+        entries: zod_1.z.array(zod_1.z.string()).optional().describe('Exact texts of decisions, patterns, errors or debts to move to `status`. Retired entries stay in the file (entry_status) but leave recall like a superseded fact. With status verified: decisions or patterns, by exact text or entry id.'),
+        status: zod_1.z.enum(['superseded', 'retracted', 'active', 'verified']).optional().describe('superseded = a newer truth exists (default); retracted = it was never true; active = reactivate a retired fact or entry (local only on a shared neuron: the next sync re-applies the retirement; shared_warning says so). verified = you checked these active facts, or live decisions or patterns, against their source and they still hold: their last verification becomes now and they leave possibly_stale. A retired target is not verifiable: it comes back in unmatched and retired_targets.'),
+        note: zod_1.z.string().optional().describe('Why. Stored as revision_note on facts and entry_status.note on entries. The next reader will wonder. Ignored with status verified.'),
         summary: zod_1.z.string().optional().describe('Replace the neuron summary. Credentials are redacted and listed in redacted.'),
         domain: zod_1.z.string().optional().describe('Replace the neuron domain unconditionally, e.g. "proyectos-web".'),
         tags: zod_1.z.array(zod_1.z.string()).optional().describe('Replace the WHOLE tag list (trimmed, deduplicated). On protocol neurons re-send the priority: and source: tags or they are gone.'),
@@ -938,7 +1095,7 @@ function createServer(shared) {
     });
     server.registerTool('crbro_revise', {
         title: 'Revise a neuron',
-        description: 'Write: change what a neuron says without deleting anything. Stage 2 of the lifecycle: something stopped being true, or was never true, and nothing replaces it → crbro_revise (kept in the file, gone from recall, reversible with status active). If a replacement exists, crbro_learn with supersedes does both; for what must not exist on disk use crbro_forget. facts retires facts by id or exact text; entries retires decisions, patterns, errors and debts by exact text; status active reactivates either (local only on a shared neuron: the next sync re-applies the retirement, shared_warning says so). summary, domain, tags and name edit metadata in the same call (tags replaces the whole list; the id never changes). move_to splits: the listed entries go to another neuron with their dates. Anything in unmatched is STILL LIVE — fix and re-run.',
+        description: 'Write: change what a neuron says without deleting anything. Stage 2 of the lifecycle: something stopped being true, or was never true, and nothing replaces it → crbro_revise (kept in the file, gone from recall, reversible with status active). If a replacement exists, crbro_learn with supersedes does both; for what must not exist on disk use crbro_forget. facts retires facts by id or exact text; entries retires decisions, patterns, errors and debts by exact text; status active reactivates either (local only on a shared neuron: the next sync re-applies the retirement, shared_warning says so); status verified records that a fact, decision or pattern was checked against its source and still holds. summary, domain, tags and name edit metadata in the same call (tags replaces the whole list; the id never changes). move_to splits: the listed entries go to another neuron with their dates. Anything in unmatched is STILL LIVE — fix and re-run.',
         inputSchema: reviseSchema,
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     }, async (args) => {
@@ -977,6 +1134,42 @@ function createServer(shared) {
                         : 'Nothing matched, nothing moved. Pass entry ids from crbro_inspect view=neuron, or the exact text.',
                 });
             }
+            // ── status verified: reconfirm, do not retire (shelf life) ──
+            if (status === 'verified') {
+                const v = (args.facts?.length || args.entries?.length)
+                    ? await cortex.verify(target.id, { facts: args.facts, entries: args.entries })
+                    : { verified: [], unmatched: [], retired: [] };
+                let cambiados = [];
+                let tachados = [];
+                const metaV = { summary: args.summary, domain: args.domain, tags: args.tags, name: args.name };
+                if (Object.values(metaV).some(x => x !== undefined)) {
+                    const r = await cortex.setMeta(target.id, metaV);
+                    cambiados = r.changed;
+                    tachados = r.redacted;
+                }
+                const n = v.verified.length;
+                const partes = [];
+                if (n > 0)
+                    partes.push(`${n} entr${n === 1 ? 'y' : 'ies'} verified: last checked now, shelf-life clock restarted`);
+                if (cambiados.length > 0)
+                    partes.push(`${cambiados.join(', ')} updated`);
+                return jsonResult({
+                    neuron_id: target.id,
+                    status,
+                    verified: v.verified,
+                    unmatched: v.unmatched.length > 0 ? v.unmatched : undefined,
+                    retired_targets: v.retired.length > 0 ? v.retired : undefined,
+                    changed: cambiados,
+                    redacted: tachados.length > 0 ? tachados : undefined,
+                    message: partes.length > 0
+                        ? `${partes.join('; ')} in "${target.name}".` +
+                            (v.unmatched.length > 0 ? ` WARNING: ${v.unmatched.length} target(s) matched no active fact or live decision/pattern and were not verified.` : '') +
+                            (v.retired.length > 0 ? ' A retired line is not verifiable: if it holds again, reactivate it with status active first.' : '')
+                        : (v.retired.length > 0
+                            ? 'Nothing verified: the targets are retired. If one holds again, reactivate it with status active first, then verify.'
+                            : 'Nothing verified. Pass the fact id (entry_id from crbro_recall) or exact text in facts; decisions and patterns go in entries. Preferences, errors and debts never go stale.'),
+                });
+            }
             let revisedFacts = 0;
             let revisedEntries = 0;
             const unmatched = [];