instar 1.3.758 → 1.3.760

package/dist/testing/selfActionRegistry.d.ts

@@ -0,0 +1,88 @@
+/**
+ * selfActionRegistry.ts — the self-action controller registry (Part D1 of
+ * docs/specs/self-action-convergence.md). This is the single list the
+ * convergence ratchet (`tests/unit/self-action-convergence.test.ts`) iterates,
+ * the direct analog of `lint-no-unbounded-llm-spawn.js`'s one closed set of
+ * provider classes: one place to look, one thing the ratchet drives.
+ *
+ * WHY a modeled registry (not the live controllers): the real controllers
+ * (SubscriptionPool proactive swap, SessionReaper age-kill, PromiseBeacon) are
+ * bound to tmux, HTTP, config, and a real wall clock — undrivable
+ * deterministically. Each entry here is a FAITHFUL, minimal convergence MODEL of
+ * a real controller's trigger -> brake -> emit shape under the pinned
+ * sustained-pressure fixture (Part D2), with a pointer to the real source. The
+ * ratchet proves the BRAKE converges; the forcing lint
+ * (`scripts/lint-no-unregistered-self-action.js`) proves COMPLETENESS (a new
+ * self-action emit must register here). The two together make the closure
+ * genuine rather than opt-in.
+ *
+ * Constitution: "Capacity Safety — No Unbounded Self-Action" (the temporal twin
+ * of "Bounded Blast Radius": BBR bounds instantaneous MASS, this bounds
+ * steady-state FREQUENCY under feedback).
+ */
+/** A deterministic virtual clock — no real time, no randomness (a fixed adversary). */
+export interface VirtualClock {
+    nowMs(): number;
+    advance(ms: number): void;
+}
+/**
+ * The sustained worst case that never clears on its own — the exact condition
+ * swap-thrash ran under. Deterministic by construction (no fuzzing): a ping-pong
+ * cannot hide behind randomness.
+ */
+export interface PressureFixture {
+    clock: VirtualClock;
+    /** All quota readings >= threshold, forever (the all-hot condition). */
+    everyAccountHot(): boolean;
+    /** All sessions mid-turn / carrying subagents (no idle window ever opens). */
+    everySessionBusy(): boolean;
+    /** The peer/CI/flush the loop retries against always rejects (veto never clears). */
+    targetAlwaysRejects(): boolean;
+    /** A polled quota value that LAGS real state — so a just-vacated account still reads sub-threshold. */
+    staleQuotaReading(accountId: string): number;
+}
+/**
+ * Where a controller's actions land. `considered` proves the fixture actually
+ * pressured the controller (a controller cannot pass by being inertly idle);
+ * `count` is the invariant subject; `perTarget` feeds the anti-ping-pong check.
+ */
+export interface ActionSink {
+    emit(action: {
+        verb: string;
+        target: string;
+    }): void;
+    count: number;
+    perTarget: Map<string, number>;
+    considered: number;
+    /** Virtual-clock timestamps of each emit, for the eternal-sentinel rate-floor assertion. */
+    emitTimesMs: number[];
+}
+/** Create a fresh sink. */
+export declare function makeActionSink(): ActionSink;
+export interface SelfActionController {
+    /** Stable id (greppable by the forcing lint). */
+    id: string;
+    /** The action verb — MUST contain a detector token (SELF_ACTION_VERB_TOKENS). */
+    actionVerb: string;
+    /** Real source this models (documentation + audit trail). */
+    models: string;
+    /** Build the controller under a fixture + sink; returns something with tick(). */
+    makeUnderPressure(f: PressureFixture, sink: ActionSink): {
+        tick(): void;
+    };
+    /** Proven max total actions over `ticks` under the pinned pressure. */
+    boundK: number;
+    /** Proven max actions against ANY single target (anti-ping-pong). */
+    perTargetBoundK: number;
+    /** N — the sustained-pressure horizon (ticks driven). */
+    ticks: number;
+    /** Virtual ms the clock advances each tick. */
+    tickMs: number;
+    /** A declared Eternal Sentinel (P19 exemption) — replaces the count bound with a rate-floor bound. */
+    eternalSentinel?: {
+        reason: string;
+        rateFloorMs: number;
+    };
+}
+export declare const SELF_ACTION_CONTROLLERS: SelfActionController[];
+//# sourceMappingURL=selfActionRegistry.d.ts.map

