instar 1.3.1151 → 1.3.1153

package/dist/data/standards-guard-index.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "generatedFrom": "source-tree",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1151",
+  "packageVersion": "1.3.1153",
   "guards": [
     {
       "ref": "docs/audits/phase-b/f10-triage.md",

package/dist/data/standards-guard-index.meta.json

@@ -1,5 +1,5 @@
 {
-  "sha256": "2781a4e62937b5faedcefb2635981134a4f27ba058786b5d16b5017f41b017e9",
+  "sha256": "c9fe9271930f52c79239f9b43e4d3c873717dc1dd98744525290c8ccba4f07bf",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1151"
+  "packageVersion": "1.3.1153"
 }

package/dist/data/standards-registry.meta.json

@@ -2,5 +2,5 @@
   "sha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
   "articleCount": 88,
   "generatedFrom": "docs/STANDARDS-REGISTRY.md",
-  "packageVersion": "1.3.1151"
+  "packageVersion": "1.3.1153"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.1151",
+  "version": "1.3.1153",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/scripts/lint-no-unfunneled-tmux-literal-send.js

@@ -22,9 +22,33 @@
  * Structure > Willpower — a comment asking authors to remember is a wish; this
  * is the guarantee.
  *
- * Guardrail, not proof: a wrapper that builds the argv array dynamically could
- * still evade it. The declared duty stays "literal sends go through the
- * funnel"; this catches the direct pattern.
+ * SCOPE CORRECTED 2026-08-15. The previous header said only that "a wrapper that
+ * builds the argv array dynamically could still evade it". That understated the
+ * gap: the check was LINE-oriented and required `send-keys` and `'-l'` on the
+ * SAME line, so four PLAIN literal forms — none of them dynamic, none of them a
+ * wrapper — walked straight past it. Measured against the shipped check, with the
+ * one-line form as a positive control firing in the same run:
+ *
+ *   ["send-keys", "-l", p]                        CONTROL  exit 1 (caught)
+ *   [\n  "send-keys",\n  "-l",\n  p,\n]        exit 0 — EVADES
+ *   const F = "-l";      ["send-keys", F, p]      exit 0 — EVADES
+ *   const C = "send-keys"; [C, "-l", p]           exit 0 — EVADES
+ *   ["send-keys","-l",p]  // buildLiteralSendArgs exit 0 — EVADES
+ *
+ * The first is the one that matters: a multi-line argv array is simply how any
+ * formatter writes an array over the print width. The guard could be defeated by
+ * running prettier. The last is worse in kind — merely NAMING the funnel in a
+ * COMMENT on that line suppressed the check, so `// TODO: use buildLiteralSendArgs`
+ * beside a raw send silenced the guard that the TODO was admitting was needed.
+ *
+ * Now: comments are stripped quote-aware first, string constants are resolved
+ * per file, and the unit of matching is the ARRAY LITERAL (bracket-matched,
+ * bounded) rather than the line — which is what the original rule always meant.
+ *
+ * STILL not proof, and this is the honest remainder: an argv array assembled at
+ * RUNTIME (push(), concat(), spread of a computed list, a helper that returns the
+ * array) is invisible here. That is the gap the original header named, and it is
+ * the only one left. Closing it needs dataflow, not more patterns.
  */
 import fs from 'node:fs';
 import path from 'node:path';
@@ -46,20 +70,142 @@ function walk(dir, out = []) {
   return out;
 }
 
+/**
+ * Strip // and block comments WITHOUT touching string contents, replacing each
+ * removed character with a space so every byte offset — and therefore every
+ * reported line number — is preserved exactly.
+ */
+export function stripComments(src) {
+  let out = '';
+  let i = 0;
+  let quote = null;
+  while (i < src.length) {
+    const c = src[i];
+    const n = src[i + 1];
+    if (quote) {
+      out += c;
+      if (c === '\\') { out += n ?? ''; i += 2; continue; }
+      if (c === quote) quote = null;
+      i += 1;
+      continue;
+    }
+    if (c === '"' || c === "'" || c === '`') { quote = c; out += c; i += 1; continue; }
+    if (c === '/' && n === '/') {
+      while (i < src.length && src[i] !== '\n') { out += ' '; i += 1; }
+      continue;
+    }
+    if (c === '/' && n === '*') {
+      out += '  '; i += 2;
+      while (i < src.length && !(src[i] === '*' && src[i + 1] === '/')) {
+        out += src[i] === '\n' ? '\n' : ' ';
+        i += 1;
+      }
+      out += '  '; i += 2;
+      continue;
+    }
+    out += c;
+    i += 1;
+  }
+  return out;
+}
+
+/**
+ * Identifiers bound to a plain string literal in THIS file. An identifier bound
+ * more than once to DIFFERENT values is UNRESOLVABLE and dropped, so an ambiguous
+ * name can never be substituted into a match — ambiguity fails toward NOT flagging,
+ * because a guess that fails someone's build is the expensive direction.
+ */
+export function collectStringConsts(code) {
+  const seen = new Map();
+  const conflicting = new Set();
+  const DECL = /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(['"`])([^'"`\n]*)\2/g;
+  let m;
+  while ((m = DECL.exec(code)) !== null) {
+    const [, name, , value] = m;
+    if (seen.has(name) && seen.get(name) !== value) conflicting.add(name);
+    else seen.set(name, value);
+  }
+  for (const name of conflicting) seen.delete(name);
+  return seen;
+}
+
+/**
+ * Every bracket-matched array literal in the source, as {text, line}. Bounded:
+ * an array longer than MAX_ARRAY_CHARS is truncated rather than scanned whole, so
+ * a pathological file cannot make this quadratic. Unbalanced brackets simply
+ * yield no region — the check fails toward NOT flagging.
+ */
+const MAX_ARRAY_CHARS = 4000;
+export function arrayRegions(code) {
+  const regions = [];
+  for (let i = 0; i < code.length; i++) {
+    if (code[i] !== '[') continue;
+    let depth = 0;
+    let quote = null;
+    let j = i;
+    for (; j < code.length && j - i < MAX_ARRAY_CHARS; j++) {
+      const c = code[j];
+      if (quote) {
+        if (c === '\\') { j += 1; continue; }
+        if (c === quote) quote = null;
+        continue;
+      }
+      if (c === '"' || c === "'" || c === '`') { quote = c; continue; }
+      if (c === '[') depth += 1;
+      else if (c === ']') { depth -= 1; if (depth === 0) break; }
+    }
+    if (depth !== 0) continue;
+    const text = code.slice(i, j + 1);
+    const line = code.slice(0, i).split('\n').length;
+    regions.push({ text, line });
+  }
+  return regions;
+}
+
+/** True when the resolved region is a raw literal `send-keys -l` argv. */
+export function regionViolates(regionText, consts) {
+  let t = regionText;
+  for (const [name, value] of consts) {
+    t = t.replace(new RegExp(`\\b${name}\\b`, 'g'), `'${value}'`);
+  }
+  if (!/['"`]send-keys['"`]/.test(t)) return false;
+  if (!/['"`]-l['"`]/.test(t)) return false;
+  // Already funnelled — checked on COMMENT-STRIPPED code, so merely naming the
+  // funnel in a comment can no longer silence the guard.
+  if (t.includes('buildLiteralSendArgs')) return false;
+  return true;
+}
+
+export function scanSource(code) {
+  const stripped = stripComments(code);
+  const consts = collectStringConsts(stripped);
+  const hits = [];
+  for (const region of arrayRegions(stripped)) {
+    if (regionViolates(region.text, consts)) {
+      hits.push({ line: region.line, text: region.text.replace(/\s+/g, ' ').trim() });
+    }
+  }
+  return hits;
+}
+
+// DIRECT-INVOCATION GUARD. Without it, importing this module to unit-test the
+// helpers above runs the whole src/ scan and calls process.exit(1) the moment the
+// repo has a real violation — killing the importing process. Four other lints hit
+// exactly that this week; the guard is the same fix.
+const invokedDirectly =
+  process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url));
+
+if (invokedDirectly) runLint();
+
+function runLint() {
 const violations = [];
 
 for (const file of walk(SRC)) {
   const rel = path.relative(REPO, file);
   if (EXEMPT.has(rel)) continue;
-  const lines = fs.readFileSync(file, 'utf-8').split('\n');
-  lines.forEach((line, i) => {
-    // Match an argv array literal carrying both 'send-keys' and a '-l' flag.
-    if (!line.includes('send-keys')) return;
-    if (!/['"]-l['"]/.test(line)) return;
-    // Already funnelled.
-    if (line.includes('buildLiteralSendArgs')) return;
-    violations.push({ rel, line: i + 1, text: line.trim() });
-  });
+  for (const hit of scanSource(fs.readFileSync(file, 'utf-8'))) {
+    violations.push({ rel, line: hit.line, text: hit.text });
+  }
 }
 
 if (violations.length > 0) {
@@ -76,3 +222,4 @@ if (violations.length > 0) {
 }
 
 console.log(`✓ tmux literal sends funnelled (scanned ${walk(SRC).length} files, 0 unfunneled)`);
+}

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-08-15T00:48:31.405Z",
-  "instarVersion": "1.3.1151",
+  "generatedAt": "2026-08-15T01:31:14.741Z",
+  "instarVersion": "1.3.1153",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

package/src/data/standards-guard-index.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "generatedFrom": "source-tree",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1151",
+  "packageVersion": "1.3.1153",
   "guards": [
     {
       "ref": "docs/audits/phase-b/f10-triage.md",

package/src/data/standards-guard-index.meta.json

@@ -1,5 +1,5 @@
 {
-  "sha256": "2781a4e62937b5faedcefb2635981134a4f27ba058786b5d16b5017f41b017e9",
+  "sha256": "c9fe9271930f52c79239f9b43e4d3c873717dc1dd98744525290c8ccba4f07bf",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1151"
+  "packageVersion": "1.3.1153"
 }

package/src/data/standards-registry.meta.json

@@ -2,5 +2,5 @@
   "sha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
   "articleCount": 88,
   "generatedFrom": "docs/STANDARDS-REGISTRY.md",
-  "packageVersion": "1.3.1151"
+  "packageVersion": "1.3.1153"
 }

package/upgrades/1.3.1152.md

@@ -0,0 +1,54 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+`scripts/lint-no-unfunneled-tmux-literal-send.js` now matches the bracket-matched ARGV ARRAY rather
+than a single line.
+
+That lint guards the `send-keys -l` argv ceiling (~16.2 KB) — the class behind the 2026-08-04 incident
+where a ~40 KB prompt blew the ceiling, the circuit breaker misread the opaque send error as a provider
+rate-limit and tripped 14 consecutive times, and ten LLM-backed components sat at 76-100% error rate.
+
+It required `send-keys` and `'-l'` on the SAME line, so four PLAIN literal forms evaded it — measured
+against the shipped check with the one-line form as a positive control firing in the same run: a
+multi-line array (what any formatter produces), the flag lifted into a const, the verb lifted into a
+const, and — worst in kind — merely NAMING the funnel in a comment on that line, so
+`// TODO: use buildLiteralSendArgs` beside a raw send silenced the guard the TODO was admitting was
+needed.
+
+The first is the one that matters: **the guard could be defeated by running prettier.**
+
+Added: `stripComments` (quote-aware, line-number preserving), `collectStringConsts` (per-file;
+conflicting bindings dropped as unresolvable), `arrayRegions` (bracket-matched, string-aware, bounded),
+`regionViolates` and `scanSource`. The rule, the exemption and the message are unchanged. Also added a
+direct-invocation guard — importing the module previously ran the whole `src/` scan and could
+`process.exit(1)`, which is why its internals had never been unit-tested.
+
+## What to Tell Your User
+
+Nothing changes for you. A build-time check that stops a known way of breaking terminal sends could be
+walked past just by letting a code formatter split a list across lines — no intent required. It now
+reads the whole list instead of one line. Nothing you use behaves differently; a failure mode that once
+took down ten components for hours got harder to reintroduce by accident.
+
+## Summary of New Capabilities
+
+None. No new command, endpoint, setting, or runtime behaviour. A CI guard that a code formatter could
+defeat no longer can be.
+
+## Evidence
+
+- `tests/unit/tmux-send-lint-array-scope.test.ts` — 18/18 green.
+- **Negative control: 6 of 18 fail** against the shipped line-oriented behaviour; the other 12 pass both
+  ways and are the controls. Source restored byte-exact afterwards (sha match, zero markers left).
+- Six anti-over-block controls, because this lint blocks commits: send-keys without the flag; a genuinely
+  funnelled call; two SEPARATE arrays never joined; a const bound to a different flag; an example living
+  entirely inside a comment; and an identifier with conflicting bindings left unresolvable.
+- Real tree: `exit 0` before AND after, 1,631 files scanned.
+- Full `npm run lint` chain green; chain membership verified explicitly rather than inferred.
+- **Scope CORRECTED, not restated:** the old header claimed only that a dynamically-built argv could
+  evade it. None of the four measured evasions is dynamic. The header now names what was actually
+  missing, and the genuine remainder (a runtime-assembled array — push/concat/spread/helper).

package/upgrades/1.3.1153.md

@@ -0,0 +1,62 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The atomic-writes consistency test could not detect the defect it exists to detect.
+
+Measured rather than argued: a bare `fs.writeFileSync` of durable session state, inserted into
+`saveSession` — a DECLARED method of a DECLARED module — passed all 21 of its assertions.
+
+Three causes, all fixed:
+
+1. **Scoping.** `inSaveMethod` was set when a method NAME appeared on a line and never reset, while
+   `hasWriteFile`/`hasRename` were re-zeroed at each occurrence. Only the window from the LAST name
+   mention to EOF reached the assertion — 125 of 617 lines (20%) in `StateManager.ts`, leaving three
+   of its four declared methods structurally unreachable. Bodies are now brace-matched per method.
+2. **File-scope substring checks.** `source.includes('renameSync')` and `source.includes('.tmp')` are
+   satisfied by one occurrence anywhere in the file, comments included. Pairing is now per body.
+3. **Silent declaration rot.** A missing file was `it.skip`ped and a missing method never set the
+   flag, so a rename dropped a module out of coverage without a sound. Both are failures now — and
+   enabling that found two immediately: `saveState` has ZERO occurrences in `StateManager.ts` and in
+   `QuotaTracker.ts`. QuotaTracker's real writer, `updateState()`, is atomic and had never been
+   verified by this test. The declared list is corrected here.
+
+**Delegation.** `StateManager` funnels every write through a private `atomicWrite()`. A naive
+per-method rule would have failed the best-written module in the set for being well written, so one
+level of `this.helper()` delegation is resolved and the funnel is what gets verified — which means
+`StateManager`'s writes are now genuinely checked, where before nothing checked them.
+
+Added `tests/helpers/atomicWriteScope.ts` (`stripComments`, `methodBodies`, `delegateTargets`,
+`classifyMethod`) and `tests/unit/atomic-write-scope.test.ts`.
+
+**Declared open in the source:** the module list is curated at 7 entries and says nothing about the
+hundreds of other files under `src/` that call `writeFileSync`; delegation resolves one level within
+one file; only `writeFileSync`/`renameSync` are recognised.
+
+**The production code is atomic** everywhere the check now looks. This fixes a weak instrument, not a
+live corruption bug.
+
+## What to Tell Your User
+
+None — internal change (no user-facing surface).
+
+## Summary of New Capabilities
+
+None — internal change (no user-facing surface).
+
+## Evidence
+
+- `tests/unit/atomic-write-scope.test.ts` — 18/18 green (6 defect cases, 6 over-block controls, 6 primitives).
+- `tests/unit/atomic-writes-consistency.test.ts` — 32/32 green against the real tree.
+- **Both-directions proof in ONE worktree**, shipped check restored from git alongside the new one so
+  subject and control share a boundary: shipped → **21/21 PASSED** against the mutation; new →
+  **1 failed / 31 passed**, naming file, method, deciding body and line. `src/core/StateManager.ts`
+  restored byte-exact (sha match, zero markers, zero stray files).
+- Six over-block controls pass under BOTH behaviours — genuine funnel delegation, in-body
+  tmp-then-rename, a method that writes nothing, a commented-out write, a call site vs a declaration,
+  and worst-verdict-wins across duplicate declarations.
+- `tsc --noEmit` exit 0 — with the boundary stated: `tsconfig.json` excludes `tests`, so that run says
+  nothing about these files.

package/upgrades/side-effects/atomic-writes-method-scope.md

@@ -0,0 +1,152 @@
+# Side-Effects Review — atomic-writes check scopes to method bodies
+
+**Version / slug:** `atomic-writes-method-scope`
+**Date:** `2026-08-15`
+**Author:** `echo`
+**Second-pass reviewer:** `not required — Tier 1. Test-only change; no file under src/, scripts/, .husky/ or skills/ is touched, so there is no runtime path and no shipped behaviour. The change makes an existing check stricter and adds no authority.`
+
+## Summary of the change
+
+`tests/unit/atomic-writes-consistency.test.ts` verifies that state-writing modules use
+write-to-tmp-then-rename, so a crash mid-write cannot leave a truncated state file. **It could not
+detect the defect it exists to detect.**
+
+Measured, not argued — a bare `fs.writeFileSync` of durable session state inserted into
+`saveSession`, a DECLARED method of a DECLARED module:
+
+| check | verdict against that mutation |
+|---|---|
+| shipped | **21/21 PASSED** |
+| this change | **1 failed / 31 passed**, naming file, method, deciding body, line |
+
+Both runs were made in the SAME worktree against the SAME mutated source, with the shipped check
+restored from git alongside the new one — subject and control share a boundary rather than being
+compared across two checkouts.
+
+Three causes, all fixed:
+
+1. **Scoping.** `inSaveMethod` was set when a method NAME appeared on a line and never reset, while
+   `hasWriteFile`/`hasRename` were re-zeroed at each occurrence. Only the window from the LAST name
+   mention to EOF survived to the assertion — measured at **125 of 617 lines (20%)** in
+   `StateManager.ts`, leaving three of its four declared methods structurally unreachable. Within
+   that window the booleans were file-scope, so a rename in one method vouched for a write in another.
+2. **File-scope substring checks.** `source.includes('renameSync')` and `source.includes('.tmp')` are
+   satisfied by one occurrence anywhere, comments included.
+3. **Silent declaration rot.** A missing file was `it.skip`ped; a missing method simply never set the
+   flag. Both are failures now.
+
+## What enabling (3) immediately found
+
+**Two of the ten declared (module, method) pairs name methods that do not exist.** `saveState` has
+ZERO occurrences in `src/core/StateManager.ts` and ZERO in `src/monitoring/QuotaTracker.ts` — verified
+by grep with a control (`saveSession(`, `appendEvent(`, `persistUsers(` all found). QuotaTracker's
+real writer is `updateState()`, which is correctly atomic and had never been verified by this test.
+The declared list is corrected in the same change.
+
+## Decision-point inventory
+
+- `tests/helpers/atomicWriteScope.ts` — ADD. `stripComments` (quote-aware, line-count preserving),
+  `methodBodies` (brace-matched, string-aware, declaration-vs-call aware), `delegateTargets`,
+  `classifyMethod`.
+- `tests/unit/atomic-writes-consistency.test.ts` — REWRITTEN to per-method assertions; declared list
+  corrected; missing file/method now fail; anti-vacuity assertion added.
+- `tests/unit/atomic-write-scope.test.ts` — ADD. 18 tests pinning the primitives and both directions.
+- No file under `src/`, `scripts/`, `.husky/` or `skills/` is touched. No runtime decision added.
+
+## 1. Over-block
+
+**The dominant risk, and it nearly bit me.** The obvious fix — require a rename in each declared
+method's own body — would have FAILED on `StateManager`, the best-written module in the set, because
+it routes every write through a private `atomicWrite()` funnel and its save methods contain no write
+call at all. Failing the single-funnel pattern this codebase argues for everywhere else would be a
+false red on exemplary code.
+
+So one level of `this.helper()` delegation is resolved and the funnel is what gets verified — which
+also means `StateManager`'s writes are now genuinely checked, where previously nothing checked them.
+
+Six controls, each with a test, all passing under BOTH the old and new behaviour:
+
+- delegation to a genuine atomic funnel → `atomic-via-funnel`, not a violation;
+- in-body tmp-then-rename → `atomic-inline`;
+- a method that legitimately writes nothing → `no-write`, no invented violation;
+- a commented-out write is not a write;
+- a CALL site (`this.saveSession({...})` inside another method) is not a declaration — treating it as
+  one is precisely how the old flag conflated two methods;
+- an unbalanced brace yields no body rather than a wrong region, so a syntax error elsewhere cannot
+  become a false verdict here.
+
+**Verified against the real tree: 32/32 green.** The production code is atomic everywhere the check
+now looks, including through the funnel.
+
+**A defect in my own helper, caught by these controls before it shipped:** the first `methodBodies`
+required a declaration at line start. That works on real source (which indents declarations) and
+returned `found: false` for every hand-written fixture — so five tests failed loudly rather than
+passing vacuously. The matcher now decides by the PRECEDING token (start / `{` / `}` / `;` after
+skipping modifiers), which rejects `this.save(` and `helper(save(1))` as calls while accepting a
+declaration that does not begin its own line.
+
+## 2. Under-block
+
+Stated in the source rather than implied:
+
+- **Population.** The module list is CURATED and holds 7 entries. Hundreds of files under `src/` call
+  `writeFileSync`; this test says nothing about any of them. A heuristic sweep suggested a state-writing
+  population in the low hundreds, but that heuristic missed 2 of the 7 KNOWN-good modules, so it is not
+  a defect count and is not quoted as one. Widening the population is separate work with real
+  over-block risk and is deliberately not attempted here.
+- **Delegation depth.** One level, one file. A helper calling another helper, or an imported writer,
+  is not resolved — that needs a symbol graph, not text.
+- **Write vocabulary.** Only `writeFileSync`/`renameSync`. A module writing via a stream, `fs.promises`,
+  or a third-party helper is invisible.
+
+## 3. Level-of-abstraction fit
+
+Same layer as the existing check — source-text analysis in a unit test, no AST, no type information,
+no new dependency. The brace matcher is the minimum needed to answer "which method is this line in?",
+which is the question the original flag was trying and failing to answer.
+
+## 4. Signal vs authority compliance
+
+A test, not a runtime authority. It gates CI only. It gained teeth (it can now fail) but no new
+decision-making power over agent behaviour.
+
+## 5. Interactions
+
+- Runs in the existing unit shards; no new script, no lint-chain entry, no CI wiring change.
+- `tsc --noEmit` exit 0 — **but stated honestly: `tsconfig.json` excludes `tests`, so that run says
+  nothing about these files.** Their correctness is evidenced by the suite passing, not by the compiler.
+- No source module, route, config key, or state file touched.
+
+## 6. External surfaces
+
+None. Developer tooling. The Agent Awareness Standard does not apply — no agent capability is added.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**Machine-local by design, and correct.** A unit test reads files in one checkout and returns an exit
+code. No durable state, no user-facing notice, no generated URL, no runtime decision — nothing to
+replicate, merge on read, or strand on a topic transfer. Every machine runs it over its own checkout
+of the same tracked source and reaches the same verdict; determinism comes from the source tree, not
+from coordination.
+
+## 8. Rollback cost
+
+`git revert` of three test files. No migration, no state, no deployed artifact, no runtime impact.
+
+## Conclusion
+
+Ship. A check that could not fail on its own subject now fails on it, two stale declarations are
+repaired, the best-written module in the set is verified for the first time, and the limits are named
+in the source rather than implied.
+
+## Evidence pointers
+
+- `tests/unit/atomic-write-scope.test.ts` — 18/18 green (6 defect cases, 6 over-block controls, 6 primitives).
+- `tests/unit/atomic-writes-consistency.test.ts` — 32/32 green against the real tree.
+- **Both-directions proof in ONE worktree:** shipped check vs the mutation → 21/21 PASSED; new check
+  vs the SAME mutation → 1 failed / 31 passed. `src/core/StateManager.ts` restored byte-exact
+  (sha match, zero probe markers, zero stray files).
+- Stale declarations verified by grep with a control that fired.
+- `tsc --noEmit` exit 0 (boundary stated above: tests are excluded from that config).
+- Tier **1** declared: `classifyTier` reports riskFloor 1 with no safety-invariant match, and `tests/`
+  is outside `inScope()`, so the size heuristic contributes nothing either.

package/upgrades/side-effects/tmux-send-lint-array-scope.md

@@ -0,0 +1,122 @@
+# Side-Effects Review — tmux send-keys guard matches the array, not the line
+
+**Version / slug:** `tmux-send-lint-array-scope`
+**Date:** `2026-08-15`
+**Author:** `echo`
+**Second-pass reviewer:** `not required — Tier 1 (CI-only lint script; no runtime path). The rule is unchanged; the check now reads the unit it always meant (the argv array) instead of a single line.`
+
+## Summary of the change
+
+`scripts/lint-no-unfunneled-tmux-literal-send.js` guards the `send-keys -l` argv ceiling (~16.2 KB).
+The 2026-08-04 incident it exists to prevent: a ~40 KB prompt blew the ceiling, `LlmCircuitBreaker`
+misclassified the opaque send error as a provider rate-limit and tripped 14 consecutive times while ten
+LLM-backed components sat at 76-100% error rate.
+
+The check required `send-keys` AND `'-l'` on the SAME LINE. Measured against the shipped check, with the
+one-line form as a positive control firing in the same run:
+
+| form | shipped |
+|---|---|
+| `["send-keys", "-l", p]` — POSITIVE CONTROL | exit 1 (caught) |
+| the same array across 5 lines | **exit 0 — EVADES** |
+| `const F = "-l"; ["send-keys", F, p]` | **exit 0 — EVADES** |
+| `const C = "send-keys"; [C, "-l", p]` | **exit 0 — EVADES** |
+| `["send-keys","-l",p] // buildLiteralSendArgs` | **exit 0 — EVADES** |
+
+The unit of matching is now the bracket-matched ARRAY LITERAL, over comment-stripped, const-resolved
+source. The rule, the exemption and the message are unchanged.
+
+## Decision-point inventory
+
+- `stripComments(src)` — ADD — quote-aware; replaces removed bytes with spaces so line numbers are exact.
+- `collectStringConsts(code)` — ADD — per-file identifier → literal; conflicting bindings dropped.
+- `arrayRegions(code)` — ADD — bracket-matched, string-aware, bounded at 4000 chars per region.
+- `regionViolates(text, consts)` — ADD — resolves then applies the EXISTING two patterns.
+- `scanSource(code)` — ADD — the composed scan, extracted so matching is testable.
+- Direct-invocation guard — ADD — the scan runs only when invoked directly.
+- The `EXEMPT` set, the two patterns, the violation message and exit codes — UNCHANGED.
+- No runtime block/allow decision added or modified. CI-time only.
+
+## 1. Over-block
+
+The failure that matters: this lint blocks commits, and a check that flags correct code gets switched
+off. Six controls, each with a test, all passing under BOTH old and new behaviour:
+
+- `send-keys` WITHOUT `-l` is not flagged (only the literal form has the ceiling).
+- A genuinely funnelled `buildLiteralSendArgs(...)` call is not flagged.
+- **Two separate arrays are never joined** — an unrelated `["ls", "-l"]` cannot complete a send-keys
+  array. This is the whole reason the unit is a bracket-matched region rather than a line window.
+- A const bound to a different flag is not flagged.
+- An example living entirely inside a comment is not flagged — which is what makes it safe to document
+  the bad pattern, including in this file and the ELI16.
+- An identifier bound twice to DIFFERENT values is unresolvable and never substituted.
+
+Unbalanced brackets yield no region, so a syntax error elsewhere cannot become a false accusation.
+
+**Verified against the real tree: exit 0 before AND after**, scanning 1,631 files. No new flags.
+
+## 2. Under-block
+
+Stated in the source, and it is a CORRECTION rather than a restatement. The old header claimed only
+that "a wrapper that builds the argv array dynamically could still evade it" — true, but it understated
+the gap, since none of the four measured evasions is dynamic or a wrapper. The header now names what was
+actually missing and what genuinely remains:
+
+- An argv array assembled at RUNTIME — `push()`, `concat()`, spread of a computed list, or a helper that
+  returns the array. That is the original declared gap and it is the only one left.
+- Closing it needs dataflow, not more patterns.
+
+## 3. Level-of-abstraction fit
+
+Same layer as the existing check — regex over source text, no AST, no type information, no new
+dependency. Bracket matching is the minimum needed to read an array literal as one unit; going further
+(a parser) would be a different check at a different layer.
+
+## 4. Signal vs authority compliance
+
+Unchanged. A CI guard, not a runtime authority. It pushes callers toward `buildLiteralSendArgs()`; the
+funnel itself stays exempt.
+
+## 5. Interactions
+
+- `npm run lint` chain — membership verified explicitly (in the `lint` chain CI runs, not merely
+  referenced by a standalone entry); full chain green.
+- The direct-invocation guard changes import behaviour from "runs the src/ scan and may exit(1)" to
+  "exports only". Nothing imported this module before, so no caller changes.
+- No source module, route, config key, or state file touched.
+
+## 6. External surfaces
+
+None. Developer tooling, not an agent capability; the Agent Awareness Standard does not apply.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**Machine-local BY DESIGN, and correctly so — not an unexamined assumption.** A CI-time source scan with
+no runtime surface: it reads files in one checkout and exits. No durable state, no user-facing notice, no
+generated URL, no runtime decision — so nothing to replicate, nothing to merge on read, nothing that can
+strand on a topic transfer. Every machine runs it over its own checkout of the same tracked source and
+reaches the same verdict; determinism comes from the source tree, not from coordination. Resolution is
+explicitly per-file, so it cannot depend on the rest of the checkout, let alone another machine.
+
+## 8. Rollback cost
+
+`git revert` of one script plus the added test file. No migration, no state, no deployed artifact.
+
+## Conclusion
+
+Ship. Four evasions closed on a guard with a real production incident behind it, six anti-over-block
+controls added, the stated scope corrected rather than restated, and the import hazard removed.
+
+## Evidence pointers
+
+- `tests/unit/tmux-send-lint-array-scope.test.ts` — **18/18 green**.
+- **Negative control: 6 of 18 fail** against the shipped line-oriented behaviour. The other 12 pass both
+  ways — which is what makes them controls. Source restored byte-exact after the mutation (sha match,
+  zero markers left).
+- Reproduced by hand FIRST with a positive control firing in the same run; the control is what makes the
+  four EVADES verdicts mean anything.
+- Real-tree verdict: exit 0, 1,631 files scanned, before and after.
+- Full `npm run lint` chain green.
+- Tier **1** declared: risk floor 1, verified with a directional control (`SessionReaper.ts` → floor 2
+  with its reason named). The size heuristic suggests 2 on added LOC alone; stated openly, since the tier
+  I choose is the one that lets my own change through.