@tpsdev-ai/flair 0.51.0 → 0.51.2

package/dist/lib/daemon-liveness.js

@@ -0,0 +1,207 @@
+/**
+ * daemon-liveness.ts — the five-state liveness machine for a local Flair
+ * (Harper) daemon (flair#1454).
+ *
+ * The defect this replaces: `flair stop` decided "not running" from a single
+ * `lsof -ti :<port>` whose `catch` converted "lsof unavailable" into "nothing
+ * is listening" — absence rendered as a definite negative. `flair start` then
+ * "succeeded" over the live daemon it had just failed to see, and a
+ * `stop; start` wrapper (a systemd `Type=forking` unit's `ExecStop`, say)
+ * produced a second daemon while the first kept running.
+ *
+ * The fix is a classifier with FIVE states, not a boolean:
+ *
+ *   RUNNING       identity-verified pid alive  +  health 200
+ *   NOT_RUNNING   no pidfile, or verified dead  +  port refused
+ *   WEDGED        identity-VERIFIED pid alive   +  not serving   -> stop ACTS
+ *   DISAGREEMENT  evidence conflicts, identity NOT verified       -> stop REFUSES
+ *   UNKNOWN       insufficient evidence to classify               -> stop REFUSES
+ *
+ * THE INVARIANT (the whole design): WEDGED is reachable ONLY when the pidfile
+ * identity has been VERIFIED. The same physical evidence with an unverified
+ * identity lands in DISAGREEMENT. This is encoded structurally — the classifier
+ * takes the identity-check RESULT as an input, and there is no code path to
+ * WEDGED that bypasses it. Killing a wedged daemon is recovery only when we
+ * have proven the pid is ours; without that proof it is a recycled-PID gamble
+ * and the machine refuses.
+ *
+ * Identity is carried by a sidecar (`<dataDir>/flair-daemon.json`) that flair
+ * writes at spawn — `{ pid, startTimeMs, port, flairVersion }` — because
+ * `hdb.pid` is written by the Harper process itself and flair does not own its
+ * format. Verification = hdb.pid's pid matches the sidecar pid AND the live
+ * process's start time matches the sidecar's startTimeMs (±2s).
+ *
+ * This module is PURE: it classifies and parses, and never touches the
+ * filesystem, the network, or a process. The adapters that do (O_NOFOLLOW
+ * reads, `kill(pid, 0)`, the health probe, the start-time readers) live in
+ * `src/cli.ts`, so every branch here is unit-testable without a daemon.
+ */
+/**
+ * Classify the gathered evidence into one of the five states.
+ *
+ * The WEDGED gate is the first branch and the only one that can return WEDGED:
+ * it requires `identity.kind === "verified"` AND `pidLiveness.kind === "alive"`.
+ * Every other "alive" pid — unverified identity, or EPERM — is DISAGREEMENT.
+ */
+export function classifyDaemonState(ev, ctx) {
+    if (ev.dataDirUnsafe !== null) {
+        return { state: "UNKNOWN", detail: ev.dataDirUnsafe };
+    }
+    if (ev.pidfile.kind === "unreadable") {
+        return { state: "UNKNOWN", detail: ev.pidfile.reason };
+    }
+    const pid = ev.pidfile.kind === "present" ? ev.pidfile.pid : null;
+    const liveness = ev.pidLiveness;
+    // THE INVARIANT: WEDGED is reachable only through a VERIFIED identity.
+    if (ev.identity.kind === "verified" && liveness?.kind === "alive") {
+        if (ev.health.kind === "ok") {
+            return { state: "RUNNING", pid: ev.identity.pid };
+        }
+        return { state: "WEDGED", pid: ev.identity.pid };
+    }
+    // No live pid recorded (absent, or the recorded pid is gone).
+    if (pid === null || liveness?.kind === "gone") {
+        if (ev.health.kind === "refused") {
+            return { state: "NOT_RUNNING" };
+        }
+        if (ev.health.kind === "ok") {
+            return {
+                state: "DISAGREEMENT",
+                detail: pid === null
+                    ? `a process is serving port ${ctx.port}, but no pid is recorded under ${ctx.dataDir}`
+                    : `a process is serving port ${ctx.port}, but the recorded pid ${pid} is not alive`,
+            };
+        }
+        return {
+            state: "UNKNOWN",
+            detail: `could not determine whether Flair is running: ` +
+                `${pid === null ? "no pid is recorded" : `recorded pid ${pid} is not alive`} ` +
+                `and the health check on port ${ctx.port} did not respond`,
+        };
+    }
+    // EPERM — the recorded pid exists but belongs to another user.
+    if (liveness?.kind === "eperm") {
+        return {
+            state: "DISAGREEMENT",
+            detail: `the recorded pid ${pid} exists but belongs to another user — refusing to act on it`,
+        };
+    }
+    // Alive, but identity NOT verified — the WEDGED shape without the proof.
+    if (liveness?.kind === "alive") {
+        const reason = ev.identity.kind === "unverified" ? ev.identity.reason : "no identity sidecar";
+        return {
+            state: "DISAGREEMENT",
+            detail: `the recorded pid ${pid} is alive, but its identity could not be verified (${reason}) — refusing to act on it`,
+        };
+    }
+    return { state: "UNKNOWN", detail: "could not determine whether Flair is running" };
+}
+/**
+ * Verify the pidfile identity against the sidecar. Pure — `readStartTime` is
+ * injected so the live-process read (the only non-deterministic part) stays in
+ * the adapter layer.
+ *
+ * Verified requires ALL of: a pidfile pid, a readable sidecar, matching pids,
+ * a readable live start time, and a start time within `toleranceMs` (±2s).
+ * Any shortfall is `unverified` (or `none` when there is nothing to check).
+ */
+export function verifyIdentity(input) {
+    const tolerance = input.toleranceMs ?? 2000;
+    if (input.pidfilePid === null) {
+        return { kind: "none" };
+    }
+    if (input.sidecar.kind === "absent") {
+        return { kind: "none" };
+    }
+    if (input.sidecar.kind === "unreadable") {
+        return { kind: "unverified", reason: input.sidecar.reason };
+    }
+    if (input.pidfilePid !== input.sidecar.pid) {
+        return {
+            kind: "unverified",
+            reason: `hdb.pid names pid ${input.pidfilePid} but the sidecar records pid ${input.sidecar.pid}`,
+        };
+    }
+    const actual = input.readStartTime(input.pidfilePid);
+    if (actual === null) {
+        return { kind: "unverified", reason: `could not read the start time of pid ${input.pidfilePid}` };
+    }
+    if (!isStartTimeMatch(actual, input.sidecar.startTimeMs, tolerance)) {
+        return {
+            kind: "unverified",
+            reason: `pid ${input.pidfilePid} started at ${actual}ms but the sidecar records ${input.sidecar.startTimeMs}ms`,
+        };
+    }
+    return { kind: "verified", pid: input.pidfilePid };
+}
+/** `|actual - recorded| <= tolerance`. */
+export function isStartTimeMatch(actualMs, recordedMs, toleranceMs = 2000) {
+    return Math.abs(actualMs - recordedMs) <= toleranceMs;
+}
+/**
+ * Parse `/proc/<pid>/stat` field 22 (starttime, in clock ticks).
+ *
+ * Field 2 (comm) is parenthesised and may itself contain spaces and `)`
+ * characters, so the split is on the LAST `)` — not the first space, which is
+ * the classic bug that mangles any process whose comm has a space in it.
+ * Returns the raw tick count; the ticks→epoch conversion (which needs boot
+ * time and CLK_TCK) lives in the adapter.
+ */
+export function parseProcStatStartTime(stat) {
+    const closeParen = stat.lastIndexOf(")");
+    if (closeParen < 0)
+        return null;
+    const rest = stat.slice(closeParen + 1).trim().split(/\s+/);
+    // rest[0] is field 3 (state); field 22 (starttime) is therefore rest[19].
+    const starttime = Number(rest[19]);
+    return Number.isFinite(starttime) ? starttime : null;
+}
+/**
+ * Convert a `/proc/<pid>/stat` starttime (clock ticks since boot) to epoch ms,
+ * given the system uptime in seconds and the current wall clock. Pure so the
+ * arithmetic is testable without a live process.
+ */
+export function procStartTimeToEpochMs(starttimeTicks, uptimeSeconds, nowMs, clkTck = 100) {
+    const bootTimeMs = nowMs - uptimeSeconds * 1000;
+    return bootTimeMs + (starttimeTicks / clkTck) * 1000;
+}
+/**
+ * Parse `ps -o lstart= -p <pid>` output ("Sat Aug 29 15:03:22 2026") to epoch
+ * ms. Returns null when the output is empty or unparseable — the caller treats
+ * that as "identity unverified", never as a verdict toward the destructive
+ * branch.
+ */
+export function parsePsLstart(output) {
+    const trimmed = output.trim();
+    if (!trimmed)
+        return null;
+    const ms = Date.parse(trimmed);
+    return Number.isFinite(ms) ? ms : null;
+}
+/**
+ * Parse the sidecar JSON. Returns null on malformed content or a missing /
+ * non-positive pid/startTimeMs/port — the caller reports that as "unreadable".
+ */
+export function parseSidecarJson(content) {
+    let obj;
+    try {
+        obj = JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+    if (typeof obj !== "object" || obj === null)
+        return null;
+    const rec = obj;
+    const pid = Number(rec.pid);
+    const startTimeMs = Number(rec.startTimeMs);
+    const port = Number(rec.port);
+    const flairVersion = typeof rec.flairVersion === "string" ? rec.flairVersion : "";
+    if (!Number.isInteger(pid) || pid <= 0)
+        return null;
+    if (!Number.isFinite(startTimeMs))
+        return null;
+    if (!Number.isInteger(port) || port <= 0)
+        return null;
+    return { pid, startTimeMs, port, flairVersion };
+}

package/dist/lib/upgrade-migrations.js

@@ -0,0 +1,181 @@
+/**
+ * upgrade-migrations.ts — flair#1439
+ *
+ * Version-keyed migrations that `flair upgrade` applies automatically during
+ * the post-restart verification step. These are distinct from the Harper data
+ * migrations in `resources/migrations/`: those run inside the server and
+ * transform stored data. These run in the CLI and bring the LOCAL dev-env
+ * (hook files, config snippets) up to the state a fresh `flair init` would
+ * produce for the harnesses already wired on this machine.
+ *
+ * ## Consent model
+ *
+ * A migration runs when ALL of the following hold:
+ *   1. The installed harness/artifact is ALREADY present on this machine
+ *      (the user consented to that integration when they ran `flair init`).
+ *   2. The target version (`toVersion`) introduces the artifact for the first
+ *      time (`toAtLeast`), AND the previous version did not have it
+ *      (`fromBefore`).
+ *   3. The artifact is currently absent (idempotent: nothing to do if it's
+ *      already there).
+ *
+ * Because (1) is the consent gate, no extra flag or TTY interaction is
+ * required. The user already said "wire Codex" — the migration just applies
+ * the piece their old init couldn't know about.
+ *
+ * ## Adding a new migration
+ *
+ *   1. Push a new entry onto UPGRADE_MIGRATIONS.
+ *   2. Set `fromBefore` to the first version that includes the new artifact.
+ *   3. Set `toAtLeast` to the same version.
+ *   4. Implement `apply(ctx)` — return ok:false (surfaced as a warning) on
+ *      partial failure; throw only on hard failure that should be logged.
+ *
+ * Migrations run in order; later entries may assume earlier ones completed.
+ */
+import { installHook, hookSettingsPath, SUPPORTED_HARNESSES, } from "../hook-install.js";
+import { checkSessionStartHook, readClientMcpBlock } from "../doctor-client.js";
+import { parseSemverCore } from "../fabric-upgrade.js";
+// ─── Semver helpers ───────────────────────────────────────────────────────────
+/** True if version `a` is strictly less than `b`. */
+function semverLt(a, b) {
+    const pa = parseSemverCore(a);
+    const pb = parseSemverCore(b);
+    if (!pa || !pb)
+        return false;
+    if (pa[0] !== pb[0])
+        return pa[0] < pb[0];
+    if (pa[1] !== pb[1])
+        return pa[1] < pb[1];
+    return pa[2] < pb[2];
+}
+/** True if version `a` is greater than or equal to `b`. */
+function semverGte(a, b) {
+    return !semverLt(a, b);
+}
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+/**
+ * Determine if a harness is "already wired" — the user previously ran
+ * `flair init` for it and the MCP block (config.toml / mcpServers JSON) is
+ * present. The hook itself is what we're migrating IN, so we deliberately
+ * do NOT check for the hook's presence here.
+ *
+ * Uses readClientMcpBlock (which temporarily overrides HOME) so the homeDir
+ * arg is honoured correctly in tests.
+ */
+function isHarnessWired(homeDir, harness) {
+    const clientId = harness === "codex" ? "codex" : "claude-code";
+    const block = readClientMcpBlock(clientId, homeDir);
+    return block.present;
+}
+/**
+ * Install the SessionStart hook for a harness, reading the agent id and flair
+ * URL from the existing MCP block (same as `resolveUpgradeHookInstall` in
+ * doctor-run.ts, but self-contained to avoid a circular dep).
+ */
+function applySessionStartHookForHarness(homeDir, harness, port) {
+    const id = `session-start-hook@0.50.0/${harness}`;
+    // Already present → idempotent no-op.
+    const settingsPath = hookSettingsPath(homeDir, harness);
+    const existing = checkSessionStartHook(homeDir, settingsPath);
+    if (existing.present) {
+        return { id, message: `SessionStart hook (${harness}): already present — no-op`, ok: true, wrote: false };
+    }
+    // Not wired at all → skip (don't wire a harness the user never had).
+    if (!isHarnessWired(homeDir, harness)) {
+        return { id, message: `SessionStart hook (${harness}): harness not wired — skip`, ok: true, wrote: false };
+    }
+    // Resolve agentId + flairUrl from the existing MCP block.
+    const clientId = harness === "codex" ? "codex" : "claude-code";
+    const block = readClientMcpBlock(clientId, homeDir);
+    const agentId = (typeof process.env.FLAIR_AGENT_ID === "string" && process.env.FLAIR_AGENT_ID) ||
+        block.agentId;
+    const flairUrl = (typeof process.env.FLAIR_URL === "string" && process.env.FLAIR_URL) ||
+        block.flairUrl ||
+        `http://127.0.0.1:${port}`;
+    if (!agentId) {
+        return {
+            id,
+            message: `SessionStart hook (${harness}): no agent id found in MCP config — run: flair hook install --harness ${harness}`,
+            ok: false,
+            wrote: false,
+        };
+    }
+    const result = installHook({ homeDir, harness, agentId, flairUrl });
+    return {
+        id,
+        message: result.message,
+        ok: result.ok,
+        wrote: result.ok,
+    };
+}
+// ─── Migration registry ───────────────────────────────────────────────────────
+/**
+ * Ordered list of all CLI upgrade migrations.
+ *
+ * To add a migration: push a new entry, set fromBefore/toAtLeast, implement
+ * apply(). The runner calls apply() only when the version window matches.
+ */
+export const UPGRADE_MIGRATIONS = [
+    {
+        id: "session-start-hook@0.50.0",
+        description: "Install missing SessionStart hook(s) for harnesses already wired in a pre-0.50.0 init",
+        fromBefore: "0.50.0",
+        toAtLeast: "0.50.0",
+        apply(ctx) {
+            // Only act on detected hook-capable harnesses already wired on this machine.
+            const harnesses = SUPPORTED_HARNESSES.filter((h) => ctx.detectedClientIds.includes(h) && isHarnessWired(ctx.homeDir, h));
+            if (harnesses.length === 0)
+                return [];
+            return harnesses.map((h) => applySessionStartHookForHarness(ctx.homeDir, h, ctx.port));
+        },
+    },
+];
+/**
+ * Run all CLI upgrade migrations whose version window matches
+ * `fromVersion → toVersion`. Migrations whose window is not matched are
+ * silently skipped (they're not pending for this upgrade pair).
+ *
+ * @param fromVersion  The previously installed version (null → unknown, skip
+ *                     migrations that need a version gate).
+ * @param toVersion    The newly installed version (null → unknown, skip all).
+ * @param ctx          Runtime context (homeDir, port, detectedClientIds).
+ */
+export function applyUpgradeMigrations(fromVersion, toVersion, ctx, 
+// Injectable for tests (e.g. the throwing-migration case); production callers
+// use the real registry.
+migrations = UPGRADE_MIGRATIONS) {
+    const applied = [];
+    if (!fromVersion || !toVersion) {
+        // Cannot gate on version — skip all version-keyed migrations.
+        return { applied, allOk: true };
+    }
+    for (const migration of migrations) {
+        const pending = semverLt(fromVersion, migration.fromBefore) &&
+            semverGte(toVersion, migration.toAtLeast);
+        if (!pending)
+            continue;
+        // A migration must never CRASH the upgrade: a thrown apply() is strictly
+        // worse than the pre-migration doctor failure it was meant to prevent — no
+        // summary, partial writes, and the doctor catalog never runs. Catch it,
+        // surface it as a non-fatal ok:false result, and let the catalog proceed
+        // (flair#1439, per Kern review).
+        let results;
+        try {
+            results = migration.apply(ctx);
+        }
+        catch (err) {
+            results = [{
+                    id: migration.id,
+                    message: `${migration.id}: migration failed (${err instanceof Error ? err.message : String(err)}) — run \`flair doctor\` to check the current state`,
+                    ok: false,
+                    wrote: false,
+                }];
+        }
+        if (results.length > 0) {
+            applied.push({ migration, results });
+        }
+    }
+    const allOk = applied.every((a) => a.results.every((r) => r.ok));
+    return { applied, allOk };
+}

package/dist/resources/MemoryArchive.js

@@ -0,0 +1,94 @@
+/**
+ * MemoryArchive.ts — user-facing archive action (flair#1472, Deliverable A).
+ *
+ * POST /MemoryArchive — sets or clears the `archived` visibility flag on a
+ * memory by id:
+ *   - `action: "basement"` → archived=true + stamps archivedAt (and archivedBy)
+ *   - `action: "restore"`  → archived=false + clears archivedAt/archivedBy
+ *
+ * `archived` is a VISIBILITY flag, not a deletion: basementing removes a
+ * memory from bootstrap + default search but leaves the row, its provenance,
+ * and its history fully intact (still retrievable via memory_get and
+ * memory_search(includeArchived:true)). Restore is the deliberate, GLOBAL
+ * inverse — it un-retires the memory for EVERY session, not a session-local
+ * view (per-session reuse is drawers, Deliverable B, which does not exist
+ * yet). The CLI help text must make that global scope explicit.
+ *
+ * Own-lane scope: the read uses Memory.get()'s read-scope gate and the write
+ * uses Memory.put()'s ownership gate (stampAttribution), so a caller can
+ * neither read nor write another agent's memory here. Anonymous HTTP is
+ * denied (401).
+ *
+ * Registered automatically at /MemoryArchive via config.yaml's
+ * `jsResource: files: dist/resources/*.js` (named export → export name).
+ */
+import { Resource } from "harper";
+import { Memory } from "./Memory.js";
+import { resolveAgentAuth, allowVerified } from "./agent-auth.js";
+function json(status, body) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { "content-type": "application/json" },
+    });
+}
+/** Unwrap a Harper Response (has .json() + .status) into a plain object, else pass through. */
+async function unwrap(value) {
+    if (value && typeof value === "object" && typeof value.json === "function" && "status" in value) {
+        try {
+            const body = await value.json();
+            return { ...body, status: value.status };
+        }
+        catch {
+            return { error: "request failed", status: value.status };
+        }
+    }
+    return value;
+}
+export class MemoryArchive extends Resource {
+    /** POST requires auth — an agent acting on its own memories (or admin). */
+    async allowCreate() {
+        return allowVerified(this.getContext?.());
+    }
+    async post(data) {
+        const { id, action } = data || {};
+        if (!id)
+            return json(400, { error: "id required" });
+        if (action !== "basement" && action !== "restore") {
+            return json(400, { error: "action must be 'basement' or 'restore'" });
+        }
+        const ctx = this.getContext?.();
+        const auth = await resolveAgentAuth(ctx);
+        if (auth.kind === "anonymous")
+            return json(401, { error: "authentication required" });
+        if (auth.kind !== "agent")
+            return json(403, { error: "forbidden" });
+        // Read the existing record — Memory.get()'s read-scope gate applies (own +
+        // org-non-private only). A non-readable id returns a 404 Response.
+        const existing = await Memory.get(id, ctx);
+        const record = await unwrap(existing);
+        if (!record || typeof record !== "object" || !record.id) {
+            return json(404, { error: "memory not found" });
+        }
+        const archived = action === "basement";
+        const merged = {
+            ...record,
+            archived,
+            updatedAt: new Date().toISOString(),
+        };
+        if (archived) {
+            // archivedBy is set by the caller (Memory.put() stamps archivedAt when
+            // archived===true). The content is unchanged, so the existing embedding
+            // stays valid — do NOT clear it (clearing would force a needless re-embed
+            // and, if the embedding engine is unavailable, silently drop the vector).
+            merged.archivedBy = auth.agentId;
+        }
+        else {
+            delete merged.archivedAt;
+            delete merged.archivedBy;
+        }
+        // Write back — Memory.put()'s ownership gate applies (stampAttribution), so
+        // a non-admin caller cannot flip another agent's memory (403).
+        const result = await Memory.put(merged, ctx);
+        return unwrap(result);
+    }
+}

