@tpsdev-ai/flair 0.44.13 → 0.46.0

package/dist/src/rem/scheduler.js

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

package/docs/notes/mcp-oauth-model2.md

@@ -59,9 +59,12 @@ never from the tool arguments (no forging of agentId / authorId).
          clientId: ${OAUTH_GITHUB_CLIENT_ID}
          clientSecret: ${OAUTH_GITHUB_CLIENT_SECRET}
      mcp:
-       enabled: true
+       enabled: ${FLAIR_MCP_OAUTH}          # whole-token env reference (flair#1152) — the choice lives in the ENVIRONMENT, so a re-packed deploy can't revert it
        issuer: ${FLAIR_MCP_ISSUER}          # pin to your public origin — REQUIRED
-       resource: ${FLAIR_MCP_ISSUER}/mcp     # RFC-8707 audience the /mcp token binds to
+       # NO resource key (flair#1180): the plugin derives <issuer>/mcp when it is
+       # absent. A composite like ${FLAIR_MCP_ISSUER}/mcp never interpolates
+       # (whole-token-only expansion) and fails every connect with
+       # invalid_target. Non-standard resource: set an explicit LITERAL URL.
        accessTokenTtl: 900                    # 5–15 min (Sherlock req 1) — short-lived
        dynamicClientRegistration:
          enabled: false                       # DCR is NOT SUPPORTED (flair#756) — explicit, not omitted (an absent block leaves DCR OPEN by the plugin's own default)
@@ -82,7 +85,11 @@ never from the tool arguments (no forging of agentId / authorId).
    turning the surface on.
 
 2. **Set the env:**
-   - `FLAIR_MCP_OAUTH=1` — turns on the `/mcp` route registration.
+   - `FLAIR_MCP_OAUTH=true` — turns on the `/mcp` route registration AND the
+     component AS (flair#1152: `true` is the ONE value both readers accept —
+     flair's flag takes 1/true/yes/on, but the component's config read of the
+     same var accepts only "true"/"false" and deletes anything else, so `1`
+     gives you a guarded `/mcp` with no authorization server behind it).
    - `FLAIR_MCP_ISSUER=https://your-public-origin` (or `FLAIR_PUBLIC_URL`).
    - `FLAIR_MCP_JIT_PROVISION=1` — ONLY if you want unknown subjects
      auto-provisioned (default OFF; pre-provision Agent+Credential otherwise).

package/docs/quickstart-fabric.md

@@ -50,7 +50,7 @@ The target defaults to `https://<cluster>.<org>.harperfabric.com`. Override with
 
 A fleet-verify table follows. That HTTPS origin is your `FLAIR_URL`.
 
-Then set an admin password in Fabric Studio (Cluster Settings → Admin). `flair agent add` against a remote instance requires `--admin-pass` — it will not reuse `~/.flair/admin-pass` or `FLAIR_ADMIN_PASS` from your laptop.
+Then set an admin password in Fabric Studio (Cluster Settings → Admin). `flair agent add` against a remote instance requires an explicit `--admin-pass-file` or `--admin-pass` — it will not reuse `~/.flair/admin-pass` or `FLAIR_ADMIN_PASS` from your laptop.
 
 ## 3. Register an agent against the remote instance
 
@@ -61,10 +61,15 @@ On Fabric, ops lives on the **same hostname at port 9925**, not the CLI's defaul
 ```bash
 export FLAIR_URL=https://<cluster>.<org>.harperfabric.com
 
+# Keep the Fabric admin password in an owner-only file; the CLI reads it in-process.
+printf '%s\n' '<fabric-admin-password>' > ~/.flair/fabric-admin-pass && chmod 600 ~/.flair/fabric-admin-pass
+
 # Fabric ops is :9925 on the same host, not derived :442. docs-freshness-allow: Fabric ops API
-flair agent add mybot --target "$FLAIR_URL" --ops-target https://<cluster>.<org>.harperfabric.com:9925 --admin-pass <fabric-admin-password>
+flair agent add mybot --target "$FLAIR_URL" --ops-target https://<cluster>.<org>.harperfabric.com:9925 --admin-pass-file ~/.flair/fabric-admin-pass
 ```
 
