gnosys 5.11.4 → 5.12.2

package/dist/lib/linksCommand.js

@@ -0,0 +1,48 @@
+import { getBacklinks, getOutgoingLinks } from "./wikilinks.js";
+function outputResult(json, data, humanFn) {
+    if (json) {
+        console.log(JSON.stringify(data, null, 2));
+    }
+    else {
+        humanFn();
+    }
+}
+export async function runLinksCommand(getResolver, memoryPath, opts) {
+    const resolver = await getResolver();
+    const memory = await resolver.readMemory(memoryPath);
+    if (!memory) {
+        console.error(`Memory not found: ${memoryPath}`);
+        process.exit(1);
+    }
+    const allMemories = await resolver.getAllMemories();
+    const outgoing = getOutgoingLinks(allMemories, memory.relativePath);
+    const backlinks = getBacklinks(allMemories, memory.relativePath);
+    outputResult(!!opts.json, {
+        memoryPath,
+        title: memory.frontmatter.title,
+        outgoing,
+        backlinks,
+    }, () => {
+        console.log(`Links for ${memory.frontmatter.title}:\n`);
+        if (outgoing.length > 0) {
+            console.log(`  Outgoing (${outgoing.length}):`);
+            for (const link of outgoing) {
+                const display = link.displayText ? ` (${link.displayText})` : "";
+                console.log(`    → [[${link.target}]]${display}`);
+            }
+        }
+        else {
+            console.log("  No outgoing links.");
+        }
+        console.log();
+        if (backlinks.length > 0) {
+            console.log(`  Backlinks (${backlinks.length}):`);
+            for (const link of backlinks) {
+                console.log(`    ← ${link.sourceTitle} (${link.sourcePath})`);
+            }
+        }
+        else {
+            console.log("  No backlinks.");
+        }
+    });
+}

package/dist/lib/listCommand.d.ts

@@ -0,0 +1,8 @@
+export type ListCommandOptions = {
+    category?: string;
+    tag?: string;
+    store?: string;
+    json?: boolean;
+    idFormat?: string;
+};
+export declare function runListCommand(opts: ListCommandOptions): Promise<void>;

package/dist/lib/listCommand.js

@@ -0,0 +1,74 @@
+import { logError } from "./log.js";
+import { findProjectIdentity } from "./projectIdentity.js";
+function outputResult(json, data, humanFn) {
+    if (json) {
+        console.log(JSON.stringify(data, null, 2));
+    }
+    else {
+        humanFn();
+    }
+}
+export async function runListCommand(opts) {
+    const { resolveClientRead, listMemoriesWithOverlay } = await import("./clientReadResolve.js");
+    const resolved = resolveClientRead();
+    if (!resolved) {
+        console.error("Central DB not available. Run 'gnosys init' first.");
+        process.exit(1);
+    }
+    try {
+        const projIdentity = await findProjectIdentity(process.cwd());
+        const projectId = projIdentity?.identity.projectId || null;
+        let memories = listMemoriesWithOverlay(resolved, (db) => db.getActiveMemories());
+        if (projectId) {
+            memories = memories.filter((m) => m.project_id === projectId || m.scope === "user" || m.scope === "global");
+        }
+        if (opts.store) {
+            memories = memories.filter((m) => m.scope === opts.store);
+        }
+        if (opts.category) {
+            memories = memories.filter((m) => m.category === opts.category);
+        }
+        if (opts.tag) {
+            memories = memories.filter((m) => {
+                try {
+                    const tags = JSON.parse(m.tags || "[]");
+                    return tags.includes(opts.tag);
+                }
+                catch {
+                    return false;
+                }
+            });
+        }
+        const { formatMemoryIdHyperlink: formatMemoryId, buildProjectNameLookup, parseIdFormat } = await import("./idFormat.js");
+        const idFormat = parseIdFormat(opts.idFormat);
+        const projectNames = buildProjectNameLookup(resolved.localDb);
+        outputResult(!!opts.json, {
+            count: memories.length,
+            memories: memories.map((m) => ({
+                id: m.id,
+                title: m.title,
+                category: m.category,
+                status: m.status,
+                scope: m.scope,
+                confidence: m.confidence,
+                project: m.project_id ? projectNames.get(m.project_id) || null : null,
+            })),
+        }, () => {
+            console.log(`${memories.length} memories:\n`);
+            for (const m of memories) {
+                const projectName = m.project_id ? projectNames.get(m.project_id) || null : null;
+                const displayId = formatMemoryId(m.id, projectName, idFormat);
+                console.log(`  [${m.scope}] [${m.status}] ${m.title}`);
+                console.log(`    id: ${displayId} | category: ${m.category} | confidence: ${m.confidence}`);
+                console.log();
+            }
+        });
+    }
+    catch (err) {
+        logError(err, { module: "cli", op: "list" });
+        process.exit(1);
+    }
+    finally {
+        resolved.release();
+    }
+}

