dev-loops 0.5.0 → 0.7.1

package/skills/loop-grill/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: loop-grill
+description: >-
+  Standalone pre-loop Socratic Q&A grill for issues (tracker-first) or local
+  plan files (local-planning). Detects spec gaps, asks clarifying questions
+  (interactive) or self-answers them from codebase context (--auto), then
+  writes a ## Grill findings section back to the source artifact.
+allowed-tools: read bash edit write
+user-invocable: false
+---
+# Loop-grill skill
+
+A standalone, on-demand pre-loop grilling skill. Run it against an issue or a local plan file **before** the dev loop starts to surface underspecified acceptance criteria, fuzzy scope boundaries, unresolved primary actors, and undocumented hard-to-reverse decisions.
+
+It is entirely separate from the in-loop docs-grill (`docs/docs-grill-step.md`), which audits code/doc drift while the loop runs. This skill operates on the *spec* before any implementation begins.
+
+## Interface
+
+```
+/loop-grill <issue-number>             # tracker-first, interactive
+/loop-grill <issue-number> --auto      # tracker-first, auto-answer
+/loop-grill <path/to/plan.md>          # local-planning, interactive
+/loop-grill <path/to/plan.md> --auto   # local-planning, auto-answer
+```
+
+## Argument validation (fail-closed)
+
+Before doing anything else:
+
+1. Confirm exactly one positional argument is present (issue number or path). No argument → error, stop.
+2. Confirm the only optional flag is `--auto`. Any other flag → error, stop.
+3. **Tracker-first:** verify the issue exists. Non-existent issue → `Error: issue #<n> not found.`, stop.
+4. **Local-planning:** verify the file exists. Missing file → `Error: plan file not found: <path>`, stop.
+5. Never mutate any artifact when argument validation fails.
+
+## Step 1 — Load the target
+
+- **Tracker-first:** fetch the issue body (title + description + any existing `## Grill findings` section).
+- **Local-planning:** read the plan file from disk.
+
+## Step 1b — Surface external resources
+
+Before detecting gaps, scan the loaded content for external resource references: links, other repo URLs, API endpoints, doc URLs, screenshots, or Playwright navigation descriptors.
+
+- **Interactive mode:** if external resources are present, ask the operator to confirm they are accessible or to provide them before the Q&A starts.
+- **`--auto` mode:** attempt to fetch each resource using bounded wrapper commands (e.g. `gh`, API wrapper scripts under `scripts/`). Do not fetch resources inline with raw `curl` or token-heavy calls. Flag any inaccessible resource as `unresolved` in the findings rather than silently skipping it.
+- When no external resources are present, skip this step silently.
+
+## Step 2 — Detect gaps
+
+Scan the loaded content and identify each gap. The minimum required gap detectors are:
+
+| Gap kind | Detection signal |
+|---|---|
+| Missing acceptance criteria | No `## Acceptance criteria` section, or section is empty / stub |
+| Missing scope boundary | No explicit in-scope / out-of-scope statement or non-goals section |
+| Unresolved primary actor | No named user, system, or role that is the main beneficiary of the feature |
+| Undocumented hard-to-reverse decision | Destructive or irreversible operations described without a rationale or rollback note |
+
+Additional gaps discovered through semantic reading of the spec are also recorded.
+
+For each gap, classify it as either:
+- **Bounded choice** — the answer is one of a small discrete set (e.g. yes/no, A/B/C).
+- **Open-ended** — the answer requires free-form elaboration.
+
+## Step 3 — Fill gaps
+
+### Interactive mode (default)
+
+For each gap, in order:
+
+- **Bounded choice gap:** use `AskUserQuestion` with the question text and the choice options, plus an "Other / free text" option. Block until the user answers.
+- **Open-ended gap:** present the question as a plain text turn. Block until the user answers.
+
+Record each answer with its source: `human`.
+
+> `AskUserQuestion` is a Claude Code–native construct. If you are running outside Claude Code, use `--auto` mode instead.
+
+### Auto mode (`--auto`)
+
+Answer every grilling question yourself without prompting the user. Source answers from (in priority order):
+
+1. **`codebase`** — inspectable source files, tests, scripts, config in the repository.
+2. **`docs`** — markdown files under `docs/`, `skills/docs/`, and adjacent contract docs.
+3. **`context`** — `CONTEXT.md` at the repo root, if present. When absent, skip silently — do not crash, no warning required.
+4. **`inferred`** — reasoning from the issue/plan text alone, with no external citation.
+
+Record the evidence source for every answer. Flag a question as **`unresolved`** when:
+- The only available source is `inferred`, **and**
+- No codebase path, doc section, or issue/plan text can be cited as the basis for the answer.
+
+Do not silently guess an `inferred` answer when no evidence can be cited — flag it `unresolved` instead.
+
+## Step 4 — Write back (replace-section semantics)
+
+Write a `## Grill findings` section back to the source artifact using **replace-section** semantics:
+
+- **Find** the existing `## Grill findings` section: the range from the `## Grill findings` heading through the next `##`-level heading (exclusive) or end of file.
+- **Replace** that range in place with the new section content.
+- If no `## Grill findings` section exists, **append** it.
+- This makes re-runs idempotent — no accumulated noise, no duplicate sections.
+- If parsing the section boundary fails, **abort with an error** rather than silently truncating.
+
+**Tracker-first write-back:** update the GitHub issue body using:
+
+```
+gh issue edit <n> --repo <owner/repo> --body-file <tmp-path>
+```
+
+The `## Grill findings` section lives in the issue body, not as a comment. Do not use `comment-issue.mjs` here — that creates a comment, not a body update.
+
+**GitHub body size guard:** issue bodies are capped at 65,536 characters. Before writing back, check whether the updated body would exceed this limit. If so, warn: `Warning: updated body would exceed GitHub's 65,536-character limit — write-back skipped. Truncate the findings or the issue body manually.` Do not silently truncate.
+
+**Local-planning write-back:** update the plan file in place using the edit tool.
+
+## Output artifact format
+
+The `## Grill findings` section written to the artifact:
+
+```markdown
+## Grill findings
+
+<!-- loop-grill: <timestamp> mode:<interactive|auto> -->
+
+### Resolved gaps
+
+| # | Gap | Question | Answer | Source |
+|---|-----|----------|--------|--------|
+| 1 | Missing AC | <question text> | <answer text> | codebase \| docs \| context \| inferred \| human |
+
+### Unresolved gaps
+
+| # | Gap | Question | Reason unresolved |
+|---|-----|----------|-------------------|
+| 1 | Unresolved primary actor | <question text> | No citable evidence found |
+
+### Verdict
+
+grill-clean
+```
+
+Replace `grill-clean` with `N unresolved items` when unresolved gaps remain.
+
+## Step 5 — Emit verdict
+
+After write-back, emit the verdict line to stdout:
+
+- `grill-clean` when no unresolved gaps remain.
+- `N unresolved items` (e.g. `3 unresolved items`) when gaps remain after all questions are answered.
+
+## CONTEXT.md degradation rule
+
+When `CONTEXT.md` is absent from the repo root, skip the context-source check silently. Do not crash. Do not emit a warning. The grill continues with the remaining sources (`codebase`, `docs`, `inferred`).
+
+## Idempotency guarantee
+
+Running `/loop-grill` twice on the same target must produce a single `## Grill findings` section, not two. The replace-section logic handles the already-present-section case. On the second run, if the gap set is identical to the first run, the section content is replaced with an equivalent section (same questions, same answers, updated timestamp).
+
+## Non-goals
+
+- Auto-triggering from `issue_intake` — this is on-demand only.
+- Replacing or modifying the in-loop docs-grill (`docs/docs-grill-step.md`, `scripts/loop/docs-grill-contract.mjs`) — different concern, different firing surface.
+- Full DDD `CONTEXT.md` management.
+- Scheduling or storing grill runs — stateless and on-demand.
+- Any CI/CD integration.

