@tpsdev-ai/flair 0.45.0 → 0.47.0

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

@@ -13,9 +13,15 @@
  *
  * `interpretActiveResult()` in particular encodes a production lesson
  * (flair#850) that took a real outage to learn. It must not be re-derived.
+ * flair#1231 extended it one layer deeper: a load command exiting 0 proves the
+ * service manager ACCEPTED the job, not that the job can RUN — two fleet
+ * incidents (a stripped exec bit, a missing log directory) both passed the
+ * load check and died on the first real run, invisibly. The rule now encoded
+ * in `verifyFirstRun()`: success may not be claimed until the thing the
+ * operator asked for has been observed to happen once.
  */
 import { existsSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
-import { resolve, dirname } from "node:path";
+import { resolve, dirname, isAbsolute } from "node:path";
 import { platform } from "node:os";
 import { spawnSync } from "node:child_process";
 /**
@@ -126,3 +132,359 @@ export function writeFileWithDir(path, contents, mode = 0o600) {
         mkdirSync(dir, { recursive: true, mode: 0o700 });
     writeFileSync(path, contents, { mode });
 }
+// ─── node binary resolution (flair#1231) ────────────────────────────────────
+/**
+ * Resolves the ABSOLUTE path to the node binary at enable time, so the shim
+ * can `exec "<node>" "<script>"` with ZERO PATH lookups at run time.
+ *
+ * Why this exists: the shims switched from `exec "{{FLAIR_BIN}}"` (which
+ * required an exec bit that tarball extraction strips — the #1231 regression)
+ * to running the CLI under node, which needs read permission only. But a bare
+ * `exec node …` would introduce a run-time PATH lookup the old absolute-path
+ * form never had: whatever PATH the service manager's environment carries
+ * would pick the `node` that runs with the operator's credentials. So the
+ * node path is resolved HERE, once, from the enabling process's own
+ * environment, and baked into the shim — symmetric with how FLAIR_BIN is
+ * already handled.
+ *
+ * Resolution order:
+ *   1. `explicit` — caller/test override.
+ *   2. `process.execPath` when the enabling runtime IS node (the published
+ *      CLI's case): absolute, known-good, already trusted to run this code.
+ *   3. `command -v node` in the enabling shell environment (dev/test under
+ *      bun): the one deliberate PATH consultation, made at enable time by the
+ *      operator's own session, never later by the service manager.
+ * Nothing resolvable ⇒ throw — enable must fail loudly rather than bake a
+ * run-time lookup into the shim.
+ */
+export function resolveNodeBin(explicit) {
+    if (explicit)
+        return explicit;
+    if (!process.versions.bun && process.execPath && isAbsolute(process.execPath)) {
+        return process.execPath;
+    }
+    const r = spawnReport(["/bin/sh", "-c", "command -v node"], STATUS_CHECK_TIMEOUT_MS);
+    const found = r.stdout.trim().split("\n")[0]?.trim() ?? "";
+    if (r.code === 0 && found && isAbsolute(found) && existsSync(found))
+        return found;
+    throw new Error("unable to resolve an absolute path to a node binary (not running under node, and `command -v node` " +
+        "found nothing). The scheduler shim runs `<node> <flair-script>` with the node path baked in at " +
+        "enable time — refusing to install a shim that would resolve `node` from the service manager's PATH " +
+        "at run time. Install node (or put it on PATH for this shell) and re-run enable.");
+}
+// ─── first-run verification (flair#1231) ────────────────────────────────────
+// A load/bootstrap command exiting 0 proves the service manager accepted the
+// job — not that the job can run. The only vantage that exercises the real
+// failure modes (launchd spawn error 209 from a missing log dir, exit 126
+// from a stripped exec bit) is the service manager itself, so the first run
+// is triggered and observed THROUGH it, never via a bare spawn of the shim.
+/** Poll cadence for darwin `launchctl print` first-run polling. */
+export const FIRST_RUN_POLL_INTERVAL_MS = 150;
+/** Total budget for first-run verification on both platforms. */
+export const FIRST_RUN_BUDGET_MS = 12_000;
+/** Synchronous sleep without spawning anything. */
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/**
+ * Parses `launchctl print <domain>/<label>` for run state. `last exit code`
+ * is absent (or "(never exited)") until a run has completed, and `pid =` /
+ * `state = running` are present only while one is in flight.
+ */
+export function parseLaunchdPrintExit(output) {
+    const running = /^\s*state\s*=\s*(?:running|spawn)/m.test(output) || /^\s*pid\s*=\s*\d+/m.test(output);
+    const m = /last exit (?:code|status)\s*=\s*(-?\d+)/.exec(output);
+    return { running, lastExitCode: m ? Number(m[1]) : null };
+}
+/** Parses `systemctl --user show <unit> --property=ExecMainStatus,Result`. */
+export function parseSystemdShowExit(output) {
+    const m = /^ExecMainStatus=(-?\d+)\s*$/m.exec(output);
+    const r = /^Result=(\S+)\s*$/m.exec(output);
+    return { execMainStatus: m ? Number(m[1]) : null, result: r ? r[1] : null };
+}
+/** Reads the last lines of a log file for failure diagnostics. Never throws. */
+export function readLogTail(path, maxLines = 12, maxChars = 1500) {
+    let text;
+    try {
+        text = readFileSync(path, "utf-8");
+    }
+    catch {
+        return { exists: false, empty: false, tail: "" };
+    }
+    const trimmed = text.trimEnd();
+    if (!trimmed)
+        return { exists: true, empty: true, tail: "" };
+    let tail = trimmed.split("\n").slice(-maxLines).join("\n");
+    if (tail.length > maxChars)
+        tail = tail.slice(-maxChars);
+    return { exists: true, empty: false, tail };
+}
+/**
+ * Names the failure class for a recorded exit status, so the report can lead
+ * with actor+state instead of a bare number.
+ */
+export function describeExitCode(code) {
+    if (code === null)
+        return "no exit status recorded";
+    if (code === 126)
+        return "exit 126 — found but not runnable (permission denied / exec format)";
+    if (code === 127)
+        return "exit 127 — command not found";
+    if (code === 209)
+        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();
+}
+/**
+ * Triggers the job's first run through the service manager and reads back how
+ * it ended (flair#1231). Call ONLY after the load/bootstrap command exited 0 —
+ * a load failure is its own failure mode with its own remedy, and layering a
+ * kickstart on top of it would blur which actor failed.
+ *
+ * darwin: `launchctl kickstart -k` returns immediately (it does NOT block for
+ * exit), so the recorded exit status is POLLED out of `launchctl print` until
+ * a completed run is visible or the budget lapses. linux: `systemctl --user
+ * start` on a oneshot blocks until the run exits, so a single
+ * `systemctl --user show` read afterwards suffices.
+ *
+ * "Can't tell" is its own state: a missing/unreachable service manager yields
+ * outcome "manager-unavailable", distinct from "run-failed" — the remedy
+ * points at the service manager, not at the job.
+ */
+export function verifyFirstRun(opts) {
+    const run = opts.hooks?.run ?? ((cmd, timeoutMs) => spawnReport(cmd, timeoutMs));
+    const sleep = opts.hooks?.sleep ?? sleepSync;
+    const now = opts.hooks?.now ?? Date.now;
+    const pollIntervalMs = opts.pollIntervalMs ?? FIRST_RUN_POLL_INTERVAL_MS;
+    const budgetMs = opts.budgetMs ?? FIRST_RUN_BUDGET_MS;
+    const finish = (outcome, exitCode, detail) => {
+        const log = outcome === "success"
+            ? { exists: false, empty: false, tail: "" } // no diagnostics needed on success
+            : readLogTail(opts.stderrLogPath);
+        return {
+            verified: outcome === "success",
+            outcome,
+            exitCode,
+            detail,
+            logPath: opts.stderrLogPath,
+            stderrTail: log.tail,
+            logEmpty: log.exists && log.empty,
+            budgetMs,
+        };
+    };
+    if (opts.plat === "darwin") {
+        const target = opts.darwinTarget;
+        if (!target)
+            throw new Error("verifyFirstRun: darwinTarget is required on darwin");
+        const kickCmd = ["launchctl", "kickstart", "-k", target];
+        const kick = run(kickCmd, SPAWN_TIMEOUT_MS);
+        if (spawnedNothing(kick)) {
+            return finish("manager-unavailable", null, `launchctl could not be run (${kickCmd.join(" ")})`);
+        }
+        if (kick.code !== 0) {
+            return finish("start-failed", null, `${kickCmd.join(" ")} → code ${kick.code}${kick.stderr.trim() ? `: ${kick.stderr.trim()}` : ""}`);
+        }
+        const deadline = now() + budgetMs;
+        // Poll: kickstart returned immediately, so watch `launchctl print` until a
+        // COMPLETED run (not running + a recorded exit code) is visible.
+        for (;;) {
+            const printCmd = ["launchctl", "print", target];
+            const r = run(printCmd, STATUS_CHECK_TIMEOUT_MS);
+            if (spawnedNothing(r)) {
+                return finish("manager-unavailable", null, `launchctl could not be run (${printCmd.join(" ")})`);
+            }
+            if (r.code === 0) {
+                const { running, lastExitCode } = parseLaunchdPrintExit(r.stdout);
+                if (!running && lastExitCode !== null) {
+                    return lastExitCode === 0
+                        ? finish("success", 0, `${printCmd.join(" ")} → last exit code = 0`)
+                        : finish("run-failed", lastExitCode, `${printCmd.join(" ")} → last exit code = ${lastExitCode}`);
+                }
+            }
+            if (now() >= deadline) {
+                return finish("timeout", null, `no completed run visible in ${printCmd.join(" ")} within ${Math.round(budgetMs / 1000)}s`);
+            }
+            sleep(pollIntervalMs);
+        }
+    }
+    // linux
+    const unit = opts.linuxServiceUnit;
+    if (!unit)
+        throw new Error("verifyFirstRun: linuxServiceUnit is required on linux");
+    const startCmd = ["systemctl", "--user", "start", unit];
+    const start = run(startCmd, budgetMs);
+    if (spawnedNothing(start)) {
+        return finish("manager-unavailable", null, `systemctl could not be run (${startCmd.join(" ")})`);
+    }
+    if (/failed to connect to bus/i.test(start.stderr)) {
+        return finish("manager-unavailable", null, `${startCmd.join(" ")} → ${start.stderr.trim()}`);
+    }
+    if (start.code === null) {
+        return finish("timeout", null, `${startCmd.join(" ")} did not return within ${Math.round(budgetMs / 1000)}s`);
+    }
+    const showCmd = ["systemctl", "--user", "show", unit, "--property=ExecMainStatus,Result"];
+    const show = run(showCmd, STATUS_CHECK_TIMEOUT_MS);
+    const parsed = parseSystemdShowExit(show.stdout);
+    if (start.code === 0) {
+        // A blocking start of a oneshot exits 0 only when the run succeeded; the
+        // show read supplies the recorded status for the report.
+        return finish("success", parsed.execMainStatus ?? 0, `${startCmd.join(" ")} → ok`);
+    }
+    const resultTxt = parsed.result ? `, Result=${parsed.result}` : "";
+    return finish("run-failed", parsed.execMainStatus, `${startCmd.join(" ")} → code ${start.code}${resultTxt}${start.stderr.trim() ? `: ${start.stderr.trim()}` : ""}`);
+}

package/dist/src/rem/scheduler.js

@@ -13,23 +13,29 @@
  * No daemon code lives here — the scheduler invokes the shim, the shim
  * invokes `flair rem nightly run-once`, the runner module does the work.
  */
-import { existsSync, chmodSync, rmSync } from "node:fs";
+import { existsSync, mkdirSync, chmodSync, rmSync } from "node:fs";
 import { resolve, dirname } from "node:path";
 import { homedir } from "node:os";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { escapeXml } from "../lib/xml-escape.js";
-import { detectPlatform as detectPlatformFor, spawnReport, readTemplate as readTemplateFrom, renderTemplateWith, writeFileWithDir, interpretActiveResult, describeLoadFailure as describeLoadFailureFor, STATUS_CHECK_TIMEOUT_MS, } from "../lib/scheduler-platform.js";
+import { detectPlatform as detectPlatformFor, spawnReport, readTemplate as readTemplateFrom, renderTemplateWith, writeFileWithDir, interpretActiveResult, describeLoadFailure as describeLoadFailureFor, describeExitCode, resolveNodeBin, verifyFirstRun, STATUS_CHECK_TIMEOUT_MS, } from "../lib/scheduler-platform.js";
 // Re-exported so this module's public surface is unchanged by the extraction
 // into src/lib/scheduler-platform.ts (a second scheduler — `flair federation
 // sync enable` — needs the identical launchctl/systemctl interpretation, and
 // 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);
 }
@@ -87,15 +93,16 @@ function validateSchedule(hour, minute) {
         throw new Error(`minute must be an integer 0-59, got ${minute}`);
     }
 }
