sealkeep 0.9.0 → 0.11.0

package/dist/src/doctor.js

@@ -1,18 +1,21 @@
-import { mkdir, rm, stat, writeFile } from "node:fs/promises";
+import { mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { join } from "node:path";
-import { detectAgents } from "./adapters.js";
-import { isVaultlineError } from "./errors.js";
+import { detectSetupAgents } from "./adapters.js";
+import { isSealkeepError } from "./errors.js";
 import { localApiTokenPath } from "./paths.js";
 import { ArchiveQueue } from "./queue.js";
 import { signerEnabled } from "./control-plane.js";
+import { liveness, readHeartbeat } from "./heartbeat.js";
 import { quotaMessage, quotaState } from "./packages.js";
 import { loadProviderCredentials, resolveRecoveryPhrase } from "./secrets.js";
-import { ENVELOPE_VERSION, SUITES } from "../packages/vaultline-crypto/src/index.js";
+import { ENVELOPE_VERSION, SUITES } from "../packages/sealkeep-crypto/src/index.js";
 import { readConfig } from "./vault.js";
 import { envVar } from "./env.js";
+import { providerLabel } from "./branding.js";
+import { readUntouchedCodexResumeStub } from "./resume-stub.js";
 async function writable(directory) {
-    const probe = join(directory, `.vaultline-write-probe-${randomUUID()}`);
+    const probe = join(directory, `.sealkeep-write-probe-${randomUUID()}`);
     try {
         await mkdir(directory, { recursive: true, mode: 0o700 });
         await writeFile(probe, "");
@@ -25,6 +28,164 @@ async function writable(directory) {
         await rm(probe, { force: true });
     }
 }
+function archiveMetadataId(raw) {
+    try {
+        const record = JSON.parse(raw);
+        return record && typeof record === "object" && typeof record.id === "string" && record.id
+            ? record.id
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function mapIntegrityMetadata(names, concurrency, work) {
+    const output = new Array(names.length);
+    let cursor = 0;
+    const workers = Array.from({ length: Math.min(Math.max(1, concurrency), names.length) }, async () => {
+        for (;;) {
+            const index = cursor++;
+            if (index >= names.length)
+                return;
+            output[index] = await work(names[index]);
+            if ((index + 1) % 16 === 0)
+                await new Promise((resolve) => setImmediate(resolve));
+        }
+    });
+    await Promise.all(workers);
+    return output;
+}
+function sameNames(left, right) {
+    return left.length === right.length && left.every((name, index) => name === right[index]);
+}
+/**
+ * Read one sidecar without turning descriptor pressure into a corruption report.
+ * A malformed document is called invalid only when the exact bytes remain
+ * malformed across a second read. I/O failures and changing bytes stay in the
+ * transient bucket; Health remains red, but does not tell the user the archive
+ * metadata itself is corrupt.
+ */
+async function readIntegrityMetadata(directory, name, read, readAttempts) {
+    const path = join(directory, name);
+    let raw = null;
+    for (let attempt = 0; attempt < readAttempts; attempt += 1) {
+        try {
+            raw = await read(path);
+            break;
+        }
+        catch {
+            if (attempt + 1 < readAttempts)
+                await new Promise((resolve) => setImmediate(resolve));
+        }
+    }
+    if (raw === null)
+        return { kind: "transient", name };
+    const id = archiveMetadataId(raw);
+    if (id)
+        return { kind: "valid", name, id };
+    // Atomic record updates should never expose partial JSON. Confirm stable bad
+    // bytes anyway, so a manual repair racing this read is not branded damage.
+    await new Promise((resolve) => setImmediate(resolve));
+    let confirmation;
+    try {
+        confirmation = await read(path);
+    }
+    catch {
+        return { kind: "transient", name };
+    }
+    const confirmedId = archiveMetadataId(confirmation);
+    if (confirmedId)
+        return { kind: "valid", name, id: confirmedId };
+    return confirmation === raw ? { kind: "invalid", name } : { kind: "transient", name };
+}
+export async function archiveIntegritySummary(directory, options = {}) {
+    const listDirectory = options.listDirectory ?? readdir;
+    const readMetadata = options.readMetadata ?? ((path) => readFile(path, "utf8"));
+    const concurrency = Math.min(64, Math.max(1, Math.trunc(options.concurrency ?? 24) || 1));
+    const readAttempts = Math.min(5, Math.max(1, Math.trunc(options.readAttempts ?? 2) || 1));
+    const snapshotAttempts = Math.min(5, Math.max(1, Math.trunc(options.snapshotAttempts ?? 3) || 1));
+    let names = [];
+    let reads = [];
+    let scanIncomplete = false;
+    for (let attempt = 0; attempt < snapshotAttempts; attempt += 1) {
+        let before;
+        try {
+            before = (await listDirectory(directory)).filter((name) => name.endsWith(".json") || name.endsWith(".skarchive")).sort();
+        }
+        catch {
+            return {
+                ok: false,
+                unreadableMetadataCount: 0,
+                invalidMetadataCount: 0,
+                transientMetadataReadErrorCount: 0,
+                detachedArchiveCount: 0,
+                scanIncomplete: true,
+                detail: "Sealkeep cannot list archive metadata. Nothing was changed.",
+            };
+        }
+        const metadata = before.filter((name) => name.endsWith(".json"));
+        reads = await mapIntegrityMetadata(metadata, concurrency, (name) => readIntegrityMetadata(directory, name, readMetadata, readAttempts));
+        let after;
+        try {
+            after = (await listDirectory(directory)).filter((name) => name.endsWith(".json") || name.endsWith(".skarchive")).sort();
+        }
+        catch {
+            names = before;
+            scanIncomplete = true;
+            break;
+        }
+        names = after;
+        if (sameNames(before, after)) {
+            scanIncomplete = false;
+            break;
+        }
+        scanIncomplete = true;
+        if (attempt + 1 < snapshotAttempts)
+            await new Promise((resolve) => setImmediate(resolve));
+    }
+    const validIds = new Set(reads.filter((item) => item.kind === "valid").map((item) => item.id));
+    const invalid = reads.filter((item) => item.kind === "invalid").map((item) => item.name);
+    const transient = reads.filter((item) => item.kind === "transient").map((item) => item.name);
+    const transientStems = new Set(transient.map((name) => name.slice(0, -".json".length)));
+    // A sidecar that could not be read may still be perfectly valid. Do not turn
+    // the same temporary I/O failure into a second, invented detached-file error.
+    const detached = scanIncomplete ? [] : names
+        .filter((name) => name.endsWith(".skarchive"))
+        .map((name) => name.slice(0, -".skarchive".length))
+        .filter((id) => !validIds.has(id) && !transientStems.has(id));
+    const unreadableMetadataCount = invalid.length + transient.length;
+    if (unreadableMetadataCount === 0 && detached.length === 0 && !scanIncomplete) {
+        return {
+            ok: true,
+            unreadableMetadataCount: 0,
+            invalidMetadataCount: 0,
+            transientMetadataReadErrorCount: 0,
+            detachedArchiveCount: 0,
+            scanIncomplete: false,
+            detail: `${validIds.size} archive metadata record${validIds.size === 1 ? " is" : "s are"} readable; no sealed files are detached from their metadata.`
+        };
+    }
+    const parts = [
+        invalid.length > 0 ? `${invalid.length} archive metadata file${invalid.length === 1 ? " is" : "s are"} invalid` : null,
+        transient.length > 0 ? `${transient.length} archive metadata file${transient.length === 1 ? " could" : "s could"} not be checked after retrying` : null,
+        detached.length > 0 ? `${detached.length} sealed file${detached.length === 1 ? " has" : "s have"} no usable metadata` : null,
+        scanIncomplete ? "the archive folder changed throughout the check, so the snapshot is incomplete" : null,
+    ].filter((part) => Boolean(part));
+    const first = (invalid[0] ?? transient[0] ?? (detached[0] ? `${detached[0]}.skarchive` : null));
+    return {
+        ok: false,
+        unreadableMetadataCount,
+        invalidMetadataCount: invalid.length,
+        transientMetadataReadErrorCount: transient.length,
+        detachedArchiveCount: detached.length,
+        scanIncomplete,
+        detail: `${parts.join("; ")}. Sealkeep left every file untouched. Invalid metadata and detached sealed files need repair; a temporary read or changing-folder result should be checked again before treating it as damage.${first ? ` First affected file: ${first}` : ""}`
+    };
+}
+async function archiveIntegrityCheck(directory) {
+    const summary = await archiveIntegritySummary(directory);
+    return { name: "archive-integrity", status: summary.ok ? "pass" : "fail", detail: summary.detail };
+}
 /**
  * A read-mostly environment report. It writes only a probe file it removes, and
  * it never reads transcript contents, prints a recovery phrase, or shows the API token.
@@ -59,7 +220,7 @@ function quotaCheck(managed) {
  */
 async function sealedCopyCheck(dataDir, signedIn) {
     if (!signedIn)
-        return { name: "sealed-key-copy", status: "warn", detail: "Not signed in, so no sealed copy of your key is stored" };
+        return { name: "sealed-key-copy", status: "warn", detail: "Could not verify the account connection or its key backup. Review your Recovery Kit; an existing backup may still be stored." };
     try {
         const { hasSealedCopy } = await import("./cloud.js");
         return await hasSealedCopy(dataDir)
@@ -70,19 +231,21 @@ async function sealedCopyCheck(dataDir, signedIn) {
         return { name: "sealed-key-copy", status: "warn", detail: `Could not check for a sealed copy: ${error instanceof Error ? error.message.split("\n")[0] : "unknown"}` };
     }
 }
-export async function runDoctor(dataDir, env = process.env) {
+export async function runDoctor(dataDir, env = process.env, home = env.HOME ?? env.USERPROFILE ?? env.home ?? ".", options = {}) {
     const checks = [];
+    let managed = null;
     const config = await readConfig(dataDir).catch((error) => {
         // This renders in the Health tab, where a raw "config_unsupported_version:"
         // slug or a bare "unreadable" reads, to someone told there is no reset, as
         // "your vault is gone." Say what is and is not affected, and never a code.
-        const detail = isVaultlineError(error) && error.code === "vault_not_initialized"
+        const detail = isSealkeepError(error) && error.code === "vault_not_initialized"
             ? "No vault has been set up on this machine yet. Open Sealkeep's setup page to create one."
             : "Sealkeep can't read this vault's settings file. Your sealed archives are separate files and are not affected — don't create a new vault; restore this machine's vault folder from a backup, or contact support.";
         checks.push({ name: "config", status: "fail", detail });
         return null;
     });
     if (config) {
+        managed = await managedAccount(dataDir);
         checks.push({ name: "config", status: "pass", detail: `Vault ${config.vaultId} (config v${config.version})` });
         // A standing warning, like the crypto row: nothing about a healthy plain
         // vault makes this go away, because the exposure is the choice itself.
@@ -92,59 +255,149 @@ export async function runDoctor(dataDir, env = process.env) {
         checks.push(await writable(config.storage.root)
             ? { name: "archive-store", status: "pass", detail: `Writable: ${config.storage.root}` }
             : { name: "archive-store", status: "fail", detail: `Not writable: ${config.storage.root}` });
+        checks.push(await archiveIntegrityCheck(config.storage.root));
         // A machine on the managed tier has no remoteStorage of its own — the
         // bucket is ours. Reporting "archives stay on this device" to someone who
         // has been pushing to managed storage all week is worse than saying
         // nothing: it is a health check telling them a comforting falsehood.
         if (config.remoteStorage) {
-            checks.push({ name: "remote-storage", status: "pass", detail: `Target ${config.remoteStorage.provider}://${config.remoteStorage.bucket}/${config.remoteStorage.prefix}` });
+            checks.push({ name: "remote-storage", status: "pass", detail: `Target ${providerLabel(config.remoteStorage.provider)} · ${config.remoteStorage.bucket}/${config.remoteStorage.prefix}` });
         }
         else {
-            const managed = await managedAccount(dataDir);
             checks.push(managed
                 // The cloud token lives in this machine's keychain, not in the vault,
                 // so being signed in says archives from here *can* go to managed
                 // storage — not that any have. Say the weaker, true thing.
                 ? { name: "remote-storage", status: "pass", detail: `Signed in to managed storage as ${managed.email} (${managed.plan})` }
-                : { name: "remote-storage", status: "warn", detail: "No remote target configured; archives stay on this device" });
+                : config.storageTargets?.length
+                    ? { name: "remote-storage", status: "warn", detail: `Configured storage: ${config.storageTargets.map((target) => providerLabel(target.provider)).join(", ")}. The account connection could not be verified by this check. Review storage connections for current availability.` }
+                    : { name: "remote-storage", status: "warn", detail: "No remote target configured. Add a storage destination to send new archives off this machine." });
             checks.push(await sealedCopyCheck(dataDir, managed !== null));
             // A zero quota is a plan with no managed entitlement at all — nothing to warn about.
             if (managed && managed.quotaBytes > 0)
                 checks.push(quotaCheck(managed));
         }
     }
+    // The native service can deliberately stay alive while waiting for a phrase:
+    // its supervised UI is the recovery path that lets Settings store one and
+    // wake the worker. Keep this context separate from the heartbeat because the
+    // locked process has not started a daemon tick yet, and its startup heartbeat
+    // only proves that the child exists.
+    const phraseAvailable = config
+        ? await resolveRecoveryPhrase(dataDir, config.vaultId, undefined, env).then((phrase) => Boolean(phrase)).catch(() => false)
+        : Boolean(envVar("RECOVERY_PHRASE", env));
+    const waitingForPhrase = config !== null && options.nativeServicePresent === true && !phraseAvailable;
     const stats = await new ArchiveQueue(dataDir).stats();
     checks.push(stats.failed > 0
         ? { name: "queue", status: "warn", detail: `${stats.failed} session${stats.failed === 1 ? "" : "s"} could not be archived. See the Queue tab for why, and retry from there.` }
         : { name: "queue", status: "pass", detail: `${stats.ready} ready, ${stats.leased} in flight, ${stats.done} archived` });
-    const agents = await detectAgents();
-    const detected = agents.filter((agent) => agent.detected).map((agent) => agent.agent);
+    const agents = await detectSetupAgents(home, dataDir);
+    const supported = agents.filter((agent) => agent.detected && agent.archivable);
+    const detected = supported.map((agent) => agent.agent);
     checks.push(detected.length > 0
         ? { name: "agents", status: "pass", detail: `Detected: ${detected.join(", ")}` }
         : { name: "agents", status: "warn", detail: "No supported agent directory found on this machine" });
+    // A command in hooks.json is not proof that Codex will dispatch it. Codex
+    // keeps enabled/trust state separately in config.toml and deliberately lets
+    // the user disable a reviewed hook. Report that state without changing it;
+    // the filesystem watcher remains the independent preservation path.
+    if (supported.length > 0) {
+        const inactive = supported.filter((agent) => agent.hooksInstalled && !agent.hooksActive);
+        const missing = supported.filter((agent) => !agent.hooksInstalled);
+        // Routed elsewhere is worse than missing: it passes every presence check
+        // while recall and hook capture silently do nothing for this vault.
+        const aimedElsewhere = supported.filter((agent) => agent.hooksAimedElsewhere);
+        if (aimedElsewhere.length > 0) {
+            checks.push({
+                name: "agent-memory-hooks", status: "fail",
+                detail: aimedElsewhere.map((agent) => `${agent.label}'s memory hooks route to ${agent.hooksDataDir ?? "another data directory"}, not this vault (${dataDir}): automatic recall and hook capture are silently off here. Run \`sealkeep autopilot\` to re-target them.`).join(" ")
+            });
+        }
+        else if (inactive.length === 0 && missing.length === 0) {
+            checks.push({
+                name: "agent-memory-hooks", status: "pass",
+                detail: `${supported.map((agent) => agent.label).join(" and ")} lifecycle hooks are configured and active.`
+            });
+        }
+        else {
+            const details = [
+                ...inactive.map((agent) => agent.note ?? `${agent.label}'s configured lifecycle hooks are not active.`),
+                ...missing.map((agent) => `${agent.label}'s complete Sealkeep lifecycle is not configured.`),
+                "The background watcher remains the independent archive path while Automatic archiving is running."
+            ];
+            checks.push({ name: "agent-memory-hooks", status: "warn", detail: details.join(" ") });
+        }
+    }
+    // Hooks fail open, so a recall lane whose passes keep dying is invisible at
+    // the agent: memory is simply absent. The service's heartbeat is the one
+    // place that records it.
+    const recallLane = (await readHeartbeat(dataDir))?.context;
+    const { readHookUnlockFailure } = await import("./agent-context.js");
+    const unlockFailure = await readHookUnlockFailure(dataDir);
+    if (unlockFailure && Date.now() - Date.parse(unlockFailure.at) < 24 * 60 * 60_000) {
+        checks.push({
+            name: "automatic-recall", status: "fail",
+            detail: `The ${unlockFailure.agent === "codex" ? "Codex" : "Claude Code"} memory hook could not unlock this vault at ${unlockFailure.at.slice(0, 16).replace("T", " ")}: automatic recall and hook capture were silently off for that session, while archiving may have kept working. The hook ran with SEALKEEP_SECRET_BACKEND ${unlockFailure.backend ? `= ${unlockFailure.backend}` : "unset"}; the hooks and the background service must find the recovery phrase in the same secret backend (Settings › Unlocking, or \`sealkeep autopilot\`).`,
+        });
+    }
+    else if (recallLane?.state === "attention" && recallLane.failures >= 3) {
+        checks.push({
+            name: "automatic-recall", status: "warn",
+            detail: `Automatic recall passes keep failing (${recallLane.failures} in a row, last: ${recallLane.lastError ?? "unknown"}${recallLane.lastSuccessAt ? `, last success ${recallLane.lastSuccessAt.slice(0, 16).replace("T", " ")}` : ""}). Memory hooks still run, but recall arrives late or not at all until this clears; the background service retries every half minute.`,
+        });
+    }
+    else if (recallLane?.lastSuccessAt) {
+        checks.push({
+            name: "automatic-recall", status: "pass",
+            detail: `Automatic recall last prepared memory at ${recallLane.lastSuccessAt.slice(0, 16).replace("T", " ")}.`,
+        });
+    }
     // The failure Paul hit in the wild: an agent's own catalog still points at
     // a session file that is gone — reclaimed by us, or deleted by anything —
     // and "resume" breaks with no hint that the bytes are one command away.
     // This check counts archived sessions whose source file is missing and
     // hands over the exact command that puts each back where resume expects it.
+    // A reclaimed Codex transcript can deliberately leave a tiny valid rollout
+    // at that path. Do not call that pointer the original source: name what it
+    // is and give the overwrite mode required while it occupies the destination.
     try {
         const { stat } = await import("node:fs/promises");
         const { listArchives } = await import("./vault.js");
         const records = (await listArchives(dataDir)).filter((record) => record.version === 2);
         const missing = [];
+        const pointers = [];
         for (const record of records) {
             const there = await stat(record.source.path).then((entry) => entry.isFile()).catch(() => false);
-            if (!there)
-                missing.push(record.source.path.split("/").pop() ?? record.id);
+            const filename = record.source.path.split("/").pop() ?? record.id;
+            if (!there) {
+                missing.push({ id: record.id, filename });
+                continue;
+            }
+            if (record.reclaimed?.resumeStub?.version === 1) {
+                const pointer = await readUntouchedCodexResumeStub(record.source.path);
+                if (pointer
+                    && pointer.archiveId === record.id
+                    && pointer.sessionId === record.reclaimed.resumeStub.sessionId
+                    && pointer.bytes === record.reclaimed.resumeStub.bytes
+                    && pointer.sha256 === record.reclaimed.resumeStub.sha256) {
+                    pointers.push({ id: record.id, filename, sessionId: pointer.sessionId });
+                }
+            }
         }
         if (missing.length > 0) {
             checks.push({
                 name: "resumable-history", status: "pass",
-                detail: `${missing.length} archived session${missing.length === 1 ? " file is" : " files are"} no longer on disk (reclaimed or removed). An agent trying to resume one will say the file is missing — \`sealkeep recover <that filename>\` puts it back exactly where resume expects it. First: ${missing[0]}`
+                detail: `${missing.length} archived session${missing.length === 1 ? " file is" : " files are"} no longer on disk (reclaimed or removed). Restore the exact archive to its native path before resuming. First: ${missing[0].filename} — \`sealkeep recover ${missing[0].id} --native\``
+            });
+        }
+        else if (pointers.length > 0) {
+            checks.push({
+                name: "resumable-history", status: "pass",
+                detail: `${pointers.length} reclaimed Codex session${pointers.length === 1 ? " keeps" : "s keep"} a tiny native resume pointer, so \`codex resume ${pointers[0].sessionId}\` remains discoverable without downloading the full transcript. Use its Sealkeep MCP search instruction for relevant memory. To restore every byte explicitly while preserving the pointer as a backup, run \`sealkeep recover ${pointers[0].id} --native --overwrite backup\`, then resume again. First: ${pointers[0].filename}`
             });
         }
         else if (records.length > 0) {
-            checks.push({ name: "resumable-history", status: "pass", detail: "Every archived session's file is still on disk; agent resume needs nothing from us" });
+            checks.push({ name: "resumable-history", status: "pass", detail: "Every archived session remains discoverable at its native path; agent resume needs nothing from Sealkeep" });
         }
     }
     catch { /* an unreadable archive store already failed its own check above */ }
@@ -159,12 +412,31 @@ export async function runDoctor(dataDir, env = process.env) {
             // nothing archived yet — nothing to say
         }
         else if (coverage.missing.length === 0) {
-            checks.push({ name: "search-index", status: "pass", detail: `All ${coverage.total} archives are in the content search index${coverage.builtAt ? ` (updated ${coverage.builtAt.slice(0, 10)})` : ""}.` });
+            // "All N archives" means all N THIS MACHINE sealed. Saying so keeps the
+            // sentence true on a team, where the account holds more than this
+            // machine has ever seen.
+            checks.push({ name: "search-index", status: "pass", detail: `All ${coverage.total} archives sealed on this machine are in the content search index${coverage.builtAt ? ` (updated ${coverage.builtAt.slice(0, 10)})` : ""}.` });
         }
         else {
+            const daemonBeat = await readHeartbeat(dataDir);
+            const service = liveness(daemonBeat);
+            const indexing = service.state === "running" ? daemonBeat?.indexing : undefined;
+            let automation;
+            if (waitingForPhrase) {
+                automation = "Automatic catch-up is waiting for this machine's recovery phrase; it will resume after you store it in Settings › Unlocking.";
+            }
+            else if (indexing?.state === "building") {
+                automation = `Automatic catch-up is running in the background (attempt ${indexing.attempts}).`;
+            }
+            else if (indexing?.state === "retry-wait") {
+                automation = `Automatic catch-up is waiting to retry${indexing.nextAttemptAt ? ` after ${indexing.nextAttemptAt}` : ""}${indexing.lastError ? ` (${indexing.lastError})` : ""}.`;
+            }
+            else {
+                automation = "Automatic catch-up is not currently active; repair or restart automatic archiving in Settings.";
+            }
             checks.push({
-                name: "search-index", status: "pass",
-                detail: `${coverage.indexed} of ${coverage.total} archives are searchable; ${coverage.missing.length} not yet indexed (new seals index themselves — \`sealkeep index build\` adds the rest). First missing: ${coverage.missing[0].path.split("/").pop() ?? coverage.missing[0].id}`
+                name: "search-index", status: "warn",
+                detail: `${coverage.indexed} of ${coverage.total} archives sealed on this machine are searchable; ${coverage.missing.length} not yet indexed. ${automation}`
             });
         }
     }
@@ -179,20 +451,13 @@ export async function runDoctor(dataDir, env = process.env) {
         const pinned = [...new Set(targets.flatMap((target) => target.projects ?? []))];
         if (pinned.length > 0) {
             const { listArchives } = await import("./vault.js");
-            const { claudeProjectFromPath, codexProjectFromRollout } = await import("./adapters.js");
+            const { projectOfRecord } = await import("./adapters.js");
             const records = await listArchives(dataDir).catch(() => []);
             const known = new Set();
             for (const record of records) {
-                try {
-                    const name = record.source.agent === "claude"
-                        ? claudeProjectFromPath(record.source.path).project
-                        : record.source.agent === "codex"
-                            ? (await codexProjectFromRollout(record.source.path, record.createdAt)).project
-                            : null;
-                    if (name)
-                        known.add(name);
-                }
-                catch { /* a project we cannot read is not evidence of a bad pin */ }
+                const name = await projectOfRecord(record).catch(() => null);
+                if (name)
+                    known.add(name);
             }
             const unmatched = pinned.filter((name) => !known.has(name));
             if (unmatched.length === 0) {
@@ -212,25 +477,35 @@ export async function runDoctor(dataDir, env = process.env) {
     // so a machine set up correctly through the window — phrase in the keystore,
     // sealing away happily — was told on its Health tab that its phrase was
     // missing and named an environment variable as the cure.
-    const phraseAvailable = config
-        ? await resolveRecoveryPhrase(dataDir, config.vaultId, undefined, env).then((phrase) => Boolean(phrase)).catch(() => false)
-        : Boolean(envVar("RECOVERY_PHRASE", env));
     checks.push(phraseAvailable
         ? { name: "recovery-phrase", status: "pass", detail: "This machine can unlock the vault on its own, so archiving runs unattended." }
         : { name: "recovery-phrase", status: "warn", detail: "This machine doesn't hold your recovery phrase, so it can't archive on its own. Add it under Settings › Unlocking to let archiving run unattended. Your vault and archives are unaffected." });
     const tokenMode = await stat(localApiTokenPath(dataDir)).then((info) => info.mode & 0o777).catch(() => null);
     checks.push(tokenMode === null
-        ? { name: "local-api-token", status: "warn", detail: "No local API token yet; it is created when `sealkeep api` first starts" }
+        ? { name: "local-api-token", status: "warn", detail: "No local API token yet; Autopilot creates it with the local UI, as do `sealkeep ui` and `sealkeep api`" }
         : tokenMode === 0o600
             ? { name: "local-api-token", status: "pass", detail: "Local API token is owner-only" }
             : { name: "local-api-token", status: "fail", detail: `Local API token mode is ${tokenMode.toString(8)}; it must be 600` });
-    const signerOn = signerEnabled(env);
+    // The doctor normally runs inside the local dashboard process, while the
+    // uploader runs inside a separately installed launchd/systemd service. Its
+    // environment is intentionally not inherited by the dashboard. Inspecting
+    // this process's signer flag therefore produced the exact opposite of the
+    // truth on healthy machines. The daemon publishes its effective capability
+    // in the heartbeat; the local flag remains a compatibility fallback for a
+    // foreground `sealkeep doctor` invocation.
+    const daemonBeat = await readHeartbeat(dataDir);
+    const daemonLive = liveness(daemonBeat);
+    const daemonUploads = daemonLive.state !== "stopped" && daemonLive.state !== "never-started"
+        && daemonBeat?.capabilities?.uploads === true;
+    const signerOn = daemonUploads || signerEnabled(env);
     const credentials = config ? await loadProviderCredentials(dataDir, config.vaultId).then(() => true).catch(() => false) : false;
-    checks.push(!signerOn
-        ? { name: "signer", status: "warn", detail: "New archives aren't being uploaded from this machine right now. Anything already shown as verified in your storage is safely there. Turn on automatic archiving in Settings to resume uploads." }
-        : credentials
-            ? { name: "signer", status: "pass", detail: "Signer enabled and provider credentials are available from the secret store" }
-            : { name: "signer", status: "warn", detail: "Uploads are on, but this machine has no key for the bucket. Add the bucket's credentials on the storage step of setup." });
+    checks.push(waitingForPhrase
+        ? { name: "signer", status: "warn", detail: "Automatic uploads are waiting for this machine's recovery phrase; they will resume after you store it in Settings › Unlocking." }
+        : !signerOn
+            ? { name: "signer", status: "warn", detail: `${daemonLive.state === "late" ? "The background service has stopped checking in on time." : "Automatic uploads are not running on this machine."} Anything already shown as verified in your storage is safely there. Repair automatic uploads in Settings.` }
+            : managed || credentials
+                ? { name: "signer", status: "pass", detail: daemonUploads ? "The background service reports automatic uploads enabled." : "Uploads are enabled in this process and storage credentials are available." }
+                : { name: "signer", status: "warn", detail: "Uploads are on, but this machine has no usable sign-in for its configured storage. Reconnect that destination in Settings." });
     // Deliberately a standing warning: the envelope is unaudited, and no local check can change that.
     checks.push({ name: "crypto", status: "warn", detail: `Archive envelope v${ENVELOPE_VERSION} (${SUITES[0]}); implemented against published primitives and not independently audited` });
     return { ok: checks.every((check) => check.status !== "fail"), checks };

package/dist/src/durable-ticket-lock.d.ts

@@ -0,0 +1,24 @@
+export type DurableTicketLock = {
+    readonly queuePath: string;
+    readonly claimPath: string;
+    readonly ticket: string;
+    readonly token: string;
+    assertOwned(): Promise<void>;
+    release(): Promise<void>;
+};
+export type DurableTicketLockOptions = {
+    timeoutMs?: number;
+    pollMs?: number;
+    signal?: AbortSignal;
+    isProcessAlive?: (pid: number) => Promise<boolean>;
+};
+/**
+ * Cross-process FIFO lock without stale-owner unlink.
+ *
+ * Every contender atomically allocates a monotonically increasing immutable
+ * ticket. Released and dead-owner tickets stay as tiny tombstones, so no later
+ * process can recreate an older pathname or race a compare-then-unlink stale
+ * takeover. A dead process is skipped by later tickets; a malformed earlier
+ * ticket fails closed until an operator repairs it.
+ */
+export declare function acquireDurableTicketLock(requestedQueuePath: string, resource: string, options?: DurableTicketLockOptions): Promise<DurableTicketLock>;