instar 1.3.625 → 1.3.626

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.625",
+  "version": "1.3.626",
   "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,13 +28,15 @@
     "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-unfunneled-credential-write.js && node scripts/lint-state-registry.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-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/check-codex-rule1-drift.js",
+    "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-unfunneled-credential-write.js && node scripts/lint-state-registry.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-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",
     "lint:destructive": "node scripts/lint-no-direct-destructive.js",
     "lint:dev-agent-dark-gate": "node scripts/lint-dev-agent-dark-gate.js",
     "lint:guard-manifest": "node scripts/lint-guard-manifest.js",
     "lint:dev-agent-dark-gate:staged": "node scripts/lint-dev-agent-dark-gate.js --staged",
     "lint:destructive:staged": "node scripts/lint-no-direct-destructive.js --staged",
     "lint:llm-http": "node scripts/lint-no-direct-llm-http.js",
+    "lint:scrape-realness": "node scripts/lint-scrape-fixture-realness.js",
+    "lint:scrape-realness:staged": "node scripts/lint-scrape-fixture-realness.js --staged",
     "lint:llm-attribution": "node scripts/lint-llm-attribution.js",
     "lint:llm-attribution:staged": "node scripts/lint-llm-attribution.js --staged",
     "lint:llm-http:staged": "node scripts/lint-no-direct-llm-http.js --staged",

package/scripts/lint-scrape-fixture-realness.js