package/dist/testing/selfActionRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selfActionRegistry.d.ts","sourceRoot":"","sources":["../../src/testing/selfActionRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,uFAAuF;AACvF,MAAM,WAAW,YAAY;IAC3B,KAAK,IAAI,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,YAAY,CAAC;IACpB,wEAAwE;IACxE,eAAe,IAAI,OAAO,CAAC;IAC3B,8EAA8E;IAC9E,gBAAgB,IAAI,OAAO,CAAC;IAC5B,qFAAqF;IACrF,mBAAmB,IAAI,OAAO,CAAC;IAC/B,uGAAuG;IACvG,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;CAC9C;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,4FAA4F;IAC5F,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,2BAA2B;AAC3B,wBAAgB,cAAc,IAAI,UAAU,CAY3C;AAED,MAAM,WAAW,oBAAoB;IACnC,iDAAiD;IACjD,EAAE,EAAE,MAAM,CAAC;IACX,iFAAiF;IACjF,UAAU,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,iBAAiB,CAAC,CAAC,EAAE,eAAe,EAAE,IAAI,EAAE,UAAU,GAAG;QAAE,IAAI,IAAI,IAAI,CAAA;KAAE,CAAC;IAC1E,uEAAuE;IACvE,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,eAAe,EAAE,MAAM,CAAC;IACxB,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,sGAAsG;IACtG,eAAe,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3D;AAiKD,eAAO,MAAM,uBAAuB,EAAE,oBAAoB,EAKzD,CAAC"}

package/dist/testing/selfActionRegistry.js

