skillwiki 0.5.4 → 0.6.0

package/dist/cli.js

@@ -8,8 +8,8 @@ import {
 } from "./chunk-TPS5XD2J.js";
 
 // src/cli.ts
-import { readFileSync as readFileSync10 } from "fs";
-import { join as join39 } from "path";
+import { readFileSync as readFileSync11 } from "fs";
+import { join as join41 } from "path";
 import { Command as Command2 } from "commander";
 
 // ../shared/src/exit-codes.ts
@@ -61,7 +61,8 @@ var ExitCode = {
   BACKUP_SYNC_FAILED: 44,
   BACKUP_RESTORE_CONFLICTS: 45,
   USAGE: 46,
-  BODY_TRUNCATION_GUARD: 47
+  BODY_TRUNCATION_GUARD: 47,
+  SYNC_LOCK_HELD: 48
 };
 
 // ../shared/src/json-output.ts
@@ -3439,10 +3440,9 @@ async function runConfigPath(input) {
 }
 
 // src/commands/doctor.ts
-import { existsSync as existsSync6, lstatSync, readlinkSync, readdirSync, readFileSync as readFileSync6, statSync as statSync2 } from "fs";
-import { join as join23, resolve as resolve4 } from "path";
-import { execSync } from "child_process";
-import { platform } from "os";
+import { existsSync as existsSync7, lstatSync, readlinkSync, readdirSync, statSync as statSync2 } from "fs";
+import { join as join24, resolve as resolve4 } from "path";
+import { execSync as execSync2 } from "child_process";
 
 // src/utils/auto-update.ts
 import { readFileSync as readFileSync4, writeFileSync as writeFileSync3, existsSync as existsSync5, mkdirSync as mkdirSync2 } from "fs";
