@lifestreamdynamics/vault-cli 1.4.1 → 1.4.6

package/README.md

@@ -158,7 +158,7 @@ lsvault auth login --api-key lsv_k_your_api_key_here
 
 **Create an API Key:**
 ```bash
-lsvault keys create --name "CI/CD Pipeline" --scopes vaults:read,documents:read
+lsvault keys create "CI/CD Pipeline" --scopes read,write
 ```
 
 ### Email/Password Authentication
@@ -313,46 +313,52 @@ lsvault search "meeting" --tags work,urgent --limit 10
 | Command | Description |
 |---------|-------------|
 | `lsvault teams list` | List all teams |
-| `lsvault teams create` | Create a new team |
+| `lsvault teams create <name>` | Create a new team |
 | `lsvault teams get <teamId>` | Get team details |
 | `lsvault teams update <teamId>` | Update team settings |
 | `lsvault teams delete <teamId>` | Delete a team |
-| `lsvault teams members <teamId>` | List team members |
-| `lsvault teams invite <teamId>` | Invite user to team |
-| `lsvault teams remove <teamId> <userId>` | Remove member from team |
+| `lsvault teams members list <teamId>` | List team members |
+| `lsvault teams members update <teamId> <userId> --role <role>` | Update a member's role (admin/editor/viewer) |
+| `lsvault teams members remove <teamId> <userId>` | Remove member from team |
+| `lsvault teams invitations create <teamId> <email> --role <role>` | Invite a user to the team |
+| `lsvault teams invitations list <teamId>` | List pending invitations |
+| `lsvault teams invitations revoke <teamId> <invitationId>` | Revoke an invitation |
+| `lsvault teams vaults list <teamId>` | List shared team vaults |
+| `lsvault teams vaults create <teamId> <name>` | Create a shared team vault |
 
 **Example:**
 ```bash
 # Create a team
-lsvault teams create --name "Engineering" --description "Dev team workspace"
+lsvault teams create "Engineering" --description "Dev team workspace"
 
 # Invite a member
-lsvault teams invite team_abc123 --email engineer@example.com --role member
+lsvault teams invitations create team_abc123 engineer@example.com --role editor
 
 # List members
-lsvault teams members team_abc123
+lsvault teams members list team_abc123
 ```
 
 ### Sharing & Publishing
 
 | Command | Description |
 |---------|-------------|
-| `lsvault shares list` | List all share links |
+| `lsvault shares list <vaultId> <path>` | List share links for a document |
 | `lsvault shares create <vaultId> <path>` | Create a share link for a document |
-| `lsvault shares revoke <shareId>` | Revoke a share link |
-| `lsvault publish list` | List published documents |
-| `lsvault publish create <vaultId> <path>` | Publish a document publicly |
-| `lsvault publish unpublish <publishId>` | Unpublish a document |
+| `lsvault shares revoke <vaultId> <shareId>` | Revoke a share link |
+| `lsvault publish list <vaultId>` | List published documents in a vault |
+| `lsvault publish create <vaultId> <path> --slug <slug>` | Publish a document publicly |
+| `lsvault publish delete <vaultId> <path>` | Unpublish a document |
 
 **Example:**
 ```bash
-# Create a password-protected share link
-lsvault shares create vault_abc123 /reports/Q1.md \
-  --password secret123 \
-  --expires-in 7d
+# Create a password-protected share link (prompts for the password)
+lsvault shares create vault_abc123 reports/Q1.md \
+  --permission view \
+  --protect-with-password \
+  --expires 2026-12-31
 
 # Publish a document
-lsvault publish create vault_abc123 /blog/post.md --slug my-first-post
+lsvault publish create vault_abc123 blog/post.md --slug my-first-post
 ```
 
 ### Publish Vault Commands
@@ -386,26 +392,25 @@ lsvault publish-vault unpublish vault_abc123
 | Command | Description |
 |---------|-------------|
 | `lsvault hooks list <vaultId>` | List vault hooks |