package/dist/lib/llm.d.ts

@@ -45,7 +45,7 @@ export declare function getLLMProvider(config: GnosysConfig, task?: "structuring
 /**
  * Create a specific LLM provider instance.
  */
-export declare function createProvider(provider: LLMProviderName, model: string, config: GnosysConfig): LLMProvider;
+export declare function createProvider(provider: LLMProviderName, model: string, config: GnosysConfig, task?: "structuring" | "synthesis" | "vision" | "transcription" | "chat" | "dream"): LLMProvider;
 /**
  * Check if an LLM provider is available (has credentials / connectivity).
  * Returns { available: boolean; error?: string }.

package/dist/lib/llm.js

@@ -3,7 +3,7 @@
  * Supports Anthropic (cloud) and Ollama (local). Clean factory pattern enables
  * future providers (Groq, OpenAI, LM Studio) with zero changes to call sites.
  */
-import { DEFAULT_CONFIG, resolveTaskModel, getAnthropicApiKey, getOllamaBaseUrl, getGroqApiKey, getOpenAIApiKey, getOpenAIBaseUrl, getLMStudioBaseUrl, getXAIApiKey, getMistralApiKey, getCustomApiKey, getProviderModel, ALL_PROVIDERS, } from "./config.js";
+import { DEFAULT_CONFIG, resolveTaskModel, getAnthropicApiKey, getOllamaBaseUrl, getGroqApiKey, getOpenAIApiKey, getOpenAIBaseUrl, getLMStudioBaseUrl, getXAIApiKey, getMistralApiKey, getOpenRouterApiKey, getOpenRouterBaseUrl, getCustomApiKey, getProviderModel, ALL_PROVIDERS, } from "./config.js";
 import { withRetry, isTransientError } from "./retry.js";
 /** Per-request timeout for LLM generation calls (ms). */
 const LLM_TIMEOUT_MS = 60_000;
@@ -426,17 +426,17 @@ export function getLLMProvider(config, task) {
     const resolved = task
         ? resolveTaskModel(config, task)
         : { provider: config.llm.defaultProvider, model: getDefaultModel(config) };
-    return createProvider(resolved.provider, resolved.model, config);
+    return createProvider(resolved.provider, resolved.model, config, task);
 }
 /**
  * Create a specific LLM provider instance.
  */
-export function createProvider(provider, model, config) {
+export function createProvider(provider, model, config, task) {
     switch (provider) {
         case "anthropic": {
             const apiKey = getAnthropicApiKey(config);
             if (!apiKey) {
-                throw new Error("No Anthropic API key found. Set ANTHROPIC_API_KEY environment variable or add llm.anthropic.apiKey to gnosys.json.");
+                throw new Error("No Anthropic API key found. Set GNOSYS_GLOBAL_ANTHROPIC_KEY, GNOSYS_ANTHROPIC_KEY, or ANTHROPIC_API_KEY.");
             }
             return new AnthropicProvider(model, apiKey, config);
         }
@@ -447,14 +447,14 @@ export function createProvider(provider, model, config) {
         case "groq": {
             const apiKey = getGroqApiKey(config);
             if (!apiKey) {
-                throw new Error("No Groq API key found. Set GROQ_API_KEY environment variable or add llm.groq.apiKey to gnosys.json.");
+                throw new Error("No Groq API key found. Set GNOSYS_GLOBAL_GROQ_KEY, GNOSYS_GROQ_KEY, or GROQ_API_KEY.");
             }
             return new OpenAICompatibleProvider("groq", model, "https://api.groq.com/openai/v1", apiKey, config);
         }
         case "openai": {
             const apiKey = getOpenAIApiKey(config);
             if (!apiKey) {
-                throw new Error("No OpenAI API key found. Set OPENAI_API_KEY environment variable or add llm.openai.apiKey to gnosys.json.");
+                throw new Error("No OpenAI API key found. Set GNOSYS_GLOBAL_OPENAI_KEY, GNOSYS_OPENAI_KEY, or OPENAI_API_KEY.");
             }
             const baseUrl = getOpenAIBaseUrl(config);
             return new OpenAICompatibleProvider("openai", model, baseUrl, apiKey, config);
@@ -466,20 +466,28 @@ export function createProvider(provider, model, config) {
         case "xai": {
             const apiKey = getXAIApiKey(config);
             if (!apiKey) {
-                throw new Error("No xAI API key found. Set XAI_API_KEY environment variable or add llm.xai.apiKey to gnosys.json.");
+                throw new Error("No xAI API key found. Set GNOSYS_GLOBAL_XAI_KEY, GNOSYS_XAI_KEY, or XAI_API_KEY.");
             }
             return new OpenAICompatibleProvider("xai", model, "https://api.x.ai/v1", apiKey, config);
         }
         case "mistral": {
             const apiKey = getMistralApiKey(config);
             if (!apiKey) {
-                throw new Error("No Mistral API key found. Set MISTRAL_API_KEY environment variable or add llm.mistral.apiKey to gnosys.json.");
+                throw new Error("No Mistral API key found. Set GNOSYS_GLOBAL_MISTRAL_KEY, GNOSYS_MISTRAL_KEY, or MISTRAL_API_KEY.");
             }
             return new OpenAICompatibleProvider("mistral", model, "https://api.mistral.ai/v1", apiKey, config);
         }
+        case "openrouter": {
+            const apiKey = getOpenRouterApiKey(config);
+            if (!apiKey) {
+                throw new Error("No OpenRouter API key found. Set GNOSYS_GLOBAL_OPENROUTER_KEY, GNOSYS_OPENROUTER_KEY, or OPENROUTER_API_KEY.");
+            }
+            const baseUrl = getOpenRouterBaseUrl(config);
+            return new OpenAICompatibleProvider("openrouter", model, baseUrl, apiKey, config);
+        }
         case "custom": {
             const customConfig = config.llm.custom;
-            if (!customConfig || !customConfig.baseUrl || !customConfig.model) {
+            if (!customConfig?.baseUrl || !customConfig.model) {
                 throw new Error("Custom provider not configured. Set llm.custom.baseUrl and llm.custom.model in gnosys.json, or use: gnosys config set provider custom");
             }
             const apiKey = getCustomApiKey(config);
@@ -552,6 +560,16 @@ export function isProviderAvailable(config, provider) {
             }
             return { available: true };
         }
+        case "openrouter": {
+            const apiKey = getOpenRouterApiKey(config);
+            if (!apiKey) {
+                return {
+                    available: false,
+                    error: "No OPENROUTER_API_KEY set. Add to environment or gnosys.json.",
+                };
+            }
+            return { available: true };
+        }
         case "custom": {
             if (!config.llm.custom?.baseUrl || !config.llm.custom?.model) {
                 return {

package/dist/lib/localDiskCheck.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Best-effort local-disk detection for master folder setup (v13).
+ */
+export declare const LOCAL_DISK_ACK_PHRASE = "LOCAL DISK ONLY";
+export type LocalDiskCheckResult = {
+    verdict: "local";
+    message: string;
+} | {
+    verdict: "network";
+    message: string;
+} | {
+    verdict: "unknown";
+    message: string;
+};
+/** macOS: use `df` filesystem type; Linux: statfs not wired — treat as unknown. */
+export declare function checkMasterPathLocalDisk(folderPath: string): LocalDiskCheckResult;
+export declare function matchesLocalDiskAck(input: string): boolean;

package/dist/lib/localDiskCheck.js

@@ -0,0 +1,54 @@
+/**
+ * Best-effort local-disk detection for master folder setup (v13).
+ */
+import { execSync } from "child_process";
+import path from "path";
+export const LOCAL_DISK_ACK_PHRASE = "LOCAL DISK ONLY";
+/** macOS: use `df` filesystem type; Linux: statfs not wired — treat as unknown. */
+export function checkMasterPathLocalDisk(folderPath) {
+    const resolved = path.resolve(folderPath);
+    if (process.platform === "darwin") {
+        try {
+            const out = execSync(`df -T "${resolved}"`, { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] });
+            const line = out.trim().split("\n")[1] ?? "";
+            const fsType = line.split(/\s+/)[1]?.toLowerCase() ?? "";
+            const networkTypes = new Set([
+                "smbfs",
+                "nfs",
+                "afpfs",
+                "webdav",
+                "fuse",
+                "osxfuse",
+                "mntfs",
+            ]);
+            if (networkTypes.has(fsType)) {
+                return {
+                    verdict: "network",
+                    message: `Path appears to be on a network filesystem (${fsType}). Master DB must be on local disk.`,
+                };
+            }
+            if (fsType === "apfs" || fsType === "hfs" || fsType === "devfs") {
+                return { verdict: "local", message: `Path is on local disk (${fsType}).` };
+            }
+        }
+        catch {
+            // fall through to unknown
+        }
+    }
+    const lower = resolved.toLowerCase();
+    if (lower.includes("/volumes/") &&
+        !lower.includes("/volumes/macintosh hd") &&
+        !lower.startsWith("/users/")) {
+        return {
+            verdict: "unknown",
+            message: "Path is under /Volumes/ — could be an external or network volume. Cloud-sync folders (Dropbox, iCloud) also look local but corrupt SQLite.",
+        };
+    }
+    return {
+        verdict: "unknown",
+        message: "Could not verify this path is a plain local disk (not NAS, cloud-sync, or VPN mount).",
+    };
+}
+export function matchesLocalDiskAck(input) {
+    return input.trim() === LOCAL_DISK_ACK_PHRASE;
+}

package/dist/lib/lock.d.ts

@@ -29,4 +29,4 @@ export declare function acquireWriteLock(storePath: string, operation?: string):
  * unboundedly until something triggers a manual checkpoint — we observed
  * 4MB+ WAL files in the wild with no checkpoint cadence in v5.4.0.
  */
-export declare function enableWAL(db: any): void;
+export declare function enableWAL(db: any, busyTimeoutMs?: number): void;

package/dist/lib/lock.js

@@ -134,11 +134,13 @@ function isLockStale(lock) {
  * unboundedly until something triggers a manual checkpoint — we observed
  * 4MB+ WAL files in the wild with no checkpoint cadence in v5.4.0.
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function enableWAL(db) {
+export function enableWAL(db, busyTimeoutMs = 5000) {
     try {
         db.pragma("journal_mode = WAL");
-        db.pragma("busy_timeout = 5000"); // Wait up to 5s if DB is busy
+        // Single source of truth for the connection's busy timeout — callers on
+        // network shares (central DB) pass a longer value (10s) instead of
+        // overriding with a second pragma afterwards.
+        db.pragma(`busy_timeout = ${Math.max(0, Math.floor(busyTimeoutMs))}`);
         // Auto-checkpoint after every 1000 frames written to WAL. Default is
         // 1000 anyway in newer SQLite, but set explicitly so behavior is
         // predictable across SQLite versions.

package/dist/lib/machineConfig.d.ts

@@ -23,17 +23,27 @@
  * absolute path on a given machine is: `join(roots[root_id], rel_path)` (or a
  * per-machine override row for projects that live outside any root).
  */
+/** v13 multi-machine role for this machine (master writer vs staging client). */
+export type MultiMachineRole = "master" | "client";
 interface MachineRemoteConfig {
     /** Whether remote sync is configured/active on this machine. */
     enabled: boolean;
-    /** Absolute path or URL to the remote DB on this machine (NAS mount / Tailscale). */
+    /** Absolute path to the master folder as seen on this machine. */
     path?: string;
+    /** v13: whether this machine hosts the master DB or joins as a client. */
+    role?: MultiMachineRole;
 }
 export interface MachineConfig {
     /** Stable random UUID for this machine. Never shared/synced. */
     machineId: string;
     /** os.hostname() at write time — used to detect a synced-in foreign file. */
     hostname: string;
+    /**
+     * Earlier hostnames this same machine has used (most recent last). Lets the
+     * connected-machines registry prune the orphaned entry a rename leaves
+     * behind, so a renamed machine doesn't show up twice. Capped to a few.
+     */
+    previousHostnames?: string[];
     /** Named root → absolute path on THIS machine. */
     roots: Record<string, string>;
     /** Per-machine remote-sync connection. */

package/dist/lib/machineConfig.js

@@ -30,6 +30,8 @@ import { randomUUID } from "crypto";
 import { getMachineConfigPath } from "./paths.js";
 import { atomicWriteFileSync } from "./atomicWrite.js";
 const MACHINE_CONFIG_VERSION = 1;
+/** Keep the previous-hostname trail short — we only need it to prune aliases. */
+const MAX_PREVIOUS_HOSTNAMES = 5;
 /** A fresh machine config for the current host. */
 export function defaultMachineConfig() {
     return {
@@ -52,13 +54,21 @@ function normalize(parsed) {
                 roots[k] = path.resolve(v);
         }
     }
+    const role = parsed.remote?.role === "master" || parsed.remote?.role === "client"
+        ? parsed.remote.role
+        : undefined;
     const remote = {
         enabled: Boolean(parsed.remote?.enabled),
         ...(typeof parsed.remote?.path === "string" ? { path: parsed.remote.path } : {}),
+        ...(role ? { role } : {}),
     };
+    const previousHostnames = Array.isArray(parsed.previousHostnames)
+        ? parsed.previousHostnames.filter((h) => typeof h === "string" && h.length > 0)
+        : [];
     return {
         machineId: typeof parsed.machineId === "string" && parsed.machineId ? parsed.machineId : base.machineId,
         hostname: typeof parsed.hostname === "string" && parsed.hostname ? parsed.hostname : base.hostname,
+        ...(previousHostnames.length > 0 ? { previousHostnames } : {}),
         roots,
         remote,
         schemaVersion: typeof parsed.schemaVersion === "number" ? parsed.schemaVersion : MACHINE_CONFIG_VERSION,
@@ -108,10 +118,16 @@ export function ensureMachineConfig() {
         return { config: fresh, created: true, regenerated: false };
     }
     if (existing.hostname !== host) {
+        // Remember the old hostname (dedup, most-recent-last, capped) so the
+        // connected-machines registry can prune the entry it left orphaned.
+        const trail = (existing.previousHostnames ?? []).filter((h) => h !== existing.hostname && h !== host);
+        trail.push(existing.hostname);
+        const previousHostnames = trail.slice(-MAX_PREVIOUS_HOSTNAMES);
         const regenerated = {
             ...existing,
             machineId: randomUUID(),
             hostname: host,
+            previousHostnames,
         };
         writeMachineConfig(regenerated);
         return { config: regenerated, created: false, regenerated: true };

package/dist/lib/machineRegistry.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The "connected machines" registry — a small JSON blob stored under the
+ * `machines` key in the central DB's `gnosys_meta` table.
+ *
+ * Each machine records itself here whenever it runs `setup sync-projects`, so
+ * the upgrade flow can show which machines share the brain and what version
+ * each was last seen on.
+ *
+ * Historically this map was keyed by `os.hostname()` alone. That made it
+ * fragile: if a machine's hostname changed (e.g. macOS renames a laptop from
+ * `Edwards-MBP.localdomain` to `EdsMBP`), the machine started recording under
+ * the NEW name and the OLD entry was orphaned forever — a "phantom machine"
+ * that could never update or be cleaned up.
+ *
+ * The fix: every entry now also carries the stable `machineId` (from
+ * machine.json), and when a machine records itself it prunes any entry whose
+ * key matches one of its own previous hostnames (`aliases`). Renames therefore
+ * clean themselves up on the next sync. `forgetMachine` covers the one-time
+ * case of an already-orphaned phantom from before this tracking existed.
+ */
+import type { GnosysDB } from "./db.js";
+export interface MachineRegistryEntry {
+    /** Gnosys version this machine was last seen running (at last sync). */
+    version: string;
+    /** ISO timestamp of that last sync. */
+    lastSeen: string;
+    /**
+     * Stable machine id (machine.json). Optional because entries written by
+     * older versions predate this field; recorded going forward.
+     */
+    machineId?: string;
+}
+/** hostname → entry. */
+export type MachineRegistry = Record<string, MachineRegistryEntry>;
+/** Read and parse the registry, returning {} when absent or malformed. */
+export declare function readMachineRegistry(db: GnosysDB): MachineRegistry;
+/** Persist the registry as JSON. */
+export declare function writeMachineRegistry(db: GnosysDB, registry: MachineRegistry): void;
+export interface RecordMachineInput {
+    /** This machine's current hostname (os.hostname()). */
+    hostname: string;
+    /** Version to stamp for this machine. */
+    version: string;
+    /** Stable machine id from machine.json. */
+    machineId?: string;
+    /**
+     * Previous hostnames this same machine has used. Any registry entry under
+     * one of these names is removed — that's how a rename self-heals.
+     */
+    aliases?: string[];
+}
+/**
+ * Record this machine in the registry, pruning stale alias entries, and
+ * persist. Returns the updated registry.
+ */
+export declare function recordMachine(db: GnosysDB, input: RecordMachineInput): MachineRegistry;
+/**
+ * Remove a machine from the registry by hostname. Returns true if an entry was
+ * actually removed. Used by `gnosys machine forget` to clear a phantom.
+ */
+export declare function forgetMachine(db: GnosysDB, hostname: string): boolean;

package/dist/lib/machineRegistry.js

@@ -0,0 +1,80 @@
+/**
+ * The "connected machines" registry — a small JSON blob stored under the
+ * `machines` key in the central DB's `gnosys_meta` table.
+ *
+ * Each machine records itself here whenever it runs `setup sync-projects`, so
+ * the upgrade flow can show which machines share the brain and what version
+ * each was last seen on.
+ *
+ * Historically this map was keyed by `os.hostname()` alone. That made it
+ * fragile: if a machine's hostname changed (e.g. macOS renames a laptop from
+ * `Edwards-MBP.localdomain` to `EdsMBP`), the machine started recording under
+ * the NEW name and the OLD entry was orphaned forever — a "phantom machine"
+ * that could never update or be cleaned up.
+ *
+ * The fix: every entry now also carries the stable `machineId` (from
+ * machine.json), and when a machine records itself it prunes any entry whose
+ * key matches one of its own previous hostnames (`aliases`). Renames therefore
+ * clean themselves up on the next sync. `forgetMachine` covers the one-time
+ * case of an already-orphaned phantom from before this tracking existed.
+ */
+const REGISTRY_KEY = "machines";
+/** Read and parse the registry, returning {} when absent or malformed. */
+export function readMachineRegistry(db) {
+    try {
+        const raw = db.getMeta(REGISTRY_KEY);
+        if (!raw)
+            return {};
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Persist the registry as JSON. */
+export function writeMachineRegistry(db, registry) {
+    db.setMeta(REGISTRY_KEY, JSON.stringify(registry));
+}
+/**
+ * Record this machine in the registry, pruning stale alias entries, and
+ * persist. Returns the updated registry.
+ */
+export function recordMachine(db, input) {
+    const registry = readMachineRegistry(db);
+    // Drop any orphaned entries left behind by a previous hostname of THIS
+    // machine. Only this machine's own aliases are ever passed in, so this can
+    // never remove a different physical machine.
+    for (const alias of input.aliases ?? []) {
+        if (alias && alias !== input.hostname)
+            delete registry[alias];
+    }
+    // Also drop any other entry that shares our stable machineId but lives under
+    // a different hostname — covers a rename where the id was preserved.
+    if (input.machineId) {
+        for (const [host, entry] of Object.entries(registry)) {
+            if (host !== input.hostname && entry.machineId === input.machineId) {
+                delete registry[host];
+            }
+        }
+    }
+    registry[input.hostname] = {
+        version: input.version,
+        lastSeen: new Date().toISOString(),
+        ...(input.machineId ? { machineId: input.machineId } : {}),
+    };
+    writeMachineRegistry(db, registry);
+    return registry;
+}
+/**
+ * Remove a machine from the registry by hostname. Returns true if an entry was
+ * actually removed. Used by `gnosys machine forget` to clear a phantom.
+ */
+export function forgetMachine(db, hostname) {
+    const registry = readMachineRegistry(db);
+    if (!(hostname in registry))
+        return false;
+    delete registry[hostname];
+    writeMachineRegistry(db, registry);
+    return true;
+}

package/dist/lib/maintainCommand.d.ts

@@ -0,0 +1,8 @@
+import type { GnosysResolver } from "./resolver.js";
+type GetResolver = () => Promise<GnosysResolver>;
+export type MaintainCommandOptions = {
+    dryRun?: boolean;
+    autoApply?: boolean;
+};
+export declare function runMaintainCommand(getResolver: GetResolver, opts: MaintainCommandOptions): Promise<void>;
+export {};

package/dist/lib/maintainCommand.js

@@ -0,0 +1,34 @@
+import { loadConfig } from "./config.js";
+export async function runMaintainCommand(getResolver, opts) {
+    const { GnosysMaintenanceEngine, formatMaintenanceReport } = await import("./maintenance.js");
+    const resolver = await getResolver();
+    const stores = resolver.getStores();
+    if (stores.length === 0) {
+        console.error("No Gnosys stores found. Run gnosys init first.");
+        process.exit(1);
+    }
+    const cfg = await loadConfig(stores[0].path);
+    const engine = new GnosysMaintenanceEngine(resolver, cfg);
+    const report = await engine.maintain({
+        dryRun: opts.dryRun,
+        autoApply: opts.autoApply,
+        onLog: (level, message) => {
+            if (level === "warn") {
+                console.error(`⚠ ${message}`);
+            }
+            else if (level === "action") {
+                console.log(`→ ${message}`);
+            }
+            else {
+                console.log(message);
+            }
+        },
+        onProgress: (step, current, total) => {
+            process.stdout.write(`\r[${current}/${total}] ${step}...`);
+            if (current === total)
+                process.stdout.write("\n");
+        },
+    });
+    console.log("");
+    console.log(formatMaintenanceReport(report));
+}

package/dist/lib/masterLease.d.ts

@@ -0,0 +1,20 @@
+/**
+ * v13 master.json ownership marker — epoch-fenced lease on the master folder.
+ */
+export declare const MASTER_MARKER_FILE = "master.json";
+export interface MasterMarker {
+    epoch: number;
+    holderMachineId: string;
+    hostname: string;
+    updatedAt: string;
+}
+export declare function masterMarkerPath(masterPath: string): string;
+export declare function readMasterMarker(masterPath: string): MasterMarker | null;
+/** Bump epoch when claiming; reuse epoch+1 on stale takeover. */
+export declare function writeMasterMarker(masterPath: string, machineId: string, opts?: {
+    previousEpoch?: number;
+}): MasterMarker;
+/** Heartbeat refresh — same epoch, new updatedAt (transient write failures must not demote). */
+export declare function touchMasterMarkerHeartbeat(masterPath: string): MasterMarker | null;
+export declare function assertMasterLeaseHeld(masterPath: string, machineId: string): void;
+export declare function validateLeaseEpochBeforeWrite(masterPath: string, expectedEpoch: number, machineId: string): void;