plans: row 199 design r6, answers duckworth-0026 B5 (ls-remote, push and helper use the derived fork) and B6 (URL parse in D9c), N10, N11 (#1697)

agents/megavolt/work/queue-199/DESIGN.md

@@ -21,6 +21,11 @@ found while building: D8 made `identity` required for every agent whose definiti
 step 2 says today's files load unchanged. Coder declares `gitea`, so r5 makes `identity` optional and
 `publish` require it (D8).
 
+r6 answers duckworth-0026 (REVIEW-r5.md at 3cb6888e1), with Mos's acceptance (mos-1043). B5: the derived URL
+has one name, `fork`, and D9a's `ls-remote`, step 5's push, the helper's host match, `checkPublish`'s result
+and step 6's event all use it (D9, D9a, D9b, T3). B6: the URL parse is written down (D9c) and tested (T3).
+N10 in D8 and T3. N11 in D9a and A3. N9 is carried to BUILD.md for the routing commit.
+
 ## 0. Terms
 
 - **Stack instance**: one Mosaic Stack deployment (row 190). It has one OS user, one config dir
@@ -123,7 +128,10 @@ doesn't pick. A pi model credential also waits for P19 #383.
 
 D8. **Identity.** A new business-file key, `roles.<agent>.identity = {name, email, gitea: {url, user}}`. It is
 optional, because today's business files with a `gitea` agent (coder) must load unchanged. `publish` (D9
-step 2) requires it, and requires that the definition declare `gitea`. The sandbox sets `GIT_AUTHOR_*` and `GIT_COMMITTER_*` from
+step 2) requires it, and requires that the definition declare `gitea`. A business file with a `publish`
+grant on an agent that lacks either refuses at load, and the error names `roles.<agent>.publish` and says
+"needs identity and a gitea definition" (N10). Load is the only place this is checked: a business file that
+fails it never reaches the bus. The sandbox sets `GIT_AUTHOR_*` and `GIT_COMMITTER_*` from
 it in place of E7's invalid domain. The email is the one Jason gives the agent's Gitea user, so Gitea links the
 commits to that user. Agents without `gitea` keep E7.
 
@@ -131,7 +139,7 @@ D9. **Push to a remote: a new git socket op, `publish`.** No new socket, no bund
 
 ```
 publish {"cap", "op": "publish", "task_ref", "project", "branch", "decision"}
-  -> {"ok": true, "result": {"remote", "ref", "commit", "previous"}} or a refusal
+  -> {"ok": true, "result": {"fork", "ref", "commit", "previous"}} or a refusal
 ```
 
 The host checks, in order, and each refusal goes through `broker.refuse()`:
@@ -156,13 +164,15 @@ The host checks, in order, and each refusal goes through `broker.refuse()`:
    without a decision, and `decision` is optional for a within-role class only.
 2. The project is in the agent's grant, `roles.<agent>.publish: [project]`, and the business file names the
    project's upstream repository, `projects.<project>.remote: "https://HOST/OWNER/REPO"`
-   (`remote-not-granted`). Its scheme is https and its host and port equal `identity.gitea.url`'s
-   (`remote-host-mismatch`). The default https port counts as 443 on both sides. The host never pushes to
-   that URL. It builds the agent's fork, `https://HOST[:PORT]/<gitea.user>/REPO`, from the upstream's
-   origin and repository name and the agent's own `gitea.user`, and pushes there. So the remote's owner is
-   the agent's own Gitea user on every push, by construction, and the agent can't name it (webby-0011 N1).
-   Gitea's refusal of a push to a repository the user doesn't own or collaborate on is the second layer.
-   An upstream whose owner is the agent's own user refuses `remote-not-fork`, at load and at push. `remote` is a new key
+   (`remote-not-granted`). Both URLs pass D9c's parse at load. The upstream's host and port equal
+   `identity.gitea.url`'s (`remote-host-mismatch`). The host never contacts that URL. It builds the agent's
+   fork, `fork = https://HOST[:PORT]/<gitea.user>/REPO`, from the upstream's origin and repository name and
+   the agent's own `gitea.user`. `fork` is the only URL the rest of `publish` uses: D9a's `ls-remote`, step
+   5's push, the helper's host match, `checkPublish`'s result and step 6's event. So the owner of the
+   repository that receives a push is the agent's own Gitea user on every push, by construction, and the
+   agent can't name it (webby-0011 N1). D9c is what makes "by construction" hold. Gitea's refusal of a
+   push to a repository the user doesn't own or collaborate on is the second layer. An upstream whose owner
+   equals the agent's `gitea.user`, compared without case, refuses `remote-not-fork`, at load and at push. `remote` is a new key
    beside `root` and `repo` (`business.mjs:186`), and `identity` and `publish` are new keys on a role entry
    (`business.mjs:89`). All three are optional, so today's business files load unchanged.
 3. The source is one commit, `C = context.pushCommit`. It is checked three ways, so all three are equal:
