@tpsdev-ai/flair 0.52.0 → 0.53.0

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.52.0",
-  "commit": "f5fbdfda5d1065256f70821721c53fb6ec93a84c",
-  "builtAt": "2026-09-09T16:23:44.353Z",
+  "version": "0.53.0",
+  "commit": "3a238b4a3ce3fce8cf64fcb83bd3203096ebae3a",
+  "builtAt": "2026-09-10T17:58:16.549Z",
   "builder": "tsc"
 }

package/dist/cli.js

@@ -5,7 +5,7 @@ import { load as parseYaml } from "js-yaml";
 import * as render from "./render.js";
 import { existsSync, mkdirSync, writeFileSync, readFileSync, openSync, closeSync, chmodSync, renameSync, cpSync, rmSync, mkdtempSync, readdirSync, statSync, lstatSync, realpathSync, unlinkSync, chownSync, constants as fsConstants, } from "node:fs";
 import { homedir, tmpdir } from "node:os";
-import { join, resolve, sep, dirname } from "node:path";
+import { join, resolve, sep, dirname, basename } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn, execFileSync, spawnSync, execSync } from "node:child_process";
 import { createHash, randomUUID, randomBytes } from "node:crypto";
@@ -33,7 +33,9 @@ import { validateSnapshotArchive, extractSnapshotSafely } from "./lib/safe-snaps
 import { entityFormatHint, parseEntitiesCsv } from "./lib/entity-vocab-cli.js";
 import { escapeXml, unescapeXml } from "./lib/xml-escape.js";
 import { assessLaunchdManagement, diagnoseLaunchdPlistPaths, isDetached, pickInstancePid, renderDetachedWarning, LAUNCHCTL_QUERY_TIMEOUT_MS, } from "./lib/launchd-management.js";
-import { applyUpgradeHookConsent, catalogIssueDelta, renderCatalogDoctorLines, renderVerifiedSummary, runDoctorChecks, } from "./lib/doctor-run.js";
+import { classifyPlist, planLaunchdRepair, mapRepairThrow, decideAdoptStop, } from "./lib/launchd-repair.js";
+import { stabilizeMqttNetworkKeyOrder } from "./lib/stabilize-mqtt-network.js";
+import { applyUpgradeHookConsent, catalogIssueDelta, DOCTOR_CHECK_IDS, renderCatalogDoctorLines, renderVerifiedSummary, runDoctorChecks, } from "./lib/doctor-run.js";
 import { classifyDaemonState, verifyIdentity, parseProcStatStartTime, procStartTimeToEpochMs, parsePsLstart, parseSidecarJson, } from "./lib/daemon-liveness.js";
 // Value-only static import so `--interval`'s advertised default cannot drift
 // from the one the scheduler actually validates against. The module itself is
