create-walle 0.10.1 → 0.10.2

package/template/wall-e/lib/coding-journal-writer-child-client.js

@@ -20,7 +20,6 @@ const SAFE_ENV_KEYS = [
   'WALL_E_SQLITE_STORAGE_POLICY',
   'WALL_E_SQLITE_BUSY_TIMEOUT_MS',
   'WALL_E_SQLITE_WRITE_LOCK_TIMEOUT_MS',
-  'WALL_E_SQLITE_WRITE_LOCK_STALE_MS',
   'WALL_E_BRAIN_BOOT_LOCK_WAIT_MS',
   'WALL_E_SQLITE_SYNCHRONOUS',
   'WALL_E_SQLITE_WAL_AUTOCHECKPOINT_PAGES',
@@ -82,16 +81,48 @@ function writeJournalEntryInChild(entry, options = {}) {
       serialization: 'json',
     });
   } catch (error) {
+    // C7: a fork that threw synchronously returned no child, so this call owns
+    // nothing to watch and nothing to terminate — reject with the original value.
     return Promise.reject(error);
   }
 
   return new Promise((resolve, reject) => {
+    // C7: the application result (one reply envelope) and the native lifecycle
+    // (exit/close) are two separate facts about the same child. Only the child's
+    // own 'close' finalizes this operation — a reply envelope or 'exit' alone
+    // leaves the operation pending, because the child may still be running (or
+    // may still die badly) after either one.
+    let replied = false;
+    let replyResult = null;
+    let failed = false; // explicit Boolean: a falsy thrown value is still a failure
+    let failure = null;
+    let nativeExited = false; // 'exit' seen: the process is gone, its stdio is not necessarily closed
+    let nativeClosed = false; // 'close' seen: the only fact that finalizes this operation
+    let terminationRequested = false;
     let settled = false;
+
+    const recordFailure = (error) => {
+      // The FIRST failure wins, verbatim (identity and value): later errors, the
+      // deadline and a nonzero native close must never replace it.
+      if (failed) return;
+      failed = true;
+      failure = error;
+    };
+    const requestTermination = () => {
+      if (terminationRequested) return;
+      // Marked BEFORE kill: an 'error' emitted by the kill call itself must not
+      // re-enter here and signal the same child twice.
+      terminationRequested = true;
+      if (nativeExited || nativeClosed) return; // never signal after the native exit/close was observed
+      try { child.kill('SIGKILL'); }
+      catch { /* expected: the child may already be gone; a throwing kill neither relinquishes ownership nor proves closure — the operation still joins the child's actual close below */ }
+    };
     const cleanup = () => {
       clearTimeout(timer);
       child.off('message', onMessage);
       child.off('error', onError);
       child.off('exit', onExit);
+      child.off('close', onClose);
     };
     const settle = (fn, value) => {
       if (settled) return false;
@@ -101,39 +132,57 @@ function writeJournalEntryInChild(entry, options = {}) {
       return true;
     };
     const onMessage = (message) => {
-      if (!message || message.type !== 'coding-journal-result') return;
-      if (message.ok) settle(resolve, message.result || null);
-      else {
-        const error = new Error(String(message.error || 'One-shot journal writer failed').slice(0, 500));
-        if (message.code) error.code = String(message.code).slice(0, 100);
-        settle(reject, error);
-      }
+      if (!message || message.type !== 'coding-journal-result') return; // unrelated envelope
+      if (replied) return; // first valid result wins; duplicate and late envelopes are ignored
+      replied = true;
+      if (message.ok) { replyResult = message.result || null; return; }
+      const error = new Error(String(message.error || 'One-shot journal writer failed').slice(0, 500));
+      if (message.code) error.code = String(message.code).slice(0, 100);
+      recordFailure(error);
+    };
+    const onError = (error) => {
+      // A process/IPC error is a failure but not a closure: the operation keeps
+      // waiting for the child's own close, and this first failure is preserved.
+      recordFailure(error);
+      requestTermination();
     };
-    const onError = (error) => settle(reject, error);
-    const onExit = (code, signal) => {
+    // 'exit' only records that the process is gone; the verdict reads the close
+    // event's own (code, signal), so exit and close can never be conflated.
+    const onExit = () => { nativeExited = true; };
+    const onClose = (code, signal) => {
+      nativeClosed = true;
+      // A falsy thrown value must not be laundered into a success: the boolean,
+      // not the value, says whether a failure happened.
+      if (failed) { settle(reject, failure); return; }
       const suffix = signal ? `signal ${signal}` : `code ${code}`;
-      settle(reject, new Error(`One-shot journal writer exited before replying (${suffix})`));
+      if (!replied) { settle(reject, new Error(`One-shot journal writer exited before replying (${suffix})`)); return; }
+      if (code === 0 && signal === null) { settle(resolve, replyResult); return; }
+      // Replied, then died badly: the reply alone is not proof the write survived.
+      const error = new Error(`One-shot journal writer exited after replying (${suffix})`);
+      error.code = 'WALL_E_JOURNAL_WRITER_EXIT';
+      settle(reject, error);
     };
     const timer = setTimeout(() => {
       const error = new Error(`One-shot journal writer timed out after ${timeoutMs}ms`);
       error.code = 'WALL_E_JOURNAL_WRITER_TIMEOUT';
-      if (!settle(reject, error)) return;
-      try { child.kill('SIGKILL'); } catch {}
+      recordFailure(error); // only the first failure is kept; the deadline joins the close
+      requestTermination();
     }, timeoutMs);
 
     child.on('message', onMessage);
-    child.once('error', onError);
-    child.once('exit', onExit);
+    child.on('error', onError);
+    child.on('exit', onExit);
+    child.on('close', onClose);
     try {
       child.send({
         type: 'persist-coding-journal',
         dbPath: path.resolve(dbPath),
         entry: JSON.parse(entryJson),
       });
+      // A false return is IPC backpressure, never a failure or a cancellation.
     } catch (error) {
-      if (settle(reject, error)) {
-        try { child.kill('SIGKILL'); } catch {}
-      }
+      recordFailure(error);
+      requestTermination();
     }
   });
 }

package/template/wall-e/lib/error-kinds.js

@@ -87,10 +87,19 @@ const CODE_KIND = Object.freeze({
   ANTHROPIC_WIRE_TOOL_NAME_INVALID: 'FATAL',
   // shared/sqlite-write-lock.js: process-liveness / lock-file-existence control-flow codes, not
   // genuine transient failures a retry loop should chase — the lock module already has its own
-  // stale-window / foreign-hold handling around these.
+  // foreign-hold handling around these (protocol 2 has no stale window: a dead holder's kernel
+  // lock is dropped by the OS, D-4). EISDIR is the same family as EEXIST: an object at the record
+  // path that is not our record file (the fail-fast fixtures use a directory) is somebody else's
+  // claim, and SQLITE_WRITE_LOCK_STATE is the lock DB found inside a transaction — a bug state,
+  // never a race worth retrying.
   ESRCH: 'FATAL',
   ENOENT: 'FATAL',
   EEXIST: 'FATAL',
+  EISDIR: 'FATAL',
+  SQLITE_WRITE_LOCK_STATE: 'FATAL',
+  // BEGIN EXCLUSIVE on the lock DB lost the race for the EXCLUSIVE lock: contention, exactly like
+  // SQLITE_WRITE_LOCK_BUSY above, and won by the same later attempt.
+  SQLITE_BUSY: 'WRITE_LOCK_BUSY',
   CTM_MAIN_WRITE_ESCAPE: 'FATAL',
   CTM_MAIN_THREAD_WRITE_FORBIDDEN: 'FATAL',
   // D-7 (WP-2): a loop wrote directly to a brain handle this process opened

package/template/wall-e/lib/feature-manifest.js

@@ -265,7 +265,7 @@ const FEATURES = [
   // numeric-tunable suffix/read shape; 1 site(s); first: wall-e/brain.js:1800
   { id: "walle_wall_e_sqlite_wal_autocheckpoint_pages", env: "WALL_E_SQLITE_WAL_AUTOCHECKPOINT_PAGES", owner: "wall-e-core-team", stage: "ops", tunable: true, default: 10, since: "2026-07-02", expires: null, note: "numeric tunable" },
   // numeric-tunable suffix/read shape; 1 site(s); first: wall-e/brain.js:1769
-  { id: "walle_wall_e_sqlite_write_lock_stale_ms", env: "WALL_E_SQLITE_WRITE_LOCK_STALE_MS", owner: "wall-e-core-team", stage: "ops", tunable: true, default: 10, since: "2026-05-21", expires: null, note: "numeric tunable" },
+  { id: "walle_wall_e_sqlite_write_lock_stale_ms", env: "WALL_E_SQLITE_WRITE_LOCK_STALE_MS", owner: "wall-e-core-team", stage: "removed", defaultOn: false, since: "2026-05-21", expires: null, note: "retired 2026-10-23 (fsevents-churn WP-1, coding-task-manager/docs/fsevents-churn-kernel-write-lock-2026-10-23.html D-4): the SQLite write lock is a kernel lock on a .mutex lock DB released by the OS when its holder dies, so stale-claim recovery and its age knob were deleted; no read of this name survives." },
   // numeric-tunable suffix/read shape; 1 site(s); first: wall-e/skills/script-skill-runner.js:64
   { id: "walle_wall_e_sqlite_write_lock_timeout_ms", env: "WALL_E_SQLITE_WRITE_LOCK_TIMEOUT_MS", owner: "wall-e-core-team", stage: "ops", tunable: true, default: 0, since: "2026-05-21", expires: null, note: "numeric tunable" },
   // bare truthy opt-in read; 1 site(s); first: wall-e/agent.js:55

package/template/wall-e/lib/helper-rules/cell-state.js

@@ -0,0 +1,123 @@
+'use strict';
+
+// WP-4 (lead-cost-routing-round1-2026-10-21.html §6.4): the ONE reader of a lead harness's
+// `explore` rule cell, plus the transport-facing plumbing both MCP transports need to gate the
+// exploration hand-off block appended to the `initialize` instructions.
+//
+// The cell is the row `cell_key = 'explore|default|<agent>'` in helper_rule_cells. WP-5 owns the
+// table's migration; this module NEVER creates it. A missing table, a missing row or any read
+// error means "never switched off" -- the state is 'on' (fail-open, the same shape as an absent
+// flag), so a brain built before WP-5 keeps serving today's guidance.
+//
+// States: 'on' (block appended), 'probe' (block appended, WP-5 owns what probe means) and 'off'
+// (plain SERVER_INSTRUCTIONS). Only those three values are recognized; anything else reads 'on'.
+
+const EXPLORE_STATES = Object.freeze(['on', 'off', 'probe']);
+const DEFAULT_EXPLORE_STATE = 'on';
+const GUIDANCE_PATH = '/api/wall-e/helper-rules/guidance';
+// The stdio proxy blocks its `initialize` reply on this fetch, so the deadline is short and the
+// failure mode is the fail-open default: a slow or dead daemon may not stall a client handshake.
+const GUIDANCE_TIMEOUT_MS = 1500;
+
+function readExploreCellState(db, agent = 'claude') {
+  if (!db || typeof db.prepare !== 'function') return DEFAULT_EXPLORE_STATE;
+  try {
+    const row = db.prepare('SELECT state FROM helper_rule_cells WHERE cell_key = ?')
+      .get(`explore|default|${agent}`);
+    const state = row && typeof row.state === 'string' ? row.state.trim() : '';
+    return EXPLORE_STATES.includes(state) ? state : DEFAULT_EXPLORE_STATE;
+  } catch {
+    // expected: helper_rule_cells is absent until WP-5's migration runs; a missing row means 'on'
+    return DEFAULT_EXPLORE_STATE;
+  }
+}
+
+function leadAgentFromClientInfo(clientInfo) {
+  return /codex/i.test(clientInfo?.name) ? 'codex' : 'claude';
+}
+
+// The daemon transport's one call: mcp-server.js already holds the brain module, and its getDb()
+// throws before initDb() -- which must not break the initialize reply, so the read is guarded here
+// rather than at the call site (the call site stays a single line, see mcp-server.js).
+function leadGuidanceForMessage(message, brainModule) {
+  // Only `initialize` carries instructions; every other MCP message skips the read entirely
+  // (an undefined leadGuidance leaves handleProtocolMessage on its no-option path).
+  if (!message || message.method !== 'initialize') return undefined;
+  let db = null;
+  try {
+    db = brainModule && typeof brainModule.getDb === 'function' ? brainModule.getDb() : brainModule;
+  } catch {
+    // expected: brain not initialized yet (initialize can arrive before/without a DB) -- 'on'
+    db = null;
+  }
+  return { explore: readExploreCellState(db, leadAgentFromClientInfo(message?.params?.clientInfo)) };
+}
+
+function guidancePathFor(agent) {
+  return `${GUIDANCE_PATH}?agent=${encodeURIComponent(agent)}`;
+}
+
+// The read-only GET the stdio transport performs against the daemon (the stdio process does not
+// own the brain). Kept here so bin/walle-mcp-stdio.js -- a frozen-ceiling file -- gains no logic.
+// `host`/`port` arrive from the caller: the transport owns endpoint resolution (no env read here).
+function httpJsonGet({ host = '127.0.0.1', port, path: requestPath, timeoutMs = GUIDANCE_TIMEOUT_MS } = {}) {
+  return new Promise((resolve, reject) => {
+    const req = require('node:http').request({ host, port, path: requestPath, method: 'GET', timeout: timeoutMs }, (res) => {
+      let raw = '';
+      res.setEncoding('utf8');
+      res.on('data', (chunk) => { raw += chunk; });
+      res.on('end', () => {
+        if (res.statusCode !== 200) {
+          reject(new Error(`helper-rules guidance returned HTTP ${res.statusCode}`));
+          return;
+        }
+        try {
+          resolve(JSON.parse(raw));
+        } catch (err) {
+          reject(err);
+        }
+      });
+      res.on('error', reject);
+    });
+    req.on('timeout', () => { req.destroy(new Error(`helper-rules guidance timed out after ${timeoutMs}ms`)); });
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+// requestFn is the transport's own request machinery: it is handed the guidance path and returns
+// the parsed JSON body (the stdio proxy passes its _executeDaemonRequest breaker wrapper around
+// httpJsonGet). Every failure -- no requestFn, refused, non-2xx, malformed body, or the timeout --
+// resolves to the fail-open default, so the transport always has an answer.
+async function fetchExploreCellState({ requestFn, agent = 'claude', timeoutMs = GUIDANCE_TIMEOUT_MS } = {}) {
+  let timer = null;
+  try {
+    if (typeof requestFn !== 'function') return DEFAULT_EXPLORE_STATE;
+    const payload = await Promise.race([
+      Promise.resolve(requestFn(guidancePathFor(agent))),
+      new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`helper-rules guidance fetch exceeded ${timeoutMs}ms`)), timeoutMs);
+      }),
+    ]);
+    const state = payload && typeof payload.explore === 'string' ? payload.explore.trim() : '';
+    return EXPLORE_STATES.includes(state) ? state : DEFAULT_EXPLORE_STATE;
+  } catch {
+    // expected: daemon unavailable/refusing/malformed -- 'on' keeps today's guidance served
+    return DEFAULT_EXPLORE_STATE;
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+module.exports = {
+  DEFAULT_EXPLORE_STATE,
+  EXPLORE_STATES,
+  GUIDANCE_PATH,
+  GUIDANCE_TIMEOUT_MS,
+  fetchExploreCellState,
+  guidancePathFor,
+  httpJsonGet,
+  leadAgentFromClientInfo,
+  leadGuidanceForMessage,
+  readExploreCellState,
+};

package/template/wall-e/lib/helper-rules/evaluate.js

@@ -0,0 +1,357 @@
+'use strict';
+
+// Lead-cost routing WP-5a (design §6.8): the PURE rule evaluator. One function, no I/O —
+// the caller (lib/helper-rules/store.js) reads the cell row and the trailing window and
+// owns every write. This is what makes "why did the cell turn off?" answerable in a test
+// and the panel honest: same inputs, same verdict.
+
+const { LABEL_VERSION } = require('./label');
+
+const WINDOW = 20;
+const MIN_LABELLED = 10;
+const WATCH_OFF_BELOW = 0.5;
+const WATCH_ON_ABOVE = 0.7;
+const EXPLORE_FALLBACK_MAX = 0.3;
+const EXPLORE_REREAD_MAX = 0.5;
+const EXPLORE_SUFFICIENT_MIN = 0.7;
+const EXPLORE_PROBE_AFTER_DAYS = 7;
+const PROBE_N = 10;
+const GRADED_MIN = 10;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+// Round 2 WP-2 (§5 D-7/D-10, §6.4): the two constants the measurability guard and the open-row
+// sweep need. No round-1 threshold moves — D-7 is additive by design (the design's §5 note).
+const EXPLORE_OPEN_TTL_MS = 4 * 60 * 60 * 1000; // D-10: worker deadline 1,800,000 ms × lease ceiling 4 = 2 h, doubled
+const UNMEASURED_MAX_SHARE = 0.5;                // D-7: an unmeasured/abandoned majority proves nothing
+
+const CELL_STATES = Object.freeze(['on', 'off', 'probe']);
+
+// The decisions an explore row may carry once it is no longer open. Anything else (a NULL from a
+// round-1 write, or a value this rule has never produced) is unmeasured — D-7's "no data is not
+// failure", applied to the row rather than to the window.
+const EXPLORE_DECISIONS = Object.freeze(['open', 'handoff', 'fallback', 'abandoned', 'unmeasured']);
+
+// Machine-readable reasons — short, stable strings the events table and the panel show.
+const REASONS = Object.freeze({
+  USER_VETO: 'user_veto',
+  WATCH_PRECISION_BELOW: `precision_below_${WATCH_OFF_BELOW}`,
+  WATCH_SILENT_PRECISION_ABOVE: `silent_precision_above_${WATCH_ON_ABOVE}`,
+  EXPLORE_FALLBACK_ABOVE: `fallback_rate_above_${EXPLORE_FALLBACK_MAX}`,
+  EXPLORE_REREAD_ABOVE: `reread_rate_above_${EXPLORE_REREAD_MAX}`,
+  EXPLORE_HELPER_USD_AT_OR_ABOVE: 'helper_usd_at_or_above_lead_burst',
+  EXPLORE_SUFFICIENT_BELOW: `sufficient_rate_below_${EXPLORE_SUFFICIENT_MIN}`,
+  EXPLORE_PROBE_AFTER: `probe_after_${EXPLORE_PROBE_AFTER_DAYS}_days`,
+  EXPLORE_PROBE_PASSED: 'probe_passed',
+  EXPLORE_PROBE_FAILED: 'probe_failed',
+  // D-6: the audit row the one-time recovery pass writes on every cell it returns to `on` after
+  // the v1 labels it was demoted on turned out to be a labelling bug. Distinct from the reasons
+  // above so a query can tell "the evaluator demoted this" from "the record repaired itself".
+  LABEL_V2_RESET: 'label_v2_reset',
+});
+
+// D-6: the DEMOTION set — the reasons that mean "the evaluator (not the user) turned this cell off
+// or into a probe on a window it could not measure". Only a cell whose LAST event carries one of
+// these may be returned to `on` by the relabel recovery pass; a `user_veto` never is.
+const EXPLORE_DEMOTION_REASONS = Object.freeze(new Set([
+  REASONS.EXPLORE_FALLBACK_ABOVE,
+  REASONS.EXPLORE_REREAD_ABOVE,
+  REASONS.EXPLORE_HELPER_USD_AT_OR_ABOVE,
+  REASONS.EXPLORE_SUFFICIENT_BELOW,
+  REASONS.EXPLORE_PROBE_FAILED,
+  REASONS.EXPLORE_PROBE_AFTER,
+]));
+
+function _stateOf(cell) {
+  const state = cell && typeof cell.state === 'string' ? cell.state.trim() : '';
+  return CELL_STATES.includes(state) ? state : 'on';
+}
+
+function _vetoOf(cell) {
+  return Boolean(cell && Number(cell.user_veto) === 1);
+}
+
+function _toMs(value) {
+  if (value == null) return null;
+  if (value instanceof Date) return Number.isFinite(value.getTime()) ? value.getTime() : null;
+  if (typeof value === 'number') return Number.isFinite(value) ? value : null;
+  const text = String(value).trim();
+  if (!text) return null;
+  // SQLite's datetime('now') writes 'YYYY-MM-DD HH:MM:SS' in UTC.
+  const iso = /^\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}:\d{2}$/.test(text) ? `${text.replace(' ', 'T')}Z` : text;
+  const ms = Date.parse(iso);
+  return Number.isFinite(ms) ? ms : null;
+}
+
+function _ratio(numerator, denominator) {
+  return denominator > 0 ? numerator / denominator : null;
+}
+
+function _median(values) {
+  const numbers = values.filter((value) => Number.isFinite(value)).sort((a, b) => a - b);
+  if (!numbers.length) return null;
+  const middle = Math.floor(numbers.length / 2);
+  return numbers.length % 2 === 1 ? numbers[middle] : (numbers[middle - 1] + numbers[middle]) / 2;
+}
+
+function _number(value) {
+  if (value == null || value === '') return null;
+  const number = Number(value);
+  return Number.isFinite(number) ? number : null;
+}
+
+function _verdict(state, previousState, metrics, reason) {
+  return { state, metrics, reason: state === previousState ? null : reason };
+}
+
+// --- wait-watch -------------------------------------------------------------------
+
+/**
+ * D-9 (WP-4b): the watcher spend the window's cell actually accrued. The store reads it from
+ * `model_usage_ledger` and hands it over as ONE object, `{usd, rows}` — or null when the window
+ * names no worker or the ledger matched no row. These are REPORTED metrics: no threshold in this
+ * file reads them (the design's D-9 is a read, never a new rule).
+ */
+function _watcherUsdWindow(watcherUsd) {
+  if (!watcherUsd || typeof watcherUsd !== 'object') return null;
+  if (Number.isFinite(watcherUsd.rows) && watcherUsd.rows <= 0) return null;
+  return typeof watcherUsd.usd === 'number' && Number.isFinite(watcherUsd.usd) ? watcherUsd.usd : null;
+}
+
+function _watchMetrics(outcomes, watcherUsd) {
+  const useful = outcomes.filter((row) => row.label === 'useful').length;
+  const empty = outcomes.filter((row) => row.label === 'empty').length;
+  const late = outcomes.filter((row) => row.label === 'late').length;
+  const silentUseful = outcomes.filter((row) => row.label === 'silent_useful').length;
+  const silentEmpty = outcomes.filter((row) => row.label === 'silent_empty').length;
+  const labelled = useful + empty;
+  const silentLabelled = silentUseful + silentEmpty;
+  const watcherUsdWindow = _watcherUsdWindow(watcherUsd);
+  return {
+    n_window: outcomes.length,
+    labelled,
+    useful,
+    empty,
+    late,
+    precision: _ratio(useful, labelled),
+    silent_labelled: silentLabelled,
+    silent_precision: _ratio(silentUseful, silentLabelled),
+    collecting: labelled < MIN_LABELLED,
+    watcher_usd_window: watcherUsdWindow,
+    // null (not 0) when there is no spend to divide or no useful wake to divide it by -- the panel
+    // must be able to say "not measured" rather than "$0.000 per wake".
+    usd_per_useful_wake: watcherUsdWindow !== null && useful > 0 ? watcherUsdWindow / useful : null,
+  };
+}
+
+function _evaluateWatch(cellState, outcomes, watcherUsd) {
+  const metrics = _watchMetrics(outcomes, watcherUsd);
+  if (cellState === 'on') {
+    if (metrics.labelled >= MIN_LABELLED && metrics.precision < WATCH_OFF_BELOW) {
+      return _verdict('off', cellState, metrics, REASONS.WATCH_PRECISION_BELOW);
+    }
+    return _verdict(cellState, cellState, metrics, null);
+  }
+  if (cellState === 'off') {
+    // While off, the silent ticks are the window: the lead's own next call is the only
+    // evidence left that the wake was not needed.
+    metrics.collecting = metrics.silent_labelled < MIN_LABELLED;
+    if (metrics.silent_labelled >= MIN_LABELLED && metrics.silent_precision >= WATCH_ON_ABOVE) {
+      return _verdict('on', cellState, metrics, REASONS.WATCH_SILENT_PRECISION_ABOVE);
+    }
+    return _verdict(cellState, cellState, metrics, null);
+  }
+  return _verdict(cellState, cellState, metrics, null);
+}
+
+// --- explore ----------------------------------------------------------------------
+
+/** The row's parsed `grade_json` object, or null when it carries nothing readable. */
+function _parseGrade(row) {
+  if (row.grade_json == null || row.grade_json === '') return null;
+  let parsed = row.grade_json;
+  if (typeof parsed === 'string') {
+    try {
+      parsed = JSON.parse(parsed);
+    } catch {
+      // expected: an unparsable grade_json carries no verdict — the row counts as ungraded
+      return null;
+    }
+  }
+  if (!parsed || typeof parsed !== 'object') return null;
+  return parsed;
+}
+
+function _gradeOf(row) {
+  const parsed = _parseGrade(row);
+  if (!parsed || parsed.unavailable === true) return null;
+  return parsed;
+}
+
+/**
+ * D-1/D-7: a closed round-1 row stored no facts (label_version below the current version and
+ * facts_json empty), so its decision is a v1 label that cannot be recomputed -- the very labels
+ * that demoted the live cells. It is kept as evidence but measures nothing. A row without a
+ * label_version key (a bare test fixture) is read as current.
+ */
+function _isFactlessOldRow(row) {
+  if (row.label_version == null || row.decision === 'open') return false;
+  return Number(row.label_version) < LABEL_VERSION && (row.facts_json == null || row.facts_json === '');
+}
+
+/** A handoff/fallback row the window may count as a measurement. */
+function _isClosedRow(row) {
+  return (row.decision === 'handoff' || row.decision === 'fallback') && !_isFactlessOldRow(row);
+}
+
+/** D-7: a row that carries no measurement — an explicit `unmeasured`, a decision the rule never produced, or a factless round-1 label. */
+function _isUnmeasuredRow(row) {
+  return row.decision === 'unmeasured'
+    || (row.decision !== 'open' && !EXPLORE_DECISIONS.includes(row.decision))
+    || _isFactlessOldRow(row);
+}
+
+function _exploreMetrics(outcomes, leadBurstUsd) {
+  const closed = outcomes.filter(_isClosedRow);
+  const handoff = closed.filter((row) => row.decision === 'handoff');
+  const fallback = closed.length - handoff.length;
+  const gradedRows = closed.map((row) => _gradeOf(row)).filter(Boolean);
+  const sufficient = gradedRows.filter((grade) => grade.sufficient === true).length;
+  // D-8: how many of the window's rows carry an unavailable grade — the grader failed, was never
+  // pinned, or never parsed. `_gradeOf` still excludes them from `graded`; this only makes them
+  // visible, and it is a metric, never a threshold.
+  const gradeUnavailable = outcomes.filter((row) => _parseGrade(row)?.unavailable === true).length;
+  const unmeasured = outcomes.filter(_isUnmeasuredRow).length;
+  const abandoned = outcomes.filter((row) => row.decision === 'abandoned').length;
+  const open = outcomes.filter((row) => row.decision === 'open').length;
+  // D-7 (S-14): a verdict needs 10 MEASURED rows and a window that is not mostly no-data. Round 1
+  // read every non-handoff row as a fallback, so an all-unmeasured window ("the status read came
+  // back without a citation count") demoted a healthy cell. `closed` is unchanged — handoff +
+  // fallback only; the guard is on measurability, never on a threshold.
+  const measurable = closed.length >= MIN_LABELLED
+    && (unmeasured + abandoned) <= outcomes.length * UNMEASURED_MAX_SHARE;
+  return {
+    n_window: outcomes.length,
+    closed: closed.length,
+    handoff: handoff.length,
+    fallback,
+    fallback_rate: _ratio(fallback, closed.length),
+    graded: gradedRows.length,
+    grade_unavailable: gradeUnavailable,
+    sufficient_rate: _ratio(sufficient, gradedRows.length),
+    median_helper_usd: _median(handoff.map((row) => _number(row.helper_usd)).filter((value) => value !== null)),
+    median_reread: _median(closed.map((row) => _number(row.reread_rate)).filter((value) => value !== null)),
+    lead_burst_usd: Number.isFinite(Number(leadBurstUsd)) ? Number(leadBurstUsd) : null,
+    unmeasured,
+    abandoned,
+    open,
+    measurable,
+    collecting: !measurable,
+  };
+}
+
+/** The first off-condition the window trips, or null when it trips none. */
+function _exploreFailureReason(metrics, leadBurstUsd) {
+  // D-7: neither an `on → off` demotion nor a failed probe may rest on a window that is mostly
+  // no-data — "unmeasured" is not evidence that the helper failed.
+  if (!metrics.measurable) return null;
+  if (metrics.fallback_rate > EXPLORE_FALLBACK_MAX) return REASONS.EXPLORE_FALLBACK_ABOVE;
+  if (metrics.median_reread !== null && metrics.median_reread > EXPLORE_REREAD_MAX) return REASONS.EXPLORE_REREAD_ABOVE;
+  if (metrics.median_helper_usd !== null && Number.isFinite(leadBurstUsd) && metrics.median_helper_usd >= leadBurstUsd) {
+    return REASONS.EXPLORE_HELPER_USD_AT_OR_ABOVE;
+  }
+  if (metrics.graded >= GRADED_MIN && metrics.sufficient_rate < EXPLORE_SUFFICIENT_MIN) {
+    return REASONS.EXPLORE_SUFFICIENT_BELOW;
+  }
+  return null;
+}
+
+function _evaluateExplore(cell, outcomes, now, leadBurstUsd) {
+  const cellState = _stateOf(cell);
+  const metrics = _exploreMetrics(outcomes, leadBurstUsd);
+
+  if (cellState === 'on') {
+    const reason = _exploreFailureReason(metrics, leadBurstUsd);
+    if (reason) return _verdict('off', cellState, metrics, reason);
+    return _verdict(cellState, cellState, metrics, null);
+  }
+
+  if (cellState === 'off') {
+    // The 7-day probe timer: only the daily tick can move an off cell, and only when the
+    // user has not vetoed it.
+    const changedAt = _toMs(cell.state_changed_at);
+    const nowMs = _toMs(now) ?? Date.now();
+    const days = changedAt == null ? 0 : (nowMs - changedAt) / DAY_MS;
+    if (!_vetoOf(cell) && days >= EXPLORE_PROBE_AFTER_DAYS) {
+      return _verdict('probe', cellState, metrics, REASONS.EXPLORE_PROBE_AFTER);
+    }
+    return _verdict(cellState, cellState, metrics, null);
+  }
+
+  // probe: the next PROBE_N closed rows that landed AFTER the probe started decide it.
+  const changedAt = _toMs(cell.state_changed_at);
+  const probeWindow = outcomes
+    .filter(_isClosedRow)
+    .filter((row) => {
+      const createdMs = _toMs(row.created_at);
+      return changedAt == null || createdMs == null || createdMs >= changedAt;
+    })
+    .slice(0, PROBE_N);
+  metrics.probed = probeWindow.length;
+  if (probeWindow.length < PROBE_N) return _verdict(cellState, cellState, metrics, null);
+  const failed = _exploreFailureReason(_exploreMetrics(probeWindow, leadBurstUsd), leadBurstUsd);
+  if (failed) return _verdict('off', cellState, metrics, REASONS.EXPLORE_PROBE_FAILED);
+  return _verdict('on', cellState, metrics, REASONS.EXPLORE_PROBE_PASSED);
+}
+
+/**
+ * Pure. Decide the next state of one rule cell from its stored state and its trailing
+ * window of outcomes. `reason` is null whenever the state does not change.
+ * @param {{state?:string, user_veto?:number, state_changed_at?:string}} cell
+ * @param {Array<object>} trailingOutcomes most-recent-first window of helper_outcomes rows
+ * @param {{now?: number|string|Date, leadBurstUsd?: number, watcherUsd?: {usd:number, rows:number}|null}} [options]
+ * @returns {{state:'on'|'off'|'probe', metrics:object, reason:string|null}}
+ */
+function evaluateCell(cell, trailingOutcomes, { now, leadBurstUsd, watcherUsd } = {}) {
+  const outcomes = Array.isArray(trailingOutcomes) ? trailingOutcomes : [];
+  const cellState = _stateOf(cell);
+  if (_vetoOf(cell)) {
+    // D-18: a vetoed cell is off, and it can never probe. Reason only when this is news.
+    return { state: 'off', metrics: _kindMetrics(cell, outcomes, leadBurstUsd, now, watcherUsd), reason: cellState === 'off' ? null : REASONS.USER_VETO };
+  }
+  const kind = String(cell?.kind || '').trim();
+  if (kind === 'explore' || String(cell?.cell_key || '').startsWith('explore|')) {
+    return _evaluateExplore(cell, outcomes, now, leadBurstUsd);
+  }
+  return _evaluateWatch(cellState, outcomes, watcherUsd);
+}
+
+/** The metrics a short-circuited (vetoed) cell reports — same shape as its kind's. */
+function _kindMetrics(cell, outcomes, leadBurstUsd, now, watcherUsd) {
+  void now;
+  const kind = String(cell?.kind || '').trim();
+  if (kind === 'explore' || String(cell?.cell_key || '').startsWith('explore|')) {
+    return _exploreMetrics(outcomes, leadBurstUsd);
+  }
+  return _watchMetrics(outcomes, watcherUsd);
+}
+
+module.exports = {
+  CELL_STATES,
+  DAY_MS,
+  EXPLORE_DECISIONS,
+  EXPLORE_DEMOTION_REASONS,
+  EXPLORE_FALLBACK_MAX,
+  EXPLORE_OPEN_TTL_MS,
+  EXPLORE_PROBE_AFTER_DAYS,
+  EXPLORE_REREAD_MAX,
+  EXPLORE_SUFFICIENT_MIN,
+  GRADED_MIN,
+  MIN_LABELLED,
+  PROBE_N,
+  REASONS,
+  UNMEASURED_MAX_SHARE,
+  WATCH_OFF_BELOW,
+  WATCH_ON_ABOVE,
+  WINDOW,
+  evaluateCell,
+};

package/template/wall-e/lib/helper-rules/explore-rubric.md

@@ -0,0 +1,12 @@
+You are a careful grader for an evaluation. A lead coding agent explored a codebase with several read-only steps, then made a decision. Separately, a helper model was given a short brief describing the same question and explored the same code on its own, then wrote a report. Your job: judge whether the helper's report would have served the lead as well as its own exploration did.
+
+The card has: the brief given to the helper, the helper's report, and the list of tools and paths the helper touched.
+
+Judge:
+- coverage: did the report contain the facts the brief's "Stop when" condition needs? "all" | "most" | "little"
+- inaccuracies: how many claims in the report are wrong or unsupported by a file:line the report cites? an integer
+- sufficient: could the lead make its next decision from the report alone, without re-reading the files? true | false
+- why: <= 40 words, concrete (name the missing or wrong fact if any).
+Judge only facts the report itself supports with file:line; if the report marks something INFERENCE, do not count it as wrong. A "not found" row is valid when the brief's question has no answer in the code.
+
+Answer with one JSON object only: {"sufficient": true|false, "coverage": "all"|"most"|"little", "inaccuracies": <integer>, "why": "<= 40 words"}