@@ -3470,9 +3470,9 @@ function readCacheRaw(home) {
 function readCache(home) {
   const cache = readCacheRaw(home);
   if (!cache) return { cache: null, hasUpdate: false, isStale: true };
-  const isStale = Date.now() - cache.lastCheck >= CHECK_INTERVAL_MS;
+  const isStale2 = Date.now() - cache.lastCheck >= CHECK_INTERVAL_MS;
   const hasUpdate = !!cache.latestVersion && semverGt(cache.latestVersion, cache.currentVersion);
-  return { cache, hasUpdate, isStale };
+  return { cache, hasUpdate, isStale: isStale2 };
 }
 function writeCache(home, cache) {
   const p = cachePath(home);
@@ -3492,8 +3492,8 @@ function isDisabled() {
 }
 function triggerAutoUpdate(home, currentVersion) {
   if (isDisabled()) return;
-  const { isStale } = readCache(home);
-  if (!isStale) return;
+  const { isStale: isStale2 } = readCache(home);
+  if (!isStale2) return;
   const bgScript = new URL("../auto-update-bg.js", import.meta.url).pathname;
   if (!existsSync5(bgScript)) return;
   const child = spawn(process.execPath, [bgScript, home, currentVersion], {
@@ -3526,6 +3526,208 @@ function findPlugin(home, key = PLUGIN_KEY) {
   return entries[0];
 }
 
+// src/utils/s3-mount-health.ts
+import { execSync } from "child_process";
+import { platform } from "os";
+import { readFileSync as readFileSync6, writeFileSync as writeFileSync4, unlinkSync as unlinkSync3, readFileSync as readFile17 } from "fs";
+import { join as join23 } from "path";
+var OS = platform();
+function findRcloneMountPid() {
+  try {
+    const out = execSync("pgrep -f 'rclone.*mount'", {
+      encoding: "utf8",
+      timeout: 2e3,
+      stdio: ["pipe", "pipe", "pipe"]
+    }).trim();
+    const pids = out.split("\n").filter(Boolean);
+    if (pids.length === 0) return null;
+    return parseInt(pids[0], 10);
+  } catch {
+    try {
+      const out = execSync("ps aux", { encoding: "utf8", timeout: 2e3, stdio: ["pipe", "pipe", "pipe"] });
+      for (const line of out.split("\n")) {
+        if (line.includes("rclone") && line.includes("mount") && !line.includes("grep")) {
+          const parts = line.trim().split(/\s+/);
+          if (parts.length >= 2) return parseInt(parts[1], 10);
+        }
+      }
+    } catch {
+    }
+    return null;
+  }
+}
+function parseRcloneFlags(pid) {
+  const flags = /* @__PURE__ */ new Map();
+  try {
+    const args = getRcloneArgs(pid);
+    for (let i = 0; i < args.length; i++) {
+      const arg = args[i];
+      if (arg.startsWith("--") && arg.includes("=")) {
+        const eq = arg.indexOf("=");
+        flags.set(arg.slice(0, eq), arg.slice(eq + 1));
+      } else if (arg.startsWith("--")) {
+        const next = args[i + 1];
+        if (next && !next.startsWith("-")) {
+          flags.set(arg, next);
+          i++;
+        } else {
+          flags.set(arg, "");
+        }
+      }
+    }
+  } catch {
+  }
+  return flags;
+}
+function getRcloneVersion() {
+  try {
+    const out = execSync("rclone version", {
+      encoding: "utf8",
+      timeout: 3e3,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    const match = out.match(/rclone\s+v(\d+)\.(\d+)\.(\d+)/i);
+    if (!match) return null;
+    return {
+      major: parseInt(match[1], 10),
+      minor: parseInt(match[2], 10),
+      patch: parseInt(match[3], 10),
+      raw: out.split("\n")[0].trim()
+    };
+  } catch {
+    return null;
+  }
+}
+function extractRcloneFs(args) {
+  let foundMount = false;
+  for (const arg of args) {
+    if (arg === "mount") {
+      foundMount = true;
+      continue;
+    }
+    if (foundMount && arg.includes(":") && !arg.startsWith("-") && !arg.startsWith("/")) {
+      return arg;
+    }
+  }
+  return null;
+}
+function getRcloneArgs(pid) {
+  try {
+    if (OS === "linux") {
+      const raw = readFileSync6(`/proc/${pid}/cmdline`);
+      return new TextDecoder().decode(raw).split("\0").filter(Boolean);
+    } else {
+      const out = execSync(`ps -o args= -p ${pid}`, {
+        encoding: "utf8",
+        timeout: 2e3,
+        stdio: ["pipe", "pipe", "pipe"]
+      }).trim();
+      return out.split(/\s+/);
+    }
+  } catch {
+    return [];
+  }
+}
+function queryRcloneRC(rcAddr, fs) {
+  try {
+    const payload = JSON.stringify({ fs });
+    const out = execSync(
+      `curl -s --max-time 3 -X POST "http://${rcAddr}/vfs/stats" -H "Content-Type: application/json" -d '${payload}' 2>/dev/null`,
+      { encoding: "utf8", timeout: 5e3, stdio: ["pipe", "pipe", "pipe"] }
+    );
+    if (!out.trim()) return null;
+    const data = JSON.parse(out);
+    if (data.status && data.status >= 400) {
+      return { error: data.error || `RC error (status ${data.status})`, erroredFiles: 0, uploadsInProgress: 0, uploadsQueued: 0, outOfSpace: false, bytesUsed: 0, files: 0, totalSize: "unknown" };
+    }
+    const dc = data.diskCache || {};
+    return {
+      erroredFiles: dc.erroredFiles ?? 0,
+      uploadsInProgress: dc.uploadsInProgress ?? 0,
+      uploadsQueued: dc.uploadsQueued ?? 0,
+      outOfSpace: dc.outOfSpace ?? false,
+      bytesUsed: dc.bytesUsed ?? 0,
+      files: dc.files ?? 0,
+      totalSize: data.totalSize || "unknown"
+    };
+  } catch {
+    return { error: "RC endpoint unreachable", erroredFiles: 0, uploadsInProgress: 0, uploadsQueued: 0, outOfSpace: false, bytesUsed: 0, files: 0, totalSize: "unknown" };
+  }
+}
+function detectFuseMount(vaultPath) {
+  try {
+    if (OS === "linux") {
+      const mounts = readFileSync6("/proc/mounts", "utf8");
+      let best = null;
+      for (const line of mounts.split("\n")) {
+        const parts = line.split(" ");
+        if (parts.length < 3) continue;
+        const point = parts[1];
+        const fs = parts[2];
+        if (vaultPath.startsWith(point) && (!best || point.length > best.point.length)) {
+          best = { point, fs };
+        }
+      }
+      if (best && best.fs.includes("fuse")) return { mountPoint: best.point, fsType: best.fs };
+    } else if (OS === "darwin") {
+      const out = execSync("mount", { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
+      let best = null;
+      for (const line of out.split("\n")) {
+        const match = line.match(/^(\S+) on (\S+) \((.*?)\)/);
+        if (!match) continue;
+        const point = match[2];
+        const opts = match[3];
+        if (opts.includes("fuse") && vaultPath.startsWith(point) && (!best || point.length > best.point.length)) {
+          best = { point, fsType: `fuse.${match[1].split(":")[0] || "unknown"}` };
+        }
+      }
+      if (best) return best;
+    }
+  } catch {
+  }
+  return null;
+}
+function writeTest(dir) {
+  const testFile = join23(dir, `.doctor-write-test-${process.pid}.tmp`);
+  const payload = `skillwiki doctor write test \u2014 ${Date.now()} \u2014 ${Math.random().toString(36).slice(2)}`;
+  const start = Date.now();
+  try {
+    writeFileSync4(testFile, payload, "utf8");
+  } catch (e) {
+    return { success: false, writeMs: Date.now() - start, readMs: 0, size: 0, error: `write failed: ${e.message}` };
+  }
+  const writeMs = Date.now() - start;
+  const readStart = Date.now();
+  try {
+    const back = readFile17(testFile, "utf8");
+    const readMs = Date.now() - readStart;
+    if (back !== payload) {
+      try {
+        unlinkSync3(testFile);
+      } catch {
+      }
+      return { success: false, writeMs, readMs, size: Buffer.byteLength(payload, "utf8"), error: "content mismatch \u2014 wrote and read-back differ" };
+    }
+  } catch (e) {
+    try {
+      unlinkSync3(testFile);
+    } catch {
+    }
+    return { success: false, writeMs, readMs: Date.now() - readStart, size: 0, error: `read failed: ${e.message}` };
+  }
+  try {
+    unlinkSync3(testFile);
+  } catch {
+  }
+  return { success: true, writeMs, readMs: Date.now() - readStart, size: Buffer.byteLength(payload, "utf8") };
+}
+var FLAG_THRESHOLDS = {
+  "--vfs-write-back": { min: 15, unit: "s", label: "VFS write-back window" },
+  "--vfs-write-wait": { min: 10, unit: "s", label: "VFS write-wait" },
+  "--vfs-cache-max-age": { min: 24, unit: "h", label: "VFS cache max age" }
+};
+var MIN_RCLONE_VERSION = { major: 1, minor: 65, patch: 0 };
+
 // src/commands/doctor.ts
 function check(status, id, label, detail) {
   return { id, label, status, detail };
@@ -3544,7 +3746,7 @@ function detectCliChannels(argv, home) {
     channels.push({ name: "dev", path: devPath, isDevLink: true });
   }
   try {
-    const whichOut = execSync("which skillwiki 2>/dev/null", { encoding: "utf8" }).trim();
+    const whichOut = execSync2("which skillwiki 2>/dev/null", { encoding: "utf8" }).trim();
     if (whichOut) {
       const isDev = isDevSymlink(whichOut);
       if (!channels.some((c) => c.path === resolve4(whichOut))) {
@@ -3555,13 +3757,13 @@ function detectCliChannels(argv, home) {
   }
   const plugin = findPlugin(home);
   if (plugin) {
-    const pluginBin = join23(plugin.installPath, "bin", "skillwiki");
-    if (existsSync6(pluginBin)) {
+    const pluginBin = join24(plugin.installPath, "bin", "skillwiki");
+    if (existsSync7(pluginBin)) {
       channels.push({ name: "plugin", path: pluginBin, isDevLink: false });
     }
   }
-  const installBin = join23(home, ".claude", "skills", "bin", "skillwiki");
-  if (existsSync6(installBin)) {
+  const installBin = join24(home, ".claude", "skills", "bin", "skillwiki");
+  if (existsSync7(installBin)) {
     channels.push({ name: "install", path: installBin, isDevLink: false });
   }
   return channels;
@@ -3613,7 +3815,7 @@ function checkCliChannels(argv, home) {
 }
 async function checkConfigFile(home) {
   const cfgPath = configPath(home);
-  if (!existsSync6(cfgPath)) {
+  if (!existsSync7(cfgPath)) {
     return check("warn", "config_file", "Config file exists", `${cfgPath} not found`);
   }
   try {
@@ -3628,7 +3830,7 @@ function checkWikiPathExists(resolvedPath) {
   if (resolvedPath === void 0) {
     return check("error", "wiki_path_exists", "Vault directory exists", "Cannot check \u2014 WIKI_PATH not resolved");
   }
-  if (existsSync6(resolvedPath) && statSync2(resolvedPath).isDirectory()) {
+  if (existsSync7(resolvedPath) && statSync2(resolvedPath).isDirectory()) {
     return check("pass", "wiki_path_exists", "Vault directory exists", resolvedPath);
   }
   return check("error", "wiki_path_exists", "Vault directory exists", `${resolvedPath} does not exist or is not a directory`);
@@ -3637,13 +3839,13 @@ function checkVaultStructure(resolvedPath) {
   if (resolvedPath === void 0) {
     return check("error", "vault_structure", "Vault structure valid", "Cannot check \u2014 WIKI_PATH not resolved");
   }
-  if (!existsSync6(resolvedPath)) {
+  if (!existsSync7(resolvedPath)) {
     return check("error", "vault_structure", "Vault structure valid", "Cannot check \u2014 vault directory does not exist");
   }
   const missing = [];
-  if (!existsSync6(join23(resolvedPath, "SCHEMA.md"))) missing.push("SCHEMA.md");
+  if (!existsSync7(join24(resolvedPath, "SCHEMA.md"))) missing.push("SCHEMA.md");
   for (const dir of ["raw", "entities", "concepts", "meta"]) {
-    if (!existsSync6(join23(resolvedPath, dir))) missing.push(dir + "/");
+    if (!existsSync7(join24(resolvedPath, dir))) missing.push(dir + "/");
   }
   if (missing.length === 0) {
     return check("pass", "vault_structure", "Vault structure valid", "All required files and directories present");
@@ -3651,8 +3853,8 @@ function checkVaultStructure(resolvedPath) {
   return check("warn", "vault_structure", "Vault structure valid", `Missing: ${missing.join(", ")} \u2014 run \`skillwiki init\` to add CodeWiki structure`);
 }
 function checkSkillsInstalled(home, cwd) {
-  const srcDir = cwd ? join23(cwd, "packages", "skills") : void 0;
-  if (srcDir && existsSync6(srcDir)) {
+  const srcDir = cwd ? join24(cwd, "packages", "skills") : void 0;
+  if (srcDir && existsSync7(srcDir)) {
     const found = findSkillMd(srcDir);
     if (found.length > 0) {
       return check("pass", "skills_installed", "Skills installed", `${found.length} SKILL.md file(s) found (source)`);
@@ -3665,8 +3867,8 @@ function checkSkillsInstalled(home, cwd) {
       return check("pass", "skills_installed", "Skills installed", `${found.length} SKILL.md file(s) found (plugin v${plugin.version})`);
     }
   }
-  const skillsDir = join23(home, ".claude", "skills");
-  if (existsSync6(skillsDir)) {
+  const skillsDir = join24(home, ".claude", "skills");
+  if (existsSync7(skillsDir)) {
     const found = findSkillMd(skillsDir);
     if (found.length > 0) {
       return check("pass", "skills_installed", "Skills installed", `${found.length} SKILL.md file(s) found (CLI install)`);
@@ -3676,10 +3878,10 @@ function checkSkillsInstalled(home, cwd) {
 }
 function checkDuplicateSkills(home) {
   const plugin = findPlugin(home);
-  const skillsDir = join23(home, ".claude", "skills");
+  const skillsDir = join24(home, ".claude", "skills");
   const agentSkillDirs = [
-    { label: "~/.codex/skills/", path: join23(home, ".codex", "skills") },
-    { label: "~/.agents/skills/", path: join23(home, ".agents", "skills") }
+    { label: "~/.codex/skills/", path: join24(home, ".codex", "skills") },
+    { label: "~/.agents/skills/", path: join24(home, ".agents", "skills") }
   ];
   if (!plugin) {
     return check("pass", "skills_duplicate", "Skills not duplicated", "Single install channel");
@@ -3756,8 +3958,8 @@ async function checkProfiles(home) {
 }
 async function checkProjectLocalOverride(cwd) {
   const dir = cwd ?? process.cwd();
-  const envPath = join23(dir, ".skillwiki", ".env");
-  if (existsSync6(envPath)) {
+  const envPath = join24(dir, ".skillwiki", ".env");
+  if (existsSync7(envPath)) {
     return check("pass", "project_local", "Project-local config", `Found: ${envPath}`);
   }
   return check("pass", "project_local", "Project-local config", "None");
@@ -3766,17 +3968,17 @@ function checkVaultGitRemote(resolvedPath) {
   if (resolvedPath === void 0) {
     return check("error", "vault_git_remote", "Vault git remote", "Cannot check \u2014 WIKI_PATH not resolved");
   }
-  if (!existsSync6(join23(resolvedPath, ".git"))) {
+  if (!existsSync7(join24(resolvedPath, ".git"))) {
     return check("warn", "vault_git_remote", "Vault git remote", "Vault is not a git repository \u2014 sync features unavailable");
   }
   try {
-    const remote = execSync("git remote", { cwd: resolvedPath, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+    const remote = execSync2("git remote", { cwd: resolvedPath, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
     if (!remote) {
       return check("warn", "vault_git_remote", "Vault git remote", "No remote configured \u2014 push/pull unavailable");
     }
     let branch = "(no commits yet)";
     try {
-      branch = execSync("git rev-parse --abbrev-ref HEAD", { cwd: resolvedPath, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+      branch = execSync2("git rev-parse --abbrev-ref HEAD", { cwd: resolvedPath, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
     } catch {
     }
     return check("pass", "vault_git_remote", "Vault git remote", `Remote: ${remote.split("\n")[0]}, branch: ${branch}`);
@@ -3789,9 +3991,9 @@ function checkObsidianTemplates(resolvedPath) {
     return check("error", "obsidian_templates", "Obsidian templates", "Cannot check \u2014 WIKI_PATH not resolved");
   }
   const missing = [];
-  if (!existsSync6(join23(resolvedPath, "_Templates"))) missing.push("_Templates/");
-  if (!existsSync6(join23(resolvedPath, ".obsidian", "templates.json"))) missing.push(".obsidian/templates.json");
-  if (!existsSync6(join23(resolvedPath, ".obsidian", "app.json"))) missing.push(".obsidian/app.json");
+  if (!existsSync7(join24(resolvedPath, "_Templates"))) missing.push("_Templates/");
+  if (!existsSync7(join24(resolvedPath, ".obsidian", "templates.json"))) missing.push(".obsidian/templates.json");
+  if (!existsSync7(join24(resolvedPath, ".obsidian", "app.json"))) missing.push(".obsidian/app.json");
   if (missing.length === 0) {
     return check("pass", "obsidian_templates", "Obsidian templates", "Template folder and config present");
   }
@@ -3801,8 +4003,8 @@ function checkDotStoreClean(resolvedPath) {
   if (resolvedPath === void 0) {
     return check("error", "dsstore_clean", "No .DS_Store in raw/", "Cannot check \u2014 WIKI_PATH not resolved");
   }
-  const rawDir = join23(resolvedPath, "raw");
-  if (!existsSync6(rawDir)) {
+  const rawDir = join24(resolvedPath, "raw");
+  if (!existsSync7(rawDir)) {
     return check("pass", "dsstore_clean", "No .DS_Store in raw/", "raw/ directory not found \u2014 check skipped");
   }
   const found = [];
@@ -3817,7 +4019,7 @@ function checkDotStoreClean(resolvedPath) {
       if (entry.name === ".DS_Store") {
         found.push(rel ? `${rel}/.DS_Store` : ".DS_Store");
       } else if (entry.isDirectory()) {
-        walk2(join23(dir, entry.name), rel ? `${rel}/${entry.name}` : entry.name);
+        walk2(join24(dir, entry.name), rel ? `${rel}/${entry.name}` : entry.name);
       }
     }
   })(rawDir, "");
@@ -3830,12 +4032,12 @@ function checkSyncLastPush(resolvedPath) {
   if (resolvedPath === void 0) {
     return check("error", "sync_last_push", "Vault sync recency", "Cannot check \u2014 WIKI_PATH not resolved");
   }
-  if (!existsSync6(join23(resolvedPath, ".git"))) {
+  if (!existsSync7(join24(resolvedPath, ".git"))) {
     return check("pass", "sync_last_push", "Vault sync recency", "No git repo \u2014 sync check skipped");
   }
   let timestamp;
   try {
-    const out = execSync("git log -1 --format=%ct origin/HEAD", {
+    const out = execSync2("git log -1 --format=%ct origin/HEAD", {
       cwd: resolvedPath,
       encoding: "utf8",
       stdio: ["pipe", "pipe", "pipe"]
@@ -3843,7 +4045,7 @@ function checkSyncLastPush(resolvedPath) {
     timestamp = parseInt(out, 10);
   } catch {
     try {
-      const out = execSync("git log -1 --format=%ct HEAD", {
+      const out = execSync2("git log -1 --format=%ct HEAD", {
         cwd: resolvedPath,
         encoding: "utf8",
         stdio: ["pipe", "pipe", "pipe"]
@@ -3862,56 +4064,23 @@ function checkSyncLastPush(resolvedPath) {
   }
   return check("pass", "sync_last_push", "Vault sync recency", `Last push: ${dateStr} (${daysSince2} day(s) ago)`);
 }
-function detectFuseMount(vaultPath) {
-  const os = platform();
-  try {
-    if (os === "linux") {
-      const mounts = readFileSync6("/proc/mounts", "utf8");
-      let best = null;
-      for (const line of mounts.split("\n")) {
-        const parts = line.split(" ");
-        if (parts.length < 3) continue;
-        const point = parts[1];
-        const fs = parts[2];
-        if (vaultPath.startsWith(point) && (!best || point.length > best.point.length)) {
-          best = { point, fs };
-        }
-      }
-      if (best && best.fs.includes("fuse")) return best.point;
-    } else if (os === "darwin") {
-      const out = execSync("mount", { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
-      let best = null;
-      for (const line of out.split("\n")) {
-        const match = line.match(/^(\S+) on (\S+) \((.*?)\)/);
-        if (!match) continue;
-        const point = match[2];
-        const opts = match[3];
-        if (opts.includes("fuse") && vaultPath.startsWith(point) && (!best || point.length > best.point.length)) {
-          best = { point };
-        }
-      }
-      if (best) return best.point;
-    }
-  } catch {
-  }
-  return null;
-}
 function checkS3MountPerf(resolvedPath) {
   if (resolvedPath === void 0) {
     return check("pass", "s3_mount_perf", "S3 mount performance", "No vault path \u2014 check skipped");
   }
-  const mountPoint = detectFuseMount(resolvedPath);
-  if (!mountPoint) {
+  const fuse = detectFuseMount(resolvedPath);
+  if (!fuse) {
     return check("pass", "s3_mount_perf", "S3 mount performance", "local disk");
   }
-  const conceptsDir = join23(resolvedPath, "concepts");
-  if (!existsSync6(conceptsDir)) {
+  const mountPoint = fuse.mountPoint;
+  const conceptsDir = join24(resolvedPath, "concepts");
+  if (!existsSync7(conceptsDir)) {
     return check("pass", "s3_mount_perf", "S3 mount performance", `S3 FUSE mount (${mountPoint}), no concepts/ to benchmark`);
   }
   const start = Date.now();
   let timedOut = false;
   try {
-    execSync(`rg -l "." "${conceptsDir}"`, {
+    execSync2(`rg -l "." "${conceptsDir}"`, {
       timeout: 5e3,
       encoding: "utf8",
       stdio: ["pipe", "pipe", "pipe"]
@@ -3944,6 +4113,170 @@ function checkS3MountPerf(resolvedPath) {
     `S3 FUSE mount, cache warm (rg scan: ${elapsed.toFixed(3)}s)`
   );
 }
+function checkRcloneFlagAudit(resolvedPath) {
+  if (!resolvedPath) {
+    return check("pass", "rclone_flags", "rclone VFS flags", "No vault path \u2014 check skipped");
+  }
+  const fuse = detectFuseMount(resolvedPath);
+  if (!fuse) {
+    return check("pass", "rclone_flags", "rclone VFS flags", "local disk \u2014 check skipped");
+  }
+  const pid = findRcloneMountPid();
+  if (pid === null) {
+    return check("warn", "rclone_flags", "rclone VFS flags", `S3 FUSE mount (${fuse.mountPoint}) but no rclone process found \u2014 cannot audit flags`);
+  }
+  const flags = parseRcloneFlags(pid);
+  if (flags.size === 0) {
+    return check("warn", "rclone_flags", "rclone VFS flags", `rclone PID ${pid} found but could not parse flags`);
+  }
+  const warnings = [];
+  for (const [flag, threshold] of Object.entries(FLAG_THRESHOLDS)) {
+    const raw = flags.get(flag);
+    if (raw === void 0) {
+      warnings.push(`${flag} not set (default may be unsafe)`);
+      continue;
+    }
+    const value = parseFloat(raw);
+    if (isNaN(value)) continue;
+    let inSeconds = value;
+    if (raw.endsWith("h")) inSeconds = value * 3600;
+    else if (raw.endsWith("m")) inSeconds = value * 60;
+    const thresholdSec = threshold.unit === "h" ? threshold.min * 3600 : threshold.unit === "m" ? threshold.min * 60 : threshold.min;
+    if (inSeconds < thresholdSec) {
+      warnings.push(`${flag}=${raw} (recommended \u2265${threshold.min}${threshold.unit})`);
+    }
+  }
+  const cacheMode = flags.get("--vfs-cache-mode");
+  if (!cacheMode) {
+    warnings.push("--vfs-cache-mode not set (recommended: full)");
+  } else if (cacheMode !== "full") {
+    warnings.push(`--vfs-cache-mode=${cacheMode} (recommended: full)`);
+  }
+  if (!flags.has("--log-file")) {
+    warnings.push("--log-file not set \u2014 no rclone error log configured");
+  }
+  if (warnings.length > 0) {
+    return check("warn", "rclone_flags", "rclone VFS flags", warnings.join("; "));
+  }
+  return check("pass", "rclone_flags", "rclone VFS flags", `PID ${pid}: all critical flags at safe values`);
+}
+function checkRcloneVersion(resolvedPath) {
+  if (!resolvedPath) {
+    return check("pass", "rclone_version", "rclone version", "No vault path \u2014 check skipped");
+  }
+  const fuse = detectFuseMount(resolvedPath);
+  if (!fuse) {
+    return check("pass", "rclone_version", "rclone version", "local disk \u2014 check skipped");
+  }
+  const ver = getRcloneVersion();
+  if (!ver) {
+    return check("warn", "rclone_version", "rclone version", "rclone not found on PATH \u2014 cannot verify version");
+  }
+  const min = MIN_RCLONE_VERSION;
+  const tooOld = ver.major < min.major || ver.major === min.major && ver.minor < min.minor || ver.major === min.major && ver.minor === min.minor && ver.patch < min.patch;
+  if (tooOld) {
+    return check(
+      "warn",
+      "rclone_version",
+      "rclone version",
+      `${ver.raw} \u2014 upgrade to \u2265v${min.major}.${min.minor}.${min.patch} for --vfs-write-wait support (current version may silently ignore this flag)`
+    );
+  }
+  return check("pass", "rclone_version", "rclone version", ver.raw);
+}
+function checkWriteTest(resolvedPath) {
+  if (!resolvedPath) {
+    return check("pass", "s3_write_test", "S3 write test", "No vault path \u2014 check skipped");
+  }
+  const fuse = detectFuseMount(resolvedPath);
+  if (!fuse) {
+    return check("pass", "s3_write_test", "S3 write test", "local disk \u2014 check skipped");
+  }
+  const conceptsDir = join24(resolvedPath, "concepts");
+  if (!existsSync7(conceptsDir)) {
+    return check("pass", "s3_write_test", "S3 write test", "no concepts/ dir to test \u2014 check skipped");
+  }
+  const result = writeTest(conceptsDir);
+  if (result.success) {
+    const totalMs = result.writeMs + result.readMs;
+    if (totalMs > 3e3) {
+      return check(
+        "warn",
+        "s3_write_test",
+        "S3 write test",
+        `write+read ${totalMs}ms (write ${result.writeMs}ms, read ${result.readMs}ms, ${result.size}B) \u2014 S3 mount is slow`
+      );
+    }
+    return check(
+      "pass",
+      "s3_write_test",
+      "S3 write test",
+      `write+read ${totalMs}ms (write ${result.writeMs}ms, read ${result.readMs}ms)`
+    );
+  }
+  return check(
+    "warn",
+    "s3_write_test",
+    "S3 write test",
+    `${result.error} \u2014 S3 mount may have a stale FUSE handle or write-back failure`
+  );
+}
+function checkVfsCacheHealth(resolvedPath) {
+  if (!resolvedPath) {
+    return check("pass", "vfs_cache_health", "VFS cache health", "No vault path \u2014 check skipped");
+  }
+  const fuse = detectFuseMount(resolvedPath);
+  if (!fuse) {
+    return check("pass", "vfs_cache_health", "VFS cache health", "local disk \u2014 check skipped");
+  }
+  const pid = findRcloneMountPid();
+  if (pid === null) {
+    return check("warn", "vfs_cache_health", "VFS cache health", "no rclone process found \u2014 cannot query VFS stats");
+  }
+  const flags = parseRcloneFlags(pid);
+  const rcAddr = flags.get("--rc-addr") || "127.0.0.1:5572";
+  if (!flags.has("--rc")) {
+    return check(
+      "info",
+      "vfs_cache_health",
+      "VFS cache health",
+      `rclone RC not enabled \u2014 add --rc --rc-addr ${rcAddr} to enable cache health monitoring`
+    );
+  }
+  const args = getRcloneArgs(pid);
+  const fs = extractRcloneFs(args) || "unknown:";
+  const stats = queryRcloneRC(rcAddr, fs || "unknown:");
+  if (!stats) {
+    return check(
+      "warn",
+      "vfs_cache_health",
+      "VFS cache health",
+      `RC endpoint ${rcAddr} unreachable \u2014 is rclone --rc enabled?`
+    );
+  }
+  if (stats.error) {
+    return check("warn", "vfs_cache_health", "VFS cache health", stats.error);
+  }
+  const issues = [];
+  if (stats.uploadsInProgress > 0) issues.push(`${stats.uploadsInProgress} upload(s) in progress`);
+  if (stats.uploadsQueued > 10) issues.push(`${stats.uploadsQueued} upload(s) queued (backlog)`);
+  if (stats.erroredFiles > 0) issues.push(`${stats.erroredFiles} errored file(s)`);
+  if (stats.outOfSpace) issues.push("cache disk full");
+  if (issues.length > 0) {
+    return check(
+      "warn",
+      "vfs_cache_health",
+      "VFS cache health",
+      `${stats.files} files, ${stats.bytesUsed} bytes \u2014 ${issues.join("; ")}`
+    );
+  }
+  return check(
+    "pass",
+    "vfs_cache_health",
+    "VFS cache health",
+    `${stats.files} files, ${(stats.bytesUsed / 1024 / 1024).toFixed(1)}MB \u2014 clean (0 errored, 0 pending)`
+  );
+}
 function findSkillMd(dir) {
   const results = [];
   let entries;
@@ -3954,9 +4287,9 @@ function findSkillMd(dir) {
   }
   for (const entry of entries) {
     if (entry.isFile() && entry.name === "SKILL.md") {
-      results.push(join23(dir, entry.name));
+      results.push(join24(dir, entry.name));
     } else if (entry.isDirectory()) {
-      results.push(...findSkillMd(join23(dir, entry.name)));
+      results.push(...findSkillMd(join24(dir, entry.name)));
     }
   }
   return results;
@@ -3970,7 +4303,7 @@ function findSkillNames(dir) {
     return results;
   }
   for (const entry of entries) {
-    if (entry.isDirectory() && existsSync6(join23(dir, entry.name, "SKILL.md"))) {
+    if (entry.isDirectory() && existsSync7(join24(dir, entry.name, "SKILL.md"))) {
       results.push(entry.name);
     }
   }
@@ -3997,6 +4330,10 @@ async function runDoctor(input) {
   checks.push(checkSyncLastPush(resolvedPath));
   checks.push(checkDotStoreClean(resolvedPath));
   checks.push(checkS3MountPerf(resolvedPath));
+  checks.push(checkRcloneFlagAudit(resolvedPath));
+  checks.push(checkRcloneVersion(resolvedPath));
+  checks.push(checkWriteTest(resolvedPath));
+  checks.push(checkVfsCacheHealth(resolvedPath));
   checks.push(checkSkillsInstalled(input.home, input.cwd));
   checks.push(checkDuplicateSkills(input.home));
   checks.push(checkNpmUpdate(input.home, input.currentVersion));
@@ -4024,8 +4361,8 @@ async function runDoctor(input) {
 }
 
 // src/commands/archive.ts
-import { rename as rename5, mkdir as mkdir8, readFile as readFile17, writeFile as writeFile9 } from "fs/promises";
-import { join as join24, dirname as dirname9 } from "path";
+import { rename as rename5, mkdir as mkdir8, readFile as readFile18, writeFile as writeFile9 } from "fs/promises";
+import { join as join25, dirname as dirname9 } from "path";
 async function runArchive(input) {
   const scan = await scanVault(input.vault);
   if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
@@ -4041,13 +4378,13 @@ async function runArchive(input) {
   }
   if (!relPath) return { exitCode: ExitCode.ARCHIVE_TARGET_NOT_FOUND, result: err("ARCHIVE_TARGET_NOT_FOUND", { page: input.page }) };
   if (relPath.startsWith("_archive/")) return { exitCode: ExitCode.ARCHIVE_ALREADY_ARCHIVED, result: err("ARCHIVE_ALREADY_ARCHIVED", { page: relPath }) };
-  const archivePath = join24("_archive", relPath).replace(/\\/g, "/");
-  await mkdir8(dirname9(join24(input.vault, archivePath)), { recursive: true });
+  const archivePath = join25("_archive", relPath).replace(/\\/g, "/");
+  await mkdir8(dirname9(join25(input.vault, archivePath)), { recursive: true });
   let indexUpdated = false;
   if (!isRaw) {
-    const indexPath = join24(input.vault, "index.md");
+    const indexPath = join25(input.vault, "index.md");
     try {
-      const idx = await readFile17(indexPath, "utf8");
+      const idx = await readFile18(indexPath, "utf8");
       const slug = relPath.replace(/\.md$/, "").split("/").pop();
       const originalLines = idx.split("\n");
       const filtered = originalLines.filter((l) => !l.includes(`[[${slug}]]`));
@@ -4059,7 +4396,7 @@ async function runArchive(input) {
       if (e instanceof Error && "code" in e && e.code !== "ENOENT") throw e;
     }
   }
-  await rename5(join24(input.vault, relPath), join24(input.vault, archivePath));
+  await rename5(join25(input.vault, relPath), join25(input.vault, archivePath));
   appendLastOp(input.vault, {
     operation: "archive",
     summary: `moved ${relPath} to ${archivePath}`,
@@ -4432,16 +4769,16 @@ ${newBody}`;
 }
 
 // src/commands/update.ts
-import { execSync as execSync2 } from "child_process";
+import { execSync as execSync3 } from "child_process";
 import { readFileSync as readFileSync7 } from "fs";
-import { join as join25 } from "path";
+import { join as join26 } from "path";
 function resolveGlobalSkillsRoot() {
   try {
-    const globalRoot = execSync2("npm root -g", {
+    const globalRoot = execSync3("npm root -g", {
       encoding: "utf8",
       timeout: 5e3
     }).trim();
-    return join25(globalRoot, "skillwiki", "skills");
+    return join26(globalRoot, "skillwiki", "skills");
   } catch {
     return null;
   }
@@ -4467,10 +4804,10 @@ async function runUpdate(input) {
   );
   const currentVersion = pkg2.version;
   const tag = input.distTag ?? "latest";
-  const target = join25(input.home, ".claude", "skills");
+  const target = join26(input.home, ".claude", "skills");
   let latest;
   try {
-    latest = execSync2(`npm view skillwiki@${tag} version`, {
+    latest = execSync3(`npm view skillwiki@${tag} version`, {
       encoding: "utf8",
       timeout: 15e3
     }).trim();
@@ -4500,7 +4837,7 @@ async function runUpdate(input) {
     };
   }
   try {
-    execSync2(`npm install -g skillwiki@${tag}`, {
+    execSync3(`npm install -g skillwiki@${tag}`, {
       stdio: "pipe",
       timeout: 6e4
     });
@@ -4536,17 +4873,17 @@ async function runUpdate(input) {
 }
 
 // src/commands/self-update.ts
-import { execSync as execSync3 } from "child_process";
-import { existsSync as existsSync7, readFileSync as readFileSync8 } from "fs";
-import { join as join26 } from "path";
+import { execSync as execSync4 } from "child_process";
+import { existsSync as existsSync8, readFileSync as readFileSync8 } from "fs";
+import { join as join27 } from "path";
 var DEFAULT_SOURCE_ROOT_SUFFIX = "/Desktop/code/llm-wiki";
 async function runSelfUpdate(input) {
   const currentVersion = JSON.parse(
     readFileSync8(new URL("../../package.json", import.meta.url), "utf8")
   ).version;
   const sourceRoot = input.sourceRoot ?? `${input.home}${DEFAULT_SOURCE_ROOT_SUFFIX}`;
-  const localPkgPath = join26(sourceRoot, "packages", "cli", "package.json");
-  const hasLocalSource = existsSync7(localPkgPath);
+  const localPkgPath = join27(sourceRoot, "packages", "cli", "package.json");
+  const hasLocalSource = existsSync8(localPkgPath);
   if (input.check) {
     let availableVersion = null;
     let source;
@@ -4560,7 +4897,7 @@ async function runSelfUpdate(input) {
     } else {
       source = "npm";
       try {
-        availableVersion = execSync3("npm view skillwiki@latest version", {
+        availableVersion = execSync4("npm view skillwiki@latest version", {
           encoding: "utf8",
           timeout: 15e3
         }).trim();
@@ -4586,7 +4923,7 @@ async function runSelfUpdate(input) {
   }
   if (hasLocalSource) {
     try {
-      execSync3("npm run build -w packages/cli", {
+      execSync4("npm run build -w packages/cli", {
         cwd: sourceRoot,
         stdio: "pipe",
         timeout: 6e4
@@ -4598,7 +4935,7 @@ async function runSelfUpdate(input) {
       };
     }
     try {
-      execSync3("npm link ./packages/cli", {
+      execSync4("npm link ./packages/cli", {
         cwd: sourceRoot,
         stdio: "pipe",
         timeout: 3e4
@@ -4630,7 +4967,7 @@ async function runSelfUpdate(input) {
   }
   let latestVersion;
   try {
-    latestVersion = execSync3("npm view skillwiki@latest version", {
+    latestVersion = execSync4("npm view skillwiki@latest version", {
       encoding: "utf8",
       timeout: 15e3
     }).trim();
@@ -4653,7 +4990,7 @@ async function runSelfUpdate(input) {
     };
   }
   try {
-    execSync3("npm install -g skillwiki@latest", {
+    execSync4("npm install -g skillwiki@latest", {
       stdio: "pipe",
       timeout: 6e4
     });
@@ -4677,10 +5014,10 @@ async function runSelfUpdate(input) {
 }
 
 // src/commands/transcripts.ts
-import { readdir as readdir5, stat as stat6, readFile as readFile18 } from "fs/promises";
-import { join as join27 } from "path";
+import { readdir as readdir5, stat as stat6, readFile as readFile19 } from "fs/promises";
+import { join as join28 } from "path";
 async function runTranscripts(input) {
-  const dir = join27(input.vault, "raw", "transcripts");
+  const dir = join28(input.vault, "raw", "transcripts");
   let entries;
   try {
     entries = await readdir5(dir, { withFileTypes: true });
@@ -4690,8 +5027,8 @@ async function runTranscripts(input) {
   const transcripts = [];
   for (const entry of entries) {
     if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
-    const filePath = join27(dir, entry.name);
-    const content = await readFile18(filePath, "utf8");
+    const filePath = join28(dir, entry.name);
+    const content = await readFile19(filePath, "utf8");
     const fm = extractFrontmatter(content);
     if (!fm.ok) continue;
     const ingested = typeof fm.data.ingested === "string" ? fm.data.ingested : "";
@@ -4708,12 +5045,12 @@ async function runTranscripts(input) {
 }
 
 // src/commands/project-index.ts
-import { readdir as readdir6, readFile as readFile19, writeFile as writeFile10, mkdir as mkdir9 } from "fs/promises";
-import { join as join28, dirname as dirname10 } from "path";
+import { readdir as readdir6, readFile as readFile20, writeFile as writeFile10, mkdir as mkdir9 } from "fs/promises";
+import { join as join29, dirname as dirname10 } from "path";
 var LAYER2_DIRS = ["entities", "concepts", "comparisons", "queries", "meta"];
 async function runProjectIndex(input) {
   const slug = input.slug;
-  const projectDir = join28(input.vault, "projects", slug);
+  const projectDir = join29(input.vault, "projects", slug);
   try {
     await readdir6(projectDir);
   } catch {
@@ -4724,15 +5061,15 @@ async function runProjectIndex(input) {
   }
   const wikilinkPattern = `[[${slug}]]`;
   const entries = [];
-  const compoundDir = join28(input.vault, "projects", slug, "compound");
+  const compoundDir = join29(input.vault, "projects", slug, "compound");
   try {
     const compoundFiles = await readdir6(compoundDir, { withFileTypes: true });
     for (const entry of compoundFiles) {
       if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
-      const filePath = join28(compoundDir, entry.name);
+      const filePath = join29(compoundDir, entry.name);
       let text;
       try {
-        text = await readFile19(filePath, "utf8");
+        text = await readFile20(filePath, "utf8");
       } catch {
         continue;
       }
@@ -4749,16 +5086,16 @@ async function runProjectIndex(input) {
   for (const dir of LAYER2_DIRS) {
     let files;
     try {
-      files = await readdir6(join28(input.vault, dir), { withFileTypes: true });
+      files = await readdir6(join29(input.vault, dir), { withFileTypes: true });
     } catch {
       continue;
     }
     for (const entry of files) {
       if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
-      const filePath = join28(input.vault, dir, entry.name);
+      const filePath = join29(input.vault, dir, entry.name);
       let text;
       try {
-        text = await readFile19(filePath, "utf8");
+        text = await readFile20(filePath, "utf8");
       } catch {
         continue;
       }
@@ -4779,11 +5116,11 @@ async function runProjectIndex(input) {
     const tb = typeOrder[b.type] ?? 99;
     return ta !== tb ? ta - tb : a.title.localeCompare(b.title);
   });
-  const indexPath = join28(projectDir, "knowledge.md");
+  const indexPath = join29(projectDir, "knowledge.md");
   let existing = false;
   let stale = false;
   try {
-    const existingText = await readFile19(indexPath, "utf8");
+    const existingText = await readFile20(indexPath, "utf8");
     existing = true;
     const existingEntries = existingText.split("\n").filter((l) => l.startsWith("- [["));
     const existingPages = new Set(existingEntries.map((l) => {
@@ -4853,9 +5190,9 @@ ${entries.map((e) => `  ${e.type}: [[${e.page.replace(/\.md$/, "")}]] \u2014 ${e
 
 // src/commands/compound.ts
 import { writeFile as writeFile11, mkdir as mkdir10, readdir as readdir7, unlink as unlink3 } from "fs/promises";
-import { join as join29 } from "path";
-import { existsSync as existsSync8 } from "fs";
-import { readFile as readFile20 } from "fs/promises";
+import { join as join30 } from "path";
+import { existsSync as existsSync9 } from "fs";
+import { readFile as readFile21 } from "fs/promises";
 var RETRO_HEADING_RE = /^## \[(\d{4}-\d{2}-\d{2})(?:\s+[^\]]+)?\] retro \| loop cycle(?: (\d+))?: (.+)$/;
 var FIELD_RE = {
   improve: /^-\s+\*?\*?Improve:?\*?\*?\s*(.+)$/m,
@@ -4953,17 +5290,17 @@ function extractRetroFields(date, cycleName, block) {
   };
 }
 async function runCompound(input) {
-  const logPath = join29(input.vault, "log.md");
+  const logPath = join30(input.vault, "log.md");
   let logText;
   try {
-    logText = await readFile20(logPath, "utf8");
+    logText = await readFile21(logPath, "utf8");
   } catch {
     return { exitCode: ExitCode.FILE_NOT_FOUND, result: err("FILE_NOT_FOUND", { path: logPath }) };
   }
   const entries = parseRetroEntries(logText);
   const promoted = [];
   const skipped = [];
-  const compoundDir = join29(input.vault, "projects", input.project, "compound");
+  const compoundDir = join30(input.vault, "projects", input.project, "compound");
   for (const entry of entries) {
     const generalizeValue = entry.generalize.trim();
     if (!/^yes/i.test(generalizeValue)) {
@@ -4971,8 +5308,8 @@ async function runCompound(input) {
       continue;
     }
     const slug = slugify(entry.cycleName);
-    const compoundPath = join29(compoundDir, `${slug}.md`);
-    if (existsSync8(compoundPath)) {
+    const compoundPath = join30(compoundDir, `${slug}.md`);
+    if (existsSync9(compoundPath)) {
       skipped.push(entry.date);
       continue;
     }
@@ -5010,7 +5347,7 @@ async function runCompound(input) {
     ].join("\n");
     const content = frontmatter + "\n" + body;
     if (!input.dryRun) {
-      if (!existsSync8(compoundDir)) {
+      if (!existsSync9(compoundDir)) {
         await mkdir10(compoundDir, { recursive: true });
       }
       await writeFile11(compoundPath, content, "utf8");
@@ -5032,16 +5369,16 @@ async function runCompound(input) {
   };
 }
 async function runCompoundDelete(input) {
-  const projectDir = join29(input.vault, "projects", input.project);
-  if (!existsSync8(projectDir)) {
+  const projectDir = join30(input.vault, "projects", input.project);
+  if (!existsSync9(projectDir)) {
     return {
       exitCode: ExitCode.PROJECT_NOT_FOUND,
       result: err("PROJECT_NOT_FOUND", { slug: input.project, path: projectDir })
     };
   }
   const entryName = input.entry.replace(/\.md$/, "");
-  const compoundPath = join29(projectDir, "compound", `${entryName}.md`);
-  if (!existsSync8(compoundPath)) {
+  const compoundPath = join30(projectDir, "compound", `${entryName}.md`);
+  if (!existsSync9(compoundPath)) {
     return {
       exitCode: ExitCode.FILE_NOT_FOUND,
       result: err("FILE_NOT_FOUND", { path: compoundPath })
@@ -5074,8 +5411,8 @@ knowledge.md regenerated`
   };
 }
 async function runCompoundList(input) {
-  const compoundDir = join29(input.vault, "projects", input.project, "compound");
-  if (!existsSync8(compoundDir)) {
+  const compoundDir = join30(input.vault, "projects", input.project, "compound");
+  if (!existsSync9(compoundDir)) {
     return {
       exitCode: ExitCode.OK,
       result: ok({
@@ -5105,10 +5442,10 @@ could not read compound directory`
   const entries = [];
   for (const dirent of dirents) {
     if (!dirent.isFile() || !dirent.name.endsWith(".md")) continue;
-    const filePath = join29(compoundDir, dirent.name);
+    const filePath = join30(compoundDir, dirent.name);
     let text;
     try {
-      text = await readFile20(filePath, "utf8");
+      text = await readFile21(filePath, "utf8");
     } catch {
       continue;
     }
@@ -5138,8 +5475,8 @@ no compound entries found`;
 
 // src/commands/observe.ts
 import { mkdir as mkdir11, writeFile as writeFile12 } from "fs/promises";
-import { existsSync as existsSync9, statSync as statSync3 } from "fs";
-import { join as join30 } from "path";
+import { existsSync as existsSync10, statSync as statSync3 } from "fs";
+import { join as join31 } from "path";
 import { createHash as createHash4 } from "crypto";
 var ALLOWED_KINDS = /* @__PURE__ */ new Set(["note", "bug", "task", "idea", "session-log"]);
 function slugify2(text) {
@@ -5162,13 +5499,13 @@ async function runObserve(input) {
       result: err("SCHEME_REJECTED", { message: "Text must not be empty" })
     };
   }
-  if (!existsSync9(input.vault) || !statSync3(input.vault).isDirectory()) {
+  if (!existsSync10(input.vault) || !statSync3(input.vault).isDirectory()) {
     return {
       exitCode: ExitCode.VAULT_PATH_INVALID,
       result: err("VAULT_PATH_INVALID", { path: input.vault })
     };
   }
-  const transcriptsDir = join30(input.vault, "raw", "transcripts");
+  const transcriptsDir = join31(input.vault, "raw", "transcripts");
   try {
     await mkdir11(transcriptsDir, { recursive: true });
   } catch {
@@ -5180,7 +5517,7 @@ async function runObserve(input) {
   const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   const slug = slugify2(input.text);
   const fileName = `${today}-observation-${slug}.md`;
-  const filePath = join30(transcriptsDir, fileName);
+  const filePath = join31(transcriptsDir, fileName);
   const body = `
 ${input.text.trim()}
 `;
@@ -5220,8 +5557,8 @@ ${input.text.trim()}
 }
 
 // src/commands/ingest.ts
-import { readFile as readFile21, writeFile as writeFile13, mkdir as mkdir12 } from "fs/promises";
-import { join as join31 } from "path";
+import { readFile as readFile22, writeFile as writeFile13, mkdir as mkdir12 } from "fs/promises";
+import { join as join32 } from "path";
 import { createHash as createHash5 } from "crypto";
 var ALLOWED_TYPES = /* @__PURE__ */ new Set(["entity", "concept", "comparison", "query"]);
 var TYPE_DIR = {
@@ -5380,7 +5717,7 @@ async function runIngest(input) {
     sourceContent = fetchResult.data.body;
   } else {
     try {
-      sourceContent = await readFile21(input.source, "utf8");
+      sourceContent = await readFile22(input.source, "utf8");
     } catch {
       return {
         exitCode: ExitCode.FILE_NOT_FOUND,
@@ -5395,8 +5732,8 @@ async function runIngest(input) {
   const rawRelPath = `raw/articles/${slug}.md`;
   const typedDir = TYPE_DIR[input.type] ?? `${input.type}s`;
   const typedRelPath = `${typedDir}/${slug}.md`;
-  const rawAbsPath = join31(input.vault, rawRelPath);
-  const typedAbsPath = join31(input.vault, typedRelPath);
+  const rawAbsPath = join32(input.vault, rawRelPath);
+  const typedAbsPath = join32(input.vault, typedRelPath);
   const rawContent = buildRawContent(sourceUrl, today, sha256, sourceContent);
   const typedContent = buildTypedContent(
     input.title,
@@ -5459,7 +5796,7 @@ async function runIngest(input) {
     };
   }
   try {
-    await mkdir12(join31(input.vault, "raw", "articles"), { recursive: true });
+    await mkdir12(join32(input.vault, "raw", "articles"), { recursive: true });
     await writeFile13(rawAbsPath, rawContent, "utf8");
   } catch (e) {
     return {
@@ -5468,7 +5805,7 @@ async function runIngest(input) {
     };
   }
   try {
-    await mkdir12(join31(input.vault, typedDir), { recursive: true });
+    await mkdir12(join32(input.vault, typedDir), { recursive: true });
     await writeFile13(typedAbsPath, typedContent, "utf8");
   } catch (e) {
     return {
@@ -5647,11 +5984,105 @@ ${body}`;
 }
 
 // src/commands/sync.ts
-import { existsSync as existsSync10 } from "fs";
-import { join as join32 } from "path";
+import { existsSync as existsSync12 } from "fs";
+import { join as join34 } from "path";
+
+// src/utils/sync-lock.ts
+import { existsSync as existsSync11, mkdirSync as mkdirSync3, readFileSync as readFileSync9, renameSync, unlinkSync as unlinkSync4, writeFileSync as writeFileSync5 } from "fs";
+import { join as join33 } from "path";
+import { createHash as createHash6 } from "crypto";
+function getSessionId() {
+  if (process.env.CLAUDE_SESSION_ID) return process.env.CLAUDE_SESSION_ID;
+  if (process.env.SKILLWIKI_SESSION_ID) return process.env.SKILLWIKI_SESSION_ID;
+  return process.pid.toString();
+}
+function lockPath(vault) {
+  return join33(vault, ".skillwiki", "sync.lock");
+}
+function readLock(vault) {
+  const path = lockPath(vault);
+  if (!existsSync11(path)) return null;
+  try {
+    const raw = readFileSync9(path, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function isStale(lock, now) {
+  const nowTime = (now ?? /* @__PURE__ */ new Date()).getTime();
+  const expiresTime = new Date(lock.expires).getTime();
+  return expiresTime < nowTime;
+}
+function acquireLock(vault, opts = {}) {
+  const path = lockPath(vault);
+  const dir = join33(vault, ".skillwiki");
+  if (!existsSync11(dir)) {
+    mkdirSync3(dir, { recursive: true });
+  }
+  const sessionId = opts.sessionId ?? getSessionId();
+  const summary = opts.summary ?? "skillwiki sync";
+  const ttlMinutes = opts.ttlMinutes ?? 30;
+  const force = opts.force ?? false;
+  const now = /* @__PURE__ */ new Date();
+  const acquired = now.toISOString();
+  const expires = new Date(now.getTime() + ttlMinutes * 60 * 1e3).toISOString();
+  const lock = {
+    session_id: sessionId,
+    pid: process.pid,
+    cwd: process.cwd(),
+    summary,
+    acquired,
+    expires
+  };
+  try {
+    const content = JSON.stringify(lock, null, 2) + "\n";
+    writeFileSync5(path, content, { flag: "wx" });
+    return { ok: true, lock };
+  } catch (e) {
+    const err3 = e;
+    if (err3.code !== "EEXIST") throw err3;
+  }
+  const existing = readLock(vault);
+  if (!existing) {
+    writeLockedFile(path, lock);
+    return { ok: true, lock };
+  }
+  if (force || isStale(existing)) {
+    writeLockedFile(path, lock);
+    return { ok: true, lock };
+  }
+  return { ok: false, held: existing };
+}
+function writeLockedFile(path, lock) {
+  const tmp = path + ".tmp";
+  const content = JSON.stringify(lock, null, 2) + "\n";
+  writeFileSync5(tmp, content);
+  renameSync(tmp, path);
+}
+function releaseLock(vault, opts = {}) {
+  const path = lockPath(vault);
+  if (!existsSync11(path)) {
+    return { released: false };
+  }
+  const sessionId = opts.sessionId ?? getSessionId();
+  const existing = readLock(vault);
+  if (!existing || existing.session_id !== sessionId) {
+    return { released: false };
+  }
+  try {
+    unlinkSync4(path);
+    return { released: true };
+  } catch {
+    return { released: false };
+  }
+}
+
+// src/commands/sync.ts
 function runSyncStatus(input) {
   const vault = input.vault;
-  if (!existsSync10(join32(vault, ".git"))) {
+  const includeStashes = input.includeStashes ?? false;
+  if (!existsSync12(join34(vault, ".git"))) {
     return {
       exitCode: ExitCode.VAULT_PATH_INVALID,
       result: ok({
@@ -5705,22 +6136,30 @@ function runSyncStatus(input) {
     `last_commit: ${last_commit}`
   ];
   const exitCode = status === "clean" ? ExitCode.OK : ExitCode.LINT_HAS_WARNINGS;
+  let stashes;
+  if (includeStashes) {
+    stashes = enumerateStashes(vault);
+  }
+  const output = {
+    is_git_repo: true,
+    dirty,
+    ahead,
+    behind,
+    last_commit,
+    status,
+    humanHint: hintLines.join("\n")
+  };
+  if (stashes !== void 0) {
+    output.stashes = stashes;
+  }
   return {
     exitCode,
-    result: ok({
-      is_git_repo: true,
-      dirty,
-      ahead,
-      behind,
-      last_commit,
-      status,
-      humanHint: hintLines.join("\n")
-    })
+    result: ok(output)
   };
 }
 async function runSyncPush(input) {
   const vault = input.vault;
-  if (!existsSync10(join32(vault, ".git"))) {
+  if (!existsSync12(join34(vault, ".git"))) {
     return {
       exitCode: ExitCode.VAULT_PATH_INVALID,
       result: err("NOT_A_GIT_REPO", { path: vault })
@@ -5803,9 +6242,28 @@ async function runSyncPush(input) {
     })
   };
 }
+function enumerateStashes(vault) {
+  const output = git(vault, ["log", "--format=%gd%x09%s%x09%ct", "-g", "stash"]);
+  if (!output) return [];
+  const now = Date.now();
+  const stashes = [];
+  const lines = output.split("\n").filter((l) => l.trim().length > 0);
+  for (const line of lines) {
+    const parts = line.split("	");
+    if (parts.length < 3) continue;
+    const ref = parts[0];
+    const message = parts[1];
+    const ctStr = parts[2];
+    const ct = parseInt(ctStr, 10);
+    if (isNaN(ct)) continue;
+    const age_minutes = Math.floor((now - ct * 1e3) / (60 * 1e3));
+    stashes.push({ ref, message, age_minutes });
+  }
+  return stashes;
+}
 async function runSyncPull(input) {
   const vault = input.vault;
-  if (!existsSync10(join32(vault, ".git"))) {
+  if (!existsSync12(join34(vault, ".git"))) {
     return {
       exitCode: ExitCode.VAULT_PATH_INVALID,
       result: err("NOT_A_GIT_REPO", { path: vault })
@@ -5878,10 +6336,106 @@ async function runSyncPull(input) {
     })
   };
 }
+function runSyncPeers(input) {
+  const vault = input.vault;
+  const locks = [];
+  const existingLock = readLock(vault);
+  if (existingLock) {
+    const self = existingLock.session_id === getSessionId();
+    locks.push({ ...existingLock, is_self: self });
+  }
+  const allStashes = enumerateStashes(vault);
+  const stashes = [];
+  for (const stash of allStashes) {
+    let actualMessage = stash.message;
+    const prefixMatch = stash.message.match(/^On [^:]+:\s*(.*)/);
+    if (prefixMatch) {
+      actualMessage = prefixMatch[1];
+    }
+    const match = actualMessage.match(/^wiki-sync:([^:]+):([^:]+):(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z):(.*)$/);
+    if (!match) continue;
+    const session_id = match[1];
+    const cwd_hash = match[2];
+    const timestamp = match[3];
+    const summary = match[4];
+    stashes.push({
+      ref: stash.ref,
+      session_id,
+      cwd_hash,
+      timestamp,
+      summary,
+      age_minutes: stash.age_minutes
+    });
+  }
+  const hintParts = [];
+  if (locks.length > 0) hintParts.push(`${locks.length} lock(s)`);
+  if (stashes.length > 0) hintParts.push(`${stashes.length} wiki-sync stash(es)`);
+  const humanHint = hintParts.length > 0 ? hintParts.join(", ") : "no peers detected";
+  return {
+    exitCode: ExitCode.OK,
+    result: ok({
+      locks,
+      stashes,
+      humanHint
+    })
+  };
+}
+function runSyncLock(input) {
+  const vault = input.vault;
+  if (!existsSync12(vault)) {
+    return {
+      exitCode: ExitCode.VAULT_PATH_INVALID,
+      result: err("VAULT_PATH_INVALID", { path: vault })
+    };
+  }
+  const result = acquireLock(vault, {
+    sessionId: input.sessionId,
+    summary: input.summary,
+    ttlMinutes: input.ttlMinutes,
+    force: input.force
+  });
+  if (result.ok) {
+    return {
+      exitCode: ExitCode.OK,
+      result: ok({
+        acquired: true,
+        lock: result.lock,
+        humanHint: `lock acquired for ${result.lock.summary} (expires ${result.lock.expires})`
+      })
+    };
+  } else {
+    return {
+      exitCode: ExitCode.SYNC_LOCK_HELD,
+      result: ok({
+        acquired: false,
+        lock: result.held,
+        held_by: result.held,
+        humanHint: `lock held by session ${result.held.session_id} (PID ${result.held.pid}) for ${result.held.summary}`
+      })
+    };
+  }
+}
+function runSyncUnlock(input) {
+  const vault = input.vault;
+  if (!existsSync12(vault)) {
+    return {
+      exitCode: ExitCode.VAULT_PATH_INVALID,
+      result: err("VAULT_PATH_INVALID", { path: vault })
+    };
+  }
+  const result = releaseLock(vault, { sessionId: input.sessionId });
+  return {
+    exitCode: ExitCode.OK,
+    result: ok({
+      released: result.released,
+      humanHint: result.released ? "lock released" : "lock not held by this session (no-op)"
+    })
+  };
+}
 
 // src/commands/backup.ts
-import { statSync as statSync4, readdirSync as readdirSync2, readFileSync as readFileSync9, mkdirSync as mkdirSync3, writeFileSync as writeFileSync4 } from "fs";
-import { join as join33, relative as relative3, dirname as dirname11 } from "path";
+import { statSync as statSync4, readdirSync as readdirSync2, readFileSync as readFileSync10, mkdirSync as mkdirSync4, writeFileSync as writeFileSync6 } from "fs";
+import { join as join35, relative as relative3, dirname as dirname11 } from "path";
 import { PutObjectCommand, HeadObjectCommand, ListObjectsV2Command, GetObjectCommand, DeleteObjectsCommand } from "@aws-sdk/client-s3";
 
 // src/utils/s3-client.ts
@@ -5905,7 +6459,7 @@ var SKIP_DIRS = /* @__PURE__ */ new Set([".git", ".obsidian", "_archive", "node_
 function* walkMarkdown(dir, base) {
   for (const entry of readdirSync2(dir, { withFileTypes: true })) {
     if (SKIP_DIRS.has(entry.name)) continue;
-    const full = join33(dir, entry.name);
+    const full = join35(dir, entry.name);
     if (entry.isDirectory()) {
       yield* walkMarkdown(full, base);
     } else if (entry.name.endsWith(".md")) {
@@ -5928,7 +6482,7 @@ async function runBackupSync(input) {
   let failed = 0;
   const files = [...walkMarkdown(input.vault, input.vault)];
   for (const relPath of files) {
-    const absPath = join33(input.vault, relPath);
+    const absPath = join35(input.vault, relPath);
     const localStat = statSync4(absPath);
     let needsUpload = true;
     try {
@@ -5947,7 +6501,7 @@ async function runBackupSync(input) {
       continue;
     }
     try {
-      const body = readFileSync9(absPath);
+      const body = readFileSync10(absPath);
       await client.send(new PutObjectCommand({ Bucket: input.bucket, Key: relPath, Body: body }));
       uploaded++;
     } catch {
@@ -6004,7 +6558,7 @@ async function runBackupRestore(input) {
     const objects = list.Contents ?? [];
     for (const obj of objects) {
       if (!obj.Key) continue;
-      const localPath = join33(target, obj.Key);
+      const localPath = join35(target, obj.Key);
       try {
         const localStat = statSync4(localPath);
         if (obj.LastModified && localStat.mtime > obj.LastModified) {
@@ -6017,8 +6571,8 @@ async function runBackupRestore(input) {
         const resp = await client.send(new GetObjectCommand({ Bucket: input.bucket, Key: obj.Key }));
         const body = await resp.Body?.transformToByteArray();
         if (body) {
-          mkdirSync3(dirname11(localPath), { recursive: true });
-          writeFileSync4(localPath, Buffer.from(body));
+          mkdirSync4(dirname11(localPath), { recursive: true });
+          writeFileSync6(localPath, Buffer.from(body));
           downloaded++;
         }
       } catch {
@@ -6050,11 +6604,11 @@ async function runBackupRestore(input) {
 }
 
 // src/commands/status.ts
-import { existsSync as existsSync11, statSync as statSync5 } from "fs";
-import { readFile as readFile22 } from "fs/promises";
-import { join as join34 } from "path";
+import { existsSync as existsSync13, statSync as statSync5 } from "fs";
+import { readFile as readFile23 } from "fs/promises";
+import { join as join36 } from "path";
 async function runStatus(input) {
-  if (!existsSync11(input.vault)) {
+  if (!existsSync13(input.vault)) {
     return { exitCode: ExitCode.VAULT_PATH_INVALID, result: err("VAULT_PATH_INVALID", { vault: input.vault }) };
   }
   const scan = await scanVault(input.vault);
@@ -6079,7 +6633,7 @@ async function runStatus(input) {
   const compound = scan.data.compound.length;
   let schemaVersion = "v1";
   try {
-    const schemaContent = await readFile22(join34(input.vault, "SCHEMA.md"), "utf8");
+    const schemaContent = await readFile23(join36(input.vault, "SCHEMA.md"), "utf8");
     const versionMatch = schemaContent.match(/version:\s*["']?([^"'\s\n]+)/i);
     if (versionMatch) schemaVersion = versionMatch[1];
   } catch {
@@ -6140,7 +6694,7 @@ async function runStatus(input) {
 
 // src/commands/seed.ts
 import { mkdir as mkdir13, writeFile as writeFile14, stat as stat7 } from "fs/promises";
-import { join as join35 } from "path";
+import { join as join37 } from "path";
 var TODAY = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
 var EXAMPLE_PAGES = {
   "entities/example-project.md": `---
@@ -6209,29 +6763,29 @@ Real sources are immutable after ingestion \u2014 never edit them.
 `;
 async function runSeed(input) {
   try {
-    await stat7(join35(input.vault, "SCHEMA.md"));
+    await stat7(join37(input.vault, "SCHEMA.md"));
   } catch {
     return { exitCode: ExitCode.VAULT_PATH_INVALID, result: err("VAULT_PATH_INVALID", { root: input.vault, reason: "SCHEMA.md missing \u2014 run `skillwiki init` first" }) };
   }
   const created = [];
   const skipped = [];
   for (const [relPath, content] of Object.entries(EXAMPLE_PAGES)) {
-    const absPath = join35(input.vault, relPath);
+    const absPath = join37(input.vault, relPath);
     try {
       await stat7(absPath);
       skipped.push(relPath);
     } catch {
-      await mkdir13(join35(absPath, ".."), { recursive: true });
+      await mkdir13(join37(absPath, ".."), { recursive: true });
       await writeFile14(absPath, content, "utf8");
       created.push(relPath);
     }
   }
-  const rawPath = join35(input.vault, "raw", "articles", "example-source.md");
+  const rawPath = join37(input.vault, "raw", "articles", "example-source.md");
   try {
     await stat7(rawPath);
     skipped.push("raw/articles/example-source.md");
   } catch {
-    await mkdir13(join35(rawPath, ".."), { recursive: true });
+    await mkdir13(join37(rawPath, ".."), { recursive: true });
     await writeFile14(rawPath, EXAMPLE_RAW, "utf8");
     created.push("raw/articles/example-source.md");
   }
@@ -6254,9 +6808,9 @@ async function runSeed(input) {
 }
 
 // src/commands/canvas.ts
-import { readFile as readFile23, writeFile as writeFile15 } from "fs/promises";
-import { existsSync as existsSync12 } from "fs";
-import { join as join36 } from "path";
+import { readFile as readFile24, writeFile as writeFile15 } from "fs/promises";
+import { existsSync as existsSync14 } from "fs";
+import { join as join38 } from "path";
 var NODE_WIDTH = 240;
 var NODE_HEIGHT = 60;
 var COLUMN_SPACING = 400;
@@ -6334,8 +6888,8 @@ function buildCanvasEdges(adjacency) {
   return edges;
 }
 async function runCanvasGenerate(input) {
-  const graphPath = input.graphPath ?? join36(input.vault, ".skillwiki", "graph.json");
-  if (!existsSync12(graphPath)) {
+  const graphPath = input.graphPath ?? join38(input.vault, ".skillwiki", "graph.json");
+  if (!existsSync14(graphPath)) {
     return {
       exitCode: ExitCode.FILE_NOT_FOUND,
       result: err("FILE_NOT_FOUND", {
@@ -6346,7 +6900,7 @@ async function runCanvasGenerate(input) {
   }
   let raw;
   try {
-    raw = await readFile23(graphPath, "utf8");
+    raw = await readFile24(graphPath, "utf8");
   } catch (e) {
     return {
       exitCode: ExitCode.FILE_NOT_FOUND,
@@ -6372,7 +6926,7 @@ async function runCanvasGenerate(input) {
   const nodes = buildCanvasNodes(paths);
   const edges = buildCanvasEdges(graph.adjacency);
   const canvas = { nodes, edges };
-  const outPath = join36(input.vault, "vault-graph.canvas");
+  const outPath = join38(input.vault, "vault-graph.canvas");
   try {
     await writeFile15(outPath, JSON.stringify(canvas, null, 2));
   } catch (e) {
@@ -6394,8 +6948,8 @@ written: ${outPath}`
 }
 
 // src/commands/query.ts
-import { readFile as readFile24, stat as stat8 } from "fs/promises";
-import { join as join37 } from "path";
+import { readFile as readFile25, stat as stat8 } from "fs/promises";
+import { join as join39 } from "path";
 var W_KEYWORD = 2;
 var W_SOURCE_OVERLAP = 4;
 var W_WIKILINK = 3;
@@ -6516,7 +7070,7 @@ function computeKeywordScore(terms, title, tags, body) {
   return score;
 }
 async function loadOrBuildGraph(vault) {
-  const graphPath = join37(vault, ".skillwiki", "graph.json");
+  const graphPath = join39(vault, ".skillwiki", "graph.json");
   let needsBuild = false;
   try {
     const fileStat = await stat8(graphPath);
@@ -6530,7 +7084,7 @@ async function loadOrBuildGraph(vault) {
     if (buildResult.exitCode !== 0) return null;
   }
   try {
-    const raw = await readFile24(graphPath, "utf8");
+    const raw = await readFile25(graphPath, "utf8");
     return JSON.parse(raw);
   } catch {
     return null;
@@ -6538,14 +7092,14 @@ async function loadOrBuildGraph(vault) {
 }
 
 // src/utils/auto-commit.ts
-import { existsSync as existsSync13 } from "fs";
-import { join as join38 } from "path";
+import { existsSync as existsSync15 } from "fs";
+import { join as join40 } from "path";
 async function postCommit(vault, exitCode) {
   if (exitCode !== 0) return;
   const home = process.env.HOME ?? "";
   const dotenv = await parseDotenvFile(configPath(home));
   if (dotenv["AUTO_COMMIT"] === "false") return;
-  if (!existsSync13(join38(vault, ".git"))) return;
+  if (!existsSync15(join40(vault, ".git"))) return;
   const lastOps = readLastOp(vault);
   if (lastOps.length === 0) return;
   const porcelain = git(vault, ["status", "--porcelain"]);
@@ -6574,7 +7128,7 @@ async function postCommit(vault, exitCode) {
 }
 
 // src/cli.ts
-var pkg = JSON.parse(readFileSync10(new URL("../package.json", import.meta.url), "utf8"));
+var pkg = JSON.parse(readFileSync11(new URL("../package.json", import.meta.url), "utf8"));
 var program = new Command2();
 program.name("skillwiki").description("Deterministic helpers for CodeWiki skills").version(pkg.version);
 program.option("--human", "render terminal-readable output instead of JSON");
@@ -6596,7 +7150,7 @@ program.command("validate <file>").description("validate vault page frontmatter
   emit(await runValidate({ file, apply: !!opts.apply, vault }), vault);
 });
 program.command("graph").description("graph subcommands").command("build <vault>").option("--out <path>", "graph output path (default: <vault>/.skillwiki/graph.json)").option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
-  const out = opts.out ?? join39(vault, ".skillwiki", "graph.json");
+  const out = opts.out ?? join41(vault, ".skillwiki", "graph.json");
   emit(await runGraphBuild({ vault, out }), vault);
 });
 var canvasCmd = program.command("canvas").description("manage Obsidian canvas files");
@@ -6821,10 +7375,10 @@ program.command("tag-sync [vault]").description("mirror frontmatter enum values
   else emit(await runTagSync({ vault: v.vault, dryRun: !!opts.dryRun }), v.vault);
 });
 var syncCmd = program.command("sync").description("manage vault sync");
-syncCmd.command("status [vault]").description("check vault git sync status").option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
+syncCmd.command("status [vault]").description("check vault git sync status").option("--wiki <name>", "wiki profile name").option("--include-stashes", "enumerate all stashes in output", false).action(async (vault, opts) => {
   const v = await resolveVaultArg(vault, opts.wiki);
   if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
-  else emit(runSyncStatus({ vault: v.vault }));
+  else emit(runSyncStatus({ vault: v.vault, includeStashes: !!opts.includeStashes }));
 });
 syncCmd.command("push [vault]").description("lint, commit, and push vault changes to remote").option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
   const v = await resolveVaultArg(vault, opts.wiki);
@@ -6836,6 +7390,24 @@ syncCmd.command("pull [vault]").description("pull remote vault changes and lint"
   if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
   else emit(await runSyncPull({ vault: v.vault }), v.vault);
 });
+syncCmd.command("lock [vault]").description("acquire advisory lock on vault").option("--summary <text>", "lock description", "skillwiki sync").option("--ttl-minutes <n>", "lock time-to-live in minutes", "30").option("--force", "overwrite existing lock", false).option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
+  const v = await resolveVaultArg(vault, opts.wiki);
+  if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
+  else {
+    const ttl = parseInt(opts.ttlMinutes, 10) || 30;
+    emit(runSyncLock({ vault: v.vault, summary: opts.summary, ttlMinutes: ttl, force: !!opts.force }));
+  }
+});
+syncCmd.command("unlock [vault]").description("release advisory lock on vault").option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
+  const v = await resolveVaultArg(vault, opts.wiki);
+  if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
+  else emit(runSyncUnlock({ vault: v.vault }));
+});
+syncCmd.command("peers [vault]").description("list active locks and recent wiki-sync stashes").option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
+  const v = await resolveVaultArg(vault, opts.wiki);
+  if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
+  else emit(runSyncPeers({ vault: v.vault }));
+});
 var backupCmd = program.command("backup").description("manage S3-compatible remote backup");
 backupCmd.command("sync [vault]").description("sync vault to S3-compatible remote backup").option("--dry-run", "list actions without executing").option("--bucket <name>", "S3 bucket name").option("--endpoint <url>", "S3 endpoint URL").option("--region <region>", "S3 region", "us-east-1").option("--prune", "delete orphaned S3 objects not in vault", false).option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
   const v = await resolveVaultArg(vault, opts.wiki);