devlog-tracker 0.22.0

package/cursor/hooks/on-submit-prompt.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+set -uo pipefail
+_src="${BASH_SOURCE[0]}"
+SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
+PLUGIN_SCRIPTS="$(cd "$SCRIPT_DIR/../../hooks/scripts" && pwd)"
+INPUT="$(cat 2>/dev/null || true)"
+ROOT="$(printf '%s' "$INPUT" | bash "$SCRIPT_DIR/project-dir.sh")"
+export CLAUDE_PROJECT_DIR="$ROOT"
+PROMPT=""
+SESSION_ID=""
+if command -v jq >/dev/null 2>&1; then
+  PROMPT="$(printf '%s' "$INPUT" | jq -r '.prompt // empty' 2>/dev/null || true)"
+  SESSION_ID="$(printf '%s' "$INPUT" | jq -r '.session_id // empty' 2>/dev/null || true)"
+  PAYLOAD="$(jq -n --arg prompt "$PROMPT" --arg session_id "$SESSION_ID" '{prompt:$prompt,session_id:$session_id}')"
+else
+  PROMPT="$(printf '%s' "$INPUT" | grep -o '"prompt"[[:space:]]*:[[:space:]]*"[^"]*"' 2>/dev/null | head -1 | sed 's/.*"prompt"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/' || true)"
+  SESSION_ID="$(printf '%s' "$INPUT" | grep -o '"session_id"[[:space:]]*:[[:space:]]*"[^"]*"' 2>/dev/null | head -1 | sed 's/.*"session_id"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/' || true)"
+  # Escape only what we embed; prompts with quotes remain a known no-jq limitation.
+  PAYLOAD="$(printf '{"prompt":"%s","session_id":"%s"}' "$PROMPT" "$SESSION_ID")"
+fi
+NOTE="$(printf '%s' "$PAYLOAD" | bash "$PLUGIN_SCRIPTS/round-start.sh" 2>/dev/null || true)"
+if command -v jq >/dev/null 2>&1; then
+  jq -cn --arg n "$NOTE" '{continue:true, additional_context:$n}'
+else
+  esc="$(printf '%s' "$NOTE" | sed 's/\\/\\\\/g; s/"/\\"/g; s/	/\\t/g' | awk '{printf "%s\\n", $0}' | sed '$ s/\\n$//')"
+  printf '{"continue":true,"additional_context":"%s"}\n' "$esc"
+fi
+exit 0

package/cursor/hooks/on-tool-failure.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+set -uo pipefail
+_src="${BASH_SOURCE[0]}"
+SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
+PLUGIN_SCRIPTS="$(cd "$SCRIPT_DIR/../../hooks/scripts" && pwd)"
+INPUT="$(cat 2>/dev/null || true)"
+ROOT="$(printf '%s' "$INPUT" | bash "$SCRIPT_DIR/project-dir.sh")"
+export CLAUDE_PROJECT_DIR="$ROOT"
+if command -v jq >/dev/null 2>&1; then
+  IS_INTERRUPT="$(printf '%s' "$INPUT" | jq -r '.is_interrupt // .tool_result.is_interrupt // false' 2>/dev/null || echo false)"
+else
+  case "$INPUT" in *'"is_interrupt":true'*|*'"is_interrupt": true'*) IS_INTERRUPT=true ;; *) IS_INTERRUPT=false ;; esac
+fi
+printf '{"is_interrupt":%s}' "$IS_INTERRUPT" | bash "$PLUGIN_SCRIPTS/on-tool-failure.sh" >/dev/null 2>&1 || true
+echo '{}'
+exit 0

package/cursor/hooks/project-dir.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -uo pipefail
+INPUT="$(cat 2>/dev/null || true)"
+ROOT=""
+if command -v jq >/dev/null 2>&1; then
+  ROOT="$(printf '%s' "$INPUT" | jq -r '.workspace_roots[0] // empty' 2>/dev/null || true)"
+else
+  ROOT="$(printf '%s' "$INPUT" | grep -o '"workspace_roots"[[:space:]]*:[[:space:]]*\["[^"]*"' 2>/dev/null | head -1 | sed 's/.*"workspace_roots"[[:space:]]*:[[:space:]]*\["\([^"]*\)".*/\1/' || true)"
+fi
+printf '%s\n' "${ROOT:-.}"

package/cursor/hooks/test-adapters.sh

