instar 1.3.765 → 1.3.766

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.765",
+  "version": "1.3.766",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,7 @@
     "test:contract": "node scripts/run-contract-tests.js",
     "test:contract:raw": "vitest run --config vitest.contract.config.ts",
     "test:all": "vitest run && vitest run --config vitest.integration.config.ts && vitest run --config vitest.e2e.config.ts",
-    "lint": "tsc --noEmit && node scripts/lint-no-direct-destructive.js && node scripts/lint-no-direct-llm-http.js && node scripts/lint-no-direct-url-log.js && node scripts/lint-no-unfunneled-topic-creation.js && node scripts/lint-no-unfunneled-headless-launch.js && node scripts/lint-no-unbounded-llm-spawn.js && node scripts/lint-no-unregistered-self-action.js && node scripts/lint-no-unfunneled-credential-write.js && node scripts/lint-state-registry.js && node scripts/lint-store-retention-declared.js && node scripts/lint-no-wholefile-sync-read.js && node scripts/lint-cas-emit-placement.js && node scripts/lint-journal-actuation-ban.js && node scripts/lint-no-blocking-process-scans.js && node scripts/lint-sync-subprocess-chokepoint.js && node scripts/lint-dev-agent-dark-gate.js && node scripts/lint-guard-manifest.js && node scripts/lint-llm-attribution.js && node scripts/lint-no-mainthread-cartographer-walk.js && node scripts/lint-scrape-fixture-realness.js && node scripts/check-codex-rule1-drift.js && node scripts/lint-routing-registry-freshness.js && node scripts/lint-no-opus-claude-cli-gating.js && node scripts/lint-model-registry-freshness.mjs",
+    "lint": "tsc --noEmit && node scripts/lint-no-direct-destructive.js && node scripts/lint-no-direct-llm-http.js && node scripts/lint-no-direct-url-log.js && node scripts/lint-no-unfunneled-topic-creation.js && node scripts/lint-no-unfunneled-headless-launch.js && node scripts/lint-no-unbounded-llm-spawn.js && node scripts/lint-no-unregistered-self-action.js && node scripts/lint-no-unfunneled-credential-write.js && node scripts/lint-state-registry.js && node scripts/lint-store-retention-declared.js && node scripts/lint-no-wholefile-sync-read.js && node scripts/lint-cas-emit-placement.js && node scripts/lint-journal-actuation-ban.js && node scripts/lint-no-blocking-process-scans.js && node scripts/lint-sync-subprocess-chokepoint.js && node scripts/lint-dev-agent-dark-gate.js && node scripts/lint-guard-manifest.js && node scripts/lint-llm-attribution.js && node scripts/lint-no-mainthread-cartographer-walk.js && node scripts/lint-scrape-fixture-realness.js && node scripts/check-codex-rule1-drift.js && node scripts/lint-routing-registry-freshness.js && node scripts/lint-no-opus-claude-cli-gating.js && node scripts/lint-model-registry-freshness.mjs && node scripts/lint-no-unreachable-messaging-gate.js",
     "lint:routing-registry": "node scripts/lint-routing-registry-freshness.js",
     "lint:no-opus-claude-cli-gating": "node scripts/lint-no-opus-claude-cli-gating.js",
     "lint:model-freshness": "node scripts/lint-model-registry-freshness.mjs",

