gnosys 5.10.0 → 5.11.0

package/dist/lib/heartbeat.d.ts

@@ -11,21 +11,8 @@
  * Wire into commands that can block on I/O:
  *   status / sync / reindex / bootstrap / import / migrate-db / dream / doctor.
  */
-export interface Heartbeat {
-    /** Update the message shown next to the spinner. Safe to call repeatedly. */
-    setMessage(msg: string): void;
-    /** Stop the spinner and clear the line. */
-    stop(): void;
-}
-/**
- * Start a heartbeat. Returns a handle with `setMessage` and `stop`.
- *
- * In non-TTY contexts (pipes, CI), returns a no-op handle.
- */
-export declare function startHeartbeat(message: string): Heartbeat;
 /**
  * Run an async function with a heartbeat wrapped around it. The heartbeat
  * is always stopped, even on error.
  */
 export declare function withHeartbeat<T>(message: string, fn: () => Promise<T>): Promise<T>;
-//# sourceMappingURL=heartbeat.d.ts.map

package/dist/lib/heartbeat.js

@@ -33,7 +33,7 @@ function paint(state) {
  *
  * In non-TTY contexts (pipes, CI), returns a no-op handle.
  */
-export function startHeartbeat(message) {
+function startHeartbeat(message) {
     if (!isTty()) {
         return {
             setMessage: () => { },
@@ -88,4 +88,3 @@ export async function withHeartbeat(message, fn) {
         hb.stop();
     }
 }
-//# sourceMappingURL=heartbeat.js.map

package/dist/lib/hybridSearch.d.ts

@@ -7,27 +7,12 @@
  *   semantic — embeddings cosine similarity only
  *   hybrid   — RRF fusion of both (default when embeddings exist)
  */
-import { GnosysSearch } from "./search.js";
+import type { GnosysSearch } from "./search.js";
 import { GnosysEmbeddings } from "./embeddings.js";
-import { GnosysResolver } from "./resolver.js";
-import { GnosysDB } from "./db.js";
-export type SearchMode = "keyword" | "semantic" | "hybrid";
-export interface HybridSearchResult {
-    relativePath: string;
-    title: string;
-    snippet: string;
-    score: number;
-    /** Which method(s) found this result */
-    sources: ("keyword" | "semantic" | "archive")[];
-    /** Full memory content (loaded on demand for ask engine) */
-    content?: string;
-    /** The memory frontmatter content field */
-    fullContent?: string;
-    /** Memory ID (used for dearchiving) */
-    memoryId?: string;
-    /** Whether this result came from the archive */
-    fromArchive?: boolean;
-}
+import type { GnosysResolver } from "./resolver.js";
+import type { GnosysDB } from "./db.js";
+import type { HybridSearchResult, SearchMode } from "./searchTypes.js";
+export type { HybridSearchResult, SearchMode } from "./searchTypes.js";
 export declare class GnosysHybridSearch {
     private search;
     private embeddings;
@@ -77,4 +62,3 @@ export declare class GnosysHybridSearch {
      */
     embeddingCount(): number;
 }
-//# sourceMappingURL=hybridSearch.d.ts.map

package/dist/lib/hybridSearch.js

@@ -293,4 +293,3 @@ export class GnosysHybridSearch {
         return this.embeddings.count();
     }
 }
-//# sourceMappingURL=hybridSearch.js.map

package/dist/lib/idFormat.d.ts

@@ -19,7 +19,6 @@
  */
 import type { GnosysDB } from "./db.js";
 export type IdFormat = "short" | "long" | "raw";
-export declare function isTtyStdout(): boolean;
 /** Build the gnosys:// URI for a memory id. Encodes the id defensively. */
 export declare function memoryUri(id: string): string;
 /** Wrap `display` in OSC8 escapes pointing at `uri`. Caller decides when to use. */
@@ -59,4 +58,3 @@ export declare function buildProjectNameLookup(db: GnosysDB): Map<string, string
  * `short` for unknown inputs so CLI callers don't have to guard.
  */
 export declare function parseIdFormat(value: string | undefined): IdFormat;
-//# sourceMappingURL=idFormat.d.ts.map

package/dist/lib/idFormat.js

@@ -35,7 +35,7 @@ const SHORT_ULID_PREFIX = 8;
 const OSC8_START = "\x1b]8;;";
 const OSC8_BREAK = "\x1b\\";
 const OSC8_END = "\x1b]8;;\x1b\\";
-export function isTtyStdout() {
+function isTtyStdout() {
     return Boolean(process.stdout.isTTY);
 }
 /** Build the gnosys:// URI for a memory id. Encodes the id defensively. */
@@ -111,4 +111,3 @@ export function parseIdFormat(value) {
         return value;
     return "short";
 }
-//# sourceMappingURL=idFormat.js.map

package/dist/lib/imageExtract.d.ts

@@ -23,4 +23,3 @@ export interface ImageDescription {
  * returns a minimal fallback description with just filename and file size.
  */
 export declare function extractImageDescription(filePath: string, provider: LLMProvider): Promise<ImageDescription>;
-//# sourceMappingURL=imageExtract.d.ts.map

package/dist/lib/imageExtract.js

@@ -110,4 +110,3 @@ export async function extractImageDescription(filePath, provider) {
     const raw = await provider.generateWithImage(VISION_PROMPT, imageBase64, mimeType);
     return parseVisionResponse(raw);
 }
-//# sourceMappingURL=imageExtract.js.map

package/dist/lib/import.d.ts

@@ -3,9 +3,9 @@
  * Supports CSV, JSON, JSONL formats with LLM or structured ingestion modes.
  * Shared core used by both the MCP tool and CLI command.
  */
-import { GnosysIngestion } from "./ingest.js";
-import { GnosysStore } from "./store.js";
-import { GnosysDB } from "./db.js";
+import type { GnosysIngestion } from "./ingest.js";
+import type { GnosysStore } from "./store.js";
+import type { GnosysDB } from "./db.js";
 export interface ImportOptions {
     format: "csv" | "json" | "jsonl";
     data: string;
@@ -21,7 +21,7 @@ export interface ImportOptions {
     authority?: "declared" | "observed" | "imported" | "inferred";
     onProgress?: (progress: ImportProgress) => void;
 }
-export interface ImportProgress {
+interface ImportProgress {
     processed: number;
     total: number;
     current: string;
@@ -41,6 +41,7 @@ export interface ImportResult {
     totalProcessed: number;
     duration: number;
 }
+export declare function loadData(data: string, format: "csv" | "json" | "jsonl"): Promise<Record<string, unknown>[]>;
 export declare function performImport(store: GnosysStore, ingestion: GnosysIngestion, options: ImportOptions, db?: GnosysDB | null, projectId?: string | null, scope?: string): Promise<ImportResult>;
 /**
  * Format a human-readable summary of import results.
@@ -50,4 +51,4 @@ export declare function formatImportSummary(result: ImportResult): string;
  * Estimate import duration for smart threshold guidance.
  */
 export declare function estimateDuration(recordCount: number, mode: "llm" | "structured", concurrency?: number): string;
-//# sourceMappingURL=import.d.ts.map
+export {};

package/dist/lib/import.js

@@ -6,42 +6,13 @@
 import { parse as csvParse } from "csv-parse/sync";
 import fs from "fs/promises";
 import { syncMemoryToDb } from "./dbWrite.js";
-// ─── URL Safety ──────────────────────────────────────────────────────────
-function isSafeImportUrl(urlStr) {
-    try {
-        const url = new URL(urlStr);
-        if (url.protocol !== "http:" && url.protocol !== "https:")
-            return false;
-        const hostname = url.hostname;
-        if (hostname === "169.254.169.254" || hostname === "metadata.google.internal")
-            return false;
-        const ipv4Match = hostname.match(/^(\d+)\.(\d+)\.(\d+)\.(\d+)$/);
-        if (ipv4Match) {
-            const [, a, b] = ipv4Match.map(Number);
-            if (a === 10)
-                return false;
-            if (a === 172 && b >= 16 && b <= 31)
-                return false;
-            if (a === 192 && b === 168)
-                return false;
-            if (a === 169 && b === 254)
-                return false;
-        }
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
+import { safeFetch } from "./webIngest.js";
 // ─── Parsing ─────────────────────────────────────────────────────────────
-async function loadData(data, format) {
+export async function loadData(data, format) {
     let raw;
     // Determine if data is a file path, URL, or inline
     if (data.startsWith("http://") || data.startsWith("https://")) {
-        if (!isSafeImportUrl(data)) {
-            throw new Error(`Refusing to fetch unsafe URL: ${data}`);
-        }
-        const response = await fetch(data);
+        const response = await safeFetch(data);
         if (!response.ok) {
             throw new Error(`Failed to fetch URL: ${response.status} ${response.statusText}`);
         }
@@ -359,4 +330,3 @@ export function estimateDuration(recordCount, mode, concurrency = 5) {
         return `~${Math.ceil(seconds / 60)}m`;
     return `~${(seconds / 3600).toFixed(1)}h`;
 }
-//# sourceMappingURL=import.js.map

package/dist/lib/importProject.d.ts

@@ -3,9 +3,9 @@
  * exportProject.ts into the central DB. Three conflict strategies for
  * existing project IDs / memory IDs.
  */
-import { GnosysDB } from "./db.js";
-import { ProjectBundle } from "./exportProject.js";
-export type ImportStrategy = 
+import type { GnosysDB } from "./db.js";
+import { type ProjectBundle } from "./exportProject.js";
+type ImportStrategy = 
 /** Skip rows that already exist; insert new ones. Safe default. */
 "merge"
 /** Replace existing project + its memories. Destructive — deletes target project's memories first. */
@@ -32,4 +32,4 @@ export interface ImportProjectResult {
 export declare function readBundle(bundlePath: string): ProjectBundle;
 /** Restore a bundle into the central DB. Returns counts and the final project ID. */
 export declare function importProject(db: GnosysDB, opts: ImportProjectOptions): ImportProjectResult;
-//# sourceMappingURL=importProject.d.ts.map
+export {};

package/dist/lib/importProject.js

@@ -36,7 +36,7 @@ export function importProject(db, opts) {
     }
     const existing = db.getProject(project.id);
     let projectId = project.id;
-    let memoryIdRewrites = new Map();
+    const memoryIdRewrites = new Map();
     let memoriesReplaced = 0;
     if (existing) {
         if (strategy === "replace") {
@@ -132,4 +132,3 @@ export function importProject(db, opts) {
         auditEntriesInserted,
     };
 }
-//# sourceMappingURL=importProject.js.map

package/dist/lib/ingest.d.ts

@@ -3,9 +3,9 @@
  * Accepts messy human input, produces clean markdown files with YAML frontmatter.
  * Uses the LLM abstraction layer — works with Anthropic, Ollama, or any future provider.
  */
-import { GnosysTagRegistry } from "./tags.js";
-import { GnosysStore } from "./store.js";
-import { GnosysConfig } from "./config.js";
+import type { GnosysTagRegistry } from "./tags.js";
+import type { GnosysStore } from "./store.js";
+import { type GnosysConfig } from "./config.js";
 interface IngestResult {
     title: string;
     category: string;
@@ -54,4 +54,3 @@ export declare class GnosysIngestion {
     private slugify;
 }
 export {};
-//# sourceMappingURL=ingest.d.ts.map

package/dist/lib/ingest.js

@@ -180,4 +180,3 @@ Rules:
             .substring(0, 60);
     }
 }
-//# sourceMappingURL=ingest.js.map

package/dist/lib/lensing.d.ts

@@ -4,7 +4,7 @@
  * A lens is a set of filter criteria applied to memories.
  * Compound lenses combine multiple filters with AND/OR logic.
  */
-import { Memory } from "./store.js";
+import type { Memory } from "./store.js";
 export interface LensFilter {
     category?: string;
     tags?: string[];
@@ -23,4 +23,3 @@ export interface LensFilter {
  * Apply a single lens filter to an array of memories.
  */
 export declare function applyLens(memories: Memory[], lens: LensFilter): Memory[];
-//# sourceMappingURL=lensing.d.ts.map

package/dist/lib/lensing.js

@@ -67,4 +67,3 @@ function flattenTags(tags) {
         return tags;
     return Object.values(tags).flat();
 }
-//# sourceMappingURL=lensing.js.map

package/dist/lib/llm.d.ts

@@ -3,13 +3,15 @@
  * Supports Anthropic (cloud) and Ollama (local). Clean factory pattern enables
  * future providers (Groq, OpenAI, LM Studio) with zero changes to call sites.
  */
-import { GnosysConfig, LLMProviderName } from "./config.js";
-export interface LLMGenerateOptions {
+import { type GnosysConfig, type LLMProviderName } from "./config.js";
+/** Strip literal API keys and known key-prefix patterns from provider error text. */
+export declare function redactKey(text: string, apiKey?: string): string;
+interface LLMGenerateOptions {
     system?: string;
     maxTokens?: number;
     stream?: boolean;
 }
-export interface LLMStreamCallbacks {
+interface LLMStreamCallbacks {
     onToken: (token: string) => void;
 }
 /**
@@ -35,47 +37,6 @@ export interface LLMProvider {
      */
     testConnection(): Promise<boolean>;
 }
-export declare class AnthropicProvider implements LLMProvider {
-    readonly name: LLMProviderName;
-    readonly model: string;
-    private client;
-    private config;
-    private apiKey;
-    private clientPromise;
-    constructor(model: string, apiKey: string, config?: GnosysConfig);
-    private getClient;
-    generate(prompt: string, options?: LLMGenerateOptions, streamCallbacks?: LLMStreamCallbacks): Promise<string>;
-    private streamGenerate;
-    generateWithImage(prompt: string, imageBase64: string, mimeType: string, options?: LLMGenerateOptions): Promise<string>;
-    testConnection(): Promise<boolean>;
-}
-export declare class OllamaProvider implements LLMProvider {
-    readonly name: LLMProviderName;
-    readonly model: string;
-    private baseUrl;
-    private config;
-    constructor(model: string, baseUrl: string, config?: GnosysConfig);
-    generate(prompt: string, options?: LLMGenerateOptions, streamCallbacks?: LLMStreamCallbacks): Promise<string>;
-    private readStream;
-    generateWithImage(prompt: string, imageBase64: string, _mimeType: string, options?: LLMGenerateOptions): Promise<string>;
-    testConnection(): Promise<boolean>;
-}
-/**
- * Generic OpenAI-compatible provider. Works with any service that implements
- * the OpenAI /v1/chat/completions API: OpenAI, Groq, LM Studio, etc.
- */
-export declare class OpenAICompatibleProvider implements LLMProvider {
-    readonly name: LLMProviderName;
-    readonly model: string;
-    private baseUrl;
-    private apiKey;
-    private config;
-    constructor(name: LLMProviderName, model: string, baseUrl: string, apiKey: string, config?: GnosysConfig);
-    generate(prompt: string, options?: LLMGenerateOptions, streamCallbacks?: LLMStreamCallbacks): Promise<string>;
-    private readSSEStream;
-    generateWithImage(prompt: string, imageBase64: string, mimeType: string, options?: LLMGenerateOptions): Promise<string>;
-    testConnection(): Promise<boolean>;
-}
 /**
  * Create an LLM provider for a specific task.
  * Resolves provider + model from config's taskModels or defaultProvider.
@@ -93,4 +54,4 @@ export declare function isProviderAvailable(config: GnosysConfig, provider?: LLM
     available: boolean;
     error?: string;
 };
-//# sourceMappingURL=llm.d.ts.map
+export {};

package/dist/lib/llm.js

@@ -5,8 +5,20 @@
  */
 import { DEFAULT_CONFIG, resolveTaskModel, getAnthropicApiKey, getOllamaBaseUrl, getGroqApiKey, getOpenAIApiKey, getOpenAIBaseUrl, getLMStudioBaseUrl, getXAIApiKey, getMistralApiKey, 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;
+/** Shorter timeout for connectivity probes (testConnection, model lists). */
+const PROBE_TIMEOUT_MS = 10_000;
+/** Strip literal API keys and known key-prefix patterns from provider error text. */
+export function redactKey(text, apiKey) {
+    let out = text;
+    if (apiKey && apiKey.length >= 8) {
+        out = out.split(apiKey).join("***");
+    }
+    return out.replace(/(?:sk-ant-|sk-|gsk_|xai-|Bearer\s+)[^\s"']+/g, "***");
+}
 // ─── Anthropic Provider ──────────────────────────────────────────────────
-export class AnthropicProvider {
+class AnthropicProvider {
     name = "anthropic";
     model;
     client = null; // Anthropic SDK client (lazy-initialized)
@@ -24,7 +36,7 @@ export class AnthropicProvider {
         if (!this.clientPromise) {
             this.clientPromise = import("@anthropic-ai/sdk").then((mod) => {
                 const Anthropic = mod.default || mod;
-                this.client = new Anthropic({ apiKey: this.apiKey });
+                this.client = new Anthropic({ apiKey: this.apiKey, timeout: LLM_TIMEOUT_MS });
                 return this.client;
             });
         }
@@ -111,12 +123,12 @@ export class AnthropicProvider {
         catch (err) {
             // Sanitize error message to prevent API key leakage
             const msg = err instanceof Error ? err.message : String(err);
-            throw new Error(`Anthropic connection failed: ${msg.replace(/sk-ant-[^\s"']+/g, "sk-ant-***")}`);
+            throw new Error(`Anthropic connection failed: ${redactKey(msg, this.apiKey)}`);
         }
     }
 }
 // ─── Ollama Provider ─────────────────────────────────────────────────────
-export class OllamaProvider {
+class OllamaProvider {
     name = "ollama";
     model;
     baseUrl;
@@ -147,6 +159,7 @@ export class OllamaProvider {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify(body),
+            signal: AbortSignal.timeout(LLM_TIMEOUT_MS),
         }), {
             maxAttempts: this.config.llmRetryAttempts,
             baseDelayMs: this.config.llmRetryBaseDelayMs,
@@ -211,6 +224,7 @@ export class OllamaProvider {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify(body),
+            signal: AbortSignal.timeout(LLM_TIMEOUT_MS),
         }), {
             maxAttempts: this.config.llmRetryAttempts,
             baseDelayMs: this.config.llmRetryBaseDelayMs,
@@ -225,7 +239,9 @@ export class OllamaProvider {
     }
     async testConnection() {
         try {
-            const response = await fetch(`${this.baseUrl}/api/tags`);
+            const response = await fetch(`${this.baseUrl}/api/tags`, {
+                signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+            });
             if (!response.ok) {
                 throw new Error(`HTTP ${response.status}`);
             }
@@ -257,7 +273,7 @@ export class OllamaProvider {
  * Generic OpenAI-compatible provider. Works with any service that implements
  * the OpenAI /v1/chat/completions API: OpenAI, Groq, LM Studio, etc.
  */
-export class OpenAICompatibleProvider {
+class OpenAICompatibleProvider {
     name;
     model;
     baseUrl;
@@ -291,6 +307,7 @@ export class OpenAICompatibleProvider {
                 ...(this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {}),
             },
             body: JSON.stringify(body),
+            signal: AbortSignal.timeout(LLM_TIMEOUT_MS),
         }), {
             maxAttempts: this.config.llmRetryAttempts,
             baseDelayMs: this.config.llmRetryBaseDelayMs,
@@ -299,7 +316,7 @@ export class OpenAICompatibleProvider {
         if (!response.ok) {
             const errorText = await response.text();
             // Sanitize error text to prevent API key leakage
-            const safeText = errorText.replace(/(?:sk-|gsk_|Bearer\s+)[^\s"']+/g, "***");
+            const safeText = redactKey(errorText, this.apiKey);
             throw new Error(`${this.name} request failed (${response.status}): ${safeText}`);
         }
         if (shouldStream && streamCallbacks) {
@@ -368,6 +385,7 @@ export class OpenAICompatibleProvider {
                 messages,
                 max_tokens: maxTokens,
             }),
+            signal: AbortSignal.timeout(LLM_TIMEOUT_MS),
         }), {
             maxAttempts: this.config.llmRetryAttempts,
             baseDelayMs: this.config.llmRetryBaseDelayMs,
@@ -375,7 +393,7 @@ export class OpenAICompatibleProvider {
         });
         if (!response.ok) {
             const errorText = await response.text();
-            const safeText = errorText.replace(/(?:sk-|gsk_|Bearer\s+)[^\s"']+/g, "***");
+            const safeText = redactKey(errorText, this.apiKey);
             throw new Error(`${this.name} vision request failed (${response.status}): ${safeText}`);
         }
         const data = (await response.json());
@@ -387,6 +405,7 @@ export class OpenAICompatibleProvider {
                 headers: {
                     ...(this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {}),
                 },
+                signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
             });
             if (!response.ok) {
                 throw new Error(`HTTP ${response.status}`);
@@ -550,4 +569,3 @@ export function isProviderAvailable(config, provider) {
             return { available: false, error: `Unknown provider: ${target}` };
     }
 }
-//# sourceMappingURL=llm.js.map

package/dist/lib/lock.d.ts

@@ -30,4 +30,3 @@ export declare function acquireWriteLock(storePath: string, operation?: string):
  * 4MB+ WAL files in the wild with no checkpoint cadence in v5.4.0.
  */
 export declare function enableWAL(db: any): void;
-//# sourceMappingURL=lock.d.ts.map

package/dist/lib/lock.js

@@ -151,4 +151,3 @@ export function enableWAL(db) {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
-//# sourceMappingURL=lock.js.map

package/dist/lib/log.d.ts

@@ -0,0 +1,4 @@
+export declare function logError(err: unknown, ctx?: object): void;
+export declare function logWarn(message: string, ctx?: object): void;
+export declare function logInfo(message: string, ctx?: object): void;
+export declare function logDebug(message: string, ctx?: object): void;

package/dist/lib/log.js

@@ -0,0 +1,85 @@
+import fs from "fs";
+const LEVEL_ORDER = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+};
+function configuredLevel() {
+    const raw = (process.env.GNOSYS_LOG_LEVEL || "info").toLowerCase();
+    if (raw === "debug" || raw === "info" || raw === "warn" || raw === "error")
+        return raw;
+    return "info";
+}
+function shouldEmit(level) {
+    return LEVEL_ORDER[level] >= LEVEL_ORDER[configuredLevel()];
+}
+function normalizeError(err) {
+    return err instanceof Error ? err : new Error(String(err));
+}
+function buildRecord(level, message, err, ctx) {
+    const record = {
+        timestamp: new Date().toISOString(),
+        level,
+        message,
+        ...(ctx ?? {}),
+    };
+    if (err) {
+        record.error = {
+            name: err.name,
+            message: err.message,
+            stack: err.stack,
+        };
+    }
+    return record;
+}
+function formatText(level, message, err) {
+    const prefix = level === "error"
+        ? message.startsWith("gnosys:")
+            ? message
+            : `gnosys: ${message}`
+        : `gnosys: ${level}: ${message}`;
+    if (err?.stack && level === "error") {
+        return `${prefix}\n${err.stack}\n`;
+    }
+    return `${prefix}\n`;
+}
+function writeJsonLine(line) {
+    const logFile = process.env.GNOSYS_LOG_FILE;
+    if (logFile) {
+        fs.appendFileSync(logFile, line, "utf8");
+    }
+}
+function emit(level, message, err, ctx) {
+    if (!shouldEmit(level))
+        return;
+    try {
+        const jsonLine = `${JSON.stringify(buildRecord(level, message, err, ctx))}\n`;
+        const useJson = process.env.GNOSYS_LOG_FORMAT === "json";
+        if (useJson) {
+            process.stderr.write(jsonLine);
+        }
+        else {
+            process.stderr.write(formatText(level, message, err));
+        }
+        if (process.env.GNOSYS_LOG_FILE) {
+            writeJsonLine(jsonLine);
+        }
+    }
+    catch {
+        // Best-effort logging must never throw.
+    }
+}
+export function logError(err, ctx) {
+    const error = normalizeError(err);
+    emit("error", error.message, error, ctx);
+}
+export function logWarn(message, ctx) {
+    emit("warn", message, undefined, ctx);
+}
+export function logInfo(message, ctx) {
+    emit("info", message, undefined, ctx);
+}
+export function logDebug(message, ctx) {
+    emit("debug", message, undefined, ctx);
+}

package/dist/lib/machineConfig.d.ts

@@ -23,8 +23,7 @@
  * 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).
  */
-export declare const MACHINE_CONFIG_VERSION = 1;
-export interface MachineRemoteConfig {
+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). */
@@ -84,4 +83,4 @@ export declare function relPathUnderRoot(cfg: MachineConfig, absPath: string): {
     rootId: string;
     relPath: string;
 } | null;
-//# sourceMappingURL=machineConfig.d.ts.map
+export {};

package/dist/lib/machineConfig.js

@@ -28,7 +28,8 @@ import os from "os";
 import path from "path";
 import { randomUUID } from "crypto";
 import { getMachineConfigPath } from "./paths.js";
-export const MACHINE_CONFIG_VERSION = 1;
+import { atomicWriteFileSync } from "./atomicWrite.js";
+const MACHINE_CONFIG_VERSION = 1;
 /** A fresh machine config for the current host. */
 export function defaultMachineConfig() {
     return {
@@ -77,7 +78,7 @@ export function readMachineConfig() {
 export function writeMachineConfig(cfg) {
     const p = getMachineConfigPath();
     fs.mkdirSync(path.dirname(p), { recursive: true });
-    fs.writeFileSync(p, JSON.stringify(cfg, null, 2) + "\n", "utf-8");
+    atomicWriteFileSync(p, JSON.stringify(cfg, null, 2) + "\n");
 }
 /**
  * Load machine.json, creating it on first run. If the persisted config's
@@ -88,8 +89,19 @@ export function writeMachineConfig(cfg) {
  * genuine foreign file gets corrected when the user re-runs `projects scan`).
  */
 export function ensureMachineConfig() {
+    const override = process.env.GNOSYS_MACHINE_ID?.trim();
     const existing = readMachineConfig();
     const host = os.hostname();
+    if (override) {
+        const base = existing ?? defaultMachineConfig();
+        const cfg = {
+            ...base,
+            machineId: override,
+            hostname: host,
+        };
+        writeMachineConfig(cfg);
+        return { config: cfg, created: !existing, regenerated: false };
+    }
     if (!existing) {
         const fresh = defaultMachineConfig();
         writeMachineConfig(fresh);
@@ -143,4 +155,3 @@ export function relPathUnderRoot(cfg, absPath) {
     }
     return best ? { rootId: best.rootId, relPath: best.relPath } : null;
 }
-//# sourceMappingURL=machineConfig.js.map

package/dist/lib/machineMigrate.d.ts

@@ -36,4 +36,3 @@ export declare function migrateMachine(localDb: GnosysDB, opts?: {
  * outlier projects live elsewhere.
  */
 export declare function deriveCommonRoot(): string | null;
-//# sourceMappingURL=machineMigrate.d.ts.map

package/dist/lib/machineMigrate.js

@@ -100,4 +100,3 @@ export function deriveCommonRoot() {
     }
     return best;
 }
-//# sourceMappingURL=machineMigrate.js.map