@@ -0,0 +1,201 @@
+#!/usr/bin/env bash
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+FAIL=0
+assert_single_json() {
+  local desc="$1" json="$2" count
+  if command -v jq >/dev/null 2>&1; then
+    count="$(printf '%s' "$json" | jq -s 'length' 2>/dev/null || echo '')"
+  else
+    # No jq: count top-level {...} closures ourselves, quote/escape-aware so
+    # a brace inside a string value doesn't throw the depth count off.
+    count="$(printf '%s' "$json" | awk '
+      {
+        line = $0
+        for (i = 1; i <= length(line); i++) {
+          c = substr(line, i, 1)
+          if (esc) { esc = 0; continue }
+          if (c == "\\" && in_str) { esc = 1; continue }
+          if (c == "\"") { in_str = !in_str; continue }
+          if (in_str) continue
+          if (c == "{") depth++
+          else if (c == "}") { depth--; if (depth == 0) n_obj++ }
+        }
+      }
+      END { print n_obj + 0 }
+    ' 2>/dev/null || echo '')"
+  fi
+  if [ "$count" = "1" ]; then
+    echo "PASS: $desc"
+  else
+    echo "FAIL: $desc (expected 1 top-level JSON value, got [$count]) [$json]"; FAIL=1
+  fi
+}
+mkdir -p "$TMP/project/.devlog"
+cat > "$TMP/project/.devlog/devlog.md" <<'EOF'
+## Round 1 — now
+
+### Summary
+done
+
+### Handoff
+#### 現況
+done
+
+### Status
+DONE
+EOF
+OUT="$(printf '{"workspace_roots":["%s"]}' "$TMP/project" | bash "$SCRIPT_DIR/on-session-start.sh")"
+case "$OUT" in *'"additional_context"'*"Round 1"*) echo "PASS: sessionStart context" ;; *) echo "FAIL: sessionStart [$OUT]"; FAIL=1 ;; esac
+assert_single_json "sessionStart single json" "$OUT"
+EMPTY="$(printf '{}' | bash "$SCRIPT_DIR/on-session-start.sh")"
+case "$EMPTY" in \{*\}) echo "PASS: empty workspace valid json" ;; *) echo "FAIL: empty json [$EMPTY]"; FAIL=1 ;; esac
+assert_single_json "empty workspace single json" "$EMPTY"
+
+# submit prompt
+SUBMIT="$TMP/submit"
+mkdir -p "$SUBMIT/.devlog"
+touch "$SUBMIT/.devlog/.enabled"
+OUT="$(printf '{"workspace_roots":["%s"],"prompt":"hello","session_id":"cursor-1"}' "$SUBMIT" | bash "$SCRIPT_DIR/on-submit-prompt.sh")"
+case "$OUT" in *'"continue":true'*) echo "PASS: submit continues" ;; *) echo "FAIL: submit [$OUT]"; FAIL=1 ;; esac
+assert_single_json "submit single json" "$OUT"
+grep -q 'hello' "$SUBMIT/.devlog/.round-current.md" && echo "PASS: submit writes round" || { echo "FAIL: submit round"; FAIL=1; }
+ROUNDS="$(grep -c '^## Round ' "$SUBMIT/.devlog/.round-current.md" || true)"
+if [ "$ROUNDS" -eq 1 ]; then echo "PASS: submit writes one round"; else echo "FAIL: submit round count [$ROUNDS]"; FAIL=1; fi
+
+# submit prompt with stale 工作區 forwards additional_context
+MIS="$TMP/mismatch-submit"
+mkdir -p "$MIS/.devlog"
+touch "$MIS/.devlog/.enabled"
+git -C "$MIS" init -q -b main
+git -C "$MIS" config user.email test@example.com
+git -C "$MIS" config user.name test
+echo hello > "$MIS/a.txt"
+git -C "$MIS" add a.txt
+git -C "$MIS" commit -q -m init
+cat > "$MIS/.devlog/devlog.md" <<'EOF'
+## Round 1 — 2026-09-11T00:00:00+08:00
+
+### Handoff
+#### 工作區
+main @ deadbeef，工作樹乾淨
+#### 現況
+going
+#### 下一步
+do x
+
+### Status
+IN_PROGRESS
+EOF
+OUT="$(printf '{"workspace_roots":["%s"],"prompt":"keep going","session_id":"cursor-mismatch"}' "$MIS" | bash "$SCRIPT_DIR/on-submit-prompt.sh")"
+case "$OUT" in *'"continue":true'*) echo "PASS: mismatch submit continues" ;; *) echo "FAIL: mismatch submit [$OUT]"; FAIL=1 ;; esac
+case "$OUT" in *'"additional_context"'*工作區*) echo "PASS: mismatch submit additional_context" ;; *) echo "FAIL: mismatch context [$OUT]"; FAIL=1 ;; esac
+assert_single_json "mismatch submit single json" "$OUT"
+[ -f "$MIS/.devlog/.workspace-mismatch" ] && echo "PASS: mismatch submit writes marker" || { echo "FAIL: no cursor marker"; FAIL=1; }
+
+# preToolUse allowlists writes to the devlog and denies expired other tools
+NOW="$(date +%s)"
+OLD=$((NOW - 1000))
+SUM="$(cksum < "$SUBMIT/.devlog/.round-current.md" | tr -d '\n')"
+printf '{"last_change_epoch": %s, "last_seen_cksum": "%s", "max_silent_seconds": 900, "session_id": "cursor-1"}\n' "$OLD" "$SUM" > "$SUBMIT/.devlog/.segment-state"
+OUT="$(printf '{"workspace_roots":["%s"],"tool_name":"Write","tool_input":{"file_path":"%s/.devlog/.round-current.md"},"session_id":"cursor-1"}' "$SUBMIT" "$SUBMIT" | bash "$SCRIPT_DIR/on-pre-tool.sh")"
+case "$OUT" in *'"permission":"deny"'*) echo "FAIL: devlog write denied"; FAIL=1 ;; *) echo "PASS: devlog write allowed" ;; esac
+assert_single_json "preTool write single json" "$OUT"
+OUT="$(printf '{"workspace_roots":["%s"],"tool_name":"StrReplace","tool_input":{"file_path":"%s/.devlog/.round-current.md"},"session_id":"cursor-1"}' "$SUBMIT" "$SUBMIT" | bash "$SCRIPT_DIR/on-pre-tool.sh")"
+case "$OUT" in *'"permission":"deny"'*) echo "FAIL: StrReplace devlog denied"; FAIL=1 ;; *) echo "PASS: StrReplace devlog allowed" ;; esac
+assert_single_json "preTool StrReplace single json" "$OUT"
+OUT="$(printf '{"workspace_roots":["%s"],"tool_name":"Bash","tool_input":{},"session_id":"cursor-1"}' "$SUBMIT" | bash "$SCRIPT_DIR/on-pre-tool.sh")"
+case "$OUT" in *permission*deny*"### 段落"*) echo "PASS: expired tool denied" ;; *) echo "FAIL: preTool [$OUT]"; FAIL=1 ;; esac
+assert_single_json "preTool deny single json" "$OUT"
+
+# stop: incomplete round asks Cursor for one follow-up; loop_count prevents retry
+OUT="$(printf '{"workspace_roots":["%s"],"status":"completed","loop_count":0}' "$SUBMIT" | bash "$SCRIPT_DIR/on-stop.sh")"
+case "$OUT" in *'"followup_message"'*"Summary"*) echo "PASS: stop followup" ;; *) echo "FAIL: stop [$OUT]"; FAIL=1 ;; esac
+assert_single_json "stop followup single json" "$OUT"
+OUT="$(printf '{"workspace_roots":["%s"],"status":"completed","loop_count":1}' "$SUBMIT" | bash "$SCRIPT_DIR/on-stop.sh")"
+case "$OUT" in *followup_message*) echo "FAIL: loop guard followup"; FAIL=1 ;; *) echo "PASS: stop loop guard" ;; esac
+assert_single_json "stop loop guard single json" "$OUT"
+OUT="$(printf '{"workspace_roots":["%s"],"status":"running","loop_count":0}' "$SUBMIT" | bash "$SCRIPT_DIR/on-stop.sh")"
+case "$OUT" in *followup_message*) echo "FAIL: non-completed stop enforced [$OUT]"; FAIL=1 ;; *) echo "PASS: non-completed stop skipped" ;; esac
+assert_single_json "non-completed stop single json" "$OUT"
+
+# aborted stop and session end close the open round
+printf '%s\n' '{"round": 1, "opened_at": "now"}' > "$SUBMIT/.devlog/.round-open"
+OUT="$(printf '{"workspace_roots":["%s"],"status":"aborted"}' "$SUBMIT" | bash "$SCRIPT_DIR/on-stop.sh")"
+grep -q 'INTERRUPTED' "$SUBMIT/.devlog/devlog.md" && echo "PASS: aborted closes round" || { echo "FAIL: aborted"; FAIL=1; }
+assert_single_json "aborted stop single json" "$OUT"
+
+# sessionEnd delegates its reason to the existing close helper
+printf '\n## Round 2 — now\n\n### Status\nIN_PROGRESS\n' > "$SUBMIT/.devlog/.round-current.md"
+printf '%s\n' '{"round": 2, "opened_at": "now"}' > "$SUBMIT/.devlog/.round-open"
+cksum < "$SUBMIT/.devlog/.round-current.md" > "$SUBMIT/.devlog/.turn-start"
+OUT="$(printf '{"workspace_roots":["%s"],"reason":"windowClosed"}' "$SUBMIT" | bash "$SCRIPT_DIR/on-session-end.sh")"
+grep -q 'SessionEnd:windowClosed' "$SUBMIT/.devlog/devlog.md" && echo "PASS: session end reason" || { echo "FAIL: session end"; FAIL=1; }
+assert_single_json "sessionEnd single json" "$OUT"
+
+# project-dir without jq still reads workspace_roots[0]
+PATH_NO_JQ="$TMP/no-jq-path"
+mkdir -p "$PATH_NO_JQ"
+for bin in bash cat printf grep sed head mktemp rm date cksum awk tr mkdir; do
+  bin_path="$(command -v "$bin" 2>/dev/null || true)"
+  [ -n "$bin_path" ] && ln -sf "$bin_path" "$PATH_NO_JQ/$bin"
+done
+ROOT="$(printf '{"workspace_roots":["%s"]}' "$SUBMIT" | PATH="$PATH_NO_JQ" bash "$SCRIPT_DIR/project-dir.sh")"
+if [ "$ROOT" = "$SUBMIT" ]; then echo "PASS: project-dir without jq"; else echo "FAIL: project-dir without jq [$ROOT]"; FAIL=1; fi
+
+# tool interruption marker
+rm -f "$SUBMIT/.devlog/.interrupted"
+OUT="$(printf '{"workspace_roots":["%s"],"is_interrupt":true}' "$SUBMIT" | bash "$SCRIPT_DIR/on-tool-failure.sh")"
+[ -f "$SUBMIT/.devlog/.interrupted" ] && echo "PASS: tool interruption marked" || { echo "FAIL: interrupt marker"; FAIL=1; }
+assert_single_json "toolFailure single json" "$OUT"
+
+# --- no-jq session_id must reach segment-state via round-start ------------
+NOJQ_HOME="$TMP/nojq_home"
+mkdir -p "$NOJQ_HOME/.devlog" "$TMP/nojq_path"
+touch "$NOJQ_HOME/.devlog/.enabled"
+printf '%s\n' '{"last_change_epoch": 0, "last_seen_cksum": "", "max_silent_seconds": 600, "session_id": ""}' \
+  > "$NOJQ_HOME/.devlog/.segment-state"
+CLEAN_PATH="$TMP/nojq_path"
+# Resolve real binaries (zsh `command -v` may return aliases / builtins).
+for cmd in bash sh cksum date grep sed cat mkdir tr mktemp rm head awk touch \
+  pwd dirname uname ln printf sort cut wc env sleep; do
+  src=""
+  for cand in "/bin/$cmd" "/usr/bin/$cmd"; do
+    if [ -x "$cand" ]; then src="$cand"; break; fi
+  done
+  [ -n "$src" ] && ln -sf "$src" "$CLEAN_PATH/$cmd"
+done
+# Explicitly do NOT link jq.
+OUT="$(printf '{"workspace_roots":["%s"],"prompt":"nojq-hi","session_id":"cursor-nojq"}' "$NOJQ_HOME" \
+  | env PATH="$CLEAN_PATH" bash "$SCRIPT_DIR/on-submit-prompt.sh")"
+case "$OUT" in *'"continue":true'*) echo "PASS: nojq submit continues" ;; *) echo "FAIL: nojq submit [$OUT]"; FAIL=1 ;; esac
+SEG_SID="$(grep -o '"session_id"[[:space:]]*:[[:space:]]*"[^"]*"' "$NOJQ_HOME/.devlog/.segment-state" 2>/dev/null | head -1 | sed 's/.*"session_id"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/' || true)"
+if [ "$SEG_SID" = "cursor-nojq" ]; then
+  echo "PASS: nojq session_id stored in segment-state"
+else
+  echo "FAIL: nojq session_id missing (got [$SEG_SID])"; FAIL=1
+fi
+
+# --- no-jq PreToolUse deny must emit a single-line JSON object --------------
+# segment-watch deny stderr is multiline; without newline escaping, bash 3.2
+# prints unparseable JSON and Cursor fail-opens (valve vanishes).
+OUT="$(printf '{"workspace_roots":["%s"],"tool_name":"Bash","tool_input":{},"session_id":"cursor-mismatch"}' "$MIS" \
+  | env PATH="$CLEAN_PATH" bash "$SCRIPT_DIR/on-pre-tool.sh")"
+case "$OUT" in *'"permission":"deny"'*) echo "PASS: nojq mismatch preTool denies" ;; *) echo "FAIL: nojq mismatch preTool [$OUT]"; FAIL=1 ;; esac
+assert_single_json "nojq mismatch preTool deny single json" "$OUT"
+case "$OUT" in
+  *$'\n'*$'\n'*) echo "FAIL: nojq deny JSON contains raw newlines [$OUT]"; FAIL=1 ;;
+  *) echo "PASS: nojq deny JSON has no raw newlines inside the string" ;;
+esac
+if command -v python3 >/dev/null 2>&1; then
+  if printf '%s' "$OUT" | python3 -c 'import json,sys; json.load(sys.stdin)' >/dev/null 2>&1; then
+    echo "PASS: nojq deny JSON is parseable"
+  else
+    echo "FAIL: nojq deny JSON is not parseable [$OUT]"; FAIL=1
+  fi
+fi
+
+if [ "$FAIL" -eq 0 ]; then echo "All checks passed."; exit 0
+else echo "Some checks FAILED."; exit 1; fi

