jeo-code 0.8.22 → 0.8.23

package/src/commands/launch.ts

@@ -8,6 +8,7 @@ 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 { createSubagentTool, SUBAGENT_TOOL_PROTOCOL_LINE } from "../agent/subagent-tool";
 import { SubagentRegistry } from "../agent/subagent-registry";
@@ -51,7 +52,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";
@@ -976,11 +977,54 @@ 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);
     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);
+      }
       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 => !images?.length || catalogMetadata(model)?.images !== false);
       let candidates = poolCandidates();
       // The static MODEL_CATALOG only lists a couple of OpenAI-compatible clouds by
@@ -1383,7 +1427,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/
@@ -1448,6 +1492,57 @@ 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);
+        };
         const runLoopWithModel = (model: string, thinking: ThinkLevel | undefined, cacheKey: string | undefined, maxSteps = flags.maxSteps, budget?: { maxExtensions: number }) => runAgentLoop(history, {
           cwd,
           tools,
@@ -1459,6 +1554,7 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
           signal: ac.signal,
           sessionKey: cacheKey,
           steer: drainSteer,
+          rateLimitFallbackAvailable,
           events: wrapEvents(withStepPersistence({ ...withToolDetailCapture(tui ? tui.events() : streamEvents), onBeforeDone }, persistTurnTail), opik),
         });
         const routeFailureReason = (doneReason: unknown): string | null => {
@@ -1530,21 +1626,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 +1673,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 =
@@ -1685,12 +1775,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)` : "";

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,14 +51,48 @@ 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;
+  const runOnce = () => runAgentLoop(history, {
     cwd: args.cwd,
-    model,
+    model: activeModel,
     maxSteps,
     budget: { maxExtensions: 0 },
     signal: args.signal,
     tools: subagentToolset(role),
+    rateLimitFallbackAvailable,
   });
+  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);

package/src/commands/routine.ts

@@ -0,0 +1,249 @@
+/**
+ * `jeo routine init` — generate a GitHub Actions workflow that runs
+ * `jeo "<prompt>" -p` headlessly on a schedule or repo event.
+ *
+ * This is the SCOPED-SAFE take on "Routines": jeo-code itself never runs a
+ * scheduler, listens on a port, or accepts a webhook — it's a pure template
+ * generator. GitHub's own hosted runners do the actual triggering/running,
+ * which achieves "runs without your laptop" with zero new attack surface
+ * inside jeo-code's own process. See ../util/routine-template.ts for the
+ * pure YAML-building logic this command wraps with flag parsing + I/O.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { renderRoutineWorkflow, validateCron, type RoutineConfig, type RoutineTrigger } from "../util/routine-template";
+import { slugify } from "../agent/memory-okf";
+
+const TRIGGERS: readonly RoutineTrigger[] = ["schedule", "issues", "pull_request"];
+function isTrigger(val: string | undefined): val is RoutineTrigger {
+  return val !== undefined && (TRIGGERS as readonly string[]).includes(val);
+}
+
+const VALUE_FLAGS: Record<string, true> = { "--name": true, "--trigger": true, "--cron": true, "--prompt": true, "--api-key-env": true, "--out": true };
+
+interface ParsedInit {
+  name: string;
+  triggerRaw?: string;
+  cron?: string;
+  prompt?: string;
+  apiKeyEnvVar: string;
+  openPr: boolean;
+  out?: string;
+  force: boolean;
+  dryRun: boolean;
+  json: boolean;
+  help: boolean;
+  /** Parse-level problems: unknown flags, or a value-flag given with no value. */
+  errors: string[];
+}
+
+/** `--flag value` or `--flag=value`, matching launch/flags.ts's takeValue shape
+ *  (a bare value-flag followed by another `-`-prefixed token is treated as
+ *  missing, not as accidentally swallowing the next flag). */
+function takeValue(args: string[], index: number, flag: string): { value?: string; nextIndex: number } {
+  const current = args[index]!;
+  const inline = `${flag}=`;
+  if (current.startsWith(inline)) return { value: current.slice(inline.length), nextIndex: index };
+  const next = args[index + 1];
+  if (next !== undefined && !next.startsWith("-")) return { value: next, nextIndex: index + 1 };
+  return { nextIndex: index };
+}
+
+function parseInitArgs(args: string[]): ParsedInit {
+  const parsed: ParsedInit = {
+    name: "jeo routine",
+    apiKeyEnvVar: "ANTHROPIC_API_KEY",
+    openPr: true,
+    force: false,
+    dryRun: false,
+    json: false,
+    help: false,
+    errors: [],
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!;
+    const flag = a.includes("=") ? a.slice(0, a.indexOf("=")) : a;
+
+    if (flag === "-h" || flag === "--help") { parsed.help = true; continue; }
+    if (flag === "--no-pr") { parsed.openPr = false; continue; }
+    if (flag === "--force") { parsed.force = true; continue; }
+    if (flag === "--dry-run") { parsed.dryRun = true; continue; }
+    if (flag === "--json") { parsed.json = true; continue; }
+
+    if (VALUE_FLAGS[flag]) {
+      const { value, nextIndex } = takeValue(args, i, flag);
+      i = nextIndex;
+      if (value === undefined) {
+        parsed.errors.push(`${flag} requires a value`);
+        continue;
+      }
+      switch (flag) {
+        case "--name": parsed.name = value; break;
+        case "--trigger": parsed.triggerRaw = value; break;
+        case "--cron": parsed.cron = value; break;
+        case "--prompt": parsed.prompt = value; break;
+        case "--api-key-env": parsed.apiKeyEnvVar = value; break;
+        case "--out": parsed.out = value; break;
+      }
+      continue;
+    }
+
+    parsed.errors.push(`Unknown flag: ${a}`);
+  }
+
+  return parsed;
+}
+
+function printUsage(): void {
+  console.log("Usage: jeo routine init [options]");
+  console.log("");
+  console.log('Generate a GitHub Actions workflow that runs `jeo "<prompt>" -p` headlessly');
+  console.log("on a schedule or repo event. GitHub's own hosted runners do the triggering —");
+  console.log("jeo-code never runs a scheduler or listens on a port for this.");
+  console.log("");
+  console.log("Options:");
+  console.log("  --trigger <schedule|issues|pull_request>  Required. What fires the routine.");
+  console.log("  --prompt <text>            Required. The task/goal text passed to `jeo -p`.");
+  console.log('  --cron <expr>              Required when --trigger schedule (e.g. "0 7 * * *").');
+  console.log('  --name <name>              Workflow display name. Default: "jeo routine".');
+  console.log("  --api-key-env <VAR_NAME>   Secret env var name. Default: ANTHROPIC_API_KEY.");
+  console.log("  --no-pr                    Commit directly to the branch instead of opening a PR.");
+  console.log("  --out <path>               Output path. Default: .github/workflows/jeo-routine-<slug>.yml");
+  console.log("  --force                    Overwrite an existing file at --out.");
+  console.log("  --dry-run                  Print the rendered YAML instead of writing it.");
+  console.log("  --json                     Machine-readable output.");
+  console.log("  -h, --help                 Show this help message.");
+}
+
+async function runInit(args: string[]): Promise<void> {
+  const parsed = parseInitArgs(args);
+
+  if (parsed.errors.length > 0) {
+    for (const e of parsed.errors) console.log(`Error: ${e}`);
+    printUsage();
+    process.exitCode = 1;
+    return;
+  }
+
+  if (parsed.help) {
+    printUsage();
+    return;
+  }
+
+  const problems: string[] = [];
+  if (!isTrigger(parsed.triggerRaw)) {
+    problems.push(
+      parsed.triggerRaw
+        ? `--trigger must be one of: schedule, issues, pull_request (got '${parsed.triggerRaw}')`
+        : "--trigger is required (one of: schedule, issues, pull_request)",
+    );
+  }
+  if (!parsed.prompt) {
+    problems.push("--prompt is required");
+  }
+  const trigger = isTrigger(parsed.triggerRaw) ? parsed.triggerRaw : undefined;
+  if (trigger === "schedule") {
+    if (!parsed.cron) {
+      problems.push("--cron is required when --trigger schedule");
+    } else if (!validateCron(parsed.cron)) {
+      problems.push(`--cron '${parsed.cron}' does not look like a valid 5-field cron expression`);
+    }
+  }
+
+  if (problems.length > 0) {
+    for (const p of problems) console.log(`Error: ${p}`);
+    printUsage();
+    process.exitCode = 1;
+    return;
+  }
+
+  const config: RoutineConfig = {
+    name: parsed.name,
+    trigger: trigger!,
+    cron: parsed.cron,
+    prompt: parsed.prompt!,
+    apiKeyEnvVar: parsed.apiKeyEnvVar,
+    openPr: parsed.openPr,
+  };
+
+  let yaml: string;
+  try {
+    yaml = renderRoutineWorkflow(config);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (parsed.json) console.log(JSON.stringify({ error: msg }));
+    else console.log(`Error: ${msg}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const outPath = parsed.out ?? path.join(".github", "workflows", `jeo-routine-${slugify(parsed.name)}.yml`);
+  const resolvedOut = path.resolve(process.cwd(), outPath);
+
+  if (parsed.dryRun) {
+    if (parsed.json) console.log(JSON.stringify({ dryRun: true, out: resolvedOut, yaml }, null, 2));
+    else console.log(yaml);
+    return;
+  }
+
+  let exists = true;
+  try {
+    await fs.access(resolvedOut);
+  } catch {
+    exists = false;
+  }
+  if (exists && !parsed.force) {
+    const msg = `${resolvedOut} already exists. Use --force to overwrite.`;
+    if (parsed.json) console.log(JSON.stringify({ error: msg }));
+    else console.log(`Error: ${msg}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  await fs.mkdir(path.dirname(resolvedOut), { recursive: true });
+  // Atomic write: build the file fully off to the side, then rename into
+  // place, so a crash mid-write never leaves a truncated workflow file.
+  const tmpPath = `${resolvedOut}.tmp-${process.pid}`;
+  await fs.writeFile(tmpPath, yaml, "utf-8");
+  await fs.rename(tmpPath, resolvedOut);
+
+  if (parsed.json) {
+    console.log(JSON.stringify({ wrote: resolvedOut, trigger, apiKeyEnvVar: parsed.apiKeyEnvVar, openPr: parsed.openPr }, null, 2));
+    return;
+  }
+
+  console.log(`Wrote ${resolvedOut}`);
+  console.log("");
+  console.log("Next steps:");
+  console.log(`  - Add '${parsed.apiKeyEnvVar}' as a repo secret: Settings -> Secrets and variables -> Actions.`);
+  if (trigger === "schedule") {
+    console.log("  - Scheduled workflows only run on the repo's default branch, and GitHub may");
+    console.log("    delay or skip scheduled runs on low-activity repos — this is documented");
+    console.log("    GitHub Actions behavior, not a bug in the generated workflow.");
+  }
+  console.log(`  - Commit and push ${resolvedOut} to enable it.`);
+}
+
+export async function runRoutineCommand(args: string[]): Promise<void> {
+  const sub = args[0];
+
+  if (sub === "-h" || sub === "--help") {
+    printUsage();
+    return;
+  }
+
+  if (sub === undefined) {
+    printUsage();
+    process.exitCode = 1;
+    return;
+  }
+
+  if (sub !== "init") {
+    console.log(`Unknown 'jeo routine' subcommand '${sub}'. Usage: jeo routine init [options]`);
+    process.exitCode = 1;
+    return;
+  }
+
+  await runInit(args.slice(1));
+}

package/src/commands/skills.ts

@@ -2,6 +2,7 @@ import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { SKILLS, getSkillFrom, formatSkill, loadSkills, skillDirs, bundledSkillFileContent, userSkillsDir } from "../skills/catalog";
 import { getLocalJeoDir } from "../agent/state";
+import { appendSkillLesson, evalSkillLessons, type SkillLesson } from "../agent/skill-lessons";
 
 export { userSkillsDir };
 
@@ -147,6 +148,62 @@ export async function runSkillsCommand(args: string[] = []): Promise<void> {
     return;
   }
 
+  // `jeo skills lesson <skill> <failure|anti-pattern> "<title>" "<detail>"` — manual
+  // lesson entry into the project-level skill file (the same compounding write the
+  // launch.ts stall-guard fires automatically; lets an agent or human record one directly).
+  if (cleanArgs[0] === "lesson") {
+    const [, skillName, kindArg, title, detail] = cleanArgs;
+    if (!skillName || !kindArg || !title || !detail) {
+      console.log('Usage: jeo skills lesson <skill> <failure|anti-pattern> "<title>" "<detail>"');
+      process.exitCode = 1;
+      return;
+    }
+    const kind: SkillLesson["kind"] | null =
+      kindArg === "failure" ? "failure-mode" : kindArg === "anti-pattern" ? "anti-pattern" : null;
+    if (!kind) {
+      console.log(`Error: kind must be 'failure' or 'anti-pattern' (got '${kindArg}').`);
+      process.exitCode = 1;
+      return;
+    }
+    const result = await appendSkillLesson(cwd, { skill: skillName, kind, title, detail });
+    if (isJson) {
+      console.log(JSON.stringify(result, null, 2));
+    } else if (result.appended) {
+      console.log("Appended.");
+    } else if (result.reason === "duplicate") {
+      console.log("Already recorded (duplicate).");
+    } else {
+      console.log(`Error: ${result.reason ?? "unknown error"}`);
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  // `jeo skills eval <skill>` — self-eval half: judge whether recorded lessons are
+  // still covered by the skill's current guidance, or have gone stale.
+  if (cleanArgs[0] === "eval") {
+    const skillName = cleanArgs[1];
+    if (!skillName) {
+      console.log("Error: Missing skill name for 'eval' command.");
+      process.exitCode = 1;
+      return;
+    }
+    const result = await evalSkillLessons(cwd, skillName);
+    if (result === null) {
+      console.log(`No recorded lessons for '${skillName}' yet.`);
+      return;
+    }
+    if (isJson) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(`${result.covered}/${result.total} lessons still covered by current guidance.`);
+      for (const s of result.stale) {
+        console.log(`  STALE  ${s.title}: ${s.reason}`);
+      }
+    }
+    return;
+  }
+
   // List/lookup over the MERGED set (bundled + ~/.jeo/skills + ~/.agents/skills + project dirs), matching the REPL /skill.
   const skills = await loadSkills(cwd);
   const command = cleanArgs[0];

package/src/util/provider-error.ts

@@ -117,6 +117,21 @@ export function friendlyProviderError(err: unknown): string {
   if (status === 401 || status === 403 || /\b40[13]\b/.test(msg)) {
     return `${provider} rejected the credential (HTTP ${status ?? "401/403"}). Run 'jeo auth status', re-login with /provider login <name>, and for Antigravity prefer '/provider login antigravity' (gemini login only works when the Cloud Code Assist backend authorizes that token).`;
   }
+  // A persistent 5xx (server-side fault on the provider's backend) — `ProviderHttpError`
+  // already embeds the numeric status directly in its message ("… failed (HTTP 500) …",
+  // caught here too, redundantly but harmlessly), but `ProviderStreamError` (the in-band
+  // SSE/stream error shape — antigravity.ts/gemini.ts's `google.rpc.Status` and
+  // openai-responses.ts's `response.failed`/`error` events) composes its `.message` from
+  // a STRING status code only ("Antigravity stream failed (INTERNAL): internal error"),
+  // never the numeric one, even though `.status` carries it correctly (explicitStatus
+  // for antigravity/gemini's google.rpc.Status `error.code`; the 500 default for
+  // openai-responses's non-rate_limit_exceeded codes). Without a digit anywhere in the
+  // text, launch.ts's `routeFailureReason` `/\b(?:500|502|503|504|529)\b/` text regex
+  // never matched, so the equivalent-pool fallback never fired for a stream-shaped 5xx
+  // even with a credentialed same-tier fallback sitting right there.
+  if (status !== undefined && status >= 500 && status < 600) {
+    return `${provider} hit a persistent server-side error (HTTP ${status}) — ${msg}. The provider's backend itself is failing; switch model with /model or wait and retry.`;
+  }
   if ((err instanceof Error && err.name === "TimeoutError") || /the operation timed out/i.test(msg)) {
     return `${provider} did not complete the request within the call timeout (default 30min). This is expected for a HIGH/XHIGH-reasoning-effort completion that legitimately runs long on a hard problem — raise JEO_CALL_TIMEOUT_MS (ms) if this recurs, or lower the thinking level with /model.`;
   }

package/src/util/retry.ts

@@ -5,8 +5,16 @@ export interface RetryOptions {
   isRetryable?: (err: unknown, attempt: number) => boolean;
   sleep?: (ms: number) => Promise<void>;   // injectable for tests (default real setTimeout)
   random?: () => number;   // injectable RNG for jitter (default Math.random); equal-jitter in [0.5x, 1x]
-  /** Notified before each backoff wait; `delayMs` is the wait actually applied. */
-  onRetry?: (attempt: number, err: unknown, delayMs: number) => void;
+  /** Notified before each backoff wait; `delayMs` is the wait actually applied.
+   *  Returning `false` (explicitly) aborts the retry ladder immediately — the
+   *  pending error is thrown right away instead of sleeping and re-attempting.
+   *  Lets a caller with a same-tier FALLBACK model available bail out of a
+   *  same-model rate-limit retry loop early rather than riding the full
+   *  `rateLimitRetries` budget (up to ~90s of escalating backoff) before the
+   *  turn-level equivalent-pool fallback ever gets a chance to switch models.
+   *  Any other return value (including `undefined`, the common case) continues
+   *  the retry ladder unchanged. */
+  onRetry?: (attempt: number, err: unknown, delayMs: number) => void | false;
   /** Aborts an in-progress backoff wait (e.g. Ctrl-C / turn cancel). Already-aborted or
    *  aborted-mid-wait rejects immediately instead of completing the sleep — the escape hatch
    *  for a long, honored provider `Retry-After` (see `rateLimitMaxServerDelayMs`: those are no
@@ -200,8 +208,11 @@ export async function withRetry<T>(fn: () => Promise<T>, opts?: RetryOptions): P
         : 0;
       const delay = Math.max(base, floor);
 
-      if (onRetry) {
-        onRetry(attempt, err, delay);
+      // A `false` return from onRetry means the caller wants to bail NOW instead of
+      // sleeping and re-attempting (see RetryOptions.onRetry's doc comment) — throw
+      // the pending error immediately rather than entering the backoff wait.
+      if (onRetry && onRetry(attempt, err, delay) === false) {
+        throw err;
       }
 
       await abortableSleep(sleep, delay, signal);