jeo-code 0.8.23 → 0.8.24

package/src/agent/task-tool.ts

@@ -9,7 +9,7 @@
  * repo). Subagents are spawned with `subagentToolset(role)`, which never includes
  * `task` itself, so delegation cannot recurse infinitely.
  */
-import { runAgentLoop, type ToolHandler } from "./engine";
+import { runAgentLoop, isSafetyFallbackBail, stripSafetyFallbackTag, type ToolHandler } from "./engine";
 import { toolTarget } from "./step-budget";
 
 import type { ToolResult } from "./tools";
@@ -30,7 +30,7 @@ import {
   validateSubagentDoneReason,
   type SubagentRole,
 } from "./subagents";
-import { resolveMaxOutputTokens } from "../ai/model-manager";
+import { resolveMaxOutputTokens, resolveProvider } from "../ai/model-manager";
 import type { SubagentRegistry } from "./subagent-registry";
 import { ensureSessionNotifyEndpoint, type SessionNotifyEndpoint } from "./notify/session-endpoint";
 import { inferTierForModel, tierModelPool, credentialScopeFor, selectFromPool, strongestMidTierCredentialed, type RoutingConfig } from "./prompt-router";
@@ -107,7 +107,7 @@ export interface TaskToolOptions {
  *  disjoint files (documented in `taskToolProtocolLine`); overlapping scopes
  *  should either run sequentially (separate `task` calls) or coordinate — jeo has
  *  no in-batch peer channel yet, so overlapping-scope tasks MUST be sequential. */
-const MAX_FANOUT = 4;
+export const MAX_FANOUT = 4;
 
 /** Small bounded reroute budget for a SUBAGENT's own 429 (distinct from
  *  launch.ts's `ROUTE_FALLBACK_MAX_ATTEMPTS`, default 3): a subagent is already
@@ -263,6 +263,14 @@ export interface SubagentRunResult extends ToolResult {
   fileMutations: number;
   /** Successful bash calls observed (tracked apart — bash CAN mutate but isn't proof). */
   bashRuns: number;
+  /** Successful read/search/find/ast_grep/lsp calls observed — evidence a
+   *  READ-ONLY role (architect/critic) actually inspected real files before
+   *  rendering a verdict, mirroring goal-verifier.ts's `applyEvidenceGate`
+   *  philosophy (a claim is only trustworthy when backed by an OBSERVED
+   *  signal in THIS run, never by the model's own unverified assertion).
+   *  Zero means the verdict's `Inspected:`/prose claims are unevidenced,
+   *  regardless of what the text says. */
+  readOnlyEvidenceCalls: number;
 }
 
 /**
@@ -312,6 +320,7 @@ export async function runSubagentOnce(
   // never which model dispatched a given step.
   let fileMutations = 0;
   let bashRuns = 0;
+  let readOnlyEvidenceCalls = 0;
   // Per-run prompt-cache key: the subagent replays its own growing history each
   // step, so a stable key (even across a model switch below — a stale cache key
   // on a NEW provider is simply unused, never wrong) gets provider cache hits
@@ -357,6 +366,28 @@ export async function runSubagentOnce(
   // retry ladder on the FIRST failed attempt instead of riding ~90s of backoff when
   // a genuinely different-credential-scope candidate is available RIGHT NOW.
   const rateLimitFallbackAvailable = (): boolean => fallbackCandidates().length > 0;
+  // Providers that have ALREADY produced an uncategorized-refusal bail THIS run —
+  // accumulates across reroutes (mirrors excludedCredentialScopes' own pattern)
+  // so a 2nd safety bail (on the FIRST fallback model) can never cycle back to a
+  // provider already ruled out, even though `attemptedModels` only tracks exact
+  // model ids, not whole providers.
+  const excludedSafetyProviders = new Set<string>();
+  // Stricter than fallbackCandidates(): a same-provider sibling shares the SAME
+  // constitutional/moderation classifier (unlike a same-credential-scope sibling,
+  // which is a BILLING boundary, not a classifier boundary) — trying it after an
+  // uncategorized refusal is not a genuinely different verdict, it's very likely
+  // the identical false positive again. Always excludes the CURRENT provider (not
+  // just accumulated ones), so this is correct from the very first check too.
+  const safetyFallbackCandidates = (): string[] => {
+    const currentProvider = resolveProvider(activeModel);
+    return fallbackCandidates().filter(m => {
+      const p = resolveProvider(m);
+      return p !== currentProvider && !excludedSafetyProviders.has(p);
+    });
+  };
+  // Fed to AgentLoopOptions.safetyFallbackAvailable — see its doc comment for the
+  // "false positive -> try a different model" design this implements.
+  const safetyFallbackAvailable = (): boolean => safetyFallbackCandidates().length > 0;
 
   let activeModel = initialModel;
   emit({ role: role.id, kind: "start", detail: taskText, maxSteps, model: activeModel });
@@ -374,6 +405,7 @@ export async function runSubagentOnce(
       steer,
       tools: subagentToolset(role),
       rateLimitFallbackAvailable,
+      safetyFallbackAvailable,
       events: {
         onStep: n => { currentStep = n; },
         // Live reasoning preview (native extended-thinking models only — the JSON-protocol
@@ -398,6 +430,7 @@ export async function runSubagentOnce(
           if (success) {
             if (tool === "write" || tool === "edit" || tool === "mkdir" || tool === "delete") fileMutations++;
             else if (tool === "bash") bashRuns++;
+            else if (tool === "read" || tool === "search" || tool === "find" || tool === "ast_grep" || tool === "lsp") readOnlyEvidenceCalls++;
           }
           const label = lastTarget || tool;
           const summary = firstUsefulLine(output);
@@ -418,22 +451,35 @@ export async function runSubagentOnce(
 
   let result = await runOnce();
   for (let attempt = 0; attempt < MAX_SUBAGENT_REROUTES; attempt++) {
-    if (result.done || !isRateLimitError(new Error(result.doneReason ?? ""))) break;
-    // The model that just 429'd: exclude its WHOLE credential scope (not just its
-    // own id) so a sibling model riding the SAME exhausted OAuth subscription is
-    // never proposed as a "fallback" (cca5fe2's fix, mirrored here).
-    const failedScope = credentialScopeFor(activeModel, opts.config);
-    if (failedScope) excludedCredentialScopes.add(failedScope.key);
-    const candidates = fallbackCandidates();
-    if (candidates.length === 0) break;
+    const rateLimited = !result.done && isRateLimitError(new Error(result.doneReason ?? ""));
+    const safetyBail = !result.done && !rateLimited && isSafetyFallbackBail(result.doneReason);
+    if (!rateLimited && !safetyBail) break;
     const previousModel = activeModel;
-    activeModel = selectFromPool(candidates, undefined);
+    if (rateLimited) {
+      // The model that just 429'd: exclude its WHOLE credential scope (not just its
+      // own id) so a sibling model riding the SAME exhausted OAuth subscription is
+      // never proposed as a "fallback" (cca5fe2's fix, mirrored here).
+      const failedScope = credentialScopeFor(activeModel, opts.config);
+      if (failedScope) excludedCredentialScopes.add(failedScope.key);
+      const candidates = fallbackCandidates();
+      if (candidates.length === 0) break;
+      activeModel = selectFromPool(candidates, undefined);
+      emit({ role: role.id, kind: "step", detail: `↳ rate limited on '${previousModel}' — switching to equivalent '${activeModel}'`, step: currentStep, maxSteps, model: activeModel });
+    } else {
+      // Uncategorized refusal with a fallback available (engine already verified
+      // this via safetyFallbackAvailable before bailing) — exclude the WHOLE
+      // provider (see safetyFallbackCandidates' doc comment), not just this model.
+      excludedSafetyProviders.add(resolveProvider(activeModel));
+      const candidates = safetyFallbackCandidates();
+      if (candidates.length === 0) break;
+      activeModel = selectFromPool(candidates, undefined);
+      emit({ role: role.id, kind: "step", detail: `↳ refused on '${previousModel}' — switching to '${activeModel}' in case of a classifier false positive`, step: currentStep, maxSteps, model: activeModel });
+    }
     attemptedModels.add(activeModel);
-    emit({ role: role.id, kind: "step", detail: `↳ rate limited on '${previousModel}' — switching to equivalent '${activeModel}'`, step: currentStep, maxSteps, model: activeModel });
     result = await runOnce();
   }
 
-  const reason = result.doneReason?.trim() || `(subagent reached the ${result.steps}-step limit without signaling done)`;
+  const reason = stripSafetyFallbackTag(result.doneReason?.trim() || "") || `(subagent reached the ${result.steps}-step limit without signaling done)`;
   const validation = validateSubagentDoneReason(role, reason);
   const complete = result.done && validation.ok;
   const detail = validation.ok ? reason : `${reason}\n\n[contract incomplete: missing ${validation.missing?.join(", ")}]`;
@@ -459,6 +505,7 @@ export async function runSubagentOnce(
     missingMarkers: validation.ok ? undefined : validation.missing,
     fileMutations,
     bashRuns,
+    readOnlyEvidenceCalls,
   };
 }
 

package/src/commands/launch.ts

@@ -1,7 +1,7 @@
 import { createInterface } from "node:readline/promises";
 import { emitKeypressEvents } from "node:readline";
 import { PassThrough } from "node:stream";
-import { runAgentLoop, DEFAULT_TOOLS, TOOL_PROTOCOL, WORKING_DISCIPLINE, OUTPUT_DISCIPLINE, VERIFICATION_DIRECTIVE, type AgentLoopEvents } from "../agent/engine";
+import { runAgentLoop, DEFAULT_TOOLS, TOOL_PROTOCOL, WORKING_DISCIPLINE, OUTPUT_DISCIPLINE, VERIFICATION_DIRECTIVE, isSafetyFallbackBail, stripSafetyFallbackTag, type AgentLoopEvents } from "../agent/engine";
 import { computerSupervisor } from "../agent/computer-supervisor";
 import { executeComputerAction } from "./computer";
 
@@ -10,6 +10,7 @@ import { initialDynamicStepLimit } from "../agent/step-budget";
 import { memoryPromptSection, spawnDetachedDistill, recordFailedAttempt } from "../agent/memory";
 import { recordSkillLesson } from "../agent/skill-lessons";
 import { createTaskTool, taskToolProtocolLine, type TaskSubEvent } from "../agent/task-tool";
+import { createEvalTool, evalToolProtocolLine } from "../agent/eval-tool";
 import { createSubagentTool, SUBAGENT_TOOL_PROTOCOL_LINE } from "../agent/subagent-tool";
 import { SubagentRegistry } from "../agent/subagent-registry";
 import { stopSessionNotifyEndpoint, startSessionNotifyEndpoint, type SessionNotifyEndpoint } from "../agent/notify/session-endpoint";
@@ -550,7 +551,7 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
   // pi-style: load project context (JEO.md / AGENTS.md / .jeo/context.md / CLAUDE.md) into the prompt.
   const contextFiles = await loadProjectContext(cwd);
 
-  const KNOWN_TOOLS = new Set(["read", "write", "edit", "bash", "find", "search", "ls", "task", "todo", "subagent", "job", "irc", "goal", "approve", "ast_grep", "ast_edit", "computer", "lsp", "lsp_rename", "debug", "browser"]);
+  const KNOWN_TOOLS = new Set(["read", "write", "edit", "bash", "find", "search", "ls", "task", "eval", "todo", "subagent", "job", "irc", "goal", "approve", "ast_grep", "ast_edit", "computer", "lsp", "lsp_rename", "debug", "browser"]);
   let allowedTools = new Set(KNOWN_TOOLS);
 
   if (flags.noTools) {
@@ -618,6 +619,7 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
     "\nWhen you have finished the user's request, or need to reply to or ask the user something, call done with {\"reason\": <your natural-language reply to the user>}. The reason text is shown to the user as your message." +
     (allowedTools.has("task") ? "\n\nDelegation: " + taskToolProtocolLine(cfg) +
     " Call task with {\"role\": <one of the advertised roles>, \"task\": <assignment>, \"context\": <optional>} to hand a focused slice to a subagent." : "") +
+    (allowedTools.has("eval") ? "\n\nDynamic Workflows: " + evalToolProtocolLine(cfg) : "") +
     (allowedTools.has("todo") ? "\n\nPlanning: " + TODO_TOOL_PROTOCOL_LINE : "") +
     (allowedTools.has("subagent") ? "\n\nDetached subagents: " + SUBAGENT_TOOL_PROTOCOL_LINE +
     " Launch background work with task {\"detached\": true, \"role\": <role>, \"task\": <assignment>}; it returns a subagent id immediately so you can keep working and collect the result later." : "") +
@@ -1012,11 +1014,33 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
     // genuinely different credential.
     const isAccountLevelRouteFailure = (reason: string): boolean =>
       /hit a rate limit|hit a usage\/quota limit|is unauthenticated for this session|has no usable credential|requires billing\/payment on this provider account/i.test(reason);
+    // Providers that have ALREADY produced a safety-classifier bail THIS turn —
+    // accumulates across fallback rounds (mirrors excludedCredentialScopes exactly,
+    // one paragraph up). Provider-scoped rather than credential-scoped: a
+    // same-provider sibling model shares the SAME constitutional/moderation
+    // classifier regardless of which credential serves it (unlike a rate limit,
+    // which is a billing/quota boundary, not a classifier boundary) — trying it
+    // after an uncategorized refusal is very likely the identical false positive,
+    // not a genuinely different verdict.
+    const excludedSafetyProviders = new Set<string>();
+    // Matches ONLY routeFailureReason's dedicated safety-fallback branch (the
+    // engine's `SafetyFallback (uncategorized):`-tagged bail, stripped to this
+    // reason text) — deliberately narrower than isRefusalError/isSafetyFallbackBail
+    // so a genuinely categorized (true-positive) refusal, which never reaches this
+    // branch at all, can never be classified as an account-level OR safety-level
+    // route failure by this predicate.
+    const isSafetyRouteFailure = (reason: string): boolean => /was refused \(possible safety classifier false positive\)/i.test(reason);
     const equivalentRouteFallback = async (decision: RouteDecision, reason: string, exclude: readonly string[] = []): Promise<string | null> => {
       if (isAccountLevelRouteFailure(reason)) {
         const scope = credentialScopeFor(decision.model, turnConfig);
         if (scope) excludedCredentialScopes.add(scope.key);
       }
+      // Provider-level exclusion (not just the credential scope above): a
+      // same-provider sibling shares the identical classifier a safety refusal
+      // just tripped on, so it is excluded ENTIRELY here — a stricter exclusion
+      // than the account-level branch's credential-scope-only one, matching
+      // task-tool.ts's `safetyFallbackCandidates` (same rationale, same shape).
+      if (isSafetyRouteFailure(reason)) excludedSafetyProviders.add(resolveProvider(decision.model));
       const excluded = new Set([decision.model, ...exclude]);
       const poolCandidates = (): string[] =>
         tierModelPool(decision.tier, turnConfig)
@@ -1025,6 +1049,7 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
             const scope = credentialScopeFor(model, turnConfig);
             return !scope || !excludedCredentialScopes.has(scope.key);
           })
+          .filter(model => !excludedSafetyProviders.has(resolveProvider(model)))
           .filter(model => !images?.length || catalogMetadata(model)?.images !== false);
       let candidates = poolCandidates();
       // The static MODEL_CATALOG only lists a couple of OpenAI-compatible clouds by
@@ -1465,6 +1490,14 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
               ? (e => tui?.onSubagentEvent(e))
               : (e => logTaskSubEvent(e)),
           }),
+          eval: createEvalTool({
+            config: { ...turnConfig, defaultModel: activeModel },
+            signal: ac.signal,
+            steer: drainSteer,
+            onEvent: useTui
+              ? (e => tui?.onSubagentEvent(e))
+              : (e => logTaskSubEvent(e)),
+          }),
           todo: createTodoTool({ onChange: items => { turnTodos = items; tui?.setTodos(items); } }),
           subagent: createSubagentTool(subagentRegistry),
           job: createJobTool(jobRegistry),
@@ -1543,6 +1576,25 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
             })
             .some(model => !images?.length || catalogMetadata(model)?.images !== false);
         };
+        // Same shape as rateLimitFallbackAvailable above, plus a same-PROVIDER
+        // exclusion (not just same-credential-scope): a sibling model from the
+        // provider that JUST safety-bailed shares its classifier, so it is not a
+        // genuinely different fallback candidate (see excludedSafetyProviders'
+        // doc comment). Fed to AgentLoopOptions.safetyFallbackAvailable.
+        const safetyFallbackAvailable = (): boolean => {
+          const currentScope = credentialScopeFor(fallbackBaseDecision.model, turnConfig);
+          const currentProvider = resolveProvider(fallbackBaseDecision.model);
+          return tierModelPool(fallbackBaseDecision.tier, turnConfig)
+            .filter(model => !attemptedRouteModels.has(model))
+            .filter(model => resolveProvider(model) !== currentProvider && !excludedSafetyProviders.has(resolveProvider(model)))
+            .filter(model => {
+              const scope = credentialScopeFor(model, turnConfig);
+              if (!scope) return true; // API-key-served (or keyless) — independent budget
+              if (currentScope && scope.key === currentScope.key) return false; // same exhausted subscription
+              return !excludedCredentialScopes.has(scope.key);
+            })
+            .some(model => !images?.length || catalogMetadata(model)?.images !== false);
+        };
         const runLoopWithModel = (model: string, thinking: ThinkLevel | undefined, cacheKey: string | undefined, maxSteps = flags.maxSteps, budget?: { maxExtensions: number }) => runAgentLoop(history, {
           cwd,
           tools,
@@ -1555,11 +1607,20 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
           sessionKey: cacheKey,
           steer: drainSteer,
           rateLimitFallbackAvailable,
+          safetyFallbackAvailable,
           events: wrapEvents(withStepPersistence({ ...withToolDetailCapture(tui ? tui.events() : streamEvents), onBeforeDone }, persistTurnTail), opik),
         });
         const routeFailureReason = (doneReason: unknown): string | null => {
           const message = String(doneReason ?? "");
           if (!message) return "stopped without a final answer";
+          // MUST be checked before every pattern below: the engine's own tagged
+          // safety-fallback bail wraps a `friendlyProviderError` refusal message,
+          // which contains "refusal"/"safety" text that the safety-refusal guard
+          // further down (`returned no content` branch) would otherwise swallow
+          // (return null, never reroute) — this tag means the engine ALREADY
+          // verified a fallback is available and deliberately asked for a reroute,
+          // so it must win outright, not fall through to that guard.
+          if (isSafetyFallbackBail(message)) return "was refused (possible safety classifier false positive)";
           const asError = new Error(message);
           if (isRateLimitError(asError)) return "hit a rate limit";
           if (isUsageLimitError(asError)) return "hit a usage/quota limit";
@@ -1720,7 +1781,7 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
     }
     // A completed turn with an empty done-reason must NOT masquerade as a step-limit
     // failure ("reached the 3-step limit" after the model called done at step 3).
-    const reply = result.doneReason
+    const reply = stripSafetyFallbackTag(result.doneReason ?? "")
       || (result.done
         ? `(done in ${result.steps} step${result.steps === 1 ? "" : "s"} — the model returned no summary)`
         : `(reached the ${result.steps}-step limit without signaling done)`);
@@ -1820,6 +1881,18 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
 
   const joinedArgs = flags.message;
   const isOneShot = flags.print || joinedArgs.length > 0 || !process.stdin.isTTY;
+  // hermes-style experience distill (plan/gjc-inheritance.md B6) for one-shot
+  // (`-p`/`--print`/piped) mode — previously ONLY the interactive exit path
+  // spawned this, so a one-shot invocation (the common CI/scripted shape, e.g.
+  // `jeo "task" -p`) never wrote anything to session memory no matter how many
+  // turns it ran. Mirrors the interactive path's exact gate (sessionUsage.turns
+  // > 0) and stays silent (no stdout noise) since one-shot output may be
+  // piped/parsed by a script.
+  const maybeDistillOneShot = async (): Promise<void> => {
+    if (sessionUsage.turns > 0) {
+      await spawnDetachedDistill(history, cwd, sessionModel || defaultModel);
+    }
+  };
 
   if (isOneShot) {
     let messageContent = joinedArgs;
@@ -2006,12 +2079,14 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
       for (const inv of skillChain.invocations) {
         await runOneSkillShot(inv);
       }
+      await maybeDistillOneShot();
       return;
     }
     // A `$skill` invocation resolves to a single skill (by name, declared alias, or unique prefix).
     const skillInvocation = parseSkillInvocation(messageContent, resolvedSkills);
     if (skillInvocation) {
       await runOneSkillShot(skillInvocation);
+      await maybeDistillOneShot();
       return;
     }
     try {
@@ -2021,6 +2096,7 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
     } catch (err) {
       console.log(`! ${friendlyProviderError(err)}`);
     }
+    await maybeDistillOneShot();
     return;
   }
 

package/src/commands/ralplan.ts

@@ -73,6 +73,13 @@ export async function runConsensusCriticGate(args: {
   const rateLimitFallbackAvailable = (): boolean => fallbackCandidates().length > 0;
 
   let activeModel = initialModel;
+  // Evidence tracking (mirrors task-tool.ts's runSubagentOnce readOnlyEvidenceCalls
+  // + team.ts's evaluateSubagentResult gate): this consensus gate is the OTHER
+  // independent-verifier code path in jeo (team.ts's per-step gate is the first) —
+  // it does NOT go through runSubagentOnce, so it needs its own tracking. A verdict
+  // is gated the SAME way: zero observed read/search/find/ast_grep/lsp calls means
+  // the [OKAY]/[ITERATE]/[REJECT] text is unevidenced regardless of what it claims.
+  let evidenceCalls = 0;
   const runOnce = () => runAgentLoop(history, {
     cwd: args.cwd,
     model: activeModel,
@@ -81,6 +88,11 @@ export async function runConsensusCriticGate(args: {
     signal: args.signal,
     tools: subagentToolset(role),
     rateLimitFallbackAvailable,
+    events: {
+      onToolResult: (tool, success) => {
+        if (success && (tool === "read" || tool === "search" || tool === "find" || tool === "ast_grep" || tool === "lsp")) evidenceCalls++;
+      },
+    },
   });
   let result = await runOnce();
   for (let attempt = 0; attempt < MAX_SUBAGENT_REROUTES; attempt++) {
@@ -97,6 +109,9 @@ export async function runConsensusCriticGate(args: {
   if (!result.done) return { verdict: "unverified", detail: reason || `critic did not converge within ${result.steps} steps` };
   const contract = validateSubagentDoneReason(role, reason);
   if (!contract.ok) return { verdict: "unverified", detail: `critic report incomplete (missing ${contract.missing?.join(", ")}): ${reason.slice(0, 300)}` };
+  if (evidenceCalls === 0) {
+    return { verdict: "unverified", detail: `critic returned a verdict with ZERO observed read/search/find/ast_grep/lsp calls — unevidenced, regardless of the verdict text: ${reason.slice(0, 300)}` };
+  }
   const firstLine = reason.split(/\r?\n/, 1)[0]?.trim() ?? "";
   const verdict = firstLine === "[OKAY]" ? "okay" : firstLine === "[ITERATE]" ? "iterate" : firstLine === "[REJECT]" ? "reject" : "unverified";
   return { verdict, detail: reason };
@@ -189,7 +204,14 @@ export async function runRalplanEngine(opts: RalplanEngineOptions = {}): Promise
     `reading or building on another's output. Never mark two steps parallel if one depends on, ` +
     `reads, or extends a file another writes. When unsure, leave parallel_group out — a plain ` +
     `serial step is always correct; a wrongly-parallel step risks a merge conflict that halts ` +
-    `execution.`;
+    `execution.\n\n` +
+    `MANDATORY: if ANY step mutates (role: executor, or role omitted — omitted defaults to ` +
+    `executor), the plan MUST end with a DEDICATED role: architect or role: critic step AFTER ` +
+    `the last mutating step (never inside the same parallel_group as a mutating step — concurrent ` +
+    `steps cannot verify each other). A plan of executor-only steps with no trailing verifier is ` +
+    `REJECTED. This is the independent verifier that inspects what was actually built before the ` +
+    `plan counts as done — a read-only-only plan (planner/architect/critic steps with no executor ` +
+    `at all) needs no verifier, since nothing mutated.`;
 
   const PLANNER = `You are the PLANNER. From the crystallized spec, sequence the work into a logical, outcome-based progression of concrete, ordered tasks.\n` + SCHEMA_SPEC;
   const ARCHITECT = `You are the ARCHITECT. Review the Planner's draft for technical feasibility, correct file targets, directory structure, and any missing setup/wiring/test steps. Return an improved plan (same shape).\n` + SCHEMA_SPEC;
@@ -212,16 +234,26 @@ export async function runRalplanEngine(opts: RalplanEngineOptions = {}): Promise
       const raw = await callLlm([{ role: "user" as const, content: userContent }], { systemPrompt, model });
       return raw.replace(/```yaml|```/g, "").trim();
     };
-    const isValidPlan = (yaml: string): boolean => {
+    /** Validates `yaml` against `PlanSchema` + role-name legality, returning the
+     *  FIRST concrete reason it's invalid (zod issue message, or an unknown-role
+     *  name) — or `undefined` when valid. Feeding the actual reason back into the
+     *  repair prompt (instead of a generic "didn't match the schema") lets the
+     *  Critic's one repair attempt fix the REAL problem (e.g. a missing trailing
+     *  verifier step) instead of guessing. */
+    const planValidationError = (yaml: string): string | undefined => {
       try {
         const parsed = PlanSchema.safeParse(normalizePlanShape(parseYaml(yaml)));
-        if (!parsed.success) return false;
+        if (!parsed.success) {
+          return parsed.error.issues[0]?.message ?? "plan did not match the required schema";
+        }
         // Round-10 #2 (architect ref 8-Round10Planning): write-time parity with
         // team's execution gate — an unknown role (e.g. "developer") used to pass
         // here and abort only at `jeo team`, after the planning model was gone.
-        return parsed.data.steps.every(s => !s.role?.trim() || !!getSubagentRole(s.role));
-      } catch {
-        return false;
+        const badRole = parsed.data.steps.find(s => s.role?.trim() && !getSubagentRole(s.role));
+        if (badRole) return `step "${badRole.name}" declares unknown role "${badRole.role}" (must be executor|planner|architect|critic)`;
+        return undefined;
+      } catch (e) {
+        return e instanceof Error ? e.message : "plan YAML failed to parse";
       }
     };
 
