Introduction¶
In DSH (DeepSeek Harness)’s Maestro toolchain, the local file system often stores memory and session data. When this state needs to be synchronized across multiple machines, using tools such as rsync directly can carry risks of overwriting hidden files, lacking a preview mechanism, or breaking existing structures. dsh-maestro-sync aims to provide a safe, previewable, and backup-backed synchronization solution.
What It Is¶
This is a plugin maintained by ddtcorex under the MIT license. Its core purpose is to merge memory and sessions across machines, with support for publish mode.
Installation and Enablement¶
To install this plugin, run the following command:
dsh plugin add @ddtcorex/dsh-maestro-sync
Core Features and Usage¶
Safe Synchronization: Preview First, Apply Later¶
This plugin does not provide a “direct overwrite” sync mode. All sync operations must go through a preview stage and can be applied only after confirmation.
1. Preview sync
Use the --dry-run parameter for a read-only preview. No write operations are performed. The system calculates differences and outputs a SyncPreview object, which includes a preview ID, version number, and expiration time.
node lib/cli.js --pull --dry-run
2. Apply preview
The apply operation must satisfy all three conditions: --apply, --preview-id (the ID output in the previous step), and --confirm (operator confirmation).
node lib/cli.js --pull --apply --preview-id <id> --confirm
3. Stale-guard mechanism
When applying, the state of both machines is rechecked. If any file has changed since the preview was generated, synchronization is rejected, the status is STALE_PREVIEW, and no writes are performed.
R2 Offline Backup¶
The plugin supports backing up eligible memory and session logs to S3-compatible object storage (such as Cloudflare R2).
Configuration
Configure the domains.sync.r2 field in ~/.dsh/maestro/settings.json, including accountId, bucket, prefix, and region.
Credentials
Backup credentials do not support plaintext storage in settings. Only the following methods are supported:
* Environment variables: R2_ACCESS_KEY_ID / R2_SECRET_ACCESS_KEY
* Private sidecar file: ~/.dsh/dsh-maestro-sync/backup-secrets.json (permissions must be 0600)
Backup behavior
* Preview backup: Read-only; compares local hashes with the manifest in storage.
* Apply backup: Uploads missing Blobs, generates an immutable manifest, and advances the HEAD pointer.
* GC policy: Retains the latest 30 daily manifests and 12 monthly manifests.
Recovery and Fault Tolerance¶
Fail-closed mechanism
If a transfer or publish failure occurs during synchronization, the system does not fall back to destructive rsync overwrite mode. The returned status is ok:true only when all files are published successfully.
Data recovery
A timestamped backup file is generated next to each overwritten file (format: .bak.<timestamp>.<random>). If rollback is needed, the backup file can be restored directly:
cp <path>.bak.* <path>
Scope and Limitations¶
This plugin applies only to specific files, including dsh-maestro-memory/**/*.md, dsh-maestro-memory/SUGGESTIONS.jsonl, and files under the sessions directory.
The following items are excluded during synchronization and backup; they are not read, hashed, or copied:
* Settings files, tunnel configuration, secret material
* Configuration files, Supervisor state, storage
* Tools, skills, logs, caches
* All .bak.* backup files
Development¶
To verify or build the plugin locally, use the following command:
pnpm --filter @ddtcorex/dsh-maestro-sync verify