instar 1.3.305 → 1.3.307

package/src/scaffold/templates/jobs/instar/mentor-onboarding.md

@@ -22,17 +22,20 @@ That keeps the structural two-hats enforcement in code, not in this prompt.
 
 Do exactly this:
 
-1. POST to `http://localhost:${PORT}/mentor/tick` with the bearer token:
-   `curl -s -X POST -H "Authorization: Bearer $AUTH" http://localhost:${PORT}/mentor/tick`
+1. Resolve auth context:
+   `AUTH="${INSTAR_AUTH_TOKEN:-$(python3 -c "import json; v=json.load(open('.instar/config.json')).get('authToken',''); print(v if isinstance(v, str) else '')" 2>/dev/null)}"; AGENT_ID="${INSTAR_AGENT_ID:-$(python3 -c "import json; print(json.load(open('.instar/config.json')).get('projectName',''))" 2>/dev/null)}"; PORT="${INSTAR_PORT:-4042}"`
 
-2. Read the JSON result. It will be one of:
+2. POST to `http://localhost:${PORT}/mentor/tick` with the bearer token:
+   `curl -s -X POST -H "Authorization: Bearer $AUTH" -H "X-Instar-AgentId: $AGENT_ID" http://localhost:${PORT}/mentor/tick`
+
+3. Read the JSON result. It will be one of:
    - `{"ran":false,"reason":"disabled"}` — the mentor is off (the default). Nothing to do; stop.
    - `{"ran":false,"reason":"budget"|"unsafe-window"|"canary-failed"}` — it correctly skipped this
      tick. Stop; the next heartbeat will try again.
    - `{"ran":true,...}` — a mentor tick ran. Note `leakDetected` and `observationsWritten` briefly,
      then stop.
 
-3. Do NOT do any mentoring work yourself in this session, do NOT read the mentee's logs or code,
+4. Do NOT do any mentoring work yourself in this session, do NOT read the mentee's logs or code,
    and do NOT send the mentee any message — the in-process tick owns all of that. You are only the
    timer that pokes it. Then exit.
 

package/src/scaffold/templates/jobs/instar/org-intent-drift-audit.md

@@ -20,13 +20,15 @@ The job:
 
 1. Verify the prerequisites. The drift audit only makes sense when `.instar/ORG-INTENT.md` is present AND the Coherence Gate has accumulated at least 5 review entries in the last 7 days. If either condition isn't met, send a short Telegram message saying so and exit — there's nothing to audit yet.
 
-2. Call the drift digest endpoint: `curl -H "Authorization: Bearer $AUTH" "http://localhost:$PORT/intent/org/drift?lookbackDays=7"`. The response is a structured analysis: overall block rate, per-reviewer breakdown, half-window trend comparison (first half vs second half block rate), cross-reference against ORG-INTENT constraints / goals / values, and a single `trend` label (`stable` | `rising` | `concerning` | `insufficient-data` | `no-org-intent`).
+2. Set auth context: `AUTH="${INSTAR_AUTH_TOKEN:-$(python3 -c "import json; v=json.load(open('.instar/config.json')).get('authToken',''); print(v if isinstance(v, str) else '')" 2>/dev/null)}"; AGENT_ID="${INSTAR_AGENT_ID:-$(python3 -c "import json; print(json.load(open('.instar/config.json')).get('projectName',''))" 2>/dev/null)}"; PORT="${INSTAR_PORT:-4042}"`
 
-3. If `trend === 'stable'` or `trend === 'insufficient-data'` or `trend === 'no-org-intent'`, stay silent. Most weeks should be silent — that means the agent is staying aligned with the organizational intent. The `shouldSurface` field in the response will be `false` in these cases.
+3. Call the drift digest endpoint: `curl -H "Authorization: Bearer $AUTH" -H "X-Instar-AgentId: $AGENT_ID" "http://localhost:$PORT/intent/org/drift?lookbackDays=7"`. The response is a structured analysis: overall block rate, per-reviewer breakdown, half-window trend comparison (first half vs second half block rate), cross-reference against ORG-INTENT constraints / goals / values, and a single `trend` label (`stable` | `rising` | `concerning` | `insufficient-data` | `no-org-intent`).
 
-4. If `trend === 'rising'` or `trend === 'concerning'`, surface the drift via Telegram. The response includes a `summary` field (plain-English one-paragraph framing) and a `suggestions` array (specific next actions). Compose a conversational message that leads with the trend and what changed: "Block rate climbed from 4% to 12% in the second half of the week — most flags came from value-alignment." Then list the most-flagged reviewer dimensions. Then surface the top 1-2 suggestions. Keep it under 600 characters. Plain English. No raw JSON.
+4. If `trend === 'stable'` or `trend === 'insufficient-data'` or `trend === 'no-org-intent'`, stay silent. Most weeks should be silent — that means the agent is staying aligned with the organizational intent. The `shouldSurface` field in the response will be `false` in these cases.
 
-5. After surfacing (or not), the audit is done. No state to persist — the gate's own review history is the canonical store.
+5. If `trend === 'rising'` or `trend === 'concerning'`, surface the drift via Telegram. The response includes a `summary` field (plain-English one-paragraph framing) and a `suggestions` array (specific next actions). Compose a conversational message that leads with the trend and what changed: "Block rate climbed from 4% to 12% in the second half of the week — most flags came from value-alignment." Then list the most-flagged reviewer dimensions. Then surface the top 1-2 suggestions. Keep it under 600 characters. Plain English. No raw JSON.
+
+6. After surfacing (or not), the audit is done. No state to persist — the gate's own review history is the canonical store.
 
 IMPORTANT: This is a guardian job, not a doer. Surface the drift and where it might be coming from. Don't try to fix it autonomously. The fix work — if any — is a deliberate update to `.instar/ORG-INTENT.md` constraints, or a configuration change to the gate, or an operator-level decision about whether the agent's behavior is actually drifting or whether the constraints need updating. Surface; don't fix.
 

