skillwiki 0.10.39 → 0.10.40

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.39",
+  "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.39",
+  "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.39",
+  "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.39",
+  "version": "0.10.40",
   "private": true,
   "files": [
     "wiki-*",