@tpsdev-ai/flair 0.45.0 → 0.47.0

package/dist/lib/mcp-enable.js

@@ -306,7 +306,6 @@ export function buildMcpOAuthConfigBlock(params) {
     const provider = params.idpProvider;
     const envPrefix = `OAUTH_${provider.toUpperCase()}`;
     const cimdAllowedHosts = params.cimdAllowedHosts ?? DEFAULT_CIMD_ALLOWED_HOSTS;
-    const enabled = params.enabled ?? true;
     return {
         "@harperfast/oauth": {
             package: "@harperfast/oauth",
@@ -317,9 +316,29 @@ export function buildMcpOAuthConfigBlock(params) {
                 },
             },
             mcp: {
-                enabled,
+                // flair#1152: whole-token env reference — same flag flair's in-process
+                // route gates on. ASYMMETRY (load-bearing, measured on oauth 2.5.0):
+                // the component's coerceConfigBoolean accepts ONLY "true"/"false" and
+                // DELETES any other string (unresolved placeholder, "1", "yes",
+                // garbage) so its disabled default applies; flair's mcpOAuthEnabled()
+                // (resources/mcp-oauth-flag.ts) accepts 1/true/yes/on. So "true" is
+                // the one value that enables BOTH; "1"/"yes"/"on" flip flair's /mcp
+                // handler on while the component AS stays off (fail-closed broken-on:
+                // all 401, no AS advertised); garbage/unset disable both. On oauth
+                // <2.5.0 there is NO normalization and an unresolved placeholder is a
+                // truthy string (fail-open) — which is why the resolved-version
+                // assertion in mcp-oauth-boot-safety.test.ts exists. If component
+                // `enabled` semantics ever change, or it ever drives flair handler
+                // registration directly, re-derive this table before shipping.
+                enabled: "${FLAIR_MCP_OAUTH}",
                 issuer: "${FLAIR_MCP_ISSUER}",
-                resource: "${FLAIR_MCP_ISSUER}/mcp",
+                // flair#1180: NO `resource` key — the component's resolveResource()
+                // derives `<issuer>/mcp` at request time when it is absent, identical
+                // to flair's in-process derivation. The old composite
+                // "${FLAIR_MCP_ISSUER}/mcp" never interpolated (whole-token-only
+                // expansion) and failed every connect with invalid_target. Escape
+                // hatch: an operator needing a non-standard resource sets an explicit
+                // LITERAL absolute URL in config.yaml (never a composite).
                 accessTokenTtl: REQUIRED_ACCESS_TOKEN_TTL,
                 // Explicit fail-closed disable — see the doc comment above and the
                 // module header for why an omitted block is NOT equivalent to this.
@@ -336,14 +355,24 @@ export function buildMcpOAuthConfigBlock(params) {
     };
 }
 // ─── Local config.yaml update (flair#1136) ──────────────────────────────────
+/** The whole-token env reference `flair mcp enable` writes as mcp.enabled
+ *  (flair#1152). The on/off choice lives in the environment (the secrets
+ *  bundle stages FLAIR_MCP_OAUTH=true — see buildSecretsBundle for why it
+ *  must be "true"), never as a literal in the config file. */
+export const MCP_ENABLED_ENV_REFERENCE = "${FLAIR_MCP_OAUTH}";
 /**
- * Flip mcp.enabled in a local component config.yaml. Best-effort: returns
- * `{ ok: false }` with a reason when the file can't be found or parsed.
+ * Set mcp.enabled in a local component config.yaml to the flair#1152 shape.
+ * Best-effort: returns `{ ok: false }` with a reason when the file can't be
+ * found or parsed.
+ *
+ * `enabled: true` writes the WHOLE-TOKEN env reference ${FLAIR_MCP_OAUTH}
+ * (never a literal `true` — the env var, staged to `true` by the secrets bundle,
+ * carries the choice; a legacy literal `true` found in the file is normalized
+ * to the reference). `enabled: false` writes literal `false` — decisively off
+ * regardless of environment.
  *
  * Looks for config.yaml at `explicitPath`, then `./config.yaml`, then
- * `~/.flair/config.yaml`. When found, replaces `mcp:\n    enabled: false`
- * with `mcp:\n    enabled: true` (exact string match — avoids a YAML parser
- * dependency for a single boolean flip).
+ * `~/.flair/config.yaml`.
  */
 export function updateLocalConfigMcpEnabled(enabled, explicitPath) {
     const candidates = explicitPath
@@ -356,11 +385,15 @@ export function updateLocalConfigMcpEnabled(enabled, explicitPath) {
             break;
         }
     }
+    // The value the file should carry for this call (flair#1152): the env
+    // reference when enabling, literal false when disabling.
+    const target = enabled ? MCP_ENABLED_ENV_REFERENCE : false;
+    const targetLabel = enabled ? `${MCP_ENABLED_ENV_REFERENCE} (env-referenced)` : "false";
     if (!configPath) {
         return {
             ok: false,
             detail: `local config.yaml not found (tried: ${candidates.join(", ")}). ` +
-                `Set mcp.enabled: ${enabled} in your component config.yaml manually, then restart.`,
+                `Set mcp.enabled: ${targetLabel} in your component config.yaml manually, then restart.`,
         };
     }
     let raw;
@@ -388,7 +421,7 @@ export function updateLocalConfigMcpEnabled(enabled, explicitPath) {
         return {
             ok: false,
             detail: `@harperfast/oauth block not found in ${configPath}. ` +
-                `Ensure the component block is present with mcp.enabled: ${enabled}.`,
+                `Ensure the component block is present with mcp.enabled: ${targetLabel}.`,
         };
     }
     const mcp = oauth.mcp;
@@ -396,15 +429,15 @@ export function updateLocalConfigMcpEnabled(enabled, explicitPath) {
         return {
             ok: false,
             detail: `mcp key not found under @harperfast/oauth in ${configPath}. ` +
-                `Ensure the mcp block is present with enabled: ${enabled}.`,
+                `Ensure the mcp block is present with enabled: ${targetLabel}.`,
         };
     }
     const current = mcp.enabled;
-    if (current === enabled) {
-        return { ok: true, detail: `mcp.enabled already ${enabled} in ${configPath}` };
+    if (current === target) {
+        return { ok: true, detail: `mcp.enabled already ${targetLabel} in ${configPath}` };
     }
     // Mutate the parsed document and re-emit.
-    mcp.enabled = enabled;
+    mcp.enabled = target;
     const updated = yaml.dump(doc, { lineWidth: -1, noCompatMode: true });
     try {
         writeFileSync(configPath, updated, { encoding: "utf-8" });
@@ -412,7 +445,7 @@ export function updateLocalConfigMcpEnabled(enabled, explicitPath) {
     catch (err) {
         return { ok: false, detail: `cannot write ${configPath}: ${err.message}` };
     }
-    return { ok: true, detail: `mcp.enabled set to ${enabled} in ${configPath}` };
+    return { ok: true, detail: `mcp.enabled set to ${targetLabel} in ${configPath}` };
 }
 /** The exact callback URL to hand the operator when they create the IdP
  *  OAuth app ("with the exact GitHub callback URL printed"). */
@@ -425,7 +458,14 @@ export function idpCallbackUrl(issuer, idpProvider) {
 export function buildSecretsBundle(params) {
     const envPrefix = `OAUTH_${params.idpProvider.toUpperCase()}`;
     return {
-        FLAIR_MCP_OAUTH: "1",
+        // "true" is the ONLY value both readers of this flag accept (flair#1152,
+        // measured against oauth 2.5.0): flair's strict mcpOAuthEnabled() takes
+        // 1/true/yes/on, but the component's coerceConfigBoolean takes ONLY
+        // "true"/"false" and DELETES anything else (disabled default applies).
+        // Staging "1" here would flip flair's /mcp handler ON while the
+        // component's AS stays OFF — fail-closed but broken-on (every request
+        // 401s, no AS is advertised). Keep this "true".
+        FLAIR_MCP_OAUTH: "true",
         FLAIR_MCP_ISSUER: params.issuer.replace(/\/+$/, ""),
         FLAIR_MCP_SIGNING_KEY_PEM: params.signingKeyPem,
         [`${envPrefix}_CLIENT_ID`]: params.idpClientId,
@@ -1024,8 +1064,18 @@ export async function enableMcp(params, deps = {}) {
             idpProvider,
             idpSubject: params.idpSubject,
         }, { fetchImpl: deps.fetchImpl, now: deps.now });
-        push(true, `principal '${principal}' ${mapping.principalCreated ? "created" : "already existed"}; ` +
-            `Credential(kind:idp) ${mapping.credentialReused ? "reused" : "created"} (${mapping.credentialId})`);
+        // flair#1280 — provisioning legibility: distinct identities are the
+        // DEFAULT (a connector sub is not your CLI agent unless you link them),
+        // and the one silent failure mode this surface has is discovering that
+        // via an empty bootstrap. So the step that creates the mapping states it
+        // plainly, names the link remedy, and points at the runtime diagnostic.
+        push(true, `connector identity: sub '${params.idpSubject}' (provider '${idpProvider}') resolves to Agent '${principal}' — ` +
+            `every /mcp call reads and writes AS '${principal}'. ` +
+            `principal ${mapping.principalCreated ? "created" : "already existed"}; ` +
+            `Credential(kind:idp) ${mapping.credentialReused ? "re-pointed" : "created"} (${mapping.credentialId}). ` +
+            `If your CLI signs as a DIFFERENT agent id, the connector sees that agent's DISTINCT memory scope (by design) — ` +
+            `re-run with --principal <your-agent-id> to link them. ` +
+            `Diagnostic: the bootstrap tool's agentId/scope fields always say who the server resolved you to.`);
         // ── Gate: confirm the staged secrets are actually live before restarting ─
         let confirmed = Boolean(params.confirmSecretsApplied);
         if (!confirmed && deps.confirmPrompt) {
@@ -1052,9 +1102,9 @@ export async function enableMcp(params, deps = {}) {
             currentStep = "fabric-operator-deploy";
             const msg = [
                 `Fabric deployment detected (${new URL(params.instance).hostname}).`,
-                `The @harperfast/oauth block ships in config.yaml with mcp.enabled: false.`,
-                `To activate: set mcp.enabled: true (literal boolean) in your deployed component config.yaml,`,
-                `ensure the staged secrets are live in the instance's process environment, and redeploy.`,
+                `The @harperfast/oauth block ships in config.yaml with mcp.enabled: \${FLAIR_MCP_OAUTH} (env-referenced, flair#1152) — no config edit is needed.`,
+                `To activate: apply the staged secrets (FLAIR_MCP_OAUTH=true among them) to the instance's environment (Fabric env), then restart the instance.`,
+                `Deploys can no longer revert the choice — it lives in the environment, not the packed file.`,
                 `Then re-run \`flair mcp enable\` — earlier steps are idempotent and will be reused.`,
             ].join(" ");
             push(false, msg);

package/dist/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/postinstall.cjs

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * postinstall.cts — `npm install -g` PATH check (flair#1134).
+ *
+ * THIS IS THE POSTINSTALL ENTRY (`package.json` "postinstall" requires
+ * dist/postinstall.cjs). It exists for exactly one case: a user-prefix
+ * global install (prefix = ~/.npm-global or similar) where npm links the
+ * `flair` bin into a directory that is not on PATH. The install "succeeds",
+ * then `flair` is command-not-found, and the docs' one-command install claim
+ * is a lie. This is the only surface that can reach the user at the moment
+ * that happens — a first-run banner can never run, because the bin the user
+ * would run is precisely what's unreachable.
+ *
+ * History note (#1078/#1008): the previous postinstall was removed because it
+ * was a NO-OP (chmod +x on bins npm already marks executable) that cost an
+ * install-script approval line. This one is not that: it does work no other
+ * surface can, it is read-only (env + one existsSync — no network, no
+ * writes), and it NEVER fails the install (every path swallows errors and
+ * exits 0). Where lifecycle scripts are suppressed — `--ignore-scripts`,
+ * bun without trustedDependencies, the fleet's tar-swap deploys (the #1078
+ * path, which manages PATH itself) — `flair doctor` runs the same check.
+ *
+ * Delivery: npm ≥8 hides lifecycle-script output on success (it only shows
+ * with --foreground-scripts or on failure), so printing to stderr alone
+ * would be invisible exactly where it matters. We write to /dev/tty first —
+ * that bypasses npm's captured pipes and lands on the interactive terminal —
+ * and fall back to stderr (visible under --foreground-scripts, bun, older
+ * npm; harmlessly buffered otherwise). No TTY (CI) ⇒ the fallback is the
+ * only path, which is the right amount of noise for CI: none visible.
+ *
+ * Like cli-shim.cts this is CommonJS on purpose: it parses and runs on any
+ * Node a user could have, and the ESM helper is loaded via dynamic import()
+ * with every failure swallowed — a postinstall must never be the thing that
+ * breaks an install.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+function writeToTty(text) {
+    // npm captures the script's stdout/stderr pipes; the controlling terminal
+    // does not go through them. Best-effort, sync, closed either way.
+    //
+    // FLAIR_POSTINSTALL_NO_TTY: unit tests spawn this entry and assert on the
+    // stderr fallback; without the knob, a dev running the suite from a real
+    // terminal would have /dev/tty succeed — scribbling the banner over their
+    // screen and blanking the stderr the test asserts on (flaky by
+    // environment). The tty path's own coverage is the manual pty
+    // verification recorded in the flair#1134 PR (`script`-wrapped npm i -g).
+    if (process.env.FLAIR_POSTINSTALL_NO_TTY)
+        return false;
+    try {
+        var fs = require("node:fs");
+        var fd = fs.openSync("/dev/tty", "w");
+        try {
+            fs.writeSync(fd, text);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        return true;
+    }
+    catch (e) {
+        return false;
+    }
+}
+import("./install/global-bin-path.js")
+    .then(function (mod) {
+    try {
+        var path = require("node:path");
+        var message = mod.postinstallWarning({
+            npmConfigGlobal: process.env.npm_config_global,
+            npmConfigPrefix: process.env.npm_config_prefix,
+            pathEnv: process.env.PATH,
+            shell: process.env.SHELL,
+            // __dirname is <pkg>/dist — the package root is one up.
+            packageDir: path.resolve(__dirname, ".."),
+        });
+        if (message) {
+            var banner = "\n@tpsdev-ai/flair postinstall:\n\n" + message + "\n";
+            if (!writeToTty(banner))
+                console.error(banner);
+        }
+    }
+    catch (e) {
+        // Never fail the install over a diagnostic.
+    }
+})
+    .catch(function () {
+    // Helper unloadable (ancient Node, partial install) — never fail the install.
+});