@geminilight/mindos 1.0.9 → 1.0.29

package/dist/server/handlers/sync.js

@@ -1,21 +1,118 @@
 import { execFile, execFileSync } from 'node:child_process';
-import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
-import { homedir } from 'node:os';
+import { createHash, randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { homedir, hostname } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { resolveExistingSafe } from '../../foundation/security/index.js';
 import { json } from '../response.js';
 const DEFAULT_MINDOS_DIR = join(homedir(), '.mindos');
 const DEFAULT_CONFIG_PATH = join(DEFAULT_MINDOS_DIR, 'config.json');
 const DEFAULT_SYNC_STATE_PATH = join(DEFAULT_MINDOS_DIR, 'sync-state.json');
+const SYNC_LOCK_OWNER_STALE_MS = 5 * 60 * 1000;
+const SYNC_LOCK_ALIVE_HARD_STALE_MS = 30 * 60 * 1000;
+const PROTECTED_GITIGNORE_ENTRIES = ['*.sync-conflict', 'INSTRUCTION.md'];
+class SyncLockedError extends Error {
+    owner;
+    code = 'SYNC_LOCKED';
+    constructor(owner) {
+        super(formatSyncLockedMessage(owner));
+        this.owner = owner;
+        this.name = 'SyncLockedError';
+    }
+}
+function ensureProtectedGitignoreEntries(content) {
+    const normalizedLines = content.split(/\r?\n/).map(line => line.trim());
+    const missing = PROTECTED_GITIGNORE_ENTRIES.filter(entry => !normalizedLines.includes(entry));
+    if (missing.length === 0)
+        return content;
+    const base = content.trimEnd();
+    const appendix = [
+        '# MindOS protected sync files',
+        ...missing,
+        '',
+    ].join('\n');
+    return base ? `${base}\n\n${appendix}` : `${appendix}`;
+}
 export async function handleSyncGet(services = {}) {
     try {
         const config = readConfig(services);
-        const syncConfig = config.sync ?? {};
+        const syncConfig = config.sync;
         const state = readState(services);
         const mindRoot = config.mindRoot;
-        if (!syncConfig.enabled) {
+        const conflicts = normalizeConflicts(state.conflicts);
+        const configReadError = getConfigReadError(config);
+        if (configReadError) {
+            return json({
+                enabled: false,
+                configured: true,
+                needsSetup: true,
+                provider: 'git',
+                remote: '(not configured)',
+                branch: 'main',
+                lastSync: state.lastSync || null,
+                lastPull: state.lastPull || null,
+                unpushed: '?',
+                conflicts,
+                lastError: configReadError,
+            });
+        }
+        if (!syncConfig) {
             return json({ enabled: false });
         }
+        if (!syncConfig.enabled) {
+            if (!mindRoot) {
+                return json({
+                    enabled: false,
+                    configured: true,
+                    needsSetup: true,
+                    provider: syncConfig.provider || 'git',
+                    remote: '(not configured)',
+                    branch: 'main',
+                    lastSync: state.lastSync || null,
+                    lastPull: state.lastPull || null,
+                    unpushed: '?',
+                    conflicts,
+                    lastError: state.lastError || 'Knowledge base directory is not configured. Please re-configure sync.',
+                    autoCommitInterval: syncConfig.autoCommitInterval || 30,
+                    autoPullInterval: syncConfig.autoPullInterval || 300,
+                });
+            }
+            const hasRepo = callIsGitRepo(services, mindRoot);
+            const remote = hasRepo ? callGetRemoteUrl(services, mindRoot) : null;
+            if (!hasRepo || !remote) {
+                return json({
+                    enabled: false,
+                    configured: true,
+                    needsSetup: true,
+                    provider: syncConfig.provider || 'git',
+                    remote: redactGitRemote(remote) || '(not configured)',
+                    branch: hasRepo ? (callGetBranch(services, mindRoot) || 'main') : 'main',
+                    lastSync: state.lastSync || null,
+                    lastPull: state.lastPull || null,
+                    unpushed: '?',
+                    conflicts,
+                    lastError: state.lastError || (!hasRepo
+                        ? 'Git repository not found in knowledge base directory. Please re-configure sync.'
+                        : 'Remote not configured. Please re-configure sync.'),
+                    autoCommitInterval: syncConfig.autoCommitInterval || 30,
+                    autoPullInterval: syncConfig.autoPullInterval || 300,
+                });
+            }
+            return json({
+                enabled: false,
+                configured: true,
+                provider: syncConfig.provider || 'git',
+                remote: redactGitRemote(remote),
+                branch: callGetBranch(services, mindRoot) || 'main',
+                lastSync: state.lastSync || null,
+                lastPull: state.lastPull || null,
+                unpushed: callGetUnpushedCount(services, mindRoot),
+                conflicts,
+                lastError: state.lastError || null,
+                autoCommitInterval: syncConfig.autoCommitInterval || 30,
+                autoPullInterval: syncConfig.autoPullInterval || 300,
+            });
+        }
         const hasRepo = !!mindRoot && callIsGitRepo(services, mindRoot);
         const remote = hasRepo && mindRoot ? callGetRemoteUrl(services, mindRoot) : null;
         if (!hasRepo || !remote) {
@@ -23,15 +120,15 @@ export async function handleSyncGet(services = {}) {
                 enabled: true,
                 needsSetup: true,
                 provider: syncConfig.provider || 'git',
-                remote: remote || '(not configured)',
-                branch: 'main',
-                lastSync: null,
-                lastPull: null,
+                remote: redactGitRemote(remote) || '(not configured)',
+                branch: hasRepo && mindRoot ? (callGetBranch(services, mindRoot) || 'main') : 'main',
+                lastSync: state.lastSync || null,
+                lastPull: state.lastPull || null,
                 unpushed: '?',
-                conflicts: [],
-                lastError: !hasRepo
+                conflicts,
+                lastError: state.lastError || (!hasRepo
                     ? 'Git repository not found in knowledge base directory. Please re-configure sync.'
-                    : 'Remote not configured. Please re-configure sync.',
+                    : 'Remote not configured. Please re-configure sync.'),
                 autoCommitInterval: syncConfig.autoCommitInterval || 30,
                 autoPullInterval: syncConfig.autoPullInterval || 300,
             });
@@ -39,18 +136,20 @@ export async function handleSyncGet(services = {}) {
         return json({
             enabled: true,
             provider: syncConfig.provider || 'git',
-            remote,
+            remote: redactGitRemote(remote),
             branch: callGetBranch(services, mindRoot) || 'main',
             lastSync: state.lastSync || null,
             lastPull: state.lastPull || null,
             unpushed: callGetUnpushedCount(services, mindRoot),
-            conflicts: state.conflicts || [],
+            conflicts,
             lastError: state.lastError || null,
             autoCommitInterval: syncConfig.autoCommitInterval || 30,
             autoPullInterval: syncConfig.autoPullInterval || 300,
         });
     }
     catch (error) {
+        if (isSyncLockedError(error))
+            return syncLockedResponse(error);
         return json({ error: error instanceof Error ? error.message : String(error) }, { status: 500 });
     }
 }
@@ -58,6 +157,10 @@ export async function handleSyncPost(body, services = {}) {
     try {
         const payload = body && typeof body === 'object' ? body : {};
         const config = readConfig(services);
+        const configReadError = getConfigReadError(config);
+        if (configReadError && payload.action !== 'reset') {
+            return json({ error: configReadError }, { status: 500 });
+        }
         const mindRoot = config.mindRoot;
         if (payload.action === 'reset') {
             return handleSyncReset(config, services);
@@ -67,63 +170,88 @@ export async function handleSyncPost(body, services = {}) {
         }
         switch (payload.action) {
             case 'init':
-                return await handleSyncInit(payload, services);
+                return await handleSyncInit(payload, config, services);
             case 'now':
                 return await handleSyncNow(mindRoot, services);
             case 'on':
-                config.sync = { ...(config.sync ?? {}), enabled: true };
-                writeConfig(config, services);
-                return json({ ok: true, enabled: true });
+                return handleSyncToggle(mindRoot, config, services, true);
             case 'off':
-                config.sync = { ...(config.sync ?? {}), enabled: false };
-                writeConfig(config, services);
-                return json({ ok: true, enabled: false });
+                return handleSyncToggle(mindRoot, config, services, false);
             case 'gitignore-get':
                 return handleGitignoreGet(mindRoot);
             case 'gitignore-save':
-                return handleGitignoreSave(mindRoot, payload);
+                return handleGitignoreSave(mindRoot, payload, services);
             case 'resolve-conflict':
                 return handleResolveConflict(mindRoot, payload, services);
             case 'conflict-preview':
-                return handleConflictPreview(mindRoot, payload);
+                return handleConflictPreview(mindRoot, payload, services);
             case 'update-intervals':
-                return handleUpdateIntervals(payload, config, services);
+                return handleUpdateIntervals(mindRoot, payload, config, services);
             default:
                 return json({ error: `Unknown action: ${payload.action}` }, { status: 400 });
         }
     }
     catch (error) {
+        if (isSyncLockedError(error))
+            return syncLockedResponse(error);
         return json({ error: error instanceof Error ? error.message : String(error) }, { status: 500 });
     }
 }
+function handleSyncToggle(mindRoot, config, services, enabled) {
+    return withServerSyncLock(mindRoot, enabled ? 'sync-on' : 'sync-off', services, () => {
+        config.sync = { ...(config.sync ?? {}), enabled };
+        writeConfig(config, services);
+        if (enabled)
+            notifySyncDaemon(services, 'restart', mindRoot);
+        else
+            notifySyncDaemon(services, 'stop');
+        return json({ ok: true, enabled });
+    });
+}
 function handleSyncReset(config, services) {
-    delete config.sync;
-    writeConfig(config, services);
-    try {
-        writeState({}, services);
-    }
-    catch { }
-    return json({ ok: true, enabled: false });
+    return withServerSyncLock(config.mindRoot ?? null, 'reset', services, () => {
+        if (getConfigReadError(config)) {
+            backupUnreadableConfig(services);
+            writeConfig({}, services);
+        }
+        else {
+            delete config.sync;
+            writeConfig(stripInternalConfigFields(config), services);
+        }
+        try {
+            writeState({}, services);
+        }
+        catch { }
+        notifySyncDaemon(services, 'stop');
+        return json({ ok: true, enabled: false });
+    });
 }
-async function handleSyncInit(payload, services) {
+async function handleSyncInit(payload, config, services) {
     const remote = payload.remote?.trim();
     if (!remote) {
         return json({ error: 'Remote URL is required' }, { status: 400 });
     }
     const isHttps = remote.startsWith('https://');
-    const isSsh = /^git@[\w.-]+:.+/.test(remote);
+    const isSsh = /^git@[\w.-]+:.+/.test(remote) || /^ssh:\/\/git@[^/]+\/.+/.test(remote);
     if (!isHttps && !isSsh) {
         return json({ error: 'Invalid remote URL — must be HTTPS or SSH format' }, { status: 400 });
     }
     const branch = payload.branch?.trim() || 'main';
-    const args = ['sync', 'init', '--non-interactive', '--remote', remote, '--branch', branch];
-    if (payload.token)
-        args.push('--token', payload.token);
+    if (!isValidGitBranchName(branch)) {
+        return json({ error: 'Invalid branch name' }, { status: 400 });
+    }
+    const normalizedRemote = normalizeHttpsRemoteCredentials(remote, payload.token?.trim());
+    const args = ['sync', 'init', '--non-interactive', '--remote', normalizedRemote.remote, '--branch', branch];
+    const envOverrides = normalizedRemote.token ? { MINDOS_SYNC_TOKEN: normalizedRemote.token } : undefined;
     try {
-        await runCli(args, 120000, services);
+        await runCli(args, 120000, services, envOverrides);
+        if (config.mindRoot)
+            notifySyncDaemon(services, 'restart', config.mindRoot);
         return json({ success: true, message: 'Sync initialized' });
     }
     catch (error) {
+        if (isSyncLockedError(error))
+            return syncLockedResponse(error);
         return json({ error: error instanceof Error ? error.message : String(error) }, { status: 400 });
     }
 }
@@ -136,6 +264,8 @@ async function handleSyncNow(mindRoot, services) {
         return json({ ok: true });
     }
     catch (error) {
+        if (isSyncLockedError(error))
+            return syncLockedResponse(error);
         return json({ error: error instanceof Error ? error.message : String(error) }, { status: 500 });
     }
 }
@@ -143,19 +273,29 @@ function handleGitignoreGet(mindRoot) {
     try {
         return json({ content: readFileSync(resolveExistingSafe(mindRoot, '.gitignore'), 'utf-8') });
     }
-    catch {
-        return json({ content: '' });
+    catch (error) {
+        if (isFsErrorCode(error, 'ENOENT'))
+            return json({ content: '' });
+        const message = error instanceof Error ? error.message : String(error);
+        if (/access denied|outside root|absolute paths/i.test(message))
+            return json({ error: 'Access denied' }, { status: 403 });
+        return json({ error: message }, { status: 500 });
     }
 }
-function handleGitignoreSave(mindRoot, payload) {
+function handleGitignoreSave(mindRoot, payload, services) {
     if (typeof payload.content !== 'string') {
         return json({ error: 'Missing content' }, { status: 400 });
     }
+    const content = ensureProtectedGitignoreEntries(payload.content);
     try {
-        writeFileSync(resolveExistingSafe(mindRoot, '.gitignore'), payload.content, 'utf-8');
-        return json({ ok: true });
+        return withServerSyncLock(mindRoot, 'gitignore-save', services, () => {
+            writeFileSync(resolveExistingSafe(mindRoot, '.gitignore'), content, 'utf-8');
+            return json({ ok: true, content });
+        });
     }
     catch (error) {
+        if (isSyncLockedError(error))
+            return syncLockedResponse(error);
         const message = error instanceof Error ? error.message : String(error);
         if (/access denied|outside root|absolute paths/i.test(message))
             return json({ error: 'Access denied' }, { status: 403 });
@@ -163,11 +303,14 @@ function handleGitignoreSave(mindRoot, payload) {
     }
 }
 function handleResolveConflict(mindRoot, payload, services) {
-    const file = payload.remote;
-    const strategy = payload.branch ?? 'keep-local';
+    const file = payload.file ?? payload.remote;
+    const strategy = payload.strategy ?? payload.branch ?? 'keep-local';
     if (!file || typeof file !== 'string') {
         return json({ error: 'Missing file path' }, { status: 400 });
     }
+    if (strategy !== 'keep-local' && strategy !== 'keep-remote') {
+        return json({ error: 'Invalid conflict resolution strategy' }, { status: 400 });
+    }
     if (!isPathWithinMindRoot(mindRoot, file)) {
         return json({ error: 'Invalid file path' }, { status: 400 });
     }
@@ -176,21 +319,33 @@ function handleResolveConflict(mindRoot, payload, services) {
     if (!conflictPath || !originalPath) {
         return json({ error: 'Invalid file path' }, { status: 400 });
     }
-    if (strategy === 'keep-remote' && existsSync(conflictPath)) {
-        writeFileSync(originalPath, readFileSync(conflictPath, 'utf-8'), 'utf-8');
-    }
-    if (existsSync(conflictPath)) {
-        unlinkSync(conflictPath);
-    }
-    const state = readState(services);
-    if (state.conflicts) {
-        state.conflicts = state.conflicts.filter((conflict) => conflict.file !== file);
-        writeState(state, services);
-    }
-    return json({ ok: true });
+    return withServerSyncLock(mindRoot, 'resolve-conflict', services, () => {
+        const state = readState(services);
+        const conflict = findConflict(state, file);
+        if (strategy === 'keep-remote') {
+            if (conflict?.remoteExists === false) {
+                rmSync(originalPath, { force: true });
+            }
+            else if (existsSync(conflictPath)) {
+                writeFileSync(originalPath, readFileSync(conflictPath, 'utf-8'), 'utf-8');
+            }
+            else {
+                return json({ error: 'Remote conflict backup is missing' }, { status: 409 });
+            }
+        }
+        else if (conflict?.localExists === false) {
+            rmSync(originalPath, { force: true });
+        }
+        if (existsSync(conflictPath)) {
+            unlinkSync(conflictPath);
+        }
+        const nextConflicts = normalizeConflicts(state.conflicts).filter((conflict) => conflict.file !== file);
+        writeState({ ...state, conflicts: nextConflicts }, services);
+        return json({ ok: true });
+    });
 }
-function handleConflictPreview(mindRoot, payload) {
-    const file = payload.remote;
+function handleConflictPreview(mindRoot, payload, services) {
+    const file = payload.file ?? payload.remote;
     if (!file || typeof file !== 'string') {
         return json({ error: 'Missing file path' }, { status: 400 });
     }
@@ -202,12 +357,33 @@ function handleConflictPreview(mindRoot, payload) {
     if (!localPath || !remotePath) {
         return json({ error: 'Invalid file path' }, { status: 400 });
     }
-    return json({
-        local: existsSync(localPath) ? readFileSync(localPath, 'utf-8') : '',
-        remote: existsSync(remotePath) ? readFileSync(remotePath, 'utf-8') : '',
-    });
+    try {
+        const conflict = findConflict(readState(services), file);
+        if (!existsSync(remotePath)) {
+            if (conflict?.remoteExists === false) {
+                return json({
+                    local: conflict?.localExists === false || !existsSync(localPath) ? '' : readFileSync(localPath, 'utf-8'),
+                    remote: '',
+                });
+            }
+            return json({ error: 'Remote conflict backup is missing' }, { status: 409 });
+        }
+        return json({
+            local: conflict?.localExists === false || !existsSync(localPath) ? '' : readFileSync(localPath, 'utf-8'),
+            remote: readFileSync(remotePath, 'utf-8'),
+        });
+    }
+    catch (error) {
+        if (isFsErrorCode(error, 'ENOENT')) {
+            return json({ error: 'Remote conflict backup is missing' }, { status: 409 });
+        }
+        if (isFsErrorCode(error, 'EACCES') || isFsErrorCode(error, 'EPERM')) {
+            return json({ error: 'Access denied' }, { status: 403 });
+        }
+        return json({ error: error instanceof Error ? error.message : String(error) }, { status: 500 });
+    }
 }
-function handleUpdateIntervals(payload, config, services) {
+function handleUpdateIntervals(mindRoot, payload, config, services) {
     const commitInterval = typeof payload.autoCommitInterval === 'number' ? payload.autoCommitInterval : undefined;
     const pullInterval = typeof payload.autoPullInterval === 'number' ? payload.autoPullInterval : undefined;
     if (commitInterval === undefined && pullInterval === undefined) {
@@ -219,21 +395,98 @@ function handleUpdateIntervals(payload, config, services) {
     if (pullInterval !== undefined && (!Number.isInteger(pullInterval) || pullInterval < 60 || pullInterval > 3600)) {
         return json({ error: 'autoPullInterval must be an integer between 60 and 3600 seconds' }, { status: 400 });
     }
-    config.sync = config.sync ?? {};
-    if (commitInterval !== undefined)
-        config.sync.autoCommitInterval = commitInterval;
-    if (pullInterval !== undefined)
-        config.sync.autoPullInterval = pullInterval;
-    writeConfig(config, services);
-    return json({
-        autoCommitInterval: config.sync.autoCommitInterval || 30,
-        autoPullInterval: config.sync.autoPullInterval || 300,
+    return withServerSyncLock(mindRoot, 'update-intervals', services, () => {
+        config.sync = config.sync ?? {};
+        if (commitInterval !== undefined)
+            config.sync.autoCommitInterval = commitInterval;
+        if (pullInterval !== undefined)
+            config.sync.autoPullInterval = pullInterval;
+        writeConfig(config, services);
+        if (config.sync.enabled)
+            notifySyncDaemon(services, 'reconfigure', mindRoot);
+        return json({
+            autoCommitInterval: config.sync.autoCommitInterval || 30,
+            autoPullInterval: config.sync.autoPullInterval || 300,
+        });
     });
 }
+function isValidGitBranchName(input) {
+    const value = input.trim();
+    if (!value || value === '@')
+        return false;
+    if (value.startsWith('-') || value.startsWith('/') || value.endsWith('/'))
+        return false;
+    if (value.endsWith('.') || value.includes('..') || value.includes('//') || value.includes('@{'))
+        return false;
+    if (/[\s~^:?*\[\\\]]/.test(value))
+        return false;
+    return value.split('/').every(part => part && !part.startsWith('.') && !part.endsWith('.lock'));
+}
+function normalizeConflicts(value) {
+    const items = Array.isArray(value) ? value : (value && typeof value === 'object' ? [value] : []);
+    const conflicts = [];
+    for (const item of items) {
+        if (typeof item === 'string') {
+            const file = item.trim();
+            if (file)
+                conflicts.push({ file });
+            continue;
+        }
+        if (!item || typeof item !== 'object')
+            continue;
+        const record = item;
+        const file = typeof record.file === 'string' ? record.file.trim() : '';
+        if (!file)
+            continue;
+        conflicts.push({
+            file,
+            ...(typeof record.time === 'string' && record.time ? { time: record.time } : {}),
+            ...(record.noBackup === true ? { noBackup: true } : {}),
+            ...(typeof record.localExists === 'boolean' ? { localExists: record.localExists } : {}),
+            ...(typeof record.remoteExists === 'boolean' ? { remoteExists: record.remoteExists } : {}),
+        });
+    }
+    return conflicts;
+}
+function findConflict(state, file) {
+    return normalizeConflicts(state.conflicts).find((conflict) => conflict.file === file) ?? null;
+}
+function notifySyncDaemon(services, action, mindRoot) {
+    try {
+        if (action === 'stop') {
+            services.syncDaemon?.stop?.();
+            return;
+        }
+        if (!mindRoot)
+            return;
+        if (action === 'restart') {
+            if (services.syncDaemon?.restart) {
+                services.syncDaemon.restart(mindRoot);
+            }
+            else {
+                services.syncDaemon?.stop?.();
+                services.syncDaemon?.start?.(mindRoot);
+            }
+            return;
+        }
+        if (action === 'reconfigure') {
+            if (services.syncDaemon?.reconfigure)
+                services.syncDaemon.reconfigure(mindRoot);
+            else if (services.syncDaemon?.restart)
+                services.syncDaemon.restart(mindRoot);
+            return;
+        }
+        services.syncDaemon?.start?.(mindRoot);
+    }
+    catch {
+        // Sync config/state has already been persisted. Runtime daemon refresh is
+        // best-effort and will also be corrected by the daemon config poller.
+    }
+}
 function readConfig(services) {
     if (services.readConfig)
         return services.readConfig();
-    return readJsonFile(services.configPath ?? DEFAULT_CONFIG_PATH);
+    return readJsonFile(services.configPath ?? DEFAULT_CONFIG_PATH, { reportParseError: true });
 }
 function writeConfig(config, services) {
     if (services.writeConfig) {
@@ -254,13 +507,180 @@ function writeState(state, services) {
     }
     atomicWriteJson(services.statePath ?? DEFAULT_SYNC_STATE_PATH, state);
 }
-function readJsonFile(filePath) {
+function withServerSyncLock(mindRoot, operation, services, callback) {
+    if (!mindRoot)
+        return callback();
+    const lock = acquireServerSyncLock(mindRoot, operation, services);
+    try {
+        return callback();
+    }
+    finally {
+        releaseServerSyncLock(lock);
+    }
+}
+export function getServerSyncLockPath(mindRoot, services = {}) {
+    const normalized = resolve(mindRoot || '.');
+    const hash = createHash('sha256').update(normalized).digest('hex').slice(0, 16);
+    return join(services.syncLockDir ?? join(DEFAULT_MINDOS_DIR, 'sync-locks'), `${hash}.lock`);
+}
+function acquireServerSyncLock(mindRoot, operation, services) {
+    const lockPath = getServerSyncLockPath(mindRoot, services);
+    mkdirSync(dirname(lockPath), { recursive: true });
+    const token = randomUUID();
+    while (true) {
+        try {
+            mkdirSync(lockPath);
+            try {
+                writeFileSync(join(lockPath, 'owner.json'), `${JSON.stringify({
+                    pid: process.pid,
+                    hostname: hostname(),
+                    operation,
+                    mindRoot: resolve(mindRoot),
+                    startedAt: new Date().toISOString(),
+                    token,
+                }, null, 2)}\n`, 'utf-8');
+            }
+            catch (error) {
+                rmSync(lockPath, { recursive: true, force: true });
+                throw error;
+            }
+            return { lockPath, token };
+        }
+        catch (error) {
+            if (!isFsErrorCode(error, 'EEXIST'))
+                throw error;
+            if (!isServerSyncLockStale(lockPath)) {
+                throw new SyncLockedError(readServerSyncLockOwner(lockPath));
+            }
+            rmSync(lockPath, { recursive: true, force: true });
+        }
+    }
+}
+function releaseServerSyncLock(lock) {
+    const owner = readServerSyncLockOwner(lock.lockPath);
+    if (owner?.token === lock.token) {
+        rmSync(lock.lockPath, { recursive: true, force: true });
+    }
+}
+function readServerSyncLockOwner(lockPath) {
+    try {
+        return JSON.parse(readFileSync(join(lockPath, 'owner.json'), 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+function isServerSyncLockStale(lockPath) {
+    const owner = readServerSyncLockOwner(lockPath);
+    const ageMs = getServerSyncLockAgeMs(lockPath, owner);
+    if (!owner || typeof owner !== 'object')
+        return ageMs > SYNC_LOCK_OWNER_STALE_MS;
+    if (owner.hostname && owner.hostname !== hostname()) {
+        return ageMs > SYNC_LOCK_ALIVE_HARD_STALE_MS;
+    }
+    if (owner.pid && !isProcessAlive(owner.pid))
+        return true;
+    if (owner.pid && isProcessAlive(owner.pid))
+        return false;
+    return ageMs > SYNC_LOCK_OWNER_STALE_MS;
+}
+function getServerSyncLockAgeMs(lockPath, owner) {
+    const startedAt = owner?.startedAt ? new Date(owner.startedAt).getTime() : NaN;
+    if (Number.isFinite(startedAt))
+        return Math.max(0, Date.now() - startedAt);
+    try {
+        return Math.max(0, Date.now() - statSync(lockPath).mtimeMs);
+    }
+    catch {
+        return Number.POSITIVE_INFINITY;
+    }
+}
+function isProcessAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return isFsErrorCode(error, 'EPERM');
+    }
+}
+function formatSyncLockedMessage(owner) {
+    const parts = [];
+    if (owner?.operation)
+        parts.push(`owner=${owner.operation}`);
+    if (owner?.pid)
+        parts.push(`pid=${owner.pid}`);
+    if (owner?.startedAt)
+        parts.push(`startedAt=${owner.startedAt}`);
+    const suffix = parts.length ? ` (${parts.join(', ')})` : '';
+    return `SYNC_LOCKED: Sync is already running${suffix}`;
+}
+function isSyncLockedError(error) {
+    const code = typeof error === 'object' && error !== null && 'code' in error ? String(error.code) : '';
+    const message = error instanceof Error ? error.message : String(error);
+    return code === 'SYNC_LOCKED' || /SYNC_LOCKED/i.test(message);
+}
+function syncLockedResponse(error) {
+    const message = error instanceof SyncLockedError
+        ? error.message
+        : normalizeSyncLockedMessage(error instanceof Error ? error.message : String(error));
+    return json({ error: message }, { status: 423 });
+}
+function normalizeSyncLockedMessage(message) {
+    const trimmed = stripAnsi(message).trim();
+    if (/^SYNC_LOCKED:/i.test(trimmed))
+        return trimmed;
+    const match = trimmed.match(/SYNC_LOCKED:.*$/ims);
+    return match ? match[0].trim() : 'SYNC_LOCKED: Sync is already running';
+}
+function stripAnsi(value) {
+    return value.replace(/\x1B\[[0-9;]*m/g, '');
+}
+function isFsErrorCode(error, code) {
+    return typeof error === 'object' && error !== null && 'code' in error && error.code === code;
+}
+function readJsonFile(filePath, opts = {}) {
+    let raw = '';
     try {
-        return JSON.parse(readFileSync(filePath, 'utf-8'));
+        raw = readFileSync(filePath, 'utf-8');
     }
     catch {
         return {};
     }
+    try {
+        return JSON.parse(stripBom(raw));
+    }
+    catch (error) {
+        if (!opts.reportParseError)
+            return {};
+        const detail = error instanceof Error ? error.message : String(error);
+        return {
+            __readError: `MindOS config file could not be read: ${detail}`,
+            __readErrorPath: filePath,
+        };
+    }
+}
+function stripBom(value) {
+    return value.charCodeAt(0) === 0xFEFF ? value.slice(1) : value;
+}
+function getConfigReadError(config) {
+    return typeof config.__readError === 'string' && config.__readError ? config.__readError : null;
+}
+function stripInternalConfigFields(config) {
+    const { __readError, __readErrorPath, ...rest } = config;
+    return rest;
+}
+function backupUnreadableConfig(services) {
+    const configPath = services.configPath ?? DEFAULT_CONFIG_PATH;
+    if (services.readConfig || services.writeConfig || !existsSync(configPath))
+        return;
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    try {
+        renameSync(configPath, `${configPath}.broken-${stamp}`);
+    }
+    catch { }
 }
 function atomicWriteJson(filePath, data) {
     const dir = dirname(filePath);
@@ -298,12 +718,27 @@ function callGetBranch(services, cwd) {
 function callGetUnpushedCount(services, cwd) {
     if (services.getUnpushedCount)
         return services.getUnpushedCount(cwd);
+    let unpushedCommits = null;
+    let dirtyFiles = null;
     try {
-        return runGit(cwd, ['rev-list', '--count', '@{u}..HEAD']);
+        const raw = runGit(cwd, ['rev-list', '--count', '@{u}..HEAD']);
+        const parsed = Number.parseInt(raw, 10);
+        if (Number.isFinite(parsed))
+            unpushedCommits = parsed;
     }
-    catch {
-        return '?';
+    catch { }
+    try {
+        const status = runGit(cwd, ['status', '--porcelain=v1']);
+        dirtyFiles = status
+            ? status.split('\n').filter(line => line.trim() && !line.slice(3).endsWith('.sync-conflict')).length
+            : 0;
     }
+    catch { }
+    if (unpushedCommits === null && dirtyFiles === null)
+        return '?';
+    if (unpushedCommits === null && dirtyFiles === 0)
+        return '?';
+    return String((unpushedCommits || 0) + (dirtyFiles || 0));
 }
 function runGit(cwd, args) {
     return execFileSync('git', args, {
@@ -312,6 +747,42 @@ function runGit(cwd, args) {
         stdio: ['ignore', 'pipe', 'ignore'],
     }).trim();
 }
+export function redactGitRemote(remote) {
+    if (!remote)
+        return null;
+    if (!/^https?:\/\//i.test(remote))
+        return remote;
+    try {
+        const parsed = new URL(remote);
+        parsed.username = '';
+        parsed.password = '';
+        return parsed.toString();
+    }
+    catch {
+        return remote.replace(/^(https?:\/\/)[^/@]+@/i, '$1');
+    }
+}
+function looksLikeAccessToken(value) {
+    return /^(gh[pousr]_|github_pat_|glpat-|pat_)/i.test(value);
+}
+function normalizeHttpsRemoteCredentials(remote, token) {
+    if (!/^https?:\/\//i.test(remote))
+        return { remote, token };
+    try {
+        const parsed = new URL(remote);
+        const embeddedPassword = parsed.password ? decodeURIComponent(parsed.password) : '';
+        const embeddedUsername = parsed.username ? decodeURIComponent(parsed.username) : '';
+        parsed.username = '';
+        parsed.password = '';
+        return {
+            remote: parsed.toString(),
+            token: token || embeddedPassword || (looksLikeAccessToken(embeddedUsername) ? embeddedUsername : undefined),
+        };
+    }
+    catch {
+        return { remote, token };
+    }
+}
 function isPathWithinMindRoot(mindRoot, filePath) {
     return resolveMindRootPath(mindRoot, filePath) !== null;
 }
@@ -323,12 +794,12 @@ function resolveMindRootPath(mindRoot, filePath) {
         return null;
     }
 }
-async function runCli(args, timeoutMs, services) {
+async function runCli(args, timeoutMs, services, envOverrides) {
     if (services.runCli) {
-        await services.runCli(args, timeoutMs);
+        await services.runCli(args, timeoutMs, envOverrides);
         return;
     }
-    const env = services.env ?? process.env;
+    const env = { ...(services.env ?? process.env), ...(envOverrides ?? {}) };
     const nodeBin = services.nodeBin ?? env.MINDOS_NODE_BIN ?? process.execPath;
     const cliPath = services.cliPath ?? resolveMindosCliPath({
         env,
@@ -336,7 +807,7 @@ async function runCli(args, timeoutMs, services) {
         projectRoot: services.projectRoot,
     });
     await new Promise((resolveDone, rejectDone) => {
-        execFile(nodeBin, [cliPath, ...args], { timeout: timeoutMs, encoding: 'utf-8' }, (error, stdout, stderr) => {
+        execFile(nodeBin, [cliPath, ...args], { timeout: timeoutMs, encoding: 'utf-8', env }, (error, stdout, stderr) => {
             if (error)
                 rejectDone(new Error(formatProcessError(error, stdout, stderr)));
             else