@tpsdev-ai/flair 0.46.0 → 0.47.0

package/dist/resources/memory-reflect-lib.js

@@ -39,8 +39,114 @@ export const DEFAULT_MAX_TOKENS = 2000;
  * over creative extrapolation.
  */
 export const GENERATE_TEMPERATURE = 0.2;
+// ─── Continuity-journal distillation (flair#1257 slice 3) ────────────────────
+// The session-continuity journal (slice 2, #1283) writes ephemeral+private
+// rows tagged `adk:continuity:<sessionId>`. REM distills those journals with
+// the SAME scope:"tagged" machinery ADK per-user tags use (#1205b) — slice 3
+// is wiring and guards, not a new engine. The constants/predicates here are
+// the continuity-specific guards:
+//
+//   - stale-intent (two layers, Kern-ruled): the distiller prompt carries the
+//     rule (primary), AND a text-shape post-filter drops in-flight-intent-
+//     shaped candidates when the source session is stale (testable
+//     defense-in-depth — see filterStaleSessionIntentCandidates).
+//   - visibility (Sherlock-ruled, default-private-unless): promotion out of
+//     ephemeral+private is a visibility ESCALATION from the most sensitive
+//     tier. The distiller may rule "shared" only AFFIRMATIVELY, with a
+//     team-relevance justification recorded on the candidate — never by
+//     default, never silently (see resolveCandidateVisibilityRuling).
+/** Tag prefix for continuity-journal rows (`adk:continuity:<sessionId>`).
+ *  Canonical string duplicated in packages/flair-mcp/src/continuity.ts
+ *  (CONTINUITY_TAG_PREFIX — the writer) and src/rem/runner.ts — the three
+ *  live on opposite sides of npm-packaging boundaries (resources/ ships as
+ *  the Harper component; src/ and packages/ ship separately; imports across
+ *  them don't survive packaging — see src/cli.ts's header). Kept in sync by
+ *  the shared canonical string. */
+export const CONTINUITY_SCOPE_TAG_PREFIX = "adk:continuity:";
+/** True iff `tag` is a continuity-journal scope tag (has a 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);
+}
+/**
+ * Staleness horizon for the stale-intent guard (spec item 3, default 72h,
+ * FLAIR_REM_STALE_INTENT_HOURS). A journal entry like "about to merge X" is
+ * useful context shortly after the session died (the intent may still be
+ * live); past this horizon the intent has resolved or died, and promoting it
+ * manufactures a false present. Distinct from the SETTLE window (2h,
+ * src/rem/runner.ts) — settle decides when a session may be distilled at
+ * all; this horizon decides whether in-flight-intent content from it may
+ * still promote.
+ */
+export const DEFAULT_STALE_INTENT_HORIZON_MS = 72 * 3600_000;
+/**
+ * Text shapes that mark a candidate as IN-FLIGHT INTENT — an action described
+ * as pending/current rather than decided/done. Deliberately the obvious
+ * shapes only (Kern's ruling: the prompt rule is the primary layer; this
+ * post-filter is testable defense-in-depth and need not be exhaustive).
+ * Case-insensitive; word-bounded so e.g. "roundabout to" doesn't match.
+ */
+export const IN_FLIGHT_INTENT_PATTERNS = [
+    /\babout to\b/i,
+    /\bwaiting (?:on|for)\b/i,
+    /\bgoing to\b/i,
+    /\bplanning to\b/i,
+];
+/** True iff `text` matches an in-flight-intent shape. */
+export function isInFlightIntentShaped(text) {
+    return IN_FLIGHT_INTENT_PATTERNS.some((p) => p.test(text));
+}
+/**
+ * The stale-intent POST-FILTER (spec item 3, the testable layer). When the
+ * source session is STALE — its newest entry older than `horizonMs` — drop
+ * every candidate whose claim is in-flight-intent-shaped. Runs AFTER
+ * parseAndValidateCandidates (a drop here is a policy skip, never a batch
+ * failure) and BEFORE dedup/staging.
+ *
+ * Fresh sessions pass everything through (an "about to merge X" from two
+ * hours ago is genuinely useful resume context). Stale sessions still
+ * promote DECISION-class content — the filter drops only the in-flight
+ * shapes, which is the positive control the acceptance set demands.
+ *
+ * An UNDATEABLE session (no newest-entry timestamp) is treated as STALE:
+ * this guard exists to stop manufactured false-presents, and "can't tell how
+ * old" must fail toward filtering, not toward promoting (fail-closed).
+ */
+export function filterStaleSessionIntentCandidates(candidates, params) {
+    const horizonMs = params.horizonMs ?? DEFAULT_STALE_INTENT_HORIZON_MS;
+    const newestMs = params.sessionNewestCreatedAt ? new Date(params.sessionNewestCreatedAt).getTime() : NaN;
+    const sessionStale = !Number.isFinite(newestMs) || params.now.getTime() - newestMs > horizonMs;
+    if (!sessionStale)
+        return { kept: candidates, droppedStaleIntent: [] };
+    const kept = [];
+    const droppedStaleIntent = [];
+    for (const c of candidates) {
+        (isInFlightIntentShaped(c.claim) ? droppedStaleIntent : kept).push(c);
+    }
+    return { kept, droppedStaleIntent };
+}
+/**
+ * Resolve a distilled candidate's visibility ruling (Sherlock's
+ * default-private-unless, flair#1257 slice 3). Returns a ruling ONLY when the
+ * distiller AFFIRMATIVELY ruled "shared" AND recorded a non-empty
+ * team-relevance justification — anything less (absent, "private", "shared"
+ * with no justification, whitespace justification) returns null, which
+ * downstream reads as the private default. The uncertainty fallback is
+ * private, fail-closed; a shared promoted row must always trace to a
+ * recorded justification on its candidate, never to a default.
+ */
+export function resolveCandidateVisibilityRuling(candidate) {
+    if (candidate.visibility !== "shared")
+        return null;
+    const rationale = typeof candidate.teamRelevance === "string" ? candidate.teamRelevance.trim() : "";
+    if (rationale.length === 0)
+        return null;
+    return { ruling: "shared", rationale };
+}
 // ─── Candidate shape (spec §3A) ───────────────────────────────────────────────
 // { candidates: [ { claim: string, sourceMemoryIds: string[], tags?: string[] } ] }
