create-walle 0.10.1 → 0.10.2

package/template/wall-e/llm/portkey-sync.js

@@ -13,13 +13,12 @@ const {
   portkeyKeyFingerprint,
 } = require('./portkey');
 const { scaleDecimal, canonicalRateNumber } = require('../../shared/usage-pricing');
-const { redactSecrets } = require('./provider-error');
 const { findSupportedModel } = require('./supported-models');
 const { isDecideOnlyModel } = require('./decide-only');
 const { generateRouteGroups } = require('./route-groups');
 const { scheduleRebuild } = require('./model-identity');
 const { notifyModelRegistryChanged } = require('../lib/ctm-model-registry-notify');
-const { createRetryPolicy } = require('../lib/kernel/retry-policy');
+const { fetchJsonOrError, safeJson, _setRetrySleepForTest } = require('./portkey-http');
 
 const PORTKEY_SYNC_INTERVAL_MS = 60 * 60 * 1000;
 const PORTKEY_SYNC_INITIAL_DELAY_MS = 15 * 1000;
@@ -28,10 +27,6 @@ const PORTKEY_CONTROL_PLANE_URL = 'https://api.portkey.ai/v1';
 const PORTKEY_PRICING_BASE_URL = 'https://configs.portkey.ai/pricing';
 const PORTKEY_DISCOVERY_PAGE_SIZE = 50;
 const PORTKEY_CATALOG_PAGE_SIZE = 500;
-// D-2: TOTAL attempts for a transient failure, with the backoff between them.
-const PORTKEY_REQUEST_ATTEMPTS = 3;
-const PORTKEY_RETRY_DELAYS_MS = [1000, 3000];
-const PORTKEY_RETRY_AFTER_MAX_MS = 30 * 1000;
 
 // D-9: vendor names Wall-E has a dedicated LLM adapter for. A discovered
 // provider whose vendor slug does not resolve to one of these keeps its own
@@ -96,141 +91,6 @@ function inferGatewayCapabilities(providerType, model = {}) {
   return supported?.capabilities || (isDecideOnlyModel({ providerType, modelId: id }) ? ['decide'] : ['chat']);
 }
 
