skillwiki 0.10.26 → 0.10.28

package/dist/chunk-NOXDRIHM.js

@@ -0,0 +1,1194 @@
+#!/usr/bin/env node
+import {
+  FLEET_REL_PATH,
+  acquireLock,
+  appendLastOp,
+  buildDegradedReasons,
+  clearLastOp,
+  findReviewRequiredOp,
+  fixPathTooLong,
+  getSessionId,
+  git,
+  gitStrict,
+  hasActiveGitSequencer,
+  hasUnmergedPaths,
+  loadFleetManifestAndHost,
+  probeRemoteHealth,
+  readLastOp,
+  readLock,
+  releaseLock,
+  resolveConfiguredSnapshotWorktree,
+  runLint,
+  runSyncLintDelta,
+  runVaultSyncPullHelper,
+  supersedeStaleReviewRequiredJournals
+} from "./chunk-5XQWYC5K.js";
+import {
+  ExitCode,
+  err,
+  ok
+} from "./chunk-RQARJ6HB.js";
+
+// src/utils/managed-write-preflight.ts
+import { existsSync as existsSync3 } from "fs";
+import { join as join3, resolve as resolve2 } from "path";
+
+// src/commands/sync.ts
+import { existsSync } from "fs";
+import { join } from "path";
+import { execFileSync } from "child_process";
+
+// src/utils/vault-git-pathspec.ts
+var VAULT_GENERATED_COMMIT_PATHS = [
+  ".skillwiki/last-op.json",
+  ".skillwiki/memory",
+  ".skillwiki/memory-topics.json"
+];
+var VAULT_GENERATED_COMMIT_EXCLUDES = [
+  ...VAULT_GENERATED_COMMIT_PATHS.map((path) => `:!${path}`)
+];
+var VAULT_COMMIT_PATHSPEC = [".", ...VAULT_GENERATED_COMMIT_EXCLUDES];
+function stageVaultContentChanges(vault) {
+  gitStrict(vault, ["add", "-A", "--", "."]);
+  for (const generatedPath of VAULT_GENERATED_COMMIT_PATHS) {
+    try {
+      gitStrict(vault, ["reset", "HEAD", "--", generatedPath]);
+    } catch (_e) {
+    }
+  }
+}
+
+// src/commands/sync.ts
+function parseDirtyPaths(porcelain) {
+  if (!porcelain) return [];
+  return porcelain.split("\n").map((line) => line.trimEnd()).filter((line) => line.length >= 4).map((line) => {
+    const payload = line.length >= 3 && line[2] === " " ? line.slice(3) : line.length >= 2 && line[1] === " " ? line.slice(2) : line;
+    const arrow = payload.lastIndexOf(" -> ");
+    return arrow >= 0 ? payload.slice(arrow + 4) : payload;
+  }).filter((path) => path.length > 0);
+}
+function splitNonEmptyLines(text) {
+  if (!text) return [];
+  return text.split("\n").map((line) => line.trim()).filter((line) => line.length > 0);
+}
+function isTrackedNotePath(path) {
+  if (!path.endsWith(".md")) return false;
+  return !/^\.(skillwiki|claude|obsidian|antigravitycli|playwright-cli)\//.test(path);
+}
+function refHasPath(vault, ref, path) {
+  try {
+    execFileSync("git", ["cat-file", "-e", `${ref}:${path}`], {
+      cwd: vault,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function runSyncStatus(input) {
+  const vault = input.vault;
+  const includeStashes = input.includeStashes ?? false;
+  if (!existsSync(join(vault, ".git"))) {
+    return {
+      exitCode: ExitCode.VAULT_PATH_INVALID,
+      result: ok({
+        is_git_repo: false,
+        dirty: 0,
+        ahead: 0,
+        behind: 0,
+        unpromoted_note_paths: 0,
+        unpromoted_note_examples: [],
+        last_commit: "never",
+        status: "not_a_repo",
+        humanHint: "not a git repository"
+      })
+    };
+  }
+  enableGitLongPathsOnWindows(vault);
+  const porcelain = git(vault, ["status", "--porcelain"]);
+  const dirty = porcelain ? porcelain.split("\n").filter((l) => l.trim().length > 0).length : 0;
+  const dirtyPaths = parseDirtyPaths(porcelain);
+  const untrackedPaths = splitNonEmptyLines(git(vault, ["ls-files", "--others", "--exclude-standard"]));
+  const revOutput = git(vault, ["rev-list", "--left-right", "--count", "origin/HEAD...HEAD"]);
+  let ahead = 0;
+  let behind = 0;
+  if (revOutput) {
+    const parts = revOutput.split(/\s+/);
+    behind = parseInt(parts[0], 10) || 0;
+    ahead = parseInt(parts[1], 10) || 0;
+  }
+  const tsRaw = git(vault, ["log", "-1", "--format=%ct"]);
+  let last_commit;
+  if (tsRaw) {
+    const ts = parseInt(tsRaw, 10);
+    if (!isNaN(ts) && ts > 0) {
+      last_commit = new Date(ts * 1e3).toISOString();
+    } else {
+      last_commit = "never";
+    }
+  } else {
+    last_commit = "never";
+  }
+  const remoteRef = git(vault, ["rev-parse", "--verify", "origin/main"]) ? "origin/main" : git(vault, ["rev-parse", "--verify", "origin/HEAD"]) ? "origin/HEAD" : "HEAD";
+  const unpromotedNoteAll = Array.from(/* @__PURE__ */ new Set([...dirtyPaths, ...untrackedPaths])).filter(isTrackedNotePath).filter((path) => !refHasPath(vault, remoteRef, path));
+  const unpromotedNoteExamples = unpromotedNoteAll.slice(0, 5);
+  const unpromotedNotePaths = unpromotedNoteAll.length;
+  let status;
+  if (dirty > 0) {
+    status = "dirty";
+  } else if (ahead > 0) {
+    status = "ahead";
+  } else if (behind > 0) {
+    status = "behind";
+  } else {
+    status = "clean";
+  }
+  const hintLines = [
+    `status: ${status}`,
+    `dirty: ${dirty}`,
+    `ahead: ${ahead}`,
+    `behind: ${behind}`,
+    `unpromoted_note_paths: ${unpromotedNotePaths}`,
+    `last_commit: ${last_commit}`
+  ];
+  const exitCode = status === "clean" ? ExitCode.OK : ExitCode.LINT_HAS_WARNINGS;
+  let stashes;
+  if (includeStashes) {
+    stashes = enumerateStashes(vault);
+  }
+  const output = {
+    is_git_repo: true,
+    dirty,
+    ahead,
+    behind,
+    unpromoted_note_paths: unpromotedNotePaths,
+    unpromoted_note_examples: unpromotedNoteExamples,
+    last_commit,
+    status,
+    humanHint: hintLines.join("\n")
+  };
+  if (stashes !== void 0) {
+    output.stashes = stashes;
+  }
+  if (input.includeRemoteHealth) {
+    const home = input.home ?? process.env.HOME ?? "";
+    const remote_health = probeRemoteHealth({
+      vaultPath: vault,
+      home,
+      s3Remote: input.s3Remote,
+      snapshotterAlias: input.snapshotterAlias,
+      checkSnapshotter: input.checkSnapshotter,
+      exec: input.execProbe
+    });
+    output.remote_health = remote_health;
+    const degraded = buildDegradedReasons(remote_health);
+    if (degraded.length > 0) {
+      output.degraded_reasons = degraded;
+      hintLines.push(`degraded_reasons: ${degraded.join(", ")}`);
+      output.humanHint = hintLines.join("\n");
+    }
+  }
+  return {
+    exitCode,
+    result: ok(output)
+  };
+}
+async function runSyncPush(input) {
+  const vault = input.vault;
+  if (!existsSync(join(vault, ".git"))) {
+    return {
+      exitCode: ExitCode.VAULT_PATH_INVALID,
+      result: err("NOT_A_GIT_REPO", { path: vault })
+    };
+  }
+  enableGitLongPathsOnWindows(vault);
+  let pathFixes = 0;
+  const pathFix = await fixPathTooLong({ vault });
+  if (pathFix.result.ok && pathFix.result.data.fixed.length > 0) {
+    pathFixes = pathFix.result.data.fixed.length;
+    appendLastOp(vault, {
+      operation: "lint-fix",
+      summary: `fixed ${pathFixes} long path(s)`,
+      files: pathFix.result.data.fixed.flatMap((f) => [f.from, f.to]),
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+  const porcelain = git(vault, ["status", "--porcelain"]);
+  const dirtyFiles = porcelain ? porcelain.split("\n").filter((l) => l.trim().length > 0) : [];
+  if (dirtyFiles.length === 0) {
+    return {
+      exitCode: ExitCode.OK,
+      result: ok({
+        files_committed: 0,
+        commit_message: "",
+        pushed: false,
+        path_fixes: pathFixes,
+        humanHint: "nothing to commit, working tree clean"
+      })
+    };
+  }
+  let delta = { full_errors: 0, base_errors: 0, new_errors: 0, resolved_errors: 0 };
+  const preferredBase = git(vault, ["rev-parse", "--verify", "origin/main"]) ? "origin/main" : git(vault, ["rev-parse", "--verify", "origin/HEAD"]) ? "origin/HEAD" : "";
+  if (preferredBase) {
+    const deltaResult = await runSyncLintDelta({ vault, baseRef: preferredBase });
+    if (!deltaResult.result.ok) {
+      return {
+        exitCode: ExitCode.LINT_HAS_ERRORS,
+        result: err("LINT_DELTA_UNAVAILABLE", {
+          message: "lint-delta evidence missing or failed \u2014 fail closed",
+          detail: deltaResult.result
+        })
+      };
+    }
+    delta = deltaResult.result.data;
+    if (delta.new_errors > 0) {
+      return {
+        exitCode: ExitCode.LINT_HAS_ERRORS,
+        result: err("LINT_NEW_ERRORS_BLOCK_PUSH", {
+          full_errors: delta.full_errors,
+          base_errors: delta.base_errors,
+          new_errors: delta.new_errors,
+          resolved_errors: delta.resolved_errors,
+          new_fingerprints: deltaResult.result.data.new_fingerprints
+        })
+      };
+    }
+  } else {
+    const lintResult = await runLint({ vault, days: 90, lines: 200, logThreshold: 500 });
+    if (lintResult.result.ok) {
+      const fullErrors = lintResult.result.data.summary.errors;
+      delta = { full_errors: fullErrors, base_errors: 0, new_errors: fullErrors, resolved_errors: 0 };
+      if (fullErrors > 0) {
+        const buckets = "by_severity" in lintResult.result.data ? lintResult.result.data.by_severity.error : [];
+        return {
+          exitCode: ExitCode.LINT_HAS_ERRORS,
+          result: err("LINT_ERRORS_BLOCK_PUSH", {
+            errors: fullErrors,
+            buckets,
+            message: "no origin base ref for delta; absolute lint errors block push"
+          })
+        };
+      }
+    } else {
+      delta = { full_errors: 0, base_errors: 0, new_errors: 0, resolved_errors: 0 };
+    }
+  }
+  try {
+    stageVaultContentChanges(vault);
+  } catch (e) {
+    return {
+      exitCode: ExitCode.SYNC_PUSH_FAILED,
+      result: err("GIT_ADD_FAILED", { message: String(e) })
+    };
+  }
+  const lastOps = readLastOp(vault);
+  let commitMessage;
+  if (lastOps.length > 0) {
+    commitMessage = lastOps.map((op) => `${op.operation}: ${op.summary} (${op.files.length} files)`).join("; ");
+  } else {
+    const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d{3}Z$/, "Z");
+    commitMessage = `sync: vault update ${timestamp}`;
+  }
+  try {
+    gitStrict(vault, ["commit", "-m", commitMessage]);
+  } catch (e) {
+    return {
+      exitCode: ExitCode.SYNC_PUSH_FAILED,
+      result: err("GIT_COMMIT_FAILED", { message: String(e) })
+    };
+  }
+  clearLastOp(vault);
+  let pushed = false;
+  try {
+    gitStrict(vault, ["push", "origin", "HEAD"]);
+    pushed = true;
+  } catch (e) {
+    return {
+      exitCode: ExitCode.SYNC_PUSH_FAILED,
+      result: ok({
+        files_committed: dirtyFiles.length,
+        commit_message: commitMessage,
+        pushed: false,
+        path_fixes: pathFixes,
+        humanHint: `committed ${dirtyFiles.length} file(s)${pathFixes > 0 ? ` after ${pathFixes} long-path fix(es)` : ""} but push failed: ${String(e)}`
+      })
+    };
+  }
+  const inheritedNote = delta.full_errors > 0 ? `; lint full=${delta.full_errors} base=${delta.base_errors} new=${delta.new_errors} resolved=${delta.resolved_errors} (inherited debt only)` : `; lint full=0 new=0`;
+  return {
+    exitCode: ExitCode.OK,
+    result: ok({
+      files_committed: dirtyFiles.length,
+      commit_message: commitMessage,
+      pushed,
+      path_fixes: pathFixes,
+      lint_full_errors: delta.full_errors,
+      lint_base_errors: delta.base_errors,
+      lint_new_errors: delta.new_errors,
+      lint_resolved_errors: delta.resolved_errors,
+      humanHint: `committed and pushed ${dirtyFiles.length} file(s)${pathFixes > 0 ? ` after ${pathFixes} long-path fix(es)` : ""}${inheritedNote}`
+    })
+  };
+}
+function enumerateStashes(vault, nowMs = Date.now()) {
+  const output = git(vault, ["log", "--format=%gd%x09%H%x09%s%x09%ct", "-g", "stash"]);
+  if (!output) return [];
+  const stashes = [];
+  const lines = output.split("\n").filter((l) => l.trim().length > 0);
+  for (const line of lines) {
+    const parts = line.split("	");
+    if (parts.length < 4) continue;
+    const ref = parts[0];
+    const oid = parts[1];
+    const message = parts[2];
+    const ctStr = parts[3];
+    const ct = parseInt(ctStr, 10);
+    if (isNaN(ct)) continue;
+    const age_minutes = Math.floor((nowMs - ct * 1e3) / (60 * 1e3));
+    stashes.push({ ref, oid, message, age_minutes });
+  }
+  return stashes;
+}
+function enableGitLongPathsOnWindows(vault) {
+  if (process.platform !== "win32") return;
+  git(vault, ["config", "core.longpaths", "true"]);
+}
+async function runSyncPull(input) {
+  const vault = input.vault;
+  if (!existsSync(join(vault, ".git"))) {
+    return {
+      exitCode: ExitCode.VAULT_PATH_INVALID,
+      result: err("NOT_A_GIT_REPO", { path: vault })
+    };
+  }
+  enableGitLongPathsOnWindows(vault);
+  const remoteUrl = git(vault, ["remote", "get-url", "origin"]);
+  if (!remoteUrl) {
+    return {
+      exitCode: ExitCode.SYNC_PULL_FAILED,
+      result: err("GIT_PULL_FAILED", { message: "no remote configured (origin)" })
+    };
+  }
+  const helper = await runVaultSyncPullHelper({ vault, remote: "origin", branch: "main" });
+  if (!helper.ok) {
+    if (helper.error === "PREFLIGHT_FAILED") {
+      return {
+        exitCode: ExitCode.PREFLIGHT_FAILED,
+        result: err("PREFLIGHT_FAILED", helper.detail)
+      };
+    }
+    return {
+      exitCode: ExitCode.SYNC_PULL_FAILED,
+      result: err("GIT_PULL_FAILED", helper.detail)
+    };
+  }
+  const fetched = true;
+  const pulled = helper.data.changed;
+  const conflicts = 0;
+  const autoResolved = 0;
+  let filesUpdated = 0;
+  if (helper.data.changed) {
+    const diffOutput = git(vault, ["diff", "--stat", `${helper.data.before_oid}..${helper.data.after_oid}`]);
+    if (diffOutput) {
+      const fileMatch = diffOutput.match(/(\d+) file[s]? changed/);
+      if (fileMatch) filesUpdated = parseInt(fileMatch[1], 10);
+    }
+  }
+  const pathFix = await fixPathTooLong({ vault });
+  const pathFixCount = pathFix.result.ok ? pathFix.result.data.fixed.length : 0;
+  let lintErrors = 0;
+  let lintWarnings = 0;
+  const lintResult = await runLint({ vault, days: 90, lines: 200, logThreshold: 500 });
+  if (lintResult.result.ok) {
+    lintErrors = lintResult.result.data.summary.errors;
+    lintWarnings = lintResult.result.data.summary.warnings;
+  }
+  const hintParts = [];
+  if (filesUpdated > 0) hintParts.push(`updated ${filesUpdated} file(s)`);
+  else hintParts.push(pulled ? "pulled via vault-sync helper" : "already up to date");
+  if (pathFixCount > 0) hintParts.push(`${pathFixCount} long path(s) fixed`);
+  if (lintErrors > 0) hintParts.push(`${lintErrors} lint error(s)`);
+  if (lintWarnings > 0) hintParts.push(`${lintWarnings} lint warning(s)`);
+  const exitCode = lintErrors > 0 ? ExitCode.LINT_HAS_ERRORS : lintWarnings > 0 ? ExitCode.LINT_HAS_WARNINGS : ExitCode.OK;
+  return {
+    exitCode,
+    result: ok({
+      fetched,
+      pulled,
+      files_updated: filesUpdated,
+      conflicts,
+      auto_resolved: autoResolved,
+      lint_errors: lintErrors,
+      lint_warnings: lintWarnings,
+      humanHint: hintParts.join(", ")
+    })
+  };
+}
+var STASH_AUDIT_CLASSIFICATIONS = [
+  "recent_known_peer_stash",
+  "self_or_local_recovery_stash",
+  "stale_stash_backlog",
+  "unknown_stash_ownership"
+];
+var STASH_AUDIT_FORMATS = ["wiki-sync", "vault-sync", "manual", "unknown"];
+var STASH_RECENT_MINUTES = 120;
+var MANAGED_WRITER_SPECS = [
+  ["wiki-push", /(?:^|[\s/\\])wiki-push(?:\.[a-z0-9_-]+)?(?:\s|$)/i],
+  ["rclone", /(?:^|[\s/\\])rclone(?:\.[a-z0-9_-]+)?(?:\s|$)/i],
+  ["vault-sync", /(?:^|[\s/\\])vault-sync(?:\.[a-z0-9_-]+)?(?:\s|$)/i]
+];
+var MANAGED_WRITER_KINDS = MANAGED_WRITER_SPECS.map(([kind]) => kind);
+function classifyStash(ageMinutes, sessionId, currentSession) {
+  if (sessionId && sessionId === currentSession) return "self_or_local_recovery_stash";
+  if (sessionId && ageMinutes <= STASH_RECENT_MINUTES) return "recent_known_peer_stash";
+  if (ageMinutes > STASH_RECENT_MINUTES) return "stale_stash_backlog";
+  return "unknown_stash_ownership";
+}
+function classifyManagedWriterProcesses(snapshot, currentPid = process.pid) {
+  const kinds = /* @__PURE__ */ new Set();
+  let count = 0;
+  for (const line of snapshot.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let pid;
+    let processName = "";
+    const csvMatch = trimmed.match(/^"([^"]*)","(\d+)"(?:,|$)/);
+    if (csvMatch) {
+      processName = csvMatch[1];
+      pid = Number(csvMatch[2]);
+    } else {
+      const pidMatch = trimmed.match(/^(\d+)\s+(.*)$/);
+      if (!pidMatch) continue;
+      pid = Number(pidMatch[1]);
+      processName = pidMatch[2];
+    }
+    if (pid === currentPid) continue;
+    const kind = MANAGED_WRITER_SPECS.find(([, pattern]) => pattern.test(processName))?.[0];
+    if (!kind) continue;
+    count += 1;
+    kinds.add(kind);
+  }
+  return { count, kinds: [...kinds].sort(), blocking: count > 0 };
+}
+function managedWriterSnapshot() {
+  try {
+    if (process.platform === "win32") {
+      return execFileSync("tasklist", ["/FO", "CSV", "/NH"], {
+        encoding: "utf8",
+        stdio: ["pipe", "pipe", "pipe"]
+      });
+    }
+    return execFileSync("ps", ["-axo", "pid=,command="], {
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+  } catch {
+    return "";
+  }
+}
+function runSyncPeers(input) {
+  const vault = input.vault;
+  const currentSession = input.sessionId ?? getSessionId();
+  const locks = [];
+  const existingLock = readLock(vault);
+  if (existingLock) {
+    const self = existingLock.session_id === currentSession;
+    locks.push({ ...existingLock, is_self: self });
+  }
+  const allStashes = enumerateStashes(vault, input.nowMs);
+  const stashes = [];
+  const wikiSyncAudit = [];
+  const otherStashAudit = [];
+  for (const stash of allStashes) {
+    let actualMessage = stash.message;
+    const prefixMatch = stash.message.match(/^On [^:]+:\s*(.*)/);
+    if (prefixMatch) {
+      actualMessage = prefixMatch[1];
+    }
+    const match = actualMessage.match(/^wiki-sync:([^:]+):([^:]+):(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z):(.*)$/);
+    if (match) {
+      const session_id = match[1];
+      const cwd_hash = match[2];
+      const timestamp = match[3];
+      const summary = match[4];
+      stashes.push({
+        ref: stash.ref,
+        oid: stash.oid,
+        session_id,
+        cwd_hash,
+        timestamp,
+        summary,
+        age_minutes: stash.age_minutes
+      });
+      wikiSyncAudit.push({
+        ref: stash.ref,
+        oid: stash.oid,
+        age_minutes: stash.age_minutes,
+        classification: classifyStash(stash.age_minutes, session_id, currentSession),
+        format: "wiki-sync",
+        session_id
+      });
+      continue;
+    }
+    const vaultSyncMatch = actualMessage.match(/^vault-sync\s+op=([^\s]+)(?:\s+.*)?$/i);
+    const operationId = vaultSyncMatch?.[1];
+    const manualPeer = /^peer$/i.test(actualMessage.trim());
+    const format = operationId ? "vault-sync" : manualPeer ? "manual" : "unknown";
+    const classification = operationId ? stash.age_minutes <= STASH_RECENT_MINUTES ? "recent_known_peer_stash" : "stale_stash_backlog" : "unknown_stash_ownership";
+    otherStashAudit.push({
+      ref: stash.ref,
+      oid: stash.oid,
+      age_minutes: stash.age_minutes,
+      classification,
+      format,
+      ...operationId ? { operation_id: operationId } : {}
+    });
+  }
+  const stashAudit = [...wikiSyncAudit, ...otherStashAudit];
+  const managedWriters = classifyManagedWriterProcesses(
+    input.processSnapshot ?? managedWriterSnapshot()
+  );
+  const hintParts = [];
+  if (locks.length > 0) hintParts.push(`${locks.length} lock(s)`);
+  if (stashes.length > 0) hintParts.push(`${stashes.length} wiki-sync stash(es)`);
+  if (managedWriters.count > 0) hintParts.push(`${managedWriters.count} live writer overlap(s)`);
+  if (stashAudit.length > 0) hintParts.push(`${stashAudit.length} stash audit item(s)`);
+  const blocking = locks.some((lock) => !lock.is_self) || managedWriters.blocking || stashAudit.some((entry) => entry.classification === "recent_known_peer_stash");
+  const humanHint = hintParts.length > 0 ? hintParts.join(", ") : "no peers detected";
+  return {
+    exitCode: ExitCode.OK,
+    result: ok({
+      locks,
+      stashes,
+      stash_audit: stashAudit,
+      managed_writers: managedWriters,
+      blocking,
+      humanHint
+    })
+  };
+}
+function runSyncLock(input) {
+  const vault = input.vault;
+  if (!existsSync(vault)) {
+    return {
+      exitCode: ExitCode.VAULT_PATH_INVALID,
+      result: err("VAULT_PATH_INVALID", { path: vault })
+    };
+  }
+  const result = acquireLock(vault, {
+    sessionId: input.sessionId,
+    summary: input.summary,
+    ttlMinutes: input.ttlMinutes,
+    force: input.force
+  });
+  if (result.ok) {
+    return {
+      exitCode: ExitCode.OK,
+      result: ok({
+        acquired: true,
+        lock: result.lock,
+        humanHint: `lock acquired for ${result.lock.summary} (expires ${result.lock.expires})`
+      })
+    };
+  } else {
+    return {
+      exitCode: ExitCode.SYNC_LOCK_HELD,
+      result: ok({
+        acquired: false,
+        lock: result.held,
+        held_by: result.held,
+        humanHint: `lock held by session ${result.held.session_id} (PID ${result.held.pid}) for ${result.held.summary}`
+      })
+    };
+  }
+}
+function runSyncUnlock(input) {
+  const vault = input.vault;
+  if (!existsSync(vault)) {
+    return {
+      exitCode: ExitCode.VAULT_PATH_INVALID,
+      result: err("VAULT_PATH_INVALID", { path: vault })
+    };
+  }
+  const result = releaseLock(vault, { sessionId: input.sessionId, force: input.force });
+  let humanHint;
+  if (result.released && result.prior) {
+    humanHint = `lock force-released (was held by session ${result.prior.session_id}, PID ${result.prior.pid})`;
+  } else if (result.released) {
+    humanHint = "lock released";
+  } else {
+    humanHint = "lock not held by this session (no-op)";
+  }
+  const output = {
+    released: result.released,
+    humanHint
+  };
+  if (result.prior) {
+    output.prior = {
+      session_id: result.prior.session_id,
+      pid: result.prior.pid,
+      summary: result.prior.summary
+    };
+  }
+  return {
+    exitCode: ExitCode.OK,
+    result: ok(output)
+  };
+}
+
+// src/utils/managed-write-lock.ts
+import { randomBytes } from "crypto";
+import {
+  existsSync as existsSync2,
+  mkdirSync,
+  readFileSync,
+  unlinkSync,
+  writeFileSync
+} from "fs";
+import { hostname } from "os";
+import { dirname, join as join2, resolve } from "path";
+function managedWriteLockPath(vault) {
+  const gitPath = git(vault, ["rev-parse", "--git-path", "vault-sync/managed-write.lock"]);
+  if (gitPath) return gitPath.startsWith("/") ? gitPath : join2(vault, gitPath);
+  return join2(vault, ".skillwiki", "managed-write.lock");
+}
+function readLockRecord(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function isManagedWriteLockOwnerAlive(pid) {
+  if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    if (error.code === "EPERM") return true;
+    return false;
+  }
+}
+function hasUnsafeGitState(vault) {
+  const gitDirRaw = git(vault, ["rev-parse", "--git-dir"]);
+  if (!gitDirRaw) return true;
+  const gitDir = gitDirRaw.startsWith("/") ? gitDirRaw : join2(vault, gitDirRaw);
+  for (const rel of ["rebase-merge", "rebase-apply"]) {
+    if (existsSync2(join2(gitDir, rel))) return true;
+  }
+  for (const rel of ["MERGE_HEAD", "CHERRY_PICK_HEAD", "REVERT_HEAD"]) {
+    if (existsSync2(join2(gitDir, rel))) return true;
+  }
+  const unmerged = git(vault, ["ls-files", "-u"]);
+  return Boolean(unmerged && unmerged.trim().length > 0);
+}
+function isGitBackedVault(vault) {
+  return Boolean(git(vault, ["rev-parse", "--absolute-git-dir"]));
+}
+function hasLocalOwnerProof(vault, record) {
+  return isGitBackedVault(vault) || typeof record.owner_hostname === "string" && record.owner_hostname === hostname();
+}
+function reclaimDeadManagedWriteLockOwner(vault, options = {}) {
+  const path = managedWriteLockPath(vault);
+  const gitStateVault = resolve(options.gitStateVault ?? vault);
+  if (!existsSync2(path)) return ok({ reclaimed: false });
+  const record = readLockRecord(path);
+  if (!record) {
+    return err("SYNC_LOCK_HELD", { path, message: "managed-write lock unreadable" });
+  }
+  if (!hasLocalOwnerProof(vault, record)) {
+    return err("SYNC_LOCK_HELD", {
+      path,
+      owner_hostname: record.owner_hostname,
+      current_hostname: hostname(),
+      message: "managed-write lock origin is foreign or unknown"
+    });
+  }
+  if (isManagedWriteLockOwnerAlive(record.pid)) {
+    return err("SYNC_LOCK_HELD", { path, message: "managed-write lock owner is alive" });
+  }
+  if (hasUnsafeGitState(gitStateVault)) {
+    return err("SYNC_LOCK_HELD", {
+      path,
+      git_state_vault: gitStateVault,
+      message: "managed-write lock not reclaimed: unsafe git state"
+    });
+  }
+  try {
+    const recoveryDir = join2(dirname(path), "recovery");
+    mkdirSync(recoveryDir, { recursive: true });
+    const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z");
+    const recoveryPath = join2(recoveryDir, `stale-managed-write-lock-${stamp}-${process.pid}.json`);
+    const meta = {
+      recovered_at: (/* @__PURE__ */ new Date()).toISOString(),
+      recovery_reason: "owner_pid_dead",
+      owner_pid_alive: false,
+      git_state_vault: gitStateVault,
+      lock: record
+    };
+    writeFileSync(recoveryPath, `${JSON.stringify(meta, null, 2)}
+`, { flag: "wx" });
+    unlinkSync(path);
+    return ok({ reclaimed: true, recoveryPath });
+  } catch (error) {
+    return err("WRITE_FAILED", { path, message: String(error) });
+  }
+}
+function tryCreateLock(path, command) {
+  const ownerToken = randomBytes(16).toString("hex");
+  const acquired = (/* @__PURE__ */ new Date()).toISOString();
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(
+      path,
+      `${JSON.stringify({
+        pid: process.pid,
+        owner_hostname: hostname(),
+        owner_token: ownerToken,
+        acquired,
+        command
+      })}
+`,
+      { flag: "wx" }
+    );
+    return ok({ vault: "", path, ownerToken, acquired });
+  } catch (error) {
+    if (error.code === "EEXIST") return err("SYNC_LOCK_HELD", { path });
+    return err("WRITE_FAILED", { path, message: String(error) });
+  }
+}
+function acquireManagedWriteLock(vault, command, options = {}) {
+  const path = managedWriteLockPath(vault);
+  const first = tryCreateLock(path, command);
+  if (first.ok) {
+    return ok({ ...first.data, vault });
+  }
+  if (first.error !== "SYNC_LOCK_HELD") return first;
+  const reclaimed = reclaimDeadManagedWriteLockOwner(vault, options);
+  if (!reclaimed.ok || !reclaimed.data.reclaimed) {
+    return err("SYNC_LOCK_HELD", { path });
+  }
+  const second = tryCreateLock(path, command);
+  if (second.ok) return ok({ ...second.data, vault });
+  return second.ok === false ? second : err("SYNC_LOCK_HELD", { path });
+}
+function releaseManagedWriteLock(handle) {
+  try {
+    const parsed = JSON.parse(readFileSync(handle.path, "utf8"));
+    if (parsed.owner_token !== handle.ownerToken || parsed.acquired !== handle.acquired) {
+      return err("SYNC_LOCK_HELD", {
+        path: handle.path,
+        message: "managed-write lock ownership changed"
+      });
+    }
+    unlinkSync(handle.path);
+    return ok({ released: true });
+  } catch (error) {
+    return err("WRITE_FAILED", { path: handle.path, message: String(error) });
+  }
+}
+
+// src/utils/managed-write-preflight.ts
+var DEFAULT_DEPS = {
+  converge: (input) => runVaultSyncPullHelper(input),
+  resolveConfiguredSnapshotWorktree,
+  syncPeers: runSyncPeers
+};
+var SAFE_MANAGED_WRITER_KINDS = new Set(MANAGED_WRITER_KINDS);
+var SAFE_STASH_AUDIT_CLASSIFICATIONS = new Set(STASH_AUDIT_CLASSIFICATIONS);
+var SAFE_STASH_AUDIT_FORMATS = new Set(STASH_AUDIT_FORMATS);
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function isNonNegativeFiniteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+function isNonNegativeInteger(value) {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+function isPeerLock(value) {
+  if (!isRecord(value)) return false;
+  return typeof value.session_id === "string" && isNonNegativeInteger(value.pid) && typeof value.cwd === "string" && typeof value.summary === "string" && typeof value.acquired === "string" && typeof value.expires === "string" && typeof value.is_self === "boolean";
+}
+function isWikiSyncStash(value) {
+  if (!isRecord(value)) return false;
+  return typeof value.ref === "string" && typeof value.oid === "string" && typeof value.session_id === "string" && typeof value.cwd_hash === "string" && typeof value.timestamp === "string" && typeof value.summary === "string" && isNonNegativeFiniteNumber(value.age_minutes);
+}
+function isStashAuditEntry(value) {
+  if (!isRecord(value)) return false;
+  if (typeof value.ref !== "string" || typeof value.oid !== "string" || !isNonNegativeFiniteNumber(value.age_minutes) || typeof value.classification !== "string" || !SAFE_STASH_AUDIT_CLASSIFICATIONS.has(value.classification) || typeof value.format !== "string" || !SAFE_STASH_AUDIT_FORMATS.has(value.format)) {
+    return false;
+  }
+  if (value.session_id !== void 0 && typeof value.session_id !== "string") return false;
+  if (value.operation_id !== void 0 && typeof value.operation_id !== "string") return false;
+  return true;
+}
+function isManagedWriterObservation(value) {
+  if (!isRecord(value) || !Array.isArray(value.kinds)) return false;
+  if (!isNonNegativeInteger(value.count) || typeof value.blocking !== "boolean" || value.kinds.some(
+    (kind) => typeof kind !== "string" || !SAFE_MANAGED_WRITER_KINDS.has(kind)
+  )) {
+    return false;
+  }
+  if (value.blocking !== value.count > 0) return false;
+  if (value.count === 0 && value.kinds.length > 0) return false;
+  if (value.count > 0 && value.kinds.length === 0) return false;
+  return true;
+}
+function validateSyncPeersOutput(value) {
+  if (!isRecord(value)) return null;
+  if (!Array.isArray(value.locks) || !Array.isArray(value.stashes) || !Array.isArray(value.stash_audit) || typeof value.humanHint !== "string" || typeof value.blocking !== "boolean" || !isManagedWriterObservation(value.managed_writers)) {
+    return null;
+  }
+  let foreignLockCount = 0;
+  for (const lock of value.locks) {
+    if (!isPeerLock(lock)) return null;
+    if (!lock.is_self) foreignLockCount += 1;
+  }
+  for (const stash of value.stashes) {
+    if (!isWikiSyncStash(stash)) return null;
+  }
+  let recentPeerStashCount = 0;
+  for (const entry of value.stash_audit) {
+    if (!isStashAuditEntry(entry)) return null;
+    if (entry.classification === "recent_known_peer_stash") recentPeerStashCount += 1;
+  }
+  return {
+    output: value,
+    foreignLockCount,
+    recentPeerStashCount
+  };
+}
+function peerCheckFailure(reason, detail = {}) {
+  return {
+    exitCode: ExitCode.PREFLIGHT_FAILED,
+    result: err("PREFLIGHT_FAILED", { reason, ...detail })
+  };
+}
+function runManagedWritePeerGate(vault, deps) {
+  try {
+    const check = (deps.syncPeers ?? DEFAULT_DEPS.syncPeers)({ vault });
+    if (check.exitCode !== ExitCode.OK || !check.result.ok) {
+      return peerCheckFailure("peer-check-failed");
+    }
+    const validated = validateSyncPeersOutput(check.result.data);
+    if (!validated) {
+      return peerCheckFailure("peer-check-failed");
+    }
+    const { output: peerOutput, foreignLockCount, recentPeerStashCount } = validated;
+    const hasKnownBlockingSignal = foreignLockCount > 0 || peerOutput.managed_writers.blocking || recentPeerStashCount > 0;
+    if (!peerOutput.blocking) {
+      return hasKnownBlockingSignal ? peerCheckFailure("peer-check-failed") : null;
+    }
+    if (peerOutput.managed_writers.blocking) {
+      return peerCheckFailure("live-writer-overlap", {
+        managed_writer_count: peerOutput.managed_writers.count,
+        managed_writer_kinds: peerOutput.managed_writers.kinds.slice(0, 8),
+        blocking: true
+      });
+    }
+    if (foreignLockCount > 0) {
+      return peerCheckFailure("peer-lock", {
+        foreign_lock_count: foreignLockCount,
+        blocking: true
+      });
+    }
+    if (recentPeerStashCount > 0) {
+      return peerCheckFailure("recent-peer-stash", {
+        recent_peer_stash_count: recentPeerStashCount,
+        stash_classification: "recent_known_peer_stash",
+        blocking: true
+      });
+    }
+    return peerCheckFailure("peer-blocked", { blocking: true });
+  } catch {
+    return peerCheckFailure("peer-check-failed");
+  }
+}
+function preflightBlocker(vault) {
+  const unmerged = hasUnmergedPaths(vault);
+  if (unmerged.length > 0) {
+    return {
+      reason: "unmerged-paths",
+      operation_id: findReviewRequiredOp(vault),
+      unmerged_paths: unmerged
+    };
+  }
+  if (hasActiveGitSequencer(vault)) {
+    return { reason: "git-operation-in-progress" };
+  }
+  supersedeStaleReviewRequiredJournals(vault, {
+    by: "skillwiki-managed-write-preflight",
+    requireClean: false
+  });
+  const op = findReviewRequiredOp(vault);
+  if (op) return { reason: "review-required", operation_id: op };
+  return null;
+}
+function hasFleetManifest(vault) {
+  return existsSync3(join3(vault, FLEET_REL_PATH));
+}
+function isGitVault(vault) {
+  return Boolean(git(vault, ["rev-parse", "--absolute-git-dir"]));
+}
+async function runManagedWritePreflight(input, deps = DEFAULT_DEPS) {
+  const mutationVault = resolve2(input.vault);
+  let convergenceVault = input.convergenceVault && resolve2(input.convergenceVault) !== mutationVault ? resolve2(input.convergenceVault) : void 0;
+  let convergenceSource = convergenceVault ? "explicit" : "single-path";
+  const mutationBlocker = preflightBlocker(mutationVault);
+  if (mutationBlocker) {
+    return {
+      exitCode: ExitCode.PREFLIGHT_FAILED,
+      result: err("PREFLIGHT_FAILED", {
+        reason: mutationBlocker.reason,
+        operation_id: mutationBlocker.operation_id,
+        unmerged_paths: mutationBlocker.unmerged_paths
+      })
+    };
+  }
+  const fleet = await loadFleetManifestAndHost({
+    vault: mutationVault,
+    hostId: input.hostId,
+    env: input.env,
+    home: input.home,
+    cwd: input.cwd,
+    osHostname: input.osHostname,
+    user: input.user
+  });
+  if (!fleet) {
+    const gitVault2 = isGitVault(mutationVault) ? mutationVault : null;
+    const head = gitVault2 ? git(gitVault2, ["rev-parse", "HEAD"]) || null : null;
+    return {
+      exitCode: ExitCode.OK,
+      result: ok({
+        mode: "standalone",
+        mutation_vault: mutationVault,
+        git_vault: gitVault2,
+        base_oid: head,
+        converged: false,
+        convergence_source: "single-path"
+      })
+    };
+  }
+  if (fleet.identityStatus === "unknown" || fleet.identityStatus === "invalid" || !fleet.hostId) {
+    return {
+      exitCode: ExitCode.PREFLIGHT_FAILED,
+      result: err("PREFLIGHT_FAILED", {
+        reason: "fleet-identity-unresolved",
+        identity_status: fleet.identityStatus,
+        host_id: fleet.hostId
+      })
+    };
+  }
+  const host = fleet.manifest.hosts[fleet.hostId];
+  if (!host) {
+    return {
+      exitCode: ExitCode.PREFLIGHT_FAILED,
+      result: err("PREFLIGHT_FAILED", { reason: "fleet-host-missing", host_id: fleet.hostId })
+    };
+  }
+  const writesGithub = host.writes_to.includes("github");
+  if (!writesGithub) {
+    return {
+      exitCode: ExitCode.OK,
+      result: ok({
+        mode: "immutable-record",
+        host_id: fleet.hostId,
+        mutation_vault: mutationVault,
+        git_vault: null,
+        base_oid: null,
+        converged: false,
+        ...convergenceVault ? { convergence_vault: convergenceVault } : {},
+        convergence_source: convergenceSource
+      })
+    };
+  }
+  if (!convergenceVault && host.role === "snapshotter" && host.protected === true) {
+    const home = input.home ?? input.env?.HOME ?? process.env.HOME ?? "";
+    const configured = (deps.resolveConfiguredSnapshotWorktree ?? resolveConfiguredSnapshotWorktree)(home);
+    if (!configured) {
+      return {
+        exitCode: ExitCode.PREFLIGHT_FAILED,
+        result: err("PREFLIGHT_FAILED", {
+          reason: "convergence-vault-not-configured",
+          host_id: fleet.hostId,
+          mutation_vault: mutationVault
+        })
+      };
+    }
+    convergenceVault = resolve2(configured);
+    convergenceSource = "configured";
+    if (convergenceVault === mutationVault) {
+      return {
+        exitCode: ExitCode.PREFLIGHT_FAILED,
+        result: err("PREFLIGHT_FAILED", {
+          reason: "convergence-vault-not-distinct",
+          host_id: fleet.hostId,
+          mutation_vault: mutationVault,
+          convergence_vault: convergenceVault
+        })
+      };
+    }
+  }
+  const gitVault = convergenceVault ?? mutationVault;
+  if (convergenceVault) {
+    if (!isGitVault(convergenceVault)) {
+      return {
+        exitCode: ExitCode.PREFLIGHT_FAILED,
+        result: err("PREFLIGHT_FAILED", {
+          reason: "convergence-vault-not-git",
+          convergence_vault: convergenceVault
+        })
+      };
+    }
+    const convergenceHasFleet = hasFleetManifest(convergenceVault);
+    if (convergenceSource === "configured" && !convergenceHasFleet) {
+      return {
+        exitCode: ExitCode.PREFLIGHT_FAILED,
+        result: err("PREFLIGHT_FAILED", {
+          reason: "convergence-vault-fleet-missing",
+          host_id: fleet.hostId,
+          convergence_vault: convergenceVault
+        })
+      };
+    }
+    const gitBlocker = preflightBlocker(convergenceVault);
+    if (gitBlocker) {
+      return {
+        exitCode: ExitCode.PREFLIGHT_FAILED,
+        result: err("PREFLIGHT_FAILED", {
+          reason: gitBlocker.reason,
+          operation_id: gitBlocker.operation_id,
+          unmerged_paths: gitBlocker.unmerged_paths,
+          convergence_vault: convergenceVault
+        })
+      };
+    }
+  }
+  if (convergenceVault && hasFleetManifest(convergenceVault)) {
+    const convergeFleetCtx = await loadFleetManifestAndHost({
+      vault: convergenceVault,
+      hostId: input.hostId ?? fleet.hostId,
+      env: input.env,
+      home: input.home,
+      cwd: input.cwd,
+      osHostname: input.osHostname,
+      user: input.user
+    });
+    if (!convergeFleetCtx || convergeFleetCtx.identityStatus !== "known" || convergeFleetCtx.hostId !== fleet.hostId) {
+      return {
+        exitCode: ExitCode.PREFLIGHT_FAILED,
+        result: err("PREFLIGHT_FAILED", {
+          reason: "convergence-vault-identity-mismatch",
+          host_id: fleet.hostId,
+          convergence_host_id: convergeFleetCtx?.hostId,
+          convergence_identity_status: convergeFleetCtx?.identityStatus,
+          convergence_vault: convergenceVault
+        })
+      };
+    }
+  }
+  const dualPathMeta = convergenceVault ? { convergence_vault: convergenceVault } : {};
+  const converge = await deps.converge({
+    vault: gitVault,
+    lockToken: convergenceVault ? void 0 : input.lockToken,
+    env: input.env,
+    home: input.home
+  });
+  if (!converge.ok) {
+    const exitCode = converge.error === "PREFLIGHT_FAILED" ? ExitCode.PREFLIGHT_FAILED : ExitCode.SYNC_PULL_FAILED;
+    return { exitCode, result: converge };
+  }
+  const baseOid = git(gitVault, ["rev-parse", "HEAD"]);
+  if (!baseOid) {
+    return {
+      exitCode: ExitCode.PREFLIGHT_FAILED,
+      result: err("PREFLIGHT_FAILED", {
+        reason: "missing-head-after-converge",
+        ...dualPathMeta
+      })
+    };
+  }
+  return {
+    exitCode: ExitCode.OK,
+    result: ok({
+      mode: "git-writer",
+      host_id: fleet.hostId,
+      mutation_vault: mutationVault,
+      git_vault: gitVault,
+      base_oid: baseOid,
+      converged: true,
+      helper_path: converge.data.helper_path,
+      ...dualPathMeta,
+      convergence_source: convergenceSource
+    })
+  };
+}
+async function runManagedWriteTransaction(input, deps = DEFAULT_DEPS) {
+  const mutationVault = resolve2(input.vault);
+  const lock = acquireManagedWriteLock(mutationVault, input.command, {
+    gitStateVault: input.convergenceVault ? resolve2(input.convergenceVault) : mutationVault
+  });
+  if (!lock.ok) {
+    return { exitCode: ExitCode.SYNC_LOCK_HELD, result: lock };
+  }
+  const handle = lock.data;
+  try {
+    const preflightInput = {
+      vault: mutationVault,
+      command: input.command,
+      convergenceVault: input.convergenceVault,
+      hostId: input.hostId,
+      lockToken: handle.ownerToken,
+      env: input.env,
+      home: input.home,
+      cwd: input.cwd,
+      osHostname: input.osHostname,
+      user: input.user
+    };
+    const preflight = input.preflight ? await input.preflight(preflightInput) : await runManagedWritePreflight(preflightInput, deps);
+    if (!preflight.result.ok) {
+      return { exitCode: preflight.exitCode, result: preflight.result };
+    }
+    const receipt = preflight.result.data;
+    if (receipt.mutation_vault !== mutationVault) {
+      return {
+        exitCode: ExitCode.PREFLIGHT_FAILED,
+        result: err("PREFLIGHT_FAILED", {
+          reason: "mutation-vault-receipt-mismatch",
+          expected: mutationVault,
+          actual: receipt.mutation_vault
+        })
+      };
+    }
+    if (receipt.mode === "immutable-record" && !input.allowImmutableRecord) {
+      return {
+        exitCode: ExitCode.PREFLIGHT_FAILED,
+        result: err("PREFLIGHT_FAILED", {
+          reason: "immutable-record-not-enabled",
+          message: "Release A rejects immutable-record mode; event mode arrives in Release B",
+          host_id: receipt.host_id
+        })
+      };
+    }
+    const peerGate = runManagedWritePeerGate(mutationVault, deps);
+    if (peerGate) return peerGate;
+    return await input.mutate(receipt);
+  } finally {
+    releaseManagedWriteLock(handle);
+  }
+}
+
+export {
+  VAULT_COMMIT_PATHSPEC,
+  stageVaultContentChanges,
+  runSyncStatus,
+  runSyncPush,
+  runSyncPull,
+  runSyncPeers,
+  runSyncLock,
+  runSyncUnlock,
+  runManagedWritePreflight,
+  runManagedWriteTransaction
+};