automata-cli 0.8.1 → 0.9.0-develop.387

package/dist/index.js

@@ -11,7 +11,7 @@ import {
   readConfig,
   readRawConfig,
   writeConfig
-} from "./chunk-MIPBYVK5.js";
+} from "./chunk-42OV4UI4.js";
 
 // src/index.ts
 import { Command as Command7 } from "commander";
@@ -26,6 +26,60 @@ var version = packageJson.version;
 
 // src/commands/config.ts
 import { Command } from "commander";
+
+// src/git/releaseFlow.ts
+var RELEASE_FLOWS = ["gitflow", "trunk"];
+var RELEASE_FLOW_CONFIG_KEY = "git.releaseFlow";
+function isReleaseFlow(value) {
+  return typeof value === "string" && RELEASE_FLOWS.includes(value);
+}
+function describeReleaseFlowSource(source) {
+  switch (source) {
+    case "config":
+      return `configured as ${RELEASE_FLOW_CONFIG_KEY}`;
+    case "develop-present":
+      return "detected: origin/develop exists";
+    case "develop-absent":
+      return "detected: origin/develop does not exist";
+  }
+}
+function invalidReleaseFlowMessage(value) {
+  return `Invalid ${RELEASE_FLOW_CONFIG_KEY} ${JSON.stringify(value)} in .automata/config.json; expected one of: ${RELEASE_FLOWS.join(", ")}.
+Fix it with: automata config set git-release-flow <gitflow|trunk>`;
+}
+function planRelease(flow, version2, trunk, trunkIsLocal) {
+  if (flow === "trunk") {
+    const message = `chore(release): ${version2}`;
+    return [
+      { args: ["commit", "--allow-empty", "-m", message], desc: `git commit --allow-empty -m "${message}"` },
+      { args: ["tag", version2], desc: `git tag ${version2}` },
+      {
+        args: ["push", "--atomic", "origin", trunk, version2],
+        desc: `git push --atomic origin ${trunk} ${version2}`
+      }
+    ];
+  }
+  const releaseBranch = `release/${version2}`;
+  const checkoutTrunk = trunkIsLocal ? { args: ["checkout", trunk], desc: `git checkout ${trunk}` } : {
+    args: ["checkout", "-b", trunk, `origin/${trunk}`],
+    desc: `git checkout -b ${trunk} origin/${trunk}`
+  };
+  return [
+    { args: ["checkout", "-b", releaseBranch], desc: `git checkout -b ${releaseBranch}` },
+    checkoutTrunk,
+    { args: ["merge", "--no-ff", releaseBranch], desc: `git merge --no-ff ${releaseBranch}` },
+    { args: ["tag", version2], desc: `git tag ${version2}` },
+    { args: ["checkout", "develop"], desc: `git checkout develop` },
+    { args: ["merge", "--no-ff", releaseBranch], desc: `git merge --no-ff ${releaseBranch}` },
+    { args: ["branch", "-d", releaseBranch], desc: `git branch -d ${releaseBranch}` },
+    {
+      args: ["push", "origin", "develop", trunk, version2],
+      desc: `git push origin develop ${trunk} ${version2}`
+    }
+  ];
+}
+
+// src/commands/config.ts
 var VALID_TYPES = ["gh", "azdo"];
 var VALID_TECHNIQUES = ["label", "assignee", "title-contains"];
 var VALID_EXECUTORS = ["claude", "codex"];
@@ -184,6 +238,20 @@ var configSetDoWorkLockStaleMinutes = new Command("do-work-lock-stale-minutes").
   process.stdout.write(`do-work lock staleness set to: ${String(minutes)} minutes
 `);
 });
