sealkeep 0.9.0 → 0.11.1

package/dist/src/machine-settings.d.ts

@@ -0,0 +1,51 @@
+import type { AgentId } from "./adapters.js";
+import { type TrashResult } from "./trash.js";
+export type LocalSettings = {
+    version: 1;
+    deviceLabel: string;
+    watchedAgents: AgentId[];
+    /** Reserved for a future adapter-aware custom-root model; not exposed by the current UI. */
+    watchedPaths: string[];
+    exclusions: string[];
+    reclaimEnabled: boolean;
+    trashStrategy: "auto" | TrashResult["strategy"];
+    schedule: {
+        intervalMinutes: number;
+    };
+    /** Sustained aggregate background network limit in megabits/second. null = safe automatic limit. */
+    bandwidth: {
+        uploadLimitMbps: number | null;
+    };
+    /** MB the disk guard always leaves free. null = automatic. */
+    diskReserveMb: number | null;
+    /**
+     * How long a verified encrypted archive remains cached on this machine.
+     * This never applies to the original Codex/Claude transcript. null keeps
+     * every sealed copy locally; 0 lets a verified duplicate leave immediately.
+     */
+    localArchiveCacheDays: number | null;
+};
+/**
+ * True when an automatic watcher must leave this transcript alone.
+ *
+ * Entries without wildcards name either one file or a whole directory tree.
+ * Entries with `*`, `**`, or `?` use conventional path-glob semantics. This
+ * matcher is intentionally about transcript storage paths, not project cwd:
+ * the live watcher knows the former before it reads any transcript metadata.
+ */
+export declare function transcriptPathIsExcluded(path: string, exclusions: readonly string[], home?: string): boolean;
+/** One policy check shared by filesystem events, lifecycle hooks, and workers. */
+export declare function automaticTranscriptIsEnabled(settings: Pick<LocalSettings, "watchedAgents" | "exclusions">, agent: string, path: string, home?: string): boolean;
+/** Safe defaults: no deletion and no exclusion until the person asks. */
+export declare function defaultLocalSettings(): LocalSettings;
+/** Automatic work must not infer "unlimited" from an older settings file.
+ * 8 Mbps stays below common 10–20 Mbps uplinks while a large archive still
+ * makes steady progress. The local Settings page exposes this default. */
+export declare const DEFAULT_BACKGROUND_UPLOAD_LIMIT_MBPS = 8;
+export declare function backgroundUploadBytesPerSecond(settings: Pick<LocalSettings, "bandwidth">): number;
+export declare const localSettingsPath: (dataDir: string) => string;
+/** Missing/older fields inherit safe defaults; this file is preferences, not cryptographic state. */
+export declare function readLocalSettings(dataDir: string): Promise<LocalSettings>;
+/** Atomic and owner-only: per-machine preferences are never synced. */
+export declare function writeLocalSettings(dataDir: string, settings: LocalSettings): Promise<void>;
+export declare function resolvedTrashStrategy(settings: LocalSettings): TrashResult["strategy"];

package/dist/src/machine-settings.js

