docs: update forge PRD — orchestrator split, done signal, org targeting, forge env vars

docs: add PRD for forge native integration
fix(skills): validate skill names and quote provisioning paths
2026-06-29 12:39:02 -04:00 · 2026-06-29 12:10:41 -04:00 · 2026-06-27 02:15:30 -04:00
7 changed files with 408 additions and 11 deletions
@@ -217,7 +217,7 @@ class ClaudeAgentProvider(AgentProvider):
        if not agent.skills:
            return
        skills_dir = _skills_dir(plan.guest_home)
-        bottle.exec(f"mkdir -p {skills_dir}", user="root")
+        bottle.exec(f"mkdir -p {shlex.quote(skills_dir)}", user="root")
        for name in agent.skills:
            src = host_skill_dir(name)
            if not os.path.isdir(src):
@@ -227,9 +227,13 @@ class ClaudeAgentProvider(AgentProvider):
                )
            dst = f"{skills_dir}/{name}"
            info(f"copying skill {name} into {bottle.name}:{dst}")
-            bottle.exec(f"rm -rf {dst} && mkdir -p {dst}", user="root")
+            # Defense in depth: skill names are validated kebab-case at
+            # manifest load, but quote the path so a future unvalidated
+            # field can't inject shell metacharacters here either.
+            dst_q = shlex.quote(dst)
+            bottle.exec(f"rm -rf {dst_q} && mkdir -p {dst_q}", user="root")
            bottle.cp_in(f"{src}/.", f"{dst}/")
-            bottle.exec(f"chown -R node:node {dst}", user="root")
+            bottle.exec(f"chown -R node:node {dst_q}", user="root")

    def provision_prompt(self, plan: "BottlePlan", bottle: "Bottle") -> str | None:
        """Copy the prompt file into the guest, fix ownership/mode.
@@ -183,7 +183,7 @@ class CodexAgentProvider(AgentProvider):
        if not agent.skills:
            return
        skills_dir = _skills_dir(plan.guest_home)
-        bottle.exec(f"mkdir -p {skills_dir}", user="root")
+        bottle.exec(f"mkdir -p {shlex.quote(skills_dir)}", user="root")
        for name in agent.skills:
            src = host_skill_dir(name)
            if not os.path.isdir(src):
@@ -193,9 +193,13 @@ class CodexAgentProvider(AgentProvider):
                )
            dst = f"{skills_dir}/{name}"
            info(f"copying skill {name} into {bottle.name}:{dst}")
-            bottle.exec(f"rm -rf {dst} && mkdir -p {dst}", user="root")
+            # Defense in depth: skill names are validated kebab-case at
+            # manifest load, but quote the path so a future unvalidated
+            # field can't inject shell metacharacters here either.
+            dst_q = shlex.quote(dst)
+            bottle.exec(f"rm -rf {dst_q} && mkdir -p {dst_q}", user="root")
            bottle.cp_in(f"{src}/.", f"{dst}/")
-            bottle.exec(f"chown -R node:node {dst}", user="root")
+            bottle.exec(f"chown -R node:node {dst_q}", user="root")

    def provision_prompt(self, plan: "BottlePlan", bottle: "Bottle") -> str | None:
        """Copy the prompt file into the guest, fix ownership/mode.
@@ -238,7 +238,7 @@ class PiAgentProvider(AgentProvider):
        if not agent.skills:
            return
        skills_dir = _skills_dir(plan.guest_home)
-        bottle.exec(f"mkdir -p {skills_dir}", user="root")
+        bottle.exec(f"mkdir -p {shlex.quote(skills_dir)}", user="root")
        for name in agent.skills:
            src = host_skill_dir(name)
            if not os.path.isdir(src):
@@ -248,9 +248,13 @@ class PiAgentProvider(AgentProvider):
                )
            dst = f"{skills_dir}/{name}"
            info(f"copying skill {name} into {bottle.name}:{dst}")
-            bottle.exec(f"rm -rf {dst} && mkdir -p {dst}", user="root")
+            # Defense in depth: skill names are validated kebab-case at
+            # manifest load, but quote the path so a future unvalidated
+            # field can't inject shell metacharacters here either.
+            dst_q = shlex.quote(dst)
+            bottle.exec(f"rm -rf {dst_q} && mkdir -p {dst_q}", user="root")
            bottle.cp_in(f"{src}/.", f"{dst}/")
-            bottle.exec(f"chown -R node:node {dst}", user="root")
+            bottle.exec(f"chown -R node:node {dst_q}", user="root")

    def provision_prompt(self, plan: "BottlePlan", bottle: "Bottle") -> str | None:
        prompt_path = _prompt_path(plan.guest_home)