+var configSetDoWorkDumpOnBlock = new Command("do-work-dump-on-block").description(
+  "Set whether `do-work` prints the full health report when a tick exits having done nothing"
+).argument("<value>", `true or false (default: ${String(DEFAULT_DO_WORK.dumpOnBlock)})`).action((value) => {
+  const normalized = value.trim().toLowerCase();
+  if (normalized !== "true" && normalized !== "false") {
+    process.stderr.write(`Error: do-work-dump-on-block must be true or false (got "${value}").
+`);
+    process.exit(1);
+  }
+  const dumpOnBlock = normalized === "true";
+  writeDoWork({ dumpOnBlock });
+  process.stdout.write(`do-work dump on block set to: ${String(dumpOnBlock)}
+`);
+});
 var configSetDoWorkPrompt = new Command("do-work-prompt").description("Set the turn instructions for a `do-work` turn kind (prompt text or a .md filename)").argument("<turn-kind>", `Turn kind: ${VALID_TURN_KINDS.join(", ")}`).argument("<value>", "Prompt text, or a plain .md filename inside .automata/").action((turnKind, value) => {
   if (!VALID_TURN_KINDS.includes(turnKind)) {
     process.stderr.write(
@@ -225,12 +293,24 @@ var configSetGitTrunkBranch = new Command("git-trunk-branch").description("Pin t
   process.stdout.write(`git trunk branch set to: ${branch}
 `);
 });
-var configSet = new Command("set").description("Set a configuration value").addCommand(configSetType).addCommand(configSetIssueDiscoveryTechnique).addCommand(configSetIssueDiscoveryValue).addCommand(configSetClaudeSystemPrompt).addCommand(configSetAllowedUsers).addCommand(configSetAgentUser).addCommand(configSetDoWorkBaseBranch).addCommand(configSetDoWorkProtectedBranches).addCommand(configSetDoWorkExecutor).addCommand(configSetDoWorkModel).addCommand(configSetDoWorkEffort).addCommand(configSetDoWorkMaxRuns).addCommand(configSetDoWorkLockStaleMinutes).addCommand(configSetDoWorkPrompt).addCommand(configSetGitTrunkBranch);
+var configSetGitReleaseFlow = new Command("git-release-flow").description("Pin the release procedure `publish-release` runs, instead of detecting it").argument("<value>", `Release flow: ${RELEASE_FLOWS.join(" | ")} (when the key is absent, the flow is detected from origin/develop)`).action((value) => {
+  const flow = value.trim();
+  if (!isReleaseFlow(flow)) {
+    process.stderr.write(`Error: invalid release flow "${value}". Must be one of: ${RELEASE_FLOWS.join(", ")}
+`);
+    process.exit(1);
+  }
+  const current = readRawConfig();
+  writeConfig({ ...current, git: { ...current.git, releaseFlow: flow } });
+  process.stdout.write(`git release flow set to: ${flow}
+`);
+});
+var configSet = new Command("set").description("Set a configuration value").addCommand(configSetType).addCommand(configSetIssueDiscoveryTechnique).addCommand(configSetIssueDiscoveryValue).addCommand(configSetClaudeSystemPrompt).addCommand(configSetAllowedUsers).addCommand(configSetAgentUser).addCommand(configSetDoWorkBaseBranch).addCommand(configSetDoWorkProtectedBranches).addCommand(configSetDoWorkExecutor).addCommand(configSetDoWorkModel).addCommand(configSetDoWorkEffort).addCommand(configSetDoWorkMaxRuns).addCommand(configSetDoWorkLockStaleMinutes).addCommand(configSetDoWorkDumpOnBlock).addCommand(configSetDoWorkPrompt).addCommand(configSetGitTrunkBranch).addCommand(configSetGitReleaseFlow);
 var configCommand = new Command("config").description("Configure automata settings").addCommand(configSet).action(async () => {
   const [{ render }, React, { ConfigWizard }] = await Promise.all([
     import("ink"),
     import("react"),
-    import("./ConfigWizard-GULICHML.js")
+    import("./ConfigWizard-RGXIC7OS.js")
   ]);
   const { waitUntilExit } = render(React.createElement(ConfigWizard));
   await waitUntilExit();
@@ -291,6 +371,38 @@ function getPrInfo() {
   };
 }
 
+// src/run/commandTrace.ts
+var sink = null;
+function startCommandTrace() {
+  sink = [];
+}
+function stopCommandTrace() {
+  sink = null;
+}
+function takeCommandTrace() {
+  const taken = sink;
+  sink = null;
+  return taken;
+}
+function recordCommand(command, args, startedAt, exitCode) {
+  if (sink === null) return;
+  sink.push({
+    command,
+    args: [...args],
+    // A clock that went backwards must not produce a negative duration in a
+    // report an operator is reading for anomalies.
+    durationMs: Math.max(0, Date.now() - startedAt),
+    exitCode
+  });
+}
+function describeTracedCommand(traced) {
+  const rendered = [traced.command, ...traced.args].join(" ");
+  const flat = rendered.replace(/\s+/g, " ").trim();
+  const shown = flat.length <= MAX_COMMAND_LENGTH ? flat : `${flat.slice(0, MAX_COMMAND_LENGTH)}\u2026`;
+  return `${shown} \u2014 ${String(traced.durationMs)}ms exit ${String(traced.exitCode)}`;
+}
+var MAX_COMMAND_LENGTH = 300;
+
 // src/git/trunkDetection.ts
 var TRUNK_CANDIDATES = ["main", "master"];
 var TRUNK_BRANCH_CONFIG_KEY = "git.trunkBranch";
@@ -331,11 +443,14 @@ Set it explicitly with: automata config set git-trunk-branch <branch>`;
 
 // src/git/gitService.ts
 function run2(cmd, args) {
+  const startedAt = Date.now();
   const result = spawnSync2(cmd, args, { encoding: "utf8" });
+  const status = result.status ?? 1;
+  recordCommand(cmd, args, startedAt, result.error ? -1 : status);
   return {
     stdout: result.stdout ?? "",
     stderr: result.stderr ?? "",
-    status: result.status ?? 1
+    status
   };
 }
 function getCurrentBranch() {
@@ -1098,17 +1213,44 @@ ${stderr.trim()}`);
   }
   return stdout.trim().length > 0;
 }
-function checkReleasePreconditions() {
+function probeRemoteBranch(branch) {
+  const ref = `refs/heads/${branch}`;
+  const { status, stderr } = run2("git", ["ls-remote", "--exit-code", "origin", ref]);
+  if (status === 0) return { ok: true, exists: true };
+  if (status === 2) return { ok: true, exists: false };
+  return {
+    ok: false,
+    message: stderr.trim() || `git ls-remote --exit-code origin ${ref} failed.`
+  };
+}
+function resolveReleaseFlow() {
+  const configured = readRawConfig().git?.releaseFlow;
+  if (configured !== void 0) {
+    if (!isReleaseFlow(configured)) return { ok: false, message: invalidReleaseFlowMessage(configured) };
+    return { ok: true, flow: configured, source: "config" };
+  }
+  const develop = probeRemoteBranch("develop");
+  if (!develop.ok) {
+    return {
+      ok: false,
+      message: `Could not check whether origin has a 'develop' branch to choose the release flow.
+${develop.message}
+Set it explicitly with: automata config set git-release-flow <gitflow|trunk>`
+    };
+  }
+  return develop.exists ? { ok: true, flow: "gitflow", source: "develop-present" } : { ok: true, flow: "trunk", source: "develop-absent" };
+}
+function checkReleasePreconditions(expectedBranch) {
   let branch;
   try {
     branch = getCurrentBranch();
   } catch (err) {
     return { ok: false, message: err.message };
   }
-  if (branch !== "develop") {
+  if (branch !== expectedBranch) {
     return {
       ok: false,
-      message: `publish-release must be run from the 'develop' branch (currently on '${branch}').`
+      message: `publish-release must be run from the '${expectedBranch}' branch (currently on '${branch}').`
     };
   }
   if (hasUncommittedChanges()) {
@@ -1119,25 +1261,8 @@ function checkReleasePreconditions() {
   }
   return { ok: true };
 }
-function publishRelease(version2, dryRun, trunk) {
-  const releaseBranch = `release/${version2}`;
-  const checkoutTrunk = localBranchExists(trunk) ? { args: ["checkout", trunk], desc: `git checkout ${trunk}` } : {
-    args: ["checkout", "-b", trunk, `origin/${trunk}`],
-    desc: `git checkout -b ${trunk} origin/${trunk}`
-  };
-  const steps = [
-    { args: ["checkout", "-b", releaseBranch], desc: `git checkout -b ${releaseBranch}` },
-    checkoutTrunk,
-    { args: ["merge", "--no-ff", releaseBranch], desc: `git merge --no-ff ${releaseBranch}` },
-    { args: ["tag", version2], desc: `git tag ${version2}` },
-    { args: ["checkout", "develop"], desc: `git checkout develop` },
-    { args: ["merge", "--no-ff", releaseBranch], desc: `git merge --no-ff ${releaseBranch}` },
-    { args: ["branch", "-d", releaseBranch], desc: `git branch -d ${releaseBranch}` },
-    {
-      args: ["push", "origin", "develop", trunk, version2],
-      desc: `git push origin develop ${trunk} ${version2}`
-    }
-  ];
+function publishRelease(version2, dryRun, trunk, flow) {
+  const steps = planRelease(flow, version2, trunk, flow === "gitflow" && localBranchExists(trunk));
   for (const step of steps) {
     if (dryRun) {
       process.stdout.write(`[dry-run] ${step.desc}
@@ -1565,10 +1690,13 @@ var finishFeatureCmd = new Command2("finish-feature").description("Clean up a me
     process.exit(1);
   }
 });
-var publishReleaseCmd = new Command2("publish-release").description("Execute the full GitFlow release sequence and push to origin").argument("[version]", "Release version in X.Y.Z format (auto-detected from the trunk tag if omitted)").option("--dry-run", "Print git commands without executing them").addHelpText(
+var publishReleaseCmd = new Command2("publish-release").description("Execute the release sequence (GitFlow or trunk-based) and push to origin").argument("[version]", "Release version in X.Y.Z format (auto-detected from the trunk tag if omitted)").option("--dry-run", "Print git commands without executing them").addHelpText(
   "after",
   `
-Release sequence:
+Release flow: git.releaseFlow in .automata/config.json if set, else detected \u2014
+gitflow when origin has a 'develop' branch, trunk when it does not.
+
+GitFlow sequence (run from develop):
   1. git checkout -b release/<version>
   2. git checkout <trunk> && git merge --no-ff release/<version>
   3. git tag <version>
@@ -1576,6 +1704,11 @@ Release sequence:
   5. git branch -d release/<version>
   6. git push origin develop <trunk> <version>
 
+Trunk sequence (run from <trunk>; it may be ahead of origin, not behind):
+  1. git commit --allow-empty -m "chore(release): <version>"
+  2. git tag <version>
+  3. git push --atomic origin <trunk> <version>
+
 <trunk> is resolved from origin \u2014 git.trunkBranch in .automata/config.json if
 set, else origin/HEAD, the remote's advertised HEAD, or a probe of main/master.
 Tags are fetched from origin first, in --dry-run too, so the version a dry run
@@ -1586,16 +1719,10 @@ 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.`
+before any commit, 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();
-  if (!preconditions.ok) {
-    process.stderr.write(`Error: ${preconditions.message}
-`);
-    process.exit(1);
-  }
   const trunk = resolveTrunkBranch();
   if (!trunk.ok) {
     process.stderr.write(`Error: ${unresolvedTrunkMessage(trunk.attempted)}
@@ -1604,7 +1731,22 @@ not subject to the check.`
   }
   const trunkBranch = trunk.branch;
   const trunkRef = `origin/${trunkBranch}`;
+  const flow = resolveReleaseFlow();
+  if (!flow.ok) {
+    process.stderr.write(`Error: ${flow.message}
+`);
+    process.exit(1);
+  }
+  const releaseFlow = flow.flow;
+  const preconditions = checkReleasePreconditions(releaseFlow === "gitflow" ? "develop" : trunkBranch);
+  if (!preconditions.ok) {
+    process.stderr.write(`Error: ${preconditions.message}
+`);
+    process.exit(1);
+  }
   process.stdout.write(`Trunk branch: ${trunkBranch} (${describeTrunkSource(trunk.source, trunkBranch)})
+`);
+  process.stdout.write(`Release flow: ${releaseFlow} (${describeReleaseFlowSource(flow.source)})
 `);
   const fetched = fetchTrunkAndTags(trunkBranch);
   if (!fetched.ok) {
@@ -1651,7 +1793,7 @@ ${fetched.message}
 `);
   }
   try {
-    publishRelease(resolvedVersion, dryRun, trunkBranch);
+    publishRelease(resolvedVersion, dryRun, trunkBranch, releaseFlow);
   } catch (err) {
     process.stderr.write(`Error: ${err.message}
 `);
@@ -1672,7 +1814,9 @@ import { Command as Command3 } from "commander";
 import { spawnSync as spawnSync3 } from "child_process";
 var GITHUB_ISSUE_COMMENT_URL_RE = /github\.com\/([^/]+\/[^/]+)\/issues\/\d+#issuecomment-(\d+)/;
 function run3(cmd, args) {
+  const startedAt = Date.now();
   const result = spawnSync3(cmd, args, { encoding: "utf8" });
+  recordCommand(cmd, args, startedAt, result.error ? -1 : result.status ?? 1);
   if (result.error) {
     const err = result.error;
     if (err.code === "ENOENT") {
@@ -1828,7 +1972,9 @@ function addCopilotReviewer(prNumber) {
 // src/github/ghWorkService.ts
 import { spawnSync as spawnSync4 } from "child_process";
 function run4(cmd, args) {
+  const startedAt = Date.now();
   const result = spawnSync4(cmd, args, { encoding: "utf8" });
+  recordCommand(cmd, args, startedAt, result.error ? -1 : result.status ?? 1);
   if (result.error) {
     const err = result.error;
     if (err.code === "ENOENT") {
@@ -3666,19 +3812,108 @@ function analyseAnswer(messages, p, marker, watermark) {
 }
 
 // src/run/runLock.ts
-import { writeFileSync, readFileSync as readFileSync4, unlinkSync, mkdirSync, renameSync, linkSync, statSync as statSync2 } from "fs";
+import { writeFileSync as writeFileSync2, readFileSync as readFileSync5, unlinkSync as unlinkSync2, mkdirSync, renameSync, linkSync, statSync as statSync2 } from "fs";
 import { randomUUID } from "crypto";
 import { hostname } from "os";
+import { join as join4 } from "path";
+
+// src/run/heartbeat.ts
+import { unlinkSync, readFileSync as readFileSync4, writeFileSync } from "fs";
 import { join as join3 } from "path";
+var HEARTBEAT_DIR = ".automata";
+var HEARTBEAT_FILE = "automata-heartbeat.json";
+var HEARTBEAT_RELATIVE_PATH = `${HEARTBEAT_DIR}/${HEARTBEAT_FILE}`;
+var PHASES = ["pre-flight", "discovery", "item", "summary"];
+function isPhase(value) {
+  return typeof value === "string" && PHASES.includes(value);
+}
+function heartbeatPath(cwd = process.cwd()) {
+  return join3(cwd, HEARTBEAT_DIR, HEARTBEAT_FILE);
+}
+function buildHeartbeat(token, update, now = /* @__PURE__ */ new Date()) {
+  return {
+    token,
+    updatedAt: now.toISOString(),
+    phase: update.phase,
+    item: update.item ?? null,
+    executor: update.executor ?? null
+  };
+}
+function formatHeartbeat(heartbeat) {
+  return JSON.stringify(heartbeat, null, 2) + "\n";
+}
+function parseHeartbeat(content) {
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null) return null;
+  const raw = parsed;
+  if (typeof raw.token !== "string" || raw.token.length === 0) return null;
+  if (typeof raw.updatedAt !== "string") return null;
+  if (!isPhase(raw.phase)) return null;
+  return {
+    token: raw.token,
+    updatedAt: raw.updatedAt,
+    phase: raw.phase,
+    item: parseItem(raw.item),
+    executor: parseExecutor(raw.executor)
+  };
+}
+function parseItem(value) {
+  if (typeof value !== "object" || value === null) return null;
+  const raw = value;
+  if (typeof raw.index !== "number" || typeof raw.total !== "number") return null;
+  if (typeof raw.subject !== "string") return null;
+  return { index: raw.index, total: raw.total, subject: raw.subject };
+}
+function parseExecutor(value) {
+  if (typeof value !== "object" || value === null) return null;
+  const raw = value;
+  if (typeof raw.command !== "string" || typeof raw.startedAt !== "string") return null;
+  return { command: raw.command, startedAt: raw.startedAt };
+}
+function writeHeartbeat(token, update, cwd = process.cwd(), now = /* @__PURE__ */ new Date()) {
+  try {
+    writeFileSync(heartbeatPath(cwd), formatHeartbeat(buildHeartbeat(token, update, now)), "utf8");
+  } catch {
+  }
+}
+function clearHeartbeat(token, cwd = process.cwd()) {
+  if (readHeartbeat(token, cwd) === null) return;
+  try {
+    unlinkSync(heartbeatPath(cwd));
+  } catch {
+  }
+}
+function readHeartbeat(token, cwd = process.cwd()) {
+  let content;
+  try {
+    content = readFileSync4(heartbeatPath(cwd), "utf8");
+  } catch {
+    return null;
+  }
+  const heartbeat = parseHeartbeat(content);
+  if (heartbeat?.token !== token) return null;
+  return heartbeat;
+}
+
+// src/run/runLock.ts
 var LOCK_DIR = ".automata";
 var LOCK_FILE = "automata.lock";
 var RUN_LOCK_RELATIVE_PATH = `${LOCK_DIR}/${LOCK_FILE}`;
+var AUTOMATA_OWN_PATHS = [
+  RUN_LOCK_RELATIVE_PATH,
+  HEARTBEAT_RELATIVE_PATH
+];
 function lockPath() {
-  return join3(process.cwd(), LOCK_DIR, LOCK_FILE);
+  return join4(process.cwd(), LOCK_DIR, LOCK_FILE);
 }
 function processStartedAt(pid) {
   try {
-    const stat = readFileSync4(`/proc/${String(pid)}/stat`, "utf8");
+    const stat = readFileSync5(`/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;
@@ -3696,7 +3931,7 @@ function isAlive(pid) {
 }
 function readOwnerError(path) {
   try {
-    readFileSync4(path, "utf8");
+    readFileSync5(path, "utf8");
     return null;
   } catch (err) {
     return err.message;
@@ -3704,7 +3939,7 @@ function readOwnerError(path) {
 }
 function readOwner(path) {
   try {
-    const parsed = JSON.parse(readFileSync4(path, "utf8"));
+    const parsed = JSON.parse(readFileSync5(path, "utf8"));
     if (typeof parsed.pid !== "number" || typeof parsed.startedAt !== "string") return null;
     return {
       pid: parsed.pid,
@@ -3712,7 +3947,8 @@ function readOwner(path) {
       host: parsed.host ?? "unknown",
       command: parsed.command ?? "unknown",
       token: parsed.token ?? "",
-      pidStartedAt: parsed.pidStartedAt
+      pidStartedAt: parsed.pidStartedAt,
+      cwd: parsed.cwd
     };
   } catch {
     return null;
@@ -3741,10 +3977,16 @@ function heldTooLong(owner, staleMinutes) {
 }
 function makeHandle(path, token) {
   let released = false;
+  const cwd = process.cwd();
   return {
+    heartbeat(update) {
+      if (released) return;
+      writeHeartbeat(token, update, cwd);
+    },
     release() {
       if (released) return;
       released = true;
+      clearHeartbeat(token, cwd);
       const current = readOwner(path);
       if (current !== null && current.token !== token) {
         return;
@@ -3758,7 +4000,7 @@ function makeHandle(path, token) {
       const owner = readOwner(takenAway);
       if (owner === null || owner.token === token) {
         try {
-          unlinkSync(takenAway);
+          unlinkSync2(takenAway);
         } catch {
         }
         return;
@@ -3768,7 +4010,7 @@ function makeHandle(path, token) {
       } catch {
       }
       try {
-        unlinkSync(takenAway);
+        unlinkSync2(takenAway);
       } catch {
       }
     }
@@ -3781,11 +4023,12 @@ function publishLock(path, command, token) {
     host: hostname(),
     command,
     token,
-    pidStartedAt: processStartedAt(process.pid) ?? void 0
+    pidStartedAt: processStartedAt(process.pid) ?? void 0,
+    cwd: process.cwd()
   };
   const staging = `${path}.staging.${token}`;
   try {
-    writeFileSync(staging, JSON.stringify(owner, null, 2) + "\n", { encoding: "utf8", flag: "wx" });
+    writeFileSync2(staging, JSON.stringify(owner, null, 2) + "\n", { encoding: "utf8", flag: "wx" });
   } catch {
     return false;
   }
@@ -3797,7 +4040,7 @@ function publishLock(path, command, token) {
     return false;
   } finally {
     try {
-      unlinkSync(staging);
+      unlinkSync2(staging);
     } catch {
     }
   }
@@ -3805,7 +4048,7 @@ function publishLock(path, command, token) {
 function acquireRunLock(command, staleMinutes) {
   const path = lockPath();
   const token = randomUUID();
-  mkdirSync(join3(process.cwd(), LOCK_DIR), { recursive: true });
+  mkdirSync(join4(process.cwd(), LOCK_DIR), { recursive: true });
   if (publishLock(path, command, token)) {
     return { ok: true, handle: makeHandle(path, token) };
   }
@@ -3840,7 +4083,7 @@ function claimStaleLock(path, token, expected) {
       } catch {
       }
       try {
-        unlinkSync(claimed);
+        unlinkSync2(claimed);
       } catch {
       }
       return false;
@@ -3852,7 +4095,7 @@ var CLAIM_STALE_MS = 6e4;
 function acquireClaim(path) {
   const claimPath = `${path}.claim`;
   try {
-    writeFileSync(claimPath, JSON.stringify({ pid: process.pid, at: (/* @__PURE__ */ new Date()).toISOString() }), {
+    writeFileSync2(claimPath, JSON.stringify({ pid: process.pid, at: (/* @__PURE__ */ new Date()).toISOString() }), {
       encoding: "utf8",
       flag: "wx"
     });
@@ -3867,11 +4110,11 @@ function acquireClaim(path) {
     return null;
   }
   try {
-    unlinkSync(`${claimPath}.abandoned.${String(process.pid)}`);
+    unlinkSync2(`${claimPath}.abandoned.${String(process.pid)}`);
   } catch {
   }
   try {
-    writeFileSync(claimPath, JSON.stringify({ pid: process.pid, at: (/* @__PURE__ */ new Date()).toISOString() }), {
+    writeFileSync2(claimPath, JSON.stringify({ pid: process.pid, at: (/* @__PURE__ */ new Date()).toISOString() }), {
       encoding: "utf8",
       flag: "wx"
     });
@@ -3883,7 +4126,7 @@ function acquireClaim(path) {
 function claimIsAbandoned(claimPath) {
   let at = Number.NaN;
   try {
-    const raw = JSON.parse(readFileSync4(claimPath, "utf8"));
+    const raw = JSON.parse(readFileSync5(claimPath, "utf8"));
     if (raw.at !== void 0) at = Date.parse(raw.at);
   } catch {
   }
@@ -3915,13 +4158,13 @@ function reclaim(path, command, token, expected) {
       return { ok: false, heldBy: readOwner(path) ?? UNKNOWN_OWNER, suspect: false };
     } finally {
       try {
-        unlinkSync(claimed);
+        unlinkSync2(claimed);
       } catch {
       }
     }
   } finally {
     try {
-      unlinkSync(claimPath);
+      unlinkSync2(claimPath);
     } catch {
     }
   }
@@ -3946,7 +4189,12 @@ function inspectRunLock(staleMinutes, now = Date.now()) {
   }
   const held = owner;
   const kind = heldTooLong(held, staleMinutes) ? "suspect" : "held";
-  return { kind, owner: held, heldForMs: heldForMs(held, now) };
+  return {
+    kind,
+    owner: held,
+    heldForMs: heldForMs(held, now),
+    heartbeat: readHeartbeat(held.token, held.cwd ?? process.cwd())
+  };
 }
 
 // src/git/workspaceService.ts
@@ -3958,7 +4206,7 @@ function dirtyTree() {
   };
 }
 function prepareBaseBranch(baseBranch) {
-  if (hasUncommittedChanges([RUN_LOCK_RELATIVE_PATH])) return dirtyTree();
+  if (hasUncommittedChanges([...AUTOMATA_OWN_PATHS])) return dirtyTree();
   const checkout = checkoutBranch(baseBranch);
   if (!checkout.ok) {
     return { ok: false, reason: "checkout-failed", detail: checkout.stderr };
@@ -4054,7 +4302,7 @@ function divergenceRefusal(headRefName, pullError) {
   };
 }
 function preparePrBranch(headRefName) {
-  if (hasUncommittedChanges([RUN_LOCK_RELATIVE_PATH])) return dirtyTree();
+  if (hasUncommittedChanges([...AUTOMATA_OWN_PATHS])) return dirtyTree();
   const previousRemoteSha = revParse(`refs/remotes/origin/${headRefName}`);
   const fetched = fetchBranch(headRefName);
   if (!fetched.ok) {
@@ -4130,7 +4378,7 @@ function findOpenPr(branch) {
   return prs.find((pr) => pr.state === "OPEN") ?? null;
 }
 function rescueUncommittedChanges(options, now) {
-  if (!hasUncommittedChanges([RUN_LOCK_RELATIVE_PATH])) {
+  if (!hasUncommittedChanges([...AUTOMATA_OWN_PATHS])) {
     options.log("  rescue    nothing to do; the working tree is clean\n");
     return { kind: "clean" };
   }
@@ -4143,7 +4391,7 @@ function rescueUncommittedChanges(options, now) {
     );
     return { kind: "would-rescue", branch: target.branch, createdBranch: target.createdBranch };
   }
-  const staged = stageAllExcept([RUN_LOCK_RELATIVE_PATH]);
+  const staged = stageAllExcept([...AUTOMATA_OWN_PATHS]);
   if (!staged.ok) {
     options.log(`  rescue    FAILED to stage the changes: ${staged.stderr}
 `);
@@ -4422,13 +4670,13 @@ import {
   accessSync as accessSync2,
   appendFileSync,
   constants as constants2,
-  readFileSync as readFileSync5,
+  readFileSync as readFileSync6,
   renameSync as renameSync2,
-  unlinkSync as unlinkSync2,
-  writeFileSync as writeFileSync2
+  unlinkSync as unlinkSync3,
+  writeFileSync as writeFileSync3
 } from "fs";
 import { randomUUID as randomUUID2 } from "crypto";
-import { dirname as dirname2, join as join4 } from "path";
+import { dirname as dirname2, join as join5 } from "path";
 var EXECUTION_LOG_FILE = "automata-execution.log";
 var WORK_LOG_FILE = "automata-work.log";
 var MAX_EXECUTION_LINES = 1e3;
@@ -4444,6 +4692,14 @@ var OUTCOMES = [
 function operationLogDirectory() {
   return dirname2(process.cwd());
 }
+function inspectLogDirectory(dir = operationLogDirectory(), cwd = process.cwd()) {
+  try {
+    accessSync2(dir, constants2.W_OK);
+    return { dir, cwd, writable: true, detail: null };
+  } catch (err) {
+    return { dir, cwd, writable: false, detail: err.message };
+  }
+}
 function repoField(repo) {
   if (repo === null) return "-";
   const flat = oneLine(repo);
@@ -4550,18 +4806,18 @@ function pruneOldRecords(content, now, maxAgeMs) {
   }).map((group) => group.lines.join("\n") + "\n").join("");
 }
 function appendWithRetention(dir, file, content, retain) {
-  const target = join4(dir, file);
+  const target = join5(dir, file);
   appendFileSync(target, content, "utf8");
-  const existing = readFileSync5(target, "utf8");
+  const existing = readFileSync6(target, "utf8");
   const retained = retain(existing);
   if (retained === existing) return;
   const temp = `${target}.${randomUUID2()}.tmp`;
   try {
-    writeFileSync2(temp, retained, "utf8");
+    writeFileSync3(temp, retained, "utf8");
     renameSync2(temp, target);
   } finally {
     try {
-      unlinkSync2(temp);
+      unlinkSync3(temp);
     } catch {
     }
   }
@@ -4599,7 +4855,7 @@ function isOutcome(value) {
 }
 function readLogFile(path) {
   try {
-    return { content: readFileSync5(path, "utf8"), error: null };
+    return { content: readFileSync6(path, "utf8"), error: null };
   } catch (err) {
     if (err.code === "ENOENT") return { content: null, error: null };
     return { content: null, error: err.message };
@@ -4665,7 +4921,7 @@ function parseExecutionLine(line) {
   };
 }
 function readExecutionTicks(options = {}) {
-  const path = join4(options.dir ?? operationLogDirectory(), EXECUTION_LOG_FILE);
+  const path = join5(options.dir ?? operationLogDirectory(), EXECUTION_LOG_FILE);
   const { content, error } = readLogFile(path);
   if (content === null) return emptyResult(path, error, isFiltered(options.repo));
   const entries = [];
@@ -4727,7 +4983,7 @@ function parseWorkItem(line) {
   };
 }
 function readWorkRecords(options = {}) {
-  const path = join4(options.dir ?? operationLogDirectory(), WORK_LOG_FILE);
+  const path = join5(options.dir ?? operationLogDirectory(), WORK_LOG_FILE);
   const { content, error } = readLogFile(path);
   if (content === null) return emptyResult(path, error, isFiltered(options.repo));
   const entries = [];
@@ -4779,11 +5035,14 @@ function readWorkRecords(options = {}) {
 import { spawnSync as spawnSync7 } from "child_process";
 var GIT_BIN = resolveCommand("git");
 function git(args) {
+  const startedAt = Date.now();
   const result = spawnSync7(GIT_BIN, args, { encoding: "utf8" });
+  const status = result.status ?? 1;
+  recordCommand(GIT_BIN, args, startedAt, result.error ? -1 : status);
   return {
     stdout: result.stdout ?? "",
     stderr: result.stderr ?? "",
-    status: result.status ?? 1
+    status
   };
 }
 function notARepo(baseBranch, detail) {
@@ -4804,7 +5063,8 @@ function notARepo(baseBranch, detail) {
   };
 }
 function isOwnLockFile(porcelainEntry) {
-  return porcelainEntry.slice(3).trim().endsWith(RUN_LOCK_RELATIVE_PATH);
+  const path = porcelainEntry.slice(3).trim();
+  return AUTOMATA_OWN_PATHS.some((own) => path.endsWith(own));
 }
 function divergence(upstream, branch) {
   const { stdout, status } = git([
@@ -4890,6 +5150,9 @@ function inspectRepoStatus(options) {
 }
 
 // src/run/checkReport.ts
+function finding(summary, command) {
+  return { summary, command };
+}
 var SECTION_ORDER = [
   "lock",
   "ticks",
@@ -4951,36 +5214,84 @@ function build(id, lines, problems, data) {
     id,
     title: SECTION_TITLES[id],
     lines,
-    problems: problems.map((summary) => ({ section: id, summary })),
+    problems: problems.map((item) => ({ section: id, ...item })),
     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 };
+function describeOwnerLocation(owner, context, lines, problems) {
+  if (owner.cwd === void 0) {
+    lines.push("  working directory: not recorded (lock written by an older automata)");
+    return;
+  }
+  lines.push(`  working directory: ${owner.cwd}`);
+  if (owner.cwd === context.cwd) return;
+  const ownerLogs = context.parentOf(owner.cwd);
+  lines.push(`  logs to ${ownerLogs} (this check reads ${context.logDirectory})`);
+  problems.push(
+    finding(
+      `the tick holding the lock runs from \`${owner.cwd}\` and writes its operation logs to \`${ownerLogs}\`, while this check reads \`${context.logDirectory}\` \u2014 the two will not agree about what has run; run the check from the directory the scheduler uses`,
+      `ls -l ${ownerLogs}/automata-execution.log`
+    )
+  );
+}
+function describeHeartbeat(heartbeat, now, lines) {
+  if (heartbeat === void 0 || heartbeat === null) {
+    lines.push("  phase: not reported (no heartbeat from this holder)");
+    return;
+  }
+  const updated = Date.parse(heartbeat.updatedAt);
+  const age = Number.isNaN(updated) ? "unknown" : `${describeDuration(now.getTime() - updated)} ago`;
+  const item = heartbeat.item === null ? "" : ` \u2014 item ${String(heartbeat.item.index)} of ${String(heartbeat.item.total)}, ${heartbeat.item.subject}`;
+  lines.push(`  phase: ${heartbeat.phase}${item} (updated ${age})`);
+  if (heartbeat.executor === null) return;
+  const started = Date.parse(heartbeat.executor.startedAt);
+  const running = Number.isNaN(started) ? `since ${heartbeat.executor.startedAt}` : `running for ${describeDuration(now.getTime() - started)}`;
+  lines.push(`  executor: ${heartbeat.executor.command}, ${running}`);
+}
+function lockSection(status, staleMinutes, context, now = /* @__PURE__ */ new Date()) {
+  const data = {
+    status: status.kind,
+    staleMinutes,
+    cwd: context.cwd,
+    logDirectory: context.logDirectory
+  };
   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}`], [], {
+      const lines = [`a tick is running: ${describeOwner(status.owner)}${held}`];
+      const problems = [];
+      describeOwnerLocation(status.owner, context, lines, problems);
+      describeHeartbeat(status.heartbeat, now, lines);
+      return build("lock", lines, problems, {
         ...data,
         owner: status.owner,
-        heldForMs: status.heldForMs
+        heldForMs: status.heldForMs,
+        heartbeat: status.heartbeat ?? null
       });
     }
     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 }
+      const lines = [`a tick has held the lock for ${held}: ${describeOwner(status.owner)}`];
+      const problems = [];
+      describeOwnerLocation(status.owner, context, lines, problems);
+      describeHeartbeat(status.heartbeat, now, lines);
+      problems.push(
+        finding(
+          `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\``,
+          `ps -p ${String(status.owner.pid)} -o pid,lstart,args`
+        )
       );
+      return build("lock", lines, problems, {
+        ...data,
+        owner: status.owner,
+        heldForMs: status.heldForMs,
+        heartbeat: status.heartbeat ?? null
+      });
     }
     case "stale":
       return build(
@@ -4989,7 +5300,10 @@ function lockSection(status, staleMinutes) {
           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"
+          finding(
+            "a stale run lock is present; the next tick reclaims it automatically, so no action is needed unless ticks keep being turned away",
+            "cat .automata/automata.lock"
+          )
         ],
         { ...data, owner: status.owner, heldForMs: status.heldForMs }
       );
@@ -4997,7 +5311,12 @@ function lockSection(status, staleMinutes) {
       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}`],
+        [
+          finding(
+            `the run lock at \`.automata/automata.lock\` could not be read: ${status.detail}`,
+            "ls -l .automata/automata.lock"
+          )
+        ],
         { ...data, detail: status.detail }
       );
   }
@@ -5019,28 +5338,56 @@ 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}`
+      problem: finding(
+        `the execution log \`${read.path}\` could not be read: ${read.error}`,
+        `ls -l ${read.path}`
+      ),
+      explainedByLiveTick: false
     };
   }
   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`
+      problem: finding(
+        `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`,
+        `ls -la ${read.path}`
+      ),
+      explainedByLiveTick: true
     };
   }
   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"
+      problem: finding(
+        "the execution log holds no tick for this repository \u2014 the scheduler has never successfully run `do-work` here",
+        `tail -5 ${read.path}`
+      ),
+      explainedByLiveTick: true
     };
   }
   return null;
 }
-function describeTickHistory(ticks, cadence, now, lines, problems) {
+function describeLogDirectory(directory, lines, problems) {
+  const writable = directory.writable ? "writable" : `not writable: ${directory.detail ?? "unknown"}`;
+  lines.push(
+    `log directory: ${directory.dir} (the parent of the working directory ${directory.cwd}), ${writable}`
+  );
+  if (directory.writable) return;
+  problems.push(
+    finding(
+      `the operation log directory \`${directory.dir}\` is not writable (${directory.detail ?? "unknown"}), so every tick records nothing and this report can only ever be blank; make it writable by the account the scheduler runs as`,
+      `ls -ld ${directory.dir}`
+    )
+  );
+}
+function describeTickHistory(ticks, cadence, now, logPath, 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`
+      finding(
+        `the last tick exited ${String(ticks[0].exitCode)} \u2014 see \`Last work\` below and the work log for the item that failed`,
+        "automata do-work --check --verbose"
+      )
     );
   }
   const lockHeld = ticks.filter((tick) => tick.note === "lock-held").length;
