@tpsdev-ai/flair 0.51.2 → 0.53.0

package/dist/doctor-client.js

@@ -839,6 +839,41 @@ export function detectWiredFlairMcp(homeDir) {
     }
     return { wired, pinnedVersion };
 }
+/** The `@tpsdev-ai/flair-mcp` version pinned in a client's MCP config, or null
+ *  when the client is unwired or wired unpinned. */
+export function readClientMcpPin(clientId, homeDir) {
+    const configPath = withHome(homeDir, () => clientConfigPath(clientId));
+    return extractFlairMcpPin(readTextFile(configPath) ?? "");
+}
+/**
+ * Compare a harness's SessionStart hook pin against its MCP client pin.
+ *
+ * `flair init`/`flair upgrade`/`flair hook install` keep both on the same
+ * @version. A skew means an upgrade moved the client block forward but left
+ * the hook behind (flair#1516) — so every session silently launches the OLD
+ * adapter while the client block advertises the new one. `flair doctor` used
+ * to report such a hook as wired "and still runs" without ever comparing the
+ * two pins.
+ *
+ * Only a concrete-vs-concrete difference is a skew: an unpinned hook (pre-
+ * #1143) or a missing pin on either side is "nothing to compare", never a
+ * false skew.
+ */
+export function checkSessionStartHookPinSkew(homeDir, harness) {
+    const hookPath = harness === "codex"
+        ? join(homeDir, ".codex", "hooks.json")
+        : join(homeDir, ".claude", "settings.json");
+    const hook = checkSessionStartHook(homeDir, hookPath);
+    const hookWired = hook.present && isFlairHookCommand(hook.command ?? "");
+    const hookPin = hookWired ? extractFlairMcpPin(hook.command ?? "") : null;
+    const clientPin = readClientMcpPin(harness, homeDir);
+    return {
+        hookWired,
+        hookPin,
+        clientPin,
+        skewed: !!hookPin && !!clientPin && hookPin !== clientPin,
+    };
+}
 /**
  * Merge-safe insert of a Flair SessionStart hook group into the harness
  * settings file (default ~/.claude/settings.json) — creates the file/array

package/dist/hook-install.js

@@ -55,6 +55,7 @@
 import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { SESSION_START_HOOK_MARKER, buildSessionStartHookCommand, buildContinuityCaptureHookCommand, checkContinuityCaptureHooks, computeContinuityHookInstall, computeContinuityHookRemoval, hookCommandIsSilenced, isHookCommandValueSafe, isSessionStartHookInvocation, readClientMcpBlock, } from "./doctor-client.js";
+import { mcpServerSpec } from "./lib/mcp-spec.js";
 // ── harness registry ────────────────────────────────────────────────────────
 /** SessionStart hook harnesses. A second harness is an additive registry
  *  entry, not a rewrite (Kern's #719 verdict: "a switch statement... is
@@ -352,6 +353,79 @@ export function installHook(opts) {
         backupPath, delta,
     };
 }
+/**
+ * Re-pin an ALREADY-WIRED Flair SessionStart hook to the current
+ * mcpServerSpec(), preserving the agent id and Flair URL the entry already
+ * carries.
+ *
+ * This is `flair upgrade`'s hook counterpart to refreshing the MCP client
+ * pins (flair#1516). `flair upgrade` re-pins every wired client's MCP block
+ * to the new @version but used to leave the SessionStart hook command on the
+ * OLD one — so a user who upgraded by the documented path kept launching the
+ * previous adapter on every session, silently, while `flair doctor` reported
+ * the hook "still runs" without noticing the skew.
+ *
+ * NEVER adds a hook — a home with no Flair hook is a clean `skip`, not an
+ * `add`: wiring a hook is `flair init` / `flair hook install`, an opt-in the
+ * upgrade path must not make on the user's behalf. Only rewrites the exact
+ * canonical `npx -y -p …` invocation Flair itself writes (pinned or the
+ * pre-#1143 unpinned form); a hand-edited command is the user's and is left
+ * untouched. Fail-closed on a malformed settings file and backs up before any
+ * real write — the same Sherlock conditions installHook implements. Idempotent:
+ * a second call is a `noop`.
+ */
+export function repinSessionStartHook(homeDir, harness) {
+    const path = hookSettingsPath(homeDir, harness);
+    const skip = (ok, message) => ({ ok, path, harness, action: "skip", message, backupPath: null });
+    const read = readSettingsFile(path);
+    if (read.parseError) {
+        return skip(false, `${read.parseError} — refusing to re-pin a file we can't safely parse; left untouched`);
+    }
+    const config = read.parsed ?? {};
+    const existing = findHookEntry(config);
+    if (!existing) {
+        return skip(true, `no Flair SessionStart hook in ${path} — nothing to re-pin`);
+    }
+    const current = config.hooks.SessionStart[existing.groupIndex].hooks[existing.hookIndex]?.command ?? "";
+    // Only re-pin the canonical invocation Flair writes. A legacy (pre-#1143,
+    // no `-p`) or hand-edited command is NOT version-bumped here — `flair
+    // doctor`/`flair hook install` own the legacy → current rewrite, with their
+    // own consent.
+    if (!isSessionStartHookInvocation(current)) {
+        return skip(true, `SessionStart hook in ${path} is not the canonical form Flair writes — left untouched`);
+    }
+    const env = parseHookCommandEnv(current);
+    if (!env.agentId) {
+        return skip(true, `could not read the agent id from the SessionStart hook in ${path} — left untouched`);
+    }
+    let next;
+    try {
+        next = buildSessionStartHookCommand(env.agentId, env.flairUrl);
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return skip(false, `could not rebuild the SessionStart hook command for ${path}: ${reason}`);
+    }
+    if (next === current) {
+        return { ok: true, path, harness, action: "noop", message: `SessionStart hook in ${path} already pinned to ${mcpServerSpec()}`, backupPath: null };
+    }
+    let backupPath = null;
+    try {
+        backupPath = takeBackup(path);
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return skip(false, `could not back up ${path} before re-pinning it: ${reason} — refusing to touch it`);
+    }
+    const newConfig = deepClone(config);
+    newConfig.hooks.SessionStart[existing.groupIndex].hooks[existing.hookIndex] = { type: "command", command: next };
+    writeFileSync(path, JSON.stringify(newConfig, null, 2) + "\n");
+    return {
+        ok: true, path, harness, action: "update",
+        message: `re-pinned the SessionStart hook in ${path} to ${mcpServerSpec()}`,
+        backupPath,
+    };
+}
 /** Symmetric removal — deletes ONLY our hook entry (found the same way
  *  install finds it: SESSION_START_HOOK_MARKER substring match), never
  *  touches unrelated hooks/keys. A no-op (ok:true, action "noop") when

package/dist/install/global-bin-path.js

@@ -145,6 +145,20 @@ export function prefixFromPackageDir(packageDir, platform = process.platform) {
     const kept = segments.slice(0, Math.max(1, segments.length - ups));
     return kept.join(win32 ? "\\" : "/") || (win32 ? packageDir : "/");
 }
+/**
+ * Inverse of {@link prefixFromPackageDir}: where a global
+ * `@tpsdev-ai/flair` install lives under `prefix`.
+ *
+ * String-based (not path.join) so the win32 shape stays faithful even in
+ * tests running on posix hosts.
+ */
+export function npmGlobalFlairPackageDir(prefix, platform = process.platform) {
+    const win32 = platform === "win32";
+    const clean = stripTrailingSeps(prefix.trim(), win32);
+    return win32
+        ? [clean, "node_modules", "@tpsdev-ai", "flair"].join("\\")
+        : [clean, "lib", "node_modules", "@tpsdev-ai", "flair"].join("/");
+}
 function defaultBinDirHasFlair(binDir, platform) {
     const names = platform === "win32" ? ["flair.cmd", "flair"] : ["flair"];
     return names.some((n) => existsSync(join(binDir, n)));

package/dist/lib/auth-resolve.js

@@ -445,6 +445,21 @@ export async function authedRequest(method, path, body, opts) {
             console.error(`Warning: Ed25519 auth failed for agent '${opts.agentId}': ${message}`);
         }
     }