@@ -0,0 +1,202 @@
+/**
+ * selfActionRegistry.ts — the self-action controller registry (Part D1 of
+ * docs/specs/self-action-convergence.md). This is the single list the
+ * convergence ratchet (`tests/unit/self-action-convergence.test.ts`) iterates,
+ * the direct analog of `lint-no-unbounded-llm-spawn.js`'s one closed set of
+ * provider classes: one place to look, one thing the ratchet drives.
+ *
+ * WHY a modeled registry (not the live controllers): the real controllers
+ * (SubscriptionPool proactive swap, SessionReaper age-kill, PromiseBeacon) are
+ * bound to tmux, HTTP, config, and a real wall clock — undrivable
+ * deterministically. Each entry here is a FAITHFUL, minimal convergence MODEL of
+ * a real controller's trigger -> brake -> emit shape under the pinned
+ * sustained-pressure fixture (Part D2), with a pointer to the real source. The
+ * ratchet proves the BRAKE converges; the forcing lint
+ * (`scripts/lint-no-unregistered-self-action.js`) proves COMPLETENESS (a new
+ * self-action emit must register here). The two together make the closure
+ * genuine rather than opt-in.
+ *
+ * Constitution: "Capacity Safety — No Unbounded Self-Action" (the temporal twin
+ * of "Bounded Blast Radius": BBR bounds instantaneous MASS, this bounds
+ * steady-state FREQUENCY under feedback).
+ */
+/** Create a fresh sink. */
+export function makeActionSink() {
+    const sink = {
+        count: 0,
+        considered: 0,
+        perTarget: new Map(),
+        emitTimesMs: [],
+        emit(action) {
+            sink.count += 1;
+            sink.perTarget.set(action.target, (sink.perTarget.get(action.target) ?? 0) + 1);
+        },
+    };
+    return sink;
+}
+// ── The seeded controllers ─────────────────────────────────────────────────
+/**
+ * proactive-swap-monitor — THE presenting case (#1035, ff3083a31). The real
+ * proactive pre-limit account swap self-triggered ~72 swaps/day via a
+ * quota-POSITIVE kill+respawn. Models the shipped "three brakes" fix
+ * (SubscriptionPool proactiveSwap antiThrash): under the pinned all-hot
+ * fixture, the ALL-HOT brake refuses every candidate swap (STAY PUT) and the
+ * projected-post-swap-load gate refuses a target that a stale reading makes look
+ * cool-but-actually-hot — so the count settles to 0, horizon-independent, not
+ * 72/day.
+ */
+const proactiveSwapMonitor = {
+    id: 'proactive-swap-monitor',
+    actionVerb: 'account-swap',
+    models: 'src/monitoring/SubscriptionPool.ts (proactive pre-limit swap, antiThrash all-hot + projected-load brake)',
+    boundK: 1,
+    perTargetBoundK: 1,
+    ticks: 20,
+    tickMs: 5 * 60_000, // 5 min/tick — crosses the ~45-min dwell window several times
+    makeUnderPressure(f, sink) {
+        const CANDIDATES = ['acct-A', 'acct-B'];
+        const REHYDRATION_BURST_PCT = 15; // a swap's own kill+re-hydrate lands on the destination
+        return {
+            tick() {
+                sink.considered += 1;
+                // Brake 1 — ALL-HOT: when every account reads hot, staying put beats a
+                // pointless kill+re-hydrate. Under the pinned fixture this is true
+                // forever, so the loop converges to 0 (the swap-thrash fix).
+                if (f.everyAccountHot())
+                    return;
+                // Brake 2 — PROJECTED-POST-SWAP-LOAD: gate on (target current + this
+                // swap's re-hydration burst), NOT the stale current reading. A target
+                // that a lagging poll makes look cool but that this swap would itself
+                // push hot is refused — the amplifying edge that caused the ping-pong.
+                const target = CANDIDATES.find((id) => {
+                    const projected = f.staleQuotaReading(id) + REHYDRATION_BURST_PCT;
+                    return projected < 80;
+                });
+                if (!target)
+                    return; // no MATERIALLY-cooler destination -> stay put
+                sink.emit({ verb: 'account-swap', target });
+            },
+        };
+    },
+};
+/**
+ * age-kill-backoff — the 2026-06-05 reaper age-gate that fired 17,503 identical
+ * kill requests/day (request -> veto -> re-request every 5s). Models the P19
+ * fix: exponential backoff between attempts + a breaker cap that gives up
+ * LOUDLY. Under the pinned targetAlwaysRejects fixture (the veto never clears —
+ * a protected/in-flight session), the count settles to `maxAttempts` and the
+ * breaker opens, horizon-independent.
+ */
+const ageKillBackoff = {
+    id: 'age-kill-backoff',
+    actionVerb: 'age-kill',
+    models: 'src/monitoring/SessionReaper.ts (age-limit kill-request; AgeKillBackoff — P19 backoff + breaker)',
+    boundK: 5,
+    perTargetBoundK: 5, // legitimately the SAME session, bounded by the breaker (not a ping-pong)
+    // Horizon chosen so N ticks FULLY reaches the breaker cap (cumulative
+    // exponential backoff to the 5th attempt is ~150s = 30 ticks); N=50 and
+    // 2N=100 both settle at 5, so the horizon-independence check is exact.
+    ticks: 50,
+    tickMs: 5_000, // 5s/tick — the original re-request cadence
+    eternalSentinel: undefined,
+    makeUnderPressure(f, sink) {
+        const MAX_ATTEMPTS = 5;
+        const BACKOFF_BASE_MS = 5_000;
+        const TARGET = 'over-age-session';
+        let attempts = 0;
+        let nextAllowedAtMs = 0;
+        let breakerOpen = false;
+        return {
+            tick() {
+                sink.considered += 1;
+                if (breakerOpen)
+                    return; // P19 breaker — gave up LOUDLY (in real code: one aggregated attention item)
+                if (f.clock.nowMs() < nextAllowedAtMs)
+                    return; // dwell inside the backoff window
+                sink.emit({ verb: 'requestKill', target: TARGET });
+                attempts += 1;
+                if (f.targetAlwaysRejects()) {
+                    // Exponential backoff, then trip the breaker at the cap.
+                    nextAllowedAtMs = f.clock.nowMs() + BACKOFF_BASE_MS * 2 ** attempts;
+                    if (attempts >= MAX_ATTEMPTS)
+                        breakerOpen = true;
+                }
+            },
+        };
+    },
+};
+/**
+ * promise-beacon-notify — the ⏳ "still on it, no new output" heartbeat that
+ * used to fire every tick (zero-information spam). Models the honest-progress
+ * fix (PromiseBeacon suppressUnchangedHeartbeats): under the worst case
+ * (everySessionBusy with NO genuine new progress ever), the progress heartbeat
+ * is SUPPRESSED every tick -> count 0, horizon-independent. (The sparse
+ * once-per-interval liveness line is the SEPARATE eternal-sentinel controller
+ * below — a rate-floored constant-cost heartbeat, not a bounded action.)
+ */
+const promiseBeaconNotify = {
+    id: 'promise-beacon-notify',
+    actionVerb: 'beacon-notify',
+    models: 'src/monitoring/PromiseBeacon.ts (suppressUnchangedHeartbeats — progress-only heartbeat)',
+    boundK: 1,
+    perTargetBoundK: 1,
+    ticks: 20,
+    tickMs: 20 * 60_000, // 20 min/tick (the relaxed base cadence)
+    makeUnderPressure(f, sink) {
+        return {
+            tick() {
+                sink.considered += 1;
+                // The worst case: work is happening (everySessionBusy) but the terminal
+                // frame never CHANGES — the exact "busy long task looks identical to a
+                // frozen one" the fix addresses. No new progress -> suppress. Emitting a
+                // filler line here is precisely the zero-info spam the fix removed.
+                const hasGenuineNewProgress = false;
+                if (hasGenuineNewProgress) {
+                    sink.emit({ verb: 'notify', target: 'topic-progress' });
+                }
+            },
+        };
+    },
+};
+/**
+ * liveness-heartbeat — a DECLARED Eternal Sentinel (P19 exemption). A sparse,
+ * constant-cost "I'm alive" line on a rate FLOOR (the once-per-60m liveness the
+ * PromiseBeacon still emits). It is EXEMPT from a total-count bound by design;
+ * the ratchet asserts the P19 four conditions instead — a constant per-attempt
+ * cost + a rate floor that prevents accumulation (emits never exceed
+ * elapsed/rateFloorMs). This exercises the ratchet's eternal-sentinel path so
+ * the exemption is a tested contract, not prose.
+ */
+const livenessHeartbeat = {
+    id: 'liveness-heartbeat',
+    actionVerb: 'liveness-notify',
+    models: 'src/monitoring/PromiseBeacon.ts (beaconLivenessIntervalMs — sparse once-per-interval liveness line)',
+    boundK: Number.POSITIVE_INFINITY, // exempt — bounded by the rate floor, not a total count
+    perTargetBoundK: Number.POSITIVE_INFINITY,
+    ticks: 24,
+    tickMs: 20 * 60_000, // 20 min/tick
+    eternalSentinel: { reason: 'sparse constant-cost liveness heartbeat', rateFloorMs: 60 * 60_000 },
+    makeUnderPressure(f, sink) {
+        const RATE_FLOOR_MS = 60 * 60_000;
+        let lastEmitAtMs = Number.NEGATIVE_INFINITY;
+        return {
+            tick() {
+                sink.considered += 1;
+                // Constant per-attempt cost (one fixed-size line) + a hard rate floor:
+                // emit ONLY if at least RATE_FLOOR_MS has elapsed since the last line.
+                if (f.clock.nowMs() - lastEmitAtMs >= RATE_FLOOR_MS) {
+                    sink.emit({ verb: 'notify', target: 'topic-liveness' });
+                    sink.emitTimesMs.push(f.clock.nowMs());
+                    lastEmitAtMs = f.clock.nowMs();
+                }
+            },
+        };
+    },
+};
+export const SELF_ACTION_CONTROLLERS = [
+    proactiveSwapMonitor,
+    ageKillBackoff,
+    promiseBeaconNotify,
+    livenessHeartbeat,
+];
+//# sourceMappingURL=selfActionRegistry.js.map