+// Continuity runs (flair#1257 slice 3) may additionally carry per-candidate
+// `visibility` + `teamRelevance` — see resolveCandidateVisibilityRuling.
 //
 // Passed as `responseFormat: { schema: CANDIDATES_SCHEMA }` to models.generate()
 // so backends that honor structured output (Ollama, OpenAI — verified against
@@ -64,6 +170,11 @@ export const CANDIDATES_SCHEMA = {
                     claim: { type: "string" },
                     sourceMemoryIds: { type: "array", items: { type: "string" } },
                     tags: { type: "array", items: { type: "string" } },
+                    // flair#1257 slice 3 (continuity runs only — see the module note
+                    // above CONTINUITY_SCOPE_TAG_PREFIX): an AFFIRMATIVE visibility
+                    // ruling. Optional for every run; validated when present.
+                    visibility: { type: "string", enum: ["private", "shared"] },
+                    teamRelevance: { type: "string" },
                 },
                 required: ["claim", "sourceMemoryIds"],
             },
@@ -77,7 +188,39 @@ export const FOCUS_PROMPTS = {
     patterns: "Identify recurring patterns across these memories. What themes, approaches, or outcomes appear multiple times? Extract each pattern as a persistent memory.",
     decisions: "Catalog the key decisions made and their outcomes. For each: what was decided, why, and what resulted. Promote important decisions to persistent.",
     errors: "Extract errors, bugs, and failures. For each: what failed, root cause, and fix applied. These are high-value persistent memories.",
+    // flair#1257 slice 3 — continuity-journal distillation. The source rows are
+    // an agent's auto-captured working-state journal (ephemeral, private,
+    // intent-class), not curated knowledge — distill what deserves to OUTLIVE
+    // the session. The stale-intent prompt rule here is the PRIMARY layer of
+    // the two-layer guard (Kern's ruling); filterStaleSessionIntentCandidates
+    // is the testable second layer.
+    continuity: "These memories are an agent's short-term session journal: auto-captured working-state deltas (what it was doing, deciding, and why). Distill the DURABLE takeaways — decisions made and their reasons, outcomes, lessons — into atomic persistent memories. Do NOT promote in-flight intent (e.g. \"about to merge X\", \"waiting on Y\", \"going to\", \"planning to\") from a session that is no longer live: the action has since resolved or died, and restating it as current manufactures a false present. Do not promote world-recoverable facts (PR status, CI state) — they are re-observable and go stale.",
 };
