@openparachute/vault 0.4.7-rc.1 → 0.4.8-rc.4

package/src/scribe-env.ts

@@ -3,9 +3,12 @@
  *
  * Lives in its own module so the boot-time token resolution in server.ts is
  * testable without running the rest of server.ts (which has side effects:
- * triggers, auto-init, Bun.serve). Keep this module pure and dependency-free.
+ * triggers, auto-init, Bun.serve). Keep this module pure and dependency-free
+ * (except for the `node:crypto` import used by bearer generation).
  */
 
+import { randomBytes } from "node:crypto";
+
 /**
  * Resolve the scribe auth token. `SCRIBE_AUTH_TOKEN` is the canonical name
  * (matches the CLI's install-time auto-wire); `SCRIBE_TOKEN` is a legacy alias
@@ -31,3 +34,41 @@ export function resolveScribeAuthToken(
   }
   return undefined;
 }
+
+/**
+ * Generate a fresh shared bearer for the vault↔scribe loopback contract
+ * (design 2026-05-21 Part 2, design question 2). 32 random bytes → base64url
+ * encoded. The operator (or hub install) writes the result into vault's
+ * `~/.parachute/vault/.env` as `SCRIBE_AUTH_TOKEN` AND into scribe's config
+ * (via env propagation or the scribe admin endpoint).
+ *
+ * Generation is callable as a pure function so install code, tests, and any
+ * future "rotate scribe bearer" admin endpoint share the same length +
+ * encoding without copy-paste.
+ */
+export function generateScribeBearer(): string {
+  return randomBytes(32).toString("base64url");
+}
+
+/**
+ * Ensure a scribe bearer exists in the vault .env. Idempotent: if a value
+ * (canonical or legacy) is already set, returns `{ created: false, token: ... }`
+ * without touching the file. Otherwise generates a fresh bearer, persists it
+ * to the .env via the provided writer, and returns `{ created: true, token }`.
+ *
+ * The `envReader` + `envWriter` parameters are injection seams for tests; the
+ * production caller (`cli.ts` init flow) passes `readEnvFile` + `setEnvVar`.
+ */
+export function ensureScribeBearer(
+  envReader: () => Record<string, string>,
+  envWriter: (key: string, value: string) => void,
+): { created: boolean; token: string } {
+  const env = envReader();
+  const existing = env.SCRIBE_AUTH_TOKEN ?? env.SCRIBE_TOKEN;
+  if (existing && existing.trim()) {
+    return { created: false, token: existing };
+  }
+  const token = generateScribeBearer();
+  envWriter("SCRIBE_AUTH_TOKEN", token);
+  return { created: true, token };
+}

package/src/self-register.test.ts