package/dist/resources/MemoryBootstrap.js

@@ -697,6 +697,7 @@ export class BootstrapMemories extends Resource {
             conditions: [
                 { attribute: "agentId", comparator: "equals", value: agentId },
                 { attribute: "durability", comparator: "equals", value: "permanent" },
+                { attribute: "archived", comparator: "not_equal", value: true },
             ],
             select: OWN_SELECT,
         }));
@@ -767,6 +768,7 @@ export class BootstrapMemories extends Resource {
             conditions: [
                 { attribute: "agentId", comparator: "equals", value: agentId },
                 { attribute: "durability", comparator: "not_equal", value: "permanent" },
+                { attribute: "archived", comparator: "not_equal", value: true },
             ],
             select: OWN_SELECT,
             sort: { attribute: "createdAt", descending: true },
@@ -952,7 +954,7 @@ export class BootstrapMemories extends Resource {
                 const candidatePoolK = Math.min(MAX_CANDIDATE_POOL, Math.max(3 * expectedFill, 5 * teammateIds.length, MIN_CANDIDATE_POOL));
                 const candidates = await retrieveCandidates({
                     queryEmbedding,
-                    conditions: [scope.condition],
+                    conditions: [scope.condition, { attribute: "archived", comparator: "not_equal", value: true }],
                     limit: candidatePoolK,
                     // flair#1246 — ONE RANKER, ONE SCALE: this pass now invokes the
                     // core in the SAME mode memory_search does (hybrid + q via the

package/dist/resources/SemanticSearch.js

@@ -61,7 +61,7 @@ export class SemanticSearch extends Resource {
         // recall-harness (test/bench/recall-harness/run.ts) and `recall-eval.mjs`
         // before reconsidering this default if the compositeScore formula or
         // corpus changes.
-        const { agentId: bodyAgentId, q, queryEmbedding, tag, subject, subjects, limit = 10, includeSuperseded = false, scoring = "raw", minScore = 0, since, asOf, includeTrust = false, includeMetadata = false, abstain = false, explain = false, includeLegs = false } = data || {};
+        const { agentId: bodyAgentId, q, queryEmbedding, tag, subject, subjects, limit = 10, includeSuperseded = false, scoring = "raw", minScore = 0, since, asOf, includeTrust = false, includeMetadata = false, abstain = false, explain = false, includeLegs = false, includeArchived = false } = data || {};
         // Authenticated identity lives on the Harper Resource context (getContext().request).
         // `this.request` is NOT populated on Harper v5 Resources — prior reads here
         // silently returned undefined and the defense-in-depth scope check below
@@ -160,7 +160,12 @@ export class SemanticSearch extends Resource {
         }
         // Exclude archived records. Use "not_equal" (Harper v5 comparator) instead of
         // "equals false" so records without the archived field are included.
-        conditions.push({ attribute: "archived", comparator: "not_equal", value: true });
+        // flair#1472 — `includeArchived` opts back IN to the basement: when true the
+        // archived predicate is omitted entirely, so basemented memories are returned
+        // under the SAME read-scope gate as a normal search (never a wider scope).
+        if (!includeArchived) {
+            conditions.push({ attribute: "archived", comparator: "not_equal", value: true });
+        }
         if (tag) {
             conditions.push({ attribute: "tags", comparator: "equals", value: tag });
         }

package/dist/resources/mcp-tools.js

@@ -10,9 +10,10 @@
  * per-source scoping — see resources/AttentionQuery.ts's module doc), so the
  * MCP surface inherits the SAME security model as the signed-REST path. There
  * is no raw CRUD surface — the only way to reach the datastore through /mcp is
- * via one of these 12 semantic tools.
+ * via one of these 14 semantic tools.
  *
  *   memory_search · memory_store · memory_update · memory_get · memory_delete ·
+ *   memory_basement · memory_restore ·
  *   bootstrap · soul_set · soul_get · flair_workspace_set · flair_orgevent ·
  *   attention · record_usage
  *
@@ -184,6 +185,10 @@ async function memorySearch(agent, args) {
     // requested so a plain search delegates a byte-identical body.
     if (args?.abstain === true)
         body.abstain = true;
+    // flair#1472 — opt-in basement inclusion. Forwarded ONLY when requested so a
+    // plain search delegates a byte-identical body (archived excluded by default).
+    if (args?.includeArchived === true)
+        body.includeArchived = true;
     return unwrap(await h.post(body));
 }
 async function memoryStore(agent, args) {
@@ -351,6 +356,56 @@ async function memoryUpdate(agent, args) {
     // regenerates the vector server-side); no-op when the response carries none.
     return stripInternalFields(await unwrap(await Cls.put(merged, delegationContext(agent))));
 }
+// ── flair#1472 memory_basement / memory_restore ──────────────────────────────
+// The user-facing archive action. `archived` is a VISIBILITY flag, not a
+// deletion: basementing a memory removes it from bootstrap + default search
+// but leaves the row, its provenance, and its history fully intact (still
+// retrievable via memory_get and memory_search(includeArchived:true)). Restore
+// is the deliberate, GLOBAL inverse — it un-retires the memory for EVERY
+// session, not a session-local view (that is drawers, Deliverable B, which does
+// not exist yet). Both are writes scoped to the caller's own lane: the read
+// uses Memory.get()'s read-scope gate and the write uses Memory.put()'s
+// ownership gate (stampAttribution), so a caller can neither read nor write
+// another agent's memory here.
+async function memoryBasement(agent, args) {
+    const Cls = await handler("Memory");
+    const id = args?.id;
+    const existing = await unwrap(await Cls.get(id, delegationContext(agent)));
+    if (!existing || existing.error != null || existing.status === 404) {
+        return { error: "memory not found", status: 404 };
+    }
+    const merged = {
+        ...existing,
+        archived: true,
+        archivedBy: agent.agentId,
+        updatedAt: new Date().toISOString(),
+    };
+    // Memory.put() stamps archivedAt when archived===true (see Memory.ts). The
+    // content is unchanged, so the existing embedding stays valid — do NOT clear
+    // it (clearing would force a needless re-embed and, if the embedding engine
+    // is unavailable, would silently drop the vector).
+    if (agent.clientId)
+        merged.claimedClient = agent.clientId;
+    return stripInternalFields(await unwrap(await Cls.put(merged, delegationContext(agent))));
+}
+async function memoryRestore(agent, args) {
+    const Cls = await handler("Memory");
+    const id = args?.id;
+    const existing = await unwrap(await Cls.get(id, delegationContext(agent)));
+    if (!existing || existing.error != null || existing.status === 404) {
+        return { error: "memory not found", status: 404 };
+    }
+    const merged = {
+        ...existing,
+        archived: false,
+        updatedAt: new Date().toISOString(),
+    };
+    delete merged.archivedAt;
+    delete merged.archivedBy;
+    if (agent.clientId)
+        merged.claimedClient = agent.clientId;
+    return stripInternalFields(await unwrap(await Cls.put(merged, delegationContext(agent))));
+}
 async function memoryGet(agent, args) {
     const Cls = await handler("Memory");
     // flair#1181 — by-id reads MUST use the STATIC `Cls.get(id, context)` form,
@@ -635,6 +690,7 @@ export const TOOLS = {
                     limit: { type: "number", description: "Max results (default 5)" },
                     includeTrust: { type: "boolean", description: "Attach a per-result trust-evidence block (provenance, author, usage, freshness, supersession). Default false." },
                     abstain: { type: "boolean", description: "Opt into first-class abstention: when the best match is below a global confidence threshold, return { abstained: true, reason, bestScore } with no weak matches instead of the N weakest results. Default false." },
+                    includeArchived: { type: "boolean", description: "Include basemented (archived) memories in results. Default false — archived memories are excluded from normal search. When true, archived memories are returned under the SAME read-scope gate as a normal search (never a wider scope)." },
                 },
                 required: ["query"],
             },
@@ -712,6 +768,55 @@ export const TOOLS = {
             errorShape: { trigger: "updating a non-existent id", fields: ["error", "status"] },
         },
     },
+    memory_basement: {
+        def: {
+            name: "memory_basement",
+            description: "Send a memory to the basement (archive it). Sets archived=true and stamps archivedAt. " +
+                "The memory is removed from bootstrap and default search but remains retrievable via " +
+                "memory_get and memory_search(includeArchived:true). Deliberate and GLOBAL — this is a " +
+                "visibility flag, not a deletion: provenance and history are untouched. Scoped to your own memories only.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    id: { type: "string", description: "ID of the memory to basement (archive)" },
+                },
+                required: ["id"],
+            },
+        },
+        impl: memoryBasement,
+        contract: {
+            summary: "Write echo of the archived record { id, archived:true, archivedAt, ... }. No internal embedding fields; the flip round-trips via memory_get.",
+            requiredFields: ["id", "archived"],
+            fieldTypes: { id: "string", archived: "boolean" },
+            forbiddenFields: INTERNAL_MEMORY_FIELDS,
+            invariants: { fullyResolved: true },
+            errorShape: { trigger: "basementing a non-existent or non-owned id", fields: ["error", "status"] },
+        },
+    },
+    memory_restore: {
+        def: {
+            name: "memory_restore",
+            description: "Restore a basemented (archived) memory. Clears archived and archivedAt. Deliberate and GLOBAL — " +
+                "this un-retires the memory for EVERY session, not a session-local view (per-session reuse is " +
+                "drawers, which do not exist yet). Scoped to your own memories only.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    id: { type: "string", description: "ID of the memory to restore (un-archive)" },
+                },
+                required: ["id"],
+            },
+        },
+        impl: memoryRestore,
+        contract: {
+            summary: "Write echo of the restored record { id, archived:false, ... }. No internal embedding fields; the flip round-trips via memory_get.",
+            requiredFields: ["id", "archived"],
+            fieldTypes: { id: "string", archived: "boolean" },
+            forbiddenFields: INTERNAL_MEMORY_FIELDS,
+            invariants: { fullyResolved: true },
+            errorShape: { trigger: "restoring a non-existent or non-owned id", fields: ["error", "status"] },
+        },
+    },
     memory_get: {
         def: {
             name: "memory_get",