[codex] Operationalize coven-github hosted MVP

[BunsDev]

Summary

This PR operationalizes the coven-github hosted MVP direction around the familiar moat: a known team-aware familiar working through GitHub with Cave oversight as the core trust surface.

What changed

• Adds real issues.labeled webhook trigger support for configured familiar trigger_labels.
• Suppresses familiar bot self-comments so issue/PR mention loops do not retrigger tasks.
• Enforces configured worker timeouts for coven-code --headless runs.
• Adds tests for label parsing/routing, self-comment suppression, and worker timeout behavior.
• Adds strategic and operational docs: DESIGN.md, HOSTED.md, FAMILIAR-CONTRACT.md, ROADMAP.md, hosted/self-hosted docs, security docs, container isolation docs, and a starter GitHub familiar example.
• Captures the ClawSweeper-inspired operating pattern: one visible task status, marker-backed/edit-in-place comments, explicit maintainer steering commands, durable audit trail, and live-state rechecks before mutation.
• Updates the README and self-hosting guide so implementation status, familiar positioning, and hosted path are clearer.

Why

The strongest market wedge is not “another GitHub coding agent.” It is trust continuity: teams can deploy a familiar that knows their repo, team standards, and operational context, with Cave oversight making the workflow auditable and controlled.

ClawSweeper is a useful internal reference for the operational style: conservative GitHub automation, durable state, explicit maintainer commands, and deterministic gates. coven-github borrows that discipline while adding the familiar/team-context layer as the moat.

Validation

• cargo clippy --all-targets -- -D warnings
• cargo test --workspace
• git diff --check

Opened as a draft so the repo has a visible PR while leaving room for review before merge.

[Copilot]

Pull request overview

This PR operationalizes the hosted coven-github MVP direction by hardening the GitHub App adapter’s trigger surface (including issues.labeled), adding loop-suppression for bot self-comments, enforcing worker timeouts for coven-code --headless, and adding supporting tests and operational documentation.

Changes:

• Added issues.labeled webhook parsing + routing via familiar trigger_labels.
• Prevented familiar self-comment mention loops from retriggering tasks.
• Enforced worker.timeout_secs for coven-code --headless runs and added tests/docs for the operational model.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
ROADMAP.md	Adds a milestone-based roadmap for hosted + self-hosted evolution.
README.md	Updates positioning and capability/status matrix; links to new docs and starter example.
HOSTED.md	Documents hosted tier value-add, packaging, and data boundaries.
FAMILIAR-CONTRACT.md	Defines behavioral guarantees and launch rules for familiars.
examples/familiar-github-starter/README.md	Adds a minimal familiar setup walkthrough for demos.
examples/familiar-github-starter/config.toml	Provides a starter TOML config including trigger_labels.
docs/self-hosting.md	Expands operator docs with prerequisites, smoke test, and troubleshooting.
docs/security.md	Introduces a security model and boundaries for credentials, webhooks, workers, and tenants.
docs/hosted-vs-self-hosted.md	Clarifies buyer/operator split and packaging rationale.
docs/hosted-mvp-plan.md	Captures phased plan from self-host hardening to hosted control plane.
docs/container-isolation.md	Defines the container/sandbox isolation target and worker contract.
DESIGN.md	Documents task flow, routing model, trust boundaries, and operational pattern.
crates/worker/src/lib.rs	Implements coven-code timeout enforcement and adds a timeout test.
crates/webhook/src/routes.rs	Adds label-trigger routing and self-comment suppression; adds unit tests for routing.
crates/webhook/src/events.rs	Extends webhook parsing to emit IssueLabeled events + tests.
crates/github/src/pr.rs	Suppresses clippy lint for many-arg PR helpers (no logic change).
crates/github/src/lib.rs	Adds IssueLabeledEvent and GitHubEvent::IssueLabeled.
crates/github/src/check_run.rs	Suppresses clippy lint for many-arg check-run helpers (no logic change).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[BunsDev]

Review pass: no blocking findings.

I reviewed the webhook label routing, bot self-comment suppression, worker timeout/reaping path, ClawSweeper-inspired docs additions, and the later Copilot autofix commits. The added tests cover the new routing paths and timeout behavior, and the PR is mergeable with GitHub CI green.

Validation checked locally on the PR head:

• cargo clippy --all-targets -- -D warnings
• cargo test --workspace
• git diff --check origin/main...HEAD

Residual non-blocking note: cargo fmt --check still reports pre-existing formatting drift in crates/config/src/lib.rs, crates/webhook/src/lib.rs, and crates/worker/src/brief.rs; those files are outside this PR’s changed surface.