-| `lsvault hooks create <vaultId>` | Create a new hook |
-| `lsvault hooks update <hookId>` | Update hook configuration |
-| `lsvault hooks delete <hookId>` | Delete a hook |
-| `lsvault webhooks list` | List all webhooks |
-| `lsvault webhooks create` | Create a new webhook |
-| `lsvault webhooks update <webhookId>` | Update webhook configuration |
-| `lsvault webhooks delete <webhookId>` | Delete a webhook |
+| `lsvault hooks create <vaultId> <name>` | Create a new hook |
+| `lsvault hooks delete <vaultId> <hookId>` | Delete a hook |
+| `lsvault hooks executions <vaultId> <hookId>` | View hook execution history |
+| `lsvault webhooks list <vaultId>` | List vault webhooks |
+| `lsvault webhooks create <vaultId> <url>` | Create a new webhook |
+| `lsvault webhooks update <vaultId> <webhookId>` | Update webhook configuration |
+| `lsvault webhooks delete <vaultId> <webhookId>` | Delete a webhook |
 
 **Example:**
 ```bash
-# Create an auto-tag hook
-lsvault hooks create vault_abc123 \
-  --type auto-tag \
-  --config '{"patterns":{"meeting":"#meeting"}}'
+# Create a hook that runs an AI prompt on document creation
+lsvault hooks create vault_abc123 "Auto-tag" \
+  --trigger document.created \
+  --action ai_prompt \
+  --config '{"prompt":"Suggest tags"}'
 
 # Create a webhook for document updates
-lsvault webhooks create \
-  --url https://api.example.com/webhook \
-  --events document.created,document.updated \
-  --secret webhook_secret_key
+lsvault webhooks create vault_abc123 https://api.example.com/webhook \
+  --events document.created,document.updated
 ```
 
 ### Calendar
@@ -414,10 +419,11 @@ lsvault webhooks create \
 |---------|-------------|
 | `lsvault calendar view <vaultId>` | Browse calendar views and activity heatmap |
 | `lsvault calendar due <vaultId>` | List documents by due date |
+| `lsvault calendar set-due <vaultId> <path> --date <date>` | Set or clear a document due date (pass `--date clear` to clear) |
 | `lsvault calendar events <vaultId>` | List calendar events |
-| `lsvault calendar create-event <vaultId>` | Create a calendar event |
-| `lsvault calendar update-event <vaultId> <eventId>` | Update a calendar event |
-| `lsvault calendar delete-event <vaultId> <eventId>` | Delete a calendar event |
+| `lsvault calendar event create <vaultId> <title>` | Create a calendar event |
+| `lsvault calendar event update <vaultId> <eventId>` | Update a calendar event |
+| `lsvault calendar event delete <vaultId> <eventId>` | Delete a calendar event |
 
 ### Booking Commands
 
@@ -638,13 +644,13 @@ Manage multiple configurations with profiles:
 # List profiles
 lsvault config profiles
 
-# Create a profile
-lsvault config create-profile production --api-url https://vault.lifestreamdynamics.com
+# Create a profile by setting a value in it (profiles are created on first use)
+lsvault config set apiUrl https://vault.lifestreamdynamics.com --profile production
 
 # Switch profiles
 lsvault config use production
 
-# Set config values
+# Set config values (in the active profile)
 lsvault config set apiUrl https://vault.lifestreamdynamics.com
 
 # Get config values
@@ -759,12 +765,13 @@ lsvault sync watch sync_xyz789
 lsvault search "quarterly report" --vault vault_abc123 -o json
 
 # Create a share link for the found document
-lsvault shares create vault_abc123 /reports/Q4-2025.md \
-  --password secure123 \
-  --expires-in 30d
+lsvault shares create vault_abc123 reports/Q4-2025.md \
+  --permission view \
+  --protect-with-password \
+  --expires 2026-01-31
 
 # Publish a document publicly
-lsvault publish create vault_abc123 /blog/announcement.md \
+lsvault publish create vault_abc123 blog/announcement.md \
   --slug new-features-2026
 ```
 
@@ -772,30 +779,27 @@ lsvault publish create vault_abc123 /blog/announcement.md \
 
 ```bash
 # Create a team
-lsvault teams create --name "Product Team" --description "Product docs"
+lsvault teams create "Product Team" --description "Product docs"
 
 # Create a vault
 lsvault vaults create "Product Docs" --description "Product documentation"
 
 # Invite team members
-lsvault teams invite team_abc123 --email pm@example.com --role admin
-lsvault teams invite team_abc123 --email dev@example.com --role member
+lsvault teams invitations create team_abc123 pm@example.com --role admin
+lsvault teams invitations create team_abc123 dev@example.com --role editor
 
-# Configure webhook for team updates
-lsvault webhooks create \
-  --url https://slack.example.com/webhook \
-  --events document.created,document.updated \
-  --filter '{"vaultId":"vault_xyz789"}'
+# Configure a webhook for vault updates
+lsvault webhooks create vault_xyz789 https://slack.example.com/webhook \
+  --events document.created,document.updated
 ```
 
 ### Automation with API Keys
 
 ```bash
 # Create a read-only API key for monitoring