@@ -221,21 +223,45 @@ function launchdPlistPath(label, launchAgentsDir = defaultLaunchAgentsDir()) {
  */
 export function buildLaunchdPlist(opts) {
     const e = escapeXml;
-    return `<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-  <key>Label</key><string>${e(opts.label)}</string>
-  <key>ProgramArguments</key>
-  <array>
+    const passFile = opts.passFile;
+    // ProgramArguments: inline mode execs node directly; pass-file mode execs
+    // the launcher, which reads the secret from a 0600 file and then execs node
+    // itself (so launchd still tracks Harper as the job).
+    const programArguments = passFile
+        ? `<array>
+    <string>${e(passFile.launcher)}</string>
+    <string>${e(passFile.adminPassFile)}</string>
+    <string>${e(opts.execPath)}</string>
+    <string>${e(opts.harperBinPath)}</string>
+  </array>`
+        : `<array>
     <string>${e(opts.execPath)}</string>
     <string>${e(opts.harperBinPath)}</string>
     <string>run</string>
     <string>.</string>
-  </array>
-  <key>WorkingDirectory</key><string>${e(opts.workingDirectory)}</string>
-  <key>EnvironmentVariables</key>
-  <dict>
+  </array>`;
+    // EnvironmentVariables: pass-file mode drops HDB_ADMIN_PASSWORD (the secret
+    // is read from the file by the launcher) and adds HOME + PATH, which the
+    // launcher needs under launchd's minimal env to start Harper non-interactively.
+    const environmentVariables = passFile
+        ? `<dict>
+    <key>ROOTPATH</key><string>${e(opts.dataDir)}</string>
+    <key>FLAIR_MODELS_DIR</key><string>${e(opts.modelsDir)}</string>
+    <key>HARPER_SET_CONFIG</key><string>${e(opts.setConfig)}</string>
+    <key>DEFAULTS_MODE</key><string>dev</string>
+    <key>HDB_ADMIN_USERNAME</key><string>${e(opts.adminUser)}</string>
+    <key>THREADS_COUNT</key><string>1</string>
+    <key>NODE_HOSTNAME</key><string>localhost</string>
+    <key>HTTP_PORT</key><string>${e(String(opts.httpPort))}</string>
+    <key>OPERATIONSAPI_NETWORK_PORT</key><string>${e(opts.opsNetworkPort)}</string>
+    <key>LOCAL_STUDIO</key><string>false</string>
+    <key>MQTT_NETWORK_PORT</key><string>null</string>
+    <key>MQTT_NETWORK_SECUREPORT</key><string>null</string>
+    <key>MQTT_WEBSOCKET</key><string>false</string>
+    <key>HOME</key><string>${e(passFile.home)}</string>
+    <key>PATH</key><string>${e(passFile.path)}</string>
+  </dict>`
+        : `<dict>
     <key>ROOTPATH</key><string>${e(opts.dataDir)}</string>
     <key>FLAIR_MODELS_DIR</key><string>${e(opts.modelsDir)}</string>
     <key>HARPER_SET_CONFIG</key><string>${e(opts.setConfig)}</string>
@@ -247,7 +273,20 @@ export function buildLaunchdPlist(opts) {
     <key>HTTP_PORT</key><string>${e(String(opts.httpPort))}</string>
     <key>OPERATIONSAPI_NETWORK_PORT</key><string>${e(opts.opsNetworkPort)}</string>
     <key>LOCAL_STUDIO</key><string>false</string>
-  </dict>
+    <key>MQTT_NETWORK_PORT</key><string>null</string>
+    <key>MQTT_NETWORK_SECUREPORT</key><string>null</string>
+    <key>MQTT_WEBSOCKET</key><string>false</string>
+  </dict>`;
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${e(opts.label)}</string>
+  <key>ProgramArguments</key>
+  ${programArguments}
+  <key>WorkingDirectory</key><string>${e(opts.workingDirectory)}</string>
+  <key>EnvironmentVariables</key>
+  ${environmentVariables}
   <key>RunAtLoad</key><true/>
   <key>KeepAlive</key><true/>
   <key>StandardOutPath</key><string>${e(join(opts.dataDir, "log", "launchd-stdout.log"))}</string>
@@ -255,6 +294,46 @@ export function buildLaunchdPlist(opts) {
 </dict>
 </plist>`;
 }
+/**
+ * Absolute path to the product-owned launchd launcher (flair#1573 slice a).
+ * Shipped in the package under templates/launchd/; the plist's
+ * ProgramArguments point at it in pass-file mode. `packageRoot` is injectable
+ * so tests can point this at a fixture tree instead of the real package dir.
+ */
+export function launchdLauncherPath(packageRoot = flairPackageDir()) {
+    return join(packageRoot, "templates", "launchd", "start-flair-with-admin-pass.sh");
+}
+/**
+ * Write `content` to `path` atomically: write to a temp file in the SAME
+ * directory, then rename over the target. Same-fs rename is atomic on POSIX,
+ * so a reader never observes a half-written file. `mode` is applied to the
+ * temp file from creation — pass 0o600 when `content` holds a secret, so the
+ * secret is never briefly world-readable on disk (flair#1573 slice a).
+ */
+export function writeFileAtomic(path, content, mode) {
+    const dir = dirname(path);
+    mkdirSync(dir, { recursive: true });
+    const tmpPath = join(dir, `.${basename(path)}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`);
+    try {
+        writeFileSync(tmpPath, content, { mode });
+        renameSync(tmpPath, path);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmpPath);
+        }
+        catch { /* best effort */ }
+        throw err;
+    }
+}
+/**
+ * Write the admin password to `path` with mode 0600 from creation (flair#1573
+ * slice a). The secret is written to a temp file in the same dir (0600) and
+ * renamed into place, so it is never briefly world-readable.
+ */
+export function writeAdminPassFile(path, content) {
+    writeFileAtomic(path, content, 0o600);
+}
 /**
  * Which launchd label an existing installation for `dataDir` is actually
  * registered under right now. Prefers the new instance-scoped label if its
@@ -854,6 +933,26 @@ export function buildOperationsApiConfig(opsPort, opsSocket, opsBindHost) {
         network: { port: opsNetworkPortValue(opsBindHost, opsPort), cors: true, domainSocket: opsSocket },
     };
 }
+/**
+ * Harper config that fully disables the MQTT broker (flair#1586).
+ *
+ * Flair does not use MQTT. Harper's mqtt component (server/mqtt.ts
+ * `handleApplication`) binds a TCP listener on `mqtt.network.port` (1883) and
+ * a TLS listener on `mqtt.network.securePort` (8883) whenever EITHER is truthy
+ * (`if (port || securePort)`), plus a WebSocket upgrade path when
+ * `mqtt.webSocket` is true. Nulling only `network.port` leaves
+ * `network.securePort` at its 8883 default, so the TLS listener still binds.
+ * Fully disabling MQTT requires nulling BOTH ports and turning off the
+ * WebSocket path.
+ *
+ * Note: config-root.schema.json still documents a flat `mqtt.port` /
+ * `mqtt.securePort`, but the runtime reads the nested `mqtt.network.*` form
+ * (see static/defaultConfig.yaml) — the flat keys are stale.
+ */
+const MQTT_DISABLED_CONFIG = {
+    network: { port: null, securePort: null },
+    webSocket: false,
+};
 /**
  * Build the flair-owned environment overrides for a DIRECT (non-launchd)
  * Harper spawn (flair#863) — shared by `flair start`'s fallback path and
@@ -868,6 +967,15 @@ export function buildOperationsApiConfig(opsPort, opsSocket, opsBindHost) {
  * the ops API to all interfaces on every restart/upgrade, and persisted it.
  * One builder means the next spawn site cannot reintroduce that gap.
  *
+ * MQTT (flair#1586): the direct-spawn path re-asserts the mqtt disable via the
+ * individual MQTT_* env vars (the same channel as OPERATIONSAPI_NETWORK_PORT /
+ * HTTP_PORT) rather than HARPER_SET_CONFIG, so it cannot reintroduce the
+ * SET_CONFIG drift/restore gap. "null" casts to a null port (Harper's
+ * castConfigValue), which passes config validation (portConstraints
+ * `.empty(null)`) and is falsy, so Harper's mqtt component (server/mqtt.ts
+ * `if (port || securePort)`) binds neither the TCP (1883) nor TLS (8883)
+ * listener, and MQTT_WEBSOCKET=false turns off the WebSocket upgrade path.
+ *
  * Deliberately omits HDB_ADMIN_PASSWORD when no password is in hand: an empty
  * string would strip Harper's auth on an existing install.
  */
@@ -881,6 +989,14 @@ export function buildDirectSpawnEnv(opts) {
         HDB_ADMIN_USERNAME: opts.adminUser,
         HTTP_PORT: String(opts.httpPort),
         OPERATIONSAPI_NETWORK_PORT: opsNetworkPortValue(opts.opsBindHost, opts.opsPort),
+        // flair#1586: fully disable the MQTT broker (Flair does not use it). "null"
+        // casts to a null port (Harper's castConfigValue), which passes config
+        // validation (portConstraints `.empty(null)`) and is falsy, so Harper binds
+        // neither the TCP (1883) nor TLS (8883) listener; MQTT_WEBSOCKET=false turns
+        // off the WebSocket upgrade path.
+        MQTT_NETWORK_PORT: "null",
+        MQTT_NETWORK_SECUREPORT: "null",
+        MQTT_WEBSOCKET: "false",
         LOCAL_STUDIO: "false",
         // flair#905 / lrf5: Harper's forceDowngradePrompt reads CONFIRM_DOWNGRADE
         // from the environment (via the `prompt` npm package's assignCmdEnvVariables
@@ -3429,7 +3545,7 @@ program
                 rootPath: dataDir,
                 http: { port: httpPort, cors: true, corsAccessList: [`http://127.0.0.1:${httpPort}`, `http://localhost:${httpPort}`] },
                 operationsApi: buildOperationsApiConfig(opsPort, opsSocket, opsBindHost),
-                mqtt: { network: { port: null }, webSocket: false },
+                mqtt: MQTT_DISABLED_CONFIG,
                 localStudio: { enabled: false },
                 authentication: { authorizeLocal: false, enableSessions: true },
             });
