Control app: design

This text is LLM generated.

Status: proposal, revised 2026-09-25 after an independent fact-check.

Configured-session chat uses the existing ACP drawer through the service bridge. The pinned attach contract documented in service/README.md has no since-cursor replay contract; the bridge forwards ACP frames unchanged and stores no replay. The UI therefore never silently reconnects: close/error shows “Session ended” and explains that a new conversation needs the session server restarted. The listener admits one client and session/new returns its existing session; there is no fresh-conversation control or retry of a consumed destination. Prior text remains visibly ended, separated by provider even when another attachment fails; it is not evidence of recovered agent context. An unsent draft must be cleared or copied before changing providers.

Tracks cgwalters-bot/cgwalters-bot#8 and builds on the review-workflow part of the pivot plan (gist). Each Decision is a recommendation for cgwalters to accept or overrule. The questions for him are at the end.

Revision: the board is the backend (2026-09-25)

cgwalters decided against a new items repository: "the app can be public but yes we may have some private repos so we don't want to leak that. I think the backend could again be a project/issues/gist". So, for now, this replaces §1 (the items repository, its format, review-items, the board mirror and the migration). Auth, hosting, CSP, rendering and deploys (§2, §3) stand as written; the GitHub app comes first, Forgejo later.

Answers, and why the bot can trust them (revised 2026-09-26)

The bot's existing rule is that only the cgwalters login carries intent. Answers must therefore be something only that login can create. A comment is the simplest option: GitHub records its author.

The first version answered board draft items, which have no comments and whose edits are unattributed (DraftIssue and ProjectV2Item expose only a creator and updatedAt, with no edit history). So the app wrote the answer into the draft's public body and saved an unlisted gist under his account as a receipt for the bot to verify, with Q#n question ids and timing rules to reject replayed or stale answers. cgwalters found that weird, and it was: all of it existed only because drafts can't carry authorship. It is gone. Instead:

What the bot checks (in homegit, not in this repository): the comment is by cgwalters and was not edited by anyone else (people with write access can edit others' comments, so check userContentEdits editors, as bot-pr does for PR bodies), on an open question issue in the tracker that is assigned to him.

Reviews and chores: every Needs human item has an ask (2026-09-26)

cgwalters opened an upstream Needs human item (bootc-dev/bootc#2256) and the app said "Nothing to answer here": its Why held two asks, to re-approve a PR at a new head and to rerun two CI legs that lost their runner, and neither was a question. So every Needs human item now gets a tracker issue per ask, of one of three kinds, told apart by exactly one label: question (as above), review or chore. Each is an open issue in the tracker, opened by the bot, assigned to him, with the same Blocks: first line and sub-issue rule. He finishes any of them with a comment on it; only his login counts, and the bot then acts and closes it.

Auth changes

The relay and the cgwalters-review App stay as in §3; v0 ships the client side (see "Hosting v0" below). With answers as issue comments, the App doesn't need Gists permission; Contents write is not needed until PR review (v2).

Resolved (2026-09-30): the board was owned by the cgwalters-bot user, and GitHub Apps have no account-level Projects permission (discussion), so it moved to the cgwalters-forge org (cgwalters-forge/tracker#144), where an App with Projects write can update it. App user tokens reach only repositories where the App is installed, including the tracker and the forge; upstream repositories don't need write access now that answers never go there.

Plan, revised: v0 is the GitHub queue, the item view and answers, as above, in development mode. Next come the relay, the bot's answer check in homegit, and the App (created by you, with its secret installed by you on forge). PR review (§6 v2) and Forgejo follow.

Direction (2026-09-26)

cgwalters' stated goal, recorded as direction rather than a committed design; a separate design pass will follow:

Hosting v0: GitHub Pages and a pasted token (2026-09-26)

cgwalters asked for something usable now rather than after the relay and the tailnet host, so v0 is published on GitHub Pages (https://cgwalters-forge.github.io/review/) by a workflow on every merge to main, and you sign in by pasting a personal access token. This replaces the relay client and the loopback-only development mode above; the tailnet host, the cgwalters-review App and the relay (§3) remain the target, and would replace only src/github/auth.ts.

Since 2026-11-12 (tracker#1456, review#320) this is the serverless default: the Pages app needs no service. It reads the pass's publications and the Actions run lists from GitHub, and acts through GitHub as the operator: writes, workflow_dispatch, and job plans that the hosted pass dispatches. The supported sign-in is a pasted fine-grained token, read-only unless an action needs more. The OAuth device flow stays off: its endpoints send no CORS headers (§2), so a static page can't use it without a relay.

What this gives up, compared with §3:

Persistent cache (2026-09-26)

Every GitHub read is a conditional GET, and the board alone is about 1.1 MB in two pages that take GitHub 3 to 4 seconds to answer, 304 or not. So the app keeps its responses across reloads and renders from them first (stale-while-revalidate):

Summary

1. Source of truth

Replaced by the revision at the top: the Workstream board and tracker issues are the backend. The earlier proposal, an items repository of markdown files mirrored to the board, is in git history.

2. Static-site feasibility

GitHub Forgejo (your instance)
REST API from a browser Yes. api.github.com sends access-control-allow-origin: * and exposes ETag and the rate-limit headers (curl, 2026-09-25) Yes, with [cors] ENABLED=true (cors.go; /api always allows Authorization, per routers/api/shared/middleware.go)
PKCE S256 only, since 2025-07-14 S256 and plain, required for public clients (AuthorizeOAuth in routers/web/auth/oauth.go)
Code exchange without the secret No. client_secret is required even with PKCE (docs); GitHub "does not distinguish between public and confidential clients" Yes for apps not marked confidential (the secret is checked only for ConfidentialClient)
CORS on the token endpoint No. Preflight and POST to /login/oauth/access_token and /login/device/code return no Access-Control-* (curl). In #15752, staff said CORS on the token endpoint is not supported yet. roadmap#1153, "Single page app support for GitHub Apps [Preview]", was labelled Paused on 2026-08-13, and its plan caps SPA refresh tokens at possibly ~24h Yes, when [cors] is enabled. optionsCorsHandler() wraps /login/oauth/access_token (web.go). Its allowed headers are only [cors] HEADERS, so send client_id in the body, not Basic auth
Rewriting commits Git Data API No API: every git/* route is read-only except notes. Needs git smart HTTP with [repository] ACCESS_CONTROL_ALLOW_ORIGIN

Verdict:

Hosting: tailnet only.

3. Auth

GitHub: which token

Fine-grained PAT OAuth App token GitHub App user token (chosen)
Reach Selected repos of one owner All you can reach, by coarse scope The intersection of what you can reach and where the app is installed (docs), plus implicit read of public resources (docs)
Permissions Fine-grained Coarse The intersection of your permissions and the app's
Lifetime Up to a year Until revoked 8h, refreshable for 6 months, refresh token rotated on use (docs)
Attribution You You You, with the app's badge (docs)

Decision: a dedicated GitHub App, cgwalters-review, for user tokens only.

Create the cgwalters-review app

Settings → Developer settings → GitHub Apps → New GitHub App, owned by your user account (docs).

Does PKCE let a public client skip the secret? No, not on GitHub as of 2026-09-25.

The relay: a token-mediating backend

A single Rust binary (axum, reqwest) on the same origin as the static files. RFC 10017 (BCP 212, OAuth 2.0 for Browser-Based Applications) calls this pattern a token-mediating backend (§6.2). It is a confidential client that hands the application access tokens.

§6.2's trade-off: it "is less secure than a BFF". Injected script can't get at the refresh token or the session cookie, but it can steal the current access token, or "request a fresh token from the token-mediating backend" (§5.1.4). So the deciding defence is that no attacker-controlled script runs on the origin. That's why deployment and CSP below are not optional.

Endpoints:

The relay has no database and doesn't log tokens. Rotating the sealing key signs everyone out. The same code handles /auth/forgejo/* for relay-mode Forgejo.

Forgejo: the equivalent setup

ConfidentialClient is a per-application setting, so relay mode and static mode need two OAuth2 applications, created under Settings → Applications (docs):

App Confidential Redirect URI
cgwalters-review (relay mode) yes https://forge.<tailnet>.ts.net/review/auth/forgejo/callback
cgwalters-review-static no (PKCE mandatory) https://forge.<tailnet>.ts.net/review/forgejo/

Browser hygiene

Deployment and supply chain

The relay will mint a token acting as you for any script running on its origin (§6.2 above). So the served code is the security boundary:

4. Architecture

Two thin apps, one shared library

Decision: no general forge abstraction. Separate GitHub and Forgejo apps are fine, and simpler. The layout:

packages/items/   item format: parse, edit, round-trip (TypeScript)
packages/ui/      queue + item components (Preact), fed plain item data
apps/github/      GitHub client: REST + one GraphQL mutation, relay auth
apps/forgejo/     Forgejo client: REST + isomorphic-git, static or relay auth
relay/            review-relay (Rust)
crates/items/     item format + review-items CLI (Rust)
spec/             format spec fixtures, run by both test suites

Technology.

API use

Operation GitHub app Forgejo app
Poll items repo GET commits/{branch} with If-None-Match (304 is free) GET branches/{branch}, comparing the commit id (no ETags)
Read items git/trees/{sha}?recursive=1, git/blobs/{sha}; blobs cached forever by sha same paths
Answer or edit PUT contents/{path} with sha; retry on 409, 422 and 5xx same, and 5xx expected on a race
PR, commits, diff pulls/{n}, pulls/{n}/commits, Accept: application/vnd.github.diff pulls/{n}, pulls/{n}/commits, pulls/{n}.diff
Edit PR body PATCH pulls/{n} after rereading and comparing (no precondition) same
Reword and sign-off POST git/commits per commit, then GraphQL updateRefs with beforeOid (compare-and-swap; REST PATCH git/refs takes only sha and force) isomorphic-git: fetch the branch, rebuild the commits, push with force, and use onPrePush to cancel unless remoteRef.oid === expectedHead. force alone isn't a lease: the old value sent is whatever the server advertised at push time
/promote issue comment issue comment

Polling:

UI flows

  1. Queue: items needing you (needs-human, draft, unanswered questions, triage), grouped by priority and ordered by rank. Options answer in one tap, as in the prototype.
  2. Answer, or approve triage: one PUT writing only inside the answer markers, or the status line. The card shows "sent" at once, and "acted on" once the bot's Acted-on: commit arrives.
  3. PR review:
    • the rendered, editable description;
    • the commit stack, with per-commit diffs (ReviewStack-style navigation);
    • the CI summary;
    • each commit message editable in place, with a "Sign off" toggle that appends your Signed-off-by from review.yaml (in the items repo).
  4. Rewrite and sign off:
    • the app shows each message before and after, and checks that every tree is reused;
    • it writes new commits: author unchanged, committer you;
    • then a compare-and-swap ref update against the head you reviewed. If the bot pushed meanwhile, the update fails and your edits stay as drafts.
    • GitHub doesn't sign commits with a custom committer. Projects that require signed commits go through the CLI.
  5. Sign off and promote: step 4, then a /promote comment. bot-pr promote and its D6 sign-off gate do the rest.

Also from issue #8, placed in the plan:

Offline

5. Prior art

Project What it is Verdict
Gerrit NoteDb Review state as commits on refs/changes/XX/N/meta, with the state in footers (Patch-set:, Label:, Status:; ChangeNoteFooters.java) Borrow: state changes are commits with trailers, on a normal branch
Backlog.md Markdown tasks with front matter, a CLI/TUI, and a local web server. Active (v1.53.0, 2026-09-24) Loosely modelled on it; not compatible with its tooling. Its <!-- AC:BEGIN --> markers inspired our answer markers
git-appraise Reviews as JSON lines in git notes, merged with cat_sort_uniq. Dormant since 2023-08, not archived Borrow the append-only idea. Notes are invisible on both forges
git-bug An operation-based CRDT in JSON blobs under refs/bugs/, with a GraphQL server UI. The Forgejo bridge is a draft (#1628). Active (v0.11.0) Not a base: hidden refs, JSON, needs a server
Radicle Collaborative objects (issues, patches, reviews) under refs/cobs/, on its own peer-to-peer network Borrow the patch/revision/verdict vocabulary
Sapling ReviewStack A static React UI over GitHub GraphQL with per-commit stack review. It writes comments, reviews and labels, but can't rewrite commits. MIT, GitHub only Borrow its UX. Proof that a static review UI works
Sveltia CMS A static app committing markdown via the GitHub and Forgejo APIs, with serverless PKCE on Forgejo Borrow its auth approach
Pages CMS A Next.js app with Postgres Ignore: it has a lookaside DB
Utterances, Giscus Issues or discussions as the store. Utterances uses a Cloudflare worker; Giscus a GitHub App, with optional caching Ignore: the forge becomes the database

Decision: build new and small, borrowing the pieces above.

6. Plan

First PRs:

  1. spec: Define the work item format: docs/items-format.md and spec/fixtures/ (parse, round-trip, one-line-edit, answer-block edits).
  2. items: Add item parser and review-items CLI: the Rust crate with data-driven fixture tests; import, list, set.
  3. items: Import the Workstream board and the prototype queue: run once into the items repository, reviewed as one commit.
  4. web: Add read-only GitHub queue: packages/items (TypeScript, same fixtures), packages/ui, apps/github, CSP, and CI (typecheck, tests, cargo test).
  5. relay: Add GitHub App token relay: sealed cookies, PKCE, single-flight refresh, the systemd unit for the review user, and a signed-tag deploy script.
  6. items: Verify answers by push actor: review-items answered, with fixtures for forged-author and rebased-on-top cases.

Later (not in scope)

Codespace-on-devspace mode: trying a change live, browsing all of the code, and talking to an agent about it, on a devspace. Recorded here only as a direction. This design stays a lightweight client-side app.

Open questions for cgwalters

  1. Installs of cgwalters-review.

    • Is "Any account" acceptable? It gives the app a public install page, but it's unlisted in the Marketplace.
    • On cgwalters-forge: selected repositories (you add each new fork), or all repositories?
    • Workflows stays off unless you want it.
    • Install on bootc-dev and composefs?
  2. Your existing app, cgwaltersbot.

    • Confirm it stays the bot's identity only, never used for review.
    • Who owns it (your user or an org), and what's its install setting?
    • Are expiring user tokens on?

    This doesn't block the control app, but it matters for D1/D2 of the pivot plan. For cgwalters-review I need its client ID, and the secret installed by you on forge as the review user's credential, never through the bot.

  3. forge.

    • Its MagicDNS name.
    • Is the name appearing in Certificate Transparency logs acceptable?
    • Can a dedicated review user own the deployment, with the bot's user unable to read or write it?
    • Which key signs deploy tags?
  4. Sign-off identity: the exact Signed-off-by name and email.

  5. Your Forgejo.

    • Its version, and whether REQUIRE_SIGNIN_VIEW is on.
    • Are the [cors] and git-HTTP CORS settings acceptable?
    • Static mode, or relay mode (the default)?