@@ -266,11 +298,12 @@ export async function runRalplanEngine(opts: RalplanEngineOptions = {}): Promise
     // complete (round-10 #2) — failing here, while the model is still in the loop,
     // beats failing later at `jeo team` with the same plan.
     let planValid = true;
-    if (!isValidPlan(cleanPlan)) {
-      log("[ralplan] Final plan did not match the required shape; requesting a corrected plan…");
-      cleanPlan = await callRole(CRITIC, `Your previous output was not valid for the required schema. Fix it (roles MUST be one of executor|planner|architect|critic).\n\n${SCHEMA_SPEC}\n\nPlan to fix:\n\n${cleanPlan}`, CRITIC_MODEL);
-      if (!isValidPlan(cleanPlan)) {
-        const fallback = [reviewed, draft].find(isValidPlan);
+    const firstError = planValidationError(cleanPlan);
+    if (firstError) {
+      log(`[ralplan] Final plan did not match the required shape (${firstError}); requesting a corrected plan…`);
+      cleanPlan = await callRole(CRITIC, `Your previous output was invalid: ${firstError}\n\n${SCHEMA_SPEC}\n\nPlan to fix:\n\n${cleanPlan}`, CRITIC_MODEL);
+      if (planValidationError(cleanPlan)) {
+        const fallback = [reviewed, draft].find(p => !planValidationError(p));
         if (fallback) {
           cleanPlan = fallback;
           log("[ralplan] Using an earlier valid pass output (Critic output was unparseable).");
@@ -314,7 +347,7 @@ export async function runRalplanEngine(opts: RalplanEngineOptions = {}): Promise
         `Revise the plan to address every point.\n\n${SCHEMA_SPEC}\n\nCurrent plan:\n\n${cleanPlan}`,
         CRITIC_MODEL,
       );
-      if (isValidPlan(revised)) {
+      if (!planValidationError(revised)) {
         cleanPlan = revised;
         await fs.writeFile(planPath, cleanPlan, "utf-8");
         gate = await runConsensusCriticGate({ cwd, seedContent, plan: cleanPlan, signal: opts.signal });

package/src/commands/team.ts

@@ -519,6 +519,25 @@ function evaluateSubagentResult(
     return false;
   }
 
+  // Evidence gate (UNCONDITIONAL — same tier as parseRoleGateVerdict, never
+  // softened by --strict-mutations): an architect/critic verdict is worthless
+  // if the subagent never actually looked at anything. Mirrors goal-verifier.ts's
+  // applyEvidenceGate philosophy applied to the OTHER independent-verifier gate
+  // in this codebase — a formatted "Architectural Status: CLEAR" or "[OKAY]"
+  // first line is text the model can emit with ZERO real inspection; only an
+  // OBSERVED read/search/find/ast_grep/lsp call in this run counts as evidence
+  // the verdict is grounded in the actual repository state, not the model's own
+  // unverified assertion (2026 pattern: "avoid vibes verification — a claim is
+  // only trustworthy when backed by a programmatic, observed signal").
+  if ((role.id === "architect" || role.id === "critic") && result.readOnlyEvidenceCalls === 0) {
+    log(formatRalphStreamEvent(
+      "error",
+      `${role.title} returned a verdict with ZERO observed read/search/find/ast_grep/lsp calls — an unevidenced verdict is not trustworthy regardless of what the text claims. Blocking.`,
+      renderOpts,
+    ));
+    return false;
+  }
+
   // Round-8: a mutating role finished without a successful file mutation — the
   // task may be legitimately read-only, but its "Changed Files:" claim is
   // unverified. bash is tracked apart: an only-bash run MIGHT have mutated.