@ai-dossier/cli 0.13.0 → 0.18.0

package/dist/commands/runstate.js

@@ -12,211 +12,15 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerRunstateCommand = registerRunstateCommand;
-const node_child_process_1 = require("node:child_process");
 const node_fs_1 = __importDefault(require("node:fs"));
 const duration_1 = require("../duration");
+const gh_1 = require("../gh");
 const issue_selection_1 = require("../issue-selection");
 const runstate_1 = require("../runstate");
 const runstate_stats_1 = require("../runstate-stats");
 const table_1 = require("../table");
-/**
- * Fail on stderr and exit 1, so a calling dossier can detect it.
- *
- * Each entry is one problem. An entry may span lines: the first gets the ❌, the rest are
- * indented under it, which is how a cause line and its "Fix:" line stay visibly one item.
- */
-function fail(lines) {
-    for (const line of lines) {
-        const [first, ...rest] = line.split('\n');
-        console.error(`❌ ${first}`);
-        for (const cont of rest)
-            console.error(`   ${cont}`);
-    }
-    process.exit(1);
-}
-/**
- * Run a command, keeping WHY it failed.
- *
- * The whole point of this subcommand is that agents were silently getting things wrong,
- * so a discarded stderr is the one thing we cannot afford: "gh is not installed", "gh is
- * not logged in", and "issue 440 does not exist" need three different fixes and are
- * indistinguishable without it.
- */
-function exec(file, args) {
-    try {
-        const stdout = (0, node_child_process_1.execFileSync)(file, args, {
-            encoding: 'utf8',
-            stdio: ['ignore', 'pipe', 'pipe'],
-        });
-        return { ok: true, stdout: String(stdout).trim() };
-    }
-    catch (err) {
-        const e = err;
-        const stderr = String(e?.stderr ?? '').trim() || String(e?.message ?? '').trim();
-        return {
-            ok: false,
-            error: {
-                notFound: e?.code === 'ENOENT',
-                status: typeof e?.status === 'number' ? e.status : null,
-                stderr,
-            },
-        };
-    }
-}
-/** Characters of command output kept in a top-level failure message. */
-const SNIPPET_LENGTH = 300;
 /** Characters kept in a `verify` warning, which is one line among several. */
 const WARNING_SNIPPET_LENGTH = 120;
