From d4efebdc3515989fe7549342f5a18a607c87278d Mon Sep 17 00:00:00 2001
From: Val Alexander <bunsthedev@gmail.com>
Date: Fri, 19 Jun 2026 22:03:31 -0500
Subject: [PATCH 1/6] feat: operationalize coven-github hosted MVP

---
 DESIGN.md                                    |  98 +++++++++++++
 FAMILIAR-CONTRACT.md                         |  57 ++++++++
 HOSTED.md                                    |  76 ++++++++++
 README.md                                    |  25 +++-
 ROADMAP.md                                   |  74 ++++++++++
 crates/github/src/lib.rs                     |  12 ++
 crates/webhook/src/events.rs                 |  68 ++++++++-
 crates/webhook/src/routes.rs                 | 146 ++++++++++++++++++-
 crates/worker/src/lib.rs                     |  87 ++++++++++-
 docs/container-isolation.md                  |  63 ++++++++
 docs/hosted-mvp-plan.md                      | 103 +++++++++++++
 docs/hosted-vs-self-hosted.md                |  91 ++++++++++++
 docs/security.md                             |  82 +++++++++++
 docs/self-hosting.md                         |  56 ++++++-
 examples/familiar-github-starter/README.md   |  13 ++
 examples/familiar-github-starter/config.toml |  34 +++++
 16 files changed, 1072 insertions(+), 13 deletions(-)
 create mode 100644 DESIGN.md
 create mode 100644 FAMILIAR-CONTRACT.md
 create mode 100644 HOSTED.md
 create mode 100644 ROADMAP.md
 create mode 100644 docs/container-isolation.md
 create mode 100644 docs/hosted-mvp-plan.md
 create mode 100644 docs/hosted-vs-self-hosted.md
 create mode 100644 docs/security.md
 create mode 100644 examples/familiar-github-starter/README.md
 create mode 100644 examples/familiar-github-starter/config.toml

diff --git a/DESIGN.md b/DESIGN.md
new file mode 100644
index 0000000..17f01b0
--- /dev/null
+++ b/DESIGN.md
@@ -0,0 +1,98 @@
+# coven-github Design
+
+`coven-github` is a thin GitHub ingress layer for trusted familiar work. It should not become a generic agent platform inside the GitHub App. The GitHub App accepts repository events, routes them to the right familiar, records task state, and keeps humans in control through Cave oversight.
+
+## Design Goal
+
+Assign GitHub work to a known familiar and get a draft PR back with visible context, evidence, and an oversight path.
+
+The core design constraint is trust continuity:
+
+- The same familiar can return to the same repository with memory and team context.
+- The team can see what the familiar used, changed, tested, and could not decide.
+- The service can fail transparently without losing task state.
+- The open-source adapter remains self-hostable so buyers can inspect the trust boundary.
+
+## Task Flow
+
+```text
+GitHub event
+  -> webhook HMAC validation
+  -> event parsing and familiar routing
+  -> task record and queue
+  -> worker starts isolated session
+  -> coven-code --headless receives session brief
+  -> familiar drafts changes and result envelope
+  -> GitHub Check Run and PR are updated
+  -> Cave Board and session link expose oversight
+```
+
+## Routing Model
+
+The initial self-hosted adapter uses TOML familiar config:
+
+- `bot_username` routes issue assignment and mentions.
+- `trigger_labels` route issue labels such as `coven:fix`.
+- `skills` and `model` shape the familiar runtime.
+
+Hosted routing should move this into installation-scoped configuration:
+
+- installation id,
+- organization,
+- repository,
+- familiar id,
+- allowed trigger labels,
+- memory scope,
+- skill pack,
+- model route,
+- autonomy tier.
+
+## Cave Oversight Gate
+
+Cave oversight is the control plane. It should show:
+
+- task status and terminal state,
+- familiar identity,
+- repository and issue/PR links,
+- Check Run link,
+- session link,
+- context and memory scope used,
+- evidence collected,
+- human decision points.
+
+Draft PRs are the default. The team should promote more autonomy only after the familiar earns trust through repeated visible work.
+
+## Trust Boundaries
+
+| Boundary | Rule |
+|---|---|
+| Webhook ingress | Validate HMAC before parsing or routing. |
+| Tenant data | Scope task state by GitHub installation before hosted launch. |
+| Worker execution | Run each task with a timeout and isolated workspace. |
+| Git auth | Use installation tokens, not user credentials. |
+| Memory | Make familiar memory opt-in, inspectable, and revocable. |
+| Comments | Ignore familiar bot self-comments to avoid loops. |
+| Output | Prefer draft PRs and explicit failure states. |
+
+## Hosted Reliability Requirements
+
+Hosted `coven-github` needs these before paid beta:
+
+1. Durable queue.
+2. Persistent task store.
+3. GitHub delivery idempotency.
+4. Tenant-scoped task API auth.
+5. Installation-scoped familiar routing.
+6. Worker isolation and timeout enforcement.
+7. Audit events for accepted, started, retried, timed out, failed, needs input, PR opened, and completed.
+
+## Why This Design Monetizes
+
+The paid product is not "an agent that can write code." The paid product is a managed trust pipeline:
+
+- Teams keep familiar context instead of re-explaining their standards.
+- Managers get visibility instead of hidden automation.
+- Security reviewers get a self-host path and a clear credential boundary.
+- Engineers get PRs from a known actor with a history.
+
+That is what generic GitHub bots and one-shot coding agents do not provide.
diff --git a/FAMILIAR-CONTRACT.md b/FAMILIAR-CONTRACT.md
new file mode 100644
index 0000000..c8069c7
--- /dev/null
+++ b/FAMILIAR-CONTRACT.md
@@ -0,0 +1,57 @@
+# Familiar Contract for GitHub Work
+
+`coven-github` is not valuable because it can call the GitHub API. The value is that a team can deploy a familiar: a known, persistent, context-aware operator that understands the repo, the team's standards, and when to stop for human judgment.
+
+The GitHub App should make that trust visible.
+
+## Promise
+
+A GitHub familiar should:
+
+- Carry persistent identity across issues, PRs, repositories, and review cycles.
+- Use the team's configured model, skills, memory, and operating rules.
+- Explain what it changed and why in the familiar's voice.
+- Prefer draft PRs and Cave oversight for non-trivial work.
+- Treat ambiguity as a reason to ask, not a reason to guess.
+- Preserve repo hygiene: small branches, tested changes, clear failure states.
+- Make recovery easy when the task cannot be completed.
+
+## Behavioral Guarantees
+
+| Guarantee | Product behavior |
+|---|---|
+| Context continuity | The familiar can use organization/repo memory and prior task history when enabled. |
+| Team fit | Routing and skills are configured per installation, repository, and familiar. |
+| Human control | Cave oversight links appear in Check Runs, comments, and task state. |
+| Failure transparency | Every task ends in a visible state: review, done, needs input, failed, or timed out. |
+| Minimal surprise | Familiars open draft PRs by default until the team explicitly promotes automation. |
+| No self-trigger loops | Bot-authored comments do not retrigger the same familiar. |
+| Bounded execution | Worker timeout, retry, and isolation rules are enforced. |
+
+## Why This Beats Generic Agents
+
+Generic coding agents optimize for a single task. Familiars optimize for an ongoing working relationship.
+
+That matters most in PR clearing:
+
+- A generic agent can satisfy a prompt; a familiar can remember the team's release posture.
+- A generic agent can run tests; a familiar can know which tests are trusted signal.
+- A generic agent can make edits; a familiar can know when the change needs a design note, a migration path, or a human decision.
+- A generic agent can produce output; a familiar can build trust over repeated work.
+
+## Operational Requirements
+
+To make the familiar promise real, hosted `coven-github` needs:
+
+1. Tenant-scoped familiar routing.
+2. Durable task history and event idempotency.
+3. Cave oversight as the default review surface.
+4. Familiar memory boundaries that are opt-in, inspectable, and revocable.
+5. Audit logs for task acceptance, execution, retries, timeout, PR creation, and human intervention.
+6. Clear tier limits so teams know when a familiar is operating as a draft helper versus an autonomous maintainer.
+
+## Launch Rule
+
+Do not sell "autonomous code changes" first. Sell "a trusted familiar that drafts PRs under your team's control."
+
+Autonomy can expand after the service proves reliability through visible oversight, repeatable failure handling, and team-specific context.
diff --git a/HOSTED.md b/HOSTED.md
new file mode 100644
index 0000000..1a0bd40
--- /dev/null
+++ b/HOSTED.md
@@ -0,0 +1,76 @@
+# Hosted OpenCoven for GitHub
+
+Hosted OpenCoven is the managed version of `coven-github`: install the GitHub App, configure a familiar, assign an issue or label, and get a draft PR back with Cave oversight.
+
+The hosted tier should monetize managed reliability and familiar continuity, while the open-source adapter remains self-hostable for trust and inspection.
+
+## What Hosted Adds
+
+| Capability | Self-hosted adapter | Hosted OpenCoven |
+|---|---|---|
+| GitHub App ingress | You run it | Managed |
+| Queue | In-process/dev path until configured | Durable queue |
+| Task state | Local/in-memory unless extended | Persistent history |
+| Worker isolation | Operator-managed | Managed worker pool |
+| Familiar routing | Static config | Installation/repo scoped |
+| Familiar memory | Local/operator-managed | Optional cloud memory |
+| Cave oversight | Local Cave | Hosted-ready oversight links and dashboard |
+| Usage limits | Operator-managed | Tiered limits and audit logs |
+| Support | Community | Priority by tier |
+
+## Packaging
+
+| Tier | Buyer | Initial shape |
+|---|---|---|
+| Open / Self-host | OSS maintainers, security reviewers, local-first users | Free adapter, BYOM, one familiar, community support. |
+| Hosted Starter | Small teams with backlog | Managed queue, one familiar, task caps, Cave oversight links. |
+| Hosted Team | Product/platform teams | Multi-familiar routing, audit log, usage controls, priority queue, team memory. |
+| Hosted Dedicated | Security-sensitive orgs | Dedicated workers, stronger retention controls, custom limits, SLA, onboarding support. |
+
+Launch with flat monthly tiers and task caps. Avoid pure usage billing until task duration and model-cost distribution are known.
+
+## Buyer Promise
+
+> Your familiar on your GitHub: the one that already knows your code, your team, and how you ship.
+
+The strongest buyer promise is trust continuity. A familiar should know the diff between "works" and "good enough for this repo." Hosted makes that reliable without making the customer operate workers, queues, or task history.
+
+## Data Boundaries
+
+Hosted should make these boundaries explicit before beta:
+
+- GitHub installation tokens are scoped to the installed repositories.
+- User GitHub credentials are not used for worker pushes.
+- Familiar memory is opt-in and scoped by installation/repository policy.
+- Task history records metadata, status, evidence, links, and summaries.
+- Raw repository workspaces are temporary and destroyed after the task.
+- Secrets are redacted from logs and task output.
+
+## Beta Gate
+
+Hosted beta should wait for:
+
+1. Persistent task store.
+2. Durable queue.
+3. Tenant-scoped task API authentication.
+4. Worker isolation with cleanup and timeouts.
+5. Usage metering by installation, repo, familiar, and task.
+6. Cave oversight dashboard for task history and human intervention.
+
+## Landing Page Copy
+
+Headline:
+
+> Assign it like a teammate. Get a PR back.
+
+Support copy:
+
+> OpenCoven lets your team deploy a trusted familiar to GitHub. It knows your repo context, follows your skills and review norms, drafts PRs under Cave oversight, and gets better as it works with your team.
+
+Primary CTA:
+
+- Join hosted beta
+
+Secondary CTA:
+
+- Self-host the adapter
diff --git a/README.md b/README.md
index 397db50..2e75a4a 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,10 @@ Every existing GitHub coding agent is a black box: GitHub's model, GitHub's cont
 
 `coven-github` flips that. Your familiar is yours: your model, your skills, your memory, your voice in the PR body. The GitHub App is just the ingress layer.
 
