dsh-memory-sync 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project uses
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-11-05
+
+First public release.
+
+### Added
+
+- Three-phase startup sync: local pull/commit/push → peer commit over ssh → local
+  pull again, so both machines end on the same commit.
+- `peer` and `local` modes; `repoPath`, `remote`, `branch`, `peerHost`,
+  `peerUser`, `peerKeyPath`, `peerCommand` and timeouts are configurable.
+- Startup grace window (`startupGraceSec`, default 300 s) so hot reloads do not
+  trigger a sync.
+- Retry once after `retryDelaySec` (60 s), then silent self-heal every
+  `healIntervalSec` (600 s) until the sync succeeds.
+- Optional OS dialog on final failure (`notifyOnFailure`).
+- Optional machine snapshot written before each sync and committed with it
+  (`statusFile`).
+- `memory_sync` tool for agents: `{"action":"run"}` and `{"action":"status"}`.
+- Lock file and `last-run.json` / `sync.log` under `$DSH_HOME/memory-sync/`.
+- Tests covering dirty-tree commits, rebase over a peer commit, non-repo errors,
+  lock exclusivity and staleness, and config normalization.
+
+[0.1.0]: https://github.com/QIC-9821/dsh/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QIC-9821
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,120 @@
+# dsh-memory-sync
+
+[![npm version](https://img.shields.io/npm/v/dsh-memory-sync.svg)](https://www.npmjs.com/package/dsh-memory-sync)
+[![CI](https://github.com/QIC-9821/dsh/actions/workflows/ci.yml/badge.svg)](https://github.com/QIC-9821/dsh/actions/workflows/ci.yml)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![node](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](package.json)
+
+> Sync your git-backed memory folder with a peer machine every time DeepSeek Harness starts — latest memories at boot, no daemon, no cron, no manual pull.
+
+中文: [README.md](README.md)
+
+Typical setup: the memory folder (`~/.dsh/memories`) lives on an always-on machine; a laptop syncs its side at startup, lets the server commit and push back, then pulls the result. Nothing runs between startups.
+
+## Install
+
+```bash
+dsh plugin add dsh-memory-sync
+```
+
+Pin a tag, or install from a checkout:
+
+```bash
+dsh plugin add github:QIC-9821/dsh#v0.1.0
+dsh plugin add /absolute/path/to/dsh-memory-sync
+```
+
+Node.js ≥ 22 is required (the runtime bundled with Harness works too).
+
+Then configure it in Harness settings ("Memory sync on startup"), or directly in the profile patch:
+
+```yaml
+- id: dsh-memory-sync
+  name: 'dsh-memory-sync'
+  config:
+    repoPath: ''            # empty = $DSH_HOME/memories
+    remote: cloud
+    branch: main
+    mode: peer
+    peerHost: 203.0.113.10
+    peerUser: dsh
+    peerKeyPath: C:/Users/me/.ssh/id_ed25519
+```
+
+## Config
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `repoPath` | `$DSH_HOME/memories` | git working tree to sync |
+| `remote` | `cloud` | git remote; falls back to `origin` / `cloud` |
+| `branch` | `main` | branch name |
+| `enabled` | `true` | master switch |
+| `runOnStartup` | `true` | run on mount |
+| `startupGraceSec` | `300` | mount counts as a boot only within this many seconds |
+| `mode` | `peer` | `peer` = three phases; `local` = local pull/commit/push only |
+| `peerHost` / `peerUser` | empty | ssh target |
+| `peerKeyPath` | empty | private key; empty = ssh default |
+| `peerCommand` | `/usr/local/bin/dsh-mem-sync` | command run on the peer |
+| `peerEnvName` | `cloud` | `DSH_SYNC_NAME` for that command |
+| `retryDelaySec` | `60` | first retry delay; 0 disables |
+| `healIntervalSec` | `600` | silent self-heal interval; 0 disables |
+| `notifyOnFailure` | `true` | show an OS dialog on final failure |
+| `commitPrefix` | `sync` | auto-commit prefix |
+| `gitPath` | `git` | git executable |
+| `localTimeoutMs` / `peerTimeoutMs` | `120000` | per-phase timeout |
+| `statusFile` | empty | write a machine snapshot there before each sync and commit it (e.g. `~/.dsh/memories/pc-status.md`); empty = off |
+
+State lives in `$DSH_HOME/memory-sync/`: `last-run.json`, `sync.log`, `lock/sync.lock`.
+
+## How it runs
+
+On mount (which is one Harness start) the plugin performs three phases:
+
+1. **Local push** — `git pull --rebase --autostash`, `git add -A`, commit if dirty, `git push`. A rejected push is retried once after `fetch` + `rebase`.
+2. **Peer commit** — over ssh, run a command on the peer (default `DSH_SYNC_NAME=cloud /usr/local/bin/dsh-mem-sync`), so the peer commits and pushes its own side into the same bare repo.
+3. **Local pull** — run the local sync again to fetch the peer's fresh commit.
+
+All three must succeed. On failure the plugin retries once after 60 s; if it still fails it writes `last-run.json`, raises an OS dialog (Windows / macOS / Linux), and then retries silently every 10 minutes until it succeeds.
+
+The startup run only happens when the plugin mounts within 300 s of process start; a hot reload does not trigger a sync.
+
+## Peer setup
+
+The peer only needs a bare repo plus a command that commits and pushes:
+
+```bash
+git init --bare -b main /srv/dsh-memory.git
+chown -R dsh:dsh /srv/dsh-memory.git
+git --git-dir=/srv/dsh-memory.git symbolic-ref HEAD refs/heads/main
+git -C /home/dsh/.dsh/memories remote add origin /srv/dsh-memory.git
+chmod 755 /usr/local/bin/dsh-mem-sync
+```
+
+Add this machine's public key to the peer user's `~/.ssh/authorized_keys` and point the local remote at `ssh://dsh@host/srv/dsh-memory.git`. The plugin only runs the phases in order; it does not care how the repo is laid out.
+
+## Tool
+
+`memory_sync`:
+
+- `{"action":"run"}` — sync now; returns per-phase exit/duration/head.
+- `{"action":"status"}` — last run, HEAD, dirty, ahead/behind, peer configured.
+
+## Security and privacy
+
+- The plugin only runs local `git` and `ssh`; it opens no other network connections and sends no telemetry.
+- It commits and pushes whatever is in `repoPath`; the `statusFile` snapshot is committed too. Check the content before syncing to a public remote.
+- The failure dialog contains the failing phase and git/ssh errors, not repository contents; the log is at `$DSH_HOME/memory-sync/sync.log`.
+- Report vulnerabilities privately as described in [SECURITY.md](SECURITY.md); please do not open a public issue.
+
+## Development
+
+```bash
+npm test
+node --check index.js
+```
+
+Tests use a temporary bare repo and two clones: dirty-file push, rebase over a peer commit, non-repo error, lock exclusivity/staleness, config normalization.
+
+## License and contributing
+
+MIT. Issues and PRs are welcome — read [CONTRIBUTING.md](CONTRIBUTING.md) first; changes are tracked in [CHANGELOG.md](CHANGELOG.md).

package/README.md

@@ -1,3 +1,125 @@
-# Temporary Holding Version
+# dsh-memory-sync
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/dsh-memory-sync.svg)](https://www.npmjs.com/package/dsh-memory-sync)
+[![CI](https://github.com/QIC-9821/dsh/actions/workflows/ci.yml/badge.svg)](https://github.com/QIC-9821/dsh/actions/workflows/ci.yml)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![node](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](package.json)
+
+> 每次打开 DeepSeek Harness，自动把本机的 git 记忆目录和另一台机器双向同步一次——开机就有最新记忆，不用常驻后台。
+
+English: [README.en.md](README.en.md)
+
+适合把 `~/.dsh/memories`（或任意 git 目录）放在一台常开的机器上，另一台电脑每次打开 Harness 时自动对齐；平时不做周期同步，也不需要常驻进程。
+
+## 安装
+
+```bash
+dsh plugin add dsh-memory-sync
+```
+
+固定版本或从源码安装：
+
+```bash
+dsh plugin add github:QIC-9821/dsh#v0.1.0
+dsh plugin add /absolute/path/to/dsh-memory-sync
+```
+
+要求 Node.js ≥ 22（用 Harness 自带运行时也可以）。
+
+安装后在 Harness 设置里找到「启动时同步记忆」并填写配置。配置也可以直接写在 profile 的插槽里：
+
+```yaml
+- id: dsh-memory-sync
+  name: 'dsh-memory-sync'
+  config:
+    repoPath: ''            # 留空 = $DSH_HOME/memories
+    remote: cloud
+    branch: main
+    mode: peer
+    peerHost: 203.0.113.10
+    peerUser: dsh
+    peerKeyPath: C:/Users/me/.ssh/id_ed25519
+```
+
+## 配置
+
+| 键 | 默认 | 说明 |
+| --- | --- | --- |
+| `repoPath` | `$DSH_HOME/memories` | 要同步的 git 工作目录 |
+| `remote` | `cloud` | git remote 名；不存在时依次尝试 `origin`、`cloud` |
+| `branch` | `main` | 分支名 |
+| `enabled` | `true` | 总开关 |
+| `runOnStartup` | `true` | 启动时自动跑 |
+| `startupGraceSec` | `300` | 启动后多少秒内挂载才算「启动」；超过视为热重载 |
+| `mode` | `peer` | `peer` = 三段式；`local` = 只在本机 pull/commit/push |
+| `peerHost` / `peerUser` | 空 | ssh 目标 |
+| `peerKeyPath` | 空 | 私钥路径；空 = 用 ssh 默认密钥 |
+| `peerCommand` | `/usr/local/bin/dsh-mem-sync` | 对端执行的同步脚本 |
+| `peerEnvName` | `cloud` | 执行时设置的 `DSH_SYNC_NAME` |
+| `retryDelaySec` | `60` | 启动失败后第一次重试间隔；0 关闭 |
+| `healIntervalSec` | `600` | 失败后静默自愈间隔；0 关闭 |
+| `notifyOnFailure` | `true` | 失败弹系统窗口 |
+| `commitPrefix` | `sync` | 自动提交信息前缀 |
+| `gitPath` | `git` | git 可执行文件 |
+| `localTimeoutMs` / `peerTimeoutMs` | `120000` | 单段超时 |
+| `statusFile` | 空 | 每次同步前写一份机器快照到该文件（如 `~/.dsh/memories/pc-status.md`），随同步一起提交；空 = 不写 |
+
+状态、日志、锁都在 `$DSH_HOME/memory-sync/`：`last-run.json`、`sync.log`、`lock/sync.lock`。
+
+## 工作方式
+
+插件在 Harness 挂载时（即一次启动）依次执行三段：
+
+1. **本机推送**：`git pull --rebase --autostash` → `git add -A` → 有改动就提交 → `git push`（push 被拒时 fetch + rebase 再试一次）。
+2. **对端提交**：通过 ssh 在远端执行一条命令（默认 `DSH_SYNC_NAME=cloud /usr/local/bin/dsh-mem-sync`），让对端把它的改动提交并推回同一个裸仓。
+3. **本机拉回**：再本地执行一次同样的 pull/commit/push，拿到对端刚推上来的提交。
+
+三段都成功才算成功。失败会 60 秒后重试一次；仍失败则写 `last-run.json`，弹系统窗口提醒（Windows/macOS/Linux 各自实现），之后每 10 分钟静默重试，成功后停止。
+
+> 插件只在进程启动后 300 秒内挂载时执行启动同步；热重载/开发时重新加载插件不会触发。
+
+## 对端准备
+
+对端只需要一个**裸仓**和一条能提交的同步命令，例如：
+
+```bash
+# 裸仓
+git init --bare -b main /srv/dsh-memory.git
+chown -R dsh:dsh /srv/dsh-memory.git
+git --git-dir=/srv/dsh-memory.git symbolic-ref HEAD refs/heads/main
+
+# 对端工作副本（/home/dsh/.dsh/memories）的 remote 指向裸仓
+git -C /home/dsh/.dsh/memories remote add origin /srv/dsh-memory.git
+
+# /usr/local/bin/dsh-mem-sync：pull --rebase --autostash → add/commit → push
+chmod 755 /usr/local/bin/dsh-mem-sync
+```
+
+把本机的 ssh 公钥加到对端用户的 `~/.ssh/authorized_keys`，本机 remote 用 `ssh://dsh@host/srv/dsh-memory.git`。插件只负责「启动时按顺序跑」，不理解仓库布局。
+
+## 工具
+
+Agent 可调用 `memory_sync`：
+
+- `{"action":"run"}`：立刻同步一次，返回三段的 exit/耗时/head。
+- `{"action":"status"}`：上次结果、HEAD、dirty、ahead/behind、peer 是否配置。
+
+## 安全与隐私
+
+- 插件只运行本机 `git` 和 `ssh`，不发起其它网络请求、不上传遥测。
+- 它会把 `repoPath` 里的内容提交并推送；`statusFile` 生成的机器快照也会一起进入仓库。同步到公开仓库前请自行确认内容。
+- 失败弹窗包含出错的阶段和 git/ssh 报错，不含仓库文件内容；日志在 `$DSH_HOME/memory-sync/sync.log`。
+- 安全漏洞请走 [SECURITY.md](SECURITY.md) 里的私密渠道，不要开公开 issue。
+
+## 开发
+
+```bash
+npm test          # node --test test/*.test.mjs
+node --check index.js
+```
+
+测试用临时裸仓 + 两次 clone 覆盖：脏文件提交推送、对端先提交的 rebase、非 git 目录报错、锁互斥与过期回收、配置归一化。
+
+## 许可与贡献
+
+MIT。欢迎提 issue / PR，先看 [CONTRIBUTING.md](CONTRIBUTING.md)；变更记录在 [CHANGELOG.md](CHANGELOG.md)。

package/cordis.patch.yml

@@ -0,0 +1,8 @@
+- insert:
+    - id: dsh-memory-sync
+      name: 'dsh-memory-sync'
+      config:
+        enabled: true
+        runOnStartup: true
+        mode: peer
+        repoPath: ''

package/icon.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">
+  <rect width="64" height="64" rx="14" fill="#1f2a44"/>
+  <circle cx="20" cy="20" r="6" fill="#7ee0c5"/>
+  <circle cx="44" cy="44" r="6" fill="#7ee0c5"/>
+  <path d="M20 26v6a6 6 0 0 0 6 6h12" fill="none" stroke="#7ee0c5" stroke-width="4" stroke-linecap="round"/>
+  <path d="M44 38v-6a6 6 0 0 0-6-6H26" fill="none" stroke="#4f7cff" stroke-width="4" stroke-linecap="round" stroke-dasharray="2 7"/>
+  <path d="M36 14l6 4-6 4" fill="none" stroke="#4f7cff" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M28 50l-6-4 6-4" fill="none" stroke="#7ee0c5" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/index.js

@@ -0,0 +1,93 @@
+import { join } from 'node:path'
+
+import { normalizeConfig } from './lib/config.mjs'
+import { ensureDir, createLogger, rotateLog } from './lib/state.mjs'
+import { createSyncRuntime } from './lib/sync.mjs'
+import { memorySyncToolSpec } from './lib/tool.mjs'
+
+export const name = 'dsh-memory-sync'
+
+/**
+ * Config is optional: hosts without @deepseek-ai/schemastery must still load
+ * the plugin (they just lose the generated settings form).
+ */
+let z = null
+try {
+  const mod = await import('@deepseek-ai/schemastery')
+  z = mod?.default ?? mod ?? null
+} catch {
+  z = null
+}
+
+const field = (schema) => (typeof schema?.extra === 'function' ? schema.extra('volatile', true) : schema)
+
+export const Config = z
+  ? z.object({
+      repoPath: field(z.string().default('')),
+      remote: field(z.string().default('cloud')),
+      branch: field(z.string().default('main')),
+      enabled: field(z.boolean().default(true)),
+      runOnStartup: field(z.boolean().default(true)),
+      startupGraceSec: field(z.natural().default(300)),
+      mode: field(z.string().default('peer')),
+      peerHost: field(z.string().default('')),
+      peerUser: field(z.string().default('')),
+      peerKeyPath: field(z.string().default('')),
+      peerCommand: field(z.string().default('/usr/local/bin/dsh-mem-sync')),
+      peerEnvName: field(z.string().default('cloud')),
+      retryDelaySec: field(z.natural().default(60)),
+      healIntervalSec: field(z.natural().default(600)),
+      notifyOnFailure: field(z.boolean().default(true)),
+      commitPrefix: field(z.string().default('sync')),
+      gitPath: field(z.string().default('git')),
+      localTimeoutMs: field(z.natural().default(120000)),
+      peerTimeoutMs: field(z.natural().default(120000)),
+      statusFile: field(z.string().default('')),
+    })
+  : undefined
+
+export const inject = ['tools']
+
+function pickLogger(logger) {
+  if (typeof logger?.info === 'function') return logger
+  return {
+    info: (...args) => console.log('[memory-sync]', ...args),
+    warn: (...args) => console.warn('[memory-sync]', ...args),
+    error: (...args) => console.error('[memory-sync]', ...args),
+  }
+}
+
+export async function apply(ctx, config = {}) {
+  const cfg = normalizeConfig(config, process.env)
+  await ensureDir(cfg.stateDir).catch(() => {})
+  await rotateLog(join(cfg.stateDir, 'sync.log')).catch(() => {})
+
+  const logger = pickLogger(createLogger({ dir: cfg.stateDir, tag: 'memory-sync' }))
+  const runtime = createSyncRuntime({ cfg, logger })
+
+  const disposers = []
+  if (typeof ctx?.tools?.register === 'function') {
+    try {
+      disposers.push(ctx.tools.register(memorySyncToolSpec(runtime)))
+    } catch (error) {
+      logger.warn(`tool registration failed: ${error?.message || error}`)
+    }
+  }
+
+  runtime.scheduleStartup()
+  logger.info(`ready: repo=${cfg.repoPath} mode=${cfg.mode} remote=${cfg.remote}/${cfg.branch}`)
+
+  const dispose = async () => {
+    runtime.dispose()
+    for (const disposer of disposers.reverse()) {
+      try {
+        disposer?.()
+      } catch {
+        // ignore teardown errors
+      }
+    }
+  }
+
+  ctx.effect?.(() => () => dispose(), 'dsh-memory-sync: teardown')
+  return dispose
+}

package/lib/config.mjs

@@ -0,0 +1,149 @@
+import { homedir } from 'node:os'
+import { isAbsolute, join, resolve } from 'node:path'
+
+/** Defaults for every config key. Empty strings mean "not set yet". */
+export const DEFAULTS = Object.freeze({
+  repoPath: '',
+  remote: 'cloud',
+  branch: 'main',
+  enabled: true,
+  runOnStartup: true,
+  startupGraceSec: 300,
+  mode: 'peer',
+  peerHost: '',
+  peerUser: '',
+  peerKeyPath: '',
+  peerCommand: '/usr/local/bin/dsh-mem-sync',
+  peerEnvName: 'cloud',
+  retryDelaySec: 60,
+  healIntervalSec: 600,
+  notifyOnFailure: true,
+  commitPrefix: 'sync',
+  gitPath: 'git',
+  localTimeoutMs: 120000,
+  peerTimeoutMs: 120000,
+  statusFile: '',
+  stateDir: '',
+})
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+/**
+ * Hosts expose config fields marked `.extra('volatile', true)` as live
+ * references (`{ get() }`) instead of raw scalars. Unwrap them so both a
+ * plain object and a reference map normalize to the same values.
+ */
+function unwrapRef(value) {
+  let current = value
+  for (let i = 0; i < 4; i += 1) {
+    if (current === null || typeof current !== 'object') return current
+    // Live config references look like `{ get() }` (method) or `{ get value() }`
+    // (accessor). Support both, plus a plain `{ value }` wrapper.
+    if (typeof current.get === 'function') {
+      try {
+        current = current.get()
+      } catch {
+        return undefined
+      }
+      continue
+    }
+    if ('get' in current) {
+      current = current.get
+      continue
+    }
+    if ('value' in current) {
+      current = current.value
+      continue
+    }
+    return current
+  }
+  return current
+}
+
+function toInt(value, fallback, min, max) {
+  const n = Number(value)
+  if (!Number.isFinite(n)) return fallback
+  const i = Math.trunc(n)
+  if (i < min || i > max) return fallback
+  return i
+}
+
+function toBool(value, fallback) {
+  if (typeof value === 'boolean') return value
+  if (value === 'true' || value === 1) return true
+  if (value === 'false' || value === 0) return false
+  return fallback
+}
+
+function dshHome(env) {
+  const home = String(env?.DSH_HOME || '').trim()
+  return home ? resolve(home) : join(homedir(), '.dsh')
+}
+
+function expandHome(value, env) {
+  const text = String(value || '').trim()
+  if (!text) return ''
+  if (text === '~') return homedir()
+  if (text.startsWith('~/') || text.startsWith('~\\')) {
+    return join(homedir(), text.slice(2))
+  }
+  if (isAbsolute(text)) return text
+  return resolve(env?.DSH_HOME ? dshHome(env) : process.cwd(), text)
+}
+
+/**
+ * Normalize a Loader config object into a frozen, fully-resolved config.
+ * Empty strings are treated as "not set" so a user can clear a field and
+ * fall back to the default.
+ */
+export function normalizeConfig(raw = {}, env = process.env) {
+  const input = unwrapRef(raw)
+  const src = isPlainObject(input) ? input : {}
+  const merged = { ...DEFAULTS }
+  for (const key of Object.keys(DEFAULTS)) {
+    const value = unwrapRef(src[key])
+    if (value === undefined || value === null) continue
+    if (typeof value === 'string' && value.trim() === '') continue
+    merged[key] = value
+  }
+
+  const home = dshHome(env)
+  const stateDir = resolve(
+    expandHome(String(merged.stateDir || ''), env) || join(home, 'memory-sync'),
+  )
+  const repoPath = resolve(
+    expandHome(String(merged.repoPath || ''), env) || join(home, 'memories'),
+  )
+
+  return Object.freeze({
+    repoPath,
+    stateDir,
+    remote: String(merged.remote || DEFAULTS.remote),
+    branch: String(merged.branch || DEFAULTS.branch),
+    enabled: toBool(merged.enabled, DEFAULTS.enabled),
+    runOnStartup: toBool(merged.runOnStartup, DEFAULTS.runOnStartup),
+    startupGraceSec: toInt(merged.startupGraceSec, DEFAULTS.startupGraceSec, 0, 86400),
+    mode: merged.mode === 'local' ? 'local' : 'peer',
+    peerHost: String(merged.peerHost || '').trim(),
+    peerUser: String(merged.peerUser || '').trim(),
+    peerKeyPath: expandHome(String(merged.peerKeyPath || ''), env),
+    peerCommand: String(merged.peerCommand || DEFAULTS.peerCommand).trim(),
+    peerEnvName: String(merged.peerEnvName || DEFAULTS.peerEnvName).trim(),
+    retryDelaySec: toInt(merged.retryDelaySec, DEFAULTS.retryDelaySec, 0, 3600),
+    healIntervalSec: toInt(merged.healIntervalSec, DEFAULTS.healIntervalSec, 0, 86400),
+    notifyOnFailure: toBool(merged.notifyOnFailure, DEFAULTS.notifyOnFailure),
+    commitPrefix: String(merged.commitPrefix || DEFAULTS.commitPrefix).trim() || 'sync',
+    gitPath: String(merged.gitPath || DEFAULTS.gitPath).trim() || 'git',
+    localTimeoutMs: toInt(merged.localTimeoutMs, DEFAULTS.localTimeoutMs, 5000, 600000),
+    peerTimeoutMs: toInt(merged.peerTimeoutMs, DEFAULTS.peerTimeoutMs, 5000, 600000),
+    // Optional machine snapshot committed with the sync (empty = disabled).
+    statusFile: expandHome(String(merged.statusFile || ''), env),
+  })
+}
+
+/** The config has a usable repo path; the runtime checks whether it is a git repo. */
+export function isConfigured(cfg) {
+  return Boolean(cfg?.repoPath)
+}