instar 1.3.1150 → 1.3.1152

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

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

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

@@ -1,5 +1,5 @@
 {
-  "sha256": "65b8fa203de000f59bf34d2f1ac5f30e0656f81da112a5f1dde281cf1be35b3c",
+  "sha256": "cb5b39009ce485f47b3010b819bd2a9c0dc4e2294204deaef41bf69db200fd41",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1150"
+  "packageVersion": "1.3.1152"
 }

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.1150",
+  "version": "1.3.1152",
   "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/scripts/lint-no-unfunneled-topic-creation.js

@@ -64,6 +64,86 @@ const PATTERNS = [
   /method\s*:\s*['"`]createForumTopic['"`]/,
 ];
 
+// ── Name resolution (added 2026-08-15) ────────────────────────────────────
+// The three patterns above each require `createForumTopic` as a string
+// LITERAL adjacent to the seam. Measured against the shipped lint, all three
+// of these reach the Bot API and NONE were caught:
+//
+//   const M = 'createForumTopic'; apiCall(M, {...});
+//   apiCall('createForum' + 'Topic', {...});
+//   const M = 'createForumTopic'; ({ method: M, ... });
+//
+// None of that is evasive — lifting a repeated string into a named constant
+// is ordinary tidying. Someone could step around the notification-flood
+// ceiling while making code NICER, and this lint would say `clean`. So the
+// method name is RESOLVED before the existing rules are applied; the rules
+// themselves are unchanged, they simply see through one level of naming.
+//
+// Deliberately NOT a parser. Everything below is bounded, per-file, and
+// fails toward NOT flagging, because this lint blocks commits and a check
+// that flags correct code gets switched off — which would cost more than the
+// hole it closes.
+
+const METHOD = 'createForumTopic';
+
+/**
+ * Fold ADJACENT string literals only: `'a' + 'b'` -> `'ab'`.
+ * Never invents text and never folds across an identifier, so
+ * `'createForum' + suffix` stays unresolved rather than guessed at.
+ */
+export function foldAdjacentLiterals(text) {
+  let out = text;
+  for (let i = 0; i < 5; i++) {
+    const next = out.replace(
+      /(['"`])([^'"`\n]*)\1\s*\+\s*(['"`])([^'"`\n]*)\3/g,
+      (_m, q, a, _q2, b) => `${q}${a}${b}${q}`,
+    );
+    if (next === out) break;
+    out = next;
+  }
+  return out;
+}
+
+/**
+ * Identifiers bound to a string literal (after folding) in THIS file.
+ * An identifier bound more than once to DIFFERENT values is UNRESOLVABLE and
+ * is dropped, so an ambiguous name can never be substituted into a match.
+ */
+export function collectStringConsts(lines) {
+  const seen = new Map();
+  const conflicting = new Set();
+  const DECL = /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*([^;]+)/;
+  for (const line of lines) {
+    const m = DECL.exec(line);
+    if (!m) continue;
+    const name = m[1];
+    const folded = foldAdjacentLiterals(m[2].trim());
+    const lit = /^(['"`])([^'"`\n]*)\1\s*$/.exec(folded);
+    if (!lit) continue;
+    const value = lit[2];
+    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;
+}
+
+/**
+ * Produce a view of one line with the method name resolved, for matching only.
+ * Substitution happens ONLY in the two seam positions the rules look at —
+ * never globally — so an unrelated identifier sharing a value is untouched.
+ */
+export function resolveLine(line, consts) {
+  let out = foldAdjacentLiterals(line);
+  out = out.replace(/(apiCall\(\s*)([A-Za-z_$][\w$]*)/g, (m, head, name) =>
+    consts.get(name) === METHOD ? `${head}'${METHOD}'` : m,
+  );
+  out = out.replace(/(method\s*:\s*)([A-Za-z_$][\w$]*)/g, (m, head, name) =>
+    consts.get(name) === METHOD ? `${head}'${METHOD}'` : m,
+  );
+  return out;
+}
+
 function listFiles() {
   const staged = process.argv.includes('--staged');
   if (staged) {
@@ -94,36 +174,54 @@ function listFiles() {
   return files;
 }
 
-let violations = 0;
-for (const rel of listFiles()) {
-  const normalized = rel.split(path.sep).join('/');
-  if (ALLOWLIST.has(normalized)) continue;
-  if (!EXTENSIONS.has(path.extname(normalized))) continue;
-  const full = path.join(ROOT, normalized);
-  let content;
-  try {
-    content = fs.readFileSync(full, 'utf-8');
-  } catch {
-    continue;
-  }
+export function scanFile(normalized, content) {
   const lines = content.split('\n');
+  const consts = collectStringConsts(lines);
+  const hits = [];
   for (let i = 0; i < lines.length; i++) {
+    const resolved = resolveLine(lines[i], consts);
     for (const pattern of PATTERNS) {
-      if (pattern.test(lines[i])) {
-        console.error(
-          `${normalized}:${i + 1} — raw createForumTopic invocation outside the budgeted funnel. ` +
-          `Route through TelegramAdapter.createForumTopic / findOrCreateForumTopic (declare an origin/label), ` +
-          `or add an allowlist entry here with a bounded-volume justification.`,
-        );
-        violations++;
-      }
+      if (pattern.test(resolved)) hits.push({ file: normalized, line: i + 1 });
     }
   }
+  return hits;
 }
 
-if (violations > 0) {
-  console.error(`\nlint-no-unfunneled-topic-creation: ${violations} violation(s). ` +
-    `See docs/STANDARDS-REGISTRY.md "Bounded Notification Surface".`);
-  process.exit(1);
+function runLint() {
+  let violations = 0;
+  for (const rel of listFiles()) {
+    const normalized = rel.split(path.sep).join('/');
+    if (ALLOWLIST.has(normalized)) continue;
+    if (!EXTENSIONS.has(path.extname(normalized))) continue;
+    const full = path.join(ROOT, normalized);
+    let content;
+    try {
+      content = fs.readFileSync(full, 'utf-8');
+    } catch {
+      continue;
+    }
+    for (const hit of scanFile(normalized, content)) {
+      console.error(
+        `${hit.file}:${hit.line} — raw createForumTopic invocation outside the budgeted funnel. ` +
+        `Route through TelegramAdapter.createForumTopic / findOrCreateForumTopic (declare an origin/label), ` +
+        `or add an allowlist entry here with a bounded-volume justification.`,
+      );
+      violations++;
+    }
+  }
+
+  if (violations > 0) {
+    console.error(`\nlint-no-unfunneled-topic-creation: ${violations} violation(s). ` +
+      `See docs/STANDARDS-REGISTRY.md "Bounded Notification Surface".`);
+    process.exit(1);
+  }
+  console.log('lint-no-unfunneled-topic-creation: clean');
 }
-console.log('lint-no-unfunneled-topic-creation: clean');
+
+// DIRECT-INVOCATION GUARD. Without this, importing this module to unit-test the
+// resolution helpers runs the whole repo scan — and calls process.exit(1) the
+// moment the repo has a real violation, killing the test runner. Three other
+// lints hit exactly that this window; the guard is the same fix.
+const invokedDirectly =
+  process.argv[1] && path.resolve(process.argv[1]) === path.resolve(__filename);
+if (invokedDirectly) runLint();

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-08-15T00:12:54.107Z",
-  "instarVersion": "1.3.1150",
+  "generatedAt": "2026-08-15T01:02:42.043Z",
+  "instarVersion": "1.3.1152",
   "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.1150",
+  "packageVersion": "1.3.1152",
   "guards": [
     {
       "ref": "docs/audits/phase-b/f10-triage.md",

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

@@ -1,5 +1,5 @@
 {
-  "sha256": "65b8fa203de000f59bf34d2f1ac5f30e0656f81da112a5f1dde281cf1be35b3c",
+  "sha256": "cb5b39009ce485f47b3010b819bd2a9c0dc4e2294204deaef41bf69db200fd41",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1150"
+  "packageVersion": "1.3.1152"
 }

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

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

package/upgrades/1.3.1151.md

@@ -0,0 +1,62 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+`scripts/lint-no-unfunneled-topic-creation.js` now resolves the Telegram method name before applying
+its rules.
+
+That lint enforces the **Bounded Notification Surface** standard — the last-resort budget on
+automatically-created forum topics, added after the third topic-spam incident. Its three patterns each
+required `createForumTopic` as a string LITERAL adjacent to the seam, so all three of these reached the
+Bot API uncounted while the build reported `clean`:
+
+```js
+const M = 'createForumTopic'; apiCall(M, { name: 'x' });
+apiCall('createForum' + 'Topic', { name: 'x' });
+const M = 'createForumTopic'; ({ method: M, name: 'x' });
+```
+
+Measured against the shipped lint with a positive control (the bare literal) firing in the same run:
+control caught, all three EVADE.
+
+None of that is evasive — lifting a repeated string into a named constant is ordinary tidying. Someone
+could step around a notification-flood ceiling while making code *nicer*, and nothing would say a word.
+
+Added: `foldAdjacentLiterals` (folds `'a' + 'b'` only, never across an identifier),
+`collectStringConsts` (per-file identifier → literal; an identifier bound twice to different values is
+dropped as unresolvable), `resolveLine` (substitutes ONLY at the two seam positions), and `scanFile`
+(extracted so matching is testable). `PATTERNS`, `ALLOWLIST` and the violation message are unchanged.
+
+Also added: a **direct-invocation guard**. Importing this module previously ran the whole repo scan and
+called `process.exit(1)` on the first real violation, killing the importing process — which is why its
+internals had never been unit-tested. Three other lints hit the same hazard this week.
+
+## What to Tell Your User
+
+Nothing changes for you. A build-time check that stops features from creating unlimited Telegram topics
+could be walked past by giving a string a name first — an ordinary bit of tidying, not a trick. It now
+sees through that. Nothing you use behaves differently; a category of notification flood just got harder
+to ship by accident.
+
+## Summary of New Capabilities
+
+None. No new command, endpoint, setting, or runtime behaviour. A CI guard that was defeatable by a local
+constant is no longer defeatable by one.
+
+## Evidence
+
+- `tests/unit/topic-creation-lint-resolution.test.ts` — 18/18 green.
+- **Negative control: 5 of 18 fail** against the shipped matching behaviour; the other 13 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: a const bound elsewhere, an identifier
+  that never reaches a seam, an identifier with conflicting bindings, a concatenation involving an
+  identifier, a longer look-alike method name, and seam-local (not global) substitution.
+- Real tree: `exit 0` before AND after — no new flags on existing code.
+- Full `npm run lint` chain green (57 steps); lint-chain membership verified explicitly rather than
+  inferred from a `package.json` reference.
+- **Declared open in the source:** cross-module names, runtime-built names, and anything needing
+  dataflow. Also named: the lint does not strip comments, which is pre-existing and neither fixed nor
+  worsened here.

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

package/upgrades/side-effects/topic-creation-lint-resolution.md

@@ -0,0 +1,135 @@
+# Side-Effects Review — topic-creation guard resolves the method name
+
+**Version / slug:** `topic-creation-lint-resolution`
+**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 resolves one level of naming before applying the rules it already had.`
+
+## Summary of the change
+
+`scripts/lint-no-unfunneled-topic-creation.js` enforces the **Bounded Notification Surface** standard —
+the last-resort budget on automatically-created forum topics, added after the THIRD topic-spam incident
+(2026-06-05). All three of its patterns required `createForumTopic` as a string LITERAL adjacent to the
+seam, so a resolved name walked past a safety floor.
+
+Measured against the shipped lint, with a positive control (the bare literal) firing in the same run:
+
+| form | shipped |
+|---|---|
+| `apiCall("createForumTopic", …)` — POSITIVE CONTROL | exit 1 (caught) |
+| `const M = "createForumTopic"; apiCall(M, …)` | **exit 0 — EVADES** |
+| `apiCall("createForum" + "Topic", …)` | **exit 0 — EVADES** |
+| `const M = "createForumTopic"; { method: M }` | **exit 0 — EVADES** |
+
+The method name is now RESOLVED before the existing patterns are applied. The patterns are byte-identical;
+only what they can see changed.
+
+## Decision-point inventory
+
+- `foldAdjacentLiterals(text)` — ADD — folds `'a' + 'b'` only; never folds across an identifier.
+- `collectStringConsts(lines)` — ADD — per-file identifier → string-literal map; an identifier bound twice
+  to DIFFERENT values is dropped as unresolvable.
+- `resolveLine(line, consts)` — ADD — substitutes ONLY at the two seam positions (`apiCall(` and `method:`).
+- `scanFile(normalized, content)` — ADD — extracted so the matching behaviour is testable without the CLI.
+- Direct-invocation guard — ADD — the scan runs only when the script is invoked directly.
+- `PATTERNS`, `ALLOWLIST`, `SCAN_DIRS`, `EXTENSIONS`, 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 — which would cost more than the hole it closes. Six controls, each with a test, all passing under
+BOTH the old and new behaviour:
+
+- **A const bound to a different method** (`"sendMessage"`) is not flagged.
+- **An identifier that never reaches a seam** is not flagged — holding the value is not calling with it.
+- **An identifier bound twice to different values** is unresolvable and never substituted. Ambiguity
+  fails toward NOT flagging, because a guess that fails someone's build is the expensive direction.
+- **A concatenation involving an identifier** (`"createForum" + suffix`) is left unresolved. Folding it
+  would mean inventing text the source does not contain.
+- **A longer name starting with the method** (`createForumTopicIconStickers`) is not flagged — the
+  existing quote-delimited patterns already bound this, and resolution preserves it.
+- **Substitution is seam-local, not global** — an unrelated `logger.debug(M)` is untouched.
+
+Resolution is per-file by construction: one file's names cannot affect another's.
+
+**Verified against the real tree: exit 0 before AND after.** No new flags on existing code.
+
+## 2. Under-block
+
+Stated in the source rather than implied:
+
+- **Cross-module names** — a method name imported from another file is not followed.
+- **Runtime-built names** — from a variable, a function call, or a template literal.
+- **Anything needing dataflow** to resolve.
+
+Guessing at those would over-match.
+
+**One residual I want named rather than absorbed:** the lint does not strip comments, so a comment
+containing the literal form is flagged. That is PRE-EXISTING behaviour (it is why this script is on its
+own allowlist), and this change neither fixes nor worsens it — resolution runs on the same lines the
+patterns already ran on. I am not changing it here because loosening a flood guard to be tidier is the
+wrong direction, and doing it unrequested is the unrequested-tightening mistake in reverse.
+
+## 3. Level-of-abstraction fit
+
+Same layer as the existing check — line-oriented regex over raw source, no AST, no type information, no
+new dependency. The resolution map is the minimum needed to answer "what method name is at this seam?"
+without climbing to a parser.
+
+## 4. Signal vs authority compliance
+
+Unchanged. A CI guard, not a runtime authority. It pushes callers toward the budgeted funnel; the
+allowlist still exempts the funnel itself, the lifeline's fixed-cardinality system topic, and the
+setup-wizard doc string.
+
+## 5. Interactions
+
+- `npm run lint` chain — membership verified explicitly (the script is in the `lint` chain CI runs, not
+  merely referenced by a standalone entry); full chain exit 0 across 57 steps.
+- The direct-invocation guard changes import behaviour from "runs the repo 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 it is the correct posture — not an unexamined assumption.** This is a
+CI-time source scan with no runtime surface: it reads files in one checkout and exits. It holds no
+durable state, emits no user-facing notice, generates no URL, and makes no runtime decision, so there
+is nothing to replicate, nothing to merge on read, and nothing that could strand on a topic transfer.
+
+Every machine that runs the lint 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 even depend on the rest of the checkout, let alone another machine.
+
+Worth stating because the audit that added this question found ~20 features shipped machine-blind: the
+thing that makes THIS one genuinely local is that its input is version-controlled and its output is an
+exit code, not that I could not think of a cross-machine concern.
+
+## 8. Rollback cost
+
+`git revert` of one script plus the added test file. No migration, no state, no deployed artifact.
+
+## Conclusion
+
+Ship. Three evasions closed on a safety floor, six anti-over-block controls added, real tree verified
+clean in both directions, and the import hazard that blocked testing it removed.
+
+## Evidence pointers
+
+- `tests/unit/topic-creation-lint-resolution.test.ts` — **18/18 green**.
+- **Negative control: 5 of 18 fail** against the shipped matching behaviour (local const, concatenation,
+  `method:` const, let/var bindings, const-declared-after-use). The other 13 pass both ways — which is
+  what makes them controls. Source restored byte-exact after the mutation (sha match, 0 markers left).
+- Reproduced by hand FIRST with a positive control firing in the same run; the control is what makes the
+  three EVADES verdicts mean anything.
+- Real-tree verdict: `node scripts/lint-no-unfunneled-topic-creation.js` → exit 0, before and after.
+- Full `npm run lint` chain green, 57 steps.
+- Tier **1** declared: risk floor 1 (no safety-invariant path match — verified with two directional
+  controls, `SessionReaper.ts` → floor 2 with its reason named, `devClaimCheck.ts` → floor 1). The size
+  heuristic suggests 2 on added LOC alone; stated openly rather than left silent, since the tier I chose
+  is the one that lets the change through.