@@ -8,7 +8,7 @@ from typing import cast
 from .agent_provider import PROVIDER_TEMPLATES
 from .manifest_util import ManifestError, as_json_object
 from .manifest_git import ManifestGitUser
-from .manifest_schema import AGENT_MODEL_KEYS
+from .manifest_schema import AGENT_MODEL_KEYS, is_valid_entity_name


@dataclass(frozen=True)
@@ -161,6 +161,16 @@ class ManifestAgent:
                        f"agent '{name}' skills[{i}] must be a string "
                        f"(was {type(skill).__name__})"
                    )
+                # Skill names become host/guest path segments and are
+                # interpolated into provisioning shell commands, so they
+                # must fit the same kebab-case convention as bottle/agent
+                # filenames — rejecting anything that could break out of a
+                # path segment or inject shell metacharacters.
+                if not is_valid_entity_name(skill):
+                    raise ManifestError(
+                        f"agent '{name}' skills[{i}] {skill!r} is not a valid "
+                        f"skill name; must match [a-z][a-z0-9-]*"
+                    )
                collected.append(skill)
            skills = tuple(collected)

@@ -33,13 +33,20 @@ AGENT_KEYS = (
 AGENT_MODEL_KEYS = AGENT_KEYS | frozenset({"prompt"})


+def is_valid_entity_name(name: str) -> bool:
+    """True if `name` fits the kebab-case `[a-z][a-z0-9-]*` convention
+    shared by bottle/agent filenames and skill names. Names that satisfy
+    this are also safe to interpolate into a host/guest path segment."""
+    return bool(_FILENAME_RX.match(name))
+
+
 def entity_name_from_path(path: Path) -> str | None:
    """Return the entity name implied by the filename, or None if the
    filename does not fit the [a-z][a-z0-9-]* convention."""
    if path.suffix != ".md":
        return None
    stem = path.stem
-    if not _FILENAME_RX.match(stem):
+    if not is_valid_entity_name(stem):
        return None
    return stem

@@ -0,0 +1,352 @@
+# PRD prd-new: Forge native integration
+
+- **Status:** Draft
+- **Author:** claude
+- **Created:** 2026-06-29
+- **Issue:** #317
+
+## Summary
+
+Add a webhook-driven orchestration layer that lets Gitea issues and PR comments
+drive bot-bottle sessions end-to-end with no operator in the loop for the happy
+path. An issue assigned to a member of the configured agent org and labelled
+with an agent name triggers a headless bottle launch; the bottle processes the
+issue, opens a PR, and posts a done-comment via the Gitea API (through
+cred-proxy) before exiting. The orchestrator detects the done-comment, freezes
+the bottle, and attaches a provenance footer. Subsequent PR comments rehydrate
+the frozen bottle. The bottle is destroyed when the PR closes.
+
+The separation of concerns across the two layers: bot-bottle owns the headless
+launch primitives, forge state, Gitea client, and provenance builder.
+`bot-bottle-orchestrator` (separate binary) owns the webhook listener, bottle
+lifecycle loop, and monitoring dashboard; it calls into bot-bottle via
+`./cli.py orchestrate`, a thin wrapper command. This PRD covers bot-bottle's
+side of that contract.
+
+## Problem
+
+Today an operator must open the TUI, select an agent and bottle, confirm the
+preflight, and type prompts interactively. This blocks "issue → PR" automation
+and produces no durable audit record of what the agent did. The security model
+already provides the right isolation and egress controls; the missing pieces are
+the headless launch primitive that `bot-bottle-orchestrator` can call, the
+in-bottle Gitea API access the agent uses to signal completion, and the
+provenance trail that makes the audit story legible to reviewers on every PR.
+
+## Goals / Success Criteria
+
+1. `./cli.py orchestrate start` and `./cli.py orchestrate resume` are the
+   non-interactive counterparts to `start` and `resume`. They accept agent,
+   bottle, and prompt via flags rather than TUI pickers, and exit when the
+   agent process exits.
+2. An issue assigned to a member of the configured org (`FORGE_ORG`, default
+   `bot-bottle`) and labelled `bot-bottle:<agent-name>` is the trigger
+   convention. Org membership is verified via the Gitea API at event time.
+3. Forge-targeted bottles receive a set of env vars at launch
+   (`FORGE_GITEA_API`, `FORGE_OWNER`, `FORGE_REPO`, `FORGE_ISSUE_NUMBER`) so
+   the agent knows where to post its done-comment without hardcoding forge
+   context in the agent manifest.
+4. The agent's egress policy for forge runs includes `gitea.<host>` with Bearer
+   auth injected by cred-proxy, enabling direct Gitea API calls from inside the
+   bottle.
+5. The done-comment the agent posts is the done signal. A watchdog timeout
+   (configurable, default 30 min) causes the orchestrator to post the
+   done-comment on the agent's behalf if the agent exits without posting one.
+6. Every orchestrator-posted comment ends with a provenance footer: agent name,
+   bottle name(s), slug, start time, duration, exit code, gitleaks result, and
+   egress summary.
+7. Forge state (issue → slug, status) is persisted to disk and survives
+   orchestrator restarts.
+8. `./cli.py orchestrate status` lists active forge-managed bottles and their
+   issue/PR URLs.
+9. Unit tests cover: label parsing, org-membership check path, forge state
+   read/write, provenance footer rendering, headless launch arg construction,
+   forge env var injection, echo-loop guard.
+
+## Non-goals
+
+- Webhook signature verification (HMAC-SHA256). Added as a follow-up.
+- The `bot-bottle-orchestrator` binary itself — this PRD covers bot-bottle's
+  side of the interface only. The orchestrator is a separate project.
+- GitHub or GitLab support.
+- Multiple simultaneous forge bottles per issue.
+- Automatic retry on agent error exit.
+- Bottle destruction on issue close (PR close only; issue close is ambiguous).
+- Concurrent multi-issue handling (one blocking run per orchestrator process).
+- A monitoring dashboard (orchestrator-side concern).
+
+## Design
+
+### Targeting convention
+
+An issue is forge-targeted when **both** hold:
+
+- At least one assignee is a member of the Gitea org named by `FORGE_ORG`
+  (default `bot-bottle`). Checked via `GET /api/v1/orgs/{org}/members/{user}`.
+- At least one label has the prefix `bot-bottle:`. The suffix names the agent
+  manifest, e.g. `bot-bottle:implementer` → agent `implementer`.
+
+`FORGE_ORG` is read at orchestrate-command startup. It is not embedded in
+manifests or state files; the orchestrator stamps its value into log output for
+auditability.
+
+An optional label `bot-bottle-bottle:<name>` overrides bottle selection. When
+absent the agent's default bottle is used.
+
+### `./cli.py orchestrate` — the thin wrapper
+
+```
+./cli.py orchestrate start  --agent AGENT [--bottle BOTTLE ...] --prompt PROMPT
+                            [--label LABEL] [--backend BACKEND]
+./cli.py orchestrate resume --slug SLUG --prompt PROMPT [--backend BACKEND]
+./cli.py orchestrate status
+```
+
+`orchestrate start` is `start_headless` exposed as a subcommand. It prepares
+the bottle non-interactively, launches the agent in print mode, and exits
+with the agent's exit code. The caller (`bot-bottle-orchestrator`) manages
+freeze, state, and Gitea comments around it.
+
+`orchestrate resume` is `resume_headless` exposed as a subcommand.
+
+`orchestrate status` prints the forge state table.
+
+### Headless primitives
+
+**`attach_agent_headless`** — new function in `bot_bottle/cli/start.py`:
+
+```python
+def attach_agent_headless(
+    bottle: Bottle,
+    *,
+    prompt: str,
+    resume: bool = False,
+    agent_provider_template: str = "claude",
+    startup_args: tuple[str, ...] = (),
+) -> int:
+    runtime = runtime_for(agent_provider_template)
+    agent_args = list(runtime.bypass_args)   # --dangerously-skip-permissions
+    agent_args.extend(startup_args)
+    agent_args.append("--no-interactive")
+    if resume:
+        agent_args.extend(runtime.resume_args)  # --continue
+    agent_args.extend(["-p", prompt])
+    return bottle.exec_agent(agent_args, tty=False)
+```
+
+**`start_headless`** — new function in `bot_bottle/cli/start.py` that mirrors
+`_launch_bottle` without any TUI steps:
+
+```python
+def start_headless(
+    manifest: ManifestIndex,
+    *,
+    agent_name: str,
+    bottle_names: tuple[str, ...],
+    label: str,
+    prompt: str,
+    forge_env: dict[str, str] | None = None,
+    backend_name: str | None = None,
+) -> tuple[str, int]:
+    """Non-interactive bottle launch. Returns (slug, exit_code)."""
+```
+
+`forge_env` is merged into the bottle's `guest_env` so the agent receives the
+forge context as env vars (see below). The caller freezes the bottle after
+`start_headless` returns.
+
+**`resume_headless`** — new function in `bot_bottle/cli/resume.py`:
+
+```python
+def resume_headless(slug: str, *, prompt: str, backend_name: str | None = None) -> int:
+    """Rehydrate a frozen bottle and run one headless prompt. Returns exit_code."""
+```
+
+### Forge env vars
+
+The orchestrator builds this dict and passes it to `start_headless` as
+`forge_env`:
+
+| Var | Example | Purpose |
+|---|---|---|
+| `FORGE_GITEA_API` | `https://gitea.dideric.is/api/v1` | Base URL for Gitea API calls |
+| `FORGE_OWNER` | `didericis` | Repo owner |
+| `FORGE_REPO` | `bot-bottle` | Repo name |
+| `FORGE_ISSUE_NUMBER` | `317` | Issue that triggered the run |
+| `FORGE_PR_NUMBER` | `318` | PR to comment on (empty until PR exists) |
+
+The agent's system prompt (from the manifest) instructs it to post a comment to
+`$FORGE_GITEA_API/repos/$FORGE_OWNER/$FORGE_REPO/issues/$FORGE_ISSUE_NUMBER/comments`
+when it finishes a work unit. The instruction is part of the forge-specific
+agent prompt, not the base agent manifest, so non-forge runs are unaffected.
+
+### Gitea egress for forge-targeted bottles
+
+Forge-targeted bottles get an additional egress route injected by the
+orchestrator at launch time. This is passed as an extra `EgressRoute` in the
+`BottleSpec` (or via the forge env and bottle manifest) rather than requiring
+operators to add it to every agent manifest:
+
+```yaml
+host: gitea.dideric.is
+auth:
+  scheme: Bearer
+  token_env: GITEA_TOKEN
+```
+
+The cred-proxy injects the token; the agent never sees the raw credential.
+
+### Done signal and watchdog
+
+The agent posts a Gitea comment when it finishes a work unit. The orchestrator
+webhook listener receives the `issue_comment` event and:
+
+1. Verifies the commenter is a member of `FORGE_ORG`.
+2. Reads the forge state for `(owner, repo, issue_number)`.
+3. If `status == "running"`, treats the comment as the done signal: freezes the
+   bottle, appends the provenance footer to the same comment thread, sets
+   `status = "frozen"`.
+
+**Watchdog**: the orchestrator tracks `last_checkin_at` in forge state. A
+background thread wakes every minute. If `now - last_checkin_at > FORGE_WATCHDOG_TIMEOUT`
+(default 30 min, configurable via env) and `status == "running"`, the
+orchestrator posts the provenance footer comment on behalf of the agent and
+freezes the bottle.
+
+Echo-loop guard: comments from members of `FORGE_ORG` that are not the
+currently-running slug's agent user are still dispatched as resume triggers, not
+as done signals. The comment-is-done-signal path checks that
+`comment.user.login == agent_git_user` (read from forge state).
+
+### Forge state — `bot_bottle/contrib/gitea/forge_state.py`
+
+```
+~/.bot-bottle/forge/
+    <owner>/
+        <repo>/
+            issue-<n>.json
+```
+
+Schema:
+
+```json
+{
+  "slug": "implementer-abc12",
+  "pr_number": 42,
+  "agent_name": "implementer",
+  "bottle_names": ["claude"],
+  "backend_name": "docker",
+  "agent_git_user": "didericis-claude",
+  "issue_number": 17,
+  "owner": "didericis",
+  "repo": "bot-bottle",
+  "status": "frozen",
+  "last_checkin_at": "2026-06-29T12:04:12-04:00"
+}
+```
+
+`status`: `"running"` | `"frozen"` | `"destroyed"`.
+
+Public API:
+
+```python
+def write_forge_state(state: ForgeState) -> None: ...
+def read_forge_state(owner: str, repo: str, issue_number: int) -> ForgeState | None: ...
+def delete_forge_state(owner: str, repo: str, issue_number: int) -> None: ...
+def all_forge_states() -> list[ForgeState]: ...
+```
+
+Writes use atomic rename (`os.replace`) for crash safety.
+
+### Provenance — `bot_bottle/contrib/gitea/provenance.py`
+
+```python
+def build_provenance_footer(
+    slug: str,
+    *,
+    agent_name: str,
+    bottle_names: tuple[str, ...],
+    started_at: str,
+    finished_at: str,
+    exit_code: int,
+    watchdog_fired: bool = False,
+    egress_log_path: Path | None = None,
+) -> str:
+    """Return a markdown string for appending to a Gitea comment body."""
+```
+
+Output (collapsed by default):
+
+```markdown
+<details><summary>🔬 Run provenance</summary>
+
+| Field | Value |
+|---|---|
+| agent | `implementer` |
+| bottle | `claude` |
+| slug | `implementer-abc12` |
+| started | 2026-06-29T12:00:00-04:00 |
+| duration | 4m 12s |
+| exit | 0 ✓ |
+| gitleaks | ✓ no secrets detected |
+| done signal | agent comment *(or: watchdog — agent did not check in)* |
+
+**Egress** (deny-by-default; 3 routes allowed)
+- `api.anthropic.com` — Bearer auth
+- `gitea.dideric.is` — Bearer auth
+- `pypi.org` — unauthenticated
+
+</details>
+```
+
+The egress summary is read from `~/.bot-bottle/state/<slug>/egress/`. When
+unavailable the section is omitted. `watchdog_fired=True` changes the
+"done signal" row to warn reviewers.
+
+### Gitea client — `bot_bottle/contrib/gitea/client.py`
+
+```python
+class GiteaClient:
+    def __init__(self, *, api_url: str) -> None: ...
+    def is_org_member(self, org: str, username: str) -> bool: ...
+    def post_comment(self, owner: str, repo: str, issue_number: int, body: str) -> None: ...
+    def get_pr_for_issue(self, owner: str, repo: str, issue_number: int) -> int | None: ...
+    def is_pr_open(self, owner: str, repo: str, pr_number: int) -> bool: ...
+```
+
+Auth is not configured in the client — the egress layer injects the token on
+the way out, matching the existing `GiteaDeployKeyProvisioner` pattern.
+
+### Implementation chunks
+
+1. **Headless primitives** — `attach_agent_headless` + `start_headless` (with
+   `forge_env` param) in `cli/start.py`; `resume_headless` in `cli/resume.py`.
+   Tests: no tty, correct arg order, `forge_env` appears in `guest_env`.
+
+2. **Forge state** — `contrib/gitea/forge_state.py`: `ForgeState` dataclass,
+   read/write/delete/all helpers, atomic rename. Tests: round-trip JSON, missing
+   file → None, atomic write.
+
+3. **Gitea client** — `contrib/gitea/client.py`: `is_org_member`,
+   `post_comment`, `get_pr_for_issue`, `is_pr_open`. Tests: mock
+   `urllib.request.urlopen`, assert payloads and 404-as-false for membership.
+
+4. **Provenance** — `contrib/gitea/provenance.py`: `build_provenance_footer`.
+   Tests: required fields present, watchdog row text, egress omitted when log
+   absent.
+
+5. **`./cli.py orchestrate`** — `cli/orchestrate.py` with `start`, `resume`,
+   `status` subcommands wired into `cli.py`. Tests: arg parsing, `start`
+   delegates to `start_headless`, `resume` delegates to `resume_headless`.
+
+## Provenance as the product
+
+Every orchestrator-posted comment ends with the provenance footer — non-optional
+and not configurable off. PRs that land without a footer were not produced by
+this integration. The `watchdog_fired` flag in the footer flags runs where the
+agent did not self-report completion, so reviewers know the audit trail may be
+incomplete.
+
+The footer links to the bot-bottle repo pinned to the commit SHA active during
+the run (not `main`), so the policy that governed the run is permanently
+anchored in the PR history.
@@ -165,6 +165,22 @@ class TestAgentValidation(unittest.TestCase):
        with self.assertRaises(ManifestError):
            ManifestAgent.from_dict("a", {"skills": [5]}, set())

+    def test_skill_name_rejects_shell_metacharacters(self) -> None:
+        # Skill names become host/guest path segments interpolated into
+        # provisioning shell commands; anything outside kebab-case is
+        # rejected at load so it can never reach a `bottle.exec` string.
+        for bad in ("foo; rm -rf /", "../escape", "foo bar", "Foo", "-leading"):
+            with self.assertRaises(ManifestError):
+                ManifestAgent.from_dict("a", {"skills": [bad]}, set())
+
+    def test_skill_name_accepts_kebab_case(self) -> None:
+        agent = ManifestAgent.from_dict(
+            "a", {"skills": ["init-entry", "quality-eval", "skill0"]}, set()
+        )
+        self.assertEqual(
+            agent.skills, ("init-entry", "quality-eval", "skill0")
+        )
+
    def test_prompt_not_string(self) -> None:
        with self.assertRaises(ManifestError):
            ManifestAgent.from_dict("a", {"prompt": 5}, set())