+That is the product wedge: assign it like a teammate, get a PR back, and keep Cave oversight in the loop. A familiar should know the difference between "technically works" and "good enough for this repo, this team, and this moment."
+
+See [Design](DESIGN.md), [Hosted OpenCoven](HOSTED.md), [Familiar Contract](FAMILIAR-CONTRACT.md), [Roadmap](ROADMAP.md), and [Hosted vs self-hosted](docs/hosted-vs-self-hosted.md) for the operational plan.
+
 ---
 
 ## Architecture
@@ -72,7 +76,22 @@ CovenCave oversight UI   ← watch session live, intervene, steer
 
 ## Status
 
-🚧 **In development.** See [COVEN-GITHUB.md](COVEN-GITHUB.md) for the full product spec.
+🚧 **In development.** The repo has the first GitHub App adapter path wired, but hosted production readiness is still being built. See [COVEN-GITHUB.md](COVEN-GITHUB.md) for the roadmap-level product spec.
+
+| Capability | Status | Notes |
+|---|---|---|
+| Webhook HMAC validation | Implemented | Rejects unsigned or invalid GitHub webhook payloads. |
+| Issue assignment trigger | Implemented | Routes matching bot assignees to configured familiars. |
+| 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`. |
+| 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). |
+| Familiar trust contract | Planned | See [Familiar Contract](FAMILIAR-CONTRACT.md). |
 
 ---
 
@@ -91,7 +110,7 @@ cp config/example.toml config/local.toml\n# Set: github_app_id, private_key_path
 ./target/release/coven-github serve --config config/local.toml
 ```
 
-See [docs/self-hosting.md](docs/self-hosting.md) for full setup including GitHub App registration.
+See [docs/self-hosting.md](docs/self-hosting.md) for full setup including GitHub App registration. For a minimal familiar route, start from [`examples/familiar-github-starter`](examples/familiar-github-starter/).
 
 ---
 
@@ -99,7 +118,7 @@ See [docs/self-hosting.md](docs/self-hosting.md) for full setup including GitHub
 
 `coven-github` is open source and self-hostable. OpenCoven offers a **hosted tier** for organizations that want managed infra, cloud familiar memory, and multi-familiar routing without running their own workers.
 