package/cursor/hooks.json

@@ -0,0 +1,26 @@
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [
+      { "command": "bash \"${DEVLOG_TRACKER_ROOT}/cursor/hooks/on-session-start.sh\"" }
+    ],
+    "beforeSubmitPrompt": [
+      { "command": "bash \"${DEVLOG_TRACKER_ROOT}/cursor/hooks/on-submit-prompt.sh\"" }
+    ],
+    "preToolUse": [
+      { "command": "bash \"${DEVLOG_TRACKER_ROOT}/cursor/hooks/on-pre-tool.sh\"" }
+    ],
+    "stop": [
+      {
+        "command": "bash \"${DEVLOG_TRACKER_ROOT}/cursor/hooks/on-stop.sh\"",
+        "loop_limit": 1
+      }
+    ],
+    "sessionEnd": [
+      { "command": "bash \"${DEVLOG_TRACKER_ROOT}/cursor/hooks/on-session-end.sh\"" }
+    ],
+    "postToolUseFailure": [
+      { "command": "bash \"${DEVLOG_TRACKER_ROOT}/cursor/hooks/on-tool-failure.sh\"" }
+    ]
+  }
+}

package/hooks/scripts/await-open.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+set -uo pipefail
+_src="${BASH_SOURCE[0]}"
+SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
+# shellcheck source=json-field.sh
+. "$SCRIPT_DIR/json-field.sh"
+# shellcheck source=devlog-md.sh
+. "$SCRIPT_DIR/devlog-md.sh"
+# shellcheck source=devlog-path.sh
+. "$SCRIPT_DIR/devlog-path.sh"
+
+devlog_resolve_paths "${CLAUDE_PROJECT_DIR:-.}"
+[ -f "$DEVLOG_DIR/.enabled" ] || { echo "NOT_ENABLED"; exit 1; }
+[ ! -e "$DEVLOG_DIR/.awaiting-reply" ] || { echo "ALREADY_OPEN"; exit 1; }
+ROUND=""
+[ ! -f "$DEVLOG_DIR/.round-open" ] || ROUND="$(json_int_get "$DEVLOG_DIR/.round-open" round)"
+if [ -z "$ROUND" ] && [ -f "$DEVLOG_FILE" ]; then
+  ROUND="$(devlog_list_round_starts "$DEVLOG_FILE" | awk 'END { print $2 }')"
+fi
+[ -n "$ROUND" ] || { echo "NO_ROUND"; exit 1; }
+OPENED_AT="$(date -Iseconds 2>/dev/null || date '+%Y-%m-%dT%H:%M:%S%z')"
+printf '{"round": %s, "opened_at": "%s"}\n' "$ROUND" "$OPENED_AT" > "$DEVLOG_DIR/.awaiting-reply" || exit 1
+printf 'OPENED=%s\n' "$ROUND"