+`--admin-pass-file` reads the file inside the CLI process (mode `0600` enforced), so the password never appears in shell history **or** `ps`. Inline `--admin-pass <pass>` still works but lands in both; the older `--admin-pass "$(cat <path>)"` workaround stays out of history but is still visible to local `ps` while the command runs. Remote `agent add` honors **only** an explicit flag by design — `FLAIR_ADMIN_PASS` and `~/.flair/admin-pass` are this machine's *local* credentials and are never reused against a remote target.
+
 ```
 Keypair written: ~/.flair/keys/mybot.key
 ✅ Agent 'mybot' (mybot) registered (ops: https://<cluster>.<org>.harperfabric.com:9925) <!-- docs-freshness-allow: Fabric ops API -->
@@ -86,7 +91,41 @@ In Cursor: **Plugins → Configure**
 
 Those are the two plugin schema fields. Local Cursor's `npx` can use the key from step 3 at `~/.flair/keys/mybot.key`. A cloud agent's `npx` runs on a different machine — that VM needs the key (or host-env admin credentials). See [`packages/cursor-flair/README.md`](../packages/cursor-flair/README.md).
 
-## 5. Verify
+## 5. Wire a Grok Bot agent
+
+Same connector, different panel. This is the field-verified sequence — including the two places it fails first.
+
+**One identity per agent.** Short lowercase ids (`grok-cos` for a Chief-of-Staff agent). Never share an id across agents, and never leave admin credentials as an agent's standing auth — the admin password is for registration, once.
+
+1. In the Grok Bot agent's **Tools & MCPs** panel, add the Flair connector (the same `flair-mcp` stdio server the Cursor plugin runs):
+
+   | Variable | Value |
+   |---|---|
+   | `FLAIR_URL` | `https://<cluster>.<org>.harperfabric.com` |
+   | `FLAIR_AGENT_ID` | `grok-cos` (this agent's own id) |
+
+2. Ask for a bootstrap. **The first one returns 401.** That is fail-closed working as designed: the id is not registered yet and the machine has no key. Do not "fix" it by pasting admin credentials into the agent's environment.
+
+3. Provide the Fabric admin password through the platform's secret mechanism — Grok Bot's secure secret card — never pasted in chat. It is needed once, for registration only.
+
+4. On the machine that runs the MCP process (for Grok Bot, that is the agent VM): Node.js **22 or newer** — the field machine had 20 and had to upgrade before anything else worked. Then:
+
+   ```bash
+   npm i -g @tpsdev-ai/flair
+
+   # Fabric ops is :9925 on the same host, as in step 3. docs-freshness-allow: Fabric ops API
+   flair agent add grok-cos --target https://<cluster>.<org>.harperfabric.com --ops-target https://<cluster>.<org>.harperfabric.com:9925 --admin-pass "$(cat <pass-file>)"
+   ```
+
+   Keep the pass file mode `0600`. Newer releases add `--admin-pass-file <path>`, which reads the file in-process (invisible to `ps`) — check `flair agent add --help` and prefer it when present.
+
+5. **Restart the MCP process** if it started before the key existed — it does not pick the key up mid-session. Still 401 with the key on disk? Set the key path explicitly in the agent's MCP env: `FLAIR_KEY_PATH=~/.flair/keys/grok-cos.key`. Known papercut, tracked in [flair#1271](https://github.com/tpsdev-ai/flair/issues/1271).
+
+6. Verify: ask the agent to "load my Flair bootstrap". You should get soul + memories **including shared org context** — findings written by teammate agents. A shared-visibility write from this agent is now readable by every org agent.
+
+**Account-wide connectors are shared.** A connector added at the Grok Bot account level is one identity used by every agent on that account. For per-agent identity, give each agent its own MCP entry with its own `FLAIR_AGENT_ID` — and register each id (steps 2–5).
+
+## 6. Verify
 
 ```bash
 flair status --target "$FLAIR_URL"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.44.13",
+  "version": "0.46.0",
   "packageManager": "bun@1.3.10",
   "description": "Identity, memory, and soul for AI agents. Cryptographic identity (Ed25519), semantic memory with local embeddings, and persistent personality — all in a single process.",
   "type": "module",

package/templates/bin/flair-federation-sync.sh.tmpl

@@ -25,4 +25,11 @@ if [ -n "${FLAIR_ADMIN_PASS_FILE:-}" ] && [ -f "${FLAIR_ADMIN_PASS_FILE}" ]; the
   set -- "$@" --admin-pass-file "${FLAIR_ADMIN_PASS_FILE}"
 fi
 
-exec "{{FLAIR_BIN}}" federation sync "$@"
+# Run the CLI under node rather than exec-ing it directly: `node <script>`
+# needs READ permission only, so the shim keeps working when a deploy method
+# (npm-pack tarball extraction) strips the exec bit from the script (#1231).
+# NODE_BIN is an ABSOLUTE path resolved at enable time — the shim performs
+# zero PATH lookups at run time, exactly like the old absolute-FLAIR_BIN
+# form. Do not replace it with a bare `node`: that would hand binary
+# selection to whatever PATH the service manager happens to carry.
+exec "{{NODE_BIN}}" "{{FLAIR_BIN}}" federation sync "$@"

package/templates/bin/flair-rem-nightly.sh.tmpl

@@ -5,5 +5,12 @@
 #
 # Single line that invokes the CLI's run-once subcommand — the runner module
 # does all the work. Logs land in {{HOME}}/.flair/logs/.
+#
+# Run the CLI under node rather than exec-ing it directly: `node <script>`
+# needs READ permission only, so the shim keeps working when a deploy method
+# (npm-pack tarball extraction) strips the exec bit from the script (#1231).
+# NODE_BIN is an ABSOLUTE path resolved at enable time — the shim performs
+# zero PATH lookups at run time. Do not replace it with a bare `node`: that
+# would hand binary selection to whatever PATH the service manager carries.
 set -e
-exec {{FLAIR_BIN}} rem nightly run-once
+exec "{{NODE_BIN}}" "{{FLAIR_BIN}}" rem nightly run-once