package/scripts/lint-no-unreachable-messaging-gate.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+/**
+ * lint-no-unreachable-messaging-gate.js — ban a DEFAULT-OFF config gate read at a
+ * `messaging.<child>.*` dot-path.
+ *
+ * The 2026-07-04 incident (PR #1379): the Action-Claim / Slack-followthrough
+ * sentinel gated on `messaging.actionClaim.enabled`, read as
+ * `liveConfig.get('messaging.actionClaim.enabled', false)`. On every real install
+ * `messaging` is a JSON ARRAY of adapter configs, so `getNestedValue` walks the
+ * array, `array['actionClaim']` is undefined, and it returns the `false` default.
+ * Because the feature defaults OFF, the master switch could never be set true — the
+ * feature was structurally UN-ENABLABLE in production. CI missed it because every
+ * test used an OBJECT-shaped `messaging`, which no real install uses.
+ *
+ * The sibling default-ON `messaging.*` sentinels (toneGate, outboundAdvisory) share
+ * the same unreachability but are masked — unreachable just means they stay ON. Only
+ * a DEFAULT-OFF gate is un-enablable. So this lint flags exactly the un-enablable
+ * shape: a `.get('messaging.<...>', false)` (a dot-path under the array-valued
+ * `messaging`, with a `false` default). The fix is to read the config from a
+ * reachable TOP-LEVEL key (e.g. `actionClaim`), as #1379 did.
+ *
+ * Conservative by design: it flags only the concrete `.get('messaging.*', false)`
+ * shape (the primary LiveConfig gate-read), not every messaging.* access. A
+ * genuinely-intended exception can be suppressed inline with
+ *   // lint-allow-messaging-gate: <reason>
+ * on the same or the immediately-preceding line.
+ *
+ * Exit 0 = clean. Exit 1 = at least one offending site (printed).
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * `.get('messaging.<child>...', false)` — optionally with a `<T>` generic and any
+ * whitespace. The `false` default is what makes it un-enablable (an unreachable
+ * default-true gate merely stays on). Matches both quote styles.
+ */
+export const UNREACHABLE_OFF_GATE =
+  /\.get\s*(?:<[^>]*>)?\s*\(\s*['"`]messaging\.[^'"`]+['"`]\s*,\s*false\b/;
+
+const SUPPRESS = /lint-allow-messaging-gate\s*:/;
+
+/** Scan raw source text; return 1-indexed line numbers of un-suppressed offenders. */
+export function scanText(text) {
+  const lines = text.split('\n');
+  const hits = [];
+  lines.forEach((line, i) => {
+    if (!UNREACHABLE_OFF_GATE.test(line)) return;
+    if (SUPPRESS.test(line)) return;
+    if (i > 0 && SUPPRESS.test(lines[i - 1])) return;
+    hits.push(i + 1);
+  });
+  return hits;
+}
+
+function walk(dir, out = []) {
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (e.name === 'node_modules' || e.name === 'templates') continue;
+      walk(full, out);
+    } else if (e.name.endsWith('.ts') && !e.name.endsWith('.test.ts')) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+function main() {
+  const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+  const SRC = path.join(ROOT, 'src');
+  const offenders = [];
+  for (const file of walk(SRC)) {
+    const rel = path.relative(ROOT, file);
+    const text = fs.readFileSync(file, 'utf-8');
+    for (const line of scanText(text)) {
+      offenders.push({ rel, line, text: text.split('\n')[line - 1].trim() });
+    }
+  }
+
+  if (offenders.length > 0) {
+    console.error(
+      'lint-no-unreachable-messaging-gate: default-OFF config gate at an unreachable messaging.<child>.* dot-path.\n' +
+        "On a real install `messaging` is a JSON ARRAY, so `messaging.<child>.*` resolves undefined → the `false`\n" +
+        'default → the feature is structurally UN-ENABLABLE (the PR #1379 bug). Read it from a reachable TOP-LEVEL\n' +
+        'key instead (e.g. `actionClaim.enabled`), or suppress with `// lint-allow-messaging-gate: <reason>`.\n',
+    );
+    for (const o of offenders) console.error(`  ${o.rel}:${o.line}  ${o.text}`);
+    process.exit(1);
+  }
+  console.log('lint-no-unreachable-messaging-gate: clean');
+  process.exit(0);
+}
+
+// Run the CLI scan only when executed directly (not when imported by a test).
+if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
+  main();
+}

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-07-04T23:42:04.602Z",
-  "instarVersion": "1.3.765",
+  "generatedAt": "2026-07-04T23:55:08.310Z",
+  "instarVersion": "1.3.766",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.766.md

