feat(selfhost): App checks:write + an instance-wide write kill switch (#1288)

Two cloud→self-host migration prerequisites (Phase 2), gated so the live cloud Worker
is byte-identical (it never sets the new env):

- The /setup App manifest declared checks:read, but the gate posts a check-run
  (POST /check-runs needs checks:write); GitHub 403s that write and the engine swallows
  it as a permission_missing warning — a silent first-review failure. The rest of the
  system already asserts checks:write as required (backfill/data-spine tests). Fix the
  manifest; existing self-host Apps must be recreated.

- Add SELFHOST_DEPLOYMENT_MODE=dry-run|disabled as an instance-wide kill switch in the
  makeInstallationOctokit chokepoint: it forces write suppression for EVERY installation
  write regardless of the per-call mode, so a self-host running in parallel with the cloud
  App can receive the same webhooks but provably post nothing (check-run/comment/label/
  merge) until cutover — without relying on every call site threading the repo mode. Unset
  (cloud) → no forcing → behavior unchanged.

Advances the self-host migration (Phase 2 of the cutover plan).

Author: JSONbored

.env.example

@@ -26,6 +26,13 @@
 # Example: GITTENSORY_REVIEW_REPOS="JSONbored/gittensory,JSONbored/awesome-claude"
 GITTENSORY_REVIEW_REPOS=
 
+# Instance-wide write kill switch for the cloud→self-host parallel-run migration. When set to "dry-run"
+# (or "disabled"), EVERY GitHub write from this instance is suppressed regardless of per-repo settings —
+# the instance can receive webhooks and compute verdicts but posts NOTHING (no check-run/comment/label/
+# merge), so it can shadow the live cloud App safely until cutover. "dry-run" audits as completed-shadow;
+# "disabled" audits as denied. Leave empty (= live) for normal operation. Flip to live only at cutover.
+# SELFHOST_DEPLOYMENT_MODE=dry-run
+
 # --- Per-PR capabilities (also require the repo in GITTENSORY_REVIEW_REPOS) ---
 
 # Safety scan: defangs untrusted PR title/body/diff (prompt-injection

src/env.d.ts

@@ -51,6 +51,9 @@ declare global {
     SCORING_TIME_DECAY_ENABLED?: string;
     /** #776 agent-layer GLOBAL kill-switch — when truthy, halts ALL agent actions across every repo. */
     AGENT_ACTIONS_PAUSED?: string;
+    /** Self-host instance-wide write switch: "dry-run" | "disabled" forces EVERY installation write to be
+     *  suppressed regardless of per-repo mode (the cloud→self-host parallel-run kill switch). Unset = live. */
+    SELFHOST_DEPLOYMENT_MODE?: string;
     GITTENSORY_AUTO_FILE_DRIFT_ISSUES?: string;
     GITTENSORY_DRIFT_ISSUE_REPO?: string;
     GITTENSORY_DRIFT_ISSUE_TOKEN?: string;

src/github/client.ts

@@ -55,15 +55,31 @@ function syntheticWriteResponse(url: string): { status: number; url: string; hea
   return { ...base, data: { dryRunSuppressed: true } };
 }
 
+/**
+ * Instance-wide self-host kill switch (#selfhost-deployment-mode). SELFHOST_DEPLOYMENT_MODE=dry-run|disabled
+ * forces write suppression for the WHOLE instance regardless of the per-call mode — so a self-host running in
+ * PARALLEL with the live cloud App can receive the same webhooks but provably post NOTHING (no check-run /
+ * comment / label / merge) until an explicit cutover, without relying on every call site threading the repo mode.
+ * Unset (the cloud Worker never sets it) → null → behavior is byte-identical to today.
+ */
+export function forcedSelfhostMode(env: { SELFHOST_DEPLOYMENT_MODE?: string | undefined }): AgentActionMode | null {
+  const m = (env.SELFHOST_DEPLOYMENT_MODE ?? "").trim().toLowerCase();
+  if (m === "disabled") return "paused"; // suppress + audit as denied
+  if (m === "dry-run" || m === "dry_run") return "dry_run"; // suppress + audit as completed-shadow
+  return null; // "live" / unset → no forcing
+}
+
 /**
  * Build an installation Octokit from an ALREADY-minted token. Takes the token (not the installationId) so this
  * module never imports createInstallationToken — the mint stays in app.ts via raw fetch and can never be reached
  * by the suppression hook. `mode` defaults to "live", so the action helpers (pr-actions) that are already gated by
  * the executor are not double-denied; surface callers (check-run / comment / label) pass the resolved repo mode.
+ * A SELFHOST_DEPLOYMENT_MODE override beats the per-call mode so the whole instance can be forced non-actuating.
  */
 export function makeInstallationOctokit(env: Env, token: string, mode: AgentActionMode = "live"): Octokit {
   const octokit = new Octokit({ auth: token, request: { fetch: timeoutFetch } });
-  if (mode !== "live") {
+  const effectiveMode = forcedSelfhostMode(env) ?? mode;
+  if (effectiveMode !== "live") {
     octokit.hook.wrap("request", async (request, options) => {
       const method = options.method.toUpperCase();
       if (!WRITE_METHODS.has(method)) return request(options); // reads + create-vs-update probes always run
@@ -72,9 +88,9 @@ export function makeInstallationOctokit(env: Env, token: string, mode: AgentActi
         eventType: "github.write.suppressed",
         actor: "gittensory",
         targetKey: url,
-        outcome: mode === "dry_run" ? "completed" : "denied",
-        detail: `${mode}: suppressed ${method} ${url}`,
-        metadata: { method, url, mode },
+        outcome: effectiveMode === "dry_run" ? "completed" : "denied",
+        detail: `${effectiveMode}: suppressed ${method} ${url}`,
+        metadata: { method, url, mode: effectiveMode },
       }).catch(
         /* v8 ignore next -- fail-safe: an audit-write failure never blocks the suppression itself */
         () => undefined,

src/selfhost/setup-wizard.ts

@@ -27,7 +27,9 @@ export function buildManifest(origin: string, state: string): Record<string, unk
       pull_requests: "write",
       contents: "write",
       issues: "write",
-      checks: "read",
+      // checks:write — the gate posts a check-run (POST /repos/{o}/{r}/check-runs in src/github/app.ts);
+      // checks:read would 403 that write (swallowed as a permission_missing warning → silent first-review failure).
+      checks: "write",
       metadata: "read",
       statuses: "read",
     },

test/unit/github-client.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { makeInstallationOctokit, resolveRepoActionMode, timeoutFetch } from "../../src/github/client";
+import { forcedSelfhostMode, makeInstallationOctokit, resolveRepoActionMode, timeoutFetch } from "../../src/github/client";
 import { setGlobalAgentFrozen } from "../../src/db/repositories";
 import { createTestEnv } from "../helpers/d1";
 
@@ -76,6 +76,35 @@ describe("makeInstallationOctokit", () => {
   });
 });
 
+describe("forcedSelfhostMode (instance-wide self-host kill switch)", () => {
+  it("maps SELFHOST_DEPLOYMENT_MODE to a forced action mode (else null)", () => {
+    expect(forcedSelfhostMode({ SELFHOST_DEPLOYMENT_MODE: "dry-run" })).toBe("dry_run");
+    expect(forcedSelfhostMode({ SELFHOST_DEPLOYMENT_MODE: "dry_run" })).toBe("dry_run"); // underscore variant
+    expect(forcedSelfhostMode({ SELFHOST_DEPLOYMENT_MODE: "DISABLED" })).toBe("paused"); // case-insensitive
+    expect(forcedSelfhostMode({ SELFHOST_DEPLOYMENT_MODE: "live" })).toBeNull();
+    expect(forcedSelfhostMode({})).toBeNull();
+  });
+
+  it("forces suppression for the WHOLE instance even when the caller passes mode=live", async () => {
+    const calls: RecordedCall[] = [];
+    stubFetchRecording(calls);
+    const env = { ...createTestEnv(), SELFHOST_DEPLOYMENT_MODE: "dry-run" };
+    const octokit = makeInstallationOctokit(env, "tok", "live"); // a LIVE caller…
+    const r = await octokit.request("POST /repos/{owner}/{repo}/check-runs", { owner: "o", repo: "r", name: "Gate", head_sha: "abc" });
+    expect(calls.some((c) => c.method === "POST")).toBe(false); // …but the instance switch suppresses it anyway
+    expect((r.data as unknown as { id: number }).id).toBe(-1);
+  });
+
+  it("'disabled' forces suppression audited as denied (vs dry-run's completed-shadow)", async () => {
+    stubFetchRecording([]);
+    const env = { ...createTestEnv(), SELFHOST_DEPLOYMENT_MODE: "disabled" };
+    const octokit = makeInstallationOctokit(env, "tok", "live");
+    await octokit.request("POST /repos/{owner}/{repo}/check-runs", { owner: "o", repo: "r", name: "Gate", head_sha: "abc" });
+    const audit = await env.DB.prepare("SELECT outcome FROM audit_events WHERE event_type = ?").bind("github.write.suppressed").first<{ outcome: string }>();
+    expect(audit?.outcome).toBe("denied");
+  });
+});
+
 describe("resolveRepoActionMode", () => {
   it("maps the env brake, DB freeze, per-repo pause and dry-run to the same modes the executor uses", async () => {
     const env = createTestEnv();