docs(prd): add PRD for egress control plane

Out-of-band egress enforcement & cost-control plane: meter token usage
at the egress proxy, evaluate budgets with agent→bottle→parent→global
precedence, and force cutoff/freeze/kill without the agent in the loop.
Introduces a host-level SQLite ledger behind a thin repository API and a
host-only TUI dashboard. Closes the design discussion on #251.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NkwFXLFff9PYPy4wgVBJp9

bot_bottle/contrib/claude/agent_provider.py

@@ -217,7 +217,7 @@ class ClaudeAgentProvider(AgentProvider):
         if not agent.skills:
             return
         skills_dir = _skills_dir(plan.guest_home)
-        bottle.exec(f"mkdir -p {shlex.quote(skills_dir)}", user="root")
+        bottle.exec(f"mkdir -p {skills_dir}", user="root")
         for name in agent.skills:
             src = host_skill_dir(name)
             if not os.path.isdir(src):
@@ -227,13 +227,9 @@ class ClaudeAgentProvider(AgentProvider):
                 )
             dst = f"{skills_dir}/{name}"
             info(f"copying skill {name} into {bottle.name}:{dst}")
-            # Defense in depth: skill names are validated kebab-case at
+            bottle.exec(f"rm -rf {dst} && mkdir -p {dst}", user="root")
-            # 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_q}", user="root")
+            bottle.exec(f"chown -R node:node {dst}", user="root")
 
     def provision_prompt(self, plan: "BottlePlan", bottle: "Bottle") -> str | None:
         """Copy the prompt file into the guest, fix ownership/mode.

bot_bottle/contrib/codex/agent_provider.py

@@ -183,7 +183,7 @@ class CodexAgentProvider(AgentProvider):
         if not agent.skills:
             return
         skills_dir = _skills_dir(plan.guest_home)
-        bottle.exec(f"mkdir -p {shlex.quote(skills_dir)}", user="root")
+        bottle.exec(f"mkdir -p {skills_dir}", user="root")
         for name in agent.skills:
             src = host_skill_dir(name)
             if not os.path.isdir(src):
@@ -193,13 +193,9 @@ class CodexAgentProvider(AgentProvider):
                 )
             dst = f"{skills_dir}/{name}"
             info(f"copying skill {name} into {bottle.name}:{dst}")
-            # Defense in depth: skill names are validated kebab-case at
+            bottle.exec(f"rm -rf {dst} && mkdir -p {dst}", user="root")
-            # 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_q}", user="root")
+            bottle.exec(f"chown -R node:node {dst}", user="root")
 
     def provision_prompt(self, plan: "BottlePlan", bottle: "Bottle") -> str | None:
         """Copy the prompt file into the guest, fix ownership/mode.

bot_bottle/contrib/pi/agent_provider.py

@@ -238,7 +238,7 @@ class PiAgentProvider(AgentProvider):
         if not agent.skills:
             return
         skills_dir = _skills_dir(plan.guest_home)
-        bottle.exec(f"mkdir -p {shlex.quote(skills_dir)}", user="root")
+        bottle.exec(f"mkdir -p {skills_dir}", user="root")
         for name in agent.skills:
             src = host_skill_dir(name)
             if not os.path.isdir(src):
@@ -248,13 +248,9 @@ class PiAgentProvider(AgentProvider):
                 )
             dst = f"{skills_dir}/{name}"
             info(f"copying skill {name} into {bottle.name}:{dst}")
-            # Defense in depth: skill names are validated kebab-case at
+            bottle.exec(f"rm -rf {dst} && mkdir -p {dst}", user="root")
-            # 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_q}", user="root")
+            bottle.exec(f"chown -R node:node {dst}", user="root")
 
     def provision_prompt(self, plan: "BottlePlan", bottle: "Bottle") -> str | None:
         prompt_path = _prompt_path(plan.guest_home)

bot_bottle/manifest_agent.py

@@ -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, is_valid_entity_name
+from .manifest_schema import AGENT_MODEL_KEYS
 
 
 @dataclass(frozen=True)
@@ -161,16 +161,6 @@ 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)
 

bot_bottle/manifest_schema.py

@@ -33,20 +33,13 @@ 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 is_valid_entity_name(stem):
+    if not _FILENAME_RX.match(stem):
         return None
     return stem
 

docs/prds/prd-new-egress-control-plane.md