@@ -0,0 +1,37 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Added a CI lint (`scripts/lint-no-unreachable-messaging-gate.js`, wired into the `lint` chain) that
+fails the build if any source reads a **default-OFF** config gate at a `messaging.<child>.*`
+dot-path. On a real install `messaging` is a JSON **array** of adapter configs, so
+`messaging.<child>.*` resolves `undefined` → the `false` default → the feature is structurally
+un-enablable. This is the class-level guard for the PR #1379 bug (the Action-Claim / Slack-followthrough
+sentinel that couldn't be turned on). It flags only the concrete `.get('messaging.*', false)` shape,
+exempts default-`true` gates, and supports an inline `// lint-allow-messaging-gate: <reason>`
+suppression. Zero current offenders — a pure forward guard.
+
+## What to Tell Your User
+
+Nothing proactive — this is an internal build-time safety check. It only matters to developers: it
+stops a whole class of "the on-switch was written in a place the program can't read" mistakes from
+ever landing again, which is the exact bug that made the promise follow-through tracker impossible to
+turn on earlier. It is the automated backstop so a human doesn't have to remember that quirk.
+
+## Summary of New Capabilities
+
+- CI now refuses a default-off config gate placed at an unreachable position under the messaging list.
+- Points the author at the fix (move the switch to a reachable top-level setting) with a precise
+  file:line, or lets them suppress a deliberate exception visibly.
+- No runtime effect; a build-time guard only.
+
+## Evidence
+
+- `tests/unit/lint-no-unreachable-messaging-gate.test.ts` — 8 cases: flags the #1379 shape (generic +
+  plain, both quote styles); exempts default-true, non-messaging, and top-level `actionClaim`; honors
+  same-line and preceding-line suppression; the exported regex matches the incident line.
+- `node scripts/lint-no-unreachable-messaging-gate.js` → `clean` on current `main` (0 offenders).
+- Side-effects review: `upgrades/side-effects/lint-unreachable-messaging-gate.md`.

package/upgrades/side-effects/lint-unreachable-messaging-gate.eli16.md

