@splinterzzz/ouro 0.1.1 → 0.1.3

package/src/lib/claudeCodeExec.js

@@ -34,10 +34,16 @@ function agentFlags(agent, restrictTo) {
   }
 
   const granted = agent.tools?.length ? agent.tools : DEFAULT_WRITE_TOOLS;
+  // "*" means fully unrestricted — every native Claude Code tool (including
+  // Task, for subagent fan-out) plus any project skills and connected
+  // MCP/plugin tools, none of which ouro's fixed TOOL_UNIVERSE enumerates.
+  // Only honored outside a read-only phase — Analyze/Plan/QA must never
+  // widen past restrictTo no matter what the agent itself requests.
+  const unrestricted = granted.includes("*") && !restrictTo;
   const allowed = restrictTo ? granted.filter((t) => restrictTo.includes(t)) : granted;
 
   const flags = [];
-  if (allowed.length) flags.push("--allowedTools", allowed.join(","));
+  if (!unrestricted && allowed.length) flags.push("--allowedTools", allowed.join(","));
   if (agent.model) flags.push("--model", agent.model);
   // Append rather than replace: Claude Code's own system prompt carries the
   // tool contract, so blowing it away with --system-prompt breaks tool use.
@@ -122,22 +128,26 @@ export async function askJson({ prompt, cwd, signal }) {
 }
 
 /**
- * Triage: read-only tools only, no file writes. Claude Code doesn't have a
- * sandbox flag like Codex — read-only-ness comes from restricting
- * --allowedTools instead.
+ * Analyze: a read-only agent pass (the Analyst agent) that scopes the ticket.
+ * Read-only-ness comes from restricting --allowedTools — Claude Code has no
+ * sandbox flag like Codex. The agent's tools are intersected with the read-only
+ * set, so even a mis-granted Write can't take effect here. Streams events to
+ * `onEvent` so the analysis is visible on the card like any other run, and
+ * returns structured findings — crucially the acceptance criteria that plan/
+ * execute and the QA gate are both held to.
  */
-export async function triage({ prompt, cwd, signal }) {
+export async function analyze({ prompt, cwd, signal, agent, onEvent }) {
   const { lastMessage } = await runClaude(
     [
       "-p",
-      `${prompt}\n\nRespond with ONLY a JSON object: {"summary": string, "priority": "low"|"medium"|"high", "files_likely_affected": string[]}. No prose, no markdown fences.`,
+      `${prompt}\n\nRespond with ONLY a JSON object: {"summary": string, "priority": "low"|"medium"|"high", "files_likely_affected": string[], "acceptance_criteria": string[]}. Each acceptance_criteria item is a concrete, checkable definition-of-done statement a test or reviewer could mark pass/fail. No prose, no markdown fences.`,
       "--output-format",
       "stream-json",
       "--verbose",
-      "--allowedTools",
-      READ_ONLY_TOOLS.join(","),
+      ...agentFlags(agent, READ_ONLY_TOOLS),
+      ...(agent ? [] : ["--allowedTools", READ_ONLY_TOOLS.join(",")]),
     ],
-    { cwd, signal }
+    { cwd, signal, onEvent }
   );
 
   return (
@@ -145,6 +155,7 @@ export async function triage({ prompt, cwd, signal }) {
       summary: lastMessage ?? "(no summary returned)",
       priority: "medium",
       files_likely_affected: [],
+      acceptance_criteria: [],
     }
   );
 }
@@ -170,6 +181,46 @@ export function runAgent({ prompt, cwd, onEvent, signal, agent }) {
   );
 }
 