package/scripts/loop/conductor.mjs

@@ -1,233 +0,0 @@
-#!/usr/bin/env node
-import { runConductorCycle } from "./run-conductor-cycle.mjs";
-import { runConductorMonitor } from "./conductor-monitor.mjs";
-import { requireTokenValue } from "../_cli-primitives.mjs";
-import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
-import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
-import {
-  loadDevLoopConfig,
-  resolveWorkflowConfig,
-  resolveAutonomyStopAt,
-  resolveGateConfig,
-} from "@dev-loops/core/config";
-import { readFileSync } from "node:fs";
-import path from "node:path";
-import { parseArgs } from "node:util";
-const USAGE = `Usage: conductor.mjs --repo <owner/name> [--auto-resume] [--cycle-only] [--monitor-only] [--require-retrospective]
-Unified conductor entrypoint for dev-loop lifecycle orchestration.`.trim();
-const parseError = buildParseError(USAGE);
-function checkRetrospectiveGate(cwd, requireRetrospective) {
-  if (!requireRetrospective) return { blocked: false };
-  try {
-    const checkpointPath = path.join(cwd, ".pi", "dev-loop-retrospective-checkpoint.json");
-    const checkpointText = readFileSync(checkpointPath, "utf8");
-    const checkpoint = JSON.parse(checkpointText);
-    const state = typeof checkpoint?.state === "string" ? checkpoint.state.trim().toLowerCase() : null;
-    if (state === "none" || state === "complete" || state === "skipped") {
-      return { blocked: false };
-    }
-    if (state === "required" || state === "missing" || state === null || state === "") {
-      return {
-        blocked: true,
-        reason: state === "required" || state === "missing"
-          ? `Retrospective checkpoint pending (state: ${state}). Complete the retrospective before running the conductor.`
-          : "Retrospective checkpoint file exists but has an unrecognized or empty state; cannot determine retrospective status safely.",
-      };
-    }
-    return {
-      blocked: true,
-      reason: `Retrospective checkpoint has an unrecognized state: "${state}".`,
-    };
-  } catch (err) {
-    if (err?.code === "ENOENT") return { blocked: false };
-    return { blocked: true, reason: `Cannot read retrospective checkpoint: ${err.message}` };
-  }
-}
-function parseCliArgs(argv) {
-  const options = {
-    help: false,
-    repo: undefined,
-    autoResume: false,
-    cycleOnly: false,
-    monitorOnly: false,
-    requireRetrospective: false,
-  };
-  const { tokens } = parseArgs({
-    args: [...argv],
-    options: {
-      help: { type: "boolean", short: "h" },
-      repo: { type: "string" },
-      "auto-resume": { type: "boolean" },
-      "cycle-only": { type: "boolean" },
-      "monitor-only": { type: "boolean" },
-      "require-retrospective": { type: "boolean" },
-    },
-    allowPositionals: true,
-    strict: false,
-    tokens: true,
-  });
-  for (const token of tokens) {
-    if (token.kind === "positional") {
-      throw parseError(`Unknown argument: ${token.value}`);
-    }
-    if (token.kind !== "option") {
-      continue;
-    }
-    if (token.name === "help") {
-      options.help = true;
-      return options;
-    }
-    if (token.name === "repo") {
-      options.repo = requireTokenValue(token, parseError).trim();
-      continue;
-    }
-    if (token.name === "auto-resume") {
-      options.autoResume = true;
-      continue;
-    }
-    if (token.name === "cycle-only") {
-      options.cycleOnly = true;
-      continue;
-    }
-    if (token.name === "monitor-only") {
-      options.monitorOnly = true;
-      continue;
-    }
-    if (token.name === "require-retrospective") {
-      options.requireRetrospective = true;
-      continue;
-    }
-    throw parseError(`Unknown argument: ${token.rawName}`);
-  }
-  if (options.repo === undefined) {
-    throw parseError("conductor requires --repo <owner/name>");
-  }
-  if (options.cycleOnly && options.monitorOnly) {
-    throw parseError("--cycle-only and --monitor-only are mutually exclusive");
-  }
-  try {
-    parseRepoSlug(options.repo);
-  } catch (error) {
-    throw parseError(error instanceof Error ? error.message : String(error));
-  }
-  return options;
-}
-export async function runConductor(options, runtime = {}) {
-  const { cycleOnly = false, monitorOnly = false, autoResume = false, requireRetrospective: forceRetrospective = false } = options;
-  const cwd = runtime.repoRoot || process.cwd();
-  const loadConfig = runtime.loadConfigImpl || loadDevLoopConfig;
-  let configLoadResult;
-  let requireRetrospective = false;
-  let autonomyStopAt = ["merge"];
-  let gateConfig = { draft: { requireCi: true }, preApproval: { requireCi: true } };
-  try {
-    configLoadResult = await loadConfig({ repoRoot: cwd });
-    const hasErrors = Array.isArray(configLoadResult.errors) && configLoadResult.errors.length > 0;
-    if (hasErrors) {
-      configLoadResult = { ...configLoadResult };
-    } else {
-      const cfg = configLoadResult.config ?? {};
-      requireRetrospective = resolveWorkflowConfig(cfg, "requireRetrospective");
-      autonomyStopAt = resolveAutonomyStopAt(cfg);
-      const draftCfg = resolveGateConfig(cfg, "draft");
-      const preApprovalCfg = resolveGateConfig(cfg, "preApproval");
-      gateConfig = {
-        draft: { requireCi: draftCfg.requireCi },
-        preApproval: { requireCi: preApprovalCfg.requireCi },
-      };
-    }
-  } catch (error) {
-    const errorMessage = error instanceof Error ? error.message : String(error);
-    configLoadResult = { config: null, warnings: [], errors: [{ path: "<config>", message: `Failed to load config: ${errorMessage}`, layer: "merged" }] };
-  }
-  const effectiveRequireRetrospective = forceRetrospective || requireRetrospective;
-  const retroGate = checkRetrospectiveGate(cwd, effectiveRequireRetrospective);
-  if (retroGate.blocked) {
-    return {
-      ok: false,
-      error: retroGate.reason,
-      repo: options.repo,
-      blockedByRetrospective: true,
-      checkedAt: new Date().toISOString(),
-    };
-  }
-  const runCycle = !monitorOnly;
-  const runMonitor = !cycleOnly;
-  const cycleResult = runCycle
-    ? await runConductorCycle({ repo: options.repo, autonomyStopAt, gateConfig }, runtime).catch((error) => ({
-        ok: false,
-        error: error instanceof Error ? error.message : String(error),
-      }))
-    : null;
-  const monitorResult = runMonitor
-    ? await runConductorMonitor({ repo: options.repo, autoResume }, runtime).catch((error) => ({
-        ok: false,
-        error: error instanceof Error ? error.message : String(error),
-      }))
-    : null;
-  const cycleOk = cycleResult?.ok === true;
-  const monitorOk = monitorResult?.ok === true;
-  return {
-    ok: (runCycle ? cycleOk : true) && (runMonitor ? monitorOk : true),
-    repo: options.repo,
-    checkedAt: new Date().toISOString(),
-    cycle: cycleResult ?? null,
-    monitor: monitorResult ?? null,
-    cycleOk,
-    monitorOk,
-    config: {
-      requireRetrospective: effectiveRequireRetrospective,
-      configRequireRetrospective: requireRetrospective,
-      autonomyStopAt,
-      gateConfig,
-      configErrors: configLoadResult?.errors?.length ?? 0,
-    },
-    summary: {
-      totalPrs: (cycleResult?.prCount ?? 0) || (monitorResult?.prCount ?? 0),
-      cycleActions: cycleResult?.actions?.length ?? 0,
-      needsSubagent: cycleResult?.summary?.needsSubagent ?? 0,
-      readyToMerge: cycleResult?.summary?.readyToMerge ?? 0,
-      waiting: cycleResult?.summary?.waiting ?? 0,
-      blocked: cycleResult?.summary?.blocked ?? 0,
-      done: cycleResult?.summary?.done ?? 0,
-      errors: cycleResult?.summary?.errors ?? 0,
-      queueStatus: monitorResult?.queueStatus ?? "unknown",
-      needsAttentionCount: monitorResult?.needsAttentionCount ?? 0,
-      orphanedPrCount: monitorResult?.orphanedPrCount ?? 0,
-      resumePlanCount: monitorResult?.resumePlanCount ?? 0,
-      manualAttentionCount: monitorResult?.manualAttentionCount ?? 0,
-    },
-  };
-}
-export async function runCli(
-  argv = process.argv.slice(2),
-  {
-    stdout = process.stdout,
-    env = process.env,
-    ghCommand = "gh",
-    cwd = process.cwd(),
-  } = {},
-) {
-  const options = parseCliArgs(argv);
-  if (options.help) {
-    stdout.write(`${USAGE}\n`);
-    return;
-  }
-  const result = await runConductor(options, {
-    env,
-    ghCommand,
-    repoRoot: cwd,
-  });
-  if (result.ok === false) {
-    process.stderr.write(`${JSON.stringify(result)}\n`);
-    process.exitCode = 1;
-    return;
-  }
-  stdout.write(`${JSON.stringify(result)}\n`);
-}
-if (isDirectCliRun(import.meta.url)) {
-  runCli().catch((error) => {
-    process.stderr.write(`${formatCliError(error)}\n`);
-    process.exitCode = 1;
-  });
-}