@@ -0,0 +1,166 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import { homedir, hostname } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { defaultStrategy } from "./trash.js";
+/**
+ * Turns a person-entered exclusion into the same absolute, slash-normalised
+ * shape used for transcript candidates. `~` is useful in a machine-local
+ * setting, and a relative entry is deliberately relative to that machine's
+ * home rather than to whichever directory happened to launch the daemon.
+ */
+function normaliseExclusion(value, home) {
+    const trimmed = value.trim();
+    const expanded = trimmed === "~"
+        ? home
+        : trimmed.startsWith("~/") || trimmed.startsWith("~\\")
+            ? join(home, trimmed.slice(2))
+            : trimmed;
+    return (isAbsolute(expanded) ? resolve(expanded) : resolve(home, expanded)).replaceAll("\\", "/");
+}
+function escapeRegexCharacter(character) {
+    return /[\\^$.*+?()[\]{}|]/.test(character) ? `\\${character}` : character;
+}
+/** A small path-only glob: `*` stays in one directory, `**` crosses them. */
+function globRegex(pattern) {
+    let source = "^";
+    for (let index = 0; index < pattern.length; index += 1) {
+        const character = pattern[index];
+        if (character === "*" && pattern[index + 1] === "*") {
+            index += 1;
+            // `foo/**/bar` also matches `foo/bar`; a plain terminal `/**` matches
+            // descendants, while the directory itself is handled by the prefix
+            // check in transcriptPathIsExcluded.
+            if (pattern[index + 1] === "/") {
+                index += 1;
+                source += "(?:.*/)?";
+            }
+            else {
+                source += ".*";
+            }
+        }
+        else if (character === "*") {
+            source += "[^/]*";
+        }
+        else if (character === "?") {
+            source += "[^/]";
+        }
+        else {
+            source += escapeRegexCharacter(character);
+        }
+    }
+    source += "$";
+    return new RegExp(source, process.platform === "win32" ? "i" : "");
+}
+/**
+ * True when an automatic watcher must leave this transcript alone.
+ *
+ * Entries without wildcards name either one file or a whole directory tree.
+ * Entries with `*`, `**`, or `?` use conventional path-glob semantics. This
+ * matcher is intentionally about transcript storage paths, not project cwd:
+ * the live watcher knows the former before it reads any transcript metadata.
+ */
+export function transcriptPathIsExcluded(path, exclusions, home = process.env.HOME ?? homedir()) {
+    const candidate = resolve(path).replaceAll("\\", "/");
+    const foldedCandidate = process.platform === "win32" ? candidate.toLowerCase() : candidate;
+    for (const raw of exclusions) {
+        if (!raw.trim())
+            continue;
+        const pattern = normaliseExclusion(raw, home).replace(/\/+$/, "");
+        if (!pattern)
+            continue;
+        if (/[*?]/.test(pattern)) {
+            if (globRegex(pattern).test(candidate))
+                return true;
+            // `/private/**` is normally understood to include the directory itself,
+            // which lets discovery prune that branch before walking its files.
+            if (pattern.endsWith("/**")) {
+                const directory = pattern.slice(0, -3);
+                const foldedDirectory = process.platform === "win32" ? directory.toLowerCase() : directory;
+                if (foldedCandidate === foldedDirectory)
+                    return true;
+            }
+            continue;
+        }
+        const foldedPattern = process.platform === "win32" ? pattern.toLowerCase() : pattern;
+        if (foldedCandidate === foldedPattern || foldedCandidate.startsWith(`${foldedPattern}/`))
+            return true;
+    }
+    return false;
+}
+/** One policy check shared by filesystem events, lifecycle hooks, and workers. */
+export function automaticTranscriptIsEnabled(settings, agent, path, home = process.env.HOME ?? homedir()) {
+    return (agent === "codex" || agent === "claude")
+        && settings.watchedAgents.includes(agent)
+        && !transcriptPathIsExcluded(path, settings.exclusions, home);
+}
+/** Safe defaults: no deletion and no exclusion until the person asks. */
+export function defaultLocalSettings() {
+    return {
+        version: 1,
+        deviceLabel: hostname(),
+        watchedAgents: ["codex", "claude"],
+        watchedPaths: [],
+        exclusions: [],
+        reclaimEnabled: false,
+        trashStrategy: "auto",
+        schedule: { intervalMinutes: 5 },
+        bandwidth: { uploadLimitMbps: null },
+        diskReserveMb: null,
+        // A week keeps recent memory restorable while offline without allowing a
+        // second, encrypted copy of the whole history to grow forever on disk.
+        localArchiveCacheDays: 7,
+    };
+}
+/** Automatic work must not infer "unlimited" from an older settings file.
+ * 8 Mbps stays below common 10–20 Mbps uplinks while a large archive still
+ * makes steady progress. The local Settings page exposes this default. */
+export const DEFAULT_BACKGROUND_UPLOAD_LIMIT_MBPS = 8;
+export function backgroundUploadBytesPerSecond(settings) {
+    const configured = settings.bandwidth.uploadLimitMbps;
+    const mbps = typeof configured === "number" && Number.isFinite(configured) && configured > 0
+        ? configured
+        : DEFAULT_BACKGROUND_UPLOAD_LIMIT_MBPS;
+    return mbps * 1_000_000 / 8;
+}
+export const localSettingsPath = (dataDir) => join(dataDir, "local-settings.json");
+/** Missing/older fields inherit safe defaults; this file is preferences, not cryptographic state. */
+export async function readLocalSettings(dataDir) {
+    const fallback = defaultLocalSettings();
+    try {
+        const saved = JSON.parse(await readFile(localSettingsPath(dataDir), "utf8"));
+        return {
+            ...fallback,
+            ...saved,
+            watchedAgents: Array.isArray(saved?.watchedAgents)
+                ? saved.watchedAgents.filter((agent) => agent === "codex" || agent === "claude")
+                : fallback.watchedAgents,
+            watchedPaths: Array.isArray(saved?.watchedPaths) ? saved.watchedPaths.filter((path) => typeof path === "string") : [],
+            exclusions: Array.isArray(saved?.exclusions) ? saved.exclusions.filter((path) => typeof path === "string") : [],
+            schedule: { ...fallback.schedule, ...saved?.schedule },
+            bandwidth: { ...fallback.bandwidth, ...saved?.bandwidth },
+            localArchiveCacheDays: saved?.localArchiveCacheDays === null
+                ? null
+                : typeof saved?.localArchiveCacheDays === "number"
+                    && Number.isFinite(saved.localArchiveCacheDays)
+                    && saved.localArchiveCacheDays >= 0
+                    && saved.localArchiveCacheDays <= 3650
+                    ? saved.localArchiveCacheDays
+                    : fallback.localArchiveCacheDays,
+        };
+    }
+    catch {
+        return fallback;
+    }
+}
+/** Atomic and owner-only: per-machine preferences are never synced. */
+export async function writeLocalSettings(dataDir, settings) {
+    await mkdir(dataDir, { recursive: true, mode: 0o700 });
+    const target = localSettingsPath(dataDir);
+    const temp = `${target}.${randomBytes(9).toString("hex")}.tmp`;
+    await writeFile(temp, JSON.stringify(settings, null, 2) + "\n", { mode: 0o600 });
+    await rename(temp, target);
+}
+export function resolvedTrashStrategy(settings) {
+    return settings.trashStrategy === "auto" ? defaultStrategy() : settings.trashStrategy;
+}