@@ -5050,7 +5397,10 @@ function describeTickHistory(ticks, cadence, now, lines, problems) {
   );
   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"
+      finding(
+        "every recorded tick was turned away by a held run lock \u2014 a previous tick is wedged; see `Run lock` above",
+        "cat .automata/automata.lock"
+      )
     );
   }
   if (cadence.medianIntervalMs === null) {
@@ -5060,24 +5410,38 @@ function describeTickHistory(ticks, cadence, now, lines, problems) {
   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)`
+      finding(
+        `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)`,
+        // The log's own tail is the only thing automata can offer: the
+        // scheduler belongs to the host, and naming a `crontab -l` here would
+        // be a guess about how this installation is driven.
+        `tail -5 ${logPath}`
+      )
     );
   }
 }
 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) {
+function tickSection(read, now, directory, lockStatus) {
   const lines = [];
   const problems = [];
   const ticks = read.entries;
   const cadence = tickCadence(ticks, now);
+  const tickInFlight = lockStatus.kind === "held" || lockStatus.kind === "suspect";
+  describeLogDirectory(directory, lines, problems);
   const missing = describeMissingTicks(read);
   if (missing !== null) {
     lines.push(missing.line);
-    problems.push(missing.problem);
+    if (tickInFlight && missing.explainedByLiveTick) {
+      lines.push(
+        "a tick is running and has not recorded itself yet \u2014 the log is written when a tick ends, so this is the expected state for a first tick still in flight"
+      );
+    } else {
+      problems.push(missing.problem);
+    }
   } else {
-    describeTickHistory(ticks, cadence, now, lines, problems);
+    describeTickHistory(ticks, cadence, now, read.path, lines, problems);
   }
   if (!read.filtered && read.present) lines.push(unfilteredLine("line(s)"));
   if (read.skipped > 0)
@@ -5095,7 +5459,9 @@ function tickSection(read, now) {
     otherRepos: read.otherRepos,
     filtered: read.filtered,
     logPath: read.path,
-    logPresent: read.present
+    logPresent: read.present,
+    logDirectory: directory,
+    tickInFlight
   });
 }
 function describeWorkItem(item) {
@@ -5115,7 +5481,9 @@ function workSection(read, now) {
   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}`);
