skillwiki 0.5.5 → 0.6.1-beta.1

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 join40 } 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
@@ -2779,7 +2780,7 @@ function extractSourceEntries(rawFm) {
   return entries;
 }
 var ERROR_ORDER = ["broken_wikilinks", "invalid_frontmatter", "raw_dedup", "broken_sources", "tag_not_in_taxonomy"];
-var WARNING_ORDER = ["raw_body_duplicate", "raw_subdirectory_duplicate", "index_incomplete", "index_link_format", "stale_page", "page_too_large", "log_rotate_needed", "orphans", "compound_refs", "legacy_citation_style", "orphaned_citations", "duplicate_frontmatter", "work_item_health", "orphaned_project_pages", "missing_overview", "missing_diagram"];
+var WARNING_ORDER = ["raw_body_duplicate", "raw_subdirectory_duplicate", "file_source_url", "index_incomplete", "index_link_format", "stale_page", "page_too_large", "log_rotate_needed", "orphans", "compound_refs", "legacy_citation_style", "orphaned_citations", "duplicate_frontmatter", "work_item_health", "orphaned_project_pages", "missing_overview", "missing_diagram"];
 var INFO_ORDER = ["bridges", "page_structure", "topic_map_recommended", "frontmatter_wikilink", "wikilink_citation", "missing_tldr", "stale_sections", "cli_refs"];
 async function runLint(input) {
   const buckets = {};
@@ -2864,6 +2865,16 @@ async function runLint(input) {
     if (subDirDupes.length > 0) {
       buckets.raw_subdirectory_duplicate = subDirDupes;
     }
+    const fileSourceUrlFlags = [];
+    for (const raw of scan.data.raw) {
+      const text = await readPage(raw);
+      const split = splitFrontmatter(text);
+      if (!split.ok) continue;
+      if (/^source_url:\s*file:\/\//m.test(split.data.rawFrontmatter)) {
+        fileSourceUrlFlags.push(raw.relPath);
+      }
+    }
+    if (fileSourceUrlFlags.length > 0) buckets.file_source_url = fileSourceUrlFlags;
     const legacyPages = [];
     const orphanedPages = [];
     const structFlags = [];
@@ -3303,6 +3314,45 @@ ${newBody}`;
         else delete buckets.wikilink_citation;
       }
     }
+    if (input.fix && fileSourceUrlFlags.length > 0) {
+      const FILE_FIXED = [];
+      for (const relPath of fileSourceUrlFlags) {
+        try {
+          const absPath = `${input.vault}/${relPath}`;
+          const raw = await readFile15(absPath, "utf8");
+          const parts = raw.split("---", 3);
+          if (parts.length < 3) {
+            unresolved.push(relPath);
+            continue;
+          }
+          const rawFm = parts[1];
+          const rest = parts[2];
+          const sourceMatch = rest.match(/^source:\s*"?(https?:\/\/[^\s\n"]+)"?\s*$/m);
+          if (!sourceMatch) {
+            unresolved.push(relPath);
+            continue;
+          }
+          const realUrl = sourceMatch[1];
+          const newRawFm = rawFm.replace(/^source_url:\s*file:\/\/[^\n]+/m, `source_url: ${realUrl}`);
+          const newContent = `---${newRawFm}---${rest}`;
+          const w = await safeWritePage(absPath, newContent);
+          if (!w.ok) {
+            unresolved.push(relPath);
+            continue;
+          }
+          FILE_FIXED.push(relPath);
+        } catch {
+          unresolved.push(relPath);
+        }
+      }
+      fixed.push(...FILE_FIXED);
+      if (FILE_FIXED.length > 0) {
+        const fixedSet = new Set(FILE_FIXED);
+        const remaining = fileSourceUrlFlags.filter((p) => !fixedSet.has(p));
+        if (remaining.length > 0) buckets.file_source_url = remaining;
+        else delete buckets.file_source_url;
+      }
+    }
   }
   const errorOut = ERROR_ORDER.flatMap((k) => buckets[k] ? [{ kind: k, items: buckets[k] }] : []);
   const warningOut = WARNING_ORDER.flatMap((k) => buckets[k] ? [{ kind: k, items: buckets[k] }] : []);
@@ -3469,9 +3519,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);
@@ -3491,8 +3541,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], {
@@ -3680,7 +3730,7 @@ function detectFuseMount(vaultPath) {
           best = { point, fsType: `fuse.${match[1].split(":")[0] || "unknown"}` };
         }
       }
-      if (best) return best;
+      if (best) return { mountPoint: best.point, fsType: best.fsType };
     }
   } catch {
   }
@@ -4362,6 +4412,17 @@ async function runDoctor(input) {
 // src/commands/archive.ts
 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";
+function countWikilinks(body, slug) {
+  const escaped = slug.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const re = new RegExp(`\\[\\[${escaped}(?:[|#][^\\]]*)?\\]\\]`, "g");
+  const m = body.match(re);
+  return m ? m.length : 0;
+}
+function arraysEqual(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+}
 async function runArchive(input) {
   const scan = await scanVault(input.vault);
   if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
@@ -4377,14 +4438,81 @@ 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 slug = relPath.replace(/\.md$/, "").split("/").pop();
   const archivePath = join25("_archive", relPath).replace(/\\/g, "/");
+  let cascade;
+  if (input.cascade) {
+    const wikilinkRefs = [];
+    const sourceArrayRefs = [];
+    for (const page of scan.data.typedKnowledge) {
+      if (page.relPath === relPath) continue;
+      const text = await readPage(page);
+      const split = splitFrontmatter(text);
+      if (!split.ok) continue;
+      const wl = countWikilinks(split.data.body, slug);
+      if (wl > 0) wikilinkRefs.push({ page: page.relPath, count: wl });
+      const fm = extractFrontmatter(text);
+      if (!fm.ok) continue;
+      const sources = fm.data.sources;
+      if (Array.isArray(sources) && sources.includes(relPath)) {
+        const before = sources.filter((s) => typeof s === "string");
+        const after = before.filter((s) => s !== relPath);
+        sourceArrayRefs.push({ page: page.relPath, sources_before: before, sources_after: after });
+      }
+    }
+    const indexRefs = [];
+    if (!isRaw) {
+      try {
+        const idx = await readFile18(join25(input.vault, "index.md"), "utf8");
+        idx.split("\n").forEach((line, i) => {
+          if (line.includes(`[[${slug}]]`)) indexRefs.push({ line: i + 1, text: line });
+        });
+      } catch (e) {
+        if (e instanceof Error && "code" in e && e.code !== "ENOENT") throw e;
+      }
+    }
+    cascade = { wikilink_refs: wikilinkRefs, index_refs: indexRefs, source_array_refs: sourceArrayRefs };
+  }
+  if (input.cascade && !input.apply) {
+    const summary = `DRY-RUN \u2014 would archive ${relPath}; ${cascade.wikilink_refs.length} wikilink ref(s), ${cascade.index_refs.length} index ref(s), ${cascade.source_array_refs.length} source array ref(s).`;
+    return {
+      exitCode: ExitCode.OK,
+      result: ok({
+        archived_from: relPath,
+        archived_to: archivePath,
+        index_updated: false,
+        applied: false,
+        cascade,
+        humanHint: summary
+      })
+    };
+  }
+  if (input.cascade && input.apply && cascade) {
+    for (const ref of cascade.source_array_refs) {
+      const absPath = join25(input.vault, ref.page);
+      const text = await readFile18(absPath, "utf8");
+      const split = splitFrontmatter(text);
+      if (!split.ok) continue;
+      const before = split.data.rawFrontmatter;
+      const newSourcesYaml = ref.sources_after.length === 0 ? "sources: []" : "sources:\n" + ref.sources_after.map((s) => `  - ${s}`).join("\n");
+      const fmRewritten = before.replace(
+        /^sources:\s*(?:\[[^\]]*\]|(?:\r?\n(?:\s*-\s.*))+)/m,
+        newSourcesYaml
+      );
+      if (fmRewritten === before) continue;
+      if (!arraysEqual(ref.sources_after, ref.sources_before)) {
+        await writeFile9(absPath, `---
+${fmRewritten}
+---${split.data.body}`, "utf8");
+      }
+    }
+  }
   await mkdir8(dirname9(join25(input.vault, archivePath)), { recursive: true });
   let indexUpdated = false;
   if (!isRaw) {
     const indexPath = join25(input.vault, "index.md");
     try {
       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}]]`));
       if (filtered.length !== originalLines.length) {
@@ -4397,12 +4525,24 @@ async function runArchive(input) {
   }
   await rename5(join25(input.vault, relPath), join25(input.vault, archivePath));
   appendLastOp(input.vault, {
-    operation: "archive",
-    summary: `moved ${relPath} to ${archivePath}`,
+    operation: input.cascade ? "archive-cascade" : "archive",
+    summary: `moved ${relPath} to ${archivePath}${input.cascade ? ` (cascade: ${cascade?.source_array_refs.length ?? 0} source arrays updated)` : ""}`,
     files: [relPath],
     timestamp: (/* @__PURE__ */ new Date()).toISOString()
   });
-  return { exitCode: ExitCode.OK, result: ok({ archived_from: relPath, archived_to: archivePath, index_updated: indexUpdated, humanHint: `${relPath} -> ${archivePath}${indexUpdated ? " (index updated)" : ""}` }) };
+  const applied = input.cascade ? true : void 0;
+  const cascadeNote = input.cascade ? ` (cascade: ${cascade.source_array_refs.length} src arrays updated, ${cascade.wikilink_refs.length} wikilinks reported)` : "";
+  return {
+    exitCode: ExitCode.OK,
+    result: ok({
+      archived_from: relPath,
+      archived_to: archivePath,
+      index_updated: indexUpdated,
+      ...applied !== void 0 ? { applied } : {},
+      ...cascade ? { cascade } : {},
+      humanHint: `${relPath} -> ${archivePath}${indexUpdated ? " (index updated)" : ""}${cascadeNote}`
+    })
+  };
 }
 
 // src/commands/drift.ts
@@ -5983,11 +6123,105 @@ ${body}`;
 }
 
 // src/commands/sync.ts
-import { existsSync as existsSync11 } from "fs";
+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 (!existsSync11(join33(vault, ".git"))) {
+  const includeStashes = input.includeStashes ?? false;
+  if (!existsSync12(join34(vault, ".git"))) {
     return {
       exitCode: ExitCode.VAULT_PATH_INVALID,
       result: ok({
@@ -6041,22 +6275,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 (!existsSync11(join33(vault, ".git"))) {
+  if (!existsSync12(join34(vault, ".git"))) {
     return {
       exitCode: ExitCode.VAULT_PATH_INVALID,
       result: err("NOT_A_GIT_REPO", { path: vault })
@@ -6139,9 +6381,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 (!existsSync11(join33(vault, ".git"))) {
+  if (!existsSync12(join34(vault, ".git"))) {
     return {
       exitCode: ExitCode.VAULT_PATH_INVALID,
       result: err("NOT_A_GIT_REPO", { path: vault })
@@ -6214,10 +6475,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 writeFileSync5 } from "fs";
-import { join as join34, 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
@@ -6241,7 +6598,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 = join34(dir, entry.name);
+    const full = join35(dir, entry.name);
     if (entry.isDirectory()) {
       yield* walkMarkdown(full, base);
     } else if (entry.name.endsWith(".md")) {
@@ -6264,7 +6621,7 @@ async function runBackupSync(input) {
   let failed = 0;
   const files = [...walkMarkdown(input.vault, input.vault)];
   for (const relPath of files) {
-    const absPath = join34(input.vault, relPath);
+    const absPath = join35(input.vault, relPath);
     const localStat = statSync4(absPath);
     let needsUpload = true;
     try {
@@ -6283,7 +6640,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 {
@@ -6340,7 +6697,7 @@ async function runBackupRestore(input) {
     const objects = list.Contents ?? [];
     for (const obj of objects) {
       if (!obj.Key) continue;
-      const localPath = join34(target, obj.Key);
+      const localPath = join35(target, obj.Key);
       try {
         const localStat = statSync4(localPath);
         if (obj.LastModified && localStat.mtime > obj.LastModified) {
@@ -6353,8 +6710,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 });
-          writeFileSync5(localPath, Buffer.from(body));
+          mkdirSync4(dirname11(localPath), { recursive: true });
+          writeFileSync6(localPath, Buffer.from(body));
           downloaded++;
         }
       } catch {
@@ -6386,11 +6743,11 @@ async function runBackupRestore(input) {
 }
 
 // src/commands/status.ts
-import { existsSync as existsSync12, statSync as statSync5 } from "fs";
+import { existsSync as existsSync13, statSync as statSync5 } from "fs";
 import { readFile as readFile23 } from "fs/promises";
-import { join as join35 } from "path";
+import { join as join36 } from "path";
 async function runStatus(input) {
-  if (!existsSync12(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);
@@ -6415,7 +6772,7 @@ async function runStatus(input) {
   const compound = scan.data.compound.length;
   let schemaVersion = "v1";
   try {
-    const schemaContent = await readFile23(join35(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 {
@@ -6476,7 +6833,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 join36 } from "path";
+import { join as join37 } from "path";
 var TODAY = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
 var EXAMPLE_PAGES = {
   "entities/example-project.md": `---
@@ -6545,29 +6902,29 @@ Real sources are immutable after ingestion \u2014 never edit them.
 `;
 async function runSeed(input) {
   try {
-    await stat7(join36(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 = join36(input.vault, relPath);
+    const absPath = join37(input.vault, relPath);
     try {
       await stat7(absPath);
       skipped.push(relPath);
     } catch {
-      await mkdir13(join36(absPath, ".."), { recursive: true });
+      await mkdir13(join37(absPath, ".."), { recursive: true });
       await writeFile14(absPath, content, "utf8");
       created.push(relPath);
     }
   }
-  const rawPath = join36(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(join36(rawPath, ".."), { recursive: true });
+    await mkdir13(join37(rawPath, ".."), { recursive: true });
     await writeFile14(rawPath, EXAMPLE_RAW, "utf8");
     created.push("raw/articles/example-source.md");
   }
@@ -6591,8 +6948,8 @@ async function runSeed(input) {
 
 // src/commands/canvas.ts
 import { readFile as readFile24, writeFile as writeFile15 } from "fs/promises";
-import { existsSync as existsSync13 } from "fs";
-import { join as join37 } from "path";
+import { existsSync as existsSync14 } from "fs";
+import { join as join38 } from "path";
 var NODE_WIDTH = 240;
 var NODE_HEIGHT = 60;
 var COLUMN_SPACING = 400;
@@ -6670,8 +7027,8 @@ function buildCanvasEdges(adjacency) {
   return edges;
 }
 async function runCanvasGenerate(input) {
-  const graphPath = input.graphPath ?? join37(input.vault, ".skillwiki", "graph.json");
-  if (!existsSync13(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", {
@@ -6708,7 +7065,7 @@ async function runCanvasGenerate(input) {
   const nodes = buildCanvasNodes(paths);
   const edges = buildCanvasEdges(graph.adjacency);
   const canvas = { nodes, edges };
-  const outPath = join37(input.vault, "vault-graph.canvas");
+  const outPath = join38(input.vault, "vault-graph.canvas");
   try {
     await writeFile15(outPath, JSON.stringify(canvas, null, 2));
   } catch (e) {
@@ -6731,7 +7088,7 @@ written: ${outPath}`
 
 // src/commands/query.ts
 import { readFile as readFile25, stat as stat8 } from "fs/promises";
-import { join as join38 } from "path";
+import { join as join39 } from "path";
 var W_KEYWORD = 2;
 var W_SOURCE_OVERLAP = 4;
 var W_WIKILINK = 3;
@@ -6852,7 +7209,7 @@ function computeKeywordScore(terms, title, tags, body) {
   return score;
 }
 async function loadOrBuildGraph(vault) {
-  const graphPath = join38(vault, ".skillwiki", "graph.json");
+  const graphPath = join39(vault, ".skillwiki", "graph.json");
   let needsBuild = false;
   try {
     const fileStat = await stat8(graphPath);
@@ -6874,14 +7231,14 @@ async function loadOrBuildGraph(vault) {
 }
 
 // src/utils/auto-commit.ts
-import { existsSync as existsSync14 } from "fs";
-import { join as join39 } 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 (!existsSync14(join39(vault, ".git"))) return;
+  if (!existsSync15(join40(vault, ".git"))) return;
   const lastOps = readLastOp(vault);
   if (lastOps.length === 0) return;
   const porcelain = git(vault, ["status", "--porcelain"]);
@@ -6910,7 +7267,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");
@@ -6932,7 +7289,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 ?? join40(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");
@@ -7092,10 +7449,10 @@ program.command("status [vault]").description("output vault diagnostics").option
     langEnvValue: process.env.WIKI_LANG
   }), v.vault);
 });
-program.command("archive <page> [vault]").description("archive a typed-knowledge or raw page").option("--wiki <name>", "wiki profile name").action(async (page, vault, opts) => {
+program.command("archive <page> [vault]").description("archive a typed-knowledge or raw page").option("--wiki <name>", "wiki profile name").option("--cascade", "scan vault for references (wikilinks + sources arrays); preview by default", false).option("--apply", "with --cascade: mutate sources arrays and archive (without --apply, --cascade is preview-only)", false).action(async (page, vault, opts) => {
   const v = await resolveVaultArg(vault, opts.wiki);
   if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
-  else emit(await runArchive({ vault: v.vault, page }), v.vault);
+  else emit(await runArchive({ vault: v.vault, page, cascade: !!opts.cascade, apply: !!opts.apply }), v.vault);
 });
 program.command("drift [vault]").description("detect content drift in raw sources").option("--apply", "update sha256 in drifted sources").option("--new <date>", "list raw files ingested on/after this date (YYYY-MM-DD)").option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
   const v = await resolveVaultArg(vault, opts.wiki);
@@ -7157,10 +7514,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);
@@ -7172,6 +7529,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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.5.5",
+  "version": "0.6.1-beta.1",
   "type": "module",
   "bin": {
     "skillwiki": "dist/cli.js"

package/skills/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.5.5",
+  "version": "0.6.1-beta.1",
   "skills": "./",
   "description": "Project-aware Karpathy-style knowledge base for Claude Code: 18 prompt-only skills (wiki-*, proj-*, using-skillwiki) backed by the deterministic `skillwiki` CLI.",
   "author": {

package/skills/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.5.5",
+  "version": "0.6.1-beta.1",
   "description": "Project-aware Karpathy-style knowledge base for Codex with 18 prompt-only skills backed by the deterministic skillwiki CLI.",
   "author": {
     "name": "karlorz",

package/skills/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillwiki/skills",
-  "version": "0.5.5",
+  "version": "0.6.1-beta.1",
   "private": true,
   "files": [
     "wiki-*",

package/skills/wiki-sync/SKILL.md

@@ -1,47 +1,124 @@
 ---
-version: 0.2.1
+version: 0.6.1
 name: wiki-sync
-description: Safely sync the vault git repository. Runs skillwiki sync status, then guides push or pull with lint guards and conflict resolution.
+description: Safely sync the vault git repository — multi-session safe via advisory lockfile. Handles rebase conflict storms from archive-commit × snapshot-stream patterns. Runs skillwiki sync status, then guides push or pull with lint guards and conflict resolution.
 ---
 # wiki-sync
 ## When This Skill Activates
 - User wants to push local vault changes to the remote.
 - User wants to pull remote changes into their local vault.
 - User asks about vault sync status, git state, or multi-device coordination.
+- Multiple Claude Code sessions targeting the same vault.
 - Periodic maintenance before or after editing sessions.
 ## Pre-orientation reads
 Standard four reads.
 ## Steps
 0. Resolve vault: `skillwiki path` (record source for context).
+
+## Pre-flight peer check (multi-session safe)
+
+**Before any git stash or pull/push operation**, check for peer sessions:
+
+1. Run `skillwiki sync peers <vault>` to detect other sessions with active locks or recent `wiki-sync:*` stashes.
+2. If any non-self peer is present (locked or has stashes newer than 5 minutes):
+   - Surface the peer's session_id, PID, and summary to the user
+   - Ask the user to wait for the peer to finish, or pass `--force` to proceed anyway
+   - If `--force` is not given and peer is detected, **abort and exit**
+3. Acquire an advisory lock: `skillwiki sync lock <vault> --summary "wiki-sync <op>"` (where `<op>` is "pull" or "push")
+   - If lock is held (exit code 48), surface the holder (session_id, PID, summary) and abort
+4. **Always pair with unlock on exit** (success or error):
+   - `skillwiki sync unlock <vault>` in a finally block or error handler
+
+### Stash backlog warning
+
+On every invocation, count `wiki-sync:*` stashes older than 24 hours via `skillwiki sync peers`:
+- If any old stashes exist, warn the user: "Found N wiki-sync stash(es) older than 24h — audit and clean before proceeding"
+- **Do not auto-drop old stashes** — the user audits each one
+
+## Sync workflow
+
 1. Run `skillwiki sync status <vault>`. Read the JSON output.
-- Exit code 0: vault is clean (nothing to sync).
-- Exit code 22: warnings — dirty/ahead/behind (needs action).
+   - Exit code 0: vault is clean (nothing to sync).
+   - Exit code 22: warnings — dirty/ahead/behind (needs action).
 2. Present the current state: `status`, `dirty`, `ahead`, `behind`, `last_commit`.
 3. Ask the user which operation they want: **push**, **pull**, or **both** (pull then push).
+
 ### Push workflow
 4. If vault is dirty, ask the user to review uncommitted changes before proceeding.
 5. Run `skillwiki lint <vault>`. If errors exist, stop and report — do not push lint errors to remote.
 6. If lint passes (errors = 0), stage and commit:
-- `git -C <vault> add -A`
-- `git -C <vault> commit -m "sync: vault update $(date -u +%Y-%m-%dT%H:%MZ)"`
+   - `git -C <vault> add -A`
+   - `git -C <vault> commit -m "sync: vault update $(date -u +%Y-%m-%dT%H:%MZ)"`
 7. Run `git -C <vault> push origin HEAD`. Report result.
 8. Append one `log.md` entry summarizing: files pushed, lint result, commit hash.
+
 ### Pull workflow
-9. If vault is dirty, stash first: `git -C <vault> stash push -m "auto-stash before pull $(date -u +%Y-%m-%dT%H:%MZ)"`.
-10. Run `git -C <vault> pull --rebase origin HEAD`. Report result.
-11. If a stash was created, pop it: `git -C <vault> stash pop`.
-12. If conflicts occur during stash pop, identify them and present to the user for resolution (see Conflict Resolution below).
-13. Run `skillwiki lint <vault>` after pull to verify vault integrity.
-14. Append one `log.md` entry summarizing: commits pulled, lint result, any conflicts.
+9. Run `skillwiki sync status <vault> --include-stashes` to check for untracked file collisions (see Untracked file fingerprint below).
+10. If vault is dirty, stash first with the identifiable name format:
+    ```bash
+    VAULT="<vault>"
+    SESSION_ID="$(echo $CLAUDE_SESSION_ID)" # or fallback to PID/hostname
+    CWD_HASH="$(echo -n "$VAULT" | sha256sum | cut -c1-8)"
+    ISO_TS="$(date -u +%Y-%m-%dT%H:%MZ)"
+    MSG="wiki-sync:${SESSION_ID}:${CWD_HASH}:${ISO_TS}:pre-pull"
+    git -C "$VAULT" stash push -m "$MSG"
+    ```
+11. Run `git -C <vault> pull --rebase origin HEAD`. Report result.
+12. If a stash was created, pop it: `git -C <vault> stash pop`.
+13. If conflicts occur during stash pop, identify them and present to the user for resolution (see Conflict Resolution below).
+14. Run `skillwiki lint <vault>` after pull to verify vault integrity.
+15. Append one `log.md` entry summarizing: commits pulled, lint result, any conflicts.
+
 ### Pull-then-push workflow
-15. Execute the pull workflow (steps 9-13) first.
-16. Then execute the push workflow (steps 4-8).
+16. Execute the pull workflow (steps 9-14) first.
+17. Then execute the push workflow (steps 4-8).
+
+## Stash naming convention
+
+When `wiki-sync` creates a stash, use the identifiable message format:
+
+```
+wiki-sync:{session_id}:{cwd_hash}:{iso8601_timestamp}:{summary}
+```
+
+- **session_id**: prefer `$CLAUDE_SESSION_ID` env var if set, else `$$` (shell PID), else `unknown`
+- **cwd_hash**: first 8 chars of sha256(`$VAULT` path)
+- **iso8601_timestamp**: e.g., `2026-05-23T03:25:00Z` (UTC)
+- **summary**: short label like `pre-pull`, `pre-push`, or custom reason
+
+This allows any session to list `git stash list` and identify which stash came from which session/working directory.
+
+## Untracked file fingerprint (pre-pull)
+
+Before `git pull --rebase`, check for untracked files that exist on the remote and may collide:
+
+```bash
+for f in $(git -C "$VAULT" ls-files --others --exclude-standard); do
+  if git -C "$VAULT" cat-file -e "origin/main:$f" 2>/dev/null; then
+    # File exists on remote; check if identical
+    if diff -q <(git -C "$VAULT" show "origin/main:$f") "$VAULT/$f" >/dev/null 2>&1; then
+      # Byte-identical — safe to remove (presync artifact)
+      rm "$VAULT/$f"
+    else
+      # DIFFERENT — surface to user, DO NOT silently --include-untracked
+      echo "UNTRACKED COLLISION: $f differs from origin/main — surface to user for resolution"
+    fi
+  fi
+  # If file does not exist on remote, leave it alone (pull won't touch it)
+done
+```
+
+If collisions are found (different content), ask the user to resolve manually before pulling.
+
 ## Conflict Resolution
+
 When merge conflicts are detected:
-- **Frontmatter conflicts:**
+
+### Frontmatter conflicts
 - For `updated:` fields: always take the newer timestamp (compare both sides, keep the later one).
 - For all other frontmatter fields: present both versions to the user and ask which to keep.
-- **Body conflicts:**
+
+### Body conflicts
 - Do not auto-resolve body conflicts.
 - Mark unresolved regions with `???` on a line by itself between the conflicting versions, so the user can see both sides and decide.
 - Example:
@@ -51,12 +128,53 @@ Content from local version
 Content from remote version
 ```
 - After resolving conflicts, run `skillwiki lint <vault>` to verify before committing.
+
+### Modify/delete conflicts
+
+When `git pull --rebase` reports `CONFLICT (modify/delete)`:
+
+1. Identify the commit that deleted the file:
+   ```bash
+   git -C "$VAULT" log --diff-filter=D --pretty=oneline -- <path>
+   ```
+2. Read the commit message and any retro / log entry referencing it to determine if the deletion was intentional or accidental.
+3. Decide:
+   - `git -C "$VAULT" rm <path>` — accept the deletion (rebase continues)
+   - `git -C "$VAULT" add <path>` — keep the local restoration (rebase continues)
+4. `git -C "$VAULT" rebase --continue`.
+
+### Rebase conflict storm (archive commits × snapshot stream)
+
+When many local archive-only commits (e.g., `archive: moved X to _archive/`) are rebased over an origin/main that receives frequent snapshot commits (e.g., sg01 `Snapshot YYYYMMDD_HHMMSS`), every archive commit re-triggers the same content conflicts on shared files (`log.md`, `knowledge.md`, `spec.md`). This is predictable and can be resolved systematically.
+
+**Detection**: 3+ consecutive rebase stops on commits whose message matches `^archive: moved`.
+
+**Resolution**: For each archive commit during the storm:
+
+```bash
+# Apply --ours to all conflicting files (keep HEAD = origin/main + snapshots)
+for f in $(git -C "$VAULT" diff --name-only --diff-filter=U); do
+  git -C "$VAULT" checkout --ours "$f" && git -C "$VAULT" add "$f"
+done
+git -C "$VAULT" rebase --continue
+```
+
+**After the storm passes** (non-archive commits or clean rebase), pop the stash and handle any remaining conflicts per the normal Conflict Resolution sections above.
+
+**Prevention**:
+- Sync more frequently — don't let local fall >5 commits behind origin/main
+- Bundle archive commits — `skillwiki archive --batch` groups 5-10 transcript archives into one commit, reducing rebase surface
+- For vaults with snapshot cron, prefer smaller, more frequent syncs over large batch rebases
+
+See `concepts/wiki-sync-rebase-conflict-storm-pattern.md` for detailed analysis.
+
 ## Multi-device coordination
 When the user mentions editing from Obsidian desktop and Claude Code on a server (or any two-device setup):
 - Recommend pulling before every editing session on each device.
 - Recommend pushing after every editing session on each device.
 - If both devices edit the same page between syncs, conflicts are inevitable — the Conflict Resolution section handles this.
 - Suggest enabling auto-commit in Obsidian (Community Plugins: `obsidian-git`) to reduce dirty-state drift.
+
 ## Rclone-backed vault with git snapshotting (cron pattern)
 Some deployments use a cloud-backed vault (`rclone mount`) with a separate git repository for versioned snapshots. This pattern separates "live working vault" from "versioned backup".
 ### Architecture
@@ -105,12 +223,18 @@ bash ~/.hermes/scripts/wiki-snapshot.sh  # Re-sync fresh
 2. **Slow rsync on rclone mounts**: The rclone FUSE mount can be slow for large directory listings. Use `rsync -q` (quiet) to reduce output overhead, and consider `--delete-delay` instead of `--delete` if file churn is high. The rclone mount latency can cause `du` and `find` operations to timeout — this is normal, not an error.
 3. **Golden Rule violation**: Never mix sync methods on the same vault. If using rclone mount + git snapshotting, do NOT also enable Obsidian Sync, Syncthing, or iCloud on `~/wiki`. The rclone mount IS the sync mechanism.
 4. **Credential exposure**: The rclone mount and git remote use different credentials. Ensure git credentials are cached or use HTTPS with token, but never commit rclone config to git.
+
 ## Stop conditions
 - `skillwiki sync status` reports `not_a_repo` — the vault is not a git repository. Advise the user to initialize one.
 - Lint errors are found before a push — do not push until resolved.
 - `git push` or `git pull` fails with a network error — report and stop.
+- Peer lock is held or peer stashes exist — abort and ask the user to wait or pass `--force`.
+- Untracked file collision detected on pull — surface to user for manual resolution.
+
 ## Forbidden
 - Pushing when lint errors exist.
 - Auto-resolving body conflicts without user review.
 - Force-pushing (`git push --force`).
 - Modifying files in `raw/` to resolve conflicts (N9 — archive and re-ingest instead).
+- Stashing without the `wiki-sync:...` name format (breaks peer detection).
+- Force-deleting a peer's lockfile (use `--force` only if peer is confirmed dead).