package/src/scaffold/templates/jobs/instar/overseer-development.md

@@ -14,7 +14,10 @@ unrestrictedTools: true
 ---
 You are a Category Overseer for the DEVELOPMENT category. Your job is to review development-focused jobs.
 
-1. Fetch the category report: curl -H "Authorization: Bearer $AUTH" http://localhost:${INSTAR_PORT:-4042}/jobs/category-report/development?sinceHours=48
+AUTH="${INSTAR_AUTH_TOKEN:-}"
+AGENT_ID="${INSTAR_AGENT_ID:-}"
+
+1. Fetch the category report: curl -H "Authorization: Bearer $AUTH" -H "X-Instar-AgentId: $AGENT_ID" http://localhost:${INSTAR_PORT:-4042}/jobs/category-report/development?sinceHours=48
 2. Analyze:
    - Are development jobs consuming appropriate resources for their value?
    - Are there CI/testing patterns that could be automated?

package/src/scaffold/templates/jobs/instar/overseer-guardian.md

@@ -14,7 +14,10 @@ unrestrictedTools: true
 ---
 You are a Category Overseer for the GUARDIAN category. Your job is to review all guardian/monitoring jobs and assess the health of the monitoring system itself.
 
-1. Fetch the category report: curl -H "Authorization: Bearer $AUTH" http://localhost:${INSTAR_PORT:-4042}/jobs/category-report/guardian?sinceHours=24
+AUTH="${INSTAR_AUTH_TOKEN:-}"
+AGENT_ID="${INSTAR_AGENT_ID:-}"
+
+1. Fetch the category report: curl -H "Authorization: Bearer $AUTH" -H "X-Instar-AgentId: $AGENT_ID" http://localhost:${INSTAR_PORT:-4042}/jobs/category-report/guardian?sinceHours=24
 2. Analyze the report for:
    - Jobs with high failure rates or consecutive failures
    - Jobs that are being skipped excessively (especially for quota reasons)

package/src/scaffold/templates/jobs/instar/overseer-infrastructure.md

@@ -14,7 +14,10 @@ unrestrictedTools: true
 ---
 You are a Category Overseer for the INFRASTRUCTURE category. Your job is to review infrastructure/plumbing jobs.
 
-1. Fetch the category report: curl -H "Authorization: Bearer $AUTH" http://localhost:${INSTAR_PORT:-4042}/jobs/category-report/infrastructure?sinceHours=48
+AUTH="${INSTAR_AUTH_TOKEN:-}"
+AGENT_ID="${INSTAR_AGENT_ID:-}"
+
+1. Fetch the category report: curl -H "Authorization: Bearer $AUTH" -H "X-Instar-AgentId: $AGENT_ID" http://localhost:${INSTAR_PORT:-4042}/jobs/category-report/infrastructure?sinceHours=48
 2. Analyze:
    - Is git-sync succeeding? Any merge conflicts or divergence?
    - Is dashboard-link-refresh keeping links current? Could it run less often?

package/src/scaffold/templates/jobs/instar/overseer-learning.md

@@ -14,7 +14,10 @@ unrestrictedTools: true
 ---
 You are a Category Overseer for the LEARNING category. Your job is to review all evolution/learning jobs and assess whether the learning pipeline is producing genuine value.
 
-1. Fetch the category report: curl -H "Authorization: Bearer $AUTH" http://localhost:${INSTAR_PORT:-4042}/jobs/category-report/learning?sinceHours=48
+AUTH="${INSTAR_AUTH_TOKEN:-}"
+AGENT_ID="${INSTAR_AGENT_ID:-}"
+
+1. Fetch the category report: curl -H "Authorization: Bearer $AUTH" -H "X-Instar-AgentId: $AGENT_ID" http://localhost:${INSTAR_PORT:-4042}/jobs/category-report/learning?sinceHours=48
 2. Analyze:
    - Are evolution proposals being generated AND accepted? What's the accept/reject ratio?
    - Is insight-harvest finding novel insights or recycling stale ones?

package/src/scaffold/templates/jobs/instar/overseer-maintenance.md

@@ -14,7 +14,10 @@ unrestrictedTools: true
 ---
 You are a Category Overseer for the MAINTENANCE category. Your job is to review all housekeeping/maintenance jobs and ensure they're keeping the system clean.
 
-1. Fetch the category report: curl -H "Authorization: Bearer $AUTH" http://localhost:${INSTAR_PORT:-4042}/jobs/category-report/maintenance?sinceHours=48
+AUTH="${INSTAR_AUTH_TOKEN:-}"
+AGENT_ID="${INSTAR_AGENT_ID:-}"
+
+1. Fetch the category report: curl -H "Authorization: Bearer $AUTH" -H "X-Instar-AgentId: $AGENT_ID" http://localhost:${INSTAR_PORT:-4042}/jobs/category-report/maintenance?sinceHours=48
 2. Analyze:
    - Is memory-hygiene actually reducing stale entries, or finding nothing each run?
    - Is project-map-refresh keeping the map accurate? How often does it find drift?

package/src/scaffold/templates/jobs/instar/release-readiness-check.md

