hafez 1.0.1

package/dist/digest.js

@@ -0,0 +1,94 @@
+// src/digest.ts
+import { z } from 'zod';
+// --- Schema ---
+export const DigestInputSchema = z.object({
+    entities_touched: z.array(z.string())
+        .describe('Slugs of entities worked on. Each gets a session log entry; the session note links them all. Unknown slugs warn on stderr and are omitted.'),
+    decisions: z.array(z.string())
+        .describe('Key decisions made this session (may be empty). Recorded in the session note.')
+        .default([]),
+    narrative: z.string().min(1)
+        .describe('1-3 sentence cross-cutting summary — what happened, connections discovered.'),
+    session_date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'Must be YYYY-MM-DD')
+        .describe('Session date, YYYY-MM-DD.'),
+    agent: z.string()
+        .describe('Agent identifier recorded in session logs.')
+        .default('claude'),
+});
+/**
+ * Validate and parse raw digest input from stdin.
+ * Returns unknown fields so callers can warn on stderr.
+ * Uses strict() parse to detect unknown keys, then normal parse for the clean result.
+ */
+export function parseDigestInput(raw) {
+    const result = DigestInputSchema.safeParse(raw);
+    if (!result.success) {
+        return { success: false, error: result.error };
+    }
+    // Detect unknown fields via strict parse (Zod's unrecognized_keys error code)
+    const unknownFields = [];
+    const strictResult = DigestInputSchema.strict().safeParse(raw);
+    if (!strictResult.success) {
+        for (const issue of strictResult.error.issues) {
+            if (issue.code === 'unrecognized_keys')
+                unknownFields.push(...issue.keys);
+        }
+    }
+    return { success: true, data: result.data, unknownFields };
+}
+/**
+ * Convert session context into a hafez batch payload.
+ * Pure function — no file I/O, no vault access.
+ * Unknown slugs in entities_touched are silently omitted (caller should warn).
+ */
+export function digest(input, existingSlugs, now = new Date()) {
+    const ops = [];
+    // 1. Session log updates for each known slug
+    const knownTouched = input.entities_touched.filter(s => existingSlugs.has(s));
+    for (const slug of knownTouched) {
+        const sessionLogSummary = buildSessionLogSummary(input);
+        const fields = {
+            session_log: {
+                type: 'progress',
+                summary: sessionLogSummary,
+                agent: input.agent,
+            },
+        };
+        ops.push({ op: 'update', slug, fields });
+    }
+    // 2. Session note — built from known slugs only, so unknown slugs never
+    //    leak into the note body (the schema promises they are omitted).
+    const noteBody = buildSessionNoteBody(input, knownTouched);
+    const related = knownTouched;
+    const noteFields = {
+        synthesis: noteBody,
+        'session-date': input.session_date,
+        ...(related.length > 0 ? { related } : {}),
+    };
+    const noteName = `Session ${input.session_date} ${now.toISOString().slice(11, 19)}`;
+    ops.push({ op: 'create', kind: 'session', name: noteName, fields: noteFields });
+    return ops;
+}
+// --- Helpers ---
+function buildSessionLogSummary(input) {
+    const parts = [input.narrative.trim()];
+    if (input.decisions.length > 0) {
+        parts.push(`Decisions: ${input.decisions.join('; ')}`);
+    }
+    return parts.join(' | ');
+}
+function buildSessionNoteBody(input, knownTouched) {
+    const lines = [input.narrative.trim()];
+    if (input.decisions.length > 0) {
+        lines.push('');
+        lines.push('**Decisions:**');
+        for (const d of input.decisions) {
+            lines.push(`- ${d}`);
+        }
+    }
+    if (knownTouched.length > 0) {
+        lines.push('');
+        lines.push(`**Entities touched:** ${knownTouched.join(', ')}`);
+    }
+    return lines.join('\n');
+}

package/dist/export-okf.d.ts

@@ -0,0 +1,12 @@
+export interface OkfExportReport {
+    outDir: string;
+    entities: number;
+    knowledge: number;
+    sessions: number;
+    skipped: Array<{
+        file: string;
+        reason: string;
+    }>;
+    unresolvedLinks: number;
+}
+export declare function exportOkf(vaultPath: string, outDir: string): OkfExportReport;

