wisp-agents 0.17.0 → 0.20.0

package/server/adapters/cursor.js

@@ -4,6 +4,7 @@
 // ask_user tool isn't available here; the protocol tells the agent to end with a question block.
 
 import { attachmentNote, clip, detectVersion, exitText, fileTracker, quietOutput, rel, spawnJsonl, withProtocol } from './common.js';
+import { describeCommand } from './commands.js';
 
 const BIN = process.env.WISP_CURSOR_BIN || 'cursor-agent';
 
@@ -130,7 +131,7 @@ function describeTool(name, a, cwd) {
     case 'deleteToolCall':
       return { kind: 'edit', label: `Deleting ${f}`, file: f };
     case 'shellToolCall':
-      return { kind: 'run', label: a.description ? clip(a.description) : `Running ${clip(a.command, 60)}`, detail: a.command };
+      return { kind: 'run', label: a.description ? clip(a.description) : describeCommand(a.command, cwd), detail: a.command };
     case 'grepToolCall':
       return { kind: 'search', label: `Searching for “${clip(a.pattern, 40)}”` };
     case 'globToolCall':

package/server/adapters/grok.js

@@ -10,6 +10,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { ASK_TIMEOUT_MS, attachmentNote, clip, detectVersion, exitText, fileTracker, flatten, quietOutput, rel, spawnJsonl } from './common.js';
+import { describeCommand } from './commands.js';
 
 const BIN = process.env.WISP_GROK_BIN || 'grok';
 
@@ -195,7 +196,7 @@ function describeTool(name, input, cwd) {
       return { kind: 'edit', label: `Writing ${f}`, file: f };
     case 'run_terminal_command':
     case 'run_terminal_cmd':
-      return { kind: 'run', label: input.description ? clip(input.description) : `Running ${clip(input.command, 60)}`, detail: input.command };
+      return { kind: 'run', label: input.description ? clip(input.description) : describeCommand(input.command, cwd), detail: input.command };
     case 'grep':
       return { kind: 'search', label: `Searching for “${clip(input.pattern, 40)}”` };
     case 'list_dir':

package/server/adapters/opencode.js

@@ -5,6 +5,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { toolsDir } from '../util.js';
 import { ASK_TIMEOUT_MS, attachmentNote, clip, detectVersion, exitText, fileTracker, quietOutput, rel, spawnJsonl, withProtocol } from './common.js';
+import { describeCommand } from './commands.js';
 
 const exe = process.platform === 'win32' ? 'opencode.cmd' : 'opencode';
 // Where opencode lives when it isn't on PATH: the copy wisp installs (POST /agents/install),
@@ -213,7 +214,7 @@ function describeTool(name, input, cwd) {
       return { kind: 'edit', label: `Writing ${f}`, file: f };
     case 'bash':
     case 'shell':
-      return { kind: 'run', label: input.description ? clip(input.description) : `Running ${clip(input.command, 60)}`, detail: input.command };
+      return { kind: 'run', label: input.description ? clip(input.description) : describeCommand(input.command, cwd), detail: input.command };
     case 'grep':
       return { kind: 'search', label: `Searching for “${clip(input.pattern, 40)}”` };
     case 'glob':

package/server/check.js

@@ -0,0 +1,205 @@
+// wisp's own test check: after an Auto turn, wisp runs the project's tests itself instead of taking
+// the agent's word for it (in the wisp-bench pilot, 19 of 20 failed runs still said "done").
+//
+// detectTests(dir, project) finds the command; runCheck(dir, command) runs it and reads which tests
+// failed from the usual reporters (node --test, jest/vitest, pytest, go, cargo, rspec). A failure
+// only counts against the agent when it's new: check() compares with the same command on the
+// task's base commit (a throwaway worktree, cached per base and command), and runs a failing
+// command twice so a flaky test doesn't send the agent off to fix nothing.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { git } from './git.js';
+import { killTree } from './proc.js';
+
+const MAX_OUTPUT = 400 * 1024;
+export const CHECK_TIMEOUT_MS = Number(process.env.WISP_CHECK_TIMEOUT_MS || 10 * 60_000);
+
+const read = (f) => {
+  try {
+    return fs.readFileSync(f, 'utf8');
+  } catch {
+    return null;
+  }
+};
+const has = (dir, f) => fs.existsSync(path.join(dir, f));
+
+// { command, kind, why } | { skip: reason } | null (nothing that looks like tests).
+// project.testCommand overrides it; 'off' turns the check off for that project.
+export function detectTests(dir, project = null) {
+  const custom = String(project?.testCommand || '').trim();
+  if (custom === 'off') return { skip: 'Turned off for this project' };
+  if (custom) return { command: custom, kind: 'custom', why: 'Set for this project' };
+
+  const pkg = JSON.parse(read(path.join(dir, 'package.json')) || 'null');
+  const script = pkg?.scripts?.test;
+  if (script && !/no test specified/.test(script)) {
+    const deps = Object.keys({ ...pkg.dependencies, ...pkg.devDependencies });
+    if (deps.length && !has(dir, 'node_modules')) return { skip: 'Dependencies are not installed in this worktree (no node_modules)' };
+    const pm = has(dir, 'pnpm-lock.yaml') ? 'pnpm' : has(dir, 'yarn.lock') ? 'yarn' : has(dir, 'bun.lockb') || has(dir, 'bun.lock') ? 'bun' : 'npm';
+    return { command: `${pm} test`, kind: 'node', why: 'package.json "test" script' };
+  }
+  const py = ['pytest.ini', 'tox.ini', 'conftest.py'].some((f) => has(dir, f)) || /\[tool\.pytest/.test(read(path.join(dir, 'pyproject.toml')) || '') || /\[tool:pytest\]/.test(read(path.join(dir, 'setup.cfg')) || '') || (has(dir, 'tests') && fs.readdirSync(path.join(dir, 'tests')).some((f) => /^test_.*\.py$|_test\.py$/.test(f)));
+  if (py) {
+    const python = ['.venv/bin/python', 'venv/bin/python', '.venv/Scripts/python.exe'].find((p) => has(dir, p)) || 'python3';
+    return { command: `${python} -m pytest -q -rA`, kind: 'pytest', why: 'pytest configuration' };
+  }
+  if (has(dir, 'go.mod')) return { command: 'go test ./...', kind: 'go', why: 'go.mod' };
+  if (has(dir, 'Cargo.toml')) return { command: 'cargo test', kind: 'cargo', why: 'Cargo.toml' };
+  if (has(dir, 'Gemfile') && has(dir, 'spec')) return { command: 'bundle exec rspec', kind: 'rspec', why: 'Gemfile and spec/' };
+  if (/^test:/m.test(read(path.join(dir, 'Makefile')) || '')) return { command: 'make test', kind: 'make', why: 'Makefile test target' };
+  return null;
+}
+
+// Failing test names and pass/fail counts from whatever reporter printed `out`.
+export function parseResults(out) {
+  const failed = new Set();
+  let passed = null;
+  let failedN = null;
+  let skipped = null;
+  const add = (x) => x && failed.add(x.trim().replace(/\s+\(\d+(\.\d+)?m?s\)$/, ''));
+  for (const line of out.split('\n')) {
+    let m;
+    if ((m = line.match(/^\s*✖ (.+?)(?: \([\d.]+m?s\))?$/)) && !/^failing tests:$/.test(m[1])) add(m[1]); // node --test spec
+    else if ((m = line.match(/^not ok \d+ - (.+?)(?: # .*)?$/))) add(m[1]); // TAP, top level
+    else if ((m = line.match(/^(?:FAILED|ERROR) (\S+)/))) add(m[1]); // pytest -rA
+    else if ((m = line.match(/^\s+[✕×] (.+?)(?: \(\d+ ?ms\))?$/))) add(m[1]); // jest / vitest
+    else if ((m = line.match(/^--- FAIL: (\S+)/))) add(m[1]); // go
+    else if ((m = line.match(/^test (\S+) \.\.\. FAILED/))) add(m[1]); // cargo
+    else if ((m = line.match(/^rspec (\.\/\S+)/))) add(m[1]); // rspec
+    if ((m = line.match(/^ℹ pass (\d+)/))) passed = +m[1];
+    if ((m = line.match(/^ℹ fail (\d+)/))) failedN = +m[1];
+    if ((m = line.match(/^ℹ skipped (\d+)/))) skipped = +m[1];
+    if ((m = line.match(/^# pass (\d+)/))) passed = +m[1];
+    if ((m = line.match(/^# fail (\d+)/))) failedN = +m[1];
+    if ((m = line.match(/^=+ (.*) in [\d.]+s/))) {
+      // pytest summary: "== 3 failed, 41 passed, 2 skipped in 1.2s =="
+      passed = +(m[1].match(/(\d+) passed/)?.[1] || 0);
+      failedN = +(m[1].match(/(\d+) failed/)?.[1] || 0) + +(m[1].match(/(\d+) errors?/)?.[1] || 0);
+      skipped = +(m[1].match(/(\d+) skipped/)?.[1] || 0) || null;
+    }
+    if ((m = line.match(/^Tests:\s+(.*)$/))) {
+      // jest / vitest: "Tests: 1 failed, 12 passed, 13 total"
+      passed = +(m[1].match(/(\d+) passed/)?.[1] || 0);
+      failedN = +(m[1].match(/(\d+) failed/)?.[1] || 0);
+      skipped = +(m[1].match(/(\d+) skipped/)?.[1] || 0) || null;
+    }
+    if ((m = line.match(/^test result: \w+\. (\d+) passed; (\d+) failed/))) {
+      passed = (passed || 0) + +m[1];
+      failedN = (failedN || 0) + +m[2];
+    }
+  }
+  return { failed: [...failed].slice(0, 200), passed, failedCount: failedN ?? failed.size, skipped };
+}
+
+// Run `command` in dir: { exitCode, output, durationMs, timedOut, ...parseResults }.
+export function runCheck(dir, command, { timeout = CHECK_TIMEOUT_MS, env = {} } = {}) {
+  return new Promise((resolve) => {
+    const started = Date.now();
+    let output = '';
+    let timedOut = false;
+    // Not inherited: a test runner's own markers (wisp under `node --test` would make the project's
+    // `node --test` report to it and exit 0) and wisp's.
+    const base = Object.fromEntries(Object.entries(process.env).filter(([k]) => !/^(NODE_TEST_CONTEXT|NODE_UNIQUE_ID|WISP_|FAKE_)/.test(k)));
+    const child = spawn(process.platform === 'win32' ? 'cmd.exe' : 'sh', process.platform === 'win32' ? ['/d', '/s', '/c', command] : ['-c', command], {
+      cwd: dir,
+      env: { ...base, CI: '1', FORCE_COLOR: '0', NO_COLOR: '1', ...env },
+      stdio: ['ignore', 'pipe', 'pipe'],
+      detached: process.platform !== 'win32',
+    });
+    const take = (d) => {
+      output += d;
+      if (output.length > MAX_OUTPUT * 2) output = output.slice(-MAX_OUTPUT);
+    };
+    child.stdout.on('data', take);
+    child.stderr.on('data', take);
+    const timer = setTimeout(() => {
+      timedOut = true;
+      killTree(child);
+    }, timeout);
+    const done = (exitCode) => {
+      clearTimeout(timer);
+      output = output.replace(/\x1b\[[0-9;]*m/g, '').slice(-MAX_OUTPUT);
+      resolve({ exitCode, output, durationMs: Date.now() - started, timedOut, ...parseResults(output) });
+    };
+    child.on('error', (err) => ((output += `\n${err.message}`), done(127)));
+    child.on('close', (code) => done(timedOut ? 124 : code ?? 1));
+  });
+}
+
+// The same command at the base commit, once per (repo, base, command).
+const baselines = new Map();
+export async function baseline(wt, command) {
+  if (!wt?.root || !wt.head) return null;
+  const key = `${wt.root}\0${wt.head}\0${command}`;
+  if (!baselines.has(key)) {
+    baselines.set(
+      key,
+      (async () => {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'wisp-base-'));
+        try {
+          await git(wt.root, ['worktree', 'add', '--quiet', '--detach', dir, wt.head]);
+          // node_modules and virtualenvs aren't in git: borrow the task's, so the base can run too.
+          for (const d of ['node_modules', '.venv', 'venv']) {
+            const from = path.join(wt.path, d);
+            if (fs.existsSync(from) && !fs.existsSync(path.join(dir, d))) fs.symlinkSync(from, path.join(dir, d), 'dir');
+          }
+          const sub = path.relative(wt.path, wt.cwd || wt.path);
+          return await runCheck(path.join(dir, sub), command);
+        } catch {
+          return null;
+        } finally {
+          await git(wt.root, ['worktree', 'remove', '--force', dir]).catch(() => {});
+          fs.rmSync(dir, { recursive: true, force: true });
+        }
+      })(),
+    );
+  }
+  return baselines.get(key);
+}
+
+// The verdict wisp acts on. pass: exit 0, or every failure was failing on the base already.
+// fail: tests that passed on the base fail now (twice). unknown: it failed and we can't tell why
+// (no base to compare with, or a reporter we can't read). skip: nothing to run.
+export async function check({ dir, project, worktree, timeout } = {}) {
+  const found = detectTests(dir, project);
+  if (!found) return { verdict: 'skip', reason: 'No test command found', command: null };
+  if (found.skip) return { verdict: 'skip', reason: found.skip, command: null };
+  const { command } = found;
+  let run = await runCheck(dir, command, { timeout });
+  if (run.exitCode === 0 && !run.timedOut) return summary('pass', command, run, [], []);
+  // Flaky? Only failures that happen twice count.
+  const again = await runCheck(dir, command, { timeout });
+  if (again.exitCode === 0 && !again.timedOut) return summary('pass', command, again, [], [], 'Passed on a second run (a flaky test)');
+  const twice = run.failed.filter((t) => again.failed.includes(t));
+  run = { ...again, failed: twice.length || !again.failed.length ? twice : again.failed };
+  const base = await baseline(worktree, command);
+  if (!base) return summary(run.failed.length || run.timedOut ? 'fail' : 'unknown', command, run, run.failed, [], 'No base to compare with');
+  if (base.exitCode === 0) return summary('fail', command, run, run.failed, []);
+  const before = new Set(base.failed);
+  const fresh = run.failed.filter((t) => !before.has(t));
+  const old = run.failed.filter((t) => before.has(t));
+  if (!run.failed.length || !base.failed.length) return summary('unknown', command, run, [], [], 'Fails on the base commit too, and the failures could not be read');
+  return summary(fresh.length ? 'fail' : 'pass', command, run, fresh, old, fresh.length ? '' : `${old.length} failing on the base commit too`);
+}
+
+function summary(verdict, command, run, fresh, old, note = '') {
+  const tail = run.output.split('\n').filter((l) => l.trim()).slice(-60).join('\n');
+  return {
+    verdict,
+    command,
+    exitCode: run.exitCode,
+    passed: run.passed,
+    failed: run.failedCount || run.failed.length || (run.exitCode ? 1 : 0),
+    skipped: run.skipped,
+    newFailures: fresh.slice(0, 50),
+    preexisting: old.slice(0, 50),
+    timedOut: run.timedOut,
+    durationMs: run.durationMs,
+    note,
+    output: verdict === 'pass' ? '' : tail.slice(-6000),
+    at: Date.now(),
+  };
+}

package/server/git.js

@@ -129,7 +129,7 @@ export async function removeWorktree(wt, { force = false, branch = false } = {})
 
 // --- Ship it: commit, push, open a PR, follow it, merge it -----------------------------------
 
-const PR_FIELDS = 'number,url,title,state,isDraft,reviewDecision,mergeStateStatus,statusCheckRollup,headRefOid,baseRefName,mergedAt';
+const PR_FIELDS = 'number,url,title,state,isDraft,reviewDecision,mergeable,mergeStateStatus,statusCheckRollup,headRefOid,baseRefName,mergedAt';
 const PASS = new Set(['SUCCESS', 'NEUTRAL', 'SKIPPED']);
 const FAIL = new Set(['FAILURE', 'ERROR', 'TIMED_OUT', 'CANCELLED', 'ACTION_REQUIRED', 'STARTUP_FAILURE', 'STALE']);
 
@@ -149,6 +149,8 @@ export function prSummary(j) {
     draft: !!j.isDraft,
     review: j.reviewDecision || '', // APPROVED | CHANGES_REQUESTED | REVIEW_REQUIRED | ''
     mergeState: j.mergeStateStatus || '',
+    // GitHub can't merge it into its base: both sides changed the same lines (UNKNOWN while it computes).
+    conflict: j.mergeable === 'CONFLICTING' || j.mergeStateStatus === 'DIRTY',
     head: j.headRefOid,
     base: j.baseRefName,
     mergedAt: j.mergedAt || null,
@@ -162,23 +164,58 @@ export async function prView(cwd, ref) {
 }
 
 // Commit whatever the session left uncommitted, push its branch and open (or update) its PR.
-export async function ship(wt, { title, body = '', draft = false, pr }) {
+// `onStep` hears each stage as it starts ('commit', 'push', 'pr'), so the card can follow along.
+export async function ship(wt, { title, body = '', draft = false, pr, onStep = () => {} }) {
   await ensureWorktree(wt);
   const dir = wt.path;
   if (await quiet(git(dir, ['status', '--porcelain']))) {
     if (!String(title || '').trim()) throw bad('A commit message is required.');
+    onStep('commit');
     await git(dir, ['add', '-A']);
     await git(dir, ['commit', '--quiet', '--no-verify', '-m', title.trim(), ...(body.trim() ? ['-m', body.trim()] : [])]);
   }
   const { ahead } = await worktreeStatus(wt);
   if (!ahead) throw bad('Nothing to ship: this branch has no changes.');
   if (!wt.remote) throw bad('This repo has no origin remote to push to.');
+  onStep('push');
   await git(dir, ['push', '--quiet', '-u', wt.remote, `HEAD:refs/heads/${wt.branch}`], { timeout: 120_000 });
+  onStep('pr');
   if (pr?.state === 'OPEN') return prView(dir, pr.number);
   const url = (await gh(dir, ['pr', 'create', '--base', wt.base, '--head', wt.branch, '--title', title.trim(), '--body', body.trim() || ' ', ...(draft ? ['--draft'] : [])])).split('\n').pop();
   return prView(dir, url);
 }
 
+// Does the branch really conflict with its freshly fetched base? Checked before spending an agent
+// run on GitHub's word, which can lag a push. true / false, or null when this git can't tell (< 2.38).
+export async function conflictsWithBase(wt) {
+  if (!wt?.remote || !fs.existsSync(wt.path)) return null;
+  await quiet(git(wt.path, ['fetch', '--quiet', wt.remote, wt.base], { timeout: 30_000 }));
+  return new Promise((resolve) => {
+    execFile(GIT(), ['merge-tree', '--write-tree', '--name-only', '--no-messages', `refs/remotes/${wt.remote}/${wt.base}`, 'HEAD'], { cwd: wt.path, timeout: 30_000, env: { ...process.env, ...QUIET_ENV } }, (err) =>
+      resolve(!err ? false : err.code === 1 ? true : null),
+    );
+  });
+}
+
+// After an agent was asked to merge the base into its branch: is it in, with nothing left half
+// done? A merge it resolved but left uncommitted is committed here. { ok } or { ok: false, why }.
+export async function baseMerged(wt) {
+  const dir = wt.path;
+  const unmerged = await quiet(git(dir, ['diff', '--name-only', '--diff-filter=U']));
+  if (unmerged) return { ok: false, why: `Still conflicted: ${unmerged.split('\n').join(', ')}` };
+  if (await quiet(git(dir, ['rev-parse', '--quiet', '--verify', 'MERGE_HEAD']))) {
+    await git(dir, ['add', '-A']);
+    await git(dir, ['commit', '--quiet', '--no-verify', '--no-edit']);
+  }
+  const base = `refs/remotes/${wt.remote}/${wt.base}`;
+  const merged = await git(dir, ['merge-base', '--is-ancestor', base, 'HEAD']).then(() => true, () => false);
+  if (!merged) return { ok: false, why: `${wt.remote}/${wt.base} is not merged into the branch.` };
+  // Conflict markers staged as if resolved: git no longer sees them, so look in the PR's diff.
+  const marked = await quiet(git(dir, ['diff', '--name-only', '-G^<<<<<<< ', `${base}...HEAD`]));
+  if (marked) return { ok: false, why: `Conflict markers left in ${marked.split('\n').join(', ')}` };
+  return { ok: true };
+}
+
 // Squash-merge the exact head that was reviewed, then tidy up and catch the user's checkout up.
 export async function merge(wt, number) {
   const dir = fs.existsSync(wt.path) ? wt.path : wt.root;
@@ -205,3 +242,78 @@ export async function syncBase(root, base) {
     return { ok: false, text: `Local ${base} was not updated: ${err.message}` };
   }
 }
+
+// --- cloning: "add a project" from a repo URL instead of a folder ---
+
+// A repo the user pasted: https://github.com/o/r(/tree/…), github.com/o/r, git@host:o/r.git,
+// ssh:// git:// file:// URLs, and (shorthand) o/r for GitHub. Null when it's not a repo, e.g. a path.
+export function parseRepo(input, { shorthand = false } = {}) {
+  const s = String(input || '').trim();
+  const strip = (p) => p.replace(/\/+$/, '').replace(/\.git$/i, '');
+  const of = (url, host, repoPath) => {
+    const parts = strip(repoPath).split('/').filter(Boolean);
+    if (!parts.length) return null;
+    const gh = host === 'github.com' && parts.length >= 2 ? `${parts[0]}/${parts[1]}` : null;
+    return { url, host, name: gh ? parts[1] : parts.at(-1), gh, path: parts.join('/') };
+  };
+  let m;
+  if (/^(https?|ssh|git|file):\/\//i.test(s) || /^(www\.)?github\.com\//i.test(s)) {
+    let u;
+    try {
+      u = new URL(/^\w+:\/\//.test(s) ? s : `https://${s}`);
+    } catch {
+      return null;
+    }
+    const host = u.hostname.replace(/^www\./, '').toLowerCase();
+    if (u.protocol === 'file:') return of(u.href, '', u.pathname);
+    if (!host) return null;
+    // A GitHub page inside the repo (/tree/main, /pull/3) still means the repo.
+    if (host === 'github.com') {
+      const [o, r] = u.pathname.split('/').filter(Boolean);
+      return o && r ? of(`https://github.com/${o}/${strip(r)}.git`, host, `${o}/${r}`) : null;
+    }
+    return u.pathname.split('/').filter(Boolean).length >= 2 || u.protocol !== 'https:' ? of(s, host, u.pathname) : null;
+  }
+  if ((m = s.match(/^[\w.-]+@([\w.-]+):(?!\/\/)(.+)$/))) return of(s, m[1].toLowerCase(), m[2]);
+  if (shorthand && (m = s.match(/^([\w-]+)\/([\w.-]+)$/))) return of(`https://github.com/${m[1]}/${strip(m[2])}.git`, 'github.com', `${m[1]}/${m[2]}`);
+  return null;
+}
+
+// The same repo, however it was spelled (https vs ssh, .git or not, case of the host).
+const sameRepo = (a, b) => {
+  const key = (u) => {
+    const r = parseRepo(u);
+    return r && (r.gh ? `github.com/${r.gh.toLowerCase()}` : `${r.host}/${r.path}`);
+  };
+  return !!key(a) && key(a) === key(b);
+};
+
+// Clone `repo` (from parseRepo) into `parent`/<name>. A folder there that already is this repo is
+// reused; any other one gets a -2, -3… suffix. GitHub repos go through `gh repo clone` when gh is
+// there, so private repos work with the user's gh login; otherwise (or if gh fails) plain git.
+export async function cloneRepo(repo, parent, { timeout = 10 * 60_000 } = {}) {
+  fs.mkdirSync(parent, { recursive: true });
+  let dir = path.join(parent, repo.name);
+  for (let n = 2; fs.existsSync(dir); n++) {
+    const origin = await quiet(git(dir, ['remote', 'get-url', 'origin']));
+    if (origin && (await repoRoot(dir)) === fs.realpathSync(dir) && sameRepo(origin, repo.url)) return { dir, existed: true };
+    dir = path.join(parent, `${repo.name}-${n}`);
+  }
+  const attempts = [];
+  if (repo.gh) attempts.push(() => gh(parent, ['repo', 'clone', repo.gh, dir], { timeout }));
+  attempts.push(() => run(GIT(), ['clone', '--quiet', repo.url, dir], { cwd: parent, timeout }));
+  let last;
+  for (const attempt of attempts) {
+    try {
+      await attempt();
+      return { dir, existed: false };
+    } catch (err) {
+      last = err;
+      fs.rmSync(dir, { recursive: true, force: true }); // a half clone would block the next try
+    }
+  }
+  const what = repo.gh || repo.url;
+  if (/not found|does not exist|could not read username|authentication|permission denied|403/i.test(last.message))
+    throw bad(`Couldn’t clone ${what}: it doesn’t exist, or this login can’t see it.${repo.gh ? ' Private repo? Check `gh auth status`.' : ''}`);
+  throw bad(`Couldn’t clone ${what}: ${last.message}`);
+}

package/server/index.js

@@ -25,6 +25,7 @@ import { Routes } from './http/router.js';
 import { send, eventStream } from './http/respond.js';
 import { serveStatic } from './http/static.js';
 import { createAuto } from './services/auto.js';
+import { scoutNote } from './scout.js';
 import { createFeedback } from './services/feedback.js';
 import { createInstaller } from './services/install.js';
 import { createLaunch } from './services/launch.js';
@@ -119,7 +120,7 @@ export async function startServer({ port = DEFAULT_PORT, host = '127.0.0.1', han
   app.prefs = new Preferences(store.home);
   app.learning = () => store.config.defaults.learn !== 'off';
   const projectOf = (cwd) => store.projectFor(cwd)?.path || cwd;
-  runner.promptExtra = (s) => (app.learning() && s.agent !== 'wisp' ? app.prefs.prompt(projectOf(s.cwd)) : '');
+  runner.promptExtra = (s) => (app.learning() && s.agent !== 'wisp' ? app.prefs.prompt(projectOf(s.cwd)) : '') + scoutNote(s.scout);
   app.retro = new Retro({
     store,
     runner,

package/server/judge.js

@@ -0,0 +1,78 @@
+// Picking between two runs of the same task (best-of-2). Tests decide when they can: a run whose
+// check passed beats one whose check failed. Otherwise a cheap model reads both diffs, and if
+// that isn't available either, fewer new failures and then the smaller diff win.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { askJson } from './quick.js';
+
+const MAX_DIFF = 24_000;
+
+// The run's changes against its base: tracked diff plus new files.
+export function diffOf(dir, base = 'HEAD') {
+  const run = (args) => {
+    try {
+      return execFileSync('git', args, { cwd: dir, stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 64 << 20, timeout: 15_000 }).toString();
+    } catch {
+      return '';
+    }
+  };
+  let out = run(['diff', base, '--', '.', ':(exclude)node_modules']);
+  for (const f of run(['ls-files', '--others', '--exclude-standard']).split('\n').filter(Boolean).slice(0, 30)) {
+    try {
+      out += `\n--- /dev/null\n+++ b/${f}\n${fs.readFileSync(path.join(dir, f), 'utf8').slice(0, 4000).split('\n').map((l) => `+${l}`).join('\n')}`;
+    } catch {}
+  }
+  return out;
+}
+
+const changed = (d) => d.split('\n').filter((l) => /^[+-](?![+-])/.test(l)).length;
+const SCORE = { pass: 3, unknown: 2, skip: 2, fail: 0 };
+
+// candidates: [{ id, label, check, diff }]. Resolves with { winner, why, by }.
+export async function judge({ prompt, candidates, agents }) {
+  const [a, b] = candidates;
+  const sa = SCORE[a.check?.verdict] ?? 1;
+  const sb = SCORE[b.check?.verdict] ?? 1;
+  if (sa !== sb) {
+    const w = sa > sb ? a : b;
+    return { winner: w.id, by: 'tests', why: `${w.label}'s changes pass the tests; the other run's don't.` };
+  }
+  const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'wisp-judge-'));
+  try {
+    const ask = `Two coding agents did the same task. Judge which change is better: correct, complete, minimal, and in the style of the code around it. Tests: run A ${a.check?.verdict || 'not checked'}, run B ${b.check?.verdict || 'not checked'}.
+
+<task>
+${String(prompt).slice(0, 4000)}
+</task>
+
+<run id="A" label="${a.label}">
+${a.diff.slice(0, MAX_DIFF) || '(no changes)'}
+</run>
+
+<run id="B" label="${b.label}">
+${b.diff.slice(0, MAX_DIFF) || '(no changes)'}
+</run>
+
+Reply with one JSON object: {"winner": "A" | "B", "why": "one sentence"}`;
+    const j = await askJson({ agents, prompt: ask, cwd, timeoutMs: 120_000 });
+    if (j && (j.winner === 'A' || j.winner === 'B')) return { winner: (j.winner === 'A' ? a : b).id, by: 'model', why: String(j.why || '').slice(0, 300) };
+  } finally {
+    fs.rmSync(cwd, { recursive: true, force: true });
+  }
+  const fa = a.check?.newFailures?.length ?? 0;
+  const fb = b.check?.newFailures?.length ?? 0;
+  if (fa !== fb) {
+    const w = fa < fb ? a : b;
+    return { winner: w.id, by: 'rule', why: `${w.label} leaves fewer new failing tests.` };
+  }
+  const empty = (c) => !c.diff.trim();
+  if (empty(a) !== empty(b)) {
+    const w = empty(a) ? b : a;
+    return { winner: w.id, by: 'rule', why: `${w.label} changed something; the other run didn't.` };
+  }
+  const w = changed(a.diff) <= changed(b.diff) ? a : b;
+  return { winner: w.id, by: 'rule', why: `${w.label} made the smaller change.` };
+}

package/server/machines.js

@@ -500,7 +500,7 @@ export class Machines extends EventEmitter {
   summary(mid, s) {
     const m = this.get(mid);
     const q = (id) => qualify(id, mid);
-    const p = this.store.projectFor(s.cwd || '', mid);
+    const p = s.scratch ? null : this.store.projectFor(s.cwd || '', mid);
     return {
       ...s,
       id: q(s.id),
@@ -578,7 +578,7 @@ export class Machines extends EventEmitter {
   }
 
   async addProject(mid, dir, name) {
-    const p = await this.json(mid, 'POST', '/projects', { path: dir });
+    const p = await this.json(mid, 'POST', '/projects', { path: dir }, { timeout: 10 * 60_000 }); // dir may be a repo URL to clone
     const local = this.store.addProject(p.path, { name: name || p.name, machine: mid });
     return local;
   }

package/server/openapi.js

@@ -47,7 +47,7 @@ export function openapi({ version, port }) {
       '/agents': { get: { summary: 'Installed harnesses with their models and thinking levels (?fresh=1 detects again)', responses: { 200: json({ type: 'array', items: ref('Agent') }) } } },
       '/router': {
         get: { summary: 'Auto: the goal, settings, every harness · model with its learned chance of success and cost, and recent routes', responses: { 200: json({ type: 'object' }) } },
-        patch: { summary: 'Auto settings', requestBody: body({ type: 'object', properties: { goal: { enum: ['cheap', 'balanced', 'best'] }, explore: { type: 'boolean', description: 'Let Auto try new models on a few tasks' }, allowed: { type: 'array', items: { type: 'string' }, description: 'Harness ids Auto may pick; empty or null = all' } } }), responses: { 200: json({ type: 'object' }) } },
+        patch: { summary: 'Auto settings', requestBody: body({ type: 'object', properties: { goal: { enum: ['cheap', 'balanced', 'best'] }, explore: { type: 'boolean', description: 'Let Auto try new models on a few tasks' }, allowed: { type: 'array', items: { type: 'string' }, description: 'Harness ids Auto may pick; empty or null = all' }, check: { type: 'boolean', description: 'Run the project tests after an Auto run; only new failures count' }, repairs: { type: 'integer', minimum: 0, maximum: 2, description: 'Times failing tests go back to the same agent' }, escalate: { type: 'boolean', description: 'Still failing: run the task again on a stronger pick, in its own worktree' }, best2: { type: 'boolean', description: 'Goal Best: two picks side by side, the better one marked' }, scout: { enum: ['off', 'big', 'all'], description: 'A cheap model looks at the repo first' } } }), responses: { 200: json({ type: 'object' }) } },
       },
       '/router/reset': { post: { summary: 'Forget what Auto learned here (the shipped starting point stays)', responses: { 200: json({ type: 'object' }) } } },
       '/agents/install': {
@@ -90,7 +90,19 @@ export function openapi({ version, port }) {
       },
       '/projects': {
         get: { summary: 'List projects', responses: { 200: json({ type: 'array', items: ref('Project') }) } },
-        post: { summary: 'Add a folder as a project', requestBody: body({ type: 'object', required: ['path'], properties: { path: { type: 'string' }, name: { type: 'string' } } }), responses: { 201: json(ref('Project')), 400: err[400] } },
+        post: {
+          summary: 'Add a folder as a project, or clone a repo URL and add the clone',
+          requestBody: body({
+            type: 'object',
+            properties: {
+              path: { type: 'string', description: 'A folder, or a repo URL (https://github.com/o/r, git@host:o/r.git, o/r)' },
+              repo: { type: 'string', description: 'A repo URL to clone into defaults.cloneDir (default ~/code), then add' },
+              name: { type: 'string' },
+              machine: { type: 'string', description: 'Add (or clone) it on this machine' },
+            },
+          }),
+          responses: { 201: json(ref('Project')), 400: err[400] },
+        },
       },
       '/projects/{pid}': {
         parameters: [{ name: 'pid', in: 'path', required: true, schema: { type: 'string' } }],
@@ -132,6 +144,7 @@ export function openapi({ version, port }) {
         },
       },
       '/sessions/{id}/pr': { parameters: [id], post: { summary: 'Refresh the PR status (checks, review, state) now; it is also polled every minute', responses: { 200: json(ref('PullRequest')), 404: err[404] } } },
+      '/sessions/{id}/fix-conflicts': { parameters: [id], post: { summary: 'Fix the PR\'s merge conflicts now (the PR row\'s Fix conflicts button): a follow-up merges the base in, then wisp pushes to the PR', responses: { 200: json({ type: 'object' }), 400: err[400] } } },
       '/sessions/{id}/merge': {
         parameters: [id],
         post: { summary: 'Mark the PR ready if draft, squash-merge it with --match-head-commit, fast-forward the local base branch, remove the worktree', responses: { 200: json({ type: 'object', properties: { pr: ref('PullRequest'), sync: { type: 'object', properties: { ok: { type: 'boolean' }, text: { type: 'string' } } } } }), 400: err[400] } },
@@ -291,6 +304,7 @@ export function openapi({ version, port }) {
           properties: {
             prompt: { type: 'string' },
             cwd: { type: 'string', description: 'Project folder (absolute; ~ allowed). Default: the server’s cwd' },
+            scratch: { type: 'boolean', description: 'No project folder: run in an empty scratch directory (no worktree). Overrides cwd' },
             agent: { enum: ['auto', 'claude', 'codex', 'opencode', 'cursor', 'antigravity', 'grok'], default: 'auto', description: 'auto: wisp picks the harness and model from what worked before; model is then the goal (cheap, balanced, best)' },
             important: { type: 'boolean', description: 'With agent auto: no exploring, take the pick with the best record' },
             mode: { enum: ['plan', 'edits', 'auto'], default: 'auto' },
@@ -312,6 +326,7 @@ export function openapi({ version, port }) {
             draft: { type: 'boolean' },
             review: { type: 'string', description: 'APPROVED | CHANGES_REQUESTED | REVIEW_REQUIRED | ""' },
             checks: { type: 'object', properties: { pass: { type: 'integer' }, fail: { type: 'integer' }, pending: { type: 'integer' } } },
+            conflict: { type: 'boolean', description: 'GitHub cannot merge it into its base: merge conflicts' },
             head: { type: 'string' },
             base: { type: 'string' },
           },
@@ -393,6 +408,8 @@ export function openapi({ version, port }) {
             updatedAt: { type: 'integer' },
             branch: { type: 'string', description: 'Worktree branch, if it has one' },
             pr: { type: ['object', 'null'], description: 'Its pull request, once shipped' },
+            shipping: { type: ['object', 'null'], description: "{ step: start | commit | push | pr, update } while Ship it runs" },
+            conflictFix: { type: ['object', 'null'], description: "{ step: fixing | pushing | done | failed, why } while wisp fixes the PR's merge conflicts: after Fix conflicts, or on its own with defaults.fixConflicts: 'on'" },
             groupId: { type: ['string', 'null'], description: 'Shared by sessions launched together with compare' },
             origin: { type: ['object', 'null'], description: '{ kind: recipe | trigger, id, name } when not launched by hand' },
           },