instar 1.3.762 → 1.3.764

package/upgrades/1.3.763.md

@@ -0,0 +1,23 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Added the **External-Hog Zombie Auto-Kill Sentinel** (CMT-1901) — a background watcher that surfaces sustained EXTERNAL CPU hogs (broad observability) and auto-kills exactly one narrow class: orphaned Electron editor extension-host wrappers (the 2026-07-03 VS Code MongoDB-extension zombie that pinned ~2.2 cores for ~24h). The intelligence decides kill/leave/alert WITHIN a mechanical veto-only safety floor; a kill fires iff `floor_pass && classifier==='kill'` — the model can only ever SPARE a process, never widen the target set. Kill-SAFETY is carried entirely by the deterministic floor (same-uid non-root, orphaned-owner, launchctl-unmanaged, sustained N-window CPU, code-defined allowlist class, a kill-time CPU re-confirm); the model carries EFFECTIVENESS.
+
+Ships **dev-gated DARK on the fleet, watch-only `dryRun` on a development agent** (`monitoring.externalHogSentinel.enabled` OMITTED → `resolveDevAgentGate`; `dryRun:true` is the kill-safety canary). Nothing is killed until a deliberate **PIN-gated arm**. New routes: `GET /external-hog` (status), `POST /external-hog/arm` (PIN-gated — a Bearer token cannot arm a real kill), `POST /external-hog/disarm` (Bearer — the safe direction). New config block `monitoring.externalHogSentinel` (enabled dev-gate-resolved; dryRun + kill-gate knobs via applyDefaults; a dev-gate strip migration for existing agents). Registered in `/guards` (dev-gated), and in the CLAUDE.md agent-awareness template.
+
+## What to Tell Your User
+
+Nothing on the fleet — the feature ships **dark**: every route 503s and it is a strict no-op until deliberately enabled. On an agent where it is live, it is **watch-only**: it observes and reports sustained CPU hogs but kills nothing until the operator arms it with their dashboard PIN — and even armed, only the one narrow orphaned-editor-helper class, never anything else.
+
+## Summary of New Capabilities
+
+- **Observability**: `GET /external-hog` reports sustained external CPU hogs (killed or left-alive) plus the durable arm state and an honest guard posture (`on-stale` when blind, never a false `on-confirmed`).
+- **Operator control (dashboard PIN)**: arm the live kill with `POST /external-hog/arm` (PIN-gated; the marker binds the PIN consent to the current allowlist-class content-hashes) and disarm back to watch-only with `POST /external-hog/disarm`. A disarm can never be silently un-done (epoch monotonicity — returning to live-kill needs a fresh PIN arm).
+
+## Evidence
+
+Built across 25 independently-reviewed checkpoints. ~246 external-hog unit/integration tests across 23 modules + a Tier-3 "feature is alive" E2E over the real `AgentServer` (GET 200 with a live status, the arm→disarm→re-arm epoch lifecycle, dark → 503, Bearer + PIN auth). **6 real bugs were caught by mandatory second-pass reviews of kill-adjacent code** (a fail-OPEN floor invariant, a false-HIGH CPU reading, a brake-off breaker, an invisible-hog drop, a non-boolean-laundering gate, and shell-caught deferral tracking) plus 1 self-caught §4.5 kill-time CPU re-confirm gap. Spec: `docs/specs/external-hog-zombie-autokill-sentinel.md` (converged 11 rounds + operator-approved).

package/upgrades/1.3.764.md