@@ -0,0 +1,380 @@
+import { describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { buildVaultServicePaths, selfRegister } from "./self-register.ts";
+import type { VaultModuleManifest } from "./module-manifest.ts";
+
+/**
+ * Spin up a fresh PARACHUTE_HOME tmpdir + restore the prior env on teardown.
+ * The self-register pass writes through to `~/.parachute/services.json` via
+ * the per-call path resolution in services-manifest.ts (which honors
+ * PARACHUTE_HOME), so this is the canonical isolation seam.
+ */
+function withParachuteHome(fn: (home: string) => void): void {
+  const home = mkdtempSync(join(tmpdir(), "pvault-self-register-"));
+  const prior = process.env.PARACHUTE_HOME;
+  process.env.PARACHUTE_HOME = home;
+  // Also override HOME so readGlobalConfig + listVaults don't fall through
+  // to the operator's real ~/.parachute.
+  const priorHome = process.env.HOME;
+  process.env.HOME = home;
+  try {
+    // Seed the config dir with an empty config.yaml so readGlobalConfig
+    // returns a clean state.
+    mkdirSync(join(home, "vault"), { recursive: true });
+    writeFileSync(join(home, "vault", "config.yaml"), "port: 1940\n");
+    fn(home);
+  } finally {
+    if (prior === undefined) delete process.env.PARACHUTE_HOME;
+    else process.env.PARACHUTE_HOME = prior;
+    if (priorHome === undefined) delete process.env.HOME;
+    else process.env.HOME = priorHome;
+    rmSync(home, { recursive: true, force: true });
+  }
+}
+
+const TEST_MANIFEST: VaultModuleManifest = {
+  name: "vault",
+  manifestName: "parachute-vault",
+  displayName: "Vault",
+  tagline: "Test tagline",
+  kind: "api",
+  port: 1940,
+  paths: ["/vault/default"],
+  health: "/vault/default/health",
+};
+
+function captureLogs(): {
+  log: (m: string) => void;
+  warn: (m: string) => void;
+  logs: string[];
+  warnings: string[];
+} {
+  const logs: string[] = [];
+  const warnings: string[] = [];
+  return {
+    log: (m: string) => logs.push(m),
+    warn: (m: string) => warnings.push(m),
+    logs,
+    warnings,
+  };
+}
+
+describe("self-register", () => {
+  test("buildVaultServicePaths — no vaults yet → manifest fallback", () => {
+    expect(buildVaultServicePaths(undefined, [], ["/vault/default"])).toEqual([
+      "/vault/default",
+    ]);
+  });
+
+  test("buildVaultServicePaths — default vault sorts first", () => {
+    expect(
+      buildVaultServicePaths("default", ["alpha", "default", "beta"], ["/"]),
+    ).toEqual(["/vault/default", "/vault/alpha", "/vault/beta"]);
+  });
+
+  test("buildVaultServicePaths — no default → map by listed order", () => {
+    expect(buildVaultServicePaths(undefined, ["alpha", "beta"], ["/"])).toEqual([
+      "/vault/alpha",
+      "/vault/beta",
+    ]);
+  });
+
+  test("buildVaultServicePaths — default points to missing vault → ignore default", () => {
+    expect(
+      buildVaultServicePaths("missing", ["alpha", "beta"], ["/"]),
+    ).toEqual(["/vault/alpha", "/vault/beta"]);
+  });
+
+  test("writes services.json with manifest-sourced fields + installDir", () => {
+    withParachuteHome((home) => {
+      const { log, warn, logs, warnings } = captureLogs();
+      const result = selfRegister({
+        version: "0.4.8-rc.3",
+        log,
+        warn,
+        readManifest: () => TEST_MANIFEST,
+        resolvePackageRoot: () => "/fake/install/dir",
+        listVaults: () => [],
+        readGlobalConfig: () => ({ port: 1940 }),
+      });
+      expect(result.status).toBe("registered");
+      expect(warnings).toEqual([]);
+      expect(logs[0]).toContain("registered parachute-vault");
+
+      const raw = readFileSync(join(home, "services.json"), "utf8");
+      const parsed = JSON.parse(raw) as { services: unknown[] };
+      expect(parsed.services).toHaveLength(1);
+      const row = parsed.services[0] as Record<string, unknown>;
+      expect(row.name).toBe("parachute-vault");
+      expect(row.port).toBe(1940);
+      expect(row.paths).toEqual(["/vault/default"]);
+      expect(row.health).toBe("/vault/default/health");
+      expect(row.version).toBe("0.4.8-rc.3");
+      expect(row.installDir).toBe("/fake/install/dir");
+      expect(row.displayName).toBe("Vault");
+      expect(row.tagline).toBe("Test tagline");
+    });
+  });
+
+  test("idempotent — re-running reports no changes", () => {
+    withParachuteHome(() => {
+      const { log, warn } = captureLogs();
+      const deps = {
+        version: "0.4.8-rc.3",
+        log,
+        warn,
+        readManifest: () => TEST_MANIFEST,
+        resolvePackageRoot: () => "/fake/install/dir",
+        listVaults: () => [],
+        readGlobalConfig: () => ({ port: 1940 }),
+      };
+      const first = selfRegister(deps);
+      expect(first.status).toBe("registered");
+      if (first.status === "registered") expect(first.changed).toBe(true);
+
+      const second = selfRegister(deps);
+      expect(second.status).toBe("registered");
+      if (second.status === "registered") expect(second.changed).toBe(false);
+    });
+  });
+
+  test("preserves hub-stamped fields on the row", () => {
+    withParachuteHome((home) => {
+      // Pre-existing row carries a hub-stamped field we don't write.
+      const servicesPath = join(home, "services.json");
+      writeFileSync(
+        servicesPath,
+        `${JSON.stringify(
+          {
+            services: [
+              {
+                name: "parachute-vault",
+                port: 1940,
+                paths: ["/vault/default"],
+                health: "/vault/default/health",
+                version: "0.4.7",
+                // Pretend hub stamped some custom field — should survive.
+                hubCustomField: "preserved",
+                installDir: "/some/prior/path",
+              },
+            ],
+          },
+          null,
+          2,
+        )}\n`,
+      );
+
+      const { log, warn } = captureLogs();
+      const result = selfRegister({
+        version: "0.4.8-rc.3",
+        log,
+        warn,
+        readManifest: () => TEST_MANIFEST,
+        resolvePackageRoot: () => "/new/install/dir",
+        listVaults: () => [],
+        readGlobalConfig: () => ({ port: 1940 }),
+      });
+      expect(result.status).toBe("registered");
+
+      const raw = readFileSync(servicesPath, "utf8");
+      const parsed = JSON.parse(raw) as { services: Record<string, unknown>[] };
+      const row = parsed.services[0]!;
+      // Vault-owned fields win.
+      expect(row.version).toBe("0.4.8-rc.3");
+      expect(row.installDir).toBe("/new/install/dir");
+      // Hub-stamped foreign field survives.
+      expect(row.hubCustomField).toBe("preserved");
+    });
+  });
+
+  test("preserves entries written by other modules", () => {
+    withParachuteHome((home) => {
+      const servicesPath = join(home, "services.json");
+      writeFileSync(
+        servicesPath,
+        `${JSON.stringify(
+          {
+            services: [
+              {
+                name: "parachute-scribe",
+                port: 1943,
+                paths: ["/scribe"],
+                health: "/scribe/health",
+                version: "0.3.0",
+              },
+            ],
+          },
+          null,
+          2,
+        )}\n`,
+      );
+
+      const { log, warn } = captureLogs();
+      selfRegister({
+        version: "0.4.8-rc.3",
+        log,
+        warn,
+        readManifest: () => TEST_MANIFEST,
+        resolvePackageRoot: () => "/fake/install/dir",
+        listVaults: () => [],
+        readGlobalConfig: () => ({ port: 1940 }),
+      });
+
+      const raw = readFileSync(servicesPath, "utf8");
+      const parsed = JSON.parse(raw) as { services: { name: string }[] };
+      expect(parsed.services).toHaveLength(2);
+      expect(parsed.services.find((s) => s.name === "parachute-scribe")).toBeDefined();
+      expect(parsed.services.find((s) => s.name === "parachute-vault")).toBeDefined();
+    });
+  });
+
+  test("skipped when manifest absent — never throws", () => {
+    withParachuteHome(() => {
+      const { log, warn, warnings } = captureLogs();
+      const result = selfRegister({
+        version: "0.4.8-rc.3",
+        log,
+        warn,
+        readManifest: () => null,
+        resolvePackageRoot: () => "/fake/install/dir",
+        listVaults: () => [],
+        readGlobalConfig: () => ({ port: 1940 }),
+      });
+      expect(result.status).toBe("skipped");
+      if (result.status === "skipped") expect(result.reason).toMatch(/manifest absent/);
+      expect(warnings).toEqual([]); // skipped is informational, not a warning
+    });
+  });
+
+  test("failed when manifest read throws — does not propagate", () => {
+    withParachuteHome(() => {
+      const { log, warn, warnings } = captureLogs();
+      const result = selfRegister({
+        version: "0.4.8-rc.3",
+        log,
+        warn,
+        readManifest: () => {
+          throw new Error("corrupt JSON");
+        },
+        resolvePackageRoot: () => "/fake/install/dir",
+        listVaults: () => [],
+        readGlobalConfig: () => ({ port: 1940 }),
+      });
+      expect(result.status).toBe("failed");
+      if (result.status === "failed") expect(result.reason).toContain("corrupt JSON");
+      expect(warnings.some((w) => w.includes("could not read"))).toBe(true);
+    });
+  });
+
+  test("failed when upsert throws — does not propagate", () => {
+    withParachuteHome(() => {
+      const { log, warn, warnings } = captureLogs();
+      const result = selfRegister({
+        version: "0.4.8-rc.3",
+        log,
+        warn,
+        readManifest: () => TEST_MANIFEST,
+        resolvePackageRoot: () => "/fake/install/dir",
+        listVaults: () => [],
+        readGlobalConfig: () => ({ port: 1940 }),
+        upsertService: () => {
+          throw new Error("disk full");
+        },
+      });
+      expect(result.status).toBe("failed");
+      if (result.status === "failed") expect(result.reason).toContain("disk full");
+      expect(warnings.some((w) => w.includes("services.json write failed"))).toBe(true);
+    });
+  });
+
+  test("multi-vault: default vault sorts first in paths", () => {
+    withParachuteHome((home) => {
+      const { log, warn } = captureLogs();
+      selfRegister({
+        version: "0.4.8-rc.3",
+        log,
+        warn,
+        readManifest: () => TEST_MANIFEST,
+        resolvePackageRoot: () => "/fake/install/dir",
+        listVaults: () => ["alpha", "default", "beta"],
+        readGlobalConfig: () => ({ port: 1940, default_vault: "default" }),
+      });
+
+      const raw = readFileSync(join(home, "services.json"), "utf8");
+      const parsed = JSON.parse(raw) as { services: Record<string, unknown>[] };
+      expect(parsed.services[0]!.paths).toEqual([
+        "/vault/default",
+        "/vault/alpha",
+        "/vault/beta",
+      ]);
+    });
+  });
+
+  test("uses globalConfig.port over DEFAULT_PORT when set", () => {
+    withParachuteHome((home) => {
+      const { log, warn } = captureLogs();
+      selfRegister({
+        version: "0.4.8-rc.3",
+        log,
+        warn,
+        readManifest: () => TEST_MANIFEST,
+        resolvePackageRoot: () => "/fake/install/dir",
+        listVaults: () => [],
+        readGlobalConfig: () => ({ port: 19999 }),
+      });
+
+      const raw = readFileSync(join(home, "services.json"), "utf8");
+      const parsed = JSON.parse(raw) as { services: Record<string, unknown>[] };
+      expect(parsed.services[0]!.port).toBe(19999);
+    });
+  });
+
+  test("stripPrefix flows from manifest to row when set", () => {
+    withParachuteHome((home) => {
+      const { log, warn } = captureLogs();
+      selfRegister({
+        version: "0.4.8-rc.3",
+        log,
+        warn,
+        readManifest: () => ({ ...TEST_MANIFEST, stripPrefix: true }),
+        resolvePackageRoot: () => "/fake/install/dir",
+        listVaults: () => [],
+        readGlobalConfig: () => ({ port: 1940 }),
+      });
+
+      const raw = readFileSync(join(home, "services.json"), "utf8");
+      const parsed = JSON.parse(raw) as { services: Record<string, unknown>[] };
+      expect(parsed.services[0]!.stripPrefix).toBe(true);
+    });
+  });
+
+  test("changed=true when installDir differs from prior row", () => {
+    withParachuteHome(() => {
+      const { log, warn } = captureLogs();
+      const baseDeps = {
+        version: "0.4.8-rc.3",
+        log,
+        warn,
+        readManifest: () => TEST_MANIFEST,
+        listVaults: () => [],
+        readGlobalConfig: () => ({ port: 1940 }),
+      };
+      const first = selfRegister({
+        ...baseDeps,
+        resolvePackageRoot: () => "/old/install/dir",
+      });
+      expect(first.status).toBe("registered");
+      if (first.status === "registered") expect(first.changed).toBe(true);
+
+      // Second call with a different installDir — should re-stamp.
+      const second = selfRegister({
+        ...baseDeps,
+        resolvePackageRoot: () => "/new/install/dir",
+      });
+      expect(second.status).toBe("registered");
+      if (second.status === "registered") expect(second.changed).toBe(true);
+    });
+  });
+});

package/src/self-register.ts

@@ -0,0 +1,234 @@
+/**
+ * Boot-time self-registration of vault's manifest + `installDir` into
+ * `~/.parachute/services.json` — the POC for retiring hub's
+ * `FIRST_PARTY_FALLBACKS[vault]` (vault#266).
+ *
+ * Background: hub today vendors a `VAULT_FALLBACK` manifest in
+ * `parachute-hub/src/service-spec.ts` and stamps `installDir` onto the
+ * services.json row via `stampInstallDirOnRow` during `parachute install
+ * vault` / API install. That fallback exists because (a) bun-link dev
+ * mode never runs the hub install path so installDir isn't stamped,
+ * and (b) v0.5 vault didn't ship its own `.parachute/module.json` so
+ * hub had no manifest to read at lifecycle time.
+ *
+ * The endgame: every first-party module self-registers its manifest +
+ * installDir on startup so hub's vendored fallbacks retire one by one.
+ * This module is vault's piece of that pattern. Once vault/notes/scribe/
+ * runner all self-register reliably, a hub follow-up deletes
+ * `FIRST_PARTY_FALLBACKS` (see `parachute-hub` for the cleanup PR).
+ *
+ * Design choice — filesystem-direct rather than HTTP:
+ *
+ *   In v0.6 (single-container, hub-as-supervisor — see workspace
+ *   CLAUDE.md), hub and vault share the same filesystem. Writing directly
+ *   to services.json with the existing merge-preserving `upsertService`
+ *   is the simplest shape that works today. The hub-stamped fields the
+ *   row already carries (`installDir`, anything else hub adds in the
+ *   future) ride through because `upsertService` merges rather than
+ *   replaces (see `services-manifest.ts`).
+ *
+ *   v0.7 (multi-container cloud) will need an HTTP `POST
+ *   /api/modules/self-register` on hub so a module on a different
+ *   container can register without filesystem access to the operator's
+ *   `~/.parachute/`. Filed as a separate hub follow-up; this module's
+ *   shape is forward-compatible — `selfRegister` is the single seam that
+ *   would swap from filesystem to HTTP transport.
+ *
+ * Failure mode: every error path logs + returns (never throws). A bad
+ * registration must not crash server boot — the running vault is more
+ * valuable than the discoverability bookkeeping. Symptom of failure is
+ * "vault doesn't appear on hub discovery / admin SPA"; the fix is to
+ * restart vault or run `parachute install vault` to stamp the row via
+ * the hub-side path.
+ */
+
+import { readSelfManifest, resolvePackageRoot, type VaultModuleManifest } from "./module-manifest.ts";
+import {
+  ServicesManifestError,
+  type ServiceEntry,
+  readManifest,
+  upsertService,
+} from "./services-manifest.ts";
+import { listVaults, readGlobalConfig, DEFAULT_PORT } from "./config.ts";
+
+/**
+ * Compute the `paths` array for the parachute-vault services.json entry.
+ *
+ * Mirrors `buildVaultServicePaths` in `cli.ts` so the self-register pass
+ * produces the same multi-vault path advertisement as `parachute-vault
+ * init` / `vault create`. With no vaults yet, falls back to the manifest's
+ * canonical `paths[0]` so early-boot registration is still well-formed.
+ *
+ * Exported for tests; not part of the public module surface.
+ */
+export function buildVaultServicePaths(
+  defaultVault: string | undefined,
+  vaults: readonly string[],
+  fallbackFromManifest: readonly string[],
+): string[] {
+  if (vaults.length === 0) return [...fallbackFromManifest];
+  if (defaultVault && vaults.includes(defaultVault)) {
+    return [
+      `/vault/${defaultVault}`,
+      ...vaults.filter((v) => v !== defaultVault).map((v) => `/vault/${v}`),
+    ];
+  }
+  return vaults.map((v) => `/vault/${v}`);
+}
+
+export interface SelfRegisterDeps {
+  /** Override the manifest reader (tests inject a stub manifest). */
+  readManifest?: () => VaultModuleManifest | null;
+  /** Override the package-root resolver (tests inject a tmp dir). */
+  resolvePackageRoot?: () => string;
+  /** Override the services.json reader (tests inject a tmp-file reader). */
+  readServicesManifest?: typeof readManifest;
+  /** Override the services.json upsert (tests inject a tmp-file writer). */
+  upsertService?: typeof upsertService;
+  /** Override the vault lister (tests pass a fixed list). */
+  listVaults?: typeof listVaults;
+  /** Override the global config reader (tests pass a synthetic config). */
+  readGlobalConfig?: typeof readGlobalConfig;
+  /** Sink for status + warning lines. Production passes a console wrapper. */
+  log?: (msg: string) => void;
+  warn?: (msg: string) => void;
+  /** Vault's runtime version (from `package.json`). Required — no default. */
+  version: string;
+}
+
+/** Result of a `selfRegister` call, surfaced to callers for observability. */
+export type SelfRegisterResult =
+  | { status: "registered"; installDir: string; changed: boolean }
+  | { status: "skipped"; reason: string }
+  | { status: "failed"; reason: string };
+
+/**
+ * Self-register vault's manifest + installDir into `~/.parachute/services.json`.
+ *
+ * Idempotent: re-runs with the same manifest + installDir produce the same
+ * row (the `changed` field on the result telegraphs whether the write
+ * actually mutated the file).
+ *
+ * Never throws. Errors (missing manifest, services.json unreadable,
+ * filesystem write failure) are logged via `warn` and surfaced as a
+ * `failed` / `skipped` result. The caller (server boot) treats failure
+ * as non-fatal — vault keeps serving without the row stamp.
+ */
+export function selfRegister(deps: SelfRegisterDeps): SelfRegisterResult {
+  const log = deps.log ?? ((m) => console.log(m));
+  const warn = deps.warn ?? ((m) => console.warn(m));
+  const readManifestImpl = deps.readManifest ?? readSelfManifest;
+  const resolveRootImpl = deps.resolvePackageRoot ?? resolvePackageRoot;
+  const upsertImpl = deps.upsertService ?? upsertService;
+  const listVaultsImpl = deps.listVaults ?? listVaults;
+  const readGlobalConfigImpl = deps.readGlobalConfig ?? readGlobalConfig;
+
+  let manifest: VaultModuleManifest | null;
+  try {
+    manifest = readManifestImpl();
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    warn(`[self-register] could not read .parachute/module.json: ${msg}`);
+    return { status: "failed", reason: msg };
+  }
+  if (!manifest) {
+    log("[self-register] no .parachute/module.json found — skipping (legacy install or dev tree)");
+    return { status: "skipped", reason: "manifest absent" };
+  }
+
+  // `installDir` is the directory containing both `package.json` and
+  // `.parachute/module.json`. Hub's resolver (`<installDir>/.parachute/module.json`)
+  // expects exactly this shape — see `parachute-hub/src/post-install.ts`'s
+  // `stampInstallDirOnRow`.
+  let installDir: string;
+  try {
+    installDir = resolveRootImpl();
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    warn(`[self-register] could not resolve package root: ${msg}`);
+    return { status: "failed", reason: msg };
+  }
+
+  let globalConfig: ReturnType<typeof readGlobalConfig>;
+  let vaults: string[];
+  try {
+    globalConfig = readGlobalConfigImpl();
+    vaults = listVaultsImpl();
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    warn(`[self-register] could not read vault config: ${msg}`);
+    return { status: "failed", reason: msg };
+  }
+
+  const paths = buildVaultServicePaths(globalConfig.default_vault, vaults, manifest.paths);
+  const port = globalConfig.port ?? DEFAULT_PORT;
+
+  // Build the entry with manifest-sourced metadata (displayName, tagline,
+  // stripPrefix) layered on top of the operationally-determined fields
+  // (port from config, paths from current vault list, version from
+  // package.json). hub-stamped fields on the existing row (installDir
+  // from prior CLI install path, anything future) survive via
+  // `upsertService`'s merge semantics — see services-manifest.ts.
+  const entry: ServiceEntry & {
+    installDir: string;
+    displayName?: string;
+    tagline?: string;
+    stripPrefix?: boolean;
+  } = {
+    name: manifest.manifestName,
+    port,
+    paths,
+    health: manifest.health,
+    version: deps.version,
+    installDir,
+  };
+  if (manifest.displayName !== undefined) entry.displayName = manifest.displayName;
+  if (manifest.tagline !== undefined) entry.tagline = manifest.tagline;
+  if (manifest.stripPrefix !== undefined) entry.stripPrefix = manifest.stripPrefix;
+
+  // Detect whether the existing row already matches (no-op idempotency
+  // signal). We don't gate the write on this — `upsertService` itself is
+  // already idempotent at the byte level — but reporting `changed: false`
+  // lets the boot log say "already registered" instead of restamping noise.
+  let priorRow: (ServiceEntry & { installDir?: string }) | undefined;
+  try {
+    const current = (deps.readServicesManifest ?? readManifest)();
+    priorRow = current.services.find((s) => s.name === manifest.manifestName) as
+      | (ServiceEntry & { installDir?: string })
+      | undefined;
+  } catch (err) {
+    // Read failure here is non-fatal — we'll still attempt the write below.
+    // services.json may not exist yet (fresh boot); upsertService creates it.
+    if (err instanceof ServicesManifestError) {
+      warn(`[self-register] services.json read warning: ${err.message}`);
+    } else {
+      warn(`[self-register] services.json read warning: ${String(err)}`);
+    }
+  }
+
+  const changed =
+    !priorRow ||
+    priorRow.installDir !== installDir ||
+    priorRow.version !== deps.version ||
+    priorRow.port !== port ||
+    JSON.stringify(priorRow.paths) !== JSON.stringify(paths) ||
+    priorRow.health !== manifest.health ||
+    (priorRow as { displayName?: string }).displayName !== manifest.displayName ||
+    (priorRow as { tagline?: string }).tagline !== manifest.tagline ||
+    (priorRow as { stripPrefix?: boolean }).stripPrefix !== manifest.stripPrefix;
+
+  try {
+    upsertImpl(entry);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    warn(`[self-register] services.json write failed: ${msg}`);
+    return { status: "failed", reason: msg };
+  }
+
+  if (changed) {
+    log(`[self-register] registered ${manifest.manifestName} (installDir=${installDir})`);
+  } else {
+    log(`[self-register] already registered ${manifest.manifestName} (no changes)`);
+  }
+  return { status: "registered", installDir, changed };
+}