package/hooks/scripts/checkpoint-set.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# User-invoked: /devlog-tracker:checkpoint filesystem side.
+# Sets Checkpoint Mode's max_silent_rounds threshold. $1 is required: a
+# positive integer number of rounds.
+set -uo pipefail
+_src="${BASH_SOURCE[0]}"
+SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
+# shellcheck source=json-field.sh
+. "$SCRIPT_DIR/json-field.sh"
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+DEVLOG_DIR="$PROJECT_DIR/.devlog"
+
+if [ ! -f "$DEVLOG_DIR/.enabled" ]; then
+  echo "NOT_STARTED"
+  exit 0
+fi
+
+ROUNDS_ARG="${1:-}"
+case "$ROUNDS_ARG" in
+  ''|*[!0-9]*|0)
+    echo "max_silent_rounds must be a positive integer number of rounds, got: $ROUNDS_ARG" >&2
+    exit 1
+    ;;
+esac
+
+if [ -f "$DEVLOG_DIR/.checkpoint-state" ]; then
+  json_int_set "$DEVLOG_DIR/.checkpoint-state" max_silent_rounds "$ROUNDS_ARG"
+  APPLIED="$(json_int_get "$DEVLOG_DIR/.checkpoint-state" max_silent_rounds)"
+  if [ "$APPLIED" != "$ROUNDS_ARG" ]; then
+    ROUNDS="$(json_int_get "$DEVLOG_DIR/.checkpoint-state" rounds_since_checkpoint)"
+    MARKERS="$(json_int_get "$DEVLOG_DIR/.checkpoint-state" checkpoint_marker_count)"
+    case "$ROUNDS" in ''|*[!0-9]*) ROUNDS=0 ;; esac
+    case "$MARKERS" in ''|*[!0-9]*) MARKERS=0 ;; esac
+    printf '%s\n' "{\"rounds_since_checkpoint\": ${ROUNDS}, \"max_silent_rounds\": ${ROUNDS_ARG}, \"checkpoint_marker_count\": ${MARKERS}}" \
+      > "$DEVLOG_DIR/.checkpoint-state" || exit 1
+  fi
+else
+  printf '%s\n' "{\"rounds_since_checkpoint\": 0, \"max_silent_rounds\": ${ROUNDS_ARG}, \"checkpoint_marker_count\": 0}" \
+    > "$DEVLOG_DIR/.checkpoint-state" || exit 1
+fi
+
+echo "CHECKPOINT_MAX_SILENT_ROUNDS=$(json_int_get "$DEVLOG_DIR/.checkpoint-state" max_silent_rounds)"
+exit 0

