@tpsdev-ai/flair 0.49.0 → 0.50.0

package/dist/deploy.js

@@ -631,9 +631,26 @@ export function publishedEntryNames(packageRoot) {
     }
     // `files` entries are npm patterns; the ones flair uses are plain top-level
     // names, optionally trailing-slashed ("dist/"). Normalise to the entry name.
-    const names = declared
-        .map((f) => String(f).replace(/^\.\//, "").replace(/\/+$/, ""))
-        .filter((f) => f !== "" && !f.includes("*") && !f.startsWith("!"));
+    //
+    // Honourable iff the entry is a plain top-level name. A blacklist of `*` and
+    // `!` lets `?`, `[]`, `{}` (and anything else minimatch understands) through
+    // as a literal that matches no real file — the same silent drop this fix
+    // exists to prevent (Sherlock on #1398). Whitelist: there is no
+    // differently-malformed form that slips through.
+    const names = [];
+    for (const raw of declared) {
+        const f = String(raw).replace(/^\.\//, "").replace(/\/+$/, "");
+        // Empty after normalize (`""`, `./`, `/`) is a listed entry we cannot
+        // honour as a plain top-level name. Skipping it left hasDeclaredFiles
+        // true and shipped only the always-includes — the same silent omit
+        // (Bugbot on #1398).
+        if (f === "." || f === ".." || !/^[a-zA-Z0-9._-]+$/.test(f)) {
+            throw new Error(`Cannot honour files entry ${JSON.stringify(String(raw))}: the deploy payload filter supports plain ` +
+                `top-level entries only. Either simplify the entry, or extend publishedEntryNames() ` +
+                `to match npm pack semantics.`);
+        }
+        names.push(f);
+    }
     return new Set([...names, ...always]);
 }
 /**

package/dist/doctor-client.js

@@ -23,7 +23,7 @@ import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { ALL_CLIENTS, clientConfigPath, piSettingsPath, resolvePiExtensionPath, scanPiSettings, } from "./install/clients.js";
-import { FLAIR_MCP_PACKAGE } from "./lib/mcp-spec.js";
+import { FLAIR_MCP_PACKAGE, mcpServerSpec } from "./lib/mcp-spec.js";
 // The exact substring `flair init` writes into CLAUDE.md (src/cli.ts, the
 // `init` action) and that the doctor check + fix both key off of.
 export const CLAUDE_MD_BOOTSTRAP_MARKER = "mcp__flair__bootstrap";
@@ -42,9 +42,10 @@ export const SESSION_START_HOOK_MARKER = "flair-session-start";
 //
 // WHY THE INVOCATION IS WRAPPED
 // -----------------------------
-// The hook runs `npx -y -p @tpsdev-ai/flair-mcp flair-session-start`: it resolves
-// a package binary through whatever Node runtime the user's shell happens to
-// expose. Under a Node version manager, globally installed packages are
+// The hook runs `npx -y -p @tpsdev-ai/flair-mcp@<version> flair-session-start`
+// (same mcpServerSpec() pin as `flair init`'s user-local MCP client configs —
+// flair#1143). It resolves a package binary through whatever Node runtime the
+// user's shell happens to expose. Under a Node version manager, globally installed packages are
 // per-runtime-version, so a routine and entirely unrelated runtime upgrade
 // orphans that binary. The command then stops resolving and the harness
 // reports a hook error on EVERY session, indefinitely, in wording that names
@@ -64,7 +65,7 @@ export const SESSION_START_HOOK_MARKER = "flair-session-start";
 // spawns with `shell: true` and never consults $SHELL (verified against the
 // 2.1.220 bundle; the settings schema's claim that `"shell": "bash"` uses your
 // $SHELL is not what the code does on POSIX). So a bare POSIX fragment would
-// in fact be enough for the one harness we support today.
+// in fact be enough for the JSON-command harnesses we support today.
 //
 // It is still wrapped, because this string is not private to that harness:
 // SUPPORTED_HARNESSES (src/hook-install.ts) is a registry meant to grow, and
@@ -118,9 +119,23 @@ export function buildSessionStartHookCommand(agentId, 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 ${SESSION_START_HOOK_MARKER}`;
+    // Same pin as user-local MCP client configs (mcpServerSpec / flair#907).
+    // Public plugin mcp.json stays unpinned (flair#1308) — that is a scraped
+    // listing, not a machine we just wired.
+    const invocation = `${env} npx -y -p ${mcpServerSpec()} ${SESSION_START_HOOK_MARKER}`;
     return `sh -c 'out=$(${invocation} 2>/dev/null) && printf %s "$out" || true'`;
 }
+/**
+ * The `npx -y -p` invocation that runs `flair-session-start` — pinned
+ * (`@tpsdev-ai/flair-mcp@<ver>`) or the pre-#1143 unpinned form. Used by
+ * `flair hook status` so a freshly-pinned hook is not reported as
+ * hand-edited, and an older unpinned hook is not reported as broken.
+ * Rejects the pre-#1166 form (no `-p`), which runs the MCP shim.
+ */
+export const SESSION_START_HOOK_INVOCATION_RE = /npx -y -p @tpsdev-ai\/flair-mcp(?:@[^\s"']+)? flair-session-start/;
+export function isSessionStartHookInvocation(command) {
+    return typeof command === "string" && SESSION_START_HOOK_INVOCATION_RE.test(command);
+}
 /**
  * Does this command absorb a failure instead of surfacing it? Checked as two
  * independent PROPERTIES (stderr discarded, non-zero exit absorbed) rather
@@ -249,8 +264,8 @@ function continuityEventReport(config, event) {
  * 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");
+export function checkContinuityCaptureHooks(homeDir, settingsPath) {
+    const path = settingsPath ?? join(homeDir, ".claude", "settings.json");
     let config = {};
     const raw = readTextFile(path);
     if (raw && raw.trim()) {
@@ -728,12 +743,14 @@ export function fixClaudeMdBootstrap(cwd) {
     }
 }
 /**
- * Pass when ~/.claude/settings.json exists, parses as JSON, and ANY hook
+ * Pass when the harness settings file exists, parses as JSON, and ANY hook
  * command anywhere under hooks.SessionStart[*].hooks[*].command contains the
  * flair-session-start marker (see docs/mcp-clients.md for the exact shape).
+ * `settingsPath` defaults to ~/.claude/settings.json; pass the Codex
+ * `~/.codex/hooks.json` path (or any other hookSettingsPath) for that harness.
  */
-export function checkSessionStartHook(homeDir) {
-    const path = join(homeDir, ".claude", "settings.json");
+export function checkSessionStartHook(homeDir, settingsPath) {
+    const path = settingsPath ?? join(homeDir, ".claude", "settings.json");
     const raw = readTextFile(path);
     if (!raw || !raw.trim())
         return { present: false, path };
@@ -772,10 +789,9 @@ export function checkSessionStartHook(homeDir) {
  * command. Returns the version when the spec is written
  * `@tpsdev-ai/flair-mcp@<ver>`; null for a bare/unpinned spec.
  *
- * The SessionStart hook is deliberately unpinned (`npx -y -p
- * @tpsdev-ai/flair-mcp`, buildSessionStartHookCommand above), so a hook
- * establishes that flair-mcp is wired but never carries a version — the pin
- * comes from the client MCP config.
+ * SessionStart hooks written since flair#1143 carry the same pin as a
+ * client MCP config (`mcpServerSpec()`). A pre-#1143 unpinned hook still
+ * establishes that flair-mcp is wired but contributes no version.
  */
 export function extractFlairMcpPin(text) {
     if (typeof text !== "string")
@@ -800,27 +816,39 @@ export function detectWiredFlairMcp(homeDir) {
                 pinnedVersion = pin;
         }
     };
-    // 1. The SessionStart hook (claude-code). Establishes wiring; unpinned by design.
-    const hook = checkSessionStartHook(homeDir);
-    if (hook.present && isFlairHookCommand(hook.command ?? ""))
-        note(hook.command);
-    // 2. Every known client's MCP config — a wired flair block carries the spec.
+    // 1. Every known client's MCP config — a wired flair block carries the spec.
+    //    Scanned first so a client pin wins (see module note above).
     for (const client of ALL_CLIENTS) {
         const configPath = withHome(homeDir, () => clientConfigPath(client.id));
         note(readTextFile(configPath));
     }
+    // 2. SessionStart hooks (claude-code settings.json + Codex hooks.json).
+    //    Establish wiring; may carry a pin, but NEVER override a client pin
+    //    already taken above — `note()` only sets pinnedVersion when it is still
+    //    unset, so THIS ORDERING IS THE PRECEDENCE RULE, not decoration. The
+    //    Codex path is additive (flair#1148); it must not reorder these two steps.
+    //    Paths match hookSettingsPath in src/hook-install.ts — listed here to
+    //    avoid a cycle (hook-install already imports this module).
+    for (const hookPath of [
+        join(homeDir, ".claude", "settings.json"),
+        join(homeDir, ".codex", "hooks.json"),
+    ]) {
+        const hook = checkSessionStartHook(homeDir, hookPath);
+        if (hook.present && isFlairHookCommand(hook.command ?? ""))
+            note(hook.command);
+    }
     return { wired, pinnedVersion };
 }
 /**
- * Merge-safe insert of a Flair SessionStart hook group into
- * ~/.claude/settings.json — creates the file/array if absent, preserves any
- * other existing hooks/keys (read-parse-merge-write, mirroring wireJsonMcp's
- * merge safety in src/install/clients.ts; never a blind overwrite). Dedupes:
- * a no-op (ok:true) if a matching hook is already present, so it's safe to
- * call twice.
+ * Merge-safe insert of a Flair SessionStart hook group into the harness
+ * settings file (default ~/.claude/settings.json) — creates the file/array
+ * if absent, preserves any other existing hooks/keys (read-parse-merge-write,
+ * mirroring wireJsonMcp's merge safety in src/install/clients.ts; never a
+ * blind overwrite). Dedupes: a no-op (ok:true) if a matching hook is already
+ * present, so it's safe to call twice.
  */
-export function fixSessionStartHook(homeDir, agentId) {
-    const path = join(homeDir, ".claude", "settings.json");
+export function fixSessionStartHook(homeDir, agentId, settingsPath) {
+    const path = settingsPath ?? join(homeDir, ".claude", "settings.json");
     if (!agentId) {
         return {
             ok: false,
@@ -953,7 +981,7 @@ export function classifyHookProbe(outcome) {
  * (or null via `{ probe: false }`) to keep a caller hermetic.
  */
 export function inspectSessionStartHook(homeDir, opts = {}) {
-    const found = checkSessionStartHook(homeDir);
+    const found = checkSessionStartHook(homeDir, opts.settingsPath);
     if (!found.present || !found.command) {
         return { path: found.path, present: false, ours: false, silenced: false, upgradable: false, execution: null };
     }
@@ -995,8 +1023,8 @@ export function classifyHookReadiness(report) {
  * decision to un-wire ambient memory, and `flair hook uninstall` is the
  * command for that when the user does decide.
  */
-export function upgradeSessionStartHookCommand(homeDir) {
-    const path = join(homeDir, ".claude", "settings.json");
+export function upgradeSessionStartHookCommand(homeDir, settingsPath) {
+    const path = settingsPath ?? join(homeDir, ".claude", "settings.json");
     try {
         const raw = readTextFile(path);
         if (!raw || !raw.trim())

package/dist/federation/scheduler.js

@@ -62,7 +62,7 @@ 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, describeExitCode, resolveNodeBin, verifyFirstRun, STATUS_CHECK_TIMEOUT_MS, } from "../lib/scheduler-platform.js";
+import { detectPlatform as detectPlatformFor, spawnReport, readTemplate, renderTemplateWith, writeFileWithDir, interpretActiveResult, describeLoadFailure as describeLoadFailureFor, describeExitCode, resolveNodeBin, resolveFlairBin, formatFlairBinWarning, verifyFirstRun, probeUserLingerEnabled, 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";
@@ -165,7 +165,8 @@ function launchdDomain() {
  */
 export function enableScheduler(opts) {
     const plat = detectPlatform(opts.platformOverride);
-    const flairBin = opts.flairBin ?? process.argv[1] ?? "flair";
+    const resolvedFlair = resolveFlairBin(opts.flairBin);
+    const flairBin = resolvedFlair.path;
     const nodeBin = resolveNodeBin(opts.nodeBin);
     const shimPath = opts.shimPathOverride ?? SHIM_PATH_DEFAULT;
     const templateRoot = opts.templateRootOverride ?? defaultTemplateRoot();
@@ -221,6 +222,7 @@ export function enableScheduler(opts) {
         return {
             platform: plat, shimPath, schedulerPath: plistPath, intervalSeconds: opts.intervalSeconds,
             loadCommand, loadResult, firstRunVerified: firstRun?.verified === true, firstRun,
+            flairBin, flairBinCanonical: resolvedFlair.canonical, flairBinPublic: resolvedFlair.publicBin,
         };
     }
     // Linux: systemd user units.
@@ -249,6 +251,7 @@ export function enableScheduler(opts) {
     return {
         platform: plat, shimPath, schedulerPath: timerPath, intervalSeconds: opts.intervalSeconds,
         loadCommand, loadResult, firstRunVerified: firstRun?.verified === true, firstRun,
+        flairBin, flairBinCanonical: resolvedFlair.canonical, flairBinPublic: resolvedFlair.publicBin,
     };
 }
 /** Removes the scheduler entry. Peer records and sync history are untouched. */
@@ -485,6 +488,15 @@ export function assessDriver(input) {
  * asked for — a sync run through the service manager — has been observed to
  * happen once.
  */
+function appendFlairBinWarning(lines, r) {
+    if (r.flairBinCanonical !== false || !r.flairBin)
+        return;
+    const warning = formatFlairBinWarning(r.flairBin, r.flairBinPublic ?? null, "flair federation sync enable");
+    if (warning.length === 0)
+        return;
+    lines.push("");
+    lines.push(...warning);
+}
 export function formatEnableReport(r, input) {
     const activationFailed = !!r.loadResult && r.loadResult.code !== 0;
     const credLine = input.adminPassFile
@@ -504,11 +516,18 @@ export function formatEnableReport(r, input) {
         lines.push(`   Activation:  ${r.loadCommand.join(" ")} → code ${lr.code}`);
         if (lr.stderr)
             lines.push(`     stderr: ${lr.stderr.trim()}`);
-        const remedy = describeLoadFailureFor(r.platform, lr, "flair federation sync enable");
+        const lingerEnabled = input.lingerEnabled !== undefined
+            ? input.lingerEnabled
+            : (r.platform === "linux" ? (input.probeLinger ?? probeUserLingerEnabled)() : undefined);
+        const remedy = describeLoadFailureFor(r.platform, lr, "flair federation sync enable", {
+            lingerEnabled,
+            env: input.env,
+        });
         lines.push("");
         lines.push(remedy ? `   ${remedy}` : `   Re-run the activation command above manually to see the full diagnostic.`);
         lines.push("");
         lines.push(`   Nothing is scheduled until activation succeeds. Check anytime with: flair federation sync status`);
+        appendFlairBinWarning(lines, r);
         return { lines, ok: false };
     }
     if (!r.firstRunVerified) {
@@ -561,6 +580,7 @@ export function formatEnableReport(r, input) {
         }
         lines.push("");
         lines.push(`   Check anytime with: flair federation sync status`);
+        appendFlairBinWarning(lines, r);
         return { lines, ok: false };
     }
     const lines = [
@@ -579,6 +599,7 @@ export function formatEnableReport(r, input) {
     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\`.`);
+    appendFlairBinWarning(lines, r);
     return { lines, ok: true };
 }
 /** Formats the `flair federation sync status` report. */

package/dist/hook-install.js

@@ -54,12 +54,13 @@
 //      reuses bootstrap's own maxTokens machinery.
 import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { SESSION_START_HOOK_MARKER, buildSessionStartHookCommand, buildContinuityCaptureHookCommand, checkContinuityCaptureHooks, computeContinuityHookInstall, computeContinuityHookRemoval, hookCommandIsSilenced, isHookCommandValueSafe, } from "./doctor-client.js";
+import { SESSION_START_HOOK_MARKER, buildSessionStartHookCommand, buildContinuityCaptureHookCommand, checkContinuityCaptureHooks, computeContinuityHookInstall, computeContinuityHookRemoval, hookCommandIsSilenced, isHookCommandValueSafe, isSessionStartHookInvocation, readClientMcpBlock, } from "./doctor-client.js";
 // ── harness registry ────────────────────────────────────────────────────────
-/** v1 supports exactly one harness. The flag/type exist so a second harness
- *  is an additive registry entry, not a rewrite (Kern's #719 verdict: "a
- *  switch statement... is fine until we have 3+ harnesses"). */
-export const SUPPORTED_HARNESSES = ["claude-code"];
+/** SessionStart hook harnesses. A second harness is an additive registry
+ *  entry, not a rewrite (Kern's #719 verdict: "a switch statement... is
+ *  fine until we have 3+ harnesses"). Codex writes the same JSON hook
+ *  schema Claude Code uses, into `~/.codex/hooks.json` (flair#1148). */
+export const SUPPORTED_HARNESSES = ["claude-code", "codex"];
 export function isSupportedHarness(value) {
     return SUPPORTED_HARNESSES.includes(value);
 }
@@ -70,8 +71,37 @@ export function hookSettingsPath(homeDir, harness) {
     switch (harness) {
         case "claude-code":
             return join(homeDir, ".claude", "settings.json");
+        case "codex":
+            return join(homeDir, ".codex", "hooks.json");
     }
 }
+/** Continuity capture (PostToolUse + Stop) is Claude Code only. The matcher
+ *  is Claude tool names; writing it into another harness looks enabled and
+ *  never journals (flair#1148 Bugbot). SessionStart stays per-harness. */
+export function harnessSupportsContinuity(harness) {
+    return harness === "claude-code";
+}
+/** Status/doctor hint for `flair hook install`. Claude Code stays the bare
+ *  default; every other harness is named so the hint cannot silently write
+ *  the wrong file (flair#1148 Bugbot). */
+export function hookInstallHint(harness, extraFlags = "") {
+    const parts = ["flair hook install"];
+    if (extraFlags)
+        parts.push(extraFlags);
+    if (harness !== "claude-code")
+        parts.push(`--harness ${harness}`);
+    return parts.join(" ");
+}
+/** Agent id for a hook install: flag, env, this harness's MCP block, then
+ *  Claude Code's block as a last resort (same agent is often shared). */
+export function resolveHookAgentId(opts, homeDir, harness) {
+    return (opts.agent ||
+        opts.agentId ||
+        process.env.FLAIR_AGENT_ID ||
+        readClientMcpBlock(harness, homeDir).agentId ||
+        (harness !== "claude-code" ? readClientMcpBlock("claude-code", homeDir).agentId : undefined) ||
+        undefined);
+}
 /** Backup path convention: a single sibling `<path>.bak`, overwritten on
  *  every mutating run — recovery insurance for the mutation that's about to
  *  happen, not a version history. Exported so tests assert against the same
@@ -131,7 +161,7 @@ export const HOOK_STATUS_UNPARSED = "(unknown — could not parse command)";
  *  Recovered values are shown. The installer-no-URL omit (flair#1325) is
  *  allowed ONLY when agentId was parsed — that is the real `flair init`
  *  shape (`FLAIR_AGENT_ID` set, `FLAIR_URL` omitted). correctShape alone
- *  is not enough: it is an npx-substring check and a wired correct-shape
+ *  is not enough: it is an npx-invocation check and a wired correct-shape
  *  command with no env assignments must still show the unknown lines,
  *  not a silent all-clear. */
 export function hookStatusIdentityLines(status) {
@@ -392,7 +422,7 @@ export function hookStatus(homeDir, harness) {
     }
     const hookEntry = config.hooks.SessionStart[existing.groupIndex].hooks[existing.hookIndex];
     const command = typeof hookEntry?.command === "string" ? hookEntry.command : "";
-    const correctShape = hookEntry?.type === "command" && command.includes(`npx -y -p @tpsdev-ai/flair-mcp ${SESSION_START_HOOK_MARKER}`);
+    const correctShape = hookEntry?.type === "command" && isSessionStartHookInvocation(command);
     const env = parseHookCommandEnv(command);
     return {
         harness, path, wired: true, correctShape,
@@ -425,6 +455,13 @@ export function installContinuityHooks(opts) {
     const { homeDir, harness, agentId, flairUrl } = opts;
     const dryRun = !!opts.dryRun;
     const path = hookSettingsPath(homeDir, harness);
+    if (!harnessSupportsContinuity(harness)) {
+        return {
+            ok: false, path, harness, dryRun,
+            message: `continuity capture is Claude Code only — ${harness} has no PostToolUse/Stop matcher Flair can journal (SessionStart is still ${hookInstallHint(harness)})`,
+            backupPath: null, actions: null,
+        };
+    }
     for (const [label, value] of [["agent id", agentId], ["Flair URL", flairUrl]]) {
         if (!isHookCommandValueSafe(value)) {
             return {
@@ -542,10 +579,5 @@ export function uninstallContinuityHooks(opts) {
 /** Read-only continuity status for `flair hook status` — the same report
  *  doctor's check consumes, resolved through the harness's settings path. */
 export function continuityHookStatus(homeDir, harness) {
-    // hookSettingsPath and checkContinuityCaptureHooks both resolve
-    // ~/.claude/settings.json from homeDir; asserting through the harness
-    // registry keeps a future second harness from silently reading the wrong
-    // file.
-    void hookSettingsPath(homeDir, harness);
-    return checkContinuityCaptureHooks(homeDir);
+    return checkContinuityCaptureHooks(homeDir, hookSettingsPath(homeDir, harness));
 }

package/dist/lib/scheduler-platform.js

@@ -20,9 +20,9 @@
  * 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, isAbsolute } from "node:path";
-import { platform } from "node:os";
+import { existsSync, mkdirSync, writeFileSync, readFileSync, realpathSync } from "node:fs";
+import { resolve, dirname, isAbsolute, basename } from "node:path";
+import { platform, userInfo } from "node:os";
 import { spawnSync } from "node:child_process";
 /**
  * 30s ceiling on launchctl/systemctl invocations so a hung service manager
@@ -90,20 +90,71 @@ export function interpretActiveResult(plat, code, stdout, stderr) {
         return null; // spawn itself failed — inconclusive
     return false; // covers the no-bus case: empty stdout, nonzero/failed exit
 }
+/** True when this session already has the env `systemctl --user` needs. */
+export function sessionHasUserBusEnv(env = process.env) {
+    return Boolean(env.XDG_RUNTIME_DIR?.trim() && env.DBUS_SESSION_BUS_ADDRESS?.trim());
+}
+/**
+ * Reads whether lingering is already enabled for the current user.
+ * `loginctl show-user … Linger=yes` is the official answer; the stamp file
+ * `loginctl enable-linger` creates is the fallback when loginctl is missing
+ * or inconclusive. A failed probe is `null`, never linger-off — inventing
+ * linger-off would repeat the linger remedy after it already ran (#1107).
+ */
+export function probeUserLingerEnabled(opts = {}) {
+    const run = opts.run ?? spawnReport;
+    const lingerStampExists = opts.lingerStampExists ?? ((u) => existsSync(`/var/lib/systemd/linger/${u}`));
+    let user = "";
+    try {
+        user = userInfo().username;
+    }
+    catch {
+        user = process.env.USER || process.env.LOGNAME || "";
+    }
+    if (!user)
+        return null;
+    const r = run(["loginctl", "show-user", user, "--property=Linger"], STATUS_CHECK_TIMEOUT_MS);
+    const m = /^Linger=(yes|no)\s*$/m.exec(r.stdout ?? "");
+    if (m)
+        return m[1] === "yes";
+    if (lingerStampExists(user))
+        return true;
+    return null;
+}
 /**
- * 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.
+ * Human remedy text for a failed scheduler-load attempt (flair#850, #1107).
+ * Covers the traced "no systemd user session bus" failure, which blocks
+ * `systemctl --user` entirely in ssh-without-lingering, container, and CI
+ * contexts. Two cases that used to share one remedy:
+ *   (a) lingering genuinely off — print `loginctl enable-linger`
+ *   (b) linger already on, this session has no user-bus env — print the
+ *       `XDG_RUNTIME_DIR` / `DBUS_SESSION_BUS_ADDRESS` export lines
+ * Repeating (a) after the operator has applied it is the #1107 lie.
+ * 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) {
+export function describeLoadFailure(plat, loadResult, enableCommand, session) {
     const stderr = loadResult.stderr || "";
     if (plat === "linux" && /failed to connect to bus/i.test(stderr)) {
+        if (session?.lingerEnabled === true) {
+            const env = session.env ?? process.env;
+            if (!sessionHasUserBusEnv(env)) {
+                return ("No systemd user session bus is available in this session. Lingering is already enabled — " +
+                    "do not re-run `loginctl enable-linger`. The remaining gap is this session's user-bus environment. " +
+                    "Export:\n" +
+                    "     export XDG_RUNTIME_DIR=/run/user/$(id -u)\n" +
+                    "     export DBUS_SESSION_BUS_ADDRESS=unix:path=$XDG_RUNTIME_DIR/bus\n" +
+                    `   then re-run \`${enableCommand}\`.`);
+            }
+            return ("No systemd user session bus is available in this session. Lingering is already enabled and " +
+                "this session already has XDG_RUNTIME_DIR / DBUS_SESSION_BUS_ADDRESS — " +
+                "do not re-run `loginctl enable-linger` or re-export those variables. " +
+                "Check that `$XDG_RUNTIME_DIR/bus` exists (the systemd --user instance may not be running), " +
+                `then re-run \`${enableCommand}\`.`);
+        }
         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}\`.`);
@@ -172,6 +223,77 @@ export function resolveNodeBin(explicit) {
         "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.");
 }
+/**
+ * Resolves the path enable will bake as FLAIR_BIN, and whether that path is
+ * the stable public `flair` entry (flair#1279).
+ *
+ * Resolution order:
+ *   1. `explicit` — caller/test override. Relatives are resolved against cwd.
+ *   2. `hooks.argv1` / `process.argv[1]` — whatever launched enable.
+ *   3. The public `flair` on PATH, only when (1) and (2) are empty.
+ * Nothing absolute resolvable ⇒ throw. A bare `"flair"` is not an exec
+ * target under #1231's `exec <node> <script>` form (`node flair` looks in
+ * cwd, not PATH).
+ */
+export function resolveFlairBin(explicit, hooks) {
+    const publicBin = hooks && "publicBin" in hooks ? (hooks.publicBin ?? null) : lookupPublicFlairBin();
+    const captured = explicit ?? hooks?.argv1 ?? process.argv[1];
+    let path;
+    if (typeof captured === "string" && captured.length > 0) {
+        path = isAbsolute(captured) ? captured : resolve(captured);
+    }
+    else if (publicBin) {
+        path = publicBin;
+    }
+    else {
+        throw new Error("unable to resolve an absolute path to the flair CLI (process.argv[1] was empty and `command -v flair` " +
+            "found nothing). The scheduler shim bakes this path in at enable time — refusing to install a shim " +
+            "whose exec target is unknown. Re-run enable via the `flair` command.");
+    }
+    return { path, publicBin, canonical: isCanonicalFlairBin(path, publicBin) };
+}
+/** True when `baked` is the public `flair` entry, not a working-tree capture. */
+export function isCanonicalFlairBin(baked, publicBin) {
+    if (basename(baked) === "flair")
+        return true;
+    if (publicBin && pathsReferToSameFile(baked, publicBin))
+        return true;
+    return false;
+}
+/**
+ * The enable-report lines for a non-canonical FLAIR_BIN. Empty when the
+ * baked path is the public entry — callers should not print a warning then.
+ */
+export function formatFlairBinWarning(baked, publicBin, enableCommand) {
+    if (isCanonicalFlairBin(baked, publicBin))
+        return [];
+    const lines = [
+        `⚠️  FLAIR_BIN is ${baked} — that is the process that ran enable, not a stable public entry.`,
+        `   A later blue/green directory swap, or deleting this working tree, will strand the scheduler unit.`,
+    ];
+    if (publicBin) {
+        lines.push(`   Public \`flair\` on PATH: ${publicBin}. Re-run \`${enableCommand}\` as the \`flair\` command to bake that path instead.`);
+    }
+    else {
+        lines.push(`   No \`flair\` on PATH. Re-run \`${enableCommand}\` via the installed \`flair\` command (or a stable symlink) so the baked path survives a tree swap.`);
+    }
+    return lines;
+}
+function lookupPublicFlairBin() {
+    const r = spawnReport(["/bin/sh", "-c", "command -v flair"], STATUS_CHECK_TIMEOUT_MS);
+    const found = r.stdout.trim().split("\n")[0]?.trim() ?? "";
+    if (r.code === 0 && found && isAbsolute(found) && existsSync(found))
+        return found;
+    return null;
+}
+function pathsReferToSameFile(a, b) {
+    try {
+        return realpathSync(a) === realpathSync(b);
+    }
+    catch {
+        return resolve(a) === resolve(b);
+    }
+}
 // ─── 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

package/dist/lib/scratch-owner.js

@@ -0,0 +1,49 @@
+/**
+ * Owner stamp for harness scratch directories (flair#1032).
+ *
+ * Directory mtime is not a liveness signal: on Linux, appending to files
+ * inside subdirectories does not update the parent. The stamp records the
+ * creating process; a sweep may delete a tree only when that process is gone
+ * (and, for Harper trees, when `hdb.pid` is gone too).
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+export const SCRATCH_OWNER_FILE = ".flair-scratch-owner";
+export function writeScratchOwnerStamp(dir, pid = process.pid) {
+    writeFileSync(join(dir, SCRATCH_OWNER_FILE), `${pid}\n`, { encoding: "utf-8" });
+}
+export function isPidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function readPidFile(path) {
+    try {
+        const pid = Number(readFileSync(path, "utf-8").trim());
+        return Number.isInteger(pid) && pid > 0 ? pid : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function readScratchOwnerPid(dir) {
+    return readPidFile(join(dir, SCRATCH_OWNER_FILE));
+}
+export function hasScratchOwnerStamp(dir) {
+    return existsSync(join(dir, SCRATCH_OWNER_FILE));
+}
+/** True when the creating process is still alive. Unreadable stamp → not live. */
+export function scratchOwnerIsLive(dir) {
+    const pid = readScratchOwnerPid(dir);
+    return pid !== null && isPidAlive(pid);
+}
+export function hdbPidIsLive(dir) {
+    const pid = readPidFile(join(dir, "hdb.pid"));
+    return pid !== null && isPidAlive(pid);
+}