@lifestreamdynamics/vault-cli 1.3.11 → 1.4.4

package/dist/commands/audit.js

@@ -2,7 +2,7 @@ import chalk from 'chalk';
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
-import { AuditLogger } from '@lifestreamdynamics/vault-sdk';
+import { AuditLogger } from '@lifestreamdynamics/vault-sdk/audit';
 import { addGlobalFlags, resolveFlags } from '../utils/flags.js';
 import { createOutput, handleError } from '../utils/output.js';
 const DEFAULT_LOG_PATH = path.join(os.homedir(), '.lsvault', 'audit.log');

package/dist/commands/hooks.js

@@ -3,6 +3,21 @@ import { getClientAsync } from '../client.js';
 import { addGlobalFlags, resolveFlags } from '../utils/flags.js';
 import { createOutput, handleError } from '../utils/output.js';
 import { resolveVaultId } from '../utils/resolve-vault.js';
+/**
+ * Valid hook trigger events. Unlike webhooks, hooks do NOT accept the `*`
+ * wildcard. Inlined from the internal vault-shared package (not published to
+ * npm) so the standalone CLI build has no unpublishable workspace dependency.
+ * Keep in sync with VAULT_EVENT_TYPES in packages/shared/src/constants.ts.
+ */
+const VAULT_EVENT_TYPES = [
+    'document.created', 'document.updated', 'document.deleted', 'document.moved', 'document.copied',
+    'directory.created', 'document.overdue', 'document.due-soon',
+    'calendar.event.created', 'calendar.event.updated', 'calendar.event.deleted', 'calendar.event.due',
+    'calendar.event.overdue', 'calendar.event.status_changed',
+    'booking.created', 'booking.confirmed', 'booking.cancelled', 'booking.no_show', 'booking.completed',
+    'booking.reminder', 'booking.rescheduled',
+    'calendar.event.participant.added', 'calendar.event.participant.responded',
+];
 export function registerHookCommands(program) {
     const hooks = program.command('hooks').description('Manage vault event hooks');
     addGlobalFlags(hooks.command('list')
@@ -49,17 +64,35 @@ export function registerHookCommands(program) {
         .description('Create a new hook')
         .argument('<vaultId>', 'Vault ID or slug')
         .argument('<name>', 'Hook name')
-        .requiredOption('--trigger <event>', 'Trigger event (document.created, document.updated, document.deleted, document.moved, document.copied)')
+        .requiredOption('--trigger <event>', 'Trigger event (e.g. document.created, calendar.event.created, booking.confirmed)')
         .requiredOption('--action <type>', 'Action type (webhook, ai_prompt, document_operation, auto_calendar_event, auto_booking_process)')
         .requiredOption('--config <json>', 'Action configuration as JSON')
         .option('--filter <json>', 'Trigger filter as JSON')
         .addHelpText('after', `
-VALID TRIGGER EVENTS
-  document.created        Document was created
-  document.updated        Document content was updated
-  document.deleted        Document was deleted
-  document.moved          Document was moved or renamed
-  document.copied         Document was copied
+VALID TRIGGER EVENTS (no wildcard — hooks fire on a single event type)
+  document.created                    Document was created
+  document.updated                    Document content was updated
+  document.deleted                    Document was deleted
+  document.moved                      Document was moved or renamed
+  document.copied                     Document was copied
+  directory.created                   Directory was created
+  document.overdue                    Document is past its due date
+  document.due-soon                   Document is due soon
+  calendar.event.created              Calendar event was created
+  calendar.event.updated              Calendar event was updated
+  calendar.event.deleted              Calendar event was deleted
+  calendar.event.due                  Calendar event is due
+  calendar.event.overdue              Calendar event is overdue
+  calendar.event.status_changed       Calendar event status changed
+  booking.created                     Booking was created
+  booking.confirmed                   Booking was confirmed
+  booking.cancelled                   Booking was cancelled
+  booking.no_show                     Booking was marked no-show
+  booking.completed                   Booking was completed
+  booking.reminder                    Booking reminder sent
+  booking.rescheduled                 Booking was rescheduled
+  calendar.event.participant.added    Participant added to event
+  calendar.event.participant.responded Participant responded to event
 
 VALID ACTION TYPES
   webhook                 Send an HTTP notification to a URL
@@ -71,6 +104,7 @@ VALID ACTION TYPES
 EXAMPLES
   lsvault hooks create <vaultId> my-hook --trigger document.created --action webhook --config '{"url":"https://example.com/hook"}'
   lsvault hooks create <vaultId> ai-tag --trigger document.created --action ai_prompt --config '{"prompt":"Suggest tags"}'
+  lsvault hooks create <vaultId> booking-hook --trigger booking.confirmed --action webhook --config '{"url":"https://example.com/hook"}'
   lsvault hooks create <vaultId> move-docs --trigger document.created --action document_operation --config '{"operation":"move","targetPath":"inbox/"}'`))
         .action(async (vaultId, name, _opts) => {
         const flags = resolveFlags(_opts);
@@ -95,12 +129,12 @@ EXAMPLES
                 return;
             }
         }
-        const VALID_TRIGGERS = ['document.created', 'document.updated', 'document.deleted', 'document.moved', 'document.copied'];
+        const VALID_TRIGGERS = VAULT_EVENT_TYPES;
         const VALID_ACTIONS = ['webhook', 'ai_prompt', 'document_operation', 'auto_calendar_event', 'auto_booking_process'];
         const trigger = String(_opts.trigger);
         const action = String(_opts.action);
         if (!VALID_TRIGGERS.includes(trigger)) {
-            out.error(`Invalid trigger "${trigger}". Valid values: document.created, document.updated, document.deleted, document.moved, document.copied`);
+            out.error(`Invalid trigger "${trigger}". Valid values: ${VALID_TRIGGERS.join(', ')}`);
             process.exitCode = 1;
             return;
         }

package/dist/commands/sync.js

@@ -169,16 +169,24 @@ Sync modes:
             const ignorePatterns = resolveIgnorePatterns(config.ignore, config.localPath);
             const lastState = loadSyncState(config.id);
             out.startSpinner('Scanning local files...');
-            const localFiles = scanLocalFiles(config.localPath, ignorePatterns);
+            const localFiles = scanLocalFiles(config.localPath, ignorePatterns, lastState);
             out.debug(`Found ${Object.keys(localFiles).length} local files`);
             out.startSpinner('Scanning remote files...');
-            const remoteFiles = await scanRemoteFiles(client, config.vaultId, ignorePatterns);
+            const remoteResult = await scanRemoteFiles(client, config.vaultId, ignorePatterns, { remote: lastState.remote ?? {}, remoteListEtag: lastState.remoteListEtag });
+            const remoteFiles = remoteResult.files;
             out.debug(`Found ${Object.keys(remoteFiles).length} remote files`);
             out.startSpinner('Computing diff...');
             const diff = computePullDiff(localFiles, remoteFiles, lastState);
             const unchanged = Object.keys(remoteFiles).length - diff.downloads.length;
             const totalOps = diff.downloads.length + diff.deletes.length;
+            // Persist the new list ETag regardless of whether there are changes
+            if (remoteResult.listEtag) {
+                lastState.remoteListEtag = remoteResult.listEtag;
+            }
             if (totalOps === 0) {
+                if (remoteResult.listEtag) {
+                    saveSyncState(lastState);
+                }
                 out.succeedSpinner('Everything is up to date');
                 if (flags.output === 'json') {
                     out.record({
@@ -218,7 +226,9 @@ Sync modes:
                 if (progress.phase === 'transferring' && progress.currentFile) {
                     out.startSpinner(`[${progress.current}/${progress.total}] ${progress.currentFile}`);
                 }
-            }, concurrency);
+            }, concurrency, (file) => {
+                out.startSpinner(`Rate limited — waiting and retrying… (${file})`);
+            });
             if (result.errors.length > 0) {
                 out.failSpinner(`Pull completed with ${result.errors.length} error(s)`);
                 for (const err of result.errors) {
@@ -259,16 +269,24 @@ Sync modes:
             const ignorePatterns = resolveIgnorePatterns(config.ignore, config.localPath);
             const lastState = loadSyncState(config.id);
             out.startSpinner('Scanning local files...');
-            const localFiles = scanLocalFiles(config.localPath, ignorePatterns);
+            const localFiles = scanLocalFiles(config.localPath, ignorePatterns, lastState);
             out.debug(`Found ${Object.keys(localFiles).length} local files`);
             out.startSpinner('Scanning remote files...');
-            const remoteFiles = await scanRemoteFiles(client, config.vaultId, ignorePatterns);
+            const remoteResult = await scanRemoteFiles(client, config.vaultId, ignorePatterns, { remote: lastState.remote ?? {}, remoteListEtag: lastState.remoteListEtag });
+            const remoteFiles = remoteResult.files;
             out.debug(`Found ${Object.keys(remoteFiles).length} remote files`);
             out.startSpinner('Computing diff...');
             const diff = computePushDiff(localFiles, remoteFiles, lastState);
             const unchanged = Object.keys(localFiles).length - diff.uploads.length;
             const totalOps = diff.uploads.length + diff.deletes.length;
+            // Persist the new list ETag regardless of whether there are changes
+            if (remoteResult.listEtag) {
+                lastState.remoteListEtag = remoteResult.listEtag;
+            }
             if (totalOps === 0) {
+                if (remoteResult.listEtag) {
+                    saveSyncState(lastState);
+                }
                 out.succeedSpinner('Everything is up to date');
                 if (flags.output === 'json') {
                     out.record({
@@ -308,7 +326,9 @@ Sync modes:
                 if (progress.phase === 'transferring' && progress.currentFile) {
                     out.startSpinner(`[${progress.current}/${progress.total}] ${progress.currentFile}`);
                 }
-            }, concurrency);
+            }, concurrency, (file) => {
+                out.startSpinner(`Rate limited — waiting and retrying… (${file})`);
+            });
             if (result.errors.length > 0) {
                 out.failSpinner(`Push completed with ${result.errors.length} error(s)`);
                 for (const err of result.errors) {
@@ -348,8 +368,9 @@ Sync modes:
             const ignorePatterns = resolveIgnorePatterns(config.ignore, config.localPath);
             const lastState = loadSyncState(config.id);
             out.startSpinner('Scanning...');
-            const localFiles = scanLocalFiles(config.localPath, ignorePatterns);
-            const remoteFiles = await scanRemoteFiles(client, config.vaultId, ignorePatterns);
+            const localFiles = scanLocalFiles(config.localPath, ignorePatterns, lastState);
+            const remoteResult = await scanRemoteFiles(client, config.vaultId, ignorePatterns, { remote: lastState.remote ?? {}, remoteListEtag: lastState.remoteListEtag });
+            const remoteFiles = remoteResult.files;
             const pullDiff = computePullDiff(localFiles, remoteFiles, lastState);
             const pushDiff = computePushDiff(localFiles, remoteFiles, lastState);
             out.stopSpinner();

package/dist/commands/webhooks.js

@@ -3,6 +3,22 @@ import { getClientAsync } from '../client.js';
 import { addGlobalFlags, resolveFlags } from '../utils/flags.js';
 import { createOutput, handleError } from '../utils/output.js';
 import { resolveVaultId } from '../utils/resolve-vault.js';
+/**
+ * Valid webhook event names, including the `*` wildcard. Inlined from the
+ * internal vault-shared package (not published to npm) so the standalone CLI
+ * build has no unpublishable workspace dependency. Keep in sync with
+ * WEBHOOK_EVENT_TYPES in packages/shared/src/constants.ts.
+ */
+const WEBHOOK_EVENT_TYPES = [
+    '*',
+    'document.created', 'document.updated', 'document.deleted', 'document.moved', 'document.copied',
+    'directory.created', 'document.overdue', 'document.due-soon',
+    'calendar.event.created', 'calendar.event.updated', 'calendar.event.deleted', 'calendar.event.due',
+    'calendar.event.overdue', 'calendar.event.status_changed',
+    'booking.created', 'booking.confirmed', 'booking.cancelled', 'booking.no_show', 'booking.completed',
+    'booking.reminder', 'booking.rescheduled',
+    'calendar.event.participant.added', 'calendar.event.participant.responded',
+];
 export function registerWebhookCommands(program) {
     const webhooks = program.command('webhooks').description('Manage vault webhooks');
     addGlobalFlags(webhooks.command('list')
@@ -46,19 +62,38 @@ export function registerWebhookCommands(program) {
         .description('Create a new webhook')
         .argument('<vaultId>', 'Vault ID or slug')
         .argument('<url>', 'Webhook endpoint URL')
-        .option('--events <events>', 'Comma-separated events (document.created, document.updated, document.deleted, document.moved, document.copied, or * for all)', 'document.created,document.updated,document.deleted')
+        .option('--events <events>', 'Comma-separated events (document.created, calendar.event.created, booking.created, *, etc.)', 'document.created,document.updated,document.deleted')
         .addHelpText('after', `
 VALID EVENT NAMES
-  document.created   Document was created
-  document.updated   Document content was updated
-  document.deleted   Document was deleted
-  document.moved     Document was moved or renamed
-  document.copied    Document was copied
-  *                  All events
+  document.created                    Document was created
+  document.updated                    Document content was updated
+  document.deleted                    Document was deleted
+  document.moved                      Document was moved or renamed
+  document.copied                     Document was copied
+  directory.created                   Directory was created
+  document.overdue                    Document is past its due date
+  document.due-soon                   Document is due soon
+  calendar.event.created              Calendar event was created
+  calendar.event.updated              Calendar event was updated
+  calendar.event.deleted              Calendar event was deleted
+  calendar.event.due                  Calendar event is due
+  calendar.event.overdue              Calendar event is overdue
+  calendar.event.status_changed       Calendar event status changed
+  booking.created                     Booking was created
+  booking.confirmed                   Booking was confirmed
+  booking.cancelled                   Booking was cancelled
+  booking.no_show                     Booking was marked no-show
+  booking.completed                   Booking was completed
+  booking.reminder                    Booking reminder sent
+  booking.rescheduled                 Booking was rescheduled
+  calendar.event.participant.added    Participant added to event
+  calendar.event.participant.responded Participant responded to event
+  *                                   All events
 
 EXAMPLES
   lsvault webhooks create <vaultId> https://example.com/hook
   lsvault webhooks create <vaultId> https://example.com/hook --events "document.created,document.deleted"
+  lsvault webhooks create <vaultId> https://example.com/hook --events "calendar.event.created,booking.created"
   lsvault webhooks create <vaultId> https://example.com/hook --events "*"`))
         .action(async (vaultId, url, _opts) => {
         const flags = resolveFlags(_opts);
@@ -68,7 +103,7 @@ EXAMPLES
             process.exitCode = 1;
             return;
         }
-        const VALID_EVENTS = ['document.created', 'document.updated', 'document.deleted', 'document.moved', 'document.copied', '*'];
+        const VALID_EVENTS = WEBHOOK_EVENT_TYPES;
         const events = String(_opts.events || 'document.created,document.updated,document.deleted').split(',').map((e) => e.trim());
         const invalid = events.filter(e => !VALID_EVENTS.includes(e));
         if (invalid.length > 0) {

package/dist/sync/daemon-worker.js

@@ -11,7 +11,7 @@ import { removePid } from './daemon.js';
 import { loadConfigAsync } from '../config.js';
 import { LifestreamVaultClient } from '@lifestreamdynamics/vault-sdk';
 import { scanLocalFiles, scanRemoteFiles, computePushDiff, computePullDiff, executePush, executePull } from './engine.js';
-import { loadSyncState } from './state.js';
+import { loadSyncState, saveSyncState } from './state.js';
 const managed = [];
 function log(msg) {
     const ts = new Date().toISOString();
@@ -50,8 +50,13 @@ async function start() {
             log(`Reconciling ${config.id.slice(0, 8)} (${config.mode} mode)...`);
             const ignorePatterns = resolveIgnorePatterns(config.ignore, config.localPath);
             const lastState = loadSyncState(config.id);
-            const localFiles = scanLocalFiles(config.localPath, ignorePatterns);
-            const remoteFiles = await scanRemoteFiles(client, config.vaultId, ignorePatterns);
+            const localFiles = scanLocalFiles(config.localPath, ignorePatterns, lastState);
+            const remoteResult = await scanRemoteFiles(client, config.vaultId, ignorePatterns, { remote: lastState.remote ?? {}, remoteListEtag: lastState.remoteListEtag });
+            const remoteFiles = remoteResult.files;
+            if (remoteResult.listEtag) {
+                lastState.remoteListEtag = remoteResult.listEtag;
+                saveSyncState(lastState);
+            }
             let pushed = 0;
             let pulled = 0;
             let deleted = 0;

package/dist/sync/engine.d.ts

@@ -1,5 +1,5 @@
 import type { LifestreamVaultClient } from '@lifestreamdynamics/vault-sdk';
-import type { SyncConfig, FileState } from './types.js';
+import type { SyncConfig, SyncState, FileState } from './types.js';
 import { computePullDiff, computePushDiff, type SyncDiff, type SyncDiffEntry } from './diff.js';
 export interface SyncProgress {
     phase: 'scanning' | 'computing' | 'transferring' | 'complete';
@@ -23,13 +23,40 @@ export interface SyncResult {
 /**
  * Scan local directory recursively for .md files.
  * Returns a map of relative doc paths -> FileState.
+ *
+ * When `lastState` is provided, files whose stat mtime and size match the
+ * persisted entry skip the readFileSync + hash step entirely (D-2 fast-path).
  */
-export declare function scanLocalFiles(localPath: string, ignorePatterns: string[]): Record<string, FileState>;
+export declare function scanLocalFiles(localPath: string, ignorePatterns: string[], lastState?: SyncState): Record<string, FileState>;
+/** Result type for {@link scanRemoteFiles}. */
+export interface ScanRemoteResult {
+    /** Map of doc paths -> FileState for all non-ignored remote files. */
+    files: Record<string, FileState>;
+    /** List ETag from this response, for use in the next call. */
+    listEtag: string;
+    /** True when the server confirmed the vault is unchanged (304 fast-path). */
+    vaultUnchanged: boolean;
+}
+/**
+ * Scan remote vault for document list using the syncList fast-path.
+ *
+ * When `knownState` is provided (with hashes and optionally a prior listEtag),
+ * the server may respond 304 and `vaultUnchanged` will be true — in that case
+ * `files` is rebuilt from `knownState.remote` without any per-doc network call.
+ *
+ * When `knownState` is omitted a full list is always fetched (backward-compat).
+ */
+export declare function scanRemoteFiles(client: LifestreamVaultClient, vaultId: string, ignorePatterns: string[], knownState?: {
+    remote: Record<string, FileState>;
+    remoteListEtag?: string;
+}): Promise<ScanRemoteResult>;
 /**
- * Scan remote vault for document list.
- * Returns a map of doc paths -> FileState.
+ * Called when the SDK signals a 429 response while transferring a file.
+ * The SDK will back off and retry automatically; the CLI uses this to
+ * update the spinner text so the user sees "Rate limited — waiting and retrying…"
+ * rather than an apparently frozen transfer.
  */
-export declare function scanRemoteFiles(client: LifestreamVaultClient, vaultId: string, ignorePatterns: string[]): Promise<Record<string, FileState>>;
+export type ThrottleCallback = (file: string) => void;
 /**
  * Validates and clamps a user-supplied concurrency value. Throws on invalid
  * values so the CLI can surface a clear error before kicking off any I/O.
@@ -38,9 +65,22 @@ export declare function resolveConcurrency(value: number | undefined): number;
 /**
  * Execute a pull operation: download remote changes to local.
  */
-export declare function executePull(client: LifestreamVaultClient, config: SyncConfig, diff: SyncDiff, onProgress?: ProgressCallback, concurrency?: number): Promise<SyncResult>;
+export declare function executePull(client: LifestreamVaultClient, config: SyncConfig, diff: SyncDiff, onProgress?: ProgressCallback, concurrency?: number, onThrottle?: ThrottleCallback): Promise<SyncResult>;
 /**
  * Execute a push operation: upload local changes to remote.
  */
-export declare function executePush(client: LifestreamVaultClient, config: SyncConfig, diff: SyncDiff, onProgress?: ProgressCallback, concurrency?: number): Promise<SyncResult>;
+export declare function executePush(client: LifestreamVaultClient, config: SyncConfig, diff: SyncDiff, onProgress?: ProgressCallback, concurrency?: number, onThrottle?: ThrottleCallback): Promise<SyncResult>;
+/**
+ * Returns true when an error represents an HTTP 429 (Too Many Requests / rate
+ * limited) response. The SDK retries 429s transparently; a 429 reaching here
+ * means all retry attempts were exhausted.
+ *
+ * Prefers the structured status code the SDK attaches (RateLimitError sets
+ * `statusCode = 429`) and only falls back to a narrow message match. The
+ * message fallback is intentionally strict — it does NOT match "rate limit" or
+ * "throttle" loosely, since those words appear in unrelated errors (e.g. an
+ * authorization message mentioning a rate-limited account) and a false positive
+ * would suppress a real error.
+ */
+export declare function isThrottleError(err: unknown): boolean;
 export { computePullDiff, computePushDiff, type SyncDiff, type SyncDiffEntry };

package/dist/sync/engine.js

@@ -11,8 +11,11 @@ import { computePullDiff, computePushDiff } from './diff.js';
 /**
  * Scan local directory recursively for .md files.
  * Returns a map of relative doc paths -> FileState.
+ *
+ * When `lastState` is provided, files whose stat mtime and size match the
+ * persisted entry skip the readFileSync + hash step entirely (D-2 fast-path).
  */
-export function scanLocalFiles(localPath, ignorePatterns) {
+export function scanLocalFiles(localPath, ignorePatterns, lastState) {
     const files = {};
     function walk(dir, prefix) {
         if (!fs.existsSync(dir))
@@ -28,14 +31,21 @@ export function scanLocalFiles(localPath, ignorePatterns) {
             else if (entry.isFile() && entry.name.endsWith('.md')) {
                 if (!shouldIgnore(relPath, ignorePatterns)) {
                     const absPath = path.join(dir, entry.name);
-                    const content = fs.readFileSync(absPath);
                     const stat = fs.statSync(absPath);
-                    files[relPath] = {
-                        path: relPath,
-                        hash: hashFileContent(content),
-                        mtime: stat.mtime.toISOString(),
-                        size: stat.size,
-                    };
+                    const stored = lastState?.local?.[relPath];
+                    if (stored && stat.size === stored.size && stat.mtime.toISOString() === stored.mtime) {
+                        // mtime+size unchanged — reuse persisted hash, skip file read
+                        files[relPath] = stored;
+                    }
+                    else {
+                        const content = fs.readFileSync(absPath);
+                        files[relPath] = {
+                            path: relPath,
+                            hash: hashFileContent(content),
+                            mtime: stat.mtime.toISOString(),
+                            size: stat.size,
+                        };
+                    }
                 }
             }
         }
@@ -44,23 +54,61 @@ export function scanLocalFiles(localPath, ignorePatterns) {
     return files;
 }
 /**
- * Scan remote vault for document list.
- * Returns a map of doc paths -> FileState.
+ * Scan remote vault for document list using the syncList fast-path.
+ *
+ * When `knownState` is provided (with hashes and optionally a prior listEtag),
+ * the server may respond 304 and `vaultUnchanged` will be true — in that case
+ * `files` is rebuilt from `knownState.remote` without any per-doc network call.
+ *
+ * When `knownState` is omitted a full list is always fetched (backward-compat).
  */
-export async function scanRemoteFiles(client, vaultId, ignorePatterns) {
-    const docs = await client.documents.list(vaultId);
+export async function scanRemoteFiles(client, vaultId, ignorePatterns, knownState) {
+    const sdkKnownState = {
+        hashes: knownState
+            ? Object.fromEntries(Object.entries(knownState.remote).map(([k, v]) => [k, v.hash]))
+            : {},
+        listEtag: knownState?.remoteListEtag,
+    };
+    const sync = await client.documents.syncList(vaultId, sdkKnownState);
+    if (sync.vaultUnchanged) {
+        // Server confirmed nothing changed — rebuild files from persisted state.
+        const files = {};
+        if (knownState) {
+            for (const [docPath, fs_] of Object.entries(knownState.remote)) {
+                if (!shouldIgnore(docPath, ignorePatterns)) {
+                    files[docPath] = fs_;
+                }
+            }
+        }
+        return { files, listEtag: sync.listEtag, vaultUnchanged: true };
+    }
+    // Build files from changes + unchanged paths.
     const files = {};
-    for (const doc of docs) {
-        if (!shouldIgnore(doc.path, ignorePatterns)) {
-            files[doc.path] = {
-                path: doc.path,
-                hash: doc.contentHash,
-                mtime: doc.fileModifiedAt,
-                size: doc.sizeBytes,
+    for (const change of sync.changes) {
+        if (!shouldIgnore(change.path, ignorePatterns)) {
+            files[change.path] = {
+                path: change.path,
+                hash: change.contentHash,
+                mtime: change.fileModifiedAt,
+                // sizeBytes is not provided by syncList change objects; use 0 as a
+                // fallback — size is only used for progress-bar estimation in the diff.
+                size: 0,
             };
         }
     }
-    return files;
+    for (const unchangedPath of sync.unchanged) {
+        if (!shouldIgnore(unchangedPath, ignorePatterns)) {
+            // Reuse the persisted FileState so size is preserved for progress reporting.
+            const stored = knownState?.remote?.[unchangedPath];
+            files[unchangedPath] = stored ?? {
+                path: unchangedPath,
+                hash: sdkKnownState.hashes[unchangedPath] ?? '',
+                mtime: '',
+                size: 0,
+            };
+        }
+    }
+    return { files, listEtag: sync.listEtag, vaultUnchanged: false };
 }
 /**
  * Write a file atomically using a temp file + rename.
@@ -95,7 +143,7 @@ export function resolveConcurrency(value) {
  * Handles result initialization, state loading, progress callbacks,
  * quota error handling, state saving, and lastSync update.
  */
-async function executeSyncOperation(config, diff, handlers, onProgress, concurrency = DEFAULT_TRANSFER_CONCURRENCY) {
+async function executeSyncOperation(config, diff, handlers, onProgress, concurrency = DEFAULT_TRANSFER_CONCURRENCY, onThrottle) {
     const result = {
         filesUploaded: 0,
         filesDownloaded: 0,
@@ -122,7 +170,7 @@ async function executeSyncOperation(config, diff, handlers, onProgress, concurre
             totalBytes: diff.totalBytes,
         });
         try {
-            const content = await handlers.transferFile(entry, config);
+            const content = await handlers.transferFile(entry, config, onThrottle);
             result[handlers.transferCounterKey]++;
             result.bytesTransferred += entry.sizeBytes;
             // Update state
@@ -140,6 +188,11 @@ async function executeSyncOperation(config, diff, handlers, onProgress, concurre
             if (isQuotaError(message)) {
                 stopSubmitting = true;
             }
+            // 429 errors that reach here have already exhausted SDK-level retries.
+            // Stop submitting new work to avoid hammering a still-throttled API.
+            if (isThrottleError(err)) {
+                stopSubmitting = true;
+            }
         }
     }
     // Bounded async pool. Workers race for entries off the queue tail; once
@@ -190,13 +243,13 @@ async function executeSyncOperation(config, diff, handlers, onProgress, concurre
 /**
  * Execute a pull operation: download remote changes to local.
  */
-export async function executePull(client, config, diff, onProgress, concurrency) {
+export async function executePull(client, config, diff, onProgress, concurrency, onThrottle) {
     return executeSyncOperation(config, diff, {
         transfers: diff.downloads,
         deletes: diff.deletes,
         transferCounterKey: 'filesDownloaded',
-        async transferFile(entry, cfg) {
-            const { content } = await retryWithBackoff(() => client.documents.get(cfg.vaultId, entry.path));
+        async transferFile(entry, cfg, throttleCallback) {
+            const { content } = await retryWithBackoff(() => client.documents.get(cfg.vaultId, entry.path), throttleCallback ? () => throttleCallback(entry.path) : undefined);
             const localFile = path.join(cfg.localPath, entry.path);
             const localDir = path.dirname(localFile);
             if (!fs.existsSync(localDir)) {
@@ -211,31 +264,40 @@ export async function executePull(client, config, diff, onProgress, concurrency)
                 fs.unlinkSync(localFile);
             }
         },
-    }, onProgress, concurrency);
+    }, onProgress, concurrency, onThrottle);
 }
 /**
  * Execute a push operation: upload local changes to remote.
  */
-export async function executePush(client, config, diff, onProgress, concurrency) {
+export async function executePush(client, config, diff, onProgress, concurrency, onThrottle) {
     return executeSyncOperation(config, diff, {
         transfers: diff.uploads,
         deletes: diff.deletes,
         transferCounterKey: 'filesUploaded',
-        async transferFile(entry, cfg) {
+        async transferFile(entry, cfg, throttleCallback) {
             const localFile = path.join(cfg.localPath, entry.path);
             const content = fs.readFileSync(localFile, 'utf-8');
-            await retryWithBackoff(() => client.documents.put(cfg.vaultId, entry.path, content));
+            await retryWithBackoff(() => client.documents.put(cfg.vaultId, entry.path, content), throttleCallback ? () => throttleCallback(entry.path) : undefined);
             return content;
         },
         async deleteFile(entry, cfg) {
             await retryWithBackoff(() => client.documents.delete(cfg.vaultId, entry.path));
         },
-    }, onProgress, concurrency);
+    }, onProgress, concurrency, onThrottle);
 }
 /**
- * Retry a function with exponential backoff (max 3 retries).
+ * Retry a function with exponential backoff (max 3 retries) for transient
+ * network errors. Throttle (429) and quota/permission errors are NOT retried
+ * here — the SDK already retries 429s transparently (ky retry config), and
+ * quota/permission errors are not recoverable by retrying.
+ *
+ * @param onThrottle - Optional callback to invoke when a 429 is observed.
+ *   The SDK will retry automatically; this is called so the CLI can update
+ *   its spinner text to "Rate limited — waiting and retrying…".
+ *   The parameter value is the file path being transferred.
  */
-async function retryWithBackoff(fn, maxRetries = 3) {
+async function retryWithBackoff(fn, onThrottle) {
+    const maxRetries = 3;
     let lastError;
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
         try {
@@ -244,7 +306,14 @@ async function retryWithBackoff(fn, maxRetries = 3) {
         catch (err) {
             lastError = err;
             const message = err instanceof Error ? err.message : String(err);
-            // Don't retry on non-transient errors
+            // Throttle errors: the SDK already exhausted its own retry budget with
+            // proper Retry-After backoff. Don't layer another retry loop on top —
+            // that would ignore the server's backoff signal and hammer the API.
+            if (isThrottleError(err)) {
+                onThrottle?.('');
+                throw err;
+            }
+            // Don't retry on other non-transient errors
             if (isQuotaError(message) || isPermissionError(message)) {
                 throw err;
             }
@@ -256,6 +325,28 @@ async function retryWithBackoff(fn, maxRetries = 3) {
     }
     throw lastError;
 }
+/**
+ * Returns true when an error represents an HTTP 429 (Too Many Requests / rate
+ * limited) response. The SDK retries 429s transparently; a 429 reaching here
+ * means all retry attempts were exhausted.
+ *
+ * Prefers the structured status code the SDK attaches (RateLimitError sets
+ * `statusCode = 429`) and only falls back to a narrow message match. The
+ * message fallback is intentionally strict — it does NOT match "rate limit" or
+ * "throttle" loosely, since those words appear in unrelated errors (e.g. an
+ * authorization message mentioning a rate-limited account) and a false positive
+ * would suppress a real error.
+ */
+export function isThrottleError(err) {
+    if (err && typeof err === 'object') {
+        const code = err.statusCode
+            ?? err.status;
+        if (code === 429)
+            return true;
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    return /\b429\b|too many requests/i.test(message);
+}
 function isQuotaError(message) {
     return /quota|storage limit|limit exceeded/i.test(message);
 }

package/dist/sync/ignore.js

@@ -50,6 +50,7 @@ export function resolveIgnorePatterns(configIgnore, localPath) {
  * The docPath should be a relative path using forward slashes.
  */
 export function shouldIgnore(docPath, patterns) {
+    const basename = path.posix.basename(docPath);
     for (const pattern of patterns) {
         // Directory patterns (ending with /)
         if (pattern.endsWith('/')) {
@@ -63,7 +64,6 @@ export function shouldIgnore(docPath, patterns) {
             return true;
         }
         // Also check basename for file-level patterns (e.g., ".DS_Store" matches "sub/.DS_Store")
-        const basename = path.posix.basename(docPath);
         if (minimatch(basename, pattern, { dot: true })) {
             return true;
         }

package/dist/sync/remote-poller.js

@@ -8,6 +8,7 @@ import { shouldIgnore } from './ignore.js';
 import { loadSyncState, saveSyncState, hashFileContent, buildRemoteFileState } from './state.js';
 import { updateLastSync } from './config.js';
 import { resolveConflict, detectConflict, createConflictFile, formatConflictLog } from './conflict.js';
+import { isThrottleError } from './engine.js';
 /**
  * Creates and starts a remote poller for a sync configuration.
  * Returns a stop function.
@@ -22,62 +23,91 @@ export function createRemotePoller(client, config, options) {
             return; // Skip if previous poll still in progress
         polling = true;
         try {
-            const remoteDocs = await client.documents.list(config.vaultId);
             const state = loadSyncState(config.id);
             let changes = 0;
-            for (const doc of remoteDocs) {
-                if (shouldIgnore(doc.path, ignorePatterns))
-                    continue;
-                const lastRemote = state.remote[doc.path];
-                // Detect remote changes by comparing mtime
-                const remoteChanged = !lastRemote || doc.fileModifiedAt !== lastRemote.mtime;
-                if (!remoteChanged)
-                    continue;
-                // Fetch the full content
-                const { content } = await client.documents.get(config.vaultId, doc.path);
-                const remoteHash = hashFileContent(content);
-                // Skip if hash hasn't actually changed
-                if (lastRemote && remoteHash === lastRemote.hash) {
-                    // Update mtime in state but skip file operations
-                    state.remote[doc.path] = buildRemoteFileState(doc.path, content, doc.fileModifiedAt);
+            let stateMutated = false;
+            // Build the known state from persisted remote hashes + stored list ETag.
+            const known = {
+                hashes: Object.fromEntries(Object.entries(state.remote).map(([k, v]) => [k, v.hash])),
+                listEtag: state.remoteListEtag,
+            };
+            const sync = await client.documents.syncList(config.vaultId, known);
+            // Steady-state: server confirmed nothing changed — skip all per-doc work.
+            if (sync.vaultUnchanged)
+                return;
+            // Persist the new list ETag so the next poll can 304.
+            state.remoteListEtag = sync.listEtag;
+            stateMutated = true;
+            // Process added/changed documents.
+            for (const change of sync.changes) {
+                if (shouldIgnore(change.path, ignorePatterns))
                     continue;
+                const lastRemote = state.remote[change.path];
+                let content;
+                let remoteHash;
+                if (lastRemote) {
+                    // Conditional GET — server can still 304 us if our hash is current
+                    // (rare: syncList classified this as 'changed' but the GET hash matches
+                    // our last-known hash — possible race between list and get).
+                    const result = await client.documents.get(config.vaultId, change.path, {
+                        ifNoneMatch: `"${lastRemote.hash}"`,
+                    });
+                    if (result.notModified) {
+                        // Server confirmed our copy is current despite differing list hash.
+                        // Update mtime only; no file write needed.
+                        if (lastRemote.mtime !== change.fileModifiedAt) {
+                            state.remote[change.path] = { ...lastRemote, mtime: change.fileModifiedAt };
+                            stateMutated = true;
+                        }
+                        continue;
+                    }
+                    content = result.content;
+                    remoteHash = hashFileContent(content);
+                }
+                else {
+                    // First-time entry: unconditional GET.
+                    const fetched = await client.documents.get(config.vaultId, change.path);
+                    content = fetched.content;
+                    remoteHash = hashFileContent(content);
                 }
-                const localFile = path.join(config.localPath, doc.path);
+                const localFile = path.join(config.localPath, change.path);
                 const localExists = fs.existsSync(localFile);
                 if (localExists) {
                     const localContent = fs.readFileSync(localFile, 'utf-8');
                     const localHash = hashFileContent(localContent);
                     if (localHash === remoteHash) {
                         // Content is already the same — just update state
-                        state.local[doc.path] = { path: doc.path, hash: localHash, mtime: new Date().toISOString(), size: Buffer.byteLength(localContent) };
-                        state.remote[doc.path] = buildRemoteFileState(doc.path, content, doc.fileModifiedAt);
+                        state.local[change.path] = { path: change.path, hash: localHash, mtime: new Date().toISOString(), size: Buffer.byteLength(localContent) };
+                        state.remote[change.path] = buildRemoteFileState(change.path, content, change.fileModifiedAt);
+                        stateMutated = true;
                         continue;
                     }
                     // Check for conflict
-                    const lastLocal = state.local[doc.path];
-                    const localState = { path: doc.path, hash: localHash, mtime: fs.statSync(localFile).mtime.toISOString(), size: Buffer.byteLength(localContent) };
-                    const remoteState = { path: doc.path, hash: remoteHash, mtime: doc.fileModifiedAt, size: Buffer.byteLength(content) };
+                    const lastLocal = state.local[change.path];
+                    const localState = { path: change.path, hash: localHash, mtime: fs.statSync(localFile).mtime.toISOString(), size: Buffer.byteLength(localContent) };
+                    const remoteState = { path: change.path, hash: remoteHash, mtime: change.fileModifiedAt, size: Buffer.byteLength(content) };
                     if (detectConflict(localState, remoteState, lastLocal, lastRemote)) {
                         const resolution = resolveConflict(config.onConflict, localState, remoteState);
                         let conflictFile = null;
                         if (resolution === 'remote') {
-                            conflictFile = createConflictFile(config.localPath, doc.path, localContent, 'local');
-                            onLocalWrite?.(doc.path);
+                            conflictFile = createConflictFile(config.localPath, change.path, localContent, 'local');
+                            onLocalWrite?.(change.path);
                             const tmpConflict = localFile + '.tmp';
                             fs.writeFileSync(tmpConflict, content, 'utf-8');
                             fs.renameSync(tmpConflict, localFile);
-                            log(`Conflict: ${doc.path} — used remote, saved local as ${conflictFile}`);
+                            log(`Conflict: ${change.path} — used remote, saved local as ${conflictFile}`);
                         }
                         else {
-                            conflictFile = createConflictFile(config.localPath, doc.path, content, 'remote');
-                            await client.documents.put(config.vaultId, doc.path, localContent);
-                            log(`Conflict: ${doc.path} — used local, saved remote as ${conflictFile}`);
+                            conflictFile = createConflictFile(config.localPath, change.path, content, 'remote');
+                            await client.documents.put(config.vaultId, change.path, localContent);
+                            log(`Conflict: ${change.path} — used local, saved remote as ${conflictFile}`);
                         }
-                        onConflictLog?.(formatConflictLog(doc.path, resolution, conflictFile));
-                        state.local[doc.path] = resolution === 'remote' ? remoteState : localState;
-                        state.remote[doc.path] = resolution === 'remote'
-                            ? buildRemoteFileState(doc.path, content, doc.fileModifiedAt)
-                            : buildRemoteFileState(doc.path, localContent, new Date().toISOString());
+                        onConflictLog?.(formatConflictLog(change.path, resolution, conflictFile));
+                        state.local[change.path] = resolution === 'remote' ? remoteState : localState;
+                        state.remote[change.path] = resolution === 'remote'
+                            ? buildRemoteFileState(change.path, content, change.fileModifiedAt)
+                            : buildRemoteFileState(change.path, localContent, new Date().toISOString());
+                        stateMutated = true;
                         changes++;
                         continue;
                     }
@@ -87,44 +117,55 @@ export function createRemotePoller(client, config, options) {
                 if (!fs.existsSync(dir)) {
                     fs.mkdirSync(dir, { recursive: true });
                 }
-                onLocalWrite?.(doc.path);
+                onLocalWrite?.(change.path);
                 const tmpFile = localFile + '.tmp';
                 fs.writeFileSync(tmpFile, content, 'utf-8');
                 fs.renameSync(tmpFile, localFile);
-                log(`Pulled: ${doc.path}`);
+                log(`Pulled: ${change.path}`);
                 changes++;
-                state.local[doc.path] = {
-                    path: doc.path,
+                state.local[change.path] = {
+                    path: change.path,
                     hash: remoteHash,
                     mtime: new Date().toISOString(),
                     size: Buffer.byteLength(content),
                 };
-                state.remote[doc.path] = buildRemoteFileState(doc.path, content, doc.fileModifiedAt);
+                state.remote[change.path] = buildRemoteFileState(change.path, content, change.fileModifiedAt);
+                stateMutated = true;
             }
-            // Check for remote deletions
-            for (const docPath of Object.keys(state.remote)) {
-                if (shouldIgnore(docPath, ignorePatterns))
+            // Process remote deletions.
+            for (const removedPath of sync.removed) {
+                if (shouldIgnore(removedPath, ignorePatterns))
                     continue;
-                const stillExists = remoteDocs.some(d => d.path === docPath);
-                if (!stillExists) {
-                    const localFile = path.join(config.localPath, docPath);
-                    if (fs.existsSync(localFile)) {
-                        fs.unlinkSync(localFile);
-                        log(`Deleted local: ${docPath} (removed from remote)`);
-                        changes++;
-                    }
-                    delete state.local[docPath];
-                    delete state.remote[docPath];
+                const localFile = path.join(config.localPath, removedPath);
+                if (fs.existsSync(localFile)) {
+                    fs.unlinkSync(localFile);
+                    log(`Deleted local: ${removedPath} (removed from remote)`);
+                    changes++;
                 }
+                delete state.local[removedPath];
+                delete state.remote[removedPath];
+                stateMutated = true;
             }
-            if (changes > 0) {
+            if (changes > 0 || stateMutated) {
                 saveSyncState(state);
-                updateLastSync(config.id);
-                log(`Poll complete: ${changes} change(s)`);
+                if (changes > 0) {
+                    updateLastSync(config.id);
+                    log(`Poll complete: ${changes} change(s)`);
+                }
             }
         }
         catch (err) {
-            onError?.(err instanceof Error ? err : new Error(String(err)));
+            if (isThrottleError(err)) {
+                // The SDK already retried the request with Retry-After backoff and
+                // exhausted its retry budget. Log a warning rather than invoking
+                // onError so the daemon loop does NOT immediately re-poll on top of
+                // the backoff that the SDK already applied.  The next scheduled poll
+                // (after intervalMs) will pick up the changes.
+                log('Rate limited by server — will retry on next scheduled poll');
+            }
+            else {
+                onError?.(err instanceof Error ? err : new Error(String(err)));
+            }
         }
         finally {
             polling = false;

package/dist/sync/state.js

@@ -46,7 +46,7 @@ export function saveSyncState(state) {
         fs.mkdirSync(STATE_DIR, { recursive: true, mode: 0o700 });
     }
     state.updatedAt = new Date().toISOString();
-    fs.writeFileSync(stateFilePath(state.syncId), JSON.stringify(state, null, 2) + '\n', { mode: 0o600 });
+    fs.writeFileSync(stateFilePath(state.syncId), JSON.stringify(state) + '\n', { mode: 0o600 });
 }
 /**
  * Delete sync state for a given sync configuration.

package/dist/sync/types.d.ts

@@ -51,6 +51,8 @@ export interface SyncState {
     local: Record<string, FileState>;
     /** Map of document path -> file state for remote files */
     remote: Record<string, FileState>;
+    /** ETag from the most recent successful list response (for conditional polling). */
+    remoteListEtag?: string;
     /** ISO 8601 timestamp when state was last updated */
     updatedAt: string;
 }

package/dist/sync/watcher.js

@@ -101,18 +101,25 @@ export function createWatcher(client, config, options) {
             // Check remote for conflicts in bidirectional mode
             if (config.mode === 'sync' && lastRemote) {
                 try {
-                    const remote = await client.documents.get(config.vaultId, docPath);
-                    const remoteHash = hashFileContent(remote.content);
-                    if (remoteHash !== lastRemote.hash) {
-                        const result = await handleConflict({
-                            absPath, docPath, localContent: content, localHash,
-                            lastLocal, lastRemote,
-                            remoteContent: remote.content, remoteHash,
-                            remoteUpdatedAt: remote.document.updatedAt, state,
-                        });
-                        if (result !== 'skip')
-                            return;
+                    const result = await client.documents.get(config.vaultId, docPath, {
+                        ifNoneMatch: `"${lastRemote.hash}"`,
+                    });
+                    if (!result.notModified) {
+                        // Server returned the body — check if hash differs from our last-known state.
+                        const remoteHash = hashFileContent(result.content);
+                        if (remoteHash !== lastRemote.hash) {
+                            const conflictResult = await handleConflict({
+                                absPath, docPath, localContent: content, localHash,
+                                lastLocal, lastRemote,
+                                remoteContent: result.content, remoteHash,
+                                remoteUpdatedAt: result.document.updatedAt, state,
+                            });
+                            if (conflictResult !== 'skip')
+                                return;
+                        }
+                        // 200 + matching hash: rare list/cache mismatch — fall through to push.
                     }
+                    // 304: remote unchanged since last sync — no conflict possible. Fall through to push.
                 }
                 catch {
                     // Remote check failed — proceed with push

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifestreamdynamics/vault-cli",
-  "version": "1.3.11",
+  "version": "1.4.4",
   "description": "Command-line interface for Lifestream Vault",
   "engines": {
     "node": ">=22"
@@ -44,7 +44,7 @@
     "prepublishOnly": "npm run build && npm test"
   },
   "dependencies": {
-    "@lifestreamdynamics/vault-sdk": "^2.1.0",
+    "@lifestreamdynamics/vault-sdk": "^2.2.0",
     "chalk": "^5.4.0",
     "chokidar": "^4.0.3",
     "commander": "^13.0.0",