sealkeep 0.9.0 → 0.11.0

package/dist/src/service.js

@@ -6,8 +6,49 @@ import { dirname, join } from "node:path";
 import { promisify } from "node:util";
 import { fail } from "./errors.js";
 import { envVar } from "./env.js";
+import { INTEGRATION_MANAGER_SOURCE } from "./integration-manager.js";
 const run = promisify(execFile);
-export const SERVICE_LABEL = "ai.vaultline.agent";
+export const SERVICE_LABEL = "ai.sealkeep.agent";
+/**
+ * What this service was called before the rename, and why that is not just
+ * trivia.
+ *
+ * A launchd agent is not owned by the file that wrote it — it is owned by the
+ * OS, under a label, until something tells the OS to let go. Rename the label
+ * and install, and the old agent does not disappear: it keeps loading at every
+ * login, running an executable that may no longer exist, next to the new one.
+ * So every install and every uninstall tears the old label down first.
+ */
+export const LEGACY_SERVICE_LABEL = "ai.vaultline.agent";
+export const LEGACY_SYSTEMD_UNIT = "vaultline.service";
+/**
+ * The user config root a service definition belongs in.
+ *
+ * `XDG_CONFIG_HOME` names the CURRENT user's config root, so it may only
+ * answer for the machine's own home. A caller that names a different home —
+ * a test fixture, tooling that manages another account — must get that home's
+ * `.config`, or every such caller collides on one path: on a CI runner, which
+ * exports XDG_CONFIG_HOME, each install found the previous vault's unit file
+ * already there and refused as "owned by a different Sealkeep vault".
+ */
+function userConfigRoot(home) {
+    const real = homedir();
+    return home === real ? (process.env.XDG_CONFIG_HOME ?? join(home, ".config")) : join(home, ".config");
+}
+/** The commands that retire whatever the previous name left running. */
+function legacyTeardown(kind, home) {
+    if (kind === "launchd") {
+        const path = join(home, "Library", "LaunchAgents", `${LEGACY_SERVICE_LABEL}.plist`);
+        return { commands: [["launchctl", ["unload", "-w", path]]], paths: [path] };
+    }
+    if (kind === "systemd") {
+        const path = join(userConfigRoot(home), "systemd", "user", LEGACY_SYSTEMD_UNIT);
+        return { commands: [["systemctl", ["--user", "disable", "--now", LEGACY_SYSTEMD_UNIT]]], paths: [path] };
+    }
+    if (kind === "schtasks")
+        return { commands: [["schtasks", ["/delete", "/f", "/tn", "Vaultline"]]], paths: [] };
+    return { commands: [], paths: [] };
+}
 function kindFor(target) {
     if (target === "darwin")
         return "launchd";
@@ -32,6 +73,13 @@ export function servicePlan(options) {
     const home = options.home ?? homedir();
     const executable = options.executable ?? process.execPath;
     const args = options.args ?? [];
+    const managerPath = join(options.dataDir, "integrations", "manager.mjs");
+    const receiptPath = join(options.dataDir, "integrations", "ownership.json");
+    // The stable manager is the service target. The original invocation remains
+    // in argv as visible evidence and in the receipt as its machine-readable
+    // form; the manager starts it while installed and self-cleans when absent.
+    const serviceExecutable = process.execPath;
+    const serviceArgs = [managerPath, receiptPath, "--", executable, ...args];
     const logs = join(options.dataDir, "logs");
     const environment = options.environment ?? {};
     const environmentEntries = Object.entries(environment);
@@ -44,7 +92,7 @@ export function servicePlan(options) {
   <key>Label</key><string>${SERVICE_LABEL}</string>
   <key>ProgramArguments</key>
   <array>
-${[executable, ...args].map((value) => `    <string>${escapeXml(value)}</string>`).join("\n")}
+${[serviceExecutable, ...serviceArgs].map((value) => `    <string>${escapeXml(value)}</string>`).join("\n")}
   </array>
 ${environmentEntries.length === 0 ? "" : `  <key>EnvironmentVariables</key>
   <dict>
@@ -53,7 +101,11 @@ ${environmentEntries.map(([key, value]) => `    <key>${escapeXml(key)}</key><str
 `}  <key>RunAtLoad</key><true/>
   <key>KeepAlive</key>
   <dict><key>SuccessfulExit</key><false/></dict>
-  <key>ProcessType</key><string>Background</string>
+  <!-- The service owns the loopback UI as well as archive work. Marking the
+       whole process Background lets macOS starve even /health and Settings
+       while the machine is busy. Keep disk I/O and nice priority deferential,
+       but leave CPU/process QoS at launchd's normal class so user-facing local
+       requests remain schedulable. -->
   <key>LowPriorityIO</key><true/>
   <key>Nice</key><integer>5</integer>
   <key>StandardOutPath</key><string>${escapeXml(join(logs, "daemon.log"))}</string>
@@ -62,21 +114,21 @@ ${environmentEntries.map(([key, value]) => `    <key>${escapeXml(key)}</key><str
 </plist>
 `;
         return {
-            kind, label: SERVICE_LABEL, path, contents,
+            kind, label: SERVICE_LABEL, path, contents, managerPath, receiptPath,
             enable: [["launchctl", ["load", "-w", path]]],
             disable: [["launchctl", ["unload", "-w", path]]]
         };
     }
     if (kind === "systemd") {
-        const path = join(process.env.XDG_CONFIG_HOME ?? join(home, ".config"), "systemd", "user", "vaultline.service");
+        const path = join(userConfigRoot(home), "systemd", "user", "sealkeep.service");
         const contents = `[Unit]
 Description=Sealkeep — seals and archives AI coding-agent sessions
-Documentation=https://github.com/vaultline/vaultline
+Documentation=https://sealkeep.spala.ai
 After=default.target
 
 [Service]
 Type=simple
-ExecStart=${[executable, ...args].map((value) => JSON.stringify(value)).join(" ")}
+ExecStart=${[serviceExecutable, ...serviceArgs].map((value) => JSON.stringify(value)).join(" ")}
 ${environmentEntries.map(([key, value]) => `Environment=${key}=${value}\n`).join("")}Restart=on-failure
 RestartSec=20
 Nice=5
@@ -86,26 +138,556 @@ IOSchedulingClass=idle
 WantedBy=default.target
 `;
         return {
-            kind, label: "vaultline.service", path, contents,
-            enable: [["systemctl", ["--user", "daemon-reload"]], ["systemctl", ["--user", "enable", "--now", "vaultline.service"]]],
-            disable: [["systemctl", ["--user", "disable", "--now", "vaultline.service"]]]
+            kind, label: "sealkeep.service", path, contents, managerPath, receiptPath,
+            enable: [["systemctl", ["--user", "daemon-reload"]], ["systemctl", ["--user", "enable", "--now", "sealkeep.service"]]],
+            disable: [["systemctl", ["--user", "disable", "--now", "sealkeep.service"]]]
         };
     }
     if (kind === "schtasks") {
-        const path = join(options.dataDir, "vaultline-task.xml");
-        const invocation = [executable, ...args].map((value) => `"${value}"`).join(" ");
+        const path = join(options.dataDir, "sealkeep-task.xml");
+        const invocation = [serviceExecutable, ...serviceArgs].map((value) => `"${value}"`).join(" ");
         // schtasks has no environment block, so anything the daemon needs has to be
         // set inside the command it runs.
         const commandLine = environmentEntries.length === 0
             ? invocation
             : `cmd /c "${environmentEntries.map(([key, value]) => `set ${key}=${value}&& `).join("")}${invocation}"`;
         return {
-            kind, label: "Sealkeep", path, contents: commandLine,
+            kind, label: "Sealkeep", path, contents: commandLine, managerPath, receiptPath,
             enable: [["schtasks", ["/create", "/f", "/tn", "Sealkeep", "/sc", "onlogon", "/rl", "limited", "/tr", commandLine]]],
             disable: [["schtasks", ["/delete", "/f", "/tn", "Sealkeep"]]]
         };
     }
-    return { kind, label: "", path: "", contents: "", enable: [], disable: [] };
+    return { kind, label: "", path: "", contents: "", enable: [], disable: [], managerPath, receiptPath };
+}
+/**
+ * Tears down whatever the previous name left behind, and only then.
+ *
+ * The guard matters: without it a first-ever install still issues an unload
+ * for a unit file that never existed, which is a command run for nothing and
+ * a line of noise in every install transcript.
+ */
+async function retireLegacy(kind, home, exec) {
+    const { commands, paths } = legacyTeardown(kind, home);
+    // Unload unconditionally. A loaded job outlives its unit file — delete the
+    // plist by hand and launchd keeps running the agent — so "the file is gone"
+    // is not "there is nothing to retire", and skipping the unload on that basis
+    // is how a machine ends up running BOTH agents, which is what this exists
+    // to prevent.
+    for (const [file, args] of commands) {
+        try {
+            await exec(file, args);
+        }
+        catch { /* was never loaded */ }
+    }
+    // And never let cleanup sink the install. `force: true` swallows a missing
+    // file but not a locked or read-only one, and this runs BEFORE the new unit
+    // is written: an uncaught throw here stopped the old agent and then aborted
+    // before starting the new one, leaving the machine with no agent at all and
+    // no message saying so.
+    for (const stale of paths) {
+        try {
+            await rm(stale, { force: true });
+        }
+        catch { /* a leftover file is not worth failing an install over */ }
+    }
+}
+function launchdTarget(label) {
+    return typeof process.getuid === "function" ? `gui/${process.getuid()}/${label}` : null;
+}
+/** True only for the daemon child of this exact package-independent manager. */
+function runningInsideServicePlan(plan) {
+    return process.env.SEALKEEP_SERVICE_MANAGER_PATH === plan.managerPath
+        && process.env.SEALKEEP_SERVICE_RECEIPT_PATH === plan.receiptPath;
+}
+/**
+ * Ask the service manager, rather than the filesystem, whether this service is
+ * loaded. A plist/unit can survive a failed load (or a later crash), and a
+ * launchd job can remain loaded after somebody deletes its plist by hand.
+ */
+async function registrationIsLive(plan, exec) {
+    if (plan.kind === "launchd") {
+        const target = launchdTarget(plan.label);
+        if (target) {
+            const printed = await exec("launchctl", ["print", target]).then(() => true).catch(() => false);
+            if (printed)
+                return true;
+        }
+        // `list <label>` is the compatibility probe for older launchctl versions
+        // and for environments where a numeric GUI domain is unavailable.
+        return exec("launchctl", ["list", plan.label]).then(() => true).catch(() => false);
+    }
+    if (plan.kind === "systemd") {
+        return exec("systemctl", ["--user", "is-active", "--quiet", plan.label]).then(() => true).catch(() => false);
+    }
+    if (plan.kind === "schtasks") {
+        // There is no durable unit file on Windows; the scheduler is the source of
+        // truth. `/query` also fails when the task registration is unusable.
+        return exec("schtasks", ["/query", "/tn", plan.label]).then(() => true).catch(() => false);
+    }
+    return false;
+}
+function commandOutput(result) {
+    if (typeof result === "string")
+        return result;
+    if (result && typeof result === "object" && "stdout" in result) {
+        const stdout = result.stdout;
+        if (typeof stdout === "string")
+            return stdout;
+        if (stdout instanceof Uint8Array)
+            return Buffer.from(stdout).toString("utf8");
+    }
+    return null;
+}
+function currentUid(options) {
+    const uid = options.uid ?? (typeof process.getuid === "function" ? process.getuid() : undefined);
+    return Number.isInteger(uid) && (uid ?? -1) >= 0 ? uid : null;
+}
+function serviceExec(options) {
+    if (options.exec)
+        return options.exec;
+    const target = options.platform ?? platform();
+    const uid = currentUid(options);
+    return (file, args) => {
+        // A launchd registration from an older release can keep its Background
+        // process policy cached until logout even after its plist is corrected.
+        // Reconciliation is the escape path, so its launchctl probes must not be
+        // starved by the very policy they are repairing. taskpolicy's application
+        // profile applies before launchctl starts, and the timeout keeps a broken
+        // service manager from delaying the local UI indefinitely.
+        if (target === "darwin") {
+            return run("/usr/sbin/taskpolicy", ["-a", file, ...args], {
+                timeout: 5_000,
+                killSignal: "SIGTERM",
+            });
+        }
+        if (target !== "linux")
+            return run(file, args);
+        // Minimal/root SSH sessions do not always export XDG_RUNTIME_DIR even
+        // after logind has created the current user's manager. Point systemctl at
+        // that same current-user runtime directory; never manufacture one or
+        // target a different uid. loginctl calls are bounded so a missing D-Bus or
+        // polkit agent cannot strand the rest of Autopilot setup.
+        const standardRuntime = uid === null ? null : `/run/user/${uid}`;
+        const runtime = standardRuntime && existsSync(standardRuntime) ? standardRuntime : null;
+        // XDG_RUNTIME_DIR selects the user bus. Never inherit a value that may
+        // belong to the invoking shell's/sudo caller's different account: use only
+        // the standard directory for the exact current UID, or omit it entirely.
+        const { XDG_RUNTIME_DIR: _untrustedRuntime, ...baseEnvironment } = process.env;
+        return run(file, args, {
+            env: { ...baseEnvironment, ...(runtime ? { XDG_RUNTIME_DIR: runtime } : {}) },
+            ...(file === "loginctl" ? { timeout: 5_000, killSignal: "SIGTERM" } : {}),
+        });
+    };
+}
+function linuxLingerValue(result) {
+    const value = commandOutput(result)?.trim().toLowerCase();
+    if (value === "yes" || value === "linger=yes")
+        return true;
+    if (value === "no" || value === "linger=no")
+        return false;
+    return null;
+}
+async function linuxLingerEnabled(uid, exec) {
+    const result = await exec("loginctl", ["show-user", String(uid), "--property=Linger", "--value"]).catch(() => null);
+    return linuxLingerValue(result);
+}
+async function readLinuxLingerOwnership(plan, uid) {
+    if (uid === null)
+        return null;
+    const receipt = await readFile(plan.receiptPath, "utf8")
+        .then((raw) => JSON.parse(raw))
+        .catch(() => null);
+    const linger = receipt?.linuxLinger;
+    return linger?.enabledBySealkeep === true
+        && linger.uid === uid
+        && typeof linger.enabledAt === "string"
+        ? linger
+        : null;
+}
+function oneLine(error) {
+    return error instanceof Error ? error.message.split("\n")[0] : "not permitted";
+}
+/**
+ * A systemd user unit normally follows login sessions. Linger makes the
+ * current user's manager start at boot and survive the last SSH logout. It is
+ * a user-wide switch, so Sealkeep records and later reverses it only when the
+ * switch was proven off before this install. No sudo or other user is ever
+ * attempted, and inability to enable it never blocks preservation right now.
+ */
+async function ensureLinuxBootPersistence(plan, options, exec) {
+    const uid = currentUid(options);
+    if (uid === null) {
+        return {
+            persistence: "login", ownership: null, previousOwnership: null, newlyEnabled: false,
+            note: "Automatic preservation is active, but this Linux runtime did not expose the current user id, so persistence after logout or reboot could not be verified. It will resume at the next login."
+        };
+    }
+    const previousOwnership = await readLinuxLingerOwnership(plan, uid);
+    const before = await linuxLingerEnabled(uid, exec);
+    if (before === true) {
+        return { persistence: "boot", ownership: previousOwnership, previousOwnership, newlyEnabled: false };
+    }
+    if (before === null) {
+        return {
+            persistence: "login", ownership: previousOwnership, previousOwnership, newlyEnabled: false,
+            note: "Automatic preservation is active, but this host could not inspect systemd user lingering, so persistence after the last logout or reboot could not be verified. It will resume at the next login."
+        };
+    }
+    try {
+        await exec("loginctl", ["enable-linger", String(uid)]);
+    }
+    catch (error) {
+        return {
+            persistence: "login", ownership: previousOwnership, previousOwnership, newlyEnabled: false,
+            note: `Automatic preservation is active, but this host did not allow boot persistence (${oneLine(error)}). It will resume at the next login.`
+        };
+    }
+    if (await linuxLingerEnabled(uid, exec) !== true) {
+        // The mutating command returned success without proving the state. Restore
+        // the known-off state instead of claiming a reboot promise we cannot test.
+        const rollbackError = await exec("loginctl", ["disable-linger", String(uid)])
+            .then(() => null)
+            .catch((error) => error);
+        const ownership = previousOwnership ?? { uid, enabledBySealkeep: true, enabledAt: new Date().toISOString() };
+        return {
+            persistence: "login",
+            // A failed reversal leaves state uncertain but still ours: it was proven
+            // off before our enable attempt. Keep the receipt so uninstall can retry.
+            ownership: rollbackError ? ownership : previousOwnership,
+            previousOwnership,
+            newlyEnabled: rollbackError !== null,
+            note: rollbackError
+                ? `Automatic preservation is active, but systemd neither confirmed boot persistence nor restored its previous setting (${oneLine(rollbackError)}). Sealkeep kept an ownership receipt so cleanup can retry.`
+                : "Automatic preservation is active, but systemd did not confirm boot persistence. It will resume at the next login."
+        };
+    }
+    const ownership = previousOwnership ?? { uid, enabledBySealkeep: true, enabledAt: new Date().toISOString() };
+    return { persistence: "boot", ownership, previousOwnership, newlyEnabled: true };
+}
+async function rollbackNewLinuxLinger(setup, exec, ranCommands) {
+    if (!setup?.newlyEnabled || !setup.ownership)
+        return null;
+    try {
+        await exec("loginctl", ["disable-linger", String(setup.ownership.uid)]);
+        ranCommands?.push(`loginctl disable-linger ${setup.ownership.uid}`);
+        return null;
+    }
+    catch (error) {
+        return `loginctl could not roll back Sealkeep's linger setting: ${oneLine(error)}`;
+    }
+}
+/** Whether the manager's loaded command is the package-independent target. */
+async function registrationUsesPlan(plan, exec) {
+    let result;
+    if (plan.kind === "launchd") {
+        const target = launchdTarget(plan.label);
+        if (!target)
+            return true;
+        result = await exec("launchctl", ["print", target]).catch(() => null);
+    }
+    else if (plan.kind === "systemd") {
+        result = await exec("systemctl", ["--user", "show", plan.label, "--property=ExecStart", "--value"]).catch(() => null);
+    }
+    else {
+        return true;
+    }
+    const output = commandOutput(result);
+    // Injected test executors and older managers may expose only success/failure.
+    // In that case file drift still drives repair; never declare drift from an
+    // observation the platform did not provide.
+    return output === null || (output.includes(plan.managerPath) && output.includes(plan.receiptPath));
+}
+function definitionUsesPlan(contents, plan) {
+    return contents !== null && contents.includes(plan.managerPath) && contents.includes(plan.receiptPath);
+}
+function decodeServiceXml(value) {
+    return value.replace(/&(?:lt|gt|amp|quot|apos|#\d+|#x[0-9a-f]+);/gi, (entity) => {
+        const named = { "&lt;": "<", "&gt;": ">", "&amp;": "&", "&quot;": '"', "&apos;": "'" };
+        if (named[entity])
+            return named[entity];
+        const numeric = entity.startsWith("&#x") ? Number.parseInt(entity.slice(3, -1), 16) : Number(entity.slice(2, -1));
+        return Number.isInteger(numeric) && numeric >= 0 && numeric <= 0x10ffff ? String.fromCodePoint(numeric) : entity;
+    });
+}
+/** Parse only the direct argv forms emitted by our service definitions. Shell
+ * programs, expansion, and malformed quoting are not ownership evidence. */
+function serviceCommandWords(command, windows = false) {
+    const words = [];
+    const token = /\s*("(?:[^"\\]|\\.)*"|'[^']*'|[^\s"']+)/gy;
+    let offset = 0;
+    while (offset < command.length) {
+        if (!command.slice(offset).trim())
+            break;
+        token.lastIndex = offset;
+        const match = token.exec(command);
+        if (!match)
+            return null;
+        const raw = match[1];
+        try {
+            words.push(raw.startsWith('"') ? (windows ? raw.slice(1, -1) : JSON.parse(raw))
+                : raw.startsWith("'") ? raw.slice(1, -1) : raw);
+        }
+        catch {
+            return null;
+        }
+        offset = token.lastIndex;
+    }
+    return words;
+}
+function serviceArgvOwnsVault(argv, plan, dataDir) {
+    if (!argv)
+        return false;
+    const executable = argv[0]?.replace(/\\/g, "/").split("/").at(-1) ?? "";
+    if (!/^(?:node(?:\.exe)?|sealkeep(?:\.cmd|\.exe)?|vaultline(?:\.cmd|\.exe)?)$/i.test(executable))
+        return false;
+    const manager = argv.findIndex((argument) => /(?:^|[/\\])manager\.mjs$/.test(argument));
+    if (manager >= 0) {
+        // A foreign manager/receipt remains foreign even when a trailing argument
+        // or comment happens to mention the requested vault.
+        if (manager !== 1 || argv[manager] !== plan.managerPath || argv[manager + 1] !== plan.receiptPath || argv[manager + 2] !== "--")
+            return false;
+    }
+    const roots = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        if (argv[index] === "--data-dir")
+            roots.push(argv[++index] ?? "");
+        else if (argv[index].startsWith("--data-dir="))
+            roots.push(argv[index].slice("--data-dir=".length));
+    }
+    if (roots.some((root) => root !== dataDir))
+        return false;
+    return manager >= 0 || (argv.includes("daemon") && roots.length > 0);
+}
+async function reconciliationReceiptAgrees(plan, dataDir) {
+    let raw;
+    try {
+        raw = await readFile(plan.receiptPath, "utf8");
+    }
+    catch (error) {
+        return error.code === "ENOENT";
+    }
+    try {
+        const receipt = JSON.parse(raw);
+        return receipt.dataDir === dataDir && receipt.managerPath === plan.managerPath && receipt.receiptPath === plan.receiptPath;
+    }
+    catch {
+        return false;
+    }
+}
+function serviceDefinitionOwnsVault(contents, plan, dataDir) {
+    if (plan.kind === "launchd") {
+        const array = /<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/.exec(contents)?.[1];
+        if (array !== undefined) {
+            const strings = [...array.matchAll(/<string>([^<]*)<\/string>/g)];
+            if (array.replace(/<string>[^<]*<\/string>/g, "").trim())
+                return false;
+            return serviceArgvOwnsVault(strings.map((match) => decodeServiceXml(match[1])), plan, dataDir);
+        }
+        // Older malformed plists stored a command string rather than an argv
+        // array. Repair only when that command explicitly names this same vault.
+        const legacy = /<key>ProgramArguments<\/key>\s*<string>([^<]*)<\/string>/.exec(contents)?.[1];
+        return legacy !== undefined && serviceArgvOwnsVault(serviceCommandWords(decodeServiceXml(legacy)), plan, dataDir);
+    }
+    if (plan.kind === "systemd") {
+        const commands = [...contents.matchAll(/^ExecStart=(.*)$/gm)];
+        return commands.length === 1 && serviceArgvOwnsVault(serviceCommandWords(commands[0][1]), plan, dataDir);
+    }
+    return false;
+}
+function scheduledTaskOwnsVault(xml, plan, dataDir) {
+    const actions = [...xml.matchAll(/<Exec(?:\s[^>]*)?>([\s\S]*?)<\/Exec>/g)];
+    if (actions.length !== 1)
+        return false;
+    const command = /<Command>([^<]*)<\/Command>/.exec(actions[0][1])?.[1];
+    const argumentsText = /<Arguments>([^<]*)<\/Arguments>/.exec(actions[0][1])?.[1] ?? "";
+    if (!command)
+        return false;
+    const executable = decodeServiceXml(command).replace(/^"|"$/g, "");
+    let args = decodeServiceXml(argumentsText);
+    if (/(?:^|[/\\])cmd(?:\.exe)?$/i.test(executable)) {
+        const wrapper = /^\/c\s+"((?:set [A-Za-z_][A-Za-z0-9_]*=[^&"\r\n]*&& )+)([\s\S]*)"$/i.exec(args);
+        if (!wrapper)
+            return false;
+        return serviceArgvOwnsVault(serviceCommandWords(wrapper[2], true), plan, dataDir);
+    }
+    return serviceArgvOwnsVault([executable, ...(serviceCommandWords(args, true) ?? [])], plan, dataDir);
+}
+async function receiptUsesPlan(plan, dataDir) {
+    try {
+        const receipt = JSON.parse(await readFile(plan.receiptPath, "utf8"));
+        return receipt.dataDir === dataDir && receipt.managerPath === plan.managerPath && receipt.receiptPath === plan.receiptPath;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Remove the current launchd registration by label before loading a corrected
+ * plist. `bootout` deliberately comes first: old Sealkeep builds wrote
+ * ProgramArguments in a malformed shape, so asking launchctl to parse that
+ * stale file again is not a reliable way to unload it.
+ */
+async function unloadLaunchdRegistration(plan, exec) {
+    const target = launchdTarget(plan.label);
+    if (target) {
+        const command = ["launchctl", ["bootout", target]];
+        if (await exec(command[0], command[1]).then(() => true).catch(() => false))
+            return command;
+    }
+    const fallback = ["launchctl", ["unload", "-w", plan.path]];
+    if (await exec(fallback[0], fallback[1]).then(() => true).catch(() => false))
+        return fallback;
+    return null;
+}
+function packageTargetOf(executable, args) {
+    const command = executable.replace(/\\/g, "/").split("/").pop()?.toLowerCase() ?? "";
+    return command.startsWith("node") && args[0] ? args[0] : executable;
+}
+async function writeIntegrationManager(plan, options, linuxLingerOverride) {
+    const home = options.home ?? homedir();
+    const executable = options.executable ?? process.execPath;
+    const args = options.args ?? [];
+    const previousLinger = await readLinuxLingerOwnership(plan, currentUid(options));
+    // `undefined` preserves an ownership record while reconciling an upgrade;
+    // `null` deliberately clears it after a rollback or when another tool
+    // already owned the user-wide setting.
+    const linuxLinger = linuxLingerOverride === undefined ? previousLinger : linuxLingerOverride;
+    const receipt = {
+        version: 1,
+        disclosed: true,
+        installedAt: new Date().toISOString(),
+        dataDir: options.dataDir,
+        home,
+        kind: plan.kind,
+        label: plan.label,
+        unitPath: plan.path,
+        managerPath: plan.managerPath,
+        receiptPath: plan.receiptPath,
+        executable,
+        args,
+        packageTarget: packageTargetOf(executable, args),
+        cleanupGraceMs: options.cleanupGraceMs ?? 5 * 60_000,
+        monitorIntervalMs: options.cleanupMonitorMs ?? 30_000,
+        ...(linuxLinger ? { linuxLinger } : {}),
+        hookFiles: [join(home, ".codex", "hooks.json"), join(home, ".claude", "settings.json")],
+        ownedFragments: [join(options.dataDir, "integrations", "codex-hooks.json"), join(options.dataDir, "integrations", "claude-hooks.json")],
+        // Runtime evidence owned by the supervised child. Normal service shutdown
+        // removes this itself; the surviving manager also names it explicitly so
+        // an interrupted package uninstall cannot leave a convincing stale owner.
+        // ui-server.json is deliberately absent: an interactive UI for this vault
+        // may own that listener and must not be torn down by service cleanup.
+        ownedRuntimeFiles: [join(options.dataDir, "ui-supervisor.json")],
+        cleanupPolicy: {
+            removes: [
+                "Sealkeep-owned agent lifecycle entries",
+                "background service/task",
+                "Autopilot local UI supervision record",
+                "Sealkeep-owned hook fragments",
+                ...(linuxLinger ? ["systemd user lingering enabled by Sealkeep"] : []),
+            ],
+            preserves: ["encrypted archives", "unsynced outbox", "native-keychain recovery material", "remote objects"],
+        },
+    };
+    await mkdir(dirname(plan.managerPath), { recursive: true, mode: 0o700 });
+    await writeFile(plan.managerPath, INTEGRATION_MANAGER_SOURCE, { mode: 0o700 });
+    await writeFile(plan.receiptPath, JSON.stringify(receipt, null, 2) + "\n", { mode: 0o600 });
+}
+/**
+ * Upgrade path for units installed before the package-independent manager
+ * existed. No new service is installed on a machine that did not already
+ * consent to one; an existing stale or inactive registration is repaired and
+ * activated immediately instead of waiting for the next login/reboot.
+ */
+export async function reconcileInstalledService(options) {
+    const plan = servicePlan(options);
+    if (plan.kind === "unsupported")
+        return false;
+    const exec = serviceExec(options);
+    if (plan.kind !== "schtasks") {
+        const current = await readFile(plan.path, "utf8").catch(() => null);
+        if (current === null)
+            return false;
+        // The service label is user-wide, not vault-wide. Automatic reconciliation
+        // is an upgrade of an already-owned integration, never a vault switch.
+        // Check before even querying/altering service or linger state.
+        if (!serviceDefinitionOwnsVault(current, plan, options.dataDir))
+            return false;
+        if (!(await reconciliationReceiptAgrees(plan, options.dataDir)))
+            return false;
+        const live = await registrationIsLive(plan, exec);
+        const changed = current !== plan.contents;
+        const staleRegistration = live && !(await registrationUsesPlan(plan, exec));
+        if (await readFile(plan.path, "utf8").catch(() => null) !== current)
+            return false;
+        const linger = plan.kind === "systemd" ? await ensureLinuxBootPersistence(plan, options, exec) : null;
+        try {
+            await writeIntegrationManager(plan, options, linger?.ownership);
+        }
+        catch (error) {
+            const rollbackNote = await rollbackNewLinuxLinger(linger, exec);
+            if (rollbackNote && linger?.ownership) {
+                await writeIntegrationManager(plan, options, linger.ownership).catch(() => undefined);
+            }
+            throw error;
+        }
+        if (changed)
+            await writeFile(plan.path, plan.contents, { mode: 0o600 });
+        const failed = async () => {
+            const rollbackNote = await rollbackNewLinuxLinger(linger, exec);
+            if (linger?.newlyEnabled) {
+                await writeIntegrationManager(plan, options, rollbackNote ? linger.ownership : linger.previousOwnership).catch(() => undefined);
+            }
+            return false;
+        };
+        if (plan.kind === "launchd" && (changed || staleRegistration || !live)) {
+            // A daemon also runs this reconciliation after package upgrades. It must
+            // never boot out the launchd job it is currently a child of: launchd
+            // terminates the manager and this process before either can execute the
+            // matching load, leaving the login agent unregistered. The corrected
+            // files are already on disk; an ordinary setup/settings call (outside
+            // the job) can reload them safely, and the next login uses them anyway.
+            if (process.env.XPC_SERVICE_NAME === plan.label && live)
+                return true;
+            if (live && !(await unloadLaunchdRegistration(plan, exec)))
+                return failed();
+            for (const [file, args] of plan.enable) {
+                if (!(await exec(file, args).then(() => true).catch(() => false)))
+                    return failed();
+            }
+        }
+        else if (plan.kind === "systemd" && (changed || staleRegistration || !live)) {
+            for (const [file, args] of plan.enable) {
+                if (!(await exec(file, args).then(() => true).catch(() => false)))
+                    return failed();
+            }
+            // `enable --now` starts an inactive unit but does not replace the process
+            // of an already-active unit after ExecStart changed.
+            if ((changed || staleRegistration) && live) {
+                // The daemon itself runs reconciliation after an npm upgrade. Asking
+                // systemd to synchronously restart the service from that child creates
+                // a stop cycle: systemd waits for the child, while daemon shutdown waits
+                // for this very `restart` call. The corrected unit/manager are already
+                // durable and will be used at the next safe native restart. Foreground
+                // setup/settings callers still restart an active drifted service now.
+                if (!runningInsideServicePlan(plan)
+                    && !(await exec("systemctl", ["--user", "restart", plan.label]).then(() => true).catch(() => false)))
+                    return failed();
+            }
+        }
+        return true;
+    }
+    const present = await registrationIsLive(plan, exec);
+    if (!present)
+        return false;
+    const registered = commandOutput(await exec("schtasks", ["/query", "/tn", plan.label, "/xml"]).catch(() => null));
+    if (registered === null || !scheduledTaskOwnsVault(registered, plan, options.dataDir))
+        return false;
+    if (!(await reconciliationReceiptAgrees(plan, options.dataDir)))
+        return false;
+    await writeIntegrationManager(plan, options);
+    for (const [file, args] of plan.enable)
+        await exec(file, args).catch(() => undefined);
+    return true;
 }
 /** Writes the unit file and asks the platform's service manager to start it at login. */
 export async function installService(options) {
@@ -113,54 +695,199 @@ export async function installService(options) {
     if (plan.kind === "unsupported") {
         return { kind: plan.kind, installed: false, path: "", ranCommands: [], note: `No background service is available on ${options.platform ?? platform()}. Run \`sealkeep daemon\` yourself.` };
     }
-    const exec = options.exec ?? ((file, args) => run(file, args));
+    const exec = serviceExec(options);
+    const previous = plan.kind === "schtasks" ? null : await readFile(plan.path, "utf8").catch(() => null);
+    const live = await registrationIsLive(plan, exec);
+    if (plan.kind !== "schtasks" && previous !== null && !definitionUsesPlan(previous, plan)) {
+        return {
+            kind: plan.kind,
+            installed: false,
+            path: plan.path,
+            ranCommands: [],
+            note: "Autopilot is already owned by a different Sealkeep vault for this user. Stop it from that vault before choosing another; nothing was changed.",
+        };
+    }
+    const changed = previous !== plan.contents;
+    const staleRegistration = live && !(await registrationUsesPlan(plan, exec));
     await mkdir(join(options.dataDir, "logs"), { recursive: true, mode: 0o700 });
+    await writeIntegrationManager(plan, options);
+    // Retire the previous name first, or both agents load at the next login.
+    // Only when there is something to retire: asking launchctl to unload a unit
+    // file that was never written is a command that does nothing, and a fresh
+    // install should not run it.
+    await retireLegacy(plan.kind, options.home ?? homedir(), exec);
     if (plan.kind !== "schtasks") {
         await mkdir(dirname(plan.path), { recursive: true });
         await writeFile(plan.path, plan.contents, { mode: 0o600 });
     }
     const ranCommands = [];
+    let linger = null;
+    if (plan.kind === "systemd") {
+        linger = await ensureLinuxBootPersistence(plan, options, exec);
+        if (linger.newlyEnabled && linger.ownership) {
+            ranCommands.push(`loginctl enable-linger ${linger.ownership.uid}`);
+        }
+        try {
+            await writeIntegrationManager(plan, options, linger.ownership);
+        }
+        catch (error) {
+            await rollbackNewLinuxLinger(linger, exec, ranCommands);
+            throw error;
+        }
+    }
+    const installFailure = async (message) => {
+        const rollbackNote = await rollbackNewLinuxLinger(linger, exec, ranCommands);
+        if (linger?.newlyEnabled) {
+            await writeIntegrationManager(plan, options, rollbackNote ? linger.ownership : linger.previousOwnership).catch(() => undefined);
+        }
+        return {
+            kind: plan.kind, installed: false, path: plan.path, ranCommands,
+            persistence: linger?.persistence,
+            note: rollbackNote ? `${message}. ${rollbackNote}` : message,
+        };
+    };
+    if (plan.kind === "launchd" && live && (changed || staleRegistration)) {
+        const unloaded = await unloadLaunchdRegistration(plan, exec);
+        if (!unloaded) {
+            return installFailure("launchctl failed to unload the stale service registration");
+        }
+        ranCommands.push([unloaded[0], ...unloaded[1]].join(" "));
+    }
+    // A byte-identical launchd job that is already loaded needs no second `load`
+    // (which launchctl rejects as a duplicate registration).
+    if (plan.kind === "launchd" && live && !changed && !staleRegistration) {
+        return { kind: plan.kind, installed: true, path: plan.path, managerPath: plan.managerPath, receiptPath: plan.receiptPath, ranCommands, persistence: "login" };
+    }
     for (const [file, args] of plan.enable) {
         try {
             await exec(file, args);
             ranCommands.push([file, ...args].join(" "));
         }
         catch (error) {
-            return { kind: plan.kind, installed: false, path: plan.path, ranCommands, note: `${file} failed: ${error instanceof Error ? error.message.split("\n")[0] : "unknown error"}` };
+            return installFailure(`${file} failed: ${error instanceof Error ? error.message.split("\n")[0] : "unknown error"}`);
         }
     }
-    return { kind: plan.kind, installed: true, path: plan.path, ranCommands };
+    if (plan.kind === "systemd" && live && (changed || staleRegistration)) {
+        // `installService` is normally foreground, but retain the same exact
+        // self-restart guard as reconciliation for library callers inside the
+        // managed daemon.
+        if (!runningInsideServicePlan(plan)) {
+            const file = "systemctl";
+            const args = ["--user", "restart", plan.label];
+            try {
+                await exec(file, args);
+                ranCommands.push([file, ...args].join(" "));
+            }
+            catch (error) {
+                return installFailure(`${file} failed: ${error instanceof Error ? error.message.split("\n")[0] : "unknown error"}`);
+            }
+        }
+    }
+    return {
+        kind: plan.kind, installed: true, path: plan.path,
+        managerPath: plan.managerPath, receiptPath: plan.receiptPath, ranCommands,
+        persistence: linger?.persistence ?? "login",
+        note: linger?.note,
+    };
 }
 export async function uninstallService(options) {
     const plan = servicePlan(options);
     if (plan.kind === "unsupported")
         return { kind: plan.kind, installed: false, path: "", ranCommands: [] };
-    const exec = options.exec ?? ((file, args) => run(file, args));
+    const exec = serviceExec(options);
     const ranCommands = [];
+    const uid = currentUid(options);
+    const definition = plan.kind === "schtasks" ? null : await readFile(plan.path, "utf8").catch(() => null);
+    const receiptOwned = await receiptUsesPlan(plan, options.dataDir);
+    const liveBefore = await registrationIsLive(plan, exec);
+    if (plan.kind !== "schtasks" && ((definition !== null && !definitionUsesPlan(definition, plan)) || (definition === null && liveBefore && !receiptOwned))) {
+        return {
+            kind: plan.kind,
+            installed: false,
+            path: plan.path,
+            ranCommands,
+            note: "The active Autopilot service belongs to a different Sealkeep vault. Nothing was stopped or removed.",
+        };
+    }
+    const ownedLinger = plan.kind === "systemd" ? await readLinuxLingerOwnership(plan, uid) : null;
+    const stopErrors = [];
     for (const [file, args] of plan.disable) {
         try {
             await exec(file, args);
             ranCommands.push([file, ...args].join(" "));
         }
-        catch { /* already stopped */ }
+        catch (error) {
+            stopErrors.push(`${file}: ${oneLine(error)}`);
+        }
+    }
+    const stillLive = await registrationIsLive(plan, exec);
+    // A service that was demonstrably live before a failed stop is not proven
+    // gone merely because the follow-up query cannot see it. Preserve every
+    // ownership artifact in that ambiguous state so a retry can finish safely.
+    if (stillLive || (liveBefore && stopErrors.length > 0)) {
+        return {
+            kind: plan.kind,
+            installed: true,
+            path: plan.path,
+            managerPath: plan.managerPath,
+            receiptPath: plan.receiptPath,
+            ranCommands,
+            note: `Autopilot is still running, so its files, phrase, hooks, and ownership receipt were kept. Retry after resolving the service-manager error${stopErrors.length ? ` (${stopErrors.join("; ")})` : ""}.`,
+        };
     }
+    await retireLegacy(plan.kind, options.home ?? homedir(), exec);
     if (plan.kind !== "schtasks")
         await rm(plan.path, { force: true });
-    return { kind: plan.kind, installed: false, path: plan.path, ranCommands };
+    // The managed child normally removes this on SIGTERM together with its
+    // loopback listener. Remove the owner record here as well for service
+    // managers (notably Task Scheduler) that may terminate a child without
+    // delivering Node a graceful signal. Never remove ui-server.json here: a
+    // separately opened interactive UI may legitimately own it.
+    await rm(join(options.dataDir, "ui-supervisor.json"), { force: true });
+    let note;
+    let lingerCleanupPending = false;
+    // Never trust a receipt to target another account. The only shared systemd
+    // setting Sealkeep reverses is the current numeric user's setting, and only
+    // when the owner-only receipt proves Sealkeep enabled it from an off state.
+    if (ownedLinger && uid === ownedLinger.uid) {
+        try {
+            await exec("loginctl", ["disable-linger", String(uid)]);
+            ranCommands.push(`loginctl disable-linger ${uid}`);
+        }
+        catch (error) {
+            lingerCleanupPending = true;
+            note = `The Sealkeep service is removed, but systemd user lingering could not be restored (${oneLine(error)}). No Sealkeep process will run.`;
+        }
+    }
+    await rm(plan.managerPath, { force: true });
+    // The receipt is the proof that a later retry may disable this user-wide
+    // setting. Erasing it after a transient loginctl failure makes safe cleanup
+    // impossible, so retain it until restoration succeeds.
+    if (!lingerCleanupPending)
+        await rm(plan.receiptPath, { force: true });
+    return { kind: plan.kind, installed: false, path: plan.path, ranCommands, note };
 }
-/** Reports whether the unit file this build would write is currently present. */
+/** Reports durable installation separately from whether the manager has it live now. */
 export async function serviceStatus(options) {
     const plan = servicePlan(options);
     if (plan.kind === "unsupported")
-        return { kind: plan.kind, present: false, path: "" };
-    if (plan.kind === "schtasks") {
-        const exec = options.exec ?? ((file, args) => run(file, args));
-        const present = await exec("schtasks", ["/query", "/tn", "Sealkeep"]).then(() => true).catch(() => false);
-        return { kind: plan.kind, present, path: plan.path };
-    }
-    const contents = await readFile(plan.path, "utf8").catch(() => null);
+        return { kind: plan.kind, installed: false, present: false, path: "" };
+    const exec = serviceExec(options);
+    const contents = plan.kind === "schtasks" ? null : await readFile(plan.path, "utf8").catch(() => null);
     const runs = contents?.match(/ExecStart=(.*)/)?.[1] ?? contents?.match(/<string>([^<]*daemon[^<]*)<\/string>/)?.[1];
-    return { kind: plan.kind, present: contents !== null, path: plan.path, runs: runs ?? undefined };
+    // A durable POSIX service is healthy only when both halves agree: its unit
+    // remains installed for the next login and the service manager has it live
+    // now. Windows keeps both facts in Task Scheduler itself.
+    const owned = plan.kind === "schtasks" ? true : definitionUsesPlan(contents, plan);
+    const present = owned && await registrationIsLive(plan, exec) && await registrationUsesPlan(plan, exec);
+    // POSIX keeps the durable registration in its unit file. Task Scheduler is
+    // itself both the stored definition and the queryable registration.
+    const installed = plan.kind === "schtasks" ? present : owned;
+    const uid = currentUid(options);
+    const persistence = plan.kind === "systemd" && contents !== null
+        ? (uid !== null && await linuxLingerEnabled(uid, exec) === true ? "boot" : "login")
+        : plan.kind === "launchd" || plan.kind === "schtasks" ? "login" : undefined;
+    return { kind: plan.kind, installed, present, path: plan.path, runs: runs ?? undefined, persistence };
 }
 /**
  * The environment a service unit needs beyond its flags. A service manager
@@ -168,14 +895,21 @@ export async function serviceStatus(options) {
  * where secrets live has to ride along in the unit — a vault set up with
  * SEALKEEP_SECRET_BACKEND=file kept its phrase in a keystore the daemon then
  * never looked in, and every tick died on "No recovery phrase available".
+ * Upload capability is included by default because storage may be connected
+ * after installation; target configuration and credentials remain mandatory.
+ * Callers representing an explicit `--no-upload` omit it with `uploads:false`.
  */
-export function serviceUnitEnvironment(base = {}, env = process.env) {
+export function serviceUnitEnvironment(base = {}, env = process.env, options = {}) {
     const backend = envVar("SECRET_BACKEND", env);
-    return { ...(backend ? { SEALKEEP_SECRET_BACKEND: backend } : {}), ...base };
+    return {
+        ...(backend ? { SEALKEEP_SECRET_BACKEND: backend } : {}),
+        ...(options.uploads === false ? {} : { SEALKEEP_ENABLE_SIGNER: "1" }),
+        ...base,
+    };
 }
-/** The argv the service should run: this package's CLI, with the daemon subcommand. */
+/** The argv the service should run: this package's daemon plus its loopback UI lane. */
 export function daemonInvocation(dataDir, options = {}) {
-    let cli = options.cliPath ?? process.argv[1] ?? "vaultline";
+    let cli = options.cliPath ?? process.argv[1] ?? "sealkeep";
     // A service unit runs plain node, and plain node cannot execute TypeScript.
     // Installed packages always resolve to dist/cli.js, but a source checkout
     // running under tsx resolves to src/cli.ts — writing that path into launchd
@@ -191,9 +925,16 @@ export function daemonInvocation(dataDir, options = {}) {
         }
         cli = built;
     }
-    const args = [cli, "daemon", "--data-dir", dataDir];
+    // `--serve-ui` is intentionally explicit. `sealkeep daemon` remains a
+    // foreground worker unless its native service owns the browserless UI lane;
+    // a developer command must never acquire 7477 as a hidden side effect.
+    const args = [cli, "daemon", "--data-dir", dataDir, "--serve-ui"];
+    if (Number.isFinite(options.intervalSeconds) && (options.intervalSeconds ?? 0) > 0) {
+        args.push("--interval", String(Math.max(1, Math.round(options.intervalSeconds))));
+    }
+    if (options.upload === false)
+        args.push("--no-upload");
     if (options.reclaim)
         args.push("--reclaim");
     return { executable: process.execPath, args };
 }
-export function serviceKind(target = platform()) { return kindFor(target); }