jeo-code 0.8.22 → 0.8.24

package/src/cli/runner.ts

@@ -119,11 +119,23 @@ export const COMMANDS: readonly CommandSpec[] = [
       return args => m.runDaemonCommand(args);
     },
   },
+  {
+    name: "routine",
+    summary: "Generate a GitHub Actions workflow that runs jeo headlessly on a schedule or repo event.",
+    usage: 'routine init --trigger <schedule|issues|pull_request> --prompt "<task>" [--cron <expr>] [--name <name>] [--out <path>] [--no-pr] [--force] [--dry-run] [--json]',
+    loader: async () => {
+      // Dynamic import: lazy-loaded command registry entry (CommandSpec.loader
+      // contract), matching every other entry in this array — avoids eagerly
+      // importing all ~25 command modules at CLI startup.
+      const m = await import("../commands/routine");
+      return args => m.runRoutineCommand(args);
+    },
+  },
 
   {
     name: "skills",
     summary: "List bundled workflow skills, or sync them into ~/.jeo/skills (jeo skills <name> for details).",
-    usage: "skills [list|read <name>|sync [--check|--force] [dir]|--write [dir]] [--json]",
+    usage: "skills [list|read <name>|sync [--check|--force] [dir]|--write [dir]|lesson <skill> <failure|anti-pattern> \"<title>\" \"<detail>\"|eval <skill>] [--json]",
     loader: async () => {
       const m = await import("../commands/skills");
       return args => m.runSkillsCommand(args);

package/src/commands/launch.ts

@@ -1,14 +1,16 @@
 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";
 
 import { createOpikTracer, wrapEvents } from "../agent/opik-tracer";
 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";
@@ -51,7 +53,7 @@ import { rememberModelPatch, recentModelsForDisplay } from "../agent/model-recen
 import { describeModel, describeAllProviders, describeProvider, resolveProvider, thinkingMaxTokens, resolveMaxOutputTokens, thinkingToReasoningEffort, discoverModels, flattenModels, resolveSelection, catalogMetadata, catalogByProvider, resolveRoleModel, CODEX_MODELS, qualifyModelId, modelServableWithConfig, isLocalProviderReachable } from "../ai";
 import type { ProviderModelsResult, PickEntry, ProviderName, ModelRole, ThinkLevel } from "../ai";
 import { readGoalState, writeGoalState, clearGoalState, verifyGoal, applyEvidenceGate } from "../agent/goal-verifier";
-import { routePrompt, deriveCacheSessionKey, warnOnce, tierModelPool, selectFromPool, PROMPT_TIERS, withRoutingTierSetting, inferTierForModel, type PromptTier, type RouteDecision } from "../agent/prompt-router";
+import { routePrompt, deriveCacheSessionKey, warnOnce, tierModelPool, selectFromPool, PROMPT_TIERS, withRoutingTierSetting, inferTierForModel, credentialScopeFor, resolveVerifierModel, type PromptTier, type RouteDecision, type RoutingConfig } from "../agent/prompt-router";
 import { RouteHistory } from "../agent/route-history";
 
 import { isRateLimitError, isUsageLimitError, isConnectionError } from "../util/retry";
@@ -549,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) {
@@ -617,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." : "") +
@@ -976,11 +979,77 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
     const routingEnabled = sessionRouteOverride ?? !!turnConfig.routing?.enabled;
     let routeCredentialNotice: string | undefined;
     let routeVetoNote: string | undefined;
+    // Credential SCOPES that have shown an ACCOUNT-LEVEL failure (rate limit,
+    // usage/quota limit, or zero usable credential) THIS turn — accumulates across
+    // every fallback round. Read by both `equivalentRouteFallback` (post/pre-call
+    // fallback search) and `rateLimitFallbackAvailable` (the engine's fast-bail
+    // predicate) so neither path proposes a candidate doomed to fail the same way.
+    //
+    // Scoped to the CREDENTIAL, not the bare provider (see `credentialScopeFor` in
+    // prompt-router.ts for the full classification rationale/doc comment) — an OAuth
+    // SUBSCRIPTION shares ONE account-wide rate-limit window across every model it
+    // serves; an API key is typically its OWN independent per-key/per-model budget.
+    // `null` (from `credentialScopeFor`) means "API-key-served, or otherwise not
+    // sharing a subscription credential" — never added to or matched against this set.
+    const excludedCredentialScopes = new Set<string>();
+    // Matches routeFailureReason's post-call reasons ("hit a rate limit", "hit a
+    // usage/quota limit", "is unauthenticated for this session", "requires
+    // billing/payment on this provider account") AND the pre-call credential gate's
+    // "(<provider>) has no usable credential this turn" — every string that means
+    // "this CREDENTIAL is exhausted/broken", as opposed to a model-specific issue
+    // (OAuth serves only some models, a single model is retired/gated — see
+    // routeFailureReason's own doc comments for why those stay model-scoped).
+    //
+    // Billing/payment (402) is intentionally included even though the ORIGINAL field
+    // observation behind routeFailureReason's 402 branch (Tencent: kimi-k2.5/
+    // deepseek-v3.2 402 while deepseek-v4-flash/glm-5.2 kept working on the SAME key)
+    // is a per-MODEL billing block on an API-KEY-served provider — this does NOT
+    // contradict including it here: `credentialScopeFor` already returns `null` for
+    // every API-key-served model (never group-excluded regardless of this regex's
+    // answer), so the Tencent case is unaffected either way. What this DOES newly
+    // catch: an OAuth SUBSCRIPTION billing failure (e.g. a Claude Pro/Max payment
+    // lapse) is account-wide by construction — every model riding that subscription
+    // is equally blocked — and previously wasted a full fallback round retrying a
+    // same-scope sibling model guaranteed to 402 identically before ever reaching a
+    // 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)
           .filter(model => !excluded.has(model))
+          .filter(model => {
+            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
@@ -1383,7 +1452,7 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
             }
 
             if (tui) tui.events().onNotice?.("[Goal Verifier] Running goal verification...");
-            const llmVerdict = await verifyGoal(goalState.condition, history, activeModel);
+            const llmVerdict = await verifyGoal(goalState.condition, history, resolveVerifierModel(turnConfig));
             // Deterministic downgrade: a fresh MET from the transcript-only LLM
             // judge still needs mutation/verification evidence to back it up —
             // see applyEvidenceGate's own docs (goal-verifier.ts). NOT_MET/
@@ -1421,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),
@@ -1448,6 +1525,76 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
           tags: ["jeo", "launch"],
         });
         opik.startTurn();