-function buildSubstitutions(opts, shimPath, flairBin) {
+function buildSubstitutions(opts, shimPath, flairBin, nodeBin) {
     validateSchedule(opts.hour, opts.minute);
     if (!/^[a-zA-Z0-9_-]+$/.test(opts.agentId)) {
         throw new Error(`invalid agent id: ${opts.agentId}`);
     }
     return {
         FLAIR_BIN: flairBin,
+        NODE_BIN: nodeBin,
         SHIM_PATH: shimPath,
-        HOME: homedir(),
+        HOME: opts.homeOverride ?? homedir(),
         AGENT_ID: opts.agentId,
         FLAIR_URL: opts.flairUrl,
         HOUR: String(opts.hour),
@@ -112,9 +119,9 @@ function buildSubstitutions(opts, shimPath, flairBin) {
  */
 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`).
@@ -183,10 +190,14 @@ export function describeLoadFailure(plat, loadResult) {
  * succeeded) is unit-testable without spawning a real launchctl/systemctl or
  * parsing CLI argv.
  *
- * `r.loadResult` is only set when the load command actually ran (the CLI
- * never sets `skipLoad`). A missing `loadResult` (test-only path) is treated
- * as success — matches the CLI's real-world behavior, which always runs the
- * load command and therefore always gets a `loadResult`.
+ * flair#1231 deepened the #850 rule by one layer: activation exiting 0 proves
+ * the service manager ACCEPTED the job, not that the job can run — a stripped
+ * exec bit and a missing log directory both passed activation and killed the
+ * first real run invisibly. So the ✅ headline is now additionally gated on
+ * `firstRunVerified`: success may not be claimed until the thing the operator
+ * asked for — a REM run through the service manager — has been observed to
+ * happen once. A missing `loadResult`/`firstRun` (test-only skipLoad shape)
+ * therefore withholds the headline too, instead of being treated as success.
  */
 export function formatEnableReport(r, input) {
     const { hour, minute, agentId, flairUrl } = input;
@@ -212,6 +223,57 @@ export function formatEnableReport(r, input) {
         lines.push(`   Nothing is scheduled until activation succeeds. Check anytime with: flair rem nightly status`);
         return { lines, ok: false };
     }
+    if (!r.firstRunVerified) {
+        const fr = r.firstRun;
+        const headline = fr?.outcome === "run-failed"
+            ? `⚠️  REM nightly scheduler installed but the first run FAILED (${describeExitCode(fr.exitCode)})`
+            : fr?.outcome === "timeout"
+                ? `⚠️  REM nightly scheduler installed but the first run did not complete within ${Math.round(fr.budgetMs / 1000)}s — cannot confirm it works`
+                : fr?.outcome === "manager-unavailable"
+                    ? `⚠️  REM nightly scheduler installed but the service manager is unreachable — cannot verify the first run`
+                    : fr?.outcome === "start-failed"
+                        ? `⚠️  REM nightly scheduler installed but the first run could not be started`
+                        : `⚠️  REM nightly scheduler installed but the first run was never verified`;
+        const lines = [
+            headline,
+            `   Schedule:    ${scheduleTime} local time`,
+            `   Scheduler:   ${r.schedulerPath}`,
+            `   Shim:        ${r.shimPath}`,
+            `   Agent:       ${agentId}`,
+            `   Flair URL:   ${flairUrl}`,
+        ];
+        if (r.loadResult)
+            lines.push(`   Load:        ${r.loadCommand.join(" ")} → ok`);
+        if (fr) {
+            lines.push(`   First run:   ${fr.detail}`);
+            if (fr.stderrTail) {
+                lines.push(`   Log tail (${fr.logPath}):`);
+                for (const l of fr.stderrTail.split("\n"))
+                    lines.push(`     ${l}`);
+            }
+            else if (fr.logEmpty) {
+                lines.push(`   Log file ${fr.logPath} exists but is EMPTY — the run died before writing anything.`);
+            }
+            else {
+                lines.push(`   No log file at ${fr.logPath}.`);
+            }
+        }
+        lines.push("");
+        if (fr?.outcome === "timeout") {
+            lines.push(`   The run may legitimately still be going (a REM cycle can be slow). Check the log above and`);
+            lines.push(`   \`flair rem nightly status\`; no cycle has been CONFIRMED to work yet.`);
+        }
+        else if (fr?.outcome === "manager-unavailable") {
+            lines.push(`   The scheduler files are installed, but launchctl/systemctl could not be consulted, so whether`);
+            lines.push(`   the nightly cycle runs is UNKNOWN. Fix the service manager for this session, then re-run \`flair rem nightly enable\`.`);
+        }
+        else {
+            lines.push(`   No REM cycle has run. Fix the cause above, then re-run \`flair rem nightly enable\`.`);
+        }
+        lines.push("");
+        lines.push(`   Check anytime with: flair rem nightly status`);
+        return { lines, ok: false };
+    }
     const lines = [
         `✅ REM nightly scheduler enabled (${r.platform})`,
         `   Schedule:    ${scheduleTime} local time`,
@@ -223,9 +285,9 @@ export function formatEnableReport(r, input) {
     if (r.loadResult) {
         lines.push(`   Load:        ${r.loadCommand.join(" ")} → ok`);
     }
+    lines.push(`   First run:   completed through the service manager, exit 0`);
     lines.push("");
-    lines.push(`Tip: run \`flair rem nightly run-once --dry-run\` to verify the cycle works`);
-    lines.push(`     before the first scheduled fire. Disable with \`flair rem nightly disable\`.`);
+    lines.push(`Disable with \`flair rem nightly disable\`.`);
     return { lines, ok: true };
 }
 /**
@@ -268,9 +330,29 @@ export function formatStatusReport(s) {
 export function enableScheduler(opts) {
     const plat = detectPlatform(opts.platformOverride);
     const flairBin = opts.flairBin ?? process.argv[1] ?? "flair";
+    const nodeBin = resolveNodeBin(opts.nodeBin);
     const shimPath = opts.shimPathOverride ?? SHIM_PATH_DEFAULT;
     const templateRoot = opts.templateRootOverride ?? defaultTemplateRoot();
-    const subs = buildSubstitutions(opts, shimPath, flairBin);
+    const subs = buildSubstitutions(opts, shimPath, flairBin, nodeBin);
+    // 0. Create the log directory the unit files point stdout/stderr at.
+    // Nothing else ever creates it — launchd kills a job whose StandardOutPath
+    // directory is missing (spawn error 209) and systemd fails the unit (#1231).
+    //
+    // Mode 0700 is load-bearing, NOT cosmetic: REM's nightly log carries
+    // distillation CANDIDATE CONTENT — actual memory text, not just counts.
+    // Relaxing it to 0755 (e.g. "for shared debugging") would expose memory
+    // content to every local user.
+    const logsDir = resolve(subs.HOME, ".flair", "logs");
+    try {
+        mkdirSync(logsDir, { recursive: true, mode: 0o700 });
+    }
+    catch (err) {
+        throw new Error(`could not create the scheduler log directory ${logsDir}: ${err?.message ?? err}. ` +
+            `The service manager writes the job's stdout/stderr there; without it the first run dies ` +
+            `before producing any output. Fix whatever blocks creating that directory, then re-run ` +
+            `\`flair rem nightly enable\`.`);
+    }
+    const stderrLogPath = resolve(logsDir, "rem-nightly.stderr.log");
     // 1. Deploy the shim (always — both platforms invoke it).
     const shimContents = renderTemplate(readTemplate(templateRoot, "bin/flair-rem-nightly.sh.tmpl"), subs);
     writeFileWithDir(shimPath, shimContents, 0o700);
@@ -282,12 +364,26 @@ export function enableScheduler(opts) {
         writeFileWithDir(plistPath, plistContents, 0o600);
         const loadCommand = ["launchctl", "bootstrap", `gui/${process.getuid?.() ?? ""}`, plistPath];
         let loadResult;
+        let firstRun;
         if (!opts.skipLoad) {
             // Bootout first in case a prior install left the job loaded.
             spawnReport(["launchctl", "bootout", `gui/${process.getuid?.() ?? ""}`, plistPath]);
             loadResult = spawnReport(loadCommand);
+            if (loadResult.code === 0) {
+                // Ordering gate (#1231): verify the first run ONLY after the load
+                // exited 0. A load failure is its own failure mode with its own
+                // remedy — kickstarting on top of it would blur which actor failed.
+                firstRun = verifyFirstRun({
+                    plat,
+                    darwinTarget: `gui/${process.getuid?.() ?? ""}/${LAUNCHD_LABEL}`,
+                    stderrLogPath,
+                });
+            }
         }
-        return { platform: plat, shimPath, schedulerPath: plistPath, loadCommand, loadResult };
+        return {
+            platform: plat, shimPath, schedulerPath: plistPath, loadCommand, loadResult,
+            firstRunVerified: firstRun?.verified === true, firstRun,
+        };
     }
     // Linux: systemd user units.
     const timerPath = opts.systemdTimerOverride ?? SYSTEMD_TIMER_PATH;
@@ -296,13 +392,23 @@ 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) {
         spawnReport(["systemctl", "--user", "daemon-reload"]);
         loadResult = spawnReport(loadCommand);
+        if (loadResult.code === 0) {
+            // 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: SYSTEMD_SERVICE_UNIT, stderrLogPath });
+        }
     }
-    return { platform: plat, shimPath, schedulerPath: timerPath, loadCommand, loadResult };
+    return {
+        platform: plat, shimPath, schedulerPath: timerPath, loadCommand, loadResult,
+        firstRunVerified: firstRun?.verified === true, firstRun,
+    };
 }
 /**
  * Removes the scheduler entry. Audit log + snapshots are preserved.
@@ -332,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) {