feat(manifest): git-gate.signing opt-in (PRD chunk 2)

Implements the manifest surface for the signed-commits & audit-attribution
PRD (#423, PR #480): a bottle opts into per-activation commit signing with

    git-gate:
      signing:
        enabled: true

- New ManifestGitSigning value type (frozen, enabled: bool = False) parsed
  under git-gate.signing; unknown sub-keys and non-bool `enabled` die with
  targeted errors. parse_git_gate_config now returns (repos, user, signing).
- ManifestBottle gains git_signing; defaults to off, so bottles that omit
  the block are unchanged.
- Bottle-only: git-gate.signing on an agent is rejected by the existing
  agent-level non-`user` guard (like git-gate.repos).
- extends/runtime merges thread git_signing with an enable-wins overlay
  (a child enabling signing wins; omitting inherits the parent), mirroring
  the git_user non-empty-wins overlay.
- Facade exports ManifestGitSigning.

Tests: tests/unit/test_manifest_git_signing.py (parse, validation,
agent-level rejection, extends overlay). Full unit suite green.

This is the first stacked chunk; signing pipeline, gate signature check,
and control-plane verification + audit tables follow per the PRD.

Issue: #423

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

README.md

@@ -5,7 +5,7 @@
 # bot-bottle
 
 [![test](https://gitea.dideric.is/didericis/bot-bottle/actions/workflows/test.yml/badge.svg?branch=main)](https://gitea.dideric.is/didericis/bot-bottle/actions?workflow=test.yml)
-[![coverage](https://img.shields.io/badge/coverage-83%25-brightgreen)](https://coverage.readthedocs.io/)
+[![coverage](https://img.shields.io/badge/coverage-84%25-brightgreen)](https://coverage.readthedocs.io/)
 [![core coverage](https://img.shields.io/badge/core%20coverage-94%25-brightgreen)](https://gitea.dideric.is/didericis/bot-bottle/src/branch/main/docs/decisions/0004-coverage-policy.md)
 
 **Problem:** Developer wants to run a coding agent without supervision, but they don't want a prompt injected or misbehaving agent wrecking their environment or exfiltrating sensitive data.

bot_bottle/manifest/__init__.py

@@ -66,7 +66,12 @@ if TYPE_CHECKING:
     from .agent import ManifestAgent, ManifestAgentProvider
     from .bottle import ManifestBottle
     from .egress import EGRESS_AUTH_SCHEMES, ManifestEgressConfig, ManifestEgressRoute
-    from .git import ManifestGitEntry, ManifestGitUser, ManifestKeyConfig
+    from .git import (
+        ManifestGitEntry,
+        ManifestGitSigning,
+        ManifestGitUser,
+        ManifestKeyConfig,
+    )
 
 
 # Facade name -> submodule that defines it. The aggregate model (`Manifest`,
@@ -82,6 +87,7 @@ _LAZY_MODULES: dict[str, str] = {
     "ManifestEgressRoute": "egress",
     "ManifestEgressConfig": "egress",
     "ManifestGitEntry": "git",
+    "ManifestGitSigning": "git",
     "ManifestGitUser": "git",
     "ManifestKeyConfig": "git",
 }
@@ -107,6 +113,7 @@ __all__ = [
     "ManifestIndex",
     "ManifestError",
     "ManifestGitEntry",
+    "ManifestGitSigning",
     "ManifestGitUser",
     "ManifestKeyConfig",
     "ManifestAgentProvider",

bot_bottle/manifest/bottle.py

@@ -18,7 +18,12 @@ from typing import Mapping
 from .util import ManifestError, as_json_object
 from .agent import ManifestAgentProvider
 from .egress import ManifestEgressConfig
-from .git import ManifestGitEntry, ManifestGitUser, parse_git_gate_config
+from .git import (
+    ManifestGitEntry,
+    ManifestGitSigning,
+    ManifestGitUser,
+    parse_git_gate_config,
+)
 from .schema import BOTTLE_KEYS
 
 __all__ = ["ManifestBottle"]
@@ -38,6 +43,10 @@ class ManifestBottle:
     # `git config --global` step entirely. A bottle can declare a user
     # identity without any git-gate.repos upstreams, and vice versa.
     git_user: ManifestGitUser = field(default_factory=ManifestGitUser)
+    # Per-bottle commit signing (PRD prd-new: signed commits & audit
+    # attribution). Off by default; `git-gate.signing.enabled: true`
+    # opts a bottle into per-activation signing + audit. Bottle-only.
+    git_signing: ManifestGitSigning = field(default_factory=ManifestGitSigning)
     egress: ManifestEgressConfig = field(default_factory=ManifestEgressConfig)
     # Per-bottle stuck-recovery daemon (PRD 0013). When true (the
     # default, issue #249), the launch step brings up a supervise
@@ -109,9 +118,10 @@ class ManifestBottle:
 
         git: tuple[ManifestGitEntry, ...] = ()
         git_user = ManifestGitUser()
+        git_signing = ManifestGitSigning()
         git_raw = d.get("git-gate")
         if git_raw is not None:
-            git, git_user = parse_git_gate_config(name, git_raw)
+            git, git_user, git_signing = parse_git_gate_config(name, git_raw)
 
         agent_provider = (
             ManifestAgentProvider.from_dict(name, d["agent_provider"])
@@ -141,7 +151,8 @@ class ManifestBottle:
 
         return cls(
             env=env, agent_provider=agent_provider, git=git,
-            git_user=git_user, egress=egress, supervise=supervise_raw,
+            git_user=git_user, git_signing=git_signing, egress=egress,
+            supervise=supervise_raw,
             nested_containers=nested_raw,
             declared_fields=frozenset(d),
         )

bot_bottle/manifest/extends.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from .bottle import ManifestBottle
 from .egress import ManifestEgressConfig, validate_egress_routes
-from .git import ManifestGitUser, parse_git_gate_config
+from .git import ManifestGitSigning, ManifestGitUser, parse_git_gate_config
 from .util import ManifestError, as_json_object
 
 
@@ -19,6 +19,17 @@ def _overlay_declared_bool(
     return value
 
 
+def _overlay_signing(
+    base: ManifestBottle, override: ManifestBottle
+) -> ManifestGitSigning:
+    """Overlay `git-gate.signing`: an override that enables signing wins;
+    otherwise the base's value is inherited. Mirrors the non-empty-wins
+    overlay used for `git_user` — a child cannot un-set a parent's signing
+    by declaring `enabled: false` (that reads as the default), the same
+    way a child cannot blank a parent's git-gate.user field."""
+    return override.git_signing if override.git_signing.enabled else base.git_signing
+
+
 def merge_bottles_runtime(bottles: "list[ManifestBottle]") -> "ManifestBottle":
     """Merge an ordered list of pre-resolved ManifestBottle objects.
 
@@ -69,6 +80,7 @@ def _merge_two_bottles_runtime(base: "ManifestBottle", override: "ManifestBottle
         agent_provider=override.agent_provider,
         git=merged_git,
         git_user=merged_git_user,
+        git_signing=_overlay_signing(base, override),
         egress=merged_egress,
         supervise=_overlay_declared_bool(base, override, "supervise"),
         nested_containers=_overlay_declared_bool(
@@ -210,7 +222,7 @@ def _fold_two_bottles(
         for n in names
     }
     if merged_repos_raw:
-        merged_git, _ = parse_git_gate_config("_fold", {"repos": merged_repos_raw})
+        merged_git, _, _ = parse_git_gate_config("_fold", {"repos": merged_repos_raw})
     else:
         merged_git = ()
 
@@ -225,6 +237,7 @@ def _fold_two_bottles(
         agent_provider=later.agent_provider,
         git=merged_git,
         git_user=merged_git_user,
+        git_signing=_overlay_signing(earlier, later),
         egress=merged_egress,
         supervise=_overlay_declared_bool(earlier, later, "supervise"),
         nested_containers=_overlay_declared_bool(
@@ -299,6 +312,7 @@ def _merge_bottles(
         agent_provider=merged_agent_provider,
         git=merged_git,
         git_user=merged_git_user,
+        git_signing=_overlay_signing(parent, child),
         egress=merged_egress,
         supervise=merged_supervise,
         nested_containers=merged_nested_containers,

bot_bottle/manifest/git.py

@@ -283,16 +283,52 @@ class ManifestGitUser:
         return not self.name and not self.email
 
 
+@dataclass(frozen=True)
+class ManifestGitSigning:
+    """Per-bottle commit-signing switch (PRD prd-new: signed commits &
+    audit attribution).
+
+    When `enabled`, the launcher mints a per-activation Ed25519 signing
+    key host-side, holds the private half in the sidecar ssh-agent, and
+    configures the bottle to sign every commit at commit time; the gate
+    rejects any commit it forwards that is not signed by the activation
+    key, and the control plane records an audit binding.
+
+    Bottle-only: it carries data-plane / audit policy, not an
+    agent-overlayable identity, so — like `git-gate.repos` — it is
+    rejected at the agent level. Defaults to off: bottles that omit
+    `git-gate.signing` behave exactly as before."""
+
+    enabled: bool = False
+
+    @classmethod
+    def from_dict(cls, bottle_name: str, raw: object) -> "ManifestGitSigning":
+        d = as_json_object(raw, f"bottle '{bottle_name}' git-gate.signing")
+        for k in d:
+            if k != "enabled":
+                raise ManifestError(
+                    f"bottle '{bottle_name}' git-gate.signing has unknown key "
+                    f"{k!r}; allowed: enabled"
+                )
+        enabled = d.get("enabled", False)
+        if not isinstance(enabled, bool):
+            raise ManifestError(
+                f"bottle '{bottle_name}' git-gate.signing.enabled must be a "
+                f"boolean (was {type(enabled).__name__})"
+            )
+        return cls(enabled=enabled)
+
+
 def parse_git_gate_config(
     bottle_name: str,
     raw: object,
-) -> tuple[tuple[ManifestGitEntry, ...], ManifestGitUser]:
+) -> tuple[tuple[ManifestGitEntry, ...], ManifestGitUser, ManifestGitSigning]:
     d = as_json_object(raw, f"bottle '{bottle_name}' git-gate")
     for k in d:
-        if k not in {"user", "repos"}:
+        if k not in {"user", "repos", "signing"}:
             raise ManifestError(
                 f"bottle '{bottle_name}' git-gate has unknown key {k!r}; "
-                f"allowed: user, repos"
+                f"allowed: user, repos, signing"
             )
 
     git_user = (
@@ -301,6 +337,12 @@ def parse_git_gate_config(
         else ManifestGitUser()
     )
 
+    git_signing = (
+        ManifestGitSigning.from_dict(bottle_name, d["signing"])
+        if "signing" in d
+        else ManifestGitSigning()
+    )
+
     git: tuple[ManifestGitEntry, ...] = ()
     repos_raw = d.get("repos")
     if repos_raw is not None:
@@ -311,4 +353,4 @@ def parse_git_gate_config(
         )
         validate_unique_git_names(bottle_name, git)
 
-    return git, git_user
+    return git, git_user, git_signing

bot_bottle/orchestrator/lifecycle.py

@@ -59,9 +59,8 @@ class Orchestrator(abc.ABC):
 
     # The shared control-plane auth provisioning contract (#476). Every backend
     # gets its signing key + gateway token through this one seam rather than
-    # re-deriving the wiring; the default topology is co-located + fail-closed,
-    # so a backend need not redeclare it (a truly isolated control plane would
-    # override this with a different `Topology`).
+    # re-deriving the wiring; it is fail-closed for every backend — the
+    # orchestrator never starts without its signing key.
     provisioning: ControlPlaneProvisioning = ControlPlaneProvisioning()
 
     def ensure_built(self) -> None:

bot_bottle/trust_domain.py

@@ -26,7 +26,7 @@ from __future__ import annotations
 
 import os
 from collections.abc import Mapping
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 
 from . import orchestrator_auth
 from .orchestrator_auth import ROLE_GATEWAY
@@ -39,8 +39,8 @@ from .paths import (
 
 
 class ProvisioningError(RuntimeError):
-    """A control-plane auth invariant would be violated (e.g. starting a
-    co-located control plane without its signing key — which would run OPEN)."""
+    """A control-plane auth invariant would be violated (e.g. starting the
+    orchestrator without its signing key — which would run OPEN)."""
 
 
 @dataclass(frozen=True)
@@ -99,31 +99,6 @@ CONTROL_PLANE = TrustDomain(
 )
 
 
-@dataclass(frozen=True)
-class Topology:
-    """Where a backend runs the two planes, so the provisioning seam can decide
-    whether an open control plane is dangerous — the backend declares this
-    instead of hardcoding the decision in its launcher.
-
-    `data_plane_shares_control_host` — the gateway runs on the same host/VM as
-    the orchestrator, so an open orchestrator would hand the co-located gateway
-    full `cli`. The default, and what makes the signing key mandatory. Every
-    current backend is co-located (docker/macOS: two containers on one host;
-    firecracker: two VMs on one host, agents L3-isolated); an isolated control
-    plane on a separate trusted host may declare False.
-
-    `combined_guest` — both planes in one guest (the retired combined infra VM).
-    Informational; kept so a future combined backend declares it."""
-
-    data_plane_shares_control_host: bool = True
-    combined_guest: bool = False
-
-
-# The default posture: data plane co-located with the control plane. Fail-closed
-# — the signing key is mandatory. A backend opts out only by declaring otherwise.
-COLOCATED = Topology(data_plane_shares_control_host=True)
-
-
 @dataclass(frozen=True)
 class ControlPlaneProvisioning:
     """The one seam every backend launcher uses to provision control-plane auth,
@@ -131,22 +106,22 @@ class ControlPlaneProvisioning:
     round: the orchestrator gets the raw key (`orchestrator_key`), the gateway
     gets a minted `gateway` token (`gateway_token`), the host CLI mints its own
     `cli` token from the same host-canonical key, and the orchestrator never
-    starts open where its gateway is co-located."""
+    starts open."""
 
     domain: TrustDomain = CONTROL_PLANE
-    topology: Topology = field(default=COLOCATED)
 
     def orchestrator_key(self) -> str:
         """The raw signing key the orchestrator process must receive (carry it in
-        `domain.key_env`). Fail-closed: raises rather than return "" for a
-        co-located topology, since an empty key runs the server open and hands
-        the co-located gateway full `cli`."""
+        `domain.key_env`). Fail-closed: raises rather than return "", since an
+        empty key runs the server open — and being on a separate host does not
+        stop the gateway from reaching the control plane (it must, for
+        `/resolve`), so an open orchestrator would treat that gateway as `cli`."""
         key = self.domain.signing_key()
-        if not key and self.topology.data_plane_shares_control_host:
+        if not key:
             raise ProvisioningError(
                 f"refusing to start the {self.domain.name} orchestrator without "
-                "a signing key: its gateway shares this host/VM, so an open "
-                "orchestrator would grant that gateway full `cli` (#476)"
+                "a signing key: an open orchestrator authenticates no one and "
+                "grants every caller that reaches it full `cli` (#476)"
             )
         return key
 
@@ -161,7 +136,5 @@ __all__ = [
     "ProvisioningError",
     "TrustDomain",
     "CONTROL_PLANE",
-    "Topology",
-    "COLOCATED",
     "ControlPlaneProvisioning",
 ]

docs/prds/prd-new-control-plane-auth-provisioning.md

@@ -45,7 +45,9 @@ key.
      pre-minted `gateway` token it can't rewrite into `cli`;
   3. the host CLI's `cli` token is minted from the same key, so it stays valid
      across co-running backends;
-  4. the control plane never runs open where its data plane shares the host/VM.
+  4. the orchestrator never runs open — the signing key is mandatory, with no
+     topology opt-out (a separate host does not stop a caller from reaching the
+     control-plane listener, so it cannot make open mode safe).
 
 ## Non-goals
 
@@ -72,9 +74,8 @@ signed by one service's key neither carries nor verifies another service's role.
 
 **`ControlPlaneProvisioning`** is the seam the backends call.
 `orchestrator_key()` returns the raw key for the control-plane process
-(fail-closed: it raises rather than hand back an empty key that would run the
-server open where the data plane is co-located). `gateway_token()` mints the
-gateway's token. Each backend applies these through its own transport —
+(fail-closed for every backend: it raises rather than hand back an empty key that
+would run the server open). `gateway_token()` mints the gateway's token. Each backend applies these through its own transport —
 docker/macOS inject env vars, firecracker pushes over SSH — but none re-derives
 *which* key or role.
 

docs/prds/prd-new-signed-commits-attribution.md

@@ -0,0 +1,463 @@
+# PRD prd-new: Per-bottle signed commits & audit attribution
+
+- **Status:** Draft
+- **Author:** didericis-claude
+- **Created:** 2026-07-25
+- **Issue:** #423
+
+## Summary
+
+Give each bottled agent a **per-activation signing key** so that every commit it
+produces is signed in the git-gate trust boundary (outside the bottle) and
+recorded in bot-bottle's own **host-owned audit store**, which is the portable
+source of truth. Each row cryptographically binds a commit's bytes (and their
+control-plane-recomputed SHA) to **access to that activation's signing key**, and
+binds the key to control-plane-owned activation metadata — bottle, host,
+manifest, agent, activation interval, retained public key — plus the commit's
+*claimed* author. The gate mints a short-lived Ed25519 key at spin-up, holds the
+private half in the sidecar `ssh-agent`, and forwards only `SSH_AUTH_SOCK` into
+the bottle. The gate rejects any commit it forwards that is not signed by the
+activation key; separately, the **control plane** independently recomputes each
+commit's object ID and verifies its signature before recording attribution — it
+never trusts a SHA, key, or verdict asserted by the gate.
+
+This PRD deliberately does **not** enforce or vouch author/committer identity.
+Author/committer name/email are recorded as claims carried inside the signed
+object; making the gate reject a mismatching author/committer is a possible
+future add (see **Non-goals** and **Deferred: identity enforcement**). Push
+capability stays exactly as PRD 0048 deploy keys; forge subuser accounts,
+provisioned API tokens, and forge-side status/"Verified" badges remain out of
+scope (a future "forge actors" PRD).
+
+Successor to:
+
+- **PRD 0027 (agent git identity, #94)** / **ADR 0002** — established that
+  `git-gate.user` name/email is *claimed, not vouched*. This PRD keeps that
+  posture: it adds signed **provenance** and a durable host record, not identity
+  enforcement.
+- **PRD 0048 (deploy-key provisioning, #169)** — the host-side mint-at-spin-up /
+  revoke-at-teardown lifecycle the signing key follows. Deploy keys are
+  unchanged.
+- **PRD 0070 (per-host orchestrator, #351)** — the orchestrator/control plane is
+  the sole owner of `bot-bottle.db`; audit verification and recording live
+  there, not in the data-plane gate (see **Trust boundary**).
+
+## The guarantee
+
+The crisp property this feature provides:
+
+> The **host-owned audit store** binds a set of commit bytes — whose Git object
+> ID the control plane **recomputes** itself — to **access to this activation's
+> signing key**, and binds that key to **control-plane-owned activation
+> metadata**: bottle, host, manifest, agent, activation interval, retained public
+> key. An agent may author and sign arbitrary commit contents, but it cannot make
+> that signature verify as a *different* activation, and it cannot choose the
+> activation metadata the control plane records. The commit's author/committer
+> identity is **recorded as a claim**, not enforced or vouched. The forge remains
+> only the repository transport/capability layer.
+
+What this does and does not prove (issue #423, comments #5554 / #5607 / #5608):
+
+- It proves **access to activation *Y*'s signing key**: whoever assembled these
+  commit bytes could sign with that key. Recomputing the object ID and verifying
+  the embedded signature binds the SHA to activation *Y*, and the control plane's
+  own records bind *Y*'s key to *Y*'s metadata.
+- It does **not** prove the commit was ever pushed, observed upstream, kept
+  (vs. later reverted or dropped), or produced by the *agent* rather than by any
+  other holder of the activation signing capability (the sidecar itself). The
+  store deliberately makes no claim about publication or sole-agent authorship
+  — the owner's requirement is attribution of *what manifest/agent/etc. was in
+  use when a commit was signed*, not proof of where the commit went (#5607).
+- It does **not** make author/committer identity cryptographically vouched. The
+  bottle chooses every byte sent through the forwarded agent, so a signature over
+  `author Mallory <mallory@example>` is just as valid. Those fields are a claim
+  carried inside the signed object and recorded as-is.
+- The binding is trustworthy because the **control plane** supplies the SHA (it
+  recomputes it), the public key, and the activation metadata from its own state
+  — never from a value the gateway asserts (see **Trust boundary**). The
+  residual, by design: anything that holds the activation signing capability can
+  produce commits that attribute to that activation. That is inherent to a
+  binding on *activation-key access*, not a defect.
+
+## Problem
+
+An agent runs on the developer's machine as a *subrole*, scoped down per role.
+Locally that is fine because the machine is single-tenant. The git history an
+agent produces, however, is a durable artifact that outlives the session and
+can be pushed to shared repositories, and today bot-bottle offers no
+tamper-evidence over it:
+
+- **No provenance.** Nothing ties a pushed commit to the bottle/activation that
+  actually produced it. `git-gate.user` name/email is forgeable and cosmetic
+  (ADR 0002); a commit could be produced anywhere.
+- **No durable, portable record.** There is no host-side ledger that says "SHA
+  *X* was produced by agent *A* in bottle *B* on host *H* during interval
+  *[t0,t1]*, signed by key *K*," independent of any forge and surviving key
+  rotation.
+
+## Goals / Success Criteria
+
+- **Per-activation signing key.** A fresh Ed25519 keypair is minted host-side at
+  each activation; the private half lives only in the sidecar `ssh-agent`, never
+  in the bottle. Only `SSH_AUTH_SOCK` crosses the boundary.
+- **Signed commits with no SHA divergence.** Commits produced in the bottle are
+  signed at commit time; the SHA the agent observes is the SHA that reaches the
+  upstream through the gate.
+- **Gate rejects unsigned commits.** Before the gate forwards a push, every
+  newly-introduced commit (those not already reachable from the advertised
+  upstream refs) must verify against the activation public key; a push with any
+  unsigned or wrong-key new commit is rejected, loudly, with the offending SHA.
+  This is a **signature** check only — no author/committer matching.
+- **Control-plane-owned attribution.** The orchestrator/control plane (sole
+  owner of `bot-bottle.db`, PRD 0070) recomputes each commit's object ID from the
+  bytes, verifies the embedded signature against the activation public key it
+  holds, and attaches activation metadata from its own state — accepting no SHA,
+  key, verdict, or metadata asserted by the gateway. No upstream fetch is
+  required.
+- **Host is the source of truth.** The audit record binds each recomputed SHA to
+  the bottle, host, manifest, agent, activation interval, and retained public
+  key, and records the commit's claimed author/committer.
+- **Verifiable after teardown.** The audit record retains the **full public
+  key, fingerprint, principal, and validity interval** — enough to regenerate an
+  allowed-signers file and run `git verify-commit` long after the activation
+  ends and the key is gone.
+- **Reprovision-per-activation, fail-loud teardown.** The signing key is minted
+  once per activation (persists across restarts within that activation) and
+  discarded at teardown; deploy-key revocation continues to follow PRD 0048's
+  fail-loud discipline.
+- **Push capability unchanged.** Forge access remains PRD 0048 deploy keys; no
+  new forge API dependency beyond 0048's existing deploy-key registration.
+
+## Non-goals
+
+- **Author/committer enforcement.** Explicitly out of scope for this PRD (issue
+  #423, comment #5590). The gate does not reject a commit for carrying a foreign
+  author or committer; those fields are recorded as claims. We rely on the
+  cross-forge audit store of signed commits and the authors recorded there. See
+  **Deferred: identity enforcement** for what a future add would look like.
+- **Cryptographically-vouched author identity.** Not claimed — see **The
+  guarantee**.
+- **Forge subuser accounts / provisioned API tokens / PAT minting.** Dropped.
+  Gitea's `POST /users/:name/tokens` requires Basic Auth *as the target user*
+  (an admin PAT cannot mint one for another user; the only server-side path is
+  the `gitea admin user generate-access-token` CLI), so a token-minting
+  bootstrap is a design in its own right (issue #423, comments #5518 / #5554).
+  This PRD needs no subrole API token, so that bootstrap problem does not arise.
+- **Forge-side attribution surfaces.** No commit-status badges, no forge
+  "Verified" badge. The latter is doubly unsuitable: it renders dynamically
+  against a *currently registered* key (so it would lie the moment a
+  reprovisioned key is revoked), and on Gitea registering a signing key also
+  grants push. Attribution lives in the host record and local `git
+  verify-commit`, not the forge.
+- **Non-Gitea forges, dashboard UI for orphan cleanup, mid-session rotation,
+  dirty-teardown reconciliation.** As before; a separate cleanup/sync pass
+  handles orphans left by a crash or discarded snapshot.
+
+## Scope narrowing
+
+This PRD started as "forge subroles" (forge subuser accounts + provisioned API
+tokens + optional forge status posting + signing). Review (issue #423, comments
+#5518 → #5590) narrowed it in two steps:
+
+1. **Dropped the forge-account and API-token machinery** (#5518 → #5556):
+   the PAT bootstrap is not implementable as sketched (Basic-Auth-as-target-user
+   constraint); the signature never vouched the author anyway; and making the
+   host audit store the portable source of truth is a cleaner boundary that
+   removes the forge-specific token lifecycle and commit-status dependence.
+2. **Dropped author/committer enforcement** (#5590): rely on the audit store of
+   signed commits and the authors recorded there; gate enforcement of the
+   identity fields is a possible future add, not part of this slice.
+
+What remains is the core that stands on its own: **signed commits + a
+host-owned, independently-verified audit record.** Forge *actors* (a per-bottle
+account that comments/opens PRs) and *identity enforcement* (the gate rejecting a
+foreign author/committer) are each candidate future PRDs.
+
+## Design
+
+### Trust boundary (control plane vs data plane)
+
+git-gate is the **data plane**: it parses hostile bytes from inside the bottle
+and forwards pushes. The orchestrator is the **control plane** and, per PRD
+0070, is the sole owner of `bot-bottle.db`. These are different trust boundaries,
+and the audit record must be anchored in the control plane:
+
+- The gate performs a **synchronous pre-forward signature check** (below) and
+  can reject a push before it reaches the upstream. This is a data-plane gate on
+  what leaves the bottle, not the audit binding.
+- The **control plane** takes the commit bytes to attribute (gateway-delivered
+  opaque bytes are fine), **recomputes the Git object ID**, **verifies the
+  embedded signature** against the activation public key it minted and holds, and
+  writes `attributed_commit` attaching metadata from its own state. It accepts
+  **no** gateway-supplied `verified` flag, claimed SHA, public key, or activation
+  identity.
+
+The precise trust statement (issue #423, review by didericis-codex on d8362ec,
+resolved in #5608): the row binds *these commit bytes / this recomputed SHA* to
+*access to this activation's signing key*, and the control plane binds that key
+to the recorded activation metadata. It does **not** assert forge observation or
+that only the agent (not the signing sidecar) authored the commit — so this PRD
+does **not** claim a compromised gateway cannot obtain an attribution row.
+Because the sidecar holds the activation signing capability, a compromised
+gateway *can* assemble and sign a commit and have it attributed to that
+activation; what it cannot do is make the signature verify as a *different*
+activation or choose the metadata the control plane records. That residual is
+acceptable under the intended guarantee (#5607) and is why the guarantee is
+worded as activation-key access, not agent-only authorship or upstream
+publication. The gate therefore cannot stand in for host-side verification: the
+control plane recomputes the object ID and verifies the signature itself rather
+than trusting the gate's word.
+
+### Identity model
+
+Per **bottled agent** (agent definition ∘ sealed bottle), realized per
+activation:
+
+| Part | Value | Source | Role |
+|------|-------|--------|------|
+| Signing key | one Ed25519 keypair | minted host-side per activation | signs every commit; private half sidecar-only; the anchor of provenance |
+| Author/committer | name + email | `git-gate.user` (PRD 0027 overlay) | written into commits and **recorded** as a claim; **not** enforced |
+
+### Manifest surface
+
+No new top-level keys and no `git-forge`/`forge-accounts` blocks. A single
+opt-in flag under the existing `git-gate` key turns on per-activation signing;
+`git-gate.user` (PRD 0027) supplies the author string as today.
+
+```yaml
+git-gate:
+  user:                          # PRD 0027 — author string; recorded, not enforced
+    name: didericis-claude
+    email: eric+claude@dideric.is
+  signing:
+    enabled: true                # NEW — opt-in per-activation signing + audit
+  repos:
+    bot-bottle:
+      url: ssh://git@100.78.141.42:30009/didericis/bot-bottle.git
+      provisioned_key:           # PRD 0048 — push capability, UNCHANGED
+        provider: gitea
+        token_env: GITEA_DEPLOY_TOKEN
+      host_key: "ssh-ed25519 AAAA..."
+```
+
+- `git-gate.signing.enabled: true` opts a bottle in. Without it, behavior is
+  exactly as today. There is **no `enforce` sub-key** — this PRD does not enforce
+  identity fields, so no knob is needed (and a knob that weakened a guarantee
+  was flagged as a contradiction in review).
+- `git-gate.signing` is **bottle-only** (home-only policy), rejected at the
+  agent level with a clear pointer. `git-gate.user` keeps its PRD 0027
+  agent-overlay semantics.
+
+### Signing: sign at commit time via a forwarded ssh-agent
+
+The reason SHAs never diverge:
+
+- The **sidecar** (the git-gate trust boundary) runs an `ssh-agent` holding the
+  short-lived signing private key.
+- **Only `SSH_AUTH_SOCK`** is forwarded into the bottle — a bounded signing
+  capability, not the key.
+- The provisioner writes the bottle `.gitconfig`:
+
+  ```ini
+  [commit]
+      gpgsign = true
+  [gpg]
+      format = ssh
+  [user]
+      name = didericis-claude
+      email = eric+claude@dideric.is
+      signingkey = ssh-ed25519 AAAA...   # activation signing PUBLIC key
+  ```
+
+- `git commit` asks the forwarded agent to sign; the signature is embedded at
+  object creation, so the agent-space SHA equals the pushed SHA. No transcoder,
+  no SHA translation table.
+
+### Gate pre-forward signature check (data plane)
+
+The gate already fetches from upstream before every `upload-pack` and mirrors
+bidirectionally (PRD 0008). When `git-gate.signing.enabled` is set, after
+gitleaks and before forwarding a push upstream:
+
+1. **Compute the newly-introduced set.** Commits reachable from the pushed ref
+   tips but **not** reachable from any ref already advertised by the upstream
+   (which the gate knows because it fetches upstream first) — equivalent to
+   `git rev-list <new-tips> --not <all-known-upstream-refs>`. This excludes
+   pulled/merged existing history; a merge commit the bottle creates is itself
+   new and is checked, its already-upstream ancestors are not.
+2. **Verify each new commit's signature** against the activation public key. A
+   commit that is unsigned or signed by any other key causes the push to be
+   **rejected** with the offending SHA.
+3. No author/committer matching is performed.
+
+This is a synchronous safety gate on what leaves the bottle; it is not the audit
+record.
+
+### Control-plane verification & recording
+
+For each commit to attribute (the gate hands the control plane the commit bytes;
+opaque gateway-delivered bytes are acceptable because nothing the gateway *says*
+about them is trusted), the orchestrator/control plane:
+
+1. **Recomputes the Git object ID** from the bytes itself. The stored `sha` is
+   this recomputed value, never a SHA the gateway claims.
+2. **Verifies the embedded signature** against the activation public key it
+   minted and holds for that activation (via a generated allowed-signers file) —
+   ignoring any `verified` flag, key, or activation identity supplied by the
+   gateway.
+3. Writes `attributed_commit` only for bytes that pass, stamping the activation
+   metadata (bottle/manifest/agent/host/interval) from its **own** state — not
+   from anything the gateway provides — and recording the commit's claimed
+   author/committer.
+
+No upstream fetch is required: the guarantee is a byte↔activation-key binding, so
+the object does not need to come from the forge (issue #423, #5608). Bytes that
+do not verify against the activation key are **not** recorded as attributed (they
+may be logged as an anomaly instead).
+
+### Audit trail
+
+The host SQLite store (PRD 0067, `~/.bot-bottle/bot-bottle.db`, owned by the
+control plane per PRD 0070) records the signing-key lifecycle and per-commit
+attribution. Retention is the **full public key, fingerprint, principal, and
+validity interval** — enough to regenerate an allowed-signers file and verify
+commits after teardown (issue #423, comment #5554, resolution 3). Never any
+private key material.
+
+```sql
+CREATE TABLE bottled_agent_activation (
+    bottled_agent_slug TEXT NOT NULL,
+    activation_id      TEXT NOT NULL,     -- one per activation cycle
+    host              TEXT NOT NULL,
+    manifest_digest   TEXT NOT NULL,      -- ties the record to the sealed manifest
+    agent             TEXT NOT NULL,
+    signing_pubkey    TEXT NOT NULL,      -- full ssh-ed25519 public key (for verify-commit)
+    signing_fpr       TEXT NOT NULL,      -- SHA256:... fingerprint (stable handle)
+    principal         TEXT NOT NULL,      -- allowed-signers principal, e.g. the author email
+    valid_from        TEXT NOT NULL,
+    valid_until       TEXT,               -- NULL while active; set at teardown
+    status            TEXT NOT NULL,      -- active | retired
+    PRIMARY KEY (bottled_agent_slug, activation_id)
+);
+
+CREATE TABLE attributed_commit (
+    sha                TEXT NOT NULL,      -- control-plane-RECOMPUTED object ID, not gateway-claimed
+    bottled_agent_slug TEXT NOT NULL,
+    activation_id      TEXT NOT NULL,
+    repo               TEXT NOT NULL,
+    author_name        TEXT NOT NULL,     -- CLAIMED, recorded as-is (not enforced)
+    author_email       TEXT NOT NULL,     -- CLAIMED
+    committer_name     TEXT NOT NULL,     -- CLAIMED
+    committer_email    TEXT NOT NULL,     -- CLAIMED
+    observed_at        TEXT NOT NULL,
+    PRIMARY KEY (sha, repo)
+);
+```
+
+Verification/allowed-signers generation is a stated part of the design: for a
+given SHA, join `attributed_commit → bottled_agent_activation`, emit
+`<principal> <signing_pubkey>` to a temporary allowed-signers file, and
+`git verify-commit` (or `ssh-keygen -Y verify`) against it. The
+`(pubkey, principal, valid_from/until)` tuple is exactly what that requires. The
+recorded author/committer columns are the *claim*; a consumer that wants to know
+"who says they wrote this" reads them, understanding they are unenforced.
+
+### Credential lifecycle
+
+Follows PRD 0048, minus the API-token kind (dropped):
+
+- **Activation:** mint a fresh Ed25519 signing keypair; load the private half
+  into the sidecar `ssh-agent`; write the public half into `.gitconfig` and the
+  `bottled_agent_activation` row (`active`, `valid_from` set). Deploy keys are
+  provisioned exactly as PRD 0048. Minting is **per activation** (a restart
+  re-attaches the same key; a new activation mints a new key and retires the old
+  row), so frozen snapshots don't accumulate live keys.
+- **Teardown (fail-loud):** revoke provisioned deploy keys via the forge API
+  (0048); discard the signing key from the sidecar agent and set the activation
+  row to `retired` with `valid_until`. The signing key was never on the forge,
+  so there is nothing to revoke there — only the local retire. Deploy-key
+  revocation failure halts teardown (0048); 404 = already-gone = success.
+- **Dirty teardown** is assumed handled; a separate cleanup/sync pass reconciles
+  orphaned deploy keys.
+
+## Deferred: identity enforcement
+
+If a future PRD wants the gate to *enforce* that new commits carry the manifest
+identity, the natural shape is: extend the gate pre-forward check to also require
+each new commit's author **and** committer name/email to equal `git-gate.user`,
+rejecting mismatches — with the same control-plane re-verification before
+recording. This is deliberately left out now (issue #423, comment #5590); it is
+noted so the door stays open and the current schema (which records the claimed
+author/committer) already carries what such a check would compare against. Note
+that even then the property would be gate-*enforced*, not signature-*vouched*; a
+validating signing broker in front of the key would be required for the latter.
+
+## Implementation chunks
+
+1. **This PRD.** Sets the (narrowed) design.
+2. **Manifest surface.** Add `git-gate.signing` (bottle-only; `enabled` only);
+   reject it at the agent level. Unit tests for parse/validation and the
+   agent-level rejection.
+3. **Signing pipeline.** Sidecar `ssh-agent` provisioning; forward
+   `SSH_AUTH_SOCK` into the bottle across docker, smolmachines, macOS-container,
+   and firecracker backends; emit the `commit.gpgsign` / `gpg.format=ssh` /
+   `user.signingkey` gitconfig. Integration test: a bottle commit is
+   `verify-commit`-valid and its SHA is unchanged through the gate; the private
+   key is absent from the bottle.
+4. **Gate pre-forward signature check.** Compute the newly-introduced set
+   (excluding upstream-reachable commits), verify each against the activation
+   key, reject unsigned/wrong-key with the offending SHA. Tests: unsigned
+   rejected; wrong-key rejected; pulled/merged upstream history passes; an
+   all-signed push succeeds. A foreign-author commit that is correctly signed
+   **passes the gate** (identity is not enforced here).
+5. **Control-plane verification + audit.** `bottled_agent_activation` /
+   `attributed_commit` tables (PRD 0067 store, control-plane-owned per PRD 0070);
+   the control plane recomputes each commit's object ID and verifies the
+   signature before writing a row; retain full pubkey + fingerprint + principal +
+   validity interval; record claimed author/committer; allowed-signers generation
+   + a post-teardown `verify-commit` helper. Tests: a gateway-claimed SHA/key/
+   verdict is ignored — the row's `sha` is the recomputed ID and bytes not signed
+   by the activation key produce **no** row.
+6. **Docs.** Glossary entry ("per-bottle signed commits"); README manifest
+   section; ADR note that signing-enabled bottles gain signed *provenance* and a
+   host-owned audit record while authorship stays *claimed* (ADR 0002 unchanged).
+
+## Testing strategy
+
+- **Unit (must):** `git-gate.signing` parse/validation; agent-level `signing`
+  rejection.
+- **Integration — signing (must):** end-to-end signed commit verifies with
+  `git verify-commit`; SHA observed in the bottle equals the SHA upstream; the
+  private key is absent from the bottle.
+- **Integration — gate check (must):** unsigned rejected; wrong-key rejected;
+  the upstream-reachable exclusion (pull + merge human history and push a signed
+  merge); a correctly-signed foreign-author commit **passes** (no identity
+  enforcement); a clean all-signed push succeeds.
+- **Control plane (must):** the control plane recomputes the object ID and
+  records a row for bytes genuinely signed by the activation key; a gateway-
+  supplied SHA/key/verdict is ignored (the stored `sha` is the recomputed value);
+  bytes signed by a foreign/invalid key produce **no** row.
+- **Lifecycle:** activation mints the key and writes an `active` row; teardown
+  retires it (`valid_until`) and revokes deploy keys fail-loud; a restart
+  re-attaches the same key (no new row); a fresh activation mints a new key and
+  retires the old.
+- **Post-teardown verification:** regenerate the allowed-signers file from a
+  `retired` row and confirm `verify-commit` still succeeds for an attributed SHA.
+
+## Resolved: control-plane transport
+
+Raised in review and **resolved** (issue #423, #5608): the commit object does not
+need to come from the forge, and reading the gateway-owned mirror is no stronger
+than accepting gateway-delivered bytes — both are fabricatable, and neither
+matters because the control plane trusts nothing the gateway *asserts*. The
+transport is therefore: the gate hands the control plane the raw commit bytes,
+the control plane **recomputes the object ID** and **verifies the signature**
+against the activation key, and stamps its own activation metadata. No upstream
+fetch. This is exactly what makes the byte↔activation-key binding sound
+regardless of transport.
+
+## Open questions
+
+- **Where the gate check slots into PRD 0008 ordering.** Modeled as a
+  pre-forward step after gitleaks; confirm it composes with the existing
+  access-hook / mirror ordering rather than needing a separate hook.

tests/unit/test_manifest_git_signing.py

@@ -0,0 +1,133 @@
+"""Unit: git-gate.signing manifest parsing + validation.
+
+PRD prd-new (signed commits & audit attribution): a bottle opts into
+per-activation commit signing with `git-gate.signing.enabled: true`.
+The block is bottle-only (rejected at the agent level, like
+git-gate.repos) and defaults to off.
+"""
+
+import unittest
+
+from bot_bottle.manifest import ManifestError, ManifestGitSigning, ManifestIndex
+
+
+def _bottle(git_gate: dict) -> dict:  # type: ignore
+    return {
+        "bottles": {"dev": {"git-gate": git_gate}},
+        "agents": {"demo": {"skills": [], "prompt": "", "bottle": "dev"}},
+    }
+
+
+class TestSigningParsing(unittest.TestCase):
+    def test_default_is_disabled(self):
+        """A bottle with no git-gate block signs nothing."""
+        m = ManifestIndex.from_json_obj({
+            "bottles": {"dev": {}},
+            "agents": {"demo": {"skills": [], "prompt": "", "bottle": "dev"}},
+        })
+        self.assertEqual(ManifestGitSigning(), m.bottles["dev"].git_signing)
+        self.assertFalse(m.bottles["dev"].git_signing.enabled)
+
+    def test_git_gate_without_signing_is_disabled(self):
+        """git-gate present (e.g. user only) but no signing → off."""
+        m = ManifestIndex.from_json_obj(_bottle({
+            "user": {"name": "claude", "email": "eric+claude@dideric.is"},
+        }))
+        self.assertFalse(m.bottles["dev"].git_signing.enabled)
+
+    def test_enabled_true(self):
+        m = ManifestIndex.from_json_obj(_bottle({"signing": {"enabled": True}}))
+        self.assertTrue(m.bottles["dev"].git_signing.enabled)
+
+    def test_enabled_false(self):
+        m = ManifestIndex.from_json_obj(_bottle({"signing": {"enabled": False}}))
+        self.assertFalse(m.bottles["dev"].git_signing.enabled)
+
+    def test_signing_coexists_with_user_and_repos(self):
+        m = ManifestIndex.from_json_obj(_bottle({
+            "user": {"name": "claude", "email": "eric+claude@dideric.is"},
+            "signing": {"enabled": True},
+            "repos": {
+                "bot-bottle": {
+                    "url": "ssh://git@gitea.dideric.is:30009/didericis/bot-bottle.git",
+                    "key": {"provider": "static", "path": "/dev/null"},
+                },
+            },
+        }))
+        b = m.bottles["dev"]
+        self.assertTrue(b.git_signing.enabled)
+        self.assertEqual("claude", b.git_user.name)
+        self.assertEqual(1, len(b.git))
+
+
+class TestSigningValidation(unittest.TestCase):
+    def test_unknown_key_under_signing_dies(self):
+        with self.assertRaises(ManifestError) as cm:
+            ManifestIndex.from_json_obj(_bottle({
+                "signing": {"enabled": True, "enforce": ["author"]},
+            }))
+        msg = str(cm.exception)
+        self.assertIn("git-gate.signing", msg)
+        self.assertIn("enforce", msg)
+
+    def test_non_bool_enabled_dies(self):
+        with self.assertRaises(ManifestError) as cm:
+            ManifestIndex.from_json_obj(_bottle({"signing": {"enabled": "yes"}}))
+        self.assertIn("git-gate.signing.enabled must be a boolean", str(cm.exception))
+
+    def test_signing_not_a_mapping_dies(self):
+        with self.assertRaises(ManifestError):
+            ManifestIndex.from_json_obj(_bottle({"signing": ["enabled"]}))
+
+    def test_unknown_git_gate_key_lists_signing(self):
+        """The git-gate allowed-key error names signing as valid."""
+        with self.assertRaises(ManifestError) as cm:
+            ManifestIndex.from_json_obj(_bottle({"bogus": {}}))
+        self.assertIn("allowed: user, repos, signing", str(cm.exception))
+
+
+class TestSigningIsBottleOnly(unittest.TestCase):
+    def test_agent_level_signing_rejected(self):
+        """git-gate.signing on an agent dies — it is bottle-only."""
+        with self.assertRaises(ManifestError) as cm:
+            ManifestIndex.from_json_obj({
+                "bottles": {"dev": {}},
+                "agents": {
+                    "demo": {
+                        "skills": [],
+                        "prompt": "",
+                        "bottle": "dev",
+                        "git-gate": {"signing": {"enabled": True}},
+                    },
+                },
+            })
+        msg = str(cm.exception)
+        self.assertIn("git-gate.signing", msg)
+        self.assertIn("not allowed at the agent level", msg)
+
+
+class TestSigningExtendsOverlay(unittest.TestCase):
+    def test_child_inherits_parent_signing(self):
+        """A child that omits signing inherits the parent's enabled flag."""
+        m = ManifestIndex.from_json_obj({
+            "bottles": {
+                "base": {"git-gate": {"signing": {"enabled": True}}},
+                "dev": {"extends": "base"},
+            },
+            "agents": {"demo": {"skills": [], "prompt": "", "bottle": "dev"}},
+        })
+        self.assertTrue(m.bottles["dev"].git_signing.enabled)
+
+    def test_child_enables_over_disabled_parent(self):
+        m = ManifestIndex.from_json_obj({
+            "bottles": {
+                "base": {},
+                "dev": {"extends": "base", "git-gate": {"signing": {"enabled": True}}},
+            },
+            "agents": {"demo": {"skills": [], "prompt": "", "bottle": "dev"}},
+        })
+        self.assertTrue(m.bottles["dev"].git_signing.enabled)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/unit/test_trust_domain.py

@@ -11,7 +11,6 @@ from bot_bottle.trust_domain import (
     CONTROL_PLANE,
     ControlPlaneProvisioning,
     ProvisioningError,
-    Topology,
     TrustDomain,
 )
 
@@ -78,23 +77,16 @@ class TestControlPlaneProvisioning(unittest.TestCase):
         with patch("bot_bottle.trust_domain.host_signing_key", return_value="key"):
             self.assertEqual("key", prov.orchestrator_key())
 
-    def test_orchestrator_key_fail_closes_when_colocated_and_empty(self) -> None:
-        # Invariant 4: a co-located backend must never start the control plane
-        # without a key (it would run OPEN and hand the co-located data plane
-        # full `cli`).
-        prov = ControlPlaneProvisioning()  # default topology: co-located
+    def test_orchestrator_key_fail_closes_when_empty(self) -> None:
+        # Invariant 4: the orchestrator must never start without a key — it would
+        # run OPEN and grant every caller that reaches it full `cli`. There is no
+        # topology opt-out: a separate host does not stop the gateway (or any
+        # other caller) from reaching the control-plane listener.
+        prov = ControlPlaneProvisioning()
         with patch("bot_bottle.trust_domain.host_signing_key", return_value=""):
             with self.assertRaises(ProvisioningError):
                 prov.orchestrator_key()
 
-    def test_orchestrator_key_allows_empty_when_isolated(self) -> None:
-        # A genuinely isolated control plane (no co-located data plane) may run
-        # without a key — the only topology where open mode is permissible.
-        prov = ControlPlaneProvisioning(
-            topology=Topology(data_plane_shares_control_host=False))
-        with patch("bot_bottle.trust_domain.host_signing_key", return_value=""):
-            self.assertEqual("", prov.orchestrator_key())
-
     def test_gateway_token_is_a_verifiable_gateway_role_token(self) -> None:
         prov = ControlPlaneProvisioning()
         with patch("bot_bottle.trust_domain.host_signing_key", return_value="k"):