skillwiki 0.10.12 → 0.10.14

package/dist/{chunk-YYWGP7DN.js → chunk-2AOOMDZ7.js}

@@ -33,7 +33,7 @@ import {
   satelliteGateFromFleetLoad,
   snapshotterAliasForLocalHost,
   writeDotenv
-} from "./chunk-TYN2IHBY.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,142 @@ function resolveSnapshotGitWorktree(config) {
   const defaultPath = "/root/wiki-git";
   return existsSync13(defaultPath) ? defaultPath : void 0;
 }
+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"]
+    }).trim();
+    return out || void 0;
+  } catch {
+    return void 0;
+  }
+}
+function snapshotProp(kind, prop, fixture, scope) {
+  if (fixture) {
+    const v = fixture[kind][prop];
+    return v == null ? void 0 : String(v);
+  }
+  const unit = kind === "timer" ? "wiki-snapshot.timer" : "wiki-snapshot.service";
+  return systemctlShowProperty(scope, unit, prop);
+}
+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;
+  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(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" && sActiveEnter != null) {
+    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 +6665,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 +6680,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 +6731,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 +7148,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 +9989,7 @@ export {
   isFailedRunStatus,
   readSatelliteLatestRunFromText,
   evaluateSatelliteRunHealth,
+  snapshotterHealthChecks,
   runDoctor,
   readCliPackageJson,
   DEFAULT_DIRTY_VOLUME_THRESHOLD,

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

@@ -702,16 +702,23 @@ 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;
+function journalSupersedeHead(vault, requireClean) {
+  if (hasUnmergedPaths(vault).length > 0 || hasActiveGitSequencer(vault) || requireClean && !isWorktreeClean(vault)) {
+    return null;
+  }
   const head = git(vault, ["rev-parse", "HEAD"]);
+  return head || null;
+}
+function canSupersedeJournalInContext(vault, fields, head) {
   if (!head) return false;
+  const target = fields.target_oid?.trim();
+  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]);
@@ -733,14 +740,12 @@ function markJournalSuperseded(vault, opId, fields, by) {
 }
 function supersedeStaleReviewRequiredJournals(vault, opts = {}) {
   const by = opts.by ?? "skillwiki-preflight";
+  const requireClean = opts.requireClean !== false;
   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 };
-  }
+  const head = journalSupersedeHead(vault, requireClean);
   for (const { opId, fields } of listReviewRequiredOps(vault)) {
-    if (!canSupersedeJournal(vault, fields)) {
+    if (!canSupersedeJournalInContext(vault, fields, head)) {
       skipped.push(opId);
       continue;
     }
@@ -886,6 +891,9 @@ export {
   findReviewRequiredOp,
   hasUnmergedPaths,
   hasActiveGitSequencer,
+  isWorktreeClean,
+  canSupersedeJournal,
+  markJournalSuperseded,
   supersedeStaleReviewRequiredJournals,
   resolveVaultSyncPullHelper,
   runVaultSyncPullHelper

package/dist/{chunk-3ZVZ2YEE.js → chunk-UJLSUJB6.js}

@@ -8,7 +8,7 @@ import {
   loadFleetManifestAndHost,
   runVaultSyncPullHelper,
   supersedeStaleReviewRequiredJournals
-} from "./chunk-TYN2IHBY.js";
+} from "./chunk-OWPQJOFG.js";
 import {
   ExitCode,
   err,
@@ -163,7 +163,10 @@ function preflightBlocker(vault) {
   if (hasActiveGitSequencer(vault)) {
     return { reason: "git-operation-in-progress" };
   }
-  supersedeStaleReviewRequiredJournals(vault, { by: "skillwiki-managed-write-preflight" });
+  supersedeStaleReviewRequiredJournals(vault, {
+    by: "skillwiki-managed-write-preflight",
+    requireClean: false
+  });
   const op = findReviewRequiredOp(vault);
   if (op) return { reason: "review-required", operation_id: op };
   return null;