+    // Tier 1.5: flag-pinned agent (flair#1500) — an --agent flag identity signs
+    // as THAT agent BEFORE env admin. A flag-pinned agent with no key on disk is
+    // a hard error (never a warning, never a silent substitution to env admin or
+    // the local admin-pass file): the operator named a specific identity and the
+    // CLI must not quietly sign as someone else.
+    if (!authHeader && opts.agentIdSource === "flag" && opts.agentId) {
+        const keyPath = resolveKeyPath(opts.agentId);
+        if (!keyPath) {
+            throw new Error(`--agent '${opts.agentId}' has no signing key. Expected a key at ` +
+                `${join(defaultKeysDir(), `${opts.agentId}.key`)} (or set FLAIR_KEY_DIR ` +
+                `to a directory containing it). Refusing to fall back to FLAIR_ADMIN_PASS ` +
+                `or the local admin-pass file.`);
+        }
+        authHeader = buildEd25519Auth(opts.agentId, method, path, keyPath);
+    }
     // Tier 2: env — FLAIR_TOKEN (Bearer), else FLAIR_ADMIN_PASS/HDB_ADMIN_PASSWORD (Basic).
     if (!authHeader) {
         if (process.env.FLAIR_TOKEN) {

package/dist/lib/doctor-run.js

@@ -53,19 +53,24 @@ function runMcpBlock(ctx) {
     if (mcp.length === 0) {
         return result(id, label, "skip", { detail: "no MCP client detected" });
     }
-    const missing = [];
-    for (const clientId of mcp) {
-        const block = readClientMcpBlock(clientId, ctx.homeDir);
-        if (!block.present)
-            missing.push(`${clientId} (${block.configPath})`);
-    }
-    if (missing.length > 0) {
-        return result(id, label, "fail", {
-            detail: `no Flair MCP server configured: ${missing.join(", ")}`,
-            remedy: "flair doctor --fix",
+    // flair#989: DETECTION is not OPT-IN. A client whose binary or config merely
+    // exists on the box — e.g. Codex is installed but the user ran `flair init
+    // --client claude-code` — is not an install FAILURE for lacking a Flair
+    // block; it was never opted into. The MCP block IS the opt-in signal, so the
+    // install-health subject is the WIRED clients only. An un-wired but detected
+    // client is surfaced as info by `flair doctor`, never counted as a failure
+    // here (which used to inflate the ✗ count with clients the user never chose).
+    const wired = mcp.filter((clientId) => readClientMcpBlock(clientId, ctx.homeDir).present);
+    if (wired.length === 0) {
+        // Detected clients exist, but Flair is wired to none of them. Not a
+        // per-client failure (nothing was opted in) — a skip that names the
+        // detected clients, so a zero-wiring run neither invents a failure the
+        // user didn't cause nor masquerades as a verified-healthy wiring.
+        return result(id, label, "skip", {
+            detail: `no Flair MCP server wired into any detected client (${mcp.join(", ")}) — wire one with: flair init --client <id>`,
         });
     }
-    return result(id, label, "pass", { detail: `configured for ${mcp.join(", ")}` });
+    return result(id, label, "pass", { detail: `configured for ${wired.join(", ")}` });
 }
 function runFlairUrl(ctx) {
     const id = "flair-url";
@@ -91,8 +96,11 @@ function runFlairUrl(ctx) {
 function runClaudeMd(ctx) {
     const id = "claude-md";
     const label = "CLAUDE.md bootstrap";
-    if (!ctx.detectedClientIds.includes("claude-code")) {
-        return result(id, label, "skip", { detail: "Claude Code not detected" });
+    // flair#989: only relevant once Claude Code is actually WIRED. A Claude Code
+    // binary merely present on the box (never `flair init`-ed) does not owe a
+    // CLAUDE.md bootstrap line — same opt-in rule as runMcpBlock/runSessionStartHook.
+    if (!ctx.detectedClientIds.includes("claude-code") || !readClientMcpBlock("claude-code", ctx.homeDir).present) {
+        return result(id, label, "skip", { detail: "Claude Code not wired" });
     }
     const check = checkClaudeMdBootstrap(ctx.cwd, ctx.homeDir);
     if (!check.present) {
@@ -106,9 +114,14 @@ function runClaudeMd(ctx) {
 function runSessionStartHook(ctx) {
     const id = "session-start-hook";
     const label = "SessionStart hook";
-    const harnesses = SUPPORTED_HARNESSES.filter((h) => ctx.detectedClientIds.includes(h));
+    // flair#989: only a harness the user actually WIRED (its MCP block is
+    // present) owes a SessionStart hook. A merely-detected harness — Codex on
+    // PATH that was never `flair init`-ed — is not an install failure for
+    // lacking a hook it was never asked to have. This mirrors runMcpBlock's
+    // opt-in rule so a detected-but-unwired client can't fail either check.
+    const harnesses = SUPPORTED_HARNESSES.filter((h) => ctx.detectedClientIds.includes(h) && readClientMcpBlock(h, ctx.homeDir).present);
     if (harnesses.length === 0) {
-        return result(id, label, "skip", { detail: "no hook-capable client detected" });
+        return result(id, label, "skip", { detail: "no wired hook-capable client detected" });
     }
     const missing = [];
     const loud = [];

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 };
+}