fix: harden native review publication

Author: CompleteDotTech

.env.1password.example

@@ -1,6 +1,13 @@
 GITHUB_APP_ID=op://Private/CovenCat/App ID
 GITHUB_WEBHOOK_SECRET=op://Private/CovenCat/Webhook Secret
 GITHUB_APP_PRIVATE_KEY=op://Private/CovenCat/Private Key
+COVEN_PUBLICATION_SIGNING_SECRET=op://Private/CovenCat/Publication Signing Secret
 COVEN_GITHUB_POLICY_PATH=./coven-github-policy.json
 COVEN_GITHUB_STATE_DIR=./coven-github-state
-COVEN_CODE_BIN=coven-code
+COVEN_RUNTIME_ISOLATION=bwrap
+COVEN_RUNTIME_EXTERNAL_ISOLATION=verify-host-controls-before-setting
+COVEN_GITHUB_REVOCATION_EVENTS=verify-live-app-before-setting
+COVEN_BWRAP_BIN=/usr/bin/bwrap
+COVEN_RUNTIME_ROOTFS=/opt/coven-runtime/rootfs
+COVEN_RUNTIME_NETWORK=shared
+COVEN_CODE_BIN=/usr/local/bin/coven-code

README.md

@@ -10,6 +10,17 @@ The adapter is deployment-specific. It is not the canonical Rust worker
 implementation; it exists so hosted webhook behavior can be reviewed,
 reproduced, and changed through PRs instead of server-only edits.
 
+Long-running tasks execute outside the HTTP thread so GitHub deliveries are
+acknowledged promptly and health endpoints stay responsive. Queued or
+interrupted tasks are discovered again when the service starts. Native review
+deployments must subscribe the GitHub App to both `pull_request` and `push`, and
+must enable `pull_request.synchronize`, `pull_request.edited`,
+`pull_request.reopened`, and the actionless `push` trigger. These deliveries
+reconcile stale decisive reviews after head changes, base retargeting, reopening,
+or new commits on a PR's base branch. A `publication.mode=comment` route that
+lacks any of these safety triggers fails closed instead of publishing native PR
+reviews.
+
 ## Files
 
 - `src/adapter.ts` - webhook handler, task router, task runner, PR evidence
@@ -32,17 +43,60 @@ The deployment expects secrets and mutable state to be supplied outside git:
 
 - `GITHUB_APP_ID`
 - `GITHUB_WEBHOOK_SECRET` or `WEBHOOK_SECRET`
+- `COVEN_PUBLICATION_SIGNING_SECRET` - optional dedicated HMAC key for review
+  identity markers; defaults to the webhook secret for compatibility
+- `COVEN_PUBLICATION_PREVIOUS_SIGNING_SECRETS` - comma-separated prior marker
+  keys retained only during rotation/reconciliation
 - `GITHUB_APP_PRIVATE_KEY_PATH` or `.coven-github-private-key.pem`
 - `COVEN_GITHUB_STATE_DIR`
 - `COVEN_GITHUB_POLICY_PATH`
-- `COVEN_CODE_BIN`
+- `COVEN_RUNTIME_ISOLATION=bwrap` - required for every non-demo task; unset is
+  fail-closed and never falls back to direct execution
+- `COVEN_RUNTIME_EXTERNAL_ISOLATION=network-egress-and-resource-limits-verified`
+  - mandatory declaration that the deployment independently enforces egress,
+  CPU, memory, PID, and disk/scratch limits
+- `COVEN_GITHUB_REVOCATION_EVENTS=pull-request-and-push-verified` - set only
+  after verifying the installed App's live `pull_request` and `push`
+  subscriptions; native PR publication fails closed without it
+- `COVEN_BWRAP_BIN` - absolute host path to bubblewrap (defaults to
+  `/usr/bin/bwrap`)
+- `COVEN_RUNTIME_ROOTFS` - dedicated credential-free runtime rootfs
+- `COVEN_CODE_BIN` - absolute coven-code path inside that rootfs
+- `COVEN_RUNTIME_NETWORK=shared` - explicit opt-in required when the Codex
+  provider needs network access; the default is `none`
 - `COVEN_REVIEW_FIX_LOOPS` - optional bounded review-fix loop count, clamped
   between `0` and `5`; defaults to `0` so hosted repair loops are opt-in
 - Codex OAuth tokens under the deployed account's `.coven-code` directory
 
 Do not commit private keys, webhook secrets, OAuth tokens, generated task state,
 workspaces, or attempt artifacts.
 