@@ -0,0 +1,327 @@
+#!/usr/bin/env node
+/**
+ * lint-scrape-fixture-realness.js — enforces that every REGISTERED scrape/parser
+ * has a test that FEEDS it a structurally-real captured fixture and asserts on
+ * the result (not a hand-authored clean string).
+ *
+ * Implements piece 3 of docs/specs/scrape-fixture-realness.md (the "code=t"
+ * lesson, structurally enforced). A parser of untrusted real-world text is only
+ * as good as the realness of its test input. The check is precise by
+ * construction — a CURATED registry (SCRAPE_PARSERS), not a heuristic over all
+ * tests — so false-positives are near-zero (same posture as
+ * lint-no-direct-llm-http / lint-dev-agent-dark-gate). Adding/removing a registry
+ * entry requires a spec change.
+ *
+ * For each registered parser the lint verifies (spec §3):
+ *   (a) tests/fixtures/captured/<slug>/ has >=1 `.txt`, each with a valid matching
+ *       `.meta.json` (required fields present + capturedAt parses as ISO date).
+ *   (b) testFile contains a test whose name === testName, and within that test's
+ *       body ALL of: a loadCapturedFixture('<slug>', ...) call, the parserSymbol
+ *       called with the loaded var as an argument (member-expression accepted),
+ *       and an expect( call.
+ *
+ * It ALSO scans src/ for exported parse-prefixed / scrape-prefixed symbols not covered by the
+ * registry and prints a non-blocking WARNING ("register-or-justify") — a
+ * Close-the-Loop signal, never a block (Signal vs. Authority).
+ *
+ * Exit codes:
+ *   0 — every registered entry conforms (warnings do NOT affect exit code).
+ *   1 — at least one registered entry fails a sub-check.
+ *
+ * Usage:
+ *   node scripts/lint-scrape-fixture-realness.js                # full check
+ *   node scripts/lint-scrape-fixture-realness.js --staged       # staged files (still runs full registry check)
+ *   node scripts/lint-scrape-fixture-realness.js path1 path2    # explicit paths (still runs full registry check)
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const ROOT = path.resolve(__dirname, '..');
+
+/**
+ * The curated registry of parsers whose realness is enforced. Each entry:
+ *   { parserSymbol, fixtureSlug, testFile, testName }
+ *
+ * Adding/removing an entry requires a spec change (FD1/FD3). The seed is the one
+ * parser we KNOW consumes untrusted terminal text and bit us (the code=t bug).
+ */
+export const SCRAPE_PARSERS = [
+  {
+    parserSymbol: 'FrameworkLoginDriver.parseArtifact',
+    fixtureSlug: 'claude-url-code-paste',
+    testFile: 'tests/unit/framework-login-driver.test.ts',
+    testName: 'parses the REAL wrapped Mac Mini login pane',
+  },
+];
+
+const REQUIRED_META_FIELDS = ['source', 'command', 'capturedAt', 'machine', 'redactions', 'note'];
+
+/**
+ * (a) — verify the captured-fixture directory + sidecars for a slug.
+ * @returns {string[]} list of failure messages (empty = ok)
+ */
+export function checkFixtures(root, fixtureSlug) {
+  const failures = [];
+  const dir = path.join(root, 'tests', 'fixtures', 'captured', fixtureSlug);
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
+    failures.push(`fixture dir missing: tests/fixtures/captured/${fixtureSlug}/`);
+    return failures;
+  }
+  const entries = fs.readdirSync(dir);
+  const txts = entries.filter((f) => f.endsWith('.txt'));
+  if (txts.length === 0) {
+    failures.push(`no .txt captures in tests/fixtures/captured/${fixtureSlug}/`);
+    return failures;
+  }
+  for (const txt of txts) {
+    const base = txt.slice(0, -'.txt'.length);
+    const sidecar = `${base}.meta.json`;
+    const sidecarPath = path.join(dir, sidecar);
+    if (!fs.existsSync(sidecarPath)) {
+      failures.push(`missing sidecar ${fixtureSlug}/${sidecar} for capture ${fixtureSlug}/${txt}`);
+      continue;
+    }
+    let meta;
+    try {
+      meta = JSON.parse(fs.readFileSync(sidecarPath, 'utf-8'));
+    } catch (err) {
+      failures.push(`sidecar ${fixtureSlug}/${sidecar} is not valid JSON: ${err.message}`);
+      continue;
+    }
+    for (const field of REQUIRED_META_FIELDS) {
+      if (!(field in meta)) {
+        failures.push(`sidecar ${fixtureSlug}/${sidecar} missing required field "${field}"`);
+      }
+    }
+    if (meta.capturedAt !== undefined) {
+      const t = Date.parse(meta.capturedAt);
+      if (Number.isNaN(t)) {
+        failures.push(`sidecar ${fixtureSlug}/${sidecar} capturedAt "${meta.capturedAt}" is not a parseable ISO-8601 date`);
+      }
+    }
+  }
+  return failures;
+}
+
+/**
+ * Extract the body text of an `it('<name>', ...)` / `test('<name>', ...)` block
+ * by matching the opening and walking braces to the matching close. Returns null
+ * if no test with that exact name is found.
+ */
+export function extractTestBody(source, testName) {
+  // Find an it/test call whose first string-literal arg === testName.
+  // Match the literal (single, double, or backtick quotes) followed by a comma.
+  const escaped = testName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const opener = new RegExp(`\\b(?:it|test)\\s*\\(\\s*(['"\`])${escaped}\\1\\s*,`, 'g');
+  const m = opener.exec(source);
+  if (!m) return null;
+  // Walk forward from the end of the matched opener to find the body's braces.
+  // The test body is the arrow/function passed as the 2nd arg; find its first
+  // `{` after the opener and brace-match to its close.
+  let i = opener.lastIndex;
+  // Skip ahead to the first `{` that starts the callback body.
+  const braceStart = source.indexOf('{', i);
+  if (braceStart < 0) return null;
+  let depth = 0;
+  for (let j = braceStart; j < source.length; j++) {
+    const ch = source[j];
+    if (ch === '{') depth++;
+    else if (ch === '}') {
+      depth--;
+      if (depth === 0) {
+        return source.slice(braceStart + 1, j);
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * (b) — verify the registered test exists and feeds-and-asserts.
+ * @returns {string[]} list of failure messages (empty = ok)
+ */
+export function checkTest(root, entry) {
+  const failures = [];
+  const testPath = path.join(root, entry.testFile);
+  if (!fs.existsSync(testPath)) {
+    failures.push(`testFile missing: ${entry.testFile}`);
+    return failures;
+  }
+  const source = fs.readFileSync(testPath, 'utf-8');
+  const body = extractTestBody(source, entry.testName);
+  if (body === null) {
+    failures.push(`no test named "${entry.testName}" found in ${entry.testFile}`);
+    return failures;
+  }
+
+  // The loader call, capturing the variable it assigns to.
+  // const <v> = loadCapturedFixture('<slug>', ...)
+  const slugEsc = entry.fixtureSlug.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const loaderRe = new RegExp(
+    `(?:const|let|var)\\s+([A-Za-z_$][\\w$]*)\\s*=\\s*loadCapturedFixture\\s*\\(\\s*['"\`]${slugEsc}['"\`]`,
+  );
+  const loaderMatch = body.match(loaderRe);
+  if (!loaderMatch) {
+    failures.push(
+      `test "${entry.testName}" must call loadCapturedFixture('${entry.fixtureSlug}', …) and assign the result to a variable`,
+    );
+  }
+  const loadedVar = loaderMatch ? loaderMatch[1] : null;
+
+  // The parser call, fed the loaded variable as an argument.
+  // Accept member-expression (Cls.method) or bare/aliased call.
+  // parserSymbol may be "Cls.method" — escape dots literally.
+  const parserEsc = entry.parserSymbol.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  let parserFed = false;
+  if (loadedVar) {
+    const varEsc = loadedVar.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    // <parserSymbol>( ... <loadedVar> ... ) — loadedVar appears as an arg.
+    const parserRe = new RegExp(`${parserEsc}\\s*\\(\\s*${varEsc}\\b`);
+    parserFed = parserRe.test(body);
+  }
+  if (!parserFed) {
+    failures.push(
+      `test "${entry.testName}" must pass the loaded fixture variable as the first argument to ${entry.parserSymbol}(…)`,
+    );
+  }
+
+  // At least one expect( on the result.
+  if (!/\bexpect\s*\(/.test(body)) {
+    failures.push(`test "${entry.testName}" must assert on the parse result with expect(…)`);
+  }
+
+  return failures;
+}
+
+/** Recursively collect `.ts` files under a dir. */
+function walkTs(dir, out, skip) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    if (skip.has(e.name)) continue;
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) walkTs(full, out, skip);
+    else if (e.name.endsWith('.ts') && !e.name.endsWith('.d.ts')) out.push(full);
+  }
+}
+
+/**
+ * Close-the-Loop signal: scan src/ for exported parse-prefixed / scrape-prefixed symbols not in
+ * the registry. Non-blocking — returns a warning list only.
+ * @returns {Array<{symbol:string,file:string}>}
+ */
+export function findUnregisteredParsers(root) {
+  const skip = new Set(['node_modules', 'dist', 'build', '.instar', '.git', '.next', 'coverage']);
+  const files = [];
+  const srcDir = path.join(root, 'src');
+  if (fs.existsSync(srcDir)) walkTs(srcDir, files, skip);
+
+  // The bare method names already covered by the registry (e.g. "parseArtifact").
+  const registeredMethodNames = new Set(
+    SCRAPE_PARSERS.map((e) => {
+      const parts = e.parserSymbol.split('.');
+      return parts[parts.length - 1];
+    }),
+  );
+
+  const re = /export\s+(?:async\s+)?function\s+((?:parse|scrape)[A-Z]\w*)|export\s+const\s+((?:parse|scrape)[A-Z]\w*)/g;
+  const found = [];
+  const seen = new Set();
+  for (const file of files) {
+    let text;
+    try {
+      text = fs.readFileSync(file, 'utf-8');
+    } catch {
+      continue;
+    }
+    let m;
+    re.lastIndex = 0;
+    while ((m = re.exec(text)) !== null) {
+      const symbol = m[1] || m[2];
+      if (!symbol) continue;
+      if (registeredMethodNames.has(symbol)) continue;
+      const rel = path.relative(root, file).split(path.sep).join('/');
+      const key = `${rel}:${symbol}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      found.push({ symbol, file: rel });
+    }
+  }
+  return found;
+}
+
+/**
+ * Run the full lint over the registry. Pure-ish (reads fs, returns a result).
+ * @returns {{ exitCode:number, errors:string[], warnings:string[], passed:Array }}
+ */
+export function runLint(root = ROOT) {
+  const errors = [];
+  const passed = [];
+  for (const entry of SCRAPE_PARSERS) {
+    const failures = [...checkFixtures(root, entry.fixtureSlug), ...checkTest(root, entry)];
+    if (failures.length > 0) {
+      errors.push(
+        `Registered parser "${entry.parserSymbol}" (${entry.testFile}) failed realness check:\n` +
+          failures.map((f) => `      - ${f}`).join('\n'),
+      );
+    } else {
+      passed.push(entry);
+    }
+  }
+
+  const unregistered = findUnregisteredParsers(root);
+  const warnings = [];
+  if (unregistered.length > 0) {
+    warnings.push(
+      `register-or-justify: ${unregistered.length} exported parse*/scrape* symbol(s) in src/ are not in SCRAPE_PARSERS.\n` +
+        `      If they consume untrusted real-world text, register them (spec change) or justify out-of-scope in the PR:\n` +
+        unregistered.slice(0, 20).map((u) => `        • ${u.symbol} (${u.file})`).join('\n') +
+        (unregistered.length > 20 ? `\n        • ...and ${unregistered.length - 20} more` : ''),
+    );
+  }
+
+  return { exitCode: errors.length > 0 ? 1 : 0, errors, warnings, passed };
+}
+
+function main() {
+  // --staged / explicit paths are accepted for parity with sibling lints, but
+  // the realness check is over the curated registry, so it always runs the full
+  // registry check regardless of which files changed.
+  const { exitCode, errors, warnings, passed } = runLint(ROOT);
+
+  if (errors.length > 0) {
+    console.error('lint-scrape-fixture-realness: registered parser(s) failed realness enforcement.\n');
+    console.error('A registered scrape/parser must have a test that FEEDS it a structurally-real captured');
+    console.error('fixture and asserts on the result. See docs/specs/scrape-fixture-realness.md.\n');
+    for (const e of errors) console.error(`  ❌ ${e}`);
+    console.error('');
+  } else {
+    for (const e of passed) {
+      console.log(`  ✅ ${e.parserSymbol} — realness fixture + feeds-and-asserts test OK (${e.testName})`);
+    }
+  }
+
+  if (warnings.length > 0) {
+    for (const w of warnings) console.warn(`  ⚠️  ${w}`);
+    console.warn('');
+  }
+
+  process.exit(exitCode);
+}
+
+const isDirectRun = (() => {
+  try {
+    return process.argv[1] && path.resolve(process.argv[1]) === __filename;
+  } catch {
+    return false;
+  }
+})();
+if (isDirectRun) main();

package/scripts/pre-push-gate.js

@@ -428,6 +428,12 @@ try {
   warnings.push(`lint-no-direct-llm-http failed to run: ${err.message}`);
 }
 
+// (The scrape-fixture-realness lint is enforced via the `npm run lint` chain in
+// package.json, which CI runs — not duplicated here. A direct gate invocation
+// would run against this gate's resolved ROOT, which is a scratch dir under the
+// gate's own unit tests, where the registered fixtures don't exist; the chain in
+// `npm run lint` runs in the real repo and is the authoritative enforcement.)
+
 // ── 6. URL.pathname filesystem guard ──────────────────────────────────
 // new URL(..., import.meta.url).pathname preserves %20-encoded spaces,
 // breaking filesystem operations. Use __dirname (via fileURLToPath) instead.

package/scripts/redact-captured-fixture.mjs

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+/**
+ * redact-captured-fixture.mjs — same-SHAPE, grammar-valid secret redaction for
+ * captured parser fixtures.
+ *
+ * Captured fixtures (tests/fixtures/captured/<slug>/) preserve every STRUCTURAL
+ * byte that matters to parsing (wrapping/ANSI/spacing/line-breaks) — those are
+ * the realness and are NEVER tidied. But a real capture carries secrets (OAuth
+ * client_id/state, tokens, usernames, paths). Committing them raw is a leak, so
+ * each secret VALUE is replaced with a same-SHAPE placeholder:
+ *
+ *   - SAME LENGTH (so line positions + wrapping stay byte-identical),
+ *   - SAME CHARACTER CLASS (hex stays hex, base64url stays base64url, …),
+ *   - delimiters preserved AT THEIR POSITIONS (a UUID keeps its `-` offsets),
+ *   - GRAMMAR-VALID (a redacted URL still parses; encoding form intact).
+ *
+ * A redaction that would change length is REJECTED — a length change shifts the
+ * wrapping and silently produces a passing-but-fake fixture.
+ *
+ * See docs/specs/scrape-fixture-realness.md (FD2) and
+ * tests/fixtures/captured/README.md.
+ *
+ * Usage (CLI):
+ *   node scripts/redact-captured-fixture.mjs <raw.txt> \
+ *     --redact '<find>:<class>' [--redact '<find>:<class>' ...] [-o out.txt]
+ *
+ *   <class> ∈ hex | uuid | base64url | alnum | token
+ *
+ * Programmatic:
+ *   import { redactCapture } from './redact-captured-fixture.mjs';
+ *   const { redacted, redactions } = redactCapture(raw, [{ find, class }]);
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// The supported redaction classes. Adding a class requires a spec change
+// (it widens the same-shape contract).
+export const REDACTION_CLASSES = new Set(['hex', 'uuid', 'base64url', 'alnum', 'token']);
+
+// Per-class placeholder fill characters. The fill is a single canonical char of
+// the class so the result is obviously inert (not a plausible real secret),
+// while staying in the class so the parser's grammar is preserved.
+const CLASS_FILL = {
+  hex: 'a', // [0-9a-f]
+  uuid: 'a', // hex within UUID segments; hyphens are preserved positionally
+  base64url: 'z', // [A-Za-z0-9_-]
+  alnum: 'x', // [A-Za-z0-9]
+  token: 'x', // generic opaque token — treated like alnum for the fill
+};
+
+// Characters that are DELIMITERS within a value of a given class — preserved at
+// their exact positions so the value's internal structure (and thus length +
+// grammar) is unchanged. Everything else is replaced with the class fill char.
+const CLASS_DELIMITERS = {
+  hex: new Set([]),
+  uuid: new Set(['-']),
+  base64url: new Set(['-', '_']),
+  alnum: new Set([]),
+  token: new Set(['-', '_', '.']),
+};
+
+/**
+ * Build a same-length, same-class, grammar-valid placeholder for a secret value.
+ * Delimiter characters for the class are preserved at their positions.
+ */
+function placeholderFor(value, cls) {
+  const fill = CLASS_FILL[cls];
+  const delims = CLASS_DELIMITERS[cls];
+  let out = '';
+  for (const ch of value) {
+    out += delims.has(ch) ? ch : fill;
+  }
+  return out;
+}
+
+/**
+ * Redact secrets from a raw capture, producing a same-shape result.
+ *
+ * @param {string} raw    the raw captured text (structural bytes preserved)
+ * @param {Array<{find:string, class:string}>} specs  secrets to redact
+ * @returns {{ redacted: string, redactions: Array<{what:string,strategy:string,length:number,class:string}> }}
+ * @throws if a class is unknown, a `find` is missing from `raw`, or a
+ *         placeholder would change length (it never should — this is a guard).
+ */
+export function redactCapture(raw, specs) {
+  if (typeof raw !== 'string') throw new Error('redactCapture: raw must be a string');
+  if (!Array.isArray(specs)) throw new Error('redactCapture: specs must be an array');
+
+  let redacted = raw;
+  const redactions = [];
+
+  for (const spec of specs) {
+    const { find } = spec;
+    const cls = spec.class;
+    if (typeof find !== 'string' || find.length === 0) {
+      throw new Error('redactCapture: each spec needs a non-empty `find` string');
+    }
+    if (!REDACTION_CLASSES.has(cls)) {
+      throw new Error(
+        `redactCapture: unknown class "${cls}" for find "${find}" — must be one of ${[...REDACTION_CLASSES].join(', ')}`,
+      );
+    }
+    if (!redacted.includes(find)) {
+      throw new Error(`redactCapture: secret to redact not found in capture: "${find}"`);
+    }
+
+    const placeholder = placeholderFor(find, cls);
+    // Length-preservation guard: the whole point is byte-identical wrapping.
+    if (placeholder.length !== find.length) {
+      throw new Error(
+        `redactCapture: placeholder length ${placeholder.length} != original length ${find.length} ` +
+          `for class "${cls}" — a length-changing redaction shifts wrapping and is rejected.`,
+      );
+    }
+
+    redacted = redacted.split(find).join(placeholder);
+    redactions.push({
+      what: find,
+      strategy: `same-length ${find.length} ${cls}-class placeholder, delimiters preserved at positions`,
+      length: find.length,
+      class: cls,
+    });
+  }
+
+  return { redacted, redactions };
+}
+
+// ── thin CLI wrapper ──────────────────────────────────────────────────
+function parseArgs(argv) {
+  const specs = [];
+  let input = null;
+  let out = null;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--redact') {
+      const v = argv[++i];
+      const idx = v.lastIndexOf(':');
+      if (idx < 0) throw new Error(`--redact expects '<find>:<class>', got "${v}"`);
+      specs.push({ find: v.slice(0, idx), class: v.slice(idx + 1) });
+    } else if (a === '-o' || a === '--out') {
+      out = argv[++i];
+    } else if (!input) {
+      input = a;
+    }
+  }
+  return { input, out, specs };
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) {
+    console.log(
+      'Usage: node scripts/redact-captured-fixture.mjs <raw.txt> --redact \'<find>:<class>\' [...] [-o out.txt]\n' +
+        `  <class> ∈ ${[...REDACTION_CLASSES].join(' | ')}`,
+    );
+    process.exit(argv.length === 0 ? 1 : 0);
+  }
+  const { input, out, specs } = parseArgs(argv);
+  const raw = fs.readFileSync(input, 'utf-8');
+  const { redacted, redactions } = redactCapture(raw, specs);
+  if (out) {
+    fs.writeFileSync(out, redacted);
+    console.error(`Wrote redacted capture to ${out}`);
+  } else {
+    process.stdout.write(redacted);
+  }
+  console.error(`Redactions (${redactions.length}):`);
+  for (const r of redactions) {
+    console.error(`  - ${r.class} (len ${r.length}): ${r.strategy}`);
+  }
+}
+
+const isDirectRun = (() => {
+  try {
+    return process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+})();
+if (isDirectRun) main();

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-19T06:08:39.918Z",
-  "instarVersion": "1.3.625",
+  "generatedAt": "2026-06-19T06:11:32.609Z",
+  "instarVersion": "1.3.626",
   "entryCount": 201,
   "entries": {
     "hook:session-start": {

package/upgrades/{1.3.625.md → 1.3.626.md}

@@ -7,6 +7,8 @@
 
 Adds a machine × account matrix on the dashboard Subscriptions tab — the on-demand "put account X on machine Y" surface that was missing (the account-follow-me Approve cards are quota-driven and never offered accounts on demand, so adding accounts to another machine meant a clunky chat dance). Rows are accounts, columns are machines; each cell is a ✓ (active there), a "Set up" button (not yet), or an honest in-progress / needs-reauth / offline / held state. Tapping "Set up" runs the whole sign-in IN the dashboard: it PIN-checks (operator presence — the agent shares the Bearer token, so the dashboard PIN is what proves a human is acting), drives the existing PIN→mandate→enroll-start chain to start a fresh login on the target machine (that machine re-mints its own login, ToS-safe), shows the auth link + a code box, and the shipped code-paste-back relay finishes it — flipping the cell to ✓. The wrong-account safety (S7 email-gate) and cross-machine delivery are reused unchanged. Dev-gated (`multiMachine.accountFollowMe`), dark on the fleet.
 
+Structurally enforces the `code=t` lesson (the broken account-follow-me sign-in link, 2026-06-18): a parser of untrusted real-world text must be tested against a byte-for-byte REAL captured fixture, not a hand-authored clean string. Adds a Testing-Integrity standard, a `tests/fixtures/captured/` convention (structural bytes sacrosanct; secrets swapped for same-shape, grammar-valid placeholders via a tested redaction helper; one provenance sidecar per capture), and a registry-driven lint `scripts/lint-scrape-fixture-realness.js`. Each registered parser (seeded with `FrameworkLoginDriver.parseArtifact`) must have a test that loads a captured fixture through the single `loadCapturedFixture` helper, feeds it to the parser, and asserts — and the suite runs that test, so the realness is executed, not grepped. A non-blocking `parse*`/`scrape*` register-or-justify warning re-surfaces new parsers. The original `code=t` capture is migrated to disk (secrets redacted, hard-wrap preserved). No runtime code changes.
+
 ## What to Tell Your User
 
 There's now a grid on the Subscriptions tab showing which of your accounts are signed in on which machines, at a glance. To add an account to another machine, tap the empty cell, enter your dashboard PIN, sign in on the page it opens, and paste the code right there — it sets up that machine and the cell turns into a check mark. No more routing sign-in codes through chat.
@@ -21,3 +23,8 @@ There's now a grid on the Subscriptions tab showing which of your accounts are s
 - `tests/unit/subscriptions-render.test.ts` — matrix renders ✓ for active, "Set up" for empty, a disabled offline column for a `pool.failed` machine (no fabricated ✓), in-progress for a pending login.
 - `tests/unit/follow-me-controller-wiring.test.ts` — a "Set up" tap with a PIN POSTs start-cell {accountId, machineId, pin}; no-PIN does not POST.
 - `npx tsc --noEmit` clean; `npm run lint` (full battery) clean; 47 tests green.
+
+- `tests/unit/lint-scrape-fixture-realness.test.ts` (10) — both boundary sides: the shipped registry entry passes; tampered cases (missing test, removed loader, missing/invalid sidecar) fail.
+- `tests/unit/redact-captured-fixture.test.ts` (8) — same-length, line-position/wrap preservation, redacted URL still parses, length-changing redaction rejected.
+- `tests/unit/framework-login-driver.test.ts` (17) — the migrated realness test loads the disk fixture, asserts the full de-wrapped URL ≠ `code=t`.
+- `node scripts/lint-scrape-fixture-realness.js` exits 0 (seed entry clean + register-or-justify warning); `npm run lint` (full battery) exits 0; `tsc --noEmit` clean.

package/upgrades/side-effects/scrape-fixture-realness.md

@@ -0,0 +1,49 @@
+# Side-effects review — Scrape/Parser fixture-realness enforcement
+
+Spec: `docs/specs/scrape-fixture-realness.md` (converged @ iter 4, approved) · ELI16: `docs/specs/scrape-fixture-realness.eli16.md`
+Parent principle: Testing Integrity
+
+## What the change is
+
+Structural enforcement of the `code=t` lesson: a parser of untrusted real-world text must be tested against a byte-for-byte REAL captured fixture, not a hand-authored clean string. Adds (1) a registry standard, (2) a `tests/fixtures/captured/` convention with secret-redaction + provenance sidecars, (3) a registry-driven lint `scripts/lint-scrape-fixture-realness.js` that requires each registered parser's test to load a captured fixture via `loadCapturedFixture`, feed it to the parser, and assert — plus a non-blocking register-or-justify warning for un-registered `parse*`/`scrape*` exports. No runtime code changes.
+
+Files: `scripts/lint-scrape-fixture-realness.js`, `scripts/redact-captured-fixture.mjs`, `tests/helpers/loadCapturedFixture.ts`, `tests/fixtures/captured/**`, `docs/STANDARDS-REGISTRY.md`, `package.json` (lint chain), `scripts/pre-push-gate.js` (direct invocation), `tests/unit/framework-login-driver.test.ts` (migrated), + tests for the lint and the redaction helper.
+
+## 1. Over-block — legitimate inputs rejected that shouldn't be
+The lint only enforces realness for parsers EXPLICITLY in the `SCRAPE_PARSERS` registry (seeded with one). It never fires on un-registered code — so it cannot false-positive a normal test. The register-or-justify check is a non-blocking WARNING (exit code unaffected). Near-zero over-block by construction (FD1).
+
+## 2. Under-block — failure modes still missed
+- The lint proves the registered test loads-feeds-asserts; it cannot prove the assertion is non-trivial (a deliberately weak `expect`) — owned as a review concern (FD6).
+- It cannot prove un-redacted bytes were genuinely real (provenance is review-checkable, not machine-verifiable) — owned (FD2).
+- Inline/method/private parsers aren't caught by the `parse*`/`scrape*` export scan — the PR register-or-justify trigger (review) is primary; the warning is a backstop (FD3). This is the conformance gate's noted Structure-vs-Willpower residual, accepted because full coverage needs the unbounded heuristic FD1 rejects.
+
+## 3. Level-of-abstraction fit
+Correct layer: a build-time lint alongside the existing `lint-*` family, run via `npm run lint` (the real battery) + the pre-push gate. The redaction helper sits in `scripts/` with its peers. The fixture convention sits under `tests/fixtures/`. No runtime layer touched.
+
+## 4. Signal vs authority compliance
+A hard-blocking lint over a CURATED registry — legitimate per Signal-vs-Authority because the false-positive surface is near-zero by construction (identical posture to `lint-no-direct-llm-http` / `lint-dev-agent-dark-gate`, both hard-block on curated lists). The register-or-justify check is signal-only (warning, never blocks). No brittle blocking authority over messages/sessions.
+
+## 5. Interactions
+- Adds one entry to the `npm run lint` `&&`-chain (ordering-independent; each lint is self-contained) + a direct pre-push invocation (mirrors the two existing direct lints). No shadowing/double-fire.
+- The migrated `framework-login-driver` realness test now loads from disk via `loadCapturedFixture` instead of an inline const; the de-wrap assertion (full URL ≠ `code=t`) is unchanged, so the regression guard and the realness convention reinforce each other.
+- The redaction helper is a new dependency of the fixture-authoring flow; it carries its own unit tests so a redaction bug can't silently produce a passing-but-fake fixture.
+
+## 6. External surfaces
+None at runtime. Build-time only: a new lint contributors run via `npm run lint`; a new standard in the registry; a new fixtures dir. Nothing visible to users, other agents, or other systems.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+Machine-local by design (FD4): build-time lint over the committed source tree + committed fixtures. No runtime surface, no state, no cross-machine behavior. Every machine builds the identical repo and runs the identical lint over the identical fixtures.
+
+## 8. Rollback cost
+Cheap. Revert the new files + the three small wiring edits (package.json, pre-push-gate.js, the migrated test). No data migration, no runtime/state. The migrated fixture can revert to an inline const if ever needed (the assertion is unchanged).
+
+## Second-pass (high-risk: "lint"/gate)
+The lint's core (`checkTest`) was independently re-read against the spec: it requires, within the registry-named test, a `loadCapturedFixture('<slug>')` assigned to a var, that var passed as the first arg to the registered parser symbol (member-expression accepted), and an `expect(`. The sidecar check validates required fields + ISO timestamp. Matches the spec's canonical-shape matcher; the realness is executed (the suite runs the named test). Concur.
+
+## Follow-up fix (CI regressions)
+
+Two regressions this PR introduced were caught by CI (not the 3 files I first ran) and fixed:
+1. **Dangling ref:** the standard cited the `SCRAPE_PARSERS` token; the standards-enforcement-auditor resolves backticked `FOO_BAR` tokens as `src/**` symbols, and this one lives in `scripts/`, so it never resolved → danglingCount 0→1. Rephrased the standard to "a curated parser registry" (no marker token). Re-verified danglingCount=0.
+   - Over-block/Under-block: none — the lint's behavior is unchanged; only the registry prose changed.
+2. **Pre-push-gate scratch test:** the direct lint invocation added to `scripts/pre-push-gate.js` ran against the gate's resolved ROOT, which is a scratch dir in the gate's own unit tests (where the registered fixtures don't exist) → status 1. Removed the redundant direct invocation; the lint is enforced via the `npm run lint` chain that CI runs (authoritative). No loss of enforcement.
+   - Rollback cost: trivial (re-add the block if a future need arises, guarded for scratch).