@tpsdev-ai/flair 0.46.0 → 0.47.0

package/dist/doctor-client.js

@@ -454,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));
@@ -476,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.
@@ -507,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);
@@ -523,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/install/global-bin-path.js

@@ -0,0 +1,234 @@
+// ─── npm global bin dir vs PATH (flair#1134) ────────────────────────────────
+//
+// `npm install -g @tpsdev-ai/flair` on a user-prefix setup (prefix =
+// ~/.npm-global or similar) succeeds, puts the `flair` bin in
+// `<prefix>/bin`, and then `flair` is "command not found" because that
+// directory was never added to PATH. The install instructions claim
+// one-command readiness, so the failure reads as a broken package, not a
+// broken PATH.
+//
+// This module is the single source of truth for detecting that state and
+// for the message that fixes it. Two consumers:
+//   - dist/postinstall.cjs (src/postinstall.cts) — runs at `npm i -g` time,
+//     the moment the user hits the lie.
+//   - `flair doctor` — cheap, always runs, and covers every path where
+//     lifecycle scripts are suppressed (--ignore-scripts, bun without
+//     trustedDependencies, the fleet's tar-swap deploys).
+//
+// Contract (errors must enable a response): every warning names the ACTUAL
+// bin directory and prints the exact line to add for the user's shell —
+// never "check your PATH". If we cannot VALIDATE the directory (the flair
+// bin is really there), we say nothing rather than print a wrong fix.
+//
+// Everything here is pure and dependency-injected except
+// resolveNpmGlobalPrefix (spawns `npm prefix -g` for doctor).
+import { join } from "node:path";
+import { existsSync } from "node:fs";
+// ─── path membership ────────────────────────────────────────────────────────
+/** Strip trailing separators ("/", and "\" on win32) without eating a bare root. */
+function stripTrailingSeps(p, win32) {
+    const stripped = p.replace(win32 ? /[\\/]+$/ : /\/+$/, "");
+    return stripped === "" ? p.slice(0, 1) : stripped;
+}
+function normalizeEntry(entry, win32) {
+    let e = stripTrailingSeps(entry.trim(), win32);
+    if (win32)
+        e = e.replace(/\//g, "\\").toLowerCase();
+    return e;
+}
+/**
+ * The directory npm links global bins into for a given prefix:
+ * `<prefix>/bin` everywhere except win32, where shims land in the prefix
+ * itself (npm's own layout, not ours).
+ */
+export function npmGlobalBinDir(prefix, platform = process.platform) {
+    const win32 = platform === "win32";
+    const clean = stripTrailingSeps(prefix.trim(), win32);
+    return win32 ? clean : join(clean, "bin");
+}
+/**
+ * Is `dir` one of the entries of `pathEnv`? Trailing slashes are ignored on
+ * both sides; win32 compares case-insensitively with either separator and
+ * splits on ";". Empty entries (historical "cwd" semantics) never match.
+ */
+export function isDirOnPath(dir, pathEnv, platform = process.platform) {
+    if (!pathEnv)
+        return false;
+    const win32 = platform === "win32";
+    const delim = win32 ? ";" : ":";
+    const want = normalizeEntry(dir, win32);
+    return pathEnv
+        .split(delim)
+        .filter((e) => e.trim() !== "")
+        .some((e) => normalizeEntry(e, win32) === want);
+}
+/** basename of $SHELL, lowercased — "/usr/local/bin/zsh" → "zsh". */
+function shellFlavor(shell) {
+    if (!shell)
+        return "";
+    return shell.replace(/\\/g, "/").split("/").pop().toLowerCase();
+}
+export function shellPathFix(binDir, shell) {
+    const flavor = shellFlavor(shell);
+    if (flavor === "fish") {
+        // fish_add_path persists via a universal variable — one command does both.
+        const line = `fish_add_path ${binDir}`;
+        return { exportLine: line, persistCommand: line, rcFile: null };
+    }
+    const exportLine = `export PATH="${binDir}:$PATH"`;
+    const rcFile = flavor === "zsh" ? "~/.zshrc" : flavor === "bash" ? "~/.bashrc" : null;
+    return {
+        exportLine,
+        persistCommand: rcFile === null ? null : `echo '${exportLine}' >> ${rcFile}`,
+        rcFile,
+    };
+}
+// ─── the message ────────────────────────────────────────────────────────────
+/**
+ * The full actionable warning. Names the actual bin dir, gives the exact
+ * line for the user's shell, says how to persist it, and how to verify.
+ */
+export function formatOffPathMessage(binDir, shell, platform = process.platform) {
+    if (platform === "win32") {
+        return [
+            `flair is installed in ${binDir}, but that directory is not on your PATH,`,
+            `so the "flair" command will not be found.`,
+            ``,
+            `Fix — add it to your user PATH (new terminals pick it up):`,
+            ``,
+            `  powershell -Command "[Environment]::SetEnvironmentVariable('Path', [Environment]::GetEnvironmentVariable('Path','User') + ';${binDir}', 'User')"`,
+            ``,
+            `Then open a new terminal and verify:  flair --version`,
+        ].join("\n");
+    }
+    const fix = shellPathFix(binDir, shell);
+    const lines = [
+        `flair is installed at ${binDir}/flair, but ${binDir} is not on your PATH,`,
+        `so the "flair" command will not be found.`,
+        ``,
+        `Fix — run this in your shell now:`,
+        ``,
+        `  ${fix.exportLine}`,
+    ];
+    if (fix.persistCommand) {
+        lines.push(``, `and persist it for new shells:`, ``, `  ${fix.persistCommand}`);
+    }
+    else if (shellFlavor(shell) !== "fish") {
+        lines.push(``, `and add that same line to your shell's startup file to persist it.`);
+    }
+    lines.push(``, `Then verify:  flair --version`);
+    return lines.join("\n");
+}
+export function checkGlobalBinOnPath(input) {
+    const platform = input.platform ?? process.platform;
+    const binDir = npmGlobalBinDir(input.prefix, platform);
+    if (isDirOnPath(binDir, input.pathEnv, platform))
+        return { onPath: true, binDir };
+    return {
+        onPath: false,
+        binDir,
+        exportLine: shellPathFix(binDir, input.shell).exportLine,
+        message: formatOffPathMessage(binDir, input.shell, platform),
+    };
+}
+/**
+ * Fallback when npm_config_prefix is absent: derive prefix from where npm put
+ * us. String-based (not path.join) so the win32 shape stays faithful even in
+ * tests running on posix hosts.
+ */
+export function prefixFromPackageDir(packageDir, platform = process.platform) {
+    // posix:  <prefix>/lib/node_modules/@tpsdev-ai/flair  → 4 segments up
+    // win32:  <prefix>\node_modules\@tpsdev-ai\flair      → 3 segments up
+    const win32 = platform === "win32";
+    const segments = stripTrailingSeps(packageDir, win32).split(win32 ? /[\\/]/ : "/");
+    const ups = win32 ? 3 : 4;
+    const kept = segments.slice(0, Math.max(1, segments.length - ups));
+    return kept.join(win32 ? "\\" : "/") || (win32 ? packageDir : "/");
+}
+function defaultBinDirHasFlair(binDir, platform) {
+    const names = platform === "win32" ? ["flair.cmd", "flair"] : ["flair"];
+    return names.some((n) => existsSync(join(binDir, n)));
+}
+/**
+ * Decide what (if anything) the postinstall hook should print.
+ *
+ * Returns the warning message, or null when there is nothing to say:
+ *   - not a global install (npm_config_global !== "true" — local installs and
+ *     non-npm runners stay silent),
+ *   - no candidate prefix VALIDATES (the flair bin is not actually in the
+ *     candidate's bin dir — we never print a fix naming a wrong directory),
+ *   - or the bin dir is already on PATH.
+ */
+export function postinstallWarning(env) {
+    if (env.npmConfigGlobal !== "true")
+        return null;
+    const platform = env.platform ?? process.platform;
+    const hasFlair = env.binDirHasFlair ?? ((d) => defaultBinDirHasFlair(d, platform));
+    const candidates = [];
+    if (env.npmConfigPrefix)
+        candidates.push(env.npmConfigPrefix);
+    if (env.packageDir)
+        candidates.push(prefixFromPackageDir(env.packageDir, platform));
+    for (const prefix of candidates) {
+        const binDir = npmGlobalBinDir(prefix, platform);
+        if (!hasFlair(binDir))
+            continue; // unvalidated — never name a wrong dir
+        if (isDirOnPath(binDir, env.pathEnv, platform))
+            return null;
+        return formatOffPathMessage(binDir, env.shell, platform);
+    }
+    return null;
+}
+/** Compact per-boot variant of the message — this one repeats until fixed. */
+export function formatCompactOffPathBanner(binDir, shell) {
+    const fix = shellPathFix(binDir, shell);
+    const lines = [
+        `flair: ${binDir} (where npm installed flair) is not on your PATH.`,
+        `  fix now:  ${fix.exportLine}`,
+    ];
+    if (fix.persistCommand && fix.persistCommand !== fix.exportLine) {
+        lines.push(`  persist:  ${fix.persistCommand}`);
+    }
+    else if (!fix.persistCommand) {
+        lines.push(`  persist:  add that line to your shell's startup file`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Decide what (if anything) the CLI should print to stderr at boot.
+ * Null when: not a TTY, the layout does not validate (dev checkouts, npx
+ * cache copies, tar-swap deploys — their derived dir has no flair bin), or
+ * the bin dir is on PATH.
+ */
+export function cliBootPathWarning(env) {
+    if (!env.stderrIsTTY)
+        return null;
+    const platform = env.platform ?? process.platform;
+    const hasFlair = env.binDirHasFlair ?? ((d) => defaultBinDirHasFlair(d, platform));
+    const binDir = npmGlobalBinDir(prefixFromPackageDir(env.packageDir, platform), platform);
+    if (!hasFlair(binDir))
+        return null; // unvalidated — never name a wrong dir
+    if (isDirOnPath(binDir, env.pathEnv, platform))
+        return null;
+    return formatCompactOffPathBanner(binDir, env.shell);
+}
+// ─── doctor plumbing ────────────────────────────────────────────────────────
+/**
+ * `npm prefix -g`, best-effort. Returns the trimmed prefix or null when npm
+ * is absent / slow / errors — doctor SKIPS the check then (flair may have
+ * been installed by other means; a missing npm is not something this check
+ * can turn into an actionable finding).
+ */
+export async function resolveNpmGlobalPrefix() {
+    try {
+        const { execFile } = await import("node:child_process");
+        const out = await new Promise((resolve, reject) => {
+            execFile(process.platform === "win32" ? "npm.cmd" : "npm", ["prefix", "-g"], { timeout: 5000, encoding: "utf-8", shell: process.platform === "win32" }, (err, stdout) => (err ? reject(err) : resolve(String(stdout))));
+        });
+        const prefix = out.trim();
+        return prefix === "" ? null : prefix;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/lib/entity-vocab-cli.js

@@ -0,0 +1,113 @@
+/**
+ * entity-vocab-cli.ts — CLI-side copy of the attention-plane entity
+ * vocabulary validator (resources/entity-vocab.ts is the canonical module).
+ *
+ * INLINED, not imported: cross-boundary imports from src/ into resources/
+ * don't survive npm packaging — tsconfig.cli.json compiles with
+ * `rootDir: "src"`, so dist/cli.js has no resources/ module it can resolve
+ * at the same relative path. This is the same reason src/cli.ts inlines the
+ * federation crypto helpers (see the note beside `sortKeys()` there) and the
+ * private-visibility filter. The two files MUST stay in sync:
+ * test/unit/cli-entities-option.test.ts imports BOTH and pins ENTITY_TYPES
+ * equality, validator parity across a known-answer table, and the
+ * entityFormatHint() string — drift fails CI rather than shipping.
+ *
+ * Used by the `--entities <csv>` option on `flair memory add`,
+ * `flair workspace set`, and `flair orgevent` (flair#1288): the CLI validates
+ * before any signing/network work so a malformed entity is rejected
+ * client-side with an error that names the `type:value` format and
+ * enumerates the closed type set. The server independently re-validates on
+ * every write path (resources/Memory.ts / WorkspaceState.ts / OrgEvent.ts via
+ * invalidEntitiesResponse) — this module is UX, not the security gate.
+ */
+/** The closed set of entity types. Mirror of resources/entity-vocab.ts — extend BOTH together. */
+export const ENTITY_TYPES = [
+    "repo",
+    "issue",
+    "customer",
+    "subsystem",
+    "agent",
+    "person",
+];
+const ENTITY_TYPE_SET = new Set(ENTITY_TYPES);
+/**
+ * A "slug" value: lowercase alphanumeric segments joined by single `-` or
+ * `_` separators. Used for `customer:`, `subsystem:`, `agent:`, `person:`.
+ */
+const SLUG_RE = /^[a-z0-9]+(?:[-_][a-z0-9]+)*$/;
+/** A single repo path segment (owner or name): lowercase alphanumeric with `.`, `-`, `_` internal. */
+const REPO_SEGMENT_RE = /^[a-z0-9]+(?:[.\-_][a-z0-9]+)*$/;
+/** `<owner>/<name>` — both segments valid, exactly one `/`. */
+function isValidRepoValue(value) {
+    const parts = value.split("/");
+    if (parts.length !== 2)
+        return false;
+    const [owner, name] = parts;
+    return REPO_SEGMENT_RE.test(owner) && REPO_SEGMENT_RE.test(name);
+}
+/** `<owner>/<name>#<n>` — a valid repo value, `#`, then a positive integer (no leading zero). */
+function isValidIssueValue(value) {
+    const hashIndex = value.indexOf("#");
+    if (hashIndex === -1)
+        return false;
+    const repoPart = value.slice(0, hashIndex);
+    const numberPart = value.slice(hashIndex + 1);
+    if (!/^[1-9][0-9]*$/.test(numberPart))
+        return false;
+    return isValidRepoValue(repoPart);
+}
+function isValidSlugValue(value) {
+    return SLUG_RE.test(value);
+}
+const VALUE_VALIDATORS = {
+    repo: isValidRepoValue,
+    issue: isValidIssueValue,
+    customer: isValidSlugValue,
+    subsystem: isValidSlugValue,
+    agent: isValidSlugValue,
+    person: isValidSlugValue,
+};
+/** Split an entity string on its first `:` into { type, value }; null if it can't be well-formed. */
+function parseEntity(entity) {
+    if (typeof entity !== "string" || entity.length === 0)
+        return null;
+    const colonIndex = entity.indexOf(":");
+    if (colonIndex <= 0)
+        return null; // no colon, or colon is the first char (empty type)
+    const type = entity.slice(0, colonIndex);
+    const value = entity.slice(colonIndex + 1);
+    if (value.length === 0)
+        return null;
+    return { type, value };
+}
+/** Full validation: well-formed `type:value`, type in the closed set, value matches the type's grammar. */
+export function isValidEntity(entity) {
+    if (typeof entity !== "string")
+        return false;
+    const parsed = parseEntity(entity);
+    if (!parsed)
+        return false;
+    if (!ENTITY_TYPE_SET.has(parsed.type))
+        return false;
+    return VALUE_VALIDATORS[parsed.type](parsed.value);
+}
+/**
+ * Canonical "what does well-formed look like" hint (flair#1288): names the
+ * `type:value` format AND enumerates the closed type set, so the rejection
+ * enables a response. Must produce the EXACT string resources/entity-vocab.ts's
+ * entityFormatHint() produces — the sync test compares them verbatim.
+ */
+export function entityFormatHint() {
+    return `entities are 'type:value' vocabulary strings (e.g. 'repo:owner/name'); valid types: ${ENTITY_TYPES.join(", ")}`;
+}
+/**
+ * Parse a `--entities <csv>` option value: comma-split, trim, drop empties —
+ * the same list-option convention `--tags <csv>` / `--derived-from <csv>`
+ * already use (safe here because no entity grammar admits a comma) — then
+ * validate each element against the vocabulary.
+ */
+export function parseEntitiesCsv(csv) {
+    const entities = String(csv).split(",").map((x) => x.trim()).filter(Boolean);
+    const invalid = entities.filter((e) => !isValidEntity(e));
+    return { entities, invalid };
+}

package/dist/lib/mcp-enable.js

@@ -1064,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) {

package/dist/lib/scheduler-platform.js

@@ -234,6 +234,159 @@ export function describeExitCode(code) {
         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();
 }