-See [opencoven.ai/github](https://opencoven.ai/github) for hosted tier details.
+See [Hosted OpenCoven](HOSTED.md) and [Hosted vs self-hosted](docs/hosted-vs-self-hosted.md) for the service shape, security boundaries, and buyer packaging.
 
 ---
 
diff --git a/ROADMAP.md b/ROADMAP.md
new file mode 100644
index 0000000..842193f
--- /dev/null
+++ b/ROADMAP.md
@@ -0,0 +1,74 @@
+# coven-github Roadmap
+
+This roadmap operationalizes `coven-github` as a hosted service funded by teams that want trusted familiar-driven GitHub work.
+
+## Strategic Thesis
+
+The market already has generic coding agents. OpenCoven's advantage is the familiar:
+
+- A known teammate, not a disposable bot.
+- Context-aware across repos, issues, reviews, and team norms.
+- Governed by skills, memory, and a visible trust contract.
+- Watched and steered through Cave instead of hidden in a black box.
+
+The hosted product should monetize managed reliability and trust continuity: durable task infrastructure, worker isolation, auditability, familiar memory, and multi-familiar routing.
+
+## Milestone 1: Honest Self-Hosted Adapter
+
+Goal: a motivated user can run the adapter and understand exactly what works.
+
+- Implement issue assignment, label, issue mention, and PR review comment triggers.
+- Enforce webhook HMAC validation and bot self-comment suppression.
+- Enforce worker timeout behavior.
+- Keep README status honest about implemented, partial, and planned capabilities.
+- Publish security, isolation, self-hosting, hosted-vs-self-hosted, and familiar contract docs.
+
+## Milestone 2: Hosted Control Plane
+
+Goal: support real hosted installations without losing task state or leaking tenant context.
+
+- Persistent task store.
+- Durable queue.
+- GitHub delivery idempotency.
+- Installation-scoped familiar routing.
+- Tenant-scoped task API auth for Cave.
+- Task audit log and terminal states.
+
+## Milestone 3: GitHub Correctness
+
+Goal: make the GitHub App reliable across normal repositories.
+
+- Resolve repository default branch through the GitHub API.
+- Resolve Check Run head SHA instead of using placeholders.
+- Use the repo default branch for PR base and session brief.
+- Capture review-comment diff hunk context.
+- Add transient GitHub API retry classification.
+- Add webhook fixture tests for all supported triggers.
+
+## Milestone 4: Hosted Worker Fleet
+
+Goal: make familiar execution safe enough to charge for.
+
+- Containerized worker backend.
+- CPU, memory, disk, network, and timeout limits.
+- Workspace cleanup guarantees.
+- Token redaction and secret handling tests.
+- Usage metering by installation, repo, familiar, and task runtime.
+- Tier limits and concurrency controls.
+
+## Milestone 5: Monetization Surface
+
+Goal: make the value legible and buyable.
+
+- `opencoven.ai/github` landing page.
+- Hosted beta waitlist.
+- Pricing: Community, Hosted Starter, Hosted Team, Hosted Dedicated.
+- Cave dashboard for task history, familiar routing, usage, and audit events.
+- Demo assets: issue assignment to Check Run, draft PR back to issue, Cave oversight intervention.
+
+## Current Focus
+
+1. Land the hosted MVP hardening branch.
+2. Build persistent task state and idempotency.
+3. Move familiar routing from global TOML toward installation-scoped config.
+4. Make Cave oversight central in the public story and product loop.
diff --git a/crates/github/src/lib.rs b/crates/github/src/lib.rs
index 31e396d..b4c2605 100644
--- a/crates/github/src/lib.rs
+++ b/crates/github/src/lib.rs
@@ -58,6 +58,7 @@ async fn send_json(
 #[serde(tag = "event_type", rename_all = "snake_case")]
 pub enum GitHubEvent {
     IssueAssigned(IssueAssignedEvent),
+    IssueLabeled(IssueLabeledEvent),
     IssueComment(IssueCommentEvent),
     PullRequestReviewComment(PrReviewCommentEvent),
     Unsupported { name: String },
@@ -74,6 +75,17 @@ pub struct IssueAssignedEvent {
     pub assignee_login: String,
 }
 
+#[derive(Debug, Clone, Deserialize, Serialize)]
+pub struct IssueLabeledEvent {
+    pub installation_id: u64,
+    pub repo_owner: String,
+    pub repo_name: String,
+    pub issue_number: u64,
+    pub issue_title: String,
+    pub issue_body: String,
+    pub label_name: String,
+}
+
 #[derive(Debug, Clone, Deserialize, Serialize)]
 pub struct IssueCommentEvent {
     pub installation_id: u64,
diff --git a/crates/webhook/src/events.rs b/crates/webhook/src/events.rs
index e1a13c2..d8294a6 100644
--- a/crates/webhook/src/events.rs
+++ b/crates/webhook/src/events.rs
@@ -1,9 +1,9 @@
 //! Webhook event parsing: GitHub payload → typed events.
 
-use serde::Deserialize;
 use coven_github_api::{
-    GitHubEvent, IssueAssignedEvent, IssueCommentEvent, PrReviewCommentEvent,
+    GitHubEvent, IssueAssignedEvent, IssueCommentEvent, IssueLabeledEvent, PrReviewCommentEvent,
 };
+use serde::Deserialize;
 
 /// Raw GitHub webhook payload (partial — we only pull what we need).
 #[derive(Debug, Deserialize)]
@@ -13,6 +13,7 @@ pub struct WebhookPayload {
     pub repository: Option<Repository>,
     pub issue: Option<Issue>,
     pub comment: Option<Comment>,
+    pub label: Option<Label>,
     pub assignee: Option<User>,
     pub pull_request: Option<PullRequest>,
 }
@@ -40,6 +41,11 @@ pub struct Issue {
     pub body: Option<String>,
 }
 
+#[derive(Debug, Deserialize)]
+pub struct Label {
+    pub name: String,
+}
+
 #[derive(Debug, Deserialize)]
 pub struct Comment {
     pub body: String,
@@ -77,6 +83,24 @@ pub fn parse_event(event_type: &str, payload: &WebhookPayload) -> GitHubEvent {
                 });
             }
         }
+        "issues" if payload.action.as_deref() == Some("labeled") => {
+            if let (Some(inst), Some(repo), Some(issue), Some(label)) = (
+                &payload.installation,
+                &payload.repository,
+                &payload.issue,
+                &payload.label,
+            ) {
+                return GitHubEvent::IssueLabeled(IssueLabeledEvent {
+                    installation_id: inst.id,
+                    repo_owner: repo.owner.login.clone(),
+                    repo_name: repo.name.clone(),
+                    issue_number: issue.number,
+                    issue_title: issue.title.clone(),
+                    issue_body: issue.body.clone().unwrap_or_default(),
+                    label_name: label.name.clone(),
+                });
+            }
+        }
         "issue_comment" if payload.action.as_deref() == Some("created") => {
             if let (Some(inst), Some(repo), Some(issue), Some(comment)) = (
                 &payload.installation,
@@ -118,3 +142,43 @@ pub fn parse_event(event_type: &str, payload: &WebhookPayload) -> GitHubEvent {
         name: event_type.to_string(),
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn parses_labeled_issue_as_label_event() {
+        let payload: WebhookPayload = serde_json::from_value(json!({
+            "action": "labeled",
+            "installation": { "id": 123 },
+            "repository": {
+                "name": "coven-code",
+                "owner": { "login": "OpenCoven" }
+            },
+            "issue": {
+                "number": 42,
+                "title": "Fix the spell compiler",
+                "body": "It loses sigils."
+            },
+            "label": { "name": "coven:fix" }
+        }))
+        .expect("payload should deserialize");
+
+        let event = parse_event("issues", &payload);
+
+        match event {
+            GitHubEvent::IssueLabeled(e) => {
+                assert_eq!(e.installation_id, 123);
+                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 the spell compiler");
+                assert_eq!(e.issue_body, "It loses sigils.");
+                assert_eq!(e.label_name, "coven:fix");
+            }
+            other => panic!("expected IssueLabeled, got {other:?}"),
+        }
+    }
+}
diff --git a/crates/webhook/src/routes.rs b/crates/webhook/src/routes.rs
index 1e1497e..89027d1 100644
--- a/crates/webhook/src/routes.rs
+++ b/crates/webhook/src/routes.rs
@@ -131,11 +131,33 @@ fn event_to_task(state: &AppState, event: GitHubEvent) -> Option<Task> {
             })
         }
 
+        GitHubEvent::IssueLabeled(e) => {
+            let familiar = state
+                .config
+                .familiars
+                .iter()
+                .find(|f| f.trigger_labels.iter().any(|label| label == &e.label_name))?;
+
+            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::FixIssue {
+                    issue_number: e.issue_number,
+                    issue_title: e.issue_title,
+                    issue_body: e.issue_body,
+                },
+            })
+        }
+
         GitHubEvent::IssueComment(e) => {
             // Find a familiar mentioned in the comment body.
             let familiar = state.config.familiars.iter().find(|f| {
-                e.comment_body
-                    .contains(&format!("@{}", f.bot_username.trim_end_matches("[bot]")))
+                e.commenter_login != f.bot_username
+                    && e.comment_body
+                        .contains(&format!("@{}", f.bot_username.trim_end_matches("[bot]")))
             })?;
 
             Some(Task {
@@ -153,8 +175,9 @@ fn event_to_task(state: &AppState, event: GitHubEvent) -> Option<Task> {
 
         GitHubEvent::PullRequestReviewComment(e) => {
             let familiar = state.config.familiars.iter().find(|f| {
-                e.comment_body
-                    .contains(&format!("@{}", f.bot_username.trim_end_matches("[bot]")))
+                e.commenter_login != f.bot_username
+                    && e.comment_body
+                        .contains(&format!("@{}", f.bot_username.trim_end_matches("[bot]")))
             })?;
 
             Some(Task {
@@ -174,3 +197,118 @@ fn event_to_task(state: &AppState, event: GitHubEvent) -> Option<Task> {
         GitHubEvent::Unsupported { .. } => None,
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use coven_github_api::{IssueCommentEvent, IssueLabeledEvent, TaskKind};
+    use coven_github_config::{FamiliarConfig, GitHubAppConfig, ServerConfig, WorkerConfig};
+    use std::{path::PathBuf, sync::Arc};
+
+    fn app_state() -> AppState {
+        let (task_tx, _task_rx) = tokio::sync::mpsc::channel(1);
+        AppState {
+            config: Arc::new(Config {
+                server: ServerConfig {
+                    bind: "127.0.0.1:0".to_string(),
+                    cave_base_url: None,
+                },
+                github: GitHubAppConfig {
+                    app_id: 1,
+                    private_key_path: PathBuf::from("private.pem"),
+                    webhook_secret: "secret".to_string(),
+                    api_base_url: None,
+                },
+                worker: WorkerConfig {
+                    concurrency: 1,
+                    coven_code_bin: PathBuf::from("coven-code"),
+                    workspace_root: PathBuf::from("/tmp/coven-github-test"),
+                    timeout_secs: 60,
+                    max_retries: 0,
+                },
+                familiars: vec![FamiliarConfig {
+                    id: "cody".to_string(),
+                    display_name: "Cody".to_string(),
+                    bot_username: "coven-cody[bot]".to_string(),
+                    model: None,
+                    skills: vec![],
+                    trigger_labels: vec!["coven:fix".to_string()],
+                }],
+            }),
+            task_tx,
+            task_store: TaskStore::default(),
+        }
+    }
+
+    #[test]
+    fn labeled_issue_routes_to_familiar_trigger_label() {
+        let state = app_state();
+        let task = event_to_task(
+            &state,
+            GitHubEvent::IssueLabeled(IssueLabeledEvent {
+                installation_id: 123,
+                repo_owner: "OpenCoven".to_string(),
+                repo_name: "coven-code".to_string(),
+                issue_number: 42,
+                issue_title: "Fix auth".to_string(),
+                issue_body: "Token refresh is broken.".to_string(),
+                label_name: "coven:fix".to_string(),
+            }),
+        )
+        .expect("matching trigger label should create a task");
+
+        assert_eq!(task.installation_id, 123);
+        assert_eq!(task.repo_owner, "OpenCoven");
+        assert_eq!(task.repo_name, "coven-code");
+        assert_eq!(task.familiar_id, "cody");
+        match task.kind {
+            TaskKind::FixIssue {
+                issue_number,
+                issue_title,
+                issue_body,
+            } => {
+                assert_eq!(issue_number, 42);
+                assert_eq!(issue_title, "Fix auth");
+                assert_eq!(issue_body, "Token refresh is broken.");
+            }
+            other => panic!("expected FixIssue task, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn labeled_issue_ignores_unknown_labels() {
+        let state = app_state();
+        let task = event_to_task(
+            &state,
+            GitHubEvent::IssueLabeled(IssueLabeledEvent {
+                installation_id: 123,
+                repo_owner: "OpenCoven".to_string(),
+                repo_name: "coven-code".to_string(),
+                issue_number: 42,
+                issue_title: "Fix auth".to_string(),
+                issue_body: "Token refresh is broken.".to_string(),
+                label_name: "help wanted".to_string(),
+            }),
+        );
+
+        assert!(task.is_none());
+    }
+
+    #[test]
+    fn issue_comment_ignores_bot_self_mentions() {
+        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 thanks, I opened a PR.".to_string(),
+                commenter_login: "coven-cody[bot]".to_string(),
+            }),
+        );
+
+        assert!(task.is_none());
+    }
+}
diff --git a/crates/worker/src/lib.rs b/crates/worker/src/lib.rs
index 1d039f1..f42b920 100644
--- a/crates/worker/src/lib.rs
+++ b/crates/worker/src/lib.rs
@@ -238,14 +238,29 @@ async fn run_coven_code(
     brief_path: &PathBuf,
     result_path: &PathBuf,
 ) -> Result<SessionResult> {
-    let status = Command::new(&config.worker.coven_code_bin)
+    let mut child = Command::new(&config.worker.coven_code_bin)
         .arg("--headless")
         .arg("--context")
         .arg(brief_path)
         .arg("--output")
         .arg(result_path)
-        .status()
-        .await?;
+        .spawn()?;
+
+    let status = match tokio::time::timeout(
+        std::time::Duration::from_secs(config.worker.timeout_secs),
+        child.wait(),
+    )
+    .await
+    {
+        Ok(status) => status?,
+        Err(_) => {
+            let _ = child.kill().await;
+            anyhow::bail!(
+                "coven-code timed out after {} seconds",
+                config.worker.timeout_secs
+            );
+        }
+    };
 
     match status.code() {
         Some(0) => {}
@@ -287,3 +302,69 @@ fn task_issue_number(kind: &TaskKind) -> Option<u64> {
         TaskKind::AddressReviewComment { .. } => None,
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use coven_github_config::{FamiliarConfig, GitHubAppConfig, ServerConfig, WorkerConfig};
+    use std::{fs, os::unix::fs::PermissionsExt, time::Instant};
+
+    fn test_config(coven_code_bin: PathBuf, workspace_root: PathBuf) -> Config {
+        Config {
+            server: ServerConfig {
+                bind: "127.0.0.1:0".to_string(),
+                cave_base_url: None,
+            },
+            github: GitHubAppConfig {
+                app_id: 1,
+                private_key_path: PathBuf::from("private.pem"),
+                webhook_secret: "secret".to_string(),
+                api_base_url: None,
+            },
+            worker: WorkerConfig {
+                concurrency: 1,
+                coven_code_bin,
+                workspace_root,
+                timeout_secs: 1,
+                max_retries: 0,
+            },
+            familiars: vec![FamiliarConfig {
+                id: "cody".to_string(),
+                display_name: "Cody".to_string(),
+                bot_username: "coven-cody[bot]".to_string(),
+                model: None,
+                skills: vec![],
+                trigger_labels: vec![],
+            }],
+        }
+    }
+
+    #[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()
+        ));
+        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))
+            .expect("script should be executable");
+
+        let config = test_config(script, root.clone());
+        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).await;
+
+        assert!(result.is_err());
+        assert!(
+            started.elapsed().as_secs() < 3,
+            "process should stop close to the configured timeout"
+        );
+
+        let _ = fs::remove_dir_all(root);
+    }
+}
diff --git a/docs/container-isolation.md b/docs/container-isolation.md
new file mode 100644
index 0000000..20975d4
--- /dev/null
+++ b/docs/container-isolation.md
@@ -0,0 +1,63 @@
+# Container Isolation
+
+Self-hosted development can run `coven-code` directly on the host. Hosted OpenCoven should not. A paid GitHub App service needs a stronger worker boundary because tasks clone private repositories and execute project commands.
+
+## Production Target
+
+Each task should run in a fresh container or equivalent sandbox:
+
+- One repository task per container.
+- Temporary filesystem mounted at the task workspace.
+- Installation token scoped to the target repository only.
+- CPU, memory, disk, and wall-clock limits.
+- Network egress policy appropriate to the customer's trust tier.
+- Workspace deleted after task completion, failure, or timeout.
+
+## Minimum Worker Contract
+
+The host worker should:
+
+1. Receive a persisted task from the queue.
+2. Mint or fetch a short-lived installation token.
+3. Start an isolated workspace.
+4. Inject the session brief and git auth.
+5. Run `coven-code --headless --context <brief> --output <result>`.
+6. Stream progress to task state and Check Runs.
+7. Stop the process when `timeout_secs` expires.
+8. Copy out only the result envelope and required logs.
+9. Destroy the workspace.
+
+## What Not To Persist
+
+Do not persist:
+
+- Raw installation tokens.
+- GitHub App private keys.
+- Full repository checkouts.
+- Unredacted model provider keys.
+- Arbitrary command output without secret filtering.
+
+Persist only task metadata, summaries, exit reasons, changed file lists, branch names, PR links, Check Run links, and explicitly retained logs.
+
+## Self-Hosted Guidance
+
+For self-hosters, local process execution is acceptable for early evaluation if the host already has permission to clone and build the target repositories. Operators should move to containers before letting untrusted repositories or broad organizations trigger tasks.
+
+Recommended baseline:
+
+- Dedicated worker user.
+- Dedicated workspace root.
+- Short task timeout.
+- Low concurrency until resource needs are known.
+- Separate GitHub App per environment.
+- Private key and webhook secret stored outside the repo.
+
+## Hosted Roadmap
+
+Recommended order:
+
+1. Enforce process timeouts for all local workers.
+2. Persist task state before and after each worker phase.
+3. Add Docker-based worker backend behind the current worker interface.
+4. Add resource limits and workspace cleanup tests.
+5. Add a dedicated worker pool tier for paid hosted customers.
diff --git a/docs/hosted-mvp-plan.md b/docs/hosted-mvp-plan.md
new file mode 100644
index 0000000..2bce813
--- /dev/null
+++ b/docs/hosted-mvp-plan.md
@@ -0,0 +1,103 @@
+# Hosted MVP Plan
+
+This plan turns `coven-github` from a promising open-source adapter into a monetizable hosted service.
+
+## Product Wedge
+
+OpenCoven should not compete as "another coding agent." The wedge is an owned GitHub coding pipeline:
+
+- Familiar identity instead of generic bot output.
+- BYOM and skill routing instead of model lock-in.
+- Self-hostable adapter for trust and adoption.
+- Hosted worker fleet for teams that do not want to operate infra.
+- CovenCave oversight so humans can watch, steer, and recover agent work.
+
+The paid product should sell reliability, memory, routing, and trust. Token arbitrage is not the business.
+
+The business frame from Astra: Cave oversight is the product surface, not a safety checkbox. Teams should feel like they are assigning work to a known teammate under their control, not gambling on a one-off agent run.
+
+Ideal first buyers:
+
+- Small engineering teams with more backlog than hands.
+- Platform teams that need safe dependency, docs, and maintenance PRs.
+- DevRel and open-source teams that triage issues across public repos.
+- Security-conscious teams that want the self-host escape hatch before adopting hosted workers.
+
+## Phase 1: Trustworthy Self-Hosted Adapter
+
+Goal: a stranger can install the App, trigger a familiar, and understand failures.
+
+- Keep README status honest with implemented, partial, and planned capabilities.
+- Expand self-hosting docs with smoke tests and troubleshooting.
+- Implement documented trigger labels.
+- Prevent familiar bot self-comment loops.
+- Enforce worker task timeouts.
+- Add security and isolation docs.
+- Add route and worker tests for the above.
+
+Status: started in this branch.
+
+## Phase 2: Hosted Control Plane Foundation
+
+Goal: a hosted installation can survive restarts and safely separate tenants.
+
+- Add persistent task store behind the existing task list API.
+- Store GitHub delivery ID and event coordinates for idempotency.
+- Add tenant model keyed by GitHub installation ID.
+- Move familiar routing from global TOML to installation-scoped config.
+- Protect `/api/github/tasks` with internal or tenant-scoped auth.
+- Persist task states: queued, running, needs input, review, done, failed.
+- Record Check Run, branch, PR, issue, and session links.
+- Record the familiar identity, memory scope, skill pack, and oversight session for each task.
+
+This is the first paid-service foundation. Without it, hosted cannot be trusted.
+
+## Phase 3: Production GitHub Correctness
+
+Goal: the adapter behaves correctly across real repositories.
+
+- Resolve repository default branch through GitHub API.
+- Resolve head SHA instead of using `HEAD` for Check Runs.
+- Use repository default branch instead of hardcoded `main` for PR base and session brief.
+- Add PR review comment diff hunk support.
+- Add retry behavior for transient GitHub API errors.
+- Add webhook tests for assigned, labeled, issue mentions, and PR review comments.
+
+## Phase 4: Worker Isolation and Usage Metering
+
+Goal: turn worker execution into a paid hosted unit.
+
+- Add containerized worker backend.
+- Keep process backend for local development.
+- Enforce CPU, memory, disk, timeout, and cleanup rules.
+- Meter task runtime, model provider, familiar, repo, and installation.
+- Add per-tier concurrency and task-credit limits.
+- Emit audit events for accepted, started, completed, failed, retried, and timed-out tasks.
+
+## Phase 5: Monetization Surface
+
+Goal: make buying obvious.
+
+- Publish `opencoven.ai/github` landing page.
+- Add hosted beta waitlist.
+- Offer self-hosted install docs as the trust path.
+- Package Hosted Starter, Hosted Team, and Hosted Dedicated.
+- Add Cave dashboard views for task history, usage, and familiar routing.
+- Add example PRs and demo videos for issue assignment to draft PR.
+
+## Near-Term Engineering Backlog
+
+1. Persistent task store and idempotency.
+2. Tenant-scoped installation config.
+3. Authenticated task API for Cave.
+4. Default branch and head SHA resolution.
+5. Container worker backend.
+6. Hosted beta landing page and waitlist.
+
+## Success Metrics
+
+- Self-hosted user can complete the smoke test in under 15 minutes.
+- Hosted beta user can install the GitHub App and trigger a visible task in under 5 minutes.
+- Every accepted webhook has a durable task record.
+- Every worker task has a terminal state.
+- A failed task leaves enough evidence for the operator to know whether the failure was spec, code, model, GitHub API, or infrastructure.
diff --git a/docs/hosted-vs-self-hosted.md b/docs/hosted-vs-self-hosted.md
new file mode 100644
index 0000000..c946c93
--- /dev/null
+++ b/docs/hosted-vs-self-hosted.md
@@ -0,0 +1,91 @@
+# Hosted vs Self-Hosted
+
+`coven-github` stays open source so teams can run a Coven-native GitHub App in their own infrastructure. The hosted OpenCoven service should monetize the parts that are operationally expensive: secure workers, durable queues, cross-repo familiar memory, observability, and multi-familiar routing.
+
+## Who Should Self-Host
+
+Self-hosting is best for:
+
+- Solo maintainers and small teams that already operate their own infrastructure.
+- Teams that want BYOM and local CovenCave oversight without managed OpenCoven services.
+- Organizations that need source-available control before committing to a paid hosted tier.
+- Security reviewers validating the adapter before installing a hosted GitHub App.
+
+Self-hosted users manage:
+
+- GitHub App registration, private key storage, and webhook secret rotation.
+- Worker hosts, logs, upgrades, and task retries.
+- Model credentials and `coven-code` runtime installation.
+- Workspace isolation and cleanup.
+- Task persistence and queue durability once they move beyond the in-process development path.
+
+## Who Should Use Hosted OpenCoven
+
+Hosted is best for:
+
+- Teams that want to assign GitHub issues to familiars without running worker infrastructure.
+- Organizations that want managed uptime, usage controls, audit logs, and billing.
+- Teams that need familiar memory across repositories and repeated PRs.
+- Engineering leaders who want multiple specialist familiars: implementation, review, security, docs, release, and triage.
+
+Hosted OpenCoven should manage:
+
+- GitHub App installation and webhook ingress.
+- Durable task queue, retries, and task history.
+- Ephemeral worker environments with cleanup and timeout enforcement.
+- Centralized usage metering, limits, and billing.
+- Organization and repository routing policy.
+- Familiar memory, skills, and model routing.
+- CovenCave oversight links for live intervention.
+
+## Pricing Shape
+
+The initial pricing should be simple enough to buy without procurement drama:
+
+| Tier | Buyer | Packaging |
+|---|---|---|
+| Community | OSS maintainers and self-hosters | Free self-hosted adapter, community support, one familiar per installation. |
+| Hosted Starter | Indie teams and small shops | Monthly base fee with included task credits, one organization, one or two familiars, standard worker pool. |
+| Hosted Team | Product teams | Higher task credits, cross-repo familiar memory, multi-familiar routing, team usage dashboard, priority support. |
+| Hosted Dedicated | Security-sensitive orgs | Dedicated workers, private network options, stronger audit retention, custom limits, SLA, onboarding support. |
+
+The sell is not cheaper tokens. The sell is an owned, inspectable coding agent pipeline with persistent familiar identity, self-host escape hatch, and enough managed reliability that teams can trust it with real backlog work.
+
+## Familiar Advantage
+
+The strongest hosted pitch is trust continuity. Teams are not buying a bot that can edit files; they are deploying a familiar that knows their context, standards, release posture, and repeated pain points.
+
+Suggested positioning:
+
+> Assign it like a teammate. Get a PR back. Your familiar knows the difference between good and good enough for your repo.
+
+That makes Cave oversight a primary product surface, not a safety footnote. The buyer should see:
+
+- who the familiar is,
+- what team context it used,
+- what it tried,
+- what changed,
+- what evidence it collected,
+- where it needs human judgment.
+
+This is the part generic GitHub coding agents do not have: identity, relationship, memory, and operational trust.
+
+## Buyer Proof Needed Before Launch
+
+- A public status matrix that separates implemented, partial, and planned capabilities.
+- A security document covering private keys, installation tokens, model credentials, workspace cleanup, and data retention.
+- A short operator guide that gets a self-hosted GitHub App to a successful webhook smoke test.
+- A hosted beta CTA with a clear promise: "Assign an issue to Cody; get a draft PR back with a Cave oversight link."
+- Two demo videos or GIFs: issue assignment to Check Run, then draft PR back to issue.
+- A familiar contract page that explains behavioral guarantees, oversight, and failure transparency.
+
+## Landing Page Brief
+
+Recommended structure for `opencoven.ai/github`:
+
+1. Headline: "Assign an issue to your familiar. Get a PR back."
+2. Three-step flow: install GitHub App, configure familiar, assign issue or label.
+3. Trust block: open source adapter, BYOM, familiar memory, Cave oversight, self-hostable.
+4. Hosted/service block: managed workers, durable queues, usage limits, auditability, multi-familiar routing.
+5. Security block: installation tokens, ephemeral workspaces, no user Git credentials, retention policy.
+6. CTA pair: "Join hosted beta" and "Self-host from GitHub."
diff --git a/docs/security.md b/docs/security.md
new file mode 100644
index 0000000..68d76b4
--- /dev/null
+++ b/docs/security.md
@@ -0,0 +1,82 @@
+# Security Model
+
+This document describes the security boundaries `coven-github` needs for self-hosted operators and the hosted OpenCoven service.
+
+## GitHub App Credentials
+
+`coven-github` authenticates as a GitHub App:
+
+- The GitHub App private key signs short-lived JWTs.
+- JWTs are exchanged for installation access tokens scoped to a specific installation.
+- Installation tokens are used for repository clone, Check Runs, comments, and pull requests.
+- User GitHub credentials are never required for worker pushes.
+
+Self-hosted operators are responsible for storing the private key and webhook secret outside the repository. Hosted OpenCoven should store these in managed secret storage and rotate webhook secrets when an installation is reconfigured.
+
+## Webhook Integrity
+
+Every webhook request must include `X-Hub-Signature-256`. The receiver validates the HMAC over the raw request body before parsing JSON. Invalid or missing signatures are rejected before task routing.
+
+Production hosted ingress should also add:
+
+- Delivery ID idempotency with `X-GitHub-Delivery`.
+- Rate limits by installation and repository.
+- Structured audit logs for accepted, rejected, and duplicate deliveries.
+
+## Worker Boundaries
+
+Workers execute `coven-code --headless` using a per-task workspace. Current development workers use local directories and enforce task timeouts. Production hosted workers should run each task in an isolated container or sandbox.
+
+Worker rules:
+
+- Create one workspace per task.
+- Pass only the installation token required for that repository.
+- Clean up workspaces after task completion or failure.
+- Enforce timeout and retry limits.
+- Persist failure states before cleanup.
+
+See [Container Isolation](container-isolation.md) for the production isolation target.
+
+## Token Handling
+
+The current session brief includes clone auth so `coven-code` can operate on the repository. The production target is stricter:
+
+- Prefer `GIT_ASKPASS` or environment-based git auth over embedding tokens in JSON.
+- 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.
+
+## Tenant Data
+
+Hosted OpenCoven should treat each GitHub installation as a tenant boundary.
+
+Tenant-scoped data:
+
+- Installation ID and repository list.
+- Familiar routing config.
+- Task history, status, branch, PR, and Check Run links.
+- Optional familiar memory, if enabled by the customer.
+
+The public task API must not return cross-installation data. The current in-memory `/api/github/tasks` path is suitable for local development and Cave polling, but hosted usage needs tenant-scoped authentication before launch.
+
+## Model and Memory Boundaries
+
+OpenCoven's strongest hosted differentiator is familiar identity plus memory. That also makes data boundaries explicit:
+
+- BYOM keys should be installation-scoped or organization-scoped.
+- Model routing choices should be visible to operators.
+- Cloud familiar memory should be opt-in for hosted customers.
+- Retention should be configurable by tier and organization policy.
+- PR bodies should disclose the familiar identity and link back to the oversight session.
+
+## Launch Gate
+
+Before accepting paid hosted customers, the service should have:
+
+- Durable task persistence.
+- Delivery idempotency.
+- Tenant-scoped task API auth.
+- Worker timeout enforcement.
+- Containerized or sandboxed worker execution.
+- Secret redaction tests.
+- A documented data retention policy.
diff --git a/docs/self-hosting.md b/docs/self-hosting.md
index 10aba74..a94704c 100644
--- a/docs/self-hosting.md
+++ b/docs/self-hosting.md
@@ -7,6 +7,10 @@ This guide walks you through registering a GitHub App and running `coven-github`
 - Rust toolchain (`rustup`)
 - `coven-code` binary installed and in PATH (or set `coven_code_bin` in config)
 - A public HTTPS endpoint for the webhook receiver (ngrok works for local dev)
+- A GitHub account with permission to create and install GitHub Apps
+- Model provider credentials available to the `coven-code` runtime you plan to use
+
+This guide targets macOS and Linux operators. Windows should work through WSL2 or a containerized worker, but the production isolation path is still being hardened.
 
 ## 1. Register a GitHub App
 
@@ -56,6 +60,21 @@ Edit `config/local.toml`:
 - Set `worker.coven_code_bin` to your `coven-code` binary path
 - Configure `[[familiars]]` with your bot username and model
 
+Important config fields:
+
+| Field | Purpose |
+|---|---|
+| `server.bind` | Local address the webhook server listens on. |
+| `server.cave_base_url` | Optional CovenCave URL used in Check Runs and comments. |
+| `github.app_id` | Numeric GitHub App ID from the App settings page. |
+| `github.private_key_path` | Path to the downloaded PEM private key. Do not commit it. |
+| `github.webhook_secret` | Secret GitHub uses to sign webhook deliveries. |
+| `worker.coven_code_bin` | Path to the `coven-code` binary with headless mode support. |
+| `worker.workspace_root` | Temporary task workspace root. Keep it outside the repo. |
+| `worker.timeout_secs` | Wall-clock limit for each familiar run. |
+| `familiars[].bot_username` | GitHub App bot username that assignment and mentions match. |
+| `familiars[].trigger_labels` | Labels such as `coven:fix` that create familiar tasks. |
+
 ## 5. Run
 
 ```bash
@@ -64,13 +83,34 @@ Edit `config/local.toml`:
 
 The server starts on the configured bind address. Point your GitHub App webhook at `https://your-host/webhook`.
 
-## 6. Test it
+Expected startup log:
+
+```txt
+coven-github listening on 0.0.0.0:3000
+```
+
+## 6. Local smoke test
+
+Before connecting a real GitHub App delivery, verify the server rejects unsigned payloads:
+
+```bash
+curl -i \
+  -H 'X-GitHub-Event: issues' \
+  -d '{"action":"labeled"}' \
+  http://localhost:3000/webhook
+```
+
+Expected result: `401 Unauthorized` with `{"error":"missing signature"}`. That confirms the webhook route is reachable and signature enforcement is active.
+
+## 7. End-to-end test
 
 On a repo where the App is installed:
 1. Create an issue
 2. Assign it to your bot user (`@coven-cody`)
 3. Watch the Check Run appear and the familiar start working
 
+You can also apply a configured label such as `coven:fix` to route the issue through `familiars[].trigger_labels`.
+
 ## Local development with ngrok
 
 ```bash
@@ -99,3 +139,17 @@ CMD ["coven-github", "serve", "--config", "/config/local.toml"]
 - Installation tokens expire every hour — coven-github refreshes them automatically
 - Never commit your private key PEM to the repository
 - Run workers in isolated containers per task in production (see `docs/container-isolation.md`)
+
+See [Security Model](security.md) and [Container Isolation](container-isolation.md) for the production security target.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `401 missing signature` | Local curl or GitHub did not send `X-Hub-Signature-256`. | Expected for unsigned smoke tests; check GitHub App webhook secret for real deliveries. |
+| `401 invalid signature` | `github.webhook_secret` does not match the GitHub App secret. | Rotate/copy the secret into `config/local.toml` and restart. |
+| No task appears after assignment | Bot username or installed repository does not match config. | Confirm `familiars[].bot_username` equals the App bot login and the App is installed on the repo. |
+| Label does nothing | Label is not in `familiars[].trigger_labels`. | Add the exact label name and restart. |
+| Check Run fails immediately | GitHub App permissions are incomplete or the head SHA/base branch path needs hardening. | Confirm Contents, Issues, Pull requests, Checks, and Metadata permissions. |
+| Familiar never exits | Runtime process hung. | Lower `worker.timeout_secs`; current workers enforce this timeout. |
+| No PR opens | `coven-code` did not write commits or a successful `result.json`. | Inspect worker logs and the task workspace before cleanup in a development run. |
diff --git a/examples/familiar-github-starter/README.md b/examples/familiar-github-starter/README.md
new file mode 100644
index 0000000..45795c4
--- /dev/null
+++ b/examples/familiar-github-starter/README.md
@@ -0,0 +1,13 @@
+# Familiar GitHub Starter
+
+This example shows a minimal familiar setup for routing GitHub issues to Cody through `coven-github`.
+
+Use it as a starting point for a demo repository:
+
+1. Copy `config.toml` to your own `config/local.toml`.
+2. Replace the GitHub App ID, private key path, and webhook secret.
+3. Set `bot_username` to your GitHub App bot login.
+4. Confirm `coven_code_bin` points at a `coven-code` binary with headless mode support.
+5. Add labels such as `coven:fix` and `coven:docs` to issues you want Cody to draft PRs for.
+
+The example keeps autonomy conservative: the familiar should draft PRs and expose Cave oversight rather than merging changes directly.
diff --git a/examples/familiar-github-starter/config.toml b/examples/familiar-github-starter/config.toml
new file mode 100644
index 0000000..802bb4f
--- /dev/null
+++ b/examples/familiar-github-starter/config.toml
@@ -0,0 +1,34 @@
+# Minimal self-hosted coven-github starter config.
+# Copy to config/local.toml and replace placeholders before running.
+
+[server]
+bind = "0.0.0.0:3000"
+cave_base_url = "http://localhost:3000"
+
+[github]
+app_id = 123456
+private_key_path = "keys/coven-cody.private-key.pem"
+webhook_secret = "replace-with-a-random-webhook-secret"
+
+[worker]
+concurrency = 1
+coven_code_bin = "/usr/local/bin/coven-code"
+workspace_root = "/tmp/coven-github-cody"
+timeout_secs = 1800
+max_retries = 1
+
+[[familiars]]
+id = "cody"
+display_name = "Cody"
+bot_username = "coven-cody[bot]"
+model = "openai/gpt-5.4"
+skills = [
+  "systematic-debugging",
+  "test-driven-development",
+  "verification-before-completion",
+]
+trigger_labels = [
+  "coven:fix",
+  "coven:docs",
+  "coven:review",
+]

From 57c1887239975b1bce01ee5c317ad4514cc311d3 Mon Sep 17 00:00:00 2001
From: Val Alexander <bunsthedev@gmail.com>
Date: Fri, 19 Jun 2026 22:23:36 -0500
Subject: [PATCH 2/6] fix: keep hosted MVP PR green

---
 DESIGN.md                      | 15 +++++++++++++++
 ROADMAP.md                     |  4 ++++
 crates/github/src/check_run.rs |  2 ++
 crates/github/src/pr.rs        |  2 ++
 4 files changed, 23 insertions(+)

diff --git a/DESIGN.md b/DESIGN.md
index 17f01b0..b48115a 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -62,6 +62,21 @@ Cave oversight is the control plane. It should show:
 
 Draft PRs are the default. The team should promote more autonomy only after the familiar earns trust through repeated visible work.
 
+## Operational Pattern
+
+ClawSweeper is the reference pattern for conservative GitHub automation inside the OpenClaw ecosystem: narrow promises, durable state, marker-backed comments edited in place, explicit maintainer commands, and deterministic gates before repair or merge work.
+
+`coven-github` should borrow the operating style without becoming the same product:
+
+- Keep one visible status surface per task instead of noisy repeated comments.
+- Treat maintainer commands as clear steering inputs, not casual chat.
+- Store durable task records before worker execution starts.
+- Re-check live GitHub state immediately before every mutation.
+- Prefer proposal, draft PR, and Cave approval loops before any higher-autonomy behavior.
+- Make status, evidence, and next action obvious to reviewers who never open Cave.
+
+The familiar layer adds the moat: a known teammate with repo and team context. The ClawSweeper pattern supplies the operational discipline that makes that familiar safe to trust.
+
 ## Trust Boundaries
 
 | Boundary | Rule |
diff --git a/ROADMAP.md b/ROADMAP.md
index 842193f..e83038b 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -33,6 +33,8 @@ Goal: support real hosted installations without losing task state or leaking ten
 - Installation-scoped familiar routing.
 - Tenant-scoped task API auth for Cave.
 - Task audit log and terminal states.
+- Marker-backed GitHub status comments that are edited in place per task.
+- Maintainer command router for status, stop, retry, explain, and approve.
 
 ## Milestone 3: GitHub Correctness
 
@@ -65,6 +67,7 @@ Goal: make the value legible and buyable.
 - Pricing: Community, Hosted Starter, Hosted Team, Hosted Dedicated.
 - Cave dashboard for task history, familiar routing, usage, and audit events.
 - Demo assets: issue assignment to Check Run, draft PR back to issue, Cave oversight intervention.
+- A reference demo showing the ClawSweeper-style operating loop: one visible status, explicit steering commands, durable audit trail, and familiar-specific PR output.
 
 ## Current Focus
 
@@ -72,3 +75,4 @@ Goal: make the value legible and buyable.
 2. Build persistent task state and idempotency.
 3. Move familiar routing from global TOML toward installation-scoped config.
 4. Make Cave oversight central in the public story and product loop.
+5. Borrow ClawSweeper's conservative GitHub bot ergonomics: edited status comments, maintainer steering commands, and live-state rechecks before mutation.
diff --git a/crates/github/src/check_run.rs b/crates/github/src/check_run.rs
index 0a1a232..fcbe6cf 100644
--- a/crates/github/src/check_run.rs
+++ b/crates/github/src/check_run.rs
@@ -99,6 +99,7 @@ pub async fn update(
     .await
 }
 
+#[allow(clippy::too_many_arguments)]
 pub async fn update_with_base_url(
     api_base_url: &str,
     installation_token: &str,
@@ -144,6 +145,7 @@ pub async fn complete(
     .await
 }
 
+#[allow(clippy::too_many_arguments)]
 pub async fn complete_with_base_url(
     api_base_url: &str,
     installation_token: &str,
diff --git a/crates/github/src/pr.rs b/crates/github/src/pr.rs
index f9e3759..0253074 100644
--- a/crates/github/src/pr.rs
+++ b/crates/github/src/pr.rs
@@ -11,6 +11,7 @@ struct PullRequestResponse {
 }
 
 /// Opens a draft pull request. Returns the PR number.
+#[allow(clippy::too_many_arguments)]
 pub async fn open_pull_request(
     installation_token: &str,
     repo_owner: &str,
@@ -41,6 +42,7 @@ pub async fn open_pull_request(
     .await
 }
 
+#[allow(clippy::too_many_arguments)]
 pub async fn open_pull_request_with_base_url(
     api_base_url: &str,
     installation_token: &str,

From 2f9e84526f2a83099a5d584893f5441551fb0db4 Mon Sep 17 00:00:00 2001
From: Val Alexander <bunsthedev@gmail.com>
Date: Fri, 19 Jun 2026 22:43:21 -0500
Subject: [PATCH 3/6] Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---
 crates/worker/src/lib.rs | 1 +
 1 file changed, 1 insertion(+)

diff --git a/crates/worker/src/lib.rs b/crates/worker/src/lib.rs
index f42b920..7fd18f0 100644
--- a/crates/worker/src/lib.rs
+++ b/crates/worker/src/lib.rs
@@ -255,6 +255,7 @@ async fn run_coven_code(
         Ok(status) => status?,
         Err(_) => {
             let _ = child.kill().await;
+            let _ = child.wait().await;
             anyhow::bail!(
                 "coven-code timed out after {} seconds",
                 config.worker.timeout_secs

From 35de017f8a7e5174c5f0aa53e4408d23f04bc5ba Mon Sep 17 00:00:00 2001
From: Val Alexander <bunsthedev@gmail.com>
Date: Fri, 19 Jun 2026 22:43:32 -0500
Subject: [PATCH 4/6] Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---
 crates/worker/src/lib.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/crates/worker/src/lib.rs b/crates/worker/src/lib.rs
index 7fd18f0..cd9d8ef 100644
--- a/crates/worker/src/lib.rs
+++ b/crates/worker/src/lib.rs
@@ -304,7 +304,7 @@ fn task_issue_number(kind: &TaskKind) -> Option<u64> {
     }
 }
 
-#[cfg(test)]
+#[cfg(all(test, unix))]
 mod tests {
     use super::*;
     use coven_github_config::{FamiliarConfig, GitHubAppConfig, ServerConfig, WorkerConfig};

From b7d44cba7b93697f70c651bf6c854d87942c04b7 Mon Sep 17 00:00:00 2001
From: Val Alexander <bunsthedev@gmail.com>
Date: Fri, 19 Jun 2026 22:43:39 -0500
Subject: [PATCH 5/6] Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---
 crates/webhook/src/routes.rs | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/crates/webhook/src/routes.rs b/crates/webhook/src/routes.rs
index 89027d1..01333dc 100644
--- a/crates/webhook/src/routes.rs
+++ b/crates/webhook/src/routes.rs
@@ -311,4 +311,22 @@ mod tests {
 
         assert!(task.is_none());
     }
+
+    #[test]
+    fn pr_review_comment_ignores_bot_self_mentions() {
+        let state = app_state();
+        let task = event_to_task(
+            &state,
+            GitHubEvent::PullRequestReviewComment(coven_github_api::PrReviewCommentEvent {
+                installation_id: 123,
+                repo_owner: "OpenCoven".to_string(),
+                repo_name: "coven-code".to_string(),
+                pr_number: 7,
+                comment_body: "@coven-cody please fix.".to_string(),
+                commenter_login: "coven-cody[bot]".to_string(),
+            }),
+        );
+
+        assert!(task.is_none());
+    }
 }

From 9405da0dd9bb4ebd06ca3ee72a49ec0027ed6a72 Mon Sep 17 00:00:00 2001
From: Val Alexander <bunsthedev@gmail.com>
Date: Sat, 20 Jun 2026 04:48:16 -0500
Subject: [PATCH 6/6] style: format hosted MVP rust sources

---
 crates/config/src/lib.rs   |  8 ++++++--
 crates/webhook/src/lib.rs  |  3 +--
 crates/worker/src/brief.rs | 42 +++++++++++++++++++++++---------------
 3 files changed, 32 insertions(+), 21 deletions(-)

diff --git a/crates/config/src/lib.rs b/crates/config/src/lib.rs
index c91af5c..250e4e6 100644
--- a/crates/config/src/lib.rs
+++ b/crates/config/src/lib.rs
@@ -45,8 +45,12 @@ pub struct WorkerConfig {
     pub max_retries: u32,
 }
 
-fn default_timeout() -> u64 { 600 }
-fn default_retries() -> u32 { 2 }
+fn default_timeout() -> u64 {
+    600
+}
+fn default_retries() -> u32 {
+    2
+}
 
 /// Per-familiar configuration for task routing.
 #[derive(Debug, Clone, Deserialize, Serialize)]
diff --git a/crates/webhook/src/lib.rs b/crates/webhook/src/lib.rs
index 27554c2..1af896c 100644
--- a/crates/webhook/src/lib.rs
+++ b/crates/webhook/src/lib.rs
@@ -15,8 +15,7 @@ pub fn verify_signature(secret: &str, payload: &[u8], signature_header: &str) ->
         .strip_prefix("sha256=")
         .ok_or_else(|| anyhow::anyhow!("missing sha256= prefix on signature"))?;
 
-    let sig_bytes = hex::decode(sig)
-        .map_err(|_| anyhow::anyhow!("invalid hex in signature"))?;
+    let sig_bytes = hex::decode(sig).map_err(|_| anyhow::anyhow!("invalid hex in signature"))?;
 
     let mut mac = HmacSha256::new_from_slice(secret.as_bytes())
         .map_err(|_| anyhow::anyhow!("HMAC key error"))?;
diff --git a/crates/worker/src/brief.rs b/crates/worker/src/brief.rs
index c8c0780..854b8f5 100644
--- a/crates/worker/src/brief.rs
+++ b/crates/worker/src/brief.rs
@@ -76,23 +76,31 @@ pub fn build(
     };
 
     let task_brief = match &task.kind {
-        TaskKind::FixIssue { issue_number, issue_title, issue_body } =>
-            TaskBrief::FixIssue {
-                issue_number: *issue_number,
-                issue_title: issue_title.clone(),
-                issue_body: issue_body.clone(),
-            },
-        TaskKind::AddressReviewComment { pr_number, comment_body, diff_hunk } =>
-            TaskBrief::AddressReviewComment {
-                pr_number: *pr_number,
-                comment_body: comment_body.clone(),
-                diff_hunk: diff_hunk.clone(),
-            },
-        TaskKind::RespondToMention { issue_number, comment_body } =>
-            TaskBrief::RespondToMention {
-                issue_number: *issue_number,
-                comment_body: comment_body.clone(),
-            },
+        TaskKind::FixIssue {
+            issue_number,
+            issue_title,
+            issue_body,
+        } => TaskBrief::FixIssue {
+            issue_number: *issue_number,
+            issue_title: issue_title.clone(),
+            issue_body: issue_body.clone(),
+        },
+        TaskKind::AddressReviewComment {
+            pr_number,
+            comment_body,
+            diff_hunk,
+        } => TaskBrief::AddressReviewComment {
+            pr_number: *pr_number,
+            comment_body: comment_body.clone(),
+            diff_hunk: diff_hunk.clone(),
+        },
+        TaskKind::RespondToMention {
+            issue_number,
+            comment_body,
+        } => TaskBrief::RespondToMention {
+            issue_number: *issue_number,
+            comment_body: comment_body.clone(),
+        },
     };
 
     SessionBrief {