jules-orchestrator-kit 0.69.0 → 0.71.0

package/src/session-ops.mjs

@@ -31,6 +31,106 @@ export function parseAgeDuration(duration) {
   }
 }
 
+/**
+ * Output shapes that mean "this command failed" even when the runner exited 0.
+ *
+ * Kept deliberately narrow: this list is only consulted for a `bashOutput`
+ * whose `exitCode` is `0` or absent, where the alternative is reporting
+ * nothing at all. A false positive here costs a few hundred characters of
+ * retry prompt; a false negative costs the retry its only evidence.
+ */
+const BASH_FAILURE_HINTS = [
+  /(^|\n)\s*not ok\b/i,
+  /(^|\n)# fail [1-9]/i,
+  /\b[1-9]\d* failed\b/i,
+  /\b[1-9]\d* failing\b/i,
+  /\bAssertionError\b/,
+  /\bFAILED\b/,
+  /\bTraceback \(most recent call last\)/,
+  /\bpanic: /,
+  /\berror:/i,
+];
+
+/**
+ * Collects the diagnostics a session actually carries.
+ *
+ * The documented Activity type — the Jules API types reference, transcribed
+ * in `docs/jules-quality-plan.md` — puts command output under
+ * `artifacts[].bashOutput.{command,output,exitCode}` and the failure reason
+ * under `sessionFailed.reason`. Neither `act.error` nor `act.executionOutput`
+ * — the only two fields this file used to read — exists in that schema, so a
+ * real failure came back as the generic fallback sentence and the retry session
+ * was dispatched without the assertion it existed to fix.
+ *
+ * Blocks are returned highest-signal first, because `retrySession` truncates
+ * the joined result to 4000 characters from the front: the ordering decides
+ * which evidence survives the cut.
+ *
+ * The legacy spellings are still read. They cost nothing, and an unrecognised
+ * provider shape that does carry an error is better served by it than by the
+ * fallback sentence.
+ *
+ * @param {Array<object>} activities - Activities as returned by `listActivities`.
+ * @returns {Array<{ source: string, text: string }>} Highest-signal first.
+ */
+export function extractFailureDiagnostics(activities) {
+  const list = Array.isArray(activities) ? activities : [];
+  const failingBash = [];
+  const failureReasons = [];
+  const suspiciousBash = [];
+  const legacy = [];
+  const agentNotes = [];
+  const seen = new Set();
+
+  const push = (bucket, source, text) => {
+    const clean = String(text ?? "").trim();
+    if (!clean) return;
+    const key = `${source}\u0000${clean}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    bucket.push({ source, text: clean });
+  };
+
+  for (const act of list) {
+    if (!act || typeof act !== "object") continue;
+
+    const artifacts = Array.isArray(act.artifacts) ? act.artifacts : [];
+    for (const art of artifacts) {
+      const bash = art && typeof art === "object" ? art.bashOutput : null;
+      if (!bash || typeof bash !== "object") continue;
+      const command = typeof bash.command === "string" ? bash.command : "";
+      const output = typeof bash.output === "string" ? bash.output : "";
+      if (!command && !output) continue;
+      const rendered = `$ ${command || "(unknown command)"}\n${output || "(no output)"}`;
+      const exitCode = bash.exitCode;
+      if (typeof exitCode === "number" && exitCode !== 0) {
+        push(failingBash, "bashOutput", `${rendered}\n(exit code ${exitCode})`);
+      } else if (BASH_FAILURE_HINTS.some((re) => re.test(output))) {
+        const codeNote = typeof exitCode === "number" ? String(exitCode) : "not reported";
+        push(suspiciousBash, "bashOutput", `${rendered}\n(exit code ${codeNote})`);
+      }
+    }
+
+    const failed = act.sessionFailed && typeof act.sessionFailed === "object" ? act.sessionFailed : null;
+    if (failed && typeof failed.reason === "string") {
+      push(failureReasons, "sessionFailed", failed.reason);
+    }
+
+    if (act.error) {
+      push(legacy, "legacy.error", typeof act.error === "string" ? act.error : JSON.stringify(act.error));
+    }
+    if (act.executionOutput && (act.exitCode !== 0 || act.status === "FAILED")) {
+      push(legacy, "legacy.executionOutput", act.executionOutput);
+    }
+
+    if (act.originator === "agent" && typeof act.description === "string") {
+      push(agentNotes, "agentMessage", act.description);
+    }
+  }
+
+  return [...failingBash, ...failureReasons, ...suspiciousBash, ...legacy, ...agentNotes];
+}
+
 /**
  * Extracts git diff patch, PR details, and modified files from a Jules session.
  *
@@ -213,7 +313,7 @@ export async function applySessionPatch(sessionId, opts = {}) {
  *
  * @param {string} sessionId
  * @param {object} opts
- * @returns {Promise<{ ok: boolean, originalSessionId: string, newSession: object, failureReason: string }>}
+ * @returns {Promise<{ ok: boolean, originalSessionId: string, newSession: object, failureReason: string, diagnosticsFound: number, diagnosticSources: string[] }>}
  */
 export async function retrySession(sessionId, opts = {}) {
   if (!sessionId || typeof sessionId !== "string") {
@@ -227,18 +327,19 @@ export async function retrySession(sessionId, opts = {}) {
   const activitiesRes = await provider.listActivities(sessionId, opts).catch(() => ({ activities: [] }));
   const activities = activitiesRes.activities || [];
 
-  // Extract failure diagnostics
-  const errors = [];
-  for (const act of activities) {
-    if (act.error) errors.push(typeof act.error === "string" ? act.error : JSON.stringify(act.error));
-    if (act.executionOutput && (act.exitCode !== 0 || act.status === "FAILED")) {
-      errors.push(act.executionOutput);
-    }
-  }
+  // Extract failure diagnostics. `extractFailureDiagnostics` reads the fields
+  // the API actually documents (artifacts[].bashOutput, sessionFailed.reason)
+  // and returns them highest-signal first, so the 4000-character cut below
+  // drops the least useful evidence rather than the assertion that failed.
+  const diagnostics = extractFailureDiagnostics(activities);
 
   const rawPrompt = session?.raw?.prompt || session?.prompt || "";
   const title = session?.raw?.title || `Retry of Session ${sessionId}`;
-  const failureReason = errors.join("\n").slice(0, 4000) || "Previous session did not complete cleanly.";
+  const failureReason =
+    diagnostics
+      .map((d) => d.text)
+      .join("\n")
+      .slice(0, 4000) || "Previous session did not complete cleanly.";
 
   let synthesizedPrompt = rawPrompt;
   if (opts.withFailure !== false && failureReason) {
@@ -264,6 +365,12 @@ export async function retrySession(sessionId, opts = {}) {
     originalSessionId: sessionId,
     newSession: dispatchRes,
     failureReason,
+    // Non-zero only when the session carried evidence the retry could act on.
+    // A zero here with a non-empty `failureReason` means the fallback sentence
+    // was sent — the distinction the CLI and any telemetry need, because the
+    // two look identical in `failureReason` alone.
+    diagnosticsFound: diagnostics.length,
+    diagnosticSources: diagnostics.map((d) => d.source),
   };
 }
 

package/src/stack-detector.mjs

@@ -1,6 +1,7 @@
 import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync } from "node:fs";
 import { join, relative } from "node:path";
 import { whichBinary } from "./provider-readiness.mjs";
+import { yamlScalar } from "./config.mjs";
 
 /**
  * The Python interpreter to invoke, by whatever name this machine has it under.
@@ -31,11 +32,48 @@ function pythonBin(env = process.env) {
  * Falls back to the bare console script only when no interpreter can be found
  * to host the module.
  */
-export function pytestCmd(env = process.env) {
+export function pytestCmd(env = process.env, root = null) {
+  const prefix = root && isSrcLayout(root) ? "PYTHONPATH=src " : "";
   for (const name of ["python3", "python", "py"]) {
-    if (whichBinary(name, env)) return `${name} -m pytest`;
+    if (whichBinary(name, env)) return `${prefix}${name} -m pytest`;
+  }
+  return `${prefix}pytest`;
+}
+
+/**
+ * Does this repository keep its package under `src/` rather than at the root?
+ *
+ * The sibling of the bug above, and a worse one. `-m` puts the *working
+ * directory* on `sys.path` — which is the fix for a module at the root, and
+ * no help at all when the package lives in `src/`. There, `import iniconfig`
+ * finds nothing in the working directory and falls through to whatever is
+ * installed in site-packages. The suite then runs green against a *different
+ * copy of the library than the one in the diff*: measured on `pytest-dev/
+ * iniconfig`, `_parse.py` gutted to `return False`, 49 tests passed, and the
+ * gate returned APPROVED (Exit 0).
+ *
+ * That is this project's worst failure shape — a check that examined
+ * something other than the thing under review, reporting a pass — and no
+ * amount of counting collected tests can see it, because the tests really
+ * did run. Only the import path can.
+ *
+ * `PYTHONPATH=src` is the ordinary spelling and puts the working tree first
+ * whether or not the package is also installed. Leading assignments are
+ * peeled into the child's environment by `runCommand`, so this needs no shell.
+ *
+ * Keyed on `__init__.py` under `src/`, which is the marker of a Python
+ * package and not of a Rust, C or JavaScript `src/` directory.
+ */
+export function isSrcLayout(root) {
+  const src = join(root, "src");
+  if (!existsSync(src)) return false;
+  try {
+    return readdirSync(src, { withFileTypes: true }).some(
+      (e) => e.isDirectory() && existsSync(join(src, e.name, "__init__.py"))
+    );
+  } catch (_) {
+    return false;
   }
-  return "pytest";
 }
 
 /**
@@ -234,7 +272,7 @@ export function oracleCandidates(root = process.cwd(), detected = "") {
     } catch (_) {}
   }
   if (has("pytest.ini") || has("pyproject.toml") || has("setup.py") || has("tox.ini") || has("setup.cfg")) {
-    push(pytestCmd());
+    push(pytestCmd(process.env, root));
   }
   if (has("Cargo.toml")) push("cargo test");
   if (has("go.mod")) push("go test ./...");
@@ -386,7 +424,7 @@ export function detectPolyglotStack(projectRoot = process.cwd()) {
   }
   if (existsSync(join(projectRoot, "pyproject.toml")) || existsSync(join(projectRoot, "requirements.txt")) || existsSync(join(projectRoot, "setup.py"))) {
     const triggerFile = existsSync(join(projectRoot, "pyproject.toml")) ? "pyproject.toml" : existsSync(join(projectRoot, "requirements.txt")) ? "requirements.txt" : "setup.py";
-    return { ...container, stack: "python", testCmd: pytestCmd(), buildCmd: `${pythonBin()} -m compileall -q .`, triggerFile };
+    return { ...container, stack: "python", testCmd: pytestCmd(process.env, projectRoot), buildCmd: `${pythonBin()} -m compileall -q .`, triggerFile };
   }
   if (existsSync(join(projectRoot, "mix.exs"))) {
     return { ...container, stack: "mix", testCmd: "mix test", buildCmd: "mix compile", triggerFile: "mix.exs" };
@@ -470,7 +508,7 @@ export function detectPolyglotStack(projectRoot = process.cwd()) {
     }
     const pyFile = rootFiles.find((f) => f.endsWith(".py"));
     if (pyFile) {
-      return { ...container, stack: "python", testCmd: pytestCmd(), buildCmd: `${pythonBin()} -m compileall -q .`, triggerFile: pyFile };
+      return { ...container, stack: "python", testCmd: pytestCmd(process.env, projectRoot), buildCmd: `${pythonBin()} -m compileall -q .`, triggerFile: pyFile };
     }
   } catch (_) {}
 
@@ -966,19 +1004,19 @@ export function bootstrapZeroTestRepo(root = process.cwd(), options = {}) {
     try {
       let rawConfig = readFileSync(configPath, "utf-8");
       if (/^\s*test:\s*.*$/m.test(rawConfig)) {
-        rawConfig = rawConfig.replace(/^\s*test:\s*.*$/m, `  test: "${testCmd}"`);
+        rawConfig = rawConfig.replace(/^\s*test:\s*.*$/m, () => `  test: ${yamlScalar(testCmd)}`);
       } else if (/^\s*verify:\s*$/m.test(rawConfig)) {
-        rawConfig = rawConfig.replace(/^\s*verify:\s*$/m, `verify:\n  test: "${testCmd}"`);
+        rawConfig = rawConfig.replace(/^\s*verify:\s*$/m, () => `verify:\n  test: ${yamlScalar(testCmd)}`);
       } else {
-        rawConfig += `\nverify:\n  test: "${testCmd}"\n`;
+        rawConfig += `\nverify:\n  test: ${yamlScalar(testCmd)}\n`;
       }
       if (detected.buildCmd && /^\s*build:\s*["']?["']?\s*$/m.test(rawConfig)) {
-        rawConfig = rawConfig.replace(/^\s*build:\s*.*$/m, `  build: "${detected.buildCmd}"`);
+        rawConfig = rawConfig.replace(/^\s*build:\s*.*$/m, () => `  build: ${yamlScalar(detected.buildCmd)}`);
       }
       writeFileSync(configPath, rawConfig, "utf-8");
     } catch (_) {}
   } else {
-    const cfg = `version: 1\nprovider: jules\ntier: free\nverify:\n  test: "${testCmd}"\n  build: "${detected.buildCmd || ""}"\nlimits:\n  diff_kb: 75\n  daily_tasks: 15\n  repair_attempts: 3\nbranch_prefix: agent/\nbase_branch: main\n`;
+    const cfg = `version: 1\nprovider: jules\ntier: free\nverify:\n  test: ${yamlScalar(testCmd)}\n  build: ${yamlScalar(detected.buildCmd || "")}\nlimits:\n  diff_kb: 75\n  daily_tasks: 15\n  repair_attempts: 3\nbranch_prefix: agent/\nbase_branch: main\n`;
     writeFileSync(configPath, cfg, "utf-8");
   }
 
@@ -987,12 +1025,12 @@ export function bootstrapZeroTestRepo(root = process.cwd(), options = {}) {
     try {
       let rawJules = readFileSync(julesPath, "utf-8");
       if (/^\s*test_cmd:\s*.*$/m.test(rawJules)) {
-        rawJules = rawJules.replace(/^\s*test_cmd:\s*.*$/m, `test_cmd: "${testCmd}"`);
+        rawJules = rawJules.replace(/^\s*test_cmd:\s*.*$/m, () => `test_cmd: ${yamlScalar(testCmd)}`);
       } else {
-        rawJules += `\ntest_cmd: "${testCmd}"\n`;
+        rawJules += `\ntest_cmd: ${yamlScalar(testCmd)}\n`;
       }
       if (detected.buildCmd && /^\s*build_cmd:\s*["']?["']?\s*$/m.test(rawJules)) {
-        rawJules = rawJules.replace(/^\s*build_cmd:\s*.*$/m, `build_cmd: "${detected.buildCmd}"`);
+        rawJules = rawJules.replace(/^\s*build_cmd:\s*.*$/m, () => `build_cmd: ${yamlScalar(detected.buildCmd)}`);
       }
       writeFileSync(julesPath, rawJules, "utf-8");
     } catch (_) {}

package/src/wizard-init.mjs

@@ -1,12 +1,12 @@
 import { existsSync, readFileSync, writeFileSync, openSync, fsyncSync, closeSync, renameSync, mkdirSync, readdirSync } from "node:fs";
 import { join } from "node:path";
-import { parseYaml, TIER_PRESETS, VENDOR_TIERS, FALLBACK_TIER } from "./config.mjs";
+import { parseYaml, yamlScalar, TIER_PRESETS, VENDOR_TIERS, FALLBACK_TIER } from "./config.mjs";
 import { suggestProvider, detectAvailableProviders } from "./provider-readiness.mjs";
 import { detectDefaultBranch } from "./git.mjs";
 import { resolveWorkspaceBoundary, oracleCandidates } from "./stack-detector.mjs";
 import { PROFILE_NAMES, PROFILE_DESCRIPTIONS } from "./profiles.mjs";
 import { detectStackOracles, runVerificationProbe } from "./wizard-oracle.mjs";
-import { parseCollectedTests } from "./ops/test-collection.mjs";
+import { parseCollectedTests, producedNoOutput, looksLikeTestSuiteCommand } from "./ops/test-collection.mjs";
 import { select, multiSelect, input, confirm, spinner, isTTY } from "./tui.mjs";
 import { KIT_VERSION } from "./version.mjs";
 
@@ -201,6 +201,19 @@ export function planInit(root = process.cwd(), options = {}) {
     ? `\nlimits:\n  concurrency: ${limits.concurrency}\n  daily_tasks: ${limits.daily_tasks}\n  stagger_ms: ${limits.stagger_ms}\n  diff_kb: ${limits.diff_kb}\n`
     : "";
 
+  // A generated comment must not begin with an ESLint directive keyword.
+  //
+  // `global`, `globals`, `exported`, `eslint`, `eslint-disable` and friends are
+  // configuration when they open a comment — in any language ESLint has a
+  // parser for, YAML included. This template began a line with "global runs
+  // the ...", which ESLint read as `/* global runs, the, ... */`: a declaration
+  // of globals named after each word of the sentence. Measured on
+  // `unjs/unimport`, that produced 18 `no-unused-vars` errors quoting
+  // individual English words back at the user, on a file `init` had written
+  // thirty seconds earlier.
+  //
+  // The word is unavoidable — `global` is the name of the setting being
+  // explained — so the sentence leads with the key instead.
   const configYaml = `# Agent Orchestrator Kit Config (v${KIT_VERSION})
 # provider: jules | claude-code | codex | gemini-flash  (agentctl providers)
 version: 1
@@ -212,16 +225,16 @@ ${limitsBlock}
 verify:
   # minimal | standard | max  — see: agentctl profile --list
   profile: ${profile}
-  # global runs the repository's own commands; affected resolves changed files
-  # to their sub-projects and runs only those suites (monorepos)
+  # scope: global runs the commands this repository declares; affected
+  # resolves changed files to their sub-projects, running only those suites
   scope: ${verifyScope}
-  test: "${verify.test}"
+  test: ${yamlScalar(verify.test)}
   # How long a verification stage may run before the gate kills it (default
   # 300000). Raise it for a suite that legitimately takes longer.
   timeout_ms: 300000
-  build: "${verify.build}"
-  lint: "${verify.lint}"
-  typecheck: "${verify.typecheck}"
+  build: ${yamlScalar(verify.build)}
+  lint: ${yamlScalar(verify.lint)}
+  typecheck: ${yamlScalar(verify.typecheck)}
 
 presets:
 ${selectedPresets.map((p) => `  - ${p}`).join("\n")}
@@ -246,11 +259,11 @@ ${selectedPresets.map((p) => `  - ${p}`).join("\n")}
 
   const julesYaml = `# Google Jules Repository Configuration (Version 2)
 version: 2
-test_cmd: "${verify.test}"
-build_cmd: "${verify.build}"
+test_cmd: ${yamlScalar(verify.test)}
+build_cmd: ${yamlScalar(verify.build)}
 forbidden_paths:
-${forbiddenPaths.map((p) => `  - "${p}"`).join("\n")}
-allow_paths: ${allowPaths.length > 0 ? "\n" + allowPaths.map((p) => `  - "${p}"`).join("\n") : "[]"}
+${forbiddenPaths.map((p) => `  - ${yamlScalar(p)}`).join("\n")}
+allow_paths: ${allowPaths.length > 0 ? "\n" + allowPaths.map((p) => `  - ${yamlScalar(p)}`).join("\n") : "[]"}
 `;
 
   return {
@@ -330,8 +343,18 @@ export function loadPresets(root = process.cwd()) {
  * cost of rejecting a candidate is trying the next one, where at gate time it
  * would be a hard red on a repository that is fine.
  */
-function probeVerdict(probeRes) {
+function probeVerdict(probeRes, cmd) {
   if (!probeRes.ok) return "failed";
+  // Writing nothing at all is `empty`, not `silent`. The distinction is the
+  // whole point: `silent` is the forgiving bucket that keeps a command the
+  // guard could not read, and `pnpm -r test` landed in it because it prints
+  // no output to be unreadable. So the candidate this verdict was introduced
+  // to reject was the one case it waved through, and every repository
+  // scaffolded on such a workspace kept it.
+  // Same rule as the gate's floor, from the same predicate: a command that
+  // claims to run a suite and printed nothing ran none. A static gate that
+  // printed nothing did what it promised, so it keeps the forgiving verdict.
+  if (looksLikeTestSuiteCommand(cmd) && producedNoOutput(probeRes.stdout, probeRes.stderr)) return "empty";
   const { count } = parseCollectedTests(probeRes.stdout, probeRes.stderr);
   if (count === null) return "silent";
   return count > 0 ? "ran" : "empty";
@@ -341,7 +364,7 @@ async function resolveRunnableOracle(root, testCmd, options = {}) {
   if (!testCmd) return testCmd;
   const probeSp = spinner(`Probing oracle: ${testCmd}`, options);
   const probeRes = await runVerificationProbe(testCmd, root);
-  const verdict = probeVerdict(probeRes);
+  const verdict = probeVerdict(probeRes, testCmd);
   if (verdict === "ran") {
     probeSp.stop(`Oracle verified successfully (${probeRes.durationMs}ms)`);
     return testCmd;
@@ -364,7 +387,7 @@ async function resolveRunnableOracle(root, testCmd, options = {}) {
   for (const cand of alternates) {
     const altSp = spinner(`Trying ${cand}`, options);
     const altRes = await runVerificationProbe(cand, root);
-    const altVerdict = probeVerdict(altRes);
+    const altVerdict = probeVerdict(altRes, cand);
     if (altVerdict === "ran") {
       altSp.stop(`${cand} runs here (${altRes.durationMs}ms) — using it instead`);
       return cand;

package/src/wizard-task.mjs

@@ -261,7 +261,21 @@ ${fullPrompt}
  * @returns {Promise<{ ok: boolean, dryRun: boolean, taskFile: string, written: boolean, plan: object }>}
  */
 export async function runTaskCreateWizard(root = process.cwd(), options = {}) {
-  const interactive = options.interactive !== false && isTTY(options.stdin || process.stdin);
+  // `-p` is the documented way to skip the questions, so it has to skip them.
+  //
+  // README: "Pass the prompt to skip straight to review:
+  // npx jules-orchestrator-kit task create -p 'Refactor the invoice module'".
+  // Interactivity was decided by `isTTY` alone, and `-p` was consulted only by
+  // the TODO-import branch below — so in a real terminal the advertised
+  // quickstart stopped at "? Task Title" and waited for a keypress forever,
+  // then asked for the instructions it had already been handed.
+  //
+  // It looked fine under test because a non-TTY run takes the headless path and
+  // never asks. That is the same defect the flag itself has: one rule, two
+  // paths, and only the path nobody was watching kept the old answer. Making
+  // `-p` mean the headless path everywhere makes the two agree by construction.
+  const promptSupplied = typeof options.prompt === "string" && options.prompt.trim() !== "";
+  const interactive = options.interactive !== false && !promptSupplied && isTTY(options.stdin || process.stdin);
 
   let title = options.title;
   let promptText = options.prompt;