package/dist/export-okf.js

@@ -0,0 +1,176 @@
+// src/export-okf.ts
+// Read-only export of the vault as an OKF v0.1 bundle (entities + knowledge + sessions).
+// Spec: https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md
+// Pure sync function — no Hafez instance, index, git, or lock (mirrors migrate-*.ts).
+// Re-export overwrites a prior bundle in place but never deletes: files for vault
+// docs renamed or removed since the last export linger (unreferenced by the
+// regenerated indexes) until the bundle directory is deleted and re-exported.
+import { readdirSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { join, resolve, sep, basename } from 'path';
+import { parseFilePath, serializeFile } from './vault.js';
+import { deriveSummary } from './sections.js';
+const KIND_DIRS = [
+    { dir: 'entities', kind: 'entity' },
+    { dir: 'knowledge', kind: 'knowledge' },
+    { dir: 'sessions', kind: 'session' },
+];
+// Local capturing variant of the shared WIKI_LINK_RE — captures display text in
+// group 2, which the shared regex's consumers don't need.
+const OKF_LINK_RE = /\[\[([^\]|]+)(?:\|([^\]]+))?\]\]/g;
+function scanDir(dirPath) {
+    try {
+        return readdirSync(dirPath).filter(f => f.endsWith('.md')).map(f => join(dirPath, f));
+    }
+    catch {
+        return [];
+    }
+}
+function mapFrontmatter(doc) {
+    const { fm, kind, body } = doc;
+    const mapped = {};
+    if (kind === 'entity')
+        mapped.type = fm.type ?? 'entity';
+    else if (kind === 'knowledge')
+        mapped.type = fm.subtype ? `knowledge/${fm.subtype}` : 'knowledge';
+    else
+        mapped.type = 'session';
+    mapped.title = fm.name;
+    const description = deriveSummary(kind, fm, body);
+    if (description)
+        mapped.description = description;
+    if (kind === 'entity' && fm.resource)
+        mapped.resource = fm.resource;
+    if (fm.tags)
+        mapped.tags = fm.tags;
+    let timestamp;
+    if (kind === 'entity')
+        timestamp = fm['last-touched'] ?? fm.created;
+    else if (kind === 'knowledge')
+        timestamp = fm['last-reinforced'] ?? fm.created;
+    else
+        timestamp = fm['session-date'] ?? fm.created;
+    if (timestamp)
+        mapped.timestamp = timestamp;
+    // Carry all remaining original keys verbatim; drop only name (mapped to title).
+    const consumed = new Set(['name', 'type', 'description', 'resource', 'tags']);
+    for (const [key, value] of Object.entries(fm)) {
+        if (!consumed.has(key) && !(key in mapped))
+            mapped[key] = value;
+    }
+    return mapped;
+}
+export function exportOkf(vaultPath, outDir) {
+    const resolvedVault = resolve(vaultPath);
+    const resolvedOut = resolve(outDir);
+    if (resolvedOut === resolvedVault || resolvedOut.startsWith(resolvedVault + sep)) {
+        throw new Error(`Export target ${resolvedOut} is inside the vault. Pass --out <path> outside the vault.`);
+    }
+    if (existsSync(resolvedOut)) {
+        const existing = readdirSync(resolvedOut);
+        if (existing.length > 0) {
+            const rootIndex = join(resolvedOut, 'index.md');
+            let isPriorBundle = false;
+            if (existsSync(rootIndex)) {
+                try {
+                    isPriorBundle = parseFilePath(rootIndex).frontmatter.okf_version !== undefined;
+                }
+                catch { /* unparseable — treat as not a bundle */ }
+            }
+            if (!isPriorBundle) {
+                throw new Error(`Export target ${resolvedOut} is non-empty and not a prior OKF bundle. Refusing to write.`);
+            }
+        }
+    }
+    const report = {
+        outDir: resolvedOut, entities: 0, knowledge: 0, sessions: 0,
+        skipped: [], unresolvedLinks: 0,
+    };
+    // Enumerate and parse. Sessions are not in SQLite — disk enumeration is required.
+    const docs = [];
+    for (const { dir, kind } of KIND_DIRS) {
+        for (const filePath of scanDir(join(resolvedVault, dir))) {
+            const slug = basename(filePath, '.md');
+            const relFile = `${dir}/${slug}.md`;
+            let fm, body;
+            try {
+                const parsed = parseFilePath(filePath);
+                fm = parsed.frontmatter;
+                body = parsed.body;
+            }
+            catch (err) {
+                report.skipped.push({ file: relFile, reason: `failed to parse (${err.message})` });
+                process.stderr.write(`Warning: skipping ${relFile}: failed to parse\n`);
+                continue;
+            }
+            if (!fm.name) {
+                report.skipped.push({ file: relFile, reason: 'missing name' });
+                process.stderr.write(`Warning: skipping ${relFile}: missing name\n`);
+                continue;
+            }
+            docs.push({ slug, dir, kind, fm, body });
+        }
+    }
+    // Slug→dir map: insertion order entities/knowledge/sessions, first write wins,
+    // giving entity precedence on cross-kind slug collisions.
+    const slugDirs = new Map();
+    for (const doc of docs) {
+        if (!slugDirs.has(doc.slug))
+            slugDirs.set(doc.slug, doc.dir);
+    }
+    function transformBody(body) {
+        return body.replace(OKF_LINK_RE, (_m, rawSlug, rawDisplay) => {
+            // Trim: Obsidian-idiomatic [[ foo ]] / [[foo | Label]] carry whitespace in the captures
+            const slug = rawSlug.trim();
+            const label = rawDisplay?.trim() || slug;
+            const dir = slugDirs.get(slug);
+            if (!dir) {
+                report.unresolvedLinks++;
+                return label;
+            }
+            // Bundle-root-absolute path, hardcoded '/' separators
+            return `[${label}](/${dir}/${slug}.md)`;
+        });
+    }
+    mkdirSync(resolvedOut, { recursive: true });
+    const byDir = new Map();
+    for (const doc of docs) {
+        const mapped = mapFrontmatter(doc);
+        const outSubdir = join(resolvedOut, doc.dir);
+        mkdirSync(outSubdir, { recursive: true });
+        writeFileSync(join(outSubdir, `${doc.slug}.md`), serializeFile(mapped, transformBody(doc.body)));
+        if (doc.kind === 'entity')
+            report.entities++;
+        else if (doc.kind === 'knowledge')
+            report.knowledge++;
+        else
+            report.sessions++;
+        const list = byDir.get(doc.dir) ?? [];
+        list.push({ slug: doc.slug, title: mapped.title, description: mapped.description ?? '' });
+        byDir.set(doc.dir, list);
+    }
+    // Per-dir index.md — reserved file: NO frontmatter, sorted bullets
+    for (const [dir, items] of byDir) {
+        const heading = dir.charAt(0).toUpperCase() + dir.slice(1);
+        const lines = [`# ${heading}`, ''];
+        for (const item of items.sort((a, b) => a.title.localeCompare(b.title))) {
+            const desc = item.description ? ` — ${item.description}` : '';
+            lines.push(`- [${item.title}](/${dir}/${item.slug}.md)${desc}`);
+        }
+        writeFileSync(join(resolvedOut, dir, 'index.md'), lines.join('\n') + '\n');
+    }
+    // Root index.md — the only place okf_version may appear
+    const counts = [
+        ['entities', report.entities],
+        ['knowledge', report.knowledge],
+        ['sessions', report.sessions],
+    ];
+    const rootLines = ['# Vault Export', ''];
+    for (const [dir, count] of counts) {
+        if (count === 0)
+            continue;
+        const heading = dir.charAt(0).toUpperCase() + dir.slice(1);
+        rootLines.push(`- [${heading}](/${dir}/index.md) — ${count} concepts`);
+    }
+    writeFileSync(join(resolvedOut, 'index.md'), serializeFile({ okf_version: '0.1' }, rootLines.join('\n')));
+    return report;
+}

