Issue 353: an agent off the control node cannot put a commit on the forge, and the forge tools' other gaps

2026-10-09 17:48:31 +02:00
1 changed files with 67 additions and 0 deletions
@@ -0,0 +1,67 @@
+---
+status: open
+opened: 2026-10-09
+located-in: []
+fixed-by:
+amended-design:
+---
+
+# 353. An agent cannot put a commit on the forge
+
+## Symptom
+
+On 2026-10-09, in an agent session on the operator's laptop, local times:
+
+- An agent finished a change to this repository's connectivity design on a branch, committed it in a
+  worktree, and ran `merge-check.sh`; all four checks passed.
+- `git push` was not possible: this repository's clone on the laptop has its push URL set to the literal
+  `DISABLED`. The laptop's clones of the mesh's code repositories push normally. Who set it, when, and
+  why is not recorded anywhere this session could find.
+- The forge's tools have no verb that pushes a branch or makes a commit. `gitea_api` refused
+  `POST /repos/{owner}/{repo}/diffpatch`, the forge's endpoint that applies a patch to a branch: *not a
+  write gitea_api makes* ([ADR 0266](../../02-DECISIONS/0266-on-the-control-node-agents-run-under-an-account-of-their-own-that-cannot-become-root-without-a-person.md)).
+- The one file write `gitea_api` allows is the contents endpoint, which takes the **whole file**,
+  base64-encoded. The changed design document is about 90 KB, so the call would carry about 121 KB of
+  base64 that the agent must reproduce character for character. That is not a workable path.
+
+The change waits for the operator to push it by hand. This report waits for the same push.
+
+## Why it is an issue
+
+- **The mesh's own rule for a change cannot be followed by an agent.** Every change goes through a branch,
+  a pull request and a person's approval. An agent off the control node can make the branch locally and
+  open the pull request through `gitea_create_pull_request`, but it cannot put the commits between the two
+  on the forge.
+- **Where no tool covers a need, none is worked around** ([ADR 0245](../../02-DECISIONS/0245-a-verb-says-what-it-replaces-and-the-agent-is-guarded-from-working-round-the-mesh.md)).
+  The only ways round are pushing to an explicit URL past the disabled one, or retyping a file as base64.
+  The first undoes a setting someone made on purpose. The second risks a commit that silently differs
+  from what was checked.
+- **The control node already has an answer the laptop does not.** On the control node the agent account
+  holds a forge key of its own, so its pushes are its own (ADR 0266). An agent on any other machine has
+  no equivalent.
+
+## Other gaps in the forge's tools
+
+Found by listing the forge module's 37 tools on 2026-10-09. Only the first one blocks work. The others
+can be done through `gitea_api`, which costs a raw call and a large answer each time.
+
+| Gap | Today | Checked |
+|---|---|---|
+| **No push, commit or patch on a branch** | blocked, as above | yes |
+| **No commit history or compare** | `GET …/commits` through `gitea_api`: about 100 lines of JSON for one commit, its author and committer printed in full each time. `gitea_contains` answers only whether one commit contains another. | yes |
+| **No reading a pull request's reviews or line comments** | `gitea_list_comments` returns the conversation only. Reviews and comments on lines need `GET …/pulls/{n}/reviews` through `gitea_api`. An agent asked to address review feedback does not see it unless it knows to ask there. No *approve* tool is right, since approval is a person's. | yes |
+| **No creating a branch** | `POST …/branches` through `gitea_api` | no |
+| **No editing an issue** — title, body, labels | only close and reopen exist | no |
+| **No listing a directory** | `gitea_get_file` reads one file | no |
+| **No code search across repositories** | none | no |
+
+*Checked* says whether this session called the raw endpoint and saw it answer. The rows marked *no* are
+read from the tool list and the forge's API, not tried.
+
+## Open
+
+- Who disabled the push URL on the laptop's clone of this repository, and whether it was meant to keep
+  agents from pushing here or was a step in something else.
+- Whether an agent off the control node should push with a forge key of its own, as on the control node,
+  or whether the forge module should take a commit as a patch and write it under the agent's account.
+  Either needs a decision record.