@rtorcato/repo-tooling 3.42.0 → 3.44.0

package/AGENTS.md

@@ -29,6 +29,8 @@ Every command supports `--json` and a non-interactive mode. Combine with `--yes`
 | `loop guard --root <path>` | ✅ | ✅ | Guard an `ai-issue-loop` tick: repair a wrongly-bare main checkout, gate the `node_modules` rebuild (`--removed`), and assert `gh` authenticates as the declared `rules.aiLoop.agentUser`. Exit `0` continue, `1` repair failed, `2` root is not a repairable checkout or the agent identity is wrong — both non-zero halt the tick. |
 | `loop env` | ✅ | ✅ | Resolve an `ai-issue-loop` tick's variables once: `root` (main checkout, correct from inside a worktree), `worktreeRoot`, `ownerRepo`, `agentUser` (empty unless an assignable collaborator), `humanUser` (empty for org repos), `me`. Without `--json`, prints `KEY='value'` lines for `eval`. Exit `1` when the checkout or its GitHub repo cannot be resolved. |
 | `loop worktree add <ai-N-slug>` | ✅ | ✅ | Create an `ai-issue-loop` worktree at `<root>-worktrees/<slug>` on a new branch off `origin/main` (`--base`), symlink every `worktree.symlinkDirectories` entry from `.claude/settings.json`, and add `node_modules` to `.git/info/exclude`. `needsInstall: true` when no list is declared. Exit `1` when the worktree was not created or an entry is left unlinked — do not spawn an implementer. |
+| `loop reap --json` | ✅ | ✅ | Report the `ai-issue-loop` Pass 2 stalls: a label that sat ≥45 minutes past its last application (per the issue timeline). Each entry is `{ kind, issue, pr, label, minutes, applications, action, worktree, reason }` — `kind` is `implementer` / `reviewer` / `fixer` / `orphan`, `action` is `block` / `drop-label` / `remove-worktree` (`block` once a claim has been applied ≥3 times). Read-only; exit `1` when a `gh` query failed. |
+| `loop comment <pr> --body-file <path>` / `loop verdict <pr> --arm <code\|sec>` | ✅ | ✅ | The loop's hidden-marker protocols. `comment` upserts the one `<!-- ai-issue-loop:decision -->` comment (body from a file or `-` stdin, never argv). `verdict` prints the arm's `PASS` / `PASS-NOTES` / `CHANGES` for the PR's current head, or empty. Both only trust markers posted by `gh`'s own login. Exit `1` when GitHub cannot be read. |
 
 ## Recommended workflows
 