@@ -18,8 +18,9 @@ mcpAccess: none
 Run the release-readiness check once. This is a mechanical, near-silent watchdog — do NOT message the user.
 
 AUTH=$(python3 -c "import json; print(json.load(open('.instar/config.json')).get('authToken',''))" 2>/dev/null)
+AGENT_ID="${INSTAR_AGENT_ID:-$(python3 -c "import json; print(json.load(open('.instar/config.json')).get('projectName',''))" 2>/dev/null)}"
 
 1. Trigger one evaluation tick:
-   curl -s -X POST http://localhost:${INSTAR_PORT:-4042}/release-readiness/tick -H "Authorization: Bearer $AUTH"
+   curl -s -X POST http://localhost:${INSTAR_PORT:-4042}/release-readiness/tick -H "Authorization: Bearer $AUTH" -H "X-Instar-AgentId: $AGENT_ID"
 2. That endpoint runs the ReleaseReadinessSentinel: it fetches canonical main, checks whether unreleased feature/fix work is piling up while publishing is blocked, and (only above the age threshold) raises a single deduped Attention item. All transitions are written to logs/sentinel-events.jsonl.
 3. Exit silently. The sentinel owns all signalling (Attention queue) — this job is just the cadence. Do not relay anything to Telegram; do not summarize. If the curl fails, that is itself recorded by the server; do not retry-flood.

package/src/templates/hooks/compaction-recovery.sh

@@ -14,6 +14,11 @@
 # matched on "compaction".
 
 INSTAR_DIR="${CLAUDE_PROJECT_DIR:-.}/.instar"
+CONFIG_FILE="$INSTAR_DIR/config.json"
+AGENT_ID="${INSTAR_AGENT_ID:-}"
+if [ -z "$AGENT_ID" ] && [ -f "$CONFIG_FILE" ]; then
+  AGENT_ID=$(python3 -c "import json; print(json.load(open('$CONFIG_FILE')).get('projectName',''))" 2>/dev/null)
+fi
 
 echo "=== COMPACTION RECOVERY — IDENTITY RESTORATION ==="
 echo ""
@@ -36,7 +41,7 @@ if [ -f "$INSTAR_DIR/soul.md" ]; then
     # Check integrity via server if available
     SOUL_INTEGRITY="valid"
     if [ -n "$PORT" ] && [ -n "$AUTH_TOKEN" ]; then