+/**
+ * Staging QA gate: the Senior QA Engineer agent validates the running result.
+ *
+ * Deliberately READ-ONLY — Read/Grep/Glob, no Bash, no bypassPermissions. QA is
+ * a validator, not an implementer: ouro runs the tests and hands QA the results
+ * and the diff, so QA only needs to read the change, the source, and any built
+ * HTML. Denying Bash matters because ticket title/body are untrusted (Telegram
+ * intake is external), and an unrestricted Bash validator would turn a prompt-
+ * injected ticket into arbitrary command execution. Returns the parsed JSON
+ * verdict (null if unparseable).
+ */
+export async function qaReview({ prompt, cwd, signal, onEvent, agent }) {
+  const { lastMessage } = await runClaude(
+    [
+      "-p",
+      prompt,
+      "--output-format",
+      "stream-json",
+      "--verbose",
+      ...agentFlags(agent, READ_ONLY_TOOLS),
+      ...(agent ? [] : ["--allowedTools", READ_ONLY_TOOLS.join(",")]),
+    ],
+    { cwd, signal, onEvent }
+  );
+  return parseJsonish(lastMessage);
+}
+
+/**
+ * Read-only run that returns the raw final message. Backs `ouro init --spec`
+ * (reverse-engineering a CLAUDE.md): the agent explores but never writes — ouro
+ * writes the file from what comes back, so "read-only" stays literally true.
+ */
+export async function generateSpec({ prompt, cwd, signal, onEvent }) {
+  const { lastMessage } = await runClaude(
+    ["-p", prompt, "--output-format", "stream-json", "--verbose", "--allowedTools", READ_ONLY_TOOLS.join(",")],
+    { cwd, signal, onEvent }
+  );
+  return lastMessage;
+}
+
 /**
  * Human-in-the-loop, phase 1: plan only, read-only tools, no edits. Returns
  * the session_id so the UI can resume it once the person approves.

package/src/lib/codexExec.js

@@ -16,14 +16,17 @@ import path from "node:path";
 
 const CODEX_BIN = process.env.OURO_CODEX_BIN || "codex";
 
-const TRIAGE_SCHEMA = {
+const ANALYZE_SCHEMA = {
   type: "object",
   properties: {
     summary: { type: "string" },
     priority: { type: "string", enum: ["low", "medium", "high"] },
     files_likely_affected: { type: "array", items: { type: "string" } },
+    // Checkable definition-of-done items. Plan/execute implement against these
+    // and the QA gate validates against them, so they must be concrete.
+    acceptance_criteria: { type: "array", items: { type: "string" } },
   },
-  required: ["summary", "priority", "files_likely_affected"],
+  required: ["summary", "priority", "files_likely_affected", "acceptance_criteria"],
   additionalProperties: false,
 };
 
@@ -124,18 +127,18 @@ export async function askJson({ prompt, cwd, signal }) {
 }
 
 /**
- * Triage: read-only, schema-constrained call. Cheap, safe, no repo writes.
+ * Analyze: read-only, schema-constrained call. Cheap, safe, no repo writes.
  */