-/** Collapse output to one bounded line so a huge or binary payload stays readable. */
-function snippet(text, max = SNIPPET_LENGTH) {
-    const oneLine = text.replace(/\s+/g, ' ').trim();
-    if (oneLine === '')
-        return '(no output)';
-    return oneLine.length > max
-        ? `${oneLine.slice(0, max)}… (${oneLine.length} characters total)`
-        : oneLine;
-}
-const GH_FAILURE_CASES = [
-    {
-        match: [
-            'gh auth login',
-            'not logged',
-            'authentication',
-            'unauthorized',
-            'http 401',
-            'bad credentials',
-        ],
-        cause: () => 'gh is not authenticated.',
-        fix: `Fix: run 'gh auth login', confirm with 'gh auth status', then re-run.`,
-    },
-    {
-        match: ['could not resolve to', 'not found', 'http 404'],
-        cause: (where) => `GitHub could not find it in ${where}.`,
-        fix: `Fix: check the number is right and that the repository is the one you mean — pass --repo <owner/name> when running outside it.`,
-    },
-    {
-        // Ahead of the 403 case on purpose: gh reports rate limiting AS an HTTP 403, so without
-        // this the operator is told to fix their permissions — which are fine. `stats --issues`
-        // can fire up to 200 sequential reads, which makes this a realistic failure.
-        match: ['rate limit', 'secondary rate', 'abuse detection', 'http 429'],
-        cause: () => 'GitHub rate-limited the request.',
-        fix: `Fix: wait for the window to reset ('gh api rate_limit' shows when), then re-run; narrow --issues to read fewer issues per run.`,
-    },
-    {
-        match: ['http 403', 'permission', 'write access', 'forbidden'],
-        cause: (where) => `GitHub refused the request — the authenticated account lacks access to ${where}.`,
-        fix: `Fix: check the account and its scopes with 'gh auth status'; reading an issue needs read access to the repository, and posting a milestone needs write.`,
-    },
-    {
-        match: ['dial tcp', 'no such host', 'timeout', 'connection refused', 'network is unreachable'],
-        cause: () => 'gh could not reach GitHub.',
-        fix: `Fix: check network/proxy access to github.com and re-run; this is transient, so a retry is usually enough.`,
-    },
-];
-/**
- * `JSON.parse` for a `gh --json` payload: `null` instead of a throw, and the caller's
- * declared shape instead of `any`. Every gh call here reads a `--json` payload, so all
- * three call sites need the same "gh exited 0 but printed something that is not JSON"
- * branch — they differ only in what they say about it. Fields stay `unknown` because gh's
- * output is remote data — {@link asString} narrows each one at the point of use.
- */
-function parseGhJson(raw) {
-    try {
-        return JSON.parse(raw);
-    }
-    catch {
-        return null;
-    }
-}
-/** A JSON field as a string, or `fallback` when gh omitted it or sent another type. */
-function asString(value, fallback = '') {
-    return typeof value === 'string' ? value : fallback;
-}
-/**
- * Turn a failed `gh` invocation into a message that names the cause and the fix.
- *
- * `action` is what we were trying to do, e.g. "Could not read issue #440".
- */
-function ghFailure(action, err, repo) {
-    if (err.notFound) {
-        return [
-            `${action}: 'gh' is not installed, or is not on PATH.`,
-            `Fix: install the GitHub CLI (https://cli.github.com), then re-run. Check with: gh --version`,
-        ].join('\n');
-    }
-    const hint = err.stderr.toLowerCase();
-    const where = repo ? `--repo ${repo}` : 'the current repository (no --repo was passed)';
-    const matched = GH_FAILURE_CASES.find((c) => c.match.some((needle) => hint.includes(needle)));
-    const cause = matched
-        ? `${action}: ${matched.cause(where)}`
-        : `${action}: gh exited ${err.status === null ? 'abnormally' : `with status ${err.status}`}.`;
-    const fix = matched?.fix ?? `Fix: run the same gh command by hand to see the full error.`;
-    return [cause, fix, `gh said: ${snippet(err.stderr)}`].join('\n');
-}
-/** Reject a non-numeric `--issue` here rather than letting gh (or `mint`) fail obscurely. */
-function requireIssueNumber(issue) {
-    if (!(0, runstate_1.isIssueNumber)(issue)) {
-        fail([
-            `Invalid --issue '${issue}' — expected a positive GitHub issue number.\nFix: pass the number only, e.g. --issue 440 (not a URL, a '#', or a branch name).`,
-        ]);
-    }
-}
-/**
- * The `--issue`/`--repo` checks every issue-targeting subcommand runs before it starts.
- * Kept together so a new subcommand cannot pick up one guard and miss the other.
- */
-function requireIssueTarget(options) {
-    requireIssueNumber(options.issue);
-    requireRepoSlug(options.repo);
-}
-/** `--repo owner/name` appended to a gh invocation when the caller supplied one. */
-function repoArgs(repo) {
-    return repo ? ['--repo', repo] : [];
-}
-/** `owner/name`, or `host/owner/name` for a GitHub Enterprise host. */
-const REPO_SLUG_RE = /^(?:[A-Za-z0-9][A-Za-z0-9.-]*\/)?[A-Za-z0-9][A-Za-z0-9._-]*\/[A-Za-z0-9][A-Za-z0-9._-]*$/;
-/** Reject a `--repo` that is not a repository slug before handing it to gh. */
-function requireRepoSlug(repo) {
-    if (repo === undefined)
-        return;
-    if (!REPO_SLUG_RE.test(repo)) {
-        fail([
-            `Invalid --repo '${repo}' — expected owner/name.\nFix: pass the slug only, e.g. --repo imboard-ai/ai-dossier (not a URL, and not a shell expansion).`,
-        ]);
-    }
-}
-/** Whether `value` carries a control character, which has no place in a milestone value. */
-function hasControlChar(value) {
-    for (let i = 0; i < value.length; i += 1) {
-        const code = value.charCodeAt(i);
-        if (code < 0x20 || code === 0x7f)
-            return true;
-    }
-    return false;
-}
-/**
- * Whether a value read back OUT of a milestone comment may be passed to `git`/`gh`.
- *
- * These values are attacker-reachable: anyone who can comment on the issue can post a
- * `<!-- runstate:v1 -->` body, so `branch=`, `worktree=` and `pr=` arrive from the network
- * rather than from the caller. Every invocation here is `execFileSync` with an argument
- * array and no shell, so there is no command injection — but a value that begins with `-`
- * is still read as a FLAG rather than as data. `gh` (cobra) parses flags interspersed with
- * positionals, so `pr=--repo=someone/else` or `pr=--web` would silently retarget, or add a
- * side effect to, a subcommand documented as strictly read-only.
- */
-function isSafeArg(value) {
-    return value !== '' && !value.startsWith('-') && !/\s/.test(value) && !hasControlChar(value);
-}
-/**
- * Paths are only ever passed in value position (`git -C <path>`) or to `fs.statSync`, so
- * they cannot be mistaken for a flag — but the protocol requires them absolute, and a
- * relative path from a forged comment would resolve against whatever directory the agent
- * happens to be in.
- */
-function isSafePath(value) {
-    return value.startsWith('/') && !hasControlChar(value);
-}
 /** Parse `--kv k=v` occurrences into ordered pairs. */
 function parseKvPairs(raw) {
     const pairs = [];
@@ -240,43 +44,17 @@ function parseKvPairs(raw) {
  * reports it.
  */
 function tryFetchMilestones(issue, repo) {
-    const res = exec('gh', ['issue', 'view', issue, '--json', 'comments', ...repoArgs(repo)]);
-    if (!res.ok) {
-        return { ok: false, error: ghFailure(`Could not read issue #${issue}`, res.error, repo) };
-    }
-    const parsed = parseGhJson(res.stdout);
-    if (parsed === null) {
-        return {
-            ok: false,
-            error: [
-                `Could not read issue #${issue}: gh exited 0 but did not print JSON.`,
-                `Expected a {"comments":[…]} object from: gh issue view ${issue} --json comments${repo ? ` --repo ${repo}` : ''}`,
-                `Fix: run that command by hand — a gh older than 2.0 (no --json), or an interactive prompt landing on stdout, both look like this.`,
-                `gh printed: ${snippet(res.stdout)}`,
-            ].join('\n'),
-        };
-    }
-    // A milestone-less issue and a shape we cannot read must not look the same: the first
-    // means "fresh run", the second means the tool is broken, and silently returning [] for
-    // both would make a resume start over and destroy work.
-    if (!Array.isArray(parsed?.comments)) {
-        return {
-            ok: false,
-            error: [
-                `Could not read issue #${issue}: gh's JSON has no "comments" array.`,
-                `Fix: confirm your gh supports 'gh issue view <n> --json comments' (gh --version); if it does, re-run — this is not an issue with no comments, it is an unreadable response.`,
-                `gh printed: ${snippet(res.stdout)}`,
-            ].join('\n'),
-        };
-    }
-    const bodies = parsed.comments.map((c) => typeof c?.body === 'string' ? c.body : '');
+    const result = (0, gh_1.tryFetchComments)(issue, repo);
+    if (!result.ok)
+        return { ok: false, error: result.error };
+    const bodies = result.comments.map((c) => (typeof c?.body === 'string' ? c.body : ''));
     return { ok: true, milestones: (0, runstate_1.parseMilestones)(bodies) };
 }
 /** Fetch every runstate milestone on an issue, oldest first, or exit 1 explaining why. */
 function fetchMilestones(issue, repo) {
     const result = tryFetchMilestones(issue, repo);
     if (!result.ok)
-        fail([result.error]);
+        (0, gh_1.fail)([result.error]);
     return result.milestones;
 }
 /** `git ls-remote --exit-code` exits 2 for "no such ref" — an answer, not a fault. */
@@ -298,18 +76,18 @@ const RUN_INCOMPLETE = 'treating the run as not yet complete';
  * instead).
  */
 function probeFailure(tool, subject, err, consequence) {
-    return `could not ${subject} (${tool} exited ${err.status ?? 'abnormally'}: ${snippet(err.stderr, WARNING_SNIPPET_LENGTH)}) — ${consequence}`;
+    return `could not ${subject} (${tool} exited ${err.status ?? 'abnormally'}: ${(0, gh_1.snippet)(err.stderr, WARNING_SNIPPET_LENGTH)}) — ${consequence}`;
 }
 /** The warning for a gh call that exited 0 but did not print JSON. */
 function nonJsonFailure(subject, stdout, consequence) {
-    return `gh returned non-JSON for ${subject} (${snippet(stdout, WARNING_SNIPPET_LENGTH)}) — ${consequence}`;
+    return `gh returned non-JSON for ${subject} (${(0, gh_1.snippet)(stdout, WARNING_SNIPPET_LENGTH)}) — ${consequence}`;
 }
 function probeBranchOnRemote(branch, warn) {
-    if (!isSafeArg(branch)) {
+    if (!(0, gh_1.isSafeArg)(branch)) {
         warn(`milestone branch '${branch}' is not a usable branch name — refusing to pass it to git, and ${TREATED_MISSING}`);
         return false;
     }
-    const res = exec('git', ['ls-remote', '--exit-code', 'origin', branch]);
+    const res = (0, gh_1.exec)('git', ['ls-remote', '--exit-code', 'origin', branch]);
     if (res.ok)
         return true;
     if (res.error.notFound) {
@@ -326,7 +104,7 @@ function probeBranchOnRemote(branch, warn) {
  * path came from (`label`) and the kind of entry they expect.
  */
 function probePathExists(path, label, kind, warn) {
-    if (!isSafePath(path)) {
+    if (!(0, gh_1.isSafePath)(path)) {
         warn(`milestone ${label} '${path}' is not an absolute path — ${TREATED_MISSING}`);
         return false;
     }
@@ -339,11 +117,11 @@ function probePathExists(path, label, kind, warn) {
     }
 }
 function probeHeadOf(worktree, warn) {
-    if (!isSafePath(worktree)) {
+    if (!(0, gh_1.isSafePath)(worktree)) {
         warn(`milestone worktree '${worktree}' is not an absolute path — refusing to run git in it, and ${IMPLEMENT_UNVERIFIED}`);
         return null;
     }
-    const res = exec('git', ['-C', worktree, 'rev-parse', '--short', 'HEAD']);
+    const res = (0, gh_1.exec)('git', ['-C', worktree, 'rev-parse', '--short', 'HEAD']);
     if (res.ok)
         return res.stdout;
     // The worktree directory already passed dirExists, so a failure here is surprising.
@@ -351,45 +129,45 @@ function probeHeadOf(worktree, warn) {
     return null;
 }
 function probePrState(pr, repo, warn) {
-    if (!isSafeArg(pr)) {
+    if (!(0, gh_1.isSafeArg)(pr)) {
         warn(`milestone pr '${pr}' is not a usable PR reference — refusing to pass it to gh, and ${SHIP_UNVERIFIED}`);
         return null;
     }
-    const res = exec('gh', [
+    const res = (0, gh_1.exec)('gh', [
         'pr',
         'view',
         pr,
         '--json',
         'state,mergedAt,mergeable',
-        ...repoArgs(repo),
+        ...(0, gh_1.repoArgs)(repo),
     ]);
     if (!res.ok) {
         warn(probeFailure('gh', `read PR ${pr}`, res.error, SHIP_UNVERIFIED));
         return null;
     }
-    const data = parseGhJson(res.stdout);
+    const data = (0, gh_1.parseGhJson)(res.stdout);
     if (data === null) {
         warn(nonJsonFailure(`PR ${pr}`, res.stdout, SHIP_UNVERIFIED));
         return null;
     }
     return {
-        state: asString(data.state),
+        state: (0, gh_1.asString)(data.state),
         mergedAt: typeof data.mergedAt === 'string' ? data.mergedAt : null,
-        mergeable: asString(data.mergeable),
+        mergeable: (0, gh_1.asString)(data.mergeable),
     };
 }
 function probeIssueClosed(issue, repo, warn) {
-    const res = exec('gh', ['issue', 'view', issue, '--json', 'state', ...repoArgs(repo)]);
+    const res = (0, gh_1.exec)('gh', ['issue', 'view', issue, '--json', 'state', ...(0, gh_1.repoArgs)(repo)]);
     if (!res.ok) {
         warn(probeFailure('gh', `read the state of issue #${issue}`, res.error, RUN_INCOMPLETE));
         return false;
     }
-    const data = parseGhJson(res.stdout);
+    const data = (0, gh_1.parseGhJson)(res.stdout);
     if (data === null) {
         warn(nonJsonFailure(`the state of issue #${issue}`, res.stdout, RUN_INCOMPLETE));
         return false;
     }
-    return asString(data.state) === GH_STATE_CLOSED;
+    return (0, gh_1.asString)(data.state) === GH_STATE_CLOSED;
 }
 /**
  * The real-world probe backing `runstate verify`. All reads — never needs push access.
@@ -412,39 +190,21 @@ function makeProbe(issue, repo, warnings = []) {
         issueClosed: () => probeIssueClosed(issue, repo, warn),
     };
 }
-/** `--dry-run`: show the exact body that would have been posted, and post nothing. */
-function printDryRun(body, json) {
-    if (json) {
-        console.log(JSON.stringify({ posted: false, dryRun: true, body }, null, 2));
-    }
-    else {
-        process.stdout.write(body);
-    }
-}
-/** Comment the built body onto the issue and report where it landed. */
+/** `--dry-run` and posting are shared with the plan protocol — see `../gh`. */
+/** Comment the built milestone body onto the issue and report where it landed. */
 function postMilestone(body, options) {
-    const res = exec('gh', [
-        'issue',
-        'comment',
-        options.issue,
-        '--body',
+    (0, gh_1.postIssueComment)({
+        issue: options.issue,
+        repo: options.repo,
         body,
-        ...repoArgs(options.repo),
-    ]);
-    if (!res.ok) {
-        fail([
-            ghFailure(`Failed to post the ${options.phase}/${options.status} milestone to issue #${options.issue}`, res.error, options.repo),
-            // The milestone is the only durable record of the phase, so hand back the body it
-            // could not post: re-running the phase is far more expensive than a retry.
-            `The milestone was NOT posted. Retry, or post it by hand:\ngh issue comment ${options.issue}${options.repo ? ` --repo ${options.repo}` : ''} --body ${JSON.stringify(body)}`,
-        ]);
-    }
-    if (options.json) {
-        console.log(JSON.stringify({ posted: true, url: res.stdout, body }, null, 2));
-    }
-    else {
-        console.log(`✅ ${options.phase} ${options.status} → ${res.stdout}`);
-    }
+        noun: 'milestone',
+        action: `Failed to post the ${options.phase}/${options.status} milestone to issue #${options.issue}`,
+        json: options.json,
+        // The milestone is the only durable record of the phase, so the body is handed back
+        // in the JSON result: re-running the phase is far more expensive than a retry.
+        jsonExtras: { body },
+        successLine: (url) => `✅ ${options.phase} ${options.status} → ${url}`,
+    });
 }
 /**
  * `post` refuses an over-long body itself: GitHub answers a too-large comment with an
@@ -455,7 +215,7 @@ function requirePostableBody(body, pairs) {
     if (body.length <= runstate_1.MAX_BODY_LENGTH)
         return;
     const biggest = [...pairs].sort((a, b) => b[1].length - a[1].length)[0];
-    fail([
+    (0, gh_1.fail)([
         [
             `Milestone is ${body.length} characters — GitHub rejects an issue comment over ${runstate_1.MAX_BODY_LENGTH}.`,
             biggest
@@ -471,16 +231,16 @@ function registerPostSubcommand(cmd) {
         .command('post')
         .description('Build and post a runstate milestone comment (validates before posting)')
         .requiredOption('--issue <number>', 'GitHub issue number')
-        .requiredOption('--phase <phase>', 'gate, setup, plan, implement, review, ship, or report')
+        .requiredOption('--phase <phase>', `classify, ${[...runstate_1.PHASES].join(', ')}, or a batch phase (${runstate_1.BATCH_PHASES.join(', ')})`)
         .requiredOption('--status <status>', 'done, partial, blocked, or awaiting-merge')
-        .requiredOption('--run <id>', 'Run id minted by the gate phase (r-<issue>-<hex>)')
+        .requiredOption('--run <id>', 'Run id (r-<issue>-<hex>) — mint one with: runstate mint; full-cycle runs mint it at the gate phase')
         .option('--kv <key=value...>', 'Phase-specific key=value pair (repeatable)')
         .option('--next <phase>', 'Override the computed next= value')
         .option('--repo <owner/name>', 'Target repository (defaults to the current one)')
         .option('--dry-run', 'Print the comment body without posting it')
         .option('--json', 'Output the result as JSON')
         .action((options) => {
-        requireIssueTarget(options);
+        (0, gh_1.requireIssueTarget)(options);
         const { pairs, errors: kvErrors } = parseKvPairs(options.kv ?? []);
         const input = {
             phase: options.phase,
@@ -491,11 +251,11 @@ function registerPostSubcommand(cmd) {
         };
         const errors = [...kvErrors, ...(0, runstate_1.validateMilestone)(input)];
         if (errors.length > 0)
-            fail(errors);
+            (0, gh_1.fail)(errors);
         const body = (0, runstate_1.buildMilestone)(input);
         requirePostableBody(body, pairs);
         if (options.dryRun) {
-            printDryRun(body, options.json);
+            (0, gh_1.printDryRun)(body, options.json);
             return;
         }
         postMilestone(body, options);
@@ -510,7 +270,7 @@ function registerLastSubcommand(cmd) {
         .option('--repo <owner/name>', 'Target repository (defaults to the current one)')
         .option('--json', 'Output the parsed milestone as JSON')
         .action((options) => {
-        requireIssueTarget(options);
+        (0, gh_1.requireIssueTarget)(options);
         const milestones = fetchMilestones(options.issue, options.repo);
         if (milestones.length === 0) {
             if (options.json) {
@@ -540,7 +300,7 @@ function registerVerifySubcommand(cmd) {
         .option('--repo <owner/name>', 'Target repository (defaults to the current one)')
         .option('--json', 'Output the result as JSON')
         .action((options) => {
-        requireIssueTarget(options);
+        (0, gh_1.requireIssueTarget)(options);
         const milestones = fetchMilestones(options.issue, options.repo);
         const warnings = [];
         const result = (0, runstate_1.computeResume)(milestones, makeProbe(options.issue, options.repo, warnings));
@@ -550,6 +310,7 @@ function registerVerifySubcommand(cmd) {
                 run_id: result.run_id,
                 verified: result.verified,
                 resume_context: result.resume_context,
+                ...(result.slot_trail ? { slot_trail: true } : {}),
                 ...(result.hard_block ? { hard_block: result.hard_block } : {}),
                 ...(result.note ? { note: result.note } : {}),
                 ...(warnings.length > 0 ? { warnings } : {}),
@@ -559,6 +320,8 @@ function registerVerifySubcommand(cmd) {
             console.log(`resume_from=${result.resume_from}`);
             console.log(`run_id=${result.run_id ?? 'none'}`);
             console.log(`verified=${result.verified.length > 0 ? result.verified.join(',') : 'none'}`);
+            if (result.slot_trail)
+                console.log('slot_trail=present');
             if (result.hard_block)
                 console.log(`hard_block=${result.hard_block}`);
             if (result.note)
@@ -583,27 +346,27 @@ function registerVerifySubcommand(cmd) {
  */
 function resolveStatsIssues(options) {
     if (options.issue !== undefined && options.issues !== undefined) {
-        fail([
+        (0, gh_1.fail)([
             `Pass --issue or --issues, not both.\nFix: --issue ${options.issue} for one issue, or --issues ${options.issues} for a set.`,
         ]);
     }
     if (options.issue !== undefined) {
-        requireIssueTarget({ issue: options.issue, repo: options.repo });
+        (0, gh_1.requireIssueTarget)({ issue: options.issue, repo: options.repo });
         return [Number(options.issue)];
     }
     if (options.issues === undefined) {
-        fail([
+        (0, gh_1.fail)([
             `Missing --issue or --issues.\nFix: 'runstate stats --issue 451', or a set: 'runstate stats --issues 440,448,451' (ranges too: 440..451).`,
         ]);
     }
-    requireRepoSlug(options.repo);
+    (0, gh_1.requireRepoSlug)(options.repo);
     try {
         return (0, issue_selection_1.parseIssueSelection)(options.issues);
     }
     catch (err) {
         // Selection errors already carry their own `Fix:` line — appending a generic one told
         // the operator to do the very thing that just failed ("pass a range" on a cap error).
-        return fail([err instanceof Error ? err.message : String(err)]);
+        return (0, gh_1.fail)([err instanceof Error ? err.message : String(err)]);
     }
 }
 /** Column layout of the per-run phase table. */
@@ -752,8 +515,9 @@ function readTrails(issues, repo) {
 /**
  * `runstate stats` — per-phase durations derived from a trail's `at=` stamps.
  *
- * Read-only by construction: the only subprocess it can reach is the `gh issue view` inside
- * {@link fetchMilestones}, which is also where the auth/404/network failure taxonomy lives.
+ * Read-only by construction: the only subprocesses it can reach are the `gh issue view`
+ * inside {@link fetchMilestones} and the verify probes, which apply the shared gh/git
+ * failure taxonomy from `src/gh.ts`.
  */
 function registerStatsSubcommand(cmd) {
     cmd
@@ -769,7 +533,7 @@ function registerStatsSubcommand(cmd) {
         // Every issue unreadable is a genuine failure, not a degraded read — there is no
         // report to hand back, so say why rather than printing an empty one and exiting 0.
         if (trails.length === 0 && failed.length > 0) {
-            fail(failed.map((f) => f.error));
+            (0, gh_1.fail)(failed.map((f) => f.error));
         }
         const report = (0, runstate_stats_1.buildStatsReport)({ trails, failed, repo: options.repo });
         if (options.json) {
@@ -801,7 +565,7 @@ function registerMintSubcommand(cmd) {
         .action((options) => {
         // Without this, `mint --issue not-a-number` happily prints `r-not-a-number-ab56`
         // and the mistake only surfaces one phase later as "Invalid run id" from `post`.
-        requireIssueNumber(options.issue);
+        (0, gh_1.requireIssueNumber)(options.issue);
         console.log((0, runstate_1.mintRunId)(options.issue));
     });
 }