+Real tasks never execute directly as the webhook account. Before minting a
+GitHub token, the adapter runs a bubblewrap probe and verifies read-only input,
+writable workspace/output mounts, a private PID namespace, no network for
+validation, and a dedicated rootfs that does not contain adapter state or
+credentials. A missing binary, rootfs, executable, or usable user namespace
+records the task as `runtime_isolation_unavailable` with no direct fallback.
+`publication.mode=record_only` is not an isolation control.
+
+The runtime rootfs must contain the configured `coven-code`, `git`, and shell
+executables plus their libraries, CA/DNS files, and approved runtime assets. It
+must not contain the GitHub App key, webhook state, policy, parent home, or Codex
+token store. The runtime receives only its dedicated model credential; it never
+receives a GitHub token or Git askpass helper. Shared networking is not an
+egress-confidentiality boundary, so use a dedicated, revocable model credential
+and an externally enforced allowlist that blocks loopback, LAN, and metadata
+services. The adapter refuses real tasks unless the external network/resource
+isolation declaration is present.
+
+The current runtime passes that model credential to `coven-code`; an untrusted
+checkout can therefore try to consume or encode it through the model channel
+even when ordinary egress is filtered. Treat this release as trusted-repository
+only. Public/untrusted pull requests require a separately constrained worker and
+a quota-limited credential broker that never exposes a reusable model token to
+the repository process. Do not set the external-isolation declaration for that
+use case until those controls exist.
+
 ## Local runtime
 
 Install dependencies, build TypeScript, and start the webhook service:
@@ -95,6 +149,16 @@ Deployments should provide `coven-github-policy.json` through
 `COVEN_GITHUB_POLICY_PATH`. That file is intentionally ignored because it is
 environment-specific.
 
+Every route with `publication.mode=comment` must include all native-review
+safety triggers: `pull_request.synchronize`, `pull_request.edited`,
+`pull_request.reopened`, and `push`. The `push` key is actionless; do not write
+`push.`. Both the `pull_request` and `push` webhook events must also be enabled
+on the installed GitHub App. Missing policy coverage is a configuration error
+and native publication remains fail closed. After verifying the live App
+registration, set
+`COVEN_GITHUB_REVOCATION_EVENTS=pull-request-and-push-verified`; this declaration
+is required in addition to the policy trigger list.
+
 Start from [`config/example-policy.json`](config/example-policy.json) and the
 connection guide in
 [`docs/coven-github-connection.md`](docs/coven-github-connection.md).
@@ -114,8 +178,17 @@ connection guide in
   remain in the review body. Decisive reviews are bound to the captured commit
   and require full changed-file coverage, a clean matching checkout, and
   verified passing test evidence. They are created pending, then submitted only
-  after a fresh head check; a concurrent head change causes a COMMENT downgrade
-  or automatic dismissal.
+  after fresh head and base checks; a concurrent revision change causes a
+  COMMENT downgrade or automatic dismissal. Passing claims are decisive only
+  when they match successful host-captured validation receipts. Validation and
+  post-run Git checks execute in a second credential-free, network-disabled
+  sandbox.
+- Uses repository-scoped installation tokens: parent Git gets only
+  `contents:read`, PR evidence gets read authority, and publication write
+  authority is minted only after isolated execution has finished.
+- Persists `publication_pending` before GitHub writes and resumes interrupted
+  publication on startup or duplicate webhook delivery without rerunning the
+  agent.
 - Persists publication identities and review/comment IDs in the configured
   state directory, reconciles HMAC-signed App-authored identities with GitHub,
   and serializes publication per PR so retries and concurrent runs do not