package/dist/src/managed-chunks.d.ts

@@ -1,4 +1,5 @@
 import { type ChunkStoreClient } from "./chunk-store.js";
+import { type ManagedDeleteContext } from "./cloud.js";
 /**
  * Managed chunk folders, Paul's way: no chunk support in the control plane at
  * all. The client already chunks — every sealed chunk is an ordinary file of
@@ -12,7 +13,7 @@ import { type ChunkStoreClient } from "./chunk-store.js";
  * the object's cloud reference is `<archiveId>.<name>`:
  *
  *   f0be…12af/chunk-000000   →  vault_ref  f0be…12af.chunk-000000
- *   f0be…12af/envelope.vlmeta →  vault_ref  f0be…12af.envelope.vlmeta
+ *   f0be…12af/envelope.skmeta →  vault_ref  f0be…12af.envelope.skmeta
  *
  * Deterministic both ways, so any machine of the vault re-derives every
  * reference from the archive id and the chunk count — no listing, no state.
@@ -52,4 +53,6 @@ export declare function collapseCloudRows<T extends CloudRowLike>(rows: T[]): (T
  * `pullCiphertext` hash-checks every read against the digest recorded at
  * upload before handing it back.
  */
-export declare function managedChunkClient(dataDir: string): ChunkStoreClient;
+export declare function managedChunkClient(dataDir: string, options?: {
+    deleteContext?: ManagedDeleteContext;
+}): ChunkStoreClient;

