@rtorcato/repo-tooling 3.43.0 → 3.45.0

package/AGENTS.md

@@ -30,6 +30,8 @@ Every command supports `--json` and a non-interactive mode. Combine with `--yes`
 | `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 tick --json` | ✅ | ✅ | One `ai-issue-loop` tick's work list: runs `loop guard`, `loop cleanup` (and `guard --removed`) and `loop reap`, reads verdicts, merge states, required checks and the `ai-ready` queue, and returns `{ halt, idle, adopt, disarm, handoffs, sendBacks, stripMergeReady, cleaned, stalled, decay, verdicts, reviewsToSpawn, fixRounds, slots, pickups, summary, errors }`. Writes no GitHub state — the skill applies every label, comment and spawn. Exit `1`/`2` halts the tick. |
+| `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
 
@@ -123,6 +125,8 @@ A fixer may also **refuse** — the target file holds something the generator ca
 - `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-tick.ts` — `loop tick`: composes the other `loop` helpers into one tick's work list, so the skill keeps only judgement and spawns (#620)
+- `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/base/github-settings.js

@@ -588,6 +588,19 @@ async function readEnvironments(gh, nwo) {
         return 'skip';
     }
 }
+/**
+ * The ai-issue-loop's unattended-merge probe (#620): true only when the job
+ * that publishes runs behind an environment carrying `required_reviewers`, so a
+ * human still stands between a merge and the registry. An environment no job
+ * references gates nothing, and every unreadable answer fails closed.
+ */
+export async function releaseGated(gh, nwo, dir) {
+    const publish = await findPublishJob(dir);
+    if (publish === null || publish === 'skip' || publish.environment === null)
+        return false;
+    const envs = await readEnvironments(gh, nwo);
+    return envs !== 'skip' && envs.get(publish.environment) === true;
+}
 /**
  * The gap between merging the default branch and publishing to npm (#429). On
  * the shipped semantic-release preset those are one event: nothing stands

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

@@ -31,6 +31,24 @@ const REVIEW_CLAIMS = {
     'ai-reviewing-code': 'ai-ok-code',
     'ai-reviewing-sec': 'ai-ok-sec',
 };
+/** Every application of `label` on issue/PR `n`, oldest first — or why it could not be read. */
+export async function labelApplications(gh, 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)
+        return `timeline for #${n} failed: ${r.stderr.trim()}`;
+    return r.stdout
+        .split('\n')
+        .map((line) => line.split('\t'))
+        .filter(([name]) => name === label)
+        .map(([, at]) => Date.parse(at))
+        .sort((a, b) => a - b);
+}
 export async function runLoopReap(options = {}) {
     const root = path.resolve(options.root ?? process.cwd());
     const worktreeRoot = options.worktreeRoot
@@ -48,25 +66,13 @@ export async function runLoopReap(options = {}) {
         }
         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()}`);
+        const times = await labelApplications(gh, n, label);
+        if (typeof times === 'string') {
+            errors.push(times);
             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);
+        return times;
     };
     /** Age and count of `label` on `n`, or null when it is not stale yet (or unknown). */
     const stale = async (n, label) => {

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

@@ -0,0 +1,349 @@
+import path from 'node:path';
+import chalk from 'chalk';
+import { realGitExec } from '../../base/git-identity.js';
+import { realGhExec, releaseGated } from '../../base/github-settings.js';
+import { runLoopCleanup } from './loop-cleanup.js';
+import { resolveLoopEnv } from './loop-env.js';
+import { runLoopGuard } from './loop-guard.js';
+import { runLoopVerdict } from './loop-marker.js';
+import { labelApplications, MAX_APPLICATIONS, runLoopReap } from './loop-reap.js';
+/**
+ * `repo-tooling loop tick` — one ai-issue-loop tick's mechanics as one work
+ * list (#620). It composes `loop env`, `loop guard`, `loop cleanup`,
+ * `loop reap` and `loop verdict` with the Pass 1 merge-state and CI reads, the
+ * Pass 0 PR-adoption query, the Pass 2 `ai-suggested` decay and the Pass 4
+ * eligibility query, and says what to do. The skill applies it: every label,
+ * assignee, comment, merge and agent spawn stays the agent's call.
+ *
+ * It writes no GitHub state. Its only local writes are the ones the helpers it
+ * composes already make — `loop guard`'s bare repair and gated `node_modules`
+ * rebuild, and `loop cleanup`'s removal of worktrees whose PR landed or closed.
+ *
+ * Exit non-zero only to halt the tick: `loop guard`'s own code (`1`/`2`), or `1`
+ * when the checkout or its GitHub repo cannot be resolved. A failed gh read is
+ * not a halt — the lists it feeds are left empty, it lands in `errors`, and the
+ * summary leads with `⚠error`.
+ */
+/** Issues in flight at once. */
+export const MAX_IN_FLIGHT = 6;
+/** `ai-suggested` issues untouched this long are closed. */
+export const DECAY_DAYS = 30;
+const TRUSTED = new Set(['OWNER', 'MEMBER', 'COLLABORATOR']);
+/** Merge states that name something to fix; any other non-CLEAN state waits. */
+const SEND_BACK_STATES = new Set(['BEHIND', 'DIRTY', 'BLOCKED']);
+const ARMS = ['code', 'sec'];
+const issueOf = (head) => Number(head.match(/^(?:worktree-)?ai-(\d+)-/)?.[1]) || null;
+function empty(env) {
+    return {
+        env,
+        halt: null,
+        idle: false,
+        releaseGated: false,
+        adopt: [],
+        disarm: [],
+        handoffs: [],
+        sendBacks: [],
+        stripMergeReady: [],
+        dependabotCiRed: [],
+        dependabotChanges: [],
+        cleaned: [],
+        stalled: [],
+        decay: [],
+        verdicts: [],
+        reviewsToSpawn: [],
+        fixRounds: [],
+        slots: 0,
+        pickups: [],
+        rebuild: 'not-requested',
+        summary: '',
+        errors: [],
+        exitCode: 0,
+    };
+}
+export async function runLoopTick(options = {}) {
+    const dir = path.resolve(options.root ?? process.cwd());
+    const env = await resolveLoopEnv({ dir, git: options.git, gh: options.gh, env: options.env });
+    const result = empty(env);
+    if (!env.root || !env.ownerRepo) {
+        result.halt = env.warnings.join('; ') || 'could not resolve the checkout';
+        result.exitCode = 1;
+        return result;
+    }
+    const { root, ownerRepo } = env;
+    const git = options.git ?? ((args) => realGitExec(args, root, 120_000));
+    const gh = options.gh ?? ((args, stdin) => realGhExec(args, stdin, root));
+    const now = (options.now ?? new Date()).getTime();
+    const errors = result.errors;
+    const seams = { root, git: options.git, gh: options.gh };
+    const guard = await runLoopGuard({ ...seams, install: options.install });
+    if (guard.exitCode !== 0) {
+        result.halt = guard.messages.filter((m) => m.startsWith('⚠')).join('; ') || 'loop guard failed';
+        result.exitCode = guard.exitCode;
+        return result;
+    }
+    // Best-effort: Pass 4 branches worktrees off origin/main.
+    await git(['fetch', '--prune', 'origin']);
+    const cleanup = await runLoopCleanup(seams);
+    result.cleaned = cleanup.worktrees.filter((w) => w.action === 'removed');
+    for (const w of cleanup.worktrees.filter((w) => w.action === 'remove-failed'))
+        errors.push(`could not remove ${w.path}`);
+    let live = guard.live;
+    if (cleanup.removed) {
+        const again = await runLoopGuard({ ...seams, install: options.install, removed: true });
+        if (again.exitCode !== 0) {
+            result.halt =
+                again.messages.filter((m) => m.startsWith('⚠')).join('; ') || 'loop guard failed';
+            result.exitCode = again.exitCode;
+            return result;
+        }
+        result.rebuild = again.rebuild;
+        live = again.live;
+    }
+    const reap = await runLoopReap({ root, gh: options.gh, now: options.now });
+    result.stalled = reap.stalled;
+    errors.push(...reap.errors);
+    const json = async (args) => {
+        const r = await gh(args);
+        if (r.ok) {
+            try {
+                return JSON.parse(r.stdout || 'null');
+            }
+            catch { }
+        }
+        errors.push(`gh ${args.slice(0, 3).join(' ')} failed: ${r.stderr.trim()}`);
+        return null;
+    };
+    const prs = await json([
+        'pr',
+        'list',
+        '--state',
+        'open',
+        '--limit',
+        '100',
+        '--json',
+        'number,headRefName,labels,autoMergeRequest,author,body,statusCheckRollup',
+    ]);
+    const wip = await json([
+        'issue',
+        'list',
+        '--label',
+        'ai-wip',
+        '--state',
+        'open',
+        '--limit',
+        '100',
+        '--json',
+        'number',
+    ]);
+    result.releaseGated = await releaseGated(gh, ownerRepo, root);
+    for (const pr of prs ?? []) {
+        const labels = new Set(pr.labels.map((l) => l.name));
+        const has = (l) => labels.has(l);
+        const issue = issueOf(pr.headRefName);
+        if (pr.headRefName.startsWith('dependabot/')) {
+            const red = (pr.statusCheckRollup ?? []).some((c) => c.conclusion === 'FAILURE');
+            if (pr.autoMergeRequest && red)
+                result.dependabotCiRed.push(pr.number);
+            if (has('ai-changes'))
+                result.dependabotChanges.push(pr.number);
+            continue;
+        }
+        const loopPr = has('merge-ready') || [...labels].some((l) => l.startsWith('ai-'));
+        if (!loopPr) {
+            // The 🤖 header is the discriminator: every agent is the owner's login.
+            const mine = pr.author?.login.toLowerCase() === env.me.toLowerCase();
+            if (env.me && mine && (pr.body ?? '').startsWith('🤖 '))
+                result.adopt.push(pr.number);
+            continue;
+        }
+        const passed = (has('ai-ok-code') && has('ai-ok-sec')) || has('merge-ready');
+        if (pr.autoMergeRequest && !passed)
+            result.disarm.push(pr.number);
+        const claimed = has('ai-reviewing-code') || has('ai-reviewing-sec');
+        // CI red is a send-back, except mid-review or when one is already out.
+        if (!claimed && !has('ai-changes')) {
+            const r = await gh([
+                'pr',
+                'checks',
+                String(pr.number),
+                '--required',
+                '--json',
+                'name,state,link',
+            ]);
+            // Exits non-zero whenever a check fails or is pending; stdout is still the answer.
+            let checks = [];
+            try {
+                checks = JSON.parse(r.stdout || '[]');
+            }
+            catch { }
+            const failing = checks
+                .filter((c) => c.state === 'FAILURE')
+                .map(({ name, link }) => ({ name, link }));
+            if (failing.length > 0) {
+                result.sendBacks.push({ pr: pr.number, issue, reason: 'ci-red', failing });
+                continue;
+            }
+        }
+        if (has('ai-changes')) {
+            if (has('merge-ready'))
+                result.stripMergeReady.push(pr.number);
+        }
+        else if (passed) {
+            const view = await json([
+                'pr',
+                'view',
+                String(pr.number),
+                '--json',
+                'mergeStateStatus',
+            ]);
+            const s = view?.mergeStateStatus ?? 'UNKNOWN';
+            if (s === 'CLEAN') {
+                const notes = has('ai-notes');
+                result.handoffs.push({
+                    pr: pr.number,
+                    issue,
+                    notes,
+                    autoMerge: result.releaseGated && !notes,
+                });
+            }
+            else if (SEND_BACK_STATES.has(s)) {
+                result.sendBacks.push({
+                    pr: pr.number,
+                    issue,
+                    reason: s,
+                    failing: [],
+                });
+            }
+            else if (s !== 'UNKNOWN' && has('merge-ready')) {
+                result.stripMergeReady.push(pr.number);
+            }
+            continue;
+        }
+        if (has('ai-review') && !has('ai-changes')) {
+            const spawn = [];
+            let changes = false;
+            for (const arm of ARMS) {
+                if (has(`ai-ok-${arm}`) || has(`ai-reviewing-${arm}`))
+                    continue;
+                const v = await runLoopVerdict(pr.number, { dir: root, arm, gh: options.gh });
+                if (v.error)
+                    errors.push(`verdict ${arm} on #${pr.number}: ${v.error}`);
+                else if (v.verdict) {
+                    result.verdicts.push({ pr: pr.number, arm, verdict: v.verdict });
+                    changes ||= v.verdict === 'CHANGES';
+                }
+                else
+                    spawn.push(arm);
+            }
+            // A CHANGES about to be applied sends the PR back; a review now is wasted.
+            if (!changes)
+                for (const arm of spawn)
+                    result.reviewsToSpawn.push({ pr: pr.number, issue, arm });
+        }
+        if (has('ai-changes') && !has('ai-fixing')) {
+            const times = await labelApplications(gh, pr.number, 'ai-changes');
+            if (typeof times === 'string') {
+                errors.push(times);
+                continue;
+            }
+            const slug = pr.headRefName.replace(/^worktree-/, '');
+            const worktree = live.find((d) => path.basename(d) === slug) ?? null;
+            const atCap = times.length >= MAX_APPLICATIONS;
+            result.fixRounds.push({
+                pr: pr.number,
+                issue,
+                worktree,
+                applications: times.length,
+                action: atCap || !worktree ? 'block' : 'spawn',
+                reason: atCap
+                    ? `ai-changes applied ${times.length}× — round cap reached`
+                    : worktree
+                        ? `round ${times.length}`
+                        : 'no worktree to fix in',
+            });
+        }
+    }
+    const suggested = await json([
+        'issue',
+        'list',
+        '--label',
+        'ai-suggested',
+        '--state',
+        'open',
+        '--limit',
+        '100',
+        '--json',
+        'number,updatedAt,labels',
+    ]);
+    const cutoff = now - DECAY_DAYS * 86_400_000;
+    result.decay = (suggested ?? [])
+        // A promoted suggestion keeps its label; closing a queued one is unrecoverable.
+        .filter((i) => !i.labels.some((l) => ['ai-ready', 'ai-wip', 'holding'].includes(l.name)))
+        .filter((i) => Date.parse(i.updatedAt) < cutoff)
+        .map((i) => i.number);
+    // ponytail: first 100 ai-ready issues; paginate if a queue ever outgrows that.
+    const queue = await json([
+        'api',
+        `repos/${ownerRepo}/issues?labels=ai-ready&state=open&per_page=100`,
+    ]);
+    result.pickups = (queue ?? [])
+        .filter((i) => !i.pull_request)
+        .filter((i) => !i.labels.some((l) => ['ai-wip', 'ai-blocked', 'holding'].includes(l.name)))
+        // The label is the hard gate; association is the backstop.
+        .filter((i) => TRUSTED.has(i.author_association))
+        .map(({ number, title, body }) => ({ number, title, body: body ?? '' }));
+    // Slots count what is still in flight once this tick's cleanup and reaping land.
+    const freed = new Set([
+        ...result.cleaned.map((w) => w.issue),
+        ...result.stalled.filter((s) => s.kind === 'implementer').map((s) => s.issue),
+    ]);
+    const inFlight = (wip ?? []).filter((i) => !freed.has(i.number)).length;
+    result.slots = wip ? Math.max(0, MAX_IN_FLIGHT - inFlight) : 0;
+    const loopPrs = (prs ?? []).filter((p) => !p.headRefName.startsWith('dependabot/') &&
+        p.labels.some((l) => l.name === 'merge-ready' || l.name.startsWith('ai-')));
+    result.idle =
+        errors.length === 0 &&
+            loopPrs.length === 0 &&
+            live.length === 0 &&
+            [result.adopt, result.pickups, result.stalled, result.decay, result.dependabotCiRed].every((l) => l.length === 0);
+    result.summary = summarize(result, inFlight, loopPrs.length);
+    return result;
+}
+/** `⚠` segments first, so a truncated phone banner still leads with the stall. */
+export function summarize(r, inFlight, loopPrs) {
+    if (r.idle)
+        return 'idle';
+    const blocked = r.stalled.filter((s) => s.action === 'block').length +
+        r.fixRounds.filter((f) => f.action === 'block').length;
+    const ciRed = r.sendBacks.filter((s) => s.reason === 'ci-red').length + r.dependabotCiRed.length;
+    const wip = inFlight + Math.min(r.slots, r.pickups.length);
+    const ready = r.handoffs.length;
+    const segments = [
+        [r.errors.length > 0, '⚠error'],
+        [blocked, `⚠${blocked}blocked`],
+        [ciRed, `⚠${ciRed}ci-red`],
+        [r.rebuild === 'deferred' || r.rebuild === 'rebuild-failed', '⚠rebuild'],
+        [wip, `${wip}wip`],
+        [loopPrs - ready, `${loopPrs - ready}rev`],
+        [ready, `${ready}ready`],
+    ];
+    return (segments
+        .filter(([n]) => n)
+        .map(([, s]) => s)
+        .join('·') || 'idle');
+}
+export async function loopTickCommand(options) {
+    const result = await runLoopTick(options);
+    if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else if (result.halt) {
+        console.error(chalk.red(`✖ halt: ${result.halt}`));
+    }
+    else {
+        console.log(result.summary);
+        for (const e of result.errors)
+            console.log(`  ${chalk.yellow(e)}`);
+    }
+    process.exitCode = result.exitCode;
+}

package/dist/cli/index.js

@@ -8,7 +8,9 @@ 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 { loopTickCommand } from './commands/loop-tick.js';
 import { loopWorktreeAddCommand } from './commands/loop-worktree.js';
 import { setupProject } from './commands/setup.js';
 import { copyPreset, PRESETS } from './utils/copy-preset.js';
@@ -412,6 +414,30 @@ loop
     .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);
+loop
+    .command('tick')
+    .description("📋 Compute one tick's work list — guard, cleanup, reap, verdicts, pickups")
+    .option('--root <path>', 'Main checkout, or any worktree of it', process.cwd())
+    .option('--json', 'Emit machine-readable JSON output')
+    .addHelpText('after', '\nWrites no GitHub state: the caller applies every label, comment and spawn.\n' +
+    "Exit 1 or 2 halts the tick (loop guard's codes, or an unresolvable checkout).\n")
+    .action(loopTickCommand);
 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.43.0",
+	"version": "3.45.0",
 	"description": "One CLI to scaffold, audit and fix your repo's whole toolchain — linting, tests, commits, releases & CI.",
 	"type": "module",
 	"keywords": [