@@ -121,6 +123,8 @@ A fixer may also **refuse** — the target file holds something the generator ca
 - `src/cli/commands/loop-guard.ts` — `loop guard`: the `--is-inside-work-tree` / `.git` invariant table and the `node_modules` rebuild gate, drained out of the ai-issue-loop skill's prose (#519)
 - `src/cli/commands/loop-env.ts` — `loop env`: the skill's Pass 0 variables resolved in one call (#615)
 - `src/cli/commands/loop-worktree.ts` — `loop worktree add`: Pass 4 worktree creation, dependency linking and the missing-link assertion (#616)
+- `src/cli/commands/loop-reap.ts` — `loop reap`: the skill's Pass 2 stalled-agent table as verdicts (#618)
+- `src/cli/commands/loop-marker.ts` — `loop comment` / `loop verdict`: the decision-comment upsert and verdict read-back, with the author and head-commit gates (#619)
 - `src/cli/generators/` — one file per concern (linting, testing, build, git, github-actions, security, misc)
 - `tooling/` — every shipped preset, mirrored 1:1 with `package.json` `exports`
 

package/dist/cli/commands/loop-env.js

@@ -3,7 +3,7 @@ import { LOGIN } from '../../base/agent-user.js';
 import { realGitExec } from '../../base/git-identity.js';
 import { realGhExec } from '../../base/github-settings.js';
 import { configuredAgentUser, defaultWorktreeRoot } from './loop-guard.js';
-async function ghOut(gh, args) {
+export async function ghOut(gh, args) {
     const r = await gh(args);
     return r.ok ? r.stdout.trim() : '';
 }

package/dist/cli/commands/loop-marker.js

@@ -0,0 +1,169 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import { realGhExec } from '../../base/github-settings.js';
+import { ghOut } from './loop-env.js';
+/**
+ * `repo-tooling loop comment` and `loop verdict` — the ai-issue-loop skill's
+ * two hidden-marker protocols, moved out of prose-with-jq (#619):
+ *
+ * - **comment** upserts the one `<!-- ai-issue-loop:decision -->` comment on a
+ *   PR (Pass 1), so a PR left over a weekend gets one edited comment, not one
+ *   per tick.
+ * - **verdict** reads a reviewer arm's `<!-- ai-issue-loop:verdict:… -->`
+ *   marker back off the PR's reviews (Pass 3), so a reviewer that posted and
+ *   died before labelling is adopted rather than re-spawned.
+ *
+ * Both gate on the loop's own login — anyone can comment on or review a public
+ * PR, and a stranger's marker would otherwise own the slot or override a
+ * genuine `CHANGES`. Login, not `author_association`, which wobbles with repo
+ * ownership. Bodies travel to gh as JSON on stdin, never through a shell.
+ */
+export const DECISION_MARKER = '<!-- ai-issue-loop:decision -->';
+async function resolveTarget(dir, gh) {
+    const cwd = path.resolve(dir ?? process.cwd());
+    const exec = gh ?? ((args, stdin) => realGhExec(args, stdin, cwd));
+    const ownerRepo = await ghOut(exec, [
+        'repo',
+        'view',
+        '--json',
+        'nameWithOwner',
+        '--jq',
+        '.nameWithOwner',
+    ]);
+    if (!ownerRepo)
+        return 'could not resolve the GitHub repo from the working directory';
+    const me = await ghOut(exec, ['api', 'user', '--jq', '.login']);
+    if (!me)
+        return 'could not resolve the gh login';
+    return { ownerRepo, me, gh: exec };
+}
+/** The PR number goes into an API path — digits only. */
+function prNumber(pr) {
+    const s = String(pr);
+    return /^[1-9]\d*$/.test(s) ? Number(s) : null;
+}
+/** `--paginate --slurp` yields one array per page; `--jq` would run per page. */
+async function slurp(gh, route) {
+    const r = await gh(['api', route, '--paginate', '--slurp']);
+    if (!r.ok)
+        return null;
+    try {
+        return JSON.parse(r.stdout).flat();
+    }
+    catch {
+        return null;
+    }
+}
+export async function runLoopComment(pr, options) {
+    const n = prNumber(pr);
+    const fail = (error) => ({
+        pr: n,
+        action: 'failed',
+        commentId: null,
+        error,
+    });
+    if (n === null)
+        return fail(`not a PR number: ${pr}`);
+    const text = options.text.trim();
+    if (!text)
+        return fail('empty comment body');
+    const target = await resolveTarget(options.dir, options.gh);
+    if (typeof target === 'string')
+        return fail(target);
+    const { ownerRepo, me, gh } = target;
+    const comments = await slurp(gh, `repos/${ownerRepo}/issues/${n}/comments`);
+    // A failed read must not fall through to "create" — that is the duplicate.
+    if (comments === null)
+        return fail('could not list PR comments');
+    const existing = comments.find((c) => c.user?.login === me && (c.body ?? '').startsWith(DECISION_MARKER));
+    const input = JSON.stringify({ body: `${DECISION_MARKER}\n${text}` });
+    const r = existing
+        ? await gh(['api', '-X', 'PATCH', `repos/${ownerRepo}/issues/comments/${existing.id}`, '--input', '-'], input)
+        : await gh(['api', `repos/${ownerRepo}/issues/${n}/comments`, '--input', '-'], input);
+    if (!r.ok)
+        return fail(r.stderr.trim() || 'gh api failed');
+    let id = existing?.id ?? null;
+    try {
+        id = JSON.parse(r.stdout).id ?? id;
+    }
+    catch { }
+    return { pr: n, action: existing ? 'updated' : 'created', commentId: id };
+}
+export async function runLoopVerdict(pr, options) {
+    const n = prNumber(pr);
+    const { arm } = options;
+    const fail = (error) => ({
+        pr: n,
+        arm,
+        head: null,
+        verdict: null,
+        error,
+    });
+    if (n === null)
+        return fail(`not a PR number: ${pr}`);
+    if (arm !== 'code' && arm !== 'sec')
+        return fail(`--arm must be code or sec, got ${arm}`);
+    const target = await resolveTarget(options.dir, options.gh);
+    if (typeof target === 'string')
+        return fail(target);
+    const { ownerRepo, me, gh } = target;
+    const head = await ghOut(gh, [
+        'pr',
+        'view',
+        String(n),
+        '-R',
+        ownerRepo,
+        '--json',
+        'headRefOid',
+        '--jq',
+        '.headRefOid',
+    ]);
+    if (!head)
+        return fail('could not resolve the PR head commit');
+    // `issues/<N>/comments` would never see these — `gh pr review --comment`
+    // creates a review.
+    const reviews = await slurp(gh, `repos/${ownerRepo}/pulls/${n}/reviews`);
+    if (reviews === null)
+        return { ...fail('could not list PR reviews'), head };
+    const marker = new RegExp(`<!-- ai-issue-loop:verdict:${arm}:(PASS-NOTES|PASS|CHANGES) -->`);
+    let verdict = null;
+    for (const r of reviews) {
+        // The head gate: a verdict expires with the diff it read.
+        if (r.user?.login !== me || r.commit_id !== head)
+            continue;
+        const m = (r.body ?? '').match(marker);
+        if (m)
+            verdict = m[1];
+    }
+    return { pr: n, arm, head, verdict };
+}
+export async function loopCommentCommand(pr, options) {
+    let text;
+    try {
+        text = fs.readFileSync(options.bodyFile === '-' ? 0 : options.bodyFile, 'utf8');
+    }
+    catch (err) {
+        console.error(`✖ cannot read ${options.bodyFile}: ${err.message}`);
+        process.exitCode = 1;
+        return;
+    }
+    const result = await runLoopComment(pr, { dir: options.dir, text });
+    if (options.json)
+        console.log(JSON.stringify(result, null, 2));
+    else if (result.error)
+        console.error(`✖ ${result.error}`);
+    else
+        console.log(`${result.action} comment ${result.commentId} on #${result.pr}`);
+    process.exitCode = result.action === 'failed' ? 1 : 0;
+}
+export async function loopVerdictCommand(pr, options) {
+    const result = await runLoopVerdict(pr, options);
+    if (options.json)
+        console.log(JSON.stringify(result, null, 2));
+    else if (result.error)
+        console.error(`✖ ${result.error}`);
+    // Empty line for "none", so `VERDICT=$(… loop verdict …)` needs no null check.
+    else
+        console.log(result.verdict ?? '');
+    process.exitCode = result.error ? 1 : 0;
+}

package/dist/cli/commands/loop-reap.js

@@ -0,0 +1,196 @@
+import path from 'node:path';
+import chalk from 'chalk';
+import { realGhExec } from '../../base/github-settings.js';
+import { defaultWorktreeRoot, findLive } from './loop-guard.js';
+/**
+ * `repo-tooling loop reap` — the ai-issue-loop skill's Pass 2 stalled-agent
+ * table, moved out of prose (#618). Nothing can time out an agent, so a label
+ * that sat `STALE_MINUTES` past its last application (per the timeline) marks
+ * a dead one:
+ *
+ * - **implementer** — issue `ai-wip`, no PR for `ai-<N>-*` → `block`.
+ * - **reviewer** — PR `ai-reviewing-code|sec` with no matching `ai-ok-*` and
+ *   no `ai-changes` → `drop-label` that claim, or `block` at ≥3 applications.
+ * - **fixer** — PR `ai-fixing` still `ai-changes` → `drop-label`, or `block`.
+ * - **orphan** — `ai-<N>-*` worktree whose issue is not `ai-wip` and has no
+ *   open PR → `remove-worktree`.
+ *
+ * Read-only: it reports verdicts, the skill applies them — the label, assign
+ * and comment of an `ai-blocked`, and the call on whether a stall was benign.
+ * Exit `1` when a gh query failed, so the report is incomplete.
+ */
+/** Three ticks. Generous: a live agent must never be reaped out from under itself. */
+export const STALE_MINUTES = 45;
+/** A claim applied this many times is not one more spawn away from working. */
+export const MAX_APPLICATIONS = 3;
+// ponytail: newest 200 PRs; an ai-wip issue's PR older than that reads as "no PR".
+const PR_WINDOW = 200;
+/** `ai-<N>-slug`, or the legacy `worktree-ai-<N>-slug`. */
+const issueOf = (name) => Number(name.match(/^(?:worktree-)?ai-(\d+)-/)?.[1]) || null;
+const REVIEW_CLAIMS = {
+    'ai-reviewing-code': 'ai-ok-code',
+    'ai-reviewing-sec': 'ai-ok-sec',
+};
+export async function runLoopReap(options = {}) {
+    const root = path.resolve(options.root ?? process.cwd());
+    const worktreeRoot = options.worktreeRoot
+        ? path.resolve(options.worktreeRoot)
+        : defaultWorktreeRoot(root);
+    const gh = options.gh ?? ((args, stdin) => realGhExec(args, stdin, root));
+    const now = (options.now ?? new Date()).getTime();
+    const errors = [];
+    const stalled = [];
+    const list = async (args) => {
+        const r = await gh(args);
+        if (!r.ok) {
+            errors.push(`gh ${args.slice(0, 2).join(' ')} failed: ${r.stderr.trim()}`);
+            return null;
+        }
+        return JSON.parse(r.stdout || '[]');
+    };
+    /** Every application of `label` on issue/PR `n`, oldest first. */
+    const applications = async (n, label) => {
+        const r = await gh([
+            'api',
+            `repos/{owner}/{repo}/issues/${n}/timeline`,
+            '--paginate',
+            '--jq',
+            '.[] | select(.event=="labeled") | [.label.name, .created_at] | @tsv',
+        ]);
+        if (!r.ok) {
+            errors.push(`timeline for #${n} failed: ${r.stderr.trim()}`);
+            return null;
+        }
+        return r.stdout
+            .split('\n')
+            .map((line) => line.split('\t'))
+            .filter(([name]) => name === label)
+            .map(([, at]) => Date.parse(at))
+            .sort((a, b) => a - b);
+    };
+    /** Age and count of `label` on `n`, or null when it is not stale yet (or unknown). */
+    const stale = async (n, label) => {
+        const times = await applications(n, label);
+        const last = times?.at(-1);
+        if (last === undefined)
+            return null;
+        const minutes = Math.floor((now - last) / 60_000);
+        return minutes >= STALE_MINUTES ? { minutes, applications: times?.length ?? 0 } : null;
+    };
+    const wip = await list([
+        'issue',
+        'list',
+        '--label',
+        'ai-wip',
+        '--state',
+        'open',
+        '--limit',
+        '100',
+        '--json',
+        'number',
+    ]);
+    const prs = await list([
+        'pr',
+        'list',
+        '--state',
+        'all',
+        '--limit',
+        String(PR_WINDOW),
+        '--json',
+        'number,state,headRefName,labels',
+    ]);
+    const dirs = await findLive([worktreeRoot, path.join(root, '.claude', 'worktrees')]);
+    const worktreeOf = (issue) => dirs.find((d) => issueOf(path.basename(d)) === issue) ?? null;
+    // Without both lists a "no PR" or "not ai-wip" verdict would be a guess.
+    if (wip && prs) {
+        const wipSet = new Set(wip.map((i) => i.number));
+        const prIssues = (state) => new Set(prs.filter((p) => !state || p.state === state).map((p) => issueOf(p.headRefName)));
+        const anyPr = prIssues();
+        const openPr = prIssues('OPEN');
+        for (const issue of wipSet) {
+            if (anyPr.has(issue))
+                continue;
+            const s = await stale(issue, 'ai-wip');
+            if (!s)
+                continue;
+            stalled.push({
+                kind: 'implementer',
+                issue,
+                pr: null,
+                label: 'ai-wip',
+                ...s,
+                action: 'block',
+                worktree: worktreeOf(issue),
+                reason: `ai-wip for ${s.minutes}min and no PR`,
+            });
+        }
+        for (const pr of prs.filter((p) => p.state === 'OPEN')) {
+            const labels = new Set(pr.labels.map((l) => l.name));
+            const issue = issueOf(pr.headRefName);
+            const claims = Object.entries(REVIEW_CLAIMS)
+                .filter(([claim, ok]) => labels.has(claim) && !labels.has(ok) && !labels.has('ai-changes'))
+                .map(([claim]) => ({ kind: 'reviewer', claim }));
+            if (labels.has('ai-fixing') && labels.has('ai-changes'))
+                claims.push({ kind: 'fixer', claim: 'ai-fixing' });
+            for (const { kind, claim } of claims) {
+                const s = await stale(pr.number, claim);
+                if (!s)
+                    continue;
+                const block = s.applications >= MAX_APPLICATIONS;
+                stalled.push({
+                    kind,
+                    issue,
+                    pr: pr.number,
+                    label: claim,
+                    ...s,
+                    action: block ? 'block' : 'drop-label',
+                    worktree: null,
+                    reason: `${claim} for ${s.minutes}min, applied ${s.applications}×`,
+                });
+            }
+        }
+        for (const dir of dirs) {
+            const issue = issueOf(path.basename(dir));
+            if (issue === null || wipSet.has(issue) || openPr.has(issue))
+                continue;
+            stalled.push({
+                kind: 'orphan',
+                issue,
+                pr: null,
+                label: null,
+                minutes: null,
+                applications: null,
+                action: 'remove-worktree',
+                worktree: dir,
+                reason: 'issue not ai-wip and no open PR',
+            });
+        }
+    }
+    return {
+        root,
+        worktreeRoot,
+        staleMinutes: STALE_MINUTES,
+        stalled,
+        errors,
+        exitCode: errors.length > 0 ? 1 : 0,
+    };
+}
+export async function loopReapCommand(options) {
+    const result = await runLoopReap(options);
+    if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        console.log();
+        if (result.stalled.length === 0)
+            console.log(chalk.gray('  nothing stalled'));
+        for (const s of result.stalled) {
+            const target = s.pr ? `PR #${s.pr}` : `#${s.issue}`;
+            console.log(`  ${chalk.yellow(s.action.padEnd(15))} ${target} (${s.kind}) — ${s.reason}`);
+        }
+        for (const e of result.errors)
+            console.log(`  ${chalk.red(e)}`);
+        console.log();
+    }
+    process.exitCode = result.exitCode;
+}

package/dist/cli/index.js

@@ -8,6 +8,8 @@ import { fixCommand } from './commands/fix.js';
 import { loopCleanupCommand } from './commands/loop-cleanup.js';
 import { loopEnvCommand } from './commands/loop-env.js';
 import { loopGuardCommand } from './commands/loop-guard.js';
+import { loopCommentCommand, loopVerdictCommand } from './commands/loop-marker.js';
+import { loopReapCommand } from './commands/loop-reap.js';
 import { loopWorktreeAddCommand } from './commands/loop-worktree.js';
 import { setupProject } from './commands/setup.js';
 import { copyPreset, PRESETS } from './utils/copy-preset.js';
@@ -402,6 +404,31 @@ loop
     .addHelpText('after', '\nExit 1 when the worktree was not created or a symlinkDirectories entry is left\n' +
     'unlinked — do not spawn an implementer. needsInstall means no list was declared.\n')
     .action(loopWorktreeAddCommand);
+loop
+    .command('reap')
+    .description('🪦 Report agents stalled past 45 minutes and what to do about each')
+    .option('--root <path>', 'Main checkout the loop branches worktrees from', process.cwd())
+    .option('--worktree-root <path>', 'Where ai-* worktrees live (default: <root>-worktrees)')
+    .option('--json', 'Emit machine-readable JSON output')
+    .addHelpText('after', '\nRead-only: prints a verdict per stall (block / drop-label / remove-worktree).\n' +
+    'Exits 1 when a gh query failed and the report is incomplete.\n')
+    .action(loopReapCommand);
+loop
+    .command('comment <pr>')
+    .description("💬 Upsert the loop's one decision-marker comment on a PR")
+    .requiredOption('--body-file <path>', 'Comment text, without the marker (- for stdin)')
+    .option('-d, --dir <path>', 'Directory to resolve the GitHub repo from', process.cwd())
+    .option('--json', 'Emit machine-readable JSON output')
+    .action(loopCommentCommand);
+loop
+    .command('verdict <pr>')
+    .description("⚖️  Read a reviewer arm's verdict marker for the PR's current head")
+    .requiredOption('--arm <arm>', 'Reviewer arm: code or sec')
+    .option('-d, --dir <path>', 'Directory to resolve the GitHub repo from', process.cwd())
+    .option('--json', 'Emit machine-readable JSON output')
+    .addHelpText('after', '\nPrints PASS, PASS-NOTES, CHANGES, or an empty line when none is posted.\n' +
+    'Exits 1 when the PR or its reviews cannot be read.\n')
+    .action(loopVerdictCommand);
 program.hook('preAction', async (_, actionCommand) => {
     const name = actionCommand.name();
     if (name === 'setup' || name === 'doctor' || name === 'fix') {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rtorcato/repo-tooling",
-	"version": "3.42.0",
+	"version": "3.44.0",
 	"description": "One CLI to scaffold, audit and fix your repo's whole toolchain — linting, tests, commits, releases & CI.",
 	"type": "module",
 	"keywords": [