@@ -0,0 +1,42 @@
+# ELI16 — a guard so the "un-turn-on-able switch" bug can't come back
+
+## The story so far
+
+Earlier today we found a safety feature whose on-switch was written in a spot the program could never
+read: the config's "messaging" section is a *list* of chat platforms, but the switch was addressed as
+if it were a labeled box inside that list. Lists don't have named boxes, so the program always found
+"nothing," and "nothing" means off. The feature was impossible to turn on, and every test had used a
+fake box-shaped config so nobody noticed. We fixed that specific feature (PR #1379). This change makes
+sure the *whole class* of that mistake can't happen again.
+
+## What this adds
+
+A tiny automated check (a "lint") that runs whenever the code is built or someone tries to commit. It
+scans the code for the exact broken shape: reading an **off-by-default** switch from a
+`messaging.<something>` address. Because "messaging" is a list, any such address is unreadable, and an
+off-by-default switch there can never be turned on — so the check fails the build and points at the
+line, telling the author to move the switch to a spot that actually works (a top-level setting).
+
+## Why it's careful (not annoying)
+
+- It only flags the genuinely-broken case: **off-by-default** switches. Switches that default to *on*
+  are left alone, because "unreadable" just means they quietly stay on — no harm.
+- It only looks at the one common way switches are read (`.get("messaging.x.enabled", false)`), so it
+  won't cry wolf on unrelated code.
+- If there's ever a real reason to keep such a line, an author can add a short "allow this on purpose"
+  comment and the check steps aside — but that choice is now visible in the code instead of silent.
+- Right now there are **zero** offending lines (the earlier fix removed the last one), so turning this
+  check on breaks nothing today — it's purely a guard for the future.
+
+## How we know it works
+
+Eight small tests feed the checker example lines: it correctly flags the exact bug shape (in a few
+spellings), correctly ignores the safe cases (default-on switches, top-level switches, non-messaging
+switches), and correctly honors the "allow this on purpose" comment. So the guard catches the mistake
+without blocking legitimate code.
+
+## The bigger idea
+
+This is the "Structure beats Willpower" principle in one line: instead of hoping future authors
+*remember* that "messaging" is a list and won't hold a switch, the build now *refuses* the mistake
+automatically. A guard that a human missed once shouldn't rely on a human not missing it again.

package/upgrades/side-effects/lint-unreachable-messaging-gate.md

@@ -0,0 +1,107 @@
+# Side-Effects Review — lint: ban default-off config gate at an unreachable messaging.* path
+
+**Version / slug:** `lint-unreachable-messaging-gate`
+**Date:** `2026-07-04`
+**Author:** `Echo`
+**Second-pass reviewer:** `not required (Tier-1)`
+
+## Summary of the change
+
+Adds `scripts/lint-no-unreachable-messaging-gate.js` (wired into the `lint` chain in `package.json`)
+and its unit test. The lint fails CI if any source file reads a **default-OFF** config gate at a
+`messaging.<child>.*` dot-path — the exact shape of the PR #1379 bug: on a real install `messaging`
+is a JSON **array**, so `messaging.<child>.*` resolves `undefined` → the `false` default → the
+feature is structurally un-enablable. It flags only the concrete `.get('messaging.*', false)`
+LiveConfig gate-read shape, exempts default-`true` gates (unreachable just leaves them on), and
+supports an inline `// lint-allow-messaging-gate: <reason>` suppression. Currently 0 offenders on
+`main` (PR #1379 removed the last one) — this is a pure forward guard.
+
+## Decision-point inventory
+
+- `scripts/lint-no-unreachable-messaging-gate.js` — **add** — a new CI lint gate.
+- `package.json` `lint` script — **modify** — append the new lint to the chain.
+- `tests/unit/lint-no-unreachable-messaging-gate.test.ts` — **add** — detector unit tests.
+
+## 1. Over-block
+
+The regex targets `.get('messaging.<...>', false)` specifically. A legitimate default-OFF gate that
+genuinely must live under `messaging` (none known) would be flagged — but the correct answer is to
+move it to a reachable top-level key (the whole point), and the inline suppression exists for a
+deliberate exception. Default-`true` gates and non-`messaging` paths are not flagged.
+
+## 2. Under-block
+
+It only catches the `.get(path, false)` shape. A default-off gate read via a cast
+(`(cfg as {...}).messaging?.x`) or a raw-file read (`cfg.messaging.x.enabled` in a generated hook)
+is not caught — a known, accepted limitation (the `.get` gate is the primary and highest-frequency
+pattern; the two others are rarer and harder to lint without false positives). Documented in the
+lint header.
+
+## 3. Level-of-abstraction fit
+
+Right layer: a build-time lint (cheap, deterministic, CI-enforced) is exactly the "Structure beats
+Willpower" guard for a class that a human/CI missed once (object-shaped-messaging tests hid it). It
+does not add runtime behavior or authority.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — this change has no runtime block/allow surface. It is a build-time CI lint. Its "authority"
+  is failing a build on a precise, suppressible pattern — not gating any live message or action.
+
+## 5. Interactions
+
+- **Shadowing:** none — it's an independent step appended to the end of the `lint` chain.
+- **Double-fire:** none.
+- **Races:** none — pure file scan at build time.
+- **Feedback loops:** none.
+
+## 6. External surfaces
+
+- **Install base / agents:** none at runtime — a CI/dev-time lint only.
+- **External systems / persistent state:** none.
+- **Operator surface:** no operator-facing action.
+
+## 6b. Operator-surface quality
+
+No operator surface — not applicable.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**machine-local BY DESIGN** — a build-time lint runs in CI / on a developer's checkout; it has no
+runtime, no cross-machine state, no notices, no URLs. It is identical everywhere it runs by
+construction.
+
+## 8. Rollback cost
+
+Pure additive tooling — revert the script + the one-line `package.json` edit + the test. No
+persistent state, no runtime effect, no user-visible change. Zero-cost back-out.
+
+## Conclusion
+
+A small, precise, suppressible CI lint that would have caught the PR #1379 un-enablable bug at the
+read site (`.get('messaging.actionClaim.enabled', false)`). 0 current offenders, so it is a pure
+forward guard closing the class the operator's live-enable attempt surfaced. Clear to ship.
+
+## Second-pass review (if required)
+
+**Reviewer:** not required (Tier-1)
+
+## Evidence pointers
+
+- `tests/unit/lint-no-unreachable-messaging-gate.test.ts` — 8 cases: flags the #1379 shape (generic +
+  plain + both quote styles), exempts default-true and non-messaging and top-level `actionClaim`,
+  honors same-line and preceding-line suppression, regex matches the incident line.
+- `node scripts/lint-no-unreachable-messaging-gate.js` → `clean` (0 offenders on current `main`).
+
+## Class-Closure Declaration (display-only mirror)
+
+- **`defectClass`** — `config-unreachable-on-shape` (the class named in the PR #1379 side-effects
+  artifact; the guard the operator asked be built to close it).
+- **`closure`** — `guard` — this lint IS the class-level guard: it structurally fails CI when a
+  default-off config gate is read at an unreachable `messaging.<child>.*` dot-path.
+- **`guardEvidence`** — `{ enforcementType: lint, citation: scripts/lint-no-unreachable-messaging-gate.js
+  (wired into package.json `lint`, run by .husky/pre-commit + CI), howCaught: it flags
+  `.get('messaging.<child>.*', false)` — the exact read shape of the #1379 master gate — so the
+  un-enablable gate can never re-land }`.