instar 1.3.625 → 1.3.627

package/src/data/builtin-manifest.json

@@ -1,9 +1,9 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-19T06:08:39.918Z",
-  "instarVersion": "1.3.625",
-  "entryCount": 201,
+  "generatedAt": "2026-06-19T20:44:32.422Z",
+  "instarVersion": "1.3.627",
+  "entryCount": 202,
   "entries": {
     "hook:session-start": {
       "id": "hook:session-start",
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "fbbfc1adac0ebc5e8405574f97a758ce5a391961465f99f40a735cafded65097",
+      "contentHash": "922bf0f5c403a51a5eaa0dd73a276219f3be302aa1cd122cdd1d0f279a019a12",
       "since": "2025-01-01"
     },
     "hook:dangerous-command-guard": {
@@ -20,7 +20,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/dangerous-command-guard.sh",
-      "contentHash": "fbbfc1adac0ebc5e8405574f97a758ce5a391961465f99f40a735cafded65097",
+      "contentHash": "922bf0f5c403a51a5eaa0dd73a276219f3be302aa1cd122cdd1d0f279a019a12",
       "since": "2025-01-01"
     },
     "hook:grounding-before-messaging": {
@@ -29,7 +29,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/grounding-before-messaging.sh",
-      "contentHash": "fbbfc1adac0ebc5e8405574f97a758ce5a391961465f99f40a735cafded65097",
+      "contentHash": "922bf0f5c403a51a5eaa0dd73a276219f3be302aa1cd122cdd1d0f279a019a12",
       "since": "2025-01-01"
     },
     "hook:compaction-recovery": {
@@ -38,7 +38,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/compaction-recovery.sh",
-      "contentHash": "fbbfc1adac0ebc5e8405574f97a758ce5a391961465f99f40a735cafded65097",
+      "contentHash": "922bf0f5c403a51a5eaa0dd73a276219f3be302aa1cd122cdd1d0f279a019a12",
       "since": "2025-01-01"
     },
     "hook:external-operation-gate": {
@@ -47,7 +47,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-operation-gate.js",
-      "contentHash": "fbbfc1adac0ebc5e8405574f97a758ce5a391961465f99f40a735cafded65097",
+      "contentHash": "922bf0f5c403a51a5eaa0dd73a276219f3be302aa1cd122cdd1d0f279a019a12",
       "since": "2025-01-01"
     },
     "hook:deferral-detector": {
@@ -56,7 +56,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/deferral-detector.js",
-      "contentHash": "fbbfc1adac0ebc5e8405574f97a758ce5a391961465f99f40a735cafded65097",
+      "contentHash": "922bf0f5c403a51a5eaa0dd73a276219f3be302aa1cd122cdd1d0f279a019a12",
       "since": "2025-01-01"
     },
     "hook:self-stop-guard": {
@@ -65,7 +65,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/self-stop-guard.js",
-      "contentHash": "fbbfc1adac0ebc5e8405574f97a758ce5a391961465f99f40a735cafded65097",
+      "contentHash": "922bf0f5c403a51a5eaa0dd73a276219f3be302aa1cd122cdd1d0f279a019a12",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -74,7 +74,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "fbbfc1adac0ebc5e8405574f97a758ce5a391961465f99f40a735cafded65097",
+      "contentHash": "922bf0f5c403a51a5eaa0dd73a276219f3be302aa1cd122cdd1d0f279a019a12",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -83,7 +83,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "fbbfc1adac0ebc5e8405574f97a758ce5a391961465f99f40a735cafded65097",
+      "contentHash": "922bf0f5c403a51a5eaa0dd73a276219f3be302aa1cd122cdd1d0f279a019a12",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-collector": {
@@ -92,7 +92,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "fbbfc1adac0ebc5e8405574f97a758ce5a391961465f99f40a735cafded65097",
+      "contentHash": "922bf0f5c403a51a5eaa0dd73a276219f3be302aa1cd122cdd1d0f279a019a12",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -101,7 +101,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "fbbfc1adac0ebc5e8405574f97a758ce5a391961465f99f40a735cafded65097",
+      "contentHash": "922bf0f5c403a51a5eaa0dd73a276219f3be302aa1cd122cdd1d0f279a019a12",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -110,7 +110,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "fbbfc1adac0ebc5e8405574f97a758ce5a391961465f99f40a735cafded65097",
+      "contentHash": "922bf0f5c403a51a5eaa0dd73a276219f3be302aa1cd122cdd1d0f279a019a12",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -119,7 +119,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "fbbfc1adac0ebc5e8405574f97a758ce5a391961465f99f40a735cafded65097",
+      "contentHash": "922bf0f5c403a51a5eaa0dd73a276219f3be302aa1cd122cdd1d0f279a019a12",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -128,7 +128,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "fbbfc1adac0ebc5e8405574f97a758ce5a391961465f99f40a735cafded65097",
+      "contentHash": "922bf0f5c403a51a5eaa0dd73a276219f3be302aa1cd122cdd1d0f279a019a12",
       "since": "2025-01-01"
     },
     "hook:stop-gate-router": {
@@ -137,7 +137,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/stop-gate-router.js",
-      "contentHash": "fbbfc1adac0ebc5e8405574f97a758ce5a391961465f99f40a735cafded65097",
+      "contentHash": "922bf0f5c403a51a5eaa0dd73a276219f3be302aa1cd122cdd1d0f279a019a12",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -146,7 +146,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "fbbfc1adac0ebc5e8405574f97a758ce5a391961465f99f40a735cafded65097",
+      "contentHash": "922bf0f5c403a51a5eaa0dd73a276219f3be302aa1cd122cdd1d0f279a019a12",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1189,6 +1189,14 @@
       "contentHash": "c258707dafb41518f376ffbab4ea3c5a824d6ab7dc9b1df5f8b8a2f7f99fbaee",
       "since": "2025-01-01"
     },
+    "template:load-assess.sh": {
+      "id": "template:load-assess.sh",
+      "type": "template",
+      "domain": "operations",
+      "sourcePath": "src/templates/scripts/load-assess.sh",
+      "contentHash": "0d8c335b167a7e46099b8636692849a48d4c0ca5722853a453d1a963427c9b88",
+      "since": "2025-01-01"
+    },
     "template:secret-drop-retrieve.mjs": {
       "id": "template:secret-drop-retrieve.mjs",
       "type": "template",
@@ -1554,7 +1562,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "fbbfc1adac0ebc5e8405574f97a758ce5a391961465f99f40a735cafded65097",
+      "contentHash": "922bf0f5c403a51a5eaa0dd73a276219f3be302aa1cd122cdd1d0f279a019a12",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

package/src/scaffold/templates.ts

@@ -14,7 +14,7 @@
 // existing-agent migration there) so the two can never drift. Imported as a runtime
 // function call inside generateClaudeMd — no module-init cycle (PostUpdateMigrator
 // never imports templates).
-import { PLAYWRIGHT_PROFILE_REGISTRY_CLAUDEMD_SECTION } from '../core/PostUpdateMigrator.js';
+import { PLAYWRIGHT_PROFILE_REGISTRY_CLAUDEMD_SECTION, MACHINE_LOAD_ASSESSMENT_CLAUDEMD_SECTION } from '../core/PostUpdateMigrator.js';
 
 export interface AgentIdentity {
   name: string;
@@ -828,6 +828,7 @@ I declare owner/blockedOn at commitment creation; a later state change goes thro
 - **The autonomous balancer surface** — \`GET /credentials/rebalancer\` (the use-it-or-lose-it drainer is Increment B; this surfaces the env-token applicability gate's verdict + WHY re-pointing would refuse, when enabled).
 - **When to use** (PROACTIVE — these are the triggers): "flip my default account to X" / "make X my default" → \`POST /credentials/set-default\`; "which account is this session/slot on?" / "where does ~/.claude point?" → \`GET /credentials/locations\` (read it, don't infer from \`claude auth status\` — that reads a metadata file, not the live credential). Single-account agents are a no-op. (Spec: \`docs/specs/live-credential-repointing-rebalancer.md\`.)
 ${PLAYWRIGHT_PROFILE_REGISTRY_CLAUDEMD_SECTION(port)}
+${MACHINE_LOAD_ASSESSMENT_CLAUDEMD_SECTION()}
 **Per-Feature LLM Metrics & LLM Activity (Observable Intelligence)** — Audit what each of your LLM-driven gates/sentinels actually does: WHICH provider + model ran it, how often it ACTED (fired) vs found nothing (noop), how often it was skipped to save rate limits (shed), cost, and latency. This is the *Observable Intelligence* standard — no autonomous AI action the system takes is allowed to be invisible. Read-only observability — it never gates anything.
 - Check: \`curl -H "Authorization: Bearer $AUTH" "http://localhost:${port}/metrics/features?sinceHours=24"\`
 - Returns \`{ totals, features: [{ feature, frameworks, models, byModel, calls, realCalls, tokensIn, tokensOut, tokensCached, fired, noop, shed, fireRate, p50LatencyMs, p95LatencyMs, ... }] }\` — one row per system (e.g. MessagingToneGate, MessageSentinel). \`frameworks\`/\`models\` = which provider(s) actually served the call; \`fireRate\` = how often it acts; \`shed\` = skipped by the rate-limit guard. Filter with \`?feature=<name>\`.

package/src/templates/scripts/load-assess.sh

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+# load-assess.sh — the DURABLE go-to method for evaluating machine load.
+#
+# WHY THIS EXISTS: `uptime` 1-minute load average is the WRONG signal for "can I
+# do work / is the machine genuinely loaded." It is (a) spike-susceptible (the
+# 1-min figure swings wildly) and (b) on macOS INFLATED by threads stuck in
+# uninterruptible disk I/O (e.g. Spotlight/mds reindex after a cold boot) — so a
+# high load average can coexist with a mostly-idle CPU. On 2026-06-19 a load avg
+# of ~40 was quoted as "heavy load" when the CPU was actually 62% IDLE and the
+# load was Spotlight reindexing, not the agent. Never repeat that.
+#
+# THIS reports the RIGHT signals: real CPU idle% (sampled, not instantaneous),
+# instar's time-windowed ResourceLedger (agent-attributed CPU avg/peak over the
+# last hour), per-core load normalization, and WHAT is consuming CPU (so you can
+# tell "my work" from external/transient like Spotlight). Then it emits a verdict.
+#
+# SCOPE HONESTY: the verdict is a CPU-CAPACITY signal. It does NOT assess
+# memory/swap, thermal throttling, or disk-I/O saturation — OK means "CPU has
+# headroom," not "everything is fine." Memory/pressure is covered separately by
+# the ResourceLedger / reaper-pressure surfaces.
+#
+# Usage: load-assess.sh            (human-readable verdict)
+#        load-assess.sh --json     (machine-readable; human-diagnostic only,
+#                                    unversioned — a programmatic consumer must
+#                                    add a schemaVersion first, not assume shape)
+set -uo pipefail
+cd "$(dirname "$0")/../.." 2>/dev/null || true   # agent home (.instar/scripts -> home)
+
+JSON=0; [ "${1:-}" = "--json" ] && JSON=1
+OS=$(uname -s 2>/dev/null || echo unknown)
+
+# --- cores ---
+if [ "$OS" = "Darwin" ]; then CORES=$(sysctl -n hw.ncpu 2>/dev/null || echo 0)
+else CORES=$(nproc 2>/dev/null || grep -c ^processor /proc/cpuinfo 2>/dev/null || echo 0); fi
+
+# --- real CPU idle%: sampled (NOT a single instantaneous read) ---
+IDLE=""
+if [ "$OS" = "Darwin" ]; then
+  # macOS: top -l 2, SECOND sample is the real one (first is bogus)
+  CPU_LINE=$(top -l 2 -n 0 -s 1 2>/dev/null | grep "CPU usage" | tail -1)
+  IDLE=$(echo "$CPU_LINE" | sed -n 's/.*[, ]\([0-9.]*\)% idle.*/\1/p')
+elif [ -r /proc/stat ]; then
+  # Linux: TWO-SAMPLE /proc/stat delta. A single read CANNOT compute idle%.
+  read_stat() { awk '/^cpu /{idle=$5+$6; tot=0; for(i=2;i<=NF;i++)tot+=$i; print idle, tot}' /proc/stat; }
+  S1=$(read_stat); sleep 1; S2=$(read_stat)
+  IDLE=$(awk -v a="$S1" -v b="$S2" 'BEGIN{
+    split(a,x," "); split(b,y," ");
+    di=y[1]-x[1]; dt=y[2]-x[2];
+    if(dt>0) printf "%.1f", 100*di/dt; else print "";
+  }')
+fi
+[ -z "$IDLE" ] && IDLE=""   # empty => CPU read unavailable (e.g. unknown OS / no top)
+# Test-only seam: force the sampled idle% so the verdict-threshold boundaries can be
+# exercised deterministically (the real CPU read is environment-dependent). Read-only,
+# affects only the printed verdict; never set in production.
+[ -n "${LOAD_ASSESS_FORCE_IDLE:-}" ] && IDLE="$LOAD_ASSESS_FORCE_IDLE"
+if [ -n "$IDLE" ]; then BUSY=$(awk -v i="$IDLE" 'BEGIN{printf "%.1f", 100-i}'); else BUSY=""; fi
+
+# --- load averages (CONTEXT ONLY — never the basis of the verdict) ---
+LOADS=$(uptime 2>/dev/null | sed -n 's/.*load average[s]*: *//p')
+L1=$(echo "$LOADS" | awk -F'[ ,]+' '{print $1}')
+L5=$(echo "$LOADS" | awk -F'[ ,]+' '{print $2}')
+LOAD_PER_CORE=$(awk -v l="${L5:-0}" -v c="${CORES:-0}" 'BEGIN{if(c+0>0)printf "%.2f", l/c; else print "?"}')
+
+# --- instar ResourceLedger: time-windowed agent-attributed CPU (the durable signal) ---
+LEDGER="unavailable"
+AUTH=$(node .instar/scripts/secret-get.mjs authToken 2>/dev/null || echo "")
+PORT=$(node -pe "require('./.instar/config.json').port" 2>/dev/null || echo 4042)
+AGENT_ID="${INSTAR_AGENT_ID:-$(node -pe "require('./.instar/config.json').projectName" 2>/dev/null || echo "")}"
+if [ -n "$AUTH" ]; then
+  LEDGER=$(curl -s -m 8 -H "Authorization: Bearer $AUTH" -H "X-Instar-AgentId: ${AGENT_ID}" "http://localhost:${PORT}/resources/summary?sinceHours=1" 2>/dev/null \
+    | node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{const j=JSON.parse(d);const a=(j.sources||[]).find(s=>s.source==='aggregate')||{};console.log('avg='+(a.avgCpuPercent??'?')+' peak='+(a.peakCpuPercent??'?')+' current='+(a.currentCpuPercent??'?')+' samples='+(j.sampleCount??'?'))}catch(e){console.log('unavailable')}})" 2>/dev/null || echo "unavailable")
+fi
+
+# --- top CPU consumers + classify my-work vs external ---
+TOP=$(ps -Ao pcpu,comm -r 2>/dev/null | sed -n '2,4p')
+TOP1=$(echo "$TOP" | head -1 | awk '{print $2}')
+EXTERNAL="unknown"
+case "$TOP1" in
+  *mds*|*mdworker*|*Spotlight*|*WindowServer*|*backupd*|*photoanalysisd*|*mediaanalysisd*) EXTERNAL="external-transient (macOS: $(basename "$TOP1" 2>/dev/null))";;
+  *instar*|*node*|*claude*|*tmux*|*python*) EXTERNAL="agent-work ($(basename "$TOP1" 2>/dev/null))";;
+  "") EXTERNAL="unknown";;
+  *) EXTERNAL="other ($(basename "$TOP1" 2>/dev/null))";;
+esac
+
+# --- VERDICT (based on real idle%, NOT load average) ---
+awk_lt() { awk -v a="$1" -v b="$2" 'BEGIN{exit !(a+0<b+0)}'; }
+if [ -z "$IDLE" ]; then
+  VERDICT="UNKNOWN"; REASON="CPU idle% unavailable on this platform; rely on the agent CPU ledger + load context"
+elif awk_lt "$IDLE" 12; then VERDICT="SATURATED"; REASON="CPU genuinely saturated (idle <12%)";
+elif awk_lt "$IDLE" 30; then VERDICT="ELEVATED"; REASON="CPU busy but not saturated";
+else VERDICT="OK"; REASON="CPU mostly idle"; fi
+
+if [ "$JSON" = "1" ]; then
+  printf '{"verdict":"%s","reason":"%s","cpuIdlePercent":%s,"cpuBusyPercent":%s,"cores":%s,"loadAvg1":"%s","loadAvg5":"%s","loadPerCore":"%s","ledger":"%s","topConsumer":"%s","topClass":"%s","scope":"cpu-capacity-only","os":"%s"}\n' \
+    "$VERDICT" "$REASON" "${IDLE:-null}" "${BUSY:-null}" "${CORES:-0}" "${L1:-}" "${L5:-}" "$LOAD_PER_CORE" "$LEDGER" "${TOP1:-}" "$EXTERNAL" "$OS"
+else
+  echo "=== MACHINE LOAD ASSESSMENT ==="
+  echo "VERDICT: $VERDICT — $REASON"
+  echo "  (scope: CPU capacity only — does NOT assess memory/swap/thermal/disk-IO)"
+  echo ""
+  echo "Real CPU:        ${BUSY:-?}% busy / ${IDLE:-?}% idle   (sampled, the primary signal)"
+  echo "Cores:           ${CORES:-?} logical"
+  echo "Agent CPU (1h):  $LEDGER   (instar ResourceLedger, time-windowed)"
+  echo "Top consumer:    ${TOP1:-?}  →  $EXTERNAL"
+  echo "Load avg (ctx):  1m=${L1:-?} 5m=${L5:-?}  (per-core ${LOAD_PER_CORE})  ← context only; spike-prone + I/O-inflated, NOT the verdict"
+  echo ""
+  echo "Top 3 CPU:"; echo "$TOP" | sed 's/^/  /'
+  echo ""
+  echo "Interpretation: trust the real CPU idle% + the time-windowed agent CPU."
+  echo "A high load average with high idle% = external/transient (e.g. Spotlight), NOT agent pressure."
+fi
+exit 0

package/upgrades/{1.3.625.md → 1.3.626.md}

@@ -7,6 +7,8 @@
 
 Adds a machine × account matrix on the dashboard Subscriptions tab — the on-demand "put account X on machine Y" surface that was missing (the account-follow-me Approve cards are quota-driven and never offered accounts on demand, so adding accounts to another machine meant a clunky chat dance). Rows are accounts, columns are machines; each cell is a ✓ (active there), a "Set up" button (not yet), or an honest in-progress / needs-reauth / offline / held state. Tapping "Set up" runs the whole sign-in IN the dashboard: it PIN-checks (operator presence — the agent shares the Bearer token, so the dashboard PIN is what proves a human is acting), drives the existing PIN→mandate→enroll-start chain to start a fresh login on the target machine (that machine re-mints its own login, ToS-safe), shows the auth link + a code box, and the shipped code-paste-back relay finishes it — flipping the cell to ✓. The wrong-account safety (S7 email-gate) and cross-machine delivery are reused unchanged. Dev-gated (`multiMachine.accountFollowMe`), dark on the fleet.
 
+Structurally enforces the `code=t` lesson (the broken account-follow-me sign-in link, 2026-06-18): a parser of untrusted real-world text must be tested against a byte-for-byte REAL captured fixture, not a hand-authored clean string. Adds a Testing-Integrity standard, a `tests/fixtures/captured/` convention (structural bytes sacrosanct; secrets swapped for same-shape, grammar-valid placeholders via a tested redaction helper; one provenance sidecar per capture), and a registry-driven lint `scripts/lint-scrape-fixture-realness.js`. Each registered parser (seeded with `FrameworkLoginDriver.parseArtifact`) must have a test that loads a captured fixture through the single `loadCapturedFixture` helper, feeds it to the parser, and asserts — and the suite runs that test, so the realness is executed, not grepped. A non-blocking `parse*`/`scrape*` register-or-justify warning re-surfaces new parsers. The original `code=t` capture is migrated to disk (secrets redacted, hard-wrap preserved). No runtime code changes.
+
 ## What to Tell Your User
 
 There's now a grid on the Subscriptions tab showing which of your accounts are signed in on which machines, at a glance. To add an account to another machine, tap the empty cell, enter your dashboard PIN, sign in on the page it opens, and paste the code right there — it sets up that machine and the cell turns into a check mark. No more routing sign-in codes through chat.
@@ -21,3 +23,8 @@ There's now a grid on the Subscriptions tab showing which of your accounts are s
 - `tests/unit/subscriptions-render.test.ts` — matrix renders ✓ for active, "Set up" for empty, a disabled offline column for a `pool.failed` machine (no fabricated ✓), in-progress for a pending login.
 - `tests/unit/follow-me-controller-wiring.test.ts` — a "Set up" tap with a PIN POSTs start-cell {accountId, machineId, pin}; no-PIN does not POST.
 - `npx tsc --noEmit` clean; `npm run lint` (full battery) clean; 47 tests green.
+
+- `tests/unit/lint-scrape-fixture-realness.test.ts` (10) — both boundary sides: the shipped registry entry passes; tampered cases (missing test, removed loader, missing/invalid sidecar) fail.
+- `tests/unit/redact-captured-fixture.test.ts` (8) — same-length, line-position/wrap preservation, redacted URL still parses, length-changing redaction rejected.
+- `tests/unit/framework-login-driver.test.ts` (17) — the migrated realness test loads the disk fixture, asserts the full de-wrapped URL ≠ `code=t`.
+- `node scripts/lint-scrape-fixture-realness.js` exits 0 (seed entry clean + register-or-justify warning); `npm run lint` (full battery) exits 0; `tsc --noEmit` clean.

package/upgrades/1.3.627.md

@@ -0,0 +1,23 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Added `load-assess.sh` — a robust, durable, go-to method for an agent to evaluate machine load — and shipped it fleet-wide. It reports the RIGHT signals (real CPU idle% sampled, instar's time-windowed ResourceLedger agent-CPU, per-core load, and what's actually consuming CPU) and emits a verdict (OK / ELEVATED / SATURATED), instead of the spike-prone, macOS-Spotlight-I/O-inflated `uptime` 1-minute load average. A static "use load-assess.sh, never trust the load average" reminder is wired into the session-start hook ABOVE its compact-`exec` delegate, so it survives compaction (not just session start), and a Machine Load Assessment section is added to the CLAUDE.md template (generate + migrate) so every agent knows the capability exists.
+
+## What to Tell Your User
+
+Your agent now judges whether the machine is genuinely busy using real CPU idle% (and its own recent CPU use), not the misleading 1-minute load average — so it won't mistake a quiet-but-disk-indexing machine for an overloaded one and unnecessarily hold off on work. It's read-only: it measures and reports, changing nothing.
+
+## Summary of New Capabilities
+
+- `.instar/scripts/load-assess.sh` (`--json` to parse) — go-to machine-load assessment with a verdict; CPU-capacity-scoped (does not assess memory/thermal). Installed on every agent on update.
+
+## Evidence
+
+- 14 new tests pass: verdict thresholds (both sides of each boundary via a `LOAD_ASSESS_FORCE_IDLE` test seam), `--json` contract, fail-soft when the ResourceLedger is unreachable, the compaction-survival property (`blockIdx < execIdx` in `getSessionStartHook()`), `migrateScripts` install (always-overwrite, executable), and `migrateClaudeMd` idempotent append.
+- 568 existing PostUpdateMigrator + scaffold tests still green (no regression).
+- Independent second-pass review (touches compaction) concurred after live simulation — bash builtin `echo` writes directly to fd 1, so the awareness block's stdout reaches the captured output before the process-replacing `exec` on the compact path.
+- Spec converged through `/spec-converge` (2 rounds, `cross-model-review: codex-cli:gpt-5.5`); the review caught two critical bugs in the first draft (editing a dead template file; a mechanically-false compaction guarantee) before any code was written.

package/upgrades/side-effects/robust-load-assessment-fleet.md

@@ -0,0 +1,74 @@
+# Side-Effects Review — Robust Load Assessment (fleet-wide + compaction-surviving)
+
+**Version / slug:** `robust-load-assessment-fleet`
+**Date:** 2026-06-19
+**Author:** echo
+**Second-pass reviewer:** echo-spawned reviewer subagent (required — touches compaction)
+
+## Summary of the change
+
+Ships a read-only machine-load diagnostic (`load-assess.sh`) to every agent as a script template, wires a static "use load-assess.sh / never trust the uptime load average" awareness block into the in-code session-start hook ABOVE its compact-`exec` delegate (so it survives compaction), and adds an Agent-Awareness CLAUDE.md section (generate + migrate). Born from a 2026-06-19 incident where the agent misread the spike-prone, Spotlight-I/O-inflated 1-minute load average as "heavy load" while the CPU was ~60% idle. Three source files + two test files; 14 new tests, 568 existing PostUpdateMigrator/scaffold tests still green.
+
+## Decision-point inventory
+
+- `load-assess.sh` verdict (OK/ELEVATED/SATURATED) — **add** — produces a SIGNAL (a load verdict printed to stdout); holds **zero** blocking authority. Nothing consumes it as a gate.
+- session-start hook output — **modify** (additive) — adds a static doc block; no conditional logic, no decision.
+- `migrateScripts` / `migrateClaudeMd` — **add** (install + append) — idempotent, content-sniffed; no decision surface.
+
+---
+
+## 1. Over-block
+No block/allow surface — over-block not applicable. The script reads CPU/ledger and prints; the hook emits a static string. Nothing is rejected or gated.
+
+## 2. Under-block
+No block/allow surface — under-block not applicable. The change adds no enforcement, so there is no failure mode to "miss." (The script's verdict is advisory: a human/agent reading "OK" still makes the call. Scope honesty is built in — the verdict explicitly states it is CPU-capacity only, not a universal health oracle, so a reader does not over-trust an OK on a memory/thermal-pressured box.)
+
+## 3. Level-of-abstraction fit
+Right layer. A diagnostic script lives in `.instar/scripts/` alongside `secret-get.mjs`/`emit-session-clock.sh` (the established sibling pattern); the awareness lives in the session-start hook (the existing always-fires-on-lifecycle surface) and the CLAUDE.md template (the canonical agent-awareness surface). No smarter gate should own this — there is no gate; it is read-only observability feeding the agent's own judgment. The time-windowed signal it surfaces (ResourceLedger) is consumed, not duplicated.
+
+## 4. Signal vs authority compliance
+Compliant (`docs/signal-vs-authority.md`). `load-assess.sh` is a pure **detector/signal** — it computes a load verdict and prints it, with no power to block, delay, or rewrite anything. It does not add brittle logic with blocking authority; it adds a read-only signal a smart authority (the agent) consumes. The hook block and CLAUDE.md section are documentation, not decision points.
+
+## 5. Interactions
+- The hook block is placed ABOVE the `exec compaction-recovery.sh` branch so it is emitted on every event (startup/resume/clear/compact); it does not shadow or get shadowed by the recovery delegation (verified by a test asserting `blockIdx < execIdx`). It adds a few lines of static stdout to a hook that already emits many — no latency (no network), and the block precedes no `exit N` (the hook ends on an `echo`, which exits 0), so it cannot change the exit code. (Compaction-survival rests on bash builtin `echo` writing directly to fd 1 with no userspace stdio buffer for the subsequent `exec` to discard — verified empirically by the second-pass reviewer across tty/pipe/file-redirect.)
+- `migrateScripts` adds a sibling install next to `secret-get.mjs`; independent try/catch, cannot affect the other script installs.
+- `migrateClaudeMd` appends a content-sniffed section (`!includes('Machine Load Assessment')`) — idempotent, does not duplicate on re-run (tested), does not edit other sections in place.
+- The CLAUDE.md section text is single-sourced (`MACHINE_LOAD_ASSESSMENT_CLAUDEMD_SECTION()`) and used by BOTH generate (new agents) and migrate (existing) — they cannot drift (tested).
+
+## 6. External surfaces
+- The script reads the existing `GET /resources/summary` endpoint (read-only; no new surface) and degrades to local-only if it is unreachable (fail-soft, tested). No new external API.
+- `--json` is documented human-diagnostic-only and unversioned — no system consumes it; a future programmatic consumer must add a `schemaVersion` first (stated in the script + spec).
+- The hook output is agent-internal stdout, not visible to other agents/users/systems.
+- No timing/conversation-state dependence: the script samples CPU on demand; the hook block is static. A test-only `LOAD_ASSESS_FORCE_IDLE` env seam exists (read-only, affects only the printed verdict for boundary testing; never set in production).
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+- `load-assess.sh` — **machine-local BY DESIGN**: load is a property of the machine the script runs on; there is nothing to replicate. Cross-machine load reads are already served separately by `/guards?scope=pool` and `/resources/summary`.
+- The hook block and CLAUDE.md section — **machine-local static template content**, installed identically on every machine by each machine's own migration; no replication needed, no strand-on-transfer risk (no durable per-topic state), no generated URLs.
+
+## 8. Rollback cost
+Low. Revert the PR (3 source files). The change is additive and idempotent: reverting stops shipping the script template + hook block + CLAUDE.md section to future migrations. Agents that already migrated keep a harmless read-only `load-assess.sh` on disk (no cleanup required; it gates nothing). No data migration, no agent-state repair. A hot-fix release is sufficient if needed.
+
+---
+
+## Second-pass review (required — touches compaction)
+
+**Reviewer:** echo-spawned independent reviewer subagent. **Verdict: Concur with the review.**
+
+The reviewer independently audited the 4 additive blocks, ran the 14 tests, AND ran live simulations rather than trusting the framing:
+1. **Compaction-survival — TRUE (verified by execution):** simulated the hook with stdout to a tty, a pipe, and a file redirect with the compact `exec` actually firing — the MACHINE LOAD block appeared before the delegate's output in every case. Robust because bash builtin `echo` writes via `write(2)` directly to fd 1 (no userspace stdio buffer for `exec` to discard); bytes are in the kernel before `exec` runs. The non-executable-recovery fallback also behaves correctly (exec skipped, block still emitted, hook continues).
+2. **Timeout/exit code — no risk:** static echoes, zero network; precedes no `exit N`.
+3. **Script safety — sound:** `set -uo pipefail` with NO `set -e`; ran under stripped env / empty-IDLE / faked unknown-OS — all exit 0 with a clean verdict (UNKNOWN + null JSON on genuine no-CPU-read, never a crash). All `set -u`-sensitive vars assigned before use; verdict chain exhaustive (VERDICT+REASON on every branch); `bash -n` clean.
+4. **Test `blockIdx < execIdx`** pins the real property; combined with both-boundary script tests + the empirically-confirmed flush-survives-exec behavior, the guarantee is covered.
+5. **Packaging — sound:** `loadRelayTemplate('load-assess.sh')` resolves via `src/templates/scripts/`, which IS in package.json `files` (ships to npm) — the same proven mechanism as `secret-get.mjs`. Content-sniff anchor `'Machine Load Assessment'` is unique (no cross-section collision); idempotency confirmed count==1 after repeated runs.
+
+No concerns raised.
+
+---
+
+## CI-conformance follow-up (post-open, #1231)
+
+CI shard 4/4 surfaced two required-conformance gaps (caught by the full suite, not my local subset run):
+- `load-assess.sh`'s localhost API call to `/resources/summary` lacked the `X-Instar-AgentId` header that `template-agent-id-header.test.ts` requires of every Bearer call in a template. Added (AGENT_ID derived from `INSTAR_AGENT_ID`/config.json projectName, same as session-start.sh). No behavior change — the header is identification only; the call already fail-softs.
+- The `Machine Load Assessment` migrateClaudeMd section was not registered in `feature-delivery-completeness.test.ts`'s `legacyMigratorSections` tracking list. Added (observe-only, ships ON, no framework-shadow marker → legacy migrator list, not featureSections). No runtime change — a test-registry entry.
+
+Both are conformance fixes to the same change; the design + second-pass review above stand unchanged.

package/upgrades/side-effects/scrape-fixture-realness.md

@@ -0,0 +1,49 @@
+# Side-effects review — Scrape/Parser fixture-realness enforcement
+
+Spec: `docs/specs/scrape-fixture-realness.md` (converged @ iter 4, approved) · ELI16: `docs/specs/scrape-fixture-realness.eli16.md`
+Parent principle: Testing Integrity
+
+## What the change is
+
+Structural enforcement of the `code=t` lesson: a parser of untrusted real-world text must be tested against a byte-for-byte REAL captured fixture, not a hand-authored clean string. Adds (1) a registry standard, (2) a `tests/fixtures/captured/` convention with secret-redaction + provenance sidecars, (3) a registry-driven lint `scripts/lint-scrape-fixture-realness.js` that requires each registered parser's test to load a captured fixture via `loadCapturedFixture`, feed it to the parser, and assert — plus a non-blocking register-or-justify warning for un-registered `parse*`/`scrape*` exports. No runtime code changes.
+
+Files: `scripts/lint-scrape-fixture-realness.js`, `scripts/redact-captured-fixture.mjs`, `tests/helpers/loadCapturedFixture.ts`, `tests/fixtures/captured/**`, `docs/STANDARDS-REGISTRY.md`, `package.json` (lint chain), `scripts/pre-push-gate.js` (direct invocation), `tests/unit/framework-login-driver.test.ts` (migrated), + tests for the lint and the redaction helper.
+
+## 1. Over-block — legitimate inputs rejected that shouldn't be
+The lint only enforces realness for parsers EXPLICITLY in the `SCRAPE_PARSERS` registry (seeded with one). It never fires on un-registered code — so it cannot false-positive a normal test. The register-or-justify check is a non-blocking WARNING (exit code unaffected). Near-zero over-block by construction (FD1).
+
+## 2. Under-block — failure modes still missed
+- The lint proves the registered test loads-feeds-asserts; it cannot prove the assertion is non-trivial (a deliberately weak `expect`) — owned as a review concern (FD6).
+- It cannot prove un-redacted bytes were genuinely real (provenance is review-checkable, not machine-verifiable) — owned (FD2).
+- Inline/method/private parsers aren't caught by the `parse*`/`scrape*` export scan — the PR register-or-justify trigger (review) is primary; the warning is a backstop (FD3). This is the conformance gate's noted Structure-vs-Willpower residual, accepted because full coverage needs the unbounded heuristic FD1 rejects.
+
+## 3. Level-of-abstraction fit
+Correct layer: a build-time lint alongside the existing `lint-*` family, run via `npm run lint` (the real battery) + the pre-push gate. The redaction helper sits in `scripts/` with its peers. The fixture convention sits under `tests/fixtures/`. No runtime layer touched.
+
+## 4. Signal vs authority compliance
+A hard-blocking lint over a CURATED registry — legitimate per Signal-vs-Authority because the false-positive surface is near-zero by construction (identical posture to `lint-no-direct-llm-http` / `lint-dev-agent-dark-gate`, both hard-block on curated lists). The register-or-justify check is signal-only (warning, never blocks). No brittle blocking authority over messages/sessions.
+
+## 5. Interactions
+- Adds one entry to the `npm run lint` `&&`-chain (ordering-independent; each lint is self-contained) + a direct pre-push invocation (mirrors the two existing direct lints). No shadowing/double-fire.
+- The migrated `framework-login-driver` realness test now loads from disk via `loadCapturedFixture` instead of an inline const; the de-wrap assertion (full URL ≠ `code=t`) is unchanged, so the regression guard and the realness convention reinforce each other.
+- The redaction helper is a new dependency of the fixture-authoring flow; it carries its own unit tests so a redaction bug can't silently produce a passing-but-fake fixture.
+
+## 6. External surfaces
+None at runtime. Build-time only: a new lint contributors run via `npm run lint`; a new standard in the registry; a new fixtures dir. Nothing visible to users, other agents, or other systems.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+Machine-local by design (FD4): build-time lint over the committed source tree + committed fixtures. No runtime surface, no state, no cross-machine behavior. Every machine builds the identical repo and runs the identical lint over the identical fixtures.
+
+## 8. Rollback cost
+Cheap. Revert the new files + the three small wiring edits (package.json, pre-push-gate.js, the migrated test). No data migration, no runtime/state. The migrated fixture can revert to an inline const if ever needed (the assertion is unchanged).
+
+## Second-pass (high-risk: "lint"/gate)
+The lint's core (`checkTest`) was independently re-read against the spec: it requires, within the registry-named test, a `loadCapturedFixture('<slug>')` assigned to a var, that var passed as the first arg to the registered parser symbol (member-expression accepted), and an `expect(`. The sidecar check validates required fields + ISO timestamp. Matches the spec's canonical-shape matcher; the realness is executed (the suite runs the named test). Concur.
+
+## Follow-up fix (CI regressions)
+
+Two regressions this PR introduced were caught by CI (not the 3 files I first ran) and fixed:
+1. **Dangling ref:** the standard cited the `SCRAPE_PARSERS` token; the standards-enforcement-auditor resolves backticked `FOO_BAR` tokens as `src/**` symbols, and this one lives in `scripts/`, so it never resolved → danglingCount 0→1. Rephrased the standard to "a curated parser registry" (no marker token). Re-verified danglingCount=0.
+   - Over-block/Under-block: none — the lint's behavior is unchanged; only the registry prose changed.
+2. **Pre-push-gate scratch test:** the direct lint invocation added to `scripts/pre-push-gate.js` ran against the gate's resolved ROOT, which is a scratch dir in the gate's own unit tests (where the registered fixtures don't exist) → status 1. Removed the redundant direct invocation; the lint is enforced via the `npm run lint` chain that CI runs (authoritative). No loss of enforcement.
+   - Rollback cost: trivial (re-add the block if a future need arises, guarded for scratch).