config/example-policy.json

@@ -7,7 +7,11 @@
           "enabled_triggers": [
             "issues.labeled",
             "issue_comment.created",
-            "pull_request_review_comment.created"
+            "pull_request_review_comment.created",
+            "pull_request.synchronize",
+            "pull_request.edited",
+            "pull_request.reopened",
+            "push"
           ],
           "trigger_labels": [
             "coven:fix",

docs/coven-github-connection.md

@@ -21,14 +21,40 @@ Set the manifest webhook URL to this service:
 https://your-host/webhook
 ```
 
-The manifest subscribes to the events this adapter can route:
+The adapter can route these GitHub App webhook events:
 
 - `issues`
 - `issue_comment`
+- `pull_request`
 - `pull_request_review`
 - `pull_request_review_comment`
 - `check_suite`
 - `check_run`
+- `push`
+
+For every route using `publication.mode: comment`, the installed GitHub App must
+subscribe to both **Pull request** (`pull_request`) and **Push** (`push`) events.
+The route's `enabled_triggers` must contain all four safety triggers:
+
+- `pull_request.synchronize` for new commits or force-pushes on the PR head.
+- `pull_request.edited` for base-branch retargeting.
+- `pull_request.reopened` to reconcile a PR when it becomes active again.
+- `push` to reconcile open PRs when new commits land on their base branch. Push
+  deliveries have no `action`, so the policy key is exactly `push`, not `push.`.
+
+These deliveries let the adapter dismiss signed, decisive covencat reviews
+whose reviewed head/base pair is no longer current. Native publication fails
+closed if any required policy trigger is absent. `doctor:app` reports each
+missing trigger as an error. Keep the route on `record_only` until both the
+policy and App subscriptions are complete. After checking the live App settings,
+set `COVEN_GITHUB_REVOCATION_EVENTS=pull-request-and-push-verified`; this explicit
+deployment declaration is also required for native PR publication.
+
+Treat the manifest file and the live App registration as separate checks:
+ensure `docs/app-manifest.json` in `OpenCoven/coven-github` lists both events,
+then verify the installed App's settings also subscribe to **Pull request** and
+**Push**. Updating a manifest file does not retroactively update an existing
+GitHub App registration.
 
 After creating the App, keep these values outside git:
 
@@ -68,6 +94,11 @@ Then replace:
 - `bot_usernames` with the GitHub App bot login, for example
   `coven-cody[bot]`.
 - `trigger_labels` with labels that should start tasks.
+- `enabled_triggers` with the exact event/action pairs allowed to spend compute,
+  plus actionless `push` where needed. Events not listed are acknowledged and
+  ignored. A `publication.mode: comment` route must include all four
+  native-review safety triggers listed above; otherwise publication fails
+  closed.
 - `familiar` with the familiar id, display name, model, and skills to pass to
   `coven-code`.
 
@@ -79,7 +110,14 @@ export COVEN_GITHUB_POLICY_PATH="$PWD/coven-github-policy.json"
 
 Keep `publication.mode` as `record_only` for first smoke runs. Switch it to
 `comment` only after you have verified the App installation, `coven-code`
-runtime, Codex token, and workspace permissions.
+runtime, Codex token, workspace permissions, both required GitHub App webhook
+subscriptions, and all four required safety triggers.
+
+`record_only` controls publication, not process isolation. Non-demo work stays
+blocked until the mandatory runtime sandbox below passes its executable probe.
+For decisive native reviews, also configure a bounded list of trusted
+validation commands under `publication.validation_commands`; a runtime-authored
+claim without a matching successful sandbox receipt is published as COMMENT.
 
 ## Runtime Checklist
 
@@ -92,12 +130,51 @@ export GITHUB_WEBHOOK_SECRET="replace-with-github-secret"
 export GITHUB_APP_PRIVATE_KEY_PATH="$PWD/keys/coven-github.private-key.pem"
 export COVEN_GITHUB_POLICY_PATH="$PWD/coven-github-policy.json"
 export COVEN_GITHUB_STATE_DIR="$PWD/coven-github-state"
-export COVEN_CODE_BIN="$(command -v coven-code)"
+install -d -m 700 "$COVEN_GITHUB_STATE_DIR"
+export COVEN_RUNTIME_ISOLATION="bwrap"
+export COVEN_RUNTIME_EXTERNAL_ISOLATION="network-egress-and-resource-limits-verified"
+export COVEN_GITHUB_REVOCATION_EVENTS="pull-request-and-push-verified"
+export COVEN_BWRAP_BIN="/usr/bin/bwrap"
+export COVEN_RUNTIME_ROOTFS="/opt/coven-runtime/rootfs"
+export COVEN_CODE_BIN="/usr/local/bin/coven-code" # path inside the rootfs
+export COVEN_RUNTIME_NETWORK="shared"             # explicit Codex egress opt-in
 
 npm run doctor:app
 npm start
 ```
 
+Build the dedicated rootfs as an administrator-controlled deployment artifact.
+It must contain the configured `coven-code`, `/usr/bin/git`, `/bin/sh`,
+`/bin/true`, their libraries, CA/DNS files, and required runtime assets. Do not
+copy the webhook checkout, state directory, policy, App key, hosting-user home,
+or `.coven-code` token store into it. Bubblewrap must be able to create user
+namespaces on the target host; `doctor:app` runs a real read/write isolation
+probe and fails when it cannot.
+
+The external-isolation declaration is intentionally mandatory. Set it only
+after the worker host or container enforces allowlisted egress (including no
+loopback, LAN, or metadata access) and CPU, memory, PID, workspace/disk, and
+scratch limits. Bubblewrap mount namespaces and timeouts do not provide those
+controls. A state directory from an older deployment must be owned by the
+service user and made inaccessible to group/other (for example, `chmod -R go-rwx
+"$COVEN_GITHUB_STATE_DIR"`) before this version starts.
+
+This release passes the model credential to `coven-code`, so an untrusted
+checkout can still try to consume or encode it through the allowed model
+channel. Limit real execution to trusted repositories. Supporting public or
+otherwise untrusted pull requests requires a separately constrained worker and
+a quota-limited credential broker that does not expose a reusable model token
+to repository code; the declaration above must remain unset until that boundary
+is actually deployed.
+
+The adapter mounts only per-task input (read-only), the checkout and result
+directory (writable), and the checkout `.git` directory again as read-only. It
+passes no GitHub token, askpass helper, App secret, SSH agent, or parent home to
+`coven-code`. Publication authority is minted only after the sandbox exits.
+Validation commands run again without credentials or network access. If the
+host cannot satisfy this boundary, leave real execution disabled and use demo
+mode or an externally isolated worker; there is no unsafe direct fallback.
+
 In another shell:
 
 ```bash

scripts/doctor-app-config.mjs

@@ -1,8 +1,16 @@
 #!/usr/bin/env node
-import {existsSync, readFileSync} from "node:fs";
+import {existsSync, mkdtempSync, readFileSync, rmSync} from "node:fs";
+import {tmpdir} from "node:os";
 import {join} from "node:path";
 
-import {createConfig} from "../dist/src/adapter.js";
+import {createConfig, probeRuntimeIsolation, runtimeIsolationIssue} from "../dist/src/adapter.js";
+
+const NATIVE_REVIEW_SAFETY_TRIGGERS = [
+  "pull_request.synchronize",
+  "pull_request.edited",
+  "pull_request.reopened",
+  "push",
+];
 
 function finding(level, field, message, next) {
   return {level, field, message, next};
@@ -45,6 +53,7 @@ if (!config.privateKeyPem && !existsSync(config.privateKeyPath)) {
 }
 
 const policy = loadJson(config.policyPath);
+let requiresRevocationEvents = false;
 if (!policy) {
   findings.push(finding("error", "COVEN_GITHUB_POLICY_PATH", "policy file is missing or invalid JSON", "Copy config/example-policy.json and replace the installation/repository IDs."));
 } else {
@@ -64,11 +73,49 @@ if (!policy) {
     if (Object.keys(repos).includes("987654321")) {
       findings.push(finding("error", "policy.repositories", "policy still uses placeholder repository ID 987654321", "Replace it with the real repository ID."));
     }
+    for (const [repositoryId, route] of Object.entries(repos)) {
+      if (route?.publication?.mode !== "comment") continue;
+      requiresRevocationEvents = true;
+      const enabledTriggers = new Set(Array.isArray(route.enabled_triggers) ? route.enabled_triggers.map(String) : []);
+      for (const trigger of NATIVE_REVIEW_SAFETY_TRIGGERS) {
+        if (!enabledTriggers.has(trigger)) {
+          const field = `policy.installations.${installationId}.repositories.${repositoryId}.enabled_triggers`;
+          findings.push(finding(
+            "error",
+            field,
+            `native review publication requires ${trigger}`,
+            `Add ${trigger} to enabled_triggers and subscribe the GitHub App to the corresponding webhook event, or use publication.mode=record_only.`,
+          ));
+        }
+      }
+    }
   }
 }
 
-if (!process.env.COVEN_CODE_BIN && !config.demoMode) {
-  findings.push(finding("warning", "COVEN_CODE_BIN", "COVEN_CODE_BIN is not set", "Set it to the coven-code binary path before running real tasks."));
+if (requiresRevocationEvents && !config.revocationEventsVerified) {
+  findings.push(finding(
+    "error",
+    "COVEN_GITHUB_REVOCATION_EVENTS",
+    "native review publication requires verified pull_request and push delivery subscriptions on the installed GitHub App",
+    "Verify the live App subscriptions, then set COVEN_GITHUB_REVOCATION_EVENTS=pull-request-and-push-verified; otherwise use publication.mode=record_only.",
+  ));
+}
+
+if (!config.demoMode) {
+  const isolationIssue = runtimeIsolationIssue(config);
+  if (isolationIssue) {
+    findings.push(finding("error", "COVEN_RUNTIME_ISOLATION", isolationIssue, "Configure COVEN_RUNTIME_ISOLATION=bwrap with a dedicated rootfs and absolute runtime binary paths. There is no direct-execution fallback."));
+  } else {
+    const probeDir = mkdtempSync(join(tmpdir(), "coven-runtime-doctor-"));
+    try {
+      const probeIssue = probeRuntimeIsolation(config, probeDir);
+      if (probeIssue) {
+        findings.push(finding("error", "COVEN_RUNTIME_ISOLATION", probeIssue, "Fix bubblewrap/user-namespace support or keep real task execution disabled."));
+      }
+    } finally {
+      rmSync(probeDir, {recursive: true, force: true});
+    }
+  }
 }
 
 const errors = findings.filter((item) => item.level === "error");
@@ -81,6 +128,10 @@ const output = {
     private_key: Boolean(config.privateKeyPem || existsSync(config.privateKeyPath)),
     policy_path: config.policyPath,
     state_dir: config.stateDir,
+    runtime_isolation: config.runtimeIsolation,
+    runtime_external_isolation: config.runtimeExternalIsolationVerified,
+    revocation_events: config.revocationEventsVerified,
+    runtime_rootfs: config.runtimeRootfs || null,
   },
   findings,
 };