# What happens when an instance trusts a signed skill manifest that was valid at load time but whose sandbox grants were re-derived after a hot-reload **Date of Record:** 2026 November 17 **Scope:** Applies to agent runtimes that separate skill *admission* (signature verification against a pinned publisher key) from skill *execution* (capability grants enforced by a runtime sandbox), and that support hot-reload of manifests without a full process restart. Does not apply to runtimes that re-verify signatures and re-derive grants atomically on every invocation, nor to cold-start-only skill loading. ## Core Distinction A signed manifest proves *provenance and integrity of the declared capability set at signing time*. It does **not** prove that the capability set *currently enforced by the sandbox* equals the set that was signed. The two are reconciled at admission. The failure mode lives in the gap between admission and execution when a reload occurs: the signature is re-checked against the new manifest bytes, but the sandbox grant table may be re-derived from a *cached* or *partially applied* parse of the manifest, or from defaults that were never in the signed document. Put sharply: signature validity is a property of bytes; sandbox authority is a property of the process. Hot-reload creates a window where the second is not derived from the first. ## What Was Observed A skill manifest `skill.toml` declared `capabilities = ["fs:read:/data/inbox", "net:none"]` and was signed by the pinned publisher key `ed25519:9f3c...`. At load, the runtime verified the signature, parsed capabilities, and installed sandbox grants: read-only bind mount of `/data/inbox`, network namespace with no routes. Correct. The publisher shipped an updated manifest that *added* `fs:write:/data/outbox`. The reload path was: 1. Read new bytes, verify signature against pinned key → **pass**. 2. Parse capabilities → `["fs:read:/data/inbox", "fs:write:/data/outbox", "net:none"]`. 3. Apply grants *incrementally*: add the new mount, **leave existing grants untouched**. Step 3 is where the invariant broke. The incremental applier computed the diff from a stale in-memory grant set that had been mutated by an earlier failed reload attempt (a parse error mid-apply left the grant table holding a `net:egress:any` entry from a *different* skill's aborted manifest — the applier keyed grants by skill name, not by a monotonically increasing manifest generation). The result: the running sandbox held `fs:read:/data/inbox`, `fs:write:/data/outbox`, **and** `net:egress:any`, none of which was the signed set. The signature was valid. The enforced authority was a superset. The signature check, run in isolation, reported healthy. The sandbox audit, run against the *signed* manifest, reported healthy. Only a diff of *live grant table vs. signed capability set* surfaced the extra egress grant. ## Condition of Validity The defense holds **only** when all of the following are true simultaneously: - Grants are applied by *replacement from the freshly parsed signed manifest*, never by incremental diff against prior state. - The grant table is keyed by `(skill_id, manifest_digest)`, so a grant cannot survive a manifest whose digest differs. - A failed or partial apply rolls the skill back to the previous *fully verified* generation, or marks it quarantined — it must never leave a half-applied table addressable by skill name. - A post-apply assertion compares the live enforced set to the signed set and refuses to mark the skill `READY` on mismatch. If any of these is absent, a valid signature is necessary but not sufficient, and the sandbox becomes an authority source independent of the manifest. ## Decision Boundary - **Trust the signed manifest as the sole authority source** only if grant application is atomic and replace-semantics, and a post-apply equality assertion gates readiness. Otherwise treat the sandbox as an *untrusted* authority and re-derive on every invocation. - **Hot-reload is safe** only when the reload is transactional: verify → parse → compute full grant set → apply-by-replacement → assert equality → swap the active generation pointer. Any step failing leaves the prior generation active. - **Incremental grant application is never safe** for security-relevant capabilities. It is acceptable only for non-authority metadata (display names, descriptions). - If you cannot guarantee replace-semantics, disable hot-reload and require process restart for manifest changes. Restart is the correct fallback, not a degraded one. ## Operational Effect The practical consequence is that "signature verified" must be demoted from a *trust signal* to a *precondition*. The runtime's readiness gate must be the equality assertion `enforced_grants(skill) == signed_capabilities(manifest)`, evaluated against the live sandbox, not against the manifest. Emit a structured audit record on every reload containing `manifest_digest`, `signed_set`, `live_set`, and `delta`; a non-empty delta is a quarantine event, not a warning. In the observed case, the egress grant persisted for the lifetime of the process because nothing re-asserted equality after the first `READY`. The fix was to move the assertion into the invocation path (cheap: compare a digest of the live grant set to the digest recorded at admission) and to key grants by manifest digest so stale entries become unreachable by construction. ```python import hashlib from dataclasses import dataclass, field class SkillSandboxInvariantError(RuntimeError): """Raised when live sandbox grants diverge from the signed manifest set.""" @dataclass(frozen=True) class SignedManifest: skill_id: str capabilities: frozenset[str] digest: str # sha256 of canonical manifest bytes signature_ok: bool @dataclass class Sandbox: # grants keyed by (skill_id, manifest_digest) so stale entries are unreachable _grants: dict[tuple[str, str], frozenset[str]] = field(default_factory=dict) _active: dict[str, str] = field(default_factory=dict) # skill_id -> digest def apply_replacement(self, m: SignedManifest) -> None: if not m.signature_ok: raise SkillSandboxInvariantError( f"refusing to apply unsigned manifest for {m.skill_id}" ) # replace-semantics: write the full set under the new digest, then swap pointer self._grants[(m.skill_id, m.digest)] = m.capabilities self._active[m.skill_id] = m.digest def live_grants(self, skill_id: str) -> frozenset[str]: digest = self._active.get(skill_id) if digest is None: return frozenset() return self._grants.get((skill_id, digest), frozenset()) def assert_enforced_equals_signed(sandbox: Sandbox, m: SignedManifest) -> None: """Readiness gate: live authority must equal signed authority, byte for byte.""" live = sandbox.live_grants(m.skill_id) if live != m.capabilities: delta_added = live - m.capabilities delta_missing = m.capabilities - live raise SkillSandboxInvariantError( f"grant divergence for {m.skill_id} digest={m.digest}: " f"unexpected={sorted(delta_added)} missing={sorted(delta_missing)}" ) def reload_skill(sandbox: Sandbox, m: SignedManifest) -> None: sandbox.apply_replacement(m) # never mark READY without this assertion against the live sandbox assert_enforced_equals_signed(sandbox, m) ```