+/**
+ * Extra execute-mode instruction block for continuity runs (flair#1257 slice
+ * 3). Two parts:
+ *   - the VISIBILITY ruling contract (Sherlock, default-private-unless): the
+ *     source journal is the most sensitive tier (ephemeral+private), so the
+ *     promoted claim defaults private; the distiller may rule "shared" only
+ *     affirmatively, and then MUST justify team-relevance (the justification
+ *     is recorded on the candidate — resolveCandidateVisibilityRuling drops
+ *     any shared ruling that arrives without one).
+ *   - when the session is STALE, an explicit restatement of the stale-intent
+ *     rule with the session's age class named (the prompt-layer half of the
+ *     two-layer guard; the post-filter backstops it either way).
+ */
+export function buildContinuityExecuteAddendum(params) {
+    const lines = [
+        `Continuity visibility rules:`,
+        `- Every candidate's visibility defaults to "private". Omit the visibility field unless you are AFFIRMATIVELY ruling a candidate team-relevant.`,
+        `- To rule a candidate shared, set visibility: "shared" AND teamRelevance: one sentence stating why teammates need this. A shared ruling without a teamRelevance justification is discarded and the candidate stays private.`,
+        `- If uncertain, stay private.`,
+    ];
+    if (params.sessionStale) {
+        lines.push(`This session is STALE (its newest journal entry is beyond the staleness horizon): do NOT emit candidates describing in-flight actions ("about to", "waiting on", "going to", "planning to") — those intents have resolved or died. Distill only decisions, outcomes, and lessons.`);
+    }
+    return lines.join("\n");
+}
 /**
  * Shared "Source Memories" block for both prompt mode and execute mode
  * (K&S prompt-injection hardening, spec §3A item 7). Each memory is wrapped
@@ -127,9 +270,12 @@ For each insight:
  * handing a prompt to a human/agent.
  */
 export function buildExecutePrompt(params) {
-    const { agentId, focus, scope, sinceISO, memories } = params;
+    const { agentId, focus, scope, sinceISO, memories, continuity } = params;
     const focusText = FOCUS_PROMPTS[focus] ?? FOCUS_PROMPTS.lessons_learned;
     const validIds = memories.map((m) => `"${m.id}"`).join(", ");
+    const candidateShape = continuity
+        ? `{"candidates": [{"claim": string, "sourceMemoryIds": string[], "tags"?: string[], "visibility"?: "shared", "teamRelevance"?: string}]}`
+        : `{"candidates": [{"claim": string, "sourceMemoryIds": string[], "tags"?: string[]}]}`;
     return `# Memory Reflection — ${agentId}
 Focus: ${focus}
 Scope: ${scope} (since ${sinceISO})
@@ -137,13 +283,13 @@ Memories: ${memories.length}
 
 ## Task
 ${focusText}
-
+${continuity ? `\n${buildContinuityExecuteAddendum(continuity)}\n` : ""}
 ## Source Memories
 ${buildSourceMemoriesBlock(memories)}
 
 ## Output
 Respond with ONLY a JSON object of this shape (no prose, no markdown fences):
-{"candidates": [{"claim": string, "sourceMemoryIds": string[], "tags"?: string[]}]}
+${candidateShape}
 Rules:
 - Every sourceMemoryIds entry must be one of: ${validIds || "(none available)"}
 - claim must be a single atomic insight, at most ${MAX_CLAIM_LENGTH} characters
@@ -219,7 +365,27 @@ export function parseAndValidateCandidates(raw, gatheredMemoryIds) {
             }
             tags = candidate.tags;
         }
-        candidates.push({ claim: candidate.claim, sourceMemoryIds, tags });
+        // flair#1257 slice 3: optional visibility ruling fields (continuity runs).
+        // Validated for every run — an unknown visibility value must fail closed
+        // exactly like any other malformed field, never pass through to a place
+        // where "not private" could later read as readable (the free-form-string
+        // exact-match lesson). Whether a valid ruling has any EFFECT is decided
+        // downstream (resolveCandidateVisibilityRuling, continuity staging only).
+        let visibility;
+        if (candidate.visibility !== undefined) {
+            if (candidate.visibility !== "private" && candidate.visibility !== "shared") {
+                return { ok: false, reason: "shape_mismatch" };
+            }
+            visibility = candidate.visibility;
+        }
+        let teamRelevance;
+        if (candidate.teamRelevance !== undefined) {
+            if (typeof candidate.teamRelevance !== "string") {
+                return { ok: false, reason: "shape_mismatch" };
+            }
+            teamRelevance = candidate.teamRelevance;
+        }
+        candidates.push({ claim: candidate.claim, sourceMemoryIds, tags, visibility, teamRelevance });
     }
     return { ok: true, candidates };
 }
@@ -310,6 +476,33 @@ export function dedupeCandidates(candidates, existingPendingClaims) {
 // rules, not scope selection.
 export function memoryMatchesReflectScope(record, params) {
     const { scope, tag, sinceDate } = params;
+    // ── flair#1257 slice 3: continuity-journal containment (both directions) ───
+    // The JOURNAL is the ephemeral rows carrying a continuity session tag.
+    // Two rules keep it contained:
+    //
+    //   1. A continuity-tag tagged run gathers THE JOURNAL ONLY — ephemeral
+    //      rows carrying that session's tag. Promoted rows PRESERVE the
+    //      session scopeTag (spec item 2), so without the durability bound a
+    //      re-distill of the same tag would gather its own previous OUTPUTS as
+    //      input — a distill-of-distilled feedback loop.
+    //   2. A journal row is distillable ONLY through its own session's
+    //      continuity run — the path that carries every slice-3 guard (settle
+    //      window, continuity focus prompt, stale-intent post-filter, the
+    //      visibility ruling contract). Without this, the agentId-wide
+    //      scope:"recent"/"all" gather would sweep a LIVE session's journal
+    //      into a generic distill, bypassing all of those guards at once (the
+    //      settle window would be a check that cannot fire).
+    //
+    // Non-journal rows that carry a continuity tag (the promoted persistent
+    // rows) follow the NORMAL scope rules below — they stay re-reflectable
+    // like any other durable memory.
+    if (scope === "tagged" && isContinuityScopeTag(tag)) {
+        return record.durability === "ephemeral" && (record.tags ?? []).includes(tag);
+    }
+    const rowIsJournal = record.durability === "ephemeral" && (record.tags ?? []).some(isContinuityScopeTag);
+    if (rowIsJournal) {
+        return false;
+    }
     if (scope === "tagged") {
         // No tag ⇒ admit nothing. A tagged reflection with no tag must gather an
         // EMPTY set (fail-closed), never fall through to admitting everything —
@@ -355,5 +548,9 @@ export function buildStagedCandidateRow(params) {
     if (params.scope === "tagged" && typeof params.tag === "string" && params.tag.length > 0) {
         row.scopeTag = params.tag;
     }
+    if (params.visibilityRuling) {
+        row.visibilityRuling = params.visibilityRuling.ruling;
+        row.visibilityRationale = params.visibilityRuling.rationale;
+    }
     return row;
 }

package/dist/src/lib/scheduler-platform.js

@@ -234,6 +234,159 @@ export function describeExitCode(code) {
         return "exit 209 — launchd could not spawn the job (a missing/unwritable log directory produces this)";
     return `exit ${code}`;
 }
+/**
+ * Reads how the job's most recent run ended, from the only vantage that
+ * knows: the service manager itself.
+ *
+ * darwin: `launchctl print` carries `last exit code = N` once a run has
+ * completed (parseLaunchdPrintExit). linux: `systemctl --user show` on the
+ * service unit — with one trap encoded here rather than in every caller: a
+ * unit that has NEVER completed a run still reports `ExecMainStatus=0,
+ * Result=success` (systemd property defaults), so the exit properties are
+ * only believed when `ExecMainExitTimestampMonotonic` proves a run actually
+ * finished. Without that check, "never ran" renders as "last run succeeded"
+ * — the exact skipped-check-looks-like-a-pass shape this feature exists to
+ * kill.
+ */
+export function queryLastExitStatus(opts) {
+    const run = opts.run ?? ((cmd, timeoutMs) => spawnReport(cmd, timeoutMs));
+    if (opts.plat === "darwin") {
+        const target = opts.darwinTarget;
+        if (!target)
+            throw new Error("queryLastExitStatus: darwinTarget is required on darwin");
+        const printCmd = ["launchctl", "print", target];
+        const r = run(printCmd, STATUS_CHECK_TIMEOUT_MS);
+        if (spawnedNothing(r)) {
+            return { state: "unavailable", exitCode: null, detail: `launchctl could not be run (${printCmd.join(" ")})` };
+        }
+        if (r.code !== 0) {
+            return { state: "unavailable", exitCode: null, detail: `${printCmd.join(" ")} → code ${r.code} (job not loaded — no run record to read)` };
+        }
+        const { running, lastExitCode } = parseLaunchdPrintExit(r.stdout);
+        if (running) {
+            return { state: "running", exitCode: null, detail: `${printCmd.join(" ")} → a run is in flight` };
+        }
+        if (lastExitCode === null) {
+            return { state: "never-ran", exitCode: null, detail: `${printCmd.join(" ")} → no completed run recorded` };
+        }
+        return { state: "recorded", exitCode: lastExitCode, detail: `${printCmd.join(" ")} → last exit code = ${lastExitCode}` };
+    }
+    const unit = opts.linuxServiceUnit;
+    if (!unit)
+        throw new Error("queryLastExitStatus: linuxServiceUnit is required on linux");
+    const showCmd = ["systemctl", "--user", "show", unit, "--property=ExecMainStatus,Result,ExecMainExitTimestampMonotonic"];
+    const r = run(showCmd, STATUS_CHECK_TIMEOUT_MS);
+    if (spawnedNothing(r)) {
+        return { state: "unavailable", exitCode: null, detail: `systemctl could not be run (${showCmd.join(" ")})` };
+    }
+    if (/failed to connect to bus/i.test(r.stderr)) {
+        return { state: "unavailable", exitCode: null, detail: `${showCmd.join(" ")} → ${r.stderr.trim()}` };
+    }
+    if (r.code !== 0) {
+        return { state: "unavailable", exitCode: null, detail: `${showCmd.join(" ")} → code ${r.code}${r.stderr.trim() ? `: ${r.stderr.trim()}` : ""}` };
+    }
+    // Believe the exit properties only when a run has actually finished — see
+    // the doc comment above for why this must be checked FIRST.
+    const ts = /^ExecMainExitTimestampMonotonic=(\d+)\s*$/m.exec(r.stdout);
+    if (ts && Number(ts[1]) === 0) {
+        return { state: "never-ran", exitCode: null, detail: `${showCmd.join(" ")} → no completed run recorded` };
+    }
+    const parsed = parseSystemdShowExit(r.stdout);
+    if (parsed.execMainStatus === null) {
+        return { state: "unavailable", exitCode: null, detail: `${showCmd.join(" ")} → no ExecMainStatus in the reply` };
+    }
+    const resultTxt = parsed.result ? `, Result=${parsed.result}` : "";
+    return {
+        state: "recorded",
+        exitCode: parsed.execMainStatus,
+        detail: `${showCmd.join(" ")} → ExecMainStatus=${parsed.execMainStatus}${resultTxt}`,
+    };
+}
+/**
+ * Pure decision logic for `flair doctor`'s "Scheduled drivers" section
+ * (flair#1278) — extracted so it is unit-testable without spawning
+ * launchctl/systemctl, same idiom as formatEnableReport/assessDriver in the
+ * scheduler modules and summarizeDoctorRun in the CLI.
+ *
+ * The three load-bearing rules:
+ *   - not-enabled is a CHOICE, not a defect: informational marker, never the
+ *     pass marker, never the fail marker, never an issue (a skipped check
+ *     must not look like a pass — flair#970's rule applied to schedulers).
+ *   - a last-run failure IS a defect, reported loud with actor+state+remedy
+ *     (embed-verify style): the service manager is firing the job, the runs
+ *     themselves are dying, so the schedule looks alive while nothing is
+ *     delivered — the #1231 incident shape.
+ *   - "could not read" is UNVERIFIED, never a pass and never a hard failure
+ *     — the same discipline as doctor's audit-log and embeddings probes.
+ */
+export function describeScheduledDriverFinding(f) {
+    if (!f.installed) {
+        return {
+            state: "not-enabled",
+            icon: "info",
+            isIssue: false,
+            message: `${f.label}: not enabled`,
+            detail: [`Opt-in — enable: ${f.enableCommand}`],
+        };
+    }
+    if (f.active === false) {
+        return {
+            state: "degraded",
+            icon: "error",
+            isIssue: true,
+            message: `${f.label}: INSTALLED BUT NOT LOADED — nothing will run it`,
+            detail: [
+                `The unit files are on disk, but the service manager does not have the job loaded, so it never fires.`,
+                `Fix: ${f.enableCommand}   # then check: ${f.statusCommand}`,
+            ],
+        };
+    }
+    if (f.active === null) {
+        return {
+            state: "unverified",
+            icon: "warn",
+            isIssue: false,
+            message: `${f.label}: UNVERIFIED — installed, but whether it is loaded could not be read`,
+            detail: [`Querying the service manager was inconclusive. Check: ${f.statusCommand}`],
+        };
+    }
+    // Loaded from here down.
+    const le = f.lastExit;
+    if (!le || le.state === "unavailable") {
+        return {
+            state: "unverified",
+            icon: "warn",
+            isIssue: false,
+            message: `${f.label}: loaded, but its last-run status could not be read`,
+            detail: [...(le ? [le.detail] : []), `Check: ${f.statusCommand}`],
+        };
+    }
+    if (le.state === "recorded" && le.exitCode !== 0) {
+        return {
+            state: "degraded",
+            icon: "error",
+            isIssue: true,
+            message: `${f.label} DEGRADED — loaded, but its last run failed (${describeExitCode(le.exitCode)})`,
+            detail: [
+                `The service manager has the job loaded and is firing it; the runs themselves are failing, so the schedule looks alive while nothing is delivered.`,
+                `Check ${f.stderrLogPath}, then: ${f.statusCommand}`,
+            ],
+        };
+    }
+    if (le.state === "running") {
+        return { state: "healthy", icon: "ok", isIssue: false, message: `${f.label}: loaded (a run is in flight now)`, detail: [] };
+    }
+    if (le.state === "never-ran") {
+        return {
+            state: "healthy",
+            icon: "ok",
+            isIssue: false,
+            message: `${f.label}: loaded (no completed run on record yet)`,
+            detail: [`Installed and loaded; the service manager has not recorded a completed run since it last (re)loaded the job.`],
+        };
+    }
+    return { state: "healthy", icon: "ok", isIssue: false, message: `${f.label}: loaded (last run: exit 0)`, detail: [] };
+}
 function spawnedNothing(r) {
     return r.code === null && !r.stdout.trim() && !r.stderr.trim();
 }

