@tpsdev-ai/flair 0.22.0 → 0.22.1

package/dist/cli.js

@@ -8131,6 +8131,46 @@ see src/fleet-verify.ts's file header for the full caveat.`)
     }
     process.exit(result.exitCode);
 });
+// ─── flair doctor — pure summary/exit helper ─────────────────────────────────
+// Extracted for testability (flair#721), same pattern as formatCandidateLine /
+// describeReflectError above: the action callback spawns process.exit and a
+// long sequence of console.log side effects, which makes it high-effort/
+// low-value to drive directly — this is the actual decision logic. Before
+// #721, doctor tracked only a single `issues` counter: every detected
+// problem incremented it, and the final summary/exit-code read that counter
+// alone, with no separate record of which of those issues `--fix` actually
+// resolved during the same run. So a `--fix` run that interactively fixed
+// every issue it found still printed "N issues found — see fixes above" and
+// exited 1 — indistinguishable from a run that fixed nothing. This helper
+// takes the accumulated found/fixed counts plus whether `--fix` was passed
+// at all, and decides the summary line + exit code:
+//   - 0 found                       → "No issues found", exit 0 (unchanged)
+//   - found, no --fix               → "N issues found — see fixes above", exit 1 (unchanged)
+//   - found, --fix, all fixed       → "N issues found, N fixed ✓", exit 0
+//   - found, --fix, some remaining  → "N issues found, M fixed, K remaining", exit 1
+export function summarizeDoctorRun(found, fixed, autoFix) {
+    const plural = (n) => `issue${n === 1 ? "" : "s"}`;
+    if (found === 0) {
+        return { line: `  ${render.icons.ok} ${render.wrap(render.c.green, "No issues found")}`, exitCode: 0 };
+    }
+    if (!autoFix) {
+        return {
+            line: `  ${render.icons.error} ${render.wrap(render.c.red, `${found} ${plural(found)} found`)} ${render.wrap(render.c.dim, "— see fixes above")}`,
+            exitCode: 1,
+        };
+    }
+    if (fixed >= found) {
+        return {
+            line: `  ${render.icons.ok} ${render.wrap(render.c.green, `${found} ${plural(found)} found, ${fixed} fixed ✓`)}`,
+            exitCode: 0,
+        };
+    }
+    const remaining = found - fixed;
+    return {
+        line: `  ${render.icons.error} ${render.wrap(render.c.red, `${found} ${plural(found)} found, ${fixed} fixed, ${remaining} remaining`)}`,
+        exitCode: 1,
+    };
+}
 // ─── flair doctor ─────────────────────────────────────────────────────────────
 program
     .command("doctor")
@@ -8149,6 +8189,7 @@ program
     let effectivePort = port;
     let baseUrl = `http://127.0.0.1:${port}`;
     let issues = 0;
+    let fixed = 0; // issues that --fix successfully resolved during this run (flair#721)
     let harperResponding = false;
     console.log(`\n${render.wrap(render.c.bold, "🩺 Flair Doctor")}\n`);
     // 0. Version check (flair#587) — offline-tolerant + cached, independent
@@ -8234,6 +8275,7 @@ program
                     else {
                         writeConfig(discoveredPort);
                         console.log(`     ${render.icons.ok} Updated config to port ${discoveredPort}`);
+                        fixed++;
                     }
                 }
                 else {
@@ -8277,6 +8319,7 @@ program
                             const { execSync } = await import("node:child_process");
                             execSync(`${process.argv[0]} ${process.argv[1]} restart --port ${port}`, { stdio: "inherit" });
                             console.log(`     ${render.icons.ok} Restart attempted`);
+                            fixed++;
                         }
                         catch {
                             console.log(`     ${render.icons.error} Restart failed — try: flair init --agent-id <your-agent>`);
@@ -8319,6 +8362,7 @@ program
                         const { execSync } = await import("node:child_process");
                         execSync(`${process.argv[0]} ${process.argv[1]} restart --port ${effectivePort}`, { stdio: "inherit" });
                         console.log(`     ${render.icons.ok} Restarted onto ${__pkgVersion}`);
+                        fixed++;
                     }
                     catch {
                         console.log(`     ${render.icons.error} Restart failed — try: flair restart`);
@@ -8418,6 +8462,7 @@ program
                 else {
                     (await import("node:fs")).unlinkSync(pidFile);
                     console.log(`     ${render.icons.ok} Removed stale PID file`);
+                    fixed++;
                 }
             }
             else {
@@ -8498,6 +8543,8 @@ program
                                         client.id === "gemini" ? wireGemini(wireEnv) :
                                             wireCursor(wireEnv);
                                 console.log(`     ${wireResult.ok ? render.icons.ok : render.icons.warn} ${wireResult.message}`);
+                                if (wireResult.ok)
+                                    fixed++;
                             }
                         }
                     }