package/hooks/scripts/clean-devlog.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+_src="${BASH_SOURCE[0]}"
+SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
+. "$SCRIPT_DIR/devlog-md.sh"
+. "$SCRIPT_DIR/json-field.sh"
+. "$SCRIPT_DIR/devlog-lock.sh"
+. "$SCRIPT_DIR/devlog-path.sh"
+
+# Destructive and irreversible: only run when the caller has explicitly
+# confirmed with the user first. This is a mechanical guard, not a
+# replacement for that confirmation.
+[ "${1:-}" = "--confirmed" ] || { echo "需要 --confirmed（使用者尚未確認，不要呼叫這支腳本）" >&2; exit 1; }
+
+devlog_resolve_paths "${CLAUDE_PROJECT_DIR:-.}"
+devlog_lock_acquire
+trap 'devlog_lock_release' EXIT
+MAIN="$DEVLOG_FILE"
+ROUND_OPEN="$DEVLOG_DIR/.round-open"
+ROUND_CURRENT="$DEVLOG_DIR/.round-current.md"
+# Post-split, devlog.md may legitimately not exist yet (a project's very
+# first round can still be open, with real content sitting only in
+# .round-current.md) — accept either devlog.md existing or .round-current.md
+# having content to clean.
+[ -f "$MAIN" ] || [ -s "$ROUND_CURRENT" ] || { echo "devlog.md 不存在" >&2; exit 1; }
+
+HAS_OPEN=0
+OPEN=""
+if [ -f "$ROUND_OPEN" ]; then
+  OPEN="$(json_int_get "$ROUND_OPEN" round)"
+  [ -n "$OPEN" ] || { echo ".round-open 內容無法解析，未清空" >&2; exit 1; }
+  [ -s "$ROUND_CURRENT" ] || { echo "找不到開著的 .round-current.md 內容，狀態可能不一致，未清空" >&2; exit 1; }
+  HAS_OPEN=1
+fi
+
+if [ "$HAS_OPEN" -eq 1 ]; then
+  # Keep the split's invariant intact: the open round's content stays in
+  # .round-current.md (renumbered to Round 1), never in devlog.md. Writing
+  # it into devlog.md here would leave .round-open pointing at a round
+  # that Stop/close-open-round.sh can't find (they only ever look at
+  # .round-current.md), silently disabling enforcement for the rest of
+  # this turn and orphaning recovery on a crash.
+  TMP_DIR="$(mktemp -d "$DEVLOG_DIR/.clean.XXXXXX")" || exit 1
+  trap 'rm -rf "$TMP_DIR"; devlog_lock_release' EXIT
+  NEW_CURRENT="$TMP_DIR/round-current.md"
+  awk -v open="$OPEN" '
+    NR == 1 && $0 ~ ("^## Round " open "([^0-9]|$)") { sub("^## Round " open, "## Round 1") }
+    { print }
+  ' "$ROUND_CURRENT" > "$NEW_CURRENT" || exit 1
+  [ -s "$NEW_CURRENT" ] && grep -q '^## Round 1' "$NEW_CURRENT" || { echo "重寫結果異常，未寫入" >&2; exit 1; }
+  mv "$NEW_CURRENT" "$ROUND_CURRENT" || exit 1
+  rm -f "$MAIN" || exit 1
+  rm -rf "$TMP_DIR"
+  json_int_set "$ROUND_OPEN" round 1
+  KEPT_ROUND=1
+else
+  rm -f "$MAIN" "$ROUND_CURRENT" || exit 1
+  KEPT_ROUND=0
+fi
+
+rm -f "$DEVLOG_DIR/.span-open" "$DEVLOG_DIR/.interrupted" "$DEVLOG_DIR/.awaiting-reply"
+if [ -f "$DEVLOG_DIR/.checkpoint-state" ]; then
+  json_int_set "$DEVLOG_DIR/.checkpoint-state" rounds_since_checkpoint 0
+  json_int_set "$DEVLOG_DIR/.checkpoint-state" checkpoint_marker_count 0
+fi
+
+printf 'CLEANED KEPT_ROUND=%s\n' "$KEPT_ROUND"
+exit 0

