hafez 1.0.1 → 1.0.2

package/dist/git.js

@@ -7,6 +7,9 @@ import { HafezError } from './types.js';
 const logMerge = (msg) => process.stderr.write(`[hafez-merge] ${msg}\n`);
 const MAX_PUSH_RETRIES = 3;
 const RETRY_BASE_MS = 200;
+// A pull --rebase replays one local commit at a time; each can stop on a
+// conflict. Bound the resolution loop far above any realistic commit count.
+const MAX_REBASE_STEPS = 50;
 function isRebaseInProgress(vaultPath) {
     return (existsSync(join(vaultPath, '.git', 'rebase-merge')) ||
         existsSync(join(vaultPath, '.git', 'rebase-apply')));
@@ -47,66 +50,166 @@ async function hasOriginRemote(git) {
     const remotes = await git.getRemotes();
     return remotes.some(r => r.name === 'origin');
 }
-async function attemptSemanticMerge(git, vaultPath, files, message) {
-    // Only merge vault files — non-vault files fall through to error
-    if (!files.every(f => VAULT_FILE_RE.test(f)))
-        return false;
-    logMerge(`conflict detected, attempting semantic merge for: ${files.join(', ')}`);
-    const branch = (await git.branchLocal()).current;
-    // Save local commit SHA so we can restore if merge fails after reset
-    const localSHA = (await git.log(['-1'])).latest.hash;
-    // Read local content from working tree (preserved after rebase abort)
-    const localContents = new Map();
-    for (const file of files) {
-        localContents.set(file, readFileSync(join(vaultPath, file), 'utf-8'));
+/** Read one side of a conflicted file from the index; null if that side deleted it. */
+async function showStage(git, stage, file) {
+    try {
+        return await git.show([`:${stage}:${file}`]);
+    }
+    catch (err) {
+        // Only a genuinely absent stage means "this side deleted the file". Any
+        // other failure (spawn error, repo corruption) must abort resolution —
+        // treating it as a deletion would silently drop that side's content.
+        if (/not at stage|does not exist/i.test(String(err)))
+            return null;
+        throw err;
+    }
+}
+/**
+ * Resolve a conflicted in-progress rebase by semantically merging each
+ * conflicting vault file and continuing the rebase — never by resetting.
+ * Every non-conflicting local commit is replayed untouched, so nothing
+ * outside the conflicting files can be lost.
+ *
+ * On failure (non-vault conflicts, malformed content, unexpected git error)
+ * the rebase is aborted, which restores the local branch exactly as it was
+ * before the pull. Returns the conflicting files either way, for error messages.
+ */
+async function resolveRebaseConflicts(git, vaultPath) {
+    let lastFiles = [];
+    // Only rebase conflicts are resolvable here. A merge (MERGE_HEAD) can only
+    // come from an interrupted non-rebase pull, which hafez never runs — abort it.
+    if (isMergeInProgress(vaultPath)) {
+        await ensureCleanState(git, vaultPath);
+        return { resolved: false, files: [] };
     }
-    // Get remote content and merge — all done BEFORE any destructive ops
-    const mergedContents = new Map();
     try {
-        for (const file of files) {
-            let remoteContent;
+        for (let step = 0; step < MAX_REBASE_STEPS && isRebaseInProgress(vaultPath); step++) {
+            const conflictFiles = await getConflictingFiles(git);
+            if (conflictFiles.length > 0)
+                lastFiles = conflictFiles;
+            if (!conflictFiles.every(f => VAULT_FILE_RE.test(f))) {
+                await ensureCleanState(git, vaultPath);
+                return { resolved: false, files: conflictFiles };
+            }
+            if (conflictFiles.length > 0) {
+                logMerge(`conflict detected, attempting semantic merge for: ${conflictFiles.join(', ')}`);
+            }
+            for (const file of conflictFiles) {
+                // During a rebase, stage 2 ("ours") is the upstream/remote side and
+                // stage 3 ("theirs") is the local commit being replayed.
+                const remoteContent = await showStage(git, 2, file);
+                const localContent = await showStage(git, 3, file);
+                if (remoteContent === null && localContent === null) {
+                    // Deleted on both sides — accept the deletion
+                    await git.raw(['rm', '--force', '--ignore-unmatch', '--', file]);
+                    continue;
+                }
+                const merged = localContent === null ? remoteContent
+                    : remoteContent === null ? localContent
+                        : mergeVaultContent(remoteContent, localContent);
+                const fullPath = join(vaultPath, file);
+                mkdirSync(dirname(fullPath), { recursive: true });
+                writeFileSync(fullPath, merged);
+                await git.add([file]);
+            }
+            // Decide structurally whether this step still has anything to commit:
+            // no staged paths means the merged result is identical to the already-
+            // applied tree, so the replayed commit became empty and must be skipped.
+            // Output-based on purpose — never `--quiet` exit codes (simple-git
+            // swallows diff's silent exit 1) and never git's error prose (localized,
+            // and it quotes commit subjects; a false "empty" match would skip a
+            // real commit — the COR-1 bug class again).
+            const staged = (await git.raw(['diff', '--cached', '--name-only'])).trim();
+            const stepEmpty = staged.length === 0;
             try {
-                remoteContent = await git.show(`origin/${branch}:${file}`);
+                // Non-interactive: --continue reuses the replayed commit's message
+                await git.rebase([stepEmpty ? '--skip' : '--continue']);
             }
-            catch {
-                // File doesn't exist on remote — no merge needed, keep local
-                mergedContents.set(file, localContents.get(file));
-                continue;
+            catch (err) {
+                // --continue/--skip exit non-zero when the rebase stops again on the
+                // NEXT local commit's conflict. That is progress, not failure — the
+                // loop resolves the new conflicts on its next pass. Anything else
+                // (stuck with nothing to resolve) aborts via the outer catch.
+                const nextConflicts = await getConflictingFiles(git);
+                if (!isRebaseInProgress(vaultPath) || nextConflicts.length === 0) {
+                    throw err;
+                }
             }
-            mergedContents.set(file, mergeVaultContent(remoteContent, localContents.get(file)));
         }
+        if (isRebaseInProgress(vaultPath)) {
+            // Step budget exhausted — bail out safely
+            await ensureCleanState(git, vaultPath);
+            return { resolved: false, files: lastFiles };
+        }
+        if (lastFiles.length > 0)
+            logMerge(`semantic merge succeeded for: ${lastFiles.join(', ')}`);
+        return { resolved: true, files: lastFiles };
     }
-    catch {
-        // Merge failed (malformed content, etc.) — local commit is still intact
-        return false;
+    catch (err) {
+        logMerge(`semantic merge failed, restoring local state: ${err}`);
+        try {
+            await ensureCleanState(git, vaultPath);
+        }
+        catch { /* last resort failed */ }
+        return { resolved: false, files: lastFiles };
     }
-    // --- Destructive section: reset + rewrite ---
-    // If anything fails below, restore the local commit
+}
+/**
+ * One `pull --rebase` attempt, resolving vault-file conflicts inside the
+ * rebase. Throws HafezError when a conflict cannot be auto-resolved (the
+ * repo is left clean, local commits intact); rethrows the raw git error on
+ * transient failures so the caller can retry.
+ */
+async function pullResolving(git, vaultPath, conflictMessage) {
     try {
-        await git.reset(['--hard', `origin/${branch}`]);
-        for (const [file, content] of mergedContents) {
-            const fullPath = join(vaultPath, file);
-            mkdirSync(dirname(fullPath), { recursive: true });
-            writeFileSync(fullPath, content);
+        await git.pull('origin', undefined, { '--rebase': null });
+    }
+    catch (err) {
+        if (isRebaseInProgress(vaultPath) || isMergeInProgress(vaultPath)) {
+            const { resolved, files } = await resolveRebaseConflicts(git, vaultPath);
+            if (resolved)
+                return;
+            const detail = err instanceof Error ? err.message : String(err);
+            throw new HafezError('GIT_PUSH_FAILED', conflictMessage(files), [detail]);
         }
-        await git.add(files);
-        const status = await git.status();
-        if (status.staged.length === 0) {
-            // Contents identical after merge — nothing to commit, but we're on remote now
-            return true;
+        try {
+            await ensureCleanState(git, vaultPath);
         }
-        await git.commit(message);
-        logMerge(`semantic merge succeeded for: ${files.join(', ')}`);
-        return true;
+        catch { /* preserve error */ }
+        throw err;
     }
-    catch (err) {
-        // Restore local commit — "changes saved locally" must remain true
-        logMerge(`merge failed after reset, restoring local commit ${localSHA}: ${err}`);
+}
+/**
+ * Push local commits, pulling with rebase and resolving vault-file conflicts
+ * semantically when the push is rejected. Push-first: callers either just
+ * pulled (gitSync) or usually have a current remote view, so the extra
+ * round-trip only happens when the remote actually moved. Shared by gitSync
+ * and gitCommitAndPush — this is the single code path that decides whether
+ * local data survives a conflict.
+ */
+async function pushResolving(git, vaultPath, conflictMessage, exhaustedMessage) {
+    let lastDetail = '';
+    for (let attempt = 1; attempt <= MAX_PUSH_RETRIES; attempt++) {
         try {
-            await git.reset(['--hard', localSHA]);
+            await git.push();
+            return;
+        }
+        catch (pushErr) {
+            lastDetail = pushErr instanceof Error ? pushErr.message : String(pushErr);
+            // Rejected (remote moved) or transient — integrate remote, then retry
+            try {
+                await pullResolving(git, vaultPath, conflictMessage);
+            }
+            catch (err) {
+                if (err instanceof HafezError)
+                    throw err;
+                lastDetail = err instanceof Error ? err.message : String(err);
+            }
+            if (attempt === MAX_PUSH_RETRIES) {
+                throw new HafezError('GIT_PUSH_FAILED', exhaustedMessage, [lastDetail]);
+            }
+            await new Promise((resolve) => setTimeout(resolve, RETRY_BASE_MS * attempt));
         }
-        catch { /* last resort failed */ }
-        return false;
     }
 }
 /**
@@ -121,40 +224,20 @@ export async function gitSync(vaultPath) {
     // Clean up any stuck rebase/merge from a previous crash.
     // Safe to abort without saving files — all work is already committed.
     await ensureCleanState(git, vaultPath);
+    const syncConflictMessage = (files) => `Git conflict during sync (files: ${files.join(', ')}). Changes saved locally.`;
     let pulled = false;
     // Always pull first (bidirectional sync)
     const headBefore = (await git.revparse(['HEAD'])).trim();
     for (let attempt = 1; attempt <= MAX_PUSH_RETRIES; attempt++) {
         try {
-            await git.pull('origin', undefined, { '--rebase': null });
+            await pullResolving(git, vaultPath, syncConflictMessage);
             const headAfter = (await git.revparse(['HEAD'])).trim();
             pulled = headAfter !== headBefore;
             break;
         }
         catch (err) {
-            const hadConflict = isRebaseInProgress(vaultPath) || isMergeInProgress(vaultPath);
-            if (hadConflict) {
-                // Discover conflicting files from git status
-                const conflictFiles = await getConflictingFiles(git);
-                try {
-                    await ensureCleanState(git, vaultPath);
-                }
-                catch { /* preserve error */ }
-                if (conflictFiles.length > 0) {
-                    const merged = await attemptSemanticMerge(git, vaultPath, conflictFiles, `sync: resolve conflicts`);
-                    if (merged) {
-                        pulled = true;
-                        break;
-                    }
-                }
-                // Merge not possible
-                const detail = err instanceof Error ? err.message : String(err);
-                throw new HafezError('GIT_PUSH_FAILED', `Git conflict during sync (files: ${conflictFiles.join(', ')}). Changes saved locally.`, [detail]);
-            }
-            try {
-                await ensureCleanState(git, vaultPath);
-            }
-            catch { /* preserve error */ }
+            if (err instanceof HafezError)
+                throw err;
             if (attempt === MAX_PUSH_RETRIES) {
                 const detail = err instanceof Error ? err.message : String(err);
                 throw new HafezError('GIT_PUSH_FAILED', `Git pull failed after ${MAX_PUSH_RETRIES} attempts during sync. Changes saved locally.`, [detail]);
@@ -166,46 +249,20 @@ export async function gitSync(vaultPath) {
     const ahead = await git.raw(['rev-list', '--count', '@{u}..HEAD']).then(s => parseInt(s.trim(), 10));
     if (ahead === 0)
         return { pulled, pushed: false, remote: true };
-    // Push local commits
-    for (let attempt = 1; attempt <= MAX_PUSH_RETRIES; attempt++) {
-        try {
-            await git.push();
-            return { pulled, pushed: true, remote: true };
-        }
-        catch (err) {
-            // Another writer may have pushed — pull and retry
-            try {
-                await git.pull('origin', undefined, { '--rebase': null });
-            }
-            catch (pullErr) {
-                const hadConflict = isRebaseInProgress(vaultPath) || isMergeInProgress(vaultPath);
-                if (hadConflict) {
-                    const conflictFiles = await getConflictingFiles(git);
-                    try {
-                        await ensureCleanState(git, vaultPath);
-                    }
-                    catch { /* preserve error */ }
-                    if (conflictFiles.length > 0) {
-                        const merged = await attemptSemanticMerge(git, vaultPath, conflictFiles, `sync: resolve conflicts`);
-                        if (merged)
-                            continue; // retry push
-                    }
-                }
-                else {
-                    try {
-                        await ensureCleanState(git, vaultPath);
-                    }
-                    catch { /* preserve error */ }
-                }
-            }
-            if (attempt === MAX_PUSH_RETRIES) {
-                const detail = err instanceof Error ? err.message : String(err);
-                throw new HafezError('GIT_PUSH_FAILED', `Git push failed after ${MAX_PUSH_RETRIES} attempts during sync. Changes saved locally.`, [detail]);
-            }
-            await new Promise((resolve) => setTimeout(resolve, RETRY_BASE_MS * attempt));
-        }
+    await pushResolving(git, vaultPath, syncConflictMessage, `Git push failed after ${MAX_PUSH_RETRIES} attempts during sync. Changes saved locally.`);
+    return { pulled, pushed: true, remote: true };
+}
+/**
+ * Unstage files (best effort). Used by batch rollback: a commit that fails
+ * after `git add` leaves the new blobs staged in .git/index, and the next
+ * successful commit would publish the rolled-back content under the wrong
+ * message. Clearing the index entries restores worktree/HEAD/index agreement.
+ */
+export async function gitUnstage(vaultPath, files) {
+    try {
+        await simpleGit(vaultPath).raw(['reset', '-q', 'HEAD', '--', ...files]);
     }
-    return { pulled, pushed: false, remote: true }; // unreachable, but satisfies TS
+    catch { /* best effort — rollback must not mask the original error */ }
 }
 /** Get list of files with unresolved conflicts */
 async function getConflictingFiles(git) {
@@ -294,62 +351,17 @@ export async function gitCommitAndPush(vaultPath, files, message, config = {}) {
     const status = await git.status();
     if (status.staged.length === 0)
         return;
-    await git.commit(message);
+    const committed = await git.commit(message);
+    // simple-git swallows some commit failures (e.g. a rejected pre-commit
+    // hook) into an empty result instead of throwing. Staged content with no
+    // commit hash means the commit did NOT land — surface it so callers
+    // (batch rollback in particular) treat it as a commit-stage failure.
+    if (!committed.commit) {
+        throw new HafezError('GIT_COMMIT_FAILED', `git commit produced no commit for: ${files.join(', ')}`);
+    }
     if (config.push === false)
         return;
     if (!(await hasOriginRemote(git)))
         return;
-    for (let attempt = 1; attempt <= MAX_PUSH_RETRIES; attempt++) {
-        try {
-            await git.pull('origin', undefined, { '--rebase': null });
-            await git.push();
-            return; // success
-        }
-        catch (err) {
-            const hadConflict = isRebaseInProgress(vaultPath) || isMergeInProgress(vaultPath);
-            // Always restore clean state before throwing or retrying.
-            // Wrap in try-catch to preserve the original error if abort fails.
-            try {
-                await ensureCleanState(git, vaultPath);
-            }
-            catch {
-                // Abort failed — repo may be in a bad state, but we still throw
-                // the original error so the caller gets useful diagnostics.
-            }
-            const detail = err instanceof Error ? err.message : String(err);
-            if (hadConflict) {
-                const merged = await attemptSemanticMerge(git, vaultPath, files, message);
-                if (merged) {
-                    // Try pushing the merged result
-                    try {
-                        await git.push();
-                        return; // success
-                    }
-                    catch (pushErr) {
-                        // One final retry: another writer may have pushed during our merge
-                        try {
-                            await git.pull('origin', undefined, { '--rebase': null });
-                            await git.push();
-                            return;
-                        }
-                        catch (retryErr) {
-                            try {
-                                await ensureCleanState(git, vaultPath);
-                            }
-                            catch { /* preserve original error */ }
-                            const retryDetail = retryErr instanceof Error ? retryErr.message : String(retryErr);
-                            throw new HafezError('GIT_PUSH_FAILED', `Git push failed after semantic merge. Changes saved locally.`, [retryDetail]);
-                        }
-                    }
-                }
-                // Merge not possible (non-vault files) — original behavior
-                throw new HafezError('GIT_PUSH_FAILED', `Git conflict with remote (files: ${files.join(', ')}). Changes saved locally.`, [detail]);
-            }
-            // Transient error (network, push race). Retry if attempts remain.
-            if (attempt === MAX_PUSH_RETRIES) {
-                throw new HafezError('GIT_PUSH_FAILED', `Git push failed after ${MAX_PUSH_RETRIES} attempts. Changes saved locally.`, [detail]);
-            }
-            await new Promise((resolve) => setTimeout(resolve, RETRY_BASE_MS * attempt));
-        }
-    }
+    await pushResolving(git, vaultPath, (conflictFiles) => `Git conflict with remote (files: ${conflictFiles.join(', ')}). Changes saved locally.`, `Git push failed after ${MAX_PUSH_RETRIES} attempts. Changes saved locally.`);
 }

package/dist/index.js

@@ -1,6 +1,6 @@
 // src/index.ts
 import { parseFilePath, serializeFile, slugify, resolveFilePath } from './vault.js';
-import { gitCommitAndPush, gitSync, gitChangelog } from './git.js';
+import { gitCommitAndPush, gitSync, gitChangelog, gitUnstage } from './git.js';
 import { validateEntityFrontmatter, validateKnowledgeFrontmatter, validateSessionLogEntry } from './schema.js';
 import { bodyTemplate, knowledgeBodyTemplate } from './templates.js';
 import { formatSessionLogEntry, countSessionLogEntries, extractOldestSessionLogEntry } from './parser.js';
@@ -12,15 +12,41 @@ import { generateVaultIndex } from './knowledge-index.js';
 import { HafezError } from './types.js';
 import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, appendFileSync, unlinkSync } from 'fs';
 import { join, relative, basename } from 'path';
+import { lock as lockVault } from 'proper-lockfile';
 export function createHafez(config) {
     const { vaultPath, readOnly = false, git: gitConfig = {}, onWrite } = config;
-    // Per-instance mutex — each createHafez() gets its own lock
+    // Two-level write lock: an in-process promise chain serializes calls within
+    // this instance, then a cross-process advisory lock (proper-lockfile, mkdir
+    // based — works on network/drvfs mounts) serializes against other hafez
+    // processes sharing the vault (concurrent CLIs, a bot, another agent).
     let lockPromise = Promise.resolve();
     function withLock(fn) {
         const prev = lockPromise;
         let release;
         lockPromise = new Promise(resolve => { release = resolve; });
-        return prev.then(fn).finally(() => release());
+        return prev.then(() => withVaultLock(fn)).finally(() => release());
+    }
+    async function withVaultLock(fn) {
+        let releaseVault = null;
+        try {
+            releaseVault = await lockVault(vaultPath, {
+                lockfilePath: join(vaultPath, '.hafez.lock'),
+                stale: 30_000,
+                retries: { retries: 20, minTimeout: 100, maxTimeout: 1_000, randomize: true },
+            });
+        }
+        catch (err) {
+            throw new HafezError('VAULT_LOCKED', 'Vault is locked by another hafez process. Retry when it finishes.', [err instanceof Error ? err.message : String(err)]);
+        }
+        try {
+            return await fn();
+        }
+        finally {
+            try {
+                await releaseVault();
+            }
+            catch { /* stale lock reclaimed by another process */ }
+        }
     }
     function entityPath(slug) { return resolveFilePath(vaultPath, slug, 'entity'); }
     function knowledgePath(slug) { return resolveFilePath(vaultPath, slug, 'knowledge'); }
@@ -33,12 +59,22 @@ export function createHafez(config) {
             return kp;
         return null;
     }
-    function exists(slug) { return findFile(slug) !== null; }
+    function exists(slug) {
+        // An invalid slug definitionally doesn't exist — reference checks (create
+        // parent/related, link targets, validate) must report "does not exist",
+        // not crash. validate() in particular exists to REPORT malformed refs.
+        try {
+            return findFile(slug) !== null;
+        }
+        catch {
+            return false;
+        }
+    }
     function today() { return new Date().toISOString().slice(0, 10); }
     function kindFromPath(filePath) {
         return filePath.includes('/entities/') ? 'entity' : 'knowledge';
     }
-    const ENTITY_ONLY_FIELDS = ['status', 'next_action', 'add_action', 'add_actions', 'complete_action', 'remove_action', 'clear_actions', 'brief', 'current_state', 'session_log', 'resource'];
+    const ENTITY_ONLY_FIELDS = ['status', 'add_action', 'add_actions', 'complete_action', 'remove_action', 'clear_actions', 'brief', 'current_state', 'session_log', 'resource'];
     const KNOWLEDGE_ONLY_FIELDS = ['confidence', 'synthesis', 'add_evidence', 'add_source'];
     function validateKindFields(kind, fields) {
         if (kind === 'knowledge') {
@@ -159,12 +195,6 @@ export function createHafez(config) {
     function applyUpdateFields(fm, body, fields) {
         if (fields.status !== undefined)
             fm.status = fields.status;
-        if (fields.next_action !== undefined) {
-            if (fields.next_action === null)
-                delete fm['next-action'];
-            else
-                fm['next-action'] = fields.next_action;
-        }
         if (fields.current_state !== undefined) {
             body = replaceSection(body, '## Current State', fields.current_state, '## Session Log');
         }
@@ -346,7 +376,6 @@ export function createHafez(config) {
             const kind = kindFromPath(filePath);
             validateKindFields(kind, fields);
             let { frontmatter: fm, body } = parseFilePath(filePath);
-            const previousNextAction = fm['next-action'] ?? null;
             const applied = applyUpdateFields(fm, body, fields);
             fm = applied.fm;
             body = applied.body;
@@ -371,7 +400,7 @@ export function createHafez(config) {
             getIndex().upsertFromFile(slug, kind);
             regenerateIndexSafe();
             onWrite?.(slug, 'update');
-            return { previous_next_action: previousNextAction, matched_action: applied.matchedAction };
+            return { matched_action: applied.matchedAction };
         });
     }
     async function link(slug, target, relation) {
@@ -618,8 +647,7 @@ export function createHafez(config) {
             }
             // Single git commit for all batch operations
             const uniqueFiles = [...new Set(modifiedFiles)];
-            if (uniqueFiles.length > 0) {
-                await gitCommitAndPush(vaultPath, uniqueFiles, `batch: ${operations.length} operations`, gitConfig);
+            const indexAfterBatch = () => {
                 for (const slug of affectedSlugs) {
                     const fp = findFile(slug);
                     if (fp) {
@@ -633,6 +661,38 @@ export function createHafez(config) {
                 }
                 for (const slug of affectedSlugs)
                     onWrite?.(slug, 'batch');
+            };
+            if (uniqueFiles.length > 0) {
+                try {
+                    await gitCommitAndPush(vaultPath, uniqueFiles, `batch: ${operations.length} operations`, gitConfig);
+                }
+                catch (err) {
+                    if (!(err instanceof HafezError && err.code === 'GIT_PUSH_FAILED')) {
+                        // Commit-stage failure (e.g. a raced .git/index.lock): nothing was
+                        // committed — restore the captured originals so files, git, and
+                        // index stay consistent instead of leaving the batch half-applied.
+                        for (const [path, content] of originals) {
+                            if (content === null) {
+                                try {
+                                    unlinkSync(path);
+                                }
+                                catch { }
+                            }
+                            else {
+                                writeFileSync(path, content);
+                            }
+                        }
+                        // Also clear anything the failed commit left staged, or the next
+                        // commit would publish the rolled-back content.
+                        await gitUnstage(vaultPath, uniqueFiles);
+                        throw err;
+                    }
+                    // Push-stage failure: the batch commit exists locally ("changes
+                    // saved locally") — keep it and index it, then surface the error.
+                    indexAfterBatch();
+                    throw err;
+                }
+                indexAfterBatch();
             }
             return results;
         });
@@ -822,7 +882,8 @@ export function createHafez(config) {
             catch (err) {
                 if (target === 'knowledge' && originalContent) {
                     writeFileSync(filePath, originalContent);
-                    if (knowledgeTarget && existsSync(knowledgeTarget))
+                    // Never unlink the file we just restored (SEC-4)
+                    if (knowledgeTarget && knowledgeTarget !== filePath && existsSync(knowledgeTarget))
                         unlinkSync(knowledgeTarget);
                 }
                 throw err;

package/dist/merge.js

@@ -10,13 +10,17 @@ const ARRAY_FIELDS_UNCAPPED = ['tags', 'domain', 'related'];
 export function mergeVaultContent(remote, local) {
     const r = parseContent(remote);
     const l = parseContent(local);
-    const fm = mergeFrontmatter(r.frontmatter, l.frontmatter);
-    const body = mergeBody(r.body, l.body);
+    // Scalar policy: the side with the newer last-touched wins; local on tie.
+    // Append-only sections (Session Log, Next Actions, Evidence, Sources) and
+    // array/date/count frontmatter fields are always unioned regardless.
+    const localWins = String(l.frontmatter?.['last-touched'] ?? '') >= String(r.frontmatter?.['last-touched'] ?? '');
+    const fm = mergeFrontmatter(r.frontmatter, l.frontmatter, localWins);
+    const body = mergeBody(r.body, l.body, localWins);
     return serializeFile(fm, body);
 }
-function mergeFrontmatter(remote, local) {
-    // Start with remote as base, overlay local (local wins for scalars)
-    const merged = { ...remote, ...local };
+function mergeFrontmatter(remote, local, localWins) {
+    // Overlay the winning side's scalars on top of the other's
+    const merged = localWins ? { ...remote, ...local } : { ...local, ...remote };
     // Date fields: latest wins
     for (const key of DATE_FIELDS) {
         const r = remote[key], l = local[key];
@@ -64,12 +68,12 @@ function splitSections(body) {
     }
     return { preamble, sections };
 }
-function mergeBody(remoteBody, localBody) {
+function mergeBody(remoteBody, localBody, localWins) {
     if (remoteBody === localBody)
         return localBody;
     const remote = splitSections(remoteBody);
     const local = splitSections(localBody);
-    // Build merged sections starting from local
+    // Build merged sections starting from local (local section order is canonical)
     const localHeadings = new Set(local.sections.map(s => s.heading));
     const mergedSections = [];
     for (const ls of local.sections) {
@@ -80,8 +84,15 @@ function mergeBody(remoteBody, localBody) {
         else if (ls.heading === '## Next Actions' && rs) {
             mergedSections.push({ heading: ls.heading, content: mergeNextActions(rs.content, ls.content) });
         }
+        else if ((ls.heading === '## Evidence' || ls.heading === '## Sources') && rs) {
+            // Append-only sections: union lines from both sides, dedup identical
+            mergedSections.push({ heading: ls.heading, content: mergeAppendOnlyLines(rs.content, ls.content) });
+        }
+        else if (rs && !localWins) {
+            // Scalar sections (Brief, Current State, Synthesis, ...): newer side wins
+            mergedSections.push(rs);
+        }
         else {
-            // Brief, Current State, anything else: local wins
             mergedSections.push(ls);
         }
     }
@@ -92,10 +103,26 @@ function mergeBody(remoteBody, localBody) {
         }
     }
     // Reassemble
-    const preamble = local.preamble || remote.preamble;
+    const preamble = localWins
+        ? (local.preamble || remote.preamble)
+        : (remote.preamble || local.preamble);
     const parts = [preamble, ...mergedSections.map(s => `${s.heading}\n\n${s.content}`)].filter(Boolean);
     return parts.join('\n\n');
 }
+/** Union merge for append-only free-text sections: local lines first, then
+ *  remote lines not already present. Blank lines are kept only from local. */
+function mergeAppendOnlyLines(remoteContent, localContent) {
+    if (remoteContent === localContent)
+        return localContent;
+    const localLines = localContent.split('\n');
+    const seen = new Set(localLines.map(l => l.trim()).filter(Boolean));
+    const remoteOnly = remoteContent
+        .split('\n')
+        .filter(l => l.trim() && !seen.has(l.trim()));
+    if (remoteOnly.length === 0)
+        return localContent;
+    return [...localLines, ...remoteOnly].join('\n');
+}
 function mergeSessionLogs(remoteContent, localContent) {
     const remoteEntries = parseLogEntries(remoteContent);
     const localEntries = parseLogEntries(localContent);