instar 1.3.305 → 1.3.306

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/side-effects/template-agent-id-header.md

@@ -0,0 +1,48 @@
+# Side-Effects Review — Template Agent-ID Header
+
+**Version / slug:** `template-agent-id-header`
+**Date:** `2026-06-05`
+**Author:** `instar-codey`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+This change updates the fleet-installed local API client surface so bearer-authenticated template calls also send `X-Instar-AgentId`. It adds `INSTAR_AGENT_ID` env propagation from `Config` -> `JobScheduler` and `SessionManager`, updates built-in job templates, hook/script templates, and selected migrator inline hook content, and adds a template scanner regression test.
+
+## Decision-point inventory
+
+No new decision point is added. Existing server auth remains the authority for missing/mismatched agent-id headers. This change only updates clients/templates to provide identity to that existing authority.
+
+## 1. Over-block
+
+No block/allow surface is added. A malformed or missing `projectName` could make a template send an empty or wrong `X-Instar-AgentId`, which the existing server auth would reject. The normal paths use `config.projectName`, and direct-run fallbacks read the same field.
+
+## 2. Under-block
+
+This does not remove the server's bearer-only compatibility window. A custom user-authored curl outside shipped templates can still be bearer-only and receive the deprecation warning until the server policy changes.
+
+## 3. Level-of-abstraction fit
+
+The fix sits at the client/template layer. The server already owns auth authority and should not be weakened to hide template warnings. Scheduler/session env propagation is the right shared primitive for jobs and hooks.
+
+## 4. Signal vs authority compliance
+
+Required reference: `docs/signal-vs-authority.md`
+
+No brittle blocking authority is introduced. The change feeds identity into the existing deterministic auth authority; it does not add a new detector or gate.
+
+## 5. Interactions
+
+The scheduler now injects `INSTAR_AGENT_ID` alongside `INSTAR_AUTH_TOKEN` for gate and script job shells. `SessionManager` injects the same variable for spawned sessions, so hook and prompt-job examples have it. Fleet watchdog peer requests read the peer project name and bind the peer token to the peer identity.
+
+## 6. External surfaces
+
+Installed agents get quieter logs and future-compatible local API calls after template refresh/migration. No public API response shapes change. No persistent state is written.
+
+## 7. Rollback cost
+
+Rollback is a source/template revert and patch release. Existing agents would fall back to the current accepted-but-deprecated bearer-only behavior until a corrected template ships.
+
+## Conclusion
+
+Clear to ship as Tier 1. The change aligns installed templates with the existing auth contract and pins the class with a scanner test.