feat(automation): implement explicit agent source-repair commands

[seonghobae]

Purpose

Implement a real explicit source-mutation path without weakening review-agent semantics. @opencode-agent, @noema-agent, and @strix-agent remain review-only; mutation uses the dedicated @cwl-source-fix command and a separate central control-plane lane. A review mention is never counted as repair progress.

Architecture

This PR adds:

• scripts/ci/agent_source_repair.py: dedicated command parsing, live writer-permission revalidation, same-repository/non-protected-head enforcement, protected-base consumer policy, no-retroactive-command boundary, exact comment-body SHA-256 binding, complete paginated PR Files receipt validation, control-plane path exclusion, sealed edit scope, dispatch and acknowledgement receipt.
• scripts/ci/agent_source_repair_sweep.py: bounded organization sweep reusing the existing repository/comment discovery primitives.
• .github/workflows/agent-source-repair.yml: a separate scheduled dispatcher plus per-repository/PR serialized write worker. The worker uses only contextual-orchestrator/orchestrator/free, reuses the central CO sidecar and workspace-scope verifier, runs OpenCode without shell/web/credential access, revalidates authority and edit scope immediately before a normal non-force push, and never approves or merges.
• docs/automation/explicit-agent-source-repair.md: opt-in, command and trust-boundary specification.
• focused hostile-case and workflow contract tests.

No change is made to agent_mention_router.py, pr_review_fix_scheduler.py, Noema, Strix, provider discovery or merge policy. Appending fix or repair to a review-agent mention does not authorize source mutation.

Protected consumer opt-in

Source repair is disabled unless the exact protected base contains .github/cwl-agent-source-repair.json:

{
  "version": 1,
  "enabled": true,
  "not_before": "<rollout-time UTC timestamp>"
}

The not_before value prevents central deployment from executing historical source-fix comments. Missing, disabled, malformed, unknown-version or extra-field policy fails closed.

Mutation boundary

Admission requires all of the following at dispatch and again in the worker: dedicated first-line @cwl-source-fix command, human author, live write or admin permission, unchanged exact comment body, open PR, exact base/head identity, same-repository head, non-protected head branch, protected-base opt-in, and a complete PR Files receipt matching live changed_files.

The organization sweep prefilters bot/untrusted-association comments before it fetches the live PR object or enters source-command validation. This prevents an outsider comment from consuming live PR validation resources or turning an unrelated PR-fetch failure into source-repair scheduler failure. Trusted candidates still receive the complete live authority checks above.

The agent may modify only safe current-PR paths from that receipt. .github/, scripts/ci/, .git/, removed files and malformed/traversal paths are excluded. Workspace verification, git diff --check, changed-Python compilation, changed-YAML/YML parsing, final authority/scope revalidation, and exact live-head comparison all precede a normal commit/push. Force-push, self-approval, merge and branch-protection changes are absent.

RED → repair evidence

Initial RED eadca7f4a4eb8331db75fe5bd56d87dd29252b55 proved that adding fix/repair language to the current review-only mention did not create a source writer.

After ordinary reconciliation to protected main@828eaaefb0cc97bba4da63eb9270447476d26710, RED a03d372a0bc77bd0b951151df1e99a63a41835d4 required changed YAML/YML syntax validation before publication; GREEN 158511750c76d8ef729c1d8f34c0781bd21c6e21 added the runner-side Ruby/Psych parse and 599b01208cdc0b5f5f93a134672862a9c8b065f6 made the operational documentation code-current.

A second semantic RED 00fcf48b8f99c635df7efe274eba05c171318046 locked the intended boundary that review-agent handles stay review-only and only a dedicated mutation command can authorize writes. GREEN 1f8687dcc0e3a04cd9cc3b22ce55456454b3c43d implemented @cwl-source-fix as that command; 39426d9fd07e3a9a8a5936b164c80b6069727763 updated the operational contract.

Later sweep hardening added trusted-human prefiltering. Exact 651d9bb9f1b373da58f2fb89a072ab7312412765 still had both quality workflows fail at their repository-suite/coverage stage. Independent source inspection found one remaining resource-admission defect: even when every recent comment was untrusted, the sweep fetched the live PR before skipping those comments. fa01c54e02fde2687573c8086cd7409d4be6be1b moves live-PR fetch behind a non-empty trusted-comment set. 95105a4833d0638a785c5e199bf151956207ff11 strengthens the regression so an outsider-only candidate fails the test if any live-PR request is attempted, while also proving source-command parsing is never reached.