package/dist/git.d.ts

@@ -0,0 +1,12 @@
+import { type GitConfig, type ChangelogEntry } from './types.js';
+/**
+ * Bidirectional sync: pull remote changes, push local commits.
+ * All work must be committed before calling — no file save/restore needed.
+ */
+export declare function gitSync(vaultPath: string): Promise<{
+    pulled: boolean;
+    pushed: boolean;
+    remote: boolean;
+}>;
+export declare function gitChangelog(vaultPath: string, since: string): Promise<ChangelogEntry[]>;
+export declare function gitCommitAndPush(vaultPath: string, files: string[], message: string, config?: GitConfig): Promise<void>;

package/dist/git.js

@@ -0,0 +1,355 @@
+// src/git.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { simpleGit } from 'simple-git';
+import { mergeVaultContent } from './merge.js';
+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;
+function isRebaseInProgress(vaultPath) {
+    return (existsSync(join(vaultPath, '.git', 'rebase-merge')) ||
+        existsSync(join(vaultPath, '.git', 'rebase-apply')));
+}
+function isMergeInProgress(vaultPath) {
+    return existsSync(join(vaultPath, '.git', 'MERGE_HEAD'));
+}
+/**
+ * Abort any in-progress rebase or merge, restoring the repo to a clean state.
+ * Silently ignores "nothing to abort" errors (TOCTOU race: another process
+ * may have resolved the state between our check and the abort call).
+ */
+async function ensureCleanState(git, vaultPath) {
+    if (isRebaseInProgress(vaultPath)) {
+        try {
+            await git.rebase(['--abort']);
+        }
+        catch {
+            // Already resolved by another process — safe to ignore
+        }
+    }
+    if (isMergeInProgress(vaultPath)) {
+        try {
+            await git.raw(['merge', '--abort']);
+        }
+        catch {
+            // Already resolved by another process — safe to ignore
+        }
+    }
+}
+const VAULT_FILE_RE = /^(?:entities|knowledge|sessions)\/.+\.md$/;
+/**
+ * True if the vault repo has an `origin` remote. A local-only vault (the
+ * default the README setup produces) has none — every pull/push must be
+ * skipped for it, silently: the commit IS the whole job.
+ */
+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'));
+    }
+    // Get remote content and merge — all done BEFORE any destructive ops
+    const mergedContents = new Map();
+    try {
+        for (const file of files) {
+            let remoteContent;
+            try {
+                remoteContent = await git.show(`origin/${branch}:${file}`);
+            }
+            catch {
+                // File doesn't exist on remote — no merge needed, keep local
+                mergedContents.set(file, localContents.get(file));
+                continue;
+            }
+            mergedContents.set(file, mergeVaultContent(remoteContent, localContents.get(file)));
+        }
+    }
+    catch {
+        // Merge failed (malformed content, etc.) — local commit is still intact
+        return false;
+    }
+    // --- Destructive section: reset + rewrite ---
+    // If anything fails below, restore the local commit
+    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.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;
+        }
+        await git.commit(message);
+        logMerge(`semantic merge succeeded for: ${files.join(', ')}`);
+        return true;
+    }
+    catch (err) {
+        // Restore local commit — "changes saved locally" must remain true
+        logMerge(`merge failed after reset, restoring local commit ${localSHA}: ${err}`);
+        try {
+            await git.reset(['--hard', localSHA]);
+        }
+        catch { /* last resort failed */ }
+        return false;
+    }
+}
+/**
+ * Bidirectional sync: pull remote changes, push local commits.
+ * All work must be committed before calling — no file save/restore needed.
+ */
+export async function gitSync(vaultPath) {
+    const git = simpleGit(vaultPath);
+    if (!(await hasOriginRemote(git))) {
+        return { pulled: false, pushed: false, remote: false };
+    }
+    // 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);
+    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 });
+            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 (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]);
+            }
+            await new Promise((resolve) => setTimeout(resolve, RETRY_BASE_MS * attempt));
+        }
+    }
+    // Check if there are local commits to push
+    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));
+        }
+    }
+    return { pulled, pushed: false, remote: true }; // unreachable, but satisfies TS
+}
+/** Get list of files with unresolved conflicts */
+async function getConflictingFiles(git) {
+    try {
+        const output = await git.diff(['--name-only', '--diff-filter=U']);
+        return output.split('\n').map(f => f.trim()).filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+const FILE_STATUS_MAP = {
+    A: 'created',
+    M: 'updated',
+    D: 'deleted',
+};
+export async function gitChangelog(vaultPath, since) {
+    const git = simpleGit(vaultPath);
+    let output;
+    try {
+        output = await git.raw([
+            'log', `--since=${since}`, '--name-status',
+            '--pretty=format:%H|%aI|%s', '--', 'entities/', 'knowledge/',
+        ]);
+    }
+    catch {
+        return []; // No git history or invalid since — return empty
+    }
+    if (!output.trim())
+        return [];
+    const entries = [];
+    const blocks = output.split(/\n(?=[0-9a-f]{40}\|)/);
+    for (const block of blocks) {
+        const lines = block.split('\n').filter(l => l.trim());
+        if (lines.length === 0)
+            continue;
+        const headerMatch = lines[0].match(/^([0-9a-f]+)\|(.+?)\|(.*)$/);
+        if (!headerMatch)
+            continue;
+        const [, , timestamp, commit_message] = headerMatch;
+        for (let i = 1; i < lines.length; i++) {
+            const fileMatch = lines[i].match(/^([AMDRC])\t(.+)$/);
+            if (!fileMatch)
+                continue;
+            const [, statusChar, filePath] = fileMatch;
+            const operation = FILE_STATUS_MAP[statusChar];
+            if (!operation)
+                continue;
+            let kind;
+            let slug;
+            if (filePath.startsWith('entities/')) {
+                kind = 'entity';
+                slug = filePath.replace('entities/', '').replace('.md', '');
+            }
+            else if (filePath.startsWith('knowledge/')) {
+                kind = 'knowledge';
+                slug = filePath.replace('knowledge/', '').replace('.md', '');
+            }
+            else {
+                continue;
+            }
+            entries.push({ slug, kind, operation, timestamp, commit_message });
+        }
+    }
+    return entries;
+}
+export async function gitCommitAndPush(vaultPath, files, message, config = {}) {
+    const git = simpleGit(vaultPath);
+    // If a previous run crashed mid-rebase/merge, the repo is stuck.
+    // Aborting restores tracked files to their pre-rebase state, which may
+    // overwrite files that index.ts just wrote. Save and restore them.
+    if (isRebaseInProgress(vaultPath) || isMergeInProgress(vaultPath)) {
+        const saved = new Map();
+        for (const f of files) {
+            const full = join(vaultPath, f);
+            if (existsSync(full))
+                saved.set(full, readFileSync(full));
+        }
+        await ensureCleanState(git, vaultPath);
+        for (const [fullPath, content] of saved) {
+            writeFileSync(fullPath, content);
+        }
+    }
+    await git.add(files);
+    // Handle "nothing to commit" (e.g., idempotent update wrote identical content)
+    const status = await git.status();
+    if (status.staged.length === 0)
+        return;
+    await git.commit(message);
+    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));
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import type { Hafez, HafezConfig } from './types.js';
+export declare function createHafez(config: HafezConfig): Hafez;
+export { HafezError } from './types.js';
+export type { Hafez, HafezConfig, HafezErrorCode, EntityType, EntityStatus, EntityQueryOpts, KnowledgeQueryOpts, EntityFrontmatter, KnowledgeFrontmatter, ParsedFile, SessionLogEntry, UpdateFields, UpdateResult, CreateEntityFields, CreateKnowledgeFields, QueryFilter, QueryResult, KnowledgeQueryResult, UnifiedResult, ValidationReport, BatchOperation, BatchResult, ReadDepth, ConfidenceLevel, LinkRelation, GitConfig, SearchResult, VaultStats, ChangelogEntry, KnowledgeSubtype } from './types.js';
+export { getBrief, getNextActions, findSection } from './sections.js';
+export { parseSessionLogHeading, parseSessionLog } from './parser.js';
+export { formatStats, formatChangelog, formatValidation } from './cli/format.js';