chore(plan-exec): 2026-07-16-github-trigger-on-pluggable-app-free-auth — phase "Phase E: Specs, rules, docs" passed gates

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NGgfho2J6YfRSQN1bSDhj6

Author: edgehero

.env.example

@@ -21,3 +21,17 @@ PI_CONCURRENCY=3       # how many jobs run in parallel
 VALKEY_URL=redis://127.0.0.1:6379
 PI_JOB_IMAGE=pi-job:latest          # the image you built:  docker build -f image/Dockerfile -t pi-job:latest .
 # PI_JOBS_DIR=                      # where per-job /job inputs live (default: your OS temp dir)
+
+# --- GitHub trigger (receiver + worker auth) ---
+# Webhook receiver
+WEBHOOK_SECRET=
+RECEIVER_PORT=3000
+RECEIVER_BIND=0.0.0.0
+# Worker GitHub auth: source is gh | pat | app (default gh)
+GITHUB_AUTH_SOURCE=gh
+# For GITHUB_AUTH_SOURCE=pat: a repo-scoped, short-expiry fine-grained PAT
+GITHUB_PAT=
+# For GITHUB_AUTH_SOURCE=app (optional; required for multi-tenant)
+GITHUB_APP_ID=
+GITHUB_APP_INSTALLATION_ID=
+GITHUB_APP_PRIVATE_KEY_PATH=

README.md