-// WP-1 review R6: this is the ONLY request budget in the Portkey path, and it
-// is per REQUEST, not per host — callers that must bound a whole host (the
-// resolver) also cap the number of pages. There is deliberately no
-// AbortController+setTimeout fallback when `AbortSignal.timeout` is missing:
-// that would be a recovery timer, which `stabilization-lint` requires to be
-// registered in release/ownership-registry.json and which this feature's
-// design forbids. `AbortSignal.timeout` is Node >= 17.3 and this repo pins
-// v25.2.1, so the fallback branch below is unreachable in practice; if it is
-// ever reached the request is unbounded and the caller's page cap is what
-// stops it.
-function withTimeout(timeoutMs) {
-  if (typeof AbortSignal !== 'undefined' && AbortSignal.timeout && Number.isFinite(timeoutMs)) {
-    return { signal: AbortSignal.timeout(timeoutMs) };
-  }
-  return {};
-}
-
-async function safeJson(response) {
-  try { return await response.json(); } catch { return null; /* expected: non-JSON or empty error body; callers fall back to a generic message */ }
-}
-
-// D-2 test seam: when set, createRetryPolicy uses it instead of the kernel's
-// own registered timer. null (default) means "use the kernel sleep".
-let _retrySleepOverride = null;
-
-function _setRetrySleepForTest(fn) {
-  _retrySleepOverride = typeof fn === 'function' ? fn : null;
-}
-
-// D-1: TRANSIENT iff no response at all (status 0) or 408/429/5xx; every other
-// status (3xx/401/403/AB03/033/other 4xx) is DEFINITIVE and never retried.
-function isTransientStatus(status) {
-  if (status === 0) return true;
-  const code = Number(status);
-  return code === 408 || code === 429 || (code >= 500 && code <= 599);
-}
-
-// D-2: honour Retry-After only as integer seconds ≤ 30 s; else fixed backoff.
-function retryAfterMs(response) {
-  if (!response || typeof response.headers?.get !== 'function') return null;
-  const raw = response.headers.get('retry-after');
-  if (raw == null) return null;
-  const seconds = Number(String(raw).trim());
-  if (!Number.isFinite(seconds) || seconds < 0) return null;
-  const ms = seconds * 1000;
-  return ms <= PORTKEY_RETRY_AFTER_MAX_MS ? ms : null;
-}
-
-function errorCodeFromBody(body) {
-  if (!body || typeof body !== 'object') return '';
-  if (body.data && body.data.errorCode) return String(body.data.errorCode);
-  if (body.error && body.error.code) return String(body.error.code);
-  return '';
-}
-
-function errorMessageFromBody(body, fallback) {
-  if (body && typeof body === 'object') {
-    if (body.data && body.data.message) return String(body.data.message);
-    if (body.message) return String(body.message);
-  }
-  return fallback;
-}
-
-// `redirect: 'manual'` is the DEFAULT here, for EVERY request in the Portkey
-// path — not only the resolver's probe (final review, finding #3). Every one
-// carries the full gateway key in `x-portkey-api-key`, and undici keeps that
-// header across a cross-origin redirect, so following a 3xx would hand the key
-// to a host the user never named (the axios GHSA-jr5f-v2jv-69x6 class). With
-// `manual` a 3xx is not followed and `response.ok` is false, so it surfaces as
-// `{ok:false, status:3xx}` — a verdict, never a second request.
-// `fetchInit` (WP-1): extra init the CALLER owns — today the resolver's
-// per-host AbortController signal. Spread last so it replaces withTimeout's.
-// D-2: ONE attempt; returns today's ok/failure shape plus the response's
-// Retry-After (null when the fetch threw — a transport failure has no headers).
-async function fetchJsonOnce(fetchFn, url, { headers, timeoutMs, fallbackMessage, fetchInit } = {}) {
-  try {
-    const response = await fetchFn(url, { headers, redirect: 'manual', ...withTimeout(timeoutMs), ...(fetchInit || {}) });
-    const body = await safeJson(response);
-    if (response.ok) return { result: { ok: true, status: response.status, body }, retryAfter: null };
-    return {
-      result: {
-        ok: false,
-        status: response.status,
-        code: errorCodeFromBody(body),
-        message: redactSecrets(errorMessageFromBody(body, fallbackMessage(response.status))),
-      },
-      retryAfter: retryAfterMs(response),
-    };
-  } catch (err) {
-    // D-1: no HTTP response at all (status 0 — transport/timeout) is transient.
-    const message = err && err.message ? err.message : String(err);
-    return { result: { ok: false, status: 0, code: '', message: redactSecrets(message) }, retryAfter: null };
-  }
-}
-
-// D-2: transient failures are retried through wall-e's ONE retry engine
-// (lib/kernel/retry-policy.js); a caller owning its own abort signal (the
-// resolver's single probe) is single-shot and never retries.
-async function fetchJsonOrError(fetchFn, url, opts = {}) {
-  if (opts.fetchInit) {
-    const { result } = await fetchJsonOnce(fetchFn, url, opts);
-    if (result.ok) return result;
-    const transient = isTransientStatus(result.status);
-    return transient ? { ...result, transient, attempts: 1 } : { ...result, transient };
-  }
-  let nextDelay = null;
-  let lastAttempt = 1;
-  const policyOptions = {
-    maxAttempts: PORTKEY_REQUEST_ATTEMPTS,
-    jitter: 0,
-    delayFn: (attempt) => nextDelay ?? PORTKEY_RETRY_DELAYS_MS[attempt - 1],
-    classify: (err) => (err && err.portkeyTransient ? 'transient' : 'permanent'),
-    layer: 'portkey-sync',
-    operation: 'fetch',
-  };
-  // Only override the kernel's own registered timer when a test seam is set.
-  if (_retrySleepOverride) policyOptions.sleep = (ms) => _retrySleepOverride(ms);
-  const policy = createRetryPolicy(policyOptions);
-  try {
-    return await policy.run(async (attempt) => {
-      const { result, retryAfter } = await fetchJsonOnce(fetchFn, url, opts);
-      if (result.ok || !isTransientStatus(result.status)) {
-        return result.ok ? result : { ...result, transient: false };
-      }
-      nextDelay = retryAfter;
-      lastAttempt = attempt;
-      throw Object.assign(new Error(result.message), { portkeyTransient: true, result });
-    });
-  } catch (err) {
-    // Only our transient sentinel is converted; anything else propagates.
-    if (!err || !err.portkeyTransient) throw err;
-    return { ...err.result, transient: true, attempts: lastAttempt };
-  }
-}
-
 // D-3: per-integration data-plane listing, scoped by the '@slug' header —
 // never a virtual key.
 async function listPortkeyModelsForIntegration({ baseUrl, apiKey, slug, fetchFn = fetch, timeoutMs = 8000 }) {
@@ -308,6 +168,7 @@ async function listPortkeyCatalogModels({
   let total = Infinity;
   let seen = 0;
   let pages = 0;
+  let last = {}; // WP-0: last page's HTTP status + raw body.total ride along as evidence for catalog_empty
   while (seen < total && pages < maxPages) {
     const url = `${root}/models?offset=${offset}&limit=${pageSize}`;
     const result = await fetchJsonOrError(fetchFn, url, {
@@ -319,6 +180,7 @@ async function listPortkeyCatalogModels({
     if (!result.ok) return result;
     const data = Array.isArray(result.body?.data) ? result.body.data : [];
     total = Number.isFinite(result.body?.total) ? result.body.total : data.length;
+    last = { status: typeof result.status === 'number' ? result.status : null, total: Number.isFinite(result.body?.total) ? result.body.total : null };
     for (const model of data) {
       const id = String(model.id || '').trim();
       const match = id.match(/^@([^/]+)\/(.+)$/);
@@ -332,7 +194,7 @@ async function listPortkeyCatalogModels({
     if (!data.length) break;
     offset += pageSize;
   }
-  return { ok: true, bySlug };
+  return { ok: true, bySlug, status: last.status ?? null, total: last.total ?? null };
 }
 
 function extractPortkeyPricing(modelConfig = {}) {
@@ -474,9 +336,10 @@ function upsertIntegrationRow(brain, gateway, provider, rows, now) {
   return { rowId, slug, type: vendorType, enabled };
 }
 
-// D-4: an `ok` listing (catalog or passthrough, empty or not) is authoritative —
-// it refreshes rows and disables omitted ones ('manual' rows excepted). A
-// transient failure never reaches here (it is reported, D-3).
+// D-4/D-6: a NON-EMPTY `ok` listing (catalog or passthrough) is authoritative —
+// it refreshes rows and disables omitted ones ('manual' rows excepted). An empty
+// `ok` listing for an integration with ≥1 enabled row never reaches here: it is
+// reported as `catalog_empty` (D-6, 2026-10-22 incident). Transient failures too (D-3).
 function upsertLiveModels(brain, rowInfo, models, verificationStatus, now) {
   const seenIds = new Set();
   let imported = 0;
@@ -520,6 +383,13 @@ async function syncModelsForIntegration(brain, gateway, rowInfo, catalog, { fetc
 
   if (catalog.ok) {
     models = catalog.bySlug.get(rowInfo.slug) || [];
+    // D-6 (WP-0): a zero-model ok listing never disables rows enabled now (the control plane timed
+    // out while the catalog still answered 200, 2026-10-22) — report it via the error branch below.
+    const enabledNow = models.length ? 0 : (brain.listModelsByProvider?.(rowInfo.rowId) || []).length;
+    if (enabledNow > 0) {
+      console.warn(`[portkey-sync] catalog_empty slug=${rowInfo.slug} row=${rowInfo.rowId} enabled=${enabledNow} status=${catalog.status ?? 200} total=${catalog.total ?? 'n/a'} data=0`);
+      listError = { ok: false, status: catalog.status ?? 200, code: 'catalog_empty', message: `Portkey catalog listed 0 models for ${rowInfo.slug} while ${enabledNow} are enabled; rows kept` };
+    }
   } else if (catalog.transient) {
     // D-3: a transient catalog failure says nothing about this integration's
     // models — report and change NOTHING (never swap in a passthrough listing;

package/template/wall-e/llm/worker-mcp-routing.js

@@ -268,6 +268,63 @@ function callerDoorBearerOk(req) {
   return require('../http/auth').requireBearer(req, strFlag('WALL_E_API_TOKEN', ''));
 }
 
+// WP-5b (lead-cost routing §6.2/§6.7): the rule cell decides whether a wait parks the watcher.
+// 'off' is a user veto (D-18: final, and silent ticks cannot move it), 'silent' is an off cell
+// still collecting 1-in-10 ticks (D-16), and CTM's default 'on' is returned as null so an
+// unchanged request keeps its exact shape (`watch=` is omitted entirely). A route wait starts
+// no watcher (WP-1), and a wait whose worker has no recorded route has no cell to read.
+const WATCH_ORDER = Object.freeze({ off: 0, silent: 1, on: 2 });
+const WATCH_OFF_CELL = 'off';
+
+function _helperRulesDb() {
+  try {
+    // lib/brain-events is the one legal way to the db handle from llm/ (dependency-rules.json).
+    return require('../lib/brain-events').getDb();
+  } catch {
+    // expected: the brain is not initialized (a bare unit call) -- a missing handle reads 'on'
+    return null;
+  }
+}
+
+function _watchModeOfRoute(route, db) {
+  const { readCell, readCellState } = require('../lib/helper-rules/store');
+  const cellKey = `wait-watch|default|${route}`;
+  const row = readCell(db, cellKey);
+  if (row && Number(row.user_veto) === 1) return 'off';
+  return readCellState(db, cellKey) === WATCH_OFF_CELL ? 'silent' : 'on';
+}
+
+/**
+ * The `watch` mode one wait request carries, or null to omit the parameter (CTM's default
+ * 'on'). `hook` is lib/helper-rules/lead-call-hook.js and `db` the brain handle — both
+ * injectable so a test can drive the cell state directly.
+ */
+function watchModeFor(args = {}, hook = require('../lib/helper-rules/lead-call-hook'), db = _helperRulesDb()) {
+  const routes = new Set();
+  if (args.route) return null; // a route wait starts no watcher (WP-1)
+  try {
+    if (args.ctm_session_id) {
+      const entry = hook.workerRouteOf(args.ctm_session_id);
+      if (!entry || !entry.route) return null; // unknown -> 'on'
+      routes.add(entry.route);
+    } else {
+      for (const worker of hook.leadWorkersOf(args.parent_agent_session_id) || []) {
+        if (worker && worker.route) routes.add(worker.route);
+      }
+      if (!routes.size) return null; // nothing recorded -> 'on'
+    }
+  } catch {
+    // expected: the hook cannot answer -- 'on' is the fail-open default, never a failed wait
+    return null;
+  }
+  let mode = 'on';
+  for (const route of routes) {
+    const next = _watchModeOfRoute(route, db);
+    if (WATCH_ORDER[next] < WATCH_ORDER[mode]) mode = next; // the most restrictive route wins
+  }
+  return mode === 'on' ? null : mode;
+}
+
 // WP-5 (lead-aware wait, D-12, §6.5 E): one place decides which CTM call a worker
 // status/wait tool makes and caps any report text it carries. It lives here, outside
 // mcp-server.js's frozen ceiling: a named worker reads/waits on that worker alone with the
@@ -281,15 +338,19 @@ async function resolveWorkerWaitResult(ctmContextClient, toolName, args, reportT
   if (isWait && args.route && args.ctm_session_id) {
     return { error: 'wait_args_conflict', detail: 'ctm_session_id and route are mutually exclusive' };
   }
+  // WP-5b: the watcher mode rides the WAIT request only (a plain status read starts none).
+  const watch = isWait ? watchModeFor(args) : null;
   if (args.ctm_session_id) {
     result = await ctmContextClient.workerStatus(args.ctm_session_id, {
       timeoutMs: args.timeout_ms || 30000, includeReport: true, waitMs,
       leadAgentSessionId: isWait ? args.parent_agent_session_id : undefined,
+      ...(watch ? { watch } : {}),
     });
   } else if (isWait) {
     result = await ctmContextClient.waitForWorkers({
       leadAgentSessionId: args.parent_agent_session_id, waitMs, timeoutMs: args.timeout_ms || 30000,
       ...(args.route ? { route: String(args.route) } : {}),
+      ...(watch ? { watch } : {}),
     });
   } else {
     result = await ctmContextClient.workerStatus(args.ctm_session_id, { timeoutMs: args.timeout_ms || 30000, includeReport: true });

package/template/wall-e/llm/worker-route.js

@@ -12,7 +12,7 @@
 // gateway can sit behind any hostname).
 
 const { parseCustomHeaders, isPortkeyRouteRow, portkeyRequestHeaders } = require('./portkey');
-const { providerReasoningParams } = require('../../shared/reasoning-control');
+const { providerReasoningParams, resolveReasoningControl } = require('../../shared/reasoning-control');
 const { validateModelDeployments, canonicalJson } = require('../../shared/coding-model-deployment');
 const crypto = require('node:crypto');
 
@@ -165,6 +165,45 @@ function routeReasoningLevelsForRow(row) {
   return routeReasoningLevels(reasoningParamsForRoute(normalizeRowType(row), upstreamApisForRow(row).upstream_apis));
 }
 
+/** The Claude Code --effort vocabulary (code.claude.com/docs/en/model-config). Frozen; display order. */
+const CLAUDE_CLI_EFFORT_LEVELS = Object.freeze(['low', 'medium', 'high', 'xhigh', 'max']);
+
+/**
+ * D-1: the CLI effort levels a (route, wire model) pair can carry.
+ *  - upstream_apis includes 'anthropic-messages' -> CLAUDE_CLI_EFFORT_LEVELS
+ *    filtered to the Claude matrix for `model_id`
+ *    (resolveReasoningControl({ providerType: 'anthropic', modelId }).values;
+ *    a 'fixed' control, or an unparseable id, yields []).
+ *    A passthrough anthropic-messages route relays the Claude CLI's own
+ *    `output_config.effort` verbatim, so the CLI vocabulary -- not the
+ *    chat-translate fragment map, which is empty for this wire shape -- is
+ *    the truth here.
+ *  - otherwise -> routeReasoningLevels(reasoningParamsForRoute(type,
+ *    upstream_apis)) unchanged (D-4): the chat-translate fragment producer
+ *    still decides for every other upstream API.
+ * Always returns a NEW array; never null; never throws on garbage input.
+ * @param {{ type?: string, upstream_apis?: string[], model_id?: string }} [args]
+ * @returns {string[]}
+ */
+function routeModelReasoningLevels(args) {
+  // Tolerate a null/undefined/garbage argument container: callers project rows
+  // from the brain and a malformed row must read as "no levels", never throw.
+  const { type = '', upstream_apis = [], model_id = '' } = (args && typeof args === 'object' && !Array.isArray(args)) ? args : {};
+  const apis = Array.isArray(upstream_apis) ? upstream_apis : [];
+  if (apis.indexOf(ANTHROPIC_MESSAGES_API) !== -1) {
+    const control = resolveReasoningControl({ providerType: 'anthropic', modelId: model_id });
+    const allowed = new Set((Array.isArray(control?.values) ? control.values : []).map((option) => option?.value));
+    return CLAUDE_CLI_EFFORT_LEVELS.filter((level) => allowed.has(level));
+  }
+  return routeReasoningLevels(reasoningParamsForRoute(String(type || '').toLowerCase(), apis));
+}
+
+/** Row convenience, mirrors routeReasoningLevelsForRow. */
+function routeModelReasoningLevelsForRow(row, modelId) {
+  const { upstream_apis } = upstreamApisForRow(row);
+  return routeModelReasoningLevels({ type: normalizeRowType(row), upstream_apis, model_id: modelId });
+}
+
 function publicWorkerCapability(row) {
   const capabilities = row.capabilities || JSON.parse(row.capabilities_json || '{}');
   const expired = row.state === 'unknown';
@@ -312,4 +351,7 @@ module.exports = {
   reasoningParamsForRoute,
   routeReasoningLevels,
   routeReasoningLevelsForRow,
+  CLAUDE_CLI_EFFORT_LEVELS,
+  routeModelReasoningLevels,
+  routeModelReasoningLevelsForRow,
 };

package/template/wall-e/loops/brain-custom-writes.js

@@ -594,6 +594,44 @@ function finishConversationBootstrap({ state, batchLimit = 500 } = {}) {
   }).immediate();
 }
 
+// Lead-cost routing WP-5a (design §6.6/§6.8, contract §2): the helper-rules record's four
+// writes. lib/helper-rules/store.js owns the SQL and takes the handle; these wrappers are
+// what brainWrite resolves — same function on the direct (RW) path and on the owner-routed
+// path (workers/brain-owner-worker.js's CUSTOM_BRAIN_CALLS). WP-6 adds the fifth
+// (helperRulesSetGrade): the spot-check grader's verdict on one explore row; round 2 WP-2 adds
+// the two below it (D-5's close-by-worker and D-5/D-6's relabel).
+function helperRulesRecordOutcome(outcome) {
+  return require('../lib/helper-rules/store').recordOutcome(brain.getDb(), outcome);
+}
+
+function helperRulesCloseOutcome(id, patch) {
+  return require('../lib/helper-rules/store').closeOutcome(brain.getDb(), id, patch);
+}
+
+// Round 2 WP-2 (§6.4 S-16): D-5's close path is keyed on the row's worker_id, so a Wall-E
+// restart, an evicted in-memory map or a second process cannot orphan an open row.
+function helperRulesCloseOutcomeByWorker(workerId, patch) {
+  return require('../lib/helper-rules/store').closeOutcomeByWorker(brain.getDb(), workerId, patch);
+}
+
+// Round 2 WP-2 (§6.4 S-16): the one-time relabel + D-6 recovery pass (idempotent — the second
+// run changes nothing). The daily tick calls it too.
+function helperRulesRelabel(options) {
+  return require('../lib/helper-rules/store').relabel(brain.getDb(), options);
+}
+
+function helperRulesSetCellState(cellKey, options) {
+  return require('../lib/helper-rules/store').setCellState(brain.getDb(), cellKey, options);
+}
+
+function helperRulesDailyTick() {
+  return require('../lib/helper-rules/store').dailyTick(brain.getDb());
+}
+
+function helperRulesSetGrade(id, gradeJson) {
+  return require('../lib/helper-rules/store').setGrade(brain.getDb(), id, gradeJson);
+}
+
 module.exports = {
   failConversationExtraction,
   markMemoriesExtractionSkipped,
@@ -620,4 +658,11 @@ module.exports = {
   ingestUpdateMemoryContent,
   runDbOptimizeMigration,
   recordProviderHealthStatus,
+  helperRulesRecordOutcome,
+  helperRulesCloseOutcome,
+  helperRulesSetCellState,
+  helperRulesDailyTick,
+  helperRulesSetGrade,
+  helperRulesCloseOutcomeByWorker,
+  helperRulesRelabel,
 };

package/template/wall-e/mcp-protocol-contract.js

@@ -28,12 +28,47 @@ const SERVER_INSTRUCTIONS = [
   '`worker_started` already launched a separate worker: wait on it and review its report -- a process start is never task completion.',
   "Keep the lead's own model and account.",
   'Read-only census and review work can be delegated the same way with `worker_profile: "review"`: the worker cannot edit files, and you keep the verdict.',
+  'Wait on workers with walle_worker_wait and omit wait_ms; it wakes on a finished, failed, resumed or stuck worker, on a question, and when your user types -- never sleep-and-check or wrap it in a short-yield script.',
   '',
   'This guidance is advice, not enforcement: it never authorizes spawning extra agents on your own initiative, and Wall-E cannot intercept or reroute native `spawn_agent` calls you make without it.',
   '',
   "Use Wall-E memory before public web search or guesswork for private, remembered, or work-context questions: prior sessions, decisions, preferences, people, projects, documents, and the user's own style. `walle_context_hint` gives cheap preflight routing, `walle_lookup_context` one-shot private context, `walle_route_query` a routing verdict when unsure, and `walle_memory_status` connection health. In Codex, prefer `CODEX_THREAD_ID` over `CTM_SESSION_ID` for current-session lookups.",
 ].join('\n');
 
+// WP-4 (lead-cost-routing-round1-2026-10-21.html §6.4 "Lead: exploration hand-off"): the block a
+// lead harness receives ONLY while its `explore` rule cell is 'on' or 'probe' (lib/helper-rules/
+// cell-state.js reads it; WP-5 owns the cell's storage and the switch). It is appended to
+// SERVER_INSTRUCTIONS, never merged into it, so SERVER_INSTRUCTIONS stays the stable text every
+// brain serves and the first 512 characters never move.
+//
+// Like the routing guidance above, this is ADVICE: the lead keeps the verdict, a review worker
+// cannot edit files, and nothing here authorizes delegation the user did not ask for.
+const EXPLORE_GUIDANCE = [
+  '## Lead: exploration hand-off',
+  '- If the question you are answering will take more than two reads and is not the exact lines you are about to edit,',
+  '  hand it off before the third read. Write the brief FIRST, then call',
+  '  walle_delegate_implementation({ brief_path, cwd, agent, worker_profile: "review" }) with no model or route.',
+  '  If the result is resolved_native, run your own read-only sub-agent with the same brief instead.',
+  '  Brief (four fields, nothing else):',
+  '    Question: <one sentence>',
+  '    Known so far: <facts you already have, with file:line>',
+  '    Start from: <paths you already know matter>            (optional)',
+  '    Stop when: <the condition that answers the question>',
+  '  Expected report (<= 600 words): a table of file:line + a <=5-line quote per row; INFERENCE marks; a "not found" row is valid.',
+  '- Check the report before using it: at least one file:line row and the Stop-when condition addressed. If not, or the',
+  '  worker failed, read it yourself once. Never hand the same question off twice.',
+  "- Trust the report's file:line facts; re-read only the lines you will change.",
+].join('\n');
+
+// The one builder both transports call with the state their reader resolved; 'off' (and anything
+// unrecognized) serves SERVER_INSTRUCTIONS byte-for-byte, so the guidance is switchable per lead
+// harness without a restart and without a second copy of the text.
+function buildServerInstructions({ explore = 'on' } = {}) {
+  return (explore === 'on' || explore === 'probe')
+    ? `${SERVER_INSTRUCTIONS}\n\n${EXPLORE_GUIDANCE}`
+    : SERVER_INSTRUCTIONS;
+}
+
 // WP-2 correction (lead review): the managed agent-instruction block is the SECOND surface of the
 // same shared guidance, so its owner lives here too -- one pure builder owning the full text, with
 // no I/O, no filesystem and no dependencies (the two host-derived values arrive as arguments).
@@ -123,7 +158,10 @@ function handleProtocolMessage(message, options = {}) {
           serverInfo: SERVER_INFO,
           // WP-2: shared guidance every transport serves verbatim (MCP initialize result
           // instructions) -- never a per-transport variant, so stdio and HTTP cannot drift.
-          instructions: SERVER_INSTRUCTIONS,
+          // WP-4: the lead harness's exploration hand-off block rides on top ONLY when the
+          // transport resolved its `explore` cell (options.leadGuidance); with no option the
+          // reply is SERVER_INSTRUCTIONS, exactly as before this rule existed.
+          instructions: options.leadGuidance ? buildServerInstructions(options.leadGuidance) : SERVER_INSTRUCTIONS,
         }),
       },
     };
@@ -142,11 +180,13 @@ function handleProtocolMessage(message, options = {}) {
 
 module.exports = {
   CAPABILITIES,
+  EXPLORE_GUIDANCE,
   PROTOCOL_VERSION,
   SERVER_INFO,
   SERVER_INSTRUCTIONS,
   SUPPORTED_PROTOCOL_VERSIONS,
   buildManagedAgentInstructions,
+  buildServerInstructions,
   handleProtocolMessage,
   mcpError,
   mcpResponse,

package/template/wall-e/mcp-server.js

@@ -3,6 +3,8 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { randomUUID: uuidv4 } = require('node:crypto');
 const brain = require('./brain');
+const { leadGuidanceForMessage } = require('./lib/helper-rules/cell-state');
+const { recordLeadToolCall } = require('./lib/helper-rules/lead-call-hook'); // WP-5b §6.7: one-line lead-tool hook (S-11/S-13)
 const { brainWrite } = require('./loops/brain-write');
 const { normalizeKnowledgeCategory } = require('./brain/knowledge-categories');
 const ctmSessionContext = require('./memory/ctm-session-context');
@@ -848,15 +850,22 @@ async function executeTool(name, args = {}, context = {}) {
       // high-confidence or non-identity match, matching the test plan's
       // "delegate with a 1.0 row never calls it" case.
       if (typeof identityVerified === 'boolean') result.identity_verified = identityVerified;
+      recordLeadToolCall({ agentSessionId: args.parent_agent_session_id, tool: name, args, result, at: Date.now() });
       return result;
     }
     case 'walle_worker_status': case 'walle_worker_wait': {
       // WP-5 (D-12): the branching (named worker vs whole-set wait vs the no-identity
       // 400 result) and the report-text cap live in worker-mcp-routing.js's
       // resolveWorkerWaitResult -- mcp-server.js is at its frozen line ceiling.
-      return resolveWorkerWaitResult(ctmContextClient, name, args, WORKER_STATUS_REPORT_TEXT_CAP_BYTES);
+      const result = await resolveWorkerWaitResult(ctmContextClient, name, args, WORKER_STATUS_REPORT_TEXT_CAP_BYTES);
+      recordLeadToolCall({ agentSessionId: args.parent_agent_session_id, tool: name, args, result, at: Date.now() });
+      return result;
+    }
+    case 'walle_stop_worker': {
+      const result = await resolveWorkerStopResult(ctmContextClient, args);
+      recordLeadToolCall({ agentSessionId: args.parent_agent_session_id, tool: name, args, result, at: Date.now() });
+      return result;
     }
-    case 'walle_stop_worker': return resolveWorkerStopResult(ctmContextClient, args);
     case 'walle_resume_worker': {
       const result = await ctmContextClient.resumeWorker(args.ctm_session_id, args.message, {
         timeoutMs: args.timeout_ms || 30000, clientMessageId: args.client_message_id,
@@ -866,6 +875,7 @@ async function executeTool(name, args = {}, context = {}) {
         // (worker-continuation.js) -- undefined leaves the key out, as parentAgentSessionId does.
         callerToolUseId: args.caller_tool_use_id,
       });
+      recordLeadToolCall({ agentSessionId: args.parent_agent_session_id, tool: name, args, result, at: Date.now() });
       return projectWorkerResumeResult(result, { ctmSessionId: args.ctm_session_id });
     }
     case 'walle_list_sources': {
@@ -2734,6 +2744,7 @@ async function handleMcpMessage(msg, context = {}) {
     // that do not need a response. Stdio keeps this false and proxies future
     // notification methods here instead of silently swallowing them.
     acceptAnyNotification: true,
+    leadGuidance: leadGuidanceForMessage(msg, brain), // WP-4 §6.4: gates the exploration hand-off block
   });
   if (control.handled) return control.result;
 

package/template/wall-e/mcp-worker-schemas.js

@@ -342,6 +342,15 @@ const WORKER_STATUS_OUTPUT_SCHEMA = {
     // §6.4): which source report_text came from: report, last_message, or a successful
     // final provider result (status stays exited and report_present stays false).
     report_source: { type: ['string', 'null'], enum: ['report', 'last_message', 'final_result', null] },
+    // lead-cost routing round 2 D-3: the distinct `file:line` citation count of the text
+    // report_source names -- null on a non-terminal status, never gated by include_report.
+    report_citation_rows: { type: ['integer', 'null'], minimum: 0 },
+    // lead-cost routing round 2 D-3: the character count of that same text (after the 64 KiB
+    // byte cap), null on a non-terminal status.
+    report_chars: { type: ['integer', 'null'], minimum: 0 },
+    // lead-cost routing round 2 D-3: present only when the report/last-message read threw --
+    // the error code (or 'read_failed'), with both counts at 0.
+    report_read_error: { type: 'string' },
     last_message_path: { type: 'string' },
     retention: WORKER_RETENTION_SCHEMA, poll_after_ms: { type: 'integer', minimum: 0 }, execution_profile: { type: 'object' }, // M-7 retention; WP-7 D-8 poll hint
     // Worker budget ledger (WP-3, delegate-codex-lessons §5 D-2/D-6): task-scoped provider
@@ -422,7 +431,16 @@ const WORKER_WAIT_OUTPUT_SCHEMA = {
   properties: {
     ...WORKER_STATUS_OUTPUT_SCHEMA.properties,
     waited_ms: { type: 'integer', minimum: 0 },
-    woke_on: { type: 'string', enum: ['terminal', 'generation', 'advisory', 'timeout', 'user_input', 'route_clear'] },
+    // WP-1 (D-3/D-4): 'watcher' = the parked wait's watcher saw the worker stuck, looping or
+    // asking a question; 'watcher_unavailable' = it failed twice in a row and the lead is back
+    // to plain-code wakes.
+    woke_on: { type: 'string', enum: ['terminal', 'generation', 'advisory', 'timeout', 'user_input', 'route_clear', 'watcher', 'watcher_unavailable'] },
+    watcher_reason: { type: ['string', 'null'] },
+    watcher_decisions: { type: 'array', items: { type: 'object', additionalProperties: true } },
+    // WP-2 (session-stops-mid-job-2026-10-24.html §6 D-9): non-null while a worker this wait
+    // covered is still live -- it names that worker and says to call walle_worker_wait again
+    // (or walle_stop_worker); null once every worker of the wait is terminal.
+    lead_next_step: { type: ['string', 'null'] },
     route: { type: 'string' },
     admission: { type: ['object', 'null'], additionalProperties: true },
     worker: { type: 'object', additionalProperties: true },
@@ -435,7 +453,7 @@ const WORKER_WAIT_OUTPUT_SCHEMA = {
 
 const WORKER_WAIT_TOOL = {
   name: 'walle_worker_wait',
-  description: 'Block until a delegated worker reaches a terminal state or starts a new generation, or until wait_ms elapses (or, with route, until that route hold ends); returns the walle_worker_status payload plus woke_on. Use this instead of sleep loops or polling the report file.',
+  description: 'Block until a delegated worker reaches a terminal state or starts a new generation, or until wait_ms elapses (or, with route, until that route hold ends); returns the walle_worker_status payload plus woke_on. Use this instead of sleep loops or polling the report file, or when a watcher sees the worker stuck, looping or asking a question, or when your user types.',
   inputSchema: {
     type: 'object',
     properties: {