-lsvault keys create \
-  --name "Monitoring Script" \
-  --scopes vaults:read,documents:read \
-  --expires-in 90d
+lsvault keys create "Monitoring Script" \
+  --scopes read \
+  --expires 2026-12-31
 
 # Use API key in scripts
 export LSVAULT_API_KEY=lsv_k_generated_key

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

@@ -9,7 +9,7 @@ import { formatUptime } from '../utils/format.js';
 import { loadSyncConfigs, createSyncConfig, deleteSyncConfig, getSyncConfig, } from '../sync/config.js';
 import { deleteSyncState, loadSyncState, saveSyncState, hashFileContent, buildRemoteFileState } from '../sync/state.js';
 import { resolveIgnorePatterns } from '../sync/ignore.js';
-import { scanLocalFiles, scanRemoteFiles, executePull, executePush, computePullDiff, computePushDiff, resolveConcurrency, } from '../sync/engine.js';
+import { scanLocalFiles, scanRemoteFiles, executePull, executePush, computePullDiff, computePushDiff, resolveConcurrency, sweepOrphanedTempFiles, } from '../sync/engine.js';
 import { formatDiff } from '../sync/diff.js';
 import { createWatcher } from '../sync/watcher.js';
 import { createRemotePoller } from '../sync/remote-poller.js';
@@ -168,17 +168,30 @@ Sync modes:
             const client = await getClientAsync();
             const ignorePatterns = resolveIgnorePatterns(config.ignore, config.localPath);
             const lastState = loadSyncState(config.id);
+            // Clean up any orphaned temp files left by a prior interrupted pull.
+            const swept = sweepOrphanedTempFiles(config.localPath);
+            if (swept > 0) {
+                out.debug(`Removed ${swept} orphaned temp file(s) from ${config.localPath}`);
+            }
             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 +231,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 +274,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 +331,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 +373,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/atomic-write.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Write `content` to `targetPath` atomically.
+ *
+ * A uniquely named temp file is created alongside the target.  On success it
+ * is renamed to the target (atomic on POSIX).  If the write or rename throws,
+ * the temp file is best-effort deleted before the original error is re-thrown,
+ * guaranteeing no orphaned `.tmp.<hash>` files are left behind.
+ */
+export declare function atomicWriteFileSync(targetPath: string, content: string, encoding?: BufferEncoding): void;
+/**
+ * Recursively walk `rootDir` and delete orphaned temp files.
+ *
+ * A temp file is considered orphaned when its canonical counterpart — the
+ * path with the `.tmp[.<hash>]` suffix stripped — already exists on disk.
+ * This guard ensures only leftover cruft is removed, never unique content.
+ *
+ * Dirs named `.git`, `node_modules`, or starting with `.` (hidden dirs) and
+ * the `.lsvault` dir are skipped, matching the sync engine's own exclusions.
+ *
+ * Any individual fs error (unreadable dir, permission denied, etc.) is caught
+ * and skipped so a single bad entry cannot abort the sweep.
+ *
+ * @returns the number of orphaned temp files deleted.
+ */
+export declare function sweepOrphanedTempFiles(rootDir: string): number;

package/dist/sync/atomic-write.js

