@windyroad/itil 0.47.6 → 0.47.7

package/.claude-plugin/plugin.json

@@ -497,5 +497,5 @@
     }
   },
   "name": "wr-itil",
-  "version": "0.47.6"
+  "version": "0.47.7"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/itil",
-  "version": "0.47.6",
+  "version": "0.47.7",
   "description": "ITIL-aligned IT service management for Claude Code (problem, and future incident/change skills)",
   "bin": {
     "windyroad-itil": "./bin/install.mjs"

package/skills/work-problems/SKILL.md

@@ -368,9 +368,26 @@ claude -p \
 ITER_PID=$!
 
 SIGTERM_SENT=0
+LAST_POLL_EPOCH=$DISPATCH_START_EPOCH
+SUSPEND_OFFSET_S=0
+EXPECTED_POLL_DELTA_S=60   # matches `sleep 60` cadence below
+SUSPEND_JITTER_S=120       # tolerance above expected before treating gap as suspend (P307)
 while kill -0 "$ITER_PID" 2>/dev/null; do
-  sleep 60
+  sleep "$EXPECTED_POLL_DELTA_S"
   NOW=$(date +%s)
+  # P307 machine-sleep false-kill: when the host suspends between polls,
+  # wall-clock advances while the iter subprocess is itself suspended (no
+  # actual idle work). Detect the wall-clock jump and accumulate it into
+  # SUSPEND_OFFSET_S so IDLE_SECONDS (computed against NOW - SUSPEND_OFFSET_S
+  # below) reads active-elapsed rather than wall-clock-elapsed. Without
+  # this, laptop suspend falsely kills a completing iter (2026-05-26 iter 1
+  # evidence: idle jumped 481s -> 1016s -> 5544s across suspend gaps;
+  # SIGTERM fired at 5544s > 3600s, lost the iter's commit + cost metadata).
+  ACTUAL_POLL_DELTA=$(( NOW - LAST_POLL_EPOCH ))
+  if (( ACTUAL_POLL_DELTA > EXPECTED_POLL_DELTA_S + SUSPEND_JITTER_S )); then
+    SUSPEND_OFFSET_S=$(( SUSPEND_OFFSET_S + ACTUAL_POLL_DELTA - EXPECTED_POLL_DELTA_S ))
+  fi
+  LAST_POLL_EPOCH=$NOW
   LAST_COMMIT_EPOCH=$(git log -1 --format=%at HEAD 2>/dev/null || echo "$DISPATCH_START_EPOCH")
   # LAST_ACTIVITY_MARK = max(DISPATCH_START_EPOCH, last commit timestamp).
   # The dispatch-start floor handles skip-iterations that produce no commit:
@@ -381,7 +398,7 @@ while kill -0 "$ITER_PID" 2>/dev/null; do
   else
     LAST_ACTIVITY_MARK=$DISPATCH_START_EPOCH
   fi
-  IDLE_SECONDS=$(( NOW - LAST_ACTIVITY_MARK ))
+  IDLE_SECONDS=$(( NOW - SUSPEND_OFFSET_S - LAST_ACTIVITY_MARK ))
   if (( IDLE_SECONDS > IDLE_TIMEOUT_S )) && (( SIGTERM_SENT == 0 )); then
     kill -TERM "$ITER_PID" 2>/dev/null || true
     SIGTERM_SENT=1
@@ -409,6 +426,8 @@ rm -f "$ITER_JSON"
 
 **LAST_ACTIVITY_MARK signal trade-off.** The mark is `max(DISPATCH_START_EPOCH, last commit timestamp)`. The dispatch-start floor is intentional: skip-iterations that produce no commit (Step 4 routes a ticket to `action: skipped`) are bounded by `IDLE_TIMEOUT_S` since dispatch start, not by an arbitrarily-stale prior-commit timestamp. This protects against false-positive SIGTERM at iter T=0 when the most recent commit happens to be hours old. The trade-off is the inverse: a skip-iter that runs for `IDLE_TIMEOUT_S` (60 min default) will SIGTERM even though it never had a chance to commit. The 60-min default is well past the typical skip-iter wall-clock (a normal skip completes in seconds), so the trade-off rarely fires in practice; adopters who run unusually long skip-evaluation iters (e.g. deep architect-design probes) should raise `WORK_PROBLEMS_IDLE_TIMEOUT_S` accordingly. Alternative signals considered and rejected: `stat -f%m "$ITER_JSON"` (binary — file mtime only changes on subprocess exit, useless during the idle gap); subprocess RSS-change tracking (noisy; spikes during Agent-tool expansions confound the signal). The git-log signal is the cheapest reliable progress indicator the orchestrator already has.
 
+**Machine-sleep false-kill — suspend-detect heuristic (P307).** The IDLE_SECONDS computation above subtracts `SUSPEND_OFFSET_S` from wall-clock `NOW` so the orchestrator measures *active-elapsed* time rather than raw wall-clock between LAST_ACTIVITY_MARK and now. The offset accumulates whenever a poll observes `ACTUAL_POLL_DELTA > EXPECTED_POLL_DELTA_S + SUSPEND_JITTER_S` (default `60 + 120 = 180s`) — i.e., the gap between consecutive `sleep 60` polls vastly exceeds the cadence the loop scheduled. The driver is the 2026-05-26 iter 1 evidence: the iter's host suspended (lid-close mid-loop) and the next poll observed an idle of 5544s; the wall-clock-only computation tripped SIGTERM at 5544s > 3600s, exit 143 + 0-byte JSON (the P147 stuck-before-emit metadata-loss class), losing a commit + cost metadata for an iter whose semantic work had completed. The suspend-detect heuristic converts that wall-clock-elapsed measure to "active-elapsed approximate" without needing monotonic clocks (which bash does not natively expose anyway). Alternatives considered and rejected: (a) monotonic / active-time clocks (POSIX `CLOCK_MONOTONIC` is not surfaced by `date` or `$EPOCHSECONDS`; would require a C helper or a Python-shim subprocess per poll); (b) iter-side heartbeat file the poll loop reads instead of wall-clock (works but adds an iter-side write contract; suspend-detect is purely orchestrator-side, no iter-prompt changes). The jitter buffer (`SUSPEND_JITTER_S=120`) is the load-bearing safety margin: it tolerates slow-hook / GC / brief-load-spike jitter (up to 180s total inter-poll delay) without falsely shifting; only genuine suspend / system-clock jumps cross the threshold. Adopters with unusually noisy hosts can raise `SUSPEND_JITTER_S` per environment; lowering it risks counting brief stalls as suspend. The heuristic is asymmetric — it can absorb a 5 min host hang into the offset and treat it as suspend, but the cost is at worst that one iter runs an extra 5 min before SIGTERM (cheaper than losing the iter's commit + metadata to a false-kill).
+
 **Iteration prompt body (self-contained — the subprocess has no prior conversation context):**
 
 1. **Context**: this is one iteration of the AFK work-problems loop. The user is AFK. The orchestrator selected `P<NNN> (<title>)` as the highest-WSJF actionable ticket.

