@tpsdev-ai/flair 0.45.0 → 0.47.0

package/dist/doctor-client.js

@@ -154,6 +154,272 @@ export function parseLegacySessionStartHookCommand(command) {
 export function isFlairHookCommand(command) {
     return typeof command === "string" && command.includes("@tpsdev-ai/flair-mcp") && command.includes(SESSION_START_HOOK_MARKER);
 }
+// ── the continuity capture hooks (flair#1257 slice 2) ──────────────────────
+//
+// Continuity's write side is a pair of Claude Code hook entries — PostToolUse
+// (mutating tools only, via the matcher below) and Stop — both running the
+// SAME `flair-continuity-capture` binary shipped by @tpsdev-ai/flair-mcp.
+// Same ONE-builder discipline as the SessionStart command above (#1007):
+// every path that writes these entries (`flair doctor --fix`, `flair hook
+// install --continuity` in src/hook-install.ts) goes through
+// buildContinuityCaptureHookCommand, so the invocation's failure behaviour is
+// defined and tested in one place.
+//
+// Unlike the SessionStart command, this one captures NOTHING to re-emit: a
+// PostToolUse/Stop hook's stdout is harness-interpreted surface and the
+// capture binary never has anything to say to it, so the wrapper discards
+// BOTH streams and absorbs failure (`>/dev/null 2>/dev/null || true`). The
+// same #1007 reasoning applies: if the npx resolution breaks, the silence has
+// to be a property of the command string, because the binary's own fail-open
+// guarantee is behind the door that stopped opening. hookCommandIsSilenced()
+// recognizes this shape unchanged.
+//
+// INSTALLING THESE HOOKS IS THE OPT-IN. There is no env flag: an agent whose
+// settings.json carries the pair journals; one that doesn't, doesn't. Doctor
+// therefore reports "absent" as "not enabled" — informational, never a pass,
+// never a failure (see checkContinuityCaptureHooks / cli.ts's rendering).
+/** The exact substring identifying a Flair continuity-capture hook command. */
+export const CONTINUITY_CAPTURE_HOOK_MARKER = "flair-continuity-capture";
+/**
+ * The PostToolUse matcher written alongside our hook entry — the EXACT
+ * mutating-tool allowlist the capture binary enforces internally
+ * (packages/flair-mcp/src/continuity.ts's MUTATING_TOOLS: Write/Edit/
+ * NotebookEdit mutate file/cell state, Bash can mutate anything; read-only
+ * tools are world-recoverable and journal nothing). The matcher is an
+ * EFFICIENCY (no process spawn for a Read), not the control — the binary's
+ * own allowlist is the control and fires regardless of who spawns it.
+ */
+export const CONTINUITY_POST_TOOL_USE_MATCHER = "Write|Edit|NotebookEdit|Bash";
+/**
+ * Build the exact `command` string registered for BOTH continuity hook events
+ * (PostToolUse and Stop run the same binary; the payload's hook_event_name
+ * tells it which fired). Same strict value allow-list as the SessionStart
+ * builder — throws rather than emitting a quoted approximation.
+ */
+export function buildContinuityCaptureHookCommand(agentId, flairUrl) {
+    if (!isHookCommandValueSafe(agentId)) {
+        throw new Error(`agent id '${agentId}' contains characters that cannot be safely written into a shell hook command (allowed: letters, digits, . _ : / -)`);
+    }
+    if (flairUrl != null && flairUrl !== "" && !isHookCommandValueSafe(flairUrl)) {
+        throw new Error(`Flair URL '${flairUrl}' contains characters that cannot be safely written into a shell hook command (allowed: letters, digits, . _ : / -)`);
+    }
+    const env = flairUrl ? `FLAIR_AGENT_ID=${agentId} FLAIR_URL=${flairUrl}` : `FLAIR_AGENT_ID=${agentId}`;
+    const invocation = `${env} npx -y -p @tpsdev-ai/flair-mcp ${CONTINUITY_CAPTURE_HOOK_MARKER}`;
+    return `sh -c '${invocation} >/dev/null 2>/dev/null || true'`;
+}
+/** Does this command invoke the Flair continuity-capture binary at all? */
+export function isFlairContinuityCommand(command) {
+    return (typeof command === "string" &&
+        command.includes("@tpsdev-ai/flair-mcp") &&
+        command.includes(CONTINUITY_CAPTURE_HOOK_MARKER));
+}
+/** The two hook events continuity registers under. */
+export const CONTINUITY_HOOK_EVENTS = ["PostToolUse", "Stop"];
+function findContinuityEntry(config, event) {
+    const groups = config?.hooks?.[event];
+    if (!Array.isArray(groups))
+        return null;
+    for (let gi = 0; gi < groups.length; gi++) {
+        const hooks = groups[gi]?.hooks;
+        if (!Array.isArray(hooks))
+            continue;
+        for (let hi = 0; hi < hooks.length; hi++) {
+            if (typeof hooks[hi]?.command === "string" && hooks[hi].command.includes(CONTINUITY_CAPTURE_HOOK_MARKER)) {
+                return { group: groups[gi], hookIndex: hi, groupIndex: gi };
+            }
+        }
+    }
+    return null;
+}
+function continuityEventReport(config, event) {
+    const found = findContinuityEntry(config, event);
+    if (!found)
+        return { present: false, currentForm: false };
+    const hook = found.group.hooks[found.hookIndex];
+    const command = typeof hook?.command === "string" ? hook.command : "";
+    const matcher = typeof found.group?.matcher === "string" ? found.group.matcher : undefined;
+    const shapeOk = hook?.type === "command" &&
+        command.includes(`npx -y -p @tpsdev-ai/flair-mcp ${CONTINUITY_CAPTURE_HOOK_MARKER}`) &&
+        hookCommandIsSilenced(command);
+    const matcherOk = event !== "PostToolUse" || matcher === CONTINUITY_POST_TOOL_USE_MATCHER;
+    return { present: true, command, matcher, currentForm: shapeOk && matcherOk };
+}
+/**
+ * Doctor's check-5 twin of checkSessionStartHook for the continuity pair —
+ * pure fs read, no probe. A missing or unparseable settings.json reads as
+ * "absent" (not enabled), matching checkSessionStartHook's tolerance.
+ */
+export function checkContinuityCaptureHooks(homeDir) {
+    const path = join(homeDir, ".claude", "settings.json");
+    let config = {};
+    const raw = readTextFile(path);
+    if (raw && raw.trim()) {
+        try {
+            config = JSON.parse(raw);
+        }
+        catch {
+            config = {};
+        }
+    }
+    const postToolUse = continuityEventReport(config, "PostToolUse");
+    const stop = continuityEventReport(config, "Stop");
+    let state;
+    if (!postToolUse.present && !stop.present)
+        state = "absent";
+    else if (!postToolUse.present || !stop.present)
+        state = "partial";
+    else if (postToolUse.currentForm && stop.currentForm)
+        state = "installed";
+    else
+        state = "stale";
+    return { path, postToolUse, stop, state };
+}
+/**
+ * Pure merge of the continuity pair into a parsed settings object — the ONE
+ * mutation core both write paths (`flair doctor --fix` via
+ * fixContinuityCaptureHooks below, `flair hook install --continuity` via
+ * src/hook-install.ts) share. Idempotent: re-running with unchanged inputs is
+ * a structural no-op. Only OUR entries are ever touched — sibling hooks,
+ * groups and keys are preserved byte-identical; a group we don't own keeps
+ * its matcher (our binary's internal allowlist still filters — the matcher is
+ * an efficiency, not the control).
+ */
+export function computeContinuityHookInstall(config, agentId, flairUrl) {
+    const command = buildContinuityCaptureHookCommand(agentId, flairUrl);
+    const newConfig = JSON.parse(JSON.stringify(config ?? {}));
+    const actions = { PostToolUse: "noop", Stop: "noop" };
+    let changed = false;
+    newConfig.hooks = newConfig.hooks && typeof newConfig.hooks === "object" && !Array.isArray(newConfig.hooks) ? newConfig.hooks : {};
+    for (const event of CONTINUITY_HOOK_EVENTS) {
+        const existing = findContinuityEntry(newConfig, event);
+        if (existing) {
+            const hook = existing.group.hooks[existing.hookIndex];
+            const soleOwner = existing.group.hooks.length === 1;
+            const wantMatcher = event === "PostToolUse" && soleOwner;
+            const matcherCurrent = !wantMatcher || existing.group.matcher === CONTINUITY_POST_TOOL_USE_MATCHER;
+            if (hook.command === command && hook.type === "command" && matcherCurrent)
+                continue;
+            existing.group.hooks[existing.hookIndex] = { type: "command", command };
+            if (wantMatcher)
+                existing.group.matcher = CONTINUITY_POST_TOOL_USE_MATCHER;
+            actions[event] = "update";
+            changed = true;
+            continue;
+        }
+        newConfig.hooks[event] = Array.isArray(newConfig.hooks[event]) ? newConfig.hooks[event] : [];
+        const group = { hooks: [{ type: "command", command }] };
+        if (event === "PostToolUse")
+            group.matcher = CONTINUITY_POST_TOOL_USE_MATCHER;
+        newConfig.hooks[event].push(group);
+        actions[event] = "add";
+        changed = true;
+    }
+    return { changed, actions, newConfig };
+}
+/**
+ * Pure removal of the continuity pair — deletes ONLY our entries (marker
+ * substring match, exactly how install finds them), then prunes any group /
+ * event array / `hooks` key left empty by that removal. Never touches
+ * anything else.
+ */
+export function computeContinuityHookRemoval(config) {
+    const newConfig = JSON.parse(JSON.stringify(config ?? {}));
+    const actions = { PostToolUse: "noop", Stop: "noop" };
+    let changed = false;
+    for (const event of CONTINUITY_HOOK_EVENTS) {
+        const existing = findContinuityEntry(newConfig, event);
+        if (!existing)
+            continue;
+        existing.group.hooks.splice(existing.hookIndex, 1);
+        if (existing.group.hooks.length === 0) {
+            newConfig.hooks[event].splice(existing.groupIndex, 1);
+        }
+        if (newConfig.hooks[event].length === 0) {
+            delete newConfig.hooks[event];
+        }
+        actions[event] = "remove";
+        changed = true;
+    }
+    if (changed && newConfig.hooks && typeof newConfig.hooks === "object" && Object.keys(newConfig.hooks).length === 0) {
+        delete newConfig.hooks;
+    }
+    return { changed, actions, newConfig };
+}
+/**
+ * `flair doctor --fix` write path: register (or repair to current form) the
+ * continuity pair in ~/.claude/settings.json. Merge-safe read-parse-write,
+ * mirroring fixSessionStartHook — creates the file if absent, refuses on a
+ * file it cannot parse.
+ */
+export function fixContinuityCaptureHooks(homeDir, agentId, flairUrl) {
+    const path = join(homeDir, ".claude", "settings.json");
+    if (!agentId) {
+        return {
+            ok: false,
+            path,
+            changed: false,
+            message: "no agent id known — pass --agent <id> (or set FLAIR_AGENT_ID) so doctor knows which agent to wire the continuity hooks to",
+        };
+    }
+    if (!isHookCommandValueSafe(agentId)) {
+        return {
+            ok: false,
+            path,
+            changed: false,
+            message: `agent id '${agentId}' contains characters that cannot be safely written into a shell hook command (allowed: letters, digits, . _ : / -)`,
+        };
+    }
+    if (flairUrl != null && flairUrl !== "" && !isHookCommandValueSafe(flairUrl)) {
+        return {
+            ok: false,
+            path,
+            changed: false,
+            message: `Flair URL '${flairUrl}' contains characters that cannot be safely written into a shell hook command (allowed: letters, digits, . _ : / -)`,
+        };
+    }
+    try {
+        let config = {};
+        const raw = readTextFile(path);
+        if (raw && raw.trim())
+            config = JSON.parse(raw);
+        const { changed, newConfig } = computeContinuityHookInstall(config, agentId, flairUrl);
+        if (!changed) {
+            return { ok: true, path, changed: false, message: `continuity capture hooks already current in ${path}` };
+        }
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(newConfig, null, 2) + "\n");
+        return { ok: true, path, changed: true, message: `wired the continuity capture hooks (PostToolUse + Stop) in ${path} (agent '${agentId}')` };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return { ok: false, path, changed: false, message: `could not write ${path}: ${reason}` };
+    }
+}
+/**
+ * Symmetric removal path (`flair doctor --fix` when disabling / `flair hook
+ * uninstall --continuity`). A no-op when nothing is wired — never creates a
+ * file that didn't exist, refuses on a file it cannot parse.
+ */
+export function removeContinuityCaptureHooks(homeDir) {
+    const path = join(homeDir, ".claude", "settings.json");
+    const raw = readTextFile(path);
+    if (!raw || !raw.trim()) {
+        return { ok: true, path, changed: false, message: `no ${path} — continuity capture hooks are not enabled` };
+    }
+    try {
+        const config = JSON.parse(raw);
+        const { changed, newConfig } = computeContinuityHookRemoval(config);
+        if (!changed) {
+            return { ok: true, path, changed: false, message: `no continuity capture hooks found in ${path} — nothing to remove` };
+        }
+        writeFileSync(path, JSON.stringify(newConfig, null, 2) + "\n");
+        return { ok: true, path, changed: true, message: `removed the continuity capture hooks (PostToolUse + Stop) from ${path}` };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return { ok: false, path, changed: false, message: `could not update ${path}: ${reason}` };
+    }
+}
 // ── shared helpers ──────────────────────────────────────────────────────────
 /**
  * Run `fn` with process.env.HOME temporarily pointed at `homeDir`, then
@@ -188,12 +454,40 @@ function readTextFile(path) {
         return null;
     }
 }
+// ── check 1: MCP server block present + configured ─────────────────────────
+/**
+ * flair-client's own DEFAULT_URL (packages/flair-client/src/client.ts:
+ * `this.url = config.url ?? readEnvOrUnset("FLAIR_URL") ?? DEFAULT_URL`).
+ * Duplicated here as a value rather than imported — flair-client does not
+ * export it, and this module stays dependency-light by the same convention as
+ * the AgentGateState type duplication below. A unit test
+ * (doctor-client-native-shapes.test.ts) asserts this literal matches
+ * flair-client's source, so the two cannot drift silently.
+ */
+export const FLAIR_CLIENT_DEFAULT_URL = "http://localhost:19926";
+/**
+ * The URL the wired flair-mcp process will actually connect to: the block's
+ * FLAIR_URL when set, else flair-client's built-in default. `defaulted` tells
+ * the caller which of the two it got, so doctor's output can say so
+ * (flair#1287 — a defaulted URL is still a probe-able, working URL).
+ */
+export function effectiveFlairUrl(block) {
+    return block.flairUrl ? { url: block.flairUrl, defaulted: false } : { url: FLAIR_CLIENT_DEFAULT_URL, defaulted: true };
+}
 /**
  * Read the Flair MCP server block from `clientId`'s config file. `present`
- * is true only when the block exists AND both FLAIR_AGENT_ID and FLAIR_URL
- * are set (non-empty) — a half-wired block (e.g. block present, env missing)
- * counts as absent for the pass/fail check, but agentId/flairUrl are still
- * returned when partially found so callers can use whatever is known.
+ * is true when the block exists AND FLAIR_AGENT_ID is set (non-empty).
+ *
+ * FLAIR_URL is deliberately NOT required (flair#1287): flair-client treats it
+ * as optional and falls back to FLAIR_CLIENT_DEFAULT_URL, and the documented
+ * `claude mcp add` command (docs/mcp-clients.md) sets only FLAIR_AGENT_ID —
+ * so a URL-less block is a WORKING setup that doctor used to false-negative
+ * as "no Flair MCP server configured". Doctor's requirement now matches
+ * flair-client's actual contract: agent id required (flair-mcp refuses to
+ * start without one — "(none — required)" in docs), URL optional
+ * (`urlDefaulted` reports the fallback so the output can distinguish it).
+ * agentId/flairUrl are still returned when partially found so callers can use
+ * whatever is known.
  */
 export function readClientMcpBlock(clientId, homeDir) {
     const configPath = withHome(homeDir, () => clientConfigPath(clientId));
@@ -210,7 +504,11 @@ function readJsonFlairBlock(configPath) {
             return { present: false, configPath };
         const agentId = typeof flair.env?.FLAIR_AGENT_ID === "string" && flair.env.FLAIR_AGENT_ID ? flair.env.FLAIR_AGENT_ID : undefined;
         const flairUrl = typeof flair.env?.FLAIR_URL === "string" && flair.env.FLAIR_URL ? flair.env.FLAIR_URL : undefined;
-        return { present: !!agentId && !!flairUrl, configPath, agentId, flairUrl };
+        // FLAIR_URL optional — see readClientMcpBlock's doc (flair#1287). Any
+        // extra fields the client's own tooling writes (e.g. `claude mcp add`'s
+        // `type: "stdio"`) are irrelevant to presence and deliberately ignored.
+        const present = !!agentId;
+        return { present, configPath, agentId, flairUrl, urlDefaulted: present && !flairUrl };
     }
     catch {
         // Malformed JSON — treat as "not present", never throw.
@@ -241,7 +539,55 @@ function readCodexFlairBlock(configPath) {
     if (!raw)
         return { present: false, configPath };
     const scanned = scanCodexFlairBlock(raw);
-    return { present: scanned.present, configPath, agentId: scanned.agentId, flairUrl: scanned.flairUrl };
+    return { present: scanned.present, configPath, agentId: scanned.agentId, flairUrl: scanned.flairUrl, urlDefaulted: scanned.urlDefaulted };
+}
+/**
+ * The two env keys the codex scanner ever looks for, each with LITERAL
+ * regexes for both TOML shapes a real Codex config carries:
+ *
+ *   `line`   — the `[mcp_servers.flair.env]` sub-table form (`FLAIR_AGENT_ID
+ *              = "..."` on its own line): what `codex mcp add` serializes
+ *              (toml_edit Table via table_from_pairs, openai/codex
+ *              codex-rs config/edit/document_helpers.rs), what Codex's own
+ *              config docs show, and what our tomlSnippet() writes;
+ *   `inline` — the inline table (`env = { "FLAIR_AGENT_ID" = "..." }`, bare
+ *              or quoted keys): valid Codex TOML that `codex mcp add` itself
+ *              PRESERVES when merging into a hand-written inline entry
+ *              (merge_inline_table, same file). The old line-anchored regex
+ *              silently missed this shape — the flair#1287 defect class (a
+ *              client-accepted config our detector rejects) in TOML form.
+ *
+ * Spelled out as regex LITERALS per key rather than built via `new RegExp`
+ * with the key interpolated: the key set is closed (these two), and literal
+ * patterns keep the scanner off the non-literal-regexp SAST surface entirely
+ * — there is nothing dynamic for an injected pattern to ride in on. The
+ * `keyof` parameter type makes a third key a compile error here, not a
+ * silently unmatched scan.
+ */
+const CODEX_ENV_PATTERNS = {
+    FLAIR_AGENT_ID: {
+        line: /^\s*FLAIR_AGENT_ID\s*=\s*"([^"]*)"/m,
+        inline: /"?FLAIR_AGENT_ID"?\s*=\s*"([^"]*)"/,
+    },
+    FLAIR_URL: {
+        line: /^\s*FLAIR_URL\s*=\s*"([^"]*)"/m,
+        inline: /"?FLAIR_URL"?\s*=\s*"([^"]*)"/,
+    },
+};
+/** Pull one env value out of the `[mcp_servers.flair]` block text — see
+ *  CODEX_ENV_PATTERNS for the two shapes each key is matched against. */
+function scanCodexEnvValue(block, key) {
+    const patterns = CODEX_ENV_PATTERNS[key];
+    const lineMatch = block.match(patterns.line);
+    if (lineMatch?.[1])
+        return lineMatch[1];
+    const inlineEnv = block.match(/^\s*env\s*=\s*\{([^}]*)\}/m);
+    if (inlineEnv) {
+        const inlineMatch = inlineEnv[1].match(patterns.inline);
+        if (inlineMatch?.[1])
+            return inlineMatch[1];
+    }
+    return undefined;
 }
 function scanCodexFlairBlock(raw) {
     const startMatch = raw.match(/^\[mcp_servers\.flair\]\s*$/m);
@@ -257,11 +603,12 @@ function scanCodexFlairBlock(raw) {
         blockLines.push(lines[i]);
     }
     const block = blockLines.join("\n");
-    const agentMatch = block.match(/^\s*FLAIR_AGENT_ID\s*=\s*"([^"]*)"/m);
-    const urlMatch = block.match(/^\s*FLAIR_URL\s*=\s*"([^"]*)"/m);
-    const agentId = agentMatch?.[1] || undefined;
-    const flairUrl = urlMatch?.[1] || undefined;
-    return { present: !!agentId && !!flairUrl, agentId, flairUrl };
+    const agentId = scanCodexEnvValue(block, "FLAIR_AGENT_ID");
+    const flairUrl = scanCodexEnvValue(block, "FLAIR_URL");
+    // FLAIR_URL optional — same contract as readJsonFlairBlock (flair#1287);
+    // docs/mcp-clients.md's own Codex snippet sets only FLAIR_AGENT_ID.
+    const present = !!agentId;
+    return { present, agentId, flairUrl, urlDefaulted: present && !flairUrl };
 }
 // ── check 2: FLAIR_URL to use when (re-)wiring a client (flair#727) ────────
 /**

package/dist/federation/scheduler.js

@@ -57,12 +57,12 @@
  * `flair federation sync --admin-pass-file`, which reads it through
  * readAdminPassFileSecure() and refuses a file that is not owner-only.
  */