@@ -0,0 +1,98 @@
+/**
+ * Atomic file-write helpers shared by the sync engine and remote poller.
+ *
+ * All writes use a temp-file + rename strategy so interrupted writes never
+ * leave a partial file at the target path.  On any error the temp file is
+ * cleaned up before the error is re-thrown.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomBytes } from 'node:crypto';
+/**
+ * Write `content` to `targetPath` atomically.
+ *
+ * A uniquely named temp file is created alongside the target.  On success it
+ * is renamed to the target (atomic on POSIX).  If the write or rename throws,
+ * the temp file is best-effort deleted before the original error is re-thrown,
+ * guaranteeing no orphaned `.tmp.<hash>` files are left behind.
+ */
+export function atomicWriteFileSync(targetPath, content, encoding = 'utf-8') {
+    const tmpFile = targetPath + '.tmp.' + randomBytes(4).toString('hex');
+    try {
+        fs.writeFileSync(tmpFile, content, encoding);
+        fs.renameSync(tmpFile, targetPath);
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(tmpFile);
+        }
+        catch {
+            // Ignore — the file may not exist if writeFileSync was what threw.
+        }
+        throw err;
+    }
+}
+/**
+ * Regex that matches both forms of orphaned temp-file suffix:
+ *   - `.tmp`           (static suffix used by the legacy inline write in remote-poller)
+ *   - `.tmp.<8hex>`    (randomised suffix used by atomicWriteFileSync)
+ */
+const ORPHAN_TEMP_RE = /\.tmp(\.[0-9a-f]{8})?$/;
+/**
+ * Recursively walk `rootDir` and delete orphaned temp files.
+ *
+ * A temp file is considered orphaned when its canonical counterpart — the
+ * path with the `.tmp[.<hash>]` suffix stripped — already exists on disk.
+ * This guard ensures only leftover cruft is removed, never unique content.
+ *
+ * Dirs named `.git`, `node_modules`, or starting with `.` (hidden dirs) and
+ * the `.lsvault` dir are skipped, matching the sync engine's own exclusions.
+ *
+ * Any individual fs error (unreadable dir, permission denied, etc.) is caught
+ * and skipped so a single bad entry cannot abort the sweep.
+ *
+ * @returns the number of orphaned temp files deleted.
+ */
+export function sweepOrphanedTempFiles(rootDir) {
+    let removed = 0;
+    function walk(dir) {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            try {
+                if (entry.isDirectory()) {
+                    // Skip hidden dirs, node_modules, .lsvault
+                    if (entry.name.startsWith('.') ||
+                        entry.name === 'node_modules') {
+                        continue;
+                    }
+                    walk(fullPath);
+                }
+                else if (entry.isFile() && ORPHAN_TEMP_RE.test(entry.name)) {
+                    // Derive the canonical sibling path by stripping the temp suffix.
+                    const canonical = fullPath.replace(ORPHAN_TEMP_RE, '');
+                    if (fs.existsSync(canonical)) {
+                        try {
+                            fs.unlinkSync(fullPath);
+                            removed++;
+                        }
+                        catch {
+                            // Ignore individual unlink failures.
+                        }
+                    }
+                }
+            }
+            catch {
+                // Ignore stat/access errors for individual entries.
+            }
+        }
+    }
+    walk(rootDir);
+    return removed;
+}

package/dist/sync/daemon-worker.js

@@ -10,8 +10,8 @@ import { createRemotePoller } from './remote-poller.js';
 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 { scanLocalFiles, scanRemoteFiles, computePushDiff, computePullDiff, executePush, executePull, sweepOrphanedTempFiles } from './engine.js';
+import { loadSyncState, saveSyncState } from './state.js';
 const managed = [];
 function log(msg) {
     const ts = new Date().toISOString();
@@ -43,6 +43,18 @@ async function start() {
         process.exit(0);
     }
     log(`Found ${configs.length} auto-sync configuration(s)`);
+    // One-time orphan sweep: remove any temp files left by prior interrupted pulls.
+    for (const config of configs) {
+        try {
+            const swept = sweepOrphanedTempFiles(config.localPath);
+            if (swept > 0) {
+                log(`Swept ${swept} orphaned temp file(s) from ${config.localPath}`);
+            }
+        }
+        catch {
+            // Non-fatal — continue startup.
+        }
+    }
     const client = await createClient();
     // Startup reconciliation: catch changes made while daemon was stopped
     for (const config of configs) {
@@ -50,8 +62,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/diff.d.ts

@@ -16,6 +16,12 @@ export interface SyncDiffEntry {
     sizeBytes: number;
     /** Human-readable reason for this change */
     reason: string;
+    /**
+     * SHA-256 hash of the remote file at diff-computation time.
+     * Present on download entries so executePull can issue a conditional GET
+     * (If-None-Match) and skip the write when the local file is already current.
+     */
+    remoteHash?: string;
 }
 export interface SyncDiff {
     /** Files to upload (local -> remote) */

package/dist/sync/diff.js

@@ -19,6 +19,7 @@ export function computePullDiff(localFiles, remoteFiles, lastState) {
                     direction: 'download',
                     sizeBytes: remote.size,
                     reason: 'Deleted locally, exists remotely (pull restores)',
+                    remoteHash: remote.hash,
                 });
             }
             else {
@@ -29,6 +30,7 @@ export function computePullDiff(localFiles, remoteFiles, lastState) {
                     direction: 'download',
                     sizeBytes: remote.size,
                     reason: 'New remote file',
+                    remoteHash: remote.hash,
                 });
             }
         }
@@ -40,6 +42,7 @@ export function computePullDiff(localFiles, remoteFiles, lastState) {
                 direction: 'download',
                 sizeBytes: remote.size,
                 reason: 'Remote file updated',
+                remoteHash: remote.hash,
             });
         }
         else if (!lastRemote && remote.hash !== local.hash) {
@@ -50,6 +53,7 @@ export function computePullDiff(localFiles, remoteFiles, lastState) {
                 direction: 'download',
                 sizeBytes: remote.size,
                 reason: 'Content differs (first sync, pull prefers remote)',
+                remoteHash: remote.hash,
             });
         }
     }

package/dist/sync/engine.d.ts