+    problems.push(
+      finding(`the work log \`${read.path}\` could not be read: ${read.error}`, `ls -l ${read.path}`)
+    );
   } else if (!read.present || records.length === 0) {
     lines.push("no tick has invoked the executor in the retained window");
   } else {
@@ -5138,7 +5506,12 @@ function workSection(read, now) {
 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");
+    problems.push(
+      finding(
+        "HEAD is detached; the pre-flight expects a branch, so check one out",
+        "git status --short --branch"
+      )
+    );
   } else {
     const at = status.head === null ? "" : ` at ${status.head}`;
     lines.push(`on ${status.branch}${at}`);
@@ -5146,7 +5519,10 @@ function describeCheckout(status, lines, problems) {
   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`
+      finding(
+        `\`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`,
+        "git status --porcelain"
+      )
     );
     return;
   }
@@ -5157,21 +5533,30 @@ function describeCheckout(status, lines, problems) {
   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`
+    finding(
+      `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`,
+      "git status --porcelain"
+    )
   );
 }
 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>\``
+      finding(
+        `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>\``,
+        "git branch --list --all"
+      )
     );
     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`
+      finding(
+        `the base branch \`${status.baseBranch}\` has no upstream, so the pre-flight cannot fast-forward it`,
+        `git branch -vv --list ${status.baseBranch}`
+      )
     );
     return;
   }
