apple-notes-mcp 2.0.0 → 2.1.0

package/README.md

@@ -41,6 +41,17 @@ Install as a Claude Code plugin for automatic configuration and enhanced AI beha
 
 This method also installs a **skill** that teaches Claude when and how to use Apple Notes effectively.
 
+### Using the Codex Marketplace
+
+The same plugin is available for Codex. Add the marketplace and install the plugin:
+
+```bash
+codex plugin marketplace add sweetrb/apple-notes-mcp
+codex plugin add apple-notes@apple-notes-mcp
+```
+
+The Codex plugin runs the published `apple-notes-mcp` server through `npx` and ships the same Apple Notes skill, so behavior matches the Claude Code plugin.
+
 ### Manual Installation
 
 **1. Install the server:**
@@ -102,6 +113,15 @@ Resources expose read-only context the client can attach without a tool call:
 `notes://note/{id}` template (returns the note as Markdown). Prompts package
 common workflows: `find-note`, `weekly-review`, `new-meeting-note`.
 
+### Known limitations
+
+A few Notes UI features are not exposed to AppleScript and therefore cannot be
+supported. See **[docs/APPLESCRIPT-LIMITATIONS.md](docs/APPLESCRIPT-LIMITATIONS.md)**
+for the investigation and verification behind each:
+
+- **Pinned notes** — Notes has no scriptable `pinned` property, so pin state can be neither read nor set.
+- **Note-to-note links** — there is no `applenotes://` deep link or link property; the only stable handle is the `x-coredata://` note id.
+
 ---
 
 ## Tool Reference
