skillwiki 0.10.37 → 0.10.40

package/dist/{chunk-WJVG3DD5.js → chunk-NDR2OY4K.js}

@@ -5968,6 +5968,7 @@ export {
   isFailedRunStatus,
   readSatelliteLatestRunFromText,
   evaluateSatelliteRunHealth,
+  detectFuseMount,
   snapshotterHealthChecks,
   runDoctor,
   readCliPackageJson,

package/dist/cli.js

@@ -7,6 +7,7 @@ import {
   GateError,
   SATELLITE_STALE_MS,
   configPath,
+  detectFuseMount,
   evaluateDirtyVolumeGate,
   evaluateSatelliteRunHealth,
   findPlugin,
@@ -38,7 +39,7 @@ import {
   scanConflictMarkerBlocksInText,
   snapshotterHealthChecks,
   upsertIndexEntry
-} from "./chunk-WJVG3DD5.js";
+} from "./chunk-NDR2OY4K.js";
 import {
   normalizeDistTag,
   readCache,
@@ -168,6 +169,7 @@ import {
   ok,
   readPage,
   redactSensitiveContent,
+  resolveReadOnlyVaultRoot,
   scanSensitiveContent,
   scanVault,
   splitFrontmatter
@@ -4471,7 +4473,8 @@ import { mkdir as mkdir8, readFile as readFile11, writeFile as writeFile7 } from
 import { join as join24, relative, sep } from "path";
 var MAX_WORDS = 900;
 async function runSessionBrief(input) {
-  const scan = await scanVault(input.vault);
+  const { root: scanRoot } = resolveReadOnlyVaultRoot(input.vault);
+  const scan = await scanVault(scanRoot);
   if (!scan.ok) {
     return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
   }
@@ -4497,7 +4500,7 @@ async function runSessionBrief(input) {
       loadSatelliteHealth(input.vault),
       loadSessionPins(input.vault, project),
       project ? loadMemoryTopics(input.vault, project) : Promise.resolve([]),
-      loadPendingSources(input.vault, today)
+      loadPendingSources(scanRoot, today)
     ]);
     const healthWarnings = [
       ...baseHealthWarnings,
@@ -8404,11 +8407,23 @@ async function runBackupRestore(input) {
 import { existsSync as existsSync10, statSync as statSync4 } from "fs";
 import { readFile as readFile16 } from "fs/promises";
 import { join as join32 } from "path";
+var FUSE_NO_MIRROR_NOTE = "FUSE vault with no read mirror - status scan may be slow";
 async function runStatus(input) {
   if (!existsSync10(input.vault)) {
     return { exitCode: ExitCode.VAULT_PATH_INVALID, result: err("VAULT_PATH_INVALID", { vault: input.vault }) };
   }
-  const scan = await scanVault(input.vault);
+  const { root: scanRoot, mirrored } = resolveReadOnlyVaultRoot(input.vault);
+  let readSource = "live";
+  if (mirrored) {
+    readSource = "mirror";
+  } else if (detectFuseMount(input.vault)) {
+    readSource = "fuse-no-mirror";
+  }
+  if (readSource === "fuse-no-mirror") {
+    process.stderr.write(`warning: ${FUSE_NO_MIRROR_NOTE}
+`);
+  }
+  const scan = await scanVault(scanRoot);
   if (!scan.ok) {
     return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
   }
@@ -8430,7 +8445,7 @@ async function runStatus(input) {
   const compound = scan.data.compound.length;
   let schemaVersion = "v1";
   try {
-    const schemaContent = await readFile16(join32(input.vault, "SCHEMA.md"), "utf8");
+    const schemaContent = await readFile16(join32(scanRoot, "SCHEMA.md"), "utf8");
     const versionMatch = schemaContent.match(/version:\s*["']?([^"'\s\n]+)/i);
     if (versionMatch) schemaVersion = versionMatch[1];
   } catch {
@@ -8467,14 +8482,20 @@ async function runStatus(input) {
   };
   const totalPages = Object.values(pageCounts).reduce((a, b) => a + b, 0);
   const rawTotal = rawArticles + rawTranscripts;
-  const humanHint = [
+  const hintLines = [
     `vault: ${input.vault}`,
     `lang: ${langResult.value}`,
     `total: ${totalPages} pages`,
     `  entities: ${pageCounts.entities}  concepts: ${pageCounts.concepts}  comparisons: ${pageCounts.comparisons}  queries: ${pageCounts.queries}  meta: ${pageCounts.meta}`,
     `  raw: ${rawTotal}  work_items: ${workItems}  compound: ${compound}`,
     `last modified: ${lastModified.slice(0, 10)}`
-  ].join("\n");
+  ];
+  if (readSource === "mirror") {
+    hintLines.push(`read source: mirror (${scanRoot}) - page counts may lag up to 30m`);
+  } else if (readSource === "fuse-no-mirror") {
+    hintLines.push(FUSE_NO_MIRROR_NOTE);
+  }
+  const humanHint = hintLines.join("\n");
   return {
     exitCode: ExitCode.OK,
     result: ok({
@@ -8484,6 +8505,7 @@ async function runStatus(input) {
       page_counts: pageCounts,
       total_pages: totalPages,
       last_modified: lastModified,
+      read_source: readSource,
       humanHint
     })
   };

package/dist/skillwiki-mcp.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   runSkillwikiMcpStdio
-} from "./chunk-WJVG3DD5.js";
+} from "./chunk-NDR2OY4K.js";
 import "./chunk-7I2TPIV5.js";
 import "./chunk-QVO332CT.js";
 import "./chunk-XRBUABGE.js";

package/dist/vault-sync/scripts/wiki-fetch-notify.sh

@@ -32,6 +32,21 @@ HANDOFF_NOTIFY_AFTER_SECONDS="${WIKI_FETCH_HANDOFF_NOTIFY_AFTER_SECONDS:-3600}"
 case "$HANDOFF_NOTIFY_AFTER_SECONDS" in
   ''|*[!0-9]*) HANDOFF_NOTIFY_AFTER_SECONDS=3600 ;;
 esac
+# P2 handoff hard-pause (2026-08-12 design, see projects/llm-wiki/architecture/2026-08-12-wiki-push-fail-dedup-design.md)
+# WIKI_FETCH_HANDOFF_HARD_PAUSE=1 enables the hard pause; default is 0 (opt-in
+# per design Q3) so the legacy reminder-backoff behavior is preserved.
+# WIKI_FETCH_HANDOFF_HARD_PAUSE_CYCLES controls the threshold of consecutive
+# 5-min cycles of the same handoff identity before pausing the fetch job
+# (default 13 cycles — one past the 1h HANDOFF_NOTIFY_AFTER_SECONDS mark at
+# StartInterval=300, so the counter can reach the threshold before the
+# notify resets it; the design's "1-hour hard pause" intent is preserved).
+FETCH_HARD_PAUSE="${WIKI_FETCH_HANDOFF_HARD_PAUSE:-0}"
+FETCH_HARD_PAUSE_CYCLES="${WIKI_FETCH_HANDOFF_HARD_PAUSE_CYCLES:-13}"
+case "$FETCH_HARD_PAUSE_CYCLES" in
+  ''|*[!0-9]*) FETCH_HARD_PAUSE_CYCLES=13 ;;
+esac
+FETCH_HARD_PAUSE_COUNTER_FILE="$STATE_DIR/handoff-cycle-counter"
+FETCH_HARD_PAUSE_MARKER="$STATE_DIR/wiki-fetch.paused"
 # Opt-in: when enabled, a positive delta triggers `git pull --rebase` so the
 # local working tree consumes sg01 Snapshot commits automatically. This
 # replaces the git pull that was previously bundled inside wiki-push.sh's
@@ -43,6 +58,15 @@ LOG_FILE="$(platform_log_dir)/wiki-fetch.log"
 
 mkdir -p "$STATE_DIR" "$(dirname "$LOG_FILE")"
 
+# Terminal-state check: if the pause marker exists from a prior incident,
+# the launchd job is already unloaded. Honor the pause — log once and exit
+# without re-fetching or re-notifying. The user clears this by removing
+# the marker and re-loading the plist (per design Q1, B).
+if [ -f "$FETCH_HARD_PAUSE_MARKER" ]; then
+  log "PAUSED fetch job is paused; marker present at $FETCH_HARD_PAUSE_MARKER — exiting"
+  exit 0
+fi
+
 log() {
   printf '%s %s\n' "$(date -u +%FT%TZ)" "$*" >>"$LOG_FILE"
 }
@@ -50,7 +74,7 @@ log() {
 handle_existing_handoff() {
   local blocker reason op identity previous_identity notified_at now
   blocker="$(vault_sync_op_preflight_blocker "$WIKI_DIR" 2>/dev/null || true)"
-  [ -n "$blocker" ] || { rm -f "$HANDOFF_STATE_FILE" 2>/dev/null || true; return 1; }
+  [ -n "$blocker" ] || { rm -f "$HANDOFF_STATE_FILE" "$FETCH_HARD_PAUSE_COUNTER_FILE" 2>/dev/null || true; return 1; }
 
   reason="${blocker%%	*}"
   op="${blocker#*	}"
@@ -69,8 +93,34 @@ handle_existing_handoff() {
     platform_notify "wiki" "review-required handoff ${op:-none} still blocks sync"
     printf 'identity=%s\nnotified_at=%s\n' "$identity" "$now" > "$HANDOFF_STATE_FILE"
     log "NOTIFY handoff identity=$identity"
+    # P2: a new handoff identity (or a fresh notify) resets the cycle counter.
+    if [ "$FETCH_HARD_PAUSE" = "1" ]; then
+      printf '0\n' > "$FETCH_HARD_PAUSE_COUNTER_FILE" 2>/dev/null || true
+    fi
   else
     log "SKIP PULL handoff identity=$identity reminder-backoff"
+    # P2: increment the cycle counter for this identity. When the counter
+    # reaches FETCH_HARD_PAUSE_CYCLES, write the persistent-handoff log line
+    # and unload the launchd job (with marker-file fallback for non-macOS).
+    if [ "$FETCH_HARD_PAUSE" = "1" ]; then
+      local cycle_count
+      cycle_count=0
+      if [ -f "$FETCH_HARD_PAUSE_COUNTER_FILE" ]; then
+        cycle_count="$(cat "$FETCH_HARD_PAUSE_COUNTER_FILE" 2>/dev/null || echo 0)"
+        case "$cycle_count" in ''|*[!0-9]*) cycle_count=0 ;; esac
+      fi
+      cycle_count=$((cycle_count + 1))
+      printf '%s\n' "$cycle_count" > "$FETCH_HARD_PAUSE_COUNTER_FILE" 2>/dev/null || true
+      if [ "$cycle_count" -ge "$FETCH_HARD_PAUSE_CYCLES" ]; then
+        log "handoff persistent — pausing fetch (identity=$identity cycles=$cycle_count threshold=$FETCH_HARD_PAUSE_CYCLES)"
+        printf 'paused_at=%s\nidentity=%s\ncycles=%s\nthreshold=%s\nreason=handoff-persistent-past-threshold\n' \
+          "$(date -u +%FT%TZ)" "$identity" "$cycle_count" "$FETCH_HARD_PAUSE_CYCLES" \
+          > "$FETCH_HARD_PAUSE_MARKER" 2>/dev/null || true
+        if [ "$(platform_scheduler)" = "launchd" ]; then
+          launchctl unload "$HOME/Library/LaunchAgents/com.karlchow.wiki-fetch.plist" 2>/dev/null || true
+        fi
+      fi
+    fi
   fi
   return 0
 }

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

@@ -37,20 +37,122 @@ LOCK_FILE="$(platform_cache_dir)/wiki-push.lock"
 LOG_FILE="$(platform_log_dir)/wiki-push.log"
 LOG_MAX_SIZE=1048576  # 1 MB
 LOG_KEEP=5
+# P1 conflict-marker dedup (2026-08-12 design, see projects/llm-wiki/architecture/2026-08-12-wiki-push-fail-dedup-design.md)
+# WIKI_PUSH_FAIL_DEDUP_DISABLE=1 disables the dedup entirely (rollback to legacy behavior).
+# WIKI_PUSH_FAIL_DEDUP_COOLDOWN_SECONDS controls the per-incident cooldown window (default 900s = 15min).
+PUSH_DEDUP_DISABLE="${WIKI_PUSH_FAIL_DEDUP_DISABLE:-0}"
+PUSH_DEDUP_COOLDOWN_SECONDS="${WIKI_PUSH_FAIL_DEDUP_COOLDOWN_SECONDS:-900}"
+PUSH_DEDUP_STATE_FILE="$(platform_cache_dir)/wiki-push-fail-dedup.state"
+PUSH_DEDUP_PAUSE_MARKER="$(platform_cache_dir)/wiki-push.paused"
 
 mkdir -p "$(dirname "$LOCK_FILE")" "$(dirname "$LOG_FILE")"
 
 log() { printf '%s %s\n' "$(date -u +%FT%TZ)" "$*" >>"$LOG_FILE"; }
 
+# Terminal-state check: if the pause marker exists from a prior incident,
+# the launchd job is already unloaded. Honor the pause — log once and exit
+# without re-scanning or re-attempting the push. The user clears this by
+# removing the marker and re-loading the plist (per design Q1, B).
+if [ "$PUSH_DEDUP_DISABLE" != "1" ] && [ -f "$PUSH_DEDUP_PAUSE_MARKER" ]; then
+    log "PAUSED push job is paused; marker present at $PUSH_DEDUP_PAUSE_MARKER — exiting"
+    exit 0
+fi
+
+# P1 dedup state check: read the dedup state file's mtime and compare against
+# the cooldown window. Echoes one of: "disabled" (dedup turned off, caller
+# must not touch state), "first" (no prior incident, standard guard should
+# run), "cooldown" (within window, suppress duplicate FAIL line + skip the
+# new FAIL log), "expired" (past window, escalate to pause).
+push_dedup_cooldown_check() {
+    if [ "$PUSH_DEDUP_DISABLE" = "1" ]; then
+        printf '%s\n' "disabled"
+        return 0
+    fi
+    if [ ! -f "$PUSH_DEDUP_STATE_FILE" ]; then
+        printf '%s\n' "first"
+        return 0
+    fi
+    local state_ctime now elapsed
+    state_ctime="$(platform_stat_ctime "$PUSH_DEDUP_STATE_FILE" 2>/dev/null || echo 0)"
+    now="$(date +%s)"
+    elapsed=$((now - state_ctime))
+    if [ "$elapsed" -lt "$PUSH_DEDUP_COOLDOWN_SECONDS" ]; then
+        printf '%s\n' "cooldown"
+        return 0
+    fi
+    printf '%s\n' "expired"
+    return 0
+}
+
+# Touch (or create) the dedup state file so subsequent invocations see the
+# incident's first-detection timestamp. Uses a single `touch` to avoid races
+# with parallel invocations (which are guarded by the lockfile above).
+push_dedup_touch_state() {
+    touch "$PUSH_DEDUP_STATE_FILE" 2>/dev/null || true
+}
+
+# Clear the dedup state file (used on a successful push, when markers are gone).
+push_dedup_clear_state() {
+    rm -f "$PUSH_DEDUP_STATE_FILE" 2>/dev/null || true
+}
+
+# Write a pause marker file as a portable stand-in for `launchctl unload`.
+# On a real macOS host, the launchd plist is the actual unpause target; this
+# marker is a portable test surface and a cross-platform indicator.
+push_dedup_write_pause_marker() {
+    local now
+    now="$(date -u +%FT%TZ)"
+    printf 'paused_at=%s reason=conflict-markers-persist-past-cooldown cooldown_seconds=%s\n' \
+        "$now" "$PUSH_DEDUP_COOLDOWN_SECONDS" > "$PUSH_DEDUP_PAUSE_MARKER" 2>/dev/null || true
+    if [ "$(platform_scheduler)" = "launchd" ]; then
+        # Best-effort launchd unload. Failure is non-fatal — the marker file is
+        # the canonical pause signal. This matches the design doc's rollback
+        # semantics: the marker is the test surface, launchctl is the production
+        # surface, both can be present.
+        launchctl unload "$HOME/Library/LaunchAgents/com.karlchow.wiki-push.plist" 2>/dev/null || true
+    fi
+}
+
 conflict_marker_guard() {
     local findings
     findings="$(mktemp)" || { log "FAIL could not create conflict-marker scan temp file"; return 1; }
     if ! vault_sync_scan_conflict_markers "$WIKI_DIR" "$findings"; then
-        log "FAIL conflict marker blocks present; refusing S3 push"
-        vault_sync_log_conflict_marker_findings "$findings" "$LOG_FILE"
+        local dedup_state
+        dedup_state="$(push_dedup_cooldown_check)"
+        case "$dedup_state" in
+            first)
+                # First detection: log the FAIL line, mark the state file so
+                # subsequent invocations within the cooldown window are silent.
+                log "FAIL conflict marker blocks present; refusing S3 push"
+                vault_sync_log_conflict_marker_findings "$findings" "$LOG_FILE"
+                push_dedup_touch_state
+                ;;
+            expired)
+                # Past the cooldown: log the FAIL line + escalation notice,
+                # write the pause marker, refresh the state file so the next
+                # cooldown starts from this moment.
+                log "FAIL conflict marker blocks present; refusing S3 push"
+                vault_sync_log_conflict_marker_findings "$findings" "$LOG_FILE"
+                log "cooldown expired — pausing push (markers persist past ${PUSH_DEDUP_COOLDOWN_SECONDS}s)"
+                push_dedup_write_pause_marker
+                push_dedup_touch_state
+                ;;
+            cooldown)
+                # Within cooldown: suppress the duplicate FAIL line. The first
+                # FAIL line in the incident (state=first) is already logged;
+                # subsequent invocations within the cooldown are silent.
+                ;;
+            disabled)
+                # Dedup is off: log the FAIL line (legacy behavior), do not
+                # touch any state file or pause marker.
+                log "FAIL conflict marker blocks present; refusing S3 push"
+                vault_sync_log_conflict_marker_findings "$findings" "$LOG_FILE"
+                ;;
+        esac
         rm -f "$findings"
         return 1
     fi
+    push_dedup_clear_state
     rm -f "$findings"
     return 0
 }
@@ -359,6 +461,11 @@ if [ "$RC" -eq 0 ]; then
     if ! remote_prune_tombstoned_paths; then
         log "FAIL tombstone prune failed after rclone copy"
     fi
+    # P1: a successful push proves markers are gone. conflict_marker_guard
+    # already cleared the dedup state on the scan-success path. The pause
+    # marker rm is defensive: it covers the case where the user manually
+    # unpaused the launchd job without removing the marker file.
+    rm -f "$PUSH_DEDUP_PAUSE_MARKER" 2>/dev/null || true
 fi
 
 exit 0

package/package.json

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

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

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.10.37",
+  "version": "0.10.40",
   "skills": "./",
   "description": "Project-aware Karpathy-style knowledge base for Claude Code: 19 prompt-only skills (wiki-*, proj-*, using-skillwiki) backed by the deterministic `skillwiki` CLI.",
   "author": {

package/skills/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.10.37",
+  "version": "0.10.40",
   "description": "Project-aware Karpathy-style knowledge base for Codex with 19 prompt-only skills backed by the deterministic skillwiki CLI.",
   "author": {
     "name": "karlorz",

package/skills/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillwiki/skills",
-  "version": "0.10.37",
+  "version": "0.10.40",
   "private": true,
   "files": [
     "wiki-*",