@@ -5180,7 +5565,10 @@ function describeBaseBranch(status, lines, problems) {
       `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}\``
+      finding(
+        `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}\``,
+        `git branch -vv --list ${status.baseBranch}`
+      )
     );
   }
   const freshness = status.refreshed ? "" : " (not refreshed)";
@@ -5191,14 +5579,20 @@ function describeBaseBranch(status, lines, problems) {
   );
   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`
+      finding(
+        `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`,
+        `git rev-list --left-right --count ${status.upstream}...${status.baseBranch}`
+      )
     );
     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`
+      finding(
+        `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`,
+        `git log --oneline --left-right ${status.upstream}...${status.baseBranch}`
+      )
     );
     return;
   }
@@ -5211,7 +5605,7 @@ function gitSection(status) {
     return build(
       "git",
       [`not a usable git repository: ${status.error}`],
-      [`not a usable git repository: ${status.error}`],
+      [finding(`not a usable git repository: ${status.error}`, "git rev-parse --is-inside-work-tree")],
       {
         ...status
       }
@@ -5222,7 +5616,10 @@ function gitSection(status) {
   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`
+      finding(
+        `\`git fetch\` failed (${status.fetchError}); the ahead/behind figures above are from the last successful fetch and may be out of date`,
+        "git fetch origin"
+      )
     );
   }
   return build("git", lines, problems, { ...status });
@@ -5240,26 +5637,38 @@ function assembleReport(input) {
     offline: input.offline,
     sections: ordered,
     problems,
-    exitCode: problems.length === 0 ? 0 : 1
+    exitCode: problems.length === 0 ? 0 : 1,
+    trace: input.trace ?? null,
+    blocked: input.blocked ?? null
   };
 }