+        // Hoisted above `runLoopWithModel` (moved from after its first call) so the
+        // rate-limit fast-fallback predicate below can see the CURRENT attempted-model
+        // set on every call, including the very first one. `attemptedRouteModels` is
+        // mutated in place (`.add`) as the fallback loop below tries more models — this
+        // closure always reads its live contents, never a stale snapshot.
+        const attemptedRouteModels = new Set<string>([activeModel]);
+        // A NON-routed turn (routing disabled, or the user pinned a model via /model)
+        // still needs the equivalent-pool fallback on a usage-limit/rate-limit/credential
+        // failure — the exact "5-hour usage window exhausted, model just stops working"
+        // case this loop exists to fix. Synthesize a same-size-class RouteDecision
+        // (inferTierForModel) so `equivalentRouteFallback` has a tier/pool to search even
+        // with routing off; a real `routed` decision (routing enabled) is used unchanged.
+        let fallbackBaseDecision: RouteDecision = routed ?? {
+          model: activeModel,
+          thinking: activeThinking,
+          tier: inferTierForModel(activeModel),
+          confidence: 1,
+          source: "heuristic",
+          signals: [],
+        };
+        // Cheap SYNC check (no network/credential probing — that full validation is
+        // `equivalentRouteFallback`'s job when a switch actually happens) for "does an
+        // untried, DIFFERENT-PROVIDER candidate exist RIGHT NOW". Feeds
+        // AgentLoopOptions.rateLimitFallbackAvailable so the engine can bail a 429 retry
+        // ladder on the first failed attempt instead of riding ~90s of backoff on a
+        // model that has an equivalent sitting right there. Mirrors
+        // `equivalentRouteFallback`'s own `poolCandidates` filters (tier pool minus
+        // already-tried models minus image-incapable models when this turn has images)
+        // PLUS excludes any candidate sharing the SAME CREDENTIAL SCOPE as the model
+        // CURRENTLY being attempted (a 429 on this model means ITS credential's
+        // account/subscription window is exhausted THIS instant — another model
+        // riding the SAME OAuth subscription hits that exact limit and is not a real
+        // fallback; an API-key-served candidate has an independent budget and is NOT
+        // excluded) and any scope already excluded by an earlier account-level
+        // failure this turn — see `excludedCredentialScopes`'s doc comment. Without
+        // this, the predicate could see e.g. `claude-sonnet-4-6` as "available" while
+        // `claude-sonnet-5` (same Anthropic OAuth subscription) is the one currently
+        // 429ing, bail, switch to it, and immediately re-429 — which looks
+        // indistinguishable from "never escaping auto-retry #1".
+        const rateLimitFallbackAvailable = (): boolean => {
+          const currentScope = credentialScopeFor(fallbackBaseDecision.model, turnConfig);
+          return tierModelPool(fallbackBaseDecision.tier, turnConfig)
+            .filter(model => !attemptedRouteModels.has(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);
+        };
+        // 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,
@@ -1459,11 +1606,21 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
           signal: ac.signal,
           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";
@@ -1530,21 +1687,6 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
         const routeFallbackMax = Number.isFinite(routeFallbackMaxRaw) && routeFallbackMaxRaw >= 0
           ? Math.floor(routeFallbackMaxRaw)
           : 3;
-        const attemptedRouteModels = new Set<string>([activeModel]);
-        // A NON-routed turn (routing disabled, or the user pinned a model via /model)
-        // still needs the equivalent-pool fallback on a usage-limit/rate-limit/credential
-        // failure — the exact "5-hour usage window exhausted, model just stops working"
-        // case this loop exists to fix. Synthesize a same-size-class RouteDecision
-        // (inferTierForModel) so `equivalentRouteFallback` has a tier/pool to search even
-        // with routing off; a real `routed` decision (routing enabled) is used unchanged.
-        let fallbackBaseDecision: RouteDecision = routed ?? {
-          model: activeModel,
-          thinking: activeThinking,
-          tier: inferTierForModel(activeModel),
-          confidence: 1,
-          source: "heuristic",
-          signals: [],
-        };
         for (let routeFallbackAttempt = 0; routeFallbackAttempt < routeFallbackMax; routeFallbackAttempt++) {
           const routedFailureReason = !result.done ? routeFailureReason(result.doneReason) : null;
           if (!routedFailureReason) break;
@@ -1592,6 +1734,15 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
             signal: ac.signal,
             sessionKey: turnSessionKey,
             steer: drainSteer,
+            // Deliberately NOT wiring rateLimitFallbackAvailable here: this repair
+            // retry has no reroute loop around it (unlike runLoopWithModel's
+            // routeFallbackAttempt loop) — bailing the retry ladder early on a 429
+            // would only fail FASTER with the identical outcome (no fallback model to
+            // switch to either way), trading away the one real win the full backoff
+            // ladder still offers here: a transient (<~90s) rate-limit blip clearing
+            // mid-wait and this retry succeeding. See launch.ts's `rateLimitFallbackAvailable`
+            // doc comment / commit history for why this predicate is paired with an
+            // actual model-switch loop everywhere else it's used.
             events: wrapEvents(withToolDetailCapture(tui ? tui.events() : streamEvents), opik),
           });
           const usage =