-      INTEGRITY_CHECK=$(curl -s -H "Authorization: Bearer ${AUTH_TOKEN}" \
+      INTEGRITY_CHECK=$(curl -s -H "Authorization: Bearer ${AUTH_TOKEN}" -H "X-Instar-AgentId: ${AGENT_ID}" \
         "http://localhost:${PORT}/identity/soul/integrity" 2>/dev/null)
       SOUL_INTEGRITY=$(echo "$INTEGRITY_CHECK" | python3 -c "
 import sys, json
@@ -180,7 +185,7 @@ if [ -f "$CONFIG_FILE" ]; then
     if [ -z "$AUTH_TOKEN" ]; then
       AUTH_TOKEN=$(python3 -c "import json; v=json.load(open('$CONFIG_FILE')).get('authToken',''); print(v if isinstance(v, str) else '')" 2>/dev/null)
     fi
-    FEATURES_JSON=$(curl -s -H "Authorization: Bearer ${AUTH_TOKEN}" \
+    FEATURES_JSON=$(curl -s -H "Authorization: Bearer ${AUTH_TOKEN}" -H "X-Instar-AgentId: ${AGENT_ID}" \
       "http://localhost:${PORT}/features/summary" 2>/dev/null)
     if [ -n "$FEATURES_JSON" ]; then
       DISCOVERY_STATE=$(echo "$FEATURES_JSON" | python3 -c "
@@ -255,7 +260,7 @@ if [ -f "$CONFIG_FILE" ]; then
       AUTH_TOKEN=$(python3 -c "import json; v=json.load(open('$CONFIG_FILE')).get('authToken',''); print(v if isinstance(v, str) else '')" 2>/dev/null)
     fi
         SLACK_MSGS=$(curl -s \
-          -H "Authorization: Bearer ${AUTH_TOKEN}" \
+          -H "Authorization: Bearer ${AUTH_TOKEN}" -H "X-Instar-AgentId: ${AGENT_ID}" \
           "http://localhost:${PORT}/slack/channels/${SLACK_CHANNEL}/messages?limit=20" 2>/dev/null)
 
         echo "$SLACK_MSGS" | python3 -c "
@@ -358,7 +363,7 @@ except Exception:
     fi
         if [ -n "$AUTH_TOKEN" ]; then
           RECENT_MSGS=$(curl -s \
-            -H "Authorization: Bearer ${AUTH_TOKEN}" \
+            -H "Authorization: Bearer ${AUTH_TOKEN}" -H "X-Instar-AgentId: ${AGENT_ID}" \
             "http://localhost:${PORT}/telegram/topics/${TOPIC_FOR_CONTEXT}/messages?limit=15" 2>/dev/null)
         else
           RECENT_MSGS=$(curl -s \
@@ -433,7 +438,7 @@ if [ -f "$CONFIG_FILE" ]; then
     if [ -z "$AUTH_TOKEN" ]; then
       AUTH_TOKEN=$(python3 -c "import json; v=json.load(open('$CONFIG_FILE')).get('authToken',''); print(v if isinstance(v, str) else '')" 2>/dev/null)
     fi
-    WORKING_MEM=$(curl -s -H "Authorization: Bearer ${AUTH_TOKEN}" \
+    WORKING_MEM=$(curl -s -H "Authorization: Bearer ${AUTH_TOKEN}" -H "X-Instar-AgentId: ${AGENT_ID}" \
       "http://localhost:${PORT}/context/working-memory?prompt=compaction-recovery&limit=5" 2>/dev/null)
     if [ -n "$WORKING_MEM" ]; then
       CONTEXT=$(echo "$WORKING_MEM" | python3 -c "
@@ -472,7 +477,7 @@ if [ -f "$CONFIG_FILE" ] && command -v tmux >/dev/null 2>&1; then
       AUTH_TOKEN=$(python3 -c "import json; v=json.load(open('$CONFIG_FILE')).get('authToken',''); print(v if isinstance(v, str) else '')" 2>/dev/null)
     fi
     curl -s -m 2 -X POST \
-      -H "Authorization: Bearer ${AUTH_TOKEN}" \
+      -H "Authorization: Bearer ${AUTH_TOKEN}" -H "X-Instar-AgentId: ${AGENT_ID}" \
       -H "Content-Type: application/json" \
       -d "{\"sessionName\":\"${TMUX_SESSION}\"}" \
       "http://localhost:${PORT}/internal/compaction-resume" >/dev/null 2>&1 &

package/src/templates/hooks/session-start.sh

@@ -34,10 +34,15 @@ AUTH_TOKEN="${INSTAR_AUTH_TOKEN:-}"
 if [ -z "$AUTH_TOKEN" ]; then
   AUTH_TOKEN=$(python3 -c "import json; v=json.load(open('$CONFIG_FILE')).get('authToken',''); print(v if isinstance(v, str) else '')" 2>/dev/null)
 fi
+AGENT_ID="${INSTAR_AGENT_ID:-}"
+if [ -z "$AGENT_ID" ]; then
+  AGENT_ID=$(python3 -c "import json; print(json.load(open('$CONFIG_FILE')).get('projectName',''))" 2>/dev/null)
+fi
 
 # Check if server is alive
 HEALTH=$(curl -s -o /dev/null -w "%{http_code}" \
   -H "Authorization: Bearer ${AUTH_TOKEN}" \
+  -H "X-Instar-AgentId: ${AGENT_ID}" \
   "http://localhost:${PORT}/health" 2>/dev/null)
 if [ "$HEALTH" != "200" ]; then
   exit 0
@@ -50,15 +55,17 @@ curl -s -X POST "http://localhost:${PORT}/scope-coherence/reset" -o /dev/null 2>
 # Record session start for reflection metrics (usage-based reflection trigger)
 curl -s -X POST "http://localhost:${PORT}/reflection/session-start" \
   -H "Authorization: Bearer ${AUTH_TOKEN}" \
+  -H "X-Instar-AgentId: ${AGENT_ID}" \
   -H "Content-Type: application/json" -o /dev/null 2>/dev/null || true
 
 # Reset homeostasis state for new session (work-velocity awareness)
 curl -s -X POST "http://localhost:${PORT}/homeostasis/reset" \
   -H "Authorization: Bearer ${AUTH_TOKEN}" \
+  -H "X-Instar-AgentId: ${AGENT_ID}" \
   -H "Content-Type: application/json" -o /dev/null 2>/dev/null || true
 
 # Check reflection metrics — usage-based reflection suggestion
-REFLECTION_CHECK=$(curl -s -H "Authorization: Bearer ${AUTH_TOKEN}" \
+REFLECTION_CHECK=$(curl -s -H "Authorization: Bearer ${AUTH_TOKEN}" -H "X-Instar-AgentId: ${AGENT_ID}" \
   "http://localhost:${PORT}/reflection/metrics" 2>/dev/null)
 if [ -n "$REFLECTION_CHECK" ]; then
   SUGGESTED=$(echo "$REFLECTION_CHECK" | python3 -c "import sys,json; print(json.load(sys.stdin).get('suggested',False))" 2>/dev/null)
@@ -166,7 +173,7 @@ if [ -n "$JOB_SLUG" ]; then
   QUERY_URL="${QUERY_URL}&jobSlug=${JOB_SLUG_ENCODED}"
 fi
 
-WORKING_MEM=$(curl -s -H "Authorization: Bearer ${AUTH_TOKEN}" "$QUERY_URL" 2>/dev/null)
+WORKING_MEM=$(curl -s -H "Authorization: Bearer ${AUTH_TOKEN}" -H "X-Instar-AgentId: ${AGENT_ID}" "$QUERY_URL" 2>/dev/null)
 
 if [ -z "$WORKING_MEM" ]; then
   exit 0
@@ -199,7 +206,7 @@ except Exception:
 # Active commitments injection (PROMISE-BEACON-SPEC Round 3 #7).
 # Surfaces beacon-watched pending commitments so the agent can self-regulate
 # pacing across compaction. Capped server-side at 20 entries.
-ACTIVE_COMMITMENTS=$(curl -s -H "Authorization: Bearer ${AUTH_TOKEN}" \
+ACTIVE_COMMITMENTS=$(curl -s -H "Authorization: Bearer ${AUTH_TOKEN}" -H "X-Instar-AgentId: ${AGENT_ID}" \
   "http://localhost:${PORT}/commitments/active-context" 2>/dev/null)
 if [ -n "$ACTIVE_COMMITMENTS" ]; then
   python3 -c "
@@ -326,6 +333,7 @@ if [ -n "$PORT" ] && [ -n "$AUTH_TOKEN" ]; then
 
   EVAL_RESULT=$(curl -s --max-time 6 -X POST \
     -H "Authorization: Bearer ${AUTH_TOKEN}" \
+    -H "X-Instar-AgentId: ${AGENT_ID}" \
     -H "Content-Type: application/json" \
     "http://localhost:${PORT}/features/evaluate-context" \
     -d "{\"topicCategory\":\"${TOPIC_LABEL}\",\"conversationIntent\":\"${INTENT}\",\"problemCategories\":[],\"autonomyProfile\":\"collaborative\",\"enabledFeatures\":[]}" \

package/src/templates/hooks/slack-channel-context.sh

@@ -23,6 +23,7 @@ fi
 # Get port and auth from config
 PORT="${INSTAR_PORT:-}"
 AUTH=""
+AGENT_ID="${INSTAR_AGENT_ID:-}"
 
 if [ -f ".instar/config.json" ]; then
   if [ -z "$PORT" ]; then
@@ -37,6 +38,9 @@ if [ -f ".instar/config.json" ]; then
   if [ -z "$AUTH" ]; then
     AUTH=$(python3 -c "import json; v=json.load(open('.instar/config.json')).get('authToken',''); print(v if isinstance(v, str) else '')" 2>/dev/null)
   fi
+  if [ -z "$AGENT_ID" ]; then
+    AGENT_ID=$(python3 -c "import json; print(json.load(open('.instar/config.json')).get('projectName',''))" 2>/dev/null)
+  fi
 fi
 
 PORT="${PORT:-4042}"
@@ -49,6 +53,7 @@ fi
 # Fetch channel history from ring buffer cache
 MESSAGES=$(curl -sf \
   ${AUTH:+-H "Authorization: Bearer $AUTH"} \
+  ${AGENT_ID:+-H "X-Instar-AgentId: $AGENT_ID"} \
   "http://localhost:${PORT}/slack/channels/${CHANNEL_ID}/messages?limit=30" 2>/dev/null) || exit 0
 
 # Format thread history for session context

package/src/templates/hooks/telegram-topic-context.sh

@@ -66,11 +66,16 @@ AUTH_TOKEN="${INSTAR_AUTH_TOKEN:-}"
 if [ -z "$AUTH_TOKEN" ] && [ -f "$CONFIG_FILE" ]; then
   AUTH_TOKEN=$(python3 -c "import json; v=json.load(open('$CONFIG_FILE')).get('authToken',''); print(v if isinstance(v, str) else '')" 2>/dev/null)
 fi
+AGENT_ID="${INSTAR_AGENT_ID:-}"
+if [ -z "$AGENT_ID" ] && [ -f "$CONFIG_FILE" ]; then
+  AGENT_ID=$(python3 -c "import json; print(json.load(open('$CONFIG_FILE')).get('projectName',''))" 2>/dev/null)
+fi
 
 # Fetch recent messages for this topic
 if [ -n "$AUTH_TOKEN" ]; then
   RECENT_MSGS=$(curl -s \
     -H "Authorization: Bearer ${AUTH_TOKEN}" \
+    -H "X-Instar-AgentId: ${AGENT_ID}" \
     "http://localhost:${PORT}/telegram/topics/${TOPIC_ID}/messages?limit=30" 2>/dev/null)
 else
   RECENT_MSGS=$(curl -s \
@@ -85,6 +90,7 @@ TOPIC_BRIEFING=""
 if [ -n "$AUTH_TOKEN" ]; then
   TOPIC_BRIEFING=$(curl -s --max-time 2 \
     -H "Authorization: Bearer ${AUTH_TOKEN}" \
+    -H "X-Instar-AgentId: ${AGENT_ID}" \
     "http://localhost:${PORT}/topic-intent/${TOPIC_ID}/briefing" 2>/dev/null)
 else
   TOPIC_BRIEFING=$(curl -s --max-time 2 \

package/src/templates/scripts/emit-session-clock.sh

@@ -13,7 +13,7 @@
 #     computed) values. The caller (autonomous-stop-hook) has already resolved
 #     the record + computed elapsed/remaining, so there is NO re-resolution —
 #     the injected clock can never disagree with the hook's expiry verdict.
-#   query <topic> <port> <auth>
+#   query <topic> <port> <auth> [agent-id]
 #     Curls GET /session/clock?topic=<topic> and prints the SESSION CLOCK line
 #     for the first active session (or nothing if none / server unreachable).
 
@@ -42,11 +42,11 @@ case "$MODE" in
     render_line "${1:-}" "${2:-}" "${3:-0}" "${4:-}" "${5:-}"
     ;;
   query)
-    TOPIC="${1:-}"; PORT="${2:-}"; AUTH="${3:-}"
+    TOPIC="${1:-}"; PORT="${2:-}"; AUTH="${3:-}"; AGENT_ID="${4:-${INSTAR_AGENT_ID:-}}"
     [ -z "$PORT" ] && exit 0
     URL="http://localhost:${PORT}/session/clock"
     [ -n "$TOPIC" ] && URL="${URL}?topic=${TOPIC}"
-    RESP=$(curl -s --max-time 3 -H "Authorization: Bearer ${AUTH}" "$URL" 2>/dev/null)
+    RESP=$(curl -s --max-time 3 -H "Authorization: Bearer ${AUTH}" -H "X-Instar-AgentId: ${AGENT_ID}" "$URL" 2>/dev/null)
     [ -z "$RESP" ] && exit 0
     printf '%s' "$RESP" | python3 -c "
 import sys, json

package/src/templates/scripts/imessage-reply.sh

@@ -47,9 +47,13 @@ PORT="${INSTAR_PORT:-4042}"
 # string-type guard so the { "secret": true } placeholder produced by
 # SecretMigrator cannot leak through as a bogus Bearer.
 AUTH_TOKEN="${INSTAR_AUTH_TOKEN:-}"
+AGENT_ID="${INSTAR_AGENT_ID:-}"
 if [ -z "$AUTH_TOKEN" ] && [ -f ".instar/config.json" ]; then
   AUTH_TOKEN=$(python3 -c "import json; v=json.load(open('.instar/config.json')).get('authToken',''); print(v if isinstance(v, str) else '')" 2>/dev/null)
 fi
+if [ -z "$AGENT_ID" ] && [ -f ".instar/config.json" ]; then
+  AGENT_ID=$(python3 -c "import json; print(json.load(open('.instar/config.json')).get('projectName',''))" 2>/dev/null)
+fi
 
 # Escape message for JSON
 JSON_MSG=$(printf '%s' "$MSG" | python3 -c 'import sys,json; print(json.dumps(sys.stdin.read()))' 2>/dev/null)
@@ -67,12 +71,17 @@ AUTH_HEADER=""
 if [ -n "$AUTH_TOKEN" ]; then
   AUTH_HEADER="Authorization: Bearer ${AUTH_TOKEN}"
 fi
+AGENT_HEADER=""
+if [ -n "$AGENT_ID" ]; then
+  AGENT_HEADER="X-Instar-AgentId: ${AGENT_ID}"
+fi
 
 # ── Step 1: Validate with server BEFORE sending (get single-use token) ──
 
 VALIDATE_RESPONSE=$(curl -s -w "\n%{http_code}" \
   -X POST "http://localhost:${PORT}/imessage/validate-send/${ENCODED_RECIPIENT}" \
   ${AUTH_HEADER:+-H "$AUTH_HEADER"} \
+  ${AGENT_HEADER:+-H "$AGENT_HEADER"} \
   -H 'Content-Type: application/json' \
   -d "{\"text\":${JSON_MSG}}" 2>/dev/null)
 
@@ -140,6 +149,7 @@ fi
 
 curl -s -o /dev/null -w "" -X POST "http://localhost:${PORT}/imessage/reply/${ENCODED_RECIPIENT}" \
   ${AUTH_HEADER:+-H "$AUTH_HEADER"} \
+  ${AGENT_HEADER:+-H "$AGENT_HEADER"} \
   -H 'Content-Type: application/json' \
   -d "{\"text\":${JSON_MSG},\"sendToken\":\"${SEND_TOKEN}\"}" 2>/dev/null || \
   echo "Warning: server confirmation failed (message was sent)" >&2

package/src/templates/scripts/instar-watchdog.sh

@@ -328,9 +328,11 @@ escalate_via_peer() {
     # placeholder that SecretMigrator writes after externalizing the auth token:
     # `c.authToken || ''` would otherwise return the object itself (truthy)
     # which serializes to "[object Object]" — never a valid Bearer.
-    peer_meta=$("$node_bin" -e "const c=JSON.parse(require('fs').readFileSync(process.argv[1],'utf8'));const t=typeof c.authToken==='string'?c.authToken:'';process.stdout.write((c.port||'')+'\t'+t)" "$peer_dir/.instar/config.json" 2>/dev/null || true)
+    peer_meta=$("$node_bin" -e "const c=JSON.parse(require('fs').readFileSync(process.argv[1],'utf8'));const t=typeof c.authToken==='string'?c.authToken:'';process.stdout.write((c.port||'')+'\t'+t+'\t'+(c.projectName||''))" "$peer_dir/.instar/config.json" 2>/dev/null || true)
     peer_port="${peer_meta%%	*}"
-    peer_auth="${peer_meta##*	}"
+    peer_rest="${peer_meta#*	}"
+    peer_auth="${peer_rest%%	*}"
+    peer_agent_id="${peer_rest#*	}"
     [ -z "$peer_port" ] && continue
 
     health_code=$(curl -s -o /dev/null -w "%{http_code}" "http://localhost:${peer_port}/health" 2>/dev/null || echo "000")
@@ -356,6 +358,7 @@ JSONEOF
         resp_code=$(curl -s -o /dev/null -w "%{http_code}" \
           -X POST "http://localhost:${peer_port}/attention" \
           -H "Authorization: Bearer $peer_auth" \
+          -H "X-Instar-AgentId: $peer_agent_id" \
           -H "Content-Type: application/json" \
           -H "X-Instar-Request: 1" \
           -d "$payload" 2>/dev/null || echo "000")
@@ -385,6 +388,7 @@ JSONEOF
           resp_code=$(curl -s -o /dev/null -w "%{http_code}" \
             -X POST "http://localhost:${peer_port}/attention" \
             -H "Authorization: Bearer $peer_auth" \
+            -H "X-Instar-AgentId: $peer_agent_id" \
             -H "Content-Type: application/json" \
             -H "X-Instar-Request: 1" \
             -d "$safe_payload" 2>/dev/null || echo "000")
@@ -434,7 +438,7 @@ probe_server_identity() {
   local config_file="$project_dir/.instar/config.json"
   [ ! -r "$config_file" ] && return 0
 
-  local node_bin port auth_token
+  local node_bin port auth_token agent_id
   node_bin=$(resolve_node || true)
   [ -z "$node_bin" ] && return 0
 
@@ -447,9 +451,11 @@ probe_server_identity() {
   # auth token — `String(c.authToken || '')` would otherwise yield
   # "[object Object]" and the Bearer would be invalid.
   local meta
-  meta=$("$node_bin" -e "const c=JSON.parse(require('fs').readFileSync(process.argv[1],'utf8'));const t=process.env.INSTAR_AUTH_TOKEN||(typeof c.authToken==='string'?c.authToken:'');process.stdout.write(String(c.port||'')+'\t'+t)" "$config_file" 2>/dev/null || true)
+  meta=$("$node_bin" -e "const c=JSON.parse(require('fs').readFileSync(process.argv[1],'utf8'));const t=process.env.INSTAR_AUTH_TOKEN||(typeof c.authToken==='string'?c.authToken:'');process.stdout.write(String(c.port||'')+'\t'+t+'\t'+(c.projectName||''))" "$config_file" 2>/dev/null || true)
   port="${meta%%	*}"
-  auth_token="${meta##*	}"
+  rest="${meta#*	}"
+  auth_token="${rest%%	*}"
+  agent_id="${rest#*	}"
   # Lifeline-only agents have no port; treat as healthy from probe POV.
   [ -z "$port" ] && return 0
 
@@ -460,7 +466,7 @@ probe_server_identity() {
   local resp http_code body project_field auth_args
   auth_args=()
   if [ -n "$auth_token" ]; then
-    auth_args=(-H "Authorization: Bearer $auth_token")
+    auth_args=(-H "Authorization: Bearer $auth_token" -H "X-Instar-AgentId: $agent_id")
   fi
   resp=$(curl -sS --max-time 5 -w '\n%{http_code}' "${auth_args[@]}" "http://localhost:${port}/health" 2>/dev/null || echo $'\n000')
   http_code=$(echo "$resp" | tail -n1)

package/src/templates/scripts/secret-drop-retrieve.mjs

@@ -81,10 +81,12 @@ if (runMode && runCmd.length === 0) {
 // guard so the { "secret": true } placeholder produced by SecretMigrator
 // cannot leak through as a bogus Bearer.
 let authToken = process.env.INSTAR_AUTH_TOKEN || '';
+let agentId = process.env.INSTAR_AGENT_ID || '';
 let port;
 try {
   const config = JSON.parse(fs.readFileSync('.instar/config.json', 'utf-8'));
   if (!authToken && typeof config.authToken === 'string') authToken = config.authToken;
+  if (!agentId && typeof config.projectName === 'string') agentId = config.projectName;
   port = config.port;
 } catch (e) {
   if (!authToken) {
@@ -104,7 +106,10 @@ if (!resolvedPort) {
 const url = `http://localhost:${resolvedPort}/secrets/retrieve/${token}${consume ? '?consume=true' : ''}`;
 const res = await fetch(url, {
   method: 'POST',
-  headers: { 'Authorization': `Bearer ${authToken}` },
+  headers: {
+    'Authorization': `Bearer ${authToken}`,
+    ...(agentId ? { 'X-Instar-AgentId': agentId } : {}),
+  },
 });
 
 if (!res.ok) {
@@ -160,7 +165,10 @@ async function consumeSubmission() {
   try {
     await fetch(`http://localhost:${resolvedPort}/secrets/retrieve/${token}?consume=true`, {
       method: 'POST',
-      headers: { 'Authorization': `Bearer ${authToken}` },
+      headers: {
+        'Authorization': `Bearer ${authToken}`,
+        ...(agentId ? { 'X-Instar-AgentId': agentId } : {}),
+      },
     });
   } catch {
     // Non-fatal — the sliding/absolute-cap cleanup will reclaim it regardless.

package/src/templates/scripts/slack-reply.sh

@@ -38,6 +38,7 @@ fi
 # Get port from env or config
 PORT="${INSTAR_PORT:-}"
 AUTH=""
+AGENT_ID="${INSTAR_AGENT_ID:-}"
 
 if [ -f ".instar/config.json" ]; then
   if [ -z "$PORT" ]; then
@@ -52,6 +53,9 @@ if [ -f ".instar/config.json" ]; then
   if [ -z "$AUTH" ]; then
     AUTH=$(python3 -c "import json; v=json.load(open('.instar/config.json')).get('authToken',''); print(v if isinstance(v, str) else '')" 2>/dev/null)
   fi
+  if [ -z "$AGENT_ID" ]; then
+    AGENT_ID=$(python3 -c "import json; print(json.load(open('.instar/config.json')).get('projectName',''))" 2>/dev/null)
+  fi
 fi
 
 PORT="${PORT:-4042}"
@@ -68,6 +72,7 @@ RESPONSE=$(curl -s -w "\n%{http_code}" -X POST \
   "http://localhost:${PORT}/slack/reply/${CHANNEL_ID}" \
   -H "Content-Type: application/json" \
   ${AUTH:+-H "Authorization: Bearer $AUTH"} \
+  ${AGENT_ID:+-H "X-Instar-AgentId: $AGENT_ID"} \
   -d "{\"text\": ${ESCAPED}}")
 
 HTTP_CODE=$(echo "$RESPONSE" | tail -1)

package/src/templates/scripts/whatsapp-reply.sh

@@ -38,9 +38,13 @@ PORT="${INSTAR_PORT:-4040}"
 # string-type guard so the { "secret": true } placeholder produced by
 # SecretMigrator cannot leak through as a bogus Bearer.
 AUTH_TOKEN="${INSTAR_AUTH_TOKEN:-}"
+AGENT_ID="${INSTAR_AGENT_ID:-}"
 if [ -z "$AUTH_TOKEN" ] && [ -f ".instar/config.json" ]; then
   AUTH_TOKEN=$(python3 -c "import json; v=json.load(open('.instar/config.json')).get('authToken',''); print(v if isinstance(v, str) else '')" 2>/dev/null)
 fi
+if [ -z "$AGENT_ID" ] && [ -f ".instar/config.json" ]; then
+  AGENT_ID=$(python3 -c "import json; print(json.load(open('.instar/config.json')).get('projectName',''))" 2>/dev/null)
+fi
 
 # Escape for JSON
 JSON_MSG=$(printf '%s' "$MSG" | python3 -c 'import sys,json; print(json.dumps(sys.stdin.read()))' 2>/dev/null)
@@ -53,6 +57,7 @@ if [ -n "$AUTH_TOKEN" ]; then
   RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "http://localhost:${PORT}/whatsapp/send/${JID}" \
     -H 'Content-Type: application/json' \
     -H "Authorization: Bearer ${AUTH_TOKEN}" \
+    -H "X-Instar-AgentId: ${AGENT_ID}" \
     -d "{\"text\":${JSON_MSG}}")
 else
   RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "http://localhost:${PORT}/whatsapp/send/${JID}" \

package/upgrades/1.3.306.md

@@ -0,0 +1,22 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Built-in job, hook, and helper-script templates now include the agent identity header on authenticated local API calls. The scheduler and session launcher expose `INSTAR_AGENT_ID` alongside the existing local auth token so installed templates do not need to guess their identity.
+
+## What to Tell Your User
+
+Nothing user-visible. This quiets internal auth deprecation warnings from built-in jobs and hooks and keeps installed templates aligned with the stricter local auth contract.
+
+## Summary of New Capabilities
+
+- Job gates, script jobs, and spawned sessions receive `INSTAR_AGENT_ID`.
+- Built-in local API templates send `X-Instar-AgentId` with bearer auth.
+- A regression test scans shipped templates for bearer-only local API calls.
+
+## Evidence
+
+Grounded against canonical `authMiddleware`: bearer-only local API calls are still accepted during the deprecation window but log a warning; `/whoami` already requires the header. Focused validation: `npx vitest run tests/unit/template-agent-id-header.test.ts tests/unit/JobScheduler.test.ts tests/unit/JobScheduler-script-job.test.ts tests/unit/telegram-topic-context-session-clock.test.ts` passed, 41/41 tests.

package/upgrades/1.3.307.md

@@ -0,0 +1,20 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The instar-dev pre-commit gate's decision-audit entries gain a verdict field ('pass' | 'blocked', written as 'pending' and finalized by a process exit hook that also re-stages the corrected file). The riding-the-retry design is unchanged — blocked-run entries still ride the next successful commit — but each entry is now self-describing.
+
+## What to Tell Your User
+
+Nothing user-visible — contributor audit hygiene. Gate audit records that ride into a PR from earlier blocked attempts (often under an unresolved or stale slug) are now labeled as blocked evaluations instead of reading like real shipped decisions.
+
+## Summary of New Capabilities
+
+- Decision-audit entries carry verdict: pass | blocked (pending only if finalization itself failed). Reviewers can distinguish shipped decisions from rode-along blocked evaluations at a glance.
+
+## Evidence
+
+Live recurrence (2026-06-05, twice in one day): echo's PR #836 swept in a blocked-attempt entry labeled with a DIFFERENT PR's slug (the then-freshest stale trace), and codey's PR #842 shipped an "unknown"-slug entry from a pre-trace gate run — both read as real decisions and needed review-time explanation. Pinned by 2 new sandbox tests in tests/unit/instar-dev-precommit-audit-staging.test.ts (blocked run finalizes 'blocked' incl. the STAGED copy; passing Tier-1 run finalizes 'pass') alongside the existing 4; the development itself caught the source-order trap twice (TDZ on the shared variable, exit-before-registration on the hook) — both now documented in code comments and covered by the blocked-path test.

package/upgrades/gate-blocked-audit-hygiene.eli16.md

@@ -0,0 +1,11 @@
+# Gate audit entries now say whether the commit actually passed
+
+Every gated commit writes a small audit record — which tier the change declared, what the risk heuristic suggested, how big the diff was. By design, a record written during a BLOCKED attempt also survives: it gets staged, and when the developer fixes the problem and commits again, the old record rides along. The intent was honest bookkeeping — every gate evaluation leaves a trace.
+
+The problem: nothing in the record said whether the evaluation passed or was blocked. And blocked attempts often run before the developer's trace file is fully resolved, so the record gets written under the wrong name — the slug says "unknown", or worse, it carries the slug of some OTHER pull request whose stale trace happened to be the freshest file at that moment. The result reads like a real shipped decision for a change that never shipped under that name. This bit twice in one day: Echo's registry-fix PR carried a record labeled with a different PR's slug, and Codey's header PR carried an "unknown" record — both rode into main as confusing audit noise, and both had to be explained in review.
+
+The fix keeps the deliberate riding-the-retry design and makes every record self-describing: a **verdict** field, finalized the moment the gate process exits. Records start as "pending" when written, and a process exit hook — one hook covering every way the gate can finish — rewrites them as "pass" or "blocked" and re-stages the corrected file. A reviewer who sees verdict "blocked" next to a foreign slug now knows exactly what they're looking at: a failed evaluation under a stale trace, not a shipped decision.
+
+Two implementation traps are documented in the code because both actually fired during development: the shared variable and the exit hook must both live ABOVE the gate's main flow in the file, because the gate runs top-to-bottom and can exit (blocked) before ever reaching code placed lower down. The first draft had the hook at the bottom; blocked runs exited before the hook was registered, and the verdict silently stayed "pending" — caught by the new tests.
+
+Nothing changes about when records are written, staged, or how files are named. Old records without a verdict field remain valid history. Two new tests pin both sides: a blocked run's record finalizes as "blocked" (including the staged copy), and a passing Tier-1 run's record finalizes as "pass".