skillwiki 0.10.0 → 0.10.1

package/dist/{chunk-S5ABQCXQ.js → chunk-R6BKJWVC.js}

@@ -562,6 +562,305 @@ function safeUserName() {
   }
 }
 
+// src/utils/git.ts
+import { execFileSync } from "child_process";
+function git(cwd, args) {
+  try {
+    return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+  } catch {
+    return "";
+  }
+}
+function gitStrict(cwd, args) {
+  return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+}
+
+// src/utils/operation-journal.ts
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync
+} from "fs";
+import { join as join2 } from "path";
+function journalDir(vault) {
+  const gitPath = git(vault, ["rev-parse", "--git-path", "vault-sync/operations"]);
+  if (!gitPath) return null;
+  return gitPath.startsWith("/") ? gitPath : join2(vault, gitPath);
+}
+function parseJournalEnv(text) {
+  return Object.fromEntries(
+    text.split("\n").filter((line) => line.includes("=")).map((line) => {
+      const i = line.indexOf("=");
+      return [line.slice(0, i), line.slice(i + 1)];
+    })
+  );
+}
+function serializeJournalEnv(fields, preferredOrder = []) {
+  const keys = [...preferredOrder.filter((k) => k in fields), ...Object.keys(fields).filter((k) => !preferredOrder.includes(k))];
+  const seen = /* @__PURE__ */ new Set();
+  const lines = [];
+  for (const k of keys) {
+    if (seen.has(k)) continue;
+    seen.add(k);
+    lines.push(`${k}=${fields[k]}`);
+  }
+  return lines.join("\n") + "\n";
+}
+function readJournal(vault, opId) {
+  const dir = journalDir(vault);
+  if (!dir) return null;
+  const path = join2(dir, `${opId}.env`);
+  if (!existsSync(path)) return null;
+  try {
+    return parseJournalEnv(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function writeJournal(vault, opId, fields) {
+  const dir = journalDir(vault);
+  if (!dir) return false;
+  try {
+    mkdirSync(dir, { recursive: true });
+    const path = join2(dir, `${opId}.env`);
+    const tmp = `${path}.tmp.${process.pid}`;
+    const order = [
+      "operation_id",
+      "phase",
+      "retry_count",
+      "original_branch",
+      "original_head",
+      "target_oid",
+      "owned_stash_oid",
+      "preservation_scope",
+      "lock_identity",
+      "helper_version",
+      "deployed_runtime_hash",
+      "conflict_identity",
+      "handoff",
+      "reason",
+      "prior_reason",
+      "superseded_at",
+      "cleared_reason",
+      "cleared_by",
+      "worktree_path",
+      "worktree_git_dir",
+      "inventory_path"
+    ];
+    writeFileSync(tmp, serializeJournalEnv(fields, order), "utf8");
+    renameSync(tmp, path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function listJournalOpIds(vault) {
+  const dir = journalDir(vault);
+  if (!dir || !existsSync(dir)) return [];
+  try {
+    return readdirSync(dir).filter((f) => f.endsWith(".env")).map((f) => f.replace(/\.env$/, "")).sort();
+  } catch {
+    return [];
+  }
+}
+function listReviewRequiredOps(vault) {
+  const currentGitDir = git(vault, ["rev-parse", "--absolute-git-dir"]);
+  const out = [];
+  for (const opId of listJournalOpIds(vault)) {
+    const fields = readJournal(vault, opId);
+    if (!fields) continue;
+    if (fields.phase !== "review-required" || fields.handoff !== "1") continue;
+    const journalGitDir = fields.worktree_git_dir ?? "";
+    if (!journalGitDir || !currentGitDir || journalGitDir === currentGitDir) {
+      out.push({ opId, fields });
+    }
+  }
+  return out;
+}
+function findReviewRequiredOp(vault) {
+  return listReviewRequiredOps(vault)[0]?.opId;
+}
+function hasUnmergedPaths(vault) {
+  const unmergedRaw = git(vault, ["diff", "--name-only", "--diff-filter=U"]);
+  return unmergedRaw ? unmergedRaw.split("\n").map((s) => s.trim()).filter(Boolean) : [];
+}
+function hasActiveGitSequencer(vault) {
+  const gitDir = git(vault, ["rev-parse", "--absolute-git-dir"]);
+  if (!gitDir) return false;
+  for (const m of ["MERGE_HEAD", "CHERRY_PICK_HEAD", "REVERT_HEAD"]) {
+    if (existsSync(join2(gitDir, m))) return true;
+  }
+  if (existsSync(join2(gitDir, "rebase-merge")) || existsSync(join2(gitDir, "rebase-apply"))) {
+    return true;
+  }
+  return false;
+}
+function isWorktreeClean(vault) {
+  const porcelain = git(vault, ["status", "--porcelain"]);
+  return !porcelain || porcelain.trim() === "";
+}
+function canSupersedeJournal(vault, fields) {
+  if (hasUnmergedPaths(vault).length > 0) return false;
+  if (hasActiveGitSequencer(vault)) return false;
+  if (!isWorktreeClean(vault)) return false;
+  const target = fields.target_oid?.trim();
+  if (!target) return false;
+  const head = git(vault, ["rev-parse", "HEAD"]);
+  if (!head) return false;
+  return gitMergeBaseIsAncestor(vault, target, head);
+}
+function gitMergeBaseIsAncestor(vault, ancestor, tip) {
+  if (ancestor === tip) return true;
+  const mb = git(vault, ["merge-base", ancestor, tip]);
+  return mb !== "" && mb === ancestor;
+}
+function markJournalSuperseded(vault, opId, fields, by) {
+  const next = { ...fields };
+  if (next.reason && next.reason !== "superseded-stale-review-required") {
+    next.prior_reason = next.prior_reason || next.reason;
+  }
+  next.phase = "complete";
+  next.reason = "superseded-stale-review-required";
+  next.superseded_at = (/* @__PURE__ */ new Date()).toISOString();
+  next.cleared_by = by;
+  next.cleared_reason = `operator-or-preflight ${next.superseded_at}`;
+  if (!next.handoff) next.handoff = "1";
+  if (!next.operation_id) next.operation_id = opId;
+  return writeJournal(vault, opId, next);
+}
+function supersedeStaleReviewRequiredJournals(vault, opts = {}) {
+  const by = opts.by ?? "skillwiki-preflight";
+  const superseded = [];
+  const skipped = [];
+  if (hasUnmergedPaths(vault).length > 0 || hasActiveGitSequencer(vault) || !isWorktreeClean(vault)) {
+    for (const { opId } of listReviewRequiredOps(vault)) skipped.push(opId);
+    return { superseded, skipped };
+  }
+  for (const { opId, fields } of listReviewRequiredOps(vault)) {
+    if (!canSupersedeJournal(vault, fields)) {
+      skipped.push(opId);
+      continue;
+    }
+    if (opts.dryRun) {
+      superseded.push(opId);
+      continue;
+    }
+    if (markJournalSuperseded(vault, opId, fields, by)) {
+      superseded.push(opId);
+    } else {
+      skipped.push(opId);
+    }
+  }
+  return { superseded, skipped };
+}
+
+// src/utils/vault-sync-helper.ts
+import { spawnSync } from "child_process";
+import { existsSync as existsSync2 } from "fs";
+import { homedir, platform } from "os";
+import { dirname as dirname2, join as join3 } from "path";
+import { fileURLToPath } from "url";
+var HELPER_NAME = "wiki-pull-with-auto-resolve.sh";
+function candidateHelperPaths(input = { vault: "" }) {
+  const env = input.env ?? process.env;
+  const paths = [];
+  if (input.helperPath) paths.push(input.helperPath);
+  if (env.SKILLWIKI_VAULT_SYNC_PULL_HELPER) paths.push(env.SKILLWIKI_VAULT_SYNC_PULL_HELPER);
+  let here = input.moduleDir;
+  if (!here) {
+    try {
+      here = dirname2(fileURLToPath(import.meta.url));
+    } catch {
+      here = void 0;
+    }
+  }
+  if (here) {
+    paths.push(join3(here, "vault-sync", "scripts", HELPER_NAME));
+    paths.push(join3(here, "..", "vault-sync", "scripts", HELPER_NAME));
+    paths.push(join3(here, "..", "..", "vault-sync", "scripts", HELPER_NAME));
+    paths.push(join3(here, "..", "..", "..", "vault-sync", "scripts", HELPER_NAME));
+  }
+  const home = input.home ?? env.HOME ?? env.USERPROFILE ?? (() => {
+    try {
+      return homedir();
+    } catch {
+      return void 0;
+    }
+  })();
+  if (home) {
+    const xdg = env.XDG_DATA_HOME;
+    const isDarwin = platform() === "darwin";
+    if (isDarwin) {
+      paths.push(join3(home, "Library", "Application Support", "vault-sync", "bin", HELPER_NAME));
+    }
+    paths.push(join3(xdg || join3(home, ".local", "share"), "vault-sync", "bin", HELPER_NAME));
+    if (!isDarwin) {
+      paths.push(join3(home, "Library", "Application Support", "vault-sync", "bin", HELPER_NAME));
+    }
+  }
+  return paths;
+}
+function resolveVaultSyncPullHelper(input) {
+  for (const p of candidateHelperPaths(input)) {
+    if (p && existsSync2(p)) return p;
+  }
+  return null;
+}
+async function runVaultSyncPullHelper(input) {
+  const helperPath = resolveVaultSyncPullHelper(input);
+  if (!helperPath) {
+    const tried = candidateHelperPaths(input).filter(Boolean);
+    return err("GIT_PULL_FAILED", {
+      message: "canonical vault-sync pull helper not found; run skillwiki doctor; install skillwiki@0.10.1+ or set SKILLWIKI_VAULT_SYNC_PULL_HELPER; host install: ~/Library/Application Support/vault-sync/bin or ~/.local/share/vault-sync/bin",
+      tried_paths: tried.slice(0, 12)
+    });
+  }
+  const remote = input.remote ?? "origin";
+  const branch = input.branch ?? "main";
+  const beforeOid = git(input.vault, ["rev-parse", "HEAD"]);
+  if (!beforeOid) {
+    return err("GIT_PULL_FAILED", { message: "could not read HEAD before pull" });
+  }
+  const env = {
+    ...process.env,
+    ...input.env ?? {},
+    WIKI_DIR: input.vault
+  };
+  if (input.lockToken) {
+    env.VAULT_SYNC_MANAGED_LOCK_TOKEN = input.lockToken;
+  }
+  const result = spawnSync("bash", [helperPath, remote, branch], {
+    env,
+    encoding: "utf8",
+    cwd: input.vault
+  });
+  const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+  const status = result.status ?? 1;
+  if (status === 2) {
+    return err("PREFLIGHT_FAILED", { reason: "existing-handoff", output, helper_path: helperPath });
+  }
+  if (status !== 0) {
+    return err("GIT_PULL_FAILED", {
+      message: result.error ? String(result.error) : `helper exited ${status}`,
+      output,
+      helper_path: helperPath
+    });
+  }
+  const afterOid = git(input.vault, ["rev-parse", "HEAD"]);
+  if (!afterOid) {
+    return err("GIT_PULL_FAILED", { message: "could not read HEAD after pull", helper_path: helperPath });
+  }
+  return ok({
+    before_oid: beforeOid,
+    after_oid: afterOid,
+    changed: beforeOid !== afterOid,
+    helper_path: helperPath
+  });
+}
+
 export {
   CONFIG_KEYS,
   isValidWikiProfileKey,
@@ -576,5 +875,16 @@ export {
   snapshotterAliasForLocalHost,
   satelliteGateFromFleetLoad,
   loadFleetManifest,
-  resolveFleetHostId
+  resolveFleetHostId,
+  git,
+  gitStrict,
+  readJournal,
+  listJournalOpIds,
+  listReviewRequiredOps,
+  findReviewRequiredOp,
+  hasUnmergedPaths,
+  hasActiveGitSequencer,
+  supersedeStaleReviewRequiredJournals,
+  resolveVaultSyncPullHelper,
+  runVaultSyncPullHelper
 };

package/dist/{chunk-5TBIMLTZ.js → chunk-SCGC7YNM.js}

@@ -1,30 +1,19 @@
 #!/usr/bin/env node
 import {
-  loadFleetManifestAndHost
-} from "./chunk-S5ABQCXQ.js";
+  findReviewRequiredOp,
+  git,
+  hasActiveGitSequencer,
+  hasUnmergedPaths,
+  loadFleetManifestAndHost,
+  runVaultSyncPullHelper,
+  supersedeStaleReviewRequiredJournals
+} from "./chunk-R6BKJWVC.js";
 import {
   ExitCode,
   err,
   ok
 } from "./chunk-C5OLZRRM.js";
 
-// src/utils/managed-write-preflight.ts
-import { readdirSync, readFileSync as readFileSync2 } from "fs";
-import { join as join3 } from "path";
-
-// src/utils/git.ts
-import { execFileSync } from "child_process";
-function git(cwd, args) {
-  try {
-    return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
-  } catch {
-    return "";
-  }
-}
-function gitStrict(cwd, args) {
-  return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
-}
-
 // src/utils/managed-write-lock.ts
 import { randomBytes } from "crypto";
 import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from "fs";
@@ -68,122 +57,12 @@ function releaseManagedWriteLock(handle) {
   }
 }
 
-// src/utils/vault-sync-helper.ts
-import { spawnSync } from "child_process";
-import { existsSync } from "fs";
-import { dirname as dirname2, join as join2 } from "path";
-import { fileURLToPath } from "url";
-function candidateHelperPaths(input) {
-  const env = input.env ?? process.env;
-  const paths = [];
-  if (input.helperPath) paths.push(input.helperPath);
-  if (env.SKILLWIKI_VAULT_SYNC_PULL_HELPER) paths.push(env.SKILLWIKI_VAULT_SYNC_PULL_HELPER);
-  try {
-    const here = dirname2(fileURLToPath(import.meta.url));
-    paths.push(join2(here, "..", "vault-sync", "scripts", "wiki-pull-with-auto-resolve.sh"));
-    paths.push(join2(here, "..", "..", "vault-sync", "scripts", "wiki-pull-with-auto-resolve.sh"));
-    paths.push(join2(here, "..", "..", "..", "vault-sync", "scripts", "wiki-pull-with-auto-resolve.sh"));
-  } catch {
-  }
-  return paths;
-}
-function resolveVaultSyncPullHelper(input) {
-  for (const p of candidateHelperPaths(input)) {
-    if (p && existsSync(p)) return p;
-  }
-  return null;
-}
-async function runVaultSyncPullHelper(input) {
-  const helperPath = resolveVaultSyncPullHelper(input);
-  if (!helperPath) {
-    return err("GIT_PULL_FAILED", { message: "canonical vault-sync pull helper not found" });
-  }
-  const remote = input.remote ?? "origin";
-  const branch = input.branch ?? "main";
-  const beforeOid = git(input.vault, ["rev-parse", "HEAD"]);
-  if (!beforeOid) {
-    return err("GIT_PULL_FAILED", { message: "could not read HEAD before pull" });
-  }
-  const env = {
-    ...process.env,
-    ...input.env ?? {},
-    WIKI_DIR: input.vault
-  };
-  if (input.lockToken) {
-    env.VAULT_SYNC_MANAGED_LOCK_TOKEN = input.lockToken;
-  }
-  const result = spawnSync("bash", [helperPath, remote, branch], {
-    env,
-    encoding: "utf8",
-    cwd: input.vault
-  });
-  const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
-  const status = result.status ?? 1;
-  if (status === 2) {
-    return err("PREFLIGHT_FAILED", { reason: "existing-handoff", output, helper_path: helperPath });
-  }
-  if (status !== 0) {
-    return err("GIT_PULL_FAILED", {
-      message: result.error ? String(result.error) : `helper exited ${status}`,
-      output,
-      helper_path: helperPath
-    });
-  }
-  const afterOid = git(input.vault, ["rev-parse", "HEAD"]);
-  if (!afterOid) {
-    return err("GIT_PULL_FAILED", { message: "could not read HEAD after pull", helper_path: helperPath });
-  }
-  return ok({
-    before_oid: beforeOid,
-    after_oid: afterOid,
-    changed: beforeOid !== afterOid,
-    helper_path: helperPath
-  });
-}
-
 // src/utils/managed-write-preflight.ts
 var DEFAULT_DEPS = {
   converge: (input) => runVaultSyncPullHelper(input)
 };
-function journalDir(vault) {
-  const gitPath = git(vault, ["rev-parse", "--git-path", "vault-sync/operations"]);
-  if (!gitPath) return null;
-  return gitPath.startsWith("/") ? gitPath : join3(vault, gitPath);
-}
-function findReviewRequiredOp(vault) {
-  const dir = journalDir(vault);
-  if (!dir) return void 0;
-  let files;
-  try {
-    files = readdirSync(dir).filter((f) => f.endsWith(".env"));
-  } catch {
-    return void 0;
-  }
-  const currentGitDir = git(vault, ["rev-parse", "--absolute-git-dir"]);
-  for (const file of files) {
-    let text;
-    try {
-      text = readFileSync2(join3(dir, file), "utf8");
-    } catch {
-      continue;
-    }
-    const fields = Object.fromEntries(
-      text.split("\n").filter((line) => line.includes("=")).map((line) => {
-        const i = line.indexOf("=");
-        return [line.slice(0, i), line.slice(i + 1)];
-      })
-    );
-    if (fields.phase !== "review-required" || fields.handoff !== "1") continue;
-    const journalGitDir = fields.worktree_git_dir ?? "";
-    if (!journalGitDir || !currentGitDir || journalGitDir === currentGitDir) {
-      return file.replace(/\.env$/, "");
-    }
-  }
-  return void 0;
-}
 function preflightBlocker(vault) {
-  const unmergedRaw = git(vault, ["diff", "--name-only", "--diff-filter=U"]);
-  const unmerged = unmergedRaw ? unmergedRaw.split("\n").map((s) => s.trim()).filter(Boolean) : [];
+  const unmerged = hasUnmergedPaths(vault);
   if (unmerged.length > 0) {
     return {
       reason: "unmerged-paths",
@@ -191,17 +70,10 @@ function preflightBlocker(vault) {
       unmerged_paths: unmerged
     };
   }
-  const gitDir = git(vault, ["rev-parse", "--absolute-git-dir"]);
-  if (gitDir) {
-    const markers = ["MERGE_HEAD", "CHERRY_PICK_HEAD", "REVERT_HEAD"];
-    for (const m of markers) {
-      try {
-        readFileSync2(join3(gitDir, m));
-        return { reason: "git-operation-in-progress" };
-      } catch {
-      }
-    }
+  if (hasActiveGitSequencer(vault)) {
+    return { reason: "git-operation-in-progress" };
   }
+  supersedeStaleReviewRequiredJournals(vault, { by: "skillwiki-managed-write-preflight" });
   const op = findReviewRequiredOp(vault);
   if (op) return { reason: "review-required", operation_id: op };
   return null;
@@ -269,7 +141,8 @@ async function runManagedWritePreflight(input, deps = DEFAULT_DEPS) {
   const converge = await deps.converge({
     vault,
     lockToken: input.lockToken,
-    env: input.env
+    env: input.env,
+    home: input.home
   });
   if (!converge.ok) {
     const exitCode = converge.error === "PREFLIGHT_FAILED" ? ExitCode.PREFLIGHT_FAILED : ExitCode.SYNC_PULL_FAILED;
@@ -333,11 +206,8 @@ async function runManagedWriteTransaction(input, deps = DEFAULT_DEPS) {
 }
 
 export {
-  git,
-  gitStrict,
   acquireManagedWriteLock,
   releaseManagedWriteLock,
-  runVaultSyncPullHelper,
   runManagedWritePreflight,
   runManagedWriteTransaction
 };

package/dist/{chunk-DR7KFHNH.js → chunk-XSTXPA34.js}

@@ -22,14 +22,16 @@ import {
 import {
   CONFIG_KEYS,
   isValidWikiProfileKey,
+  listReviewRequiredOps,
   loadFleetManifestAndHost,
   parseDotenvFile,
   parseDotenvText,
   profileKey,
+  resolveVaultSyncPullHelper,
   satelliteGateFromFleetLoad,
   snapshotterAliasForLocalHost,
   writeDotenv
-} from "./chunk-S5ABQCXQ.js";
+} from "./chunk-R6BKJWVC.js";
 import {
   CompoundSchema,
   ExitCode,
@@ -3032,6 +3034,10 @@ function buildCliSurface() {
   syncCmd.command("status").option("--wiki <name>").option("--include-stashes").option("--include-remote-health").option("--check-snapshotter");
   syncCmd.command("push").option("--wiki <name>");
   syncCmd.command("pull").option("--wiki <name>");
+  syncCmd.command("resolve-derived").option("--operation-id <id>").option("--wiki <name>");
+  const syncJournalCmd = syncCmd.command("journal");
+  syncJournalCmd.command("list").option("--wiki <name>");
+  syncJournalCmd.command("clear-stale").option("--dry-run").option("--wiki <name>");
   syncCmd.command("lock").option("--summary <text>").option("--ttl-minutes <n>").option("--force").option("--wiki <name>");
   syncCmd.command("unlock").option("--force").option("--wiki <name>");
   syncCmd.command("peers").option("--wiki <name>");
@@ -6210,6 +6216,42 @@ function checkVfsCacheHealth(resolvedPath) {
     `${stats.files} files, ${(stats.bytesUsed / 1024 / 1024).toFixed(1)}MB \u2014 clean (0 errored, 0 pending)`
   );
 }
+function checkVaultSyncPullHelper(home, env) {
+  const path = resolveVaultSyncPullHelper({
+    vault: "",
+    home,
+    env
+  });
+  if (path) {
+    return check("pass", "vault_sync_pull_helper", "Vault-sync pull helper", `Resolved: ${path}`);
+  }
+  return check(
+    "error",
+    "vault_sync_pull_helper",
+    "Vault-sync pull helper",
+    "Not found \u2014 install skillwiki@0.10.1+, redeploy vault-sync, or set SKILLWIKI_VAULT_SYNC_PULL_HELPER"
+  );
+}
+function checkVaultSyncReviewRequiredJournals(vaultPath) {
+  if (!vaultPath || !existsSync13(join24(vaultPath, ".git"))) {
+    return check("pass", "vault_sync_review_required_journals", "Review-required journals", "No git vault \u2014 check skipped");
+  }
+  try {
+    const ops = listReviewRequiredOps(vaultPath);
+    if (ops.length === 0) {
+      return check("pass", "vault_sync_review_required_journals", "Review-required journals", "None");
+    }
+    const sample = ops[0]?.opId ?? "?";
+    return check(
+      "warn",
+      "vault_sync_review_required_journals",
+      "Review-required journals",
+      `${ops.length} handoff(s); oldest/sample: ${sample} \u2014 if worktree clean: skillwiki sync journal clear-stale --dry-run`
+    );
+  } catch {
+    return check("pass", "vault_sync_review_required_journals", "Review-required journals", "Could not read journals \u2014 check skipped");
+  }
+}
 function readVaultSyncConfig(home) {
   try {
     const content = readFileSync10(join24(home, ".skillwiki", ".env"), "utf8");
@@ -6820,6 +6862,8 @@ async function runDoctor(input) {
     vaultSyncServiceScope: vsConfig.serviceScope,
     snapshotScriptPath: vsConfig.snapshotScript
   }));
+  checks.push(checkVaultSyncPullHelper(input.home, input.env ?? process.env));
+  checks.push(checkVaultSyncReviewRequiredJournals(resolvedPath));
   const satelliteGate = satelliteGateFromFleetLoad(fleetLoad);
   checks.push(checkSatelliteLastRun(resolvedPath, satelliteGate.satelliteExpected));
   checks.push(checkSatelliteTimer(satelliteGate.satelliteExpected));

package/dist/cli.js

@@ -68,7 +68,7 @@ import {
   satelliteLatestRunPath,
   taxonomyCommentForPage,
   upsertIndexEntry
-} from "./chunk-DR7KFHNH.js";
+} from "./chunk-XSTXPA34.js";
 import {
   normalizeDistTag,
   readCache,
@@ -91,26 +91,30 @@ import {
 } from "./chunk-IZABIE44.js";
 import {
   acquireManagedWriteLock,
-  git,
-  gitStrict,
   releaseManagedWriteLock,
   runManagedWritePreflight,
-  runManagedWriteTransaction,
-  runVaultSyncPullHelper
-} from "./chunk-5TBIMLTZ.js";
+  runManagedWriteTransaction
+} from "./chunk-SCGC7YNM.js";
 import {
   FLEET_REL_PATH,
+  git,
+  gitStrict,
+  listJournalOpIds,
+  listReviewRequiredOps,
   loadFleetManifest,
   loadFleetManifestAndHost,
   parseDotenvFile,
   parseDotenvText,
   profileKey,
+  readJournal,
   resolveFleetHostId,
   runFleetContext,
   runFleetValidate,
+  runVaultSyncPullHelper,
   snapshotterAliasForLocalHost,
+  supersedeStaleReviewRequiredJournals,
   writeDotenv
-} from "./chunk-S5ABQCXQ.js";
+} from "./chunk-R6BKJWVC.js";
 import {
   ExitCode,
   MetaSchema,
@@ -2990,6 +2994,30 @@ ${migratedBody}${newFooter}`;
 // src/commands/update.ts
 import { execSync } from "child_process";
 import { join as join19 } from "path";
+function parseCoreSemver(version) {
+  const m = version.match(/^(\d+)\.(\d+)\.(\d+)/);
+  if (!m) return null;
+  return { major: parseInt(m[1], 10), minor: parseInt(m[2], 10), patch: parseInt(m[3], 10) };
+}
+function needs0101Migration(previousVersion, newVersion) {
+  const p = parseCoreSemver(previousVersion);
+  const n = parseCoreSemver(newVersion);
+  if (!p || !n) return false;
+  const prevLt = p.major < 0 || p.major === 0 && p.minor < 10 || p.major === 0 && p.minor === 10 && p.patch < 1;
+  const newGe = n.major > 0 || n.major === 0 && n.minor > 10 || n.major === 0 && n.minor === 10 && n.patch >= 1;
+  return prevLt && newGe;
+}
+function migrationNotesForUpgrade(previousVersion, newVersion) {
+  if (!needs0101Migration(previousVersion, newVersion)) return [];
+  return [
+    "Migration 0.10.1:",
+    "- pull helper resolves from dist/ + host vault-sync install",
+    "- run: skillwiki doctor",
+    "- if managed writes blocked: skillwiki sync journal list",
+    "- then: skillwiki sync journal clear-stale --dry-run",
+    "- legacy override: SKILLWIKI_VAULT_SYNC_PULL_HELPER=<path-to-wiki-pull-with-auto-resolve.sh>"
+  ];
+}
 function resolveGlobalSkillsRoot() {
   try {
     const globalRoot = execSync("npm root -g", {
@@ -3085,6 +3113,9 @@ async function runUpdate(input) {
     hintLines.push(`version warnings: ${version_warnings.length}`);
     for (const w of version_warnings) hintLines.push(`  ${w}`);
   }
+  for (const line of migrationNotesForUpgrade(currentVersion, latest)) {
+    hintLines.push(line);
+  }
   return {
     exitCode: ExitCode.OK,
     result: ok({
@@ -5772,6 +5803,50 @@ function runSyncUnlock(input) {
   };
 }
 
+// src/commands/sync-journal.ts
+function runSyncJournalList(input) {
+  const byPhase = {};
+  for (const opId of listJournalOpIds(input.vault)) {
+    const fields = readJournal(input.vault, opId);
+    const phase = fields?.phase ?? "unknown";
+    byPhase[phase] = (byPhase[phase] ?? 0) + 1;
+  }
+  const review = listReviewRequiredOps(input.vault).map(({ opId, fields }) => ({
+    operation_id: opId,
+    reason: fields.reason,
+    target_oid: fields.target_oid,
+    original_head: fields.original_head
+  }));
+  const total = Object.values(byPhase).reduce((a, b) => a + b, 0);
+  const hint = review.length === 0 ? `journals: ${total} total; no review-required handoffs` : `journals: ${total} total; ${review.length} review-required \u2014 if worktree clean: skillwiki sync journal clear-stale --dry-run`;
+  return {
+    exitCode: ExitCode.OK,
+    result: ok({
+      total,
+      by_phase: byPhase,
+      review_required: review,
+      humanHint: hint
+    })
+  };
+}
+function runSyncJournalClearStale(input) {
+  const { superseded, skipped } = supersedeStaleReviewRequiredJournals(input.vault, {
+    dryRun: !!input.dryRun,
+    by: input.dryRun ? "skillwiki-sync-journal-clear-stale-dry-run" : "skillwiki-sync-journal-clear-stale"
+  });
+  const mode = input.dryRun ? "dry-run" : "write";
+  const hint = superseded.length === 0 ? `clear-stale (${mode}): nothing to supersede; skipped=${skipped.length}` : `clear-stale (${mode}): ${superseded.length} journal(s); skipped=${skipped.length}`;
+  return {
+    exitCode: ExitCode.OK,
+    result: ok({
+      dry_run: !!input.dryRun,
+      superseded,
+      skipped,
+      humanHint: hint
+    })
+  };
+}
+
 // src/commands/backup.ts
 import { statSync as statSync2, readdirSync, readFileSync as readFileSync11, mkdirSync as mkdirSync2, writeFileSync as writeFileSync4 } from "fs";
 import { join as join28, relative as relative2, dirname as dirname6 } from "path";
@@ -6674,7 +6749,7 @@ async function emitManagedVaultWrite(vault, command, mutate, opts) {
   if (guard.blocked) {
     return emit({ exitCode: guard.exitCode, result: guard.result }, void 0, { postCommit: false });
   }
-  const { runManagedWriteTransaction: runManagedWriteTransaction2 } = await import("./managed-write-preflight-SILEUQEV.js");
+  const { runManagedWriteTransaction: runManagedWriteTransaction2 } = await import("./managed-write-preflight-PW4OOOMV.js");
   const run = await runManagedWriteTransaction2({
     vault,
     command,
@@ -7225,6 +7300,24 @@ syncCmd.command("resolve-derived [vault]").description("resolve mixed derived co
     );
   }
 });
+var syncJournalCmd = syncCmd.command("journal").description("inspect or clear vault-sync operation journals");
+syncJournalCmd.command("list [vault]").description("list vault-sync operation journals and review-required handoffs").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(runSyncJournalList({ vault: v.vault }));
+});
+syncJournalCmd.command("clear-stale [vault]").description("supersede stale review-required journals when worktree is clean").option("--dry-run", "report what would be cleared without writing", 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 if (opts.dryRun) emit(runSyncJournalClearStale({ vault: v.vault, dryRun: true }));
+  else {
+    return emitGuardedVaultWrite(
+      v.vault,
+      "sync journal clear-stale",
+      async () => runSyncJournalClearStale({ vault: v.vault, dryRun: false })
+    );
+  }
+});
 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 });

package/dist/{managed-write-preflight-SILEUQEV.js → managed-write-preflight-PW4OOOMV.js}

@@ -2,8 +2,8 @@
 import {
   runManagedWritePreflight,
   runManagedWriteTransaction
-} from "./chunk-5TBIMLTZ.js";
-import "./chunk-S5ABQCXQ.js";
+} from "./chunk-SCGC7YNM.js";
+import "./chunk-R6BKJWVC.js";
 import "./chunk-C5OLZRRM.js";
 export {
   runManagedWritePreflight,

package/dist/skillwiki-mcp.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import {
   runSkillwikiMcpStdio
-} from "./chunk-DR7KFHNH.js";
+} from "./chunk-XSTXPA34.js";
 import "./chunk-7I2TPIV5.js";
 import "./chunk-IZABIE44.js";
-import "./chunk-S5ABQCXQ.js";
+import "./chunk-R6BKJWVC.js";
 import "./chunk-C5OLZRRM.js";
 
 // src/mcp-entry.ts

package/package.json

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

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

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "skills": "./",
   "description": "Project-aware Karpathy-style knowledge base for Claude Code: 19 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.10.0",
+  "version": "0.10.1",
   "description": "Project-aware Karpathy-style knowledge base for Codex with 19 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.10.0",
+  "version": "0.10.1",
   "private": true,
   "files": [
     "wiki-*",

package/skills/skills/using-skillwiki/SKILL.md

@@ -80,6 +80,17 @@ path, run publisher dry-run, then run the same command with `--write`.
 
 Before a managed vault mutation, invoke the managed SkillWiki command while the draft remains outside the authoritative target path. The command resolves fleet authority, refuses existing unmerged/review-required state, converges an authorized Git writer, freezes the base OID, and only then applies the write. Do not run `git pull --rebase --autostash` after placing the authoritative change in the live worktree. Do not edit root `index.md` or root `log.md` directly; projection and log commands own those compatibility files.
 
+### Managed write / 0.10.1 migration troubleshooting
+
+After upgrading to skillwiki **≥0.10.1** (or when managed write fails):
+
+1. Run `skillwiki doctor` — checks `vault_sync_pull_helper` and `vault_sync_review_required_journals`.
+2. If pull helper is missing: install `skillwiki@0.10.1+` (helper must resolve from `dist/vault-sync/scripts/`) and/or redeploy vault-sync host install. Last-resort override: `SKILLWIKI_VAULT_SYNC_PULL_HELPER` pointing at `wiki-pull-with-auto-resolve.sh` under host vault-sync `bin/` (macOS Application Support or Linux `~/.local/share/vault-sync/bin`).
+3. If preflight reports `review-required` on a **clean** worktree: `skillwiki sync journal list`, then `skillwiki sync journal clear-stale --dry-run`, then `clear-stale` without dry-run. Preflight also auto-supersedes stale handoffs when criteria match; do not force-clear during active rebase/unmerged state.
+4. After `skillwiki update` across 0.10.1, read the printed Migration 0.10.1 notes.
+
+Also mirror these pointers in vault-presync / vault-sync-status skills when operating pull/push.
+
 - typed pages: `skillwiki page publish <draft> <vault> --target <path>` then the same command with `--write`
 - archive: `skillwiki archive <path> <vault>`
 - ad-hoc structural log: `skillwiki log-append <vault> --content '<entry>'` (Release A dual-write) or event materialization (Release B)

package/skills/using-skillwiki/SKILL.md

@@ -80,6 +80,17 @@ path, run publisher dry-run, then run the same command with `--write`.
 
 Before a managed vault mutation, invoke the managed SkillWiki command while the draft remains outside the authoritative target path. The command resolves fleet authority, refuses existing unmerged/review-required state, converges an authorized Git writer, freezes the base OID, and only then applies the write. Do not run `git pull --rebase --autostash` after placing the authoritative change in the live worktree. Do not edit root `index.md` or root `log.md` directly; projection and log commands own those compatibility files.
 
+### Managed write / 0.10.1 migration troubleshooting
+
+After upgrading to skillwiki **≥0.10.1** (or when managed write fails):
+
+1. Run `skillwiki doctor` — checks `vault_sync_pull_helper` and `vault_sync_review_required_journals`.
+2. If pull helper is missing: install `skillwiki@0.10.1+` (helper must resolve from `dist/vault-sync/scripts/`) and/or redeploy vault-sync host install. Last-resort override: `SKILLWIKI_VAULT_SYNC_PULL_HELPER` pointing at `wiki-pull-with-auto-resolve.sh` under host vault-sync `bin/` (macOS Application Support or Linux `~/.local/share/vault-sync/bin`).
+3. If preflight reports `review-required` on a **clean** worktree: `skillwiki sync journal list`, then `skillwiki sync journal clear-stale --dry-run`, then `clear-stale` without dry-run. Preflight also auto-supersedes stale handoffs when criteria match; do not force-clear during active rebase/unmerged state.
+4. After `skillwiki update` across 0.10.1, read the printed Migration 0.10.1 notes.
+
+Also mirror these pointers in vault-presync / vault-sync-status skills when operating pull/push.
+
 - typed pages: `skillwiki page publish <draft> <vault> --target <path>` then the same command with `--write`
 - archive: `skillwiki archive <path> <vault>`
 - ad-hoc structural log: `skillwiki log-append <vault> --content '<entry>'` (Release A dual-write) or event materialization (Release B)