From ce237555364f6d03528c7a785ddf9c830f96fe49 Mon Sep 17 00:00:00 2001
From: Val Alexander <bunsthedev@gmail.com>
Date: Thu, 25 Jun 2026 03:14:26 -0500
Subject: [PATCH 1/3] Introduce headless contract, webhook parsing, and repo
 client

Add a locked headless execution contract (v1) with doc, JSON schemas, and golden fixtures. Make session briefs tokenless and enforce COVEN_GIT_TOKEN as the git-auth channel. Add HEADLESS_CONTRACT_VERSION, contract_version fields to brief/result types, and conformance tests. Implement repo metadata client to resolve branch/PR SHAs and wire it into worker task execution (CheckRun target, brief default_branch, PR base ref). Enhance webhook parsing/routing: PR review events, PR comment detection, ping handling, and robust mention matching. Several tests and fixtures added; update docs (security, self-hosting, README).
---
 COVEN-GITHUB.md                               |  11 +
 README.md                                     |   7 +-
 crates/github/src/lib.rs                      |  50 +++-
 crates/github/src/repo.rs                     | 225 +++++++++++++++
 crates/github/src/tasks.rs                    |   1 +
 crates/webhook/src/events.rs                  |  34 +++
 crates/webhook/src/routes.rs                  | 223 ++++++++++++++-
 .../tests/fixtures/issue_assigned.json        |  18 ++
 .../tests/fixtures/issue_comment_created.json |  22 ++
 .../tests/fixtures/issue_comment_on_pr.json   |  26 ++
 .../webhook/tests/fixtures/issue_labeled.json |  18 ++
 crates/webhook/tests/fixtures/ping.json       |  20 ++
 .../pull_request_review_comment_created.json  |  22 ++
 .../pull_request_review_submitted.json        |  21 ++
 crates/webhook/tests/parse_fixtures.rs        | 128 +++++++++
 crates/worker/src/brief.rs                    | 100 ++++++-
 crates/worker/src/lib.rs                      |  86 +++++-
 crates/worker/tests/contract.rs               |  97 +++++++
 docs/app-manifest.json                        |  26 ++
 docs/contracts/result.example.json            |  12 +
 docs/contracts/result.schema.json             |  44 +++
 docs/contracts/session-brief.example.json     |  25 ++
 docs/contracts/session-brief.schema.json      |  89 ++++++
 docs/headless-contract.md                     | 258 ++++++++++++++++++
 docs/security.md                              |   6 +-
 docs/self-hosting.md                          |  29 ++
 26 files changed, 1549 insertions(+), 49 deletions(-)
 create mode 100644 crates/github/src/repo.rs
 create mode 100644 crates/webhook/tests/fixtures/issue_assigned.json
 create mode 100644 crates/webhook/tests/fixtures/issue_comment_created.json
 create mode 100644 crates/webhook/tests/fixtures/issue_comment_on_pr.json
 create mode 100644 crates/webhook/tests/fixtures/issue_labeled.json
 create mode 100644 crates/webhook/tests/fixtures/ping.json
 create mode 100644 crates/webhook/tests/fixtures/pull_request_review_comment_created.json
 create mode 100644 crates/webhook/tests/fixtures/pull_request_review_submitted.json
 create mode 100644 crates/webhook/tests/parse_fixtures.rs
 create mode 100644 crates/worker/tests/contract.rs
 create mode 100644 docs/app-manifest.json
 create mode 100644 docs/contracts/result.example.json
 create mode 100644 docs/contracts/result.schema.json
 create mode 100644 docs/contracts/session-brief.example.json
 create mode 100644 docs/contracts/session-brief.schema.json
 create mode 100644 docs/headless-contract.md

diff --git a/COVEN-GITHUB.md b/COVEN-GITHUB.md
index e8b7350..0a3eab0 100644
--- a/COVEN-GITHUB.md
+++ b/COVEN-GITHUB.md
@@ -116,6 +116,17 @@ The same lifecycle in operational prose:
 
 ## coven-code Delta: Headless Mode
 
+> **The normative, locked contract lives in [`docs/headless-contract.md`](docs/headless-contract.md)
+> (contract version `1`).** That document is the single source of truth, with
+> machine-checkable JSON Schemas and golden fixtures in [`docs/contracts/`](docs/contracts/)
+> and a conformance test (`crates/worker/tests/contract.rs`). The summary below
+> is illustrative; where it disagrees with the contract, the contract wins. In
+> particular the contract supersedes this section on three points: the session
+> brief is **tokenless** (git auth flows via the `COVEN_GIT_TOKEN` env var, not
+> `GIT_ASKPASS`/an embedded `auth.token`), the brief carries a `task` tagged
+> union (not an `issue` object), and the v1 `result.json` envelope does **not**
+> include an `events` array (progress streaming is deferred to M2).
+
 The execution runtime needs the following additions to work as a GitHub App backend:
 
 ### `--headless` flag
diff --git a/README.md b/README.md
index a828147..b2b39b2 100644
--- a/README.md
+++ b/README.md
@@ -112,9 +112,10 @@ For deeper system, sequence, state, security-boundary, and hosted deployment dia
 | Label trigger | Implemented | Routes configured `trigger_labels` such as `coven:fix`. |
 | Issue / PR mention trigger | Implemented | Ignores familiar bot self-comments to avoid loops. |
 | GitHub App installation tokens | Implemented | Mints installation access tokens from the App private key. |
-| Check Run creation and completion | Partial | Creates and updates Check Runs; branch/SHA resolution still needs production hardening. |
-| `coven-code --headless` execution | Partial | Worker spawns headless sessions and enforces task timeouts; result quality depends on the runtime. |
-| Pull request creation | Partial | Opens draft PRs from session results; base branch is still hardcoded to `main`. |
+| Check Run creation and completion | Partial | Creates and updates Check Runs against the resolved target head SHA; stale-ref revalidation before publish is still planned. |
+| Headless execution contract | Locked (v1) | Brief, result envelope, exit codes, and git-auth channel are pinned in [`docs/headless-contract.md`](docs/headless-contract.md) with JSON Schemas, golden fixtures, and a conformance test. |
+| `coven-code --headless` execution | Partial | Worker spawns headless sessions with a tokenless session brief and enforces task timeouts; result quality depends on the runtime. |
+| Pull request creation | Partial | Opens draft PRs from session results against the repository's resolved default/base branch. |
 | CovenCave task polling | Partial | In-memory task API exists for local oversight; hosted control-plane auth and persistence are planned. |
 | Durable queue / task store | Planned | Required for hosted reliability and restarts. |
 | Hosted tier | Planned | See [Hosted vs self-hosted](docs/hosted-vs-self-hosted.md). |
diff --git a/crates/github/src/lib.rs b/crates/github/src/lib.rs
index b4c2605..70358a8 100644
--- a/crates/github/src/lib.rs
+++ b/crates/github/src/lib.rs
@@ -5,9 +5,18 @@ use serde::{Deserialize, Serialize};
 pub mod check_run;
 pub mod installation;
 pub mod pr;
+pub mod repo;
 pub mod tasks;
 
 pub const DEFAULT_API_BASE_URL: &str = "https://api.github.com";
+
+/// Major version of the coven-code headless execution contract this adapter
+/// speaks. See `docs/headless-contract.md`. Bump only on breaking changes.
+pub const HEADLESS_CONTRACT_VERSION: &str = "1";
+
+fn default_contract_version() -> String {
+    HEADLESS_CONTRACT_VERSION.to_string()
+}
 const GITHUB_API_VERSION: &str = "2026-03-10";
 
 #[derive(Debug, Clone, PartialEq, Eq)]
