skillwiki 0.10.60 → 0.10.62

package/dist/{chunk-NTM3WRAV.js → chunk-EK7SNIU3.js}

@@ -17,6 +17,7 @@ import {
   buildWikilinkAdjacency,
   communityCohesion,
   git,
+  hasUnmergedPaths,
   isValidWikiProfileKey,
   listReviewRequiredOps,
   loadFleetManifestAndHost,
@@ -39,7 +40,7 @@ import {
   snapshotterAliasForLocalHost,
   toUndirectedWeighted,
   writeDotenv
-} from "./chunk-CUSHQB5N.js";
+} from "./chunk-KZZUTQEA.js";
 import {
   atomicWriteText,
   prepareTypedPage
@@ -2909,6 +2910,104 @@ function checkPushAgeFromLog(logDir, logFile) {
     );
   }
 }
+var SNAPSHOT_RUN_HEADER = /=== Wiki Snapshot:/;
+var SNAPSHOT_SUCCESS_RECORD = "SNAPSHOT_COMPLETE schema=v1";
+var SNAPSHOT_INHIBITED_RECORD = "SNAPSHOT_INHIBITED schema=v1";
+var SNAPSHOT_TIMESTAMPED_FAIL = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2} FAIL\b/;
+var SNAPSHOT_LOG_STAMP = /^(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2})/;
+function isSnapshotSuccessLine(line) {
+  return line.includes(SNAPSHOT_SUCCESS_RECORD);
+}
+function isSnapshotFailureLine(line) {
+  if (line.includes(SNAPSHOT_INHIBITED_RECORD)) return true;
+  if (line.includes("PREFLIGHT_FAILED")) return true;
+  if (SNAPSHOT_TIMESTAMPED_FAIL.test(line)) return true;
+  if (line.includes("ERROR")) return true;
+  return false;
+}
+function parseSnapshotFailureMeta(lines) {
+  let stamp = "";
+  let reason = "";
+  let operationId = "";
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i];
+    if (!stamp) {
+      const m = line.match(SNAPSHOT_LOG_STAMP);
+      if (m) stamp = m[1];
+    }
+    const trimmed = line.trim();
+    if (trimmed.startsWith("{") && trimmed.includes("PREFLIGHT_FAILED")) {
+      try {
+        const parsed = JSON.parse(trimmed);
+        const detail = parsed.detail;
+        if (detail && typeof detail === "object") {
+          if (!reason && typeof detail.reason === "string") reason = detail.reason;
+          if (!operationId && typeof detail.operation_id === "string") operationId = detail.operation_id;
+        }
+      } catch {
+      }
+    }
+    if (!reason) {
+      const m = line.match(/\breason=(\S+)/) ?? line.match(/"reason"\s*:\s*"([^"]+)"/);
+      if (m) reason = m[1];
+    }
+    if (!operationId) {
+      const m = line.match(/\boperation_id=(\S+)/) ?? line.match(/\bopid=(\S+)/) ?? line.match(/"operation_id"\s*:\s*"([^"]+)"/);
+      if (m) operationId = m[1];
+    }
+  }
+  return { stamp, reason, operationId };
+}
+function splitSnapshotRuns(lines) {
+  const runs = [];
+  let current = null;
+  for (const line of lines) {
+    if (SNAPSHOT_RUN_HEADER.test(line)) {
+      if (current) runs.push(current);
+      current = { lines: [line], hasHeader: true };
+    } else if (current?.hasHeader) {
+      current.lines.push(line);
+    } else if (isSnapshotFailureLine(line) || isSnapshotSuccessLine(line)) {
+      if (current) {
+        runs.push(current);
+        current = null;
+      }
+      runs.push({ lines: [line], hasHeader: false });
+    }
+  }
+  if (current) runs.push(current);
+  return runs;
+}
+function countConsecutiveSnapshotFailures(logRecords) {
+  const window = logRecords.length > 60 ? logRecords.slice(-60) : logRecords;
+  const runs = splitSnapshotRuns(window);
+  let count = 0;
+  let mostRecentFail = "";
+  let reason = "";
+  let operationId = "";
+  for (let i = runs.length - 1; i >= 0; i--) {
+    const lines = runs[i].lines;
+    if (lines.some(isSnapshotSuccessLine)) break;
+    if (!lines.some(isSnapshotFailureLine)) continue;
+    count++;
+    if (count === 1) {
+      const meta = parseSnapshotFailureMeta(lines);
+      mostRecentFail = meta.stamp;
+      reason = meta.reason;
+      operationId = meta.operationId;
+    }
+  }
+  return { count, mostRecentFail, reason, operationId };
+}
+function consecutiveSnapshotFailureDetail(result) {
+  if (result.count >= 2) {
+    let detail = `${result.count} consecutive snapshot failure(s); most recent: ${result.mostRecentFail || "unknown"}`;
+    if (result.reason) detail += `; reason=${result.reason}`;
+    if (result.operationId) detail += ` operation_id=${result.operationId}`;
+    return detail;
+  }
+  return `${result.count} consecutive failure(s) in recent window (recurrence threshold: 2)`;
+}
 function snapshotterHealthChecks(scope, logDir, env) {
   const fixture = loadSnapshotFixture(env);
   const cadence = fixture ? fixture.cadence_minutes : parseInt(env.VS_SNAPSHOT_CADENCE_MINUTES ?? "30", 10) || 30;
@@ -2995,20 +3094,8 @@ function snapshotterHealthChecks(scope, logDir, env) {
   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)`);
+  const failureStreak = countConsecutiveSnapshotFailures(logRecords);
+  const consecutiveFailures = failureStreak.count >= 2 ? check("error", "vault_sync_snapshot_consecutive_failures", "Vault sync snapshot consecutive failures", consecutiveSnapshotFailureDetail(failureStreak)) : check("pass", "vault_sync_snapshot_consecutive_failures", "Vault sync snapshot consecutive failures", consecutiveSnapshotFailureDetail(failureStreak));
   return [jobs, serviceResult, freshness, consecutiveFailures];
 }
 function vaultSyncChecks(input) {
@@ -3336,26 +3423,71 @@ function checkVaultSyncPullHelper(home, env) {
     "Not found \u2014 install skillwiki@0.10.1+, redeploy vault-sync, or set SKILLWIKI_VAULT_SYNC_PULL_HELPER"
   );
 }
-function checkVaultSyncReviewRequiredJournals(vaultPath) {
-  if (!vaultPath || !existsSync12(join15(vaultPath, ".git"))) {
+function isGitDir(path) {
+  return Boolean(path && existsSync12(join15(path, ".git")));
+}
+function checkVaultSyncReviewRequiredJournals(ctx) {
+  const live = ctx.resolvedPath;
+  let checked = live;
+  if (!isGitDir(live) && ctx.vsConfig.role === "snapshotter") {
+    const worktree = resolveConfiguredSnapshotWorktree(ctx.input.home);
+    if (!worktree) {
+      return check(
+        "warn",
+        "vault_sync_review_required_journals",
+        "Review-required journals",
+        "snapshotter has no configured snapshot worktree \u2014 journals not inspected"
+      );
+    }
+    checked = worktree;
+  }
+  if (!isGitDir(checked)) {
     return check("pass", "vault_sync_review_required_journals", "Review-required journals", "No git vault \u2014 check skipped");
   }
   try {
-    const ops = listReviewRequiredOps(vaultPath);
+    const ops = listReviewRequiredOps(checked);
     if (ops.length === 0) {
-      return check("pass", "vault_sync_review_required_journals", "Review-required journals", "None");
+      return check("pass", "vault_sync_review_required_journals", "Review-required journals", `None at ${checked}`);
     }
     const sample = ops[0]?.opId ?? "?";
     return check(
       "warn",
       "vault_sync_review_required_journals",
       "Review-required journals",
-      `${ops.length} handoff(s); oldest/sample: ${sample} \u2014 if worktree clean: skillwiki sync journal clear-stale --dry-run`
+      `${ops.length} handoff(s) at ${checked}; oldest/sample: ${sample} \u2014 if worktree clean: skillwiki sync journal clear-stale --dry-run`
     );
   } catch {
     return check("pass", "vault_sync_review_required_journals", "Review-required journals", "Could not read journals \u2014 check skipped");
   }
 }
+function checkSnapshotWorktreeUnmerged(ctx) {
+  const id = "vault_sync_snapshot_worktree_unmerged";
+  const label = "Vault sync snapshot worktree unmerged paths";
+  if (ctx.vsConfig.role !== "snapshotter") {
+    return check("pass", id, label, "Not a snapshotter host \u2014 check skipped");
+  }
+  const worktree = resolveConfiguredSnapshotWorktree(ctx.input.home);
+  if (!worktree) {
+    return check(
+      "warn",
+      id,
+      label,
+      "no configured snapshot worktree (vault_sync.snapshot_worktree or snapshot_profile required)"
+    );
+  }
+  if (!isGitDir(worktree)) {
+    return check("warn", id, label, `configured snapshot worktree is not a git repo: ${worktree}`);
+  }
+  try {
+    const paths = hasUnmergedPaths(worktree);
+    if (paths.length === 0) {
+      return check("pass", id, label, `none at ${worktree}`);
+    }
+    return check("error", id, label, `unmerged paths at ${worktree}: ${paths.join(", ")}`);
+  } catch {
+    return check("warn", id, label, `could not inspect unmerged paths at ${worktree}`);
+  }
+}
 var vaultSyncProbe = {
   id: "vault_sync",
   run(ctx) {
@@ -3369,7 +3501,8 @@ var vaultSyncProbe = {
       env: ctx.input.env ?? process.env
     }));
     checks.push(checkVaultSyncPullHelper(ctx.input.home, ctx.input.env ?? process.env));
-    checks.push(checkVaultSyncReviewRequiredJournals(ctx.resolvedPath));
+    checks.push(checkVaultSyncReviewRequiredJournals(ctx));
+    checks.push(checkSnapshotWorktreeUnmerged(ctx));
     return checks;
   }
 };

package/dist/{chunk-CUSHQB5N.js → chunk-KZZUTQEA.js}

@@ -3417,6 +3417,8 @@ function buildCliSurface() {
   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 snapMaintProjectionCmd = snapshotMaintenanceCmd.command("projection-conflict");
+  snapMaintProjectionCmd.command("repair").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>");

package/dist/cli.js

@@ -50,7 +50,7 @@ import {
   snapshotterHealthChecks,
   upsertIndexEntry,
   vectorIndexStatus
-} from "./chunk-NTM3WRAV.js";
+} from "./chunk-EK7SNIU3.js";
 import {
   normalizeDistTag,
   readCache,
@@ -151,7 +151,7 @@ import {
   supersedeStaleReviewRequiredJournals,
   taxonomyCommentForPage,
   writeDotenv
-} from "./chunk-CUSHQB5N.js";
+} from "./chunk-KZZUTQEA.js";
 import {
   assertTargetInsideVault,
   atomicWriteText,
@@ -8457,13 +8457,15 @@ function runSyncJournalClearStale(input) {
 }
 
 // src/commands/snapshot-maintenance.ts
-import { existsSync as existsSync10, mkdirSync as mkdirSync4, appendFileSync } from "fs";
+import { existsSync as existsSync10, writeFileSync as writeFileSync6, mkdirSync as mkdirSync4, 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 join34, resolve as resolvePath } from "path";
 var MAINTENANCE_SCHEMA_VERSION = 1;
 var MAINTENANCE_COMMAND = "snapshot-maintenance journal clear-stale";
+var REPAIR_COMMAND = "snapshot-maintenance projection-conflict repair";
+var PROJECTION_CONFLICT_ALLOWLIST = ["index.md", "log.md"];
 function canonicalize(p) {
   return resolvePath(p);
 }
@@ -8617,11 +8619,11 @@ function defaultAuditSink(home) {
     }
   };
 }
-function makeAuditEvent(input, hostId, now, result, errorCode, approvalId) {
+function makeAuditEvent(input, hostId, now, result, errorCode, approvalId, command = MAINTENANCE_COMMAND) {
   return {
     ts: new Date(now).toISOString(),
     schema_version: MAINTENANCE_SCHEMA_VERSION,
-    command: MAINTENANCE_COMMAND,
+    command,
     host: hostId,
     actor: input.env?.USER ?? process.env.USER ?? "unknown",
     session: input.sessionId ?? "unknown",
@@ -8740,6 +8742,244 @@ async function performSupersession(input, plan, audit, now) {
     })
   };
 }
+function computeRepairApprovalId(plan) {
+  const paths = [...plan.unmerged_paths].sort().join(",");
+  const payload = [
+    `v${plan.schema_version}`,
+    plan.command,
+    plan.host_id,
+    plan.snapshot_worktree,
+    plan.git_directory,
+    plan.branch,
+    plan.head_oid,
+    paths,
+    normalizeReason(plan.operator_reason)
+  ].join("|");
+  return "smap1-" + createHash5("sha256").update(payload).digest("hex").slice(0, 32);
+}
+function nonMergeSequencerActive(repo) {
+  const gitDir = git(repo, ["rev-parse", "--absolute-git-dir"]);
+  if (!gitDir) return false;
+  for (const m of ["CHERRY_PICK_HEAD", "REVERT_HEAD"]) {
+    if (existsSync10(join34(gitDir, m))) return true;
+  }
+  return existsSync10(join34(gitDir, "rebase-merge")) || existsSync10(join34(gitDir, "rebase-apply"));
+}
+function extraUnmergedPaths(unmerged) {
+  const allow = new Set(PROJECTION_CONFLICT_ALLOWLIST);
+  return unmerged.filter((p) => !allow.has(p));
+}
+async function authorizeRepairContext(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 liveVaultPath = input.liveVaultPath ? canonicalize(input.liveVaultPath) : await resolveLiveVault({ env, home });
+  const fleetLoad = input.fleetLoad !== void 0 ? input.fleetLoad : await loadFleetManifestAndHost({
+    vault: 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", void 0, REPAIR_COMMAND));
+    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", void 0, REPAIR_COMMAND));
+    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", void 0, REPAIR_COMMAND));
+    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", void 0, REPAIR_COMMAND));
+    return { exitCode: ExitCode.PROTECTED_SNAPSHOTTER_WRITE_BLOCKED, result: refusalErr("MAINTENANCE_WRONG_WORKTREE", `requested path '${requested}' is not the configured snapshot worktree '${canonicalize(configuredWorktree)}'`) };
+  }
+  if (!existsSync10(requested) || !existsSync10(join34(requested, ".git"))) {
+    audit(makeAuditEvent(input, fleetLoad.hostId, now, "refusal", "MAINTENANCE_MISSING_GIT_REPO", void 0, REPAIR_COMMAND));
+    return { exitCode: ExitCode.PROTECTED_SNAPSHOTTER_WRITE_BLOCKED, result: refusalErr("MAINTENANCE_MISSING_GIT_REPO", `snapshot worktree is not a git repository: ${requested}`) };
+  }
+  if (liveVaultPath && requested === canonicalize(liveVaultPath)) {
+    audit(makeAuditEvent(input, fleetLoad.hostId, now, "refusal", "MAINTENANCE_LIVE_VAULT_TARGET", void 0, REPAIR_COMMAND));
+    return { exitCode: ExitCode.PROTECTED_SNAPSHOTTER_WRITE_BLOCKED, result: refusalErr("MAINTENANCE_LIVE_VAULT_TARGET", "requested path is the live vault, not the snapshot worktree") };
+  }
+  if (nonMergeSequencerActive(requested)) {
+    audit(makeAuditEvent(input, fleetLoad.hostId, now, "refusal", "MAINTENANCE_ACTIVE_SEQUENCER", void 0, REPAIR_COMMAND));
+    return { exitCode: ExitCode.PROTECTED_SNAPSHOTTER_WRITE_BLOCKED, result: refusalErr("MAINTENANCE_ACTIVE_SEQUENCER", "git sequencer (rebase/cherry-pick/revert) is active") };
+  }
+  const unmerged = hasUnmergedPaths(requested);
+  const extra = extraUnmergedPaths(unmerged);
+  if (extra.length > 0) {
+    audit(makeAuditEvent(input, fleetLoad.hostId, now, "refusal", "MAINTENANCE_UNMERGED_PATHS", void 0, REPAIR_COMMAND));
+    return { exitCode: ExitCode.PROTECTED_SNAPSHOTTER_WRITE_BLOCKED, result: refusalErr("MAINTENANCE_UNMERGED_PATHS", `unmerged paths not in projection allowlist: ${extra.join(", ")}`) };
+  }
+  if (unmerged.length === 0) {
+    audit(makeAuditEvent(input, fleetLoad.hostId, now, "refusal", "MAINTENANCE_NO_PROJECTION_CONFLICT", void 0, REPAIR_COMMAND));
+    return { exitCode: ExitCode.PROTECTED_SNAPSHOTTER_WRITE_BLOCKED, result: refusalErr("MAINTENANCE_NO_PROJECTION_CONFLICT", "no unmerged projection paths") };
+  }
+  return {
+    hostId: fleetLoad.hostId,
+    requested,
+    gitDirectory: git(requested, ["rev-parse", "--absolute-git-dir"]) || "",
+    branch: git(requested, ["rev-parse", "--abbrev-ref", "HEAD"]) || "HEAD",
+    headOid: git(requested, ["rev-parse", "HEAD"]) || "",
+    unmerged
+  };
+}
+async function runProjectionConflictRepairDryRun(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 ctx = await authorizeRepairContext(input);
+  if ("exitCode" in ctx) return ctx;
+  const planBase = {
+    schema_version: MAINTENANCE_SCHEMA_VERSION,
+    command: REPAIR_COMMAND,
+    host_id: ctx.hostId,
+    snapshot_worktree: ctx.requested,
+    git_directory: ctx.gitDirectory,
+    branch: ctx.branch,
+    head_oid: ctx.headOid,
+    unmerged_paths: ctx.unmerged,
+    allowlisted_paths: [...PROJECTION_CONFLICT_ALLOWLIST],
+    operator_reason: normalizeReason(input.reason ?? "")
+  };
+  const approvalId = computeRepairApprovalId(planBase);
+  const plan = { ...planBase, approval_id: approvalId };
+  audit(makeAuditEvent(input, ctx.hostId, now, "dry-run", void 0, approvalId, REPAIR_COMMAND));
+  return {
+    exitCode: ExitCode.OK,
+    result: ok({
+      dry_run: true,
+      plan: {
+        schema_version: plan.schema_version,
+        command: plan.command,
+        host_id: plan.host_id,
+        role: "snapshotter",
+        protected: true,
+        snapshot_worktree: plan.snapshot_worktree,
+        snapshot_lock_path: input.snapshotLockPath ?? "/var/lock/wiki-snapshot.lock",
+        git_directory: plan.git_directory,
+        branch: plan.branch,
+        head_oid: plan.head_oid,
+        worktree_clean: false,
+        active_sequencer: false,
+        unmerged_paths: plan.unmerged_paths,
+        eligible_journals: [],
+        skipped_journals: [],
+        approval_id: approvalId,
+        operator_reason: plan.operator_reason
+      },
+      humanHint: `dry-run: rematerialize ${plan.unmerged_paths.join(", ")}; approval_id=${approvalId}`
+    })
+  };
+}
+async function rematerializeProjections(input, worktree) {
+  if (input.renderIndex && input.renderLog) {
+    const index = await input.renderIndex(worktree);
+    if (!index.ok) return index;
+    const log = await input.renderLog(worktree);
+    if (!log.ok) return log;
+    return ok({ index: index.data.text, log: log.data.text });
+  }
+  const indexProj = await renderRootIndex({ vault: worktree });
+  if (!indexProj.ok) return indexProj;
+  const events = await readLogEvents(worktree);
+  if (!events.ok) return events;
+  return ok({ index: indexProj.data.text, log: renderLogProjection(events.data) });
+}
+async function performProjectionRepair(input, plan, audit, now) {
+  const rendered = await rematerializeProjections(input, plan.snapshot_worktree);
+  if (!rendered.ok) {
+    audit(makeAuditEvent(input, plan.host_id, now, "refusal", "MAINTENANCE_REMATERIALIZE_FAILED", plan.approval_id ?? void 0, REPAIR_COMMAND));
+    return { exitCode: ExitCode.WRITE_FAILED, result: rendered };
+  }
+  try {
+    writeFileSync6(join34(plan.snapshot_worktree, "index.md"), rendered.data.index);
+    writeFileSync6(join34(plan.snapshot_worktree, "log.md"), rendered.data.log);
+    gitStrict(plan.snapshot_worktree, ["add", "--", "index.md", "log.md"]);
+    gitStrict(plan.snapshot_worktree, [
+      "commit",
+      "-m",
+      "snapshot-maintenance: rematerialize projection conflict"
+    ]);
+  } catch (e) {
+    audit(makeAuditEvent(input, plan.host_id, now, "refusal", "MAINTENANCE_COMMIT_FAILED", plan.approval_id ?? void 0, REPAIR_COMMAND));
+    return { exitCode: ExitCode.WRITE_FAILED, result: refusalErr("MAINTENANCE_COMMIT_FAILED", String(e)) };
+  }
+  const remaining = hasUnmergedPaths(plan.snapshot_worktree);
+  if (remaining.length > 0) {
+    audit(makeAuditEvent(input, plan.host_id, now, "refusal", "MAINTENANCE_UNMERGED_PATHS", plan.approval_id ?? void 0, REPAIR_COMMAND));
+    return { exitCode: ExitCode.PROTECTED_SNAPSHOTTER_WRITE_BLOCKED, result: refusalErr("MAINTENANCE_UNMERGED_PATHS", `unmerged paths remain: ${remaining.join(", ")}`) };
+  }
+  const commitOid = git(plan.snapshot_worktree, ["rev-parse", "HEAD"]);
+  audit(makeAuditEvent(input, plan.host_id, now, "success", void 0, plan.approval_id ?? void 0, REPAIR_COMMAND));
+  return {
+    exitCode: ExitCode.OK,
+    result: ok({
+      dry_run: false,
+      execution: {
+        superseded: [],
+        skipped: [],
+        approval_id: plan.approval_id,
+        no_op: false
+      },
+      humanHint: `execution: rematerialized index.md,log.md commit=${commitOid}`
+    })
+  };
+}
+async function runProjectionConflictRepairExecute(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", void 0, REPAIR_COMMAND));
+    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", void 0, REPAIR_COMMAND));
+    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", void 0, REPAIR_COMMAND));
+    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 runProjectionConflictRepairDryRun(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_PROJECTION_CONFLICT", void 0, REPAIR_COMMAND));
+    return { exitCode: ExitCode.PROTECTED_SNAPSHOTTER_WRITE_BLOCKED, result: refusalErr("MAINTENANCE_NO_PROJECTION_CONFLICT", "no unmerged projection paths") };
+  }
+  if (plan.approval_id !== input.approvalId) {
+    audit(makeAuditEvent(input, plan.host_id, now, "refusal", "MAINTENANCE_STALE_APPROVAL_ID", void 0, REPAIR_COMMAND));
+    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 (!input.skipFlock) {
+    const flockResult = acquireSnapshotFlock(plan.snapshot_lock_path);
+    if (!flockResult.acquired) {
+      audit(makeAuditEvent(input, plan.host_id, now, "refusal", "MAINTENANCE_FLOCK_BUSY", void 0, REPAIR_COMMAND));
+      return { exitCode: ExitCode.PROTECTED_SNAPSHOTTER_WRITE_BLOCKED, result: refusalErr("MAINTENANCE_FLOCK_BUSY", `snapshot flock busy: ${plan.snapshot_lock_path}`) };
+    }
+    try {
+      return await performProjectionRepair(input, plan, audit, now);
+    } finally {
+      releaseSnapshotFlock(flockResult);
+    }
+  }
+  return performProjectionRepair(input, plan, audit, now);
+}
 function acquireSnapshotFlock(lockPath) {
   try {
     const child = spawn("bash", ["-c", `exec 9>"${lockPath}"; flock -n 9 || exit 1; while true; do sleep 3600; done`], {
@@ -8771,7 +9011,7 @@ function releaseSnapshotFlock(handle) {
 }
 
 // src/commands/backup.ts
-import { statSync as statSync3, readdirSync as readdirSync2, readFileSync as readFileSync15, mkdirSync as mkdirSync5, writeFileSync as writeFileSync6 } from "fs";
+import { statSync as statSync3, readdirSync as readdirSync2, readFileSync as readFileSync15, mkdirSync as mkdirSync5, writeFileSync as writeFileSync7 } from "fs";
 import { join as join35, relative as relative3, dirname as dirname11 } from "path";
 import { PutObjectCommand, HeadObjectCommand, ListObjectsV2Command, GetObjectCommand, DeleteObjectsCommand } from "@aws-sdk/client-s3";
 
@@ -8909,7 +9149,7 @@ async function runBackupRestore(input) {
         const body = await resp.Body?.transformToByteArray();
         if (body) {
           mkdirSync5(dirname11(localPath), { recursive: true });
-          writeFileSync6(localPath, Buffer.from(body));
+          writeFileSync7(localPath, Buffer.from(body));
           downloaded++;
         }
       } catch {
@@ -10170,7 +10410,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-Z6MEAGQI.js");
+  const { runManagedWriteTransaction: runManagedWriteTransaction2 } = await import("./managed-write-preflight-GJP4RN26.js");
   const run = await runManagedWriteTransaction2({
     vault,
     command,
@@ -11079,6 +11319,20 @@ snapMaintJournalCmd.command("clear-stale [snapshot-worktree]").description("supe
     emit({ exitCode: ExitCode.USAGE, result: err("USAGE", "provide --dry-run for a plan, or --approve <id> --reason <text> to execute") });
   }
 });
+var snapMaintProjectionCmd = snapshotMaintenanceCmd.command("projection-conflict").description("attended projection-owned unmerged-path repair");
+snapMaintProjectionCmd.command("repair [snapshot-worktree]").description("rematerialize allowlisted UU log.md/index.md 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 projection-conflict repair requires a snapshot-worktree path argument") });
+    return;
+  }
+  if (opts.dryRun) {
+    emit(await runProjectionConflictRepairDryRun({ snapshotWorktree, dryRun: true, reason: opts.reason }));
+  } else if (opts.approve) {
+    emit(await runProjectionConflictRepairExecute({ 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-Z6MEAGQI.js → managed-write-preflight-GJP4RN26.js}

@@ -6,7 +6,7 @@ import {
   runManagedWritePeerGate,
   runManagedWritePreflight,
   runManagedWriteTransaction
-} from "./chunk-CUSHQB5N.js";
+} from "./chunk-KZZUTQEA.js";
 import "./chunk-NG72ZD4C.js";
 import "./chunk-6AMXNODT.js";
 import "./chunk-MHGUYPGE.js";

package/dist/skillwiki-mcp.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import {
   runSkillwikiMcpStdio
-} from "./chunk-NTM3WRAV.js";
+} from "./chunk-EK7SNIU3.js";
 import "./chunk-7I2TPIV5.js";
 import "./chunk-NHRRYAXT.js";
-import "./chunk-CUSHQB5N.js";
+import "./chunk-KZZUTQEA.js";
 import "./chunk-NG72ZD4C.js";
 import "./chunk-JMV7YBQN.js";
 import "./chunk-6AMXNODT.js";

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

@@ -87,6 +87,15 @@ SNAPSHOT_WORKTREE="${WIKI_GIT_WORKTREE:-${SNAPSHOT_WORKTREE:-/root/wiki-git}}"
 LOCK_FILE="${WIKI_SNAPSHOT_LOCK:-/var/lock/wiki-snapshot.lock}"
 DEFAULT_LOG_DIR="$(platform_log_dir)"
 LOG_FILE="${WIKI_SNAPSHOT_LOG:-$DEFAULT_LOG_DIR/wiki-snapshot.log}"
+INHIBIT_AFTER="${WIKI_SNAPSHOT_INHIBIT_AFTER:-3}"
+INHIBIT_RECHECK_RUNS="${WIKI_SNAPSHOT_INHIBIT_RECHECK_RUNS:-6}"
+INHIBIT_RECHECK_SECONDS="${WIKI_SNAPSHOT_INHIBIT_RECHECK_SECONDS:-21600}"
+INHIBIT_STATE_FILE="${WIKI_SNAPSHOT_INHIBIT_STATE:-$(platform_cache_dir)/wiki-snapshot-inhibit.state}"
+case "$INHIBIT_AFTER" in ''|*[!0-9]*) INHIBIT_AFTER=3 ;; esac
+case "$INHIBIT_RECHECK_RUNS" in ''|*[!0-9]*) INHIBIT_RECHECK_RUNS=6 ;; esac
+case "$INHIBIT_RECHECK_SECONDS" in ''|*[!0-9]*) INHIBIT_RECHECK_SECONDS=21600 ;; esac
+if [ "$INHIBIT_AFTER" -lt 1 ]; then INHIBIT_AFTER=3; fi
+if [ "$INHIBIT_RECHECK_RUNS" -lt 1 ]; then INHIBIT_RECHECK_RUNS=6; fi
 CLOUD_REMOTE="${CLOUD_REMOTE:-cloud:cloud/wiki}"
 REPAIR_SCRIPT="${WIKI_GIT_REPAIR_SCRIPT:-$SCRIPT_DIR/wiki-git-repair-v3.sh}"
 MAX_S3_ONLY_NOTES="${WIKI_SNAPSHOT_MAX_S3_ONLY_NOTES:-200}"
@@ -337,6 +346,89 @@ log() {
     echo "$(date '+%Y-%m-%d %H:%M:%S') $1" | tee -a "$LOG_FILE"
 }
 
+snapshot_inhibit_clear() {
+    rm -f "$INHIBIT_STATE_FILE" 2>/dev/null || true
+}
+
+snapshot_inhibit_read_field() {
+    local key="$1"
+    [ -f "$INHIBIT_STATE_FILE" ] || return 0
+    sed -n "s/^${key}=//p" "$INHIBIT_STATE_FILE" 2>/dev/null | head -1
+}
+
+snapshot_inhibit_write() {
+    local opid="$1" count="$2" first_seen="$3" last_full="$4" skips="$5"
+    local dir
+    dir="$(dirname "$INHIBIT_STATE_FILE")"
+    mkdir -p "$dir" 2>/dev/null || return 0
+    {
+        printf 'opid=%s\n' "$opid"
+        printf 'count=%s\n' "$count"
+        printf 'first_seen=%s\n' "$first_seen"
+        printf 'last_full_epoch=%s\n' "$last_full"
+        printf 'skips_since_full=%s\n' "$skips"
+    } > "$INHIBIT_STATE_FILE" 2>/dev/null || true
+}
+
+snapshot_parse_operation_id() {
+    local file="$1"
+    [ -f "$file" ] || return 0
+    sed -n 's/.*"operation_id"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$file" 2>/dev/null | head -1
+}
+
+snapshot_inhibit_should_skip() {
+    local count last_full skips now age
+    [ -f "$INHIBIT_STATE_FILE" ] || return 1
+    count="$(snapshot_inhibit_read_field count)"
+    last_full="$(snapshot_inhibit_read_field last_full_epoch)"
+    skips="$(snapshot_inhibit_read_field skips_since_full)"
+    case "$count" in ''|*[!0-9]*) count=0 ;; esac
+    case "$last_full" in ''|*[!0-9]*) last_full=0 ;; esac
+    case "$skips" in ''|*[!0-9]*) skips=0 ;; esac
+    if [ "$count" -lt "$INHIBIT_AFTER" ]; then
+        return 1
+    fi
+    now="$(date +%s)"
+    age=$((now - last_full))
+    if [ "$age" -ge "$INHIBIT_RECHECK_SECONDS" ]; then
+        return 1
+    fi
+    if [ "$skips" -ge "$INHIBIT_RECHECK_RUNS" ]; then
+        return 1
+    fi
+    return 0
+}
+
+snapshot_inhibit_mark_skip() {
+    local opid count first_seen last_full skips
+    opid="$(snapshot_inhibit_read_field opid)"
+    count="$(snapshot_inhibit_read_field count)"
+    first_seen="$(snapshot_inhibit_read_field first_seen)"
+    last_full="$(snapshot_inhibit_read_field last_full_epoch)"
+    skips="$(snapshot_inhibit_read_field skips_since_full)"
+    case "$skips" in ''|*[!0-9]*) skips=0 ;; esac
+    skips=$((skips + 1))
+    snapshot_inhibit_write "$opid" "$count" "$first_seen" "$last_full" "$skips"
+}
+
+snapshot_inhibit_record_failure() {
+    local opid="$1"
+    local now count first_seen
+    [ -n "$opid" ] || return 0
+    now="$(date +%s)"
+    if [ -f "$INHIBIT_STATE_FILE" ] && [ "$(snapshot_inhibit_read_field opid)" = "$opid" ]; then
+        count="$(snapshot_inhibit_read_field count)"
+        first_seen="$(snapshot_inhibit_read_field first_seen)"
+        case "$count" in ''|*[!0-9]*) count=0 ;; esac
+        count=$((count + 1))
+        [ -n "$first_seen" ] || first_seen="$now"
+    else
+        count=1
+        first_seen="$now"
+    fi
+    snapshot_inhibit_write "$opid" "$count" "$first_seen" "$now" 0
+}
+
 snapshot_projection_hash_file() {
     local path="${1:-}"
     [ -f "$path" ] || return 1
@@ -522,6 +614,7 @@ emit_snapshot_complete() {
         log "ERROR: final snapshot proof failed head=$head_oid origin=$origin_oid"
         return 1
     fi
+    snapshot_inhibit_clear
     log "SNAPSHOT_COMPLETE schema=v1 outcome=${outcome} result=success ts=$(date -u +%Y-%m-%dT%H:%M:%SZ) head=${head_oid} origin=${origin_oid}"
     return 0
 }
@@ -671,6 +764,12 @@ if ! snapshot_freeze_git_receipt; then
     exit 1
 fi
 
+if snapshot_inhibit_should_skip; then
+    snapshot_inhibit_mark_skip
+    log "SNAPSHOT_INHIBITED schema=v1 opid=$(snapshot_inhibit_read_field opid) count=$(snapshot_inhibit_read_field count) first_seen=$(snapshot_inhibit_read_field first_seen)"
+    exit 1
+fi
+
 # Single-authority root projections before FUSE/S3 pull promotion.
 # Mutation target is the live vault ($WIKI_DIR); Git pull/base-OID use
 # $SNAPSHOT_WORKTREE so FUSE/S3 hosts without a local Git HEAD still work.
@@ -691,11 +790,17 @@ if command -v "$SKILLWIKI_BIN" >/dev/null 2>&1; then
             exit 1
             ;;
     esac
+    proj_out="$(mktemp)"
     if ! "$SKILLWIKI_BIN" projections materialize "$WIKI_DIR" --write \
-        --converge-vault "$SNAPSHOT_WORKTREE" >>"$LOG_FILE" 2>&1; then
+        --converge-vault "$SNAPSHOT_WORKTREE" >"$proj_out" 2>&1; then
+        cat "$proj_out" >>"$LOG_FILE" 2>/dev/null || true
+        snapshot_inhibit_record_failure "$(snapshot_parse_operation_id "$proj_out")"
+        rm -f "$proj_out"
         log "FAIL root projection materialization; snapshot promotion refused"
         exit 1
     fi
+    cat "$proj_out" >>"$LOG_FILE" 2>/dev/null || true
+    rm -f "$proj_out"
     log "OK projections materialize before snapshot sync"
     if ! snapshot_freeze_projection_expectations; then
         log "FAIL projection expectation freeze; snapshot promotion refused"

package/package.json

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

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

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