instar 1.3.626 → 1.3.628

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.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/1.3.628.md

@@ -0,0 +1,23 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Added operator-**Cancel** for an in-flight account×machine matrix cell. PR #1230 shipped the matrix happy-path (tap a cell → start a cross-machine sign-in) but left no way to back out: a mis-tapped cell sat "in-progress" (◷) for up to 15 minutes with a live `claude auth login` pane and no undo. This adds a tappable Cancel on the in-progress cell that abandons the pending login and tears down its sign-in pane — on THIS machine or a peer, via a fronting relay that mirrors the existing `submit-code` pattern (Bearer-authed, one mesh hop; offline peer → honest 502). Two new routes (`POST /subscription-pool/follow-me/enroll/:id/cancel` target-local + `POST /subscription-pool/follow-me/cancel` relay), dark behind the existing `multiMachine.accountFollowMe` flag (no new config key). Two `PendingLoginStore` hardening tweaks ride along: a `transition()` terminal guard (a cancel can never clobber a login that just COMPLETED) and an `issue()` that replaces a stale terminal/expired same-id record (so re-enrollment after a cancel works instead of erroring "already exists").
+
+## What to Tell Your User
+
+If you start setting up an account on a machine from the dashboard's account×machine grid and realize you tapped the wrong cell, you can now tap **Cancel** right on that spinning cell to back out — it shuts down the leftover sign-in window and frees the cell so you can set up the right one. It works whether the cell is on the machine you're looking at or another of your machines. (This rides the account-follow-me feature, which is off by default.)
+
+## Summary of New Capabilities
+
+- **Cancel an in-flight matrix cell** — a tappable Cancel on the in-progress (◷) cell in the dashboard Subscriptions grid; abandons the pending login + tears down its sign-in pane on the owning machine (self or peer). Bearer-only (no PIN — a per-machine PIN can't cross the mesh, same as the code-submit step). Dark behind `multiMachine.accountFollowMe`.
+
+## Evidence
+
+- 32 new tests pass: store terminal-guard + issue()-replace + the live-pending-still-throws boundary (unit); `EnrollmentWizard.getById`/`abandon` pass-throughs (unit); the full route matrix over HTTP (integration) — dark→503, happy→200+abandoned with the RAW `tmux kill-session` asserted via a recording stub, idempotent terminal→200, completed-not-clobbered, unknown/malformed id→404, expired-still-cancellable→200, submit-in-flight→409, relay self/peer/offline; and the Tier-3 "feature is alive" E2E booting the real `AgentServer` (200 + abandoned, not 404; dark→503; Bearer required).
+- 178 existing related tests still green (no regression), tsc clean, full custom-lint suite clean.
+- Spec converged through `/spec-converge` (2 rounds, `cross-model-review: codex-cli:gpt-5.5`); the review caught FOUR real bugs in the first draft before any code: the original pane-kill (`sessionManager.killSession`) was a no-op for these unregistered raw-tmux panes; cancel→abandon would have broken re-enrollment; a cancel could have un-done a successful login; and a self-only scope would have silently 404'd peer cells.
+- Independent second-pass review (kill-path + gate) — see `upgrades/side-effects/matrix-cell-operator-cancel.md`.

package/upgrades/side-effects/matrix-cell-operator-cancel.md

@@ -0,0 +1,151 @@
+# Side-Effects Review — matrix-cell-operator-cancel
+
+**Change:** Adds operator-cancel for an in-flight account×machine matrix cell — a
+target-local route `POST /subscription-pool/follow-me/enroll/:id/cancel`, a fronting
+relay `POST /subscription-pool/follow-me/cancel`, two `PendingLoginStore` hardening
+tweaks, two `EnrollmentWizard` pass-throughs, a dashboard Cancel button, and a one-clause
+CLAUDE.md awareness addition. Dark behind `multiMachine.accountFollowMe`.
+
+**Spec:** `docs/specs/matrix-cell-operator-cancel.md` (converged iter 2, approved).
+
+## 1. Over-block — what legitimate inputs does this reject that it shouldn't?
+
+- A cancel against a `completed`/`abandoned` login returns a calm idempotent `200`
+  (`cancelled:false, alreadyTerminal:true`) — it does NOT reject; correct.
+- A cancel while a `submit-code` is in flight returns `409` ("try again in a moment").
+  This is intentional and momentary (the ~2s credential-poll window) — the operator can
+  re-tap. It is the right call: cancelling mid-credential-write would strand a partial
+  credential. Not an over-block.
+- Malformed id (`^[a-z0-9-]+$` fail) → `404`. The store's own `ID_RE` is identical, so a
+  malformed id could never name a real login anyway — no legitimate input rejected.
+
+## 2. Under-block — what failure modes does this still miss?
+
+- **Peer cancel when the peer is offline** → honest `502` (the relay can't reach it); the
+  peer's pane keeps running until that machine's next enroll pre-cleans it. Surfaced to the
+  operator, not silently swallowed.
+- **Crash between abandon and pane-kill** → orphaned pane. Self-heals on the next enroll
+  (enroll-start pre-cleans the slot's pane before re-spawning). Accepted (D2).
+- **Mandate not revoked** on cancel (D4) — a bounded, re-mint-only, 1h-expiring mandate
+  lingers. Grants no standing authority; accepted residual.
+- **configHome slot not wiped** (D3) — a deliberate decision (wiping could clobber a valid
+  prior credential for the same account); stale-slot hygiene is the existing
+  credential-coherence path's job.
+
+## 3. Level-of-abstraction fit
+
+Correct layer. The route family already exists (`start-cell` mints; `submit-code` operates
+on an in-flight login). Cancel is a peer of `submit-code` ("operate on an existing login")
+and is placed in the same route closure, sharing the `followMeSubmitInFlight` guard. The
+store-level terminal guard + `issue()` replace push correctness DOWN to the store (defense
+in depth) rather than relying on route logic alone. The pane teardown uses the SAME raw
+`tmux kill-session` the spawn (`server.ts:10713`) uses — not a higher-level helper that
+turned out to be a no-op for these unregistered panes.
+
+## 4. Signal vs authority compliance
+
+The route holds de-escalating authority (kills a pane, abandons a record) gated by Bearer
+auth + the dark flag. It is NOT a brittle detector with blocking teeth — it reuses the
+existing structural API-edge gates (auth, `^[a-z0-9-]+$` validation, terminal-state
+idempotent read, the in-flight 409). No content/intent judgment is made; the "should I
+cancel?" decision is the operator's tap, not an inferred classifier. The `transition()`
+terminal guard is pure mechanics (refuse a terminal→terminal flip), not a judgment gate.
+Compliant with `docs/signal-vs-authority.md` (the exempted "structural guard at the edge /
+idempotency mechanics" class).
+
+## 5. Interactions
+
+- **Shares `followMeSubmitInFlight` with submit-code** — cancel reads it (409 if held). It
+  never writes it, so it can't deadlock submit-code. Verified the cancel route is colocated
+  in submit-code's closure (it references the same `Set`).
+- **`issue()` change touches ALL callers** — but the only production caller is
+  `EnrollmentWizard.start()` (verified: the other `.issue(` hits are the unrelated mandate
+  store). start-cell only reaches `issue()` after its reuse pre-check fails on a live-pending
+  record, so any same-id record at `issue()` is non-pending → safe to replace.
+- **`transition()` terminal guard** affects `complete()` + `abandon()` (both route through
+  it). It only blocks terminal→terminal; normal `pending→completed`/`pending→abandoned`
+  unaffected. `reissue()` does not call `transition()` and already guards terminal states.
+- **Cancel vs start-cell reuse** — abandon-first makes the record non-reusable before the
+  cell clears, so start-cell's reuse path can never hand out a cancelled login's URL.
+- No double-fire / shadow: the relay and target-local route have distinct paths
+  (`/follow-me/cancel` vs `/follow-me/enroll/:id/cancel`); `:id` cannot match the literal
+  `start`/`cancel` segments.
+
+## 6. External surfaces
+
+- **Dashboard Cancel button** — a new operator-visible affordance on the in-progress (◷)
+  matrix cell, behind the dark dev-agent gate. Mobile-first (full-tap-target button,
+  optional native confirm that degrades to proceed under headless). Ships with the npm
+  package (no migration).
+- **Two new HTTP routes** — dark behind `multiMachine.accountFollowMe` (503 when off). No
+  new config key.
+- **No new external network egress** beyond the existing same-mesh relay hop (Bearer-authed,
+  to this agent's own paired machines only — `resolvePeerUrls`). No credential ever crosses.
+- Timing/runtime dependence: only the momentary submit-in-flight 409 (a real, transient
+  condition the operator retries through).
+
+## 6b. Operator-surface quality (Operator-Surface Quality standard)
+
+This change touches an operator surface (`dashboard/subscriptions.js` — the Cancel
+button on the in-progress matrix cell).
+
+1. **Leads with the primary action?** Yes. The Cancel button is the single,
+   visible action on an in-progress (◷) cell — a full-tap-target `<button>Cancel</button>`
+   rendered inline beside the status glyph on every poll re-render (not collapsed,
+   not below the fold, no explanatory prose in front of it).
+2. **Zero raw internals as primary content?** Yes. The cell shows the glyph + the
+   word "Signing in…" + the "Cancel" button; on tap, a plain status line
+   ("Cancelling…" → "Cancelled — you can set this up again.") or the route's
+   plain-English error. No JSON, no fingerprints, no config paths, no slugs. The
+   `loginId`/`machineId` ride as `data-*` attributes (support metadata), never shown.
+3. **Destructive actions de-emphasized?** N/A in the harmful sense — Cancel is
+   itself the *reversing* (de-escalating) action, fully reversible (re-tap "Set up"
+   to redo). It is a small single button, optionally guarded by a native confirm
+   ("Cancel this in-progress setup?"). There is no separate destructive control to
+   demote; the constructive "Set up" path reappears after a cancel.
+4. **Plain language + phone width?** Yes. "Cancel" / "Signing in…" / "Cancelled —
+   you can set this up again." read the way a non-engineer would say them; the
+   button is a real tap target in the existing mobile-responsive matrix grid (same
+   cell layout as the shipped "Set up"/"Submit" buttons), no horizontal scroll, no
+   truncated table hiding the action.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**Proxied-on-write (relay).** A `PendingLogin` + pane live on the machine running the login
+subprocess; the target-local route is machine-local by necessity. Cross-machine reach is the
+fronting relay `follow-me/cancel`, dispatching by `machineId` to self-loopback or the owning
+peer over the authed mesh hop — the SAME proven pattern as `follow-me/submit-code`. The
+dashboard always calls the relay, so a peer cell cancels correctly; an offline peer yields an
+honest 502. No durable state strands on topic transfer (a PendingLogin is not topic-scoped);
+no generated URL crosses a machine boundary. The earlier self-only draft (which would have
+silently 404'd peer cells) was rejected in convergence — this is the corrected posture.
+
+## 8. Rollback cost
+
+Single `git revert`. Pure additive surface behind an existing dark flag. The two store
+changes are backward-compatible (the terminal guard only PREVENTS a clobber that should
+never happen; the `issue()` replace only RELAXES a throw). No data migration — `abandoned`
+is already a valid terminal state the store + sweeps handle today. No agent-state repair. The
+auto-merger handles the merge; a bad merge is one revert.
+
+---
+
+## Second-pass review
+
+_(High-risk: touches a block/allow decision surface — a kill path + a dark gate + the word
+"gate". Reviewer appended below.)_
+
+An independent second-pass reviewer audited the actual implementation code (not just the
+spec) against the artifact, line by line. Findings: **all [OK]** — kill targets the correct
+pane with no injection (derived from the stored record, not `req.params.id`; `id` regex-gated
+`^[a-z0-9-]+$`; no shell); gate order exactly as specified with abandon-before-kill; the
+`@silent-fallback-ok` tag is correct and both catch ratchets pass; the `transition()` terminal
+guard cannot break `complete()`/`reissue()`/normal flows; `issue()` replace has a single
+production caller (`EnrollmentWizard.start`) and still throws on a live-pending dup; the
+dashboard Cancel is on the durable cell, no PIN, confirm degrades under jsdom; template↔migrator
+parity + idempotency hold; the relay adds no SSRF surface beyond submit-code (own paired
+machines only, `encodeURIComponent`'d id, no `code` body); no new CI ratchet trips. One
+**[MINOR]**: the submit-in-flight 409 is a momentary retry-through window (documented in §1) —
+not a defect. No blockers, no material issues, no signal-vs-authority violation.
+
+**Verdict: Concur with the review.**

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.