Rebase onto upstream/master (2026-07-16): 68 commits (4a40c0c..f44a002) (#243)

Cherry-picked 68 upstream commits covering: MCP access governance (8-part split), security hardening (cross-tenant oracle fix, invite-token entropy, rate-limit key fix), performance (event-sourced live-runs, tab memory churn cuts, transcript buffer cap), adapters (local process confinement, env forwarding, codex auth fixes), heartbeat/recovery improvements, active PR gardening workflow, skills import, bulk extract, company skill policies, cost event tracking, tool connections, and dependency bumps.

- Migration rename: upstream 0147–0171 renumbered to 0148–0172 (offset +1 for fork-specific 0137_acpx_default_engine_migration)
- 49 files re-merged preserving fork-specific customizations
- Fork test updated for upstream's companyId validation on plugin config reads

Author: stubbi

.agents/skills/pr-gardening/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: pr-gardening
+description: >
+  Discover recently referenced Paperclip pull requests, mechanically verify
+  their current-head readiness, drive non-draft PRs back to green through their
+  originating issues, and publish a merge-confidence report without merging.
+compatibility: Requires Node.js 20+, gh authenticated for GitHub read access, and Paperclip run credentials.
+allowed-tools: Bash(node:*) Bash(gh:*) Bash(curl:*)
+---
+
+# PR Gardening
+
+Actively garden pull requests referenced by Paperclip issues active in a recent window. Candidate discovery and readiness checking are scripts, not LLM analysis. GitHub access is read-only throughout this workflow.
+
+## Hard Guardrails
+
+- **Never merge, approve, or close a pull request.**
+- **Never instruct another person or agent to merge, approve, or close a pull request.**
+- Never use mutating `gh` commands or mutating GitHub API requests. The scripts only use `gh pr view` and read-only `gh api` GET requests.
+- Draft pull requests are report-only. Do not post gardening comments for drafts.
+- Comment only on existing originating issues. Never create a gardening issue per pull request.
+- `--dry-run` suppresses all Paperclip gardening comments. Discovery and GitHub inspection remain read-only in every mode.
+
+## Inputs
+
+- `--days <N>`: issue activity window, default `30`.
+- `--repo <owner/repo>`: GitHub repository, default detected by `gh repo view`.
+- `--dry-run`: discover, verify, and report without posting Stage C comments.
+- `--cooldown-hours <N>`: repeat-comment cooldown, default `48`.
+- `--max-rounds <N>`: maximum gardening rounds per PR, default `3`.
+
+Use a run-owned directory such as `$PAPERCLIP_RUN_SCRATCH_DIR/pr-gardening` for generated files.
+
+## Stage A — Discover Candidates
+
+Run the extract-search path. It scans every result page, rejects truncated match sets, normalizes PR URLs, deduplicates PR numbers, records every mentioning issue, checks issue work products to identify the origin, and drops PRs that GitHub says are merged or closed.
+
+```bash
+node .agents/skills/pr-gardening/scripts/find-candidates.mjs \
+  --days 30 \
+  --dry-run \
+  --output "$RUN_DIR/candidates.json"
+```
+
+The script calls `GET /api/companies/:companyId/search/extract` with `kind=url`, `scope=all`, and `updatedWithin=<N>d`. Do not replace it with full issue-list fetching or LLM scanning.
+
+## Stage B — Verify Current-Head Readiness
+
+```bash
+node .agents/skills/pr-gardening/scripts/check-readiness.mjs \
+  --input "$RUN_DIR/candidates.json" \
+  --output "$RUN_DIR/readiness.json" \
+  --dry-run
+```
+
+For every candidate, the script re-fetches the current head SHA and records:
+
+- open/draft state and mergeability/conflicts;
+- `statusCheckRollup` check-run and legacy status inventory;
+- a completed Greptile check-run on the exact head, clean only for `success` or `neutral`;
+- `reviewDecision`;
+- commits behind the base branch.
+
+Verdicts are `ready`, `needs_gardening`, or `report_only` for drafts. Always rerun this stage after any wake or claim that a PR was fixed. Never trust issue comments as proof of readiness.
+
+## Stage C — Comment on Originating Issues
+
+Skip this stage in `--dry-run` mode and for `ready` or `report_only` entries.
+
+For each `needs_gardening` PR, use `originatingIssue` from `candidates.json`. Selection priority is:
+
+1. issue carrying the exact PR URL as a `pull_request` work product;
+2. issue whose comment mentions the PR;
+3. most recently active mentioning issue.
+
+Before commenting, fetch the issue comments and search for this marker:
+
+```text
+<!-- pr-gardening:<owner/repo>#<number> -->
+```
+
+Do not comment if the latest matching marker is newer than the cooldown. Track rounds from matching markers; after three rounds, stop nagging and report `not converging; recommend close or human decision`. This is a recommendation for human disposition, not an instruction to close the PR.
+
+When a comment is allowed, mention the originating issue assignee, instruct them to run `/prepare-pr`, include the current head SHA, and copy the exact machine-detected `reasons[]`. Use `POST /api/issues/:issueId/comments` with `X-Paperclip-Run-Id`. Include `resume: true` when the issue is terminal so the comment creates a live continuation.
+
+Suggested body:
+
+```markdown
+<!-- pr-gardening:paperclipai/paperclip#1234 -->
+@Assignee please run `/prepare-pr` for https://github.com/paperclipai/paperclip/pull/1234.
+
+Current-head verification at `abc123` found:
+- failing check: test
+- Greptile missing at current head
+
+Gardening round 1/3. Re-verification is required after changes; do not merge based on this comment.
+```
+
+## Stage D — Monitor to Termination
+
+Set the gardening run issue's `blockedByIssueIds` to the non-terminal issues commented in Stage C so blocker resolution wakes the gardener. A scheduled or manual rerun is the fallback.
+
+On every wake, rerun Stage B first. A PR terminates from active gardening only when one of these is mechanically observed:
+
+- verified `ready` at the current head;
+- merged or closed externally;
+- maximum rounds reached, reported as not converging.
+
+Do not leave the gardening issue blocked on terminal issues. Do not poll agents or long-running sessions.
+
+## Stage E — Render and Publish the Report
+
+```bash
+node .agents/skills/pr-gardening/scripts/render-report.mjs \
+  --input "$RUN_DIR/readiness.json" \
+  --output "$RUN_DIR/gardening-report.md"
+```
+
+The report groups open PRs by confidence:
+
+- **High:** current-head checks green, no conflicts, Greptile clean, base fresh, originating issue terminal.
+- **Medium:** otherwise green but base stale, review not complete, or originating issue active.
+- **Low:** failing/pending checks, missing Greptile, draft/just-fixed-unverified state, or no identifiable origin.
+
+Upload `candidates.json`, `readiness.json`, and `gardening-report.md` to the gardening issue, create/update the `gardening-report` issue document with the Markdown body, and leave a summary comment linking the artifacts. The report is the deliverable; it is never authorization to merge.
+
+## Verification
+
+Run focused script tests:
+
+```bash
+node --test .agents/skills/pr-gardening/scripts/pr-gardening.test.mjs
+```
+
+For a live dry run, execute Stages A, B, and E with `--dry-run`, then sanity-check named PRs only if they are still open. Merged or closed examples should appear under `droppedClosedPullRequests`, not in readiness results.

.agents/skills/pr-gardening/scripts/check-readiness.mjs

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+import { pathToFileURL } from "node:url";
+import {
+  ghJson,
+  isTerminalIssue,
+  normalizeCheck,
+  normalizeRepository,
+  parseArgs,
+  readJson,
+  reason,
+  writeJson,
+} from "./lib.mjs";
+
+function assessChecks(contexts) {
+  const checks = contexts.map(normalizeCheck);
+  return {
+    checks,
+    pending: checks.filter((check) => check.pending),
+    failing: checks.filter((check) => !check.pending && !check.green),
+    allGreen: checks.length > 0 && checks.every((check) => check.green),
+  };
+}
+
+function assessGreptile(checkRuns) {
+  const runs = checkRuns.filter((run) => /greptile/i.test(run.name));
+  const completed = runs.filter((run) => run.status === "completed");
+  const clean = completed.filter((run) => run.conclusion === "success" || run.conclusion === "neutral");
+  const blocking = completed.filter((run) => run.conclusion !== "success" && run.conclusion !== "neutral");
+  return {
+    present: runs.length > 0,
+    pending: runs.some((run) => run.status !== "completed"),
+    clean: clean.length > 0 && blocking.length === 0,
+    runs: runs.map((run) => ({
+      name: run.name,
+      status: run.status,
+      conclusion: run.conclusion,
+      detailsUrl: run.details_url ?? null,
+    })),
+  };
+}
+
+function fetchCheckRuns(repository, headSha) {
+  const runs = [];
+  for (let page = 1; page <= 100; page += 1) {
+    const response = ghJson([
+      "api",
+      `repos/${repository}/commits/${headSha}/check-runs?per_page=100&page=${page}`,
+    ]);
+    const pageRuns = response.check_runs ?? [];
+    runs.push(...pageRuns);
+    if (pageRuns.length < 100) return runs;
+  }
+  throw new Error(`Check-run pagination exceeded 100 pages for ${headSha}`);
+}
+
+export function readinessVerdict({ pullRequest, checks, greptile, behindBy, originatingIssue }) {
+  const reasons = [];
+  if (pullRequest.state !== "OPEN") reasons.push(reason("pr_not_open", `PR is ${pullRequest.state.toLowerCase()}`));
+  const mergeable = pullRequest.mergeable ?? "UNKNOWN";
+  if (mergeable === "CONFLICTING") reasons.push(reason("merge_conflict", "GitHub reports merge conflicts"));
+  if (mergeable === "UNKNOWN") reasons.push(reason("mergeability_unknown", "GitHub has not resolved mergeability"));
+  if (checks.pending.length > 0) {
+    reasons.push(reason("checks_pending", `${checks.pending.length} check(s) are pending`, "blocking", { names: checks.pending.map((check) => check.name) }));
+  }
+  if (checks.failing.length > 0) {
+    reasons.push(reason("checks_failing", `${checks.failing.length} check(s) are not green`, "blocking", { names: checks.failing.map((check) => check.name) }));
+  }
+  if (checks.checks.length === 0) reasons.push(reason("checks_missing", "No status checks were found at the current head"));
+  if (!greptile.present) reasons.push(reason("greptile_missing", "No Greptile check-run exists at the current head"));
+  else if (greptile.pending) reasons.push(reason("greptile_pending", "Greptile has not completed at the current head"));
+  else if (!greptile.clean) reasons.push(reason("greptile_not_clean", "Greptile did not conclude success or neutral at the current head"));
+  if (pullRequest.reviewDecision === "CHANGES_REQUESTED") reasons.push(reason("changes_requested", "A review requests changes"));
+  if (pullRequest.reviewDecision === "REVIEW_REQUIRED") reasons.push(reason("review_required", "Required review approval is missing"));
+  if (behindBy > 0) reasons.push(reason("base_behind", `Head is ${behindBy} commit(s) behind base`, "blocking", { behindBy }));
+  if (!originatingIssue) reasons.push(reason("originating_issue_missing", "No originating Paperclip issue was identified", "reporting"));
+  else if (!isTerminalIssue(originatingIssue.status)) {
+    reasons.push(reason("originating_issue_active", `Originating issue ${originatingIssue.identifier ?? originatingIssue.issueId} is ${originatingIssue.status}`, "reporting"));
+  }
+
+  if (pullRequest.isDraft) return { verdict: "report_only", reasons };
+  return { verdict: reasons.some((entry) => entry.severity === "blocking") ? "needs_gardening" : "ready", reasons };
+}
+
+export function confidenceFor(entry) {
+  if (entry.verdict === "report_only") return "low";
+  const codes = new Set(entry.reasons.map((entryReason) => entryReason.code));
+  const lowConfidenceCodes = [
+    "originating_issue_missing",
+    "greptile_missing",
+    "greptile_pending",
+    "greptile_not_clean",
+    "checks_missing",
+    "checks_failing",
+    "checks_pending",
+    "merge_conflict",
+    "mergeability_unknown",
+    "changes_requested",
+  ];
+  if (lowConfidenceCodes.some((code) => codes.has(code))) {
+    return "low";
+  }
+  if (entry.verdict === "ready" && !codes.has("originating_issue_active")) return "high";
+  return "medium";
+}
+
+export async function checkReadiness(candidatesDocument, options = {}) {
+  const repository = normalizeRepository(options.repo ?? candidatesDocument.repository);
+  const results = [];
+  for (const candidate of candidatesDocument.candidates) {
+    const pullRequest = ghJson([
+      "pr",
+      "view",
+      String(candidate.number),
+      "--repo",
+      repository,
+      "--json",
+      "number,url,title,state,isDraft,headRefOid,baseRefName,headRefName,mergeable,mergeStateStatus,reviewDecision,statusCheckRollup,updatedAt",
+    ]);
+    const checkRuns = fetchCheckRuns(repository, pullRequest.headRefOid);
+    const comparison = ghJson([
+      "api",
+      `repos/${repository}/compare/${encodeURIComponent(pullRequest.baseRefName)}...${encodeURIComponent(pullRequest.headRefOid)}`,
+    ]);
+    const checks = assessChecks(pullRequest.statusCheckRollup ?? []);
+    const greptile = assessGreptile(checkRuns);
+    const assessment = readinessVerdict({
+      pullRequest,
+      checks,
+      greptile,
+      behindBy: comparison.behind_by ?? 0,
+      originatingIssue: candidate.originatingIssue,
+    });
+    const entry = {
+      number: pullRequest.number,
+      url: pullRequest.url,
+      title: pullRequest.title,
+      state: pullRequest.state.toLowerCase(),
+      isDraft: pullRequest.isDraft,
+      headSha: pullRequest.headRefOid,
+      baseRefName: pullRequest.baseRefName,
+      headRefName: pullRequest.headRefName,
+      mergeable: (pullRequest.mergeable ?? "UNKNOWN").toLowerCase(),
+      mergeStateStatus: (pullRequest.mergeStateStatus ?? "UNKNOWN").toLowerCase(),
+      reviewDecision: pullRequest.reviewDecision || null,
+      behindBy: comparison.behind_by ?? 0,
+      checks,
+      greptile,
+      originatingIssue: candidate.originatingIssue,
+      sourceIssues: candidate.sourceIssues,
+      ...assessment,
+    };
+    entry.confidence = confidenceFor(entry);
+    results.push(entry);
+  }
+  return {
+    schemaVersion: 1,
+    generatedAt: new Date().toISOString(),
+    repository,
+    candidatesGeneratedAt: candidatesDocument.generatedAt,
+    dryRun: Boolean(options.dry_run ?? candidatesDocument.dryRun),
+    summary: {
+      total: results.length,
+      ready: results.filter((entry) => entry.verdict === "ready").length,
+      needsGardening: results.filter((entry) => entry.verdict === "needs_gardening").length,
+      reportOnly: results.filter((entry) => entry.verdict === "report_only").length,
+    },
+    pullRequests: results,
+  };
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2), { input: "candidates.json", output: "readiness.json" });
+  writeJson(options.output, await checkReadiness(readJson(options.input), options));
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });
+}