+function renderBlock(title, body, empty) {
+  return [title, ...(body.length === 0 ? [empty] : body).map((line) => `  ${line}`), ""];
+}
+function renderTrace(trace) {
+  return renderBlock(
+    `Commands (${String(trace.length)})`,
+    trace.map(describeTracedCommand),
+    "(no git or gh command was run)"
+  );
+}
+function renderProblems(problems) {
+  const body = problems.flatMap((problem) => [
+    `\xB7 ${problem.section}: ${problem.summary}`,
+    // Indented under its problem rather than beside it: the command is a
+    // follow-up to that one finding, not another finding.
+    ...problem.command === null ? [] : [`    try: ${problem.command}`]
+  ]);
+  return [`Problems (${String(problems.length)})`, ...body.map((line) => `  ${line}`), ""];
+}
 function renderText(report) {
   const head = `automata do-work --check \u2014 ${report.repo ?? "unknown repository"} \u2014 ${report.generatedAt.toISOString()}`;
-  const parts = [head, ""];
+  const parts = report.blocked === null ? [head, ""] : [`blocked: ${report.blocked.trigger}`, 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(...renderBlock(section.title, section.lines, "(nothing to report)"));
   }
+  if (report.trace !== null) parts.push(...renderTrace(report.trace));
+  if (report.problems.length > 0) parts.push(...renderProblems(report.problems));
   parts.push(
     report.problems.length === 0 ? "RESULT: healthy" : `RESULT: ${String(report.problems.length)} problem(s) found`
   );
@@ -5281,13 +5690,21 @@ function toJson(report) {
     offline: report.offline,
     exitCode: report.exitCode,
     problems: report.problems,
-    sections
+    sections,
+    trace: report.trace,
+    blocked: report.blocked
   };
 }
 
 // src/commands/doWork.ts
+import { dirname as dirname3 } from "path";
 var inFlightMarker = null;
 var inFlightSync = null;
+var lockHandle = null;
+var heartbeatItem = null;
+function beat(update) {
+  lockHandle?.heartbeat(update);
+}
 function subjectLabel(issue, pr) {
   if (issue !== null) return `#${String(issue)}`;
   return pr === null ? "#?" : `PR #${String(pr)}`;
@@ -5342,11 +5759,6 @@ function resolveSettingsResult(options, verifyIdentity) {
     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") {
     failSettings(
@@ -5419,6 +5831,7 @@ function buildSettings(options, verifyIdentity) {
     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,
+    dumpOnBlock: doWork.dumpOnBlock ?? DEFAULT_DO_WORK.dumpOnBlock,
     limit: parsePositiveInt(options.limit, "--limit"),
     participants: { allowedUsers, agentUser },
     prompts: {
@@ -5580,11 +5993,19 @@ function validateDoWorkConfig(section) {
   validateOptionalString(section, "baseBranch", "doWork.baseBranch");
   validateOptionalInt(section, "maxRunsPerTick", "doWork.maxRunsPerTick", 0, "a non-negative integer (0 = unlimited)");
   validateOptionalInt(section, "lockStaleMinutes", "doWork.lockStaleMinutes", 1, "a positive integer");
+  validateOptionalBoolean(section, "dumpOnBlock", "doWork.dumpOnBlock");
   validateProtectedBranches(section["protectedBranches"]);
   validateSettingContainer(section["models"], "models", ["claude", "codex"]);
   validateSettingContainer(section["effort"], "effort", ["claude", "codex"]);
   validateSettingContainer(section["prompts"], "prompts", ["issueDiscuss", "prWork", "prOrphan"]);
 }
+function validateOptionalBoolean(container, key, path) {
+  const value = container[key];
+  if (value === void 0 || value === null) return;
+  if (typeof value !== "boolean") {
+    failSettings(`${path} must be true or false, got ${JSON.stringify(value)}.`);
+  }
+}
 function validateProtectedBranches(value) {
   if (value === void 0 || value === null) return;
   const isNonEmptyString = (b) => typeof b === "string" && b.trim().length > 0;
@@ -5894,6 +6315,11 @@ function reportNoAnswer(item, marker, runError) {
   return runError === null ? { outcome: "answered-no-reply", detail: "run finished but posted no answer", reason: "no-answer" } : { outcome: "failed", detail: `run failed: ${runError.message}`, reason: "no-answer" };
 }
 async function invokeExecutor(prompt, execution, silent) {
+  beat({
+    phase: "item",
+    item: heartbeatItem,
+    executor: { command: execution.executor, startedAt: (/* @__PURE__ */ new Date()).toISOString() }
+  });
   if (execution.executor === "codex") {
     await runCodex(prompt, { model: execution.model, effort: execution.effort });
     return;
@@ -6143,37 +6569,82 @@ var doWorkCommand = new Command6("do-work").description(
 ).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(
+  "--verbose",
+  "Show the work behind the report: every `git` and `gh` invocation with its duration and exit code, the discovery query as sent, and every candidate considered. Applies to --check and to a blocked-exit dump"
 ).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 exitCode = await runDoWork(options);
+  if (exitCode !== 0) process.exit(exitCode);
+});
+async function runDoWork(options) {
+  try {
+    return await runDoWorkTraced(options);
+  } finally {
+    stopCommandTrace();
+  }
+}
+async function runDoWorkTraced(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);
+      return 1;
     }
-    const exitCode2 = runCheck(options);
-    if (exitCode2 !== 0) process.exit(exitCode2);
-    return;
+    return runCheck(options);
   }
+  if (options.verbose === true) startCommandTrace();
   if (options.dryRun !== true) loggableInvocation = { startedAt };
-  const settings = resolveSettings(options);
+  const resolved = resolveSettingsResult(options, options.dryRun !== true);
+  if (!resolved.ok) {
+    const payload = dumpBlocked(options, {
+      reason: "config-invalid",
+      trigger: `configuration is not usable \u2014 ${resolved.error}`,
+      selection: null,
+      resolved
+    });
+    if (payload !== null) out(JSON.stringify({ blocked: payload, exitCode: 1 }, null, 2) + "\n");
+    fail(resolved.error);
+  }
+  const settings = resolved.settings;
   if (options.dryRun === true) {
     const { exitCode: exitCode2 } = await runTick(settings, options);
-    if (exitCode2 !== 0) process.exit(exitCode2);
-    return;
+    return exitCode2;
   }
   loggableInvocation = null;
   const lock = acquireRunLock("do-work", settings.lockStaleMinutes);
   if (!lock.ok) {
-    const exitCode2 = reportLockHeld(lock, settings, options);
+    const exitCode2 = reportLockHeld(lock, settings, options, resolved);
     logTick([], exitCode2, startedAt, "lock-held");
-    if (exitCode2 !== 0) process.exit(exitCode2);
-    return;
+    return exitCode2;
+  }
+  const { exitCode, reports } = await runTickUnderLock(lock.handle, settings, options);
+  logTick(reports, exitCode, startedAt);
+  return exitCode;
+}
+async function runTickUnderLock(handle, settings, options) {
+  lockHandle = handle;
+  const onSignal = interruptHandler(handle);
+  process.once("SIGINT", onSignal);
+  process.once("SIGTERM", onSignal);
+  try {
+    return await runTick(settings, options);
+  } catch (err) {
+    process.stderr.write(`Error: ${err.message}
+`);
+    return { exitCode: 1, reports: [] };
+  } finally {
+    lockHandle = null;
+    heartbeatItem = null;
+    handle.release();
+    process.removeListener("SIGINT", onSignal);
+    process.removeListener("SIGTERM", onSignal);
   }
-  const handle = lock.handle;
+}
+function interruptHandler(handle) {
   let shuttingDown = false;
-  const onSignal = () => {
+  return () => {
     if (shuttingDown) return;
     shuttingDown = true;
     progress("\nInterrupted: stopping the executor before releasing the run lock\u2026\n");
@@ -6189,26 +6660,7 @@ var doWorkCommand = new Command6("do-work").description(
       process.exit(130);
     });
   };
-  process.once("SIGINT", onSignal);
-  process.once("SIGTERM", onSignal);
-  let exitCode;
-  let reports = [];
-  try {
-    const result = await runTick(settings, options);
-    exitCode = result.exitCode;
-    reports = result.reports;
-  } catch (err) {
-    process.stderr.write(`Error: ${err.message}
-`);
-    exitCode = 1;
-  } finally {
-    handle.release();
-    process.removeListener("SIGINT", onSignal);
-    process.removeListener("SIGTERM", onSignal);
-  }
-  logTick(reports, exitCode, startedAt);
-  if (exitCode !== 0) process.exit(exitCode);
-});
+}
 function resolveRepoSlug() {
   try {
     const slug = getRepoSlug();
@@ -6217,7 +6669,24 @@ function resolveRepoSlug() {
     return null;
   }
 }
-function collectSelection(settings) {
+function buildSelectionEvidence(settings, issues, linkMap, decisions, verbose) {
+  const issuePass = issuePassEnabled(settings);
+  const orphanPass = orphanPassEnabled(settings);
+  return {
+    decisions,
+    issuePass,
+    orphanPass,
+    issues: verbose && issuePass ? issues : null,
+    // Read off the link map rather than off `discoverOrphanPrs`, which returns
+    // only the survivors — the whole point here is to show what was dropped.
+    orphans: verbose && orphanPass ? linkMap.orphans.map((candidate) => ({
+      number: candidate.pr.number,
+      title: candidate.pr.title,
+      matched: prMatchesFilter(candidate, settings)
+    })) : null
+  };
+}
+function collectSelection(settings, verbose) {
   const issues = discoverIssues(settings);
   const linkMap = getOpenPrLinkMap();
   const policy = {
@@ -6225,52 +6694,135 @@ function collectSelection(settings) {
     defaultBranch: linkMap.defaultBranch,
     protectedBranches: settings.protectedBranches
   };
-  return skipDuplicateHeadBranches([
+  const decisions = 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)
     )
   ]);
+  return buildSelectionEvidence(settings, issues, linkMap, decisions, verbose);
 }
-function selectionSection(settings, offline) {
-  const section = (lines2, problems, data) => ({
+function makeSelectionSection(lines, problems, data) {
+  return {
     id: "selection",
     title: sectionTitle("selection"),
-    lines: lines2,
-    problems: problems.map((summary) => ({ section: "selection", summary })),
+    lines,
+    problems: problems.map((problem) => ({ section: "selection", ...problem })),
     data
-  });
+  };
+}
+function describeSelectionEvidence(settings, evidence, lines) {
+  lines.push(
+    ...describeIssueEvidence(settings, evidence),
+    ...describeOrphanEvidence(settings, evidence)
+  );
+}
+function heading(text, count) {
+  return `${text}${count === 0 ? "" : ":"}`;
+}
+function describeIssueEvidence(settings, evidence) {
+  if (!evidence.issuePass) {
+    return [
+      `issue discovery: not run \u2014 --pr ${String(settings.onlyPr)} restricts this tick to that pull request`
+    ];
+  }
+  const restriction = settings.onlyIssue === void 0 ? "" : `, restricted to #${String(settings.onlyIssue)}`;
+  const lines = [
+    `discovery query: ${settings.technique} = ${settings.discoveryValue}, limit ${String(settings.limit)}${restriction}`
+  ];
+  if (evidence.issues === null) return lines;
+  lines.push(heading(`discovery returned ${String(evidence.issues.length)} issue(s)`, evidence.issues.length));
+  for (const issue of evidence.issues) {
+    lines.push(`    #${String(issue.number)} ${issue.title}`);
+  }
+  return lines;
+}
+function describeOrphanEvidence(settings, evidence) {
+  if (!evidence.orphanPass) {
+    return [
+      `orphan pull-request pass: not run \u2014 --issue ${String(settings.onlyIssue)} restricts this tick to that issue`
+    ];
+  }
+  if (evidence.orphans === null) return [];
+  const restriction = settings.onlyPr === void 0 ? "" : ` (only PR #${String(settings.onlyPr)} would be taken up)`;
+  const lines = [
+    heading(
+      `${String(evidence.orphans.length)} open orphan pull request(s) considered${restriction}`,
+      evidence.orphans.length
+    )
+  ];
+  for (const orphan of evidence.orphans) {
+    const verdict = orphan.matched ? "matches the filter" : "dropped by the discovery filter";
+    lines.push(`    PR #${String(orphan.number)} ${orphan.title} \u2014 ${verdict}`);
+  }
+  return lines;
+}
+function describeSelectionDecisions(decisions) {
+  const work = decisions.filter((decision) => decision.kind === "work").length;
+  return [
+    `${String(work)} of ${String(decisions.length)} candidate(s) would be picked up`,
+    ...describePlan(decisions).trimEnd().split("\n")
+  ];
+}
+function selectionSection(settings, offline, verbose) {
   if (offline) {
-    return section(
+    return makeSelectionSection(
       ["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(
+    return makeSelectionSection(
       ["not run: the configuration could not be resolved \u2014 see Environment below"],
       [],
       { ran: false, detail: "configuration invalid", plan: [] }
     );
   }
-  let decisions;
+  let evidence;
   try {
-    decisions = collectSelection(settings);
+    evidence = collectSelection(settings, verbose);
   } catch (err) {
     const detail = err.message;
-    return section(
+    return makeSelectionSection(
       [`could not be computed: ${detail}`],
-      [`the GitHub selection could not be computed: ${detail}`],
+      [
+        {
+          summary: `the GitHub selection could not be computed: ${detail}`,
+          command: `gh issue list --limit ${String(settings.limit)}`
+        }
+      ],
       { 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) });
+  const lines = [];
+  if (verbose) describeSelectionEvidence(settings, evidence, lines);
+  lines.push(...describeSelectionDecisions(evidence.decisions));
+  return makeSelectionSection(lines, [], selectionData(evidence));
+}
+function selectionData(evidence) {
+  return {
+    ran: true,
+    detail: null,
+    plan: evidence.decisions.map(toPlanJson),
+    issues: evidence.issues,
+    orphans: evidence.orphans,
+    issuePass: evidence.issuePass,
+    orphanPass: evidence.orphanPass
+  };
+}
+function selectionSectionFromEvidence(settings, evidence, verbose) {
+  if (evidence === null) {
+    return makeSelectionSection(
+      ["not run: the tick was blocked before discovery"],
+      [],
+      { ran: false, detail: "blocked before discovery", plan: [] }
+    );
+  }
+  const lines = [];
+  if (verbose && settings !== null) describeSelectionEvidence(settings, evidence, lines);
+  lines.push(...describeSelectionDecisions(evidence.decisions));
+  return makeSelectionSection(lines, [], selectionData(evidence));
 }
 function describeExecutor(settings, lines, problems) {
   const executor = settings.withOption ?? settings.configExecutor ?? "claude";
@@ -6279,15 +6831,16 @@ function describeExecutor(settings, lines, problems) {
   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`
-    );
+    problems.push({
+      summary: `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`,
+      command: `command -v ${command}`
+    });
   }
   return { executor, command, onPath };
 }
-function describeGitHubIdentity(options, settings, lines, problems) {
-  if (options.fetch === false) {
-    lines.push("`gh` authentication not checked: --no-fetch");
+function describeGitHubIdentity(checkIdentity, settings, lines, problems, reason) {
+  if (!checkIdentity) {
+    lines.push(`\`gh\` authentication not checked: ${reason}`);
     return { ghAvailable: null, ghLogin: null, identityProblem: null };
   }
   let identity;
@@ -6296,14 +6849,18 @@ function describeGitHubIdentity(options, settings, lines, problems) {
   } 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\``);
+    problems.push({
+      summary: `\`gh\` could not be queried (${detail}); install it and run \`gh auth login\``,
+      command: "gh auth status"
+    });
     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`
-    );
+    problems.push({
+      summary: `\`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`,
+      command: "gh auth status"
+    });
     return { ghAvailable: false, ghLogin: null, identityProblem: null };
   }
   const ghLogin = identity.kind === "login" ? identity.login : null;
@@ -6315,7 +6872,9 @@ function describeGitHubIdentity(options, settings, lines, problems) {
     settings.participants.agentUser,
     settings.participants.allowedUsers
   );
-  if (identityProblem !== null) problems.push(identityProblem);
+  if (identityProblem !== null) {
+    problems.push({ summary: identityProblem, command: "automata config get" });
+  }
   return { ghAvailable: true, ghLogin, identityProblem };
 }
 function readRemoteType() {
@@ -6325,7 +6884,7 @@ function readRemoteType() {
     return null;
   }
 }
-function environmentSection(options, resolved, repo) {
+function environmentSection(checkIdentity, identitySkipReason, resolved, repo) {
   const lines = [`automata ${version}`];
   const problems = [];
   const remoteType = readRemoteType();
@@ -6338,20 +6897,24 @@ function environmentSection(options, resolved, repo) {
   };
   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"
-    );
+    problems.push({
+      summary: "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",
+      command: "git remote -v"
+    });
   } 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}`);
+    problems.push({
+      summary: `the configuration is not usable: ${resolved.error}`,
+      command: "automata config get"
+    });
     return {
       id: "environment",
       title: sectionTitle("environment"),
       lines,
-      problems: problems.map((summary) => ({ section: "environment", summary })),
+      problems: problems.map((problem) => ({ section: "environment", ...problem })),
       // `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 }
