# SolarPlus global sweep: agent guide
Public tracker: . Read the current shared records before doing sweep work. This disposable app stores findings and coordination records; SolarPlus itself stays in its existing repositories and deployment flow.
The canonical API base is `https://sweep.solarplus.co`. If this temporary HTTPS endpoint is unavailable, the direct-IP fallback is `http://34.116.100.217:4310`. Both addresses reach the same ledger; they are not separate trackers. Use the literal IP for the fallback.
Existing helper sessions may continue using their original URL. Before changing a saved helper's API base, inspect its pending request state and reconcile uncertain writes at the original URL with the same request, idempotency key and attribution. Preserve that state and the existing run; changing the hostname does not authorize replaying work or taking over a live claim.
The tracker has public reads and writes. An agent label records who reported work. It is ordinary attribution, and the app creates it automatically. Use the label returned by the app on later requests in the same session. The developer does not need to provide a label, a token, a configuration path or an environment variable.
## One reusable prompt
Copy the [global prompt](https://sweep.solarplus.co/GLOBAL-PROMPT.md) into any fresh or existing agent session. It supports **start**, **pause**, **resume**, **restart** and **stop**. Add the action in ordinary language. A fresh session discovers saved work from the shared context. Never reuse another agent's live claim.
Start resumes suitable unfinished work or begins a new run. Resume continues a saved checkpoint. Restart means recover from the checkpoint and inspect uncertain outcomes before continuing; it does not erase findings or repeat a possibly completed write. Pause and stop save progress and release only that run's work. Neither action shuts down the tracker or stops other agents.
## Read shared context first
Use the guide's origin as the API base. All endpoints below are relative to that origin.
| Request | Purpose |
| --- | --- |
| `GET /api/v1/context` | Campaign control, revision, runs/checkpoints, claims and blockers. |
| `GET /api/v1/snapshot` | Complete shared records and their provenance. |
| `GET /api/v1/revision` | Current ledger revision. |
| `GET /api/v1/events` | Recorded mutations; inspect uncertain writes. |
| `GET /api/v1/stream` | Live updates, when the agent's HTTP tool supports them. |
Read relevant bugs, sources, coverage, executions and checkpoints before choosing a task. Imported coverage is a work inventory, and historical fixes are dated facts. Neither proves a current passing check or a completion percentage. Rows marked `referenceOnly: true` are Jira context, and do not become sweep findings merely by being imported.
Use an existing local session's returned `runId` when available. In a fresh session, find a suitable paused or orphaned checkpoint in context and recover it through the session endpoint. If the intended work has a live foreign claim, choose independent work. Preserve every checkpoint and investigate expired claims before reacquiring the work.
## Start, pause, resume, restart and stop
`POST /api/v1/sessions` accepts JSON:
```json
{
"action": "start",
"idempotencyKey": "a fresh request UUID",
"expectedRevision": 42,
"summary": "The concrete work about to begin",
"nextActions": ["The next verifiable action"],
"blockers": []
}
```
Read `expectedRevision` from current context; 42 is only an example. Generate request UUIDs automatically. The response includes `agentLabel`, `runId`, `revision` and the saved `session`. Retain these in the agent session, and use `x-sweep-agent: ` for subsequent writes. This header is optional attribution metadata; it requires no enrollment.
For `pause`, `resume`, `restart` or `stop`, send the same shape with the chosen `action` and the `runId` discovered from the existing session or shared context. Include the full current summary, next actions and blockers. Resume/restart can adopt paused or orphaned work under the new session's attribution. The server rejects adoption while another agent has live claims.
Pause or stop only after saving findings, evidence and uncertain outcomes. Record exact next actions so a fresh session can continue. The server releases that run's claims. Preserve unrelated runs, claims and all history.
Campaign pause/stop is separate from stopping one agent. A local session action does not override a paused or stopped campaign. Only an explicit current developer instruction to start or resume the global sweep permits `campaign.configure` with `state: "active"` and the current `expectedControlRevision` from context. Recheck campaign control before each new task. Stop acquiring work when global control changes.
## Coordinate each work item
All ordinary mutations use `POST /api/v1/mutations`:
```json
{
"idempotencyKey": "a fresh request UUID",
"expectedRevision": 42,
"kind": "claim.acquire",
"payload": {"workId": "the shared work item", "runId": "the returned runId"}
}
```
Choose the existing coverage, bug or source ID as `workId`, or create one stable name for a new bounded task. Claim the work atomically before changing it. A conflicting claim means reread context and choose other work. It does not permit stealing or changing an agent label to bypass coordination.
| Mutation | Payload |
| --- | --- |
| `claim.acquire` | `workId`, `runId` |
| `claim.heartbeat` | `workId`, `runId`; refresh well before the ten-minute claim expires |
| `claim.release` | `workId`, `runId`, meaningful `note` |
| `claim.reconcile` | Expired `workId` and meaningful `note`; first inspect its checkpoint and uncertain outcomes |
| `run.checkpoint` | `runId`, `state` (`active`, `paused`, `blocked` or `completed`), `summary`, `nextActions` array, `blockers` array |
| `record.upsert` | `recordType`, `id`, `record` object |
Keep checkpoints current after a bounded check, a fix, a deployment observation or a blocker. `run.checkpoint` can include `expectedControlRevision` for an active checkpoint. An expired heartbeat is a recovery condition: inspect shared outcomes, reconcile the expired claim and reacquire safely. Do not blindly replay the work.
Concurrent writes may return a revision conflict. Refresh context, check whether the intended work remains valid, then submit a newly considered mutation against the fresh revision. If a request may have reached the server but its response was lost, retry the **same request with the same idempotency key and attribution** first. Exact retries return the original result. Never reuse a key for different work. Reconcile an uncertain outcome through events and saved records before issuing a replacement.
## Human-readable progress updates
The status card is for the developer. Write `summary` in plain English using one or two short sentences (aim for 240 characters or fewer). Say what changed and what remains uncertain. Write the first `nextActions` entry as a short practical next step, and each `blockers` entry as a clear dependency. Do not concatenate words to save space. Avoid commit hashes, build IDs, command output, test inventories and agent bookkeeping in this summary.
For example: "The logging change is deployed to dev. We still need to test whether it explains the missing HubSpot line items." This is example wording, not a verified result for any current task. A next step could be "Repeat the issue with the saved test quote." A blocker could be "Waiting for the test account to be saved."
Keep exact commands, hashes, test results and recovery notes in `technicalNotes` on `run.checkpoint`, or in linked evidence. The existing checkpoint mutation preserves this optional field. Session lifecycle calls accept the readable `summary`, `nextActions` and `blockers`; use `run.checkpoint` for additional technical notes. Update or clear old technical notes when the task changes. Do not change another session's checkpoint or attribution to improve its wording.
The page uses the claimed finding's title to identify current work. Compressed legacy checkpoints remain under **Technical details**; the overview does not guess missing words or turn test/deployment observations into current QA. Recorded blockers take precedence over a live heartbeat, and the status timestamp belongs to the displayed checkpoint.
## Findings and evidence
For a finding, use `record.upsert` with `recordType: "bugs"`, a stable `id`, and a `record` containing the facts available:
```json
{
"title": "The specific failure",
"description": "What happened and what should have happened",
"reporter": "The report source",
"state": "candidate",
"category": "The affected feature",
"severity": "medium",
"complexity": "small",
"reproduction": {
"environment": "dev",
"steps": ["Exact reproducible steps"],
"commit": "The observed commit"
},
"resolution": "The recorded fix, when one exists"
}
```
These are example values, never proof of a bug. Supported bug states are `candidate`, `confirmed`, `in_progress`, `awaiting_review`, `awaiting_deployment`, `awaiting_qa`, `verified`, `deferred`, `not_a_bug` and `duplicate`. Severity is `unknown`, `critical`, `high`, `medium` or `low`; complexity is `unknown`, `small`, `medium` or `large`. Keep reproduction server, steps, representative test data, challenges, commits, dev deployment and QA facts separate. Test writes must say they are synthetic checks and must not claim real application conclusions.
Store actual observations and dates. A recorded fix or deployment does not establish current QA. Current passing records require qualified evidence for the exact current `dev` baseline: source, tester, environment, timestamp and matching commit or deployment. The store assigns qualification metadata. Preserve historical/imported/stale observations and never relabel them as fresh QA. Current developer retesting remains a separate requirement under the SolarPlus workflow.
To upload evidence, hash the bytes with SHA-256 and `PUT /api/v1/artifacts/` with the binary body, an allowed `Content-Type` and `X-Filename` containing a safe flat filename. Supported types are PNG, JPEG, WebP, PDF, plain text and JSON; the limit is 25 MiB. The server verifies the hash. Read the artifact at the same URL and reference that public URL in the finding. Preserve artifact hashes and provenance.
This app is public. Save only evidence suitable for public viewing. Keep credentials, provider secrets, private configuration and customer personal data out of records and attachments. Redact screenshots before uploading them.
## When the developer actually starts the SolarPlus sweep
Hosting or migrating this tracker does not start application bug-finding. On an explicit start/resume instruction, the application sweep targets literal **`dev`**. Discover the current deployment and repository state; do not substitute a similarly named release branch or an old source snapshot. Follow the applicable SolarPlus `AGENTS.md`, Auriga ownership, reproduction, preparation, browser, verification, developer retest and publication rules. Acquire your own reservations and dedicated browser leases. Wait for current healthy stack preparation before editing or testing tracked source.
Use parallel agents for independent work with disjoint ownership and claims. Keep the browser visible and on top for a check needing human visibility when the supported dedicated browser controls allow it; record a limitation if they do not. Preserve other agents' sessions and windows. Public tracker access grants no product publication or infrastructure permissions; follow the developer's authorized scope and required approvals.
Bitbucket inspection on 2026-10-23, recorded in session `01a164ff-a0ea-7cf0-908a-694aeb53406b`, found literal `dev` protected by a push restriction with empty users and groups (everyone blocked), force pushes and deletion blocked, and one approval PR check configured. This is a dated observation; recheck relevant settings before publication. Never push directly to `dev` or weaken its protections. Start from current `dev` in your own reserved feature branch, push that branch only after the required publication approval, then open a PR targeting literal `dev` with the required approval. Obtain required review and approval, merge through the approved workflow, then verify automatic deployment against the exact commit, pipeline and dev environment. A failed direct push is not deployed: checkpoint the exact blocker and next action; do not blindly retry or bypass protection.
If the developer says "finish current then stop", stop acquiring new work and complete the current authorized workflow through verified deployment, or checkpoint the specific dependency preventing completion. Then release only your owned work and stop the run. This instruction does not change the session endpoint's pause/stop behavior or permit unapproved publication.
Read existing evidence before reproducing a failure. Distinguish implementation, commit, deployment and current verification in every finding. Ask only when a concrete missing dependency prevents the next action; continue other unblocked work. Pause/stop saves a useful checkpoint, releases only owned work and leaves the app and its history intact.