@@ -8549,6 +8596,8 @@ program
                         else {
                             const fixRes = fixClaudeMdBootstrap(process.cwd());
                             console.log(`     ${fixRes.ok ? render.icons.ok : render.icons.warn} ${fixRes.message}`);
+                            if (fixRes.ok)
+                                fixed++;
                         }
                     }
                 }
@@ -8576,6 +8625,8 @@ program
                             const fixAgentId = claudeCodeAgentId || opts.agent || process.env.FLAIR_AGENT_ID;
                             const fixRes = fixSessionStartHook(homedir(), fixAgentId);
                             console.log(`     ${fixRes.ok ? render.icons.ok : render.icons.warn} ${fixRes.message}`);
+                            if (fixRes.ok)
+                                fixed++;
                         }
                     }
                 }
@@ -8726,17 +8777,14 @@ program
             console.log(`  ${render.icons.warn} Migration state check failed: ${err?.message ?? err}`);
         }
     }
-    // Summary
+    // Summary — see summarizeDoctorRun above (flair#721): distinguishes
+    // issues --fix actually resolved this run from ones still outstanding.
     console.log("");
-    if (issues === 0) {
-        console.log(`  ${render.icons.ok} ${render.wrap(render.c.green, "No issues found")}`);
-    }
-    else {
-        console.log(`  ${render.icons.error} ${render.wrap(render.c.red, `${issues} issue${issues > 1 ? "s" : ""} found`)} ${render.wrap(render.c.dim, "— see fixes above")}`);
-    }
+    const summary = summarizeDoctorRun(issues, fixed, autoFix);
+    console.log(summary.line);
     console.log("");
-    if (issues > 0)
-        process.exit(1);
+    if (summary.exitCode !== 0)
+        process.exit(summary.exitCode);
 });
 // ─── flair session snapshot ──────────────────────────────────────────────────
 // Slice 2 of FLAIR-AGENT-CONTEXT-TIERS-B. Snapshot a

package/dist/resources/migrations/runner.js

@@ -70,7 +70,6 @@ function resolveDeps(deps) {
         ledgerDeps: deps.ledgerDeps ?? {},
         batchDelayMs: deps.batchDelayMs ?? resolveTestBatchDelayMs() ?? 100,
         initiator: deps.initiator ?? "auto",
-        headroomFloor: deps.headroomFloor,
     };
 }
 // ─── space/snapshot sizing heuristics (overridable via RunnerDeps in future if ever needed) ──
@@ -256,11 +255,11 @@ async function runOneMigration(migration, envelope, deps, lock) {
     }
     const estSnapshot = estimateSnapshotBytes(posture.snapshotScope, initialRemaining);
     const estWorkingSet = estimateWorkingSetBytes(migration.riskClass, initialRemaining);
-    let space = checkSpace({ dataDir: deps.dataDir, estimatedSnapshotBytes: estSnapshot, estimatedWorkingSetBytes: estWorkingSet, headroomFloor: deps.headroomFloor }, deps.spaceProbe);
+    let space = checkSpace({ dataDir: deps.dataDir, estimatedSnapshotBytes: estSnapshot, estimatedWorkingSetBytes: estWorkingSet }, deps.spaceProbe);
     if (!space.ok) {
         // ── Ladder step 2: prune snapshots, then retry ──
         pruneMigrationSnapshots(deps.snapshotRoot);
-        space = checkSpace({ dataDir: deps.dataDir, estimatedSnapshotBytes: estSnapshot, estimatedWorkingSetBytes: estWorkingSet, headroomFloor: deps.headroomFloor }, deps.spaceProbe);
+        space = checkSpace({ dataDir: deps.dataDir, estimatedSnapshotBytes: estSnapshot, estimatedWorkingSetBytes: estWorkingSet }, deps.spaceProbe);
     }
     if (!space.ok) {
         // ── Ladder step 5: no safe path → halt-don't-brick ──

package/dist/resources/migrations/space.js

@@ -13,9 +13,60 @@
  * `estimateWorkingSetBytes` below is the caller's job (the runner computes
  * it per risk class); this module just evaluates the estimate against real
  * (or test-overridden) disk free/total space.
