@openhands/extensions 0.15.0 → 0.17.0

package/marketplaces/openhands-extensions.json

@@ -29,6 +29,7 @@
       "source": "./skills/add-skill",
       "description": "Add (import) an OpenHands skill from a GitHub repository into the current workspace.",
       "category": "agent-authoring",
+      "defaultEnabled": true,
       "keywords": [
         "skill",
         "import",
@@ -41,6 +42,7 @@
       "source": "./skills/agent-memory",
       "description": "Persist and retrieve repository-specific knowledge using AGENTS.md files. Use when you want to save important information about a codebase (build commands, code style, workflows) for future sessions.",
       "category": "agent-authoring",
+      "defaultEnabled": true,
       "keywords": [
         "memory",
         "knowledge",
@@ -53,6 +55,7 @@
       "source": "./skills/agent-sdk-builder",
       "description": "Guided workflow for building custom AI agents using the OpenHands Software Agent SDK. Use when you want to create a new agent through an interactive interview process that gathers requirements and generates implementation plans.",
       "category": "agent-authoring",
+      "defaultEnabled": true,
       "keywords": [
         "agent",
         "sdk",
@@ -80,6 +83,7 @@
       "source": "./skills/openhands-automation",
       "description": "Create and manage OpenHands automations - scheduled tasks that run in sandboxes. Use the prompt preset to create automations from natural language, or manage existing automations.",
       "category": "automations",
+      "defaultEnabled": true,
       "keywords": [
         "automation",
         "cron",
@@ -93,6 +97,7 @@
       "source": "./skills/agent-canvas-environment",
       "description": "Work effectively inside a local Agent Canvas environment, including local agent-server auth, safe workspace hygiene, and local conversation delegation.",
       "category": "agent-authoring",
+      "defaultEnabled": true,
       "keywords": [
         "agent-canvas",
         "openhands",
@@ -106,6 +111,7 @@
       "source": "./skills/openhands-sdk",
       "description": "Reference skill for the OpenHands Software Agent SDK - build AI agents with custom tools, LLM configuration, conversations, sub-agent delegation, MCP integration, security, and persistence.",
       "category": "agent-authoring",
+      "defaultEnabled": true,
       "keywords": [
         "sdk",
         "agent",
@@ -182,6 +188,7 @@
       "source": "./skills/code-review",
       "description": "Rigorous code review focusing on data structures, simplicity, security, pragmatism, and risk/safety evaluation. Provides brutally honest, actionable feedback on pull requests or merge requests, including a risk assessment for every review. Use when reviewing code changes.",
       "category": "code-quality",
+      "defaultEnabled": true,
       "keywords": [
         "code-review",
         "quality",
@@ -232,6 +239,7 @@
       "source": "./skills/docker",
       "description": "Run Docker commands within a container environment, including starting the Docker daemon and managing containers. Use when building, running, or managing Docker containers and images.",
       "category": "environment",
+      "defaultEnabled": true,
       "keywords": [
         "docker",
         "container",
@@ -268,6 +276,7 @@
       "source": "./skills/github",
       "description": "Interact with GitHub repositories, pull requests, issues, and workflows using the GITHUB_TOKEN environment variable and GitHub CLI. Use when working with code hosted on GitHub or managing GitHub resources.",
       "category": "code-hosting",
+      "defaultEnabled": true,
       "keywords": [
         "github",
         "git",
@@ -444,6 +453,7 @@
       "source": "./skills/openhands-api",
       "description": "Use the OpenHands Cloud REST API (V1) and agent-server APIs to create and manage Cloud or local backend conversations, including multi-conversation delegation workflows. Includes minimal Python and TypeScript clients under scripts/.",
       "category": "agent-authoring",
+      "defaultEnabled": true,
       "keywords": [
         "openhands",
         "api",
@@ -534,6 +544,7 @@
       "source": "./skills/skill-creator",
       "description": "Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.",
       "category": "agent-authoring",
+      "defaultEnabled": true,
       "keywords": [
         "skill",
         "plugin",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openhands/extensions",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Public OpenHands extension catalogs for skills, plugins, integrations, and automation templates.",
   "license": "MIT",
   "type": "module",

package/plugins/qa-changes/action.yml

@@ -160,7 +160,7 @@ runs:
         # so we enforce the time limit via the coreutils timeout command.
         TIMEOUT_SECONDS=$((TIMEOUT_MINUTES * 60))
         timeout "${TIMEOUT_SECONDS}" \
-          uv run --no-project --with openhands-sdk --with openhands-tools --with 'lmnr<0.7.53' \
+          uv run --no-project --with openhands-sdk --with openhands-tools --with lmnr \
             python ../extensions/plugins/qa-changes/scripts/agent_script.py
 
     - name: Upload logs as artifact

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "openhands-extensions"
-version = "0.15.0"
+version = "0.17.0"
 description = "OpenHands extensions, plugins, and skills (Python bindings for the integration catalog)"
 requires-python = ">=3.12"
 dependencies = [

package/python/openhands_extensions/_version.py

@@ -18,7 +18,7 @@ from importlib.metadata import PackageNotFoundError, version
 #: Kept in lock-step with pyproject.toml/package.json by the version test.
 #: release-please only rewrites a semver found on the annotated line itself, so
 #: the annotation must stay on the assignment; on its own line it is a no-op.
-_FALLBACK_VERSION = "0.15.0"  # x-release-please-version
+_FALLBACK_VERSION = "0.17.0"  # x-release-please-version
 
 try:
     __version__: str = version("openhands-extensions")

package/scripts/build-automation-catalog.mjs

@@ -4,6 +4,7 @@ import path from "node:path";
 const root = process.cwd();
 const catalogDir = path.join(root, "automations", "catalog");
 const outputPath = path.join(root, "automations", "catalog-index.js");
+const bundleOutputPath = path.join(root, "automations", "bundle-index.js");
 
 const directories = (await readdir(catalogDir, { withFileTypes: true }))
   .filter((entry) => entry.isDirectory())
@@ -37,6 +38,25 @@ const imports = indexedAutomations
   .join("\n");
 const entries = indexedAutomations.map(({ importName }) => `  ${importName},`).join("\n");
 
+// A bundle entry names its files by repository-relative path, so the one copy
+// of a script shipped by both a skill and the catalog stays in one place. The
+// package cannot ship a path, though - a browser host has no repository - so
+// the contents are inlined here at build time.
+const bundles = {};
+for (const { entry } of automations) {
+  const files = entry.setup?.bundle?.files;
+  if (!files) continue;
+  bundles[entry.id] = {};
+  for (const [packedPath, source] of Object.entries(files).sort()) {
+    if (!/^(skills|automations)\//.test(source) || source.includes("..")) {
+      throw new Error(
+        `${entry.id}: bundle file "${packedPath}" names ${source}, which is outside skills/ or automations/`,
+      );
+    }
+    bundles[entry.id][packedPath] = await readFile(path.join(root, source), "utf8");
+  }
+}
+
 const header = `// This file is auto-generated by scripts/build-automation-catalog.mjs.
 // Do not edit it manually. To update it after changing automations/catalog/*/manifest.json,
 // run: npm run build:automations
@@ -49,3 +69,13 @@ ${entries}
 ];
 `;
 await writeFile(outputPath, body);
+
+const bundleHeader = `// This file is auto-generated by scripts/build-automation-catalog.mjs.
+// Do not edit it manually. It inlines the files each bundle entry ships, read from
+// the repository paths its manifest names. To update it, run: npm run build:automations
+
+`;
+await writeFile(
+  bundleOutputPath,
+  `${bundleHeader}export const AUTOMATION_BUNDLE_FILES = ${JSON.stringify(bundles, null, 2)};\n`,
+);

package/scripts/build-skills-catalog.mjs

@@ -36,8 +36,8 @@ export const SKILL_CATEGORY_IDS = [
 
 const FALLBACK_CATEGORY = "other";
 
-/** Build a `skill directory name -> {category, file}` map from every manifest. */
-export function buildCategoryMap(marketplacesDir) {
+/** Build a `skill directory name -> {category, defaultEnabled, file}` map from every manifest. */
+export function buildEntryMap(marketplacesDir) {
   const map = new Map();
 
   for (const filename of readdirSync(marketplacesDir).filter((f) => f.endsWith(".json")).sort()) {
@@ -56,14 +56,27 @@ export function buildCategoryMap(marketplacesDir) {
         );
       }
 
+      if ("defaultEnabled" in entry && typeof entry.defaultEnabled !== "boolean") {
+        throw new Error(
+          `${filename}: skill "${name}" has defaultEnabled ${JSON.stringify(entry.defaultEnabled)}, expected a boolean`,
+        );
+      }
+
+      const defaultEnabled = entry.defaultEnabled === true;
+
       const existing = map.get(name);
       if (existing && existing.category !== category) {
         throw new Error(
           `Conflicting categories for skill "${name}": ${existing.file} says "${existing.category}", ${filename} says "${category}"`,
         );
       }
+      if (existing && existing.defaultEnabled !== defaultEnabled) {
+        throw new Error(
+          `Conflicting defaultEnabled for skill "${name}": ${existing.file} says ${existing.defaultEnabled}, ${filename} says ${defaultEnabled}`,
+        );
+      }
 
-      map.set(name, { category, file: filename });
+      map.set(name, { category, defaultEnabled, file: filename });
     }
   }
 
@@ -114,7 +127,7 @@ export function parseFrontmatter(raw) {
  */
 export function buildCatalog(skillsDir, marketplacesDir = MARKETPLACES_DIR) {
   const entries = [];
-  const categories = buildCategoryMap(marketplacesDir);
+  const manifestEntries = buildEntryMap(marketplacesDir);
   const uncategorized = [];
 
   for (const dir of readdirSync(skillsDir).sort()) {
@@ -133,7 +146,7 @@ export function buildCatalog(skillsDir, marketplacesDir = MARKETPLACES_DIR) {
     const fm = parseFrontmatter(parts[1]);
     const body = parts.slice(2).join("---").trim();
 
-    const mapped = categories.get(dir);
+    const mapped = manifestEntries.get(dir);
     if (!mapped) uncategorized.push(dir);
 
     entries.push({
@@ -142,6 +155,8 @@ export function buildCatalog(skillsDir, marketplacesDir = MARKETPLACES_DIR) {
       triggers: fm.triggers,
       content: body,
       category: mapped?.category ?? FALLBACK_CATEGORY,
+      // Only when true, so off-by-default has one shape.
+      ...(mapped?.defaultEnabled ? { defaultEnabled: true } : {}),
       ...(fm.license ? { license: fm.license } : {}),
       ...(fm.compatibility ? { compatibility: fm.compatibility } : {}),
     });
@@ -160,14 +175,16 @@ export function buildCatalog(skillsDir, marketplacesDir = MARKETPLACES_DIR) {
 const isMain = process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1];
 if (isMain) {
   const entries = buildCatalog(SKILLS_DIR);
+  const defaultEnabledNames = entries.filter((e) => e.defaultEnabled).map((e) => e.name);
 
   const source = `// Auto-generated by scripts/build-skills-catalog.mjs — do not edit.
-// Source of truth: skills/*/SKILL.md and marketplaces/*.json (category)
+// Source of truth: skills/*/SKILL.md and marketplaces/*.json (category, defaultEnabled)
 export const SKILL_CATEGORY_IDS = ${JSON.stringify(SKILL_CATEGORY_IDS)};
 export const SKILLS_CATALOG = ${JSON.stringify(entries, null, 2)};
+export const DEFAULT_ENABLED_SKILL_NAMES = ${JSON.stringify(defaultEnabledNames)};
 export default SKILLS_CATALOG;
 `;
 
   writeFileSync(OUTPUT, source);
-  console.log(`Generated ${OUTPUT} with ${entries.length} skills`);
+  console.log(`Generated ${OUTPUT} with ${entries.length} skills (${defaultEnabledNames.length} default-enabled)`);
 }

package/skills/add-skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: add-skill
-description: Add an external skill from a GitHub repository to the current workspace. Use when users want to import, install, or add a skill from a GitHub URL (e.g., `/add-skill https://github.com/OpenHands/extensions/tree/main/skills/codereview` or "add the codereview skill from https://github.com/OpenHands/extensions/"). Handles fetching the skill files and placing them in .agents/skills/.
+description: Import an existing skill from a GitHub repository URL into the current workspace. Use only when the user provides or references a GitHub URL/repo to fetch from (e.g., `/add-skill https://github.com/OpenHands/extensions/tree/main/skills/codereview` or "add the codereview skill from https://github.com/OpenHands/extensions/"). Handles fetching the skill files and placing them in .agents/skills/. This does not author new skills — to create a new skill from scratch (no source URL), use the skill-creator skill instead.
 ---
 
 # Add Skill

package/skills/github-pr-reviewer/README.md

@@ -12,25 +12,31 @@ This skill is activated by:
 ## Features
 
 - Reviews PRs on demand by watching for a GitHub label event
+- Watches several repositories from a single automation, each with its own state
 - Processes each label application exactly once, with persistent state
 - Re-review support by removing and re-applying the label
 - Suppresses stale reviews when the PR head commit changes mid-review
-- Uses a real cloned checkout and full PR context instead of only a truncated diff
-- Posts acknowledgement and final review comments with AI disclosure
+- Hands the agent the reviewed commit already checked out, and removes that
+  checkout when the review ends, so nothing accumulates between runs
+- Publishes a real pull request review, with inline comments where a finding
+  maps to a changed line, and verifies on GitHub that it landed
+- Posts acknowledgement comments with AI disclosure
 - Configurable review tone and polling schedule
 
 ## Prerequisites
 
 Set `GITHUB_PERSONAL_ACCESS_TOKEN` in OpenHands Settings -> Secrets. The token
-must be able to read the repository, read pull requests, read issue events, and
-write issue comments.
+must be able to read the repositories and their contents, read issue events,
+write issue comments, and **write pull request reviews** — the review is
+published through the pull request reviews API, so read-only pull request access
+is not enough.
 
 ## Quick Start
 
 Ask OpenHands:
 
-> "Set up a PR review automation for my `myorg/backend` repo using the
-> `openhands-review` label and concise reviews."
+> "Set up a PR review automation for my `myorg/backend` and `myorg/frontend`
+> repos using the `openhands-review` label and concise reviews."
 
 After setup, apply the configured label to a pull request to queue a review. To
 request another review later, remove and re-apply the label.

package/skills/github-pr-reviewer/SKILL.md

@@ -2,23 +2,30 @@
 name: github-pr-reviewer
 description: >
   Create an automation that reviews GitHub pull requests when a configurable
-  trigger label is applied. Polls GitHub deterministically, starts one
-  OpenHands review conversation per label event, inspects full repository and
-  PR context, and posts the final review comment back to GitHub.
+  trigger label is applied. Polls one or more repositories deterministically,
+  starts one OpenHands review conversation per label event with the pull
+  request's head commit already checked out, and publishes the review to GitHub.
 triggers:
   - /pr-reviewer:setup
 ---
 
 # GitHub PR Reviewer Automation
 
-Create a cron automation that watches a GitHub repository for pull requests
-with a review trigger label, starts an OpenHands review conversation once per
-label event, and posts the AI review as a GitHub comment.
+Create a cron automation that watches one or more GitHub repositories for pull
+requests with a review trigger label, starts an OpenHands review conversation
+once per label event, and publishes the AI review to GitHub.
 Windows PowerShell equivalents for the setup, packaging, upload, and API-check shell snippets are in `references/windows.md`.
 
 The automation script is deterministic: PR discovery, label-event tracking,
-state persistence, stale-result suppression, and GitHub comment posting are
-handled in Python. The LLM is invoked only for the review itself.
+state persistence, stale-result suppression, the repository checkout, and its
+removal are all handled in Python. The LLM is invoked only for the review
+itself.
+
+The script prepares each review's workspace before the agent starts: the pull
+request's head commit is downloaded as a tarball and extracted to a directory of
+its own, which becomes the conversation's working directory. The agent is told
+not to clone, fetch, check out, or delete anything, and the script removes the
+checkout once the conversation has stopped. Nothing accumulates between runs.
 
 ---
 
@@ -31,7 +38,13 @@ Verify that the following secret is set in **OpenHands Settings -> Secrets**:
 | Secret name | Token type | Minimum permissions |
 |---|---|---|
 | `GITHUB_PERSONAL_ACCESS_TOKEN` | Classic PAT | `repo` for private repos or `public_repo` for public repos |
-| `GITHUB_PERSONAL_ACCESS_TOKEN` | Fine-grained PAT | Contents: Read, Metadata: Read, Pull requests: Read, Issues: Read and Write |
+| `GITHUB_PERSONAL_ACCESS_TOKEN` | Fine-grained PAT | Contents: Read, Metadata: Read, Pull requests: **Read and Write**, Issues: Read and Write |
+
+Pull-request **write** access is required because the agent publishes a pull
+request review, not just an issue comment. A token with only Pull requests: Read
+will poll happily and then fail at the point of publishing.
+
+When several repositories are monitored, the token must cover all of them.
 
 Check with:
 ```bash
@@ -57,12 +70,13 @@ Run the `curl` check above.
 - If the API returns `{"message": "Bad credentials"}`: tell the user the
   token is invalid and ask them to update it. Stop.
 
-### Step 2 - Collect repository
+### Step 2 - Collect repositories
 
-Ask: *"Which GitHub repository should be monitored?
-(Format: `owner/repo`, e.g. `myorg/backend`)"*
+Ask: *"Which GitHub repositories should be monitored?
+(Format: `owner/repo`, e.g. `myorg/backend`. List several separated by commas to
+review them all from one automation.)"*
 
-Validate access:
+Validate access to **each** repository:
 ```bash
 curl -s "https://api.github.com/repos/{owner}/{repo}" \
   -H "Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN" \
@@ -76,7 +90,13 @@ else:
 "
 ```
 
-Record `REPO = "{owner}/{repo}"`.
+Record every accepted repository into `REPOS = ["{owner}/{repo}", ...]`. If one
+repository fails the check, say which and ask whether to continue without it.
+
+Each repository is polled independently and keeps its own state, so pull-request
+numbers never collide between them. The trigger label, tone, and schedule are
+shared by all of them; a repository needing different settings wants its own
+automation.
 
 ### Step 3 - Collect trigger label
 
@@ -122,9 +142,15 @@ Record as `CRON_SCHEDULE`.
 Read `scripts/main.py` from this skill's directory. Apply exactly five constant
 substitutions near the top of the file:
 
+> The script also reads a `config.json` shipped beside it, if there is one, over
+> these constants. That is how the catalog entry
+> (`automations/catalog/github-pr-reviewer/`) configures an unmodified copy,
+> since a declarative host cannot rewrite Python. This setup path substitutes the
+> constants and ships no `config.json`, so the two never collide.
+
 | Placeholder | Replace with |
 |---|---|
-| `REPO = "owner/repo"` | `REPO = "{owner_repo}"` |
+| `REPOS = ["owner/repo"]` | `REPOS = ["{owner_repo}", ...]` - one entry per repository collected in Step 2 |
 | `TRIGGER_LABEL = "openhands-review"` | `TRIGGER_LABEL = "{trigger_label}"` |
 | `REVIEW_TONE = "thorough"` | `REVIEW_TONE = "{review_tone}"` |
 | `REVIEW_STYLE_INSTRUCTIONS = ""` | `REVIEW_STYLE_INSTRUCTIONS = "{style_instructions}"` |
@@ -132,6 +158,7 @@ substitutions near the top of the file:
 
 Use a safe string writer such as `json.dumps(value)` when inserting user-provided
 repository names, labels, or style instructions into Python string literals.
+`json.dumps(list_of_repos)` produces the whole `REPOS` list safely in one step.
 
 Write the customized script to a temporary build directory:
 ```bash
@@ -173,14 +200,19 @@ curl -s -X POST "${OPENHANDS_HOST}/api/automation/v1" \
   -H "X-Session-API-Key: $OPENHANDS_AUTOMATION_API_KEY" \
   -H "Content-Type: application/json" \
   -d "{
-    \"name\": \"GitHub PR Reviewer: {owner}/{repo} label {trigger_label}\",
+    \"name\": \"GitHub PR Reviewer: {repo_summary} label {trigger_label}\",
     \"trigger\": {\"type\": \"cron\", \"schedule\": \"{cron_schedule}\"},
     \"tarball_path\": \"$TARBALL_PATH\",
     \"entrypoint\": \"python3 main.py\",
-    \"timeout\": 300
+    \"timeout\": 600
   }" | python3 -m json.tool
 ```
 
+Use the single repository as `{repo_summary}` when there is one, and something
+like `3 repos` when there are several. A poll now downloads a tarball per queued
+review, so the timeout allows for that; a run never waits for a review to
+finish, only for it to be started.
+
 Record the returned `id`.
 
 ### Step 9 - Confirm
@@ -190,44 +222,67 @@ Tell the user:
 > ✅ **GitHub PR Reviewer** is running!
 >
 > - Automation ID: `{id}`
-> - Repository: `{owner}/{repo}`
+> - Repositories: `{owner}/{repo}`, ... (one line each)
 > - Trigger label: `{trigger_label}`
 > - Review tone: `{tone}`
 > - Polling schedule: `{cron_schedule}`
-> - State file: `~/.openhands/workspaces/automation-state/github_pr_reviewer_label_event_{id}.json`
+> - State file per repository:
+>   `~/.openhands/workspaces/automation-state/github_pr_reviewer_label_event_{id}_{owner}__{repo}.json`
 >
 > Apply the `{trigger_label}` label to a pull request to queue a review. Each
 > label event is processed once. To request another review, remove and re-apply
 > the label.
+>
+> The review is published as a pull request review on the head commit, with
+> inline comments where a finding maps to a changed line.
 
 ---
 
 ## Runtime Behaviour (per poll)
 
-Each cron run executes `main.py`, which:
+Each cron run executes `main.py`, which resolves and validates
+`GITHUB_PERSONAL_ACCESS_TOKEN` once, then processes every repository in `REPOS`
+independently. One repository failing does not stop the others; the run fails
+only if every repository fails.
+
+For each repository:
 
-1. Loads state from the JSON file (see `references/state-schema.md`).
-2. Resolves and validates `GITHUB_PERSONAL_ACCESS_TOKEN` and repository access.
+1. Loads that repository's state (see `references/state-schema.md`).
+2. Verifies repository access.
 3. Lists open PRs, newest-updated first.
 4. For each open PR carrying `TRIGGER_LABEL`:
    - Refetches current PR metadata to avoid acting on stale list data.
    - Finds the latest matching GitHub `labeled` issue event.
    - Skips the event if it has already been tracked.
-   - Starts an OpenHands conversation with a review prompt that includes PR
-     metadata, the exact head SHA, label event details, and instructions to
-     clone the repo, inspect PR discussion, review comments, changed files,
-     diff, and surrounding code.
+   - Downloads the PR's head commit as a tarball and extracts it to
+     `{WORKSPACE_BASE}/repositories/{owner}__{repo}/pr-{number}-{sha12}`. The
+     archive is checked as it is unpacked: a single root, no absolute or `..`
+     paths, and symlinks skipped rather than materialised.
+   - Starts an OpenHands conversation **whose working directory is that
+     checkout**, with a review prompt carrying PR metadata, the exact head SHA,
+     and label event details.
    - Posts an acknowledgement comment with the label event, head SHA, and
      conversation link.
-   - Records the label-event review in state with `status: "active"`.
+   - Records the review in state with `status: "active"` and the checkout path.
+   - If the checkout or the conversation cannot be created, the checkout is
+     removed and nothing is recorded, so the next poll retries the label event.
 5. For each active review conversation:
    - Marks it closed without posting if the PR has closed or merged.
    - Suppresses stale results if the PR head SHA changed after the review was
      queued.
    - When the conversation reaches `idle`, `finished`, `error`, or `stuck`,
-     posts the agent's final response as a GitHub comment and marks the review
-     closed.
-6. Saves state atomically and fires the completion callback.
+     asks GitHub whether a review by the token's own user exists for that head
+     SHA. If it does, the review is complete. If it does not, the agent's final
+     response is posted as a comment so the work is not lost.
+   - Abandons a conversation that has not reached a terminal status within two
+     hours, so its checkout can be reclaimed.
+6. Removes the checkout of every finished review, but only after confirming the
+   conversation has stopped - deleting it under a running agent would remove its
+   working directory. When that cannot be confirmed the directory is left alone
+   and the next poll tries again.
+7. Saves that repository's state atomically.
+
+The completion callback fires once for the whole run.
 
 ---
 
@@ -237,6 +292,9 @@ Each cron run executes `main.py`, which:
   review lifecycle diagram.
 - **`scripts/main.py`** - The complete automation script. Customize the five
   constants at the top before packaging.
+- **`tests/test_main.py`** - Unit tests for the checkout, its removal, and state
+  handling. Run them from the skill root with `python -m pytest tests/` after
+  editing the script.
 
 ---
 
@@ -246,7 +304,11 @@ Each cron run executes `main.py`, which:
 |---|---|---|
 | Bot never queues reviews | Trigger label not present or no matching `labeled` event | Apply the configured label to the PR |
 | "Bad credentials" in run logs | Token expired | Rotate and update `GITHUB_PERSONAL_ACCESS_TOKEN` |
-| 404 on repo access | Repo name wrong or no access | Re-check `owner/repo` and token permissions |
+| 404 on repo access | Repo name wrong or no access | Re-check the entry in `REPOS` and the token's permissions |
+| One repository is skipped, others work | That repository failed its access check | Read the `=== owner/repo ===` block in the run log |
 | Same PR not reviewed after new commits | Label event was already processed | Remove and re-apply the trigger label |
 | Review result never posts | Conversation still running or stuck | Open the conversation link from the acknowledgement comment |
 | Stale review suppressed | PR head SHA changed while the agent was reviewing | Re-apply the trigger label after the latest commit |
+| Review arrives as a plain comment, not a review | Publishing failed, so the script posted the text as a fallback | Check that the token has Pull requests: Read and Write |
+| Agent reports it cannot clone the repo | Prompt asked it not to; the workspace is already the checkout | No action - the code is at the head SHA in its working directory |
+| Checkouts remain under `repositories/` | Their conversations had not stopped yet | They are removed by a later poll once the conversation is terminal |

package/skills/github-pr-reviewer/commands/pr-reviewer-setup.md

@@ -1,6 +1,6 @@
 ---
 # auto-generated by sync_extensions.py
-description: Create an automation that reviews GitHub pull requests when a configurable trigger label is applied. Polls GitHub deterministically, starts one OpenHands review conversation per label event, inspects full repository and PR context, and posts the final review comment back to GitHub.
+description: Create an automation that reviews GitHub pull requests when a configurable trigger label is applied. Polls one or more repositories deterministically, starts one OpenHands review conversation per label event with the pull request's head commit already checked out, and publishes the review to GitHub.
 ---
 
 Read and follow the complete instructions in the SKILL.md file located in this skill's directory.