package/dist/src/rem/scheduler.js

@@ -26,10 +26,16 @@ import { detectPlatform as detectPlatformFor, spawnReport, readTemplate as readT
 // flair#850's lesson must have exactly one implementation).
 export { interpretActiveResult };
 export const SHIM_PATH_DEFAULT = resolve(homedir(), ".flair", "bin", "flair-rem-nightly");
-export const LAUNCHD_PLIST_PATH = resolve(homedir(), "Library", "LaunchAgents", "dev.flair.rem.nightly.plist");
+// Unit names, exported (flair#1278) so `flair doctor`'s scheduled-drivers
+// section addresses the same job this module installs — same single-source
+// rule as the federation scheduler's LAUNCHD_LABEL/SYSTEMD_*_UNIT constants.
+export const LAUNCHD_LABEL = "dev.flair.rem.nightly";
+export const SYSTEMD_TIMER_UNIT = "flair-rem-nightly.timer";
+export const SYSTEMD_SERVICE_UNIT = "flair-rem-nightly.service";
+export const LAUNCHD_PLIST_PATH = resolve(homedir(), "Library", "LaunchAgents", `${LAUNCHD_LABEL}.plist`);
 export const SYSTEMD_USER_DIR = resolve(homedir(), ".config", "systemd", "user");
-export const SYSTEMD_TIMER_PATH = resolve(SYSTEMD_USER_DIR, "flair-rem-nightly.timer");
-export const SYSTEMD_SERVICE_PATH = resolve(SYSTEMD_USER_DIR, "flair-rem-nightly.service");
+export const SYSTEMD_TIMER_PATH = resolve(SYSTEMD_USER_DIR, SYSTEMD_TIMER_UNIT);
+export const SYSTEMD_SERVICE_PATH = resolve(SYSTEMD_USER_DIR, SYSTEMD_SERVICE_UNIT);
 function detectPlatform(override) {
     return detectPlatformFor("REM nightly scheduler", override);
 }
@@ -113,9 +119,9 @@ function buildSubstitutions(opts, shimPath, flairBin, nodeBin) {
  */
 function activeCheckCommand(plat) {
     if (plat === "darwin") {
-        return ["launchctl", "print", `gui/${process.getuid?.() ?? ""}/dev.flair.rem.nightly`];
+        return ["launchctl", "print", `gui/${process.getuid?.() ?? ""}/${LAUNCHD_LABEL}`];
     }
-    return ["systemctl", "--user", "is-active", "flair-rem-nightly.timer"];
+    return ["systemctl", "--user", "is-active", SYSTEMD_TIMER_UNIT];
 }
 /**
  * Synchronous active-state check for CLI use (`flair rem nightly status`).
@@ -369,7 +375,7 @@ export function enableScheduler(opts) {
                 // remedy — kickstarting on top of it would blur which actor failed.
                 firstRun = verifyFirstRun({
                     plat,
-                    darwinTarget: `gui/${process.getuid?.() ?? ""}/dev.flair.rem.nightly`,
+                    darwinTarget: `gui/${process.getuid?.() ?? ""}/${LAUNCHD_LABEL}`,
                     stderrLogPath,
                 });
             }
@@ -386,7 +392,7 @@ export function enableScheduler(opts) {
     const timerContents = renderTemplate(readTemplate(templateRoot, "systemd/flair-rem-nightly.timer.tmpl"), subs);
     writeFileWithDir(servicePath, serviceContents, 0o600);
     writeFileWithDir(timerPath, timerContents, 0o600);
-    const loadCommand = ["systemctl", "--user", "enable", "--now", "flair-rem-nightly.timer"];
+    const loadCommand = ["systemctl", "--user", "enable", "--now", SYSTEMD_TIMER_UNIT];
     let loadResult;
     let firstRun;
     if (!opts.skipLoad) {
@@ -396,7 +402,7 @@ export function enableScheduler(opts) {
             // Ordering gate (#1231): only after the load exited 0. Starts the
             // SERVICE unit directly (oneshot ⇒ blocks until the run exits) rather
             // than waiting for the nightly timer to fire.
-            firstRun = verifyFirstRun({ plat, linuxServiceUnit: "flair-rem-nightly.service", stderrLogPath });
+            firstRun = verifyFirstRun({ plat, linuxServiceUnit: SYSTEMD_SERVICE_UNIT, stderrLogPath });
         }
     }
     return {
@@ -432,7 +438,7 @@ export function disableScheduler(opts = {}) {
     }
     const timerPath = opts.systemdTimerOverride ?? SYSTEMD_TIMER_PATH;
     const servicePath = opts.systemdServiceOverride ?? SYSTEMD_SERVICE_PATH;
-    const unloadCommand = ["systemctl", "--user", "disable", "--now", "flair-rem-nightly.timer"];
+    const unloadCommand = ["systemctl", "--user", "disable", "--now", SYSTEMD_TIMER_UNIT];
     let unloadResult;
     if (existsSync(timerPath) || existsSync(servicePath)) {
         if (!opts.skipUnload) {

package/docs/deepseek-harness.md

@@ -0,0 +1,110 @@
+# Flair + DeepSeek Harness (zero-code MCP bridge)
+
+Give DeepSeek Harness (DSH) sessions persistent, portable memory — no plugin code, just one Cordis overlay wiring [`@tpsdev-ai/flair-mcp`](../packages/flair-mcp) through DSH's first-party MCP bridge, [`@deepseek-ai/dsh-mcp-client`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/mcp/mcp-client).
+
+> **Verified against DSH as of 2026-08-20** (`deepseek-ai/deepseek-harness`, branch `master`). DSH is a developer preview and its own README promises compatibility-breaking changes. If wiring fails after a DSH upgrade, re-check the config field names against [their MCP client README](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/mcp/mcp-client/README.md) before suspecting Flair.
+
+The same eleven tools every other MCP client gets ([full table in mcp-clients.md](mcp-clients.md#what-the-mcp-server-exposes)) appear to the model under DSH's server-qualified names: `mcp__flair__memory_search`, `mcp__flair__memory_store`, `mcp__flair__bootstrap`, and so on — the same `mcp__<server>__<tool>` convention Claude Code uses.
+
+Two caveats up front, both structural to DSH's bridge (details below):
+
+1. **DSH scrubs the ambient environment before spawning MCP servers.** Flair's env vars must be declared in the overlay's `config.env` — exported shell vars will not reliably reach the server.
+2. **Recall on this path is reactive.** The model must *choose* to call the memory tools; DSH's MCP bridge cannot inject Flair context at session start. There is a documented mitigation (a persona nudge), but real auto-inject requires a native DSH plugin — planned as phase 2 of [flair#1289](https://github.com/tpsdev-ai/flair/issues/1289).
+
+## Prerequisites
+
+Same as every MCP client — a running Flair and an agent identity. Follow [Step 1 of mcp-clients.md](mcp-clients.md#step-1--install-flair-do-once) (install, `flair init`, `flair agent add <id>`, `flair status`). If DSH runs on a machine that cannot see your Flair instance's loopback address, you need a reachable `FLAIR_URL` — see [quickstart-fabric.md](quickstart-fabric.md).
+
+DSH spawns the server with `npx`, so the machine running DSH needs Node.js 22+ (Flair's own floor).
+
+## The overlay
+
+A ready-to-use copy of this file ships in the repo at [`examples/deepseek-harness/flair.cordis.yml`](../examples/deepseek-harness/flair.cordis.yml):
+
+```yaml
+- insert:
+    - id: memory-flair
+      name: '@deepseek-ai/dsh-mcp-client'
+      config:
+        serverName: flair
+        transport: stdio
+        command: npx
+        args: ['-y', '@tpsdev-ai/flair-mcp@<version>']
+        env:
+          FLAIR_AGENT_ID: <agent-id>
+          FLAIR_URL: http://127.0.0.1:19926
+```
+
+Replace the two placeholders before use:
+
+- `<version>` — pin the flair-mcp version you intend to run (the one you already have is `flair --version`). The [pinning rationale from mcp-clients.md](mcp-clients.md#step-2--wire-the-mcp-server-into-your-cli) applies with extra force here: DSH re-spawns the command per session, so an unpinned spec re-resolves to whatever is currently on npm every time. Leaving the literal `<version>` in place fails loudly at `npx` — intended.
+- `<agent-id>` — the identity you created with `flair agent add`.
+
+`FLAIR_URL` as shown is the local default; point it at your Fabric URL for a remote instance.
+
+Apply it for one run:
+
+```sh
+dsh web --patch "$PWD/examples/deepseek-harness/flair.cordis.yml"
+```
+
+To keep it across runs, merge the single `insert` patch into a user patch layer — `$DSH_HOME/profiles/<name>/cordis.patch.yml` for one profile, or `$DSH_HOME/cordis.patch.yml` machine-wide. Merge into an existing file rather than copying over it; it may already carry unrelated patches.
+
+DSH's own reference memory overlays prefer a preinstalled binary over a package runner ("DSH starts it but does not run a package manager"). If you want that shape: `npm install -g @tpsdev-ai/flair-mcp@<version>`, then `command: flair-mcp` with no `args`.
+
+## Caveat 1 — the bridge scrubs ambient env; declare Flair's env explicitly
+
+Before spawning a stdio MCP server, DSH's bridge builds the child environment from a **scrubbed** copy of the parent env: every variable whose name matches `KEY`, `PASSWORD`, `SECRET`, or `TOKEN` (case-insensitive) is dropped, and so is every `DSH_*` variable. The overlay's `config.env` is merged **after** the scrub, so it is the one reliable channel.
+
+Concretely for Flair:
+
+- `FLAIR_KEY_PATH` contains `KEY` — an exported value is **silently dropped**. If your Ed25519 key is not at the default `~/.flair/keys/<agent>.key`, you must set `FLAIR_KEY_PATH` in `config.env`.
+- `FLAIR_AGENT_ID` and `FLAIR_URL` happen to survive today's scrub pattern, but the pattern is DSH's to change. Declare all three in `config.env` and depend on none of the ambient env.
+
+This mirrors the general rule from [mcp-clients.md troubleshooting](mcp-clients.md#troubleshooting) — a client's own env does not propagate to the spawned MCP subprocess unless declared — DSH just enforces it deliberately.
+
+## Caveat 2 — recall is reactive on this path
+
+DSH's MCP bridge registers **tools** on the model's tool list. That is all it can do: DSH has no first-class memory seam, and the bridge has no way to run `bootstrap` at session start and inject the result into context. Whether memory gets consulted is the model's per-turn decision — identical to the behavior DSH documents for its own reference memory servers.
+
+The documented mitigation is a standing prompt nudge. DSH's deployment persona is the `persona` config key on its `system-prompt` row (agent presets can shadow it with a persona row of their own; there is no end-user prompt-editing API — prompt text is config/composition only). Add something like:
+
+> At the start of a task, call `mcp__flair__bootstrap` or `mcp__flair__memory_search` to load relevant memory before planning. When you make a decision worth keeping, or the user asks you to remember something, record it with `mcp__flair__memory_store`.
+
+This is additive guidance in the shape DSH's own memory examples recommend, and it works — but it is a nudge, not a guarantee. **Honest limitation:** automatic session-start injection (what Flair's Claude Code `SessionStart` hook does) requires a native DSH plugin using their per-turn system-prompt context seam. That is phase 2 of [flair#1289](https://github.com/tpsdev-ai/flair/issues/1289); until it ships, this wiring gives pull-based memory only.
+
+## Tools-only bridging
+
+DSH bridges MCP **tools** only — Resources and Prompts are explicitly not bridged (a documented DSH limitation, not a Flair one). This costs nothing here: `flair-mcp` is a tools-only server, so its entire surface crosses the bridge.
+
+## Verify your wiring
+
+Initial tool discovery is asynchronous — wait until the `mcp__flair__*` tools appear in the session's tool list before the first prompt. Then run the write → fresh-session → recall check (the same protocol shape DSH uses to validate its own reference memory servers):
+
+1. In DSH session A, ask: *"Remember that my validation drink is lapsang-`<unique suffix>`."* Confirm the model calls `mcp__flair__memory_store` and the tool reports success.
+2. Open DSH session B in the same running Host — do not copy session A's conversation. Ask: *"What is my validation drink? Check memory."* Confirm the model calls `mcp__flair__memory_search` and returns the value.
+3. Still in session B, ask it to *use* the recalled value ("suggest one drink for the meeting"). Confirm the answer builds on it.
+
+A new DSH session is enough; a Host restart is not. Because the memory now lives in Flair rather than a local file, the same check also passes *across harnesses*: store in DSH, then `memory_search` from Claude Code or any other [MCP client](mcp-clients.md) pointed at the same Flair instance and agent.
+
+## Config reference (the fields this wiring uses)
+
+Field names verified against DSH `master` 2026-08-20; [their table](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/mcp/mcp-client/README.md) is authoritative.
+
+| Field | Value here | Notes |
+|---|---|---|
+| `serverName` | `flair` | Namespace for tool names (`mcp__flair__*`); must be unique across live instances |
+| `transport` | `stdio` | flair-mcp is a stdio server |
+| `command` / `args` | `npx` / `['-y', '@tpsdev-ai/flair-mcp@<version>']` | Or a preinstalled `flair-mcp` binary |
+| `env` | `FLAIR_AGENT_ID`, `FLAIR_URL`, optionally `FLAIR_KEY_PATH` | Merged after DSH's env scrub — the only reliable channel (see caveat 1) |
+| `toolCallTimeoutMs` | (default 60000) | Per-tool-call timeout; raise it only if slow remote searches genuinely exceed a minute |
+
+## Troubleshooting
+
+**"FLAIR_AGENT_ID is required" on startup.** The env block is missing or ambient-only — declare it in `config.env` (caveat 1).
+
+**Tools never appear.** DSH logs initial connection and discovery failures; by default a failed startup registers no tools rather than failing the plugin. Check `flair status` on the Flair side, and check the DSH logs for the `flair` server's connect errors. A duplicate `serverName: flair` across live instances fails the later instance at load.
+
+**`auth_error` on every call.** Identity/key mismatch — and remember that an exported `FLAIR_KEY_PATH` never reaches the server (caveat 1). Re-run `flair agent add <id>` (idempotent) or set `FLAIR_KEY_PATH` in `config.env`.
+
+For everything else: [troubleshooting.md](troubleshooting.md).

package/docs/entity-vocabulary.md

@@ -89,6 +89,21 @@ Per the attention-plane spec's K&S-approved refinements, `entities: [String] @in
 Existing rows on all three tables simply carry no `entities` — readers must tolerate absence,
 the same pattern already used for `Presence.activityUpdatedAt`. No migration, no backfill.
 
+All three fields are reachable from the CLI (flair#1288): `flair memory add`,
+`flair workspace set`, and `flair orgevent` take `--entities <csv>`, a comma-separated list of
+vocabulary strings:
+
+```bash
+flair memory add --agent flint --entities "repo:tpsdev-ai/flair,issue:tpsdev-ai/flair#1288" "shipped the entities CLI surface"
+```
+
+The CLI validates each value before writing (a malformed value is rejected with the
+`type:value` format and the valid type list); the server re-validates on every write path
+regardless. The CLI's validator is an inlined copy of this module
+(`src/lib/entity-vocab-cli.ts` — `src/` can't import across the packaging boundary into
+`resources/`), pinned to it by `test/unit/cli-entities-option.test.ts`; the server-side gate
+remains this module alone.
+
 `Relationship` gets **no** `entities` field: its `subject`/`object` columns already carry
 free-form entity-reference strings and are already indexed — they're the vocabulary carrier
 for that table. They are lowercased on write today but not yet validated against this

package/docs/integrations.md

@@ -17,6 +17,7 @@ Where Flair already runs. Each integration shown here is a working surface — t
 | **Gemini CLI** | [`flair-mcp`](#claude-code-cursor-codex-gemini-cli-continuedev-via-flair-mcp) | MCP config | Standard MCP server |
 | **Antigravity CLI** (`agy`) | [`flair-mcp`](#claude-code-cursor-codex-gemini-cli-continuedev-via-flair-mcp) | MCP config | `~/.gemini/config/mcp_config.json`; pickup by a live `agy` pending verification |
 | **Goose** (block/goose) | [`flair-mcp`](#claude-code-cursor-codex-gemini-cli-continuedev-via-flair-mcp) | MCP config | Goose ships native MCP support |
+| **DeepSeek Harness** (`dsh`) | [`flair-mcp`](deepseek-harness.md) | Cordis overlay | First-party MCP bridge; tools-only, reactive recall — [dedicated page](deepseek-harness.md) |
 | **LangGraph (TS)** | [`langgraph-flair`](#langgraph-typescript) | FlairClient | Drop-in `BaseStore` |
 | **OpenClaw** | [`openclaw-flair`](#openclaw) | Ed25519 | Native plugin + context engine |
 | **n8n** | [`n8n-nodes-flair`](#n8n) | FlairApi credential | Three nodes (chat memory, search, store) |