+ *
+ * flair#720 rewrote the rule this module enforces. The original shape
+ * (`projectedUsedFraction <= 0.9`, measured against TOTAL disk size) was
+ * designed for a flair-dedicated volume, but on a general-purpose machine
+ * — a personal Mac especially, where APFS purgeable space makes
+ * `statfs.bavail` understate real availability — the system volume
+ * routinely sits above 90% used already, so the fraction test failed
+ * before a single byte was written, regardless of how trivially the
+ * migration's own footprint fit (flair#720: 220 KB needed, 18.6 GB free,
+ * halted anyway). The fix keeps invariant III's "never fill past a
+ * cushion" intent but measures the migration's OWN impact plus an
+ * absolute reserve, instead of the disk's pre-existing fullness:
+ * `ok = neededBytes <= freeBytes AND (freeBytes - neededBytes) >= reserve`.
+ * See `RESERVE_MIN_BYTES` / `RESERVE_MAX_BYTES` / `RESERVE_FRACTION` below
+ * for how `reserve` is derived.
  */
 import { statfsSync } from "node:fs";
-export const DEFAULT_HEADROOM_FLOOR = 0.9; // never project past 90% used
+/**
+ * Reserve floor: on any disk, no migration may leave less than this much
+ * free afterward, even on a tiny volume where 5% of total would be less.
+ * 256 MiB is comfortably more than any single migration's own working set
+ * in this codebase (the largest estimate is embedding/HNSW rebuild
+ * overhead, a few KB per row) — it exists to leave room for Harper's own
+ * ordinary operation (WAL, temp files, log growth), not the migration
+ * itself.
+ */
+export const RESERVE_MIN_BYTES = 256 * 1024 * 1024; // 256 MiB
+/**
+ * Reserve cap: on a large disk, 5% of total would be an unreasonably large
+ * cushion to demand (e.g. 50 GB on a 1 TB drive) for what is, worst case,
+ * a few GB of migration working set. 2 GiB caps the reserve so the rule
+ * stays proportionate to what migrations actually need, not the disk's
+ * raw size.
+ */
+export const RESERVE_MAX_BYTES = 2 * 1024 * 1024 * 1024; // 2 GiB
+/**
+ * Between the floor and the cap, the reserve scales with disk size: 5% of
+ * total. This is the "proportionate cushion" middle ground — big enough to
+ * matter on a mid-size disk, small enough not to dominate on either
+ * extreme (RESERVE_MIN_BYTES / RESERVE_MAX_BYTES clamp the two ends).
+ */
+export const RESERVE_FRACTION = 0.05;
+/**
+ * Production escape hatch for constrained deployments (flair#720) — e.g. a
+ * small dedicated volume where even the 256 MiB floor is more cushion than
+ * the operator can spare. When set to a finite, non-negative number, this
+ * overrides the computed reserve entirely (including the floor/cap clamp
+ * — set it to 0 to disable the reserve check outright, keeping only the
+ * `neededBytes <= freeBytes` fit test). Invalid values (non-numeric,
+ * negative, NaN, Infinity) are ignored and the computed reserve is used
+ * instead — mirrors TEST_FREE_BYTES_ENV's validation below. Unset (the
+ * default) in every normal deployment.
+ */
+export const RESERVE_BYTES_ENV = "FLAIR_MIGRATION_RESERVE_BYTES";
 /**
  * Test-only escape hatch: when set, overrides the real statfs-reported free
  * byte count. Used by the halt-on-blocked-space integration test (real
@@ -45,29 +96,72 @@ export const defaultSpaceProbe = {
     getTotalBytes: realGetTotalBytes,
 };
 /**
- * Evaluates the pre-flight space check. Fails (ok:false) if the needed
- * bytes don't fit in free space OR if consuming them would project disk
- * usage past the headroom floor — matching invariant III's "never fill past
- * ~90%" rule exactly (a technically-fitting migration that would still push
- * the disk to 95% full is refused, same as one that doesn't fit at all).
+ * Resolves the absolute reserve a migration must leave free afterward:
+ * `RESERVE_BYTES_ENV` if set to a valid (finite, >= 0) value, else
+ * `clamp(RESERVE_FRACTION * totalBytes, RESERVE_MIN_BYTES, RESERVE_MAX_BYTES)`.
+ * Exported so tests can exercise the clamp/override logic directly without
+ * going through a full `checkSpace` call.
+ */
+export function resolveReserveBytes(totalBytes, env = process.env) {
+    const override = env[RESERVE_BYTES_ENV];
+    if (override !== undefined) {
+        const n = Number(override);
+        if (Number.isFinite(n) && n >= 0)
+            return n;
+    }
+    const fractional = totalBytes * RESERVE_FRACTION;
+    return Math.min(RESERVE_MAX_BYTES, Math.max(RESERVE_MIN_BYTES, fractional));
+}
+/**
+ * Bytes → human readable (binary-based thresholds, decimal labels — same
+ * convention as src/render.ts's `humanBytes`, which this module can't
+ * import: resources/**\/*.ts and src/**\/*.ts are separate TypeScript
+ * project boundaries (tsconfig.json vs tsconfig.cli.json/tsconfig.check.src.json)
+ * — resources/ is Harper-loaded component code and never imports from the
+ * CLI's src/ tree. Small enough to duplicate locally rather than restructure
+ * the module boundary for one formatter.
+ */
+export function humanBytes(n) {
+    if (!Number.isFinite(n) || n < 0)
+        return "—";
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    if (n < 1024 * 1024 * 1024)
+        return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+    return `${(n / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+}
+/**
+ * Evaluates the pre-flight space check (flair#720's rule): fails (ok:false)
+ * if the needed bytes don't fit in free space outright, OR if spending them
+ * would leave less than `reserveBytes` free afterward. Unlike the rule this
+ * replaced, fullness that already exists on the disk before the migration
+ * runs is irrelevant — only the migration's OWN impact on free space is
+ * judged, against an absolute (not fraction-of-total) cushion.
  */
 export function checkSpace(input, probe = defaultSpaceProbe) {
-    const floor = input.headroomFloor ?? DEFAULT_HEADROOM_FLOOR;
     const freeBytes = probe.getFreeBytes(input.dataDir);
     const totalBytes = probe.getTotalBytes(input.dataDir);
     const neededBytes = input.estimatedSnapshotBytes + input.estimatedWorkingSetBytes;
-    const usedBytesNow = Math.max(0, totalBytes - freeBytes);
-    const projectedUsedBytes = usedBytesNow + neededBytes;
-    const projectedUsedFraction = totalBytes > 0 ? projectedUsedBytes / totalBytes : 1;
+    const reserveBytes = resolveReserveBytes(totalBytes);
     const fits = neededBytes <= freeBytes;
-    const withinFloor = projectedUsedFraction <= floor;
-    const ok = fits && withinFloor;
+    const remainingAfter = freeBytes - neededBytes;
+    const withinReserve = fits && remainingAfter >= reserveBytes;
+    const ok = fits && withinReserve;
     let reason;
-    if (!ok) {
+    if (!fits) {
+        reason =
+            `need ${humanBytes(neededBytes)} free (snapshot + migration working set), have ${humanBytes(freeBytes)} — ` +
+                `short by ${humanBytes(neededBytes - freeBytes)}. Set ${RESERVE_BYTES_ENV} to lower the required post-migration ` +
+                `reserve on constrained deployments (this won't help here — the migration doesn't fit even before any reserve)`;
+    }
+    else if (!withinReserve) {
         reason =
-            `need ${neededBytes} bytes free (snapshot + migration working set), have ${freeBytes}; ` +
-                `proceeding would exceed the ${Math.round(floor * 100)}% disk headroom floor — ` +
-                `prune old snapshots (flair keeps last-3/30-day) or set FLAIR_SNAPSHOT_DIR to a volume with more room`;
+            `need ${humanBytes(neededBytes)} free (snapshot + migration working set); have ${humanBytes(freeBytes)}, ` +
+                `which covers it but would leave only ${humanBytes(remainingAfter)} free afterward — short of the ` +
+                `${humanBytes(reserveBytes)} minimum reserve required post-migration. Set ${RESERVE_BYTES_ENV} to a lower ` +
+                `byte count to shrink the required reserve on constrained deployments`;
     }
-    return { ok, freeBytes, totalBytes, neededBytes, projectedUsedFraction, reason };
+    return { ok, freeBytes, totalBytes, neededBytes, reserveBytes, reason };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.22.0",
+  "version": "0.22.1",
   "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",
   "license": "Apache-2.0",