package/hooks/scripts/close-open-round.sh

@@ -0,0 +1,186 @@
+#!/usr/bin/env bash
+# Stamp the open Round as INTERRUPTED. Always exit 0 (fail-open).
+# Usage: close-open-round.sh <reason> [detail]
+# The reason is written as a bracketed tag under Status (`[reason: ...]`) so
+# it reads as internal debug metadata, not a broken/extra Status value — and
+# stays visible even through a Markdown renderer (unlike an HTML comment,
+# which a renderer would silently drop, losing the debug trail).
+# detail (optional): "awaiting_question" makes the stub Summary/Handoff name
+# the likely cause (interrupted while an AskUserQuestion answer was pending)
+# instead of the generic "沒有正常收尾" — caller decides via
+# detect-pending-question.sh; empty/unknown detail falls back to the generic
+# stub, same as before.
+# When detail is empty, the stub wording also depends on RECOVERED (did
+# devlog.md change at all since the round's skeleton was written): if not,
+# nothing was ever written back for this round (most likely the next prompt
+# arrived before Claude engaged with it at all), so the stub says that
+# plainly instead of implying work was interrupted mid-way.
+# Silent on stdout — SessionStart injects stdout as additionalContext.
+set -uo pipefail
+
+REASON="${1:-unknown}"
+DETAIL="${2:-}"
+
+_src="${BASH_SOURCE[0]}"
+SCRIPT_DIR="$(cd "${_src%/*}" && pwd)"
+# shellcheck source=json-field.sh
+. "$SCRIPT_DIR/json-field.sh"
+# shellcheck source=devlog-lock.sh
+. "$SCRIPT_DIR/devlog-lock.sh"
+# shellcheck source=devlog-path.sh
+. "$SCRIPT_DIR/devlog-path.sh"
+# shellcheck source=devlog-md.sh
+. "$SCRIPT_DIR/devlog-md.sh"
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+devlog_resolve_paths "$PROJECT_DIR"
+ENABLED_FLAG="$DEVLOG_DIR/.enabled"
+ROUND_OPEN="$DEVLOG_DIR/.round-open"
+INTERRUPTED_FLAG="$DEVLOG_DIR/.interrupted"
+ROUND_CURRENT="$DEVLOG_DIR/.round-current.md"
+TURN_MARKER="$DEVLOG_DIR/.turn-start"
+
+drop_markers() {
+  rm -f "$ROUND_OPEN" "$INTERRUPTED_FLAG" 2>/dev/null || true
+}
+
+[ -f "$ENABLED_FLAG" ] || exit 0
+devlog_lock_acquire
+trap 'devlog_lock_release' EXIT
+if [ ! -f "$ROUND_OPEN" ]; then
+  rm -f "$INTERRUPTED_FLAG" 2>/dev/null || true
+  exit 0
+fi
+
+ROUND_OPEN_FILE="$(json_str_get "$ROUND_OPEN" file 2>/dev/null || true)"
+if [ -n "$ROUND_OPEN_FILE" ] && [ "$ROUND_OPEN_FILE" != "${DEVLOG_FILE##*/}" ]; then
+  # This marker belongs to a different branch's devlog file (e.g. the user
+  # switched branches between round-start and now). Leave it untouched —
+  # whichever branch it actually belongs to will resolve and close it
+  # correctly when that branch is current again.
+  exit 0
+fi
+
+OPEN_ROUND="$(json_int_get "$ROUND_OPEN" round)"
+case "$OPEN_ROUND" in
+  ''|*[!0-9]*) drop_markers; exit 0 ;;
+esac
+
+if [ ! -f "$ROUND_CURRENT" ] || [ ! -s "$ROUND_CURRENT" ]; then
+  drop_markers
+  exit 0
+fi
+
+RECOVERED=0
+if [ -f "$TURN_MARKER" ]; then
+  TURN_HASH="$(cat "$TURN_MARKER" 2>/dev/null || echo '')"
+  CUR_HASH="$(cksum < "$ROUND_CURRENT" 2>/dev/null || echo '')"
+  if [ -n "$TURN_HASH" ] && [ -n "$CUR_HASH" ] && [ "$CUR_HASH" != "$TURN_HASH" ]; then
+    RECOVERED=1
+  fi
+fi
+
+TMP="$ROUND_CURRENT.tmp"
+awk -v reason="$REASON" -v detail="$DETAIL" -v recovered="$RECOVERED" '
+  function summary_stub() {
+    if (detail == "awaiting_question") return "這輪在等待使用者回答 AskUserQuestion 時結束，還沒收到答案。"
+    if (recovered == 0) return "這一輪送出後，devlog.md 沒有留下任何後續處理紀錄就結束了。"
+    return "這輪意外中斷。"
+  }
+  function reply_stub() {
+    if (detail == "awaiting_question") return "（中斷前正在等使用者回答問題。）"
+    if (recovered == 0) return "（這一輪在 devlog.md 裡沒有留下回覆紀錄。）"
+    return "（這輪意外中斷，沒有對使用者完成回覆。）"
+  }
+  function handoff_stub() {
+    if (detail == "awaiting_question") return "Claude 提了問題還在等回答，session 就先結束了；不是中途出錯，只是還沒收到答案。需要的話重新確認一次問題再繼續。"
+    if (recovered == 0) return "這一輪沒有留下任何處理紀錄；下一步請看上面的 User Input 原文決定要不要接著處理。"
+    return "這輪沒有正常收尾。"
+  }
+  { lines[NR] = $0; n = NR }
+  END {
+    has_s = 0
+    has_r = 0
+    has_h = 0
+    for (i = 1; i <= n; i++) {
+      if (lines[i] ~ /^### Summary/) has_s = 1
+      if (lines[i] ~ /^### Reply/) has_r = 1
+      if (lines[i] ~ /^### Handoff/) has_h = 1
+    }
+    # Recovered-complete still keys off Summary+Handoff (pre-Reply contract);
+    # Stop will require Reply on the next normal close if missing.
+    if (recovered && has_s && has_h) { exit 3 }
+
+    skip_val = 0
+    saw_status = 0
+    for (i = 1; i <= n; i++) {
+      if (skip_val) { skip_val = 0; continue }
+      if (lines[i] ~ /^### Status/) {
+        saw_status = 1
+        if (!has_s) {
+          print "### Summary"
+          print summary_stub()
+          print ""
+        }
+        if (!has_r) {
+          print "### Reply"
+          print reply_stub()
+          print ""
+        }
+        if (!has_h) {
+          print "### Handoff"
+          print "#### 現況"
+          print handoff_stub()
+          print ""
+        }
+        print "### Status"
+        print "INTERRUPTED"
+        print "[reason: " reason "]"
+        skip_val = 1
+        continue
+      }
+      print lines[i]
+    }
+    if (!saw_status) {
+      if (!has_s) {
+        print "### Summary"
+        print summary_stub()
+        print ""
+      }
+      if (!has_r) {
+        print "### Reply"
+        print reply_stub()
+        print ""
+      }
+      if (!has_h) {
+        print "### Handoff"
+        print "#### 現況"
+        print handoff_stub()
+        print ""
+      }
+      print "### Status"
+      print "INTERRUPTED"
+      print "[reason: " reason "]"
+    }
+  }
+' "$ROUND_CURRENT" > "$TMP" 2>/dev/null
+AWK_RC=$?
+if [ "$AWK_RC" -eq 0 ]; then
+  mv "$TMP" "$ROUND_CURRENT" 2>/dev/null || true
+else
+  rm -f "$TMP" 2>/dev/null || true
+fi
+if [ "$AWK_RC" -eq 0 ] || [ "$AWK_RC" -eq 3 ]; then
+  # 只有併入真的成功才清掉 .round-open：併入失敗（例如寫入失敗）時保留它，
+  # 讓下一次 dangling-heal（下一則訊息／下次 SessionStart 都會跑到）還有
+  # 機會重試，而不是內容被孤立在 .round-current.md 卻沒有任何機制知道要去
+  # 救它。.interrupted 這個訊號本身已經處理完，兩種結果都清掉。
+  if devlog_merge_round_current "$DEVLOG_FILE" "$ROUND_CURRENT"; then
+    drop_markers
+  else
+    rm -f "$INTERRUPTED_FLAG" 2>/dev/null || true
+  fi
+else
+  drop_markers
+fi
+exit 0