@@ -224,7 +244,10 @@ Retrieves the full content of a specific note.
 }
 ```
 
-**Returns:** The HTML content of the note, or error if not found.
+**Returns:** The HTML content of the note, or error if not found. The
+`structuredContent` also includes `hashtags` — any inline `#hashtag` tags parsed
+from the body. Apple Notes tags are inline hashtags, not a scriptable property;
+see [docs/APPLESCRIPT-LIMITATIONS.md](../docs/APPLESCRIPT-LIMITATIONS.md#tags--hashtags-29). Smart Folders are not scriptable.
 
 ---
 
@@ -946,12 +969,20 @@ The `\\\\` in JSON becomes `\\` in the actual string, which represents a single
 ## Development
 
 ```bash
-npm install      # Install dependencies
-npm run build    # Compile TypeScript
-npm test         # Run test suite (313 tests)
-npm run lint     # Check code style
-npm run format   # Format code
-```
+npm install            # Install dependencies
+npm run build          # Compile TypeScript
+npm test               # Run unit test suite (mocked AppleScript)
+npm run test:integration  # Run integration tests against real Notes.app
+npm run test:all       # Unit + integration
+npm run lint           # Check code style
+npm run format         # Format code
+```
+
+The integration suite (`test/integration.test.ts`) drives the real
+`AppleNotesManager → AppleScript → Notes.app` stack — creating, reading,
+searching, and deleting throwaway notes. Its live tests self-skip when no
+writable Notes account is available (e.g. CI), so it is safe to run anywhere;
+the pure path-safety and hashtag tests always run.
 
 ---
 

package/build/index.js

@@ -27,6 +27,7 @@ import { AppleNotesManager } from "./services/appleNotesManager.js";
 import { getSyncStatus, withSyncAwarenessSync } from "./utils/syncDetection.js";
 import { getChecklistItems, hasFullDiskAccess } from "./utils/checklistParser.js";
 import { detectChecklistAttempt } from "./utils/contentWarnings.js";
+import { parseHashtags } from "./utils/hashtags.js";
 import { runDoctor, formatDoctorReport } from "./tools/doctor.js";
 import { loadFileConfig } from "./services/fileConfig.js";
 import { registerResourcesAndPrompts } from "./tools/resourcesAndPrompts.js";
@@ -200,7 +201,8 @@ server.tool("get-note-content", {
         if (!content) {
             return errorResponse(`Failed to read content of note "${note.title}"`);
         }
-        return successResponse(content, { title: note.title, content });
+        const hashtags = parseHashtags(content);
+        return successResponse(content, { title: note.title, content, hashtags });
     }
     // Fall back to title-based lookup
     if (!title) {
@@ -218,7 +220,8 @@ server.tool("get-note-content", {
     if (!content) {
         return errorResponse(`Failed to read content of note "${title}"`);
     }
-    return successResponse(content, { title, content });
+    const hashtags = parseHashtags(content);
+    return successResponse(content, { title, content, hashtags });
 }, "Error retrieving note content"));
 // --- get-note-by-id ---
 server.tool("get-note-by-id", {
@@ -599,6 +602,15 @@ server.tool("get-notes-stats", {}, withErrorHandling(() => {
     lines.push(`  Last 24 hours: ${stats.recentlyModified.last24h}`);
     lines.push(`  Last 7 days: ${stats.recentlyModified.last7d}`);
     lines.push(`  Last 30 days: ${stats.recentlyModified.last30d}`);
+    // Partial-coverage diagnostics (#19): if some scopes couldn't be read, say so
+    // explicitly so the numbers above aren't mistaken for a complete picture.
+    if (!stats.coverage.complete) {
+        lines.push(``);
+        lines.push(`⚠️  Partial results: read ${stats.coverage.covered}/${stats.coverage.scanned} scopes. Counts above exclude:`);
+        for (const w of stats.coverage.warnings) {
+            lines.push(`  - ${w.scope}: ${w.reason}`);
+        }
+    }
     return successResponse(lines.join("\n"), { ...stats });
 }, "Error getting notes statistics"));
 // --- list-attachments ---

package/build/services/appleNotesManager.js

@@ -634,7 +634,7 @@ export class AppleNotesManager {
      */
     searchNotes(query, searchContent = false, account, folder, modifiedSince, limit) {
         const targetAccount = this.resolveAccount(account);
-        const safeQuery = escapeForAppleScript(query);
+        const safeQuery = escapePlainStringForAppleScript(query);
         const safeLimit = limit !== undefined && limit > 0 ? Math.floor(limit) : undefined;
         // Build the where clause based on search type
         // AppleScript uses 'name' for title and 'body' for content
@@ -664,24 +664,26 @@ export class AppleNotesManager {
             ? `
           if (count of resultList) >= ${safeLimit} then exit repeat`
             : "";
-        // Get names, IDs, and folder for each matching note
-        // We use a repeat loop to get all properties, separated by a delimiter
-        // Note: Some notes may have inaccessible containers, so we wrap in try/on error
+        // Get names, IDs, and folder for each matching note.
+        // Notes.app can return the same CoreData note more than once when asking
+        // an account for all notes, so dedupe on note ID before adding results.
         const searchCommand = `
       ${dateSetup}set matchingNotes to ${notesSource} where ${whereClause}
       set resultList to {}
-      repeat with n in matchingNotes${limitCheck}
+      set seenIds to {}
+      repeat with n in matchingNotes
         try
           set noteName to name of n
           set noteId to id of n
-          set noteFolder to name of container of n
-          set end of resultList to noteName & ${AS_FIELD_SEP} & noteId & ${AS_FIELD_SEP} & noteFolder
-        on error
-          try
-            set noteName to name of n
-            set noteId to id of n
-            set end of resultList to noteName & ${AS_FIELD_SEP} & noteId & ${AS_FIELD_SEP} & "Notes"
-          end try
+          if seenIds does not contain noteId then
+            set end of seenIds to noteId
+            try
+              set noteFolder to name of container of n
+            on error
+              set noteFolder to "Notes"
+            end try
+            set end of resultList to noteName & ${AS_FIELD_SEP} & noteId & ${AS_FIELD_SEP} & noteFolder${limitCheck}
+          end if
         end try
       end repeat
       set AppleScript's text item delimiters to ${AS_RECORD_SEP}
@@ -700,12 +702,17 @@ export class AppleNotesManager {
         // Parse the control-char-delimited output (#18): fields by FIELD_SEP, records by RECORD_SEP.
         const items = result.output.split(RECORD_SEP);
         const notes = [];
+        const seenIds = new Set();
         for (const item of items) {
             const [title, id, folder] = item.split(FIELD_SEP);
             if (!title?.trim())
                 continue;
+            const noteId = id?.trim() || generateFallbackId();
+            if (seenIds.has(noteId))
+                continue;
+            seenIds.add(noteId);
             notes.push({
-                id: id?.trim() || generateFallbackId(), // Use real ID, fallback to unique temp ID
+                id: noteId,
                 title: title.trim(),
                 content: "", // Not fetched in search
                 tags: [],
@@ -738,7 +745,7 @@ export class AppleNotesManager {
      */
     getNoteContent(title, account) {
         const targetAccount = this.resolveAccount(account);
-        const safeTitle = escapeForAppleScript(title);
+        const safeTitle = escapePlainStringForAppleScript(title);
         // Retrieve the body property of the note
         const getCommand = `get body of note "${safeTitle}"`;
         const script = buildAccountScopedScript({ account: targetAccount }, getCommand);
@@ -830,7 +837,7 @@ export class AppleNotesManager {
      */
     getNoteDetails(title, account) {
         const targetAccount = this.resolveAccount(account);
-        const safeTitle = escapeForAppleScript(title);
+        const safeTitle = escapePlainStringForAppleScript(title);
         // Fetch multiple properties at once
         const getCommand = `
       set n to note "${safeTitle}"
@@ -875,7 +882,7 @@ export class AppleNotesManager {
      */
     deleteNote(title, account) {
         const targetAccount = this.resolveAccount(account);
-        const safeTitle = escapeForAppleScript(title);
+        const safeTitle = escapePlainStringForAppleScript(title);
         const deleteCommand = `delete note "${safeTitle}"`;
         const script = buildAccountScopedScript({ account: targetAccount }, deleteCommand);
         const result = executeAppleScript(script);
@@ -931,7 +938,7 @@ export class AppleNotesManager {
             validateLength(newTitle, MAX_TITLE_LENGTH, "Note title");
         validateLength(newContent, MAX_CONTENT_LENGTH, "Note content");
         const targetAccount = this.resolveAccount(account);
-        const safeCurrentTitle = escapeForAppleScript(title);
+        const safeCurrentTitle = escapePlainStringForAppleScript(title);
         let fullBody;
         if (format === "html") {
             // HTML mode: content is the complete body, escaped only for AppleScript string
@@ -1032,15 +1039,24 @@ export class AppleNotesManager {
                     notesSource = `(${baseNotesSource} whose modification date >= thresholdDate)`;
                 }
             }
-            // Build the limit check
+            // Build the limit check. Check after appending so deduped results,
+            // rather than duplicate AppleScript references, determine the limit.
             const limitCheck = safeLimit !== undefined
                 ? `
             if (count of resultList) >= ${safeLimit} then exit repeat`
                 : "";
             const listCommand = `
         ${dateSetup}set resultList to {}
-        repeat with n in ${notesSource}${limitCheck}
-          set end of resultList to name of n
+        set seenIds to {}
+        repeat with n in ${notesSource}
+          try
+            set noteName to name of n
+            set noteId to id of n
+            if seenIds does not contain noteId then
+              set end of seenIds to noteId
+              set end of resultList to noteName & ${AS_FIELD_SEP} & noteId${limitCheck}
+            end if
+          end try
         end repeat
         set AppleScript's text item delimiters to ${AS_RECORD_SEP}
         return resultList as text
@@ -1053,16 +1069,36 @@ export class AppleNotesManager {
             if (!result.output.trim()) {
                 return [];
             }
-            return result.output
-                .split(RECORD_SEP)
-                .map((item) => item.trim())
-                .filter((item) => item.length > 0);
+            const seenIds = new Set();
+            const titles = [];
+            for (const item of result.output.split(RECORD_SEP)) {
+                const [title, id] = item.split(FIELD_SEP);
+                if (!title?.trim())
+                    continue;
+                const noteId = id?.trim() || generateFallbackId();
+                if (seenIds.has(noteId))
+                    continue;
+                seenIds.add(noteId);
+                titles.push(title.trim());
+            }
+            return titles;
         }
-        // Simple path: no date or limit filters. Coerce the name list to text with a
-        // control-char record separator so titles containing commas don't split (#18).
+        // Simple path: no date or limit filters. Use a repeat loop so duplicate
+        // CoreData note references can be deduped by ID before returning titles.
         const notesRef = folder ? `notes of ${buildFolderReference(folder)}` : `notes`;
         const listCommand = `
-      set resultList to name of ${notesRef}
+      set resultList to {}
+      set seenIds to {}
+      repeat with n in ${notesRef}
+        try
+          set noteName to name of n
+          set noteId to id of n
+          if seenIds does not contain noteId then
+            set end of seenIds to noteId
+            set end of resultList to noteName & ${AS_FIELD_SEP} & noteId
+          end if
+        end try
+      end repeat
       set AppleScript's text item delimiters to ${AS_RECORD_SEP}
       return resultList as text
     `;
@@ -1073,10 +1109,19 @@ export class AppleNotesManager {
         }
         if (!result.output.trim())
             return [];
-        return result.output
-            .split(RECORD_SEP)
-            .map((item) => item.trim())
-            .filter((item) => item.length > 0);
+        const seenIds = new Set();
+        const titles = [];
+        for (const item of result.output.split(RECORD_SEP)) {
+            const [title, id] = item.split(FIELD_SEP);
+            if (!title?.trim())
+                continue;
+            const noteId = id?.trim() || generateFallbackId();
+            if (seenIds.has(noteId))
+                continue;
+            seenIds.add(noteId);
+            titles.push(title.trim());
+        }
+        return titles;
     }
     /**
      * Lists all shared (collaborative) notes across all accounts.
@@ -1251,7 +1296,7 @@ export class AppleNotesManager {
                 continue;
             }
             // Folder doesn't exist — create it
-            const segmentName = escapeForAppleScript(parts[i]);
+            const segmentName = escapePlainStringForAppleScript(parts[i]);
             let createCommand;
             if (i === 0) {
                 createCommand = `make new folder with properties {name:"${segmentName}"}`;
@@ -1549,10 +1594,16 @@ export class AppleNotesManager {
     getNotesStats() {
         const accounts = this.listAccounts();
         const accountStats = [];
+        const warnings = [];
         let totalNotes = 0;
         // Collect stats per account with ONE bounded script per account (#20/#26):
         // count notes server-side per folder instead of fetching every note's name
         // (unbounded) via a listNotes call per folder (N+1 osascript spawns).
+        //
+        // Per-account failures degrade gracefully (#19): a single unreachable or
+        // locked account is recorded as a coverage warning and skipped, rather than
+        // discarding the stats for every healthy account. Only a total wipeout
+        // (no account readable) is escalated to a thrown error below.
         for (const account of accounts) {
             const countScript = buildAccountScopedScript({ account: account.name }, `
         set out to ""
@@ -1563,7 +1614,8 @@ export class AppleNotesManager {
         `);
             const res = executeAppleScript(countScript);
             if (!res.success) {
-                throw new Error(`Failed to read folder stats for "${account.name}": ${res.error ?? "unknown error"}`);
+                warnings.push({ scope: account.name, reason: res.error ?? "unknown error" });
+                continue;
             }
             const folderStats = [];
             let accountTotal = 0;
@@ -1583,12 +1635,33 @@ export class AppleNotesManager {
                 folders: folderStats,
             });
         }
-        // Get recently modified notes counts
-        const recentlyModified = this.getRecentlyModifiedCounts();
+        // If every account failed, there is no data to report — surface the error
+        // (#19) rather than returning a deceptively empty stats object.
+        if (accounts.length > 0 && accountStats.length === 0) {
+            throw new Error(`Failed to read folder stats for any of ${accounts.length} account(s): ${warnings
+                .map((w) => `${w.scope} (${w.reason})`)
+                .join("; ")}`);
+        }
+        // Get recently modified notes counts. A failure here is non-fatal — record a
+        // coverage warning and report zeros, flagged as not-covered (#19), instead of
+        // passing off fake zero activity as real.
+        const recent = this.getRecentlyModifiedCounts();
+        if (recent.error) {
+            warnings.push({ scope: "recent-activity", reason: recent.error });
+        }
+        // scopes = each account + the recent-activity scan
+        const scanned = accounts.length + 1;
+        const covered = scanned - warnings.length;
         return {
             totalNotes,
             accounts: accountStats,
-            recentlyModified,
+            recentlyModified: recent.counts,
+            coverage: {
+                complete: warnings.length === 0,
+                scanned,
+                covered,
+                warnings,
+            },
         };
     }
     /**
@@ -1621,15 +1694,22 @@ export class AppleNotesManager {
     `;
         const result = executeAppleScript(script);
         if (!result.success) {
-            // Surface the failure (#19) rather than reporting fake zero recent activity.
-            throw new Error(`Failed to read recent activity: ${result.error ?? "unknown error"}`);
+            // Non-fatal (#19): report the error to the caller so it becomes a coverage
+            // warning, with zeroed counts, instead of throwing away the whole stats
+            // result or passing off fake zero activity as real.
+            return {
+                counts: { last24h: 0, last7d: 0, last30d: 0 },
+                error: result.error ?? "unknown error",
+            };
         }
         const parts = result.output.trim().split(FIELD_SEP);
         const toInt = (s) => {
             const n = parseInt((s ?? "").trim(), 10);
             return Number.isFinite(n) ? n : 0;
         };
-        return { last24h: toInt(parts[0]), last7d: toInt(parts[1]), last30d: toInt(parts[2]) };
+        return {
+            counts: { last24h: toInt(parts[0]), last7d: toInt(parts[1]), last30d: toInt(parts[2]) },
+        };
     }
     // ===========================================================================
     // Attachments
@@ -1699,7 +1779,7 @@ export class AppleNotesManager {
      */
     listAttachments(title, account) {
         const targetAccount = this.resolveAccount(account);
-        const safeTitle = escapeForAppleScript(title);
+        const safeTitle = escapePlainStringForAppleScript(title);
         const script = `
       tell application "Notes"
         tell account "${targetAccount}"
@@ -1759,8 +1839,8 @@ export class AppleNotesManager {
             return { success: false, error: e instanceof Error ? e.message : String(e) };
         }
         const safeNoteId = sanitizeId(noteId);
-        const safeAttId = escapeForAppleScript(attachmentId);
-        const safePath = escapeForAppleScript(abs);
+        const safeAttId = escapePlainStringForAppleScript(attachmentId);
+        const safePath = escapePlainStringForAppleScript(abs);
         const script = `
       tell application "Notes"
         set theNote to note id "${safeNoteId}"
@@ -1858,29 +1938,94 @@ export class AppleNotesManager {
      * ```
      */
     batchDeleteNotes(ids) {
-        const results = [];
-        for (const id of ids) {
-            // First verify the note exists and isn't password protected
-            const note = this.getNoteById(id);
-            if (!note) {
-                results.push(this.createBatchResult(id, false, "Note not found"));
-                continue;
+        if (ids.length === 0)
+            return [];
+        // Collapse the whole batch into ONE osascript spawn (#26): a single
+        // app-level script loops over every id, with a per-id `try` so one bad note
+        // can't abort the rest. The old path spawned 3 processes per note
+        // (getNoteById + isNotePasswordProtectedById + deleteNoteById) — i.e. 3N
+        // spawns for N notes. This is one spawn total, with the same per-item
+        // isolation and result semantics.
+        const results = new Array(ids.length);
+        const runnable = [];
+        ids.forEach((id, i) => {
+            try {
+                runnable.push({ index: i, safe: sanitizeId(id) });
             }
-            if (this.isNotePasswordProtectedById(id)) {
-                results.push(this.createBatchResult(id, false, "Note is password-protected"));
-                continue;
+            catch (e) {
+                results[i] = this.createBatchResult(id, false, e instanceof Error ? e.message : "Invalid note ID");
             }
-            // Attempt deletion
-            const success = this.deleteNoteById(id);
-            if (success) {
-                results.push(this.createBatchResult(id, true));
+        });
+        if (runnable.length > 0) {
+            const idList = runnable.map((r) => `"${r.safe}"`).join(", ");
+            const script = buildAppLevelScript(`
+        set out to ""
+        repeat with rawId in {${idList}}
+          set theId to (rawId as text)
+          set noteRef to missing value
+          try
+            set noteRef to note id theId
+          end try
+          if noteRef is missing value then
+            set out to out & "missing" & ${AS_RECORD_SEP}
+          else
+            set isPw to false
+            try
+              set isPw to (password protected of noteRef)
+            end try
+            if isPw then
+              set out to out & "pw" & ${AS_RECORD_SEP}
+            else
+              try
+                delete noteRef
+                set out to out & "ok" & ${AS_RECORD_SEP}
+              on error
+                set out to out & "fail" & ${AS_RECORD_SEP}
+              end try
+            end if
+          end if
+        end repeat
+        return out
+      `);
+            const res = executeAppleScript(script);
+            if (!res.success) {
+                // Whole-batch failure (e.g. Notes.app not responding): can't isolate,
+                // so mark every runnable note as failed with the underlying error.
+                for (const r of runnable) {
+                    results[r.index] = this.createBatchResult(ids[r.index], false, res.error ?? "Batch delete failed");
+                }
             }
             else {
-                results.push(this.createBatchResult(id, false, "Deletion failed"));
+                const statuses = res.output
+                    .split(RECORD_SEP)
+                    .map((s) => s.trim())
+                    .filter((s) => s.length > 0);
+                runnable.forEach((r, k) => {
+                    results[r.index] = this.mapBatchStatus(ids[r.index], statuses[k], "delete");
+                });
             }
         }
         return results;
     }
+    /**
+     * Maps a per-item status token emitted by a batch AppleScript loop to a
+     * BatchResult, preserving the human-readable error messages of the original
+     * per-note implementation. See {@link batchDeleteNotes} / {@link batchMoveNotes}.
+     */
+    mapBatchStatus(id, status, op) {
+        switch (status) {
+            case "ok":
+                return this.createBatchResult(id, true);
+            case "pw":
+                return this.createBatchResult(id, false, "Note is password-protected");
+            case "missing":
+                return this.createBatchResult(id, false, "Note not found");
+            case "fail":
+                return this.createBatchResult(id, false, op === "delete" ? "Deletion failed" : "Move failed");
+            default:
+                return this.createBatchResult(id, false, "Unknown error");
+        }
+    }
     /**
      * Moves multiple notes to a folder by their IDs.
      *
@@ -1901,25 +2046,76 @@ export class AppleNotesManager {
      * ```
      */
     batchMoveNotes(ids, folder, account) {
-        const results = [];
-        for (const id of ids) {
-            // First verify the note exists
-            const note = this.getNoteById(id);
-            if (!note) {
-                results.push(this.createBatchResult(id, false, "Note not found"));
-                continue;
+        if (ids.length === 0)
+            return [];
+        // Collapse the whole batch into ONE osascript spawn (#26). The old path
+        // spawned 5+ processes per note (getNoteById + isNotePasswordProtectedById +
+        // moveNoteById's copy-then-delete fan-out). This uses the native `move`
+        // command — which preserves the note's identity and metadata rather than
+        // copy+delete — inside a single app-level loop with per-id `try` isolation.
+        const targetAccount = this.resolveAccount(account);
+        const safeAccount = sanitizeAccountName(targetAccount);
+        // buildFolderReference validates the (single, shared) destination path; a
+        // malformed folder is a precondition error for the whole call, so let it throw.
+        const destFolderRef = `${buildFolderReference(folder)} of account "${safeAccount}"`;
+        const results = new Array(ids.length);
+        const runnable = [];
+        ids.forEach((id, i) => {
+            try {
+                runnable.push({ index: i, safe: sanitizeId(id) });
             }
-            if (this.isNotePasswordProtectedById(id)) {
-                results.push(this.createBatchResult(id, false, "Note is password-protected"));
-                continue;
+            catch (e) {
+                results[i] = this.createBatchResult(id, false, e instanceof Error ? e.message : "Invalid note ID");
             }
-            // Attempt move using the ID-based method
-            const success = this.moveNoteById(id, folder, account);
-            if (success) {
-                results.push(this.createBatchResult(id, true));
+        });
+        if (runnable.length > 0) {
+            const idList = runnable.map((r) => `"${r.safe}"`).join(", ");
+            const script = buildAppLevelScript(`
+        set destFolder to ${destFolderRef}
+        set out to ""
+        repeat with rawId in {${idList}}
+          set theId to (rawId as text)
+          set noteRef to missing value
+          try
+            set noteRef to note id theId
+          end try
+          if noteRef is missing value then
+            set out to out & "missing" & ${AS_RECORD_SEP}
+          else
+            set isPw to false
+            try
+              set isPw to (password protected of noteRef)
+            end try
+            if isPw then
+              set out to out & "pw" & ${AS_RECORD_SEP}
+            else
+              try
+                move noteRef to destFolder
+                set out to out & "ok" & ${AS_RECORD_SEP}
+              on error
+                set out to out & "fail" & ${AS_RECORD_SEP}
+              end try
+            end if
+          end if
+        end repeat
+        return out
+      `);
+            const res = executeAppleScript(script);
+            if (!res.success) {
+                // Whole-batch failure (e.g. destination folder unresolved, Notes not
+                // responding): can't isolate, so fail every runnable note.
+                for (const r of runnable) {
+                    results[r.index] = this.createBatchResult(ids[r.index], false, res.error ?? "Batch move failed");
+                }
             }
             else {
-                results.push(this.createBatchResult(id, false, "Move failed"));
+                const statuses = res.output
+                    .split(RECORD_SEP)
+                    .map((s) => s.trim())
+                    .filter((s) => s.length > 0);
+                runnable.forEach((r, k) => {
+                    results[r.index] = this.mapBatchStatus(ids[r.index], statuses[k], "move");
+                });
             }
         }
         return results;

package/build/services/appleNotesManager.test.js

@@ -526,6 +526,19 @@ describe("AppleNotesManager", () => {
             expect(results[1].id).toBe("x-coredata://ABC/ICNote/p2");
             expect(results[1].folder).toBe("Notes");
         });
+        it("deduplicates duplicate note IDs returned by Notes.app", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: [
+                    ["Not uploaded", "x-coredata://ABC/ICNote/p1", "Notes"].join(F),
+                    ["Not uploaded", "x-coredata://ABC/ICNote/p1", "Notes"].join(F),
+                ].join(R),
+            });
+            const results = manager.searchNotes("Not uploaded");
+            expect(results).toHaveLength(1);
+            expect(results[0].title).toBe("Not uploaded");
+            expect(results[0].id).toBe("x-coredata://ABC/ICNote/p1");
+        });
         it("scopes search to specified account", () => {
             mockExecuteAppleScript.mockReturnValue({
                 success: true,
@@ -633,6 +646,15 @@ describe("AppleNotesManager", () => {
             const content = manager.getNoteContent("Missing Note");
             expect(content).toBe("");
         });
+        it("looks up titles containing & literally, not HTML-escaped (regression)", () => {
+            // Bug found in live testing: titles with "&" were HTML-escaped to "&"
+            // in the `note "..."` lookup, so the note could never be found.
+            mockExecuteAppleScript.mockReturnValue({ success: true, output: "<div>x</div>" });
+            manager.getNoteContent("Tom & Jerry", "iCloud");
+            const script = mockExecuteAppleScript.mock.calls[0][0];
+            expect(script).toContain("Tom & Jerry");
+            expect(script).not.toContain("Tom &amp; Jerry");
+        });
         it("uses specified account", () => {
             mockExecuteAppleScript.mockReturnValue({
                 success: true,
@@ -993,7 +1015,11 @@ describe("AppleNotesManager", () => {
         it("returns array of note titles", () => {
             mockExecuteAppleScript.mockReturnValue({
                 success: true,
-                output: ["Note A", "Note B", "Note C"].join(R),
+                output: [
+                    ["Note A", "x-coredata://ABC/ICNote/p1"].join(F),
+                    ["Note B", "x-coredata://ABC/ICNote/p2"].join(F),
+                    ["Note C", "x-coredata://ABC/ICNote/p3"].join(F),
+                ].join(R),
             });
             const titles = manager.listNotes();
             expect(titles).toEqual(["Note A", "Note B", "Note C"]);
@@ -1001,11 +1027,29 @@ describe("AppleNotesManager", () => {
         it("filters out empty entries", () => {
             mockExecuteAppleScript.mockReturnValue({
                 success: true,
-                output: ["Note A", "", "Note B", "", ""].join(R),
+                output: [
+                    ["Note A", "x-coredata://ABC/ICNote/p1"].join(F),
+                    "",
+                    ["Note B", "x-coredata://ABC/ICNote/p2"].join(F),
+                    "",
+                    "",
+                ].join(R),
             });
             const titles = manager.listNotes();
             expect(titles).toEqual(["Note A", "Note B"]);
         });
+        it("deduplicates duplicate note IDs while preserving separate notes with the same title", () => {
+            mockExecuteAppleScript.mockReturnValue({
+                success: true,
+                output: [
+                    ["Same Title", "x-coredata://ABC/ICNote/p1"].join(F),
+                    ["Same Title", "x-coredata://ABC/ICNote/p1"].join(F),
+                    ["Same Title", "x-coredata://ABC/ICNote/p2"].join(F),
+                ].join(R),
+            });
+            const titles = manager.listNotes();
+            expect(titles).toEqual(["Same Title", "Same Title"]);
+        });
         it("throws on failure rather than returning empty (#19)", () => {
             mockExecuteAppleScript.mockReturnValue({
                 success: false,
@@ -1017,7 +1061,10 @@ describe("AppleNotesManager", () => {
         it("filters by folder when specified", () => {
             mockExecuteAppleScript.mockReturnValue({
                 success: true,
-                output: ["Work Note 1", "Work Note 2"].join(R),
+                output: [
+                    ["Work Note 1", "x-coredata://ABC/ICNote/p1"].join(F),
+                    ["Work Note 2", "x-coredata://ABC/ICNote/p2"].join(F),
+                ].join(R),
             });
             manager.listNotes("iCloud", "Work");
             expect(mockExecuteAppleScript).toHaveBeenCalledWith(expect.stringContaining('notes of folder "Work"'));
@@ -1025,7 +1072,10 @@ describe("AppleNotesManager", () => {
         it("uses whose clause when modifiedSince is provided", () => {
             mockExecuteAppleScript.mockReturnValue({
                 success: true,
-                output: ["Recent Note 1", "Recent Note 2"].join(R),
+                output: [
+                    ["Recent Note 1", "x-coredata://ABC/ICNote/p1"].join(F),
+                    ["Recent Note 2", "x-coredata://ABC/ICNote/p2"].join(F),
+                ].join(R),
             });
             const results = manager.listNotes(undefined, undefined, "2025-06-15T00:00:00");
             const script = mockExecuteAppleScript.mock.calls[0][0];
@@ -1040,7 +1090,11 @@ describe("AppleNotesManager", () => {
         it("uses repeat loop when limit is provided", () => {
             mockExecuteAppleScript.mockReturnValue({
                 success: true,
-                output: ["Note 1", "Note 2", "Note 3"].join(R),
+                output: [
+                    ["Note 1", "x-coredata://ABC/ICNote/p1"].join(F),
+                    ["Note 2", "x-coredata://ABC/ICNote/p2"].join(F),
+                    ["Note 3", "x-coredata://ABC/ICNote/p3"].join(F),
+                ].join(R),
             });
             const results = manager.listNotes(undefined, undefined, undefined, 3);
             const script = mockExecuteAppleScript.mock.calls[0][0];
@@ -1050,7 +1104,10 @@ describe("AppleNotesManager", () => {
         it("combines folder, modifiedSince, and limit", () => {
             mockExecuteAppleScript.mockReturnValue({
                 success: true,
-                output: ["Work Note", "Another Work Note"].join(R),
+                output: [
+                    ["Work Note", "x-coredata://ABC/ICNote/p1"].join(F),
+                    ["Another Work Note", "x-coredata://ABC/ICNote/p2"].join(F),
+                ].join(R),
             });
             manager.listNotes("iCloud", "Work", "2025-01-01", 10);
             const script = mockExecuteAppleScript.mock.calls[0][0];
@@ -1069,7 +1126,10 @@ describe("AppleNotesManager", () => {
         it("ignores invalid modifiedSince date and falls back to limit-only", () => {
             mockExecuteAppleScript.mockReturnValue({
                 success: true,
-                output: ["Note 1", "Note 2"].join(R),
+                output: [
+                    ["Note 1", "x-coredata://ABC/ICNote/p1"].join(F),
+                    ["Note 2", "x-coredata://ABC/ICNote/p2"].join(F),
+                ].join(R),
             });
             const results = manager.listNotes(undefined, undefined, "not-a-date", 5);
             const script = mockExecuteAppleScript.mock.calls[0][0];
@@ -1390,7 +1450,13 @@ describe("AppleNotesManager", () => {
                 // Check 3: listAccounts
                 .mockReturnValueOnce({ success: true, output: "iCloud" })
                 // Check 4: listNotes
-                .mockReturnValueOnce({ success: true, output: ["Note 1", "Note 2"].join(R) });
+                .mockReturnValueOnce({
+                success: true,
+                output: [
+                    ["Note 1", "x-coredata://ABC/ICNote/p1"].join(F),
+                    ["Note 2", "x-coredata://ABC/ICNote/p2"].join(F),
+                ].join(R),
+            });
             const result = manager.healthCheck();
             expect(result.healthy).toBe(true);
             expect(result.checks).toHaveLength(4);
@@ -1489,6 +1555,56 @@ describe("AppleNotesManager", () => {
             expect(stats.accounts[0].name).toBe("iCloud");
             expect(stats.accounts[1].name).toBe("Gmail");
         });
+        it("reports complete coverage when every scope succeeds (#19)", () => {
+            mockExecuteAppleScript
+                .mockReturnValueOnce({ success: true, output: "iCloud" })
+                .mockReturnValueOnce({ success: true, output: ["Notes", "3"].join(F) + R })
+                .mockReturnValueOnce({ success: true, output: ["1", "2", "3"].join(F) });
+            const stats = manager.getNotesStats();
+            expect(stats.coverage.complete).toBe(true);
+            expect(stats.coverage.warnings).toEqual([]);
+            expect(stats.coverage.covered).toBe(stats.coverage.scanned);
+        });
+        it("degrades gracefully when one account fails, with a coverage warning (#19)", () => {
+            mockExecuteAppleScript
+                // listAccounts
+                .mockReturnValueOnce({ success: true, output: ["iCloud", "Gmail"].join(R) })
+                // iCloud folder counts succeed
+                .mockReturnValueOnce({ success: true, output: ["Notes", "4"].join(F) + R })
+                // Gmail folder counts FAIL
+                .mockReturnValueOnce({ success: false, output: "", error: "Gmail account is locked" })
+                // getRecentlyModifiedCounts succeed
+                .mockReturnValueOnce({ success: true, output: ["0", "0", "0"].join(F) });
+            const stats = manager.getNotesStats();
+            // Healthy account's data is preserved, not discarded
+            expect(stats.totalNotes).toBe(4);
+            expect(stats.accounts).toHaveLength(1);
+            expect(stats.accounts[0].name).toBe("iCloud");
+            // Failure surfaced as a coverage warning
+            expect(stats.coverage.complete).toBe(false);
+            expect(stats.coverage.warnings).toHaveLength(1);
+            expect(stats.coverage.warnings[0].scope).toBe("Gmail");
+            expect(stats.coverage.warnings[0].reason).toContain("locked");
+        });
+        it("flags recent-activity failure as a coverage warning, not fake zeros (#19)", () => {
+            mockExecuteAppleScript
+                .mockReturnValueOnce({ success: true, output: "iCloud" })
+                .mockReturnValueOnce({ success: true, output: ["Notes", "5"].join(F) + R })
+                // getRecentlyModifiedCounts FAILS
+                .mockReturnValueOnce({ success: false, output: "", error: "timed out" });
+            const stats = manager.getNotesStats();
+            expect(stats.totalNotes).toBe(5);
+            expect(stats.recentlyModified.last24h).toBe(0);
+            expect(stats.coverage.complete).toBe(false);
+            expect(stats.coverage.warnings.some((w) => w.scope === "recent-activity")).toBe(true);
+        });
+        it("throws when no account can be read at all (#19)", () => {
+            mockExecuteAppleScript
+                .mockReturnValueOnce({ success: true, output: ["iCloud", "Gmail"].join(R) })
+                .mockReturnValueOnce({ success: false, output: "", error: "iCloud unreachable" })
+                .mockReturnValueOnce({ success: false, output: "", error: "Gmail unreachable" });
+            expect(() => manager.getNotesStats()).toThrow(/Failed to read folder stats for any/);
+        });
     });
     // ---------------------------------------------------------------------------
     // Attachment Listing
@@ -1569,50 +1685,23 @@ describe("AppleNotesManager", () => {
     // Batch Operations
     // ---------------------------------------------------------------------------
     describe("batchDeleteNotes", () => {
-        // Helper to create getNoteById mock output (matches AppleScript format)
-        const noteByIdOutput = (title, passwordProtected = false) => [
-            title,
-            "x-coredata://ABC/ICNote/p1",
-            "Sunday, January 1, 2025 at 1:00:00 PM",
-            "Sunday, January 1, 2025 at 1:00:00 PM",
-            "false",
-            String(passwordProtected),
-        ].join(F);
-        it("deletes multiple notes successfully", () => {
-            // For each note: getNoteById (which isNotePasswordProtectedById also calls), deleteNoteById
-            mockExecuteAppleScript
-                // First note: getNoteById for existence check
-                .mockReturnValueOnce({ success: true, output: noteByIdOutput("Note 1", false) })
-                // First note: getNoteById for password check (isNotePasswordProtectedById calls getNoteById)
-                .mockReturnValueOnce({ success: true, output: noteByIdOutput("Note 1", false) })
-                // First note: deleteNoteById
-                .mockReturnValueOnce({ success: true, output: "" })
-                // Second note: getNoteById for existence check
-                .mockReturnValueOnce({ success: true, output: noteByIdOutput("Note 2", false) })
-                // Second note: getNoteById for password check
-                .mockReturnValueOnce({ success: true, output: noteByIdOutput("Note 2", false) })
-                // Second note: deleteNoteById
-                .mockReturnValueOnce({ success: true, output: "" });
-            const results = manager.batchDeleteNotes([
-                "x-coredata://ABC00000-0000-0000-0000-000000000011/ICNote/p1",
-                "x-coredata://ABC00000-0000-0000-0000-000000000012/ICNote/p2",
-            ]);
-            expect(results).toHaveLength(2);
-            expect(results[0]).toEqual({
-                id: "x-coredata://ABC00000-0000-0000-0000-000000000011/ICNote/p1",
-                success: true,
-            });
-            expect(results[1]).toEqual({
-                id: "x-coredata://ABC00000-0000-0000-0000-000000000012/ICNote/p2",
+        const ID1 = "x-coredata://ABC00000-0000-0000-0000-000000000011/ICNote/p1";
+        const ID2 = "x-coredata://ABC00000-0000-0000-0000-000000000012/ICNote/p2";
+        it("deletes the whole batch in a single osascript spawn (#26)", () => {
+            // One script handles all ids; per-id status tokens joined by RECORD_SEP.
+            mockExecuteAppleScript.mockReturnValueOnce({
                 success: true,
+                output: ["ok", "ok"].join(R) + R,
             });
+            const results = manager.batchDeleteNotes([ID1, ID2]);
+            // Exactly one spawn for N notes, not 3N.
+            expect(mockExecuteAppleScript).toHaveBeenCalledTimes(1);
+            expect(results).toHaveLength(2);
+            expect(results[0]).toEqual({ id: ID1, success: true });
+            expect(results[1]).toEqual({ id: ID2, success: true });
         });
         it("returns error for non-existent note", () => {
-            mockExecuteAppleScript.mockReturnValueOnce({
-                success: false,
-                output: "",
-                error: "Not found",
-            });
+            mockExecuteAppleScript.mockReturnValueOnce({ success: true, output: "missing" + R });
             const results = manager.batchDeleteNotes([
                 "x-coredata://ABC00000-0000-0000-0000-000000000099/ICNote/p404",
             ]);
@@ -1623,97 +1712,58 @@ describe("AppleNotesManager", () => {
             });
         });
         it("returns error for password-protected note", () => {
-            mockExecuteAppleScript
-                // getNoteById for existence check
-                .mockReturnValueOnce({ success: true, output: noteByIdOutput("Locked Note", true) })
-                // getNoteById for password check (returns true for passwordProtected)
-                .mockReturnValueOnce({ success: true, output: noteByIdOutput("Locked Note", true) });
-            const results = manager.batchDeleteNotes([
-                "x-coredata://ABC00000-0000-0000-0000-000000000011/ICNote/p1",
-            ]);
-            expect(results[0]).toEqual({
-                id: "x-coredata://ABC00000-0000-0000-0000-000000000011/ICNote/p1",
-                success: false,
-                error: "Note is password-protected",
-            });
+            mockExecuteAppleScript.mockReturnValueOnce({ success: true, output: "pw" + R });
+            const results = manager.batchDeleteNotes([ID1]);
+            expect(results[0]).toEqual({ id: ID1, success: false, error: "Note is password-protected" });
         });
-        it("handles mixed success and failure", () => {
-            mockExecuteAppleScript
-                // First note: success
-                .mockReturnValueOnce({ success: true, output: noteByIdOutput("Note 1", false) })
-                .mockReturnValueOnce({ success: true, output: noteByIdOutput("Note 1", false) })
-                .mockReturnValueOnce({ success: true, output: "" })
-                // Second note: not found
-                .mockReturnValueOnce({ success: false, output: "", error: "Not found" });
-            const results = manager.batchDeleteNotes([
-                "x-coredata://ABC00000-0000-0000-0000-000000000011/ICNote/p1",
-                "x-coredata://ABC00000-0000-0000-0000-000000000012/ICNote/p2",
-            ]);
-            expect(results[0]).toEqual({
-                id: "x-coredata://ABC00000-0000-0000-0000-000000000011/ICNote/p1",
+        it("handles mixed success and failure, preserving order", () => {
+            mockExecuteAppleScript.mockReturnValueOnce({
                 success: true,
+                output: ["ok", "missing"].join(R) + R,
             });
-            expect(results[1]).toEqual({
-                id: "x-coredata://ABC00000-0000-0000-0000-000000000012/ICNote/p2",
+            const results = manager.batchDeleteNotes([ID1, ID2]);
+            expect(results[0]).toEqual({ id: ID1, success: true });
+            expect(results[1]).toEqual({ id: ID2, success: false, error: "Note not found" });
+        });
+        it("fails an invalid id without spawning, isolating it from valid ids", () => {
+            mockExecuteAppleScript.mockReturnValueOnce({ success: true, output: "ok" + R });
+            const results = manager.batchDeleteNotes(["not-a-valid-id", ID1]);
+            expect(results[0].success).toBe(false);
+            expect(results[0].error).toMatch(/Invalid note ID/);
+            expect(results[1]).toEqual({ id: ID1, success: true });
+        });
+        it("fails the whole batch when the single script errors", () => {
+            mockExecuteAppleScript.mockReturnValueOnce({
                 success: false,
-                error: "Note not found",
+                output: "",
+                error: "Notes.app not responding",
             });
+            const results = manager.batchDeleteNotes([ID1, ID2]);
+            expect(results.every((r) => r.success === false)).toBe(true);
+            expect(results[0].error).toContain("Notes.app not responding");
+        });
+        it("returns [] for an empty batch without spawning", () => {
+            const results = manager.batchDeleteNotes([]);
+            expect(results).toEqual([]);
+            expect(mockExecuteAppleScript).not.toHaveBeenCalled();
         });
     });
     describe("batchMoveNotes", () => {
-        // Helper to create getNoteById mock output (matches AppleScript format)
-        const noteByIdOutput = (title, passwordProtected = false) => [
-            title,
-            "x-coredata://ABC/ICNote/p1",
-            "Sunday, January 1, 2025 at 1:00:00 PM",
-            "Sunday, January 1, 2025 at 1:00:00 PM",
-            "false",
-            String(passwordProtected),
-        ].join(F);
-        it("moves multiple notes successfully", () => {
-            // For each note: getNoteById, getNoteById (password check), getNoteContentById, create, delete
-            mockExecuteAppleScript
-                // First note: getNoteById for existence check
-                .mockReturnValueOnce({ success: true, output: noteByIdOutput("Note 1", false) })
-                // First note: getNoteById for password check
-                .mockReturnValueOnce({ success: true, output: noteByIdOutput("Note 1", false) })
-                // First note: moveNoteById calls getNoteContentById
-                .mockReturnValueOnce({ success: true, output: "<div>Note 1</div><div>Content</div>" })
-                // First note: createNote in destination
-                .mockReturnValueOnce({ success: true, output: "" })
-                // First note: deleteNoteById (original)
-                .mockReturnValueOnce({ success: true, output: "" })
-                // Second note: getNoteById for existence check
-                .mockReturnValueOnce({ success: true, output: noteByIdOutput("Note 2", false) })
-                // Second note: getNoteById for password check
-                .mockReturnValueOnce({ success: true, output: noteByIdOutput("Note 2", false) })
-                // Second note: moveNoteById calls getNoteContentById
-                .mockReturnValueOnce({ success: true, output: "<div>Note 2</div><div>Content</div>" })
-                // Second note: createNote in destination
-                .mockReturnValueOnce({ success: true, output: "" })
-                // Second note: deleteNoteById (original)
-                .mockReturnValueOnce({ success: true, output: "" });
-            const results = manager.batchMoveNotes([
-                "x-coredata://ABC00000-0000-0000-0000-000000000011/ICNote/p1",
-                "x-coredata://ABC00000-0000-0000-0000-000000000012/ICNote/p2",
-            ], "Archive");
-            expect(results).toHaveLength(2);
-            expect(results[0]).toEqual({
-                id: "x-coredata://ABC00000-0000-0000-0000-000000000011/ICNote/p1",
-                success: true,
-            });
-            expect(results[1]).toEqual({
-                id: "x-coredata://ABC00000-0000-0000-0000-000000000012/ICNote/p2",
+        const ID1 = "x-coredata://ABC00000-0000-0000-0000-000000000011/ICNote/p1";
+        const ID2 = "x-coredata://ABC00000-0000-0000-0000-000000000012/ICNote/p2";
+        it("moves the whole batch in a single osascript spawn (#26)", () => {
+            mockExecuteAppleScript.mockReturnValueOnce({
                 success: true,
+                output: ["ok", "ok"].join(R) + R,
             });
+            const results = manager.batchMoveNotes([ID1, ID2], "Archive");
+            expect(mockExecuteAppleScript).toHaveBeenCalledTimes(1);
+            expect(results).toHaveLength(2);
+            expect(results[0]).toEqual({ id: ID1, success: true });
+            expect(results[1]).toEqual({ id: ID2, success: true });
         });
         it("returns error for non-existent note", () => {
-            // getNoteById fails for existence check
-            mockExecuteAppleScript.mockReturnValueOnce({
-                success: false,
-                output: "",
-                error: "Not found",
-            });
+            mockExecuteAppleScript.mockReturnValueOnce({ success: true, output: "missing" + R });
             const results = manager.batchMoveNotes(["x-coredata://ABC00000-0000-0000-0000-000000000099/ICNote/p404"], "Archive");
             expect(results[0]).toEqual({
                 id: "x-coredata://ABC00000-0000-0000-0000-000000000099/ICNote/p404",
@@ -1722,17 +1772,18 @@ describe("AppleNotesManager", () => {
             });
         });
         it("returns error for password-protected note", () => {
-            mockExecuteAppleScript
-                // getNoteById for existence check
-                .mockReturnValueOnce({ success: true, output: noteByIdOutput("Locked Note", true) })
-                // getNoteById for password check (returns true for passwordProtected)
-                .mockReturnValueOnce({ success: true, output: noteByIdOutput("Locked Note", true) });
-            const results = manager.batchMoveNotes(["x-coredata://ABC00000-0000-0000-0000-000000000011/ICNote/p1"], "Archive");
-            expect(results[0]).toEqual({
-                id: "x-coredata://ABC00000-0000-0000-0000-000000000011/ICNote/p1",
-                success: false,
-                error: "Note is password-protected",
+            mockExecuteAppleScript.mockReturnValueOnce({ success: true, output: "pw" + R });
+            const results = manager.batchMoveNotes([ID1], "Archive");
+            expect(results[0]).toEqual({ id: ID1, success: false, error: "Note is password-protected" });
+        });
+        it("maps a per-item move failure to 'Move failed'", () => {
+            mockExecuteAppleScript.mockReturnValueOnce({
+                success: true,
+                output: ["ok", "fail"].join(R) + R,
             });
+            const results = manager.batchMoveNotes([ID1, ID2], "Archive");
+            expect(results[0]).toEqual({ id: ID1, success: true });
+            expect(results[1]).toEqual({ id: ID2, success: false, error: "Move failed" });
         });
     });
     // ---------------------------------------------------------------------------
@@ -1755,7 +1806,10 @@ describe("AppleNotesManager", () => {
                 // listFolders for iCloud
                 .mockReturnValueOnce({ success: true, output: "id1\tNotes" })
                 // listNotes for Notes folder
-                .mockReturnValueOnce({ success: true, output: "Test Note" })
+                .mockReturnValueOnce({
+                success: true,
+                output: ["Test Note", "x-coredata://ABC/ICNote/p1"].join(F),
+            })
                 // getNoteDetails
                 .mockReturnValueOnce({ success: true, output: noteDetailsOutput("Test Note", false) })
                 // getNoteContent
@@ -1780,7 +1834,10 @@ describe("AppleNotesManager", () => {
                 // listFolders for iCloud
                 .mockReturnValueOnce({ success: true, output: "id1\tNotes" })
                 // listNotes for Notes folder
-                .mockReturnValueOnce({ success: true, output: "Locked Note" })
+                .mockReturnValueOnce({
+                success: true,
+                output: ["Locked Note", "x-coredata://ABC/ICNote/p1"].join(F),
+            })
                 // getNoteDetails (passwordProtected = true)
                 .mockReturnValueOnce({ success: true, output: noteDetailsOutput("Locked Note", true) });
             // No getNoteContent call because note is password-protected

package/build/utils/hashtags.js

@@ -0,0 +1,56 @@
+/**
+ * Inline hashtag extraction for Apple Notes.
+ *
+ * Apple Notes "tags" are not a first-class AppleScript property — they are
+ * inline `#hashtag` tokens typed into the note body. Notes stores the tag
+ * relationship in its private Core Data store, which AppleScript does not
+ * expose, so the only way to surface a note's tags is to parse them back out
+ * of the body text. This module does exactly that.
+ *
+ * See docs/APPLESCRIPT-LIMITATIONS.md and issue #29.
+ */
+/**
+ * Strip HTML tags from a Notes body and neutralise numeric character
+ * references so they can't masquerade as hashtags (e.g. `’`).
+ */
+function htmlToText(html) {
+    return html
+        .replace(/<[^>]*>/g, " ") // drop tags
+        .replace(/&#x?[0-9a-f]+;/gi, " ") // neutralise numeric entities (&#8217;)
+        .replace(/&[a-z]+;/gi, " "); // neutralise named entities (&amp; &nbsp;)
+}
+/**
+ * A hashtag token: `#` followed by a run of letters/digits/underscores that
+ * contains at least one letter. This matches Apple Notes' own rule — a purely
+ * numeric token like `#123` is NOT treated as a tag. The token must not be
+ * preceded by a word character, so `foo#bar` and URL fragments like
+ * `page.html#section` (preceded by a letter) are ignored.
+ */
+const HASHTAG_RE = /(?<![\p{L}\p{N}_])#([\p{L}\p{N}_]*\p{L}[\p{L}\p{N}_]*)/gu;
+/**
+ * Extract inline `#hashtag` tokens from a note body (HTML or plain text).
+ *
+ * - HTML is stripped first, so tags inside `<div>#work</div>` are found.
+ * - Pure-number tokens (`#123`) are ignored, matching Notes' behaviour.
+ * - Results are de-duplicated case-insensitively, preserving the first-seen
+ *   casing and document order. The leading `#` is not included.
+ *
+ * @param body - The note body, as HTML or plain text.
+ * @returns Ordered, de-duplicated tag names without the leading `#`.
+ */
+export function parseHashtags(body) {
+    if (!body)
+        return [];
+    const text = htmlToText(body);
+    const seen = new Set();
+    const result = [];
+    for (const match of text.matchAll(HASHTAG_RE)) {
+        const tag = match[1];
+        const key = tag.toLowerCase();
+        if (!seen.has(key)) {
+            seen.add(key);
+            result.push(tag);
+        }
+    }
+    return result;
+}

package/build/utils/hashtags.test.js

@@ -0,0 +1,45 @@
+import { describe, it, expect } from "vitest";
+import { parseHashtags } from "../utils/hashtags.js";
+describe("parseHashtags", () => {
+    it("returns [] for empty / nullish input", () => {
+        expect(parseHashtags("")).toEqual([]);
+        expect(parseHashtags(null)).toEqual([]);
+        expect(parseHashtags(undefined)).toEqual([]);
+        expect(parseHashtags("no tags here")).toEqual([]);
+    });
+    it("extracts a single tag", () => {
+        expect(parseHashtags("Buy milk #groceries")).toEqual(["groceries"]);
+    });
+    it("extracts multiple tags in document order", () => {
+        expect(parseHashtags("#work then #home then #travel")).toEqual(["work", "home", "travel"]);
+    });
+    it("strips the leading # and not the rest", () => {
+        expect(parseHashtags("#project_alpha")).toEqual(["project_alpha"]);
+    });
+    it("finds tags inside HTML bodies", () => {
+        expect(parseHashtags("<div>Plan <b>#q3</b> launch</div>")).toEqual(["q3"]);
+    });
+    it("de-duplicates case-insensitively, keeping first-seen casing", () => {
+        expect(parseHashtags("#Work and #work and #WORK")).toEqual(["Work"]);
+    });
+    it("ignores purely numeric tokens (matches Notes behaviour)", () => {
+        expect(parseHashtags("ticket #123 and #4you")).toEqual(["4you"]);
+    });
+    it("does not match mid-word or URL fragments", () => {
+        expect(parseHashtags("foo#bar")).toEqual([]);
+        expect(parseHashtags("see page.html#section for details")).toEqual([]);
+    });
+    it("does not treat numeric HTML entities as tags", () => {
+        // &#8217; is a right single quote entity, not a #8217 tag
+        expect(parseHashtags("It&#8217;s a #plan")).toEqual(["plan"]);
+    });
+    it("matches a tag at the very start of the body", () => {
+        expect(parseHashtags("#start of note")).toEqual(["start"]);
+    });
+    it("handles tags terminated by punctuation", () => {
+        expect(parseHashtags("done: #alpha, #beta; #gamma.")).toEqual(["alpha", "beta", "gamma"]);
+    });
+    it("supports unicode letters in tags", () => {
+        expect(parseHashtags("café trip #café")).toEqual(["café"]);
+    });
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "apple-notes-mcp",
-  "version": "2.0.0",
-  "description": "MCP server for Apple Notes - create, search, update, and manage notes via Claude",
+  "version": "2.1.0",
+  "description": "MCP server for Apple Notes - create, search, update, and manage notes via Claude and Codex",
   "type": "module",
   "main": "build/index.js",
   "types": "build/index.d.ts",
@@ -20,19 +20,22 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "test:all": "vitest run && vitest run --config vitest.integration.config.ts",
     "lint": "eslint src",
     "lint:fix": "eslint src --fix",
     "format": "prettier --write src",
     "format:check": "prettier --check src",
     "typecheck": "tsc --noEmit",
-    "version": "node -e \"const p=require('./package.json'); const f='.claude-plugin/plugin.json'; const c=JSON.parse(require('fs').readFileSync(f,'utf8')); c.version=p.version; require('fs').writeFileSync(f,JSON.stringify(c,null,2)+'\\n')\" && git add .claude-plugin/plugin.json",
+    "version": "node scripts/sync-plugin-version.mjs && git add .claude-plugin/plugin.json .claude-plugin/marketplace.json .agents/plugins/marketplace.json codex/.codex-plugin/plugin.json",
     "prepublishOnly": "npm run lint && npm run test && npm run build",
-    "prepare": "husky && npm run build"
+    "prepare": "husky; npm run build"
   },
   "keywords": [
     "mcp",
     "apple-notes",
     "claude",
+    "codex",
     "ai",
     "applescript",
     "macos",