skillwiki 0.5.5 → 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 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
@@ -3469,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);
@@ -3491,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], {
@@ -5983,11 +5984,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 +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 (!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 +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 (!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 +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 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 +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 = 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 +6482,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 +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 {
@@ -6340,7 +6558,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 +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 });
-          writeFileSync5(localPath, Buffer.from(body));
+          mkdirSync4(dirname11(localPath), { recursive: true });
+          writeFileSync6(localPath, Buffer.from(body));
           downloaded++;
         }
       } catch {
@@ -6386,11 +6604,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 +6633,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 +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 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 +6763,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 +6809,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 +6888,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 +6926,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 +6949,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 +7070,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 +7092,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 +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");
@@ -6932,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 ?? 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");
@@ -7157,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);
@@ -7172,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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.5.5",
+  "version": "0.6.0",
   "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.0",
   "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.0",
   "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.0",
   "private": true,
   "files": [
     "wiki-*",

package/skills/wiki-sync/SKILL.md

@@ -1,47 +1,124 @@
 ---
-version: 0.2.1
+version: 0.3.0
 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. 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,28 @@ 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`.
+
 ## 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 +198,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).