-import { existsSync, chmodSync, rmSync, readFileSync } from "node:fs";
+import { existsSync, chmodSync, rmSync, readFileSync, mkdirSync } from "node:fs";
 import { resolve, dirname } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { escapeXml } from "../lib/xml-escape.js";
-import { detectPlatform as detectPlatformFor, spawnReport, readTemplate, renderTemplateWith, writeFileWithDir, interpretActiveResult, describeLoadFailure as describeLoadFailureFor, STATUS_CHECK_TIMEOUT_MS, } from "../lib/scheduler-platform.js";
+import { detectPlatform as detectPlatformFor, spawnReport, readTemplate, renderTemplateWith, writeFileWithDir, interpretActiveResult, describeLoadFailure as describeLoadFailureFor, describeExitCode, resolveNodeBin, verifyFirstRun, STATUS_CHECK_TIMEOUT_MS, } from "../lib/scheduler-platform.js";
 export const LAUNCHD_LABEL = "dev.flair.federation.sync";
 export const SYSTEMD_TIMER_UNIT = "flair-federation-sync.timer";
 export const SYSTEMD_SERVICE_UNIT = "flair-federation-sync.service";
@@ -132,7 +132,7 @@ export function validateInterval(intervalSeconds) {
             `For sub-minute latency use \`flair federation watch --interval <s>\` in a foreground session instead.`);
     }
 }
