pi-hermes-memory 0.8.1 → 0.9.0

package/src/store/db.ts

@@ -4,6 +4,7 @@ import { createRequire } from 'node:module';
 import { SCHEMA_SQL } from './schema.js';
 import { AtomicLockCoordinator } from './atomic-lock-coordinator.js';
 import { canonicalStoragePathSync } from './canonical-storage-path.js';
+import { isBunRuntime, loadBetterSqlite3 } from './sqlite-native.js';
 
 type StatementLike = {
   run: (...args: any[]) => any;
@@ -69,6 +70,7 @@ class DatabaseCorruptionError extends Error {
   }
 }
 
+export const SQLITE_BUSY_TIMEOUT_MS = 5000;
 export const SQLITE_WAL_AUTOCHECKPOINT_PAGES = 1000;
 
 const DATABASE_FILE_SUFFIXES: readonly DatabaseFileSuffix[] = ['', '-wal', '-shm'];
@@ -118,24 +120,23 @@ function createBunCompatDatabaseCtor(require: NodeRequire): DatabaseCtor {
   };
 }
 
-function loadDatabaseCtor(): DatabaseCtor {
-  const require = createRequire(import.meta.url);
-  const isBunRuntime = typeof (globalThis as { Bun?: unknown }).Bun !== 'undefined';
-
-  if (isBunRuntime) {
-    return createBunCompatDatabaseCtor(require);
-  }
-
-  try {
-    const mod = require('better-sqlite3') as { default?: DatabaseCtor } | DatabaseCtor;
-    return (mod as { default?: DatabaseCtor }).default ?? (mod as DatabaseCtor);
-  } catch (err) {
-    throw err;
+let cachedDatabaseCtor: DatabaseCtor | null = null;
+
+/**
+ * Resolved on first use, never at import time. A module-scope native load turns
+ * any SQLite resolve/ABI failure into "Failed to load extension", which hides
+ * the actionable rebuild message and bricks the whole extension (issue #117).
+ */
+function getDatabaseCtor(): DatabaseCtor {
+  if (!cachedDatabaseCtor) {
+    const require = createRequire(import.meta.url);
+    cachedDatabaseCtor = isBunRuntime()
+      ? createBunCompatDatabaseCtor(require)
+      : (loadBetterSqlite3({ requireImpl: require }) as DatabaseCtor);
   }
+  return cachedDatabaseCtor;
 }
 
-const Database = loadDatabaseCtor();
-
 export class DatabaseManager {
   private db: DatabaseLike | null = null;
   private readonly displayDbPath: string;
@@ -273,7 +274,7 @@ export class DatabaseManager {
 
   private openUnchecked(): DatabaseLike {
     const existed = this.hasExistingMainDatabaseFile();
-    const db = new Database(this.dbPath);
+    const db = new (getDatabaseCtor())(this.dbPath);
     let ok = false;
 
     try {
@@ -294,6 +295,9 @@ export class DatabaseManager {
   }
 
   private configureConnection(db: DatabaseLike): void {
+    // Wait briefly for concurrent writers across Pi processes instead of failing
+    // immediately with SQLITE_BUSY. Connection-local; applies before WAL/schema.
+    db.exec(`PRAGMA busy_timeout = ${SQLITE_BUSY_TIMEOUT_MS}`);
     // Enable WAL mode + FK enforcement for each connection. Keep SQLite's
     // default WAL autocheckpoint size; a very aggressive checkpoint cadence
     // increases the chance that abrupt VM/host shutdown catches a checkpoint.
@@ -361,7 +365,7 @@ export class DatabaseManager {
   }
 
   private recoverDatabaseFile(cause: unknown, verify: () => void): DatabaseRecoveryResult {
-    const coordinator = new AtomicLockCoordinator(path.join(path.dirname(this.dbPath), '.pi-hermes-locks.sqlite'));
+    const coordinator = AtomicLockCoordinator.shared(path.join(path.dirname(this.dbPath), '.pi-hermes-locks.sqlite'));
     const lockKey = `recovery:${this.dbPath}`;
     const deadline = Date.now() + Math.max(0, this.recoveryOptions.recoveryLockWaitMs);
 
@@ -434,7 +438,7 @@ export class DatabaseManager {
     if (!this.hasExistingMainDatabaseFile()) return false;
     let db: DatabaseLike | null = null;
     try {
-      db = new Database(this.dbPath);
+      db = new (getDatabaseCtor())(this.dbPath);
       this.assertIntegrityOk(db, 'quick_check', 'while joining corruption recovery');
       return true;
     } catch {
@@ -546,6 +550,7 @@ export class DatabaseManager {
     let rebuildOk = false;
 
     try {
+      const Database = getDatabaseCtor();
       source = new Database(this.dbPath);
       target = new Database(tempPath);
       target.exec('PRAGMA journal_mode = DELETE');

package/src/store/fts-query.ts

@@ -63,6 +63,37 @@ export function buildFallbackFts5Query(query: string): string | null {
     .join(' OR ');
 }
 
+function quoteTerms(terms: string[], separator: string): string {
+  return terms.map((term) => `"${term.replace(/"/g, '""')}"`).join(separator);
+}
+
+/**
+ * Normalize a query as natural language even when it contains uppercase
+ * operator words. Queries like "DO NOT USE FIND /" are passed through as raw
+ * FTS5 syntax by normalizeFts5Query; when that raw form fails to parse, this
+ * produces the quoted-term form to retry with.
+ */
+export function normalizeNaturalLanguageFts5Query(query: string): string {
+  const trimmed = query.trim();
+  if (trimmed.length === 0) return '';
+
+  return quoteTerms(collectNaturalLanguageTerms(trimmed), ' ');
+}
+
+/**
+ * Build the broader OR fallback for the same recovery path, ignoring
+ * operator detection.
+ */
+export function buildNaturalLanguageFallbackQuery(query: string): string | null {
+  const trimmed = query.trim();
+  if (trimmed.length === 0) return null;
+
+  const terms = collectNaturalLanguageTerms(trimmed);
+  if (terms.length <= 1) return null;
+
+  return quoteTerms(terms, ' OR ');
+}
+
 export function isFts5QueryError(err: unknown): boolean {
   if (!(err instanceof Error)) return false;
   const msg = err.message.toLowerCase();

package/src/store/markdown-mutation-lock.ts

@@ -12,7 +12,7 @@ export async function canonicalMarkdownIdentity(filePath: string): Promise<strin
 export async function acquireMarkdownMutationLock(filePath: string): Promise<AtomicLockLease> {
   const identity = await canonicalMarkdownIdentity(filePath);
   const coordinatorDir = path.dirname(path.dirname(identity));
-  const coordinator = new AtomicLockCoordinator(path.join(coordinatorDir, ".pi-hermes-locks.sqlite"));
+  const coordinator = AtomicLockCoordinator.shared(path.join(coordinatorDir, ".pi-hermes-locks.sqlite"));
   const lockKey = `mutation:${identity}`;
   const deadline = Date.now() + MUTATION_WAIT_MS;
   let lease = coordinator.tryAcquire(lockKey, { staleMs: MUTATION_STALE_MS });

package/src/store/memory-store.ts

@@ -587,6 +587,46 @@ export class MemoryStore {
     this.fileFingerprints[filePath] = state.fingerprint;
   }
 
+  /**
+   * Reload target state from disk (source of truth), refresh success metadata,
+   * and always notify the mutation observer so SQLite stays aligned even when
+   * the mutation itself failed or an external editor raced the write.
+   */
+  private async finalizeTargetMutation(
+    target: "memory" | "user" | "failure",
+    storagePath: string,
+    result: MemoryResult,
+  ): Promise<MemoryResult> {
+    const state = await this.readFileState(storagePath);
+    this.setEntries(target, [...new Set(state.entries)]);
+    this.fileFingerprints[storagePath] = state.fingerprint;
+
+    let finalized = result;
+    if (result.success) {
+      finalized = {
+        ...result,
+        ...this.successResponse(target, result.message),
+      };
+      if (result.evicted_entries) finalized.evicted_entries = result.evicted_entries;
+      if (result.evicted_count !== undefined) finalized.evicted_count = result.evicted_count;
+      if (result.matches) finalized.matches = result.matches;
+      if (result.entries) finalized.entries = result.entries;
+    }
+
+    if (!this.mutationObserver) return finalized;
+
+    const warning = await this.mutationObserver(target, [...state.entries]);
+    if (!warning || !finalized.success) return finalized;
+
+    const warnings = [...(finalized.warnings ?? []), warning];
+    return {
+      ...finalized,
+      message: finalized.message ? `${finalized.message} Warning: ${warning}` : warning,
+      warning,
+      warnings,
+    };
+  }
+
   private async runTargetMutation(
     target: "memory" | "user" | "failure",
     mutation: () => Promise<MemoryResult>,
@@ -596,35 +636,32 @@ export class MemoryStore {
       for (let attempt = 0; ; attempt++) {
         try {
           const result = await mutation();
-          if (result.success && this.mutationObserver) {
-            const filePath = storagePath;
-            const state = await this.readFileState(filePath);
-            this.setEntries(target, [...new Set(state.entries)]);
-            this.fileFingerprints[filePath] = state.fingerprint;
-            const warning = await this.mutationObserver(target, [...state.entries]);
-            if (warning) {
-              const warnings = [...(result.warnings ?? []), warning];
-              return {
-                ...result,
-                message: result.message ? `${result.message} Warning: ${warning}` : warning,
-                warning,
-                warnings,
-              };
+          if (result.success) {
+            // saveToDisk stamps fileFingerprints on success. If an editor
+            // truncates/replaces the file after publish returns, refuse the
+            // phantom success and retry against disk truth.
+            const expectedFingerprint = this.fileFingerprints[storagePath];
+            if (expectedFingerprint !== undefined) {
+              const state = await this.readFileState(storagePath);
+              if (state.fingerprint !== expectedFingerprint) {
+                this.setEntries(target, [...new Set(state.entries)]);
+                this.fileFingerprints[storagePath] = state.fingerprint;
+                throw new ExternalMemoryWriteConflict();
+              }
             }
           }
-          return result;
+          return await this.finalizeTargetMutation(target, storagePath, result);
         } catch (error) {
-          const filePath = storagePath;
-          delete this.fileFingerprints[filePath];
-          const state = await this.readFileState(filePath);
+          delete this.fileFingerprints[storagePath];
+          const state = await this.readFileState(storagePath);
           this.setEntries(target, [...new Set(state.entries)]);
-          this.fileFingerprints[filePath] = state.fingerprint;
+          this.fileFingerprints[storagePath] = state.fingerprint;
           if (!(error instanceof ExternalMemoryWriteConflict)) throw error;
           if (attempt >= MAX_EXTERNAL_WRITE_RETRIES) {
-            return {
+            return await this.finalizeTargetMutation(target, storagePath, {
               success: false,
-              error: "Memory file changed repeatedly during this update. No external changes were overwritten.",
-            };
+              error: "Memory file changed repeatedly during this update. No external changes were overwritten. If you edited the file manually, re-run the memory tool or /memory-sync-markdown after the file is stable.",
+            });
           }
         }
       }
@@ -718,7 +755,18 @@ export class MemoryStore {
       }
 
       try { await this.unlinkPublishedTempLink(tmpPath); } catch { /* ignore */ }
-      this.fileFingerprints[filePath] = this.fingerprint(content);
+
+      // Re-read after publish. An external truncate/cp can land between the
+      // link/rename and returning success; treat that as a write conflict so
+      // the caller retries against disk truth instead of reporting phantom state.
+      const publishedFingerprint = this.fingerprint(content);
+      this.fileFingerprints[filePath] = publishedFingerprint;
+      const publishedState = await this.readFileState(filePath);
+      if (publishedState.fingerprint !== publishedFingerprint) {
+        this.setEntries(target, [...new Set(publishedState.entries)]);
+        this.fileFingerprints[filePath] = publishedState.fingerprint;
+        throw new ExternalMemoryWriteConflict();
+      }
     } catch (err) {
       try { await fs.unlink(tmpPath); } catch { /* ignore */ }
       throw err;

package/src/store/session-search.ts

@@ -1,5 +1,12 @@
 import { DatabaseManager } from './db.js';
-import { buildFallbackFts5Query, hasExplicitFts5Operator, isFts5QueryError, normalizeFts5Query } from './fts-query.js';
+import {
+  buildFallbackFts5Query,
+  buildNaturalLanguageFallbackQuery,
+  hasExplicitFts5Operator,
+  isFts5QueryError,
+  normalizeFts5Query,
+  normalizeNaturalLanguageFts5Query,
+} from './fts-query.js';
 
 /**
  * Search result from session history.
@@ -93,6 +100,8 @@ export function searchSessions(
   const db = dbManager.getDb();
   const { limit = 10, project, role, since } = options;
 
+  let ftsParseError = false;
+
   const executeSearch = (match: SearchMatch): SessionSearchResult[] => {
     const conditions: string[] = [];
     const params: unknown[] = [];
@@ -160,6 +169,7 @@ export function searchSessions(
       return mapRows(rows);
     } catch (err) {
       if (match.type === 'fts' && isFts5QueryError(err)) {
+        ftsParseError = true;
         return [];
       }
       throw err;
@@ -178,7 +188,28 @@ export function searchSessions(
 
   const explicitOperatorQuery = hasExplicitFts5Operator(query);
   if (explicitOperatorQuery) {
-    return exactResults;
+    // Same recovery as searchMemories: only when the raw operator query fails
+    // to parse do we retry it as natural language; valid operator queries that
+    // match nothing keep their exact semantics.
+    if (!ftsParseError) {
+      return exactResults;
+    }
+    const nlQuery = normalizeNaturalLanguageFts5Query(query);
+    if (nlQuery.length > 0 && nlQuery !== normalizedQuery) {
+      const nlResults = executeSearch({ type: 'fts', query: nlQuery });
+      if (nlResults.length > 0) {
+        return nlResults;
+      }
+      const nlFallback = buildNaturalLanguageFallbackQuery(query);
+      if (nlFallback && nlFallback !== nlQuery) {
+        const nlFallbackResults = executeSearch({ type: 'fts', query: nlFallback });
+        if (nlFallbackResults.length > 0) {
+          return nlFallbackResults;
+        }
+      }
+    }
+    const likeTerms = collectLikeTerms(query);
+    return executeSearch({ type: 'like', terms: likeTerms });
   }
 
   const fallbackQuery = buildFallbackFts5Query(query);

package/src/store/skill-store.ts

@@ -27,8 +27,9 @@ interface SkillStoreOptions {
   projectSkillsDir?: string | null;
   projectName?: string | null;
   legacySkillsDir?: string;
-  legacyPiGlobalSkillsDir?: string;
+  legacyExtensionSkillsDir?: string;
   migrationSentinelPath?: string;
+  extensionSkillsMigrationSentinelPath?: string;
 }
 
 interface SkillLocation {
@@ -46,13 +47,119 @@ export interface LegacySkillMigrationResult {
   warnings: string[];
 }
 
+const LIST_SECTIONS = new Set(["procedure", "pitfalls", "verification"]);
+
+function normalizeSectionName(section: string): string {
+  return section.replace(/^#+\s*/, "").trim();
+}
+
+function isExactSectionHeader(line: string, section: string): boolean {
+  const heading = line.trim().match(/^##\s+(.+?)\s*$/);
+  if (!heading) return false;
+  return heading[1].trim().toLowerCase() === section.trim().toLowerCase();
+}
+
+function looksLikeJsonArray(content: string): boolean {
+  const trimmed = content.trim();
+  return trimmed.startsWith("[") && trimmed.endsWith("]");
+}
+
+function looksLikeJsonObject(content: string): boolean {
+  const trimmed = content.trim();
+  return trimmed.startsWith("{") && trimmed.endsWith("}");
+}
+
+function formatPatchList(section: string, items: string[]): string {
+  const cleaned = items.map((item) => item.trim()).filter(Boolean);
+  if (cleaned.length === 0) return "";
+  const key = section.trim().toLowerCase();
+  if (key === "pitfalls") {
+    return cleaned.map((item) => `- ${item.replace(/^[-*]\s+/, "")}`).join("\n");
+  }
+  // Procedure / Verification default to ordered steps.
+  return cleaned
+    .map((item, index) => `${index + 1}. ${item.replace(/^\d+\.\s+/, "").replace(/^[-*]\s+/, "")}`)
+    .join("\n");
+}
+
+/**
+ * Normalize/validate free-form patch content so LLM format drift cannot wipe
+ * or splice skill sections. Coerces JSON string arrays into Markdown lists for
+ * list-shaped sections and rejects empty / object / header-injecting payloads.
+ */
+export function normalizeSkillPatchContent(
+  section: string,
+  rawContent: string,
+): { content: string } | { error: string } {
+  const sectionName = normalizeSectionName(section);
+  if (!sectionName) {
+    return { error: "section is required for patch." };
+  }
+
+  let content = typeof rawContent === "string" ? rawContent.trim() : "";
+  if (!content) {
+    return {
+      error: "New content is required for patch. Prefer structured fields (procedure_steps, pitfalls, verification_steps, when_to_use) over free-form content.",
+    };
+  }
+
+  if (looksLikeJsonObject(content)) {
+    return {
+      error: "Patch content looks like a JSON object. Provide Markdown section body or a string array via structured fields.",
+    };
+  }
+
+  if (looksLikeJsonArray(content)) {
+    try {
+      const parsed: unknown = JSON.parse(content);
+      if (!Array.isArray(parsed)) {
+        return { error: "Patch content looks like JSON but is not a string array." };
+      }
+      const items = parsed
+        .filter((item): item is string => typeof item === "string")
+        .map((item) => item.trim())
+        .filter(Boolean);
+      if (items.length === 0) {
+        return { error: "Patch content JSON array must contain non-empty strings." };
+      }
+      const key = sectionName.toLowerCase();
+      if (key === "when to use") {
+        content = items.join("\n\n");
+      } else if (LIST_SECTIONS.has(key)) {
+        content = formatPatchList(sectionName, items);
+      } else {
+        content = items.map((item) => `- ${item}`).join("\n");
+      }
+    } catch {
+      return {
+        error: "Patch content looks like a JSON array but could not be parsed. Use Markdown or structured string[] fields.",
+      };
+    }
+  }
+
+  // Reject payloads that would inject extra ## sections mid-body.
+  if (/^#{1,6}\s+\S/m.test(content)) {
+    return {
+      error: "Patch content must not include Markdown section headers (## ...). Patch only the body of the target section.",
+    };
+  }
+
+  if (!content.trim()) {
+    return { error: "New content is required for patch." };
+  }
+
+  return { content: content.trim() };
+}
+
+
 export class SkillStore {
   private globalSkillsDir: string;
   private projectSkillsDir: string | null;
   private projectName: string | null;
   private legacySkillsDir: string;
-  private legacyPiGlobalSkillsDir: string;
+  private legacyExtensionSkillsDir: string;
   private migrationSentinelPath: string;
+  private extensionSkillsMigrationSentinelPath: string;
 
   constructor(options: SkillStoreOptions = {}) {
     const agentRoot = AGENT_ROOT;
@@ -60,9 +167,12 @@ export class SkillStore {
     this.projectSkillsDir = options.projectSkillsDir ?? null;
     this.projectName = options.projectName ?? null;
     this.legacySkillsDir = options.legacySkillsDir ?? path.join(agentRoot, "memory", "skills");
-    this.legacyPiGlobalSkillsDir = options.legacyPiGlobalSkillsDir ?? path.join(agentRoot, "skills");
+    this.legacyExtensionSkillsDir = options.legacyExtensionSkillsDir
+      ?? path.join(agentRoot, "pi-hermes-memory", "skills");
     this.migrationSentinelPath = options.migrationSentinelPath
       ?? path.join(agentRoot, "pi-hermes-memory", ".skills-migrated-to-extension-storage");
+    this.extensionSkillsMigrationSentinelPath = options.extensionSkillsMigrationSentinelPath
+      ?? path.join(agentRoot, "pi-hermes-memory", ".skills-migrated-to-pi-global");
   }
 
   getGlobalSkillsDir(): string {
@@ -95,16 +205,19 @@ export class SkillStore {
     // Always normalize flat markdown files under the global skills root,
     // even when a previous migration sentinel already exists.
     await this.migrateFlatMarkdownInGlobalSkillsDir(result);
+    await this.migrateExtensionSkillsToGlobalRoot(result);
 
     if (await exists(this.migrationSentinelPath)) return result;
 
     await fs.mkdir(path.dirname(this.migrationSentinelPath), { recursive: true });
 
+    // Only this migration's own warnings may hold back its sentinel — a
+    // permanently shadowed skill reported above must not make it retry forever.
+    const warningsBefore = result.warnings.length;
     try {
       await this.migrateLegacyMarkdownSkills(result);
-      await this.migrateLegacyPiGlobalSkillDirs(result);
     } finally {
-      if (result.warnings.length === 0) {
+      if (result.warnings.length === warningsBefore) {
         await fs.writeFile(this.migrationSentinelPath, `${new Date().toISOString()}\n`, "utf-8");
       }
     }
@@ -202,45 +315,61 @@ export class SkillStore {
     }
   }
 
-  private async migrateLegacyPiGlobalSkillDirs(result: LegacySkillMigrationResult): Promise<void> {
-    if (path.resolve(this.legacyPiGlobalSkillsDir) === path.resolve(this.globalSkillsDir)) return;
-    if (!await exists(this.legacyPiGlobalSkillsDir)) return;
+  /**
+   * Move extension-managed global skills back into Pi's own global skills root.
+   *
+   * Pi keys skills by name, first-loaded wins, and `~/.pi/agent/skills/` is
+   * auto-discovered at higher precedence than anything an extension contributes
+   * via `resources_discover`. While global skills lived in a private directory,
+   * any name that also existed in Pi's root was permanently shadowed: the
+   * collision warning fired every session and `skill_manage` edits silently had
+   * no effect on the skill the agent actually loaded (#125, #126).
+   *
+   * Runs on every startup until it completes with no shadowed names, since a
+   * shadowed skill can only be resolved by the user renaming one of the two.
+   */
+  private async migrateExtensionSkillsToGlobalRoot(result: LegacySkillMigrationResult): Promise<void> {
+    if (path.resolve(this.legacyExtensionSkillsDir) === path.resolve(this.globalSkillsDir)) return;
+    if (await exists(this.extensionSkillsMigrationSentinelPath)) return;
+    if (!await exists(this.legacyExtensionSkillsDir)) return;
+
+    const entries = await fs.readdir(this.legacyExtensionSkillsDir, { withFileTypes: true });
+    let shadowed = 0;
 
-    const entries = await fs.readdir(this.legacyPiGlobalSkillsDir, { withFileTypes: true });
     for (const entry of entries) {
       if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
 
-      const sourceDir = path.join(this.legacyPiGlobalSkillsDir, entry.name);
-      const sourceSkill = path.join(sourceDir, "SKILL.md");
-      if (!await exists(sourceSkill)) continue;
+      const sourceDir = path.join(this.legacyExtensionSkillsDir, entry.name);
+      if (!await exists(path.join(sourceDir, "SKILL.md"))) continue;
 
       const targetDir = path.join(this.globalSkillsDir, entry.name);
-      const targetSkill = path.join(targetDir, "SKILL.md");
-      if (await exists(targetSkill)) {
+      if (await exists(path.join(targetDir, "SKILL.md"))) {
+        // Pi already loads the copy in its own root; ours was never reachable.
+        // Leave both in place rather than clobbering a skill we did not write.
+        shadowed++;
         result.skipped++;
+        result.warnings.push(
+          `${entry.name}: already exists at ${targetDir}; the copy at ${sourceDir} was never loaded by Pi. `
+          + `Rename or delete one of them, then restart Pi.`,
+        );
         continue;
       }
 
       try {
-        const raw = await fs.readFile(sourceSkill, "utf-8");
-        const parsed = parseFrontmatter(raw);
-        const hasExtensionManagedMeta = Boolean(parsed.meta.display_name)
-          && Boolean(parsed.meta.created)
-          && Boolean(parsed.meta.updated)
-          && /^\d+$/.test(parsed.meta.version ?? "");
-
-        if (!hasExtensionManagedMeta) {
-          result.skipped++;
-          continue;
-        }
-
         await fs.mkdir(path.dirname(targetDir), { recursive: true });
         await fs.rename(sourceDir, targetDir);
         result.migrated++;
       } catch (error) {
+        shadowed++;
         result.warnings.push(`${entry.name}: ${error instanceof Error ? error.message : String(error)}`);
       }
     }
+
+    if (shadowed === 0) {
+      await fs.mkdir(path.dirname(this.extensionSkillsMigrationSentinelPath), { recursive: true });
+      await fs.writeFile(this.extensionSkillsMigrationSentinelPath, `${new Date().toISOString()}\n`, "utf-8");
+      await fs.rm(this.legacyExtensionSkillsDir, { recursive: true, force: true });
+    }
   }
 
   async loadIndex(scope?: SkillScope): Promise<SkillIndex[]> {
@@ -352,34 +481,47 @@ export class SkillStore {
   }
 
   async patch(skillId: string, section: string, newContent: string): Promise<SkillResult> {
-    newContent = newContent.trim();
-    if (!newContent) return { success: false, error: "New content is required for patch." };
+    const sectionName = normalizeSectionName(section);
+    if (!sectionName) return { success: false, error: "section is required for patch." };
+
+    const normalized = normalizeSkillPatchContent(sectionName, newContent);
+    if ("error" in normalized) return { success: false, error: normalized.error };
+    const content = normalized.content;
 
-    const scanError = scanContent(newContent);
+    const scanError = scanContent(content);
     if (scanError) return { success: false, error: scanError };
 
     const doc = await this.loadSkill(skillId);
     if (!doc) return { success: false, error: `Skill '${skillId}' not found.` };
 
-    const sectionHeader = `## ${section}`;
+    const sectionHeader = `## ${sectionName}`;
     const lines = doc.body.split("\n");
     let found = false;
     const result: string[] = [];
 
     for (let i = 0; i < lines.length; i++) {
-      if (lines[i].startsWith(sectionHeader)) {
+      if (isExactSectionHeader(lines[i], sectionName)) {
         result.push(sectionHeader);
-        result.push(newContent);
+        // Preserve multi-line body as discrete lines so later headers stay exact.
+        for (const bodyLine of content.split("\n")) {
+          result.push(bodyLine);
+        }
         found = true;
         i++;
-        while (i < lines.length && !lines[i].startsWith("## ")) i++;
+        while (i < lines.length && !lines[i].trim().startsWith("## ")) i++;
         if (i < lines.length) result.push(lines[i]);
       } else {
         result.push(lines[i]);
       }
     }
 
-    if (!found) result.push("", sectionHeader, newContent);
+    if (!found) {
+      if (result.length > 0 && result[result.length - 1] !== "") result.push("");
+      result.push(sectionHeader);
+      for (const bodyLine of content.split("\n")) {
+        result.push(bodyLine);
+      }
+    }
 
     await this.atomicWrite(doc.path, formatFrontmatter({
       name: doc.name,
@@ -393,7 +535,7 @@ export class SkillStore {
 
     return {
       success: true,
-      message: `Skill '${doc.displayName || doc.name}' section '${section}' updated.`,
+      message: `Skill '${doc.displayName || doc.name}' section '${sectionName}' updated.`,
       fileName: doc.fileName,
       skillId: doc.skillId,
       scope: doc.scope,