package/dist/src/managed-chunks.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { fail, isVaultlineError } from "./errors.js";
+import { fail, isSealkeepError } from "./errors.js";
 import { chunkObjectName, ENVELOPE_OBJECT } from "./chunk-store.js";
 import { completeUpload, deleteCloudArchive, pullCiphertext, putCiphertext, requestUpload, statCiphertext } from "./cloud.js";
 /**
@@ -15,7 +15,7 @@ import { completeUpload, deleteCloudArchive, pullCiphertext, putCiphertext, requ
  * the object's cloud reference is `<archiveId>.<name>`:
  *
  *   f0be…12af/chunk-000000   →  vault_ref  f0be…12af.chunk-000000
- *   f0be…12af/envelope.vlmeta →  vault_ref  f0be…12af.envelope.vlmeta
+ *   f0be…12af/envelope.skmeta →  vault_ref  f0be…12af.envelope.skmeta
  *
  * Deterministic both ways, so any machine of the vault re-derives every
  * reference from the archive id and the chunk count — no listing, no state.
@@ -44,7 +44,7 @@ export function managedChunkRefs(archiveId, chunkCount) {
     };
 }
 /** Recognises a cloud row that is one member of a chunk family, by its reference alone. */
-const FAMILY_REF = /^(.+)\.(chunk-\d{6}|envelope\.vlmeta)$/;
+const FAMILY_REF = /^(.+)\.(chunk-\d{6}|envelope\.skmeta)$/;
 /**
  * Folds chunk-family rows into one synthetic row per archive for listings:
  * the family's reference is the archive id, its bytes are the chunk sum (the
@@ -78,28 +78,28 @@ export function collapseCloudRows(rows) {
  * `pullCiphertext` hash-checks every read against the digest recorded at
  * upload before handing it back.
  */