@@ -73,17 +73,19 @@ pi-dispatch run ── enqueue ──▶ Valkey + BullMQ ──▶ worker (on yo
 
 Read [`SECURITY.md`](SECURITY.md) before you rely on it — it states plainly what is and is not defended.
 
-## Advanced: GitHub automation *(in progress)*
+## Advanced: GitHub automation
 
 pi-dispatch can also be triggered by GitHub — label an issue, and a container works it on a fresh clone,
-opens a PR, and comments back. This path needs a **GitHub App** and is **not yet built** in this
-repository; the local-folder path above is complete. When it lands:
+opens a PR, and comments back. A repo **webhook** drives it (set a `WEBHOOK_SECRET`), and the worker
+authenticates to GitHub via `GITHUB_AUTH_SOURCE`: `gh` (a `gh auth token`) or a repo-scoped fine-grained
+**PAT** by default. A GitHub **App is optional** — it buys stronger token scoping and is what you need
+for multi-tenant.
 
 - Only a collaborator's label or `@pi` comment starts a job (the label *is* the approval step).
-- The agent gets a **1-hour, single-repo token** — and, honestly: that token *can* merge, because GitHub
-  gates push and merge behind the same `contents: write` scope. **Branch protection on your default
-  branch is the real control**, so the worker will refuse an unprotected repo. `SECURITY.md` has the
-  detail.
+- The agent gets a **repo-scoped, short-lived token** — and, honestly: that token *can* merge, because
+  GitHub gates push and merge behind the same `contents: write` scope. **Branch protection on your
+  default branch is the real control**, so the worker **refuses** an unprotected repo. `SECURITY.md` has
+  the detail.
 - A separate **admin panel** on `127.0.0.1` (never on the internet-facing receiver) will turn the queue
   on/off, show jobs, and set the model/budgets. It will not edit your persona or skills — those live in
   your project's `.pi/`, in git, reviewed.
@@ -99,8 +101,9 @@ minutes.
 
 ## Status
 
-The local-folder path (image, worker, `pi-dispatch run` / `worker`) is built and works. The GitHub
-webhook path, the admin panel, and scheduled (cron) triggers are in progress. The design is specified in
+The local-folder path (image, worker, `pi-dispatch run` / `worker`) and the GitHub webhook path
+(receiver → queue → clone → PR) are built and work. The admin panel and scheduled (cron) triggers are in
+progress. The design is specified in
 [`specs/`](specs/) — start with [`specs/constitution.md`](specs/constitution.md) for the non-negotiables
 and [`specs/design.md`](specs/design.md) for the decisions and what was rejected.
 

SECURITY.md

@@ -64,12 +64,13 @@ Jobs are a **trigger × target** matrix, and the triggers do not share a threat
 - **Isolation.** One ephemeral container per job: `--cap-drop=ALL`, `--security-opt no-new-privileges`,
   memory/CPU/pids limits, non-root, `--rm`. Per-job rather than per-session, so state cannot leak
   between mutually-untrusting issue authors.
-- **Credential scope.** A GitHub App installation token minted per job: one repository, one hour. The
-  expiry and the single-repo scope bound **where** an injected agent can act — not **how much**, within
-  that repo. See *What is NOT defended*.
-- **CI integrity.** The token is minted **without** the `workflows` permission, which is a separate scope
-  from `contents`. An injected agent therefore cannot rewrite `.github/workflows/` even though it can
-  write code. This one holds.
+- **Credential scope.** A repo-scoped, short-lived token minted per job — a GitHub App installation
+  token, or a single-owner fine-grained PAT. Its narrow scope and short expiry bound **where** and for
+  **how long** an injected agent can act within that repo. See *What is NOT defended*.
+- **CI integrity.** The token is minimally-permissioned — `contents` and `pull-requests`, **not**
+  `workflows`, which is a separate scope. For a fine-grained PAT this is an operator-set property. An
+  injected agent therefore cannot rewrite `.github/workflows/` even though it can write code. This one
+  holds.
 - **Branch protection is required.** The worker refuses to run against a repository whose default branch
   is unprotected, checked before any money is spent. This is the control that makes human review real
   rather than customary — without it, nothing technical stops a merge.
@@ -82,9 +83,9 @@ Jobs are a **trigger × target** matrix, and the triggers do not share a threat
   a pull request cannot change them. Baked guardrails are read from a path the project cannot influence.
 - **We never merge.** No code path in this project calls a merge API; grep is the test. Note carefully
   what that does and does not mean — see below.
-- **Spend.** A daily cap checked *before* tokens are spent, plus a per-job turn budget enforced by our
-  runner (pi has no turn limit of its own). An agent that concluded "I can't fix this" is a success and
-  is never blind-retried.
+- **Spend.** A daily cap checked *before* tokens are spent, a per-job turn budget enforced by our runner
+  (pi has no turn limit of its own), and a 30-minute container wall-clock timeout. An agent that concluded
+  "I can't fix this" is a success and is never blind-retried.
 
 ## What is NOT defended (v1)
 
@@ -112,7 +113,7 @@ Stated openly rather than discovered later:
   removing the human who would have noticed.
 - **Network egress from the job container is unrestricted.** There is no allowlist proxy in v1. A job
   can reach the internet. If an agent is successfully induced to exfiltrate its environment, egress
-  filtering will not stop it — the scoped token's one-hour expiry is what bounds the damage. Run this on
+  filtering will not stop it — the token's short expiry and narrow scope are what bound the damage. Run this on
   hardware where that is acceptable, or put an egress policy on the Docker network yourself.
 - **The provider API key is broad.** Unlike the GitHub token it cannot be meaningfully scoped per job —
   the agent needs it to function. It is the one broad secret inside the container. **Set a spend limit

specs/constitution.md

@@ -256,16 +256,28 @@ that always fires is one nobody reads.
 
 ## CONST-TOKEN-SCOPED-PER-JOB
 
-- **Statement**: Each job shall receive a freshly minted GitHub App installation token, scoped to one
-  repository, expiring in one hour. No long-lived PAT shall enter a container.
-- **Why**: The one-hour expiry **is** the blast-radius bound for the case where an injected agent
-  exfiltrates its environment — which is a *when*, not an *if*. A PAT makes one successful injection
-  permanent and multi-repo. The provider API key is the acknowledged exception: it cannot be scoped
-  because the agent cannot function without it, so it is bounded by a provider-side spend limit instead
-  of by scope. That asymmetry is deliberate and documented rather than pretended away.
+- **Statement**: The container git credential shall be **repo-scoped** (reaching only the serviced
+  repository), **minimally-permissioned** (contents + pull-requests only), **short-lived**,
+  **host-held** and **env-injected** (never written to an agent-reachable file), and **not
+  merge-capable in practice** (branch protection is the barrier — see `CONST-MERGE-NEVER-AUTOMATIC`).
+  A freshly-minted GitHub App installation token satisfies these properties. A tightly-scoped,
+  short-expiry **fine-grained** PAT satisfies them for a **single-owner** deployment. A **broad or
+  long-lived classic PAT does not** and shall not enter a container. The App path remains strictly
+  stronger on the token axis and is **mandatory for multi-tenant** deployments — a fine-grained PAT is
+  per-account and cannot isolate mutually-distrusting owners.
+- **Why**: The credential's short **expiry** — not its capabilities — is the blast-radius bound for the
+  case where an injected agent exfiltrates its environment, which is a *when*, not an *if*. A broad,
+  long-lived classic PAT makes one successful injection permanent and multi-repo, which is why it is
+  excluded. The provider API key is the acknowledged exception: it cannot be scoped because the agent
+  cannot function without it, so it is bounded by a provider-side spend limit instead of by scope. That
+  asymmetry is deliberate and documented rather than pretended away.
 - **Traces to**: `CONST-ISOLATION-CONTAINER-PER-JOB`, `INT-CONTAINER-RUNTIME-CONTRACT`
-- **Acceptance**: No container environment contains a credential valid beyond one hour or beyond one
-  repository, except the provider key.
+- **Acceptance**: (a) **Code-checkable** — no container environment holds a credential that is
+  broad-scope or long-lived; the App path scopes the token to exactly one repository; the token is
+  env-injected and never written to `/workspace`, `.git/config`, argv, or logs; no acceptance clause
+  mandates a specific expiry duration. (b) **Operator obligation** — a single-owner deployment must
+  supply a repo-scoped, minimally-permissioned, short-expiry fine-grained PAT (or use the App); a broad
+  or long-lived classic PAT is non-conformant. Multi-tenant deployments must use the App.
 
 ## CONST-PI-VERSION-PINNED
 
@@ -291,3 +303,4 @@ that always fires is one nobody reads.
 |---|---|
 | 2026-07-15 | Initial. Extracted from `DESIGN.md` v0.1 (2026-07-14, local, uncommitted). That document recorded "50 claims adversarially verified: 48 confirmed, 2 refuted" — but verified **against documentation**. Source-verification at `earendil-works/pi @ 5e336cf` subsequently corrected ~7 points, two of them architecture-breaking. Hence the evidence convention above: source is authoritative, docs are a hint. |
 | 2026-07-15 | `CONST-NO-CONTEXT-FILES-MANDATORY` amended: it named only the CLI flag (`-nc`), but the runner uses the **SDK**, where the mechanism is `noContextFiles: true` on a caller-constructed `DefaultResourceLoader` — and it is **off by default**. The constraint therefore fails **open by omission**: there is no flag to forget, there is an entire object to forget to build. Statement and Evidence corrected; Acceptance unchanged (it was right; the named mechanism was wrong). This is the distinction the evidence convention exists to catch — the *requirement* was verified, the *mechanism* was assumed. |
+| 2026-07-17 | `CONST-TOKEN-SCOPED-PER-JOB` amended: Statement, Why, and Acceptance rewritten from a single-mechanism mandate (App installation token with one fixed expiry duration) to mechanism-neutral **required properties** — repo-scoped, minimally-permissioned, short-lived, host-held, env-injected, not merge-capable in practice. The App path satisfies them and stays **mandatory for multi-tenant**; a tightly-scoped short-expiry **fine-grained** PAT satisfies them for **single-owner**; a broad or long-lived classic PAT is excluded. The bound is the token's **expiry**, not a fixed duration — no acceptance clause mandates one. Provider-key exception preserved unchanged. |

specs/interfaces.md

@@ -356,7 +356,7 @@ Evidence convention as in `constitution.md`.
     reaps nothing. Chromium spawns many processes; zombies accumulate against `--pids-limit` until the
     job dies of something unrelated to its actual work.
   - Env **passed by the worker**: the configured provider's key variable(s), derived — not hardcoded
-    (see below); `GITHUB_TOKEN` (scoped, 1h — GitHub-backed jobs only); `PI_JOB_ID`; `PI_PROVIDER`;
+    (see below); `GITHUB_TOKEN` (scoped, short-lived — GitHub-backed jobs only); `PI_JOB_ID`; `PI_PROVIDER`;
     `PI_MODEL`; `PI_MAX_TURNS`; `PI_CODING_AGENT_DIR` (if not `$HOME/.pi/agent`)
   - Env **baked into the image**, because they are facts about the image and not choices a job makes:
     `PLAYWRIGHT_BROWSERS_PATH=/ms-playwright`, `PLAYWRIGHT_MCP_BROWSER=chromium`,

specs/open-questions.md

@@ -53,7 +53,7 @@ Status values: `OPEN` (unanswered) · `WATCH` (not a question — a known-incomi
 
 - **Status**: **ACCEPTED RISK** — *wants explicit ratification*
 - **Position**: v1 ships without an allowlist proxy. A job container can reach the internet. The bound
-  on exfiltration is `CONST-TOKEN-SCOPED-PER-JOB`'s one-hour expiry, not network policy.
+  on exfiltration is `CONST-TOKEN-SCOPED-PER-JOB`'s short-lived, minimally-permissioned credential, not network policy.
 - **Why it is a risk row and not a constraint**: the source design doc listed egress allowlisting as
   security "layer 4" while also saying v1 ships without it. **A constraint that ships unenforced is worse
   than an honest open risk** — it teaches readers that the constitution is aspirational, which corrodes
@@ -97,6 +97,25 @@ Status values: `OPEN` (unanswered) · `WATCH` (not a question — a known-incomi
   `earendil-works/pi @ 5e336cf → CHANGELOG.md:5-10` (`[Unreleased]`) · `→ sdk.ts:33-80`
   (`modelRuntime?: ModelRuntime` present **on main only**) · `→ sdk.ts:171` (async `ModelRuntime.create`)
 
+## OQ-006 — Which GitHub auth mechanism is the default, and when is an App required?
+
+- **Status**: **CLOSED — default `gh` / fine-grained PAT for single-owner; App for multi-tenant**
+- **Answer**: The default `GITHUB_AUTH_SOURCE` is `gh` (or a repo-scoped, short-expiry fine-grained PAT)
+  for a single-owner deployment. The GitHub App path is optional, strictly stronger on the token axis
+  (true per-repo scoping, shorter expiry), and **mandatory for multi-tenant** deployments — a
+  fine-grained PAT is per-account and cannot isolate mutually-distrusting owners. A broad or long-lived
+  classic PAT is non-conformant either way. This is the property set `CONST-TOKEN-SCOPED-PER-JOB`
+  enumerates; the App is no longer a hard prerequisite for running GitHub jobs.
+- **Why it was an open question**: the original design assumed a GitHub App was mandatory. Research
+  found no GitHub requirement forcing an App for a single-owner tool, and `@octokit/auth-app` shipped
+  declared-but-unused — so the mechanism was undecided in practice while the docs implied App-only.
+- **What closed it**: this plan (the pluggable `makeGitHubAuth(pat|gh|app)` resolver) plus the E1
+  amendment of `CONST-TOKEN-SCOPED-PER-JOB` from App-mandatory/one-hour to mechanism-neutral required
+  properties. Recorded here so the decision is durable and greppable rather than buried in a closed PR.
+- **Related risk**: `OQ-004` (unrestricted egress) is the reason the credential mechanism matters — the
+  token's short expiry, not network policy, is the exfiltration bound, so the mechanism must keep that
+  expiry short and the scope narrow. `OQ-004` remains **ACCEPTED RISK** (unchanged by this entry).
+
 ---
 
 ## Retired from the source design document
@@ -135,3 +154,4 @@ adversarial passes did.
 | 2026-07-15 | Initial. Replaces `DESIGN.md` v0.1 §10. Collapsed from ~10 checklist items to 5 rows: source-verification at `earendil-works/pi @ 5e336cf` answered most of them. The register's value inverted in the process — from "holds ten unknowns" to "holds one known-incoming breaking change" (`OQ-005`). |
 | 2026-07-16 | `OQ-005` **retracted and re-corrected** to `WATCH — NOT IN THE PIN`. The 2026-07-15 "correction" below was itself wrong: it read `sdk.ts` at `5e336cf` (**HEAD**) to describe npm `0.80.7` (**the pin**), concluded `modelRuntime` had already landed, and declared the changelog unreliable. `ModelRuntime` does not exist in `0.80.7` — no `model-runtime` in its `dist/`, not exported from `dist/index.js`. The changelog said `[Unreleased]` and was exactly right. The runner was written against the phantom API, the image built cleanly, and every job would have died on a missing export; CI caught it on the first real container run. `constitution.md`'s evidence convention now requires verification against the **published artifact**, and `pinned-api.test.mjs` asserts `ModelRuntime` is absent so the real migration fails a test instead of a job. |
 | 2026-07-15 | ~~`OQ-005` corrected to **WATCH — PARTIALLY LANDED**~~ — **this entry was wrong; see above.** It claimed `modelRuntime` was already in `CreateAgentSessionOptions` at the pinned sha and that the changelog was not a reliable signal. Both false: the sha was HEAD, not the pin. Kept rather than deleted, because a spec that hides having been wrong teaches the next reader to trust it more than it deserves. |
+| 2026-07-17 | Added OQ-006 recording the GitHub-auth-mechanism decision (default gh/fine-grained PAT single-owner; App mandatory multi-tenant), closed by this plan + the E1 CONST-TOKEN-SCOPED-PER-JOB amendment. |