@tpsdev-ai/flair 0.49.0 → 0.51.0

package/README.md

@@ -16,17 +16,28 @@ Runs on a laptop, a VPS, or anywhere Node does. Needs **Node.js 22+**.
 # 1. Install the CLI (no sudo)
 npm install -g @tpsdev-ai/flair
 
-# 2. Bootstrap the instance and register an agent
+# 2. Verify the command is on your PATH
+flair --version
+
+# 3. Bootstrap the instance and register an agent
 flair init --agent mybot
 
-# 3. Write a memory
+# 4. Write a memory
 flair memory add --agent mybot "Harper v5 sandbox blocks node:module but process.dlopen works"
 
-# 4. Find it back by meaning, not by keyword
+# 5. Find it back by meaning, not by keyword
 flair search --agent mybot "native addon loading in sandboxed runtimes"
 ```
 
-Step 4 finds the memory you never keyword-matched:
+If `flair --version` prints `command not found`, your npm global bin directory is not on `PATH`:
+
+```bash
+export PATH="$(npm prefix -g)/bin:$PATH"
+```
+
+Re-run `flair --version` to confirm, then continue.
+
+Step 5 finds the memory you never keyword-matched:
 
 ```
   Harper v5 sandbox blocks node:module but process.dlopen works

package/dist/bridges/runtime/roundtrip.js

@@ -16,7 +16,7 @@
  * Implementation note: does NOT talk to Flair. Fixture-to-fixture only.
  * Lives here so slice-3c code plugins can reuse the same harness.
  */
-import { promises as fsp } from "node:fs";
+import { promises as fsp, readdirSync, rmSync, statSync } from "node:fs";
 import { join, isAbsolute } from "node:path";
 import { tmpdir } from "node:os";
 import { randomUUID } from "node:crypto";
@@ -25,6 +25,74 @@ import { parseRecords } from "./formats.js";
 import { applyMap } from "./mapper.js";
 import { evaluatePredicate } from "./predicate.js";
 import { writeRecords } from "./writers.js";
+import { hasScratchOwnerStamp, scratchOwnerIsLive, writeScratchOwnerStamp, } from "../../lib/scratch-owner.js";
+/** mkdtemp prefix for this harness. Leaked trees of this name filled a host
+ *  to zero bytes (flair#1032) — 7,188 leftovers, mostly `…-test-bridge-*`. */
+export const BRIDGE_TEST_DIR_PREFIX = "flair-bridge-test-";
+/** Grace for *unstamped* leftovers only (stamp not written yet, or a tree
+ *  from before the owner file existed). Stamped trees use pid liveness. */
+export const STALE_BRIDGE_TEST_DIR_MS = 60_000;
+const IN_FLIGHT_BRIDGE_TEST_DIRS = new Set();
+let bridgeTestExitHookInstalled = false;
+function installBridgeTestExitHook() {
+    if (bridgeTestExitHookInstalled)
+        return;
+    bridgeTestExitHookInstalled = true;
+    // Exit only — no signal handlers. The integration suite SIGTERMs the
+    // runner as a fixture (federation-watch); a handler here would truncate it.
+    process.on("exit", () => {
+        for (const dir of IN_FLIGHT_BRIDGE_TEST_DIRS) {
+            try {
+                rmSync(dir, { recursive: true, force: true });
+            }
+            catch { /* best effort */ }
+        }
+    });
+}
+/**
+ * Remove leftover `flair-bridge-test-*` trees from earlier interrupted runs.
+ *
+ * A process-exit hook cannot cover SIGKILL or a hard crash, so the next
+ * harness start has to sweep what the last one left. Skips in-flight trees
+ * in this process and any tree whose owner pid is still alive. Directory
+ * mtime is not a liveness signal (Linux does not update it when files
+ * inside subdirs are appended) — it is only a race guard for unstamped dirs.
+ *
+ * @returns number of trees removed
+ */
+export function sweepStaleBridgeTestDirs(opts) {
+    const root = opts?.root ?? tmpdir();
+    const olderThanMs = opts?.olderThanMs ?? STALE_BRIDGE_TEST_DIR_MS;
+    const now = Date.now();
+    let names;
+    try {
+        names = readdirSync(root);
+    }
+    catch {
+        return 0;
+    }
+    let removed = 0;
+    for (const name of names) {
+        if (!name.startsWith(BRIDGE_TEST_DIR_PREFIX))
+            continue;
+        const dir = join(root, name);
+        if (IN_FLIGHT_BRIDGE_TEST_DIRS.has(dir))
+            continue;
+        if (scratchOwnerIsLive(dir))
+            continue;
+        try {
+            if (!hasScratchOwnerStamp(dir)) {
+                const st = statSync(dir);
+                if (now - st.mtimeMs < olderThanMs)
+                    continue;
+            }
+            rmSync(dir, { recursive: true, force: true });
+            removed++;
+        }
+        catch { /* gone, or not ours to remove */ }
+    }
+    return removed;
+}
 /** Fields the spec (§8) requires to survive round-trip. */
 export const ROUND_TRIP_STABLE_FIELDS = ["content", "subject", "tags", "durability"];
 export async function runRoundTrip(opts) {
@@ -52,8 +120,29 @@ export async function runRoundTrip(opts) {
     const importSource = descriptor.import.sources[0];
     const exportTarget = descriptor.export.targets[0];
     const resolvedFixture = resolvePath(cwd, opts.fixturePath ?? importSource.path);
-    const tmpDir = await fsp.mkdtemp(join(tmpdir(), `flair-bridge-test-${descriptor.name}-`));
+    // Sweep leftovers from interrupted runs *before* creating ours so a crash
+    // mid-call is all the next start has to find. In-flight trees in this
+    // process are skipped inside the sweep.
+    sweepStaleBridgeTestDirs();
+    const tmpDir = await fsp.mkdtemp(join(tmpdir(), `${BRIDGE_TEST_DIR_PREFIX}${descriptor.name}-`));
+    writeScratchOwnerStamp(tmpDir);
     const tmpPath = join(tmpDir, `roundtrip.${suffixForFormat(exportTarget.format)}`);
+    IN_FLIGHT_BRIDGE_TEST_DIRS.add(tmpDir);
+    installBridgeTestExitHook();
+    try {
+        return await runRoundTripAgainst(descriptor, resolvedFixture, importSource, exportTarget, tmpPath);
+    }
+    finally {
+        IN_FLIGHT_BRIDGE_TEST_DIRS.delete(tmpDir);
+        if (!opts.retainTmpDir) {
+            try {
+                await fsp.rm(tmpDir, { recursive: true, force: true });
+            }
+            catch { /* best effort */ }
+        }
+    }
+}
+async function runRoundTripAgainst(descriptor, resolvedFixture, importSource, exportTarget, tmpPath) {
     // Pass 1: fixture → BridgeMemory[]
     const pass1 = [];
     for await (const { record } of parseRecords(descriptor.name, resolvedFixture, importSource.format)) {

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.49.0",
-  "commit": "e6336fcbb25c46fcd53b00488d695659c61cc420",
-  "builtAt": "2026-08-24T19:36:52.866Z",
+  "version": "0.51.0",
+  "commit": "92b5d12cc3aafe892e90af657f073ef88b180ba6",
+  "builtAt": "2026-08-30T16:10:24.457Z",
   "builder": "tsc"
 }