This fixes the verified outsider-resource boundary; it does not claim the earlier hosted quality failure is fully settled until fresh exact-head workflows finish.

Current gate

Current exact head: 95105a4833d0638a785c5e199bf151956207ff11, base main@828eaaefb0cc97bba4da63eb9270447476d26710, Open / Draft / mergeable.

Fresh Agent Source Repair Quality, Agent Mention Router Quality, Security/SAST/Python Security and CodeQL workflows were created for this exact head and are currently queued. Queued work is non-passing. Keep Draft until terminal exact-head hosted checks, independent review, owned production docstring/test/edge-case coverage at 100%, normal protected integration, and a post-integration BandScope opt-in live model-to-commit canary. No consumer is enabled by this PR alone.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[seonghobae]

Current-head RCA/fix evidence for the hosted quality RED:

• Previous exact head d676e8cdd6b4f07499d8b00986b4578886362247 failed both Agent Source Repair Quality (34768385789 / job 103753371580) and the repository-wide Agent Mention Router Quality (34768385605 / job 103753371283) during pytest collection.
• Both failures had the same deterministic cause: tests/test_agent_source_repair_workflow_contract.py imported yaml, while the hash-locked CI requirements used by these gates do not install PyYAML.
• Ordinary descendant 604658019eb50a2bbe13f8a59b2535efb66de4bd removes that undeclared runtime dependency. The workflow contract test now uses only stdlib text/indent structure to assert the exact two top-level jobs, serialized source-repair concurrency, and absence of a worker timeout. No production source, workflow behavior, permissions, or gate was weakened.
• Fresh exact-head hosted runs were triggered by the commit and are currently the authority; do not reuse the failed predecessor results.

Separate review note: GitHub's repository-permission endpoint deliberately maps the maintain role to legacy permission: write, so the current write|admin check is compatible with maintainers and should not be widened merely because another draft uses the role name.

[seonghobae]