-export function managedChunkClient(dataDir) {
+export function managedChunkClient(dataDir, options = {}) {
     return {
-        async putObject(key, body) {
+        async putObject(key, body, writeOptions = {}) {
             const ref = managedRefForKey(key);
             const digest = createHash("sha256").update(body).digest("hex");
-            const lease = await requestUpload(dataDir, { vaultRef: ref, ciphertextSha256: digest, bytes: body.length });
-            await putCiphertext(lease, body);
-            await completeUpload(dataDir, lease.lease_id, body.length);
+            const lease = await requestUpload(dataDir, { vaultRef: ref, ciphertextSha256: digest, bytes: body.length }, undefined, { signal: writeOptions.signal });
+            await putCiphertext(lease, body, writeOptions.signal);
+            await completeUpload(dataDir, lease.lease_id, body.length, undefined, { signal: writeOptions.signal });
             return { checksum: digest };
         },
-        async headObject(key) {
-            return statCiphertext(dataDir, managedRefForKey(key));
+        async headObject(key, readOptions = {}) {
+            return statCiphertext(dataDir, managedRefForKey(key), undefined, { signal: readOptions.signal });
         },
-        async getObject(key) {
-            return (await pullCiphertext(dataDir, managedRefForKey(key))).ciphertext;
+        async getObject(key, readOptions = {}) {
+            return (await pullCiphertext(dataDir, managedRefForKey(key), undefined, { signal: readOptions.signal })).ciphertext;
         },
         async deleteObject(key) {
             try {
-                await deleteCloudArchive(dataDir, managedRefForKey(key));
+                await deleteCloudArchive(dataDir, managedRefForKey(key), undefined, { context: options.deleteContext });
             }
             catch (error) {
-                if (isVaultlineError(error) && (error.code === "archive_not_found" || /returned 404|not[ _-]?found/i.test(error.message)))
+                if (isSealkeepError(error) && (error.code === "archive_not_found" || /returned 404|not[ _-]?found/i.test(error.message)))
                     return;
                 throw error;
             }

package/dist/src/mcp-install.d.ts

@@ -1,14 +1,17 @@
-import { execFile } from "node:child_process";
 import { type SetupAgentId } from "./adapters.js";
-declare const run: typeof execFile.__promisify__;
+/** Test seam for agent-owned installers (`which`/`where` and `claude mcp add`). */
+export type McpExec = (file: string, args: string[], options?: {
+    env?: NodeJS.ProcessEnv;
+}) => Promise<unknown>;
 /**
  * Registering Sealkeep's MCP server with the agents on this machine.
  *
  * Archiving sessions and being able to *ask about* them are different products,
  * and only the first one was wired. `src/mcp.ts` has always exposed
- * `vaultline_search` and `vaultline_recover`, but nothing installed it and
- * nothing told an agent it existed — a door with no sign on it. This is the
- * sign.
+ * `sealkeep_search` and `sealkeep_recover` (still answering to their original
+ * `vaultline_search` / `vaultline_recover` names too, for configs that already
+ * point at them), but nothing installed it and nothing told an agent it
+ * existed — a door with no sign on it. This is the sign.
  *
  * What is deliberately NOT here: any claim that an agent can reach archives it
  * does not hold locally. The MCP server searches this machine's index. A
@@ -36,17 +39,16 @@ export declare function mcpServerSpec(dataDir: string, executable?: string): {
 /**
  * Whether the command we are about to hand another program can actually be run.
  *
- * Registering `vaultline` when it is not on PATH — a checkout, an npx run, a
+ * Registering `sealkeep` when it is not on PATH — a checkout, an npx run, a
  * shell whose PATH the agent does not inherit — writes a server the agent
  * reports as "Failed to connect: ENOENT" forever, while this command claims
  * success. Reporting a registration that cannot start is the same false claim
  * as an archive that was never verified, and it is caught the same way: prove
  * it before saying it.
  */
-export declare function executableResolves(executable?: string, exec?: typeof execFile.__promisify__): Promise<boolean>;
+export declare function executableResolves(executable?: string, exec?: McpExec): Promise<boolean>;
 export declare function installMcpServer(dataDir: string, options?: {
     only?: string;
-    exec?: typeof run;
+    exec?: McpExec;
     home?: string;
 }): Promise<McpInstallResult>;
-export {};

package/dist/src/mcp-install.js

@@ -4,9 +4,13 @@ import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 import { promisify } from "node:util";
 import { detectSetupAgents } from "./adapters.js";
+import { PRODUCT_SLUG } from "./branding.js";
 const run = promisify(execFile);
+const execute = (file, args, options) => options?.env
+    ? run(file, args, { env: options.env })
+    : run(file, args);
 /** What every agent needs to start the server, in one place so the copies cannot drift. */
-export function mcpServerSpec(dataDir, executable = "vaultline") {
+export function mcpServerSpec(dataDir, executable = PRODUCT_SLUG) {
     return {
         command: executable,
         args: ["mcp"],
@@ -16,14 +20,14 @@ export function mcpServerSpec(dataDir, executable = "vaultline") {
 /**
  * Whether the command we are about to hand another program can actually be run.
  *
- * Registering `vaultline` when it is not on PATH — a checkout, an npx run, a
+ * Registering `sealkeep` when it is not on PATH — a checkout, an npx run, a
  * shell whose PATH the agent does not inherit — writes a server the agent
  * reports as "Failed to connect: ENOENT" forever, while this command claims
  * success. Reporting a registration that cannot start is the same false claim
  * as an archive that was never verified, and it is caught the same way: prove
  * it before saying it.
  */
-export async function executableResolves(executable = "vaultline", exec = run) {
+export async function executableResolves(executable = PRODUCT_SLUG, exec = execute) {
     try {
         await exec(process.platform === "win32" ? "where" : "which", [executable]);
         return true;
@@ -39,14 +43,14 @@ export async function executableResolves(executable = "vaultline", exec = run) {
  * installer then refused as foreign — the client normalises what it stores, so
  * a hand-written entry never matches what the client would have written.
  */
-async function installForClaude(dataDir, exec = run) {
+async function installForClaude(dataDir, exec = execute, home) {
     const spec = mcpServerSpec(dataDir);
     try {
         await exec("claude", [
-            "mcp", "add", "--transport", "stdio", "--scope", "user", "vaultline",
+            "mcp", "add", "--transport", "stdio", "--scope", "user", PRODUCT_SLUG,
             "--env", `SEALKEEP_DATA_DIR=${dataDir}`,
             "--", spec.command, ...spec.args
-        ]);
+        ], home ? { env: { ...process.env, HOME: home, USERPROFILE: home } } : undefined);
         return { installed: true, detail: "registered with Claude Code — ask it to search your sessions" };
     }
     catch (error) {
@@ -58,38 +62,77 @@ async function installForClaude(dataDir, exec = run) {
 }
 /**
  * Codex configures itself in TOML. This still ships no TOML *parser* — but it
- * does not need one to APPEND safely: a `[mcp_servers.vaultline]` table at the
+ * does not need one to APPEND safely: a `[mcp_servers.sealkeep]` table at the
  * end of the file is a new top-level table, valid TOML regardless of what
  * precedes it, as long as that section does not already exist. So the rule is:
+ * config file absent → create it exclusively with owner-only permissions;
  * config file present and section absent → back it up, append, registered;
- * anything else → the reviewable fragment, exactly as before. The backup makes
- * the edit as reversible as never having made it.
+ * section present → leave it alone. The backup makes an edit to an existing
+ * config as reversible as never having made it.
  */
-async function installForCodex(dataDir, home) {
+async function writeCodexFragment(dataDir) {
     const spec = mcpServerSpec(dataDir);
     const fragmentPath = join(dataDir, "integrations", "codex-mcp.toml");
     const table = [
-        "[mcp_servers.vaultline]",
+        `[mcp_servers.${PRODUCT_SLUG}]`,
         `command = ${JSON.stringify(spec.command)}`,
         `args = ${JSON.stringify(spec.args)}`,
         "",
-        "[mcp_servers.vaultline.env]",
+        `[mcp_servers.${PRODUCT_SLUG}.env]`,
         `SEALKEEP_DATA_DIR = ${JSON.stringify(dataDir)}`,
         ""
     ].join("\n");
     await mkdir(dirname(fragmentPath), { recursive: true });
-    await writeFile(fragmentPath, `# Merge into ~/.codex/config.toml to let Codex search your archived sessions.\n${table}`, { mode: 0o600 });
+    await writeFile(fragmentPath, `# Sealkeep MCP registration for Codex.\n${table}`, { mode: 0o600 });
+    return { fragmentPath, table };
+}
+async function installForCodex(dataDir, home) {
+    const { fragmentPath, table } = await writeCodexFragment(dataDir);
     const configPath = join(home ?? homedir(), ".codex", "config.toml");
-    const current = await readFile(configPath, "utf8").catch(() => null);
-    if (current === null) {
-        return { installed: false, detail: `Codex has no config.toml yet — merge this once it exists: ${fragmentPath}`, fragmentPath };
+    let current;
+    try {
+        current = await readFile(configPath, "utf8");
     }
-    if (current.includes("[mcp_servers.vaultline]")) {
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            const message = error instanceof Error ? error.message.split("\n")[0] : "unknown error";
+            return { installed: false, detail: `could not read ~/.codex/config.toml: ${message}`, fragmentPath };
+        }
+        await mkdir(dirname(configPath), { recursive: true, mode: 0o700 });
+        try {
+            // `wx` is the safety boundary: if Codex (or another setup process) creates
+            // the file after our read, never replace what it wrote.
+            await writeFile(configPath, table, { mode: 0o600, flag: "wx" });
+            return { installed: true, detail: "created ~/.codex/config.toml and registered the local Sealkeep MCP", fragmentPath };
+        }
+        catch (createError) {
+            if (createError.code !== "EEXIST") {
+                const message = createError instanceof Error ? createError.message.split("\n")[0] : "unknown error";
+                return { installed: false, detail: `could not create ~/.codex/config.toml: ${message}`, fragmentPath };
+            }
+            try {
+                current = await readFile(configPath, "utf8");
+            }
+            catch (raceError) {
+                const message = raceError instanceof Error ? raceError.message.split("\n")[0] : "unknown error";
+                return { installed: false, detail: `Codex created config.toml during setup, but Sealkeep could not read it: ${message}`, fragmentPath };
+            }
+        }
+    }
+    if (current.includes(`[mcp_servers.${PRODUCT_SLUG}]`)) {
         return { installed: true, detail: "already registered in ~/.codex/config.toml", fragmentPath };
     }
-    const backupPath = `${configPath}.vaultline-backup-${Date.now()}`;
+    /**
+     * A registration from before the rename names a command that no longer
+     * exists, so Codex fails to start it forever. Appending a good table beside
+     * it does not help — the dead one still errors on every launch — so the
+     * legacy block is REPLACED, not left to rot next to its replacement.
+     */
+    const legacy = /\[mcp_servers\.vaultline(?:\.env)?\][^[]*/g;
+    const cleaned = current.replace(legacy, "").replace(/\n{3,}/g, "\n\n");
+    const backupPath = `${configPath}.${PRODUCT_SLUG}-backup-${Date.now()}`;
     await writeFile(backupPath, current, { mode: 0o600 });
-    await writeFile(configPath, `${current}${current.endsWith("\n") ? "" : "\n"}\n${table}`, { mode: 0o600 });
+    await writeFile(configPath, `${cleaned}${cleaned.endsWith("\n") ? "" : "\n"}\n${table}`, { mode: 0o600 });
     return { installed: true, detail: `registered in ~/.codex/config.toml (backup kept beside it)`, fragmentPath, backupPath };
 }
 export async function installMcpServer(dataDir, options = {}) {
@@ -104,8 +147,8 @@ export async function installMcpServer(dataDir, options = {}) {
      * there. A fragment is inert until someone merges it deliberately, so
      * withholding it would only remove information.
      */
-    const runnable = await executableResolves("vaultline", options.exec);
-    const notOnPath = "`vaultline` is not on PATH, so the server could not start. Install it globally (npm i -g vaultline) and run this again.";
+    const runnable = await executableResolves(PRODUCT_SLUG, options.exec);
+    const notOnPath = "The `sealkeep` executable is not on PATH, so the MCP server could not start. Install it globally (`npm i -g sealkeep`), then reopen Setup.";
     for (const found of detected) {
         if (!found.detected)
             continue;
@@ -113,18 +156,20 @@ export async function installMcpServer(dataDir, options = {}) {
             continue;
         if (found.agent === "claude") {
             agents.push(runnable
-                ? { agent: found.agent, label: found.label, ...(await installForClaude(dataDir, options.exec)) }
+                ? { agent: found.agent, label: found.label, ...(await installForClaude(dataDir, options.exec, options.home)) }
                 : { agent: found.agent, label: found.label, installed: false, detail: `not registered — ${notOnPath}` });
         }
         else if (found.agent === "codex") {
             // A registration that cannot start is worse than none (same rule as
-            // Claude): only a runnable `vaultline` earns the config append; without
+            // Claude): only a runnable `sealkeep` earns the config append; without
             // it the fragment is written and the advice says why.
-            const fragment = runnable
-                ? await installForCodex(dataDir, options.home)
-                : await installForCodex(dataDir, "/nonexistent-home-so-only-the-fragment-is-written");
-            agents.push({ ...fragment, agent: found.agent, label: found.label,
-                detail: runnable ? fragment.detail : `not registered — ${notOnPath}`, installed: runnable ? fragment.installed : false });
+            if (runnable) {
+                agents.push({ ...(await installForCodex(dataDir, options.home)), agent: found.agent, label: found.label });
+            }
+            else {
+                const { fragmentPath } = await writeCodexFragment(dataDir);
+                agents.push({ agent: found.agent, label: found.label, fragmentPath, installed: false, detail: `not registered — ${notOnPath}` });
+            }
         }
         else {
             // Detected, but Sealkeep has no adapter for its sessions, so an MCP

package/dist/src/mcp-workspace.d.ts

@@ -0,0 +1,18 @@
+import type { TeamSpaceBinding } from "./vault.js";
+type Selection = {
+    project: string;
+    projectKey: string;
+};
+export type WorkspaceSelection = Selection | {
+    note: string;
+    candidates: Selection[];
+};
+/** Roots are authoritative when supported. No label or last-used-project fallback. */
+export declare function resolveMcpWorkspace(input: {
+    roots?: readonly {
+        uri: string;
+    }[];
+    cwd: string;
+    bindings: Record<string, TeamSpaceBinding>;
+}): Promise<WorkspaceSelection>;
+export {};

package/dist/src/mcp-workspace.js

@@ -0,0 +1,50 @@
+import { realpath, stat } from "node:fs/promises";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { projectFromCwd } from "./adapters.js";
+/** Roots are authoritative when supported. No label or last-used-project fallback. */
+export async function resolveMcpWorkspace(input) {
+    const candidates = Object.entries(input.bindings).flatMap(([projectKey, binding]) => /^(g1|p1):[a-f0-9]{64}$/.test(projectKey) && binding.localConfirmed && binding.localProject
+        ? [{ project: binding.localProject, projectKey }] : []);
+    const hint = () => ({
+        note: "Workspace scope could not be resolved to one confirmed project. Supply project and projectKey from a confirmed checkout, or scope: account for an explicitly account-wide search.",
+        candidates,
+    });
+    try {
+        const paths = input.roots === undefined ? [input.cwd] : input.roots.map(({ uri }) => {
+            const url = new URL(uri);
+            if (url.protocol !== "file:" || url.search || url.hash)
+                throw new Error("invalid workspace root");
+            return fileURLToPath(url);
+        });
+        if (!paths.length || paths.length > 32)
+            return hint();
+        const canonical = [...new Set(await Promise.all(paths.map(async (path) => {
+                const resolved = await realpath(path);
+                if (!(await stat(resolved)).isDirectory())
+                    throw new Error("workspace is not a folder");
+                return resolved;
+            })))];
+        // Duplicate representations of one root are harmless; multiple folders are
+        // not evidence of which one the current tool call concerns.
+        if (canonical.length !== 1)
+            return hint();
+        let current = canonical[0];
+        // Never fall through an unconfirmed nested repository into its parent repo.
+        const gitRoot = await promisify(execFile)("git", ["-C", current, "rev-parse", "--show-toplevel"], { timeout: 2000, maxBuffer: 64 * 1024 }).then(async ({ stdout }) => realpath(stdout.trim()), () => null);
+        for (let depth = 0; depth < 64; depth++) {
+            const identity = await projectFromCwd(current);
+            const match = candidates.find((candidate) => candidate.projectKey === identity.projectKey);
+            if (match)
+                return match;
+            const parent = dirname(current);
+            if (current === gitRoot || parent === current)
+                break;
+            current = parent;
+        }
+    }
+    catch { /* unavailable/unknown roots must not widen the search */ }
+    return hint();
+}