instar 1.3.490 → 1.3.492

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.490",
+  "version": "1.3.492",
   "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,9 +28,10 @@
     "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-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-llm-attribution.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-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: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",

package/scripts/lint-guard-manifest.js

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+/**
+ * lint-guard-manifest.js — the guard-inventory CI ratchet
+ * (GUARD-POSTURE-ENDPOINT-SPEC §2.1, "CI ratchet (manifest-driven, repo-wide)").
+ *
+ * THE RULE: every guard-shaped component in src/monitoring, src/messaging,
+ * src/lifeline, src/core must be CLASSIFIED — it appears either as a
+ * `component:` in GUARD_MANIFEST (it IS an inventory guard) or in NOT_A_GUARD
+ * (it deliberately is not, with a real reason). A future guard cannot be
+ * forgotten from the /guards inventory: the moment its file lands, this lint
+ * fails until someone makes the classification decision explicitly
+ * (Structure > Willpower — same contract as lint-dev-agent-dark-gate.js +
+ * DARK_GATE_EXCLUSIONS).
+ *
+ * Three assertions:
+ *
+ *   A. EVERY CANDIDATE CLASSIFIED — a candidate component is (1) a .ts file in
+ *      one of the four dirs whose basename matches the guard-shape suffix
+ *      pattern (Sentinel|Reaper|Watchdog|Guard|Tripwire|Monitor|Beacon|
+ *      Detector|Promoter|Pauser|Backstop), component name = basename, OR
+ *      (2) a name in ADDITIONAL_CANDIDATES (enabled-gated boot constructs
+ *      whose filenames don't match the pattern, e.g. QuotaTracker, PromptGate).
+ *      Each candidate must appear in GUARD_MANIFEST's `component:` fields or
+ *      in NOT_A_GUARD.
+ *
+ *   B. REAL REASONS — every NOT_A_GUARD entry's reason must be ≥12
+ *      non-whitespace chars (defeats placeholder reasons; same bar as
+ *      DARK_GATE_EXCLUSIONS).
+ *
+ *   C. EXACTLY ONE LIST — a component must not appear in BOTH GUARD_MANIFEST
+ *      and NOT_A_GUARD (a dual classification is a contradiction the
+ *      inventory cannot resolve).
+ *
+ * LIMITATIONS (P2 Signal-vs-Authority — do NOT claim full closure):
+ *   - Detection is the file-basename suffix pattern + the explicit
+ *     ADDITIONAL_CANDIDATES list. A guard-shaped component in a file whose
+ *     name matches neither (e.g. a guard class defined inside server.ts)
+ *     evades detection until someone names it in ADDITIONAL_CANDIDATES.
+ *     Deliberate: cheap, deterministic, explainable — the precedent's
+ *     pragmatism over an AST-grade analyzer.
+ *   - The manifest is parsed STATICALLY (regex over the source — this lint
+ *     must not import TS). `component:` and `reason:` must be single-line
+ *     'single-' or "double-quoted" string literals, which is the file's
+ *     enforced house style; a template-literal or multi-line reason would be
+ *     invisible to the parse (and the entry would then fail assertion A,
+ *     loudly, not silently pass).
+ *
+ * Exit codes:
+ *   0 — no violations.
+ *   1 — at least one violation.
+ *
+ * Usage:
+ *   node scripts/lint-guard-manifest.js              # full scan of the four dirs
+ *   node scripts/lint-guard-manifest.js path1 path2  # specific candidate files
+ *
+ * Test override:
+ *   INSTAR_GUARDLINT_MANIFEST=<path>  # point the parse at a fixture manifest
+ */
+
+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, '..');
+
+const MANIFEST_REL = 'src/monitoring/guardManifest.ts';
+const MANIFEST_ABS = process.env.INSTAR_GUARDLINT_MANIFEST
+  ? path.resolve(process.env.INSTAR_GUARDLINT_MANIFEST)
+  : path.join(ROOT, MANIFEST_REL);
+
+// The repo-wide scan boundary (spec §2.1: "in ANY of src/monitoring,
+// src/messaging, src/lifeline, src/core" — path-pattern linting scoped to one
+// directory would miss the spec's own canonical examples).
+const GUARD_DIRS = ['src/monitoring', 'src/messaging', 'src/lifeline', 'src/core'];
+
+// Guard-shape detection 1: the basename suffix pattern.
+const GUARD_SHAPE_BASENAME =
+  /(Sentinel|Reaper|Watchdog|Guard|Tripwire|Monitor|Beacon|Detector|Promoter|Pauser|Backstop)\.ts$/;
+
+// Guard-shape detection 2: explicit additional candidates — enabled-gated
+// boot-constructed components whose FILENAMES do not match the suffix pattern.
+// Append here when a new guard-shaped component ships under a non-matching
+// name (the lint then forces its classification like any other candidate).
+const ADDITIONAL_CANDIDATES = [
+  'QuotaTracker',          // monitoring.quotaTracking
+  'ResourceLedger',        // monitoring.resourceLedger.enabled
+  'TelemetryCollector',    // monitoring.telemetry.enabled
+  'StallTriageNurse',      // monitoring.triage.enabled
+  'TriageOrchestrator',    // monitoring.triageOrchestrator.enabled
+  'GrowthMilestoneAnalyst',// monitoring.growthAnalyst.enabled (dev-gated)
+  'BlockerLedger',         // monitoring.blockerLedger.enabled (dev-gated)
+  'SecretSync',            // multiMachine.secretSync.enabled
+  'CoherenceJournal',      // multiMachine.coherenceJournal.enabled
+  'PromptGate',            // monitoring.promptGate.enabled
+];
+
+const MIN_REASON_NON_WS = 12;
+
+/** Strip line + block comments so commented-out entries can't satisfy the rule. */
+function stripComments(src) {
+  return src
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/^\s*\/\/.*$/gm, '');
+}
+
+/** Extract the source slice of `export const NAME ... = [ ... ] as const;`. */
+function extractArrayBlock(src, name) {
+  const declRe = new RegExp(`export\\s+const\\s+${name}\\b[\\s\\S]*?=\\s*\\[`);
+  const m = declRe.exec(src);
+  if (!m) return null;
+  const start = m.index + m[0].length;
+  const end = src.indexOf('] as const', start);
+  if (end < 0) return null;
+  return src.slice(start, end);
+}
+
+/**
+ * Statically parse the manifest file (regex over source — never imports TS).
+ * Returns { manifestComponents: Set, notAGuard: [{component, reason, line}] }.
+ */
+function parseManifest(manifestAbs) {
+  const raw = fs.readFileSync(manifestAbs, 'utf-8');
+  const src = stripComments(raw);
+
+  const manifestBlock = extractArrayBlock(src, 'GUARD_MANIFEST');
+  const notAGuardBlock = extractArrayBlock(src, 'NOT_A_GUARD');
+  if (manifestBlock === null || notAGuardBlock === null) {
+    return {
+      error: `could not locate ${manifestBlock === null ? 'GUARD_MANIFEST' : 'NOT_A_GUARD'} array in ${manifestAbs}`,
+    };
+  }
+
+  const manifestComponents = new Set();
+  const componentRe = /component:\s*(['"])([^'"]+)\1/g;
+  for (const m of manifestBlock.matchAll(componentRe)) manifestComponents.add(m[2]);
+
+  // NOT_A_GUARD entries: `{ component: '...', reason: '...' }` (single-line
+  // string literals — the file's house style; see header LIMITATIONS).
+  const notAGuard = [];
+  const entryRe = /component:\s*(['"])([^'"]+)\1\s*,\s*reason:\s*(['"])((?:[^\\]|\\.)*?)\3/g;
+  for (const m of notAGuardBlock.matchAll(entryRe)) {
+    notAGuard.push({ component: m[2], reason: m[4] });
+  }
+
+  return { manifestComponents, notAGuard };
+}
+
+/** Walk the four guard dirs for candidate .ts files (skip tests/declarations). */
+function listCandidateFiles() {
+  const out = [];
+  for (const rel of GUARD_DIRS) {
+    const dir = path.join(ROOT, rel);
+    if (!fs.existsSync(dir)) continue;
+    const walk = (d) => {
+      for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+        const full = path.join(d, e.name);
+        if (e.isDirectory()) {
+          if (e.name === 'node_modules') continue;
+          walk(full);
+        } else if (
+          e.name.endsWith('.ts') &&
+          !e.name.endsWith('.test.ts') &&
+          !e.name.endsWith('.d.ts')
+        ) {
+          out.push(full);
+        }
+      }
+    };
+    walk(dir);
+  }
+  return out;
+}
+
+function resolveCandidateFiles() {
+  const explicit = process.argv.slice(2).filter((a) => !a.startsWith('--'));
+  if (explicit.length) return explicit.map((f) => path.resolve(ROOT, f));
+  return listCandidateFiles();
+}
+
+// ── Run ──────────────────────────────────────────────────────────────────────
+
+const violations = [];
+
+if (!fs.existsSync(MANIFEST_ABS)) {
+  console.error(`lint-guard-manifest: manifest not found at ${MANIFEST_ABS}`);
+  process.exit(1);
+}
+
+const parsed = parseManifest(MANIFEST_ABS);
+if (parsed.error) {
+  console.error(`lint-guard-manifest: ${parsed.error}`);
+  process.exit(1);
+}
+const { manifestComponents, notAGuard } = parsed;
+const notAGuardComponents = new Set(notAGuard.map((e) => e.component));
+
+// ── Assertion B: every NOT_A_GUARD reason is real (≥12 non-ws chars) ──
+for (const e of notAGuard) {
+  const reasonLen = (e.reason || '').replace(/\s/g, '').length;
+  if (reasonLen < MIN_REASON_NON_WS) {
+    violations.push({
+      file: MANIFEST_REL, kind: 'B: NOT_A_GUARD reason too short',
+      text: `${e.component} → reason '${e.reason}' (${reasonLen} non-ws chars)`,
+      fix: `a NOT_A_GUARD reason must be ≥${MIN_REASON_NON_WS} non-whitespace chars (defeats placeholder reasons)`,
+    });
+  }
+}
+
+// ── Assertion C: exactly one list ──
+for (const c of notAGuardComponents) {
+  if (manifestComponents.has(c)) {
+    violations.push({
+      file: MANIFEST_REL, kind: 'C: dual classification',
+      text: `${c} appears in BOTH GUARD_MANIFEST and NOT_A_GUARD`,
+      fix: 'a component is a guard or it is not — remove it from one list',
+    });
+  }
+}
+
+// ── Assertion A: every candidate component is classified ──
+const explicitArgs = process.argv.slice(2).filter((a) => !a.startsWith('--'));
+const candidates = new Map(); // component name → where it was detected
+for (const file of resolveCandidateFiles()) {
+  if (!fs.existsSync(file)) continue;
+  const base = path.basename(file);
+  if (!GUARD_SHAPE_BASENAME.test(base)) continue;
+  candidates.set(base.replace(/\.ts$/, ''), path.relative(ROOT, file));
+}
+// ADDITIONAL_CANDIDATES are repo-global names — only meaningful on a full
+// scan (an explicit-args run, e.g. a test fixture, scopes to those files).
+if (explicitArgs.length === 0) {
+  for (const name of ADDITIONAL_CANDIDATES) {
+    if (!candidates.has(name)) candidates.set(name, '(ADDITIONAL_CANDIDATES)');
+  }
+}
+
+for (const [component, where] of [...candidates.entries()].sort()) {
+  if (manifestComponents.has(component)) continue;
+  if (notAGuardComponents.has(component)) continue;
+  violations.push({
+    file: where, kind: 'A: unclassified guard-shaped component',
+    text: `${component} is in NEITHER GUARD_MANIFEST (component:) NOR NOT_A_GUARD`,
+    fix: `declare it in GUARD_MANIFEST (it joins the /guards inventory) OR classify it in NOT_A_GUARD with a ≥${MIN_REASON_NON_WS}-char reason (${MANIFEST_REL})`,
+  });
+}
+
+if (violations.length === 0) {
+  console.log('lint-guard-manifest: clean');
+  process.exit(0);
+}
+
+console.error('\n❌ lint-guard-manifest found violations of the guard-inventory classification standard:\n');
+console.error('NOTE: detection is the file-basename suffix pattern + ADDITIONAL_CANDIDATES only —');
+console.error('a guard-shaped component under a non-matching filename evades it until named in');
+console.error('ADDITIONAL_CANDIDATES. This closes the forgotten-file hole, not every hole.\n');
+for (const v of violations) {
+  console.error(`  ${v.file}  [${v.kind}]`);
+  console.error(`    ${v.text}`);
+  console.error(`    fix: ${v.fix}\n`);
+}
+console.error('Standard: every guard-shaped component is CLASSIFIED — declared in GUARD_MANIFEST (it appears in the /guards inventory) or in NOT_A_GUARD with a real reason. A future guard cannot be silently forgotten. Spec: docs/specs/GUARD-POSTURE-ENDPOINT-SPEC.md §2.1\n');
+process.exit(1);

package/scripts/lint-no-direct-destructive.js

@@ -88,6 +88,10 @@ const ALLOWLIST = new Set([
   // completeness) — read-only `git diff --cached --name-only` for --staged.
   // Cannot depend on the TS funnel because TS is not compiled at pre-push.
   'scripts/lint-llm-attribution.js',
+  // Same bootstrap-escape pattern (cartographer main-thread-walk lint, fix
+  // instar#1069) — read-only `git diff --cached --name-only` for --staged.
+  // Cannot depend on the TS funnel because TS is not compiled at pre-push.
+  'scripts/lint-no-mainthread-cartographer-walk.js',
   // Postinstall bootstrap script — runs before TypeScript is compiled and
   // before SafeFsExecutor is available. CommonJS, can't use ESM imports.
   'scripts/fix-better-sqlite3.cjs',

package/scripts/lint-no-mainthread-cartographer-walk.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * lint-no-mainthread-cartographer-walk.js — refuses the O(nodeCount)/67MB
+ * synchronous cartographer operations on the server's main-thread surfaces.
+ *
+ * Earned by instar#1069: enabling the doc-freshness sweep on a real tree
+ * (366,757 nodes / 67MB index) put the AgentServer into a supervisor kill-loop.
+ * The "what's stale?" detect read + walked the whole index ON THE MAIN EVENT
+ * LOOP, starving /health for ~35s at a stretch, so the supervisor declared the
+ * (alive) server dead and force-restarted it — every ~10-15 min.
+ *
+ * The fix moved the detect + index writes off the event loop (a worker thread)
+ * and made every /cartographer/* route serve a cheap snapshot. This lint stops
+ * the regression from returning: "Structure > Willpower", not "enforced by review".
+ *
+ * Rule (PATH-ALLOWLIST — a callsite lint matches FILES, not runtime threads):
+ *   FORBIDDEN in the main-thread surfaces:
+ *     - src/server/routes.ts                 (the request thread)
+ *     - src/core/CartographerSweepEngine.ts  (the sweep poller thread = main loop)
+ *   the heavy calls: .staleNodes(  .loadIndex(  .freshnessHealth(  .scaffold(
+ *   PERMITTED everywhere else, specifically:
+ *     - src/core/cartographerDetect.ts  (the pure module — legitimately parses, OFF-thread)
+ *     - src/core/CartographerTree.ts    (the definitions of these methods)
+ *     - tests/                          (tests scaffold/load directly)
+ *   The bounded request loader (`.loadIndexBounded(`) is NOT matched — it stats
+ *   the file and refuses before parsing, so it is safe on the request thread.
+ *
+ * Escape hatch (closed, reviewed): a genuinely off-thread / boot-only call may
+ * carry an inline justification on the same line or directly above:
+ *     // lint-allow-carto-heavy: <why this can't starve the event loop>
+ *
+ * Exit codes: 0 — clean; 1 — at least one violation.
+ * Usage:
+ *   node scripts/lint-no-mainthread-cartographer-walk.js            # full repo
+ *   node scripts/lint-no-mainthread-cartographer-walk.js --staged   # staged files
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const ROOT = path.resolve(path.dirname(__filename), '..');
+
+// The main-thread surfaces where these heavy calls re-introduce #1069.
+const FORBIDDEN_FILES = new Set([
+  'src/server/routes.ts',
+  'src/core/CartographerSweepEngine.ts',
+]);
+
+// .staleNodes( / .loadIndex( / .freshnessHealth( / .scaffold(  — note the trailing
+// `\(` means `.loadIndexBounded(` (the safe byte-bounded loader) is NOT matched.
+const VIOLATION = /\.(staleNodes|loadIndex|freshnessHealth|scaffold)\(/;
+const ALLOW = /lint-allow-carto-heavy:/;
+
+function listFiles() {
+  if (process.argv.includes('--staged')) {
+    const out = execSync('git diff --cached --name-only', { cwd: ROOT, encoding: 'utf-8' });
+    return out.split('\n').filter(Boolean);
+  }
+  const explicit = process.argv.slice(2).filter((a) => !a.startsWith('--'));
+  if (explicit.length) return explicit;
+  return [...FORBIDDEN_FILES];
+}
+
+let violations = 0;
+for (const rel of listFiles()) {
+  const normalized = rel.split(path.sep).join('/');
+  if (!FORBIDDEN_FILES.has(normalized)) continue; // only the main-thread surfaces are enforced
+  const full = path.isAbsolute(normalized) ? normalized : path.join(ROOT, normalized);
+  let content;
+  try { content = fs.readFileSync(full, 'utf-8'); } catch { continue; }
+  const lines = content.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = lines[i].trimStart();
+    if (/^(\/\/|\*|\/\*)/.test(trimmed)) continue; // comment-only mention
+    if (!VIOLATION.test(lines[i])) continue;
+    let allowed = false;
+    for (let j = i; j >= Math.max(0, i - 6); j--) {
+      if (ALLOW.test(lines[j])) { allowed = true; break; }
+    }
+    if (allowed) continue;
+    const m = lines[i].match(VIOLATION);
+    console.error(
+      `${normalized}:${i + 1} — main-thread cartographer ${m ? m[1] + '()' : 'walk'} ` +
+      `(O(nodeCount)/67MB synchronous) on a server hot path. This is the instar#1069 ` +
+      `kill-loop regression. Use the off-event-loop detect (cartographerDetect.runDetect) ` +
+      `or serve the snapshot / use loadIndexBounded(). If genuinely off-thread/boot-only, ` +
+      `add "// lint-allow-carto-heavy: <reason>".`,
+    );
+    violations++;
+  }
+}
+
+if (violations > 0) {
+  console.error(`\nlint-no-mainthread-cartographer-walk: ${violations} violation(s). ` +
+    `See docs/specs/CARTOGRAPHER-SWEEP-EVENTLOOP-SAFETY.md (fix instar#1069).`);
+  process.exit(1);
+}
+console.log('lint-no-mainthread-cartographer-walk: clean');