@tpsdev-ai/flair 0.44.13 → 0.46.0

package/dist/resources/memory-visibility.js

@@ -79,3 +79,51 @@ export function assertValidVisibility(visibility) {
         `(got: ${JSON.stringify(visibility)}). Omit it to use the durability-keyed default: ` +
         `permanent/persistent -> shared, standard/ephemeral -> private.`);
 }
+/** Deliberately a LOCAL literal, not an import from memory-durability.ts: this
+ *  module's zero-imports property is load-bearing (see the header — src/cli.ts
+ *  must be able to import it with no transitive baggage), and the tripwire
+ *  tests in test/unit/visibility-write-validation.test.ts pin the value to the
+ *  durability enum so the two cannot drift apart silently. */
+export const EPHEMERAL_DURABILITY = "ephemeral";
+/**
+ * ─── flair#1257 hard precondition: ephemeral memories are private-only ───────
+ *
+ * `ephemeral` is the continuity-journal tier: auto-captured working state,
+ * self-pruning, never meant to leave its owner. `defaultVisibilityForDurability`
+ * keys it to `private`, but a DEFAULT is not a CONSTRAINT — before this guard,
+ * an explicit `visibility:"shared"` on an ephemeral write was accepted, which
+ * would have made journal entries org-readable AND federation-pushed. Kern's
+ * #1257 ruling requires the server to REFUSE the combination so the boundary
+ * holds for every caller (REST, in-process, any adapter), not just the hooks
+ * that promise to send `private` explicitly.
+ *
+ * The rule is deliberately "ephemeral may only carry `private` or nothing",
+ * NOT "refuse ephemeral+shared": on the read side any value other than the
+ * literal "private" resolves to non-private (the migration invariant above),
+ * so an unknown value on an ephemeral row would leak exactly like "shared".
+ * assertValidVisibility refuses unknowns first at both call sites, but this
+ * guard must stay fail-closed on its own — unknown means refused, not allowed.
+ *
+ * Absent (`undefined`/`null`) is accepted: it resolves through the
+ * durability-keyed default, which for ephemeral is `private` — the documented,
+ * intentional path (and the one the continuity hooks use, belt-and-suspenders
+ * with an explicit `private`).
+ *
+ * Returns an error message, or null when the combination is acceptable.
+ * `durability` is the EFFECTIVE durability of the row being written — for
+ * Memory.put() updates, where the payload may omit durability, the caller
+ * passes the pre-existing row's durability as the fallback so a PUT that flips
+ * a stored ephemeral row to shared refuses too.
+ */
+export function assertVisibilityAllowedForDurability(durability, visibility) {
+    if (durability !== EPHEMERAL_DURABILITY)
+        return null;
+    if (visibility === undefined || visibility === null || visibility === PRIVATE_VISIBILITY) {
+        return null;
+    }
+    return (`ephemeral memories are private-only (continuity journal tier, flair#1257): ` +
+        `durability "${EPHEMERAL_DURABILITY}" cannot be written with visibility ${JSON.stringify(visibility)}. ` +
+        `Omit visibility (the durability-keyed default is "${PRIVATE_VISIBILITY}") or set it to ` +
+        `"${PRIVATE_VISIBILITY}"; for a memory other agents should read, use durability ` +
+        `"standard", "persistent", or "permanent".`);
+}

package/dist/resources/semantic-retrieval-core.js

@@ -29,14 +29,29 @@
 // withDetachedTxn's transaction-chain workaround — both SemanticSearch and
 // MemoryBootstrap are Harper Resources with their own `ctx`).
 //
-// Returns results AFTER all filters, sorted best-first by `_score` — bounded
-// ONLY by the `limit` the caller chose to push down (the core never
+// Returns results AFTER all filters, sorted best-first by RETRIEVAL RANK —
+// bounded ONLY by the `limit` the caller chose to push down (the core never
 // multiplies `limit` internally; any overfetch policy — SemanticSearch's
 // CANDIDATE_MULTIPLIER, MemoryBootstrap's K formula — is the CALLER's
 // decision, made
 // before calling in). Never exposes which internal leg (BM25+RRF hybrid vs.
 // legacy HNSW-only vs. keyword-only fallback) produced a given result — the
 // output shape is identical regardless of `hybrid`.