@@ -1630,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)`);
@@ -1685,12 +1836,17 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
       const tags = Array.from(new Set(
         task.toLowerCase().match(/[a-z0-9][a-z0-9_-]{3,}/g) ?? [],
       )).slice(0, 8);
-      void recordFailedAttempt(cwd, {
-        title: `Stalled on: ${excerpt}`,
-        description: `A prior turn stalled (${why}) on this task — change approach before retrying.`,
-        body: `Task: ${task.slice(0, 240)}\n\nThe agent gave up after ${why} (${result.steps} steps) and could not recover. ` +
-          `Do NOT repeat the same line of attack; try a different decomposition, tool, or verification path.`,
-        tags,
+      const title = `Stalled on: ${excerpt}`;
+      const description = `A prior turn stalled (${why}) on this task — change approach before retrying.`;
+      const body = `Task: ${task.slice(0, 240)}\n\nThe agent gave up after ${why} (${result.steps} steps) and could not recover. ` +
+        `Do NOT repeat the same line of attack; try a different decomposition, tool, or verification path.`;
+      void recordFailedAttempt(cwd, { title, description, body, tags }).catch(() => {});
+      // Also offer the same failure to the skill-lessons system (deterministic
+      // free-text -> skill match; writes nothing when no skill clearly relates).
+      void recordSkillLesson(cwd, `${title} ${description}`, {
+        kind: "failure-mode",
+        title,
+        detail: body.slice(0, 300),
       }).catch(() => {});
     }
     const usage = result.usage ? `  (${result.usage.inputTokens} in / ${result.usage.outputTokens} out tokens)` : "";
@@ -1725,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;
@@ -1911,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 {
@@ -1926,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

@@ -19,6 +19,9 @@ import {
   resolveSubagentMaxSteps,
 } from "../agent/subagents";
 import { runAgentLoop } from "../agent/engine";
+import { inferTierForModel, tierModelPool, credentialScopeFor, selectFromPool } from "../agent/prompt-router";
+import { isRateLimitError } from "../util/retry";
+import { MAX_SUBAGENT_REROUTES } from "../agent/task-tool";
 
 /** Round-11 (architect ref 8-Round10Planning #1): the REAL consensus gate. A
  *  read-only critic SUBAGENT (repo access via read/search/find) reviews the
@@ -33,7 +36,7 @@ export async function runConsensusCriticGate(args: {
 }): Promise<{ verdict: "okay" | "iterate" | "reject" | "unverified"; detail: string }> {
   const role = getSubagentRole("critic")!;
   const config = await readGlobalConfig();
-  const model = resolveSubagentModel(role.id, config);
+  const initialModel = resolveSubagentModel(role.id, config);
   const maxSteps = resolveSubagentMaxSteps(role.id, config);
   const history: Message[] = [
     { role: "system", content: subagentSystemPrompt(role) },
@@ -48,18 +51,67 @@ export async function runConsensusCriticGate(args: {
         `Then call done — your reason MUST start with [OKAY], [ITERATE], or [REJECT] and include a 'Justification:' section.`,
     },
   ];
-  const result = await runAgentLoop(history, {
+  // Rate-limit fast fallback (see task-tool.ts's `runSubagentOnce` for the full
+  // design doc — same pattern, single-call variant: no fan-out here, so no
+  // batch-shared excludedCredentialScopes need apply). A bail-only predicate with
+  // no real reroute-and-retry loop around it is a net regression (02b7e59) — this
+  // gate pairs `rateLimitFallbackAvailable` with the actual switch-and-retry below.
+  const tier = inferTierForModel(initialModel);
+  const attemptedModels = new Set<string>([initialModel]);
+  const excludedCredentialScopes = new Set<string>();
+  const fallbackCandidates = (): string[] => {
+    const currentScope = credentialScopeFor(activeModel, config);
+    return tierModelPool(tier, config)
+      .filter(m => !attemptedModels.has(m))
+      .filter(m => {
+        const scope = credentialScopeFor(m, config);
+        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);
+      });
+  };
+  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,
+    model: activeModel,
     maxSteps,
     budget: { maxExtensions: 0 },
     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++) {
+    if (result.done || !isRateLimitError(new Error(result.doneReason ?? ""))) break;
+    const failedScope = credentialScopeFor(activeModel, config);
+    if (failedScope) excludedCredentialScopes.add(failedScope.key);
+    const candidates = fallbackCandidates();
+    if (candidates.length === 0) break;
+    activeModel = selectFromPool(candidates, undefined);
+    attemptedModels.add(activeModel);
+    result = await runOnce();
+  }
   const reason = result.doneReason?.trim() ?? "";
   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 };
@@ -152,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;
@@ -175,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";
       }
     };
 
@@ -229,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).");
@@ -277,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 });