@@ -173,7 +183,7 @@ The host checks, in order, and each refusal goes through `broker.refuse()`:
    `validBranch(branch)` holds (`invalid-request`). The agent never names the destination ref.
 4. Every commit in `main..<work ref>` has author and committer email equal to `identity.email`
    (`identity-mismatch`).
-5. The push runs through `credentials.useFor(session, "gitea", ...)`: `git push <remote> <C>:<dst>`, by oid,
+5. The push runs through `credentials.useFor(session, "gitea", ...)`: `git push <fork> <C>:<dst>`, by oid,
    with no `+` and no `--force`. It never pushes by ref name, so a push to the working repo after
    `checkPublish` can't change what goes out (`non-fast-forward` from git stays a refusal). Git runs with E8's SAFE flags
    (`working.mjs:92-98`), which set `protocol.allow=never`. `publish` adds exactly two flags,
@@ -183,29 +193,53 @@ The host checks, in order, and each refusal goes through `broker.refuse()`:
    PATH from the host and sets the rest itself, so no proxy or `GIT_SSL_*` variable reaches git. `publish` takes a `tls` parameter that
    defaults to `[]`, the same way `push` takes `fsck = FSCK` (`working.mjs:100`). Tests pass
    `["-c", "http.sslCAInfo=<scratch CA>"]`. The host never sets it, and nothing in config or env reaches it. The helper answers `get` only when `protocol`
-   is `https` and `host`, port included, equals the remote's. It writes nothing for any other `get` and for
-   `store` and `erase`. `assertClean` checks git's output, so a remote that echoes the token gets
+   is `https` and `host`, port included, equals `fork`'s. It writes nothing for any other `get` and for
+   `store` and `erase`. `assertClean` checks git's output, so a fork that echoes the token gets
    `credential-leak`.
-6. The bus records `action.allowed` for `git.push.remote` with remote, ref and commit.
+6. The bus records `action.allowed` for `git.push.remote` with fork, ref and commit.
 
-D9a. **The remote must share root's history.** A push sends every object the remote lacks. The working
-repo's `main` is the project root's history (`working.mjs`, seed), so a remote that doesn't share it would
-receive all of root, landing squashes included. A project's `remote` must be root's upstream or a fork of it.
+D9a. **The agent's fork must share root's history.** A push sends every object the fork lacks. The working
+repo's `main` is the project root's history (`working.mjs`, seed), so a fork that doesn't share it would
+receive all of root, landing squashes included. The check runs on `fork`, never on the upstream: a related
+upstream says nothing about what the agent's `<user>/REPO` holds.
 `publish` runs `seed` first (`working.mjs:164-176`), under the repository's lock as `push` does, so `main`
 catches up with root before the check below. That means a fork also receives any landed root commits that
 upstream doesn't have yet, because they sit under the agent's work. That is expected: the agent's branch is
 built on them.
