skillwiki 0.10.13 → 0.10.15

package/dist/{chunk-X2CPXF4T.js → chunk-24MVNAFJ.js}

@@ -33,7 +33,7 @@ import {
   satelliteGateFromFleetLoad,
   snapshotterAliasForLocalHost,
   writeDotenv
-} from "./chunk-E3PMAHS3.js";
+} from "./chunk-OWPQJOFG.js";
 import {
   CompoundSchema,
   ExitCode,
@@ -3211,6 +3211,7 @@ function buildCliSurface() {
   program.command("tag");
   program.command("tag-sync").option("--dry-run").option("--wiki <name>");
   program.command("sync");
+  program.command("snapshot-maintenance");
   program.command("backup");
   program.command("seed").option("--wiki <name>");
   program.command("observe").requiredOption("--text <text>").option("--kind <kind>").option("--project <slug>").option("--severity <level>").option("--capture-budget <n>").option("--wiki <name>");
@@ -3252,6 +3253,9 @@ function buildCliSurface() {
   const backupCmd = program.commands.find((c) => c.name() === "backup");
   backupCmd.command("sync").option("--dry-run").option("--bucket <name>").option("--endpoint <url>").option("--region <region>").option("--prune").option("--wiki <name>");
   backupCmd.command("restore").option("--bucket <name>").option("--endpoint <url>").option("--region <region>").option("--target <dir>").option("--wiki <name>");
+  const snapshotMaintenanceCmd = program.commands.find((c) => c.name() === "snapshot-maintenance");
+  const snapMaintJournalCmd = snapshotMaintenanceCmd.command("journal");
+  snapMaintJournalCmd.command("clear-stale").option("--dry-run").option("--approve <id>").option("--reason <text>").option("--wiki <name>");
   const memoryCmd = program.commands.find((c) => c.name() === "memory");
   memoryCmd.command("topics").option("--project <slug>").option("--limit <n>").option("--wiki <name>");
   memoryCmd.command("index").requiredOption("--project <slug>").option("--check").option("--if-stale").option("--wiki <name>");
@@ -6517,6 +6521,176 @@ function resolveSnapshotGitWorktree(config) {
   const defaultPath = "/root/wiki-git";
   return existsSync13(defaultPath) ? defaultPath : void 0;
 }
+var SNAPSHOT_SEMANTIC_TO_SYSTEMD = {
+  load_state: "LoadState",
+  unit_file_state: "UnitFileState",
+  active_state: "ActiveState",
+  sub_state: "SubState",
+  next_elapse: "NextElapseUSecRealtime",
+  result: "Result",
+  exec_main_status: "ExecMainStatus",
+  exec_main_code: "ExecMainCode",
+  active_enter_timestamp: "ActiveEnterTimestamp",
+  inactive_enter_timestamp: "InactiveEnterTimestamp",
+  exec_main_start_timestamp: "ExecMainStartTimestamp",
+  exec_main_exit_timestamp: "ExecMainExitTimestamp",
+  invocation_id: "InvocationID"
+};
+function semanticToSystemdProp(semantic) {
+  return SNAPSHOT_SEMANTIC_TO_SYSTEMD[semantic];
+}
+function normalizeSystemdValue(raw) {
+  if (raw == null) return void 0;
+  const v = raw.trim();
+  if (!v || v === "n/a" || v === "N/A") return void 0;
+  return v;
+}
+function hasCompletedRunEvidence(...timestamps) {
+  return timestamps.some((t) => normalizeSystemdValue(t ?? void 0) != null);
+}
+function loadSnapshotFixture(env) {
+  const path = env.VS_SNAPSHOT_HEALTH_FIXTURE;
+  if (!path || !existsSync13(path)) return null;
+  try {
+    return JSON.parse(readFileSync10(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function systemctlShowProperty(scope, unit, prop) {
+  try {
+    const cmd = scope === "system" ? `systemctl show ${unit} --property=${prop} --value` : `systemctl --user show ${unit} --property=${prop} --value`;
+    const out = execSync2(cmd, {
+      encoding: "utf8",
+      timeout: 2e3,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    return normalizeSystemdValue(out);
+  } catch {
+    return void 0;
+  }
+}
+function snapshotProp(kind, prop, fixture, scope) {
+  if (fixture) {
+    const bag = fixture[kind];
+    const v = bag[prop];
+    return v == null ? void 0 : String(v);
+  }
+  const unit = kind === "timer" ? "wiki-snapshot.timer" : "wiki-snapshot.service";
+  const liveProp = semanticToSystemdProp(prop);
+  if (!liveProp) return void 0;
+  return systemctlShowProperty(scope, unit, liveProp);
+}
+function parseIsoToMs(ts) {
+  if (!ts || ts === "MISSING") return null;
+  const ms = Date.parse(ts);
+  return Number.isFinite(ms) ? ms : null;
+}
+function ageMinutes(nowMs, tsMs) {
+  if (tsMs == null) return null;
+  return Math.floor((nowMs - tsMs) / 6e4);
+}
+function snapshotterHealthChecks(scope, logDir, env) {
+  const fixture = loadSnapshotFixture(env);
+  const cadence = fixture ? fixture.cadence_minutes : parseInt(env.VS_SNAPSHOT_CADENCE_MINUTES ?? "30", 10) || 30;
+  const timeout = fixture ? fixture.service_timeout_seconds : parseInt(env.VS_SNAPSHOT_SERVICE_TIMEOUT_SECONDS ?? "900", 10) || 900;
+  const nowMs = fixture ? Date.parse(fixture.now) : Date.now();
+  const warnAge = cadence * 2 + 15;
+  const errorAge = cadence * 4 + 15;
+  const tUnitfile = snapshotProp("timer", "unit_file_state", fixture, scope);
+  const tActive = snapshotProp("timer", "active_state", fixture, scope);
+  const tNext = snapshotProp("timer", "next_elapse", fixture, scope);
+  let jobs;
+  if (tUnitfile == null && tActive == null) {
+    jobs = check("warn", "vault_sync_jobs_enabled", "Vault sync jobs enabled", "wiki-snapshot.timer properties unavailable (read-only)");
+  } else if (tUnitfile === "enabled" && tActive === "active" && tNext) {
+    jobs = check("pass", "vault_sync_jobs_enabled", "Vault sync jobs enabled", `wiki-snapshot.timer enabled+active, next=${tNext} (${scope})`);
+  } else {
+    jobs = check("error", "vault_sync_jobs_enabled", "Vault sync jobs enabled", `wiki-snapshot.timer not eligible: unit_file_state=${tUnitfile ?? "missing"} active_state=${tActive ?? "missing"} next_elapse=${tNext ?? "missing"} (${scope})`);
+  }
+  const sActive = snapshotProp("service", "active_state", fixture, scope) ?? null;
+  const sResult = snapshotProp("service", "result", fixture, scope) ?? null;
+  const sExecMainStatus = snapshotProp("service", "exec_main_status", fixture, scope);
+  const sActiveEnter = snapshotProp("service", "active_enter_timestamp", fixture, scope) ?? null;
+  const sInactiveEnter = snapshotProp("service", "inactive_enter_timestamp", fixture, scope) ?? null;
+  const sExecMainStart = snapshotProp("service", "exec_main_start_timestamp", fixture, scope) ?? null;
+  const sExecMainExit = snapshotProp("service", "exec_main_exit_timestamp", fixture, scope) ?? null;
+  const completedEvidence = hasCompletedRunEvidence(sExecMainExit, sInactiveEnter, sActiveEnter);
+  let serviceResult;
+  if (sActive == null && sResult == null) {
+    serviceResult = check("warn", "vault_sync_snapshot_service_result", "Vault sync snapshot service result", "wiki-snapshot.service properties unavailable (read-only)");
+  } else if (sActive === "active" || sActive === "activating") {
+    const startMs = parseIsoToMs(sExecMainStart) ?? parseIsoToMs(sActiveEnter);
+    const runSec = startMs == null ? null : Math.floor((nowMs - startMs) / 1e3);
+    if (runSec != null && runSec > timeout) {
+      serviceResult = check("error", "vault_sync_snapshot_service_result", "Vault sync snapshot service result", `wiki-snapshot.service running ${runSec}s beyond timeout ${timeout}s`);
+    } else {
+      serviceResult = check("pass", "vault_sync_snapshot_service_result", "Vault sync snapshot service result", `wiki-snapshot.service in progress (running ${runSec ?? "?"}s)`);
+    }
+  } else if (sResult === "success" && (sExecMainStatus ?? "0") === "0" && completedEvidence) {
+    serviceResult = check("pass", "vault_sync_snapshot_service_result", "Vault sync snapshot service result", "wiki-snapshot.service result=success ExecMainStatus=0");
+  } else if (sResult === "failed" || sExecMainStatus != null && sExecMainStatus !== "0") {
+    serviceResult = check("error", "vault_sync_snapshot_service_result", "Vault sync snapshot service result", `wiki-snapshot.service result=${sResult ?? "missing"} ExecMainStatus=${sExecMainStatus ?? "missing"}`);
+  } else {
+    serviceResult = check("warn", "vault_sync_snapshot_service_result", "Vault sync snapshot service result", `wiki-snapshot.service result=${sResult ?? "missing"} (never ran or unrecognized)`);
+  }
+  let completionTs = null;
+  let completionOutcome = "unknown";
+  const logRecords = fixture ? fixture.log_records : (() => {
+    try {
+      const content = readFileSync10(join25(logDir, "wiki-snapshot.log"), "utf8");
+      return content.split(/\r?\n/).filter(Boolean);
+    } catch {
+      return [];
+    }
+  })();
+  for (let i = logRecords.length - 1; i >= 0; i--) {
+    const m = logRecords[i].match(/SNAPSHOT_COMPLETE schema=v1 .*ts=(\S+)/);
+    if (m) {
+      completionTs = m[1];
+      const om = logRecords[i].match(/outcome=(\S+)/);
+      if (om) completionOutcome = om[1];
+      break;
+    }
+  }
+  let freshness;
+  if (!completionTs || completionTs === "MISSING") {
+    if (sActive === "active" || sActive === "activating") {
+      freshness = check("warn", "vault_sync_last_push_age", "Vault sync last snapshot recency", "snapshot in progress; no prior canonical completion record");
+    } else {
+      freshness = check("error", "vault_sync_last_push_age", "Vault sync last snapshot recency", "no canonical SNAPSHOT_COMPLETE record found");
+    }
+  } else {
+    const ageMin = ageMinutes(nowMs, parseIsoToMs(completionTs));
+    if (ageMin == null) {
+      freshness = check("error", "vault_sync_last_push_age", "Vault sync last snapshot recency", `unparseable completion timestamp: ${completionTs}`);
+    } else if (ageMin <= warnAge) {
+      freshness = check("pass", "vault_sync_last_push_age", "Vault sync last snapshot recency", `last snapshot ${ageMin}m ago (outcome=${completionOutcome}, <=${warnAge}m)`);
+    } else if (ageMin <= errorAge) {
+      freshness = check("warn", "vault_sync_last_push_age", "Vault sync last snapshot recency", `last snapshot ${ageMin}m ago (outcome=${completionOutcome}, >${warnAge}m)`);
+    } else {
+      freshness = check("error", "vault_sync_last_push_age", "Vault sync last snapshot recency", `last snapshot ${ageMin}m ago (outcome=${completionOutcome}, >${errorAge}m)`);
+    }
+  }
+  if (serviceResult.status === "error" && sActive !== "active" && sActive !== "activating") {
+    freshness = check("error", "vault_sync_last_push_age", "Vault sync last snapshot recency", `latest service result failed: ${serviceResult.detail}`);
+  }
+  let failCount = 0;
+  let mostRecentFail = "";
+  for (let i = logRecords.length - 1; i >= 0 && i >= logRecords.length - 60; i--) {
+    const line = logRecords[i];
+    if (/SNAPSHOT_COMPLETE schema=v1/.test(line)) break;
+    if (/ERROR/.test(line)) {
+      failCount++;
+      if (!mostRecentFail) {
+        const m = line.match(/^(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2})/);
+        mostRecentFail = m ? m[1] : "unknown";
+      }
+    }
+  }
+  const consecutiveFailures = failCount >= 2 ? check("error", "vault_sync_snapshot_consecutive_failures", "Vault sync snapshot consecutive failures", `${failCount} consecutive snapshot failure(s); most recent: ${mostRecentFail || "unknown"}`) : check("pass", "vault_sync_snapshot_consecutive_failures", "Vault sync snapshot consecutive failures", `${failCount} consecutive failure(s) in recent window (recurrence threshold: 2)`);
+  return [jobs, serviceResult, freshness, consecutiveFailures];
+}
 function vaultSyncChecks(input) {
   const os = input.os ?? platform2();
   const home = input.home;
@@ -6525,7 +6699,9 @@ function vaultSyncChecks(input) {
     return [
       skip("vault_sync_installed", "Vault sync installed"),
       skip("vault_sync_jobs_enabled", "Vault sync jobs enabled"),
+      skip("vault_sync_snapshot_service_result", "Vault sync snapshot service result"),
       skip("vault_sync_last_push_age", "Vault sync last push recency"),
+      skip("vault_sync_snapshot_consecutive_failures", "Vault sync snapshot consecutive failures"),
       skip("vault_sync_last_fetch_status", "Vault sync last fetch status"),
       skip("vault_sync_filter_present", "Vault sync filter file present"),
       skip("vault_sync_snapshot_guard", "Snapshot script guard")
@@ -6538,79 +6714,10 @@ function vaultSyncChecks(input) {
   const packagedSnapshotPath = join25(shareDir, "wiki-snapshot.sh");
   const legacySnapshotPath = "/root/.hermes/scripts/wiki-snapshot-v3.sh";
   const snapshotPath = input.snapshotScriptPath ?? (existsSync13(packagedSnapshotPath) ? packagedSnapshotPath : legacySnapshotPath);
-  function snapshotLastStatusCheck() {
-    const snapshotLog = join25(logDir, "wiki-snapshot.log");
-    try {
-      const logContent = readFileSync10(snapshotLog, "utf8");
-      const lines = logContent.trim().split("\n").filter(Boolean);
-      if (lines.length === 0) {
-        return check(
-          "warn",
-          "vault_sync_last_push_age",
-          "Vault sync last snapshot status",
-          "Snapshot log file is empty"
-        );
-      }
-      const lastLine = [...lines].reverse().find(
-        (line) => /ERROR|Status: complete|Push successful|No changes to commit/.test(line)
-      ) ?? lines[lines.length - 1];
-      if (/ERROR/.test(lastLine)) {
-        return check(
-          "error",
-          "vault_sync_last_push_age",
-          "Vault sync last snapshot status",
-          `Last snapshot failed: ${lastLine.slice(0, 160)}`
-        );
-      }
-      if (/Status: complete|Push successful|No changes to commit/.test(lastLine)) {
-        return check(
-          "pass",
-          "vault_sync_last_push_age",
-          "Vault sync last snapshot status",
-          lastLine.slice(0, 160)
-        );
-      }
-      return check(
-        "warn",
-        "vault_sync_last_push_age",
-        "Vault sync last snapshot status",
-        `Last snapshot log entry: ${lastLine.slice(0, 160)}`
-      );
-    } catch {
-      return check(
-        "warn",
-        "vault_sync_last_push_age",
-        "Vault sync last snapshot status",
-        `Snapshot log not found at ${snapshotLog}`
-      );
-    }
-  }
   if (input.vaultSyncRole === "snapshotter") {
     const c12 = existsSync13(snapshotPath) ? check("pass", "vault_sync_installed", "Vault sync installed", `Found snapshot script: ${snapshotPath}`) : check("error", "vault_sync_installed", "Vault sync installed", `Snapshot script not found at ${snapshotPath}`);
     const serviceScope = input.vaultSyncServiceScope ?? "user";
-    const userTimerPath = join25(home, ".config", "systemd", "user", "wiki-snapshot.timer");
-    const systemTimerPath = "/etc/systemd/system/wiki-snapshot.timer";
-    let c22;
-    if (serviceScope === "user" && existsSync13(userTimerPath)) {
-      c22 = check("pass", "vault_sync_jobs_enabled", "Vault sync jobs enabled", `Found: ${userTimerPath}`);
-    } else if (serviceScope === "system" && existsSync13(systemTimerPath)) {
-      c22 = check("pass", "vault_sync_jobs_enabled", "Vault sync jobs enabled", `Found: ${systemTimerPath}`);
-    } else if (os !== "linux") {
-      c22 = check("warn", "vault_sync_jobs_enabled", "Vault sync jobs enabled", "Snapshotter scheduler is Linux-only and no wiki-snapshot.timer file was found");
-    } else {
-      try {
-        const command = serviceScope === "system" ? "systemctl is-enabled wiki-snapshot.timer" : "systemctl --user is-enabled wiki-snapshot.timer";
-        const out = execSync2(command, {
-          encoding: "utf8",
-          timeout: 2e3,
-          stdio: ["pipe", "pipe", "pipe"]
-        }).trim();
-        c22 = out === "enabled" ? check("pass", "vault_sync_jobs_enabled", "Vault sync jobs enabled", `systemd: wiki-snapshot.timer enabled (${serviceScope})`) : check("error", "vault_sync_jobs_enabled", "Vault sync jobs enabled", `systemd: wiki-snapshot.timer is ${out || "not enabled"} (${serviceScope})`);
-      } catch {
-        c22 = check("error", "vault_sync_jobs_enabled", "Vault sync jobs enabled", `wiki-snapshot.timer check failed (${serviceScope})`);
-      }
-    }
-    const c32 = snapshotLastStatusCheck();
+    const healthChecks = snapshotterHealthChecks(serviceScope, logDir, input.env ?? process.env);
     const cFetch2 = check(
       "pass",
       "vault_sync_last_fetch_status",
@@ -6658,7 +6765,7 @@ function vaultSyncChecks(input) {
         `Cannot read ${snapshotPath}`
       );
     }
-    return [c12, c22, c32, cFetch2, c42, c52];
+    return [c12, ...healthChecks, cFetch2, c42, c52];
   }
   const pushScriptPath = join25(shareDir, "wiki-push.sh");
   const c1 = existsSync13(pushScriptPath) ? check("pass", "vault_sync_installed", "Vault sync installed", `Found: ${pushScriptPath}`) : check("error", "vault_sync_installed", "Vault sync installed", `Script not found at ${pushScriptPath} \u2014 run vault-sync-install`);
@@ -7075,7 +7182,8 @@ async function runDoctor(input) {
     vaultSyncInstalled: vsConfig.installed,
     vaultSyncRole: vsConfig.role,
     vaultSyncServiceScope: vsConfig.serviceScope,
-    snapshotScriptPath: vsConfig.snapshotScript
+    snapshotScriptPath: vsConfig.snapshotScript,
+    env: input.env ?? process.env
   }));
   checks.push(checkVaultSyncPullHelper(input.home, input.env ?? process.env));
   checks.push(checkVaultSyncReviewRequiredJournals(resolvedPath));
@@ -9915,6 +10023,7 @@ export {
   isFailedRunStatus,
   readSatelliteLatestRunFromText,
   evaluateSatelliteRunHealth,
+  snapshotterHealthChecks,
   runDoctor,
   readCliPackageJson,
   DEFAULT_DIRTY_VOLUME_THRESHOLD,

package/dist/{chunk-E3PMAHS3.js → chunk-OWPQJOFG.js}

@@ -715,6 +715,10 @@ function canSupersedeJournalInContext(vault, fields, head) {
   if (!target) return false;
   return gitMergeBaseIsAncestor(vault, target, head);
 }
+function canSupersedeJournal(vault, fields, opts = {}) {
+  const head = journalSupersedeHead(vault, opts.requireClean !== false);
+  return canSupersedeJournalInContext(vault, fields, head);
+}
 function gitMergeBaseIsAncestor(vault, ancestor, tip) {
   if (ancestor === tip) return true;
   const mb = git(vault, ["merge-base", ancestor, tip]);
@@ -887,6 +891,9 @@ export {
   findReviewRequiredOp,
   hasUnmergedPaths,
   hasActiveGitSequencer,
+  isWorktreeClean,
+  canSupersedeJournal,
+  markJournalSuperseded,
   supersedeStaleReviewRequiredJournals,
   resolveVaultSyncPullHelper,
   runVaultSyncPullHelper

package/dist/{chunk-IIUMTKKA.js → chunk-UJLSUJB6.js}

@@ -8,7 +8,7 @@ import {
   loadFleetManifestAndHost,
   runVaultSyncPullHelper,
   supersedeStaleReviewRequiredJournals
-} from "./chunk-E3PMAHS3.js";
+} from "./chunk-OWPQJOFG.js";
 import {
   ExitCode,
   err,

package/dist/cli.js

@@ -78,11 +78,12 @@ import {
   safeWritePage,
   satelliteLatestRunPath,
   scanConflictMarkerBlocksInText,
+  snapshotterHealthChecks,
   taxonomyCommentForPage,
   upsertIndexEntry,
   validateLogEvent,
   writeLogEvent
-} from "./chunk-X2CPXF4T.js";
+} from "./chunk-24MVNAFJ.js";
 import {
   normalizeDistTag,
   readCache,
@@ -110,15 +111,20 @@ import {
   releaseManagedWriteLock,
   runManagedWritePreflight,
   runManagedWriteTransaction
-} from "./chunk-IIUMTKKA.js";
+} from "./chunk-UJLSUJB6.js";
 import {
   FLEET_REL_PATH,
+  canSupersedeJournal,
   git,
   gitStrict,
+  hasActiveGitSequencer,
+  hasUnmergedPaths,
+  isWorktreeClean,
   listJournalOpIds,
   listReviewRequiredOps,
   loadFleetManifest,
   loadFleetManifestAndHost,
+  markJournalSuperseded,
   parseDotenvFile,
   parseDotenvText,
   parseJournalEnv,
@@ -132,7 +138,7 @@ import {
   snapshotterAliasForLocalHost,
   supersedeStaleReviewRequiredJournals,
   writeDotenv
-} from "./chunk-E3PMAHS3.js";
+} from "./chunk-OWPQJOFG.js";
 import {
   ExitCode,
   MetaSchema,
@@ -143,7 +149,7 @@ import {
 } from "./chunk-C5OLZRRM.js";
 
 // src/cli.ts
-import { join as join36 } from "path";
+import { join as join37 } from "path";
 import { Command } from "commander";
 
 // src/utils/output.ts
@@ -2662,7 +2668,30 @@ function classifyLog(path, id, label, okPattern) {
   if (okPattern.test(last)) return { id, label, status: "pass", detail: last.slice(0, 120) };
   return { id, label, status: "warn", detail: last.slice(0, 120) };
 }
-function runVaultSyncHealth(home, syncMode) {
+function readVaultSyncRoleAndScope(home) {
+  try {
+    const content = readFileSync11(join17(home, ".skillwiki", ".env"), "utf8");
+    let role;
+    let serviceScope;
+    let snapshotScript;
+    for (const line of content.split(/\r?\n/)) {
+      const trimmed = line.trim();
+      if (trimmed.length === 0 || trimmed.startsWith("#")) continue;
+      const eq = trimmed.indexOf("=");
+      if (eq <= 0) continue;
+      const k = trimmed.slice(0, eq).trim();
+      const v = trimmed.slice(eq + 1).trim();
+      if (v.length === 0) continue;
+      if (k === "vault_sync.role") role = v;
+      if (k === "vault_sync.service_scope") serviceScope = v;
+      if (k === "vault_sync.snapshot_script") snapshotScript = v;
+    }
+    return { role, serviceScope, snapshotScript };
+  } catch {
+    return {};
+  }
+}
+function runVaultSyncHealth(home, syncMode, env = process.env) {
   if (syncMode === "off") {
     return {
       status: "pass",
@@ -2691,6 +2720,30 @@ function runVaultSyncHealth(home, syncMode) {
       }]
     };
   }
+  const vsConfig = readVaultSyncRoleAndScope(home);
+  if (vsConfig.role === "snapshotter") {
+    const snapshotScript = vsConfig.snapshotScript ?? join17(shareDir, "wiki-snapshot.sh");
+    const installed = existsSync5(snapshotScript) ? { id: "vault_sync_installed", label: "Vault sync installed", status: "pass", detail: `Found snapshot script: ${snapshotScript}` } : { id: "vault_sync_installed", label: "Vault sync installed", status: "error", detail: `Snapshot script not found at ${snapshotScript}` };
+    const healthChecks = snapshotterHealthChecks(vsConfig.serviceScope ?? "user", logDir, env);
+    const fetchNA = { id: "vault_sync_last_fetch_status", label: "Vault sync last fetch status", status: "pass", detail: "Snapshotter host \u2014 leaf wiki-fetch-notify log not applicable" };
+    const filterNA = { id: "vault_sync_filter_present", label: "Vault sync filter file present", status: "pass", detail: "Snapshotter host \u2014 leaf wiki-push filter not applicable" };
+    let guard;
+    if (!existsSync5(snapshotScript)) {
+      guard = { id: "vault_sync_snapshot_guard", label: "Snapshot script guard", status: "error", detail: `Snapshot script not found at ${snapshotScript}` };
+    } else {
+      const content = readFileSync11(snapshotScript, "utf8");
+      guard = content.includes("--max-delete") ? { id: "vault_sync_snapshot_guard", label: "Snapshot script guard", status: "pass", detail: `--max-delete present in ${snapshotScript}` } : { id: "vault_sync_snapshot_guard", label: "Snapshot script guard", status: "error", detail: `${snapshotScript} is missing --max-delete guard` };
+    }
+    const allChecks = [installed, ...healthChecks, fetchNA, filterNA, guard];
+    const summary2 = summarizeChecks(allChecks);
+    return {
+      status: statusFromCounts(summary2),
+      blocking: syncMode === "required",
+      installed: installed.status === "pass",
+      summary: summary2,
+      checks: allChecks.map((c) => ({ id: c.id, status: c.status, detail: c.detail }))
+    };
+  }
   checks.push(existsSync5(pushScript) ? { id: "vault_sync_installed", label: "Vault sync installed", status: "pass", detail: `Found: ${pushScript}` } : { id: "vault_sync_installed", label: "Vault sync installed", status: "error", detail: `Script missing: ${pushScript}` });
   if (isMac) {
     const pushPlist = join17(home, "Library", "LaunchAgents", "com.karlchow.wiki-push.plist");
@@ -6503,9 +6556,352 @@ function runSyncJournalClearStale(input) {
   };
 }
 
+// src/commands/snapshot-maintenance.ts
+import { existsSync as existsSync9, readFileSync as readFileSync13, mkdirSync as mkdirSync3, appendFileSync } from "fs";
+import { createHash as createHash5 } from "crypto";
+import { execSync as execSync3, spawn } from "child_process";
+import { platform as platform2 } from "os";
+import { join as join30, resolve as resolvePath2 } from "path";
+var MAINTENANCE_SCHEMA_VERSION = 1;
+var MAINTENANCE_COMMAND = "snapshot-maintenance journal clear-stale";
+function resolveConfiguredSnapshotWorktree(home) {
+  const skillwikiEnv = join30(home, ".skillwiki", ".env");
+  const explicit = readEnvKey2(skillwikiEnv, ["vault_sync.snapshot_worktree"]);
+  if (explicit) return resolvePath2(explicit);
+  const snapshotProfile = readEnvKey2(skillwikiEnv, ["vault_sync.snapshot_profile"]);
+  if (snapshotProfile) {
+    const fromProfile = readEnvKey2(snapshotProfile, ["WIKI_GIT_WORKTREE", "SNAPSHOT_WORKTREE", "GIT_DIR"]);
+    if (fromProfile) return resolvePath2(fromProfile);
+  }
+  return void 0;
+}
+function readEnvKey2(path, keys) {
+  try {
+    const content = readFileSync13(path, "utf8");
+    for (const line of content.split(/\r?\n/)) {
+      const trimmed = line.trim();
+      if (trimmed.length === 0 || trimmed.startsWith("#")) continue;
+      const eq = trimmed.indexOf("=");
+      if (eq <= 0) continue;
+      const key = trimmed.slice(0, eq).trim();
+      if (!keys.includes(key)) continue;
+      const value = trimmed.slice(eq + 1).trim();
+      if (value.length > 0) return value;
+    }
+  } catch {
+    return void 0;
+  }
+  return void 0;
+}
+function canonicalize(p) {
+  return resolvePath2(p);
+}
+function computeApprovalId(plan) {
+  const eligible = [...plan.eligible_journals].sort((a, b) => a.operation_id.localeCompare(b.operation_id));
+  const targets = eligible.map((j) => `${j.operation_id}:${j.target_oid}`).join(",");
+  const payload = [
+    `v${plan.schema_version}`,
+    plan.command,
+    plan.host_id,
+    plan.role,
+    plan.snapshot_worktree,
+    plan.snapshot_lock_path,
+    plan.git_directory,
+    plan.branch,
+    plan.head_oid,
+    targets,
+    normalizeReason(plan.operator_reason)
+  ].join("|");
+  return "smap1-" + createHash5("sha256").update(payload).digest("hex").slice(0, 32);
+}
+function normalizeReason(reason) {
+  return reason.trim().replace(/\s+/g, " ");
+}
+function refusalErr(code, reason, guidance) {
+  return err(code, { reason, guidance: guidance ?? "" });
+}
+async function runSnapshotMaintenanceDryRun(input) {
+  const env = input.env ?? process.env;
+  const home = input.home ?? env.HOME ?? "";
+  const audit = input.auditSink ?? defaultAuditSink(home);
+  const now = input.now ?? Date.now();
+  const fleetLoad = input.fleetLoad !== void 0 ? input.fleetLoad : await loadFleetManifestAndHost({
+    vault: input.liveVaultPath ?? "",
+    env,
+    home,
+    cwd: process.cwd(),
+    osHostname: env.HOSTNAME,
+    user: env.USER
+  });
+  if (!fleetLoad || !fleetLoad.hostId || fleetLoad.identityStatus !== "known") {
+    audit(makeAuditEvent(input, fleetLoad?.hostId ?? "unknown", now, "refusal", "MAINTENANCE_UNKNOWN_IDENTITY"));
+    return { exitCode: ExitCode.PROTECTED_SNAPSHOTTER_WRITE_BLOCKED, result: refusalErr("MAINTENANCE_UNKNOWN_IDENTITY", "unknown or unresolved fleet identity; cannot authorize snapshot maintenance") };
+  }
+  const host = fleetLoad.manifest.hosts[fleetLoad.hostId];
+  if (!host || host.role !== "snapshotter" || host.protected !== true) {
+    audit(makeAuditEvent(input, fleetLoad.hostId, now, "refusal", "MAINTENANCE_NOT_PROTECTED_SNAPSHOTTER"));
+    return { exitCode: ExitCode.PROTECTED_SNAPSHOTTER_WRITE_BLOCKED, result: refusalErr("MAINTENANCE_NOT_PROTECTED_SNAPSHOTTER", `host '${fleetLoad.hostId}' is not a protected snapshotter (role=${host?.role ?? "missing"}, protected=${host?.protected ?? false})`) };
+  }
+  const configuredWorktree = resolveConfiguredSnapshotWorktree(home);
+  if (!configuredWorktree) {
+    audit(makeAuditEvent(input, fleetLoad.hostId, now, "refusal", "MAINTENANCE_NO_CONFIGURED_WORKTREE"));
+    return { exitCode: ExitCode.PROTECTED_SNAPSHOTTER_WRITE_BLOCKED, result: refusalErr("MAINTENANCE_NO_CONFIGURED_WORKTREE", "no configured snapshot worktree (vault_sync.snapshot_worktree or snapshot_profile required)") };
+  }
+  const requested = canonicalize(input.snapshotWorktree);
+  if (requested !== canonicalize(configuredWorktree)) {
+    audit(makeAuditEvent(input, fleetLoad.hostId, now, "refusal", "MAINTENANCE_WRONG_WORKTREE"));
+    return { exitCode: ExitCode.PROTECTED_SNAPSHOTTER_WRITE_BLOCKED, result: refusalErr("MAINTENANCE_WRONG_WORKTREE", `requested path '${requested}' is not the configured snapshot worktree '${canonicalize(configuredWorktree)}'`) };
+  }
+  if (!existsSync9(requested) || !existsSync9(join30(requested, ".git"))) {
+    audit(makeAuditEvent(input, fleetLoad.hostId, now, "refusal", "MAINTENANCE_MISSING_GIT_REPO"));
+    return { exitCode: ExitCode.PROTECTED_SNAPSHOTTER_WRITE_BLOCKED, result: refusalErr("MAINTENANCE_MISSING_GIT_REPO", `snapshot worktree is not a git repository: ${requested}`) };
+  }
+  const liveVaultPath = input.liveVaultPath ? canonicalize(input.liveVaultPath) : await resolveLiveVault({ env, home });
+  if (liveVaultPath && requested === canonicalize(liveVaultPath)) {
+    audit(makeAuditEvent(input, fleetLoad.hostId, now, "refusal", "MAINTENANCE_LIVE_VAULT_TARGET"));
+    return { exitCode: ExitCode.PROTECTED_SNAPSHOTTER_WRITE_BLOCKED, result: refusalErr("MAINTENANCE_LIVE_VAULT_TARGET", "requested path is the live vault, not the snapshot worktree") };
+  }
+  const branch = git(requested, ["rev-parse", "--abbrev-ref", "HEAD"]) || "HEAD";
+  const headOid = git(requested, ["rev-parse", "HEAD"]) || "";
+  const gitDirectory = git(requested, ["rev-parse", "--absolute-git-dir"]) || "";
+  const worktreeClean = isWorktreeClean(requested);
+  const activeSequencer = hasActiveGitSequencer(requested);
+  const unmerged = hasUnmergedPaths(requested);
+  const reviewRequired = listReviewRequiredOps(requested);
+  const eligible = [];
+  const skipped = [];
+  for (const { opId, fields } of reviewRequired) {
+    const target = fields.target_oid?.trim();
+    if (!target) {
+      skipped.push({ operation_id: opId, target_oid: "", reason: fields.reason, prior_reason: fields.prior_reason, eligible: false, refusal_reason: "missing-target-oid" });
+      continue;
+    }
+    if (!canSupersedeJournal(requested, fields, { requireClean: false })) {
+      let refusal = "not-ancestor";
+      if (activeSequencer) refusal = "active-sequencer";
+      else if (unmerged.length > 0) refusal = "unmerged-paths";
+      else if (!gitMergeBaseIsAncestor(requested, target, headOid)) refusal = "not-ancestor";
+      skipped.push({ operation_id: opId, target_oid: target, reason: fields.reason, prior_reason: fields.prior_reason, eligible: false, refusal_reason: refusal });
+      continue;
+    }
+    eligible.push({ operation_id: opId, target_oid: target, reason: fields.reason, prior_reason: fields.prior_reason, eligible: true });
+  }
+  const snapshotLockPath = input.snapshotLockPath ?? "/var/lock/wiki-snapshot.lock";
+  const planBase = {
+    schema_version: MAINTENANCE_SCHEMA_VERSION,
+    command: MAINTENANCE_COMMAND,
+    host_id: fleetLoad.hostId,
+    role: host.role,
+    protected: host.protected === true,
+    snapshot_worktree: requested,
+    snapshot_lock_path: snapshotLockPath,
+    git_directory: gitDirectory,
+    branch,
+    head_oid: headOid,
+    worktree_clean: worktreeClean,
+    active_sequencer: activeSequencer,
+    unmerged_paths: unmerged,
+    eligible_journals: eligible,
+    skipped_journals: skipped,
+    operator_reason: normalizeReason(input.reason ?? "")
+  };
+  const approvalId = eligible.length > 0 ? computeApprovalId(planBase) : null;
+  const plan = { ...planBase, approval_id: approvalId };
+  audit(makeAuditEvent(input, fleetLoad.hostId, now, "dry-run", void 0, approvalId ?? void 0));
+  return {
+    exitCode: ExitCode.OK,
+    result: ok({
+      dry_run: true,
+      plan,
+      humanHint: eligible.length === 0 ? `dry-run: 0 eligible journals; skipped=${skipped.length}` : `dry-run: ${eligible.length} eligible journal(s); approval_id=${approvalId}`
+    })
+  };
+}
+function gitMergeBaseIsAncestor(repo, ancestor, tip) {
+  if (ancestor === tip) return true;
+  const mb = git(repo, ["merge-base", ancestor, tip]);
+  return mb !== "" && mb === ancestor;
+}
+async function resolveLiveVault(input) {
+  const resolved = await resolveRuntimePath({
+    flag: void 0,
+    envValue: input.env.WIKI_PATH,
+    wikiEnv: input.env.WIKI,
+    home: input.home,
+    cwd: process.cwd()
+  });
+  return resolved.ok ? canonicalize(resolved.data.path) : void 0;
+}
+function snapshotMaintenanceAuditLogPath(home) {
+  const stateDir = platform2() === "darwin" ? join30(home, "Library", "Application Support", "vault-sync") : join30(home, ".local", "state", "vault-sync");
+  return join30(stateDir, "snapshot-maintenance-audit.jsonl");
+}
+function defaultAuditSink(home) {
+  return (event) => {
+    try {
+      const logPath = snapshotMaintenanceAuditLogPath(home);
+      mkdirSync3(join30(logPath, ".."), { recursive: true });
+      appendFileSync(logPath, JSON.stringify(event) + "\n", { encoding: "utf8" });
+    } catch {
+    }
+  };
+}
+function makeAuditEvent(input, hostId, now, result, errorCode, approvalId) {
+  return {
+    ts: new Date(now).toISOString(),
+    schema_version: MAINTENANCE_SCHEMA_VERSION,
+    command: MAINTENANCE_COMMAND,
+    host: hostId,
+    actor: input.env?.USER ?? process.env.USER ?? "unknown",
+    session: input.sessionId ?? "unknown",
+    canonical_target: canonicalize(input.snapshotWorktree),
+    reason: normalizeReason(input.reason ?? ""),
+    approval_id: approvalId,
+    result,
+    error_code: errorCode
+  };
+}
+async function runSnapshotMaintenanceExecute(input) {
+  const env = input.env ?? process.env;
+  const home = input.home ?? env.HOME ?? "";
+  const audit = input.auditSink ?? defaultAuditSink(home);
+  const now = input.now ?? Date.now();
+  const isTty = input.isTty ?? !!process.stdin.isTTY;
+  if (!isTty) {
+    audit(makeAuditEvent(input, "unknown", now, "refusal", "MAINTENANCE_NO_TTY"));
+    return { exitCode: ExitCode.PROTECTED_SNAPSHOTTER_WRITE_BLOCKED, result: refusalErr("MAINTENANCE_NO_TTY", "snapshot maintenance requires an attended TTY") };
+  }
+  const reason = normalizeReason(input.reason ?? "");
+  if (!reason) {
+    audit(makeAuditEvent(input, "unknown", now, "refusal", "MAINTENANCE_NO_REASON"));
+    return { exitCode: ExitCode.PROTECTED_SNAPSHOTTER_WRITE_BLOCKED, result: refusalErr("MAINTENANCE_NO_REASON", "snapshot maintenance requires a non-empty operator reason") };
+  }
+  if (!input.approvalId) {
+    audit(makeAuditEvent(input, "unknown", now, "refusal", "MAINTENANCE_NO_APPROVAL_ID"));
+    return { exitCode: ExitCode.PROTECTED_SNAPSHOTTER_WRITE_BLOCKED, result: refusalErr("MAINTENANCE_NO_APPROVAL_ID", "snapshot maintenance requires an approval ID from a prior dry run") };
+  }
+  const dryRunResult = await runSnapshotMaintenanceDryRun(input);
+  if (!dryRunResult.result.ok) return dryRunResult;
+  const plan = dryRunResult.result.data.plan;
+  if (!plan.approval_id) {
+    audit(makeAuditEvent(input, plan.host_id, now, "refusal", "MAINTENANCE_NO_ELIGIBLE_JOURNALS"));
+    return { exitCode: ExitCode.PROTECTED_SNAPSHOTTER_WRITE_BLOCKED, result: refusalErr("MAINTENANCE_NO_ELIGIBLE_JOURNALS", "no eligible journals to supersede") };
+  }
+  if (plan.approval_id !== input.approvalId) {
+    audit(makeAuditEvent(input, plan.host_id, now, "refusal", "MAINTENANCE_STALE_APPROVAL_ID"));
+    return { exitCode: ExitCode.PROTECTED_SNAPSHOTTER_WRITE_BLOCKED, result: refusalErr("MAINTENANCE_STALE_APPROVAL_ID", "approval ID does not match the current state; rerun dry run") };
+  }
+  if (!plan.worktree_clean) {
+    audit(makeAuditEvent(input, plan.host_id, now, "refusal", "MAINTENANCE_DIRTY_WORKTREE"));
+    return { exitCode: ExitCode.PROTECTED_SNAPSHOTTER_WRITE_BLOCKED, result: refusalErr("MAINTENANCE_DIRTY_WORKTREE", "snapshot worktree is dirty") };
+  }
+  if (plan.active_sequencer) {
+    audit(makeAuditEvent(input, plan.host_id, now, "refusal", "MAINTENANCE_ACTIVE_SEQUENCER"));
+    return { exitCode: ExitCode.PROTECTED_SNAPSHOTTER_WRITE_BLOCKED, result: refusalErr("MAINTENANCE_ACTIVE_SEQUENCER", "git sequencer (merge/rebase/cherry-pick/revert) is active") };
+  }
+  if (plan.unmerged_paths.length > 0) {
+    audit(makeAuditEvent(input, plan.host_id, now, "refusal", "MAINTENANCE_UNMERGED_PATHS"));
+    return { exitCode: ExitCode.PROTECTED_SNAPSHOTTER_WRITE_BLOCKED, result: refusalErr("MAINTENANCE_UNMERGED_PATHS", `unmerged paths: ${plan.unmerged_paths.join(", ")}`) };
+  }
+  if (!input.skipFlock) {
+    const flockResult = acquireSnapshotFlock(plan.snapshot_lock_path);
+    if (!flockResult.acquired) {
+      audit(makeAuditEvent(input, plan.host_id, now, "refusal", "MAINTENANCE_FLOCK_BUSY"));
+      return { exitCode: ExitCode.PROTECTED_SNAPSHOTTER_WRITE_BLOCKED, result: refusalErr("MAINTENANCE_FLOCK_BUSY", `snapshot flock busy: ${plan.snapshot_lock_path}`) };
+    }
+    try {
+      return await performSupersession(input, plan, audit, now);
+    } finally {
+      releaseSnapshotFlock(flockResult);
+    }
+  }
+  return performSupersession(input, plan, audit, now);
+}
+async function performSupersession(input, plan, audit, now) {
+  const reDryRun = await runSnapshotMaintenanceDryRun(input);
+  if (!reDryRun.result.ok) return reDryRun;
+  const recomputed = reDryRun.result.data.plan;
+  if (recomputed.head_oid !== plan.head_oid) {
+    audit(makeAuditEvent(input, plan.host_id, now, "refusal", "MAINTENANCE_HEAD_CHANGED"));
+    return { exitCode: ExitCode.PROTECTED_SNAPSHOTTER_WRITE_BLOCKED, result: refusalErr("MAINTENANCE_HEAD_CHANGED", "HEAD changed after dry run") };
+  }
+  const reEligible = new Set(recomputed.eligible_journals.map((j) => j.operation_id));
+  const approvedSet = new Set(plan.eligible_journals.map((j) => j.operation_id));
+  for (const id of approvedSet) {
+    if (!reEligible.has(id)) {
+      audit(makeAuditEvent(input, plan.host_id, now, "refusal", "MAINTENANCE_JOURNAL_SET_CHANGED"));
+      return { exitCode: ExitCode.PROTECTED_SNAPSHOTTER_WRITE_BLOCKED, result: refusalErr("MAINTENANCE_JOURNAL_SET_CHANGED", `approved journal '${id}' is no longer eligible`) };
+    }
+  }
+  const superseded = [];
+  const skipped = [];
+  for (const j of plan.eligible_journals) {
+    const fields = readJournal(plan.snapshot_worktree, j.operation_id);
+    if (!fields) {
+      skipped.push(j.operation_id);
+      continue;
+    }
+    if (fields.target_oid?.trim() !== j.target_oid) {
+      skipped.push(j.operation_id);
+      continue;
+    }
+    const by = `snapshot-maintenance:${input.env?.USER ?? process.env.USER ?? "unknown"}:${input.sessionId ?? "unknown"}`;
+    if (markJournalSuperseded(plan.snapshot_worktree, j.operation_id, fields, by)) {
+      superseded.push(j.operation_id);
+    } else {
+      skipped.push(j.operation_id);
+    }
+  }
+  const noOp = superseded.length === 0;
+  const result = {
+    superseded,
+    skipped,
+    approval_id: plan.approval_id,
+    no_op: noOp
+  };
+  audit(makeAuditEvent(input, plan.host_id, now, noOp ? "no-op" : "success", void 0, plan.approval_id ?? void 0));
+  return {
+    exitCode: ExitCode.OK,
+    result: ok({
+      dry_run: false,
+      execution: result,
+      humanHint: noOp ? `execution: no-op (0 superseded; skipped=${skipped.length})` : `execution: ${superseded.length} journal(s) superseded; skipped=${skipped.length}`
+    })
+  };
+}
+function acquireSnapshotFlock(lockPath) {
+  try {
+    const child = spawn("bash", ["-c", `exec 9>"${lockPath}"; flock -n 9 || exit 1; while true; do sleep 3600; done`], {
+      stdio: ["pipe", "pipe", "pipe"],
+      detached: false
+    });
+    const deadline = Date.now() + 300;
+    while (Date.now() < deadline) {
+      if (child.exitCode !== null) {
+        return { acquired: false, path: lockPath };
+      }
+      try {
+        execSync3("sleep 0.05", { timeout: 200 });
+      } catch {
+      }
+    }
+    return { acquired: true, path: lockPath, holder: { kill: () => child.kill("SIGTERM") } };
+  } catch {
+    return { acquired: false, path: lockPath };
+  }
+}
+function releaseSnapshotFlock(handle) {
+  if (handle.holder) {
+    try {
+      handle.holder.kill();
+    } catch {
+    }
+  }
+}
+
 // src/commands/backup.ts
-import { statSync as statSync2, readdirSync as readdirSync2, readFileSync as readFileSync13, mkdirSync as mkdirSync3, writeFileSync as writeFileSync5 } from "fs";
-import { join as join30, relative as relative2, dirname as dirname6 } from "path";
+import { statSync as statSync2, readdirSync as readdirSync2, readFileSync as readFileSync14, mkdirSync as mkdirSync4, writeFileSync as writeFileSync5 } from "fs";
+import { join as join31, relative as relative2, dirname as dirname6 } from "path";
 import { PutObjectCommand, HeadObjectCommand, ListObjectsV2Command, GetObjectCommand, DeleteObjectsCommand } from "@aws-sdk/client-s3";
 
 // src/utils/s3-client.ts
@@ -6529,7 +6925,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 = join30(dir, entry.name);
+    const full = join31(dir, entry.name);
     if (entry.isDirectory()) {
       yield* walkMarkdown(full, base);
     } else if (entry.name.endsWith(".md")) {
@@ -6552,7 +6948,7 @@ async function runBackupSync(input) {
   let failed = 0;
   const files = [...walkMarkdown(input.vault, input.vault)];
   for (const relPath of files) {
-    const absPath = join30(input.vault, relPath);
+    const absPath = join31(input.vault, relPath);
     const localStat = statSync2(absPath);
     let needsUpload = true;
     try {
@@ -6571,7 +6967,7 @@ async function runBackupSync(input) {
       continue;
     }
     try {
-      const body = readFileSync13(absPath);
+      const body = readFileSync14(absPath);
       await client.send(new PutObjectCommand({ Bucket: input.bucket, Key: relPath, Body: body }));
       uploaded++;
     } catch {
@@ -6628,7 +7024,7 @@ async function runBackupRestore(input) {
     const objects = list.Contents ?? [];
     for (const obj of objects) {
       if (!obj.Key) continue;
-      const localPath = join30(target, obj.Key);
+      const localPath = join31(target, obj.Key);
       try {
         const localStat = statSync2(localPath);
         if (obj.LastModified && localStat.mtime > obj.LastModified) {
@@ -6641,7 +7037,7 @@ 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(dirname6(localPath), { recursive: true });
+          mkdirSync4(dirname6(localPath), { recursive: true });
           writeFileSync5(localPath, Buffer.from(body));
           downloaded++;
         }
@@ -6674,11 +7070,11 @@ async function runBackupRestore(input) {
 }
 
 // src/commands/status.ts
-import { existsSync as existsSync9, statSync as statSync3 } from "fs";
+import { existsSync as existsSync10, statSync as statSync3 } from "fs";
 import { readFile as readFile15 } from "fs/promises";
-import { join as join31 } from "path";
+import { join as join32 } from "path";
 async function runStatus(input) {
-  if (!existsSync9(input.vault)) {
+  if (!existsSync10(input.vault)) {
     return { exitCode: ExitCode.VAULT_PATH_INVALID, result: err("VAULT_PATH_INVALID", { vault: input.vault }) };
   }
   const scan = await scanVault(input.vault);
@@ -6703,7 +7099,7 @@ async function runStatus(input) {
   const compound = scan.data.compound.length;
   let schemaVersion = "v1";
   try {
-    const schemaContent = await readFile15(join31(input.vault, "SCHEMA.md"), "utf8");
+    const schemaContent = await readFile15(join32(input.vault, "SCHEMA.md"), "utf8");
     const versionMatch = schemaContent.match(/version:\s*["']?([^"'\s\n]+)/i);
     if (versionMatch) schemaVersion = versionMatch[1];
   } catch {
@@ -6764,7 +7160,7 @@ async function runStatus(input) {
 
 // src/commands/seed.ts
 import { mkdir as mkdir10, writeFile as writeFile9, stat as stat4 } from "fs/promises";
-import { join as join32 } from "path";
+import { join as join33 } from "path";
 var TODAY = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
 var EXAMPLE_PAGES = {
   "entities/example-project.md": `---
@@ -6833,29 +7229,29 @@ Real sources are immutable after ingestion \u2014 never edit them.
 `;
 async function runSeed(input) {
   try {
-    await stat4(join32(input.vault, "SCHEMA.md"));
+    await stat4(join33(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 = join32(input.vault, relPath);
+    const absPath = join33(input.vault, relPath);
     try {
       await stat4(absPath);
       skipped.push(relPath);
     } catch {
-      await mkdir10(join32(absPath, ".."), { recursive: true });
+      await mkdir10(join33(absPath, ".."), { recursive: true });
       await writeFile9(absPath, content, "utf8");
       created.push(relPath);
     }
   }
-  const rawPath = join32(input.vault, "raw", "articles", "example-source.md");
+  const rawPath = join33(input.vault, "raw", "articles", "example-source.md");
   try {
     await stat4(rawPath);
     skipped.push("raw/articles/example-source.md");
   } catch {
-    await mkdir10(join32(rawPath, ".."), { recursive: true });
+    await mkdir10(join33(rawPath, ".."), { recursive: true });
     await writeFile9(rawPath, EXAMPLE_RAW, "utf8");
     created.push("raw/articles/example-source.md");
   }
@@ -6879,8 +7275,8 @@ async function runSeed(input) {
 
 // src/commands/canvas.ts
 import { readFile as readFile16, writeFile as writeFile10 } from "fs/promises";
-import { existsSync as existsSync10 } from "fs";
-import { join as join33 } from "path";
+import { existsSync as existsSync11 } from "fs";
+import { join as join34 } from "path";
 var NODE_WIDTH = 240;
 var NODE_HEIGHT = 60;
 var COLUMN_SPACING = 400;
@@ -6958,8 +7354,8 @@ function buildCanvasEdges(adjacency) {
   return edges;
 }
 async function runCanvasGenerate(input) {
-  const graphPath = input.graphPath ?? join33(input.vault, ".skillwiki", "graph.json");
-  if (!existsSync10(graphPath)) {
+  const graphPath = input.graphPath ?? join34(input.vault, ".skillwiki", "graph.json");
+  if (!existsSync11(graphPath)) {
     return {
       exitCode: ExitCode.FILE_NOT_FOUND,
       result: err("FILE_NOT_FOUND", {
@@ -6996,7 +7392,7 @@ async function runCanvasGenerate(input) {
   const nodes = buildCanvasNodes(paths);
   const edges = buildCanvasEdges(graph.adjacency);
   const canvas = { nodes, edges };
-  const outPath = join33(input.vault, "vault-graph.canvas");
+  const outPath = join34(input.vault, "vault-graph.canvas");
   try {
     await writeFile10(outPath, JSON.stringify(canvas, null, 2));
   } catch (e) {
@@ -7018,10 +7414,10 @@ written: ${outPath}`
 }
 
 // src/commands/fleet-health.ts
-import { existsSync as existsSync11, readFileSync as readFileSync14 } from "fs";
+import { existsSync as existsSync12, readFileSync as readFileSync15 } from "fs";
 import { execSync as nodeExecSync } from "child_process";
 import { hostname as nodeHostname, platform as nodePlatform } from "os";
-import { join as join34 } from "path";
+import { join as join35 } from "path";
 var SSH_TIMEOUT_MS = 15e3;
 var TIMER_UNIT = "agent-memory-trends.timer";
 var SERVICE_UNIT = "agent-memory-trends.service";
@@ -7118,9 +7514,9 @@ function applyServiceFailedOverlay(run, serviceFailed) {
 function probeLocal(vaultPath, deps) {
   const latestPath = satelliteLatestRunPath(vaultPath);
   let parsed = null;
-  if (existsSync11(latestPath)) {
+  if (existsSync12(latestPath)) {
     try {
-      const wire = readSatelliteLatestRunFromText(readFileSync14(latestPath, "utf8"));
+      const wire = readSatelliteLatestRunFromText(readFileSync15(latestPath, "utf8"));
       if (wire) {
         parsed = {
           status: wire.status,
@@ -7237,12 +7633,12 @@ function formatTable(rows) {
   );
   return [header, ...lines].join("\n");
 }
-function rowHealthy(reachable, timer, runUnhealthy, timerBad, platform2) {
+function rowHealthy(reachable, timer, runUnhealthy, timerBad, platform3) {
   if (reachable === "no-access") return true;
   if (reachable === "no") return false;
   if (runUnhealthy) return false;
-  if (platform2 === "linux" && timerBad) return false;
-  if (platform2 === "linux" && timer === "inactive") return false;
+  if (platform3 === "linux" && timerBad) return false;
+  if (platform3 === "linux" && timer === "inactive") return false;
   return true;
 }
 async function runFleetHealth(input) {
@@ -7251,7 +7647,7 @@ async function runFleetHealth(input) {
   const home = input.home ?? env.HOME ?? "";
   const osHostname = input.osHostname ?? env.HOSTNAME ?? nodeHostname();
   const vault = input.vault ?? env.WIKI_PATH;
-  const file = input.file ?? (vault ? join34(vault, FLEET_REL_PATH) : void 0);
+  const file = input.file ?? (vault ? join35(vault, FLEET_REL_PATH) : void 0);
   if (!file) {
     return {
       exitCode: ExitCode.NO_VAULT_CONFIGURED,
@@ -7335,15 +7731,15 @@ async function runFleetHealth(input) {
 }
 
 // src/utils/auto-commit.ts
-import { existsSync as existsSync12 } from "fs";
-import { join as join35 } from "path";
+import { existsSync as existsSync13 } from "fs";
+import { join as join36 } from "path";
 async function postCommit(vault, exitCode) {
   if (exitCode !== 0) return;
   const home = process.env.HOME ?? "";
   const dotenv = await parseDotenvFile(configPath(home));
   const autoCommit = process.env.AUTO_COMMIT ?? dotenv["AUTO_COMMIT"];
   if (autoCommit === "false") return;
-  if (!existsSync12(join35(vault, ".git"))) return;
+  if (!existsSync13(join36(vault, ".git"))) return;
   const lastOps = readLastOp(vault);
   if (lastOps.length === 0) return;
   const porcelain = git(vault, ["status", "--porcelain", "--", ...VAULT_COMMIT_PATHSPEC]);
@@ -7367,9 +7763,9 @@ async function postCommit(vault, exitCode) {
 }
 
 // src/commands/write-preflight.ts
-import { existsSync as existsSync13, readFileSync as readFileSync15, statSync as statSync4 } from "fs";
+import { existsSync as existsSync14, readFileSync as readFileSync16, statSync as statSync4 } from "fs";
 async function runWritePreflightCommand(input) {
-  if (!existsSync13(input.vault) || !statSync4(input.vault).isDirectory()) {
+  if (!existsSync14(input.vault) || !statSync4(input.vault).isDirectory()) {
     return {
       exitCode: ExitCode.VAULT_PATH_INVALID,
       result: err(GateError.VAULT_PATH_INVALID, { path: input.vault })
@@ -7377,13 +7773,13 @@ async function runWritePreflightCommand(input) {
   }
   let priorText = input.priorArtifactText;
   if (input.priorArtifactFile) {
-    if (!existsSync13(input.priorArtifactFile)) {
+    if (!existsSync14(input.priorArtifactFile)) {
       return {
         exitCode: ExitCode.FILE_NOT_FOUND,
         result: err("FILE_NOT_FOUND", { path: input.priorArtifactFile })
       };
     }
-    priorText = readFileSync15(input.priorArtifactFile, "utf8");
+    priorText = readFileSync16(input.priorArtifactFile, "utf8");
   }
   const checkList = input.checks ? input.checks.split(",").map((s) => s.trim()).filter(Boolean) : void 0;
   const result = runWritePreflight({
@@ -7497,7 +7893,7 @@ async function emitManagedVaultWrite(vault, command, mutate, opts) {
   if (dirty) {
     return emit(dirty, void 0, { postCommit: false });
   }
-  const { runManagedWriteTransaction: runManagedWriteTransaction2 } = await import("./managed-write-preflight-4SWWFT75.js");
+  const { runManagedWriteTransaction: runManagedWriteTransaction2 } = await import("./managed-write-preflight-M2HL6DDY.js");
   const run = await runManagedWriteTransaction2({
     vault,
     command,
@@ -7522,7 +7918,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 ?? join36(vault, ".skillwiki", "graph.json");
+  const out = opts.out ?? join37(vault, ".skillwiki", "graph.json");
   return emitGuardedVaultWrite(vault, "graph build", () => runGraphBuild({ vault, out }));
 });
 var canvasCmd = program.command("canvas").description("manage Obsidian canvas files");
@@ -8132,6 +8528,21 @@ syncJournalCmd.command("clear-stale [vault]").description("supersede stale revie
     );
   }
 });
+var snapshotMaintenanceCmd = program.command("snapshot-maintenance").description("attended protected-snapshotter maintenance operations");
+var snapMaintJournalCmd = snapshotMaintenanceCmd.command("journal").description("snapshot operation journal maintenance");
+snapMaintJournalCmd.command("clear-stale [snapshot-worktree]").description("supersede safe stale review-required journals on a protected snapshotter (attended, one-shot)").option("--dry-run", "non-mutating plan + approval ID (no execution)", false).option("--approve <id>", "state-bound approval ID from a prior --dry-run").option("--reason <text>", "non-empty operator reason for the maintenance").option("--wiki <name>", "wiki profile name").action(async (snapshotWorktree, opts) => {
+  if (!snapshotWorktree) {
+    emit({ exitCode: ExitCode.USAGE, result: err("USAGE", "snapshot-maintenance journal clear-stale requires a snapshot-worktree path argument") });
+    return;
+  }
+  if (opts.dryRun) {
+    emit(await runSnapshotMaintenanceDryRun({ snapshotWorktree, dryRun: true, reason: opts.reason }));
+  } else if (opts.approve) {
+    emit(await runSnapshotMaintenanceExecute({ snapshotWorktree, dryRun: false, approvalId: opts.approve, reason: opts.reason }));
+  } else {
+    emit({ exitCode: ExitCode.USAGE, result: err("USAGE", "provide --dry-run for a plan, or --approve <id> --reason <text> to execute") });
+  }
+});
 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-4SWWFT75.js → managed-write-preflight-M2HL6DDY.js}

@@ -2,8 +2,8 @@
 import {
   runManagedWritePreflight,
   runManagedWriteTransaction
-} from "./chunk-IIUMTKKA.js";
-import "./chunk-E3PMAHS3.js";
+} from "./chunk-UJLSUJB6.js";
+import "./chunk-OWPQJOFG.js";
 import "./chunk-C5OLZRRM.js";
 export {
   runManagedWritePreflight,

package/dist/skillwiki-mcp.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import {
   runSkillwikiMcpStdio
-} from "./chunk-X2CPXF4T.js";
+} from "./chunk-24MVNAFJ.js";
 import "./chunk-7I2TPIV5.js";
 import "./chunk-NMUYMNNB.js";
-import "./chunk-E3PMAHS3.js";
+import "./chunk-OWPQJOFG.js";
 import "./chunk-C5OLZRRM.js";
 
 // src/mcp-entry.ts

package/dist/vault-sync/scripts/wiki-snapshot.sh

@@ -309,6 +309,18 @@ log() {
     echo "$(date '+%Y-%m-%d %H:%M:%S') $1" | tee -a "$LOG_FILE"
 }
 
+# Emit the canonical snapshot-completion terminal record (v0.10.14).
+# One stable machine-parseable line written for both pushed and no-change
+# success outcomes. Failure paths must never call this.
+#   SNAPSHOT_COMPLETE schema=v1 outcome=<pushed|no-change> result=success ts=<ISO> head=<oid> origin=<oid|unknown>
+emit_snapshot_complete() {
+    local outcome="$1"
+    local head_oid origin_oid
+    head_oid="$(git -C "$SNAPSHOT_WORKTREE" rev-parse HEAD 2>/dev/null || echo unknown)"
+    origin_oid="$(git -C "$SNAPSHOT_WORKTREE" rev-parse --verify -q origin/main 2>/dev/null || echo unknown)"
+    log "SNAPSHOT_COMPLETE schema=v1 outcome=${outcome} result=success ts=$(date -u +%Y-%m-%dT%H:%M:%SZ) head=${head_oid} origin=${origin_oid}"
+}
+
 validate_tombstone_prune_cap() {
     case "$MAX_TOMBSTONE_PRUNES" in
         ''|*[!0-9]*)
@@ -731,6 +743,7 @@ fi
 # Check for changes
 if [ -z "$(git status --porcelain)" ]; then
     log "No changes to commit"
+    emit_snapshot_complete "no-change"
     exit 0
 fi
 
@@ -807,6 +820,7 @@ done
 if [ "$PUSH_SUCCESS" = true ]; then
     log "Push successful"
     log "Status: complete"
+    emit_snapshot_complete "pushed"
     exit 0
 else
     log "ERROR: Push failed after $PUSH_RETRIES attempts"

package/package.json

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

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

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

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

@@ -87,7 +87,8 @@ 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. Managed preflight automatically supersedes a handoff when its `target_oid` is already an ancestor of `HEAD` and Git has no active sequencer or unmerged paths; unrelated dirty WIP is preserved. When the same incident also left a dead-owner managed-write lock, that preflight reclaims it with a recovery record in the same invocation. Live owners, active sequencers/unmerged paths, missing/non-ancestor targets, and remaining review-required journals still fail closed.
-4. After `skillwiki update` across 0.10.1, read the printed Migration 0.10.1 notes.
+4. **Protected snapshotter stale-journal cleanup (v0.10.14+):** On a known protected snapshotter (sg01) where `sync journal clear-stale` is blocked by `PROTECTED_SNAPSHOTTER_WRITE_BLOCKED`, use the attended one-shot maintenance authority instead: `skillwiki snapshot-maintenance journal clear-stale <snapshot-worktree> --dry-run --reason "<operator reason>"` to produce a state-bound approval ID, then `skillwiki snapshot-maintenance journal clear-stale <snapshot-worktree> --approve <id> --reason "<same reason>"` on an attended TTY to execute. This requires the exact configured snapshot worktree, the production snapshot flock, and recomputes the plan under the flock; it is the only allowlisted mutation across the protected boundary. No generic force flag or env bypass exists.
+5. 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.
 

package/skills/using-skillwiki/SKILL.md

@@ -87,7 +87,8 @@ 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. Managed preflight automatically supersedes a handoff when its `target_oid` is already an ancestor of `HEAD` and Git has no active sequencer or unmerged paths; unrelated dirty WIP is preserved. When the same incident also left a dead-owner managed-write lock, that preflight reclaims it with a recovery record in the same invocation. Live owners, active sequencers/unmerged paths, missing/non-ancestor targets, and remaining review-required journals still fail closed.
-4. After `skillwiki update` across 0.10.1, read the printed Migration 0.10.1 notes.
+4. **Protected snapshotter stale-journal cleanup (v0.10.14+):** On a known protected snapshotter (sg01) where `sync journal clear-stale` is blocked by `PROTECTED_SNAPSHOTTER_WRITE_BLOCKED`, use the attended one-shot maintenance authority instead: `skillwiki snapshot-maintenance journal clear-stale <snapshot-worktree> --dry-run --reason "<operator reason>"` to produce a state-bound approval ID, then `skillwiki snapshot-maintenance journal clear-stale <snapshot-worktree> --approve <id> --reason "<same reason>"` on an attended TTY to execute. This requires the exact configured snapshot worktree, the production snapshot flock, and recomputes the plan under the flock; it is the only allowlisted mutation across the protected boundary. No generic force flag or env bypass exists.
+5. 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.