automata-cli 0.8.0-develop.353 → 0.8.0-develop.368

package/dist/index.js

@@ -1175,6 +1175,32 @@ function resolveReleaseVersion(requested, trunkRef, latestTag) {
   return { ok: true, version: version2, notice: `Auto-detected version: ${latest} \u2192 ${version2}` };
 }
 
+// src/git/changelogGate.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { join } from "path";
+var CHANGELOG_FILE = "CHANGELOG.md";
+var VERSION_HEADING = /^## \[(\d+\.\d+\.\d+)\] - \d{4}-\d{2}-\d{2}$/;
+function checkChangelogSection(version2, changelog) {
+  if (changelog === null) {
+    return { ok: true };
+  }
+  const documented = changelog.split("\n").map((line) => VERSION_HEADING.exec(line.trimEnd())).some((match) => match !== null && match[1] === version2);
+  if (documented) {
+    return { ok: true };
+  }
+  return {
+    ok: false,
+    message: `${CHANGELOG_FILE} has no section for ${version2}. Add a '## [${version2}] - YYYY-MM-DD' heading \u2014 rename the current '## [Unreleased]' heading to it and open a fresh, empty '## [Unreleased]' above \u2014 then commit and re-run. See docs/maintenance.md#what-a-release-does-to-it.`
+  };
+}
+function readChangelog(dir = process.cwd()) {
+  try {
+    return readFileSync2(join(dir, CHANGELOG_FILE), "utf8");
+  } catch {
+    return null;
+  }
+}
+
 // src/commands/git.ts
 var FAIL_CONCLUSIONS = /* @__PURE__ */ new Set(["FAILURE", "TIMED_OUT", "ACTION_REQUIRED", "CANCELLED"]);
 var SKIP_CONCLUSIONS = /* @__PURE__ */ new Set(["SKIPPED", "NEUTRAL"]);
@@ -1556,7 +1582,12 @@ Tags are fetched from origin first, in --dry-run too, so the version a dry run
 prints is the one a real run would use.
 
 When [version] is omitted the latest semver tag on origin/<trunk> is detected