-Before the push, the host runs `git ls-remote` (same flags and helper) for the remote's default branch. It
-refuses `remote-unrelated` when the remote is empty or when that tip isn't a commit the working repo already
-has and an ancestor of `main`. Only `ls-remote` crosses the network for this, so nothing is fetched from the
-remote. If upstream has moved past root, the refusal stands until root catches up. That is a human pull into
-root, not an agent's.
+Before the push, the host runs `git ls-remote --symref <fork> HEAD` (same flags and helper). It refuses
+`remote-unrelated` when the fork is empty or when that tip isn't a commit the working repo already has and an
+ancestor of `main`. When `ls-remote` exits non-zero, for a fork that doesn't exist, a refused token or a
+network failure, `publish` refuses `fork-unavailable` and the push doesn't run (N11). Git's stderr isn't
+parsed to tell those apart and isn't returned, since it can carry the URL. Only `ls-remote` crosses the
+network for this, so nothing is fetched from the fork. If the fork has moved past root, the refusal stands
+until root catches up. That is a human pull into root, not an agent's.
+
+D9c. **The URL parse (B6).** `projects.<p>.remote` and `identity.gitea.url` are parsed with `new URL()` at load,
+and the business file refuses to load unless all of these hold:
+
+- The scheme is `https:`. There is no username, password, query or fragment.
+- The string equals its own normalized form: for the upstream, `url.origin + url.pathname`; for
+  `gitea.url`, `url.origin + "/"` or `url.origin`. So a dot segment (`/<user>/../OWNER/REPO`), a
+  percent-encoded dot, an upper-case host, an explicit `:443`, a backslash, userinfo, a query and a fragment
+  each refuse, because `new URL()` would change them (checked with node: each differs from its normalized
+  form). A trailing slash survives normalization and is refused by the two-segment rule below. The checks below run on that path, so the owner that is checked is
+  the owner that is used.
+- The upstream's path is exactly `/OWNER/REPO`: two non-empty segments, no more and no fewer. One trailing `.git` on
+  REPO is allowed and stripped. `fork` is built from the stripped REPO.
+- `OWNER`, `REPO` and `gitea.user` each match Gitea's name rule, `^[A-Za-z0-9_.-]{1,100}$` and not `.` or
+  `..`. REPO after stripping must still match.
+- `gitea.url`'s path is `/`. A Gitea served under a sub-path isn't supported by this row and refuses at load.
+- Host and port are compared after `new URL()` normalized them, and an omitted port counts as 443 on both
+  sides.
+- Gitea compares user and repository names without case (`lower_name`), so `remote-not-fork` compares the
+  upstream's OWNER with `gitea.user` without case. An upstream owned by `Coder` and a `gitea.user` of `coder`
+  would otherwise build a "fork" that is the upstream itself.
 
 D9b. **How `publish` reaches the broker and the store.** The git socket runs in the bus process
 (`cli.mjs:504-506`) and reaches the broker only through the host's op table (`bus/src/runtime.mjs:222-246`).
 `publish` adds three entries there, each wrapped in `refusing()`:
 
-- `checkPublish(cap, args)`: steps 1 to 3, including the decision check. It returns `{ticket, remote, user,
+- `checkPublish(cap, args)`: steps 1 to 3, including the decision check. It returns `{ticket, fork, user,
   email, source}` and no token. The ticket holds the session and the decision until `recordPublish`, the
   same way `checkLand` holds a landing.
 - `withGitea(cap, fn)`: `credentials.useFor(broker.session(cap), "gitea", fn)`. `fn` gets the token and runs
@@ -232,7 +266,7 @@ Token scopes for either: `write:repository` and `read:user`, nothing else, per v
 
 D11. **The host git socket.** `publish` is added to the socket. `push`, `fetch` and `land` don't change. The
 socket's bind rule (E4) adds `git.push.remote`. The working repo stays credential-free and remote-free. The
-remote URL is passed per call and never written into its config. A landing still squashes into the project
+`fork` URL is passed per call and never written into its config. A landing still squashes into the project
 root as "Mosaic bus host". Landings don't push anywhere.
 
 ## 6. Lifecycle (brief item 4)
@@ -277,7 +311,9 @@ Agents never mint accounts or tokens. Jason's steps, per agent that needs `gitea
   `gitea.user`. The email is the agent's `identity.email`.
 - A2. Create its token: sign in as that user, Settings, Applications, Generate New Token, scopes
   `write:repository` and `read:user`, nothing else.
-- A3. Create the fork of each granted repo as that user (O1).
+- A3. Create the fork of each granted repo as that user (O1). Gitea's push-to-create
+  (`ENABLE_PUSH_CREATE_USER`, `ENABLE_PUSH_CREATE_ORG`) stays off, so a push to a missing `<user>/REPO`
+  fails rather than creating a plain repository (N11). `publish` refuses `fork-unavailable` before that.
 - A4. On the stack instance's VM, as its OS user: `mosaic credentials issue AGENT gitea --rotate-by DATE`, with
   the token pasted into stdin.
 - A5. On fire or rotate: delete the token in Gitea (Settings, Applications), or disable the user.