package/scripts/loop/detect-stale-runner.mjs

@@ -1,265 +0,0 @@
-#!/usr/bin/env node
-import process from "node:process";
-import { buildParseError, formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
-import { parsePrNumber, requireTokenValue } from "../_cli-primitives.mjs";
-import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
-import { resolveRunId as resolveEnvRunId } from "@dev-loops/core/loop/run-context";
-import { parseArgs } from "node:util";
-import {
-  detectStaleRunner,
-  STALE_RUNNER_ERROR,
-} from "./_stale-runner-detection.mjs";
-const USAGE = `Usage: detect-stale-runner.mjs --repo <owner/name> --pr <number>
-Detect whether the active runner for a PR is stale or has received an exit
-signal. Fails closed with status "stale_runner" or "exit_signal_recorded" so
-the pre-merge guard can refuse to proceed.
-Required:
-  --repo <owner/name>   Repository slug (e.g. owner/repo)
-  --pr <number>         Pull request number
-Optional:
-  --stale-runner-max-age-ms <ms>
-                        Override the staleness threshold (default 30 minutes,
-                        or $DEVLOOPS_STALE_RUNNER_MAX_AGE_MS).
-  --run-id <id>         Override the active run id (default: read from
-                        DEVLOOPS_RUN_ID). When supplied, the detector additionally
-                        verifies the current run id is still the active owner.
-Output (stdout, JSON; always includes staleRunnerCheck):
-  {
-    "ok": true,
-    "repo": "owner/repo",
-    "pr": 17,
-    "status": "fresh_runner",
-    "activeRun": { "runId": "...", "claimedAt": "...", "updatedAt": "..." },
-    "staleRunnerCheck": {
-      "ok": true,
-      "failures": []
-    }
-  }
-  or on failure:
-  {
-    "ok": false,
-    "error": "stale_runner" | "exit_signal_recorded",
-    "message": "...",
-    "staleRunnerCheck": {
-      "ok": false,
-      "failures": ["stale runner: run X claimed N ms ago, last updated M ms ago (max age K ms)"]
-    }
-  }
-Exit codes:
-  0  Success / fresh runner / no owner record
-  1  Argument error or stale/exit-signal condition detected`.trim();
-const parseError = buildParseError(USAGE);
-function parseCliArgs(argv) {
-  const options = {
-    help: false,
-    repo: undefined,
-    pr: undefined,
-    staleRunnerMaxAgeMs: undefined,
-    runId: undefined,
-  };
-  const { tokens } = parseArgs({
-    args: [...argv],
-    options: {
-      help: { type: "boolean", short: "h" },
-      repo: { type: "string" },
-      pr: { type: "string" },
-      "stale-runner-max-age-ms": { type: "string" },
-      "run-id": { type: "string" },
-    },
-    allowPositionals: true,
-    strict: false,
-    tokens: true,
-  });
-  for (const token of tokens) {
-    if (token.kind === "positional") {
-      throw parseError(`Unknown argument: ${token.value}`);
-    }
-    if (token.kind !== "option") {
-      continue;
-    }
-    if (token.name === "help") {
-      options.help = true;
-      return options;
-    }
-    if (token.name === "repo") {
-      options.repo = requireTokenValue(token, parseError).trim();
-      continue;
-    }
-    if (token.name === "pr") {
-      options.pr = parsePrNumber(requireTokenValue(token, parseError), parseError);
-      continue;
-    }
-    if (token.name === "stale-runner-max-age-ms") {
-      const raw = requireTokenValue(token, parseError).trim();
-      const parsed = Number(raw);
-      if (!Number.isFinite(parsed) || parsed <= 0) {
-        throw parseError(`--stale-runner-max-age-ms must be a positive integer (ms), got: ${raw}`);
-      }
-      options.staleRunnerMaxAgeMs = Math.floor(parsed);
-      continue;
-    }
-    if (token.name === "run-id") {
-      options.runId = requireTokenValue(token, parseError).trim();
-      continue;
-    }
-    throw parseError(`Unknown argument: ${token.rawName}`);
-  }
-  if (options.repo === undefined || options.pr === undefined) {
-    throw parseError("detect-stale-runner requires both --repo <owner/name> and --pr <number>");
-  }
-  try {
-    parseRepoSlug(options.repo);
-  } catch (error) {
-    throw parseError(error instanceof Error ? error.message : String(error));
-  }
-  return options;
-}
-function resolveRunId(explicitRunId, env) {
-  if (typeof explicitRunId === "string" && explicitRunId.trim().length > 0) {
-    return explicitRunId.trim();
-  }
-  return resolveEnvRunId(env);
-}
-function buildStaleRunnerCheck(detection) {
-  if (detection.status === "no_owner_record") {
-    return {
-      ok: true,
-      failures: [],
-    };
-  }
-  if (detection.status === "exit_signal_recorded") {
-    return {
-      ok: false,
-      failures: [`exit signal recorded for run ${detection.activeRun?.runId ?? "unknown"}: refuse to merge`],
-    };
-  }
-  if (detection.status === "stale_runner") {
-    return {
-      ok: false,
-      failures: [
-        `stale runner: run ${detection.staleRunner.runId} claimed ${detection.staleRunner.claimedAgeMs}ms ago, last updated ${detection.staleRunner.updatedAgeMs}ms ago (max age ${detection.staleRunner.maxAgeMs}ms)`,
-      ],
-    };
-  }
-  return { ok: true, failures: [] };
-}
-export async function runDetectStaleRunner(options, { env = process.env, cwd = process.cwd() } = {}) {
-  const detection = await detectStaleRunner({
-    repo: options.repo,
-    pr: options.pr,
-    maxAgeMs: options.staleRunnerMaxAgeMs,
-    cwd,
-  });
-  const explicitRunId = resolveRunId(options.runId, env);
-  const ownershipLost = explicitRunId !== null
-    && detection.activeRun !== null
-    && detection.activeRun.runId !== explicitRunId;
-  const ownershipMissing = explicitRunId !== null && detection.activeRun === null;
-  const staleRunnerCheck = buildStaleRunnerCheck(detection);
-  if (ownershipMissing) {
-    return {
-      ok: false,
-      error: "ownership_lost",
-      repo: options.repo.trim().toLowerCase(),
-      pr: options.pr,
-      status: "ownership_lost",
-      activeRun: null,
-      runId: explicitRunId,
-      exitSignals: [],
-      filePath: detection.filePath,
-      maxAgeMs: detection.maxAgeMs,
-      message: `Stale-runner check: run ${explicitRunId} is no longer the active owner of ${options.repo}#${options.pr}; no active owner record exists.`,
-      staleRunnerCheck: {
-        ok: false,
-        failures: [`ownership_lost: no active owner record exists; run ${explicitRunId} is not the owner`],
-      },
-    };
-  }
-  if (ownershipLost) {
-    return {
-      ok: false,
-      error: "ownership_lost",
-      repo: options.repo.trim().toLowerCase(),
-      pr: options.pr,
-      status: "ownership_lost",
-      activeRun: detection.activeRun,
-      runId: explicitRunId,
-      exitSignals: detection.exitSignal?.signals ?? [],
-      filePath: detection.filePath,
-      maxAgeMs: detection.maxAgeMs,
-      message: `Stale-runner check: run ${explicitRunId} is no longer the active owner of ${options.repo}#${options.pr}; current owner is ${detection.activeRun?.runId}.`,
-      staleRunnerCheck: {
-        ok: false,
-        failures: [`ownership_lost: active owner is ${detection.activeRun?.runId ?? "unknown"}, not ${explicitRunId}`],
-      },
-    };
-  }
-  if (detection.status === "exit_signal_recorded") {
-    return {
-      ok: false,
-      error: STALE_RUNNER_ERROR.EXIT_SIGNAL_RECORDED,
-      repo: options.repo.trim().toLowerCase(),
-      pr: options.pr,
-      status: "exit_signal_recorded",
-      activeRun: detection.activeRun,
-      runId: explicitRunId,
-      exitSignals: detection.exitSignal?.signals ?? [],
-      filePath: detection.filePath,
-      maxAgeMs: detection.maxAgeMs,
-      message: detection.message,
-      staleRunnerCheck,
-    };
-  }
-  if (detection.status === "stale_runner") {
-    return {
-      ok: false,
-      error: STALE_RUNNER_ERROR.STALE_RUNNER,
-      repo: options.repo.trim().toLowerCase(),
-      pr: options.pr,
-      status: "stale_runner",
-      activeRun: detection.activeRun,
-      runId: explicitRunId,
-      exitSignals: [],
-      staleRunner: detection.staleRunner,
-      filePath: detection.filePath,
-      maxAgeMs: detection.maxAgeMs,
-      message: detection.message,
-      staleRunnerCheck,
-    };
-  }
-  return {
-    ok: true,
-    repo: options.repo.trim().toLowerCase(),
-    pr: options.pr,
-    status: detection.status,
-    activeRun: detection.activeRun,
-    runId: explicitRunId,
-    exitSignals: [],
-    filePath: detection.filePath,
-    maxAgeMs: detection.maxAgeMs,
-    staleRunnerCheck,
-  };
-}
-async function main() {
-  try {
-    const options = parseCliArgs(process.argv.slice(2));
-    if (options.help) {
-      console.log(USAGE);
-      return;
-    }
-    const result = await runDetectStaleRunner(options, { env: process.env });
-    if (!result.ok) {
-      console.error(JSON.stringify(result));
-      process.exitCode = 1;
-      return;
-    }
-    console.log(JSON.stringify(result));
-  } catch (error) {
-    const payload = formatCliError(error, { usage: USAGE });
-    console.error(JSON.stringify(payload));
-    process.exitCode = 1;
-  }
-}
-if (isDirectCliRun(import.meta.url)) {
-  await main();
-}