-and the minor segment is incremented (e.g. 1.2.0 \u2192 1.3.0).`
+and the minor segment is incremented (e.g. 1.2.0 \u2192 1.3.0).
+
+CHANGELOG.md must already carry a '## [<version>] - YYYY-MM-DD' section for the
+version being released; the release is refused otherwise, in --dry-run too, and
+before any branch, merge or tag is created. A repository with no CHANGELOG.md is
+not subject to the check.`
 ).action((version2, options) => {
   const dryRun = options.dryRun ?? false;
   const preconditions = checkReleasePreconditions();
@@ -1595,6 +1626,12 @@ ${fetched.message}
   }
   if (tagExists(resolvedVersion)) {
     process.stderr.write(`Error: Tag '${resolvedVersion}' already exists.
+`);
+    process.exit(1);
+  }
+  const changelog = checkChangelogSection(resolvedVersion, readChangelog());
+  if (!changelog.ok) {
+    process.stderr.write(`Error: ${changelog.message}
 `);
     process.exit(1);
   }
@@ -1831,10 +1868,16 @@ function getRepoSlug() {
   return { owner: match[1], repo: match[2] };
 }
 function getAuthenticatedLogin() {
-  const { stdout, status } = run4("gh", ["api", "user", "--jq", ".login"]);
-  if (status !== 0) return null;
+  const identity = getAuthenticatedIdentity();
+  return identity.kind === "login" ? identity.login : null;
+}
+function getAuthenticatedIdentity() {
+  const { stdout, stderr, status } = run4("gh", ["api", "user", "--jq", ".login"]);
+  if (status !== 0) {
+    return { kind: "unavailable", detail: stderr.trim() || `gh api user exited ${String(status)}` };
+  }
   const login2 = stdout.trim();
-  return login2.length > 0 ? login2 : null;
+  return login2.length > 0 ? { kind: "login", login: login2 } : { kind: "no-user" };
 }
 function listCandidateIssues(technique, value, limit) {
   const args = [
@@ -2234,10 +2277,27 @@ function parseCreatedPrUrl(stdout, head) {
 // src/claude/claudeService.ts
 import { spawn, spawnSync as spawnSync5 } from "child_process";
 import { createInterface } from "readline";
-import { existsSync as existsSync2 } from "fs";
-import { delimiter, join } from "path";
 
 // src/cli/spawnUtils.ts
+import { accessSync, constants, statSync } from "fs";
+import { delimiter, join as join2 } from "path";
+function resolveCommand(name) {
+  const pathDirs = (process.env["PATH"] ?? "").split(delimiter);
+  for (const dir of pathDirs) {
+    const candidate = join2(dir, name);
+    if (isLaunchable(candidate)) return candidate;
+  }
+  return name;
+}
+function isLaunchable(candidate) {
+  try {
+    if (!statSync(candidate).isFile()) return false;
+    accessSync(candidate, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
 var SHELL_SAFE = /^[A-Za-z0-9_@%+=:,./-]+$/;
 var ESCAPED_QUOTE = String.raw`'\''`;
 function shellQuote(arg) {
@@ -2261,8 +2321,10 @@ function handleSpawnError(error, toolName) {
 }
 function handleExitCode(status, toolName) {
   if (status === null) {
-    process.stderr.write(`Error: ${toolName} terminated abnormally (exit code is null, likely due to a signal).
-`);
+    process.stderr.write(
+      `Error: ${toolName} terminated abnormally (exit code is null, likely due to a signal).
+`
+    );
     process.exit(1);
   }
   if (status !== 0) {
@@ -2271,14 +2333,20 @@ function handleExitCode(status, toolName) {
     process.exit(status);
   }
 }
-function resolveEffortOption(value) {
-  if (value === void 0) return void 0;
+function normalizeEffortOption(value) {
+  if (value === void 0) return { ok: true, value: void 0 };
   const trimmed2 = value.trim();
-  if (trimmed2.length === 0) {
-    process.stderr.write("Error: --effort must be a non-empty level.\n");
+  if (trimmed2.length === 0) return { ok: false, error: "--effort must be a non-empty level." };
+  return { ok: true, value: trimmed2 };
+}
+function resolveEffortOption(value) {
+  const result = normalizeEffortOption(value);
+  if (!result.ok) {
+    process.stderr.write(`Error: ${result.error}
+`);
     process.exit(1);
   }
-  return trimmed2;
+  return result.value;
 }
 
 // src/cli/childRegistry.ts
@@ -2324,14 +2392,6 @@ async function terminateTrackedChildren(timeoutMs = 1e4, killGraceMs = 5e3) {
 }
 
 // src/claude/claudeService.ts
-function resolveCommand(name) {
-  const pathDirs = (process.env["PATH"] ?? "").split(delimiter);
-  for (const dir of pathDirs) {
-    const candidate = join(dir, name);
-    if (existsSync2(candidate)) return candidate;
-  }
-  return name;
-}
 function buildClaudeArgs(prompt, options = {}) {
   const args = [];
   if (options.yolo) args.push("--dangerously-skip-permissions");
@@ -2743,7 +2803,7 @@ function linkPrToIssue(issueNumber, commentUrl, askCopilotReview, agentUser) {
 }
 
 // src/commands/execute.ts
-import { readFileSync as readFileSync2 } from "fs";
+import { readFileSync as readFileSync3 } from "fs";
 import { Command as Command4 } from "commander";
 function readStdin() {
   return new Promise((resolve2, reject) => {
@@ -2766,7 +2826,7 @@ async function resolvePrompt(options) {
   if (hasFile) {
     const path = options.filePrompt;
     try {
-      return readFileSync2(path, "utf8");
+      return readFileSync3(path, "utf8");
     } catch {
       process.stderr.write(`Error: Cannot read file: ${path}
 `);
@@ -3133,6 +3193,16 @@ var executePromptCommand = new Command5("execute-prompt").description("Execute a
 // src/commands/doWork.ts
 import { Command as Command6 } from "commander";
 
+// src/github/identity.ts
+function identityProblemFor(login2, agentUser, allowedUsers) {
+  if (login2 === null) return null;
+  if (login2.toLowerCase() === agentUser.toLowerCase()) return null;
+  if (allowedUsers.some((user) => user.toLowerCase() === login2.toLowerCase())) {
+    return `\`gh\` is authenticated as "${login2}", which is listed in allowedUsers. Everything do-work posts would be attributed to an account that is allowed to instruct the agent, so its own marker comment would look like a new instruction and each tick would answer the previous tick forever. Authenticate \`gh\` as the agent account (${agentUser}) in this environment, or correct \`agentUser\`.`;
+  }
+  return `\`gh\` is authenticated as "${login2}" but agentUser is "${agentUser}". Comments posted under that identity are neither the agent's nor an authorized user's, so they are filtered out of the conversation: the answer boundary would never advance and the same message would start a run on every tick. Authenticate \`gh\` as the agent account (${agentUser}) in this environment, or correct \`agentUser\`.`;
+}
+
 // src/github/workDetection.ts
 var NO_ISSUE_MESSAGES = {
   messages: [],
@@ -3596,19 +3666,19 @@ function analyseAnswer(messages, p, marker, watermark) {
 }
 
 // src/run/runLock.ts
-import { writeFileSync, readFileSync as readFileSync3, unlinkSync, mkdirSync, renameSync, linkSync, statSync } from "fs";
+import { writeFileSync, readFileSync as readFileSync4, unlinkSync, mkdirSync, renameSync, linkSync, statSync as statSync2 } from "fs";
 import { randomUUID } from "crypto";
 import { hostname } from "os";
-import { join as join2 } from "path";
+import { join as join3 } from "path";
 var LOCK_DIR = ".automata";
 var LOCK_FILE = "automata.lock";
 var RUN_LOCK_RELATIVE_PATH = `${LOCK_DIR}/${LOCK_FILE}`;
 function lockPath() {
-  return join2(process.cwd(), LOCK_DIR, LOCK_FILE);
+  return join3(process.cwd(), LOCK_DIR, LOCK_FILE);
 }
 function processStartedAt(pid) {
   try {
-    const stat = readFileSync3(`/proc/${String(pid)}/stat`, "utf8");
+    const stat = readFileSync4(`/proc/${String(pid)}/stat`, "utf8");
     const afterComm = stat.slice(stat.lastIndexOf(")") + 2);
     const field = afterComm.split(" ")[19];
     return field === void 0 || field.length === 0 ? null : field;
@@ -3624,9 +3694,17 @@ function isAlive(pid) {
     return err.code === "EPERM";
   }
 }
+function readOwnerError(path) {
+  try {
+    readFileSync4(path, "utf8");
+    return null;
+  } catch (err) {
+    return err.message;
+  }
+}
 function readOwner(path) {
   try {
-    const parsed = JSON.parse(readFileSync3(path, "utf8"));
+    const parsed = JSON.parse(readFileSync4(path, "utf8"));
     if (typeof parsed.pid !== "number" || typeof parsed.startedAt !== "string") return null;
     return {
       pid: parsed.pid,
@@ -3727,7 +3805,7 @@ function publishLock(path, command, token) {
 function acquireRunLock(command, staleMinutes) {
   const path = lockPath();
   const token = randomUUID();
-  mkdirSync(join2(process.cwd(), LOCK_DIR), { recursive: true });
+  mkdirSync(join3(process.cwd(), LOCK_DIR), { recursive: true });
   if (publishLock(path, command, token)) {
     return { ok: true, handle: makeHandle(path, token) };
   }
@@ -3805,13 +3883,13 @@ function acquireClaim(path) {
 function claimIsAbandoned(claimPath) {
   let at = Number.NaN;
   try {
-    const raw = JSON.parse(readFileSync3(claimPath, "utf8"));
+    const raw = JSON.parse(readFileSync4(claimPath, "utf8"));
     if (raw.at !== void 0) at = Date.parse(raw.at);
   } catch {
   }
   if (Number.isNaN(at)) {
     try {
-      at = statSync(claimPath).mtimeMs;
+      at = statSync2(claimPath).mtimeMs;
     } catch {
       return true;
     }
@@ -3848,6 +3926,28 @@ function reclaim(path, command, token, expected) {
     }
   }
 }
+function heldForMs(owner, now) {
+  const startedAt = Date.parse(owner.startedAt);
+  return Number.isNaN(startedAt) ? null : now - startedAt;
+}
+function inspectRunLock(staleMinutes, now = Date.now()) {
+  const path = lockPath();
+  try {
+    statSync2(path);
+  } catch (err) {
+    if (err.code === "ENOENT") return { kind: "free" };
+    return { kind: "unreadable", detail: err.message };
+  }
+  const readError = readOwnerError(path);
+  if (readError !== null) return { kind: "unreadable", detail: readError };
+  const owner = readOwner(path);
+  if (isStale(owner, staleMinutes)) {
+    return { kind: "stale", owner, heldForMs: owner === null ? null : heldForMs(owner, now) };
+  }
+  const held = owner;
+  const kind = heldTooLong(held, staleMinutes) ? "suspect" : "held";
+  return { kind, owner: held, heldForMs: heldForMs(held, now) };
+}
 
 // src/git/workspaceService.ts
 function dirtyTree() {
@@ -3881,11 +3981,11 @@ function resetToForcePushedRemote(headRefName, previousRemoteSha) {
 }
 function rebaseOntoAlreadyAppliedRemote(headRefName) {
   const upstream = `refs/remotes/origin/${headRefName}`;
-  const divergence = describeDivergence(upstream, `refs/heads/${headRefName}`);
-  if (divergence === null) return null;
-  if (divergence.merges > 0) return null;
-  if (divergence.commits.length === 0) return null;
-  if (divergence.commits.some((commit) => !commit.alreadyUpstream)) return null;
+  const divergence2 = describeDivergence(upstream, `refs/heads/${headRefName}`);
+  if (divergence2 === null) return null;
+  if (divergence2.merges > 0) return null;
+  if (divergence2.commits.length === 0) return null;
+  if (divergence2.commits.some((commit) => !commit.alreadyUpstream)) return null;
   if (isRebaseInProgress()) {
     return {
       ok: false,
@@ -3922,18 +4022,18 @@ function rebaseOntoAlreadyAppliedRemote(headRefName) {
   return { ok: true, branch: headRefName, strategy: "rebase" };
 }
 function divergenceRefusal(headRefName, pullError) {
-  const divergence = describeDivergence(
+  const divergence2 = describeDivergence(
     `refs/remotes/origin/${headRefName}`,
     `refs/heads/${headRefName}`
   );
-  if (divergence === null) {
+  if (divergence2 === null) {
     return {
       ok: false,
       reason: "pull-failed",
       detail: `${pullError} \u2014 how the local ${headRefName} relates to origin/${headRefName} could not be established, so nothing was changed and ${headRefName} is untouched; inspect it with \`git log --oneline origin/${headRefName}...${headRefName}\` before deciding what to do`
     };
   }
-  const unpushedCount = divergence.commits.filter((c) => !c.alreadyUpstream).length + divergence.merges;
+  const unpushedCount = divergence2.commits.filter((c) => !c.alreadyUpstream).length + divergence2.merges;
   if (unpushedCount === 0) {
     return {
       ok: false,
@@ -4319,16 +4419,16 @@ function describeRescueRemains(rescue) {
 
 // src/run/operationLog.ts
 import {
-  accessSync,
+  accessSync as accessSync2,
   appendFileSync,
-  constants,
-  readFileSync as readFileSync4,
+  constants as constants2,
+  readFileSync as readFileSync5,
   renameSync as renameSync2,
   unlinkSync as unlinkSync2,
   writeFileSync as writeFileSync2
 } from "fs";
 import { randomUUID as randomUUID2 } from "crypto";
-import { dirname as dirname2, join as join3 } from "path";
+import { dirname as dirname2, join as join4 } from "path";
 var EXECUTION_LOG_FILE = "automata-execution.log";
 var WORK_LOG_FILE = "automata-work.log";
 var MAX_EXECUTION_LINES = 1e3;
@@ -4450,9 +4550,9 @@ function pruneOldRecords(content, now, maxAgeMs) {
   }).map((group) => group.lines.join("\n") + "\n").join("");
 }
 function appendWithRetention(dir, file, content, retain) {
-  const target = join3(dir, file);
+  const target = join4(dir, file);
   appendFileSync(target, content, "utf8");
-  const existing = readFileSync4(target, "utf8");
+  const existing = readFileSync5(target, "utf8");
   const retained = retain(existing);
   if (retained === existing) return;
   const temp = `${target}.${randomUUID2()}.tmp`;
@@ -4468,7 +4568,7 @@ function appendWithRetention(dir, file, content, retain) {
 }
 function recordTick(tick, dir = operationLogDirectory()) {
   try {
-    accessSync(dir, constants.W_OK);
+    accessSync2(dir, constants2.W_OK);
   } catch {
     return;
   }
@@ -4494,6 +4594,696 @@ function recordTick(tick, dir = operationLogDirectory()) {
   } catch {
   }
 }
+function isOutcome(value) {
+  return OUTCOMES.includes(value);
+}
+function readLogFile(path) {
+  try {
+    return { content: readFileSync5(path, "utf8"), error: null };
+  } catch (err) {
+    if (err.code === "ENOENT") return { content: null, error: null };
+    return { content: null, error: err.message };
+  }
+}
+function emptyResult(path, error, filtered) {
+  return { entries: [], present: false, error, skipped: 0, otherRepos: 0, filtered, path };
+}
+function isFiltered(want) {
+  return want !== void 0 && want !== null;
+}
+function matchesRepo(entryRepo, want) {
+  if (want === void 0 || want === null) return true;
+  return entryRepo === null || entryRepo === want;
+}
+function readInt(value) {
+  if (value === void 0) return 0;
+  if (!/^-?\d+$/.test(value)) return null;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) ? parsed : null;
+}
+function readDurationSeconds(value) {
+  if (value === void 0) return 0;
+  if (!/^\d+(?:\.\d+)?s?$/.test(value)) return null;
+  const parsed = Number.parseFloat(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+function parseExecutionLine(line) {
+  const fields = line.trim().split(" ").filter((field) => field.length > 0);
+  if (fields.length < 2) return null;
+  const timestamp = new Date(fields[0]);
+  if (Number.isNaN(timestamp.getTime())) return null;
+  const pairs = /* @__PURE__ */ new Map();
+  for (const field of fields.slice(2)) {
+    const eq = field.indexOf("=");
+    if (eq <= 0) continue;
+    pairs.set(field.slice(0, eq), field.slice(eq + 1));
+  }
+  const exit = readInt(pairs.get("exit"));
+  if (exit === null) return null;
+  const counts = {};
+  for (const outcome of OUTCOMES) {
+    const count = readInt(pairs.get(outcome));
+    if (count === null) return null;
+    counts[outcome] = count;
+  }
+  const items = readInt(pairs.get("items"));
+  const runs = readInt(pairs.get("runs"));
+  const durationSeconds = readDurationSeconds(pairs.get("dur"));
+  if (items === null || runs === null || durationSeconds === null) return null;
+  const repo = pairs.get("repo");
+  const note = pairs.get("note");
+  return {
+    timestamp,
+    command: fields[1],
+    repo: repo === void 0 || repo === "-" ? null : repo,
+    items,
+    counts,
+    runs,
+    exitCode: exit,
+    durationSeconds,
+    note: note === void 0 || note.length === 0 ? null : note
+  };
+}
+function readExecutionTicks(options = {}) {
+  const path = join4(options.dir ?? operationLogDirectory(), EXECUTION_LOG_FILE);
+  const { content, error } = readLogFile(path);
+  if (content === null) return emptyResult(path, error, isFiltered(options.repo));
+  const entries = [];
+  let skipped = 0;
+  let otherRepos = 0;
+  for (const line of content.split("\n")) {
+    if (line.trim().length === 0) continue;
+    const tick = parseExecutionLine(line);
+    if (tick === null) {
+      skipped++;
+      continue;
+    }
+    if (!matchesRepo(tick.repo, options.repo)) {
+      otherRepos++;
+      continue;
+    }
+    entries.push(tick);
+  }
+  entries.reverse();
+  return {
+    entries: options.limit === void 0 ? entries : entries.slice(0, options.limit),
+    present: true,
+    error: null,
+    skipped,
+    otherRepos,
+    filtered: isFiltered(options.repo),
+    path
+  };
+}
+var WORK_ITEM_LINE = /^(#\S+|PR #\S+) (\S+) (answered-no-reply|answered|skipped|failed|deferred)(?: \[([^\]]*)\])?(?: sync=(.*?))? — (.*)$/;
+function parseExecution(bracket) {
+  if (bracket === void 0) return { executor: null, model: null, effort: null };
+  const parts = bracket.split(" ").filter((part) => part.length > 0);
+  const executor = parts[0] ?? null;
+  const find = (key) => {
+    const hit = parts.find((part) => part.startsWith(`${key}=`));
+    return hit === void 0 ? null : hit.slice(key.length + 1);
+  };
+  return { executor, model: find("model"), effort: find("effort") };
+}
+function parseWorkHeader(line) {
+  const header = /^=== (\S+) (\S+) ===$/.exec(line);
+  if (header === null) return "not-a-header";
+  const timestamp = new Date(header[1]);
+  if (Number.isNaN(timestamp.getTime())) return null;
+  return { timestamp, repo: header[2] === "-" ? null : header[2], items: [] };
+}
+function parseWorkItem(line) {
+  const item = WORK_ITEM_LINE.exec(line);
+  if (item === null) return null;
+  return {
+    subject: item[1],
+    turn: item[2] === "-" ? null : item[2],
+    // The alternation in the pattern admits nothing else.
+    outcome: isOutcome(item[3]) ? item[3] : "skipped",
+    ...parseExecution(item[4]),
+    sync: item[5] === void 0 || item[5].length === 0 ? null : item[5],
+    detail: item[6]
+  };
+}
+function readWorkRecords(options = {}) {
+  const path = join4(options.dir ?? operationLogDirectory(), WORK_LOG_FILE);
+  const { content, error } = readLogFile(path);
+  if (content === null) return emptyResult(path, error, isFiltered(options.repo));
+  const entries = [];
+  let skipped = 0;
+  let otherRepos = 0;
+  let current = null;
+  const close = () => {
+    if (current === null) return;
+    if (matchesRepo(current.repo, options.repo)) {
+      entries.push(current);
+    } else {
+      otherRepos++;
+    }
+    current = null;
+  };
+  for (const line of content.split("\n")) {
+    if (line.trim().length === 0) continue;
+    const header = parseWorkHeader(line);
+    if (header === null) {
+      skipped++;
+      continue;
+    }
+    if (header !== "not-a-header") {
+      close();
+      current = header;
+      continue;
+    }
+    const item = parseWorkItem(line);
+    if (item === null || current === null) {
+      skipped++;
+      continue;
+    }
+    current.items.push(item);
+  }
+  close();
+  entries.reverse();
+  return {
+    entries: options.limit === void 0 ? entries : entries.slice(0, options.limit),
+    present: true,
+    error: null,
+    skipped,
+    otherRepos,
+    filtered: isFiltered(options.repo),
+    path
+  };
+}
+
+// src/git/repoStatus.ts
+import { spawnSync as spawnSync7 } from "child_process";
+var GIT_BIN = resolveCommand("git");
+function git(args) {
+  const result = spawnSync7(GIT_BIN, args, { encoding: "utf8" });
+  return {
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+    status: result.status ?? 1
+  };
+}
+function notARepo(baseBranch, detail) {
+  return {
+    branch: null,
+    head: null,
+    dirtyPaths: [],
+    statusError: null,
+    baseBranch,
+    baseLocal: false,
+    upstream: null,
+    upstreamTracked: false,
+    ahead: null,
+    behind: null,
+    refreshed: false,
+    fetchError: null,
+    error: detail
+  };
+}
+function isOwnLockFile(porcelainEntry) {
+  return porcelainEntry.slice(3).trim().endsWith(RUN_LOCK_RELATIVE_PATH);
+}
+function divergence(upstream, branch) {
+  const { stdout, status } = git([
+    "rev-list",
+    "--left-right",
+    "--count",
+    `${upstream}...${branch}`
+  ]);
+  if (status !== 0) return null;
+  const parts = stdout.trim().split(/\s+/);
+  if (parts.length < 2) return null;
+  const behind = Number.parseInt(parts[0], 10);
+  const ahead = Number.parseInt(parts[1], 10);
+  if (Number.isNaN(behind) || Number.isNaN(ahead)) return null;
+  return { ahead, behind };
+}
+function readHead() {
+  const head = git(["rev-parse", "--short", "HEAD"]);
+  if (head.status === 0) return { head: head.stdout.trim(), fatal: null };
+  if (git(["rev-parse", "--is-inside-work-tree"]).status === 0) return { head: null, fatal: null };
+  return { head: null, fatal: head.stderr.trim() || "not a git repository" };
+}
+function readDirtyPaths() {
+  const porcelain = git(["status", "--porcelain"]);
+  if (porcelain.status !== 0) {
+    return { paths: [], error: porcelain.stderr.trim() || "git status --porcelain failed" };
+  }
+  return {
+    paths: porcelain.stdout.split("\n").filter((line) => line.trim().length > 0).filter((line) => !isOwnLockFile(line)),
+    error: null
+  };
+}
+function refreshBase(baseBranch) {
+  const fetched = git([
+    "fetch",
+    "origin",
+    `+refs/heads/${baseBranch}:refs/remotes/origin/${baseBranch}`
+  ]);
+  if (fetched.status === 0) return { refreshed: true, fetchError: null };
+  return { refreshed: false, fetchError: fetched.stderr.trim() || "git fetch failed" };
+}
+function resolveUpstream(baseBranch, baseLocal) {
+  if (baseLocal) {
+    const configured = git([
+      "rev-parse",
+      "--abbrev-ref",
+      "--symbolic-full-name",
+      `${baseBranch}@{u}`
+    ]);
+    if (configured.status === 0) return { upstream: configured.stdout.trim(), tracked: true };
+  }
+  if (git(["rev-parse", "--verify", "--quiet", `refs/remotes/origin/${baseBranch}`]).status === 0) {
+    return { upstream: `origin/${baseBranch}`, tracked: false };
+  }
+  return { upstream: null, tracked: false };
+}
+function inspectRepoStatus(options) {
+  const { baseBranch } = options;
+  const { head, fatal } = readHead();
+  if (fatal !== null) return notARepo(baseBranch, fatal);
+  const symbolic = git(["symbolic-ref", "--quiet", "--short", "HEAD"]);
+  const branch = symbolic.status === 0 ? symbolic.stdout.trim() : null;
+  const { paths: dirtyPaths, error: statusError } = readDirtyPaths();
+  const baseLocal = git(["rev-parse", "--verify", "--quiet", `refs/heads/${baseBranch}`]).status === 0;
+  const { refreshed, fetchError } = options.fetch ? refreshBase(baseBranch) : { refreshed: false, fetchError: null };
+  const { upstream, tracked } = resolveUpstream(baseBranch, baseLocal);
+  const counts = baseLocal && upstream !== null ? divergence(upstream, baseBranch) : null;
+  return {
+    branch,
+    head,
+    dirtyPaths,
+    statusError,
+    baseBranch,
+    baseLocal,
+    upstream,
+    upstreamTracked: tracked,
+    ahead: counts?.ahead ?? null,
+    behind: counts?.behind ?? null,
+    refreshed,
+    fetchError,
+    error: null
+  };
+}
+
+// src/run/checkReport.ts
+var SECTION_ORDER = [
+  "lock",
+  "ticks",
+  "work",
+  "git",
+  "selection",
+  "environment"
+];
+var SECTION_TITLES = {
+  lock: "Run lock",
+  ticks: "Recent ticks",
+  work: "Last work",
+  git: "Repository",
+  selection: "Selection",
+  environment: "Environment"
+};
+function sectionTitle(id) {
+  return SECTION_TITLES[id];
+}
+var TICK_HISTORY = 20;
+var WORK_HISTORY = 3;
+var SILENCE_MULTIPLIER = 3;
+var MIN_INTERVALS = 3;
+function median(values) {
+  const sorted = [...values].sort((a, b) => a - b);
+  const middle = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 1 ? sorted[middle] : (sorted[middle - 1] + sorted[middle]) / 2;
+}
+function tickCadence(ticks, now) {
+  if (ticks.length === 0) return { medianIntervalMs: null, sinceNewestMs: null, silent: false };
+  const sinceNewestMs = now.getTime() - ticks[0].timestamp.getTime();
+  const intervals = [];
+  for (let i = 0; i + 1 < ticks.length; i++) {
+    const gap = ticks[i].timestamp.getTime() - ticks[i + 1].timestamp.getTime();
+    if (gap > 0) intervals.push(gap);
+  }
+  if (intervals.length < MIN_INTERVALS)
+    return { medianIntervalMs: null, sinceNewestMs, silent: false };
+  const medianIntervalMs = median(intervals);
+  return {
+    medianIntervalMs,
+    sinceNewestMs,
+    silent: sinceNewestMs > SILENCE_MULTIPLIER * medianIntervalMs
+  };
+}
+function describeDuration(ms) {
+  if (ms < 0) return "in the future";
+  const seconds = Math.floor(ms / 1e3);
+  if (seconds < 60) return `${String(seconds)}s`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${String(minutes)}m`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${String(hours)}h ${String(minutes % 60)}m`;
+  const days = Math.floor(hours / 24);
+  return `${String(days)}d ${String(hours % 24)}h`;
+}
+function build(id, lines, problems, data) {
+  return {
+    id,
+    title: SECTION_TITLES[id],
+    lines,
+    problems: problems.map((summary) => ({ section: id, summary })),
+    data
+  };
+}
+function describeOwner(owner) {
+  return `pid ${String(owner.pid)} on ${owner.host}, \`${owner.command}\`, since ${owner.startedAt}`;
+}
+function lockSection(status, staleMinutes) {
+  const data = { status: status.kind, staleMinutes };
+  switch (status.kind) {
+    case "free":
+      return build("lock", ["no tick is running in this checkout"], [], data);
+    case "held": {
+      const held = status.heldForMs === null ? "" : ` (${describeDuration(status.heldForMs)} so far)`;
+      return build("lock", [`a tick is running: ${describeOwner(status.owner)}${held}`], [], {
+        ...data,
+        owner: status.owner,
+        heldForMs: status.heldForMs
+      });
+    }
+    case "suspect": {
+      const held = status.heldForMs === null ? "unknown" : describeDuration(status.heldForMs);
+      return build(
+        "lock",
+        [`a tick has held the lock for ${held}: ${describeOwner(status.owner)}`],
+        [
+          `the run lock has been held longer than ${String(staleMinutes)} minutes by a process whose identity cannot be verified; if no executor is running, kill the holder or delete \`.automata/automata.lock\``
+        ],
+        { ...data, owner: status.owner, heldForMs: status.heldForMs }
+      );
+    }
+    case "stale":
+      return build(
+        "lock",
+        [
+          status.owner === null ? "a run lock exists but could not be parsed" : `a stale run lock is present: ${describeOwner(status.owner)}`
+        ],
+        [
+          "a stale run lock is present; the next tick reclaims it automatically, so no action is needed unless ticks keep being turned away"
+        ],
+        { ...data, owner: status.owner, heldForMs: status.heldForMs }
+      );
+    case "unreadable":
+      return build(
+        "lock",
+        [`the run lock could not be read: ${status.detail}`],
+        [`the run lock at \`.automata/automata.lock\` could not be read: ${status.detail}`],
+        { ...data, detail: status.detail }
+      );
+  }
+}
+function describeTick(tick, now) {
+  const counts = [
+    `answered=${String(tick.counts.answered)}`,
+    `no-reply=${String(tick.counts["answered-no-reply"])}`,
+    `skipped=${String(tick.counts.skipped)}`,
+    `failed=${String(tick.counts.failed)}`,
+    `deferred=${String(tick.counts.deferred)}`,
+    `runs=${String(tick.runs)}`
+  ].join(" ");
+  const note = tick.note === null ? "" : ` note=${tick.note}`;
+  const age = describeDuration(now.getTime() - tick.timestamp.getTime());
+  return `${tick.timestamp.toISOString()} (${age} ago) exit=${String(tick.exitCode)} ${counts}${note}`;
+}
+function describeMissingTicks(read) {
+  if (read.error !== null) {
+    return {
+      line: `the execution log could not be read: ${read.error}`,
+      problem: `the execution log \`${read.path}\` could not be read: ${read.error}`
+    };
+  }
+  if (!read.present) {
+    return {
+      line: `no execution log at ${read.path}`,
+      problem: `no execution log at \`${read.path}\` \u2014 no tick has ever run here, or automata cannot write to the workspace root; check that the scheduler runs \`do-work\` from inside the checkout`
+    };
+  }
+  if (read.entries.length === 0) {
+    return {
+      line: "the execution log holds no tick for this repository",
+      problem: "the execution log holds no tick for this repository \u2014 the scheduler has never successfully run `do-work` here"
+    };
+  }
+  return null;
+}
+function describeTickHistory(ticks, cadence, now, lines, problems) {
+  lines.push(`last tick: ${describeTick(ticks[0], now)}`);
+  if (ticks[0].exitCode !== 0) {
+    problems.push(
+      `the last tick exited ${String(ticks[0].exitCode)} \u2014 see \`Last work\` below and the work log for the item that failed`
+    );
+  }
+  const lockHeld = ticks.filter((tick) => tick.note === "lock-held").length;
+  const withRuns = ticks.filter((tick) => tick.runs > 0).length;
+  lines.push(
+    `history: ${String(ticks.length)} tick(s), ${String(withRuns)} invoked the executor, ${String(lockHeld)} were turned away by a held lock`
+  );
+  if (lockHeld === ticks.length && ticks.length > 1) {
+    problems.push(
+      "every recorded tick was turned away by a held run lock \u2014 a previous tick is wedged; see `Run lock` above"
+    );
+  }
+  if (cadence.medianIntervalMs === null) {
+    lines.push("cadence: not enough history to judge whether the scheduler is still firing");
+    return;
+  }
+  lines.push(`cadence: about one tick every ${describeDuration(cadence.medianIntervalMs)}`);
+  if (cadence.silent) {
+    problems.push(
+      `no tick for ${describeDuration(cadence.sinceNewestMs ?? 0)}, against a usual interval of ${describeDuration(cadence.medianIntervalMs)} \u2014 the scheduler appears to have stopped firing (automata does not manage the scheduler; check it on this host)`
+    );
+  }
+}
+function unfilteredLine(unit) {
+  return `not filtered by repository: the slug could not be resolved, so ${unit} from other checkouts may be shown`;
+}
+function tickSection(read, now) {
+  const lines = [];
+  const problems = [];
+  const ticks = read.entries;
+  const cadence = tickCadence(ticks, now);
+  const missing = describeMissingTicks(read);
+  if (missing !== null) {
+    lines.push(missing.line);
+    problems.push(missing.problem);
+  } else {
+    describeTickHistory(ticks, cadence, now, lines, problems);
+  }
+  if (!read.filtered && read.present) lines.push(unfilteredLine("line(s)"));
+  if (read.skipped > 0)
+    lines.push(`${String(read.skipped)} log line(s) could not be parsed and were ignored`);
+  if (read.otherRepos > 0)
+    lines.push(`${String(read.otherRepos)} line(s) belonged to another repository`);
+  return build("ticks", lines, problems, {
+    newest: ticks[0] ?? null,
+    history: ticks,
+    lockHeldCount: ticks.filter((tick) => tick.note === "lock-held").length,
+    medianIntervalMs: cadence.medianIntervalMs,
+    sinceNewestMs: cadence.sinceNewestMs,
+    silent: cadence.silent,
+    skipped: read.skipped,
+    otherRepos: read.otherRepos,
+    filtered: read.filtered,
+    logPath: read.path,
+    logPresent: read.present
+  });
+}
+function describeWorkItem(item) {
+  const how = item.executor === null ? "" : ` [${[item.executor, item.model, item.effort].filter((part) => part !== null).join(" ")}]`;
+  const sync = item.sync === null ? "" : ` sync=${item.sync}`;
+  return `  ${item.subject} ${item.turn ?? "-"} ${item.outcome}${how}${sync} \u2014 ${item.detail}`;
+}
+function describeWorkRecords(records, now) {
+  return records.flatMap((record) => [
+    `${record.timestamp.toISOString()} (${describeDuration(now.getTime() - record.timestamp.getTime())} ago)`,
+    ...record.items.map(describeWorkItem)
+  ]);
+}
+function workSection(read, now) {
+  const lines = [];
+  const problems = [];
+  const records = read.entries;
+  if (read.error !== null) {
+    lines.push(`the work log could not be read: ${read.error}`);
+    problems.push(`the work log \`${read.path}\` could not be read: ${read.error}`);
+  } else if (!read.present || records.length === 0) {
+    lines.push("no tick has invoked the executor in the retained window");
+  } else {
+    lines.push(...describeWorkRecords(records, now));
+  }
+  if (!read.filtered && read.present) lines.push(unfilteredLine("record(s)"));
+  if (read.skipped > 0)
+    lines.push(`${String(read.skipped)} log line(s) could not be parsed and were ignored`);
+  if (read.otherRepos > 0)
+    lines.push(`${String(read.otherRepos)} record(s) belonged to another repository`);
+  return build("work", lines, problems, {
+    records,
+    skipped: read.skipped,
+    otherRepos: read.otherRepos,
+    filtered: read.filtered,
+    logPath: read.path,
+    logPresent: read.present
+  });
+}
+function describeCheckout(status, lines, problems) {
+  if (status.branch === null) {
+    lines.push(`HEAD is detached at ${status.head ?? "an unknown commit"}`);
+    problems.push("HEAD is detached; the pre-flight expects a branch, so check one out");
+  } else {
+    const at = status.head === null ? "" : ` at ${status.head}`;
+    lines.push(`on ${status.branch}${at}`);
+  }
+  if (status.statusError !== null) {
+    lines.push(`the working tree could not be inspected: ${status.statusError}`);
+    problems.push(
+      `\`git status\` failed (${status.statusError}), so whether the working tree is clean is unknown; the pre-flight runs the same command and stops every item when it cannot answer`
+    );
+    return;
+  }
+  if (status.dirtyPaths.length === 0) {
+    lines.push("working tree is clean");
+    return;
+  }
+  lines.push(`working tree has ${String(status.dirtyPaths.length)} uncommitted change(s):`);
+  for (const path of status.dirtyPaths) lines.push(`  ${path}`);
+  problems.push(
+    `the working tree has ${String(status.dirtyPaths.length)} uncommitted change(s); the pre-flight will try to rescue them onto a branch, and every item skips as \`dirty-tree\` if that fails`
+  );
+}
+function describeBaseBranch(status, lines, problems) {
+  if (!status.baseLocal) {
+    lines.push(`base branch ${status.baseBranch} does not exist in this checkout`);
+    problems.push(
+      `the base branch \`${status.baseBranch}\` does not exist locally; either check it out or correct \`doWork.baseBranch\` with \`automata config set do-work-base-branch <branch>\``
+    );
+    return;
+  }
+  if (status.upstream === null) {
+    lines.push(`base branch ${status.baseBranch} has no upstream`);
+    problems.push(
+      `the base branch \`${status.baseBranch}\` has no upstream, so the pre-flight cannot fast-forward it`
+    );
+    return;
+  }
+  if (!status.upstreamTracked) {
+    lines.push(
+      `base branch ${status.baseBranch} has no tracking configuration; counted against ${status.upstream}`
+    );
+    problems.push(
+      `the base branch \`${status.baseBranch}\` has no upstream configured, so the pre-flight's \`git pull --ff-only\` fails even though ${status.upstream} exists; set it with \`git branch --set-upstream-to=${status.upstream} ${status.baseBranch}\``
+    );
+  }
+  const freshness = status.refreshed ? "" : " (not refreshed)";
+  const ahead = status.ahead === null ? "?" : String(status.ahead);
+  const behind = status.behind === null ? "?" : String(status.behind);
+  lines.push(
+    `base branch ${status.baseBranch} vs ${status.upstream}: ahead ${ahead}, behind ${behind}${freshness}`
+  );
+  if (status.ahead === null || status.behind === null) {
+    problems.push(
+      `the divergence of \`${status.baseBranch}\` from ${status.upstream} could not be read, so whether the pre-flight's fast-forward pull will succeed is unknown; try \`git rev-list --left-right --count ${status.upstream}...${status.baseBranch}\` to see git's own error`
+    );
+    return;
+  }
+  if (status.ahead === 0) return;
+  if (status.behind > 0) {
+    problems.push(
+      `the base branch \`${status.baseBranch}\` has diverged from ${status.upstream} (${String(status.ahead)} ahead, ${String(status.behind)} behind); the pre-flight's fast-forward pull will fail until that is resolved by hand`
+    );
+    return;
+  }
+  lines.push(`  ${String(status.ahead)} local commit(s) not on ${status.upstream}`);
+}
+function gitSection(status) {
+  const lines = [];
+  const problems = [];
+  if (status.error !== null) {
+    return build(
+      "git",
+      [`not a usable git repository: ${status.error}`],
+      [`not a usable git repository: ${status.error}`],
+      {
+        ...status
+      }
+    );
+  }
+  describeCheckout(status, lines, problems);
+  describeBaseBranch(status, lines, problems);
+  if (status.fetchError !== null) {
+    lines.push(`fetch failed: ${status.fetchError}`);
+    problems.push(
+      `\`git fetch\` failed (${status.fetchError}); the ahead/behind figures above are from the last successful fetch and may be out of date`
+    );
+  }
+  return build("git", lines, problems, { ...status });
+}
+function assembleReport(input) {
+  const byId = new Map(input.sections.map((section) => [section.id, section]));
+  const ordered = SECTION_ORDER.flatMap((id) => {
+    const section = byId.get(id);
+    return section === void 0 ? [] : [section];
+  });
+  const problems = ordered.flatMap((section) => section.problems);
+  return {
+    generatedAt: input.generatedAt,
+    repo: input.repo,
+    offline: input.offline,
+    sections: ordered,
+    problems,
+    exitCode: problems.length === 0 ? 0 : 1
+  };
+}
+function renderText(report) {
+  const head = `automata do-work --check \u2014 ${report.repo ?? "unknown repository"} \u2014 ${report.generatedAt.toISOString()}`;
+  const parts = [head, ""];
+  for (const section of report.sections) {
+    parts.push(section.title);
+    if (section.lines.length === 0) {
+      parts.push("  (nothing to report)");
+    } else {
+      for (const line of section.lines) parts.push(`  ${line}`);
+    }
+    parts.push("");
+  }
+  if (report.problems.length > 0) {
+    parts.push(`Problems (${String(report.problems.length)})`);
+    for (const problem of report.problems) parts.push(`  \xB7 ${problem.section}: ${problem.summary}`);
+    parts.push("");
+  }
+  parts.push(
+    report.problems.length === 0 ? "RESULT: healthy" : `RESULT: ${String(report.problems.length)} problem(s) found`
+  );
+  return parts.join("\n") + "\n";
+}
+function toJson(report) {
+  const sections = {};
+  for (const section of report.sections) {
+    sections[section.id] = {
+      title: section.title,
+      lines: section.lines,
+      problems: section.problems,
+      data: section.data
+    };
+  }
+  return {
+    generatedAt: report.generatedAt.toISOString(),
+    repo: report.repo,
+    offline: report.offline,
+    exitCode: report.exitCode,
+    problems: report.problems,
+    sections
+  };
+}
 
 // src/commands/doWork.ts
 var inFlightMarker = null;
@@ -4528,55 +5318,89 @@ function fail(message) {
   }
   process.exit(1);
 }
+var SettingsError = class extends Error {
+};
+function failSettings(message) {
+  throw new SettingsError(message);
+}
 function parsePositiveInt(value, label) {
   const trimmed2 = value.trim();
   if (!/^\d+$/.test(trimmed2)) {
-    fail(`${label} must be a positive integer (got "${value}").`);
+    failSettings(`${label} must be a positive integer (got "${value}").`);
   }
   const parsed = Number(trimmed2);
   if (!Number.isSafeInteger(parsed) || parsed <= 0) {
-    fail(`${label} must be a positive integer within the safe range (got "${value}").`);
+    failSettings(`${label} must be a positive integer within the safe range (got "${value}").`);
   }
   return parsed;
 }
-function resolveSettings(options) {
-  let config;
+function resolveSettingsResult(options, verifyIdentity) {
   try {
-    config = readConfig();
+    return { ok: true, settings: buildSettings(options, verifyIdentity) };
   } catch (err) {
-    fail(err.message);
+    if (err instanceof SettingsError) return { ok: false, error: err.message };
+    throw err;
   }
+}
+function resolveSettings(options) {
+  const result = resolveSettingsResult(options, options.dryRun !== true);
+  if (!result.ok) fail(result.error);
+  return result.settings;
+}
+function requireParticipants(config) {
   if (config.remoteType !== "gh") {
-    fail(
+    failSettings(
       "do-work is only supported for GitHub remotes. Set it with `automata config set type gh`. Azure DevOps lacks the issue conversation APIs this needs \u2014 see docs/azdo-gap.md."
     );
   }
   if (!config.issueDiscoveryTechnique) {
-    fail("No issue discovery technique configured. Run `automata config set issue-discovery-technique <value>`.");
+    failSettings("No issue discovery technique configured. Run `automata config set issue-discovery-technique <value>`.");
   }
   if (!config.issueDiscoveryValue) {
-    fail("No issue discovery value configured. Run `automata config set issue-discovery-value <value>`.");
+    failSettings("No issue discovery value configured. Run `automata config set issue-discovery-value <value>`.");
   }
   const allowedUsers = (config.allowedUsers ?? []).filter((user) => user.trim().length > 0);
   if (allowedUsers.length === 0) {
-    fail("No allowed users configured. Run `automata config set allowed-users <user1,user2>`.");
+    failSettings("No allowed users configured. Run `automata config set allowed-users <user1,user2>`.");
   }
   const agentUser = (config.agentUser ?? "").trim();
   if (agentUser.length === 0) {
-    fail("No agent user configured. Run `automata config set agent-user <login>`.");
+    failSettings("No agent user configured. Run `automata config set agent-user <login>`.");
   }
+  return {
+    allowedUsers,
+    agentUser,
+    technique: config.issueDiscoveryTechnique,
+    discoveryValue: config.issueDiscoveryValue
+  };
+}
+function resolveWithOption(value) {
+  if (value === void 0) return void 0;
+  const requested = value.toLowerCase();
+  if (requested !== "claude" && requested !== "codex") {
+    failSettings(`--with must be 'claude' or 'codex', got '${value}'.`);
+  }
+  return requested;
+}
+function resolveEffort(value) {
+  const result = normalizeEffortOption(value);
+  if (!result.ok) failSettings(result.error);
+  return result.value;
+}
+function buildSettings(options, verifyIdentity) {
+  let config;
+  try {
+    config = readConfig();
+  } catch (err) {
+    failSettings(err.message);
+  }
+  const { allowedUsers, agentUser, technique, discoveryValue } = requireParticipants(config);
   validateDoWorkConfig(config.doWork);
   const doWork = config.doWork ?? {};
-  let withOption;
-  if (options.with !== void 0) {
-    const requested = options.with.toLowerCase();
-    if (requested !== "claude" && requested !== "codex") {
-      fail(`--with must be 'claude' or 'codex', got '${options.with}'.`);
-    }
-    withOption = requested;
-  }
-  if (options.dryRun !== true) {
-    checkAuthenticatedIdentity(agentUser, allowedUsers);
+  const withOption = resolveWithOption(options.with);
+  if (verifyIdentity) {
+    const problem = describeIdentityProblem(agentUser, allowedUsers);
+    if (problem !== null) failSettings(problem);
   }
   return {
     baseBranch: doWork.baseBranch ?? DEFAULT_DO_WORK.baseBranch,
@@ -4588,8 +5412,10 @@ function resolveSettings(options) {
     // Rejected here rather than per item: an empty `--effort` is an operator
     // mistake on this invocation, not a property of any one work item. The
     // configured per-executor defaults are trimmed inside `resolveExecution`,
-    // which is where the executor in use is finally known.
-    effortOption: resolveEffortOption(options.effort),
+    // which is where the executor in use is finally known. Routed through
+    // `failSettings` rather than `resolveEffortOption`, whose rejection exits the
+    // process — which would take `--check` down before it printed a section.
+    effortOption: resolveEffort(options.effort),
     configEfforts: doWork.effort,
     maxRuns: options.maxRuns !== void 0 ? parsePositiveInt(options.maxRuns, "--max-runs") : doWork.maxRunsPerTick ?? DEFAULT_DO_WORK.maxRunsPerTick,
     lockStaleMinutes: doWork.lockStaleMinutes ?? DEFAULT_DO_WORK.lockStaleMinutes,
@@ -4600,30 +5426,22 @@ function resolveSettings(options) {
       "pr-work": doWork.prompts?.prWork ?? DEFAULT_DO_WORK_PR_WORK_PROMPT,
       "pr-orphan": doWork.prompts?.prOrphan ?? DEFAULT_DO_WORK_PR_ORPHAN_PROMPT
     },
-    technique: config.issueDiscoveryTechnique,
-    discoveryValue: config.issueDiscoveryValue,
+    technique,
+    discoveryValue,
     onlyIssue: options.issue === void 0 ? void 0 : parsePositiveInt(options.issue, "--issue"),
     onlyPr: options.pr === void 0 ? void 0 : parsePositiveInt(options.pr, "--pr")
   };
 }
-function checkAuthenticatedIdentity(agentUser, allowedUsers) {
+function describeIdentityProblem(agentUser, allowedUsers) {
   const login2 = getAuthenticatedLogin();
   if (login2 === null) {
     progress(
       `Warning: could not determine which account \`gh\` is authenticated as; assuming it is the agent (${agentUser}).
 `
     );
-    return;
-  }
-  if (login2.toLowerCase() === agentUser.toLowerCase()) return;
-  if (allowedUsers.some((user) => user.toLowerCase() === login2.toLowerCase())) {
-    fail(
-      `\`gh\` is authenticated as "${login2}", which is listed in allowedUsers. Everything do-work posts would be attributed to an account that is allowed to instruct the agent, so its own marker comment would look like a new instruction and each tick would answer the previous tick forever. Authenticate \`gh\` as the agent account (${agentUser}) in this environment, or correct \`agentUser\`.`
-    );
+    return null;
   }
-  fail(
-    `\`gh\` is authenticated as "${login2}" but agentUser is "${agentUser}". Comments posted under that identity are neither the agent's nor an authorized user's, so they are filtered out of the conversation: the answer boundary would never advance and the same message would start a run on every tick. Authenticate \`gh\` as the agent account (${agentUser}) in this environment, or correct \`agentUser\`.`
-  );
+  return identityProblemFor(login2, agentUser, allowedUsers);
 }
 function resolveItemExecution(item, settings) {
   const trigger = triggeringMessage(item);
@@ -4740,24 +5558,24 @@ function validateOptionalString(container, key, path) {
   const value = container[key];
   if (value === void 0 || value === null) return;
   if (typeof value !== "string" || value.trim().length === 0) {
-    fail(`${path} must be a non-empty string.`);
+    failSettings(`${path} must be a non-empty string.`);
   }
 }
 function validateOptionalInt(container, key, path, min, hint) {
   const value = container[key];
   if (value === void 0 || value === null) return;
   if (typeof value !== "number" || !Number.isSafeInteger(value) || value < min) {
-    fail(`${path} must be ${hint}, got ${JSON.stringify(value)}.`);
+    failSettings(`${path} must be ${hint}, got ${JSON.stringify(value)}.`);
   }
 }
 function validateDoWorkConfig(section) {
   if (section === void 0 || section === null) return;
   if (!isPlainObject(section)) {
-    fail(`doWork must be an object, got ${JSON.stringify(section)}.`);
+    failSettings(`doWork must be an object, got ${JSON.stringify(section)}.`);
   }
   const executor = section["executor"];
   if (executor !== void 0 && executor !== "claude" && executor !== "codex") {
-    fail(`doWork.executor must be 'claude' or 'codex', got ${JSON.stringify(executor)}.`);
+    failSettings(`doWork.executor must be 'claude' or 'codex', got ${JSON.stringify(executor)}.`);
   }
   validateOptionalString(section, "baseBranch", "doWork.baseBranch");
   validateOptionalInt(section, "maxRunsPerTick", "doWork.maxRunsPerTick", 0, "a non-negative integer (0 = unlimited)");
@@ -4771,20 +5589,20 @@ function validateProtectedBranches(value) {
   if (value === void 0 || value === null) return;
   const isNonEmptyString = (b) => typeof b === "string" && b.trim().length > 0;
   if (!Array.isArray(value) || !value.every(isNonEmptyString)) {
-    fail("doWork.protectedBranches must be an array of non-empty strings.");
+    failSettings("doWork.protectedBranches must be an array of non-empty strings.");
   }
 }
 function validateSettingContainer(value, container, keys) {
   if (value === void 0 || value === null) return;
   if (!isPlainObject(value)) {
-    fail(`doWork.${container} must be an object, got ${JSON.stringify(value)}.`);
+    failSettings(`doWork.${container} must be an object, got ${JSON.stringify(value)}.`);
   }
   for (const key of keys) {
     validateOptionalString(value, key, `doWork.${container}.${key}`);
   }
   for (const key of Object.keys(value)) {
     if (!keys.includes(key)) {
-      fail(`doWork.${container}.${key} is not a recognised setting; expected one of: ${keys.join(", ")}.`);
+      failSettings(`doWork.${container}.${key} is not a recognised setting; expected one of: ${keys.join(", ")}.`);
     }
   }
 }
@@ -5319,8 +6137,25 @@ var doWorkCommand = new Command6("do-work").description(
 ).option("--limit <n>", "Maximum number of issues to fetch", "10").option("--max-runs <n>", "Maximum number of model runs this tick").option(
   "--dry-run",
   "Print the work plan, plus a summary and the exact command that would be launched for each item, and exit without changing anything"
+).option(
+  "--check",
+  "Print a read-only health report for the loop \u2014 run lock, tick history, last work, repository state, per-candidate selection and environment \u2014 and exit 0 when it found no problem, 1 when it did"
+).option(
+  "--no-fetch",
+  "With --check: make no network call at all \u2014 no `git fetch` and no `gh` query. Ahead/behind is reported from the last fetch and the selection section does not run"
 ).option("--json", "Emit the work plan and outcomes as JSON on stdout").option("--silent", "Suppress step-by-step Claude output; show only the final summary").action(async (options) => {
   const startedAt = Date.now();
+  if (options.check === true) {
+    if (options.dryRun === true) {
+      process.stderr.write(
+        "Error: --check and --dry-run are two different read-only reports; run one or the other.\n"
+      );
+      process.exit(1);
+    }
+    const exitCode2 = runCheck(options);
+    if (exitCode2 !== 0) process.exit(exitCode2);
+    return;
+  }
   if (options.dryRun !== true) loggableInvocation = { startedAt };
   const settings = resolveSettings(options);
   if (options.dryRun === true) {
@@ -5374,6 +6209,213 @@ var doWorkCommand = new Command6("do-work").description(
   logTick(reports, exitCode, startedAt);
   if (exitCode !== 0) process.exit(exitCode);
 });
+function resolveRepoSlug() {
+  try {
+    const slug = getRepoSlug();
+    return `${slug.owner}/${slug.repo}`;
+  } catch {
+    return null;
+  }
+}
+function collectSelection(settings) {
+  const issues = discoverIssues(settings);
+  const linkMap = getOpenPrLinkMap();
+  const policy = {
+    baseBranch: settings.baseBranch,
+    defaultBranch: linkMap.defaultBranch,
+    protectedBranches: settings.protectedBranches
+  };
+  return skipDuplicateHeadBranches([
+    ...issues.map((issue) => decideWork(buildIssueState(issue, linkMap), settings.participants, policy)),
+    ...discoverOrphanPrs(settings, linkMap).map(
+      (candidate) => decideOrphanPrWork({ prSurface: getPrSurface(candidate.pr.number) }, settings.participants, policy)
+    )
+  ]);
+}
+function selectionSection(settings, offline) {
+  const section = (lines2, problems, data) => ({
+    id: "selection",
+    title: sectionTitle("selection"),
+    lines: lines2,
+    problems: problems.map((summary) => ({ section: "selection", summary })),
+    data
+  });
+  if (offline) {
+    return section(
+      ["not run: --no-fetch makes no network call, and the selection needs live GitHub data"],
+      [],
+      { ran: false, detail: "offline", plan: [] }
+    );
+  }
+  if (settings === null) {
+    return section(
+      ["not run: the configuration could not be resolved \u2014 see Environment below"],
+      [],
+      { ran: false, detail: "configuration invalid", plan: [] }
+    );
+  }
+  let decisions;
+  try {
+    decisions = collectSelection(settings);
+  } catch (err) {
+    const detail = err.message;
+    return section(
+      [`could not be computed: ${detail}`],
+      [`the GitHub selection could not be computed: ${detail}`],
+      { ran: false, detail, plan: [] }
+    );
+  }
+  const work = decisions.filter((decision) => decision.kind === "work").length;
+  const lines = [
+    `${String(work)} of ${String(decisions.length)} candidate(s) would be picked up`,
+    ...describePlan(decisions).trimEnd().split("\n")
+  ];
+  return section(lines, [], { ran: true, detail: null, plan: decisions.map(toPlanJson) });
+}
+function describeExecutor(settings, lines, problems) {
+  const executor = settings.withOption ?? settings.configExecutor ?? "claude";
+  const command = executor === "codex" ? "codex" : "claude";
+  const resolvedPath = resolveCommand(command);
+  const onPath = resolvedPath !== command;
+  lines.push(`default executor: ${executor} (${onPath ? resolvedPath : "not found on PATH"})`);
+  if (!onPath) {
+    problems.push(
+      `the \`${command}\` command is not on PATH, so every run this tick would fail. Under cron the PATH is not your login shell's \u2014 set it in the crontab or use an absolute path`
+    );
+  }
+  return { executor, command, onPath };
+}
+function describeGitHubIdentity(options, settings, lines, problems) {
+  if (options.fetch === false) {
+    lines.push("`gh` authentication not checked: --no-fetch");
+    return { ghAvailable: null, ghLogin: null, identityProblem: null };
+  }
+  let identity;
+  try {
+    identity = getAuthenticatedIdentity();
+  } catch (err) {
+    const detail = err.message;
+    lines.push(`\`gh\` could not be queried: ${detail}`);
+    problems.push(`\`gh\` could not be queried (${detail}); install it and run \`gh auth login\``);
+    return { ghAvailable: false, ghLogin: null, identityProblem: null };
+  }
+  if (identity.kind === "unavailable") {
+    lines.push(`\`gh\` could not name an account: ${identity.detail}`);
+    problems.push(
+      `\`gh api user\` failed (${identity.detail}), so \`gh\` is not authenticated here and every GitHub call a tick makes would fail; run \`gh auth login\`, or set \`GH_TOKEN\` in the scheduler's environment`
+    );
+    return { ghAvailable: false, ghLogin: null, identityProblem: null };
+  }
+  const ghLogin = identity.kind === "login" ? identity.login : null;
+  lines.push(
+    ghLogin === null ? "`gh` is available but its account could not be determined (an app installation token has none)" : `\`gh\` is authenticated as ${ghLogin}`
+  );
+  const identityProblem = identityProblemFor(
+    ghLogin,
+    settings.participants.agentUser,
+    settings.participants.allowedUsers
+  );
+  if (identityProblem !== null) problems.push(identityProblem);
+  return { ghAvailable: true, ghLogin, identityProblem };
+}
+function readRemoteType() {
+  try {
+    return readConfig().remoteType ?? null;
+  } catch {
+    return null;
+  }
+}
+function environmentSection(options, resolved, repo) {
+  const lines = [`automata ${version}`];
+  const problems = [];
+  const remoteType = readRemoteType();
+  const data = {
+    version,
+    repo,
+    remoteType,
+    configValid: resolved.ok,
+    configError: resolved.ok ? null : resolved.error
+  };
+  if (repo === null) {
+    lines.push("repository slug could not be resolved from `origin`");
+    problems.push(
+      "the repository slug could not be resolved; `gh` needs an `origin` remote pointing at GitHub to read issues, and the operation logs cannot attribute their lines without it"
+    );
+  } else {
+    lines.push(`repository ${repo}`);
+  }
+  if (!resolved.ok) {
+    lines.push(`configuration is not usable: ${resolved.error}`);
+    problems.push(`the configuration is not usable: ${resolved.error}`);
+    return {
+      id: "environment",
+      title: sectionTitle("environment"),
+      lines,
+      problems: problems.map((summary) => ({ section: "environment", summary })),
+      // `ghAvailable` is null rather than false: nothing was asked of `gh`,
+      // which is not the same as having asked and been refused.
+      data: { ...data, ghAvailable: null, ghLogin: null, identityProblem: null }
+    };
+  }
+  const settings = resolved.settings;
+  const runCap = settings.maxRuns === 0 ? "unlimited" : String(settings.maxRuns);
+  lines.push(
+    "configuration parses and validates",
+    `discovery: ${settings.technique} = ${settings.discoveryValue}`,
+    `base branch: ${settings.baseBranch}`,
+    `run cap: ${runCap}; lock stale after ${String(settings.lockStaleMinutes)} minutes`
+  );
+  const { executor, command, onPath } = describeExecutor(settings, lines, problems);
+  const { ghAvailable, ghLogin, identityProblem } = describeGitHubIdentity(
+    options,
+    settings,
+    lines,
+    problems
+  );
+  return {
+    id: "environment",
+    title: sectionTitle("environment"),
+    lines,
+    problems: problems.map((summary) => ({ section: "environment", summary })),
+    data: {
+      ...data,
+      discovery: { technique: settings.technique, value: settings.discoveryValue },
+      baseBranch: settings.baseBranch,
+      maxRuns: settings.maxRuns,
+      lockStaleMinutes: settings.lockStaleMinutes,
+      executor,
+      executorCommand: command,
+      executorOnPath: onPath,
+      ghAvailable,
+      ghLogin,
+      identityProblem
+    }
+  };
+}
+function runCheck(options) {
+  const now = /* @__PURE__ */ new Date();
+  const offline = options.fetch === false;
+  const repo = resolveRepoSlug();
+  const resolved = resolveSettingsResult(options, false);
+  const settings = resolved.ok ? resolved.settings : null;
+  const staleMinutes = settings?.lockStaleMinutes ?? DEFAULT_DO_WORK.lockStaleMinutes;
+  const baseBranch = settings?.baseBranch ?? DEFAULT_DO_WORK.baseBranch;
+  const report = assembleReport({
+    generatedAt: now,
+    repo,
+    offline,
+    sections: [
+      lockSection(inspectRunLock(staleMinutes), staleMinutes),
+      tickSection(readExecutionTicks({ repo, limit: TICK_HISTORY }), now),
+      workSection(readWorkRecords({ repo, limit: WORK_HISTORY }), now),
+      gitSection(inspectRepoStatus({ baseBranch, fetch: !offline })),
+      selectionSection(settings, offline),
+      environmentSection(options, resolved, repo)
+    ]
+  });
+  out(options.json === true ? JSON.stringify(toJson(report), null, 2) + "\n" : renderText(report));
+  return report.exitCode;
+}
 function toTickLogItem(report) {
   return {
     subject: reportLabel(report),