@@ -333,20 +369,27 @@ All tests use scratch roots, fake tokens and a fake Gitea: `git http-backend` be
 - T3. The fake Gitea serves https on 127.0.0.1 with a cert from a scratch CA made by the test. It reaches git
   only through the `tls` parameter (D9 step 5). Each refusal test that should reach the network asserts that
   the first port received the request, so no test passes because git refused http first. `publish`: the
-  happy path lands `refs/heads/<user>/<branch>` on the fake remote, a fork that shares root's history, at
+  happy path lands `refs/heads/<user>/<branch>` on the agent's fork in the fake, which shares root's history, at
   exactly the decision's commit. Refusals for each step in D9, one test each, including `work-not-yours`. Until routing, a publish with
   no decision refuses, one with a decision for another task or commit refuses, and a second publish on a
   spent decision refuses `decision-consumed`. Approve while the latest push is A, push B, publish: refuses
-  `decision-mismatch`, and the remote receives nothing. A push to the working repo between `checkPublish` and
+  `decision-mismatch`, and the fork receives nothing. A push to the working repo between `checkPublish` and
   the git push doesn't change the commit that lands. A raise with no recorded push refuses `no-push`. A test pins that `git.push.remote` is in neither ROUTED list
   and that no `roles/*.json` grants it. A force-push attempt is
-  refused by git's non-fast-forward. A fake remote that answers 302 to a second 127.0.0.1 port: the push
+  refused by git's non-fast-forward. A fake fork that answers 302 to a second 127.0.0.1 port: the push
   fails, and the second port receives no request with an Authorization header. A remote on the right host
   and a different port is refused at step 2. Two agents granted one project each land on their own fork:
   agent A's push reaches `/<A's user>/REPO` only and B's reaches `/<B's user>/REPO` only, and the fake's
-  upstream repository receives nothing. An upstream owned by the agent's own user refuses `remote-not-fork`. A first publish to an empty remote and to an unrelated remote
-  each refuse `remote-unrelated`, and the fake remote receives no objects.
-- T4. Token handoff: the token never appears in argv, env, the remote URL, the working repo config,
+  upstream repository receives nothing. An upstream owned by the agent's own user refuses `remote-not-fork`,
+  and so does one whose owner differs from `gitea.user` only in case. With an upstream that shares root's
+  history, a first publish to an empty fork and to an unrelated fork each refuse `remote-unrelated`, and
+  neither fork nor upstream receives objects. A fork that doesn't exist refuses `fork-unavailable`, and the
+  fake records no push. `ls-remote` and the push each reach the fork's path only (the fake records every
+  path). Load refusals (D9c), one test each: a dot segment, an extra path segment, a missing segment,
+  a trailing slash, userinfo, a query, a fragment, an explicit `:443`, a name outside Gitea's rule, and a `gitea.url` with a
+  sub-path. A `.git` suffix loads and builds the fork without it. A `publish` grant on an agent without
+  `identity`, and on one whose definition lacks `gitea`, each refuse at load with the N10 message.
+- T4. Token handoff: the token never appears in argv, env, the fork URL, the working repo config,
   `changes.jsonl`, events or logs (scan every file under the scratch roots).
 - T5. Lifecycle: issue, rotate, revoke and delete, each live with no restart. After revoke, `publish` and the
   Vikunja path refuse `credential-unavailable`, and so they do after a bus restart that follows the revoke.
@@ -359,8 +402,10 @@ check, allow a `{file}` reference into another agent's dir, make ENOENT on a `st
 ENOENT on a `{file}` path silent, a helper that answers any host, drop `http.followRedirects=false`, drop the
 `work-not-yours` check, drop the `remote-unrelated` check, add `git.push.remote` to ROUTED, skip the spent
 check on the decision, drop the `pushCommit` comparison in `#authorityFor`, push by ref name in place of the
-oid, push to the upstream URL in place of the derived fork, take the fork's owner from anywhere but the agent's
-`gitea.user`, skip the tip check under the lock, and pass a CA flag in production.
+oid, push to the upstream URL in place of the derived fork, run `ls-remote` against the upstream in place of
+the fork, take the fork's owner from anywhere but the agent's `gitea.user`, compare the owner with case, run the
+D9c checks on the raw path in place of the normalized one, read a failed `ls-remote` as empty, skip the tip
+check under the lock, and pass a CA flag in production.
 
 ## 12. Risks