Agent Labels

Agent labels

This page documents the label registry in src/labels.ts and src/stops.ts. Reimagined pipeline describes the caller-assigned workflow. Labels are visible status, not a substitute for signed state, exact revision receipts or fresh write authority.

Status labels

Label	Registry meaning
agent:working	The agent pipeline is working on this.
agent:needs-info	The agent pipeline asked a question.
agent:split	Split into agent sub-issues.
agent:merged	Merged by the agent pipeline.

The registry recognizes these labels; it does not imply that the executor discovers or splits issues. The caller owns issue selection and splitting. The Author asks needs-info questions; only trusted input can change the input revision. A code merge alone is not final security clearance or completed wiki publication.

Stop labels

A failed control adds agent:stopped-<code> and posts a comment naming the control, reason and recovery. stopFor chooses the first matching reason pattern; error catches the rest. Read that comment and signed state rather than inferring the exact failure from the label alone.

Code (suffix of agent:stopped-)	Registered control / meaning
user-harm	Security found harm to users, such as exposure, leakage or destruction of their data.
rights	Security found a violation of users' rights, such as privacy, consent or access to their data.
financial-harm	Security found financial harm to users or the operator.
abuse-risk	Security found abuse risk, such as missing auth/rate limits, privilege escalation or injection.
check-fixes	Configured check-fix attempts (maxCiFixes) did not produce passing checks.
no-ci	requireCi is enabled but the PR has no required CI checks.
not-doable	The issue cannot be done as written, or implementation changed neither code nor wiki.
branch-changed	The PR branch moved outside the pipeline.
wiki-check	Wiki validation failed.
conflict	Conflict-resolution attempts (maxConflictFixes) ran out or their result was rejected.
sync-limit	The base kept moving and maxSyncs was exhausted without merging.
push-rejected	GitHub rejected a branch push.
merge-refused	GitHub refused the merge or the pipeline could not confirm the merge result; code may already have landed.
error	A pipeline step, agent session or claim failed without a more specific match.

The registry also recognizes review-rounds and job for compatibility with saved labels. They do not define a review-round limit or automatic restart scheduler for this workflow. maxFixRounds is warned about and ignored; the caller must bound its own restart policy. Any label beginning agent:stopped- is recognized as a stop even if its code is absent from the registry. This recognition is not a new control or permission to resume.

wiki-check requires page links in changed wiki pages to resolve to existing pages. Every new page except Home and underscore-prefixed pages needs an incoming link from another page, such as _Sidebar. It checks page existence, not heading anchors or external URLs; review those separately.

Recovery meaning

A successful stop removes agent:working, applies the chosen stop label on issue and PR, closes live claims and clears the saved lease while preserving the resume stage and durable authority. Its merge-authored, editor-verifiable stopped state is reread before cleanup is considered complete. Stop-time login verification retries transient safe reads (four attempts, waits 2/4/6 seconds), never wrong accounts or HTTP 401, and never the requested mutation.

GitHub or identity failure can prevent a signed stop or its cleanup. In that case labels may still show working or only part of the intended stop; absence of a stop label is not evidence of success. The job writes runs/<slug>/issue-N/stop-recovery/<uuid>.json before attempting stop, recording reconciliation-required, the intended code, assigned branch/resume stage, original failure, stop failure and confirmed/unresolved effects. Explanations, signed state/lease, working-label removal, stop-label changes and claim closure are tracked separately. A lost response stays unresolved; required cleanup failure is not silently accepted. A fully confirmed stop records signed-stop-confirmed. Diagnostic fields are token-redacted before truncation.

If a signal interrupts stop, the job preserves this evidence and does not overwrite any possibly saved stop code/stage with its older working snapshot; reconcile unresolved effects before restarting.

Before restart, stop dispatch, retain that evidence and all remote code/private-wiki work and saved receipts, then read actual GitHub state/editor provenance, lease, claims and issue/PR labels. Reconcile every unresolved effect and the original failure under the configured identity. The local JSON is not signed state or restart authority. Removing labels or finding pushed commits does not manufacture missing hardening; existing saved-authority and exact-head checks still apply.

The caller owns restarts and must inspect the stop, saved state and recovery evidence first. Removing a label does not restore missing authority, fix checks or authorize a code push. Retain the repository/issue/branch/lane assignment; choose a restart stage from saved state and current inputs using the operator recovery procedure, not an automatic sweep or a reset of all limits. Safe provider/read rate limits or transport failures defer rather than stop, and require backoff. An uncertain merge mutation instead requires read-only reconciliation, never blind retry.

Unconfirmed saved merge attempts use bounded read-only confirmation: by default, a 90-second elapsed window with spaced backoff. Deadline expiry preserves the attempted repository, PR, target, authorized head, any saved successful result, original authorization and merged/security evidence. It blocks publication and completion, not a later explicitly authorized bounded merge recovery run with unchanged authority.

That later run reads saved evidence without repeating approval or the merge POST; neither lifting the stop nor rereading OPEN grants mutation authority. Never reset attempt evidence, merged truth or security state to obtain progress.

GitHub's default-branch closing keyword can close an issue before Merge finishes. That closure is not agent:merged or pipeline completion. The caller may canonically resume the same assigned branch with an eligible claimant when genuine merge-authored, editor-verified saved state is an incomplete Merge (including a stop resuming Merge), its recorded PR is freshly confirmed merged into the configured base, and GitHub does not contradict its saved merge provenance (including any attempted merge's repository, PR, target, branch, retained source head and saved successful response result). Only the winning claimant reopens it, using the review/merge identity; normal working/stop label handling then resumes. Closed issues with missing, malformed or untrusted authority, done/non-Merge state, no recorded PR or unconfirmed/contradicted merge evidence are refused without claim/state/working-label/reopen writes. Another live claimant and branch binding still apply.

Recovery does not fabricate an own-merge receipt or clearance. An exact saved own receipt retains its original hardening/integration and merged provenance. A confirmation race first reconciles saved attempt/response evidence; an exact successful HTTP response and original authorization may establish the missing own receipt. Without that successful response, recovery follows the independently authorized postmerge path, including hardening again where required. Neither path repeats the merge POST or pushes code. Actual-result checks and exact read-only Security must still pass before approved wiki publication and completion; completion labels both issue and PR agent:merged and closes the reopened issue as completed. There is no automatic retry scheduler.

Final security runs on the actual merged result. A security stop can therefore leave code already merged while wiki publication and completion remain blocked. It is not a rollback. Lifting the stop cannot reroll the same rejected revision: it re-stops without a model. Remediation may need a separate issue or operator action. Missing or stale clearance never permits completion.

Preserve local refused work and recovery artifacts. Job and shared session contract describes the recovery boundary; the source README gives operator procedures.