package/dist/testing/selfActionRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selfActionRegistry.js","sourceRoot":"","sources":["../../src/testing/selfActionRegistry.ts"],"names":[],"mappings":"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"}

package/package.json

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

package/scripts/class-closure-declare.mjs

@@ -27,6 +27,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 const DECISIONS_REL = path.join('.instar', 'instar-dev-decisions');
+const TRACES_REL = path.join('.instar', 'instar-dev-traces');
 
 /** Parse `--key value` / `--flag` pairs into a plain object. */
 export function parseArgs(argv) {
@@ -67,10 +68,20 @@ export function buildClassClosureBlock(args) {
   if (!args.class || typeof args.class !== 'string') throw new Error('--class <id|novel> is required');
   block.defectClass = args.class;
   const closure = args.closure;
-  if (closure !== 'guard' && closure !== 'gap') throw new Error("--closure must be 'guard' or 'gap'");
+  // 'n/a' is the NEGATIVE declaration (docs/specs/self-action-convergence.md →
+  // E3): a genuine one-shot / user-driven action, not a self-triggered loop —
+  // the trace-level analog of the D4 lint's allowlist entry. Requires a reason.
+  if (closure !== 'guard' && closure !== 'gap' && closure !== 'n/a') {
+    throw new Error("--closure must be 'guard', 'gap', or 'n/a' (negative declaration)");
+  }
   block.closure = closure;
 
-  if (closure === 'guard') {
+  if (closure === 'n/a') {
+    if (!args.reason || typeof args.reason !== 'string') {
+      throw new Error("closure 'n/a' (negative declaration) requires --reason \"<why this is a one-shot / user-driven action, not a loop>\"");
+    }
+    block.reason = args.reason;
+  } else if (closure === 'guard') {
     if (!args.citation || typeof args.citation !== 'string') throw new Error("closure 'guard' requires --citation <path|route|symbol>");
     block.guardEvidence = {
       enforcementType: typeof args.enforcement === 'string' ? args.enforcement : undefined,
@@ -166,11 +177,65 @@ export function applyDeclaration(repoRoot, block) {
   return { changed: true, file: target.file, block };
 }
 
+/** Find the most-recent instar-dev TRACE file (by mtime). */
+export function findMostRecentTrace(repoRoot) {
+  const dir = path.join(repoRoot, TRACES_REL);
+  let files;
+  try {
+    files = fs.readdirSync(dir).filter((f) => f.endsWith('.json'));
+  } catch {
+    return null;
+  }
+  if (files.length === 0) return null;
+  let best = null;
+  for (const f of files) {
+    const full = path.join(dir, f);
+    let mtime;
+    try {
+      mtime = fs.statSync(full).mtimeMs;
+    } catch {
+      continue;
+    }
+    if (best === null || mtime > best.mtime) best = { file: full, mtime };
+  }
+  if (!best) return null;
+  let entry;
+  try {
+    entry = JSON.parse(fs.readFileSync(best.file, 'utf-8'));
+  } catch {
+    return null;
+  }
+  return { file: best.file, entry };
+}
+
+/**
+ * Merge the block into the most-recent instar-dev TRACE (the E3 declaration
+ * host — the same place `specPath`/`tier`/`causalAutopsy` live, authored BEFORE
+ * the commit). Idempotent. The precommit's writeDecisionAudit then persists it
+ * into the machine-readable decision-audit entry.
+ * @returns {{ changed: boolean, file: string, block: object }}
+ */
+export function applyDeclarationToTrace(repoRoot, block) {
+  const target = findMostRecentTrace(repoRoot);
+  if (!target) {
+    throw new Error(`no instar-dev trace found under ${TRACES_REL} to attach the declaration to (run the /instar-dev skill first)`);
+  }
+  const before = JSON.stringify(target.entry.classClosure ?? null);
+  const after = JSON.stringify(block);
+  if (before === after) {
+    return { changed: false, file: target.file, block };
+  }
+  target.entry.classClosure = block;
+  fs.writeFileSync(target.file, `${JSON.stringify(target.entry, null, 2)}\n`, 'utf-8');
+  return { changed: true, file: target.file, block };
+}
+
 // ── CLI entrypoint ──────────────────────────────────────────────────────────
 const invokedDirectly = process.argv[1] && import.meta.url.endsWith(process.argv[1].split('/').pop());
 if (invokedDirectly) {
   const repoRoot = process.env.CLASS_CLOSURE_REPO_ROOT || process.cwd();
   const args = parseArgs(process.argv.slice(2));
+  const toTrace = args['to-trace'] === true;
   let block;
   try {
     block = buildClassClosureBlock(args);
@@ -180,12 +245,12 @@ if (invokedDirectly) {
   }
   let result;
   try {
-    result = applyDeclaration(repoRoot, block);
+    result = toTrace ? applyDeclarationToTrace(repoRoot, block) : applyDeclaration(repoRoot, block);
   } catch (err) {
     console.error(`class-closure-declare: ${err instanceof Error ? err.message : String(err)}`);
     process.exit(2);
   }
-  console.log(`class-closure-declare: ${result.changed ? 'wrote' : 'no change (idempotent)'} classClosure into ${path.relative(repoRoot, result.file)}`);
+  console.log(`class-closure-declare: ${result.changed ? 'wrote' : 'no change (idempotent)'} classClosure into ${path.relative(repoRoot, result.file)}${toTrace ? ' (trace host)' : ''}`);
   console.log(JSON.stringify(result.block, null, 2));
   process.exit(0);
 }

package/scripts/class-closure-lint.mjs

@@ -54,9 +54,27 @@ import {
   REGISTRY_REL_PATH,
 } from './lib/defect-class-registry.mjs';
 import { evaluateGuardClosure } from './lib/class-closure-grader.mjs';
+import { isSelfActionControllerFile } from './lib/self-action-detect.mjs';
 
 const DEFAULT_CONFIG = { enabled: false, dryRun: true, escalatorDrafting: false };
 
+// The self-action class id + the convergence-argument regex (Part E2). A
+// `defectClass: unbounded-self-action` + `closure: guard` declaration's
+// guardEvidence.howCaught must ADDRESS the convergence argument (control-loop
+// edge + steady-state bound + settling brake) — a per-tick-cap-only
+// justification does NOT address it.
+const SELF_ACTION_CLASS_ID = 'unbounded-self-action';
+const CONVERGENCE_ADDRESSED = /converge|steady[- ]?state|bound|dwell|hysteresis|all[- ]?hot|projected.*load|breaker/i;
+
+/** Read a repo file, or null (a deleted/binary path in a diff). */
+function readFileMaybe(repoRoot, rel) {
+  try {
+    return fs.readFileSync(path.join(repoRoot, rel), 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
 /**
  * The agent-authored-artifact predicate — a fix touching one of these is
  * IN SCOPE for the class declaration (docs/specs/class-closure-gate.md →
@@ -92,7 +110,14 @@ export function isGateSourceFile(file) {
     f === 'docs/defect-classes.json' ||
     f === '.github/workflows/class-closure-gate.yml' ||
     f === 'docs/specs/class-closure-gate.md' ||
-    /^tests\/(unit|integration)\/class-closure-/.test(f)
+    /^tests\/(unit|integration)\/class-closure-/.test(f) ||
+    // The self-action gate's own source (docs/specs/self-action-convergence.md
+    // → Part E5): a broken self-action gate can never block its own repair.
+    f === 'scripts/lint-no-unregistered-self-action.js' ||
+    f === 'scripts/lib/self-action-detect.mjs' ||
+    f === 'src/testing/selfActionRegistry.ts' ||
+    f === 'docs/specs/self-action-convergence.md' ||
+    /^tests\/(unit|integration)\/self-action-/.test(f)
   );
 }
 
@@ -169,6 +194,17 @@ function validateDeclaration(repoRoot, decl, knownClassIds) {
         findings.push(`${where}: guard citation resolves (${verdict.gradedKind}) — closure:'guard' upheld`);
       }
     }
+    // Class-specific arm (Part E2): for the unbounded-self-action class, the
+    // convergence ARGUMENT must be addressed in howCaught — a per-tick-cap-only
+    // justification bounds one pass, never the loop. A hard violation when
+    // enforcing (returned to the caller so it can gate).
+    if (decl.defectClass === SELF_ACTION_CLASS_ID) {
+      const howCaught = decl.guardEvidence && decl.guardEvidence.howCaught;
+      if (typeof howCaught !== 'string' || !CONVERGENCE_ADDRESSED.test(howCaught)) {
+        findings.push(`${where}: unbounded-self-action closure:'guard' howCaught does NOT address convergence (steady-state bound / settling brake / dwell / all-hot / breaker) — a per-tick-cap-only justification is insufficient`);
+        hardViolations.push(`${where}: unbounded-self-action guard howCaught fails the convergence-addressed check (E2)`);
+      }
+    }
   } else if (decl.closure === 'gap') {
     if (!decl.gapItem || typeof decl.gapItem !== 'string') {
       findings.push(`${where}: closure:'gap' should cite a tracked gap item (gapItem) — none provided`);
@@ -247,12 +283,19 @@ export function runClassClosureLint(input) {
     findings.push('mirror-consistency: counted the decision-audit host only (side-effects mirror is display-only) — trivially satisfied');
   }
 
-  // Diff-scope: does this PR touch an agent-authored artifact needing a declaration?
+  // Diff-scope: does this PR touch an agent-authored artifact OR a self-action
+  // controller (Part E2 — the concrete realization of #1347 Frontloaded
+  // Decision 1) needing a declaration?
   let inScope = false;
   let exempt;
   if (changedFiles && changedFiles.length > 0) {
     const agentFiles = changedFiles.filter(isAgentAuthoredArtifact);
-    inScope = agentFiles.length > 0;
+    // A diff touching a self-action controller file (name-shape or marker) is
+    // in scope for the unbounded-self-action declaration.
+    const selfActionFiles = changedFiles.filter((f) =>
+      isSelfActionControllerFile(f, readFileMaybe(repoRoot, f)),
+    );
+    inScope = agentFiles.length > 0 || selfActionFiles.length > 0;
     if (inScope) {
       // Gate-source-ONLY self-wedge exemption: applies ONLY when the diff
       // touches EXCLUSIVELY the gate's own source (a mixed PR cannot ride it).
@@ -260,8 +303,21 @@ export function runClassClosureLint(input) {
       if (allGateSource) {
         exempt = 'gate-source-only';
         findings.push('exempt: diff touches EXCLUSIVELY the gate\'s own source (gate-source-only self-wedge exemption, logged)');
-      } else if (declarations.length === 0) {
-        findings.push('missing class declaration (report-only) — this PR touches agent-authored artifacts but carries no classClosure declaration');
+      } else {
+        if (declarations.length === 0) {
+          findings.push('missing class declaration (report-only) — this PR touches agent-authored artifacts or self-action controllers but carries no classClosure declaration');
+        }
+        // Enforcement condition (i) (Part E2): an in-scope SELF-ACTION diff with
+        // no unbounded-self-action declaration is a hard violation when
+        // enforcing (report-only until prGate.classClosure.dryRun:false).
+        if (selfActionFiles.length > 0) {
+          const hasSelfActionDecl = declarations.some((d) => d.defectClass === SELF_ACTION_CLASS_ID);
+          if (!hasSelfActionDecl) {
+            const msg = `self-action controller(s) touched (${selfActionFiles.join(', ')}) but no unbounded-self-action classClosure declaration is present`;
+            findings.push(`missing unbounded-self-action declaration — ${msg}`);
+            hardViolations.push(msg);
+          }
+        }
       }
     }
   }