gnosys 5.12.0 → 5.12.3

package/dist/lib/docxExtract.js

@@ -30,7 +30,7 @@ export async function extractDocxText(filePath) {
     await assertDocxDecompressedSizeWithinLimit(buffer);
     const result = await mammoth.convertToHtml({ buffer });
     const html = result.value;
-    if (!html || !html.trim()) {
+    if (!html?.trim()) {
         return [];
     }
     // Convert HTML to markdown

package/dist/lib/dream.d.ts

@@ -107,6 +107,14 @@ export declare class GnosysDreamEngine {
     private providerInitError;
     private createPhase;
     private finishPhase;
+    /**
+     * v5.12.1 crash safety: persist analyzed fingerprints at every phase
+     * boundary, not only in finalize(). A crash mid-run previously lost all
+     * pendingFingerprints, so the next run re-analyzed (and re-paid for) the
+     * same memory sets and could double-create summaries. Checkpointing only
+     * merges fingerprints — lastRunAt / watermarks remain finalize()'s job.
+     */
+    private checkpointFingerprints;
     private addTouched;
     private recordLLMSkip;
     private llmCalls;

package/dist/lib/dream.js

@@ -23,7 +23,7 @@ import { createProvider } from "./llm.js";
 import { notifyDesktop } from "./desktopNotify.js";
 import { syncConfidenceToDb, auditToDb } from "./dbWrite.js";
 import { logError } from "./log.js";
-import { estimateCost, estimateTokens, fingerprintMemories, memoryWatermark, readDreamState, writeDreamState, } from "./dreamRunLog.js";
+import { estimateCost, acquireDreamLock, estimateTokens, fingerprintMemories, memoryWatermark, readDreamState, writeDreamState, } from "./dreamRunLog.js";
 /** Layer 4 alert threshold: fire desktop notification at this many consecutive provider failures. */
 const DREAM_FAILURE_NOTIFY_THRESHOLD = 3;
 export const DEFAULT_DREAM_CONFIG = {
@@ -109,6 +109,30 @@ export class GnosysDreamEngine {
         phase.durationMs = Date.now() - startedAtMs;
         phase.memoryIdsTouched = Array.from(new Set(phase.memoryIdsTouched));
         phase.estimatedCostUsd = Math.round(phase.estimatedCostUsd * 1_000_000) / 1_000_000;
+        this.checkpointFingerprints();
+    }
+    /**
+     * v5.12.1 crash safety: persist analyzed fingerprints at every phase
+     * boundary, not only in finalize(). A crash mid-run previously lost all
+     * pendingFingerprints, so the next run re-analyzed (and re-paid for) the
+     * same memory sets and could double-create summaries. Checkpointing only
+     * merges fingerprints — lastRunAt / watermarks remain finalize()'s job.
+     */
+    checkpointFingerprints() {
+        if (Object.keys(this.pendingFingerprints).length === 0)
+            return;
+        try {
+            writeDreamState({
+                ...this.dreamState,
+                analyzedFingerprints: {
+                    ...this.dreamState.analyzedFingerprints,
+                    ...this.pendingFingerprints,
+                },
+            });
+        }
+        catch {
+            // Best-effort: a failed checkpoint only costs re-analysis on resume.
+        }
     }
     addTouched(phase, memoryIds) {
         for (const id of memoryIds) {
@@ -986,6 +1010,15 @@ export class DreamScheduler {
         const idleMs = Date.now() - this.lastActivity;
         const idleMinutes = idleMs / 60_000;
         if (idleMinutes >= this.config.idleMinutes) {
+            // v5.12.1: the in-memory `running` flag does not survive a sandbox
+            // restart and cannot see a concurrent manual `gnosys dream`. Tie the
+            // scheduler to the same cross-process file lock the CLI uses.
+            const lock = acquireDreamLock();
+            if (!lock.acquired) {
+                console.error(`[dream] scheduler skipped: ${lock.reason}`);
+                this.lastActivity = Date.now(); // back off a full idle window
+                return;
+            }
             this.running = true;
             try {
                 this.currentDream = this.engine.dream((phase, detail) => {
@@ -1002,6 +1035,7 @@ export class DreamScheduler {
                 this.running = false;
                 this.currentDream = null;
                 this.lastActivity = Date.now(); // Reset idle timer after dream
+                lock.release();
             }
         }
     }

package/dist/lib/dreamLogCommand.js

@@ -8,7 +8,7 @@ export async function runDreamLogCommand(opts, context = {}) {
             process.exitCode = 1;
             return;
         }
-        const limit = Math.max(1, parseInt(opts.last) || 20);
+        const limit = Math.max(1, parseInt(opts.last, 10) || 20);
         const sinceIso = opts.since ? `${opts.since}T00:00:00Z` : undefined;
         const runs = centralDb.getRecentDreamRuns(limit, {
             failuresOnly: !!opts.failuresOnly,

package/dist/lib/dreamRunLog.d.ts

@@ -88,7 +88,7 @@ export interface DreamReadOptions {
 export declare function getDreamRunsPath(): string;
 export declare function getDreamStatePath(): string;
 export declare function getDreamLockPath(): string;
-export declare function acquireDreamLock(): {
+export declare function acquireDreamLock(depth?: number): {
     acquired: true;
     release: () => void;
 } | {

package/dist/lib/dreamRunLog.js

@@ -26,7 +26,7 @@ export function getDreamStatePath() {
 export function getDreamLockPath() {
     return path.join(getGnosysHome(), "dream.lock");
 }
-export function acquireDreamLock() {
+export function acquireDreamLock(depth = 0) {
     const lockPath = getDreamLockPath();
     fs.mkdirSync(path.dirname(lockPath), { recursive: true });
     try {
@@ -46,17 +46,39 @@ export function acquireDreamLock() {
         };
     }
     catch {
+        // Bounded retries so stale-lock cleanup can't recurse forever under
+        // genuine contention (two processes racing to re-acquire).
+        if (depth >= 3) {
+            return { acquired: false, reason: "dream lock contention" };
+        }
+        let raw;
+        try {
+            raw = fs.readFileSync(lockPath, "utf8");
+        }
+        catch {
+            // Lock vanished between our create attempt and this read — retry.
+            return acquireDreamLock(depth + 1);
+        }
         try {
-            const raw = fs.readFileSync(lockPath, "utf8");
             const parsed = JSON.parse(raw);
             if (parsed.pid && !isProcessRunning(parsed.pid)) {
                 fs.unlinkSync(lockPath);
-                return acquireDreamLock();
+                return acquireDreamLock(depth + 1);
             }
             return { acquired: false, reason: `dream already running (pid ${parsed.pid || "unknown"})` };
         }
         catch {
-            return { acquired: false, reason: "dream already running (lock exists)" };
+            // v5.12.1: unreadable/corrupt lock (crash mid-write) previously blocked
+            // dreaming forever until manual deletion. Treat it as stale: the lock
+            // payload is a single tiny write, so a live owner with a corrupt lock
+            // is implausible.
+            try {
+                fs.unlinkSync(lockPath);
+            }
+            catch {
+                // ignore — next acquire retries
+            }
+            return acquireDreamLock(depth + 1);
         }
     }
 }

package/dist/lib/embeddings.js

@@ -5,7 +5,6 @@
  * Embeddings are stored in SQLite as regeneratable sidecar data.
  */
 // Dynamic import — gracefully handles missing native module (dlopen failures)
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
 let Database = null;
 try {
     Database = (await import("better-sqlite3")).default;
@@ -17,10 +16,8 @@ import path from "path";
 import fs from "fs/promises";
 import { enableWAL } from "./lock.js";
 const MODEL_NAME = "Xenova/all-MiniLM-L6-v2";
-const EMBEDDING_DIM = 384;
 export class GnosysEmbeddings {
     pipeline = null;
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     db = null;
     storePath;
     modelReady = false;

package/dist/lib/exportProject.d.ts

@@ -14,9 +14,10 @@ interface BundleManifest {
     source_user: string;
     gnosys_version: string;
 }
-/** A memory row with its embedding base64-encoded for JSON transport. */
-export interface PortableMemory extends Omit<DbMemory, "embedding"> {
+/** A memory row with its binary columns base64-encoded for JSON transport. */
+export interface PortableMemory extends Omit<DbMemory, "embedding" | "attachment_data"> {
     embedding_b64: string | null;
+    attachment_data_b64: string | null;
 }
 export interface ProjectBundle {
     manifest: BundleManifest;

package/dist/lib/exportProject.js

@@ -34,10 +34,11 @@ export function exportProject(db, opts) {
     const totalIncludingArchived = db.getMemoriesByProject(opts.projectId, true).length;
     const archivedExcluded = opts.includeArchived ? 0 : totalIncludingArchived - rawMemories.length;
     const memories = rawMemories.map((m) => {
-        const { embedding: _embedding, ...rest } = m;
+        const { embedding: _embedding, attachment_data: _attachment, ...rest } = m;
         return {
             ...rest,
             embedding_b64: m.embedding ? Buffer.from(m.embedding).toString("base64") : null,
+            attachment_data_b64: m.attachment_data ? Buffer.from(m.attachment_data).toString("base64") : null,
         };
     });
     const memoryIds = rawMemories.map((m) => m.id);

package/dist/lib/federated.js

@@ -132,7 +132,7 @@ export function detectAmbiguity(db, query, opts) {
     const projectHits = new Map();
     for (const r of results) {
         const mem = db.getMemory(r.id);
-        if (!mem || !mem.project_id)
+        if (!mem?.project_id)
             continue;
         projectHits.set(mem.project_id, (projectHits.get(mem.project_id) || 0) + 1);
     }

package/dist/lib/ftsQuery.d.ts

@@ -0,0 +1,25 @@
+/**
+ * FTS5 MATCH query construction — shared by the central-DB search (db.ts),
+ * the per-store search index (search.ts), and archive search (archive.ts).
+ *
+ * FTS5 treats space-separated bare terms as implicit AND, so the long
+ * descriptive queries the tool docs encourage ("auth JWT session tokens
+ * refresh") return zero results unless EVERY term matches. Callers use
+ * these helpers to try AND first (precision), then retry with OR
+ * (recall) when AND finds nothing — BM25 still ranks the best-covered
+ * memories first in the OR pass.
+ *
+ * Every term is emitted as a quoted phrase, which also makes previously
+ * syntax-error-prone input (hyphens, colons, FTS5 keywords like NOT)
+ * safe. A trailing `*` is preserved as an FTS5 prefix query (`"term"*`).
+ */
+/**
+ * Split a raw query into sanitized terms. Drops quote characters and any
+ * token with no letters or digits (pure punctuation can't match anything
+ * under the unicode61 tokenizer).
+ */
+export declare function ftsTerms(query: string): string[];
+/** Implicit-AND MATCH expression: all terms must match. */
+export declare function ftsAndQuery(terms: string[]): string;
+/** OR MATCH expression: any term may match; BM25 ranks fuller matches higher. */
+export declare function ftsOrQuery(terms: string[]): string;

package/dist/lib/ftsQuery.js

@@ -0,0 +1,42 @@
+/**
+ * FTS5 MATCH query construction — shared by the central-DB search (db.ts),
+ * the per-store search index (search.ts), and archive search (archive.ts).
+ *
+ * FTS5 treats space-separated bare terms as implicit AND, so the long
+ * descriptive queries the tool docs encourage ("auth JWT session tokens
+ * refresh") return zero results unless EVERY term matches. Callers use
+ * these helpers to try AND first (precision), then retry with OR
+ * (recall) when AND finds nothing — BM25 still ranks the best-covered
+ * memories first in the OR pass.
+ *
+ * Every term is emitted as a quoted phrase, which also makes previously
+ * syntax-error-prone input (hyphens, colons, FTS5 keywords like NOT)
+ * safe. A trailing `*` is preserved as an FTS5 prefix query (`"term"*`).
+ */
+/**
+ * Split a raw query into sanitized terms. Drops quote characters and any
+ * token with no letters or digits (pure punctuation can't match anything
+ * under the unicode61 tokenizer).
+ */
+export function ftsTerms(query) {
+    return query
+        .replace(/['"]/g, "")
+        .split(/\s+/)
+        .filter((t) => /[\p{L}\p{N}]/u.test(t));
+}
+/** Render one term as a safe FTS5 phrase, preserving trailing-`*` prefix queries. */
+function ftsPhrase(term) {
+    const prefixMatch = term.match(/^(.*?)\*+$/);
+    if (prefixMatch && /[\p{L}\p{N}]/u.test(prefixMatch[1])) {
+        return `"${prefixMatch[1]}"*`;
+    }
+    return `"${term}"`;
+}
+/** Implicit-AND MATCH expression: all terms must match. */
+export function ftsAndQuery(terms) {
+    return terms.map(ftsPhrase).join(" ");
+}
+/** OR MATCH expression: any term may match; BM25 ranks fuller matches higher. */
+export function ftsOrQuery(terms) {
+    return terms.map(ftsPhrase).join(" OR ");
+}

package/dist/lib/hybridSearch.d.ts

@@ -57,6 +57,15 @@ export declare class GnosysHybridSearch {
      * Check if embeddings are available.
      */
     hasEmbeddings(): boolean;
+    /**
+     * True when hybrid/semantic search can actually run its semantic leg.
+     * In DB mode this requires BOTH stored vectors in the central DB and the
+     * store-local embeddings.db used to embed the query text — the central
+     * count alone can be non-zero on a machine that only syncs gnosys.db,
+     * in which case hybridSearch() silently runs keyword-only (embedQuery
+     * is never constructed).
+     */
+    canRunSemantic(): boolean;
     /**
      * Get embedding count.
      */

package/dist/lib/hybridSearch.js

@@ -284,6 +284,20 @@ export class GnosysHybridSearch {
             return this.dbSearch.hasEmbeddings();
         return this.embeddings.hasEmbeddings();
     }
+    /**
+     * True when hybrid/semantic search can actually run its semantic leg.
+     * In DB mode this requires BOTH stored vectors in the central DB and the
+     * store-local embeddings.db used to embed the query text — the central
+     * count alone can be non-zero on a machine that only syncs gnosys.db,
+     * in which case hybridSearch() silently runs keyword-only (embedQuery
+     * is never constructed).
+     */
+    canRunSemantic() {
+        if (this.dbSearch) {
+            return this.dbSearch.hasEmbeddings() && this.embeddings.hasEmbeddings();
+        }
+        return this.embeddings.hasEmbeddings();
+    }
     /**
      * Get embedding count.
      */

package/dist/lib/hybridSearchCommand.js

@@ -67,7 +67,12 @@ export async function runHybridSearchCommand(getResolver, query, opts) {
     const embeddings = new GnosysEmbeddings(storePath);
     const hybridSearch = new GnosysHybridSearch(search, embeddings, resolver, storePath);
     const mode = opts.mode;
-    const results = await hybridSearch.hybridSearch(query, parseInt(opts.limit), mode);
+    // v5.12.3: hybrid used to degrade to keyword-only silently when the
+    // semantic leg can't run. Warn on stderr so --json stdout stays clean.
+    if (mode !== "keyword" && !hybridSearch.canRunSemantic()) {
+        console.error(`⚠ Semantic embeddings unavailable — ${mode} search will run keyword-only. Run 'gnosys reindex' to build embeddings.`);
+    }
+    const results = await hybridSearch.hybridSearch(query, parseInt(opts.limit, 10), mode);
     if (results.length === 0) {
         outputResult(!!opts.json, { query, mode, results: [] }, () => {
             console.log(`No results for "${query}". Try gnosys reindex to build embeddings.`);

package/dist/lib/importProject.js

@@ -20,10 +20,11 @@ export function readBundle(bundlePath) {
     return bundle;
 }
 function portableToDbMemory(p) {
-    const { embedding_b64, ...rest } = p;
+    const { embedding_b64, attachment_data_b64, ...rest } = p;
     return {
         ...rest,
         embedding: embedding_b64 ? Buffer.from(embedding_b64, "base64") : null,
+        attachment_data: attachment_data_b64 ? Buffer.from(attachment_data_b64, "base64") : null,
     };
 }
 /** Restore a bundle into the central DB. Returns counts and the final project ID. */

package/dist/lib/llm.js

@@ -487,7 +487,7 @@ export function createProvider(provider, model, config, task) {
         }
         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);

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/migrate.js

@@ -10,7 +10,6 @@ import { GnosysDB, fnv1a } from "./db.js";
 import { GnosysStore } from "./store.js";
 import { GnosysArchive } from "./archive.js";
 // Dynamic import for embeddings DB
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
 let Database = null;
 try {
     Database = (await import("better-sqlite3")).default;

package/dist/lib/multimodalIngest.js

@@ -143,7 +143,7 @@ function buildTranscriptChunks(segments, targetSize) {
  */
 export async function ingestFile(options) {
     const startTime = Date.now();
-    const { filePath, storePath, mode = "llm", author = "human", authority = "imported", dryRun = false, projectRoot, onProgress, } = options;
+    const { filePath, storePath, mode = "llm", author = "human", authority = "imported", dryRun = false, onProgress, } = options;
     // Step 1: Detect file type
     const fileInfo = await detectFileType(filePath);
     // Reject unsupported types early

package/dist/lib/platform.d.ts

@@ -4,16 +4,10 @@
 export type OsFamily = "macos" | "linux" | "windows";
 /** Current OS family for CLI messages and help text. */
 export declare function getOsFamily(): OsFamily;
-/** Primary secure credential store name on this machine. */
-export declare function getSecureStorageLabel(): string;
 /** Short phrase for error messages (setup may still be required on Windows). */
 export declare function getSecureStorageSetupHint(): string;
-/** Order of API key resolution for user-facing help on the current OS. */
-export declare function getApiKeyResolutionOrderText(): string;
 /** Claude Desktop MCP config file path for the current platform. */
 export declare function getClaudeDesktopConfigPath(): string;
-/** Display path with ~ for home (for logs and help). */
-export declare function displayClaudeDesktopConfigPath(): string;
 /** Shell profile file(s) suggested for env vars on this OS. */
 export declare function getShellProfileHint(): string;
 /** Lines shown when user skips API key setup in gnosys setup. */

package/dist/lib/platform.js

@@ -11,17 +11,6 @@ export function getOsFamily() {
         return "windows";
     return "linux";
 }
-/** Primary secure credential store name on this machine. */
-export function getSecureStorageLabel() {
-    switch (getOsFamily()) {
-        case "macos":
-            return "macOS Keychain";
-        case "linux":
-            return "GNOME Keyring";
-        case "windows":
-            return "Windows Credential Manager";
-    }
-}
 /** Short phrase for error messages (setup may still be required on Windows). */
 export function getSecureStorageSetupHint() {
     switch (getOsFamily()) {
@@ -33,17 +22,6 @@ export function getSecureStorageSetupHint() {
             return "your user environment or ~/.config/gnosys/.env (via gnosys setup)";
     }
 }
-/** Order of API key resolution for user-facing help on the current OS. */
-export function getApiKeyResolutionOrderText() {
-    switch (getOsFamily()) {
-        case "macos":
-            return "macOS Keychain, environment variable, then ~/.config/gnosys/.env";
-        case "linux":
-            return "GNOME Keyring (when available), environment variable, then ~/.config/gnosys/.env";
-        case "windows":
-            return "environment variable, then ~/.config/gnosys/.env";
-    }
-}
 /** Claude Desktop MCP config file path for the current platform. */
 export function getClaudeDesktopConfigPath() {
     const home = os.homedir();
@@ -56,12 +34,6 @@ export function getClaudeDesktopConfigPath() {
     }
     return path.join(home, ".config", "Claude", "claude_desktop_config.json");
 }
-/** Display path with ~ for home (for logs and help). */
-export function displayClaudeDesktopConfigPath() {
-    const home = os.homedir();
-    const p = getClaudeDesktopConfigPath();
-    return p.startsWith(home) ? "~" + p.slice(home.length) : p;
-}
 /** Shell profile file(s) suggested for env vars on this OS. */
 export function getShellProfileHint() {
     switch (getOsFamily()) {

package/dist/lib/readCommand.js

@@ -1,5 +1,4 @@
 import fs from "fs/promises";
-import { GnosysDB } from "./db.js";
 function outputResult(json, data, humanFn) {
     if (json) {
         console.log(JSON.stringify(data, null, 2));
@@ -9,11 +8,14 @@ function outputResult(json, data, humanFn) {
     }
 }
 export async function runReadCommand(getResolver, memoryPath, opts) {
-    const centralDb = GnosysDB.openCentral();
-    if (centralDb.isAvailable()) {
-        const dbMem = centralDb.getMemory(memoryPath);
-        if (dbMem) {
-            try {
+    // v13 client read path: master/snapshot routing + pending-offline-adds overlay,
+    // so `gnosys read <id>` sees the same memories as list/discover/search.
+    const { resolveClientRead, getMemoryWithOverlay } = await import("./clientReadResolve.js");
+    const resolved = resolveClientRead();
+    if (resolved) {
+        try {
+            const dbMem = getMemoryWithOverlay(resolved, memoryPath);
+            if (dbMem) {
                 const tags = dbMem.tags || "[]";
                 const headerLines = [
                     `---`,
@@ -42,12 +44,11 @@ export async function runReadCommand(getResolver, memoryPath, opts) {
                 });
                 return;
             }
-            finally {
-                centralDb.close();
-            }
+        }
+        finally {
+            resolved.release();
         }
     }
-    centralDb.close();
     const resolver = await getResolver();
     const memory = await resolver.readMemory(memoryPath);
     if (!memory) {

package/dist/lib/remoteWizard.d.ts

@@ -24,7 +24,7 @@ export declare function configureFromPath(centralDb: GnosysDB, remotePath: strin
     migrate?: boolean;
     role?: MultiMachineRole;
 }): Promise<boolean>;
-export { stagingDirForMachine, clientPresencePath } from "./syncStaging.js";
+export { machineStagingDir as stagingDirForMachine, clientPresencePath } from "./syncStaging.js";
 export declare const __test: {
     matchesTypedPhrase: typeof matchesTypedPhrase;
     detectClonedStagingPresence: typeof detectClonedStagingPresence;

package/dist/lib/remoteWizard.js

@@ -6,7 +6,7 @@
  *  - Reconfigure: change path, re-validate, or disconnect (when already configured)
  */
 import { randomUUID } from "crypto";
-import { existsSync, mkdirSync, renameSync } from "fs";
+import { existsSync, mkdirSync, renameSync, } from "fs";
 import * as path from "path";
 import { createInterface } from "readline/promises";
 import { GnosysDB } from "./db.js";
@@ -16,7 +16,7 @@ import { getGnosysHome } from "./paths.js";
 import { atomicWriteFileSync } from "./atomicWrite.js";
 import { readMasterMarker, writeMasterMarker } from "./masterLease.js";
 import { checkMasterPathLocalDisk, LOCAL_DISK_ACK_PHRASE, } from "./localDiskCheck.js";
-import { stagingDirForMachine, clientPresencePath, machineStagingDir } from "./syncStaging.js";
+import { clientPresencePath, machineStagingDir } from "./syncStaging.js";
 import { safeQuestion } from "./setup/ui/safePrompt.js";
 import { Spinner } from "./setup/ui/spinner.js";
 import { printStatus } from "./setup/ui/status.js";
@@ -500,10 +500,10 @@ export async function configureFromPath(centralDb, remotePath, opts = {}) {
     }
     return true;
 }
-export { stagingDirForMachine, clientPresencePath } from "./syncStaging.js";
+export { machineStagingDir as stagingDirForMachine, clientPresencePath } from "./syncStaging.js";
 export const __test = {
     matchesTypedPhrase,
     detectClonedStagingPresence,
-    stagingDirForMachine,
+    stagingDirForMachine: machineStagingDir,
     clientPresencePath,
 };

package/dist/lib/resolver.d.ts

@@ -46,6 +46,23 @@ export declare class GnosysResolver {
      * Discover and initialize all store layers.
      */
     resolve(): Promise<ResolvedStore[]>;
+    /**
+     * Load the env-configured store tiers (optional `GNOSYS_STORES`, personal
+     * `GNOSYS_PERSONAL`, global `GNOSYS_GLOBAL`) onto `this.stores`.
+     *
+     * Shared by {@link resolve} and {@link resolveForProject}: a per-tool
+     * `projectRoot` call must STILL see personal/global, otherwise cross-project
+     * and global memories are unreachable — you couldn't write `store: "global"`
+     * / `"personal"` nor read them back from another project. Since every tool
+     * is told to always pass `projectRoot`, omitting these here silently
+     * disabled the entire cross-project tier system.
+     *
+     * Global is loaded whenever `GNOSYS_GLOBAL` is set, creating its directory on
+     * demand (parity with personal) so a configured-but-empty global store still
+     * works. It remains write-only-when-explicitly-targeted: {@link getWriteTarget}
+     * never auto-selects it.
+     */
+    private loadEnvTiers;
     /**
      * Get all stores in precedence order.
      */