@@ -35,14 +44,16 @@ async fn send_json(
     request: GitHubRequest,
 ) -> anyhow::Result<reqwest::Response> {
     let method = reqwest::Method::from_bytes(request.method.as_bytes())?;
-    let response = client
+    let mut builder = client
         .request(method, api_url(base_url, &request.path))
         .bearer_auth(token)
         .header("Accept", "application/vnd.github+json")
-        .header("X-GitHub-Api-Version", GITHUB_API_VERSION)
-        .json(&request.body)
-        .send()
-        .await?;
+        .header("X-GitHub-Api-Version", GITHUB_API_VERSION);
+    // GET/metadata requests carry no body; only attach JSON for mutations.
+    if !request.body.is_null() {
+        builder = builder.json(&request.body);
+    }
+    let response = builder.send().await?;
 
     if !response.status().is_success() {
         let status = response.status();
@@ -60,7 +71,10 @@ pub enum GitHubEvent {
     IssueAssigned(IssueAssignedEvent),
     IssueLabeled(IssueLabeledEvent),
     IssueComment(IssueCommentEvent),
+    PullRequestReview(PrReviewEvent),
     PullRequestReviewComment(PrReviewCommentEvent),
+    /// `ping` delivery GitHub sends when a webhook is first configured.
+    Ping,
     Unsupported { name: String },
 }
 
@@ -94,6 +108,27 @@ pub struct IssueCommentEvent {
     pub issue_number: u64,
     pub comment_body: String,
     pub commenter_login: String,
+    /// `issue_comment` fires for pull-request conversation comments as well as
+    /// issue comments. GitHub flags the former with an `issue.pull_request`
+    /// object; this lets routing send PR comments through PR iteration rather
+    /// than issue-mention handling.
+    pub on_pull_request: bool,
+}
+
+/// Top-level pull request review submission (`pull_request_review` → `submitted`).
+///
+/// Distinct from [`PrReviewCommentEvent`], which is a single inline comment on a
+/// diff hunk. This carries the review summary body and verdict (state).
+#[derive(Debug, Clone, Deserialize, Serialize)]
+pub struct PrReviewEvent {
+    pub installation_id: u64,
+    pub repo_owner: String,
+    pub repo_name: String,
+    pub pr_number: u64,
+    pub review_body: String,
+    /// Review verdict: `approved`, `changes_requested`, or `commented`.
+    pub review_state: String,
+    pub reviewer_login: String,
 }
 
 #[derive(Debug, Clone, Deserialize, Serialize)]
@@ -139,6 +174,11 @@ pub enum TaskKind {
 /// Structured result envelope written by coven-code --headless.
 #[derive(Debug, Clone, Deserialize, Serialize)]
 pub struct SessionResult {
+    /// Contract major version. Defaults to the current version when a runtime
+    /// omits it, but conformant producers MUST emit it. See
+    /// `docs/headless-contract.md`.
+    #[serde(default = "default_contract_version")]
+    pub contract_version: String,
     pub status: SessionStatus,
     pub branch: Option<String>,
     pub commits: Vec<CommitInfo>,
diff --git a/crates/github/src/repo.rs b/crates/github/src/repo.rs
new file mode 100644
index 0000000..529e5da
--- /dev/null
+++ b/crates/github/src/repo.rs
@@ -0,0 +1,225 @@
+//! GitHub repository, branch, and pull request metadata client.
+//!
+//! Used to resolve the target refs a task operates on instead of relying on
+//! placeholders like `"HEAD"` or a hardcoded `"main"` base branch.
+
+use anyhow::Result;
+use serde::Deserialize;
+
+use crate::{client, send_json, GitHubRequest, DEFAULT_API_BASE_URL};
+
+/// Repository metadata we care about for routing and publication.
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
+pub struct RepoMetadata {
+    pub default_branch: String,
+}
+
+/// Pull request refs needed to attach checks and open/update PRs correctly.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PullRequestRefs {
+    pub head_ref: String,
+    pub head_sha: String,
+    pub base_ref: String,
+    pub base_sha: String,
+}
+
+#[derive(Debug, Deserialize)]
+struct BranchResponse {
+    commit: CommitRef,
+}
+
+#[derive(Debug, Deserialize)]
+struct CommitRef {
+    sha: String,
+}
+
+#[derive(Debug, Deserialize)]
+struct PullRequestMetaResponse {
+    head: PrRef,
+    base: PrRef,
+}
+
+#[derive(Debug, Deserialize)]
+struct PrRef {
+    #[serde(rename = "ref")]
+    ref_name: String,
+    sha: String,
+}
+
+/// Fetches repository metadata (default branch, etc.).
+pub async fn get_repo(installation_token: &str, owner: &str, name: &str) -> Result<RepoMetadata> {
+    get_repo_with_base_url(DEFAULT_API_BASE_URL, installation_token, owner, name).await
+}
+
+pub async fn get_repo_with_base_url(
+    api_base_url: &str,
+    installation_token: &str,
+    owner: &str,
+    name: &str,
+) -> Result<RepoMetadata> {
+    let client = client()?;
+    let response = send_json(
+        &client,
+        api_base_url,
+        installation_token,
+        get_repo_request(owner, name),
+    )
+    .await?;
+    Ok(response.json().await?)
+}
+
+/// Resolves the current commit SHA at the tip of a branch.
+pub async fn get_branch_sha(
+    installation_token: &str,
+    owner: &str,
+    name: &str,
+    branch: &str,
+) -> Result<String> {
+    get_branch_sha_with_base_url(
+        DEFAULT_API_BASE_URL,
+        installation_token,
+        owner,
+        name,
+        branch,
+    )
+    .await
+}
+
+pub async fn get_branch_sha_with_base_url(
+    api_base_url: &str,
+    installation_token: &str,
+    owner: &str,
+    name: &str,
+    branch: &str,
+) -> Result<String> {
+    let client = client()?;
+    let response = send_json(
+        &client,
+        api_base_url,
+        installation_token,
+        get_branch_request(owner, name, branch),
+    )
+    .await?;
+    let body: BranchResponse = response.json().await?;
+    Ok(body.commit.sha)
+}
+
+/// Fetches the head/base refs and SHAs for a pull request.
+pub async fn get_pull_request_refs(
+    installation_token: &str,
+    owner: &str,
+    name: &str,
+    pr_number: u64,
+) -> Result<PullRequestRefs> {
+    get_pull_request_refs_with_base_url(
+        DEFAULT_API_BASE_URL,
+        installation_token,
+        owner,
+        name,
+        pr_number,
+    )
+    .await
+}
+
+pub async fn get_pull_request_refs_with_base_url(
+    api_base_url: &str,
+    installation_token: &str,
+    owner: &str,
+    name: &str,
+    pr_number: u64,
+) -> Result<PullRequestRefs> {
+    let client = client()?;
+    let response = send_json(
+        &client,
+        api_base_url,
+        installation_token,
+        get_pull_request_request(owner, name, pr_number),
+    )
+    .await?;
+    let body: PullRequestMetaResponse = response.json().await?;
+    Ok(PullRequestRefs {
+        head_ref: body.head.ref_name,
+        head_sha: body.head.sha,
+        base_ref: body.base.ref_name,
+        base_sha: body.base.sha,
+    })
+}
+
+fn get_repo_request(owner: &str, name: &str) -> GitHubRequest {
+    GitHubRequest {
+        method: "GET",
+        path: format!("/repos/{owner}/{name}"),
+        body: serde_json::Value::Null,
+    }
+}
+
+fn get_branch_request(owner: &str, name: &str, branch: &str) -> GitHubRequest {
+    GitHubRequest {
+        method: "GET",
+        path: format!("/repos/{owner}/{name}/branches/{branch}"),
+        body: serde_json::Value::Null,
+    }
+}
+
+fn get_pull_request_request(owner: &str, name: &str, pr_number: u64) -> GitHubRequest {
+    GitHubRequest {
+        method: "GET",
+        path: format!("/repos/{owner}/{name}/pulls/{pr_number}"),
+        body: serde_json::Value::Null,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn get_repo_request_targets_repo_endpoint() {
+        let request = get_repo_request("octo", "repo");
+        assert_eq!(request.method, "GET");
+        assert_eq!(request.path, "/repos/octo/repo");
+    }
+
+    #[test]
+    fn get_branch_request_targets_branch_endpoint() {
+        let request = get_branch_request("octo", "repo", "develop");
+        assert_eq!(request.method, "GET");
+        assert_eq!(request.path, "/repos/octo/repo/branches/develop");
+    }
+
+    #[test]
+    fn get_pull_request_request_targets_pulls_endpoint() {
+        let request = get_pull_request_request("octo", "repo", 7);
+        assert_eq!(request.method, "GET");
+        assert_eq!(request.path, "/repos/octo/repo/pulls/7");
+    }
+
+    #[test]
+    fn repo_metadata_deserializes_default_branch() {
+        let meta: RepoMetadata =
+            serde_json::from_value(json!({ "default_branch": "master", "id": 99 })).unwrap();
+        assert_eq!(meta.default_branch, "master");
+    }
+
+    #[test]
+    fn branch_response_extracts_commit_sha() {
+        let body: BranchResponse =
+            serde_json::from_value(json!({ "name": "main", "commit": { "sha": "abc123" } }))
+                .unwrap();
+        assert_eq!(body.commit.sha, "abc123");
+    }
+
+    #[test]
+    fn pull_request_meta_extracts_head_and_base_refs() {
+        let body: PullRequestMetaResponse = serde_json::from_value(json!({
+            "head": { "ref": "feature", "sha": "headsha" },
+            "base": { "ref": "develop", "sha": "basesha" }
+        }))
+        .unwrap();
+        assert_eq!(body.head.ref_name, "feature");
+        assert_eq!(body.head.sha, "headsha");
+        assert_eq!(body.base.ref_name, "develop");
+        assert_eq!(body.base.sha, "basesha");
+    }
+}
diff --git a/crates/github/src/tasks.rs b/crates/github/src/tasks.rs
index 781eb68..0c91fb1 100644
--- a/crates/github/src/tasks.rs
+++ b/crates/github/src/tasks.rs
@@ -170,6 +170,7 @@ mod tests {
                 "task-1",
                 "OpenCoven/coven-code",
                 &SessionResult {
+                    contract_version: crate::HEADLESS_CONTRACT_VERSION.to_string(),
                     status: SessionStatus::Success,
                     branch: Some("cody/fix-auth".to_string()),
                     commits: vec![],
diff --git a/crates/webhook/src/events.rs b/crates/webhook/src/events.rs
index d8294a6..26cd8e9 100644
--- a/crates/webhook/src/events.rs
+++ b/crates/webhook/src/events.rs
@@ -2,6 +2,7 @@
 
 use coven_github_api::{
     GitHubEvent, IssueAssignedEvent, IssueCommentEvent, IssueLabeledEvent, PrReviewCommentEvent,
+    PrReviewEvent,
 };
 use serde::Deserialize;
 
@@ -13,6 +14,7 @@ pub struct WebhookPayload {
     pub repository: Option<Repository>,
     pub issue: Option<Issue>,
     pub comment: Option<Comment>,
+    pub review: Option<Review>,
     pub label: Option<Label>,
     pub assignee: Option<User>,
     pub pull_request: Option<PullRequest>,
@@ -39,6 +41,9 @@ pub struct Issue {
     pub number: u64,
     pub title: String,
     pub body: Option<String>,
+    /// Present (non-null) only when the "issue" is actually a pull request.
+    /// GitHub delivers PR conversation comments via the `issue_comment` event.
+    pub pull_request: Option<serde_json::Value>,
 }
 
 #[derive(Debug, Deserialize)]
@@ -52,6 +57,15 @@ pub struct Comment {
     pub user: User,
 }
 
+#[derive(Debug, Deserialize)]
+pub struct Review {
+    /// A review can be submitted with no summary body (e.g. a bare approval).
+    pub body: Option<String>,
+    pub user: User,
+    /// `approved`, `changes_requested`, or `commented`.
+    pub state: Option<String>,
+}
+
 #[derive(Debug, Deserialize)]
 pub struct User {
     pub login: String,
@@ -115,6 +129,25 @@ pub fn parse_event(event_type: &str, payload: &WebhookPayload) -> GitHubEvent {
                     issue_number: issue.number,
                     comment_body: comment.body.clone(),
                     commenter_login: comment.user.login.clone(),
+                    on_pull_request: issue.pull_request.is_some(),
+                });
+            }
+        }
+        "pull_request_review" if payload.action.as_deref() == Some("submitted") => {
+            if let (Some(inst), Some(repo), Some(pr), Some(review)) = (
+                &payload.installation,
+                &payload.repository,
+                &payload.pull_request,
+                &payload.review,
+            ) {
+                return GitHubEvent::PullRequestReview(PrReviewEvent {
+                    installation_id: inst.id,
+                    repo_owner: repo.owner.login.clone(),
+                    repo_name: repo.name.clone(),
+                    pr_number: pr.number,
+                    review_body: review.body.clone().unwrap_or_default(),
+                    review_state: review.state.clone().unwrap_or_default(),
+                    reviewer_login: review.user.login.clone(),
                 });
             }
         }
@@ -135,6 +168,7 @@ pub fn parse_event(event_type: &str, payload: &WebhookPayload) -> GitHubEvent {
                 });
             }
         }
+        "ping" => return GitHubEvent::Ping,
         _ => {}
     }
 
diff --git a/crates/webhook/src/routes.rs b/crates/webhook/src/routes.rs
index 01333dc..c862759 100644
--- a/crates/webhook/src/routes.rs
+++ b/crates/webhook/src/routes.rs
@@ -93,6 +93,13 @@ pub async fn handle_webhook(
     let event = parse_event(&event_type, &payload);
     info!(?event_type, "received webhook event");
 
+    // `ping` is GitHub's webhook-configuration handshake — acknowledge it
+    // explicitly so operators get a clear signal the endpoint is wired up.
+    if matches!(event, GitHubEvent::Ping) {
+        info!("webhook ping received — endpoint configured");
+        return (StatusCode::OK, Json(json!({"ok": true, "pong": true}))).into_response();
+    }
+
     // 4. Route event → task.
     if let Some(task) = event_to_task(&state, event) {
         let task_id = task.id.clone();
@@ -153,12 +160,29 @@ fn event_to_task(state: &AppState, event: GitHubEvent) -> Option<Task> {
         }
 
         GitHubEvent::IssueComment(e) => {
-            // Find a familiar mentioned in the comment body.
-            let familiar = state.config.familiars.iter().find(|f| {
-                e.commenter_login != f.bot_username
-                    && e.comment_body
-                        .contains(&format!("@{}", f.bot_username.trim_end_matches("[bot]")))
-            })?;
+            // Find a familiar mentioned in the comment body (skip the bot's own
+            // comments to avoid self-trigger loops).
+            let familiar = state
+                .config
+                .familiars
+                .iter()
+                .find(|f| e.commenter_login != f.bot_username && mentions(&e.comment_body, &f.bot_username))?;
+
+            // GitHub delivers PR conversation comments through `issue_comment`.
+            // Route those through PR iteration so the familiar gets PR context
+            // rather than issue context (the numbers coincide in GitHub).
+            let kind = if e.on_pull_request {
+                TaskKind::AddressReviewComment {
+                    pr_number: e.issue_number,
+                    comment_body: e.comment_body,
+                    diff_hunk: None,
+                }
+            } else {
+                TaskKind::RespondToMention {
+                    issue_number: e.issue_number,
+                    comment_body: e.comment_body,
+                }
+            };
 
             Some(Task {
                 id: uuid::Uuid::new_v4().to_string(),
@@ -166,19 +190,39 @@ fn event_to_task(state: &AppState, event: GitHubEvent) -> Option<Task> {
                 repo_owner: e.repo_owner,
                 repo_name: e.repo_name,
                 familiar_id: familiar.id.clone(),
-                kind: TaskKind::RespondToMention {
-                    issue_number: e.issue_number,
-                    comment_body: e.comment_body,
+                kind,
+            })
+        }
+
+        GitHubEvent::PullRequestReview(e) => {
+            // A submitted review carries a summary body and a verdict. Trigger
+            // on an explicit mention in the body, same as inline comments.
+            let familiar = state
+                .config
+                .familiars
+                .iter()
+                .find(|f| e.reviewer_login != f.bot_username && mentions(&e.review_body, &f.bot_username))?;
+
+            Some(Task {
+                id: uuid::Uuid::new_v4().to_string(),
+                installation_id: e.installation_id,
+                repo_owner: e.repo_owner,
+                repo_name: e.repo_name,
+                familiar_id: familiar.id.clone(),
+                kind: TaskKind::AddressReviewComment {
+                    pr_number: e.pr_number,
+                    comment_body: e.review_body,
+                    diff_hunk: None,
                 },
             })
         }
 
         GitHubEvent::PullRequestReviewComment(e) => {
-            let familiar = state.config.familiars.iter().find(|f| {
-                e.commenter_login != f.bot_username
-                    && e.comment_body
-                        .contains(&format!("@{}", f.bot_username.trim_end_matches("[bot]")))
-            })?;
+            let familiar = state
+                .config
+                .familiars
+                .iter()
+                .find(|f| e.commenter_login != f.bot_username && mentions(&e.comment_body, &f.bot_username))?;
 
             Some(Task {
                 id: uuid::Uuid::new_v4().to_string(),
@@ -194,10 +238,42 @@ fn event_to_task(state: &AppState, event: GitHubEvent) -> Option<Task> {
             })
         }
 
-        GitHubEvent::Unsupported { .. } => None,
+        // `ping` is acknowledged at the handler; it never produces a task.
+        GitHubEvent::Ping | GitHubEvent::Unsupported { .. } => None,
     }
 }
 
+/// Returns true if `body` mentions the familiar's `@handle` as a whole token.
+///
+/// `bot_username` is the GitHub App bot login (e.g. `coven-cody[bot]`); the
+/// `[bot]` suffix is dropped since mentions are written `@coven-cody`. Matching
+/// is boundary-aware: `@cody` inside `@codyx`, `@cody-2`, or `email@cody` does
+/// not count, and `@coven-cody/team` (a team mention) is not a bot mention.
+fn mentions(body: &str, bot_username: &str) -> bool {
+    let handle = bot_username.trim_end_matches("[bot]");
+    if handle.is_empty() {
+        return false;
+    }
+    let needle = format!("@{handle}");
+    let mut offset = 0;
+    while let Some(pos) = body[offset..].find(&needle) {
+        let start = offset + pos;
+        let end = start + needle.len();
+        let before = body[..start].chars().next_back();
+        let after = body[end..].chars().next();
+        // The character before `@` must be a separator (or start of string),
+        // and the character after the handle must not continue an identifier.
+        let boundary_before = before.is_none_or(|c| !c.is_alphanumeric() && c != '@');
+        let boundary_after =
+            after.is_none_or(|c| !(c.is_alphanumeric() || c == '-' || c == '_' || c == '/'));
+        if boundary_before && boundary_after {
+            return true;
+        }
+        offset = start + 1;
+    }
+    false
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -306,6 +382,7 @@ mod tests {
                 issue_number: 42,
                 comment_body: "@coven-cody thanks, I opened a PR.".to_string(),
                 commenter_login: "coven-cody[bot]".to_string(),
+                on_pull_request: false,
             }),
         );
 
@@ -329,4 +406,120 @@ mod tests {
 
         assert!(task.is_none());
     }
+
+    #[test]
+    fn issue_comment_on_pr_routes_to_pr_iteration() {
+        let state = app_state();
+        let task = event_to_task(
+            &state,
+            GitHubEvent::IssueComment(IssueCommentEvent {
+                installation_id: 123,
+                repo_owner: "OpenCoven".to_string(),
+                repo_name: "coven-code".to_string(),
+                issue_number: 73,
+                comment_body: "@coven-cody the lint is still failing".to_string(),
+                commenter_login: "octocat".to_string(),
+                on_pull_request: true,
+            }),
+        )
+        .expect("a mention on a PR comment should create a task");
+
+        match task.kind {
+            TaskKind::AddressReviewComment {
+                pr_number,
+                diff_hunk,
+                ..
+            } => {
+                assert_eq!(pr_number, 73);
+                assert!(diff_hunk.is_none());
+            }
+            other => panic!("expected AddressReviewComment for a PR comment, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn issue_comment_on_issue_routes_to_respond_to_mention() {
+        let state = app_state();
+        let task = event_to_task(
+            &state,
+            GitHubEvent::IssueComment(IssueCommentEvent {
+                installation_id: 123,
+                repo_owner: "OpenCoven".to_string(),
+                repo_name: "coven-code".to_string(),
+                issue_number: 42,
+                comment_body: "@coven-cody can you take a look?".to_string(),
+                commenter_login: "octocat".to_string(),
+                on_pull_request: false,
+            }),
+        )
+        .expect("a mention on an issue comment should create a task");
+
+        match task.kind {
+            TaskKind::RespondToMention { issue_number, .. } => assert_eq!(issue_number, 42),
+            other => panic!("expected RespondToMention for an issue comment, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn submitted_review_mention_routes_to_pr_iteration() {
+        let state = app_state();
+        let task = event_to_task(
+            &state,
+            GitHubEvent::PullRequestReview(coven_github_api::PrReviewEvent {
+                installation_id: 123,
+                repo_owner: "OpenCoven".to_string(),
+                repo_name: "coven-code".to_string(),
+                pr_number: 73,
+                review_body: "@coven-cody please add test coverage before merge.".to_string(),
+                review_state: "changes_requested".to_string(),
+                reviewer_login: "octocat".to_string(),
+            }),
+        )
+        .expect("a mention in a review body should create a task");
+
+        match task.kind {
+            TaskKind::AddressReviewComment { pr_number, .. } => assert_eq!(pr_number, 73),
+            other => panic!("expected AddressReviewComment for a review, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn submitted_review_without_mention_is_ignored() {
+        let state = app_state();
+        let task = event_to_task(
+            &state,
+            GitHubEvent::PullRequestReview(coven_github_api::PrReviewEvent {
+                installation_id: 123,
+                repo_owner: "OpenCoven".to_string(),
+                repo_name: "coven-code".to_string(),
+                pr_number: 73,
+                review_body: "LGTM, nice work!".to_string(),
+                review_state: "approved".to_string(),
+                reviewer_login: "octocat".to_string(),
+            }),
+        );
+
+        assert!(task.is_none());
+    }
+
+    #[test]
+    fn ping_event_produces_no_task() {
+        let state = app_state();
+        assert!(event_to_task(&state, GitHubEvent::Ping).is_none());
+    }
+
+    #[test]
+    fn mention_matching_is_boundary_aware() {
+        // Exact handle (with the [bot] suffix stripped) matches.
+        assert!(mentions("hey @coven-cody can you help", "coven-cody[bot]"));
+        // Trailing identifier characters must not be swallowed into the handle.
+        assert!(!mentions("ping @coven-codyx instead", "coven-cody[bot]"));
+        assert!(!mentions("ping @coven-cody-2 instead", "coven-cody[bot]"));
+        // A team mention (`@org/team`) is not a bot mention.
+        assert!(!mentions("cc @coven-cody/maintainers", "coven-cody[bot]"));
+        // An email-like local part is not a mention.
+        assert!(!mentions("mail user@coven-cody.example", "coven-cody[bot]"));
+        // Mention at end of string still matches.
+        assert!(mentions("over to you @coven-cody", "coven-cody[bot]"));
+    }
 }
diff --git a/crates/webhook/tests/fixtures/issue_assigned.json b/crates/webhook/tests/fixtures/issue_assigned.json
new file mode 100644
index 0000000..b177eec
--- /dev/null
+++ b/crates/webhook/tests/fixtures/issue_assigned.json
@@ -0,0 +1,18 @@
+{
+  "action": "assigned",
+  "issue": {
+    "number": 42,
+    "title": "Fix OAuth token refresh",
+    "body": "The refresh path drops clock skew between client and auth server.",
+    "state": "open",
+    "user": { "login": "octocat" }
+  },
+  "assignee": { "login": "coven-cody[bot]" },
+  "repository": {
+    "name": "coven-code",
+    "owner": { "login": "OpenCoven" },
+    "default_branch": "main"
+  },
+  "installation": { "id": 987654 },
+  "sender": { "login": "octocat" }
+}
diff --git a/crates/webhook/tests/fixtures/issue_comment_created.json b/crates/webhook/tests/fixtures/issue_comment_created.json
new file mode 100644
index 0000000..2769c2f
--- /dev/null
+++ b/crates/webhook/tests/fixtures/issue_comment_created.json
@@ -0,0 +1,22 @@
+{
+  "action": "created",
+  "issue": {
+    "number": 42,
+    "title": "Fix OAuth token refresh",
+    "body": "The refresh path drops clock skew.",
+    "state": "open",
+    "user": { "login": "octocat" }
+  },
+  "comment": {
+    "id": 1122334455,
+    "body": "@coven-cody can you take a look at this one?",
+    "user": { "login": "octocat" }
+  },
+  "repository": {
+    "name": "coven-code",
+    "owner": { "login": "OpenCoven" },
+    "default_branch": "main"
+  },
+  "installation": { "id": 987654 },
+  "sender": { "login": "octocat" }
+}
diff --git a/crates/webhook/tests/fixtures/issue_comment_on_pr.json b/crates/webhook/tests/fixtures/issue_comment_on_pr.json
new file mode 100644
index 0000000..e93090a
--- /dev/null
+++ b/crates/webhook/tests/fixtures/issue_comment_on_pr.json
@@ -0,0 +1,26 @@
+{
+  "action": "created",
+  "issue": {
+    "number": 73,
+    "title": "Add clock-skew buffer to token refresh",
+    "body": "Implements the fix for #42.",
+    "state": "open",
+    "user": { "login": "coven-cody[bot]" },
+    "pull_request": {
+      "url": "https://api.github.com/repos/OpenCoven/coven-code/pulls/73",
+      "html_url": "https://github.com/OpenCoven/coven-code/pull/73"
+    }
+  },
+  "comment": {
+    "id": 2233445566,
+    "body": "@coven-cody the lint is still failing on this PR, mind fixing it?",
+    "user": { "login": "octocat" }
+  },
+  "repository": {
+    "name": "coven-code",
+    "owner": { "login": "OpenCoven" },
+    "default_branch": "main"
+  },
+  "installation": { "id": 987654 },
+  "sender": { "login": "octocat" }
+}
diff --git a/crates/webhook/tests/fixtures/issue_labeled.json b/crates/webhook/tests/fixtures/issue_labeled.json
new file mode 100644
index 0000000..7cf8072
--- /dev/null
+++ b/crates/webhook/tests/fixtures/issue_labeled.json
@@ -0,0 +1,18 @@
+{
+  "action": "labeled",
+  "issue": {
+    "number": 42,
+    "title": "Fix the spell compiler",
+    "body": "It loses sigils on nested casts.",
+    "state": "open",
+    "user": { "login": "octocat" }
+  },
+  "label": { "name": "coven:fix", "color": "5319e7" },
+  "repository": {
+    "name": "coven-code",
+    "owner": { "login": "OpenCoven" },
+    "default_branch": "main"
+  },
+  "installation": { "id": 987654 },
+  "sender": { "login": "octocat" }
+}
diff --git a/crates/webhook/tests/fixtures/ping.json b/crates/webhook/tests/fixtures/ping.json
new file mode 100644
index 0000000..4ca9a69
--- /dev/null
+++ b/crates/webhook/tests/fixtures/ping.json
@@ -0,0 +1,20 @@
+{
+  "zen": "Non-blocking is better than blocking.",
+  "hook_id": 44556677,
+  "hook": {
+    "type": "App",
+    "id": 44556677,
+    "events": [
+      "issues",
+      "issue_comment",
+      "pull_request_review",
+      "pull_request_review_comment"
+    ]
+  },
+  "repository": {
+    "name": "coven-code",
+    "owner": { "login": "OpenCoven" }
+  },
+  "installation": { "id": 987654 },
+  "sender": { "login": "octocat" }
+}
diff --git a/crates/webhook/tests/fixtures/pull_request_review_comment_created.json b/crates/webhook/tests/fixtures/pull_request_review_comment_created.json
new file mode 100644
index 0000000..755efc3
--- /dev/null
+++ b/crates/webhook/tests/fixtures/pull_request_review_comment_created.json
@@ -0,0 +1,22 @@
+{
+  "action": "created",
+  "comment": {
+    "id": 6677889900,
+    "body": "@coven-cody this off-by-one looks wrong — should it be `<=`?",
+    "user": { "login": "octocat" },
+    "path": "src/auth/refresh.rs",
+    "diff_hunk": "@@ -10,3 +10,5 @@\n-    if now > expiry {\n+    if now >= expiry {"
+  },
+  "pull_request": {
+    "number": 73,
+    "title": "Add clock-skew buffer to token refresh",
+    "state": "open"
+  },
+  "repository": {
+    "name": "coven-code",
+    "owner": { "login": "OpenCoven" },
+    "default_branch": "main"
+  },
+  "installation": { "id": 987654 },
+  "sender": { "login": "octocat" }
+}
diff --git a/crates/webhook/tests/fixtures/pull_request_review_submitted.json b/crates/webhook/tests/fixtures/pull_request_review_submitted.json
new file mode 100644
index 0000000..37b163e
--- /dev/null
+++ b/crates/webhook/tests/fixtures/pull_request_review_submitted.json
@@ -0,0 +1,21 @@
+{
+  "action": "submitted",
+  "review": {
+    "id": 5566778899,
+    "body": "@coven-cody two of these branches still need test coverage — please address before merge.",
+    "state": "changes_requested",
+    "user": { "login": "octocat" }
+  },
+  "pull_request": {
+    "number": 73,
+    "title": "Add clock-skew buffer to token refresh",
+    "state": "open"
+  },
+  "repository": {
+    "name": "coven-code",
+    "owner": { "login": "OpenCoven" },
+    "default_branch": "main"
+  },
+  "installation": { "id": 987654 },
+  "sender": { "login": "octocat" }
+}
diff --git a/crates/webhook/tests/parse_fixtures.rs b/crates/webhook/tests/parse_fixtures.rs
new file mode 100644
index 0000000..e76b93c
--- /dev/null
+++ b/crates/webhook/tests/parse_fixtures.rs
@@ -0,0 +1,128 @@
+//! Fixture-driven parsing tests.
+//!
+//! Each fixture is a trimmed but structurally faithful GitHub webhook payload
+//! captured from the real `X-GitHub-Event` deliveries we subscribe to. They
+//! exercise `parse_event` end-to-end (raw JSON → typed `GitHubEvent`), guarding
+//! against drift between GitHub's payload shape and our partial deserializers.
+
+use coven_github_api::GitHubEvent;
+use coven_github_webhook::events::{parse_event, WebhookPayload};
+
+/// Parse a fixture string under the given `X-GitHub-Event` type.
+fn parse(event_type: &str, raw: &str) -> GitHubEvent {
+    let payload: WebhookPayload =
+        serde_json::from_str(raw).expect("fixture should deserialize as a WebhookPayload");
+    parse_event(event_type, &payload)
+}
+
+#[test]
+fn issue_assigned_fixture_parses() {
+    let event = parse(
+        "issues",
+        include_str!("fixtures/issue_assigned.json"),
+    );
+    match event {
+        GitHubEvent::IssueAssigned(e) => {
+            assert_eq!(e.installation_id, 987654);
+            assert_eq!(e.repo_owner, "OpenCoven");
+            assert_eq!(e.repo_name, "coven-code");
+            assert_eq!(e.issue_number, 42);
+            assert_eq!(e.issue_title, "Fix OAuth token refresh");
+            assert_eq!(e.assignee_login, "coven-cody[bot]");
+        }
+        other => panic!("expected IssueAssigned, got {other:?}"),
+    }
+}
+
+#[test]
+fn issue_labeled_fixture_parses() {
+    let event = parse("issues", include_str!("fixtures/issue_labeled.json"));
+    match event {
+        GitHubEvent::IssueLabeled(e) => {
+            assert_eq!(e.issue_number, 42);
+            assert_eq!(e.label_name, "coven:fix");
+        }
+        other => panic!("expected IssueLabeled, got {other:?}"),
+    }
+}
+
+#[test]
+fn issue_comment_fixture_parses_as_issue_comment() {
+    let event = parse(
+        "issue_comment",
+        include_str!("fixtures/issue_comment_created.json"),
+    );
+    match event {
+        GitHubEvent::IssueComment(e) => {
+            assert_eq!(e.issue_number, 42);
+            assert_eq!(e.commenter_login, "octocat");
+            assert!(
+                !e.on_pull_request,
+                "a plain issue comment must not be flagged as a PR comment"
+            );
+            assert!(e.comment_body.contains("@coven-cody"));
+        }
+        other => panic!("expected IssueComment, got {other:?}"),
+    }
+}
+
+#[test]
+fn issue_comment_on_pr_fixture_is_flagged_as_pull_request() {
+    // GitHub delivers PR conversation comments via `issue_comment`; the only
+    // signal that distinguishes them is `issue.pull_request`.
+    let event = parse(
+        "issue_comment",
+        include_str!("fixtures/issue_comment_on_pr.json"),
+    );
+    match event {
+        GitHubEvent::IssueComment(e) => {
+            assert_eq!(e.issue_number, 73);
+            assert!(
+                e.on_pull_request,
+                "a comment carrying issue.pull_request must be flagged as a PR comment"
+            );
+        }
+        other => panic!("expected IssueComment, got {other:?}"),
+    }
+}
+
+#[test]
+fn pull_request_review_fixture_parses() {
+    let event = parse(
+        "pull_request_review",
+        include_str!("fixtures/pull_request_review_submitted.json"),
+    );
+    match event {
+        GitHubEvent::PullRequestReview(e) => {
+            assert_eq!(e.pr_number, 73);
+            assert_eq!(e.review_state, "changes_requested");
+            assert_eq!(e.reviewer_login, "octocat");
+            assert!(e.review_body.contains("test coverage"));
+        }
+        other => panic!("expected PullRequestReview, got {other:?}"),
+    }
+}
+
+#[test]
+fn pull_request_review_comment_fixture_parses() {
+    let event = parse(
+        "pull_request_review_comment",
+        include_str!("fixtures/pull_request_review_comment_created.json"),
+    );
+    match event {
+        GitHubEvent::PullRequestReviewComment(e) => {
+            assert_eq!(e.pr_number, 73);
+            assert_eq!(e.commenter_login, "octocat");
+        }
+        other => panic!("expected PullRequestReviewComment, got {other:?}"),
+    }
+}
+
+#[test]
+fn ping_fixture_parses_as_ping() {
+    let event = parse("ping", include_str!("fixtures/ping.json"));
+    assert!(
+        matches!(event, GitHubEvent::Ping),
+        "ping delivery should parse as GitHubEvent::Ping, got {event:?}"
+    );
+}
diff --git a/crates/worker/src/brief.rs b/crates/worker/src/brief.rs
index 854b8f5..2dce3d7 100644
--- a/crates/worker/src/brief.rs
+++ b/crates/worker/src/brief.rs
@@ -3,18 +3,30 @@
 use serde::{Deserialize, Serialize};
 use std::path::Path;
 
-use coven_github_api::{Task, TaskKind};
+use coven_github_api::{Task, TaskKind, HEADLESS_CONTRACT_VERSION};
 use coven_github_config::FamiliarConfig;
 
+fn default_contract_version() -> String {
+    HEADLESS_CONTRACT_VERSION.to_string()
+}
+
 /// The session-brief.json schema injected into coven-code --headless.
+///
+/// The brief is intentionally tokenless: the agent receives read context only.
+/// Git authentication is injected out-of-band (env / GIT_ASKPASS) and GitHub
+/// write authority (comments, Check Runs, branches, PRs) stays with the adapter
+/// behind its publication gate. See issue #4.
 #[derive(Debug, Serialize, Deserialize)]
 pub struct SessionBrief {
+    /// Contract major version this brief is written against. See
+    /// `docs/headless-contract.md`.
+    #[serde(default = "default_contract_version")]
+    pub contract_version: String,
     pub trigger: String,
     pub repo: RepoBrief,
     pub task: TaskBrief,
     pub familiar: FamiliarBrief,
     pub workspace: WorkspaceBrief,
-    pub auth: AuthBrief,
 }
 
 #[derive(Debug, Serialize, Deserialize)]
@@ -57,17 +69,15 @@ pub struct WorkspaceBrief {
     pub root: String,
 }
 
-#[derive(Debug, Serialize, Deserialize)]
-pub struct AuthBrief {
-    pub token: String,
-}
-
-/// Build a session brief from a Task and familiar config.
+/// Build a tokenless session brief from a Task and familiar config.
+///
+/// `default_branch` is resolved from live GitHub repository metadata rather than
+/// assuming `main` (see issue #9).
 pub fn build(
     task: &Task,
     familiar: &FamiliarConfig,
-    token: &str,
     workspace: &Path,
+    default_branch: &str,
 ) -> SessionBrief {
     let trigger = match &task.kind {
         TaskKind::FixIssue { .. } => "issue_assigned",
@@ -104,15 +114,17 @@ pub fn build(
     };
 
     SessionBrief {
+        contract_version: HEADLESS_CONTRACT_VERSION.to_string(),
         trigger: trigger.to_string(),
         repo: RepoBrief {
             owner: task.repo_owner.clone(),
             name: task.repo_name.clone(),
+            // No embedded credentials: git auth is injected out-of-band.
             clone_url: format!(
-                "https://x-access-token:{}@github.com/{}/{}.git",
-                token, task.repo_owner, task.repo_name
+                "https://github.com/{}/{}.git",
+                task.repo_owner, task.repo_name
             ),
-            default_branch: "main".to_string(),
+            default_branch: default_branch.to_string(),
         },
         task: task_brief,
         familiar: FamiliarBrief {
@@ -124,8 +136,66 @@ pub fn build(
         workspace: WorkspaceBrief {
             root: workspace.to_string_lossy().to_string(),
         },
-        auth: AuthBrief {
-            token: token.to_string(),
-        },
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use coven_github_api::{Task, TaskKind};
+
+    fn familiar() -> FamiliarConfig {
+        FamiliarConfig {
+            id: "cody".to_string(),
+            display_name: "Cody".to_string(),
+            bot_username: "coven-cody[bot]".to_string(),
+            model: None,
+            skills: vec![],
+            trigger_labels: vec![],
+        }
+    }
+
+    fn task() -> Task {
+        Task {
+            id: "task-1".to_string(),
+            installation_id: 1,
+            repo_owner: "OpenCoven".to_string(),
+            repo_name: "coven-code".to_string(),
+            familiar_id: "cody".to_string(),
+            kind: TaskKind::FixIssue {
+                issue_number: 42,
+                issue_title: "Fix auth".to_string(),
+                issue_body: "Body".to_string(),
+            },
+        }
+    }
+
+    #[test]
+    fn brief_uses_resolved_default_branch_not_hardcoded_main() {
+        let brief = build(&task(), &familiar(), Path::new("/tmp/ws"), "develop");
+        assert_eq!(brief.repo.default_branch, "develop");
+    }
+
+    #[test]
+    fn brief_serialization_never_contains_token_or_auth_fields() {
+        let brief = build(&task(), &familiar(), Path::new("/tmp/ws"), "main");
+        let value = serde_json::to_value(&brief).expect("brief should serialize");
+        let json = serde_json::to_string(&brief).expect("brief should serialize");
+
+        // The brief must never carry credentials (issue #4). Check for the
+        // serialized field keys rather than raw substrings, since free-text
+        // task content may legitimately mention "auth"/"token".
+        assert!(
+            value.get("auth").is_none(),
+            "brief leaked an auth field: {json}"
+        );
+        assert!(
+            !json.contains("\"token\""),
+            "brief leaked a token field: {json}"
+        );
+        assert!(
+            !json.contains("x-access-token"),
+            "clone_url leaked an embedded credential: {json}"
+        );
     }
 }
diff --git a/crates/worker/src/lib.rs b/crates/worker/src/lib.rs
index cd9d8ef..0a677f5 100644
--- a/crates/worker/src/lib.rs
+++ b/crates/worker/src/lib.rs
@@ -6,8 +6,8 @@ use tokio::process::Command;
 use tracing::{error, info, warn};
 
 use coven_github_api::{
-    check_run, installation, pr, tasks::TaskStore, SessionResult, SessionStatus, Task, TaskKind,
-    DEFAULT_API_BASE_URL,
+    check_run, installation, pr, repo, tasks::TaskStore, SessionResult, SessionStatus, Task,
+    TaskKind, DEFAULT_API_BASE_URL,
 };
 use coven_github_config::Config;
 
@@ -59,14 +59,19 @@ async fn execute_task(config: &Config, task_store: TaskStore, task: Task) -> Res
     )
     .await?;
 
-    // Create Check Run.
+    // Resolve target refs and base branch from live GitHub state. Check Runs
+    // must attach to an immutable commit SHA, and PRs must target the repo's
+    // actual base branch rather than a hardcoded "main".
+    let targets = resolve_targets(api_base_url, &token, &task).await?;
+
+    // Create Check Run against the resolved head SHA.
     let check_name = format!("{} — {}", familiar.display_name, task_title(&task.kind));
     let check_id = check_run::create_with_base_url(
         api_base_url,
         &token,
         &task.repo_owner,
         &task.repo_name,
-        "HEAD", // TODO: resolve head SHA
+        &targets.head_sha,
         &check_name,
         config
             .server
@@ -104,7 +109,7 @@ async fn execute_task(config: &Config, task_store: TaskStore, task: Task) -> Res
     let workspace = config.worker.workspace_root.join(&task.id);
     tokio::fs::create_dir_all(&workspace).await?;
 
-    let brief = brief::build(&task, familiar, &token, &workspace);
+    let brief = brief::build(&task, familiar, &workspace, &targets.default_branch);
     let brief_path = workspace.join("session-brief.json");
     let result_path = workspace.join("result.json");
     tokio::fs::write(&brief_path, serde_json::to_string_pretty(&brief)?).await?;
@@ -122,7 +127,14 @@ async fn execute_task(config: &Config, task_store: TaskStore, task: Task) -> Res
     )
     .await?;
 
-    let result = run_with_retry(config, &brief_path, &result_path, config.worker.max_retries).await;
+    let result = run_with_retry(
+        config,
+        &brief_path,
+        &result_path,
+        &token,
+        config.worker.max_retries,
+    )
+    .await;
 
     match result {
         Ok(session_result) => {
@@ -139,7 +151,7 @@ async fn execute_task(config: &Config, task_store: TaskStore, task: Task) -> Res
                         &task.repo_owner,
                         &task.repo_name,
                         branch,
-                        "main",
+                        &targets.base_ref,
                         &format!(
                             "{} (#{} via Coven)",
                             session_result.summary,
@@ -217,11 +229,12 @@ async fn run_with_retry(
     config: &Config,
     brief_path: &PathBuf,
     result_path: &PathBuf,
+    git_token: &str,
     max_retries: u32,
 ) -> Result<SessionResult> {
     let mut attempts = 0;
     loop {
-        match run_coven_code(config, brief_path, result_path).await {
+        match run_coven_code(config, brief_path, result_path, git_token).await {
             Ok(r) => return Ok(r),
             Err(e) if attempts < max_retries => {
                 warn!("coven-code attempt {attempts} failed ({e:#}), retrying…");
@@ -237,6 +250,7 @@ async fn run_coven_code(
     config: &Config,
     brief_path: &PathBuf,
     result_path: &PathBuf,
+    git_token: &str,
 ) -> Result<SessionResult> {
     let mut child = Command::new(&config.worker.coven_code_bin)
         .arg("--headless")
@@ -244,6 +258,9 @@ async fn run_coven_code(
         .arg(brief_path)
         .arg("--output")
         .arg(result_path)
+        // Git auth is injected via the environment, never written to the
+        // session brief or any durable artifact (issue #4).
+        .env("COVEN_GIT_TOKEN", git_token)
         .spawn()?;
 
     let status = match tokio::time::timeout(
@@ -296,6 +313,57 @@ fn task_title(kind: &TaskKind) -> String {
     }
 }
 
+/// Refs resolved from live GitHub state for a task.
+struct ResolvedTargets {
+    /// Repository default branch (for the session brief).
+    default_branch: String,
+    /// Branch a draft PR should target.
+    base_ref: String,
+    /// Immutable commit SHA the Check Run attaches to.
+    head_sha: String,
+}
+
+/// Resolves the repository default branch and the immutable target refs a task
+/// operates on. Issue tasks target the default branch tip; PR review-comment
+/// tasks target the PR's own head/base refs.
+async fn resolve_targets(api_base_url: &str, token: &str, task: &Task) -> Result<ResolvedTargets> {
+    let meta = repo::get_repo_with_base_url(api_base_url, token, &task.repo_owner, &task.repo_name)
+        .await?;
+
+    match &task.kind {
+        TaskKind::AddressReviewComment { pr_number, .. } => {
+            let refs = repo::get_pull_request_refs_with_base_url(
+                api_base_url,
+                token,
+                &task.repo_owner,
+                &task.repo_name,
+                *pr_number,
+            )
+            .await?;
+            Ok(ResolvedTargets {
+                default_branch: meta.default_branch,
+                base_ref: refs.base_ref,
+                head_sha: refs.head_sha,
+            })
+        }
+        TaskKind::FixIssue { .. } | TaskKind::RespondToMention { .. } => {
+            let head_sha = repo::get_branch_sha_with_base_url(
+                api_base_url,
+                token,
+                &task.repo_owner,
+                &task.repo_name,
+                &meta.default_branch,
+            )
+            .await?;
+            Ok(ResolvedTargets {
+                base_ref: meta.default_branch.clone(),
+                default_branch: meta.default_branch,
+                head_sha,
+            })
+        }
+    }
+}
+
 fn task_issue_number(kind: &TaskKind) -> Option<u64> {
     match kind {
         TaskKind::FixIssue { issue_number, .. } => Some(*issue_number),
@@ -358,7 +426,7 @@ mod tests {
         fs::write(&brief_path, "{}").expect("brief should be written");
 
         let started = Instant::now();
-        let result = run_coven_code(&config, &brief_path, &result_path).await;
+        let result = run_coven_code(&config, &brief_path, &result_path, "test-token").await;
 
         assert!(result.is_err());
         assert!(
diff --git a/crates/worker/tests/contract.rs b/crates/worker/tests/contract.rs
new file mode 100644
index 0000000..7e0c10c
--- /dev/null
+++ b/crates/worker/tests/contract.rs
@@ -0,0 +1,97 @@
+//! Headless execution contract conformance.
+//!
+//! Pins the adapter's wire types to the locked contract in
+//! `docs/headless-contract.md` via the golden fixtures in `docs/contracts/`.
+//! If these fail, either the runtime contract drifted or the docs are stale —
+//! fix one of them, do not just bless the test.
+
+use coven_github_api::{ExitReason, SessionResult, SessionStatus, HEADLESS_CONTRACT_VERSION};
+use coven_github_worker::brief::SessionBrief;
+
+fn fixture(name: &str) -> String {
+    let path = format!(
+        "{}/../../docs/contracts/{}",
+        env!("CARGO_MANIFEST_DIR"),
+        name
+    );
+    std::fs::read_to_string(&path).unwrap_or_else(|e| panic!("missing fixture {path}: {e}"))
+}
+
+#[test]
+fn golden_session_brief_deserializes_into_adapter_type() {
+    let raw = fixture("session-brief.example.json");
+    let brief: SessionBrief =
+        serde_json::from_str(&raw).expect("golden brief must match SessionBrief");
+
+    assert_eq!(brief.contract_version, HEADLESS_CONTRACT_VERSION);
+    assert_eq!(brief.trigger, "issue_assigned");
+    assert_eq!(brief.repo.owner, "OpenCoven");
+    assert_eq!(brief.repo.default_branch, "main");
+    assert_eq!(brief.familiar.id, "cody");
+
+    // Round-trips without losing or inventing fields.
+    let reserialized = serde_json::to_value(&brief).expect("brief reserializes");
+    let original: serde_json::Value = serde_json::from_str(&raw).expect("fixture is valid json");
+    assert_eq!(reserialized, original, "brief did not round-trip cleanly");
+}
+
+#[test]
+fn golden_result_deserializes_into_adapter_type() {
+    let raw = fixture("result.example.json");
+    let result: SessionResult =
+        serde_json::from_str(&raw).expect("golden result must match SessionResult");
+
+    assert_eq!(result.contract_version, HEADLESS_CONTRACT_VERSION);
+    assert_eq!(result.status, SessionStatus::Success);
+    assert_eq!(result.branch.as_deref(), Some("cody/fix-issue-42"));
+    assert_eq!(result.commits.len(), 1);
+    assert_eq!(result.files_changed, vec!["src/auth/refresh.rs".to_string()]);
+    assert!(result.exit_reason.is_none());
+}
+
+#[test]
+fn result_without_contract_version_defaults_to_current() {
+    // Backward compatibility: a runtime that predates the version field still
+    // parses, and is treated as the current major version.
+    let raw = r#"{
+        "status": "failure",
+        "branch": null,
+        "commits": [],
+        "files_changed": [],
+        "summary": "Could not reproduce.",
+        "pr_body": "",
+        "exit_reason": "ambiguous_spec"
+    }"#;
+    let result: SessionResult = serde_json::from_str(raw).expect("legacy result must parse");
+    assert_eq!(result.contract_version, HEADLESS_CONTRACT_VERSION);
+    assert_eq!(result.status, SessionStatus::Failure);
+    assert_eq!(result.exit_reason, Some(ExitReason::AmbiguousSpec));
+}
+
+#[test]
+fn every_result_status_variant_is_wire_named_as_documented() {
+    for (json, expected) in [
+        ("success", SessionStatus::Success),
+        ("failure", SessionStatus::Failure),
+        ("partial", SessionStatus::Partial),
+        ("needs_input", SessionStatus::NeedsInput),
+    ] {
+        let parsed: SessionStatus =
+            serde_json::from_str(&format!("\"{json}\"")).expect("documented status must parse");
+        assert_eq!(parsed, expected);
+    }
+}
+
+#[test]
+fn every_exit_reason_variant_is_wire_named_as_documented() {
+    for (json, expected) in [
+        ("test_failure", ExitReason::TestFailure),
+        ("ambiguous_spec", ExitReason::AmbiguousSpec),
+        ("git_conflict", ExitReason::GitConflict),
+        ("infra_error", ExitReason::InfraError),
+    ] {
+        let parsed: ExitReason =
+            serde_json::from_str(&format!("\"{json}\"")).expect("documented exit_reason must parse");
+        assert_eq!(parsed, expected);
+    }
+}
diff --git a/docs/app-manifest.json b/docs/app-manifest.json
new file mode 100644
index 0000000..70fd0e7
--- /dev/null
+++ b/docs/app-manifest.json
@@ -0,0 +1,26 @@
+{
+  "name": "coven-cody",
+  "url": "https://opencoven.ai",
+  "description": "Coven-native GitHub coding agent. Assign an issue to a familiar bot and it plans, edits, commits, and opens a PR — with live oversight in CovenCave.",
+  "hook_attributes": {
+    "url": "https://your-host/webhook",
+    "active": true
+  },
+  "redirect_url": "https://your-host/app/created",
+  "public": false,
+  "default_permissions": {
+    "contents": "write",
+    "issues": "write",
+    "pull_requests": "write",
+    "checks": "write",
+    "metadata": "read"
+  },
+  "default_events": [
+    "issues",
+    "issue_comment",
+    "pull_request_review",
+    "pull_request_review_comment",
+    "check_suite",
+    "check_run"
+  ]
+}
diff --git a/docs/contracts/result.example.json b/docs/contracts/result.example.json
new file mode 100644
index 0000000..53fd6ac
--- /dev/null
+++ b/docs/contracts/result.example.json
@@ -0,0 +1,12 @@
+{
+  "contract_version": "1",
+  "status": "success",
+  "branch": "cody/fix-issue-42",
+  "commits": [
+    { "sha": "a1b2c3d4e5f6", "message": "Add 60s clock-skew buffer to OAuth refresh" }
+  ],
+  "files_changed": ["src/auth/refresh.rs"],
+  "summary": "Fixed OAuth token refresh by adding a 60-second clock skew buffer.",
+  "pr_body": "## Hey, I'm Cody 🦄\n\nIssue #42 traced to the OAuth refresh path not accounting for clock skew. I added a 60-second buffer to the expiry check.\n\n**Changed:** `src/auth/refresh.rs` (+12 / -3)\n**Tests:** 8/8 passing (added 2 regression cases)\n",
+  "exit_reason": null
+}
diff --git a/docs/contracts/result.schema.json b/docs/contracts/result.schema.json
new file mode 100644
index 0000000..0a86c4c
--- /dev/null
+++ b/docs/contracts/result.schema.json
@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/OpenCoven/coven-github/docs/contracts/result.schema.json",
+  "title": "coven-code headless result envelope",
+  "description": "Terminal task state coven-code --headless writes to --output. Contract version 1.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["status", "commits", "files_changed", "summary", "pr_body"],
+  "properties": {
+    "contract_version": {
+      "type": "string",
+      "const": "1"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["success", "failure", "partial", "needs_input"]
+    },
+    "branch": {
+      "type": ["string", "null"]
+    },
+    "commits": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["sha", "message"],
+        "properties": {
+          "sha": { "type": "string" },
+          "message": { "type": "string" }
+        }
+      }
+    },
+    "files_changed": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "summary": { "type": "string" },
+    "pr_body": { "type": "string" },
+    "exit_reason": {
+      "type": ["string", "null"],
+      "enum": ["test_failure", "ambiguous_spec", "git_conflict", "infra_error", null]
+    }
+  }
+}
diff --git a/docs/contracts/session-brief.example.json b/docs/contracts/session-brief.example.json
new file mode 100644
index 0000000..8ecbc9a
--- /dev/null
+++ b/docs/contracts/session-brief.example.json
@@ -0,0 +1,25 @@
+{
+  "contract_version": "1",
+  "trigger": "issue_assigned",
+  "repo": {
+    "owner": "OpenCoven",
+    "name": "coven-code",
+    "clone_url": "https://github.com/OpenCoven/coven-code.git",
+    "default_branch": "main"
+  },
+  "task": {
+    "kind": "fix_issue",
+    "issue_number": 42,
+    "issue_title": "Fix OAuth token refresh",
+    "issue_body": "The refresh path ignores clock skew between client and auth server."
+  },
+  "familiar": {
+    "id": "cody",
+    "display_name": "Cody",
+    "model": "anthropic/claude-sonnet-4-6",
+    "skills": ["systematic-debugging"]
+  },
+  "workspace": {
+    "root": "/tmp/task-abc123"
+  }
+}
diff --git a/docs/contracts/session-brief.schema.json b/docs/contracts/session-brief.schema.json
new file mode 100644
index 0000000..613a352
--- /dev/null
+++ b/docs/contracts/session-brief.schema.json
@@ -0,0 +1,89 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/OpenCoven/coven-github/docs/contracts/session-brief.schema.json",
+  "title": "coven-code headless session brief",
+  "description": "Tokenless read-context payload the adapter writes for coven-code --headless --context. Contract version 1.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["trigger", "repo", "task", "familiar", "workspace"],
+  "properties": {
+    "contract_version": {
+      "type": "string",
+      "const": "1"
+    },
+    "trigger": {
+      "type": "string",
+      "enum": ["issue_assigned", "pr_review_comment", "issue_mention"]
+    },
+    "repo": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["owner", "name", "clone_url", "default_branch"],
+      "properties": {
+        "owner": { "type": "string" },
+        "name": { "type": "string" },
+        "clone_url": {
+          "type": "string",
+          "description": "HTTPS clone URL without embedded credentials.",
+          "not": { "pattern": "@" }
+        },
+        "default_branch": { "type": "string" }
+      }
+    },
+    "task": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "issue_number", "issue_title", "issue_body"],
+          "properties": {
+            "kind": { "const": "fix_issue" },
+            "issue_number": { "type": "integer", "minimum": 0 },
+            "issue_title": { "type": "string" },
+            "issue_body": { "type": "string" }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "pr_number", "comment_body"],
+          "properties": {
+            "kind": { "const": "address_review_comment" },
+            "pr_number": { "type": "integer", "minimum": 0 },
+            "comment_body": { "type": "string" },
+            "diff_hunk": { "type": ["string", "null"] }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "issue_number", "comment_body"],
+          "properties": {
+            "kind": { "const": "respond_to_mention" },
+            "issue_number": { "type": "integer", "minimum": 0 },
+            "comment_body": { "type": "string" }
+          }
+        }
+      ]
+    },
+    "familiar": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "display_name", "skills"],
+      "properties": {
+        "id": { "type": "string" },
+        "display_name": { "type": "string" },
+        "model": { "type": ["string", "null"] },
+        "skills": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "workspace": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["root"],
+      "properties": {
+        "root": { "type": "string" }
+      }
+    }
+  }
+}
diff --git a/docs/headless-contract.md b/docs/headless-contract.md
new file mode 100644
index 0000000..f71eb54
--- /dev/null
+++ b/docs/headless-contract.md
@@ -0,0 +1,258 @@
+# coven-code Headless Execution Contract
+
+**Contract version: `1`** · Status: **Locked** (V1 / M1)
+
+This document is the single source of truth for the interface between
+`coven-github` (the GitHub ingress adapter) and `coven-code` (the execution
+runtime) when the runtime is invoked in headless mode.
+
+It is normative. Where the prose in [`COVEN-GITHUB.md`](../COVEN-GITHUB.md) or any
+other doc disagrees with this file, **this file wins**. Both repositories MUST
+implement exactly what is specified here, and changes require a contract version
+bump (see [Versioning](#versioning)).
+
+The contract is enforced on the `coven-github` side by golden fixtures in
+[`docs/contracts/`](contracts/) and a conformance test
+(`crates/github/tests/contract.rs`) that round-trips those fixtures through the
+Rust types. `coven-code` MUST validate its emitted `result.json` against
+[`docs/contracts/result.schema.json`](contracts/result.schema.json) and its
+accepted `session-brief.json` against
+[`docs/contracts/session-brief.schema.json`](contracts/session-brief.schema.json).
+
+The key words MUST, MUST NOT, SHOULD, and MAY are used as in RFC 2119.
+
+---
+
+## 1. Invocation
+
+The adapter spawns the runtime as a child process:
+
+```
+coven-code --headless --context <session-brief.json> --output <result.json>
+```
+
+| Flag | Meaning |
+|---|---|
+| `--headless` | Disables the ratatui TUI entirely. All human-facing output is suppressed; the process is non-interactive and reads no stdin. |
+| `--context <path>` | Path to a `session-brief.json` file the adapter has already written. Read-only input. |
+| `--output <path>` | Path the runtime MUST write `result.json` to before exiting `0`, `1`, or `3`. |
+
+The runtime MUST NOT require a TTY. It MUST NOT block on interactive prompts.
+
+### 1.1 Environment
+
+| Variable | Required | Meaning |
+|---|---|---|
+| `COVEN_GIT_TOKEN` | yes (for any push) | GitHub App **installation access token** used to authenticate `git push` over HTTPS. The runtime MUST use this token for git write operations and MUST NOT use ambient user credentials. |
+
+The token is passed **only** through the environment. It MUST NOT appear in the
+session brief, the result envelope, the clone URL, logs, or any durable
+artifact. The 1-hour token TTL is the adapter's concern; the runtime treats the
+token as opaque and valid for the session.
+
+> **Drift note (supersedes `COVEN-GITHUB.md`):** earlier spec prose referenced
+> `GIT_ASKPASS` / `GIT_TOKEN` and an `auth.token` field embedded in the brief.
+> Those are **removed**. The brief is tokenless (issue #4) and the only git
+> credential channel is `COVEN_GIT_TOKEN`.
+
+---
+
+## 2. Input — `session-brief.json`
+
+The adapter is the **producer**; the runtime is the **consumer**. The brief is
+**tokenless**: it carries read context only.
+
+```json
+{
+  "contract_version": "1",
+  "trigger": "issue_assigned",
+  "repo": {
+    "owner": "OpenCoven",
+    "name": "coven-code",
+    "clone_url": "https://github.com/OpenCoven/coven-code.git",
+    "default_branch": "main"
+  },
+  "task": {
+    "kind": "fix_issue",
+    "issue_number": 42,
+    "issue_title": "Fix OAuth token refresh",
+    "issue_body": "The refresh path ignores clock skew…"
+  },
+  "familiar": {
+    "id": "cody",
+    "display_name": "Cody",
+    "model": "anthropic/claude-sonnet-4-6",
+    "skills": ["systematic-debugging"]
+  },
+  "workspace": {
+    "root": "/tmp/task-abc123"
+  }
+}
+```
+
+### 2.1 Fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `contract_version` | string | MUST be `"1"`. Consumers MUST reject a brief whose major version they do not implement. |
+| `trigger` | string enum | `issue_assigned` \| `pr_review_comment` \| `issue_mention`. |
+| `repo.owner` | string | |
+| `repo.name` | string | |
+| `repo.clone_url` | string | HTTPS clone URL **without** embedded credentials. The runtime supplies auth via `COVEN_GIT_TOKEN`. |
+| `repo.default_branch` | string | Resolved from live GitHub metadata, not assumed to be `main` (issue #9). |
+| `task` | object | Tagged union discriminated by `kind`. See [2.2](#22-task-kinds). |
+| `familiar.id` | string | Stable familiar identifier (e.g. `cody`). |
+| `familiar.display_name` | string | Human label used in familiar-voice output. |
+| `familiar.model` | string \| null | BYOM model id; `null`/absent means runtime default. |
+| `familiar.skills` | string[] | Skill ids to load for the session. MAY be empty. |
+| `workspace.root` | string | Absolute path to the pre-cloned, isolated workspace. The runtime operates **inside** this directory and MUST NOT write outside it. |
+
+### 2.2 Task kinds
+
+The `task` object is discriminated by a `kind` string (serde
+`#[serde(tag = "kind", rename_all = "snake_case")]`).
+
+| `kind` | Paired `trigger` | Fields |
+|---|---|---|
+| `fix_issue` | `issue_assigned` | `issue_number: u64`, `issue_title: string`, `issue_body: string` |
+| `address_review_comment` | `pr_review_comment` | `pr_number: u64`, `comment_body: string`, `diff_hunk: string \| null` |
+| `respond_to_mention` | `issue_mention` | `issue_number: u64`, `comment_body: string` |
+
+---
+
+## 3. Output — `result.json`
+
+The runtime is the **producer**; the adapter is the **consumer**. The runtime
+MUST write this file before exiting `0`, `1`, or `3`. On exit `2` (infra error)
+the file MAY be absent.
+
+```json
+{
+  "contract_version": "1",
+  "status": "success",
+  "branch": "cody/fix-issue-42",
+  "commits": [
+    { "sha": "a1b2c3d", "message": "Add clock-skew buffer to refresh path" }
+  ],
+  "files_changed": ["src/auth/refresh.rs"],
+  "summary": "Fixed OAuth token refresh by adding a 60-second clock skew buffer.",
+  "pr_body": "## Hey, I'm Cody 🦄\n\nI looked at issue #42…",
+  "exit_reason": null
+}
+```
+
+### 3.1 Fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `contract_version` | string | MUST be `"1"`. If absent, the consumer assumes `"1"` for backward compatibility, but producers MUST emit it. |
+| `status` | string enum | `success` \| `failure` \| `partial` \| `needs_input`. See [3.2](#32-status). |
+| `branch` | string \| null | Branch the runtime pushed. `null` when no branch was created. The adapter only opens a PR when `branch` is set **and** `commits` is non-empty. |
+| `commits` | array | `{ "sha": string, "message": string }`. MAY be empty. |
+| `files_changed` | string[] | Workspace-relative paths. MAY be empty. |
+| `summary` | string | One-line familiar-voice summary. Used in the Check Run and PR title. |
+| `pr_body` | string | Full PR body, **authored by the familiar** in its own voice — not a template. |
+| `exit_reason` | string enum \| null | `null` on success; otherwise the terminal cause. See [3.3](#33-exit_reason). |
+
+> **Drift note (supersedes `COVEN-GITHUB.md`):** the prose result envelope listed
+> an `events` array. Progress/event streaming is **not** part of the v1 result
+> envelope — it is deferred to M2 and will travel over a separate channel. The
+> v1 envelope carries terminal task state only. Producers MUST NOT rely on
+> `events` being read.
+
+### 3.2 `status`
+
+| Value | Meaning |
+|---|---|
+| `success` | Work complete; commits made; ready for a PR. |
+| `partial` | Some progress committed but the task is not fully done (e.g. tests still failing after the retry budget). The adapter still opens a PR if there are commits. |
+| `failure` | The agent gave up; no usable result. |
+| `needs_input` | The agent needs human clarification and has posted (or expects the adapter to surface) a question. Pairs with exit code `3`. |
+
+The adapter treats `success` and `partial` as PR-opening outcomes; `failure`
+and `needs_input` do not open a PR by themselves.
+
+### 3.3 `exit_reason`
+
+`null` on success. Otherwise one of:
+
+| Value | Meaning |
+|---|---|
+| `test_failure` | Tests could not be made to pass within the retry budget. |
+| `ambiguous_spec` | The request is underspecified; the agent chose to ask rather than guess. |
+| `git_conflict` | A git conflict the agent could not safely resolve. |
+| `infra_error` | Workspace, git, or tool failure. Retry-safe. |
+
+---
+
+## 4. Exit codes
+
+The exit code is the authoritative signal; `status` is advisory detail. The
+adapter's dispatch logic (`crates/worker`) keys on the exit code:
+
+| Code | Name | `result.json` | Adapter behavior |
+|---|---|---|---|
+| `0` | success | MUST be present | Read result; open draft PR if `branch` + `commits` present; complete Check Run `success` (or `failure` if `status` is `failure`/`needs_input`). |
+| `1` | failure | MUST be present | Agent gave up. Mark Check Run `failure` with `summary`. **Not** retried. |
+| `2` | infra error | MAY be absent | Retry-safe. Adapter retries up to its configured `max_retries`, then marks `failure`. |
+| `3` | needs input | MUST be present (`status: needs_input`) | Agent posted a clarifying question and exited cleanly. Adapter surfaces it; does not retry. |
+
+A process **killed by signal**, or one that **times out** (the adapter enforces
+`worker.timeout_secs`), is treated as a retry-safe failure equivalent to exit
+`2`.
+
+> **Drift note (supersedes `COVEN-GITHUB.md`):** earlier prose described exit `1`
+> as "failure: result.json written with exit_reason" and exit `3` as
+> "ambiguous". That intent is preserved, but the **locked** semantics are the
+> table above: `2` = infra/retry-safe, `3` = needs-input/clean. The adapter's
+> retry boundary is exit `2` (and timeout/signal), never exit `1`.
+
+---
+
+## 5. Security invariants
+
+These are non-negotiable for v1:
+
+1. The session brief is **tokenless**. Serializing a brief MUST NOT produce an
+   `auth` field, a `"token"` field, or a credential-bearing `clone_url`
+   (enforced by `brief_serialization_never_contains_token_or_auth_fields`).
+2. The only git credential channel is the `COVEN_GIT_TOKEN` environment
+   variable. It MUST NOT be persisted to the brief, the result, or logs.
+3. GitHub **write authority** (comments, Check Runs, branches, PRs) stays with
+   the adapter behind its publication gate. The runtime's only direct GitHub
+   write is `git push` of its working branch, authenticated by the installation
+   token.
+4. The runtime confines all filesystem writes to `workspace.root`.
+
+---
+
+## 6. Versioning
+
+The contract is versioned by the single `contract_version` string, which tracks
+**major** compatibility only.
+
+- A change that adds an **optional** field, a new enum variant a consumer can
+  ignore, or clarifies prose is **backward-compatible** and does **not** bump
+  the version.
+- A change that adds a **required** field, removes a field, renames a field,
+  changes a type, or changes exit-code/status semantics is **breaking** and MUST
+  bump `contract_version` to `"2"`, update both schemas and fixtures, and ship a
+  migration note here.
+- Consumers MUST reject a payload whose major version they do not implement,
+  rather than silently mis-parsing it.
+
+---
+
+## 7. Conformance artifacts
+
+| Artifact | Purpose |
+|---|---|
+| [`docs/contracts/session-brief.schema.json`](contracts/session-brief.schema.json) | JSON Schema for the input brief. |
+| [`docs/contracts/result.schema.json`](contracts/result.schema.json) | JSON Schema for the output envelope. |
+| [`docs/contracts/session-brief.example.json`](contracts/session-brief.example.json) | Golden input fixture. |
+| [`docs/contracts/result.example.json`](contracts/result.example.json) | Golden output fixture. |
+| `crates/github/tests/contract.rs` | Round-trips the golden fixtures through the Rust types — fails the build if the adapter drifts from this contract. |
+
+A `coven-code` change is contract-conformant when its emitted `result.json`
+validates against `result.schema.json` and it accepts any brief that validates
+against `session-brief.schema.json`.
diff --git a/docs/security.md b/docs/security.md
index f7bd49d..23401d6 100644
--- a/docs/security.md
+++ b/docs/security.md
@@ -57,9 +57,11 @@ See [Container Isolation](container-isolation.md) for the production isolation t
 
 ## Token Handling
 
-The current session brief includes clone auth so `coven-code` can operate on the repository. The production target is stricter:
+The session brief is **tokenless**: it carries read context only and never embeds an installation token or a credentialed `clone_url`. Git authentication is injected into the `coven-code` child process out-of-band through the `COVEN_GIT_TOKEN` environment variable, which is never written to `session-brief.json` or any durable artifact. GitHub write authority (comments, Check Runs, branches, PRs) stays with the adapter behind its publication gate; the agent emits a result envelope and the adapter publishes. A serialization test fails if the brief ever serializes an `auth`/`token` field or an `x-access-token` clone URL.
 
-- Prefer `GIT_ASKPASS` or environment-based git auth over embedding tokens in JSON.
+Remaining hardening targets:
+
+- Prefer `GIT_ASKPASS` / credential-helper injection over a plain env var so the token never appears in child process listings.
 - Avoid writing installation tokens to durable task stores.
 - Redact tokens in logs, Check Runs, issue comments, PR bodies, and task APIs.
 - Refresh installation tokens through a single token manager with cache expiry.
diff --git a/docs/self-hosting.md b/docs/self-hosting.md
index a94704c..1fac6ae 100644
--- a/docs/self-hosting.md
+++ b/docs/self-hosting.md
@@ -14,6 +14,28 @@ This guide targets macOS and Linux operators. Windows should work through WSL2 o
 
 ## 1. Register a GitHub App
 
+You can register the App from the prefilled manifest (fastest) or by hand.
+
+### Option A — manifest flow (recommended)
+
+`docs/app-manifest.json` describes the exact permissions and event subscriptions
+`coven-github` needs. Use it to create the App in one round trip:
+
+1. Open `docs/app-manifest.json` and replace the two `https://your-host`
+   placeholders (`hook_attributes.url` → `https://your-host/webhook`,
+   `redirect_url`) with your public endpoint.
+2. Visit `https://github.com/settings/apps/new` (personal) or
+   `https://github.com/organizations/<org>/settings/apps/new` (org) and use the
+   "Create from manifest" flow, or POST the manifest via the
+   [App manifest API](https://docs.github.com/apps/sharing-github-apps/registering-a-github-app-from-a-manifest).
+3. GitHub returns the **App ID**, generated **webhook secret**, and a downloadable
+   **private key** — save all three for the config step.
+
+The manifest already requests the correct permissions and subscribes to every
+event below, so you can skip the manual checklist.
+
+### Option B — manual registration
+
 1. Go to **GitHub → Settings → Developer settings → GitHub Apps → New GitHub App**
 2. Set:
    - **App name:** `coven-cody` (or your org's name)
@@ -29,12 +51,19 @@ This guide targets macOS and Linux operators. Windows should work through WSL2 o
 4. **Subscribe to events:**
    - Issues
    - Issue comment
+   - Pull request review
    - Pull request review comment
    - Check suite / Check run
 5. Click **Create GitHub App**
 6. Generate and download a **private key** (PEM file)
 7. Note your **App ID**
 
+> **Webhook triggers.** `coven-github` reacts to: issue **assignment** to a bot
+> familiar, configured **trigger labels**, **@mentions** in issue comments, PR
+> conversation comments, submitted **PR reviews**, and inline **review comments**.
+> GitHub's `ping` delivery is acknowledged with a `pong` so you can confirm the
+> endpoint is wired up from the App's **Advanced → Recent Deliveries** page.
+
 ## 2. Install the App on a repo
 
 From your GitHub App's page, click **Install App** and select the target repository.

From 8af77c89a3c4d5f189caedfe703a557c5a6c33c9 Mon Sep 17 00:00:00 2001
From: Val Alexander <bunsthedev@gmail.com>
Date: Tue, 30 Jun 2026 16:11:44 -0500
Subject: [PATCH 2/3] Harden worker preflight, retries, and checks

Refactors worker task execution so failures before check creation are still recorded in TaskStore, and so check runs are always finalized while workspace cleanup always happens. Moves publish/comment/check-progress steps to best-effort behavior, adds status-based disposition mapping (including neutral/action_required), and only opens PRs when appropriate. Reworks coven-code execution into contract-aware attempt types so only retry-safe failures (exit 2, timeout, signal, spawn/read issues) are retried, while exit 1 and exit 3 are terminal. Adds targeted tests for failed-task registration, disposition mapping, and retry/exit-code behavior, plus small README/COVEN formatting fixes.
---
 COVEN-GITHUB.md            |   3 +-
 README.md                  |   4 +-
 crates/github/src/tasks.rs |  28 ++
 crates/worker/src/lib.rs   | 796 +++++++++++++++++++++++++++++--------
 4 files changed, 663 insertions(+), 168 deletions(-)

diff --git a/COVEN-GITHUB.md b/COVEN-GITHUB.md
index 0a3eab0..6cc08e1 100644
--- a/COVEN-GITHUB.md
+++ b/COVEN-GITHUB.md
@@ -216,7 +216,8 @@ The PR body and issue comments are written in the familiar's voice:
 I looked at issue #42 and here's what I found:
 
 The OAuth token refresh path in `src/auth/refresh.rs` wasn't accounting for
-clock skew between the client and the auth server. I added a 60-second buffer\nto the expiry check.
+clock skew between the client and the auth server. I added a 60-second buffer
+to the expiry check.
 
 **Changed:** `src/auth/refresh.rs` (+12 / -3)
 **Tests:** 8/8 passing (added 2 regression cases)
diff --git a/README.md b/README.md
index b2b39b2..471477d 100644
--- a/README.md
+++ b/README.md
@@ -132,7 +132,9 @@ cd coven-github
 cargo build --release
 
 # Configure (see config/example.toml)
-cp config/example.toml config/local.toml\n# Set: github_app_id, private_key_path, webhook_secret, familiar config
+cp config/example.toml config/local.toml
+# Then set in config/local.toml: github.app_id, github.private_key_path,
+# github.webhook_secret, worker.coven_code_bin, and a [[familiars]] block.
 
 # Run
 ./target/release/coven-github serve --config config/local.toml
diff --git a/crates/github/src/tasks.rs b/crates/github/src/tasks.rs
index 0c91fb1..4b1aff8 100644
--- a/crates/github/src/tasks.rs
+++ b/crates/github/src/tasks.rs
@@ -84,6 +84,20 @@ impl TaskStore {
         }
     }
 
+    /// Records a task as failed, inserting it if it was never marked running.
+    ///
+    /// Used for pre-flight failures (token, ref resolution, Check Run creation)
+    /// that happen before [`mark_running`](Self::mark_running), so the task is
+    /// still visible in Cave as failed rather than vanishing silently.
+    pub async fn register_failed(&self, task: &Task, familiar_name: &str) {
+        let mut items = self.inner.write().await;
+        let item = items
+            .entry(task.id.clone())
+            .or_insert_with(|| task_list_item(task, familiar_name));
+        item.status = TaskListStatus::Failed;
+        item.updated_at = now_rfc3339();
+    }
+
     pub async fn list(&self) -> Vec<TaskListItem> {
         let mut items: Vec<_> = self.inner.read().await.values().cloned().collect();
         items.sort_by(|a, b| b.updated_at.cmp(&a.updated_at));
@@ -191,4 +205,18 @@ mod tests {
             Some("https://github.com/OpenCoven/coven-code/pull/9")
         );
     }
+
+    #[tokio::test]
+    async fn register_failed_inserts_a_failed_task_when_never_running() {
+        // A pre-flight failure (token / ref resolution / Check Run creation)
+        // happens before mark_running, so the task is not yet in the store.
+        let store = TaskStore::default();
+        store.register_failed(&task(), "Cody").await;
+
+        let items = store.list().await;
+        assert_eq!(items.len(), 1, "pre-flight failure must still be visible");
+        assert_eq!(items[0].status, TaskListStatus::Failed);
+        assert_eq!(items[0].issue_number, 42);
+        assert_eq!(items[0].familiar_name, "Cody");
+    }
 }
diff --git a/crates/worker/src/lib.rs b/crates/worker/src/lib.rs
index 0a677f5..b5512d6 100644
--- a/crates/worker/src/lib.rs
+++ b/crates/worker/src/lib.rs
@@ -1,7 +1,8 @@
 //! Worker: pulls tasks from the queue, spawns coven-code sessions, streams progress.
 
 use anyhow::Result;
-use std::path::PathBuf;
+use std::path::Path;
+use std::time::Duration;
 use tokio::process::Command;
 use tracing::{error, info, warn};
 
@@ -9,10 +10,17 @@ use coven_github_api::{
     check_run, installation, pr, repo, tasks::TaskStore, SessionResult, SessionStatus, Task,
     TaskKind, DEFAULT_API_BASE_URL,
 };
-use coven_github_config::Config;
+use coven_github_config::{Config, FamiliarConfig};
 
 pub mod brief;
 
+/// Base unit for exponential backoff between retry-safe coven-code attempts.
+/// Attempt `n` sleeps `RETRY_BACKOFF_BASE * 2^n` (so 2s, 4s, … in production).
+const RETRY_BACKOFF_BASE: Duration = Duration::from_secs(1);
+
+/// Default Cave base URL used in familiar-voice comments when none is configured.
+const DEFAULT_CAVE_BASE_URL: &str = "https://cave.opencoven.ai";
+
 /// Runs the worker loop: pulls tasks and executes them concurrently.
 pub async fn run(
     config: std::sync::Arc<Config>,
@@ -24,11 +32,15 @@ pub async fn run(
     while let Some(task) = task_rx.recv().await {
         let config = config.clone();
         let task_store = task_store.clone();
-        let permit = semaphore.clone().acquire_owned().await.unwrap();
+        let permit = match semaphore.clone().acquire_owned().await {
+            Ok(permit) => permit,
+            // The semaphore is only ever closed on shutdown; stop pulling tasks.
+            Err(_) => break,
+        };
 
         tokio::spawn(async move {
             let _permit = permit;
-            if let Err(e) = execute_task(&config, task_store.clone(), task).await {
+            if let Err(e) = execute_task(&config, task_store, task).await {
                 error!("task execution error: {e:#}");
             }
         });
@@ -49,75 +61,185 @@ async fn execute_task(config: &Config, task_store: TaskStore, task: Task) -> Res
         .as_deref()
         .unwrap_or(DEFAULT_API_BASE_URL);
 
-    // Get installation token.
-    let private_key = std::fs::read_to_string(&config.github.private_key_path)?;
-    let token = installation::get_token_with_base_url(
-        api_base_url,
-        config.github.app_id,
-        &private_key,
-        task.installation_id,
-    )
-    .await?;
+    // Pre-flight: installation token, ref resolution, and Check Run creation.
+    // These run *before* the Check Run exists, so a failure here can't orphan a
+    // check — but it would otherwise make the task vanish silently. Record it as
+    // failed so it stays visible in Cave, then propagate.
+    let prepared = async {
+        let private_key = std::fs::read_to_string(&config.github.private_key_path)?;
+        let token = installation::get_token_with_base_url(
+            api_base_url,
+            config.github.app_id,
+            &private_key,
+            task.installation_id,
+        )
+        .await?;
+
+        // Resolve target refs and base branch from live GitHub state. Check Runs
+        // must attach to an immutable commit SHA, and PRs must target the repo's
+        // actual base branch rather than a hardcoded "main".
+        let targets = resolve_targets(api_base_url, &token, &task).await?;
+
+        // Create Check Run against the resolved head SHA. From this point on the
+        // Check Run MUST reach a terminal conclusion on every code path — a flaky
+        // comment or PR API call must never leave a perpetually in-progress check
+        // blocking merges on a real repo.
+        let check_name = format!("{} — {}", familiar.display_name, task_title(&task.kind));
+        let check_id = check_run::create_with_base_url(
+            api_base_url,
+            &token,
+            &task.repo_owner,
+            &task.repo_name,
+            &targets.head_sha,
+            &check_name,
+            config
+                .server
+                .cave_base_url
+                .as_deref()
+                .map(|b| format!("{b}/sessions/{}", task.id))
+                .as_deref(),
+        )
+        .await?;
+        Ok::<_, anyhow::Error>((token, targets, check_id))
+    }
+    .await;
 
-    // Resolve target refs and base branch from live GitHub state. Check Runs
-    // must attach to an immutable commit SHA, and PRs must target the repo's
-    // actual base branch rather than a hardcoded "main".
-    let targets = resolve_targets(api_base_url, &token, &task).await?;
+    let (token, targets, check_id) = match prepared {
+        Ok(prepared) => prepared,
+        Err(e) => {
+            error!(task_id = %task.id, "pre-flight failed before check run: {e:#}");
+            task_store
+                .register_failed(&task, &familiar.display_name)
+                .await;
+            return Err(e);
+        }
+    };
 
-    // Create Check Run against the resolved head SHA.
-    let check_name = format!("{} — {}", familiar.display_name, task_title(&task.kind));
-    let check_id = check_run::create_with_base_url(
-        api_base_url,
-        &token,
-        &task.repo_owner,
-        &task.repo_name,
-        &targets.head_sha,
-        &check_name,
-        config
-            .server
-            .cave_base_url
-            .as_deref()
-            .map(|b| format!("{b}/sessions/{}", task.id))
-            .as_deref(),
-    )
-    .await?;
     let repo = format!("{}/{}", task.repo_owner, task.repo_name);
     let check_run_url = Some(format!("https://github.com/{repo}/runs/{check_id}"));
     task_store
         .mark_running(&task, &familiar.display_name, check_run_url)
         .await;
 
-    // Post "starting" comment.
+    // Everything past check creation is fallible but must not orphan the check
+    // or leak the workspace. Run it, then finalize unconditionally below.
+    let workspace = config.worker.workspace_root.join(&task.id);
+    let outcome = run_and_publish(
+        config,
+        &task,
+        familiar,
+        &token,
+        api_base_url,
+        &targets,
+        &workspace,
+        check_id,
+    )
+    .await;
+
+    // Workspace cleanup ALWAYS runs — success or failure.
+    tokio::fs::remove_dir_all(&workspace).await.ok();
+
+    // The Check Run ALWAYS reaches a terminal conclusion; both arms complete it.
+    match outcome {
+        Ok(published) => {
+            let disp = disposition(&published.result);
+            task_store
+                .mark_complete(&task.id, &repo, &published.result, published.opened_pr)
+                .await;
+            if let Err(e) = check_run::complete_with_base_url(
+                api_base_url,
+                &token,
+                &task.repo_owner,
+                &task.repo_name,
+                check_id,
+                disp.conclusion,
+                disp.title,
+                &published.result.summary,
+            )
+            .await
+            {
+                error!(task_id = %task.id, "failed to finalize check run: {e:#}");
+            }
+        }
+        Err(e) => {
+            error!(task_id = %task.id, "session failed: {e:#}");
+            task_store.mark_failed(&task.id).await;
+            if let Err(ce) = check_run::complete_with_base_url(
+                api_base_url,
+                &token,
+                &task.repo_owner,
+                &task.repo_name,
+                check_id,
+                check_run::CheckConclusion::Failure,
+                "Error",
+                &format!("Task failed: {e}"),
+            )
+            .await
+            {
+                error!(task_id = %task.id, "failed to finalize check run after error: {ce:#}");
+            }
+        }
+    }
+
+    Ok(())
+}
+
+/// Successful end-to-end publication of a session result.
+struct Published {
+    result: SessionResult,
+    opened_pr: Option<u64>,
+}
+
+/// Provisions the workspace, runs coven-code with the retry policy, and publishes
+/// the outcome (PR + comments). Returns `Err` only for failures that should mark
+/// the task — and complete the Check Run — as failed: workspace/brief I/O errors
+/// and retry-safe session failures that exhausted the retry budget. Cosmetic
+/// side-effects (comments, the in-progress transition, even PR opening) are
+/// best-effort and logged rather than propagated.
+#[allow(clippy::too_many_arguments)]
+async fn run_and_publish(
+    config: &Config,
+    task: &Task,
+    familiar: &FamiliarConfig,
+    token: &str,
+    api_base_url: &str,
+    targets: &ResolvedTargets,
+    workspace: &Path,
+    check_id: u64,
+) -> Result<Published> {
+    // Provision ephemeral workspace and write the tokenless session brief.
+    tokio::fs::create_dir_all(workspace).await?;
+    let brief = brief::build(task, familiar, workspace, &targets.default_branch);
+    let brief_path = workspace.join("session-brief.json");
+    let result_path = workspace.join("result.json");
+    tokio::fs::write(&brief_path, serde_json::to_string_pretty(&brief)?).await?;
+
+    // Best-effort "starting" comment — a flaky comment API call must not abort
+    // the task or orphan the Check Run.
     if let Some(issue_number) = task_issue_number(&task.kind) {
         let start_msg = format!(
             "👋 I'm **{}**, your Coven coding familiar. I'm on it — I'll open a PR once I've had a look.\n\n[Watch this session in CovenCave →]({})",
             familiar.display_name,
-            config.server.cave_base_url.as_deref().unwrap_or("https://cave.opencoven.ai"),
+            cave_base_url(config),
         );
-        pr::post_comment_with_base_url(
+        if let Err(e) = pr::post_comment_with_base_url(
             api_base_url,
-            &token,
+            token,
             &task.repo_owner,
             &task.repo_name,
             issue_number,
             &start_msg,
         )
-        .await?;
+        .await
+        {
+            warn!(task_id = %task.id, "failed to post starting comment: {e:#}");
+        }
     }
 
-    // Build session brief.
-    let workspace = config.worker.workspace_root.join(&task.id);
-    tokio::fs::create_dir_all(&workspace).await?;
-
-    let brief = brief::build(&task, familiar, &workspace, &targets.default_branch);
-    let brief_path = workspace.join("session-brief.json");
-    let result_path = workspace.join("result.json");
-    tokio::fs::write(&brief_path, serde_json::to_string_pretty(&brief)?).await?;
-
-    // Spawn coven-code.
-    check_run::update_with_base_url(
+    // Best-effort progress transition; the check is completed regardless below.
+    if let Err(e) = check_run::update_with_base_url(
         api_base_url,
-        &token,
+        token,
         &task.repo_owner,
         &task.repo_name,
         check_id,
@@ -125,134 +247,221 @@ async fn execute_task(config: &Config, task_store: TaskStore, task: Task) -> Res
         "Running",
         "Familiar is working on the task…",
     )
-    .await?;
+    .await
+    {
+        warn!(task_id = %task.id, "failed to mark check in progress: {e:#}");
+    }
 
-    let result = run_with_retry(
+    // Run coven-code. Only retry-safe failures (exit 2, timeout, signal) are
+    // retried; exit 1 (gave up) and exit 3 (needs input) are terminal.
+    let result = run_session(
         config,
         &brief_path,
         &result_path,
-        &token,
+        token,
         config.worker.max_retries,
     )
-    .await;
+    .await?;
 
-    match result {
-        Ok(session_result) => {
-            let success = session_result.status == SessionStatus::Success
-                || session_result.status == SessionStatus::Partial;
-
-            // Open PR if we have commits.
-            let mut opened_pr = None;
-            if !session_result.commits.is_empty() {
-                if let Some(branch) = &session_result.branch {
-                    let pr_num = pr::open_pull_request_with_base_url(
-                        api_base_url,
-                        &token,
-                        &task.repo_owner,
-                        &task.repo_name,
-                        branch,
-                        &targets.base_ref,
-                        &format!(
-                            "{} (#{} via Coven)",
-                            session_result.summary,
-                            task_issue_number(&task.kind).unwrap_or(0)
-                        ),
-                        &session_result.pr_body,
-                        true, // draft
-                    )
-                    .await?;
+    // Publish according to the terminal disposition of the result.
+    let disp = disposition(&result);
+    let mut opened_pr = None;
+    if disp.open_pr {
+        if let Some(branch) = &result.branch {
+            match pr::open_pull_request_with_base_url(
+                api_base_url,
+                token,
+                &task.repo_owner,
+                &task.repo_name,
+                branch,
+                &targets.base_ref,
+                &pr_title(&result, task),
+                &result.pr_body,
+                true, // draft
+            )
+            .await
+            {
+                Ok(pr_num) => {
                     opened_pr = Some(pr_num);
-
                     if let Some(issue_number) = task_issue_number(&task.kind) {
-                        pr::post_comment_with_base_url(
+                        let msg = format!(
+                            "✅ PR #{pr_num} opened — [watch in CovenCave →]({})",
+                            cave_base_url(config)
+                        );
+                        if let Err(e) = pr::post_comment_with_base_url(
                             api_base_url,
-                            &token,
+                            token,
                             &task.repo_owner,
                             &task.repo_name,
                             issue_number,
-                            &format!(
-                                "✅ PR #{pr_num} opened — [watch in CovenCave →]({})",
-                                config
-                                    .server
-                                    .cave_base_url
-                                    .as_deref()
-                                    .unwrap_or("https://cave.opencoven.ai")
-                            ),
+                            &msg,
                         )
-                        .await?;
+                        .await
+                        {
+                            warn!(task_id = %task.id, "failed to post PR comment: {e:#}");
+                        }
+                    }
+                }
+                Err(e) => {
+                    // The branch is already pushed; the PR just didn't open.
+                    // Surface it rather than failing the whole task, so the work
+                    // isn't lost from the user's view.
+                    warn!(task_id = %task.id, "failed to open PR: {e:#}");
+                    if let Some(issue_number) = task_issue_number(&task.kind) {
+                        let msg = format!(
+                            "⚠️ I pushed `{branch}` but couldn't open the PR automatically ({e}). You can open it manually."
+                        );
+                        let _ = pr::post_comment_with_base_url(
+                            api_base_url,
+                            token,
+                            &task.repo_owner,
+                            &task.repo_name,
+                            issue_number,
+                            &msg,
+                        )
+                        .await;
                     }
                 }
             }
-            task_store
-                .mark_complete(&task.id, &repo, &session_result, opened_pr)
-                .await;
-
-            check_run::complete_with_base_url(
-                api_base_url,
-                &token,
-                &task.repo_owner,
-                &task.repo_name,
-                check_id,
-                if success {
-                    check_run::CheckConclusion::Success
-                } else {
-                    check_run::CheckConclusion::Failure
-                },
-                if success { "Done" } else { "Incomplete" },
-                &session_result.summary,
-            )
-            .await?;
         }
-        Err(e) => {
-            error!(task_id = %task.id, "session failed: {e:#}");
-            task_store.mark_failed(&task.id).await;
-            check_run::complete_with_base_url(
+    }
+
+    // Needs-input: surface the familiar's clarifying question on the issue/PR.
+    if result.status == SessionStatus::NeedsInput {
+        if let Some(issue_number) = task_issue_number(&task.kind) {
+            let msg = format!(
+                "🤔 I need a bit more direction before I continue:\n\n{}",
+                result.summary
+            );
+            if let Err(e) = pr::post_comment_with_base_url(
                 api_base_url,
-                &token,
+                token,
                 &task.repo_owner,
                 &task.repo_name,
-                check_id,
-                check_run::CheckConclusion::Failure,
-                "Error",
-                &format!("Task failed: {e}"),
+                issue_number,
+                &msg,
             )
-            .await?;
+            .await
+            {
+                warn!(task_id = %task.id, "failed to post clarifying comment: {e:#}");
+            }
         }
     }
 
-    // Clean up workspace.
-    tokio::fs::remove_dir_all(&workspace).await.ok();
-    Ok(())
+    Ok(Published { result, opened_pr })
+}
+
+/// Terminal disposition of a completed session, derived purely from the result.
+///
+/// This refines the coarse "success or failure" prose in the headless contract
+/// (`docs/headless-contract.md` §4) into the adapter's own Check Run UX. It is an
+/// adapter-internal mapping, not part of the coven-code wire contract, so the
+/// finer conclusions (`neutral`/`action_required`) require no contract bump:
+///
+/// | status      | conclusion        | opens PR   | rationale |
+/// |-------------|-------------------|------------|-----------|
+/// | success     | success           | if commits | work complete |
+/// | partial     | neutral           | if commits | progress made, not done — non-blocking |
+/// | failure     | failure           | no         | agent gave up |
+/// | needs_input | action_required   | no         | human must answer a question |
+struct Disposition {
+    conclusion: check_run::CheckConclusion,
+    title: &'static str,
+    open_pr: bool,
+}
+
+fn disposition(result: &SessionResult) -> Disposition {
+    use check_run::CheckConclusion;
+
+    // The adapter only opens a PR when there is a branch AND commits to review.
+    let has_changes = result.branch.is_some() && !result.commits.is_empty();
+
+    match result.status {
+        SessionStatus::Success => Disposition {
+            conclusion: CheckConclusion::Success,
+            title: "Done",
+            open_pr: has_changes,
+        },
+        SessionStatus::Partial => Disposition {
+            conclusion: CheckConclusion::Neutral,
+            title: "Partial",
+            open_pr: has_changes,
+        },
+        SessionStatus::Failure => Disposition {
+            conclusion: CheckConclusion::Failure,
+            title: "Failed",
+            open_pr: false,
+        },
+        SessionStatus::NeedsInput => Disposition {
+            conclusion: CheckConclusion::ActionRequired,
+            title: "Needs input",
+            open_pr: false,
+        },
+    }
+}
+
+/// Outcome of a single coven-code invocation, classified per the exit-code
+/// contract (`docs/headless-contract.md` §4).
+enum Attempt {
+    /// The runtime exited 0/1/3 and wrote a parseable `result.json`. Terminal:
+    /// the adapter acts on `status`/`exit_reason` and MUST NOT retry.
+    Completed(SessionResult),
+    /// Exit 2, timeout, kill-by-signal, an unexpected exit code, or a spawn/read
+    /// failure. Retry-safe per the contract.
+    RetrySafe(anyhow::Error),
+}
+
+async fn run_session(
+    config: &Config,
+    brief_path: &Path,
+    result_path: &Path,
+    git_token: &str,
+    max_retries: u32,
+) -> Result<SessionResult> {
+    run_session_with_backoff(
+        config,
+        brief_path,
+        result_path,
+        git_token,
+        max_retries,
+        RETRY_BACKOFF_BASE,
+    )
+    .await
 }
 
-async fn run_with_retry(
+/// Retry loop with an injectable backoff base so tests don't sleep for seconds.
+/// Only `Attempt::RetrySafe` failures are retried; `Attempt::Completed` (exit
+/// 0/1/3) is returned immediately even when the agent gave up (exit 1) — the
+/// retry boundary is exit 2 / timeout / signal, never exit 1 or 3.
+async fn run_session_with_backoff(
     config: &Config,
-    brief_path: &PathBuf,
-    result_path: &PathBuf,
+    brief_path: &Path,
+    result_path: &Path,
     git_token: &str,
     max_retries: u32,
+    backoff_base: Duration,
 ) -> Result<SessionResult> {
-    let mut attempts = 0;
+    let mut attempts = 0u32;
     loop {
         match run_coven_code(config, brief_path, result_path, git_token).await {
-            Ok(r) => return Ok(r),
-            Err(e) if attempts < max_retries => {
-                warn!("coven-code attempt {attempts} failed ({e:#}), retrying…");
+            Attempt::Completed(result) => return Ok(result),
+            Attempt::RetrySafe(e) if attempts < max_retries => {
                 attempts += 1;
-                tokio::time::sleep(std::time::Duration::from_secs(2u64.pow(attempts))).await;
+                warn!("coven-code attempt {attempts} hit a retry-safe failure ({e:#}), retrying…");
+                tokio::time::sleep(backoff_base * 2u32.pow(attempts)).await;
             }
-            Err(e) => return Err(e),
+            Attempt::RetrySafe(e) => return Err(e),
         }
     }
 }
 
 async fn run_coven_code(
     config: &Config,
-    brief_path: &PathBuf,
-    result_path: &PathBuf,
+    brief_path: &Path,
+    result_path: &Path,
     git_token: &str,
-) -> Result<SessionResult> {
-    let mut child = Command::new(&config.worker.coven_code_bin)
+) -> Attempt {
+    let child = Command::new(&config.worker.coven_code_bin)
         .arg("--headless")
         .arg("--context")
         .arg(brief_path)
@@ -261,42 +470,75 @@ async fn run_coven_code(
         // Git auth is injected via the environment, never written to the
         // session brief or any durable artifact (issue #4).
         .env("COVEN_GIT_TOKEN", git_token)
-        .spawn()?;
+        .spawn();
+
+    let mut child = match child {
+        Ok(child) => child,
+        Err(e) => return Attempt::RetrySafe(anyhow::anyhow!("failed to spawn coven-code: {e}")),
+    };
 
     let status = match tokio::time::timeout(
-        std::time::Duration::from_secs(config.worker.timeout_secs),
+        Duration::from_secs(config.worker.timeout_secs),
         child.wait(),
     )
     .await
     {
-        Ok(status) => status?,
+        Ok(Ok(status)) => status,
+        Ok(Err(e)) => {
+            return Attempt::RetrySafe(anyhow::anyhow!("failed to await coven-code: {e}"))
+        }
         Err(_) => {
             let _ = child.kill().await;
             let _ = child.wait().await;
-            anyhow::bail!(
+            return Attempt::RetrySafe(anyhow::anyhow!(
                 "coven-code timed out after {} seconds",
                 config.worker.timeout_secs
-            );
+            ));
         }
     };
 
     match status.code() {
-        Some(0) => {}
-        Some(2) => anyhow::bail!("coven-code infra error (exit 2) — retry-safe"),
-        Some(3) => {
-            // Agent needs clarification — read partial result.
+        // Terminal outcomes. result.json MUST be present and parseable for these
+        // exit codes; if it isn't, the runtime misbehaved — fall back to a
+        // retry-safe failure rather than silently losing the task.
+        Some(code @ (0 | 1 | 3)) => match read_result(result_path).await {
+            Ok(result) => Attempt::Completed(result),
+            Err(e) => Attempt::RetrySafe(anyhow::anyhow!(
+                "coven-code exited {code} but result.json was unusable: {e}"
+            )),
+        },
+        Some(2) => Attempt::RetrySafe(anyhow::anyhow!("coven-code infra error (exit 2)")),
+        Some(code) => {
+            Attempt::RetrySafe(anyhow::anyhow!("coven-code exited with unexpected code {code}"))
         }
-        Some(code) => anyhow::bail!("coven-code exited with code {code}"),
-        None => anyhow::bail!("coven-code killed by signal"),
+        None => Attempt::RetrySafe(anyhow::anyhow!("coven-code killed by signal")),
     }
+}
 
-    let result_bytes = tokio::fs::read(result_path)
+async fn read_result(result_path: &Path) -> Result<SessionResult> {
+    let bytes = tokio::fs::read(result_path)
         .await
         .map_err(|_| anyhow::anyhow!("result.json not written by coven-code"))?;
-    let result: SessionResult = serde_json::from_slice(&result_bytes)?;
+    let result: SessionResult = serde_json::from_slice(&bytes)?;
     Ok(result)
 }
 
+fn cave_base_url(config: &Config) -> &str {
+    config
+        .server
+        .cave_base_url
+        .as_deref()
+        .unwrap_or(DEFAULT_CAVE_BASE_URL)
+}
+
+fn pr_title(result: &SessionResult, task: &Task) -> String {
+    format!(
+        "{} (#{} via Coven)",
+        result.summary,
+        task_issue_number(&task.kind).unwrap_or(0)
+    )
+}
+
 fn task_title(kind: &TaskKind) -> String {
     match kind {
         TaskKind::FixIssue {
@@ -372,13 +614,93 @@ fn task_issue_number(kind: &TaskKind) -> Option<u64> {
     }
 }
 
+#[cfg(test)]
+mod disposition_tests {
+    use super::*;
+    use coven_github_api::{CommitInfo, HEADLESS_CONTRACT_VERSION};
+
+    fn result(status: SessionStatus, branch: Option<&str>, commits: usize) -> SessionResult {
+        SessionResult {
+            contract_version: HEADLESS_CONTRACT_VERSION.to_string(),
+            status,
+            branch: branch.map(str::to_string),
+            commits: (0..commits)
+                .map(|i| CommitInfo {
+                    sha: format!("sha{i}"),
+                    message: "msg".to_string(),
+                })
+                .collect(),
+            files_changed: vec![],
+            summary: "summary".to_string(),
+            pr_body: "body".to_string(),
+            exit_reason: None,
+        }
+    }
+
+    #[test]
+    fn success_with_commits_opens_pr_and_concludes_success() {
+        let disp = disposition(&result(SessionStatus::Success, Some("cody/fix"), 1));
+        assert!(disp.open_pr);
+        assert!(matches!(
+            disp.conclusion,
+            check_run::CheckConclusion::Success
+        ));
+    }
+
+    #[test]
+    fn success_without_commits_does_not_open_pr() {
+        let disp = disposition(&result(SessionStatus::Success, None, 0));
+        assert!(!disp.open_pr);
+        assert!(matches!(
+            disp.conclusion,
+            check_run::CheckConclusion::Success
+        ));
+    }
+
+    #[test]
+    fn partial_with_commits_opens_pr_but_concludes_neutral() {
+        let disp = disposition(&result(SessionStatus::Partial, Some("cody/fix"), 2));
+        assert!(disp.open_pr);
+        assert!(matches!(
+            disp.conclusion,
+            check_run::CheckConclusion::Neutral
+        ));
+    }
+
+    #[test]
+    fn failure_never_opens_pr_and_concludes_failure() {
+        // Even if the agent left a branch behind, a failed session opens no PR.
+        let disp = disposition(&result(SessionStatus::Failure, Some("cody/fix"), 3));
+        assert!(!disp.open_pr);
+        assert!(matches!(
+            disp.conclusion,
+            check_run::CheckConclusion::Failure
+        ));
+    }
+
+    #[test]
+    fn needs_input_concludes_action_required_without_pr() {
+        let disp = disposition(&result(SessionStatus::NeedsInput, None, 0));
+        assert!(!disp.open_pr);
+        assert!(matches!(
+            disp.conclusion,
+            check_run::CheckConclusion::ActionRequired
+        ));
+    }
+}
+
 #[cfg(all(test, unix))]
-mod tests {
+mod process_tests {
     use super::*;
     use coven_github_config::{FamiliarConfig, GitHubAppConfig, ServerConfig, WorkerConfig};
-    use std::{fs, os::unix::fs::PermissionsExt, time::Instant};
+    use std::{
+        fs,
+        os::unix::fs::PermissionsExt,
+        path::PathBuf,
+        time::{Duration, Instant},
+    };
 
-    fn test_config(coven_code_bin: PathBuf, workspace_root: PathBuf) -> Config {
+    fn test_config(coven_code_bin: PathBuf, workspace_root: PathBuf, max_retries: u32) -> Config {
         Config {
             server: ServerConfig {
                 bind: "127.0.0.1:0".to_string(),
@@ -395,7 +717,7 @@ mod tests {
                 coven_code_bin,
                 workspace_root,
                 timeout_secs: 1,
-                max_retries: 0,
+                max_retries,
             },
             familiars: vec![FamiliarConfig {
                 id: "cody".to_string(),
@@ -408,27 +730,38 @@ mod tests {
         }
     }
 
-    #[tokio::test]
-    async fn coven_code_process_is_stopped_after_configured_timeout() {
-        let root = std::env::temp_dir().join(format!(
-            "coven-github-timeout-test-{}",
-            uuid::Uuid::new_v4()
-        ));
+    /// Builds an isolated temp dir for one test and writes an executable script
+    /// (the fake coven-code binary) into it. Returns (root, script_path).
+    fn scratch(name: &str, script: &str) -> (PathBuf, PathBuf) {
+        let root =
+            std::env::temp_dir().join(format!("coven-github-{name}-{}", uuid::Uuid::new_v4()));
         fs::create_dir_all(&root).expect("test dir should be created");
-        let script = root.join("slow-coven-code.sh");
-        fs::write(&script, "#!/usr/bin/env bash\nsleep 5\n").expect("script should be written");
-        fs::set_permissions(&script, fs::Permissions::from_mode(0o755))
+        let script_path = root.join("fake-coven-code.sh");
+        fs::write(&script_path, script).expect("script should be written");
+        fs::set_permissions(&script_path, fs::Permissions::from_mode(0o755))
             .expect("script should be executable");
+        (root, script_path)
+    }
 
-        let config = test_config(script, root.clone());
+    /// A minimal contract-valid result.json with the given status/exit_reason.
+    fn result_json(status: &str, exit_reason: &str) -> String {
+        format!(
+            r#"{{"contract_version":"1","status":"{status}","branch":null,"commits":[],"files_changed":[],"summary":"s","pr_body":"","exit_reason":{exit_reason}}}"#
+        )
+    }
+
+    #[tokio::test]
+    async fn coven_code_process_is_stopped_after_configured_timeout() {
+        let (root, script) = scratch("timeout-test", "#!/usr/bin/env bash\nsleep 5\n");
+        let config = test_config(script, root.clone(), 0);
         let brief_path = root.join("session-brief.json");
         let result_path = root.join("result.json");
         fs::write(&brief_path, "{}").expect("brief should be written");
 
         let started = Instant::now();
-        let result = run_coven_code(&config, &brief_path, &result_path, "test-token").await;
+        let attempt = run_coven_code(&config, &brief_path, &result_path, "test-token").await;
 
-        assert!(result.is_err());
+        assert!(matches!(attempt, Attempt::RetrySafe(_)));
         assert!(
             started.elapsed().as_secs() < 3,
             "process should stop close to the configured timeout"
@@ -436,4 +769,135 @@ mod tests {
 
         let _ = fs::remove_dir_all(root);
     }
+
+    #[tokio::test]
+    async fn exit_zero_with_result_is_completed() {
+        let body = result_json("success", "null");
+        let script = format!("#!/usr/bin/env bash\ncat > \"$5\" <<'EOF'\n{body}\nEOF\nexit 0\n");
+        let (root, path) = scratch("exit0", &script);
+        let config = test_config(path, root.clone(), 0);
+        let brief = root.join("session-brief.json");
+        let result = root.join("result.json");
+        fs::write(&brief, "{}").unwrap();
+
+        let attempt = run_coven_code(&config, &brief, &result, "tok").await;
+        match attempt {
+            Attempt::Completed(r) => assert_eq!(r.status, SessionStatus::Success),
+            Attempt::RetrySafe(e) => panic!("expected Completed, got RetrySafe: {e:#}"),
+        }
+        let _ = fs::remove_dir_all(root);
+    }
+
+    #[tokio::test]
+    async fn exit_three_needs_input_is_completed_not_retried() {
+        let body = result_json("needs_input", "\"ambiguous_spec\"");
+        let script = format!("#!/usr/bin/env bash\ncat > \"$5\" <<'EOF'\n{body}\nEOF\nexit 3\n");
+        let (root, path) = scratch("exit3", &script);
+        let config = test_config(path, root.clone(), 0);
+        let brief = root.join("session-brief.json");
+        let result = root.join("result.json");
+        fs::write(&brief, "{}").unwrap();
+
+        let attempt = run_coven_code(&config, &brief, &result, "tok").await;
+        match attempt {
+            Attempt::Completed(r) => assert_eq!(r.status, SessionStatus::NeedsInput),
+            Attempt::RetrySafe(e) => panic!("exit 3 must be terminal, got RetrySafe: {e:#}"),
+        }
+        let _ = fs::remove_dir_all(root);
+    }
+
+    #[tokio::test]
+    async fn exit_two_is_retry_safe() {
+        let (root, path) = scratch("exit2", "#!/usr/bin/env bash\nexit 2\n");
+        let config = test_config(path, root.clone(), 0);
+        let brief = root.join("session-brief.json");
+        let result = root.join("result.json");
+        fs::write(&brief, "{}").unwrap();
+
+        let attempt = run_coven_code(&config, &brief, &result, "tok").await;
+        assert!(matches!(attempt, Attempt::RetrySafe(_)));
+        let _ = fs::remove_dir_all(root);
+    }
+
+    #[tokio::test]
+    async fn exit_one_failure_is_not_retried_and_surfaces_result() {
+        // Exit 1 = agent gave up; the contract forbids retrying it. The script
+        // records each invocation so we can assert it ran exactly once.
+        let body = result_json("failure", "\"test_failure\"");
+        let script = format!(
+            "#!/usr/bin/env bash\necho x >> \"$(dirname \"$5\")/runs\"\ncat > \"$5\" <<'EOF'\n{body}\nEOF\nexit 1\n"
+        );
+        let (root, path) = scratch("exit1", &script);
+        let config = test_config(path, root.clone(), 2); // budget of 2 retries
+        let brief = root.join("session-brief.json");
+        let result = root.join("result.json");
+        fs::write(&brief, "{}").unwrap();
+
+        let session = run_session_with_backoff(
+            &config,
+            &brief,
+            &result,
+            "tok",
+            config.worker.max_retries,
+            Duration::from_millis(1),
+        )
+        .await
+        .expect("exit 1 yields a terminal result, not an error");
+        assert_eq!(session.status, SessionStatus::Failure);
+
+        let runs = fs::read_to_string(root.join("runs")).unwrap_or_default();
+        assert_eq!(
+            runs.lines().count(),
+            1,
+            "exit 1 must run exactly once (no retries)"
+        );
+        let _ = fs::remove_dir_all(root);
+    }
+
+    #[tokio::test]
+    async fn exit_two_retries_until_budget_exhausted_then_errors() {
+        // Exit 2 is retry-safe: with max_retries=2 the binary runs 1 + 2 = 3
+        // times before the session gives up with an error.
+        let script =
+            "#!/usr/bin/env bash\necho x >> \"$(dirname \"$5\")/runs\"\nexit 2\n".to_string();
+        let (root, path) = scratch("exit2-retries", &script);
+        let config = test_config(path, root.clone(), 2);
+        let brief = root.join("session-brief.json");
+        let result = root.join("result.json");
+        fs::write(&brief, "{}").unwrap();
+
+        let err = run_session_with_backoff(
+            &config,
+            &brief,
+            &result,
+            "tok",
+            config.worker.max_retries,
+            Duration::from_millis(1),
+        )
+        .await;
+        assert!(err.is_err(), "exhausted retry budget should error");
+
+        let runs = fs::read_to_string(root.join("runs")).unwrap_or_default();
+        assert_eq!(
+            runs.lines().count(),
+            3,
+            "exit 2 should run 1 + max_retries times"
+        );
+        let _ = fs::remove_dir_all(root);
+    }
+
+    #[tokio::test]
+    async fn exit_zero_without_result_file_is_retry_safe() {
+        // A runtime that exits 0 but never writes result.json misbehaved; treat
+        // it as retry-safe rather than crashing the task.
+        let (root, path) = scratch("exit0-noresult", "#!/usr/bin/env bash\nexit 0\n");
+        let config = test_config(path, root.clone(), 0);
+        let brief = root.join("session-brief.json");
+        let result = root.join("result.json");
+        fs::write(&brief, "{}").unwrap();
+
+        let attempt = run_coven_code(&config, &brief, &result, "tok").await;
+        assert!(matches!(attempt, Attempt::RetrySafe(_)));
+        let _ = fs::remove_dir_all(root);
+    }
 }

From 5a0870ac36ea0e778f4f3a5fe99e862fe7e5a5af Mon Sep 17 00:00:00 2001
From: Val Alexander <bunsthedev@gmail.com>
Date: Fri, 3 Jul 2026 08:05:44 -0500
Subject: [PATCH 3/3] test(worker): fix flaky exit-code tests racing the kill
 timer
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

test_config hardcoded timeout_secs=1 for every caller, so the exit-code
tests (0/1/2/3) raced the kill timer under load — the exit-3 needs-input
test intermittently saw RetrySafe(timeout) instead of the terminal
NeedsInput disposition.

Default test_config to a generous 30s timeout so exit-code tests never
race the kill path; the dedicated timeout test overrides it back to 1s
inline (it exercises sleep 5 and asserts elapsed < 3s).
---
 crates/worker/src/lib.rs | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/crates/worker/src/lib.rs b/crates/worker/src/lib.rs
index b5512d6..4bc70f3 100644
--- a/crates/worker/src/lib.rs
+++ b/crates/worker/src/lib.rs
@@ -716,7 +716,9 @@ mod process_tests {
                 concurrency: 1,
                 coven_code_bin,
                 workspace_root,
-                timeout_secs: 1,
+                // Generous default so exit-code tests never race the kill timer.
+                // The timeout test overrides this to a short value on purpose.
+                timeout_secs: 30,
                 max_retries,
             },
             familiars: vec![FamiliarConfig {
@@ -753,7 +755,9 @@ mod process_tests {
     #[tokio::test]
     async fn coven_code_process_is_stopped_after_configured_timeout() {
         let (root, script) = scratch("timeout-test", "#!/usr/bin/env bash\nsleep 5\n");
-        let config = test_config(script, root.clone(), 0);
+        let mut config = test_config(script, root.clone(), 0);
+        // This test specifically exercises the kill-on-timeout path.
+        config.worker.timeout_secs = 1;
         let brief_path = root.join("session-brief.json");
         let result_path = root.join("result.json");
         fs::write(&brief_path, "{}").expect("brief should be written");