@@ -0,0 +1,45 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Fixed a config-shape bug that made the **Action-Claim Follow-Through Sentinel** (including the
+Slack-followthrough registration lane) impossible to enable on real installs. The sentinel gated on
+`messaging.actionClaim.enabled`, but on every real install `messaging` is a JSON **array** of adapter
+configs — so the dot-path `messaging.actionClaim.*` was unreachable (an array has no `actionClaim`
+property), and the read always returned the `false` default. Because the sentinel defaults OFF, its
+master switch could never be turned on. The tests didn't catch it because they all used an
+object-shaped `messaging`, which no real install uses. The enable/config now lives at a reachable
+**top-level `actionClaim`** block (the legacy object-shaped `messaging.actionClaim` is still honored
+for back-compat).
+
+## What to Tell Your User
+
+Nothing proactive — this is an internal enablement fix for a feature that ships off by default. If a
+user asks why the promise follow-through tracker (the thing that turns "I'll post that in about five
+minutes" into a durable commitment) never activated even after they tried to switch it on, the answer
+is that the on-switch was written in a spot the program could never actually read; it now lives in a
+reachable place and can genuinely be turned on (tried on a development agent first, before any wider
+rollout).
+
+## Summary of New Capabilities
+
+- The Action-Claim / Slack-followthrough sentinel is now **enablable** on real (array-`messaging`)
+  installs via top-level `actionClaim.enabled` (plus `actionClaim.slack`, `actionClaim.perTopicCap`,
+  `actionClaim.expiresHours`).
+- Legacy object-shaped `messaging.actionClaim` config keeps working unchanged.
+- No behavior change while the feature stays dark (its default); this only makes the switch reachable.
+
+## Evidence
+
+- `tests/integration/action-claim-config-shape.test.ts` — with array-shaped `messaging` + top-level
+  `actionClaim.enabled:true`, a promise like "I'll restart the server now" registers a durable
+  commitment (returns `feature-disabled` before the fix); tuning knobs honored; explicit-false
+  off-switch works; object-shaped `messaging.actionClaim` back-compat verified.
+- `tests/unit/action-claim-hook-slack.test.ts` — the generated Stop hook resolves config array-safely
+  (reads top-level `cfg.actionClaim`, `Array.isArray`-guards the legacy fallback).
+- Existing route (14) + e2e lifecycle (4) + generated-hooks-parse (25) + migration (5) tests stay
+  green; `tsc --noEmit` clean.
+- Side-effects review: `upgrades/side-effects/actionclaim-config-shape-fix.md`.

package/upgrades/side-effects/actionclaim-config-shape-fix.eli16.md

@@ -0,0 +1,50 @@
+# ELI16 — Why the "I'll do that in 5 minutes" tracker couldn't be turned on
+
+## The one-sentence version
+
+There's a safety feature that watches for promises the agent makes ("I'll restart it", "I'll post
+that in about 5 minutes") and quietly writes them down so they survive a restart — and it turned out
+you literally could not switch it on. This change fixes the switch.
+
+## What was broken
+
+Think of the config file as a form. Most settings live in labeled boxes you can fill in. The switch
+for this promise-tracker was written as "fill in the box `messaging → actionClaim → enabled`."
+
+The problem: `messaging` isn't a box that holds other boxes. It's a **list** — one row per chat
+platform (Telegram, Slack, WhatsApp). You can't write "actionClaim" *inside a list*; there's nowhere
+to put it. So when the program looked for `messaging → actionClaim → enabled`, it always found
+nothing, and "nothing" means "off." No matter what you did, the feature stayed off.
+
+Why nobody noticed for so long: every automated test filled the form out the *wrong* way — it made
+`messaging` a box instead of a list, so in the tests the switch worked fine. But no real install
+looks like that. Real installs always use the list. So the tests were green while the real thing was
+un-turn-on-able. Two sibling features have the same quirk, but they default to **on**, so nobody ever
+had to find the switch — this promise-tracker is the first one that defaults to **off** and actually
+needs its switch to work.
+
+## What this change does
+
+It moves the switch to a box that actually exists: a **top-level `actionClaim`** setting, right
+alongside the other real settings — not buried inside the platform list. The old (broken) location
+is still honored if anyone used it, so nothing that already worked breaks.
+
+Two places read that switch: the live server route that receives the promise, and a small "when a
+turn finishes" hook script. Both now look in the new top-level spot first, and both are careful never
+to trip over the list.
+
+## Why it's safe
+
+- The feature is *signal-only*: it just writes a note; it never blocks or changes a message. So there
+  is no risk of it wrongly rejecting something.
+- It still ships **off by default** — this change only makes the "on" switch reachable, it doesn't
+  turn anything on.
+- Old configs keep working (the old location is a fallback), so it's backwards compatible.
+- If it's ever wrong, the fix is a plain code revert — there's no saved data to clean up.
+
+## How we know it works now
+
+A new test fills the form out the **real** way — `messaging` as a list — and flips the new top-level
+switch, then checks that a promise like "I'll restart the server now" actually gets written down. It
+fails without the fix and passes with it. Older tests (the ones using the box shape) still pass, so
+the backwards-compatibility promise holds.

package/upgrades/side-effects/actionclaim-config-shape-fix.md

@@ -0,0 +1,149 @@
+# Side-Effects Review — Action-Claim sentinel enablable on array-shaped `messaging`
+
+**Version / slug:** `actionclaim-config-shape-fix`
+**Date:** `2026-07-04`
+**Author:** `Echo`
+**Second-pass reviewer:** `not required (Tier-1)`
+
+## Summary of the change
+
+The Action-Claim Follow-Through Sentinel (including the Slack-followthrough lane from #1361)
+gated on the config path `messaging.actionClaim.enabled`. On every real install `messaging` is a
+JSON **array** of adapter configs, so `messaging.actionClaim.*` is unreachable — `LiveConfig`'s
+`getNestedValue` walks `messaging`, gets the array, evaluates `array['actionClaim']` → `undefined`,
+and returns the `false` default. Because this sentinel defaults OFF, the master gate could never be
+set true: the feature was **structurally un-enablable in production**. CI never caught it because
+every test wrote an object-shaped `messaging`, which no real install uses. Fix: read the config from
+a reachable **top-level `actionClaim`** block (canonical), honoring the legacy object-shaped
+`messaging.actionClaim` as a back-compat fallback. Files: `src/server/routes.ts` (the
+`/action-claim/observe` reads, via a small `acGet` live-read helper), `src/core/PostUpdateMigrator.ts`
+(the generated Stop hook's raw-file resolution + the CLAUDE-template enable-key text),
+`src/scaffold/templates.ts` (the scaffold CLAUDE-template enable-key text), plus tests.
+
+## Decision-point inventory
+
+- `POST /action-claim/observe` config reads (`src/server/routes.ts`) — **modify** — master `enabled`,
+  `slack.enabled` dev-gate value, `slack.dryRun`, `perTopicCap`, `expiresHours` now resolve
+  top-level-first via `acGet`.
+- Generated `action-claim-followthrough.js` Stop hook (`PostUpdateMigrator.getActionClaimFollowthroughHook`)
+  — **modify** — the raw-file `enabled` resolution reads top-level `cfg.actionClaim` and Array-guards
+  the legacy `cfg.messaging.actionClaim` fallback.
+- The `messaging.actionClaim.slack.enabled` dev-gate (`resolveDevAgentGate`) — **pass-through** — value
+  now sourced via `acGet` but the `undefined → live-on-dev, dark-fleet` semantics are unchanged.
+
+---
+
+## 1. Over-block
+
+No block/allow surface — over-block not applicable. The change only affects whether a
+signal-only, never-blocking sentinel can be turned ON. An explicit top-level `actionClaim.enabled:false`
+correctly keeps it off (covered by a test).
+
+## 2. Under-block
+
+No block/allow surface — under-block not applicable. The sentinel remains dark by default (absent
+config → `false`); the fix does not change detection precision, only config reachability.
+
+## 3. Level-of-abstraction fit
+
+Right layer. This is a config-resolution fix at the exact read sites that were broken; it introduces
+no new authority and reuses the existing `LiveConfig` getter and the raw-file read in the generated
+hook. It does not re-implement config parsing — it adds a top-level-first fallback around the
+existing getters.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — this change has no block/allow surface. It changes config reachability for a signal-only
+  sentinel (the Stop hook always `exit(0)`; the observe route never blocks a message). No brittle
+  logic gains blocking authority.
+
+## 5. Interactions
+
+- **Shadowing:** none. The `acGet` helper reads top-level first, then falls back to the old
+  `messaging.actionClaim` path with the same default — a superset of prior behavior. Object-shaped
+  configs (existing tests) resolve identically via the fallback.
+- **Double-fire:** none. Single read path per field; no new emitter.
+- **Races:** none. Reads are per-request via `LiveConfig` (live, no shared mutable state added).
+- **Feedback loops:** none.
+
+## 6. External surfaces
+
+- **Other agents / install base:** the generated Stop hook is regenerated on every migration
+  (`instar/` hooks are always-overwritten), so existing agents pick up the array-safe resolution on
+  their next update — no per-agent config migration required (a fresh top-level `actionClaim` enable
+  is purely additive).
+- **External systems:** none changed. Slack/Telegram delivery paths untouched.
+- **Persistent state:** none. No new ledger/column/file.
+- **Operator surface:** no operator-facing action added — enabling is a config edit (dev-first soak),
+  same as before, now at a reachable key. "No operator-facing actions" — the CLAUDE-template text was
+  corrected so agents point operators at the reachable `actionClaim.enabled` key.
+
+## 6b. Operator-surface quality
+
+No operator surface — not applicable. No dashboard renderer, approval page, or grant/secret form is
+touched.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**machine-local BY DESIGN.** Config (`.instar/config.json`) is per-machine, and the Action-Claim
+sentinel already runs per-machine on the machine that owns the responding session (it registers under
+that session's own bind token — slack-followthrough-generalization §4.5). This change only alters
+*where in the local config file* the enable flag is read; it introduces no cross-machine state, no
+user-facing notice, no durable state, and no URLs. Enabling it on one machine does not and should not
+implicitly enable it on another — each machine's config is authoritative for its own sessions.
+
+## 8. Rollback cost
+
+Pure code change — revert and ship as a patch. No persistent state, no data migration, no user-visible
+regression during the rollback window. The generated hook is regenerated on the next migration in
+either direction. A deployed agent that had set top-level `actionClaim.enabled:true` would, on
+rollback, simply return to un-enablable (the pre-fix state) — no cleanup needed.
+
+## Conclusion
+
+The review confirms a low-risk, additive config-resolution fix that makes a previously un-enablable
+default-off sentinel actually turnable-on on real (array-`messaging`) installs, with the legacy
+object-shape fully back-compatible. It adds the missing test coverage (array-shaped `messaging`) that
+would have caught the original bug. Clear to ship. Follow-up worth tracking: the sibling default-ON
+`messaging.*` sentinels (`toneGate`, `outboundAdvisory`) share the same latent unreachability but are
+masked by their on-by-default posture — noted here, not fixed in this change (out of scope).
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** not required (Tier-1)
+**Independent read of the artifact: n/a**
+
+---
+
+## Evidence pointers
+
+- `tests/integration/action-claim-config-shape.test.ts` — array-shaped `messaging` + top-level
+  `actionClaim`: enablement, tuning-knob read, explicit-false off-switch, object-shape back-compat.
+- `tests/unit/action-claim-hook-slack.test.ts` — hook-body array-safe resolution assertion.
+- Existing `tests/integration/action-claim-route.test.ts` (14) + `tests/e2e/action-claim-lifecycle.test.ts`
+  (4) + `tests/unit/generated-hooks-parse.test.ts` (25) + `tests/unit/migrate-actionclaim-slack-devgate.test.ts`
+  (5) all stay green; `tsc --noEmit` clean.
+- `docs/investigations/s7-slack-delivery-repro-2026-07-04.md` — the S7 keystone investigation that
+  surfaced this bug (the merged #1361 fix could not be turned on).
+
+---
+
+## Class-Closure Declaration (display-only mirror)
+
+- **`defectClass`** — `config-unreachable-on-shape` (`novel`; nearestExistingClass:
+  `feature-un-enablable`; includes: a config gate whose dot-path is unreachable given the container's
+  real runtime shape, e.g. a key nested under an array-valued parent; excludes: a feature disabled by a
+  correctly-read explicit flag). Enters `status: "unconfirmed"` pending operator confirmation, so this
+  fix carries `closure: gap` (below), not `closure: guard`.
+- **`closure`** — `gap` — the class-level guard (a lint that flags a `messaging.<x>` dot-path read when
+  `messaging` is array-shaped in the shipped config, or a shape-fuzzing test harness for config gates)
+  is out of scope for this fix.
+- **`guardEvidence`** — n/a for `closure: gap`.
+- **`gap`** — tracked as a standards-gap follow-up: "config-gate shape-reachability lint/fuzz — a
+  default-off feature gated on an unreachable dot-path is un-enablable; add a guard that fails when a
+  gate reads `messaging.<child>.*` given `messaging` ships as an array." (This change ships the direct
+  regression test for THIS feature; the class-level guard is the tracked gap.)