@@ -3451,6 +3567,12 @@ program
                 // all interfaces. See opsNetworkPortValue's doc comment.
                 OPERATIONSAPI_NETWORK_PORT: opsNetworkPortValue(opsBindHost, opsPort),
                 LOCAL_STUDIO: "false",
+                // flair#1586: same MQTT_* re-assert as buildDirectSpawnEnv / the
+                // launchd plist, so init cannot restore Harper's 1883/8883 defaults
+                // on a later boot that omits HARPER_SET_CONFIG.
+                MQTT_NETWORK_PORT: "null",
+                MQTT_NETWORK_SECUREPORT: "null",
+                MQTT_WEBSOCKET: "false",
             };
             // models (flair#504 Phase 1): the embedding backend registers itself
             // in-process at boot (resources/embeddings-boot.ts, loaded by
@@ -3554,7 +3676,7 @@ program
                     rootPath: dataDir,
                     http: { port: httpPort, cors: true, corsAccessList: [`http://127.0.0.1:${httpPort}`, `http://localhost:${httpPort}`] },
                     operationsApi: buildOperationsApiConfig(opsPort, opsSocket, opsBindHost),
-                    mqtt: { network: { port: null }, webSocket: false },
+                    mqtt: MQTT_DISABLED_CONFIG,
                     localStudio: { enabled: false },
                     authentication: { authorizeLocal: false, enableSessions: true },
                 });
@@ -11787,6 +11909,253 @@ function observeLaunchdManagement(dataDir, port) {
         list: realLaunchctlLister,
     });
 }