@@ -6367,16 +6930,17 @@ function environmentSection(options, resolved, repo) {
   );
   const { executor, command, onPath } = describeExecutor(settings, lines, problems);
   const { ghAvailable, ghLogin, identityProblem } = describeGitHubIdentity(
-    options,
+    checkIdentity,
     settings,
     lines,
-    problems
+    problems,
+    identitySkipReason
   );
   return {
     id: "environment",
     title: sectionTitle("environment"),
     lines,
-    problems: problems.map((summary) => ({ section: "environment", summary })),
+    problems: problems.map((problem) => ({ section: "environment", ...problem })),
     data: {
       ...data,
       discovery: { technique: settings.technique, value: settings.discoveryValue },
@@ -6392,30 +6956,121 @@ function environmentSection(options, resolved, repo) {
     }
   };
 }
+function buildCheckReport(input) {
+  const settings = input.resolved.ok ? input.resolved.settings : null;
+  const staleMinutes = settings?.lockStaleMinutes ?? DEFAULT_DO_WORK.lockStaleMinutes;
+  const baseBranch = settings?.baseBranch ?? DEFAULT_DO_WORK.baseBranch;
+  const lockStatus = inspectRunLock(staleMinutes);
+  const logDirectory = inspectLogDirectory();
+  const lockContext = {
+    cwd: logDirectory.cwd,
+    logDirectory: logDirectory.dir,
+    parentOf: dirname3
+  };
+  return assembleReport({
+    generatedAt: input.now,
+    repo: input.repo,
+    offline: input.offline,
+    blocked: input.blocked,
+    sections: [
+      lockSection(lockStatus, staleMinutes, lockContext, input.now),
+      tickSection(
+        readExecutionTicks({ repo: input.repo, limit: TICK_HISTORY }),
+        input.now,
+        logDirectory,
+        lockStatus
+      ),
+      workSection(readWorkRecords({ repo: input.repo, limit: WORK_HISTORY }), input.now),
+      gitSection(inspectRepoStatus({ baseBranch, fetch: input.fetch })),
+      input.selection,
+      environmentSection(input.checkIdentity, input.identitySkipReason, input.resolved, input.repo)
+    ],
+    // Taken last, so the trace covers every command the collectors above made.
+    trace: takeCommandTrace()
+  });
+}
 function runCheck(options) {
+  const verbose = options.verbose === true;
+  if (verbose) startCommandTrace();
   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,
+  const report = buildCheckReport({
+    now,
     repo,
+    resolved,
+    selection: selectionSection(settings, offline, verbose),
+    fetch: !offline,
+    checkIdentity: !offline,
+    identitySkipReason: "--no-fetch",
     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)
-    ]
+    blocked: null
   });
   out(options.json === true ? JSON.stringify(toJson(report), null, 2) + "\n" : renderText(report));
   return report.exitCode;
 }