+//
+// ── SCORE CONTRACT (flair#985) ───────────────────────────────────────────────
+// `_score` under `scoring:"raw"` is ALWAYS an ABSOLUTE similarity (cosine of
+// the query and the record's stored embedding, plus the legacy +0.05 substring
+// keyword bump) — on every path, hybrid included. It is NEVER a
+// rank-normalized value. Ordering and score are deliberately decoupled on the
+// hybrid path: results are ORDERED by the fused RRF rank (that ordering is the
+// hybrid recall win), but each result's `_score` reports its true evidence, so
+// order and `_score` can disagree. The pre-#985 hybrid path reported the
+// normalized RRF value AS `_score`, which pinned the top result of ANY query
+// at 1.0 — and every consumer thresholding `_score` as a similarity (the
+// pre-0.18 flair-client dedup gate at 0.95, `minScore`, `flair doctor`'s
+// embed-verify probe) failed open at maximal confidence. For the dedup gate
+// that meant EVERY memory_store from a stale client silently dropped its
+// content into the arbitrary top-1 match — the #985 data-loss report.
 import { databases } from "harper";
 import { withDetachedTxn } from "./table-helpers.js";
 import { wrapUntrusted } from "./content-safety.js";
@@ -85,10 +100,12 @@ export async function retrieveCandidates(params) {
         // ── (a) Semantic candidate records (best-first) ──────────────────────
         const semRecords = [];
         const semIds = [];
-        // flair#744 slice 2: absolute cosine similarity per semantic candidate
-        // (from the HNSW `$distance`), captured HERE before `$distance` is stripped
-        // downstream — the confidence signal the abstention decision reads (only
-        // when `withSemSimilarity`; empty/unused otherwise).
+        // Absolute cosine similarity per semantic candidate (from the HNSW
+        // `$distance`), captured HERE before `$distance` is stripped downstream.
+        // Captured UNCONDITIONALLY (flair#985): this is the value `_score` reports
+        // under `scoring:"raw"` — see the fused loop below — and, when
+        // `withSemSimilarity` (flair#744 slice 2), also the confidence signal the
+        // abstention decision reads via the opt-in `_semSimilarity` field.
         const semSimById = new Map();
         if (qEmb) {
             const semQuery = {
@@ -119,9 +136,20 @@ export async function retrieveCandidates(params) {
                     continue;
                 if (!passesAllowed(record))
                     continue;
-                if (withSemSimilarity && record.$distance !== undefined) {
+                if (record.$distance !== undefined) {
                     semSimById.set(record.id, distanceToSimilarity(record.$distance));
                 }
+                else {
+                    // Harper's cosine-sort query omits `$distance` for a SINGLETON
+                    // post-filter result set (see the legacy path below and
+                    // resources/SemanticSearch.ts's original writeup). Point-lookup the
+                    // record and compute cosine ourselves from its real stored
+                    // embedding — a missing/empty stored embedding yields 0 (safe "no
+                    // semantic evidence"), never a false-high score.
+                    const full = await withDetachedTxn(ctx, () => databases.flair.Memory.get(record.id));
+                    const storedEmbedding = Array.isArray(full?.embedding) ? full.embedding : [];
+                    semSimById.set(record.id, cosineSimilarity(qEmb, storedEmbedding));
+                }
                 semRecords.push(record);
                 semIds.push(record.id);
             }
@@ -175,40 +203,78 @@ export async function retrieveCandidates(params) {
                     _score: Math.round(finalScore * 1000) / 1000,
                     _rawScore: scoring !== "raw" ? Math.round(rawScore * 1000) / 1000 : undefined,
                     _source: source,
+                    _rank: finalScore,
                 });
             }
         }
         else {
-            // ── Candidate-union RRF → normalized [0,1] rawScore ────────────────
+            // ── Candidate-union RRF → normalized [0,1] RANKING value ────────────
+            // flair#985: the fused RRF value ORDERS results but is never REPORTED
+            // as a score. RRF normalization pins the top candidate at exactly 1.0
+            // regardless of how weak the real match is — reporting it as `_score`
+            // (the pre-#985 behavior) silently changed the meaning of `_score` from
+            // "absolute similarity, 0.95 ≈ near-duplicate" to "relative rank". Every
+            // consumer that thresholds `_score` as a similarity then fails OPEN at
+            // maximal confidence: the pre-0.18 flair-client dedup gate (`score >=
+            // 0.95` → suppress the write) suppressed EVERY memory_store into the
+            // arbitrary top-1 — however unrelated — which is the #985 field report
+            // (4/5 writes silently lost cross-topic). `minScore`, `flair doctor`'s
+            // embed-verify probe, and compositeScore's relevance floors all carry
+            // the same absolute-scale expectation. So: rank by fusion (`_rank`,
+            // internal, stripped before return — the hybrid recall win lives in the
+            // fused ORDER), report absolute evidence (`_score` = true cosine + the
+            // legacy keyword bump, same scale as the legacy HNSW-only path below).
             const fused = fuseRrfNormalized(semIds, bm25Ids);
             for (const [id, rrfRaw] of fused) {
                 const record = allowedById.get(id);
                 if (!record)
                     continue; // should not happen — union ⊆ allowed
-                const rawScore = rrfRaw; // already normalized to [0,1]
-                let finalScore = scoring === "raw" ? rawScore : compositeScore(rawScore, record);
+                // Absolute semantic similarity for this candidate. Sem-leg candidates
+                // already carry it (captured above, incl. the singleton-`$distance`
+                // fallback). A BM25-only candidate never went through the HNSW leg —
+                // point-lookup its stored embedding and compute the true cosine, so a
+                // genuinely-relevant lexical rescue reports its real similarity
+                // instead of a fabricated one (missing/legacy embedding ⇒ 0, safe).
+                let semSim = semSimById.get(id);
+                if (semSim === undefined && qEmb) {
+                    const full = await withDetachedTxn(ctx, () => databases.flair.Memory.get(id));
+                    const storedEmbedding = Array.isArray(full?.embedding) ? full.embedding : [];
+                    semSim = cosineSimilarity(qEmb, storedEmbedding);
+                    semSimById.set(id, semSim);
+                }
+                let keywordHit = false;
+                if (q && String(record.content || "").toLowerCase().includes(String(q).toLowerCase())) {
+                    keywordHit = true;
+                }
+                const rawScore = (semSim ?? 0) + (keywordHit ? 0.05 : 0);
+                let finalScore = scoring === "raw" ? rawScore : compositeScore(rrfRaw, record);
                 if (temporalBoost > 1.0)
                     finalScore *= temporalBoost;
                 const isFlagged = record._safetyFlags && Array.isArray(record._safetyFlags) && record._safetyFlags.length > 0;
                 const source = record.agentId !== agentId ? record.agentId : undefined;
-                // flair#744 slice 2: absolute cosine confidence for the abstention
-                // decision — only for records that had a semantic (HNSW) candidate; a
-                // BM25-lexical-only match carries no cosine and contributes none.
-                const semSim = withSemSimilarity ? semSimById.get(id) : undefined;
                 results.push({
                     ...record,
                     content: isFlagged ? wrapUntrusted(record.content, source) : record.content,
                     _score: Math.round(finalScore * 1000) / 1000,
                     _rawScore: scoring !== "raw" ? Math.round(rawScore * 1000) / 1000 : undefined,
                     _source: source,
-                    ...(semSim !== undefined ? { _semSimilarity: semSim } : {}),
+                    // Ordering key: fused rank for raw mode; composite value for
+                    // composite mode (composite ordering is unchanged by #985 — its
+                    // rrfRaw input and result order are exactly the pre-#985 behavior).
+                    _rank: scoring === "raw" ? rrfRaw : finalScore,
+                    // flair#744 slice 2: the opt-in absolute-confidence field for the
+                    // abstention decision. Attach remains OPT-IN so non-abstain
+                    // responses stay byte-identical (the capture above is now
+                    // unconditional, but the response field is not).
+                    ...(withSemSimilarity && semSim !== undefined ? { _semSimilarity: semSim } : {}),
                 });
             }
         }
     }
     else if (qEmb) {
-        // ─── HNSW vector search path (legacy, hybrid flag OFF — or a caller
-        // like MemoryBootstrap forcing HNSW-leg-only regardless of the flag) ────
+        // ─── HNSW vector search path (legacy, hybrid flag OFF — the
+        // FLAIR_HYBRID_RETRIEVAL kill-switch path for BOTH production callers
+        // since flair#1246) ─────────────────────────────────────────────────────
         const query = {
             sort: { attribute: "embedding", target: qEmb, distance: "cosine" },
             select: hnswSelect,
@@ -269,6 +335,7 @@ export async function retrieveCandidates(params) {
                 _score: Math.round(finalScore * 1000) / 1000,
                 _rawScore: scoring !== "raw" ? Math.round(rawScore * 1000) / 1000 : undefined,
                 _source: source,
+                _rank: finalScore,
                 ...(withSemSimilarity ? { _semSimilarity: semanticScore } : {}),
             });
         }