+/**
+ * Build the launchd plist for a `doctor --fix` repair (flair#1573 slice b).
+ *
+ * Deliberately DIVERGES from the `flair init` plist in one way that matters:
+ * it always uses the pass-file (secret-free) mode, so the regenerated plist
+ * never embeds HDB_ADMIN_PASSWORD inline — the exact regression this issue
+ * exists to prevent. The ports and ROOTPATH come from the instance's own
+ * harper-config.yaml (config authority, flair#914), never ~/.flair/config.yaml
+ * or defaults, so the repair cannot re-bootstrap Harper against a different
+ * directory or port.
+ *
+ * `config` is the parsed harper-config.yaml, already gated readable by the
+ * caller. Throws when the Harper binary cannot be resolved — a plist pointing
+ * at a missing binary is the stale-plist failure this repair must not write.
+ */
+function buildRepairPlist(dataDir, config) {
+    // The DEFAULT_PORT / httpPort-1 fallbacks below are practically unreachable:
+    // Harper writes harper-config.yaml ports on every boot (flair#914), so a
+    // readable config always carries them. They exist only as a last resort.
+    const httpPort = harperPortValue(config?.http?.port) ?? DEFAULT_PORT;
+    const opsPortRaw = config?.operationsApi?.network?.port;
+    const opsPort = harperPortValue(opsPortRaw) ?? (httpPort - 1);
+    const opsBind = detectOpsApiAllInterfacesBind(opsPortRaw);
+    const opsBindHost = opsBind.boundHost ?? "127.0.0.1";
+    const opsSocket = join(dataDir, "operations-server");
+    // Preserve the config's exact ops-port form (host-qualified or bare) so the
+    // regenerated plist neither re-narrows nor re-widens the bind — the
+    // no-re-bootstrap guarantee is mechanical, not best-effort.
+    const opsNetworkPort = typeof opsPortRaw === "string" && opsPortRaw.trim() !== ""
+        ? opsPortRaw.trim()
+        : opsNetworkPortValue(opsBindHost, opsPort);
+    const setConfig = JSON.stringify({
+        rootPath: dataDir,
+        http: { port: httpPort, cors: true, corsAccessList: [`http://127.0.0.1:${httpPort}`, `http://localhost:${httpPort}`] },
+        operationsApi: { network: { port: opsNetworkPort, cors: true, domainSocket: opsSocket } },
+        mqtt: MQTT_DISABLED_CONFIG,
+        localStudio: { enabled: false },
+        authentication: { authorizeLocal: false, enableSessions: true },
+    });
+    const harperBinPath = harperBin();
+    if (!harperBinPath)
+        throw new Error(harperBinNotFoundMessage(harperSearchRoots()));
+    const label = launchdLabel(dataDir);
+    const modelsDir = process.env.FLAIR_MODELS_DIR ?? join(dataDir, "models");
+    return buildLaunchdPlist({
+        label,
+        execPath: process.execPath,
+        harperBinPath,
+        workingDirectory: flairPackageDir(),
+        dataDir,
+        modelsDir,
+        setConfig,
+        adminUser: DEFAULT_ADMIN_USER,
+        adminPass: "", // ignored in pass-file mode
+        httpPort,
+        opsNetworkPort,
+        passFile: {
+            launcher: launchdLauncherPath(),
+            adminPassFile: defaultAdminPassPath(),
+            home: homedir(),
+            path: process.env.PATH ?? "/usr/bin:/bin:/usr/sbin:/sbin",
+        },
+    });
+}
+/**
+ * Compute the launchd repair plan for `dataDir` (flair#1573 slice b) WITHOUT
+ * executing it — the detect + classify + decide half. The doctor command uses
+ * this for dry-run / non-`--fix` reporting; `repairLaunchdManagement` (below)
+ * reuses it and then executes a `regenerate` or `adopt` plan.
+ */
+function planLaunchdRepairFor(dataDir, port) {
+    // Config authority gate (flair#914): the whole fix is gated on the
+    // instance's own harper-config.yaml being readable.
+    const config = harperConfigPath(dataDir) ? readHarperConfig(dataDir) : null;
+    const configReadable = config !== null;
+    // Observe the current state.
+    const observation = observeLaunchdManagement(dataDir, port);
+    // Classify the plist disposition (ownership guard's first question).
+    const { plistPath, isLegacy } = resolveLaunchdLabel(dataDir);
+    const disposition = classifyPlist(plistPath, dataDir, {
+        exists: existsSync,
+        read: (p) => { try {
+            return readFileSync(p, "utf-8");
+        }
+        catch {
+            return null;
+        } },
+        readRootPath: readPlistRootPath,
+    });
+    // Is a direct (non-launchd) process serving this instance right now?
+    const instancePid = resolveInstanceServingPid(dataDir, port);
+    const directProcessRunning = instancePid !== null && observation.state !== "managed";
+    const plan = planLaunchdRepair({ observation, disposition, plistPath, directProcessRunning, configReadable });
+    return { plan, plistPath, isLegacy, config };
+}
+/**
+ * Repair launchd management for `dataDir` (flair#1573 slice b) — the
+ * `doctor --fix` launchd repair for a MISSING, CORRUPT, or DETACHED plist.
+ *
+ * detect -> (adopt: clean-stop the direct process) -> regenerate (pass-file
+ * mode) -> load -> verify. The DECISION (state matrix + ownership guard +
+ * config authority) lives in planLaunchdRepair (src/lib/launchd-repair.ts);
+ * this is the EXECUTION, and it is the only place that touches the real
+ * filesystem and launchctl.
+ *
+ * Reuses the existing primitives rather than re-inventing them:
+ *   - observeLaunchdManagement / assessLaunchdManagement is the fail-loud
+ *     verifier (launchctl PID AND that PID is the serving process).
+ *   - ensureLaunchdServiceLoaded is the unload -> load -> start.
+ *   - the five-state liveness machine (gatherDaemonEvidence +
+ *     classifyDaemonState, flair#1454) attributes and clean-stops the direct
+ *     process on the adopt path — never a foreign/recycled pid, never kill -9.
+ *
+ * The adopt path (flair#1573 slice b2) BOUNCES the live instance: it
+ * clean-stops the direct-spawned process (SIGTERM + wait for exit), confirms
+ * the port is free, then regenerates + loads. A foreign/unattributable direct
+ * process is refused by the liveness machine (DISAGREEMENT/UNKNOWN), never
+ * signalled.
+ *
+ * Never reports success on a direct-start fallback: the final verify is
+ * assessLaunchdManagement, and anything short of `managed` is a `failed` result
+ * with the detached detail + remedy, never a silent pass. The whole executor
+ * arm is wrapped in try/catch (Kern's b1 defect): a throw becomes a named
+ * `failed` result (or an engine-backwards `refused`), never a crash mid-report.
+ */
+async function repairLaunchdManagement(dataDir, port) {
+    const { plan, plistPath, isLegacy, config } = planLaunchdRepairFor(dataDir, port);
+    switch (plan.kind) {
+        case "no-op":
+            return { kind: "no-op", reason: plan.reason, detail: plan.detail };
+        case "refuse":
+            return { kind: "refused", reason: plan.reason, detail: plan.detail, plistPath: plan.plistPath };
+        case "adopt":
+        case "regenerate": {
+            try {
+                // Guard FIRST (flair#1093): the repair is a boot path, and an older
+                // engine opening a newer store fails at the storage layer minutes
+                // later — same refusal as startFlairProcess. On the adopt arm this
+                // must run BEFORE the stop: it is a pure read whose inputs don't
+                // change during the repair, so guard-first refuses WITHOUT bouncing
+                // the live instance (guard-after-stop would SIGTERM the instance and
+                // then refuse, leaving it down with nothing to restart it).
+                guardEngineNotBackwards(dataDir);
+                // Adopt (flair#1573 slice b2): clean-stop the direct process first, so
+                // the regenerate + load below does not collide on the port.
+                if (plan.kind === "adopt") {
+                    const stop = await stopDirectProcessForAdopt(port, dataDir);
+                    if (stop)
+                        return stop; // a named failed result
+                }
+                const { execSync } = await import("node:child_process");
+                // Regenerate the plist (pass-file mode) and write it atomically.
+                // No secret is embedded, so 0644 is correct here.
+                const plist = buildRepairPlist(dataDir, config);
+                const newPlistPath = launchdPlistPath(launchdLabel(dataDir));
+                writeFileAtomic(newPlistPath, plist, 0o644);
+                // flair#1586 / #1581: a SET_CONFIG-less detach (MQTT_* via
+                // buildDirectSpawnEnv) can persist mqtt.network as mtls, port,
+                // securePort when Harper stored no originals for already-null ports.
+                // Adopt SET_CONFIG updates those keys in place and would otherwise
+                // leave harper-config.yaml not byte-identical to the first-repair
+                // file (port, securePort, mtls). Reorder only those scalar lines
+                // before launchd loads so the next persist matches the settled file.
+                const cfgPath = harperConfigPath(dataDir);
+                if (cfgPath) {
+                    const raw = readFileSync(cfgPath, "utf-8");
+                    const { text, changed } = stabilizeMqttNetworkKeyOrder(raw);
+                    if (changed)
+                        writeFileAtomic(cfgPath, text, 0o644);
+                }
+                // If the resolved plist was a pre-flair#693 legacy label, unload and
+                // remove it so it is not orphaned beside the regenerated one.
+                if (isLegacy && plistPath !== newPlistPath) {
+                    try {
+                        execSync(`launchctl unload "${plistPath}"`, { stdio: "pipe" });
+                    }
+                    catch { /* best effort */ }
+                    try {
+                        unlinkSync(plistPath);
+                    }
+                    catch { /* best effort */ }
+                }
+                // Load (unload -> load -> start).
+                ensureLaunchdServiceLoaded(dataDir, (cmd) => execSync(cmd, { stdio: "pipe" }));
+                // Verify (fail-loud).
+                const after = observeLaunchdManagement(dataDir, port);
+                if (after.state !== "managed") {
+                    return { kind: "failed", detail: after.detail, remedy: after.remedy };
+                }
+                const detail = plan.kind === "adopt"
+                    ? `adopted the direct-spawned instance into launchd (bounced the live instance): ${after.detail}`
+                    : after.detail;
+                return { kind: "repaired", detail };
+            }
+            catch (err) {
+                return mapRepairThrow(err);
+            }
+        }
+    }
+}
+/**
+ * Clean-stop the direct (non-launchd) process serving `dataDir`+`port` for the
+ * adopt path (flair#1573 slice b2). Returns a `failed` result when the process
+ * cannot be attributed (never stop a foreign process) or the port is still
+ * occupied after the stop; returns null when the port is free and the caller
+ * should proceed to regenerate + load.
+ *
+ * Reuses the five-state liveness machine (flair#1454): identity is verified
+ * (pidfile + sidecar + start time) before any signal, so a DISAGREEMENT/UNKNOWN
+ * verdict refuses rather than gambling on a recycled pid. The stop is SIGTERM +
+ * wait for exit — never kill -9.
+ */
+async function stopDirectProcessForAdopt(port, dataDir) {
+    const evidence = await gatherDaemonEvidence(port, dataDir);
+    const state = classifyDaemonState(evidence, { port, dataDir });
+    // SIGTERM + wait for exit for a verified live pid (RUNNING or WEDGED — a
+    // wedged daemon is recovery, not a recycled-pid gamble).
+    if (state.state === "RUNNING" || state.state === "WEDGED") {
+        try {
+            process.kill(state.pid, "SIGTERM");
+        }
+        catch { /* already gone */ }
+        try {
+            await waitForProcessExit(state.pid, STARTUP_TIMEOUT_MS);
+        }
+        catch { /* best-effort — the port check below surfaces the real problem */ }
+    }
+    const postStopHealth = await probeHealth(port);
+    const decision = decideAdoptStop(state, postStopHealth);
+    if (decision !== "proceed")
+        return decision;
+    // Belt-and-suspenders: lsof confirms no TCP listener remains before the
+    // caller loads the plist. probeHealth "refused" (ECONNREFUSED) already means
+    // nothing is listening, but a port that is BOUND yet refuses connections
+    // (backlog-full, or a non-HTTP listener) would still EADDRINUSE on load —
+    // this catches that rare case the HTTP probe cannot see.
+    const { execSync } = await import("node:child_process");
+    const listeners = listeningPidsOnPort(port, (cmd) => execSync(cmd, { encoding: "utf-8" }));
+    if (listeners.length > 0) {
+        return {
+            kind: "failed",
+            detail: `port still occupied after stopping the direct process (listener pid ${listeners.join(", ")})`,
+            remedy: ["flair stop", "flair doctor --fix"],
+        };
+    }
+    return null;
+}
 /**
  * Stop the local Flair (Harper) process — launchd `stop` on darwin when a
  * plist is present (falling back on failure), otherwise a manual SIGTERM by
@@ -13538,16 +13907,22 @@ program
     // catalog upgrade asserts. Adding a check to DOCTOR_CHECK_IDS widens
     // both. Extra doctor UX (pi, --fix, execution probe, continuity,
     // agent registration) stays below and does not redefine those checks.
+    //
+    // flair#1573 slice b — launchd management is diagnosed + repaired by its
+    // own section below (planLaunchdRepairFor / repairLaunchdManagement), not
+    // by the install-health catalog. The catalog's launchd check stays for
+    // `upgrade` (flair#1022), but doctor would otherwise double-count the same
+    // drift (catalog "detached" fail + repair "regenerate"/"adopt"/"refuse").
+    const doctorCatalogIds = DOCTOR_CHECK_IDS.filter((id) => id !== "launchd-management");
     const doctorCtx = {
         homeDir: homedir(),
         cwd: process.cwd(),
         detectedClientIds: detectedClients.map((c) => c.id),
-        launchd: observeLaunchdManagement(defaultDataDir(), effectivePort),
         keysDir,
         keyAgentIds,
         agentFlag: typeof opts.agent === "string" ? opts.agent : undefined,
     };
-    const catalogBefore = runDoctorChecks(doctorCtx);
+    const catalogBefore = runDoctorChecks(doctorCtx, { catalogIds: doctorCatalogIds });
     if (detectedClients.length === 0) {
         console.log(`  ${render.icons.info} No MCP client detected — skipping client-integration checks`);
     }
@@ -14016,7 +14391,7 @@ program
     // Catalog is the install-health verdict — count fail/unrun here, not
     // via a second issues++ on MCP / CLAUDE.md / SessionStart hook above.
     // --fix that cleared a catalog member shows up in the found→fixed delta.
-    const catalogAfter = autoFix ? runDoctorChecks(doctorCtx) : catalogBefore;
+    const catalogAfter = autoFix ? runDoctorChecks(doctorCtx, { catalogIds: doctorCatalogIds }) : catalogBefore;
     const catalogDelta = catalogIssueDelta(catalogBefore, catalogAfter);
     issues += catalogDelta.found;
     if (autoFix)
@@ -14025,6 +14400,74 @@ program
     for (const row of renderCatalogDoctorLines(catalogAfter)) {
         console.log(`  ${render.icons[row.icon]} ${row.line}`);
     }
+    // 7b. Launchd management repair (flair#1573 slice b) — `doctor --fix`
+    //     repairs a MISSING, CORRUPT, or DETACHED launchd plist. This is a
+    //     distinct concern from the install-health catalog above (which
+    //     `upgrade` also asserts), so it owns its own reporting + counting
+    //     rather than double-counting the catalog's launchd check. The
+    //     DECISION is pure (planLaunchdRepairFor -> planLaunchdRepair); the
+    //     EXECUTION (adopt: clean-stop -> regenerate pass-file plist -> load ->
+    //     verify) is repairLaunchdManagement, which is the only place that
+    //     touches the real filesystem and launchctl.
+    console.log(`\n  ${render.wrap(render.c.bold, "Launchd management")}`);
+    if (autoFix && !dryRun) {
+        // Execute the repair directly; it re-derives the plan internally and
+        // verifies via assessLaunchdManagement (fail-loud, never a silent pass).
+        const repairResult = await repairLaunchdManagement(defaultDataDir(), effectivePort);
+        switch (repairResult.kind) {
+            case "no-op":
+                console.log(`  ${render.icons.ok} ${repairResult.detail}`);
+                break;
+            case "refused":
+                issues++;
+                console.log(`  ${render.icons.error} ${repairResult.detail}`);
+                break;
+            case "repaired":
+                fixed++;
+                console.log(`  ${render.icons.ok} ${repairResult.detail}`);
+                break;
+            case "failed":
+                issues++;
+                console.log(`  ${render.icons.error} ${repairResult.detail}`);
+                if (repairResult.remedy)
+                    console.log(`     ${render.wrap(render.c.dim, "Fix:")} ${repairResult.remedy.join(" && ")}`);
+                break;
+        }
+    }
+    else {
+        // Report only (no --fix, or --fix --dry-run): compute the plan, touch
+        // nothing. A regenerate plan is drift; a refuse plan is a named refusal.
+        const repairPlan = planLaunchdRepairFor(defaultDataDir(), effectivePort);
+        switch (repairPlan.plan.kind) {
+            case "no-op":
+                console.log(`  ${render.icons.ok} ${repairPlan.plan.detail}`);
+                break;
+            case "refuse":
+                issues++;
+                console.log(`  ${render.icons.error} ${repairPlan.plan.detail}`);
+                break;
+            case "regenerate":
+                issues++;
+                console.log(`  ${render.icons.error} ${repairPlan.plan.detail}`);
+                if (dryRun) {
+                    console.log(`     ${render.wrap(render.c.dim, "Would regenerate")} the launchd plist (pass-file mode) and load it`);
+                }
+                else {
+                    console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair doctor --fix ${render.wrap(render.c.dim, "(regenerates the plist in pass-file mode, loads it, and verifies)")}`);
+                }
+                break;
+            case "adopt":
+                issues++;
+                console.log(`  ${render.icons.error} ${repairPlan.plan.detail}`);
+                if (dryRun) {
+                    console.log(`     ${render.wrap(render.c.dim, "Would adopt")} the direct-spawned instance into launchd (clean-stop, regenerate, load — bounces the live instance)`);
+                }
+                else {
+                    console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair doctor --fix ${render.wrap(render.c.dim, "(clean-stops the direct process, regenerates the plist, loads it, and verifies — bounces the live instance)")}`);
+                }
+                break;
+        }
+    }
     // 7a. Resolve which agent identities the two verified-read sections below
     // (Fleet presence, Migrations) iterate (flair#722). Previously both
     // sections required --agent explicitly; doctor already enumerates every

package/dist/lib/launchd-repair.js

@@ -0,0 +1,198 @@
+/**
+ * launchd-repair.ts — the `doctor --fix` launchd repair (flair#1573 slice b).
+ *
+ * Slice (a) made the no-inline-secret plist a product capability (pass-file
+ * mode + the product launcher). This module is the DECISION half of the repair
+ * that uses it: given the current launchd observation and the on-disk plist,
+ * decide what `doctor --fix` may do — and, just as importantly, what it must
+ * refuse to do. The EXECUTION half (regenerate the plist, adopt a running
+ * process, load, verify) lives in src/cli.ts, which owns the real filesystem
+ * and launchctl; everything here is pure and unit-testable without either.
+ *
+ * The two load-bearing decisions, both from the adjudication (issue comment
+ * 5607172125):
+ *
+ *   1. CONFIG AUTHORITY (flair#914). The whole fix is gated on the instance's
+ *      own harper-config.yaml being readable. ROOTPATH and the ports come from
+ *      that file — never ~/.flair/config.yaml, never defaults — because a
+ *      wrong ROOTPATH boots Harper against the wrong data directory, which is
+ *      the data-adjacent disaster this issue exists to prevent. If the config
+ *      cannot be read, there is no safe way to regenerate the plist, so the
+ *      repair refuses rather than invent a ROOTPATH.
+ *
+ *   2. OWNERSHIP GUARD (mirror flair#966). A plist is only repaired when it is
+ *      provably ours (ROOTPATH == dataDir), provably corrupt (not XML), or
+ *      absent. A valid plist whose ROOTPATH names a DIFFERENT directory is a
+ *      different instance and is refused. A valid plist with NO ROOTPATH at all
+ *      cannot be attributed, so it is refused and the file is named — the
+ *      operator decides. (No TTY confirm-adopt escape hatch exists; a
+ *      confirm-adopt for the unattributable case is slice b3, if ever.)
+ *
+ * The state matrix the plan collapses to:
+ *
+ *   - not-applicable (not macOS)  -> no-op.
+ *   - managed                     -> no-op ("already managed").
+ *   - absent / corrupt / ours     -> regenerate (pass-file mode).
+ *   - foreign / unattributable    -> refuse.
+ *   - config unreadable           -> refuse.
+ *   - detached-and-running (ours) -> adopt (clean-stop -> regenerate -> load).
+ *   - detached-and-running (foreign) -> refuse (ownership guard).
+ */
+import { resolve } from "node:path";
+/**
+ * Classify the plist at `plistPath` against `dataDir`.
+ *
+ * The "corrupt" test is deliberately structural, not a full plist parse: a
+ * Flair plist is an XML document with a `<plist>` root and a `<dict>` body,
+ * and the reported corruption (a bare JSON array) has neither. A full parser
+ * would pull the whole EnvironmentVariables dict — including the admin
+ * password — into memory to answer a question about two tags, and the shape
+ * here is fixed because buildLaunchdPlist wrote it.
+ */
+export function classifyPlist(plistPath, dataDir, deps) {
+    if (!deps.exists(plistPath))
+        return "absent";
+    const raw = deps.read(plistPath);
+    if (raw === null)
+        return "corrupt";
+    if (!/<plist[\s>]/.test(raw) || !/<dict>/.test(raw))
+        return "corrupt";
+    const rootPath = deps.readRootPath(plistPath);
+    if (rootPath === null)
+        return "unattributable";
+    return resolve(rootPath) === resolve(dataDir) ? "ours" : "foreign";
+}
+/**
+ * Decide what `doctor --fix` may do about launchd management.
+ *
+ * Pure: no filesystem, no launchctl. The executor in cli.ts turns a
+ * `regenerate` plan into a plist write + load + verify, an `adopt` plan into
+ * a clean-stop + regenerate + load + verify, and a `refuse` plan into a named
+ * refusal.
+ */
+export function planLaunchdRepair(input) {
+    const { observation, disposition, plistPath, directProcessRunning, configReadable } = input;
+    if (observation.state === "not-applicable") {
+        return { kind: "no-op", reason: "not-applicable", detail: observation.detail };
+    }
+    if (observation.state === "managed") {
+        return { kind: "no-op", reason: "already-managed", detail: observation.detail };
+    }
+    // Config authority (flair#914): no readable harper-config.yaml means no safe
+    // ROOTPATH/ports, so the repair cannot proceed without inventing them.
+    if (!configReadable) {
+        return {
+            kind: "refuse",
+            reason: "config-unreadable",
+            detail: "cannot repair launchd management: the instance's harper-config.yaml is missing or unreadable, " +
+                "so its ROOTPATH and ports cannot be established. Run 'flair init' to (re)create the instance.",
+        };
+    }
+    // Ownership guard (flair#966 mirror).
+    if (disposition === "foreign") {
+        return {
+            kind: "refuse",
+            reason: "foreign",
+            detail: `refusing to repair the launchd plist at ${plistPath}: it is registered to a different data ` +
+                "directory, so it belongs to a different Flair instance.",
+            plistPath,
+        };
+    }
+    if (disposition === "unattributable") {
+        return {
+            kind: "refuse",
+            reason: "unattributable",
+            detail: `refusing to repair the launchd plist at ${plistPath}: it has no ROOTPATH, so it cannot be ` +
+                "proven to belong to this instance.",
+            plistPath,
+        };
+    }
+    // Detached-and-running (flair#1573 slice b2): a direct (non-launchd) process
+    // is serving this instance. The plist is ours/absent/corrupt (the foreign and
+    // unattributable cases were refused above), so the direct process is THIS
+    // instance's and the adopt path clean-stops it before regenerating + loading.
+    // The plan states the bounce explicitly: adopt is the one repair that takes
+    // the live instance down and back up.
+    if (directProcessRunning) {
+        return {
+            kind: "adopt",
+            detail: "the instance is running but not under launchd (direct-spawned) — adopting it into launchd " +
+                "will clean-stop the live process (SIGTERM, wait for exit), regenerate the plist, and reload it. " +
+                "This bounces the live instance.",
+        };
+    }
+    // Repairable: absent, corrupt, or ours, with no direct process in the way.
+    return {
+        kind: "regenerate",
+        detail: "regenerating the launchd plist for this instance",
+    };
+}
+// ─── the executor's pure helpers (slice b2) ───────────────────────────────
+/**
+ * Map a throw from the executor arm to a named result (flair#1573 slice b2,
+ * Kern's b1 defect). `doctor --fix` must never crash mid-report: every throw
+ * becomes a `failed` result, except an engine-backwards refusal (flair#1093),
+ * which is a refusal by nature and is surfaced as `refused` so the operator
+ * sees the actor/state/remedy rather than a generic failure.
+ *
+ * NOTE: the engine-backwards `refused` intentionally carries its remedy in the
+ * detail prose (the actor/state/remedy sentence buildRecoveryLines renders),
+ * NOT in a structured `remedy` field — a refusal is a verdict, not a failure,
+ * and the prose is what the operator reads.
+ */
+export function mapRepairThrow(err) {
+    const e = err;
+    if (e?.engineBackwards) {
+        return { kind: "refused", reason: "engine-backwards", detail: e.message ?? "engine is backwards" };
+    }
+    return {
+        kind: "failed",
+        detail: e?.message ?? String(err),
+        remedy: ["flair doctor --fix"],
+    };
+}
+/**
+ * Decide whether the adopt path may proceed to regenerate + load, given the
+ * liveness classification of the direct process and the post-stop health probe
+ * (flair#1573 slice b2). Pure — the SIGTERM + wait and the probe happen in the
+ * executor; this only maps their results to a verdict.
+ *
+ *   - DISAGREEMENT / UNKNOWN -> failed (never stop a foreign/unattributable
+ *     process — the liveness machine refused to verify identity).
+ *   - post-stop health "ok"  -> failed ("port still occupied" — the old
+ *     process did not fully exit, so loading the new plist would collide).
+ *   - post-stop health "unreachable" -> failed ("port not confirmed free" — a
+ *     wedged daemon that ignored SIGTERM but stays BOUND to the port while no
+ *     longer serving /Health would EADDRINUSE on load; "unreachable" is the
+ *     probe's "cannot tell", so it must NOT proceed).
+ *   - post-stop health "refused" -> proceed (ECONNREFUSED — nothing is
+ *     listening, the port is provably free).
+ */
+export function decideAdoptStop(state, postStopHealth) {
+    switch (state.state) {
+        case "RUNNING":
+        case "WEDGED":
+        case "NOT_RUNNING":
+            break;
+        case "DISAGREEMENT":
+        case "UNKNOWN":
+            return {
+                kind: "failed",
+                detail: `refusing to adopt: ${state.detail}`,
+                remedy: ["flair stop", "flair doctor --fix"],
+            };
+    }
+    // Proceed ONLY when the port is provably free (ECONNREFUSED). "ok" means
+    // something is still serving; "unreachable" means a wedged daemon may still
+    // be BOUND to the port (ignored SIGTERM) — both would EADDRINUSE on load.
+    if (postStopHealth.kind !== "refused") {
+        return {
+            kind: "failed",
+            detail: postStopHealth.kind === "ok"
+                ? "port still occupied after stopping the direct process"
+                : "port not confirmed free after stopping the direct process (a wedged process may still hold it)",
+            remedy: ["flair stop", "flair doctor --fix"],
+        };
+    }
+    return "proceed";
+}

