cawdev-cli 1.0.10-beta → 1.0.11-beta

package/runner/runner.mjs

@@ -19,7 +19,9 @@ import {
 import { homedir, tmpdir } from 'node:os';
 
 import { join, resolve } from 'node:path';
+import { spawnFailureSaid, workspaceProblem, workspaceProblemSaid } from './workspace-check.mjs';
 import { changedLines } from './changed-lines.mjs';
+import { adapterFor, hostFor, repoOf } from './git-host.mjs';
 import { describeTurn, totalsOf } from '../lib/usage.mjs';
 import { withinCeiling } from '../lib/tool-rules.mjs';
 import { serveControl } from './control.mjs';
@@ -1987,6 +1989,16 @@ async function surveyWorkingCopies(config) {
   for (const [slug, project] of Object.entries(config.projects)) {
     for (const path of project.workspaces) {
       const held = heldBy(path);
+      const problem = await workspaceProblem(path).catch(() => null);
+      if (problem) {
+        survey.push({
+          project: slug,
+          path,
+          runId: held ?? null,
+          unreadable: workspaceProblemSaid(slug, problem, { first: project.workspaces[0] }),
+        });
+        continue;
+      }
       try {
         await access(join(path, '.git'));
         const porcelain = await git(path, ['status', '--porcelain']);
@@ -2038,6 +2050,52 @@ async function looksClean(path) {
   return porcelain === null ? null : porcelain === '';
 }
 
+/**
+ * `workspaceProblem` for `path`, asked once per `problems` Map. The Map lives
+ * for one poll pass, so a folder cloned meanwhile is picked up without a restart.
+ */
+async function problemOf(problems, path) {
+  if (!problems.has(path)) problems.set(path, await workspaceProblem(path));
+  return problems.get(path);
+}
+
+/**
+ * The checkout a question about the project is read from — R377. The first
+ * workspace nobody holds and that can be used; else null, and the caller
+ * falls back to `project.path` as it always did. A missing `workspaces[0]` must not make the project read as
+ * broken while `[1]` is fine.
+ */
+async function usableWorkspace(project, held, problems, { reading = false } = {}) {
+  const usable = [];
+  for (const path of project.workspaces) {
+    const trouble = await problemOf(problems, path);
+    // A reader has always been able to run in a folder with no `.git` — it
+    // reads the files as they are (`readingCopy`) — so only a folder that is
+    // not there at all stops it.
+    if (!trouble || (reading && trouble.kind === 'not-git')) usable.push(path);
+  }
+  return usable.find((path) => !held.has(path)) ?? null;
+}
+
+/**
+ * One log line per workspace that cannot be used — R377. Said at boot and on
+ * SIGHUP so the operator hears it before a run is queued behind it.
+ * Returns how many there were.
+ */
+async function sayWhichWorkspacesCannotBeUsed(config) {
+  let found = 0;
+  for (const [slug, project] of Object.entries(config.projects)) {
+    for (const path of project.workspaces) {
+      const problem = await workspaceProblem(path).catch(() => null);
+      if (problem) {
+        found += 1;
+        log(`  ${workspaceProblemSaid(slug, problem, { first: project.workspaces[0] })}`);
+      }
+    }
+  }
+  return found;
+}
+
 /**
  * What every checkout on this machine holds — R87.
  *
@@ -2059,6 +2117,15 @@ async function surveyWorkspaces(config) {
   const readings = [];
   for (const [slug, project] of Object.entries(config.projects)) {
     for (const path of project.workspaces) {
+      const problem = await workspaceProblem(path).catch(() => null);
+      if (problem) {
+        readings.push({
+          path,
+          projectSlug: slug,
+          error: workspaceProblemSaid(slug, problem, { first: project.workspaces[0] }),
+        });
+        continue;
+      }
       try {
         await access(join(path, '.git'));
         const branch = (await git(path, ['rev-parse', '--abbrev-ref', 'HEAD'])).trim();
@@ -2415,9 +2482,10 @@ async function surveyGit(config) {
     // session's branch with its work uncommitted. Reading the pool's spare
     // gives the honest picture of the default branch instead.
     const held = heldWorkspaces();
-    const free = project.workspaces.find((candidate) => !held.has(candidate));
+    const free = await usableWorkspace(project, held, new Map());
     const path = free ?? resolve(project.path);
-    const busy = free === undefined;
+    // Busy means no free USABLE workspace.
+    const busy = free === null;
 
     const reading = await surveyProjectGit(path, { fetch: !busy }).catch((failure) => ({
       error: failure.message.split('\n')[0],
@@ -3398,7 +3466,7 @@ async function perform(config, run, cwd, action) {
     ({ ok, result } = await openPullRequest(cwd, run, action.message));
   } else if (action.kind === 'MERGE') {
     log(`  MERGING ${run.branch} into ${run.baseBranch ?? 'the default branch'}${byRule(action)} — nobody is reading this diff`);
-    ({ ok, result } = await mergePullRequest(cwd, run.branch));
+    ({ ok, result } = await mergePullRequest(cwd, run.branch, { declared: run.gitHost ?? null }));
   } else {
     result = `This runner does not know how to ${action.kind}.`;
   }
@@ -3685,6 +3753,7 @@ async function performWorkspaceRequest(config, request, afterTheTreeMoved = null
       // squashes as it always did. The claim says which.
       ({ ok, result, failure: failureKind } = await mergePullRequest(cwd, branch, {
         method: request.mergeMethod ?? null,
+        declared: request.gitHost ?? null,
       }));
     }
   } else if (request.kind === 'TAG') {
@@ -3726,6 +3795,7 @@ async function performWorkspaceRequest(config, request, afterTheTreeMoved = null
         result = pushed.failed;
       } else {
         ({ ok, result } = await openPullRequestFor(cwd, {
+          declared: request.gitHost ?? null,
           branch,
           base,
           title: request.title?.trim() || branch,
@@ -3754,6 +3824,19 @@ async function performWorkspaceRequest(config, request, afterTheTreeMoved = null
       log(`  cutting ${name} on origin from ${request.defaultBranch || 'main'}`);
       ({ ok, result } = await cutBranchOnOrigin(cwd, name, request.defaultBranch));
     }
+  } else if (request.kind === 'CREATE_BRANCH') {
+    // R379. Put a named branch on origin, cut from another branch's tip. Unlike
+    // CUT_BRANCH an existing name is a REFUSAL: the person asked for a new
+    // branch, and one that is already there may be somebody else's work.
+    // Touches no working tree: the push names two refs and HEAD is neither.
+    const name = (request.message ?? '').trim();
+    const from = (request.fromBranch ?? '').trim();
+    if (!name || !from) {
+      result = 'A new branch has to name itself and the branch to cut it from. Nothing was created.';
+    } else {
+      log(`  creating ${name} on origin from ${from} — asked for from the console`);
+      ({ ok, result } = await createBranchOnOrigin(cwd, name, from));
+    }
   } else {
     result = `This runner does not know how to ${request.kind}.`;
   }
@@ -3920,27 +4003,30 @@ async function readPushState(cwd, branch) {
  * already holds the credentials, so the runner answers and the platform never
  * needs a token of its own.
  */
-async function findPullRequest(cwd, branch) {
-  const viaGh = await new Promise((resolvePromise) => {
-    const child = spawn('gh', ['pr', 'view', branch, '--json', 'url', '--jq', '.url'], {
-      cwd,
-      stdio: ['ignore', 'pipe', 'ignore'],
-    });
-    let out = '';
-    child.stdout.on('data', (chunk) => (out += chunk));
-    child.on('error', () => resolvePromise(null));
-    // `close`, not `exit` — see git() above.
-    child.on('close', (code) => resolvePromise(code === 0 ? out.trim() : null));
-  });
-  if (viaGh) {
-    return viaGh;
+async function findPullRequest(cwd, branch, { declared = null, base = null } = {}) {
+  const { host, adapter, originUrl } = await hostOf(cwd, declared);
+  const viaCli = await adapter.find(cwd, branch);
+  if (viaCli) {
+    return viaCli;
   }
 
-  // No gh, or no PR yet. A compare URL is honest: it is where you would go to
+  // No CLI, or no PR yet. A compare URL is honest: it is where you would go to
   // open one, and it is obviously not a claim that one exists.
-  const origin = await git(cwd, ['remote', 'get-url', 'origin']).catch(() => '');
-  const github = /github\.com[:/](.+?)(?:\.git)?$/.exec(origin.trim());
-  return github ? `https://github.com/${github[1]}/compare/${encodeURIComponent(branch)}` : null;
+  const repo = repoOf(originUrl);
+  const against = host === 'gitlab' && !base ? await defaultBranchOf(cwd) : base;
+  return adapter.fallbackLink(repo, against, branch);
+}
+
+/**
+ * Which host this checkout's origin is on, and the adapter that talks to it —
+ * R379. `declared` is the project's own word (`GITHUB`/`GITLAB`), from the claim
+ * or the request; with none, a GitLab-looking host is GitLab and everything else
+ * is GitHub, as it has always been.
+ */
+async function hostOf(cwd, declared) {
+  const originUrl = (await git(cwd, ['remote', 'get-url', 'origin']).catch(() => '')).trim();
+  const host = hostFor({ declared, originUrl });
+  return { host, adapter: adapterFor(host), originUrl };
 }
 
 // --- what a project's rules asked for (R40) ----------------------------------
@@ -3989,25 +4075,6 @@ async function firstRemote(cwd) {
   return remotes.split('\n')[0]?.trim() || null;
 }
 
-/** Runs `gh` and hands back everything it said, including on failure. */
-function gh(cwd, args) {
-  return new Promise((resolvePromise) => {
-    const child = spawn('gh', args, { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
-    let out = '';
-    let err = '';
-    child.stdout.on('data', (chunk) => (out += chunk));
-    child.stderr.on('data', (chunk) => (err += chunk));
-    child.on('error', (failure) => resolvePromise({
-      code: -1,
-      out: '',
-      err: failure.code === 'ENOENT'
-        ? 'gh is not installed on this machine, so it cannot talk to the git host.'
-        : failure.message,
-    }));
-    // `close`, not `exit` — see git() above.
-    child.on('close', (code) => resolvePromise({ code, out: out.trim(), err: err.trim() }));
-  });
-}
 
 /**
  * The branch, on the remote.
@@ -4087,6 +4154,7 @@ async function openPullRequest(cwd, run, title) {
   }
 
   return openPullRequestFor(cwd, {
+    declared: run.gitHost ?? null,
     branch: run.branch,
     // R260. The sprint's branch, when the claim carried one; otherwise the
     // argv is byte for byte what it was and the host picks its own default.
@@ -4157,44 +4225,40 @@ async function pushIfOriginLacks(cwd, branch) {
   }
 }
 
-async function openPullRequestFor(cwd, { branch, base, title, body }) {
-  const existing = await findPullRequest(cwd, branch).catch(() => null);
+async function openPullRequestFor(cwd, { branch, base, title, body, declared = null }) {
+  const { adapter } = await hostOf(cwd, declared);
+  const existing = await findPullRequest(cwd, branch, { declared, base }).catch(() => null);
   if (existing && !existing.includes('/compare/')) {
     return { ok: true, result: existing };
   }
 
-  const opened = await gh(cwd, [
-    'pr', 'create',
-    '--head', branch,
-    ...(base ? ['--base', base] : []),
-    '--title', title,
-    '--body', body,
-  ]);
+  // R379: `gh pr create` or `glab mr create`; for GitHub it is the argv it always was.
+  const opened = await adapter.create(cwd, { branch, base, title, body });
   if (opened.code === 0 && opened.out) {
-    // gh prints the URL and nothing else on success — and then the host is
-    // asked whether it is really there, because "asked for" is not "made",
-    // and a URL on the card that 404s is worse than an honest failure.
-    const printed = opened.out.split('\n').pop().trim();
-    const confirmed = await findPullRequest(cwd, branch).catch(() => null);
+    // The CLI prints the URL and the host is then asked whether it is really
+    // there, because "asked for" is not "made", and a URL on the card that
+    // 404s is worse than an honest failure.
+    const printed = adapter.urlOf(opened);
+    const confirmed = await findPullRequest(cwd, branch, { declared, base }).catch(() => null);
     if (confirmed && !confirmed.includes('/compare/')) {
       return { ok: true, result: confirmed };
     }
     return {
       ok: false,
-      result: `gh said it opened ${printed}, but the host does not show a pull request for ${branch}.`,
+      result: `${adapter.bin} said it opened ${printed}, but the host does not show a ${adapter.noun} for ${branch}.`,
     };
   }
   // The one failure somebody can fix in a minute, said with the fix — and the
-  // link to open it by hand meanwhile, which `findPullRequest` builds without gh.
+  // link to open it by hand meanwhile, which `findPullRequest` builds without the CLI.
   if (opened.code === -1 && /not installed/.test(opened.err)) {
-    const compare = await findPullRequest(cwd, branch).catch(() => null);
+    const compare = await findPullRequest(cwd, branch, { declared, base }).catch(() => null);
     return {
       ok: false,
-      result: `${opened.err} Install it and sign in (brew install gh && gh auth login), `
+      result: `${opened.err} Install it and sign in (${adapter.installHint}), `
         + `then ask again${compare ? ` — or open it yourself: ${compare}` : '.'}`,
     };
   }
-  return { ok: false, result: opened.err || opened.out || 'gh pr create failed without saying why.' };
+  return { ok: false, result: opened.err || opened.out || `${adapter.bin} ${adapter.name === 'gitlab' ? 'mr' : 'pr'} create failed without saying why.` };
 }
 
 /**
@@ -4245,18 +4309,27 @@ function mergeabilityWaitMs() {
   return Number.isFinite(configured) && configured > 0 ? configured : 5000;
 }
 
-async function mergePullRequest(cwd, branch, { method = null } = {}) {
-  const url = await findPullRequest(cwd, branch).catch(() => null);
+async function mergePullRequest(cwd, branch, { method = null, declared = null } = {}) {
+  const { adapter } = await hostOf(cwd, declared);
+  const url = await findPullRequest(cwd, branch, { declared }).catch(() => null);
   if (!url || url.includes('/compare/')) {
+    // R379. On GitLab a missing `glab` looks exactly like "no merge request" —
+    // the lookup that would have found it never ran. Said as what it is.
+    if (adapter.name === 'gitlab') {
+      const probe = await adapter.run(cwd, ['--version']);
+      if (probe.code === -1) {
+        return { ok: false, failure: 'UNREACHABLE', result: probe.err };
+      }
+    }
     return {
       ok: false,
       failure: 'NO_PULL_REQUEST',
       result: 'There is no pull request for this branch to merge. Nothing was merged.',
     };
   }
-  await waitOutUnknownMergeability(cwd, url, branch);
+  await waitOutUnknownMergeability(cwd, url, branch, adapter);
   const mergeCommit = method === 'MERGE_COMMIT';
-  const merged = await gh(cwd, ['pr', 'merge', url, mergeCommit ? '--merge' : '--squash', '--delete-branch']);
+  const merged = await adapter.merge(cwd, url, { mergeCommit });
   if (merged.code === 0) {
     // The URL on its own FIRST LINE — R134. The platform reads that line as the
     // evidence a merge happened and puts it on the card as the card's `merge`
@@ -4273,10 +4346,10 @@ async function mergePullRequest(cwd, branch, { method = null } = {}) {
     ok: false,
     // R155. WHICH kind of failure, so the console can offer Merge with an agent
     // on the one an agent can fix and stay quiet on the three it cannot.
-    failure: await classifyMergeFailure(cwd, url, merged),
+    failure: await classifyMergeFailure(cwd, url, merged, adapter),
     // Unchanged: `gh`'s own words still reach the card. The classification is a
     // word beside them, never a replacement for them.
-    result: merged.err || merged.out || 'gh pr merge failed without saying why.',
+    result: merged.err || merged.out || `${adapter.bin} ${adapter.name === 'gitlab' ? 'mr' : 'pr'} merge failed without saying why.`,
   };
 }
 
@@ -4285,19 +4358,12 @@ async function mergePullRequest(cwd, branch, { method = null } = {}) {
  * bounded. See `mergePullRequest`. One log line if it waited at all, so a
  * merge that took thirty seconds says why.
  */
-async function waitOutUnknownMergeability(cwd, url, branch) {
+async function waitOutUnknownMergeability(cwd, url, branch, adapter) {
   let waited = 0;
   for (let poll = 0; poll < MERGEABILITY_POLLS; poll++) {
-    const asked = await gh(cwd, ['pr', 'view', url, '--json', 'mergeable,mergeStateStatus']);
-    if (asked.code !== 0) return;
-    let view;
-    try {
-      view = JSON.parse(asked.out || '{}');
-    } catch {
-      // Not JSON — a gh that answered something else. Nothing to wait for.
-      return;
-    }
-    if (view.mergeable !== 'UNKNOWN') {
+    // `UNKNOWN` is the only answer worth waiting out; an error, something that
+    // is not JSON or any other word proceeds at once (the adapter says which).
+    if ((await adapter.mergeability(cwd, url)) !== 'UNKNOWN') {
       if (waited) log(`  ${branch}: mergeability known after ${waited}s`);
       return;
     }
@@ -4401,6 +4467,67 @@ async function cutBranchOnOrigin(cwd, name, defaultBranch) {
   return { ok: true, result: `${tip}\n${name} cut from ${from} at ${tip.slice(0, 7)}.` };
 }
 
+/**
+ * Creates a branch on origin, cut from another — R379's `CREATE_BRANCH`.
+ *
+ * Order matters: the name is checked before anything is asked of the remote,
+ * an existing name is refused whatever it points at, and the source is read
+ * from `origin/<from>` after a fetch — what everyone else has, not this
+ * checkout's idea of it. The sha is the FIRST LINE of an ok result, the way a
+ * tag check reports it, because the platform does not take a machine's word.
+ */
+async function createBranchOnOrigin(cwd, name, from) {
+  await git(cwd, ['fetch', '--prune', 'origin']).catch((failure) => {
+    log(`  fetch skipped: ${failure.message.split('\n')[0]}`);
+  });
+  try {
+    await git(cwd, ['check-ref-format', '--branch', name]);
+    // `@{-1}` passes check-ref-format --branch (it expands), but is no name.
+    if (/[~^@]/.test(name)) throw new Error('not a name');
+  } catch {
+    return { ok: false, result: `\`${name}\` is not a branch name git accepts. Nothing was created.` };
+  }
+
+  const ref = `refs/heads/${name}`;
+  let there;
+  try {
+    there = await git(cwd, ['ls-remote', '--heads', 'origin', ref]);
+  } catch (failure) {
+    return { ok: false, result: `Could not ask the remote about ${name}: ${failure.message}` };
+  }
+  const already = there.split('\n').map((each) => each.trim()).filter(Boolean)
+    .find((each) => each.endsWith(`\t${ref}`));
+  if (already) {
+    return {
+      ok: false,
+      result: `\`${name}\` is already on origin at ${already.split(/\s+/)[0].slice(0, 7)}. Nothing was created.`,
+    };
+  }
+
+  // `from` is a branch NAME: `main~3` or `main@{1}` would resolve and be pushed.
+  try {
+    await git(cwd, ['check-ref-format', '--branch', from]);
+  } catch {
+    return { ok: false, result: `\`${from}\` is not a branch name git accepts. Nothing was created.` };
+  }
+  if (/[~^@]/.test(from)) {
+    return { ok: false, result: `\`${from}\` is not a branch name. Nothing was created.` };
+  }
+  const source = `origin/${from}`;
+  let tip;
+  try {
+    tip = (await git(cwd, ['rev-parse', '--verify', `${source}^{commit}`])).trim();
+  } catch {
+    return { ok: false, result: `${source} is not on origin, so there is nothing to create \`${name}\` from.` };
+  }
+  try {
+    await git(cwd, ['push', 'origin', `${source}:${ref}`]);
+  } catch (failure) {
+    return { ok: false, result: `Could not push ${name}: ${failure.message}` };
+  }
+  return { ok: true, result: `${tip}\n${name} created from ${from} at ${tip.slice(0, 7)}.` };
+}
+
 /**
  * Why `gh pr merge` said no — R155, in one of five words.
  *
@@ -4417,9 +4544,9 @@ async function cutBranchOnOrigin(cwd, name, defaultBranch) {
  * as OTHER, and the console offers the action for OTHER for the same reason it
  * offers it for a null — the cost of being wrong is one `git fetch`.
  */
-async function classifyMergeFailure(cwd, url, merged) {
-  // No process at all, or the host was unreachable. `gh()` reports a spawn
-  // error as code -1, which covers "gh is not installed" as well.
+async function classifyMergeFailure(cwd, url, merged, adapter) {
+  // No process at all, or the host was unreachable. The CLI runner reports a
+  // spawn error as code -1, which covers "gh/glab is not installed" as well.
   if (merged.code === -1 || /ENOTFOUND|ECONNREFUSED|ETIMEDOUT|could not resolve host|network is unreachable/i
       .test(`${merged.err} ${merged.out}`)) {
     return 'UNREACHABLE';
@@ -4429,24 +4556,10 @@ async function classifyMergeFailure(cwd, url, merged) {
     return 'NOT_PERMITTED';
   }
 
-  // The house style for asking gh a question — the same `--json` shape the merge
-  // pass already parses. A failure to answer is not an answer, so it falls
-  // through to OTHER rather than inventing one.
-  const asked = await gh(cwd, ['pr', 'view', url, '--json', 'mergeable,mergeStateStatus']);
-  if (asked.code === 0) {
-    try {
-      const view = JSON.parse(asked.out || '{}');
-      if (view.mergeable === 'CONFLICTING' || view.mergeStateStatus === 'DIRTY') {
-        return 'CONFLICT';
-      }
-      if (view.mergeStateStatus === 'BLOCKED') {
-        return 'NOT_PERMITTED';
-      }
-    } catch {
-      // gh answered with something that is not JSON. Nothing to read.
-    }
-  }
-  return 'OTHER';
+  // Asked of the host's own CLI (R379: through the adapter). A failure to
+  // answer is not an answer, so it falls through to OTHER rather than
+  // inventing one.
+  return (await adapter.refusal(cwd, url)) ?? 'OTHER';
 }
 
 /**
@@ -4744,7 +4857,7 @@ async function checkRunMerges(config, pending, fetched) {
     }
     // Same argument as the git survey: read a checkout nobody is working in.
     const heldNow = heldWorkspaces();
-    const cwd = project.workspaces.find((candidate) => !heldNow.has(candidate))
+    const cwd = (await usableWorkspace(project, heldNow, new Map()))
       ?? resolve(project.path);
 
     try {
@@ -4806,7 +4919,7 @@ async function checkWorkItemMerges(config, fetched) {
       continue;
     }
     const heldNow = heldWorkspaces();
-    const cwd = project.workspaces.find((candidate) => !heldNow.has(candidate))
+    const cwd = (await usableWorkspace(project, heldNow, new Map()))
       ?? resolve(project.path);
     try {
       await access(join(cwd, '.git'));
@@ -4856,7 +4969,7 @@ async function reportCommits(config, run, cwd, base) {
   // Only worth looking for a PR once something has been pushed: a branch that
   // has never left the machine cannot have one.
   const prUrl = pushState === 'PUSHED' || pushState === 'AHEAD'
-    ? await findPullRequest(cwd, run.branch).catch(() => null)
+    ? await findPullRequest(cwd, run.branch, { declared: run.gitHost ?? null, base: run.baseBranch ?? null }).catch(() => null)
     : null;
 
   await api(config, `/api/projects/${run.projectSlug}/runs/${run.id}/commits`, {
@@ -5406,7 +5519,9 @@ const ASK_DONT_STOP = 'If a decision is genuinely the person\'s — a scope the
  */
 const WAIT_FOR_COMMANDS = 'This stage ends when your turn ends: run every command in the '
   + 'foreground and wait for it to finish — a build or a test suite left running in the '
-  + 'background is lost, and the stage is run again.';
+  + 'background is lost, and the stage is run again. The same goes for delegating: call '
+  + '`Agent` with `run_in_background: false` and wait for its answer — an agent still '
+  + 'working when your turn ends has its work lost, and the stage is run again.';
 
 /**
  * @param hasPlan whether the card has a plan of record — the same test
@@ -6277,7 +6392,7 @@ function heldWorkspaces() {
  * they read refs, never the tree, so which checkout they pick is a different
  * question and dirtiness does not bear on it.
  */
-async function pickWorkspace(slug, project, offered, held, probed, autoMax = 0) {
+async function pickWorkspace(slug, project, offered, held, probed, autoMax = 0, problems = new Map()) {
   const pinned = offered.workspace ?? null;
   if (pinned) {
     if (!project.workspaces.includes(pinned)) {
@@ -6286,6 +6401,15 @@ async function pickWorkspace(slug, project, offered, held, probed, autoMax = 0)
       // thing to say out loud rather than quietly ignore.
       return { workspace: null, why: `its branch is in ${pinned}, which this machine does not serve` };
     }
+    // Before the busy check, so the reason is the folder's own sentence and not
+    // prepareWorkingCopy's raw error.
+    const trouble = await problemOf(problems, pinned);
+    if (trouble) {
+      return {
+        workspace: null,
+        why: workspaceProblemSaid(slug, trouble, { first: project.workspaces[0] }),
+      };
+    }
     if (held.has(pinned)) {
       return {
         workspace: null,
@@ -6297,7 +6421,8 @@ async function pickWorkspace(slug, project, offered, held, probed, autoMax = 0)
 
   const waitForClean = offered.waitForClean === true;
   const preferred = offered.preferredWorkspace ?? null;
-  if (preferred && project.workspaces.includes(preferred) && !held.has(preferred)) {
+  if (preferred && project.workspaces.includes(preferred) && !held.has(preferred)
+      && !(await problemOf(problems, preferred))) {
     if (!waitForClean) {
       return { workspace: preferred, why: null };
     }
@@ -6305,13 +6430,29 @@ async function pickWorkspace(slug, project, offered, held, probed, autoMax = 0)
     if (probed.get(preferred) === true) return { workspace: preferred, why: null };
   }
 
-  const free = project.workspaces.filter((path) => !held.has(path));
+  const broken = [];
+  for (const path of project.workspaces) {
+    const trouble = await problemOf(problems, path);
+    if (trouble) broken.push(trouble);
+  }
+  const first = project.workspaces[0];
+  const usable = project.workspaces.filter((path) => !broken.some((each) => each.path === path));
+  if (!usable.length && broken.length) {
+    // Nothing here can be used at all — said before "all busy", and without
+    // trying to clone: `createAutoWorkspace` clones FROM the first workspace.
+    return { workspace: null, why: workspaceProblemSaid(slug, broken[0], { first }) };
+  }
+  const free = usable.filter((path) => !held.has(path));
   if (!free.length) {
     // Every checkout is busy. Where the machine allows it, make one more
     // rather than wait — the second coding session on a project starting at
     // once is the whole point of `autoWorkspaces`.
-    const first = project.workspaces[0];
-    const made = project.workspaces.filter((path) => isAutoWorkspace(first, path));
+    // A deleted clone must not use up the quota until `syncAutoWorkspaces` runs.
+    const made = usable.filter((path) => isAutoWorkspace(first, path));
+    const firstTrouble = broken.find((each) => each.path === first);
+    if (firstTrouble && made.length < autoMax) {
+      return { workspace: null, why: workspaceProblemSaid(slug, firstTrouble, { first }) };
+    }
     if (made.length < autoMax) {
       try {
         log(`every checkout of ${slug} is busy — cloning another beside ${first}`);
@@ -6433,12 +6574,12 @@ function snapshotRuns() {
   return runs;
 }
 
-async function startRun(config, offered, workspace) {
+async function startRun(config, offered, workspace, source = null) {
   const run = offered.run;
   const project = config.projects[run.projectSlug];
   // The workspace this run was given, or — for a run that takes none — the
   // first, which is where a question about the project gets read from.
-  const path = workspace ?? project?.path;
+  const path = workspace ?? source ?? project?.path;
   let runToken;
   let defaultBranch;
   let allowDirty = false;
@@ -6509,6 +6650,8 @@ async function startRun(config, offered, workspace) {
     // a reset, the code map and the brief read. Null on every run until a
     // sprint has a branch — and then everything below is what it was.
     run.baseBranch = claimed.baseBranch ?? null;
+    // R379. The project's declared git host (GITHUB/GITLAB), or null to detect it.
+    run.gitHost = claimed.gitHost ?? null;
     if (run.baseBranch) {
       log(`  cut from ${run.baseBranch} (the sprint's branch)`);
     }
@@ -6594,6 +6737,16 @@ async function startRun(config, offered, workspace) {
   let cwd = path ? resolve(path) : path;
   let reader = null;
   try {
+    // R377. The folder was fine when the run was offered; it may not be now.
+    // Checked before anything is prepared, so the run says what is wrong with
+    // the folder instead of `is not a git repository` or `spawn claude ENOENT`.
+    // One check covers every walked stage, which reuse this `cwd`.
+    const trouble = path ? await workspaceProblem(resolve(path)) : null;
+    if (trouble && !(trouble.kind === 'not-git' && !writesCodeProfile(run))) {
+      throw new Error(workspaceProblemSaid(run.projectSlug, trouble, {
+        first: project?.workspaces?.[0] ?? null,
+      }));
+    }
     let branch = run.branch;
     if (!writesCodeProfile(run)) {
       // Nothing is prepared. It cuts no branch, and a dirty tree does not stop
@@ -6825,9 +6978,10 @@ async function walkLifecycle(config, run, runToken, cwd, baseCommit, workspace,
     if (before?.state === 'FAILED' && before.outcome) {
       // The attempt that stopped, handed to the one about to run.
       carried[`${stage.stage} (the attempt that stopped)`] = `${before.outcome}\n\n`
-        + 'This stage is being run again to finish that. Run the commands it left running '
-        + 'again IN THE FOREGROUND — not with run_in_background — wait for each one to end '
-        + 'and read its output, then finish the stage properly.';
+        + 'This stage is being run again to finish that. Run the commands — and the agents — '
+        + 'it left running again IN THE FOREGROUND — not with run_in_background — wait for '
+        + 'each one to end and read its output, then finish the stage properly. Check the '
+        + 'checkout first: a background agent may have left part of its work there.';
     }
     // R305. What THIS stage's processes have used, across its attempts. Outside
     // the attempt loop on purpose: `run_stage` is one row per stage and keeps
@@ -6945,7 +7099,7 @@ async function walkLifecycle(config, run, runToken, cwd, baseCommit, workspace,
       // /continue picks the run up HERE — the stages behind it stay pending.
       if (last?.unfinishedShells?.length) {
         const listed = last.unfinishedShells.map((command) => `\`${command.slice(0, 120)}\``).join(', ');
-        const why = `The ${stage.stage} stage ended with ${last.unfinishedShells.length} command(s) `
+        const why = `The ${stage.stage} stage ended with ${last.unfinishedShells.length} command(s) or agent(s) `
           + `still running in the background, or finished and never read: ${listed}. `
           + 'Nothing they proved was recorded — /continue runs this stage again and waits for them.';
         log(`  ${why}`);
@@ -8118,7 +8272,12 @@ async function spawnAgent(config, run, runToken, cwd, baseCommit, workspace, res
       prompts.stop();
       workingCopy.stop();
       await transcript.flush();
-      await finish(config, run, 'FAILED', `Could not spawn the agent: ${failure.message}`);
+      // Under a memory ceiling (`sessionScope`) the child is `systemd-run`, so a
+      // missing `claude` arrives as its exit code and never as an ENOENT here.
+      await finish(config, run, 'FAILED', spawnFailureSaid({
+        failure, command: agentCmd, cwd, slug: run.projectSlug, label: 'the agent',
+        first: config.projects[run.projectSlug]?.workspaces?.[0],
+      }));
       await rm(mcpDirectory, { recursive: true, force: true });
       clearTimeout(idleTimer);
       // A spawn that never happened has no exit code. The run is already
@@ -8788,7 +8947,10 @@ async function spawnAntigravity(config, run, runToken, cwd, baseCommit, resume,
     child.on('error', async (failure) => {
       workingCopy.stop();
       running.delete(run.id);
-      const summary = `Could not spawn Antigravity: ${failure.message}`;
+      const summary = spawnFailureSaid({
+        failure, command: agyCmd, cwd, slug: run.projectSlug, label: 'Antigravity',
+        first: config.projects[run.projectSlug]?.workspaces?.[0],
+      });
       await transcript.flush();
       await finish(config, run, 'FAILED', summary);
       resolvePromise(
@@ -9106,7 +9268,10 @@ async function spawnCodex(config, run, runToken, cwd, baseCommit, resume, projec
     child.on('error', async (failure) => {
       workingCopy.stop();
       running.delete(run.id);
-      const summary = `Could not spawn Codex: ${failure.message}`;
+      const summary = spawnFailureSaid({
+        failure, command: codexCmd, cwd, slug: run.projectSlug, label: 'Codex',
+        first: config.projects[run.projectSlug]?.workspaces?.[0],
+      });
       await transcript.flush();
       await finish(config, run, 'FAILED', summary);
       resolvePromise(stage ? { code: -1, signal: null, text: summary, turnEnded: false } : undefined);
@@ -9390,6 +9555,12 @@ function capabilities(config) {
     // that, so the platform tells it apart rather than letting one behave
     // like the other.
     waitForClean: true,
+    // R379. This daemon knows `CREATE_BRANCH` (a branch put on origin, cut from
+    // another branch) and can open, find and merge a GitLab merge request with
+    // `glab`. An older daemon would fail the unknown kind, so the platform
+    // hands the request only to a daemon that says so.
+    createBranch: true,
+    gitHosts: ['github', 'gitlab'],
   });
 }
 
@@ -9541,6 +9712,7 @@ async function main() {
       log(`quality: ${slug} scans with ${project.quality.command} after TEST, token from $${project.quality.tokenEnv}`);
     }
   }
+  await sayWhichWorkspacesCannotBeUsed(config);
   await sayWhichServedProjectsTheTokenCannotReach(config);
 
   // Frozen here, before anything can be claimed. A run that checks this very
@@ -9673,6 +9845,9 @@ async function main() {
       // A checkout made on demand may have been dropped — the attached
       // terminal's `/drop` deletes the directory and sends this signal.
       await syncAutoWorkspaces(config.projects, heldWorkspaces());
+      if (await sayWhichWorkspacesCannotBeUsed(config)) {
+        log('  (the project list itself is read at start — restart the daemon after changing "workspaces")');
+      }
       Object.assign(config, resolved);
       // R288: the hello describes the current state, not the booted one — an
       // attach opened after a toggle would otherwise offer to turn on what is
@@ -9996,6 +10171,7 @@ async function main() {
       // Several offers of one project ask `looksClean` on a shared checkout
       // only once.
       const probed = new Map();
+      const problems = new Map();
 
       let claimable = 0;
       let skipped = 0;
@@ -10063,15 +10239,30 @@ async function main() {
         // adding to `told.heldWorkspaces` mid-loop — is the same window that
         // already exists between this poll and `startRun`'s own claim.
         let workspace = null;
+        let source = null;
         if (writes) {
           const picked = await pickWorkspace(slug, config.projects[slug], offered, held, probed,
-            config.autoWorkspaces);
+            config.autoWorkspaces, problems);
           if (picked.why) {
             noteQueued(offered.run, picked.why);
             skipped += 1;
             continue;
           }
           workspace = picked.workspace;
+        } else {
+          // Reads from a usable folder, and holds none: the source goes to
+          // `startRun` on its own and never into `held` or `taken` (R70).
+          const project = config.projects[slug];
+          source = await usableWorkspace(project, new Set(), problems, { reading: true });
+          if (!source) {
+            const first = project.workspaces[0];
+            const trouble = await problemOf(problems, first);
+            noteQueued(offered.run, trouble
+              ? workspaceProblemSaid(slug, trouble, { first })
+              : `${slug} has no workspace on this machine`);
+            skipped += 1;
+            continue;
+          }
         }
         if (workspace) {
           held.add(workspace);
@@ -10084,7 +10275,7 @@ async function main() {
         });
         noted.delete(offered.run.id);
         claimable += 1;
-        void startRun(config, offered, workspace);
+        void startRun(config, offered, workspace, source);
       }
 
       // Forget runs that are no longer offered, so one that comes back around