skillwiki 0.10.12 → 0.10.14

package/dist/cli.js

@@ -78,11 +78,12 @@ import {
   safeWritePage,
   satelliteLatestRunPath,
   scanConflictMarkerBlocksInText,
+  snapshotterHealthChecks,
   taxonomyCommentForPage,
   upsertIndexEntry,
   validateLogEvent,
   writeLogEvent
-} from "./chunk-YYWGP7DN.js";
+} from "./chunk-2AOOMDZ7.js";
 import {
   normalizeDistTag,
   readCache,
@@ -110,15 +111,20 @@ import {
   releaseManagedWriteLock,
   runManagedWritePreflight,
   runManagedWriteTransaction
-} from "./chunk-3ZVZ2YEE.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-TYN2IHBY.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
@@ -2247,6 +2253,9 @@ function writeWorkJournal(vault, opId, fields) {
   writeFileSync3(tmp, body, "utf8");
   renameSync(tmp, path);
 }
+var DEFAULT_DEPS = {
+  writeEvidenceText: atomicWriteText
+};
 var PHASE_ORDER = ["validate", "evidence", "log", "projection", "commit", "done"];
 function resolveWorkDir(vault, workItem) {
   const rel = normalizeWorkItemRel(workItem);
@@ -2301,7 +2310,7 @@ ${body}`);
 async function setStatusCompleted(filePath) {
   return patchFrontmatterStatus(filePath);
 }
-async function writeEvidence(workDir, opId, phases) {
+async function writeEvidence(workDir, opId, phases, writeText) {
   const path = join16(workDir, "evidence.md");
   const body = [
     "---",
@@ -2317,7 +2326,7 @@ async function writeEvidence(workDir, opId, phases) {
     `- completed_at: ${(/* @__PURE__ */ new Date()).toISOString()}`,
     ""
   ].join("\n");
-  return atomicWriteText(path, body);
+  return writeText(path, body);
 }
 async function markPlanComplete(workDir) {
   const planPath = join16(workDir, "plan.md");
@@ -2330,7 +2339,7 @@ function writeFailure(stage, result) {
     result: result.ok ? err("WRITE_FAILED", { stage, message: "unexpected ok" }) : result
   };
 }
-async function runWorkComplete(input) {
+async function runWorkComplete(input, deps = DEFAULT_DEPS) {
   const workDirResult = resolveWorkDir(input.vault, input.workItem);
   if (!workDirResult.ok) {
     return {
@@ -2411,7 +2420,12 @@ async function runWorkComplete(input) {
       if (!statusWrite.ok) return writeFailure("evidence-spec", statusWrite);
       const planWrite = await markPlanComplete(workDir);
       if (!planWrite.ok) return writeFailure("evidence-plan", planWrite);
-      const evidenceWrite = await writeEvidence(workDir, opId, completedPhases);
+      const evidenceWrite = await writeEvidence(
+        workDir,
+        opId,
+        completedPhases,
+        deps.writeEvidenceText
+      );
       if (!evidenceWrite.ok) return writeFailure("evidence", evidenceWrite);
       if (input.failAfter === "evidence") {
         throw new Error("simulated failure after evidence");
@@ -2442,7 +2456,12 @@ async function runWorkComplete(input) {
     }
     if (phaseIndex(phase) <= phaseIndex("projection")) {
       if (!existsSync4(join16(workDir, "evidence.md"))) {
-        const evidenceWrite = await writeEvidence(workDir, opId, completedPhases);
+        const evidenceWrite = await writeEvidence(
+          workDir,
+          opId,
+          completedPhases,
+          deps.writeEvidenceText
+        );
         if (!evidenceWrite.ok) return writeFailure("projection-evidence", evidenceWrite);
       }
       const finalCheck = await runWorkValidate({
@@ -2649,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",
@@ -2678,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");
@@ -4698,7 +4764,7 @@ import { createHash as createHash4 } from "crypto";
 import { realpathSync } from "fs";
 import { readFile as readFile12 } from "fs/promises";
 import { join as join26, resolve as resolve3 } from "path";
-var DEFAULT_DEPS = {
+var DEFAULT_DEPS2 = {
   afterStage: async () => void 0,
   preflight: (input) => runManagedWritePreflight(input)
 };
@@ -5018,7 +5084,7 @@ async function previewPreparedPagePublication(input, vault) {
     true
   );
 }
-async function publishPreparedPage(input, vault, deps = DEFAULT_DEPS) {
+async function publishPreparedPage(input, vault, deps = DEFAULT_DEPS2) {
   const managed = acquireManagedWriteLock(vault, `page publish ${input.page.target}`);
   if (!managed.ok) return { exitCode: errorExitCode(managed.error), result: managed };
   try {
@@ -5173,7 +5239,7 @@ async function publishPreparedPage(input, vault, deps = DEFAULT_DEPS) {
     releaseManagedWriteLock(managed.data);
   }
 }
-async function runPagePublish(input, deps = DEFAULT_DEPS) {
+async function runPagePublish(input, deps = DEFAULT_DEPS2) {
   const prepared = await preparePagePublication(input);
   if (!prepared.ok) return { exitCode: errorExitCode(prepared.error), result: prepared };
   if (!input.write) return previewPreparedPagePublication(prepared.data, input.vault);
@@ -6490,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
@@ -6516,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")) {
@@ -6539,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 {
@@ -6558,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 {
@@ -6615,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) {
@@ -6628,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++;
         }
@@ -6661,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);
@@ -6690,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 {
@@ -6751,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": `---
@@ -6820,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");
   }
@@ -6866,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;
@@ -6945,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", {
@@ -6983,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) {
@@ -7005,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";
@@ -7105,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,
@@ -7224,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) {
@@ -7238,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,
@@ -7322,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]);
@@ -7354,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 })
@@ -7364,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({
@@ -7484,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-7TWSEZJZ.js");
+  const { runManagedWriteTransaction: runManagedWriteTransaction2 } = await import("./managed-write-preflight-M2HL6DDY.js");
   const run = await runManagedWriteTransaction2({
     vault,
     command,
@@ -7509,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");
@@ -8119,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 });