@@ -314,6 +381,7 @@ export async function retrieveCandidates(params) {
                 _score: Math.round(finalScore * 1000) / 1000,
                 _rawScore: scoring !== "raw" ? Math.round(rawScore * 1000) / 1000 : undefined,
                 _source: source,
+                _rank: finalScore,
             });
         }
     }
@@ -331,10 +399,22 @@ export async function retrieveCandidates(params) {
         }
         filteredResults = results.filter((r) => !supersededIds.has(r.id));
     }
-    // Apply minimum score filter
+    // Apply minimum score filter — against `_score`, which is ALWAYS on the
+    // absolute-similarity scale after flair#985 (the hybrid path used to report
+    // the rank-normalized RRF value here, so `minScore: 0.95` matched the
+    // always-1.0 top-1 of ANY query instead of meaning "similarity ≥ 0.95").
     if (minScore > 0) {
         filteredResults = filteredResults.filter((r) => r._score >= minScore);
     }
-    filteredResults.sort((a, b) => b._score - a._score);
+    // Order by the internal ranking key (fused RRF rank on the hybrid raw path;
+    // identical to `_score` everywhere else), then strip it — `_rank` is an
+    // ordering key, never part of the response shape. Note the hybrid raw
+    // ordering is deliberately NOT by `_score`: the recall win of hybrid
+    // retrieval lives in the fused ORDER (a BM25 rank-1 rescue outranks weak
+    // semantic hits), while `_score` carries the honest absolute evidence for
+    // each result — the two can disagree, and that is correct.
+    filteredResults.sort((a, b) => b._rank - a._rank);
+    for (const r of filteredResults)
+        delete r._rank;
     return filteredResults;
 }