-function buildSubstitutions(opts, shimPath, flairBin) {
+function buildSubstitutions(opts, shimPath, flairBin, nodeBin) {
     validateInterval(opts.intervalSeconds);
     const adminPassFile = opts.adminPassFile ?? "";
     if (adminPassFile && !existsSync(adminPassFile)) {
@@ -141,6 +141,7 @@ function buildSubstitutions(opts, shimPath, flairBin) {
     }
     return {
         FLAIR_BIN: flairBin,
+        NODE_BIN: nodeBin,
         SHIM_PATH: shimPath,
         HOME: opts.homeOverride ?? homedir(),
         INTERVAL_SECONDS: String(opts.intervalSeconds),
@@ -165,9 +166,29 @@ function launchdDomain() {
 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: this directory also receives
+    // REM's nightly log, which carries distillation CANDIDATE CONTENT — actual
+    // memory text, not just sync counts and errors. 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 federation sync enable\`.`);
+    }
+    const stderrLogPath = resolve(logsDir, "federation-sync.stderr.log");
     // 1. Deploy the shim (always — both platforms invoke it).
     const shimContents = renderTemplate(readTemplate(templateRoot, "bin/flair-federation-sync.sh.tmpl"), subs);
     writeFileWithDir(shimPath, shimContents, 0o700);
@@ -179,14 +200,28 @@ export function enableScheduler(opts) {
         writeFileWithDir(plistPath, plistContents, 0o600);
         const loadCommand = ["launchctl", "bootstrap", launchdDomain(), plistPath];
         let loadResult;
+        let firstRun;
         if (!opts.skipLoad) {
             // Bootout first in case a prior install left the job loaded — this is
             // what makes re-running enable (e.g. to change --interval) idempotent
             // rather than a "service already loaded" failure.
             spawnReport(["launchctl", "bootout", launchdDomain(), 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: `${launchdDomain()}/${LAUNCHD_LABEL}`,
+                    stderrLogPath,
+                });
+            }
         }
-        return { platform: plat, shimPath, schedulerPath: plistPath, intervalSeconds: opts.intervalSeconds, loadCommand, loadResult };
+        return {
+            platform: plat, shimPath, schedulerPath: plistPath, intervalSeconds: opts.intervalSeconds,
+            loadCommand, loadResult, firstRunVerified: firstRun?.verified === true, firstRun,
+        };
     }
     // Linux: systemd user units.
     const timerPath = opts.systemdTimerOverride ?? SYSTEMD_TIMER_PATH;
@@ -197,15 +232,24 @@ export function enableScheduler(opts) {
     writeFileWithDir(timerPath, timerContents, 0o600);
     const loadCommand = ["systemctl", "--user", "enable", "--now", SYSTEMD_TIMER_UNIT];
     let loadResult;
+    let firstRun;
     if (!opts.skipLoad) {
         spawnReport(["systemctl", "--user", "daemon-reload"]);
         // Restart so a changed --interval takes effect on re-enable; `enable
         // --now` alone leaves an already-running timer on its old schedule.
         loadResult = spawnReport(loadCommand);
-        if (loadResult.code === 0)
+        if (loadResult.code === 0) {
             spawnReport(["systemctl", "--user", "restart", SYSTEMD_TIMER_UNIT]);
+            // Ordering gate (#1231): only after the load exited 0. Starts the
+            // SERVICE unit directly (oneshot ⇒ blocks until the run exits) rather
+            // than waiting out the timer.
+            firstRun = verifyFirstRun({ plat, linuxServiceUnit: SYSTEMD_SERVICE_UNIT, stderrLogPath });
+        }
     }
-    return { platform: plat, shimPath, schedulerPath: timerPath, intervalSeconds: opts.intervalSeconds, loadCommand, loadResult };
+    return {
+        platform: plat, shimPath, schedulerPath: timerPath, intervalSeconds: opts.intervalSeconds,
+        loadCommand, loadResult, firstRunVerified: firstRun?.verified === true, firstRun,
+    };
 }
 /** Removes the scheduler entry. Peer records and sync history are untouched. */
 export function disableScheduler(opts = {}) {
@@ -432,6 +476,14 @@ export function assessDriver(input) {
  * success-vs-failure decision (flair#850: never print a success headline
  * before activation is known to have succeeded), extracted from the CLI
  * action so it is unit-testable without spawning launchctl/systemctl.
+ *
+ * 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 sync run through the service manager — has been observed to
+ * happen once.
  */
 export function formatEnableReport(r, input) {
     const activationFailed = !!r.loadResult && r.loadResult.code !== 0;
@@ -459,6 +511,58 @@ export function formatEnableReport(r, input) {
         lines.push(`   Nothing is scheduled until activation succeeds. Check anytime with: flair federation sync status`);
         return { lines, ok: false };
     }
+    if (!r.firstRunVerified) {
+        const fr = r.firstRun;
+        const headline = fr?.outcome === "run-failed"
+            ? `⚠️  Federation sync driver installed but the first run FAILED (${describeExitCode(fr.exitCode)})`
+            : fr?.outcome === "timeout"
+                ? `⚠️  Federation sync driver installed but the first run did not complete within ${Math.round(fr.budgetMs / 1000)}s — cannot confirm it works`
+                : fr?.outcome === "manager-unavailable"
+                    ? `⚠️  Federation sync driver installed but the service manager is unreachable — cannot verify the first run`
+                    : fr?.outcome === "start-failed"
+                        ? `⚠️  Federation sync driver installed but the first run could not be started`
+                        : `⚠️  Federation sync driver installed but the first run was never verified`;
+        const lines = [
+            headline,
+            `   Interval:    every ${r.intervalSeconds}s`,
+            `   Scheduler:   ${r.schedulerPath}`,
+            `   Shim:        ${r.shimPath}`,
+            credLine,
+        ];
+        if (input.target)
+            lines.push(`   Target:      ${input.target}`);
+        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. Check the log above and \`flair federation status\`;`);
+            lines.push(`   nothing has been CONFIRMED to sync yet.`);
+        }
+        else if (fr?.outcome === "manager-unavailable") {
+            lines.push(`   The driver files are installed, but launchctl/systemctl could not be consulted, so whether`);
+            lines.push(`   sync runs is UNKNOWN. Fix the service manager for this session, then re-run \`flair federation sync enable\`.`);
+        }
+        else {
+            lines.push(`   Nothing has synced. Fix the cause above, then re-run \`flair federation sync enable\`.`);
+        }
+        lines.push("");
+        lines.push(`   Check anytime with: flair federation sync status`);
+        return { lines, ok: false };
+    }
     const lines = [
         `✅ Federation sync driver enabled (${r.platform})`,
         `   Interval:    every ${r.intervalSeconds}s`,
@@ -470,9 +574,10 @@ export function formatEnableReport(r, input) {
         lines.push(`   Target:      ${input.target}`);
     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(`The first sync runs immediately. Confirm with \`flair federation status\`,`);
-    lines.push(`which now reports whether anything is actually driving sync.`);
+    lines.push(`Confirm anytime with \`flair federation status\`,`);
+    lines.push(`which reports whether anything is actually driving sync.`);
     lines.push(`Disable with \`flair federation sync disable\`.`);
     return { lines, ok: true };
 }