instar 1.2.54 → 1.2.56

package/.claude/skills/autonomous/hooks/autonomous-stop-hook.sh

@@ -4,167 +4,348 @@
 # Prevents session exit when autonomous mode is active.
 # Feeds the goal and task list back to continue working.
 #
-# SESSION-SCOPED: Only blocks the session that activated autonomous mode.
-# Other sessions on the same machine pass through unaffected.
+# MULTI-SESSION (per-topic state): each autonomous job has its own state file at
+# .instar/autonomous/<topicId>.local.md, so multiple topics can run autonomous
+# jobs concurrently without colliding. This session resolves its own topic (from
+# its tmux session name via the topic-session registry) and reads THAT topic's
+# state file. Ownership is therefore implicit: if my topic's file exists and is
+# active, I am its worker. A legacy single-file job (.instar/autonomous-state.local.md)
+# is still honored for back-compat and migrated to the per-topic path on first touch.
 #
-# RESPECTS:
-# - Session isolation (only blocks the autonomous session)
-# - Emergency stop signals (user says "stop everything")
-# - Duration expiry
-# - Genuine completion (all tasks done, promise output)
+# TOPIC-KEYED OWNERSHIP survives restarts: a memory-limit restart rotates the
+# Claude session UUID but instar respawns into the SAME tmux name, which still
+# maps to the same topic — so the restarted session reads the same per-topic file
+# and keeps going. (Legacy-file path keeps the v1.2.55 topic-or-liveness backstop.)
+#
+# RECOVERY NOTE: on a real restart-and-resume (topic file found but the recorded
+# session UUID changed) the hook emits ONE channel-neutral recovery note + audit
+# record, then records the new UUID so it never repeats.
+#
+# RESPECTS: emergency stop, duration expiry, genuine completion (promise).
 
-set -euo pipefail
+set -uo pipefail   # NOTE: -e intentionally omitted; field lookups for optional
+                   # frontmatter keys are expected to "fail" (grep finds nothing)
+                   # and must not abort the hook. Each critical step guards itself.
 
 # Read hook input from stdin
 HOOK_INPUT=$(cat)
 