package/skills/work-problems/test/work-problems-step-5-idle-timeout-sigterm.bats

@@ -298,3 +298,124 @@ FAKE_EOF
   run grep -nE "P147" "$SKILL_FILE"
   [ "$status" -eq 0 ]
 }
+
+# ---------------------------------------------------------------------------
+# P307 machine-sleep false-kill subclass: P121's IDLE_SECONDS = NOW -
+# LAST_ACTIVITY_MARK computation is wall-clock time. When the host machine
+# suspends/sleeps between the 60s polls, wall-clock advances while the iter
+# subprocess is itself suspended (no actual idle work). On resume, IDLE_SECONDS
+# jumps past the threshold and SIGTERM fires on a subprocess that was
+# genuinely making progress, not stuck. The 2026-05-26 evidence: poll log
+# idle jumped non-linearly 481s -> 1016s -> 5544s across suspend gaps,
+# SIGTERM at idle=5544s > 3600s threshold, exit 143 + 0-byte JSON (the
+# P147 stuck-before-emit metadata-loss class).
+#
+# Fix: detect large wall-clock jumps between consecutive polls (>> 60s
+# expected) as suspend events and shift LAST_ACTIVITY_MARK forward by the
+# gap-minus-expected so IDLE_SECONDS approximates active-elapsed rather
+# than wall-clock-elapsed. Pure-bash heuristic — no monotonic-clock
+# dependency.
+#
+# @problem P307
+
+# Pure-bash helper mirroring SKILL.md Step 5 suspend-detect math. Tests
+# below pin the algorithm against parameter combinations exercising
+# (a) normal poll cadence (no shift), (b) within-jitter delay (no shift),
+# (c) detected suspend (shift forward by actual-minus-expected),
+# (d) reproduction of the 2026-05-26 5544s evidence (large shift absorbs
+# the gap). The shape returned is the EFFECTIVE LAST_ACTIVITY_MARK such
+# that IDLE_SECONDS = NOW - effective_mark yields active-elapsed.
+compute_effective_mark() {
+  local prev_mark="$1"
+  local prev_poll="$2"
+  local now="$3"
+  local expected_delta="${4:-60}"
+  local jitter="${5:-120}"
+
+  local actual_delta=$(( now - prev_poll ))
+  local threshold=$(( expected_delta + jitter ))
+  if (( actual_delta > threshold )); then
+    printf '%d\n' $(( prev_mark + actual_delta - expected_delta ))
+  else
+    printf '%d\n' "$prev_mark"
+  fi
+}
+
+@test "P307: normal poll cadence (60s actual delta) does NOT shift LAST_ACTIVITY_MARK" {
+  # 60s between polls is the expected `sleep 60` cadence; no suspend; mark
+  # unchanged. Guards against an over-eager heuristic that would shift on
+  # every normal poll.
+  run compute_effective_mark 1000 0 60 60 120
+  [ "$status" -eq 0 ]
+  [ "$output" = "1000" ]
+}
+
+@test "P307: within-jitter delay (90s actual delta) does NOT shift LAST_ACTIVITY_MARK" {
+  # 90s between polls is mild jitter (slow hook, GC pause, brief load
+  # spike); below the 60+120=180s suspend threshold; mark unchanged.
+  # Bounded noise must not trigger a shift.
+  run compute_effective_mark 1000 0 90 60 120
+  [ "$status" -eq 0 ]
+  [ "$output" = "1000" ]
+}
+
+@test "P307: at-threshold delay (180s actual delta) does NOT shift LAST_ACTIVITY_MARK" {
+  # Exactly at expected+jitter is the boundary; strict-greater-than test
+  # means no shift at the boundary. Adopters tuning the jitter window
+  # know 180s == EXPECTED_POLL_DELTA_S + SUSPEND_JITTER_S is the inclusive
+  # ceiling of the no-shift band.
+  run compute_effective_mark 1000 0 180 60 120
+  [ "$status" -eq 0 ]
+  [ "$output" = "1000" ]
+}
+
+@test "P307: detected suspend (300s actual delta) shifts mark forward by actual-minus-expected" {
+  # 300s between polls vastly exceeds the 180s threshold; treat as suspend
+  # event and shift mark forward by 300-60=240s. Effect: IDLE_SECONDS
+  # (NOW - effective_mark) reads 60s instead of 300s, preserving the
+  # subprocess from a wall-clock false-kill.
+  run compute_effective_mark 1000 0 300 60 120
+  [ "$status" -eq 0 ]
+  [ "$output" = "1240" ]
+}
+
+@test "P307: reproduces 2026-05-26 iter 1 evidence (5544s suspend gap shifts mark to absorb)" {
+  # Concrete reproduction of the production observation: poll saw idle
+  # jump to 5544s after a multi-hour laptop suspend. Without suspend-detect,
+  # SIGTERM fires at 5544s > 3600s threshold. With suspend-detect, mark
+  # shifts forward by 5544-60=5484s; IDLE_SECONDS = 5544 - 5484 = 60s,
+  # below threshold; iter survives.
+  run compute_effective_mark 0 0 5544 60 120
+  [ "$status" -eq 0 ]
+  [ "$output" = "5484" ]
+}
+
+@test "P307: SKILL.md Step 5 documents the suspend-detect heuristic" {
+  # Prose must name the heuristic so adopters reading the SKILL.md know
+  # how the poll loop survives machine-sleep without inventing one.
+  # Accept any of: "suspend-detect", "wall-clock jump", "machine sleep",
+  # "machine-sleep", or the constants EXPECTED_POLL_DELTA_S /
+  # SUSPEND_JITTER_S / SUSPEND_OFFSET_S that name the construct.
+  run grep -niE "suspend.?detect|wall.?clock jump|machine.?sleep|EXPECTED_POLL_DELTA_S|SUSPEND_JITTER_S|SUSPEND_OFFSET_S" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "P307: SKILL.md Step 5 cites P307 (machine-sleep false-kill driver)" {
+  run grep -nE "P307" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "P307: SKILL.md Step 5 trade-off paragraph names suspend-detect alongside skip-iter trade-off" {
+  # The LAST_ACTIVITY_MARK signal trade-off paragraph (existing at L410)
+  # enumerates alternatives considered and rejected (mtime, RSS). The
+  # suspend-detect addition belongs in the same locus per architect
+  # review — keeps the rationale chain (P121 -> P147 -> trade-off ->
+  # P307 suspend-detect) reading linearly rather than fragmenting into
+  # a separate section. Assert the trade-off paragraph names both
+  # SUSPEND_OFFSET_S (the accumulator) AND the EXPECTED_POLL_DELTA_S +
+  # SUSPEND_JITTER_S threshold so the rationale chain is complete.
+  run grep -nE "LAST_ACTIVITY_MARK signal trade-off" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  run grep -niE "SUSPEND_OFFSET_S|suspend.?offset" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}