Consolidation finding: three independent source-mutation implementations (#2173, #2174, #2175) share protected main@78393ea901efc0d57b35dd1e383e473425b7c1da as merge base and have diverged. To avoid a control-plane micro-PR fan-out, treat #2174 as the canonical owner candidate because it already carries the stricter protected-base opt-in / not_before replay boundary, control-plane path exclusions, exact base/head/comment revision binding, complete PR-files receipt, second authority/scope revalidation, credential-isolated orchestrator/free worker, and normal non-force push.

Before #2174 can become Ready, inspect and explicitly adopt or reject with evidence the unique semantic deltas from the siblings rather than closing them mechanically:

• feat(automation): add explicit bounded source-fix command #2175: dedicated mutation-only @cwl-source-fix command, durable exact-name Actions artifact ledger, canonical claim key, changed-YAML parse gate, and organization sweep behavior. Its hosted Source Fix Quality RED on 2e614690... exposed hashlib.compare_digest; ordinary descendant 1aed8784f2bf0e7e53144b10bc23e037bf4d1f27 now repairs that with hmac.compare_digest. Preserve this fix/evidence until successor carryover is verified.
• feat(automation): add bounded source-fix command lane #2173: compatibility UX for @opencode-agent fix|repair plus a mutation-only command and its workflow-contract evidence; inspect for any non-duplicated contract before supersession.

Do not close #2173/#2175 merely because #2174 is the preferred owner. Closure is valid only after every unique source/test/contract/evidence delta is either integrated into #2174 or explicitly proven redundant/invalid. Keep all three Draft until hosted exact-head checks and independent review establish which lineage is safe to consolidate.

[seonghobae]

Ordinary current-main reconciliation completed without force/rebase: temporary integration PR #2180 merged protected main@828eaaefb0cc97bba4da63eb9270447476d26710 into this branch, producing exact head f4d8f6048226fbd831e0065410c8321271bb4a11. The two intervening main commits are confined to the Noema document-reader lane; the source-repair delta remains the same seven files.

Canonical consolidation remains incomplete. Before Ready/merge, retain or explicitly reject with executable evidence the useful sibling contracts: #2175's mutation-only @cwl-source-fix UX / durable invocation identity and changed-YAML syntax validation, and #2173's compatibility-command contract. In particular, current #2174 validates changed Python with py_compile but does not yet syntax-validate changed YAML before commit; a malformed PR-authored YAML file is therefore still within the sealed editable set and could be committed by the writer. Treat that as a real validation gap, not as a reason to widen file authority or weaken fail-closed scope.

Fresh exact-head hosted checks were triggered by the reconciliation and are authoritative; predecessor checks do not transfer.

[seonghobae]

@opencode-agent review

Please review exact head 599b01208cdc0b5f5f93a134672862a9c8b065f6. Focus on the write-capable source-repair trust boundary, current-main reconciliation, complete PR-files scope, stale-head/permission/comment replay rejection, credential isolation, the new changed-YAML publication gate, and normal non-force push semantics. Submit concrete findings against this exact head; do not treat predecessor checks or sibling-PR evidence as current-head approval.

[seonghobae]

@noema-agent review

Review exact head 599b01208cdc0b5f5f93a134672862a9c8b065f6 as an independent control-plane reviewer. Check command/admission invariants, source-comment and base/head identity binding, complete authenticated PR-file scope, TOCTOU boundaries, model credential isolation, YAML/Python pre-publication validation, single-writer serialization, and normal non-force publication. Report only current-head findings.

[seonghobae]

@opencode-agent review

Please review exact head 39426d9fd07e3a9a8a5936b164c80b6069727763. The source contract changed after the previous request: @opencode-agent/@noema-agent/@strix-agent are now explicitly review-only, while only first-line @cwl-source-fix authorizes mutation. Check that separation, command parsing, replay/TOCTOU defenses, complete PR-files scope, credential isolation, YAML/Python publication gates, and normal non-force push behavior on this exact head.

[seonghobae]

@noema-agent review

Independent review requested for exact head 39426d9fd07e3a9a8a5936b164c80b6069727763. Verify that review-agent mentions remain non-mutating, @cwl-source-fix is the sole source-write command, and the current authority/scope/replay/TOCTOU/credential/YAML-validation boundaries fail closed without weakening normal review or merge gates.

[seonghobae]

Sibling-delta disposition on current canonical lane:

• feat(automation): add explicit bounded source-fix command #2175 @cwl-source-fix command: adopted. Current feat(automation): implement explicit agent source-repair commands #2174 keeps @opencode-agent / Noema / Strix review-only and uses the dedicated mutation-only command.
• feat(automation): add explicit bounded source-fix command #2175 changed-YAML parse gate: adopted before the second authority/head revalidation and normal push.
• feat(automation): add explicit bounded source-fix command #2175 durable Actions-artifact invocation ledger: not adopted as-is. That draft writes the 30-day claim artifact before mutation credentials, final live authority/scope validation, model execution, and publication. A transient credential/provider/runner failure after that claim converts a retryable repair into an at-most-once dead request until artifact expiry or a new human comment. feat(automation): implement explicit agent source-repair commands #2174 instead tolerates duplicate dispatch if acknowledgement publication fails, but serializes per repo/PR and revalidates the exact admitted head/comment/base/scope before every worker publication; a later duplicate fails closed once the first ordinary commit moves the head. Preserve feat(automation): add explicit bounded source-fix command #2175 until this liveness/safety tradeoff is independently reviewed; do not close it merely as duplicate.
• feat(automation): add bounded source-fix command lane #2173 @opencode-agent fix|repair compatibility syntax: explicitly rejected because it conflicts with the established review-only agent-handle contract and would make the same mention family both review and write-capable. Its direct @cwl-source-fix intent is now represented by feat(automation): implement explicit agent source-repair commands #2174. Any other unique test/workflow evidence still needs comparison before feat(automation): add bounded source-fix command lane #2173 can close.

Coverage finding also became actionable on #2174: the quality workflow claims statement/branch 100% for both new production modules while the earlier focused tests did not exercise the scheduler/runtime surface. Current descendants add hostile runtime and scheduler isolation suites; exact-head hosted coverage remains authoritative once a runner starts.

[seonghobae]

@opencode-agent review

Current exact head is 95105a4833d0638a785c5e199bf151956207ff11. Review the source-repair control plane as read-only evidence only. Focus on the new trusted-comment prefilter boundary: outsider/bot comments must not trigger live PR validation, command parsing, dispatch, or mutation authority; trusted commands must still receive full exact-comment/base/head/permission/policy/PR-files validation. Do not treat this review mention as source-repair progress.