@@ -0,0 +1,247 @@
+# PRD prd-new: Egress control plane — metering, budgets, and forced cutoff
+
+- **Status:** Draft
+- **Author:** didericis
+- **Created:** 2026-06-25
+- **Issue:** #251
+
+## Summary
+
+Add an **out-of-band egress enforcement & observability plane**: meter every
+agent's token usage at the egress proxy, decrement budgets without the agent's
+cooperation, and forcibly cut a bottle's egress when a budget is exhausted —
+either automatically or on command from a host-level dashboard. The trigger
+(usage threshold) and the action (route-drop / freeze / kill) both live in the
+egress plane and run with no agent in the loop. This is distinct from the
+supervise sidecar (PRD 0013), which is agent-initiated and therefore cannot
+enforce a cost cutoff on a runaway agent. State (usage ledger, budgets, audit)
+moves into a host-level SQLite database behind a thin repository API, the first
+SQL store in an otherwise flat-file repo.
+
+## Problem
+
+bot-bottle can't currently do two things the cost-overrun case demands:
+
+1. **Forced egress shutdown on limit.** When an agent crosses a token
+   threshold, kill its egress automatically — no human in the loop.
+2. **Remote (host-level) management.** Drive agents from a single surface:
+   see usage, cut egress, stop bottles, to prevent cost overruns.
+
+The existing supervise sidecar (PRD 0013) is **entirely agent-initiated**: every
+action begins with the agent voluntarily calling an MCP tool and an operator
+approving it. A runaway or expensive agent — exactly the cost-overrun case —
+will never call `egress-block` on itself. Supervision is therefore a
+**collaborative recovery** mechanism, not an **enforcement** mechanism; making
+it mandatory (#249) would not deliver forced cost-cutoff.
+
+The requirement forces a distinction the current design blurs:
+
+- **Plane A — enforcement / observability (this PRD).** System → infrastructure.
+  Meter usage, cut egress on threshold or command, account for cost.
+  Out-of-band; independent of the agent. **Unconditional** — an enforcement
+  plane you can opt out of isn't enforcement.
+- **Plane B — agent-facing recovery (the existing supervise sidecar).**
+  Agent → operator, approval-gated. Useful interactively; meaningless for a
+  headless agent with no operator watching its queue. Remains optional.
+
+This PRD builds Plane A. It reframes the "always-on control" invariant of #249
+as "the egress control plane is always present" — a more defensible property
+than "every agent runs the agent-facing supervisor." Unsupervised
+(headless/CI/ephemeral) agents stay first-class: still subject to the mandatory
+meter + kill switch, they simply lack the agent-facing proposal tools they
+couldn't use anyway.
+
+## Goals / Success Criteria
+
+- The egress proxy meters every request to a metered API host (e.g.
+  `api.anthropic.com`) and records authoritative token usage per bottle and per
+  agent provider, with no agent cooperation.
+- A budget can be set at four scopes with deterministic precedence
+  (**agent → bottle → parent bottle → global host budget**); the
+  most-specific applicable budget governs.
+- When usage crosses a budget, the bottle's configured **cutoff policy**
+  (`cutoff` | `freeze` | `kill`) fires automatically, executed host-side on the
+  egress plane — never via the supervise queue.
+- An operator can, from a single **host-level TUI dashboard**, see live per-bottle
+  usage against budget and command a cutoff/stop on demand.
+- Host budgets, default cutoff policy, and per-provider limits are declared in a
+  new host-level `~/.bot-bottle/settings.yml`, parseable by `yaml_subset.py`.
+- All usage, budget state, and enforcement actions persist in a host-level
+  SQLite DB behind a thin repository API, so the store can later be swapped for
+  a cross-host cloud service.
+
+## Non-goals
+
+- **Remote control / cross-host control plane.** Web + mobile remote control,
+  cross-host budgets, and the authn/transport they require are explicitly
+  deferred. v1 is a **host-only TUI** with no remote surface.
+- **Dollar-denominated budgets.** Budgets are token counts keyed by agent
+  provider, not currency. Price tables are out of scope.
+- **Migrating existing flat-file state into SQLite.** Resume `metadata.json`,
+  transcripts, Dockerfile overrides, the supervise queue, and audit logs stay on
+  the filesystem. Only the *new* metering/budget/enforcement ledger is SQL.
+- **Making the supervise sidecar (Plane B) mandatory.** Out of scope here; this
+  PRD is the answer to "what should be unconditional" (Plane A), leaving #249's
+  Plane-B question open.
+- **Per-request hard pre-send blocking as the primary mechanism.** The gate is
+  budget-crossing detected at/after metering; a pre-flight estimator (below) is a
+  refinement, not the core enforcement path.
+
+## Design
+
+### Two measurements: gate vs. account
+
+There are two distinct needs, and they want different signals:
+
+- **Account (authoritative).** Decrement the real budget from the API
+  **response**, which already carries authoritative usage (Anthropic
+  `input_tokens` / `output_tokens`, OpenAI `usage`). The egress addon already
+  has a `response(flow)` hook (`bot_bottle/egress_addon.py:460`), so the real
+  number is available with no extra network call. **Caveat:** agent traffic is
+  mostly streaming SSE, so the response path must tail the stream for the final
+  usage event rather than parse a single JSON body — scoped explicitly as work.
+- **Gate (estimate).** To block *before* sending, only the request is available,
+  so an estimator / provider `count_tokens` endpoint is the only option.
+
+Calling `count_tokens` for accounting would be both less accurate *and* an extra
+metered egress call per request, so accounting uses response `usage` and the
+estimator is reserved for the optional pre-flight gate.
+
+### `count_tokens` on agent providers
+
+Add an abstract `count_tokens(request) -> int` to the `AgentProvider`
+abstraction (`bot_bottle/agent_provider.py`):
+
+- **Default** is a good-enough stdlib estimator. Prefer stdlib only; a small
+  pip dependency *for the sidecar* is acceptable for the fallback if stdlib
+  proves too inaccurate (this does not relax the package's stdlib-first stance —
+  it would be a sidecar-only dep, like the bundle already carries).
+- **Built-in `claude`** uses Anthropic's token-counting endpoint;
+  **built-in `codex`** uses OpenAI's. These are exact for the gate but cost a
+  metered call, so they are gate-only; accounting still comes from the response.
+
+### Budgets and precedence
+
+Budgets are token counts keyed by **agent provider name** (the same names
+bottles already use). Four scopes, most-specific wins:
+
+```
+agent  →  bottle  →  parent bottle  →  global (host)
+```
+
+The global host budget is the highest-priority feature to ship (the cross-host
+control plane will eventually consume it); per-agent and per-bottle budgets
+override it for finer control. A budget can also be supplied **at bottle
+launch** (`--budget` or equivalent), overriding the settings.yml defaults for
+that run. Enforcement evaluates the effective budget as the
+nearest-defined scope at decrement time.
+
+### `~/.bot-bottle/settings.yml`
+
+New **host-level** settings file (the `~/.bot-bottle/` root, *not* the per-repo
+`.bot-bottle/` — host budgets must not be committed per-repo). Parsed by
+`yaml_subset.py`, so it must stay within that bounded subset (flat mappings,
+scalars; no anchors, no multi-line block scalars). Shape:
+
+```yaml
+budget:
+  claude: 5000000      # token budget keyed by agent provider
+  codex: 2000000
+shutdown: cutoff       # default cutoff policy: cutoff | freeze | kill
+```
+
+### Forced cutoff and cutoff policy
+
+On budget exhaustion (or an operator command), the configured per-bottle cutoff
+policy fires. The three policies map onto primitives that already exist:
+
+- **`cutoff`** (default) — drop the bottle's `routes.yaml` to empty and reload
+  (or isolate the bottle from the egress network); the agent/bottle keeps
+  running but can no longer reach metered hosts. This is the route-drop already
+  available on the egress plane (`bot_bottle/backend/egress_apply.py`).
+- **`freeze`** — commit/snapshot state, then kill the agent/bottle; resumable
+  later via `bot_bottle/backend/freeze.py`.
+- **`kill`** — tear the bottle down without saving state (backend teardown).
+
+The trigger lives in the metering path and the action in the egress/backend
+plane; **neither touches the supervise proposal queue** (design constraint from
+#251).
+
+### Host-level SQLite store
+
+**Decision: introduce SQLite now, narrowly.**
+
+- **The dependency objection doesn't apply.** `sqlite3` is in the Python stdlib,
+  so it does not break the AGENTS.md stdlib-first / no-runtime-pip stance — same
+  category as the hand-rolled `yaml_subset.py`, except the stdlib already ships
+  the whole engine.
+- **It fits the problem.** A *global* token budget decremented concurrently by N
+  egress sidecars (today `~/.bot-bottle/` already has `state/`, `audit/`,
+  `queue/` written by parallel bottles) is a read-modify-write race. Over JSON
+  that means hand-rolled file locking; SQLite gives atomic transactions + WAL for
+  free. The per-agent/per-bottle precedence rollup plus "sum across all bottles"
+  is a `GROUP BY`, not an N-directory rescan.
+- **It rehearses the cloud swap.** "Wrap operations in an API so we can swap to a
+  cloud service" maps directly onto a thin repository/DAO over SQLite → Postgres
+  later. A JSON-file store is a worse rehearsal than SQL.
+
+**Costs (real but bounded):** a new paradigm in a flat-file repo needs a
+`schema_version` table + idempotent startup migrations; SQLite serializes
+writers, so WAL mode + `busy_timeout` are required (a non-issue at a handful of
+bottles); test fixtures need temp DBs.
+
+**Scope of the store:** one DB at `~/.bot-bottle/bot-bottle.db` behind a thin
+repository API. Only the **new** metering/budget/enforcement-audit ledger lives
+there. Existing per-bottle blobs (resume `metadata.json`, transcripts,
+Dockerfile overrides, supervise queue) stay on the filesystem — migrating them
+now is churn for no benefit and they lack the concurrency/aggregation problem.
+
+### Host-level controller + dashboard
+
+A single **host-level controller** owns the meter, budget evaluation, and the
+cutoff actions across all bottles (cf. `bot_bottle/cli/supervise.py`'s
+cross-bottle view), rather than a per-bottle daemon. v1 ships one host-level
+**TUI dashboard** that reads live usage-vs-budget from the SQLite store and
+offers on-demand cutoff/stop. The existing supervisor UI should eventually fold
+into this same dashboard; this PRD lays the host-level surface it will move to.
+
+## Implementation chunks
+
+Ordered, individually mergeable:
+
+1. **SQLite repository foundation.** `~/.bot-bottle/bot-bottle.db`, schema +
+   `schema_version` migrations, WAL + `busy_timeout`, thin repository API,
+   temp-DB test fixtures. No behavior wired yet.
+2. **Metering at the egress proxy.** Parse authoritative response `usage`
+   (including SSE final-usage tailing) in the egress addon `response` hook;
+   write per-bottle / per-provider usage rows to the ledger.
+3. **`settings.yml` + budget model.** Host-level `~/.bot-bottle/settings.yml`
+   parsed by `yaml_subset.py`; budget precedence (agent → bottle → parent →
+   global) and the `--budget` launch flag.
+4. **Forced cutoff + cutoff policy.** Wire the threshold trigger to the
+   `cutoff` / `freeze` / `kill` primitives on the egress/backend plane; record
+   enforcement actions to the audit ledger.
+5. **Host-level TUI dashboard.** Live usage-vs-budget view + on-demand
+   cutoff/stop, reading the store.
+6. **`count_tokens` pre-flight gate (optional refinement).** Abstract method +
+   stdlib estimator default; Anthropic/OpenAI endpoints for built-in
+   claude/codex; optional pre-send block.
+
+## Open questions
+
+- **SSE usage tailing robustness.** Buffering streamed responses to extract the
+  final usage event without breaking the agent's own stream consumption — how
+  much of the body must the addon hold, and what's the failure mode if the
+  stream is interrupted mid-flight?
+- **Crossing mid-request.** A single response can push usage past budget only
+  *after* it's already been delivered. Is post-hoc cutoff (next request blocked)
+  sufficient, or is a pre-flight estimator gate (chunk 6) required for v1?
+- **Provider name ↔ metered host mapping.** How does the proxy attribute a
+  flow to an agent-provider budget key — by destination host, by bottle
+  identity, or both?
+- **Parent-bottle budget semantics.** For `bottle extends` (PRD 0025 / 0065)
+  chains, does "parent bottle" mean the manifest parent, the launching bottle,
+  or the full ancestry summed?
+- **Dashboard ↔ controller transport (even host-only).** In-process, a local
+  socket, or polling the SQLite store directly? Picks the seam the future remote
+  control plane will extend.

docs/prds/prd-new-forge-native-integration.md

@@ -1,352 +0,0 @@
-# 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.

tests/unit/test_manifest_validation.py

@@ -165,22 +165,6 @@ 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())