package/dist/lib/stabilize-mqtt-network.js

@@ -0,0 +1,123 @@
+/**
+ * stabilize-mqtt-network.ts — keep mqtt.network key order settled (flair#1586 / #1581).
+ *
+ * Harper's HARPER_SET_CONFIG persist (`applyRuntimeEnvVarConfig`) does
+ * `YAML.stringify` of the in-memory object, so map key order is insertion
+ * order. First repair on a default/populate yaml writes:
+ *
+ *   mqtt.network: port, securePort, mtls
+ *
+ * A later direct spawn that omits SET_CONFIG (production `buildDirectSpawnEnv`)
+ * runs `cleanupRemovedEnvVar`. When SET_CONFIG first saw those ports as
+ * already-null it stored no originals, so cleanup DELETES `port` / `securePort`
+ * and the MQTT_* env vars re-add them after the surviving `mtls` key:
+ *
+ *   mqtt.network: mtls, port, securePort
+ *
+ * Adopt SET_CONFIG then `setNestedValue`s in place and keeps that order.
+ * `#1581` requires harper-config.yaml to be byte-identical across
+ * `doctor --fix`, so the adopt persist fails even though every value matches.
+ *
+ * This helper rewrites only the `mqtt.network` scalar lines, in the file's
+ * own indent/quoting, to the first-repair order. Fail-closed: nested maps,
+ * comments inside the map, or a shape we cannot attribute are left untouched
+ * rather than dumping the whole document (a full dump would fail #1581 on
+ * its own).
+ */
+import { load as parseYaml } from "js-yaml";
+const PREFERRED_MQTT_NETWORK_KEYS = ["port", "securePort", "mtls"];
+export function stabilizeMqttNetworkKeyOrder(text) {
+    let parsed;
+    try {
+        parsed = parseYaml(text);
+    }
+    catch {
+        return { text, changed: false };
+    }
+    const net = parsed && typeof parsed === "object"
+        ? parsed.mqtt?.network
+        : undefined;
+    if (!net || typeof net !== "object" || Array.isArray(net)) {
+        return { text, changed: false };
+    }
+    const keys = Object.keys(net);
+    const preferred = PREFERRED_MQTT_NETWORK_KEYS.filter((k) => Object.prototype.hasOwnProperty.call(net, k));
+    const rest = keys.filter((k) => !preferred.includes(k));
+    const wanted = [...preferred, ...rest];
+    if (wanted.length === 0 || keys.every((k, i) => k === wanted[i])) {
+        return { text, changed: false };
+    }
+    const eol = text.includes("\r\n") ? "\r\n" : "\n";
+    const endsWithEol = text.endsWith("\n");
+    const lines = text.replace(/\r\n/g, "\n").replace(/\n$/, "").split("\n");
+    let mqttIdx = -1;
+    let mqttIndent = "";
+    for (let i = 0; i < lines.length; i++) {
+        const m = lines[i].match(/^([ \t]*)mqtt:\s*$/);
+        if (m) {
+            mqttIdx = i;
+            mqttIndent = m[1];
+            break;
+        }
+    }
+    if (mqttIdx < 0)
+        return { text, changed: false };
+    let netIdx = -1;
+    let netIndent = "";
+    for (let i = mqttIdx + 1; i < lines.length; i++) {
+        const trimmed = lines[i].trim();
+        if (trimmed === "" || trimmed.startsWith("#"))
+            continue;
+        const indent = lines[i].match(/^[ \t]*/)?.[0] ?? "";
+        if (indent.length <= mqttIndent.length)
+            break;
+        const m = lines[i].match(/^([ \t]*)network:\s*$/);
+        if (m) {
+            netIdx = i;
+            netIndent = m[1];
+            break;
+        }
+    }
+    if (netIdx < 0)
+        return { text, changed: false };
+    const items = [];
+    let bodyEnd = netIdx + 1;
+    for (let i = netIdx + 1; i < lines.length; i++) {
+        const trimmed = lines[i].trim();
+        if (trimmed === "")
+            return { text, changed: false };
+        if (trimmed.startsWith("#"))
+            return { text, changed: false };
+        const indent = lines[i].match(/^[ \t]*/)?.[0] ?? "";
+        if (indent.length <= netIndent.length) {
+            bodyEnd = i;
+            break;
+        }
+        const keyMatch = lines[i].match(/^[ \t]+([^:#\s]+):\s*/);
+        if (!keyMatch)
+            return { text, changed: false };
+        const next = lines[i + 1];
+        if (next) {
+            const nextTrim = next.trim();
+            if (nextTrim !== "" && !nextTrim.startsWith("#")) {
+                const nextIndent = next.match(/^[ \t]*/)?.[0] ?? "";
+                if (nextIndent.length > indent.length)
+                    return { text, changed: false };
+            }
+        }
+        items.push({ key: keyMatch[1], line: lines[i] });
+        bodyEnd = i + 1;
+    }
+    if (items.length === 0)
+        return { text, changed: false };
+    const fileKeys = items.map((it) => it.key);
+    if (fileKeys.length !== wanted.length || wanted.some((k) => !fileKeys.includes(k))) {
+        return { text, changed: false };
+    }
+    if (fileKeys.every((k, i) => k === wanted[i]))
+        return { text, changed: false };
+    const byKey = new Map(items.map((it) => [it.key, it.line]));
+    const newBody = wanted.map((k) => byKey.get(k));
+    const newLines = [...lines.slice(0, netIdx + 1), ...newBody, ...lines.slice(bodyEnd)];
+    return { text: newLines.join(eol) + (endsWithEol ? eol : ""), changed: true };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.52.0",
+  "version": "0.53.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/launchd/start-flair-with-admin-pass.sh

@@ -0,0 +1,73 @@
+#!/bin/sh
+# start-flair-with-admin-pass.sh — product-owned launchd launcher (flair#1573).
+#
+# Reads the Flair admin password from a 0600 file and execs Harper
+# NON-INTERACTIVELY. The secret never appears in the launchd plist: it enters
+# the process environment here, from the file, at start time. This is the
+# product shape of the no-inline-secret pattern — the plist's ProgramArguments
+# point at this launcher instead of embedding HDB_ADMIN_PASSWORD.
+#
+# Usage: start-flair-with-admin-pass.sh <admin-pass-file> <node> <harper-bin>
+#
+#   admin-pass-file  path to the 0600 file holding the admin password
+#   node             the node binary to exec
+#   harper-bin       Harper's entrypoint (harper.js)
+#
+# HDB_ADMIN_USERNAME is already in the launchd environment (it is not a
+# secret); only the password is read from the file here. HOME, PATH and the
+# Harper config (HARPER_SET_CONFIG / ROOTPATH / FLAIR_MODELS_DIR) are also
+# supplied by the plist's EnvironmentVariables, so Harper boots without ever
+# hitting its interactive readline prompt under launchd's minimal env.
+
+set -eu
+
+ADMIN_PASS_FILE="$1"
+NODE="$2"
+HARPER_BIN="$3"
+
+if [ ! -f "$ADMIN_PASS_FILE" ]; then
+  echo "start-flair-with-admin-pass: admin-pass file not found: $ADMIN_PASS_FILE" >&2
+  exit 1
+fi
+
+if [ ! -r "$ADMIN_PASS_FILE" ]; then
+  echo "start-flair-with-admin-pass: admin-pass file not readable: $ADMIN_PASS_FILE" >&2
+  exit 1
+fi
+
+# Re-verify owner-only (0600) at READ time, not just at `flair init` write
+# time. A file that drifted to 0644 after init (umask change, backup tool,
+# tar restore) would leak the secret to any reader on the host. Mirrors
+# readSecretFileSecure (src/lib/auth-resolve.ts), which refuses any group/other
+# permission bit. `stat -f %Lp` is macOS (the launchd host); `stat -c %a` is
+# Linux (the unit-test host). The two syntaxes are mutually exclusive, so
+# branch on the OS rather than chaining with `||` — on Linux `stat -f %Lp`
+# prints filesystem info to stdout *and* exits non-zero, which would pollute
+# the captured mode. Fail CLOSED: an unreadable mode (empty) refuses rather
+# than proceeding on a guess.
+case "$(uname -s)" in
+  Darwin) MODE="$(stat -f %Lp "$ADMIN_PASS_FILE" 2>/dev/null)" ;;
+  *)      MODE="$(stat -c %a "$ADMIN_PASS_FILE" 2>/dev/null)" ;;
+esac
+case "$MODE" in
+  *00) : ;;
+  *)
+    echo "start-flair-with-admin-pass: admin-pass file permissions '${MODE:-unknown}' are too open (expected 600): $ADMIN_PASS_FILE" >&2
+    exit 1
+    ;;
+esac
+
+# Read the secret. Command substitution strips a trailing newline, which is
+# what `flair init` writes (base64url + "\n"); the value itself is preserved
+# verbatim by the double quotes.
+ADMIN_PASS="$(cat "$ADMIN_PASS_FILE")"
+if [ -z "$ADMIN_PASS" ]; then
+  echo "start-flair-with-admin-pass: admin-pass file is empty: $ADMIN_PASS_FILE" >&2
+  exit 1
+fi
+
+export HDB_ADMIN_PASSWORD="$ADMIN_PASS"
+
+# exec (not spawn) so launchd tracks Harper itself — the job's PID is Harper's
+# PID, and KeepAlive restarts the real service rather than a dead launcher.
+exec "$NODE" "$HARPER_BIN" run .