Refreshing plugin categories

The Plugin Category Refresh GitHub workflow operates on production wry-manatee-359 using the existing Production environment credential. It never deploys code. First deploy the matching frontend and backend from main through the normal release workflow. Every operation verifies the exact deployed commit and public category vocabulary before proceeding.

Keep production deployments frozen for the whole refresh window. The SHA check is a preflight, not a global deployment lock. Apply starts an asynchronous migration: wait until status reports completion before allowing any deployment, and recheck status if an operation loses its response. The backend separately rechecks each row's classifier, pinned bundled assignment, latest release, and source hash. The operator should verify the deployed SHA around each wave.

Preview and review

Use a stable run ID for a complete traversal. A preview writes journal rows and may call gpt-5.6-luna; it does not change the categories people browse. The production OPENAI_API_KEY must exist and OPENAI_PLUGIN_CATEGORY_MODEL must be unset or gpt-5.6-luna. Status reports these checks as booleans, without secrets.

gh workflow run plugin-category-refresh.yml --repo openclaw/clawhub --ref main \  -f mode=status -f expected_sha="$DEPLOYED_SHA" -f run_id="$CATEGORY_RUN" gh workflow run plugin-category-refresh.yml --repo openclaw/clawhub --ref main \  -f mode=preview -f expected_sha="$DEPLOYED_SHA" -f run_id="$CATEGORY_RUN" \  -f max_pages=20 -f workers=3 -f cursor="$PREVIEW_CURSOR"

Each preview handles at most twenty pages of ten package rows, with at most four simultaneous actions. Pages can contain no plugins. Download the workflow's plugin-category-refresh-* artifact and use its resumeCursor for the next dispatch. On failure, that cursor stops before the first incomplete page, even if later pages completed. Reuse the same run ID: existing journal rows are skipped, never replaced. A request that lost its response might still finish on the server; wait for it to settle before retrying. Run one final traversal from the beginning with the same run ID to reconcile changes during enumeration. Each page preserves bounded package IDs and diagnostic reasons for skipped or failed entries, including entries that never produced a journal row.

Run mode=report with cursor/max_pages to export up to 2,000 journal rows per dispatch. Report cursors and preview cursors belong to different tables; do not interchange them. Inspect proposed categories, source, evidence, previous categories, version, and status. Fallback rows cannot be accepted; retry failed classifications under a new run ID. Existing author declarations, including valid legacy arrays, remain authoritative.

Choose at most 100 rows for a wave, starting with a small pilot. Use report with the JSON reviewed_ids array to get the exact selected rows and their reviewHash. The hash binds the release, source hash, classification, and category assignment. It intentionally excludes mutable journal status so it remains valid as that assignment moves from preview to accepted to applied.

gh workflow run plugin-category-refresh.yml --repo openclaw/clawhub --ref main \  -f mode=report -f expected_sha="$DEPLOYED_SHA" -f run_id="$CATEGORY_RUN" \  -f reviewed_ids="$REVIEWED_IDS_JSON" gh workflow run plugin-category-refresh.yml --repo openclaw/clawhub --ref main \  -f mode=accept -f expected_sha="$DEPLOYED_SHA" -f run_id="$CATEGORY_RUN" \  -f reviewed_ids="$REVIEWED_IDS_JSON" -f review_hash="$REVIEW_HASH"

Accept marks reviewed rows accepted and rehearses the first ten through a transaction that rolls back. Category state stays unchanged. A failed rehearsal leaves accepted rows available for inspection. Fresh generated previews must use classifier plugin-single-category-v3; bundled previews must match the pinned OpenClaw source commit and manifest hashes in the checked-out inventory.

Apply, monitor, and undo

Dispatch mode=apply with the same reviewed IDs and hash after a successful rehearsal. Apply repeats the first-ten rehearsal and verifies how many rows it processed, so a previous failed or lost rehearsal response cannot bypass this gate. The workflow requires every selected row to be accepted and refuses to start while another migration worker runs or any unreviewed accepted row exists. The shared migration worker applies batches of ten. Its accepted-row index covers all runs, so use this workflow as the sole operator during a wave.

Poll mode=status, then export mode=report. The component's processed count includes attempts; count actual applied and stale journal rows separately. The backend checks the latest release and evidence again when applying; changed rows become stale instead of overwriting newer work. Wait for the worker to finish and verify browse/detail output before starting another wave.

If a wave stops partway through, report and select only its remaining accepted rows, obtain their new review hash, and dispatch apply again. The workflow restarts the accepted index only when no worker is active. For rollback, report and select applied rows, then dispatch mode=rollback with those IDs and hash. Rollback refuses when a newer publication or category edit changed the applied state. After a partial rollback failure, report and select only the remaining applied rows before retrying. Keep the journal and downloaded artifacts until verification is complete; artifacts expire after thirty days.