@tpsdev-ai/flair 0.30.0 → 0.31.0

package/dist/resources/migrations/data-dir.js

@@ -0,0 +1,205 @@
+/**
+ * data-dir.ts — resolves the directory the migration subsystem owns
+ * (`<dataDir>/.migrations/{state.json,lock,snapshots,exports}`), and proves
+ * it is actually usable BEFORE the boot cycle commits to it.
+ *
+ * ─── Why this file exists (flair#812) ──────────────────────────────────────
+ * The previous resolution was a single expression, duplicated in
+ * `resources/migration-boot.ts` and `resources/health.ts`:
+ *
+ *     process.env.HDB_ROOT ?? join(homedir(), ".flair", "data")
+ *
+ * Both halves of that were wrong in a way that only shows up off the
+ * developer/default shape:
+ *
+ * 1. `HDB_ROOT` IS NEVER SET BY ANYTHING. It is not a Harper process env
+ *    var — Harper's own root-path env var is `ROOTPATH`
+ *    (`harper`'s `utility/common_utils.ts` reads
+ *    `process.env['ROOTPATH']`; `HDB_ROOT` appears only as a legacy *config
+ *    key* alias in `utility/hdbTerms.ts`, and Harper never reads or writes
+ *    it on `process.env`). flair's own spawner (`src/cli.ts`) exports
+ *    `ROOTPATH`, never `HDB_ROOT`, and `resources/models-dir.ts` already
+ *    reads `ROOTPATH` for exactly this reason. So the `??` left branch was
+ *    dead code and the effective resolution was UNCONDITIONALLY
+ *    `~/.flair/data`, regardless of where Harper's real root actually is.
+ *
+ * 2. `~/.flair/data` is right only by coincidence — it is `flair init`'s
+ *    default data dir, so on a default local install the two happen to
+ *    coincide. On a PROVISIONED install (a service-managed spoke, a
+ *    container, a Harper Fabric component deployment) the process's
+ *    `homedir()` is whatever the service account has: possibly read-only,
+ *    possibly nonexistent, and in general nothing to do with the instance's
+ *    data.
+ *
+ * When `~/.flair/data` is not creatable, EVERY consumer of the old
+ * expression failed — and, critically, failed SILENTLY: the very first
+ * thing `runMigrationCycle` does is `acquireMigrationLock`, whose
+ * `mkdirSync(dirname(lockPath), { recursive: true, mode: 0o700 })` throws
+ * `EACCES`/`ENOENT`, which the runner catches and turns into
+ * `{ ran: false, reason: "lock error: ..." }` — a value `migration-boot.ts`
+ * then discarded. No log line, no state file, no health signal, and every
+ * migration ever shipped skipped forever on that instance. (Contrast
+ * `resources/embeddings-boot.ts`, loaded by the SAME `jsResource` glob:
+ * it touches no filesystem path of its own, which is exactly why embeddings
+ * kept working on the affected shapes while migrations did not.)
+ *
+ * ─── The resolution ─────────────────────────────────────────────────────
+ * An ordered candidate list, first USABLE one wins:
+ *
+ *   1. `FLAIR_MIGRATION_DATA_DIR` — explicit operator override. The escape
+ *      hatch for any deployment shape whose data dir this module cannot
+ *      infer; naming it in the failure message below is what makes an
+ *      unresolvable instance actionable rather than merely reported.
+ *   2. `HDB_ROOT` — retained purely for compatibility with anything that
+ *      may have started setting it because flair once read it. Never set by
+ *      Harper or by flair.
+ *   3. `homedir()/.flair/data` — the historical default, and `flair init`'s
+ *      own data dir. DELIBERATELY still ahead of `ROOTPATH`: on every
+ *      currently-working install this is where the state file already
+ *      lives, and reordering would silently relocate it (costing a
+ *      re-detect pass and orphaning the existing audit record) on instances
+ *      that have no problem at all. This fix is about instances where the
+ *      cycle cannot run, not about relocating ones where it can.
+ *   4. `ROOTPATH` — Harper's real root path. The rescue candidate: it is
+ *      writable by definition on a running instance (Harper is writing its
+ *      own databases there), so a shape whose `homedir()` is unusable still
+ *      gets a stable, per-instance location instead of nothing.
+ *   5. The Harper root INFERRED from this module's own location, but only
+ *      when the running layout is unambiguously a deployed component (see
+ *      `deployedComponentRootPath`). `ROOTPATH` is an env var, and a
+ *      deployment that configures `rootPath` in Harper's config file
+ *      instead of the environment leaves candidate 4 empty — this covers
+ *      that case without guessing.
+ *
+ * "Usable" is probed by DOING THE REAL OPERATION the runner would do —
+ * create `<dir>/.migrations` at 0700 and check it is writable — not by a
+ * proxy check that could disagree with it. The probe is idempotent and, on
+ * a healthy instance, is satisfied by the first candidate without touching
+ * the others.
+ *
+ * If NO candidate is usable, `resolveWritableMigrationDataDir` returns
+ * `dataDir: null` WITH the per-candidate reasons, and the boot path turns
+ * that into a loud console error plus a `failed` progress entry per
+ * registered migration — visible in `/HealthDetail`, `flair doctor` and
+ * `flair quality`'s `instance.migrationsClean`. An instance that cannot run
+ * migrations now says so; that silence was the actual defect.
+ */
+import { accessSync, constants, existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/** Explicit operator override for the migration data dir (see module doc). */
+export const MIGRATION_DATA_DIR_ENV = "FLAIR_MIGRATION_DATA_DIR";
+/** The subdirectory the migration subsystem owns inside whichever dataDir wins. */
+export const MIGRATIONS_SUBDIR = ".migrations";
+/**
+ * Harper's root path, inferred from where THIS module is running, but ONLY
+ * when the layout is unambiguously a deployed component:
+ *
+ *     <rootPath>/components/<name>/dist/resources/migrations/data-dir.js
+ *
+ * i.e. the directory two levels above `dist/` must itself be named
+ * `components` — Harper's `componentsRoot` convention, and the layout
+ * `deploy_component` produces. That check is what keeps this from firing on
+ * a source checkout or an npm install, where the same arithmetic would
+ * point at an arbitrary parent directory. Returns null whenever the layout
+ * doesn't match, so a non-match contributes no candidate rather than a
+ * guess.
+ *
+ * `moduleUrl` is a parameter purely so a unit test can exercise both the
+ * matching and non-matching layouts without relocating the built file.
+ */
+export function deployedComponentRootPath(moduleUrl = import.meta.url) {
+    try {
+        const here = dirname(fileURLToPath(moduleUrl)); // <component>/dist/resources/migrations
+        const componentDir = dirname(dirname(dirname(here))); // <component>
+        const componentsRoot = dirname(componentDir); // .../components
+        if (basename(componentsRoot) !== "components")
+            return null;
+        return dirname(componentsRoot);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Ordered candidates for the migration data dir. See the module doc for why
+ * this order is what it is — in particular, why `homedir()/.flair/data`
+ * stays ahead of `ROOTPATH`.
+ */
+export function migrationDataDirCandidates(env = process.env, moduleUrl = import.meta.url) {
+    const out = [];
+    const add = (p) => {
+        const trimmed = p?.trim();
+        if (trimmed && !out.includes(trimmed))
+            out.push(trimmed);
+    };
+    add(env[MIGRATION_DATA_DIR_ENV]);
+    add(env.HDB_ROOT);
+    add(join(homedir(), ".flair", "data"));
+    add(env.ROOTPATH);
+    add(deployedComponentRootPath(moduleUrl));
+    return out;
+}
+/**
+ * Probes a candidate by performing the exact operation the runner's lock
+ * acquisition performs (`mkdir -p <dir>/.migrations` at 0700), then
+ * confirming the result is writable. Idempotent: on an already-working
+ * instance this is a no-op stat/mkdir against a directory that already
+ * exists.
+ */
+export function probeMigrationDataDir(dir) {
+    const owned = join(dir, MIGRATIONS_SUBDIR);
+    try {
+        mkdirSync(owned, { recursive: true, mode: 0o700 });
+        accessSync(owned, constants.W_OK | constants.X_OK);
+        return { dir, ok: true };
+    }
+    catch (err) {
+        return { dir, ok: false, reason: err?.message ?? String(err) };
+    }
+}
+/**
+ * Resolves a migration data dir that is proven writable, or reports why not.
+ * Used by the boot path (`resources/migration-boot.ts`), which must not
+ * commit to a directory the runner will then fail to lock.
+ */
+export function resolveWritableMigrationDataDir(env = process.env) {
+    const tried = [];
+    for (const candidate of migrationDataDirCandidates(env)) {
+        const probe = probeMigrationDataDir(candidate);
+        tried.push(probe);
+        if (probe.ok)
+            return { dataDir: candidate, tried };
+    }
+    return { dataDir: null, tried };
+}
+/**
+ * Operator-facing explanation of a total resolution failure — carries the
+ * actor (each path tried), the state (why each was rejected) and the remedy
+ * (the override env var), so the message is actionable at 3am rather than
+ * merely accurate.
+ */
+export function describeUnresolvableDataDir(tried) {
+    const detail = tried.length
+        ? tried.map((t) => `${t.dir} (${t.reason ?? "unusable"})`).join("; ")
+        : "no candidate paths at all";
+    return (`no writable migration data directory — tried ${detail}. ` +
+        `Migrations cannot run on this instance until one exists: point ${MIGRATION_DATA_DIR_ENV} ` +
+        `at a writable directory (or make one of the paths above writable by the account this ` +
+        `instance runs as) and restart.`);
+}
+/**
+ * READ-ONLY counterpart for `/HealthDetail`, which must never create
+ * directories as a side effect of a GET. Prefers whichever candidate
+ * already carries a `.migrations` directory (i.e. the one a boot actually
+ * chose), falling back to the first candidate so the field is never empty.
+ */
+export function resolveMigrationDataDirForRead(env = process.env) {
+    const candidates = migrationDataDirCandidates(env);
+    for (const candidate of candidates) {
+        if (existsSync(join(candidate, MIGRATIONS_SUBDIR)))
+            return candidate;
+    }
+    return candidates[0] ?? join(homedir(), ".flair", "data");
+}

package/dist/resources/migrations/progress.js

@@ -25,6 +25,39 @@ export function seedIdleProgress(ids) {
         }
     }
 }
+/**
+ * Marks every migration that never got off the starting line as `failed`
+ * with `reason` — and ONLY those (flair#812).
+ *
+ * The boot path calls this when a cycle couldn't run, so that a condition
+ * which is really instance-wide (no writable data dir, tables never ready,
+ * the lock itself unobtainable) shows up per-migration, which is the shape
+ * `flair doctor` and `flair quality`'s `instance.migrationsClean` actually
+ * read.
+ *
+ * Restricting it to `idle` entries is load-bearing, not tidiness: a cycle
+ * can fail AFTER some migrations already reached a terminal state — the
+ * pre-hash path, for instance, halts each candidate with its own precise
+ * reason and THEN reports cycle failure. Overwriting those would replace a
+ * specific `halted` (which the runner retries on the next boot, per its
+ * documented contract) with a blanket `failed`, and would flip migrations
+ * that genuinely completed this cycle to failed. Only an entry still `idle`
+ * is one nothing has said anything about yet.
+ *
+ * Returns the ids actually marked, so a caller can tell "nothing had
+ * started" from "the cycle died partway".
+ */
+export function markIdleMigrationsFailed(ids, reason) {
+    const marked = [];
+    for (const id of ids) {
+        const current = progressById.get(id);
+        if (current && current.state !== "idle")
+            continue;
+        progressById.set(id, { id, rowsDone: 0, rowsRemaining: 0, state: "failed", reason });
+        marked.push(id);
+    }
+    return marked;
+}
 export function _resetProgressForTests() {
     progressById.clear();
     cycleStatus = { phase: "idle" };

package/dist/resources/migrations/runner.js

@@ -151,7 +151,21 @@ async function runCycleLocked(deps, lock) {
     const candidates = [];
     for (const migration of deps.registry.list()) {
         if (isShortCircuited(state, migration.id, deps.runningVersion)) {
-            setMigrationProgress({ id: migration.id, rowsDone: 0, rowsRemaining: 0, state: "completed" });
+            // flair#812: a short-circuit is an ASSERTION READ OFF A FILE, not an
+            // observation of the corpus — and that file is hand-editable (the
+            // documented remediation for a stuck migration is to correct it by
+            // hand). Reporting it as plain "completed" made a hand-written entry
+            // indistinguishable from a migration this boot actually verified.
+            // The skip itself is unchanged (it is the documented cheap path); it
+            // now just says what it is, so `flair doctor` never presents an
+            // unverified claim as a verified one.
+            setMigrationProgress({
+                id: migration.id,
+                rowsDone: 0,
+                rowsRemaining: 0,
+                state: "completed",
+                reason: `recorded complete at ${deps.runningVersion} in ${deps.statePath} — not re-verified this boot`,
+            });
             continue;
         }
         setMigrationProgress({ id: migration.id, rowsDone: 0, rowsRemaining: 0, state: "checking" });
@@ -160,12 +174,18 @@ async function runCycleLocked(deps, lock) {
             pending = await migration.detect();
         }
         catch (err) {
+            // flair#812: a throwing detect() removes this migration from the
+            // candidate set, so a cycle where EVERY detect() throws used to reach
+            // the `nothing pending` return and look like a clean no-op. Log it
+            // with the standard marker as well as recording it in progress.
+            const reason = `detect() threw: ${err?.message ?? String(err)}`;
+            console.error(`[flair-migrations] ${migration.id}: ${reason}`);
             setMigrationProgress({
                 id: migration.id,
                 rowsDone: 0,
                 rowsRemaining: 0,
                 state: "failed",
-                reason: `detect() threw: ${err?.message ?? String(err)}`,
+                reason,
             });
             continue;
         }
@@ -176,6 +196,13 @@ async function runCycleLocked(deps, lock) {
         candidates.push(migration);
     }
     if (candidates.length === 0) {
+        // flair#812: mark the cycle done even on the no-op path. "Nothing was
+        // pending" and "the cycle never ran" are opposite conclusions that used
+        // to produce an IDENTICAL `/HealthDetail` reading (`cyclePhase: "idle",
+        // lastCycleAt: null`), which is exactly why a totally-skipped boot cycle
+        // looked healthy for months. A cycle that reached this line has done its
+        // job, and now says so.
+        setCyclePhase("done");
         return { ran: false, reason: "nothing pending" };
     }
     // ── ONE shared async pre-hash at cycle start (K&S: computed after ready,

package/dist/resources/migrations/state.js

@@ -30,11 +30,22 @@ export function readMigrationState(path) {
         if (!existsSync(path))
             return {};
         const raw = JSON.parse(readFileSync(path, "utf-8"));
-        return raw && typeof raw === "object" ? raw : {};
+        if (raw && typeof raw === "object")
+            return raw;
+        console.warn(`[flair-migrations] ${path} is not a JSON object — ignoring it and re-detecting every migration this boot`);
+        return {};
     }
-    catch {
+    catch (err) {
         // Corrupt/unreadable state — treat as "nothing known yet", never throw.
         // Worst case this costs one extra (cheap, bounded) detect() call.
+        //
+        // flair#812: but SAY SO. This file is hand-edited in practice (the
+        // documented remediation for a stuck migration), and a fat-fingered
+        // edit silently discarding every recorded outcome is precisely the
+        // class of quiet failure this issue is about. The behaviour is
+        // unchanged and still safe — only the silence is fixed.
+        console.warn(`[flair-migrations] could not read ${path} (${err?.message ?? String(err)}) — ` +
+            `treating migration state as empty and re-detecting every migration this boot`);
         return {};
     }
 }

package/dist/resources/models-dir.js

@@ -1,25 +1,34 @@
 /**
  * models-dir.ts — the ONE place that decides where model GGUFs live.
  *
- * Extracted from embeddings-provider.ts (flair#815) so the reranker
- * (rerank-provider.ts) can share the exact same resolution WITHOUT importing
+ * Extracted from embeddings-provider.ts (flair#815) so a second model
+ * consumer could share the exact same resolution WITHOUT importing
  * embeddings-provider: several unit-isolated tests `mock.module()` the whole
  * embeddings-provider module (with only the named exports THEY consume), and
  * bun's module cache is process-wide — so any new cross-module import of
  * embeddings-provider from another resource makes those mocks incomplete and
  * kills unrelated test files at module load. This module is tiny, pure
- * node-stdlib, and never mocked, so both providers (and any future model
- * consumer) can depend on it safely.
+ * node-stdlib, and never mocked, so any model consumer can depend on it
+ * safely.
+ *
+ * The second consumer that motivated the split (the cross-encoder reranker)
+ * has since been removed (flair#893), leaving the embedding engine as the
+ * only caller. The module stays split anyway, and deliberately: the
+ * `mock.module()` hazard above is a property of embeddings-provider, not of
+ * the reranker, so folding this back in would re-arm it for whatever the next
+ * model consumer turns out to be. It is also the single documented source of
+ * truth for the models dir, independently tested as such.
  */
 import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 /**
- * Resolve the directory model GGUFs live in / download into — shared by the
- * embedding engine (embeddings-boot.ts's `register()` options) and the
- * cross-encoder reranker (rerank-provider.ts, flair#815 — it used to hardcode
- * `<cwd>/models`, silently failing open wherever Harper's cwd wasn't the
- * models location).
+ * Resolve the directory model GGUFs live in / download into — used by the
+ * embedding engine (embeddings-boot.ts's `register()` options), and the
+ * resolution any future model consumer should use rather than re-deriving its
+ * own. flair#815 exists because a consumer that hardcoded `<cwd>/models`
+ * silently failed open wherever Harper's cwd wasn't the models location; the
+ * fix was to give the decision exactly one home, which is this function.
  *
  * Resolution order (everything writable, never the read-only package dir):
  *   1. FLAIR_MODELS_DIR        — explicit operator/docker override.

package/dist/resources/semantic-retrieval-core.js

@@ -3,8 +3,8 @@
 // Extracted from resources/SemanticSearch.ts's post() (Kern-approved
 // refactor, flair#695). Before this module existed,
 // SemanticSearch.post() was one function entangling auth resolution,
-// rate-limiting, HNSW/BM25 retrieval, post-retrieval filtering, the
-// cross-encoder reranker, AND retrievalCount/lastRetrieved hit-tracking side
+// rate-limiting, HNSW/BM25 retrieval, post-retrieval filtering, AND
+// retrievalCount/lastRetrieved hit-tracking side
 // effects — so the ONLY way for MemoryBootstrap (resources/MemoryBootstrap.ts)
 // to get bounded, HNSW-pushed-down candidates was to duplicate the retrieval
 // logic or trip the side effects (an internal bootstrap call spuriously
@@ -16,7 +16,7 @@
 // the HNSW leg query construction (sort/select/conditions/limit), the BM25 +
 // union-RRF hybrid fusion, the per-record temporal/expiry/supersede filters,
 // and the scope.isAllowed() defense-in-depth re-check. It does NOT own: auth
-// resolution, rate-limiting, the reranker, or the retrievalCount/lastRetrieved
+// resolution, rate-limiting, or the retrievalCount/lastRetrieved
 // hit-tracking side effects — those stay in SemanticSearch.post()'s wrapper
 // (resources/SemanticSearch.ts) so an internal caller (bootstrap) never trips
 // them.
@@ -32,7 +32,8 @@
 // Returns results AFTER all filters, sorted best-first by `_score` — bounded
 // ONLY by the `limit` the caller chose to push down (the core never
 // multiplies `limit` internally; any overfetch policy — SemanticSearch's
-// CANDIDATE_MULTIPLIER, rerank-topN widening — is the CALLER's decision, made
+// CANDIDATE_MULTIPLIER, MemoryBootstrap's K formula — is the CALLER's
+// decision, made
 // before calling in). Never exposes which internal leg (BM25+RRF hybrid vs.
 // legacy HNSW-only vs. keyword-only fallback) produced a given result — the
 // output shape is identical regardless of `hybrid`.

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

@@ -0,0 +1,128 @@
+/**
+ * Platform-scheduler primitives shared by every Flair-managed background job.
+ *
+ * Two modules install user-session scheduler entries today:
+ *   - src/rem/scheduler.ts        (`flair rem nightly enable`)
+ *   - src/federation/scheduler.ts (`flair federation sync enable`)
+ *
+ * They differ in what they schedule and how often; they do NOT differ in how
+ * you ask launchd/systemd whether a job is really loaded, how you read the
+ * answer, or how you render a template into a unit file. This module exists so
+ * there is exactly ONE implementation of those — same reason src/lib/xml-escape.ts
+ * exists (#918): the second copy of a subtle rule is where it goes wrong.
+ *
+ * `interpretActiveResult()` in particular encodes a production lesson
+ * (flair#850) that took a real outage to learn. It must not be re-derived.
+ */
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { platform } from "node:os";
+import { spawnSync } from "node:child_process";
+/**
+ * 30s ceiling on launchctl/systemctl invocations so a hung service manager
+ * can't block the CLI indefinitely. Sherlock #415 follow-up.
+ */
+export const SPAWN_TIMEOUT_MS = 30_000;
+/**
+ * Status-check spawns (launchctl print / systemctl is-active) return
+ * near-instantly when the service manager is reachable, and fail fast (no
+ * hang) when it isn't (e.g. "Failed to connect to bus"). A short ceiling
+ * keeps status commands and the Health endpoint responsive even when the
+ * query is inconclusive.
+ */
+export const STATUS_CHECK_TIMEOUT_MS = 5_000;
+export function detectPlatform(label, override) {
+    if (override)
+        return override;
+    const p = platform();
+    if (p === "darwin")
+        return "darwin";
+    if (p === "linux")
+        return "linux";
+    throw new Error(`unsupported platform for ${label}: ${p} (only darwin and linux)`);
+}
+export function spawnReport(cmd, timeoutMs = SPAWN_TIMEOUT_MS) {
+    const r = spawnSync(cmd[0], cmd.slice(1), {
+        encoding: "buffer",
+        timeout: timeoutMs,
+    });
+    return {
+        code: r.status,
+        stdout: r.stdout?.toString("utf-8") ?? "",
+        stderr: r.stderr?.toString("utf-8") ?? "",
+    };
+}
+/**
+ * Interprets the result of a `launchctl print` / `systemctl --user is-active`
+ * probe. Shared by the sync (CLI) and async (server) callers of both
+ * schedulers.
+ *
+ * - true  — the service manager confirms the job is loaded/active.
+ * - false — confirmed NOT active. This includes the "no session bus" case
+ *   (flair#850): when `systemctl --user` can't reach a bus, it fails
+ *   before printing a status word ("Failed to connect to bus: No medium
+ *   found") — but nothing CAN be running without a bus, so `false` is the
+ *   honest answer, not "unknown".
+ * - null  — genuinely inconclusive (the command itself couldn't run at
+ *   all — e.g. the binary is missing — with no output to interpret).
+ */
+export function interpretActiveResult(plat, code, stdout, stderr) {
+    const noOutput = !stdout.trim() && !stderr.trim();
+    if (plat === "darwin") {
+        if (code === 0)
+            return true;
+        if (code === null && noOutput)
+            return null; // spawn itself failed — inconclusive
+        return false; // launchctl ran and reported not-loaded
+    }
+    const out = stdout.trim();
+    if (out === "active" || out === "activating")
+        return true;
+    if (out === "inactive" || out === "failed" || out === "unknown")
+        return false;
+    if (code === null && noOutput)
+        return null; // spawn itself failed — inconclusive
+    return false; // covers the no-bus case: empty stdout, nonzero/failed exit
+}
+/**
+ * Human remedy text for a failed scheduler-load attempt (flair#850). Covers
+ * the one root cause traced so far: a missing systemd user session bus,
+ * which blocks `systemctl --user` entirely in ssh-without-lingering,
+ * container, and CI contexts. Returns null when the failure doesn't match a
+ * known pattern — the caller already prints the raw stderr, so the operator
+ * still has something to go on.
+ *
+ * `enableCommand` is the caller's own enable invocation, named in the remedy
+ * so the operator is told to re-run the command they actually ran.
+ */
+export function describeLoadFailure(plat, loadResult, enableCommand) {
+    const stderr = loadResult.stderr || "";
+    if (plat === "linux" && /failed to connect to bus/i.test(stderr)) {
+        return ("No systemd user session bus is available in this session (common over ssh without lingering, " +
+            "in containers, or under CI). Fix: enable lingering for this user — `loginctl enable-linger <user>` " +
+            `— then re-run \`${enableCommand}\`.`);
+    }
+    return null;
+}
+/** Single-pass `{{KEY}}` substitution, with a per-value escape hook. */
+export function renderTemplateWith(text, subs, escape) {
+    return text.replace(/\{\{([A-Z_]+)\}\}/g, (_, key) => {
+        const value = subs[key];
+        if (value === undefined)
+            throw new Error(`unknown template placeholder: ${key}`);
+        return escape(String(value));
+    });
+}
+export function readTemplate(rootDir, relativePath) {
+    const full = resolve(rootDir, relativePath);
+    if (!existsSync(full)) {
+        throw new Error(`template not found: ${full}`);
+    }
+    return readFileSync(full, "utf-8");
+}
+export function writeFileWithDir(path, contents, mode = 0o600) {
+    const dir = dirname(path);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    writeFileSync(path, contents, { mode });
+}

package/dist/src/lib/xml-escape.js

@@ -0,0 +1,54 @@
+/**
+ * XML entity escaping for the launchd plists this CLI generates.
+ *
+ * A launchd plist is XML, so ANY value interpolated into one has to be
+ * escaped or the document is malformed — and `launchctl load` rejects a
+ * malformed plist outright, so the service silently never registers.
+ *
+ * Two independent writers generate plists, and both go through here:
+ *   - buildLaunchdPlist() in src/cli.ts (the Harper service, `flair init`)
+ *   - renderPlistTemplate() in src/rem/scheduler.ts (`flair rem nightly enable`)
+ *
+ * This module exists so there is exactly ONE implementation to get right.
+ * Anything that interpolates into plist XML imports it rather than
+ * hand-rolling a `.replace()` chain at the call site — a local chain is how
+ * this class of bug got in (and how it stayed partial: the original one
+ * covered three of the five entities).
+ */
+/** The five XML predefined entities, in the order they must be replaced. */
+const XML_ESCAPES = [
+    // `&` MUST be first: replacing it after `<` would turn the `&` of an
+    // already-emitted `&lt;` into `&amp;lt;` and corrupt the value.
+    [/&/g, "&amp;"],
+    [/</g, "&lt;"],
+    [/>/g, "&gt;"],
+    [/"/g, "&quot;"],
+    [/'/g, "&apos;"],
+];
+/**
+ * Escape the five XML predefined entities for use inside an XML text node.
+ *
+ * Safe to apply to any string, including one with no special characters.
+ * The result round-trips exactly through unescapeXml().
+ */
+export function escapeXml(s) {
+    let out = s;
+    for (const [pattern, replacement] of XML_ESCAPES)
+        out = out.replace(pattern, replacement);
+    return out;
+}
+/**
+ * Inverse of escapeXml(), for reading a value back out of a document we wrote.
+ *
+ * `&amp;` MUST be decoded LAST, mirroring escapeXml()'s ordering: decoding it
+ * first would turn `&amp;lt;` (the escaping of a literal "&lt;") into `<`
+ * instead of back into `&lt;`.
+ */
+export function unescapeXml(s) {
+    return s
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'")
+        .replace(/&amp;/g, "&");
+}