@@ -1,6 +1,8 @@
 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';
+import { sweepOrphanedTempFiles } from './atomic-write.js';
+export { sweepOrphanedTempFiles };
 export interface SyncProgress {
     phase: 'scanning' | 'computing' | 'transferring' | 'complete';
     current: number;
@@ -23,13 +25,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 +67,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

@@ -3,16 +3,20 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import { randomBytes } from 'node:crypto';
 import { loadSyncState, saveSyncState, hashFileContent, buildRemoteFileState } from './state.js';
 import { updateLastSync } from './config.js';
 import { shouldIgnore } from './ignore.js';
 import { computePullDiff, computePushDiff } from './diff.js';
+import { atomicWriteFileSync, sweepOrphanedTempFiles } from './atomic-write.js';
+export { sweepOrphanedTempFiles };
 /**
  * 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 +32,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,32 +55,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;
-}
-/**
- * Write a file atomically using a temp file + rename.
- * Prevents partial reads if the process is interrupted mid-write.
- */
-function atomicWriteFileSync(targetPath, content, encoding = 'utf-8') {
-    const tmpFile = targetPath + '.tmp.' + randomBytes(4).toString('hex');
-    fs.writeFileSync(tmpFile, content, encoding);
-    fs.renameSync(tmpFile, targetPath);
+    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 };
 }
 /**
  * Default in-flight transfer count. A small number flattens the load1 spike
@@ -95,7 +135,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 +162,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 +180,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,15 +235,33 @@ 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 localFile = path.join(cfg.localPath, entry.path);
             const localDir = path.dirname(localFile);
+            // Only use a conditional GET when (a) we have the remote hash AND (b)
+            // the local file already exists.  For 'create' entries the local file
+            // does not exist yet — the server will always 304 (our remoteHash IS the
+            // server's current hash), which would send the 304 branch into a
+            // readFileSync on a non-existent path (ENOENT).  Guarding on existsSync
+            // also makes the readFileSync in the 304 branch provably safe.
+            const useConditional = entry.remoteHash !== undefined && fs.existsSync(localFile);
+            const result = await retryWithBackoff(() => useConditional
+                ? client.documents.get(cfg.vaultId, entry.path, { ifNoneMatch: `"${entry.remoteHash}"` })
+                : client.documents.get(cfg.vaultId, entry.path), throttleCallback ? () => throttleCallback(entry.path) : undefined);
+            // 304 Not Modified — local already has the right content; skip the write.
+            // Safe: only reached when useConditional === true, which requires the
+            // local file to exist.
+            if ('notModified' in result && result.notModified) {
+                const localContent = fs.readFileSync(localFile, 'utf-8');
+                return localContent;
+            }
+            // 200 response — result has `content` (handle both shapes of the union).
+            const content = result.content;
             if (!fs.existsSync(localDir)) {
                 fs.mkdirSync(localDir, { recursive: true });
             }
@@ -211,31 +274,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 +316,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 +335,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

@@ -12,6 +12,7 @@ export const DEFAULT_IGNORE_PATTERNS = [
     '.hg/',
     'node_modules/',
     '*.tmp',
+    '*.tmp.*',
     '.DS_Store',
     'Thumbs.db',
     '.lsvault/',
@@ -50,6 +51,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 +65,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,8 @@ 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';
+import { atomicWriteFileSync } from './atomic-write.js';
 /**
  * Creates and starts a remote poller for a sync configuration.
  * Returns a stop function.
@@ -91,9 +93,7 @@ export function createRemotePoller(client, config, options) {
                         if (resolution === 'remote') {
                             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);
+                            atomicWriteFileSync(localFile, content, 'utf-8');
                             log(`Conflict: ${change.path} — used remote, saved local as ${conflictFile}`);
                         }
                         else {
@@ -117,9 +117,7 @@ export function createRemotePoller(client, config, options) {
                     fs.mkdirSync(dir, { recursive: true });
                 }
                 onLocalWrite?.(change.path);
-                const tmpFile = localFile + '.tmp';
-                fs.writeFileSync(tmpFile, content, 'utf-8');
-                fs.renameSync(tmpFile, localFile);
+                atomicWriteFileSync(localFile, content, 'utf-8');
                 log(`Pulled: ${change.path}`);
                 changes++;
                 state.local[change.path] = {
@@ -154,7 +152,17 @@ export function createRemotePoller(client, config, options) {
             }
         }
         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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifestreamdynamics/vault-cli",
-  "version": "1.4.1",
+  "version": "1.4.6",
   "description": "Command-line interface for Lifestream Vault",
   "engines": {
     "node": ">=22"