+function dumpOnBlockEnabled(resolved) {
+  if (resolved.ok) return resolved.settings.dumpOnBlock;
+  try {
+    return readConfig().doWork?.dumpOnBlock ?? DEFAULT_DO_WORK.dumpOnBlock;
+  } catch {
+    return DEFAULT_DO_WORK.dumpOnBlock;
+  }
+}
+function buildBlockedReport(context, verbose) {
+  return buildCheckReport({
+    now: /* @__PURE__ */ new Date(),
+    repo: resolveRepoSlug(),
+    resolved: context.resolved,
+    selection: selectionSectionFromEvidence(
+      context.resolved.ok ? context.resolved.settings : null,
+      context.selection,
+      verbose
+    ),
+    fetch: false,
+    checkIdentity: false,
+    identitySkipReason: "the tick is exiting and the dump makes no network call",
+    offline: true,
+    blocked: { reason: context.reason, trigger: context.trigger }
+  });
+}
+function dumpBlocked(options, context) {
+  if (!dumpOnBlockEnabled(context.resolved)) return null;
+  try {
+    const report = buildBlockedReport(context, options.verbose === true);
+    if (options.json === true) {
+      return { reason: context.reason, trigger: context.trigger, report: toJson(report) };
+    }
+    progress(renderText(report));
+    return null;
+  } catch (err) {
+    progress(`Warning: could not render the blocked-exit report: ${err.message}
+`);
+    return null;
+  }
+}
+function classifyBlocked(hygiene, decisions, items, reports) {
+  const ran = reports.some((report) => report.ranExecutor === true);
+  if (ran) return null;
+  if (hygiene.degraded) {
+    return {
+      reason: "preflight-failed",
+      trigger: `the pre-flight did not prepare the checkout (${describePreflightFailures(hygiene).join("; ")})`
+    };
+  }
+  if (items.length === 0) {
+    return {
+      reason: "no-candidates",
+      trigger: `no candidate was picked up (0 of ${String(decisions.length)})`
+    };
+  }
+  return {
+    reason: "all-skipped",
+    trigger: `${String(items.length)} item(s) selected, none reached the executor`
+  };
+}
 function toTickLogItem(report) {
   return {
     subject: reportLabel(report),
@@ -6447,22 +7102,41 @@ function logTick(reports, exitCode, startedAt, note) {
     items: reports.map(toTickLogItem)
   });
 }
-function reportLockHeld(lock, settings, options) {
+function reportLockHeld(lock, settings, options, resolved) {
   const held = lock.heldBy;
   const sentence = `Another automata instance is already running here (pid ${String(held.pid)} on ${held.host}, started ${held.startedAt}, command ${held.command}). Doing nothing.
 `;
   const suspectSentence = lock.suspect ? `Warning: that lock has been held longer than ${String(settings.lockStaleMinutes)} minutes. If no tick is really running, its process id was probably reused; remove ${RUN_LOCK_RELATIVE_PATH} once you have confirmed that.
 ` : "";
   const exitCode = lock.suspect ? 2 : 0;
+  const context = {
+    reason: "lock-held",
+    trigger: `run lock held by pid ${String(held.pid)} on ${held.host}`,
+    selection: null,
+    resolved
+  };
   if (options.json === true) {
     progress(sentence + suspectSentence);
     out(
-      JSON.stringify({ lockHeld: true, suspect: lock.suspect, heldBy: held, plan: [], items: [], exitCode }, null, 2) + "\n"
+      JSON.stringify(
+        {
+          lockHeld: true,
+          suspect: lock.suspect,
+          heldBy: held,
+          blocked: dumpBlocked(options, context),
+          plan: [],
+          items: [],
+          exitCode
+        },
+        null,
+        2
+      ) + "\n"
     );
-  } else {
-    out(sentence);
-    if (suspectSentence) progress(suspectSentence);
+    return exitCode;
   }
+  out(sentence);
+  if (suspectSentence) progress(suspectSentence);
+  dumpBlocked(options, context);
   return exitCode;
 }
 function explainInterruptedMarker() {
@@ -6479,6 +7153,7 @@ function explainInterruptedMarker() {
   }
 }
 async function runTick(settings, options) {
+  beat({ phase: "pre-flight" });
   const hygiene = runRepoHygiene({
     baseBranch: settings.baseBranch,
     protectedBranches: settings.protectedBranches,
@@ -6486,6 +7161,7 @@ async function runTick(settings, options) {
     agentUser: settings.participants.agentUser,
     log: progress
   });
+  beat({ phase: "discovery" });
   const issues = discoverIssues(settings);
   const linkMap = getOpenPrLinkMap();
   const policy = {
@@ -6511,49 +7187,85 @@ ${describePlan(decisions)}`;
     reportDryRun(items, decisions, settings, options, hygiene);
     return { exitCode: 0, reports: [] };
   }
+  const { reports, deferred } = await processItems(items, settings, options, hygiene);
+  heartbeatItem = null;
+  beat({ phase: "summary" });
+  reports.push(...reportDeferred(deferred, settings));
+  const degraded = hygiene.degraded || reports.some((report) => report.outcome !== "answered");
+  const exitCode = degraded ? 2 : 0;
+  const blockedBy = classifyBlocked(hygiene, decisions, items, reports);
+  const context = blockedBy === null ? null : {
+    ...blockedBy,
+    selection: buildSelectionEvidence(
+      settings,
+      issues,
+      linkMap,
+      decisions,
+      options.verbose === true
+    ),
+    resolved: { ok: true, settings }
+  };
+  reportTickOutcome({ options, hygiene, decisions, reports, context, exitCode });
+  return { exitCode, reports };
+}
+async function processItems(items, settings, options, hygiene) {
   const reports = [];
   const deferred = [];
   const preflightCauses = describePreflightFailures(hygiene);
   let runsUsed = 0;
-  for (const item of items) {
+  for (const [index, item] of items.entries()) {
     if (settings.maxRuns > 0 && runsUsed >= settings.maxRuns) {
       deferred.push(item);
       continue;
     }
-    let report;
-    try {
-      report = await processItem(item, settings, options.silent === true, preflightCauses);
-    } catch (err) {
-      progress(`  failed: ${err.message}
-`);
-      report = {
-        issue: item.issue?.number ?? null,
-        pr: item.pr?.number ?? null,
-        title: itemTitle(item),
-        turn: item.turn,
-        outcome: "failed",
-        detail: err.message,
-        sync: inFlightSync ?? void 0
-      };
-    }
+    heartbeatItem = { index: index + 1, total: items.length, subject: itemLabel(item).trim() };
+    beat({ phase: "item", item: heartbeatItem });
+    const report = await reportForItem(item, settings, options, preflightCauses);
     if (report.ranExecutor === true) runsUsed++;
     reports.push(report);
   }
-  for (const item of deferred) {
+  return { reports, deferred };
+}
+async function reportForItem(item, settings, options, preflightCauses) {
+  try {
+    return await processItem(item, settings, options.silent === true, preflightCauses);
+  } catch (err) {
+    progress(`  failed: ${err.message}
+`);
+    return {
+      issue: item.issue?.number ?? null,
+      pr: item.pr?.number ?? null,
+      title: itemTitle(item),
+      turn: item.turn,
+      outcome: "failed",
+      detail: err.message,
+      sync: inFlightSync ?? void 0
+    };
+  }
+}
+function reportDeferred(deferred, settings) {
+  return deferred.map((item) => {
     progress(`
 ${itemLabel(item)} deferred: --max-runs / maxRunsPerTick reached.
 `);
-    reports.push({
+    return {
       issue: item.issue?.number ?? null,
       pr: item.pr?.number ?? null,
       title: itemTitle(item),
       turn: item.turn,
       outcome: "deferred",
       detail: `run cap of ${String(settings.maxRuns)} reached`
-    });
-  }
-  const degraded = hygiene.degraded || reports.some((report) => report.outcome !== "answered");
-  const exitCode = degraded ? 2 : 0;
+    };
+  });
+}
+function reportTickOutcome({
+  options,
+  hygiene,
+  decisions,
+  reports,
+  context,
+  exitCode
+}) {
   if (options.json) {
     out(
       JSON.stringify(
@@ -6562,17 +7274,18 @@ ${itemLabel(item)} deferred: --max-runs / maxRunsPerTick reached.
           preflight: toHygieneJson(hygiene),
           plan: decisions.map(toPlanJson),
           items: reports.map(toItemJson),
+          blocked: context === null ? null : dumpBlocked(options, context),
           exitCode
         },
         null,
         2
       ) + "\n"
     );
-  } else {
-    summarizeHygiene(hygiene);
-    summarize(reports);
+    return;
   }
-  return { exitCode, reports };
+  summarizeHygiene(hygiene);
+  summarize(reports);
+  if (context !== null) dumpBlocked(options, context);
 }
 function toRunJson(entry) {
   if (entry.kind === "refused") {