-export async function triage({ prompt, cwd, signal }) {
+export async function analyze({ prompt, cwd, signal, agent, onEvent }) {
   // os.tmpdir(), not a hardcoded /tmp — this has to work on Windows too. The
-  // pid suffix keeps concurrent triages off one another's schema file.
-  const schemaPath = path.join(os.tmpdir(), `ouro-triage-schema-${process.pid}.json`);
-  fs.writeFileSync(schemaPath, JSON.stringify(TRIAGE_SCHEMA));
+  // pid suffix keeps concurrent analyses off one another's schema file.
+  const schemaPath = path.join(os.tmpdir(), `ouro-analyze-schema-${process.pid}.json`);
+  fs.writeFileSync(schemaPath, JSON.stringify(ANALYZE_SCHEMA));
 
   try {
     const { lastMessage } = await runCodexExec(
-      ["exec", prompt, "--json", "--sandbox", "read-only", "--output-schema", schemaPath],
-      { cwd, signal }
+      ["exec", prompt, "--json", "--sandbox", "read-only", "--output-schema", schemaPath, ...agentFlags(agent)],
+      { cwd, signal, onEvent }
     );
 
     return (
@@ -143,6 +146,7 @@ export async function triage({ prompt, cwd, signal }) {
         summary: lastMessage ?? "(no summary returned)",
         priority: "medium",
         files_likely_affected: [],
+        acceptance_criteria: [],
       }
     );
   } finally {
@@ -161,6 +165,34 @@ export function runAgent({ prompt, cwd, onEvent, signal, agent }) {
   );
 }
 
+/**
+ * Staging QA gate on the Codex backend. Read-only sandbox — Codex has no
+ * per-tool grant, so read-only is how "validate, don't modify" is enforced (the
+ * tests were already run by ouro). Returns the parsed JSON verdict.
+ */
+export async function qaReview({ prompt, cwd, signal, onEvent, agent }) {
+  const { lastMessage } = await runCodexExec(["exec", prompt, "--json", "--sandbox", "read-only", ...agentFlags(agent)], {
+    cwd,
+    signal,
+    onEvent,
+  });
+  return parseJsonish(lastMessage);
+}
+
+/**
+ * Read-only run that returns the raw final message. Backs `ouro init --spec` —
+ * the agent explores under a read-only sandbox and ouro writes the file, so
+ * "read-only" holds literally.
+ */
+export async function generateSpec({ prompt, cwd, signal, onEvent }) {
+  const { lastMessage } = await runCodexExec(["exec", prompt, "--json", "--sandbox", "read-only"], {
+    cwd,
+    signal,
+    onEvent,
+  });
+  return lastMessage;
+}
+
 /**
  * Human-in-the-loop, phase 1: plan only, read-only sandbox, no writes.
  * Non-interactive headless mode can't reliably pause mid-run for approval

package/src/lib/config.js

@@ -20,6 +20,15 @@ const DEFAULTS = {
     botTokenEnvVar: "OURO_TELEGRAM_BOT_TOKEN",
     chatIdEnvVar: "OURO_TELEGRAM_CHAT_ID",
   },
+  // Staging stage (Feature 9). All null by default: ouro resolves the test and
+  // preview commands from the repo when these aren't set, so a fresh repo needs
+  // zero config. Set them to pin exact commands. previewPort is where the
+  // preview is expected to listen (used to build the clickable URL).
+  staging: {
+    testCommand: null,
+    previewCommand: null,
+    previewPort: null,
+  },
 };
 
 export function readConfig() {
@@ -85,6 +94,16 @@ export function getAutoShip() {
   return readConfig().autoShip !== false;
 }
 
+/** Staging config, each field null when unset (ouro then resolves it per-repo). */
+export function getStaging() {
+  const s = readConfig().staging ?? {};
+  return {
+    testCommand: s.testCommand ?? null,
+    previewCommand: s.previewCommand ?? null,
+    previewPort: s.previewPort ?? null,
+  };
+}
+
 export function setAutoShip(on) {
   writeConfig({ autoShip: Boolean(on) });
   return Boolean(on);

package/src/lib/ouroLog.js

@@ -0,0 +1,91 @@
+import fs from "node:fs";
+import path from "node:path";
+import { contextDir } from "./paths.js";
+
+// ouro-log.md — a human-readable run history. Not a git-log clone: the skimmable
+// summary for people who don't want to read git history.
+//
+// One entry per run, appended at run end regardless of outcome (shipped, failed,
+// no-change, cancelled — all recorded). Templated from ticket state ouro already
+// holds — NOT an extra LLM call. It lives in .ouro/context/, so it's both a
+// viewable log AND an auto-attached artifact (cross-ticket memory), and it's
+// committed (see .ouro/.gitignore) as team memory that travels with the repo.
+//
+// Populated post-`ouro init` only — there is no retrace of prior git history.
+
+const LOG_FILENAME = "ouro-log.md";
+
+const HEADER = `# ouro run log
+
+Skimmable run history — one line per run, newest at the bottom of each day.
+Templated from ticket state (not an LLM call) and committed as team memory.
+`;
+
+function logPath() {
+  return path.join(contextDir(), LOG_FILENAME);
+}
+
+export function logFilename() {
+  return LOG_FILENAME;
+}
+
+function modeLabel(mode) {
+  return mode === "agent" ? "agent loop" : "human-in-loop";
+}
+
+function prNumber(url) {
+  const m = String(url || "").match(/\/pull\/(\d+)/);
+  return m ? `#${m[1]}` : null;
+}
+
+// File count from the stored unified diff — one "diff --git" line per file. Kept
+// here rather than re-shelling to git so the log never depends on the worktree
+// still existing at write time.
+function fileCount(diff) {
+  if (!diff) return 0;
+  return (diff.match(/^diff --git /gm) || []).length;
+}
+
+/**
+ * Append one entry for a finished run. `outcome` is the short result phrase;
+ * PR link and file count are derived from the ticket. Best-effort: a failure to
+ * write the log (e.g. .ouro/context/ absent pre-init) never fails the run.
+ */
+export function appendRunLog(ticket, outcome, when = new Date()) {
+  if (!ticket) return;
+  try {
+    const dateStr = when.toISOString().slice(0, 10); // YYYY-MM-DD
+    const timeStr = when.toTimeString().slice(0, 5); // HH:MM (local)
+
+    const bits = [outcome];
+    const pr = prNumber(ticket.prUrl);
+    if (pr) bits.push(`PR ${pr}`);
+    const files = fileCount(ticket.diff);
+    if (files) bits.push(`${files} file${files === 1 ? "" : "s"}`);
+
+    const title = String(ticket.title ?? "").replace(/\s+/g, " ").trim() || "(untitled)";
+    const entry = `- **${timeStr}** · [#${ticket.id}] ${title} · ${modeLabel(ticket.mode)}\n  → ${bits.join(" · ")}\n`;
+
+    let existing;
+    try {
+      existing = fs.readFileSync(logPath(), "utf-8");
+    } catch {
+      existing = HEADER; // first write seeds the header
+    }
+
+    // A fresh date header only when today isn't already present.
+    const needsDateHeader = !existing.includes(`\n## ${dateStr}\n`);
+    fs.writeFileSync(logPath(), existing + (needsDateHeader ? `\n## ${dateStr}\n` : "") + entry);
+  } catch {
+    // Logging is memory, not control flow — never let it break a run.
+  }
+}
+
+/** Raw markdown of the log, or "" if it doesn't exist yet. Backs the Logs tab. */
+export function readRunLog() {
+  try {
+    return fs.readFileSync(logPath(), "utf-8");
+  } catch {
+    return "";
+  }
+}

package/src/lib/paths.js

@@ -29,6 +29,13 @@ export function agentsDir() {
   return path.join(ouroDir(), "agents");
 }
 
+// Shared, committed context payload — the droppable artifacts every run can
+// discover (manifest-injected, never content-dumped) plus the ouro-log.md run
+// history. Committed via .ouro/.gitignore's `!context/`. See lib/artifacts.js.
+export function contextDir() {
+  return path.join(ouroDir(), "context");
+}
+
 // Daemon bookkeeping: one pid file and one log per background service.
 // See lib/daemon.js.
 export function runDir() {
@@ -47,7 +54,7 @@ export function envPath() {
 }
 
 export function ensureOuroDir() {
-  for (const dir of [ouroDir(), worktreesDir(), agentsDir(), runDir(), logsDir()]) {
+  for (const dir of [ouroDir(), worktreesDir(), agentsDir(), contextDir(), runDir(), logsDir()]) {
     if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
   }
 }

package/src/lib/preview.js

@@ -0,0 +1,154 @@
+import { spawn } from "node:child_process";
+import net from "node:net";
+import { getStaging } from "./config.js";
+import { askJson } from "./agentBackend.js";
+
+// Staging preview servers — launch, track, and stop the local deployment a
+// ticket is reviewed against. Tracked per-ticket so it can be torn down when the
+// ticket ships, loops back, or is cancelled.
+//
+// Everything here is best-effort: if no command resolves, or it won't start, or
+// the port never opens, the stage proceeds tests-only. A preview problem must
+// NEVER fail the stage (spec).
+
+const previews = new Map(); // ticketId -> { proc, url, command, port }
+
+/**
+ * Resolve how to start the preview: config.staging.previewCommand + previewPort
+ * if set, else a cheap read-only agent inference. Returns { command, port,
+ * source } with source "config" | "inferred" | "none".
+ */
+export async function resolvePreview({ cwd, signal }) {
+  const s = getStaging();
+  if (s.previewCommand && s.previewPort) {
+    return { command: String(s.previewCommand), port: Number(s.previewPort), source: "config" };
+  }
+
+  const inferred = await askJson({
+    prompt:
+      "Infer how to start this project's local preview / dev server and the port it listens on, from its config (package.json scripts, framework config). " +
+      'Respond with ONLY JSON: {"command": string|null, "port": number|null}. Use null if there is no runnable preview. No prose, no fences.',
+    cwd,
+    signal,
+  }).catch(() => null);
+
+  const command = typeof inferred?.command === "string" ? inferred.command.trim() : "";
+  if (!command) return { command: null, port: s.previewPort ? Number(s.previewPort) : null, source: "none" };
+  const port = Number.isInteger(inferred?.port) ? inferred.port : s.previewPort ? Number(s.previewPort) : null;
+  return { command, port, source: "inferred" };
+}
+
+// Kill the whole process tree. A `shell:true` child on Windows is cmd.exe with
+// the real server underneath it — proc.kill() would leave the grandchild (and
+// the port) alive, so use taskkill /T there.
+function killTree(proc) {
+  if (!proc?.pid) return;
+  try {
+    if (process.platform === "win32") {
+      spawn("taskkill", ["/pid", String(proc.pid), "/T", "/F"], { stdio: "ignore" });
+    } else {
+      proc.kill("SIGTERM");
+    }
+  } catch {
+    /* already gone */
+  }
+}
+
+// Best-effort wait until something accepts a TCP connection on the port.
+function waitForPort(port, timeoutMs = 15000) {
+  const deadline = Date.now() + timeoutMs;
+  return new Promise((resolve) => {
+    const attempt = () => {
+      const sock = net.connect({ host: "127.0.0.1", port }, () => {
+        sock.destroy();
+        resolve(true);
+      });
+      sock.on("error", () => {
+        sock.destroy();
+        if (Date.now() > deadline) resolve(false);
+        else setTimeout(attempt, 400);
+      });
+    };
+    attempt();
+  });
+}
+
+// Most dev servers (Next, Vite, CRA, ...) print the URL they actually bound
+// once they're up — which can differ from the guessed port if it was taken
+// (Next silently increments to the next free one). Sniffing stdout for that
+// line is the only way to know the real port rather than trusting the guess.
+const URL_IN_OUTPUT = /https?:\/\/(?:localhost|127\.0\.0\.1|0\.0\.0\.0)(?::(\d+))?/i;
+
+function sniffUrl(proc, timeoutMs) {
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = (url) => {
+      if (done) return;
+      done = true;
+      proc.stdout?.off("data", onData);
+      resolve(url);
+    };
+    const onData = (chunk) => {
+      const match = URL_IN_OUTPUT.exec(chunk.toString());
+      if (match) finish(match[0].replace("0.0.0.0", "localhost"));
+    };
+    proc.stdout?.on("data", onData);
+    setTimeout(() => finish(null), timeoutMs);
+  });
+}
+
+/**
+ * Start (or restart) the preview for a ticket. Returns a status object; never
+ * throws. `started:false` means nothing resolved — the card shows "no preview"
+ * and the stage goes on. `reachable:false` means it launched but never came up
+ * (or came up on a port that never got confirmed) — callers must not surface
+ * `url` to the UI in that case, it points at nothing trustworthy.
+ */
+export async function startPreview(ticketId, { cwd, signal } = {}) {
+  stopPreview(ticketId); // never two for one ticket
+
+  const { command, port: guessedPort, source } = await resolvePreview({ cwd, signal });
+  if (!command) return { started: false, reason: "no preview command resolved", source };
+
+  let proc;
+  try {
+    proc = spawn(command, { cwd, shell: true });
+  } catch (err) {
+    return { started: false, reason: `spawn failed: ${err.message || err}`, source };
+  }
+  proc.on("error", () => {}); // a preview that fails to launch must not crash the stage
+  proc.stderr?.on("data", () => {});
+
+  const timeoutMs = 15000;
+  const [sniffed, portOpen] = await Promise.all([
+    sniffUrl(proc, timeoutMs),
+    guessedPort ? waitForPort(guessedPort, timeoutMs) : Promise.resolve(false),
+  ]);
+  // stdout gave us the real bound URL — trust it over the pre-spawn guess,
+  // since that's the only way to catch Next.js et al. auto-incrementing off
+  // an already-occupied port.
+  const url = sniffed ?? (portOpen ? `http://localhost:${guessedPort}` : null);
+  const port = sniffed ? Number(URL_IN_OUTPUT.exec(sniffed)?.[1] ?? guessedPort) : guessedPort;
+  const reachable = Boolean(sniffed) || portOpen;
+
+  previews.set(ticketId, { proc, url, command, port });
+  return { started: true, url, command, port, source, reachable };
+}
+
+export function stopPreview(ticketId) {
+  const p = previews.get(ticketId);
+  if (!p) return false;
+  killTree(p.proc);
+  previews.delete(ticketId);
+  return true;
+}
+
+export function previewInfo(ticketId) {
+  const p = previews.get(ticketId);
+  return p ? { url: p.url, command: p.command, port: p.port } : null;
+}
+
+/** Tear down every preview — used when the dashboard process shuts down. */
+export function stopAllPreviews() {
+  for (const id of [...previews.keys()]) stopPreview(id);
+}

package/src/lib/ship.js

@@ -4,13 +4,13 @@ import { hasGh, createPullRequest } from "./github.js";
 
 // Turning a finished run into a reviewable PR.
 //
-// Before this, a run ended in the Review column with a diff living in a local
+// Before this, a run ended in the Staging column with a diff living in a local
 // worktree on an unpushed branch — real work in a place nobody else could see.
 // Shipping is the step that makes it a thing a human can actually review.
 //
 // Each stage logs to the ticket, so the terminal dock narrates the push and PR
 // the same way it narrates the agent's tool calls. Every failure mode leaves
-// the ticket in `review` with the work intact: committing and pushing are
+// the ticket in `staging` with the work intact: committing and pushing are
 // worth keeping even when the PR itself can't be opened.
 
 function commitMessage(ticket) {

package/src/lib/staging.js

@@ -0,0 +1,97 @@
+import { spawn } from "node:child_process";
+import { getStaging } from "./config.js";
+import { askJson } from "./agentBackend.js";
+
+// Staging test execution. ouro runs the tests (deterministic capture) and the
+// QA agent judges the result — so the test command has to be resolved and run
+// here, not left to the agent's Bash tool.
+//
+// Resolution order: config.staging.testCommand if set, else a cheap read-only
+// agent inference from the repo (package.json scripts, CLAUDE.md, etc.). If
+// nothing resolves, the stage proceeds tests-only-absent — never a hard failure.
+
+/**
+ * Resolve the test command. Returns { command, source } where source is
+ * "config" | "inferred" | "none".
+ */
+export async function resolveTestCommand({ cwd, signal }) {
+  const configured = getStaging().testCommand;
+  if (configured) return { command: String(configured), source: "config" };
+
+  const inferred = await askJson({
+    prompt:
+      "Infer the single shell command that runs this project's automated tests, from its config (package.json scripts, Makefile, pyproject, etc.). " +
+      'Respond with ONLY JSON: {"command": string|null}. Use null if the repo has no test setup. No prose, no fences.',
+    cwd,
+    signal,
+  }).catch(() => null);
+
+  const command = typeof inferred?.command === "string" ? inferred.command.trim() : "";
+  return { command: command || null, source: command ? "inferred" : "none" };
+}
+
+/**
+ * Run a shell command, capturing output. Bounded by a timeout so a hanging
+ * suite can't wedge the stage. Never rejects — a spawn error resolves as a
+ * failed result the QA agent can read.
+ */
+export function runShell(command, { cwd, signal, timeoutMs = 10 * 60 * 1000 } = {}) {
+  return new Promise((resolve) => {
+    let stdout = "";
+    let stderr = "";
+    // shell:true so a full command string ("npm test", "pytest -q") runs as-is.
+    const proc = spawn(command, { cwd, shell: true, signal });
+
+    const timer = setTimeout(() => {
+      try {
+        proc.kill();
+      } catch {
+        /* already gone */
+      }
+    }, timeoutMs);
+
+    proc.stdout?.on("data", (d) => (stdout += d.toString()));
+    proc.stderr?.on("data", (d) => (stderr += d.toString()));
+
+    proc.on("error", (err) => {
+      clearTimeout(timer);
+      resolve({ code: null, passed: false, stdout, stderr: `${stderr}${err.message || err}` });
+    });
+    proc.on("close", (code) => {
+      clearTimeout(timer);
+      resolve({ code, passed: code === 0, stdout, stderr });
+    });
+  });
+}
+
+// Keep only the tail — the QA agent and the card need the verdict-relevant end
+// of the output (failures, summary line), not a multi-thousand-line firehose.
+function tail(text, lines = 40) {
+  return String(text || "")
+    .trim()
+    .split("\n")
+    .slice(-lines)
+    .join("\n");
+}
+
+/**
+ * Resolve + run the tests. Returns a structured result for the card and the QA
+ * agent. `ran: false` means no command resolved — the stage goes on tests-only-
+ * absent, never failing on the absence itself.
+ */
+export async function runTests({ cwd, signal }) {
+  const { command, source } = await resolveTestCommand({ cwd, signal });
+  if (!command) {
+    return { ran: false, command: null, source, passed: null, output: "No test command resolved for this repo." };
+  }
+
+  const res = await runShell(command, { cwd, signal });
+  return {
+    ran: true,
+    command,
+    source,
+    passed: res.passed,
+    code: res.code,
+    output: tail(`${res.stdout}\n${res.stderr}`),
+  };
+}