nightralph 0.0.27 → 0.0.31

package/README.md

@@ -26,12 +26,18 @@ so they can't drift as long as you install the skills with this package.
 - [Workflow](#workflow)
   * [Create Issues](#create-issues)
   * [Examples](#examples)
+  * [Interface](#interface)
+    + [`--spec ` option](#--spec--option)
 - [How It Works](#how-it-works)
   * [Select a ticket](#select-a-ticket)
   * [Worktrees](#worktrees)
   * [Progress](#progress)
 - [Keep Your Machine Awake](#keep-your-machine-awake)
   * [Mac OS](#mac-os)
+    + [Claude Opus 4.6](#claude-opus-46)
+    + [Claude Sonnet 5](#claude-sonnet-5)
+    + [`pi` + OpenRouter model](#pi--openrouter-model)
+    + [`codex` + Luna](#codex--luna)
 
 <!-- tocstop -->
 
@@ -107,7 +113,6 @@ before a ticket can be marked `done`.
 > then follow with `to-tickets`.
 >
 
-
 ### Examples
 
 After you have the tickets, use the `nightralph` loop to execute.
@@ -124,6 +129,9 @@ npx nightralph pi -m openrouter/z-ai/glm-5.3-flash
 # Dry run to inspect the dependency graph and prompt
 npx nightralph codex --dry-run
 
+# Use codex with a specific model
+npx nightralph codex -m gpt-5.6-luna
+
 # Specify a feature by name
 npx nightralph claude -m claude-opus-4-6 --spec my-feature
 
@@ -133,15 +141,11 @@ npx nightralph claude -m claude-opus-4-6 --max-turns 30
 # Same thing, using the positional shorthand
 npx nightralph claude -m claude-opus-4-6 30
 
-# Start pi at medium thinking and allow one escalated retry
-npx nightralph pi -m openrouter/z-ai/glm-5.3-flash --thinking medium --retries 1
+# Start pi at medium effort and allow one escalated retry
+npx nightralph pi -m openrouter/z-ai/glm-5.3-flash --effort medium --retries 1
 ```
 
-#### `--spec <name>` option
-
-A feature name that resolves to `.scratch/<name>/`.
-The spec file is `.scratch/<name>/spec.md` and the issues directory
-is `.scratch/<name>/issues/`.
+### Interface
 
 Flags:
 
@@ -156,8 +160,8 @@ Flags:
 | `--timeout` | no | `3600` | Kill the agent after N seconds. A killed agent is not a failure: its work is kept (see Notes) |
 | `--test-cmd <cmd>` | no | auto | Run in each worktree after the agent exits; non-zero exit rejects the ticket. Auto-detects `npm test`. Pass `""` to disable. Shares the agent's `--timeout`. The command runs in a fresh git worktree, which contains only tracked files, so a project that needs an install step should include it, for example `--test-cmd 'npm ci && npm test'` |
 | `--max-turns <n>` | no | -- | Max agentic turns per ticket. Forwarded verbatim as `--max-turns <n>` to the provider CLI. Only `claude` accepts it; `codex` and `pi` reject it as an unknown option and the agent exits immediately. Applies to every agent spawn, including a re-spawn after a merge conflict. When omitted, `claude` applies no turn limit, so `--timeout` is the only cap. Reaching the limit is an error exit, so the ticket is recorded as failed |
-| `--thinking <level>` | no | -- | Starting thinking level for `pi`, one of `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. Forwarded as `--thinking <level>`. Omitted = pi's own default. Ignored for other providers. Each retry steps up from here (see `--retries`) |
-| `--retries <n>` | no | `2` | Extra attempts per ticket after a failed run. Each retry starts from a fresh worktree; with `pi` it also raises the thinking level (see Notes). `0` disables retries |
+| `--effort <level>` | no | -- | Starting effort/reasoning level. Each provider has its own ladder: `claude` supports `low`, `medium`, `high`, `xhigh`, `max` (forwarded as `--effort`); `codex` supports `low`, `medium`, `high` (forwarded as `-c model_reasoning_effort=<level>`); `pi` supports `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` (forwarded as `--thinking`). Omitted = provider default. Each retry steps up from here (see `--retries`) |
+| `--retries <n>` | no | `3` | Extra attempts per ticket after a failed run. Each retry starts from a fresh worktree and raises the effort level one rung (see Notes). `0` disables retries |
 | `--retry-delay <n>` | no | `30` | Seconds to wait before the first retry; doubles each further retry (30s, 60s, 120s, ...). `0` disables the wait |
 
 
@@ -185,15 +189,15 @@ Flags:
   ticket is recorded as failed. Non-zero exit, exit 0 with no new
   commits, and a red test command all count as failures; a timeout
   does not (see below). Each retry discards the previous worktree
-  and starts from a fresh one. With `pi`, each retry raises the
-  thinking level: without `--thinking` the first retry uses `high`
-  and the second `max`; with `--thinking <level>` each retry steps
-  one level up from the previous attempt, stopping at `max`.
-  `claude` and `codex` are retried at the same settings. Retries
-  are spaced with exponential backoff controlled by `--retry-delay`:
-  the first retry waits `--retry-delay` seconds, the second waits
-  double that, and so on. This lets provider outages clear before
-  burning the next attempt. Retry
+  and starts from a fresh one. Each retry also raises the effort
+  level one rung up the provider's ladder: without `--effort` the
+  first retry uses `high`; with `--effort <level>` each retry
+  steps one level up from the previous attempt, stopping at the
+  provider's max (`max` for claude/pi, `high` for codex).
+  Retries are spaced with exponential backoff controlled by
+  `--retry-delay`: the first retry waits `--retry-delay` seconds,
+  the second waits double that, and so on. This lets provider
+  outages clear before burning the next attempt. Retry
   logs are written to `<dir>/../logs/<ticket>.attempt<n>.log`
   (and `.attempt<n>.test.log` for the test command) so the first
   attempt's log is kept.
@@ -237,6 +241,13 @@ Flags:
     tool-use proposals so the agent runs non-interactively)
 
 
+#### `--spec <name>` option
+
+A feature name that resolves to `.scratch/<name>/`.
+The spec file is `.scratch/<name>/spec.md` and the issues directory
+is `.scratch/<name>/issues/`.
+
+
 ## How It Works
 
 All currently eligible tickets are grouped into a

package/dist/index.js

@@ -1359,7 +1359,26 @@ function getProviderArgs(cmd) {
   return PROVIDER_ARGS[name] ?? [];
 }
 __name(getProviderArgs, "getProviderArgs");
-var THINKING_LEVELS = [
+var EFFORT_LADDERS = {
+  pi: [
+    "off",
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+    "max"
+  ],
+  claude: [
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+    "max"
+  ],
+  codex: ["low", "medium", "high"]
+};
+var ALL_EFFORT_LEVELS = [
   "off",
   "minimal",
   "low",
@@ -1368,12 +1387,14 @@ var THINKING_LEVELS = [
   "xhigh",
   "max"
 ];
-function escalateThinking(level) {
+function escalateEffort(provider, level) {
   if (!level) return "high";
-  const i = THINKING_LEVELS.indexOf(level);
-  return THINKING_LEVELS[Math.min(i + 1, THINKING_LEVELS.length - 1)];
+  const ladder = EFFORT_LADDERS[provider];
+  const i = ladder.indexOf(level);
+  if (i === -1) return level;
+  return ladder[Math.min(i + 1, ladder.length - 1)];
 }
-__name(escalateThinking, "escalateThinking");
+__name(escalateEffort, "escalateEffort");
 function formatStreamLine(line) {
   let obj;
   try {
@@ -1509,14 +1530,39 @@ function spawnAgent(opts) {
   if (opts.model) {
     args.push("--model", opts.model);
   }
-  if (opts.maxTurns) {
-    args.push("--max-turns", String(opts.maxTurns));
-  }
   const providerName = basename2(opts.agentCmd);
   const isClaude = providerName === "claude";
   const isPi = providerName === "pi";
-  if (isPi && opts.thinking) {
-    args.push("--thinking", opts.thinking);
+  if (opts.maxTurns) {
+    if (isClaude) {
+      args.push(
+        "--max-turns",
+        String(opts.maxTurns)
+      );
+    } else if (opts.onLine) {
+      opts.onLine(
+        `Warning: --max-turns not supported by ${providerName}, skipping`
+      );
+    }
+  }
+  if (opts.effort && providerName in EFFORT_LADDERS) {
+    const ladder = EFFORT_LADDERS[providerName];
+    if (!ladder.includes(opts.effort)) {
+      if (opts.onLine) {
+        opts.onLine(
+          `Warning: effort '${opts.effort}' not supported by ${providerName}, skipping`
+        );
+      }
+    } else if (isPi) {
+      args.push("--thinking", opts.effort);
+    } else if (isClaude) {
+      args.push("--effort", opts.effort);
+    } else if (providerName === "codex") {
+      args.push(
+        "-c",
+        `model_reasoning_effort=${opts.effort}`
+      );
+    }
   }
   const prefix = opts.label ? `  [${opts.label}] ` : "  ";
   let promptFile = null;
@@ -1747,7 +1793,7 @@ Prompt for first ready ticket (${firstReady[0].filename}):
 Test command: ${opts.testCmd ?? "(none)"}`
   );
   console.log(
-    `Thinking:     ${opts.thinking ?? "(provider default)"}`
+    `Effort:       ${opts.effort ?? "(provider default)"}`
   );
   console.log(
     `Retries:      ${opts.retries ?? DEFAULT_RETRIES}`
@@ -1876,7 +1922,7 @@ async function respawnAndRetryMerge(opts) {
   return mergeResult.success;
 }
 __name(respawnAndRetryMerge, "respawnAndRetryMerge");
-var DEFAULT_RETRIES = 2;
+var DEFAULT_RETRIES = 3;
 var DEFAULT_RETRY_DELAY = 30;
 function retryDelayFor(base, attempt) {
   return base * 2 ** (attempt - 2);
@@ -1924,7 +1970,7 @@ async function runTicketAttempt(opts) {
     cwd: worktree.worktreePath,
     label: ticket.filename.replace(/\.md$/, ""),
     maxTurns: opts.maxTurns,
-    thinking: opts.thinking,
+    effort: opts.effort,
     onLine: /* @__PURE__ */ __name((line) => d.log(line), "onLine")
   });
   if (agentResult.timedOut) {
@@ -2003,8 +2049,9 @@ __name(runTicketAttempt, "runTicketAttempt");
 async function runTicketAttempts(opts) {
   const { ticket, d } = opts;
   const maxAttempts = opts.retries + 1;
-  const isPi = basename2(opts.agentCmd) === "pi";
-  let thinking = opts.thinking;
+  const providerName = basename2(opts.agentCmd);
+  const isKnown = providerName in EFFORT_LADDERS;
+  let effort = opts.effort;
   let outcome = {
     kind: "no-commits",
     worktreePath: "",
@@ -2014,10 +2061,15 @@ async function runTicketAttempts(opts) {
     if (attempt === 1) {
       d.log(`  Starting ${ticket.filename}`);
     } else {
-      thinking = escalateThinking(thinking);
+      if (isKnown) {
+        effort = escalateEffort(
+          providerName,
+          effort
+        );
+      }
       const delay = retryDelayFor(opts.retryDelay, attempt);
       d.log(
-        `  ${ticket.filename}: retrying (attempt ${attempt}/${maxAttempts}` + (isPi ? `, thinking ${thinking}` : "") + (delay > 0 ? `, waiting ${delay}s` : "") + ")"
+        `  ${ticket.filename}: retrying (attempt ${attempt}/${maxAttempts}` + (isKnown && effort ? `, effort ${effort}` : "") + (delay > 0 ? `, waiting ${delay}s` : "") + ")"
       );
       if (delay > 0) await sleep(delay * 1e3);
     }
@@ -2025,7 +2077,7 @@ async function runTicketAttempts(opts) {
       outcome = await runTicketAttempt({
         ...opts,
         attempt,
-        thinking
+        effort
       });
     } catch (error) {
       d.log(
@@ -2058,12 +2110,13 @@ function runProgress(tickets) {
   };
 }
 __name(runProgress, "runProgress");
-async function runWaves(tickets, specBody, agentCmd, model, timeout, logsDir, display, maxTurns, thinking, retries, retryDelay) {
+async function runWaves(tickets, specBody, agentCmd, model, timeout, logsDir, display, maxTurns, effort, retries, retryDelay) {
   mkdirSync2(logsDir, { recursive: true });
   const d = display ?? createDisplay();
   const maxAttempts = (retries ?? DEFAULT_RETRIES) + 1;
   const delayBase = retryDelay ?? 0;
-  const isPi = basename2(agentCmd) === "pi";
+  const providerName = basename2(agentCmd);
+  const isKnown = providerName in EFFORT_LADDERS;
   let totalWaves = 0;
   for (const _ of simulateWaves(tickets)) totalWaves++;
   let totalCompleted = 0;
@@ -2101,7 +2154,7 @@ async function runWaves(tickets, specBody, agentCmd, model, timeout, logsDir, di
         );
         d.setTicketStatus(t.num, "in-progress");
         d.log(`  Starting ${t.filename}`);
-        let level = thinking;
+        let level = effort;
         let result = await spawnAgent({
           prompt,
           agentCmd,
@@ -2110,14 +2163,19 @@ async function runWaves(tickets, specBody, agentCmd, model, timeout, logsDir, di
           logPath: attemptLogPath(logsDir, t, 1, ".log"),
           label,
           maxTurns,
-          thinking: level,
+          effort: level,
           onLine: /* @__PURE__ */ __name((line) => d.log(line), "onLine")
         });
         for (let attempt = 2; result.exitCode !== 0 && !result.timedOut && attempt <= maxAttempts; attempt++) {
-          level = escalateThinking(level);
+          if (isKnown) {
+            level = escalateEffort(
+              providerName,
+              level
+            );
+          }
           const delay = retryDelayFor(delayBase, attempt);
           d.log(
-            `  ${t.filename}: agent exited ${result.exitCode}; retrying (attempt ${attempt}/${maxAttempts}` + (isPi ? `, thinking ${level}` : "") + (delay > 0 ? `, waiting ${delay}s` : "") + ")"
+            `  ${t.filename}: agent exited ${result.exitCode}; retrying (attempt ${attempt}/${maxAttempts}` + (isKnown && level ? `, effort ${level}` : "") + (delay > 0 ? `, waiting ${delay}s` : "") + ")"
           );
           if (delay > 0) await sleep(delay * 1e3);
           result = await spawnAgent({
@@ -2133,7 +2191,7 @@ async function runWaves(tickets, specBody, agentCmd, model, timeout, logsDir, di
             ),
             label,
             maxTurns,
-            thinking: level,
+            effort: level,
             onLine: /* @__PURE__ */ __name((line) => d.log(line), "onLine")
           });
         }
@@ -2251,7 +2309,7 @@ async function runWavesIsolated(opts) {
         logsDir: opts.logsDir,
         testCmd: opts.testCmd,
         maxTurns: opts.maxTurns,
-        thinking: opts.thinking,
+        effort: opts.effort,
         retries,
         retryDelay,
         d
@@ -2662,14 +2720,14 @@ yargs(hideBin(process.argv)).scriptName("nightralph").usage("$0 <command>").comm
   }).option("max-turns", {
     type: "number",
     describe: "Max agentic turns per ticket (forwarded to the agent CLI)"
-  }).option("thinking", {
+  }).option("effort", {
     type: "string",
-    choices: THINKING_LEVELS,
-    describe: "Starting thinking level for the pi provider. Omitted = pi's default. Retries step up from here."
+    choices: ALL_EFFORT_LEVELS,
+    describe: "Starting effort level. Omitted = provider default. Retries step up from here."
   }).option("retries", {
     type: "number",
     default: DEFAULT_RETRIES,
-    describe: "Extra attempts per ticket after a failed run, each with a higher thinking level (pi). 0 disables retries."
+    describe: "Extra attempts per ticket after a failed run, each with a higher effort level. 0 disables retries."
   }).option("retry-delay", {
     type: "number",
     default: DEFAULT_RETRY_DELAY,
@@ -2685,7 +2743,7 @@ yargs(hideBin(process.argv)).scriptName("nightralph").usage("$0 <command>").comm
       testCmd: argv.testCmd,
       stopOnConflict: argv.X,
       maxTurns: argv.maxTurns ?? argv.turns,
-      thinking: argv.thinking,
+      effort: argv.effort,
       retries: argv.retries,
       retryDelay: argv.retryDelay
     });
@@ -2768,7 +2826,7 @@ async function runExecute(argv) {
         conflictStrategy,
         progressPath,
         testCmd,
-        thinking: argv.thinking,
+        effort: argv.effort,
         retries: argv.retries,
         retryDelay: argv.retryDelay
       });
@@ -2800,7 +2858,7 @@ async function runExecute(argv) {
       display,
       testCmd,
       maxTurns: argv.maxTurns,
-      thinking: argv.thinking,
+      effort: argv.effort,
       retries: argv.retries,
       retryDelay: argv.retryDelay
     });
@@ -2814,7 +2872,7 @@ async function runExecute(argv) {
       logsDir,
       display,
       argv.maxTurns,
-      argv.thinking,
+      argv.effort,
       argv.retries,
       argv.retryDelay
     );