-# Check if autonomous mode is active
-STATE_FILE=".instar/autonomous-state.local.md"
+REGISTRY_FILE=".instar/topic-session-registry.json"
+RECOVERY_AUDIT=".instar/autonomous-recovery.jsonl"
+LEGACY_STATE=".instar/autonomous-state.local.md"
+MULTI_DIR=".instar/autonomous"
+LIVENESS_SECS="${INSTAR_AUTONOMOUS_LIVENESS_SECS:-120}"
+
+# ── Inputs from the hook ──────────────────────────────────────────────
+HOOK_SESSION=$(printf '%s' "$HOOK_INPUT" | jq -r '.session_id // ""' 2>/dev/null || echo "")
+TRANSCRIPT_PATH=$(printf '%s' "$HOOK_INPUT" | jq -r '.transcript_path // ""' 2>/dev/null || echo "")
+
+# If hook has no session_id → fail OPEN (unknown context, don't trap)
+if [[ -z "$HOOK_SESSION" ]]; then
+  echo "⚠️  Autonomous mode: No session_id in hook input — fail-open (allowing exit)" >&2
+  exit 0
+fi
+
+# ── Resolve MY tmux session name (the stable address) ─────────────────
+# Test/override seam: INSTAR_HOOK_TMUX_SESSION (if the var is set at all, even
+# empty, it wins — empty means "no tmux"). INSTAR_HOOK_NO_TMUX=1 forces empty.
+resolve_my_tmux() {
+  if [[ "${INSTAR_HOOK_NO_TMUX:-}" == "1" ]]; then
+    echo ""
+    return
+  fi
+  if [[ -n "${INSTAR_HOOK_TMUX_SESSION+x}" ]]; then
+    echo "${INSTAR_HOOK_TMUX_SESSION}"
+    return
+  fi
+  tmux display-message -p '#S' 2>/dev/null || echo ""
+}
+MY_TMUX=$(resolve_my_tmux)
+
+# Reverse-lookup: which topic does MY tmux session serve? (topicToSession is
+# topic→tmux; we invert it to find my topic.)
+MY_TOPIC=""
+if [[ -n "$MY_TMUX" ]] && [[ -f "$REGISTRY_FILE" ]]; then
+  MY_TOPIC=$(INSTAR_MY_TMUX="$MY_TMUX" python3 -c "
+import json, os
+try:
+    reg = json.load(open('$REGISTRY_FILE'))
+    me = os.environ['INSTAR_MY_TMUX']
+    t2s = reg.get('topicToSession') or {}
+    hit = [k for k, v in t2s.items() if v == me]
+    print(hit[0] if hit else '')
+except Exception:
+    print('')
+" 2>/dev/null || echo "")
+fi
 
-if [[ ! -f "$STATE_FILE" ]]; then
-  # No active autonomous session — allow exit
+# Helper: read a frontmatter field from an arbitrary state file (pipefail-safe).
+fm_get_from() {
+  local file="$1" key="$2"
+  sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$file" 2>/dev/null | grep "^${key}:" | head -1 | sed "s/^${key}: *//" | tr -d '"' || true
+}
+
+# ── Select the state file (per-topic preferred; legacy fallback + migrate) ──
+STATE_FILE=""
+OWNED_VIA_TOPIC="false"
+PER_TOPIC_FILE=""
+[[ -n "$MY_TOPIC" ]] && PER_TOPIC_FILE="$MULTI_DIR/${MY_TOPIC}.local.md"
+
+if [[ -n "$PER_TOPIC_FILE" ]] && [[ -f "$PER_TOPIC_FILE" ]]; then
+  STATE_FILE="$PER_TOPIC_FILE"
+  OWNED_VIA_TOPIC="true"
+elif [[ -f "$LEGACY_STATE" ]]; then
+  # A legacy single-file job exists. If it belongs to MY topic, migrate it to the
+  # per-topic path (idempotent, never disrupts the running job — same content).
+  LEGACY_TOPIC=$(fm_get_from "$LEGACY_STATE" report_topic)
+  if [[ -n "$MY_TOPIC" ]] && [[ "$LEGACY_TOPIC" == "$MY_TOPIC" ]]; then
+    mkdir -p "$MULTI_DIR"
+    if mv "$LEGACY_STATE" "$PER_TOPIC_FILE" 2>/dev/null; then
+      STATE_FILE="$PER_TOPIC_FILE"; OWNED_VIA_TOPIC="true"
+      echo "[autonomous] migrated legacy state → $PER_TOPIC_FILE" >&2
+    else
+      STATE_FILE="$LEGACY_STATE"
+    fi
+  else
+    # Legacy job for a different/unknown topic — honor it via the legacy
+    # ownership logic below (preserves v1.2.55 behavior for in-flight jobs).
+    STATE_FILE="$LEGACY_STATE"
+  fi
+else
+  # No autonomous job for this session anywhere — allow exit.
   exit 0
 fi
 
-# Parse YAML frontmatter
+# ── Read the selected state file ──────────────────────────────────────
 FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$STATE_FILE")
+fm_get() {
+  local key="$1"
+  printf '%s\n' "$FRONTMATTER" | grep "^${key}:" | head -1 | sed "s/^${key}: *//" | tr -d '"' || true
+}
 
-ACTIVE=$(echo "$FRONTMATTER" | grep '^active:' | sed 's/active: *//')
+ACTIVE=$(fm_get active)
 if [[ "$ACTIVE" != "true" ]]; then
   exit 0
 fi
 
-# SESSION ISOLATION: Only block the session that started autonomous mode.
-# Uses self-bootstrapping: if no session_id in state file yet, the FIRST
-# session to trigger the hook claims it. All other sessions see a mismatch.
-STATE_SESSION=$(echo "$FRONTMATTER" | grep '^session_id:' | sed 's/^session_id: *//' | tr -d '"' || true)
+# Paused (e.g. by quota-pressure load-shedding) — allow exit until resumed.
+PAUSED=$(fm_get paused)
+if [[ "$PAUSED" == "true" ]]; then
+  echo "[autonomous] job paused — allowing exit until resumed" >&2
+  exit 0
+fi
 
-# VALIDATE: If state has a session_id but it's not a valid UUID, treat as empty.
-# Claude sometimes writes a custom string instead of the real $CLAUDE_CODE_SESSION_ID.
-# Non-UUID values will never match the real hook session_id, causing the hook to
-# fail-open and allow premature exit. By clearing invalid values, we fall through
-# to self-bootstrap, which captures the REAL session_id from the first hook call.
+REPORT_TOPIC=$(fm_get report_topic)
+# Channel that owns this job — recovery note routes here. Default telegram for
+# back-compat (state files written before channel-neutral delivery existed).
+REPORT_CHANNEL=$(fm_get report_channel)
+[[ -z "$REPORT_CHANNEL" ]] && REPORT_CHANNEL="telegram"
+STATE_SESSION=$(fm_get session_id)
+ITERATION=$(fm_get iteration)
+DURATION_SECONDS=$(fm_get duration_seconds)
+STARTED_AT=$(fm_get started_at)
+COMPLETION_PROMISE=$(fm_get completion_promise)
+
+# Validate recorded session_id is a real UUID. Claude sometimes writes a custom
+# string instead of $CLAUDE_CODE_SESSION_ID; non-UUID values are treated as
+# empty so the session-match backstop self-bootstraps from the real UUID.
 UUID_REGEX='^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
 if [[ -n "$STATE_SESSION" ]] && ! [[ "$STATE_SESSION" =~ $UUID_REGEX ]]; then
-  echo "[autonomous] Invalid session_id in state file (not UUID): '$STATE_SESSION' — falling back to self-bootstrap" >&2
+  echo "[autonomous] Invalid session_id in state file (not UUID): '$STATE_SESSION' — clearing" >&2
   STATE_SESSION=""
 fi
 
-HOOK_SESSION=$(echo "$HOOK_INPUT" | jq -r '.session_id // ""' 2>/dev/null || echo "")
-
-# If hook has no session_id → fail OPEN (unknown context, don't trap)
-if [[ -z "$HOOK_SESSION" ]]; then
-  echo "⚠️  Autonomous mode: No session_id in hook input — fail-open (allowing exit)" >&2
-  exit 0
-fi
+# ── Ownership decision ────────────────────────────────────────────────
+# OWNER=true means: this session IS the autonomous worker; block its exit.
+# OWNER_METHOD: topic (per-topic file) | topic-legacy | session | bootstrap | adopt-dead.
+OWNER="false"
+OWNER_METHOD=""
+RESTART_DETECTED="false"
+
+if [[ "$OWNED_VIA_TOPIC" == "true" ]]; then
+  # Reading MY topic's own file — ownership is implicit and unambiguous.
+  OWNER="true"; OWNER_METHOD="topic"
+  if [[ -n "$STATE_SESSION" ]] && [[ "$STATE_SESSION" != "$HOOK_SESSION" ]]; then
+    RESTART_DETECTED="true"
+  fi
+else
+  # ── Legacy single-file path: v1.2.55 topic-keyed-or-liveness-backstop ──
+  OWNER_TMUX=""
+  if [[ -n "$REPORT_TOPIC" ]] && [[ -f "$REGISTRY_FILE" ]]; then
+    OWNER_TMUX=$(REPORT_TOPIC="$REPORT_TOPIC" python3 -c "
+import json, os
+try:
+    reg = json.load(open('$REGISTRY_FILE'))
+    print((reg.get('topicToSession') or {}).get(os.environ['REPORT_TOPIC'], ''))
+except Exception:
+    print('')
+" 2>/dev/null || echo "")
+  fi
 
-# SELF-BOOTSTRAP: If state has no session_id yet, claim it from this hook call.
-# The first session to fire the hook becomes the autonomous session.
-if [[ -z "$STATE_SESSION" ]]; then
-  # Atomic claim: write session_id to state file
-  TEMP_FILE="${STATE_FILE}.claim.$$"
-  sed "s/^session_id:.*/session_id: \"${HOOK_SESSION}\"/" "$STATE_FILE" > "$TEMP_FILE"
-  mv "$TEMP_FILE" "$STATE_FILE"
-  STATE_SESSION="$HOOK_SESSION"
-  echo "[autonomous] Session $HOOK_SESSION claimed autonomous mode" >&2
+  if [[ -n "$MY_TMUX" ]] && [[ -n "$OWNER_TMUX" ]]; then
+    if [[ "$MY_TMUX" == "$OWNER_TMUX" ]]; then
+      OWNER="true"; OWNER_METHOD="topic-legacy"
+      if [[ -n "$STATE_SESSION" ]] && [[ "$STATE_SESSION" != "$HOOK_SESSION" ]]; then
+        RESTART_DETECTED="true"
+      fi
+    else
+      exit 0   # legacy job belongs to a different session's topic
+    fi
+  else
+    # Topic unresolved — session-id backstop, liveness-gated.
+    if [[ -z "$STATE_SESSION" ]]; then
+      OWNER="true"; OWNER_METHOD="bootstrap"
+    elif [[ "$STATE_SESSION" == "$HOOK_SESSION" ]]; then
+      OWNER="true"; OWNER_METHOD="session"
+    else
+      OWNER_ALIVE="false"
+      if [[ -n "$TRANSCRIPT_PATH" ]]; then
+        OWNER_TRANSCRIPT="$(dirname "$TRANSCRIPT_PATH")/${STATE_SESSION}.jsonl"
+        if [[ -f "$OWNER_TRANSCRIPT" ]]; then
+          NOW_E=$(date +%s)
+          # GNU stat (-c %Y) first (Linux/CI); BSD stat (-f %m) fallback (macOS).
+          # GNU `stat -f` is filesystem mode and succeeds with non-numeric output,
+          # so BSD-first would mask the GNU path on Linux; numeric guard treats a
+          # bad mtime as 0 (very old → dead) rather than crashing the arithmetic.
+          MTIME=$(stat -c %Y "$OWNER_TRANSCRIPT" 2>/dev/null || stat -f %m "$OWNER_TRANSCRIPT" 2>/dev/null || echo 0)
+          [[ "$MTIME" =~ ^[0-9]+$ ]] || MTIME=0
+          AGE=$(( NOW_E - MTIME ))
+          if [[ $MTIME -gt 0 ]] && [[ $AGE -lt $LIVENESS_SECS ]]; then
+            OWNER_ALIVE="true"
+          fi
+        fi
+      fi
+      if [[ "$OWNER_ALIVE" == "true" ]]; then
+        exit 0   # a genuinely different, live session owns this — don't steal
+      fi
+      OWNER="true"; OWNER_METHOD="adopt-dead"; RESTART_DETECTED="true"
+    fi
+  fi
 fi
 
-# Different session → allow exit (fail-open for non-autonomous sessions)
-if [[ "$STATE_SESSION" != "$HOOK_SESSION" ]]; then
+if [[ "$OWNER" != "true" ]]; then
   exit 0
 fi
 
-# Same session — this IS the autonomous session, proceed with block logic
-
-ITERATION=$(echo "$FRONTMATTER" | grep '^iteration:' | sed 's/iteration: *//')
-DURATION_SECONDS=$(echo "$FRONTMATTER" | grep '^duration_seconds:' | sed 's/duration_seconds: *//')
-STARTED_AT=$(echo "$FRONTMATTER" | grep '^started_at:' | sed 's/started_at: *//' | tr -d '"')
-COMPLETION_PROMISE=$(echo "$FRONTMATTER" | grep '^completion_promise:' | sed 's/completion_promise: *//' | tr -d '"')
-REPORT_TOPIC=$(echo "$FRONTMATTER" | grep '^report_topic:' | sed 's/report_topic: *//' | tr -d '"')
+# ── This IS the autonomous session. Terminal checks first. ────────────
 
 # Validate iteration
 if [[ ! "$ITERATION" =~ ^[0-9]+$ ]]; then
   echo "⚠️  Autonomous mode: State file corrupted (bad iteration)" >&2
-  rm "$STATE_FILE"
+  rm -f "$STATE_FILE"
   exit 0
 fi
 
-# Check duration expiry
+# Duration expiry. Fail-SAFE: if started_at can't be parsed (START_EPOCH falls
+# back to 0/empty), do NOT expire — an unparseable timestamp must never cause a
+# premature exit (that is the very failure class this hook exists to prevent).
+REMAINING_MIN=""
 if [[ "$DURATION_SECONDS" =~ ^[0-9]+$ ]] && [[ $DURATION_SECONDS -gt 0 ]]; then
-  START_EPOCH=$(date -j -f "%Y-%m-%dT%H:%M:%SZ" "$STARTED_AT" +%s 2>/dev/null || date -d "$STARTED_AT" +%s 2>/dev/null || echo "0")
-  NOW_EPOCH=$(date +%s)
-  ELAPSED=$(( NOW_EPOCH - START_EPOCH ))
-  if [[ $ELAPSED -ge $DURATION_SECONDS ]]; then
-    echo "⏰ Autonomous mode: Duration expired ($ELAPSED seconds elapsed)."
-    echo "   Session is free to exit."
-    rm "$STATE_FILE"
-    exit 0
+  START_EPOCH=$(date -u -j -f "%Y-%m-%dT%H:%M:%SZ" "$STARTED_AT" +%s 2>/dev/null || date -d "$STARTED_AT" +%s 2>/dev/null || echo "0")
+  if [[ "$START_EPOCH" =~ ^[0-9]+$ ]] && [[ $START_EPOCH -gt 0 ]]; then
+    NOW_EPOCH=$(date +%s)
+    ELAPSED=$(( NOW_EPOCH - START_EPOCH ))
+    if [[ $ELAPSED -ge $DURATION_SECONDS ]]; then
+      echo "⏰ Autonomous mode: Duration expired ($ELAPSED seconds elapsed)."
+      echo "   Session is free to exit."
+      rm -f "$STATE_FILE"
+      exit 0
+    fi
+    REMAINING=$(( DURATION_SECONDS - ELAPSED ))
+    REMAINING_MIN=$(( REMAINING / 60 ))
+  else
+    echo "[autonomous] started_at unparseable ('$STARTED_AT') — skipping duration-expiry check (fail-safe: keep running)" >&2
   fi
-  REMAINING=$(( DURATION_SECONDS - ELAPSED ))
-  REMAINING_MIN=$(( REMAINING / 60 ))
 fi
 
-# Check for emergency stop (look in recent messages)
-# The MessageSentinel handles this at the messaging layer, but also check here
+# Emergency stop (global — halts every autonomous job on its next fire)
 if [[ -f ".instar/autonomous-emergency-stop" ]]; then
   echo "🛑 Autonomous mode: Emergency stop detected."
-  rm "$STATE_FILE"
-  rm -f ".instar/autonomous-emergency-stop"
+  rm -f "$STATE_FILE"
+  # NOTE: the emergency flag is left in place so OTHER topics' hooks also see it
+  # and clear their own per-topic files; stop-all clears the flag when complete.
   exit 0
 fi
 
-# Get transcript and check for completion promise
-TRANSCRIPT_PATH=$(echo "$HOOK_INPUT" | jq -r '.transcript_path' 2>/dev/null || echo "")
-
+# Completion promise (genuine completion)
 if [[ -n "$TRANSCRIPT_PATH" ]] && [[ -f "$TRANSCRIPT_PATH" ]]; then
-  # Check last assistant message for completion promise
   LAST_LINE=$(grep '"role":"assistant"' "$TRANSCRIPT_PATH" 2>/dev/null | tail -1 || echo "")
-
   if [[ -n "$LAST_LINE" ]]; then
-    LAST_OUTPUT=$(echo "$LAST_LINE" | jq -r '
-      .message.content |
-      map(select(.type == "text")) |
-      map(.text) |
-      join("\n")
+    LAST_OUTPUT=$(printf '%s' "$LAST_LINE" | jq -r '
+      .message.content | map(select(.type == "text")) | map(.text) | join("\n")
     ' 2>/dev/null || echo "")
-
-    # Check for completion promise in <promise> tags
     if [[ -n "$COMPLETION_PROMISE" ]] && [[ "$COMPLETION_PROMISE" != "null" ]]; then
-      PROMISE_TEXT=$(echo "$LAST_OUTPUT" | perl -0777 -pe 's/.*?<promise>(.*?)<\/promise>.*/$1/s; s/^\s+|\s+$//g; s/\s+/ /g' 2>/dev/null || echo "")
-
+      PROMISE_TEXT=$(printf '%s' "$LAST_OUTPUT" | perl -0777 -pe 's/.*?<promise>(.*?)<\/promise>.*/$1/s; s/^\s+|\s+$//g; s/\s+/ /g' 2>/dev/null || echo "")
       if [[ -n "$PROMISE_TEXT" ]] && [[ "$PROMISE_TEXT" = "$COMPLETION_PROMISE" ]]; then
         echo "✅ Autonomous mode: Completion promise detected — <promise>$COMPLETION_PROMISE</promise>"
         echo "   Session is free to exit. Good work!"
-        rm "$STATE_FILE"
+        rm -f "$STATE_FILE"
         exit 0
       fi
     fi
   fi
 fi
 
-# Not complete — block exit and feed task list back
+# ── Not terminal: we are continuing. Handle restart-resume recovery note. ──
+record_session_id() {
+  local new_id="$1"
+  local tmp="${STATE_FILE}.sid.$$"
+  if grep -q '^session_id:' "$STATE_FILE"; then
+    sed "s/^session_id:.*/session_id: \"${new_id}\"/" "$STATE_FILE" > "$tmp" && mv "$tmp" "$STATE_FILE"
+  fi
+}
+
+# Channel-neutral delivery seam (no Telegram assumption). Telegram wired; other
+# channels owned by the Channel Parity initiative. Audit record is the source of truth.
+deliver_recovery_note() {
+  local channel="$1" target="$2" text="$3"
+  [[ -z "$target" ]] && return 0
+  case "$channel" in
+    telegram)
+      if [[ -x ".instar/scripts/telegram-reply.sh" ]]; then
+        printf '%s\n' "$text" | .instar/scripts/telegram-reply.sh "$target" >/dev/null 2>&1 || true
+      elif [[ -x ".claude/scripts/telegram-reply.sh" ]]; then
+        printf '%s\n' "$text" | .claude/scripts/telegram-reply.sh "$target" >/dev/null 2>&1 || true
+      fi
+      ;;
+    *)
+      echo "[autonomous] recovery note for channel '$channel' recorded to audit; live delivery pending the Channel Parity initiative" >&2
+      ;;
+  esac
+}
+
+if [[ "$RESTART_DETECTED" == "true" ]] && [[ "$STATE_SESSION" != "$HOOK_SESSION" ]]; then
+  ITER_LABEL="${ITERATION:-?}"
+  NOTE="Heads up — my session restarted mid-run and I've picked the autonomous job back up (topic ${REPORT_TOPIC:-?}, iteration ${ITER_LABEL}). No action needed."
+  TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+  printf '{"ts":"%s","event":"restart-resume","channel":"%s","topic":"%s","oldSession":"%s","newSession":"%s","method":"%s","iteration":"%s"}\n' \
+    "$TS" "$REPORT_CHANNEL" "${REPORT_TOPIC:-}" "$STATE_SESSION" "$HOOK_SESSION" "$OWNER_METHOD" "$ITER_LABEL" >> "$RECOVERY_AUDIT" 2>/dev/null || true
+  deliver_recovery_note "$REPORT_CHANNEL" "$REPORT_TOPIC" "$NOTE"
+  echo "[autonomous] restart-resume: channel=$REPORT_CHANNEL topic=${REPORT_TOPIC:-?} old=$STATE_SESSION new=$HOOK_SESSION method=$OWNER_METHOD" >&2
+fi
+
+# Reconcile recorded session_id to live (covers restart, bootstrap, adopt).
+if [[ "$STATE_SESSION" != "$HOOK_SESSION" ]]; then
+  record_session_id "$HOOK_SESSION"
+fi
+
+# ── Continue the job: increment iteration, feed the task back. ────────
 NEXT_ITERATION=$((ITERATION + 1))
 
-# Extract prompt (everything after closing ---)
 PROMPT_TEXT=$(awk '/^---$/{i++; next} i>=2' "$STATE_FILE")
-
 if [[ -z "$PROMPT_TEXT" ]]; then
   echo "⚠️  Autonomous mode: State file has no task content" >&2
-  rm "$STATE_FILE"
+  rm -f "$STATE_FILE"
   exit 0
 fi
 
-# Update iteration counter
-TEMP_FILE="${STATE_FILE}.tmp.$$"
-sed "s/^iteration: .*/iteration: $NEXT_ITERATION/" "$STATE_FILE" > "$TEMP_FILE"
-mv "$TEMP_FILE" "$STATE_FILE"
+TEMP_FILE="${STATE_FILE}.iter.$$"
+sed "s/^iteration: .*/iteration: $NEXT_ITERATION/" "$STATE_FILE" > "$TEMP_FILE" && mv "$TEMP_FILE" "$STATE_FILE"
 
 # ── Progress Report Check ──
-# Check if it's time to send a progress report
-REPORT_INTERVAL=$(echo "$FRONTMATTER" | grep '^report_interval:' | sed 's/report_interval: *//' | tr -d '"')
-LAST_REPORT_AT=$(echo "$FRONTMATTER" | grep '^last_report_at:' | sed 's/last_report_at: *//' | tr -d '"')
+REPORT_INTERVAL=$(fm_get report_interval)
+LAST_REPORT_AT=$(fm_get last_report_at)
 
-# Convert report interval to seconds
 REPORT_INTERVAL_SECS=1800  # default 30 minutes
 if [[ "$REPORT_INTERVAL" =~ ^([0-9]+)m$ ]]; then
   REPORT_INTERVAL_SECS=$(( ${BASH_REMATCH[1]} * 60 ))
@@ -174,37 +355,30 @@ fi
 
 REPORT_DUE="false"
 NOW_EPOCH=$(date +%s)
-
-if [[ -z "$LAST_REPORT_AT" ]] || [[ "$LAST_REPORT_AT" == "null" ]] || [[ "$LAST_REPORT_AT" == '""' ]]; then
-  # No report sent yet — due if we've been running for at least one interval
+if [[ -z "$LAST_REPORT_AT" ]] || [[ "$LAST_REPORT_AT" == "null" ]]; then
   if [[ -n "$STARTED_AT" ]]; then
-    START_EPOCH_R=$(date -j -f "%Y-%m-%dT%H:%M:%SZ" "$STARTED_AT" +%s 2>/dev/null || date -d "$STARTED_AT" +%s 2>/dev/null || echo "0")
+    START_EPOCH_R=$(date -u -j -f "%Y-%m-%dT%H:%M:%SZ" "$STARTED_AT" +%s 2>/dev/null || date -d "$STARTED_AT" +%s 2>/dev/null || echo "0")
     ELAPSED_SINCE_START=$(( NOW_EPOCH - START_EPOCH_R ))
     if [[ $ELAPSED_SINCE_START -ge $REPORT_INTERVAL_SECS ]]; then
       REPORT_DUE="true"
     fi
   fi
 else
-  # Check time since last report
-  LAST_REPORT_EPOCH=$(date -j -f "%Y-%m-%dT%H:%M:%SZ" "$LAST_REPORT_AT" +%s 2>/dev/null || date -d "$LAST_REPORT_AT" +%s 2>/dev/null || echo "0")
+  LAST_REPORT_EPOCH=$(date -u -j -f "%Y-%m-%dT%H:%M:%SZ" "$LAST_REPORT_AT" +%s 2>/dev/null || date -d "$LAST_REPORT_AT" +%s 2>/dev/null || echo "0")
   ELAPSED_SINCE_REPORT=$(( NOW_EPOCH - LAST_REPORT_EPOCH ))
   if [[ $ELAPSED_SINCE_REPORT -ge $REPORT_INTERVAL_SECS ]]; then
     REPORT_DUE="true"
   fi
 fi
 
-# If report is due, update last_report_at in state file
 REPORT_DIRECTIVE=""
 if [[ "$REPORT_DUE" == "true" ]]; then
   REPORT_NOW=$(date -u +%Y-%m-%dT%H:%M:%SZ)
-  # Update or add last_report_at in frontmatter
   if grep -q '^last_report_at:' "$STATE_FILE"; then
-    TEMP_FILE2="${STATE_FILE}.tmp2.$$"
-    sed "s/^last_report_at: .*/last_report_at: \"$REPORT_NOW\"/" "$STATE_FILE" > "$TEMP_FILE2"
-    mv "$TEMP_FILE2" "$STATE_FILE"
+    TEMP_FILE2="${STATE_FILE}.rpt.$$"
+    sed "s/^last_report_at: .*/last_report_at: \"$REPORT_NOW\"/" "$STATE_FILE" > "$TEMP_FILE2" && mv "$TEMP_FILE2" "$STATE_FILE"
   else
-    # Add last_report_at before the closing ---
-    TEMP_FILE2="${STATE_FILE}.tmp2.$$"
+    TEMP_FILE2="${STATE_FILE}.rpt.$$"
     sed "0,/^---$/! { /^---$/i\\
 last_report_at: \"$REPORT_NOW\"
 }" "$STATE_FILE" > "$TEMP_FILE2" 2>/dev/null && mv "$TEMP_FILE2" "$STATE_FILE" || true

package/.claude/skills/autonomous/scripts/setup-autonomous.sh

@@ -10,6 +10,7 @@ set -euo pipefail
 GOAL=""
 DURATION="4h"
 REPORT_TOPIC=""
+REPORT_CHANNEL="telegram"   # channel that owns this job; recovery note routes here (telegram|slack|whatsapp|imessage)
 LEVEL_UP="false"
 TASKS=""
 COMPLETION_PROMISE=""
@@ -29,6 +30,10 @@ while [[ $# -gt 0 ]]; do
       REPORT_TOPIC="$2"
       shift 2
       ;;
+    --report-channel)
+      REPORT_CHANNEL="$2"
+      shift 2
+      ;;
     --level-up)
       LEVEL_UP="true"
       shift
@@ -88,10 +93,51 @@ if [[ -z "$COMPLETION_PROMISE" ]]; then
   COMPLETION_PROMISE="ALL_TASKS_COMPLETE"
 fi
 
-# Create state file
+# ── Multi-session start gate: concurrency cap + quota (refuse-new) ──
+# Primary check is the server (precise active-count + QuotaTracker). If the
+# server is unreachable, fall back to a local file-count cap so the cap still
+# holds. Starting/restarting THIS topic's own job is always allowed.
+if [[ -n "$REPORT_TOPIC" ]]; then
+  PORT=$(python3 -c "import json;print(json.load(open('.instar/config.json')).get('port',4040))" 2>/dev/null || echo 4040)
+  AUTH=$(python3 -c "import json;print(json.load(open('.instar/config.json')).get('authToken',''))" 2>/dev/null || echo "")
+  CAN_START=$(curl -s -m 3 -H "Authorization: Bearer $AUTH" "http://localhost:${PORT}/autonomous/can-start?priority=medium" 2>/dev/null || echo "")
+  ALLOWED=$(printf '%s' "$CAN_START" | python3 -c "import sys,json
+try: print(json.load(sys.stdin).get('allowed'))
+except Exception: print('unknown')" 2>/dev/null || echo "unknown")
+  ALREADY_RUNNING="false"
+  [[ -f ".instar/autonomous/${REPORT_TOPIC}.local.md" ]] && ALREADY_RUNNING="true"
+  if [[ "$ALLOWED" == "False" ]] && [[ "$ALREADY_RUNNING" != "true" ]]; then
+    REASON=$(printf '%s' "$CAN_START" | python3 -c "import sys,json
+try: print(json.load(sys.stdin).get('reason',''))
+except Exception: print('')" 2>/dev/null || echo "")
+    echo "❌ Autonomous start refused: ${REASON:-cap or quota}" >&2
+    echo "   Stop a running job (POST /autonomous/sessions/<topic>/stop) or raise autonomousSessions.maxConcurrent." >&2
+    exit 1
+  fi
+  if [[ "$ALLOWED" == "unknown" ]] && [[ "$ALREADY_RUNNING" != "true" ]]; then
+    MAX_CONCURRENT=$(python3 -c "import json;print((json.load(open('.instar/config.json')).get('autonomousSessions') or {}).get('maxConcurrent',5))" 2>/dev/null || echo 5)
+    COUNT=$(ls .instar/autonomous/*.local.md 2>/dev/null | grep -cv "/${REPORT_TOPIC}\.local\.md$")
+    COUNT=${COUNT:-0}
+    if [[ "$COUNT" =~ ^[0-9]+$ ]] && [[ "$MAX_CONCURRENT" =~ ^[0-9]+$ ]] && [[ $COUNT -ge $MAX_CONCURRENT ]]; then
+      echo "❌ Autonomous start refused: concurrency cap reached ($COUNT/$MAX_CONCURRENT) [server unreachable; local check]." >&2
+      exit 1
+    fi
+  fi
+fi
+
+# Create state file. Multi-session: each topic gets its own state file at
+# .instar/autonomous/<topicId>.local.md so multiple topics run concurrent
+# autonomous jobs without collision. With no report topic, fall back to the
+# legacy single-file path (one-at-a-time, back-compat).
 mkdir -p .instar
+if [[ -n "$REPORT_TOPIC" ]]; then
+  mkdir -p .instar/autonomous
+  STATE_PATH=".instar/autonomous/${REPORT_TOPIC}.local.md"
+else
+  STATE_PATH=".instar/autonomous-state.local.md"
+fi
 
-cat > .instar/autonomous-state.local.md <<EOF
+cat > "$STATE_PATH" <<EOF
 ---
 active: true
 iteration: 1
@@ -102,6 +148,7 @@ duration_seconds: $DURATION_SECONDS
 started_at: "$STARTED_AT"
 end_at: "$END_AT"
 report_topic: "$REPORT_TOPIC"
+report_channel: "$REPORT_CHANNEL"
 report_interval: "$REPORT_INTERVAL"
 last_report_at: ""
 level_up: $LEVEL_UP

package/dist/core/AutonomousSessions.d.ts

@@ -0,0 +1,66 @@
+/**
+ * AutonomousSessions — multi-session autonomy control surface.
+ *
+ * Each autonomous job has its own state file at
+ * `<stateDir>/autonomous/<topicId>.local.md`. A legacy single-file job at
+ * `<stateDir>/autonomous-state.local.md` is also recognized for back-compat.
+ *
+ * This module is the read/control layer over those files: list active jobs,
+ * enforce the concurrency cap + quota at start, and stop jobs (all or one).
+ * The stop hook (`autonomous-stop-hook.sh`) is the per-session enforcer; this
+ * module is what the server routes, the start path, and the stop-everything
+ * path call. It never traps a session itself — it only reports and clears state.
+ */
+import type { JobPriority } from './types.js';
+/** Default concurrent autonomous-job cap when config doesn't specify one. */
+export declare const DEFAULT_MAX_CONCURRENT_AUTONOMOUS = 5;
+export interface AutonomousJobSummary {
+    topic: string | null;
+    file: string;
+    active: boolean;
+    paused: boolean;
+    goal: string | null;
+    iteration: number | null;
+    startedAt: string | null;
+    reportChannel: string | null;
+}
+/** All autonomous jobs (per-topic files + a legacy single file if present). */
+export declare function listAutonomousJobs(stateDir: string): AutonomousJobSummary[];
+/** Active (and not paused) autonomous jobs — what counts against the cap. */
+export declare function activeAutonomousJobs(stateDir: string): AutonomousJobSummary[];
+export interface CanStartDeps {
+    stateDir: string;
+    maxConcurrent: number;
+    quotaCanStart?: (priority?: JobPriority) => {
+        allowed: boolean;
+        reason: string;
+    };
+    priority?: JobPriority;
+}
+export interface CanStartResult {
+    allowed: boolean;
+    reason: string;
+    activeCount: number;
+    maxConcurrent: number;
+}
+/**
+ * Decide whether a new autonomous job may start: concurrency cap first
+ * (refuse-new at the cap), then quota (refuse-new under budget pressure).
+ * Never preempts a running job — that's the pause path, handled elsewhere.
+ */
+export declare function canStartAutonomousJob(deps: CanStartDeps): CanStartResult;
+/** Stop exactly one topic's job (removes its state file). Returns true if removed. */
+export declare function stopAutonomousTopic(stateDir: string, topic: string): boolean;
+export interface StopAllResult {
+    stoppedTopics: string[];
+    stoppedLegacy: boolean;
+}
+/**
+ * Stop every autonomous job. Removes all per-topic files + the legacy file and
+ * writes the emergency-stop flag so any session whose hook fires before its file
+ * is gone also stands down. The flag is the belt; removing files is the suspenders.
+ */
+export declare function stopAllAutonomousJobs(stateDir: string): StopAllResult;
+/** Pause one topic's job (hook will allow exit until resumed). Returns true if updated. */
+export declare function pauseAutonomousTopic(stateDir: string, topic: string): boolean;
+//# sourceMappingURL=AutonomousSessions.d.ts.map

package/dist/core/AutonomousSessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AutonomousSessions.d.ts","sourceRoot":"","sources":["../../src/core/AutonomousSessions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG9C,6EAA6E;AAC7E,eAAO,MAAM,iCAAiC,IAAI,CAAC;AAEnD,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAmCD,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,oBAAoB,EAAE,CAmB3E;AAED,6EAA6E;AAC7E,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,oBAAoB,EAAE,CAE7E;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,CAAC,QAAQ,CAAC,EAAE,WAAW,KAAK;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACjF,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,YAAY,GAAG,cAAc,CAmBxE;AAED,sFAAsF;AACtF,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAO5E;AAED,MAAM,WAAW,aAAa;IAC5B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,aAAa,EAAE,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,CAwBrE;AAED,2FAA2F;AAC3F,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAW7E"}