package/dist/src/lib/scheduler-platform.js

@@ -13,9 +13,15 @@
  *
  * `interpretActiveResult()` in particular encodes a production lesson
  * (flair#850) that took a real outage to learn. It must not be re-derived.
+ * flair#1231 extended it one layer deeper: a load command exiting 0 proves the
+ * service manager ACCEPTED the job, not that the job can RUN — two fleet
+ * incidents (a stripped exec bit, a missing log directory) both passed the
+ * load check and died on the first real run, invisibly. The rule now encoded
+ * in `verifyFirstRun()`: success may not be claimed until the thing the
+ * operator asked for has been observed to happen once.
  */
 import { existsSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
-import { resolve, dirname } from "node:path";
+import { resolve, dirname, isAbsolute } from "node:path";
 import { platform } from "node:os";
 import { spawnSync } from "node:child_process";
 /**
@@ -126,3 +132,206 @@ export function writeFileWithDir(path, contents, mode = 0o600) {
         mkdirSync(dir, { recursive: true, mode: 0o700 });
     writeFileSync(path, contents, { mode });
 }
+// ─── node binary resolution (flair#1231) ────────────────────────────────────
+/**
+ * Resolves the ABSOLUTE path to the node binary at enable time, so the shim
+ * can `exec "<node>" "<script>"` with ZERO PATH lookups at run time.
+ *
+ * Why this exists: the shims switched from `exec "{{FLAIR_BIN}}"` (which
+ * required an exec bit that tarball extraction strips — the #1231 regression)
+ * to running the CLI under node, which needs read permission only. But a bare
+ * `exec node …` would introduce a run-time PATH lookup the old absolute-path
+ * form never had: whatever PATH the service manager's environment carries
+ * would pick the `node` that runs with the operator's credentials. So the
+ * node path is resolved HERE, once, from the enabling process's own
+ * environment, and baked into the shim — symmetric with how FLAIR_BIN is
+ * already handled.
+ *
+ * Resolution order:
+ *   1. `explicit` — caller/test override.
+ *   2. `process.execPath` when the enabling runtime IS node (the published
+ *      CLI's case): absolute, known-good, already trusted to run this code.
+ *   3. `command -v node` in the enabling shell environment (dev/test under
+ *      bun): the one deliberate PATH consultation, made at enable time by the
+ *      operator's own session, never later by the service manager.
+ * Nothing resolvable ⇒ throw — enable must fail loudly rather than bake a
+ * run-time lookup into the shim.
+ */
+export function resolveNodeBin(explicit) {
+    if (explicit)
+        return explicit;
+    if (!process.versions.bun && process.execPath && isAbsolute(process.execPath)) {
+        return process.execPath;
+    }
+    const r = spawnReport(["/bin/sh", "-c", "command -v node"], STATUS_CHECK_TIMEOUT_MS);
+    const found = r.stdout.trim().split("\n")[0]?.trim() ?? "";
+    if (r.code === 0 && found && isAbsolute(found) && existsSync(found))
+        return found;
+    throw new Error("unable to resolve an absolute path to a node binary (not running under node, and `command -v node` " +
+        "found nothing). The scheduler shim runs `<node> <flair-script>` with the node path baked in at " +
+        "enable time — refusing to install a shim that would resolve `node` from the service manager's PATH " +
+        "at run time. Install node (or put it on PATH for this shell) and re-run enable.");
+}
+// ─── first-run verification (flair#1231) ────────────────────────────────────
+// A load/bootstrap command exiting 0 proves the service manager accepted the
+// job — not that the job can run. The only vantage that exercises the real
+// failure modes (launchd spawn error 209 from a missing log dir, exit 126
+// from a stripped exec bit) is the service manager itself, so the first run
+// is triggered and observed THROUGH it, never via a bare spawn of the shim.
+/** Poll cadence for darwin `launchctl print` first-run polling. */
+export const FIRST_RUN_POLL_INTERVAL_MS = 150;
+/** Total budget for first-run verification on both platforms. */
+export const FIRST_RUN_BUDGET_MS = 12_000;
+/** Synchronous sleep without spawning anything. */
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/**
+ * Parses `launchctl print <domain>/<label>` for run state. `last exit code`
+ * is absent (or "(never exited)") until a run has completed, and `pid =` /
+ * `state = running` are present only while one is in flight.
+ */
+export function parseLaunchdPrintExit(output) {
+    const running = /^\s*state\s*=\s*(?:running|spawn)/m.test(output) || /^\s*pid\s*=\s*\d+/m.test(output);
+    const m = /last exit (?:code|status)\s*=\s*(-?\d+)/.exec(output);
+    return { running, lastExitCode: m ? Number(m[1]) : null };
+}
+/** Parses `systemctl --user show <unit> --property=ExecMainStatus,Result`. */
+export function parseSystemdShowExit(output) {
+    const m = /^ExecMainStatus=(-?\d+)\s*$/m.exec(output);
+    const r = /^Result=(\S+)\s*$/m.exec(output);
+    return { execMainStatus: m ? Number(m[1]) : null, result: r ? r[1] : null };
+}
+/** Reads the last lines of a log file for failure diagnostics. Never throws. */
+export function readLogTail(path, maxLines = 12, maxChars = 1500) {
+    let text;
+    try {
+        text = readFileSync(path, "utf-8");
+    }
+    catch {
+        return { exists: false, empty: false, tail: "" };
+    }
+    const trimmed = text.trimEnd();
+    if (!trimmed)
+        return { exists: true, empty: true, tail: "" };
+    let tail = trimmed.split("\n").slice(-maxLines).join("\n");
+    if (tail.length > maxChars)
+        tail = tail.slice(-maxChars);
+    return { exists: true, empty: false, tail };
+}
+/**
+ * Names the failure class for a recorded exit status, so the report can lead
+ * with actor+state instead of a bare number.
+ */
+export function describeExitCode(code) {
+    if (code === null)
+        return "no exit status recorded";
+    if (code === 126)
+        return "exit 126 — found but not runnable (permission denied / exec format)";
+    if (code === 127)
+        return "exit 127 — command not found";
+    if (code === 209)
+        return "exit 209 — launchd could not spawn the job (a missing/unwritable log directory produces this)";
+    return `exit ${code}`;
+}
+function spawnedNothing(r) {
+    return r.code === null && !r.stdout.trim() && !r.stderr.trim();
+}
+/**
+ * Triggers the job's first run through the service manager and reads back how
+ * it ended (flair#1231). Call ONLY after the load/bootstrap command exited 0 —
+ * a load failure is its own failure mode with its own remedy, and layering a
+ * kickstart on top of it would blur which actor failed.
+ *
+ * darwin: `launchctl kickstart -k` returns immediately (it does NOT block for
+ * exit), so the recorded exit status is POLLED out of `launchctl print` until
+ * a completed run is visible or the budget lapses. linux: `systemctl --user
+ * start` on a oneshot blocks until the run exits, so a single
+ * `systemctl --user show` read afterwards suffices.
+ *
+ * "Can't tell" is its own state: a missing/unreachable service manager yields
+ * outcome "manager-unavailable", distinct from "run-failed" — the remedy
+ * points at the service manager, not at the job.
+ */
+export function verifyFirstRun(opts) {
+    const run = opts.hooks?.run ?? ((cmd, timeoutMs) => spawnReport(cmd, timeoutMs));
+    const sleep = opts.hooks?.sleep ?? sleepSync;
+    const now = opts.hooks?.now ?? Date.now;
+    const pollIntervalMs = opts.pollIntervalMs ?? FIRST_RUN_POLL_INTERVAL_MS;
+    const budgetMs = opts.budgetMs ?? FIRST_RUN_BUDGET_MS;
+    const finish = (outcome, exitCode, detail) => {
+        const log = outcome === "success"
+            ? { exists: false, empty: false, tail: "" } // no diagnostics needed on success
+            : readLogTail(opts.stderrLogPath);
+        return {
+            verified: outcome === "success",
+            outcome,
+            exitCode,
+            detail,
+            logPath: opts.stderrLogPath,
+            stderrTail: log.tail,
+            logEmpty: log.exists && log.empty,
+            budgetMs,
+        };
+    };
+    if (opts.plat === "darwin") {
+        const target = opts.darwinTarget;
+        if (!target)
+            throw new Error("verifyFirstRun: darwinTarget is required on darwin");
+        const kickCmd = ["launchctl", "kickstart", "-k", target];
+        const kick = run(kickCmd, SPAWN_TIMEOUT_MS);
+        if (spawnedNothing(kick)) {
+            return finish("manager-unavailable", null, `launchctl could not be run (${kickCmd.join(" ")})`);
+        }
+        if (kick.code !== 0) {
+            return finish("start-failed", null, `${kickCmd.join(" ")} → code ${kick.code}${kick.stderr.trim() ? `: ${kick.stderr.trim()}` : ""}`);
+        }
+        const deadline = now() + budgetMs;
+        // Poll: kickstart returned immediately, so watch `launchctl print` until a
+        // COMPLETED run (not running + a recorded exit code) is visible.
+        for (;;) {
+            const printCmd = ["launchctl", "print", target];
+            const r = run(printCmd, STATUS_CHECK_TIMEOUT_MS);
+            if (spawnedNothing(r)) {
+                return finish("manager-unavailable", null, `launchctl could not be run (${printCmd.join(" ")})`);
+            }
+            if (r.code === 0) {
+                const { running, lastExitCode } = parseLaunchdPrintExit(r.stdout);
+                if (!running && lastExitCode !== null) {
+                    return lastExitCode === 0
+                        ? finish("success", 0, `${printCmd.join(" ")} → last exit code = 0`)
+                        : finish("run-failed", lastExitCode, `${printCmd.join(" ")} → last exit code = ${lastExitCode}`);
+                }
+            }
+            if (now() >= deadline) {
+                return finish("timeout", null, `no completed run visible in ${printCmd.join(" ")} within ${Math.round(budgetMs / 1000)}s`);
+            }
+            sleep(pollIntervalMs);
+        }
+    }
+    // linux
+    const unit = opts.linuxServiceUnit;
+    if (!unit)
+        throw new Error("verifyFirstRun: linuxServiceUnit is required on linux");
+    const startCmd = ["systemctl", "--user", "start", unit];
+    const start = run(startCmd, budgetMs);
+    if (spawnedNothing(start)) {
+        return finish("manager-unavailable", null, `systemctl could not be run (${startCmd.join(" ")})`);
+    }
+    if (/failed to connect to bus/i.test(start.stderr)) {
+        return finish("manager-unavailable", null, `${startCmd.join(" ")} → ${start.stderr.trim()}`);
+    }
+    if (start.code === null) {
+        return finish("timeout", null, `${startCmd.join(" ")} did not return within ${Math.round(budgetMs / 1000)}s`);
+    }
+    const showCmd = ["systemctl", "--user", "show", unit, "--property=ExecMainStatus,Result"];
+    const show = run(showCmd, STATUS_CHECK_TIMEOUT_MS);
+    const parsed = parseSystemdShowExit(show.stdout);
+    if (start.code === 0) {
+        // A blocking start of a oneshot exits 0 only when the run succeeded; the
+        // show read supplies the recorded status for the report.
+        return finish("success", parsed.execMainStatus ?? 0, `${startCmd.join(" ")} → ok`);
+    }
+    const resultTxt = parsed.result ? `, Result=${parsed.result}` : "";
+    return finish("run-failed", parsed.execMainStatus, `${startCmd.join(" ")} → code ${start.code}${resultTxt}${start.stderr.trim() ? `: ${start.stderr.trim()}` : ""}`);
+}