gnosys 5.12.0 → 5.12.2

package/dist/lib/setup/sections/routing.js

@@ -78,14 +78,49 @@ export async function runRoutingSetup(opts) {
     console.log("");
     const choice = await askChoice(opts.rl, "What would you like to do?", [
         "Keep current routing (no changes)",
-        "Edit tasks — pick by number, then provider + model for each",
-        "Reset all task overrides to use default",
+        "Edit tasks — set the same provider + model for all tasks (simple global default)",
+        "Edit tasks — pick different providers/models for specific tasks (advanced)",
+        "Reset all task overrides to the current default (the one shown in the main setup summary)",
     ], 0);
     if (choice === 0) {
         console.log(`${DIM}No changes.${RESET}`);
         return false;
     }
-    if (choice === 2) {
+    if (choice === 1) {
+        // Edit tasks — set the same provider + model for all tasks (simple global default)
+        console.log("");
+        printStatus("progress", "setting a single default for all tasks…");
+        try {
+            const { fetchDynamicModels } = await import("../../setup.js");
+            const { pickModel } = await import("../../setup.js");
+            const dynamicModels = await fetchDynamicModels();
+            const currentModel = getProviderModel(cfg, provider);
+            const chosenModel = await pickModel(opts.rl, provider, dynamicModels, `Default model for ${provider} (used for all tasks + dream)`, currentModel);
+            if (chosenModel && chosenModel !== currentModel) {
+                const after = await loadConfig(storePath);
+                await updateConfig(storePath, {
+                    llm: {
+                        ...after.llm,
+                        [provider]: {
+                            ...(after.llm[provider] || {}),
+                            model: chosenModel,
+                        },
+                    },
+                    // Clear per-task overrides so everything truly uses the single default
+                    taskModels: {},
+                });
+                printStatus("ok", `default set for everything · ${provider} / ${chosenModel}`);
+            }
+            else {
+                printStatus("ok", "no change to the global default");
+            }
+        }
+        catch (err) {
+            printStatus("warn", "could not update default model", String(err));
+        }
+        return true;
+    }
+    if (choice === 3) {
         const { Diff } = await import("../ui/diff.js");
         const overridesBeingCleared = Object.entries(cfg.taskModels ?? {})
             .filter(([, v]) => v.provider !== provider || v.model !== model)
@@ -102,16 +137,18 @@ export async function runRoutingSetup(opts) {
         else {
             console.log(`${DIM}No overrides to clear — already using default everywhere.${RESET}`);
         }
-        const confirmReset = await askYesNo(opts.rl, "Reset all task overrides?", true);
+        console.log(`${DIM}The current default is ${provider} / ${model} (set via the main setup "Default provider" or the simple global option above).${RESET}`);
+        const confirmReset = await askYesNo(opts.rl, "Reset all task overrides to the current default?", true);
         if (!confirmReset) {
             console.log(`${DIM}Cancelled.${RESET}`);
             return false;
         }
         await updateConfig(storePath, { taskModels: {} });
-        printStatus("ok", "routing reset", "all tasks use default provider/model");
+        printStatus("ok", "routing reset", "all tasks now use the global default provider/model");
         console.log(Footer("press enter to return"));
         return true;
     }
+    // choice === 2 → advanced per-task editor (the powerful comma-list path)
     const patch = await runCommaListRoutingEditor(opts.rl, storePath, cfg);
     if (!patch) {
         return false;

package/dist/lib/setup/sections/taskRoutingEditor.d.ts

@@ -2,7 +2,7 @@
  * Comma-list task routing editor (provider + model per selected task).
  */
 import type { Interface as ReadlineInterface } from "readline/promises";
-import { type GnosysConfig } from "../../config.js";
+import type { GnosysConfig } from "../../config.js";
 /**
  * Let the user pick tasks by number, then provider + model for each.
  * Returns a patch for taskModels + dream, or null if cancelled.
@@ -11,7 +11,3 @@ export declare function runCommaListRoutingEditor(rl: ReadlineInterface, storePa
     taskModels: NonNullable<GnosysConfig["taskModels"]>;
     dream: GnosysConfig["dream"];
 } | null>;
-export declare function applyRoutingPatch(projectDir: string, patch: {
-    taskModels: NonNullable<GnosysConfig["taskModels"]>;
-    dream: GnosysConfig["dream"];
-}): Promise<GnosysConfig>;

package/dist/lib/setup/sections/taskRoutingEditor.js

@@ -1,9 +1,7 @@
 /**
  * Comma-list task routing editor (provider + model per selected task).
  */
-import { loadConfig, updateConfig, } from "../../config.js";
 import { ASSIGNABLE_TASK_LIST, fetchDynamicModels, getAssignableRouting, modelForTaskAssignment, parseCommaSeparatedTaskSelection, pickModel, pickProvider, TASK_DESCRIPTIONS, } from "../../setup.js";
-import { resolveActiveStorePath } from "../storePath.js";
 import { safeQuestion } from "../ui/safePrompt.js";
 import { renderProviderMark } from "../providerGlyphs.js";
 import { c, color, glyph } from "../ui/tokens.js";
@@ -139,11 +137,3 @@ export async function runCommaListRoutingEditor(rl, storePath, cfg) {
     }
     return { taskModels, dream };
 }
-export async function applyRoutingPatch(projectDir, patch) {
-    const storePath = resolveActiveStorePath(projectDir);
-    await updateConfig(storePath, {
-        taskModels: patch.taskModels,
-        dream: patch.dream,
-    });
-    return loadConfig(storePath);
-}

package/dist/lib/setup/ui/header.js

@@ -39,7 +39,6 @@ export function Header(crumbs, opts = {}) {
 }
 /** Strip ANSI escapes so we can measure printable width. Exported for callers/tests that need printable measurement. */
 export function stripAnsi(s) {
-    // eslint-disable-next-line no-control-regex
     return s.replace(/\x1b\[[0-9;]*m/g, "");
 }
 /** Convenience: print header + trailing blank line to stdout. */

package/dist/lib/setup/ui/status.d.ts

@@ -18,4 +18,3 @@ export type StatusKind = "ok" | "warn" | "fail" | "progress";
 export declare function Status(kind: StatusKind, text: string, meta?: string): string;
 /** Convenience: print a single status line. */
 export declare function printStatus(kind: StatusKind, text: string, meta?: string): void;
-export { MASTER_UNREACHABLE_MESSAGE, formatMemoriesWaitingToSync, formatFailedToSyncCount, formatOfflinePushStarting, renderClientSyncStatusLines, type ClientSyncStatusInput, } from "../remoteRender.js";

package/dist/lib/setup/ui/status.js

@@ -46,5 +46,3 @@ export function Status(kind, text, meta) {
 export function printStatus(kind, text, meta) {
     process.stdout.write(`${Status(kind, text, meta)}\n`);
 }
-// ─── v13 multi-machine sync (re-export render helpers for CLI/MCP callers) ─
-export { MASTER_UNREACHABLE_MESSAGE, formatMemoriesWaitingToSync, formatFailedToSyncCount, formatOfflinePushStarting, renderClientSyncStatusLines, } from "../remoteRender.js";

package/dist/lib/setup.d.ts

@@ -138,20 +138,6 @@ export declare function runSetup(opts: {
     directory?: string;
     nonInteractive?: boolean;
 }): Promise<SetupResult>;
-export interface ProviderOnlySetupOpts {
-    directory?: string;
-    rl?: ReadlineInterface;
-}
-/**
- * Update ONLY `llm.defaultProvider` in gnosys.json. Used by the summary
- * panel row 1 ("provider") so it stops dragging the user into the full
- * model picker — that's row 2's job.
- *
- * v5.9.4 Bug 4 — before this split, both summary rows routed through
- * `runModelsSetup`, leaving no way to swap provider without also choosing
- * a new model. Now row 1 picks a provider, row 2 picks a model.
- */
-export declare function runProviderOnlySetup(opts?: ProviderOnlySetupOpts): Promise<void>;
 /** Where validated keys are persisted (§3.10). */
 export type KeyPersistDestination = "secure" | "dotenv" | "none";
 /**
@@ -252,4 +238,3 @@ export declare function getApiKeyForProvider(provider: string, opts?: {
     task?: LlmTaskName;
     directory?: string;
 }): Promise<string>;
-export { getApiKeyForProviderFromConfig } from "./apiKeyVault.js";

package/dist/lib/setup.js

@@ -271,16 +271,6 @@ export async function fetchDynamicModels() {
         return {};
     }
 }
-/**
- * Get model tiers for a provider — tries dynamic first, falls back to hardcoded.
- */
-async function getModelTiers(provider) {
-    const dynamic = await fetchDynamicModels();
-    if (dynamic[provider] && dynamic[provider].length > 0) {
-        return dynamic[provider];
-    }
-    return PROVIDER_TIERS[provider] ?? [];
-}
 // ─── Provider display names and env var mapping ─────────────────────────────
 const PROVIDER_DISPLAY = {
     anthropic: "Anthropic (Claude)",
@@ -675,7 +665,7 @@ export async function detectIDEs(projectDir) {
  */
 export function upsertGrokMcpBlock(existing, name, entry) {
     // Drop mistaken v5.9.4 `[mcp.<name>]` sections so we don't leave dead config.
-    let content = removeTomlSection(existing, `[mcp.${name}]`);
+    const content = removeTomlSection(existing, `[mcp.${name}]`);
     const sectionHeader = `[mcp_servers.${name}]`;
     const lines = content.split("\n");
     const headerIdx = lines.findIndex((line) => line.trim() === sectionHeader);
@@ -779,7 +769,7 @@ export async function setupIDE(ide, projectDir) {
                 // 1. Strip legacy hand-written sections in ~/.codex/config.toml.
                 const userCodexConfig = path.join(os.homedir(), ".codex", "config.toml");
                 try {
-                    let existing = await fs.readFile(userCodexConfig, "utf-8");
+                    const existing = await fs.readFile(userCodexConfig, "utf-8");
                     const cleaned = removeTomlSection(removeTomlSection(existing, "[mcp.gnosys]"), "[gnosys]");
                     if (cleaned !== existing) {
                         await fs.writeFile(userCodexConfig, cleaned, "utf-8");
@@ -796,7 +786,7 @@ export async function setupIDE(ide, projectDir) {
                 let alreadyCorrect = false;
                 try {
                     const existing = runCli("codex", ["mcp", "get", "gnosys"], { allowFailure: true });
-                    if (existing && existing.includes(gnosysCmd) && !existing.includes(" serve")) {
+                    if (existing?.includes(gnosysCmd) && !existing.includes(" serve")) {
                         alreadyCorrect = true;
                     }
                     else if (existing) {
@@ -1439,8 +1429,7 @@ export async function runSetup(opts) {
                 const gnomeIdx = hasSecret ? idx++ : -1;
                 const envIdx = idx++;
                 const dotenvIdx = idx++;
-                const skipIdx = idx++;
-                // skipIdx is unused as a variable but documents the last index
+                idx++; // skip entry consumes the last index (value itself unused)
                 if (keyChoice === keychainIdx) {
                     // macOS Keychain — reuse existing key if available, otherwise ask
                     console.log();
@@ -1974,60 +1963,6 @@ export async function runSetup(opts) {
         throw err;
     }
 }
-/**
- * Update ONLY `llm.defaultProvider` in gnosys.json. Used by the summary
- * panel row 1 ("provider") so it stops dragging the user into the full
- * model picker — that's row 2's job.
- *
- * v5.9.4 Bug 4 — before this split, both summary rows routed through
- * `runModelsSetup`, leaving no way to swap provider without also choosing
- * a new model. Now row 1 picks a provider, row 2 picks a model.
- */
-export async function runProviderOnlySetup(opts = {}) {
-    const projectDir = opts.directory ? path.resolve(opts.directory) : process.cwd();
-    const ownsRl = !opts.rl;
-    const rl = opts.rl ?? createInterface({ input: stdin, output: stdout });
-    try {
-        const { Header } = await import("./setup/ui/header.js");
-        const { Title } = await import("./setup/ui/title.js");
-        const { Spinner } = await import("./setup/ui/spinner.js");
-        const { printStatus } = await import("./setup/ui/status.js");
-        console.log();
-        console.log(Header(["gnosys", "setup", "provider"]));
-        console.log();
-        console.log(Title("Default provider", "pick the LLM provider — model stays as configured"));
-        console.log();
-        const existingConfig = await loadExistingConfig(projectDir);
-        const currentProvider = existingConfig?.llm.defaultProvider;
-        const pricingSpin = Spinner("fetching latest pricing from openrouter…");
-        const fetchStart = Date.now();
-        const dynamicModels = await fetchDynamicModels();
-        const fetchMs = Date.now() - fetchStart;
-        if (Object.keys(dynamicModels).length > 0) {
-            pricingSpin.ok("pricing loaded", `${fetchMs} ms`);
-        }
-        else {
-            pricingSpin.fail("pricing fetch failed", "using bundled tiers");
-        }
-        console.log();
-        const provider = await pickProvider(rl, dynamicModels, "Choose your LLM provider", currentProvider);
-        if (!provider || provider === currentProvider) {
-            printStatus("warn", "no change · provider unchanged");
-            return;
-        }
-        const storePath = ensureActiveStorePath(projectDir);
-        const existingLlm = existingConfig?.llm ?? {};
-        await updateConfig(storePath, {
-            llm: { ...existingLlm, defaultProvider: provider },
-        });
-        printStatus("ok", `default provider · ${provider}`, `${storePath}/gnosys.json`);
-        printStatus("progress", "model unchanged", "use row 2 to swap the model");
-    }
-    finally {
-        if (ownsRl)
-            rl.close();
-    }
-}
 /**
  * Build API key requirements from the selected task set only (§3.7).
  * One global key per distinct cloud provider in the selection.
@@ -2142,7 +2077,6 @@ export async function promptKeyDestinationAndPersist(opts) {
         (await askChoice(opts.rl, "Where should I store this key?", options));
     const secureIdx = 0;
     const dotenvIdx = 1;
-    const noneIdx = 2;
     if (choice === secureIdx) {
         if (storeApiKeySecret(opts.service, opts.key, opts.provider)) {
             const store = process.platform === "darwin" ? "macOS Keychain" : "GNOME Keyring";
@@ -2571,84 +2505,6 @@ async function runModelsTaskRoutingSetup(ctx) {
     await updateConfig(storePath, updatePayload);
     printStatus("ok", `saved task routing · ${storePath}/gnosys.json`);
 }
-/**
- * Lightweight model-management command. Supports three operations:
- *   --list:    print available models for the current provider
- *   --refresh: clear the OpenRouter cache and re-fetch
- *   --set X:   update the default model in gnosys.json (no prompts)
- */
-async function runModelsCommand(opts = {}) {
-    const projectDir = opts.directory ? path.resolve(opts.directory) : process.cwd();
-    const existingConfig = await loadExistingConfig(projectDir);
-    const currentProvider = existingConfig?.llm.defaultProvider;
-    if (opts.refresh) {
-        const cacheFile = path.join(os.homedir(), ".config", "gnosys", "models-cache.json");
-        try {
-            await fs.unlink(cacheFile);
-            console.log(`${CHECK} Cache cleared.`);
-        }
-        catch {
-            console.log(`${DIM}No cache to clear.${RESET}`);
-        }
-    }
-    if (opts.list) {
-        if (!currentProvider) {
-            console.log(`${WARN} No provider configured. Run 'gnosys setup' first.`);
-            return;
-        }
-        console.log();
-        console.log(`${BOLD}Available models for ${currentProvider}:${RESET}`);
-        console.log();
-        const dynamicModels = await fetchDynamicModels();
-        const tiers = dynamicModels[currentProvider] ?? PROVIDER_TIERS[currentProvider] ?? [];
-        if (tiers.length === 0) {
-            console.log(`  ${DIM}No models in catalog. Try '--refresh' or use a custom model name.${RESET}`);
-            return;
-        }
-        for (const t of tiers) {
-            const rec = t.recommended ? `  ${CYAN}<- recommended${RESET}` : "";
-            const price = t.input === 0 && t.output === 0
-                ? "free"
-                : `$${t.input.toFixed(2)}–$${t.output.toFixed(2)}/M`;
-            console.log(`  ${t.name.padEnd(24)} ${t.model.padEnd(40)} ${DIM}${price}${RESET}${rec}`);
-        }
-        return;
-    }
-    if (opts.set) {
-        if (!currentProvider) {
-            console.log(`${WARN} No provider configured. Run 'gnosys setup' first.`);
-            return;
-        }
-        // v5.9.4 Bug 10 — unified store resolution.
-        const storePath = ensureActiveStorePath(projectDir);
-        const existingProviderConfig = existingConfig?.llm?.[currentProvider];
-        const providerConfigBase = (typeof existingProviderConfig === "object" && existingProviderConfig !== null)
-            ? existingProviderConfig
-            : {};
-        await updateConfig(storePath, {
-            llm: {
-                ...(existingConfig?.llm ?? {}),
-                defaultProvider: currentProvider,
-                [currentProvider]: { ...providerConfigBase, model: opts.set },
-            },
-        });
-        console.log(`${CHECK} Default model set to ${GREEN}${opts.set}${RESET} for ${currentProvider}.`);
-        return;
-    }
-    // No flags: show current config
-    if (!currentProvider) {
-        console.log(`${WARN} No provider configured. Run 'gnosys setup' first.`);
-        return;
-    }
-    const currentModel = existingConfig
-        ? getProviderModel(existingConfig, existingConfig.llm.defaultProvider)
-        : "";
-    console.log();
-    console.log(`Provider: ${GREEN}${currentProvider}${RESET}`);
-    console.log(`Model:    ${GREEN}${currentModel}${RESET}`);
-    console.log();
-    console.log(`${DIM}Use '--list' to see options, '--set <model>' to change, '--refresh' to update catalog.${RESET}`);
-}
 /**
  * Walks the user through configuring dream mode. Handles:
  *   - enable/disable
@@ -2857,23 +2713,23 @@ export async function runDreamSetup(opts = {}) {
         let discoverRelationships = dDiscover;
         if (editChoice === "e") {
             const idleAns = await askInput(rl, "idle minutes before triggering", { default: String(dIdle) });
-            idleMinutes = Math.max(1, parseInt(idleAns) || dIdle);
+            idleMinutes = Math.max(1, parseInt(idleAns, 10) || dIdle);
             const runtimeAns = await askInput(rl, "max runtime minutes", { default: String(dRuntime) });
-            maxRuntimeMinutes = Math.max(1, parseInt(runtimeAns) || dRuntime);
+            maxRuntimeMinutes = Math.max(1, parseInt(runtimeAns, 10) || dRuntime);
             const minMemAns = await askInput(rl, "minimum memories before activating", { default: String(dMinMem) });
-            minMemories = Math.max(1, parseInt(minMemAns) || dMinMem);
+            minMemories = Math.max(1, parseInt(minMemAns, 10) || dMinMem);
             const scheduleStartAns = await askInput(rl, "night window start hour (0-23)", { default: String(dScheduleStart) });
-            scheduleStartHour = Math.min(23, Math.max(0, parseInt(scheduleStartAns) || dScheduleStart));
+            scheduleStartHour = Math.min(23, Math.max(0, parseInt(scheduleStartAns, 10) || dScheduleStart));
             const scheduleEndAns = await askInput(rl, "night window end hour (0-23)", { default: String(dScheduleEnd) });
-            scheduleEndHour = Math.min(23, Math.max(0, parseInt(scheduleEndAns) || dScheduleEnd));
+            scheduleEndHour = Math.min(23, Math.max(0, parseInt(scheduleEndAns, 10) || dScheduleEnd));
             const systemIdleAns = await askInput(rl, "real machine idle minutes required", { default: String(dSystemIdle) });
-            systemIdleMinutes = Math.max(1, parseInt(systemIdleAns) || dSystemIdle);
+            systemIdleMinutes = Math.max(1, parseInt(systemIdleAns, 10) || dSystemIdle);
             const minNewAns = await askInput(rl, "minimum changed memories before dreaming", { default: String(dMinNewMemories) });
-            minNewMemoriesToDream = Math.max(0, parseInt(minNewAns) || dMinNewMemories);
+            minNewMemoriesToDream = Math.max(0, parseInt(minNewAns, 10) || dMinNewMemories);
             const minHoursAns = await askInput(rl, "minimum hours between successful dreams", { default: String(dMinHours) });
-            minHoursBetweenRuns = Math.max(0, parseInt(minHoursAns) || dMinHours);
+            minHoursBetweenRuns = Math.max(0, parseInt(minHoursAns, 10) || dMinHours);
             const maxCallsAns = await askInput(rl, "maximum LLM calls per dream run", { default: String(dMaxCalls) });
-            maxLLMCallsPerRun = Math.max(0, parseInt(maxCallsAns) || dMaxCalls);
+            maxLLMCallsPerRun = Math.max(0, parseInt(maxCallsAns, 10) || dMaxCalls);
             selfCritique = await askYesNo(rl, "self-critique (rule + LLM-based review flagging)", dSelfCritique);
             generateSummaries = await askYesNo(rl, "generate summaries (LLM)", dGenSummaries);
             discoverRelationships = await askYesNo(rl, "discover relationships (LLM)", dDiscover);
@@ -3009,4 +2865,3 @@ export async function getApiKeyForProvider(provider, opts) {
     }
     return readFirstInChain(provider) ?? "";
 }
-export { getApiKeyForProviderFromConfig } from "./apiKeyVault.js";

package/dist/lib/staleCommand.js

@@ -1,6 +1,6 @@
 export async function runStaleCommand(getResolver, opts) {
     const resolver = await getResolver();
-    const threshold = parseInt(opts.days);
+    const threshold = parseInt(opts.days, 10);
     const cutoff = new Date();
     cutoff.setDate(cutoff.getDate() - threshold);
     const cutoffStr = cutoff.toISOString().split("T")[0];
@@ -18,7 +18,7 @@ export async function runStaleCommand(getResolver, opts) {
             b.frontmatter.modified;
         return (aDate || "").localeCompare(bDate || "");
     })
-        .slice(0, parseInt(opts.limit));
+        .slice(0, parseInt(opts.limit, 10));
     if (stale.length === 0) {
         console.log(`No memories older than ${threshold} days.`);
         return;

package/dist/lib/syncClient.d.ts

@@ -33,15 +33,9 @@ export interface V13SyncStatus {
 }
 export declare function isMasterReachable(masterPath: string): boolean;
 export declare function countClientWaitingStaging(masterPath: string, machineId: string): number;
-/** Client should hide snapshot reads when master is unreachable (v13 offline rule). */
-export declare function shouldHideSnapshotReads(masterPath: string): boolean;
 export declare function listClientReceipts(masterPath: string, machineId: string): IngestReceipt[];
 export declare function getIngestedUlids(masterPath: string, machineId: string): Set<string>;
 export declare function openClientReadContext(localDb: GnosysDB, masterPath: string, machineId: string): ClientReadContext;
 /** Release snapshot/master DB handles opened by openClientReadContext. */
 export declare function closeClientReadContext(ctx: ClientReadContext): void;
-/**
- * @deprecated Use openClientReadContext — returns only the read DB without overlay or cleanup.
- */
-export declare function openClientReadDb(localDb: GnosysDB, masterPath: string): GnosysDB;
 export declare function getV13SyncStatus(localDb: GnosysDB): V13SyncStatus;

package/dist/lib/syncClient.js

@@ -6,7 +6,7 @@ import path from "path";
 import { GnosysDB } from "./db.js";
 import { readMachineConfig, getMachineId } from "./machineConfig.js";
 import { getConfiguredRemotePath } from "./remote.js";
-import { clientSnapshotStore, formatSnapshotAge, getClientAcceptedManifest, } from "./syncSnapshot.js";
+import { acceptClientSnapshot, clientSnapshotStore, compareSnapshotVersion, formatSnapshotAge, getClientAcceptedManifest, getMasterManifest, } from "./syncSnapshot.js";
 import { countFailedStagingFiles, machineStagingDir, stagingRoot } from "./syncStaging.js";
 import { renderClientSyncStatusLines, } from "./setup/remoteRender.js";
 const REACHABILITY_TTL_MS = 30_000;
@@ -53,10 +53,6 @@ export function countClientWaitingStaging(masterPath, machineId) {
         return 0;
     }
 }
-/** Client should hide snapshot reads when master is unreachable (v13 offline rule). */
-export function shouldHideSnapshotReads(masterPath) {
-    return !isMasterReachable(masterPath);
-}
 export function listClientReceipts(masterPath, machineId) {
     const dir = path.join(stagingRoot(masterPath), machineId, "receipts");
     if (!existsSync(dir))
@@ -92,7 +88,39 @@ export function openClientReadContext(localDb, masterPath, machineId) {
     const reachable = isMasterReachable(masterPath);
     const ingestedUlids = getIngestedUlids(masterPath, machineId);
     const pendingAdds = localDb.listActivePendingAdds().filter((p) => !ingestedUlids.has(p.id));
+    const store = clientSnapshotStore(masterPath);
+    const snapPath = path.join(store, "gnosys.db");
     if (reachable) {
+        // v13 completion (5.12.x): clients must not open the live gnosys.db over
+        // the network (concurrent master writes + network FS = torn-page hazard,
+        // DESIGN.md "The Simple Rule"). Refresh the verified local snapshot copy
+        // when the master has published a newer one, then read the local copy.
+        const manifest = getMasterManifest(masterPath);
+        if (manifest) {
+            const accepted = getClientAcceptedManifest(masterPath);
+            if (compareSnapshotVersion(accepted, manifest)) {
+                // Best effort — on checksum/copy failure we fall through to whatever
+                // local snapshot (or live-DB fallback) is still available.
+                acceptClientSnapshot(masterPath, manifest);
+            }
+            if (existsSync(snapPath)) {
+                const snapDb = new GnosysDB(store);
+                if (snapDb.isAvailable()) {
+                    return {
+                        db: snapDb,
+                        localDb,
+                        pendingOverlay: pendingAdds,
+                        source: "snapshot",
+                        masterReachable: true,
+                        ownsReadDb: true,
+                    };
+                }
+                snapDb.close();
+            }
+        }
+        // Compatibility fallback: master has never published a snapshot (older
+        // master version, or first sweep still pending) — open the live DB as
+        // before. Disappears once the master runs one publish-enabled sweep.
         const masterDb = new GnosysDB(masterPath);
         if (masterDb.isAvailable()) {
             return {
@@ -106,8 +134,9 @@ export function openClientReadContext(localDb, masterPath, machineId) {
         }
         masterDb.close();
     }
-    const store = clientSnapshotStore(masterPath);
-    const snapPath = path.join(store, "gnosys.db");
+    // Offline (soft rule, signed off 2026-06-11): the last-accepted snapshot
+    // stays readable — immutable + checksummed, and offline clients are
+    // add-only, so staleness is the only risk. Status surfaces snapshotAge.
     if (existsSync(snapPath)) {
         const snapDb = new GnosysDB(store);
         if (snapDb.isAvailable()) {
@@ -137,13 +166,6 @@ export function closeClientReadContext(ctx) {
         ctx.db.close();
     }
 }
-/**
- * @deprecated Use openClientReadContext — returns only the read DB without overlay or cleanup.
- */
-export function openClientReadDb(localDb, masterPath) {
-    const ctx = openClientReadContext(localDb, masterPath, getMachineId());
-    return ctx.db;
-}
 export function getV13SyncStatus(localDb) {
     const mc = readMachineConfig();
     const masterPath = getConfiguredRemotePath(localDb);

package/dist/lib/syncDoctorCommand.js

@@ -2,7 +2,7 @@ import { GnosysDB } from "./db.js";
 import { getConfiguredRemotePath } from "./remote.js";
 import { readMachineConfig } from "./machineConfig.js";
 import { getV13SyncStatus } from "./syncClient.js";
-import { runMasterIngestSweep } from "./syncIngest.js";
+import { runMasterIngestSweepAndPublish } from "./syncIngest.js";
 import { getSyncIngestTimerStatus } from "./syncIngestTimer.js";
 import { quarantineStaleTmpFiles, stagingRoot } from "./syncStaging.js";
 import { existsSync, readdirSync } from "fs";
@@ -48,7 +48,7 @@ export async function runSyncDoctorCommand(opts) {
                         quarantineStaleTmpFiles(masterPath, id);
                 }
             }
-            ingestResult = runMasterIngestSweep(masterPath, {
+            ingestResult = await runMasterIngestSweepAndPublish(masterPath, {
                 quiet: opts.quiet || !!opts.json,
             });
             if (ingestResult.errors.length > 0) {

package/dist/lib/syncIngest.d.ts

@@ -17,3 +17,14 @@ export interface IngestSweepOptions {
  * Always-on cheap ingest sweep (agent start + timer). Single-writer lock on local disk.
  */
 export declare function runMasterIngestSweep(masterPath: string, opts?: IngestSweepOptions): IngestSweepResult;
+/**
+ * v13 completion (5.12.x): sweep, then publish a fresh immutable snapshot
+ * when the sweep changed the DB (or none has ever been published). Clients
+ * read the published snapshot via a verified local copy instead of opening
+ * the live gnosys.db over the network — the hazard the design forbids.
+ *
+ * Kept separate from runMasterIngestSweep: publishMasterSnapshot acquires
+ * the same master-ingest lock, so it must run after the sweep releases it,
+ * and the sweep itself stays synchronous for existing callers.
+ */
+export declare function runMasterIngestSweepAndPublish(masterPath: string, opts?: IngestSweepOptions): Promise<IngestSweepResult>;

package/dist/lib/syncIngest.js

@@ -8,7 +8,7 @@ import { getGnosysHome } from "./paths.js";
 import { ensureMachineConfig } from "./machineConfig.js";
 import { listPendingStagingQueue, observeStagingFile, parseStagedFile, quarantineStagingFile, quarantineStaleTmpFiles, stagingRoot, verifyMemoryExistsInDb, } from "./syncStaging.js";
 import { assertMasterLeaseHeld, readMasterMarker, touchMasterMarkerHeartbeat, validateLeaseEpochBeforeWrite, } from "./masterLease.js";
-import { acquireWriteLockSync } from "./syncLock.js";
+import { acquireWriteLockSync, } from "./syncLock.js";
 const INGEST_LOCK_NAME = "master-ingest.lock";
 function payloadToMemory(p, now) {
     const contentHash = fnv1a(`${p.title}\n${p.content}`);
@@ -150,3 +150,26 @@ export function runMasterIngestSweep(masterPath, opts) {
     }
     return result;
 }
+/**
+ * v13 completion (5.12.x): sweep, then publish a fresh immutable snapshot
+ * when the sweep changed the DB (or none has ever been published). Clients
+ * read the published snapshot via a verified local copy instead of opening
+ * the live gnosys.db over the network — the hazard the design forbids.
+ *
+ * Kept separate from runMasterIngestSweep: publishMasterSnapshot acquires
+ * the same master-ingest lock, so it must run after the sweep releases it,
+ * and the sweep itself stays synchronous for existing callers.
+ */
+export async function runMasterIngestSweepAndPublish(masterPath, opts) {
+    const result = runMasterIngestSweep(masterPath, opts);
+    try {
+        const { getMasterManifest, publishMasterSnapshot } = await import("./syncSnapshot.js");
+        if (result.ingested > 0 || !getMasterManifest(masterPath)) {
+            await publishMasterSnapshot(masterPath);
+        }
+    }
+    catch (err) {
+        result.errors.push(`snapshot publish: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return result;
+}

package/dist/lib/syncIngestStartup.js

@@ -1,7 +1,7 @@
 import { GnosysDB } from "./db.js";
 import { readMachineConfig } from "./machineConfig.js";
 import { getConfiguredRemotePath } from "./remote.js";
-import { runMasterIngestSweep } from "./syncIngest.js";
+import { runMasterIngestSweepAndPublish } from "./syncIngest.js";
 /**
  * Run one ingest sweep on MCP server startup (master role only).
  * Non-blocking — callers should fire-and-forget.
@@ -22,7 +22,7 @@ export async function maybeRunStartupIngestSweep() {
     }
     if (!masterPath)
         return;
-    const result = runMasterIngestSweep(masterPath, { quiet: true });
+    const result = await runMasterIngestSweepAndPublish(masterPath, { quiet: true });
     if (result.errors.length > 0) {
         console.error(`[sync] Startup ingest sweep: ${result.ingested} ingested, ${result.errors.length} error(s)`);
     }

package/dist/lib/syncSnapshot.d.ts

@@ -11,6 +11,8 @@ export interface SnapshotManifestFile {
 }
 export declare function masterSnapshotsDir(masterPath: string): string;
 export declare function clientSnapshotStore(masterPath: string): string;
+/** Read the master's currently published snapshot manifest (null if none). */
+export declare function getMasterManifest(masterPath: string): SnapshotManifestFile | null;
 /** Publish a new immutable snapshot on the master (re-validates lease epoch first). */
 export declare function publishMasterSnapshot(masterPath: string): Promise<SnapshotManifestFile | null>;
 export declare function compareSnapshotVersion(accepted: {

package/dist/lib/syncSnapshot.js

@@ -34,6 +34,10 @@ function readManifestFile(masterPath) {
         return null;
     }
 }
+/** Read the master's currently published snapshot manifest (null if none). */
+export function getMasterManifest(masterPath) {
+    return readManifestFile(masterPath);
+}
 function writeManifestFile(masterPath, manifest) {
     const dir = masterSnapshotsDir(masterPath);
     mkdirSync(dir, { recursive: true });

package/dist/lib/syncStaging.d.ts

@@ -34,8 +34,6 @@ export type StagedFileParseResult = {
 };
 export declare function stagingRoot(masterPath: string): string;
 export declare function machineStagingDir(masterPath: string, machineId: string): string;
-/** Alias used by remoteWizard and tests. */
-export declare const stagingDirForMachine: typeof machineStagingDir;
 export declare function clientPresencePath(masterPath: string, machineId: string): string;
 export declare function failedQuarantineDir(masterPath: string, machineId: string): string;
 export declare function buildStagingFileName(memoryUlid: string, unixMs?: number): string;